.\" $Header: audio.5,v 72.4 94/09/08 13:44:18 ssa Exp $ .TA a .TH Audio 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME Audio \- audio tools available through HP VUE .SH DESCRIPTION This man-page describes the audio tools available through .C HP VUE for playing, recording, and editing sound. These include Audio Setup, Audio Security, Audio Editor, Audio Control Panel, Audio File and Data Formats, and Audio Library. .IR Audio (5) also provides information on using other audio tools from the HP-UX command line. .SS Audio Setup Requirements To use the audio tools, you need access to both audio client and server software. This software is part of HP-UX. The server requires a workstation or X station with Audio hardware. .PP Audio hardware is built into all Series 700 computers .I except the 720, 730, and 750; you can upgrade these models to become the 725, 735, or 755, which do have audio hardware. Note, older 705s (that is, 705s with the 8MB HP-UX) do not include audio software. .PP To use audio on an X station, you need either an HP ENVIZEX or ENTRIA X station that includes an audio accessory kit. .PP In most cases, you use the audio client and server software on one system. However, if you need the audio server running on a remote workstation or X station, see .IR aserver (1M). The audio data files can reside on either system or a third system. .SS "Audio Security" Audio is secured to allow access only to the user on the local workstation. If you need to allow remote systems to access audio on a workstation, see .IR asecure (1M). .SS The Audio Editor The Audio Editor is an OSF/Motif-based tool with play, record, and edit functions. The Editor displays a waveform that makes it easy to edit and play audio segments. .PP You can open an audio file, play it, look at its waveform, and use the waveform controls to edit the file. To set an output device, use the Audio Control Panel. .PP To record audio, first connect a microphone or other audio equipment that your system supports; perhaps a CD or tape player. To make the connections, see the Audio Editor online help ("Audio Editor Tasks" section) or your system owner's manual. .PP You can use the Editor to create and record an audio file. .RS .PP To start the Editor from the General Toolbox, open the Media Toolbox and drop an audio file on the Audio Editor control or double-click the control. .PP To start the Editor in a terminal window, type the following: .RS .CI /opt/audio/bin/audio_editor \0 .RI [ pathname ] .RE .RE .PP Online help is available through the .C Help menu in the upper-right hand corner of the Editor. .PP .SS The Audio Control Panel The Audio Control Panel is an OSF/Motif-based tool that you use to set the audio volume and choose the audio device for playback. .PP The volume control affects the play volume for any client system of this workstation or X station. The Audio Control Panel also includes a Stop button to stop the current play operation. .PP You can also use the Audio Control Panel to choose the device for playback, (headphones, built-in speaker, or device connected to Line Out, such as external speakers). This choice controls where audio is played when you double-click an audio file or use the Audio Editor to play a file. The default output device is the internal (built-in) speaker. .RS .PP To start the Audio Control Panel from HP VUE, click on the Audio control in HP VUE Front Panel. .PP To start the .CR "Audio Control Panel" in a terminal window, type the following: .RS .CR "/opt/audio/bin/AudioCP" .RE .RE .PP If your system has Audio applications that were developed using an earlier version of Audio software, those applications may use the .CR SPEAKER environment variable to determine their output devices. You can set the .CR SPEAKER variable for all applications started by HP VUE by modifying the .C $HOME/.vueprofile file. The .CR SPEAKER variable can be external (headphones, Line Out) or internal (built-in speaker). .RS .PP To set the .CR SPEAKER variable for a Bourne or Korn shell, enter: .RS .sp .C SPEAKER=internal .br .C export speaker .RE .PP To set the .CR SPEAKER variable for a C shell, enter: .RS .sp .C setenv SPEAKER internal .RE .RE .SS Audio File and Data Formats Audio files supported contain uncompressed audio data in one of three file formats: generic, RIFF/Waveform, or raw. Each file also needs the correct filename extension. For the three file formats, the Audio Editor online help lists which data formats and filename extensions that apply. .PP The extension causes the appropriate icon to appear in the File Manager. To play audio files you can drag and drop the file icons onto the Audio Editor or Control Panel or double-click the icon. .PP If you need to add an extension to a filename, (or convert the file format) the .C /opt/audio/bin/convert command is recommended. See .IR convert (1). However, you can instead rename the file to make it playable. Use this filename format: .RS .sp .I " filename.rate.data_type" .sp .RE .PP The .IR rate \0and \0data_type variables accept values defined for the .C "-drate" and .C "-ddata" options of .CR "convert". If needed, you can omit the .IR "rate" variable. Use this filename format: .RS .sp .I " filename.data_type" .RE .sp .SS \s-1Audio Library\s0 HP-UX includes an Audio Library that was used to build the audio tools. If you have ordered and installed the .SM User Environment Developer's Kit, you can use the Audio Library to create other audio applications. .PP The HP-UX Audio Library contains functions that C programs can use to manipulate audio. The functions interact with the Audio Server, enabling the application to record and play audio data files and convert audio data files from one format to another. .PP For more information about audio programming, refer to the manual .IR "Using the Audio Developer's Kit" . .SH AUTHOR The Audio Library, Audio Editor, and Audio Control Panel were developed by .SM HP. .SH SEE ALSO .na asecure(1m), aserver(1m), attributes(1), convert(1), send_sound(1). .PP .IR "Using the Audio Developer's Kit" .\" .\" toc@\f3Audio(5)\f1@@@audio tools available through HP VUE .\" .\" index@\f1Audio \- audio tools available through HP VUE@@@\f3Audio(5)\f1 .\" index@\f1Audio Setup@@@see \f2Audio(5)\f1 .\" index@\f1Setup, Audio@@@see \f2Audio(5)\f1 .\" index@\f1Audio Security@@@see \f2Audio(5)\f1 .\" index@\f1Security, Audio@@@see \f2Audio(5)\f1 .\" index@\f1Audio Editor,@@@see \f2Audio(5)\f1 .\" index@\f1Editor, Audio@@@see \f2Audio(5)\f1 .\" index@\f1Audio Control Panel@@@see \f2Audio(5)\f1 .\" index@\f1Control Panel, Audio@@@see \f2Audio(5)\f1 .\" index@\f1File and Data Formats, Audio@@@see \f2Audio(5)\f1 .\" index@\f1Audio File and Data Formats@@@see \f2Audio(5)\f1 .\" index@\f1Audio Library@@@see \f2Audio(5)\f1 .\" index@\f1Library, Audio@@@see \f2Audio(5)\f1 .\" .\" links@audio.5 Audio.5 .\" $Header: x_open.5,v 74.1 95/05/10 21:19:25 ssa Exp $ .TA x .TH x_open 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME x_open \- Pointer manual entry for X/Open Conformance Statement Questionnaire .SH DESCRIPTION This entry is a pointer entry for accessing the X/Open Conformance Statement Questionnaire for HP\|9000 Series 700/800 .SM HP-UX systems. To access the conformance statement, use the command: .IP .B man x_open_800 .SH FILES .TP /usr/share/man/man5.Z/x_open_800.5 Series 700/800 X/Open Conformance Statement Questionnaire (preformatted and compressed) .\" .\" index@\f4x_open(5)\f1 \- pointer manual entry for X/Open Conformance Statement Questionnaire@@@\f3x_open(5)\f1 .\" index@\f1X/Open Conformance Statement Questionnaire, pointer to manpage, x_open_800@@@\f3x_open(5)\f1 .\" index@\f1x_open_800, X/Open Conformance Statement Questionnaire@@@\f3x_open(5)\f1 .\" .\" toc@\f3x_open(5)\f1@@@pointer to manual entry for X/Open Conformance Statement Questionnaire .\" .\" links@x_open.5 X_Open.5 .\" $Header: x_open_800.5,v 76.1 95/07/24 16:11:24 ssa Exp $ .nf XXXX////OOOOppppeeeennnn CCCCoooonnnnffffoooorrrrmmmmaaaannnncccceeee SSSSttttaaaatttteeeemmmmeeeennnntttt QQQQuuuueeeessssttttiiiioooonnnnnnnnaaaaiiiirrrreeee TTTTyyyyppppeeee:::: XXXXPPPPGGGG4444 CCCCoooommmmppppoooonnnneeeennnntttt CCCCoooommmmppppoooonnnneeeennnntttt NNNNaaaammmmeeee:::: XXXXPPPPGGGG4444 CCCCoooommmmmmmmaaaannnnddddssss aaaannnndddd UUUUttttiiiilllliiiittttiiiieeeessss Completed by: Tom Shem, Hewlett-Packard Company _________________________________________ (name and organisation) on: Oct 13, 1994 _________________________________________ (date) _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 1. CCCCoooommmmmmmmaaaannnnddddssss aaaannnndddd UUUUttttiiiilllliiiittttiiiieeeessss PPPPrrrroooodddduuuucccctttt IIIIddddeeeennnnttttiiiiffffiiiiccccaaaattttiiiioooonnnn Product Identification HP-UX 9000 Operating System _________________________________________ Version/Release No. HP-UX 10.X for the Series 800 _________________________________________ If you do not supply this component yourself, please identify below the supplier you reference: IIIInnnnddddiiiiccccaaaattttoooorrrr ooooffff CCCCoooommmmpppplllliiiiaaaannnncccceeee None defined for this component. EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt SSSSppppeeeecccciiiiffffiiiiccccaaaattttiiiioooonnnn a. Testing Environment: o+ HP-UX 10.X Operating System o+ HP 9000 Series 800 b. Binary-compatible Family: HP 9000 Series 800 computers (all models). c. The environment contains an XPG4 branded Internationalised System Calls and Libraries component. TTTTeeeemmmmppppoooorrrraaaarrrryyyy WWWWaaaaiiiivvvveeeerrrrssss None. 2 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 2. CCCChhhhooooiiiicccceeee ooooffff CCCCoooonnnnffffoooorrrrmmmmaaaannnncccceeee SSSSppppeeeecccciiiiffffiiiiccccaaaattttiiiioooonnnn Question 1: Which specification are you using as a basis for listing any deviant behaviour of the product? Response: This Conformance Statement lists, in the chapter entitled CCCCoooommmmmmmmaaaannnnddddssss aaaannnndddd UUUUttttiiiilllliiiittttiiiieeeessss ---- PPPPOOOOSSSSIIIIXXXX CCCCoooommmmppppaaaattttiiiibbbbiiiilllliiiittttyyyy, all the discrepancies between the product behaviour and that specified in X/Open CAE Specification, Commands and Utilities, Issue 4 (C203) and X/Open CAE Specification, System Interface Definitions, Issue 4 (C204). Rationale: The XPG4 Commands and Utilities Component Definition requires that the discrepancies between product behaviour and either of the two specifications shown above be documented. Reference: Component Definitions, Version 1 (July 1992), Part 2 of X/Open Systems and Branded Products: XPG4, Section 3.2, XPG4 Commands and Utilities. X/Open Conformance Statement Questionnaire 3 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3. CCCCoooommmmmmmmaaaannnnddddssss aaaannnndddd UUUUttttiiiilllliiiittttiiiieeeessss ---- PPPPOOOOSSSSIIIIXXXX CCCCoooommmmppppaaaattttiiiibbbbiiiilllliiiittttyyyy 3.1 BBBBaaaassssiiiicccc UUUUttttiiiilllliiiittttiiiieeeessss 3.1.1 SSSSuuuuppppppppoooorrrrtttteeeedddd CCCCoooommmmmmmmaaaannnnddddssss Question 1: Which of the basic utilities (non-development utilities) defined in X/Open CAE Specification, Commands and Utilities, Issue 4, are not provided with the implementation? Response: All the basic utilities except _p_a_t_c_h and _t_a_l_k are provided. Rationale: This question determines whether or not the implementation provides a command of the name specified in X/Open CAE Specification, Commands and Utilities, Issue 4; it does not attempt to determine whether it supports the semantics of that command. The optional development utilities are excluded from this question and are dealt with in the next section of the questionnaire. Example: The _d_i_s command is not provided. Reference: Component Definitions, Version 1 (July 1992), Part 2 of X/Open Systems and Branded Products: XPG4, Section 3.2, XPG4 Commands and Utilities. 3.1.2 CCCCoooommmmmmmmaaaannnndddd BBBBeeeehhhhaaaavvvviiiioooouuuurrrr Question 2: In what ways do the commands provided by the implementation behave differently from the specifications contained in X/Open CAE Specification, Commands and Utilities, Issue 4? Response: 4 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s _______________________________________________________________________________ Command Behaviour Utility Option Remarks _______________________________________________________________________________ _a_d_m_i_n ----aaaa,,,, ----dddd,,,, ----eeee,,,, ----ffff,,,, Does not support blank-separated ----mmmm,,,, ----rrrr option arguments. Does not support -- as an operand. _______________________________________________________________________________ _a_r ----CCCC,,,, ----TTTT Option not supported. Does not support -- as an operand. _______________________________________________________________________________ _a_t ----tttt Option not supported. ----llll,,,, ----qqqq Option combination not supported. _______________________________________________________________________________ _c_d Does not support -- as an operand. _______________________________________________________________________________ _c_r_o_n_t_a_b ----eeee Option not supported. Does not support -- as an operand. _______________________________________________________________________________ _d_f ----PPPP Option not supported. Does not support -- as an operand. _______________________________________________________________________________ _d_u ----kkkk Option not supported. Does not report non-stat()able files or unreadable directories, nor is the exit status affected by these conditions. _______________________________________________________________________________ _e_x ----cccc,,,, ----ssss Option not supported. Does not support -- as an operand. _______________________________________________________________________________ _h_a_s_h ----rrrr Option not supported. Is not a built-in utility. _______________________________________________________________________________ _f_i_n_d Does not support -- as an operand. _______________________________________________________________________________ _m_a_i_l Does not support -- as an operand. _______________________________________________________________________________ _n_i_c_e ----nnnn Option not supported. _______________________________________________________________________________ _n_l ----bbbb,,,, ----dddd,,,, ----ffff,,,, ----hhhh,,,, Does not support blank-separated ----iiii,,,, ----llll,,,, ----nnnn,,,, ----ssss,,,, option arguments. ----vvvv,,,, ----wwww Does not support -- as an operand. _______________________________________________________________________________ _n_m ----AAAA,,,, ----gggg,,,, ----PPPP,,,, ----tttt Option not supported. Does not support -- as an operand. _______________________________________________________________________________ |8|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7| |8|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7| X/Open Conformance Statement Questionnaire 5 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s _______________________________________________________________________________ Command Behaviour, Continued Utility Option Remarks _______________________________________________________________________________ _n_o_h_u_p Does not support -- as an operand. _______________________________________________________________________________ _p_a_c_k Does not support -- as an operand. _______________________________________________________________________________ _p_a_t_c_h Command not supported. _______________________________________________________________________________ _p_a_x Option not supported. ----oooo _______________________________________________________________________________ _p_r ----cccc Option not supported. _______________________________________________________________________________ _p_s ----gggg,,,, ----pppp,,,, ----tttt,,,, ----uuuu Does not support blank-separated elements in list arguments. Option not supported. ----AAAA,,,, ----GGGG,,,, ----nnnn,,,, ----oooo,,,, ----UUUU _______________________________________________________________________________ _s_t_r_i_n_g_s Does not support -- as an operand. _______________________________________________________________________________ _t_a_l_k Command not supported. _______________________________________________________________________________ _t_i_m_e ----pppp Option not supported. Does not support -- as an operand. _______________________________________________________________________________ _t_s_o_r_t Does not support -- as an operand. _______________________________________________________________________________ _u_n_p_a_c_k Does not support -- as an operand. _______________________________________________________________________________ _v_i Does not support blank-separated option arguments. ----tttt,,,, ----wwww ----cccc Option not supported. Does not support -- as an operand. _______________________________________________________________________________ _w_h_o ----uuuu Forces -T option on. ----TTTT Session ID and remote hostname also shown. (On s700, cnode name instead of hostname). _______________________________________________________________________________ _x_a_r_g_s Option not supported. ----EEEE,,,, ----IIII,,,, ----LLLL Does not support -- as an operand. _______________________________________________________________________________ |8|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7| |8|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7| Rationale: 6 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s This question provides a greater degree of granularity than the previous question, requiring the semantic differences associated with the commands to be specified. Again, the question relates to the basic utilities rather than the development utilities. The question only relates to the semantics of the options specified within X/Open CAE Specification, Commands and Utilities, Issue 4; implementation-specific extensions should not be documented. Reference: Component Definitions, Version 1 (July 1992), Part 2 of X/Open Systems and Branded Products: XPG4, Section 3.2, XPG4 Commands and Utilities. 3.2 DDDDeeeevvvveeeellllooooppppmmmmeeeennnntttt UUUUttttiiiilllliiiittttiiiieeeessss 3.2.1 SSSSuuuuppppppppoooorrrrtttteeeedddd CCCCoooommmmmmmmaaaannnnddddssss Question 3: Which of the development utilities defined in XPG4 are not provided with the implementation? Response: All the development utilities except _d_i_s are provided. Rationale: The development utilities are required to exist on designated DEVELOPMENT systems but may not be present on all XSI-conformant systems. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Section 1.3.2, Development. 3.2.2 CCCCoooommmmmmmmaaaannnndddd BBBBeeeehhhhaaaavvvviiiioooouuuurrrr Question 4: In what ways do the commands provided by the implementation behave differently from the specifications contained in X/Open CAE Specification, Commands and Utilities, Issue 4? X/Open Conformance Statement Questionnaire 7 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s Response: _______________________________________________________________________________ Command Behaviour Utility Option Remarks _______________________________________________________________________________ _c_t_a_g_s Does not tag C typedefs by default. (-t option does this.) _______________________________________________________________________________ _d_i_s Command not supported. _______________________________________________________________________________ _m_4 Does not support blank-separated option arguments. ----DDDD,,,, ----UUUU Does not support -- as an operand. _______________________________________________________________________________ _m_a_k_e Does not support ....PPPPOOOOSSSSIIIIXXXX target. Does not support -- as an operand. _______________________________________________________________________________ _p_r_s Does not support blank-separated option arguments. ----cccc,,,, ----dddd,,,, ----rrrr Does not support -- as an operand. _______________________________________________________________________________ _r_m_d_e_l Does not support -- as an operand. _______________________________________________________________________________ _s_a_c_t Does not support -- as an operand. _______________________________________________________________________________ _s_t_r_i_p Does not support -- as an operand. _______________________________________________________________________________ _u_n_g_e_t Does not support -- as an operand. _______________________________________________________________________________ _v_a_l Does not support -- as an operand. _______________________________________________________________________________ _w_h_a_t Does not support -- as an operand. _______________________________________________________________________________ |7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7| |7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7| Rationale: This question provides a greater degree of granularity than the previous question, requiring the semantic differences associated with the commands to be specified. Again, the question relates to the basic utilities rather than the development utilities. The question only relates to the semantics of the options specified within X/Open CAE Specification, Commands and Utilities, Issue 4; implementation-specific extensions should not be documented. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Section 1.3.2, Development. 8 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.3 FFFFOOOORRRRTTTTRRRRAAAANNNN OOOOppppttttiiiioooonnnn 3.3.1 FFFFOOOORRRRTTTTRRRRAAAANNNN UUUUttttiiiilllliiiittttyyyy Question 5: Is the FORTRAN _f_o_r_t_7_7 utility provided? Response: Yes. Rationale: The _f_o_r_t_7_7 utility is the command level interface to the FORTRAN compiler, which need not be provided. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Section 1.3.3, FORTRAN. 3.3.2 CCCCoooommmmmmmmaaaannnndddd BBBBeeeehhhhaaaavvvviiiioooouuuurrrr Question 6: In what ways does the _f_o_r_t_7_7 utility provided by the implementation behave differently from the specification contained in X/Open CAE Specification, Commands and Utilities, Issue 4? _R_e_s_p_o_n_s_e: Option Remarks _____________________________ _-_O_n An optimization level cannot be specified using this option. Use the +_O_n option instead. See _f_o_r_t_7_7(1) in the _H_P-_U_X _R_e_f_e_r_e_n_c_e. _R_a_t_i_o_n_a_l_e_: X/Open Conformance Statement Questionnaire 9 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s This question provides a greater degree of granularity than the previous question, requiring the semantic differences associated with the command to be specified. Again, the question relates to the basic utilities rather than the development utilities. The question only relates to the semantics of the options specified within X/Open CAE Specification, Commands and Utilities, Issue 4; implementation-specific extensions should not be documented. _R_e_f_e_r_e_n_c_e_: X/Open CAE Specification, Commands and Utilities, Issue 4, Section 1.3.3, FORTRAN. _3_._4 PPPPoooossssssssiiiibbbbllllyyyy UUUUnnnnssssuuuuppppppppoooorrrrttttaaaabbbblllleeee UUUUttttiiiilllliiiittttiiiieeeessss aaaannnndddd OOOOppppttttiiiioooonnnnssss Question 7: Which of the following utilities and utility options are not supported on the implementation? _R_e_s_p_o_n_s_e: Utility Option Supported ____________________________ _a_r ----ssss Supported _c_a_n_c_e_l Supported _c_u Supported _l_p ----mmmm Supported _l_p ----oooo Supported _l_p ----tttt Supported _l_p ----wwww Supported _l_p_s_t_a_t Supported _s_o_r_t ----zzzz Supported _t_a_b_s ++++mmmm Supported _u_u_c_p Supported _u_u_l_o_g Supported _u_u_n_a_m_e Supported _u_u_p_i_c_k Supported _u_u_s_t_a_t Supported _u_u_t_o Supported _u_u_x Supported _R_a_t_i_o_n_a_l_e_: A number of utilities and utility options are marked as possibly unsupportable features, and the functionality associated with these need not be present in a conforming implementation. _R_e_f_e_r_e_n_c_e_: 10 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s X/Open CAE Specification, Commands and Utilities, Issue 4, Section 1.7, Portability. _3_._5 SSSSppppeeeecccciiiiffffiiiicccc CCCCoooommmmmmmmaaaannnnddddssss aaaannnndddd UUUUttttiiiilllliiiittttiiiieeeessss 3.5.1 aaaatttt Question 8: How does the _a_t command interpret a non-null _S_H_E_L_L environment variable? Response: Uses _s_h irrespective of the setting of _S_H_E_L_L. Rationale: The interpretation of the _S_H_E_L_L environment variable can cause _a_t to invoke different versions of the shell on some implementations. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _a_t, ENVIRONMENT VARIABLES, _S_H_E_L_L. 3.5.2 aaaawwwwkkkk Question 9: What is the limit on the number of open streams provided by _a_w_k? Response: 60 open streams. Rationale: The number of open streams that are available to _a_w_k may differ between implementations, possibly depending on the number of streams that are available to a process ({FOPEN_MAX}). Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _a_w_k, Input/Output and General Functions, close(). X/Open Conformance Statement Questionnaire 11 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.3 bbbbaaaattttcccchhhh Question 10: How does the _b_a_t_c_h command interpret a non-null _S_H_E_L_L environment variable? Response: Uses _s_h irrespective of the setting of _S_H_E_L_L. Rationale: The interpretation of the _S_H_E_L_L environment variable can cause _b_a_t_c_h to invoke different versions of the shell on some implementations. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _b_a_t_c_h, ENVIRONMENT VARIABLES, _S_H_E_L_L. 3.5.4 cccc88889999 Question 11: Which defined names are automatically provided by the compiler? Response: Series 700 Series 800 _______________________________________ __DATE__ __DATE__ __FILE__ __FILE__ __LINE__ __LINE__ __STDC__ __STDC__ __TIME__ __TIME__ __PA_RISC1_1 (opt) __PA_RISC1_1 (opt) __hp9000s700 __hp9000s800 __hp9000s800 __hppa __hppa __hpux __hpux __unix __unix Rationale: The automatic provision of defined names by the compiler can cause these names to be unavailable in the name space for defined names. 12 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _c_8_9, OPTIONS, -D. X/Open Conformance Statement Questionnaire 13 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s Question 12: When multiple input files are specified, where does _c_8_9 direct identification messages designating the start of each input file processing? Response: Standard output. Rationale: These messages, if produced, must be written to one or the other of standard output and standard error, but not to both. The destination of these messages is useful in determining redirections that are necessary to identify the input files from which warning messages are generated. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _c_8_9, STDOUT and STDERR. Question 13: What are the limits associated with external symbols imposed by _c_8_9? Response: Minimum Implementation Description Maximum Maximum _______________________________________________________________________________ Number of significant bytes 31 255 Number of source or object files 511 variable; see _c_8_9(1) in the _H_P-_U_X _R_e_f_e_r_e_n_c_e Total number of external symbols 4095 dependent upon available system resources Rationale: These limits vary between implementations and cannot be reset by the user. The XCU definition gives the minimum maximum value for each of the values. Some applications may require larger limits than these minimum maxima. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _c_8_9, EXTENDED DESCRIPTION, External Symbols. 14 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.5 ccccaaaannnncccceeeellll Question 14: Is the submitter of an _l_p job notified when the job is cancelled by someone else? Response: Yes. Rationale: It is useful for the submitter of a job to be notified of its cancellation, rather than having to interrogate the line printer queue to obtain this information. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _c_a_n_c_e_l, ENVIRONMENT VARIABLES, _L_A_N_G. 3.5.6 ccccpppp Question 15: What is the effect of alternate access control mechanisms on file copies? Response: If the target is a new file or directory, it inherits the Access Control List of the original file, altered to reflect any difference in ownership. See _a_c_l(5) in the _H_P-_U_X _R_e_f_e_r_e_n_c_e. Rationale: Because of the additional restrictions on creating files and reading data from files, the _c_p utility may not behave as described when alternate access control mechanisms are in use. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _c_p, DESCRIPTION, final paragraph. X/Open Conformance Statement Questionnaire 15 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.7 ddddaaaatttteeee Question 16: Does _d_a_t_e permit the setting of the date and time? Response: Yes. Rationale: Some systems, particularly those that are hosted as part of a total system environment, do not allow the _d_a_t_e command to set the date. On such systems, the setting of the date can only be accomplished from the host environment. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _d_a_t_e, OPERANDS, mmddhhmm[yy]. 3.5.8 eeeexxxx Question 17: What restrictions are imposed on the set of commands within the _r_h_s of the _m_a_p command? Response: 1. The maximum number of characters in the _r_h_s is limited to 240. 2. Tail recursion is not allowed. Rationale: Implementations may impose restrictions on the commands that can be used by macros in visual mode. Reference: X/Open CAE Specifications, Commands and Utilities, Issue 4, Chapter 3, Utilities, _e_x, EXTENDED DESCRIPTION, Command Descriptions in ex, Map. 16 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.9 ffffcccc Question 18: Is the history list mechanism disabled for users with appropriate privileges who do not set _H_I_S_T_F_I_L_E? Response: No. Rationale: XPG4 states that an implementation may, in certain circumstances, disable the history list mechanism for users with appropriate privileges who do not set _H_I_S_T_F_I_L_E. This could have some security implications. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _f_c, ENVIRONMENT VARIABLES, _H_I_S_T_F_I_L_E. 3.5.10 ffffoooorrrrtttt77777777 Question 19: When multiple input files are specified, where does _f_o_r_t_7_7 direct identification messages designating the start of each input file processing? Response: Standard error. Rationale: These messages, if produced, must be written to one or the other of standard output and standard error, but not to both. The destination of these messages is useful in determining redirections that are necessary to identify the input files from which warning messages are generated. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _f_o_r_t_7_7, STDERR. X/Open Conformance Statement Questionnaire 17 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s Question 20: What are the limits associated with external symbols imposed by _f_o_r_t_7_7? Response: Minimum Implementation Description Maximum Maximum _______________________________________________________________________________ Number of significant bytes 31 255 Number of source or object files 511 variable; see _f_o_r_t_7_7(1) in the _H_P-_U_X _R_e_f_e_r_e_n_c_e Total number of external symbols 4095 dependent upon available system resources Rationale: These limits vary between implementations and cannot be reset by the user. The XCU definition gives the minimum maximum value for each of the values. Some applications may require larger limits than these minimum maxima. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _f_o_r_t_7_7, EXTENDED DESCRIPTION, External Symbols. 3.5.11 lllleeeexxxx Question 21: Where are error messages sent when the _l_e_x ----tttt ooooppppttttiiiioooonnnn iiiissss nnnnooootttt ssssppppeeeecccciiiiffffiiiieeeedddd???? Response: Standard error. Rationale: These messages can be directed to either standard output or standard error according to XPG4, though the messages are not allowed to be directed to both. An application may wish to redirect these messages to a file. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _l_e_x, STDOUT. 18 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.12 llllnnnn Question 22: Can _l_n create links to a directory? Response: Yes. Rationale: Implementations may disallow the creation of hard links to a directory, even though the executing process has the appropriate privileges. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _l_n, OPERANDS, _s_o_u_r_c_e__f_i_l_e. 3.5.13 llllooooccccaaaalllleeeeddddeeeeffff Question 23: What is the default character mapping used when the _l_o_c_a_l_e_d_e_f ----ffff ooooppppttttiiiioooonnnn iiiissss nnnnooootttt ssssppppeeeecccciiiiffffiiiieeeedddd???? Response: ASCII. Rationale: XPG4 does not define a specific character mapping as the default for conforming systems. This character mapping provides encoding information for the members of the portable character set required by XPG4. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _l_o_c_a_l_e_d_e_f, OPTIONS, -f. X/Open Conformance Statement Questionnaire 19 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.14 llllpppp Question 24: What _l_p option or operator command is used to suppress the printing of a banner page? Response: ----oooo nnnnbbbb Rationale: The user may require that banner pages are suppressed in cases where pre-printed forms are used and the stationary is of a non-standard length. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _l_p, DESCRIPTION. 3.5.15 llllssss Question 25: How many bytes are in a block as reported by _l_s? Response: 512 bytes in a block. Rationale: The block size used by _l_s to report the number of blocks occupied by a file varies from system to system; often this depends on the underlying file system architecture. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _l_s, OPTIONS, -s. 20 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.16 mmmmaaaakkkkeeee Question 26: What additional variables does _m_a_k_e add to its environment? Response: None. Rationale: The implementation of _m_a_k_e may set certain environment variables on invocation of _m_a_k_e. These variables may not be set by the user, thus reducing the name space for environment variables. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _m_a_k_e, EXTENDED DESCRIPTION, Makefile Execution. Question 27: Does the default _M_A_K_E_F_L_A_G_S environment variable contain additional implementation-dependent options? Response: The default _M_A_K_E_F_L_A_G_S environment variable has the value ----bbbb. Rationale: The implementation of _m_a_k_e may set certain default _M_A_K_E_F_L_A_G_S options on invocation of _m_a_k_e. These variables are in addition to those set by the user on the command line and could affect the processing of _m_a_k_e. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _m_a_k_e, EXTENDED DESCRIPTION, Makefile Execution. X/Open Conformance Statement Questionnaire 21 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.17 nnnneeeewwwwggggrrrrpppp Question 28: Does _n_e_w_g_r_p allow users who are not listed as a member of a group which has no password to change to that group? Response: No. Rationale: On some implementations, a user who is not listed as a member of a group may change to that group in the case that there is no password associated with the group. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _n_e_w_g_r_p, DESCRIPTION. Question 29: Are there any other implementation-specific authorisation restrictions that affect _n_e_w_g_r_p? Response: No. Rationale: Some implementations may impose accounting or other restrictions that could cause _n_e_w_g_r_p to deny activity to a group member. For example, a resource quota system could be implemented on a group basis that would limit the ability to join a group until the resources were available to the group. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _n_e_w_g_r_p, DESCRIPTION. 22 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.18 nnnniiiicccceeee aaaannnndddd rrrreeeennnniiiicccceeee Question 30: What are the limits and default values used by _n_i_c_e and _r_e_n_i_c_e? Response: Maximum _n_i_c_e value is 19. Minimum _n_i_c_e value is 1. Default _n_i_c_e increment is 10. Rationale: Each of these values differs between implementations and the range of values gives the user some control over the relative priority of processes. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _n_i_c_e, DESCRIPTION. 3.5.19 ppppaaaaxxxx Question 31: What is the default archive format used by _p_a_x? Response: Extended _t_a_r. Rationale: The implementation has the choice as to which format it shall use as the default when it is creating files. When it is reading an archive created in either extended _t_a_r or extended _c_p_i_o format (or any other format that it understands), the _p_a_x utility will read the archive in the format as written. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _p_a_x, DESCRIPTION. X/Open Conformance Statement Questionnaire 23 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s Question 32: How does _p_a_x handle reading and writing of archives that span multiple files? Response: When end of archive medium is detected, _p_a_x prompts the user for the next volume of the archive, and allows the user to specify the location of the next volume. Rationale: In many cases _p_a_x will take actions, such as prompting the user for the device name to use for the next archive file, when the current archive file is full. There may be extensions to the syntax of _p_a_x which allow the user to specify the address to use to access subsequent files. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _p_a_x, DESCRIPTION. Question 33: How does _p_a_x handle invalid filenames when it is extracting files from an archive? Response: _p_a_x issues the error message: "Bad ASCII pathname". The file is not extracted. Rationale: An implementation may either extract the data associated with these files into files named in an implementation-defined manner or may issue an error indicating that the file is being ignored. If _p_a_x extracts the file, it is necessary for the user either to be informed of the file that is used or to know the algorithm that _p_a_x uses in generating these filenames. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _p_a_x, EXTENDED DESCRIPTION, The cpio Filename. 24 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.20 pppprrrriiiinnnnttttffff Question 34: Does _p_r_i_n_t_f support the e, E, f, g and G floating point conversion specifications? Response: Yes. Rationale: The support of these conversions is not required on an XCU conforming system. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _p_r_i_n_t_f, EXAMPLES. 3.5.21 sssshhhh Question 35: Is the environment variable _I_F_S ignored when the shell is invoked? Response: Yes. Rationale: The XCU definition allows that the _s_h command ignore the setting of the _I_F_S environment variable on invocation. The setting of this variable has been used to breach security on systems which use the shell to interpret a call to the _s_y_s_t_e_m() and _e_x_e_c_v_p() interfaces. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _s_h, ENVIRONMENT VARIABLES, _I_F_S. X/Open Conformance Statement Questionnaire 25 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.22 ttttoooouuuucccchhhh Question 36: What is the latest date after the Epoch that can be used by _t_o_u_c_h? Response: 01:00 18 January, 2038 UTC Rationale: Because of the limitations on the storage of times in the ssssttttaaaatttt structure associated with a file, there is a limitation on the valid dates that can be specified to _t_o_u_c_h. This is directly related to the value that can be stored in the integral type ttttiiiimmmmeeee____tttt. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _t_o_u_c_h, OPTIONS, -t. 3.5.23 yyyyaaaacccccccc Question 37: What are the limits of _y_a_c_c's internal tables? Response: Minimum Implementation Description Maximum Maximum _______________________________________________________________________________ Number of tokens 126 2000 Number of non-terminals 200 variable; see _y_a_c_c(1) in the _H_P-_U_X _R_e_f_e_r_e_n_c_e Number of rules 300 dependent upon available system resources Number of states 600 variable; see _y_a_c_c(1) in the _H_P-_U_X _R_e_f_e_r_e_n_c_e Length of rules 5200 dependent upon available system resources Number of actions 4000 variable; see _y_a_c_c(1) in the _H_P-_U_X _R_e_f_e_r_e_n_c_e Rationale: These internal table sizes vary between implementations and cannot be reset by the user. The XCU definition gives the minimum maximum value for each of the table values. Reference: 26 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _y_a_c_c, EXTENDED DESCRIPTION, Limits. XXXX////OOOOppppeeeennnn CCCCoooonnnnffffoooorrrrmmmmaaaannnncccceeee SSSSttttaaaatttteeeemmmmeeeennnntttt QQQQuuuueeeessssttttiiiioooonnnnnnnnaaaaiiiirrrreeee TTTTyyyyppppeeee:::: XXXXPPPPGGGG4444 PPPPrrrrooooffffiiiilllleeee PPPPrrrrooooffffiiiilllleeee NNNNaaaammmmeeee:::: XXXXPPPPGGGG4444 BBBBaaaasssseeee Completed by: Tom Shem, Hewlett-Packard Company _________________________________________ (name and organisation) on: Oct 6, 1994 _________________________________________ (date) _X_P_G_4 _B_a_s_e 4. XXXXPPPPGGGG4444 BBBBaaaasssseeee PPPPrrrroooodddduuuucccctttt IIIIddddeeeennnnttttiiiiffffiiiiccccaaaattttiiiioooonnnn Product Identification HP-UX Operating System _________________________________________ Version/Release No. HP-UX 10.X for the Series 800 _________________________________________ If you do not supply this product yourself, please identify below the supplier you reference: Product Identification HP-UX ANSI C Compiler _________________________________________ Version/Release No. Version A.10.00, HP-UX Release 10.0 _________________________________________ If you do not supply this product yourself, please identify below the supplier you reference: EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt SSSSppppeeeecccciiiiffffiiiiccccaaaattttiiiioooonnnn a. Binary-compatible Family: HP 9000 Series 800 (all models) b. Special instructions for configuring the Product(s) to meet the Conformance Requirements of this profile: None. 28 X/Open Conformance Statement Questionnaire _X_P_G_4 _B_a_s_e TTTTeeeemmmmppppoooorrrraaaarrrryyyy WWWWaaaaiiiivvvveeeerrrrssss Waiver Number Expiry Date ___________________________ 4.1 CCCCoooommmmppppoooonnnneeeennnnttttssss Completed CSQs for all the following XPG4 components are attached. 4.1.1 XXXXPPPPGGGG4444 IIIInnnntttteeeerrrrnnnnaaaattttiiiioooonnnnaaaalllliiiisssseeeedddd SSSSyyyysssstttteeeemmmm CCCCaaaallllllllssss aaaannnndddd LLLLiiiibbbbrrrraaaarrrriiiieeeessss 4.1.2 XXXXPPPPGGGG4444 CCCCoooommmmmmmmaaaannnnddddssss aaaannnndddd UUUUttttiiiilllliiiittttiiiieeeessss 4.1.3 XXXXPPPPGGGG4444 CCCC LLLLaaaannnngggguuuuaaaaggggeeee XXXX////OOOOppppeeeennnn CCCCoooonnnnffffoooorrrrmmmmaaaannnncccceeee SSSSttttaaaatttteeeemmmmeeeennnntttt QQQQuuuueeeessssttttiiiioooonnnnnnnnaaaaiiiirrrreeee TTTTyyyyppppeeee:::: XXXXPPPPGGGG4444 CCCCoooommmmppppoooonnnneeeennnntttt CCCCoooommmmppppoooonnnneeeennnntttt NNNNaaaammmmeeee:::: XXXXPPPPGGGG4444 IIIInnnntttteeeerrrrnnnnaaaattttiiiioooonnnnaaaalllliiiisssseeeedddd SSSSyyyysssstttteeeemmmm CCCCaaaallllllllssss aaaannnndddd LLLLiiiibbbbrrrraaaarrrriiiieeeessss _X_P_G_4 _B_a_s_e Completed by: Tom Shem, Hewlett-Packard Company _________________________________________ (name and organisation) on: Oct 6, 1994 _________________________________________ (date) 30 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s 5. IIIInnnntttteeeerrrrnnnnaaaattttiiiioooonnnnaaaalllliiiisssseeeedddd SSSSyyyysssstttteeeemmmm CCCCaaaallllllllssss aaaannnndddd LLLLiiiibbbbrrrraaaarrrriiiieeeessss PPPPrrrroooodddduuuucccctttt IIIIddddeeeennnnttttiiiiffffiiiiccccaaaattttiiiioooonnnn Product Identification HP-UX Operating System _________________________________________ Version/Release No. HP-UX 10.X for the Series 800 _________________________________________ If you do not supply this component yourself, please identify below the supplier you reference: IIIInnnnddddiiiiccccaaaattttoooorrrr ooooffff CCCCoooommmmpppplllliiiiaaaannnncccceeee Test report from VSX4. Test suite release number 4.3.2 Test report reference number EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt SSSSppppeeeecccciiiiffffiiiiccccaaaattttiiiioooonnnn a. Testing Environment: o+ HP 9000 Series 800. Standalone only. o+ Sufficient disk space for the tests to have at least 80Mb free on a single volume or partition. o+ Loopback cable: TX -RX RX -TX DCD-DTR DTR-DCD GND-GND o+ Mountable empty drive or partition. o+ All tests were run self-hosted on the machine being tested. X/Open Conformance Statement Questionnaire 31 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s o+ Compiler options used: ----AAAAaaaa ----DDDD____XXXXPPPPGGGG4444 ----llllMMMM o+ Due to security enhancements and a new file system, links must be created: llllnnnn ----ssss ////uuuussssrrrr////bbbbiiiinnnn////kkkksssshhhh ////bbbbiiiinnnn////kkkksssshhhh llllnnnn ----ssss ////uuuussssrrrr////bbbbiiiinnnn////sssshhhh ////bbbbiiiinnnn////sssshhhh llllnnnn ----ssss ////uuuussssrrrr////bbbbiiiinnnn////ccccsssshhhh ////bbbbiiiinnnn////ccccsssshhhh llllnnnn ----ssss ////uuuussssrrrr////bbbbiiiinnnn////rrrrmmmm ////bbbbiiiinnnn////rrrrmmmm llllnnnn ----ssss ////uuuussssrrrr////bbbbiiiinnnn////llllssss ////bbbbiiiinnnn////llllssss llllnnnn ----ssss ////uuuussssrrrr////ccccccccssss////bbbbiiiinnnn////mmmmaaaakkkkeeee ////bbbbiiiinnnn////mmmmaaaakkkkeeee llllnnnn ----ssss ////uuuussssrrrr////ccccccccssss////bbbbiiiinnnn////aaaarrrr ////bbbbiiiinnnn////aaaarrrr llllnnnn ----ssss ////oooopppptttt////aaaannnnssssiiiicccc////bbbbiiiinnnn////cccc88889999 ////bbbbiiiinnnn////cccccccc llllnnnn ----ssss ////oooopppptttt////aaaannnnssssiiiicccc////bbbbiiiinnnn////cccc88889999 ////bbbbiiiinnnn////cccc88889999 llllnnnn ----ssss ////oooopppptttt////aaaannnnssssiiiicccc////bbbbiiiinnnn////cccc88889999 ////uuuussssrrrr////ccccccccssss////bbbbiiiinnnn////cccc88889999 llllnnnn ----ssss ////uuuussssrrrr////ssssbbbbiiiinnnn////rrrreeeennnniiiicccceeee ////uuuussssrrrr////bbbbiiiinnnn////rrrreeeennnniiiicccceeee llllnnnn ----ssss ////uuuussssrrrr////ssssbbbbiiiinnnn////mmmmoooouuuunnnntttt ////eeeettttcccc////mmmmoooouuuunnnntttt llllnnnn ----ssss ////uuuussssrrrr////ssssbbbbiiiinnnn////uuuummmmoooouuuunnnntttt ////eeeettttcccc////uuuummmmoooouuuunnnntttt llllnnnn ----ssss ////vvvvaaaarrrr////ttttmmmmpppp ////uuuussssrrrr////ttttmmmmpppp llllnnnn ----ssss ////eeeettttcccc////ggggrrrroooouuuupppp ////eeeettttcccc////llllooooggggiiiinnnnggggrrrroooouuuupppp o+ If you wish to test the system with {_POSIX_CHOWN_RESTRICTED} enabled, enter (as superuser) the command: sssseeeettttpppprrrriiiivvvvggggrrrrpppp ----nnnn CCCCHHHHOOOOWWWWNNNN to disable it, use sssseeeettttpppprrrriiiivvvvggggrrrrpppp ----gggg CCCCHHHHOOOOWWWWNNNN The formal branding run was done with {_POSIX_CHOWN_RESTRICTED} enabled. If you wish to test the system with {_POSIX_NO_TRUNC} enabled, do not run the test suite on a file system set up for short file names. The formal branding run was done on a file system with long file names, so {_POSIX_NO_TRUNC} is enabled. b. Binary-compatible Family: HP 9000 Series 800 (all models) 32 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s TTTTeeeemmmmppppoooorrrraaaarrrryyyy WWWWaaaaiiiivvvveeeerrrrssss None. 5.1 GGGGeeeennnneeeerrrraaaallll AAAAttttttttrrrriiiibbbbuuuutttteeeessss 5.1.1 XXXXPPPPGGGG4444 FFFFeeeeaaaattttuuuurrrreeee GGGGrrrroooouuuuppppssss Question 1: Which of the following Feature Groups are supported by the implementation? Response: POSIX.2 C-language Binding YES Shared Memory YES Encryption YES Enhanced Internationalisation YES Note: All the interfaces in all these groups must exist on all XPG4 XSI-conformant systems, and each interface must either behave according to the description in System Interfaces and Headers, Issue 4, or indicate an error, with _e_r_r_n_o set to [ENOSYS]. Support for particular Feature Groups may be required in order to conform to particular X/Open Profiles. Support for a Feature Group can only be claimed if _a_l_l interfaces in that group behave according to the relevant descriptions in System Interfaces and Headers, Issue 4. Rationale: System Interfaces and Headers, Issue 4 states that the system may provide one or more of the Feature Groups listed. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Section 1.2, Conformance and Section 1.3, Feature Groups. X/Open Conformance Statement Questionnaire 33 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s 5.1.2 PPPPOOOOSSSSIIIIXXXX....1111 SSSSuuuuppppppppoooorrrrtttteeeedddd FFFFeeeeaaaattttuuuurrrreeeessss Question 2: Which of the following options, specified in the <<<>>> header file, are available on the system? Response: Macro Name Meaning Provided ______________________________________________________________ _POSIX_CHOWN_RESTRICTED Variable The use of _c_h_o_w_n() is restricted to a process with appropriate privileges, and to changing the group ID of a file only to the effective group ID of the process or one of its supplementary group IDs. _POSIX_NO_TRUNC Variable Pathname components longer than {NAME_MAX) generate an error. _POSIX_VDISABLE Yes Terminal special characters defined in <<<>>> can be disabled using this character value. _POSIX_SAVED_IDS Yes Each process has a saved set-user-ID and a saved set-group-ID. _POSIX_JOB_CONTROL Yes Implementation supports job control. The variable {{{{____PPPPOOOOSSSSIIIIXXXX____CCCCHHHHOOOOWWWWNNNN____RRRREEEESSSSTTTTRRRRIIIICCCCTTTTEEEEDDDD}}}} is enabled for each process for which its effective group ID or one of its supplementary group IDs has the CHOWN privilege. This is manipulated with the sssseeeettttpppprrrriiiivvvvggggrrrrpppp(1M) utility, as described in the Testing Environment section above. The variable {{{{____PPPPOOOOSSSSIIIIXXXX____NNNNOOOO____TTTTRRRRUUUUNNNNCCCC}}}} is enabled for each path that resides (or would reside) on a long file name file system, and disabled for other paths. All file systems shipped with the HP-UX product are long name file systems. Short name file systems can be created with the nnnneeeewwwwffffssss(1M) utility, and converted to long name file systems with the ccccoooonnnnvvvveeeerrrrttttffffssss(1M) utility. Rationale: 34 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s For an XSI-conformant implementation, all of these POSIX features must be provided. In some cases the feature need not be provided for all files or devices supported by the implementation. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 4, Headers, <<<>>>. X/Open Conformance Statement Questionnaire 35 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s 5.1.3 FFFFllllooooaaaatttt,,,, SSSSttttddddiiiioooo aaaannnndddd LLLLiiiimmmmiiiitttt VVVVaaaalllluuuueeeessss Question 3: What are the values associated with the following constants specified in the <<<>>> header file? Response: Macro Name Meaning Value __________________________________________________________________________ FLT_RADIX Radix of the exponent representation. 2 FLT_MANT_DIG 24 Number of base-FLT_RADIX digits in the float significand. DBL_MANT_DIG 53 Number of base-FLT_RADIX digits in the double significand. LDBL_MANT_DIG 113 Number of base-FLT_RADIX digits in the long double significand. FLT_DIG 6 Number of decimal digits, _q, such that any floating point number with _q digits can be rounded into a float representation and back again without change to the _q digits. DBL_DIG 15 Number of decimal digits, _q, such that any floating point number with _q digits can be rounded into a double representation and back again without change to the _q digits. LDBL_DIG 33 Number of decimal digits, _q, such that any floating point number with _q digits can be rounded into a long double representation and back again without change to the _q digits. FLT_MIN_EXP -125 Minimum negative integer such that FLT_RADIX raised to that power minus 1 is a normalised float. DBL_MIN_EXP -1021 Minimum negative integer such that FLT_RADIX raised to that power minus 1 is a normalised double. LDBL_MIN_EXP -16381 Minimum negative integer such that FLT_RADIX raised to that power minus 1 is a normalised long double. FLT_MIN_10_EXP -37 Minimum negative integer such that 10 raised to that power is in the range of normalised floats. DBL_MIN_10_EXP -307 Minimum negative integer such that 10 raised to that power is in the range of normalised doubles. LDBL_MIN_10_EXP -4931 Minimum negative integer such that 10 raised to that power is in the range of normalised long doubles. 36 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Macro Name Meaning Value __________________________________________________________________________ FLT_MAX_EXP 128 Maximum integer such that FLT_RADIX raised to that power minus 1 is a representable finite float. DBL_MAX_EXP 1024 Maximum integer such that FLT_RADIX raised to that power minus 1 is a representable finite double. LDBL_MAX_EXP 16384 Maximum integer such that FLT_RADIX raised to that power minus 1 is a representable finite long double. FLT_MAX_10_EXP 38 Maximum integer such that 10 raised to that power is in the range of representable finite floats. DBL_MAX_10_EXP 308 Maximum integer such that 10 raised to that power is in the range of representable finite doubles. LDBL_MAX_10_EXP 4932 Maximum integer such that 10 raised to that power is in the range of representable finite long doubles. FLT_MAX Maximum representable finite float. 3.40282347E+38 DBL_MAX Maximum representable finite double. 1.797 ... E+308 LDBL_MAX Maximum representable finite long double. 1.189 ... E4932 FLT_EPSILON 1.19209290E-07 Difference between 1.0 and the least value greater than 1.0 that is representable as a float. DBL_EPSILON 2.220 ... E-16 Difference between 1.0 and the least value greater than 1.0 that is representable as a double. LDBL_EPSILON 1.925 ... E-34 Difference between 1.0 and the least value greater than 1.0 that is representable as a long double. FLT_MIN Minimum normalised positive float. 1.17549435E-38 DBL_MIN Minimum normalised positive double. 2.225 ... E-308 LDBL_MIN Minimum normalised positive long double. 3.362 ... E-4932 Rationale: This set of constants provides useful information regarding the underlying architecture of the implementation. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 4, Headers, <<<>>>. X/Open Conformance Statement Questionnaire 37 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Question 4: What are the values associated with the following constants (optionally specified in the <<<>>> header file)? Response: Macro Name Meaning Minimum Maximum _______________________________________________________________ ARG_MAX 20478 Indeterminate Maximum length of argument to the _e_x_e_c functions including the environment data. CHILD_MAX 25 Indeterminate Maximum number of processes per user ID. LINK_MAX 32767 32767 Maximum number of links to a single file. MAX_CANON 512 512 Maximum number of bytes in a terminal canonical input line. NAME_MAX 14 255 Maximum number of bytes allowed in a terimnal input queue. OPEN_MAX 60 1024 Maximum number of open files that one process can have open at any one time. PATH_MAX 1023 1023 Maximum number of bytes in a pathname (including the terminating null). PIPE_BUF 8192 8192 Maximum number of bytes that is guaranteed to be atomic when writing to a pipe. STREAM_MAX 60 1024 Number of streams that one process can have open at one time. TZNAME_MAX 19 19 Maximum number of bytes supported for the name of a time zone. Rationale: Each of these limits can vary within bounds set by System Interfaces and Headers, Issue 4. The minimum value that a limit can take on any XSI conforming system is given in the corresponding _POSIX_ value. A specific conforming implementation may provide a higher minimum value than this and the maximum value that it provides can differ from the minimum. Some conforming implementations may provide a potentially infinite value as the maximum, in which case the value is considered to be indeterminate. The minimum value must always be definitive since the _POSIX_ value provides a known lower bound for the range of possible values. 38 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 4, Headers, <<<>>>. X/Open Conformance Statement Questionnaire 39 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Question 5: What are the values associated with the following constants specified in the <<<>>> header file? Response: Macro Name Meaning Minimum Maximum _______________________________________________________________ BC_BASE_MAX 99 99 Maximum _i_b_a_s_e and _o_b_a_s_e values allowed by the _b_c utility. BC_DIM_MAX 2048 2048 Maximum number of elements permitted in an array by the _b_c utility. BC_SCALE_MAX 99 99 Maximum scale value allowed by the _b_c utility. BC_STRING_MAX 1000 1000 Maximum length of a string constant accepted by the _b_c utility. COLL_WEIGHTS_MAX 4 4 Maximum number of weights that can be assigned to an entry of the LC_COLLATE order keyword in the locale definition file. EXPR_NEST_MAX 32 32 Maximum number of expressions that can be nested within parentheses by the expr utility. LINE_MAX 2048 2048 Maximum length in bytes including the trailing newline of a utility's input line when the utility is described as processing text files. NGROUPS_MAX 20 20 Maximum number of simultaneous supplementary group IDs per process. RE_DUP_MAX 255 255 Maximum number of repeated occurrences of a regular expression permited when using interval notation. Rationale: 40 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Each of these limits can vary within bounds set by System Interfaces and Headers, Issue 4. The minimum value that a limit can take on any XSI conforming system is given in the corresponding _POSIX_ or _POSIX2_ value. A specific conforming implementation may provide a higher minimum value than this and the maximum value that it provides can differ from the minimum. Some conforming implementations may provide a potentially infinite value as the maximum, in which case the value is considered to be indeterminate. The minimum value must always be definitive since the _POSIX_ or _POSIX2_ value provides a known lower bound for the range of possible values. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 4, Headers, <<<>>>. X/Open Conformance Statement Questionnaire 41 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Question 6: What are the values associated with the following numerical constants specified in the <<<>>> header file? Response: Macro Name Meaning Value _________________________________________________________________ CHAR_BIT Number of bits in a cccchhhhaaaarrrr. 8 CHAR_MAX Maximum value of a cccchhhhaaaarrrr. 127 INT_MAX Maximum value of an iiiinnnntttt. 2147483647 LONG_BIT Number of bits in a lllloooonnnngggg iiiinnnntttt. 32 LONG_MAX Maximum value of a lllloooonnnngggg iiiinnnntttt. 2147483647 MB_LEN_MAX 4 Maximum number of bytes in a character, for any supported locale. SCHAR_MAX Maximum value of a ssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr. 127 SHRT_MAX Maximum value of a sssshhhhoooorrrrtttt. 32767 SSIZE_MAX Maximum value of an object of type ssssssssiiiizzzzeeee____tttt. 2147483647 UCHAR_MAX Maximum value of an uuuunnnnssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr. 255 UINT_MAX Maximum value of an uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnntttt. 4294967295 ULONG_MAX Maximum value of an uuuunnnnssssiiiiggggnnnneeeedddd lllloooonnnngggg iiiinnnntttt. 4294967295 USHRT_MAX Maximum value of an uuuunnnnssssiiiiggggnnnneeeedddd sssshhhhoooorrrrtttt iiiinnnntttt. 65535 WORD_BIT Number of bits in a word or iiiinnnntttt. 32 Rationale: This set of constants provides useful information regarding the underlying architecture of the implementation. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 4, Headers, <<<>>>. Question 7: What are the values associated with the following numerical constants specified in the <<<>>> header file? Response: 42 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Macro Name Meaning Value _______________________________________________ FOPEN_MAX 60 Number of streams which the implementation guarantees can be open simultaneously. L_tmpnam 25 Maximum size of character array to hold _t_m_p_n_a_m() output. TMP_MAX 17576 Minimum number of unique filenames generated by _t_m_p_n_a_m(), which is the maximum number of times an application can call _t_m_p_n_a_m() reliably. Rationale: This set of constants provide useful information about the implementation. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 4, Headers, <<<>>>. X/Open Conformance Statement Questionnaire 43 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s 5.1.4 EEEErrrrrrrroooorrrr CCCCoooonnnnddddiiiittttiiiioooonnnnssss Question 8: Which of the following option errors listed in System Interfaces and Headers, Issue 4 are detected in the circumstances specified? Response: Function Error Detected ______________________________________________ _a_c_c_e_s_s() EINVAL Yes ETXTBSY Yes _a_c_o_s() EDOM Yes _a_s_i_n() EDOM Yes ERANGE Yes _a_t_a_n() EDOM Yes ERANGE Yes _a_t_a_n_2() EDOM Yes ERANGE Yes _c_a_t_c_l_o_s_e() EBADF Yes EINTR Yes _c_a_t_g_e_t_s() EBADF Yes EINTR Yes _c_a_t_o_p_e_n() EACCES Yes EMFILE Yes ENAMETOOLONG Yes ENFILE Yes ENOENT Yes ENOMEM Yes ENOTDIR Yes _c_e_i_l() EDOM Yes _c_f_s_e_t_i_s_p_e_e_d() EINVAL Yes _c_f_s_e_t_o_s_p_e_e_d() EINVAL Yes _c_h_m_o_d() EINVAL Yes _c_h_o_w_n() EINVAL Yes _c_l_o_s_e_d_i_r() EBADF Yes EINTR Yes _c_o_s() EDOM Yes ERANGE Yes _c_o_s_h() EDOM Yes _e_r_f() EDOM Yes ERANGE Yes _e_r_f_c() EDOM Yes 44 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Function Error Detected ______________________________________________ ERANGE Yes _e_x_e_c ENOMEM Yes ETXTBSY Yes _e_x_p() EDOM Yes ERANGE Yes _f_a_b_s() EDOM Yes ERANGE Yes _f_c_n_t_l() EDEADLK Yes _f_d_o_p_e_n() EBADF Yes EINVAL Yes EMFILE Yes ENOMEM Yes _f_g_e_t_c() ENOMEM Yes ENXIO Yes _f_g_e_t_w_c() ENOMEM Yes ENXIO Yes EILSEQ Yes _f_i_l_e_n_o() EBADF No _f_l_o_o_r() EDOM Yes _f_m_o_d() EDOM Yes ERANGE Yes _f_o_p_e_n() EINVAL Yes EMFILE Yes ENOMEM Yes ETXTBSY Yes _f_o_r_k() ENOMEM Yes _f_p_a_t_h_c_o_n_f() EBADF Yes EINVAL Yes _f_p_r_i_n_t_f() EINVAL No EILSEQ Yes _f_p_u_t_c() ENOMEM Yes ENXIO Yes _f_p_u_t_w_c() ENOMEM Yes ENXIO Yes EILSEQ Yes _f_r_e_o_p_e_n() EINVAL Yes ENOMEM Yes ETXTBSY Yes _f_r_e_x_p() EDOM Yes _f_s_e_e_k() EINVAL Yes X/Open Conformance Statement Questionnaire 45 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Function Error Detected ______________________________________________ EPIPE Yes _f_t_w() EINVAL Yes _g_e_t_c_w_d() EACCES Yes ENOMEM Yes _g_e_t_g_r_g_i_d() EIO Yes EINTR Yes EMFILE Yes ENFILE Yes _g_e_t_g_r_n_a_m() EIO Yes EINTR Yes EMFILE Yes ENFILE Yes _g_e_t_l_o_g_i_n() EMFILE Yes ENFILE Yes ENXIO Yes _g_e_t_p_a_s_s() EINTR Yes EIO Yes EMFILE Yes ENFILE Yes ENXIO Yes _g_e_t_p_w_n_a_m() EIO Yes EINTR Yes EMFILE Yes ENFILE Yes _g_e_t_p_w_u_i_d() EIO Yes EINTR Yes EMFILE Yes _h_s_e_a_r_c_h() ENOMEM Yes _h_y_p_o_t() EDOM Yes ERANGE Yes _i_c_o_n_v() EBADF Yes _i_c_o_n_v___c_l_o_s_e() EBADF Yes _i_c_o_n_v___o_p_e_n() EMFILE Yes ENFILE Yes ENOMEM Yes EINVAL Yes _i_s_a_t_t_y() EBADF Yes ENOTTY Yes _j_0() EDOM Yes ERANGE Yes _j_1() EDOM Yes ERANGE Yes 46 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Function Error Detected ______________________________________________ _j_n() EDOM Yes ERANGE Yes _l_d_e_x_p() EDOM Yes ERANGE Yes _l_g_a_m_m_a() EDOM Yes ERANGE Yes _l_i_n_k() EPERM Yes EXDEV Yes _l_o_g() EDOM Yes ERANGE Yes _l_o_g_1_0() EDOM Yes ERANGE Yes _m_b_l_e_n() EILSEQ Yes _m_b_s_t_o_w_c_s() EILSEQ Yes _m_b_t_o_w_c() EILSEQ Yes _m_o_d_f() EDOM Yes ERANGE Yes _o_p_e_n() EINVAL Yes ETXTBSY Yes _o_p_e_n_d_i_r() EMFILE Yes ENFILE Yes _p_a_t_h_c_o_n_f() EACCES Yes EINVAL Yes ENAMETOOLONG Yes ENOENT Yes ENOTDIR Yes _p_o_w() EDOM Yes ERANGE Yes _p_u_t_e_n_v() ENOMEM Yes _r_e_a_d() ENXIO Yes _r_e_a_d_d_i_r() EBADF Yes _r_e_n_a_m_e() ETXTBSY Yes _s_e_t_v_b_u_f() EBADF No _s_i_g_a_c_t_i_o_n() EINVAL Yes _s_i_g_a_d_d_s_e_t() EINVAL No _s_i_g_d_e_l_s_e_t() EINVAL No _s_i_g_i_s_m_e_m_b_e_r() EINVAL No _s_i_g_n_a_l() EINVAL Yes X/Open Conformance Statement Questionnaire 47 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Function Error Detected ______________________________________________ _s_i_n() EDOM Yes ERANGE Yes _s_i_n_h() EDOM Yes ERANGE Yes _s_q_r_t() EDOM Yes _s_t_r_c_o_l_l() EINVAL No _s_t_r_e_r_r_o_r() EINVAL No _s_t_r_x_f_r_m() EINVAL No _t_a_n() EDOM Yes ERANGE Yes _t_a_n_h() EDOM Yes ERANGE Yes _t_c_d_r_a_i_n() EIO Yes _t_c_f_l_u_s_h() EIO Yes _t_c_s_e_n_d_b_r_e_a_k() EIO Yes _t_c_s_e_t_a_t_t_r() EIO Yes _t_m_p_f_i_l_e() EMFILE Yes ENOMEM Yes _t_t_y_n_a_m_e() EBADF Yes ENOTTY Yes _u_n_g_e_t_w_c() EILSEQ Yes _u_n_l_i_n_k() ETXTBSY Yes _w_c_s_c_o_l_l() EINVAL No _w_c_s_t_o_m_b_s() EILSEQ Yes _w_c_s_x_f_r_m() EINVAL No _w_r_i_t_e() ENXIO Yes _y_0() EDOM Yes ERANGE Yes _y_1() EDOM Yes ERANGE Yes _y_n() EDOM Yes ERANGE Yes Rationale: 48 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Each of the above error conditions is marked as optional in System Interfaces and Headers, Issue 4 and an implementation may return this error in the cirumstances specified or may not provide the error indication. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Section 2.3, Error Numbers. X/Open Conformance Statement Questionnaire 49 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s 5.1.5 MMMMaaaatttthhhheeeemmmmaaaattttiiiiccccaaaallll IIIInnnntttteeeerrrrffffaaaacccceeeessss Question 9: What format of floating-point numbers is supported by this implementation? Response: IEEE floating point format. Rationale: Most implementations support IEEE floating point format either in hardware or software. Some implementations support other formats with different exponent and mantissa accuracy. These differences need to be defined. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Section 1.6, Relationship to Formal Standards. 5.1.6 DDDDaaaattttaaaa EEEEnnnnccccrrrryyyyppppttttiiiioooonnnn Question 10: Are the optional data encryption interfaces provided? Response: Function Provided ____________________ _c_r_y_p_t() Yes _e_n_c_r_y_p_t() No _s_e_t_k_e_y() No The U.S. Department of Defense does not allow "munitions" such as decryption routines to be exported from the U.S. Therefore, encryption functionality is available from _e_n_c_r_y_p_t() and _s_e_t_k_e_y(), but not decryption functionality. U.S. domestic customers may obtain fully capable copies of these routines through their customer support contract. 50 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Rationale: Normally, an implementation will either provide all three of these routines or will provide none of them at all. If the routines are not provided, then the implementation must provide a dummy interface which always raises an ENOSYS error condition. It is also possible that the implementation of the _e_n_c_r_y_p_t() function may be affected by export restrictions, in which case, the restrictions should be documented here. For example, historical implementations have supplied all three of these routines outside the U.S.A., but due to export restrictions on the decoding algorithm, a dummy version of _e_n_c_r_y_p_t() is provided that does encoding but no decoding. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Section 1.2, Conformance. 5.2 PPPPrrrroooocccceeeessssssss HHHHaaaannnnddddlllliiiinnnngggg 5.2.1 PPPPrrrroooocccceeeessssssss GGGGeeeennnneeeerrrraaaattttiiiioooonnnn Question 11: Which file types (regular, directory, FIFO, special, and so on) are considered to be executable? Response: Regular. Rationale: The [EACCES] error associated with _e_x_e_c functions occurs in circumstances when the implementation does not support execution of files of the type specified. A list of these file types needs to be provided. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 3, Functions, _e_x_e_c. X/Open Conformance Statement Questionnaire 51 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s 5.3 FFFFiiiilllleeee HHHHaaaannnnddddlllliiiinnnngggg 5.3.1 AAAAcccccccceeeessssssss CCCCoooonnnnttttrrrroooollll Question 12: What file access control mechanisms does the implementation provide? Response: The operating system supports extended Discretionary Access Control ("need to know" access restrictions and permissions) on files, as an optional superset of user, group, and other mode bits. This has the characteristics of an "additional file access control mechanism". For general information, see the _a_c_l(5) entry in the HP-UX Reference Manual. Rationale: System Interfaces and Headers, Issue 4 notes that implementations may provide _a_d_d_i_t_i_o_n_a_l or _a_l_t_e_r_n_a_t_e file access control mechanisms, or both. Reference: X/Open CAE Specification, System Interface Definitions, Issue 4, Chapter 2, Glossary, file access permissions. 5.3.2 FFFFiiiilllleeeessss aaaannnndddd DDDDiiiirrrreeeeccccttttoooorrrriiiieeeessss Question 13: Are any additional or alternate file access control mechanisms implemented that could cause _f_s_t_a_t() or _s_t_a_t() to fail? Response: No. Rationale: System Interfaces and Headers, Issue 4 notes that there could be an interaction between additional and alternate access controls and the success of _f_s_t_a_t() and _s_t_a_t(). This would suggest that an implementation can allow access to a file but not allow the process to gain information about the status of the file. 52 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 3, Functions, _f_s_t_a_t() and _s_t_a_t(). X/Open Conformance Statement Questionnaire 53 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s 5.3.3 FFFFoooorrrrmmmmaaaattttttttiiiinnnngggg IIIInnnntttteeeerrrrffffaaaacccceeeessss Question 14: Does the _p_r_i_n_t_f() function produce character string representations for Infinity and NaN to represent the respective values? Response: Yes. It generates the following strings for the indicated values: Value String ____________________ +Infinity ++.000000 -Infinity ---.000000 NaN ?.000000 Rationale: This behaviour is often provided on systems with mathematical functions that produce these results. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 3, Functions, _f_p_r_i_n_t_f(). 5.4 IIIInnnntttteeeerrrrnnnnaaaattttiiiioooonnnnaaaalllliiiisssseeeedddd SSSSyyyysssstttteeeemmmm IIIInnnntttteeeerrrrffffaaaacccceeeessss 5.4.1 CCCCooooddddeeeedddd CCCChhhhaaaarrrraaaacccctttteeeerrrr SSSSeeeettttssss Question 15: What coded character sets are supported by the implementation? Response: ISO 8859-1:1987 is supported, and others can be selected by users as their internal coded character set on a per-session basis. However, as not all of them contain the portable character set, HP does not claim "support" for these as XPG4 coded character sets. Rationale: System Interface Definitions, Issue 4 states that conforming implementations support one or more coded character sets, and that each of these includes the portable character set. Reference: 54 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s X/Open CAE Specification, System Interface Definitions, Issue 4, Chapter 4, Character Set. Question 16: What is the implementation's underlying internal codeset? Response: Per user-customer selectable option, each user may configure his/her login session to use a selected codeset. ISO 8859-1:1987 is one such codeset. Rationale: It is useful to be aware of the underlying codeset of the implementation. Reference: X/Open CAE Specification, System Interface Definitions, Issue 4, Chapter 4, Character Set. X/Open Conformance Statement Questionnaire 55 .fi .\" .\" links@x_open_800.5 X_Open_800.5 .\" $Header: acl.5,v 72.3 93/01/14 16:02:52 ssa Exp $ .TA a .TH acl 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acl \- introduction to access control lists .SH DESCRIPTION Access control lists are a key enforcement mechanism of discretionary access control (see Definitions below), for specifying access to files by users and groups more selectively than traditional .SM HP-UX mechanisms allow. .PP .SM HP-UX already enables non-privileged users or processes, such as file owners, to allow or deny other users access to files and other objects on a ``need to know'' basis, as determined by their user and/or group identity (see .IR passwd (4) and .IR group (4)). This level of control is accomplished by setting or manipulating a file's permission bits to grant or restrict access by owner, group, and others (see .IR chmod (2)). .PP .SM ACL\s0s offer a greater degree of selectivity than permission bits. .SM ACL\s0s allow the file owner or superuser to permit or deny access to a list of users, groups, or combinations thereof. .PP .SM ACL\s0s are supported as a superset of the .SM UNIX operating system discretionary access control .SM (DAC) mechanism for files, but not for other objects such as inter-process communication .SM (IPC) objects. .SS Definitions .PP Because control of access to data is a key concern of computer security, we provide the following definitions, based on those of the .I "Department of Defense Trusted Computer System Evaluation Criteria," to explain further both the concepts of access control and its relevance to .SM HP-UX security features: .TP 15 .I access ``A specific type of interaction between a subject and an object that results in the flow of information from one to the other.'' Subjects include ``persons, processes, or devices that cause information to flow among objects or change the system state.'' Objects include files (ordinary files, directories, special files, .SM FIFOs, etc.) and inter-process communication .SM (IPC) features (shared memory, message queues, semaphores, sockets). .TP .I access control list (ACL) An access control list is a set of (\f2user.group, mode\f1) entries associated with a file that specify permissions for all possible user\-\s-1ID\s+1/group\-\s-1ID\s+1 combinations. .TP 15 .I access control list (ACL) entry An entry in an .SM ACL that specifies access rights for one user and group .ID combination. .TP 15 .I "change permission" The right to alter .SM DAC information (permission bits or .SM ACL entries). Change permission is granted to object (file) owners and to privileged users. .TP 15 .I discretionary access control (DAC) ``A means of restricting access to objects based on the identity of subjects and/or groups to which they belong. The controls are discretionary in the sense that a subject with a certain access permission is capable of passing that permission (perhaps indirectly) to any other subject.'' .TP .I mode Three bits in each ACL entry which represent read, write, and execute/search permissions. These bits may exist in addition to the 16 mode bits associated with every file in the file system (see .IR glossary (9)). .TP 15 .I privilege The ability to ignore access restrictions and change restrictions imposed by security policy and implemented in an access control mechanism. In .SM HP-UX, superusers and members of certain groups (see .IR privgrp (4)) are the only privileged users. .TP .I restrictive versus permissive An individual ACL entry is considered restrictive or permissive, depending on context. Restrictive entries deny a user and/or group access that would otherwise be granted by less-specific base or optional ACL entries (see below). Permissive entries grant a user and/or group access that would otherwise be denied by less-specific base or optional ACL entries. .SS "Access Control List Entries" An access control list (ACL) consists of sets of (\f2user.group, mode\f1) entries associated with a file that specify permissions. Each entry specifies for one user\-\s-1ID\s+1/group\-\s-1ID\s+1 combination a set of access permissions, including read, write, and execute/search. .PP To help understand the relationship between access control lists and traditional file permissions, consider the following file and its permissions: .sp .RS -rwxr-xr-- james admin datafile .sp The file owner is user \f3james\f1. .br The file's group is \f3admin\f1. .br The name of the file is \f3datafile\f1. .br The file owner permissions are \f3rwx\f1. .br The file group permissions are \f3r-x\f1. .br The file other permissions are \f3r--\f1. .RE .PP In an ACL, user and group .SM IDs can be represented by names or numbers, found in .BR /etc/passwd . The following special symbols can also be used: .RS .TP 5 .B % Symbol representing no specific user or group. .PD 0 .TP 5 \@ Symbol representing the current file owner or group. .PD .RE .SS "Base ACL Entries" .PP When a file is created, three base access control list entries are mapped from the file's access permission bits to match a file's owner and group and its traditional permission bits. Base ACL entries can be changed by the .IR chmod (2) and .IR setacl (2) system calls. .nf .IP (\f2uid\f1.%,mode) \0Base ACL entry for the file's owner (%.\f2gid\f1,mode) \0Base ACL entry for the file's group (%.%,mode) \0Base entry for other users .fi .PP (Except where noted, examples are represented in short form notation. See ACL Notation, below.) .sp .SS "Optional ACL entries" .PP Optional access control list entries contain additional access control information, which the user can set with the .IR setacl (2) system call to further allow or deny file access. Up to thirteen additional user/group combinations can be specified. .PP For example, the following optional access control list entries can be associated with our file: .sp .TP 20 (mary.admin, rwx) Grant read, write, and execute access to user \f3mary\f1 in group \f3admin\f1. .TP (george.%, ---) Deny any access to user \f3george\f1 in no specific group. .fi .sp .SS "ACL Notation" .PP Supported library calls and commands that manage .SM ACL\s0s recognize three different symbolic representations: .TP 15 operator form For input of entire .SM ACL\s0s and modifications to existing .SM ACL\s0s, in a syntax similar to that used by .IR chmod (1). .TP 15 short form Easier to read, intended primarily for output. .IR Chacl (1) accepts this form as input so that it can interpret output from .IR lsacl (1). .TP 15 long form A multi-line format useful for greater clarity, and supported only for output. .PP For our example file, the base ACL entries could be represented in the three notations as follows: .RS .TP 15 operator form james.% = rwx, %.admin = rx, %.% = r .TP short form (james.%,rwx) (%.admin,r-x) (%.%,r--) .TP long form\f1 rwx james.% .br r-x %.admin .br r-- %.% .RE .PP In addition to basic .SM ACL usage, some library calls and commands understand and use a variation of operator and short forms. See the section below on .IR "ACL Patterns" . .SS "ACL Uniqueness" .PP Entries are unique in each .SM ACL. There can only be one (\f2u.g, mode\f1) entry for any pair of .I u and .I g values; one (\f2u.%, mode\f1) entry for a given value of .IR u ; one (\f2%.g, mode\f1) entry for a given value of .IR g ; and one (\f2%.%, mode\f1) entry for each file. For example, an .SM ACL can have a (23.14, \f2mode\f1) entry and a (23.%, \f2mode\f1) entry, but not two (23.14, \f2mode\f1) entries or two (23.%, \f2mode\f1) entries. .SS "Access Check Algorithm" .PP .SM ACL entries can be categorized by four levels of specificity. In access checking, .SM ACL\s0s are compared to the effective user and group IDs in this order: .nf .IP (\f2u.g\f1, rwx) specific user, specific group (\f2u\f1.%, rwx) specific user, no specific group (%.\f2g\f1, rwx) no specific user, specific group (%.%, rwx) no specific user, no specific group .fi .PP Once an entry for the combination of a process effective user .SM ID and effective group .SM ID (or any supplementary group \s-1ID\s+1) is matched, no further (that is, less specific) entries are checked. More specific entries that match take precedence over any less specific ones that also match. .PP If a process has more than one group .SM ID (that is, a non-null supplementary groups list), more than one (\f2u.g, mode\f1) or (%.\f2g, mode\f1) entry might apply for that process. If so, the access modes in all matching entries (of the same level of specificity, \f2u\f1.\f2g\f1 or %.\f2g\f1) are .SM OR'd together. Access is granted if the resulting mode bits allow it. Since entries are unique, the order of entries in each entry type is insignificant. .PP Because the traditional UNIX permission bits are mapped into base .SM ACL entries, they are included in access checks. .PP If a request is made for more than one type of access, such as opening a file for both reading and writing, access is granted only if the process is allowed all requested types of access. Note that access can be granted if the process has two groups in its groups list, one of which is only allowed read access, and the other of which is only allowed write access. In other words, even if the requested access is not granted by any one entry, it may be granted by a combination of entries due to the process belonging to several groups. .SS "Operator Form of ACLs (input only)" \f2user \f3. \f2group operator mode \f1[ \f2operator mode \f1]... \f3, \f1... .PP Multiple entries are separated by commas, as in .IR chmod (1). Each entry consists of a user identifier and group identifier followed by one or more operators and mode characters, as in the mode syntax accepted by .IR chmod (1). .PP The entire .SM ACL must be a single argument, and thus should be quoted to the shell if it contains whitespace or special characters. Whitespace is ignored except within names. A null .SM ACL is legitimate, and means either ``no access'' or ``no changes'', depending on context. .PP Each user or group .SM ID may be represented by: .TP 15 .I name Valid user or group name. .PD 0 .TP .I number Valid numeric .SM ID value. .TP .B % ``No specific user or group,'' as appropriate. .TP \@ ``Current file owner or group,'' as appropriate; useful for referring to a file's \f2u\f1.% and %.\f2g\f1 base ACL entries. .PD .PP An operator is always required in each entry. Operators are: .TP 5 .B = Set all bits in the entry to the given mode value. .PD 0 .TP 5 .B + Set the indicated mode bits in the entry. .TP 5 .B \- Clear the indicated mode bits in the entry. .PD .PP The mode is represented by an octal value of .B 0 through .BR 7 ; or any combination of .BR r , .BR w , and .B x can be given in any order (see .SM EXAMPLES below). A null mode denies access if the operator is .BR = , or represents ``no change'' if the operator is .B + or .BR \- . .PP Multiple entries and multiple operator-mode parts in an entry are applied in the order specified. Conflicts do not result in error; the last specified entry or operator takes effect. Entries need not appear in any particular order. .PP Note that .IR chmod (1) allows only .BR u , .BR g , .BR o , or .BR a to refer symbolically to the file owner, group, other, or all users, respectively. Since .SM ACL\s0s work with arbitrary user and group identifiers, \@ is provided as a convenience. .PP The exact syntax is: .nf .IP \f2acl\f1 ::= [\f2entry\f1[\f3,\f2entry\f1]...] \f2entry\f1 ::= \f2id\f3 . \f2id\f2 \f2op\f2 \f2mode\f1 [\f2op mode\f1]... \f2id\f1 ::= \f2name\f1 | \f2number\f1 | \f3%\f1 | \@\f1 \f2op\f1 ::= \f3=\f1 | \f3+\f1 | \f3\-\f1 \f2mode\f1 ::= \f30..7\f1 | [\f2char\f1[\f2char\f1]...] \f2char\f1 ::= \f3r\f1 | \f3w\f1 | \f3x\f1 .fi .SS "Short Form of ACLs (input and output)" \f3(\f2user \f3. \f2group\f3, \f2mode\f3) \f1... .PP Short form differs from operator form in several ways: .IP \- 5 Entries are surrounded by parentheses rather than being separated by commas. .IP \- 5 Each entry specifies the mode, including all mode bits. It is not possible to change the mode value with .B + and .B \- operators. However, the comma functions like the .B = operator in operator form. .IP \- 5 For clarity, hyphens represent unset permission bits in the output of the mode field and are allowed in input. This resembles the mode output style used by .IR ls (1). .PP Multiple entries are concatenated. For consistency with operator form, a dot .RB ( . ) is used to separate user and group .SM IDs. .PP On output, no whitespace is printed except in names (if any). .SM ID numbers are printed if no matching names are known. Either .SM ID can be printed as .B % for ``no specific user or group.'' The mode is represented as <\f3r\f1|\f3\-\f1><\f3w\f1|\f3\-\f1><\f3x\f1|\f3\-\f1>, that is, it always has three characters, padded with hyphens for unset mode bits. If the .SM ACL is read from the system, entries are ordered by specificity, then by numeric values of .SM ID parts. .PP On input, the entire .SM ACL must be a single argument, and thus should be quoted to the shell if it contains whitespace or special characters. Whitespace is ignored except within names. A null .SM ACL is legitimate, and means either ``no access'' or ``no changes'', depending on context. .PP User and group .SM IDs are represented as in operator form. .PP The mode is represented by an octal value of .B 0 through .BR 7 ; or any combination of .BR r , .BR w , .B x and .B \- (ignored) can be given in any order (see .SM EXAMPLES below). A null mode denies access. .PP Redundancy does not result in error; the last entry for any user-\s-1ID/\s+1group-\s-1ID\s+1 combination takes effect. Entries need not appear in any particular order. .PP The exact syntax is: .nf .IP \f2acl\f1 ::= [\f2entry\f1[\f2entry\f1]...] \f2entry\f1 ::= (\f2id\f3.\f2id\f3,\f1mode\f1) \f2id\f1 ::= \f2name \f1|\f2 number\f1 |\f3 % \f1| \@\f1 \f2mode\f1 ::= \f30..7\f1 | [\f2char\f1[\f2char\f1]...] \f2char\f1 ::= \f3r\f1 |\f3 w\f1 |\f3 x\f1 | \f3\- .fi .SS "Long Form of ACLs (output only)" \f2mode user \f3. \f2group\f1 .PP Each entry occupies a single line of output. The mode appears first in a fixed-width field, using hyphens (for unset mode bits) for easy vertical scanning. Each user and group .SM ID is shown as a name if known, a number if unknown, or .B % for ``no specific user or group.'' Entries are ordered from most to least specific, then by numeric values of .SM ID parts. .PP Note that every .SM ACL printed has at least three entries, the base ACL entries (that is, \f2uid\f1.%, %.\f2gid\f1, and %.%). .PP The exact syntax is: .nf .IP \f2acl\f1 ::= \f2entry\f1[<\f2newline\f1>\f2entry\f1]... \f2entry\f1 ::= \f2mode\f1<\f2space\f1>\f2id\f3.\f2id\f1 \f2mode\f1 ::= <\f3r\f1|\f3\-\f1><\f3w\f1|\f3\-\f1><\f3x\f1|\f3\-\f1> \f2id\f1 ::= \f2name\f1 | \f2number\f1 | \f3%\f1 .fi .SS "ACL Patterns" Some library calls and commands recognize and use .SM ACL patterns instead of exact .SM ACL\s0s to allow operations on all entries that match the patterns. .SM ACL syntax is extended in the following ways: .TP 15 wildcard user and group IDs A user or group name of .B \(** (wildcard) matches the user or group .SM ID in any entry, including .B % (no specific user or group). .TP 15 mode bits on, off, or ignored For operator-form input, the operators .BR = , .BR + , and .B \- are applied as follows: .RS .TP 5 .B = .PD 0 entry mode value matches this mode value exactly .TP .B + these bits turned on in entry mode value .TP .B \- these bits turned off in entry mode value .RE .PD .IP When only .B + and .B \- operators are used, commands ignore the values of unspecified mode bits. .IP Short-form patterns treat the mode identically to the .B = operator in operator form. .TP 15 wildcard mode values A mode of .B \(** (wildcard) in operator or short form input (for example, ``ajs.%=\(**'' or ``(ajs.%,\(**)'') matches any mode value, provided no other mode value is given in a operator-form entry. Also, the mode part of an entry can be omitted altogether for the same effect. .TP 15 entries not combined Entries with matching user and group .SM ID values are not combined. Each entry specified is applied separately by commands that accept patterns. .SS "ACL Operations Supported" .PP The system calls .IR setacl (2) and .IR getacl (2) allow setting or getting the entire .SM ACL for a file in the form of an array of .I acl_entry structures. To check access rights to a file, see .IR access (2) and .IR getaccess (2). .PP Various library calls are provided to manage .SM ACL\s0s: .TP 15 .IR acltostr (3C) Convert .I acl_entry arrays to printable strings. .TP 15 .IR strtoacl (3C) Parse and convert .SM ACL strings to .I acl_entry arrays. .TP 15 .IR strtoaclpatt (3C) Parse and convert .SM ACL pattern strings to .I acl_entry_patt arrays. .TP 15 .IR setaclentry (3C) .PD 0 .TP 15 .I fsetaclentry Add, modify, or delete a single .SM ACL entry in one file's .SM ACL. .PD .TP 15 .IR cpacl (3C) .PD 0 .TP 15 .I fcpacl Copy an .SM ACL and file miscellaneous mode bits (see .IR chmod (2)) from one file to another, transfer ownership if needed (see below), and handle remote files correctly. .PD .TP 15 .IR chownacl (3C) Change the file owner and/or group represented in an .SM ACL, that is, transfer ownership (see below). .PP The following commands are available to manage .SM ACL\s0s and permissions: .TP 15 .IR chacl (1) Add, modify, or delete individual entries or all optional entries in .SM ACL\s0s on one or more files, remove all access to files, or incorporate .SM ACL\s0s into permission bits. .TP 15 .IR lsacl (1) List .SM ACL\s0s on files. .TP 15 .IR chmod (1) Change permission bits and other file miscellaneous mode bits. .TP 15 .IR ls (1) In long form, list permission bits and other file attributes. .TP 15 .IR find (1) Find files according to their attributes, including .SM ACL\s0s. .TP 15 .IR getaccess (1) List access rights to file(s). .SS "ACL Interaction with \f2stat\f1(2), \f2chmod\f1(2), and \f2chown\f1(2)" .TP 8 .I stat The .I st_mode field summarizes the caller's access rights to the file. It differs from file permission bits only if the file has one or more optional entries applicable to the caller. The .I st_basemode field provides the file's actual permission bits. The .I st_acl field indicates the presence of optional ACL entries in the file's .SM ACL. .IP The .I st_mode field contains a user-dependent summary, so that programs ignorant of ACL\s0s that use .IR stat (2) and .IR chmod (2) are more likely to produce expected results, and so that .IR stat (2) provides reasonable information about remote files over .SM NFS. The .I st_basemode and .I st_acl fields are useful only for local files. .TP 8 .I chmod For conformance with IEEE Standard POSIX 1003.1-1988, .IR chmod (2) deletes any optional entries in a file's .SM ACL. Unfortunately, since .IR chmod (2) is used to set file miscellaneous mode bits as well as permission bits, extra effort is required in some cases to preserve a file's .SM ACL. .TP 8 .I chown If the new owner and/or group of a file does not already have an optional (\f2u.%, mode\f1) and/or (%.\f2g, mode\f1) entry in the file's .SM ACL, it inherits the old owner's and/or group's file access permission bits and base ACL entry: .RS .IP (\f2id1,mode1\f1) \-> (\f2id2,mode1\f1) .RE .IP This is the traditional behavior. However, if the new owner and/or group of a file already has an optional (\f2u.%, mode\f1) and/or (\f2%.g, mode\f1) entry in the file's .SM ACL, the .SM ACL does not change: .RS .nf .IP (\f2id1, mode1\f1) \-> (\f2id1, mode1\f1) (\f2id2, mode2\f1) \-> (\f2id2, mode2\f1) .fi .RE .IP Existing access information in the .SM ACL is preserved. However, because the old optional ACL entry becomes the new base ACL entry and vice versa, the file's access permission bits change. .IP Transferring ownership of .SM ACL\s0s by .IR chown (2) allows a file to be transferred to a different user or group, or copied by a different user or group than the owner (using .IR cpacl (3C) or .IR chownacl (3C)), and later returned to the original owner or group without net changes to its .SM ACL. The extra complexity is necessary because: .RS .TP 5 .B \- .SM ACL\s0s are a backward-compatible superset of permission bits (which are coupled to file owner and group .SM IDs), not a replacement for them. .TP 5 .B \- it enables users and programs that deal with ACL\s0s to do so simply, rather than with a combination of permission bits and .SM ACL entries. Also, the access check algorithm is simpler and more symmetrical; permission bits do not ``eclipse'' or ``mask'' .SM ACL entries. .RE .SH EXAMPLES .SS "Operator Form" The following sets the .B %.% entry to restrict ``other'' users to only reading the file. .IP .B "chacl '%.% = r' myfile" .PP The following allows user ``bill'' in any group to write the file, assuming that no restrictive entry is more specific than the .B bill.% entry (for example, a .B bill.adm entry that denies writing). .IP .B "chacl 'bill.% +w' myfile" .PP The following .SM ACL specification contains two entries. The first one deletes write and adds read capability to the entry for user 12, group 4. The second entry denies access for any unspecified user in any unspecified group. .IP .B "chacl '12.4\-w+r, %.% =' myfile" .PP The following pair of entries sets the \f2u\f1.% entry for the file's owner to allow both read and execute and results in adding write and execute capabilities for ``other'' users (the ``%.%'' entry). Note that a mode character is purposely repeated for illustration purposes. .IP \f3chacl '\@\f3.% = 5, %.% + xwx' myfile .SS "Short Form" Here is a typical .SM ACL as it might be printed. It allows user .B jpc to read or execute the file while in group .BR adm ; it denies user .B ajs access to the file while in group .BR trux ; it allows user .B jpc in any group (except .BR adm ) to only read the file; any other user in group .B bin may read or execute the file; and any other user may only read the file. .nf .IP .B "(jpc.adm,r\-x)(ajs.trux,\-\-\-)(jpc.%,r\-\-)(%.bin,r\-x)(%.%,r\-\-)" .fi .PP The following allows ``other'' users to only read the file. .IP .B "chacl '(%.%,r)' myfile" .PP The following sets write-only access for user .B bill in any group. .IP .B "chacl '(bill.%,\-w\-)' myfile" .PP The following sets the entry for user 12 in group 4 to allow read and write. .IP .B "chacl '(12.4,wr)' myfile" .PP The following sets the base ACL entry for the file's owner to allow both read and execute, and sets write and execute capabilities for ``other'' users (the ``%.%'' entry). .IP \f3chacl '(\@\f3.%, 5) (%.%, xwx)' myfile .SS "Long Form" Here is the same .SM ACL as in an earlier example, printed in long form. .nf .IP .ft 3 r\-x jpc.adm \-\-\- ajs.trux r\-\- jpc.% r\-x %.bin r\-\- %.% .fi .ft 1 .SS "ACL Patterns" .PP The following command locates files whose .SM ACL\s0s contain an entry that allows read access and denies write access to some user/group combination. .nf .IP .B "find / \-acl '\(**.\(**+r\-w' \-print" .fi .PP The following matches entries for any user in group .B bin and for user .B tammy in any group, regardless of the entries's mode values. Matching optional ACL entries are deleted and mode values in matching base ACL entries are set to zero: .nf .IP .B "chacl \-d '%.bin, tammy.\(**=\(**' myfile" .fi .PP The following matches all entries, deleting optional entries and setting mode values of base ACL entries to zero: .nf .IP .B "chacl \-d '(\(**.\(**,\(**)' myfile" .fi .SH "HEADERS" .SS "Header <\f3sys/acl.h\f1>" The .RB < sys/acl.h > header file defines the following constants to govern the numbers of entries per ACL: .TP 20 .PD 0 NACLENTRIES maximum number of entries per ACL, including base entries .TP NBASEENTRIES number of base entries .TP NOPTENTRIES number of optional entries .PD .PP The ACL entry structure .B struct acl_entry is also defined, and includes the following members: .TS l l l. aclid_t uid; /\(** user ID \(**/ aclid_t gid; /\(** group ID \(**/ aclmode_t mode; /\(** see \(**/ .TE .PP The .RB < sys/acl.h > header also defines the types .B aclid_t and .B aclmode_t. .PP Non-specific user and group ID values: .TS l l. ACL_NSUSER non-specific user ID ACL_NSGROUP non-specific group ID .TE .PP A special \f2nentries\f1 value ACL_DELOPT is used with .IR setacl (2) to delete optional entries. .SS Header <\f3sys/getaccess.h\f1> The .RB < sys/getaccess.h > header defines constants for use with .IR getaccess (2). .PP Special parameter values for \f2uid\f1: .PP .TS l l. UID_EUID use effective user ID UID_RUID use real user ID UID_SUID use saved user ID .TE .PP Special parameter values for \f2ngroups\f1: .PP .TS l l. NGROUPS_EGID process's effective gid NGROUPS_RGID process's real gid NGROUPS_SGID process's saved gid NGROUPS_SUPP process's supplementary groups only NGROUPS_EGID_SUPP process's eff gid plus supp groups NGROUPS_RGID_SUPP process's real gid plus supp groups NGROUPS_SGID_SUPP process's saved gid plus supp groups .TE .SS Header <\f3acllib.h\f1> The .RB < acllib.h > header file defines several constants for use with .SM ACL support library calls. .PP Symbolic forms of ACL\s0s for \f2acltostr()\f1: .PP .nf FORM_SHORT FORM_LONG .PP Magic values for various calls: .PP .TS l l. ACL_FILEOWNER file's owner ID ACL_FILEGROUP file's group ID ACL_ANYUSER wildcard user ID ACL_ANYGROUP wildcard group ID MODE_DEL delete one ACL entry .TE .PP Mask for valid mode bits in ACL entries: .PP .TS l l. MODEMASK (R_OK | W_OK | X_OK) .TE .PP .fi The .RB < acllib.h > header also defines the .BR "struct acl_entry_patt" ACL pattern entry structure, which includes the following members: .TS l l l l. aclid_t uid; /\(** user ID \(**/ aclid_t gid; /\(** group ID \(**/ aclmode_t onmode; /\(** mode bits that must be on \(**/ aclmode_t offmode; /\(** mode bits that must be off \(**/ .TE .SH WARNINGS .SM ACL\s0s are intended for use on ordinary files and directories. Optional ACL entries are not recommended on files that are manipulated by certain system utilities, such as terminal special files and .SM LP scheduler control files. These utilities might delete optional entries, including those whose intent is restrictive, without warning as a consequence of calling .IR chmod (2), thereby increasing access unexpectedly. .PP Most, but not all, supported utilities are able to handle ACL\s0s correctly. However, only the .IR fbackup (1M) and .IR frecover (1M) file archive utilities handle access control lists properly. When using programs (such as archive programs .IR ar (1), .IR cpio (1), .IR ftio (1), .IR tar (1), and .IR dump (1M)) unable to handle ACLs on files with optional ACL entries, note the Access Control List information included on their respective reference pages, to avoid loss of data. .PP If a user name is defined in the .B /etc/passwd file or a group name is defined in the .B /etc/group file as .B % or \@, or for patterns, \(**, .SM ACL syntax cannot reference that name as itself because the symbols have other meanings. However, such users or groups can still be referenced by their .SM ID numbers. User and/or group names must not include the following characters: .RS .TP 5 .PD 0 .B "." Do not use in user names. .TP \f3+\f1 Do not use in group names. .TP \f3\-\f1 Do not use in group names. .TP \f3=\f1 Do not use for operator form input of group names. .TP \f3\s+1,\s-1\f1 Do not use for short form or for operator form patterns. .TP \f3)\f1 Do not use for short form patterns. .PD .RE .PP It is possible to specify an .SM ACL pattern using the \@ (file owner or group) or .B \(** (wildcard) symbols so that it cannot match certain files, perhaps depending on their ownership, by giving two entries, one with specific values and the other using \@ or .BR \(** , which are equivalent for a file but contain different mode values. For example: .nf .IP \f3find / \-acl '(ajs.%,r)(\@\f3.%,rw)' \-print .fi .PP cannot match a file owned by .BR ajs . .SH DEPENDENCIES .TP 5 .SM NFS .SM NFS. does not support .SM ACL\s0s on remote files. Individual manual entries specify the behavior of various system calls, library calls, and commands under these circumstances. Be careful when transferring a file with optional entries over a network or when manipulating a remote file because optional entries may be silently deleted. .SH AUTHOR The access control list design described here was developed by .SM HP. .SH FILES .TP 20 .PD 0 < sys/acl.h > Header file that supports .IR setacl (2) and .IR getacl (2). .TP < sys/getaccess.h > Header file that supports .IR getaccess (2). .TP < acllib.h > Header file that supports .SM ACL library calls. .TP /etc/passwd Defines user names and user and group .SM ID values. .TP /etc/group Defines group names. .PD .SH SEE ALSO chacl(1), chmod(1), cp(1), find(1), getaccess(1), ln(1), ls(1), lsacl(1), mv(1), rm(1), fbackup(1M), frecover(1M), fsck(1M), fsdb(1M) access(2), chmod(2), chown(2), creat(2), getaccess(2), getacl(2), mknod(2), open(2), setacl(2), stat(2), acltostr(3C), chownacl(3C), cpacl(3C), setaclentry(3C), strtoacl(3C), group(4), passwd(4), privgrp(4). .\" index@introduction to access control lists@@@\f3acl(5)\f1 .\" index@access control lists, introduction to@@@\f3acl(5)\f1 .\" index@lists, access control, introduction to@@@\f3acl(5)\f1 .\" index \s-1ACL\s+1s see access control lists .\" toc@\f3acl(5)\f1:\0\0\f2acl\f1@@@introduction to access control lists .\" .\" fileset_database@acl.5 SYS-ADMIN-MAN .\" $Header: aliases.5,v 1.1.113.4 97/08/19 03:03:45 sita Exp $ .TA e .TH aliases 5M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: August 1997 .SH NAME aliases \- aliases file for sendmail .SH SYNOPSIS .B aliases .SH DESCRIPTION This file describes user .I ID aliases used by .I /usr/sbin/sendmail. The file resides in .I /etc/mail and is formatted as a series of lines of the form .RS .TP 5 name: name_1, name2, name_3, . . . .RE .PP The .I name is the name to alias, and the .I name_n are the aliases for that name. Lines beginning with white space are continuation lines. Lines beginning with `#' are comments. .PP Aliasing occurs only on local names. Loops can not occur, since no message will be sent to any person more than once. .PP After aliasing has been done, local and valid recipients who have a ``.forward'' file in their home directory have messages forwarded to the list of users defined in that file. .PP This is only the raw data file; the actual aliasing information is placed into a binary format in the file .I /etc/mail/aliases.db using the program newaliases(1M). A newaliases command should be executed each time the aliases file is changed for the change to take effect. Note that the NIS alias maps are generated by ypmake using the makemap program, which leaves aliases.pag and aliases.dir in the /etc/mail directory. .SH SEE ALSO .RS .TP newaliases (1M), ndbm (3X) , dbm (3X) , sendmail (1M) .RE .SH HISTORY The .B aliases file format appeared in 4.0BSD. .\" $Header: ascii.5,v 72.5 93/11/11 21:30:16 ssa Exp $ .TA a .TH ascii 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ascii \- map of \s-1ASCII\s0 character set .SH SYNOPSIS .C cat /usr/share/lib/pub/ascii .SH DESCRIPTION .C /usr/share/lib/pub/ascii provides a map of the .SM ASCII character set, giving both octal and hexadecimal equivalents of each character, to be printed as needed. The file contains the following text: .IP .ift .ft 4 .nf |000 nul|001 soh|002 stx|003 etx|004 eot|005 enq|006 ack|007 bel| |010 bs |011 ht |012 nl |013 vt |014 np |015 cr |016 so |017 si | |020 dle|021 dc1|022 dc2|023 dc3|024 dc4|025 nak|026 syn|027 etb| |030 can|031 em |032 sub|033 esc|034 fs |035 gs |036 rs |037 us | |040 sp |041 ! |042 " |043 # |044 $ |045 % |046 & |047 \' | |050 ( |051 ) |052 * |053 + |054 , |055 \- |056 . |057 / | |060 0 |061 1 |062 2 |063 3 |064 4 |065 5 |066 6 |067 7 | |070 8 |071 9 |072 : |073 ; |074 < |075 = |076 > |077 ? | |100 @ |101 A |102 B |103 C |104 D |105 E |106 F |107 G | |110 H |111 I |112 J |113 K |114 L |115 M |116 N |117 O | |120 P |121 Q |122 R |123 S |124 T |125 U |126 V |127 W | |130 X |131 Y |132 Z |133 [ |134 \\ |135 ] |136 ^ |137 _ | |140 \` |141 a |142 b |143 c |144 d |145 e |146 f |147 g | |150 h |151 i |152 j |153 k |154 l |155 m |156 n |157 o | |160 p |161 q |162 r |163 s |164 t |165 u |166 v |167 w | |170 x |171 y |172 z |173 { |174 | |175 } |176 ~ |177 del| | 00 nul| 01 soh| 02 stx| 03 etx| 04 eot| 05 enq| 06 ack| 07 bel| | 08 bs | 09 ht | 0a nl | 0b vt | 0c np | 0d cr | 0e so | 0f si | | 10 dle| 11 dc1| 12 dc2| 13 dc3| 14 dc4| 15 nak| 16 syn| 17 etb| | 18 can| 19 em | 1a sub| 1b esc| 1c fs | 1d gs | 1e rs | 1f us | | 20 sp | 21 ! | 22 " | 23 # | 24 $ | 25 % | 26 & | 27 \' | | 28 ( | 29 ) | 2a * | 2b + | 2c , | 2d \- | 2e . | 2f / | | 30 0 | 31 1 | 32 2 | 33 3 | 34 4 | 35 5 | 36 6 | 37 7 | | 38 8 | 39 9 | 3a : | 3b ; | 3c < | 3d = | 3e > | 3f ? | | 40 @ | 41 A | 42 B | 43 C | 44 D | 45 E | 46 F | 47 G | | 48 H | 49 I | 4a J | 4b K | 4c L | 4d M | 4e N | 4f O | | 50 P | 51 Q | 52 R | 53 S | 54 T | 55 U | 56 V | 57 W | | 58 X | 59 Y | 5a Z | 5b [ | 5c \\ | 5d ] | 5e ^ | 5f _ | | 60 \` | 61 a | 62 b | 63 c | 64 d | 65 e | 66 f | 67 g | | 68 h | 69 i | 6a j | 6b k | 6c l | 6d m | 6e n | 6f o | | 70 p | 71 q | 72 r | 73 s | 74 t | 75 u | 76 v | 77 w | | 78 x | 79 y | 7a z | 7b { | 7c | | 7d } | 7e ~ | 7f del| .ft 1 .fi .SS Control Characters The following table shows the set of .SM ASCII control characters with their octal, decimal, and hexadecimal values. To obtain the respective characters from the keyboard, use the indicated keypress combinations. .PP To place control characters in a file when using the .C vi or .C ex editor, type Ctrl-\c .C v before typing the desired control character. .PP .ne 35 .ps -1 .vs -1p .TS center box tab(;); cB | cB | cB | cB | cB | cB | cB c | c | c | cf4 | cp-1 | l | c . Oct;Dec;Hex;Disp;Symbol;Char Name;Keypress _ 000;000;00;\f1none\fP;NUL;Null;Ctrl-Shift-\f4\s+1@\fP\s0 001;001;01;^A;SOH;Start of Header;Ctrl-\f4\s+1A\fP\s0 002;002;02;^B;STX;Start of Text;Ctrl-\f4\s+1B\fP\s0 003;003;03;^C;ETX;End of Text;Ctrl-\f4\s+1C\fP\s0 004;004;04;^D;EOT;End of Transmission;Ctrl-\f4\s+1D\fP\s0 005;005;05;^E;ENQ;Enquire;Ctrl-\f4\s+1E\fP\s0 006;006;06;^F;ACK;Acknowledge;Ctrl-\f4\s+1F\fP\s0 007;007;07;^G;BEL;Bell;Ctrl-\f4\s+1G\fP\s0 010;008;08;^H;BS;Back Space;Ctrl-\f4\s+1H\fP\s0 011;009;09;^I;HT;Horizontal Tab;Ctrl-\f4\s+1I\fP\s0 012;010;0A;^J;LF;Line Feed;Ctrl-\f4\s+1J\fP\s0 013;011;0B;^K;VT;Vertical Tab;Ctrl-\f4\s+1K\fP\s0 014;012;0C;^L;FF;Form Feed;Ctrl-\f4\s+1L\fP\s0 015;013;0D;^M;CR;Carriage Return;Ctrl-\f4\s+1M\fP\s0 016;014;0E;^N;SO;Shift Out;Ctrl-\f4\s+1N\fP\s0 017;015;0F;^O;SI;Shift In;Ctrl-\f4\s+1O\fP\s0 020;016;10;^P;DLE;(or DEL) Delete;Ctrl-\f4\s+1P\fP\s0 021;017;11;^Q;DC1;Device Control 1;Ctrl-\f4\s+1Q\fP\s0 022;018;12;^R;DC2;Device Control 2;Ctrl-\f4\s+1R\fP\s0 023;019;13;^S;DC3;Device Control 3;Ctrl-\f4\s+1S\fP\s0 024;020;14;^T;DC4;Device Control 4;Ctrl-\f4\s+1T\fP\s0 025;021;15;^U;NAK;Negative Acknowledge;Ctrl-\f4\s+1U\fP\s0 026;022;16;^V;SYN;Synchronize;Ctrl-\f4\s+1V\fP\s0 027;023;17;^W;ETB;End Transmission Block;Ctrl-\f4\s+1W\fP\s0 030;024;18;^X;CAN;Cancel;Ctrl-\f4\s+1X\fP\s0 031;025;19;^Y;EM;End of Medium;Ctrl-\f4\s+1Y\fP\s0 032;026;1A;^Z;SUB;Substitute;Ctrl-\f4\s+1Z\fP\s0 033;026;1A;^[;ESC;Escape;Ctrl-\f4\s+1[\fP\s0 034;026;1A;^\e;FS;File Separator;Ctrl-\f4\s+1\e\fP\s0 035;026;1A;^];GS;Group Separator;Ctrl-\f4\s+1]\fP\s0 036;026;1A;^^;RS;Record Separator;Ctrl-Shift-\f4\s+1^\fP\s0 037;026;1A;^_;US;Unit Separator;Ctrl-Shift-\f4\s+1_\fP\s0 177;127;7F;^?;DEL;Delete;\s-1DEL\s0 .TE .ps +1 .vs +1 .SH WARNINGS Note that some .SM HP-UX subsystems such as the keyboard interface, window systems, and other system software may use selected keyboard control characters for special purposes, possibly causing unexpected results. .SH FILES .C /usr/share/lib/pub/ascii .\" .\" index@\f2ascii\f1 \- map of \s-1ASCII\s0 character set@@@\f3ascii(5)\f1 .\" index@map of \s-1ASCII\s0 character set@@@\f3ascii(5)\f1 .\" index@octal equivalents: \s-1ASCII\s0 character set@@@\f3ascii(5)\f1 .\" index@decimal equivalents: \s-1ASCII\s0 character set@@@\f3ascii(5)\f1 .\" index@hexadecimal equivalents: \s-1ASCII\s0 character set@@@\f3ascii(5)\f1 .\" index@type control characters, how to@@@\f3ascii(5)\f1 .\" index@characters, how to type control@@@\f3ascii(5)\f1 .\" index@control characters, how to type@@@\f3ascii(5)\f1 .\" index@keyboard, how to obtain control characters from@@@\f3ascii(5)\f1 .\" .\" toc@\f3ascii(5)\f1:\0\0\f2ascii\f1@@@map of \s-1ASCII\s0 character set .\" .\" fileset_database@ascii.5 SYS-ADMIN-MAN ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" ...\" .rm zA .rm zZ .TH aud_audit_events "5" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "enh,10234,R1.1,new manpage." .iX "events" "auditable" .iX "events" "audit services" .iX "audit services" "auditable events" .iX "auditable events" "audit services" .iX "\*Laud_audit_events\*O" .SH NAME \*Laud_audit_events\*O - Auditable events for the audit services .SH "DESCRIPTION" .PP Code is in place for auditing audit service-significant events. Among these events are: .iX "events" "audit service operations" .ML .LI Administrative operations .P These are subdivided into \*Lmodify\*O and \*Lquery\*O operations. .LI Filter operations .P These are subdivided into \*Lmodify\*O and \*Lquery\*O operations. .LE .PP .iX "event class" "definitions" Event class definitions, together with filters, control the auditing execution at these code points. Filters can be updated dynamically. Filter files are maintained by a per-host audit daemon, and are shared among all the audit clients on the same host. The \*Ldcecp\*O command interface program is used for maintaining the .iX "\*Ldcecp\*O command" filters. (See the \*Ldcecp\*O reference page.) The \*Ldcecp\*O command is executable by all users and system administrators. The control on who is allowed to modify filters is done through audit daemon's ACL, which maintains the filters. .PP The Audit Service RPC interfaces include \*Laudit_control\*O and \*Laudit_filter\*O operations. .SS "Administrative Operations" .PP The \*Ldce_audit_admin_modify\*O and \*Ldce_audit_admin_query\*O event classes lump together the administrative operations that are performed on the Audit daemon. .P The \*Ldce_audit_admin_modify\*O event class has the following events that modify the operation of the Audit daemon: .ML .LI EVT_MODIFY_STATE - Enables or disables the Audit daemon for logging. .LI EVT_MODIFY_SSTRATEGY - Modifies storage strategy. This can be any of the following: .ML .LI \*LSave\*O - If the trail is full, it is backed up and renamed with a timestamp then writes on the original trail again. .LI \*LWrap\*O - If the trail is full, goes back to the beginning of the file, overwriting previously written records. .LE .LI EVT_REWIND - Rewinds the Audit daemon's central trail file. .LI EVT_STOP - Stops the Audit daemon. .LE .PP The following are the audit code points in the Audit Service interfaces, with their Event Types, Event Classes, and any Event-Specific Information. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_MODIFY_STATE (0x306, dce_audit_admin_modify)\*O .VL .LI "Event-Specific Information" None .LE .LE .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_MODIFY_SSTRATEGY (0x305, dce_audit_admin_modify)\*O .VL .LI "Event-Specific Information" None .LE .LE .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_REWIND (0x307, dce_audit_admin_modify)\*O .VL .LI "Event-Specific Information" None .LE .LE .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_STOP (0x308, dce_audit_admin_modify)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP The \*Ldce_audit_admin_query\*O event class has two events: .ML .LI EVT_SHOW_SSTRATEGY - Shows the storage strategy. .LI EVT_SHOW_STATE - Shows the state of the Audit daemon. .LE .P Following are the details of this event class: .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_SHOW_SSTRATEGY (0x309, dce_audit_admin_query)\*O .VL .LI "Event-Specific Information" None .LE .LE .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_SHOW_STATE (0x30a, dce_audit_admin_query)\*O .VL .LI "Event-Specific Information" None .LE .LE .SS "Filter Operations" .PP The \*Ldce_audit_filter_modify\*O and \*Ldce_audit_filter_query\*O event classes are the filter operations that the Audit daemon handles. .PP The \*Ldce_audit_filter_modify\*O event class has the following events: .ML .LI EVT_ADD_FILTER - Adds a filter. .LI EVT_DELETE_FILTER - Removes all guides for a specific subject. .LI EVT_REMOVE_FILTER - Removes a specific guide for a specific subject. .LE .P Following are the details of this event class: .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_ADD_FILTER (0x303, dce_audit_filter_modify)\*O .VL .LI "Event-Specific Information" None. .LE .LE .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_DELETE_FILTER (0x300, dce_audit_filter_modify)\*O .VL .LI "Event-Specific Information" None. .LE .LE .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_REMOVE_FILTER (0x304, dce_audit_filter_modify)\*O .VL .LI "Event-Specific Information" None. .LE .LE .P The \*Ldce_audit_filter_query\*O contains two events: .ML .LI EVT_LIST_FILTER - Lists all subjects that have filters. .LI EVT_SHOW_FILTER - Shows all filters for a specific principal. .LE .P Following are the details of this event class. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_LIST_FILTER (0x302, dce_audit_filter_query)\*O .VL .LI "Event-Specific Information" None. .LE .LE .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_SHOW_FILTER (0x301, dce_audit_filter_query)\*O .VL .LI "Event-Specific Information" .iS aud_c_evt_info_long_int esl_type aud_c_evt_info_char_string subject_name .iE .LE .LE .SH RELATED INFORMATION Commands: \*Ldcecp(1m)\*O. .sp .4v Files: \*Levent_class.5\*O. .zZ "enh,10234,R1.1,new manpage." .AD CRUZ .\" $Header: audio.5,v 72.4 94/09/08 13:44:18 ssa Exp $ .TA a .TH Audio 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME Audio \- audio tools available through HP VUE .SH DESCRIPTION This man-page describes the audio tools available through .C HP VUE for playing, recording, and editing sound. These include Audio Setup, Audio Security, Audio Editor, Audio Control Panel, Audio File and Data Formats, and Audio Library. .IR Audio (5) also provides information on using other audio tools from the HP-UX command line. .SS Audio Setup Requirements To use the audio tools, you need access to both audio client and server software. This software is part of HP-UX. The server requires a workstation or X station with Audio hardware. .PP Audio hardware is built into all Series 700 computers .I except the 720, 730, and 750; you can upgrade these models to become the 725, 735, or 755, which do have audio hardware. Note, older 705s (that is, 705s with the 8MB HP-UX) do not include audio software. .PP To use audio on an X station, you need either an HP ENVIZEX or ENTRIA X station that includes an audio accessory kit. .PP In most cases, you use the audio client and server software on one system. However, if you need the audio server running on a remote workstation or X station, see .IR aserver (1M). The audio data files can reside on either system or a third system. .SS "Audio Security" Audio is secured to allow access only to the user on the local workstation. If you need to allow remote systems to access audio on a workstation, see .IR asecure (1M). .SS The Audio Editor The Audio Editor is an OSF/Motif-based tool with play, record, and edit functions. The Editor displays a waveform that makes it easy to edit and play audio segments. .PP You can open an audio file, play it, look at its waveform, and use the waveform controls to edit the file. To set an output device, use the Audio Control Panel. .PP To record audio, first connect a microphone or other audio equipment that your system supports; perhaps a CD or tape player. To make the connections, see the Audio Editor online help ("Audio Editor Tasks" section) or your system owner's manual. .PP You can use the Editor to create and record an audio file. .RS .PP To start the Editor from the General Toolbox, open the Media Toolbox and drop an audio file on the Audio Editor control or double-click the control. .PP To start the Editor in a terminal window, type the following: .RS .CI /opt/audio/bin/audio_editor \0 .RI [ pathname ] .RE .RE .PP Online help is available through the .C Help menu in the upper-right hand corner of the Editor. .PP .SS The Audio Control Panel The Audio Control Panel is an OSF/Motif-based tool that you use to set the audio volume and choose the audio device for playback. .PP The volume control affects the play volume for any client system of this workstation or X station. The Audio Control Panel also includes a Stop button to stop the current play operation. .PP You can also use the Audio Control Panel to choose the device for playback, (headphones, built-in speaker, or device connected to Line Out, such as external speakers). This choice controls where audio is played when you double-click an audio file or use the Audio Editor to play a file. The default output device is the internal (built-in) speaker. .RS .PP To start the Audio Control Panel from HP VUE, click on the Audio control in HP VUE Front Panel. .PP To start the .CR "Audio Control Panel" in a terminal window, type the following: .RS .CR "/opt/audio/bin/AudioCP" .RE .RE .PP If your system has Audio applications that were developed using an earlier version of Audio software, those applications may use the .CR SPEAKER environment variable to determine their output devices. You can set the .CR SPEAKER variable for all applications started by HP VUE by modifying the .C $HOME/.vueprofile file. The .CR SPEAKER variable can be external (headphones, Line Out) or internal (built-in speaker). .RS .PP To set the .CR SPEAKER variable for a Bourne or Korn shell, enter: .RS .sp .C SPEAKER=internal .br .C export speaker .RE .PP To set the .CR SPEAKER variable for a C shell, enter: .RS .sp .C setenv SPEAKER internal .RE .RE .SS Audio File and Data Formats Audio files supported contain uncompressed audio data in one of three file formats: generic, RIFF/Waveform, or raw. Each file also needs the correct filename extension. For the three file formats, the Audio Editor online help lists which data formats and filename extensions that apply. .PP The extension causes the appropriate icon to appear in the File Manager. To play audio files you can drag and drop the file icons onto the Audio Editor or Control Panel or double-click the icon. .PP If you need to add an extension to a filename, (or convert the file format) the .C /opt/audio/bin/convert command is recommended. See .IR convert (1). However, you can instead rename the file to make it playable. Use this filename format: .RS .sp .I " filename.rate.data_type" .sp .RE .PP The .IR rate \0and \0data_type variables accept values defined for the .C "-drate" and .C "-ddata" options of .CR "convert". If needed, you can omit the .IR "rate" variable. Use this filename format: .RS .sp .I " filename.data_type" .RE .sp .SS \s-1Audio Library\s0 HP-UX includes an Audio Library that was used to build the audio tools. If you have ordered and installed the .SM User Environment Developer's Kit, you can use the Audio Library to create other audio applications. .PP The HP-UX Audio Library contains functions that C programs can use to manipulate audio. The functions interact with the Audio Server, enabling the application to record and play audio data files and convert audio data files from one format to another. .PP For more information about audio programming, refer to the manual .IR "Using the Audio Developer's Kit" . .SH AUTHOR The Audio Library, Audio Editor, and Audio Control Panel were developed by .SM HP. .SH SEE ALSO .na asecure(1m), aserver(1m), attributes(1), convert(1), send_sound(1). .PP .IR "Using the Audio Developer's Kit" .\" .\" toc@\f3Audio(5)\f1@@@audio tools available through HP VUE .\" .\" index@\f1Audio \- audio tools available through HP VUE@@@\f3Audio(5)\f1 .\" index@\f1Audio Setup@@@see \f2Audio(5)\f1 .\" index@\f1Setup, Audio@@@see \f2Audio(5)\f1 .\" index@\f1Audio Security@@@see \f2Audio(5)\f1 .\" index@\f1Security, Audio@@@see \f2Audio(5)\f1 .\" index@\f1Audio Editor,@@@see \f2Audio(5)\f1 .\" index@\f1Editor, Audio@@@see \f2Audio(5)\f1 .\" index@\f1Audio Control Panel@@@see \f2Audio(5)\f1 .\" index@\f1Control Panel, Audio@@@see \f2Audio(5)\f1 .\" index@\f1File and Data Formats, Audio@@@see \f2Audio(5)\f1 .\" index@\f1Audio File and Data Formats@@@see \f2Audio(5)\f1 .\" index@\f1Audio Library@@@see \f2Audio(5)\f1 .\" index@\f1Library, Audio@@@see \f2Audio(5)\f1 .\" .\" links@audio.5 Audio.5 .\" $Header: audit.5,v 72.5 94/07/03 16:38:29 ssa Exp $ .TA a .TH audit 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME audit \- introduction to HP-UX Auditing System .SH SYNOPSIS .B #include .SH DESCRIPTION The purpose of the auditing system is to record instances of access by subjects to objects and to allow detection of any (repeated) attempts to bypass the protection mechanism and any misuses of privileges, thus acting as a deterrant against system abuses and exposing potential security weaknesses in the system. .SS User and Event Selection The auditing system provides administrators with a mechanism to select users and activities to be audited. Users are assigned unique identifiers called .BR "audit id" s by the administrator which remain unchanged throughout a user's history. The .IR audusr (1M) command is used to specify those users who are to be audited. The .IR audevent (1M) command is used to specify system activities (auditable events) that are to be audited. Auditable events are classified into several categories, illustrated by the event category list at the end. (An event category consists of a set of operations that affect a particular aspect of the system.) .SS Self-auditing Programs To reduce the amount of log data and to provide a higher-level recording of some typical system operations, a collection of privileged programs are given capabilities to perform self-auditing. This means that the programs can suspend the currently specified auditing on themselves and produce a high-level description of the operations they perform. These self-auditing programs include: .IR at (1), .IR chfn (1), .IR chsh (1), .IR crontab (1), .IR login (1), .IR newgrp (1), .IR passwd (1), .IR audevent (1M), .IR audisp (1M), .IR audsys (1M), .IR audusr (1M), .IR cron (1M), .IR init (1M), .IR lpsched (1M), .IR pwck (1M), and .IR sam (1M). Note that only these privileged programs are allowed to do self-auditing, and that the audit suspension they perform only affects these programs and does not affect any other processes on the system. .SS Viewing of Audited Data The .IR audisp (1M) command is used to view audited data recorded in log file(s). .IR audisp (1M) merges the log file(s) into a single audit trail in chronological sequence. The administrator can select viewing criteria provided by .IR audisp (1M) to limit the search to particular kinds of events which the administrator is interested in investigating. .SS Monitoring the Auditing System To ensure that the auditing system operates normally and that any abnormal behaviors are detected, a privileged .I daemon program, .IR audomon (1M), runs in the background to monitor various auditing system parameters. When these parameters take on abnormal (dangerous) values, or when components of the auditing system are accidentally removed, .IR audomon (1M) prints warning messages and tries to resolve the problem if possible. .SS Starting and Halting the Auditing System The administrator can use the .IR audsys (1M) command to start or halt the auditing system, or to get a brief summary of the status of the audit system. Prior to starting the auditing system, .IR audsys (1M) also validates the parameters specified, and ensures that the auditing system is in a safe and consistent state. .SS Audit Log Files At any time when the auditing system is enabled, at least an audit log file must be present, and another back-up log file is highly recommended. Both of these files (along with various attributes for these files) can be specified using .IR audsys (1M). When the current log file exceeds a pre-specified size, or when the auditing file system is dangerously full, the system automatically switches to the back-up file if possible. If a back-up log file is not available, warning messages are sent to request appropriate administrator action. .SS Event Categories .RS 5 .TP 15 .C create Log all creations of objects (files, directories, other file objects), including .IR creat (2), .IR mknod (2), .IR pipe (2), .IR mkdir (2), .IR semget (2), .IR msgget (2), .IR shmget (2), and .IR shmat (2). .TP .C delete Log all deletions of objects (files, directories, other file objects), including .IR rmdir (2), .IR semctl (2), and .IR msgctl (2). .TP .C moddac Log all modifications of object's DAC .RI ( chmod , " setacl" ), including .IR chmod (2), .IR chown (2), .IR umask (2), .IR fchown (2), .IR fchmod (2), .IR setacl (2), and .IR fsetacl (2). .TP .C modaccess Log all modifications other than DAC, including .IR link (2), .IR unlink (2), .IR chdir (2), .IR setuid (2), .IR setgid (2), .IR chroot (2), .IR setgroups (2), .IR setresuid (2), .IR setresgid (2), .IR rename (2), .IR shmctl (2), .IR shmdt (2), and .IR newgrp (1). .TP .C open Log all openings of objects (file open, other objects open) including .IR open (2), .IR execv (2), .IR ptrace (2), .IR execve (2), .IR truncate (2), .IR ftruncate (2), and .IR lpsched (1M). .TP .C close Log all closings of objects (file close, other objects close) including .IR close (2). .TP .C process Log all operations on processes, including .IR exit (2), .IR fork (2), .IR vfork (2), and .IR kill (2). .TP .C removable Log all removable media events (mounting and unmounting events), including .IR smount (2), .IR umount (2), and .IR vfsmount (2). .TP .C login Log all logins and logouts, including .IR login (1), .IR init (1M). .TP .C admin Log all administrative and privileged events, including .IR stime (2), .IR swapon (2), .IR settimeofday (2), .IR sethostid (2), .IR privgrp (2), .IR setevent (2), .IR setaudproc (2), .IR audswitch (2), .IR setaudid (2), .IR setdomainname (2), .IR reboot (2), .IR sam (1M), .IR audisp (1M), .IR audevent (1M), .IR audsys (1M), .IR audusr (1M), .IR chfn (1), .IR chsh (1), .IR passwd (1), .IR pwck (1M), and .IR init (1M). .TP .C ipccreat Log all IPC create events including .IR socket (2) and .IR bind (2). .TP .C ipcopen Log all IPC open events including .IR connect (2) and .IR accept (2). .TP .C ipcclose Log all IPC close events including .IR shutdown (2). .TP .C uevent1 Log user-defined event. .TP .C uevent2 Log user-defined event. .TP .C uevent3 Log user-defined event. .TP .C ipcdgram Log IPC Datagram transactions. .RE .PP Note that some commands such as .IR init (1M) may occur in more than one category because the event varies, depending on the operation done by the command. .SH AUTHOR The auditing system described above was developed by HP. .SH SEE ALSO audsys(1M), audusr(1M), audevent(1M), audisp(1M), audctl(2), audswitch(2), audwrite(2), getaudid(2), setaudid(2), getevent(2), setevent(2), audit(4). .\" .\" index@\f2audsys\f1(1M) \- HP-UX Auditing System described@@@\f3audit(5)\f1 .\" index@\f2audusr\f1(1M) \- HP-UX Auditing System described@@@\f3audit(5)\f1 .\" index@\f2audevent\f1(1M) \- HP-UX Auditing System described@@@\f3audit(5)\f1 .\" index@\f2audisp\f1(1M) \- HP-UX Auditing System described@@@\f3audit(5)\f1 .\" index@\f2audctl\f1(2) \- HP-UX Auditing System described@@@\f3audit(5)\f1 .\" index@\f2audswitch\f1(2) \- HP-UX Auditing System described@@@\f3audit(5)\f1 .\" index@\f2audwrite\f1(2) \- HP-UX Auditing System described@@@\f3audit(5)\f1 .\" index@\f2getaudid\f1(2) \- HP-UX Auditing System described@@@\f3audit(5)\f1 .\" index@\f2setaudid\f1(2) \- HP-UX Auditing System described@@@\f3audit(5)\f1 .\" index@\f2getevent\f1(2) \- HP-UX Auditing System described@@@\f3audit(5)\f1 .\" index@\f2setevent\f1(2) \- HP-UX Auditing System described@@@\f3audit(5)\f1 .\" index@\f2audit\f1(5) \- HP-UX Auditing System described@@@\f3audit(5)\f1 .\" .\" toc@\f3audit(5)\f1@@@introduction to HP-UX Auditing System .\" .\" fileset_database@audit.5 SYS-ADMIN-MAN .\" $Header: curses.5,v 76.2 95/07/31 17:36:54 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH 5 "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME curses.h \(em definitions for screen handling and optimisation functions .SH SYNOPSIS .C "#include " .SH DESCRIPTION .SS "Objects" The .Hd curses.h header provides a declaration for .IR COLOR_PAIRS , .IR COLORS , .IR COLS , .IR curscr , .I LINES and .IR stdscr . .SS "Constants" The following constants are defined: .TP 12 .CR EOF Function return value for end-of-file .TP .C ERR Function return value for failure .TP .CR FALSE Boolean \f2false\f1 value .TP .CR OK Function return value for success .TP .CR TRUE Boolean \f2true\f1 value .TP .CR WEOF Wide-character function return value for end-of-file, as defined in .CR . .SS "Data Types" The following data types are defined through \f3typedef\f1: .TP 12 .CR attr_t An OR-ed set of attributes .TP .CR bool Boolean data type .TP .CR chtype A character, attributes \ and a colour-pair .TP .CR SCREEN An opaque terminal representation .TP .CR wchar_t As described in .Hd stddef.h .TP .CR wint_t As described in .Hd wchar.h .TP .CR cchar_t References a string of wide characters .TP .CR WINDOW An opaque window representation .PP These data types are described in more detail in \f3Data Types\f1 in curses_intro. .P The inclusion of .Hd curses.h may make visible all symbols from the headers .CR , .CR , .Hd termios.h and .CR . .br .ne 15 .SH "Attribute Bits" The following symbolic constants are used to manipulate objects of type .CR attr_t : .P .TS lbw(2i) l. WA_ALTCHARSET \f1Alternate character set\f1 WA_BLINK \f1Blinking\f1 WA_BOLD \f1Extra bright or bold\f1 WA_DIM \f1Half bright\f1 WA_HORIZONTAL \f1Horizontal highlight\f1 WA_INVIS \f1Invisible\f1 WA_LEFT \f1Left highlight\f1 WA_LOW \f1Low highlight\f1 WA_PROTECT \f1Protected\f1 WA_REVERSE \f1Reverse video\f1 WA_RIGHT \f1Right highlight\f1 WA_STANDOUT \f1Best highlighting mode of the terminal\f1 WA_TOP \f1Top highlight\f1 WA_UNDERLINE \f1Underlining\f1 WA_VERTICAL \f1Vertical highlight\f1 .TE .P These attribute flags shall be distinct. .P The following symbolic constants are used to manipulate attribute bits in objects of type .CR chtype : .P .TS lbw(2i) l. A_ALTCHARSET \f1Alternate character set\f1 A_BLINK \f1Blinking\f1 A_BOLD \f1Extra bright or bold\f1 A_DIM \f1Half bright\f1 A_INVIS \f1Invisible\f1 A_PROTECT \f1Protected\f1 A_REVERSE \f1Reverse video\f1 A_STANDOUT \f1Best highlighting mode of the terminal\f1 A_UNDERLINE \f1Underlining\f1 .TE .P These attribute flags need not be distinct \ except when _XOPEN_CURSES is defined and the application sets _XOPEN_SOURCE_EXTENDED to 1. .P The following symbolic constants can be used as bit-masks to extract the components of a .CR chtype : .P .TS lbw(2i) l. A_ATTRIBUTES \f1Bit-mask to extract attributes\f1 A_CHARTEXT \f1Bit-mask to extract a character\f1 A_COLOR \f1Bit-mask to extract colour-pair information\f1 .TE .P The following symbolic constants can be used as bit-masks to extract the components of a .CR chtype : .P .TS lbw(2i) l. A_ATTRIBUTES \f1Bit-mask to extract attributes\f1 A_CHARTEXT \f1Bit-mask to extract a character\f1 A_COLOR \f1Bit-mask to extract colour-pair information\f1 .TE .br .ne 30 .SH "Line-Drawing Constants" The .Hd curses.h header defines the symbolic constants shown in the leftmost two columns of the following table for use in drawing lines. The symbolic constants that begin with ACS_ are .B char constants. The symbolic constants that begin with WACS_ are .CR cchar_t constants for use with the wide-character interfaces that take a pointer to a .CR cchar_t . .P In the POSIX locale, the characters shown in the .B "POSIX Locale Default" column are used when the terminal database does not specify a value using the .CR acsc capability as described in \f3Line Graphics\f1 in .IR terminfo (4). .P .TS center tab(`); cb cb cb cb cb cb cb cb lfCW lfCW cfCW l. ``POSIX Locale char Constant`cchar_t Constant`Default`Glyph Description _ ACS_ULCORNER`WACS_ULCORNER`+`upper left-hand corner ACS_LLCORNER`WACS_LLCORNER`+`lower left-hand corner ACS_URCORNER`WACS_URCORNER`+`upper right-hand corner ACS_LRCORNER`WACS_LRCORNER`+`lower right-hand corner ACS_RTEE`WACS_RTEE`+`right tee (\|\-\(br\|) ACS_LTEE`WACS_LTEE`+`left tee (\|\z\(br\-\|) ACS_BTEE`WACS_BTEE`+`bottom tee (\|\o'\(ul\(br'\|) ACS_TTEE`WACS_TTEE`+`top tee (\|\o'\(rn\(br'\|) ACS_HLINE`WACS_HLINE`\-`horizontal line ACS_VLINE`WACS_VLINE`|`vertical line ACS_PLUS`WACS_PLUS`+`plus ACS_S1`WACS_S1`-`scan line 1 ACS_S9`WACS_S9`\(ul`scan line 9 ACS_DIAMOND`WACS_DIAMOND`+`diamond ACS_CKBOARD`WACS_CKBOARD`:`checker board (stipple) ACS_DEGREE`WACS_DEGREE`'`degree symbol ACS_PLMINUS`WACS_PLMINUS`#`plus/minus ACS_BULLET`WACS_BULLET`o`bullet ACS_LARROW`WACS_LARROW`<`arrow pointing left ACS_RARROW`WACS_RARROW`>`arrow pointing right ACS_DARROW`WACS_DARROW`v`arrow pointing down ACS_UARROW`WACS_UARROW`\d^\u`arrow pointing up ACS_BOARD `WACS_BOARD `#`board of squares ACS_LANTERN`WACS_LANTERN`#`lantern symbol ACS_BLOCK `WACS_BLOCK`#`solid square block .TE .ne 20 .SH "Colour-related Macros" The following colour-related macros are defined: .P COLOR_BLACK .br COLOR_BLUE .br COLOR_GREEN .br COLOR_CYAN .br COLOR_RED .br COLOR_MAGENTA .br COLOR_YELLOW .br COLOR_WHITE .ne 20 .SH "Coordinate-related Macros" The following coordinate-related macros are defined: .P .C "void getbegyx(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .br .C "void getmaxyx(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .br .C "void getparyx(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .br .C "void getyx(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .ift .bp .SH "Key Codes" The following symbolic constants representing function key values are defined: .P .TS tab(`) expand; cbw(15) cbw(65) l l. Key Code`Description _ KEY_CODE_YES`Used to indicate that a \f3wchar_t\f1 variable contains a key code KEY_BREAK`Break key KEY_DOWN`Down arrow key KEY_UP`Up arrow key KEY_LEFT`Left arrow key KEY_RIGHT`Right arrow key KEY_HOME`Home key KEY_BACKSPACE`Backspace KEY_F0`Function keys; space for 64 keys is reserved KEY_F(\f2n\fP)`For 0\|\(<=\\|\f2n\fP\|\(<=\|63 KEY_DL`Delete line KEY_IL`Insert line KEY_DC`Delete character KEY_IC`Insert char or enter insert mode KEY_EIC`Exit insert char mode KEY_CLEAR`Clear screen KEY_EOS`Clear to end of screen KEY_EOL`Clear to end of line KEY_SF`Scroll 1 line forward KEY_SR`Scroll 1 line backward (reverse) KEY_NPAGE`Next page KEY_PPAGE`Previous page KEY_STAB`Set tab KEY_CTAB`Clear tab KEY_CATAB`Clear all tabs KEY_ENTER`Enter or send KEY_SRESET`Soft (partial) reset KEY_RESET`Reset or hard reset KEY_PRINT`Print or copy KEY_LL`Home down or bottom KEY_A1`Upper left of keypad KEY_A3`Upper right of keypad KEY_B2`Center of keypad KEY_C1`Lower left of keypad KEY_C3`Lower right of keypad .TE .ne 10 The virtual keypad is a 3-by-3 keypad arranged as follows: .P .TS allbox center tab(`); c c c. A1`UP`A3 LEFT`B2`RIGHT C1`DOWN`C3 .TE .P Each legend, such as A1, corresponds to a symbolic constant for a key code from the preceding table, such as KEY_A1. The following symbolic constants representing function key values are also defined: .PP .ift .bp .TS tab(`) center; cbw(15) cbw(65) l l. Key Code`Description _ KEY_BTAB`Back tab key KEY_BEG`Beginning key KEY_CANCEL`Cancel key KEY_CLOSE`Close key KEY_COMMAND`Cmd (command) key KEY_COPY`Copy key KEY_CREATE`Create key KEY_END`End key KEY_EXIT`Exit key KEY_FIND`Find key KEY_HELP`Help key KEY_MARK`Mark key KEY_MESSAGE`Message key KEY_MOVE`Move key KEY_NEXT`Next object key KEY_OPEN`Open key KEY_OPTIONS`Options key KEY_PREVIOUS`Previous object key KEY_REDO`Redo key KEY_REFERENCE`Reference key KEY_REFRESH`Refresh key KEY_REPLACE`Replace key KEY_RESTART`Restart key KEY_RESUME`Resume key KEY_SAVE`Save key KEY_SBEG`Shifted beginning key KEY_SCANCEL`Shifted cancel key KEY_SCOMMAND`Shifted command key KEY_SCOPY`Shifted copy key KEY_SCREATE`Shifted create key KEY_SDC`Shifted delete char key KEY_SDL`Shifted delete line key KEY_SELECT`Select key KEY_SEND`Shifted end key KEY_SEOL`Shifted clear line key KEY_SEXIT`Shifted exit key KEY_SFIND`Shifted find key KEY_SHELP`Shifted help key KEY_SHOME`Shifted home key KEY_SIC`Shifted input key KEY_SLEFT`Shifted left arrow key KEY_SMESSAGE`Shifted message key KEY_SMOVE`Shifted move key KEY_SNEXT`Shifted next key KEY_SOPTIONS`Shifted options key KEY_SPREVIOUS`Shifted prev key KEY_SPRINT`Shifted print key KEY_SREDO`Shifted redo key KEY_SREPLACE`Shifted replace key KEY_SRIGHT`Shifted right arrow KEY_SRSUME`Shifted resume key KEY_SSAVE`Shifted save key KEY_SSUSPEND`Shifted suspend key KEY_SUNDO`Shifted undo key KEY_SUSPEND`Suspend key KEY_UNDO`Undo key .TE .SK .SH "Function Prototypes" The following are declared as functions, and may also be defined as macros: .P \f4int addch(const chtype \f2ch\fP); .br \f4int addchstr(chtype *const \f2chstr\fP); .br \f4int addchnstr(chtype *const \f2chstr\fP, int \f2n\fP); .br \f4int addnstr(char *const \f2str\fP, int \f2n\fP); .br \f4int addstr(char *const \f2str\fP); .br \f4int addnwstr(wchar_t *const \f2wstr\fP, int \f2n\fP); .br \f4int addwstr(wchar_t *const \f2wstr\fP); .br \f4int add_wch(cchar_t *const \f2wch\fP); .br \f4int add_wchnstr(cchar_t *const \f2wchstr\fP, int \f2n\fP); .br \f4int add_wchstr(cchar_t *const \f2wchstr\fP); .br \f4int attroff(int \f2attrs\fP); .br \f4int attron(int \f2attrs\fP); .br \f4int attrset(int \f2attrs\fP); .br \f4attr_t attr_get(void); .br \f4int attr_off(attr_t \f2attrs\fP); .br \f4int attr_on(attr_t \f2attrs\fP); .br \f4int attr_set(attr_t \f2attrs\fP); .br \f4int baudrate(void); .br \f4int beep(void); .br \f4int bkgd(chtype \f2ch\fP); .br \f4void bkgdset(chtype \f2ch\fP); .br \f4void bkgrndset(cchar_t *const \f2wch\fP); .br \f4int bkgrnd(cchar_t *const \f2wch\fP); .br \f4int border(chtype \f2ls\fP, chtype \f2rs\fP, chtype \f2ts\fP, chtype \f2bs\fP, chtype \f2tl\fP, .br \f4chtype \f2tr\fP, chtype \f2bl\fP, chtype \f2br\fP); .br \f4int border_set(cchar_t *const \f2ls\fP, cchar_t *const \f2rs\fP, .br \f4cchar_t *const \f2ts\fP, cchar_t *const \f2bs\fP, .br \f4cchar_t *const \f2tl\fP, cchar_t *const \f2tr\fP, .br \f4cchar_t *const \f2bl\fP, cchar_t *const \f2br\fP); .br \f4int box(WINDOW *\f2win\fP, chtype \f2verch\fP, chtype \f2horch\fP); .br \f4int box_set(WINDOW *\f2win\fP, cchar_t *const \f2verch\fP, .br \f4cchar_t *const \f2horch\fP); .br \f4bool can_change_color(void); .br \f4int cbreak(void); .br \f4int chgat(int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP, void *const \f2opts\fP); .br \f4int clear(void); .br \f4int clearok(WINDOW *\f2win\fP, bool \f2bf\fP); .br \f4int clrtobot(void); .br \f4int clrtoeol(void); .br \f4int color_content(short \f2color\fP, short *\f2red\fP, short *\f2green\fP, .br \f4short *\f2blue\fP); .br \f4int COLOR_PAIR(int \f2n\fP); .br \f4int copywin(WINDOW * const \f2srcwin\fP, WINDOW *\f2dstwin\fP, int \f2sminrow\fP, .br \f4int \f2smincol\fP, int \f2dminrow\fP, int \f2dmincol\fP, int \f2dmaxrow\fP, .br \f4int \f2dmaxcol\fP, int \f2overlay\fP); .br \f4int curs_set(int \f2visibility\fP); .br \f4int def_prog_mode(void); .br \f4int def_shell_mode(void); .ne 5 \f4int delay_output(int \f2ms\fP); .br \f4int delch(void); .br \f4void delscreen(SCREEN *\f2sp\fP); .br \f4int delwin(WINDOW *\f2win\fP); .br \f4int deleteln(void); .br \f4WINDOW *derwin(WINDOW *\f2orig\fP, int \f2nlines\fP, int \f2ncols\fP, int \f2begin_y\fP, .br \f4int \f2begin_x\fP); .br \f4int doupdate(void); .br \f4WINDOW *dupwin(WINDOW *\f2win\fP); .br \f4int echo(void); .br \f4int echochar(const chtype \f2ch\fP); .br \f4int echo_wchar(cchar_t *const \f2wch\fP); .br \f4int endwin(void); .br \f4int erase(void); .br \f4char erasechar(void); .br \f4int erasewchar(wchar_t *\f2ch\fP); .br \f4void filter(void); .br \f4int flash(void); .br \f4int flushinp(void); .br \f4chtype getbkgd(WINDOW *\f2win\fP); .br \f4int getbkgrnd(cchar_t *\f2wch\fP); .br \f4int getcchar(cchar_t *const \f2wcval\fP, wchar_t *\f2wch\fP, attr_t *\f2attrs\fP, .br \f4short *\f2color_pair\fP, void *\f2opts\fP); .br \f4int getch(void); .br \f4int getnstr(char *\f2str\fP, int \f2n\fP); .br \f4int getn_wstr(wint_t *\f2wstr\fP, int \f2n\fP); .br \f4int getstr(char *\f2str\fP); .br \f4int get_wch(wint_t *\f2ch\fP); .br \f4WINDOW *getwin(FILE *\f2filep\fP); .br \f4int get_wstr(wint_t *\f2wstr\fP); .br \f4int halfdelay(int \f2tenths\fP); .br \f4bool has_colors(void); .br \f4bool has_ic(void); .br \f4bool has_il(void); .br \f4int hline(chtype \f2ch\fP, int \f2n\fP); .br \f4int hline_set(cchar_t *const \f2wch\fP, int \f2n\fP); .br \f4void idcok(WINDOW *\f2win\fP, bool \f2bf\fP); .br \f4int idlok(WINDOW *\f2win\fP, bool \f2bf\fP); .br \f4void immedok(WINDOW *\f2win\fP, bool \f2bf\fP); .br \f4chtype inch(void); .br \f4int inchnstr(chtype *\f2chstr\fP, int \f2n\fP); .br \f4int inchstr(chtype *\f2chstr\fP); .br \f4WINDOW *initscr(void); .br \f4int init_color(short \f2color\fP, short \f2red\fP, short \f2green\fP, short \f2blue\fP); .br \f4int init_pair(short \f2pair\fP, short \f2f\fP, short \f2b\fP); .br int innstr(char *\f2str\fP, int \f2n\fP); .br int innwstr(wchar_t *\f2wstr\fP, int \f2n\fP); .ne 5 int insch(chtype \f2ch\fP); .br int insdelln(int \f2n\fP); .br int insertln(void); .br int insnstr(char *const \f2str\fP, int \f2n\fP); .br int insstr(char *const \f2str\fP); .br int instr(char *\f2str\fP); .br int ins_nwstr(wchar_t *const \f2wstr\fP, int \f2n\fP); .br int ins_wch(cchar_t *const \f2wch\fP); .br int ins_wstr(wchar_t *const \f2wstr\fP); .br int intrflush(WINDOW *\f2win\fP, bool \f2bf\fP); .br int in_wch(cchar_t *\f2wcval\fP); .br int in_wchstr(cchar_t *\f2wchstr\fP); .br int in_wchnstr(cchar_t *\f2wchstr\fP, int \f2n\fP); .br int inwstr(wchar_t *\f2wstr\fP); .br bool isendwin(void); .br bool is_linetouched(WINDOW *\f2win\fP, int \f2line\fP); .br bool is_wintouched(WINDOW *\f2win\fP); .br char *keyname(int \f2c\fP); .br char *key_name(wchar_t \f2c\fP); .br int keypad(WINDOW *\f2win\fP, bool \f2bf\fP); .br char killchar(void); .br int killwchar(wchar_t *\f2ch\fP); .br int leaveok(WINDOW *\f2win\fP, bool \f2bf\fP); .br char *longname(void); .br int meta(WINDOW *\f2win\fP, bool \f2bf\fP); .br int move(int \f2y\fP, int \f2x\fP); .br int mvaddch(int \f2y\fP, int \f2x\fP, const chtype \f2ch\fP); .br int mvaddchnstr(int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP, int \f2n\fP); .br int mvaddchstr(int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP); .br int mvaddnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP); .br int mvaddnwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP); .br int mvaddstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP); .br int mvaddwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP); .br int mvadd_wch(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP); .br int mvadd_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP); .br int mvadd_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP); .br int mvchgat(int \f2y\fP, int \f2x\fP, int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP, .br void *const \f2opts\fP); .br int mvcur(int \f2oldrow\fP, int \f2oldcol\fP, int \f2newrow\fP, int \f2newcol\fP); .br int mvdelch(int \f2y\fP, int \f2x\fP); .br int mvderwin(WINDOW *\f2win\fP, int \f2par_y\fP, int \f2par_x\fP); .br int mvgetch(int \f2y\fP, int \f2x\fP); .ne 6 int mvgetnstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP); .br int mvgetn_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP); .br int mvgetstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP); .br int mvget_wch(int \f2y\fP, int \f2x\fP, wint_t *\f2ch\fP); .br int mvget_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP); .br int mvhline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP); .br int mvhline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP); .ne 5 chtype mvinch(int \f2y\fP, int \f2x\fP); .br int mvinchnstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP); .br int mvinchstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP); .br int mvinnstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP); .br int mvinnwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP); .br int mvinsch(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP); .br int mvinsnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP); .br int mvinsstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP); .br int mvinstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP); .br int mvins_nwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP); .br int mvins_wch(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP); .br int mvins_wstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP); .br int mvinwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP); .br int mvin_wch(int \f2y\fP, int \f2x\fP, cchar_t *\f2wcval\fP); .br int mvin_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP); .br int mvin_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP); .br int mvprintw(int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...); .br int mvscanw(int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...); .br int mvvline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP); .br int mvvline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP); .br int mvwaddch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, const chtype \f2ch\fP); .br int mvwaddchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP, .br int \f2n\fP); .br int mvwaddchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP); .br int mvwaddnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP); .br int mvwaddnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, .br int \f2n\fP); .br int mvwaddstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP); .br int mvwaddwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP); .br int mvwadd_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP); .br int mvwadd_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP, .br int \f2n\fP); .br int mvwadd_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP); .br int mvwchgat(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, int \f2n\fP, attr_t \f2attr\fP, .br short \f2color\fP, void *const \f2opts\fP); .br int mvwdelch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP); .br int mvwgetch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP); .br int mvwgetnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP); .br int mvwgetn_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP); .br int mvwgetstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP); .br int mvwget_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2ch\fP); .br int mvwget_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP); .br int mvwhline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP); .br int mvwhline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, .br int \f2n\fP); .br int mvwin(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP); .br chtype mvwinch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP); .br int mvwinchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP); .br int mvwinchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP); .br int mvwinnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP); .br int mvwinnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP); .ne 6 int mvwinsch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP); .br int mvwinsnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP); .br int mvwinsstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP); .br int mvwinstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP); .br int mvwins_nwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, .br int \f2n\fP); .br int mvwins_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP); .br int mvwins_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP); .br int mvwinwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP); .br int mvwin_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wcval\fP); .br int mvwin_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, .br int \f2n\fP); .br int mvwin_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP); .br int mvwprintw(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...); .br int mvwscanw(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...); .br int mvwvline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP); .br int mvwvline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, .br int \f2n\fP); .br int napms(int \f2ms\fP); .br WINDOW *newpad(int \f2nlines\fP, int \f2ncols\fP); .br SCREEN *newterm(char *\f2type\fP, FILE *\f2outfile\fP, FILE *\f2infile\fP); .br WINDOW *newwin(int \f2nlines\fP, int \f2ncols\fP, int \f2begin_y\fP, int \f2begin_x\fP); .br int nl(void); .br int nonl(void); .br int nocbreak(void); .br int nodelay(WINDOW *\f2win\fP, bool \f2bf\fP); .br int noecho(void); .br void noqiflush(void); .br int noraw(void); .br int notimeout(WINDOW *\f2win\fP, bool \f2bf\fP); .br int overlay(WINDOW * const \f2srcwin\fP, WINDOW *\f2dstwin\fP); .br int overwrite(WINDOW * const \f2srcwin\fP, WINDOW *\f2dstwin\fP); .br int pair_content(short \f2pair\fP, short *\f2f\fP, short *\f2b\fP); .br int PAIR_NUMBER(int \f2value\fP); .br int pechochar(WINDOW *\f2pad\fP, chtype *\f2ch\fP); .br int pecho_wchar(WINDOW *\f2pad\fP, cchar_t *const \f2wch\fP); .br int pnoutrefresh(WINDOW *\f2pad\fP, int \f2pminrow\fP, int \f2pmincol\fP, int \f2sminrow\fP, .br int \f2smincol\fP, int \f2smaxrow\fP, int \f2smaxcol\fP); .br int prefresh(WINDOW *\f2pad\fP, int \f2pminrow\fP, int \f2pmincol\fP, int \f2sminrow\fP, .br int \f2smincol\fP, int \f2smaxrow\fP, int \f2smaxcol\fP); .br int printw(char *\f2fmt\fP, ...); .br int putp(char *const \f2str\fP); .br int putwin(WINDOW *\f2win\fP, FILE *\f2filep\fP); .br void qiflush(void); .br int raw(void); .br int redrawwin(WINDOW *\f2win\fP); .br int refresh(void); .br int resetty(void); .br int reset_prog_mode(void); .br int reset_shell_mode(void); .br int ripoffline(int \f2line\fP, int (*\f2init\fP)(WINDOW *\f2win\fP, int \f2columns\fP)); .ne 6 int savetty(void); .br int scanw(char *\f2fmt\fP, ...); .br int scr_dump(char *const \f2filename\fP); .br int scr_init(char *const \f2filename\fP); .br int scrl(int \f2n\fP); .br int scroll(WINDOW *\f2win\fP); .br int scrollok(WINDOW *\f2win\fP, bool \f2bf\fP); .br int scr_restore(char *const \f2filename\fP); .br int scr_set(char *const \f2filename\fP); .br int setcchar(cchar_t *\f2wcval\fP, wchar_t *const \f2wch\fP, .br const attr_t \f2attrs\fP, short \f2color_pair\fP, .br void *const \f2opts\fP); .br int setscrreg(int \f2top\fP, int \f2bot\fP); .br SCREEN *set_term(SCREEN *\f2new\fP); .br int slk_attroff(const chtype \f2attrs\fP); .br int slk_attr_off(const attr_t \f2attrs\fP); .br int slk_attron(const chtype \f2attrs\fP); .br int slk_attr_on(const attr_t \f2attrs\fP); .br int slk_attrset(const chtype \f2attrs\fP); .br int slk_attr_set(const attr_t \f2attrs\fP); .br int slk_clear(void); .br int slk_init(int \f2fmt\fP); .br char *slk_label(int \f2labnum\fP); .br int slk_noutrefresh(void); .br int slk_refresh(void); .br int slk_restore(void); .br int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP); .br int slk_touch(void); .br int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP); .br int standend(void); .br int standout(void); .br int start_color(void); .br WINDOW *subpad(WINDOW *\f2orig\fP, int \f2nlines\fP, int \f2ncols\fP, int \f2begin_y\fP, .br int \f2begin_x\fP); .br WINDOW *subwin(WINDOW *\f2orig\fP, int \f2nlines\fP, int \f2ncols\fP, int \f2begin_y\fP, .br int \f2begin_x\fP); .br int syncok(WINDOW *\f2win\fP, bool \f2bf\fP); .br attr_t termattrs(void); .br char *termname(void); .br int tigetflag(char *\f2capname\fP); .br int tigetnum(char *\f2capname\fP); .br char *tigetstr(char *\f2capname\fP); .br void timeout(int \f2delay\fP); .br int touchline(WINDOW *\f2win\fP, int \f2start\fP, int \f2count\fP); .br int touchwin(WINDOW *\f2win\fP); .br char *tparm(char *\f2cap\fP, long \f2p1\fP, long \f2p2\fP, long \f2p3\fP, long \f2p4\fP, .br long \f2p5\fP, long \f2p6\fP, long \f2p7\fP, long \f2p8\fP, long \f2p9\fP); .br int typeahead(int \f2fildes\fP); .br int ungetch(int \f2ch\fP); .br int unget_wch(const wchar_t \f2wch\fP); .br int untouchwin(WINDOW *\f2win\fP); .br void use_env(char \f2boolvalue\fP); .br int vidattr(chtype \f2attr\fP); .br int vid_attr(attr_t \f2attr\fP); .br int vidputs(chtype \f2attr\fP, int (*\f2putfunc\fP)(int)); .br int vid_puts(attr_t \f2attr\fP, wint_t (*\f2putwfunc\fP)(wint_t)); .br int vline(chtype \f2ch\fP, int \f2n\fP); .br int vline_set(cchar_t *const \f2wch\fP, int \f2n\fP); .br int vwprintw(WINDOW *\f2win\fP, char *\f2fmt\fP, void *\f2varglist\fP); .br int vw_printw(WINDOW *\f2win\fP, char *\f2fmt\fP, void *\f2varglist\fP); .br int vwscanw(WINDOW *\f2win\fP, char *\f2fmt\fP, void *\f2varglist\fP); .br int vw_scanw(WINDOW *\f2win\fP, char *\f2fmt\fP, void *\f2varglist\fP); .br int waddch(WINDOW *\f2win\fP, const chtype \f2ch\fP); .br int waddchnstr(WINDOW *\f2win\fP, chtype *const \f2chstr\fP, int \f2n\fP); .br int waddchstr(WINDOW *\f2win\fP, chtype *const \f2chstr\fP); .br int waddnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP); .br int waddnwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP); .br int waddstr(WINDOW *\f2win\fP, char *const \f2str\fP); .br int waddwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP); .br int wadd_wch(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP); .br int wadd_wchnstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP); .br int wadd_wchstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP); .br int wattroff(WINDOW *\f2win\fP, int \f2attrs\fP); .br int wattron(WINDOW *\f2win\fP, int \f2attrs\fP); .br int wattrset(WINDOW *\f2win\fP, int \f2attrs\fP); .br attr_t wattr_get(WINDOW *\f2win\fP); .br int wattr_off(WINDOW *\f2win\fP, attr_t \f2attrs\fP); .br int wattr_on(WINDOW *\f2win\fP, attr_t \f2attrs\fP); .br int wattr_set(WINDOW *\f2win\fP, attr_t \f2attrs\fP); .br int wbkgd(WINDOW *\f2win\fP, chtype \f2ch\fP); .br void wbkgdset(WINDOW *\f2win\fP, chtype \f2ch\fP); .br int wbkgrnd(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP); .br void wbkgrndset(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP); .br int wborder(WINDOW *\f2win\fP, chtype \f2ls\fP, chtype \f2rs\fP, chtype \f2ts\fP, chtype \f2bs\fP, .br chtype \f2tl\fP, chtype \f2tr\fP, chtype \f2bl\fP, chtype \f2br\fP); .br int wborder_set(WINDOW *\f2win\fP, cchar_t *const \f2ls\fP, cchar_t *const \f2rs\fP, .br cchar_t *const \f2ts\fP, cchar_t *const \f2bs\fP, .br cchar_t *const \f2tl\fP, cchar_t *const \f2tr\fP, .br cchar_t *const \f2bl\fP, cchar_t *const \f2br\fP); .br int wchgat(WINDOW *\f2win\fP, int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP, .br void *const \f2opts\fP); .br int wclear(WINDOW *\f2win\fP); .br int wclrtobot(WINDOW *\f2win\fP); .br int wclrtoeol(WINDOW *\f2win\fP); .br void wcursyncup(WINDOW *\f2win\fP); .br int wdelch(WINDOW *\f2win\fP); .br int wdeleteln(WINDOW *\f2win\fP); .br int wechochar(WINDOW *\f2win\fP, const chtype \f2ch\fP); .br int wecho_wchar(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP); .br int werase(WINDOW *\f2win\fP); .br int wgetbkgrnd(WINDOW *\f2win\fP, cchar_t *\f2wch\fP); .ne 8 int wgetch(WINDOW *\f2win\fP); .br int wgetnstr(WINDOW *\f2win\fP, char *\f2str\fP, int \f2n\fP); .br int wgetn_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP, int \f2n\fP); .br int wgetstr(WINDOW *\f2win\fP, char *\f2str\fP); .br int wget_wch(WINDOW *\f2win\fP, wint_t *\f2ch\fP); .br int wget_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP); .br int whline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP); .br int whline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP); .br chtype winch(WINDOW *\f2win\fP); .br int winchnstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP, int \f2n\fP); .br int winchstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP); .br int winnstr(WINDOW *\f2win\fP, char *\f2str\fP, int \f2n\fP); .br int winnwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP, int \f2n\fP); .br int winsch(WINDOW *\f2win\fP, chtype \f2ch\fP); .br int winsdelln(WINDOW *\f2win\fP, int \f2n\fP); .br int winsertln(WINDOW *\f2win\fP); .br int winsnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP); .br int winsstr(WINDOW *\f2win\fP, char *const \f2str\fP); .br int winstr(WINDOW *\f2win\fP, char *\f2str\fP); .br int wins_nwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP); .br int wins_wch(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP); .br int wins_wstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP); .br int winwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP); .br int win_wch(WINDOW *\f2win\fP, cchar_t *\f2wcval\fP); .br int win_wchnstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP, int \f2n\fP); .br int win_wchstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP); .br int wmove(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP); .br int wnoutrefresh(WINDOW *\f2win\fP); .br int wprintw(WINDOW *\f2win\fP, char *\f2fmt\fP, ...); .br int wredrawln(WINDOW *\f2win\fP, int \f2beg_line\fP, int \f2num_lines\fP); .br int wrefresh(WINDOW *\f2win\fP); .br int wscanw(WINDOW *\f2win\fP, char *\f2fmt\fP, ...); .br int wscrl(WINDOW *\f2win\fP, int \f2n\fP); .br int wsetscrreg(WINDOW *\f2win\fP, int \f2top\fP, int \f2bot\fP); .br int wstandend(WINDOW *\f2win\fP); .br int wstandout(WINDOW *\f2win\fP); .br void wsyncdown(WINDOW *\f2win\fP); .br void wsyncup(WINDOW *\f2win\fP); .br void wtimeout(WINDOW *\f2win\fP, int \f2delay\fP); .br int wtouchln(WINDOW *\f2win\fP, int \f2y\fP, int \f2n\fP, int \f2changed\fP); .br wchar_t *wunctrl(cchar_t *\f2wc\fP); .br int wvline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP); .br int wvline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);\f1 .SH "APPLICATION USAGE" In order to support historical applications that include .Hd curses.h and use .Hd varargs.h the following interfaces using va_list are declared as having a third argument of type .CR "(void *)" : .CR vw_printw() , .CR vw_scanw() , .CR vwprintw() , .CR vwscanw() . .SH "SEE ALSO" (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is completely rewritten to include new constants, data types and function prototypes. .\" .\" index@<\f4curses.h\f1> \- definition for screen handling and optimisation functions@@@\f3curses(5)\f1 .\" .\" toc@\f3curses(5)\f1:\0\0\f4curses\f1@@@definition for screen handling and optimisation functions .\" .\" fileset_database@curses.5 CURS-ENG-A-MAN .\" $Header: dirent.5,v 72.4 94/11/15 09:57:30 ssa Exp $ .TA d .TH dirent 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dirent.h \- format of directory streams and directory entries .SH SYNOPSIS .B #include .br .B #include .SH DESCRIPTION This header file defines data types used by the directory stream routines described in .IR directory (3C). .PP The following data types are defined: .RS .TP 15 .SM .B DIR A structure containing information about an open directory stream. .TP .B struct dirent A structure defining the format of entries returned by the .I readdir function (see .IR directory (3C)). .RE .PP The .B struct dirent structure includes the following members: .RS .PP .TS l l. char d_name[MAXNAMLEN+1]; /* name of directory entry */ ino_t d_ino; /* file serial number */ short d_namlen; /* length of string in d_name */ short d_reclen; /* length of this record */ .TE .RE .PP The constant .SM .B MAXNAMLEN is defined in .RB < dirent.h >. .PP Note that the .B d_reclen entry is used internally to represent the offset from the current entry to the next valid entry. Therefore, .B d_reclen is not the length of the current entry, but the length of the current record where a record is an entry plus any currently unused space between the current entry and the next valid entry. The unused space between valid .B dirent entries results from changes in a directory's contents, such as the deletion of files and other directories. .PP This file also contains external declarations for the functions in the .IR directory (3C) package. .SH AUTHOR .I dirent.h was developed by AT&T and HP. .SH "SEE ALSO" directory(3C), ndir(5). .SH STANDARDS CONFORMANCE .RC < dirent.h ">: AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4dirent.h\f1 \- format of directory streams and directory entries@@@\f3dirent(5)\f1 .\" index@format of directory streams and directory entries@@@\f3dirent(5)\f1 .\" index@directory streams and directory entries, format of@@@\f3dirent(5)\f1 .\" index@streams, directory, format of@@@\f3dirent(5)\f1 .\" index@directory entries and directory streams, format of@@@\f3dirent(5)\f1 .\" index@entries, directory, format of@@@\f3dirent(5)\f1 .\" .\" toc@\f3dirent(5)\f1:\0\0\f4dirent.h\f1@@@format of directory streams and directory entries .\" .\" fileset_database@dirent.5 SYS-ADMIN-MAN .\" $Header: dld.sl.5,v 78.1 96/02/12 13:40:47 ssa Exp $ .TA d .TH dld.sl 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dld.sl \- dynamic loader .SH DESCRIPTION The .C /usr/lib/dld.sl program is the dynamic loader. In programs that use shared libraries, .C /usr/lib/dld.sl is invoked automatically at startup time by the startup file .CR crt0.o . Identical copies of .CR crt0.o are kept in both .C /opt/langtools/lib/ and .C /usr/ccs/lib/ directories. The dynamic loader is, itself, a shared library, although it defines no symbols for use by user programs. .SS Shared Libraries Shared libraries are executable files created with the .C -b option to .C ld (see .IR ld (1)). They must contain position-independent code .SM (PIC) that can be mapped anywhere in the address space of a process and executed with minimal relocation. .SM PIC can use .SM PC\c -relative addressing modes and/or linkage tables. It can be generated with the .C +z/+Z options to the compilers. See the .CR +help option to .IR ld (1) or the .I Programming on HP-UX manual for details on writing .SM PIC in assembly language. .SS Incomplete Executables An executable program linked with one or more shared libraries is called an .BR "incomplete executable" . .PP When creating an executable .RC ( a.out ) file from object files and libraries, the linker does not copy text (code) or data from the shared library into the output file. Instead, the dynamic loader maps the library into the address space of the process at run time. The linker binds all program references to shared library routines and data to entries in a linkage table, and relies on the dynamic loader to fill in the linkage table entries once the libraries have been mapped. This linkage table serves as a jump table for function calls. .PP In previous releases, shared library data items referenced by the program were copied into the program executable file so that the data references could be resolved statically. Beginning with the Series 700/800 10.0 release, references to shared library data from the .BR a.out are included in a linkage table and are resolved at run time. .SS Loading An incomplete executable contains a list of path names of the shared libraries searched at link time. At run time, the dynamic loader attaches to the process all shared libraries that were linked with the program. The dynamic loader will attempt to load each library from the same directory in which it was found at link time. It is possible to change the shared library run time search path by specifying a dynamic path list. There are two ways to specify a dynamic path list : .TP \(bu by storing a directory path list in the executable using the .C +b path_list option to .C ld .TP \(bu by linking the executable with .C ld option .C +s, enabling the executable to use the path list defined by the .C SHLIB_PATH environment variable at run time .PP The path list is a list of one or more path names separated by colons (:). The dynamic path list will work only for libraries specified with the .C -l option to .C ld. However, it can be enabled for libraries specified with a full path name using the .C -l option to .C chatr (see .IR chatr (1)). If both .C +s and .C +b are used, their relative order on the command line indicates which path list will be searched first. See the .C +help option to .IR ld (1) or the .I Programming on HP-UX manual for more details. .PP The text segment of a library is shared among all processes that use it. The data and bss segments are shared on a page-by-page basis. When a process first accesses (reads or writes) a data or bss page, a copy of that page is made for the process. .SS Binding The dynamic loader also resolves symbolic references between the executable and libraries. By default, function calls are trapped via the linkage table and bound on first reference. References to data symbols and other absolute address references cannot be trapped. They are bound on the first resolution of a function call that could potentially reference the object. .PP If the .C -B immediate option to .C ld is used, the loader binds all necessary references at startup time. This increases the startup cost of a program, but ensures that no more binding operations will be required later. Thus, better real-time response may result, and the risk of a later abort due to unresolved externals is eliminated. .PP The .C fastbind tool can be used to improve the start-up time of programs that use shared libraries (incomplete executables). The .C fastbind tool performs analysis on the shared library routines and data used to bind the symbols and stores this information in the executable file. The dynamic loader will notice that this information is available, and it will use this fastbind information to bind the symbols instead of the standard search method. For more details refer to .IR fastbind (1) and the .CR +help option to .IR ld (1) or the .I Programming on HP-UX manual. .SS Version Control Since code from a shared library is mapped at run time from a separate shared library file, modifications to a shared library may alter the behavior of existing executables. In some cases, this may cause programs to operate incorrectly. Two means of version control is provided to solve this problem. .SS 1. Intra-Library Versioning Whenever an incompatible change is made to a library interface, both versions of the affected module or modules are included in the library. A mark indicating the date (month/year) the change was made is recorded in the new module via the pragma .C HP_SHLIB_VERSION in C, or the compiler directive .C SHLIB_VERSION in Fortran and Pascal. This date applies to all symbols defined within the module. A high water mark giving the date of the latest incompatible change is recorded in the shared library, and the high water mark for each library linked with the program is recorded in the incomplete executable file. At run time, the dynamic loader checks the high water mark of each library and loads the library only if it is at least as new as the high water mark recorded at link time. When binding symbolic references, the loader chooses the latest version of a symbol that is not later than the high water mark recorded at link time. These two checks help ensure that the version of each library interface used at run time is the same as was expected at link time. Intra-library versioning may be removed in a future release. .SS 2. Library-level Versioning The second way for users to version their libraries is by using a new naming convention, .B libname.n where .B n is a numeral that is incremented with every new release of the library. When using the new naming scheme, users must specify an internal name for the shared library by using the .C +h internal_name option to .C ld when building the shared library. This internal name is recorded in each incomplete executable or shared library that links with the shared library. .PP At run time, the loader will look at the library list recorded in the incomplete executable file or shared library. For each library in the list that was not an internal name, the dynamic loader will look for a .C .0 version of the library (e.g. .C libname.0 ) to load. If it does not find this version, it will look for the library name that is recorded in the list. .SS Explicit Loading And Binding The duties of the dynamic loader as described above are all performed automatically, although they can be controlled somewhat by appropriate options to .CR ld . The dynamic loader can also be accessed programmatically. The reserved variable .CR _\|_dld_loc , which is defined in .CR crt0.o , points to a jump table within the dynamic loader. The routines described under .IR shl_load (3X) provide a portable interface that allows the programmer to explicitly attach a shared library to the process at run time, to calculate the addresses of symbols defined within shared libraries, and to detach the library when done. .SH DIAGNOSTICS If the dynamic loader is not present, or cannot be invoked by the process for any reason, an error message is printed to standard error and the process terminates with a non-zero exit code. .PP Normally, the operation of the dynamic loader is visible only when there is a fatal error of some kind. In these cases, an error message is printed to standard error and a .C SIGABRT signal is sent to the process. These errors fall into two basic categories: errors in attaching a shared library, and errors in binding symbols. The former can occur only at process startup time but the latter can occur at any time during process execution unless the .C -B immediate option is used with .CR ld . Possible errors that can occur while attaching a shared library include library not present, library not executable, library corrupt, high water mark too low, or insufficient room in the address space for the library. Possible errors that can occur while binding symbols include symbol not found (unresolved external), or library corrupt. .PP When using the explicit load facilities of the dynamic loader, these types of errors are not considered fatal. Consult .IR shl_load (3X) for information on error handling. .SH WARNINGS The startup cost of the dynamic loader is significant, even with deferred binding, and can cause severe performance degradation in processes dominated by startup costs (such as simple ``hello world'' programs). In addition, position-independent code is usually slower than normal code, so performance of a program may be adversely affected by the presence of .SM PIC in shared libraries. However, the advantages of decreased disk space usage and decreased memory requirements for executables should outweigh these concerns in most cases. .PP There are rare cases where the behavior of a program differs when using shared libraries as opposed to archive libraries. This happens primarily when relying on undocumented and unsupported features of the compilers, assembler, and linker. See the .CR +help option to .IR ld (1) or the .I Programming on HP-UX manual for more details. .PP The library developer is entirely responsible for version control and must be thorough in identifying incompatible changes to library interfaces. Otherwise, programs may malfunction unexpectedly with later versions of the library. There is little an application user can do if version control is not handled properly by the library developer. The application developer can usually resolve problems by modifying the source code to use the new interfaces then recompiling and relinking against the new libraries. .PP By default, most warnings are not reported by the dynamic loader. If you wish to see all of the messages, set the environment variable .CR _HP_DLDOPTS to contain one or more options. The following options are supported: .RS .TP 17 .CR -warnings Display additional dynamic loader warning messages. Some of these include: .RS .TP 2 \(bu Symbols of the same name but different types, such as CODE and DATA. See the .CR WARNINGS section in .IR ld (1) for more details on this warning. .TP \(bu Using certain flags or routines described in .IR shl_load (3X). .RE .TP .CR -fbverbose See .IR fastbind (1). .TP .CR -nofastbind See .IR fastbind (1). .RE .SH AUTHOR The .CR /usr/lib/dld.sl program was developed by HP. .SH SEE ALSO .PD .SS System Tools: .TP 18 as(1) translate assembly code to machine code .PD 0 .TP CC(1) invoke the HP-UX C++ compiler .TP cc(1) invoke the HP-UX C compiler .TP chatr(1) change program's internal attributes .TP f77(1) invoke the HP-UX FORTRAN compiler .TP fastbind(1) invoke the fastbind tool .TP ld(1) invoke the link editor .TP pc(1) invoke the HP-UX Pascal compiler .PD .SS Miscellaneous: .TP 18 a.out(4) assembler, compiler, and linker output .PD 0 .TP crt0(3) execution startup routine .TP shl_load(3X) load/unload shared libraries .PD .SS Texts and Tutorials .TP 18 .IR "HP-UX Linker and Libraries Online User Guide" (See the .CR +help option to .IR ld (1)) .TP .IR "Programming on HP-UX" (See .IR manuals (5) for ordering information) .PD .\" .\" index@\f4dld.sl\f1 \- dynamic loader@@@\f3dld.sl(5)\f1 .\" index@\f1dynamic loader@@@\f3dld.sl(5)\f1 .\" index@\f1loader, dynamic@@@\f3dld.sl(5)\f1 .\" .\" toc@\f3dld.sl(5)\f1:\0\0\f4dld.sl\f1@@@dynamic loader .\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" The following carried over when renamed from .5dts to .5 ...\" $Log: dts_audit_events.5,v $ ...\" Revision /main/1 1995/03/08 02:07 UTC arh ...\" Add OSF doc sources. ...\" ...\" Revision 1.1.2.4 1994/10/19 14:16:08 willie ...\" {enh, 10234, R1.1} ...\" Incorporated edit pass. ...\" [1994/10/19 14:15:40 willie] ...\" ...\" enh, 10234, R1.1} ...\" Incorporated edit pass. ...\" ...\" Revision 1.1.3.3 1994/10/19 14:15:40 willie ...\" {enh, 10234, R1.1} ...\" Incorporated edit pass. ...\" ...\" Revision 1.1.2.3 1994/10/11 21:02:40 willie ...\" {enh, 10234, R1.1} ...\" [DIncorporatefinal review comments. ...\" [1994/10/11 21:02:16 willie] ...\" ...\" Revision 1.1.3.2 1994/10/11 21:02:16 willie ...\" {enh, 10234, R1.1} ...\" [DIncorporatefinal review comments. ...\" ...\" Revision 1.1.2.2 1994/09/16 20:32:33 hal ...\" Corrected cross references to audit files. ...\" [1994/09/16 20:32:13 hal] ...\" ...\" Revision 1.1.3.2 1994/09/16 20:32:13 hal ...\" Corrected cross references to audit files. ...\" ...\" Revision 1.1.2.1 1994/09/16 20:03:19 hal ...\" New file name; old was dts_audit_events.5dts (but was in 5 directory). ...\" Also added .zA .zZ markers to page ...\" {1.1.,enh,10234} ...\" [1994/09/16 20:03:02 hal] ...\" ...\" Revision 1.1.1.2 1994/09/16 20:03:02 hal ...\" New file name; old was dts_audit_events.5dts (but was in 5 directory). ...\" Also added .zA .zZ markers to page ...\" {1.1.,enh,10234} ...\" ...\" Revision 1.1.2.3 1994/08/29 19:56:52 bmoy ...\" Added index entries. ...\" [1994/08/29 19:56:40 bmoy] ...\" ...\" Revision 1.1.2.2 1994/06/13 18:39:41 devobj ...\" cr10872 - fix copyright ...\" [1994/06/13 18:37:49 devobj] ...\" ...\" Revision 1.1.2.1 1994/05/10 01:32:36 willie ...\" {enh, R1.1] ...\" New refpage. Partially reviewed. ...\" [1994/05/10 01:31:10 willie] ...\" ...\" $EndLog$ ...\" .rm zA .rm zZ .TH dts_audit_events "5" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "enh,10234,R1.1,new manpage." .iX "events" "auditable" .iX "events" "time services" .iX "time services" "auditable events" .iX "auditable events" "time services" .iX "events" "\*Ldts_audit_events\*O" .iX "\*Ldts_audit_events\*O" .SH NAME \*Ldts_audit_events\*O - Auditable events for the time services .SH "DESCRIPTION" .PP Code is in place for auditing security-significant events in the Time Server. Among these events are: .iX "events" "time service processes" .iX "events" "clock readings" .iX "events" "global-set membership" .iX "events" "time service attributes" .iX "Cell Service Profile" "global-set membership" .iX "Time Server" "time service processes" .iX "Time Server" "clock readings" .iX "Time Server" "global-set membership" .iX "Time Server" "time service attributes" .ML .LI Time Service processes .LI Clock readings .LI Global-set membership (in the Cell Service Profile) .LI Time Service attributes .LE .PP .iX "event class" "definitions" .iX "event class" "auditing execution" Event class definitions, together with filters, control the auditing execution at these code points. Filters can be updated dynamically. Filter files are maintained by a per-host audit daemon, and are shared among all the audit clients on the same host. The .iX "commands" "\*Ldcecp\*O command" .iX "\*Ldcecp\*O command" \*Ldcecp\*O command interface program is used for maintaining the filters. (See the \*Ldcecp\*O reference page.) The \*Ldcecp\*O .iX "commands" "\*Ldcecp\*O command" command is executable by all users and system administrators. The control on who is allowed to modify filters .iX "ACL" "\*Ldts_audit_events\*O" .iX "\*Ldts_audit_events\*O" "ACL" is done through audit daemon's ACL, which maintains the filters. .PP .iX "Time Server" "Time Service" .iX "Time Service" "Time Server" The Time Server RPC interfaces that manage the Time Service and .iX "Time Server" "\*Ltime_control\*O" .iX "Time Server" "\*Ltime_service\*O" .iX "Time Server" "\*Lgbl_time_service\*O" .iX "Time Server" "\*Ltime_provider\*O" .iX "\*Ltime_control\*O" "Time Server" .iX "\*Ltime_service\*O" "Time Server" .iX "\*Lgbl_time_service\*O" "Time Server" .iX "\*Ltime_provider\*O" "Time Server" request and provide the time include \*Ltime_control\*O, \*Ltime_service\*O, \*Lgbl_time_service\*O, and \*Ltime_provider\*O. .PP The following are the audit code points in these Time Service .iX "Time Service" "Event Types" .iX "Time Service" "Event Classes" .iX "Time Service" "Even-Specific Information" interfaces, with their Event Types, Event Classes, and any Event-Specific Information. .SS "Control Interface (time_control) Operations" .iX "Time Service" "interfaces" The \*LCreateCmd(\|)\*O operation creates the Time Service as a server or a clerk. The caller must have write access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_CREATE_CMD (0x200, dce_dts_mgt_modify)\*O .VL .LI "Event-Specific Information" .iS signed32 servType .iE .LE .LE .PP The \*LDeleteCmd(\|)\*O operation deletes the Time Service entity from the system where the command is entered. This command stops the process. The caller must have write access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_DELETE_CMD (0x201, dce_dts_mgt_modif)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP .iX "DTS entity" The \*LEnableCmd(\|)\*O operation starts the DTS entity on the local node. This command makes the server available to the network. The \*VclockSet\*O argument tells the Time Service whether or not to set the clock after the first synchronization. The caller must have write access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_ENABLE_CMD (0x202, dce_dts_mgt_modify)\*O .VL .LI "Event-Specific Information" .iS signed32 clockSet .iE .LE .LE .PP The \*LDisableCmd\*O operation disables the Time Service by making it unavailable to the network. In the case of servers, it makes it unavailable to the RPC client trying to talk to it. For clerks, it stops synchronizing with servers. The caller must have write access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_DISABLE_CMD (0x203, dce_dts_mgt_modify)\*O .VL .LI "Event-Specific Information" None .LE .LE The \*LUpdateCmd(\|)\*O operation gradually adjusts the clock on the local node to the specified time. The caller must have write access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_UPDATE_CMD (0x204, dce_dts_synch)\*O .VL .LI "Event-Specific Information" .iS utc_t old_time utc_t new_time .iE .LE .LE .PP The \*LChangeCmd\*O operation changes the epoch number on the server and optionally sets the time to a new time. These values are passed in the argument \*VchangeDir\*O. The caller must have write access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_CHANGE_CMD (0x205, dce_dts_synch)\*O .VL .LI "Event-Specific Information" .iS signed32 old_epoch signed32 new_epoch utc_t old_time utc_t new_time .iE .LE .LE .PP The \*LSynchronizeCmd(\|)\*O operation causes the Time Service to synchronize immediately. If the argument \*VclockSet\*O is true, the clock is set to the new value after a synchronization. The caller must have write access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_SYNCHRONIZE_CMD (0x206, dce_dts_synch)\*O .VL .LI "Event-Specific Information" .iS signed32 setClock .iE .LE .LE .PP The \*LAdvertiseCm(\|)\*O operation adds (advertises) this Time Server node as a member of the global set in the Cell Services Profile. The caller must have write access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_ADVERTISE_CMD (0x207, dce_dts_mgt_modify)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP The \*LUnadvertiseCmd(\|)\*O operation removes (unadvertises) this Time Server node as a member of the set of global servers in the Cell Services profile. The caller must have write access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_UNADVERTISE_CMD (0x208, dce_dts_mgt_modify)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP The \*LSetDefaultCmd(\|)\*O operation, when an attribute with no accompanying value is passed, sets an attribute to its default value. The attribute type is passed in the \*VsetAttr\*O argument. The caller must have write access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_SET_DEFAULT_CMD (0x209, dce_dts_mgt_modify)\*O .VL .LI "Event-Specific Information" .iS byte useDefault signed32 attribute .iE .LE .LE .PP The \*LSetAttrCmd(\|)\*O operation, when an attribute and an accompanying value is passed, sets an attribute to a value given. The attribute type is passed in \*VsetAttr\*O argument and the attribute value in \*VAttrValue\*O argument. The caller must have write access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_SET_ATTR_CMD (0x20A, dce_dts_mgt_modif)\*O .VL .LI "Event-Specific Information" .iS signed32 attribute signed32 attribute_type .iE .LE .LE .PP The \*LShowAttrCmd(\|)\*O operation, when passed an attribute name, queries the Time Service for the attribute's value. The attribute value is passed back in the argument \*VattrValue\*O. The caller must have read access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_SHOW_ATTR_CMD (0x20B, dce_dts_mgt_query)\*O .VL .LI "Event-Specific Information" .iS signed32 attribute signed32 attribute_type .iE .LE .LE .PP The \*LShowAllCharsCmd(\|)\*O operation, when not passed a group name with the \*Lall\*O value, queries the Time Service for the values of all the characteristic attributes and values. The caller must have read access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_SHOW_ALL_CHARS_CMD (0x20C, dce_dts_mgt_query)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP The \*LShowAllStatusCmd(\|)\*O operation, when passed the \*Lall status\*O value, queries the Time Service for the values of all the status attributes. The caller must have read access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_SHOW_ALL_STATUS_CMD (0x20D, dce_dts_mgt_query)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP The \*LShowAllCntrsCmd(\|)\*O operation, when passed the \*Lall counters\*O value, queries the Time Service for the values of all the counters. The caller must have read access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_SHOW_ALL_CNTRS_CMD (0x20E, dce_dts_mgt_query)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP The \*LShowLocServersCmd(\|)\*O operation, when passed the \*Llocal servers\*O value, queries the Time Service for the servers in the local set. A variable conformant array is used to return the set of local servers available. The size of the array transmitted over RPC is determined at run-time. The caller must have read access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_SHOW_LOC_SERVERS_CMD (0x20F, dce_dts_mgt_query)\*O .VL .LI "Event-Specific Information None .LE .LE .PP The \*LShowGblServersCmd(\|)\*O operation, when passed the \*Lglobal servers\*O value, queries the Time Service for the servers in the global set. A variable conformant array is used to return the set of global servers available. The caller must have read access to the management interface. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_SHOW_GBL_SERVERS_CMD (0x210, dce_dts_mgt_query)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP .SS "Time Provider Interface (time_provider) Operations" .iX "Time Provider" "interfaces" Auditable events in the RPC-based Time Provider Program (TPP) interfaces are defined here. These events are invoked by a Time Service daemon running as a server (in this case it makes an RPC client call to the TPP server). .PP The \*LContactProvider(\|)\*O operation sends initial contact message to the TPP. The TPP server responds with a control message. This operation may cause modification of the time server's (not the provider's) clock and should be defined to be an auditable event in the time server. There is no access control in the provider for this operation, but the integrity of the messages is protected. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_CONTACT_PROVIDER (0x211, dce_dts_time_provider)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP The \*LServerRequestProviderTime(\|)\*O operation has the client send a request to the TPP for times. The TPP server responds with an array of time stamps obtained by querying the Time Provider hardware that it polls. There is no access control in the Time Provider for this operation, but the integrity of the message is protected. .VL .LI "Event Type (Event Number, Event Classes)" \*LEVT_REQUEST_PROVIDER_TIME (0x212, dce_dts_time_provider)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP .SH RELATED INFORMATION Commands: \*Ladvertise(1m)\*O, \*Laud(1m)\*O, \*Laudfilter(1m)\*O, \*Lchange(1m)\*O, \*Lcreate(1m)\*O, \*Ldcecp(1m)\*O. \*Ldelete(1m)\*O, \*Ldisable(1m)\*O, \*Ldts_intro(1m)\*O, \*Ldtsd(1m)\*O, \*Lenable(1m)\*O, \*Lexit(1m)\*O, \*Lhelp(1m)\*O, \*Lquit(1m)\*O, \*Lset(1m)\*O, \*Lshow(1m)\*O, \*Lsynchronize(1m)\*O, \*Lunadvertise(1m)\*O, \*Lupdate(1m)\*O, .sp .4v Files: \*Levent_class.5\*O, \*Lsec_audit_events(5)\*O. .zZ "enh,10234,R1.1,new manpage." .\" $Header: environ.5,v 72.8 94/11/30 15:43:12 ssa Exp $ .TA e .TH environ 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME environ - user environment .SH DESCRIPTION An array of strings called the .I environment is made available by .IR exec (2) when a process begins. By convention, these strings have the form .IB name = value\f1. The following names are used by various commands (listed in alphabetical order): .TP 12 .SM HOME Name of the user's login directory, set by .IR login (1) from the password file (see .IR passwd (4)). .TP 12 .SM LANG Identifies the user's requirements for native language, local customs and coded character set, if the environment variables .SM "LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, and .SM LC_TIME are unset or null. .IP The format of LANG is: .IP \s-1LANG\s0=\f2language\f1[_\f2territory\f1][.\f2codeset\f1] .IP The valid values for LANG are supported locales. (see .IR lang (5)). Native Language Support (NLS) is initiated at run-time by calling .IR setlocale (3C). The following call to .I setlocale binds the execution of a program to the user's language requirements: .IP setlocale(LC_ALL,""); .IP This .I setlocale call initializes the program locale from the environment variables associated with .IR setlocale . .SM LANG provides the necessary defaults if any of the category-specific environment variables are not set or set to the empty string. .IP The .SM LANG environment variable can have a maximum length of SL_NAME_SIZE bytes (see header file .RB < locale.h >). .TP .SM LANGOPTS Defines language options for mode and data order in the form: .IP \s-1LANGOPTS\s0=[\f2mode\f1][\|\f3_\f2order\f1] .IP .SM LANGOPTS values are given in English as an .SM ASCII character string. .I mode describes the mode of a file where .B l (ell) represents Latin mode and .B n represents non-Latin mode. Non-Latin mode is assumed for values other than .B l and .BR n . .I order describes the data order of a file where .B k is keyboard order and .B s is screen order. .TP .SM LC_ALL Determines the values for all locale categories. The value of .SM LC_ALL has precedence over any of the other environment variables .SM "LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME, and .SM LANG . .TP \s-1LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC,\s0 and \s-1LC_TIME\s0 determines the user's requirements for language, territory, and codeset with respect to character collation, character classification and conversion, output messages, currency symbol and monetary value format, numeric data presentation, and time formats, respectively. If LC_ALL and any of these are not defined in the environment, .SM LANG provides the defaults. .IP Syntax for the environment variables .SM "LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, and .SM LC_TIME is: .IP \f2language\f1[\|\f3_\f2territory\f1][\|\f3.\f2codeset\f1][\|\f3@\f2modifier\f1\] .IP The \f2language\f1 field conforms with ISO 639 standard for language names and the \f2territory\f1 field conforms with the ISO 3166 territory names. For a list of the locale names, see .IR lang (5). .IP The \f3@\f2modifier\f1 field allows the user to select between more than one value of a category within the same language definition. HP-UX does not currently provide locales with modifiers. .IP The values of the locale categories are determined by a precedence order; the first condition met below determines the value: .IP 1. If the LC_ALL environment variable is defined and is not null, the value of LC_ALL is used. .IP 2. If the LC_* environment variable (LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME) is defined and is not null, the value of the environment variable is used to initialize the category that corresponds to the environment variable. .IP 3. If the LANG environment variable is defined and is not null, the value of the LANG environment variable is used. .IP 4. If the LANG environment variable is not set or is set to the empty string, the POSIX/C default locale is used. (see .IR lang (5)) .TP .SM LC_COLLATE Determines the locale category for character collation. It determines collation information for regular expressions and sorting, including equivalence classes and multi-character collating elements, in various utilities and .IR strcoll (3C) and .IR strxfrm (3C) . .TP .SM LC_CTYPE Determines the locale category for character classification (such as alphabetic, digit, upper-case. See .IR isalpha (3C) , .IR isdigit (3C) , and .IR isupper (3C)) , character conversion. (see .IR toupper (3C) , .IR tolower (3C)) , and the interpretation of text as single-byte or multi-byte characters, .TP .SM LC_MESSAGES Determines the locale category for processing affirmative and negative responses and the language and cultural conventions in which diagnostic and informative messages should be written. It may also affect the behavior of .IR catopen (3C) in determining the message catalog to open. .TP .SM LC_MONETARY Determines the locale category for monetary-related numeric formatting information. .TP .SM LC_NUMERIC Determines the locale category for numeric formatting information (such as the thousands separator and the radix character) in various utilities as well as the formatted I/O operations in .IR printf (3S) and .IR scanf (3S) and the string conversion functions in .IR strtod (3C) . .TP .SM LC_TIME Determines the locale category for date and time formatting information. It affects the behavior of time functions in .IR strftime (3C) . .TP .SM MANPATH Contains a colon-separated list of directory prefixes to be searched by .IR man (1) for manual entries. Upon logging in, .B /etc/profile (or .BR /etc/csh.login ) sets .BR \s-1MANPATH\s0=/usr/share/man:/usr/contrib/man:usr/local/man . .IP .SM MANPATH uses the same syntax as the .SM PATH environment variable, with the addition of recognizing the specifiers .BR %L , .BR %l , .BR %t , and .BR %c as used in the .SM NLSPATH environment variable. See .SM NLSPATH below for a description of these specifiers. This provides a way to specify paths to locale-specific manual entries. .IP It is assumed that each of the prefixes given in .SM MANPATH contain subdirectories of the form .BR man\(**, .BR man\(**.Z, .BR cat\(** and .BR cat\(**.Z. (see .IR man (1) , .IR catman (1M) , and .IR fixman (1M)). .TP .SM NLSPATH Contains a sequence of pseudo-pathnames used by .IR catopen (3C) when attempting to locate message catalogs. Each pseudo-pathname contains a name template consisting of an optional path prefix, one or more substitution field descriptors, a file name and an optional file name suffix. For example: .IP \f3 \s-1NLSPATH\s0="/system/nlslib/%N.cat"\f1 .IP defines that .IR catopen (3C) should look for all message catalogs in the directory .C /system/nlslib , where the catalog name should be constructed from the .I name parameter passed to .IR catopen (3C) (%N) with the suffix .BR .cat . .IP Field descriptors consist of a .B % followed by a single character. Field descriptors and their substitution values are: .RS 15 .TP 8 .B %N The value of the .I name parameter passed to .IR catopen (3C). .PD 0 .TP .B %L The value of .SM LC_MESSAGES. .TP .B %l The .I language element from .SM LC_MESSAGES. .TP .B %t The .I territory element from .SM LC_MESSAGES. .TP .B %c The .I codeset element from .SM LC_MESSAGES. .TP .B %% Replaced by a single .BR % . .PD .RE .IP For example, given: .RS .IP .B \h'.5i'\s-1NLSPATH\s0="/system/nlslib/%L/%N.cat" .RE .IP .IR catopen (3C) attempts to open the file .B /system/nlslib/\s-1$LC_MESSAGES\s0/\f2name\fP.cat as a message catalog. .IP A null string is substituted if the specified value is not defined. Separators are not included in .B %t and .B %c substitutions. Note that a default value is not supplied for .BR %L . If .SM LC_MESSAGES is not set and .SM NLSPATH had the value in the previous example, .IR catopen (3C) would attempt to open the file .B /system/nlslib/\f2name\fP.cat as a message catalog. .IP Path names defined in .SM NLSPATH are separated by colons .RB ( : ). A leading colon or two adjacent colons .RB ( :: ) is equivalent to specifying .BR %N . For example, given: .IP .B \h'.5i'\s-1NLSPATH\s0=":%N.cat:/nlslib/%L/%N.cat" .IP .IR catopen (3C) with the .I oflag parameter set to .C NL_CAT_LOCALE will attempt to open the following files in the indicated order: \&\f3./\f2name\f1, \&\f3./\f2name\fP\f3.cat\f1, and \f3/nlslib/\s-1$LC_MESSAGES\s0/\f2name\f3.cat\f1. The first file successfully opened is taken as the message catalog. .IP A default pseudo-pathname defined by the system is effectively appended to .SM NLSPATH and used by .IR catopen (3C) whenever a message catalog cannot be opened in any of the user defined pseudo-pathnames. This system-wide default path is: .IP .B " /usr/lib/nls/msg/%L/%N.cat:/usr/lib/nls/%l/%t/%c/%N.cat" .TP .SM PAGER .SM PAGER indicates the paginator through which output from certain commands is piped. Its value must be a string specifying the complete command line of the desired paginator. Two examples are: .RS .IP .B \s-1PAGER\s0="more -cs" .IP .B \s-1PAGER\s0="pg -c" .RE .IP .SM PAGER affects several commands, including .IR man (1) and the interactive mailers. Some of the affected commands provide alternate means of selecting a pager in case there is a conflict. See the individual manual entries for details. .TP .SM PATH .SM PATH indicates the sequence of directory prefixes that .IR sh (1), .IR time (1), .IR nice (1), .IR nohup (1), and others search when looking for a file known by an incomplete path name. Prefixes are separated by colons .RB ( : ). .IR Login (1) sets .SM \f3PATH=\s0:/usr/bin\f1. .TP .SM TERM .SM TERM identifies the kind of terminal for which output is to be prepared. This information is used by commands such as .IR vi (1) and .IR mm (1), which can exploit special capabilities of that terminal. .TP .SM TZ .SM TZ sets time zone information. .SM TZ can be set using the format: .RS 15 .IP [\f3:\f1]\f3\s-1STD\s0\f2offset\f1[\f3\s-1DST\s0\f1[\f2offset\f1][\f3,\f2rule\f1]] .PP where: .RS 3 .TP 12 .BR \s-2STD\s0 " and " \s-2DST\s0 Three or more bytes that designate the standard time zone .RB ( \s-2STD\s0 ) and summer (or daylight-savings) time zone .RB ( \s-2DST\s0 ) .SM .B STD is required. If .SM .B DST is not specified, summer time does not apply in this locale. Any characters other than digits, comma .RB ( , ), minus .RB ( \- ), plus .RB ( + ), or .SM ASCII NUL are allowed. .TP .I offset .I offset is the value that must be added to local time to arrive at Coordinated Universal Time .SM (UTC). .I Offset is of the form : .IP \f2hh\f1[\f3:\f2mm\f1[\f3:\f2ss\f1]] .IP Hour .RI ( hh ) is any value from 0 through 23. The optional minutes .RI ( mm ) and seconds .RI ( ss ) fields are a value from 0 through 59. The hour field is required. If .I offset is preceded by a .BR \- , the time zone is east of the Prime Meridian. A .B + preceding .I offset indicates that the time zone is west of the Prime Meridian. The default case is west of the Prime Meridian. .TP .I rule .I rule indicates when to change to and from summer (daylight-savings) time. The .I rule has the form : .IP \f2date\f3/\f2time\f3,\|\f2date\f3/\f2time\f1 .IP where the first .IB date / time specifies when to change from standard to summer time, and the second .IB date / time specifies when to change back. The .I time field is expressed in current local time. .IP The form of .I date should be one of the following : .RS 15 .TP 8 .BI J n Julian day .I n (1 through 365). Leap days are not counted. February 29 cannot be referenced. .TP .I n The zero-based Julian day (0 through 365). Leap days are counted. February 29 can be referenced. .TP .I Mm.n.d The .I d day (0 through 6) of week .I n (1 through 5) of month .I m (1 through 12) of the year. Week 5 refers to the last day .I d of month .I m. Week 1 is the week in which the first day of the month falls. Day 0 is Sunday. .TP .I time .I Time has the same format as .I offset except that no leading sign ("\-" or "+") is allowed. The default, if .I time is not given, is 02:00:00. .RE .TP 12 \| While the .SM STD field and the offset field for .SM STD must be specified, if the .SM DST field is also provided, the system will supply default values for other fields not specified. These default values come from file .B /usr/lib/tztab (see .I tztab(4)), and, in general, reflect the various historical dates for start and end of summer time. .RE .RE .PP Additional names may be placed in the environment by the .I export command and "name=value" arguments in .IR sh (1), or by .IR exec (2). It is unwise to add names that conflict with the following shell variables frequently exported by .B .profile files: .SM .BR MAIL , .SM .BR PS1 , .SM .B PS2 and .SM .BR IFS . .PP The environment of a process is accessible from C by using the global variable: .IP .B char \(**\(**environ; .PP which points to an array of pointers to the strings that comprise the environment. The array is terminated by a null pointer. .SH WARNINGS Some .SM HP-UX commands and library routines do not use the .SM "LANG, LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC, LC_TIME," or .SM LANGOPTS environment variables. Some commands do not use message catalogs, so .SM NLSPATH does not affect their behavior. See the .SM EXTERNAL INFLUENCES section of specific commands and library routines for implementation details. .SH NOTES Coordinated Universal Time .SM (UTC) is equivalent to Greenwich Mean Time .SM (GMT). .SH AUTHOR .I Environ was developed by .SM AT&T and .SM HP. .SH SEE ALSO env(1), login(1), sh(1), exec(2), catopen(3C), ctime(3C), getenv(3C), setlocale(3C), profile(4), lang(5), term(5), tztab(4). .SH STANDARDS CONFORMANCE .CR environ ": AES, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f2environ\f1 \- user environment variables@@@\f3environ(5)\f1 .\" index@environment variables, user@@@\f3environ(5)\f1 .\" index@user environment variables@@@\f3environ(5)\f1 .\" index@variables, user environment@@@\f3environ(5)\f1 .\" .\" toc@\f3environ(5)\f1:\0\0\f2environ\f1@@@user environment .\" .\" fileset_database@environ.5 SYS-ADMIN-MAN ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" .rm zA .rm zZ .TH event_class "5" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "enh,10234,R1.1,new manpage." .iX "event class" .iX "event class file" .iX "files" "event class" .SH NAME \*Levent class file\*O - The file that contains the declaration of an event class. .SH "DESCRIPTION" .PP Audit events can be logically grouped into \*Levent classes\*O. Event classes are defined in event class files. An event class file contains an event class number and a list of event numbers corresponding to audit events. .P All event class files must be created in the \*Vdcelocal\*O\*L/etc/audit/ec\*O directory. .P The name of the event class file becomes the name of the event class. The recommended naming convention for event class files is: .iX "event class file" "naming convention" .P \*Ldce_\*O\*Vserver-name\*O_\*Vclass\*O .P where \*Vclass\*O is a descriptive text that characterizes the event class. .P Event class files must be write-protected by the local operating system (that is, only administrators should have write access to these files). Audit clients read these files to maintain an event table in their address space. .P Optionally, an event class file can contain a \*LSEP line\*O. .iX "event class file" "SEP line" .iX "SEP line" "event class file" This line contains a list of prefixes of the event numbers in the file. The SEP line speeds up the scanning performed by the Audit clients. .iX "client" "Audit" Audit clients which do not have events with one of the prefixes listed will not scan the event list. If the SEP line is not provided in the file, Audit clients will have to read the entire file to find out if the event class file contains any of their events. .P Empty lines are ignored in the event class file. .P Comments are designated by the number sign (#) placed before the comment text. .iX "event class file" "format" .SS "The Event Class File Format" .P The format of an event class file is: .sS \*LECN=\*Vevent_class_number\*L .sE .sS \*LSEP=\*Vprefix_1 prefix_2 ...\*L .sE .sS \*L#\*V comments start with the number sign .sE .sS \*Vevent_number_1 .sE .sS event_number_2\*O .sE .SH "EXAMPLES" Following is an example of an event class file for the event class \*Lec_local_authentication\*O: .oS ECN = 0x00000001 SEP = 0x100 # AS_Request 0x00000100 # TGS_TicketReq 0x00000101 # TGS_RenewReq 0x00000102 # TGS_ValidateReq 0x00000103 .oE .zZ "enh,10234,R1.1,new manpage." .\" $Header: fcntl.5,v 72.7 94/11/15 09:57:33 ssa Exp $ .TA f .TH fcntl 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fcntl \- file control options .SH SYNOPSIS .C "#include " .PP .C "#include " .SH DESCRIPTION The .CR fcntl() function provides for control over open files. The .CR include file describes .I requests and .I arguments to .CR fcntl() and .CR open() . See .IR fcntl (2) and .IR open (2). .PP The access modes set by .CR open() and accessed by .CR fcntl() are: .RS .TP 25 .C O_RDONLY .PD 0 .TP .C O_WRONLY .TP .C O_RDWR .RE .PD .PP The mask for file access modes is: .RS .TP 25 .C O_ACCMODE .RE .PP The file status flags set by .CR open() or .CR fcntl() and accessed by .CR fcntl() are: .RS .TP 25 .C O_NDELAY Nonblocking I/O. .PD 0 .TP .C O_NONBLOCK POSIX-style nonblocking I/O. .TP .C O_APPEND Append (writes guaranteed at the end). .TP .C O_DSYNC Write through cache for data. .TP .C O_SYNC Write through cache for data and attributes. .TP .CR O_RSYNC|O_DSYNC Write through cache for data on reads and writes. .TP .CR O_RSYNC|O_SYNC Write through cache for data and attributes on reads and writes. .PD .RE .PP The flag .CR O_SYNCIO is a synonym for .CR O_SYNC and is defined for backward compatibility in .CR . .PP The flag values accessible only to .CR open() are: .RS .TP 25 .C O_CREAT Open with file create (uses third open arg). .PD 0 .TP .C O_TRUNC Open with truncation. .TP .C O_EXCL Exclusive open. .TP .C O_NOCTTY Do not assign a controlling terminal. .RE .PD .ifn .bp .PP The requests for .CR fcntl() are: .RS .TP 25 .C F_DUPFD Duplicate file descriptor. .PD 0 .TP .C F_GETFD Get file descriptor flags. .TP .C F_SETFD Set file descriptor flags. .TP .C F_GETFL Get file flags. .TP .C F_SETFL Set file flags. .TP .C F_GETLK Get blocking file lock. .TP .C F_SETLK Set or clear file locks and fail on busy. .TP .C F_SETLKW Set or clear file locks and wait on busy. .RE .PD .PP The file descriptor flag for .CR F_GETFD , .CR F_SETFD is: .RS .TP 25 .C FD_CLOEXEC .RE .PP The file segment locking control structure .CR "struct flock" , includes the following members: .RS .TP 25 .CR "short l_type;" .CR "/* F_RDLCK, F_WRLCK or F_UNLCK */" .PD 0 .TP .CR "short l_whence;" .CR "/* Flag - see lseek(2) */" .TP .CR "off_t l_start;" .CR "/* Relative offset in bytes */" .TP .CR "off_t l_len;" .CR "/* Size; if 0 then until EOF */" .TP .CR "pid_t l_pid;" .CR "/* By F_GETLK - process holding lock */" .RE .PD .PP The file segment locking types are: .RS .TP 25 .C F_RDLCK Read lock. .PD 0 .TP .C F_WRLCK Write lock. .TP .C F_UNLCK Remove locks. .RE .PD .SH SEE ALSO fcntl(2), open(2). .SH STANDARDS CONFORMANCE .RC < fcntl.h ">: AES, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4fcntl\f1 \- file control options@@@\f3fcntl(5)\f1 .\" index@\f1file control options for open files@@@\f3fcntl(5)\f1 .\" index@\f1open files, file control options for@@@\f3fcntl(5)\f1 .\" index@\f1options, file control for open files@@@\f3fcntl(5)\f1 .\" .\" toc@\f3fcntl(5)\f1@@@file control options\f1 .\" $Header: fs_wrapper.5,v 72.4 94/11/29 05:53:39 ssa Exp $ .TA f .TH fs_wrapper 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fs_wrapper \- configuration and binary files used by file system administration commands .SH SYNOPSIS .CR ff .RC [ -F .IR FStype ]\ ... .PP .CR fsck .RC [ -F .IR FStype ]\ ... .PP .CR fsdb .RC [ -F .IR FStype ]\ ... .PP .CR labelit .RC [ -F .IR FStype ]\ ... .PP .CR mkfs .RC [ -F .IR FStype ]\ ... .PP .CR mount .RC [ -F .IR FStype ]\ ... .PP .CR ncheck .RC [ -F .IR FStype ]\ ... .PP .CR newfs .RC [ -F .IR FStype ]\ ... .PP .CR quot .RC [ -F .IR FStype ]\ ... .PP .CR quotacheck .RC [ -F .IR FStype ]\ ... .PP .CR volcopy .RC [ -F .IR FStype ]\ ... .SH DESCRIPTION The commands listed in the SYNOPSIS can operate on different types of file systems. Each command (except for .CR mount ) reads file system specific configuration files that control the command's behavior, and invokes a file system specific binary file to do the actual work. .I FStype is the file system type as optionally specified on the command line. If .I FStype is not given, then the file system type is determined from .CR /etc/fstab by matching an entry in this file with a device .CR special provided with the command (see individual commands for details of usage). .PP Administrators may also define a default file system type for the above commands via the file .CR /etc/default/fs . If this file exists, and contains the line: .IP .CI LOCAL= FStype .PP (e.g., .CR LOCAL=hfs ), then the above commands will assume the .I FStype given in .CR /etc/default/fs , unless an .I FStype is provided on the command line or is in .CR /etc/fstab . The default file system specification is provided to maintain compatibility with pre-10.0 invocations of the commands. .PP See the FILES section for a list of the files used. .SH WARNINGS The configuration files .CI /sbin/lib/mfsconfig.d/ FStype are supplied by HP or by other file system vendors. They are not meant to be edited by System Administrators. Corruption or removal of these files may lead to strange behavior, including the inability to boot. .PP The format of the configuration file is subject to change. .PP The file system specific binary files are not normally executed directly. However, if the configuration files become unusable, direct execution of these binary files may be a useful step in repairing and running the system again. The binary files accept the same arguments as the commands by which they are executed. .PP The .CR mount command is a special case. This command currently does not read a configuration file, and does not execute a file system specific binary file if .I FStype is .CR cdfs , .CR hfs , .CR nfs , or .CR lofs . The binary that handles these .IR FStype s also processes other .IR FStype s and calls the file system specific command if appropriate. .PP For historical reasons, the .CR hfs binary files also handle .CR nfs and .CR cdfs , so there are no separate binary files for the latter two file systems. .PP The commands (except .CR mount ) will not work if they are renamed, because they are symbolically linked to a single executable .RC ( /sbin/fs_wrapper ). .ift .br .ift .ne 8 .SH FILES .I FStype is the file system type as optionally specified on the command line. .I command is the name of the command. .TP 40 .CI /sbin/fs/ FStype / command File system specific binary files for the .CR fsck , .CR fsdb , .CR mkfs , .CR mount , and .CR newfs commands. There may be additional file system specific binary files in this directory that are not associated with .CR fs_wrapper . .TP .CI /usr/lbin/fs/ FStype / command File system specific binary files for the remaining commands. There may also be other file system specific binary files in this directory that are not associated with .CR fs_wrapper . .TP .CI /sbin/lib/mfsconfig.d/ FStype Configuration files for each file system type. .TP .C /etc/default/fs File in which the default file system type can be defined. If this file does not exist, there is no default file system type. .TP .C /etc/fstab Static information about the file systems .SH SEE ALSO ff(1M), fsck(1M), fsdb(1M), mkfs(1M), mount(1M), ncheck(1M), newfs(1M), quot(1M), quotacheck(1M), volcopy(1M), fstab(4). .\" .\" toc@\f3fs_wrapper(5)\f1@@@configuration and binary files used by file system administration commands\f1 .\" .\" index@\f4fs_wrapper\f1 \- configuration and binary files used by file system administration commands@@@\f3fs_wrapper(5)\f1 .\" index@\f1configuration files used by file system administration commands@@@\f3fs_wrapper(5)\f1 .\" index@\f1binary files used by file system administration commands@@@\f3fs_wrapper(5)\f1 .\" index@\f1file system administration commands, configuration and binary files@@@\f3fs_wrapper(5)\f1 .\" index@\f1administration commands, file system configuration and binary files@@@\f3fs_wrapper(5)\f1 .\" index@\f1commands, file system administration configuration and binary files@@@\f3fs_wrapper(5)\f1 .\" index@\f1files, configuration and binary, file system administration@@@\f3fs_wrapper(5)\f1 ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" ...\" .rm zA .rm zZ .TH group_override "5" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "group_override command" .iX "commands " "group_override" .iX "registry" "local overrides" .iX "registry database override" "files" .SH NAME \*Lgroup_override\*O - The registry group override file. .SH "SYNOPSIS" .sS \*Vdcelocal\*L/etc/group_override\*O .sE .SH "DESCRIPTION" .PP The \*Vdcelocal\*L/etc/group_override\*O administrative file lets you override group UNIX IDs and member lists stored in the network registry database. The \*Lgroup_override\*O file functions in a similar manner as the \*Lpasswd_override\*O file that overrides principal information in the network registry database. The override takes effect when you run \*Lpasswd_export\*O. It may also impact local security mechanisms of vendor specific implementations. .PP The \*Lgroup_override\*O file is stored on each machine. Any changes you make to it are in effect for the local machine only, and have no effect on the centralized registry. You may find \*Lgroup_override\*O especially useful for overriding the default group definitions supplied with the registry if they do not match your local UNIX system's group definitions. .SS "The group_override File Format" The format of \*Lgroup_override\*O entries is similar to the entries in the UNIX group file. The format is as follows: .sS \*Vgroup_name\*L:\*Vpasswd\*L:\*Vgroup_uid\*L:\*Vmembers\*O .sE .PP In the override entry, \*Vgroup_name\*O and \*Vgroup_uid\*O are keyfields. You must enter one to identify the group to which the override applies. The keyfield is used to perform a lookup in the override file. The lookup is performed in order as the fields are specified in the entry: first by group name, then by group UNIX ID. If you specify both keyfields in an override entry, the \*Vgroup_name\*O is used as the lookup key; subsequent fields are used as overrides. .SS "Field Descriptions" .PP Each entry in the \*Vgroup_override\*O file is described below. .PP .VL .LI "\*Vgroup_name\*O" A keyfield that contains the name that identifies the group to which the override applies. .LI "\*Vpasswd\*O" The encrypted password. If you specify an override in this field, the password you enter is in effect for this local machine only. .PP You can also specify \*LOMIT\*O in the \*Vpasswd\*O field to disallow using the \*Lnewgrp\*O command on the local machine to change a user's group identification. The use of \*LOMIT\*O in conjunction with an option to the \*Lpasswd_export\*O command also prevents the inclusion of this group in the group file created by \*Lpasswd_export\*O. (See the section entitled "Using OMIT," later in this command reference, for details.) .LI "\*Vgroup_uid\*O" A group UNIX ID. This field can function as a keyfield, when no other keyfields are entered, or as a field containing an override, when entered in conjunction with \*Vgroup_name\*O. When used as an override, this field specifies the ID to be used for the group on the local machine. .LI "\*Vmembers\*O" A comma-separated list of members of the group. The contents of this field override information in the registry when \*Lpasswd_export\*O creates an \*L/etc/group\*O file. Note that to specify a null membership, as opposed to indicating no override is required, use an asterisk (*) for this field. .LE .SS "Leaving Fields Blank" .PP If you do not want to override an item, leave its field blank, separating each blank field with a colon (:). Note that to override a group with a null membership list, enter an asterisk (*) for the \*Vmembers\*O field. .SS "Using OMIT" .PP If you enter either the word \*LOMIT\*O or another invalid password string (such as an asterisk or \*LNO GOOD\*O) in the \*Vpasswd\*O field, users will not be able to issue a \*Lnewgrp\*O to this group on the local machine. If you specify \*LOMIT\*O and run \*Lpasswd_export\*O with the \*L-x\*O option, the named group will not appear in the \*L/etc/group\*O file produced by \*Lpasswd_export\*O. .PP You should also be aware that, if you have omitted groups from the \*L/etc/group\*O file, information about those groups will not be available to any programs that use the group file. For example, the \*Lls -lg\*O command accesses the group file to obtain further information about a group. If the group is omitted, no group entry will exist and no information will be available. For this reason you should use \*LOMIT\*O to omit groups from the \*L/etc/group\*O file only if your user community is very large and either of the following conditions occur: .ML .LI The \*Lgroup\*O file is taking up too much space. .LI Group-ID-to-name mapping is too slow (during \*Lls -lg\*O, for example). .LE .SH "EXAMPLES" .AL .LI To assign the group named "kmem" a group ID of 3 on the local machine, the entry in the \*Lgroup_override\*O file is as follows: .oS kmem::3: .oE .LI To override the membership list of the group named "system" so that it contains only the single member named "root," the entry is as follows: .PP .oS system:::root .oE .PP .LE .SH "RELATED INFORMATION" .PP Command: \*Lpasswd_export(1m)\*O .\" $Header: hier.5,v 74.1 95/02/25 12:06:28 ssa Exp $ .TA h .TH hier 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hier \- file system hierarchy .SH DESCRIPTION .PP The HP-UX file system is a hierarchical tree organized for administrative convenience. Within the file-system tree structure, distinct areas are provided for files that are private to one machine, files that can be shared by machines, and home directories. .PP There are two types of files that are shared: those that can be shared by multiple machines of a common architecture, and those that can be shared by all machines. This organization allows sharable files to be stored on one machine (the server), but accessed by many machines (clients). .PP The following diagram illustrates the file system layout. Note that there are many directories that are not is this diagram, but are discussed below. .PP .ti +15 .B "Diagram of Directory Layout" .ifn \{ .nf |---- dev | |---- bin |---- etc | |---- bin | |---- ccs ------| |---- usr ------| |---- lib / ----| |---- lib |---- sbin | | |---- sbin |---- var | | |---- lbin |---- home | | |---- include |---- dict |---- opt | | | |---- share -----|---- lib |---- (export) | |---- man .fi \} .ift \{ .nf .C " |---- dev " .C " | |---- bin " .C " |---- etc | |---- bin " .C " | |---- ccs ------ | " .C " |---- usr ------ | |---- lib " .C " / --- | |---- lib " .C " |---- sbin | " .C " | |---- sbin " .C " |---- var | " .C " | |---- lbin " .C " |---- home | " .C " | |---- include |---- dict" .C " |---- opt | | " .C " | |---- share ----- |---- lib " .C " |---- (export) | " .C " |---- man " .fi \} .PP The following listing discusses a representative HP-UX directory hierarchy. Some HP-UX applications may add additional directories, which are not shown. .TP 25 \f4/\f1 Root directory. .TP \f4/dev\f1 Special files (block and character device files); see .IR mknod (1M). .TP \f4/etc\f1 Host-specific configuration and administration databases. .TP \f4/etc/opt\f1 Directory for application-specific configuration files. (Configuration information for optional packages.) .TP \f4/etc/rc.config.d\f1 Startup configuration files. .TP \f4/export\f1 Default root of exported file systems. Server only. .TP \f4/home\f1 Default root for user directories. .TP \f4/lost+found\f1 Storage directory for connecting detached files; for use by .IR fsck (1M). .TP \f4/mnt\f1 Mounting point for local file systems. .TP \f4/net\f1 Mounting point for remote file systems. .TP \f4/opt\f1 Root of subtree for optional application packages. .TP \f4/sbin\f1 Essential system commands. Essential commands are defined as executables that are needed to boot the system and mount the file systems. A full complement of utilities is available only after .CR /usr is mounted. .TP \f4/sbin/init.d\f1 Startup and shutdown scripts. .TP \f4/sbin/rc0.d\f1 Link files to scripts in .CR /sbin/init.d for entering or leaving run level 0. .TP \f4/sbin/rc1.d\f1 Link files to scripts in .CR /sbin/init.d for entering or leaving run level 1. .TP \f4/sbin/rc2.d\f1 Link files to scripts in .CR /sbin/init.d for entering or leaving run level 2. .TP \f4/sbin/rc3.d\f1 Link files to scripts in .CR /sbin/init.d for entering or leaving run level 3. .TP \f4/stand\f1 Standalone binaries and kernel configuration files. .TP \f4/tmp\f1 System-generated temporary files; generally cleared during the boot operation. .TP \f4/usr\f1 Mount point for sharable user and system administration commands, libraries and documentation. .TP \f4/usr/bin\f1 Primary location for common utilities and user commands. .TP \f4/usr/ccs\f1 C compilation system. Tools and libraries used to generate C programs. .TP \f4/usr/ccs/bin\f1 Development binaries; includes \f4cc\f1, \f4make\f1, \f4strings\f1, etc. .TP \f4/usr/ccs/lib\f1 Development libraries. .TP \f4/usr/ccs/lbin\f1 Development backends. .TP \f4/usr/conf\f1 Kernel configuration files. .TP \f4/usr/contrib\f1 Directory for user-contributed (unsupported, internal) commands, files, etc. Files in this directory come from outside the local site or organization (for example, from users groups or HP service engineers). .TP \f4/usr/contrib/bin\f1 User-contributed commands. .TP \f4/usr/contrib/include\f1 User-contributed include files. .TP \f4/usr/contrib/lib\f1 User-contributed libraries. .TP \f4/usr/contrib/man\f1 User-contributed man pages. .TP \f4/usr/include\f1 Included header files, for C and other programs. Some subdirectories are listed below. .TP \f4/usr/include/machine\f1 Machine-specific C include files. .TP \f4/usr/include/nfs\f1 C include files for Network File System (NFS). .TP \f4/usr/include/sys\f1 Kernel related C-language header files. .TP \f4/usr/lbin\f1 Directory for backend executables to other commands. A backend executable is an executable that is generally not invoked directly by the user. .TP \f4/usr/lib\f1 Program libraries, object code and architecture-dependent databases. .TP \f4/usr/lib/nls\f1 Directory for Native Language Support. .TP \f4/usr/local\f1 Directory for site-local commands, files, etc. Files under this directory come from inside the local site or organization. See \f4/usr/contrib\f1 for non-local unsupported commands and files. .TP \f4/usr/local/bin\f1 Site-local commands. .TP \f4/usr/local/lib\f1 Site-local libraries. .TP \f4/usr/local/man\f1 Site-local man pages. .TP \f4/usr/newconfig\f1 Default operating system configuration data files. This directory is a directory hierarchy mirroring .CR / . New versions of customizable configuration files and databases are shipped here so as not to overwrite current versions. Files in this directory are copied to regular locations for newly installed systems. System administrators may wish to keep them for later reference. .TP \f4/usr/old\f1 Files and programs that are being phased out or are obsolete. .TP \f4/usr/sbin\f1 System administration commands. .TP \f4/usr/share\f1 Architecture-independent sharable files. .TP \f4/usr/share/dict\f1 Dictionaries for \f4spell\f1 and \f4ispell\f1. .TP \f4/usr/share/lib\f1 Miscellaneous sharable libraries. .TP \f4/usr/share/man\f1 Online documentation. .TP \f4/var\f1 Root of subtree for "varying" files. These are files that are created at runtime and can grow to an arbitrary size. Some examples include log, temporary, transient, and spool files. .TP \f4/var/adm\f1 System administrative files, such as log files and accounting files. Some of the subdirectories are listed below. .TP \f4/var/adm/crash\f1 For saving kernel crash dumps. .TP \f4/var/adm/cron\f1 Directory for .IR cron (1M) queuing. .TP \f4/var/adm/sw\f1 Default location for software distribution depot. .TP \f4/var/adm/syslog\f1 Log files generated by \f4syslog\f1. See .IR syslog (3C) and .IR syslogd (1M). .TP \f4/var/mail\f1 Incoming mail. .TP \f4/var/news\f1 Local-system news articles for .IR news (1). .TP \f4/var/opt\f1 Root of subtree for varying files associated with optional software packages. .TP \f4/var/preserve\f1 Place where .IR ex (1) and .IR vi (1) save lost edit sessions until recovered. .TP \f4/var/run\f1 Files created when daemons are running. For example, the process ID (PID) file for \f4syslogd\f1, \f4syslog.pid\f1, is put here. .TP \f4/var/spool\f1 Miscellaneous directories for printer spooling, mail delivery, .IR cron (1M), etc. .TP \f4/var/spool/cron\f1 .IR cron (1M) and .IR at (1) spooling files. .TP \f4/var/spool/lp \f1 Printer spool files. .TP \f4/var/spool/mqueue\f1 Outgoing mail and log files containing messages from the mail system. .TP \f4/var/spool/uucp\f1 UUCP spool directory. .TP \f4/var/tmp\f1 Application-generated temporary files. This directory generally is not cleared between system reboots. .TP \f4/var/uucp\f1 UUCP administration files. .SH DEPENDENCIES Some directories include commands or files not supported on all HP-UX implementations. .SH SEE ALSO find(1), grep(1), ls(1), whereis(1). .\" index@\f4hier\f1 \- file system hierarchy@@@\f3hier(5)\f1 .\" index@file system: file system hierarchy@@@\f3hier(5)\f1 .\" index@hierarchy, file system@@@\f3hier(5)\f1 .\" .\" toc@\f3hier(5)\f1:\0\0\f4hier\f1@@@file system hierarchy .\" $Header: hostname.5,v 76.1 95/06/20 14:23:52 ssa Exp $ .\" Copyright (c) 1987 The Regents of the University of California. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms are permitted .\" provided that the above copyright notice and this paragraph are .\" duplicated in all such forms and that any documentation, .\" advertising materials, and other materials related to such .\" distribution and use acknowledge that the software was developed .\" by the University of California, Berkeley. The name of the .\" University may not be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" @(#)hostname.7 6.4 (Berkeley) 1/16/90 .\" .TA h .TH hostname 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hostname \- host name resolution description .SH DESCRIPTION Hostnames are domains. A domain is a hierarchical, dot-separated list of subdomains. For example, the machine .CR monet , in the .CR Berkeley subdomain of the .CR EDU subdomain of the Internet Domain Name System would be represented as .IP .C monet.Berkeley.EDU .PP (with no trailing dot). .PP Hostnames are often used with network client and server programs, which must generally translate the name to an address for use. (This task is usually performed by the library routine .IR gethostbyname (3).) .PP When NIS or the host table is being used for hostname resolution, the hostname is looked up without modification. When DNS is used, the resolver may append domains to the hostname. .PP The default method for resolving hostnames by the Internet name resolver is to follow .CR RFC .CR 1535 's security recommendations. Actions can be taken by the administrator to override these recommendations and to have the resolver behave the same as earlier, non-RFC 1535 compliant resolvers. .PP The default method (using RFC 1535 guidelines) follows: .PP If the name consists of a single component, i.e. contains no dot, and if the environment variable .CR HOSTALIASES is set to the name of a file, that file is searched for a string matching the input hostname. The file should consist of lines made up of two strings separated by white-space, the first of which is the hostname alias, and the second of which is the complete hostname to be substituted for that alias. If a case-insensitive match is found between the hostname to be resolved and the first field of a line in the file, the substituted name is looked up with no further processing. .PP If there is at least one dot in the name, then the name is first tried as is. The number of dots to cause this action is configurable by setting the threshold using the .CR ndots option in .CR /etc/resolv.conf (default: .CR 1 ). If the name ends with a dot, the trailing dot is removed, and the remaining name is looked up (regardless of the setting of the 'ndots' option) and no further processing is done. .PP If the input name does not end with a trailing dot, it is looked up by searching through a list of domains until a match is found. If neither the search option in the .CR /etc/resolv.conf file or the .CR LOCALDOMAIN environment variable is used, then the search list of domains contains only the full domain specified by the domain option (in .CR /etc/resolv.conf ) or the domain used in the local hostname (see .IR resolver (4)). For example, if the .CR domain option is set to .IR CS.Berkeley.EDU , then only CS.Berkeley.EDU will be in the search list and will be the only domain appended to the partial hostname, .IR lithium , making .CR lithium.CS.Berkeley.EDU the only name to be tried using the search list. .PP If the search option is used in .CR /etc/resolv.conf or the environment variable, .CR LOCALDOMAIN , is set by the user, then the search list will include what is set by these methods. For example, if the .CR search option contained .IP .C CS.Berkeley.EDU CChem.Berkeley.EDU Berkeley.EDU .PP then the partial hostname (e.g., .IR lithium ) will be tried with each domain name appended (in the same order specified). The resulting hostnames that would be tried are: .IP .C lithium.CS.Berkeley.EDU .br .C lithium.CChem.Berkeley.EDU .br .C lithium.Berkeley.EDU .PP The environment variable .CR LOCALDOMAIN overrides the .CR search and .CR domain options, and if both options are present in the resolver configuration file, then only the last one listed is used (see .IR resolver (5)). .PP If the name was not previously tried ``as is'' (i.e., it fell below the .CR ndots threshold or did not contain a dot), then the name, as originally provided, is attempted. .SH AUTHOR .CR hostname was developed by the University of California, Berkeley. .SH SEE ALSO gethostbyname (3), resolver (4), named (1M), RFC 1535 . .\" .\" index@\f4hostname\f1 \- host name resolution description@@@\f3hostname(5)\f1 .\" index@\f1host name resolution description@@@\f3hostname(5)\f1 .\" index@\f1description, host name resolution@@@\f3hostname(5)\f1 .\" .\" toc@\f3hostname(5)\f1:\0\0\f4hostname\f1@@@host name resolution description .\" .\" $Header: hpnls.5,v 72.4 94/07/03 14:45:09 ssa Exp $ .TA h .TH hpnls 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hpnls \- HP Native Language Support (NLS) Model .SH DESCRIPTION Native Language Support (NLS) reduces or eliminates the barriers that would otherwise make HP-UX difficult to use in a non-English-speaking work environment. NLS is available at the user-command level as well as through commands and libraries that can be used to develop international software applications. .PP Many existing C library routines have been modified to operate based upon a program's locale. A locale is the run-time NLS environment of a program which is loaded by .CR setlocale() . See .IR setlocale (3C) for a list of primary library routines that are affected by .CR setlocale . .PP In addition to routines that operate based on the program's locale, there are also commands and routines to provide a messaging system for accessing program messages based on the language requirements of the end-user. .PP Many HP-UX commands have been modified to operate in a manner sensitive to the language requirements of the end-user. These language requirements are established through the internationalization environment variables (see .IR environ (5)). The EXTERNAL INFLUENCES/Environment Variables section of the manual entry for each command that has NLS capabilities describes the environment variables to which the command is sensitive. .PP In addition, the .CR portnls routines are a set of library routines that perform miscellaneous language-dependent operations. .CR portnls is intended to provide portability between HP-UX and MPE (another HP operating system). See .IR portnls (5) for more information. .PP The following sections discuss areas of functionality that are considered language-sensitive. .SS Character Handling NLS provides for handling characters outside the 7-bit USASCII codeset. Most languages require a minimum of 8-bits to support all the characters needed to communicate in that language. Characters must be handled according to the requirements of the language they represent. .PP Codesets with 8 bit characters have been defined to support phonetic languages, such as the Western European languages. The use of an 8 bit character allows for an additional 128 characters beyond the USASCII codeset. .PP More than 8 bits are needed to uniquely define codes for characters required by ideographic languages such as Japanese. For such languages, multibyte codesets are used in which a character is represented by a sequence of one or more bytes. Multibyte codesets are defined according to the rules of a multibyte encoding scheme. Encoding schemes define the particular sequences of byte values that can be used to form characters. Full four byte EUC encoding scheme is supported by HP-UX. Refer to the book .I Developing and Localizing International Software for more information about EUC. .SS Character Classification Characters have many associated attributes. For example, characters may be classified as printable, alphabetic, numeric, etc. These attributes are commonly referred to as .I ctype characteristics. Characters and their associated attributes differ between languages. Character processing that depends on character classification must be sensitive to these differences. .SS Shifting The notion of uppercase and lowercase differs between languages. For example, in languages such as French, accents are discarded when characters are shifted to uppercase. Some languages have no notion of uppercase and lowercase characters. For example, shifting a character has no effect in ideographic languages. .SS Collating Collating sequences differ between languages and most languages require multiple collating sequences. The following collation features are available to provide a full ``dictionary-'' or ``context-based'' language-dependent comparison: .RS .TP 10 .BR "Two-to-one Conversions" Languages such as Spanish require two adjacent characters to occupy one position in the collating sequence. Examples are .BR CH (which follows .BR C ) and .BR LL (which follows .BR L ). .if t .bp .TP .BR "One-to-two Conversions" Languages such as German require one character (such as ``sharp S'') to occupy two adjacent positions in the collating sequence. .TP .BR "Don't-care Characters" Some languages designate certain characters to be ignored in character comparisons. For example, if .CR - is a don't-care character, the strings .CR REACT and .CR RE-ACT would equal each other when compared. .TP .BR "Uppercase/Lowercase and Accent Priority" Many languages require a ``two-pass'' collating algorithm. In the first pass, accents are stripped from their letters and the resulting two strings are compared. If they are equal, a second pass with the accents reinserted is performed to break the tie. Uppercase/lowercase differences can also be first ignored then used to break ties in this fashion. .RE .PP Two common methods of collation for phonetic languages are .IR folded and .IR nonfolded . A folded collating sequence is made up of the uppercase and lowercase characters intermixed. An unfolded collating sequence is made up of all of the uppercase characters followed by the lowercase characters. For example, collating the characters .CR "a b c A B C" with folded collation would result in the following order: .IP .C A a B b C c .PP Collating the same characters with unfolded collation would result in the following order: .IP .C A B C a b c .PP HP-UX only provides locales with folded collation. .SS Directionality Two properties of text files and Native Languages must be understood to process text in non-Western languages. They are the mode of the language, and the order of the characters. .PP .BR Mode refers to the direction that a language is naturally read. European languages read from left to right, some Middle Eastern languages read from right to left, and Far Eastern languages usually use vertical columns, beginning from the right. .PP .BR Order describes the order in which characters are written, stored in a file, or displayed. Keyboard order refers to the order of keystrokes by a user. Screen order refers to the order in which characters are displayed on a terminal screen or printed. .PP Screen order can differ from keyboard order when using a terminal that supports mixing Latin and non-Latin text, each requiring different directionality. In the following example, the text mode is right-to-left; .IR n represents a non-Latin character, .IR l represents a Latin character, and the numbers represent the order in which the sequence is typed. .PP In keyboard order, the letters would be stored in a file as follows: .IP .I "n1 n2 n3 l4 l5 l6" .PP In screen order, the letters would be stored in a file as follows: .IP .I "n1 n2 n3 l6 l5 l4" .PP However, both screen order and key order sequences would look identical on the screen because the terminal would be configured to display the characters properly according to the directionality requirements of both the Latin and non-Latin languages. .SS Local Customs NLS supports customs that are specific to a particular geographic region such as representation of numeric and monetary data, date, and time. These customs can differ not only between languages, but also between regions that share a common language. .RS .TP 10 .BR "Representation of Numbers" The character used to denote the radix of a decimal number varies for different regions. Similarly the use of a "thousands" indicator or grouping of digits can vary with local custom. Characters used to represent digits can also vary for different regions. .TP .BR "Monetary Representation" The currency symbol and the formatting of monetary values varies among countries. For instance, the symbol can either precede or follow the monetary value. Some currencies allow decimal fractions while others use alternate methods of representing smaller monetary values. .TP .BR "Date and Time Representation" While the Gregorian calendar is most common, some countries use other methods for determining meridian day and year, usually based on seasonal, astronomical, or historical events. Month and weekday names as well as the format of date and time varies from country to country. Even when a strictly numeric date/time representation is used, the order of year, month and day, and the delimiters that separate them, is not universal. .IP The HP-UX system clock runs on Coordinated Universal Time. Time zone adjustments for a particular regions can be specified through the .CR TZ environment variable (see .IR environ (5)). .RE .SS Messages Messages issued by a program should be sensitive to the language of the end-user. NLS provides a messaging facility for extracting hard-coded strings (messages) from an application source code and storing them externally to the code. Utilities are provided to aid the translation of messages such that at run-time the program accesses messages that coincide with the end-user's native language. .SS Codeset Conversions Since NLS provides support for multiple codesets within the same language, codeset conversion tables and algorithms are provided for codeset conversions within the same language. It is not possible to convert between codesets of different languages. For example, it is possible to convert between SJIS and eucJP, because both are Japanese codesets. However, it is not possible to convert between SJIS and ccdc, since SJIS is a Japanese codeset and ccdc is a Traditional Chinese codeset. (See .IR iconv (1), iconv (3C)). .SH FILES .if t .TP 45 .if n .TP 33 .PD 0 .CR /usr/lib/nls/config Locales available on HP-UX .TP .CR /usr/lib/nls/loc/charmaps Charmap sources .TP .CR /usr/lib/nls/loc/locales Locales .TP .CR /usr/lib/nls/loc/methods Locale specific algorithms .TP .CR /usr/lib/nls/loc/src Locale sources .TP .CR /usr/lib/nls/iconv/config.iconv .IR iconv conversions available on HP-UX .TP .CR /usr/lib/nls/iconv/methods Codeset specific algorithms .TP .CR /usr/lib/nls/iconv/tables .IR iconv tables .TP .CR /usr/lib/nls/msg Message catalogs for core HP-UX products .TP .CR /usr/share/man Man pages for core HP-UX products .PD .SH AUTHOR .CR hpnls was developed by HP. .SH SEE ALSO gencat(1), locale(1), catgets(3C), catopen(3C), localeconv(3C), nl_langinfo(3C), setlocale(3C), wconv(3X), wctype(3X), wstring(3X), environ(5), lang(5), langinfo(5). .PP .IR "Developing and Localizing International Software". .PP For additional information, see the EXTERNAL INFLUENCES/Environment Variables section of applicable manual entries for commands and library routines. .\" .\" index@\f4hpnls\f1 \- HP Native Language Support (NLS) Model@@@\f3hpnls(5)\f1 .\" index@\f1NLS, Native Language Support Model@@@\f3hpnls(5)\f1 .\" index@\f1HP Native Language Support (NLS) Model@@@\f3hpnls(5)\f1 .\" index@\f1Native Language Support@@@see \f2NLS\f1 .\" index@\f1international Native Language Support (NLS) Model@@@\f3hpnls(5)\f1 .\" index@\f1Language Support (NLS), HP international Native@@@\f3hpnls(5)\f1 .\" index@\f1internationalization (Native Language Support)@@@see \f2NLS \f1 .\" .\" toc@\f3hpnls(5)\f1:\0\0\f4hpnls\f1@@@HP Native Language Support (NLS) Model\f1 .\" .\" $Header: intro.5,v 72.4 93/01/14 16:03:20 ssa Exp $ .TA a .TH intro 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME intro \- introduction to miscellany .SH DESCRIPTION This section describes miscellaneous facilities such as macro packages, character set tables, and the file system hierarchy. .SH SEE ALSO The introduction to this manual. .\" index@\f2intro\f1 \- introduction to miscellany@@@\f3intro(5)\f1 .\" index@miscellany, introduction to@@@\f3intro(5)\f1 .\" .\" toc@\f3intro(5)\f1:\0\0\f2intro\f1@@@introduction to miscellany .\" .\" fileset_database@intro.5 SYS-ADMIN-MAN .\" $Header: ioctl.5,v 72.4 94/08/26 15:40:03 ssa Exp $ .TA i .TH ioctl 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ioctl \- generic device control commands .SH SYNOPSIS .B #include .br .B ioctl(fildes, request, arg) .br .B int fildes, request; .SH DESCRIPTION The .IR ioctl (2) system call provides for control over open devices. This include file describes .I requests and .I arguments used in .IR ioctl (2) which are of a generic nature. For details about how individual requests will affect any particular device, see the corresponding device manual entry in Section (7). If a device does not support an ioctl request it returns .SM .BR EINVAL . .TP 8 .SM FIONREAD Returns in the long integer whose address is .I arg the number of characters immediately readable from the device file. .TP .SM FIOSSAIOSTAT For those character device files which support this command, if the integer whose address is .I arg is non-zero, system asynchronous .SM I/O is enabled; that is, enable .SM SIGIO to be sent to the process currently designated with .SM FIOSSAIOOWN (see below) whenever device-file-dependent events occur. If no process has been designated with .SM FIOSSAIOOWN, then enable .SM SIGIO to be sent to the first process to open the device file. .IP If the designated process has exited, the .SM SIGIO signal is not sent to any process. .IP If the integer whose address is .I arg is 0, system asynchronous .SM I/O is disabled. .TP .SM FIOGSAIOSTAT For those character device files which support this command, the integer whose address is .I arg is set to 1, if system asynchronous .SM I/O is enabled. Otherwise, the integer whose address is .I arg is set to 0. .TP .SM FIOSSAIOOWN For those character device files which support this command, set process .SM ID to receive the .SM SIGIO signals with system asynchronous .SM I/O to the value of the integer whose address is .IR arg . Users with appropriate privileges can designate that any process receive the .SM SIGIO signals. If the request is not made by the super-user, only the calling process is allowed to designate that itself or another process whose real or saved effective user .SM ID matches its real or effective user .SM ID, or a process which is a descendant of the calling process, receive the .SM SIGIO signals. If no process can be found corresponding to that specified by the integer whose address is arg, the call will fail, with .B errno set to .SM ESRCH. If the request is not made by the super-user and the calling process attempts to designate a process other than itself or (1) another process whose real or saved effective user .SM ID matches its real or effective user .SM ID, or (2) a process which is not a descendant of the calling process, the call fails, with .B errno set to .SM EPERM. .IP If the designated process subsequently exits, the .SM SIGIO signal will not be sent to any process. .IP The default when opening a device file is that the process performing the open is set to receive the .SM SIGIO signals. .TP .SM FIOGSAIOOWN For those character device files which support this command, the integer whose address is .I arg is set to the process .SM ID designated to receive .SM SIGIO signals. .TP .SM FIOSNBIO For those character device files which support this command, if the integer whose address is .I arg is non-zero, non-blocking .SM I/O is enabled; that is, subsequent reads and writes to the device file are handled in a non-blocking manner (see below). If the integer whose address is .I arg is 0, non-blocking .SM I/O is disabled. .IP For reads, non-blocking .SM I/O prevents all read requests to that device from blocking, whether the requests succeed or fail. Such read requests complete in one of three ways: .RS 11 .TP 3 \(bu If there is enough data available to satisfy the entire request, the read completes successfully, having read all of the data, and returns the number of bytes read; .TP \(bu If there is not enough data available to satisfy the entire request, the read completes successfully, having read as much data as possible, and returns the number of bytes it was able to read; .TP \(bu If there is no data available, the read fails and .B errno is set to .SM EWOULDBLOCK. .RE .IP For writes, non-blocking .SM I/O prevents all write requests to that device file from blocking, whether the requests succeed or fail. Such a write request completes in one of three ways: .RS 11 .TP 3 \(bu If there is enough space available in the system to buffer all the data, the write completes successfully, having written out all of the data, and returns the number of bytes written; .TP \(bu If there is not enough space in the buffer to write out the entire request, the write completes successfully, having written as much data as possible, and returns the number of bytes it was able to write; .TP \(bu If there is no space in the buffer, the write fails and .B errno is set to .SM EWOULDBLOCK. .RE .IP To prohibit non-blocking .SM I/O from interfering with the .SM O_NDELAY flag (see .IR open (2) and .IR fcntl (2)), the functionality of .SM O_NDELAY always supersedes the functionality of non-blocking .SM I/O. This means that if .SM O_NDELAY is set, the driver performs read requests in accordance with the definition of .SM O_NDELAY. When .SM O_NDELAY is not set, the definition of non-blocking .SM I/O applies. .IP The default on open of a device file is that non-blocking .SM I/O is disabled. .TP FIOGNBIO For those character device files which support this command, the integer whose address is .I arg is set to 1, if non-blocking .SM I/O is enabled. Otherwise, the integer whose address is .I arg is set to 0. .SH WARNINGS .SM FIOSSAIOSTAT is similar to 4.2 .SM BSD FIOASYNC, with the addition of provisions for security. .SM FIOGSAIOSTAT is of .SM HP origin, complements .SM FIOSSAIOSTAT, and allows saving and restoring system asynchronous .SM I/O TTY state for .SM BSD style job control. .SM FIOSSAIOOWN is similar to 4.2 .SM BSD FIOSETOWN, with the addition of provisions for security. .SM FIOGSAIOOWN is similar to 4.2 .SM BSD FIOGETOWN. Note also the difference that the 4.2 .SM BSD version of this functionality used process groups, while the .SM HP-UX version only uses processes. .SM FIOSNBIO is the same as 4.2 .SM BSD FIONBIO, except that it does not interfere with the .SM AT&T .SM O_NDELAY .IR open and .IR fcntl flag. .SM FIOGNBIO is of .SM HP origin, complements .SM FIOSNBIO, and allows saving and restoring non-blocking .SM I/O TTY state for .SM BSD\s0-style job control. .SH SEE ALSO ioctl(2), socket(7), arp(7). .br Section 7 of this manual. .\" index@\f2ioctl\f1 \- generic \s-1I/O\s+1 device control commands@@@\f3ioctl(5)\f1 .\" index@generic \s-1I/O\s+1 device control commands@@@\f3ioctl(5)\f1 .\" index@\s-1I/O\s+1 device control commands, generic@@@\f3ioctl(5)\f1 .\" index@device control commands, generic \s-1I/O\s+1@@@\f3ioctl(5)\f1 .\" index@control commands, generic \s-1I/O\s+1 device@@@\f3ioctl(5)\f1 .\" index@commands, generic \s-1I/O\s+1 device control@@@\f3ioctl(5)\f1 .\" .\" toc@\f3ioctl(5)\f1:\0\0\f2ioctl\f1@@@generic device control commands .\" $Header: lang.5,v 72.4 94/07/20 14:55:22 ssa Exp $ .TA l .TH lang 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lang \- description of supported languages .SH DESCRIPTION HP-UX NLS (Native Language Support) provides support for the processing and customs requirements of a variety of languages. To enable NLS support for a particular language, a language definition must exist on the HP-UX system. Invoking the command .CR "locale -a" (see .IR locale (1)) displays information regarding which languages are currently supported on a particular HP-UX system. .PP The default processing language for HP-UX is .CR POSIX . .CR POSIX provides an environment in which processing occurs without NLS functionality. This environment is based on the 7-bit-coded USASCII character set. .PP .CR POSIX and .CR C are equivalent and can be used interchangeably. .SH AUTHOR .CR lang was developed by HP. .SH SEE ALSO locale(1), localedef(1M), setlocale(3C), environ(5), hpnls(5). .\" .\" index@\f4lang\f1 \- description of supported languages@@@\f3lang(5)\f1 .\" index@\f1NLS, description of supported languages@@@\f3lang(5)\f1 .\" index@\f1languages, description of supported@@@\f3lang(5)\f1 .\" index@\f1description of supported languages@@@\f3lang(5)\f1 .\" .\" toc@\f3lang(5)\f1:\0\0\f4lang\f1@@@description of supported languages\f1 .\" $Header: langinfo.5,v 72.4 94/07/27 14:06:23 ssa Exp $ .TA l .TH langinfo 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME langinfo \- language information constants .SH SYNOPSIS .C #include .SH DESCRIPTION This header file contains the constants used to identify items of .CR langinfo data (see .IR nl_langinfo (3C)). The mode of .I items is given in .CR . The following constants are defined. .RB ( Category indicates in which .IR setlocale (3C) category each item is defined). .PP .TS lB lB lBw(3.5i) lf4 lf4 l. Constant Category Description _ CODESET LC_CTYPE T{ Codeset name, such as .CR iso88591 and .CR eucJP . T} .ift .sp .5v .ifn .sp D_T_FMT LC_TIME T{ String for formatting the .CR %c (date and time) directive of .IR date (1), .IR getdate (3C), and .IR strftime (3C). T} .ift .sp .5v .ifn .sp D_FMT LC_TIME T{ String for formatting the .CR %x (date) directive of .IR date (1), .IR getdate (3C), and .IR strftime (3C). T} .ift .sp .5v .ifn .sp T_FMT LC_TIME T{ String for formatting the .CR %X (time) directive of .IR date (1), .IR getdate (3C), and .IR strftime (3C). T} .ift .sp .5v .ifn .sp T_FMT_AMPM LC_TIME T{ Time representation in the 12 hour clock format with .CR AM_STR and .CR PM_STR . T} .ift .sp .5v .ifn .sp AM_STR LC_TIME T{ Ante meridiem string used with 12 hour time formats ("AM" in English). T} .ift .sp .5v .ifn .sp PM_STR LC_TIME T{ Post meridiem string used with 12 hour time formats ("PM" in English). T} .ift .sp .5v .ifn .sp DAY_1 LC_TIME T{ Name of the first day of the week (``Sunday'' in English). T} \0\0: \0\0: \0\0: DAY_7 LC_TIME T{ Name of the seventh day of the week. T} .ift .sp .5v .ifn .sp ABDAY_1 LC_TIME T{ Abbreviated name of the first day of the week (``Sun'' in English). T} .ift .sp .5v .ifn .sp ABDAY_7 LC_TIME T{ Abbreviated name of the seventh day of the week. T} .ift .sp .5v .ifn .sp MON_1 LC_TIME T{ Name of the first month in the Gregorian year. T} \0\0: \0\0: \0\0: MON_12 LC_TIME T{ Name of the twelfth month. T} .ift .sp .5v .ifn .sp ABMON_1 LC_TIME T{ Abbreviated name of the first month. T} \0\0: \0\0: \0\0: ABMON_12 LC_TIME T{ Abbreviated name of the twelfth month. T} .ift .sp .5v .ifn .sp ERA LC_TIME T{ The era description segments, which describe how years are counted and displayed for each era in a locale. Each era description segment has the format: T} .ift .sp .5v .ifn .sp T{ .IC "\0\0direction" : offset : start_date : .IC "\0\0\0\0end_date" : era_name : era_format T} .ift .sp .5v .ifn .sp T{ according to the descriptions below. There will be as many era description segments as are necessary to describe the different eras. Era description segments are separated by semicolons. T} .ift .sp .5v .ifn .sp T{ Note that the start of an era might not be the earliest point in the ear it may be the latest. For example, the Christian era BC starts on the day before January 1, AD 1, and increases with earlier time. T} .ift .sp .5v .ifn .sp T{ .IR direction : Either a + or a - character. The + character indicates that years closer to the .CR start_date have lower numbers than those closer to the .CR end_date . T} .ift .sp .5v .ifn .sp T{ .IR offset : The number of the year closest to the .IR start_date in the era. T} .ift .sp .5v .ifn .sp T{ .IR start_date : A date in the format .IC yyyy / mm / dd\f1, where .IR yyyy , .IR mm , " dd" are the year, month, and day numbers respectively of the start of the era. Years prior to AD 1 are represented as negative numbers. T} .ift .sp .5v .ifn .sp T{ .IR end_date : The ending date of the era, in the same format as the .IR start_date or one of the two special values -* or +*. The value -* indicates that the ending date is the beginning of time. The value +* indicates that the ending date is the end of time. T} .ift .sp .5v .ifn .sp T{ .IR era_name : The era, corresponding to the .CR %EC conversion specification. T} .ift .sp .5v .ifn .sp T{ .IR era_format : The format of the year in the era, corresponding to the .CR %EY conversion specification. T} .ift .sp .5v .ifn .sp ERA_D_FMT LC_TIME T{ Format string for formatting the .CR %E (Emperor/Era name and year) directive of .IR date (1) and .IR strftime (3C) if an individual era format is not specified for an era (see .IR localedef (1M)). T} .ift .sp .5v .ifn .sp ERA_D_T_FMT LC_TIME T{ The locale's appropriate alternative date and time format, corresponding to the .CR %Ec field descriptor. T} .ift .sp .5v .ifn .sp ERA_T_FMT LC_TIME T{ The locale's appropriate alternative date and time format, corresponding to the .CR %EX field descriptor. T} .ift .sp .5v .ifn .sp ALT_DIGITS LC_NUMERIC T{ The alternative symbols for digits, corresponding to the .CR %O conversion specification modifier. The value consists of semicolon separated strings. The first string is the alternative symbol corresponding with zero, the second string corresponding with one, etc. Up to 100 alternate symbol strings may be specified. T} .ift .sp .5v .ifn .sp RADIXCHAR LC_NUMERIC T{ Radix character ("decimal point" in English). The string returned is the same as the .CR decimal_point element in the structure returned by .IR localeconv (3C). T} .ift .sp .5v .ifn .sp THOUSEP LC_NUMERIC T{ Separator for thousands. The string returned is the same as the .CR thousands_sep element in the structure returned by .IR localeconv (3C). T} .ift .sp .5v .ifn .sp YESEXPR LC_MESSAGES T{ Affirmative response extended regular expression. T} .ift .sp .5v .ifn .sp NOEXPR LC_MESSAGES T{ Negative response extended regular expression. T} .ift .sp .5v .ifn .sp YESSTR LC_MESSAGES T{ Affirmative response for yes/no questions. (Obsolete: use .CR YESEXPR .) T} .ift .sp .5v .ifn .sp NOSTR LC_MESSAGES T{ Negative response for yes/no questions. (Obsolete: use .CR NOEXPR .) T} .ift .sp .5v .ifn .sp CRNCYSTR LC_MONETARY T{ Symbol for currency preceded by .CR \(mi if it precedes the number, .CR + if it follows the number, and .CR .\& if it replaces the radix. For example, .CR \(miDM would be used for de_DE.iso88591 (DM1234,56), .CR "+ Kr" for da_DK.iso88591 (1234,56\ Kr), and .CR .$ for pt_PT.iso88591 (1234$56). See .IR localeconv (3C) for alternative currency formatting information. T} .ift .sp .5v .ifn .sp DIRECTION LC_CTYPE T{ Value to indicate text direction. Values currently defined include .CR null , .CR 0 , and .CR 1 . Values of .CR null or .CR 0 indicate that characters are arranged from left to right within a line and lines are arranged from top to bottom. A value of .CR 1 indicates that characters are arranged from right to left within a line and lines are arranged from top to bottom. (This constant is an HP proprietary item, subject to change, and may not be portable to other platforms.) T} .ift .sp .5v .ifn .sp CONTEXT LC_CTYPE T{ String indicating character context analysis. String .CR null or .CR 0 indicates no context analysis is required. String .CR 1 indicates Arabic context analysis required. T} .ift .sp .5v .ifn .sp ALT_DIGIT LC_NUMERIC T{ A string of the characters that are mapped into the ASCII equivalent string ``0123456789b+-.,eE'' (where b is a blank). This is also the reverse mapping for output. It is not assumed that the character code values of digits are contiguous or that they are one byte values. A null value for the string indicates that the language has no alternative digits. (This constant is an HP proprietary item, subject to change, and may not be portable to other platforms.) T} .ift .sp .5v .ifn .sp ALT_PUNCT LC_CTYPE T{ A string of the characters that are mapped into the ASCII equivalent string .RC ``b \!"#$%&'()\(**+,\-./:;<=>?@[\e]^_`{|}~'' (where b is a blank) in American usage. This is also the reverse mapping for output. It is not assumed that the character code values of punctuation characters are contiguous or that they are one byte values. If any punctuation characters do not have equivalent alternatives, ASCII codes are used in the alternative punctuation string. A null value for the string indicates that the language has no alternative punctuation characters. (This constant is an HP proprietary item, subject to change, and may not be portable to other platforms.) T} .ift .sp .5v .ifn .sp YEAR_UNIT LC_TIME T{ Symbol for year. This is usually required to specify date for Asian languages. (This constant is an HP proprietary item, subject to change, and may not be portable to other platforms.) T} .ift .sp .5v .ifn .sp MON_UNIT LC_TIME T{ Symbol for month. (This constant is an HP proprietary item, subject to change, and may not be portable to other platforms.) T} .ift .sp .5v .ifn .sp DAY_UNIT LC_TIME T{ Symbol for day. (This constant is an HP proprietary item, subject to change, and may not be portable to other platforms.) T} .ift .sp .5v .ifn .sp HOUR_UNIT LC_TIME T{ Symbol for hour. This is usually required to specify time for Asian languages. (This constant is an HP proprietary item, subject to change, and may not be portable to other platforms.) T} .ift .sp .5v .ifn .sp MIN_UNIT LC_TIME T{ Symbol for minute. (This constant is an HP proprietary item, subject to change, and may not be portable to other platforms.) T} .ift .sp .5v .ifn .sp SEC_UNIT LC_TIME T{ Symbol for second. (This constant is an HP proprietary item, subject to change, and may not be portable to other platforms.) T} .ift .sp .5v .ifn .sp CHARMAP T{ .nf LC_CTYPE/ LC_COLLATE .fi T} T{ The name of the charmap used to compile this locale. (This constant is an HP proprietary item, subject to change, and may not be portable to other platforms.) T} .TE .SH WARNINGS It is recommended to use .C strftime() to access date and time information defined in .C category (see .IR strftime (3C)), .C LC_TIME and .IR localeconv (3C) to access information corresponding to .CR RADIXCHAR , .CR THOUSEP , and .C CRNCYSTR (see .IR localeconv (3C)). .SH AUTHOR .C langinfo was developed by HP. .SH SEE ALSO date(1), getdate(3C), localeconv(3C), nl_langinfo(3C), setlocale(3C), strftime(3C), hpnls(5), lang(5). .\" .\" index@\f4langinfo\f1 \- language information constants@@@\f3langinfo(5)\f1 .\" index@\f1constants, language information@@@\f3langinfo(5)\f1 .\" index@\f1language information constants@@@\f3langinfo(5)\f1 .\" index@\f1NLS, language information constants@@@\f3langinfo(5)\f1 .\" .\" toc@\f3langinfo(5)\f1:\0\0\f4langinfo\f1@@@language information constants\f1 .\" $Header: limits.5,v 78.1 95/12/20 10:57:27 ssa Exp $ .TA l .TH limits 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME limits \- implementation-specific constants .SH SYNOPSIS .B #include .SH DESCRIPTION The following symbols are defined in .RB < limits.h > and are used throughout the descriptive text of this manual. The column headed .SM .B "HP-UX Value" lists the values that application writers should assume for portability across all .SM HP-UX systems. .PP Symbols after values are interpreted as follows: .RS .TP 5 .B + Actual limit might be greater than specified value on certain .SM HP-UX systems. .TP .B \- Actual limit might be less than the specified value on certain .SM HP-UX systems. .TP .B = Actual limit is always equal to the specified value and does not vary across .SM HP-UX systems. .TP .B \(** The name of this limit is defined .I only if the preprocessor macro .SM _XPG2 is defined, either by the compilation flag .SM \-D_XPG2, or by a .B #define directive in the source before .RB < limits.h > is included in the source. .TP .B # The value defined for this limit might not be a compile-time constant. The value defined always evaluates to an integer expression at run time. .RE .PP Some of these limits vary with system configuration, and can be determined dynamically by using .IR sysconf (2). Others can vary according to file system or device associated with a specific file, and can be determined with .IR pathconf(2). Others are obsolescent because they are redundant with other limits or not useful in portable applications. They are provided only for importability of applications from other systems, to support applications that comply with the .IR "X/Open Portability Guide" , " Issue 2" , and for backward compatibility with earlier versions of .SM HP-UX. The .SM _XPG2 flag should not be defined in new applications. .PP By including the .RB < limits.h > file in the compilation an application can test the appropriate limits to determine whether it can operate on a particular system, or it might even alter its behavior to match the system to increase its portability across a varying range of limit settings and systems. .PP \".na .TS lB lBw(2.6i) rB lb p-2 l rB. Constant Description HP-UX Value ARG_MAX T{ Max length of arguments to \f2exec\fP(2) in bytes, including environment data T} \s-15120\s+1 +* CHAR_BIT T{ Number of bits in a \f3char\fP T} 8 = CHAR_MAX T{ Max integer value of a \f3char\fP T} \s-1127\s+1 = CHAR_MIN T{ Min integer value of a \f3char\fP T} \-\s-1128\s+1 = CHILD_MAX T{ Max number of simultaneous processes per user \s-1ID\s+1 T} \s-125\s+1 +\-* CLK_TCK T{ Number of clock ticks per second T} \s-150\s+1 +# DBL_DIG T{ Digits of precision of a \f3double\fP T} \s-115\s+1 + DBL_MAX T{ Max positive value of a \f3double\fP T} \s-11.7976931348623157e+308\s+1 + DBL_MIN T{ Min positive value of a \f3double\fP T} \s-14.94065645841246544e\-324\s+1 \- FCHR_MAX T{ Max file offset in bytes T} \s-2INT_MAX\s+2 +\-* FLT_DIG T{ Digits of precision of a \f3float\fP T} 6 + FLT_MAX T{ Max positive value of a \f3float\fP T} \s-13.40282346638528860e+38\s+1 + FLT_MIN T{ Min positive value of a \f3float\fP T} \s-11.40129846432481707e\-45\s+1 \- INT_MAX T{ Max decimal value of an \f3int\fP T} \s-12147483647\s+1 + INT_MIN T{ Min decimal value of an \f3int\fP T} \-\s-12147483648\s+1 \- LINE_MAX T{ Max number of characters in a single line T} \s-12048\s+1 = LINK_MAX T{ Max number of links to a single file T} \s-132\|767\s+1 +* LOCK_MAX T{ Max number of entries in system lock table T} \s-132\s+1 +\-* LONG_BIT T{ Number of bits in a \f3long\fP T} \s-132\s+1 + LONG_MAX T{ Max decimal value of a \f3long\fP T} \s-12147483647\s+1 + LONG_MIN T{ Min decimal value of a \f3long\fP T} \s-1\-2147483648\s+1 \- MAX_CANON T{ Max number of bytes in terminal canonical input line T} \s-1512\s+1 +* MAX_CHAR T{ Max number of bytes in terminal input queue T} \s-2MAX_INPUT\s+2 =* MAX_INPUT T{ Max number of bytes in terminal input queue T} \s-1512\s+1 +* NAME_MAX T{ Max number of bytes in a path name component T} \s-114\s+1 +* NL_ARGMAX T{ Max value of "digits" in calls to the \s-1NLS\s+1 \f2printf\fP(3S) and \f2scanf\fP(3S) functions T} 9 = NL_MSGMAX T{ Max message number in an \s-1NLS\s+1 message catalog T} \s-132767\s+1 + NL_SETMAX T{ Max set number in an \s-1NLS\s+1 message catalog T} \s-1255\s+1 + NL_TEXTMAX T{ Max number of bytes in an \s-1NLS\s+1 message string T} \s-18192\s+1 + NGROUPS_MAX T{ Max number of supplementary groups per process T} \s-120\s+1 + OPEN_MAX T{ Max number of files a process can have open T} \s-160\s+1 +* PASS_MAX T{ Max number of chars in a password T} 8 + PATH_MAX T{ Max number of characters in a path name excluding the null terminator T} \s-11023\s+1 +* PID_MAX T{ Max value for a process \s-1ID\s+1 T} \s-130000\s+1 + PIPE_BUF T{ Max number of bytes atomic in write to a pipe T} \s-18192\s+1 +* PIPE_MAX T{ Max number of bytes writable to a pipe in one write T} \s-2INT_MAX\s+2 + PROC_MAX T{ Max number of simultaneous processes on system T} \s-184\s+1 +\-* SCHAR_MAX T{ Max integer value of a \f3signed char\fP T} \s-1127\s+1 = SCHAR_MIN T{ Min integer value of a \f3signed char\fP T} -\s-1128\s+1 = SHRT_MAX T{ Max decimal value of a \f3short\fP T} \s-132767\s+1 + SHRT_MIN T{ Min decimal value of a \f3short\fP T} \-\s-132768\s+1 \- STD_BLK T{ Number of bytes in a physical \s-1I/O\s+1 block T} \s-1512\s+1 + SYSPID_MAX T{ Max process \s-1ID\s+1 of system processes T} 4 +\-* SYS_NMLN T{ Length of strings returned by \f2uname\fP(2) T} 8 +* SYS_OPEN T{ Max number of files open on system T} \s-1120\s+1 +\-* TMP_MAX T{ Max number of unique names generated by \f2tmpnam\fP(3S) T} \s-117576\s+1 + UCHAR_MAX T{ Max integer value of an \f3unsigned char\fP T} \s-1255\s+1 = UID_MAX T{ Smallest unattainable value for a user or group \s-1ID\s+1 T} \s-12147483647\s+1 + UINT_MAX T{ Max decimal value of an \f3unsigned int\fP T} \s-14294967295\s+1 + ULONG_MAX T{ Max decimal value of an \f3unsigned long\fP T} \s-14294967295\s+1 + USHRT_MAX T{ Max decimal value of an \f3unsigned short\fP T} \s-165535\s+1 + USI_MAX T{ Max decimal value of an \f3unsigned int\fP T} \s-2UINT_MAX\s+2 =* WORD_BIT T{ Number of bits in a "word" (\f3int\fP) T} \s-132\s+1 + .TE .SH EXAMPLES .SM .B UID_MAX has an .SM HP-UX value of .B "2147483647 +" , which means that on all .SM HP-UX systems the smallest unattainable value for a user or group .SM ID is at least 2147483647. A particular system might be capable of supporting more than 2147483647 user or group .SM ID\s0s, in which case its .RB < limits.h > file sets .SM .B UID_MAX to a higher value; however, any application assuming such a higher value is not guaranteed to be portable to all .SM HP-UX systems. .SH AUTHOR .I limits was developed by HP. .SH "SEE ALSO" exec(2), fcntl(2), fork(2), getgroups(2), link(2), lockf(2), open(2), pathconf(2), sysconf(2), uname(2), write(2), printf(3S), scanf(3S), tmpnam(3S), passwd(4), values(5), termio(7). .TP Series 700 .br config(1M). .SH STANDARDS CONFORMANCE .RC < limits.h ">: AES, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.2, ANSI C" .\" .\" index@\f2limits\f1 \- implementation-specific constants@@@\f3limits(5)\f1 .\" index@implementation-specific constants@@@\f3limits(5)\f1 .\" index@constants, implementation-specific@@@\f3limits(5)\f1 .\" .\" toc@\f3limits(5)\f1:\0\0\f2limits\f1@@@implementation-specific constants .\" .\" fileset_database@limits.5 SYS-ADMIN-MAN .\" $Header: man.5,v 72.4 94/05/17 21:59:46 ssa Exp $ .TA m .TH man 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME man \- macros for formatting entries in this manual .SH DESCRIPTION These macros are used by .C nroff (and are usable by .CR troff ) to determine the layout format of the on-line version of entries found in this and other related reference manuals. These macros are used by the .C man command (see .IR man (1)). .PP The default page size is 8.5\|\(mu\|11 inches, with a 6.5\|\(mu\|10-inch text area. The .C \-rs1 option (which is ignored by .CR nroff ) reduces these dimensions to 6\|\(mu\|9 inches and 4.75\|\(mu\|8.375 inches, respectively \(em and reduces the default type size from 10-point to 9-point; the vertical line spacing from 12 points to 10 points. The .C \-rV2 option can be used to set certain parameters to values appropriate for certain Versatec printers: line length to 82 characters; page length to 84 lines; underlining inhibited. This option should not be confused with the .C \-Tvp option of the .C man command, which is available on some .SM UNIX operating systems. .PP Any .I text argument below can consist of one to six ``words''. Double quotes .RC ( "" ) can be used to include blanks in a ``word''. If .I text is empty, the special treatment is applied to the next line containing text to be printed. For example, .C .I can be used to italicize a whole line, or .C .SM followed by .C .B to make small bold text. .PP By default, hyphenation is turned off for .CR nroff , but remains on for .CR troff . Paragraphs are left-justified, ragged-right for .CR nroff , and adjusted both left and right for .CR troff . .PP Type font and size are reset to default values before each paragraph and after processing font- and size-setting macros such as .CR .I , .CR .RB , and .CR .SM . Tab stops are neither used nor set by any macro except .C .DT and .CR .TH . .C .TH invokes .C .DT (see below). .PP Default units for indents .I in are ens. When .I in is omitted, the previous indent is used. This remembered indent is set to its default value (7.2 ens in .CR troff , 5 ens in .C nroff \(em corresponding to 0.5 inch in the default page size) by .CR .TH , .CR .P , .CR .PP , and .CR .RS , and restored by .CR .RE . .PP .PD 0 .TP 15 .CI .TH " t s c n a" Set the title and entry heading: .RS .RS .TP 5 .I t Entry title. .TP .I s Section number. .I t is combined with .I s in parentheses to form the top left- and right-hand corners of the page heading. .TP .I c Extra commentary such as ``Optional Software Required''; placed in parentheses at the center of the bottom line in the two- or three-line page heading space. .TP .I n (for ``new manual name'') Used for other text such as "Series 300/400 Only"; centered between the title and section on the first page heading line. .TP .I a (for ``alternate entry name'') Provided to support alternate naming such as a F\s-2ORTRAN\s0 routine name corresponding to a C function name specified in .IR t . .RE .RE .TP .CI .SH " text" Place section head .IR text , e.g., .CR SYNOPSIS , here. .TP .CI .SS " text" Place sub-section head .I text such as .C Options here. .TP .CI .C " text" Set .I text in .C computer (monospaced) font. Handled the same as bold by .CR nroff . .TP .CI .B " text" Make .I text bold. .TP .CI .I " text" Make .I text italic. .TP .CI .SM " text" Make .I text 1 point smaller than default point size. .TP .CI .RI " a b" Concatenate Roman .I a with italic .IR b , and alternate these two fonts for up to six arguments. Similar macros alternate between any two of Roman, italic, and bold: .RS .RS .C ".IR .RB .BR .IB .BI" .RE .RE .TP .CI .CI " a b" Concatenate computer font .I a with italic .IR b , and alternate these two fonts for up to six arguments. Similar macros alternate between any two of computer and Roman, italic, and bold: .RS .RS .C ".IC .CB .BC .CR .RC" .RE .RE .IP Computer font printed the same as bold by .CR nroff . .TP .C .P Begin a paragraph with normal font, point size, and indent. .C .PP is a synonym for .CR .P . .TP .CI .HP " in" Begin paragraph with hanging indent. .TP .CI .TP " in" Begin indented paragraph with hanging tag. The next line that contains text to be printed is taken as the tag. If the tag does not fit, it is printed on a separate line. .TP .CI .IP " t in" Same as .CI .TP " in" with tag .IR t ; often used to get an indented paragraph without a tag. .TP .CI .RS " in" Increase relative indent (initially zero). Indent all output an extra .I in units from the current left margin. .TP .CI .RE " k" Return to the .IR k th relative indent level (initially, .IR k =1; .IR k =0 is equivalent to .IR k =1); if .I k is omitted, return to the most recent lower indent level. .TP .CI .PM " m" Produces proprietary markings; where .I m may be .C P for .CR PRIVATE , or .C N for .CR NOTICE , .C BP for .CR "BELL LABORATORIES PROPRIETARY" , or .C BR for .CR "BELL LABORATORIES RESTRICTED" . .TP .C .DT Restore default tab settings (every 7.2 ens in .CR troff , 5 ens in .CR nroff ). .TP .CI .PD " v" Set the interparagraph distance to .I v vertical spaces. If .I v is omitted, set the interparagraph distance to the default value (0.4v in .CR troff , 1v in .CR nroff ). .PD .PP The following .I strings are defined: .PP .PD 0 .TP 15 .C \e*R .C (Reg.) in .CR nroff , Registered Trademark symbol in .CR troff , if available. .TP .C \e*S Change to default type size. .TP .C \e*(Tm Trademark indicator. .PD .PP The following .I "number registers" are given default values by .CR .TH : .PP .PD 0 .TP 15 .C IN Left margin indent relative to section heads (default is 7.2 ens in .CR troff , 5 ens in .CR nroff ). .TP .C LL Line length including .CR IN . .TP .C PD Current interparagraph distance. .PD .SS Font Conventions Entries in the .SM .I HP-UX .I Reference use the following font conventions: .RS .TP 10 Roman Normal typeface used for explanatory and other normal text. .TP .C computer Used for all literals which are typed exactly as shown when used as keyboard commands or command-line options, in programs, etc. .TP .I italic Used for variables and other words that represent an argument that may take on a user-defined or variable value. Also used for .I emphasis in regular text. .TP .B boldface Used primarily in headings and occasionally for terms when first introduced or when being defined. .RE .SS Special Features Strings used in the page footer macro are initialized by the .C .TH macro. One is defined as a non-printing (null) string to prevent the printing of "Hewlett-Packard Company" at the bottom of manual entries provided by other parties. .PP This arrangement enables users and third-party software suppliers to directly control the contents of the left- and right-hand fields of the footer line for use in displaying company name, release version, etc., as desired when creating their own manual entries. Footer string .C )H is printed on the left; string .C ]W is printed on the right, and the page number is printed in the center. Strings can be defined anywhere after the .SM .TH macro call provided they appear before the end of the first page as in the following example source file segment: .IP .C .TH man 5 .br .C .ds )H XYZ Company .br .C .ds ]W Release 2.3: July 1989 .PP which produces a footer resembling: .IP .ifn \{\f3XYZ Company\h'1.2i'- 1 -\h'.2i'Release 2.3: July 1989\f1\} .ift \{\f3XYZ Company\h'1.2i'- 1 -\h'1i'Release 2.3: July 1989\f1\} .SH FILES .nf .C /usr/share/lib/macros/cmp.[nt].[dt].an .C /usr/share/lib/tmac/tmac.an .C /usr/share/lib/macros/ucmp.[nt].an .fi .SH SEE ALSO man(1), nroff(1). .SH WARNINGS In addition to the macros, strings, and number registers mentioned above, a number of .I internal macros, strings, and number registers are defined. Except for names predefined by .CR nroff / troff and number registers .CR d , .CR m , and .CR y , all such internal names are of the form .IR XA , where .I X is one of .CR ) , .CR ] , and .CR } , and .I A stands for any alphanumeric character. .PP The .C NAME section of each entry is assumed to consist of a single line of input that has the following format: .IP name[, \|name, \|name \|.\|.\|.] \|\e\- \|explanatory \|text .PP The .C NAME section is no longer used to prepare the Table of Contents and Index for this manual. Instead, that information is coded as comments at the end of each manual entry source file where it can be accessed by various tools and programs as desired. However, .IR catman (1M) and related programs still use the .C NAME line to create the mkwhatis database. .PP The macro package increases the inter-word spaces (to eliminate ambiguity) in the .C SYNOPSIS section of each entry. .PP The macro package itself uses only the Roman font (so that one can replace, for example, the bold font by the constant-width font if available). Of course, if the input text of an entry contains requests for other fonts (e.g., .CR .I , .CR .RB , .CR \efI ), the corresponding fonts must be mounted. The computer font macros use font position 3 (same as bold). To use a constant-width font, change the font 3 specification in each macro to font 4 and mount the constant-width font in position 4 using a troff .C .fp request. .PP Any argument to .C .TH containing blanks must be enclosed by double quotes .RC ( "" ) to ensure correct interpretation for formatting. .\" index@\f2man\f1 \- macros for formatting \f2\s-1HP-UX\s+1 Reference\f1 entries@@@\f3man(5)\f1 .\" index@macro package for formatting \f2\s-1HP-UX\s+1 Reference\f1 entries@@@\f3man(5)\f1 .\" index@formatting entries in \f2\s-1HP-UX\s+1 Reference\f1, macro package for@@@\f3man(5)\f1 .\" index@manual entries, macro package for formatting \f2\s-1HP-UX\s+1 Reference\f1@@@\f3man(5)\f1 .\" .\" toc@\f3man(5)\f1:\0\0\f2man\f1@@@macros for formatting entries in this manual .\" .\" fileset_database@man.5 SYS-ADMIN-MAN .\" $Header: manuals.5,v 78.1 96/05/24 06:46:56 ssa Exp $ .TA m .TH manuals 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME manuals \- Current list of HP-UX documentation .SH DESCRIPTION This entry contains a list of current English language manuals for the HP-UX operating system. The information is current as of HP-UX release 10.20. Manuals updated after release 10.20 may have different part numbers. Contact your HP Sales and Support office for assistance on getting the correct editions of manuals for your system. If discrepancies are encountered between system behavior and a given manual, verify the edition date to ensure that the manual is current. .PP Applications software manuals are not included in this list. .SS Ordering Information For information about how to order any of these manuals, as well as other HP computer and calculator manuals and supplies, call .B "Parts Direct Ordering" toll-free in the United States at .BR 1-800-227-8164 , or contact your nearest HP Sales and Support office outside the U.S.A.\& for information about ordering these manuals or versions of these manuals in other languages. .SS Manual List .\" Use Cupertino LP database for this .ift .RS 10 .TS tab(|); lB lBw(4i) l l. Stock Number|Title _ 28604-90001|HP OSI Express 802.4 Hardware 32055-90001|HP X.400/HP Desk Administration Guide 32055-90002|Using Hp DeskMgr Connection X 32070-90019|Installing and Administering OSI Transport Services 32070-90020|HP OSI Troubleshooting Guide 32070-90021|APRI Programmer's Guide 32070-90025|Release Notes: OTS 9000 10.0 36940-90017|X.25/9000 Programmer's Guide 36940-90018|Installing and Administering X.25/9000 36940-90019|Troubleshooting X.25/9000 36960-90050|Programmer's Guide to X.25 Link Software for HP9000 Systems 36960-90051|X.25/9000 User's Guide 5961-1612|Support Tools Manager User's Guide 5963-4416|C++ Customer Survey 5963-4467|C/HP-UX 10.0 Release Notes 5963-4468|C/HP-UX Technical Addendum 5963-4475|HP-UX Programming Tools Release Notes 5963-4519|FORTRAN/9000 Release Notes 5963-8916|HP C++ HP-UX 10.0 Release Notes HP9000 Series 700/800 5963-8917|HP Pascal/HP-UX Release Notes 5963-8918|Assembly Language Release Note 5964-1320|HP Micro Focus COBOL Release Notes S700/800 5964-1321|HP Micro Focus COBOL TOOLBOX Release Notes 5964-1322|HP Micro Focus COBOL DIALOG Release Notes 5964-1365|HP-UX 10.10 Release Notes (On-Line and LRom only) 92431-90005|HP Pascal/HP-UX Reference Manual 92431-90006|HP Pascal/HP-UX Programmer Guide 92432-90001|Assembly Language Reference Manual 92434-90002|HP C Programmer's Guide 92453-90024|HP C/HP-UX Reference Manual 92501-90005|HP C++ Programmer's Guide 92552-90009|NLIO Input Method Guide (Trad. Chinese) 92668-90006|Managing SwitchOver/UX 92668-90007|Read Me Before Upgrading SwitchOver/UX from HP-UX 9.0 to HP-UX 10.0 97005-90015|The Ultimate Guide to vi and ex Editors 98194-90053|LLA Programming & Migration Guide 98592-90081|Starbase Graphics Techniques A1700-90014|Using HP-UX (Series 800 only) A1703-90045|Owner's Guide to HP 9000 S800 Models F,G,H,I A2051-90020|Owner's Guide HP 9000 S800 Model E Computers A2375-90003|Owner's Guide HP 9000 S800 Model K Computers A2615-90003|Using Your HP Workstation (Series 700 only) A4011-90002|Installing and Administering Token Ring A4031-90006|Installing and Administering HP EISA Fibre Channel/9000 A4031-90007|HP EISA Fibre Channel/9000 Quick Installation A4031-90009|HP EISA Fibre Channel/9000 Release Notes B1011-90003|Using LAN Manager/X B1029-90000|Networking Overview B1030-90002|DTC Device File Access Utilities and Telnet Port Identification B1031-90000|Installing & Administering NFS B1033-90002|HP FTAM/9000 Reference Manual B1033-90012|HP FTAM/9000 Programmer's Guide B1033-90022|HP FTAM/9000 User's Guide B1033-90032|Installing and Administering HP FTAM/9000 B1033-90040|FTAM/9000 Technical Addendum B1033-90041|Release Notes: FTAM 9000 B1171-90051|Xlib Programming Manual B1171-90052|Xlib Reference Manual B1171-90053|X Toolkit Intrinsics Programming Manual B1171-90054|X Toolkit Intrinsics Reference B1171-90056|X Window System C Quick Reference B1171-90057|Mastering Motif Widgets B1171-90058|HP OSF/Motif 1.2 Style Guide B1171-90074|HP OSF/Motif 1.2 Programmer Guide B1171-90075|HP OSF/Motif 1.2 Programmer Reference Guide B1171-90076|Using the X Window System B1171-90077|HP Help System Developer's Guide B1171-90078|HP Xlib Extensions B1171-90079|HP Visual User Environment 3.0 User's Guide B1171-90080|HP Visual User Environment 3.0 Quick Start Card B1171-90100|Software Portability with Imake B1862-90012|Mail Systems: User's Guide B1862-90013|Terminal Control: User's Guide B1862-90014|Text Formatting: User's Guide B1862-90015|Number Processing: User's Guide B1862-90016|Text Processing: User's Guide B2200-90019|Japanese NLIO Manual B2204-90002|NLIO System Admin Guide (Kor.) B2204-90011|NLIO Access User's Guide (Kor.) B2208-90011|NLIO Access User's Guide (Trad. Chinese) B2208-90012|NLIO System Admin Guide (Trad. Chinese) B2212-90002|NLIO System Admin Guide (Simp. Chinese) B2212-90003|NLIO Input Method Guide (Simp. Chinese) B2212-90011|NLIO Access User's Guide (Simp. Chinese) B2351-90000|Terminal Session Manager: User's Guide B2355-90044|HP-UX Symbolic Debugger User's Guide B2355-90046|Shells: User's Guide B2355-90049|POSIX Conformance Document B2355-90052|HP-UX Reference B2355-90053|Configuring HP-UX for Peripherals B2355-90055|HP-UX Starbase Device Driver Library Manual B2355-90055|HP-UX Starbase Device Drivers Manual B2355-90056|Starbase Reference B2355-90060|Programming with Threads on HP-UX B2355-90063|Kermit Mailer Card B2355-90064|Managing Software with iFOR/LS B2355-90068|Using the Image Developer's Kit B2355-90069|Using the Audio Developer's Kit B2355-90072|Keyshell Technical Addendum B2355-90079|HP-UX System Administration Tasks B2355-90086|Installing HP-UX 10.10 and Updating 10.0x to 10.10 B2355-90087|Installing & Administering LAN/9000 B2355-90088|Using Serial Line IP Printers B2355-90088|Using Serial Line IP Protocols B2355-90091|iFOR/LS Quick Start Guide B2355-90092|BSD Socket Interface Programmer's Guide B2355-90093|DLPI Programmer's Guide B2355-90094|XTI Programmer's Guide B2355-90095|BSD Socket Quick Reference Guide B2355-90096|Graphics Administration Guide B2355-90097|Fast Alpha Font Manager Programmer's Manual B2355-90098|Starbase Display List Programmer's Manual B2355-90099|Starbase Technical Addendum B2355-90100|Installing & Administering Internet Services B2355-90101|Using Internet Services B2355-90102|HP-UX Documentation: What's Available and How to Order It B2355-90107|Managing HP-UX Software with SD-UX B2355-90108|iFor/LS Quick Start Guide B2355-90112|Quick Guide to Installing HP-UX 10.20 B2355-90113|HP-UX Distributed Print Service Administration Guide B2355-90114|HP-UX Distributed Print Service User's Guide B2355-90119|Installing HP-UX 10.20 and Updating 10.0x to 10.20 B2355-90652|Programming on HP-UX B2363-90205|HP-PHIGS Graphics Techniques B2390-90005|ARTCore Programmer's Manual B2390-90006|ARTCore Development Read Me First B2391-90006|ARTCore Runtime Read Me First B2415-90003|Technical Addendum for HP Pascal/HP-UX B2433-90029|HP Micro Focus COBOL Language Reference, Additional Topics B2433-90031|HP Micro Focus COBOL User's Guide B3176-90003|PEXlib Programming Manual B3176-90004|PEXlib Reference Manual B3176-90042|Portable Programming with CGE PEX 5.1 B3176-90048|PEXlib Implementation and Programming Supplement B3176-90049|PEXlib Development Read Me First B3176-90055|PEXlib Implementation and Programming Supplement B3177-90005|PEXlib Runtime Read Me First B3190-90011|DCE Application Environment Specification B3190-90018|Understanding DCE B3190-90029|Guide to Writing DCE Applications B3190-90037|OSF DCE Application Development Reference B3190-90038|OSF DCE Application Development Guide, I B3190-90039|OSF DCE Application Development Guide, II B3190-90040|OSF DCE Application Development Guide, III B3190-90046|Introduction to OSF DCE B3190-90046|Introduction to OSF DCE B3190-90047|OSF DCE Command Reference B3190-90048|OSF DCE System Administration: Core Components B3190-90049|OSF DCE DFS Administration Guide & Reference B3190-90050|OSF DCE GDS Aministration Guide & Reference B3190-90052|Planning and Configuring HP DCE B3782-90011|Read Me Before Installing HP-UX 10.0 B3782-90033|Release Notes for HP-UX 10.0 B3782-90034|Moving HP-UX 9.x Code and Scripts to 10.x (Analysis & Conversion) B3782-90073|Upgrading from HP-UX 9.x to 10.x B3782-90076|Read Me Before Preparing for Upgrade from HP-UX 9.x to 10.x B3782-90074|Read Me Before Installing or Upgrading HP-UX 10.10 B3782-90103|Read Me Before Installing or Updating HP-UX 10.20 B3832-90001|Managing MC/ServiceGuard B3834-90002|HP Process Resource Manager User's Guide B3834-90003|HP Process Resource Manager Version A.00.02 Release Notes B3906-90001|HP-UX FORTRAN/9000 Programmer's Guide B3906-90002|HP-UX FORTRAN/9000 Programmer's Reference B3906-90003|HP-UX Floating-Point Guide B3928-90001|HP Online JFS Installation Instructions B3939-90002|HP-PHIGS Development Product Read Me First B3939-90003|HP-PHIGS C and FORTRAN Binding Reference B3939-90004|HP-PHIGS Workstation Characteristics and Implementation B3940-90001|HP-PHIGS Runtime Read Me First B3941-90001|Read Before Installing PowerShade J2120-62000|Using the HP DTC Manager/UX J2120-90013|HP DTC Manager/UX: Release Notes J2157-90003|FDDI/9000 Installation and Administration Guide J2157-90006|Installing and Administering FDDI J2157-90007|FDDI/9000 Quick Installation Guide J2165-90008|Token Ring S700 10.0 Quick Installation J2165-90016|Token Ring for Series 700 Release Notes J2165-90017|EISA Token Ring Release Notes J2166-90008|Token Ring S800 10.0 Quick Installation J2166-90011|Token Ring for Series 800 Release Notes J2237-90005|STREAMS/UX for HP9000 Reference Manual J2399-90000|VT3K Quick Reference J2399-90001|VT3K Customer Letter J2650-90002|SNAplus Installation Guide J2650-90011|SNAplus Diagnostic Guide J2650-90021|SNAplus Link Administrator's Guide J2650-90031|SNAplus Remote Configuration Guide J2650-90041|SNAplus Text Configuration Guide J2650-90050|SNAplus Link NetWork Management Administration J2650-90060|Release Notes: SNAplus 10.0 J2651-90002|SNAplus 3270/3179G Administrator's Guide J2651-90011|SNAplus 3270/TN3270 HLLAPI Programmer's Guide J2651-90021|SNAplus 3270/3179G User's Guide J2651-9J001|SNAplus 3270/3179G Administration Guide J2652-90002|SNAplus RJE Administrator's Guide J2652-90010|SNAplus RJE User's Guide J2653-90002|SNAplus API Administrator's Guide J2653-90010|SNAplus API APPC Programmer's Guide J2653-90020|SNAplus API CPI-C Programmer's Guide J2653-90030|SNAplus API LUA Programmer's Guide J2653-90040|SNAplus API CSV Programmer's Guide J2655-90003|EISA 100VG AnyLAN Quick Installation Guide J2655-90004|Installing and Administering EISA/100VG AnyLAN J2655-90011|100VG AnyLAN for Series 700 Release Notes J2656-90001|TN3270 Administration Guide J2656-90010|TN3270 User's Guide J2669-90005|LMU Installation & Administration J2669-90006|LMU Troubleshooting and Commands J2669-90007|LMU 1.x to 2.2 Migration J2669-90008|Using LMU 2.2 J2671-90008|Netware v3.12 Installation and Administration J2671-90009|Netware v3.12 Release Notes J2695-90002|EISA 100VG AnyLan for Series 800 Release Notes .TE .PP For information about the availability of any of these manuals in your local language, contact your sales center. .PP For HP Micro Focus COBOL manuals, contact your HP sales representative and request the manuals-only option of the product. .PP Hewlett-Packard also recommends the following commercial manuals: .PP Kornshell Programming Tutorial, Addison-Wesley (to order, phone 1-800-822-6339) UNIX C Shell Field Guide, Prentice Hall (to order in the U.S., phone 515-284-6761; to order outside of the U.S., phone 201-767-4990) Developing and Localizing International Software, Prentice Hall (to order in the U.S., phone 515-284-6761; to order outside of the U.S., phone 201-767-4990) Using C-Kermit, Columbia University, Digital Press (to order, phone 212-854-3703) Managing UUCP and Usenet, O'Reilly (to order, phone 1-800-998-9938) Using UUCP and Usenet, O'Reilly (to order, phone 1-800-998-9938) Go Solo - How to Implement and Go Solo With the Single UNIX Specification, X/Open, Prentice Hall .ift .RE .\" .\" index@\f1manuals \- current list of HP-UX documentation@@@\f3manuals(5)\f1 .\" index@\f1list of orderable HP-UX manuals@@@\f3manuals(5)\f1 .\" index@\f1how to order HP-UX manuals@@@\f3manuals(5)\f1 .\" index@\f1orderable HP-UX manuals, list of@@@\f3manuals(5)\f1 .\" index@\f1manuals, list of orderable HP-UX@@@\f3manuals(5)\f1 .\" index@\f1HP-UX manuals, list of orderable@@@\f3manuals(5)\f1 .\" index@\f1documentation, list of orderable HP-UX@@@\f3manuals(5)\f1 .\" .\" toc@\f3manuals(5)\f1@@@current list of orderable HP-UX documentation\f1 .\" $Header: math.5,v 72.5 94/11/15 09:57:36 ssa Exp $ .TA m .TH math 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME math \- math functions and constants .SH SYNOPSIS .B #include .SH DESCRIPTION This file contains declarations of all the functions in the Math Library (described in Section .SM (3M)\s0), as well as various functions in the C Library (Section .SM (3C)\s0) that return floating-point values. .PP It defines the structure and constants used by the .IR matherr (3M) error-handling mechanisms, including the following constant used as an error-return value: .RS .TP 12 .SM HUGE_VAL The maximum non-infinity value of a double-precision floating-point number. .RE .PP The following mathematical constants are defined for user convenience: .RS .TP 12 .SM M_E The base of natural logarithms .RI ( e ). .TP .SM M_LOG2E The base-2 logarithm of .IR e . .TP .SM M_LOG10E The base-10 logarithm of .IR e . .TP .SM M_LN2 The natural logarithm of 2. .TP .SM M_LN10 The natural logarithm of 10. .TP .SM M_PI The ratio of the circumference of a circle to its diameter. (There are also several fractions of its reciprocal and its square root.) .TP .SM M_SQRT2 The positive square root of 2. .TP .SM M_SQRT1_2 The positive square root of 1/2. .RE .PP For the definitions of various machine-dependent ``constants'', see the description of the .RB < values.h > header file. .SH FILES /usr/include/math.h .SH "SEE ALSO" intro(3), matherr(3M), values(5). .SH STANDARDS CONFORMANCE .RC < math.h ">: AES, SVID3, XPG2, XPG3, XPG4" .\" .\" index@<\f4math.h\f1> \- math functions and constants@@@\f3math(5)\f1 .\" index@math functions and constants@@@\f3math(5)\f1 .\" index@functions and constants, math@@@\f3math(5)\f1 .\" index@constants, math functions and@@@\f3math(5)\f1 .\" .\" toc@\f3math(5)\f1:\0\0\f2math\f1@@@math functions and constants .\" .\" fileset_database@math.5 SYS-ADMIN-MAN .\" $Header: mknod.5,v 72.4 94/09/20 15:16:01 ssa Exp $ .TA m .TH mknod 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mknod.h \- header file of macros for handling device numbers .SH SYNOPSIS .C "#include " .SH DESCRIPTION The header file .CR defines macros to create and interpret device identification numbers for use with the .CR mknod() system call (see .IR mknod (2)). .PP The use of these macros is architecture-dependent. See the System Administration Manual for your system for information on how to select major and minor device numbers. .PP .CR mknod.h contains the macro .IP .C "dev_t makedev(int major, int minor)" .PP which packs the major and minor components into a device identification number suitable for the .IR dev argument of .CR mknod() , and the two macros: .IP .C "int major(dev_t dev)" .br .C "int minor(dev_t dev)" .PP which extract the major and minor number components, respectively, from a device identification number, .IR dev . .PP The macro .CR MINOR_FORMAT is a .CR printf() specification (see .IR printf (3S)) that prints the minor number in the format best suited to the particular implementation; it is used by the long format of the .CR ls command (see .IR ls (1)) to show the minor numbers for device files. .PP The base of the number is indicated in the same way as in the C programming language: no leading zero for decimal, leading zero for octal, and leading .CR 0x for hexadecimal. .SH SEE ALSO ls(1), mknod(1M), mknod(2), printf(3S). .\" .\" index@\f1device numbers, header file of macros for handling@@@\f3mknod(5)\f1 .\" index@\f1header file of macros for handling device numbers@@@\f3mknod(5)\f1 .\" index@\f1macros for handling device numbers, header file of@@@\f3mknod(5)\f1 .\" index@\f4mknod.h\f1 \- header file of macros for handling device numbers@@@\f3mknod(5)\f1 .\" .\" links@mknod.5 mknod.h.5 .\" .\" toc@\f3mknod(5)\f1:\0\0\f4mknod\f1@@@macros for handling device numbers .\" $Header: mknod.5,v 72.4 94/09/20 15:16:01 ssa Exp $ .TA m .TH mknod 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mknod.h \- header file of macros for handling device numbers .SH SYNOPSIS .C "#include " .SH DESCRIPTION The header file .CR defines macros to create and interpret device identification numbers for use with the .CR mknod() system call (see .IR mknod (2)). .PP The use of these macros is architecture-dependent. See the System Administration Manual for your system for information on how to select major and minor device numbers. .PP .CR mknod.h contains the macro .IP .C "dev_t makedev(int major, int minor)" .PP which packs the major and minor components into a device identification number suitable for the .IR dev argument of .CR mknod() , and the two macros: .IP .C "int major(dev_t dev)" .br .C "int minor(dev_t dev)" .PP which extract the major and minor number components, respectively, from a device identification number, .IR dev . .PP The macro .CR MINOR_FORMAT is a .CR printf() specification (see .IR printf (3S)) that prints the minor number in the format best suited to the particular implementation; it is used by the long format of the .CR ls command (see .IR ls (1)) to show the minor numbers for device files. .PP The base of the number is indicated in the same way as in the C programming language: no leading zero for decimal, leading zero for octal, and leading .CR 0x for hexadecimal. .SH SEE ALSO ls(1), mknod(1M), mknod(2), printf(3S). .\" .\" index@\f1device numbers, header file of macros for handling@@@\f3mknod(5)\f1 .\" index@\f1header file of macros for handling device numbers@@@\f3mknod(5)\f1 .\" index@\f1macros for handling device numbers, header file of@@@\f3mknod(5)\f1 .\" index@\f4mknod.h\f1 \- header file of macros for handling device numbers@@@\f3mknod(5)\f1 .\" .\" links@mknod.5 mknod.h.5 .\" .\" toc@\f3mknod(5)\f1:\0\0\f4mknod\f1@@@macros for handling device numbers .\" $Header: mm.5,v 72.5 94/11/30 10:11:58 ssa Exp $ .TA m .TH mm 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mm \- the MM macro package for formatting documents .SH SYNOPSIS .B mm .RI [ \|options\| ] .RI [ \|files\| ] .br .B nroff \-mm .RI [ \|options\| ] .RI [ \|files\| ] .SH DESCRIPTION This package provides a formatting capability for a very wide variety of documents. The manner in which a document is typed in and edited is essentially independent of whether the document is to be eventually formatted at a terminal or is to be phototypeset. See the references below for further details. The .B \-mm option causes .IR nroff (1) and .I troff to use the non-compacted version of the macro package. .SH FILES .PD 0 .TP 35 /usr/share/lib/macros/mmn non-compacted version of the package .TP /usr/share/lib/tmac/tmac\f3.\fPm pointer to the non-compacted version of the package .PD .SH SEE ALSO mm(1), nroff(1). .PP .I "MM \- Memorandum Macros" tutorial in .IR "Text Formatters User's Guide" . .\" index@\f2mm\f1 \- the \s-1MM\s+1 macro package for formatting documents@@@\f3mm(5)\f1 .\" index@\s-1MM\s+1 macro package for formatting documents@@@\f3mm(5)\f1 .\" index@macro package for formatting documents, \s-1MM\s+1@@@\f3mm(5)\f1 .\" index@formatting documents, \s-1MM\s+1 macro package for@@@\f3mm(5)\f1 .\" index@documents, \s-1MM\s+1 macro package for formatting@@@\f3mm(5)\f1 .\" .\" toc@\f3mm(5)\f1:\0\0\f2mm\f1@@@the \s-1MM\s+1 macro package for formatting documents .\" .\" fileset_database@mm.5 SYS-ADMIN-MAN .\" $Header: mman.5,v 74.1 95/05/10 21:14:36 ssa Exp $ .TA m .TH mman 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME memory mapping definitions .SH SYNOPSIS .C "#include " .SH DESCRIPTION The .RC < sys/mman.h > header defines the following symbolic constants for use with the .C madvise() function: .RS .TP 25 .C MADV_NORMAL No further special treatment. .PD 0 .TP .C MADV_RANDOM Expect random page references. .TP .C MADV_SEQUENTIAL Expect sequential page references. .TP .C MADV_WILLNEED Will need these pages. .TP .C MADV_DONTNEED Will not need these pages. .TP .C MADV_SPACEAVAIL Ensure that resources are reserved. .PD .RE .PP The following symbolic constants are defined for use with the .C mmap() and .C mprotect() functions: .RS .TP 25 .C PROT_READ Region can be read. .PD 0 .TP .C PROT_WRITE Region can be written. .TP .C PROT_EXEC Region can be executed. .TP .C PROT_NONE Region cannot be accessed. .PD .RE .PP The following symbolic constants are defined for use with the .C mmap() function: .RS .TP 25 .C MAP_FILE Map a file. .PD 0 .TP .C MAP_ANONYMOUS Map an unnamed memory region. .TP .C MAP_VARIABLE Place region at implementation-computed address. .TP .C MAP_FIXED Place region at specified address. .TP .C MAP_SHARED Share changes made to mapped region. .TP .C MAP_PRIVATE Changes to mapped region are private to a process. .PD .RE .PP The following symbolic constants are defined for use with the .C msync() function: .RS .TP 25 .C MS_SYNC Perform synchronous writes. .PD 0 .TP .C MS_ASYNC Perform asynchronous writes. .TP .C MS_INVALIDATE Invalidate cached pages. .PD .RE .PP The following symbolic constants are defined for use with the .CR msem_init() , .CR msem_lock() , and .C msem_unlock() functions: .RS .TP 25 .C MSEM_LOCKED Create semaphore in locked state. .PD 0 .TP .C MSEM_UNLOCKED Create semaphore in unlocked state. .TP .C MSEM_IF_NOWAIT Do not wait if semaphore is locked. .TP .C MSEM_IF_WAITERS Do not unlock if semaphore has no waiters. .PD .RE .PP The .C typedef struct msemaphore is defined for use with the .CR msem_init() , .CR msem_lock() , .CR msem_unlock() , and .C msem_remove() functions. .SH SEE ALSO mmap(2), munmap(2), mprotect(2), msync(2), madvise(2), msem_init(2), msem_remove(2), msem_lock(2), msem_unlock(2). .\" .\" toc \f3mman(5)\f1@@@memory mapping definitions .\" .\" index@\f1memory mapping definitions@@@\f3mman(5)\f1 .\" index@\f1mapping definitions, memory@@@\f3mman(5)\f1 .\" index@\f1definitions, memory mapping@@@\f3mman(5)\f1 .\" .\" $Header: ndir.5,v 72.3 93/01/14 16:04:01 ssa Exp $ .TA n .TH ndir 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ndir.h \- format of HP-UX directory streams .SH SYNOPSIS .B #include .SH DESCRIPTION This header file defines data types used by the directory stream routines described in .IR directory (3C). It is provided to allow older .SM HP-UX programs to compile unmodified. The header file .RB < dirent.h > described on .IR dirent (5) should be used in all new programs for compatibility with System V Release 3, the .IR "X/Open Portability Guide" , and the .SM IEEE P1003.1 POSIX standard. .PP The following data types are defined: .RS .TP 15 .SM .B DIR A structure containing information about an open directory stream. .TP .B "struct direct" A structure defining the format of entries returned by the old .SM HP-UX .I readdir function (see .IR directory (3C)). .RE .PP The .B "struct direct" structure includes the following members: .RS .PP .TS l l. char d_name[\s-1MAXNAMLEN\s0+1]; /* name of directory entry */ long d_ino; /* file serial number */ short d_namlen; /* length of string in d_name */ short d_reclen; /* length of this record */ .TE .RE .PP The constant .SM .B MAXNAMLEN is defined in .RB < ndir.h >. .PP This file also contains external declarations for the functions in the .IR directory (3C) package, including the following declaration: .IP .B extern struct direct *readdir(\|); .SH WARNINGS .IR lint (1) might complain about programs that include this file, although they compile and run correctly. .SH AUTHOR .I ndir.h was developed by the University of California, Berkeley, and HP. .SH "SEE ALSO" directory(3C), dirent(5). .\" index@\f2ndir.h\f1 \- format of \s-1HP-UX\s+1 directory streams@@@\f3ndir(5)\f1 .\" index@format of \s-1HP-UX\s+1 directory streams@@@\f3ndir(5)\f1 .\" index@directory streams, \s-1HP-UX\s+1, format of@@@\f3ndir(5)\f1 .\" index@streams, \s-1HP-UX\s+1 directory, format of@@@\f3ndir(5)\f1 .\" .\" toc@\f3ndir(5)\f1:\0\0\f2ndir.h\f1@@@format of \s-1HP-UX\s+1 directory streams .\" .\" fileset_database@ndir.5 SYS-ADMIN-MAN .\" $Header: nlio.5,v 72.4 93/01/14 16:08:53 ssa Exp $ .TA n .TH nlio 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlio \- Native Language \s-1I/O (NLIO)\s0 Subsystem .SH DESCRIPTION The .SM HP-UX Native Language .SM I/O (NLIO) Subsystem is a set of servers, filters, utilities and libraries that provide means to efficiently input and output multibyte characters on multibyte terminals, printers and the X Window System. .PP .SM NLIO provides application-transparent multibyte code conversion between the internal code and the external code. Application programs including .SM HP-UX commands can utilize the feature of the multibyte character .SM I/O over multibyte terminals, printers and the X Window System without modifying the .SM I/O portion of the program code or linking any special .SM I/O library. .PP The supported languages are Japanese, Korean, Simplified Chinese and Traditional Chinese. .PP .SM NLIO supports the following functionalities: .RS .TP 3 \(bu Read and write multibyte characters on .SM HP Asian terminals and the X Window System. .TP \(bu Print multibyte characters with .SM HP Asian or .SM HP LaserJet printers. .TP \(bu Allow .SM HP-UX commands, such as .IR cat (1), .IR more (1), and .IR vi (1), to use multibyte characters. .TP \(bu Create and modify user-defined characters. .TP \(bu Support multibyte characters for the .IR "Starbase Graphics Library" . .TP \(bu Provide language-specific popular input methods. .TP \(bu Support code conversion utilities and libraries. .TP \(bu Create and modify user-defined dictionaries for Japanese and Korean. .TP \(bu Read and write Japanese multibyte characters on a bitmap display. .TP \(bu Write Japanese multibyte characters on a bitmap display with the .SM FAFM libraries. .TP \(bu Provide a set of libraries for Japanese Kana-to-Kanji conversion. .RE .SH AUTHOR .I nlio was developed by HP. .SH SEE ALSO .I "Native Language I/O" manuals .\" .\" toc@\f3nlio(5)\f1:\0\0\f4nlio\fP@@@Native Language \s-1I/O (NLIO)\s0 Subsystem .\" .\" index@\f4nlio\fP \- Native Language \s-1I/O (NLIO)\s0 Subsystem@@@\f3nlio(5)\f1 .\" index@Native Language \s-1I/O (NLIO)\s0 Subsystem@@@\f3nlio(5)\f1 .\" index@Language \s-1I/O (NLIO)\s0 Subsystem, Native@@@\f3nlio(5)\f1 .\" index@\s-1I/O (NLIO)\s0 Subsystem, Native Language@@@\f3nlio(5)\f1 .\" index@\s-1NLIO\s0 Subsystem, Native Language \s-1I/O\s0@@@\f3nlio(5)\f1 .\" .\" fileset_database@nlio.5 SYS-ADMIN-MAN ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\"Copyright Hewlett-Packard Company 1991 ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" ...\" .rm zA .rm zZ .TH passwd_override "5" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "Security Service commands" "\*Lpasswd_override\*O" .iX "-[" "registry" "local overrides" .iX "files" "registry database override" .iX "\*Lpasswd_override\*O file" .iX "registry database override" "files" .SH NAME \*Lpasswd_override\*O - The registry database override file .zA "defect,6211,R1.0.3,removed SYNOPSIS with full pathname" .zZ "defect,6211,R1.0.3,removed SYNOPSIS with full pathname" .SH "DESCRIPTION" .PP The \*Vdcelocal\*L/etc/passwd_override\*O administrative file lets you override the password, GECOS, home directory, login shell, group membership, and principal UNIX ID information stored in the network registry database. .P The \*Lpasswd_override\*O file is stored on each host machine. Any changes you make to it are in effect for the local machine only, and have no effect on the centralized registry. You may find \*Lpasswd_override\*O especially useful for excluding people from using certain machines, establishing local root passwords, or tailoring local user environments. .SS "The passwd_override File Format" The format of the \*Lpasswd_override\*O entries is similar to entries in the UNIX password file. The format is .sS \*Vprincipal_name\*L:\*Vpasswd\*L:\*Vprincipal_uid\*L:\*Vgroup_id\*L:\*VGECOS\*L:\*Vhome_dir\*L:\*Vlogin_shell\*O .sE .PP In an override entry, \*Vprincipal_name\*O, \*Vprincipal_uid\*O, and \*Vgroup_id\*O fields are keyfields. You must enter one of them to identify the principal or group to which the overrides apply. The keyfield is used to perform a lookup in the override file. The lookup is performed in order as the entries are specified in an override entry: first by principal name, then by principal UNIX ID, and finally by group UNIX ID. If you specify more than one keyfield in an override entry, the first keyfield specified is used as the lookup key; subsequent keyfields are used as overrides. .SS "Field Descriptions" .PP Each of the entries in the \*Lpasswd_override\*O file is described below. .zA "defect,4890,R1.0.2,clarify keyfield use" .VL .LI "\*Vprincipal_name\*O" A keyfield that contains a principal name that identifies the account to which the overrides apply. Enter \*Vprincipal_name\*O to apply the override only to the account for the principal's primary name and not to any accounts for the principal's aliases. .LI "\*Vpasswd\*O" The encrypted password. If you specify an override in this field, the password you enter is in effect for this local machine only. .PP When you override a principal's password, only the principal's local credentials are obtained at login, not the principal's network credentials. Without network credentials, the principal cannot access the network registry and obtain the information normally provided at network login. Therefore, you must supply all this information in the \*Lpassword_override\*O file entry. For overrides to passwords, you must enter all fields in the override entry, including all keyfields. .PP You can also specify \*LOMIT\*O in the \*Vpasswd\*O field to disallow login on the local machine. The use of \*LOMIT\*O in conjunction with an option to the \*Lpasswd_export\*O command also prevents the inclusion of this principal in the password file created by \*Lpasswd_export\*O. (See the section entitled "Using OMIT," later in this command reference, for details.) .LI "\*Vprincipal_uid\*O" An encrypted principal UNIX ID. This field can function as a keyfield (when the \*Vprincipal_name\*O keyfield is not entered) or as an override field (when the \*Vprincipal_name\*O keyfield is entered). Enter \*Vprincipal_uid\*O and not \*Vprincipal_name\*O when you want to apply the overrides to all of a principal's accounts, including any accounts for the principal's aliases. The \*Vprincipal_uid\*O keyfield is especially useful for overrides to\*L root\*O. For example, if\*L root\*O has an alias of\*L virtuoso\*O, an override keyed by principal name applies only when\*L root\*O logs in as\*L root\*O. An override keyed by root's \*Vprincipal_uid\*O applies when \*Lroot\*O logs in as \*Lroot\*O, as \*Lvirtuoso\*O, and under any other alias. .PP Enter \*Vprincipal_uid\*O and \*Vprincipal_name\*O to override the UNIX ID of the named principal. .LI "\*Vgroup_id\*O" A UNIX group ID. This field can function as a keyfield, when no other keyfields are entered, or as a field containing an override, when entered in conjunction with \*Vprincipal_name\*O or \*Vprincipal_uid\*O. .PP Enter \*Vgroup_uid\*O and no other keyfield (\*Vprincipal_name\*O or \*Vprincipal_uid\*O) to apply the override to all members of the group identified by \*Vgroup_uid\*O. In this instance the \*Vgroup_uid\*O field functions as a keyfield, identifying the accounts to which to apply the overrides (that is, accounts whose principal is a member of the specified group). .PP Enter \*Vgroup_uid\*O and \*Vprincipal_name\*O to change the group of the principal identified by \*Vprincipal_name\*O to the group identified by \*Vgroup_uid\*O. The change applies only to the account for the principal's primary name, not to any accounts for the principal's aliases. Enter \*Vgroup_uid\*O and \*Vprincipal_uid\*O to apply the group override to all of the principal's accounts, including any for the principal's aliases. In these instances the \*Vgroup_uid\*O field functions as a field supplying override information, not as a keyfield. .LI "\*VGECOS\*O" The account's GECOS field. You can specify an override in this field. To keep it unchanged, leave it empty. .LI "\*Vhome_dir\*O" The account's home directory. You can specify an override in this field. To keep it unchanged, leave it empty. .LI "\*Vlogin_shell\*O" The account's log-in shell. You can specify an override in this field. To keep it unchanged, leave it empty. .LE .zZ "defect,4890,R1.0.2,clarify keyfield use" .SS "Leaving Fields Blank" .PP If you do not want to override an item, leave its field blank, separating each blank field with a : (colon). (You must enter one of the keyfields, however, to identify the principal or group for which you are creating overrides.) .zA "def,7274:.R1.0.2,colons required for trailing blanks" You are required to enter the colons associated with any blank trailing fields. .zZ "def,7274:.R1.0.2,colons required for trailing blanks" .SS "Using OMIT" .PP If you enter either the word \*LOMIT\*O or another invalid password string (such as * (asterisk) or \*LNO GOOD\*O) in the \*Vpasswd\*O field, the principal (or set of principals) will be unable to log in to the local machine. If you specify \*LOMIT\*O and run \*Lpasswd_export\*O with the \*L-x\*O option, the named principal (or set of principals) will not appear in the \*L/etc/passwd\*O file produced by \*Lpasswd_export\*O. .PP You should also be aware that, if you have omitted principials from the \*L/etc/passwd\*O file, information about those principals will not be available to any programs that use the password file. For example, the \*Lls -l\*O and the \*Lfinger\*O commands both access the password file to obtain further information about a principals. If the principal is omitted, no password entry will exist and no information will be available. For this reason, you should use \*LOMIT\*O to omit principals from the \*L/etc/passwd\*O file only if your user community is very large and either of the following conditions occur: .ML .LI The \*Lpasswd\*O file is taking up too much space. .LI User-ID-to-name mapping is too slow (during \*Lls -l\*O, for example). .LE .SH "NOTES" Principals can update their entries in the override file for the local host by using \*Lchpass\*O. Refer to the \*Lchpass\*O reference page for details. .SH "EXAMPLES" .AL .iX "login" "preventing" .LI To prevent the principal with a UNIX ID of 52 from logging in to the local machine, the entry in the \*Lpasswd_override\*O file is as follows: .oS :exclude:52:::: .oE .zA "def,4466,R1.0.2,Change evil_users to group ID 25" .LI To prevent members of the group identified by a UNIX ID of 25 from logging in to a node and to omit them from inclusion in the password file, put \*LOMIT\*O in the \*Vpasswd\*O field: .zZ "def,4466,R1.0.2,Change evil_users to group ID 25" .oS :OMIT::25::: .oE .PP Then run the following \*Lpasswd_export\*O command with the \*L-x\*O option to omit these principals from \*L/etc/passwd\*O file: .iS \*Vdcelocal\*L/etc/passwd_export -x \*O .iE .LI To change the password, home directory, and initial shell for \*Lmozart\*O's account, the entry is as follows: .oS mozart:sq1Rc1Urrb1L6:678:893:Wolfgang A. Mozart:/aria/wolfgang:/bin/csh .oE .LI To override the home directory for the account identified by\*L mozart\*O the entry is as follows: .oS mozart:::::/aria/wolfgang .oE .LE .SH "RELATED INFORMATION" .PP Commands: \*Lcrypt(1)\*O, \*Lchpass(1)\*O, \*Lfinger(1)\*O, \*Llogin(1)\*O, \*Ladduser(8)\*O, \*Lrgy_edit(1m)\*O, \*Lpasswd_export(1m)\*O .PP Functions: \*Lgetpwent(3)\*O .PP Files: \*Lgroup(5)\*O .iX "-]" "Security Service commands" "\*Lpasswd_override\*O" .iX "-]" "registry" "local overrides" .\" $Header: pfs_exports.5,v 76.3 95/07/24 16:26:56 ssa Exp $ .\" SCCS Keywords @(#)pfs_exports.5 1.2 12/1/91 .TA p .TH pfs_exports 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfs_exports, pfs_xtab \- directories to export to PFS clients .SH SYNOPSIS .C /etc/pfs_exports .PP .C /etc/pfs_xtab .SH DESCRIPTION The .CR /etc/pfs_exports file contains entries for directories that can be exported to PFS clients. This file is read automatically by the .IR pfs_exportfs (1M) command. If you change this file, you must run .IR pfs_exportfs (1M) for the changes to affect the daemon's operation. .PP It is recommended that you place a command in .IR rc (1M) so that .IR pfs_exportfs (1M) is executed at boot time. .PP The .CR /etc/pfs_xtab file contains entries for directories that are .I currently exported. You should not modify this file directly. Future updates to the .CR PFS package will contain libraries for editing this file. (Use the .CR \-u option of .CR pfs_exportfs to remove entries from this file). .PP An entry for a directory consists of a line of the following form: .IP .I directory\ \ \ \f3\-\f2option\f1[\f3,\|\f2option\f1 ]\|.\|.\|. .TP 15 .I directory is the pathname of a directory (or file). .TP .I option is one of .RS .TP .CI access= client [: client ]\|.\|.\|. Give mount access to each .I client listed. A .I client must be a hostname. The default value allows any machine to mount the given directory. .RE .PP A .RC ` # ' (pound-sign) anywhere in the file indicates a comment that extends to the end of the line. .SH EXAMPLE .ft B .ta 1i 3i .nf /usr/local # export to the world /usr2 \-access=hermes:zip:tutorial # export to only these machines .fi .ft R .br .ne 6 .SH AUTHOR .CR pfs_exports was developed by Young Minds, Inc. .SH FILES .PD 0 .TP 20 .C /etc/pfs_exports .TP .C /etc/pfs_xtab .TP .C /etc/hosts .PD .SH SEE ALSO hosts (5), pfs_exportfs (1M), pfsd (1M), pfs_mountd (1M), rc (1M). .\" .\" index@\f4pfs_exports\f1 \- directories to export to PFS clients@@@\f3pfs_exports(5)\f1 .\" index@\f1directories to export to PFS clients@@@\f3pfs_exports(5)\f1 .\" index@\f1PFS clients, directories to export to@@@\f3pfs_exports(5)\f1 .\" index@\f1clients, PFS, directories to export to@@@\f3pfs_exports(5)\f1 .\" index@\f1export directories, to PFS clients@@@\f3pfs_exports(5)\f1 .\" .\" toc@\f3pfs_exports(5)\f1:\0\0\f4pfs_exports\f1@@@directories to export to PFS clients .\" toc@\f4pfs_xtab(5)\f1:\0\0directories to export to PFS clients@@@\f1see \f3fps_exports(5)\f1 .\" .\" links@pfs_exports.5 pfs_xtab.5 .\" .\" fileset_database@pfs_exports.5 CORE-ENG-A-MAN .\" $Header: pfs_fstab.5,v 76.2 95/06/20 15:37:17 ssa Exp $ .\" @(#)fstab.5 1.25 89/03/27 SMI; .TA p .TH pfs_fstab 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfs_fstab, mtab \- static file system mounting table, mounted file systems table .SH SYNOPSIS .C /etc/pfs_fstab .PP .C /etc/mtab .SH DESCRIPTION The .CR /etc/pfs_fstab file contains entries for CD-ROM file systems and disc images to mount using the .IR pfs_mount (1M) command, which is normally invoked by .IR rc (1M) script at boot time. This file is used by various utilities such as .CR pfs_mount , and .CR pfs_umount . .PP The .CR /etc/mtab file contains entries for file systems .I currently mounted, and is read by programs using the routines described in .IR getmntent (3). .CR umount (see .IR mount (1M)) removes entries from this file. .PP Each entry consists of a line of the form: .IP .I filesystem\ \ \ directory\ \ \ type\ \ \ options\ \ \ freq\ \ \ pass .PP .TP 10 .I filesystem is the pathname of a raw or block-special device, the name of a remote file system in .IC host : pathname form, or the name of a file created with MakeDisc. .TP .I directory is the pathname of the directory on which to mount the file system. .TP .I type is the file system type, which can be one of: .RS .RS .PD 0 .TP 18 .C pfs-iso9660 to mount a device as iso9660. .TP .C pfs-hsfs to mount a device as hsfs. .TP .C pfs-rrip to mount a device as rrip. .TP .C pfs-nfs to mount an exported PFS file system .RE .RE .PD .TP .I options contains a comma-separated list (no spaces) of mounting options, some of which can be applied to all types of file systems, and others which only apply to specific types. .RS .IP .I options valid on .I all file systems: .PD 0 .RS .IP .TP 19 .BR ro Even if not specified, this option is implied. .TP .CR suid \||\| nosuid Setuid execution allowed or disallowed. .TP .CR bg \||\| fg If the first attempt fails, retry in the background, or, in the foreground. .TP .CI retry= n The number of times to retry the mount operation. .TP .CI rsize= n Set the read buffer size to .I n bytes. .TP .CI timeo= n Set the PFS timeout to .I n tenths of a second. .TP .CI retrans= n The number of PFS retransmissions. .TP .CR soft \||\| hard Return an error if the server does not respond, or continue the retry request until the server responds. .TP .C intr Allow keyboard interrupts on hard mounts. .IP .RE .IP .I options specific to .CR iso9660 and .CR hsfs file systems: .IP .RE .RS .RS .TP 20 .CR xlat=xlat_flags .I xlat_flags is a colon (:) separated list of translation options. Currently supported are no_version, dot_version, lower_case, and unix. .RE .RE .PD .TP .I freq is the interval (in days) between dumps. For a PFS file system, this should be 0. .TP .I pass is the .IR fsck (1M) pass in which to check the partition. For a PFS file system, this should be 0. .PP A pound-sign .RC ( # ) as the first character indicates a comment line which is ignored by routines that read this file. The order of records in .CR /etc/pfs_fstab is important because .CR fsck , .CR mount , and .CR umount process the file sequentially; an entry for a file system must appear .I after the entry for any file system it is to be mounted on top of. .SH EXAMPLES /dev/sr0 /cd-rom pfs-iso9660 ro,suid 0 0 .PP example:/home/user /home/user pfs-nfs ro,hard,fg 0 0 .RE .SH AUTHOR .CR pfs_fstab was developed by Young Minds, Inc. .SH FILES .PD 0 .TP 20 .C /etc/pfs_fstab .TP .C /etc/mtab .PD .SH SEE ALSO pfs_mount (1M). .\" .\" index@\f4pfs_fstab\f1 \- static file system mounting table@@@\f3pfs_fstab(5)\f1 .\" index@\f1static file system mounting table@@@\f3pfs_fstab(5)\f1 .\" index@\f1file system mounting table, static@@@\f3pfs_fstab(5)\f1 .\" index@\f1mtab, mounted file systems table@@@\f3pfs_fstab(5)\f1 .\" .\" toc@\f3pfs_fstab(5)\f1:\0\0\f4pfs_fstab\f1@@@static file system mounting table .\" toc@\f4mtab\f1:\0\0mounted file system table@@@\f1see \f3pfs_fstab(5)\f1 .\" .\" fileset_database@pfs_fstab.5 CORE-ENG-A-MAN .\" $Header: pfs_exports.5,v 76.3 95/07/24 16:26:56 ssa Exp $ .\" SCCS Keywords @(#)pfs_exports.5 1.2 12/1/91 .TA p .TH pfs_exports 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfs_exports, pfs_xtab \- directories to export to PFS clients .SH SYNOPSIS .C /etc/pfs_exports .PP .C /etc/pfs_xtab .SH DESCRIPTION The .CR /etc/pfs_exports file contains entries for directories that can be exported to PFS clients. This file is read automatically by the .IR pfs_exportfs (1M) command. If you change this file, you must run .IR pfs_exportfs (1M) for the changes to affect the daemon's operation. .PP It is recommended that you place a command in .IR rc (1M) so that .IR pfs_exportfs (1M) is executed at boot time. .PP The .CR /etc/pfs_xtab file contains entries for directories that are .I currently exported. You should not modify this file directly. Future updates to the .CR PFS package will contain libraries for editing this file. (Use the .CR \-u option of .CR pfs_exportfs to remove entries from this file). .PP An entry for a directory consists of a line of the following form: .IP .I directory\ \ \ \f3\-\f2option\f1[\f3,\|\f2option\f1 ]\|.\|.\|. .TP 15 .I directory is the pathname of a directory (or file). .TP .I option is one of .RS .TP .CI access= client [: client ]\|.\|.\|. Give mount access to each .I client listed. A .I client must be a hostname. The default value allows any machine to mount the given directory. .RE .PP A .RC ` # ' (pound-sign) anywhere in the file indicates a comment that extends to the end of the line. .SH EXAMPLE .ft B .ta 1i 3i .nf /usr/local # export to the world /usr2 \-access=hermes:zip:tutorial # export to only these machines .fi .ft R .br .ne 6 .SH AUTHOR .CR pfs_exports was developed by Young Minds, Inc. .SH FILES .PD 0 .TP 20 .C /etc/pfs_exports .TP .C /etc/pfs_xtab .TP .C /etc/hosts .PD .SH SEE ALSO hosts (5), pfs_exportfs (1M), pfsd (1M), pfs_mountd (1M), rc (1M). .\" .\" index@\f4pfs_exports\f1 \- directories to export to PFS clients@@@\f3pfs_exports(5)\f1 .\" index@\f1directories to export to PFS clients@@@\f3pfs_exports(5)\f1 .\" index@\f1PFS clients, directories to export to@@@\f3pfs_exports(5)\f1 .\" index@\f1clients, PFS, directories to export to@@@\f3pfs_exports(5)\f1 .\" index@\f1export directories, to PFS clients@@@\f3pfs_exports(5)\f1 .\" .\" toc@\f3pfs_exports(5)\f1:\0\0\f4pfs_exports\f1@@@directories to export to PFS clients .\" toc@\f4pfs_xtab(5)\f1:\0\0directories to export to PFS clients@@@\f1see \f3fps_exports(5)\f1 .\" .\" links@pfs_exports.5 pfs_xtab.5 .\" .\" fileset_database@pfs_exports.5 CORE-ENG-A-MAN .\" $Header: portnls.5,v 72.3 93/01/14 16:04:07 ssa Exp $ .TA p .TH portnls 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME portnls \- MPE Native Language Support routines .SH SYNOPSIS .nf .B /usr/lib/nls/* .fi .SH DESCRIPTION .I portnls contains a set of library routines that perform miscellaneous language-dependent operations. These routines are also available in the .SM HP MPE operating system. .PP Localizable programs written in Pascal, .SM FORTRAN, or .SM COBOL, and making use of these routines, can be written and run under .SM HP-UX, and ported to .SM MPE by a mere recompilation, and vice versa. .PP Each routine is described in an individual manual entry in Section 3X, and can be grouped in the following categories: .SS Language Information Routines: .RS .TP 15 .I nlgetlang Return current language. .TP .I nlinfo Return language-dependent information (data tables). .TP .I nlnumspec Return information needed for formatting and converting numbers. .RE .SS Date and Time Routines: .RS .TP 15 .I almanac Return numeric date information for a date in the packed date format returned by the calendar routine. .TP .I calendar Return an MPE calendar date. .TP .I clock Return an MPE clock value. .TP .I nlconvclock Check and convert a time array to an internal format. .TP .I nlconvcustdate Convert a date array to a packed date format. .TP .I nlfmtcalendar Format a packed date using a localized format. .TP .I nlfmtclock Format time of day using a localized format. .TP .I nlfmtcustdate Format a packed date using a custom date. .TP .I nlfmtdate Format a date and time in a localized format. .TP .I nlfmtlongcal Format a packed date using a long calendar format. .RE .SS Language Formatted-Number Routines: .RS .TP 15 .I nlconvnum Convert a native language formatted number to an ASCII number. .TP .I nlfmtnum Convert an ASCII number to a language-specific formatted number. .RE .SS Character Array Routines: .RS .TP 15 .I nlappend Append the appropriate language ID to a file name. .TP .I nlcollate Compare two character arrays. .TP .I nlfindstr Search for a array in another array. .TP .I nljudge Judge whether a character is a one-byte or multi-byte Asian character. .TP .I nlkeycompare Determine if a character array is almost equal to another. .TP .I nlrepchar Replace non-displayable characters of a array. .TP .I nlscanmove Move, scan and case shift character arrays. .TP .I nlsubstr Extract a subarray of a array. .TP .I nlswitchbuf Convert a array of characters between phonetic order and screen order. .TP .I nltranslate Translate ASCII arrays to EBCDIC using an conversion table. .RE .SS Flags: .I portnls routines may use flags to select their behavior. Individual manual entries contain symbolic names for the values of those flags. Actual implementation of those values (such as unsigned integer values, octal, hexadecimal, or bit values) depends on the specific programming language being used. .PP Some functions are driven by the bit-wise .SM AND or by the bit-wise .SM OR of two of those flags. For example, 0x0051 .SM AND 0x0045 is equal to 0x0041. .PP The following list contains the hexadecimal values of those constants. .PP .TP 8 Mask characters for \f2nlscanmove\f1(3X) flags .TS lp-1 l l. M_L 0x0001 /* lowercase */ M_U 0x0002 /* uppercase */ M_N 0x0004 /* numeric */ M_S 0x0008 /* special */ M_WU 0x0010 /* while/until 0/1 */ M_US 0x0020 /* upshift */ M_DS 0x0040 /* downshift */ M_TB 0x0080 /* two byte only flag */ M_OB 0x0100 /* one byte only flag */ .TE .TP Masks for \f2nlsubstr\f1(3X) .TS lp-1 l l. F_RETURNERR 0x0000 /* Return an error condition */ F_SPP1 0x0001 /* Start from start position + 1 */ F_SPM1 0x0002 /* Start from start position - 1 */ F_SPBL 0x0003 /* Start from start position. Replace character by blank */ F_SP 0x0004 /* Start from start position regardless value of first character */ F_LMP1 0x0010 /* Move until movelength + 1 is reached */ F_LMM1 0x0020 /* Move until movelength - 1 is reached */ F_LMBL 0x0030 /* Move until movelength is reached. Replace character by blank */ F_LM 0x0040 /* Move until movelength is reached regardless value of last byte */ .TE .TP Masks for \f2nlconvnum\f1(3X) .TS lp-1 l l. M_STRIPTHOU 0x0001 /* strip thousands separator */ M_STRIPDEC 0x0002 /* strip decimal separator */ M_NUMBERSONLY 0x0004 /* numbers only in input */ .TE .TP Masks for \f2nlfmtnum\f1(3X) .TS lp-1 l l. M_INSTHOU 0x0001 /* insert thousands separator */ M_INSDEC 0x0002 /* insert decimal separator */ M_CURRENCY 0x0004 /* insert currency symbol */ M_LEFTJUST 0x0008 /* left justify */ M_RIGHTJUST 0x0010 /* right justify */ M_RETLENGTH 0x0018 /* left justify and return length */ .TE .TP Masks for \f2nlnumspec\f1(3X) .TS lp-1 l l. CURRENCY_PRECEDES 0 CURRENCY_SUCCEEDS 1 CURRENCY_REPLACES 2 .TE .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS This library is provided for compatibility with the .SM HP MPE operating system. Use the Native Language Support routines for C programmers described in .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .I portnls was developed by HP. .SH FILES .nf usr/lib/libportnls.a usr/lib/nls/$LANG/custdat.cat .fi .SH SEE ALSO almanac(3X), calendar(3X), clock(3X), hpnls(5), nlappend(3X), nlconvclock(3X), nlconvcustdate(3X), nlconvnum(3X), nlcollate(3X), nlfmtcalendar(3X), nlfmtclock(3X), nlfmtcustdate(3X), nlfmtdate(3X), nlfindstr(3X), nlfmtlongcal(3X), nlfmtnum(3X), nlgetlang(3X), nlinfo(3X), nljudge(3X), nlkeycompare(3X), nlnumspec(3X), nlrepchar(3X), nlscanmove(3X), nlsubstr(3X), nlswitchbuf(3X), nltranslate(3X) .PP .I MPE Intrinsics Reference Manual. .PP .I MPE Native Language Support Reference Manual. .\" index@\f2portnls\f1 \- \s-1MPE\s+1 Native Language Support routines@@@\f3portnls(5)\f1 .\" index@\s-1MPE\s+1 Native Language Support routines@@@\f3portnls(5)\f1 .\" index@Native Language Support routines, \s-1MPE\s+1@@@\f3portnls(5)\f1 .\" index@routines, \s-1MPE\s+1 Native Language Support@@@\f3portnls(5)\f1 .\" .\" toc@\f3portnls(5)\f1:\0\0\f2portnls\f1@@@\s-1MPE\s+1 Native Language Support routines .\" .\" fileset_database@portnls.5 SYS-ADMIN-MAN .\" $Header: quota.5,v 78.1 96/01/22 22:26:23 ssa Exp $ .TA q .TH quota 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME quota \- disk quotas .SH DESCRIPTION Disk quotas can be used by the system administrator to limit the number of files and file blocks owned by a user on a per-file-system basis. Separate limits can be established for both the number of files (inodes) and the number of 1-Kbyte blocks for each user. A .I soft (preferred) and a .I hard limit are established. .PP For example, user .CR joe_doe may have soft limits of 1000 blocks and 200 files and hard limits of 1200 blocks and 300 files on the root file system .RC ( / ) containing his/her .CR HOME directory and .CR /tmp , and soft and hard block limits of 100 and 120, respectively, with no explicit file limit (0), on the mounted file system .CR /mnt . .PP A time limit is established for each file system which determines how long a user is allowed to exceed the soft limit. The default time limit is one week (7 days). .PP When a user exceeds his/her soft limit, a warning is emitted on the user's terminal. The user can continue to increase utilization over the soft limit until he/she either exceeds the hard limit or the established time limit. Once either of these events occurs, a message is sent to the user's terminal and further attempts at file creation and/or increased block utilization will fail. At this point, the user must reduce his/her use of the exceeded limit below the soft limit to restore normal operation. .PP At login time, users exceeding quota limits are reminded (via .IR login (1)) of exceeded quotas and appropriate remedial action. The user can check current quota status at any time with the .CR quota command (see .IR quota (1)). .PP Quota limits and utilization statistics are maintained by the operating system for each file system for which quotas have been enabled (see .IR mount (1M) and .IR quotaon (1M)). .PP Disk quotas are established independently for each user and each file system via the .CR edquota command (see .IR edquota (1M)). This command is also used to establish the limit for the amount of time users are permitted to exceed their soft limit. The default time limit is 1 week. .PP Limits and usage statistics are stored statically in the file .CR quotas on the root of each file system for which they are in effect. This file is synchronized with information in the kernel by the .CR quotactl() system call (see .IR quotactl (2)) and whenever an affected file system is unmounted. .PP Quotas can be enabled automatically at boot or mount time by adding the .CR quotas option to the option list in .CR /etc/fstab (see .IR fstab (4) and .IR mount (1M)). By default, .CR mount does not enable disk quotas. .PP Quotas can subsequently be disabled and re-enabled with the .CR quotaoff and .CR quotaon commands (see .IR quotaon (1M)). When quotas are disabled, the kernel does not maintain usage statistics and the .CR quotas file usage statistics are invalidated by file system activity. Disabling quotas improves performance, but necessitates running the .CR quotacheck command (see .IR quotacheck (1M)) to update the kernel and .CR quotas file after subsequently re-enabling quotas. .PP The .CR repquota command (see .IR repquota (1M)) displays reports of current quota statistics. The somewhat related, but independent, .CR quot command (see .IR quot (1M)), collects and reports disk utilization independently of the disk quota subsystem. .PP The .CR mount command (see .IR mount (1M)) reports any file systems for which quotas are enabled. .SS Data Storage Structure The .CR dqblk data structure (defined in .CR ), is used by the .CR quotactl() system call (see .IR quotactl (2)) to get or set quota information. This structure contains fields that are used to store a user's current file and block count and quota limits for a particular file system. .PP .ne 10 .CR "struct dqblk" contains the following members: .nf .IP .C "u_long dqb_bhardlimit; /* maximum # of disk blocks +1 */" .C "u_long dqb_bsoftlimit; /* preferred limit on disk blocks */" .C "u_long dqb_curblocks; /* current block count */" .C "u_long dqb_fhardlimit; /* maximum # allocated files +1 */" .C "u_long dqb_fsoftlimit; /* preferred file limit */" .C "u_long dqb_curfiles; /* current # allocated files */" .C "u_long dqb_btimelimit; /* time limit for excessive block use */" .C "u_long dqb_ftimelimit; /* time limit for excessive files */" .fi .SH NETWORKING FEATURES Quotas are not fully supported over .SM NFS file systems. However, the .CR quota command is able to report quota statistics on remote .SM NFS file systems for which disk quotas are in effect, if the remote system provides the .SM RPC .CR rquotad service (see .IR rquotad (1M)). .PP .CR rquotad is provided to allow reciprocal support to other systems. .SH EXAMPLES .SS "Initial Setup" The kernel must be reconfigured to support disk quotas; see the System Administration manuals. Eligible file systems for disk quota enforcement are those with mount options .CR rw and .CR quota , as described in .IR mount (1M) and .IR fstab (4). .PP For each file system for which quotas are to be enabled, perform the following tasks: .RS .TP 1. Mount the file system. .TP 2. Add .CR quota to the existing options list in .CR /etc/fstab . For example, change the string .CR default for the root .RC ( / ) entry to .CR default,quota . Once this is done, quotas will automatically be enabled for all relevant file systems on system reboot. .TP 3. Create the .CR quotas file at the root of the file system. For example, for the .CR /mnt file system, run the command .RS .IP .C "cpset /dev/null /mnt/quotas 600 root bin" .RE .TP 4. Establish one or more prototype user quotas using the .CR edquota command (see .IR edquota (1M)). .IP If you want a number of users on your system to have the same limits, use .CR edquota to set those quotas for a prototype user; then use the .CR "edquota -p" command to replicate those limits for that group of users. .TP 5. Turn on the quotas on the file system using .CR quotaon . For example, run the command .RS .IP /usr/sbin/quotaon /mnt .RE .TP 6. Run .CR quotacheck (see .IR quotacheck (1M)) on the file system to record the current usage statistics. .RE .SS "Adding a new user" To add a new user to the quota system: .RS .TP 1. Use .CR edquota to copy the quotas of an existing user. .TP 2. Run .CR quotacheck . .SS "Adding a new file system to an established system" Repeat steps 1 through 5 above under "Initial Setup" for the new file system. .SH WARNINGS The .SM HP-UX default is to allow .IR chown (2). This can interfere with the disk quota mechanism. Quotas can be defeated if the .CR chown command (see .IR chown (1)) or the .CR chown() system call (see .IR chown (2)) is accessible to a user. The .CR setprivgrp command (see .IR setprivgrp (1M)) can be used to limit access to the .CR chown() system call so that only a specified group of users are permitted to use the .CR chown command or the .CR chown() system call. .PP The .CR sam command (see .IR sam (1M)) does not yet support disk quotas. When adding new users or file systems, any desired quotas must be established outside of .CR sam . .PP .SM HP has added features to the original implementation to ensure correctness of the content of the quotas file when quotas are enabled by .CR mount and disabled by .CR umount (see .IR mount (1M)), thus eliminating the need to run .CR quotacheck (see .IR quotacheck (1M)). These features are ineffective, however, if .CR quotaoff and .CR quotaon (see .IR quotaon (1M)) are used to control quotas. .PP .CR quotacheck should only be run on a dormant file system to ensure accurate usage information. The .CR \-qv options of the .CR fsclean command (see .IR fsclean (1M)) report on the the current viability of the quota information. .PP Currently, only .SM HFS file systems support disk quotas, though there may be support for other file systems in the future. .SH AUTHOR Disk Quotas were developed by the University of California, Berkeley, Sun Microsystems, and HP. .SH FILES .PD 0 .TP 22 .CR /etc/fstab Static information about the file systems .TP .CR /etc/mnttab Mounted file system table .TP .IC directory /quotas Quota statistics static storage for a file system, where .I directory is the root of the file system, as specified to the .CR mount command (see .IR mount (1M)). .PD .SH "SEE ALSO" chown(1), chown(2), quota(1), edquota(1M), fstab(4), mount(1M), quot(1M), quotacheck(1M), quotaon(1M), rquotad(1M), setprivgrp(1M), quotactl(2), vfsmount(2). .\" .\" index@\f4quota\f1 \- disk quotas@@@\f3quota(5)\f1 .\" index@disk quotas@@@\f3quota(5)\f1 .\" index@user disk usage quotas@@@\f3quota(5)\f1 .\" index@usage quotas, disk@@@\f3quota(5)\f1 .\" index@limits, disk usage@@@\f3quota(5)\f1 .\" .\" toc@\f3quota(5)\f1:\0\0\f4quota\f1@@@disk quotas .\" .\" $Header: rcsintro.5,v 72.3 93/01/14 16:04:14 ssa Exp $ .TA r .TH rcsintro 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rcsintro \- description of \s-1RCS\s0 commands .SH DESCRIPTION Revision Control System (\s-1RCS\s0) automates the storing, retrieval, logging, identification, and merging of revisions of .SM ASCII text files. .SM RCS is useful for managing files that are revised frequently. .SS Functions of \s-1RCS\s0 .TP 3 \(bu Storage and retrieval of revisions of text files. .SM RCS saves revisions in a space efficient way. Revisions can be retrieved by ranges of revision numbers, symbolic names, dates, authors, and states. .TP \(bu Maintenance of a complete history of changes. .SM RCS logs all changes automatically. In addition to the text of each revision, .SM RCS stores the author, date and time of check in, and a log message summarizing the change. .TP \(bu Resolution of access conflicts. When two or more people try to modify the same revision of a file, .SM RCS alerts them and prevents one modification from corrupting the other. .TP \(bu Maintenance of a tree of revisions. .SM RCS can maintain separate lines of development for each file. It stores a tree structure that represents the ancestral relationships among revisions. .TP \(bu Merging of revisions and resolution of conflicts. Two separate lines of development of a file can be coalesced by merging. If the revisions to be merged affect the same lines of a file, .SM RCS flags the overlapping changes. .TP \(bu Release and configuration control. Revisions can be assigned symbolic names and marked as released, stable, experimental, etc. With these facilities, configurations of a file can be described simply and directly. .TP \(bu Automatic identification of each revision with filename, revision number, creation time, author, etc. This identification is like a stamp that can be embedded at an appropriate place in the text of a revision. These stamps make it simple to determine which revisions of which files make up a given configuration. .TP \(bu Minimization of secondary storage. .SM RCS uses very little extra space for revisions (only the differences are stored). If intermediate revisions are deleted, the remaining deltas are compressed accordingly. .SS Getting Started with \s-1RCS\s0 .PP The basic user interface is extremely simple. The novice only needs to learn two commands: .IR ci (1) and .IR co (1). .IR ci , short for "check in," deposits the contents of a text file into an archival file called an .SM RCS file. An .SM RCS file contains all revisions of a particular text file. .IR co , short for "check out", retrieves revisions from an .SM RCS file. .PP Suppose you have a file .B f.c that you wish to put under control of .SM RCS. Invoke the check in command: .IP .B ci f.c .PP .ne 4 This command creates the .SM RCS file .BR f.c,v , stores .B f.c into it as revision .BR 1.1 , and deletes .BR f.c . It also asks you for a description. The description should be a synopsis of the contents of the file. All subsequent check-in commands will ask for a log entry, which should summarize the changes that were made. .PP Files with names ending with "\f3,v\f1" are called .SM RCS files ("v" stands for "versions"), all other files are presumed to be working files. To get back the working file .B f.c in the previous example, use the check out command: .IP .B co f.c .PP This command extracts the latest revision from .B f.c,v and writes it into .BR f.c . You can now edit .B f.c and check it back in by invoking: .IP .B ci f.c .PP .I ci increments the revision number properly. If .I ci complains with the message: .IP .B ci error: no lock set by .PP your system administrator has decided to create all .SM RCS files with the locking attribute set to "strict". In this case, you should have locked the revision during the previous check out. Your last check out should have been: .IP .B co \-l f.c .PP Of course, it is too late now to do the check out with locking, because you probably modified .B f.c already, and a second check out would overwrite your modifications. Instead, invoke: .IP .B rcs \-l f.c .PP This command will lock the latest revision for you, unless somebody else has already locked it. In that case, you will have to negotiate with that person. .PP Locking assures that you, and only you, can check in the next update, and avoids nasty problems if several people work on the same file. Even if a revision is locked, it can still be checked out for reading, compiling, etc. All that locking prevents is a check in by anybody but the locker. .PP If your .SM RCS file is private, i.e., if you are the only person who is going to deposit revisions into it, strict locking is not needed and you can turn it off. If strict locking is turned off, the owner of the .SM RCS file need not have a lock for check in; all others still do. Turning strict locking off and on is done with the commands: .IP .B rcs \-U f.c .PP and .IP .B rcs \-L f.c .PP If you do not want to clutter your working directory with .SM RCS files, create a subdirectory called .SM RCS in your working directory, and move all your .SM RCS files there. .SM RCS commands will search that directory to find needed files. All the commands discussed above will still work without any modification. .PP To avoid the deletion of the working file during check in (in case you want to continue editing), invoke: .IP .B ci \-l f.c .PP or .IP .B ci \-u f.c .PP These commands check in .B f.c as usual, but perform an implicit check out. The first form also locks the checked in revision, the second one does not. Thus, these options save you one check out operation. The first form is useful if locking is strict; the second one if not strict. Both update the identification markers in your working file (see below). .PP You can give .I ci the number you want assigned to a checked in revision. Assume all your revisions were numbered 1.1, 1.2, 1.3, etc., and you would like to start release 2. The command: .IP .B ci \-r2 f.c .PP or .IP .B ci \-r2.1 f.c .PP assigns the number 2.1 to the new revision. From then on, .I ci will number the subsequent revisions with 2.2, 2.3, etc. The corresponding .I co commands: .IP .B co \-r2 f.c .PP and .IP .B co \-r2.1 f.c .PP retrieve the latest revision numbered 2.x and the revision 2.1, respectively. .I co without a revision number selects the latest revision on the "trunk"; i.e., the highest revision with a number consisting of 2 fields. Numbers with more than 2 fields are needed for branches. For example, to start a branch at revision 1.3, invoke: .IP .B ci \-r1.3.1 f.c .PP This command starts a branch numbered 1 at revision 1.3, and assigns the number 1.3.1.1 to the new revision. For more information about branches, see .IR rcsfile (4). .SS \s-1RCS\s0 File Naming and Location .PP .SM RCS recognizes two kinds of files: .SM RCS files (revision archives), and working files. Working filenames are defined by the .SM RCS user, .SM RCS file names are generated by .SM RCS by appending "\f3,v\f1" to the working file name. Pairs of .SM RCS files and working files can be specified in 3 ways: .RS .TP 3 \(bu Both the .SM RCS file and the working file are given. The .SM RCS filename is of the form .B path1/workfile,v and the working filename is of the form .BR path2/workfile , where .B path1 and .B path2 are (possibly different or empty) paths and .B workfile is a filename. .TP \(bu Only the .SM RCS file is given. Then the working file is assumed to be in the current directory and its name is derived from the name of the .SM RCS file by removing .B path1/ and the suffix "\f3,v\f1". .TP \(bu Only the working file is given. Then the name of the .SM RCS file is derived from the name of the working file by removing .B path2/ and appending the suffix "\f3,v\f1". .RE .PP If the .SM RCS filename is omitted or specified without a path, .SM RCS commands look for the .SM RCS file in the directory .B ./RCS (or the directory it points to if it is a directory link), then in the current working directory. .SS \s-1RCS\s0 Directory Links .SM RCS supports directory links. If a regular file named .SM RCS exists in the current working directory, .SM RCS interprets the first line as a path name to the directory where .SM RCS files are stored. .SM RCS can follow a chain of up to ten directory links to reach the .SM RCS directory. .SS Automatic Identification .SM RCS can put special strings for identification into your source and object code. To obtain such identification, place the marker: .IP .B $\&Header$ .PP into your text, for instance inside a comment. .SM RCS replaces this marker with a string of the form: .IP .BI $\&Header: " filename revision_number date time author state"$ .PP With such a marker on the first page of each module, you can always see with which revision you are working. .SM RCS keeps the markers up-to-date automatically. To propagate the markers into your object code, simply put them into literal character strings. In C, this is done as follows: .IP .B static char rcsid[] = "$\&Header$"; .PP The command .I ident extracts such markers from any file, even object code and dumps. Thus, .I ident lets you find out which revisions of which modules were used in a given program. .PP You may also find it useful to put the marker .B $\&Log$ into your text, inside a comment. This marker accumulates the log messages that are requested during check in. Thus, you can maintain the complete history of your file directly inside it. There are several additional identification markers. See .IR co (1) for details. .SH WARNINGS Names of .SM RCS files are generated by appending .B ,v to the end of the working file name. If the resulting .SM RCS file name is too long for the file system on which the .SM RCS file should reside, the .SM RCS command terminates with an error message. .PP .SM RCS is designed to be used with .SM TEXT files only. Attempting to use .SM RCS with non-text (binary) files will result in data corruption. .SH AUTHOR .I rcsintro was developed by Walter F. Tichy, Purdue University, West Lafayette, IN 47907. .br Revision Number: 3.0; Release Date: 83/05/11. .br Copyright 1982 by Walter F. Tichy. .SH SEE ALSO ci(1), co(1), ident(1), merge(1), rcs(1), rcsdiff(1), rcsmerge(1), rlog(1), rcsfile(4). .sp Walter F. Tichy, "Design, Implementation, and Evaluation of a Revision Control System," in \f2Proceedings of the 6th International Conference on Software Engineering\f1, IEEE, Tokyo, Sept. 1982. .\" index@\f2rcsintro\f1 \- description of \s-1RCS\s+1 commands@@@\f3rcsintro(5)\f1 .\" index@\s-1RCS\s+1: description of commands@@@\f3rcsintro(5)\f1 .\" index@commands, \s-1RCS\s+1, description of@@@\f3rcsintro(5)\f1 .\" .\" toc@\f3rcsintro(5)\f1:\0\0\f2rcsintro\f1@@@description of \s-1RCS\s+1 commands .\" .\" fileset_database@rcsintro.5 SYS-ADMIN-MAN .\" $Header: regexp.5,v 72.7 94/11/30 10:15:33 ssa Exp $ .TA r .TH regexp 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME regexp \- regular expression and pattern matching notation definitions .SH DESCRIPTION A .I regular expression is a mechanism supported by many utilities for locating and manipulating patterns in text. .I pattern matching notation is used by shells and other utilities for file name expansion. This manual entry defines two forms of regular expressions: .I Basic Regular Expressions and .I Extended Regular Expressions ; and the one form of .I Pattern Matching Notation . .SH BASIC REGULAR EXPRESSIONS Basic regular expression (\s-1RE\s+1) notation and construction rules apply to utilities defined as using basic RE\s0s. Any exceptions to the following rules are noted in the descriptions of the specific utilities that use RE\s0s. .SS \s-1RE\s+1s Matching a Single Character The following RE\s0s match a single character or a single collating element: .PP .B Ordinary Characters .br An ordinary character is an RE that matches itself. An ordinary character is any character in the supported character set except and the regular expression special characters listed in Special Characters below. An ordinary character preceded by a backslash .RB ( \|\e\| ) is treated as the ordinary character itself, except when the character is .BR ( , .BR ) , .BR {, or .BR } , or the digits .B 1 through .B 9 (see RE\s0s Matching Multiple Characters). Matching is based on the bit pattern used for encoding the character; not on the graphic representation of the character. .PP .B Special Characters .br A regular expression special character preceded by a backslash is a regular expression that matches the special character itself. When not preceded by a backslash, such characters have special meaning in the specification of RE\s0s. Regular expression special characters and the contexts in which they have special meaning are: .RS .TP 15 .B "[ \e" The period, left square bracket, and backslash are special except when used in a bracket expression (see RE Bracket Expression). .TP .B \(** The asterisk is special except when used in a bracket expression, as the first character of a regular expression, or as the first character following the character pair .B \e( (see RE\s0s Matching Multiple Characters). .TP .B ^ The circumflex is special when used as the first character of an entire RE (see Expression Anchoring) or as the first character of a bracket expression. .TP .B $ The dollar sign is special when used as the last character of an entire RE (see Expression Anchoring). .TP .I delimiter Any character used to bound (i.e., delimit) an entire RE is special for that RE. .RE .PP .B Period .PP A period .RB ( \|.\| ), when used outside of a bracket expression, is an RE that matches any printable or nonprintable character except . .SS RE Bracket Expression A bracket expression enclosed in square brackets .RB ( \|[\ ]\| ) is an RE that matches a single collating element contained in the nonempty set of collating elements represented by the bracket expression. .PP The following rules apply to bracket expressions: .RS 5 .TP 15 .B bracket expression A bracket expression is either a .I matching list expression or a .IR "non-matching list expression" , and consists of one or more expressions in any order. Expressions can be: collating elements, collating symbols, noncollating characters, equivalence classes, range expressions, or character classes. The right bracket .RB ( \|]\| ) loses its special meaning and represents itself in a bracket expression if it occurs first in the list (after an initial .BR ^ , if any). Otherwise, it terminates the bracket expression (unless it is the ending right bracket for a valid collating symbol, equivalence class, or character class, or it is the collating element within a collating symbol or equivalence class expression). The special characters .RS 20 .IP .B ". \(** [ \e" .RE .IP (period, asterisk, left bracket, and backslash) lose their special meaning within a bracket expression. .IP The character sequences: .RS 20 .IP .B "[. [= [:" .RE .IP (left-bracket followed by a period, equal-sign or colon) are special inside a bracket expression and are used to delimit collating symbols, equivalence class expressions and character class expressions. These symbols must be followed by a valid expression and the matching terminating .BR ".]" , .BR "=]" , or .BR ":]" . .TP .B matching list A matching list expression specifies a list that matches any one of the characters represented in the list. The first character in the list cannot be the circumflex. For example, .B [abc] is an RE that matches any of .BR a , .BR b , or .BR c . .TP .B non-matching list A .I non-matching list expression begins with a circumflex .RB ( \|^\| ), and specifies a list that matches any character or collating element .I except and the characters represented in the list. For example, .B [^abc] is an RE that matches any character except or .BR a , .BR b , or .BR c . The circumflex has this special meaning .I only when it occurs first in the list, immediately following the left square bracket. .TP .B collating element A .I collating element is a sequence of one or more characters that represents a single element in the collating sequence as identified via the most current setting of the locale category LC_COLLATE (see .IR setlocale (3C)). .TP .B collating symbol A .I collating symbol is a collating element enclosed within bracket-period .RB ( \|[. \|...\| .]\| ) delimiters. Multi-character collating elements must be represented as collating symbols to distinguish them from single-character collating elements. For example, if the string .B ch is a valid collating element, then .B [[.ch.]] is treated as an element matching the same string of characters, while .B ch is treated as a simple list of the characters .B c and .BR h . If the string within the bracket-period delimiters is not a valid collating element in the current collating sequence definition, the symbol is treated as an invalid expression. .TP .B noncollating character A .I noncollating character is a character that is ignored for collating purposes. By definition, such characters cannot participate in equivalence classes or range expressions. .TP .B equivalence class An .I equivalence class expression represents the set of collating elements belonging to an equivalence class. It is expressed by enclosing any one of the collating elements in the equivalence class within bracket-equal .RB ( \|[= \|...\| =]\| ) delimiters. For example, if .BR a , .ifn .BR Ä , .ift .BR \z\(aaa , and .BR A belong to the same equivalence class, then .BR [[=a=]b] , .ifn .BR [[=Ä=]b] , .ift .BR [[=\z\(aaa=]b] , and .BR [[=A=]b] are each equivalent to .ifn .BR [aÄAb] . .ift .BR [a\z\(aaaAb] . .TP .B range expression A .I range expression represents the set of collating elements that fall between two elements in the current collation sequence as defined via the most current setting of the locale category LC_COLLATE (see .IR setlocale (3C)). It is expressed as the starting point and the ending point separated by a hyphen .RB ( \|\-\| ). .IP The starting range point and the ending range point must be a collating element, collating symbol, or equivalence class expression. An .I equivalence class expression used as an end point of a range expression is interpreted such that all collating elements within the equivalence class are included in the range. For example, if the collating order is .BR A , .BR a , .BR B , .BR b , .BR C , .BR c , .BR ch , .BR D , and .BR d and the characters .B A and .BR a belong to the same equivalence class, then the expression .B [[=a=]\-D] is treated as .BR [AaBbCc[.ch.]D] . .IP Both starting and ending range points must be valid collating elements, collating symbols, or equivalence class expressions, and the ending range point must collate equal to or higher than the starting range point; otherwise the expression is invalid. For example, with the above collating order and assuming that .B E is a noncollating character, then both the expressions .B [[=A=]\-E] and .B [d\-a] are invalid. .IP An ending range point can also be the starting range point in a subsequent range expression. Each such range expression is evaluated separately. For example, the bracket expression .B [a\-m\-o] is treated as .BR [a\-mm\-o] . .IP The hyphen character is treated as itself if it occurs first (after an initial .BR ^ , if any) or last in the list, or as the rightmost symbol in a range expression. As examples, the expressions .B [\-ac] and .B [ac\-] are equivalent and match any of the characters .BR a , .BR c , or .BR \- ; the expressions .B [^\-ac] and .B [^ac\-] are equivalent and match any characters except , .BR a , .BR c , or .BR \- ; the expression .B [%\-\-] matches any of the characters in the defined collating sequence between .B % and .B \- inclusive; the expression \f3[\-\-@]\f1 matches any of the characters in the defined collating sequence between .B \- and \f3@\f1 inclusive; and the expression \f3[a\-\-@]\f1 is invalid, assuming .B \- precedes .B a in the collating sequence. .IP If a bracket expression must specify both \- and ], the ] must be placed first (after the ^, if any) and the \- last within the bracket expression. .TP .B character class A character class expression represents the set of characters belonging to a character class, as defined via the most current setting of the locale category LC_CTYPE. It is expressed as a character class name enclosed within bracket-colon .RB ( [:\ :] ) delimiters. .IP Standard character class expressions supported in all locales are: .RS 20 .TP 15 .B [:alpha:] letters .TP .B [:upper:] upper-case letters .TP .B [:lower:] lower-case letters .TP .B [:digit:] decimal digits .TP .B [:xdigit:] hexadecimal digits .TP .B [:alnum:] letters or decimal digits .TP .B [:space:] characters producing white-space in displayed text .TP .B [:print:] printing characters .TP .B [:punct:] punctuation characters .TP .B [:graph:] characters with a visible representation .TP .B [:cntrl:] control characters .TP .B [:blank:] blank characters .RE .SS \s-1RE\s+1s Matching Multiple Characters The following rules may be used to construct RE\s0s matching multiple characters from RE\s0s matching a single character: .RS 5 .TP 15 .I RE\|RE The concatenation of RE\s0s is an RE that matches the first encountered concatenation of the strings matched by each component of the RE. For example, the RE .B bc matches the second and third characters of the string .BR abcdefabcdef . .TP .IB RE \(** An RE matching a single character followed by an asterisk .RB ( \(** ) is an RE that matches zero or more occurrences of the RE preceding the asterisk. The first encountered string that permits a match is chosen, and the matched string will encompass the maximum number of characters permitted by the RE. For example, in the string .BR abbbcdeabbbbbbcde , both the RE .B b\(**c and the RE .B bbb\(**c are matched by the substring .B bbbc in the second through fifth positions. An asterisk as the first character of an RE loses this special meaning and is treated as itself. .TP .BI \e( \s-1RE\s0 \e) A subexpression can be defined within an RE by enclosing it between the character pairs .B \e( and .BR \e) . Such a subexpression matches whatever it would have matched without the .B \e( and .BR \e) . Subexpressions can be arbitrarily nested. An asterisk immediately following the .B \e( loses its special meaning and is treated as itself. An asterisk immediately following the .B \e) is treated as an invalid character. .TP .BI \e n The expression .BI \e n matches the same string of characters as was matched by a subexpression enclosed between .B \e( and .B \e) preceding the .BR \e \f2n\fP. The character .I n must be a digit from .B 1 through .BR 9 , specifying the .IR n \-th subexpression (the one that begins with the .IR n \-th .B \e( and ends with the corresponding paired .BR \e) . For example, the expression .B ^\e(.\(**\e)\e1$ matches a line consisting of two adjacent appearances of the same string. .IP If the .BI \e n is followed by an asterisk, it matches zero or more occurrences of the subexpression referred to. For example, the expression .B \e(ab\e(cd\e)ef\e)Z\e2\(**Z\e1 matches the string .BR abcdefZcdcdZabcdef . .TP .IB RE \e{ m , n \e} An RE matching a single character followed by .BR \e{\f2m\fP\e} , .BR \e{\f2m\fP,\e} , or .BI \e{ m , n \e} is an RE that matches repeated occurrences of the RE. The values of .I m and .I n must be decimal integers in the range 0 through 255, with .I m specifying the exact or minimum number of occurrences and .I n specifying the maximum number of occurrences. .BI \e{ m \e} matches exactly .I m occurrences of the preceding RE, .BI \e{ m ,\e} matches at least .I m occurrences, and .BI \e{ m , n \e} matches any number of occurrences between .I m and .IR n , inclusive. .IP The first encountered string that matches the expression is chosen; it will contain as many occurrences of the RE as possible. For example, in the string .B abbbbbbbc the RE .B b\e{3\e} is matched by characters two through four, the RE .B b\e{3,\e} is matched by characters two through eight, and the RE .B b\e{3,5\e}c is matched by characters four through nine. .RE .SS Expression Anchoring An RE can be limited to matching strings that begin or end a line (i.e., anchored) according to the following rules: .RS 5 .TP 3 \(bu A circumflex .RB ( \|^\| ) as the first character of an RE anchors the expression to the beginning of a line; only strings starting at the first character of a line are matched by the RE. For example, the RE .B ^ab matches the string .B ab in the line .BR abcdef , but not the same string in the line .BR cdefab . .TP \(bu A dollar sign .RB ( $ ) as the last character of an RE anchors the expression to the end of a line; only strings ending at the last character of a line are matched by the RE. For example, the RE .B ab$ matches the string .B ab in the line .BR cdefab , but not the same string in the line .BR abcdef . .TP \(bu An RE anchored by both .B ^ and .B $ matches only strings that are lines. For example, the RE .B ^abcdef$ matches only lines consisting of the string .BR abcdef . .RE .SH EXTENDED REGULAR EXPRESSIONS The extended regular expression (\s-1ERE\s0) notation and construction rules apply to utilities defined as using extended RE\s0s. Any exceptions to the following rules are noted in the descriptions of the specific utilities using ERE\s0s. .SS \s-1ERE\s+1s Matching a Single Character The following ERE\s0s match a single character or a single collating element: .PP .B Ordinary Characters .br An ordinary character is an ERE that matches itself. An ordinary character is any character in the supported character set except and the regular expression special characters listed in Special Characters below. An ordinary character preceded by a backslash .RB ( \e ) is treated as the ordinary character itself. Matching is based on the bit pattern used for encoding the character, not on the graphic representation of the character. .PP .B Special Characters .br A regular expression special character preceded by a backslash is a regular expression that matches the special character itself. When not preceded by a backslash, such characters have special meaning in the specification of ERE\s0s. The extended regular expression special characters and the contexts in which they have their special meaning are: .RS 5 .TP 17 .B ". [ \e ( ) \(** + ? $ |" The period, left square bracket, backslash, left parenthesis, right parenthesis, asterisk, plus sign, question mark, dollar sign, and vertical bar are special except when used in a bracket expression (see ERE Bracket Expression). .TP .B ^ The circumflex is special except when used in a bracket expression in a non-leading position. .TP .I delimiter Any character used to bound (i.e., delimit) an entire ERE is special for that ERE. .RE .PP .B Period .PP A period .RB ( \|.\| ), when used outside of a bracket expression, is an ERE that matches any printable or nonprintable character except . .SS \s-1ERE\s0 Bracket Expression The syntax and rules for ERE bracket expressions are the same as for RE bracket expressions found above. .SS \s-1ERE\s+1s Matching Multiple Characters The following rules may be used to construct ERE\s0s matching multiple characters from ERE\s0s matching a single character: .RS 5 .TP 15 .I RE\|RE A concatenation of ERE\s0s matches the first encountered concatenation of the strings matched by each component of the ERE. Such a concatenation of ERE\s0s enclosed in parentheses matches whatever the concatenation without the parentheses matches. For example, both the ERE .B bc and the ERE .B (bc) matches the second and third characters of the string .BR abcdefabcdef . The longest overall string is matched. .TP .IB RE + The special character plus .RB ( \|+\| ), when following an ERE matching a single character, or a concatenation of ERE\s0s enclosed in parenthesis, is an ERE that matches one or more occurrences of the ERE preceding the plus sign. The string matched will contain as many occurrences as possible. For example, the ERE .B b+c matches the fourth through seventh characters in the string .BR acabbbcde . .TP .IB RE \(** The special character asterisk .RB ( \|\(**\| ), when following an ERE matching a single character, or a concatenation of ERE\s0s enclosed in parenthesis, is an ERE that matches zero or more occurrences of the ERE preceding the asterisk. For example, the ERE .B b\(**c matches the first character in the string .BR cabbbcde . If there is any choice, the longest left-most string that permits a match is chosen. For example, the ERE .B b\(**cd matches the third through seventh characters in the string .BR cabbbcdebbbbbbcdbc . .TP .IB RE ? The special character question mark .RB ( \|?\| ), when following an ERE matching a single character, or a concatenation of ERE\s0s enclosed in parenthesis, is an ERE that matches zero or one occurrences of the ERE preceding the question mark. The string matched will contain as many occurrences as possible. For example, the ERE .B b?c matches the second character in the string .BR acabbbcde . .TP .IB RE { m,n } interval expression that functions the same way as basic regular expression syntax, .IB RE \e{ m , n \e} .RE .SS Alternation Two ERE\s0s separated by the special character vertical bar .RB ( | ) matches a string that is matched by either ERE. For example, the ERE .B ((ab)|c)d matches the string .B abd and the string .BR cd . .SS Precedence The order of precedence is as follows, from high to low: .PP .RS 5 .TP 15 .B [ ] square brackets .TP .B \(** + ? asterisk, plus sign, question mark .TP .B ^ $ anchoring .IP concatenation .TP .B | alternation .RE .PP For example, the ERE .B abba|cde is interpreted as "match either .B abba or .BR cde ". It does not mean "match .B abb followed by .B a or .B c followed in turn by .BR de " (because concatenation has a higher order of precedence than alternation). .SS Expression Anchoring An ERE can be limited to matching strings that begin or end a line (i.e., anchored) according to the following rules: .RS 5 .TP 3 \(bu A circumflex .RB ( \|^\| ) matches the beginning of a line (anchors the expression to the beginning of a line). For example, the ERE .B ^ab matches the string .B ab in the line .BR abcdef , but not the same string in the line .BR cdefab . .TP \(bu A dollar sign .RB ( \|$\| ) matches the end of a line (anchors the expression to the end of a line). For example, the ERE .B ab$ matches the string .B ab in the line .RB cdefab , but not the same string in the line .BR abcdef . .TP \(bu An ERE anchored by both .B ^ and .B $ matches only strings that are lines. For example, the ERE .B ^abcdef$ matches only lines consisting of the string .BR abcdef . Only empty lines match the ERE .BR ^$ . .RE .SH PATTERN MATCHING NOTATION The following rules apply to pattern matching notation except as noted in the descriptions of the specific utilities using pattern matching. .SS Patterns Matching a Single Character The following patterns match a single character or a single collating element: .PP .B Ordinary Characters .br An ordinary character is a pattern that matches itself. An ordinary character is any character in the supported character set except and the pattern matching special characters listed in Special Characters below. Matching is based on the bit pattern used for encoding the character, not on the graphic representation of the character. .PP .B Special Characters .br A pattern matching special character preceded by a backslash .RB ( \|\e\| ) is a pattern that matches the special character itself. When not preceded by a backslash, such characters have special meaning in the specification of patterns. The pattern matching special characters and the contexts in which they have their special meaning are: .RS 5 .TP 15 .B "? \(** [" The question mark, asterisk, and left square bracket are special except when used in a bracket expression (see Pattern Bracket Expression). .RE .PP .B Question Mark .PP A question mark .RB ( \|?\|), when used outside of a bracket expression, is a pattern that matches any printable or nonprintable character except . .SS Pattern Bracket Expression The syntax and rules for pattern bracket expressions are the same as for RE bracket expressions found above with the following exceptions: .RS 5 .PP The exclamation point character .RB ( \|!\| ) replaces the circumflex character .RB ( \|^\| ) in its role in a non-matching list in the regular expression notation. .PP The backslash is used as an escape character within bracket expressions. .RE .SS Patterns Matching Multiple Characters The following rules may be used to construct patterns matching multiple characters from patterns matching a single character: .RS 5 .TP 15 .B \(** The asterisk .RB ( \|\(**\| ) is a pattern that matches any string, including the null string. .TP .I RE\|RE The concatenation of patterns matching a single character is a valid pattern that matches the concatenation of the single characters or collating elements matched by each of the concatenated patterns. For example, the pattern .B a[bc] matches the string .B ab and .BR ac . .IP The concatenation of one or more patterns matching a single character with one or more asterisks is a valid pattern. In such patterns, each asterisk matches a string of zero or more characters, up to the first character that matches the character following the asterisk in the pattern. .IP For example, the pattern .B a\(**d matches the strings .BR ad , .BR abd , and .BR abcd ; but not the string .BR abc . When an asterisk is the first or last character in a pattern, it matches zero or more characters that precede or follow the characters matched by the remainder of the pattern. For example, the pattern .B a\(**d\(** matches the strings .BR ad , .BR abcd , .BR abcdef , .BR aaaad , and .BR adddd ; the pattern .B \(**a\(**d matches the strings .BR ad , .BR abcd , .BR efabcd , .BR aaaad , and .BR adddd . .RE .SS "Rule Qualification for Patterns Used for Filename Expansion" The rules described above for pattern matching are qualified by the following rules when the pattern matching notation is used for filename expansion by .IR sh (1), .IR csh (1), .IR ksh (1), and .IR make (1). .RS 5 .PP If a filename (including the component of a pathname that follows the slash .RB ( \|/\| ) character) begins with a period .RB ( \|.\| ), the period must be explicitly matched by using a period as the first character of the pattern; it cannot be matched by either the asterisk special character, the question mark special character, or a bracket expression. This rule does not apply to .IR make (1). .PP The slash character in a pathname must be explicitly matched by using a slash in the pattern; it cannot be matched by either the asterisk special character, the question mark special character, or a bracket expression. For .IR make (1) only the part of the pathname following the last slash character can be matched by a special character. That is, all special characters preceding the last slash character lose their special meaning. .PP Specified patterns are matched against existing filenames and pathnames, as appropriate. If the pattern matches any existing filenames or pathnames, the pattern is replaced with those filenames and pathnames, sorted according to the collating sequence in effect. If the pattern does not match any existing filenames or pathnames, the pattern string is left unchanged. .PP If the pattern begins with a tilde .RB ( \|~\| ) character, all of the ordinary characters preceding the first slash (or all characters if there is no slash) are treated as a possible login name. If the login name is null (i.e., the pattern contains only the tilde or the tilde is immediately followed by a slash), the tilde is replaced by a pathname of the process's home directory, followed by a slash. Otherwise, the combination of tilde and login name are replaced by a pathname of the home directory associated with the login name, followed by a slash. If the system cannot identify the login name, the result is implementation-defined. This rule does not apply to .IR sh (1) or .IR make (1). .PP If the pattern contains a .B $ character, variable substitution can take place. Environmental variables can be embedded within patterns as: .TP 15 \& .BI $ name .PP or: .TP 15 \& .BR ${ \|name\| } .PP Braces are used to guarantee that characters following .I name are not interpreted as belonging to .IR name . Substitution occurs in the order specified only once; that is, the resulting string is not examined again for new names that occurred because of the substitution. .RE .SS "Rule Qualification for Patterns Used in the case Command" The rules described above for pattern matching are qualified by the following rule when the pattern matching notation is used in the case command of .IR sh (1) and .IR ksh (1). .RS 5 .PP Multiple alternative patterns in a single clause can be specified by separating individual patterns with the vertical bar character .RB ( \||\| ); strings matching any of the patterns separated this way will cause the corresponding command list to be selected. .SH SEE ALSO ksh(1), sh(1), fnmatch(3C), glob(3C), regcomp(3C), setlocale(3C), cdf(4), environ(5). .SH STANDARDS CONFORMANCE .RC < regexp.h ">: AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@<\f4regexp.h\f1> \- regular expression and pattern matching notation definitions@@@\f3regexp(5)\f1 .\" index@regular expression and pattern matching notation definitions@@@\f3regexp(5)\f1 .\" index@expression, regular, and pattern matching notation definitions@@@\f3regexp(5)\f1 .\" index@definitions, regular expression and pattern matching notation@@@\f3regexp(5)\f1 .\" index@pattern matching and regular expression notation definitions@@@\f3regexp(5)\f1 .\" .\" toc@\f3regexp(5)\f1:\0\0<\f4regexp.h\f1>@@@regular expression and pattern matching notation definitions .\" $Header: sd.5,v 78.2 96/05/09 12:30:15 ssa Exp $ .\" -*-Nroff-*- .\" $Header: sd.5,v 78.2 96/05/09 12:30:15 ssa Exp $ .\" .ds RZ \&HP CONFIDENTIAL .\" .ds RL Release B.10.0x .\" .ds MT Software Distributor B.10.0x .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro (e.g., .CR, .\" .RI, etc.). A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .\" .ds PN Release B.10.0x .TA s .TH sd 5 " " "Hewlett-Packard Company" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ds )H Software Distributor .\" .ds ]W Release B.10.0x .SH NAME sd \- Create, distribute, install, monitor, and manage software .PP .SS Remarks: SD-UX commands are included with the HP-UX Operating System and manage software on the .I local host only. To install and manage software simultaneously on multiple .I remote hosts (including PCs) from a central controller, you must purchase the .B "HP OpenView Software Distributor" (HP Prod. No. B1996AA) which provides extended software management, multi-site software distribution capabilities and distribution to PCs. While most of the information in this manual page applies to both SD-UX commands and the OpenView product, some applies .B only to the OpenView product. Where this is the case, you will see: .RS .IP .IR "The following xxx applies only to HP OpenView Software Distributor" .RE .PP .SH SYNOPSIS .C sw .RI [ "XToolkit Options" ] .RC [ -r | -d ] .RC [ -i ] .RC [ -l ] .RC [ -p ] .RC [ -R ] .RC [ -u ] .RC [ -v ] .RC [ -V ] .RC [ -a\| .IR attribute\| ] .RC [ -D\| .IR acl_entry\| ] .br .RC [ -f\| .IR software_file\| ] .RC [ -F\| .IR acl_file\| ] .RC [ -J .IR jobid\| ] .RC [ -l .IR level\| ] .RC [ -M .IR acl_entry\| ] .RC [ -Q .IR date\| ] .RC [ -s .IR source\| ] .br .RC [ -C\| .IR session_file\| ] .RC [ -S\| .IR session_file\| ] .RC [ -t\| .IR target_file\| ] .RC [ -x .IR option=value\| ] .br .RC [ -X\| .IR option_file\| ] .RI [ selections ]\0[\c \*(at .IR \0target_selections ] .PP .SH DESCRIPTION .PP The SD commands are: .IP \(bu .C sd - create and monitor software jobs (HP OpenView Software Distributor only). .IP \(bu .C swacl - modify the Access Control Lists (ACLs) which protect software products. .IP \(bu .C swconfig - configure, unconfigure, or reconfigure installed software. .IP \(bu .C swcopy - copy software products for subsequent installation or distribution. .IP \(bu .C swcluster - install or remove software from a diskless cluster. .IP \(bu .C swgettools - retrieve the SD product from new media. .IP \(bu .C swinstall - install and configure software products. .IP \(bu .C swjob - monitor job progress and log files (HP OpenView Software Distributor only). .IP \(bu .C swlist - display information about software products. .IP \(bu .C swmodify - modify software product information in a target root or depot. .IP \(bu .C swpackage - package software products into a distribution directory or tape. .IP \(bu .C swreg - register or unregister depots or roots. .IP \(bu .C swremove - unconfigure and remove software products. .IP \(bu .C swverify - verify software products. .IP \(bu .C update - update or install HP-UX files. .PP The following sections highlight the features that these commands support. .PP .SS Interactive Operation .PP By default, all SD commands operate in a non-interactive mode. However, the .CR swcopy , .CR swinstall , and .CR swremove commands also support a graphical user interface (GUI). The HP OpenView Software Distributor interface is invoked using the .CR sd command. It is the central interactive interface for creating and monitoring software jobs. (The interactive GUIs may also be invoked using the .C -i option, or by invoking the commands without any command-line options.) .PP .SS Distributed Operation .PP All of the commands except .C swpackage and .C swmodify use a distributed model of operation. The commands act as the controller for distributed operations, orchestrating the specific software management tasks. For each UNIX .IR target_selection , an SD agent process performs the tasks: .IP \(bu .C swagent - perform software management tasks as the agent of an SD command. .P Communication between the command and each agent, plus other target host activities are facilitated by an SD daemon process: .IP \(bu .C swagentd - serve local or remote software management tasks. .PP .RS .IP .IR "The following PC information applies only to HP OpenView Software Distributor" .RE .PP For each PC .IR target_selection , a single Windows application combines the .C swagent and .C swagentd functionality: .IP \(bu .C SWAGENTD.EXE - perform software management tasks, serve local PC software for distribution. .P Each PC running the .C SWAGENTD.EXE is a PC Controller. When distributing PC software, it acts as a fanout server to PC targets. These targets run SD PC agent programs to perform the actual software installation tasks. .PP .SS Software Job Management .PP .RS .IP .IR "The following paragraph applies only to HP OpenView Software Distributor" .RE .PP Most SD commands create job information that records the job definition (in a session file), status and log information for the job. Jobs can be executed immediately, or scheduled for later execution. The user can browse the scheduled, active, and completed jobs using either the command line or interactive interfaces. .PP .SS Secure Operation SD uses Access Control Lists (ACLs) to authorize a user attempting to create, modify, or read software products in a depot or installed to a root filesystem. The superuser can grant specific local and remote users specific access permissions to a target host, a target depot, and/or a target root filesystem. .P SD uses a method based on credentials and passwords to authenticate the user and the SD command performing a given operation. .PP .SS Flexible Policy Control .PP Many policies and behaviors for the SD commands can be controlled via the appropriate command options. Options can be defined in an SD .IR defaults file, specified on the command-line invocation of a command, or specified in the GUI. .PP .SS Preview, Diagnostics and Logging .PP All commands, except for .C swlist and .CR swpackage , log major events on the controller host, and detailed events on the target hosts. The .C swlist command does no logging, while the .C swpackage command logs all events to the same logfile. .PP .RS .IP .IR "The following sentence applies only to HP OpenView Software Distributor" .RE .PP The SD interactive interface (invoked using the .C sd command) and the .C swjob command line interface may be used to monitor job progress and to view controller and target logfiles. .PP The .CR swconfig , .CR swcopy , .CR swinstall , .CR swpackage , and .C swremove commands support a preview mode, where the commands will proceed through the analysis phase, then exit. (The .C swpackage command goes beyond the analysis phase but makes no changes to the target depot.) .PP The preview mode only applies to non-interactive operations, since the GUIs wait for confirmation after analysis. In the interactive mode, you can resolve invalid conditions that the commands discover before they actually begin loading or removing files. .PP .SS Software Products .PP Software products are organized in a multi-level hierarchy: .IR bundles , .IR products , .IR subproducts , and .IR filesets . The actual files that make up a product are packaged into filesets. Subproducts can be used to partition or subset the filesets into logical groupings. (Subproducts are optional.) .P The .IR software_selections for an SD command can specify bundles, products, individual subproducts, and/or individual filesets. .PP .SS Compatible Software .PP Software products specify what machine types and operating systems they support (i.e. are compatible with). The .CR swconfig , .CR swinstall , and .C swverify commands can detect and/or enforcement the use of compatible software. .PP .SS Dependencies Between Software .PP The .CR swconfig , .CR swcopy , .CR swinstall , .CR swremove , and .CR swverify commands support dependencies between filesets and other filesets and products. .PP If a .IR software_selection specifies a dependency on other filesets and/or products, the commands will automatically select that software. An exception is .CR swremove , which will automatically select dependent software (filesets and/or products that depend on the .IR software_selections ). .PP By default, all dependencies must be resolved before a command will proceed. The user can override this policy using the .C enforce_dependencies option. .PP SD supports two types of dependencies: .IR prerequisites that must be installed and configured before the dependent fileset is installed and configured (respectively); and .IR corequisites that must be installed and configured before the dependent is usable. .PP .PP .SS Product Location and Multiple Versions .PP The .C swinstall command can install a software product to an alternate product location instead of the default product directory specified by the vendor. (This directory location is the root directory of all the product's files.) .P The .C swinstall command can also install multiple versions of a software product to a single target system, each in a unique product location. .PP The software management commands, .CR swconfig , .CR swlist , .CR swremove , and .CR swverify allow a user to select a specific product from the multiple installed versions by specifying the product location as part of the .IR software_selection . .PP .SS Alternate Root Directory and Depot Directory .PP By default, the .CR swinstall , .CR swlist , .CR swverify , and .C swremove commands operate on the primary root filesystem of a target host, namely "/". The user can also specify an alternate root directory to these commands, meaning a directory other than "/" that will eventually be the root of some target host (e.g. building a test system by mounting its root filesystem). For diskless support, the alternate root is used for a .B "shared root" that provides the target for shared software links below each client's private root. .P The .C swconfig command only operates on software installed to the primary root filesystem, "/". .PP When operating on a depot, the .CR swpackage , .CR swcopy , .CR swlist , .CR swverify , and .C swremove commands by default use the depot located at .CR /var/spool/sw . The user can also specify an alternate depot directory to these commands. .PP .SS Disk Space Analysis .PP The .CR swcopy , .CR swinstall , and .CR swpackage commands perform a disc space analysis on the .IR target_selections to ensure that enough free disc space is available to perform the task. The .C swremove command can also perform disk space analysis to help the user choose software to remove. .PP Before performing any disc space analysis, the commands execute the .C mount(8) command to mount all filesystems listed in each target's filesystem table .RC ( /etc/fstab or equivalent). This action helps to ensure that files are not loaded (removed) into (from) a directory that may be below a future mount point. The user can override this mounting policy using the .C mount_all_filesystems option. .PP .SS Control Scripts .PP The .CR swconfig , .CR swinstall , .CR swremove , and .C swverify commands execute vendor-defined control script to perform checks and/or other tasks beyond those explicitly performed by the commands. .PP For .C swinstall and .CR swremove , a fileset and/or product can include a check script to perform an analysis of each .IR target_selection (target host). If this analysis fails, the script can prevent the fileset/product from being installed or removed. .PP In addition, .C swinstall and .C swremove can execute scripts immediately before and immediately after the fileset/product has been installed or removed. These scripts usually perform additional file install or remove operations. .PP The .CR swconfig , .CR swinstall , and .C swremove commands will also execute configuration and unconfiguration scripts on an installed fileset/product to configure or unconfigure the system for the software. .PP The .C swverify command will execute a verification script which can analyze the configured fileset/product to verify that it is configured properly. .PP .SS Software States .PP The SD commands transition products and filesets through a number of .IR states . .P During installation, software is transitioned through the following states: non-existent, TRANSIENT, INSTALLED, and CONFIGURED. During removal, software is transitioned through these states: CONFIGURED, INSTALLED, TRANSIENT, and non-existent. .P When packaging or copying software into a depot, the software is transitioned through the following states: non-existent, TRANSIENT, and AVAILABLE. When removing software from a depot, the software is transitioned through these states: AVAILABLE, TRANSIENT, and non-existent. .P If a task fails during any TRANSIENT state, the state is set to CORRUPT. .PP .SS Session Files .PP Each invocation of an SD command defines a task session. Most SD commands automatically save options, source information, software selections, and target selections before the task actually commences. You can build, save, and reuse additional sessions with most commands. .PP .SS Software and Target Lists .PP Most SD commands support software and target selections from separate input files. A user can reuse files containing sets of software or target configurations as input to the commands. .PP .SS Options .PP The following options are generally supported by the SD commands. .PP .RS .TP 10 .IR "XToolKit Options" The interactive commands support a subset of the standard X Toolkit options to control the appearance of the GUI. The supported options are: .CR -bg , .CR -background , .CR -fg , .CR -foreground , .CR -display , .CR -name , .CR -xrm . and .CR "-synchronous" . See the .C X(1) manual page for a definition of these options. .TP .C -d Causes the command to operate on .IR target_selections which are software depots rather than root directories. .TP .C -r Causes the command to operate on .IR target_selections which are alternate root directories (e.g. root filesystems other than .CR / ). As of HP-UX release 10.2*, .CR -r is optional for the .CR swinstall , .CR swremove , .CR swlist , and .CR swverify commands but is allowed to maintain compatibility with previous versions. .TP .C -i Runs the command in interactive mode (Graphical User Interface). .TP .C -l Runs the command in .I linkinstall mode which makes software installed under a server's .IR "shared root" available to a diskless client's .IR "private root" . .IP When run in the .IR linkinstall mode, .CR swinstall : .RS .TP 3 \(bu Creates NFS mounts to the software to make it accessible from the target. This may involve delayed mounting for alternate roots. .TP \(bu Modifies the target's .IR fstab file. .TP \(bu Modifies the source's .C exports file to add mount permission for the target. .RE .IP Mounts are created by examining the .IR share_link product attribute. Not all products support .CR linkinstall . Some products may be visible without creating a new mount if they reside under an old one. The .C -l option is used by the .C swcluster command in installing to diskless clusters. .TP .C -p Previews the task by executing the session through the analysis phase and exiting before the command begins to perform the actual task. This option only applies to non-interactive sessions. .TP .C -R Recursively include all objects to the fileset level using .CR swlist , (and to the end_target level using the HP OpenView Software Distributor .CR swjob command). .TP .C -u Undo variation of the operation, unconfiguring software using .CR swconfig , unregistering the specified objects using .CR swreg , (or removing the specified jobs using the HP OpenView Software Distributor .CR swjob command). .TP .C -v Turns on verbose output to stdout. (The command logfile is not affected by this option.) By default, verbose output is enabled for all the SD commands. .TP .C -V List the SDU data model revisions that .C swpackage supports. .bp .TP .CI -a \0attribute Specifies particular attributes to display or modify using .CR swlist , .CR swmodify , (or the HP OpenView Software Distributor .CR swjob command). .TP .CI -D \0acl_entry Deletes an existing entry from the ACL associated with the specified objects using .CR swacl . .TP .CI -f \0software_file Read the list of .I selections from .I software_file instead of (or in addition to) the command line operands. .TP .CI -F \0acl_file Assigns the ACL contained in .IR acl_file to the specified object using .CR swacl . .RS .IP .IR "The -J option applies only to HP OpenView Software Distributor" .RE .PP .TP 10 .CI -J \0job_id Executes the previously scheduled job. This option is used by the .C swagentd to initiate scheduled jobs. .TP .CI -l \0level List all objects at the specified .IR level when using .CR swlist , or define the level of the objects when using .CR swacl , or .CR swreg . .TP .CI -M \0acl_entry Adds a new ACL entry or changes the permissions of an existing entry using .CR swacl . .RS .IP .IR "The -Q option applies only to HP OpenView Software Distributor" .RE .PP .TP 10 .CI -Q \0date Schedules the command for this date and time. .TP .CI -s \0source Specifies which source depot, psf file, or tape from which software will be installed, copied, listed, or packaged. .TP .CI -C \0session_file Save the current options and operands to .IR session_file . You can enter a relative or absolute path with the file name. The default directory for session files is .CR /.sw/sessions/ . You can recall a session file with the .CI -S .I session_file option. From an interactive session, you can save session information into a file at any time with the .I File/Save Session or .I File/Save Session As option. You can save session information from a command-line session with the .C -C .I session_file option. In addition, each command automatically creates a session file of the most recent session information and names the file .CR /.sw/sessions/sw.last . .TP .CI -S \0session_file Execute .C swinstall or .C swcopy based on the options and operands saved from a previous session, as defined in .IR session_file . You can save session information to a file with the .C -C .I session_file option. .TP .CI -t \0target_file Read the list of .I target_selections from .I target_file instead of (or in addition to) the command line operands. .TP .CI -x \0option=value Set the session .I option to .I value and override the default value (or a value in an alternate .IR option_file specified with the .C -X option). Multiple .C -x options can be specified. .TP .CI -X \0option_file Read the session options and behaviors from .IR option_file . These values defined in this file override the default values. .RE .\" .\" .\" .bp .PP .SS Operands .PP The .I selections operand are .I software_selections for most SD commands. For the .CR swjob ( .I HP OpenView Software Distributor command) and .CR swreg commands, the selections are .I job_ids (HP OpenView Software Distributor) and .I roots_or_depots respectively. The SD commands support the following syntax for each .IR software_selection : .IP .C bundle[.product[.subproduct][.fileset]][,version] .P or .IP .C product[.subproduct][.fileset][,version] .P The .C version component has the form: .IP .C [,r .IR .C revision][,a .IR .C arch][,v .IR .C vendor][,c .IR .C category] .P or .IP .C [instance_id] .P where .IR can be: ==, >=, <=, <, >, or != which performs individual comparisons on dot-separated fields. For example, r>=BB.10.00 means choose all revisions that are greater than or equal to BB.10.00. The system will compare each dot-separated field to find matches. Software will only be selected when matches within each field are satisfied. Wildcards are not allowed with these operators. .P The .C = (equals) relational operator is also allowed to specify a particular version component. For .CR swlist , .CR swpackage , and .CR swmodify , it also supports the shell pattern matching notations []*?! or wildcards to specify more than one version of a software product. .P All version components are repeatable within a single specification (e.g. r>=AA.12, r.log Defines the default log file for each SD command. (The agent logfiles are always located relative to the target depot or target root, e.g. .C /var/spool/sw/swagent.log and .CR /var/adm/sw/swagent.log .) .IP Applies to all commands except .CR swacl , .CR swlist , and .CR swjob (HP OpenView Software Distributor). .\" .TP .C max_agents=-1 The maximum number of agents that are permitted to run simultaneously. The value of -1 means that there is no limit. .IP Applies to .CR swagentd . .\" .\" .TP .C media_capacity=1330 If creating a distribution tape, this keyword specifies the capacity of the tape in Mbytes. This option is required if the media is not a DDS tape or a disk file. Without this option, .C swpackage sets the size to 1330 Mbytes for tape and "free space up to minfree" on a disk file. .IP Applies to .CR swpackage . .\" .TP .C mount_cmd=/etc/mount Defines the command called by the agent to mount all filesystems. .IP Applies to .CR swagent . .\" .TP .C reboot_cmd=/etc/reboot Defines the command called by the agent to reboot the system. .IP Applies to .CR swagent . .\" .TP .C source_cdrom=/SD_CDROM Defines the default location of the source CD-ROM. This syntax can be .CR host:path . .IP Applies to .CR swinstall . .\" .TP .C source_directory=/var/spool/sw Defines the default location of the source depot. This syntax can be .CR host:path , except for .C swpackage which requires the simple .CR path . The .C -s option overrides this value. .IP Applies to .CR swcopy , .CR swinstall , and .CR swpackage . .\" .bp .TP .C source_file=psf Defines the default location of the source product specification file (PSF). The .CR host:path syntax is not allowed, only a valid .CR path can be specified. The .C -s option overrides this value. .IP Applies to .CR swpackage and .CR swmodify . .\" .TP .C source_tape=/dev/rmt/0m Defines the default location of the source tape, usually the character-special file of a local tape device. If the .CR host:path syntax is used, the host must match the local host. The .C -s option overrides this value. .IP Applies to .CR swcopy and .CR swinstall . .\" .TP .C source_type=directory Defines the default source type: .CR cdrom , .CR file , .CR directory , or .CR tape . The source type derived from the .C -s option overrides this value. .IP Applies to .CR swcopy , .CR swinstall , and .CR swpackage . (The values .CR cdrom , and .CR tape apply to .CR swcopy and .CR swinstall only. The value .CR file applies to .CR swpackage only.) .TP .C system_file_path=/stand/system Defines the path to the kernel's template file. This path is passed to the .C system_prep_cmd via the .C SW_SYSTEM_FILE_PATH environment variable. .IP Applies to .CR swagent . .TP .C system_prep_cmd=/usr/lbin/sysadm/system_prep Defines the kernel build preparation script called by the agent. This script must do any necessary preparation so that control scripts can correctly configure the kernel about to be built. This script is called before any kernel filesets have been loaded. .IP Applies to .CR swagent . .\" .TP .C target_directory=/var/spool/sw Defines the default location of the target depot. .IP Applies to all commands that operate on depots. .\" .TP .C target_tape=/dev/rmt/0m Defines the default location of the target tape device (file). .IP Applies to .CR swpackage . .\" .TP .C target_type=directory Defines the default type of depot to create, either .CR directory or .CR tape . The target type derived from the .C -d option overrides this value. .IP Applies to .CR swpackage . .TP .C uncompress_cmd= Defines the command to uncompress files when installing, copying, or packaging. This command processes files which were stored on the media in a compressed format. If the .CR compression_type of the file is .C gzip then the internal uncompression .RC ( funzip ) is used instead of the external .CR uncompress_cmd . .IP Applies to .CR swpackage and .CR swagent . .\" .RE .\" .\" .\" .PP .B "System Policy Options" .br These options may be used to set system policy related to the behavior of the commands. .PP .RS .TP 10 .\".C authentication_service=internal .\"Applies to all commands. .\" .\"Use the internal authentication scheme. .\".TP .\".C protection_level=none .\"Applies to all commands. .\" .\"Level of DCE data protection. .\" .TP .\" .C auto_kernel_build=true Normally set to true. Specifies whether the removal of a kernel fileset should rebuild the kernel or not. If the kernel rebuild succeeds, the system automatically reboots. If set to false, the system continues to run the current kernel. .IP If the .CR auto_kernel_build option is set to .CR true , the .CR autoreboot option must also be set to .CR true . If the .CR auto_kernel_build option is set to .CR false , the value of the .CR autoreboot option does not matter. .IP Applies to .CR swremove only. .\" .TP .C autoreboot=false Prevents the removal of software requiring a reboot from the non-interactive interface. If set to .CR true , then this software can be removed and the target system(s) will be automatically rebooted. .IP An interactive session always asks for confirmation before software requiring a reboot is removed. .IP If the .CR auto_kernel_build option is set to .CR true , the .CR autoreboot option must also be set to .CR true . If the .CR auto_kernel_build option is set to .CR false , the value of the .CR autoreboot option does not matter. .IP Applies to .CR swinstall and ip Defines the default compression type used by the agent when it compresses files during or after transmission. If .C uncompress_files is set to false, the .C compression_type is recorded for each file compressed so that the correct uncompression can later be applied during a .CR swinstall , or a .C swcopy with .C uncompress_files set to true. The .C compress_cmd specified must produce files with the .C compression_type specified. The .C uncompress_cmd must be able to process files of the .C compression_type specified unless the format is .CR gzip , which is uncompressed by the internal uncompressor .RC ( funzip ). .IP Applies to .CR swagent . .TP .C create_target_acls=true If creating a target depot, .C swpackage will create Access Control Lists (ACLs) for the depot (if it is new) and all products being packaged into it. If set to .CR false , and if the user is the superuser, .C swpackage will not create ACLs. (The .C swpackage command never creates ACLs when software is packaged on to a distribution tape.) .IP Applies to .CR swpackage . .\" .TP .C create_target_path=true Causes the agent to create the target directory if it does not already exist. If set to .CR false , a new target directory will not be created. This option can prevent the erroneous creation of new target depots. .IP Applies to .CR swcopy and .CR swinstall . .\" .bp .TP .C follow_symlinks=false Do not follow symbolic links in the package source files, but include the symbolic links in the packaged products. A value of .C true for this keyword causes .C swpackage to follow symbolic links in the package source files and include the files they reference in the packaged products. .IP Applies to .CR swpackage . .TP .C include_file_revisions=false Do not include each source file's revision attribute in the products being packaged. Because this operation is time consuming, by default the revision attributes are not included. If set to .CR true , .C swpackage will execute .CR what(1) and possibly .CR ident(1) (in that order) to try to determine a file's revision attribute. .IP Applies to .CR swpackage . .\" .TP .C layout_version=1.0 The object and attribute syntax of SD now conforms to the .C layout_version of 1.0 from the IEEE POSIX 1387.2 Software Administration standard. This options controls to which .C layout_version the SD commands write distributions and swlist output. .IP Supported values are "0.8" and "1.0". The value of "1.0" should be used for future compatibility; the SD commands still accept the old keyword names as well as the new ones. The value of "0.8" should only be used to create distributions readable by older versions of SD. .IP Applies to .CR swpackage , .CR swcopy , .CR swmodify , and .CR swlist . .\" .TP .C mount_all_filesystems=true By default, the SD commands attempt to mount all filesystems in the .IR /etc/checklist file at the beginning of the analysis phase, to ensure that all listed filesystems are mounted before proceeding. This policy helps to ensure that files are not loaded into a directory that may be below a future mount point, and that the expected files are available for a remove or verify operation. .IP If set to .CR false , the mount operation is not attempted, and no check of the current mounts is performed. .IP Applies to .CR swconfig , .CR swcopy , .CR swinstall , .CR swremove , and .CR swverify . .\" .TP .C package_in_place=false If set to .CR true , .C swpackage will package the specified products such that the target depot will not contain the files that make up a product. Instead, .C swpackage inserts references to the original source files used to build a product. This behavior allows products to be packaged without consuming the full disc space of copying all the source files into the target depot. .IP Applies to .CR swpackage . .\" .TP .C register_new_depot=true Causes .C swcopy to register a newly created depot with the local .CR swagentd . This action allows other SD commands to automatically "see" this depot. If set to .CR false , a new depot will not be automatically registered. (It can be registered later with the .C swreg command.) .IP Applies to .CR swcopy . .\" .TP .C register_new_root=true Causes .C swinstall to register a newly created alternate root with the local .CR swagentd . This action allows other SD commands to automatically "see" this root. If set to .CR false , a new root will not be automatically registered. (It can be registered later with the .C swreg command.) .IP Applies to .CR swinstall . .\" .TP .C remove_empty_depot=true Remove an empty depot when the last product is removed. If set to .CR false , an empty depot will not be removed, preserving any depot ACLs. .IP Applies to .CR swremove . .RS .IP .IR "The following option applies only to HP OpenView Software Distributor" .RE .PP .TP 10 .C remove_fanout_depot=true When an install job to a PC is removed the software associated with that job is automatically removed from the PC depot. If the software that is part of this job is the same software being used by another job, then be sure to not delete the software as part of the job removal. If the software on the PC depot should be retained, set this option to .CR false . .IP Applies to .CR swjob . .TP .C select_local=true If no .IR target_selections are specified, select the default .C target_directory of the local host as the .IR target_selection for the command. .IP Applies to .CR swacl , .CR swconfig , .CR swcopy , .CR swinstall , .CR swlist , .CR swreg , .CR swremove , and .CR swverify . .\" .TP .C write_remote_files=false Prevents the installation, copying, or packaging of files to a target which exists on a remote (NFS) filesystem. Also prevents the removal of files from a remote filesystem. All files destined for (or already on) a remote filesystem will be skipped. .IP If set to .CR true and if the superuser has write permission on the remote filesystem, the remote files will not be skipped, but will be installed, copied, packaged, or removed. .IP Applies to .CR swcopy , .CR swinstall , .CR swpackage , and .CR swremove . .\" .\".TP .\".C use_dce_directory_service=false .\"Applies to all except .\".C swpackage .\"and .\".CR swmodify . .\" .\"Should the DCE directory or naming services be used? .\" .RE .\" .\" .\" .PP .B "Software Selection Options" .br These options may be used to assist in software selections. .PP .RS .TP 10 .C autoselect_dependencies=true Controls the automatic selection of prerequisite and corequisite software that is not explicitly selected by the user. When set to .CR true , The requisite software will be automatically selected for configuration. When set to .CR false , requisite software, which is not explicitly selected, will not be automatically selected for configuration. .IP Applies to .CR swconfig , .CR swcopy , .CR swinstall , and .CR swverify . .TP .C autoselect_dependents=false Controls the automatic selection of dependent software that is not explicitly selected by the user. A dependent is the opposite of a requisite. A dependent fileset has established either a prerequisite or a corequisite on the fileset under discussion. Specifying .C true causes dependent software to be automatically selected for the operation. The default, .C false causes dependent software, which is not explicitly selected, to not be automatically selected for the operation. .IP Applies to .CR swconfig and .CR swremove . .TP .C autoselect_reference_bundles=true If .CR true , bundles that are .C sticky will be automatically installed, or copied, along with the software it is made up of. If .CR false , the software can be installed, or copied, without automatically including .C sticky bundles that contain it. .IP For .CR swremove , if set to .CR true , any bundle with the is_sticky attribute set to true is removed automatically when the last of its contents is removed. If set to .CR false , the sticky bundles will not be automatically removed. .IP Applies to .CR swcopy , .CR swinstall , and .CR swremove . .\" .TP .C match_target=false If set to .CR true , other software selections are ignored and software selection is done by locating filesets on the source that match the target system's installed filesets. If multiple targets are specified, the first in the list is used as the basis for selections. .IP Applies to .CR swinstall . .TP .C software_view=products Indicates the software view to be used by the interactive interface of the commands and by .CR swlist for the default listing level. It can be set to products, all_bundles, or a bundle category tag (to indicate to show only bundles of that category). .IP Applies to .CR swcopy , .CR swinstall , .CR swlist , and .CR swremove . .RE .\" .\" .\" .PP .B "Version Management Options" .br These options may be used to set policies for the management of software versions. .PP .RS .TP 10 .C allow_downdate=false Prevents the installation of an older revision of fileset that already exists at the targets. (Many software products do not support "downdating".) If set to .CR true , the older revision can be installed. .IP Applies to .CR swinstall . .\" .TP .C allow_incompatible=false Requires that the software products which are being installed be "compatible" with the target selections. (All of the target selections must match the list of supported systems defined for each selected product.) If set to .CR true , target compatibility is not enforced. .IP Applies to .CR swconfig , .CR swinstall , and .CR swverify . .\" .TP .C allow_multiple_versions=false Prevents the installation or configuration of another, independent version of a product when a version already is already installed or configured at the target. .IP If set to .CR true , another version of an existing product can be installed into a new location, or can be configured in its new location. Multiple versions can only be installed if a product is locatable. Multiple configured versions will not work unless the product supports it. .IP Applies to .CR swconfig , .CR swinstall , and .CR swverify . .\" .TP .C defer_configure=false Causes .C swinstall to automatically configure the .IR software_selections after they are installed. When an alternate root directory is specified, .C swinstall never performs the configuration task, since only hosts using the software should be configured. If set to .CR true , this option allows configuration to be deferred even when the root directory is .CR / . .IP When installing a second (third, ...) version of a product, it will not be configured if another version is already configured. The .C swconfig command must be run separately. .IP Applies to .CR swinstall . .\" .TP .C reconfigure=false Prevents software which is already in the CONFIGURED state from being reconfigured. If set to .CR true , CONFIGURED software can be reconfigured. .IP Applies to .CR swconfig . .\" .RE .\" .\" .\" .PP .B "Reliability Options" .br These options may be used to tune or control behaviors in order to increase reliability. .PP .RS .TP 10 .C check_contents=true Causes .C swverify to verify the timestamp, size, and checksum attributes of files. If set to .CR false , these attributes are not verified. .IP Applies to .CR swverify . .\" .TP .C check_permissions=true Causes .C swverify to verify the mode, owner, UID, group, and GID attributes of installed files. If set to .CR false , these attributes are not verified. .IP Applies to .CR swverify . .\" .TP .C check_requisites=true Causes .C swverify to verify that the prerequisite and corequisite dependencies of the software selections are being met. If set to .CR false , these checks are not performed. .IP Applies to .CR swverify . .TP .C check_scripts=true Causes .C swverify to run the fileset/product verify scripts for installed software. If set to .CR false , these scripts are not executed. .IP Applies to .CR swverify . .\" .TP .C check_volatile=false Causes .C swverify to not verify those files marked as volatile (i.e. can be changed). If set to .CR true , volatile files are also checked (for installed software). .IP Applies to .CR swverify . .TP .C loglevel=1 Controls the log level for the events logged to the command logfile, the target agent logfile, and the source agent logfile. A value of .C 1 enables verbose logging to the logfiles. A value of .C 2 enables very verbose logging to the logfiles. .IP Applies to .CR swconfig , .CR swcopy , .CR swinstall , .CR swmodify , .CR swpackage , .CR swremove , and .CR swverify . .RS .IP .IR "The following option applies only to HP OpenView Software Distributor" .RE .PP .TP 10 .C poll_now=false The status information displayed for a PC install job is as recent as the last time the daemon polled remote targets for information (see the option .CR job_polling_interval ). If the most recent status is wanted set this option to .CR true . .IP Applies to .CR swjob . .TP .C reinstall=false When re-installing (or re-copying) an existing version of a fileset, this option causes that fileset to be skipped, i.e. not re-installed. If set to .CR true , the fileset will be re-installed (re-copied). .IP Applies to .CR swinstall and .CR swcopy . .\" .\" .TP .C reinstall_files=true Causes all the files in a fileset to always be re-installed, re-copied, or re-packaged, even when the file already exists at the target and is identical to the new file. If set to .CR false , files that have the same .IR checksum (see next option), size and timestamp will not be re-installed, re-copied, or re-packaged. This check enhances performance on slow networks or slow discs. .IP Applies to .CR swinstall , .CR swcopy , and .CR swpackage . .\" .TP .C reinstall_files_use_cksum=true This option affects the operation when the .CR reinstall_files option is set to false. It causes the checksums of the new and old file to be computed and compared to determine if the new file should replace the old one. (The checksum is slower, but is a more robust way to check for files being equivalent.) If set to .CR false , the checksums are not computed, and files are (not) reinstalled based only on their size and timestamp. For .CR swpackage , the default value for this option is .CR false . .IP Applies to .CR swcopy , .CR swinstall , and .CR swpackage . .RE .\" .\" .\" .PP .B "Performance Tuning Options" .br These options may be used to tune or control behaviors in order to increase performance. .PP .RS .TP 10 .C compress_files=false If set to .CR true , files are compressed, if not already compressed, before transfer from a source. This will enhance performance on slower networks for .CR swcopy and .CR swinstall . and will result in smaller depots for .CR swcopy and .CR swpackage , unless the .CR uncompress_files is also set to .CR true . .IP Applies to .CR swcopy , .CR swinstall , and .CR swpackage . .\" .RS .bp .IP .IR "The following job_polling options apply only to HP OpenView Software Distributor" .RE .PP .TP 10 .C job_polling_interval=30 Defines the polling interval, in minutes, used by the daemon. It specifies how often a PC install job will be polled in order to cache the progress of remote targets on the controller. .IP Applies to .CR swinstall . .TP .C minimum_job_polling_interval=1 Defines how often, in minutes, the daemon will wake up and scan the job queue to determine if any scheduled jobs need to be initiated or if any PC install jobs need their remote target status cached locally (see .CR job_polling_interval ). If set to 0, no scheduled jobs will be initiated, and no caching of PC install jobs will occur. .IP Applies to .CR swagentd . .TP .C polling_interval=2 Defines the polling interval used by interactive (GUI) sessions. It specifies how often each target agent will be polled to obtain status information about the task being performed. When operating across wide-area networks, the polling interval can be increased to reduce network overhead. .IP Applies to .CR swcopy , .CR swinstall , and .CR swremove . .TP .C retry_rpc=1 Defines the number of times a lost source connection will be retried during file transfers. A lost connection is one that has timed out. When used in conjunction with the .C rpc_timeout option, the success of installing over slow or busy networks can be increased. If set to zero, then any .C rpc_timeout to the source will cause the task to abort. If set from 1 to 9, then the install of each fileset will be attempted that number of times. The reinstall_files option should also be set to false to avoid installing files within the fileset that were successfully installed. .IP Applies to .CR swcopy and .CR swinstall . .TP .C "rpc_binding_info=ncacn_ip_tcp:[2121] or rpc_binding_info= ncadg_ip_udp:[2121]" Defines the protocol sequence and endpoint which the command should use to contact the target .CR swagentd . For the .CR swagentd process itself, this defines all of the protocol sequences and endpoints which may be used to contact it (the protocols and endpoints that the .C swagentd process is listening on, by default set to be both .C ncadg_ip_udp:[2121] and .CR ncacn_ip_tcp:[2121] ). For all commands except .C swagentd only one value is allowed. These values should be consistent among all hosts that work together. The value (or values for .CR swagentd ,) can have following form: .RS .IP - A DCE string binding containing a protocol sequence and an endpoint. The syntax is: .CR protocol_sequence:[endpoint] . .IP - The name of a DCE protocol sequence with no endpoint specified. The syntax is: .CR protocol_sequence , for example .CR ncadg_ip_udp or .CR ncacn_ip_tcp . (A trailing .C : can be attached to the protocol sequence, it has no effect.) Since no endpoint is specified, the DCE endpoint mapper .I rpcd must be running and will be used to find the endpoint registered by the .CR swagentd . .IP - The literal string .CR all . This entry means to use (try) all protocol sequences supported by the DCE RPC. It should be the only entry in the list. The DCE endpoint mapper .C rpcd also must be running in order to use this option. .RE .IP Applies to all commands except .CR swpackage and .CR swmodify . .TP .C rpc_timeout=7 For HP OpenView Software Distributor, .CR rpc_timeout=5 . Relative length of the communications timeout. This is a value in the range from 0 to 9 and is interpreted by the DCE RPC. Higher values mean longer times; you may need a higher value for a slow or busy network. Lower values will give faster recognition on attempts to contact hosts that are not up, or are not running the .CR swagentd . Each value is approximately twice as long as the preceding value. A value of 5 is about 30 seconds for the .C ncadg_ip_udp protocol sequence. This option may not have any noticeable impact when using the .C ncacn_ip_tcp protocol sequence. .IP Applies to all commands except .C swpackage and .CR swmodify . .TP .C uncompress_files=false If the files being transferred from a source are compressed, setting this option will uncompress the files before storing them on the target depot. .IP Applies to .CR swcopy and .CR swpackage . .TP .C use_alternate_source=false Empowers each target agent to use its own, configured alternate source, instead of the one specified by the user. If .CR false , each target agent will use the same source, namely the source specified by the user and validated by the command. If .CR true , each target agent will instead use its own configured value for the source. .IP Applies to .CR swcopy and .CR swinstall . .\" .RE .\" .\" .\" .PP .B "Error Control Options" .br These options may be used to override errors. They should be used with caution. .PP .RS .TP 10 .C enforce_dependencies=true Requires that all dependencies specified by the .IR software_selections be resolved either in the specified source, or at the .IR target_selections themselves. .IP The .CR swconfig , .CR swcopy , and .CR swinstall commands will not proceed unless the dependencies have also been selected or already exist at the target in the correct state (INSTALLED, CONFIGURED, or AVAILABLE). This prevents unusable software from being installed on the system. It also ensures that depots contain usable sets of software. .IP For .CR swremove , if a selected fileset has dependents (i.e. other software depends on the fileset) and they are not selected, do not remove the selected filesets. .IP If set to .CR false , dependencies will still be checked, but not enforced. Corequisite dependencies, if not enforced, may keep the selected software from working properly. Prerequisite dependencies, if not enforced, may cause the installation or configuration to fail. .IP Applies to .CR swconfig , .CR swcopy , .CR swinstall , .CR swremove , and .CR swverify . .TP .C enforce_dsa=true Prevents a command from proceeding past the analysis phase if the disk space required is beyond the available free space of the impacted filesystems. If set to .CR false , then the install, copy, or package operation will use the filesystems' minfree space and may fail because it reaches the filesystem's absolute limit. .IP Applies to .CR swcopy , .CR swinstall , and .CR swpackage . .\" .TP .C enforce_kernbld_failure=true Prevents .CR swinstall from proceeding past the kernel build phase if the kernel build processes fail. If set to .CR false , then the install operation will continue (without suspension if in the interactive mode) despite failure or warnings from either the system preparation process or the kernel build process. .IP Applies to .CR swinstall . .TP .C enforce_scripts=true If a fileset/product .IR checkinstall or .IR checkremove script fails (i.e. returns with exit code 1), none of the filesets in that product will be installed or removed. If set to .CR false , the install or remove operation will proceed even when a check script fails. .IP Applies to .CR swinstall and .CR swremove . .RS .IP .IR "The following option applies only to HP OpenView Software Distributor" .RE .TP 10 .C force_job_removal=false By default, the job information is removed from the central controller only after removing the job information stored on each of the targets succeeds. If the job should be removed regardless of the success of the removal of job information from targets, set this option to .CR true . .IP Applies to .CR swjob . .\" .\" .RE .\" .\" .\" .PP .B "Miscellaneous Options" .br These are additional miscellaneous options. .PP .RS .TP 10 .C control_files= When adding or deleting control file objects, this option lists the tags of those control files. There is no supplied default. If there is more than one tag, they must be separated by whitespace and surrounded by quotes. .IP Applies to .CR swmodify . .TP .C files= When adding or deleting file objects, this option lists the pathnames of those file objects. There is no supplied default. If there is more than one pathname, they must be separated by whitespace. .IP Applies to .CR swmodify . .\" .RS .IP .IR "The following option applies only to HP OpenView Software Distributor" .RE .PP .TP 10 .C job_title= This is an ASCII string giving a title to a job. It is displayed along with the job ID to provide additional identifying information about a job when .CR swjob is invoked. .IP Applies to .CR swconfig , .CR swcopy , .CR swinstall , .CR swremove , and .CR swverify . .TP .C level= Defines the level (or depth) of a listing produced by .CR swlist : one of ( .CR machine , .CR user , .CR group , HP OpenView Software Distributor only) .CR depot , .CR root , .CR bundle , .CR product , .CR subproduct , .CR fileset , or .CR file . .IP Defines the level of ACLs to view/modify with .CR swacl : one of .CR host , .CR depot , .CR root , .CR product , .CR product_template , .CR global_soc_template , or .CR global_product_template . Defines the level of object to register or unregister with .CR swreg : one of .CR depot or .CR root . .IP Applies to .CR swlist and .CR swacl . .TP .C objects_to_register= Defines the default objects to register or unregister. There is no supplied default (see .C select_local above). If there is more than one object, they must be separated by spaces. .IP Applies to .CR swreg . .\" .TP .C one_liner= Defines the attributes which are listed in the non-verbose listing. .IP Applies to .CR swlist and HP OpenView Software Distributor's .CR swjob . .\" .TP .C software= Defines the default .IR software_selections . There is no supplied default. If there is more than software selection, they must be separated by spaces. Software is usually specified in a software input file, as operands on the command line, or in the GUI. .IP Applies to all commands except .CR swreg and HP OpenView Software Distributor's .CR swjob . .\" .TP .C targets= Defines the default .IR target_selections . There is no supplied default (see .C select_local above). If there is more than target selection, they must be separated by spaces. Targets are usually specified in a target input file, as operands on the command line, or in the GUI. .IP Applies to all commands. .\" .TP .C verbose= Controls the verbosity of a non-interactive command's output. A value of .C 0 disables output to stdout. (Error and warning messages are always written to stderr). A value of .C 1 enables verbose messaging to stdout. For .CR swpackage and .CR swmodify , a value of .C 2 enables very verbose messaging to stdout. .IP For the .C swlist command, a verbose listing includes all attributes that have been defined for the appropriate level of each .IR software_selection operand. The attributes are listed, one per line, prefaced by the attribute keyword. .IP The .C -v option overrides this default if it is set to 0. .IP Applies to all commands. .\" .RE .\" .\" .\" .PP .SS Session Files .PP Each invocation of an SD command defines a task session. Most SD commands automatically save options, source information, software selections, and target selections before the task actually commences. This lets you re-execute the command even if the session ends before it is complete. .PP Each session is automatically saved to the file .IR $HOME/.sw/sessions/swinstall{swcopy}.last . This file is overwritten by each invocation of the command. .PP You can also save session information from interactive or command-line sessions. From an interactive session, you can save session information into a file at any time by selecting the .I Save Session or .I Save Session As option from the .I File menu. From a command-line session, you can save session information by executing the command with the .C -C .I session__file option. .PP A session file uses the same syntax as the defaults files. You can specify an absolute path for a session file. If you do not specify a directory, the default location for a session file is .IR /.sw/sessions/ . .PP To re-execute a saved session from an interactive session, use the .I Recall Session option from the .I File menu. To re-execute a session from a command-line, specify the session file as the argument for the .C -S .I session__file option of the command. .PP Note that when you re-execute a session file, the values in the session file take precedence over values in the system defaults file. Likewise, any command line options or parameters that you specify when you invoke the command take precedence over the values in the session file. .PP .SS Software and Target Lists .PP Most SD commands support software and target selections from separate input files (see the .C -f and .C -t options). Software and targets specified in these files will be selected for operation. .P Additionally, commands that support an interactive interface read a list of possible hosts to operate on from the values found in: .IP .C /var/adm/sw/defaults.hosts - the system-wide default list of hosts, .IP .C $HOME/.sw/defaults.hosts - the user-specific default list of hosts. .P Hosts in this file will not be marked for operation, but provide a default list from which to choose. For each interactive command, target hosts containing roots, containing depots, and hosts serving as fanout servers are specified in separate lists ( .CR hosts , .CR hosts_with_depots , and .C fanout_servers respectively). The list of hosts are enclosed in {} braces and separated by white space (blank, tab and newline). For example: .RS .TP 4 .C swinstall.hosts={hostA hostB hostC hostD .PD 0 .TP .C hostE hostF} .TP .C swinstall.fanout_servers={pc1 pc2} (HP OpenView Software Distributor only) .TP .C swcopy.hosts_with_depots={hostS} .TP .C swcopy.fanout_servers={pc1 pc2} (HP OpenView Software Distributor only) .TP .C swremove.hosts={hostA hostB hostC hostD .TP .C hostE hostF} .TP .C swremove.hosts_with_depots={hostS} .PD .RE .RS .IP .IR "The following PC information applies only to HP OpenView Software Distributor" .RE .PP For installing to PCs, PC target lists are generated automatically by querying the PC file server associated with a PC Controller. Any user, group, or machine known to the file server will be included in the default list from which to choose. Additionally, all machines known to the file server will by default be selected for installation when selecting a PC Controller. .PP .SS Environment Variables .PP Most SD programs set environment variables for use by the software control scripts being executed. The only SD commands that do not use environment variables are: .CR swcluster , .CR swgettools , .CR swpackage , and .CR update . .PP .C LANG .IP Determines the language in which messages are displayed. If LANG is not specified or is set to the empty string, a default value of .C C is used. See .C lang(5) for more information. .IP .PP This variable applies to all SD commands except: .CR swcluster , .CR swgettools , .CR swpackage , and .CR update . .PP NOTE: The language in which the SD agent and daemon log messages are displayed is set by the system configuration variable script, .CR /etc/rc.config.d/LANG . For example, .CR /etc/rc.config.d/LANG , must be set to .CR LANG=ja_JP.SJIS or .CR LANG=ja_JP.eucJP to make the agent and daemon log messages display in Japanese. .PP .C SW_CONTROL_DIRECTORY .IP Defines the current directory of the script being executed, either a temporary catalog directory, or a directory within in the Installed Products Database (IPD). This variable tells scripts where other control scripts for the software are located (e.g. subscripts). .PP .C SW_DEFERRED_KERNBLD .IP Only applies to .CR swinstall . This variable is normally unset. If it is set, the actions necessary for preparing the system file .CR /stand/system cannot be accomplished from within the .IR postinstall scripts, but instead must be accomplished by the .IR configure scripts . This occurs whenever software is installed to a directory other than .IR / , such as for a cluster client system. This variable should be read only by the .IR configure and .IR postinstall scripts of a kernel fileset. The .CR swinstall command sets these environment variables for use by the kernel preparation and build scripts. .PP .C SW_INITIAL_INSTALL .IP Only applies to .CR swinstall . This variable is normally unset. If it is set, the .C swinstall session is being run as the back end of an initial system software installation ("cold" install). .PP .C SW_KERNEL_PATH .IP Only applies to .CR swinstall . The path to the kernel. The default value is .CR /stand/vmunix , defined by the .CR swagent option or .CR kernel_path . .PP .C SW_LOCATION .IP Defines the location of the product, which may have been changed from the default product directory. When combined with the .CR SW_ROOT_DIRECTORY , this variable tells scripts where the product files are located. .PP .C SW_PATH .IP A PATH variable which defines a minimum set of commands available to for use in a control script (e.g. .CR /sbin:/usr/bin ). .PP .C SW_ROOT_DIRECTORY .IP Defines the root directory in which the session is operating, either "/" or an alternate root directory. This variable tells control scripts the root directory in which the products are installed. A script must use this directory as a prefix to SW_LOCATION to locate the product's installed files. The configure script is only run when SW_ROOT_DIRECTORY is "/". .PP .C SW_SESSION_IS_KERNEL .IP Indicates whether a kernel build is scheduled for a kernel fileset selected for removal. This variable is exported to a fileset's control scripts and must be tested by .I preremove scripts to determine whether to undo any additions performed by the fileset's .I postinstall script at install time. .IP A .C "TRUE" value indicates that the selected kernel fileset is scheduled for a kernel build and that changes to .I /stand/system are required. A null value, indicates that a kernel build is not scheduled and that changes to .I /stand/system is not required. .IP The value of this variable is always equal to the value of .CR SW_SESSION_IS_REBOOT . .PP .C SW_SESSION_IS_REBOOT .IP Indicates whether a reboot is scheduled for a fileset selected for removal. Because all HP-UX kernel filesets are also reboot filesets, the values of this variables is always equal to the value of .CR SW_SESSION_IS_KERNEL . .PP .C SW_SOFTWARE_SPEC .IP This variable contains the fully qualified software specification of the current product or fileset. The software specification allows the product or fileset to be uniquely identified. .PP .C SW_SYSTEM_FILE_PATH .IP Only applies to .CR swinstall . The path to the kernel's system file. The default value is .CR /stand/system . .PP .SS Signals .PP The SD commands catch the signals SIGQUIT and SIGINT. If these signals are received, the command prints a message, sends a Remote Procedure Call (RPC) to the agents to wrap up, and then exits. .PP The agent ignores SIGHUP, SIGINT, and SIGQUIT. It immediately exits gracefully after receiving SIGTERM, SIGUSR1, or SIGUSR2. Killing the agent may leave corrupt software on the system, and thus should only be done if absolutely necessary. Note that when an SD command is killed, the agent does not terminate until completing the task in progress. .PP The daemon ignores SIGHUP, SIGINT and SIGQUIT. It immediately exits gracefully after receiving SIGTERM and SIGUSR2. After receiving SIGUSR1, it waits for completion of a copy or remove from a depot session before exiting, so that it can register or unregister depots. Requests to start new sessions are refused during this wait. .\"The daemon program ignores all terminal-related signals (SIGHUP, SIGQUIT, .\"SIGINT, SIGTSTP, SIGTTIN, and SIGTTOU). It will terminate gracefully on .\"receipt of SIGTERM. SIGUSR2 or SIGUSR1. With the first two signals, .\"this termination is immediate. With SIGUSR1, the daemon waits for any .\"agents serving .\".C swcopy .\"or .\".C "swremove -d" .\"sessions to terminate so they can register or unregister a depot; .\"requests to start new sessions are refused during this wait. .PP .SS Locking .PP SD commands use a common locking mechanism for reading and modifying both root directories and software depots. This mechanism allows multiple readers but only one writer on a root or depot. .PP The SD commands which modify software in an (alternate) root directory are restricted from simultaneous modification using .IR fcntl (2) locking on the file .IP .C var/adm/sw/products/swlock .P relative to the root directory (e.g. .IR /var/adm/sw/products/swlock). .PP The SD commands which modify software in a depot are restricted from simultaneous modification using .IR fcntl (2) locking on the file .IP .C catalog/swlock .P relative to the depot directory (e.g. .IR /var/spool/sw/catalog/swlock). .PP All commands set .C fcntl(2) read locks on roots and depots using the .C swlock file mentioned above. When a read lock is set, it prevents other SD commands from performing modifications (i.e. from setting write locks). .PP .SH RETURN VALUES .PP Each SD command invocation returns: .RS .TP 4 .C 0 The .C sw successfully completed. .PD 0 .TP .C 1 The .C sw failed on all .IR target_selections . .TP .C 2 The .C sw failed on some .IR target_selections . .PD .PP .SH DIAGNOSTICS .PP The .CR swconfig , .CR swcopy , .CR swinstall , .CR swremove , and .CR swverify commands support a preview mode, where operation will proceed through the analysis of each .IR target_selection , then exit before the actual task is performed. .PP The HP OpenView Software Distributor interactive interface (invoked using the .C sd command) and the .C swjob command can be used to view the current status of any job as well as the controller and target log files. .PP The .CR swpackage and .CR swmodify commands also support a preview mode. Their operation will proceed through the analysis and execution phases without modifying the target depot. .PP Preview is only applicable for non-interactive operation, since the interactive commands wait for confirmation after analysis. In the interactive mode, you can resolve invalid conditions that the commands discover before they actually begin loading or removing files. .PP .SS Standard Output .PP When non-interactive, the commands write messages for significant events. These events include: .RS .TP 2 \(bu a begin and end task message, .PD 0 .TP \(bu a message for starting the task on each host, and .PD 0 .TP \(bu a message for completing the task on each host. .PD .RE .PP When the .C verbose option is set, summary messages about the task are also sent to the standard output. .PP .SS Standard Error .PP When non-interactive, the commands also write messages for the following significant error events: .RS .TP 2 \(bu a message for each host failing analysis and .PD 0 .TP \(bu a message for each host failing the actual task. .PD .RE .PP .SS Logging .PP .PP All commands log major events on the host where the command was invoked. They log detailed events to the .C swagent log associated with each .IR target_selection . .PP .TP Command Log .br The commands log messages to .CR /var/adm/sw/sw.log . (The user can specify a different logfile by modifying the .C logfile option.) .TP Target Log .br A .C swagent process performs the actual .CR swacl , .CR swconfig , .CR swcopy , .CR swinstall , .CR swremove , and .CR swverify operation at each .IR target_selection . For operations on target root objects, the .C swagent logs messages to the file .C var/adm/sw/swagent.log beneath the root directory (e.g. .C / or an alternate root directory). For operations on target depot objects, the .C swagent logs messages to the file .C swagent.log beneath the depot directory (e.g. .CR /var/spool/sw ). .IP The .CR swagentd running on a host logs events to the file .CR /var/adm/sw/swagentd.log . .RS .IP .IR "The following PC information applies only to HP OpenView Software Distributor" .RE .PP .IP On a PC Controller, .CR SWAGENTD.EXE logs events and messages to the file .CR ...\\\\SD\\\\DATA\\\\SWAGENTD.LOG . .P Command, agent, and PC Controller log files can be viewed using the .C swjob command. .PP .\".SH EXAMPLES .\".PP .\".SH WARNINGS .\".PP .\".SH DEPENDENCIES .\".PP .SH LIMITATIONS .PP For PCs, the SD commands generally only apply to the PC Controller, or the PC depot on the PC Controller. The .C swinstall and .C swjob commands indirectly install to and retrieve information from PC targets. .PP The .C swpackage command is not used for PC software. PC software is packaged using the PC Console on the PC Controller, then copied (with .CR swcopy ) to a UNIX depot for subsequent distribution. .PP .SH FILES .PP .\" .C / .br .RS 8 Default destination for .CR update . .RE .\" .C /dev/rmt/0m .br .RS 8 Default source for Series 700 and 800 systems. .RE .\" .C /netdist .br .RS 8 Default destination for .C updist and source for .CR netdistd . .RE .\" .C /etc/fstab .br .RS 8 List of volumes that should be mounted. .RE .\" .C /etc/mnttab .br .RS 8 List of volumes currently mounted. .RE .\" .C /etc/services .br .RS 8 Networking services database, file describing networking services, including the netdist service. .RE .\" .C /usr/sbin/sw* .br .RS 8 The SD commands. .RE .\" .C /usr/lbin/swagent .br .RS 8 The SD agent. .RE .\" .C /usr/lib/nls/$LANG/sw*.cat .br .RS 8 The SD message catalogs. .RE .\" .C /var/adm/rupdate/filesets .br .RS 8 Directory where fileset files are stored .RE .\" .C /var/adm/rupdate/system .br .RS 8 Directory containing important information about and customized scripts for each fileset. .RE .\" .C /var/adm/rupdate/system/ fileset /index .br .RS 8 Provides information about the fileset, in particular, its version .RC ( update uses the version to decide if a dependee fileset is already current on the system and need not be reloaded) .RE .\" .C /var/adm/rupdate/system/ fileset /update_dest .br .RS 8 Names the destination directory under which a fileset was loaded, if other than .CR / . .RE .\" .C /var/adm/sw/ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. This directory is also the default location of logfiles. .RE .\" .C /var/adm/sw/security/ .br .RS 8 The directory which contains ACLs for the system itself, template ACLS, and the secrets file used to authenticate remote requests. .RE .\" .C /var/adm/sw/queue/ .br .RS 8 The directory which contains the information about all active and complete install, remove, and other jobs initiated by the SD commands. Applies only to HP OpenView Software Distributor. .RE .\" .C /var/adm/sw/host_object .br .RS 8 The file which stores the list of depots registered at the local host. .RE .\" .C /usr/lib/rupdate/jam .br .RS 8 Directory containing .SM JAM user interface information. .RE .\" .C /usr/lib/rupdate/update .br .RS 8 Directory containing files used by .C update and .C updist when run interactively. .RE .\" .C /usr/lib/sw/ui/ .br .RS 8 The directory which contains the description files used by the SD Graphical User Interfaces (GUIs). .RE .\" .C /usr/lib/sw/help/ .br .RS 8 The directory which contains the help files used by the SD GUIs' on-line help facility. .RE .\" .C /usr/lib/sw/sys.defaults .br .RS 8 Contains the master list of current SD options (with their default values). .RE .\" .C /var/adm/sw/defaults .br .RS 8 Contains the active system-wide default values for some or all SD options. .RE .\" .C $HOME/.sw/defaults .br .RS 8 Contains the user-specific default values for some or all SD options. .RE .\" .C /var/adm/sw/defaults.hosts .br .RS 8 Contains the system-wide default list of hosts to manage. .RE .\" .C $HOME/.sw/defaults.hosts .br .RS 8 Contains the user-specific default list of hosts to manage. .RE .\" .C /var/adm/sw/getdate.templ .br .RS 8 Contains the set of date/time templates used when scheduling jobs. .RE .\" .C $HOME/.sw/sessions/ .br .RS 8 Contains session files automatically saved by the SD commands, or explicitly saved by the user. .RE .\" .C /var/adm/sw/products/ .br .RS 8 The Installed Products Database (IPD), a catalog of all products installed on a system. .RE .\" .C /var/spool/sw/ .br .RS 8 The default location of a source and target software depot. .RE .\" .C /dev/rmt/0m .br .RS 8 The default location of a source and target tape. .RE .\" .C /var/tmp/update.log .br .RS 8 Log file describing the events that occurred during the update process, including errors, warnings, and notes. .RE .\" .C /var/tmp/update.cleanup .br .RS 8 List of files logged as non-removable, usually due to ``text file busy''. .RE .\" .C /var/tmp/update.script .br .RS 8 File written by .CR update during interactive invocation for later non-interactive invocation and for readback of default values. .RE .\" .C /var/tmp/updist.script .br .RS 8 File written by .CR updist during interactive invocation for later non-interactive invocation and for readback of default values. .RE .\" .C /var/tmp/update.kernbld .br .RS 8 Used by cluster nodes to rebuild kernels at the next reboot. .RE .\" .C /usr/lib/sw/examples/ .br .RS 8 The directory containing an example depot and example swpackage data. .RE .\" .C /usr/newconfig/var/adm/sw/ .br .RS 8 The directory containing the configurable data shipped for the SD product, which is conditionally copied into .C /var/adm/sw/ based on the existing configuration. .RE .\" .RS .IP .IR "The following applies only to HP OpenView Software Distributor" .RE .PP .C /usr/OV/registration/$LANG/sd.reg .br .RS 8 The registration file which integrates SD into the HP OpenView Network Node Manager. .RE .\" .C /usr/OV/help/$LANG/sd/ .br .RS 8 The directory which contains the help files used by the SD integration into OpenView. .RE .PP .SH PC FILES .PP .RS .IP .IR "The following applies only to HP OpenView Software Distributor" .RE .PP .\" .C ...\\\\SD\\\\CONSOLE\\\\*.EXE .br .RS 8 The SD PC commands. .RE .\" .C ...\\\\SD\\\\AGENTS\\\\*.EXE .br .RS 8 The SD PC agents. .RE .\" .C ...\\\\SD\\\\DATA\\\\ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. .RE .\" .C ...\\\\SD\\\\DATA\\\\DEPOT\\\\ .br .RS 8 The default location of the source and target PC depot. .RE .\" .C ...\\\\SD\\\\DATA\\\\SECURITY\\\\ .br .RS 8 The directory which contains ACLs for the system itself, template ACLS, and the secrets file used to authenticate remote requests. .RE .\" .C ...\\\\SD\\\\DATA\\\\QUEUE\\\\ .br .RS 8 The directory which contains the information about all active and complete install, remove, and other jobs initiated by the SD commands. .RE .\" .C ...\\\\SD\\\\DATA\\\\NADMIN.DST .br .RS 8 The database which defines all PC distribution jobs and PC target status. .RE .\" .C ...\\\\SD\\\\DATA\\\\NADMIN.INV .br .RS 8 The database which defines all PC target machines available for fanout installation. .RE .\" .C ...\\\\SD\\\\DATA\\\\SWAGENTD.LOG .br .RS 8 The log of all actions and events performed by the PC Controller. .RE .\" .C \\\\SWAGENTD.INI .br .RS 8 Contains the configurable options for the SD PC Controller. .RE .\" .C \\\\NADMIN.INI .br .RS 8 Contains the configurable options for the SD PC Console. .RE .PP .SH AUTHOR .PP The HP Software Distributor was developed by the Hewlett-Packard Company. .PP .SH SEE ALSO sd(4), swacl(1M), swagentd(1M), swcluster(1M), swconfig(1M), swcopy(1M), .\" swdepot(1M), swgettools(1M), swinstall(1M), swjob(1M), swlist(1M), swmodify(1M), swpackage(1M), swpackage(4), swreg(1M), swremove(1M), swverify(1M), update(1M), and the .IR "HP OpenView Software Distributor Administrator's Guide" or .IR "Managing HP-UX Software with SD-UX" manuals. .\" toc@\f3sd(5)\f1@@@create, distribute, install, monitor, and manage software .\" .\" index@\f4sd\f1 \- create, distribute, install, monitor, and manage software@@@\f3sd(5)\f1 .\" index@\f1create, distribute, install, monitor, and manage software@@@\f3sd(5)\f1 .\" index@\f1distribute, install, monitor, create, and manage software@@@\f3sd(5)\f1 .\" index@\f1install, monitor, create, distribute, and manage software@@@\f3sd(5)\f1 .\" index@\f1monitor, create, distribute, install, and manage software@@@\f3sd(5)\f1 .\" index@\f1manage, monitor, create, distribute, and install software@@@\f3sd(5)\f1 ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH sec_audit_events "5" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "enh,10234,R1.1,new manpage." .iX "events" "auditable" .iX "events" "security services" .iX "security services" "auditable events" .iX "auditable events" "security services" .iX "\*Lsec_audit_events\*O" .SH NAME \*Lsec_audit_events\*O - Auditable events for the security services .SH "DESCRIPTION" .PP Code is in place for auditing security-significant events in the Security Server. Among these events are .iX "events" "security service operations" .ML .LI Attempts at invoking Authentication Server/Ticket-granting Server/Privilege Server (AS/TGS/PS) operations. .LI Deletion of Security Server objects, including .ML .LI ACLs .LI accounts .LI pgo items .LI registry properties .LI registry/organization policies .LI registry master key .LE .LI Attempts at invoking an operation that modifies Security Server objects or updates an ACL. .LI Attempts at invoking operations that involve access control. .LI Failed client responses to the server's challenge, detected replays and invalid ticket requests. .LI The usage of cryptographic keys in the RPC runtime. .LI Attempts at changing the maintenance/operation states of the registry server. .LE .PP .iX "event class" "definitions" Event class definitions, together with filters, control the auditing execution at these code points. Filters can be updated dynamically. Filter files are maintained by a per-host audit daemon, and are shared among all the audit clients on the same host. The \*Ldcecp\*O command interface program is used for maintaining the .iX "\*Ldcecp\*O command" filters. (See the \*Ldcecp\*O reference page.) The \*Ldcecp\*O command is executable by all users and system administrators. The control on who is allowed to modify filters is done through the audit daemon's ACL, which maintains the filters. .PP .iX .iX "Security Server" "interfaces" "\*Lkrb5rpc\*O" .iX "Security Server" "interfaces" "\*Lrdaclif\*O" .iX "Security Server" "interfaces" "\*Lrdacliftmp\*O" .iX "Security Server" "interfaces" "\*Lrpriv\*O" .iX "Security Server" "interfaces" "\*Lrs_acct\*O" .iX "Security Server" "interfaces" "\*Lrs_query\*O" .iX "Security Server" "interfaces" "\*Lrs_rpladmn\*O" .iX "Security Server" "interfaces" "\*Lrs_update\*O" .iX "Security Server" "interfaces" "\*Lrsec_cert\*O" ...\" .iX "Security Server" "interfaces" "\*Lsecidmap\*O" .iX "\*Lkrb5rpc\*O interface" .iX "\*Lrdaclif\*O interface" .iX "\*Lrdacliftmp\*O interface" .iX "\*Lrpriv\*O interface" .iX "\*Lrs_acct\*O interface" .iX "\*Lrs_query\*O interface" .iX "\*Lrs_rpladmn\*O interface" .iX "\*Lrs_update\*O interface" .iX "\*Lrsec_cert\*O interface" Security Server RPC interfaces include \*Lkrb5rpc\*O, \*Lrdaclif\*O, \*Lrdacliftmp\*O, \*Lrpriv\*O, \*Lrs_acct\*O, \*Lrs_query\*O, \*Lrs_rpladmn\*O, \*Lrs_update\*O, and \*Lrsec_cert\*O. All the RPC interfaces .iX "authentication services" "\*Lrpc_c_authn_dce_secret\*O" .iX "\*Lrpc_c_authn_dce_secret\*O authentication service" are offered using the \*Lrpc_c_authn_dce_secret\*O authentication service. The Security Server's RPC runtime uses \*Ldce-rgy\*O as its authentication identity. Within the same process, the security server's UDP/IP interface provides Kerberos AS/TGS functions, with \*Lkrbtgt/cell_name\*O as its authentication identity. .PP The following are the audit code points in these Security Service interfaces, with their Event Types, Event Classes, and any Event-Specific Information. .SS "Authentication Interface (krb5rpc) Operations" .PP .iX "functions" "\*Lrsec_krb5rpc_sendto_kdc(\|)\*O" .iX "\*Lrsec_krb5rpc_sendto_kdc(\|)\*O function" The \*Lrsec_krb5rpc_sendto_kdc(\|)\*O function is an RPC interface operation for accessing Kerberos AS/TGS services. Ticket-granting tickets and application tickets are requested and returned. There is no access control on this interface other than what is within the Kerberos Ticket-granting mechanism itself; that is, the TGS request verification. .VL .LI "Event Type (Event Number, Event Classes)" \*LAS_Request (0x101, dce_sec_authent)\*O .VL .LI "Event-Specific Information" None .LE .LI "Event Type (Event Number, Event Classes)" \*LTGS_TicketReq (0x102, dce_sec_authent)\*O .VL .LI "Event-Specific Information" None .LE .LI "Event Type (Event Number, Event Classes)" \*LTGS_RenewReq (0x103, dce_sec_authent)\*O .VL .LI "Event-Specific Information" None .LE .LI "Event Type (Event Number, Event Classes)" \*LTGS_ValidateReq (0x104, dce_sec_authent)\*O .VL .LI "Event-Specific Information" None .LE .LE .SS "DACL Management Interface (rdaclif) Operations" .iX "DACL Management" interfaces" .iX "DACL Managemenet" "\*Lrdaclif\*O" .iX "\*Lrdaclif\*O operations" .iX "functions" "\*Lrdacl_lookup(\|)\*O" .iX "\*Lrdacl_lookup(\|)\*O function" The \*Lrdacl_lookup(\|)\*O operation retrieves an ACL of an object in the Security Server. Review of ACL associated with an object in Security Server is allowed if the caller has any access to the object. .VL .LI "Event Type (Event Number, Event Classes)" \*LACL_Lookup (0x105, dce_sec_control, dce_sec_query)\*O .VL .LI "Event-Specific Information" .iS char *component_name uuid_t manager_type sec_acl_type_t acl_type .iE .LE .LE .PP .iX "functions" "\*Lrdacl_replace(\|)\*O" .iX "\*Lrdacl_replace(\|)\*O function" The \*Lrdacl_replace(\|)\*O operation replaces the ACL of an object in the Security Server. The client must have the \*Lsec_acl_perm_owner\*O permission for the update to be carried out. .VL .LI "Event Type (Event Number, Event Classes)" \*LACL_Replace (0x106, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS char *component_name uuid_t manager_type sec_acl_type_t acl_type sec_acl_list_t old_acl_list sec_acl_list_t new_acl_list .iE .LE .LE .PP .iX "functions" "\*Lrdacl_get_access(\|)\*O" .iX "\*Lrdacl_get_access(\|)\*O function" The \*Lrdacl_get_access(\|)\*O operation determines the caller's access to a specified object. This call is authorized if the caller has any access to the object. .VL .LI "Event Type (Event Number, Event Classes)" \*LACL_GetAccess (0x107, dce_sec_control, dce_sec_query)\*O .VL .LI "Event-Specific Information" .iS char *component_name uuid_t manager_type sec_acl_permset_t net_rights .iE .LE .LE .PP .iX "functions" "\*Lrdacl_test_access(\|)\*O" .iX "\*Lrdacl_test_access(\|)\*O function" The \*Lrdacl_test_access(\|)\*O operation determines if the caller has the requested access. The return value of the call indicates whether the caller has the requested access to the object. .VL .LI "Event Type (Event Number, Event Classes)" \*LACL_TestAccess (0x108, dce_sec_control, dce_sec_query)\*O .VL .LI "Event-Specific Information" .iS char *component_name uuid_t manager_type sec_acl_permset_t desired_permset .iE .LE .LE .PP .iX "functions" "\*Lrdacl_get_manager_types(\|)\*O" .iX "\*Lrdacl_get_manager_types(\|)\*O function" The \*Lrdacl_get_manager_types(\|)\*O operation lists the types (UUIDs) of ACLs protecting an object. The caller must have some permissions on the object for each of the manager types that is defined for the object. Otherwise, no manager type is returned. .VL .LI "Event Type (Event Number, Event Classes)" \*LACL_GetMgrTypes (0x10A, dce_sec_control, dce_sec_query)\*O .VL .LI "Event-Specific Information" .iS char *component_name sec_acl_type_t acl_type .iE .LE .LE .PP .iX "functions" "\*Lrdacl_get_referral(\|)\*O" .iX "\*Lrdacl_get_referral(\|)\*O function" The \*Lrdacl_get_referral(\|)\*O operation obtains a referral to an ACL update site. This function is used when the current ACL site yields a \*Lsec_acl_site_readonly\*O error. Some replication managers will require all updates for a given object to be directed to a given replica. Clients of the generic ACL interface may know they are dealing with an object that is replicated in this way. This function allows them to recover from this problem and rebind to the proper update site. The client is required to have execute access on the parent of the object named by \*Lcomponent_name\*O. .VL .LI "Event Type (Event Number, Event Classes)" \*LACL_GetReferral (0x10B, dce_sec_control, dce_sec_query)\*O .VL .LI "Event-Specific Information" .iS char *component_name uuid_t manager_type sec_acl_type_t sec_acl_type .iE .LE .LE .SS "Privilege Server Interface (rpriv) Operations" .iX "Privilege Server" interfaces" .iX "Privilege Server" "\*Lrpriv\*O" .iX "\*Lrpriv\*O operations" .PP .iX "functions" "\*Lrpriv_get_ptgt(\|)\*O" .iX "\*Lrpriv_get_ptgt(\|)\*O function" The \*Lrpriv_get_ptgt(\|)\*O operation returns a privilege certificate to the Ticket-granting service. The caller supplies the group set, and the Privilege Server seals the group set in the authorization portion of a privilege Ticket-granting ticket, after first rejecting any groups that are not legitimately part of the caller credentials. A group will be rejected if the caller is not a member of the group, or the group is not allowed on project lists (the \*Lprojlist_ok\*O flag is not set). .PP There is no access control on this interface other than what was within the Kerberos Ticket-granting mechanism itself; that is, the TGS request verification. This call may result in growth of potential access set. Note that this is a pre-DCE 1.1 routine. .VL .LI "Event Type (Event Number, Event Classes)" \*LPRIV_GetPtgt (0x10C, dce_sec_authent, dce_sec_control)\*O .VL .LI "Event-Specific Information" .iS char *string client_address unsigned16 num_groups /* Number of local groups in PAC */ uuid_t groups /* num_groups local groups in PAC */ .iE .LE .LE .LE .SS "Registry Server Account Interface (rs_acct) Operations" .iX "Registry Server" interfaces" .iX "Registry Server" "\*Lrs_acct\*O" .iX "\*Lrs_acct\*O operations" .PP .iX "functions" "\*Lrs_acct_add(\|)\*O" .iX "\*Lrs_acct_add(\|)\*O function" The \*Lrs_acct_add(\|)\*O operation adds an account with a specified login name. The caller needs to have \*Lm\*O, \*La\*O, and \*Lu\*O (\*Lmgmt_info\*O, \*Lauth_info\*O, and \*Luser_info\*O) permissions on the principal of the account that is to be added. The constituent principal, group, and organization (PGO) items for an account must be added before the account can be created. Also, the principal must have been added as a member of the specified group and organization. .VL .LI "Event Type (Event Number, Event Classes)" \*LACCT_Add (0x10D, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS char *login_name sec_rgy_acct_key_t key_parts .iE .LE .LE .PP .iX "functions" "\*Lrs_acct_delete(\|)\*O" .iX "\*Lrs_acct_delete(\|)\*O function" The \*Lrs_acct_delete(\|)\*O operation deletes an account with a specified login name. The caller needs to have \*Lm\*O, \*La\*O, and \*Lu\*O (\*Lmgmt_info\*O, \*Lauth_info\*O, and \*Luser_info\*O) permissions on the principal of the account that is to be deleted. .VL .LI "Event Type (Event Number, Event Classes)" \*LACCT_Delete (0x10E, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS char *login_name .iE .LE .LE .PP .iX "functions" "\*Lrs_acct_add(\|)\*O" .iX "\*Lrs_acct_add(\|)\*O function" The \*Lrs_acct_rename(\|)\*O operation changes the account login name. The caller has to have the \*Lm\*O (\*Lmgmt_info\*O) permission on the account's principal to be renamed (\*Lold_login_name.pname\*O). .VL .LI "Event Type (Event Number, Event Classes)" \*LACCT_Rename (0x10F, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS char *old_login_name char *new_login_name .iE .LE .LE .PP .iX "functions" "\*Lrs_acct_lookup(\|)\*O" .iX "\*Lrs_acct_lookup(\|)\*O function" The \*Lrs_acct_lookup(\|)\*O operation returns data for a specified account. The caller must have the \*Lr\*O (\*Lread\*O) permission according to the ACL of the account's principal in order to be viewed. .VL .LI "Event Type (Event Number, Event Classes)" \*LACCT_Lookup (0x110, dce_sec_control, dce_sec_query)\*O .VL .LI "Event-Specific Information" .iS char *login_name .iE .LE .LE .PP .iX "functions" "\*Lrs_acct_replace(\|)\*O" .iX "\*Lrs_acct_replace(\|)\*O function" The \*Lrs_acct_replace(\|)\*O operation replaces both the user and administrative information in the account record specified by the input login name. The administrative information contains limitations on the account's use and privileges. The user information contains such information as the account home directory and default shell. The administrative information can only be modified by a caller with the \*La\*O (\*Lauth_info\*O) privilege for the account's principal. The user information can be modified by a caller with the \*Lu\*O (\*Luser_info\*O) privileges for the account's principal. .VL .LI "Event Type (Event Number, Event Classes)" \*LACCT_Replace (0x111, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS char *login_name unsigned32 key_parts .iE .LE .LE .PP .iX "functions" "\*Lrs_acct_get_projlist(\|)\*O" .iX "\*Lrs_acct_get_projlist(\|)\*O function" The \*Lrs_acct_get_projlist(\|)\*O operation returns members of the project list for the specified account. This operation requires the caller to have the \*Lr\*O (\*Lread\*O) permission on the account principal for which the project list data is to be returned. .VL .LI "Event Type (Event Number, Event Classes)" \*LACCT_GetProjlist (0x112, dce_sec_control, dce_sec_query)\*O .VL .LI "Event-Specific Information" .iS char login_name .iE .LE .LE .LE .SS "Registry Miscellaneous Operation Interface (rs_misc) Operations .iX "Registry miscellaneous operations" interfaces" .iX "Registry miscellaneous operations" "\*Lrs_misc\*O" .iX "\*Lrs_misc\*O operations" .PP .iX "functions" "\*Lrs_login_get_info(\|)\*O" .iX "\*Lrs_login_get_info(\|)\*O function" The \*Lrs_login_get_info(\|)\*O operation returns login information for the specified account. This information is extracted from the account's entry in the registry database. This operation requires the caller to have the \*Lr\*O (\*Lread\*O) permission on the account's principal from which the data is to be returned. .VL .LI "Event Type (Event Number, Event Classes)" \*LLOGIN_GetInfo (0x113, dce_sec_control, dce_sec_query)\*O .VL .LI "Event-Specific Information" .iS char *login_name .iE .LE .LE .SS "Registry PGO Interface (rs_pgo) Operations" .iX "Registry PGO" interfaces" .iX "Registry PGO" "\*Lrs_pgo\*O" .iX "\*Lrs_pgo\*O operations" .PP .iX "functions" "\*Lrs_pgo_add(\|)\*O" .iX "\*Lrs_pgo_add(\|)\*O function" The \*Lrs_pgo_add(\|)\*O operation adds a PGO item to the registry database. This operation requires the caller to have the \*Li\*O (\*Linsert\*O) permission on the parent directory in which the PGO item is to be created. .VL .LI "Event Type (Event Number, Event Classes)" \*LPGO_Add (0x114, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS sec_rgy_domain_t name_domain char *pgo_name .iE .LE .LE .PP .iX "functions" "\*Lrs_pgo_delete(\|)\*O" .iX "\*Lrs_pgo_delete(\|)\*O function" The \*Lrs_pgo_delete(\|)\*O operation deletes a PGO item from registry database. Any account depending on the deleted PGO item is also deleted. The deletion operation requires the caller to have the \*Ld\*O (delete) permission on the parent directory that contains the PGO item to be deleted and the \*LD\*O (\*LDelete_object\*O) permission on the PGO item itself. .VL .LI "Event Type (Event Number, Event Classes)" \*LPGO_Delete (0x115, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS sec_rgy_domain_t name_domain char *pgo_name .iE .LE .LE .PP .iX "functions" "\*Lrs_pgo_replace(\|)\*O" .iX "\*Lrs_pgo_replace(\|)\*O function" The \*Lrs_pgo_replace(\|)\*O operation replaces the data associated with a PGO item in the registry database. The caller needs to have the \*Lm\*O (\*Lmgmt_info\*O) permission on the PGO item, if \*Lquota\*O, \*Lflags\*O, or \*Lunix_num\*O is being set. (Only a cell principal's \*Lunix_num\*O is modifiable.) The caller needs to have the \*Lf\*O (fullname) permission to modify the fullname of the PGO item. .VL .LI "Event Type (Event Number, Event Classes)" \*LPGO_Replace (0x116, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS sec_rgy_domain_t name_domain char *pgo_name .iE .LE .LE .PP .iX "functions" "\*Lrs_pgo_rename(\|)\*O" .iX "\*Lrs_pgo_rename(\|)\*O function" The \*Lrs_pgo_rename(\|)\*O operation renames a PGO item in the registry database. The caller needs to have the \*Ln\*O (\*Lname\*O) permission on the old name of the PGO item, if performing a rename within a directory. In order to move a PGO item between directories, the caller needs to have the \*Ln\*O (\*Lname\*O) permission on the old name of the PGO item as well as the \*Ld\*O (\*Ldelete\*O) permission on the old parent directory and the \*Li\*O (\*Linsert\*O) permission on the new parent directory in which the PGO item is being added under the new name. .VL .LI "Event Type (Event Classes)" \*LPGO_Rename (0x117, dce_sec_control, dce_sec_modify)\*O .VL "Event-Specific Information" .iS sec_rgy_domain_t name_domain char *old_name char *new_name .iE .LE .LE .PP .iX "functions" "\*Lrs_pgo_get(\|)\*O" .iX "\*Lrs_pgo_get(\|)\*O function" The \*Lrs_pgo_get(\|)\*O operation returns the name and data for a PGO item. The desired item is identified by a query key, which can be a \*Lname\*O, a \*Luuid\*O, a \*Lunix_num\*O, or a \*Lsequential-search\*O flag. The caller needs to have the \*Lr\*O (\*Lread\*O) permission on the PGO item to be viewed. .VL .LI "Event Type (Event Number, Event Classes)" \*LPGO_Get (0x118, dce_sec_control, dce_sec_query)\*O .VL .LI "Event-Specific Information" .iS sec_rgy_domain_t name_domain rs_pgo_query_key_t key /* The query key and one of the following */ /* depending on the query key specified: */ case (key == rs_pgo_query_name) char *name /* Name of the item being searched */ case (key == rs_pgo_query_id) uuid_t id_key /* uuid of the item being searched */ case (key == rs_pgo_query_unix_num) unsigned32 unix_num /* unix_num of item being searched */ case (key == rs_pgo_query_next) char *scope /* Scope of item being searched */ .iE .LE .LE .PP .iX "functions" "\*Lrs_pgo_key_transfer(\|)\*O" .iX "\*Lrs_pgo_key_transfer(\|)\*O function" The \*Lrs_pgo_key_transfer(\|)\*O operation performs a specified key transfer between the \*Luuid\*O, \*Lunix_num\*O, and \*Lname\*O of a PGO item. The caller needs to have some permission on the PGO item for \%\*Lid->name\*O and \%\*Lunix_num->name\*O transfers. .VL .LI "Event Type (Event Number, Event Classes)" \*LPGO_KeyTransfer (0x119, dce_sec_control)\*O .VL .LI "Event-Specific Information" .iS sec_rgy_domain_t name_domain rs_pgo_query_key_t key /* The query key */ /* One of the following, depending on the query /* key specified: */ case (key == rs_pgo_query_name) char *name /* Name of the item being searched */ case (key == rs_pgo_query_id) uuid_t id_key /* uuid of the item being searched */ case (key == rs_pgo_query_unix_num) unsigned32 unix_num /* unix_num of item being searched */ unsigned32 requested_result_type .iE .LE .LE .PP .iX "functions" "\*Lrs_pgo_add_member(\|)\*O" .iX "\*Lrs_pgo_add_member(\|)\*O function" The \*Lrs_pgo_add_member(\|)\*O operation adds a member to a group or an organization. The caller must have the \*LM\*O (\*LMember_list\*O) permission on the group or organization. Additionally, if this call is for adding a group member, the caller must have the \*Lg\*O (\*Lgroups\*O) permission on the principal to be added. .VL .LI "Event Type (Event Number, Event Classes)" \*LPGO_AddMember (0x11A, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS sec_rgy_domain_t name_domain char *person_name /* Principal's name */ char *go_name /* Group or organization's name */ .iE .LE .LE .PP .iX "functions" "\*Lrs_pgo_delete_member(\|)\*O" .iX "\*Lrs_pgo_delete_member(\|)\*O function" The \*Lrs_pgo_delete_member(\|)\*O operation deletes a principal from a group or an organization in the registry database. The caller must have the \*LM\*O (\*LMember_list\*O) permission on the group or organization. Note that the caller does not need to have the \*Lg\*O (\*Lgroups\*O) permission when deleting the principal from a group. .VL .LI "Event Type (Event Number, Event Classes)" \*LPGO_DeleteMember (0x11B, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS sec_rgy_domain_t name_domain char *person_name /* Principal's name */ char *go_name /* Group or organization's name */ .iE .LE .LE .PP .iX "functions" "\*Lrs_pgo_is_member(\|)\*O" .iX "\*Lrs_pgo_is_member(\|)\*O function" The \*Lrs_pgo_is_member(\|)\*O operation tests whether a specified principal is a member of a specified group or organization. The caller must have \*Lt\*O (\*Ltest\*O) permission on the group or organization. .VL .LI "Event Type (Event Number, Event Classes)" \*LPGO_IsMember (0x11C, dce_sec_control, dce_sec_query)\*O .VL .LI "Event-Specific Information" .iS sec_rgy_domain_t name_domain char *person_name /* Principal's name */ char *go_name /* Group or organization's name */ .iE .LE .LE .PP .iX "functions" "\*Lrs_pgo_get_members(\|)\*O" .iX "\*Lrs_pgo_get_members(\|)\*O function" The \*Lrs_pgo_get_members(\|)\*O operation, if the specified domain is group or organization, lists the members of a specified group or organization. If the domain is principal, list the groups in which the principal is a member. The caller must have the \*Lr\*O (\*Lread\*O) permission on the principal, group, or organization. .VL .LI "Event Type (Event Number, Event Classes)" \*LPGO_GetMembers (0x11D, dce_sec_control, dce_sec_query)\*O .VL .LI "Event-Specific Information" .iS sec_rgy_domain_t name_domain char *go_name /* PGO's uuid */ .iE .LE .LE .SS "Registry Policy Interface (rs_policy) Operations" .iX "Registry Policy" interfaces" .iX "Registry Policy" "\*Lrs_policy\*O" .iX "\*Lrs_policy\*O operations" .PP .iX "functions" "\*Lrs_properties_get_info(\|)\*O" .iX "\*Lrs_properties_get_info(\|)\*O function" The \*Lrs_properties_get_info(\|)\*O operation returns a list of registry properties. The caller must have the \*Lr\*O (\*Lread\*O) permission on the policy object from which the property information is to be returned. .VL .LI "Event Type (Event Number, Event Classes)" \*LPROP_GetInfo (0x11E, dce_sec_control, dce_sec_query)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP .iX "functions" "\*Lrs_properties_set_info(\|)\*O" .iX "\*Lrs_properties_set_info(\|)\*O function" The \*Lrs_properties_set_info(\|)\*O operation sets the registry properties. The caller must have the \*Lm\*O (\*Lmgmt_info\*O) permission on the policy object for which the property information is to be set. .VL .LI "Event Type (Event Number, Event Classes)" \*LPROP_SetInfo (0x11F, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP .iX "functions" "\*Lrs_policy_get_info(\|)\*O" .iX "\*Lrs_policy_get_info(\|)\*O function" The \*Lrs_policy_get_info(\|)\*O operation returns the policy for a specified organization or the registry (if no organization name is specified). The caller must have the \*Lr\*O (\*Lread\*O) permission on the policy object or organization item from which the data is to be returned. Note that the \*Lrs_policy_get_effective(\|)\*O operation uses the same audit event (\*LPOLICY_GetInfo\*O) as the \*Lrs_policy_get_info(\|)\*O operation. .VL .LI "Event Type (Event Number, Event Classes)" \*LPOLICY_GetInfo (0x120, dce_sec_control, dce_sec_query)\*O .VL .LI "Event-Specific Information" .iS char *organization .iE .LE .LE .PP .iX "functions" "\*Lrs_policy_set_info(\|)\*O" .iX "\*Lrs_policy_set_info(\|)\*O function" The \*Lrs_policy_set_info(\|)\*O operation sets the policy for a specified organization or the registry (if no organization name is specified). The caller must have the \*Lm\*O (\*Lmgmt_info\*O) permission on the policy object or organization item for which the data is to be set. .VL .LI "Event Type (Event Number, Event Classes)" \*LPOLICY_SetInfo (0x121, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS char *organization .iE .LE .LE .PP .iX "functions" "\*Lrs_auth_policy_get_info(\|)\*O" .iX "\*Lrs_auth_policy_get_info(\|)\*O function" The \*Lrs_auth_policy_get_info(\|)\*O operation returns the authentication policy for a specified account or the registry (if no account is specified). The caller must have the \*Lr\*O (\*Lread\*O) permission on the policy object or account's principal from which the data is to be returned. .VL .LI "Event Type (Event Number, Event Classes)" \*LAUTHPOLICY_GetInfo (0x122, dce_sec_control, dce_sec_query)\*O .VL .LI "Event-Specific Information" .iS char *account .iE .LE .LE .PP .iX "functions" "\*Lrs_auth_policy_get_effective(\|)\*O" .iX "\*Lrs_auth_policy_get_effective(\|)\*O function" The \*Lrs_auth_policy_get_effective(\|)\*O operation returns the effective authentication policy for an account. If no account is specified, the authentication policy for the registry is returned. The caller must have the \*Lr\*O (\*Lread\*O) permission on the policy object of the registry. If an account is specified, the caller must also have \*Lr\*O (\*Lread\*O) permission on the account's principal. .VL .LI "Event Type (Event Number, Event Classes)" No new event is defined for this operation. \*LAUTHPOLICY_GetInfo\*O is used here. .LE .PP .iX "functions" "\*Lrs_auth_policy_set_info(\|)\*O" .iX "\*Lrs_auth_policy_set_info(\|)\*O function" The \*Lrs_auth_policy_set_info(\|)\*O operation sets the authentication policy for an account or the registry (if no account is specified). The caller must have the \*La\*O (\*Lauth_info\*O) permission on the account's principal or policy object of the registry. .VL .LI "Event Type (Event Number, Event Classes)" \*LAUTHPOLICY_SetInfo (0x123, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS char *account .iE .LE .LE .SS "Registry Administration Interface Operations" .PP .iX "Registry Administration" interfaces" .iX "Registry Administration" The \*Lrs_rep_admin_stop(\|)\*O operation directs the registry server to stop servicing remote procedure calls. The caller must have \*LA\*O (\*LAdmin\*O) permission on the registry policy object. .VL .LI "Event Type (Event Number, Event Classes)" \*LREPADMIN_Stop (0x124, dce_sec_control, dce_sec_server)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP .iX "functions" "\*Lrs_rep_admin_maint(\|)\*O" .iX "\*Lrs_rep_admin_maint(\|)\*O function" The \*Lrs_rep_admin_maint(\|)\*O operation directs the registry server into (checkpoint the database, close files, and so on) or out of maintenance state. The caller must have \*LA\*O (\*LAdmin\*O) permission on the registry policy object. .VL .LI "Event Type (Event Number, Event Classes)" \*LREPADMIN_Maint (0x125, dce_sec_control, dce_sec_server)\*O .VL .LI "Event-Specific Information" .iS boolean in_maintenance .iE .LE .LE .PP .iX "functions" "\*Lrs_rep_admin_mkey(\|)\*O" .iX "\*Lrs_rep_admin_mkey(\|)\*O function" The \*Lrs_rep_admin_mkey(\|)\*O operation directs the registry to change its master key and re-encrypt account keys using the new master key. The caller must have \*LA\*O (\*LAdmin\*O) permission on the registry policy object. .VL .LI "Event Type (Event Number, Event Classes)" \*LREPADMIN_Mkey (0x126, dce_sec_control, dce_sec_server)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP The \*Lrs_rep_admin_destroy(\|)\*O operation directs the registry server replica to destroy its database and exit. The caller must have \*LA\*O (\*LAdmin\*O) permission on the registry policy object. .VL .LI "Event Type (Event Classes)" \*LREPADMIN_Destroy (0x127, dce_sec_control, dce_sec_server)\*O .VL .LI "Event-Specific Information" None .LE .LE .PP The \*Lrs_rep_admin_init_replica(\|)\*O operation directs the registry server to (re-)initialize the slave identified by \*Vrep_id\*O. This is a master server only operation. The caller must have \*LA\*O (\*LAdmin\*O) permission on the registry policy object. .VL .LI "Event Type (Event Classes)" \*LREPADMIN_Init (0x128, dce_sec_control, dce_sec_server)\*O .VL .LI "Event-Specific Information" .iS char *rep_id_str .iE .LE .LE .PP The \*Lrs_rep_admin_set_sw_rev(\|)\*O operation directs the master registry server to update the current security software version and begin supporting the security features appropriate for that version. If the master is successful, the version update is propagated to all replicas and any replicas that cannot support the new software version will shut down. This is a master-only operation. The caller must have \*LA\*O (\*LAdmin\*O) permission on the registry policy object. .VL .LI "Event Type (Event Number, Event Classes)" \*LREPADMIN_SetSwRev (0x13A, dce_sec_control, dce_sec_server)\*O .LI "Event-Specific Information" .iS unsigned long software_version .iE .LE .LE .PP ...\" .SS "Identifier Mapping Interface (secidmap) Operations" ...\" .iX "identifier Mapping" interfaces" ...\" .iX "Identifier Mapping" "\*Lsecidmap\*O" ...\" .iX "\*Lsecidmap\*O operations" ...\" .PP ...\" .iX "functions" "\*Lrsec_id_parse_name(\|)\*O" ...\" .iX "\*Lrsec_id_parse_name(\|)\*O function" ...\" The \*Lrsec_id_parse_name(\|)\*O operation ...\" translates a global name into principal and cell names and UUIDs. ...\" If the principal's UUID is requested, the caller must have at ...\" least one permission of any kind on the principal item. ...\" .VL ...\" .LI "Event Type (Event Number, Event Classes)" ...\" \*LSECID_ParseName (0x129, dce_sec_control)\*O ...\" .VL ...\" .LI "Event-Specific Information" ...\" .iS ...\" char global_namep ...\" .iE ...\" .LE ...\" .LE ...\" .PP ...\" .iX "functions" "\*Lrsec_id_gen_name(\|)\*O" ...\" .iX "\*Lrsec_id_gen_name(\|)\*O function" ...\" The \*Lrsec_id_gen_name(\|)\*O operation ...\" generates a global name from cell and principal UUIDs. The ...\" caller must have at least one permission of any kind on the ...\" specified principal. ...\" .VL ...\" .LI "Event Type (Event Number, Event Classes)" ...\" \*LSECID_GenName (0x12A, dce_sec_control)\*O ...\" .LI "Event-Specific Information" ...\" .VL ...\" .LI "Event-Specific Information" ...\" .iS ...\" char global_namep ...\" .iE ...\" .LE ...\" .LE .SS "Registry Server Attributes Manipulation Interface (rs_attr) Operations" .iX "Extended Registry Attributes (ERA" .iX "Delegation" .iX "Registry Server Attributes" The \*Lrs_attr_update(\|)\*O operation updates (writes/creates) an attribute. The caller must have, for each attribute defined in \*Lattr_keys\*O, the \*Lquery_permset\*O permission on the registry object specified. .VL .LI "Event Type (Event Classes)" \*LERA_Update (0x12B, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS char * component_name unsigned32 int num_to_write uuid in_attrs[num_to_write].attr_id .iE .LE .LE .PP The \*Lrs_attr_delete(\|)\*O operation deletes a specified attribute(s). The caller must have \*Ldelete_permset\*O permission for each attribute specified. .VL .LI "Event Type (Event Classes)" \*LERA_Delete (0x12C, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS char * component_name unsigned32 num_to_delete uuid attrs[num_to_delete].attr_id .iE .LE .LE .PP The \*Lrs_attr_lookup_by_id(\|)\*O operation performs a lookup of the attributes by attribute type ID. If the number of query attribute keys is 0, this operation will return all attributes that the caller is authorized to use. The caller must have, for each attribute specified, the \*Lquery_permset\*O permission on the registry object specified. .VL .LI "Event Type (Event Classes)" \*LERA_LookupById (0x12E, dce_sec_control)\*O .VL .LI "Event-Specific Information" .iS char * component_name unsigned32 int num_attr_keys uuid attr_keys[num_attr_keys].attr_id .iE .LE .LE .PP The \*Lrs_attr_lookup_no_expand(\|)\*O operation performs a lookup of the attributes by attribute type ID without expanding attribute sets to their constituent member attributes. If the number of query attribute keys is 0, this operation will return all attributes that the caller is authorized to use. The caller must have, for each attribute specified, the \*Lquery_permset\*O permission on the registry object specified. .VL .LI "Event Type (Event Classes)" \*LERA_LookupNoExpand (0x12F, dce_sec_control)\*O .VL .LI "Event-Specific Information" .iS char * component_name unsigned32 int num_attr_keys uuid attr_keys[num_attr_keys].attr_id .iE .LE .LE .PP The \*Lrs_attr_lookup_by_name(\|)\*O operation performs a lookup of an attribute by name. The caller must have, for the attribute specified, \*Lquery_permset\*O permission on the registry object specified. .VL .LI "Event Type (Event Classes)" \*LERA_LookupByName (0x12G, dce_sec_control)\*O .VL .LI "Event-Specific Information" .iS char * component_name char * attr_name .iE .LE .LE .PP .SS "Registry Server Attributes Schema Manipulation Interface (rs_attr_schema) Operations" .PP The \*Lrs_attr_schema_create_entry(\|)\*O operation creates a new schema entry. The caller must be authorized to add entries to the specified schema. .VL .LI "Event Type (Event Classes)" \*LERA_SchemaCreate (0x131, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS char * schema_name char * schema_entry->attr_name uuid schema_entry->attr_id .iE .LE .LE .PP The \*Lrs_attr_schema_delete_entry(\|)\*O operation deletes a schema entry. The caller must be authorized to delete schema entries. .VL .LI "Event Type (Event Classes)" \*LERA_SchemaDelete (0x132, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS char *schema_name uuid attr_id .iE .LE .LE .PP The \*Lrs_attr_schema_update_entry(\|)\*O operation updates the modifiable fields of a schema entry. The caller needs to have \*Lm (mgmt_info)\*O permissions on the schema entry that is to be modified. .VL .LI "Event Type (Event Classes)" \*LERA_SchemaUpdate (0x133, dce_sec_control, dce_sec_modify)\*O .VL .LI "Event-Specific Information" .iS char * schema_name uuid schema_entry->attr_id .iE .LE .LE .PP The \*Lrs_attr_schema_lookup_by_id(\|)\*O operation retrieves the schema entry identified by the attribute type \*Luuid\*O. The caller must have \*Lr (read)\*O permissions on the schema entry specified. .VL .LI "Event Type (Event Classes)" \*LERA_SchemaLookupId (0x134, dce_sec_control)\*O .VL .LI "Event-Specific Information" .iS char * schema_name uuid attr_id .iE .LE .LE .PP The \*Lrs_attr_schema_lookup_by_name(\|)\*O operation retrieves the schema entry identified by the attribute name. The caller must have \*Lr (read)\*O permissions on the schema entry specified. .VL .LI "Event Type (Event Classes)" \*LERA_SchemaLookupName (0x135, dce_sec_control)\*O .VL .LI "Event-Specific Information" .iS char * schema_name char * attr_name .iE .LE .LE .PP .SS "Version 1.1 Privilege Server Manager Interface (rpriv_v1_1) Operations" .PP The \*Lrpriv_get_eptgt(\|)\*O operation constructs and returns an extended privilege certificate to the ticket_granting service. The caller supplies the extended privilege attributes in the form of an encoded Extended Privilege Attribute Certificate (EPAC). The procedure by which the requested privilege attributes are verified depends on how the call is authenticated and whether the request is "local" (that is, is a request from a client in this Privilege Server's cell) or is "intercell" (that is, is from a foreign privilege service). .PP If the request is local, then the ticket to the Privilege Server is based on a Kerberos V5 TGT and the \*Lrequested_privs\*O consists of a single encoded EPAC. The Privilege Server decodes the \*Lrequested_privs\*O and verifies that the requested privileges are valid by performing the necessary database queries. .PP If the request is foreign, then the ticket to the privilege service is based on a DCE EPTGT and the Privilege Server retrieves the EPAC seal from the DCE authorization data contained in the ticket, and uses it to verify that the requested privileges are valid. .VL .LI "Event Type (Event Classes)" \*LPRIV_GetEptgt (0x136, dce_sec_control, dce_sec_authent)\*O .VL .LI "Event-Specific Information" .iS char * request_location /* "LOCAL" or "INTERCELL" */ if "LOCAL" request: uuid req_princ_id->uuid; /* requested local principal uuid */ uuid req_group_id->uuid; /* requested local primary group uuid */ unsigned short int num_groups /* number of valid local groups */ uuid = groups[num_groups].uuid /* valid local groups' uuids */ if "INTERCELL" request: unsigned short int num_epacs /* number of epacs in delegation chain */ uuid [num_epacs].pa.realm.uuid /* privilege attribute realm uuid */ uuid [num_epacs].pa.principal.uuid /* privilege attribute principal uuid */ uuid [num_epacs].pa.num_groups /* number of groups in privilege attribute */ uuid [num_epacs].pa.groups[([epac_set.num_epacs].pa.num_groups)].uuid /* uuids for groups in privilege attribute */ .iE .LE .LE .PP The \*Lrpriv_become_delegate(\|)\*O operation permits an intermediate server to become a delegate for its caller. The caller supplies extended privilege attributes in the form of an encoded Extended Privilege Attribute Certificate (EPAC). The Privilege Server verifies that the delegation token for this EPAC chain is correct and then creates a new chain from the existing one with the intermediary's EPAC as a new delegate. .VL .LI "Event Type (Event Classes)" \*LPRIV_BecomeDelegate (0x138, dce_sec_control, dce_sec_authent)\*O .VL .LI "Event-Specific Information" .iS uuid req_princ_id->uuid; /* requested local principal uuid */ uuid req_group_id->uuid; /* requested local primary group uuid */ unsigned short int num_groups /* number of valid local groups */ uuid = groups[num_groups].uuid /* valid local groups' uuids */ unsigned short int num_epacs /* number of epacs in delegation chain */ uuid [num_epacs].pa.realm.uuid /* privilege attribute realm uuid */ uuid [num_epacs].pa.principal.uuid /* privilege attribute principal uuid */ uuid [num_epacs].pa.num_groups /* number of groups in privilege attribute */ uuid [num_epacs].pa.groups[([epac_set.num_epacs].pa.num_groups)].uuid /* uuids for groups in privilege attribute */ .iE .LE .LE .PP The \*Lrpriv_become_impersonator(\|)\*O operation permits an intermediate server to become an impersonator for its caller. The caller supplies extended privilege attributes in the form of an encoded Extended Privilege Attribute Certificate (EPAC). The Privilege Server verifies that the delegation token for the initator's EPAC is correct and also that the intermediary is allowed to impersonate the initiator. .VL .LI "Event Type (Event Classes)" \*LPRIV_BecomeImpersonator (0x139, dce_sec_control, dce_sec_authent)\*O .VL .LI "Event-Specific Information" .iS uuid req_princ_id->uuid; /* requested local principal uuid */ uuid req_group_id->uuid; /* requested local primary group uuid */ unsigned short int num_groups /* number of valid local groups */ uuid = groups[num_groups].uuid /* valid local groups' uuids */ unsigned short int num_epacs /* number of epacs in delegation chain */ uuid [num_epacs].pa.realm.uuid /* privilege attribute realm uuid */ uuid [num_epacs].pa.principal.uuid /* privilege attribute principal uuid */ uuid [num_epacs].pa.num_groups /* number of groups in privilege attribute */ uuid [num_epacs].pa.groups[([epac_set.num_epacs].pa.num_groups)].uuid /* uuids for groups in privilege attribute */ .iE .LE .LE .PP .SH RELATED INFORMATION Commands: \*Ldcecp(1m)\*O. .sp .4v Files: \*Ldts_audit_events(5)\*O, \*Levent_class.5\*O. .zZ "enh,10234,R1.1,new manpage." ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1992, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\"Copyright Hewlett-Packard Company 1992 ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" .rm zA .rm zZ .TH sec_intro 5 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .SH NAME .PP \*Lsec_intro\*O - Introduction to the DCE Security administrative files .SH "DESCRIPTION" .PP .iX "DCE Audit" "files" .iX "DCE Audit" "auditable events" .iX "files" "security administration" .iX "security administration" "files" .iX "security administration" "introduction" .iX "security administration" "auditable events" This section describes DCE Security files for system administration and provides related information. The reference pages cover: .iX "files" "\*Laud_audit_events\*O" .iX "files" "\*Lpasswd_override\*O" .iX "files" "\*Lv5srvtab\*O" .iX "files" "\*Ldts_audit_events\*O" .iX "files" "\*Levent_class\*O" .iX "files" "\*Lsec_audit_events\*O" .iX "files" "\*Lgroup_override\*O" .zA "defect,12224,r1.1,Make single sec5 intro page" .VL .LI "\*Laud_audit_events\*O" This file defines the auditable events for the Audit service. .LI "\*Ldts_audit_events\*O" This file defines the auditable events for the time services This page describes the auditable events for the time services. .LI "\*Levent_class\*O" This file contains the declaration of a single event class, a logical group of auditable events. .LI "\*Lgroup_override\*O" This file contains override entries that let you override group UNIX IDs and member lists in the registry database for a local machine. .LI "\*Lpasswd_override\*O" This file contains override entries that let you override password, GECOS, home directory, and shell entries in the registry database for a local machine. .LI "\*Lsec_audit_events\*O" This file defines the auditable events for the security services. .zZ "defect,12224,r1.1,Make single sec5 intro page" .LI "\*Lv5srvtab\*O " This file contains server machine passwords on the local machine. .LE .PP See the file's reference page for further information on each file. .\" $Header: signal.5,v 76.1 95/07/07 14:55:28 ssa Exp $ .TA s .TH signal 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME signal.h \- signals .SH SYNOPSIS .C "#include " .PP .SH DESCRIPTION The .CR header defines the following symbolic constants, each of which expands to a distinct constant expression of the type: .IP .C "void (*)(int)" .PP whose value matches no declarable function. .RS .TP 15 .C SIG_DFL Request for default signal handling. .TP .C SIG_ERR Return value from .CR signal() in case of error. .TP .C SIG_HOLD Request that signal be held. .TP .C SIG_IGN Request that signal be ignored. .RE .PP The following data types are defined through .CR typedef : .RS .TP 15 .I sig_atomic_t Integral type of an object that can be accessed as an atomic entity, even in the presence of asynchronous interrupts .TP .I sigset_t Integral or structure type of an object used to represent sets of signals. .\" EX .TP .I pid_t As described in .CR . .RE .PP This header also declares the constants that are used to refer to the signals that occur in the system. Signals defined here begin with the letters .CR SIG . Each of the signals have distinct positive integral values. The value 0 is reserved for use as the null signal (see .IR kill() ). Additional implementation\-dependent signals may occurin the system. .PP The following signals are supported on all implementations (default actions are explained below the table): .PP .TS tab(#); lb#lf4#l. #Default# Signal#Action#\f4Description\f1 SIGABRT#ii#Process abort signal. SIGALRM#i#Alarm clock. SIGFPE#ii#Erroneous arithmetic operation. SIGHUP#i#Hangup. SIGILL#ii#Illegal instruction. SIGINT#i#Terminal interrupt signal. SIGKILL#i#Kill (cannot be caught or ignored). SIGPIPE#i#Write on a pipe with no one to read it. SIGQUIT#ii#Terminal quit signal. SIGSEGV#ii#Invalid memory reference. SIGTERM#i#Termination signal. SIGUSR1#i#User-defined signal 1. SIGUSR2#i#User-defined signal 2. .\" ! SIGCHLD#iii#Child process terminated or stopped. SIGCONT#v#Continue executing, if stopped. SIGSTOP#iv#Stop executing (cannot be caught or ignored). SIGTSTP#iv#Terminal stop signal. SIGTTIN#iv#Background process attempting read. SIGTTOU#iv#Background process attempting write. .\" ! SIGBUS#ii#Bus error. SIGPOLL#i#Pollable event. SIGPROF#i#Profiling timer expired. SIGSYS#ii#Bad system call. SIGTRAP#ii#Trace/breakpoint trap. SIGURG#i#High bandwidth data is available at a socket. SIGVTALRM#i#Virtual timer expired. SIGXCPU#ii#CPU time limit exceeded. SIGXFSZ#ii#File size limit exceeded. .\" ? .TE .PP The default actions are as follows: .PP .RS .TP 10 .CR i Abnormal termination of the process. The process is terminated with all the consequences of .CR _exit() except that the status is made available to .CR wait() and .CR waitpid() indicates abnormal termination by the specified signal. .TP .CR ii Abnormal termination of the process. Additionally, implementation\-dependent abnormal termination actions, such as creation of a core file, may occur. .\" ? .TP .CR iii Ignore the signal. .TP .CR iv Stop the process. .TP .CR v Continue the process, if it is stopped; otherwise ignore the signal. .RE .PP The header provides a declaration of struct .CR sigaction, including at least the following members: .PP .TS tab(#); w(2) w(2i) w(2i) lf4#lf4#l. void#(*sa_handler)(int)#T{ what to do on receipt of signal T} sigset_t#sa_mask#T{ set of signals to be blocked during execution of the signal handling function T} int#sa_flags#special flags void (*)#sa_sigaction#pointer to signal (int, siginfo_t *, void *)##handler function .\" ? .TE .PP The storage occupied by .IR sa_handler and .IR sa_sigaction may overlap, and a portable program must not use both simultaneously. .\" ? .PP The following are declared as constants: .PP .RS .TP 25 .C SA_NOCLDSTOP Do not generate .CR SIGCHLD when children stop. .TP .C SIG_BLOCK The resulting set is the union of the current set and the signal set pointed to by the argument .IR set . .TP .C SIG_UNBLOCK The resulting set is the intersection of the current set and the complement of the signal set pointed to by the argument .IR set . .TP .C SIG_SETMASK The resulting set is the signal set pointed to by the argument .IR set . .C SA_ONSTACK Causes signal delivery to occur on an alternate stack. .TP .C SA_RESETHAND Causes signal dispositions to be set to .CR SIG_DFL on entry to signal handlers. .TP .C SA_RESTART Causes certain functions to become restartable. .TP .C SA_SIGINFO Causes extra information to be passed to signal handlers at the time of receipt of a signal. .TP .C SA_NOCLDWAIT Causes implementations not to create zombie processes on child death. .TP .C SA_NODEFER Causes signal not to be automatically blocked on entry to signal handler. .TP .C SS_ONSTACK Process is executing on an alternate signal stack. .TP .C SS_DISABLE Alternate signal stack is disabled. .TP .C MINSIGSTKSZ Minimum stack size for a signal handler. .TP .C SIGSTKSZ Default size in bytes for the alternate signal stack. .RE .PP The .CR ucontext_t structure is defined through .CR typedef as described in .CR . .PP The .CR header defines the .CR stack_t type as a structure that includes at least the following members: .PP .TS tab(#); lf4#lf4#l. void#*ss_sp#stack base or pointer size_t#ss_size#stack size int#ss_flags#flags .TE .PP The .CR header defines the .CR sigstack structure that includes at least the following members: .PP .TS tab (#); lf4#lf4#l. int#ss_onstack#non-zero when signal stack is in use void#*ss_sp#signal stack pointer .TE .PP The .CR header defines the .CR siginfo_t type as a structure that includes at least the following members: .PP .TS tab(#); lf4#lf4#l. int#si_signo#signal number int#si_errno#T{ if non\-zero, an .CR errno value associated with this signal, as defined in .CR T} int#si_code#signal code id_t#si_pid#sending process ID uid_t#si_uid#real user ID of sending process void#*si_addr#address of faulting instruction int#si_status#exit value or signal long#si_band#band event for SIGPOLL .TE .PP The macros specified in the Code column of the following table are defined for use as values of .IR si_code that are signal\-specific reasons why the signal was generated. .PP .TS tab(#); lb#lb#l. Signal#Code#\f4Reason\f1 SIGILL#ILL_ILLOPC#illegal opcode #ILL_ILLOPN#illegal operand #ILL_ILLADR#illegal addressing mode #ILL_ILLTRP#illegal trap #ILL_PRVOPC#privileged opcode #ILL_PRVREG#privileged register #ILL_COPROC#coprocessor error #ILL_BADSTK#internal stack error SIGFPE#FPE_INTDIV#integer divide by zero #FPE_INTOVF#integer overflow #FPE_FLTDIV#floating point divide by zero #FPE_FLTOVF#floating point overflow #FPE_FLTUND#floating point underflow #FPE_FLTRES#floating point inexact result #FPE_FLTINV#invalid floating point operation #FPE_FLTSUB#subscript out of range SIGSEGV#SEGV_MAPERR#address not mapped to object #SEGV_ACCERR#invalid permissions for mapped object SIGBUS#BUS_ADRALN#invalid address alignment #BUS_ADRERR#non-existent physical address #BUS_OBJERR#object specific hardware error SIGTRAP#TRAP_BRKPT#process breakpoint #TRAP_TRACE#process trace trap SIGCHLD#CLD_EXITED#child has exited #CLD_KILLED#child has terminated abnormally and ##did not create a core file #CLD_DUMPED#child has terminated and ##created a core file #CLD_KILLED#child was killed #CLD_DUMPED#child has terminated abnormally #CLD_TRAPPED#traced child has trapped #CLD_STOPPED#child has stopped #CLD_CONTINUED#stopped child has continued SIGPOLL#POLL_IN#data input available #POLL_OUT#output buffers available #POLL_MSG#input message available #POLL_ERR#I/O error #POLL_PRI#high priority input available #POLL_HUP#device disconnected .TE .PP Implementations may support additional .IR si_code values not included in this list, may generate values included in this list under circumstances other than those described in this list, and may contain extensions or limitations that prevent some values from being generated. Implementations will not generate a different value from the ones described in this list for circumstances described in this list. .PP In addition, the following signal\-specific information will be available: .PP .TS tab(#); w(1i) w(1.5i) w(2.5i) lf4#lf4#l. Signal#Member#\f4Value\f1 SIGILL#void * si_addr#address of faulting instruction SIGFP## SIGSEGV#void * si_addr#address of faulting memory reference SIGBUS## SIGCHLD#pid_t si_pid#child process ID #int si_status#exit value or signal #uid_t si_uid#T{ real user ID of the process that sent the signal T} SIGPOL#long si_band#T{ band event for .CR POLL_IN , .CR POLL_OUT , or .CR POLL_MSG T} .TE .PP For some implementations, the value of .IR si_addr may be inaccurate. .\" ? .PP The following are declared as functions and may also be defined as macros: .PP .\" UX .C "void (*bsd_signal(int sig, void (*func)(int)))(int);" .br .C "int kill(pid_t pid, int sig);" .PP .\" UX .C "int killpg(pid_t pgrp, int sig);" .br .C "int raise(int sig);" .br .C "int sigaction(int sig, const struct sigaction" .br .C " *act, struct sigaction *oact);" .br .C "int sigaddset(sigset_t *set, int signo);" .PP .\" UX .C "int sigaltstack(const stack_t *ss, stack_t *oss);" .br .C "int sigdelset(sigset_t *set, int signo);" .br .C "int sigemptyset(sigset_t *set);" .br .C "int sigfillset(sigset_t *set);" .PP .\" UX .C "int sighold(int sig);" .br .C "int sigignore(int sig);" .br .C "int siginterrupt(int sig, int flag);" .br .C "int sigismember(const sigset_t *set, int signo);" .PP .\" UX .C "int sigmask(int signum);" .br .C "void (*signal(int sig, void (*func)(int)))(int);" .PP .\" UX .C "int sigpause(int sig);" .br .C "int sigpending(sigset_t *set);" .br .C "int sigprocmask(int how, const sigset_t *set, sigset_t *oset);" .br .\" UX .C "int sigrelse(int sig);" .br .C "void *sigset(int sig, void (*disp)(int)))(int);" .br .\" note about following item: "to be withdrawn" .C "int sigstack(struct sigstack *ss," .br .C " struct sigstack *oss);" .br .C "int sigsuspend(const sigset_t *sigmask);" .PP .SH SEE ALSO alarm(), bsd_signal(), ioctl(), kill(), killpg(), raise(), sigaction(), sigaddset(), sigaltstack(), sigdelset(), sigemptyset(), sigfillset(), siginterrupt(), sigismember(), signal(), sigpending(), sigprocmask(), sigstack(), sigsuspend(), wait(), waitid(), , , , . .SH CHANGE HISTORY First released in Issue 1. .SH Issue 4 .PP The following changes are incorporated for alignment with the ISO POSIX\-1 standard: .RS .TP 3 \(bu The function declarations in this header are expanded to full ISO C prototypes. .TP 3 \(bu The DESCRIPTION section is changed: .RS .TP 3 \- to define the type .IR sig_atomic_t .TP 3 \- to define the syntax of signal names and functions .TP 3 \- to combine the two tables of constants .TP 3 \- .CR SIGFPE is no longer limited to floating\-point exceptions, but covers all erroneous arithmetic operations. .RE .RE .PP The following change is incorporated for alignment with the ISO C standard: .PP .RS .TP 3 \(bu The .CR raise() function is added to the list offunctions declared in this header. .RE .PP Other changes are incorporated as follows: .PP .RS .TP 3 \(bu A reference to .CR is added for the definition of .IR pid_t . This is marked as an extension. .TP 3 \(bu In the list of signals starting with .CR SIGCHLD , the statement "but a system not supporting the job control option is not obliged to support the functionality of these signals" is removed. This is because job control is defined as mandatory on Issue 4 conforming implementations. .TP 3 \(bu Reference to implementation\-dependent abnormal termination routines, such as creation of a core file, in item ii in the defaults action list is marked as an extension. .RE .PP .SH Issue 4, Version 2 The following changes are incorporated for X\/OPEN UNIX conformance: .PP .RS .TP 3 \(bu The .CR SIGTRAP , .CR SIGBUS , .CR SIGSYS , .CR SIGPOLL , .CR SIGPROF , .CR SIGXCPU , .CR SIGXFSZ , .CR SIGURG , and .CR SIGVTALRM signals are added to the list of signals that will be supported on all conforming implementations. .TP 3 \(bu The .IR sa_sigaction member is added to the .CR sigaction structure, and a note is added that the storage used by .IR sa_handler and .IR sa_sigaction may overlap. .TP 3 \(bu The .CR SA_ONSTACK , .CR SA_RESETHAND , .CR SA_RESTART , .CR SA_SIGINFO , .CR SA_NOCLDWAIT , .CR SS_ONSTACK , .CR SS_DISABLE , .CR MINSIGSTKSZ , and .CR SIGSTKSZ constants are defined. The .CR stack_t , .CR sigstack , and .CR siginfo structures are defined. .TP 3 \(bu Definitions are given for the .CR ucontext_t , .CR stack_t , .CR sigstack , and .CR siginfo_t types. .TP 3 \(bu A table is provided listing macros that are defined as signal\-specific reasons why a signal was generated. Signal\-specific additional information is specified. .TP 3 \(bu The .CR bsd_signal() , .CR killpg() , .CR _longjmp() , .CR _setjmp() , .CR sigaltstack() , .CR sighold() , .CR sigrelse() , .CR sigset() , and .CR sigstack() functions are added to the list of functions declared in this header. .\" $Header: signal.5,v 76.1 95/07/07 14:55:28 ssa Exp $ .TA s .TH signal 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH DESCRIPTION .SM HP-UX supports multiple signal interfaces (see .IR sigaction (2), .IR signal (2), .IR sigvector (2), .IR bsdproc (2), and .IR sigset (2V)) that allow a process to specify the action taken upon receipt of a signal. All supported signal interfaces require specification of a signal, as designated by the .B Name and .B Number shown below. Signal specification can be any of the following except .C SIGKILL or .CR SIGSTOP, which cannot be caught or ignored: .PP .TS center; lb lb lb lb lf4 c lp-1 i lw(3.5i). Name Number Notes Meaning _ SIGILL 04 A,B,C illegal instruction SIGTRAP 05 A,B,C trace trap SIGIOT 06 A,B software generated signal SIGEMT 07 A,B software generated signal SIGFPE 08 A,B floating point exception SIGKILL 09 A,D,E,F kill SIGCLD l8 G death of a child (see \s-1WARNINGS\s0 below) SIGPWR 19 C,G power fail (see \s-1WARNINGS\s0 below) SIGIO 22 G asynchronous I/O signal; see \f2select\fP(2) SIGWINCH 23 G window size change; see \f2termio\fP(7) SIGURG 29 G urgent data arrived on an I/O channel SIGLOST 30 A file lock lost (\s-1NFS\s0 file locking) .TE .PP The letters in the .B Notes column in the table above indicate the action taken when the signal is received, and any special conditions on its use: .RS .TP 8 .I A The default action is to terminate the process. .TP .I B The default action of terminating the process also generates a core image file if possible. .TP .I C The action is not reset to .SM SIG_DFL before calling the signal-catching function. .TP .I D The signal cannot be ignored. .TP .I E The signal cannot be caught. .TP .I F The signal will not be held off from a stopped process. .TP .I G The default action is to ignore the signal. .TP .I H The default action is to stop the process. .RE .PP All signal interfaces allow specification of an .I action that determines what to do upon the receipt of a signal, and should be one of the following: .RS .TP 12 .C SIG_DFL Execute the default action, which varies depending on the signal as described above: .RS .RS .TP 5 .I A Terminate the receiving process with all of the consequences outlined in .IR exit (2). .TP .I B If following conditions are met, generate a core image file (see .IR core (4)) in the current working directory of the receiving process: .RS .RS .TP 3 \(bu The effective user .SM ID and the real user .SM ID of the receiving process are equal. .TP \(bu The effective group .SM ID and the real group .SM ID of the receiving process are equal. .TP \(bu A regular file named .B core does not exist and can be created, or exists and is writable. .RE .RE .IP If the file is created, it has the following properties: .RS .RS .TP 3 \(bu The file mode is 0666, modified by the file creation mode mask (see .IR umask (2)). .TP \(bu The file user .SM ID is equal to the effective user .SM ID of the receiving process. .TP \(bu The file group .SM ID is equal to the effective group .SM ID of the receiving process. .RE .RE .TP 5 .I G Ignore the signal. Do not terminate or stop the receiving process. .TP .I H Stop the receiving process. While a process is stopped, any additional signals sent to the process are suspended until the process is restarted (except those marked with Note .I F above, which are processed immediately). However, when the process is restarted, pending signals are processed. When a process that is in an orphaned process group (see .IR glossary (9)) receives a .CR SIGTSTP , .CR SIGTTIN , or .C SIGTTOU signal, the process is not stopped because a process in an orphaned process group is not allowed to stop. Instead, a .C SIGHUP signal is sent to the process, and the .CR SIGTSTP , .CR SIGTTIN , or .C SIGTTOU is discarded. .RE .RE .TP 12 .C SIG_IGN Ignore the signal. .br When one of the supported signal interface routines is used to set the action of a signal to .C SIG_IGN and an instance of the signal is pending, the pending signal is cleared. .RS .RS .TP 5 .I D Signals marked with Note .I D above cannot be ignored. .RE .RE .RE .TP 12 .I address Catch the signal. .br Upon receipt of the signal, if .C signal() is used to set the action, reset the action for the signal caught to .C SIG_DFL (except signals marked with Note .IR C ). Then, call the signal-catching function to which .IR address points, and resume executing the receiving process at the point where it was interrupted. Signal interface routines other than .C signal() normally do not reset the action for the signal caught. However, .C sigaction() and .C sigvector() provide a way of specifying this behavior (see .IR sigaction(2) or .IR sigvector (2)). .IP The signal-catching function is called with the following three parameters: .RS .RS .TP 8 .I sig The signal number. .TP .I code A word of information usually provided by the hardware. .TP .I scp A pointer to the machine-dependent structure .I sigcontext defined in .RC < signal.h >. .RE .RE .IP Depending on the value of .IR sig , .I code can be zero and/or .I scp can be .SM NULL. The meanings of .I code and .I scp and the conditions determining when they are other than zero or .SM NULL are implementation-dependent (see .SM DEPENDENCIES below). It is possible for .I code to always be zero, and .I scp to always be .SM NULL. .IP The pointer .I scp is valid only during the context of the signal-catching function. .IP Optional parameters can be omitted from the signal-catching function parameter list, in which case the signal-catching function is exactly compatible with .SM UNIX System V. Truly portable software should not use the optional parameters in signal-catching routines. .IP Upon return from the signal-catching function, the receiving process resumes execution at the point where it was interrupted. .IP When a signal is caught during the execution of system calls such as .CR read() , .CR write() , .CR open() , or .C ioctl() on a slow device (such as a terminal, but not a file), during a .C pause() system call or a .C wait() system call that does not return immediately because a previously stopped or zombie process already exists, the signal-catching function is executed and the interrupted system call returns a \(mi1 to the calling process with .C errno set to .SM EINTR. .RS 7 .TP 5 .I C If the signal is marked with Note .I C above, the action is not reset to .C SIG_DFL before calling the signal-catching function. Furthermore, the action is not reset if any signal interface routine other than .C signal() was used to set the action. See the description of signal catching above. .TP .I E If the signal is marked with Note .I E above, the signal cannot be caught. .RE .PP When any stop signal .RC ( SIGSTOP , .CR SIGTSTP , .CR SIGTTIN , .CR SIGTTOU ) is generated for a process, pending .C SIGCONT signals for that process are discarded. Conversely, when .C SIGCONT is generated for a process, all pending stop signals for that process are discarded. When .C SIGCONT is generated for a stopped process, the process is continued, even if the .C SIGCONT signal is blocked or ignored. If .C SIGCONT is blocked and not ignored, the process remains pending until it is either unblocked or a stop signal is generated. .PP .C SIGKILL is sent by the system if an .C exec() system call is unsuccessful and the original program has already been deleted. .SH WARNINGS The signals .C SIGCLD and .C SIGPWR behave differently than those described above. .PP The actions for these signals is modified as follows: .RS .TP 15 .C SIGCLD Setting the action for .C SIGCLD to .C SIG_IGN in a parent process prevents exiting children of the calling process from creating a zombie process. If the parent process executes the .C wait() function, the calling process blocks until all of the child processes of the calling processes terminate. The .C wait() function then returns a value of \(mi1 with .C errno set to .SM ECHILD (see .IR wait (2)). .IP If one of the signal interface routines is used to set the action for .C SIGCLD to be caught (that is, a function address is supplied) in a process that currently has terminated (zombie) children, a .C SIGCLD signal is delivered to the parent process immediately. Thus, if the signal-catching function reinstalls itself, the apparent effect is that any .C SIGCLD signals received due to the death of children while the function is executing are queued and the signal-catching function is continually reentered until the queue is empty. Note that the function must reinstall itself after it calls .CR wait() , .CR wait3() , or .CR waitpid() . Otherwise the presence of the child that caused the original signal causes another signal immediately, resulting in infinite recursion. .IP When processing a pipeline, the Bourne shell (see .IR sh-bourne (1)) makes the last process in the pipeline the parent of the preceding processes. Job control shells including C shell, Korn shell and the .SM POSIX shell (see .IR csh (1), .IR ksh (1), and .IR sh-posix (1)) make the shell itself the parent of all processes in the pipeline. Therefore, a process that can receive data from a pipe should not attempt to catch .C SIGCLD. .TP 15 .C SIGPWR The .C SIGPWR signal is sent to all processes after a power interruption when power is restored and the system has done all necessary reinitialization. Processes restart by catching (or ignoring) .CR SIGPWR . .IP Applications that wish to recover from power failures should catch .C SIGPWR and take whatever necessary steps to reinitialize itself. .IP Some implementations do not generate .CR SIGPWR . Only systems with nonvolatile memory can recover from power failures. .SH DEPENDENCIES .SS Series 700 The signal .C SIGPWR is not currently generated. .SS Series 700/800 The structure pointer .I scp is always defined. .PP The .I code word is always zero for all signals except .C SIGILL and .CR SIGFPE . For .CR SIGILL , .I code has the following values: .RS .TP 7 \08 Illegal instruction trap; .TP \09 Break instruction trap; .TP 10 Privileged operation trap; .TP 11 Privileged register trap. .RE .PP For .CR SIGFPE , .I code has the following values: .RS .TP 7 12 Overflow trap; .TP 13 Conditional trap; .TP 14 Assist exception trap; .TP 22 Assist emulation trap. .RE .RE .PP Refer to the Series 800 processor documentation provided with your system for more detailed information about the meaning of these errors. .PP The Instruction Address Offset Queue (program counter) is not advanced when a trap occurs on Series 800 systems. If a signal generated by a hardware trap is masked or has its signal action set to .CR SIG_IGN , the program loops infinitely since the instruction causing the trap is re-executed, causing the trap again. If the signal is received by a signal-catching function in the user program, the instruction that caused the trap is re-executed upon return from the signal-catching function unless program flow is altered by the signal-catching function. For example, the .C longjmp() routine (see .IR setjmp (3C)) can be called. Using .C longjmp() ensures software portability across different hardware architectures. .SH AUTHOR .C signal was developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO kill(1), init(1M), bsdproc(2), exit(2), kill(2), lseek(2), pause(2), sigaction(2), signal(2), sigvector(2), wait(2), sigset(2V), abort(3C), setjmp(3C). .SH STANDARDS CONFORMANCE .RC < signal.h ">: AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f1description of signals@@@\f3signal(5)\f1 .\" index@\f1signals, description of@@@\f3signal(5)\f1 .\" .\" toc@\f3signal(5)\f1:\0\0\f4signal()\f1@@@description of signals .\" $Header: stat.5,v 76.1 95/07/07 14:57:28 ssa Exp $ .TA s .TH stat 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sys/stat.h \- data returned by the stat() function .SH SYNOPSIS .C "#include " .PP .SH DESCRIPTION The .CR header defines the structure of the .\" UX data returned by the functions .CR fstat() , .CR lstat() , and .CR stat() . The structure .CR stat contains at least the following members: .PP .TS tab(#); w(1.5i) w(1.5i) w(2.5i) lf4#lf4#l. dev_t#st_dev#ID of device containing file ino_t#st_ino#file serial number mode_t#st_mode#mode of file (see below) nlink_t#st_nlink#number of links to the file uid_t#st_uid#user ID of file gid_t#st_gid#group ID of file .\" EX dev_t#st_rdev#device ID (if file is character or block special) off_t#st_size#file size in bytes (if file is a regular file) time_t#st_atime#time of last access time_t#st_mtime#time of last data modification time_t#st_ctime#time of last status change .\" UX long#st_blksize#T{ a filesystem-specific preferred I/O block size for this object. In some filesystem types, this may vary from file to file T} long#st_blocks#T{ number of blocks of a filesystem\-specific size allocated for this object T} .TE .\" ? .PP File serial number and device ID taken together .\" EX uniquely identify the file within the system. The .CR dev_t , .CR ino_t , .CR mode_t , .CR nlink_t , .CR uid_t , .CR gid_t , .CR off_t , and .CR time_t types are defined as described in .CR . Times are given in seconds since the Epoch. .PP The following symbolic names for the values of .IR st_mode are also defined: .PP File type: .\" EX .TS tab(#); w(1.5i) w(3i) lf4#l. S_IFMT#type of file S_IFBLK#block special S_IFCHR#character special S_IFIFO#FIFO special S_IFREG#regular S_IFDIR#directory .\" ? .\" UX .\" ! S_IFLNK#symbolic link .\" ? .TE .PP File mode bits: .TS tab(#); w(1.5i) w(2.5i) lf4#l. S_IRWXU#read, write, execute/search by owner S_IRUSR#read permission, owner S_IWUSR#write permission, owner S_IXUSR#execute/search permission, owner S_IRWXG#read, write, execute/search by group S_IRGRP#read permission, group S_IWGRP#write permission, group S_IXGRP#execute/search permission, group S_IRWXO#read, write, execute/search by others S_IROTH#read permission, others S_IWOTH#write permission, others S_IXOTH#execute/search permission, others S_ISUID#set-user-ID on execution S_ISGID#set-group-ID on execution .\" UX S_ISVTX#on directories, restricted deletion flag .\" ? .TE .PP The bits defined by .CR S_IRUSR , .CR S_IWUSR , .CR S_IXUSR , .CR S_IRGRP , .CR S_IWGRP , .CR S_IXGRP , .CR S_IROTH , .CR S_IWOTH , .\" UX .CR S_IXOTH , .CR S_ISUID , .CR S_ISGID .\" ! and .CR S_ISVTX are unique. .CR S_IRWXU is the bitwise OR of .CR S_IRUSR , .CR S_IWUSR , and .CR S_IXUSR . .CR S_IRWXG is the bitwise OR of .CR S_IRGRP , .CR S_IWGRP , and .CR S_IXGRP . .CR S_IRWXO is the bitwise OR of .CR S_IROTH , .CR S_IWOTH , and .CR S_IXOTH . .PP Implementations may OR other implementation\-dependent bitsinto .CR S_IRWXU , .CR S_IRWXG , and .CR S_IRWXO , but they will not overlap any of the other bits defined in this document. The file permission bits are defined to be those corresponding to the bitwise inclusive OR of .CR S_IRWXU , .CR S_IRWXG , and .CR S_IRWXO . .PP The following macros will test whether a file is of the specified type. The value .IR m supplied to the macros is the value of .IR st_mode from a .CR stat structure. The macro evaluates to a non\-zero value if the test is true, 0 if the test is false. .PP .TS tab(#); w(1.5) w(2.5) lf4#l. S_ISBLK(m)#Test for a block special file. S_ISCHR(m)#Test for a character special file. S_ISDIR(m)#Test for a directory. .TE .PP .TS tab(#); w(1.5) w(2.5) lf4#l. S_ISFIFO(m)#Test for a pipe or FIFO special file. S_ISREG(m)#Test for a regular file. .\" UX S_ISLNK(m)#Test for a symbolic link. .\" ? .TE .PP The following are declared as functions and may also be defined as macros: .TS tab(#); w(1i) w(3i) lf4#l. int#chmod(const char *path, mode_t mode); .\" UX int#lstat(const char *path, struct stat *buf); int#mkdir(const char *path, mode_t mode); int#mkfifo(const char *path, mode_t mode); .\" UX int#mknod(const char *path, mode_t mode, dev_t dev); int#stat(const char *path, struct stat *buf); mode_t#umask(mode_t cmask); .TE .SH APPLICATION USAGE Use of the macros is recommended for determining the type of a file. .SH SEE ALSO chmod(), fchmod(), fstat(), lstat(), mkdir(), mkfifo(), mknod(), stat(), umask(), . .SH CHANGE HISTORY First released in Issue 1. .PP Derived from Issue 1 of the SVID. .SH Issue 4 .PP The following changes are incorporated for alignment with the ISO POSIX\-1 standard: .RS .TP 3 \(bu The function declarations in this header are expanded to full ISO C prototypes. .TP 3 \(bu The DESCRIPTION section is expanded to indicate (a) how files are uniquely identified within the system, (b) that times are given in units of seconds since the Epoch, (c) rules governing the definition and use of the file mode bits, and (d) usage of the file type test macros. .RE .PP Other changes are incorporated as follows: .RS .TP 3 \(bu Reference to the header is added for the definitions of .IR dev_t , .IR ino_t , .IR mode_t , .IR nlink_t , .IR uid_t , .IR gid_t , .IR off_t , and .IR time_t . This has been marked as an extension. .TP 3 \(bu References to the .CR S_IREAD , .CR S_IWRITE , .CR S_IEXEC file and .CR S_ISVTX modes are removed. .TP \(bu The descriptions of the members of the .CR stat structure in the DESCRIPTION section are corrected. .SH Issue 4, Version 2 .PP The following changes are incorporated for X\/OPEN UNIX conformance: .RS .TP 3 \(bu The .IR st_blksize and .IR st_blocks members are added to the .CR stat structure. .TP 3 \(bu The .CR S_IFLINK value of .CR S_IFMT is defined. .TP 3 \(bu The .CR S_ISVTX file mode bit and the .CR S_ISLNK file type test macro is defined. .TP 3 \(bu The .CR fchmod(), .CR lstat() , and .CR mknod() functions are added to the list of functions declared in this header. .\" $Header: stat.5,v 76.1 95/07/07 14:57:28 ssa Exp $ .TA s .TH stat 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH NAME stat.h \- file-specific information .SH DESCRIPTION The contents of the .I stat structure include the following members: .RS .TP 23 ushort st_fstype; /*Type of filesystem this file */ .TP \& /* is in; see vfsmount(2) */ .TP dev_t st_realdev; /* Real device number of device */ .TP \& /* containing the inode for this file */ .RE .PP The following symbolic names for the values of the .I st_mode field are defined as indicated: .PP File type: .RS 10 .PP .TS l1p-1 l1 l. S_IFMT 0170000 type of file S_IFSOCK 0140000 socket S_IFLNK 0120000 symbolic link S_IFNWK 0110000 network special S_IFREG 0100000 regular (ordinary) S_IFBLK 0060000 block special S_IFDIR 0040000 directory S_IFCHR 0020000 character special S_IFIFO 0010000 FIFO special (named pipe) .TE .RE .PP File mode bits: .RS .PP File miscellaneous mode bits: .RS 15 .PP .TS l1p-1 l1 l. S_CDF 0004000 directory is a context-dependent file S_ISUID 0004000 set user id on execution S_ISGID 0002000 set group id on execution S_ENFMT 0002000 set file-locking mode to enforced S_ISVTX 0001000 save swapped text even after use .TE .RE .PP File permission mode bits: .RS .PP .TS l1p-1 l1 l. S_IRWXU 0000700 owner's file access permission bits S_IRUSR 0000400 read access permission for owner S_IWUSR 0000200 write access permission for owner S_IXUSR 0000100 execute/search access permission for owner S_IRWXG 0000070 group's file access permission bits S_IRGRP 0000040 read access permission for group S_IWGRP 0000020 write access permission for group S_IXGRP 0000010 execute/search access permission for group S_IRWXO 0000007 others' access permission bits S_IROTH 0000004 read access permission for others S_IWOTH 0000002 write access permission for others S_IXOTH 0000001 execute/search access permission for others .TE .RE .PP Obsolete names for file permission mode bits: .RS .PP .TS l1p-1 l1 l. S_IREAD 0000400 read access permission for owner S_IWRITE 0000200 write access permission for owner S_IEXEC 0000100 execute/search access permission for owner .TE .RE .RE .PP File type test macros: .RS 10 .TS l1p-1 l. S_ISCDF(\f2m\fP) test for a context-dependent file S_ISNWK(\f2m\fP) test for a network special S_ISSOCK(\f2m\fP) test for a socket .TE .RE .SH SEE ALSO chmod(2), chown(2), link(2), mkdir(2), mkfifo(2), mknod(2), stat(2), symlink(2), umask(2), utime(2), types(5). .SH STANDARDS CONFORMANCE .RC < sys/stat.h ">: AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4stat\f1 \- data returned by \f4stat\f1/\f4fstat\f1/\f4lstat\f1 system call@@@\f3stat(5)\f1 .\" index@data returned by \f4stat\f1/\f4fstat\f1/\f4lstat\f1 system call@@@\f3stat(5)\f1 .\" index@\f4stat\f1/\f4fstat\f1/\f4lstat\f1 system call, data returned by@@@\f3stat(5)\f1 .\" index@\f4fstat\f1/\f4stat\f1/\f4lstat\f1 system call, data returned by@@@\f3stat(5)\f1 .\" index@\f4lstat\f1/\f4fstat\f1/\f4stat\f1 system call, data returned by@@@\f3stat(5)\f1 .\" index@system call, data returned by \f4stat\f1/\f4fstat\f1/\f4lstat\f1@@@\f3stat(5)\f1 .\" index@call, data returned by \f4stat\f1/\f4fstat\f1/\f4lstat\f1@@@\f3stat(5)\f1 .\" .\" toc@\f3stat(5)\f1:\0\0\f4stat\f1@@@data returned by \f4stat\f1/\f4fstat\f1/\f4lstat\f1 system call .\" .\" fileset_database@stat.5 SYS-ADMIN-MAN .\" $Header: stdarg.5,v 72.4 94/11/15 09:57:45 ssa Exp $ .TA s .TH stdarg 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME stdarg.h \- macros for handling variable argument lists .SH SYNOPSIS .B #include .br .B "void va_start(va_list pvar, argN);" .br .B "\f2type\f3 va_arg(va_list pvar, \f2type\f3);" .br .B "void va_end(va_list pvar);" .SH DESCRIPTION The .RB < stdarg.h > header contains a set of macros that can be used to write portable procedures that accept variable argument lists. Routines that have variable argument lists (such as .IR printf (3S)) but do not use .I stdarg are inherently nonportable, because different machines use different argument-passing conventions. .PP .B va_list is a type defined for the variable used to traverse the list. .PP .B va_start is called to initialize .I pvar to the beginning of the list. The type of .I argN should be the same as the argument to the function just before the variable portion of the argument list. .PP .B va_arg returns the next argument in the list pointed to by .IR pvar . .I type is the type the argument is expected to be. Different types can be mixed, but it is up to the routine to know what type of argument is expected, because it cannot be determined at runtime. .PP .B va_end is used to clean up. .PP Multiple traversals, each bracketed by .I va_start \&... .IR va_end , are possible. .SH EXAMPLE This example is a possible implementation of .I execl (see .IR exec (2)): .PP .nf #include #define \s-1MAXARGS\s0 100 /\(** execl is called by execl(file, arg1, arg2, ..., (char \(**)0); \(**/ execl(const char *file, const char *args, ...) { va_list ap; char \(**array[\s-1MAXARGS\s0]; int argno = 0; va_start(ap, args); if ((array[0] = args) != 0) while ((array[argno++] = va_arg(ap, char \(**)) != 0) ; va_end(ap); return execv(file, array); } .fi .SH SEE ALSO exec(2), vprintf(3S), varargs(5). .SH WARNINGS It is up to the calling routine to specify how many arguments there are, since it is not always possible to determine this from the stack frame. For example, .IR execl (\|) is passed a zero pointer to signal the end of the list, and .IR printf (\|) can tell how many arguments are there by the format string. .PP Unless .SM ANSI C is used, it is non-portable to specify a second argument of .IR char , .IR short , or .IR float to .IR va_arg , because arguments seen by the called function are never .IR char , .IR short , or .IR float . .PP Pre-\c .SM ANSI C converts .I char and .I short arguments to .I int and converts .I float arguments to .IR double before passing them to a function. .SH STANDARDS CONFORMANCE .RC < stdarg.h ">: AES, SVID3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR va_arg ": SVID3, XPG4, ANSI C" .PP .CR va_end ": SVID3, XPG4, ANSI C" .PP .CR va_list ": SVID3, XPG4, ANSI C" .PP .CR va_start ": SVID3, XPG4, ANSI C" .\" .\" index@\f2stdarg.h\f1 \- macros for handling variable argument list@@@\f3stdarg(5)\f1 .\" index@variable argument list macros@@@\f3stdarg(5)\f1 .\" index@macros for handling variable argument lists@@@\f3stdarg(5)\f1 .\" index@argument lists, variable, macros for handling@@@\f3stdarg(5)\f1 .\" .\" toc@\f3stdarg(5)\f1:\0\0\f2stdarg\f1@@@handle variable argument list .\" .\" fileset_database@stdarg.5 SYS-ADMIN-MAN .\" $Header: stdsyms.5,v 72.6 94/11/02 15:58:19 ssa Exp $ .TA s .TH stdsyms 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME stdsyms \- description of HP-UX header file organization .SH DESCRIPTION HP-UX header files are organized in a manner that allows for only a subset of the symbols available in that header file to be visible to an application that conforms to a specific standard. The ANSI-C, POSIX\s0.1, POSIX\s0.2, and XPG4 standards each reserve a certain set of symbols for that standard's namespace. In addition, the HP-UX implementation of XPG3 and the "OSF AES/OS" provides for a clean namespace although this is not a specific requirement of those standards. .PP The following rules apply in determining what symbols are reserved for any standard. These symbols are reserved for the standard and for use by the implementation, and must be either avoided altogether, or used exactly as defined by the specified standard. .RS .TP 3 \(bu All symbols defined by the desired standard are reserved. Refer to the appropriate standards documentation for a complete list of reserved symbols. .TP \(bu All symbols beginning with an underscore followed by another underscore or an uppercase letter are reserved for the implementation. .TP \(bu All external identifiers beginning with an underscore are reserved for the implementation. .RE .PP The following is a list of feature test macros which must be defined to obtain the appropriate namespace from the header files. .RS .TP 10 .C _\|_STDC_\|_ This symbol is automatically defined by the ANSI-C pre-processor .RC ( /opt/langtools/lib/cpp.ansi ) and is automatically defined when specifying an ANSI-C compile .RC ( "cc -Aa" ). Using the strict ANSI option .C -Aa requests a pure ANSI-C namespace, which is the smallest subset of the HP-UX namespace available. The .C -Aa option also enables the inclusion of ANSI\c -C-style function prototypes for increased type checking. Note that the default namespace when using the .C -Aa option is the ANSI-C namespace; therefore a broader namespace must be .I requested if it is desired. .TP .C _POSIX_SOURCE As documented in the IEEE POSIX.1 standard, the programmer is required to define the .C _POSIX_SOURCE feature test macro to obtain the POSIX.1 namespace and POSIX.1 functionality. This feature test macro can be defined, either by using compiler options .RC ( -D_POSIX_SOURCE ) or by using .C #define directives in the source files before any .C #include directives. Note that the default POSIX namespace is the POSIX\s0.1-1990 namespace. It is necessary to define the .C _POSIX1_1988 feature test macro in addition to the .C _POSIX_SOURCE macro in order to obtain the POSIX\s0.1-1988 namespace. .TP .C _POSIX_C_SOURCE As documented in the IEEE POSIX.2 standard, the programmer is required to define the .C _POSIX_C_SOURCE feature test macro with a value of 2 to obtain the POSIX.1 and POSIX.2 namespaces and functionality. This feature test macro can be defined, either by using compiler options .RC ( -D_POSIX_C_SOURCE=2 ) or by using .C #define directives in the source files before any .C #include directives. This macro is also automatically defined in the XPG4 X/Open namespace (that is, whenever .C _XOPEN_SOURCE and .C _XPG4 are defined without defining .C _XPG2 or .CR _XPG3 ). .TP .C _XOPEN_SOURCE As documented in the XPG3 and XPG4 standards, the programmer is required to define the .C _XOPEN_SOURCE feature test macro to obtain X/Open functionality. This feature test macro can be defined, either by using compiler options .RC ( -D_XOPEN_SOURCE ) or by using .C #define directives in the source files before any .C #include directives. Although XPG3 does not specify any namespace pollution rules, XPG4 has instituted such rules. Therefore, the HP-UX operating system provides clean namespaces whenever .C _XOPEN_SOURCE is defined. .IP The current default X/Open namespace is that corresponding to XPG3. To request other versions of the X/Open namespace, define .C _XPG2 or .C _XPG4 in conjunction with .CR _XOPEN_SOURCE . .TP .C _AES_SOURCE As documented in the "OSF AES/OS" standard, the programmer is required to define the .C _AES_SOURCE feature test macro to obtain OSF functionality. This feature test macro can be defined, either by using compiler options .RC ( -D_AES_SOURCE ) or by using .C #define directives in the source files before any .C #include directives. Although the AES does not specify any namespace pollution rules, the other standards have instituted such rules. Therefore HP-UX provideds a clean namespace whenever .C _AES_SOURCE is defined. .TP .C _HPUX_SOURCE The programmer can define the .C _HPUX_SOURCE feature test macro to obtain the HP-UX namespace and complete HP-UX functionality. Note that the HP-UX namespace is currently a superset of all of the above mentioned namespaces. When using the compatibility-mode compiler .RI ( cc (1) without the .C -Aa option), the HP-UX namespace is provided by default. The programmer must request one of the other namespaces as described above to obtain the appropriate subset of the HP-UX namespace. When using the strict ANSI-C-mode compiler .RC ( "cc -Aa" ), the programmer must specifically request a broader namespace. .IP The .C _HPUX_SOURCE feature test macro can be defined, either by using compiler options .RC ( -D_HPUX_SOURCE ) or by using .C #define directives in the source files before any .C #include directives. .RE .PP The following is a list of miscellaneous feature test macros that provide various additional features. .RS .TP 10 .C _\|_cplusplus This symbol is automatically defined by the HP C++ compiler. Defining this macro enables the C++ function prototypes in system header files. .IP The default namespace for HP C++ is the ANSI-C namespace. To obtain another namespace define the appropriate feature test macro. .IP HP C++ uses the ANSI-C preprocessor by default. To get the compatibility mode preprocessor, use the .C -Ac option to .RI cc (1) . The compatibility mode preprocessor uses the HP-UX namespace .RC ( _HPUX_SOURCE ) . .TP .C _POSIX1_1988 This feature test macro should be defined when the .C POSIX\s0.1-1988 namespace is required. It should be used in conjunction with the .C _POSIX_SOURCE macro if the default .C POSIX\s0.1-1990 namespace is not desired. .IP This macro is defined automatically whenever .C _AES_SOURCE or .C _XPG3 is requested. .TP .C _XPG2 The .C _XPG2 macro can be defined when using the compatibility-mode compiler to obtain XPG2 functionality. This provides XPG2 specified function declarations and macros in the HP-UX namespace. Note that the values obtained from most of the macros available when using this option are now available at run-time via the .CR pathconf() , .CR fpathconf() , and .CR sysconf() system calls (see .IR pathconf (2) and .IR sysconf (2)). Use of the .C _XPG2 macro is strongly discouraged because it gives access to obsolete functionality. Note that no function prototypes are provided when using this feature test macro. .TP .C _XPG3 The .C _XPG3 feature test macro is defined automatically if the programmer has requested the XPG3 namespace (i.e., defined .CR _XOPEN_SOURCE , but not some other conflicting namespace such as .C _XPG2 or .CR _XPG4 ). .TP .C _XPG4 The .C _XPG4 feature test macro is provided so that the programmer can obtain the XPG4 namespace, since it differs slightly from the .C _XPG3 namespace. In order to obtain the XPG4 namespace, the programmer must define both the .C _XOPEN_SOURCE and .C _XPG4 feature test macros. The .C _XOPEN_SOURCE and .C _XPG4 feature test macros can be defined, either by using compiler options .RC ( "-D_XOPEN_SOURCE -D_XPG4" ) or by using .C #define directives in the source files before any .C #include directives. .TP .C _SVID2 The .C _SVID2 macro can be defined when using the compatibility mode compiler to obtain SVID2 function return types in the HP-UX namespace. The default return types of many functions have since been changed in the HP-UX operating system to align with the ANSI-C, POSIX, X/Open, and OSF standards. .TP .C _CLASSIC_TYPES The .C _CLASSIC_TYPES macro can be defined by the programmer to obtain pre-7.0 style function return types and structure element types. This macro has been provided only as a transition aid when migrating from the pre-7.0 version of HP-UX to standards-based HP-UX. Use of this macro is strongly discouraged as this functionality will be removed in a future release of HP-UX. Note that no function prototypes are provided when using this feature test macro. .RE .SH SEE ALSO cc(1), cpp(1), pathconf(2), sysconf(2). .\" .\" index@\f4stdsyms\f1 \- description of HP-UX header file organization@@@\f3stdsyms(5)\f1 .\" index@\f1description of HP-UX header file organization@@@\f3stdsyms(5)\f1 .\" index@\f1HP-UX header file organization, description of@@@\f3stdsyms(5)\f1 .\" index@\f1header file organization, description of HP-UX@@@\f3stdsyms(5)\f1 .\" index@\f1organization, description of HP-UX header file@@@\f3stdsyms(5)\f1 .\" .\" toc@\f3stdsyms(5)\f1:\0\0\f4stdsyms\f1@@@description of HP-UX header file organization .\" $Header: suffix.5,v 72.4 94/05/17 22:00:55 ssa Exp $ .TA s .TH suffix 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME suffix \- file-name suffix conventions .SH DESCRIPTION The following list summarizes file name suffix conventions that can be found in an .SM HP-UX system. It is a partial compilation of possibly useful knowledge, suggestions, and explanations, rather than a specification of standards. Suffixes are often used in preference to prefixes because they enable related files to group together alphabetically in a directory listing. .PP Note that some programs require the use of a specific value, or vary their behavior based on a choice of suffixes. Such programs are noted in many (but not all) cases. .TP 15 .B .A HP64000 cross assembler symbol file. .TP .B .a Library file (archive) managed by .IR ar ; known to .IR make . .TP .B .ad? HP Ada source, where "?" stands for any single character. .TP .B .allow List of users allowed by .I at or .I cron (for example, at.allow). .TP .B .an Source for nroff "man" macros. .TP .SM .B .ASC .SM LIF (Logical Interchange Format) type 1, .SM ASCII file for use by Pascal or .SM BASIX/UX. Incompatible with .IR lifcp . .TP .B .aux Cross-referencing information created automatically by LaTeX. .TP .B .awk .I awk script file. .TP .B .b Compiled .SM LISP (.l) source file, or a bold font file. .TP .B .back .PD 0 .TP .B .bak .TP .B .bkup Backup copy of a file. .PD .TP .SM .B .BAD .PD 0 .TP .B .bad File containing bad data, or occupying a bad spot on a disk. .PD .TP .B .bbl Bibliography created by BibTeX for inclusion in a LaTeX document. .TP .B .bib Bibliographic data file, (for example, BibTeX bibliography database). .TP .B .blg Log of errors from BibTeX. .TP .B .bst BibTeX bibliography style definition. .TP .B .C File compressed by .IR compact , or C++ language source file, or HP64000 cross compiled C source file. .TP .B .c C language source file; known to .I cc and .IR make . .TP .B .cas .SM CAST language scripts. .TP .B .cat .SM NLS (Native Language Support) message catalog. .TP .B .cf Configuration file (for example, sendmail.cf). .TP .B .clu .SM CLU file. .TP .SM .B .CODE Pascal workstation object code. .TP .B .cpio File containing output from .IB cpio " -o" , that is, a .I cpio archive. .TP .B .csh C-shell .RI ( csh ) script. .TP .B .curr Current version of a file. .TP .B .d Directory file, or data file. .TP .B .day A script that is read daily. .TP .B .deny List of users denied by .I at or .IR cron (for example, cron.deny). .TP .B .devs List of devices. .TP .B .diff Differences between two files, output from .IR diff . .TP .B .dir .SM DBM database directory file. .TP .B .doc Documentation file of some sort. .TP .B .dvi Device-independent text formatter output. .TP .B .e Extended .SM FORTRAN language .SM (EFL) source file; known to .IR make . .TP .B .el .SM GNU Emacs Elisp file. .TP .B .elc Compiled .SM GNU Emacs Elisp file. .TP .B .eqn Source for .I nroff equation macros. .TP .B .err Standard error from a program. .TP .B .errors .PD 0 .TP .B .errs Errors recorded by a program. .PD .TP .B .f .SM FORTRAN language source file; known to .I fc and .IR make . .TP .B .f77 .SM FORTRAN 77 language source file. .TP .B .fc Frozen configuration file (for example, sendmail.fc). .TP .B .full A complete file or list. .TP .B .gf TeX font bitmaps in Generic Font format. .TP .B .glo Glossary created by LaTeX. .TP .B .h C language header (include) file; known to .IR make . .TP .B .help .PD 0 .TP .B .hf .TP .B .hlp Help text for a program, often read automatically. .PD .TP .B .hour .PD 0 .TP .B .hr A script that is read hourly. .PD .TP .B .i Output of C preprocessor ("cc -P"), or a Berkeley Pascal language include file, or an italicized font file. .TP .B .icn Icon source code. .TP .B .idx Index created by LaTeX. .TP .B .in Standard input to a program. .TP .SM .B .INDEX .I notes index file. .TP .B .ksh Korn shell script file. .TP .B .L HP64000 cross linker symbol file. .TP .B .l .I lex source file (known to .IR make ), or .SM LISP source file. .TP .SM .B .LIST .I notes list file. .TP .B .list File containing a list of other files. .TP .B .ln Library information for .IR lint . .TP .B .lof List of figures created by LaTeX. .TP .B .log Generic log file, or a log of error messages from TeX. .TP .B .lot List of tables created by LaTeX. .TP .B .m Modula language source file. .TP .B .m2 Modula-2 language source file. .TP .B .make .PD 0 .TP .B .mk Makefile for .IR make . .PD .TP .B .man Source for .I nroff or .I troff using .B man macros. .TP .B .me Source for .I nroff or .I troff using .B me macros. .TP .B .mf TeX metafont input file. .TP .B .ml Gosling/Unipress Emacs Mock Lisp file. .TP .B .mm Source for .I nroff or .I troff using .B mm macros. .TP .B .mon .PD 0 .TP .B .month A script that is read monthly. .PD .TP .B .ms Source for .I nroff or .I troff using .B ms macros. .TP .B .n .I nroff source. .TP .SM .B .NEW .PD 0 .TP .B .new New version of a file. .PD .TP .B .nro .I nroff source. .TP .B .O HP64000 listing file. .TP .B .o Relocatable object file (post-compile, pre-link); known to .IR as , .IR cc , .IR fc , .IR pc , and .IR make . .TP .B .obs Obsolete version of a file. .TP .SM .B .OLD .PD 0 .TP .B .old Old version of a file. .PD .TP .B .opt File containing optional material, such as an optional part of the kernel. .TP .B .orig Original version of a file. .TP .B .out Standard output (and possibly standard error) from a program (for example, nohup.out), or an executable file output from .I ld (such as a.out). .TP .B .P HP64000 cross compiled Pascal source file. .TP .B .p Pascal language source file (known to .I pc and .IR make ), or .SM PROLOG language source file. .TP .B .pag .SM DBM database data file. .TP .B .pi .SM PILOT language source file. .TP .B .pk TeX font bitmaps in Packed Font format; denser/more recent than GF. .TP .B .prev Previous version of a file. .TP .B .ps PostScript files. .TP .B .pxl TeX font bitmaps in uncompressed format; very obsolete. .TP .B .R HP64000 relocatable file. .TP .B .r RatFor language source file; known to .IR make . .TP .B .rc A "run commands" file, normally read when a program is invoked (for example, mailx.rc). .TP .B .real Real version of a file, often one which was replaced by a front-end (for example, uucico.real). .TP .B .req File containing required material, such as a required part of the kernel. .TP .B .S HP64000 cross assembled source file. .TP .B .s Assembler input file; known to .I cc and .IR make . .TP .B .safe .PD 0 .TP .B .save Safe or saved copy of a file. .PD .TP .B .scm Scheme file. .TP .B .sh Bourne shell script file; known to .IR make . .TP .B .shar Shell archive file containing output from .IR shar . .TP .B .skel Skeletal or template file. .TP .B .sl Shared library file built by .IR ld (1); known to .IR ld (1). .TP .B .st File containing statistics (for example, .BR /etc/mail/sendmail.st ). .TP .B .sty LaTeX style definition; should have a corresponding .doc file. .TP .SM .B .SYSTM .SM LIF Bootable by the Series 300/400 boot .SM ROM (see Librarian chapter of .I "Pascal 3.2 Workstation System," vol. 1). .TP .B .t Text file. .TP .B .tar File (archive) containing output from .IR tar . .TP .B .tbl Source for .I nroff table macros. .TP .B .temp .PD 0 .TP .B .tmp Temporary file. .PD .TP .B .template Prototype or template file. .TP .B .test Test input or output file. .TP .B .tex TeX source file. .TP .SM .B .TEXT .I notes text file, or a Pascal workstation "UCSD text format" file. .TP .B .text .PD 0 .TP .B .txt .SM ASCII text file. .PD .TP .B .tfm Width information used by TeX (TeX font metrics). .TP .B .toc Source for .I nroff table of contents macros, or table of contents created by LaTeX. .TP .B .tro .I troff source. .TP .B .u1 .PD 0 .TP .B .u2 Icon intermediate code files. .PD .TP .SM .B .UX HP-UX text or binary file format. .TP .B .web Web file (Knuth's Web system). .TP .B .week .PD 0 .TP .B .wk A script that is read weekly. .PD .TP .B .X HP64000 absolute file. .TP .B .y .I yacc input file; known to .IR make . .TP .B .Z File compressed by .IR compress . .TP .B .z File compressed by .IR pack . .TP .BR .1 \0.. \0.8 Manual entry files (sections 1 through 8), optionally followed by a letter a..z. .TP .I . File saved on given date (year, month name, YYMM, MMDD, etc.) as a snapshot of a continuously-growing logfile. .TP .B ,v .SM RCS delta file; known to the .SM RCS programs. .SH AUTHOR .I suffix was developed by HP. .\" index@\f2suffix\f1 \- file-name suffix conventions@@@\f3suffix(5)\f1 .\" index@conventions, file-name suffix@@@\f3suffix(5)\f1 .\" index@file-name suffix conventions@@@\f3suffix(5)\f1 .\" .\" toc@\f3suffix(5)\f1:\0\0\f2suffix\f1@@@file-name suffix conventions .\" .\" fileset_database@suffix.5 SYS-ADMIN-MAN .\" $Header: term.5,v 76.1 95/08/01 14:51:28 ssa Exp $ .TA t .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH 5 "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME term.h \(em terminal capabilities .SH SYNOPSIS .C "#include " .SH DESCRIPTION The following data type is defined through \f3typedef\f1: .VL 12 .LI \f3TERMINAL\f1 An opaque representation of the capabilities for a single terminal from the \f3terminfo\f1 database. .LE .P The .Hd term.h header provides a declaration for the following object: .I cur_term . It represents the current terminal record from the \f3terminfo\f1 database that the application has selected by calling .Fn set_curterm . .P The .Hd term.h header contains the variable names listed in the .B "Variable" column in the table in \f3Defined Capabilities\f1 in terminfo(4). .P The following are declared as functions, and may also be defined as macros: .P \f4int del_curterm(TERMINAL *\f2oterm\fP); .br int putp(char *const \f2str\fP); .br int restartterm(char *\f2term\fP, int \f2fildes\fP, int *\f2errret\fP); .br TERMINAL *set_curterm(TERMINAL *\f2nterm\fP); .br int setupterm(char *\f2term\fP, int \f2fildes\fP, int *\f2errret\fP); .br int tgetent(char *\f2bp\fP, char *const \f2name\fP); .br int tgetflag(char \f2id\fP[2]); .br int tgetnum(char \f2id\fP[2]); .br char *tgetstr(char \f2id\fP[2], char **\f2area\fP); .br char *tgoto(char *const \f2cap\fP, int \f2col\fP, int \f2row\fP); .br int tigetflag(char *\f2capname\fP); .br int tigetnum(char *\f2capname\fP); .br char *tigetstr(char *\f2capname\fP); .br char *tparm(char *\f2cap\fP, long \f2p1\fP, long \f2p2\fP, long \f2p3\fP, long \f2p4\fP, .br long \f2p5\fP, long \f2p6\fP, long \f2p7\fP, long \f2p8\fP, long \f2p9\fP); .br int tputs(char *const \f2str\fP, int \f2affcnt\fP, int (*\f2putfunc\fP)(int)); .SH "SEE ALSO" terminfo(4), printf(), putp(), tigetflag(), tgetent(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@<\f4term.h\f1> \- terminal capabilities@@@\f3term(5)\f1 .\" .\" toc@\f3term(5)\f1:\0\0\f4term\f1@@@terminal capabilities .\" .\" fileset_database@term.5 CURS-ENG-A-MAN .\" $Header: types.5,v 74.1 95/05/10 21:18:12 ssa Exp $ .TA t .TH types 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME types \- primitive system data types .SH SYNOPSIS .B #include .SH REMARKS The example given on this page is a typical version. The type names are in general expected to be present, although exceptions (if any) may be described in .SM DEPENDENCIES. In most cases the fundamental type which implements each typedef is implementation dependent as long as source code which uses those typedefs need not be changed. In some cases the typedef is actually a shorthand for a commonly used type, and will not vary. .SH DESCRIPTION The data types defined in the include file are used in .SM HP-UX system code; some data of these types are accessible to user code: .PP .RS .ta \w'typedef\ \ 'u +\w'unsigned\ short\ \ 'u +8 .TS l l. typedef struct { int r[1]; } \(**physadr; typedef long daddr_t; typedef char \(**caddr_t; typedef unsigned int uint; typedef unsigned short ushort; typedef ushort ino_t; typedef short cnt_t; typedef long time_t; typedef long dev_t; typedef long off_t; typedef long paddr_t; typedef long key_t; typedef short pid_t; typedef long uid_t; typedef long gid_t; .TE .RE .PP Note that the defined names above are standardized, but the actual type to which they are defined may vary between .SM HP-UX implementations. .PP The meanings of the types are: .RS .TP 12 .I physadr used as a pointer to memory; the pointer is aligned to follow hardware-dependent instruction addressing conventions. .TP .I daddr_t used for disk addresses except in an inode on disk, see .IR fs (4). .TP .I caddr_t used as an untyped pointer or a pointer to untyped memory. .TP .I uint shorthand for \f2unsigned\ integer\f1. .TP .I ushort shorthand for \f2unsigned\ short\f1. .TP .I ino_t used to specify I-numbers. .TP .I cnt_t used in some implementations to hold reference counts for some kernel data structures. .TP .I time_t time encoded in seconds since 00:00:00 \s-1GMT\s0, January 1, 1970. .TP .I dev_t specifies kind and unit number of a device, encoded in two parts known as major and minor. .TP .I off_t offsets measured in bytes from the beginning of a file. .TP .I paddr_t used as an integer type which is properly sized to hold a pointer. .TP .I key_t the type of a key used to obtain a message queue, semaphore, or shared memory identifier, see .IR stdipc (3C). .TP .I pid_t used to specify process and process group identifiers. .TP .I uid_t used to specify user identifiers. .TP .I gid_t user to specify group identifiers. .RE .SH SEE ALSO fs(4), stdipc(3C). .SH STANDARDS CONFORMANCE .RC < sys/types.h ">: AES, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4types\f1 \- primitive system data types@@@\f3types(5)\f1 .\" index@\f1primitive system data types@@@\f3types(5)\f1 .\" index@\f1system data types, primitive@@@\f3types(5)\f1 .\" index@\f1data types, system primitives@@@\f3types(5)\f1 .\" index@\f1types, system data primitives@@@\f3types(5)\f1 .\" .\" toc@\f3types(5)\f1@@@primitive system data types .\" .\" $Header: unctrl.5,v 76.2 95/08/01 14:58:49 ssa Exp $ .TA u .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH 5 "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME unctrl.h \(em definitions for \f2unctrl\|\fP(\|) .SH DESCRIPTION The .Hd unctrl.h header defines the .CR chtype type as defined in .CR . .P The following is declared as a function, and may also be defined as a macro: .IP \f4char *unctrl(chtype \f2c\fP); .PP .SH "SEE ALSO" unctrl(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@<\f4unctrl.h\f1> \- definition for \f4unctrl()\f1@@@\f3unctrl(5)\f1 .\" .\" toc@\f3unctrl(5)\f1:\0\0\f4unctrl\f1@@@definition for \f4unctrl()\f1 .\" .\" fileset_database@unctrl.5 CURS-ENG-A-MAN .\" $Header: unistd.5,v 74.1 95/02/25 12:30:49 ssa Exp $ .TA u .TH unistd 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME unistd.h \- standard structures and symbolic constants .SH SYNOPSIS .C #include .SH DESCRIPTION The header .RC < unistd.h > defines the following structures and symbolic constants: .PP Symbolic constants for the .C access() function: .RS .TP 15 .C R_OK Test for read permission .PD 0 .TP .C W_OK Test for write permission .TP .C X_OK Test for execute (search) permission .TP .C F_OK Test for existence of file .PD .RE .PP The constants .CR F_OK , .CR R_OK , .C W_OK , and .C X_OK and the expressions .CR R_OK|W_OK , .CR R_OK|X_OK , and .C R_OK|W_OK|X_OK all have distinct values. .PP Symbolic constant representing a null pointer: .IP .C NULL .PP Symbolic constants for the .C lseek() and .C fcntl() functions (the following constants have distinct values): .RS .TP 15 .C SEEK_SET Set file offset to "offset" .PD 0 .TP .C SEEK_CUR Set file offset to current plus "offset" .TP .C SEEK_END Set file offset to .SM EOF plus "offset" .PD .RE .PP Symbolic constants (with fixed values): .RS .TP 18 .C _POSIX_VERSION Integer value indicating version of .SM .I IEEE .I Std 1003.1 standard implemented. The current value is 199009L, indicating the (4-digit) year and (2-digit) month that the standard was approved by the .SM IEEE Standards Board. However, if any of the symbols .CR _AES_SOURCE , .CR _XPG3 , or .C _POSIX1_1988 is defined before .RC < unistd.h > is included, the value of this symbol will be 198808L. .TP .C _POSIX2_VERSION Integer value indicating version of .SM .I IEEE .I Std 1003.2 standard implemented. The current value is 199209L, indicating the (4-digit) year and (2-digit) month that the standard was approved by the .SM IEEE Standards Board. .TP .C _POSIX2_C_VERSION Integer value indicating version of .SM .I IEEE .I Std 1003.2 C-Language Binding Option implemented. The current value is 199209L, indicating the (4-digit) year and (2-digit) month that the standard was approved by the .SM IEEE Standards Board. .TP .C _XOPEN_VERSION Integer value indicating issue number of the X/Open Portability Guide implemented. The current value is 4, indicating Issue 4. However, if the symbol .C _XPG3 is defined before .RC < unistd.h > is included, the value of this symbol will be 3. .RE .PP The following symbolic constants are defined in this header if the state of the corresponding option or restriction does not vary after compilation. If a symbol is absent from this header, the value or presence of the corresponding option or restriction should be determined at execution time through .C sysconf() or .CR pathconf() : .RS .TP 33 .C _POSIX_CHOWN_RESTRICTED the use of .C chown() is restricted to processes that have appropriate privileges .TP .C _POSIX_JOB_CONTROL implementation supports job control (true of all .SM HP-UX implementations) .TP .C _POSIX_NO_TRUNC pathname components longer than .C NAME_MAX generate an error .TP .C _POSIX_SAVED_IDS effective user and group are saved across an .C exec() call (true of all .SM HP-UX implementations) .TP .C _POSIX_FSYNC implementation supports File Synchronization (true of all .SM HP-UX implementations). See .IR open (2). .TP .C _POSIX_SYNCHRONIZED_IO implementation supports Synchronized IO (true of all .SM HP-UX implementations). See .IR open (2). .TP .C _POSIX_VDISABLE terminal special characters can be disabled using this character (see .IR termio (7)) .TP .C _POSIX2_C_BIND all .SM POSIX\s0.2 C-language functionality is provided in the default libraries used by the .C c89 C compiler (see .IR cc (1)). .TP .C _POSIX2_LOCALEDEF new locales can be defined by using the .C localedef command (see .IR localedef (1M)). .TP .C _POSIX2_UPE the system supports .I IEEE .I Std 1003.2a (\c .SM POSIX User Portability Utilities Option) .TP .C _POSIX2_CHAR_TERM at least one terminal exists that supports all required .SM POSIX\s0.2a commands. .RE .PP All symbolic constants whose names begin .CR _CS , .CR _PC , and .C _SC (see .IR confstr (3C), .IR pathconf (2), and .IR sysconf (2)) are defined. .PP The following symbolic constants for file streams are defined: .RS .TP 25 .C STDIN_FILENO File number of standard input .RI ( stdin ). .PD 0 .TP .C STDOUT_FILENO File number of standard output .RI ( stdout ). .TP .C STDERR_FILENO File number of standard error .RI ( stderr ). .PD .RE .PP The types .CR size_t , .CR ssize_t , .CR uid_t , .CR gid_t , .CR off_t , and .CR pid_t are defined. .PP Declarations are provided for the following functions: .RS .TS lf4 lf4 lf4 lf4. access() alarm() brk() chdir() chown() chroot() close() confstr() crypt() ctermid() cuserid() dup() dup2() encrypt() endusershell() execl() execle() execlp() execv() execve() execvp() _exit() fchown() fork() fpathconf() fsync() ftruncate() getcwd() getegid() geteuid() getgid() getgroups() gethostname() getlogin() getopt() getpass() getpgrp() getpgrp2() getpid() getppid() getuid() getusershell() initgroups() ioctl() isatty() link() lockf() logname() lseek() mkstemp() mktemp() nice() pathconf() pause() pipe() prealloc() read() readlink() rmdir() sbrk() setgid() setgroups() sethostname() setpgid() setpgrp() setpgrp2() setresgid() setresuid() setsid() setuid() setusershell() sgetl() sleep() sputl() swab() swapon() symlink() sync() sysconf() tcgetpgrp() tcsetpgrp() truncate() ttyname() ttyslot() unlink() vfork() write() .TE .RE .SH SEE ALSO access(2), chown(2), confstr(3C), exit(2), fcntl(2), kill(2), lseek(2), open(2), pathconf(2), sysconf(2), limits(5), stdsyms(5), termio(7). .SH AUTHOR .C unistd was developed by HP. .SH STANDARDS CONFORMANCE .RC < unistd.h ">: AES, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.2, POSIX.4" .\" .\" index@\f4unistd.h\f1 \- standard structures and symbolic constants@@@\f3unistd(5)\f1 .\" index@standard structures and symbolic constants@@@\f3unistd(5)\f1 .\" index@structures and symbolic constants, standard@@@\f3unistd(5)\f1 .\" index@symbolic constants, standard structures and@@@\f3unistd(5)\f1 .\" index@constants, standard structures and symbolic@@@\f3unistd(5)\f1 .\" .\" toc@\f3unistd(5)\f1:\0\0\f4unistd.h\f1@@@standard structures and symbolic constants .\" .\" fileset_database@unistd.5 SYS-ADMIN-MAN ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\"Copyright Hewlett-Packard Company 1991 ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" .rm zA .rm zZ .TH v5srvtab "5" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .SH NAME .iX "Security Service commands" "\*L/krb5/v5srvtab\*O" .iX "\*L/krb5/v5srvtab\*O file" .iX "keytab file" .iX "passwords" "storing server and machine" .iX "files" "keytab" .zA "defect,6211,R1.0.3,removed full pathname" \*Lv5srvtab\*O \- The server and machine keytab file .zZ "defect,6211,R1.0.3,removed full pathname" .SH "DESCRIPTION" .PP The \*L/krb5/v5srvtab\*O file is a file on the local node created by the \*Lrgy_edit\*O command, the \*Lsec_create_db\*O command, or any application that makes \*Lsec_key_mgmt(\|)\*O calls. The file contains passwords for servers and machine accounts. To view or manipulate the contents of this file, use the sec_key_mgmt API, described in the \*(Dk and the \*(Dr. .SH "RELATED INFORMATION" Books: \*(Dk, \*(Dr. .\" $Header: values.5,v 74.1 95/05/10 21:18:32 ssa Exp $ .TA v .TH values 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME values \- machine-dependent values .SH SYNOPSIS .B #include .SH DESCRIPTION This file contains a set of manifest constants, conditionally defined for particular processor architectures. .PP The model assumed for integers is binary representation (one's or two's complement), where the sign is represented by the value of the high-order bit. .RS .TP 15 .RI \s-1BITS\s0( type ) The number of bits in a specified type (e.g., int). .TP .SM HIBITS The value of a short integer with only the high-order bit set (in most implementations, 0x8000). .TP .SM HIBITL The value of a long integer with only the high-order bit set (in most implementations, 0x80000000). .TP .SM HIBITI The value of a regular integer with only the high-order bit set (usually the same as \s-1HIBITS\s0 or \s-1HIBITL\s0). .TP .SM MAXSHORT The maximum value of a signed short integer (in most implementations, 0x7FFF \(== 32767). .TP .SM MAXLONG The maximum value of a signed long integer (in most implementations, 0x7FFFFFFF \(== 2147483647). .TP .SM MAXINT The maximum value of a signed regular integer (usually the same as \s-1MAXSHORT\s0 or \s-1MAXLONG\s0). .TP .SM "MAXFLOAT, LN_MAXFLOAT" The maximum value of a single-precision floating-point number, and its natural logarithm. .TP .SM "MAXDOUBLE, LN_MAXDOUBLE" The maximum value of a double-precision floating-point number, and its natural logarithm. .TP .SM "MINFLOAT, LN_MINFLOAT" The minimum positive value of a single-precision floating-point number, and its natural logarithm. .TP .SM "MINDOUBLE, LN_MINDOUBLE" The minimum positive value of a double-precision floating-point number, and its natural logarithm. .TP .SM FSIGNIF The number of significant bits in the mantissa of a single-precision floating-point number. .TP .SM DSIGNIF The number of significant bits in the mantissa of a double-precision floating-point number. .RE .SH FILES /usr/include/values.h .SH "SEE ALSO" intro(3), math(5). .SH STANDARDS CONFORMANCE .RC < values.h ">: XPG2" .\" .\" index@\f4values\f1 \- machine-dependent values@@@\f3values(5)\f1 .\" index@\f1machine-dependent programming values and constants@@@\f3values(5)\f1 .\" index@\f1programming values and constants, machine-dependent@@@\f3values(5)\f1 .\" index@\f1constants and values for programming, machine-dependent@@@\f3values(5)\f1 .\" index@\f1values and constants for programming, machine-dependent@@@\f3values(5)\f1 .\" .\" toc@\f3values(5)\f1@@@machine-dependent values .\" .\" $Header: varargs.5,v 78.1 96/01/03 15:35:21 ssa Exp $ .TA v .TH varargs 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME varargs \- handle variable argument list .SH SYNOPSIS .C #include .PP .C va_alist .PP .C va_dcl .PP .C void va_start(pvar) .br .C va_list pvar; .PP .IC "type " va_arg(pvar, " type" ) .br .C va_list pvar; .PP .C void va_end(pvar) .br .C va_list pvar; .SH DESCRIPTION This set of macros enables programmers to write portable procedures that accept variable argument lists. Routines that have variable argument lists (such as .C printf()) but do not use .C varargs are inherently nonportable, because different machines use different argument-passing conventions (see .IR printf (3S)). .PP .C va_alist is used as the parameter list in a function header. .PP .C va_dcl is a declaration for .CR va_alist . No semicolon should follow .CR va_dcl . .PP .C va_list is a type defined for the variable used to traverse the list. .PP .C va_start is called to initialize .C pvar to the beginning of the list. .PP .C va_arg returns the next argument in the list pointed to by .CR pvar . .I type is the type the argument is expected to be. Different types can be mixed, but it is up to the routine to know what type of argument is expected, because it cannot be determined at runtime. .PP .C va_end is used to clean up. .PP Multiple traversals, each bracketed by .CR va_start \0...\0 va_end , are possible. .SH EXAMPLE The following example shows a possible implementation of .C execl() (see .IR exec (2)): .if t .RS .nf .PP .C #include .C #define MAXARGS 100 .IP .C "/* execl is called by" .C " execl(file, arg1, arg2, ..., (char *)0);" .C */ .C execl(va_alist) .C va_dcl .C { .C " va_list ap;" .C " char *file;" .C " char *args[MAXARGS];" .C " int argno = 0;" .IP .C " va_start(ap);" .C " file = va_arg(ap, char *);" .C " while ((args[argno++] = va_arg(ap, char *)) != (char *)0);" .IP .C " va_end(ap);" .C " return execv(file, args);" .C } .fi .if t .RE .PP The next example illustrates how a function that receives variable arguments can pass these arguments down to other functions. To accomplish this, the first routine .RC ( log_errors() in this example) which receives the variable argument list must pass the address pointer resulting from a call to .C va_start() on to any subsequent calls that need to access this same variable argument list. All routines that receive this address pointer .RC ( v_print_log() in this example) need only to use .C va_arg() to access the original variable argument list just as if they were the original routine to be passed the variable arguments. .PP In this example, one can imagine that there are a series of other routines (such as a .C log_warning() and .CR log_message() ) that also call the .C v_print_log() function. .if t .RS .PP .nf .C #include .C #include .C #include .PP .C int error_count; .PP .C "/* VARARGS4 -- for lint */" .C int .C "log_errors(log_fp, func_name, err_num, msg_fmt, va_alist)" .C FILE *log_fp; .C char *func_name; .C int err_num; .C char *msg_fmt; .C va_dcl .C { .PP .nf .ift .ft 4 .ifn .ft 3 .ps +1 va_list ap; .ift .sp .5v .ifn .sp /* Print error header information */ (void) fprintf(log_fp, "\\nERROR in process %d\\n", getpid()); (void) fprintf(log_fp, " function \\"%s\\": ", func_name); switch(err_num) { case ILLEGAL_OPTION: (void) fprintf(log_fp, "illegal option\\n"); break; case CANNOT_PARSE: (void) fprintf(log_fp, "cannot parse input file\\n"); break; ... } .ift .sp .5v .ifn .sp /* * Get pointer to first variable argument so that we can * pass it on to v_print_log(). We do this so that * v_print_log() can access the variable arguments passed * to this routine. */ va_start(ap); .ift .sp .5v .ifn .sp v_print_log(log_fp, msg_fmt, ap); .ift .sp .5v .ifn .sp va_end(ap); } .ift .sp .5v .ifn .sp /* VARARGS2 -- for lint */ int v_print_log(log_fp, fmt, ap) FILE *log_fp; char *fmt; va_list ap; { .ift .sp .5v .ifn .sp /* * If "%Y" is the first two characters in the format string, * a second file pointer has been passed in to print general * message information to. The rest of the format string is * a standard printf(3S) format string. */ if ((*fmt == '%') && (*(fmt + 1) == 'Y')) { FILE *other_fp; .ift .sp .5v .ifn .sp fmt += 2; .ift .sp .5v .ifn .sp other_fp = (FILE *) va_arg(ap, char *); if (other_fp != (FILE *) NULL) { /* * Print general message information to additional stream. */ (void) vfprintf(other_fp, fmt, ap); (void) fflush(other_fp); } } .ift .sp .5v .ifn .sp /* * Now print it to the log file. */ (void) vfprintf(log_fp, fmt, ap); } .ft .ps .if t .RE .SH WARNINGS It is up to the calling routine to specify how many arguments there are, because it is not always possible to determine this from the stack frame. For example, .C execl() is passed a zero pointer to signal the end of the list. .C printf() can determine how many arguments are present by the format. .PP It is non-portable to specify a second argument of .CR char , .CR short , or .C float to .CR va_arg , because arguments seen by the called function are not .CR char , .CR short , or .CR float . C converts .C char and .C short arguments to .CR int , and converts .C float arguments to .CR double , before passing them to a function. .SH SEE ALSO exec(2), vprintf(3S). .SH STANDARDS CONFORMANCE .CR va_alist ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR va_arg ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR va_dcl ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR va_end ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR va_list ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR va_start ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR ": AES, SVID3, XPG2, XPG3, XPG4" .\" .\" toc@\f3varargs(5)\f1:\0\0\f4varargs.h\f1@@@handle variable argument list .\" .\" index@\f1varargs.h\f1 \- macros for handling variable argument list@@@\f3varargs(5)\f1 .\" index@\f1variable argument list macros@@@\f3varargs(5)\f1 .\" index@\f1macros for handling variable argument lists@@@\f3varargs(5)\f1 .\" index@\f1argument lists, variable, macros for handling@@@\f3varargs(5)\f1 .\" $Header: x_open.5,v 74.1 95/05/10 21:19:25 ssa Exp $ .TA x .TH x_open 5 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME x_open \- Pointer manual entry for X/Open Conformance Statement Questionnaire .SH DESCRIPTION This entry is a pointer entry for accessing the X/Open Conformance Statement Questionnaire for HP\|9000 Series 700/800 .SM HP-UX systems. To access the conformance statement, use the command: .IP .B man x_open_800 .SH FILES .TP /usr/share/man/man5.Z/x_open_800.5 Series 700/800 X/Open Conformance Statement Questionnaire (preformatted and compressed) .\" .\" index@\f4x_open(5)\f1 \- pointer manual entry for X/Open Conformance Statement Questionnaire@@@\f3x_open(5)\f1 .\" index@\f1X/Open Conformance Statement Questionnaire, pointer to manpage, x_open_800@@@\f3x_open(5)\f1 .\" index@\f1x_open_800, X/Open Conformance Statement Questionnaire@@@\f3x_open(5)\f1 .\" .\" toc@\f3x_open(5)\f1@@@pointer to manual entry for X/Open Conformance Statement Questionnaire .\" .\" links@x_open.5 X_Open.5 .\" $Header: x_open_800.5,v 76.1 95/07/24 16:11:24 ssa Exp $ .nf XXXX////OOOOppppeeeennnn CCCCoooonnnnffffoooorrrrmmmmaaaannnncccceeee SSSSttttaaaatttteeeemmmmeeeennnntttt QQQQuuuueeeessssttttiiiioooonnnnnnnnaaaaiiiirrrreeee TTTTyyyyppppeeee:::: XXXXPPPPGGGG4444 CCCCoooommmmppppoooonnnneeeennnntttt CCCCoooommmmppppoooonnnneeeennnntttt NNNNaaaammmmeeee:::: XXXXPPPPGGGG4444 CCCCoooommmmmmmmaaaannnnddddssss aaaannnndddd UUUUttttiiiilllliiiittttiiiieeeessss Completed by: Tom Shem, Hewlett-Packard Company _________________________________________ (name and organisation) on: Oct 13, 1994 _________________________________________ (date) _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 1. CCCCoooommmmmmmmaaaannnnddddssss aaaannnndddd UUUUttttiiiilllliiiittttiiiieeeessss PPPPrrrroooodddduuuucccctttt IIIIddddeeeennnnttttiiiiffffiiiiccccaaaattttiiiioooonnnn Product Identification HP-UX 9000 Operating System _________________________________________ Version/Release No. HP-UX 10.X for the Series 800 _________________________________________ If you do not supply this component yourself, please identify below the supplier you reference: IIIInnnnddddiiiiccccaaaattttoooorrrr ooooffff CCCCoooommmmpppplllliiiiaaaannnncccceeee None defined for this component. EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt SSSSppppeeeecccciiiiffffiiiiccccaaaattttiiiioooonnnn a. Testing Environment: o+ HP-UX 10.X Operating System o+ HP 9000 Series 800 b. Binary-compatible Family: HP 9000 Series 800 computers (all models). c. The environment contains an XPG4 branded Internationalised System Calls and Libraries component. TTTTeeeemmmmppppoooorrrraaaarrrryyyy WWWWaaaaiiiivvvveeeerrrrssss None. 2 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 2. CCCChhhhooooiiiicccceeee ooooffff CCCCoooonnnnffffoooorrrrmmmmaaaannnncccceeee SSSSppppeeeecccciiiiffffiiiiccccaaaattttiiiioooonnnn Question 1: Which specification are you using as a basis for listing any deviant behaviour of the product? Response: This Conformance Statement lists, in the chapter entitled CCCCoooommmmmmmmaaaannnnddddssss aaaannnndddd UUUUttttiiiilllliiiittttiiiieeeessss ---- PPPPOOOOSSSSIIIIXXXX CCCCoooommmmppppaaaattttiiiibbbbiiiilllliiiittttyyyy, all the discrepancies between the product behaviour and that specified in X/Open CAE Specification, Commands and Utilities, Issue 4 (C203) and X/Open CAE Specification, System Interface Definitions, Issue 4 (C204). Rationale: The XPG4 Commands and Utilities Component Definition requires that the discrepancies between product behaviour and either of the two specifications shown above be documented. Reference: Component Definitions, Version 1 (July 1992), Part 2 of X/Open Systems and Branded Products: XPG4, Section 3.2, XPG4 Commands and Utilities. X/Open Conformance Statement Questionnaire 3 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3. CCCCoooommmmmmmmaaaannnnddddssss aaaannnndddd UUUUttttiiiilllliiiittttiiiieeeessss ---- PPPPOOOOSSSSIIIIXXXX CCCCoooommmmppppaaaattttiiiibbbbiiiilllliiiittttyyyy 3.1 BBBBaaaassssiiiicccc UUUUttttiiiilllliiiittttiiiieeeessss 3.1.1 SSSSuuuuppppppppoooorrrrtttteeeedddd CCCCoooommmmmmmmaaaannnnddddssss Question 1: Which of the basic utilities (non-development utilities) defined in X/Open CAE Specification, Commands and Utilities, Issue 4, are not provided with the implementation? Response: All the basic utilities except _p_a_t_c_h and _t_a_l_k are provided. Rationale: This question determines whether or not the implementation provides a command of the name specified in X/Open CAE Specification, Commands and Utilities, Issue 4; it does not attempt to determine whether it supports the semantics of that command. The optional development utilities are excluded from this question and are dealt with in the next section of the questionnaire. Example: The _d_i_s command is not provided. Reference: Component Definitions, Version 1 (July 1992), Part 2 of X/Open Systems and Branded Products: XPG4, Section 3.2, XPG4 Commands and Utilities. 3.1.2 CCCCoooommmmmmmmaaaannnndddd BBBBeeeehhhhaaaavvvviiiioooouuuurrrr Question 2: In what ways do the commands provided by the implementation behave differently from the specifications contained in X/Open CAE Specification, Commands and Utilities, Issue 4? Response: 4 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s _______________________________________________________________________________ Command Behaviour Utility Option Remarks _______________________________________________________________________________ _a_d_m_i_n ----aaaa,,,, ----dddd,,,, ----eeee,,,, ----ffff,,,, Does not support blank-separated ----mmmm,,,, ----rrrr option arguments. Does not support -- as an operand. _______________________________________________________________________________ _a_r ----CCCC,,,, ----TTTT Option not supported. Does not support -- as an operand. _______________________________________________________________________________ _a_t ----tttt Option not supported. ----llll,,,, ----qqqq Option combination not supported. _______________________________________________________________________________ _c_d Does not support -- as an operand. _______________________________________________________________________________ _c_r_o_n_t_a_b ----eeee Option not supported. Does not support -- as an operand. _______________________________________________________________________________ _d_f ----PPPP Option not supported. Does not support -- as an operand. _______________________________________________________________________________ _d_u ----kkkk Option not supported. Does not report non-stat()able files or unreadable directories, nor is the exit status affected by these conditions. _______________________________________________________________________________ _e_x ----cccc,,,, ----ssss Option not supported. Does not support -- as an operand. _______________________________________________________________________________ _h_a_s_h ----rrrr Option not supported. Is not a built-in utility. _______________________________________________________________________________ _f_i_n_d Does not support -- as an operand. _______________________________________________________________________________ _m_a_i_l Does not support -- as an operand. _______________________________________________________________________________ _n_i_c_e ----nnnn Option not supported. _______________________________________________________________________________ _n_l ----bbbb,,,, ----dddd,,,, ----ffff,,,, ----hhhh,,,, Does not support blank-separated ----iiii,,,, ----llll,,,, ----nnnn,,,, ----ssss,,,, option arguments. ----vvvv,,,, ----wwww Does not support -- as an operand. _______________________________________________________________________________ _n_m ----AAAA,,,, ----gggg,,,, ----PPPP,,,, ----tttt Option not supported. Does not support -- as an operand. _______________________________________________________________________________ |8|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7| |8|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7| X/Open Conformance Statement Questionnaire 5 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s _______________________________________________________________________________ Command Behaviour, Continued Utility Option Remarks _______________________________________________________________________________ _n_o_h_u_p Does not support -- as an operand. _______________________________________________________________________________ _p_a_c_k Does not support -- as an operand. _______________________________________________________________________________ _p_a_t_c_h Command not supported. _______________________________________________________________________________ _p_a_x Option not supported. ----oooo _______________________________________________________________________________ _p_r ----cccc Option not supported. _______________________________________________________________________________ _p_s ----gggg,,,, ----pppp,,,, ----tttt,,,, ----uuuu Does not support blank-separated elements in list arguments. Option not supported. ----AAAA,,,, ----GGGG,,,, ----nnnn,,,, ----oooo,,,, ----UUUU _______________________________________________________________________________ _s_t_r_i_n_g_s Does not support -- as an operand. _______________________________________________________________________________ _t_a_l_k Command not supported. _______________________________________________________________________________ _t_i_m_e ----pppp Option not supported. Does not support -- as an operand. _______________________________________________________________________________ _t_s_o_r_t Does not support -- as an operand. _______________________________________________________________________________ _u_n_p_a_c_k Does not support -- as an operand. _______________________________________________________________________________ _v_i Does not support blank-separated option arguments. ----tttt,,,, ----wwww ----cccc Option not supported. Does not support -- as an operand. _______________________________________________________________________________ _w_h_o ----uuuu Forces -T option on. ----TTTT Session ID and remote hostname also shown. (On s700, cnode name instead of hostname). _______________________________________________________________________________ _x_a_r_g_s Option not supported. ----EEEE,,,, ----IIII,,,, ----LLLL Does not support -- as an operand. _______________________________________________________________________________ |8|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7| |8|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7| Rationale: 6 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s This question provides a greater degree of granularity than the previous question, requiring the semantic differences associated with the commands to be specified. Again, the question relates to the basic utilities rather than the development utilities. The question only relates to the semantics of the options specified within X/Open CAE Specification, Commands and Utilities, Issue 4; implementation-specific extensions should not be documented. Reference: Component Definitions, Version 1 (July 1992), Part 2 of X/Open Systems and Branded Products: XPG4, Section 3.2, XPG4 Commands and Utilities. 3.2 DDDDeeeevvvveeeellllooooppppmmmmeeeennnntttt UUUUttttiiiilllliiiittttiiiieeeessss 3.2.1 SSSSuuuuppppppppoooorrrrtttteeeedddd CCCCoooommmmmmmmaaaannnnddddssss Question 3: Which of the development utilities defined in XPG4 are not provided with the implementation? Response: All the development utilities except _d_i_s are provided. Rationale: The development utilities are required to exist on designated DEVELOPMENT systems but may not be present on all XSI-conformant systems. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Section 1.3.2, Development. 3.2.2 CCCCoooommmmmmmmaaaannnndddd BBBBeeeehhhhaaaavvvviiiioooouuuurrrr Question 4: In what ways do the commands provided by the implementation behave differently from the specifications contained in X/Open CAE Specification, Commands and Utilities, Issue 4? X/Open Conformance Statement Questionnaire 7 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s Response: _______________________________________________________________________________ Command Behaviour Utility Option Remarks _______________________________________________________________________________ _c_t_a_g_s Does not tag C typedefs by default. (-t option does this.) _______________________________________________________________________________ _d_i_s Command not supported. _______________________________________________________________________________ _m_4 Does not support blank-separated option arguments. ----DDDD,,,, ----UUUU Does not support -- as an operand. _______________________________________________________________________________ _m_a_k_e Does not support ....PPPPOOOOSSSSIIIIXXXX target. Does not support -- as an operand. _______________________________________________________________________________ _p_r_s Does not support blank-separated option arguments. ----cccc,,,, ----dddd,,,, ----rrrr Does not support -- as an operand. _______________________________________________________________________________ _r_m_d_e_l Does not support -- as an operand. _______________________________________________________________________________ _s_a_c_t Does not support -- as an operand. _______________________________________________________________________________ _s_t_r_i_p Does not support -- as an operand. _______________________________________________________________________________ _u_n_g_e_t Does not support -- as an operand. _______________________________________________________________________________ _v_a_l Does not support -- as an operand. _______________________________________________________________________________ _w_h_a_t Does not support -- as an operand. _______________________________________________________________________________ |7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7| |7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7| Rationale: This question provides a greater degree of granularity than the previous question, requiring the semantic differences associated with the commands to be specified. Again, the question relates to the basic utilities rather than the development utilities. The question only relates to the semantics of the options specified within X/Open CAE Specification, Commands and Utilities, Issue 4; implementation-specific extensions should not be documented. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Section 1.3.2, Development. 8 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.3 FFFFOOOORRRRTTTTRRRRAAAANNNN OOOOppppttttiiiioooonnnn 3.3.1 FFFFOOOORRRRTTTTRRRRAAAANNNN UUUUttttiiiilllliiiittttyyyy Question 5: Is the FORTRAN _f_o_r_t_7_7 utility provided? Response: Yes. Rationale: The _f_o_r_t_7_7 utility is the command level interface to the FORTRAN compiler, which need not be provided. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Section 1.3.3, FORTRAN. 3.3.2 CCCCoooommmmmmmmaaaannnndddd BBBBeeeehhhhaaaavvvviiiioooouuuurrrr Question 6: In what ways does the _f_o_r_t_7_7 utility provided by the implementation behave differently from the specification contained in X/Open CAE Specification, Commands and Utilities, Issue 4? _R_e_s_p_o_n_s_e: Option Remarks _____________________________ _-_O_n An optimization level cannot be specified using this option. Use the +_O_n option instead. See _f_o_r_t_7_7(1) in the _H_P-_U_X _R_e_f_e_r_e_n_c_e. _R_a_t_i_o_n_a_l_e_: X/Open Conformance Statement Questionnaire 9 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s This question provides a greater degree of granularity than the previous question, requiring the semantic differences associated with the command to be specified. Again, the question relates to the basic utilities rather than the development utilities. The question only relates to the semantics of the options specified within X/Open CAE Specification, Commands and Utilities, Issue 4; implementation-specific extensions should not be documented. _R_e_f_e_r_e_n_c_e_: X/Open CAE Specification, Commands and Utilities, Issue 4, Section 1.3.3, FORTRAN. _3_._4 PPPPoooossssssssiiiibbbbllllyyyy UUUUnnnnssssuuuuppppppppoooorrrrttttaaaabbbblllleeee UUUUttttiiiilllliiiittttiiiieeeessss aaaannnndddd OOOOppppttttiiiioooonnnnssss Question 7: Which of the following utilities and utility options are not supported on the implementation? _R_e_s_p_o_n_s_e: Utility Option Supported ____________________________ _a_r ----ssss Supported _c_a_n_c_e_l Supported _c_u Supported _l_p ----mmmm Supported _l_p ----oooo Supported _l_p ----tttt Supported _l_p ----wwww Supported _l_p_s_t_a_t Supported _s_o_r_t ----zzzz Supported _t_a_b_s ++++mmmm Supported _u_u_c_p Supported _u_u_l_o_g Supported _u_u_n_a_m_e Supported _u_u_p_i_c_k Supported _u_u_s_t_a_t Supported _u_u_t_o Supported _u_u_x Supported _R_a_t_i_o_n_a_l_e_: A number of utilities and utility options are marked as possibly unsupportable features, and the functionality associated with these need not be present in a conforming implementation. _R_e_f_e_r_e_n_c_e_: 10 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s X/Open CAE Specification, Commands and Utilities, Issue 4, Section 1.7, Portability. _3_._5 SSSSppppeeeecccciiiiffffiiiicccc CCCCoooommmmmmmmaaaannnnddddssss aaaannnndddd UUUUttttiiiilllliiiittttiiiieeeessss 3.5.1 aaaatttt Question 8: How does the _a_t command interpret a non-null _S_H_E_L_L environment variable? Response: Uses _s_h irrespective of the setting of _S_H_E_L_L. Rationale: The interpretation of the _S_H_E_L_L environment variable can cause _a_t to invoke different versions of the shell on some implementations. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _a_t, ENVIRONMENT VARIABLES, _S_H_E_L_L. 3.5.2 aaaawwwwkkkk Question 9: What is the limit on the number of open streams provided by _a_w_k? Response: 60 open streams. Rationale: The number of open streams that are available to _a_w_k may differ between implementations, possibly depending on the number of streams that are available to a process ({FOPEN_MAX}). Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _a_w_k, Input/Output and General Functions, close(). X/Open Conformance Statement Questionnaire 11 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.3 bbbbaaaattttcccchhhh Question 10: How does the _b_a_t_c_h command interpret a non-null _S_H_E_L_L environment variable? Response: Uses _s_h irrespective of the setting of _S_H_E_L_L. Rationale: The interpretation of the _S_H_E_L_L environment variable can cause _b_a_t_c_h to invoke different versions of the shell on some implementations. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _b_a_t_c_h, ENVIRONMENT VARIABLES, _S_H_E_L_L. 3.5.4 cccc88889999 Question 11: Which defined names are automatically provided by the compiler? Response: Series 700 Series 800 _______________________________________ __DATE__ __DATE__ __FILE__ __FILE__ __LINE__ __LINE__ __STDC__ __STDC__ __TIME__ __TIME__ __PA_RISC1_1 (opt) __PA_RISC1_1 (opt) __hp9000s700 __hp9000s800 __hp9000s800 __hppa __hppa __hpux __hpux __unix __unix Rationale: The automatic provision of defined names by the compiler can cause these names to be unavailable in the name space for defined names. 12 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _c_8_9, OPTIONS, -D. X/Open Conformance Statement Questionnaire 13 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s Question 12: When multiple input files are specified, where does _c_8_9 direct identification messages designating the start of each input file processing? Response: Standard output. Rationale: These messages, if produced, must be written to one or the other of standard output and standard error, but not to both. The destination of these messages is useful in determining redirections that are necessary to identify the input files from which warning messages are generated. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _c_8_9, STDOUT and STDERR. Question 13: What are the limits associated with external symbols imposed by _c_8_9? Response: Minimum Implementation Description Maximum Maximum _______________________________________________________________________________ Number of significant bytes 31 255 Number of source or object files 511 variable; see _c_8_9(1) in the _H_P-_U_X _R_e_f_e_r_e_n_c_e Total number of external symbols 4095 dependent upon available system resources Rationale: These limits vary between implementations and cannot be reset by the user. The XCU definition gives the minimum maximum value for each of the values. Some applications may require larger limits than these minimum maxima. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _c_8_9, EXTENDED DESCRIPTION, External Symbols. 14 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.5 ccccaaaannnncccceeeellll Question 14: Is the submitter of an _l_p job notified when the job is cancelled by someone else? Response: Yes. Rationale: It is useful for the submitter of a job to be notified of its cancellation, rather than having to interrogate the line printer queue to obtain this information. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _c_a_n_c_e_l, ENVIRONMENT VARIABLES, _L_A_N_G. 3.5.6 ccccpppp Question 15: What is the effect of alternate access control mechanisms on file copies? Response: If the target is a new file or directory, it inherits the Access Control List of the original file, altered to reflect any difference in ownership. See _a_c_l(5) in the _H_P-_U_X _R_e_f_e_r_e_n_c_e. Rationale: Because of the additional restrictions on creating files and reading data from files, the _c_p utility may not behave as described when alternate access control mechanisms are in use. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _c_p, DESCRIPTION, final paragraph. X/Open Conformance Statement Questionnaire 15 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.7 ddddaaaatttteeee Question 16: Does _d_a_t_e permit the setting of the date and time? Response: Yes. Rationale: Some systems, particularly those that are hosted as part of a total system environment, do not allow the _d_a_t_e command to set the date. On such systems, the setting of the date can only be accomplished from the host environment. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _d_a_t_e, OPERANDS, mmddhhmm[yy]. 3.5.8 eeeexxxx Question 17: What restrictions are imposed on the set of commands within the _r_h_s of the _m_a_p command? Response: 1. The maximum number of characters in the _r_h_s is limited to 240. 2. Tail recursion is not allowed. Rationale: Implementations may impose restrictions on the commands that can be used by macros in visual mode. Reference: X/Open CAE Specifications, Commands and Utilities, Issue 4, Chapter 3, Utilities, _e_x, EXTENDED DESCRIPTION, Command Descriptions in ex, Map. 16 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.9 ffffcccc Question 18: Is the history list mechanism disabled for users with appropriate privileges who do not set _H_I_S_T_F_I_L_E? Response: No. Rationale: XPG4 states that an implementation may, in certain circumstances, disable the history list mechanism for users with appropriate privileges who do not set _H_I_S_T_F_I_L_E. This could have some security implications. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _f_c, ENVIRONMENT VARIABLES, _H_I_S_T_F_I_L_E. 3.5.10 ffffoooorrrrtttt77777777 Question 19: When multiple input files are specified, where does _f_o_r_t_7_7 direct identification messages designating the start of each input file processing? Response: Standard error. Rationale: These messages, if produced, must be written to one or the other of standard output and standard error, but not to both. The destination of these messages is useful in determining redirections that are necessary to identify the input files from which warning messages are generated. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _f_o_r_t_7_7, STDERR. X/Open Conformance Statement Questionnaire 17 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s Question 20: What are the limits associated with external symbols imposed by _f_o_r_t_7_7? Response: Minimum Implementation Description Maximum Maximum _______________________________________________________________________________ Number of significant bytes 31 255 Number of source or object files 511 variable; see _f_o_r_t_7_7(1) in the _H_P-_U_X _R_e_f_e_r_e_n_c_e Total number of external symbols 4095 dependent upon available system resources Rationale: These limits vary between implementations and cannot be reset by the user. The XCU definition gives the minimum maximum value for each of the values. Some applications may require larger limits than these minimum maxima. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _f_o_r_t_7_7, EXTENDED DESCRIPTION, External Symbols. 3.5.11 lllleeeexxxx Question 21: Where are error messages sent when the _l_e_x ----tttt ooooppppttttiiiioooonnnn iiiissss nnnnooootttt ssssppppeeeecccciiiiffffiiiieeeedddd???? Response: Standard error. Rationale: These messages can be directed to either standard output or standard error according to XPG4, though the messages are not allowed to be directed to both. An application may wish to redirect these messages to a file. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _l_e_x, STDOUT. 18 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.12 llllnnnn Question 22: Can _l_n create links to a directory? Response: Yes. Rationale: Implementations may disallow the creation of hard links to a directory, even though the executing process has the appropriate privileges. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _l_n, OPERANDS, _s_o_u_r_c_e__f_i_l_e. 3.5.13 llllooooccccaaaalllleeeeddddeeeeffff Question 23: What is the default character mapping used when the _l_o_c_a_l_e_d_e_f ----ffff ooooppppttttiiiioooonnnn iiiissss nnnnooootttt ssssppppeeeecccciiiiffffiiiieeeedddd???? Response: ASCII. Rationale: XPG4 does not define a specific character mapping as the default for conforming systems. This character mapping provides encoding information for the members of the portable character set required by XPG4. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _l_o_c_a_l_e_d_e_f, OPTIONS, -f. X/Open Conformance Statement Questionnaire 19 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.14 llllpppp Question 24: What _l_p option or operator command is used to suppress the printing of a banner page? Response: ----oooo nnnnbbbb Rationale: The user may require that banner pages are suppressed in cases where pre-printed forms are used and the stationary is of a non-standard length. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _l_p, DESCRIPTION. 3.5.15 llllssss Question 25: How many bytes are in a block as reported by _l_s? Response: 512 bytes in a block. Rationale: The block size used by _l_s to report the number of blocks occupied by a file varies from system to system; often this depends on the underlying file system architecture. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _l_s, OPTIONS, -s. 20 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.16 mmmmaaaakkkkeeee Question 26: What additional variables does _m_a_k_e add to its environment? Response: None. Rationale: The implementation of _m_a_k_e may set certain environment variables on invocation of _m_a_k_e. These variables may not be set by the user, thus reducing the name space for environment variables. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _m_a_k_e, EXTENDED DESCRIPTION, Makefile Execution. Question 27: Does the default _M_A_K_E_F_L_A_G_S environment variable contain additional implementation-dependent options? Response: The default _M_A_K_E_F_L_A_G_S environment variable has the value ----bbbb. Rationale: The implementation of _m_a_k_e may set certain default _M_A_K_E_F_L_A_G_S options on invocation of _m_a_k_e. These variables are in addition to those set by the user on the command line and could affect the processing of _m_a_k_e. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _m_a_k_e, EXTENDED DESCRIPTION, Makefile Execution. X/Open Conformance Statement Questionnaire 21 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.17 nnnneeeewwwwggggrrrrpppp Question 28: Does _n_e_w_g_r_p allow users who are not listed as a member of a group which has no password to change to that group? Response: No. Rationale: On some implementations, a user who is not listed as a member of a group may change to that group in the case that there is no password associated with the group. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _n_e_w_g_r_p, DESCRIPTION. Question 29: Are there any other implementation-specific authorisation restrictions that affect _n_e_w_g_r_p? Response: No. Rationale: Some implementations may impose accounting or other restrictions that could cause _n_e_w_g_r_p to deny activity to a group member. For example, a resource quota system could be implemented on a group basis that would limit the ability to join a group until the resources were available to the group. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _n_e_w_g_r_p, DESCRIPTION. 22 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.18 nnnniiiicccceeee aaaannnndddd rrrreeeennnniiiicccceeee Question 30: What are the limits and default values used by _n_i_c_e and _r_e_n_i_c_e? Response: Maximum _n_i_c_e value is 19. Minimum _n_i_c_e value is 1. Default _n_i_c_e increment is 10. Rationale: Each of these values differs between implementations and the range of values gives the user some control over the relative priority of processes. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _n_i_c_e, DESCRIPTION. 3.5.19 ppppaaaaxxxx Question 31: What is the default archive format used by _p_a_x? Response: Extended _t_a_r. Rationale: The implementation has the choice as to which format it shall use as the default when it is creating files. When it is reading an archive created in either extended _t_a_r or extended _c_p_i_o format (or any other format that it understands), the _p_a_x utility will read the archive in the format as written. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _p_a_x, DESCRIPTION. X/Open Conformance Statement Questionnaire 23 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s Question 32: How does _p_a_x handle reading and writing of archives that span multiple files? Response: When end of archive medium is detected, _p_a_x prompts the user for the next volume of the archive, and allows the user to specify the location of the next volume. Rationale: In many cases _p_a_x will take actions, such as prompting the user for the device name to use for the next archive file, when the current archive file is full. There may be extensions to the syntax of _p_a_x which allow the user to specify the address to use to access subsequent files. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _p_a_x, DESCRIPTION. Question 33: How does _p_a_x handle invalid filenames when it is extracting files from an archive? Response: _p_a_x issues the error message: "Bad ASCII pathname". The file is not extracted. Rationale: An implementation may either extract the data associated with these files into files named in an implementation-defined manner or may issue an error indicating that the file is being ignored. If _p_a_x extracts the file, it is necessary for the user either to be informed of the file that is used or to know the algorithm that _p_a_x uses in generating these filenames. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _p_a_x, EXTENDED DESCRIPTION, The cpio Filename. 24 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.20 pppprrrriiiinnnnttttffff Question 34: Does _p_r_i_n_t_f support the e, E, f, g and G floating point conversion specifications? Response: Yes. Rationale: The support of these conversions is not required on an XCU conforming system. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _p_r_i_n_t_f, EXAMPLES. 3.5.21 sssshhhh Question 35: Is the environment variable _I_F_S ignored when the shell is invoked? Response: Yes. Rationale: The XCU definition allows that the _s_h command ignore the setting of the _I_F_S environment variable on invocation. The setting of this variable has been used to breach security on systems which use the shell to interpret a call to the _s_y_s_t_e_m() and _e_x_e_c_v_p() interfaces. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _s_h, ENVIRONMENT VARIABLES, _I_F_S. X/Open Conformance Statement Questionnaire 25 _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s 3.5.22 ttttoooouuuucccchhhh Question 36: What is the latest date after the Epoch that can be used by _t_o_u_c_h? Response: 01:00 18 January, 2038 UTC Rationale: Because of the limitations on the storage of times in the ssssttttaaaatttt structure associated with a file, there is a limitation on the valid dates that can be specified to _t_o_u_c_h. This is directly related to the value that can be stored in the integral type ttttiiiimmmmeeee____tttt. Reference: X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _t_o_u_c_h, OPTIONS, -t. 3.5.23 yyyyaaaacccccccc Question 37: What are the limits of _y_a_c_c's internal tables? Response: Minimum Implementation Description Maximum Maximum _______________________________________________________________________________ Number of tokens 126 2000 Number of non-terminals 200 variable; see _y_a_c_c(1) in the _H_P-_U_X _R_e_f_e_r_e_n_c_e Number of rules 300 dependent upon available system resources Number of states 600 variable; see _y_a_c_c(1) in the _H_P-_U_X _R_e_f_e_r_e_n_c_e Length of rules 5200 dependent upon available system resources Number of actions 4000 variable; see _y_a_c_c(1) in the _H_P-_U_X _R_e_f_e_r_e_n_c_e Rationale: These internal table sizes vary between implementations and cannot be reset by the user. The XCU definition gives the minimum maximum value for each of the table values. Reference: 26 X/Open Conformance Statement Questionnaire _X_P_G_4 _C_o_m_m_a_n_d_s _a_n_d _U_t_i_l_i_t_i_e_s X/Open CAE Specification, Commands and Utilities, Issue 4, Chapter 3, Utilities, _y_a_c_c, EXTENDED DESCRIPTION, Limits. XXXX////OOOOppppeeeennnn CCCCoooonnnnffffoooorrrrmmmmaaaannnncccceeee SSSSttttaaaatttteeeemmmmeeeennnntttt QQQQuuuueeeessssttttiiiioooonnnnnnnnaaaaiiiirrrreeee TTTTyyyyppppeeee:::: XXXXPPPPGGGG4444 PPPPrrrrooooffffiiiilllleeee PPPPrrrrooooffffiiiilllleeee NNNNaaaammmmeeee:::: XXXXPPPPGGGG4444 BBBBaaaasssseeee Completed by: Tom Shem, Hewlett-Packard Company _________________________________________ (name and organisation) on: Oct 6, 1994 _________________________________________ (date) _X_P_G_4 _B_a_s_e 4. XXXXPPPPGGGG4444 BBBBaaaasssseeee PPPPrrrroooodddduuuucccctttt IIIIddddeeeennnnttttiiiiffffiiiiccccaaaattttiiiioooonnnn Product Identification HP-UX Operating System _________________________________________ Version/Release No. HP-UX 10.X for the Series 800 _________________________________________ If you do not supply this product yourself, please identify below the supplier you reference: Product Identification HP-UX ANSI C Compiler _________________________________________ Version/Release No. Version A.10.00, HP-UX Release 10.0 _________________________________________ If you do not supply this product yourself, please identify below the supplier you reference: EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt SSSSppppeeeecccciiiiffffiiiiccccaaaattttiiiioooonnnn a. Binary-compatible Family: HP 9000 Series 800 (all models) b. Special instructions for configuring the Product(s) to meet the Conformance Requirements of this profile: None. 28 X/Open Conformance Statement Questionnaire _X_P_G_4 _B_a_s_e TTTTeeeemmmmppppoooorrrraaaarrrryyyy WWWWaaaaiiiivvvveeeerrrrssss Waiver Number Expiry Date ___________________________ 4.1 CCCCoooommmmppppoooonnnneeeennnnttttssss Completed CSQs for all the following XPG4 components are attached. 4.1.1 XXXXPPPPGGGG4444 IIIInnnntttteeeerrrrnnnnaaaattttiiiioooonnnnaaaalllliiiisssseeeedddd SSSSyyyysssstttteeeemmmm CCCCaaaallllllllssss aaaannnndddd LLLLiiiibbbbrrrraaaarrrriiiieeeessss 4.1.2 XXXXPPPPGGGG4444 CCCCoooommmmmmmmaaaannnnddddssss aaaannnndddd UUUUttttiiiilllliiiittttiiiieeeessss 4.1.3 XXXXPPPPGGGG4444 CCCC LLLLaaaannnngggguuuuaaaaggggeeee XXXX////OOOOppppeeeennnn CCCCoooonnnnffffoooorrrrmmmmaaaannnncccceeee SSSSttttaaaatttteeeemmmmeeeennnntttt QQQQuuuueeeessssttttiiiioooonnnnnnnnaaaaiiiirrrreeee TTTTyyyyppppeeee:::: XXXXPPPPGGGG4444 CCCCoooommmmppppoooonnnneeeennnntttt CCCCoooommmmppppoooonnnneeeennnntttt NNNNaaaammmmeeee:::: XXXXPPPPGGGG4444 IIIInnnntttteeeerrrrnnnnaaaattttiiiioooonnnnaaaalllliiiisssseeeedddd SSSSyyyysssstttteeeemmmm CCCCaaaallllllllssss aaaannnndddd LLLLiiiibbbbrrrraaaarrrriiiieeeessss _X_P_G_4 _B_a_s_e Completed by: Tom Shem, Hewlett-Packard Company _________________________________________ (name and organisation) on: Oct 6, 1994 _________________________________________ (date) 30 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s 5. IIIInnnntttteeeerrrrnnnnaaaattttiiiioooonnnnaaaalllliiiisssseeeedddd SSSSyyyysssstttteeeemmmm CCCCaaaallllllllssss aaaannnndddd LLLLiiiibbbbrrrraaaarrrriiiieeeessss PPPPrrrroooodddduuuucccctttt IIIIddddeeeennnnttttiiiiffffiiiiccccaaaattttiiiioooonnnn Product Identification HP-UX Operating System _________________________________________ Version/Release No. HP-UX 10.X for the Series 800 _________________________________________ If you do not supply this component yourself, please identify below the supplier you reference: IIIInnnnddddiiiiccccaaaattttoooorrrr ooooffff CCCCoooommmmpppplllliiiiaaaannnncccceeee Test report from VSX4. Test suite release number 4.3.2 Test report reference number EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt SSSSppppeeeecccciiiiffffiiiiccccaaaattttiiiioooonnnn a. Testing Environment: o+ HP 9000 Series 800. Standalone only. o+ Sufficient disk space for the tests to have at least 80Mb free on a single volume or partition. o+ Loopback cable: TX -RX RX -TX DCD-DTR DTR-DCD GND-GND o+ Mountable empty drive or partition. o+ All tests were run self-hosted on the machine being tested. X/Open Conformance Statement Questionnaire 31 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s o+ Compiler options used: ----AAAAaaaa ----DDDD____XXXXPPPPGGGG4444 ----llllMMMM o+ Due to security enhancements and a new file system, links must be created: llllnnnn ----ssss ////uuuussssrrrr////bbbbiiiinnnn////kkkksssshhhh ////bbbbiiiinnnn////kkkksssshhhh llllnnnn ----ssss ////uuuussssrrrr////bbbbiiiinnnn////sssshhhh ////bbbbiiiinnnn////sssshhhh llllnnnn ----ssss ////uuuussssrrrr////bbbbiiiinnnn////ccccsssshhhh ////bbbbiiiinnnn////ccccsssshhhh llllnnnn ----ssss ////uuuussssrrrr////bbbbiiiinnnn////rrrrmmmm ////bbbbiiiinnnn////rrrrmmmm llllnnnn ----ssss ////uuuussssrrrr////bbbbiiiinnnn////llllssss ////bbbbiiiinnnn////llllssss llllnnnn ----ssss ////uuuussssrrrr////ccccccccssss////bbbbiiiinnnn////mmmmaaaakkkkeeee ////bbbbiiiinnnn////mmmmaaaakkkkeeee llllnnnn ----ssss ////uuuussssrrrr////ccccccccssss////bbbbiiiinnnn////aaaarrrr ////bbbbiiiinnnn////aaaarrrr llllnnnn ----ssss ////oooopppptttt////aaaannnnssssiiiicccc////bbbbiiiinnnn////cccc88889999 ////bbbbiiiinnnn////cccccccc llllnnnn ----ssss ////oooopppptttt////aaaannnnssssiiiicccc////bbbbiiiinnnn////cccc88889999 ////bbbbiiiinnnn////cccc88889999 llllnnnn ----ssss ////oooopppptttt////aaaannnnssssiiiicccc////bbbbiiiinnnn////cccc88889999 ////uuuussssrrrr////ccccccccssss////bbbbiiiinnnn////cccc88889999 llllnnnn ----ssss ////uuuussssrrrr////ssssbbbbiiiinnnn////rrrreeeennnniiiicccceeee ////uuuussssrrrr////bbbbiiiinnnn////rrrreeeennnniiiicccceeee llllnnnn ----ssss ////uuuussssrrrr////ssssbbbbiiiinnnn////mmmmoooouuuunnnntttt ////eeeettttcccc////mmmmoooouuuunnnntttt llllnnnn ----ssss ////uuuussssrrrr////ssssbbbbiiiinnnn////uuuummmmoooouuuunnnntttt ////eeeettttcccc////uuuummmmoooouuuunnnntttt llllnnnn ----ssss ////vvvvaaaarrrr////ttttmmmmpppp ////uuuussssrrrr////ttttmmmmpppp llllnnnn ----ssss ////eeeettttcccc////ggggrrrroooouuuupppp ////eeeettttcccc////llllooooggggiiiinnnnggggrrrroooouuuupppp o+ If you wish to test the system with {_POSIX_CHOWN_RESTRICTED} enabled, enter (as superuser) the command: sssseeeettttpppprrrriiiivvvvggggrrrrpppp ----nnnn CCCCHHHHOOOOWWWWNNNN to disable it, use sssseeeettttpppprrrriiiivvvvggggrrrrpppp ----gggg CCCCHHHHOOOOWWWWNNNN The formal branding run was done with {_POSIX_CHOWN_RESTRICTED} enabled. If you wish to test the system with {_POSIX_NO_TRUNC} enabled, do not run the test suite on a file system set up for short file names. The formal branding run was done on a file system with long file names, so {_POSIX_NO_TRUNC} is enabled. b. Binary-compatible Family: HP 9000 Series 800 (all models) 32 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s TTTTeeeemmmmppppoooorrrraaaarrrryyyy WWWWaaaaiiiivvvveeeerrrrssss None. 5.1 GGGGeeeennnneeeerrrraaaallll AAAAttttttttrrrriiiibbbbuuuutttteeeessss 5.1.1 XXXXPPPPGGGG4444 FFFFeeeeaaaattttuuuurrrreeee GGGGrrrroooouuuuppppssss Question 1: Which of the following Feature Groups are supported by the implementation? Response: POSIX.2 C-language Binding YES Shared Memory YES Encryption YES Enhanced Internationalisation YES Note: All the interfaces in all these groups must exist on all XPG4 XSI-conformant systems, and each interface must either behave according to the description in System Interfaces and Headers, Issue 4, or indicate an error, with _e_r_r_n_o set to [ENOSYS]. Support for particular Feature Groups may be required in order to conform to particular X/Open Profiles. Support for a Feature Group can only be claimed if _a_l_l interfaces in that group behave according to the relevant descriptions in System Interfaces and Headers, Issue 4. Rationale: System Interfaces and Headers, Issue 4 states that the system may provide one or more of the Feature Groups listed. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Section 1.2, Conformance and Section 1.3, Feature Groups. X/Open Conformance Statement Questionnaire 33 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s 5.1.2 PPPPOOOOSSSSIIIIXXXX....1111 SSSSuuuuppppppppoooorrrrtttteeeedddd FFFFeeeeaaaattttuuuurrrreeeessss Question 2: Which of the following options, specified in the <<<>>> header file, are available on the system? Response: Macro Name Meaning Provided ______________________________________________________________ _POSIX_CHOWN_RESTRICTED Variable The use of _c_h_o_w_n() is restricted to a process with appropriate privileges, and to changing the group ID of a file only to the effective group ID of the process or one of its supplementary group IDs. _POSIX_NO_TRUNC Variable Pathname components longer than {NAME_MAX) generate an error. _POSIX_VDISABLE Yes Terminal special characters defined in <<<>>> can be disabled using this character value. _POSIX_SAVED_IDS Yes Each process has a saved set-user-ID and a saved set-group-ID. _POSIX_JOB_CONTROL Yes Implementation supports job control. The variable {{{{____PPPPOOOOSSSSIIIIXXXX____CCCCHHHHOOOOWWWWNNNN____RRRREEEESSSSTTTTRRRRIIIICCCCTTTTEEEEDDDD}}}} is enabled for each process for which its effective group ID or one of its supplementary group IDs has the CHOWN privilege. This is manipulated with the sssseeeettttpppprrrriiiivvvvggggrrrrpppp(1M) utility, as described in the Testing Environment section above. The variable {{{{____PPPPOOOOSSSSIIIIXXXX____NNNNOOOO____TTTTRRRRUUUUNNNNCCCC}}}} is enabled for each path that resides (or would reside) on a long file name file system, and disabled for other paths. All file systems shipped with the HP-UX product are long name file systems. Short name file systems can be created with the nnnneeeewwwwffffssss(1M) utility, and converted to long name file systems with the ccccoooonnnnvvvveeeerrrrttttffffssss(1M) utility. Rationale: 34 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s For an XSI-conformant implementation, all of these POSIX features must be provided. In some cases the feature need not be provided for all files or devices supported by the implementation. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 4, Headers, <<<>>>. X/Open Conformance Statement Questionnaire 35 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s 5.1.3 FFFFllllooooaaaatttt,,,, SSSSttttddddiiiioooo aaaannnndddd LLLLiiiimmmmiiiitttt VVVVaaaalllluuuueeeessss Question 3: What are the values associated with the following constants specified in the <<<>>> header file? Response: Macro Name Meaning Value __________________________________________________________________________ FLT_RADIX Radix of the exponent representation. 2 FLT_MANT_DIG 24 Number of base-FLT_RADIX digits in the float significand. DBL_MANT_DIG 53 Number of base-FLT_RADIX digits in the double significand. LDBL_MANT_DIG 113 Number of base-FLT_RADIX digits in the long double significand. FLT_DIG 6 Number of decimal digits, _q, such that any floating point number with _q digits can be rounded into a float representation and back again without change to the _q digits. DBL_DIG 15 Number of decimal digits, _q, such that any floating point number with _q digits can be rounded into a double representation and back again without change to the _q digits. LDBL_DIG 33 Number of decimal digits, _q, such that any floating point number with _q digits can be rounded into a long double representation and back again without change to the _q digits. FLT_MIN_EXP -125 Minimum negative integer such that FLT_RADIX raised to that power minus 1 is a normalised float. DBL_MIN_EXP -1021 Minimum negative integer such that FLT_RADIX raised to that power minus 1 is a normalised double. LDBL_MIN_EXP -16381 Minimum negative integer such that FLT_RADIX raised to that power minus 1 is a normalised long double. FLT_MIN_10_EXP -37 Minimum negative integer such that 10 raised to that power is in the range of normalised floats. DBL_MIN_10_EXP -307 Minimum negative integer such that 10 raised to that power is in the range of normalised doubles. LDBL_MIN_10_EXP -4931 Minimum negative integer such that 10 raised to that power is in the range of normalised long doubles. 36 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Macro Name Meaning Value __________________________________________________________________________ FLT_MAX_EXP 128 Maximum integer such that FLT_RADIX raised to that power minus 1 is a representable finite float. DBL_MAX_EXP 1024 Maximum integer such that FLT_RADIX raised to that power minus 1 is a representable finite double. LDBL_MAX_EXP 16384 Maximum integer such that FLT_RADIX raised to that power minus 1 is a representable finite long double. FLT_MAX_10_EXP 38 Maximum integer such that 10 raised to that power is in the range of representable finite floats. DBL_MAX_10_EXP 308 Maximum integer such that 10 raised to that power is in the range of representable finite doubles. LDBL_MAX_10_EXP 4932 Maximum integer such that 10 raised to that power is in the range of representable finite long doubles. FLT_MAX Maximum representable finite float. 3.40282347E+38 DBL_MAX Maximum representable finite double. 1.797 ... E+308 LDBL_MAX Maximum representable finite long double. 1.189 ... E4932 FLT_EPSILON 1.19209290E-07 Difference between 1.0 and the least value greater than 1.0 that is representable as a float. DBL_EPSILON 2.220 ... E-16 Difference between 1.0 and the least value greater than 1.0 that is representable as a double. LDBL_EPSILON 1.925 ... E-34 Difference between 1.0 and the least value greater than 1.0 that is representable as a long double. FLT_MIN Minimum normalised positive float. 1.17549435E-38 DBL_MIN Minimum normalised positive double. 2.225 ... E-308 LDBL_MIN Minimum normalised positive long double. 3.362 ... E-4932 Rationale: This set of constants provides useful information regarding the underlying architecture of the implementation. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 4, Headers, <<<>>>. X/Open Conformance Statement Questionnaire 37 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Question 4: What are the values associated with the following constants (optionally specified in the <<<>>> header file)? Response: Macro Name Meaning Minimum Maximum _______________________________________________________________ ARG_MAX 20478 Indeterminate Maximum length of argument to the _e_x_e_c functions including the environment data. CHILD_MAX 25 Indeterminate Maximum number of processes per user ID. LINK_MAX 32767 32767 Maximum number of links to a single file. MAX_CANON 512 512 Maximum number of bytes in a terminal canonical input line. NAME_MAX 14 255 Maximum number of bytes allowed in a terimnal input queue. OPEN_MAX 60 1024 Maximum number of open files that one process can have open at any one time. PATH_MAX 1023 1023 Maximum number of bytes in a pathname (including the terminating null). PIPE_BUF 8192 8192 Maximum number of bytes that is guaranteed to be atomic when writing to a pipe. STREAM_MAX 60 1024 Number of streams that one process can have open at one time. TZNAME_MAX 19 19 Maximum number of bytes supported for the name of a time zone. Rationale: Each of these limits can vary within bounds set by System Interfaces and Headers, Issue 4. The minimum value that a limit can take on any XSI conforming system is given in the corresponding _POSIX_ value. A specific conforming implementation may provide a higher minimum value than this and the maximum value that it provides can differ from the minimum. Some conforming implementations may provide a potentially infinite value as the maximum, in which case the value is considered to be indeterminate. The minimum value must always be definitive since the _POSIX_ value provides a known lower bound for the range of possible values. 38 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 4, Headers, <<<>>>. X/Open Conformance Statement Questionnaire 39 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Question 5: What are the values associated with the following constants specified in the <<<>>> header file? Response: Macro Name Meaning Minimum Maximum _______________________________________________________________ BC_BASE_MAX 99 99 Maximum _i_b_a_s_e and _o_b_a_s_e values allowed by the _b_c utility. BC_DIM_MAX 2048 2048 Maximum number of elements permitted in an array by the _b_c utility. BC_SCALE_MAX 99 99 Maximum scale value allowed by the _b_c utility. BC_STRING_MAX 1000 1000 Maximum length of a string constant accepted by the _b_c utility. COLL_WEIGHTS_MAX 4 4 Maximum number of weights that can be assigned to an entry of the LC_COLLATE order keyword in the locale definition file. EXPR_NEST_MAX 32 32 Maximum number of expressions that can be nested within parentheses by the expr utility. LINE_MAX 2048 2048 Maximum length in bytes including the trailing newline of a utility's input line when the utility is described as processing text files. NGROUPS_MAX 20 20 Maximum number of simultaneous supplementary group IDs per process. RE_DUP_MAX 255 255 Maximum number of repeated occurrences of a regular expression permited when using interval notation. Rationale: 40 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Each of these limits can vary within bounds set by System Interfaces and Headers, Issue 4. The minimum value that a limit can take on any XSI conforming system is given in the corresponding _POSIX_ or _POSIX2_ value. A specific conforming implementation may provide a higher minimum value than this and the maximum value that it provides can differ from the minimum. Some conforming implementations may provide a potentially infinite value as the maximum, in which case the value is considered to be indeterminate. The minimum value must always be definitive since the _POSIX_ or _POSIX2_ value provides a known lower bound for the range of possible values. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 4, Headers, <<<>>>. X/Open Conformance Statement Questionnaire 41 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Question 6: What are the values associated with the following numerical constants specified in the <<<>>> header file? Response: Macro Name Meaning Value _________________________________________________________________ CHAR_BIT Number of bits in a cccchhhhaaaarrrr. 8 CHAR_MAX Maximum value of a cccchhhhaaaarrrr. 127 INT_MAX Maximum value of an iiiinnnntttt. 2147483647 LONG_BIT Number of bits in a lllloooonnnngggg iiiinnnntttt. 32 LONG_MAX Maximum value of a lllloooonnnngggg iiiinnnntttt. 2147483647 MB_LEN_MAX 4 Maximum number of bytes in a character, for any supported locale. SCHAR_MAX Maximum value of a ssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr. 127 SHRT_MAX Maximum value of a sssshhhhoooorrrrtttt. 32767 SSIZE_MAX Maximum value of an object of type ssssssssiiiizzzzeeee____tttt. 2147483647 UCHAR_MAX Maximum value of an uuuunnnnssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr. 255 UINT_MAX Maximum value of an uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnntttt. 4294967295 ULONG_MAX Maximum value of an uuuunnnnssssiiiiggggnnnneeeedddd lllloooonnnngggg iiiinnnntttt. 4294967295 USHRT_MAX Maximum value of an uuuunnnnssssiiiiggggnnnneeeedddd sssshhhhoooorrrrtttt iiiinnnntttt. 65535 WORD_BIT Number of bits in a word or iiiinnnntttt. 32 Rationale: This set of constants provides useful information regarding the underlying architecture of the implementation. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 4, Headers, <<<>>>. Question 7: What are the values associated with the following numerical constants specified in the <<<>>> header file? Response: 42 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Macro Name Meaning Value _______________________________________________ FOPEN_MAX 60 Number of streams which the implementation guarantees can be open simultaneously. L_tmpnam 25 Maximum size of character array to hold _t_m_p_n_a_m() output. TMP_MAX 17576 Minimum number of unique filenames generated by _t_m_p_n_a_m(), which is the maximum number of times an application can call _t_m_p_n_a_m() reliably. Rationale: This set of constants provide useful information about the implementation. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 4, Headers, <<<>>>. X/Open Conformance Statement Questionnaire 43 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s 5.1.4 EEEErrrrrrrroooorrrr CCCCoooonnnnddddiiiittttiiiioooonnnnssss Question 8: Which of the following option errors listed in System Interfaces and Headers, Issue 4 are detected in the circumstances specified? Response: Function Error Detected ______________________________________________ _a_c_c_e_s_s() EINVAL Yes ETXTBSY Yes _a_c_o_s() EDOM Yes _a_s_i_n() EDOM Yes ERANGE Yes _a_t_a_n() EDOM Yes ERANGE Yes _a_t_a_n_2() EDOM Yes ERANGE Yes _c_a_t_c_l_o_s_e() EBADF Yes EINTR Yes _c_a_t_g_e_t_s() EBADF Yes EINTR Yes _c_a_t_o_p_e_n() EACCES Yes EMFILE Yes ENAMETOOLONG Yes ENFILE Yes ENOENT Yes ENOMEM Yes ENOTDIR Yes _c_e_i_l() EDOM Yes _c_f_s_e_t_i_s_p_e_e_d() EINVAL Yes _c_f_s_e_t_o_s_p_e_e_d() EINVAL Yes _c_h_m_o_d() EINVAL Yes _c_h_o_w_n() EINVAL Yes _c_l_o_s_e_d_i_r() EBADF Yes EINTR Yes _c_o_s() EDOM Yes ERANGE Yes _c_o_s_h() EDOM Yes _e_r_f() EDOM Yes ERANGE Yes _e_r_f_c() EDOM Yes 44 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Function Error Detected ______________________________________________ ERANGE Yes _e_x_e_c ENOMEM Yes ETXTBSY Yes _e_x_p() EDOM Yes ERANGE Yes _f_a_b_s() EDOM Yes ERANGE Yes _f_c_n_t_l() EDEADLK Yes _f_d_o_p_e_n() EBADF Yes EINVAL Yes EMFILE Yes ENOMEM Yes _f_g_e_t_c() ENOMEM Yes ENXIO Yes _f_g_e_t_w_c() ENOMEM Yes ENXIO Yes EILSEQ Yes _f_i_l_e_n_o() EBADF No _f_l_o_o_r() EDOM Yes _f_m_o_d() EDOM Yes ERANGE Yes _f_o_p_e_n() EINVAL Yes EMFILE Yes ENOMEM Yes ETXTBSY Yes _f_o_r_k() ENOMEM Yes _f_p_a_t_h_c_o_n_f() EBADF Yes EINVAL Yes _f_p_r_i_n_t_f() EINVAL No EILSEQ Yes _f_p_u_t_c() ENOMEM Yes ENXIO Yes _f_p_u_t_w_c() ENOMEM Yes ENXIO Yes EILSEQ Yes _f_r_e_o_p_e_n() EINVAL Yes ENOMEM Yes ETXTBSY Yes _f_r_e_x_p() EDOM Yes _f_s_e_e_k() EINVAL Yes X/Open Conformance Statement Questionnaire 45 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Function Error Detected ______________________________________________ EPIPE Yes _f_t_w() EINVAL Yes _g_e_t_c_w_d() EACCES Yes ENOMEM Yes _g_e_t_g_r_g_i_d() EIO Yes EINTR Yes EMFILE Yes ENFILE Yes _g_e_t_g_r_n_a_m() EIO Yes EINTR Yes EMFILE Yes ENFILE Yes _g_e_t_l_o_g_i_n() EMFILE Yes ENFILE Yes ENXIO Yes _g_e_t_p_a_s_s() EINTR Yes EIO Yes EMFILE Yes ENFILE Yes ENXIO Yes _g_e_t_p_w_n_a_m() EIO Yes EINTR Yes EMFILE Yes ENFILE Yes _g_e_t_p_w_u_i_d() EIO Yes EINTR Yes EMFILE Yes _h_s_e_a_r_c_h() ENOMEM Yes _h_y_p_o_t() EDOM Yes ERANGE Yes _i_c_o_n_v() EBADF Yes _i_c_o_n_v___c_l_o_s_e() EBADF Yes _i_c_o_n_v___o_p_e_n() EMFILE Yes ENFILE Yes ENOMEM Yes EINVAL Yes _i_s_a_t_t_y() EBADF Yes ENOTTY Yes _j_0() EDOM Yes ERANGE Yes _j_1() EDOM Yes ERANGE Yes 46 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Function Error Detected ______________________________________________ _j_n() EDOM Yes ERANGE Yes _l_d_e_x_p() EDOM Yes ERANGE Yes _l_g_a_m_m_a() EDOM Yes ERANGE Yes _l_i_n_k() EPERM Yes EXDEV Yes _l_o_g() EDOM Yes ERANGE Yes _l_o_g_1_0() EDOM Yes ERANGE Yes _m_b_l_e_n() EILSEQ Yes _m_b_s_t_o_w_c_s() EILSEQ Yes _m_b_t_o_w_c() EILSEQ Yes _m_o_d_f() EDOM Yes ERANGE Yes _o_p_e_n() EINVAL Yes ETXTBSY Yes _o_p_e_n_d_i_r() EMFILE Yes ENFILE Yes _p_a_t_h_c_o_n_f() EACCES Yes EINVAL Yes ENAMETOOLONG Yes ENOENT Yes ENOTDIR Yes _p_o_w() EDOM Yes ERANGE Yes _p_u_t_e_n_v() ENOMEM Yes _r_e_a_d() ENXIO Yes _r_e_a_d_d_i_r() EBADF Yes _r_e_n_a_m_e() ETXTBSY Yes _s_e_t_v_b_u_f() EBADF No _s_i_g_a_c_t_i_o_n() EINVAL Yes _s_i_g_a_d_d_s_e_t() EINVAL No _s_i_g_d_e_l_s_e_t() EINVAL No _s_i_g_i_s_m_e_m_b_e_r() EINVAL No _s_i_g_n_a_l() EINVAL Yes X/Open Conformance Statement Questionnaire 47 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Function Error Detected ______________________________________________ _s_i_n() EDOM Yes ERANGE Yes _s_i_n_h() EDOM Yes ERANGE Yes _s_q_r_t() EDOM Yes _s_t_r_c_o_l_l() EINVAL No _s_t_r_e_r_r_o_r() EINVAL No _s_t_r_x_f_r_m() EINVAL No _t_a_n() EDOM Yes ERANGE Yes _t_a_n_h() EDOM Yes ERANGE Yes _t_c_d_r_a_i_n() EIO Yes _t_c_f_l_u_s_h() EIO Yes _t_c_s_e_n_d_b_r_e_a_k() EIO Yes _t_c_s_e_t_a_t_t_r() EIO Yes _t_m_p_f_i_l_e() EMFILE Yes ENOMEM Yes _t_t_y_n_a_m_e() EBADF Yes ENOTTY Yes _u_n_g_e_t_w_c() EILSEQ Yes _u_n_l_i_n_k() ETXTBSY Yes _w_c_s_c_o_l_l() EINVAL No _w_c_s_t_o_m_b_s() EILSEQ Yes _w_c_s_x_f_r_m() EINVAL No _w_r_i_t_e() ENXIO Yes _y_0() EDOM Yes ERANGE Yes _y_1() EDOM Yes ERANGE Yes _y_n() EDOM Yes ERANGE Yes Rationale: 48 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Each of the above error conditions is marked as optional in System Interfaces and Headers, Issue 4 and an implementation may return this error in the cirumstances specified or may not provide the error indication. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Section 2.3, Error Numbers. X/Open Conformance Statement Questionnaire 49 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s 5.1.5 MMMMaaaatttthhhheeeemmmmaaaattttiiiiccccaaaallll IIIInnnntttteeeerrrrffffaaaacccceeeessss Question 9: What format of floating-point numbers is supported by this implementation? Response: IEEE floating point format. Rationale: Most implementations support IEEE floating point format either in hardware or software. Some implementations support other formats with different exponent and mantissa accuracy. These differences need to be defined. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Section 1.6, Relationship to Formal Standards. 5.1.6 DDDDaaaattttaaaa EEEEnnnnccccrrrryyyyppppttttiiiioooonnnn Question 10: Are the optional data encryption interfaces provided? Response: Function Provided ____________________ _c_r_y_p_t() Yes _e_n_c_r_y_p_t() No _s_e_t_k_e_y() No The U.S. Department of Defense does not allow "munitions" such as decryption routines to be exported from the U.S. Therefore, encryption functionality is available from _e_n_c_r_y_p_t() and _s_e_t_k_e_y(), but not decryption functionality. U.S. domestic customers may obtain fully capable copies of these routines through their customer support contract. 50 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Rationale: Normally, an implementation will either provide all three of these routines or will provide none of them at all. If the routines are not provided, then the implementation must provide a dummy interface which always raises an ENOSYS error condition. It is also possible that the implementation of the _e_n_c_r_y_p_t() function may be affected by export restrictions, in which case, the restrictions should be documented here. For example, historical implementations have supplied all three of these routines outside the U.S.A., but due to export restrictions on the decoding algorithm, a dummy version of _e_n_c_r_y_p_t() is provided that does encoding but no decoding. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Section 1.2, Conformance. 5.2 PPPPrrrroooocccceeeessssssss HHHHaaaannnnddddlllliiiinnnngggg 5.2.1 PPPPrrrroooocccceeeessssssss GGGGeeeennnneeeerrrraaaattttiiiioooonnnn Question 11: Which file types (regular, directory, FIFO, special, and so on) are considered to be executable? Response: Regular. Rationale: The [EACCES] error associated with _e_x_e_c functions occurs in circumstances when the implementation does not support execution of files of the type specified. A list of these file types needs to be provided. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 3, Functions, _e_x_e_c. X/Open Conformance Statement Questionnaire 51 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s 5.3 FFFFiiiilllleeee HHHHaaaannnnddddlllliiiinnnngggg 5.3.1 AAAAcccccccceeeessssssss CCCCoooonnnnttttrrrroooollll Question 12: What file access control mechanisms does the implementation provide? Response: The operating system supports extended Discretionary Access Control ("need to know" access restrictions and permissions) on files, as an optional superset of user, group, and other mode bits. This has the characteristics of an "additional file access control mechanism". For general information, see the _a_c_l(5) entry in the HP-UX Reference Manual. Rationale: System Interfaces and Headers, Issue 4 notes that implementations may provide _a_d_d_i_t_i_o_n_a_l or _a_l_t_e_r_n_a_t_e file access control mechanisms, or both. Reference: X/Open CAE Specification, System Interface Definitions, Issue 4, Chapter 2, Glossary, file access permissions. 5.3.2 FFFFiiiilllleeeessss aaaannnndddd DDDDiiiirrrreeeeccccttttoooorrrriiiieeeessss Question 13: Are any additional or alternate file access control mechanisms implemented that could cause _f_s_t_a_t() or _s_t_a_t() to fail? Response: No. Rationale: System Interfaces and Headers, Issue 4 notes that there could be an interaction between additional and alternate access controls and the success of _f_s_t_a_t() and _s_t_a_t(). This would suggest that an implementation can allow access to a file but not allow the process to gain information about the status of the file. 52 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 3, Functions, _f_s_t_a_t() and _s_t_a_t(). X/Open Conformance Statement Questionnaire 53 _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s 5.3.3 FFFFoooorrrrmmmmaaaattttttttiiiinnnngggg IIIInnnntttteeeerrrrffffaaaacccceeeessss Question 14: Does the _p_r_i_n_t_f() function produce character string representations for Infinity and NaN to represent the respective values? Response: Yes. It generates the following strings for the indicated values: Value String ____________________ +Infinity ++.000000 -Infinity ---.000000 NaN ?.000000 Rationale: This behaviour is often provided on systems with mathematical functions that produce these results. Reference: X/Open CAE Specification, System Interfaces and Headers, Issue 4, Chapter 3, Functions, _f_p_r_i_n_t_f(). 5.4 IIIInnnntttteeeerrrrnnnnaaaattttiiiioooonnnnaaaalllliiiisssseeeedddd SSSSyyyysssstttteeeemmmm IIIInnnntttteeeerrrrffffaaaacccceeeessss 5.4.1 CCCCooooddddeeeedddd CCCChhhhaaaarrrraaaacccctttteeeerrrr SSSSeeeettttssss Question 15: What coded character sets are supported by the implementation? Response: ISO 8859-1:1987 is supported, and others can be selected by users as their internal coded character set on a per-session basis. However, as not all of them contain the portable character set, HP does not claim "support" for these as XPG4 coded character sets. Rationale: System Interface Definitions, Issue 4 states that conforming implementations support one or more coded character sets, and that each of these includes the portable character set. Reference: 54 X/Open Conformance Statement Questionnaire _X_P_G_4 _I_n_t_e_r_n_a_t_i_o_n_a_l_i_s_e_d _S_y_s_t_e_m _C_a_l_l_s _a_n_d _L_i_b_r_a_r_i_e_s X/Open CAE Specification, System Interface Definitions, Issue 4, Chapter 4, Character Set. Question 16: What is the implementation's underlying internal codeset? Response: Per user-customer selectable option, each user may configure his/her login session to use a selected codeset. ISO 8859-1:1987 is one such codeset. Rationale: It is useful to be aware of the underlying codeset of the implementation. Reference: X/Open CAE Specification, System Interface Definitions, Issue 4, Chapter 4, Character Set. X/Open Conformance Statement Questionnaire 55 .fi .\" .\" links@x_open_800.5 X_Open_800.5 aaaawwwwkkkk((((1111)))) aaaawwwwkkkk((((1111)))) NNNNAAAAMMMMEEEE awk - pattern-directed scanning and processing language SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS aaaawwwwkkkk [----FFFF_f_s] [----vvvv _v_a_r====_v_a_l_u_e] [_p_r_o_g_r_a_m | ----ffff _p_r_o_g_f_i_l_e ...] [_f_i_l_e ...] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN aaaawwwwkkkk scans each input _f_i_l_e for lines that match any of a set of patterns specified literally in _p_r_o_g_r_a_m or in one or more files specified as ----ffff _p_r_o_g_f_i_l_e. With each pattern there can be an associated action that is to be performed when a line in a _f_i_l_e matches the pattern. Each line is matched against the pattern portion of every pattern-action statement, and the associated action is performed for each matched pattern. The file name ---- means the standard input. Any _f_i_l_e of the form _v_a_r====_v_a_l_u_e is treated as an assignment, not a filename. An assignment is evaluated at the time it would have been opened if it were a filename, unless the ----vvvv option is used. An input line is made up of fields separated by white space, or by regular expression FFFFSSSS. The fields are denoted $$$$1111, $$$$2222, ...; $$$$0000 refers to the entire line. OOOOppppttttiiiioooonnnnssss aaaawwwwkkkk recognizes the following options and arguments: ----FFFF _f_s Specify regular expression used to separate fields. The default is to recognize space and tab characters, and to discard leading spaces and tabs. If the ----FFFF option is used, leading input field separators are no longer discarded. ----ffff _p_r_o_g_f_i_l_e Specify an awk program file. Up to 100 program files can be specified. The pattern-action statements in these files are executed in the same order as the files were specified. ----vvvv _v_a_r====_v_a_l_u_e Cause _v_a_r====_v_a_l_u_e assignment to occur before the BBBBEEEEGGGGIIIINNNN action (if it exists) is executed. SSSSttttaaaatttteeeemmmmeeeennnnttttssss A pattern-action statement has the form: _p_a_t_t_e_r_n {{{{ _a_c_t_i_o_n }}}} A missing {{{{ _a_c_t_i_o_n }}}} means print the line; a missing pattern always matches. Pattern-action statements are separated by new-lines or semicolons. An action is a sequence of statements. A statement can be one of the following: Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 aaaawwwwkkkk((((1111)))) aaaawwwwkkkk((((1111)))) iiiiffff((((_e_x_p_r_e_s_s_i_o_n)))) _s_t_a_t_e_m_e_n_t [eeeellllsssseeee _s_t_a_t_e_m_e_n_t] wwwwhhhhiiiilllleeee((((_e_x_p_r_e_s_s_i_o_n)))) _s_t_a_t_e_m_e_n_t ffffoooorrrr((((_e_x_p_r_e_s_s_i_o_n;;;;_e_x_p_r_e_s_s_i_o_n;;;;_e_x_p_r_e_s_s_i_o_n)))) _s_t_a_t_e_m_e_n_t ffffoooorrrr((((_v_a_r iiiinnnn _a_r_r_a_y) _s_t_a_t_e_m_e_n_t ddddoooo _s_t_a_t_e_m_e_n_t wwwwhhhhiiiilllleeee((((_e_x_p_r_e_s_s_i_o_n) bbbbrrrreeeeaaaakkkk ccccoooonnnnttttiiiinnnnuuuueeee {{{{[_s_t_a_t_e_m_e_n_t ...]}}}} _e_x_p_r_e_s_s_i_o_n #### commonly _v_a_r====_e_x_p_r_e_s_s_i_o_n pppprrrriiiinnnntttt[_e_x_p_r_e_s_s_i_o_n-_l_i_s_t] [>>>> _e_x_p_r_e_s_s_i_o_n] pppprrrriiiinnnnttttffff _f_o_r_m_a_t [,,,, _e_x_p_r_e_s_s_i_o_n-_l_i_s_t] [>>>> _e_x_p_r_e_s_s_i_o_n] rrrreeeettttuuuurrrrnnnn [_e_x_p_r_e_s_s_i_o_n] nnnneeeexxxxtttt #### skip remaining patterns on this input line. ddddeeeelllleeeetttteeee _a_r_r_a_y [_e_x_p_r_e_s_s_i_o_n] #### delete an array element. eeeexxxxiiiitttt [_e_x_p_r_e_s_s_i_o_n] #### exit immediately; status is _e_x_p_r_e_s_s_i_o_n. Statements are terminated by semicolons, newlines or right braces. An empty _e_x_p_r_e_s_s_i_o_n-_l_i_s_t stands for $$$$0000. String constants are quoted (""""""""), with the usual C escapes recognized within. Expressions take on string or numeric values as appropriate, and are built using the operators ++++, ----, ****, ////, %%%%, ^^^^ (exponentiation), and concatenation (indicated by a blank). The operators ++++++++, --------, ++++====, ----====, ****====, ////====, %%%%====, ^^^^====, ********====, >>>>, >>>>====, <<<<, <<<<====, ========, !!!!====, and ????:::: are also available in expressions. Variables can be scalars, array elements (denoted _x[[[[_i]]]]) or fields. Variables are initialized to the null string. Array subscripts can be any string, not necessarily numeric (this allows for a form of associative memory). Multiple subscripts such as [[[[_i,,,,_j,,,,_k]]]] are permitted. The constituents are concatenated, separated by the value of SSSSUUUUBBBBSSSSEEEEPPPP. The pppprrrriiiinnnntttt statement prints its arguments on the standard output (or on a file if >>>>_f_i_l_e or >>>>>>>>_f_i_l_e is present or on a pipe if ||||_c_m_d is present), separated by the current output field separator, and terminated by the output record separator. _f_i_l_e and _c_m_d can be literal names or parenthesized expressions. Identical string values in different statements denote the same open file. The pppprrrriiiinnnnttttffff statement formats its expression list according to the format (see _p_r_i_n_t_f(3)). BBBBuuuuiiiilllltttt----IIIInnnn FFFFuuuunnnnccccttttiiiioooonnnnssss The built-in function cccclllloooosssseeee((((_e_x_p_r)))) closes the file or pipe eeeexxxxpppprrrr opened by a pppprrrriiiinnnntttt or pppprrrriiiinnnnttttffff statement or a call to ggggeeeettttlllliiiinnnneeee with the same string-valued _e_x_p_r. This function returns zero if successful, otherwise, it returns non-zero. The customary functions eeeexxxxpppp, lllloooogggg, ssssqqqqrrrrtttt, ssssiiiinnnn, ccccoooossss, aaaattttaaaannnn2222 are built in. Other built-in functions are: bbbblllleeeennnnggggtttthhhh[[[[([[[[_s]]]])]]]] Length of its associated argument (in bytes) taken as a string, or of $$$$0000 if no argument. Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 aaaawwwwkkkk((((1111)))) aaaawwwwkkkk((((1111)))) lllleeeennnnggggtttthhhh[[[[([[[[_s]]]])]]]] Length of its associated argument (in characters) taken as a string, or of $$$$0000 if no argument. rrrraaaannnndddd(((()))) Returns a random number between zero and one. ssssrrrraaaannnndddd(((([_e_x_p_r])))) Sets the seed value for _r_a_n_d, and returns the previous seed value. If no argument is given, the time of day is used as the seed value; otherwise, _e_x_p_r is used. iiiinnnntttt((((_x)))) Truncates to an integer value ssssuuuubbbbssssttttrrrr((((_s,,,, _m[,,,, _n])))) Return the at most _n-character substring of _s that begins at position _m, numbering from 1. If _n is omitted, the substring is limited by the length of string _s. iiiinnnnddddeeeexxxx((((_s,,,, _t)))) Return the position, in characters, numbering from 1, in string _s where string _t first occurs, or zero if it does not occur at all. mmmmaaaattttcccchhhh((((_s,,,, _e_r_e)))) Return the position, in characters, numbering from 1, in string _s where the extended regular expression _e_r_e occurs, or 0 if it does not. The variables RRRRSSSSTTTTAAAARRRRTTTT and RRRRLLLLEEEENNNNGGGGTTTTHHHH are set to the position and length of the matched string. sssspppplllliiiitttt((((_s,,,, _a[,,,, _f_s])))) Splits the string _s into array elements _a[[[[1111]]]], _a[[[[2222]]]], ..., _a[[[[_n]]]], and returns _n. The separation is done with the regular expression _f_s, or with the field separator FFFFSSSS if _f_s is not given. ssssuuuubbbb((((_e_r_e,,,, _r_e_p_l [,,,, _i_n])))) Substitutes _r_e_p_l for the first occurrence of the extended regular expression _e_r_e in the string _i_n. If _i_n is not given, $$$$0000 is used. ggggssssuuuubbbb Same as ssssuuuubbbb except that all occurrences of the regular expression are replaced; ssssuuuubbbb and ggggssssuuuubbbb return the number of replacements. sssspppprrrriiiinnnnttttffff((((_f_m_t,,,, _e_x_p_r,,,, ...)))) String resulting from formatting _e_x_p_r ... according to the _p_r_i_n_t_f(3S) format _f_m_t ssssyyyysssstttteeeemmmm((((_c_m_d)))) Executes _c_m_d and returns its exit status ttttoooouuuuppppppppeeeerrrr((((_s)))) Converts the argument string _s to uppercase and returns the result. Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 aaaawwwwkkkk((((1111)))) aaaawwwwkkkk((((1111)))) ttttoooolllloooowwwweeeerrrr((((_s)))) Converts the argument string _s to lowercase and returns the result. The built-in function ggggeeeettttlllliiiinnnneeee sets $$$$0000 to the next input record from the current input file; ggggeeeettttlllliiiinnnneeee <<<< _f_i_l_e sets $$$$0000 to the next record from _f_i_l_e. ggggeeeettttlllliiiinnnneeee _x sets variable _x instead. Finally, _c_m_d |||| ggggeeeettttlllliiiinnnneeee pipes the output of _c_m_d into ggggeeeettttlllliiiinnnneeee; each call of ggggeeeettttlllliiiinnnneeee returns the next line of output from _c_m_d. In all cases, ggggeeeettttlllliiiinnnneeee returns 1 for a successful input, 0 for end of file, and -1 for an error. PPPPaaaatttttttteeeerrrrnnnnssss Patterns are arbitrary Boolean combinations (with !!!! |||||||| &&&&&&&&) of regular expressions and relational expressions. aaaawwwwkkkk supports Extended Regular Expressions as described in _r_e_g_e_x_p(5). Isolated regular expressions in a pattern apply to the entire line. Regular expressions can also occur in relational expressions, using the operators ~~~~ and !!!!~~~~. ////_r_e//// is a constant regular expression; any string (constant or variable) can be used as a regular expression, except in the position of an isolated regular expression in a pattern. A pattern can consist of two patterns separated by a comma; in this case, the action is performed for all lines from an occurrence of the first pattern though an occurrence of the second. A relational expression is one of the following: _e_x_p_r_e_s_s_i_o_n _m_a_t_c_h_o_p _r_e_g_u_l_a_r-_e_x_p_r_e_s_s_i_o_n _e_x_p_r_e_s_s_i_o_n _r_e_l_o_p _e_x_p_r_e_s_s_i_o_n _e_x_p_r_e_s_s_i_o_n iiiinnnn _a_r_r_a_y-_n_a_m_e ((((_e_x_p_r,_e_x_p_r,...)))) _i_n aaaarrrrrrrraaaayyyy----nnnnaaaammmmeeee where a relop is any of the six relational operators in C, and a matchop is either ~~~~ (matches) or !!!!~~~~ (does not match). A conditional is an arithmetic expression, a relational expression, or a Boolean combination of the two. The special patterns BBBBEEEEGGGGIIIINNNN and EEEENNNNDDDD can be used to capture control before the first input line is read and after the last. BBBBEEEEGGGGIIIINNNN and EEEENNNNDDDD do not combine with other patterns. SSSSppppeeeecccciiiiaaaallll CCCChhhhaaaarrrraaaacccctttteeeerrrrssss The following special escape sequences are recognized by aaaawwwwkkkk in both regular expressions and strings: EEEEssssccccaaaappppeeee MMMMeeeeaaaannnniiiinnnngggg \\\\aaaa alert character \\\\bbbb backspace character \\\\ffff form-feed character \\\\nnnn new-line character \\\\rrrr carriage-return character Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 aaaawwwwkkkk((((1111)))) aaaawwwwkkkk((((1111)))) \\\\tttt tab character \\\\vvvv vertical-tab character \\\\_n_n_n 1- to 3-digit octal value _n_n_n \\\\xxxx_h_h_h 1- to n-digit hexadecimal number VVVVaaaarrrriiiiaaaabbbblllleeee NNNNaaaammmmeeeessss Variable names with special meanings are: FFFFSSSS Input field separator regular expression; a space character by default; also settable by option ----FFFF_f_s. NNNNFFFF The number of fields in the current record. NNNNRRRR The ordinal number of the current record from the start of input. Inside a BBBBEEEEGGGGIIIINNNN action the value is zero. Inside an EEEENNNNDDDD action the value is the number of the last record processed. FFFFNNNNRRRR The ordinal number of the current record in the current file. Inside a BBBBEEEEGGGGIIIINNNN action the value is zero. Inside an EEEENNNNDDDD action the value is the number of the last record processed in the last file processed. FFFFIIIILLLLEEEENNNNAAAAMMMMEEEE A pathname of the current input file. RRRRSSSS The input record separator; a newline character by default. OOOOFFFFSSSS The pppprrrriiiinnnntttt statement output field separator; a space character by default. OOOORRRRSSSS The pppprrrriiiinnnntttt statement output record separator; a newline character by default. OOOOFFFFMMMMTTTT Output format for numbers (default %%%%....6666gggg). If the value of OOOOFFFFMMMMTTTT is not a floating-point format specification, the results are unspecified. CCCCOOOONNNNVVVVFFFFMMMMTTTT Internal conversion format for numbers (default %%%%....6666gggg). If the value of CCCCOOOONNNNVVVVFFFFMMMMTTTT is not a floating-point format specification, the results are unspecified. SSSSUUUUBBBBSSSSEEEEPPPP The subscript separator string for multi- dimensional arrays; the default value is " 34" AAAARRRRGGGGCCCC The number of elements in the AAAARRRRGGGGVVVV array. Hewlett-Packard Company - 5 - HP-UX Release 10.20: July 1996 aaaawwwwkkkk((((1111)))) aaaawwwwkkkk((((1111)))) AAAARRRRGGGGVVVV An array of command line arguments, excluding options and the _p_r_o_g_r_a_m argument numbered from zero to AAAARRRRGGGGCCCC-1. The arguments in AAAARRRRGGGGVVVV can be modified or added to; AAAARRRRGGGGCCCC can be altered. As each input file ends, aaaawwwwkkkk will treat the next non-null element of AAAARRRRGGGGVVVV, up to the current value of AAAARRRRGGGGCCCC-1, inclusive, as the name of the next input file. Thus, setting an element of AAAARRRRGGGGVVVV to null means that it will not be treated as an input file. The name ---- indicates the standard input. If an argument matches the format of an _a_s_s_i_g_n_m_e_n_t operand, this argument will be treated as an assignment rather than a _f_i_l_e argument. EEEENNNNVVVVIIIIRRRROOOONNNN Array of environment variables; subscripts are names. For example, if environment variable VVVV====tttthhhhiiiinnnngggg, EEEENNNNVVVVIIIIRRRROOOONNNN[[[[""""VVVV""""]]]] produces tttthhhhiiiinnnngggg. RRRRSSSSTTTTAAAARRRRTTTT The starting position of the string matched by the mmmmaaaattttcccchhhh function, numbering from 1. This is always equivalent to the return value of the mmmmaaaattttcccchhhh function. RRRRLLLLEEEENNNNGGGGTTTTHHHH The length of the string matched by the mmmmaaaattttcccchhhh function. Functions can be defined (at the position of a pattern-action statement) as follows: ffffuuuunnnnccccttttiiiioooonnnn ffffoooooooo((((aaaa,,,, bbbb,,,, cccc)))) {{{{ ............;;;; rrrreeeettttuuuurrrrnnnn xxxx }}}} Parameters are passed by value if scalar, and by reference if array name. Functions can be called recursively. Parameters are local to the function; all other variables are global. Note that if pattern-action statements are used in an HP-UX command line as an argument to the aaaawwwwkkkk command, the pattern-action statement must be enclosed in single quotes to protect it from the shell. For example, to print lines longer than 72 characters, the pattern-action statement as used in a script (----ffff _p_r_o_g_f_i_l_e command form) is: lllleeeennnnggggtttthhhh >>>> 77772222 The same pattern action statement used as an argument to the aaaawwwwkkkk command is quoted in this manner: aaaawwwwkkkk ''''lllleeeennnnggggtttthhhh >>>> 77772222'''' Hewlett-Packard Company - 6 - HP-UX Release 10.20: July 1996 aaaawwwwkkkk((((1111)))) aaaawwwwkkkk((((1111)))) EEEEXXXXTTTTEEEERRRRNNNNAAAALLLL IIIINNNNFFFFLLLLUUUUEEEENNNNCCCCEEEESSSS EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt VVVVaaaarrrriiiiaaaabbbblllleeeessss LLLLAAAANNNNGGGG Provides a default value for the internationalization variables that are unset or null. If LLLLAAAANNNNGGGG is unset or null, the default value of "C" (see _l_a_n_g(5)) is used. If any of the internationalization variables contains an invalid setting, aaaawwwwkkkk will behave as if all internationalization variables are set to "C". See _e_n_v_i_r_o_n(5). LLLLCCCC____AAAALLLLLLLL If set to a non-empty string value, overrides the values of all the other internationalization variables. LLLLCCCC____CCCCTTTTYYYYPPPPEEEE Determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. LLLLCCCC____NNNNUUUUMMMMEEEERRRRIIIICCCC Determines the radix character used when interpreting numeric input, performing conversion between numeric and string values and formatting numeric output. Regardless of locale, the period character (the decimal-point character of the POSIX locale) is the decimal-point character recognized in processing aaaawwwwkkkk programs (including assignments in command-line arguments). LLLLCCCC____CCCCOOOOLLLLLLLLAAAATTTTEEEE Determines the locale for the behavior of ranges, equivalence classes and multi-character collating elements within regular expressions. LLLLCCCC____MMMMEEEESSSSSSSSAAAAGGGGEEEESSSS Determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. NNNNLLLLSSSSPPPPAAAATTTTHHHH Determines the location of message catalogues for the processing of LLLLCCCC____MMMMEEEESSSSSSSSAAAAGGGGEEEESSSS.... PPPPAAAATTTTHHHH Determines the search path when looking for commands executed by ssssyyyysssstttteeeemmmm((((ccccmmmmdddd)))), or input and output pipes. In addition, all environment variables will be visible via the aaaawwwwkkkk variable EEEENNNNVVVVIIIIRRRROOOONNNN. IIIInnnntttteeeerrrrnnnnaaaattttiiiioooonnnnaaaallll CCCCooooddddeeee SSSSeeeetttt SSSSuuuuppppppppoooorrrrtttt Single- and multi-byte character code sets are supported except that variable names must contain only ASCII characters and regular expressions must contain only valid characters. Hewlett-Packard Company - 7 - HP-UX Release 10.20: July 1996 aaaawwwwkkkk((((1111)))) aaaawwwwkkkk((((1111)))) DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS aaaawwwwkkkk supports up to 199 fields ($$$$1111, $$$$2222, ..., $$$$111199999999) per record. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS Print lines longer than 72 characters: lllleeeennnnggggtttthhhh >>>> 77772222 Print first two fields in opposite order: {{{{ pppprrrriiiinnnntttt $$$$2222,,,, $$$$1111 }}}} Same, with input fields separated by comma and/or blanks and tabs: BBBBEEEEGGGGIIIINNNN {{{{ FFFFSSSS ==== """",,,,[[[[ \\\\tttt]]]]****||||[[[[ \\\\tttt]]]]++++"""" }}}} {{{{ pppprrrriiiinnnntttt $$$$2222,,,, $$$$1111 }}}} Add up first column, print sum and average: {{{{ ssss ++++==== $$$$1111 }}}}"""" EEEENNNNDDDD {{{{ pppprrrriiiinnnntttt """"ssssuuuummmm iiiissss"""",,,, ssss,,,, """" aaaavvvveeeerrrraaaaggggeeee iiiissss"""",,,, ssss////NNNNRRRR }}}} Print all lines between start/stop pairs: ////ssssttttaaaarrrrtttt////,,,, ////ssssttttoooopppp//// Simulate eeeecccchhhhoooo command (see _e_c_h_o(1)): BBBBEEEEGGGGIIIINNNN {{{{ #### SSSSiiiimmmmuuuullllaaaatttteeee eeeecccchhhhoooo((((1111)))) ffffoooorrrr ((((iiii ==== 1111;;;; iiii <<<< AAAARRRRGGGGCCCC;;;; iiii++++++++)))) pppprrrriiiinnnnttttffff """"%%%%ssss """",,,, AAAARRRRGGGGVVVV[[[[iiii]]]] pppprrrriiiinnnnttttffff """"\\\\nnnn"""" eeeexxxxiiiitttt }}}} AAAAUUUUTTTTHHHHOOOORRRR aaaawwwwkkkk was developed by AT&T, IBM, OSF, and HP. SSSSEEEEEEEE AAAALLLLSSSSOOOO lex(1), sed(1). A. V. Aho, B. W. Kernighan, P. J. Weinberger: _T_h_e _A_W_K _P_r_o_g_r_a_m_m_i_n_g _L_a_n_g_u_a_g_e, Addison-Wesley, 1988. SSSSTTTTAAAANNNNDDDDAAAARRRRDDDDSSSS CCCCOOOONNNNFFFFOOOORRRRMMMMAAAANNNNCCCCEEEE aaaawwwwkkkk: SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2 Hewlett-Packard Company - 8 - HP-UX Release 10.20: July 1996 ccccuuuutttt((((1111)))) ccccuuuutttt((((1111)))) NNNNAAAAMMMMEEEE cut - cut out (extract) selected fields of each line of a file SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ccccuuuutttt ----cccc _l_i_s_t [_f_i_l_e ...] ccccuuuutttt ----bbbb _l_i_s_t [----nnnn] [_f_i_l_e ...] ccccuuuutttt ----ffff _l_i_s_t [----dddd _c_h_a_r] [----ssss] [_f_i_l_e ...] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN ccccuuuutttt cuts out (extracts) columns from a table or fields from each line in a file; in data base parlance, it implements the projection of a relation. Fields as specified by _l_i_s_t can be fixed length (defined in terms of character or byte position in a line when using the ----cccc or ----bbbb option), or the length can vary from line to line and be marked with a field delimiter character such as the tab character (when using the ----ffff option). ccccuuuutttt can be used as a filter; if no files are given, the standard input is used. When processing single-byte character sets, the ----cccc and ----bbbb options are equivalent and produce identical results. When processing multi-byte character sets, when the ----bbbb and ----nnnn options are used together, their combined behavior is very similar, but not identical to the ----cccc option. OOOOppppttttiiiioooonnnnssss Options are interpreted as follows: _l_i_s_t A comma-separated list of integer _b_y_t_e (-b option), _c_h_a_r_a_c_t_e_r (-c option), or _f_i_e_l_d (-f option) numbers, in increasing order, with optional ---- to indicate ranges. For example: 1111,,,,4444,,,,7777 Positions 1, 4, and 7. 1111----3333,,,,8888 Positions 1 through 3 and 8. ----5555,,,,11110000 Positions 1 through 5 and 10. 3333---- Position 3 through last position. ----bbbb _l_i_s_t Cut based on a list of bytes. Each selected byte is output unless the ----nnnn option is also specified. ----cccc _l_i_s_t Cut based on character positions specified by _l_i_s_t (----cccc 1111----77772222 extracts the first 72 characters of each line). ----ffff _l_i_s_t Where _l_i_s_t is a list of fields assumed to be separated in the file by a delimiter character (see ----dddd); for example, ----ffff 1111,,,,7777 copies the first and seventh field only. Lines with no field delimiters will be passed through intact (useful Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 ccccuuuutttt((((1111)))) ccccuuuutttt((((1111)))) for table subheadings), unless ----ssss is specified. ----dddd _c_h_a_r The character following ----dddd is the field delimiter ((((-f option only). Default is _t_a_b. Space or other characters with special meaning to the shell must be quoted. Adjacent field delimiters delimit null fields. ----nnnn Do not split characters. If the high end of a range within a list is not the last byte of a character, that character is not included in the output. However, if the low end of a range within a list is not the first byte of a character, the entire character _i_s included in the output." ----ssss Suppresses lines with no delimiter characters when using ----ffff option. Unless ----ssss is specified, lines with no delimiters appear in the output without alteration. HHHHiiiinnnnttttssss Use ggggrrrreeeepppp to extract text from a file based on text pattern recognition (using regular expressions). Use ppppaaaasssstttteeee to merge files line-by-line in columnar format. To rearrange columns in a table in a different sequence, use ccccuuuutttt and ppppaaaasssstttteeee. See _g_r_e_p(1) and _p_a_s_t_e(1) for more information. EEEEXXXXTTTTEEEERRRRNNNNAAAALLLL IIIINNNNFFFFLLLLUUUUEEEENNNNCCCCEEEESSSS EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt VVVVaaaarrrriiiiaaaabbbblllleeeessss LLLLCCCC____CCCCTTTTYYYYPPPPEEEE determines the interpretation of text as single and/or multi-byte characters. If LLLLCCCC____CCCCTTTTYYYYPPPPEEEE is not specified in the environment or is set to the empty string, the value of LLLLAAAANNNNGGGG is used as a default for each unspecified or empty variable. If LLLLAAAANNNNGGGG is not specified or is set to the empty string, a default of "C" (see _l_a_n_g(5)) is used instead of LLLLAAAANNNNGGGG. If any internationalization variable contains an invalid setting, ccccuuuutttt behaves as if all internationalization variables are set to "C". See _e_n_v_i_r_o_n(5). IIIInnnntttteeeerrrrnnnnaaaattttiiiioooonnnnaaaallll CCCCooooddddeeee SSSSeeeetttt SSSSuuuuppppppppoooorrrrtttt The delimiter specified with the ----dddd argument must be a single-byte character. Otherwise, single- and multi-byte character code sets are supported. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS Password file mapping of user ID to user names: ccccuuuutttt ----dddd :::: ----ffff 1111,,,,5555 ////eeeettttcccc////ppppaaaasssssssswwwwdddd Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 ccccuuuutttt((((1111)))) ccccuuuutttt((((1111)))) Set environment variable nnnnaaaammmmeeee to current login name: nnnnaaaammmmeeee====````wwwwhhhhoooo aaaammmm iiii |||| ccccuuuutttt ----ffff 1111 ----dddd """" """"```` Convert file ssssoooouuuurrrrcccceeee containing lines of arbitrary length into two files where ffffiiiilllleeee1111 contains the first 500 bytes (unless the 500th byte is within a multi-byte character), and ffffiiiilllleeee2222 contains the remainder of each line: ccccuuuutttt ----bbbb 1111----555500000000 ----nnnn ssssoooouuuurrrrcccceeee >>>> ffffiiiilllleeee1111 ccccuuuutttt ----bbbb 555500000000---- ----nnnn ssssoooouuuurrrrcccceeee >>>> ffffiiiilllleeee2222 DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS lllliiiinnnneeee ttttoooooooo lllloooonnnngggg Line length must not exceed LLLLIIIINNNNEEEE____MMMMAAAAXXXX characters or fields, including the new-line character (see _l_i_m_i_t_s(5). bbbbaaaadddd lllliiiisssstttt ffffoooorrrr bbbb////cccc////ffff ooooppppttttiiiioooonnnn Missing ----bbbb, ----cccc, or ----ffff option or incorrectly specified _l_i_s_t. No error occurs if a line has fewer fields than the _l_i_s_t calls for. nnnnoooo ffffiiiieeeellllddddssss _l_i_s_t is empty. WWWWAAAARRRRNNNNIIIINNNNGGGGSSSS ccccuuuutttt does not expand tabs. Pipe text through _e_x_p_a_n_d(1) if tab expansion is required. Backspace characters are treated the same as any other character. To eliminate backspace characters before processing by ccccuuuutttt, use the ffffoooolllldddd or ccccoooollll command (see _f_o_l_d(1) and _c_o_l(1)). AAAAUUUUTTTTHHHHOOOORRRR ccccuuuutttt was developed by OSF and HP. SSSSEEEEEEEE AAAALLLLSSSSOOOO grep(1), paste(1). SSSSTTTTAAAANNNNDDDDAAAARRRRDDDDSSSS CCCCOOOONNNNFFFFOOOORRRRMMMMAAAANNNNCCCCEEEE ccccuuuutttt: SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2 Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 dddduuuu((((1111)))) dddduuuu((((1111)))) NNNNAAAAMMMMEEEE du - summarize disk usage SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS dddduuuu [----aaaa|----ssss] [----bbbbrrrrxxxx] [----tttt _t_y_p_e] [_n_a_m_e ...] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The dddduuuu command gives the number of 512-byte blocks allocated for all files and (recursively) directories within each directory and file specified by the _n_a_m_e operands. The block count includes the indirect blocks of the file. A file with two or more links is counted only once. If _n_a_m_e is missing, the current working directory is used. By default, dddduuuu generates an entry only for the _n_a_m_e operands and each directory contained within those hierarchies. OOOOppppttttiiiioooonnnnssss The dddduuuu command recognizes the following options: ----aaaa Print entries for each file encountered in the directory hierarchies in addition to the normal output. ----bbbb For each _n_a_m_e operand that is a directory for which file system swap has been enabled, print the number of blocks the swap system is currently using. ----rrrr Print messages about directories that cannot be read, files that cannot be accessed, etc. dddduuuu is normally silent about such conditions. ----ssss Print only the grand total of disk usage for each of the specified _n_a_m_e operands. ----xxxx Restrict reporting to only those files that have the same device as the file specified by the _n_a_m_e operand. Disk usage is normally reported for the entire directory hierarchy below each of the given _n_a_m_e operands. ----tttt _t_y_p_e Restrict reporting to file systems of the specified _t_y_p_e. (Example values for _t_y_p_e are hhhhffffssss, ccccddddffffssss, nnnnffffssss,,,, etc.) Multiple ----tttt _t_y_p_e options can be specified. Disk usage is normally reported for the entire directory hierarchy below each of the given _n_a_m_e operands. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS Display disk usage for the current working directory and all directories below it, generating error messages for unreadable Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 dddduuuu((((1111)))) dddduuuu((((1111)))) directories: dddduuuu ----rrrr Display disk usage for the entire file system except for any ccccddddffffssss or nnnnffffssss mounted file systems: dddduuuu ----tttt hhhhffffssss //// Display disk usage for files on the root volume (////) only. No usage statistics are collected for any other mounted file systems: dddduuuu ----xxxx //// WWWWAAAARRRRNNNNIIIINNNNGGGGSSSS Block counts are incorrect for files that contain holes. SSSSEEEEEEEE AAAALLLLSSSSOOOO df(1M), bdf(1M), quot(1M). SSSSTTTTAAAANNNNDDDDAAAARRRRDDDDSSSS CCCCOOOONNNNFFFFOOOORRRRMMMMAAAANNNNCCCCEEEE dddduuuu: SVID2, SVID3, XPG2, XPG3, XPG4 Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt NNNNAAAAMMMMEEEE kermit - C-Kermit 6.0.192 communications software for serial and network connections: modem dialing, file transfer and management, terminal connection, character-set translation, and script programming. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS kkkkeeeerrrrmmmmiiiitttt [_c_o_m_m_a_n_d-_f_i_l_e] [_o_p_t_i_o_n_s...] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN _K_e_r_m_i_t is a family of file transfer, management, and communication software programs from Columbia University available for most computers and operating systems. The version of Kermit for Hewlett- Packard HP-UX, called supports both serial connections (direct or dialed) and TCP/IP connections. C-Kermit can be thought of as a user-friendly and powerful alternative to cu, tip, uucp, ftp, and telnet; a single package for both network and serial communications, offering automation, convenience, and language features not found in the other packages, and having a great deal in common with its cousins, C-Kermit on other UNIX platforms, Kermit 95 for Windows 95 and NT and OS/2, MS-DOS Kermit for PCs with DOS and Windows 3.x, and IBM Mainframe Kermit-370 for VM/CMS, MVS/TSO, and CICS. C-Kermit itself also runs on Digital VMS, Data General AOS/VS, Stratus VOS, OS-9, QNX, the BeBox, Plan 9, the Commodore Amiga, and elsewhere. Together, C-Kermit, Kermit 95, MS-DOS Kermit, and IBM Mainframe Kermit offer a consistent and nearly universal approach to inter-computer communications. C-Kermit 6.0.192 is Copyright (C) 1985, 1996 by the Trustees of Columbia University in the City of New York. The C-Kermit software may not be, in whole or in part, licensed or sold for profit as a software product itself, nor may it be included in or distributed with commercial products or otherwise distributed by commercial concerns to their clients or customers without written permission of the Office of Kermit Development and Distribution, Columbia University. This copyright notice must not be removed, altered, or obscured. C-Kermit 6.0.192 is included with HP-UX 10.0 and later HP-UX releases by Hewlett-Packard in partnership with the Office of Kermit Development and Distribution, Columbia University. C-Kermit 6.0 is thoroughly documented in the book by Frank da Cruz and Christine M. Gianone, Digital Press, Second Edition, 1997; see REFERENCES at the end of this manual page. This manual page is not a substitute for the book. If you are a serious user of C-Kermit, particularly if plan to write C-Kermit script programs, you should purchase the manual. Book sales are the primary source of funding for the nonprofit Kermit Project. Any new features added since the most recent edition of the book was published are documented in the online file _c_k_c_k_e_r._u_p_d. Hints, tips, 9 - 1 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt limitations, restrictions are listed in _c_k_c_k_e_r._b_w_r (general C-Kermit) and _c_k_u_k_e_r._b_w_r (UNIX-specific); see FILES below. Please consult all of these references before reporting problems or asking for technical support. Kermit software is available for hundreds of different computers and operating systems from Columbia University. For best file-transfer results, please use C-Kermit in conjunction with real Columbia University Kermit software on other computers, such as Kermit 95 for Windows 95 and NT or MS-DOS Kermit for DOS 3.x or Windows. See CONTACTS below. MMMMOOOODDDDEEEESSSS OOOOFFFF OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN C-Kermit can be used in two "modes": remote and local. In you connect to the HP-UX system from a desktop computer and transfer files between your desktop computer and HP-UX C-Kermit. In that case, connection establishment (dialing, TELNET connection, etc.) is handled by the Kermit program on your desktop computer. In C-Kermit establishes a connection to another computer by direct serial connection, by dialing a modem, or by making a network connection. When used in local mode, C-Kermit gives you a terminal connection to the remote computer, using your actual terminal, emulator, or UNIX workstation terminal window or console driver for specific terminal emulation. C-Kermit also has two types of commands: the familiar UNIX-style command-line options, and an interactive dialog with a prompt. give you access to a small but useful subset of C-Kermit's features for terminal connection and file transfer, plus the ability to pipe files into or out of Kermit for transfer. give you access to dialing, script programming, character-set translation, and, in general, detailed control and display of all C- Kermit's features. Interactive commands can also be collected into command files or macros. SSSSTTTTAAAARRRRTTTTIIIINNNNGGGG CCCC----KKKKEEEERRRRMMMMIIIITTTT You can start C-Kermit by typing "/usr/bin/kermit", or just "kermit" if your PATH includes "/usr/bin", possibly followed by command-line options. If there are no "action options" on the command line (explained below), C-Kermit starts in interactive command mode; you will see a greeting message and then the "C-Kermit>" prompt. If you do include action options on the command line, C-Kermit takes the indicated actions and then exits directly back to UNIX. Either way, C-Kermit executes the commands in its initialization file, ////uuuussssrrrr////sssshhhhaaaarrrreeee////lllliiiibbbb////kkkkeeeerrrrmmmmiiiitttt////cccckkkkeeeerrrrmmmmiiiitttt....iiiinnnniiii, before it executes any other commands, unless you have included the `----YYYY' (uppercase) command-line option, which means to skip the initialization file, or you have included the `----yyyy _f_i_l_e_n_a_m_e' option to specify an alternative initialization file. 9 - 2 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt FFFFIIIILLLLEEEE TTTTRRRRAAAANNNNSSSSFFFFEEEERRRR Here is the most common scenario for Kermit file transfer. Many other methods are possible, most of them more convenient, but this basic method should work in all cases. o+ Start Kermit on your local computer and establish a connection to the remote computer. If C-Kermit is on your local computer, use the sequence SET MODEM TYPE _m_o_d_e_m-_n_a_m_e, SET LINE _d_e_v_i_c_e-_n_a_m_e, SET SPEED _b_i_t_s-_p_e_r-_s_e_c_o_n_d, and DIAL _p_h_o_n_e-_n_u_m_b_e_r if you are dialing; SET LINE and SPEED for direct connections; SET NETWORK _n_e_t_w_o_r_k-_t_y_p_e and SET HOST _h_o_s_t-_n_a_m_e-_o_r-_a_d_d_r_e_s_s for network connections. o+ SET any other necessary communication parameters, such as PARITY, DUPLEX, and FLOW-CONTROL. o+ Give the CONNECT command. o+ Log in to the remote computer. o+ Start Kermit on the remote computer, give it any desired SET commands for file-, communication-, or protocol-related parameters. If you will be transferring binary files, give the command SET FILE TYPE BINARY to the Kermit program that will be sending them. o+ To a file or file group, give the remote Kermit a SEND command, following by a filename or "wildcard" file specification, for example: sssseeeennnndddd ooooooooffffaaaa....ttttxxxxtttt #### ((((sssseeeennnndddd oooonnnneeee ffffiiiilllleeee)))) sssseeeennnndddd ooooooooffffaaaa....**** #### ((((sssseeeennnndddd aaaa ggggrrrroooouuuupppp ooooffff ffffiiiilllleeeessss)))) To a file or files, give the remote Kermit a RECEIVE command. The sending Kermit will tell the receiving Kermit the name (and other attributes) of each file. o+ Escape back to the Kermit program on your local (desktop) computer. If your local computer is running C-Kermit, type Ctrl-\ c (Control-backslash followed by the letter 'c') (on NeXT workstations, use Ctrl-] c). If MS-DOS or OS/2 or Windows Kermit, use Alt-x (hold down the Alt key, press 'x'). Now you should see your local Kermit program's prompt. o+ If you will be transferring binary files, give the command SET FILE TYPE BINARY to the Kermit program that is sending the files. o+ If you are files, tell the local Kermit program to RECEIVE. If you are give your local Kermit program a SEND command, specifying a filename or wildcard file specification. In 9 - 3 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt other words, tell the Kermit program what to do first, SEND or RECEIVE, then escape back to the _l_o_c_a_l Kermit and give it the opposite command, RECEIVE or SEND. o+ When the transfer is complete, give a CONNECT command. Now you are talking to Kermit on the remote computer again. Type EXIT to get back to the command prompt on the remote computer. When you are finished using the remote computer, log out and then (if necessary) escape back to Kermit on your local computer. Then you can make another connection or EXIT from the local Kermit program. C-Kermit's file transfer protocol defaults are deliberately conservative, resulting in file transfer that almost always works, but might be somewhat slow. To increase file transfer performance on computers and connections that permit it, use SET RECEIVE PACKET- LENGTH to increase the packet length, SET WINDOW to increase the packet window size, and use SET PREFIXING to reduce the overhead of control-character prefixing. (Hint: try the FFFFAAAASSSSTTTT command to enable all these performance options at once.) On serial connections, use hardware flow control (SET FLOW RTS/CTS) if available, rather than software (XON/XOFF) flow control. On TCP/IP connections, SET FLOW NONE. For details, including benchmarks, read Chapter 12 of OOOOTTTTHHHHEEEERRRR FFFFEEEEAAAATTTTUUUURRRREEEESSSS C-Kermit includes features too numerous to be explained in a man page. For further information about connection establishment, modem dialing, networks, terminal connection, key mapping, logging, file transfer options and features, troubleshooting, client/server operation, character-set translation during terminal connection and file transfer, "raw" up- and downloading of files, macro construction, script programming, convenience features, and shortcuts, plus numerous tables, examples, and illustrations, please consult HHHHEEEELLLLPPPP C-Kermit has extensive built-in help. You can find out what commands exist by typing ? at the C-Kermit> prompt. You can type HELP at the C-Kermit> prompt for "getting-started" message, or HELP followed by the name of a particular command for information about that command, for example: hhhheeeellllpppp sssseeeennnndddd hhhheeeellllpppp sssseeeetttt ffffiiiilllleeee You can type ? anywhere within a command to get brief help about the current command field. You can also type the INTRO command to get a brief introduction to C-Kermit, and the NEWS command to find out what's new in your version. Finally, you can use the BUG command to learn how to report bugs. 9 - 4 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt EEEENNNNTTTTEEEERRRRIIIINNNNGGGG CCCCOOOOMMMMMMMMAAAANNNNDDDDSSSS You can use upper or lower case for interactive-mode commands, but remember that UNIX filenames are case-sensitive. You can abbreviate commands as long as the abbreviation matches only one possibility. While typing a command, you can use the following editing characters: Delete, Backspace, or Rubout erases the rightmost character. Ctrl-W erases the rightmost "word". Ctrl-U erases the current command line. Ctrl-R redisplays the current command. Ctrl-P recalls a previous command (scrolls back in command buffer). Ctrl-N scrolls forward in a scrolled-back command buffer. Ctrl-C cancels the current command. Tab, Esc, or Ctrl-I tries to complete the current keyword or filename. ? gives help about the current field. To enter the command and make it execute, press the Return or Enter key. BBBBAAAACCCCKKKKSSSSLLLLAAAASSSSHHHH NNNNOOOOTTTTAAAATTTTIIIIOOOONNNN Within an interactive command, the "\" character (backslash) is a prefix used to enter special quantities, including ordinary characters that would otherwise be illegal. At the end of a line, \ or - (dash) makes the next line a continuation of the current line. Other than that, the character following the \ identifies what the special quantity is: % A user-defined simple (scalar) variable such as \%a or \%1 & an array reference such as \&a[3] $ an environment variable such as \$(TERM) v (or V) a built-in variable such as \v(time) f (or F) a function such as \Fsubstring(\%a,3,2) d (or D) a decimal (base 10) number (1 to 3 digits, 0..255) such as \d27 o (or O) an octal (base 8) number (1 to 3 digits, 0..377) such as \o33 x (or X) a hexadecimal (base 16) number (2 digits, 00..ff) like \x1b \ the backslash character itself b (or B) the BREAK signal (OUTPUT command only) l (or L) a Long BREAK signal (OUTPUT only) n (or N) a NUL (0) character (OUTPUT only) a decimal digit a 1-, 2-, or 3-digit decimal number, such as \27 {} used for grouping, e.g. \{27}123 anything else: following character taken literally. 9 - 5 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt Note that numbers turn into the character with that binary code (0- 255), so you can use \7 for a bell, \13 for carriage return, \10 for linefeed. For example, to have C-Kermit send a BELL to your screen, type: eeeecccchhhhoooo \\\\7777 CCCCOOOOMMMMMMMMAAAANNNNDDDD LLLLIIIISSSSTTTT The commands most commonly used, and important for beginners to know, are marked with "*": PPPPrrrrooooggggrrrraaaammmm MMMMaaaannnnaaaaggggeeeemmmmeeeennnntttt BUG Learn how to report bugs. CHECK See if a particular feature is configured. CLOSE Close a log or other local file. COMMENT Introduce a full-line comment. DATE Display current date and time. * EXIT Leave the program, return to UNIX. * HELP Display a help message for a given command. * INTRO Print a brief introduction to C-Kermit. LOG Open a log file -- debugging, packet, session, transaction. PUSH Invoke local system's interactive command interpreter. QUIT Synonym for EXIT. REDIRECT Redirect standard I/O of command to communication device. RUN Run a program or system command. SET COMMAND Command-related parameters: bytesize, recall buffer size. SET DEBUG Log or display debugging information. SET EXIT Items related to C-Kermit's action upon exit or SET LINE/HOST. SET PROMPT The C-Kermit program's interactive command prompt. SHOW EXIT Display SET EXIT parameters. SHOW FEATURES Show features that C-Kermit was built with. SHOW VERSIONS Show version numbers of each source module. SUSPEND Suspend Kermit (use only if shell supports job control!). * SHOW Display values of SET parameters. * TAKE Execute commands from a file. VERSION Display the C-Kermit program version number. Z Synonym for SUSPEND. Ctrl-C Interrupt a C-Kermit command in progress. 9 - 6 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt Ctrl-Z Synonym for SUSPEND. ; or # Introduce a full-line or trailing comment. ! or @ Synonym for RUN. < Synonym for REDIRECT. CCCCoooonnnnnnnneeeeccccttttiiiioooonnnn EEEEssssttttaaaabbbblllliiiisssshhhhmmmmeeeennnntttt aaaannnndddd RRRReeeelllleeeeaaaasssseeee * DIAL Dial a telephone number. * HANGUP Hang up the phone or network connection. PAD Command for X.25 PAD (SunOS / Solaris / VOS only). PING Check status of remote TCP/IP host. REDIAL Dial the most recently DIALed number again. SET CARRIER Treatment of carrier on terminal connections. * SET DIAL Parameters related to modem dialing. * SET FLOW Communication line flow control: AUTO, RTS/CTS, XON/XOFF, etc. * SET HOST Specify remote network host name or address. * SET LINE Specify serial communication device name, like /dev/cul0p0. * SET MODEM TYPE Specify type of modem on SET LINE device, like HAYES. * SET NETWORK Network type, TCP/IP or X.25 (SunOS / Solaris / VOS only). SET TCP Specify TCP protocol options (advanced). SET TELNET Specify TELNET protocol options. SET PAD X.25 X.3 PAD parameters (SunOS / Solaris / VOS only). * SET PARITY Character parity (none, even, etc.) for communications. * SET SPEED Serial communication device speed, e.g. 2400, 9600, 57600. SET X.25 Specify X.25 connection parameters (SunOS / Solaris / VOS only). SHOW COMM Display all communications settings. SHOW DIAL Display SET DIAL values. SHOW MODEM Display modem type, signals, etc. SHOW NETWORK Display network-related items. * TELNET = SET NETWORK TCP/IP, SET HOST ..., CONNECT. TELOPT Send a TELNET option negotiation (advanced). TTTTeeeerrrrmmmmiiiinnnnaaaallll CCCCoooonnnnnnnneeeeccccttttiiiioooonnnn * C Special abbreviation for CONNECT. * CONNECT Establish a terminal connection to a remote computer. 9 - 7 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt SET COMMAND Bytesize between C-Kermit and your keyboard and screen. * SET DUPLEX Specify which side echoes during CONNECT. SET ESCAPE Prefix for "escape commands" during CONNECT. SET KEY Key mapping and macros for use in CONNECT mode. SET TERMINAL Terminal connection items: bytesize, character-set, echo, etc. SHOW ESCAPE Display current CONNECT-mode escape character. SHOW KEY Display keycode and assigned value or macro. SHOW TERMINAL Display SET TERMINAL items. * Ctrl-\ CONNECT-mode escape character, followed by another character: C to return to C-Kermit> prompt. B to send BREAK signal. ? to see other options. FFFFiiiilllleeee TTTTrrrraaaannnnssssffffeeeerrrr ADD Add a file specification to the SEND- LIST. LOG SESSION Download a file with no error checking. MOVE Send a file and then delete it. MMOVE Multiple MOVE - accepts a list of files, separated by spaces. MSEND Multiple SEND - accepts a list of files, separated by spaces. * RECEIVE Passively wait for files to arrive from other Kermit. * R Special abbreviation for RECEIVE. * SEND Send files. * S Special abbreviation for SEND. REGET Continue an incomplete download from a server. RESEND Continue an incomplete transmission. PSEND Send part of a file. SET ATTRIB Control transmission of file attributes. * SET BLOCK Choose error-checking level, 1, 2, or 3. SET BUFFERS Size of send and receive packet buffers. SET PREFIX Which control characters to "unprefix" during file transfer. SET DELAY How long to wait before sending first packet. SET DESTINATION DISK, PRINTER, or SCREEN for incoming files. * SET FILE Transfer mode (type), character-set, collision action, etc. 9 - 8 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt * SET RECEIVE Parameters for inbound packets: packet- length, etc. SET REPEAT Repeat-count compression parameters. SET RETRY Packet retransmission limit. SET SEND Parameters for outbound packets: length, etc. SET HANDSHAKE Communication line half-duplex packet turnaround character. SET LANGUAGE Enable language-specific character-set translations. SET SESSION-LOG File type for session log, text or binary. SET TRANSFER File transfer parameters: character-set, display, etc. SET TRANSMIT Control aspects of TRANSMIT command execution. SET UNKNOWN Specify handling of unknown character sets. * SET WINDOW File transfer packet window size, 1-31. SHOW ATTRIB Display SET ATTRIBUTE values. SHOW CONTROL Display control-character prefixing map. * SHOW FILE Display file-related settings. SHOW PROTOCOL Display protocol-related settings. SHOW LANGUAGE Display language-related settings. SHOW TRANSMIT Display SET TRANSMIT values. * STATISTICS Display statistics about most recent file transfer. TRANSMIT Upload a file with no error checking. XMIT Synonym for TRANSMIT. FFFFiiiilllleeee MMMMaaaannnnaaaaggggeeeemmmmeeeennnntttt * CD Change Directory. * DELETE Delete a file or files. * DIRECTORY Display a directory listing. MAIL Send a file to other Kermit, to be delivered as e-mail. PRINT Print a local file on a local printer. * PWD Display current working directory. RENAME Change the name of a local file. SET PRINTER Choose printer device. SPACE Display current disk space usage. SHOW CHARACTER-SETS Display character-set translation info. TRANSLATE Translate a local file's character set. TYPE Display a file on the screen. XLATE Synonym for TRANSLATE. CCCClllliiiieeeennnntttt////SSSSeeeerrrrvvvveeeerrrr OOOOppppeeeerrrraaaattttiiiioooonnnn BYE Terminate a remote Kermit server and log out its job. DISABLE Disallow access to selected features during server operation. 9 - 9 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt E-PACKET Send an Error packet. ENABLE Allow access to selected features during server operation. FINISH Instruct a remote Kermit server to exit, but not log out. G Special abbreviation for GET. GET Get files from a remote Kermit server. RETRIEVE Like GET but server deletes files after. REMOTE xxx Command for server, can be redirected with > or |. REMOTE CD Tell remote Kermit server to change its directory. REMOTE ASSIGN Assign a variable. REMOTE DELETE Tell server to delete a file. REMOTE DIRECTORY Ask server for a directory listing. REMOTE HELP Ask server to send a help message. REMOTE HOST Ask server to ask its host to execute a command. REMOTE KERMIT Send an interactive Kermit command to the server. REMOTE LOGIN Authenticate yourself to a remote Kermit server. REMOTE LOGOUT Log out from a Kermit server previously LOGIN'd to. REMOTE PRINT Print a local file on the server's printer. REMOTE QUERY Get value of a variable. REMOTE SET Send a SET command to a remote server. REMOTE SPACE Ask server how much disk space it has left. REMOTE TYPE Ask server to display a file on your screen. REMOTE WHO Ask server for a "who" or "finger" listing. SERVER Be a Kermit server. SET SERVER Parameters for server operation. SHOW SERVER Show SET SERVER, ENABLE/DISABLE items. SSSSccccrrrriiiipppptttt pppprrrrooooggggrrrraaaammmmmmmmiiiinnnngggg ASK Prompt the user, store user's reply in a variable. ASKQ Like ASK, but does not echo (useful for passwords). ASSIGN Assign an evaluated string to a variable or macro. CLEAR Clear communication device input buffer. CLOSE Close a log or other local file. DECLARE Declare an array. DECREMENT Subtract one (or other number) from a variable. 9 - 10 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt DEFINE Define a variable or macro. DO Execute a macro ("DO" can be omitted). ECHO Display text on the screen. ELSE Used with IF. END A command file or macro. EVALUATE An arithmetic expression. FOR Execute commands repeatedly in a counted loop. FORWARD GOTO in the forward direction only. GETC Issue a prompt, get one character from keyboard. GETOK Ask question, get Yes or No answer, set SUCCESS or FAILURE. GOTO Go to a labeled command in a command file or macro. IF Conditionally execute the following command. INCREMENT Add one (or other number) to a variable. INPUT Match characters from another computer against a given text. LOCAL Declares local variables in a macro. MINPUT Like INPUT, but allows several match strings. MSLEEP Sleep for given number of milliseconds. OPEN Open a local file for reading or writing. O Special abbreviation for OUTPUT. OUTPUT Send text to another computer. PAUSE Do nothing for a given number of seconds. READ Read a line from a local file into a variable. REINPUT Reexamine text previously received from another computer. RETURN Return from a user-defined function. SCRIPT Execute a UUCP-style login script. SET ALARM Set a timer to be used with IF ALARM; SHOW ALARM shows it. SET CASE Treatment of alphabetic case in string comparisons. SET COMMAND QUOTING turns on/off interpretation of backslash notation. SET COUNT For counted loops. SET INPUT Control behavior of INPUT command. SET MACRO Control aspects of macro execution. SET TAKE Control aspects of TAKE file execution. SHOW ARGUMENTS Display arguments to current macro. SHOW ARRAYS Display information about active arrays. SHOW COUNT Display current COUNT value. SHOW FUNCTIONS List names of available \f() functions. 9 - 11 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt SHOW GLOBALS List defined global variables \%a..\%z. SHOW MACROS List one or more macro definitions. SHOW SCRIPTS Show script-related settings. SHOW VARIABLES Display values all \v() variables. SLEEP Sleep for given number of seconds. STOP Stop executing macro or command file, return to prompt. UNDEFINE Undefine a variable. WAIT Wait for the specified modem signals. WHILE Execute commands repeatedly while a condition is true. WRITE Write material to a local file. WRITE-LINE Write a line (record) to a local file. WRITELN Synonym for WRITE-LINE. XECHO Like ECHO but no CRLF at end. XIF Extended IF command. BBBBUUUUIIIILLLLTTTT----IIIINNNN VVVVAAAARRRRIIIIAAAABBBBLLLLEEEESSSS Built-in variables are referred to by \v(name), can be used in any command, usually used in script programming. They cannot be changed. Type SHOW VARIABLES for a current list. \v(argc) Number of arguments in current macro \v(args) Number of program command-line arguments \v(charset) Current file character-set \v(cmdfile) Name of current command file, if any \v(cmdlevel) Current command level \v(cmdsource) Where command are currently coming from, macro, file, etc. \v(cols) Number of screen columns \v(connection) Connection type: serial, tcp/ip, etc. \v(count) Current COUNT value \v(cps) Speed of most recent file transfer in chars per second \v(cpu) CPU type C-Kermit was built for \v(crc16) 16-bit CRC of most recent file transfer \v(d$ac) SET DIAL AREA-CODE value \v(d$cc) SET DIAL COUNTRY-CODE value \v(d$ip) SET DIAL INTL-PREFIX value \v(d$lc) SET DIAL LD-PREFIX value \v(date) Date as 8 Feb 1993 \v(day) Day of week \v(directory) Current/default directory \v(dialstatus) Return code from DIAL command (0 = OK, 22 = BUSY, etc.) \v(download) Current download directory if any \v(errno) Current "errno" (system error number) value \v(errstring) Error message string associated with errno 9 - 12 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt \v(evaluate) Result of most recent EVALUATE command \v(exitstatus) Current EXIT status (0 = good, nonzero = something failed) \v(filespec) Filespec given in most recent SEND/RECEIVE/GET command \v(fsize) Size of file most recently transferred \v(ftype) SET FILE TYPE value (text, binary) \v(home) Home directory \v(host) Computer host name (computer where C- Kermit is running) \v(input) Current INPUT buffer contents \v(inchar) Character most recently INPUT \v(incount) How many characters arrived during last INPUT \v(inidir) Directory where initialization file was found \v(instatus) Status of most recent INPUT command \v(line) Current communications device, set by LINE or HOST \v(local) 0 if in remote mode, 1 if in local mode \v(macro) Name of currently executing macro, if any \v(minput) Result of most recent MINPUT command \v(modem) Current modem type \v(m_aa_off) Modem command to turn autoanswer off \v(m_aa_on) Modem command to turn autoanswer on \v(m_dc_off) Modem command to turn data compression off \v(m_dc_on) Modem command to turn data compression on \v(m_dial) Telephone number most recently dialed \v(m_ec_off) Modem command to turn error correction off \v(m_ec_on) Modem command to turn error correction on \v(m_fc_hw) Modem command to turn hardware flow control on \v(m_fc_no) Modem command to turn flow control off \v(m_fc_sw) Modem command to turn software flow control on \v(m_hup) Modem command to hang up connection \v(m_init) Modem initialization string \v(m_pulse) Modem command to select pulse dialing \v(m_tone) Modem command to select tone dialing \v(ndate) Current date as 19930208 (yyyymmdd) \v(nday) Numeric day of week (0 = Sunday) \v(newline) System-independent newline character or sequence \v(ntime) Current local time in seconds since midnight (noon = 43200) 9 - 13 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt \v(packetlen) Current SET RECEIVE PACKET-LENGTH value \v(parity) Current parity setting \v(platform) Specific machine and/or operating system \v(program) Name of this program ("C-Kermit") \v(query) Result of most recent REMOTE QUERY command \v(protocol) Currently selected file transfer protocol \v(return) Most recent RETURN value \v(rows) Number of rows on the terminal screen \v(speed) Current speed, if known, or "unknown" \v(status) 0 or 1 (SUCCESS or FAILURE of previous command) \v(sysid) Kermit attribute code for system ID \v(system) UNIX \v(terminal) Terminal type \v(tfsize) Total size of file group most recently transferred \v(time) Time as 13:45:23 (hh:mm:ss) \v(tmpdir) Temporary directory \v(ttyfd) File descriptor of current communication device \v(version) Numeric version of Kermit, e.g. 501190. \v(window) Current window size (SET WINDOW value) BBBBUUUUIIIILLLLTTTT----IIIINNNN FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS Builtin functions are invoked as \Fname(args), can be used in any command, and are usually used in script programs. Type SHOW FUNCTIONS for a current list. \Fbasename(file) basename of file \Fbreak(s,c) left substring of s up to first occurrence of char c \Fcapitalize(s) uppercase first letter of s and lowercase the rest \Fcharacter(arg) convert numeric arg to character \Fchecksum(s) 32-bit arithmetic checksum of string s \Fcode(char) numeric code for character \Fcontents(v) return current definition of variable \Fcrc16(s) 16-bit CRC of string s \Fdate(filename) return file's modification date/time \Fdefinition(m) return current definition of macro \Feval(expr) evaluate arithmetic expression \Fexecute(m,a,b,..) execute macro "m" with arguments "a", "b", etc. \Ffiles(f) number of files matching file spec \Fhexify(s) translate s into a hexadecimal string \Findex(a1,a2,a3) position of string a2 in a1, starting at pos a3 \Fipaddress(s) returns first IP address from string s 9 - 14 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt \Flength(arg) length of the string "arg" \Fliteral(arg) copy argument literally, no evaluation \Flower(arg) convert to lower case \Flpad(text,n,c) left pad text to length n with char c \Fltrim(s) Trim whitespace from left of s \Fmax(a1,a2) max of two numbers \Fmin(a1,a2) min of two numbers \Fmodulus(n1,n2) modulus n2 of integer n1 \Fnextfile() next file name from list in last \Ffiles() \Fpathname(file) full pathname of file \Frepeat(a1,a2) repeat a1 a2 times \Freplace(a1,a2,a3) replace a2 by a3 in a1 \Freverse(arg) reverse characters in arg \Fright(a1,a2) rightmost a2 characters of string a1 \Frindex(a1,a2,a3) like \Findex, but searching from right \Frpad(text,n,c) right pad text to length n with char c \Fsize(filename) return file's length in bytes \Fspan(a1,a2) left substring of a1 containing only chars from a2 \Fsubstr(a1,a2,a3) substring of a1, starts at a2, length a3 \Ftod2secs(s) converts hh:mm:ss to seconds since midnight \Ftrim(s) removes trailing whitespace from s \Funhexify(s) converts a hexadecimal string s back to original \Fupper(s) converts s to upper case \Fverify(a1,a2,n) returns index of first char in a2 that is not in a1 starting at position n of a2. \Feval() allows the following operators in the expression. The expression can contain variables. Only integer arithmetic is supported. Precedences are shown as numbers, 1 is highest precedence, 6 is lowest. l l l. ( ) 1 parentheses n ! 2 factorial ~ n 3 logical NOT - n 4 negative n ^ n 4 power n * n 5 multiplication n / n 5 division n % n 5 modulus n & n 5 logical AND n + n 6 plus n - n 6 minus n | n 6 logical OR n # n 6 exclusive OR n @ n 6 greatest common divisor CCCCOOOOMMMMMMMMAAAANNNNDDDD LLLLIIIINNNNEEEE OOOOPPPPTTTTIIIIOOOONNNNSSSS C-Kermit accepts commands (or "options") on the command line, in the time-honored UNIX style. Alphabetic case is significant. All options are optional. If one or more action options are included, Kermit exits immediately after executing the command-line options, otherwise it enters interactive command mode. 9 - 15 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt kermit [_f_i_l_e_n_a_m_e] [-_x _a_r_g [-_x _a_r_g]...[-_y_y_y]...]] where: _f_i_l_e_n_a_m_e is the name of a command file to execute, ----_x is an option requiring an argument, ----_y an option with no argument. AAAAccccttttiiiioooonnnnssss -s files send files -s - send files from stdin -r receive files -k receive files to stdout -x enter server mode -f finish remote server -g files get remote files from server (quote wildcards) -a name alternate file name, used with -s, -r, -g -c connect (before file transfer), used with -l or -j -n connect (after file transfer), used with -l or -j SSSSeeeettttttttiiiinnnnggggssss -l line communication line device (to make a serial connection) -l n open file descriptor of communication device -j host TCP/IP network host name (to make a network connection) -J host connect like TELNET, exit when connection closes -l n open file descriptor of TCP/IP connection (n = number) -X X.25 network address -Z open file descriptor of X.25 connection -o n X.25 closed user group call info -u X.25 reverse-charge call -q quiet during file transfer -8 8-bit clean -i transfer files in binary mode -T transfer files in text mode -b bps serial line speed, e.g. 1200 -m name modem type, e.g. hayes -p x parity, x = e,o,m,s, or n -t half duplex, xon handshake -e n receive packet-length -v n window size 9 - 16 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt -Q Quick file-transfer settings -w write over files of same name, do not backup old file -D n delay n seconds before sending a file OOOOtttthhhheeeerrrr -y name alternate init file name -Y Skip init file -R Advise C-Kermit it will be used only in remote mode -d log debug info to file debug.log -S Stay, do not exit, after action command -C "cmds" Interactive-mode commands, comma- separated -z Force foreground operation -B Force background (batch) operation -h print command-line option help screen = Ignore all text that follows EEEExxxxaaaammmmpppplllleeeessss Remote-mode example (C-Kermit is on the far end): send file ooooooooffffaaaa....bbbbiiiinnnn in binary mode (----iiii) using a window size of 4 (----vvvv 4444): kkkkeeeerrrrmmmmiiiitttt ----vvvv 4444 ----iiii ----ssss ooooooooffffaaaa....bbbbiiiinnnn Local-mode example (C-Kermit makes the connection): make a 19200-bps direct connection out through ////ddddeeeevvvv////ttttttttyyyy0000pppp0000, CONNECT (----cccc) so you can log in and, presumably start a remote Kermit program and tell it to send a file, RECEIVE the file (----rrrr), then CONNECT back (----nnnn) so you can finish up and log out: kkkkeeeerrrrmmmmiiiitttt ----llll ////ddddeeeevvvv////ttttttttyyyy0000pppp0000 ----bbbb 11119999222200000000 ----cccc ----rrrr ----nnnn For dialing out, you must specify a modem type, and you might have to use a different device name: kkkkeeeerrrrmmmmiiiitttt ----mmmm hhhhaaaayyyyeeeessss ----llll ////ddddeeeevvvv////ccccuuuullll0000pppp0000 ----bbbb 2222444400000000 ----cccc ----rrrr ----nnnn FFFFIIIILLLLEEEESSSS $$$$HHHHOOOOMMMMEEEE////....mmmmyyyykkkkeeeerrrrmmmmrrrrcccc Your personal C- Kermit customization file. $$$$HHHHOOOOMMMMEEEE////....kkkkdddddddd Your personal dialing directory. $$$$HHHHOOOOMMMMEEEE////....kkkkssssdddd Your personal services directory. ////uuuussssrrrr////sssshhhhaaaarrrreeee////lllliiiibbbb////kkkkeeeerrrrmmmmiiiitttt////RRRREEEEAAAADDDD....MMMMEEEE Overview of HP-UX C-Kermit, please read ////uuuussssrrrr////sssshhhhaaaarrrreeee////lllliiiibbbb////kkkkeeeerrrrmmmmiiiitttt////cccckkkkeeeerrrrmmmmiiiitttt....iiiinnnniiii System-wide initialization file 9 - 17 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt ////uuuussssrrrr////sssshhhhaaaarrrreeee////lllliiiibbbb////kkkkeeeerrrrmmmmiiiitttt////cccckkkkeeeerrrrmmmmoooodddd....iiiinnnniiii Sample customization file ////uuuussssrrrr////sssshhhhaaaarrrreeee////lllliiiibbbb////kkkkeeeerrrrmmmmiiiitttt////cccckkkkeeeerrrrmmmmiiiitttt....kkkkdddddddd Sample dialing directory ////uuuussssrrrr////sssshhhhaaaarrrreeee////lllliiiibbbb////kkkkeeeerrrrmmmmiiiitttt////cccckkkkeeeerrrrmmmmiiiitttt....kkkkssssdddd Sample services directory ////uuuussssrrrr////sssshhhhaaaarrrreeee////lllliiiibbbb////kkkkeeeerrrrmmmmiiiitttt////cccckkkkcccckkkkeeeerrrr....uuuuppppdddd Supplement to "Using C-Kermit" ////uuuussssrrrr////sssshhhhaaaarrrreeee////lllliiiibbbb////kkkkeeeerrrrmmmmiiiitttt////cccckkkkcccckkkkeeeerrrr....bbbbwwwwrrrr C-Kermit "beware" file - hints & tips ////uuuussssrrrr////sssshhhhaaaarrrreeee////lllliiiibbbb////kkkkeeeerrrrmmmmiiiitttt////cccckkkkuuuukkkkeeeerrrr....bbbbwwwwrrrr UNIX-specific beware file ////uuuussssrrrr////sssshhhhaaaarrrreeee////lllliiiibbbb////kkkkeeeerrrrmmmmiiiitttt////cccckkkkeeeeddddeeeemmmmoooo....iiiinnnniiii Macros from "Using C-Kermit" ////uuuussssrrrr////sssshhhhaaaarrrreeee////lllliiiibbbb////kkkkeeeerrrrmmmmiiiitttt////cccckkkkeeeevvvvtttt....iiiinnnniiii Macros from "Using C-Kermit" ////uuuussssrrrr////sssshhhhaaaarrrreeee////lllliiiibbbb////kkkkeeeerrrrmmmmiiiitttt////cccckkkkeeeeppppaaaaggggeeeerrrr....kkkksssscccc Alpha pager script ////vvvvaaaarrrr////ssssppppoooooooollll////lllloooocccckkkkssss////LLLLCCCCKKKK........**** UUCP lockfiles To make copy the file /usr/share/lib/kermit/ckermod.ini file to your home directory, make any desired changes, and rename it to ....mmmmyyyykkkkeeeerrrrmmmmrrrrcccc. You may also create a personalized like the sample one in /usr/share/lib/kermit/ckermit.kdd. Your personalized dialing directory should be stored in your home directory as ....kkkkdddddddd and your personal network directory as ....kkkknnnndddd. See Chapters 5 and 6 of for details. And you may also create a personalized like the sample one in /usr/share/lib/kermit/ckermit.ksd. Your personalized services directory should be stored in your home directory as ....kkkkssssdddd. See Chapter 7 of for instructions. The demonstration files illustrate C-Kermit's script programming constructs; they are discussed in chapters 17-19 of the book. You can run them by typing the appropriate TAKE command at the C-Kermit> prompt, for example: "take /usr/share/lib/kermit/ckedemo.ini". AAAAUUUUTTTTHHHHOOOORRRRSSSS Frank da Cruz, Columbia University, with contributions from hundreds of other volunteer programmers all over the world. See Acknowledgements in RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEESSSS Frank da Cruz and Christine M. Gianone, Second Edition, 1997, 622 pages, Digital Press / Butterworth- Heinemann, 225 Wildwood Street, Woburn, MA 01801, USA. ISBN 1- 55558-164-1. (In the USA, call +1 800 366-2665 to order Digital Press books.) Also available in a German edition from Verlag Heinze Heise, Hannover. 9 - 18 - Formatted: January 24, 1997 kkkkeeeerrrrmmmmiiiitttt((((1111)))) kkkkeeeerrrrmmmmiiiitttt((((1111)))) 9 HHHHPPPP----UUUUXXXX CCCC----KKKKeeeerrrrmmmmiiiitttt Frank da Cruz, Digital Press / Butterworth-Heinemann, Woburn, MA, USA (1987). ISBN 0-932376-88-6. The Kermit file transfer protocol specification. Christine M. Gianone, Digital Press / Butterworth-Heinemann, Woburn, MA, USA (1992). ISBN 1-5558-082-3. Also available in a German edition from Heise, and a French edition from Heinz Schiefer & Cie, Versailles. Issues 4 (1990) and 5 (1993), Columbia University, for detailed discussions of Kermit file transfer performance. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS The diagnostics produced by _C-_K_e_r_m_i_t itself are intended to be self- explanatory. In addition, every command returns a SUCCESS or FAILURE status that can be tested by IF FAILURE or IF SUCCESS. In addition, the program itself returns an exit status code of 0 upon successful operation or nonzero if any of various operations failed. BBBBUUUUGGGGSSSS See the comp.protocols.kermit.* newsgroups on Usenet for discussion, or the files, ckcker.bwr and ckuker.bwr, for a list of bugs, hints, tips. etc. Report bugs via e-mail to kkkkeeeerrrrmmmmiiiitttt----ssssuuuuppppppppoooorrrrtttt@@@@ccccoooolllluuuummmmbbbbiiiiaaaa....eeeedddduuuu. CCCCOOOONNNNTTTTAAAACCCCTTTTSSSS For more information about Kermit software and documentation, visit the Kermit Web site: hhhhttttttttpppp::::////////wwwwwwwwwwww....ccccoooolllluuuummmmbbbbiiiiaaaa....eeeedddduuuu////kkkkeeeerrrrmmmmiiiitttt//// Or write to: The Kermit Project Columbia University 612 West 115th Street New York, NY 10025-7221 USA Or send e-mail to kkkkeeeerrrrmmmmiiiitttt@@@@ccccoooolllluuuummmmbbbbiiiiaaaa....eeeedddduuuu. Or call +1 212 854-3703. Or fax +1 212 663-8202. 9 - 19 - Formatted: January 24, 1997 nnnniiiicccceeee((((1111)))) nnnniiiicccceeee((((1111)))) NNNNAAAAMMMMEEEE nice - run a command at nondefault priority SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS nnnniiiicccceeee [----_p_r_i_o_r_i_t_y__c_h_a_n_g_e] _c_o_m_m_a_n_d [_c_o_m_m_a_n_d__a_r_g_s] nnnniiiicccceeee [----nnnn _p_r_i_o_r_i_t_y__c_h_a_n_g_e] _c_o_m_m_a_n_d [_c_o_m_m_a_n_d__a_r_g_s] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The nnnniiiicccceeee command executes _c_o_m_m_a_n_d at a nondefault CPU scheduling priority. (The name is derived from being "nice" to other system users by running large programs at lower priority.) AAAArrrrgggguuuummmmeeeennnnttttssss The command-line arguments are as follows: ----nnnn _p_r_i_o_r_i_t_y__c_h_a_n_g_e _p_r_i_o_r_i_t_y__c_h_a_n_g_e The difference between the system nice value (relative priority) of the current (or parent) process and the actual system nice value at which _c_o_m_m_a_n_d is to run. An unsigned value increases the system nice value for _c_o_m_m_a_n_d, causing it to run at lower priority. A negative value requires superuser privileges, and assigns a lower system nice value (higher priority) to _c_o_m_m_a_n_d. If the current process is not privileged, the value is silently treated as if it were 0. If the value of _p_r_i_o_r_i_t_y__c_h_a_n_g_e would result in a system nice value outside the range 0 through 39, the corresponding limit value of 0 or 39 is used instead. Note that a positive _p_r_i_o_r_i_t_y__c_h_a_n_g_e (lower priority) has a single ---- option character before the numeric value; a negative (higher priority) _p_r_i_o_r_i_t_y__c_h_a_n_g_e has two: the option character followed by the minus sign (--------). If ---- _p_r_i_o_r_i_t_y__c_h_a_n_g_e is not specified, it defaults to 11110000. _c_o_m_m_a_n_d A program, HP-UX command, user shell script, etc. to be executed at the nondefault priority. _c_o_m_m_a_n_d can be run as a foreground or background process. If _c_o_m_m_a_n_d is run as a background process, any nice _p_r_i_o_r_i_t_y__c_h_a_n_g_e made by the shell (kkkksssshhhh Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 nnnniiiicccceeee((((1111)))) nnnniiiicccceeee((((1111)))) executes all background processes via nnnniiiicccceeee ----4444) is in addition to that specified in the nnnniiiicccceeee command line. _c_o_m_m_a_n_d__a_r_g_s Any arguments recognized by _c_o_m_m_a_n_d. PPPPrrrroooocccceeeessssssss PPPPrrrriiiioooorrrriiiittttiiiieeeessss All processes have an associated system nice value which is used to compute the instantaneous-priority of the process when it is scheduled to run. Normally, all processes inherit the system nice value of their parent process when they are spawned. The shell (sssshhhh, ccccsssshhhh, kkkksssshhhh, etc.) can create a child process with a different priority from the current shell process by spawning the child process via the nnnniiiicccceeee command. If the _p_r_i_o_r_i_t_y__c_h_a_n_g_e value is unsigned (positive), the child process is nicer (lower in priority) relative to the parent. If the _p_r_i_o_r_i_t_y__c_h_a_n_g_e value is negative, the child process runs at a higher priority with a greater share of available system resources. To spawn a higher priority child process, the parent process must be owned by a user who has the appropriate privileges. At boot-up, the system starts the iiiinnnniiiitttt process at a system nice value of 20 (system default). On most systems, all processes (down to the login shells) inherit this priority. Starting from their individual login shell processes, users can alter the system nice value of descendent processes to as much as 39, or, with appropriate privileges, as little as 0. A system nice value of 0 establishes an extremely high priority, whereas a value of 39 indicates a very low priority. Ordinary users can only increase the system nice value of any child process relative to the current process; i.e., _p_r_i_o_r_i_t_y__c_h_a_n_g_e must be a positive (unsigned) value, resulting in a lower priority. To start a child process at a lower system nice value (higher priority) than the current process, the user must have the appropriate privileges, regardless of the relative nice-priority value desired. For example, using the command nnnniiiicccceeee kkkksssshhhh from a login shell whose current nice value is 20 spawns a subshell with a system nice value of 30. Attempting to use nnnniiiicccceeee --------2222 kkkksssshhhh from the new shell to spawn another subshell whose system nice value would be 28, is rejected (unless the user has appropriate privileges), even though the resulting system nice value would be less than the priority of the original login shell process. Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 nnnniiiicccceeee((((1111)))) nnnniiiicccceeee((((1111)))) The system nice value for current processes is listed under the NNNNIIII column produced by the ppppssss ----llll command (see ppppssss(1)). BBBBaaaacccckkkkggggrrrroooouuuunnnndddd PPPPrrrroooocccceeeesssssssseeeessss Foreground processes are run at same system nice value as the parent shell. Background processes spawned by kkkksssshhhh run at the equivalent of a nnnniiiicccceeee ----4444 by default. If a background process is started via nnnniiiicccceeee from kkkksssshhhh, any _p_r_i_o_r_i_t_y__c_h_a_n_g_e specified in the nnnniiiicccceeee command is added to default nnnniiiicccceeee ----4444. Thus the command nnnniiiicccceeee 11112222 _c_o_m_m_a_n_d &&&& runs at a system nice value of 36 if executed from kkkksssshhhh. EEEEXXXXTTTTEEEERRRRNNNNAAAALLLL IIIINNNNFFFFLLLLUUUUEEEENNNNCCCCEEEESSSS EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt VVVVaaaarrrriiiiaaaabbbblllleeeessss LLLLCCCC____MMMMEEEESSSSSSSSAAAAGGGGEEEESSSS determines the language in which messages are displayed. If LLLLCCCC____MMMMEEEESSSSSSSSAAAAGGGGEEEESSSS is not specified in the environment or is set to the empty string, the value of LLLLAAAANNNNGGGG is used as a default for each unspecified or empty variable. If LLLLAAAANNNNGGGG is not specified or is set to the empty string, a default of "C" (see _l_a_n_g(5)) is used instead of LLLLAAAANNNNGGGG. If any internationalization variable contains an invalid setting, nnnniiiicccceeee behaves as if all internationalization variables are set to "C". See _e_n_v_i_r_o_n(5). IIIInnnntttteeeerrrrnnnnaaaattttiiiioooonnnnaaaallll CCCCooooddddeeee SSSSeeeetttt SSSSuuuuppppppppoooorrrrtttt Single- and multi-byte character code sets are supported. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE nnnniiiicccceeee returns the value returned by _c_o_m_m_a_n_d. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS The following examples assume the current process is running with a system nice value of 20 and nnnniiiicccceeee is executed from the Korn shell (see kkkksssshhhh(1)). Run a program named pppprrrroooogggg in the current directory at the default _p_r_i_o_r_i_t_y__c_h_a_n_g_e of 10 (system nice value of 30): nnnniiiicccceeee ....////pppprrrroooogggg _p_r_o_g__a_r_g_s Run the same program in the background using a system nice value of 36 (_p_r_i_o_r_i_t_y__c_h_a_n_g_e=12 plus 4 for the Korn shell): nnnniiiicccceeee ----11112222 ....////pppprrrroooogggg _p_r_o_g__a_r_g_s &&&& As a user with appropriate privileges, run pppprrrroooogggg as a foreground process with a system nice value of 6: Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 nnnniiiicccceeee((((1111)))) nnnniiiicccceeee((((1111)))) nnnniiiicccceeee --------11114444 ....////pppprrrroooogggg _p_r_o_g__a_r_g_s WWWWAAAARRRRNNNNIIIINNNNGGGGSSSS The C shell, ccccsssshhhh, has a built-in nnnniiiicccceeee command with different syntax. See ccccsssshhhh(1) for details. SSSSEEEEEEEE AAAALLLLSSSSOOOO csh(1), ksh(1), nohup(1), renice(1), nice(2). SSSSTTTTAAAANNNNDDDDAAAARRRRDDDDSSSS CCCCOOOONNNNFFFFOOOORRRRMMMMAAAANNNNCCCCEEEE nnnniiiicccceeee: SVID2, SVID3, XPG4 Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 ppppaaaasssssssswwwwdddd((((1111)))) ppppaaaasssssssswwwwdddd((((1111)))) NNNNAAAAMMMMEEEE passwd - change login password SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ppppaaaasssssssswwwwdddd [----FFFF _f_i_l_e] [_n_a_m_e] ppppaaaasssssssswwwwdddd [----ffff] [----nnnn _m_i_n] [----xxxx _m_a_x] [----wwww _w_a_r_n] _n_a_m_e DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The ppppaaaasssssssswwwwdddd command installs or changes the password associated with the login _n_a_m_e. If _n_a_m_e is omitted, it defaults to the invoking user's login name. ppppaaaasssssssswwwwdddd uses _g_e_t_l_o_g_i_n(3C) to determine the invoking user's name. The default password file is ////eeeettttcccc////ppppaaaasssssssswwwwdddd. You can use the ----FFFF option to choose an alternate password file. You must have read and write permission for the alternate file. Ordinary users can change only the password corresponding to their own login _n_a_m_e. If there is an old password, ppppaaaasssssssswwwwdddd prompts for it. Then it prompts for the new password twice. The first time the new password is entered, ppppaaaasssssssswwwwdddd checks to see if the old password has "aged" sufficiently. If "aging" is insufficient, the new password is rejected and ppppaaaasssssssswwwwdddd terminates; see _p_a_s_s_w_d(4). Assuming "aging" is sufficient, a check is made to ensure that the new password meets construction requirements. When the new password is entered a second time, the two copies of the new password are compared. If the two copies differ, ppppaaaasssssssswwwwdddd repeats the cycle of prompting for the new password, at most twice. Passwords must be constructed to meet the following requirements: o+ A password must have at least six characters. Only the first eight characters are significant in an untrusted system. o+ Characters must be from the 7-bit USASCII character set; letters from the English alphabet. o+ A password must contain at least two uppercase and/or lowercase letters and at least one numeric or special character. o+ A password must differ from the user's login _n_a_m_e and any reverse or circular shift of that login _n_a_m_e. For comparison purposes, an uppercase letter and its corresponding lowercase equivalent are treated as identical. o+ A new password must differ from the old one by at least three characters (one character in a trusted system). For comparison purposes, an uppercase letter and its corresponding Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 ppppaaaasssssssswwwwdddd((((1111)))) ppppaaaasssssssswwwwdddd((((1111)))) lowercase equivalent are treated as identical. A superuser is a user whose effective user ID is zero; see _i_d(1), and _s_u(1). Superusers can change any password and are not forced to comply with password aging. In an untrusted system superusers are not forced to comply with password construction requirements, and ppppaaaasssssssswwwwdddd does not prompt a superuser for the old password. A superuser can create a null password by entering a carriage return in response to the prompt for a new password. A superuser can also modify password aging characteristics associated with the user _n_a_m_e using the following options: ----ffff This option forces the user to enter a new password on the next login. ----nnnn _m_i_n This option determines the minimum number of days, _m_i_n, that must transpire before the user can change the password. ----wwww _w_a_r_n This option specifies the number of days, _w_a_r_n, prior to the password expiring when the user will be notified that the password needs to be changed. This option is only enabled when your system has been converted to a trusted, secure system. Refer to the _H_P-_U_X _S_y_s_t_e_m _A_d_m_i_n_i_s_t_r_a_t_i_o_n _T_a_s_k_s _M_a_n_u_a_l on how to convert your HP-UX to a trusted, secure system. ----xxxx _m_a_x This option determines the maximum number of days, _m_a_x, a password can remain unchanged. The user must enter another password after that number of days has transpired, known as the password _e_x_p_i_r_a_t_i_o_n _t_i_m_e . The _m_i_n and _m_a_x arguments are each represented in units of days. These arguments will be rounded up to the nearest week on a non- trusted HP-UX system. If your system is then converted to a trusted system, the number of days will be based on those weeks. If you only supply one of the two arguments, ppppaaaasssssssswwwwdddd checks to see if the other one already exists. If it does not exist, then it defaults it to zero for you. NNNNEEEETTTTWWWWOOOORRRRKKKKIIIINNNNGGGG FFFFEEEEAAAATTTTUUUURRRREEEESSSS ppppaaaasssssssswwwwdddd can use the HP-UX Integrated Login Library, if configured. For a complete description of using and administering HP-UX Integrated Login, see _a_u_t_h(5) and _a_u_t_h._a_d_m_i_n(1M). HP-UX Integrated Login typically uses the Distributed Computing Environment (DCE) for its user registry. For a complete description of the DCE user registry and its relationship with HP-UX Integrated Login, see _a_u_t_h._d_c_e(5). Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 ppppaaaasssssssswwwwdddd((((1111)))) ppppaaaasssssssswwwwdddd((((1111)))) SSSSEEEECCCCUUUURRRRIIIITTTTYYYY FFFFEEEEAAAATTTTUUUURRRREEEESSSS This section applies only to a trusted system. It describes additional capabilities and restrictions. Additional restrictions which apply to superusers include: prompted for supersuer passwords, null passwords must have been allowed explicitly, all other password construction requirements, and prompted for "user number", if it exists. When you use ppppaaaasssssssswwwwdddd on a trusted system, the system prompts for the existing password (if any), and begins a password solicitation dialog that depends on the type of password generation the system administrator has enabled on your account. There are four possible options for password generation: oooo++++ rrrraaaannnnddddoooommmm ssssyyyyllllllllaaaabbbblllleeeessss:::: A pronounceable password made up of meaningless syllables. oooo++++ rrrraaaannnnddddoooommmm cccchhhhaaaarrrraaaacccctttteeeerrrrssss:::: An unpronounceable password made up of random characters from the character set. oooo++++ rrrraaaannnnddddoooommmm lllleeeetttttttteeeerrrrssss:::: An unpronounceable password made up of random letters from the alphabet. oooo++++ uuuusssseeeerrrr----ssssuuuupppppppplllliiiieeeedddd:::: A user-supplied password, subject to length and triviality restrictions. Passwords can be longer than eight characters. The system administrator specifies a maximum password length guideline for the 3 system generated options. The minimum password length depends on several parameters that the system administrator sets in the authentication databases. The system warns you if you choose a password that is too short or too long. The system requires a _m_i_n_i_m_u_m _t_i_m_e to elapse before you can change a password. This prevents you from reusing an old password too soon. A password expires after a period of time known as the _e_x_p_i_r_a_t_i_o_n _t_i_m_e. The system warns you when the expiration time is drawing near. A password dies after a period of time known as the _p_a_s_s_w_o_r_d _l_i_f_e_t_i_m_e. After the lifetime passes, the account is locked until the system administrator re-enables it. After unlocking, you must change your password again before you can use your account. The system administrator can individually enable accounts with no passwords. If your account can be run without a password, and if you are allowed to pick your password, you can type carriage-return at the NNNNeeeewwww ppppaaaasssssssswwwwoooorrrrdddd:::: prompt. Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 ppppaaaasssssssswwwwdddd((((1111)))) ppppaaaasssssssswwwwdddd((((1111)))) You can change your own password if the system administrator has enabled any of the password generation options for your account. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS Change the password expiration date of uuuusssseeeerrrr to 42 days: ppppaaaasssssssswwwwdddd ----xxxx 44442222 uuuusssseeeerrrr Change the minimum time between password changes of uuuusssseeeerrrr1111 to 7 days: ppppaaaasssssssswwwwdddd ----nnnn 7777 uuuusssseeeerrrr1111 Force uuuusssseeeerrrr2222 to establish a new password on the next login that will expire in 70 days and prohibit the user from changing the password until 7 days have transpired: ppppaaaasssssssswwwwdddd ----ffff ----xxxx 77770000 ----nnnn 7777 uuuusssseeeerrrr2222 EEEEXXXXTTTTEEEERRRRNNNNAAAALLLL IIIINNNNFFFFLLLLUUUUEEEENNNNCCCCEEEESSSS IIIInnnntttteeeerrrrnnnnaaaattttiiiioooonnnnaaaallll CCCCooooddddeeee SSSSeeeetttt SSSSuuuuppppppppoooorrrrtttt Characters from single-byte character code sets are supported in passwords. FFFFIIIILLLLEEEESSSS ////eeeettttcccc////ppppaaaasssssssswwwwdddd Standard password file used by HP-UX. ////ttttccccbbbb////ffffiiiilllleeeessss////aaaauuuutttthhhh////****////**** Protected password database used when system is converted to trusted system. SSSSEEEEEEEE AAAALLLLSSSSOOOO auth(5), auth.adm(1M), auth.dce(5), chfn(1), id(1), login(1), su(1), crypt(3C), getlogin(3C), passwd(4). SSSSTTTTAAAANNNNDDDDAAAARRRRDDDDSSSS CCCCOOOONNNNFFFFOOOORRRRMMMMAAAANNNNCCCCEEEE ppppaaaasssssssswwwwdddd: SVID2, SVID3, XPG2 Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 qqqquuuuoooottttaaaa((((1111)))) qqqquuuuoooottttaaaa((((1111)))) NNNNAAAAMMMMEEEE quota - display disk usage and limits SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS qqqquuuuoooottttaaaa [----vvvv] [_u_s_e_r ... ] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The qqqquuuuoooottttaaaa command displays the disk usage and limits for one or more _u_s_e_rs. Without the ----vvvv option, it displays information only when the usage exceeds the limits. _u_s_e_r is a user name or a numeric UID. The default is the login user name. Only users with appropriate privileges can view the limits of other users. OOOOppppttttiiiioooonnnnssss The qqqquuuuoooottttaaaa command recognizes the following option: ----vvvv Display the statistics whether they exceed limits or not. Note that no usage statistics exist if no quota is set. EEEEXXXXTTTTEEEERRRRNNNNAAAALLLL IIIINNNNFFFFLLLLUUUUEEEENNNNCCCCEEEESSSS EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt VVVVaaaarrrriiiiaaaabbbblllleeeessss LLLLCCCC____MMMMEEEESSSSSSSSAAAAGGGGEEEESSSS determines the language in which messages are displayed. If LLLLCCCC____MMMMEEEESSSSSSSSAAAAGGGGEEEESSSS is not specified in the environment or is set to the empty string, the value of LLLLAAAANNNNGGGG is used as a default for each unspecified or empty variable. If LLLLAAAANNNNGGGG is not specified or is set to the empty string, a default of "C" (see _l_a_n_g(5)) is used instead of LLLLAAAANNNNGGGG. If any internationalization variable contains an invalid setting, qqqquuuuoooottttaaaa behaves as if all internationalization variables are set to "C". See _e_n_v_i_r_o_n(5). IIIInnnntttteeeerrrrnnnnaaaattttiiiioooonnnnaaaallll CCCCooooddddeeee SSSSeeeetttt SSSSuuuuppppppppoooorrrrtttt Single- and multi-byte character code sets are supported. AAAAUUUUTTTTHHHHOOOORRRR Disk Quotas were developed by the University of California, Berkeley, Sun Microsystems, Inc., and HP. FFFFIIIILLLLEEEESSSS _d_i_r_e_c_t_o_r_y////qqqquuuuoooottttaaaassss Quota statistics static storage for a file system, where _d_i_r_e_c_t_o_r_y is the root of the file system as specified to the mmmmoooouuuunnnntttt command (see _m_o_u_n_t(1M)). ////eeeettttcccc////mmmmnnnnttttttttaaaabbbb List of currently mounted file systems Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 qqqquuuuoooottttaaaa((((1111)))) qqqquuuuoooottttaaaa((((1111)))) SSSSEEEEEEEE AAAALLLLSSSSOOOO quota(5). Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 uuuummmmaaaasssskkkk((((1111)))) uuuummmmaaaasssskkkk((((1111)))) NNNNAAAAMMMMEEEE umask - set or display the file mode creation mask SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS _S_e_t _M_a_s_k:::: uuuummmmaaaasssskkkk _m_a_s_k _D_i_s_p_l_a_y _M_a_s_k:::: uuuummmmaaaasssskkkk [----SSSS] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The uuuummmmaaaasssskkkk command sets the value of the file mode creation mask or displays the current one. The mask affects the initial value of the file mode (permission) bits for subsequently created files. SSSSeeeettttttttiiiinnnngggg tttthhhheeee FFFFiiiilllleeee MMMMooooddddeeee CCCCrrrreeeeaaaattttiiiioooonnnn MMMMaaaasssskkkk The uuuummmmaaaasssskkkk _m_a_s_k command sets a new file mode creation mask for the current shell execution environment. _m_a_s_k can be a symbolic or numeric (obsolescent) value. A symbolic mask provides a flexible way of modifying the mask permission bits individually or as a group. A numeric mask specifies all the permission bits at one time. When a mask is specified, no output is written to standard output. SSSSyyyymmmmbbbboooolllliiiicccc MMMMaaaasssskkkk VVVVaaaalllluuuueeee A symbolic _m_a_s_k replaces or modifies the current file mode creation mask. It is specified as specified as a comma-separated list of operations in the following format. Whitespace is not permitted. [_w_h_o][_o_p_e_r_a_t_o_r][_p_e_r_m_i_s_s_i_o_n_s][,...] The fields can have the following values: _w_h_o One or more of the following letters: uuuu Modify permissions for user (owner). gggg Modify permissions for group. oooo Modify permissions for others. Or: aaaa Modify permissions for all (aaaa = uuuuggggoooo). _o_p_e_r_a_t_o_r One of the following symbols: ++++ Add _p_e_r_m_i_s_s_i_o_n_s to the existing mask for _w_h_o. Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 uuuummmmaaaasssskkkk((((1111)))) uuuummmmaaaasssskkkk((((1111)))) ---- Delete _p_e_r_m_i_s_s_i_o_n_s from the existing mask for _w_h_o. ==== Replace the existing mask for _w_h_o with _p_e_r_m_i_s_s_i_o_n_s. _p_e_r_m_i_s_s_i_o_n_s One or more of the following letters: rrrr The read permission. wwww The write permission. xxxx The execute/search permission. If one or two of the fields are omitted, the following table applies: FFFFoooorrrrmmmmaaaatttt EEEEnnnntttteeeerrrreeeedddd EEEEffffffffeeeecccctttt | IIIInnnnppppuuuutttt EEEEqqqquuuuaaaallllssss __________________________________________________________|_______________ _w_h_o Delete current permissions for _w_h_o | gggg gggg==== _o_p_e_r_a_t_o_r No action | ---- (none) _p_e_r_m_i_s_s_i_o_n_s Equal to: aaaa++++_p_e_r_m_i_s_s_i_o_n_s | rrrrwwww aaaa++++rrrrwwww _w_h_o==== Delete current permissions for _w_h_o | uuuu==== uuuu==== _w_h_o++++ No action | uuuu++++ (none) _w_h_o---- No action | uuuu---- (none) _w_h_o_p_e_r_m_i_s_s_i_o_n_s Equal to: _w_h_o====_p_e_r_m_i_s_s_i_o_n_s | uuuuxxxx uuuu====xxxx _o_p_e_r_a_t_o_r_p_e_r_m_i_s_s_i_o_n_s Equal to: aaaa_o_p_e_r_a_t_o_r_p_e_r_m_i_s_s_i_o_n_s | ----rrrrwwww aaaa----rrrrwwww NNNNuuuummmmeeeerrrriiiicccc MMMMaaaasssskkkk VVVVaaaalllluuuueeee ((((OOOObbbbssssoooolllleeeesssscccceeeennnntttt)))) A numeric _m_a_s_k replaces the current file mode creation mask. It is specified as an unsigned octal integer, constructed from the logical OR (sum) of the following mode bits (leading zeros can be omitted): 0000444400000000 ( aaaa====rrrrwwwwxxxx,,,,uuuu----rrrr) Read by owner 0000222200000000 ( aaaa====rrrrwwwwxxxx,,,,uuuu----wwww) Write by owner 0000111100000000 ( aaaa====rrrrwwwwxxxx,,,,uuuu----xxxx) Execute (search in directory) by owner 0000000044440000 ( aaaa====rrrrwwwwxxxx,,,,gggg----rrrr) Read by group 0000000022220000 ( aaaa====rrrrwwwwxxxx,,,,gggg----wwww) Write by group 0000000011110000 ( aaaa====rrrrwwwwxxxx,,,,gggg----xxxx) Execute/search by group 0000000000004444 ( aaaa====rrrrwwwwxxxx,,,,oooo----rrrr) Read by others 0000000000002222 ( aaaa====rrrrwwwwxxxx,,,,oooo----wwww) Write by others 0000000000001111 ( aaaa====rrrrwwwwxxxx,,,,oooo----xxxx) Execute/search by others DDDDiiiissssppppllllaaaayyyyiiiinnnngggg tttthhhheeee CCCCuuuurrrrrrrreeeennnntttt MMMMaaaasssskkkk VVVVaaaalllluuuueeee To display the current file mode creation mask value, use one of the commands: uuuummmmaaaasssskkkk ----SSSS Print the current file mode creation mask in a symbolic format: uuuu====[rrrr][wwww][xxxx],,,,gggg====[rrrr][wwww][xxxx],,,,oooo====[rrrr][wwww][xxxx] The characters rrrr (read), wwww (write), and xxxx (execute/search) represent the bits that are clear Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 uuuummmmaaaasssskkkk((((1111)))) uuuummmmaaaasssskkkk((((1111)))) in the mask for uuuu (user/owner), gggg (group), and oooo (other). All other bits are set. uuuummmmaaaasssskkkk Print the current file mode creation mask as an octal value. The zero bits in the numeric value correspond to the displayed rrrr, wwww, and xxxx permission characters in the symbolic value. The one bits in the numeric value correspond to the missing permission characters in the symbolic value. Depending on implementation, the display consists of one to four octal digits; the first digit is always zero (see DEPENDENCIES). The rightmost three digits (leading zeros implied as needed) represent the bits that are set or clear in the mask. Both forms produce output that can be used as the _m_a_s_k argument to set the mask in a subsequent uuuummmmaaaasssskkkk command. GGGGeeeennnneeeerrrraaaallll OOOOppppeeeerrrraaaattttiiiioooonnnn When a new file is created (see _c_r_e_a_t(2)), each bit that is set in the file mode creation mask causes the corresponding permission bit in the the file mode to be cleared (disabled). Conversely, bits that are clear in the mask allow the corresponding file mode bits to be enabled in newly created files. For example, the mask uuuu====rrrrwwwwxxxx,,,,gggg====rrrrxxxx,,,,oooo====rrrrxxxx (000022222222) disables group and other write permissions. As a result, files normally created with a file mode shown by the llllssss ----llll command as ----rrrrwwwwxxxxrrrrwwwwxxxxrrrrwwwwxxxx (777777777777) become mode ---- rrrrwwwwxxxxrrrr----xxxxrrrr----xxxx (777755555555); while files created with file mode ----rrrrwwww----rrrrwwww----rrrrwwww---- (666666666666) become mode ----rrrrwwww----rrrr--------rrrr-------- (666644444444). Note that the file creation mode mask does not affect the set-user-id, set-group-id, or "sticky" bits. The file creation mode mask is also used by the cccchhhhmmmmoooodddd command (see _c_h_m_o_d(1)). Since uuuummmmaaaasssskkkk affects the current shell execution environment, it is generally provided as a shell regular built-in (see DEPENDENCIES. If uuuummmmaaaasssskkkk is called in a subshell or separate utility execution environment, such as one of the following: ((((uuuummmmaaaasssskkkk 000000002222)))) nnnnoooohhhhuuuupppp uuuummmmaaaasssskkkk ... ffffiiiinnnndddd .... ----eeeexxxxeeeecccc uuuummmmaaaasssskkkk ... Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 uuuummmmaaaasssskkkk((((1111)))) uuuummmmaaaasssskkkk((((1111)))) it does not affect the file mode creation mask of the calling environment. The default mask is uuuu====rrrrwwwwxxxx,,,,gggg====rrrrwwwwxxxx,,,,oooo====rrrrwwwwxxxx (000000000000). RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE uuuummmmaaaasssskkkk exits with one of the following values: 0000 The file mode creation mask was successfully changed or no _m_a_s_k operand was supplied. >>>>0000 An error occurred. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS In these examples, each line show an alternate way of accomplishing the same task. Set the uuuummmmaaaasssskkkk value to produce read and write permissions for the file's owner and read permissions for all others (llllssss ----llll displays ----rrrrwwww---- rrrr--------rrrr-------- on newly created files): uuuummmmaaaasssskkkk uuuu====rrrrwwwwxxxx,,,,gggg====rrrrxxxx,,,,oooo====rrrrxxxx symbolic mode uuuummmmaaaasssskkkk aaaa====rrrrxxxx,,,,uuuu++++wwww symbolic mode uuuummmmaaaasssskkkk 000022222222 numeric mode Set the uuuummmmaaaasssskkkk value to produce read, and write permissions for the file's owner, read-only for others users in the same group, and no access to others (----rrrrwwww----rrrr--------------------): uuuummmmaaaasssskkkk aaaa----rrrrwwwwxxxx,,,,uuuu++++rrrrwwww,,,,gggg++++rrrr symbolic mode uuuummmmaaaasssskkkk 111133337777 numeric mode Set the uuuummmmaaaasssskkkk value to deny read, write, and execute permissions to everyone (----------------------------------------): uuuummmmaaaasssskkkk aaaa==== symbolic mode uuuummmmaaaasssskkkk 777777777777 numeric mode Add the write permission to the current mask for everyone (there is no equivalent numeric mode): uuuummmmaaaasssskkkk aaaa++++wwww symbolic mode WWWWAAAARRRRNNNNIIIINNNNGGGGSSSS If you set a mask that prevents read or write access for the user (owner), many programs, such as editors, that create temporary files will fail because they cannot access the file data. DDDDEEEEPPPPEEEENNNNDDDDEEEENNNNCCCCIIIIEEEESSSS The uuuummmmaaaasssskkkk command is implemented both as a separate executable file (////uuuussssrrrr////bbbbiiiinnnn////uuuummmmaaaasssskkkk) and as built-in shell commands. Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 uuuummmmaaaasssskkkk((((1111)))) uuuummmmaaaasssskkkk((((1111)))) PPPPOOOOSSSSIIIIXXXX SSSShhhheeeellllllll aaaannnndddd SSSSeeeeppppaaaarrrraaaatttteeee FFFFiiiilllleeee All features are supported (see _s_h-_p_o_s_i_x(1). The numeric mask display uses a minimum of two digits. KKKKoooorrrrnnnn SSSShhhheeeellllllll The ----SSSS option is not supported in the Korn shell built-in command (see _k_s_h(1). The numeric mask display uses a minimum of two digits. CCCC SSSShhhheeeellllllll The ----SSSS option and symbolic mask values are not supported in the C shell built-in command (see _c_s_h(1). The numeric mask display uses a minimum of one digit. BBBBoooouuuurrrrnnnneeee SSSShhhheeeellllllll The ----SSSS option and symbolic mask values are not supported in the Bourne shell built-in command (see _s_h-_b_o_u_r_n_e(1). The numeric mask display always consists of four digits. SSSSEEEEEEEE AAAALLLLSSSSOOOO chmod(1), csh(1), ksh(1), sh-posix(1), sh(1), chmod(2), creat(2), umask(2). SSSSTTTTAAAANNNNDDDDAAAARRRRDDDDSSSS CCCCOOOONNNNFFFFOOOORRRRMMMMAAAANNNNCCCCEEEE uuuummmmaaaasssskkkk: SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2 Hewlett-Packard Company - 5 - HP-UX Release 10.20: July 1996 yyyyppppccccaaaatttt((((1111)))) yyyyppppccccaaaatttt((((1111)))) NNNNAAAAMMMMEEEE ypcat - print all values in Network Information Service map SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS yyyyppppccccaaaatttt [----kkkk] [----tttt] [----dddd _d_o_m_a_i_n] _m_n_a_m_e yyyyppppccccaaaatttt ----xxxx RRRReeeemmmmaaaarrrrkkkkssss The Network Information Service (NIS) was formerly known as Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN yyyyppppccccaaaatttt prints all values in a Network Information Service (NIS) map specified by _m_n_a_m_e, which can be either a _m_a_p_n_a_m_e or a map _n_i_c_k_n_a_m_e. A map _n_i_c_k_n_a_m_e is a synonym by which a NIS map can be referenced. Values are listed, one per line. OOOOppppttttiiiioooonnnnssss yyyyppppccccaaaatttt recognizes the following options: ----kkkk Print the associated key preceding each value. This option is useful for examining maps in which the values are null or the keys are not part of the value, such as the _y_p_s_e_r_v_e_r_s map. The maps derived from files that have an ASCII version in ////eeeettttcccc (such as ppppaaaasssssssswwwwdddd and hhhhoooossssttttssss) are not in this category. ----tttt Inhibit the translation of a map's _n_i_c_k_n_a_m_e to its corresponding _m_a_p_n_a_m_e. For example, yyyyppppccccaaaatttt ----tttt ppppaaaasssssssswwwwdddd fails because there is no map named ppppaaaasssssssswwwwdddd, whereas yyyyppppccccaaaatttt ppppaaaasssssssswwwwdddd translates to yyyyppppccccaaaatttt ppppaaaasssssssswwwwdddd....bbbbyyyynnnnaaaammmmeeee. ----dddd Specify a _d_o_m_a_i_n other than the one returned by ddddoooommmmaaaaiiiinnnnnnnnaaaammmmeeee (see _d_o_m_a_i_n_n_a_m_e(1)). ----xxxx Display the table that lists the _n_i_c_k_n_a_m_e for each NIS map. AAAAUUUUTTTTHHHHOOOORRRR yyyyppppccccaaaatttt was developed by Sun Microsystems, Inc. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS Display the network-wide password database whose _m_a_p_n_a_m_e is ppppaaaasssssssswwwwdddd....bbbbyyyynnnnaaaammmmeeee and _n_i_c_k_n_a_m_e is ppppaaaasssssssswwwwdddd :::: yyyyppppccccaaaatttt ppppaaaasssssssswwwwdddd SSSSEEEEEEEE AAAALLLLSSSSOOOO domainname(1), ypmatch(1), ypserv(1M), ypfiles(4). Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 yyyyppppmmmmaaaattttcccchhhh((((1111)))) yyyyppppmmmmaaaattttcccchhhh((((1111)))) NNNNAAAAMMMMEEEE ypmatch - print values of selected keys in Network Information Service map SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS yyyyppppmmmmaaaattttcccchhhh [----kkkk] [----tttt] [----dddd _d_o_m_a_i_n] kkkkeeeeyyyy [kkkkeeeeyyyy...] mmmmnnnnaaaammmmeeee yyyyppppmmmmaaaattttcccchhhh ----xxxx RRRReeeemmmmaaaarrrrkkkkssss The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN yyyyppppmmmmaaaattttcccchhhh prints the values associated with one or more keys in a Network Information Service (NIS) map specified by _m_n_a_m_e. The _m_n_a_m_e can be either a _m_a_p_n_a_m_e or a map _n_i_c_k_n_a_m_e. A map _n_i_c_k_n_a_m_e is a synonym by which a NIS map can be referenced. If multiple keys are specified, the same map is searched for an occurrence of each key. A match is made only when the case and length of a key is the same as that stored in the database. No pattern matching is available. If a key is not matched, a diagnostic message is produced. OOOOppppttttiiiioooonnnnssss yyyyppppmmmmaaaattttcccchhhh recognizes the following command-line options: ----kkkk Before printing the value associated with a key, print the key followed by a colon (::::). This option is useful if the keys are not part of the values (as in a yyyyppppsssseeeerrrrvvvveeeerrrrssss map), or so many keys were specified that the output could be confusing. ----tttt Inhibit the translation of a map's _n_i_c_k_n_a_m_e to its corresponding _m_a_p_n_a_m_e. For example, yyyyppppmmmmaaaattttcccchhhh ----tttt zzzziiiippppppppyyyy ppppaaaasssssssswwwwdddd fails because there is no map named ppppaaaasssssssswwwwdddd, while yyyyppppmmmmaaaattttcccchhhh zzzziiiippppppppyyyy ppppaaaasssssssswwwwdddd is translated to yyyyppppmmmmaaaattttcccchhhh zzzziiiippppppppyyyy ppppaaaasssssssswwwwdddd....bbbbyyyynnnnaaaammmmeeee. ----dddd Specify a _d_o_m_a_i_n other than the one returned by ddddoooommmmaaaaiiiinnnnnnnnaaaammmmeeee (see _d_o_m_a_i_n_n_a_m_e(1)). ----xxxx Display the table that lists the _n_i_c_k_n_a_m_e for each NIS map. AAAAUUUUTTTTHHHHOOOORRRR yyyyppppmmmmaaaattttcccchhhh was developed by Sun Microsystems, Inc. Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 yyyyppppmmmmaaaattttcccchhhh((((1111)))) yyyyppppmmmmaaaattttcccchhhh((((1111)))) SSSSEEEEEEEE AAAALLLLSSSSOOOO domainname(1), ypcat(1), ypserv(1M), ypfiles(4). Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 yyyyppppppppaaaasssssssswwwwdddd((((1111)))) yyyyppppppppaaaasssssssswwwwdddd((((1111)))) NNNNAAAAMMMMEEEE yppasswd - change login password in Network Information System (NIS) SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS yyyyppppppppaaaasssssssswwwwdddd [_n_a_m_e] RRRReeeemmmmaaaarrrrkkkkssss The Network Information Service (NIS) was formerly known as Yellow Pages (YP). The functionality remains the same; only the name has changed. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN yyyyppppppppaaaasssssssswwwwdddd changes or installs a password associated with the login _n_a_m_e in the Network Information System (NIS). The NIS password can be different from the one on your own machine. If _n_a_m_e is omitted, it defaults to the name returned by ggggeeeettttllllooooggggiiiinnnn(((()))) (see _g_e_t_l_o_g_i_n(3C)). yyyyppppppppaaaasssssssswwwwdddd prompts for the old NIS password (even if it does not exist), then twice for the new one. The old password must be entered correctly for the change to take effect. Checks occur to ensure that the new password meets the following construction requirements. o+ Only the first eight characters are significant. o+ A password can be as few as four characters long if it contains o+ at least one special character or o+ a mixture of numeric, uppercase and lowercase letters. o+ A password can be as few as five characters long if it contains a mixture of o+ uppercase and lowercase letters or o+ numeric and either uppercase or lowercase letters. o+ A password must contain at least six characters if it contains only monocase letters. All these rules except the first are relaxed if you try three times to enter an unacceptable new password. You cannot, however, enter a null password. Only the owner of the _n_a_m_e or the superuser can change a password. The Network Information System password daemon, _y_p_p_a_s_s_w_d_d(1M), must be running on the master NIS password server to change NIS passwords. Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 yyyyppppppppaaaasssssssswwwwdddd((((1111)))) yyyyppppppppaaaasssssssswwwwdddd((((1111)))) WWWWAAAARRRRNNNNIIIINNNNGGGGSSSS The password update protocol passes the old and new passwords to the master NIS server at once. Thus, if the old NIS password is incorrect, no notification is given until the new NIS password is successfully entered. The yyyyppppppppaaaasssssssswwwwdddd password construction rules are different from those of the HP-UX ppppaaaasssssssswwwwdddd command (see _p_a_s_s_w_d(1)). User applications that call this routine must be linked with ////uuuussssrrrr////iiiinnnncccclllluuuuddddeeee////lllliiiibbbbrrrrppppccccssssvvvvcccc....aaaa. For example, cccccccc mmmmyyyy____ssssoooouuuurrrrcccceeee....cccc ----llllrrrrppppccccssssvvvvcccc AAAAUUUUTTTTHHHHOOOORRRR yyyyppppppppaaaasssssssswwwwdddd was developed by Sun Microsystems, Inc. SSSSEEEEEEEE AAAALLLLSSSSOOOO id(1), passwd(1), su(1), yppasswdd(1M), getlogin(3C), yppasswd(3N), ypfiles(4). Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 aaaauuuuttttoooommmmoooouuuunnnntttt((((1111MMMM)))) aaaauuuuttttoooommmmoooouuuunnnntttt((((1111MMMM)))) NNNNAAAAMMMMEEEE automount - automatically mount NFS file systems SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS aaaauuuuttttoooommmmoooouuuunnnntttt [----mmmmnnnnTTTTvvvv] [----DDDD _n_a_m_e ==== _v_a_l_u_e] [----ffff _m_a_s_t_e_r-_f_i_l_e] [----MMMM _m_o_u_n_t- _d_i_r_e_c_t_o_r_y] [----ttttllll _d_u_r_a_t_i_o_n] [----ttttmmmm _i_n_t_e_r_v_a_l] [----ttttwwww _i_n_t_e_r_v_a_l] [_d_i_r_e_c_t_o_r_y _m_a_p [-_m_o_u_n_t-_o_p_t_i_o_n_s] ] ... DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN aaaauuuuttttoooommmmoooouuuunnnntttt is a daemon that automatically and transparently mounts NFS file systems as needed. It monitors attempts to access directories that are associated with an aaaauuuuttttoooommmmoooouuuunnnntttt map, along with any directories or files that reside under them. When a file is to be accessed, the daemon mounts the appropriate NFS file system. Maps can be assigned to a directory by using an entry in a direct aaaauuuuttttoooommmmoooouuuunnnntttt map, or by specifying an indirect map on the command line. aaaauuuuttttoooommmmoooouuuunnnntttt interacts with the kernel in a manner closely resembling an NFS server: o+ aaaauuuuttttoooommmmoooouuuunnnntttt uses the map to locate an appropriate NFS file server, exported file system, and mount options. o+ It then mounts the file system in a temporary location, and replaces the file system entry for the directory or subdirectory with a symbolic link to the temporary location. o+ If the file system is not accessed within an appropriate interval (five minutes by default), the daemon unmounts the file system and removes the symbolic link. o+ If the specified directory has not already been created, the daemon creates it, and then removes it upon exiting. Since name-to-location binding is dynamic, updates to an aaaauuuuttttoooommmmoooouuuunnnntttt map are transparent to the user. This obviates the need to mount shared file systems prior to running applications that contain internally hard-coded references to files. If the dummy directory (////----) is specified, aaaauuuuttttoooommmmoooouuuunnnntttt treats the _m_a_p argument that follows as the name of a direct map. In a direct map, each entry associates the full path name of a mount point with a remote file system to mount. If the _d_i_r_e_c_t_o_r_y argument is a path name, the _m_a_p argument points to an indirect map. An indirect map, contains a list of the subdirectories contained within the indicated _d_i_r_e_c_t_o_r_y. With an indirect map, it is these subdirectories that are mounted automatically. Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 aaaauuuuttttoooommmmoooouuuunnnntttt((((1111MMMM)))) aaaauuuuttttoooommmmoooouuuunnnntttt((((1111MMMM)))) A map can be a file or a NIS map; if a file, the _m_a_p argument must be a full path name. The ----_m_o_u_n_t-_o_p_t_i_o_n_s argument, when supplied, is a comma-separated list of options to the mmmmoooouuuunnnntttt command (see _m_o_u_n_t(1M)) preceded by a ----. However, any conflicting mount options specified in the indicated map take precedence. OOOOppppttttiiiioooonnnnssss aaaauuuuttttoooommmmoooouuuunnnntttt recognizes the following options: ----mmmm Ignore aaaauuuuttttoooo....mmmmaaaasssstttteeeerrrr NIS database. ----nnnn Disable dynamic mounts. With this option, references through the aaaauuuuttttoooommmmoooouuuunnnntttt daemon succeed only when the target filesystem has been previously mounted. This can be used to prevent NFS servers from cross-mounting each other. ----TTTT Trace. Expand each NFS call and log it in ////vvvvaaaarrrr////aaaaddddmmmm////aaaauuuuttttoooommmmoooouuuunnnntttt....lllloooogggg file. ----vvvv Verbose. Log status messages to the system log file (see _s_y_s_l_o_g_d(1M)). ----DDDD _e_n_v_a_r ==== _v_a_l_u_e Assign _v_a_l_u_e to the indicated aaaauuuuttttoooommmmoooouuuunnnntttt (environment) variable _e_n_v_a_r. ----ffff _m_a_s_t_e_r-_f_i_l_e Read the local mmmmaaaasssstttteeeerrrr____ffffiiiilllleeee before reading the aaaauuuuttttoooo....mmmmaaaasssstttteeeerrrr NIS map. ----MMMM _m_o_u_n_t-_d_i_r_e_c_t_o_r_y Mount temporary file systems in the named directory instead of in ////ttttmmmmpppp____mmmmnnnntttt. ----ttttllll _d_u_r_a_t_i_o_n Specify a _d_u_r_a_t_i_o_n (in seconds) that a file system is to remain mounted when not in use. The default is 5 minutes. ----ttttmmmm _i_n_t_e_r_v_a_l Specify an _i_n_t_e_r_v_a_l (in seconds) between attempts to mount a filesystem. The default is 30 seconds. ----ttttwwww _i_n_t_e_r_v_a_l Specify an _i_n_t_e_r_v_a_l (in seconds) between attempts to unmount filesystems that have exceeded their cached times. The default is 1 minute. EEEEnnnnvvvviiiirrrroooonnnnmmmmeeeennnntttt VVVVaaaarrrriiiiaaaabbbblllleeeessss Environment variables can be used within an aaaauuuuttttoooommmmoooouuuunnnntttt map. For example, if $$$$HHHHOOOOMMMMEEEE appears within a map, aaaauuuuttttoooommmmoooouuuunnnntttt expands it to the current value of the HHHHOOOOMMMMEEEE environment variable. Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 aaaauuuuttttoooommmmoooouuuunnnntttt((((1111MMMM)))) aaaauuuuttttoooommmmoooouuuunnnntttt((((1111MMMM)))) To protect a reference from affixed characters, surround the variable name with curly braces. Environment variables cannot appear as the key entry in maps. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS MMMMaaaapppp EEEEnnnnttttrrrryyyy FFFFoooorrrrmmmmaaaatttt A simple map entry (mapping) takes the form: _d_i_r_e_c_t_o_r_y [----_m_o_u_n_t-_o_p_t_i_o_n_s] _l_o_c_a_t_i_o_n ... where _d_i_r_e_c_t_o_r_y is the full path name of the directory to mount, when used in a direct map, or the basename of a subdirectory in an indirect map. _m_o_u_n_t-_o_p_t_i_o_n_s is a comma-separated list of mmmmoooouuuunnnntttt options, and _l_o_c_a_t_i_o_n specifies a remote filesystem from which the directory may be mounted. In the simple case, _l_o_c_a_t_i_o_n takes the form: _h_o_s_t::::_p_a_t_h_n_a_m_e Multiple _l_o_c_a_t_i_o_n fields can be specified, in which case aaaauuuuttttoooommmmoooouuuunnnntttt sends multiple mmmmoooouuuunnnntttt requests; aaaauuuuttttoooommmmoooouuuunnnntttt mounts the file system from the first host that replies to the mmmmoooouuuunnnntttt request. This request is first made to the local net or subnet. If there is no response, any connected server is allowed to respond. If _l_o_c_a_t_i_o_n is specified in the form: _h_o_s_t::::_p_a_t_h::::_s_u_b_d_i_r _h_o_s_t is the name of the host from which to mount the file system, _p_a_t_h is the path name of the directory to mount, and _s_u_b_d_i_r, when supplied, is the name of a subdirectory to which the symbolic link is made. This can be used to prevent duplicate mounts when multiple directories in the same remote file system might be accessed. Assume a map for ////hhhhoooommmmeeee resembling: mmmmiiiikkkkeeee hhhhppppsssseeeerrrrvvvveeeerrrr1111::::////hhhhoooommmmeeee////hhhhppppsssseeeerrrrvvvveeeerrrr1111::::mmmmiiiikkkkeeee ddddiiiiaaaannnnnnnnaaaa hhhhppppsssseeeerrrrvvvveeeerrrr1111::::////hhhhoooommmmeeee////hhhhppppsssseeeerrrrvvvveeeerrrr1111::::ddddiiiiaaaannnnnnnnaaaa Attempting to access a file in ////hhhhoooommmmeeee////mmmmiiiikkkkeeee causes aaaauuuuttttoooommmmoooouuuunnnntttt to mount hhhhppppsssseeeerrrrvvvveeeerrrr1111::::////hhhhoooommmmeeee////hhhhppppsssseeeerrrrvvvveeeerrrr1111 and creates a symbolic link called ////hhhhoooommmmeeee////mmmmiiiikkkkeeee to the mmmmiiiikkkkeeee subdirectory in the temporarily-mounted filesystem. A subsequent file access request in ////hhhhoooommmmeeee////ddddiiiiaaaannnnnnnnaaaa results in aaaauuuuttttoooommmmoooouuuunnnntttt simply creating a symbolic link that points to the ddddiiiiaaaannnnnnnnaaaa subdirectory because ////hhhhoooommmmeeee////hhhhppppsssseeeerrrrvvvveeeerrrr1111 is already mounted. Given the map: mmmmiiiikkkkeeee hhhhppppsssseeeerrrrvvvveeeerrrr1111::::////hhhhoooommmmeeee////hhhhppppsssseeeerrrrvvvveeeerrrr1111////mmmmiiiikkkkeeee ddddiiiiaaaannnnnnnnaaaa hhhhppppsssseeeerrrrvvvveeeerrrr1111::::////hhhhoooommmmeeee////hhhhppppsssseeeerrrrvvvveeeerrrr1111////ddddiiiiaaaannnnnnnnaaaa aaaauuuuttttoooommmmoooouuuunnnntttt would have to mount the filesystem twice. Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 aaaauuuuttttoooommmmoooouuuunnnntttt((((1111MMMM)))) aaaauuuuttttoooommmmoooouuuunnnntttt((((1111MMMM)))) A mapping can be continued across input lines by escaping the newline character with a backslash (\\\\). Comments begin with a #### and end at the subsequent newline character. DDDDiiiirrrreeeeccccttttoooorrrryyyy PPPPaaaatttttttteeeerrrrnnnn MMMMaaaattttcccchhhhiiiinnnngggg The &&&& character is expanded to the value of the _d_i_r_e_c_t_o_r_y field for the entry in which it occurs. Given an entry of the form: mmmmiiiikkkkeeee hhhhppppsssseeeerrrrvvvveeeerrrr1111::::////hhhhoooommmmeeee////hhhhppppsssseeeerrrrvvvveeeerrrr1111::::&&&& the &&&& expands to mmmmiiiikkkkeeee. The **** character, when supplied as the _d_i_r_e_c_t_o_r_y field, is recognized as the catch-all entry. Such an entry resolves to any entry not previously matched. For example, if the following entry appeared in the indirect map for ////hhhhoooommmmeeee: **** &&&&::::////hhhhoooommmmeeee////&&&& this would allow automatic mounts in ////hhhhoooommmmeeee of any remote file system whose location could be specified as: _h_o_s_t_n_a_m_e :/_h_o_m_e _h_o_s_t_n_a_m_e HHHHiiiieeeerrrraaaarrrrcccchhhhiiiiccccaaaallll MMMMaaaappppppppiiiinnnnggggssss A hierarchical mapping takes the form: _d_i_r_e_c_t_o_r_y [////[_s_u_b_d_i_r_e_c_t_o_r_y] [----_m_o_u_n_t-_o_p_t_i_o_n_s] _l_o_c_a_t_i_o_n ...] ... The initial //// within the ////[_s_u_b_d_i_r_e_c_t_o_r_y] is required; the optional _s_u_b_d_i_r_e_c_t_o_r_y is taken as a file name relative to the _d_i_r_e_c_t_o_r_y. If _s_u_b_d_i_r_e_c_t_o_r_y is omitted in the first occurrence, the //// refers to the directory itself. Given the direct map entry: ////uuuussssrrrr////llllooooccccaaaallll \\\\ //// ----rrrroooo,,,,iiiinnnnttttrrrr sssshhhhaaaassssttttaaaa::::////uuuussssrrrr////llllooooccccaaaallll rrrraaaannnniiiieeeerrrr::::////uuuussssrrrr////llllooooccccaaaallll \\\\ ////bbbbiiiinnnn ----rrrroooo,,,,iiiinnnnttttrrrr rrrraaaannnniiiieeeerrrr::::////uuuussssrrrr////llllooooccccaaaallll////bbbbiiiinnnn sssshhhhaaaassssttttaaaa::::////uuuussssrrrr////llllooooccccaaaallll////bbbbiiiinnnn \\\\ ////mmmmaaaannnn ----rrrroooo,,,,iiiinnnnttttrrrr sssshhhhaaaassssttttaaaa::::////uuuussssrrrr////llllooooccccaaaallll////mmmmaaaannnn rrrraaaannnniiiieeeerrrr::::////uuuussssrrrr////llllooooccccaaaallll////mmmmaaaannnn aaaauuuuttttoooommmmoooouuuunnnntttt automatically mounts ////uuuussssrrrr////llllooooccccaaaallll, ////uuuussssrrrr////llllooooccccaaaallll////bbbbiiiinnnn, and ////uuuussssrrrr////llllooooccccaaaallll////mmmmaaaannnn, as needed, from either sssshhhhaaaassssttttaaaa or rrrraaaannnniiiieeeerrrr, whichever host responded first. DDDDiiiirrrreeeecccctttt MMMMaaaappppssss A direct map contains mappings for any number of directories. Each directory listed in the map is automatically mounted as needed. The direct map as a whole is not associated with any single directory. Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 aaaauuuuttttoooommmmoooouuuunnnntttt((((1111MMMM)))) aaaauuuuttttoooommmmoooouuuunnnntttt((((1111MMMM)))) IIIInnnnddddiiiirrrreeeecccctttt MMMMaaaappppssss An indirect map allows specifying mappings for the subdirectories to be mounted under the _d_i_r_e_c_t_o_r_y indicated on the command line. It also obscures local subdirectories for which no mapping is specified. In an indirect map, each _d_i_r_e_c_t_o_r_y field consists of the basename of a subdirectory to be mounted as needed. IIIInnnncccclllluuuuddddeeeedddd MMMMaaaappppssss The contents of another map can be included within a map with an entry of the form: ++++_m_a_p_n_a_m_e _m_a_p_n_a_m_e can either be a file name, or the name of an NIS map, or one of the special maps described below. SSSSppppeeeecccciiiiaaaallll MMMMaaaappppssss Three special maps, ----hhhhoooossssttttssss, ----ppppaaaasssssssswwwwdddd, and ----nnnnuuuullllllll, are currently available: The ----hhhhoooossssttttssss map uses the ggggeeeetttthhhhoooossssttttbbbbyyyynnnnaaaammmmeeee(((()))) map to locate a remote host when the hostname is specified (see _g_e_t_h_o_s_t_b_y_n_a_m_e(3C). This map specifies mounts of all exported file systems from any host. For example, if the following aaaauuuuttttoooommmmoooouuuunnnntttt command is already in effect: aaaauuuuttttoooommmmoooouuuunnnntttt ////nnnneeeetttt ----hhhhoooossssttttssss a reference to ////nnnneeeetttt////hhhheeeerrrrmmmmeeeessss////uuuussssrrrr initiates an automatic mount of all file systems from hhhheeeerrrrmmmmeeeessss that aaaauuuuttttoooommmmoooouuuunnnntttt can mount, and any subsequent references to a directory under ////nnnneeeetttt////hhhheeeerrrrmmmmeeeessss refer to the corresponding directory on hhhheeeerrrrmmmmeeeessss. The ----ppppaaaasssssssswwwwdddd map uses the _p_a_s_s_w_d(4) database to attempt to locate a user's home directory. For example, if the following aaaauuuuttttoooommmmoooouuuunnnntttt command is already in effect: aaaauuuuttttoooommmmoooouuuunnnntttt ////hhhhoooommmmeeeessss ----ppppaaaasssssssswwwwdddd if the home directory for a user has the form ////_d_i_r////_s_e_r_v_e_r////_u_s_e_r_n_a_m_e, and _s_e_r_v_e_r matches the host system on which that directory resides, aaaauuuuttttoooommmmoooouuuunnnntttt mounts the user's home directory as: ////_h_o_m_e_s////_u_s_e_r_n_a_m_e. For this map, the tilde character (~~~~) is recognized as a synonym for _u_s_e_r_n_a_m_e. The ----nnnnuuuullllllll map, when indicated on the command line, cancels a previous map for the directory indicated. It can be used to cancel a map given in aaaauuuuttttoooo....mmmmaaaasssstttteeeerrrr. CCCCoooonnnnffffiiiigggguuuurrrraaaattttiiiioooonnnn aaaannnndddd tttthhhheeee aaaauuuuttttoooo....mmmmaaaasssstttteeeerrrr MMMMaaaapppp aaaauuuuttttoooommmmoooouuuunnnntttt normally consults the aaaauuuuttttoooo....mmmmaaaasssstttteeeerrrr NIS configuration map for a list of initial aaaauuuuttttoooommmmoooouuuunnnntttt maps, and sets up automatic mounts for them in addition to those given on the command line. If there are duplications, the command-line arguments take precedence. This configuration database contains arguments to the aaaauuuuttttoooommmmoooouuuunnnntttt command Hewlett-Packard Company - 5 - HP-UX Release 10.20: July 1996 aaaauuuuttttoooommmmoooouuuunnnntttt((((1111MMMM)))) aaaauuuuttttoooommmmoooouuuunnnntttt((((1111MMMM)))) rather than mappings. Unless ----ffff is in effect, aaaauuuuttttoooommmmoooouuuunnnntttt does _n_o_t look for an aaaauuuuttttoooo....mmmmaaaasssstttteeeerrrr file on the local host. Maps given on the command line, or those given in a local aaaauuuuttttoooo....mmmmaaaasssstttteeeerrrr file specified with ----ffff override those in the NIS aaaauuuuttttoooo....mmmmaaaasssstttteeeerrrr map. For example, given the command: aaaauuuuttttoooommmmoooouuuunnnntttt ////hhhhoooommmmeeeessss ////eeeettttcccc////aaaauuuuttttoooo....hhhhoooommmmeeeessss ////---- ////eeeettttcccc////aaaauuuuttttoooo....ddddiiiirrrreeeecccctttt and the NIS map file aaaauuuuttttoooo....mmmmaaaasssstttteeeerrrr containing: ////hhhhoooommmmeeeessss ----ppppaaaasssssssswwwwdddd aaaauuuuttttoooommmmoooouuuunnnntttt mounts home directories using the ////eeeettttcccc////aaaauuuuttttoooo....hhhhoooommmmeeeessss map instead of the special ----ppppaaaasssssssswwwwdddd map in addition to the various directories specified in the ////eeeettttcccc////aaaauuuuttttoooo....ddddiiiirrrreeeecccctttt map. WWWWAAAARRRRNNNNIIIINNNNGGGGSSSS Do not send the SSSSIIIIGGGGKKKKIIIILLLLLLLL signal (kkkkiiiillllllll ----9999, or kkkkiiiillllllll ----KKKKIIIILLLLLLLL) to the automount daemon. Doing so causes any processes accessing mount directories served by aaaauuuuttttoooommmmoooouuuunnnntttt to hang. A system reboot may be required to recover from this state. Do not start an automount daemon while another is still running. If restarting aaaauuuuttttoooommmmoooouuuunnnntttt, make sure the first daemon and all of its children are not running. When aaaauuuuttttoooommmmoooouuuunnnntttt receives signal SSSSIIIIGGGGHHHHUUUUPPPP, it rereads the ////eeeettttcccc////mmmmnnnnttttttttaaaabbbb file to update its internal record of currently mounted file systems. If a file system mounted by aaaauuuuttttoooommmmoooouuuunnnntttt is unmounted by a uuuummmmoooouuuunnnntttt command, aaaauuuuttttoooommmmoooouuuunnnntttt should be forced to reread the file by sending the SSSSIIIIGGGGHHHHUUUUPPPP signal (see _k_i_l_l(1)). Shell file name expansion does not apply to objects not currently mounted. Since aaaauuuuttttoooommmmoooouuuunnnntttt is single-threaded, any request that is delayed by a slow or nonresponding NFS server delays all subsequent automatic mount requests until it completes. Programs that read ////eeeettttcccc////mmmmnnnnttttttttaaaabbbb and then touch files that reside under automatic mount points introduce further entries to the file. Automatically-mounted file systems are mounted with type iiiiggggnnnnoooorrrreeee; they do not appear in the output of either _m_o_u_n_t(1M), or _b_d_f(1M). FFFFIIIILLLLEEEESSSS ////ttttmmmmpppp____mmmmnnnntttt directory under which filesystems are dynamically mounted ////eeeettttcccc////mmmmnnnnttttttttaaaabbbb mount table Hewlett-Packard Company - 6 - HP-UX Release 10.20: July 1996 aaaauuuuttttoooommmmoooouuuunnnntttt((((1111MMMM)))) aaaauuuuttttoooommmmoooouuuunnnntttt((((1111MMMM)))) SSSSEEEEEEEE AAAALLLLSSSSOOOO mount (1M), bdf (1M), passwd (4) Hewlett-Packard Company - 7 - HP-UX Release 10.20: July 1996 ccccoooonnnnffffiiiigggg((((1111MMMM)))) ccccoooonnnnffffiiiigggg((((1111MMMM)))) NNNNAAAAMMMMEEEE config - configure and build an HP-UX system SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ////uuuussssrrrr////ssssbbbbiiiinnnn////ccccoooonnnnffffiiiigggg [----cccc _c__f_i_l_e] [----llll _m__f_i_l_e] [----mmmm _m_a_s_t_e_r__f_i_l_e] [----rrrr _p_a_t_h] [----ssss] [----tttt] _s_y_s_t_e_m__f_i_l_e DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN ccccoooonnnnffffiiiigggg is used to configure the following parts of the operating system: o+ Device drivers o+ Swap and dump devices o+ Tunable system parameters ccccoooonnnnffffiiiigggg reads a user-provided description of an HP-UX system (_s_y_s_t_e_m__f_i_l_e) and a master kernel configuration information table and generates two output files: o+ A C program source file that defines the configuration tables for various parts of the system. o+ A makefile (see _m_a_k_e(1)) to compile the C program produced and relink the newly configured system. Lastly ccccoooonnnnffffiiiigggg executes the _m_a_k_e command to compile ccccoooonnnnffff....cccc and link the kernel (vvvvmmmmuuuunnnniiiixxxx) with the appropriate kernel libraries. File vvvvmmmmuuuunnnniiiixxxx can then be booted. See the _H_P-_U_X _S_y_s_t_e_m _A_d_m_i_n_i_s_t_r_a_t_o_r _M_a_n_u_a_l_s for information on how to include or remove a subsystem or file system, and how to boot the system. Many header files are needed to compile ccccoooonnnnffff....cccc.... Also, archive library files containing the kernel objects are needed to link the kernel. These files are supplied with the system and are contained in the directories found under ////uuuussssrrrr////ccccoooonnnnffff. CCCCoooommmmmmmmaaaannnndddd LLLLiiiinnnneeee AAAArrrrgggguuuummmmeeeennnnttttssss The ccccoooonnnnffffiiiigggg command recognizes the following arguments: ----cccc _c__f_i_l_e Specify the name of the C program source file produced by ccccoooonnnnffffiiiigggg. The default file name is ccccoooonnnnffff....cccc. ----llll _m__f_i_l_e Specify the name of the makefile which is generated by ccccoooonnnnffffiiiigggg. This is the makefile which will be used by ccccoooonnnnffffiiiigggg to compile the C program source file and make the new kernel. The default file name is ccccoooonnnnffffiiiigggg....mmmmkkkk. ----mmmm _m_a_s_t_e_r Specify the name of the master kernel configuration information file or directory that Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 ccccoooonnnnffffiiiigggg((((1111MMMM)))) ccccoooonnnnffffiiiigggg((((1111MMMM)))) config should use in creating ccccoooonnnnffff....cccc and ccccoooonnnnffffiiiigggg....mmmmkkkk. If _m_a_s_t_e_r is a directory, ccccoooonnnnffffiiiigggg reads all files in that directory to create its data structures. If _m_a_s_t_e_r is a file, only that file is read for creating data structures for ccccoooonnnnffffiiiigggg. By default, ccccoooonnnnffffiiiigggg reads the files in the directory ////uuuussssrrrr////ccccoooonnnnffff////mmmmaaaasssstttteeeerrrr....dddd. ////uuuussssrrrr////ccccoooonnnnffff////mmmmaaaasssstttteeeerrrr....dddd is supplied as part of the HP-UX operating system and should not be modified by anyone who does not fully understand its structure and purpose. ----rrrr _p_a_t_h Search the directory _p_a_t_h for the libraries and header files needed for making the kernel. By default, ccccoooonnnnffffiiiigggg uses the directory /_u_s_r/_c_o_n_f . ----ssss Stop after creating ccccoooonnnnffff....cccc and ccccoooonnnnffffiiiigggg....mmmmkkkk. _m_a_k_e is not executed and a kernel ( vvvvmmmmuuuunnnniiiixxxx) is not created. ----tttt Give a short table of major device numbers for the character and block devices, the card drivers, the streams drivers and modules which require link routines, the streams devices and the streams modules named in _s_y_s_t_e_m__f_i_l_e. These tables may be useful when creating special device files. _s_y_s_t_e_m__f_i_l_e The file containing configuration information for the user's system. The default _s_y_s_t_e_m__f_i_l_e is ////ssssttttaaaannnndddd////ssssyyyysssstttteeeemmmm and when this file is used as input to config, the resulting output is placed in the directory ////ssssttttaaaannnndddd////bbbbuuuuiiiilllldddd. If a file other than ////ssssttttaaaannnndddd////ssssyyyysssstttteeeemmmm is used for the _s_y_s_t_e_m__f_i_l_e, ccccoooonnnnffffiiiigggg places its output files in the current directory. The _s_y_s_t_e_m__f_i_l_e is divided into two parts: the first part (mandatory) contains driver specifications, and the second part (optional) contains system-dependent information. CCCCoooonnnnssssttttrrrruuuuccccttttiiiinnnngggg ssssyyyysssstttteeeemmmm____ffffiiiilllleeee:::: FFFFiiiirrrrsssstttt PPPPaaaarrrrtttt The first part of _s_y_s_t_e_m__f_i_l_e is used to configure: o+ Device drivers o+ Pseudo-drivers o+ Subsystems Each line has the following format: _d_e_v_n_a_m_e where _d_e_v_n_a_m_e is the driver or subsystem name as it appears in the alias tables, driver install tables or the device tables in the files Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 ccccoooonnnnffffiiiigggg((((1111MMMM)))) ccccoooonnnnffffiiiigggg((((1111MMMM)))) in the directory ////uuuussssrrrr////ccccoooonnnnffff////mmmmaaaasssstttteeeerrrr....dddd. For example, ssssccccssssiiii selects the driver for SCSI disk drives, ssssccccssssiiiittttaaaappppeeee selects the driver for SCSI tape drives, and nnnnffffssss selects the NFS subsystem. Together, the files in ////uuuussssrrrr////ccccoooonnnnffff////mmmmaaaasssstttteeeerrrr....dddd contain a complete list of configurable devices, cards, subsystems, and pseudo-drivers. CCCCoooonnnnssssttttrrrruuuuccccttttiiiinnnngggg ssssyyyysssstttteeeemmmm____ffffiiiilllleeee:::: OOOOppppttttiiiioooonnnnaaaallll SSSSeeeeccccoooonnnndddd PPPPaaaarrrrtttt The second part of _s_y_s_t_e_m__f_i_l_e is used to: o+ Define the swap device. Define the dump device(s). o+ Provide a mapping of a driver to a hardware path. o+ Define status and values of selected system parameters. Lines are constructed as indicated below for each category. 1111.... SSSSwwwwaaaapppp ddddeeeevvvviiiicccceeee ssssppppeeeecccciiiiffffiiiiccccaaaattttiiiioooonnnn No more than one swap specification is allowed. If a swap specification is not given, the system will be configured to swap on the root device at the end of the filesystem. sssswwwwaaaapppp < _h_w__p_a_t_h > < _o_f_f_s_e_t > [< _b_l_o_c_k_s >] Configure the swap device location and its size as specified. Arguments are interpreted as follows: _h_w__p_a_t_h The hardware path representing the device to configure as the swap device or the string ddddeeeeffffaaaauuuulllltttt may be used to indicate using the root device. _o_f_f_s_e_t The swap area location. Boundaries are located at 1K-byte intervals. A negative value specifies that a file system is expected on the device. At boot-up, the super block is read to determine the exact size of the file system, and this value is put in _o_f_f_s_e_t. If the swap device is auto-configured, this is the mechanism used. If the super block is invalid, the entry will be skipped, so that a corrupted super block will not later cause specifies the minimum area that must be reserved. Zero means to reserve no area at the head of the device. _A _z_e_r_o _v_a_l_u_e _i_m_p_l_i_e_s _t_h_a_t _t_h_e_r_e _i_s _n_o _f_i_l_e _s_y_s_t_e_m _o_n _t_h_e _d_e_v_i_c_e. _b_l_o_c_k_s The number (in decimal) of 1K-byte disk blocks in the swap area. For this swap device specification, only the _b_l_o_c_k_s parameter is optional. Zero is the default for auto-configuration. Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 ccccoooonnnnffffiiiigggg((((1111MMMM)))) ccccoooonnnnffffiiiigggg((((1111MMMM)))) If _b_l_o_c_k_s is zero, the entire remainder of the device is automatically configured in as swap area. If _b_l_o_c_k_s is non-zero, its absolute value is treated as an upper bound for the size of the swap area. Then, if the swap area size has actually been cut back, the sign of _b_l_o_c_k_s determines whether _b_l_o_c_k_s remains as is, resulting in the swap area being adjacent to the reserved area, or whether _b_l_o_c_k_s is bumped by the size of the unused area, resulting in the swap area being adjacent to the tail of the device. sssswwwwaaaapppp < _h_w__p_a_t_h > < _o_p_t_i_o_n_s > Configure the swap device at the location specified using the options specified. The _h_w__p_a_t_h argument is interpreted as it is in the previous example. The _o_p_t_i_o_n_s argument is interpreted as follows: _o_p_t_i_o_n_s This field is used to specify a section. It is only offered for backwards compatibility purposes. For example, ssss3333 would put the swap area on section 3. sssswwwwaaaapppp lvol Configure swap on a logical volume. sssswwwwaaaapppp none Configure the kernel with no swap device. 2222.... DDDDuuuummmmpppp ddddeeeevvvviiiicccceeee((((ssss)))) ssssppppeeeecccciiiiffffiiiiccccaaaattttiiiioooonnnn One or more dump specification is allowed. If a dump specification is not given, then the primary swap area will be used. dddduuuummmmpppp < _h_w__p_a_t_h > [< _o_p_t_i_o_n_s > ] Configure the dump device location and its size as specified. Arguments are interpreted as follows: _h_w__p_a_t_h The hardware path representing the device to configure as a dump device or the string ddddeeeeffffaaaauuuulllltttt may be used to indicate using the primary swap area. _o_p_t_i_o_n_s This field is used to specify a section. It is only offered for backwards compatibility purposes. For example, ssss3333 Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 ccccoooonnnnffffiiiigggg((((1111MMMM)))) ccccoooonnnnffffiiiigggg((((1111MMMM)))) would put the dump area at section 3. dddduuuummmmpppp lvol Configure dump on a logical volume. dddduuuummmmpppp none Configure the kernel with no dump device. 3333.... DDDDeeeevvvviiiicccceeee ddddrrrriiiivvvveeeerrrr ttttoooo hhhhaaaarrrrddddwwwwaaaarrrreeee ppppaaaatttthhhh One or more driver to hardware path specifications is allowed. If a driver statement is provided the specified software module will be forced into the kernel I/O system at the given hardware path. This can be used to make the system recognize a device that could not be recognized automatically. ddddrrrriiiivvvveeeerrrr < _h_w__p_a_t_h > < _d_r_i_v_e_r__n_a_m_e > Bind the driver into the kernel I/O system at the given hardware path. Arguments are interpreted as follows: _h_w__p_a_t_h The hardware path representing the device to bind the software with. _d_r_i_v_e_r__n_a_m_e The name of the software module to bind into the kernel at the specified hardware path. 4444.... SSSSyyyysssstttteeeemmmm ppppaaaarrrraaaammmmeeeetttteeeerrrrssss These parameters should not be modified without a full understanding of the ramifications of doing so (see the _H_P-_U_X _S_y_s_t_e_m _A_d_m_i_n_i_s_t_r_a_t_o_r _T_a_s_k_s _M_a_n_u_a_l for information about each parameter). Each line contains two fields. The first field can contain up to 20 characters, maximum; the second field up to 60 characters, maximum. Each line is independent, optional, and written in the following format: ppppaaaarrrraaaammmmeeeetttteeeerrrr____nnnnaaaammmmeeee _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a System V interprocess communication consists of messages (mmmmeeeessssgggg), semaphores (sssseeeemmmmaaaa) and shared memory (sssshhhhmmmmeeeemmmm) features. If mmmmeeeessssgggg, sssseeeemmmmaaaa, and/or sssshhhhmmmmeeeemmmm are specified as 0000, the kernel code for these features is not included. If they are specified as 1111, the kernel code is included; this is the default. The features can be specified independent of each other. If the code is included, the parameters listed below can be modified: mesg 1111 msgmap _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a Hewlett-Packard Company - 5 - HP-UX Release 10.20: July 1996 ccccoooonnnnffffiiiigggg((((1111MMMM)))) ccccoooonnnnffffiiiigggg((((1111MMMM)))) msgmax _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a msgmnb _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a msgmni _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a msgseg _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a msgssz _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a msgtql _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a sema 1111 semaem _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a semmap _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a semmni _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a semmns _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a semmnu _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a semume _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a semvmx _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a shmem 1111 shmall _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a smbrk _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a shmmax _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a shmmin _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a shmmni _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a shmseg _n_u_m_b_e_r _o_r _f_o_r_m_u_l_a FFFFIIIILLLLEEEESSSS ////uuuussssrrrr////ccccoooonnnnffff////mmmmaaaasssstttteeeerrrr....dddd////**** default input master kernel configuration tables ////uuuussssrrrr////ccccoooonnnnffff////ccccoooonnnnffffiiiigggg....ssssyyyyssss contains skeleton makefile ////ssssttttaaaannnndddd////ssssyyyysssstttteeeemmmm default system_file ////ssssttttaaaannnndddd////bbbbuuuuiiiilllldddd////ccccoooonnnnffff....cccc default output configuration table ////ssssttttaaaannnndddd////bbbbuuuuiiiilllldddd////ccccoooonnnnffffiiiigggg....mmmmkkkk default output _m_a_k_e(1) script ////ssssttttaaaannnndddd////bbbbuuuuiiiilllldddd////vvvvmmmmuuuunnnniiiixxxx default kernel made by ccccoooonnnnffffiiiigggg SSSSEEEEEEEE AAAALLLLSSSSOOOO make(1), master(4). Hewlett-Packard Company - 6 - HP-UX Release 10.20: July 1996 eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) NNNNAAAAMMMMEEEE eisa_config - EISA configuration tool SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg [----aaaa] eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg [----cccc _c_f_g_f_i_l_e] eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg [----nnnn _s_c_i_f_i_l_e] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg is a specialized program for configuring EISA and ISA (referred to collectively as E/ISA) I/O boards on HP-UX workstations equipped with EISA backplanes. It is used each time the E/ISA configuration is to be changed in any way; i.e., whenever an EISA or ISA board is added to the system, removed from the system, or moved to a different location in the system. eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg should be run before any physical board configuration or installation changes are made. (This is not necessary in some cases -- see automatic mode below.) eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg interprets information stored in configuration files and uses it to configure system resources needed to properly interact with E/ISA boards. Even though they may be physically present in the computer, E/ISA boards cannot be used by the HP-UX operating system until configuration by eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg is complete. The eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg command takes one of four forms: eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg Use interactive commands to examine or modify configuration. eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg prompts for a command, executes it, reports the results of command execution, then prompts for the next command. eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg ----aaaa Attempt to automatically add new EISA boards to the configuration. This option is used by ////ssssbbbbiiiinnnn////bbbbcccchhhheeeecccckkkkrrrrcccc but should not be used elsewhere. ISA boards cannot be added with this option. eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg ----cccc _c_f_g_f_i_l_e Check configuration (CFG) file (discussed below). This option is used mostly by E/ISA board developers. It simply checks the specified CFG file to verify that it follows correct grammar and can be used by eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg. This option does not affect current configuration in any way. Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg ----nnnn _s_c_i_f_i_l_e Non-target mode. This option uses the contents of _s_c_i_f_i_l_e instead of non-volatile memory (NVM) to set up E/ISA configuration, and is most commonly used for creating identical configurations on multiple workstations. AAAAssssssssiiiiggggnnnniiiinnnngggg RRRReeeessssoooouuuurrrrcccceeeessss Depending on their design, internal capabilities, and their role in system operation, E/ISA boards use various combinations of one or more system resources such as DMA channels, interrupt lines, memory, etc. Also, given boards do not always use a full set of system resources; for example, EISA provides 11 interrupt lines, but a given board might be able to use only lines 3, 5, and 6. Thus a means for the board to determine what resources are to be used must be provided. ISA boards use physical switches or jumpers on the board to specify what resources are to be used. The person installing the board sets the switches or jumpers as specified by the board's manufacturer and based on system needs. There are thousands of different kinds of ISA boards, but unfortunately there are no standard conventions for switch and jumper usage. This results in much confusion and numerous configuration problems. For example, it is easy to inadvertently assign a given resource to two different boards, but often very difficult to diagnose the problem. EISA boards usually have no switches or jumpers for resource assignment. Instead, each EISA board has a corresponding configuration (CFG) file that tells the system how the board can be used and what resources it needs. eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg is the HP-UX system program that interprets the various CFG files for all boards in the system, then builds a conflict-free configuration. CCCCoooonnnnffffiiiigggguuuurrrraaaattttiiiioooonnnn FFFFiiiilllleeeessss All EISA boards have a corresponding CFG file. ISA boards, when used in HP-UX systems, must also have a corresponding CFG file. Although eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg cannot automatically configure an ISA board, it can use the contents of the CFG file to determine what switch or jumper settings on an ISA board can be used to prevent resource conflicts. eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg expects to find a CFG file for each E/ISA board connected to the workstation. The administrator is responsible for making sure that these CFG files are present in directory ////ssssbbbbiiiinnnn////lllliiiibbbb////eeeeiiiissssaaaa. CFG files corresponding to boards being used should always be kept in this directory. Do not remove them after eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg is run the first time, because they will be needed every time the configuration is changed, such as when a new board is added or one is removed. Do not change the file names of the CFG files. The file name has a specific format which is used by eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg to automatically match a board with its CFG file. Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) CFG files are normally supplied by the E/ISA board manufacturer. Two scenarios apply: o+ If the E/ISA board is supplied by HP, the CFG file corresponding to the board is loaded into ////ssssbbbbiiiinnnn////lllliiiibbbb////eeeeiiiissssaaaa as part of normal operating system installation. It should never be removed. o+ If the E/ISA board is not supplied by HP, install both the CFG file and the software driver for the board from HP-UX-readable media supplied by the board manufacturer. Copy the CFG file to directory ////ssssbbbbiiiinnnn////lllliiiibbbb////eeeeiiiissssaaaa where it must remain as long as the card is present in the system. All CFG files must follow a grammar specified in the EISA bus specification. The most basic building block in the CFG grammar is the _b_o_a_r_d. Each board has several attributes including board ID (to match with a board's ID register), manufacturer, ASCII text describing what the board does, what kinds of slots the board can go in, whether the board has a readable ID register, and various other capability attributes. Each file can also contain lists of board-wide resources (such as I/O registers, switches, and jumpers) and how they should be initialized. A board can be treated as a set of one or more _f_u_n_c_t_i_o_n_s where a given board contains a single function or multiple functions. An example of a two-function board is one having both a serial port and a parallel printer port. Each function has a separate block in that board's CFG file. Each function has a name, a type, and a set of configuration _c_h_o_i_c_e_s. Each _c_h_o_i_c_e block has a name and a set of attributes. These attributes include what resources the choice requires and whether the function is enabled or disabled by that choice. Initialization is also usually specified within a choice. A given choice might require that certain registers be initialized to a specified value and that switches be set in a certain way. CCCCoooonnnnffffiiiigggguuuurrrraaaattttiiiioooonnnn PPPPrrrroooocccceeeessssssssiiiinnnngggg E/ISA configuration is handled as follows: o+ eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg builds a conflict-free configuration, then saves the configuration in EISA non-volatile memory (NVM). o+ Appropriate drivers and device files must be installed before rebooting the system. o+ Next time the operating system is rebooted, the HP-UX kernel initializes the specified E/ISA boards according to the contents of NVM. Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) If a board is currently present in the system, but has no corresponding configuration data in NVM, the EISA board cannot be used until the eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg program is run again and the new board is accounted for in NVM. A newly installed or existing E/ISA board is not usable until eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg has added it and the system has been rebooted with the necessary drivers and device special files installed. See EXAMPLES for an illustration of how to add a new board to the system. It is possible to add EISA boards that do not have switches or jumpers to the configuration without running eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg interactively. The ////ssssbbbbiiiinnnn////bbbbcccchhhheeeecccckkkkrrrrcccc script invokes eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg with automatic mode during each system initialization. If a board has been added since the last time eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg was executed, eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg attempts to add the new board to the configuration. If the new board is successfully added, the system may need to be rebooted (////ssssbbbbiiiinnnn////bbbbcccchhhheeeecccckkkkrrrrcccc does this automatically). If the new board could not be added to the configuration, a warning is written to the system console and ////eeeettttcccc////eeeeiiiissssaaaa////ccccoooonnnnffffiiiigggg....eeeerrrrrrrr. In addition to writing to NVM, eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg also automatically saves the current configuration to an SCI file called ////eeeettttcccc////eeeeiiiissssaaaa////ssssyyyysssstttteeeemmmm....sssscccciiii. SCI files can also be created by the interactive ssssaaaavvvveeee command (see below). The E/ISA subsystem can also be initialized from an SCI file, rather than from NVM by using the eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg ----nnnn command form discussed earlier. SCI files are quite useful when a site has several identically-configured workstations. Run eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg on one system and save the configuration in an SCI file. Copy this file to other systems, then use it to initialize those systems. Remember that the configuration must be saved to NVM and the system rebooted before the E/ISA boards can be used. DDDDrrrriiiivvvveeeerrrrssss aaaannnndddd DDDDeeeevvvviiiicccceeee FFFFiiiilllleeeessss Running eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg is not the only task necessary when adding an E/ISA board to a system. Corresponding I/O drivers must be added to the kernel and appropriate device files must be created. These steps are the same as is required for any I/O card, and can be performed either before or after running eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg. The important thing to remember is that the E/ISA board cannot be used until _a_l_l necessary tasks are complete. IIIInnnntttteeeerrrraaaaccccttttiiiivvvveeee CCCCoooommmmmmmmaaaannnnddddssss If the command form eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg is used, eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg runs in interactive mode. Interactive mode conducts configuration changes by using a series of keyboard commands. eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg prompts for a command, executes it, displays the results of executing the command, then prompts for the next command. Interactive commands are broadly grouped into five categories: _a_c_t_i_o_n Alter the configuration in some way. Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) _d_i_s_p_l_a_y Show current configuration. _c_f_g Manage CFG files. _c_o_m_m_e_n_t_s Display help and comments information found in CFG files. _h_e_l_p Help for using eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg interactive commands The _a_c_t_i_o_n commands are: aaaadddddddd _c_f_g_f_i_l_e _s_l_o_t_n_u_m Adds a board to the current configuration. _c_f_g_f_i_l_e specifies which CFG file corresponds to the board and _s_l_o_t_n_u_m identifies the slot where the board resides. rrrreeeemmmmoooovvvveeee _s_l_o_t_n_u_m Remove a board from the current configuration. _s_l_o_t_n_u_m identifies the slot where the board currently resides. mmmmoooovvvveeee _c_u_r_s_l_o_t_n_u_m _n_e_w_s_l_o_t_n_u_m Move a board that is currently configured in one slot to a different slot. _c_u_r_s_l_o_t_n_u_m and _n_e_w_s_l_o_t_n_u_m specify the current and new slot numbers, respectively. cccchhhhaaaannnnggggeeee _s_l_o_t_n_u_m _f_u_n_c_t_i_o_n_n_u_m _c_h_o_i_c_e_n_u_m Change the choice used for a given function. All three arguments, _s_l_o_t_n_u_m, _f_u_n_c_t_i_o_n_n_u_m, and _c_h_o_i_c_e_n_u_m are required. The function number (_f_u_n_c_t_i_o_n_n_u_m) and choice number (_c_h_o_i_c_e_n_u_m) can be obtained by using the sssshhhhoooowwww bbbbooooaaaarrrrdddd command on the slot in question. Function numbers are of the format FFFF_n_u_m and choice numbers are of the format CCCCHHHH_n_u_m. Note that a board must already be part of the configuration before the change command can be used. When eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg adds a board, it selects a choice for each function. Generally, the first choice for each function is selected (the default). However, in order to resolve conflicts, eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg may select a different choice for a given function. When specifying a choice for a particular function by use of the cccchhhhaaaannnnggggeeee command, eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg always uses that choice; it does not select a different one, even when a conflict needs to be resolved. Hewlett-Packard Company - 5 - HP-UX Release 10.20: July 1996 eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) ssssaaaavvvveeee [_f_i_l_e_n_a_m_e] Save the current configuration. If the current configuration is not conflict-free, a warning is produced and the save is not done. If you specify a file name, the save is done to that file; otherwise, the save is done to NVM (and the ////eeeettttcccc////eeeeiiiissssaaaa////ssssyyyysssstttteeeemmmm....sssscccciiii file). Note that the qqqquuuuiiiitttt command also (optionally) saves the configuration to NVM (and file ////eeeettttcccc////eeeeiiiissssaaaa////ssssyyyysssstttteeeemmmm....sssscccciiii). When the configuration is saved to NVM, a log file is created that provides a brief desription of the new configuration. The log file is named ////eeeettttcccc////eeeeiiiissssaaaa////ccccoooonnnnffffiiiigggg....lllloooogggg, and contains information generated by a sssshhhhoooowwww command, followed by a sssshhhhoooowwww bbbbooooaaaarrrrdddd command, followed by a sssshhhhoooowwww sssswwwwiiiittttcccchhhh command. iiiinnnniiiitttt [_f_i_l_e_n_a_m_e] Initialize the configuration. The initial configuration is retrieved from a file if one has been specified. Otherwise, it is retrieved from NVM. Note that an implicit iiiinnnniiiitttt is done when eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg is first started. This command should only be used when the current configuration eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg is dealing with is incorrect. For example, if you make some changes that you decide you do not want, you can use this command to start over. qqqquuuuiiiitttt Leave eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg. If the configuration is conflict-free and has been changed, you are asked if you want to save the configuration (to NVM). If any switches or jumpers have to be changed as a result of this new configuration, you are notified of these changes prior to saving the configuration. Be sure that all switches and jumpers match what eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg has specified before booting the system. When the configuration is saved to NVM, a log file is created that provides a brief desription of the new configuration. The log file is named ////eeeettttcccc////eeeeiiiissssaaaa////ccccoooonnnnffffiiiigggg....lllloooogggg, and contains information generated by a sssshhhhoooowwww command, followed by a sssshhhhoooowwww bbbbooooaaaarrrrdddd command, followed by a sssshhhhoooowwww sssswwwwiiiittttcccchhhh command. The _s_h_o_w (display) commands are: Hewlett-Packard Company - 6 - HP-UX Release 10.20: July 1996 eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) sssshhhhoooowwww List all slots and their current status; i.e., whether occupied by a particular board, or empty. sssshhhhoooowwww sssslllloooottttssss _c_f_g_f_i_l_e List all of the slots that could accept the board corresponding to the CFG file _c_f_g_f_i_l_e. sssshhhhoooowwww bbbbooooaaaarrrrdddd [_c_f_g_f_i_l_e|_s_l_o_t_n_u_m] List the basic attributes for the selected board or boards. Includes a list of all the functions on the board and a list of all available choices for each function. If the board is currently part of the configuration, the currently selected choice is marked. The default choice is the first choice listed for each function. If a board is not specified (either by CFG file name or slot number), information is displayed for each of board installed and configured in the system. sssshhhhoooowwww sssswwwwiiiittttcccchhhh [[[[ cccchhhhaaaannnnggggeeeedddd ]]]] [[[[_s_l_o_t_n_u_m]]]] List the switch and jumper settings (both default and required) for the boards in the configuration. If the keyword cccchhhhaaaannnnggggeeeedddd is used, only those switches and jumpers that were changed from the previous configuration are displayed. If a slot number is specified, only switches and jumpers on the board in that slot are displayed. Note that sssshhhhoooowwww sssswwwwiiiittttcccchhhh supports all combinations of cccchhhhaaaannnnggggeeeedddd and _s_l_o_t_n_u_m. There are two kinds of _c_f_g commands: ccccffffggggttttyyyyppppeeeessss List the types of boards that have CFG files in directory ////ssssbbbbiiiinnnn////lllliiiibbbb////eeeeiiiissssaaaa and how many CFG files in ////ssssbbbbiiiinnnn////lllliiiibbbb////eeeeiiiissssaaaa are of each type. ccccffffggggffffiiiilllleeeessss [_t_y_p_e] List all CFG files that are currently available for use in the ////ssssbbbbiiiinnnn////lllliiiibbbb////eeeeiiiissssaaaa directory. If a specific board _t_y_p_e is specified, only CFG files of that type are displayed. _c_o_m_m_e_n_t commands extract the help and comments text provided in the specified CFG file or files. Both help and comments are displayed if they are available. Each command form accepts as an argument either a CFG file or a slot number identifying which board you want help for. ccccoooommmmmmmmeeeennnntttt bbbbooooaaaarrrrdddd [_c_f_g_f_i_l_e|_s_l_o_t_n_u_m] Display board-level help and comments. Hewlett-Packard Company - 7 - HP-UX Release 10.20: July 1996 eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) ccccoooommmmmmmmeeeennnntttt ffffuuuunnnnccccttttiiiioooonnnn [_c_f_g_f_i_l_e|_s_l_o_t_n_u_m] Display function-level help and comments. ccccoooommmmmmmmeeeennnntttt cccchhhhooooiiiicccceeee [_c_f_g_f_i_l_e|_s_l_o_t_n_u_m] Display choice-level help. ccccoooommmmmmmmeeeennnntttt sssswwwwiiiittttcccchhhh [_c_f_g_f_i_l_e|_s_l_o_t_n_u_m] Display help and comments for switches and/or jumpers as appropriate. Note that all arguments (except the type of comments requested) are optional. If no optional argument is specified, all available comments for the specified file or board are extracted. For example: ccccoooommmmmmmmeeeennnntttt bbbbooooaaaarrrrdddd 1111 Display help and comments available for the board currently configured in slot 1. ccccoooommmmmmmmeeeennnntttt bbbbooooaaaarrrrdddd Display help and comments available for _a_l_l currently configured boards. The _h_e_l_p commands explain how to use the eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg interactive commands. If no other arguments are given, help is displayed for all of the interactive commands. Alternatively, any valid command can be used as a argument to the help command. Help is then given for the specified command only. hhhheeeellllpppp Display a brief explanation of all valid eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg interactive commands. hhhheeeellllpppp [_c_m_d_n_a_m_e] Display an explanation of the command specified. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS Add a new E/ISA board to the system: 1. Load the CFG file (from media provided by the manufacturer) into directory ////ssssbbbbiiiinnnn////lllliiiibbbb////eeeeiiiissssaaaa if the file is not already present. 2. Run eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg. eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg reads the contents of NVM to obtain current system configuration. 3. Use the interactive aaaadddddddd command to add the new board. eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg reads the corresponding CFG file to obtain needed configuration information. 4. Exit eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg, noting any required switch or jumper settings. eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg generates a new configuration and writes it to NVM. The required switch and jumper settings are also saved in the log file ////eeeettttcccc////eeeeiiiissssaaaa////ccccoooonnnnffffiiiigggg....lllloooogggg. Hewlett-Packard Company - 8 - HP-UX Release 10.20: July 1996 eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg((((1111MMMM)))) 5. Add the correct software drivers for the board (and board devices) to the kernel, and use _m_k_n_o_d(1M) to create any needed device special files. 6. Shut down and disconnect power to the system. 7. Install the E/ISA board after changing any switch or jumper settings required by eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg. 8. Reboot the system. When the system is running again, the contents of NVM will match the E/ISA boards present in the system, and the newly added board can be used immediately. This procedure can also be used to add multiple new boards at the same time. Simply use the aaaadddddddd command once for each board and alter the other steps as appropriate. If the board to be added is an EISA board that does not have switches or jumpers, the board can be added via automatic mode; that is, steps 2-4 above can be skipped. AAAAUUUUTTTTHHHHOOOORRRR eeeeiiiissssaaaa____ccccoooonnnnffffiiiigggg was developed by HP and Compaq. FFFFIIIILLLLEEEESSSS ////ssssbbbbiiiinnnn////lllliiiibbbb////eeeeiiiissssaaaa////!!!!XXXXXXXXXXXX0000000000000000....CCCCFFFFGGGG CFG files ////eeeettttcccc////eeeeiiiissssaaaa////ccccoooonnnnffffiiiigggg....eeeerrrrrrrr errors encountered in automatic mode ////eeeettttcccc////eeeeiiiissssaaaa////ccccoooonnnnffffiiiigggg....lllloooogggg log file containing current E/ISA configuration ////eeeettttcccc////eeeeiiiissssaaaa////ssssyyyysssstttteeeemmmm....sssscccciiii mirror image of configuration saved to NVM SSSSEEEEEEEE AAAALLLLSSSSOOOO config(1M), mknod(1M). Hewlett-Packard Company - 9 - HP-UX Release 10.20: July 1996 yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) NNNNAAAAMMMMEEEE ypserv, ypbind, ypxfrd - Network Information Service (NIS) server, binder, and transfer processes SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ////uuuussssrrrr////lllliiiibbbb////nnnneeeettttssssvvvvcccc////yyyypppp////yyyyppppsssseeeerrrrvvvv [----llll _l_o_g__f_i_l_e] ////uuuussssrrrr////lllliiiibbbb////nnnneeeettttssssvvvvcccc////yyyypppp////yyyyppppbbbbiiiinnnndddd [----llll _l_o_g__f_i_l_e] [----ssss] [----yyyyppppsssseeeetttt|----yyyyppppsssseeeettttmmmmeeee] ////uuuussssrrrr////ssssbbbbiiiinnnn////yyyyppppxxxxffffrrrrdddd RRRReeeemmmmaaaarrrrkkkkssss The Network Information Service (NIS) was formerly known as Yellow Pages (YP). The functionality remains the same; only the name has changed. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The Network Information Service (NIS) provides a simple network lookup service consisting of databases and processes. The databases are files in a directory tree rooted at ////vvvvaaaarrrr////yyyypppp (see _y_p_f_i_l_e_s(4)). The processes are /_u_s_r/_l_i_b/_n_e_t_s_v_c/_y_p/_y_p_s_e_r_v, the NIS database lookup server, and /_u_s_r/_l_i_b/_n_e_t_s_v_c/_y_p/_y_p_b_i_n_d, the NIS binder. Both yyyyppppsssseeeerrrrvvvv and yyyyppppbbbbiiiinnnndddd are daemon processes activated at system startup time when the NNNNIIIISSSS____MMMMAAAASSSSTTTTEEEERRRR____SSSSEEEERRRRVVVVEEEERRRR or NNNNIIIISSSS____SSSSLLLLAAAAVVVVEEEE____SSSSEEEERRRRVVVVEEEERRRR variable is set to 1, for yyyyppppsssseeeerrrrvvvv,,,, and the NNNNIIIISSSS____CCCCLLLLIIIIEEEENNNNTTTT variable is set to 1, for yyyyppppbbbbiiiinnnndddd,,,, in the ////eeeettttcccc////rrrrcccc....ccccoooonnnnffffiiiigggg....dddd////nnnnaaaammmmeeeessssvvvvrrrrssss file. The NIS programmatic interface is described in _y_p_c_l_n_t(3C). Administrative tools are described in _y_p_w_h_i_c_h(1), _y_p_p_o_l_l(1M), _y_p_p_u_s_h(1M), _y_p_s_e_t(1M) and _y_p_x_f_r(1M). Tools to see the contents of NIS maps (databases) are described in _y_p_c_a_t(1) and _y_p_m_a_t_c_h(1). Database generation and maintenance tools are described in _m_a_k_e_d_b_m(1M), _y_p_i_n_i_t(1M), and _y_p_m_a_k_e(1M). The command to set or show the default NIS domain is _d_o_m_a_i_n_n_a_m_e(1). yyyyppppxxxxffffrrrrdddd transfers entire NIS maps in an efficient manner. For systems that use this daemon, map transfers will be faster, depending on the map. yyyyppppxxxxffffrrrrdddd should be run on a server running HP-UX release 10.0. yyyyppppxxxxffffrrrr (see _y_p_x_f_r(1M)) will attempt to use yyyyppppxxxxffffrrrrdddd first. If that fails, it will use the older transfer method. The yyyyppppxxxxffffrrrrdddd daemon is activated at system startup time when the NNNNIIIISSSS____MMMMAAAASSSSTTTTEEEERRRR____SSSSEEEERRRRVVVVEEEERRRR or NNNNIIIISSSS____SSSSLLLLAAAAVVVVEEEE____SSSSEEEERRRRVVVVEEEERRRR variable is set to 1 in the ////eeeettttcccc////rrrrcccc....ccccoooonnnnffffiiiigggg....dddd////nnnnaaaammmmeeeessssvvvvrrrrssss file. The yyyyppppsssseeeerrrrvvvv daemon's primary function is to look up information in its local collection of NIS maps. It runs only on NIS server machines providing data from NIS databases. Communication to and from yyyyppppsssseeeerrrrvvvv is by means of RPC. Lookup functions are described in _y_p_c_l_n_t(3C). Four lookup functions perform on a specific map within a NIS domain: MMMMaaaattttcccchhhh, GGGGeeeetttt____ffffiiiirrrrsssstttt, GGGGeeeetttt____nnnneeeexxxxtttt, and GGGGeeeetttt____aaaallllllll. The MMMMaaaattttcccchhhh operation matches Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) a key to a record in the database and returns its associated value. The GGGGeeeetttt____ffffiiiirrrrsssstttt operation returns the first key-value pair (record) from the map, and GGGGeeeetttt____nnnneeeexxxxtttt enumerates (sequentially retrieves) the remainder of the records. GGGGeeeetttt____aaaallllllll returns all records in the map to the requester as the response to a single RPC request. Two other functions supply information about the map other than normal map entries: GGGGeeeetttt____oooorrrrddddeeeerrrr____nnnnuuuummmmbbbbeeeerrrr and GGGGeeeetttt____mmmmaaaasssstttteeeerrrr____nnnnaaaammmmeeee. The order number is the time of last modification of a map. The master name is the host name of the machine on which the master map is stored. Both order number and master name exist in the map as special key-value pairs, but the server does not return these through the normal lookup functions. (If you examine the map with mmmmaaaakkkkeeeeddddbbbbmmmm or yyyyppppppppoooollllllll (see _m_a_k_e_d_b_m(1M) or _y_p_p_o_l_l(1M)), they will be visible.) Other functions are used within the NIS system and are not of general interest to NIS clients. They include: DDDDoooo____yyyyoooouuuu____sssseeeerrrrvvvveeee____tttthhhhiiiissss____ddddoooommmmaaaaiiiinnnn???? TTTTrrrraaaannnnssssffffeeeerrrr____mmmmaaaapppp RRRReeeeiiiinnnniiiittttiiiiaaaalllliiiizzzzeeee____iiiinnnntttteeeerrrrnnnnaaaallll____ssssttttaaaatttteeee The yyyyppppbbbbiiiinnnndddd daemon remembers information that lets client processes on its machine communicate with a yyyyppppsssseeeerrrrvvvv process. The yyyyppppbbbbiiiinnnndddd daemon must run on every machine using NIS services, both NIS servers and clients. The yyyyppppsssseeeerrrrvvvv daemon may or may not be running on a NIS client machine, but it must be running somewhere on the network or be available through a gateway. The information that yyyyppppbbbbiiiinnnndddd remembers is called a bbbbiiiinnnnddddiiiinnnngggg: the association of a NIS domain name with the Internet address of the NIS server and the port on that host at which the yyyyppppsssseeeerrrrvvvv process is listening for service requests. This information is cached in the directory ////vvvvaaaarrrr////yyyypppp////bbbbiiiinnnnddddiiiinnnngggg using a filename in the form _d_o_m_a_i_n_n_a_m_e...._v_e_r_s_i_o_n. Client requests drive the binding process. As a request for an unbound domain comes in, the yyyyppppbbbbiiiinnnndddd process broadcasts on the network trying to find a yyyyppppsssseeeerrrrvvvv process serving maps within that NIS domain. Since the binding is established by broadcasting, at least one yyyyppppsssseeeerrrrvvvv process must exist on every network. Once a binding is established for a client, it is given to subsequent client requests. Execute yyyyppppwwwwhhhhiiiicccchhhh to query the yyyyppppbbbbiiiinnnndddd process (local and remote) for its current binding (see _y_p_w_h_i_c_h(1)). Bindings are verified before they are given to a client process. If yyyyppppbbbbiiiinnnndddd is unable to transact with the yyyyppppsssseeeerrrrvvvv process it is bound to, it marks the domain as unbound, tells the client process that the domain is unbound, and tries to bind again. Requests received for an unbound domain fail immediately. Generally, a bound domain is marked as unbound when the node running yyyyppppsssseeeerrrrvvvv crashes or is overloaded. In such a case, yyyyppppbbbbiiiinnnndddd binds to any NIS server (typically one that is Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) less heavily loaded) that is available on the network. The yyyyppppbbbbiiiinnnndddd daemon also accepts requests to set its binding for a particular domain. yyyyppppsssseeeetttt accesses the SSSSeeeetttt____ddddoooommmmaaaaiiiinnnn facility; it is for unsnarling messes and is not for casual use. OOOOppppttttiiiioooonnnnssss yyyyppppsssseeeerrrrvvvv recognizes the following options: ----llll _l_o_g__f_i_l_e Log diagnostic and error messages to the file, _l_o_g__f_i_l_e. If yyyyppppsssseeeerrrrvvvv is started without the ----llll option, yyyyppppsssseeeerrrrvvvv writes its messages to ////vvvvaaaarrrr////yyyypppp////yyyyppppsssseeeerrrrvvvv....lllloooogggg if that file exists. If yyyyppppbbbbiiiinnnndddd is started without the ----llll option, yyyyppppbbbbiiiinnnndddd writes its messages directly to the system console, ////ddddeeeevvvv////ccccoooonnnnssssoooolllleeee. Information logged to the file includes the date and time of the message, the host name, the process id and name of the function generating the message, and the message itself. Note that different services can share a single log file since enough information is included to uniquely identify each message. yyyyppppbbbbiiiinnnndddd recognizes the following options: ----llll _l_o_g__f_i_l_e Log diagnostic and error messages to the file, _l_o_g__f_i_l_e. See the description above. ----ssss Secure. When specified, only NIS servers bound to a reserved port are used. This allows for a slight increase in security in completely controlled environments, where there are no computers operated by untrusted individuals. It offers no real increase in security. ----yyyyppppsssseeeetttt Allow yyyyppppsssseeeetttt to be used to change the binding (see _y_p_s_e_t(1M)). For maximum security, this option should be used only when debugging the network from a remote machine. ----yyyyppppsssseeeettttmmmmeeee Allow yyyyppppsssseeeetttt to be issued from this machine (see _y_p_s_e_t(1M)). Security is based on IP address checking, which can be defeated on networks where untrusted individuals may inject packets. This option is not recommended. Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) AAAAUUUUTTTTHHHHOOOORRRR yyyyppppsssseeeerrrrvvvv, yyyyppppbbbbiiiinnnndddd, and yyyyppppxxxxffffrrrrdddd were developed by Sun Microsystems, Inc. FFFFIIIILLLLEEEESSSS ////vvvvaaaarrrr////yyyypppp////bbbbiiiinnnnddddiiiinnnngggg////_d_o_m_a_i_n_n_a_m_e...._v_e_r_s_i_o_n These files cache the last successful binding created for the given domain, in order to to speed up the binding process. When a binding is requested, these files are checked for validity and then used. ////vvvvaaaarrrr////yyyypppp////sssseeeeccccuuuurrrreeeennnneeeettttssss This file is read by yyyyppppxxxxffffrrrrdddd and yyyyppppsssseeeerrrrvvvv. It contains a list of IP addresses that these servers will allow a binding to. ////vvvvaaaarrrr////yyyypppp////sssseeeeccccuuuurrrreeeesssseeeerrrrvvvveeeerrrrssss This file is read by ypbind. It contains a list of IP addresses that ypbind will receive a binding from. SSSSEEEEEEEE AAAALLLLSSSSOOOO domainname(1), ypcat(1), ypmatch(1), yppasswd(1), ypwhich(1), makedbm(1M), rpcinfo(1M), ypinit(1M), ypmake(1M), yppasswdd(1M), yppoll(1M), yppush(1M), ypset(1M), ypxfr(1M), ypclnt(3C), yppasswd(3N), ypfiles(4). Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 yyyyppppppppaaaasssssssswwwwdddddddd((((1111MMMM)))) yyyyppppppppaaaasssssssswwwwdddddddd((((1111MMMM)))) NNNNAAAAMMMMEEEE yppasswdd - daemon for modifying Network Information Service passwd database SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ////uuuussssrrrr////lllliiiibbbb////nnnneeeettttssssvvvvcccc////yyyypppp////rrrrppppcccc....yyyyppppppppaaaasssssssswwwwdddddddd _p_a_s_s_w_d__f_i_l_e [----llll _l_o_g__f_i_l_e] [----mmmm [_a_r_g_1 _a_r_g_2 ...]] RRRReeeemmmmaaaarrrrkkkkssss The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The yyyyppppppppaaaasssssssswwwwdddddddd daemon handles password change requests from yyyyppppppppaaaasssssssswwwwdddd (see _y_p_p_a_s_s_w_d(1)). It changes a password entry in _p_a_s_s_w_d__f_i_l_e, which must be in the format defined by _p_a_s_s_w_d(4). The change is made only if the old password provided by yyyyppppppppaaaasssssssswwwwdddd matches the encrypted password of that entry. yyyyppppppppaaaasssssssswwwwdddddddd should be executed only on the master Network Information Service (NIS) server for the passwd database (map). The yyyyppppppppaaaasssssssswwwwdddddddd daemon is not executed by default, nor can it be started by iiiinnnneeeettttdddd (see iiiinnnneeeettttdddd(1M)). To enable automatic startup of yyyyppppppppaaaasssssssswwwwdddddddd at boot time, the NNNNIIIISSSS____MMMMAAAASSSSTTTTEEEERRRR____SSSSEEEERRRRVVVVEEEERRRR variable should be set to 1 in file ////eeeettttcccc////rrrrcccc....ccccoooonnnnffffiiiigggg....dddd////nnnnaaaammmmeeeessssvvvvrrrrssss on the master NIS server. OOOOppppttttiiiioooonnnnssss yyyyppppppppaaaasssssssswwwwdddddddd recognizes the following options and command-line arguments: ----llll _l_o_g__f_i_l_e Log diagnostic and error messages to _l_o_g__f_i_l_e. These messages are not available if yyyyppppppppaaaasssssssswwwwdddddddd is started without the ----llll option. Information logged to the file includes date and time of the message, the host name, process ID and name of the function generating the message, and the message itself. Note that different services can share a single log file because enough information is included to uniquely identify each message. ----mmmm [_a_r_g_1 _a_r_g_2 ...] After _p_a_s_s_w_d__f_i_l_e is modified, and if using the ----mmmm option, yyyyppppppppaaaasssssssswwwwdddddddd executes mmmmaaaakkkkeeee to update the NIS passwd database (see _y_p_m_a_k_e(1M) Any arguments following the ----mmmm flag are passed to mmmmaaaakkkkeeee. - 1 - Formatted: August 26, 1998 yyyyppppppppaaaasssssssswwwwdddddddd((((1111MMMM)))) yyyyppppppppaaaasssssssswwwwdddddddd((((1111MMMM)))) To ensure that the passwd map is rebuilt to contain the new password and all slave NIS servers have their passwd maps properly updated to include the change, always use the ----mmmm option to yyyyppppppppaaaasssssssswwwwdddddddd, but do not use the NNNNOOOOPPPPUUUUSSSSHHHH====1111 argument to mmmmaaaakkkkeeee. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS Assume the yyyyppppppppaaaasssssssswwwwdddddddd daemon is started on the master NIS server as follows: ////uuuussssrrrr////lllliiiibbbb////nnnneeeettttssssvvvvcccc////yyyypppp////rrrrppppcccc....yyyyppppppppaaaasssssssswwwwdddddddd ////vvvvaaaarrrr////yyyypppp////ssssrrrrcccc////ppppaaaasssssssswwwwdddd \\\\ ----llll ////vvvvaaaarrrr////aaaaddddmmmm////yyyyppppppppaaaasssssssswwwwdddddddd....lllloooogggg \\\\ ----mmmm ppppaaaasssssssswwwwdddd DDDDIIIIRRRR====////vvvvaaaarrrr////yyyypppp////ssssrrrrcccc This indicates that the ASCII file from which the NIS passwd database is built is ////vvvvaaaarrrr////yyyypppp////ssssrrrrcccc////ppppaaaasssssssswwwwdddd. When this file is updated by a request from yyyyppppppppaaaasssssssswwwwdddd, the NIS passwd database is rebuilt and copied to all slave NIS servers in the master's NIS domain (see _d_o_m_a_i_n_n_a_m_e(1)). Log messages are written to the file ////vvvvaaaarrrr////aaaaddddmmmm////yyyyppppppppaaaasssssssswwwwdddddddd....lllloooogggg. WWWWAAAARRRRNNNNIIIINNNNGGGGSSSS yyyyppppppppaaaasssssssswwwwdddddddd uses lock file ////vvvvaaaarrrr////aaaaddddmmmm////ppppttttmmmmpppp to get exclusive access to _p_a_s_s_w_d__f_i_l_e when updating it. The file ////vvvvaaaarrrr////aaaaddddmmmm////ppppttttmmmmpppp may persist if _p_a_s_s_w_d__f_i_l_e is being updated and o+ The system crashes or o+ yyyyppppppppaaaasssssssswwwwdddddddd is killed using SSSSIIIIGGGGKKKKIIIILLLLLLLL (see _k_i_l_l(1) and _s_i_g_n_a_l(2)). File ////vvvvaaaarrrr////aaaaddddmmmm////ppppttttmmmmpppp must be removed before yyyyppppppppaaaasssssssswwwwdddddddd can function properly again. vvvviiiippppwwww also uses ////vvvvaaaarrrr////aaaaddddmmmm////ppppttttmmmmpppp when updating ////eeeettttcccc////ppppaaaasssssssswwwwdddd (see _v_i_p_w(1M)). As a result, yyyyppppppppaaaasssssssswwwwdddddddd competes with vvvviiiippppwwww when it updates _p_a_s_s_w_d__f_i_l_e if _p_a_s_s_w_d__f_i_l_e is ////eeeettttcccc////ppppaaaasssssssswwwwdddd. AAAAUUUUTTTTHHHHOOOORRRR yyyyppppppppaaaasssssssswwwwdddddddd was developed by Sun Microsystems, Inc. FFFFIIIILLLLEEEESSSS ////vvvvaaaarrrr////aaaaddddmmmm////ppppttttmmmmpppp lock file used when updating _p_a_s_s_w_d__f_i_l_e SSSSEEEEEEEE AAAALLLLSSSSOOOO domainname(1), yppasswd(1), vipw(1M), ypmake(1M), yppasswd(3N), passwd(4), publickey(4), ypfiles(4). - 2 - Formatted: August 26, 1998 yyyyppppppppoooollllllll((((1111MMMM)))) yyyyppppppppoooollllllll((((1111MMMM)))) NNNNAAAAMMMMEEEE yppoll - query NIS server for information about NIS map SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ////uuuussssrrrr////ssssbbbbiiiinnnn////yyyyppppppppoooollllllll [----hhhh _h_o_s_t] [----dddd _d_o_m_a_i_n] _m_a_p_n_a_m_e RRRReeeemmmmaaaarrrrkkkkssss The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN yyyyppppppppoooollllllll asks a Network Information Service (NIS) server process (see _y_p_s_e_r_v(1M)) to return the order number (the ttttiiiimmmmeeee in seconds when the map was built - _t_i_m_e(2)) and master NIS server's host name for a NIS database named _m_a_p_n_a_m_e. yyyyppppppppoooollllllll then writes them to standard output. If the server uses Version 1 NIS protocol, yyyyppppppppoooollllllll uses this older protocol to communicate with it. yyyyppppppppoooollllllll also prints the old style diagnostic messages in case of failure. See _y_p_f_i_l_e_s(4) and _y_p_s_e_r_v(1M) for an overview of Network Information Service. OOOOppppttttiiiioooonnnnssss ----hhhh _h_o_s_t Ask the yyyyppppsssseeeerrrrvvvv process on _h_o_s_t to return the map information (see _y_p_s_e_r_v(1M)). If ----hhhh _h_o_s_t is not specified, the host returned by yyyyppppwwwwhhhhiiiicccchhhh is used (see _y_p_w_h_i_c_h(1)). ----dddd _d_o_m_a_i_n Use _d_o_m_a_i_n instead of the domain returned by ddddoooommmmaaaaiiiinnnnnnnnaaaammmmeeee (see _d_o_m_a_i_n_n_a_m_e(1)). AAAAUUUUTTTTHHHHOOOORRRR yyyyppppppppoooollllllll was developed by Sun Microsystems, Inc. SSSSEEEEEEEE AAAALLLLSSSSOOOO domainname(1), ypwhich(1), ypserv(1M), ypfiles(4). Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) NNNNAAAAMMMMEEEE ypserv, ypbind, ypxfrd - Network Information Service (NIS) server, binder, and transfer processes SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ////uuuussssrrrr////lllliiiibbbb////nnnneeeettttssssvvvvcccc////yyyypppp////yyyyppppsssseeeerrrrvvvv [----llll _l_o_g__f_i_l_e] ////uuuussssrrrr////lllliiiibbbb////nnnneeeettttssssvvvvcccc////yyyypppp////yyyyppppbbbbiiiinnnndddd [----llll _l_o_g__f_i_l_e] [----ssss] [----yyyyppppsssseeeetttt|----yyyyppppsssseeeettttmmmmeeee] ////uuuussssrrrr////ssssbbbbiiiinnnn////yyyyppppxxxxffffrrrrdddd RRRReeeemmmmaaaarrrrkkkkssss The Network Information Service (NIS) was formerly known as Yellow Pages (YP). The functionality remains the same; only the name has changed. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The Network Information Service (NIS) provides a simple network lookup service consisting of databases and processes. The databases are files in a directory tree rooted at ////vvvvaaaarrrr////yyyypppp (see _y_p_f_i_l_e_s(4)). The processes are /_u_s_r/_l_i_b/_n_e_t_s_v_c/_y_p/_y_p_s_e_r_v, the NIS database lookup server, and /_u_s_r/_l_i_b/_n_e_t_s_v_c/_y_p/_y_p_b_i_n_d, the NIS binder. Both yyyyppppsssseeeerrrrvvvv and yyyyppppbbbbiiiinnnndddd are daemon processes activated at system startup time when the NNNNIIIISSSS____MMMMAAAASSSSTTTTEEEERRRR____SSSSEEEERRRRVVVVEEEERRRR or NNNNIIIISSSS____SSSSLLLLAAAAVVVVEEEE____SSSSEEEERRRRVVVVEEEERRRR variable is set to 1, for yyyyppppsssseeeerrrrvvvv,,,, and the NNNNIIIISSSS____CCCCLLLLIIIIEEEENNNNTTTT variable is set to 1, for yyyyppppbbbbiiiinnnndddd,,,, in the ////eeeettttcccc////rrrrcccc....ccccoooonnnnffffiiiigggg....dddd////nnnnaaaammmmeeeessssvvvvrrrrssss file. The NIS programmatic interface is described in _y_p_c_l_n_t(3C). Administrative tools are described in _y_p_w_h_i_c_h(1), _y_p_p_o_l_l(1M), _y_p_p_u_s_h(1M), _y_p_s_e_t(1M) and _y_p_x_f_r(1M). Tools to see the contents of NIS maps (databases) are described in _y_p_c_a_t(1) and _y_p_m_a_t_c_h(1). Database generation and maintenance tools are described in _m_a_k_e_d_b_m(1M), _y_p_i_n_i_t(1M), and _y_p_m_a_k_e(1M). The command to set or show the default NIS domain is _d_o_m_a_i_n_n_a_m_e(1). yyyyppppxxxxffffrrrrdddd transfers entire NIS maps in an efficient manner. For systems that use this daemon, map transfers will be faster, depending on the map. yyyyppppxxxxffffrrrrdddd should be run on a server running HP-UX release 10.0. yyyyppppxxxxffffrrrr (see _y_p_x_f_r(1M)) will attempt to use yyyyppppxxxxffffrrrrdddd first. If that fails, it will use the older transfer method. The yyyyppppxxxxffffrrrrdddd daemon is activated at system startup time when the NNNNIIIISSSS____MMMMAAAASSSSTTTTEEEERRRR____SSSSEEEERRRRVVVVEEEERRRR or NNNNIIIISSSS____SSSSLLLLAAAAVVVVEEEE____SSSSEEEERRRRVVVVEEEERRRR variable is set to 1 in the ////eeeettttcccc////rrrrcccc....ccccoooonnnnffffiiiigggg....dddd////nnnnaaaammmmeeeessssvvvvrrrrssss file. The yyyyppppsssseeeerrrrvvvv daemon's primary function is to look up information in its local collection of NIS maps. It runs only on NIS server machines providing data from NIS databases. Communication to and from yyyyppppsssseeeerrrrvvvv is by means of RPC. Lookup functions are described in _y_p_c_l_n_t(3C). Four lookup functions perform on a specific map within a NIS domain: MMMMaaaattttcccchhhh, GGGGeeeetttt____ffffiiiirrrrsssstttt, GGGGeeeetttt____nnnneeeexxxxtttt, and GGGGeeeetttt____aaaallllllll. The MMMMaaaattttcccchhhh operation matches Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) a key to a record in the database and returns its associated value. The GGGGeeeetttt____ffffiiiirrrrsssstttt operation returns the first key-value pair (record) from the map, and GGGGeeeetttt____nnnneeeexxxxtttt enumerates (sequentially retrieves) the remainder of the records. GGGGeeeetttt____aaaallllllll returns all records in the map to the requester as the response to a single RPC request. Two other functions supply information about the map other than normal map entries: GGGGeeeetttt____oooorrrrddddeeeerrrr____nnnnuuuummmmbbbbeeeerrrr and GGGGeeeetttt____mmmmaaaasssstttteeeerrrr____nnnnaaaammmmeeee. The order number is the time of last modification of a map. The master name is the host name of the machine on which the master map is stored. Both order number and master name exist in the map as special key-value pairs, but the server does not return these through the normal lookup functions. (If you examine the map with mmmmaaaakkkkeeeeddddbbbbmmmm or yyyyppppppppoooollllllll (see _m_a_k_e_d_b_m(1M) or _y_p_p_o_l_l(1M)), they will be visible.) Other functions are used within the NIS system and are not of general interest to NIS clients. They include: DDDDoooo____yyyyoooouuuu____sssseeeerrrrvvvveeee____tttthhhhiiiissss____ddddoooommmmaaaaiiiinnnn???? TTTTrrrraaaannnnssssffffeeeerrrr____mmmmaaaapppp RRRReeeeiiiinnnniiiittttiiiiaaaalllliiiizzzzeeee____iiiinnnntttteeeerrrrnnnnaaaallll____ssssttttaaaatttteeee The yyyyppppbbbbiiiinnnndddd daemon remembers information that lets client processes on its machine communicate with a yyyyppppsssseeeerrrrvvvv process. The yyyyppppbbbbiiiinnnndddd daemon must run on every machine using NIS services, both NIS servers and clients. The yyyyppppsssseeeerrrrvvvv daemon may or may not be running on a NIS client machine, but it must be running somewhere on the network or be available through a gateway. The information that yyyyppppbbbbiiiinnnndddd remembers is called a bbbbiiiinnnnddddiiiinnnngggg: the association of a NIS domain name with the Internet address of the NIS server and the port on that host at which the yyyyppppsssseeeerrrrvvvv process is listening for service requests. This information is cached in the directory ////vvvvaaaarrrr////yyyypppp////bbbbiiiinnnnddddiiiinnnngggg using a filename in the form _d_o_m_a_i_n_n_a_m_e...._v_e_r_s_i_o_n. Client requests drive the binding process. As a request for an unbound domain comes in, the yyyyppppbbbbiiiinnnndddd process broadcasts on the network trying to find a yyyyppppsssseeeerrrrvvvv process serving maps within that NIS domain. Since the binding is established by broadcasting, at least one yyyyppppsssseeeerrrrvvvv process must exist on every network. Once a binding is established for a client, it is given to subsequent client requests. Execute yyyyppppwwwwhhhhiiiicccchhhh to query the yyyyppppbbbbiiiinnnndddd process (local and remote) for its current binding (see _y_p_w_h_i_c_h(1)). Bindings are verified before they are given to a client process. If yyyyppppbbbbiiiinnnndddd is unable to transact with the yyyyppppsssseeeerrrrvvvv process it is bound to, it marks the domain as unbound, tells the client process that the domain is unbound, and tries to bind again. Requests received for an unbound domain fail immediately. Generally, a bound domain is marked as unbound when the node running yyyyppppsssseeeerrrrvvvv crashes or is overloaded. In such a case, yyyyppppbbbbiiiinnnndddd binds to any NIS server (typically one that is Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) less heavily loaded) that is available on the network. The yyyyppppbbbbiiiinnnndddd daemon also accepts requests to set its binding for a particular domain. yyyyppppsssseeeetttt accesses the SSSSeeeetttt____ddddoooommmmaaaaiiiinnnn facility; it is for unsnarling messes and is not for casual use. OOOOppppttttiiiioooonnnnssss yyyyppppsssseeeerrrrvvvv recognizes the following options: ----llll _l_o_g__f_i_l_e Log diagnostic and error messages to the file, _l_o_g__f_i_l_e. If yyyyppppsssseeeerrrrvvvv is started without the ----llll option, yyyyppppsssseeeerrrrvvvv writes its messages to ////vvvvaaaarrrr////yyyypppp////yyyyppppsssseeeerrrrvvvv....lllloooogggg if that file exists. If yyyyppppbbbbiiiinnnndddd is started without the ----llll option, yyyyppppbbbbiiiinnnndddd writes its messages directly to the system console, ////ddddeeeevvvv////ccccoooonnnnssssoooolllleeee. Information logged to the file includes the date and time of the message, the host name, the process id and name of the function generating the message, and the message itself. Note that different services can share a single log file since enough information is included to uniquely identify each message. yyyyppppbbbbiiiinnnndddd recognizes the following options: ----llll _l_o_g__f_i_l_e Log diagnostic and error messages to the file, _l_o_g__f_i_l_e. See the description above. ----ssss Secure. When specified, only NIS servers bound to a reserved port are used. This allows for a slight increase in security in completely controlled environments, where there are no computers operated by untrusted individuals. It offers no real increase in security. ----yyyyppppsssseeeetttt Allow yyyyppppsssseeeetttt to be used to change the binding (see _y_p_s_e_t(1M)). For maximum security, this option should be used only when debugging the network from a remote machine. ----yyyyppppsssseeeettttmmmmeeee Allow yyyyppppsssseeeetttt to be issued from this machine (see _y_p_s_e_t(1M)). Security is based on IP address checking, which can be defeated on networks where untrusted individuals may inject packets. This option is not recommended. Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) yyyyppppsssseeeerrrrvvvv((((1111MMMM)))) AAAAUUUUTTTTHHHHOOOORRRR yyyyppppsssseeeerrrrvvvv, yyyyppppbbbbiiiinnnndddd, and yyyyppppxxxxffffrrrrdddd were developed by Sun Microsystems, Inc. FFFFIIIILLLLEEEESSSS ////vvvvaaaarrrr////yyyypppp////bbbbiiiinnnnddddiiiinnnngggg////_d_o_m_a_i_n_n_a_m_e...._v_e_r_s_i_o_n These files cache the last successful binding created for the given domain, in order to to speed up the binding process. When a binding is requested, these files are checked for validity and then used. ////vvvvaaaarrrr////yyyypppp////sssseeeeccccuuuurrrreeeennnneeeettttssss This file is read by yyyyppppxxxxffffrrrrdddd and yyyyppppsssseeeerrrrvvvv. It contains a list of IP addresses that these servers will allow a binding to. ////vvvvaaaarrrr////yyyypppp////sssseeeeccccuuuurrrreeeesssseeeerrrrvvvveeeerrrrssss This file is read by ypbind. It contains a list of IP addresses that ypbind will receive a binding from. SSSSEEEEEEEE AAAALLLLSSSSOOOO domainname(1), ypcat(1), ypmatch(1), yppasswd(1), ypwhich(1), makedbm(1M), rpcinfo(1M), ypinit(1M), ypmake(1M), yppasswdd(1M), yppoll(1M), yppush(1M), ypset(1M), ypxfr(1M), ypclnt(3C), yppasswd(3N), ypfiles(4). Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 ffffccccnnnnttttllll((((2222)))) ffffccccnnnnttttllll((((2222)))) NNNNAAAAMMMMEEEE fcntl - file control SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<>>> iiiinnnntttt ffffccccnnnnttttllll((((iiiinnnntttt ffffiiiillllddddeeeessss,,,, iiiinnnntttt ccccmmmmdddd,,,, ............ ////**** aaaarrrrgggg ****////))));;;; RRRReeeemmmmaaaarrrrkkkkssss The ANSI C ",,,, ............ " construct denotes a variable length argument list whose optional [or required] members are given in the associated comment (////**** ****////). DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN ffffccccnnnnttttllll(((()))) provides for control over open files. _f_i_l_d_e_s is an open file descriptor. The following are possible values for the _c_m_d argument: FFFF____DDDDUUUUPPPPFFFFDDDD Return a new file descriptor having the following characteristics: o+ Lowest numbered available file descriptor greater than or equal to _a_r_g.vvvvaaaallll. o+ Same open file (or pipe) as the original file. o+ Same file pointer as the original file (that is, both file descriptors share one file pointer). o+ Same access mode (read, write or read/write). o+ Same file status flags (that is, both file descriptors share the same file status flags). o+ The close-on-exec flag associated with the new file descriptor is set to remain open across _e_x_e_c(2) system calls. FFFF____GGGGEEEETTTTFFFFDDDD Get the close-on-exec flag associated with the file descriptor _f_i_l_d_e_s. If the low-order bit is 0000 the file will remain open across _e_x_e_c(2), otherwise the file will be closed upon execution of _e_x_e_c(2). FFFF____SSSSEEEETTTTFFFFDDDD Set the close-on-exec flag associated with _f_i_l_d_e_s to the low-order bit of _a_r_g.vvvvaaaallll (see FFFF____GGGGEEEETTTTFFFFDDDD). Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 ffffccccnnnnttttllll((((2222)))) ffffccccnnnnttttllll((((2222)))) FFFF____GGGGEEEETTTTFFFFLLLL Get file status flags and access modes; see _f_c_n_t_l(5). FFFF____SSSSEEEETTTTFFFFLLLL Set file status flags to _a_r_g...._v_a_l. Only certain flags can be set; see _f_c_n_t_l(5). It is not possible to set both OOOO____NNNNDDDDEEEELLLLAAAAYYYY and OOOO____NNNNOOOONNNNBBBBLLLLOOOOCCCCKKKK. FFFF____GGGGEEEETTTTLLLLKKKK Get the first lock that blocks the lock described by the variable of type ssssttttrrrruuuucccctttt fffflllloooocccckkkk pointed to by _a_r_g. The information retrieved overwrites the information passed to ffffccccnnnnttttllll(((()))) in the fffflllloooocccckkkk structure. If no lock is found that would prevent this lock from being created, the structure is passed back unchanged, except that the lock type is set to FFFF____UUUUNNNNLLLLCCCCKKKK. FFFF____SSSSEEEETTTTLLLLKKKK Set or clear a file segment lock according to the variable of type ssssttttrrrruuuucccctttt fffflllloooocccckkkk pointed to by _a_r_g...._l_o_c_k_d_e_s (see _f_c_n_t_l(5)). The _c_m_d FFFF____SSSSEEEETTTTLLLLKKKK is used to establish read (FFFF____RRRRDDDDLLLLCCCCKKKK) and write (FFFF____WWWWRRRRLLLLCCCCKKKK) locks, as well as to remove either type of lock (FFFF____UUUUNNNNLLLLCCCCKKKK). If a read or write lock cannot be set, ffffccccnnnnttttllll(((()))) returns immediately with an error value of ----1111. FFFF____SSSSEEEETTTTLLLLKKKKWWWW This _c_m_d is the same as FFFF____SSSSEEEETTTTLLLLKKKK except that if a read or write lock is blocked by other locks, the process will sleep until the segment is free to be locked. FFFF____GGGGEEEETTTTOOOOWWWWNNNN If _f_i_l_d_e_s refers to a socket, ffffccccnnnnttttllll(((()))) returns the process or process group ID specified to receive SSSSIIIIGGGGUUUURRRRGGGG signals when out-of-band data is available. Positive values indicate a process ID; negative values, other than -1, indicate a process group ID. FFFF____SSSSEEEETTTTOOOOWWWWNNNN If _f_i_l_d_e_s refers to a socket, ffffccccnnnnttttllll(((()))) sets the process or process group ID specified to receive SSSSIIIIGGGGUUUURRRRGGGG signals when out-of-band data is available, using the value of the third argument, arg, taken as type int. Positive values indicate a process ID; negative values, other than -1, indicate a process group ID. FFFF____GGGGEEEETTTTLLLLKKKK66664444 Same as FFFF____GGGGEEEETTTTLLLLKKKK,,,, except _a_r_g is a pointer to ssssttttrrrruuuucccctttt fffflllloooocccckkkk66664444 instead of ssssttttrrrruuuucccctttt fffflllloooocccckkkk. FFFF____SSSSEEEETTTTLLLLKKKK66664444 Same as FFFF____SSSSEEEETTTTLLLLKKKK, except _a_r_g is a pointer to ssssttttrrrruuuucccctttt fffflllloooocccckkkk66664444 instead of ssssttttrrrruuuucccctttt fffflllloooocccckkkk. Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 ffffccccnnnnttttllll((((2222)))) ffffccccnnnnttttllll((((2222)))) FFFF____SSSSEEEETTTTLLLLKKKKWWWW66664444 Same as FFFF____SSSSEEEETTTTLLLLKKKKWWWW, except _a_r_g is a pointer to ssssttttrrrruuuucccctttt fffflllloooocccckkkk66664444 instead of ssssttttrrrruuuucccctttt fffflllloooocccckkkk. Turning the OOOO____LLLLAAAARRRRGGGGEEEEFFFFIIIILLLLEEEE flag on and off can be done with FFFF____SSSSEEEETTTTFFFFLLLL. A read lock prevents any other process from write-locking the protected area. More than one read lock can exist for a given segment of a file at a given time. The file descriptor on which a read lock is being placed must have been opened with read access. A write lock prevents any other process from read-locking or write-locking the protected area. Only one write lock may exist for a given segment of a file at a given time. The file descriptor on which a write lock is being placed must have been opened with write access. The structure fffflllloooocccckkkk describes the type (llll____ttttyyyyppppeeee), starting offset (llll____wwwwhhhheeeennnncccceeee), relative offset (llll____ssssttttaaaarrrrtttt), size (llll____lllleeeennnn), and process ID (llll____ppppiiiidddd) of the segment of the file to be affected. The process ID field is only used with the FFFF____GGGGEEEETTTTLLLLKKKK _c_m_d to return the value of a block in lock. Locks can start and extend beyond the current end of a file, but cannot be negative relative to the beginning of the file. A lock can be set to always extend to the end of file by setting llll____lllleeeennnn to zero (0). If such a lock also has llll____ssssttttaaaarrrrtttt set to zero (0), the whole file will be locked. Changing or unlocking a segment from the middle of a larger locked segment leaves two smaller segments for either end. Locking a segment already locked by the calling process causes the old lock type to be removed and the new lock type to take effect. All locks associated with a file for a given process are removed when a file descriptor for that file is closed by that process or the process holding that file descriptor terminates. Locks are not inherited by a child process in a _f_o_r_k(2) system call. When enforcement-mode file and record locking is activated on a file (see _c_h_m_o_d(2)), future rrrreeeeaaaadddd(((()))) and wwwwrrrriiiitttteeee(((()))) system calls on the file are affected by the record locks in effect. NNNNEEEETTTTWWWWOOOORRRRKKKKIIIINNNNGGGG FFFFEEEEAAAATTTTUUUURRRREEEESSSS NNNNFFFFSSSS The advisory record-locking capabilities of _f_c_n_t_l(_2) are implemented throughout the network by the ``network lock daemon'' (see _l_o_c_k_d(_1_M)). If the file server crashes and is rebooted, the lock daemon attempts to recover all locks associated with the crashed server. If a lock cannot be reclaimed, the process that held the lock is issued a SSSSIIIIGGGGLLLLOOOOSSSSTTTT signal. Record locking, as implemented for NFS files, is only advisory. Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 ffffccccnnnnttttllll((((2222)))) ffffccccnnnnttttllll((((2222)))) RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE Upon successful completion, the value returned depends on _c_m_d as follows: FFFF____DDDDUUUUPPPPFFFFDDDD A new file descriptor. FFFF____GGGGEEEETTTTFFFFDDDD Value of close-on-exec flag (only the low-order bit is defined). FFFF____SSSSEEEETTTTFFFFDDDD Value other than -1. FFFF____GGGGEEEETTTTFFFFLLLL Value of file status flags and access modes. FFFF____SSSSEEEETTTTFFFFLLLL Value other than -1. FFFF____GGGGEEEETTTTLLLLKKKK Value other than -1. FFFF____SSSSEEEETTTTLLLLKKKK Value other than -1. FFFF____SSSSEEEETTTTLLLLKKKKWWWW Value other than -1. FFFF____GGGGEEEETTTTOOOOWWWWNNNN Value of process or process group ID specified to receive SSSSIIIIGGGGUUUURRRRGGGG signals when out-of-band data is available. FFFF____SSSSEEEETTTTOOOOWWWWNNNN Value other than -1. FFFF____GGGGEEEETTTTLLLLKKKK66664444 Value other than -1. FFFF____SSSSEEEETTTTLLLLKKKK66664444 Value other than -1. FFFF____SSSSEEEETTTTLLLLKKKKWWWW66664444 Value other than -1. Otherwise, a value of -1 is returned and eeeerrrrrrrrnnnnoooo is set to indicate the error. EEEERRRRRRRROOOORRRRSSSS ffffccccnnnnttttllll(((()))) fails if any of the following conditions occur: [EBADF] _f_i_l_d_e_s is not a valid open file descriptor, or was not opened for reading when setting a read lock or for writing when setting a write lock. [EMFILE] _c_m_d is FFFF____DDDDUUUUPPPPFFFFDDDD and the maximum number of file descriptors is currently open. [EMFILE] _c_m_d is FFFF____SSSSEEEETTTTLLLLKKKK or FFFF____SSSSEEEETTTTLLLLKKKKWWWW, the type of lock is a read or write lock, and no more file-locking headers are available (too many files have segments locked). Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 ffffccccnnnnttttllll((((2222)))) ffffccccnnnnttttllll((((2222)))) [EMFILE] _c_m_d is FFFF____DDDDUUUUPPPPFFFFDDDD and _a_r_g...._v_a_l is greater than or equal to the maximum number of file descriptors. [EMFILE] _c_m_d is FFFF____DDDDUUUUPPPPFFFFDDDD and _a_r_g...._v_a_l is negative. [EINVAL] _c_m_d is FFFF____GGGGEEEETTTTLLLLKKKK, FFFF____SSSSEEEETTTTLLLLKKKK, or FFFF____SSSSEEEETTTTLLLLKKKKWWWW, and _a_r_g...._l_o_c_k_d_e_s or the data it points to is not valid, or _f_i_l_d_e_s refers to a file that does not support locking. [EINVAL] _c_m_d is not a valid command. [EINVAL] _c_m_d is FFFF____SSSSEEEETTTTFFFFLLLL and both OOOO____NNNNOOOONNNNBBBBLLLLOOOOCCCCKKKK and OOOO____NNNNDDDDEEEELLLLAAAAYYYY are specified. [EINTR] _c_m_d is FFFF____SSSSEEEETTTTLLLLKKKKWWWW and the call was interrupted by a signal. [EACCES] _c_m_d is FFFF____SSSSEEEETTTTLLLLKKKK, the type of lock (llll____ttttyyyyppppeeee) is a read lock (FFFF____RRRRDDDDLLLLCCCCKKKK) or write lock (FFFF____WWWWRRRRLLLLCCCCKKKK) and the segment of a file to be locked is already write-locked by another process, or the type is a write lock (FFFF____WWWWRRRRLLLLCCCCKKKK) and the segment of a file to be locked is already read- or write-locked by another process. [ENOLCK] _c_m_d is FFFF____SSSSEEEETTTTLLLLKKKK or FFFF____SSSSEEEETTTTLLLLKKKKWWWW, the type of lock is a read or write lock, and no more file-locking headers are available (too many files have segments locked), or no more record locks are available (too many file segments locked). [ENOLCK] _c_m_d is FFFF____SSSSEEEETTTTLLLLKKKK or FFFF____SSSSEEEETTTTLLLLKKKKWWWW, the type of lock (llll____ttttyyyyppppeeee) is a read lock (FFFF____RRRRDDDDLLLLCCCCKKKK) or write lock (FFFF____WWWWRRRRLLLLCCCCKKKK) and the file is an NFS file with access bits set for enforcement mode. [ENOLCK] _c_m_d is FFFF____GGGGEEEETTTTLLLLKKKK, FFFF____SSSSEEEETTTTLLLLKKKK, or FFFF____SSSSEEEETTTTLLLLKKKKWWWW, the file is an NFS file, and a system error occurred on the remote node. [EOVERFLOW] _c_m_d is FFFF____GGGGEEEETTTTLLLLKKKK and the blocking lock's starting offset or length would not fit in the caller's structure. [EDEADLK] _c_m_d is FFFF____SSSSEEEETTTTLLLLKKKKWWWW, when the lock is blocked by a lock from another process and sleeping (waiting) for that lock to become free. This causes a deadlock situation. Hewlett-Packard Company - 5 - HP-UX Release 10.20: July 1996 ffffccccnnnnttttllll((((2222)))) ffffccccnnnnttttllll((((2222)))) [EAGAIN] _c_m_d is FFFF____SSSSEEEETTTTLLLLKKKK or FFFF____SSSSEEEETTTTLLLLKKKKWWWW, and the file is mapped in to virtual memory via the mmmmmmmmaaaapppp(((()))) system call (see _m_m_a_p(2)). [EFAULT] _c_m_d is either FFFF____GGGGEEEETTTTLLLLKKKK, FFFF____SSSSEEEETTTTLLLLKKKK, or FFFF____SSSSEEEETTTTLLLLKKKKWWWW, and _a_r_g points to an illegal address. [ENOTSOCK] _c_m_d is FFFF____GGGGEEEETTTTOOOOWWWWNNNN or FFFF____SSSSEEEETTTTOOOOWWWWNNNN, and _f_i_l_d_e_s does not refer to a socket. AAAAUUUUTTTTHHHHOOOORRRR ffffccccnnnnttttllll(((()))) was developed by HP, AT&T and the University of California, Berkeley. AAAAPPPPPPPPLLLLIIIICCCCAAAATTTTIIIIOOOONNNN UUUUSSSSAAAAGGGGEEEE Because in the future the external variable eeeerrrrrrrrnnnnoooo will be set to EAGAIN rather than EACCES when a section of a file is already locked by another process, portable application programs should expect and test for either value, for example: ffffllllkkkk---->>>>llll____ttttyyyyppppeeee ==== FFFF____RRRRDDDDLLLLCCCCKKKK;;;; iiiiffff ((((ffffccccnnnnttttllll((((ffffdddd,,,, FFFF____SSSSEEEETTTTLLLLKKKK,,,, ffffllllkkkk)))) ======== ----1111)))) iiiiffff ((((((((eeeerrrrrrrrnnnnoooo ======== EEEEAAAACCCCCCCCEEEESSSS)))) |||||||| ((((eeeerrrrrrrrnnnnoooo ======== EEEEAAAAGGGGAAAAIIIINNNN)))))))) ////**** **** sssseeeeccccttttiiiioooonnnn lllloooocccckkkkeeeedddd bbbbyyyy aaaannnnooootttthhhheeeerrrr pppprrrroooocccceeeessssssss,,,, **** cccchhhheeeecccckkkk ffffoooorrrr eeeeiiiitttthhhheeeerrrr EEEEAAAAGGGGAAAAIIIINNNN oooorrrr EEEEAAAACCCCCCCCEEEESSSS **** dddduuuueeee ttttoooo ddddiiiiffffffffeeeerrrreeeennnntttt iiiimmmmpppplllleeeemmmmeeeennnnttttaaaattttiiiioooonnnnssss ****//// eeeellllsssseeee iiiiffff ............ ////**** **** cccchhhheeeecccckkkk ffffoooorrrr ooootttthhhheeeerrrr eeeerrrrrrrroooorrrrssss ****//// SSSSEEEEEEEE AAAALLLLSSSSOOOO lockd(1M), statd(1M), chmod(2), close(2), exec(2), lockf(2), lockf64(), open(2), read(2), write(2), fcntl(5). FFFFUUUUTTTTUUUURRRREEEE DDDDIIIIRRRREEEECCCCTTTTIIIIOOOONNNNSSSS The error condition which currently sets eeeerrrrrrrrnnnnoooo to EACCES will instead set eeeerrrrrrrrnnnnoooo to EAGAIN (see also APPLICATION USAGE above). SSSSTTTTAAAANNNNDDDDAAAARRRRDDDDSSSS CCCCOOOONNNNFFFFOOOORRRRMMMMAAAANNNNCCCCEEEE ffffccccnnnnttttllll(((()))): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 Hewlett-Packard Company - 6 - HP-UX Release 10.20: July 1996 ggggeeeettttggggrrrroooouuuuppppssss((((2222)))) ggggeeeettttggggrrrroooouuuuppppssss((((2222)))) NNNNAAAAMMMMEEEE getgroups - get group access list SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<>>> iiiinnnntttt ggggeeeettttggggrrrroooouuuuppppssss((((iiiinnnntttt nnnnggggrrrroooouuuuppppssss,,,, ggggiiiidddd____tttt ggggiiiiddddsssseeeetttt[[[[]]]]))));;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN ggggeeeettttggggrrrroooouuuuppppssss(((()))) gets the current group access list of the user process and stores it in the array _g_i_d_s_e_t. The parameter _n_g_r_o_u_p_s indicates the number of entries which may be placed in _g_i_d_s_e_t. No more than NNNNGGGGRRRROOOOUUUUPPPPSSSS, as defined in , is ever returned. As a special case, if the _n_g_r_o_u_p_s argument is zero, ggggeeeettttggggrrrroooouuuuppppssss(((()))) returns the number of group entries for the process. In this case, the array pointed to by the _g_i_d_s_e_t argument is not modified. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS The following call to _g_e_t_g_r_o_u_p_s(2) retrieves the group access list of the calling process and stores the group ids in array mygidset: iiiinnnntttt nnnnggggrrrroooouuuuppppssss ==== NNNNGGGGRRRROOOOUUUUPPPPSSSS;;;; ggggiiiidddd____tttt mmmmyyyyggggiiiiddddsssseeeetttt[[[[NNNNGGGGRRRROOOOUUUUPPPPSSSS]]]];;;; iiiinnnntttt nnnnggggrrrrppppssss;;;; nnnnggggrrrrppppssss ==== ggggeeeettttggggrrrroooouuuuppppssss ((((nnnnggggrrrroooouuuuppppssss,,,, mmmmyyyyggggiiiiddddsssseeeetttt))));;;; RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE If successful, ggggeeeettttggggrrrroooouuuuppppssss(((()))) returns a non-negative value indicating the number of elements returned in _g_i_d_s_e_t. If an error occurs, a value of -1 is returned and eeeerrrrrrrrnnnnoooo is set to indicate the type of error. EEEERRRRRRRROOOORRRRSSSS ggggeeeettttggggrrrroooouuuuppppssss(((()))) fails if any of the following conditions are encountered: [EFAULT] _g_i_d_s_e_t specifies an invalid address. The reliable detection of this error is implementation dependent. [EINVAL] The argument _n_g_r_o_u_p_s is not zero and is less than the number of groups in the current group access list of the process. AAAAUUUUTTTTHHHHOOOORRRR ggggeeeettttggggrrrroooouuuuppppssss(((()))) was developed by HP and the University of California, Berkeley SSSSEEEEEEEE AAAALLLLSSSSOOOO setgroups(2), initgroups(3C) Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 ggggeeeettttggggrrrroooouuuuppppssss((((2222)))) ggggeeeettttggggrrrroooouuuuppppssss((((2222)))) SSSSTTTTAAAANNNNDDDDAAAARRRRDDDDSSSS CCCCOOOONNNNFFFFOOOORRRRMMMMAAAANNNNCCCCEEEE ggggeeeettttggggrrrroooouuuuppppssss(((()))): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1 Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 ggggeeeettttppppaaaaggggeeeessssiiiizzzzeeee((((2222)))) ggggeeeettttppppaaaaggggeeeessssiiiizzzzeeee((((2222)))) NNNNAAAAMMMMEEEE getpagesize - get the current page size SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<>>> iiiinnnntttt ggggeeeettttppppaaaaggggeeeessssiiiizzzzeeee((((vvvvooooiiiidddd))));;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The ggggeeeettttppppaaaaggggeeeessssiiiizzzzeeee(((()))) function returns the current page size. The ggggeeeettttppppaaaaggggeeeessssiiiizzzzeeee(((()))) function is equivalent to ssssyyyyssssccccoooonnnnffff((((____SSSSCCCC____PPPPAAAAGGGGEEEE____SSSSIIIIZZZZEEEE)))) and ssssyyyyssssccccoooonnnnffff((((____SSSSCCCC____PPPPAAAAGGGGEEEESSSSIIIIZZZZEEEE)))). RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE The ggggeeeettttppppaaaaggggeeeessssiiiizzzzeeee(((()))) function returns the current page size. EEEERRRRRRRROOOORRRRSSSS No errors are defined. AAAAPPPPPPPPLLLLIIIICCCCAAAATTTTIIIIOOOONNNN UUUUSSSSAAAAGGGGEEEE The value returned by ggggeeeettttppppaaaaggggeeeessssiiiizzzzeeee(((()))) need not be the minimum value that mmmmaaaalllllllloooocccc(((()))) can allocate. Moreover, the application cannot assume that an object of this size can be allocated with mmmmaaaalllllllloooocccc(((()))). SSSSEEEEEEEE AAAALLLLSSSSOOOO brk(), getrlimit(), mmap(), mprotect(), munmap(), msync(), sysconf(), . CCCCHHHHAAAANNNNGGGGEEEE HHHHIIIISSSSTTTTOOOORRRRYYYY First released in Issue 4, Version 2. Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 rrrraaaannnndddd((((3333CCCC)))) rrrraaaannnndddd((((3333CCCC)))) NNNNAAAAMMMMEEEE rand(), rand_r(), srand() - simple random-number generator SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<>>> iiiinnnntttt rrrraaaannnndddd((((vvvvooooiiiidddd))));;;; iiiinnnntttt rrrraaaannnndddd____rrrr((((uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnntttt ****sssseeeeeeeedddd,,,, iiiinnnntttt ****rrrraaaannnnddddvvvvaaaallll))));;;; vvvvooooiiiidddd ssssrrrraaaannnndddd((((uuuunnnnssssiiiiggggnnnneeeedddd iiiinnnntttt sssseeeeeeeedddd))));;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN rrrraaaannnndddd(((()))) uses a multiplicative, congruential, random-number generator with period 2^32 that returns successive pseudo-random numbers in the range from 0 to 2^15-1. ssssrrrraaaannnndddd(((()))) can be called at any time to reset the random-number generator to a random starting point. The generator is initially seeded with a value of 1. RRRReeeeeeeennnnttttrrrraaaannnntttt IIIInnnntttteeeerrrrffffaaaacccceeeessss rrrraaaannnndddd____rrrr(((()))) returns a random number at the address pointed to by the _r_a_n_d_v_a_l parameter. The _s_e_e_d parameter can be set at any time to start the random-number generator at an arbitrary point. Note that rrrraaaannnndddd(((()))) is a thread-safe function. The rrrraaaannnndddd____rrrr(((()))) interface has been provided to allow multiple threads to generate the same sequence of random numbers concurrently. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE If _s_e_e_d or _r_a_n_d_v_a_l is NULL, rrrraaaannnndddd____rrrr(((()))) returns -1 and sets eeeerrrrrrrrnnnnoooo to EINVAL. Otherwise, rrrraaaannnndddd____rrrr(((()))) returns 0. EEEEXXXXAAAAMMMMPPPPLLLLEEEE The following: iiiinnnntttt xxxx,,,, yyyy;;;; srand(10); x = rand(); y = rand(); would produce the same results as: iiiinnnntttt xxxx,,,, yyyy,,,, ssss ==== 11110000;;;; rand_r(&s, &x); rand_r(&s, &y); NNNNOOOOTTTTEEEE The spectral properties of rrrraaaannnndddd(((()))) leave a great deal to be desired. Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 rrrraaaannnndddd((((3333CCCC)))) rrrraaaannnndddd((((3333CCCC)))) ddddrrrraaaannnndddd44448888(((()))) provides a much better, though more elaborate, random-number generator (see _d_r_a_n_d_4_8(3C)). WWWWAAAARRRRNNNNIIIINNNNGGGGSSSS Users of rrrraaaannnndddd____rrrr(((()))) should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. SSSSEEEEEEEE AAAALLLLSSSSOOOO drand48(3C), random(3M). SSSSTTTTAAAANNNNDDDDAAAARRRRDDDDSSSS CCCCOOOONNNNFFFFOOOORRRRMMMMAAAANNNNCCCCEEEE rrrraaaannnndddd(((()))): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C ssssrrrraaaannnndddd(((()))): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 nnnneeeettttggggrrrroooouuuupppp((((4444)))) nnnneeeettttggggrrrroooouuuupppp((((4444)))) NNNNAAAAMMMMEEEE netgroup - list of network groups DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN File ////eeeettttcccc////nnnneeeettttggggrrrroooouuuupppp defines network-wide groups, and is used for permission checking when executing remote mounts, remote logins, and remote shells. For remote mounts, the information in nnnneeeettttggggrrrroooouuuupppp classifies machines; for remote logins and remote shells, it classifies users. Each line of the nnnneeeettttggggrrrroooouuuupppp file defines a group and has the format _g_r_o_u_p_n_a_m_e _m_e_m_b_e_r_1 _m_e_m_b_e_r_2 ... where member_i is either another group name, or a triple. (_h_o_s_t_n_a_m_e, _u_s_e_r_n_a_m_e, _d_o_m_a_i_n_n_a_m_e) If any of these three fields are left empty, it signifies a wild card. Thus uuuunnnniiiivvvveeeerrrrssssaaaallll ((((,,,,,,,,)))) defines a group to which everyone belongs. Field names that begin with something other than a letter, digit or underscore (such as ----) do not match any value. For example, consider the following entries. jjjjuuuussssttttmmmmaaaacccchhhhiiiinnnneeeessss ((((aaaannnnaaaallllyyyyttttiiiiccccaaaa,,,,----,,,,YYYYOOOOUUUURRRRDDDDOOOOMMMMAAAAIIIINNNN)))) jjjjuuuussssttttppppeeeeoooopppplllleeee ((((----,,,,rrrrooooooootttt,,,,YYYYOOOOUUUURRRRDDDDOOOOMMMMAAAAIIIINNNN)))) Machine aaaannnnaaaallllyyyyttttiiiiccccaaaa belongs to the group jjjjuuuussssttttmmmmaaaacccchhhhiiiinnnneeeessss in the domain YYYYOOOOUUUURRRRDDDDOOOOMMMMAAAAIIIINNNN, but no users belong to it. Similarly, the user rrrrooooooootttt belongs to the group jjjjuuuussssttttppppeeeeoooopppplllleeee in the domain YYYYOOOOUUUURRRRDDDDOOOOMMMMAAAAIIIINNNN, but no machines belong to it. Note, for NIS, the domain name field must match the current domain name (as returned by the ddddoooommmmaaaaiiiinnnnnnnnaaaammmmeeee command), or the entry is not matched. This field does not limit the netgroup or provide security. The domainname field refers only to the domain in which the triple is valid, not the domain containing the trusted host. Also, the user- name field is ignored for remote mounts, where only the hostname and domainname are used. The Network Information Service (NIS) can serve network groups. When so used, they are stored in the following NIS maps. netgroup netgroup.byuser netgroup.byhost Refer to _y_p_s_e_r_v(1M) and _y_p_f_i_l_e_s(4) for an overview of Network Information Service. - 1 - Formatted: November 30, 1998 nnnneeeettttggggrrrroooouuuupppp((((4444)))) nnnneeeettttggggrrrroooouuuupppp((((4444)))) AAAAUUUUTTTTHHHHOOOORRRR nnnneeeettttggggrrrroooouuuupppp was developed by Sun Microsystems, Inc. FFFFIIIILLLLEEEESSSS ////eeeettttcccc////nnnneeeettttggggrrrroooouuuupppp SSSSEEEEEEEE AAAALLLLSSSSOOOO makedbm(1M), mountd(1M), ypmake(1M), ypserv(1M), getnetgrent(3C), hosts.equiv(4), ypfiles(4). _I_n_s_t_a_l_l_i_n_g _a_n_d _A_d_m_i_n_i_s_t_e_r_i_n_g _N_F_S _S_e_r_v_i_c_e_s, Chapter 7: NIS Configuration. - 2 - Formatted: November 30, 1998 ppppaaaasssssssswwwwdddd((((4444)))) ppppaaaasssssssswwwwdddd((((4444)))) NNNNAAAAMMMMEEEE passwd - password file, pwd.h DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN ppppaaaasssssssswwwwdddd contains the following information for each user: o+ login name o+ encrypted password o+ numerical user ID o+ numerical group ID o+ reserved field, which can be used for identification o+ initial working directory o+ program to use as shell This is an ASCII file. Each field within each user's entry is separated from the next by a colon. Each user is separated from the next by a newline. This file resides in the ////eeeettttcccc directory. It can and does have general read permission and can be used, for example, to map numerical user IDs to names. If the password field is null and the system has not been converted to a trusted system, no password is demanded. If the shell field is null, ////uuuussssrrrr////bbbbiiiinnnn////sssshhhh is used. The encrypted password consists of 13 characters chosen from a 64- character set of "digits" described below, except when the password is null, in which case the encrypted password is also null. Login can be prevented by entering in the password field a character that is not part of the set of digits (such as ****). The characters used to represent "digits" are .... for 0, //// for 1, 0000 through 9999 for 2 through 11, AAAA through ZZZZ for 12 through 37, and aaaa through zzzz for 38 through 63. Password aging is put in effect for a particular user if his encrypted password in the password file is followed by a comma and a nonnull string of characters from the above alphabet. (Such a string must be introduced in the first instance by a superuser.) This string defines the "age" needed to implement password aging. The first character of the age, _M, denotes the maximum number of weeks for which a password is valid. A user who attempts to login after his password has expired is forced to supply a new one. The next character, _m, denotes the minimum period in weeks that must expire before the password can be changed. The remaining characters define the week (counted from the beginning of 1970) when the password was last changed (a null string is equivalent to zero). _M and _m have numerical values in the range 0 through 63 that correspond to the 64- character set of "digits" shown above. If _m = _M = 0 (derived from the string .... or ........), the user is forced to change his password next time he logs in (and the "age" disappears from his entry in the password Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 ppppaaaasssssssswwwwdddd((((4444)))) ppppaaaasssssssswwwwdddd((((4444)))) file). If _m > _M (signified, for example, by the string ....////), then only a superuser (not the user) can change the password. Not allowing the user to ever change the password is discouraged, especially on a trusted system. Trusted systems support password aging and password generation. For more information on converting to trusted system and on password, see the _H_P-_U_X _S_y_s_t_e_m _A_d_m_i_n_i_s_t_r_a_t_i_o_n _T_a_s_k_s _M_a_n_u_a_l and _s_a_m(1M). _g_e_t_p_w_e_n_t(3C) designates values to the fields in the following structure declared in <<<>>>: ssssttttrrrruuuucccctttt ppppaaaasssssssswwwwdddd {{{{ cccchhhhaaaarrrr ****ppppwwww____nnnnaaaammmmeeee;;;; cccchhhhaaaarrrr ****ppppwwww____ppppaaaasssssssswwwwdddd;;;; uuuuiiiidddd____tttt ppppwwww____uuuuiiiidddd;;;; ggggiiiidddd____tttt ppppwwww____ggggiiiidddd;;;; cccchhhhaaaarrrr ****ppppwwww____aaaaggggeeee;;;; cccchhhhaaaarrrr ****ppppwwww____ccccoooommmmmmmmeeeennnntttt;;;; cccchhhhaaaarrrr ****ppppwwww____ggggeeeeccccoooossss;;;; cccchhhhaaaarrrr ****ppppwwww____ddddiiiirrrr;;;; cccchhhhaaaarrrr ****ppppwwww____sssshhhheeeellllllll;;;; aaaaiiiidddd____tttt ppppwwww____aaaauuuuddddiiiidddd;;;; iiiinnnntttt ppppwwww____aaaauuuuddddffffllllgggg;;;; }}}};;;; It is suggested that the range 0-99 not be used for user and group IDs (ppppwwww____uuuuiiiidddd and ppppwwww____ggggiiiidddd in the above structure) so that IDs that might be assigned for system software do not conflict. The user's full name, office location, extension, and home phone stored in the ppppwwww____ggggeeeeccccoooossss field of the ppppaaaasssssssswwwwdddd structure can be set by use of the cccchhhhffffnnnn command (see _c_h_f_n(1)) and is used by the _f_i_n_g_e_r(1) command. These two commands assume the information in this field is in the order listed above. A portion of the user's real name can be represented in the ppppwwww____ggggeeeeccccoooossss field by an &&&& character, which some utilities (including ffffiiiinnnnggggeeeerrrr) expand by substituting the login name for it and shifting the first letter of the login name to uppercase. SSSSEEEECCCCUUUURRRRIIIITTTTYYYY FFFFEEEEAAAATTTTUUUURRRREEEESSSS On trusted systems, the encrypted password for each user is stored in the file ////ttttccccbbbb////ffffiiiilllleeeessss////aaaauuuutttthhhh////_c////_u_s_e_r__n_a_m_e (where _c is the first letter in _u_s_e_r__n_a_m_e). Password information files are not accessible to the public. The encrypted password can be longer than 13 characters . For example, the password file for user ddddaaaavvvviiiidddd is stored in ////ttttccccbbbb////ffffiiiilllleeeessss////aaaauuuutttthhhh////dddd////ddddaaaavvvviiiidddd. In addition to the password, the user profile in ////ttttccccbbbb////ffffiiiilllleeeessss////aaaauuuutttthhhh////_c////_u_s_e_r__n_a_m_e also contains: o+ numerical audit ID Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 ppppaaaasssssssswwwwdddd((((4444)))) ppppaaaasssssssswwwwdddd((((4444)))) o+ numerical audit flag Like ////eeeettttcccc////ppppaaaasssssssswwwwdddd, this file is an ASCII file. Fields within each user's entry are separated by colons. Refer to _a_u_t_h_c_a_p(4) and _p_r_p_w_d(4) for details. The passwords contained in ////ttttccccbbbb////ffffiiiilllleeeessss////aaaauuuutttthhhh////_c////**** take precedence over those contained in the encrypted password field of ////eeeettttcccc////ppppaaaasssssssswwwwdddd. User authentication is done using the encrypted passwords in this file . The password aging mechanism described in _p_a_s_s_w_d(1), under the section called SSSSEEEECCCCUUUURRRRIIIITTTTYYYY FFFFEEEEAAAATTTTUUUURRRREEEESSSS, applies to this password . NNNNEEEETTTTWWWWOOOORRRRKKKKIIIINNNNGGGG FFFFEEEEAAAATTTTUUUURRRREEEESSSS NNNNFFFFSSSS The ppppaaaasssssssswwwwdddd file can have entries that begin with a plus (++++) or minus (----) sign in the first column. Such lines are used to access the Network Information System network database. A line beginning with a plus (++++) is used to incorporate entries from the Network Information System. There are three styles of ++++ entries: ++++ Insert the entire contents of the Network Information System password file at that point; ++++_n_a_m_e Insert the entry (if any) for _n_a_m_e from the Network Information System at that point ++++@@@@_n_a_m_e Insert the entries for all members of the network group _n_a_m_e at that point. If a ++++ entry has a nonnull password, directory, gecos, or shell field, they override what is contained in the Network Information System. The numerical user ID and group ID fields cannot be overridden. The _p_a_s_s_w_d file can also have lines beginning with a minus (----), which disallow entries from the Network Information System. There are two styles of ---- entries: ----_n_a_m_e Disallow any subsequent entries (if any) for _n_a_m_e. ----@@@@_n_a_m_e Disallow any subsequent entries for all members of the network group _n_a_m_e. WWWWAAAARRRRNNNNIIIINNNNGGGGSSSS User ID (uid) 17 is reserved for the Pascal Language operating system. User ID (uid) 18 is reserved for the BASIC Language operating system. These are operating systems for Series 300 and 400 computers that can coexist with HP-UX on the same disk. Using these uids for other purposes may inhibit file transfer and sharing. The login shell for the root user (uid 0) must be ////ssssbbbbiiiinnnn////sssshhhh.... Other shells such as sh, ksh, and csh are all located under the ////uuuussssrrrr directory which may not be mounted during earlier stages of the bootup Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 ppppaaaasssssssswwwwdddd((((4444)))) ppppaaaasssssssswwwwdddd((((4444)))) process. Changing the login shell of the root user to a value other than ////ssssbbbbiiiinnnn////sssshhhh may result in a non-functional system. The information kept in the ppppwwww____ggggeeeeccccoooossss field may conflict with unsupported or future uses of this field. Use of the ppppwwww____ggggeeeeccccoooossss field for keeping user identification information has not been formalized within any of the industry standards. The current use of this field is derived from its use within the Berkeley Software Distribution. Future standards may define this field for other purposes. The following fields have character limitations as noted: o+ Login name field can be no longer than 8 characters; o+ Initial working directory field can be no longer than 63 characters; o+ Program field can be no longer than 44 characters. o+ Results are unpredictable if these fields are longer than the limits specified above. The following fields have numerical limitations as noted: o+ The user ID is an integer value between -2 and UUUUIIIIDDDD____MMMMAAAAXXXX inclusive. o+ The group ID is an integer value between 0 and UUUUIIIIDDDD____MMMMAAAAXXXX inclusive. o+ If either of these values are out of range, the _g_e_t_p_w_e_n_t(3C) functions reset the ID value to (UUUUIIIIDDDD____MMMMAAAAXXXX). EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS NNNNFFFFSSSS EEEExxxxaaaammmmpppplllleeee Here is a sample ////eeeettttcccc////ppppaaaasssssssswwwwdddd file: rrrrooooooootttt::::3333KKKKmmmm////oooo4444CCCCyyyyqqqq88884444XXXXcccc::::0000::::11110000::::SSSSyyyysssstttteeeemmmm AAAAddddmmmmiiiinnnniiiissssttttrrrraaaattttoooorrrr::::////::::////ssssbbbbiiiinnnn////sssshhhh jjjjooooeeee::::rrrr4444hhhhRRRRJJJJrrrr4444GGGGJJJJ4444CCCCqqqqEEEE::::111100000000::::55550000::::JJJJooooeeee UUUUsssseeeerrrr,,,,PPPPoooosssstttt 4444AAAA,,,,11112222333344445555::::////hhhhoooommmmeeee////jjjjooooeeee::::////uuuussssrrrr////bbbbiiiinnnn////kkkksssshhhh ++++jjjjoooohhhhnnnn:::: ----bbbboooobbbb:::: ++++@@@@ddddooooccccuuuummmmeeeennnnttttaaaattttiiiioooonnnn::::nnnnoooo----llllooooggggiiiinnnn:::: ----@@@@mmmmaaaarrrrkkkkeeeettttiiiinnnngggg:::: ++++::::::::::::GGGGuuuueeeesssstttt In this example, there are specific entries for users rrrrooooooootttt and jjjjooooeeee, in case the Network Information System are out of order. o+ User jjjjoooohhhhnnnn's password entry in the Network Information System is incorporated without change. Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 ppppaaaasssssssswwwwdddd((((4444)))) ppppaaaasssssssswwwwdddd((((4444)))) o+ Any subsequent entries for user bbbboooobbbb are ignored. o+ The password field for anyone in the netgroup ddddooooccccuuuummmmeeeennnnttttaaaattttiiiioooonnnn is disabled. o+ Users in netgroup mmmmaaaarrrrkkkkeeeettttiiiinnnngggg are not returned by _g_e_t_p_w_e_n_t(3C) and thus are not allowed to log in. o+ Anyone else can log in with their usual password, shell, and home directory, but with a ppppwwww____ggggeeeeccccoooossss field of GGGGuuuueeeesssstttt. NNNNFFFFSSSS WWWWaaaarrrrnnnniiiinnnnggggssss The plus (++++) and minus (----) features are NFS functionality; therefore, if NFS is not installed, they do not work. Also, these features work only with ////eeeettttcccc////ppppaaaasssssssswwwwdddd, but not with a system that has been converted to a trusted system. When the system has been converted to a trusted system, the encrypted passwords can be accessed only from the protected password database, ////ttttccccbbbb////ffffiiiilllleeeessss////aaaauuuutttthhhh////****////****. Any user entry in the Network Information System database also must have an entry in the protected password database. The uid of -2 is reserved for remote root access by means of NFS. The ppppwwww____nnnnaaaammmmeeee usually given to this uid is nnnnoooobbbbooooddddyyyy. Since uids are stored as signed values, the following define is included in <<<>>> to match the user nnnnoooobbbbooooddddyyyy. UUUUIIIIDDDD____NNNNOOOOBBBBOOOODDDDYYYY ((((----2222)))) FFFFIIIILLLLEEEESSSS ////ttttccccbbbb////ffffiiiilllleeeessss////aaaauuuutttthhhh////****////**** Protected password database used when system is converted to trusted system. ////eeeettttcccc////ppppaaaasssssssswwwwdddd Standard password file used by HP-UX. SSSSEEEEEEEE AAAALLLLSSSSOOOO chfn(1), finger(1), login(1), passwd(1), a64l(3C), crypt(3C), getprpwent(3), getpwent(3C), authcap(4), limits(5). SSSSTTTTAAAANNNNDDDDAAAARRRRDDDDSSSS CCCCOOOONNNNFFFFOOOORRRRMMMMAAAANNNNCCCCEEEE ppppaaaasssssssswwwwdddd: SVID2, SVID3, XPG2 Hewlett-Packard Company - 5 - HP-UX Release 10.20: July 1996 yyyyppppffffiiiilllleeeessss((((4444)))) yyyyppppffffiiiilllleeeessss((((4444)))) NNNNAAAAMMMMEEEE ypfiles - Network Information Service database and directory structure RRRReeeemmmmaaaarrrrkkkkssss The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The Network Information Service (NIS) network lookup service uses databases in the directory hierarchy under ////vvvvaaaarrrr////yyyypppp. These databases exist only on machines that act as NIS servers. A database consists of two files created by mmmmaaaakkkkeeeeddddbbbbmmmm (see _m_a_k_e_d_b_m(1M)). One has the filename extension ....ppppaaaagggg and the other has the filename extension ....ddddiiiirrrr. For example, the database named nnnneeeettttggggrrrroooouuuupppp is implemented by the pair of files nnnneeeettttggggrrrroooouuuupppp....ppppaaaagggg and nnnneeeettttggggrrrroooouuuupppp....ddddiiiirrrr. A database served by the NIS is called an NIS _m_a_p. An NIS _d_o_m_a_i_n is a named set of Network Information Service maps. Each NIS domain is implemented as a subdirectory of ////vvvvaaaarrrr////yyyypppp (whose name is the domain name) and contains the maps for that domain. Any number of NIS domains can exist, and each can contain any number of maps. Besides the databases contained in ////vvvvaaaarrrr////yyyypppp////_d_o_m_a_i_n, master NIS servers have files named _g_e_n_e_r_a_l__N_I_S__m_a_p_n_a_m_e....ttttiiiimmmmeeee that reside there, too. These files are merely empty files whose times of last modification are compared with those of the ASCII files from which the maps are built. The yyyyppppmmmmaaaakkkkeeee script performs these comparisons to determine whether the maps are current (see _y_p_m_a_k_e(1M)). The _g_e_n_e_r_a_l__N_I_S__m_a_p_n_a_m_e designation is described further in the FILES section below. The NIS lookup service does not require maps, although maps may be required for the normal operation of other parts of the system. The list of maps an NIS server provides access to is neither restricted nor must it be all-inclusive. If a map exists in a given domain and a client asks about it, the NIS serves it. For a map to be consistently accessible, it must exist on all NIS servers that serve the domain. To provide data uniformity between the replicated maps, make an entry to run yyyyppppxxxxffffrrrr periodically in root's ccccrrrroooonnnnttttaaaabbbb file on each server (see _y_p_x_f_r(1M) and _c_r_o_n_t_a_b(1M)). More information on this topic is in _y_p_p_u_s_h(1M) and _y_p_x_f_r(1M). NIS maps contain two special key-value pairs. The first key, _N_I_S__L_A_S_T__M_O_D_I_F_I_E_D, has a 10-character (ASCII) order number as a value. The order number is the ttttiiiimmmmeeee(((()))) in seconds when the map was built (see _t_i_m_e(2)). The second key is _N_I_S__M_A_S_T_E_R__N_A_M_E, whose value is the host name of the map's master NIS server. The mmmmaaaakkkkeeeeddddbbbbmmmm command generates both key-value pairs automatically. The yyyyppppxxxxffffrrrr command uses these values when it transfers a map from one NIS server to another. Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 yyyyppppffffiiiilllleeeessss((((4444)))) yyyyppppffffiiiilllleeeessss((((4444)))) Generate and modify NIS maps only on the master server. They are copied to the slaves using yyyyppppxxxxffffrrrr to avoid potential byte-ordering problems among NIS servers running on machines with different architectures, and to minimize the disk space required for the databases (see _y_p_x_f_r(1M)). NIS databases can be created initially for both masters and slaves by using yyyyppppiiiinnnniiiitttt (see _y_p_i_n_i_t(1M)). After servers' databases are created, the contents of some maps will change. Generally, an ASCII source version of each database exists on the master, and is changed with a text editor. The NIS map is rebuilt to include the changes, and propagated from the master to the slaves by running the yyyyppppmmmmaaaakkkkeeee shell script (see _y_p_m_a_k_e(1M)). All standard NIS maps are built by commands contained in the yyyyppppmmmmaaaakkkkeeee script or the NIS MMMMaaaakkkkeeeeffffiiiilllleeee.... If you add a non-standard NIS map, edit the yyyyppppmmmmaaaakkkkeeee script or MMMMaaaakkkkeeeeffffiiiilllleeee to support the new map (standard NIS maps are discussed under FILES below). yyyyppppmmmmaaaakkkkeeee and MMMMaaaakkkkeeeeffffiiiilllleeee use mmmmaaaakkkkeeeeddddbbbbmmmm to generate the NIS maps on the master and may run yyyyppppppppuuuusssshhhh to copy the rebuilt maps to the slaves (see _y_p_p_u_s_h(1M)). The yyyyppppppppuuuusssshhhh command reads the map named yyyyppppsssseeeerrrrvvvveeeerrrrssss that contains the host names of all NIS servers for the specific domain. For more information, see _y_p_m_a_k_e(1M), _y_p_p_u_s_h(1M), and _y_p_x_f_r(1M). DDDDEEEEPPPPEEEENNNNDDDDEEEENNNNCCCCIIIIEEEESSSS If ////vvvvaaaarrrr////yyyypppp is in a file system that does not allow file names longer than 14 characters and you want to create a new non-standard map for the Network Information Service, its name must not exceed 10 characters in length. This rule exists because mmmmaaaakkkkeeeeddddbbbbmmmm adds the 4- character suffixes ....ddddiiiirrrr and ....ppppaaaagggg to any mapname. The following table describes the translation of standard NIS mapnames to shorter names for storage on a 14-character filename file system. The standard mapnames should be used by NIS clients on HP machines when making requests, regardless of which machine is the NIS server. Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 yyyyppppffffiiiilllleeeessss((((4444)))) yyyyppppffffiiiilllleeeessss((((4444)))) ____________________________________________ SSSSttttaaaannnnddddaaaarrrrdddd NNNNIIIISSSS MMMMaaaappppnnnnaaaammmmeeee AAAAbbbbbbbbrrrreeeevvvviiiiaaaatttteeeedddd MMMMaaaappppnnnnaaaammmmeeee _|______________________|_____________________| |mail.aliases | mail.alias | |mail.byaddr | mail.byad | |ethers.byaddr | ether.byad | |ethers.byname | ether.byna | |group.bygid | group.bygi | |group.byname | group.byna | | | | |hosts.byaddr | hosts.byad | |hosts.byname | hosts.byna | |netgroup | netgroup | |netgroup.byhost | netgr.byho | |netgroup.byuser | netgr.byus | |netid.byname | netid.byn | |networks.byaddr | netwk.byad | |networks.byname | netwk.byna | |passwd.byname | passw.byna | |passwd.byuid | passw.byui | |protocols.byname | proto.byna | |protocols.bynumber | proto.bynu | |publickey.byname | pbkey.byna | |rpc.byname | rpc.byna | |rpc.bynumber | rpc.bynu | |services.byname | servi.byna | |vhe_list | vhe_list | |auto.master | auto.mast | |ypservers | ypservers | _||______________________||_____________________|| AAAAUUUUTTTTHHHHOOOORRRR _y_p_f_i_l_e_s was developed by Sun Microsystems, Inc. FFFFIIIILLLLEEEESSSS The following table presents information about the standard Network Information Service maps. The _G_e_n_e_r_a_l _N_I_S _M_a_p_n_a_m_e column lists names for sets of NIS maps; the sets include adjacent entries from the _S_t_a_n_d_a_r_d _N_I_S _M_a_p_n_a_m_e column. The _A_S_C_I_I _S_o_u_r_c_e column lists the ASCII files from which the maps are usually built on HP master NIS servers. The yyyyppppmmmmaaaakkkkeeee script permits the source directory, or file in the case of the passwd maps, to vary. The _S_t_a_n_d_a_r_d _N_I_S _M_a_p_n_a_m_e column lists names by which maps are stored on NIS servers and referred to by NIS clients. Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 yyyyppppffffiiiilllleeeessss((((4444)))) yyyyppppffffiiiilllleeeessss((((4444)))) _____________________________________________________ |GGGGeeeennnneeeerrrraaaallll NNNNIIIISSSS | | SSSSttttaaaannnnddddaaaarrrrdddd NNNNIIIISSSS | |MMMMaaaappppnnnnaaaammmmeeee | AAAASSSSCCCCIIIIIIII SSSSoooouuuurrrrcccceeee | MMMMaaaappppnnnnaaaammmmeeee | _|_____________|___________________|____________________| |aliases | /etc/mail/aliase | mail.aliases | | | | mail.byaddr | |ethers | * | ethers.byaddr | | | | ethers.byname | |group | /etc/group | group.byname | | | | group.bygid | |hosts | /etc/hosts | hosts.byname | | | | hosts.byaddr | |netgroup | /etc/netgroup | netgroup | | | | netgroup.byhost | | | | netgroup.byuser | |netid | /etc/netid | netid.byname | |networks | /etc/networks | network.byaddr | | | | network.byname | |passwd | /etc/passwd | passwd.byname | | | | passwd.byuid | |protocols | /etc/protocols | protocols.byname | | | | protocols.bynumber | |publickey | /etc/publickey | publickey.byname | |rpc | /etc/rpc | rpc.byname | | | | rcp.bynumber | |services | /etc/services | servi.bynp | | | | services.byname | |automounter | /etc/auto_master | auto.master | |vhe_list | /etc/vhe_list | vhe_list ** | |ypservers | *** | ypservers | _|_____________|___________________|____________________| * These databases are not built on HP master Network Information Service servers. However, if an HP machine is a slave to a master NIS server that creates and distributes these databases, the HP slave NIS server will store these databases. It is suggested that if you have a non-HP machine that requires these maps, make that machine the master NIS server. By doing this, the maps should be built as needed. ** The vvvvhhhheeee____lllliiiisssstttt map is a map generated only by HP master NIS servers. *** No ASCII source exists for the yyyyppppsssseeeerrrrvvvveeeerrrrssss database. It is created from responses provided by the user of yyyyppppiiiinnnniiiitttt on the master NIS server, and it has no matching yyyyppppsssseeeerrrrvvvveeeerrrrssss....ttttiiiimmmmeeee file. SSSSEEEEEEEE AAAALLLLSSSSOOOO domainname(1M), makedbm(1M), rpcinfo(1M), vhe_altlog(1M), Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 yyyyppppffffiiiilllleeeessss((((4444)))) yyyyppppffffiiiilllleeeessss((((4444)))) vhe_mounter(1M), vhe_u_mnt(1M), ypinit(1M), ypmake(1M), yppoll(1M), yppush(1M), ypserv(1M), ypxfr(1M), vhe_list(4). Hewlett-Packard Company - 5 - HP-UX Release 10.20: July 1996 qqqquuuuoooottttaaaa((((5555)))) qqqquuuuoooottttaaaa((((5555)))) NNNNAAAAMMMMEEEE quota - disk quotas DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN Disk quotas can be used by the system administrator to limit the number of files and file blocks owned by a user on a per-file-system basis. Separate limits can be established for both the number of files (inodes) and the number of 1-Kbyte blocks for each user. A _s_o_f_t (preferred) and a _h_a_r_d limit are established. For example, user jjjjooooeeee____ddddooooeeee may have soft limits of 1000 blocks and 200 files and hard limits of 1200 blocks and 300 files on the root file system (////) containing his/her HHHHOOOOMMMMEEEE directory and ////ttttmmmmpppp, and soft and hard block limits of 100 and 120, respectively, with no explicit file limit (0), on the mounted file system ////mmmmnnnntttt. A time limit is established for each file system which determines how long a user is allowed to exceed the soft limit. The default time limit is one week (7 days). When a user exceeds his/her soft limit, a warning is emitted on the user's terminal. The user can continue to increase utilization over the soft limit until he/she either exceeds the hard limit or the established time limit. Once either of these events occurs, a message is sent to the user's terminal and further attempts at file creation and/or increased block utilization will fail. At this point, the user must reduce his/her use of the exceeded limit below the soft limit to restore normal operation. At login time, users exceeding quota limits are reminded (via _l_o_g_i_n(1)) of exceeded quotas and appropriate remedial action. The user can check current quota status at any time with the qqqquuuuoooottttaaaa command (see _q_u_o_t_a(1)). Quota limits and utilization statistics are maintained by the operating system for each file system for which quotas have been enabled (see _m_o_u_n_t(1M) and _q_u_o_t_a_o_n(1M)). Disk quotas are established independently for each user and each file system via the eeeeddddqqqquuuuoooottttaaaa command (see _e_d_q_u_o_t_a(1M)). This command is also used to establish the limit for the amount of time users are permitted to exceed their soft limit. The default time limit is 1 week. Limits and usage statistics are stored statically in the file qqqquuuuoooottttaaaassss on the root of each file system for which they are in effect. This file is synchronized with information in the kernel by the qqqquuuuoooottttaaaaccccttttllll(((()))) system call (see _q_u_o_t_a_c_t_l(2)) and whenever an affected file system is unmounted. Hewlett-Packard Company - 1 - HP-UX Release 10.20: July 1996 qqqquuuuoooottttaaaa((((5555)))) qqqquuuuoooottttaaaa((((5555)))) Quotas can be enabled automatically at boot or mount time by adding the qqqquuuuoooottttaaaassss option to the option list in ////eeeettttcccc////ffffssssttttaaaabbbb (see _f_s_t_a_b(4) and _m_o_u_n_t(1M)). By default, mmmmoooouuuunnnntttt does not enable disk quotas. Quotas can subsequently be disabled and re-enabled with the qqqquuuuoooottttaaaaooooffffffff and qqqquuuuoooottttaaaaoooonnnn commands (see _q_u_o_t_a_o_n(1M)). When quotas are disabled, the kernel does not maintain usage statistics and the qqqquuuuoooottttaaaassss file usage statistics are invalidated by file system activity. Disabling quotas improves performance, but necessitates running the qqqquuuuoooottttaaaacccchhhheeeecccckkkk command (see _q_u_o_t_a_c_h_e_c_k(1M)) to update the kernel and qqqquuuuoooottttaaaassss file after subsequently re-enabling quotas. The rrrreeeeppppqqqquuuuoooottttaaaa command (see _r_e_p_q_u_o_t_a(1M)) displays reports of current quota statistics. The somewhat related, but independent, qqqquuuuooootttt command (see _q_u_o_t(1M)), collects and reports disk utilization independently of the disk quota subsystem. The mmmmoooouuuunnnntttt command (see _m_o_u_n_t(1M)) reports any file systems for which quotas are enabled. DDDDaaaattttaaaa SSSSttttoooorrrraaaaggggeeee SSSSttttrrrruuuuccccttttuuuurrrreeee The ddddqqqqbbbbllllkkkk data structure (defined in <<<>>>), is used by the qqqquuuuoooottttaaaaccccttttllll(((()))) system call (see _q_u_o_t_a_c_t_l(2)) to get or set quota information. This structure contains fields that are used to store a user's current file and block count and quota limits for a particular file system. ssssttttrrrruuuucccctttt ddddqqqqbbbbllllkkkk contains the following members: uuuu____lllloooonnnngggg ddddqqqqbbbb____bbbbhhhhaaaarrrrddddlllliiiimmmmiiiitttt;;;; ////**** mmmmaaaaxxxxiiiimmmmuuuummmm #### ooooffff ddddiiiisssskkkk bbbblllloooocccckkkkssss ++++1111 ****//// uuuu____lllloooonnnngggg ddddqqqqbbbb____bbbbssssooooffffttttlllliiiimmmmiiiitttt;;;; ////**** pppprrrreeeeffffeeeerrrrrrrreeeedddd lllliiiimmmmiiiitttt oooonnnn ddddiiiisssskkkk bbbblllloooocccckkkkssss ****//// uuuu____lllloooonnnngggg ddddqqqqbbbb____ccccuuuurrrrbbbblllloooocccckkkkssss;;;; ////**** ccccuuuurrrrrrrreeeennnntttt bbbblllloooocccckkkk ccccoooouuuunnnntttt ****//// uuuu____lllloooonnnngggg ddddqqqqbbbb____ffffhhhhaaaarrrrddddlllliiiimmmmiiiitttt;;;; ////**** mmmmaaaaxxxxiiiimmmmuuuummmm #### aaaallllllllooooccccaaaatttteeeedddd ffffiiiilllleeeessss ++++1111 ****//// uuuu____lllloooonnnngggg ddddqqqqbbbb____ffffssssooooffffttttlllliiiimmmmiiiitttt;;;; ////**** pppprrrreeeeffffeeeerrrrrrrreeeedddd ffffiiiilllleeee lllliiiimmmmiiiitttt ****//// uuuu____lllloooonnnngggg ddddqqqqbbbb____ccccuuuurrrrffffiiiilllleeeessss;;;; ////**** ccccuuuurrrrrrrreeeennnntttt #### aaaallllllllooooccccaaaatttteeeedddd ffffiiiilllleeeessss ****//// uuuu____lllloooonnnngggg ddddqqqqbbbb____bbbbttttiiiimmmmeeeelllliiiimmmmiiiitttt;;;; ////**** ttttiiiimmmmeeee lllliiiimmmmiiiitttt ffffoooorrrr eeeexxxxcccceeeessssssssiiiivvvveeee bbbblllloooocccckkkk uuuusssseeee ****//// uuuu____lllloooonnnngggg ddddqqqqbbbb____ffffttttiiiimmmmeeeelllliiiimmmmiiiitttt;;;; ////**** ttttiiiimmmmeeee lllliiiimmmmiiiitttt ffffoooorrrr eeeexxxxcccceeeessssssssiiiivvvveeee ffffiiiilllleeeessss ****//// NNNNEEEETTTTWWWWOOOORRRRKKKKIIIINNNNGGGG FFFFEEEEAAAATTTTUUUURRRREEEESSSS Quotas are not fully supported over NFS file systems. However, the qqqquuuuoooottttaaaa command is able to report quota statistics on remote NFS file systems for which disk quotas are in effect, if the remote system provides the RPC rrrrqqqquuuuoooottttaaaadddd service (see _r_q_u_o_t_a_d(1M)). rrrrqqqquuuuoooottttaaaadddd is provided to allow reciprocal support to other systems. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS IIIInnnniiiittttiiiiaaaallll SSSSeeeettttuuuupppp The kernel must be reconfigured to support disk quotas; see the System Administration manuals. Eligible file systems for disk quota enforcement are those with mount options rrrrwwww and qqqquuuuoooottttaaaa, as described in Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996 qqqquuuuoooottttaaaa((((5555)))) qqqquuuuoooottttaaaa((((5555)))) _m_o_u_n_t(1M) and _f_s_t_a_b(4). For each file system for which quotas are to be enabled, perform the following tasks: 1. Mount the file system. 2. Add qqqquuuuoooottttaaaa to the existing options list in ////eeeettttcccc////ffffssssttttaaaabbbb. For example, change the string ddddeeeeffffaaaauuuulllltttt for the root (////) entry to ddddeeeeffffaaaauuuulllltttt,,,,qqqquuuuoooottttaaaa. Once this is done, quotas will automatically be enabled for all relevant file systems on system reboot. 3. Create the qqqquuuuoooottttaaaassss file at the root of the file system. For example, for the ////mmmmnnnntttt file system, run the command ccccppppsssseeeetttt ////ddddeeeevvvv////nnnnuuuullllllll ////mmmmnnnntttt////qqqquuuuoooottttaaaassss 666600000000 rrrrooooooootttt bbbbiiiinnnn 4. Establish one or more prototype user quotas using the eeeeddddqqqquuuuoooottttaaaa command (see _e_d_q_u_o_t_a(1M)). If you want a number of users on your system to have the same limits, use eeeeddddqqqquuuuoooottttaaaa to set those quotas for a prototype user; then use the eeeeddddqqqquuuuoooottttaaaa ----pppp command to replicate those limits for that group of users. 5. Turn on the quotas on the file system using qqqquuuuoooottttaaaaoooonnnn. For example, run the command /usr/sbin/quotaon /mnt 6. Run qqqquuuuoooottttaaaacccchhhheeeecccckkkk (see _q_u_o_t_a_c_h_e_c_k(1M)) on the file system to record the current usage statistics. AAAAddddddddiiiinnnngggg aaaa nnnneeeewwww uuuusssseeeerrrr To add a new user to the quota system: 1. Use eeeeddddqqqquuuuoooottttaaaa to copy the quotas of an existing user. 2. Run qqqquuuuoooottttaaaacccchhhheeeecccckkkk. AAAAddddddddiiiinnnngggg aaaa nnnneeeewwww ffffiiiilllleeee ssssyyyysssstttteeeemmmm ttttoooo aaaannnn eeeessssttttaaaabbbblllliiiisssshhhheeeedddd ssssyyyysssstttteeeemmmm Repeat steps 1 through 5 above under "Initial Setup" for the new file system. WWWWAAAARRRRNNNNIIIINNNNGGGGSSSS The HP-UX default is to allow _c_h_o_w_n(2). This can interfere with the disk quota mechanism. Quotas can be defeated if the cccchhhhoooowwwwnnnn command (see _c_h_o_w_n(1)) or the cccchhhhoooowwwwnnnn(((()))) system call (see _c_h_o_w_n(2)) is accessible to a user. The sssseeeettttpppprrrriiiivvvvggggrrrrpppp command (see _s_e_t_p_r_i_v_g_r_p(1M)) can be used to limit access to the cccchhhhoooowwwwnnnn(((()))) system call so that only a specified group of users are permitted to use the cccchhhhoooowwwwnnnn command or the cccchhhhoooowwwwnnnn(((()))) system Hewlett-Packard Company - 3 - HP-UX Release 10.20: July 1996 qqqquuuuoooottttaaaa((((5555)))) qqqquuuuoooottttaaaa((((5555)))) call. The ssssaaaammmm command (see _s_a_m(1M)) does not yet support disk quotas. When adding new users or file systems, any desired quotas must be established outside of ssssaaaammmm. HP has added features to the original implementation to ensure correctness of the content of the quotas file when quotas are enabled by mmmmoooouuuunnnntttt and disabled by uuuummmmoooouuuunnnntttt (see _m_o_u_n_t(1M)), thus eliminating the need to run qqqquuuuoooottttaaaacccchhhheeeecccckkkk (see _q_u_o_t_a_c_h_e_c_k(1M)). These features are ineffective, however, if qqqquuuuoooottttaaaaooooffffffff and qqqquuuuoooottttaaaaoooonnnn (see _q_u_o_t_a_o_n(1M)) are used to control quotas. qqqquuuuoooottttaaaacccchhhheeeecccckkkk should only be run on a dormant file system to ensure accurate usage information. The ----qqqqvvvv options of the ffffsssscccclllleeeeaaaannnn command (see _f_s_c_l_e_a_n(1M)) report on the the current viability of the quota information. Currently, only HFS file systems support disk quotas, though there may be support for other file systems in the future. AAAAUUUUTTTTHHHHOOOORRRR Disk Quotas were developed by the University of California, Berkeley, Sun Microsystems, and HP. FFFFIIIILLLLEEEESSSS ////eeeettttcccc////ffffssssttttaaaabbbb Static information about the file systems ////eeeettttcccc////mmmmnnnnttttttttaaaabbbb Mounted file system table _d_i_r_e_c_t_o_r_y////qqqquuuuoooottttaaaassss Quota statistics static storage for a file system, where _d_i_r_e_c_t_o_r_y is the root of the file system, as specified to the mmmmoooouuuunnnntttt command (see _m_o_u_n_t(1M)). SSSSEEEEEEEE AAAALLLLSSSSOOOO chown(1), chown(2), quota(1), edquota(1M), fstab(4), mount(1M), quot(1M), quotacheck(1M), quotaon(1M), rquotad(1M), setprivgrp(1M), quotactl(2), vfsmount(2). Hewlett-Packard Company - 4 - HP-UX Release 10.20: July 1996 .\" $Header: imageview.1,v 74.1 95/05/10 21:48:31 ssa Exp $ .TA i .TH imageview 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME imageview \- display, manipulate, and print image files .SH SYNOPSIS .CI /opt/image/bin/imageview \0 .RC [ filename ] .RC [ -d .IC host :\c .IR number \|] .RC [ -g .IR geometry \|] .RC [ -o .IR orientation \|] .SH DESCRIPTION .C imageview displays bit-mapped image files on an X11 display on HP 9000 Series 700 or 800 systems. Through imageview's graphical user interface, which is based on .SM OSF\ /Motif, you can display and manipulate the image, and save certain changes you make. .PP If you have access to SharedPrint/UX printers, you can print the image from .CR "imageview". To set up SharedPrint/UX printers, see your administrator or .CR "setup_pr.sh(1m)". .PP The following table lists types of image files that can be displayed, what these files contain, the filename suffix (extension) .SM HP VUE uses to display the correct icon, and the file version supported. .ifn \{.PP .nf +-----+------------+-----------------------------------+-------------+ |File | VUE File | File Contents Version | |Type | Extension | Supported | +-----+------------+-----------------------------------+-------------+ |TIFF | .tif | PC, scanned, and FAX images | 5.0 (6.0 for| | | | | TIFF JPEG) | |JFIF | .jpg .jpeg | JPEG-compressed images | 8-R8 | |GIF | .gif | xv and xgif images | 87a, 89a | |XWD | .xwd | Pixmap images from xwd (Z format) | X11 | |XBM | .xbm .bm | Bitonal X bitmap images | X11 | |XPM | .xpm .pm | Color X pixmap images | 3.0 | |BMF | .bmf | Starbase bitmap images (Z format) | 1 | |PCX | .pcx | PC bitmap images | 3.0 | |BMP | .bmp | PC bitmap images | 3.0 | |IMG | .img | GEM PC Images | | +-----+------------+-----------------------------------+-------------+ .fi\} .ift \{.PP .TS center box tab(;); cB | cB | cB | cB cB | cB | cB | cB cp-1 | cf4 | l | l. File Type;VUE File;File Contents;Version ;Extension;;Supported _ TIFF;.tif;PC, scanned, and FAX images;5.0 (6.0 for ;;;TIFF JPEG) JFIF;.jpg\0\0.jpeg;JPEG-compressed images;8-R8 GIF;.gif;xv and xgif images;87a, 89a XWD;.xwd;Pixmap images from xwd (Z format);X11 XBM;.xbm\0\0.bm;Bitonal X bitmap images;X11 XPM;.xpm\0\0.pm;Color X pixmap images;3.0 BMF;.bmf;Starbase bitmap images (Z format);1 PCX;.pcx;PC bitmap images; 3.0 BMP;.bmp;PC bitmap images; 3.0 IMG;.img;GEM images .TE\} .PP The TIFF images you can view may be in uncompressed format, or any of the following compressed formats: .SM JPEG, LZW, G3, CCITT/G3, CCITT/G4, or Packbits. .PP The .I filename argument is an absolute or relative pathname of a file containing one or more images in a supported format and can contain .CR * and .C ? pattern specifiers. If .I filename resolves to more than one file, .C imageview displays the first file found. .SS Options .C imageview recognizes the following options: .RS .ift .TP 20 .ifn .TP 10 .CI -d \0host : number Specifies the display to use. Arguments are: .RS .RS .TP 15 .I host Name of the host machine. .TP .I number Number of the display. .RE .RE .IP If the .C -d option is omitted, .C imageview uses the value of the .C DISPLAY environment variable. .TP .CI -g \0geometry Specifies the position and maximum size of the viewer window. The viewer window consists of an image window framed by a menu and control panel. The syntax for .I geometry is the standard X geometry syntax; see .IR X (1) in the reference section of .IR "Using the X Window System" . .IP If the .C -g option is omitted, .C imageview creates a window that matches the image size. If the image is too large for the display, .C imageview creates the largest window possible without changing the ratio of image height to image width. .TP .CI -o \0orientation Sets the initial orientation of the image. .I orientation is one of the following: .RS .RS .TP 15 .C landscape Rotate the image 90 degrees clockwise before displaying. .TP .C portrait Do not rotate the image. .RE .RE .IP If the .C -o option is omitted, .C -o portrait is used. .RE .SH EXAMPLES Display the file .C rgb.tif in the current directory and rotate the first image found 90 degrees clockwise. .IP .C "imageview rgb.tif -o landscape" .PD .SH AUTHOR .C imageview was developed by HP. .SH SEE ALSO sprint(1), spadmin(1m), setup_pr.sh(1m), .br X(1) in .IR "Using the X Window System" . .\" .\" index@\f4imageview\fP \- display bit-mapped file images on an X11 display@@@\f3imageview(1)\f1 .\" index@display bit-mapped file images on an X11 display@@@\f3imageview(1)\f1 .\" index@\s-1TIFF\s0 file images on an X11 display, display@@@\f3imageview(1)\f1 .\" index@file images on an X11 display, display \s-1TIFF\s0@@@\f3imageview(1)\f1 .\" index@images on an X11 display, display \s-1TIFF\s0 file@@@\f3imageview(1)\f1 .\" index@X11 display, display \s-1TIFF\s0 file images on an@@@\f3imageview(1)\f1 .\" index@X11 graphics, display \s-1TIFF\s0 file images on X11 display@@@\f3imageview(1)\f1 .\" index@graphics, display \s-1TIFF\s0 file images on X11 display@@@\f3imageview(1)\f1 .\" .\" toc@\f3imageview(1)\f1:\0\0\f4imageview\fP@@@display bit-mapped images file on an X11 display .\" .\" links@imageview.1 ImageView.1 .\" .\" fileset_database@imageview.1 IMAGE-MAN .\" $XConsortium: X.man,v 1.60 91/09/09 17:27:25 rws Exp $ .TH X 1 "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.* 11.* March 1998 .SH NAME X \- a portable, network-transparent window system .SH SYNOPSIS .PP The X Window System is a network transparent window system developed at MIT which runs on a wide range of computing and graphics machines. It should be relatively straightforward to build the MIT software distribution on most ANSI C and POSIX compliant systems. Commercial implementations are also available for a wide range of platforms. .PP The X Consortium requests that the following names be used when referring to this software: .sp .ce 5 X .br X Window System .br X Version 11 .br X Window System, Version 11 .br X11 .PP .I "X Window System" is a trademark of the Massachusetts Institute of Technology. .SH DESCRIPTION X Window System servers run on computers with bitmap displays. The server distributes user input to and accepts output requests from various client programs through a variety of different interprocess communication channels. Although the most common case is for the client programs to be running on the same machine as the server, clients can be run transparently from other machines (including machines with different architectures and operating systems) as well. .PP X supports overlapping hierarchical subwindows and text and graphics operations, on both monochrome and color displays. For a full explanation of the functions that are available, see the \fIXlib - C Language X Interface\fP manual, the \fIX Window System Protocol\fP specification, the \fIX Toolkit Intrinsics - C Language Interface\fP manual, and various toolkit documents. .PP The number of programs that use \fIX\fP is quite large. Programs provided in the core MIT distribution include: a terminal emulator (\fIxterm\fP), a window manager (\fItwm\fP), a display manager (\fIxdm\fP), a console redirect program (\fIxconsole\fP), mail managing utilities (\fIxmh\fP and \fIxbiff\fP), a manual page browser (\fIxman\fP), a bitmap editor (\fIbitmap\fP), a resource editor (\fIeditres\fP), a ditroff previewer (\fIxditview\fP), access control programs (\fIxauth\fP and \fIxhost\fP), user preference setting programs (\fIxrdb\fP, \fIxcmsdb\fP, \fIxset\fP, \fIxsetroot\fP, \fIxstdcmap\fP, and \fIxmodmap\fP), a load monitor (\fIxload\fP), clocks (\fIxclock\fP and \fIoclock\fP), a font displayer (\fIxfd\fP), utilities for listing information about fonts, windows, and displays (\fIxlsfonts\fP, \fIxfontsel\fP, \fIxwininfo\fP, \fIxlsclients\fP, \fIxdpyinfo\fP, and \fIxprop\fP), a diagnostic for seeing what events are generated and when (\fIxev\fP), screen image manipulation utilities (\fIxwd\fP, \fIxwud\fP, \fIxpr\fP, and \fIxmag\fP), and various demos (\fIxeyes\fP, \fIico\fP, \fIxgc\fP, \fIx11perf\fP, etc.). .PP Hewlett-Packard provides a graphical user environment called The Common Desktop Environment (CDE). CDE is the user interface, enabling the user to control a workstation by directly manipulating graphic objects instead of typing commands on a command-line prompt. See the "CDE User's Guide" and "CDE Advanced User's and System Administrator's Guide" for more information on CDE. .PP Hewlett-Packard does not provide or support the entire core MIT distribution. Many of these programs or clients are sample implementations, or perform tasks that are accomplished by other clients in Hewlett-Packard's Visual User Environment. The primary differences between the core MIT distribution and the Hewlett-Packard X11 release are listed below. See appendix A in "Using the X Window System" for a complete list of the clients supplied and supported with Hewlett-Packard's X11 release. .TP .B Terminal Emulation \fIhpterm\fP is the primary terminal emulator. \fIxterm\fP is also provided and supported. .TP .B Window Management \fItwm\fP is replaced by \fImwm\fP and \fIdtwm\fP. .TP .B Display Manager \fIxdm\fP is replaced by an enhanced version called \fIdtlogin\fP. terminal emulators. .TP .B Bitmap Editing \fIbitmap\fP is replaced by \fIdticon\fP. .TP .B Font Display Handled by the terminal emulation option \fI -fn override\fP. \fIxfd\fP is supplied but not supported. .TP .B Demos \0 Obtained from the INTERWORKS users group. .PP A number of unsupported core MIT clients and miscellaneous utilities are provided in \fI/usr/contrib/bin\fP. In addition, the entire core MIT distribution, compiled for Hewlett-Packard platforms, can be obtained from HP's users group INTERWORKS for a nominal fee. See the release notes for details. .PP Many other utilities, window managers, games, toolkits, etc. are included as user-contributed software in the MIT distribution, or are available using anonymous ftp on the Internet. See your site administrator for details. .SH "STARTING UP" .PP Normally, the X Window System is started on Hewlett-Packard systems by \fIdtlogin\fP, which is an enhanced version of the MIT client \fIxdm\fP. If \fIdtlogin\fP is not used, \fIxinit\fP may be used with \fIx11start\fP. See the man pages for these functions for more information. .SH "DISPLAY NAMES" .PP From the user's perspective, every X server has a \fIdisplay name\fP of the form: .sp .ce 1 \fIhostname:displaynumber.screennumber\fP .sp This information is used by the application to determine how it should connect to the server and which screen it should use by default (on displays with multiple monitors): .TP 8 .I hostname The \fIhostname\fP specifies the name of the machine to which the display is physically connected. If the hostname is not given, the most efficient way of communicating to a server on the same machine will be used. .TP 8 .I displaynumber The phrase "display" is usually used to refer to the collection of monitors that share a common keyboard and pointer (mouse, tablet, etc.). Most workstations tend to only have one keyboard, and therefore, only one display. Larger, multi-user systems, however, will frequently have several displays so that more than one person can be doing graphics work at once. To avoid confusion, each display on a machine is assigned a \fIdisplay number\fP (beginning at 0) when the X server for that display is started. The display number must always be given in a display name. .TP 8 .I screennumber Some displays share a single keyboard and pointer among two or more monitors. Since each monitor has its own set of windows, each screen is assigned a \fIscreen number\fP (beginning at 0) when the X server for that display is started. If the screen number is not given, then screen 0 will be used. .PP On POSIX systems, the default display name is stored in your DISPLAY environment variable. This variable is set automatically by the \fIxterm\fP terminal emulator. However, when you log into another machine on a network, you'll need to set DISPLAY by hand to point to your display. For example, .sp .nf % setenv DISPLAY myws:0 $ DISPLAY=myws:0; export DISPLAY .fi .sp The \fIxon\fP script can be used to start an X program on a remote machine; it automatically sets the DISPLAY variable correctly. .PP Finally, most X programs accept a command line option of \fB-display \fIdisplayname\fR to temporarily override the contents of DISPLAY. This is most commonly used to pop windows on another person's screen or as part of a "remote shell" command to start an xterm pointing back to your display. For example, .sp .nf % xload -display joesws:0 -geometry 100x100+0+0 % rsh big xterm -display myws:0 -ls \fP:\fI/.../\fP .fi .PP An RGB Device specification is identified by the prefix "rgb:" and has the following syntax: .sp .nf rgb:\fI//\fP \fI\fP, \fI\fP, \fI\fP := \fIh\fP | \fIhh\fP | \fIhhh\fP | \fIhhhh\fP \fIh\fP := single hexadecimal digits .fi Note that \fIh\fP indicates the value scaled in 4 bits, \fIhh\fP the value scaled in 8 bits, \fIhhh\fP the value scaled in 12 bits, and \fIhhhh\fP the value scaled in 16 bits, respectively. These values are passed directly to the X server, and are assumed to be gamma corrected. .PP The eight primary colors can be represented as: .sp .ta 2.5i .nf black rgb:0/0/0 red rgb:ffff/0/0 green rgb:0/ffff/0 blue rgb:0/0/ffff yellow rgb:ffff/ffff/0 magenta rgb:ffff/0/ffff cyan rgb:0/ffff/ffff white rgb:ffff/ffff/ffff .fi .PP For backward compatibility, an older syntax for RGB Device is supported, but its continued use is not encouraged. The syntax is an initial sharp sign character followed by a numeric specification, in one of the following formats: .sp .ta 3i .nf #RGB (4 bits each) #RRGGBB (8 bits each) #RRRGGGBBB (12 bits each) #RRRRGGGGBBBB (16 bits each) .fi .PP The R, G, and B represent single hexadecimal digits. When fewer than 16 bits each are specified, they represent the most-significant bits of the value (unlike the "rgb:" syntax, in which values are scaled). For example, #3a7 is the same as #3000a0007000. .PP An RGB intensity specification is identified by the prefix "rgbi:" and has the following syntax: .sp .nf rgbi:\fI//\fP .fi .PP The red, green, and blue are floating point values between 0.0 and 1.0, inclusive. They represent linear intensity values, with 1.0 indicating full intensity, 0.5 half intensity, and so on. These values will be gamma corrected by \fIXlib\fP before being sent to the X server. The input format for these values is an optional sign, a string of numbers possibly containing a decimal point, and an optional exponent field containing an E or e followed by a possibly signed integer string. .PP The standard device-independent string specifications have the following syntax: .sp .ta 3.5i .nf CIEXYZ:\fI//\fP (\fInone\fP, 1, \fInone\fP) CIEuvY:\fI//\fP (~.6, ~.6, 1) CIExyY:\fI//\fP (~.75, ~.85, 1) CIELab:\fI//\fP (100, \fInone\fP, \fInone\fP) CIELuv:\fI//\fP (100, \fInone\fP, \fInone\fP) TekHVC:\fI//\fP (360, 100, 100) .fi .PP All of the values (C, H, V, X, Y, Z, a, b, u, v, y, x) are floating point values. Some of the values are constrained to be between zero and some upper bound; the upper bounds are given in parentheses above. The syntax for these values is an optional '+' or '-' sign, a string of digits possibly containing a decimal point, and an optional exponent field consisting of an 'E' or 'e' followed by an optional '+' or '-' followed by a string of digits. .PP For more information on device independent color, see the \fIXlib\fP reference manual. .SH KEYBOARDS .PP The X keyboard model is broken into two layers: server-specific codes (called \fIkeycodes\fP) which represent the physical keys, and server-independent symbols (called \fIkeysyms\fP) which represent the letters or words that appear on the keys. Two tables are kept in the server for converting keycodes to keysyms: .TP 8 .I "modifier list" Some keys (such as Shift, Control, and Caps Lock) are known as \fImodifier\fP and are used to select different symbols that are attached to a single key (such as Shift-a generates a capital A, and Control-l generates a control character ^L). The server keeps a list of keycodes corresponding to the various modifier keys. Whenever a key is pressed or released, the server generates an \fIevent\fP that contains the keycode of the indicated key as well as a mask that specifies which of the modifier keys are currently pressed. Most servers set up this list to initially contain the various shift, control, and shift lock keys on the keyboard. .TP 8 .I "keymap table" Applications translate event keycodes and modifier masks into keysyms using a \fIkeysym table\fP which contains one row for each keycode and one column for various modifier states. This table is initialized by the server to correspond to normal typewriter conventions. The exact semantics of how the table is interpreted to produce keysyms depends on the particular program, libraries, and language input method used, but the following conventions for the first four keysyms in each row are generally adhered to: .PP The first four elements of the list are split into two groups of keysyms. Group 1 contains the first and second keysyms; Group 2 contains the third and fourth keysyms. Within each group, if the first element is alphabetic and the the second element is the special keysym \fINoSymbol\fP, then the group is treated as equivalent to a group in which the first element is the lowercase letter and the second element is the uppercase letter. .PP Switching between groups is controlled by the keysym named MODE SWITCH, by attaching that keysym to some key and attaching that key to any one of the modifiers Mod1 through Mod5. This modifier is called the ``group modifier.'' Group 1 is used when the group modifier is off, and Group 2 is used when the group modifier is on. .PP Within a group, the modifier state determines which keysym to use. The first keysym is used when the Shift and Lock modifiers are off. The second keysym is used when the Shift modifier is on, when the Lock modifier is on and the second keysym is uppercase alphabetic, or when the Lock modifier is on and is interpreted as ShiftLock. Otherwise, when the Lock modifier is on and is interpreted as CapsLock, the state of the Shift modifier is applied first to select a keysym; but if that keysym is lowercase alphabetic, then the corresponding uppercase keysym is used instead. .SH OPTIONS Most X programs attempt to use the same names for command line options and arguments. All applications written with the X Toolkit Intrinsics automatically accept the following options: .TP 8 .B \-display \fIdisplay\fP This option specifies the name of the X server to use. .TP 8 .B \-geometry \fIgeometry\fP This option specifies the initial size and location of the window. .TP 8 .B \-bg \fIcolor\fP, \fB\-background \fIcolor\fP Either option specifies the color to use for the window background. .TP 8 .B \-bd \fIcolor\fP, \fB\-bordercolor \fIcolor\fP Either option specifies the color to use for the window border. .TP 8 .B \-bw \fInumber\fP, \fB\-borderwidth \fInumber\fP Either option specifies the width in pixels of the window border. .TP 8 .B \-fg \fIcolor\fP, \fB\-foreground \fIcolor\fP Either option specifies the color to use for text or graphics. .TP 8 .B \-fn \fIfont\fP, \fB-font \fIfont\fP Either option specifies the font to use for displaying text. .TP 8 .B \-iconic .br This option indicates that the user would prefer that the application's windows initially not be visible as if the windows had be immediately iconified by the user. Window managers may choose not to honor the application's request. .TP 8 .B \-name .br This option specifies the name under which resources for the application should be found. This option is useful in shell aliases to distinguish between invocations of an application, without resorting to creating links to alter the executable file name. .TP 8 .B \-rv\fP, \fB\-reverse\fP Either option indicates that the program should simulate reverse video if possible, often by swapping the foreground and background colors. Not all programs honor this or implement it correctly. It is usually only used on monochrome displays. .TP 8 .B \+rv .br This option indicates that the program should not simulate reverse video. This is used to override any defaults since reverse video doesn't always work properly. .TP 8 .B \-selectionTimeout This option specifies the timeout in milliseconds within which two communicating applications must respond to one another for a selection request. .TP 8 .B \-synchronous This option indicates that requests to the X server should be sent synchronously, instead of asynchronously. Since .I Xlib normally buffers requests to the server, errors do not necessarily get reported immediately after they occur. This option turns off the buffering so that the application can be debugged. It should never be used with a working program. .TP 8 .B \-title \fIstring\fP This option specifies the title to be used for this window. This information is sometimes used by a window manager to provide some sort of header identifying the window. .TP 8 .B \-xnllanguage \fIlanguage[_territory][.codeset]\fP This option specifies the language, territory, and codeset for use in resolving resource and other filenames. .TP 8 .B \-xrm \fIresourcestring\fP This option specifies a resource name and value to override any defaults. It is also very useful for setting resources that don't have explicit command line arguments. .SH RESOURCES To make the tailoring of applications to personal preferences easier, X provides a mechanism for storing default values for program resources (e.g. background color, window title, etc.) Resources are specified as strings that are read in from various places when an application is run. Program components are named in a hierarchical fashion, with each node in the hierarchy identified by a class and an instance name. At the top level is the class and instance name of the application itself. By convention, the class name of the application is the same as the program name, but with the first letter capitalized, although some programs that begin with the letter ``x'' also capitalize the second letter for historical reasons. .PP The precise syntax for resources is: .PP .nf .ta 1.8i 2.0i ResourceLine = Comment | IncludeFile | ResourceSpec | Comment = "!" {} IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace FileName = ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value ResourceName = [Binding] {Component Binding} ComponentName Binding = "\&." | "*" WhiteSpace = { | } Component = "?" | ComponentName ComponentName = NameChar {NameChar} NameChar = "a"\-"z" | "A"\-"Z" | "0"\-"9" | "_" | "-" Value = {} .fi .PP Elements separated by vertical bar (|) are alternatives. Curly braces ({\&.\&.\&.}) indicate zero or more repetitions of the enclosed elements. Square brackets ([\&.\&.\&.]) indicate that the enclosed element is optional. Quotes ("\&.\&.\&.") are used around literal characters. .PP IncludeFile lines are interpreted by replacing the line with the contents of the specified file. The word "include" must be in lowercase. The filename is interpreted relative to the directory of the file in which the line occurs (for example, if the filename contains no directory or contains a relative directory specification). .PP If a ResourceName contains a contiguous sequence of two or more Binding characters, the sequence will be replaced with single "\&." character if the sequence contains only "\&." characters, otherwise the sequence will be replaced with a single "*" character. .PP A resource database never contains more than one entry for a given ResourceName. If a resource file contains multiple lines with the same ResourceName, the last line in the file is used. .PP Any whitespace character before or after the name or colon in a ResourceSpec are ignored. To allow a Value to begin with whitespace, the two-character sequence ``\\\^\fIspace\fP'' (backslash followed by space) is recognized and replaced by a space character, and the two-character sequence ``\\\^\fItab\fP'' (backslash followed by horizontal tab) is recognized and replaced by a horizontal tab character. To allow a Value to contain embedded newline characters, the two-character sequence ``\\\^n'' is recognized and replaced by a newline character. To allow a Value to be broken across multiple lines in a text file, the two-character sequence ``\\\^\fInewline\fP'' (backslash followed by newline) is recognized and removed from the value. To allow a Value to contain arbitrary character codes, the four-character sequence ``\\\^\fInnn\fP'', where each \fIn\fP is a digit character in the range of ``0''\-``7'', is recognized and replaced with a single byte that contains the octal value specified by the sequence. Finally, the two-character sequence ``\\\\'' is recognized and replaced with a single backslash. .PP When an application looks for the value of a resource, it specifies a complete path in the hierarchy, with both class and instance names. However, resource values are usually given with only partially specified names and classes, using pattern matching constructs. An asterisk (*) is a loose binding and is used to represent any number of intervening components, including none. A period (.) is a tight binding and is used to separate immediately adjacent components. A question mark (?) is used to match any single component name or class. A database entry cannot end in a loose binding; the final component (which cannot be "?") must be specified. The lookup algorithm searches the resource database for the entry that most closely matches (is most specific for) the full name and class being queried. When more than one database entry matches the full name and class, precedence rules are used to select just one. .LP The full name and class are scanned from left to right (from highest level in the hierarchy to lowest), one component at a time. At each level, the corresponding component and/or binding of each matching entry is determined, and these matching components and bindings are compared according to precedence rules. Each of the rules is applied at each level, before moving to the next level, until a rule selects a single entry over all others. The rules (in order of precedence) are: .IP 1. 5 An entry that contains a matching component (whether name, class, or "?") takes precedence over entries that elide the level (that is, entries that match the level in a loose binding). .IP 2. 5 An entry with a matching name takes precedence over both entries with a matching class and entries that match using "?". An entry with a matching class takes precedence over entries that match using "?". .IP 3. 5 An entry preceded by a tight binding takes precedence over entries preceded by a loose binding. .PP Programs based on the X Tookit Intrinsics obtain resources from the following sources (other programs usually support some subset of these sources): .TP 8 .B "RESOURCE_MANAGER root window property" Any global resources that should be available to clients on all machines should be stored in the RESOURCE_MANAGER property on the root window of the first screen using the \fIxrdb\fP program. This is frequently taken care of when the user starts X through the display manager. .TP 8 .B "SCREEN_RESOURCES root window property" Any resources specific to a given screen (e.g. colors) that should be available to clients on all machines should be stored in the SCREEN_RESOURCES property on the root window of that screen. The \fIxrdb\fP program will sort resources automatically and place them in RESOURCE_MANAGER or SCREEN_RESOURCES, as appropriate. .TP 8 .B "application-specific files" Directories named by the environment variable XUSERFILESEARCHPATH or the environment variable XAPPLRESDIR, plus directories in a standard place (usually under /usr/lib/X11/, but this can be overridden with the XFILESEARCHPATH environment variable) are searched for for application-specific resources. For example, application default resources are usually kept in /usr/lib/X11/app-defaults/. See the \fIX Toolkit Intrinsics - C Language Interface\fP manual for details. .TP 8 .B XENVIRONMENT Any user- and machine-specific resources may be specified by setting the XENVIRONMENT environment variable to the name of a resource file to be loaded by all applications. If this variable is not defined, a file named \fI$HOME\fP/.Xdefaults-\fIhostname\fP is looked for instead, where \fIhostname\fP is the name of the host where the application is executing. .TP 8 .B \-xrm \fIresourcestring\fP Resources can also be specified from the command line. The \fIresourcestring\fP is a single resource name and value as shown above. Note that if the string contains characters interpreted by the shell (e.g., asterisk), they must be quoted. Any number of \fB\-xrm\fP arguments may be given on the command line. .PP Program resources are organized into groups called \fIclasses\fP, so that collections of individual resources (each of which are called \fIinstances\fP) can be set all at once. By convention, the instance name of a resource begins with a lowercase letter and class name with an upper case letter. Multiple word resources are concatenated with the first letter of the succeeding words capitalized. Applications written with the X Toolkit Intrinsics will have at least the following resources: .PP .TP 8 .B background (\fPclass\fB Background) This resource specifies the color to use for the window background. .PP .TP 8 .B borderWidth (\fPclass\fB BorderWidth) This resource specifies the width in pixels of the window border. .PP .TP 8 .B borderColor (\fPclass\fB BorderColor) This resource specifies the color to use for the window border. .PP Most applications using the X Toolkit Intrinsics also have the resource \fBforeground\fP (class \fBForeground\fP), specifying the color to use for text and graphics within the window. .PP By combining class and instance specifications, application preferences can be set quickly and easily. Users of color displays will frequently want to set Background and Foreground classes to particular defaults. Specific color instances such as text cursors can then be overridden without having to define all of the related resources. For example, .sp .nf XTerm*cursorColor: gold XTerm*multiScroll: on XTerm*jumpScroll: on XTerm*reverseWrap: on XTerm*curses: on XTerm*Font: 6x10 XTerm*scrollBar: on XTerm*scrollbar*thickness: 5 XTerm*multiClickTime: 500 XTerm*charClass: 33:48,37:48,45-47:48,64:48 XTerm*cutNewline: off XTerm*cutToBeginningOfLine: off XTerm*titeInhibit: on XTerm*ttyModes: intr ^c erase ^? kill ^u XLoad*Background: gold XLoad*Foreground: red XLoad*highlight: black XLoad*borderWidth: 0 hpterm*Geometry: 80x65-0-0 hpterm*Background: rgb:5b/76/86 hpterm*Foreground: white hpterm*Cursor: white hpterm*BorderColor: white hpterm*Font: 6x10 .fi .PP If these resources were stored in a file called \fI.Xdefaults\fP in your home directory, they could be added to any existing resources in the server with the following command: .sp .nf % xrdb -merge $HOME/.Xdefaults .fi .sp This is frequently how user-friendly startup scripts merge user-specific defaults into any site-wide defaults. All sites are encouraged to set up convenient ways of automatically loading resources. See the \fIXlib\fP manual section \fIResource Manager Functions\fP for more information. .SH EXAMPLES The following is a collection of sample command lines for some of the more frequently used commands. For more information on a particular command, please refer to that command's manual page. .sp .nf % xrdb $HOME/.Xdefaults % xmodmap -e "keysym BackSpace = Delete" % mkfontdir /usr/local/lib/X11/otherfonts % xset fp+ /usr/local/lib/X11/otherfonts % xmodmap $HOME/.keymap.km % xsetroot -solid 'rgbi:.8/.8/.8' % xset b 100 400 c 50 s 1800 r on % xset q % mwm % xclock -geometry 48x48-0+0 -bg blue -fg white % xlsfonts '*helvetica*' % xwininfo -root % xhost -joesworkstation % xwd | xwud % xterm -geometry 80x66-0-0 -name myxterm $* .fi .SH DIAGNOSTICS A wide variety of error messages are generated from various programs. The default error handler in \fIXlib\fP (also used by many toolkits) uses standard resources to construct diagnostic messages when errors occur. The defaults for these messages are usually stored in \fI/usr/lib/X11/XErrorDB\fP. If this file is not present, error messages will be rather terse and cryptic. .PP When the X Toolkit Intrinsics encounter errors converting resource strings to the appropriate internal format, no error messages are usually printed. This is convenient when it is desirable to have one set of resources across a variety of displays (e.g. color vs. monochrome, lots of fonts vs. very few, etc.), although it can pose problems for trying to determine why an application might be failing. This behavior can be overridden by the setting the \fIStringConversionsWarning\fP resource. .PP To force the X Toolkit Intrinsics to always print string conversion error messages, the following resource should be placed in the \fI.Xdefaults\fP file in the user's home directory. This file is then loaded into the RESOURCE_MANAGER property using the \fIxrdb\fP program. .sp .nf *StringConversionWarnings: on .fi .sp To have conversion messages printed for just a particular application, the appropriate instance name can be placed before the asterisk: .sp .nf xterm*StringConversionWarnings: on .fi .SH "SEE ALSO" .PP .\" introductions .\" clients, utilities, and demos bdftopcf(1), bitmap(1), fs(1), hpterm(1) mkfontdir(1), mwm(1), xauth(1), xclock(1), xcmsdb(1), xfd(1), xhost(1), xinitcolor(1), xload(1), xlsfonts(1), xmodmap(1), xpr(1), xprop(1), xrdb(1), xrefresh(1), xset(1), xsetroot(1), xterm(1), xwd(1), xwininfo(1), xwud(1), .\" servers Xserver(1), .\" specifications .I "Xlib \- C Language X Interface\fR,\fP" and .I "X Toolkit Intrinsics \- C Language Interface" .SH COPYRIGHT .PP The following copyright and permission notice outlines the rights and restrictions covering most parts of the core distribution of the X Window System from MIT. Other parts have additional or different copyrights and permissions; see the individual source files. .sp Copyright 1984, 1985, 1986, 1987, 1988, 1989, 1990, 1991 by the Massachusetts Institute of Technology. .sp Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of MIT not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. MIT makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. .SH TRADEMARKS .PP X Window System is a trademark of MIT. .SH AUTHORS .PP A cast of thousands, literally. The MIT Release 5 distribution is brought to you by the MIT X Consortium. The names of all people who made it a reality will be found in the individual documents and source files. The staff members at MIT responsible for this release are: Donna Converse (MIT X Consortium), Stephen Gildea (MIT X Consortium), Susan Hardy (MIT X Consortium), Jay Hersh (MIT X Consortium), Keith Packard (MIT X Consortium), David Sternlicht (MIT X Consortium), Bob Scheifler (MIT X Consortium), and Ralph Swick (Digital/MIT Project Athena). .TH Xserver 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.*, 11.* March 1998 .SH NAME X - X Window System server .SH SYNOPSIS .B X :\fIdisplaynumber\fP [-option] \fIttyname\fP .SH DESCRIPTION .I X is the generic name for the window system server. It is started by the \fIdtlogin\fP program which is typically run by \fIinit(1M)\fP. Alternatively it may be started from the \fIxinit(1)\fP program, which is called by \fIx11start\fR. The \fIdisplaynumber\fP argument is used by clients in their DISPLAY environment variables to indicate which server to contact (large machines may have several displays attached). This number can be any number. If no number is specified 0 is used. This number is also used in determining the names of various startup files. The \fIttyname\fP argument is passed in by \fIinit\fP and isn't used. .PP The Hewlett-Packard server has support for the following protocols: .TP 8 .B TCP\/IP .br The server listens on port 6000+N, where N is the display number. .TP 8 .B "Local Socket IPC Mechanism" The file name for the socket is "/var/spool/sockets/X11/*" where "*" is the display number. .TP 8 .B Shared Memory IPC This is the default connection that the X Library will use to connect to an X server on the same machine if the DISPLAY environment variable is set to "local:*" or ":*" where "*" is the number of the display. .PP When the server starts up, it takes over the display. If you are running on a workstation whose console is the display, you cannot log into the console while the server is running. .SH OPTIONS The following options can be given on the command line to the X server. .TP 8 .B \-a \fInumber\fP sets pointer acceleration (i.e. the ratio of how much is reported to how much the user actually moved the pointer). .TP 8 .B \-audit \fIlevel\fP Sets the audit trail level. The default level is 1, meaning only connection rejections are reported. Level 2 additionally reports all successful connections and disconnects. Level 0 turns off the audit trail. Audit lines are sent as standard error output. .TP 8 .B \-auth \fIauthorization-file\fP Specifies a file which contains a collection of authorization records used to authenticate access. .TP 8 .B bc disables certain kinds of error checking, for bug compatibility with previous releases (e.g., to work around bugs in R2 and R3 xterms and toolkits). Deprecated. .TP 8 .B \-bs disables backing store support on all screens. .TP 8 .B \-c turns off key-click. .TP 8 .B c \fIvolume\fP sets key-click volume (allowable range: 0-100). .TP 8 .B \-co \fIfilename\fP sets name of RGB color database. .TP 8 .B \-core causes the server to generate a core dump on fatal errors. .TP 8 .B \-dpi \fIresolution\fP sets the resolution of the screen, in dots per inch. To be used when the server cannot determine the screen size from the hardware. .TP 8 .B \-f \fIvolume\fP sets feep (bell) volume (allowable range: 0-100). .TP 8 .B \-fc \fIcursorFont\fP sets default cursor font. .TP 8 .B \-fn \fIfont\fP sets the default font. .TP 8 .B \-fp \fIfontPath\fP sets the search path for fonts. This path is a comma separated list of directories which the server searches for font databases. .TP 8 .B \-help prints a usage message. .TP 8 .B \-I causes all remaining command line arguments to be ignored. .TP 8 .B \-logo turns on the X Window System logo display in the screen-saver. There is currently no way to change this from a client. You also need to specify -v to enable the logo to appear. .TP 8 .B nologo turns off the X Window System logo display in the screen-saver. There is currently no way to change this from a client. .TP 8 .B \-p \fIminutes\fP sets screen-saver pattern cycle time in minutes. .TP 8 .B \-pn allows X server to run even if one or more communications mechanisms fails to initialize. .TP 8 .B \-pn permits the server to continue running if it fails to establish all of its well-known sockets, but establishes at least one. .TP 8 .B \-r turns off keyboard auto-repeat. .TP 8 .B r turns on keyboard auto-repeat. .TP 8 .B \-s \fIminutes\fP sets screen-saver timeout time in minutes. .TP 8 .B \-su disables save under support on all screens. .TP 8 .B \-t \fInumber\fP sets pointer acceleration threshold in pixels (i.e. after how many pixels pointer acceleration should take effect). .TP 8 .B \-terminate causes the server to terminate at server reset, instead of continuing to run. .TP 8 .B \-to \fIseconds\fP sets default connection timeout in seconds. .TP 8 .B \-tst disables all testing extensions (e.g., XTEST, XTestExtension1). .TP 8 .B tty\fIxx\fP ignored, for servers started the ancient way (from init). .TP 8 .B \-terminage causes server to terminate when all clients disconnect. .TP 8 .B v sets video-on screen-saver preference. A window that changes regularly will be used to save the screen. .TP 8 .B \-v sets video-off screen-saver preference. The screen will be blanked to save the screen. .TP 8 .B \-wm forces the default backing-store of all windows to be WhenMapped; a less expensive way of getting backing-store to apply to all windows. .TP 8 .PP You can also have the X server connect to xdm(1) or dtlogin(1X) using XDMCP. Although this is not typically useful as it doesn't allow xdm to manage the server process, it can be used to debug XDMCP implementations, and serves as a sample implementation of the server side of XDMCP. The following options control the behavior of XDMCP. .TP 8 .B \-query \fIhost-name\fP Enable XDMCP and send Query packets to the specified host. .TP 8 .B \-broadcast Enable XDMCP and broadcast BroadcastQuery packets to the network. The first responding display manager will be chosen for the session. .TP 8 .B \-indirect \fIhost-name\fP Enable XDMCP and send IndirectQuery packets to the specified host. .TP 8 .B \-port \fIport-num\fP Use an alternate port number for XDMCP packets. Must be specified before any -query, -broadcast or -indirect options. Default port number is 177. .TP 8 .B \-class \fIdisplay-class\fP XDMCP has an additional display qualifier used in resource lookup for display-specific options. This option sets that value, by default it is "MIT-Unspecified" (not a very useful value). .TP 8 .B \-cookie \fIxdm-auth-bits\fP When testing XDM-AUTHENTICATION-1, a private key is shared between the server and the manager. This option sets the value of that private data (not that it's very private, being on the command line and all...). .TP 8 .B \-displayID \fIdisplay-id\fP Yet another XDMCP specific value, this one allows the display manager to identify each display so that it can locate the shared key. .PP .SH "RUNNING FROM INIT" .PP Though X will usually be run by \fIdtlogin\fP from \fIinit\fP, it is possible to run X directly from \fIinit\fP. For information about running X from \fIdtlogin\fP, see the \fIdtlogin\fP man page. To run X directly from \fIinit\fR, it is necessary to modify \fI/etc/inittab\fR and \fI/etc/gettydefs\fR. Detailed information on these files may be obtained from the \fIinittab(4)\fR and \fIgettydefs(4)\fR man pages. .PP To run X from \fIinit\fR on display 0, with a login \fIxterm\fR running on \fI/dev/ttypf\fR, in init state 3, the following line must be added to \fI/etc/inittab\fR: .PP X0:3:respawn:env PATH=/bin:/usr/bin/X11:/usr/bin xinit -L ttyqf -- :0 .PP To run X with a login \fIhpterm\fR, the following should be used instead: .PP X0:3:respawn:env PATH=/bin:/usr/bin/X11:/usr/bin xinit hpterm =+1+1 -n login -L ttyqf -- :0 .PP In addition, the following line must be added to \fI/etc/gettydefs\fR (this should be a single line): .PP Xwindow# B9600 HUPCL PARENB CS7 # B9600 SANE PARENB CS7 ISTRIP IXANY TAB3 \0\0#X login: #Xwindow .PP There should not be a getty running against the display whenever X is run from \fIxinit\fR. .SH "SECURITY" .PP The sample server implements a simplistic authorization protocol, MIT-MAGIC-COOKIE-1 which uses data private to authorized clients and the server. This is a rather trivial scheme; if the client passes authorization data which is the same as the server has, it is allowed access. This scheme is inferior to host-based access control mechanisms in environments with unsecure networks as it allows any host to connect, given that it has discovered the private key. But in many environments, this level of security is better than the host-based scheme as it allows access control per-user instead of per-host. .PP In addition, the server provides support for a DES-based authorization scheme, XDM-AUTHORIZATION-1, which is more secure (given a secure key distribution mechanism), but as DES is not generally distributable, the implementation is missing routines to encrypt and decrypt the authorization data. This authorization scheme can be used in conjunction with XDMCP's authentication scheme, XDM-AUTHENTICATION-1 or in isolation. .PP The authorization data is passed to the server in a private file named with the \fB-auth\fP command line option. Each time the server is about to accept the first connection after a reset (or when the server is starting), it reads this file. If this file contains any authorization records, the local host is not automatically allowed access to the server, and only clients which send one of the authorization records contained in the file in the connection setup information will be allowed access. See the \fIXau\fP manual page for a description of the binary format of this file. Maintenance of this file, and distribution of its contents to remote sites for use there is left as an exercise for the reader. .PP The sample server also uses a host-based access control list for deciding whether or not to accept connections from clients on a particular machine. This list initially consists of the host on which the server is running as well as any machines listed in the file \fI/etc/X\fBn\fI.hosts\fR, where \fBn\fP is the display number of the server. Each line of the file should contain an Internet hostname (e.g. expo.lcs.mit.edu.) There should be no leading or trailing spaces on any lines. For example: .sp .in +8 .nf joesworkstation corporate.company.com .fi .in -8 .PP Users can add or remove hosts from this list and enable or disable access control using the \fIxhost\fP command from the same machine as the server. For example: .sp .in +8 .nf % xhost +janesworkstation janesworkstation being added to access control list % xhost + all hosts being allowed (access control disabled) % xhost - all hosts being restricted (access control enabled) % xhost access control enabled (only the following hosts are allowed) joesworkstation janesworkstation corporate.company.com .fi .SH "SIGNALS" The X server attaches special meaning to the following signals: .TP 8 .I SIGHUP This signal causes the server to close all existing connections, free all resources, and restore all defaults. It is sent by the display manager (\fIxdm\fP or \fIdtlogin\fP) whenever the main user's main application exits to force the server to clean up and prepare for the next user. .TP 8 .I SIGTERM This signal causes the server to exit cleanly. .TP 8 .I SIGUSR1 This signal is used quite differently from either of the above. When the server starts, it checks to see if it has inherited SIGUSR1 as SIG_IGN instead of the usual SIG_DFL. In this case, the server sends a SIGUSR1 to its parent process after it has set up the various connection schemes. \fIXdm\fP uses this feature to recognize when connecting to the server is possible. .SH "FONTS" Fonts are usually stored as individual files in directories. The list of directories in which the server looks when trying to open a font is controlled by the \fIfont path\fP. Although most sites will choose to have the server start up with the appropriate font path (using the \fI-fp\fP option mentioned above), it can be overridden using the \fIxset\fP program. .PP Font databases are created by running the \fImkfontdir\fP or \fIstmkdirs\fP program in the directory containing the compiled versions of the fonts (\fImkfontdir\fP) or font outlines (\fIstmkdirs\fP.) Whenever fonts are added to a directory, \fImkfontdir\fP or \fIstmkdirs\fP should be rerun so that the server can find the new fonts. \fBIf \fImkfontdir\fP or \fIstmkdirs\fP is not run, the server will not be able to find any of the new fonts in the directory.\fR .PP In addition, the X server supports font servers. A font server is a networked program that supplies fonts to X servers and other capable programs. In order to communicate with a font server, the font servers address must be supplied as part of the X server's font path. A font server's address is specified as .nf .in +8 \fItransport\fP/\fIhostname\fP:\fIport-number\fP .in -8 .fi where \fItransport\fP is always \fItcp\fP, \fIhostname\fP is the hostname of the machine being connected to (no hostname means a local connection) and \fIport-number\fP is the tcp address that the font server is listening at (typically 7000.) .SH DIAGNOSTICS Too numerous to list them all. If run from \fIinit(1M)\fP, errors are logged in the file \fI/usr/adm/X*msgs\fP, .SH FILES .TP 30 /etc/inittab Script for the init process .TP 30 /etc/gettydefs Speed and terminal settings used by getty .TP 30 /etc/X*.hosts Initial access control list .TP 30 /usr/lib/X11/fonts Top level font directory .TP 30 /usr/lib/X11/rgb.txt Color database .TP 30 /usr/lib/X11/rgb.pag Color database .TP 30 /usr/lib/X11/rgb.dir Color database .TP 30 /usr/spool/sockets/X11/* IPC mechanism socket .TP 30 /usr/adm/X*msgs Error log file .TP 30 /usr/lib/X11/X*devices Input devices used by the server. This file contains many example configurations. .TP 30 /usr/lib/X11/X*screens Screens used by the server. This file contains many example configurations. .TP 30 /usr/lib/X11/X*pointerkeys Keyboard pointer device file. This file contains many example configurations. .TP 30 /usr/lib/X11/XHPkeymaps Key device database used by the X server. .SH NOTES The option syntax is inconsistent with itself and \fIxset(1)\fP. .PP The acceleration option should take a numerator and a denominator like the protocol. .PP The color database is missing a large number of colors. However, there doesn't seem to be a better one available that can generate RGB values. .SH COPYRIGHT Copyright 1984, 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1992 Massachusetts Institute of Technology. .br Copyright 1992 Hewlett Packard Company. .br See \fIX(1)\fP for a full statement of rights and permissions. .SH ORIGIN MIT Distribution .SH "SEE ALSO" .PP dtlogin(1) bdftopcf(1) fs(1), getty(1M), gettydefs(4), gwindstop(1), hpterm(1), init(1M), inittab(4), mkfontdir(1), rgb(1), stmkdirs(1), x11start(1), xclock(1), xfd(1), xhost(1), xinit(1), xinitcolormap(1), xload(1), xmodmap(1), xrefresh(1), xseethru(1), xset(1), xsetroot(1), xterm(1), xwcreate(1), xwd(1), xwdestroy(1), xwininfo(1), xwud(1), .\" $Header: adb.1,v 78.1 96/02/12 13:28:49 ssa Exp $ .TA a .TH adb 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME adb \- absolute debugger .SH SYNOPSIS .CR adb .RC \|[ -w ]\| .RC \|[ -I\c .IR dir ]\| .RC \|[ -k ]\| .RC \|[ -m ]\| .RC \|[ -P\c .IR pid ]\| .RI \| objfil \| .RI \|[ corfil ]\| .SH DESCRIPTION The .CR adb command executes a general-purpose debugging program that is sensitive to the underlying architecture of the processor on which it runs. It can be used to examine files and provide a controlled environment for executing .SM HP-UX programs. .PP .I objfil is normally an executable program file, preferably containing a symbol table; if not, the symbolic features of .CR adb cannot be used, although the file can still be examined. The default for .I objfil is .CR a.out . .PP .I corfil is assumed to be a core image file produced after executing .IR objfil . The default for .I corfil is .CR core . .PP Requests to .CR adb are read from standard input and .CR adb responds on standard output. If the .CR -w flag is present, .I objfil is created (if necessary) and opened for reading and writing, to be modified using .CR adb . The .CR -I option specifies a directory where files read with .CR $< or .CR $<< (see below) are sought; the default is .CR /usr/lib/adb . .CR adb ignores .SM QUIT; .SM INTERRUPT causes return to the next .CR adb command. .PP The following options are also supported: .TP 10 .CR -k Allows virtual-to-physical address translation, useful for kernel debugging. In this case, .I corfil should be an .SM HP-UX crash dump or .CR /dev/mem . .IP When .CR adb is invoked with this option, it sets up the context of the currently running process using space registers four through seven. A user specified address is dereferenced by combining it with the appropriate space register, depending on the quadrant in which the 32-bit address lies. .IP When the current radix is not (decimal) ten, the .CR -k option allows .CR adb to support the notion of long pointers or addresses in the form .IC space . offset\f1. Once a space is specified, all subsequent addresses are dereferenced using that space until the user enters another long address. If a space equal to (hexadecimal) 0xffffffff is used, .CR adb reverts to the previous context and uses space registers four through seven to dereference 32-bit addresses. .TP .C -m Must be specified instead of .C -k when a core dump is written to multiple files by .CR savecore . .IP When .CR -m is used, .I corfil must be specified as the path name of the directory that contains system core dump files. For example, .CR savecore normally saves system core dump files in a directory named .CI /var/adm/crash/core. n\f1. (The trailing .I n in the path name is a number that increases by one every time .C savecore is run with the same .I dirname\f1. See .CR savecore (1M) for more information.) .IP Therefore, a command line using .CR -m might look similar to the following: .IP .C adb -m /var/adm/crash/core.1/vmunix /var/adm/crash/core.1 .IP Notice that when .C -m is specified on the command line, .C -k is not necessary. .TP .CI -P pid Causes .CR adb to adopt process .IR pid as a "traced" process (see .IR ptrace (2)). This option is helpful for debugging processes that were not originally run under the control of .CR adb . .PP Requests to .CR adb follow the form: .IP .RI \|[ address ]\| .RC \|[ , .IR count ]\| .RI \|[ command ]\| .RC \|[ ; ]\| .PP If .I address is present, .I dot is set to .IR address . Initially .I dot is set to .CR 0 . For most commands, .I count specifies the number of times the command is to be executed. The default .I count is .CR 1 . .I address and .I count are expressions. .PP The interpretation of an address depends on the context in which it is used. If a subprocess is being debugged, addresses are interpreted in the address space of the subprocess. (For further details of address mapping see Addresses below.) .PP .ne 7 .SS Expressions Expressions are interpreted as follows: .RS .TP 12 .CR . The value of .IR dot . .TP .CR + The value of .I dot increased by the current increment. .TP .CR ^ The value of .I dot decreased by the current decrement. .TP \f3"\f1 The last .I address typed. .TP .I integer A number. The prefix .CR 0 (zero) forces interpretation in octal radix; the prefixes .CR 0d and .CR 0D force interpretation in decimal radix; the prefixes .CR 0x and .CR 0X force interpretation in hexadecimal radix. Thus .CR 020 = .CR 0d16 = .CR 0x10 = sixteen. If no prefix appears, the .I default radix is used; see the .CR $d command. The radix is initialized to the base used in the assembly language for the processor involved. Note that a hexadecimal number whose most significant digit would otherwise be an alphabetic character must have a .CR 0x (or .CR 0X ) prefix. .TP .IC integer . fraction A 32-bit floating-point number. .TP .CI ' cccc ' The .SM ASCII value of up to 4 characters. A backslash .RC ( \e ) can be used to escape a single quote .RC ( ' ). .TP .CI < " name" .I name can have the value of either a variable or a register. .CR adb maintains a number of variables named by single letters or digits; see Variables below. If .I name is a register, the value of the register is obtained from the .SM CORE_PROC segment in .IR corfil (before the subprocess is initiated) or from the user area of the subprocess. Register names are implementation dependent; see the .CR $r command. .TP .I symbol A .I symbol is a sequence of uppercase or lowercase letters, underscores, or digits, not starting with a digit. A backslash .RC ( \e ) can be used to escape other characters. The value of the .I symbol is taken from the symbol table in .IR objfil . An initial underscore .RC ( _ ) is prefixed to .IR symbol , if needed. .TP .CI _ \0symbol If the compiler prefixes .CR _ to an external symbol, it may be necessary to cite this name to distinguish it from a symbol generated in assembly language. .TP .RI ( exp ) The value of the expression .IR exp . .RE .PP The following are monadic operators: .RS .TP 12 .CI * exp The contents of the location addressed by .I exp in .IR corfil . .TP \f3@ \f2exp\f1 The contents of the location addressed by .I exp in .IR objfil . .TP .CI - exp Integer negation. .TP .CI ~ exp Bitwise complement. .RE .PP The following dyadic operators are left associative and are less binding than monadic operators: .RS .TP 12 .IC e1 + e2 Integer addition. .TP .IC e1 - e2 Integer subtraction. .TP .IC e1 * e2 Integer multiplication. .TP .IC e1 % e2 Integer division. .TP .IC e1 & e2 Bitwise conjunction. .TP .IC e1 | e2 Bitwise disjunction. .TP .IC e1 # e2 .I e1 rounded up to the next multiple of .IR e2 . .RE .SS Commands Most commands consist of an action character followed by a modifier or list of modifiers. The following action characters can take format specifiers. (The action characters .CR ? and .CR / can be followed by .CR * ; see Addresses for further details.) .RS .TP 12 .CI ? f Locations starting at .I address in .I objfil are printed according to the format .IR f . .I dot is incremented by the sum of the increments for each format letter. If a subprocess has been initiated, .I address references a location in the address space of the subprocess instead of .IR objfil . .TP .CI / f Locations starting at .I address in .I corfil are printed according to the format .I f and .I dot is increased like .CR ? . If a subprocess has been initiated, .I address refers to a location in the address space of the subprocess instead of .IR corfil . .TP .CI = f The value of .I address is printed in the styles indicated by the format .IR f . (For .CR i format .CR ? is printed for the parts of the instruction that refer to subsequent words.) .RE .PP A .I format consists of one or more characters that specify a style of printing. Each format character can be preceded by an integer that indicates how many times the format is repeated. While stepping through a format, .I dot is increased by the amount given for each format character. If no format is given then the last format is used. .PP The following format characters are available: .RS .TP 12 .CR o \02 Print 2 bytes in octal. All octal numbers output by .CR adb are preceded by .CR 0 . .TP .CR O \04 Print 4 bytes in octal. .TP .CR q \02 Print 2 bytes in signed octal. .TP .CR Q \04 Print 4 bytes in signed octal. .TP .CR d \02 Print 2 bytes in decimal. .TP .CR D \04 Print 4 bytes in decimal. .TP .CR x \02 Print 2 bytes in hexadecimal. .TP .CR X \04 Print 4 bytes in hexadecimal. .TP .CR u \02 Print 2 bytes as an unsigned decimal number. .TP .CR U \04 Print 4 bytes as an unsigned decimal number. .TP .CR f \04 Print the 32 bit value as a floating point number. .TP .CR F \08 Print double floating point. .TP .CR b \01 Print the addressed byte in hexadecimal. .TP .CR B \01 Print the addressed byte in octal. .TP .CR c \01 Print the addressed character (the sign bit is ignored). .TP .CR C \01 Print the addressed character using the following escape convention. First, the sign bit is discarded, then character values .CR 000 to .CR 040 are printed as \f3@\fP followed by the corresponding character in the range .CR 0100 to .CR 0140 . The character \f3@\fP is printed as \f3@@\fP. .TP .CI s \0n Print the addressed characters until a zero character is reached. .TP .CI S \0n Print a string using the \f3@\fP escape convention. The value .I n is the length of the string including its zero terminator. .TP .CR Y \04 Print 4 bytes in date format (see .IR ctime (3C)). .TP .CI i \0n Print as machine instructions. The value of .I n is the number of bytes occupied by the instruction. .TP .CR a \00 Print the value of .I dot in symbolic form. .TP .CI p \0n Print the addressed value in symbolic form. The value of .I n is a machine-dependent constant. .TP .CR t \00 When preceded by an integer, moves to the next appropriate tab stop. For example, .CR 8t moves to the next 8-space tab stop. .TP .CR r \00 Print a space. .TP .CR n \00 Print a new-line character. .TP \f3"\f1...\f3"\f1 0 Print the enclosed string. .TP .CR ^ .I dot is decreased by the current increment. Nothing is printed. .TP .CR + .I dot is increased by 1. Nothing is printed. .TP .CR - .I dot is decreased by 1. Nothing is printed. .TP new-line Repeat the previous command with a .I count of 1. The value of .I dot continues from the end of the previous format, unlike a .RC [ ?/ ] command with no .I address, which repeats the previous .I address value. New-line can also be used to repeat a .CR :s or .CR :c command; however, any arguments to the previous command are lost. .TP .RC [ ?/ ] l "\f2 value mask\fP" Words starting at .I dot are masked with .I mask and compared with .I value until a match is found. If .CR L is used, .CR adb looks to match 4 bytes at a time instead of 2. If no match is found, .I dot is left unchanged; otherwise .I dot is set to the matched location. If .I mask is omitted .CR -1 is used. .TP .RC [ ?/ ] w "\f2 value ...\f1" Write the 2-byte .I value into the addressed location. If the command is .CR W , write 4 bytes. Odd addresses are not allowed when writing to the subprocess address space. .TP .CR =m Toggle the address mapping of .IR corfil between the initial map set up for a valid core file and the default mapping pair which the user can modify with .CR /m . If the .IR corfil was invalid, only the default mapping is available. .TP .RC [ ?/ ] m " \f2b1 e1 f1\fP[" ?/\f1\s-1] Record new values for .RI ( b1 , .IR e1 , .IR f1 ). If fewer than three expressions are given, the remaining map parameters are left unchanged. If the .CR ? or .CR / is followed by .CR * , the second segment .RI ( b2 , .IR e2 , .IR f2 ) of the mapping is changed. If the list is terminated by .CR ? or .CR / , the file .RI ( objfil or .IR corfil , respectively) is used for subsequent requests. (For example, .CR /m? causes .CR / to refer to .IR objfil .) A .CR /m command switches the .IR corfil mapping to the default mapping pair. For a valid core file, the .CR =m command can be used to switch back to the initial mapping. .TP .CI > name Assign .I dot to the variable or register named. .TP .CR ! Call a shell to read the remainder of the line following .CR ! . .PP The following .CR $ commands take the form .CI $ modifier\f1: .RS .TP 12 .CI $< f Read commands from the file .IR f . If this command is executed in a file, further commands in the file are not seen. If a .I count is given, and is zero, the command is ignored. The value of the count is placed in variable 9 before the first command in .I f is executed. .TP .CI $<< f Similar to .CR $< except it can be used in a file of commands without causing the file to be closed. Variable 9 is saved when the command executes and is restored when it completes. Only five .CR $<< files can be open at once. .TP .CI $> f Send output to the file .IR f , which is created if it does not already exist. .TP .CR $r Print the general registers and the instruction addressed by the process counter. .I dot is set to the process counter contents. .TP .CR $f Print the floating-point registers. .TP .CR $b Print all breakpoints and their associated counts and commands. .TP .CR $c C stack backtrace. If .I address is given, it is taken as the address of the current frame (instead of the normal stack frame pointer). If .I count is given, only the first .I count frames are printed. .TP .CR $e The names and values of external variables are printed. .TP .CR $w Set the page width for output to .I address (default 80). .TP .CR $s Set the limit for symbol matches to .I address. The default is system dependent. .TP .CR $o The default for all integers input is octal. .TP .CR $d Set the default radix to .I address and report the new value. Note that .I address is interpreted in the (old) current radix. Thus .CR 10$d never changes the default radix. To make decimal the default radix, use .CR 0d10$d . .TP .CR $x The default for all integers input is hexadecimal. .TP .CR $q Exit from .CR adb . .TP .CR $v Print all non-zero variables in the current radix. .TP .CR $m Print the address map. This includes both the initial and default maps for a valid .IR corfil with an indication of which is currently active. .TP .CR $ new-line Print the process id and register values. .TP .CR $z Print a list of signals and how they are handled. See .CR :z for information on changing signal handling. .RE .PP The available .CR : commands manage subprocesses, and take the form .CI : modifier\f1: .RS .TP 12 .CI :b c Set breakpoint at .IR address . The breakpoint is executed .IR count \(mi1 times before causing a stop. Each time the breakpoint is encountered, the command .I c is executed. If this command sets .I dot to zero, the breakpoint causes a stop. .TP .CR :d Delete breakpoint at .IR address . .CR :d* deletes all breakpoints. .TP .CR :r Run .I objfil as a subprocess. If .I address is given explicitly, the program is entered at this point; otherwise the program is entered at its standard entry point. The value .I count specifies how many breakpoints are ignored before stopping. Arguments to the subprocess may be supplied on the same line as the command. An argument starting with .CR < or .CR > causes the standard input or output to be established for the command. All signals are turned on when entering the subprocess. .TP .CR :e Set up a subprocess as in .CR :r ; no instructions are executed. .TP .CI :c s Continue the subprocess with signal .I s (see .IR signal (5)). If .I address is given, the subprocess continues at this address. If no signal is specified, the signal that caused the subprocess to stop is sent. Breakpoint skipping is the same as for .CR :r . .TP .CI :s s As for .CR c except that the subprocess is single stepped .I count times. If there is no current subprocess, .I objfil is run as a subprocess as for .CR :r . In this case no signal can be sent; the remainder of the line is treated as arguments to the subprocess. .TP .CI :S s Same as .CR :c except that a temporary breakpoint is set at the next instruction. Useful for stepping across subroutines. .TP .CR :x \0\f2a\fP\0[\f2b\f1]... Execute subroutine .I a with parameters .RI [ b ]... .TP .CR :k Terminate the current subprocess, if any. .TP .CI :z d Change signal handling for a specified signal. Disposition .I d can be specified as: .RS 12 .TP 5 .CR +s Stop process when signal is received. .TP .CR -s Do not stop process when signal is received. .TP .CR +r Report when signal is received. .TP .CR -r Do not report when signal is received. .TP .CR +d Deliver signal to the target process. .TP .CR -d Do not deliver signal to the target process. .RE .IP For example, .CR 0x10:z+d enables delivering of signal number .CR 0x10 to the target process. Use .CR $z to display existing settings. .RE .SS Variables .CR adb provides named and numbered variables. Named variables are set initially by .CR adb but are not used subsequently. Numbered variables are reserved for communication as follows: .RS .TP 12 .CR 0 The last value printed. .TP .CR 1 The last offset part of an instruction source. .TP .CR 2 The previous value of variable 1. .TP .CR 9 The count on the last .CR $< command. .RE .PP On entry, the following named variables are set from the coreheaders in the .IR corfil . If .I corfil does not appear to be a .CR core file, these values are set from .IR objfil . .RS .TP 12 .CR b The base address of the data segment. .TP .CR d The data segment size. .TP .CR s The stack segment size. .TP .CR t The text segment size. .RE .PP The following variables are set from .IR objfil . .RS .TP 12 .CR e The entry point. .TP .CR m The "magic" number as defined in .CR . .RE .SS Addresses The file address associated with a written address is determined by a mapping described below; see .CR $m . Both the .IR objfil mapping and the default .IR corfil mapping are represented by two triples .RI ( "b1, e1, f1" ) and .RI ( "b2, e2, f2" ). The initial mapping for a valid .IR corfil contains a triple for each segment (coreheader). .PP The .I file address corresponding to a written .I address is calculated as follows: .PP If .IP .IR "b1 \(<= address < e1, file address = address + f1\(mib1" , .PP otherwise, if .IP .IR "b2 \(<= address < e2, file address = address + f2\(mib2" , .PP otherwise, the requested .I address is not valid. For a valid .IR corfil , this pattern repeats as many times as there are segments (coreheaders) in the .IR corfil , rather than twice. If .CR ? or .CR / is followed by .CR * , only the second triple is used, or (when using the initial mapping of a valid .IR corfil ) only segments with a .CR CORE_STACK coreheader. .PP The initial setting of both mappings is suitable for normal .CR a.out and .CR core files. If either file is not of the kind expected, .CR adb sets .I b1 to .CR 0 , .I e1 to the maximum file size, and .I f1 to .CR 0 ; in this way the entire file can be examined with no address translation. .PP .CR adb keeps all appropriate values as signed 32-bit integers so that it can be used on large files. .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .CR adb comments about inaccessible files, syntax errors, abnormal termination of commands, etc. It echoes .CR adb when there is no current command or format. Exit status is .CR 0 , unless the last command failed or returned non-zero status. .ne 20 .SH DEPENDENCIES .TP 3 \(bu Setting breakpoints in shared libraries is not supported. .IP .CR adb does not read the linker symbol table for shared libraries, and cannot access locations in shared libraries by name. In a stack backtrace .RC ( $c ), .CR adb does not know the names of shared library procedures. .IP If the core file was created when the program was in a shared library function, the .CR $c command does not work. When a stack backtrace for the core file encounters a shared library procedure on the stack it aborts at that point. .TP \(bu A leading zero by itself is not recognized as a radix indicator. Use the prefixes .CR 0o or .CR 0O (zero-oh) to force interpretation in octal radix. The prefixes .CR 0t and .CR 0T are also accepted to force interpretation in decimal radix. Thus .CR 0o20 = .CR 0t16 = sixteen. A hexadecimal number whose most significant digit would otherwise be an alphabetic character may begin with a leading zero instead of .CR 0x (or .CR 0X ), if the default radix is hexadecimal. .TP \(bu The .CR $f command prints floating point registers as 32-bit single precision and .CR $F prints these registers as 64-bit doubles. .TP \(bu .CR $R prints all registers available to .CR adb users. .TP \(bu The .CR :x and .CR :S commands are not currently supported. .TP \(bu .CR adb can be used to inspect relocatable object files; it reads the symbol table and sets up the appropriate mappings for text and data. Note that relocatable object files do not necessarily contain an exact image of the initialized data; however, if this is the case, the data mapping is not set. .SH AUTHOR .CR adb was developed by AT&T and HP. .SH FILES .nf .CR a.out .CR core .CR /dev/mem .CR /dev/kmem .CR /dev/swap .fi .SH SEE ALSO ptrace(2), crt0(3), ctime(3C), end(3C), a.out(4), core(4), savecore(1M), savecore(4), \%signal(5). .PP .I ADB Tutorial .\" index@\f4adb\f1 \- absolute debugger@@@\f3adb(1)\f1 .\" index@absolute debugger@@@\f3adb(1)\f1 .\" index@assembler debugger@@@\f3adb(1)\f1 .\" index@debugger: absolute debugger@@@\f3adb(1)\f1 .\" index@debugger: object code debugger@@@\f3adb(1)\f1 .\" index@debugger: assembler debugger@@@\f3adb(1)\f1 .\" index@object code debugger@@@\f3adb(1)\f1 .\" .\" toc@\f3adb(1)\f1:\0\0\f4adb\f1@@@absolute debugger .\" .\" $Header: adjust.1,v 72.4 94/07/03 11:40:46 ssa Exp $ .TA a .TH adjust 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME adjust \- simple text formatter .SH SYNOPSIS .C adjust .RC [ -b ] .RC [ -c | -j | -r\|] .RC [ -m .IR column\| ] .RC [ -t .IR tabsize\| ] .RI [ \|files \0...\|] .SH DESCRIPTION The .CR adjust command is a simple text formatter for filling, centering, left and right justifying, or only right justifying text paragraphs, and is designed for interactive use. It reads the concatenation of input files (or standard input if none are given) and produces on standard output a formatted version of its input, with each paragraph formatted separately. If .CR - is given as an input filename, .CR adjust reads standard input at that point (use .CR -\|- as an argument to separate .CR - from options.) .PP .CR adjust reads text from input lines as a series of words separated by space characters, tabs, or newlines. Text lines are grouped into paragraphs separated by blank lines. By default, text is copied directly to the output, subject only to simple filling (see below) with a right margin of 72, and leading spaces are converted to tabs where possible. .SS Options The .CR adjust command recognizes the following command-line options: .RS .TP 10 .C -b Do not convert leading space characters to tabs on output; (output contains no tabs, even if there were tabs in input). .TP .C -c Center text on each line. Lines are pre- and post-processed, but no filling is performed. .TP .C -j Justify text. After filling, insert spaces in each line as needed to right justify it (except in the last line of each paragraph) while keeping the justified left margin. .TP .C -r After filling text, adjust the indentation of each line for a smooth right margin (ragged left margin). .TP .CI -m column Set the right fill margin to the given column number, instead of 72. Text is filled, and optionally right justified, so that no output line extends beyond this column (if possible). If .CR -m0 is given, the current right margin of the first line of each paragraph is used for that and all subsequent lines in the paragraph. .IP By default, text is centered on column 40. With .CR -c , the .CR -m option sets the middle column of the centering ``window'', but .CR -m0 auto-sets the right side as before (which then determines the center of the ``window''). .TP .CI -t tabsize Set the tab size to other than the default (eight columns). .RE .PP Only one of the .CR -c , .CR -j , and .CR -r options is allowed in a single command line. .SS Details Before doing anything else to a line of input text, .CR adjust first handles backspaces, rubbing out preceding characters in the usual way. Next, it ignores all non-printable characters except tab. It then expands all tabs to spaces. .PP For simple text filling, the first word of the first line of each paragraph is indented the same amount as in the input line. Each word is then carried to the output followed by one space. ``Words'' ending in .IR terminal_character [ quote ][ closing_character ] are followed by two spaces, where .I terminal_character is any of .CR . , .CR : , .CR ? , or .CR ! ; .I quote is a single closing quote .RC ( \|'\| ) character or double-quote character ( \|\f3"\f1\| ), and .I close is any of .CR ) , .CR ] , or .CR } . Here are some examples: .IP end. of? sentence.' sorts!" of.) words?"] .RE .PP .RC ( adjust does not place two spaces after a pair of single closing quotes .RC ( \|''\| ) following a .IR terminal_character ). .PP .CR adjust starts a new output line whenever adding a word (other than the first one) to the current line would exceed the right margin. .PP .CR \h'1i'adjust understands indented first lines of paragraphs (such as this one) when filling. The second and subsequent lines of each paragraph are indented the same amount as the second line of the input paragraph if there is a second line, else the same as the first line. .TP 10 .C * .CR adjust also has a rudimentary understanding of tagged paragraphs (such as this one) when filling. If the second line of a paragraph is indented more than the first, and the first line has a word beginning at the same indentation as the second line, the input column position of the tag word or words (prior to the one matching the second line indentation) is preserved. .PP Tag words are passed through without change of column position, even if they extend beyond the right margin. The rest of the line is filled or right justified from the position of the first non-tag word. .PP When .CR -j is given, .CR adjust uses an intelligent algorithm to insert spaces in output lines where they are most needed, until the lines extend to the right margin. First, all one space word separators are examined. One space is added to each separator, starting with the one having the most letters between it and the preceding and following separators, until the modified line reaches the right margin. If all one space separators are increased to two spaces and more spaces must be inserted, the algorithm is repeated with two space separators, and so on. .PP Output line indentation is held to one less than the right margin. If a single word is larger than the line size (right margin minus indentation), that word appears on a line by itself, properly indented, and extends beyond the right margin. However, if .CR -r is used, such words are still right justified, if possible. .PP If the current locale defines class names .CR ekinsoku and .CR bkinsoku (see .IR iswctype (3C)), .CR adjust formats the text in accordance with the .CR ekinsoku / bkinsoku character classification and margin settings (see .CR -r , .CR -j , and .CR -m options). .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG provides a default value for the internationalization variables that are unset or null. If .CR LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .CR adjust will behave as if all internationalization variables are set to "C". See .IR environ (5). .PP .CR LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .PP .CR LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .CR LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .CR NLSPATH determines the location of message catalogs for the processing of .CR LC_MESSAGES . .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS .CR adjust complains to standard error and later returns a nonzero value if any input file cannot be opened (it skips the file). It does the same (but quits immediately) if the argument to .CR -m or .CR -t is out of range, or if the program is improperly invoked. .PP Input lines longer than .CR BUFSIZ are silently split (before tab expansion) or truncated (afterwards). Lines that are too wide to center begin in column 1 (no leading spaces). .SH EXAMPLES This command is useful for filtering text while in .IR vi (1). For example, .IP .C !}adjust .PP reformats the rest of the current paragraph (from the current line down), evening the lines. .PP The .CR vi command: .IP .C ":map ^X {!}adjust -j^V^M" .PP (where .CR ^ denotes control characters) sets up a useful ``finger macro''. Typing .CR ^X (Ctrl-X) reformats the entire current paragraph. .PP .C adjust -m1 is a simple way to break text into separate words without white space, except for tagged-paragraph tags. .SH WARNINGS This program is designed to be simple and fast. It does not recognize backslash to escape white space or other characters. It does not recognize tagged paragraphs where the tag is on a line by itself. It knows that lines end in newline or null, and how to deal with tabs and backspaces, but it does not do anything special with other characters such as form feed (they are simply ignored). For complex operations, standard text processors are likely to be more appropriate. .PP This program could be implemented instead as a set of independent programs, fill, center, and justify (with the .CR -r option). However, this would be much less efficient in actual use, especially given the program's special knowledge of tagged paragraphs and last lines of paragraphs. .\" .PP .\" These options were considered but not added, because the creeping featurism .\" had to stop somewhere, before this program became another .\" .IR nroff (1): .\" .RS .\" .TP 8 .\" .C -h .\" Hyphenate. .\" Allows the program to break and join words at existing hyphens (only). .\" Words are broken across lines, at single hyphens surrounded by non-whitespace .\" characters. .\" Likewise, a word ending in a single hyphen, followed by whitespace, followed .\" by a non-hyphen character, is joined to the next word without whitespace if .\" needed. .\" .TP .\" .C -n .\" Nofill. .\" Only allowed with .\" .C -j .\" or .\" .CR -r , .\" it inhibits filling, i.e. words are not moved from one line to another. .\" Thus existing text can be left/right or right justified without being .\" otherwise modified. .\" (Note that .\" .C -n .\" is always in effect for .\" .CR -c , .\" centering.) .\" .RE .SH AUTHOR .CR adjust was developed by HP. .SH SEE ALSO nroff(1). .\" .\" index@\f4adjust\f1 \- simple text formatter@@@\f3adjust(1)\f1 .\" index@\f1formatters, text @@@\f3adjust(1)\f1 .\" index@\f1text formatters@@@see \f2adjust\f1 .\" .\" toc@\f3adjust(1)\f1:\0\0\f4adjust\f1@@@simple text formatter\f1 .\" $Header: admin.1,v 76.1 95/07/07 15:07:40 ssa Exp $ .TA a .TH admin 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME admin \- create and administer SCCS files .SH SYNOPSIS .C admin .CR -i [ \f2name\f1] .RC [ -n ] .RC [ -a .IR login "] ...\&" .RC [ -d .IR flag\c .RI [ flag-val "]\|] ...\&" .ifn .br .ifn \0\0\0\0 .RC [ -f .IR flag\c .RI [ flag-val "]\|] ...\&" .ift .br .ift \0\0\0\0 .RC [ -m .IR mrlist "] ...\&" .RC [ -r .IR rel ] .RC [ -t\c .RI [ name ]\|] .ifn .br .ifn \0\0\0\0 .RC [ -y\c .RI [ comment ]\|] .IR file " ...\&" .PP .C admin -n .RC [ -a .IR login "] ...\&" .RC [ -d .IR flag\c .RI [ flag-val "]\|] ...\&" .ifn .br .ifn \0\0\0\0 .RC [ -f .IR flag\c .RI [ flag-val "]\|] ...\&" .RC [ -m .IR mrlist "] ...\&" .ift .br .ift \0\0\0\0 .RC [ -t\c .RI [ name ]\|] .ifn .br .ifn \0\0\0\0 .RC [ -y\c .RI [ comment ]\|] .IR file " ...\&" .PP .C admin .RC [ -a .IR login "] ...\&" .RC [ -e .IR login "] ...\&" .RC [ -d .IR flag\c .RI [ flag-val "]\|] ...\&" .ifn .br .ifn \0\0\0\0 .RC [ -m .IR mrlist "] ...\&" .ift .br .ift \0\0\0\0 .RC [ -r .IR rel ] .RC [ -t\c .RI [ name ]\|] .IR file " ...\&" .PP .C admin -h .IR file " ...\&" .PP .C admin -z .IR file " ...\&" .SH DESCRIPTION The .CR admin command is used to create new SCCS files and change the parameters of existing ones. Arguments to .CR admin , which may appear in any order, ( unless .CR -- is specified as an argument, in which case all arguments after .CR -- are treated as files ) consist of option arguments, beginning with .CR - , and named .IR file s (note that SCCS file names must begin with the characters .CR s. ). If a named .I file does not exist, it is created and its parameters are initialized according to the specified option arguments. Parameters not initialized by an option argument are assigned a default value. If a named .I file does exist, parameters corresponding to specified option arguments are changed, and other parameters are left unaltered. .PP If .I directory is named instead of .IR file , .CR admin acts on each .I file in .IR directory , except that non-SCCS files (the last component of the path name does not begin with .CR s. ) and unreadable files are silently ignored. If a name of .CR - is given, the standard input is read, and each line of the standard input is assumed to be the name of an SCCS file to be processed. Again, non-SCCS files and unreadable files are silently ignored. .PP The .CR admin option arguments apply independently to all named .IR file s, whether one file or many. In the following discussion, each option is explained as if only one file is specified, although they affect single or multiple files identically. .SS Options The .CR admin command supports the following options and command-line arguments: .RS .TP 15 .C -n This option indicates that a new SCCS file is to be created. .TP .CR -i [\f2name\f1] The .I name of a file from which the text for a new SCCS file is to be taken. The text constitutes the first delta of the file (see the .CR -r option for the delta numbering scheme). If the .CR -i option is used but the file name is omitted, the text is obtained by reading the standard input until an end-of-file is encountered. If this option is omitted, the SCCS file is created with an empty initial delta. Only one SCCS file can be created by an .CR admin command on which the .CR -i option is supplied. Using a single .CR admin to create two or more SCCS files requires that they be created empty (no .CR -i option). Note that the .CR -i option implies the .CR -n option. .TP .CI -r \0rel The release .RI ( rel ) into which the initial delta is inserted. This option can be used only if the .CR -i option is also used. If the .CR -r option is not used, the initial delta is inserted into release 1. The level of the initial delta is always 1 (by default initial deltas are named 1.1). .TP .CR -t [\f2name\f1] The .I name of a file from which descriptive text for the SCCS file is to be taken. If the .CR -t option is used and .CR admin is creating a new SCCS file (the .CR -n and/or .CR -i options are also used), the descriptive text file name must also be supplied. In the case of existing SCCS files: .RS .RS .TP 3 \(bu A .CR -t option without a file name causes removal of descriptive text (if any) currently in the SCCS file. .TP \(bu A .CR -t option with a file name causes text (if any) in the named file to replace the descriptive text (if any) currently in the SCCS file. .RE .RE .ift .bp .TP .CI -f \0flag This option specifies a .IR flag , and possibly a value for the .IR flag , to be placed in the SCCS file. Several .CR -f options can be supplied on a single .CR admin command line. The allowable .IR flag s and their values are: .RS .RS .TP 10 .C b Allows use of the .CR -b option on a .CR get command (see .IR get (1)) to create branch deltas. .TP .CI c ceil The highest release (i.e., "ceiling"), a number less than or equal to 9999, which can be retrieved by a .CR get command for editing. The default value for an unspecified .CR c flag is 9999. .TP .CI f floor The lowest release (i.e., "floor"), a number greater than 0 but less than 9999, which may be retrieved by a .CR get command for editing. The default value for an unspecified .CR f flag is 1. .TP .CI d SID The default delta number .I SID to be used by a .CR get command (see .IR get (1)). .TP .CI i str Causes the message: .RS .IP .C No id keywords (cm7) .RE .IP issued by .CR get or .CR delta to be treated as a fatal error (see .IR delta (1)). In the absence of this flag, the message is only a warning. The message is issued if no SCCS identification keywords (see .IR get (1)) are found in the text retrieved or stored in the SCCS file. If a value is supplied, the keywords must exactly match the given string. However, the string must contain a keyword, but must not contain embedded newlines. .TP .C j Allows concurrent .CR get commands for editing on the same .I SID of an SCCS file. This allows multiple concurrent updates to the same version of the SCCS file. .IP Only one user can perform concurrent edits. Access by multiple users is usually accomplished by using a common login or a set user ID program (see .IR chmod (1) and .IR exec (2)). .TP .CI l list A .I list of releases to which deltas can no longer be made. (A .CR "get -e" against one of these locked releases fails). The .I list has the following syntax: .RS .IP .IC list\0 ::= \0range .CI | \0list\0 , \0range .br .IC range\0 ::= .I RELEASE NUMBER .C | a .RE .IP The character .CR a in the .I list is equivalent to specifying .I "all releases" for the named SCCS file. Omitting any list is equivalent to .CR a . .TP .C n Causes .CR delta to create a null delta in each of those releases being skipped (if any) when a delta is made in a .I new release (such as when making delta 5.1 after delta 2.7, release 3 and release 4 are skipped). These null deltas serve as .I "anchor points" so that branch deltas can be created from them later. The absence of this flag causes skipped releases to be nonexistent in the SCCS file, preventing branch deltas from being created from them in the future. .TP .CI q text User-definable text substituted for all occurrences of the .CR %\&Q% keyword in SCCS file text retrieved by .CR get . .TP .CI m mod The .I module name of the SCCS file substituted for all occurrences of the .CR %\&M% keyword in SCCS file text retrieved by .CR get . If the .CR m flag is not specified, the value assigned is the name of the SCCS file with the leading .CR s.\& removed. .TP .CI t type The .I type of module in the SCCS file substituted for all occurrences of .CR %\&Y% keyword in SCCS file text retrieved by .CR get . .ift .bp .TP .CR v [\f2pgm\fP] Causes .CR delta to prompt for Modification Request .RI ( MR ) numbers as the reason for creating a delta. The optional value specifies the name of a .RI ( MR ) number validity checking program (see .IR delta (1)). (If this flag is set when creating an SCCS file, the .CR m option must also be used even if its value is null). .RE .RE .TP 15 .CI -d \0flag Causes removal (deletion) of the specified .I flag from an SCCS file. The .CR -d option can be specified only when processing existing SCCS files. Several .CR -d options can be supplied on a single .CR admin command line. See the .CR -f option for allowable .I flag names. .RS .RS .TP 10 .CI l list A .I list of releases to be unlocked. See the .CR -f option for a description of the .CR l flag and the syntax of a .IR list . .RE .RE .TP 15 .CI -a \0login A .I login name, or numerical HP-UX group ID, to be added to the list of users allowed to make deltas (changes) to the SCCS file. A group ID is equivalent to specifying all .I login names common to that group ID. Several .CR a options can be used on a single .CR admin command line. As many .IR login s or numerical group IDs as desired can be on the list simultaneously. If the list of users is empty, anyone can add deltas. A .I login or group ID preceded by a .CR ! denies permission to make deltas. .TP .CI -e \0login A .I login name or numerical group ID to be erased from the list of users allowed to make deltas (changes) to the SCCS file. Specifying a group ID is equivalent to specifying all .I login names common to that group ID. Several .CR e options can be used on a single .CR admin command line. .TP .CR -y [\f2comment\f1] The .I comment text is inserted into the SCCS file as a comment for the initial delta in a manner identical to that of .IR delta (1). Omission of the .CR -y option results in a default comment line being inserted in the form: .IP .CR " date and time created" .IC YY \|/\| MM \|/\| DD \|/\|\c .IC HH \|/\| MM \|/\| SS .CI by " login" .IP The .CR -y option is valid only if the .CR -i and/or .CR -n options are specified (i.e., a new SCCS file is being created). .TP .CI -m \0mrlist The list of Modification Request .RI ( MR ) numbers is inserted into the SCCS file as the reason for creating the initial delta, in a manner identical to .IR delta (1). The .CR v flag must be set and the .RI ( MR ) numbers are validated if the .CR v flag has a value (the name of an .RI ( MR ) number validation program). Diagnostic messages occur if the .CR v flag is not set or .RI ( MR ) validation fails. .TP .C -h Causes .CR admin to check the structure of the SCCS file (see .IR sccsfile (4)), and to compare a newly computed checksum (the sum of all of the characters in the SCCS file except those in the first line) with the checksum that is stored in the first line of the SCCS file. Appropriate error diagnostics are produced. .IP This option inhibits writing on the file, thus canceling the effect of any other options supplied, and therefore is only meaningful when processing existing files. .TP .C -z The SCCS file checksum is recomputed and stored in the first line of the SCCS file (see .CR -h , above). .IP Note that use of this option on a truly corrupted file can prevent future detection of the corruption. .SS "Access Control Lists (ACLs)" Do not add optional ACL entries to SCCS files. SCCS removes them, possibly causing unexpected and undesirable access modes. .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_CTYPE determines the interpretation of text as single- and/or multi-byte characters. .PP .CR LC_MESSAGES determines the language in which messages are displayed. .PP If .CR LC_CTYPE or .CR LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of .CR C (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR admin behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH DIAGNOSTICS Use .IR sccshelp (1) for explanations. .SH WARNINGS SCCS files can be any length, but the number of lines in the text file itself cannot exceed 99\|999 lines. .SH FILES The last component of all SCCS file names must be of the form .CI s. filename\f1. New SCCS files are given mode 444 (see .IR chmod (1)). Write permission in the pertinent directory is required to create a file. All writing done by .CR admin is to a temporary x-file, called .CI x. filename\f1, (see .IR get (1)), created with mode 444 if the .CR admin command is creating a new SCCS file, or with the same mode as the SCCS file if it exists. After successful execution of .CR admin , the SCCS file is removed (if it exists), and the x-file is renamed to the name of the SCCS file. This ensures that changes are made to the SCCS file only if no errors occurred. .PP It is recommended that directories containing SCCS files be mode 755 and that SCCS files themselves be mode 444. The mode of any given directory allows only the owner to modify SCCS files contained in that directory. The mode of the SCCS files prevents any modification at all except by SCCS commands. .PP If it should be necessary to patch an SCCS file for any reason, the mode can be changed to 644 by the owner, thus allowing the use of .CR vi or any other suitable editor. .I "Care must be taken!" The edited file should .I always be processed by an .CR admin .CR -h to check for corruption followed by an .CR "admin -z" to generate a proper checksum. Another .CR "admin -h" is recommended to ensure the SCCS file is valid. .PP .CR admin also makes use of a transient lock file called .CI z. filename\f1), which is used to prevent simultaneous updates to the SCCS file by different users. See .IR get (1) for further information. .SH SEE ALSO delta(1), ed(1), get(1), sccshelp(1), prs(1), what(1), sccsfile(4), acl(5). .SH STANDARDS CONFORMANCE .CR admin ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4admin\f1 \- create and administer SCCS files@@@\f3admin(1)\f1 .\" index@\f1create and administer SCCS files@@@\f3admin(1)\f1 .\" index@\f1administer and create SCCS files@@@\f3admin(1)\f1 .\" index@\f1SCCS, create and administer SCCS files@@@\f3admin(1)\f1 .\" index@\f1files, administer and create SCCS files@@@\f3admin(1)\f1 .\" index@\f1Source Code Control System@@@see \f2SCCS\f1 .\" .\" toc@\f3admin(1)\f1:\0\0\f4admin\f1@@@create and administer SCCS files\f1 .\" $Header: sh-posix.1,v 76.4 95/11/02 14:15:41 ssa Exp $ .TA s .TH sh-posix 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sh, rsh \- standard and restricted POSIX.2-conformant command shells .SH SYNOPSIS .CR sh .RC [{ \- \(or + }\c .CR aefhikmnprstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [ \-c .IR string ] .IR arg ]...\& .PP .CR rsh .RC [{ \- \(or + }\c .CR aefhikmnprstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [ \-c .IR string ] .RI [ arg ]...\& .SS Remarks This shell is intended to conform to the shell specification of the POSIX.2 .I Shell and Utility standards. Check any standards conformance documents shipped with your system for information on the conformance of this shell to any other standards. .SS List of Subheadings in DESCRIPTION .\" .SS lines under DESCRIPTION (commands are vi/ex) .\" Extract header lines; copy to eof ":g/\.S[SH]/co$: .\" Delete extraneous leading and trailing headings .\" Delete .SS ":.,$s/....//" .\" Form into columns ":.,$!pr -3 -t -s@" .\" Replace pr tabs with blanks ":.,$s/[[:space:]]/ /g" .\" Move into place below. .TS tab(@); l l l . Shell Invocation@Tilde Substitution@Environment Options@Command Substitution@Functions rsh Restrictions@Parameter Substitution@Jobs Definitions@Blank Interpretation@Signals Commands@File Name Generation@Execution Simple Commands@Quoting@Command Reentry Compound Commands@Arithmetic Evaluation@Command Line Editing Special Commands@Prompting@emacs Editing Mode Comments@Conditional Expressions@vi Editing Mode Aliasing@Input/Output .TE .SH DESCRIPTION .CR sh is a command programming language that executes commands read from a terminal or a file. .PP .CR rsh is a restricted version of .CR sh . See the "rsh Restrictions" subsection below. .SS Shell Invocation If the shell is invoked by an .CI exec * () system call and the first character of argument zero (shell parameter .CR 0 ) is dash .RC ( \- ), the shell is assumed to be a login shell and commands are read first from .CR /etc/profile , then from either .CR .profile in the current directory or .CR $HOME/.profile if either file exists, and finally from the file named by performing parameter substitution on the value of the environment parameter .CR ENV , if the file exists. If the .CR \-s option is not present and an .I arg is, a path search is performed on the first .I arg to determine the name of the script to execute. When running .CR sh with .IR arg , the script .I arg must have read permission and any .CR setuid and .CR setgid settings will be ignored. Commands are read as described below. .PP Shell output, except for the output of some of the commands listed in the "Special Commands" subsection, is written to standard error (file descriptor 2). .SS Options The following options are interpreted by the shell when it is invoked. .TP 15 .CI \-c \0string Read commands from .IR string . .TP .CR \-i If .CR \-i is present or if the shell input and output are attached to a terminal (as reported by .CR tty() ), the shell is interactive. In this case .CR SIGTERM is ignored (so that .CR "kill 0" does not kill an interactive shell) and .CR SIGINT is caught and ignored (so that .CR wait is interruptible). In all cases, .CR SIGQUIT is ignored by the shell. See .IR signal (5). .TP .CR \-r The shell is a restricted shell. .TP .CR \-s If .CR \-s is present or if no arguments remain, commands are read from the standard input. .PP The remaining options and arguments are described under the .CR set command in the "Special Commands" subsection. .SS rsh Restrictions .CR rsh is used to set up login names and execution environments where capabilities are more controlled than those of the standard shell. The actions of .CR rsh are identical to those of .CR sh , except that the following are forbidden: .RS .TP 3 .PD 0 \(bu Changing directory (see the .CR cd special command and .IR cd (1)) .TP \(bu Setting the value of .CR SHELL , .CR ENV , or .CR PATH .TP \(bu Specifying path or command names containing .CR / .TP \(bu Redirecting output .RC ( > , .CR >| , .CR <> , and .CR >> ) .PD .RE .PP The restrictions above are enforced after the .CR .profile and .CR ENV files are interpreted. .PP When a command to be executed is found to be a shell procedure, .CR rsh invokes .CR sh to execute it. Thus, the end-user is provided with shell procedures accessible to the full power of the standard shell, while being restricted to a limited menu of commands. This scheme assumes that the end-user does not have write and execute permissions in the same directory. .PP These rules effectively give the writer of the .CR .profile file complete control over user actions, by performing guaranteed set-up actions and leaving the user in an appropriate directory (probably not the login directory). .PP The system administrator often sets up a directory of commands (usually .CR /usr/rbin ) that can be safely invoked by .CR rsh . HP-UX systems provide a restricted editor .CR red (see .IR ed (1)), suitable for restricted users. .SS Definitions .TP 20 .B metacharacter One of the following characters: .IP .CR "; & ( ) | < >" \0newline\0space\0tab .TP .B blank A tab or a space. .TP .B identifier A sequence of letters, digits, or underscores starting with a letter or underscore. Identifiers are used as names for .BR functions and .BR "named parameters" . .TP .B word A sequence of .B characters separated by one or more nonquoted .BR metacharacters . .TP .BR command A sequence of characters in the syntax of the shell language. The shell reads each command and carries out the desired action, either directly or by invoking separate utilities. .TP .B "special command" A command that is carried out by the shell without creating a separate process. Except for documented side effects, most special commands can be implemented as separate utilities. .TP .CR # Comment delimiter. A word beginning with .CR # and all following characters up to a newline are ignored. .TP .B parameter An .BR identifier , a decimal number, or one of the characters .CR ! , .CR # , .CR $ , .CR * , .CR \- , .CR ? , .CR @ , and .CR _ . See the "Parameter Substitution" subsection. .TP .B "named parameter" A .B parameter that can be assigned a value. See the "Parameter Substitution" subsection. .TP .B variable A .BR parameter . .TP .B "environment variable" A .BR parameter that is known outside the local shell, usually by means of the .CR export special command. .SS Commands A command can be a simple command that executes an executable file, a special command that executes within the shell, or a compound command that provides flow of control for groups of simple, special, and compound commands. .SS Simple Commands A simple command is a sequence of blank-separated words that may be preceded by a parameter assignment list. (See the "Environment" subsection). The first word specifies the name of the command to be executed. Except as specified below, the remaining words are passed as arguments to the invoked command. The command name is passed as argument .CR 0 (see .IR exec (2)). The .I value of a simple-command is its exit status if it terminates normally, or .CI 128+ errorstatus if it terminates abnormally (see .IR signal (5) for a list of .I errorstatus values). .PP A .B pipeline is a sequence of one or more commands separated by a bar .RC ( | ) and optionally preceded by an exclamation mark .RC ( ! ). The standard output of each command but the last is connected by a pipe (see .IR pipe (2)) to the standard input of the next command. Each command is run as a separate process; the shell waits for the last command to terminate. If .CR !\& does not precede the pipeline, the exit status of the pipeline is the exit status of the last command in the pipeline. Otherwise, the exit status of the pipeline is the logical negation of the exit status of the last command in the pipeline. .PP A .I list is a sequence of one or more pipelines separated by .CR ; , .CR & , .CR && , or .CR || , and optionally terminated by .CR ; , .CR & , or .CR |& . .RS .TP .CR ;\& Causes sequential execution of the preceding pipeline. An arbitrary number of newlines can appear in a .I list, instead of semicolons, to delimit commands. .TP .CR & Causes asynchronous execution of the preceding pipeline (that is, the shell does not wait for that pipeline to finish). .TP .CR |& Causes asynchronous execution of the preceding command or pipeline with a two-way pipe established to the parent shell. The standard input and output of the spawned command can be written to and read from by the parent shell using the .CR \-p option of the special commands .CR read and .CR print . .TP .CR && Causes the .I list following it to be executed only if the preceding pipeline returns a zero value. .TP .CR || Causes the .I list following it to be executed only if the preceding pipeline returns a nonzero value. .RE .PP Of these five symbols, .CR ; , .CR & , and .CR |& have equal precedence, which is lower than that of .CR && and .CR || . The symbols .CR && and .CR || also have equal precedence. .SS Compound Commands Unless otherwise stated, the value returned by a compound command is that of the last simple command executed in the compound command. The .CR ;\& segment separator can be replaced by one or more newlines. .PP The following keywords are recognized only as the first word of a command and when not quoted: .nf .RS .IP .C "! } elif for then" .C "[[ case else function time" .C "]] do esac if until" .C "{ done fi select while" .fi .RE .PP A compound command is one of the following. .PP .ne 3v .CR case \f2\0word\c .CR \0in \0[\|[ ; ]\0[ ( ]\c .IC \0pattern\0\f1[ | \0pattern\f1]... ) \0list\0\c .CR ;; ]...\0 ;\0esac .IP Execute the .I list associated with the first .I pattern that matches .IR word . The form of the patterns is identical to that used for file name generation (see the "File Name Generation" subsection). The .CR ;;\& case terminator cannot be replaced by newlines. .PP .ne 3v .CI for \0identifier\f1\0[ in \0word\f1\0...]\0\c .CR ;\0do \0\f2list\0 ;\0done .IP Set .I identifier to each .I word in sequence and execute the .CR do .IR list . If .CR in .IR word .RI ...\& is omitted, set .I identifier to each set positional parameter instead. See the "Parameter Substitution" subsection. Execution ends when there are no more positional parameters or words in the list. .PP .ne 4v .CI function \0identifier\0 { \0list\0 ;\0} .br .IC identifier \0()\0{ \0list\0 ;\0} .IP Define a function named by .IR identifier . A function is called by executing its identifier as a command. The body of the function is the .I list of commands between .CR { and .CR } . See the "Functions" subsection. .PP .ne 3v .CI if \0list\0 ;\0then \0list\0 ; \0\f1[\c .CI elif \0list\0 ;\0then \0list\0 ; \f1]...\&\0[\c .CI else \0list\0 ; \f1]\0 fi .IP Execute the .CR if .I list and, if its exit status is zero, execute the first .CR then .IR list . Otherwise, execute the .CR elif .I list (if any) and, if its exit status is zero, execute the next .CR then .IR list . Failing that, execute the .CR else .I list (if any). If no .CR else .I list or .CR then .I list is executed, .CR if returns a zero exit status. .PP .ne 3v .CI select \0identifier\0\f1[ in \0word\f1\0...\&]\0 ;\0do \0list\0\c .CI ;\0done .IP Print the set of .IR word s on standard error (file descriptor 2), each preceded by a number. If .CI in .IR word .RI ...\& is omitted, print the positional parameters instead (see the "Parameter Substitution" subsection). Print the .CR PS3 prompt and read a line from standard input into the parameter .CR REPLY . If this line consists of the number of one of the listed .IR word s, set .I identifier to the corresponding .IR word , execute .IR list , and repeat the .CR PS3 prompt. If the line is empty, print the selection list again, and repeat the .CR PS3 prompt. Otherwise, set .I identifier to null, execute .IR list , and repeat the .CR PS3 prompt. The select loop repeats until a .CR break special command or end-of-file is encountered. .PP .ne 3v .CI time \0pipeline .IP Execute the .I pipeline and print the elapsed time, the user time, and the system time on standard error. See also .IR time (1). .PP .ne 3v .CI "until\0" list "\0;\0do\0" list "\0;\0done" .IP Execute the .CR until .IR list . If the exit status of the last command in the list is nonzero, execute the .CR do .IR list and execute the .CR until .IR list again. When the exit status of the last command in the .CR until .I list is zero, terminate the loop. If no commands in the .CR do .I list are executed, .CR until returns a zero exit status. .PP .ne 3v .CI "while\0" list "\0;\0do\0" list "\0;\0done" .IP Execute the .CR while .IR list . If the exit status of the last command in the list is zero, execute the .CR do .IR list and execute the .CR while .IR list again. When the exit status of the last command in the .CR while .I list is nonzero, terminate the loop. If no commands in the .CR do .I list are executed, .CR while returns a nonzero exit status. .PP .ne 3v .CI ( "\0list\0" ) .IP Execute .I list in a separate environment. If two adjacent open parentheses are needed for nesting, a space must be inserted between them to avoid arithmetic evaluation. .PP .ne 3v .CI { "\0list\0" ";\0}" .IP Execute .IR list , but not in a separate environment. Note that .CR { is a keyword and requires a trailing blank to be recognized. .PP .ne 3v .CI [[ "\0expression\0" ]] .IP Evaluate .I expression and return a zero exit status when .I expression is true. See the "Conditional Expressions" subsection for a description of .IR expression . Note that .CR [[ and .CR ]] are keywords and require blanks between them and .IR expression . .SS Special Commands Special commands are simple commands that are executed in the shell process. They permit input/output redirection. Unless otherwise indicated, file descriptor 1 (standard output) is the default output location and the exit status, when there are no syntax errors, is zero. .PP Commands that are marked with \(dg or \(dg\(dg are treated specially in the following ways: .RS .TP 3 .PD 0 1. Variable assignment lists preceding the command remain in effect when the command completes. .TP 2. I/O redirections are processed after variable assignments. .TP 3. Errors cause a script that contains them to abort. .TP 4. Words following a command preceded by \(dg\(dg that are in the format of a variable assignment are expanded with the same rules as a variable assignment. This means that tilde substitution is performed after the .CR = sign and word-splitting and file-name generation are not performed. .PD .RE .PP .ne 3v \(dg .CR : \0[\f2arg\f1]...\& .IP (colon)\0 Only expand parameters. A zero exit status is returned. .PP .ne 3v \(dg .CI . \0file\f1\0[\f2arg\f1]...\& .IP (period)\0 Read and execute commands from .I file and return. The commands are executed in the current shell environment. The search path specified by .CR PATH is used to find the directory containing .IR file . If any arguments .I arg are given, they become the positional parameters. Otherwise, the positional parameters are unchanged. The exit status is the exit status of the last command executed. .PP .ne 3v \(dg\(dg .CR alias \0[ \-tx ]\0[\f2name\f1[\c .CI = value\f1]\|]...\& .IP With .IC name = value specified, define .I name as an alias and assign it the value .IR value . A trailing space in .I value causes the next word to be checked for alias substitution. .IP With .IC name = value omitted, print the list of aliases in the form .IC name = value on standard output. .IP With .I name specified without .CI = value\f1, print the specified alias. .IP With .CR \-t , set tracked aliases. The value of a tracked alias is the full path name corresponding to the given .IR name . The value of a tracked alias becomes undefined when the value of .CR PATH is reset, but the alias remains tracked. With .IC name = value omitted, print the list of tracked aliases in the form .IC name = pathname on standard output. .IP With .CR \-x , set exported aliases. An exported alias is defined across subshell environments. With .IC name = value omitted, print the list of exported aliases in the form .IC name = value on standard output. .IP Alias returns true unless a .I name is given for which no alias has been defined. .PP .ne 3v .CR bg \0[\f2job\f1]...\& .IP Put the specified .I jobs into the background. The current job is put in the background if .I job is unspecified. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v \(dg .CR break \0[\f2n\f1] .IP Exit from the enclosing .CR for , .CR select , .CR until , or .CR while loop, if any. If .I n is specified, exit from .I n levels. .PP .ne 4v .CR cd \0[ \-L \(or \-P ]\0[\f2arg\f1] .br .CI cd \0old\0new .IP In the first form, change the current working directory .RC ( PWD ) to .IR arg . If .I arg is .CR \- , the directory is changed to the previous directory .RC ( OLDPWD ). .IP With .CR \-L (default), preserve logical naming when treating symbolic links. .CR "cd \-L ..\&" moves the current directory one path component closer to the root directory. .IP With .CR \-P , preserve the physical path when treating symbolic links. .CR "cd \-P ..\&" changes the working directory to the actual parent directory of the current directory. .IP The shell parameter .CR HOME is the default .IR arg . The parameter .CR PWD is set to the current directory. .IP The shell parameter .CR CDPATH defines the search path for the directory containing .IR arg . Alternative directory names are separated by a colon .RC ( : ). If .CR CDPATH is null or undefined, the default value is the current directory. Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If .I arg begins with a .CR / , the search path is not used. Otherwise, each directory in the path is searched for .IR arg . See also .IR cd (1). .IP The second form of .CR cd substitutes the string .I new for the string .I old in the current directory name, .CR PWD , and tries to change to this new directory. .PP .ne 3v .CR command \0[\f2arg\f1]...\& .IP Treat .I arg as a command, but disable function lookup on .IR arg . See .IR command (1) for usage and description. .PP .ne 3v \(dg .CR continue \0[\f2n\f1] .IP Resume the next iteration of the enclosing .CR for , .CR select , .CR until , or .CR while loop. If .I n is specified, resume at the .IR n th enclosing loop. .PP .ne 3v .CR echo \0[\f2arg\f1]...\& .IP Print .I arg on standard output. See .IR echo (1) for usage and description. See also the .CR print special command. .PP .ne 3v \(dg .CR eval \0[\f2arg\f1]...\& .IP Read the arguments as input to the shell and execute the resulting commands. Allows parameter substitution for keywords and characters that would otherwise be unrecognized in the resulting commands. .PP .ne 3v \(dg .CR exec \0[\f2arg\f1]...\& .IP Parameter assignments remain in effect after the command completes. If .I arg is given, execute the command specified by the arguments in place of this shell without creating a new process. Input/output arguments may appear and affect the current process. If no arguments are given, modify file descriptors as prescribed by the input/output redirection list. In this case, any file descriptor numbers greater than 2 that are opened with this mechanism are closed when another program is invoked. .PP .ne 3v \(dg .CR exit \0[\f2n\f1] .IP Exit from the shell with the exit status specified by .IR n . If .I n is omitted, the exit status is that of the last command executed. An end-of-file also causes the shell to exit, except when a shell has the .CR ignoreeof option set. (See the .CR set special command.) .PP .ne 4v \(dg\(dg .CR export \0[\f2name\f1[ = \f2value\f1]\|]...\& .br \(dg\(dg .CR export\0\-p .IP Mark the given variable .IR name s for automatic export to the environment of subsequently executed commands. Optionally, assign values to the variables. .IP With .CR \-p , write the names and values of all exported variables to standard output, in a format with the proper use of quoting, so that it is suitable for re-input to the shell as commands that achieve the same exporting results. .PP .ne 6v .CR fc \0[ \-r ]\0[ \-e \0\f2ename\f1]\0[\f2first\f1\0[\f2last\f1]\|] .br .CR fc\0\-l \0[ \-nr ]\0[\f2first\f1\0[\f2last\f1]\|] .br .CR fc\0\-s \0[\f2old\f1 = \f2new\f1]\0[\f2first] .br .CR fc\0\-e\0\- \0[\f2old\f1 = \f2new\f1]\0[\f2command\f1] .IP List, or edit and reexecute, commands previously entered to an interactive shell. A range of commands from .I first to .I last is selected from the last .CR HISTSIZE commands typed at the terminal. The arguments .I first and .I last can be specified as a number or string. A given string is used to locate the most recent command. A negative number is used to offset the current command number. .IP With .CR \-l , list the commands on standard output. Without .CR \-l , invoke the editor program .I ename on a file containing these keyboard commands. If .I ename is not supplied, the value of the parameter .CR FCEDIT (default .CR /usr/bin/ed ) is used as the editor. Once editing has ended, the commands (if any) are executed. If .I last is omitted, only the command specified by .I first is used. If .I first is not specified, the default is the previous command for editing and \(mi16 for listing. .IP With .CR \-r , reverse the order of the commands. .IP With .CR \-n , suppress command numbers when listing. .IP With .CR \-s , reexecute the command without invoking an editor. .IP The .IC old = new argument replaces the first occurrence of string .IC old in the command to be reexecuted by the string .IR new . .PP .ne 3v .CR fg \0[\f2job\f1]...\& .IP Bring each .I job into the foreground in the order specified. If no .I job is specified, bring the current job into the foreground. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v .CR getopts \0\f2optstring\0name\f1\0[\f2arg\f1]...\& .IP Parse the argument list, or the positional parameters if no arguments, for valid options. On each execution, return the next option in .IR name . See .IR getopts (1) for usage and description. .IP An option begins with a .CR + or a .CR \- . An argument not beginning with .CR + or .CR \- , or the argument .CR \-\- , ends the options. .I optstring contains the letters that .CR getopts recognizes. If a letter is followed by a .CR : , that option is expected to have an argument. The options can be separated from the argument by blanks. .IP For an option specified as .CI \- letter\f1, .I name is set to .IR letter . For an option specified as .CI + letter\f1, .I name is set to .CI + letter\f1. The index of the next .I arg is stored in .CR OPTIND . The option argument, if any, is stored in .CR OPTARG . If no option argument is found, or the option found does not take an argument, .CR OPTARG is unset. .IP A leading .CR :\& in .I optstring causes .CR getopts to store the letter of an invalid option in .CR OPTARG , and to set .I name to .CR ?\& for an unknown option and to .CR :\& when a required option argument is missing. Otherwise, .CR getopts prints an error message. The exit status is nonzero when there are no more options. .PP .ne 4v .CR hash \0[\f2utility\f1]...\& .br .CR hash\0\-r .IP Affect the way the current shell environment remembers the locations of utilities. With .IR utility , add utility locations to a list of remembered locations. With no arguments, print the contents of the list. With .CR \-r , forget all previously remembered utility locations. .PP .ne 3v .CR jobs \0[ \-lnp ]\0[\f2job\f1]...\& .IP List information about each given job, or all active jobs if .I job is not specified. With .CR \-l , list process IDs in addition to the normal information. With .CR \-n , display only jobs that have stopped or exited since last notified. With .CR \-p , list only the process group. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 5v .CR kill \0[ \-s \0\f2signal\f1]\0\f2process\f1\0...\& .br .CR kill\0\-l .br .CR kill \0[ \- \f2signal\f1]\0\f2process\f1\0...\& .IP Send either signal 15 .RC ( SIGTERM , terminate) or the specified .I signal to the specified jobs or processes. See .IR kill (1) for usage and description. .IP With .CR \-l , list the signal names and numbers. .PP .ne 4v .CI let \0arg\f1\0... .br .CI (( \0arg\f1\0... )) .IP Evaluate each .I arg as a separate arithmetic expression. See the "Arithmetic Evaluation" subsection for a description of arithmetic expression evaluation. The exit status is 0 if the value of the last expression is nonzero, and 1 otherwise. .PP .ne 3v \(dg .CR newgrp \0[ \- ]\0[\f2group\f1] .IP Replace the current shell with a new one having .I group as the user's group. The default group is the user's login group. With .CR \- , the user's .CR .profile and .CR $ENV files are also executed. See .IR newgrp (1) for usage and description. Equivalent to .CI "exec\0newgrp" "\0arg\0\f1...." .PP .ne 3v .CR print \0[ \-nprRsu [\f2n\f1]\|]\0[\f2arg\f1]...\& .IP The shell output mechanism. With no options or with option .CR \- or .CR \-\- , print the arguments on standard output as described in .IR echo (1). See also .IR printf (1). .IP With .CR \-n , do not add a newline character to the output. .IP With .CR \-p , write the arguments onto the pipe of the process spawned with .CR |& instead of standard output. .IP With .CR \-R or .CR \-r (raw mode), ignore the escape conventions of .CR echo . With .CR \-R , print all subsequent arguments and options other than .CR \-n . .IP With .CR \-s , write the arguments into the history file instead of to standard output. .IP With .CR \-u , specify a one-digit file descriptor unit number .I n on which the output will be placed. The default is .CR 1 (standard output). .PP .ne 3v .CR pwd \0[ \-L \(or \-P ] .IP Print the name of the current working directory (equivalent to .CR "print\0\-r\0\-\0$PWD" ). With .CR \-L (the default), preserve the logical meaning of the current directory. With .CR \-P , preserve the physical meaning of the current directory if it is a symbolic link. See also the .CR cd special command, .IR cd (1), .IR ln (1), and .IR pwd (1). .PP .ne 3v .CR read \0[ \-prsu [\f2n\f1]\|]\0[\f2name\f1 ? \f2prompt\f1]\0[\f2name\f1]...\& .IP The shell input mechanism. Read one line (by default, from standard input) and break it up into words using the characters in .CR IFS as separators. The first word is assigned to the first .IR name , the second word to the second .IR name , and so on; the remaining words are assigned to the last .IR name . See also .IR read (1). The return code is .CR 0 , unless an end-of-file is encountered. .IP With .CR \-p , take the input line from the input pipe of a process spawned by the shell using .CR |& . An end-of-file with .CR \-p causes cleanup for this process so that another process can be spawned. .IP With .CR \-r (raw mode), a .CR \e at the end of a line does not signify line continuation. .IP With .CR \-s , save the input as a command in the history file. .IP With .CR \-u , specify a one-digit file descriptor unit to read from. The file descriptor can be opened with the .CR exec special command. The default value of .I n is .CR 0 (standard input). If .IR name is omitted, .CR REPLY is used as the default .IR name . .IP If the first argument contains a .CR ? , the remainder of the argument is used as a .I prompt when the shell is interactive. .IP If the given file descriptor is open for writing and is a terminal device, the prompt is placed on that unit. Otherwise, the prompt is issued on file descriptor 2 (standard error). .PP .ne 4v \(dg\(dg .CR readonly \0[\f2name\f1[ = \f2value\f1]\|]...\& .br \(dg\(dg .CR readonly\0\-p .IP Mark the given .IR name s read only. These names cannot be changed by subsequent assignment. .IP With .CR \-p , write the names and values of all read-only variables to standard output in a format with the proper use of quoting so that it is suitable for re-input to the shell as commands that achieve the same attribute-setting results. .PP .ne 3v \(dg .CR return \0[\f2n\f1] .IP Cause a shell function to return to the invoking script with the return status specified by .IR n . If .I n is omitted, the return status is that of the last command executed. Only the low 8 bits of .I n (decimal 0 to 255) are passed back to the caller. If .CR return is invoked while not in a function or a .CR .\& script (see the .CR .\& special command), it has the same effect as an .CR exit command. .PP .ne 3v .CR set .RC [{ \- \(or + }\c .CR abCefhkmnopstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [{ \- \(or + } A .IR name ]\0[ arg ]...\& .IP Set .RC ( \- ) or clear .RC ( + ) execution options or perform array assignments .RC ( \-A ,\ +A ). All options except .CR \-A and .CR +A can be supplied in a shell invocation (see the SYNOPSIS section and the "Shell Invocation" subsection). .IP Using .CR + instead of .CR \- before an option causes the option to be turned off. These options can also be used when invoking the shell. The current list of set single-letter options is contained in the shell variable .CR \- . It can be examined with the command .CR "echo $-" . .IP The .CR \- and .CR + options can be intermixed in the same command, except that there can be only one .CR \-A or .CR +A option. .IP Unless .CR \-A or .CR +A is specified, the remaining .I arg arguments are assigned consecutively to the positional parameters .CR 1 , .CR 2 ,\0.... .IP The .CR set command with neither arguments nor options displays the names and values of all shell parameters on standard output. See also .IR env (1). .IP The options are defined as follows. .RS .TP .CR \-A Array assignment. Unset the variable .I name and assign values sequentially from the list .IR arg . With .CR \+A , do not unset the variable .I name first. .TP .CR \-a Automatically export subsequently defined parameters. .TP .CR \-b Cause the shell to notify the user asynchronously of background jobs as they are completed. When the shell notifies the user that a job has been completed, it can remove the job's process ID from the list of those known in the current shell execution environment. .TP .CR \-C Prevent redirection .CR > from truncating existing files. Requires .CR >| to truncate a file when turned on. .TP .CR \-e Execute the .CR ERR trap, if set, and exit .I if a command has a nonzero exit status, and is not part of the compound list following a .CR if , .CR until , or .CR while keyword, and is not part of an AND or OR list, and is not a pipeline preceded by the .CR !\& reserved word. This mode is disabled while reading profiles. .TP .CR \-f Disable file name generation. .TP .CR \-h Specify that each command whose name is an .I identifier becomes a tracked alias when first encountered. .TP .CR \-k Place all parameter assignment arguments (not just those that precede the command name) into the environment for a command. .TP .CR \-m Run background jobs in a separate process group and print a line upon completion. The exit status of background jobs is reported in a completion message. This option is turned on automatically for interactive shells. .TP .CR \-n Read commands and check them for syntax errors, but do not execute them. The .CR \-n option is ignored for interactive shells. .TP .ne 5v .CR \-o Set an .I option argument from the following list. Repeat the .CR \-o option to specify additional .I option arguments. .RS .TP 15 .PD 0 .CR allexport Same as .CR \-a . .TP .CR bgnice Run all background jobs at a lower priority. .TP .CR errexit Same as .CR \-e . .TP .CR emacs Use a .CR emacs -style inline editor for command entry. .TP .CR gmacs Use a .CR gmacs -style inline editor for command entry. .TP .CR ignoreeof Do not exit from the shell on end-of-file .RI ( eof as defined by .CR stty ; default is .CR ^D ). The .CR exit special command must be used. .TP .CR keyword Same as .CR \-k . .TP .CR markdirs Append a trailing .CR / to all directory names resulting from file name generation. .TP .CR monitor Same as .CR \-m . .TP .CR noclobber Same as .CR \-C . .TP .CR noexec Same as .CR \-n . .TP .CR noglob Same as .CR \-f . .TP .CR nolog Do not save function definitions in history file. .TP .CR notify Same as .CR \-b . .TP .CR nounset Same as .CR \-u . .TP .CR privileged Same as .CR \-p . .TP .CR verbose Same as .CR \-v . .TP .CR trackall Same as .CR \-h . .TP .CR vi Use a .CR vi -style inline editor for command entry. .TP .CR viraw Process each character as it is typed in .CR vi mode. .TP .CR xtrace Same as .CR \-x . .PD .RE .TP .CR \-p Disable processing of the .CR $HOME/.profile file and uses the file .CR /etc/suid_profile instead of the .CR ENV file. This mode is on whenever the effective user ID (group ID) is not equal to the real user ID (group ID). Turning this off causes the effective user ID and group ID to be set to the real user ID and group ID. .TP .CR \-s Sort the positional parameters. .TP .CR \-t Exit after reading and executing one command. .TP .CR \-u Treat unset parameters as an error when substituting. .TP .CR \-v Print shell input lines as they are read. .TP .CR \-x Print commands and their arguments as they are executed. .TP .CR \- Turn off .CR \-x and .CR \-v options and stop examining arguments for options. .TP .CR \-\- Do not change any of the options; useful in setting parameter .CR 1 to a value beginning with .CR \- . If no arguments follow this option, the positional parameters are unset. .RE .PP .ne 3v \(dg .CR shift "\0[\f2n\f1]" .IP Rename the positional parameters from .IC n +1 \f1\0...\& to .CR 1 \0.... The default value of .I n is .CR 1 . .I n can be any arithmetic expression that evaluates to a nonnegative number less than or equal to .CR $# . .PP .ne 3v .CR test \0[\f2expr\f1] .IP Evaluate conditional expression .IR expr . See .IR test (1) for usage and description. The arithmetic comparison operators are not restricted to integers. They allow any arithmetic expression. The following additional primitive expressions are allowed: .RS .TP 20 .PD 0 .CI \-L \0file True if .I file is a symbolic link. .TP .CI \-e \0file True if .I file exists. .TP .IC file1\0 \-nt \0file2 True if .I file1 is newer than .IR file2 . .TP .IC file1\0 \-ot \0file2 True if .I file1 is older than .IR file2 . .TP .IC file1\0 \-ef \0file2 True if .I file1 has the same device and i-node number as .IR file2 . .PD .RE .PP .ne 3v \(dg .CR times .IP Print the accumulated user and system times for the shell and for processes run from the shell. .PP .ne 3v \(dg .CR trap \0[\f2arg\f1]\0[\f2sig\f1]...\& .IP Set .I arg as a command that is read and executed when the shell receives a .IR sig signal. (Note that .I arg is scanned once when the trap is set and once when the trap is taken.) Each .I sig can be given as the number or name of a signal. Letter case is ignored. For example, .CR 3 , .CR QUIT , .CR quit , and .CR SIGQUIT all specify the same signal. Use .CR "kill \-l" to get a list of signals. .IP Trap commands are executed in signal number order. Any attempt to set a trap on a signal that was ignored upon entering the current shell is ineffective. .IP If .I arg is .CR \- (or if .I arg is omitted and the first .I sig is numeric), reset all traps for each .I sig to their original values. .IP If .I arg is the null string .RC ( '' or \&\c .C """""\c" ), each .I sig is ignored by the shell and by the commands it invokes. .IP If .I sig is .CR DEBUG , then .I arg is executed after each command. If .I sig is .CR ERR , .I arg is executed whenever a command has a nonzero exit code. If .I sig is .CR 0 or .CR EXIT and the .CR trap statement is executed inside the body of a function, the command .I arg is executed after the function completes. If .I sig is .CR 0 or .CR EXIT for a .CR trap set outside any function, the command .I arg is executed on exit from the shell. .IP With no arguments, print a list of commands associated with each signal name. .PP .ne 4v \(dg\(dg .CR typeset \0[{ \- \(or + }\c .CR LRZfilrtux [\f2n\f1]\|]\0[\f2name\f1[ = \f2value\f1]\|]... .br \(dg\(dg .IC name = value .RC [\f2name = \f2value\f1]...\& .IP Assign types and a value to a local named parameter .IR name . See also the .CR export special command. Parameter assignments remain in effect after the command completes. When invoked inside a function, create a new instance of the parameter .IR name . The parameter value and type are restored when the function completes. .IP The following list of attributes can be specified. Use .CR \+ instead of .CR \- to turn the options off. .RS .TP .CR \-L Left justify and remove leading blanks from .IR value . If .I n is nonzero, it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. When .I name is assigned, the value is filled on the right with blanks or truncated, if necessary, to fit into the field. Leading zeros are removed if the .CR \-Z option is also set. The .CR \-R option is turned off. Flagged as .CI leftjust \0n\f1. .TP .CR \-R Right justify and fill with leading blanks. If .I n is nonzero, it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. The field is left-filled with blanks or truncated from the end if the parameter is reassigned. The .CR \-L option is turned off. Flagged as .CI rightjust \0n\f1. .TP .CR \-Z Right justify and fill with leading zeros if the first nonblank character is a digit and the .CR \-L option has not been set. If .I n is nonzero it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. Flagged as .CI zerofill \0n\f1 plus the flag for .CR \-L or .CR \-R . .TP .CR \-f Cause .I name to refer to function names rather than parameter names. No assignments can be made to the .I name declared with the .CR typeset statement. The only other valid options are .CR \-t (which turns on execution tracing for this function) and .CR \-x (which allows the function to remain in effect across shell procedures executed in the same process environment). Flagged as .CR function . .TP .CR \-i Parameter is an integer. This makes arithmetic faster. If .I n is nonzero it defines the output arithmetic base; otherwise, the first assignment determines the output base. Flagged as .CR integer \0[ base \0\f2n\f1]. .TP .CR \-l Convert all uppercase characters to lowercase. The uppercase .CR \-u option is turned off. Flagged as .CR lowercase . .TP .CR \-r Mark any given .I name as "read only". The name cannot be changed by subsequent assignment. Flagged as .CR readonly . .TP .CR \-t Tag the named parameters. Tags are user-definable and have no special meaning to the shell. Flagged as .CR tagged . .TP .CR \-u Convert all lowercase characters to uppercase characters. The lowercase .CR \-l option is turned off. Flagged as .CR uppercase . .TP .CR \-x Mark any given .I name for automatic export to the environment of subsequently executed commands. Flagged as .CR export . .RE .IP .CR typeset alone displays a list of parameter names, prefixed by any flags specified above. .IP .CR "typeset \-" displays the parameter names followed by their values. Specify one or more of the option letters to restrict the list. Some options are incompatible with others. .IP .CR "typeset +" displays the parameter names alone. Specify one or more of the option letters to restrict the list. Some options are incompatible with others. .PP .ne 3v .CR ulimit \0[ \-HSacdfnst ]\0[\f2limit\f1] .IP Set or display a resource limit. The limit for a specified resource is set when .IR limit is specified. The value of .IR limit can be a number in the unit specified with each resource, or the keyword .CR unlimited . .IP The .CR \-H and .CR \-S flags specify whether the hard limit or the soft limit is set for the given resource. A hard limit cannot be increased once it is set. A soft limit can be increased up to the hard limit. If neither .CR \-H nor .CR \-S is specified, the limit applies to both. The current resource limit is printed when .IR limit is omitted. In this case, the soft limit is printed unless .CR \-H is specified. When more than one resource is specified, the limit name and unit are printed before the value. .IP If no option is given, .CR \-f is assumed. .RS .TP .PD 0 .CR \-a List all of the current resource limits. .TP .CR \-c The number of 512-byte blocks in the size of core dumps. .TP .CR \-d The number of kilobytes in the size of the data area. .TP .CR \-f The number of 512-byte blocks in files written by child processes (files of any size can be read). .TP .CR \-n The number of file descriptors. .TP .CR \-s The number of kilobytes in the size of the stack area. .TP .CR \-t The number of seconds to be used by each process. .PD .RE .PP .ne 3v .CR umask \0[ \-S ]\0[\f2mask\f1] .IP Set the user file-creation mask .IR mask . .I mask can be either an octal number or a symbolic value as described in .IR umask (1). A symbolic value shows permissions that are unmasked. An octal value shows permissions that are masked off. .IP Without .I mask , print the current value of the mask. With .CR \-S , print the value in symbolic format. Without .CR \-S , print the value as an octal number. The output from either form can be used as the .I mask of a subsequent invocation of .CR umask . .PP .ne 4v .CI unalias \0name\f1\0...\& .br .CR unalias\0\-a .IP Remove each .IR name from the alias list. With .CR \-a , remove all .CR alias definitions from the current shell execution environment. .PP .ne 3v .CR unset \0[ \-fv ]\0\f2name\f1\0...\& .IP Remove the named shell parameters from the parameter list. Their values and attributes are erased. Read-only variables cannot be unset. With .CR \-f , .IR name s refer to function names. With .CR \-v , .IR name s refer to variable names. Unsetting .CR _ , .CR ERRNO , .CR LINENO , .CR MAILCHECK , .CR OPTARG , .CR OPTIND , .CR RANDOM , .CR SECONDS , and .CR TMOUT removes their special meaning, even if they are subsequently assigned to. .PP .ne 3v \(dg .CR wait \0[\f2job\f1] .IP Wait for the specified .I job to terminate or stop, and report its status. This status becomes the return code for the .CR wait command. Without .I job , wait for all currently active child processes to terminate or stop. The termination status returned is that of the last process. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v .CR whence \0[ \-pv ]\0\f2name\f1\0...\& .IP For each .IR name , indicate how it would be interpreted if used as a command name. With .CR \-v , produce a more verbose report. With .CR \-p do a path search for .IR name , disregarding any use as an alias, a function, or a reserved word. .SS Comments A .I word beginning with .CR # causes that word and all the following characters up to a newline to be ignored. .SS Aliasing The first word of each command is replaced by the text of an .CR alias , if an .CR alias for this word has been defined. An .CR alias name consists of any number of characters excluding metacharacters, quoting characters, file expansion characters, parameter and command substitution characters, and =. The replacement string can contain any valid shell script, including the metacharacters listed above. The first word of each command in the replaced text, other than any that are in the process of being replaced, will be tested for additional aliases. If the last character of the alias value is a .IR blank , the word following the alias is also checked for alias substitution. Aliases can be used to redefine special commands, but cannot be used to redefine the keywords listed in the "Compound Commands" subsection. Aliases can be created, listed, and exported with the .CR alias command and can be removed with the .CR unalias command. Exported aliases remain in effect for subshells but must be reinitialized for separate invocations of the shell (see the "Shell Invocation" subsection). .PP Aliasing is performed when scripts are read, not while they are executed. Therefore, for it to take effect, an .CR alias must be executed before the command referring to the alias is read. .PP Aliases are frequently used as a shorthand for full path names. An option to the aliasing facility allows the value of the alias to be automatically set to the full path name of the corresponding command. These aliases are called .I tracked aliases. The value of a .I tracked alias is defined the first time the identifier is read and becomes undefined each time the .CR PATH variable is reset. These aliases remain .I tracked so that the next reference will redefine the value. Several tracked aliases are compiled into the shell. The .CR \-h option of the .CR set command converts each command name that is an .I identifier into a tracked alias. .PP The following .I exported aliases are compiled into the shell but can be unset or redefined: .nf .IP .C autoload='typeset \-fu' .C command='command ' .C functions='typeset \-f' .C history='fc \-l' .C integer='typeset \-i' .C local=typeset .C nohup='nohup ' .C r='fc \-e \-' .C stop='kill \-STOP' .C suspend='kill \-STOP $$' .C type='whence \-v' .SS Tilde Substitution After alias substitution is performed, each word is checked to see if it begins with an unquoted tilde .RC ( ~ ). If it does, the word up to a .CR / is checked to see if it matches a user name in the .CR /etc/passwd file. If a match is found, the .CR ~ and the matched login name are replaced by the login directory of the matched user. If no match is found, the original text is left unchanged. A .CR ~ alone or before a .CR / is replaced by the value of the .CR HOME parameter. A .CR ~ followed by a .CR + or .CR \- is replaced by the value of the parameter .CR PWD and .CR OLDPWD , respectively. In addition, tilde substitution is attempted when the value of a parameter assignment begins with a .CR ~ . .SS Command Substitution The standard output from a command enclosed in parenthesis preceded by a dollar sign .RC ( $( ...\& ) ) or a pair of grave accents .RC ( ` ...\& ` ) can be used as part or all of a word; trailing newlines are removed. In the second (archaic) form, the string between the accents is processed for special quoting characters before the command is executed. See the "Quoting" subsection. The command substitution .CR "$(cat file)" can be replaced by the equivalent but faster .CR $(\0\c ". .TP .CR PS3 Selection prompt string used within a .CR select loop. If unset, it defaults to "\c .CR #?\0\c ". .TP .CR PS4 Execution trace string that precedes each line of an execution trace. See the .CR "set \-x" special command. If unset, it defaults to "\c .CR +\0\c ". .TP .CR SHELL The path name of the shell is kept in the environment. When invoked, the shell is restricted if the value of this variable contains an .CR r in the base name. .TP .CR TMOUT If set to a value greater than zero, the shell will terminate if a command is not entered within the prescribed number of seconds after issuing the .CR PS1 prompt. (Note that the shell can be compiled with a maximum bound for this value which cannot be exceeded.) .TP .CR VISUAL Invokes the corresponding option when the value of this variable ends in .CR emacs , .CR gmacs , or .CR vi . See the .CR "set \-o" special command. .PP The shell gives default values to .CR IFS , .CR MAILCHECK , .CR PATH , .CR PS1 , .CR PS2 , and .CR TMOUT . On the other hand, .CR MAIL , .CR ENV , .CR HOME , and .CR SHELL are never set automatically by the shell (although .CR HOME , .CR MAIL , and .CR SHELL are set by .CR login ; see .IR login (1)). .SS Blank Interpretation After parameter and command substitution, the results of substitution are scanned for field separator characters (defined in .CR IFS ), and split into distinct arguments when such characters are found. .CR sh retains explicit null arguments (\c .C """""" or .CR '' ) but removes implicit null arguments (those resulting from parameters that have null values). .SS File Name Generation Following substitution, each command .I word is processed as a pattern for file name expansion unless expansion has been disabled with the .CR "set \-f" special command. The form of the patterns is the Pattern Matching Notation defined in .IR regexp (5). The word is replaced with sorted file names matching the pattern. If no file name is found that matches the pattern, the word is left unchanged. .PP In addition to the notation described in .IR regexp (5), .CR sh recognizes composite patterns made up of one or more pattern lists separated from each other with a .CR | . Composite patterns can be formed with one or more of the following: .RS .TP 18 .PD 0 .CI ?( pattern-list ) Matches any one of the given patterns. .TP .CI *( pattern-list ) Matches zero or more occurrences of the given patterns. .TP .CI +( pattern-list ) Matches one or more occurrences of the given patterns. .TP .CI @( pattern-list ) Matches exactly one of the given patterns. .TP .CI !( pattern-list ) Matches anything, except one of the given patterns. .PD .RE .SS Quoting Each of the metacharacters (see the "Definitions" subsection) has a special meaning to the shell and terminates a word unless quoted. A character may be .B quoted (that is, made to stand for itself) by preceding it with a backslash .RC ( \e ). The pair .CR \e newline is ignored; the current and following lines are concatenated. .PP All characters enclosed between a pair of apostrophes .RC ( ' ...\& ' ) are quoted. An apostrophe cannot appear within apostrophes. .PP Parameter and command substitution occurs inside quotation marks (\c .C """\c" \&...\&\c .C """\c" ). .CR \e quotes the characters .CR \e , .CR ` , .C """\c" , and .CR $ . .PP Inside grave accent marks .RC ( ` ...\& ` ), .CR \e quotes the characters .CR \e , .CR ` , and .CR $ . If the grave accents occur within quotation marks, .CR \e also quotes the character .C """\c" \&. .PP The meanings of .CR $* and .CR $@ are identical when not quoted or when used as a parameter assignment value or as a file name. However, when used as a command argument, .C """\c" .CR $*\c .C """" is equivalent to .C """\c" .CI $1 d $2 d\f1...\&\c .C """\c" , whereas .C """\c" .CR $@\c .C """" is equivalent to .C """\c" .CR $1\c .C """\c" .IR d\c .C """\c" .CR $2\c .C """\c" .IR d ...\& (where .I d is the first character of .CR IFS ), .PP The special meaning of keywords or aliases can be removed by quoting any character of the name. The recognition of function names or special command names cannot be altered by quoting them. .SS Arithmetic Evaluation Integer arithmetic is provided with the special command .CR let . Evaluations are performed using long integer arithmetic. Constants take the form .IC base # n or .IR n , where .I base is a decimal number between two and thirty-six representing the arithmetic base and .I n is a number in that base. If .IC base # is omitted, base 10 is used. .PP An arithmetic expression uses the same syntax, precedence, and associativity of expression as the C language. All the integral operators, other than .CR ++ , .CR \-\- , .CR ?: , and .CR , are supported. Variables can be referenced by name within an arithmetic expression without using the parameter substitution syntax. When a variable is referenced, its value is evaluated as an arithmetic expression. .PP A variable can be typed as an integer with the .CR \-i option of the .CR typeset special command, as in .CI typeset\0-i \f1[\f2base\f1]\f2\0name\f1. Arithmetic evaluation is performed on the value of each assignment to a variable with the .CR \-i attribute. If you do not specify an arithmetic base, the first assignment to the variable determines the arithmetic base. This base is used when parameter substitution occurs. .PP Since many of the arithmetic operators require quoting, an alternative form of the .CR let command is provided. For any command beginning with .CR (( , all characters until the matching .CR )) are treated as a quoted expression. More precisely, .CR (( ...\& )) is equivalent to .CR let .C """\c" .RC ...\c .C """\c" .RC . .SS Prompting When used interactively, the shell prompts with the value of .CR PS1 before reading a command. Whenever a newline is received and further input is needed to complete a command, the secondary prompt (the value of .CR PS2 ) is issued. .SS Conditional Expressions A .B "conditional expression" is used with the .CR [[ compound command to test attributes of files and to compare strings. Word splitting and file name generation are not performed on the words between .CR [[ and .CR ]] . Each expression can be constructed from one or more of the following unary or binary expressions: .RS .TP 20 .PD 0 .CI \-a \0file True, if .I file exists. .TP .CI \-b \0file True, if .I file exists and is a block special file. .TP .CI \-c \0file True, if .I file exists and is a character special file. .TP .CI \-d \0file True, if .I file exists and is a directory. .TP .CI \-e \0file True, if .I file exists. .TP .CI \-f \0file True, if .I file exists and is an ordinary file. .TP .CI \-g \0file True, if .I file exists and has its setgid bit set. .TP .CI \-h \0file True, if .I file exists and is a symbolic link. .TP .CI \-k \0file True, if .I file exists and has its sticky bit set. .TP .CI \-n \0string True, if length of .I string is nonzero. .TP .CI \-o \0option True, if the set option named .I option is on. .TP .CI \-p \0file True, if .I file exists and is a fifo special file or a pipe. .TP .CI \-r \0file True, if .I file exists and is readable by current process. .TP .CI \-s \0file True, if .I file exists and has a size greater than zero. .TP .CI \-t \0fildes True, if file descriptor number .I fildes is open and is associated with a terminal device. .TP .CI \-u \0file True, if .I file exists and has its setuid bit set. .TP .CI \-w \0file True, if .I file exists and is writable by the current process. .TP .CI \-x \0file True, if .I file exists and is executable by the current process. If .I file exists and is a directory, then the current process has permission to search in the directory. .TP .CI \-z \0string True, if length of .I string is zero. .TP .CI \-L \0file True, if .I file exists and is a symbolic link. .TP .CI \-O \0file True, if .I file exists and is owned by the effective user ID of this process. .TP .CI \-G \0file True, if .I file exists and its group matches the effective group ID of this process. .TP .CI \-S \0file True, if .I file exists and is a socket. .TP .IC file1\0 \-nt \0file2 True, if .I file1 exists and is newer than .IR file2 . .TP .IC file1\0 \-ot \0file2 True, if .I file1 exists and is older than .IR file2 . .TP .IC file1\0 \-ef \0file2 True, if .I file1 and .I file2 exist and refer to the same file. .TP .IC string\0 = \0pattern True, if .I string matches .IR pattern . .TP .IC string\0 != \0pattern True, if .I string does not match .IR pattern . .TP .IC string\0 < \0string2 True, if .I string1 comes before .I string2 based on the ASCII value of their characters. .TP .IC string\0 > \0string2 True, if .I string1 comes after .I string2 based on the ASCII value of their characters. .TP .IC exp1\0 \-eq \0exp2 True, if .I exp1 is equal to .IR exp2 . .TP .IC exp1\0 \-ne \0exp2 True, if .I exp1 is not equal to .IR exp2 . .TP .IC exp1\0 \-lt \0exp2 True, if .I exp1 is less than .IR exp2 . .TP .IC exp1\0 \-gt \0exp2 True, if .I exp1 is greater than .IR exp2 . .TP .IC exp1\0 \-le \0exp2 True, if .I exp1 is less than or equal to .IR exp2 . .TP .IC exp1\0 \-ge \0exp2 True, if .I exp1 is greater than or equal to .IR exp2 . .PD .RE .PP A compound expression can be constructed from these primitives by using any of the following, listed in decreasing order of precedence. .RS .TP 20 .PD 0 .CI ( exp ) True, if .I exp is true. Used to group expressions. .TP .CI ! exp True, if .I exp is false. .TP .IC exp1\0 && \0exp2 True, if .I exp1 and .I exp2 are both true. .TP .IC exp1\0 || \0exp2 True, if either .I exp1 or .I exp2 is true. .PD .RE .SS Input/Output Before a command is executed, its input and output can be redirected using a special notation interpreted by the shell. The following can appear anywhere in a simple-command or may precede or follow a command and are not passed on to the invoked command. Command and parameter substitution occurs before .I word or .I digit is used, except as noted below. File name generation occurs only if the pattern matches a single file and blank interpretation is not performed. .RS .TP 15 .CI < word Use file .I word as standard input (file descriptor .CR 0 ). .TP .CI > word Use file .I word as standard output (file descriptor .CR 1 ). If the file does not exist, it is created. If the file exists, and the .CR noclobber option is on, an error occurs; otherwise, the file is truncated to zero length. .TP .CI >| word Same as .CR > , except that it overrides the .CR noclobber option. .TP .CI >> word Use file .I word as standard output. If the file exists, output is appended to it (by first searching for the end-of-file); otherwise, the file is created. .TP .CI <> word Open file .I word for reading and writing as standard input. .TP .CR << [ \- ]\f2word The shell input is read up to a line that matches .IR word , or to an end-of-file. No parameter substitution, command substitution or file name generation is performed on .IR word . The resulting document, called a .IR here-document , becomes the standard input. If any character of .I word is quoted, no interpretation is placed upon the characters of the document. Otherwise, parameter and command substitution occurs, .CR \e newline is ignored, and .CR \e must be used to quote the characters .CR \e , .CR $ , .CR ` , and the first character of .IR word . If .CR \- is appended to .CR << , all leading tabs are stripped from .I word and from the document. .TP .CI <& digit The standard input is duplicated from file descriptor .I digit (see .IR dup (2)). .TP .CI >& digit The standard output is duplicated to file descriptor .I digit (see .IR dup (2)). .TP .CR <&- The standard input is closed. .TP .CR >&- The standard output is closed. .TP .CR <&p The input from the coprocess is moved to standard input. .TP .CR >&p The output to the coprocess is moved to standard output. .RE .RE .PP If any of the above redirections is preceded by a digit .RC ( 0 to .CR 9 ), the file descriptor used is the one specified by the digit, instead of the default .CR 0 (standard input) or .CR 1 (standard output). For example: .IP .CR 2>&1 .PP means open file descriptor 2 for writing as a duplicate of file descriptor 1. Output directed to file descriptor 2 is written in the same location as output to file descriptor 1. .PP Order is significant in redirection. The shell evaluates each redirection in terms of the .RI ( "file descriptor" ", " file ) assignment at the time of evaluation. For example: .IP .CR 1> \f2fname\0 2>&1 .PP first assigns file descriptor 1 to file .IR fname . It then assigns file descriptor 2 to the file assigned to file descriptor 1 (that is, .IR fname ). .PP If the order of redirection is reversed, as in .IP .CR 2>&1\01> \f2fname .PP file descriptor 2 is assigned to the file assigned to file descriptor 1 (probably the terminal) and then file descriptor 1 is assigned to file .IR fname . .PP By using the redirection operators above, the input and output of a .I coprocess may be moved to a numbered file descriptor, allowing other commands to write to them and read from them. If the input of the current coprocess is moved to a numbered file descriptor, another coprocess may be started. .PP If a command is followed by .CR & and job control is inactive, the default standard input for the command is the empty file .CR /dev/null . Otherwise, the environment for the execution of a command contains the file descriptors of the invoking shell as modified by input/output specifications. .SS Environment The .B environment (see .IR environ (5)) is a list of name-value pairs passed to an executed program much like a normal argument list. The names must be identifiers and the values are character strings. The shell interacts with the environment in several ways. When invoked, the shell scans the environment and creates a parameter for each name found, gives it the corresponding value and marks it .CR export . Executed commands inherit the environment. If the user modifies the values of these parameters or creates new ones by using the .CR export or .CR "typeset \-x" special commands, the values become part of the environment. The environment seen by any executed command is thus composed of any name-value pairs originally inherited by the shell, whose values may be modified by the current shell, plus any additions which must be noted in .CR export or .CR "typeset \-x" commands. .PP The environment for any simple command or function can be augmented by prefixing it with one or more parameter assignments. A parameter assignment argument takes the form .IC identifier = value\f1. For example, both the following .IP .CI TERM=450 "\0cmd\0args" .IP .CI "(export TERM; TERM=450;" "\0cmd\0args" ) .PP are equivalent (as far as the execution of .I cmd is concerned, except for the special commands that are preceded by a dagger (\(dg)). .PP If the .CR \-k option is set, all parameter assignment arguments are placed in the environment, even if they occur after the command name. The following echo statement prints .CR "a=b c" . After the .CR \-k option is set, the second echo statement prints only .CR c : .nf .IP .CR "echo a=b c" \0\(->\0 "a=b c" .CR "set \-k" .CR "echo a=b c" \0\(->\0 "c" .fi .PP This feature is intended for use with scripts written for early versions of the shell and its use in new scripts is strongly discouraged. It is likely to disappear someday. .SS Functions The .CR function command (described in the "Compound Commands" subsection) defines shell functions. Shell functions are read and stored internally. Alias names are resolved when the function is read. Functions are executed like commands, with the arguments passed as positional parameters. (See the "Execution" subsection.) .PP Functions execute in the same process as the caller and share all files and current working directory with the caller. Traps defined by the caller are reset to their default action inside the function. A trap condition that is not caught or ignored by the function causes the function to terminate and the condition to be passed on to the caller. A trap on .CR EXIT set inside a function is executed after the function completes in the environment of the caller. Ordinarily, variables are shared between the calling program and the function. However, the .CR typeset special command can be used within a function to define local variables whose scope includes the current function and all functions it calls. .PP The .CR return special command is used to return from function calls. Errors within functions return control to the caller. .PP Function identifiers can be listed with the .CR +f option of the .CR typeset special command. Function identifiers and the associated text of the functions can be listed with the .CR \-f option. Functions can be undefined with the .CR \-f option of the .CR unset special command. .PP Ordinarily, functions are unset when the shell executes a shell script. The .CR \-xf option of the .CR typeset command allows a function to be exported to scripts that are executed without reinvoking the shell. Functions that must be defined across separate invocations of the shell should be placed in the .CR ENV file. .SS Jobs If the .CR monitor option of the .CR set command is turned on, an interactive shell associates a .I job with each pipeline. It keeps a table of current jobs, printed by the .CR jobs command, and assigns them small integer numbers. When a job is started asynchronously with .CR & , the shell prints a line that looks like: .IP .C "[1] 1234" .PP indicating that job number 1 was started asynchronously and had one (top-level) process whose process ID was 1234. .PP If you are running a job and wish to do something else, you can type the suspend character (the .CR susp character defined with .CR stty ; see .IR stty (1)) to send a .CR SIGSTOP signal to the current job. The shell then indicates that the job has been .CR Stopped , and prints another prompt. Then you can manipulate the state of this job by putting it in the background with the .CR bg command, running other commands, and eventually returning the job to the foreground with the .CR fg command. A suspend takes effect immediately and resembles an interrupt, since pending output and unread input are discarded when the suspend is entered. .PP A job running in the background stops if it tries to read from the terminal. Background jobs normally are allowed to produce output, but can be disabled with the .CR "stty tostop" command. If the user sets this terminal option, background jobs stop when trying to produce output. .PP There are several ways to refer to jobs in the shell. A job can be referred to by the process ID of any process in the job or by one of the following: .RS .TP 20 .PD 0 .CI % number The job with the given number. .TP .CI % string Any job whose command line begins with .IR string . .TP .CI %? string Any job whose command line contains .IR string . .TP .CI %% Current job. .TP .CI %+ Equivalent to .CR %% . .TP .CR %- Previous job. .PD .RE .PP The shell learns immediately when a process changes state. It informs the user when a job is blocked and prevented from further progress, but only just before it prints a prompt. .PP When the monitor mode is on, each background job that completes triggers any trap set for .CR SIGCHLD . .PP If you try to exit from shell while jobs are stopped, you are warned with the message .CR "You have stopped jobs." You can use the .CR jobs command to identify them. If you immediately try to exit again, the shell will not warn you a second time, and the stopped jobs will be terminated. .PP If you try to leave the shell while jobs are running, you are not warned. The shell exits silently and sets the parent of the running jobs to the .CR init process (number 1). .SS Signals The .CR SIGINT and .CR SIGQUIT signals for an invoked command are ignored if the command is followed by .CR & and the .CR monitor option is off. Otherwise, signals have the values inherited by the shell from its parent, with the exception of signal .CR SIGSEGV (but see also the .CR trap special command). .SS Execution Substitutions are made each time a command is executed. .CR sh checks the command name to determine whether it matches a special command. If it does, it is executed within the current shell process. .PP Next, .CR sh checks the command name to determine whether it matches one of the user-defined functions. If it does, .CR sh saves the positional parameters, then sets them to the arguments of the function call. The positional parameter .CR 0 is unchanged. When the function completes or issues a .CR return , .CR sh restores the positional parameter list and executes any trap set on .CR EXIT within the function. The value of a function is the value of the last command executed. A function is executed in the current shell process. .PP If a command name is not a user-defined function or a special command, .CR sh creates a process and attempts to execute the command using an .CI exec * () system call (see .IR exec (2)). .PP The shell parameter .CR PATH defines the search path for the directory containing the command. Alternative directory names are separated by a colon .RC ( : ). The default path is .CR /usr/bin:\& (specifying .CR /usr/bin , and the current directory, in that order). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign, between colon delimiters, or at the end of the path list. The search path is not used if the command name contains a .CR / . Otherwise, each directory in the path is searched for an executable file. If the file has execute permissions but is not a directory or an executable object code file, it is assumed to be a script file, which is a file of data for an interpreter. If the first two characters of the script file are .CR #! , .CI exec * () expects an interpreter path name to follow. .CI exec * () then attempts to execute the specified interpreter as a separate process to read the entire script file. If a call to .CI exec * () fails, .CR sh is spawned to interpret the script file. All nonexported aliases, functions, and named parameters are removed in this case. If the shell command file does not have read permission, or if the .CR setuid and/or .CR setgid bits are set on the file, the shell executes an agent to set up the permissions and execute the shell with the shell command file passed down as an open file. A parenthesized command is also executed in a subshell without removing nonexported quantities. .SS Command Reentry The text of the last .CR HISTSIZE (default 128) commands entered from a terminal device is saved in a history file. The file .CR $HOME/.sh_history is used if the .CR HISTFILE variable is not set or writable. A shell can access the commands of all interactive shells that use the same named .CR HISTFILE . The special command .CR fc is used to list or edit a portion of this file. The portion of the file to be edited or listed can be selected by number or by giving the first character or characters of the command. A single command or range of commands can be specified. If you do not specify an editor program as an argument to .CR fc , the value of the parameter .CR FCEDIT is used. If .CR FCEDIT is not defined, .CR /usr/bin/ed is used. The edited command is printed and reexecuted upon leaving the editor. The editor name .CR \- is used to skip the editing phase and to reexecute the command. In this case, a substitution parameter of the form .IC old = new can be used to modify the command before execution. For example, if .CR r is aliased to .CR "fc \-e \-" , typing .CR "r bad=good c" reexecutes the most recent command that starts with the letter .CR c and replaces the first occurrence of the string .CR bad with the string .CR good . .SS Command Line Editing Normally, each command line typed at a terminal device is followed by a newline or return. If one of the .CR emacs , .CR gmacs , .CR vi , or .CR viraw , options is set, you can edit the command line. An editing option is automatically selected each time the .CR VISUAL or .CR EDITOR variable is assigned a value ending in one of these option names. .PP The editing features require that the user's terminal accept return without line feed and that a space ("\ ") must overwrite the current character on the screen. ADM terminal users should set the "space\ \(mi\ advance" switch to "space". Hewlett-Packard terminal users should set the straps to "bcGHxZ\ etX". .PP The editing modes enable the user to look through a window at the current line. The default window width is 80, unless the value of .CR COLUMNS is defined. If the line is longer than the window width minus two, a mark displayed at the end of the window notifies the user. The mark is one of: .RS .TP .PD 0 .CR > The line extends to the right. .TP .CR < The line extends to the left. .TP .CR * The line extends to both sides of the window. .PD .RE .PP As the cursor moves and reaches the window boundaries, the window is centered about the cursor. .PP The search commands in each edit mode provide access to the history file. Only strings are matched, not patterns, although a leading .CR ^ in the string restricts the match to begin at the first character in the line. .SS emacs Editing Mode This mode is invoked by either the .CR emacs or .CR gmacs option. Their sole difference is their handling of .CR ^T . To edit, the user moves the cursor to the point needing correction and inserts or deletes characters or words. All editing commands are control characters or escape sequences. The notation for control characters is caret .RC ( ^ ) followed by a character. For example, .CR ^F is the notation for Control-F. This is entered by holding down the Ctrl (control) key and pressing .CR f . The shift key is .I not pressed. The notation .CR ^?\& indicates the delete (DEL) key. .PP The notation for escape sequences is .CR M- followed by a character. For example, .CR M-f (pronounced .IR "meta f" ) is entered by pressing the escape key (ESC) followed by pressing .CR f . .CR M-F is the notation for escape followed by shift (capital) .CR F . .PP All edit commands operate from any place on the line (not only at the beginning). Neither the return .RC ( ^M ) nor the newline .RC ( ^J ) key is entered after edit commands, except when noted. .RS .TP 15 .PD 0 .CR ^F Move cursor forward (right) one character. .TP .CR M-f Move cursor forward one word. (The editor's idea of a word is a string of characters consisting of only letters, digits and underscores.) .TP .CR ^B Move cursor backward (left) one character. .TP .CR M-b Move cursor backward one word. .TP .CR ^A Move cursor to start of line. .TP .CR ^E Move cursor to end of line. .TP .CI ^] char Move cursor forward to character .I char on current line. .TP .CI M-^] char Move cursor backward to character .I char on current line. .TP .CI ^X^X Interchange the cursor and mark. .TP .I erase Delete previous character. (User-defined erase character as defined by the .CR stty command, usually .CR ^H or .CR # .) .TP .CR ^D Delete current character. .TP .I eof Terminate the shell if the current line is null. (User-defined end-of-file character as defined by the .CR stty command, usually .CR ^D .) .TP .CI M-d Delete current word. .TP .CI M-^H Delete previous word. (meta-backspace) .TP .CI M-h Delete previous word. .TP .CI M-^?\& Delete previous word. (meta-delete) If your interrupt character is .CR ^?\& (DEL, the default), this command will not work. .TP .CI ^T In .CR emacs mode, transpose current character with next character. In .CR gmacs mode, transpose two previous characters. .TP .CI ^C Capitalize current character. .TP .CI M-c Capitalize current word. .TP .CI M-l Change the current word to lowercase. .TP .CI ^K Delete from the cursor to the end of the line. If preceded by a numerical parameter whose value is less that the current cursor position, then delete from the given position up to the cursor. If preceded by a numerical parameter whose value is greater than the current cursor position, then delete from the cursor up to the given position. .TP .CI ^W Kill from the cursor to the mark. .TP .CI M-p Push the region from the cursor to the mark on the stack. .TP .I kill Kill the entire current line. If two kill characters are entered in succession, all subsequent consecutive kill characters cause a line feed (useful when using paper terminals). (User-defined kill character as defined by the .CR stty command, usually .CR ^X or .CR @ .) .TP .CI ^Y Restore last item removed from line. (Yank item back to the line.) .TP .CI ^L Line feed and print current line. .TP .CR ^@ Set mark. (null character) .TP .CI M-\0 Set mark. (meta-space) .TP .CI ^J Execute the current line. (newline) .TP .CI ^M Execute the current line. (return) .TP .CI ^P Fetch previous command. Each time .CR ^P is entered, the previous command in the history list is accessed. .TP .CI ^N Fetch next command. Each time .CR ^N is entered the next command in the history list is accessed. .TP .CI M-< Fetch the least recent (oldest) history line. .TP .CI M-> Fetch the most recent (youngest) history line. .TP .CI ^R string Reverse search history for a previous command line containing .IR string . If a parameter of zero is given, the search is forward. .I string is terminated by a return or newline. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is omitted, the next command line containing the most recent .I string is accessed. In this case, a parameter of zero reverses the direction of the search. .TP .CR ^O Execute the current line and fetch the next line relative to current line from the history file. .TP .CI M- digits Define a numeric parameter. The digits are taken as a parameter to the next command. The commands that accept a parameter are .IR erase , .CR ^B , .CR ^C , .CR ^D , .CR ^F , .CR ^K , .CR ^N , .CR ^P , .CR ^R , .CR ^] , .CR M-^H , .CR M-. , .CR M-_ , .CR M-b , .CR M-c , .CR M-d , .CR M-f , .CR M-h , and .CR M-l . .TP .CI M- letter Your alias list is searched for an alias by the name .CI _ letter (underscore-letter). If an alias of this name is defined, its value is inserted on the input queue. This .I letter must not be one of the above metafunctions. .TP .CR M-. The last word of the previous command is inserted on the line. If preceded by a numeric parameter, the value of this parameter determines which word to insert rather than the last word. .TP .CR M-_ Same as .CR M-. . .TP .CR M-* Attempt file name generation on the current word. .TP .CR M-^[ File name completion. (meta-escape.) Replaces the current word with the longest common prefix of all file names matching the current word with an asterisk appended. If the match is unique, a .CR / is appended if the file is a directory and a space is appended if the file is not a directory. .TP .CR M-= List files matching current word pattern as if an asterisk were appended. .TP .CR ^U Multiply parameter of next command by 4. .TP .CR \e Escape next character. Editing characters and your erase, kill, and interrupt characters may be entered in a command line or in a search string, if preceded by a .CR \e . The .CR \e removes the next character's editing features (if any). .TP .CI ^V Display version of the shell. .TP .CI M-# Insert a .CR # at the beginning of the line and execute it. This causes a comment to be inserted in the history file. .PD .RE .SS vi Editing Mode The editor starts in insert mode until an escape (ESC) is received. This puts you in control mode in which you can move the cursor and perform editing commands. A return in either mode sends the line. .PP Most control commands accept an optional repeat .I count prior to the command. .PP In .CR vi mode on most systems, canonical processing is initially enabled and the command is echoed again if the speed is 1200 baud or greater and contains any control characters, or if less than one second has elapsed since the prompt was printed. The escape (ESC) character terminates canonical processing for the remainder of the command and you can then modify the command line. This scheme has the advantages of canonical processing with the typeahead echoing of raw mode. .PP Setting the .CR viraw option always disables canonical processing on the terminal. This mode is implicit for systems that do not support two alternate end-of-line delimiters, and may be helpful for certain terminals. .PP .B Insert Edit Commands .PP By default, the editor is in insert mode. .RS .TP 15 .PD 0 .I erase Delete previous inserted character. The .IR erase character is user-definable with the .CR stty command, usually set to .CR ^H . The system default is .CR # . .TP .I kill Delete all current inserted characters. The .IR kill character is user-definable with the .CR stty command, usually set to .CR ^X or .CR ^U . The system default is .CR @ . .TP .CR \e Escape the next .I erase or .I kill character. .TP .CR ^D Terminate the shell. .TP .CR ^V Escape next character. Editing characters and erase or kill characters may be entered in a command line or in a search string if preceded by a .CR ^V , which removes the next character's editing features (if any). .TP .CR ^W Delete the previous blank-separated word. .PD .RE .PP .B Motion Edit Commands .PP These commands move the cursor. The use of .IR count causes a repetition of the command the cited number of times. .RS .TP 15 .PD 0 .RC [\f2count\f1] l Cursor forward (right) one character. .TP .RC [\f2count\f1] w Cursor forward one alphanumeric word. .TP .RC [\f2count\f1] W Cursor forward to the beginning of the next word that follows a blank. .TP .RC [\f2count\f1] e Cursor forward to the end of the word. .TP .RC [\f2count\f1] E Cursor forward to end of the current blank-delimited word. .TP .RC [\f2count\f1] h Cursor backward (left) one character. .TP .RC [\f2count\f1] b Cursor backward one word. .TP .RC [\f2count\f1] B Cursor backward to preceding blank-separated word. .TP .RC [\f2count\f1] | Cursor to column .IR count . Default is 1. .TP .RC [\f2count\f1] f \f2c Find the next character .IR c in the current line. .TP .RC [\f2count\f1] F \f2c Find the previous character .IR c in the current line. .TP .RC [\f2count\f1] t \f2c Equivalent to .CI f c followed by .CR h . .TP .RC [\f2count\f1] T \f2c Equivalent to .CI F c followed by .CR l . .TP .RC [\f2count\f1] ; Repeat the last single-character find command, .CR f , .CR F , .CR t , or .CR T . .TP .RC [\f2count\f1] , Reverses the last single character find command. .TP .CR 0 Cursor to start of line. .TP .CR ^ Cursor to first nonblank character in line. .TP .CR $ Cursor to end of line. .PD .RE .PP .B History Search Commands .PP These commands access your command history file. .RS .TP 15 .PD 0 .RC [\f2count\f1] k Fetch previous command. Each time .CR k is entered, the next earlier command in the history list is accessed. .TP .RC [\f2count\f1] \- Equivalent to .CR k . .TP .RC [\f2count\f1] j Fetch next command. Each time .CR j is entered, the next later command in the history list is accessed. .TP .RC [\f2count\f1] + Equivalent to .CR j . .TP .RC [\f2count\f1] G The command number .I count is fetched. The default is the first command in the history list. .TP .CI / string Search backward through history for a previous command containing .IR string . .I string is terminated by a return or newline. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is null, the previous string is used. .TP .CI ? string Same as .CR / , but search in the forward direction. .TP .CR n Search for next match of the last pattern to the .CR / or .CR ? commands. .TP .CR N Search for next match of the last pattern to .CR / or .CR ? , but in reverse direction. .PD .RE .PP .B Text Modification Edit Commands .PP These commands will modify the line. .RS .TP 15 .PD 0 .CR a Enter insert mode after the current character. .TP .CR A Append text to the end of the line. Equivalent to .CR $a . .TP .RC [\f2count\f1] c \f2motion .TP .CR c [\f2count\f1]\f2motion Move cursor forward to the character position specified by .IR motion , deleting all characters between the original cursor position and the new position, and enter insert mode. If .I motion is .CR c , the entire line is deleted. .TP .CR C Delete from the current character through the end of line and enter insert mode. Equivalent to .CR c$ . .TP .CR S Equivalent to .CR cc . .TP .RC [\f2count\f1] d \f2motion .TP .CR d [\f2count\f1]\f2motion Move cursor to the character position specified by .IR motion , deleting all characters between the original cursor position and the new position. If .I motion is .CR d , the entire line will be deleted. .TP .CR D Delete from the current character through the end of line. Equivalent to .CR d$ . .TP .CR i Enter insert mode before the current character. .TP .CR I Enter insert mode before the beginning of the line. Equivalent to the two-character sequence .CR 0i . .TP .RC [\f2count\f1] P Insert the previous text modification before the cursor. .TP .RC [\f2count\f1] p Insert the previous text modification after the cursor. .TP .CR R Enter insert mode and replace characters on the screen with characters you type, overlay fashion. .TP .RC [\f2count\f1] r \f2c Replace the current character with .IR c . .TP .RC [\f2count\f1] x Delete the current character. .TP .RC [\f2count\f1] X Delete the preceding character. .TP .RC [\f2count\f1] . Repeat the previous text modification command. .TP .CR ~ Invert the case of the current character and advance the cursor. .TP .RC [\f2count\f1] _ Append the .I count word of the previous command at the current cursor location and enter insert mode at the end of the appended text. The last word is used if .I count is omitted. .TP .CR * Append an .CR * to the current word and attempt file name generation. If no match is found, ring the bell. If a match is found, replace the word with the matching string of file names and enter insert mode. .TP escape .TP .CR \e Attempt file name completion on the current word. Replace the current word with the longest common prefix of all file names matching the current word with an asterisk appended. If the match is unique, append a .CR / if the file is a directory or append a space if the file is not a directory. .PD .RE .PP .B Other Edit Commands .PP .RS .TP 15 .PD 0 .RC [\f2count\f1] y \f2motion .TP .CR y [\f2count\f1]\f2motion Yank current character through character that .I motion would move the cursor to and put them into the delete buffer. The text and cursor are unchanged. .TP .CR Y Yank from current position to end of line. Equivalent to .CR y$ . .TP .CR u Undo the last text-modifying command. .TP .CR U Undo all the text-modifying commands performed on the line. .TP .RC [\f2count\f1] v Execute the command .CI "fc \-e ${VISUAL:-${EDITOR:-vi}}" " count" in the input buffer. If .I count is omitted, the current line is used. This executes an editor with the current line as the input "file". When you exit from the editor, the result is executed. .TP .CR ^L Line feed and print current line. .TP .CR ^J Execute the current line, regardless of mode. (newline) .TP .CR ^M Execute the current line, regardless of mode. (return) .TP .CR # Insert a .CR # at the beginning of the current line and after each embedded newline, and execute the line. Useful for inserting the current command line in the history list without executing it. .TP .CR = List the file names that match the current word if an asterisk were appended to it. .TP .CI @ letter Search your alias list for an alias with the name .CI _ letter (underscore letter). If an alias of this name is defined, its value is executed as a command sequence on the current line. This provides a simple macro capability. .PD .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. If it is not defined or is empty, it defaults to the value of .CR LANG . .PP .CR LC_CTYPE determines the classification of characters as letters, and the characters matched by character class expressions in pattern matching notation. If it is not defined or is empty, it defaults to the value of .CR LANG . .PP If .CR LANG is not defined or is empty, it defaults to .CR C (see .IR lang (5)). .PP If any internationalization variable contains an invalid value, they all default to .CR C (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH RETURN VALUE Errors detected by the shell, such as syntax errors, cause the shell to return a nonzero exit status. Otherwise, the shell returns the exit status of the last command executed. See also the .CR exit special command. If the shell is being used noninteractively, the execution of the shell file is abandoned. Runtime errors detected by the shell are reported by printing the command or function name and the error condition. If the line number on which the error occurred is greater than one, the line number is also printed in brackets .RC ( [] ) after the command or function name. .\".SH EXAMPLES .\" none appropriate. .SH WARNINGS .PP .\" File descriptors 54 through 60 are used internally by the POSIX shell. File descriptors 24 through 30 are used internally by the POSIX shell. Applications using these and forking a subshell should not depend upon them surviving in the subshell or its descendants. .PP If a command that is a tracked alias is executed, and a command with the same name is installed in a directory in the search path before the directory where the original command was found, the shell will continue to load and execute the original command. Use the .CR \-t option of the .CR alias command to correct this situation. .PP If you move the current directory or one above it, .CR pwd may not give the correct response. Use the .CR cd command with a full path name to correct this situation. .PP Some very old shell scripts use a caret .RC ( ^ ) as a synonym for the pipe character .RC ( | ). .CR sh .I "does not" recognize the caret as a pipe character. .PP If a command is piped into a shell command, all variables set in the shell command are lost when the command completes. .PP Using the .CR fc built-in command within a compound command will cause the entire command to disappear from the history file. .PP The dot .RC ( . ) special command, as in .CI .\& " file\f1," reads the entire file before any commands are executed. Therefore, .CR alias and .CR unalias commands in the file will not apply to any functions defined in the file. .PP Traps are not processed while the shell is waiting for a foreground job. Thus, a trap on .CR SIGCHLD is not executed until the foreground job terminates. .PP The .CR export special command does not handle arrays properly. Only the first element of an array is exported to the environment. .PP Background processes started from a noninteractive shell cannot be accessed with job control commands. .PP The value of the .CR IFS variable in the user's environment affects the behavior of scripts. .SS Collating Order In an international environment, character ordering is determined by the value of .CR LC_COLLATE , rather than by the binary ordering of character values in the machine collating sequence. This brings with it certain attendant dangers, particularly when using range expressions in file name generation patterns. For example, the command, .IP .C "rm [a-z]*" .PP might be expected to match all file names beginning with a lowercase alphabetic character. However, if dictionary ordering is specified by .CR LC_COLLATE , it would also match file names beginning with an uppercase character (as well as those beginning with accented letters). Conversely, it would fail to match letters collated after .CR z in languages such as Danish or Norwegian. .PP The correct (and safe) way to match specific character classes in an international environment is to use a pattern (see .IR regexp (5)) of the form: .IP .C "rm [[:lower:]]*" .PP This uses .CR LC_CTYPE to determine character classes and works predictably for all supported languages and codesets. For shell scripts produced on noninternationalized systems (or without consideration for the above dangers), it is recommended that they be executed in a non-NLS environment. This requires that .CR LANG , .CR LC_COLLATE , and so on, be set to .CR C or not set at all. .SS History File Changes At HP-UX release B.10.10, the history file has a new internal magic number. This will cause a pre-B.10.10 history file to be discarded. Users who use multiple versions of HP-UX that NFS-mount the same directory that contains the history file (usually the home directory) may want to create a separate history file for each HP-UX version by setting the .CR HISTFILE parameter as: .IP .C "HISTFILE=$HOME/.sh_hist_$(uname \-r)" .PP Users on windowing systems may want to have separate history files for each window by setting the HISTFILE parameter as follows: .IP .C "HISTFILE=$HOME/.sh_hist$$" .PP A .CR cron job may be used to delete old history files. .PP The history file does not support mixing of locales in the same file. For users of multiple locales, you can assign a unique history file for each locale by setting .CR HISTFILE as: .IP .C "HISTFILE=$HOME/.sh_hist_${LANG}" .PP or include the process number in the .CR HISTFILE parameter as shown above. .SH AUTHOR .CR sh was developed by AT&T, OSF, and HP. .SH FILES .TP 30 .PD 0 .CR $HOME/.profile Read to set up user's custom environment .TP .CR /etc/passwd To find home directories .TP .CR /etc/profile Read to set up system environment .TP .CR /etc/suid_profile Security profile .TP .CR /tmp/sh* For here-documents .TP .CR /usr/bin/sh Shell executable program location .PD .SH SEE ALSO cat(1), cd(1), command(1), echo(1), ed(1), env(1), getopts(1), kill(1), ln(1), login(1), newgrp(1), printf(1), pwd(1), read(1), stty(1), test(1), time(1), umask(1), vi(1), dup(2), exec(2), fork(2), pipe(2), stty(2), ulimit(2), umask(2), wait(2), rand(3C), a.out(4), profile(4), environ(5), lang(5), regexp(5), signal(5). .SH STANDARDS CONFORMANCE .CR sh ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR . ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR : ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR break ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR case ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR continue ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR eval ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR exec ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR exit ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR export ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR for ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR if ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR read ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR return ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR set ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR shift ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR time ": SVID2, SVID3, XPG2, XPG3, XPG4" .br .CR trap ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR unset ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR until ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR while ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4sh\f1 \- shell based on POSIX.2@@@\f3sh-posix(1)\f1 .\" index@\f4alias\f1 \- substitute command and/or file name@@@\f3sh-posix(1)\f1 .\" index@\f4break\f1 \- exit from enclosing for/next loop@@@\f3sh-posix(1)\f1 .\" index@\f4case\f1 \- execute \f2list\f1 associated with \f2pattern\f1 that matches \f2word\f1@@@\f3sh-posix(1)\f1 .\" index@\f4cd\f1 \- change working directory@@@\f3sh-posix(1)\f1 .\" index@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@\f3sh-posix(1)\f1 .\" index@\f4echo\f1 \- echo (print) arguments@@@\f3sh-posix(1)\f1 .\" index@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@\f3sh-posix(1)\f1 .\" index@\f4exec\f1 \- execute command without creating new process@@@\f3sh-posix(1)\f1 .\" index@\f4exit\f1 \- exit shell with exit status@@@\f3sh-posix(1)\f1 .\" index@\f4export\f1 \- export variable names to environment of subsequent commands@@@\f3sh-posix(1)\f1 .\" index@\f4fc\f1 \- edit and execute previous command@@@\f3sh-posix(1)\f1 .\" index@\f4for\f1 \- execute a do list@@@\f3sh-posix(1)\f1 .\" index@\f4if\f1 \- execute command if previous command returns exit status 0@@@\f3sh-posix(1)\f1 .\" index@\f4jobs\f1 \- list active jobs@@@\f3sh-posix(1)\f1 .\" index@\f4kill\f1 \- terminate job or process@@@\f3sh-posix(1)\f1 .\" index@\f4let\f1 \- evaluate arithmetic expression@@@\f3sh-posix(1)\f1 .\" index@\f4newgrp\f1 \- equivalent to \f4exec newgrp\f1@@@\f3sh-posix(1)\f1 .\" index@\f4print\f1 \- output from shell@@@\f3sh-posix(1)\f1 .\" index@\f4pwd\f1 \- print current working directory@@@\f3sh-posix(1)\f1 .\" index@\f4read\f1 \- input and parse a line@@@\f3sh-posix(1)\f1 .\" index@\f4readonly\f1 \- mark names as unredefinable@@@\f3sh-posix(1)\f1 .\" index@\f4return\f1 \- shell function return to invoking script@@@\f3sh-posix(1)\f1 .\" index@\f4set\f1 \- set/define options and arguments@@@\f3sh-posix(1)\f1 .\" index@\f4shift\f1 \- shift \f2argv\f1 members one position to left@@@\f3sh-posix(1)\f1 .\" index@\f4test\f1 \- evaluate conditional expression@@@\f3sh-posix(1)\f1 .\" index@\f4time\f1, \f4times\f1 \- print summary of time used by processes@@@\f3sh-posix(1)\f1 .\" index@\f4trap\f1 \- trap specified signal@@@\f3sh-posix(1)\f1 .\" index@\f4typeset\f1 \- control leading blanks and parameter handling@@@\f3sh-posix(1)\f1 .\" index@\f4ulimit\f1 \- set size or time limits@@@\f3sh-posix(1)\f1 .\" index@\f4umask\f1 \- set permissions mask for creating new files@@@\f3sh-posix(1)\f1 .\" index@\f4unalias\f1 \- discard specified alias@@@\f3sh-posix(1)\f1 .\" index@\f4unset\f1 \- remove definition/setting of options and arguments@@@\f3sh-posix(1)\f1 .\" index@\f4until\f1 \- execute commands until expression is nonzero@@@\f3sh-posix(1)\f1 .\" index@\f4wait\f1 \- wait for child process@@@\f3sh-posix(1)\f1 .\" index@\f4whence\f1 \- define interpretation of name as a command@@@\f3sh-posix(1)\f1 .\" index@\f4while\f1 \- execute commands while expression is nonzero@@@\f3sh-posix(1)\f1 .\" .\" toc@\f3sh-posix(1)\f1:\0\0\f4sh\f1@@@shell, the standard/restricted command programming language .\" toc@\f4case\f1 \- label in a switch statement@@@see \f3sh-posix(1)\f1 .\" toc@\f4alias\f1 \- substitute command and/or file name@@@see \f3sh-posix(1)\f1 .\" toc@\f4break\f1 \- exit from enclosing for/next loop@@@see \f3sh-posix(1)\f1 .\" toc@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@see \f3sh-posix(1)\f1 .\" toc@\f4cd\f1 \- change working directory@@@see \f3sh-posix(1)\f1 .\" toc@\f4echo\f1 \- echo (print) arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@see \f3sh-posix(1)\f1 .\" toc@\f4exec\f1 \- execute command without creating new process@@@see \f3sh-posix(1)\f1 .\" toc@\f4exit\f1 \- exit shell with exit status@@@see \f3sh-posix(1)\f1 .\" toc@\f4export\f1 \- export variable names to environment of subsequent commands@@@see \f3sh-posix(1)\f1 .\" toc@\f4fc\f1 \- edit and execute previous command@@@see \f3sh-posix(1)\f1 .\" toc@\f4for\f1 \- execute a do list@@@see \f3sh-posix(1)\f1 .\" toc@\f4if\f1 \- execute command if previous command returns exit status 0@@@see \f3sh-posix(1)\f1 .\" toc@\f4jobs\f1 \- list active jobs@@@see \f3sh-posix(1)\f1 .\" toc@\f4kill\f1 \- terminate job or process@@@see \f3sh-posix(1)\f1 .\" toc@\f4let\f1 \- evaluate arithmetic expression@@@see \f3sh-posix(1)\f1 .\" toc@\f4newgrp\f1 \- equivalent to \f2exec newgrp\f1@@@see \f3sh-posix(1)\f1 .\" toc@\f4print\f1 \- output from shell@@@see \f3sh-posix(1)\f1 .\" toc@\f4pwd\f1 \- print current working directory@@@see \f3sh-posix(1)\f1 .\" toc@\f4read\f1 \- input and parse a line@@@see \f3sh-posix(1)\f1 .\" toc@\f4readonly\f1 \- mark names as unredefinable@@@see \f3sh-posix(1)\f1 .\" toc@\f4return\f1 \- shell function return to invoking script@@@see \f3sh-posix(1)\f1 .\" toc@\f4set\f1 \- set/define options and arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4shift\f1 \- shift \f2argv\f1 members one position to left@@@see \f3sh-posix(1)\f1 .\" toc@\f4test\f1 \- evaluate conditional expression@@@see \f3sh-posix(1)\f1 .\" toc@\f4trap\f1 \- trap specified signal@@@see \f3sh-posix(1)\f1 .\" toc@\f4time, times\f1 \- print summary of time used by processes@@@see \f3sh-posix(1)\f1 .\" toc@\f4typeset\f1 \- control leading blanks and parameter handling@@@see \f3sh-posix(1)\f1 .\" toc@\f4ulimit\f1 \- set size or time limits@@@see \f3sh-posix(1)\f1 .\" toc@\f4umask\f1 \- set permissions mask for creating new files@@@see \f3sh-posix(1)\f1 .\" toc@\f4unalias\f1 \- discard specified alias@@@see \f3sh-posix(1)\f1 .\" toc@\f4unset\f1 \- remove definition/setting of options and arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4wait\f1 \- wait for child process@@@see \f3sh-posix(1)\f1 .\" toc@\f4whence\f1 \- define interpretation of name as a command@@@see \f3sh-posix(1)\f1 .\" toc@\f4while\f1 \- execute commands while expression is nonzero@@@see \f3sh-posix(1)\f1 .\" toc@\f4until\f1 \- execute commands until expression is nonzero@@@see \f3sh-posix(1)\f1 .\" .\" links@sh-posix.1 alias.1 .\" links@sh-posix.1 bg.1 .\" links@sh-posix.1 fc.1 .\" links@sh-posix.1 fg.1 .\" links@sh-posix.1 jobs.1 .\" links@sh-posix.1 unalias.1 .\" $Header: New Manpage $ .TA a .TH answer 1 .SH NAME answer \- phone message transcription system .SH SYNOPSIS .CR answer .RC [ \-pu ] .SH DESCRIPTION The .CR answer interactive program helps you to transcribe telephone (and other) messages into electronic mail. .PP The program uses your personal .CR elm alias database and the system .CR elm alias database, allowing you to use aliases to address the messages. .SS Options .CR answer supports the following options: .RS .TP .CR \-p Prompt for phone-slip-type message fields. .TP .CR \-u Allow addresses that are not aliases. .RE .SS Operation .CR answer begins with the .CR "Message\ to:\&" prompt. Enter a one-word alias or a two-word user name ("Words" are separated by spaces.) The user name is converted to an alias in the form .IC f _ lastword\f1, where .I f is the first character of the first word, .I lastword is the second word, and all letters are shifted to lowercase. For example, .CR Dave " \&" Smith is converted to the alias .CR d_smith . .PP Without the .CR \-u option, the specified or converted alias must exist in the alias databases. With the .CR \-u option, if the processed "alias" is not in the alias databases, it is used for the address as is. .PP The fully expanded address is displayed. .PP With the .CR \-p option, you are asked for typical message slip data: .RS .nf .PP .C "Caller: " .C "of: " .C "Phone: " .C " " .C "TELEPHONED - " .C "CALLED TO SEE YOU - " .C "WANTS TO SEE YOU - " .C "RETURNED YOUR CALL - " .C "PLEASE CALL - " .C "WILL CALL AGAIN - " .C "*****URGENT****** -" .fi .RE .PP Enter the appropriate data. You can put just an .CR X or nothing after the pertinent dash prompts, or you can type longer comments. Whatever you enter becomes part of the message. Lines with no added text are omitted from the message. .PP Finally, you are prompted for a message. Enter a message, if any, ending with a blank line. The message is sent and the .CR "Message\ to:\&" prompt is repeated. .PP To end the program, enter any one of .CR bye , .CR done , .CR exit , or .CR quit , at the .CR "Message\ to:\&" prompt. .SH EXAMPLES User input is in normal type. .SS With No Options This example shows a valid alias, an invalid user name, and a valid user name. In the invalid case, the converted alias is displayed in square brackets. .RS .nf .PP .CR "-----------------------------------------------------------------" .CR "" .CR "Message to:\& " oswald .CR "address 'oswaldr@mycompany.com (Oswald Rarebit)'" .CR "" .CR "Enter message for oswald ending with a blank line." .CR "" .CR "> " "And here is the message." .CR "> " .CR "" .CR "-----------------------------------------------------------------" .CR "" .CR "Message to:\& " "albert einstein" .CR "Sorry, could not find 'albert einstein' [a_einstein] in list!" .CR "" .CR "Message to:\& " "john jones" .CR "address 'mrjones@companybee.com (John P. Jones)'" .CR "" .CR "Enter message for john jones ending with a blank line." .CR "" .CR "> " "A nice message" .CR "> " .CR "" .CR "-----------------------------------------------------------------" .CR "" .CR "Message to:\& " "quit" .fi .RE .SS With the -u Option If you enter .CR "answer \-u" , the previous error is treated differently. .RS .nf .PP .CR "-----------------------------------------------------------------" .CR "" .CR "Message to:\& " "albert einstein" .CR "address 'a_einstein'" .CR "" .CR "Enter message for albert einstein ending with a blank line." .CR "" .CR "> " "About your theory ..." .CR "> " .fi .RE .SS With the -p Option If you enter .CR "answer \-p" , the phone-slip prompts are added. The three lines with no added text are deleted from the message. .RS .nf .PP .CR "-----------------------------------------------------------------" .CR "" .CR "Message to:\& " "George Dancer" .CR "address 'g_dancer@cup.hp.com (George B. Dancer)'" .CR "" .CR "Caller:\& " "Harold Maudlin" .CR "of:\& " "Terpsichore Inc." .CR "Phone:\& " "123 456 7890" .CR "" .CR "TELEPHONED - " "at 4:30pm" .CR "CALLED TO SEE YOU - " .CR "WANTS TO SEE YOU - " "X" .CR "RETURNED YOUR CALL - " .CR "PLEASE CALL - " "X" .CR "WILL CALL AGAIN - " .CR "*****URGENT****** - " "very very!" .CR "" .CR "Enter message for George Dancer ending with a blank line." .CR "" .CR "> " "He said that you would ..." .CR "> " .fi .RE .SH FILES .if t .TP 40 .if n .TP 30 .PD 0 .C $HOME/.elm/aliases User alias database data table .TP .C $HOME/.elm/aliases.dir User alias database directory table .TP .C $HOME/.elm/aliases.pag User alias database hash table .TP .C $HOME/.elm/aliases.text User alias source text .TP .CR /var/mail/.elm/aliases System alias database data table .TP .CR /var/mail/.elm/aliases.dir System alias database directory table .TP .CR /var/mail/.elm/aliases.pag System alias database hash table .TP .CR /var/mail/.elm/aliases.text System alias source text .TP .CI /tmp/snd. pid Outbound mail message edit buffer .PD .SH AUTHOR .CR answer was developed by HP. .SH SEE ALSO elm(1), newalias(1). .\" .\" toc@\f3answer(1)\f1:\0\0\f4answer\f1@@@phone message transcription system .\" index@\f4answer\f1 \- phone message transcription system@@@\f3answer(1)\f1 .\" index@\f1phone message transcription system@@@\f3answer(1)\f1 .\" index@\f1message transcription system@@@\f3answer(1)\f1 .\" index@\f1transcription system@@@\f3answer(1)\f1 .\" $Header: ar.1,v 76.2 95/08/01 15:51:47 ssa Exp $ .TA a .TH ar 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ar \- create and maintain portable archives and libraries .SH SYNOPSIS .C ar .RC [\-]\c .IR key .RC [\-]\c .RI [ modifier \0...]\c .RI \ [ posname ] .I afile .RI [ name \0...] .SH DESCRIPTION The .CR ar command maintains groups of files combined into a single archive file. Its main use is to create and update library files as used by the link editor (see .IR ld (1)). It can be used, however, for any similar purpose. The magic string and file headers used by .CR ar consist of printable ASCII characters. If an archive is composed of printable files, the entire archive is printable. .PP Individual files are inserted without conversion into the archive file. When .CR ar creates an archive, it creates headers in a format that is portable across all machines. See .IR ar (4) for a detailed description of the portable archive format and structure. The archive symbol table (described in .IR ar (4)) is used by the link editor to search repeatedly and efficiently through libraries of object files. An archive symbol table is created and maintained by .CR ar only when the archive contains at least one object file. The archive symbol table is in a specially named file that is always the first file in the archive. This file is never mentioned or accessible to the user. Whenever .CR ar is used to create or update the contents of an archive, the symbol table is rebuilt (unless the .CR z modifier is used). The .CR s modifier described below forces the symbol table to be rebuilt. .PP One .I key operation character from the set, .CR drqtpmx , is required and can be optionally preceded by a hyphen (\c .CR \- ). The required .I key operation character can be specified with one or more .I modifier characters from the set .CR abcfFilsuvzACT . .I posname is used with the .CR r and .CR m key operations and the .CR a , .CR b , and .CR i modifiers to specify a position in the archive. .I afile is the archive file. Constituent files in the archive file are specified by .I name arguments. .PP The following list describes the .I key operation characters: .RS .TP .CR d Delete the named files from the archive file. .TP .CR r Replace the named files, or add a new file to the archive: .RS .TP 3 \(bu If the .CR u modifier is used with the operation character .CR r , only those files with modification dates later than those of the corresponding member files are replaced. .TP \(bu If an optional positioning character from the set .CR abi is used, the .I posname argument must be present and specifies that new files are to be placed after .RC ( a ) or before .RC ( b or .CR i ) .IR posname . In the absence of a positioning character, new files are placed at the end. .TP \(bu .CR ar creates .I afile if it does not already exist. .TP \(bu If no .I name is specified and: .RS .TP 3 \(bu the specified archive file does not exist, .CR ar creates an empty archive file containing only the archive header (see .IR ar (4)). .TP \(bu the archive contains one or more files whose names match names in the current directory, each matching archive file is replaced by the corresponding local file without considering which file may be newer unless the .CR u modifier is also specified. .RE .RE .TP .CR q Quickly append the named files to the end of the archive file. Positioning characters are invalid. The operation does not check to determine whether the added members are already in the archive. .CR ar creates .I afile if it does not already exist. .TP .CR t Print a table of contents of the archive file to the standard output. If no names are given, all files in the archive are described. If names are given, information about only those files appears. .TP .CR p Print the named files in the archive to the standard output. If no names are specified, the contents of all files are printed in the order that they appear in the archive. .TP .CR m Move the named files. By default, the files are moved to the end of the archive. If a positioning character is present, the .I posname argument must be present and, as in the .CR r operation, .I posname specifies where the files are to be moved. Note that, when used with a positioning character, the files are moved in the same order that they currently appear in the archive, .I not in the order specified on the command line. See EXAMPLES. .TP .CR x Extract the named files. If no names are given, all files in the archive are extracted. In neither case does .CR x alter entries from the archive file. .RE .PP The following list describes the optional .I modifier characters: .RS .TP .CR a Position the files after the existing positioning file specified by .I posname . .TP .CR b Place the new files before the existing positioning file specified by .I posname . .TP .CR c Suppress the message normally produced when .I afile is created. For .CR r and .CR q operations, .CR ar normally creates .I afile if it does not already exist. .TP .CR f Truncate the named file names to 14 bytes before performing operations on an archive. This modifier has been provided for compatibility with previous releases where file names up to a maximum of 14 bytes were supported. Longer file names were truncated. When used with the .CR r operation, the first existing file that matches the truncated file name is replaced. The .CR f modifier can also be used with other operations to allow the full file names to be specified, rather than the truncated file names. Also see the description of the .CR F modifier. .TP .CR i Place the new files before the existing positioning file specified by .I posname . Identical to the .CR b modifier. .TP .CR l Place temporary files in the local current working directory rather than in the directory specified by the environment variable .CR TMPDIR or in the default directory .CR /var/tmp . Only the .CR d , .CR m , .CR q , and .CR r operations and the .CR s and .CR F modifiers use temporary files. .TP .CR s Regenerate the archive symbol table even if .CR ar is not invoked with an operation that modifies the archive contents. This modifier is useful for restoring the archive symbol table after the .CR strip command has been used on the archive (see .IR strip (1)) or after the archive has been modified using the .CR z modifier. .TP .CR u Update the archive. .RC ( r operations only) Do not copy the local file to the archive unless the local file is newer than the corresponding existing file in the archive. .TP .CR v Give a verbose file-by-file description of the creation or modification of an archive file to the standard output. When used with .CR t , .CR v gives a long listing of all information about the files. When used with the .CR d , .CR m , .CR p , .CR q , or .CR x operations, the verbose modifier causes .CR ar to print each .I key operation character and the file name associated with that operation. For the .CR r operation, .CR ar shows an .CR a if it adds a new file or an .CR r if it replaces an existing one. For the .CR p operation, .CR ar prints the name of the file to the standard output before the contents of the file are printed. .TP .CR z Suppress the rebuilding of the symbol table when the archive is modified. This modifier is useful only to avoid long build times when creating a large archive piece-by-piece. If an existing archive contains a symbol table, the .CR z modifier will cause it to be invalidated. If a file name longer than 15 bytes is given the entire archive is rewritten. To rebuild the symbol table, either use the .CR ranlib command (see .IR ranlib (1)), or invoke .CR ar again with the .CR s modifier. .TP .CR A Suppress warning messages regarding optional access control list entries. .CR ar does not archive optional access control list entries in a file's access control list (see .IR acl (5)). Normally, a warning message is printed for each file having optional access control list entries. .TP .CR C Prevent extracted files from replacing files with the same name. The .CR C modifier can only be used with the .CR x operation. .TP .CR F Truncate the entire archive. The .CR F modifier causes the entire archive to be rewritten such that all file names within the archive are truncated to 14 bytes, even when .CR ar does not modify the archive contents. The long name table will be removed (see .IR ar (4)). This modifier has been provided for compatibility with previous releases where file names up to a maximum of 14 bytes were supported. Also see the description of the .CR f modifier. .TP .CR T Truncate file names whose archive names are longer than those supported by the file system. By default, files with names longer than those supported by the file system will not be extracted and will cause an error. The .CR T modifier can only be used with the .CR x operation. .RE .PP Only the following combinations are meaningful; no other combination of modifiers with operations have any effect on the operation: .RS .TP .CR d : .CR v , .CR f , .CR F , .CR l .PD 0 .TP .CR m : .CR v , .CR f , .CR F , .CR l , and .CR a " | " b " | " i .TP .CR r : .CR v , .CR f , .CR F , .CR l , .CR c , .CR A , .CR u , and .CR a " | " b " | " i .TP .CR q : .CR v , .CR f , .CR F , .CR l , .CR c , .CR A , .CR z .TP .CR t : .CR v , .CR f , .CR F , .CR s .TP .CR p : .CR v , .CR f , .CR F , .CR s .TP .CR x : .CR v , .CR f , .CR F , .CR s , .CR C , .CR T .PD .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .PP The following internationalization variables affect the execution of .CR ar : .PP .CR LANG .RS Determines the locale category for native language, local customs and coded character set in the absence of .CR LC_ALL and other .CR LC_* environment variables. If .CR LANG is not specified or is set to the empty string, a default of .CR C (see .IR lang (5)) is used instead of .CR LANG . .RE .PP .CR LC_ALL .RS Determines the values for all locale categories and has precedence over .CR LANG and other .CR LC_* environment variables. .RE .PP .CR LC_CTYPE .RS Determines the locale category for character handling functions. .RE .PP .CR LC_MESSAGES .RS Determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error. .RE .PP .CR LC_NUMERIC .RS Determines the locale category for numeric formatting. .RE .PP .CR LC_TIME .RS Determines the format and contents of date and time formatting. .RE .PP .CR NLSPATH .RS Determines the location of message catalogues for the processing of .CR LC_MESSAGES . .RE .PP If any internationalization variable contains an invalid setting, .CR ar behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .PP In addition, the following environment variable affects .CR ar : .PP .CR TMPDIR .RS Specifies a directory for temporary files (see .IR tmpnam (3S)). The .CR l modifier overrides the .CR TMPDIR variable, and .CR TMPDIR overrides .CR /var/tmp\c , the default directory. .RE .SH DIAGNOSTICS .TP 15 .CI "phase error on " "file name" The named file was modified by another process while .CR ar was copying it into the archive. When this happens, .CR ar exits and the original archive is left untouched. .TP .CR "ar write error: " "file system error message" .CR ar could not write to a temporary file or the final output file. If .CR ar was trying to write the final output file, the original archive is lost. .PP .CR ar reports .CR "cannot create" .IC file .a\c , where .IC file .a is an .CR ar \-format archive file, even if .IC file .a already exists. This message is triggered when .IC file .a is write-protected or inaccessible. .SH EXAMPLES Create a new file (if one does not already exist) in archive format with its constituents entered in the order indicated: .IP .C "ar r newlib.a f3 f2 f1 f4" .PP Replace files .CR f2 and .CR f3 such that the new copies follow file .CR f1 , and .CR f3 follows .CR f2 : .IP .C "ar ma f1 newlib.a f2 f3" .br .C "ar ma f2 newlib.a f3" .br .C "ar r newlib.a f2 f3" .PP The archive is then ordered: .IP .C "newlib.a: f1 f2' f3' f4" .PP where the single quote marks indicate updated files. The first command says "move .CR f2 and .CR f3 after .CR f1 in .IR newlib .a\c \&", thus creating the order: .IP .C "f1 f3 f2 f4" .PP Note that the relative order of .CR f2 and .CR f3 has not changed. The second command says "move .CR f3 after .CR f2 in .IR newlib.a\c \&", creating the order: .IP .C "f1 f2 f3 f4" .PP The third command then replaces files .CR f2 and .CR f3 . Since files .CR f2 and .CR f3 both already existed in the archive, this sequence of commands could not be simply replaced by: .IP .C "ar ra f1 newlib.a f2 f3" .PP because the previous position and relative order of .CR f2 and .CR f3 in the archive are preserved (no matter how the files are specified on the command line), producing the following archive: .IP .C "newlib.a: f3' f2' f1 f4" .SH WARNINGS If you are a user who has appropriate privileges, .CR ar can alter any archive file, even if it is write-protected. .PP If the same file is mentioned twice in an argument list, it might be put in the archive twice. .PP If multiple copies of a file exist in an archive, .CR ar matches the first occurrence of the file in the archive. .PP .CR ar automatically creates an archive symbol table, a task performed in early HP-UX versions by .CR ranlib . Use of the .CR z modifier either suppresses generation of the symbol table, or invalidates it if it exists. The .CR ranlib command can be used to rebuild the symbol table if an archive was built with the .CR z modifier. .\".SH DEPENDENCIES .\".SS Series 700/800 .\"The .\".CR \-A .\"optional modifier is not supported. .SH FILES .TP 25 .CR /var/tmp/ar* Temporary files .SH SEE ALSO .PD .SS System Tools: .TP 18 .IR ld(1) Invoke the link editor .PD .SS Miscellaneous: .TP 18 .IR acl(5) Access control lists .PD 0 .TP .IR a.out(4) Assembler, compiler, and linker output .TP .IR ar(4) Archive format .TP .IR lorder(1) Find the ordering relation for object files or archive libraries .TP .IR ranlib(1) Regenerate an archive symbol table .TP .IR strip(1) Strip symbol and line number information from an object file .TP .IR tmpnam(3S) Create a name for a temporary file .PD .SH STANDARDS CONFORMANCE .CR ar ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4ar\f1 \- archive and library maintainer for portable archives@@@\f3ar(1)\f1 .\" index@archive and library maintainer for portable archives@@@\f3ar(1)\f1 .\" index@portable archives, library and archive maintainer for@@@\f3ar(1)\f1 .\" index@maintainer, archive and library, for portable archives@@@\f3ar(1)\f1 .\" .\" toc@\f3ar(1)\f1:\0\0\f4ar\f1@@@maintain portable archives and libraries .\" $Header: as.1,v 78.1 96/02/12 13:29:24 ssa Exp $ .TA a .TH as 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME as \- assembler (Precision Architecture) .SH SYNOPSIS .CR as .RI [\|[ option ]...\& .RI [ file ]\0...\0]... .SH DESCRIPTION The .CR as command assembles source text from files or standard input and produces a relocatable object file suitable for the link editor, .CR ld (see .IR ld (1). .PP Source text is read from standard input only if no .I file argument is given. Standard input cannot be a device file, such as a terminal. The .I option and .I file arguments can be intermingled on the command line. Every specified .IR option applies to every specified .IR file , or standard input. The source files are concatenated to form a single input stream. .PP If the .CI -o " objfile" option is not specified, the .CR .s suffix (if any) is stripped from the end of the last source file name and .CR .o is appended to the name to form the name of the default object code output file. .PP .CR as output is not optimized. .CR as creates a relocatable object file that must be processed by .CR ld before it can be successfully executed (see .IR ld (1)). .PP The .CR cc compiler normally runs the C preprocessor .CR cpp (see .IR cpp (1)), then invokes .CR as to assemble the .CR .s files together with .CR /usr/lib/pcc_prefix.s , and subsequently invokes .CR ld . .SS Arguments .CR as recognizes the following arguments. .RS .TP 17 .IR file A text file contain assembler source code. .TP .I option An option described below in Options. .RE .SS Options .CR as recognizes the following values for the .IR option argument. .RS .TP 17 .CR -e Permit an unlimited number of errors to be tolerated before the assembly process is abandoned. By default, one hundred errors are allowed before the assembler aborts. .TP .CR -f Set the default value for the .CR .CALLINFO directive to .CR CALLS , The normal default value for a .CR .CALLINFO that omits the .CR CALLER , .CR CALLS or .CR NO_CALLS parameter is .CR NO_CALLS . .TP .CR -l Write a listing of the program to standard output after assembly. This listing shows the offsets of instructions and actual values for fields. .TP .CI -o \0objfile Name the output object file .IR objfile instead of using the default .CR .o suffix on the file name of the last .IR file specified. .TP .CI -p \0number Set the default privilege level for an .CR ".EXPORT" directive to .IR number . By default, all user-level procedures are exported at privilege level 3. .TP .CR -s Set the output file suffix to .CR .ss instead of .CR .o . The file will have a format suitable for conversion to the ROM burning programs. .TP .CR -u Do not create unwind descriptors. To avoid the need for the .CR .CALLINFO directive, the .CR .ENTER and .CR .LEAVE directives must not have been used. .TP .CI -v " xrfile" Write cross-reference data to the file named .IR xrfile . .TP .CR -V Print the version number of the assembler program to standard error before assembling the source text. .TP .CR -w [\f2number\f1] Either suppress all warning messages if no .I number is supplied or suppress just the warning .I number provided. Multiple .CI -w number options can be used to suppress additional warning messages. .TP .CI +DA architecture Assemble code for the .I architecture specified. The use of this option is discouraged. The preferred method for selecting the .I architecture is to have a .CR .LEVEL directive contained within the assembly source file. .IP The assembler uses the following precedence to determine the target architecture. .RS .RS .TP 3 .PD 0 1. Use the .CR .LEVEL directive within the assembly source file. .TP 2. Use the .CR +DA command-line specification. .TP 3. Use the default architecture of .CR PA_RISC_1.0 . .PD .RE .RE .TP .C +z,+Z Both of these options are used in the building of shared libraries. For a more complete discussion regarding these options, see the manual .IR "Programming on HP-UX" . .RE .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multibyte character code sets are supported. .SH DIAGNOSTICS When syntactic or semantic errors occur, a single-line diagnostic is written to standard error, that includes the file name and the line number where it occurred. The format is as follows: .IP .\" as: "//.profile", line 26: error 1035: Instruction .\" source = EXPORT TERM .C "as: ""\c" .I filename\c .C """," .CI "line \&" line ": error \&" error ": \&" message .br .CI " source = \&" source-line .SH WARNINGS .CR as does not invoke .IR cpp (1) or .IR m4 (1) to perform macro processing. .SH FILES .PD 0 .TP 35 .CR /usr/include/hard_reg.hr Hardware register definitions .TP .CR /usr/include/soft_reg.h Software calling convention register definitions .TP .CR /usr/include/std_space.h Standard space and subspace definition .TP .CR /usr/lib/nls/msg/C/as.cat Assembler error message catalog .TP .CR /usr/lib/pcc_prefix.s Space, subspace and register definitions .TP .IC file .o Object file .PD .SH SEE ALSO adb(1), cc(1), cc_bundled(1), ld(1), nm(1), xdb(1), crt0(3). .PP .IR "Assembly Language Reference Manual" , .br .IR "Precision Architecture and Instruction Reference Manual" , .br .IR "Procedure Calling Conventions Reference Manual" . .\" .\" toc@\f3as(1)\f1:\0\0\f4as\f1@@@assembler (Precision Architecture) .\" .\" index@\f4as\f1 \- assembler (Precision Architecture)@@@\f3as(1)\f1 .\" index@\f1assembler (Precision Architecture)@@@\f3as(1)\f1 .\" index@\f1Precision Architecture assembler@@@\f3as(1)\f1 .\" $Header: asa.1,v 76.4 95/09/14 16:17:06 ssa Exp $ .TA a .TH asa 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME asa \- interpret \s-1ASA\s0 carriage control characters .SH SYNOPSIS .C asa .RI [ files ] .SH DESCRIPTION .C asa interprets the output of FORTRAN programs that utilize ASA carriage control characters. It processes either the .I files whose names are given as arguments, or the standard input if .CR - is specified or if no file names are given. The first character of each line is assumed to be a control character. The following control characters are interpreted as indicated: .RS .TP 8 (blank) Output a single new-line character before printing. .TP (space) (XPG4 only.) The rest of the line will be output without change. .TP .C 0 Output two new-line characters before printing. .TP .C 0 (XPG4 only.) A shall be output, then the rest of the input line. .TP .C 1 Output a new-page character before printing. .TP .C + Overprint previous line. .TP .C + (XPG4 only.) The of the previous line shall be replaced with one or more implementaions-defined characters that causes printing to return to column position 1, followed by the rest of the input line. If the + is the first character in the input, it shall have the same effect as . .RE .PP Lines beginning with other than the above characters are treated the same as lines beginning with a blank. The first character of a line is .I not printed. If any such lines appear, an appropriate diagnostic is sent to standard error. This program forces the first line of each input file to start on a new page. .PP (XPG4 only.) The action of the asa utility is unspecified upon encountering any character other than those listed above as the first character in a line. .PP To view the output of FORTRAN programs which use ASA carriage control characters and have them appear in normal form, .CR asa can be used as a filter: .IP .C a.out | asa | lp .PP The output, properly formatted and paginated, is then directed to the line printer. FORTRAN output previously sent to a file can be viewed on a user terminal screen by using: .IP .CI asa \0file .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text within file as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C asa behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH SEE ALSO efl(1), f77(1), fsplit(1), ratfor(1). .SH STANDARDS CONFORMANCE .CR asa ": XPG4, POSIX.2" .\" .\" index@\f4asa\f1 \- interpret \s-1ASA\s+1 carriage control characters@@@\f3asa(1)\f1 .\" index@\s-1ASA\s+1 carriage control characters, interpret@@@\f3asa(1)\f1 .\" index@carriage control characters, \s-1ASA\s+1, interpret@@@\f3asa(1)\f1 .\" index@characters, \s-1ASA\s+1 carriage control, interpret@@@\f3asa(1)\f1 .\" index@control characters, \s-1ASA\s+1 carriage, interpret@@@\f3asa(1)\f1 .\" index@interpret \s-1ASA\s+1 carriage control characters@@@\f3asa(1)\f1 .\" .\" toc@\f3asa(1)\f1:\0\0\f4asa\f1@@@interpret \s-1ASA\s+1 carriage control characters .\" .\" $Header: at.1,v 76.1 95/07/10 16:51:35 ssa Exp $ .TA a .TH at 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME at, batch \- execute batched commands immediately or at a later time .SH SYNOPSIS .SS "Enter commands from standard input to run at a specified time:" .CR at .RC [ -m ] .RC [ -q\c .IR \0queue ] .CR -t .IR spectime .br .IR commands .br .IR eof .PP .CR at .RC [ -m ] .RC [ -q\c .IR \0queue ] .IR time .RI [ date ] .RC [ next .IR timeunit .RI \(or .CI + count .IR timeunit ] .br .IR commands .br .IR eof .SS "Enter commands from a file to run at a specified time:" .CR at .CI -f \0job-file .RC [ -m ] .RC [ -q\c .IR \0queue ] .CR -t .IR spectime .PP .CR at .CI -f \0job-file .RC [ -m ] .RC [ -q\c .IR \0queue ] .IR time .RI [ date ] .ifn .br .ifn \0\0\0\0 .RC [ next .IR timeunit .RI \(or .CI + count .IR timeunit ] .SS "List scheduled jobs:" .CR "at -l" .RI [ job-id \0...\&] .PP .CR "at -l -q" .IR queue .SS "Cancel (remove) a scheduled job:" .CR "at -r" .IR job-id \0...\& .SS "Enter commands from standard input to run as a batch process:" .CR batch .br .IR commands .br .IR eof .SS "Enter commands from a file to run as a batch process:" .CI "batch < \&" job-file .SH DESCRIPTION The .CR at and .CR batch commands schedule jobs for execution by the .CR cron daemon (see .IR cron (1M)). .PP .CR at schedules a job for execution at a specified time. .CR at can also list .RC ( -l ) or remove .RC ( -r ) existing scheduled .CR at and .CR batch jobs. .PP .CR batch schedules a job for execution immediately, or as soon as system load levels permit. .PP You can enter commands into a job in one of the following ways: .RS 2 .TP 3 \(bu From the keyboard on separate lines immediately after the .CR at or .CR batch command line, followed by the currently defined .IR eof (end-of-file) character to end the input. The default .IR eof is .RC Ctrl- D . It can be redefined in your environment (see .IR stty (1)). .TP \(bu With the .CR -f option of the .CR at command to read input from a script file. .TP \(bu From output piped from a preceding command. .RE .SS "Options and Arguments" .CR at recognizes the following options and arguments. .RS .TP 20 .IR commands One or more HP-UX commands that can be executed as a shell script by .CR at or .CR batch . .TP .IR eof End-of-file character. The default is .RC Ctrl- D unless defined otherwise in your environment. .TP .IR job-file The path name of an existing file. .TP .IR job-id The job identifier reported by .CR at or .CR batch when the job was originally scheduled. .TP .CI -f \0job-file Read in the commands contained in .IR job-file instead of using standard input. .TP .CR -l \0[\f2job-id\f1\0...] List the jobs specified. If no .IR job-id s are given, all jobs are listed. .TP .CR -m Send mail to the invoking user after the job has run, announcing its completion. Unless redirected elsewhere within the job, standard output and standard error produced by the job are automatically mailed to the user as well. .TP .CI -q \0queue Submit the specified job to the .IR queue indicated (see .IR queuedefs (4)). Queues .CR a , .CR b , and .CR d through .CR y can be used. .CR at uses queue .CR a by default. .CR batch always uses queue .CR b . All queues except .CR b require a .IR time or a .CR -t specification. .CR "at\ -qb" is equivalent to .CR "batch" . .TP .CI -r \0job-id\f1\0... Remove the jobs specified by each .IR job-id . .TP .CI -t \0spectime Define the absolute time to start the job. .RS 10 .TP 10 .IR spectime A date and time in the format: .RS .IP .RI [\|[ CC ] \^YY ] \^MMDDhhmm\c .RC [ .\c .IR ss ] .PP where the decimal digit pairs are as follows: .RS .TP .PD 0 .IR CC The first two digits of the year .RC ( 19 ", " 20 ). .TP .IR YY The second two digits of the year .RC ( 70 \(mi 99 , .CR 00 \(mi 69 ). See WARNINGS. .TP .IR MM The month of the year .RC ( 01 \(mi 12 ). .TP .IR DD The day of the month .RC ( 01 \(mi 31 ). .TP .IR hh The hour of the day .RC ( 00 \(mi 23 ). .TP .IR mm The minute of the hour .RC ( 00 \(mi 59 ). .TP .IR ss The second of the minute .RC ( 00 \(mi 61 ). .PD .RE .RE .IP If both .IR CC and .IR YY are omitted, the default is the current year. .IP If .IR CC is omitted and .IR YY is in the range .CR 70 \(mi 99 , .IR CC defaults to .CR 19 . Otherwise, .CR CC defaults to .CR 20 . .IP The range for .IR ss provides for two leap seconds. If .IR ss is .CR 60 or .CR 61 , and the resulting time, as affected by the .CR TZ environment variable, does not refer to a leap second, the time is set to the whole minute following .IR mm . .IP If .IR ss is omitted, it defaults to .CR 00 . .RE .TP .IR time \0[ date ] Define the base time for starting the job. .RS 10 .TP 10 .IR time A time specified as one, two, or four digits. One- and two-digit numbers represent hours; four digits represent hours and minutes. .IP Alternately, .IR time can be specified as two numbers separated by a colon .RC ( : ), a single quote .RC ( ' ), the letter .IR h .RC ( h ), a period .RC ( . ), or a comma .RC ( , ). If defined in .IR langinfo (5), special time unit characters can be used. .IP .CR am or .CR pm can be appended to indicate morning or afternoon. Otherwise, a 24-hour clock is understood. For example, .CR 0815 , .CR 8:15 , .CR 8'15 , .CR 8h15 , .CR 8.15 , and .CR 8,15 are read as 15 minutes after eight in the morning. The suffixes .CR zulu and .CR utc can be used to specify Coordinated Universal Time (UTC), equivalent to Greenwich Mean Time (GMT). .IP The special names .CR midnight , .CR noon , and .CR now are also recognized. .TP .IR date A day of the week (fully spelled out or abbreviated) or a date consisting of a day, a month, and optionally a year. The day and year fields must be numeric, and the month can be either fully spelled out, abbreviated, or numeric. These three fields can be in any order, and separated by punctuation marks such as slash .RC ( / ), hyphen .RC ( - ), period .RC ( . ), and comma .RC ( , ). If defined in .IR langinfo (5), special date unit characters can be present. If a given date is ambiguous (such as .CR 2/5 ), the .CR D_T_FMT string (if defined in .IR langinfo (5)) is used to resolve the ambiguity. .IP Two special days, .CR today and .CR tomorrow , are also recognized. If no .IR date is given, .CR today is assumed if the given time is greater than the current time; .CR tomorrow is assumed if it is less. .IP If the given month is less than the current month (and no year is given), next year is assumed. Two-digit years in the range 70 to 99 are expanded to 1970 to 1999; in the range 00 to 69, to 2000 to 2069. .RE .ne 4 .TP .CI next \0timeunit\ \f1\(or\ + count\0timeunit .IP Delay the execution date and time by a specific number of time units after the base time specified by .IR time \ [ date ]. .RS 10 .TP 10 .IR count A decimal number. .CR next is equivalent to .CR +1 . .TP .IR timeunit A time unit, one of the following: .CR minutes , .CR hours , .CR days , .CR weeks , .CR months , or .CR years , or their singular forms. .RE .RE .SS "How Jobs Are Processed" .PP When a job is accepted, .CR at and .CR batch print a message to standard error in the form: .IP .CI "job \&" job-id " at \&" execution-date .PP where .IR job-id is the job identifier in the form .IC jobnumber . queue\f1, such as .CR 756284400.a , and .IR execution-date is the date and time when the job will be released for execution. .PP If your login shell is not the POSIX shell .RC ( /usr/bin/sh ), the commands also print a warning message: .IP .CR "warning: commands will be executed using /usr/bin/sh" .PP .CR at jobs default to queue .CR a . .CR batch jobs always go in queue .CR b . See the .CR -q option. .PP An .CR at or .CR batch job consists of a two-part script stored in .CR /var/spool/cron/atjobs that can be executed by the POSIX shell. .PP The first part sets up the environment to match the environment when the .CR at or .CR batch command was issued. This includes the current shell environment variables, current directory, .CR umask , and .CR ulimit (see .IR ulimit (2), .IR umask (1), and .IR proto (4)). Open file descriptors, traps, and priority are lost. .PP The second part consists of the commands that you entered. .PP When .CR cron dispatches the job, it starts a POSIX shell to execute the script. .PP The number of jobs executing from a queue at any time is controlled by parameters in the file .CR /var/adm/cron/queuedefs (see .IR queuedefs (4)). .PP Standard output and standard error from the job are mailed to the user unless they are redirected elsewhere within the job. .PP Scheduled jobs are immune to the .CR SIGHUP hangup signal, and remain scheduled if the user logs off. .PP Users are permitted to use the .CR at and .CR batch commands if their user names appear in the file .CR /var/adm/cron/at.allow . If that file does not exist, users can use .CR at and .CR batch if their names .IR "do not" appear in the file .CR /var/adm/cron/at.deny . If neither file exists, only superuser is allowed to submit jobs. If only .CR at.deny exists but is empty, all users can use .CR at and .CR batch . The .CR allow / deny files consist of one user name per line. .PP All users can list and remove their own jobs. Users with appropriate privileges can list and remove jobs other than their own. .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_TIME determines the format and contents of date and time strings. .PP .CR LC_MESSAGES determines the language in which messages are displayed. .PP .CR LC_MESSAGES also determines the language in which the words .CR days , .CR hours , .CR midnight , .CR minutes , .CR months , .CR next , .CR noon , .CR now , .CR today , .CR tomorrow , .CR weeks , .CR years , and their singular forms can also be specified. .PP IF .C LC_TIME or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE The exit code is set to one of the following: .RS .TP .PD 0 .CR \00 Successful completion .TP .CR \01 Failure .PD .RE .SH DIAGNOSTICS .CR at produces self-explanatory messages for syntax errors and out-of-range times. .PP .CR "warning: commands will be executed using /usr/bin/sh" .IP If your login shell is not the POSIX shell .RC ( /usr/bin/sh ), .CR at and .CR batch produce a warning message as a reminder that .CR at and .CR batch jobs are executed using .CR /usr/bin/sh . .SH EXAMPLES .PP The following commands show three different ways to run a POSIX shell script file named .CR delayed-job five minutes from now: .nf .IP .C "at -f delayed-job now + 5 minutes" .IP .C "cat delayed-job | at now + 5 minutes" .IP .C "at now + 5 minutes output-file 2>error-file" .RC "\f2eof\fP \0\0\0\0(the default is Ctrl-" D ) .fi .PP Run a job contained in .CR future in the home directory at 12:20 a.m.\& on December 27, 2013: .IP .C "at -f $HOME/future -t201312271220.00" .PP Redirect standard error to a pipe (useful in a shell procedure). Note that the sequence of the output redirection specifications is significant. Standard error is redirected to where standard output is going; standard output is redirected to a file; the original "standard output" (which now consists of the former standard error) is piped to the .CR mail program. .nf .IP .CR "batch <&1 1> output-file | mail " loginid .CR !! .fi .PP Run a job contained in .CR jobfile in the home directory at 5:00 a.m.\& next Tuesday: .IP .C "at -f $HOME/jobfile 5am tuesday next week" .PP Run the same job at 5:00 a.m.\& one week from next Tuesday (i.e., 2 Tuesdays in advance): .IP .C "at -f $HOME/jobfile 5am tuesday + 2 weeks" .PP Add a command to the file named .CR weekly-run in directory .CR jobs in the home directory so that it automatically reschedules itself every time it runs. This example reschedules itself every Thursday at 1900 (7:00 p.m.): .IP .C "echo ""sh $HOME/jobs/weekly-run"" | at 1900 thursday next week" .PP The following commands show several forms recognized by .CR at and include native language usage: .nf .IP .CR "at 0815 Jan 24" .CR "at 8:15 Jan 24" .CR "at 9:30am tomorrow" .CR "at now + 1 day" .CR "at -f job 5 pm Friday" .CR "at 17:40 Tor. # in Danish .CR "at 17h46 demain # in French .CR "at 5:30 26. Feb. 1988 # in German .CR "at 12:00 26-02 # in Finnish .fi .SH WARNINGS If the .IR date argument begins with a number and the .IR time argument is also numeric without a suffix, the .IR time argument should be a four-digit number that can be correctly interpreted as hours and minutes. .PP If you use both .CR next and .CI + count within a single .CR at command, the first operator is accepted and the trailing operator is silently ignored. .PP If you use both .CR -t and .IR time \0... in the same command, the first specified is accepted and the second is silently ignored. .PP If the FIFO used to communicate with .CR cron fills up, .CR at is suspended until .CR cron has read sufficient messages from the FIFO to make room for the message .CR at is trying to write. This condition can occur if .CR at is writing messages faster than .CR cron can process them or if .CR cron is not executing. .PP Scheduled processes are run in the background. Any script file that calls itself will cause the user or the system to run out of available processes. .PP If the execution-time request for a job duplicates the execution time of a currently scheduled job, the new job time is set to the next available second. .PP .CR at will not schedule jobs whose start time precedes the current Epoch (00:00:00 January 1, 1970 UTC). .PP .CR at will not schedule jobs beyond the year 2030. .\" .\" OBSERVATIONS MADE BY allanp 12/19/93 .\" The maximum 32-bit integer is 2147483647; .\" therefore, the maximum time is exactly: Jan 19, 2038 03:14:07 UTC .\" END OF OBSERVATIONS .\" .SH DEPENDENCIES .SS HP Process Resource Manager If the optional HP Process Resource Management (PRM) software is installed and configured, jobs are launched in the initial process resource group of the user that scheduled the job. The user's initial group is determined at the time the job is started, not when the job is scheduled. If the user's initial group is not defined, the job runs in the user default group .RC ( PRMID=1 ). See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for a description of how the user's initial process resource group is determined. .SH AUTHOR .CR at was developed by AT&T and HP. .SH FILES .TP 35 .PD 0 .CR /usr/bin/sh POSIX shell .TP .CR /var/adm/cron Main .CR cron directory .TP .CR /var/adm/cron/.proto Prototype information .TP .CR /var/adm/cron/at.allow List of allowed users .TP .CR /var/adm/cron/at.deny List of denied users .TP .CR /var/adm/cron/queuedefs Scheduling information .TP .CR /var/spool/cron/atjobs Spool area .PD .SH SEE ALSO crontab(1), kill(1), mail(1), nice(1), ps(1), sh(1), stty(1), cron(1M), proto(4), queuedefs(4), hpnls(5). .TP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR at ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR batch ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4at\f1 \- execute commands at a later time@@@\f3at(1)\f1 .\" index@\f4batch\f1 \- execute commands immediately@@@\f3at(1)\f1 .\" index@\f1commands, execute at a later time@@@\f3at(1)\f1 .\" index@\f1execute commands at a later time@@@\f3at(1)\f1 .\" index@\f1execute commands in background@@@\f3at(1)\f1 .\" index@\f1background batch execution@@@\f3at(1)\f1 .\" index@\f1time delay, execute commands after@@@\f3at(1)\f1 .\" index@\f1delay command execution@@@\f3at(1)\f1 .\" .\" toc@\f3at(1)\f1:\0\0\f4at\f1, \f4batch\f1@@@execute batched commands immediately or at a later time .\" toc@\f4batch\f1:\0\0execute batched commands immediately@@@see \f3at(1)\f1 .\" .\" links@at.1 batch.1 .\" $Header: attributes.1,v 74.2 95/05/10 21:26:47 ssa Exp $ .TA a .TH attributes 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attributes \- describe an audio file .SH SYNOPSIS .CI /opt/audio/bin/attributes \0filename .SH DESCRIPTION This command provides information about an audio file, including file format, data format, sampling rate, number of channels, data length and header length. .SH EXAMPLE The following is an example of using .C attributes on an audio file supplied with HP-UX. .sp .nf .C "$ /opt/audio/bin/attributes /opt/audio/sounds/welcome.au" .br .C " " .br .C "File Name: /opt/audio/sounds/welcome.au" .br .C "File Type: NeXT/Sun" .br .C "Data Format: Mu-law" .br .C "Sampling Rate: 22050" .br .C "Channels: Mono" .br .C "Duration: 1.972 seconds" .br .C "Bits per Sample: 8" .br .C "Header Length: 40 bytes" .br .C "Data Length: 43492 bytes" .fill .SH AUTHOR .C attributes was developed by .SM HP. .PP Sun is a trademark of Sun MicroSystems, Inc. .br NeXT is a trademark of NeXT Computers, Inc. .SH SEE ALSO audio(5), asecure(1m), aserver(1m), convert(1), send_sound(1). .PP .IR "Using the Audio Developer's Kit" .\" .\" index@\f4attributes\f1 \- describe audio file@@@\f3attributes(1)\f1 .\" index@\f1describe audio file@@@\f3attributes(1)\f1 .\" index@\f1audio file, describe@@@\f3attributes(1)\f1 .\" toc@\f3attributes(1)\f1:\0\0\f4attributes\f1@@@describe audio file .\" $Header: awk.1,v 76.1 95/08/01 15:58:34 ssa Exp $ .TA a .TH awk 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME awk \- pattern-directed scanning and processing language .SH SYNOPSIS .C awk .RC [ -F\c .IR fs\| ] .RC [ -v .IC var = value\|\c ] .RI [ \|program \(or .C -f .IR progfile \0...\|] .RI [ \|file \0...\|] .SH DESCRIPTION .C awk scans each input .I file for lines that match any of a set of patterns specified literally in .IR program or in one or more files specified as .C -f .IR progfile . With each pattern there can be an associated action that is to be performed when a line in a .I file matches the pattern. Each line is matched against the pattern portion of every pattern-action statement, and the associated action is performed for each matched pattern. The file name .C - means the standard input. Any .IR file of the form .IC var = value is treated as an assignment, not a filename. An assignment is evaluated at the time it would have been opened if it were a filename, unless the .C -v option is used. .PP An input line is made up of fields separated by white space, or by regular expression .CR FS . The fields are denoted .CR $1 , .CR $2 , \&...; .C $0 refers to the entire line. .SS Options .C awk recognizes the following options and arguments: .RS .TP 15 .CI -F \0fs Specify regular expression used to separate fields. The default is to recognize space and tab characters, and to discard leading spaces and tabs. If the .C -F option is used, leading input field separators are no longer discarded. .TP .CI -f \0progfile Specify an awk program file. Up to 100 program files can be specified. The pattern-action statements in these files are executed in the same order as the files were specified. .TP .CI -v \0var = value Cause .IC var = value assignment to occur before the .C BEGIN action (if it exists) is executed. .RE .SS Statements A pattern-action statement has the form: .IP .IC pattern " { " action " } .PP A missing .CI { " action " } means print the line; a missing pattern always matches. Pattern-action statements are separated by new-lines or semicolons. .PP An action is a sequence of statements. A statement can be one of the following: .RS .PP .ta 3i .CI if( \|expression\| ) \0statement\0\c .RC [ else .IR statement\| ] .br .CI while( \|expression ) \0statement .br .CI for( \|expression\| ; \|expression\| ;\c .IC \|expression ) \0statement .br .CI for( \|var \0in \0array\|) .I statement .br .C do .I statement .CI while( \|expression\|) .br .C break .br .C continue .br .C {\c .RI \|[ statement \0...\|]\|\c .C } .br .IC expression "\h'1.9i'#" commonly .IC var = expression .br .C print\c .RI \|[ \|expression-list\| ] .RC [ > .IR expression\| ] .br .C printf .I format .RC [ , .IR expression-list\| ] .RC [ > .IR expression\| ] .br .C return .RI [ \|expression\| ] .br .C "next \h'1i'#" skip remaining patterns on this input line. .br .C delete .I array .RI [ \|expression\| ] .C \h'.9i'# delete an array element. .br .C exit .RI [ \|expression\| ] .C \h'0.5i'# exit immediately; status is .IR expression . .RE .PP .DT Statements are terminated by semicolons, newlines or right braces. An empty .I expression-list stands for .CR $0 . String constants are quoted .ifn (\f3""\fP), .ift (\f4\s+1"\|"\fP\s0), with the usual C escapes recognized within. Expressions take on string or numeric values as appropriate, and are built using the operators .CR + , .CR - , .CR * , .CR / , .CR % , .C ^ (exponentiation), and concatenation (indicated by a blank). The operators .CR ++ , .CR -\|- , .CR += , .CR -= , .CR *= , .CR /= , .CR %= , .CR ^= , .CR **= , .CR > , .CR >= , .CR < , .CR <= , .CR == , .CR != , and .C ?: are also available in expressions. Variables can be scalars, array elements (denoted .IC x [ i ]\c ) or fields. Variables are initialized to the null string. Array subscripts can be any string, not necessarily numeric (this allows for a form of associative memory). Multiple subscripts such as .CI [ \|i ,\c .IC j , k\| ] are permitted. The constituents are concatenated, separated by the value of .CR SUBSEP . .PP The .C print statement prints its arguments on the standard output (or on a file if .CI > file or .CI >> file is present or on a pipe if .CI | cmd is present), separated by the current output field separator, and terminated by the output record separator. .I file and .I cmd can be literal names or parenthesized expressions. Identical string values in different statements denote the same open file. The .C printf statement formats its expression list according to the format (see .IR printf (3)). .SS Built-In Functions The built-in function .CI close( expr ) closes the file or pipe .C expr opened by a .C print or .C printf statement or a call to .C getline with the same string-valued .IR expr . This function returns zero if successful, otherwise, it returns non-zero. .PP The customary functions .CR exp , .CR log , .CR sqrt , .CR sin , .CR cos , .CR atan2 are built in. Other built-in functions are: .RS 3 .TP 18 .CR blength\|[ ( \|[\|\f2s\fP\|]\| ) \|] Length of its associated argument (in bytes) taken as a string, or of .C $0 if no argument. .TP .CR length\|[ ( \|[\|\f2s\fP\|]\| ) \|] Length of its associated argument (in characters) taken as a string, or of .C $0 if no argument. .TP .C rand() Returns a random number between zero and one. .TP .CR srand( \|[\|\f2expr\fP\|]\| ) Sets the seed value for .IR rand , and returns the previous seed value. If no argument is given, the time of day is used as the seed value; otherwise, .I expr is used. .TP .CI int( x ) Truncates to an integer value .TP .CI substr( "s\fP, \fPm\f1[\fP" , " n\f1]\fP" ) Return the at most .IR n -character substring of .I s that begins at position .IR m , numbering from 1. If .I n is omitted, the substring is limited by the length of string .IR s . .TP .CI index( \|s , " t" \|) Return the position, in characters, numbering from 1, in string .I s where string .I t first occurs, or zero if it does not occur at all. .TP .CI match( \|s , " ere" \|) Return the position, in characters, numbering from 1, in string .I s where the extended regular expression .I ere occurs, or 0 if it does not. The variables .C RSTART and .C RLENGTH are set to the position and length of the matched string. .TP .CI split( "\|s\fP, \fPa\f1[" , " fs\f1]\fP\|" ) Splits the string .I s into array elements .IC a [1]\c , .IC a [2]\c , \&..., .IC a [ n ]\c , and returns .IR n . The separation is done with the regular expression .IR fs , or with the field separator .C FS if .I fs is not given. .TP .CI sub( "\|ere\fP, \fPrepl \f1[\fP" , " in\f1]\fP\|" ) Substitutes .I repl for the first occurrence of the extended regular expression .I ere in the string .IR in . If .I in is not given, .C $0 is used. .TP .C gsub Same as .C sub except that all occurrences of the regular expression are replaced; .C sub and .C gsub return the number of replacements. .TP .CI sprintf( "\|fmt\fP, \fPexpr" , " ...\|" ) String resulting from formatting .I expr ... according to the .IR printf (3S) format .I fmt .TP .CI system( cmd ) Executes .I cmd and returns its exit status .TP .CI toupper( s ) Converts the argument string .I s to uppercase and returns the result. .TP .CI tolower( s ) Converts the argument string .I s to lowercase and returns the result. .RE .PP The built-in function .C getline sets .C $0 to the next input record from the current input file; .CI "getline < " file sets .C $0 to the next record from .IR file . .C getline .I x sets variable .I x instead. Finally, .IC cmd " | getline" pipes the output of .I cmd into .CR getline ; each call of .C getline returns the next line of output from .IR cmd . In all cases, .C getline returns 1 for a successful input, 0 for end of file, and \(mi1 for an error. .SS Patterns Patterns are arbitrary Boolean combinations (with .CR "! || &&" ) of regular expressions and relational expressions. .C awk supports Extended Regular Expressions as described in .IR regexp (5). Isolated regular expressions in a pattern apply to the entire line. Regular expressions can also occur in relational expressions, using the operators .C ~ and .CR !~ . .CI / re / is a constant regular expression; any string (constant or variable) can be used as a regular expression, except in the position of an isolated regular expression in a pattern. .PP A pattern can consist of two patterns separated by a comma; in this case, the action is performed for all lines from an occurrence of the first pattern though an occurrence of the second. .PP A relational expression is one of the following: .IP .I expression matchop regular-expression .br .I expression relop expression .br .IC expression \0in\0 array-name .br .CI ( expr,expr,\&... ) \0in\0 array-name .PP where a relop is any of the six relational operators in C, and a matchop is either .C ~ (matches) or .C !~ (does not match). A conditional is an arithmetic expression, a relational expression, or a Boolean combination of the two. .PP The special patterns .C BEGIN and .C END can be used to capture control before the first input line is read and after the last. .C BEGIN and .C END do not combine with other patterns. .SS Special Characters The following special escape sequences are recognized by .C awk in both regular expressions and strings: .RS .TP 10 .B Escape .B Meaning .PD 0 .RS 2 .TP 8 .C \ea alert character .TP .C \eb backspace character .TP .C \ef form-feed character .TP .C \en new-line character .TP .C \er carriage-return character .TP .C \et tab character .TP .C \ev vertical-tab character .TP .CI \e nnn 1- to 3-digit octal value .I nnn .TP .CI \ex hhh 1- to n-digit hexadecimal number .PD .RE .RE .SS Variable Names Variable names with special meanings are: .RS .TP 18 .C FS Input field separator regular expression; a space character by default; also settable by option .CI -F fs\f1. .TP .CR NF The number of fields in the current record. .TP .C NR The ordinal number of the current record from the start of input. Inside a .C BEGIN action the value is zero. Inside an .C END action the value is the number of the last record processed. .TP .C FNR The ordinal number of the current record in the current file. Inside a .C BEGIN action the value is zero. Inside an .C END action the value is the number of the last record processed in the last file processed. .TP .C FILENAME A pathname of the current input file. .TP .C RS The input record separator; a newline character by default. .TP .C OFS The .C print statement output field separator; a space character by default. .TP .C ORS The .C print statement output record separator; a newline character by default. .TP .C OFMT Output format for numbers (default .CR "%.6g" ). If the value of .C OFMT is not a floating-point format specification, the results are unspecified. .TP .C CONVFMT Internal conversion format for numbers (default .CR "%.6g" ). If the value of .C CONVFMT is not a floating-point format specification, the results are unspecified. .TP .C SUBSEP The subscript separator string for multi-dimensional arrays; the default value is "\034" .TP .C ARGC The number of elements in the .C ARGV array. .TP .C ARGV An array of command line arguments, excluding options and the .I program argument numbered from zero to .CR ARGC -1. .IP \0 18 The arguments in .CR ARGV can be modified or added to; .CR ARGC can be altered. As each input file ends, .C awk will treat the next non-null element of .CR ARGV , up to the current value of .CR ARGC "-1," inclusive, as the name of the next input file. Thus, setting an element of .CR ARGV to null means that it will not be treated as an input file. The name .C - indicates the standard input. If an argument matches the format of an .I assignment operand, this argument will be treated as an assignment rather than a .I file argument. .TP 18 .C ENVIRON Array of environment variables; subscripts are names. For example, if environment variable .CR V=thing , .ifn \f3ENVIRON["V"]\fP .ift \f4\s+1ENVIRON["V"]\fP\s0 produces .CR thing . .TP .C RSTART The starting position of the string matched by the .C match function, numbering from 1. This is always equivalent to the return value of the .C match function. .TP .C RLENGTH The length of the string matched by the .C match function. .RE .PP Functions can be defined (at the position of a pattern-action statement) as follows: .IP .C "function foo(a, b, c) { ...; return x }" .RE .PP Parameters are passed by value if scalar, and by reference if array name. Functions can be called recursively. Parameters are local to the function; all other variables are global. .PP Note that if pattern-action statements are used in an HP-UX command line as an argument to the .C awk command, the pattern-action statement must be enclosed in single quotes to protect it from the shell. For example, to print lines longer than 72 characters, the pattern-action statement as used in a script .RC ( -f .I progfile command form) is: .IP .C length > 72 .PP The same pattern action statement used as an argument to the .C awk command is quoted in this manner: .IP .C awk 'length > 72' .SH EXTERNAL INFLUENCES .SS Environment Variables .TP 15 .C LANG Provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C awk will behave as if all internationalization variables are set to "C". See .IR environ (5). .TP .C LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .TP .C LC_CTYPE Determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .TP .C LC_NUMERIC Determines the radix character used when interpreting numeric input, performing conversion between numeric and string values and formatting numeric output. Regardless of locale, the period character (the decimal-point character of the POSIX locale) is the decimal-point character recognized in processing .C awk programs (including assignments in command-line arguments). .TP .C LC_COLLATE Determines the locale for the behavior of ranges, equivalence classes and multi-character collating elements within regular expressions. .TP .C LC_MESSAGES Determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .TP .C NLSPATH Determines the location of message catalogues for the processing of .C LC_MESSAGES. .TP .C PATH Determines the search path when looking for commands executed by .CI system(cmd) , or input and output pipes. .PP In addition, all environment variables will be visible via the .C awk variable .CI ENVIRON . .SS International Code Set Support Single- and multi-byte character code sets are supported except that variable names must contain only ASCII characters and regular expressions must contain only valid characters. .SH DIAGNOSTICS .C awk supports up to 199 fields .RC ( $1 , .CR $2 , \&..., .CR $199 ) per record. .SH EXAMPLES Print lines longer than 72 characters: .IP .C length > 72 .PP Print first two fields in opposite order: .IP .C { print $2, $1 } .PP Same, with input fields separated by comma and/or blanks and tabs: .IP .ifn .ft 3 .ift .ft 4 .ps +1 BEGIN { FS = ",[ \et]*|[ \et]+" } .br { print $2, $1 } .ft .ps .PP Add up first column, print sum and average: .IP .ifn .ft 3 .ift .ft 4 .ps +1 { s += $1 }" .br END { print "sum is", s, " average is", s/NR } .ft .ps .PP Print all lines between start/stop pairs: .IP .C /start/, /stop/ .PP Simulate .C echo command (see .IR echo (1)): .IP .ifn .ft 3 .ift .ft 4 .ps +1 BEGIN { # Simulate echo(1) .br for (i = 1; i < ARGC; i++) printf "%s ", ARGV[i] .br printf "\en" .br exit } .ft .ps .SH AUTHOR .CR awk was developed by AT&T, IBM, OSF, and HP. .SH SEE ALSO lex(1), sed(1). .br A. V. Aho, B. W. Kernighan, P. J. Weinberger: .IR "The AWK Programming Language" , Addison-Wesley, 1988. .SH STANDARDS CONFORMANCE .CR awk ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4awk\f1 \- text pattern scanning and processing language@@@\f3awk(1)\f1 .\" index@language: text pattern scanning and processing language@@@\f3awk(1)\f1 .\" index@pattern scanning and processing language, text@@@\f3awk(1)\f1 .\" index@processing language, text pattern scanning and@@@\f3awk(1)\f1 .\" index@scanning and processing language, text pattern@@@\f3awk(1)\f1 .\" index@text pattern scanning and processing language@@@\f3awk(1)\f1 .\" .\" toc@\f3awk(1)\f1:\0\0\f4awk\f1@@@text pattern scanning and processing language .\" $Header: banner.1,v 72.4 94/11/14 12:05:37 ssa Exp $ .TA b .TH banner 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME banner \- make posters in large letters .SH SYNOPSIS .C banner .I strings .SH DESCRIPTION .C banner prints its arguments (each up to 10 characters long) in large letters on the standard output. .PP Each argument is printed on a separate line. Note that multiple-word arguments must be enclosed in quotes in order to be printed on the same line. .SH EXAMPLES Print the message ``Good luck Susan'' in large letters on the screen: .IP .C banner """Good luck""" Susan .PP The words .C Good luck are displayed on one line, and .C Susan is displayed on a second line. .SH SEE ALSO echo(1). .SH STANDARDS CONFORMANCE .CR banner ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4banner\f1 \- make posters in large letters@@@\f3banner(1)\f1 .\" index@make posters in large letters@@@\f3banner(1)\f1 .\" index@posters, make in large letters@@@\f3banner(1)\f1 .\" index@large letters, make posters in@@@\f3banner(1)\f1 .\" index@letters, make posters in large@@@\f3banner(1)\f1 .\" .\" toc@\f3banner(1)\f1:\0\0\f4banner\f1@@@make posters in large letters .\" .\" fileset_database@banner.1 USER-CMDS-MAN .\" $Header: basename.1,v 76.1 95/08/01 16:01:13 ssa Exp $ .TA b .TH basename 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME basename, dirname \- extract portions of path names .SH SYNOPSIS .C basename .I string .RI [ \|suffix\| ] .br .C dirname .RI [ \|string\| ] .SH DESCRIPTION .C basename deletes any prefix ending in .C / and the .I suffix (if present in .IR string ) from .IR string , and prints the result on the standard output. If .I string consists entirely of slash characters, .I string is set to a single slash character. If there are any trailing slash characters in .IR string , they are removed. If the suffix operand is present but not identical to the characters remaining in .IR string , but it is identical to a suffix of the characters remaining in .IR string , the suffix is removed from .IR string . .C basename is normally used inside command substitution marks .RC ( \|\` ... \`\| ) within shell procedures. .PP .C dirname delivers all but the last level of the path name in .IR string . If .I string does not contain a directory component, .C dirname returns .CR . , indicating the current working directory. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of string and, in the case of basename, suffix as single and/or multi-byte characters. .PP If .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C basename and .C dirname behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following shell script, invoked with the argument .CR /usr/src/cmd/cat.c , compiles the named file and moves the output to a file named .C cat in the current directory: .IP .C cc $1 .br .C "mv a.out `basename $1 .c`" .PP The following example sets the shell variable .C NAME to .CR /usr/src/cmd : .IP .C "NAME=\`dirname /usr/src/cmd/cat.c\`" .SH RETURNS .C basename and .C dirname return one of the following values: .RS .TP 8 .B 0 Successful completion. .TP .B 1 Incorrect number of command-line arguments. .SH SEE ALSO expr(1), sh(1). .SH STANDARDS CONFORMANCE .CR basename ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR dirname ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4basename\f1, \f4dirname\f1 \- extract portions of path names@@@\f3basename(1)\f1 .\" index@\f4dirname\f1, \f4basename\f1 \- extract portions of path names@@@\f3basename(1)\f1 .\" index@extract portions of path names@@@\f3basename(1)\f1 .\" index@portions of path names, extract@@@\f3basename(1)\f1 .\" index@path names, extract portions of@@@\f3basename(1)\f1 .\" index names: extract portions of path names \f3basename(1)\f1 .\" .\" toc@\f3basename(1)\f1:\0\0\f4basename\f1, \f4dirname\f1@@@extract portions of path names .\" toc@\f4dirname\f1: extract portions of path names@@@see \f3basename(1)\f1 .\" .\" links@basename.1 dirname.1 .\" .\" fileset_database@basename.1 USER-CMDS-MAN .\" $Header: at.1,v 76.1 95/07/10 16:51:35 ssa Exp $ .TA a .TH at 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME at, batch \- execute batched commands immediately or at a later time .SH SYNOPSIS .SS "Enter commands from standard input to run at a specified time:" .CR at .RC [ -m ] .RC [ -q\c .IR \0queue ] .CR -t .IR spectime .br .IR commands .br .IR eof .PP .CR at .RC [ -m ] .RC [ -q\c .IR \0queue ] .IR time .RI [ date ] .RC [ next .IR timeunit .RI \(or .CI + count .IR timeunit ] .br .IR commands .br .IR eof .SS "Enter commands from a file to run at a specified time:" .CR at .CI -f \0job-file .RC [ -m ] .RC [ -q\c .IR \0queue ] .CR -t .IR spectime .PP .CR at .CI -f \0job-file .RC [ -m ] .RC [ -q\c .IR \0queue ] .IR time .RI [ date ] .ifn .br .ifn \0\0\0\0 .RC [ next .IR timeunit .RI \(or .CI + count .IR timeunit ] .SS "List scheduled jobs:" .CR "at -l" .RI [ job-id \0...\&] .PP .CR "at -l -q" .IR queue .SS "Cancel (remove) a scheduled job:" .CR "at -r" .IR job-id \0...\& .SS "Enter commands from standard input to run as a batch process:" .CR batch .br .IR commands .br .IR eof .SS "Enter commands from a file to run as a batch process:" .CI "batch < \&" job-file .SH DESCRIPTION The .CR at and .CR batch commands schedule jobs for execution by the .CR cron daemon (see .IR cron (1M)). .PP .CR at schedules a job for execution at a specified time. .CR at can also list .RC ( -l ) or remove .RC ( -r ) existing scheduled .CR at and .CR batch jobs. .PP .CR batch schedules a job for execution immediately, or as soon as system load levels permit. .PP You can enter commands into a job in one of the following ways: .RS 2 .TP 3 \(bu From the keyboard on separate lines immediately after the .CR at or .CR batch command line, followed by the currently defined .IR eof (end-of-file) character to end the input. The default .IR eof is .RC Ctrl- D . It can be redefined in your environment (see .IR stty (1)). .TP \(bu With the .CR -f option of the .CR at command to read input from a script file. .TP \(bu From output piped from a preceding command. .RE .SS "Options and Arguments" .CR at recognizes the following options and arguments. .RS .TP 20 .IR commands One or more HP-UX commands that can be executed as a shell script by .CR at or .CR batch . .TP .IR eof End-of-file character. The default is .RC Ctrl- D unless defined otherwise in your environment. .TP .IR job-file The path name of an existing file. .TP .IR job-id The job identifier reported by .CR at or .CR batch when the job was originally scheduled. .TP .CI -f \0job-file Read in the commands contained in .IR job-file instead of using standard input. .TP .CR -l \0[\f2job-id\f1\0...] List the jobs specified. If no .IR job-id s are given, all jobs are listed. .TP .CR -m Send mail to the invoking user after the job has run, announcing its completion. Unless redirected elsewhere within the job, standard output and standard error produced by the job are automatically mailed to the user as well. .TP .CI -q \0queue Submit the specified job to the .IR queue indicated (see .IR queuedefs (4)). Queues .CR a , .CR b , and .CR d through .CR y can be used. .CR at uses queue .CR a by default. .CR batch always uses queue .CR b . All queues except .CR b require a .IR time or a .CR -t specification. .CR "at\ -qb" is equivalent to .CR "batch" . .TP .CI -r \0job-id\f1\0... Remove the jobs specified by each .IR job-id . .TP .CI -t \0spectime Define the absolute time to start the job. .RS 10 .TP 10 .IR spectime A date and time in the format: .RS .IP .RI [\|[ CC ] \^YY ] \^MMDDhhmm\c .RC [ .\c .IR ss ] .PP where the decimal digit pairs are as follows: .RS .TP .PD 0 .IR CC The first two digits of the year .RC ( 19 ", " 20 ). .TP .IR YY The second two digits of the year .RC ( 70 \(mi 99 , .CR 00 \(mi 69 ). See WARNINGS. .TP .IR MM The month of the year .RC ( 01 \(mi 12 ). .TP .IR DD The day of the month .RC ( 01 \(mi 31 ). .TP .IR hh The hour of the day .RC ( 00 \(mi 23 ). .TP .IR mm The minute of the hour .RC ( 00 \(mi 59 ). .TP .IR ss The second of the minute .RC ( 00 \(mi 61 ). .PD .RE .RE .IP If both .IR CC and .IR YY are omitted, the default is the current year. .IP If .IR CC is omitted and .IR YY is in the range .CR 70 \(mi 99 , .IR CC defaults to .CR 19 . Otherwise, .CR CC defaults to .CR 20 . .IP The range for .IR ss provides for two leap seconds. If .IR ss is .CR 60 or .CR 61 , and the resulting time, as affected by the .CR TZ environment variable, does not refer to a leap second, the time is set to the whole minute following .IR mm . .IP If .IR ss is omitted, it defaults to .CR 00 . .RE .TP .IR time \0[ date ] Define the base time for starting the job. .RS 10 .TP 10 .IR time A time specified as one, two, or four digits. One- and two-digit numbers represent hours; four digits represent hours and minutes. .IP Alternately, .IR time can be specified as two numbers separated by a colon .RC ( : ), a single quote .RC ( ' ), the letter .IR h .RC ( h ), a period .RC ( . ), or a comma .RC ( , ). If defined in .IR langinfo (5), special time unit characters can be used. .IP .CR am or .CR pm can be appended to indicate morning or afternoon. Otherwise, a 24-hour clock is understood. For example, .CR 0815 , .CR 8:15 , .CR 8'15 , .CR 8h15 , .CR 8.15 , and .CR 8,15 are read as 15 minutes after eight in the morning. The suffixes .CR zulu and .CR utc can be used to specify Coordinated Universal Time (UTC), equivalent to Greenwich Mean Time (GMT). .IP The special names .CR midnight , .CR noon , and .CR now are also recognized. .TP .IR date A day of the week (fully spelled out or abbreviated) or a date consisting of a day, a month, and optionally a year. The day and year fields must be numeric, and the month can be either fully spelled out, abbreviated, or numeric. These three fields can be in any order, and separated by punctuation marks such as slash .RC ( / ), hyphen .RC ( - ), period .RC ( . ), and comma .RC ( , ). If defined in .IR langinfo (5), special date unit characters can be present. If a given date is ambiguous (such as .CR 2/5 ), the .CR D_T_FMT string (if defined in .IR langinfo (5)) is used to resolve the ambiguity. .IP Two special days, .CR today and .CR tomorrow , are also recognized. If no .IR date is given, .CR today is assumed if the given time is greater than the current time; .CR tomorrow is assumed if it is less. .IP If the given month is less than the current month (and no year is given), next year is assumed. Two-digit years in the range 70 to 99 are expanded to 1970 to 1999; in the range 00 to 69, to 2000 to 2069. .RE .ne 4 .TP .CI next \0timeunit\ \f1\(or\ + count\0timeunit .IP Delay the execution date and time by a specific number of time units after the base time specified by .IR time \ [ date ]. .RS 10 .TP 10 .IR count A decimal number. .CR next is equivalent to .CR +1 . .TP .IR timeunit A time unit, one of the following: .CR minutes , .CR hours , .CR days , .CR weeks , .CR months , or .CR years , or their singular forms. .RE .RE .SS "How Jobs Are Processed" .PP When a job is accepted, .CR at and .CR batch print a message to standard error in the form: .IP .CI "job \&" job-id " at \&" execution-date .PP where .IR job-id is the job identifier in the form .IC jobnumber . queue\f1, such as .CR 756284400.a , and .IR execution-date is the date and time when the job will be released for execution. .PP If your login shell is not the POSIX shell .RC ( /usr/bin/sh ), the commands also print a warning message: .IP .CR "warning: commands will be executed using /usr/bin/sh" .PP .CR at jobs default to queue .CR a . .CR batch jobs always go in queue .CR b . See the .CR -q option. .PP An .CR at or .CR batch job consists of a two-part script stored in .CR /var/spool/cron/atjobs that can be executed by the POSIX shell. .PP The first part sets up the environment to match the environment when the .CR at or .CR batch command was issued. This includes the current shell environment variables, current directory, .CR umask , and .CR ulimit (see .IR ulimit (2), .IR umask (1), and .IR proto (4)). Open file descriptors, traps, and priority are lost. .PP The second part consists of the commands that you entered. .PP When .CR cron dispatches the job, it starts a POSIX shell to execute the script. .PP The number of jobs executing from a queue at any time is controlled by parameters in the file .CR /var/adm/cron/queuedefs (see .IR queuedefs (4)). .PP Standard output and standard error from the job are mailed to the user unless they are redirected elsewhere within the job. .PP Scheduled jobs are immune to the .CR SIGHUP hangup signal, and remain scheduled if the user logs off. .PP Users are permitted to use the .CR at and .CR batch commands if their user names appear in the file .CR /var/adm/cron/at.allow . If that file does not exist, users can use .CR at and .CR batch if their names .IR "do not" appear in the file .CR /var/adm/cron/at.deny . If neither file exists, only superuser is allowed to submit jobs. If only .CR at.deny exists but is empty, all users can use .CR at and .CR batch . The .CR allow / deny files consist of one user name per line. .PP All users can list and remove their own jobs. Users with appropriate privileges can list and remove jobs other than their own. .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_TIME determines the format and contents of date and time strings. .PP .CR LC_MESSAGES determines the language in which messages are displayed. .PP .CR LC_MESSAGES also determines the language in which the words .CR days , .CR hours , .CR midnight , .CR minutes , .CR months , .CR next , .CR noon , .CR now , .CR today , .CR tomorrow , .CR weeks , .CR years , and their singular forms can also be specified. .PP IF .C LC_TIME or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE The exit code is set to one of the following: .RS .TP .PD 0 .CR \00 Successful completion .TP .CR \01 Failure .PD .RE .SH DIAGNOSTICS .CR at produces self-explanatory messages for syntax errors and out-of-range times. .PP .CR "warning: commands will be executed using /usr/bin/sh" .IP If your login shell is not the POSIX shell .RC ( /usr/bin/sh ), .CR at and .CR batch produce a warning message as a reminder that .CR at and .CR batch jobs are executed using .CR /usr/bin/sh . .SH EXAMPLES .PP The following commands show three different ways to run a POSIX shell script file named .CR delayed-job five minutes from now: .nf .IP .C "at -f delayed-job now + 5 minutes" .IP .C "cat delayed-job | at now + 5 minutes" .IP .C "at now + 5 minutes output-file 2>error-file" .RC "\f2eof\fP \0\0\0\0(the default is Ctrl-" D ) .fi .PP Run a job contained in .CR future in the home directory at 12:20 a.m.\& on December 27, 2013: .IP .C "at -f $HOME/future -t201312271220.00" .PP Redirect standard error to a pipe (useful in a shell procedure). Note that the sequence of the output redirection specifications is significant. Standard error is redirected to where standard output is going; standard output is redirected to a file; the original "standard output" (which now consists of the former standard error) is piped to the .CR mail program. .nf .IP .CR "batch <&1 1> output-file | mail " loginid .CR !! .fi .PP Run a job contained in .CR jobfile in the home directory at 5:00 a.m.\& next Tuesday: .IP .C "at -f $HOME/jobfile 5am tuesday next week" .PP Run the same job at 5:00 a.m.\& one week from next Tuesday (i.e., 2 Tuesdays in advance): .IP .C "at -f $HOME/jobfile 5am tuesday + 2 weeks" .PP Add a command to the file named .CR weekly-run in directory .CR jobs in the home directory so that it automatically reschedules itself every time it runs. This example reschedules itself every Thursday at 1900 (7:00 p.m.): .IP .C "echo ""sh $HOME/jobs/weekly-run"" | at 1900 thursday next week" .PP The following commands show several forms recognized by .CR at and include native language usage: .nf .IP .CR "at 0815 Jan 24" .CR "at 8:15 Jan 24" .CR "at 9:30am tomorrow" .CR "at now + 1 day" .CR "at -f job 5 pm Friday" .CR "at 17:40 Tor. # in Danish .CR "at 17h46 demain # in French .CR "at 5:30 26. Feb. 1988 # in German .CR "at 12:00 26-02 # in Finnish .fi .SH WARNINGS If the .IR date argument begins with a number and the .IR time argument is also numeric without a suffix, the .IR time argument should be a four-digit number that can be correctly interpreted as hours and minutes. .PP If you use both .CR next and .CI + count within a single .CR at command, the first operator is accepted and the trailing operator is silently ignored. .PP If you use both .CR -t and .IR time \0... in the same command, the first specified is accepted and the second is silently ignored. .PP If the FIFO used to communicate with .CR cron fills up, .CR at is suspended until .CR cron has read sufficient messages from the FIFO to make room for the message .CR at is trying to write. This condition can occur if .CR at is writing messages faster than .CR cron can process them or if .CR cron is not executing. .PP Scheduled processes are run in the background. Any script file that calls itself will cause the user or the system to run out of available processes. .PP If the execution-time request for a job duplicates the execution time of a currently scheduled job, the new job time is set to the next available second. .PP .CR at will not schedule jobs whose start time precedes the current Epoch (00:00:00 January 1, 1970 UTC). .PP .CR at will not schedule jobs beyond the year 2030. .\" .\" OBSERVATIONS MADE BY allanp 12/19/93 .\" The maximum 32-bit integer is 2147483647; .\" therefore, the maximum time is exactly: Jan 19, 2038 03:14:07 UTC .\" END OF OBSERVATIONS .\" .SH DEPENDENCIES .SS HP Process Resource Manager If the optional HP Process Resource Management (PRM) software is installed and configured, jobs are launched in the initial process resource group of the user that scheduled the job. The user's initial group is determined at the time the job is started, not when the job is scheduled. If the user's initial group is not defined, the job runs in the user default group .RC ( PRMID=1 ). See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for a description of how the user's initial process resource group is determined. .SH AUTHOR .CR at was developed by AT&T and HP. .SH FILES .TP 35 .PD 0 .CR /usr/bin/sh POSIX shell .TP .CR /var/adm/cron Main .CR cron directory .TP .CR /var/adm/cron/.proto Prototype information .TP .CR /var/adm/cron/at.allow List of allowed users .TP .CR /var/adm/cron/at.deny List of denied users .TP .CR /var/adm/cron/queuedefs Scheduling information .TP .CR /var/spool/cron/atjobs Spool area .PD .SH SEE ALSO crontab(1), kill(1), mail(1), nice(1), ps(1), sh(1), stty(1), cron(1M), proto(4), queuedefs(4), hpnls(5). .TP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR at ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR batch ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4at\f1 \- execute commands at a later time@@@\f3at(1)\f1 .\" index@\f4batch\f1 \- execute commands immediately@@@\f3at(1)\f1 .\" index@\f1commands, execute at a later time@@@\f3at(1)\f1 .\" index@\f1execute commands at a later time@@@\f3at(1)\f1 .\" index@\f1execute commands in background@@@\f3at(1)\f1 .\" index@\f1background batch execution@@@\f3at(1)\f1 .\" index@\f1time delay, execute commands after@@@\f3at(1)\f1 .\" index@\f1delay command execution@@@\f3at(1)\f1 .\" .\" toc@\f3at(1)\f1:\0\0\f4at\f1, \f4batch\f1@@@execute batched commands immediately or at a later time .\" toc@\f4batch\f1:\0\0execute batched commands immediately@@@see \f3at(1)\f1 .\" .\" links@at.1 batch.1 .\" $Header: bc.1,v 76.1 95/08/01 16:02:31 ssa Exp $ .TA b .TH bc 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bc \- arbitrary-precision arithmetic language .SH SYNOPSIS .C bc .RC [ -c ] .RC [ -l ] .RI [ \|file \0...\|] .SH DESCRIPTION .C bc is an interactive processor for a language that resembles C but provides unlimited-precision arithmetic. It takes input from any files given, then reads the standard input. .SS Options: .C bc recognizes the following command-line options: .RS .TP 10 .C -c Compile only. .C bc is actually a preprocessor for .C dc which .C bc invokes automatically (see .IR dc (1)). Specifying .C -c prevents invoking .IR dc , and sends the .I dc input to standard output. .TP .C -l causes an arbitrary-precision math library to be predefined. As a side effect, the scale factor is set. .SS Program Syntax: .PD 0 .TP 5 L a single letter in the range .C a through .CR z ; .TP E expression; .TP S statement; .TP R relational expression. .PD .SS Comments: Comments are enclosed in .C /* and .CR */ . .SS Names: Names include: .IP simple variables: L .br array elements: L [ E ] .br The words .CR ibase , .CR obase , and .C scale .br stacks: L .SS Other Operands Other operands include: .RS .TP 20 Arbitrarily long numbers with optional sign and decimal point. .TP ( E ) .TP sqrt ( E ) .TP length ( E ) number of significant decimal digits .TP scale ( E ) number of digits right of decimal point .TP L ( E , ... , E ) .PP Strings of ASCII characters enclosed in quotes (\f3\|"\|\f1). .RE .SS Arithmetic Operators: Arithmetic operators yield an E as a result and include: .RS .TP 40 .C "+ - * / % ^" .RC ( \|% is remainder (not mod, see below); .C ^ is power). .TP .CR "++ -\|-" (prefix and append; apply to names) .TP .C "= += -= *= /= %= ^=" .RE .SS Relational Operators Relational operators yield an R when used as .C E .I op .CR E : .IP .C "== <= >= != < >" .SS Statements .nf E { S ; ... ; S } if ( R ) S while ( R ) S for ( E ; R ; E ) S null statement break quit .fi .SS Function Definitions: .ta .5i 1i 1.5i 2i .nf define L ( L ,..., L ) { auto L, ... , L S; ... S return ( E ) } .fi .DT .SS Functions in \(mil Math Library: Functions in the .C -l math library include: .ta .7i .PP .RS .nf s(x) sine c(x) cosine e(x) exponential l(x) log a(x) arctangent j(n,x) Bessel function .fi .RE .DT .PP All function arguments are passed by value. Trigonometric angles are in radians where 2 pi radians = 360 degrees. .PP The value of a statement that is an expression is printed unless the main operator is an assignment. No operators are defined for strings, but the string is printed if it appears in a context where an expression result would be printed. Either semicolons or new-lines can separate statements. Assignment to .I scale influences the number of digits to be retained on arithmetic operations in the manner of .IR dc (1). Assignments to .C ibase or .C obase set the input and output number radix respectively, again as defined by .IR dc (1). .PP The same letter can be used simultaneously as an array, a function, and a simple variable. All variables are global to the program. ``Auto'' variables are pushed down during function calls. When using arrays as function arguments or defining them as automatic variables, empty square brackets must follow the array name. .PP The .C % operator yields the remainder at the current scale, not the integer modulus. Thus, at scale 1, .C 7 % 3 is .1 (one tenth), not 1. This is because (at scale 1) .C 7 / 3 is 2.3 with .1 as the remainder. .SH EXAMPLES Define a function to compute an approximate value of the exponential function: .nf .IP .C "scale = 20" .C "define e(x){" .C " auto a, b, c, i, s" .C " a = 1" .C " b = 1" .C " s = 1" .C " for(i=1; 1==1; i++){" .C " a = a*x" .C " b = b*i" .C " c = a/b" .C " if(c == 0) return(s)" .C " s = s+c" .C " }" .C } .fi .PP Print approximate values of the exponential function of the first ten integers. .IP .C "for(i=1; i<=10; i++) e(i)" .SH WARNINGS There are currently no .C && (\s-1AND\s+1) or .C || (\s-1OR\s+1) comparisons. .PP The .C for statement must have all three expressions. .PP .C quit is interpreted when read, not when executed. .PP .CR bc 's parser is not robust in the face of input errors. Some simple expression such as 2+2 helps get it back into phase. .PP The assignment operators: .C "=+ =- =* =/ =% and .C =^ are obsolete. Any occurences of these operators cause a syntax error with the exception of .C =- which is interpreted as .C = followed by a unary minus. .PP Neither entire arrays nor functions can be passed as function parameters. .SH FILES .PD 0 .TP 30 .C /usr/bin/dc desk calculator executable program .TP .C /usr/lib/lib.b mathematical library .PD .SH SEE ALSO bs(1), dc(1). .PP .I "bc" tutorial in .I "Number Processing Users Guide" .SH STANDARDS CONFORMANCE .CR bc ": XPG4, POSIX.2" .\" .\" index@\f4bc\f1 \- arbitrary-precision arithmetic language@@@\f3bc(1)\f1 .\" index@arbitrary-precision arithmetic language@@@\f3bc(1)\f1 .\" index@arithmetic language, arbitrary-precision@@@\f3bc(1)\f1 .\" index@language: arbitrary-precision arithmetic language@@@\f3bc(1)\f1 .\" .\" toc@\f3bc(1)\f1:\0\0\f4bc\f1@@@arbitrary-precision arithmetic language .\" .\" fileset_database@bc.1 USER-CMDS-MAN .\" $XConsortium: bdftopcf.man /main/7 1995/12/15 13:59:30 gildea $ .\" Copyright (c) 1993, 1994 X Consortium .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the .\" "Software"), to deal in the Software without restriction, including .\" without limitation the rights to use, copy, modify, merge, publish, .\" distribute, sublicense, and/or sell copies of the Software, and to .\" permit persons to whom the Software is furnished to do so, subject to .\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included .\" in all copies or substantial portions of the Software. .\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR .\" OTHER DEALINGS IN THE SOFTWARE. .\" .\" Except as contained in this notice, the name of the X Consortium shall .\" not be used in advertising or otherwise to promote the sale, use or .\" other dealings in this Software without prior written authorization .\" from the X Consortium. .TH BDFTOPCF 1 "Release 6.1" "X Version 11" .SH NAME bdftopcf \- convert X font from Bitmap Distribution Format to Portable Compiled Format .SH SYNOPSIS .B bdftopcf [ .BI \-p n ] [ .BI \-u n ] [ .B \-m ] [ .B \-l ] [ .B \-M ] [ .B \-L ] [ .B \-t ] [ .B \-i ] [ .B \-o .I outputfile ] fontfile.bdf .SH DESCRIPTION .I Bdftopcf is a font compiler for the X server and font server. Fonts in Portable Compiled Format can be read by any architecture, although the file is structured to allow one particular architecture to read them directly without reformatting. This allows fast reading on the appropriate machine, but the files are still portable (but read more slowly) on other machines. .SH OPTIONS .TP 8 .B \-p\fIn\fP Sets the font glyph padding. Each glyph in the font will have each scanline padded in to a multiple of \fIn\fP bytes, where \fIn\fP is 1, 2, 4 or 8. .TP 8 .B \-u\fIn\fP Sets the font scanline unit. When the font bit order is different from the font byte order, the scanline unit \fIn\fP describes what unit of data (in bytes) are to be swapped; the unit \fIi\fP can be 1, 2 or 4 bytes. .TP 8 .B \-m Sets the font bit order to MSB (most significant bit) first. Bits for each glyph will be placed in this order; i.e., the left most bit on the screen will be in the highest valued bit in each unit. .TP 8 .B \-l Sets the font bit order to LSB (least significant bit) first. The left most bit on the screen will be in the lowest valued bit in each unit. .TP 8 .B \-M Sets the font byte order to MSB first. All multi-byte data in the file (metrics, bitmaps and everything else) will be written most significant byte first. .TP 8 .B \-L Sets the font byte order to LSB first. All multi-byte data in the file (metrics, bitmaps and everything else) will be written least significant byte first. .TP 8 .B \-t When this option is specified, .I bdftopcf will convert fonts into "terminal" fonts when possible. A terminal font has each glyph image padded to the same size; the X server can usually render these types of fonts more quickly. .TP 8 .B \-i This option inhibits the normal computation of ink metrics. When a font has glyph images which do not fill the bitmap image (i.e., the "on" pixels don't extend to the edges of the metrics) .I bdftopcf computes the actual ink metrics and places them in the .pcf file; the \-t option inhibits this behaviour. .TP 8 .BI "\-o " output-file-name By default .I bdftopcf writes the pcf file to standard output; this option gives the name of a file to be used instead. .SH "SEE ALSO" X(1) .SH AUTHOR Keith Packard, MIT X Consortium .\" $Header: bdiff.1,v 76.1 95/07/10 16:52:48 ssa Exp $ .\" Copyright Hewlett-Packard Company .TA b .TH bdiff 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bdiff \- diff for large files .SH SYNOPSIS .C bdiff .I file1 file2 .RI [ \|n\| ] .RC [ -s ] .SH DESCRIPTION .C bdiff compares two files and produces output identical to what would be produced by .C diff (see .IR diff (1)), specifying changes that must be made to make the files identical. .C bdiff is designed for handling files that are too large for .CR diff , but it can be used on files of any length. .PP .C bdiff processes files as follows: .RS .TP 3 \(bu Ignore lines common to the beginning of both files. .TP \(bu Split the remainder of each file into .IR n -line segments, then execute .C diff on corresponding segments. The default value of .I n is 3500. .SS Command-Line Arguments .C bdiff recognizes the following command-line arguments: .RS .TP 12 .I file1 .PD 0 .TP .I file2 .sp -2v Names of two files to be compared by .CR bdiff . If .I file1 or .I file2 (but not both) is .CR - , standard input is used instead. .PD .TP .I n If a numeric value is present as the third argument, the files are divided into .IR n -line segments before processing by .CR diff . Default value for .I n is 3500. This option is useful when 3500-line segments are too large for processing by .CR diff . .TP .C -s Silent option suppresses diagnostic printing by .CR bdiff , but does not suppress possible error messages from .CR diff ). If the .I n and .C -s arguments are both used, the .I n argument must precede the .C -s option on the command line or it will not be properly recognized. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C bdiff behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS .TP 10 .C "both files standard input (bd2)" Standard input was specified for both files. Only one file can be specified as standard input. .TP .C "non-numeric limit (bd4)" A non-numeric value was specified for the .I n (third) argument. .SH EXAMPLES Find differences between two large files: .C file1 and .CR file2 , and place the result in a new file named .CR diffs_1.2 . .IP .C "bdiff file1 file2 >diffs_1.2 .PP Do the same, but limit file length to 1400 lines; suppress error messages: .IP .C "bdiff file1 file2 1400 -s >diffs_1.2" .SH WARNINGS .C bdiff produces output identical to output from .CR diff , and makes the necessary line-number corrections so that the output looks like it was processed by .CR diff . However, depending on where the files are split, .C bdiff may or may not find a fully minimized set of file differences. .SH FILES .C /tmp/bd?????? .SH SEE ALSO diff(1). .\" index@\f4bdiff\f1 \- big diff@@@\f3bdiff(1)\f1 .\" index@\f1big diff@@@\f3bdiff(1)\f1 .\" index@\f1diff, big@@@\f3bdiff(1)\f1 .\" index@\f1differences between large files, find@@@\f3bdiff(1)\f1 .\" index@\f1large files, find differences between@@@\f3bdiff(1)\f1 .\" index@\f1long files, find differences between@@@\f3bdiff(1)\f1 .\" .\" toc@\f3bdiff(1)\f1:\0\0\f4bdiff\f1@@@diff for large files .\" .\" $Header: bfs.1,v 72.3 93/01/14 11:18:01 ssa Exp $ .TA b .TH bfs 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bfs \- big file scanner .SH SYNOPSIS .C bfs .RC [ - ] .I name .SH DESCRIPTION .C bfs is similar to .C ed except that it is read-only (see .IR ed (1)) .C bfs can handle files with up to 32K \(mi 1 lines; each line can contain up to 512 characters, including the new-line character. .C bfs is usually more efficient than .C ed for scanning a file, since the file is not copied to a buffer. Historically, this command was most useful for identifying sections of a large file where .C csplit could be used to divide it into more manageable pieces for editing (see .IR csplit (1)). However, most editors now support files larger than the above-mentioned limits. .PP Normally, the size of the file being scanned is printed, as is the size of any file written with the .C w command. The optional .C - suppresses printing of sizes. Input is prompted with .C * if .C P and a carriage-return are typed, as in .CR ed . Prompting can be turned off again by inputting another .C P and pressing Return. Note that messages are given in response to errors if prompting is turned on. .PP .C bfs supports the Basic Regular Expression .SM (RE) syntax (see .IR regexp (5)) with the addition that a null .SM RE (e.g., .CR // ) is equivalent to the last .SM RE encountered. All address expressions described under .C ed are supported. In addition, regular expressions can be surrounded with two symbols besides .C / and .CR ? : .C > indicates downward search without wrap-around, and .C < indicates upward search without wrap-around. There is a slight difference in mark names: only the letters .C a through .C z can be used, and all 26 marks are remembered. .PP The .CR e , .CR g , .CR v , .CR k , .CR n , .CR p , .CR q , .CR w , .CR = , .C ! and null commands operate as described under .CR ed . Commands such as .CR --- , .CR +++- , .CR +++= , .CR -12 , and .C +4p are accepted. Note that .C 1,10p and .C 1,10 both print the first ten lines. The .C f command only prints the name of the file being scanned; there is no .I remembered file name. The .C w command is independent of output diversion, truncation, or crunching (see the .CR xo , .CR xt , and .C xc commands, below). The following additional commands are available: .TP 15 .CI xf " file" Further commands are taken from the named .IR file . When an end-of-file is reached, an interrupt signal is received or an error occurs, reading resumes with the file containing the .CR xf . .C Xf commands may be nested to a depth of 10. .TP .CI xo " \f1[\|\fPfile\f1\|]\fP" Further output from the .C p and null commands is diverted to the named .IR file , which, if necessary, is created mode 666. If .I file is missing, output is diverted to the standard output. Note that each diversion causes truncation or creation of the file. .TP .CI : " label" This positions a .I label in a command file. .I label is terminated by a new-line, and blanks between the .C : and the start of .I label are ignored. This command can also be used to insert comments into a command file, since labels need not be referenced. .TP .RC ( .,. ) "xb/\f2\s-1regular expression\fP\s0/\f2\s-1label\fP\s0" A jump (either upward or downward) is made to .I label if the command succeeds. It fails under any of the following conditions: .RS .RS .TP 4 1. Either address is not between .C 1 and .CR $ . .PD 0 .TP 2. The second address is less than the first. .TP 3. The regular expression does not match at least one line in the specified range, including the first and last lines. .RE .RE .PD .IP On success, .C . is set to the line matched and a jump is made to .IR label . This command is the only one that does not issue an error message on bad addresses. Thus it can be used to test whether addresses are bad before other commands are executed. Note that the command .RS .IP .CI xb/ label .RE .IP is an unconditional jump. .IP The .C xb command is allowed only if it is read from someplace other than a terminal. If it is read from a pipe only a downward jump is possible. .TP .C xn List the marks currently in use (marks are set by the .C k command). .TP .CI xt " number" Output from the .C p and null commands is truncated to at most .I number characters. The initial number is 255. .TP .CR xv [\f2digit\f1]\|[\f2spaces\f1]\|[\f2value\f1] The variable name is the specified .I digit following the .CR xv . .C xv5100 or .C xv5 100 both assign the value .C 100 to the variable .CR 5 . .C Xv61,100p assigns the value .C 1,100p to the variable .CR 6 . To reference a variable, put a .C % in front of the variable name. For example, using the above assignments for variables .C 5 and .CR 6 : .RS .IP .C 1,%5p .br .C 1,%5 .br .C %6 .RE .IP all print the first 100 lines. .RS .IP .C g/%5/p .RE .IP globally searches for the characters .C 100 and prints each line containing a match. To escape the special meaning of .CR % , a .C \e must precede it. For example, to match and list lines in a program file that contain .C printf() format strings specifying characters, decimal integers, or strings, the following could be used: .RS .IP .ift \f4\s+1g/".*\e%[cds]/p\s0\fP .ifn \f3g/".*\e%[cds]/p\fP .RE .IP Another feature of the .C xv command is that the first line of output from an .SM HP-UX command can be stored into a variable. The only requirement is that the first character of .I value be an .CR ! . For example: .RS .nf .IP .C .w junk .C xv5!cat junk .C !rm junk .ift \f4\s+1!echo "%5"\s0\fP .ifn \f3!echo "%5"\fP .C xv6!expr %6 + 1 .fi .RE .IP each put the current line into variable .CR 5 , print it, and increment the variable .C 6 by one. To escape the special meaning of .C ! as the first character of .IR value , precede it with a .CR \e . .RS .IP .C xv7\e!date .RE .IP stores the value .C !date into variable .CR 7 . .TP .CI xbz " label" .PD 0 .TP .CI xbn " label" These two commands test the last saved .I return code from the execution of an .SM HP-UX system command .RC ( ! \f2command\fP\|) for a zero or non-zero value, respectively, and cause a branch to the specified label. The two examples below both search for the next five lines containing the string .CR size . .PD .IP First example: .RS .nf .IP .C xv55 .C : l .C /size/ .C xv5!expr %5 - 1 .C !if [ %5 != 0 ] ; then exit 2 ; fi .C xbn l .fi .RE .IP Second Example: .RS .nf .IP .C xv45 .C : l .C /size/ .C xv4!expr %4 - 1 .C !if [ %4 = 0 ] ; then exit 2 ; fi .C xbz l .fi .RE .TP .CR xc \0[\|\f2switch\fP\|] If .I switch is .CR 1 , output from the .C p and null commands is crunched; if .I switch is .C 0 it isn't. Without an argument, .C xc reverses .IR switch . Initially .I switch is set for no crunching. Crunched output has strings of tabs and blanks reduced to one blank, and blank lines suppressed. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the collating sequence used in evaluating regular expressions. .PP .C LC_CTYPE determines the classification of characters as letters, and the characters matched by character class expressions in regular expressions. .PP If .C LC_COLLATE or .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang(5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C bfs behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte character code sets are supported. .SH DIAGNOSTICS .C ? for errors in commands, if prompting is turned off. Self-explanatory error messages when prompting is on. .\" .SH EXAMPLES (not needed -- see above) .SH SEE ALSO csplit(1), ed(1), lang(5), regexp(5). .\" .\" toc@\f3bfs(1)\f1:\0\0\f4bfs\f1@@@big file scanner .\" .\" index@\f4bfs\f1 \- big file scanner@@@\f3bfs(1)\f1 .\" index@big file scanner@@@\f3bfs(1)\f1 .\" index@files: big file scanner@@@\f3bfs(1)\f1 .\" index@scanner, big file@@@\f3bfs(1)\f1 .\" .\" fileset_database@bfs.1 USER-CMDS-MAN .\" $Header: sh-posix.1,v 76.4 95/11/02 14:15:41 ssa Exp $ .TA s .TH sh-posix 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sh, rsh \- standard and restricted POSIX.2-conformant command shells .SH SYNOPSIS .CR sh .RC [{ \- \(or + }\c .CR aefhikmnprstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [ \-c .IR string ] .IR arg ]...\& .PP .CR rsh .RC [{ \- \(or + }\c .CR aefhikmnprstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [ \-c .IR string ] .RI [ arg ]...\& .SS Remarks This shell is intended to conform to the shell specification of the POSIX.2 .I Shell and Utility standards. Check any standards conformance documents shipped with your system for information on the conformance of this shell to any other standards. .SS List of Subheadings in DESCRIPTION .\" .SS lines under DESCRIPTION (commands are vi/ex) .\" Extract header lines; copy to eof ":g/\.S[SH]/co$: .\" Delete extraneous leading and trailing headings .\" Delete .SS ":.,$s/....//" .\" Form into columns ":.,$!pr -3 -t -s@" .\" Replace pr tabs with blanks ":.,$s/[[:space:]]/ /g" .\" Move into place below. .TS tab(@); l l l . Shell Invocation@Tilde Substitution@Environment Options@Command Substitution@Functions rsh Restrictions@Parameter Substitution@Jobs Definitions@Blank Interpretation@Signals Commands@File Name Generation@Execution Simple Commands@Quoting@Command Reentry Compound Commands@Arithmetic Evaluation@Command Line Editing Special Commands@Prompting@emacs Editing Mode Comments@Conditional Expressions@vi Editing Mode Aliasing@Input/Output .TE .SH DESCRIPTION .CR sh is a command programming language that executes commands read from a terminal or a file. .PP .CR rsh is a restricted version of .CR sh . See the "rsh Restrictions" subsection below. .SS Shell Invocation If the shell is invoked by an .CI exec * () system call and the first character of argument zero (shell parameter .CR 0 ) is dash .RC ( \- ), the shell is assumed to be a login shell and commands are read first from .CR /etc/profile , then from either .CR .profile in the current directory or .CR $HOME/.profile if either file exists, and finally from the file named by performing parameter substitution on the value of the environment parameter .CR ENV , if the file exists. If the .CR \-s option is not present and an .I arg is, a path search is performed on the first .I arg to determine the name of the script to execute. When running .CR sh with .IR arg , the script .I arg must have read permission and any .CR setuid and .CR setgid settings will be ignored. Commands are read as described below. .PP Shell output, except for the output of some of the commands listed in the "Special Commands" subsection, is written to standard error (file descriptor 2). .SS Options The following options are interpreted by the shell when it is invoked. .TP 15 .CI \-c \0string Read commands from .IR string . .TP .CR \-i If .CR \-i is present or if the shell input and output are attached to a terminal (as reported by .CR tty() ), the shell is interactive. In this case .CR SIGTERM is ignored (so that .CR "kill 0" does not kill an interactive shell) and .CR SIGINT is caught and ignored (so that .CR wait is interruptible). In all cases, .CR SIGQUIT is ignored by the shell. See .IR signal (5). .TP .CR \-r The shell is a restricted shell. .TP .CR \-s If .CR \-s is present or if no arguments remain, commands are read from the standard input. .PP The remaining options and arguments are described under the .CR set command in the "Special Commands" subsection. .SS rsh Restrictions .CR rsh is used to set up login names and execution environments where capabilities are more controlled than those of the standard shell. The actions of .CR rsh are identical to those of .CR sh , except that the following are forbidden: .RS .TP 3 .PD 0 \(bu Changing directory (see the .CR cd special command and .IR cd (1)) .TP \(bu Setting the value of .CR SHELL , .CR ENV , or .CR PATH .TP \(bu Specifying path or command names containing .CR / .TP \(bu Redirecting output .RC ( > , .CR >| , .CR <> , and .CR >> ) .PD .RE .PP The restrictions above are enforced after the .CR .profile and .CR ENV files are interpreted. .PP When a command to be executed is found to be a shell procedure, .CR rsh invokes .CR sh to execute it. Thus, the end-user is provided with shell procedures accessible to the full power of the standard shell, while being restricted to a limited menu of commands. This scheme assumes that the end-user does not have write and execute permissions in the same directory. .PP These rules effectively give the writer of the .CR .profile file complete control over user actions, by performing guaranteed set-up actions and leaving the user in an appropriate directory (probably not the login directory). .PP The system administrator often sets up a directory of commands (usually .CR /usr/rbin ) that can be safely invoked by .CR rsh . HP-UX systems provide a restricted editor .CR red (see .IR ed (1)), suitable for restricted users. .SS Definitions .TP 20 .B metacharacter One of the following characters: .IP .CR "; & ( ) | < >" \0newline\0space\0tab .TP .B blank A tab or a space. .TP .B identifier A sequence of letters, digits, or underscores starting with a letter or underscore. Identifiers are used as names for .BR functions and .BR "named parameters" . .TP .B word A sequence of .B characters separated by one or more nonquoted .BR metacharacters . .TP .BR command A sequence of characters in the syntax of the shell language. The shell reads each command and carries out the desired action, either directly or by invoking separate utilities. .TP .B "special command" A command that is carried out by the shell without creating a separate process. Except for documented side effects, most special commands can be implemented as separate utilities. .TP .CR # Comment delimiter. A word beginning with .CR # and all following characters up to a newline are ignored. .TP .B parameter An .BR identifier , a decimal number, or one of the characters .CR ! , .CR # , .CR $ , .CR * , .CR \- , .CR ? , .CR @ , and .CR _ . See the "Parameter Substitution" subsection. .TP .B "named parameter" A .B parameter that can be assigned a value. See the "Parameter Substitution" subsection. .TP .B variable A .BR parameter . .TP .B "environment variable" A .BR parameter that is known outside the local shell, usually by means of the .CR export special command. .SS Commands A command can be a simple command that executes an executable file, a special command that executes within the shell, or a compound command that provides flow of control for groups of simple, special, and compound commands. .SS Simple Commands A simple command is a sequence of blank-separated words that may be preceded by a parameter assignment list. (See the "Environment" subsection). The first word specifies the name of the command to be executed. Except as specified below, the remaining words are passed as arguments to the invoked command. The command name is passed as argument .CR 0 (see .IR exec (2)). The .I value of a simple-command is its exit status if it terminates normally, or .CI 128+ errorstatus if it terminates abnormally (see .IR signal (5) for a list of .I errorstatus values). .PP A .B pipeline is a sequence of one or more commands separated by a bar .RC ( | ) and optionally preceded by an exclamation mark .RC ( ! ). The standard output of each command but the last is connected by a pipe (see .IR pipe (2)) to the standard input of the next command. Each command is run as a separate process; the shell waits for the last command to terminate. If .CR !\& does not precede the pipeline, the exit status of the pipeline is the exit status of the last command in the pipeline. Otherwise, the exit status of the pipeline is the logical negation of the exit status of the last command in the pipeline. .PP A .I list is a sequence of one or more pipelines separated by .CR ; , .CR & , .CR && , or .CR || , and optionally terminated by .CR ; , .CR & , or .CR |& . .RS .TP .CR ;\& Causes sequential execution of the preceding pipeline. An arbitrary number of newlines can appear in a .I list, instead of semicolons, to delimit commands. .TP .CR & Causes asynchronous execution of the preceding pipeline (that is, the shell does not wait for that pipeline to finish). .TP .CR |& Causes asynchronous execution of the preceding command or pipeline with a two-way pipe established to the parent shell. The standard input and output of the spawned command can be written to and read from by the parent shell using the .CR \-p option of the special commands .CR read and .CR print . .TP .CR && Causes the .I list following it to be executed only if the preceding pipeline returns a zero value. .TP .CR || Causes the .I list following it to be executed only if the preceding pipeline returns a nonzero value. .RE .PP Of these five symbols, .CR ; , .CR & , and .CR |& have equal precedence, which is lower than that of .CR && and .CR || . The symbols .CR && and .CR || also have equal precedence. .SS Compound Commands Unless otherwise stated, the value returned by a compound command is that of the last simple command executed in the compound command. The .CR ;\& segment separator can be replaced by one or more newlines. .PP The following keywords are recognized only as the first word of a command and when not quoted: .nf .RS .IP .C "! } elif for then" .C "[[ case else function time" .C "]] do esac if until" .C "{ done fi select while" .fi .RE .PP A compound command is one of the following. .PP .ne 3v .CR case \f2\0word\c .CR \0in \0[\|[ ; ]\0[ ( ]\c .IC \0pattern\0\f1[ | \0pattern\f1]... ) \0list\0\c .CR ;; ]...\0 ;\0esac .IP Execute the .I list associated with the first .I pattern that matches .IR word . The form of the patterns is identical to that used for file name generation (see the "File Name Generation" subsection). The .CR ;;\& case terminator cannot be replaced by newlines. .PP .ne 3v .CI for \0identifier\f1\0[ in \0word\f1\0...]\0\c .CR ;\0do \0\f2list\0 ;\0done .IP Set .I identifier to each .I word in sequence and execute the .CR do .IR list . If .CR in .IR word .RI ...\& is omitted, set .I identifier to each set positional parameter instead. See the "Parameter Substitution" subsection. Execution ends when there are no more positional parameters or words in the list. .PP .ne 4v .CI function \0identifier\0 { \0list\0 ;\0} .br .IC identifier \0()\0{ \0list\0 ;\0} .IP Define a function named by .IR identifier . A function is called by executing its identifier as a command. The body of the function is the .I list of commands between .CR { and .CR } . See the "Functions" subsection. .PP .ne 3v .CI if \0list\0 ;\0then \0list\0 ; \0\f1[\c .CI elif \0list\0 ;\0then \0list\0 ; \f1]...\&\0[\c .CI else \0list\0 ; \f1]\0 fi .IP Execute the .CR if .I list and, if its exit status is zero, execute the first .CR then .IR list . Otherwise, execute the .CR elif .I list (if any) and, if its exit status is zero, execute the next .CR then .IR list . Failing that, execute the .CR else .I list (if any). If no .CR else .I list or .CR then .I list is executed, .CR if returns a zero exit status. .PP .ne 3v .CI select \0identifier\0\f1[ in \0word\f1\0...\&]\0 ;\0do \0list\0\c .CI ;\0done .IP Print the set of .IR word s on standard error (file descriptor 2), each preceded by a number. If .CI in .IR word .RI ...\& is omitted, print the positional parameters instead (see the "Parameter Substitution" subsection). Print the .CR PS3 prompt and read a line from standard input into the parameter .CR REPLY . If this line consists of the number of one of the listed .IR word s, set .I identifier to the corresponding .IR word , execute .IR list , and repeat the .CR PS3 prompt. If the line is empty, print the selection list again, and repeat the .CR PS3 prompt. Otherwise, set .I identifier to null, execute .IR list , and repeat the .CR PS3 prompt. The select loop repeats until a .CR break special command or end-of-file is encountered. .PP .ne 3v .CI time \0pipeline .IP Execute the .I pipeline and print the elapsed time, the user time, and the system time on standard error. See also .IR time (1). .PP .ne 3v .CI "until\0" list "\0;\0do\0" list "\0;\0done" .IP Execute the .CR until .IR list . If the exit status of the last command in the list is nonzero, execute the .CR do .IR list and execute the .CR until .IR list again. When the exit status of the last command in the .CR until .I list is zero, terminate the loop. If no commands in the .CR do .I list are executed, .CR until returns a zero exit status. .PP .ne 3v .CI "while\0" list "\0;\0do\0" list "\0;\0done" .IP Execute the .CR while .IR list . If the exit status of the last command in the list is zero, execute the .CR do .IR list and execute the .CR while .IR list again. When the exit status of the last command in the .CR while .I list is nonzero, terminate the loop. If no commands in the .CR do .I list are executed, .CR while returns a nonzero exit status. .PP .ne 3v .CI ( "\0list\0" ) .IP Execute .I list in a separate environment. If two adjacent open parentheses are needed for nesting, a space must be inserted between them to avoid arithmetic evaluation. .PP .ne 3v .CI { "\0list\0" ";\0}" .IP Execute .IR list , but not in a separate environment. Note that .CR { is a keyword and requires a trailing blank to be recognized. .PP .ne 3v .CI [[ "\0expression\0" ]] .IP Evaluate .I expression and return a zero exit status when .I expression is true. See the "Conditional Expressions" subsection for a description of .IR expression . Note that .CR [[ and .CR ]] are keywords and require blanks between them and .IR expression . .SS Special Commands Special commands are simple commands that are executed in the shell process. They permit input/output redirection. Unless otherwise indicated, file descriptor 1 (standard output) is the default output location and the exit status, when there are no syntax errors, is zero. .PP Commands that are marked with \(dg or \(dg\(dg are treated specially in the following ways: .RS .TP 3 .PD 0 1. Variable assignment lists preceding the command remain in effect when the command completes. .TP 2. I/O redirections are processed after variable assignments. .TP 3. Errors cause a script that contains them to abort. .TP 4. Words following a command preceded by \(dg\(dg that are in the format of a variable assignment are expanded with the same rules as a variable assignment. This means that tilde substitution is performed after the .CR = sign and word-splitting and file-name generation are not performed. .PD .RE .PP .ne 3v \(dg .CR : \0[\f2arg\f1]...\& .IP (colon)\0 Only expand parameters. A zero exit status is returned. .PP .ne 3v \(dg .CI . \0file\f1\0[\f2arg\f1]...\& .IP (period)\0 Read and execute commands from .I file and return. The commands are executed in the current shell environment. The search path specified by .CR PATH is used to find the directory containing .IR file . If any arguments .I arg are given, they become the positional parameters. Otherwise, the positional parameters are unchanged. The exit status is the exit status of the last command executed. .PP .ne 3v \(dg\(dg .CR alias \0[ \-tx ]\0[\f2name\f1[\c .CI = value\f1]\|]...\& .IP With .IC name = value specified, define .I name as an alias and assign it the value .IR value . A trailing space in .I value causes the next word to be checked for alias substitution. .IP With .IC name = value omitted, print the list of aliases in the form .IC name = value on standard output. .IP With .I name specified without .CI = value\f1, print the specified alias. .IP With .CR \-t , set tracked aliases. The value of a tracked alias is the full path name corresponding to the given .IR name . The value of a tracked alias becomes undefined when the value of .CR PATH is reset, but the alias remains tracked. With .IC name = value omitted, print the list of tracked aliases in the form .IC name = pathname on standard output. .IP With .CR \-x , set exported aliases. An exported alias is defined across subshell environments. With .IC name = value omitted, print the list of exported aliases in the form .IC name = value on standard output. .IP Alias returns true unless a .I name is given for which no alias has been defined. .PP .ne 3v .CR bg \0[\f2job\f1]...\& .IP Put the specified .I jobs into the background. The current job is put in the background if .I job is unspecified. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v \(dg .CR break \0[\f2n\f1] .IP Exit from the enclosing .CR for , .CR select , .CR until , or .CR while loop, if any. If .I n is specified, exit from .I n levels. .PP .ne 4v .CR cd \0[ \-L \(or \-P ]\0[\f2arg\f1] .br .CI cd \0old\0new .IP In the first form, change the current working directory .RC ( PWD ) to .IR arg . If .I arg is .CR \- , the directory is changed to the previous directory .RC ( OLDPWD ). .IP With .CR \-L (default), preserve logical naming when treating symbolic links. .CR "cd \-L ..\&" moves the current directory one path component closer to the root directory. .IP With .CR \-P , preserve the physical path when treating symbolic links. .CR "cd \-P ..\&" changes the working directory to the actual parent directory of the current directory. .IP The shell parameter .CR HOME is the default .IR arg . The parameter .CR PWD is set to the current directory. .IP The shell parameter .CR CDPATH defines the search path for the directory containing .IR arg . Alternative directory names are separated by a colon .RC ( : ). If .CR CDPATH is null or undefined, the default value is the current directory. Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If .I arg begins with a .CR / , the search path is not used. Otherwise, each directory in the path is searched for .IR arg . See also .IR cd (1). .IP The second form of .CR cd substitutes the string .I new for the string .I old in the current directory name, .CR PWD , and tries to change to this new directory. .PP .ne 3v .CR command \0[\f2arg\f1]...\& .IP Treat .I arg as a command, but disable function lookup on .IR arg . See .IR command (1) for usage and description. .PP .ne 3v \(dg .CR continue \0[\f2n\f1] .IP Resume the next iteration of the enclosing .CR for , .CR select , .CR until , or .CR while loop. If .I n is specified, resume at the .IR n th enclosing loop. .PP .ne 3v .CR echo \0[\f2arg\f1]...\& .IP Print .I arg on standard output. See .IR echo (1) for usage and description. See also the .CR print special command. .PP .ne 3v \(dg .CR eval \0[\f2arg\f1]...\& .IP Read the arguments as input to the shell and execute the resulting commands. Allows parameter substitution for keywords and characters that would otherwise be unrecognized in the resulting commands. .PP .ne 3v \(dg .CR exec \0[\f2arg\f1]...\& .IP Parameter assignments remain in effect after the command completes. If .I arg is given, execute the command specified by the arguments in place of this shell without creating a new process. Input/output arguments may appear and affect the current process. If no arguments are given, modify file descriptors as prescribed by the input/output redirection list. In this case, any file descriptor numbers greater than 2 that are opened with this mechanism are closed when another program is invoked. .PP .ne 3v \(dg .CR exit \0[\f2n\f1] .IP Exit from the shell with the exit status specified by .IR n . If .I n is omitted, the exit status is that of the last command executed. An end-of-file also causes the shell to exit, except when a shell has the .CR ignoreeof option set. (See the .CR set special command.) .PP .ne 4v \(dg\(dg .CR export \0[\f2name\f1[ = \f2value\f1]\|]...\& .br \(dg\(dg .CR export\0\-p .IP Mark the given variable .IR name s for automatic export to the environment of subsequently executed commands. Optionally, assign values to the variables. .IP With .CR \-p , write the names and values of all exported variables to standard output, in a format with the proper use of quoting, so that it is suitable for re-input to the shell as commands that achieve the same exporting results. .PP .ne 6v .CR fc \0[ \-r ]\0[ \-e \0\f2ename\f1]\0[\f2first\f1\0[\f2last\f1]\|] .br .CR fc\0\-l \0[ \-nr ]\0[\f2first\f1\0[\f2last\f1]\|] .br .CR fc\0\-s \0[\f2old\f1 = \f2new\f1]\0[\f2first] .br .CR fc\0\-e\0\- \0[\f2old\f1 = \f2new\f1]\0[\f2command\f1] .IP List, or edit and reexecute, commands previously entered to an interactive shell. A range of commands from .I first to .I last is selected from the last .CR HISTSIZE commands typed at the terminal. The arguments .I first and .I last can be specified as a number or string. A given string is used to locate the most recent command. A negative number is used to offset the current command number. .IP With .CR \-l , list the commands on standard output. Without .CR \-l , invoke the editor program .I ename on a file containing these keyboard commands. If .I ename is not supplied, the value of the parameter .CR FCEDIT (default .CR /usr/bin/ed ) is used as the editor. Once editing has ended, the commands (if any) are executed. If .I last is omitted, only the command specified by .I first is used. If .I first is not specified, the default is the previous command for editing and \(mi16 for listing. .IP With .CR \-r , reverse the order of the commands. .IP With .CR \-n , suppress command numbers when listing. .IP With .CR \-s , reexecute the command without invoking an editor. .IP The .IC old = new argument replaces the first occurrence of string .IC old in the command to be reexecuted by the string .IR new . .PP .ne 3v .CR fg \0[\f2job\f1]...\& .IP Bring each .I job into the foreground in the order specified. If no .I job is specified, bring the current job into the foreground. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v .CR getopts \0\f2optstring\0name\f1\0[\f2arg\f1]...\& .IP Parse the argument list, or the positional parameters if no arguments, for valid options. On each execution, return the next option in .IR name . See .IR getopts (1) for usage and description. .IP An option begins with a .CR + or a .CR \- . An argument not beginning with .CR + or .CR \- , or the argument .CR \-\- , ends the options. .I optstring contains the letters that .CR getopts recognizes. If a letter is followed by a .CR : , that option is expected to have an argument. The options can be separated from the argument by blanks. .IP For an option specified as .CI \- letter\f1, .I name is set to .IR letter . For an option specified as .CI + letter\f1, .I name is set to .CI + letter\f1. The index of the next .I arg is stored in .CR OPTIND . The option argument, if any, is stored in .CR OPTARG . If no option argument is found, or the option found does not take an argument, .CR OPTARG is unset. .IP A leading .CR :\& in .I optstring causes .CR getopts to store the letter of an invalid option in .CR OPTARG , and to set .I name to .CR ?\& for an unknown option and to .CR :\& when a required option argument is missing. Otherwise, .CR getopts prints an error message. The exit status is nonzero when there are no more options. .PP .ne 4v .CR hash \0[\f2utility\f1]...\& .br .CR hash\0\-r .IP Affect the way the current shell environment remembers the locations of utilities. With .IR utility , add utility locations to a list of remembered locations. With no arguments, print the contents of the list. With .CR \-r , forget all previously remembered utility locations. .PP .ne 3v .CR jobs \0[ \-lnp ]\0[\f2job\f1]...\& .IP List information about each given job, or all active jobs if .I job is not specified. With .CR \-l , list process IDs in addition to the normal information. With .CR \-n , display only jobs that have stopped or exited since last notified. With .CR \-p , list only the process group. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 5v .CR kill \0[ \-s \0\f2signal\f1]\0\f2process\f1\0...\& .br .CR kill\0\-l .br .CR kill \0[ \- \f2signal\f1]\0\f2process\f1\0...\& .IP Send either signal 15 .RC ( SIGTERM , terminate) or the specified .I signal to the specified jobs or processes. See .IR kill (1) for usage and description. .IP With .CR \-l , list the signal names and numbers. .PP .ne 4v .CI let \0arg\f1\0... .br .CI (( \0arg\f1\0... )) .IP Evaluate each .I arg as a separate arithmetic expression. See the "Arithmetic Evaluation" subsection for a description of arithmetic expression evaluation. The exit status is 0 if the value of the last expression is nonzero, and 1 otherwise. .PP .ne 3v \(dg .CR newgrp \0[ \- ]\0[\f2group\f1] .IP Replace the current shell with a new one having .I group as the user's group. The default group is the user's login group. With .CR \- , the user's .CR .profile and .CR $ENV files are also executed. See .IR newgrp (1) for usage and description. Equivalent to .CI "exec\0newgrp" "\0arg\0\f1...." .PP .ne 3v .CR print \0[ \-nprRsu [\f2n\f1]\|]\0[\f2arg\f1]...\& .IP The shell output mechanism. With no options or with option .CR \- or .CR \-\- , print the arguments on standard output as described in .IR echo (1). See also .IR printf (1). .IP With .CR \-n , do not add a newline character to the output. .IP With .CR \-p , write the arguments onto the pipe of the process spawned with .CR |& instead of standard output. .IP With .CR \-R or .CR \-r (raw mode), ignore the escape conventions of .CR echo . With .CR \-R , print all subsequent arguments and options other than .CR \-n . .IP With .CR \-s , write the arguments into the history file instead of to standard output. .IP With .CR \-u , specify a one-digit file descriptor unit number .I n on which the output will be placed. The default is .CR 1 (standard output). .PP .ne 3v .CR pwd \0[ \-L \(or \-P ] .IP Print the name of the current working directory (equivalent to .CR "print\0\-r\0\-\0$PWD" ). With .CR \-L (the default), preserve the logical meaning of the current directory. With .CR \-P , preserve the physical meaning of the current directory if it is a symbolic link. See also the .CR cd special command, .IR cd (1), .IR ln (1), and .IR pwd (1). .PP .ne 3v .CR read \0[ \-prsu [\f2n\f1]\|]\0[\f2name\f1 ? \f2prompt\f1]\0[\f2name\f1]...\& .IP The shell input mechanism. Read one line (by default, from standard input) and break it up into words using the characters in .CR IFS as separators. The first word is assigned to the first .IR name , the second word to the second .IR name , and so on; the remaining words are assigned to the last .IR name . See also .IR read (1). The return code is .CR 0 , unless an end-of-file is encountered. .IP With .CR \-p , take the input line from the input pipe of a process spawned by the shell using .CR |& . An end-of-file with .CR \-p causes cleanup for this process so that another process can be spawned. .IP With .CR \-r (raw mode), a .CR \e at the end of a line does not signify line continuation. .IP With .CR \-s , save the input as a command in the history file. .IP With .CR \-u , specify a one-digit file descriptor unit to read from. The file descriptor can be opened with the .CR exec special command. The default value of .I n is .CR 0 (standard input). If .IR name is omitted, .CR REPLY is used as the default .IR name . .IP If the first argument contains a .CR ? , the remainder of the argument is used as a .I prompt when the shell is interactive. .IP If the given file descriptor is open for writing and is a terminal device, the prompt is placed on that unit. Otherwise, the prompt is issued on file descriptor 2 (standard error). .PP .ne 4v \(dg\(dg .CR readonly \0[\f2name\f1[ = \f2value\f1]\|]...\& .br \(dg\(dg .CR readonly\0\-p .IP Mark the given .IR name s read only. These names cannot be changed by subsequent assignment. .IP With .CR \-p , write the names and values of all read-only variables to standard output in a format with the proper use of quoting so that it is suitable for re-input to the shell as commands that achieve the same attribute-setting results. .PP .ne 3v \(dg .CR return \0[\f2n\f1] .IP Cause a shell function to return to the invoking script with the return status specified by .IR n . If .I n is omitted, the return status is that of the last command executed. Only the low 8 bits of .I n (decimal 0 to 255) are passed back to the caller. If .CR return is invoked while not in a function or a .CR .\& script (see the .CR .\& special command), it has the same effect as an .CR exit command. .PP .ne 3v .CR set .RC [{ \- \(or + }\c .CR abCefhkmnopstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [{ \- \(or + } A .IR name ]\0[ arg ]...\& .IP Set .RC ( \- ) or clear .RC ( + ) execution options or perform array assignments .RC ( \-A ,\ +A ). All options except .CR \-A and .CR +A can be supplied in a shell invocation (see the SYNOPSIS section and the "Shell Invocation" subsection). .IP Using .CR + instead of .CR \- before an option causes the option to be turned off. These options can also be used when invoking the shell. The current list of set single-letter options is contained in the shell variable .CR \- . It can be examined with the command .CR "echo $-" . .IP The .CR \- and .CR + options can be intermixed in the same command, except that there can be only one .CR \-A or .CR +A option. .IP Unless .CR \-A or .CR +A is specified, the remaining .I arg arguments are assigned consecutively to the positional parameters .CR 1 , .CR 2 ,\0.... .IP The .CR set command with neither arguments nor options displays the names and values of all shell parameters on standard output. See also .IR env (1). .IP The options are defined as follows. .RS .TP .CR \-A Array assignment. Unset the variable .I name and assign values sequentially from the list .IR arg . With .CR \+A , do not unset the variable .I name first. .TP .CR \-a Automatically export subsequently defined parameters. .TP .CR \-b Cause the shell to notify the user asynchronously of background jobs as they are completed. When the shell notifies the user that a job has been completed, it can remove the job's process ID from the list of those known in the current shell execution environment. .TP .CR \-C Prevent redirection .CR > from truncating existing files. Requires .CR >| to truncate a file when turned on. .TP .CR \-e Execute the .CR ERR trap, if set, and exit .I if a command has a nonzero exit status, and is not part of the compound list following a .CR if , .CR until , or .CR while keyword, and is not part of an AND or OR list, and is not a pipeline preceded by the .CR !\& reserved word. This mode is disabled while reading profiles. .TP .CR \-f Disable file name generation. .TP .CR \-h Specify that each command whose name is an .I identifier becomes a tracked alias when first encountered. .TP .CR \-k Place all parameter assignment arguments (not just those that precede the command name) into the environment for a command. .TP .CR \-m Run background jobs in a separate process group and print a line upon completion. The exit status of background jobs is reported in a completion message. This option is turned on automatically for interactive shells. .TP .CR \-n Read commands and check them for syntax errors, but do not execute them. The .CR \-n option is ignored for interactive shells. .TP .ne 5v .CR \-o Set an .I option argument from the following list. Repeat the .CR \-o option to specify additional .I option arguments. .RS .TP 15 .PD 0 .CR allexport Same as .CR \-a . .TP .CR bgnice Run all background jobs at a lower priority. .TP .CR errexit Same as .CR \-e . .TP .CR emacs Use a .CR emacs -style inline editor for command entry. .TP .CR gmacs Use a .CR gmacs -style inline editor for command entry. .TP .CR ignoreeof Do not exit from the shell on end-of-file .RI ( eof as defined by .CR stty ; default is .CR ^D ). The .CR exit special command must be used. .TP .CR keyword Same as .CR \-k . .TP .CR markdirs Append a trailing .CR / to all directory names resulting from file name generation. .TP .CR monitor Same as .CR \-m . .TP .CR noclobber Same as .CR \-C . .TP .CR noexec Same as .CR \-n . .TP .CR noglob Same as .CR \-f . .TP .CR nolog Do not save function definitions in history file. .TP .CR notify Same as .CR \-b . .TP .CR nounset Same as .CR \-u . .TP .CR privileged Same as .CR \-p . .TP .CR verbose Same as .CR \-v . .TP .CR trackall Same as .CR \-h . .TP .CR vi Use a .CR vi -style inline editor for command entry. .TP .CR viraw Process each character as it is typed in .CR vi mode. .TP .CR xtrace Same as .CR \-x . .PD .RE .TP .CR \-p Disable processing of the .CR $HOME/.profile file and uses the file .CR /etc/suid_profile instead of the .CR ENV file. This mode is on whenever the effective user ID (group ID) is not equal to the real user ID (group ID). Turning this off causes the effective user ID and group ID to be set to the real user ID and group ID. .TP .CR \-s Sort the positional parameters. .TP .CR \-t Exit after reading and executing one command. .TP .CR \-u Treat unset parameters as an error when substituting. .TP .CR \-v Print shell input lines as they are read. .TP .CR \-x Print commands and their arguments as they are executed. .TP .CR \- Turn off .CR \-x and .CR \-v options and stop examining arguments for options. .TP .CR \-\- Do not change any of the options; useful in setting parameter .CR 1 to a value beginning with .CR \- . If no arguments follow this option, the positional parameters are unset. .RE .PP .ne 3v \(dg .CR shift "\0[\f2n\f1]" .IP Rename the positional parameters from .IC n +1 \f1\0...\& to .CR 1 \0.... The default value of .I n is .CR 1 . .I n can be any arithmetic expression that evaluates to a nonnegative number less than or equal to .CR $# . .PP .ne 3v .CR test \0[\f2expr\f1] .IP Evaluate conditional expression .IR expr . See .IR test (1) for usage and description. The arithmetic comparison operators are not restricted to integers. They allow any arithmetic expression. The following additional primitive expressions are allowed: .RS .TP 20 .PD 0 .CI \-L \0file True if .I file is a symbolic link. .TP .CI \-e \0file True if .I file exists. .TP .IC file1\0 \-nt \0file2 True if .I file1 is newer than .IR file2 . .TP .IC file1\0 \-ot \0file2 True if .I file1 is older than .IR file2 . .TP .IC file1\0 \-ef \0file2 True if .I file1 has the same device and i-node number as .IR file2 . .PD .RE .PP .ne 3v \(dg .CR times .IP Print the accumulated user and system times for the shell and for processes run from the shell. .PP .ne 3v \(dg .CR trap \0[\f2arg\f1]\0[\f2sig\f1]...\& .IP Set .I arg as a command that is read and executed when the shell receives a .IR sig signal. (Note that .I arg is scanned once when the trap is set and once when the trap is taken.) Each .I sig can be given as the number or name of a signal. Letter case is ignored. For example, .CR 3 , .CR QUIT , .CR quit , and .CR SIGQUIT all specify the same signal. Use .CR "kill \-l" to get a list of signals. .IP Trap commands are executed in signal number order. Any attempt to set a trap on a signal that was ignored upon entering the current shell is ineffective. .IP If .I arg is .CR \- (or if .I arg is omitted and the first .I sig is numeric), reset all traps for each .I sig to their original values. .IP If .I arg is the null string .RC ( '' or \&\c .C """""\c" ), each .I sig is ignored by the shell and by the commands it invokes. .IP If .I sig is .CR DEBUG , then .I arg is executed after each command. If .I sig is .CR ERR , .I arg is executed whenever a command has a nonzero exit code. If .I sig is .CR 0 or .CR EXIT and the .CR trap statement is executed inside the body of a function, the command .I arg is executed after the function completes. If .I sig is .CR 0 or .CR EXIT for a .CR trap set outside any function, the command .I arg is executed on exit from the shell. .IP With no arguments, print a list of commands associated with each signal name. .PP .ne 4v \(dg\(dg .CR typeset \0[{ \- \(or + }\c .CR LRZfilrtux [\f2n\f1]\|]\0[\f2name\f1[ = \f2value\f1]\|]... .br \(dg\(dg .IC name = value .RC [\f2name = \f2value\f1]...\& .IP Assign types and a value to a local named parameter .IR name . See also the .CR export special command. Parameter assignments remain in effect after the command completes. When invoked inside a function, create a new instance of the parameter .IR name . The parameter value and type are restored when the function completes. .IP The following list of attributes can be specified. Use .CR \+ instead of .CR \- to turn the options off. .RS .TP .CR \-L Left justify and remove leading blanks from .IR value . If .I n is nonzero, it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. When .I name is assigned, the value is filled on the right with blanks or truncated, if necessary, to fit into the field. Leading zeros are removed if the .CR \-Z option is also set. The .CR \-R option is turned off. Flagged as .CI leftjust \0n\f1. .TP .CR \-R Right justify and fill with leading blanks. If .I n is nonzero, it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. The field is left-filled with blanks or truncated from the end if the parameter is reassigned. The .CR \-L option is turned off. Flagged as .CI rightjust \0n\f1. .TP .CR \-Z Right justify and fill with leading zeros if the first nonblank character is a digit and the .CR \-L option has not been set. If .I n is nonzero it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. Flagged as .CI zerofill \0n\f1 plus the flag for .CR \-L or .CR \-R . .TP .CR \-f Cause .I name to refer to function names rather than parameter names. No assignments can be made to the .I name declared with the .CR typeset statement. The only other valid options are .CR \-t (which turns on execution tracing for this function) and .CR \-x (which allows the function to remain in effect across shell procedures executed in the same process environment). Flagged as .CR function . .TP .CR \-i Parameter is an integer. This makes arithmetic faster. If .I n is nonzero it defines the output arithmetic base; otherwise, the first assignment determines the output base. Flagged as .CR integer \0[ base \0\f2n\f1]. .TP .CR \-l Convert all uppercase characters to lowercase. The uppercase .CR \-u option is turned off. Flagged as .CR lowercase . .TP .CR \-r Mark any given .I name as "read only". The name cannot be changed by subsequent assignment. Flagged as .CR readonly . .TP .CR \-t Tag the named parameters. Tags are user-definable and have no special meaning to the shell. Flagged as .CR tagged . .TP .CR \-u Convert all lowercase characters to uppercase characters. The lowercase .CR \-l option is turned off. Flagged as .CR uppercase . .TP .CR \-x Mark any given .I name for automatic export to the environment of subsequently executed commands. Flagged as .CR export . .RE .IP .CR typeset alone displays a list of parameter names, prefixed by any flags specified above. .IP .CR "typeset \-" displays the parameter names followed by their values. Specify one or more of the option letters to restrict the list. Some options are incompatible with others. .IP .CR "typeset +" displays the parameter names alone. Specify one or more of the option letters to restrict the list. Some options are incompatible with others. .PP .ne 3v .CR ulimit \0[ \-HSacdfnst ]\0[\f2limit\f1] .IP Set or display a resource limit. The limit for a specified resource is set when .IR limit is specified. The value of .IR limit can be a number in the unit specified with each resource, or the keyword .CR unlimited . .IP The .CR \-H and .CR \-S flags specify whether the hard limit or the soft limit is set for the given resource. A hard limit cannot be increased once it is set. A soft limit can be increased up to the hard limit. If neither .CR \-H nor .CR \-S is specified, the limit applies to both. The current resource limit is printed when .IR limit is omitted. In this case, the soft limit is printed unless .CR \-H is specified. When more than one resource is specified, the limit name and unit are printed before the value. .IP If no option is given, .CR \-f is assumed. .RS .TP .PD 0 .CR \-a List all of the current resource limits. .TP .CR \-c The number of 512-byte blocks in the size of core dumps. .TP .CR \-d The number of kilobytes in the size of the data area. .TP .CR \-f The number of 512-byte blocks in files written by child processes (files of any size can be read). .TP .CR \-n The number of file descriptors. .TP .CR \-s The number of kilobytes in the size of the stack area. .TP .CR \-t The number of seconds to be used by each process. .PD .RE .PP .ne 3v .CR umask \0[ \-S ]\0[\f2mask\f1] .IP Set the user file-creation mask .IR mask . .I mask can be either an octal number or a symbolic value as described in .IR umask (1). A symbolic value shows permissions that are unmasked. An octal value shows permissions that are masked off. .IP Without .I mask , print the current value of the mask. With .CR \-S , print the value in symbolic format. Without .CR \-S , print the value as an octal number. The output from either form can be used as the .I mask of a subsequent invocation of .CR umask . .PP .ne 4v .CI unalias \0name\f1\0...\& .br .CR unalias\0\-a .IP Remove each .IR name from the alias list. With .CR \-a , remove all .CR alias definitions from the current shell execution environment. .PP .ne 3v .CR unset \0[ \-fv ]\0\f2name\f1\0...\& .IP Remove the named shell parameters from the parameter list. Their values and attributes are erased. Read-only variables cannot be unset. With .CR \-f , .IR name s refer to function names. With .CR \-v , .IR name s refer to variable names. Unsetting .CR _ , .CR ERRNO , .CR LINENO , .CR MAILCHECK , .CR OPTARG , .CR OPTIND , .CR RANDOM , .CR SECONDS , and .CR TMOUT removes their special meaning, even if they are subsequently assigned to. .PP .ne 3v \(dg .CR wait \0[\f2job\f1] .IP Wait for the specified .I job to terminate or stop, and report its status. This status becomes the return code for the .CR wait command. Without .I job , wait for all currently active child processes to terminate or stop. The termination status returned is that of the last process. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v .CR whence \0[ \-pv ]\0\f2name\f1\0...\& .IP For each .IR name , indicate how it would be interpreted if used as a command name. With .CR \-v , produce a more verbose report. With .CR \-p do a path search for .IR name , disregarding any use as an alias, a function, or a reserved word. .SS Comments A .I word beginning with .CR # causes that word and all the following characters up to a newline to be ignored. .SS Aliasing The first word of each command is replaced by the text of an .CR alias , if an .CR alias for this word has been defined. An .CR alias name consists of any number of characters excluding metacharacters, quoting characters, file expansion characters, parameter and command substitution characters, and =. The replacement string can contain any valid shell script, including the metacharacters listed above. The first word of each command in the replaced text, other than any that are in the process of being replaced, will be tested for additional aliases. If the last character of the alias value is a .IR blank , the word following the alias is also checked for alias substitution. Aliases can be used to redefine special commands, but cannot be used to redefine the keywords listed in the "Compound Commands" subsection. Aliases can be created, listed, and exported with the .CR alias command and can be removed with the .CR unalias command. Exported aliases remain in effect for subshells but must be reinitialized for separate invocations of the shell (see the "Shell Invocation" subsection). .PP Aliasing is performed when scripts are read, not while they are executed. Therefore, for it to take effect, an .CR alias must be executed before the command referring to the alias is read. .PP Aliases are frequently used as a shorthand for full path names. An option to the aliasing facility allows the value of the alias to be automatically set to the full path name of the corresponding command. These aliases are called .I tracked aliases. The value of a .I tracked alias is defined the first time the identifier is read and becomes undefined each time the .CR PATH variable is reset. These aliases remain .I tracked so that the next reference will redefine the value. Several tracked aliases are compiled into the shell. The .CR \-h option of the .CR set command converts each command name that is an .I identifier into a tracked alias. .PP The following .I exported aliases are compiled into the shell but can be unset or redefined: .nf .IP .C autoload='typeset \-fu' .C command='command ' .C functions='typeset \-f' .C history='fc \-l' .C integer='typeset \-i' .C local=typeset .C nohup='nohup ' .C r='fc \-e \-' .C stop='kill \-STOP' .C suspend='kill \-STOP $$' .C type='whence \-v' .SS Tilde Substitution After alias substitution is performed, each word is checked to see if it begins with an unquoted tilde .RC ( ~ ). If it does, the word up to a .CR / is checked to see if it matches a user name in the .CR /etc/passwd file. If a match is found, the .CR ~ and the matched login name are replaced by the login directory of the matched user. If no match is found, the original text is left unchanged. A .CR ~ alone or before a .CR / is replaced by the value of the .CR HOME parameter. A .CR ~ followed by a .CR + or .CR \- is replaced by the value of the parameter .CR PWD and .CR OLDPWD , respectively. In addition, tilde substitution is attempted when the value of a parameter assignment begins with a .CR ~ . .SS Command Substitution The standard output from a command enclosed in parenthesis preceded by a dollar sign .RC ( $( ...\& ) ) or a pair of grave accents .RC ( ` ...\& ` ) can be used as part or all of a word; trailing newlines are removed. In the second (archaic) form, the string between the accents is processed for special quoting characters before the command is executed. See the "Quoting" subsection. The command substitution .CR "$(cat file)" can be replaced by the equivalent but faster .CR $(\0\c ". .TP .CR PS3 Selection prompt string used within a .CR select loop. If unset, it defaults to "\c .CR #?\0\c ". .TP .CR PS4 Execution trace string that precedes each line of an execution trace. See the .CR "set \-x" special command. If unset, it defaults to "\c .CR +\0\c ". .TP .CR SHELL The path name of the shell is kept in the environment. When invoked, the shell is restricted if the value of this variable contains an .CR r in the base name. .TP .CR TMOUT If set to a value greater than zero, the shell will terminate if a command is not entered within the prescribed number of seconds after issuing the .CR PS1 prompt. (Note that the shell can be compiled with a maximum bound for this value which cannot be exceeded.) .TP .CR VISUAL Invokes the corresponding option when the value of this variable ends in .CR emacs , .CR gmacs , or .CR vi . See the .CR "set \-o" special command. .PP The shell gives default values to .CR IFS , .CR MAILCHECK , .CR PATH , .CR PS1 , .CR PS2 , and .CR TMOUT . On the other hand, .CR MAIL , .CR ENV , .CR HOME , and .CR SHELL are never set automatically by the shell (although .CR HOME , .CR MAIL , and .CR SHELL are set by .CR login ; see .IR login (1)). .SS Blank Interpretation After parameter and command substitution, the results of substitution are scanned for field separator characters (defined in .CR IFS ), and split into distinct arguments when such characters are found. .CR sh retains explicit null arguments (\c .C """""" or .CR '' ) but removes implicit null arguments (those resulting from parameters that have null values). .SS File Name Generation Following substitution, each command .I word is processed as a pattern for file name expansion unless expansion has been disabled with the .CR "set \-f" special command. The form of the patterns is the Pattern Matching Notation defined in .IR regexp (5). The word is replaced with sorted file names matching the pattern. If no file name is found that matches the pattern, the word is left unchanged. .PP In addition to the notation described in .IR regexp (5), .CR sh recognizes composite patterns made up of one or more pattern lists separated from each other with a .CR | . Composite patterns can be formed with one or more of the following: .RS .TP 18 .PD 0 .CI ?( pattern-list ) Matches any one of the given patterns. .TP .CI *( pattern-list ) Matches zero or more occurrences of the given patterns. .TP .CI +( pattern-list ) Matches one or more occurrences of the given patterns. .TP .CI @( pattern-list ) Matches exactly one of the given patterns. .TP .CI !( pattern-list ) Matches anything, except one of the given patterns. .PD .RE .SS Quoting Each of the metacharacters (see the "Definitions" subsection) has a special meaning to the shell and terminates a word unless quoted. A character may be .B quoted (that is, made to stand for itself) by preceding it with a backslash .RC ( \e ). The pair .CR \e newline is ignored; the current and following lines are concatenated. .PP All characters enclosed between a pair of apostrophes .RC ( ' ...\& ' ) are quoted. An apostrophe cannot appear within apostrophes. .PP Parameter and command substitution occurs inside quotation marks (\c .C """\c" \&...\&\c .C """\c" ). .CR \e quotes the characters .CR \e , .CR ` , .C """\c" , and .CR $ . .PP Inside grave accent marks .RC ( ` ...\& ` ), .CR \e quotes the characters .CR \e , .CR ` , and .CR $ . If the grave accents occur within quotation marks, .CR \e also quotes the character .C """\c" \&. .PP The meanings of .CR $* and .CR $@ are identical when not quoted or when used as a parameter assignment value or as a file name. However, when used as a command argument, .C """\c" .CR $*\c .C """" is equivalent to .C """\c" .CI $1 d $2 d\f1...\&\c .C """\c" , whereas .C """\c" .CR $@\c .C """" is equivalent to .C """\c" .CR $1\c .C """\c" .IR d\c .C """\c" .CR $2\c .C """\c" .IR d ...\& (where .I d is the first character of .CR IFS ), .PP The special meaning of keywords or aliases can be removed by quoting any character of the name. The recognition of function names or special command names cannot be altered by quoting them. .SS Arithmetic Evaluation Integer arithmetic is provided with the special command .CR let . Evaluations are performed using long integer arithmetic. Constants take the form .IC base # n or .IR n , where .I base is a decimal number between two and thirty-six representing the arithmetic base and .I n is a number in that base. If .IC base # is omitted, base 10 is used. .PP An arithmetic expression uses the same syntax, precedence, and associativity of expression as the C language. All the integral operators, other than .CR ++ , .CR \-\- , .CR ?: , and .CR , are supported. Variables can be referenced by name within an arithmetic expression without using the parameter substitution syntax. When a variable is referenced, its value is evaluated as an arithmetic expression. .PP A variable can be typed as an integer with the .CR \-i option of the .CR typeset special command, as in .CI typeset\0-i \f1[\f2base\f1]\f2\0name\f1. Arithmetic evaluation is performed on the value of each assignment to a variable with the .CR \-i attribute. If you do not specify an arithmetic base, the first assignment to the variable determines the arithmetic base. This base is used when parameter substitution occurs. .PP Since many of the arithmetic operators require quoting, an alternative form of the .CR let command is provided. For any command beginning with .CR (( , all characters until the matching .CR )) are treated as a quoted expression. More precisely, .CR (( ...\& )) is equivalent to .CR let .C """\c" .RC ...\c .C """\c" .RC . .SS Prompting When used interactively, the shell prompts with the value of .CR PS1 before reading a command. Whenever a newline is received and further input is needed to complete a command, the secondary prompt (the value of .CR PS2 ) is issued. .SS Conditional Expressions A .B "conditional expression" is used with the .CR [[ compound command to test attributes of files and to compare strings. Word splitting and file name generation are not performed on the words between .CR [[ and .CR ]] . Each expression can be constructed from one or more of the following unary or binary expressions: .RS .TP 20 .PD 0 .CI \-a \0file True, if .I file exists. .TP .CI \-b \0file True, if .I file exists and is a block special file. .TP .CI \-c \0file True, if .I file exists and is a character special file. .TP .CI \-d \0file True, if .I file exists and is a directory. .TP .CI \-e \0file True, if .I file exists. .TP .CI \-f \0file True, if .I file exists and is an ordinary file. .TP .CI \-g \0file True, if .I file exists and has its setgid bit set. .TP .CI \-h \0file True, if .I file exists and is a symbolic link. .TP .CI \-k \0file True, if .I file exists and has its sticky bit set. .TP .CI \-n \0string True, if length of .I string is nonzero. .TP .CI \-o \0option True, if the set option named .I option is on. .TP .CI \-p \0file True, if .I file exists and is a fifo special file or a pipe. .TP .CI \-r \0file True, if .I file exists and is readable by current process. .TP .CI \-s \0file True, if .I file exists and has a size greater than zero. .TP .CI \-t \0fildes True, if file descriptor number .I fildes is open and is associated with a terminal device. .TP .CI \-u \0file True, if .I file exists and has its setuid bit set. .TP .CI \-w \0file True, if .I file exists and is writable by the current process. .TP .CI \-x \0file True, if .I file exists and is executable by the current process. If .I file exists and is a directory, then the current process has permission to search in the directory. .TP .CI \-z \0string True, if length of .I string is zero. .TP .CI \-L \0file True, if .I file exists and is a symbolic link. .TP .CI \-O \0file True, if .I file exists and is owned by the effective user ID of this process. .TP .CI \-G \0file True, if .I file exists and its group matches the effective group ID of this process. .TP .CI \-S \0file True, if .I file exists and is a socket. .TP .IC file1\0 \-nt \0file2 True, if .I file1 exists and is newer than .IR file2 . .TP .IC file1\0 \-ot \0file2 True, if .I file1 exists and is older than .IR file2 . .TP .IC file1\0 \-ef \0file2 True, if .I file1 and .I file2 exist and refer to the same file. .TP .IC string\0 = \0pattern True, if .I string matches .IR pattern . .TP .IC string\0 != \0pattern True, if .I string does not match .IR pattern . .TP .IC string\0 < \0string2 True, if .I string1 comes before .I string2 based on the ASCII value of their characters. .TP .IC string\0 > \0string2 True, if .I string1 comes after .I string2 based on the ASCII value of their characters. .TP .IC exp1\0 \-eq \0exp2 True, if .I exp1 is equal to .IR exp2 . .TP .IC exp1\0 \-ne \0exp2 True, if .I exp1 is not equal to .IR exp2 . .TP .IC exp1\0 \-lt \0exp2 True, if .I exp1 is less than .IR exp2 . .TP .IC exp1\0 \-gt \0exp2 True, if .I exp1 is greater than .IR exp2 . .TP .IC exp1\0 \-le \0exp2 True, if .I exp1 is less than or equal to .IR exp2 . .TP .IC exp1\0 \-ge \0exp2 True, if .I exp1 is greater than or equal to .IR exp2 . .PD .RE .PP A compound expression can be constructed from these primitives by using any of the following, listed in decreasing order of precedence. .RS .TP 20 .PD 0 .CI ( exp ) True, if .I exp is true. Used to group expressions. .TP .CI ! exp True, if .I exp is false. .TP .IC exp1\0 && \0exp2 True, if .I exp1 and .I exp2 are both true. .TP .IC exp1\0 || \0exp2 True, if either .I exp1 or .I exp2 is true. .PD .RE .SS Input/Output Before a command is executed, its input and output can be redirected using a special notation interpreted by the shell. The following can appear anywhere in a simple-command or may precede or follow a command and are not passed on to the invoked command. Command and parameter substitution occurs before .I word or .I digit is used, except as noted below. File name generation occurs only if the pattern matches a single file and blank interpretation is not performed. .RS .TP 15 .CI < word Use file .I word as standard input (file descriptor .CR 0 ). .TP .CI > word Use file .I word as standard output (file descriptor .CR 1 ). If the file does not exist, it is created. If the file exists, and the .CR noclobber option is on, an error occurs; otherwise, the file is truncated to zero length. .TP .CI >| word Same as .CR > , except that it overrides the .CR noclobber option. .TP .CI >> word Use file .I word as standard output. If the file exists, output is appended to it (by first searching for the end-of-file); otherwise, the file is created. .TP .CI <> word Open file .I word for reading and writing as standard input. .TP .CR << [ \- ]\f2word The shell input is read up to a line that matches .IR word , or to an end-of-file. No parameter substitution, command substitution or file name generation is performed on .IR word . The resulting document, called a .IR here-document , becomes the standard input. If any character of .I word is quoted, no interpretation is placed upon the characters of the document. Otherwise, parameter and command substitution occurs, .CR \e newline is ignored, and .CR \e must be used to quote the characters .CR \e , .CR $ , .CR ` , and the first character of .IR word . If .CR \- is appended to .CR << , all leading tabs are stripped from .I word and from the document. .TP .CI <& digit The standard input is duplicated from file descriptor .I digit (see .IR dup (2)). .TP .CI >& digit The standard output is duplicated to file descriptor .I digit (see .IR dup (2)). .TP .CR <&- The standard input is closed. .TP .CR >&- The standard output is closed. .TP .CR <&p The input from the coprocess is moved to standard input. .TP .CR >&p The output to the coprocess is moved to standard output. .RE .RE .PP If any of the above redirections is preceded by a digit .RC ( 0 to .CR 9 ), the file descriptor used is the one specified by the digit, instead of the default .CR 0 (standard input) or .CR 1 (standard output). For example: .IP .CR 2>&1 .PP means open file descriptor 2 for writing as a duplicate of file descriptor 1. Output directed to file descriptor 2 is written in the same location as output to file descriptor 1. .PP Order is significant in redirection. The shell evaluates each redirection in terms of the .RI ( "file descriptor" ", " file ) assignment at the time of evaluation. For example: .IP .CR 1> \f2fname\0 2>&1 .PP first assigns file descriptor 1 to file .IR fname . It then assigns file descriptor 2 to the file assigned to file descriptor 1 (that is, .IR fname ). .PP If the order of redirection is reversed, as in .IP .CR 2>&1\01> \f2fname .PP file descriptor 2 is assigned to the file assigned to file descriptor 1 (probably the terminal) and then file descriptor 1 is assigned to file .IR fname . .PP By using the redirection operators above, the input and output of a .I coprocess may be moved to a numbered file descriptor, allowing other commands to write to them and read from them. If the input of the current coprocess is moved to a numbered file descriptor, another coprocess may be started. .PP If a command is followed by .CR & and job control is inactive, the default standard input for the command is the empty file .CR /dev/null . Otherwise, the environment for the execution of a command contains the file descriptors of the invoking shell as modified by input/output specifications. .SS Environment The .B environment (see .IR environ (5)) is a list of name-value pairs passed to an executed program much like a normal argument list. The names must be identifiers and the values are character strings. The shell interacts with the environment in several ways. When invoked, the shell scans the environment and creates a parameter for each name found, gives it the corresponding value and marks it .CR export . Executed commands inherit the environment. If the user modifies the values of these parameters or creates new ones by using the .CR export or .CR "typeset \-x" special commands, the values become part of the environment. The environment seen by any executed command is thus composed of any name-value pairs originally inherited by the shell, whose values may be modified by the current shell, plus any additions which must be noted in .CR export or .CR "typeset \-x" commands. .PP The environment for any simple command or function can be augmented by prefixing it with one or more parameter assignments. A parameter assignment argument takes the form .IC identifier = value\f1. For example, both the following .IP .CI TERM=450 "\0cmd\0args" .IP .CI "(export TERM; TERM=450;" "\0cmd\0args" ) .PP are equivalent (as far as the execution of .I cmd is concerned, except for the special commands that are preceded by a dagger (\(dg)). .PP If the .CR \-k option is set, all parameter assignment arguments are placed in the environment, even if they occur after the command name. The following echo statement prints .CR "a=b c" . After the .CR \-k option is set, the second echo statement prints only .CR c : .nf .IP .CR "echo a=b c" \0\(->\0 "a=b c" .CR "set \-k" .CR "echo a=b c" \0\(->\0 "c" .fi .PP This feature is intended for use with scripts written for early versions of the shell and its use in new scripts is strongly discouraged. It is likely to disappear someday. .SS Functions The .CR function command (described in the "Compound Commands" subsection) defines shell functions. Shell functions are read and stored internally. Alias names are resolved when the function is read. Functions are executed like commands, with the arguments passed as positional parameters. (See the "Execution" subsection.) .PP Functions execute in the same process as the caller and share all files and current working directory with the caller. Traps defined by the caller are reset to their default action inside the function. A trap condition that is not caught or ignored by the function causes the function to terminate and the condition to be passed on to the caller. A trap on .CR EXIT set inside a function is executed after the function completes in the environment of the caller. Ordinarily, variables are shared between the calling program and the function. However, the .CR typeset special command can be used within a function to define local variables whose scope includes the current function and all functions it calls. .PP The .CR return special command is used to return from function calls. Errors within functions return control to the caller. .PP Function identifiers can be listed with the .CR +f option of the .CR typeset special command. Function identifiers and the associated text of the functions can be listed with the .CR \-f option. Functions can be undefined with the .CR \-f option of the .CR unset special command. .PP Ordinarily, functions are unset when the shell executes a shell script. The .CR \-xf option of the .CR typeset command allows a function to be exported to scripts that are executed without reinvoking the shell. Functions that must be defined across separate invocations of the shell should be placed in the .CR ENV file. .SS Jobs If the .CR monitor option of the .CR set command is turned on, an interactive shell associates a .I job with each pipeline. It keeps a table of current jobs, printed by the .CR jobs command, and assigns them small integer numbers. When a job is started asynchronously with .CR & , the shell prints a line that looks like: .IP .C "[1] 1234" .PP indicating that job number 1 was started asynchronously and had one (top-level) process whose process ID was 1234. .PP If you are running a job and wish to do something else, you can type the suspend character (the .CR susp character defined with .CR stty ; see .IR stty (1)) to send a .CR SIGSTOP signal to the current job. The shell then indicates that the job has been .CR Stopped , and prints another prompt. Then you can manipulate the state of this job by putting it in the background with the .CR bg command, running other commands, and eventually returning the job to the foreground with the .CR fg command. A suspend takes effect immediately and resembles an interrupt, since pending output and unread input are discarded when the suspend is entered. .PP A job running in the background stops if it tries to read from the terminal. Background jobs normally are allowed to produce output, but can be disabled with the .CR "stty tostop" command. If the user sets this terminal option, background jobs stop when trying to produce output. .PP There are several ways to refer to jobs in the shell. A job can be referred to by the process ID of any process in the job or by one of the following: .RS .TP 20 .PD 0 .CI % number The job with the given number. .TP .CI % string Any job whose command line begins with .IR string . .TP .CI %? string Any job whose command line contains .IR string . .TP .CI %% Current job. .TP .CI %+ Equivalent to .CR %% . .TP .CR %- Previous job. .PD .RE .PP The shell learns immediately when a process changes state. It informs the user when a job is blocked and prevented from further progress, but only just before it prints a prompt. .PP When the monitor mode is on, each background job that completes triggers any trap set for .CR SIGCHLD . .PP If you try to exit from shell while jobs are stopped, you are warned with the message .CR "You have stopped jobs." You can use the .CR jobs command to identify them. If you immediately try to exit again, the shell will not warn you a second time, and the stopped jobs will be terminated. .PP If you try to leave the shell while jobs are running, you are not warned. The shell exits silently and sets the parent of the running jobs to the .CR init process (number 1). .SS Signals The .CR SIGINT and .CR SIGQUIT signals for an invoked command are ignored if the command is followed by .CR & and the .CR monitor option is off. Otherwise, signals have the values inherited by the shell from its parent, with the exception of signal .CR SIGSEGV (but see also the .CR trap special command). .SS Execution Substitutions are made each time a command is executed. .CR sh checks the command name to determine whether it matches a special command. If it does, it is executed within the current shell process. .PP Next, .CR sh checks the command name to determine whether it matches one of the user-defined functions. If it does, .CR sh saves the positional parameters, then sets them to the arguments of the function call. The positional parameter .CR 0 is unchanged. When the function completes or issues a .CR return , .CR sh restores the positional parameter list and executes any trap set on .CR EXIT within the function. The value of a function is the value of the last command executed. A function is executed in the current shell process. .PP If a command name is not a user-defined function or a special command, .CR sh creates a process and attempts to execute the command using an .CI exec * () system call (see .IR exec (2)). .PP The shell parameter .CR PATH defines the search path for the directory containing the command. Alternative directory names are separated by a colon .RC ( : ). The default path is .CR /usr/bin:\& (specifying .CR /usr/bin , and the current directory, in that order). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign, between colon delimiters, or at the end of the path list. The search path is not used if the command name contains a .CR / . Otherwise, each directory in the path is searched for an executable file. If the file has execute permissions but is not a directory or an executable object code file, it is assumed to be a script file, which is a file of data for an interpreter. If the first two characters of the script file are .CR #! , .CI exec * () expects an interpreter path name to follow. .CI exec * () then attempts to execute the specified interpreter as a separate process to read the entire script file. If a call to .CI exec * () fails, .CR sh is spawned to interpret the script file. All nonexported aliases, functions, and named parameters are removed in this case. If the shell command file does not have read permission, or if the .CR setuid and/or .CR setgid bits are set on the file, the shell executes an agent to set up the permissions and execute the shell with the shell command file passed down as an open file. A parenthesized command is also executed in a subshell without removing nonexported quantities. .SS Command Reentry The text of the last .CR HISTSIZE (default 128) commands entered from a terminal device is saved in a history file. The file .CR $HOME/.sh_history is used if the .CR HISTFILE variable is not set or writable. A shell can access the commands of all interactive shells that use the same named .CR HISTFILE . The special command .CR fc is used to list or edit a portion of this file. The portion of the file to be edited or listed can be selected by number or by giving the first character or characters of the command. A single command or range of commands can be specified. If you do not specify an editor program as an argument to .CR fc , the value of the parameter .CR FCEDIT is used. If .CR FCEDIT is not defined, .CR /usr/bin/ed is used. The edited command is printed and reexecuted upon leaving the editor. The editor name .CR \- is used to skip the editing phase and to reexecute the command. In this case, a substitution parameter of the form .IC old = new can be used to modify the command before execution. For example, if .CR r is aliased to .CR "fc \-e \-" , typing .CR "r bad=good c" reexecutes the most recent command that starts with the letter .CR c and replaces the first occurrence of the string .CR bad with the string .CR good . .SS Command Line Editing Normally, each command line typed at a terminal device is followed by a newline or return. If one of the .CR emacs , .CR gmacs , .CR vi , or .CR viraw , options is set, you can edit the command line. An editing option is automatically selected each time the .CR VISUAL or .CR EDITOR variable is assigned a value ending in one of these option names. .PP The editing features require that the user's terminal accept return without line feed and that a space ("\ ") must overwrite the current character on the screen. ADM terminal users should set the "space\ \(mi\ advance" switch to "space". Hewlett-Packard terminal users should set the straps to "bcGHxZ\ etX". .PP The editing modes enable the user to look through a window at the current line. The default window width is 80, unless the value of .CR COLUMNS is defined. If the line is longer than the window width minus two, a mark displayed at the end of the window notifies the user. The mark is one of: .RS .TP .PD 0 .CR > The line extends to the right. .TP .CR < The line extends to the left. .TP .CR * The line extends to both sides of the window. .PD .RE .PP As the cursor moves and reaches the window boundaries, the window is centered about the cursor. .PP The search commands in each edit mode provide access to the history file. Only strings are matched, not patterns, although a leading .CR ^ in the string restricts the match to begin at the first character in the line. .SS emacs Editing Mode This mode is invoked by either the .CR emacs or .CR gmacs option. Their sole difference is their handling of .CR ^T . To edit, the user moves the cursor to the point needing correction and inserts or deletes characters or words. All editing commands are control characters or escape sequences. The notation for control characters is caret .RC ( ^ ) followed by a character. For example, .CR ^F is the notation for Control-F. This is entered by holding down the Ctrl (control) key and pressing .CR f . The shift key is .I not pressed. The notation .CR ^?\& indicates the delete (DEL) key. .PP The notation for escape sequences is .CR M- followed by a character. For example, .CR M-f (pronounced .IR "meta f" ) is entered by pressing the escape key (ESC) followed by pressing .CR f . .CR M-F is the notation for escape followed by shift (capital) .CR F . .PP All edit commands operate from any place on the line (not only at the beginning). Neither the return .RC ( ^M ) nor the newline .RC ( ^J ) key is entered after edit commands, except when noted. .RS .TP 15 .PD 0 .CR ^F Move cursor forward (right) one character. .TP .CR M-f Move cursor forward one word. (The editor's idea of a word is a string of characters consisting of only letters, digits and underscores.) .TP .CR ^B Move cursor backward (left) one character. .TP .CR M-b Move cursor backward one word. .TP .CR ^A Move cursor to start of line. .TP .CR ^E Move cursor to end of line. .TP .CI ^] char Move cursor forward to character .I char on current line. .TP .CI M-^] char Move cursor backward to character .I char on current line. .TP .CI ^X^X Interchange the cursor and mark. .TP .I erase Delete previous character. (User-defined erase character as defined by the .CR stty command, usually .CR ^H or .CR # .) .TP .CR ^D Delete current character. .TP .I eof Terminate the shell if the current line is null. (User-defined end-of-file character as defined by the .CR stty command, usually .CR ^D .) .TP .CI M-d Delete current word. .TP .CI M-^H Delete previous word. (meta-backspace) .TP .CI M-h Delete previous word. .TP .CI M-^?\& Delete previous word. (meta-delete) If your interrupt character is .CR ^?\& (DEL, the default), this command will not work. .TP .CI ^T In .CR emacs mode, transpose current character with next character. In .CR gmacs mode, transpose two previous characters. .TP .CI ^C Capitalize current character. .TP .CI M-c Capitalize current word. .TP .CI M-l Change the current word to lowercase. .TP .CI ^K Delete from the cursor to the end of the line. If preceded by a numerical parameter whose value is less that the current cursor position, then delete from the given position up to the cursor. If preceded by a numerical parameter whose value is greater than the current cursor position, then delete from the cursor up to the given position. .TP .CI ^W Kill from the cursor to the mark. .TP .CI M-p Push the region from the cursor to the mark on the stack. .TP .I kill Kill the entire current line. If two kill characters are entered in succession, all subsequent consecutive kill characters cause a line feed (useful when using paper terminals). (User-defined kill character as defined by the .CR stty command, usually .CR ^X or .CR @ .) .TP .CI ^Y Restore last item removed from line. (Yank item back to the line.) .TP .CI ^L Line feed and print current line. .TP .CR ^@ Set mark. (null character) .TP .CI M-\0 Set mark. (meta-space) .TP .CI ^J Execute the current line. (newline) .TP .CI ^M Execute the current line. (return) .TP .CI ^P Fetch previous command. Each time .CR ^P is entered, the previous command in the history list is accessed. .TP .CI ^N Fetch next command. Each time .CR ^N is entered the next command in the history list is accessed. .TP .CI M-< Fetch the least recent (oldest) history line. .TP .CI M-> Fetch the most recent (youngest) history line. .TP .CI ^R string Reverse search history for a previous command line containing .IR string . If a parameter of zero is given, the search is forward. .I string is terminated by a return or newline. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is omitted, the next command line containing the most recent .I string is accessed. In this case, a parameter of zero reverses the direction of the search. .TP .CR ^O Execute the current line and fetch the next line relative to current line from the history file. .TP .CI M- digits Define a numeric parameter. The digits are taken as a parameter to the next command. The commands that accept a parameter are .IR erase , .CR ^B , .CR ^C , .CR ^D , .CR ^F , .CR ^K , .CR ^N , .CR ^P , .CR ^R , .CR ^] , .CR M-^H , .CR M-. , .CR M-_ , .CR M-b , .CR M-c , .CR M-d , .CR M-f , .CR M-h , and .CR M-l . .TP .CI M- letter Your alias list is searched for an alias by the name .CI _ letter (underscore-letter). If an alias of this name is defined, its value is inserted on the input queue. This .I letter must not be one of the above metafunctions. .TP .CR M-. The last word of the previous command is inserted on the line. If preceded by a numeric parameter, the value of this parameter determines which word to insert rather than the last word. .TP .CR M-_ Same as .CR M-. . .TP .CR M-* Attempt file name generation on the current word. .TP .CR M-^[ File name completion. (meta-escape.) Replaces the current word with the longest common prefix of all file names matching the current word with an asterisk appended. If the match is unique, a .CR / is appended if the file is a directory and a space is appended if the file is not a directory. .TP .CR M-= List files matching current word pattern as if an asterisk were appended. .TP .CR ^U Multiply parameter of next command by 4. .TP .CR \e Escape next character. Editing characters and your erase, kill, and interrupt characters may be entered in a command line or in a search string, if preceded by a .CR \e . The .CR \e removes the next character's editing features (if any). .TP .CI ^V Display version of the shell. .TP .CI M-# Insert a .CR # at the beginning of the line and execute it. This causes a comment to be inserted in the history file. .PD .RE .SS vi Editing Mode The editor starts in insert mode until an escape (ESC) is received. This puts you in control mode in which you can move the cursor and perform editing commands. A return in either mode sends the line. .PP Most control commands accept an optional repeat .I count prior to the command. .PP In .CR vi mode on most systems, canonical processing is initially enabled and the command is echoed again if the speed is 1200 baud or greater and contains any control characters, or if less than one second has elapsed since the prompt was printed. The escape (ESC) character terminates canonical processing for the remainder of the command and you can then modify the command line. This scheme has the advantages of canonical processing with the typeahead echoing of raw mode. .PP Setting the .CR viraw option always disables canonical processing on the terminal. This mode is implicit for systems that do not support two alternate end-of-line delimiters, and may be helpful for certain terminals. .PP .B Insert Edit Commands .PP By default, the editor is in insert mode. .RS .TP 15 .PD 0 .I erase Delete previous inserted character. The .IR erase character is user-definable with the .CR stty command, usually set to .CR ^H . The system default is .CR # . .TP .I kill Delete all current inserted characters. The .IR kill character is user-definable with the .CR stty command, usually set to .CR ^X or .CR ^U . The system default is .CR @ . .TP .CR \e Escape the next .I erase or .I kill character. .TP .CR ^D Terminate the shell. .TP .CR ^V Escape next character. Editing characters and erase or kill characters may be entered in a command line or in a search string if preceded by a .CR ^V , which removes the next character's editing features (if any). .TP .CR ^W Delete the previous blank-separated word. .PD .RE .PP .B Motion Edit Commands .PP These commands move the cursor. The use of .IR count causes a repetition of the command the cited number of times. .RS .TP 15 .PD 0 .RC [\f2count\f1] l Cursor forward (right) one character. .TP .RC [\f2count\f1] w Cursor forward one alphanumeric word. .TP .RC [\f2count\f1] W Cursor forward to the beginning of the next word that follows a blank. .TP .RC [\f2count\f1] e Cursor forward to the end of the word. .TP .RC [\f2count\f1] E Cursor forward to end of the current blank-delimited word. .TP .RC [\f2count\f1] h Cursor backward (left) one character. .TP .RC [\f2count\f1] b Cursor backward one word. .TP .RC [\f2count\f1] B Cursor backward to preceding blank-separated word. .TP .RC [\f2count\f1] | Cursor to column .IR count . Default is 1. .TP .RC [\f2count\f1] f \f2c Find the next character .IR c in the current line. .TP .RC [\f2count\f1] F \f2c Find the previous character .IR c in the current line. .TP .RC [\f2count\f1] t \f2c Equivalent to .CI f c followed by .CR h . .TP .RC [\f2count\f1] T \f2c Equivalent to .CI F c followed by .CR l . .TP .RC [\f2count\f1] ; Repeat the last single-character find command, .CR f , .CR F , .CR t , or .CR T . .TP .RC [\f2count\f1] , Reverses the last single character find command. .TP .CR 0 Cursor to start of line. .TP .CR ^ Cursor to first nonblank character in line. .TP .CR $ Cursor to end of line. .PD .RE .PP .B History Search Commands .PP These commands access your command history file. .RS .TP 15 .PD 0 .RC [\f2count\f1] k Fetch previous command. Each time .CR k is entered, the next earlier command in the history list is accessed. .TP .RC [\f2count\f1] \- Equivalent to .CR k . .TP .RC [\f2count\f1] j Fetch next command. Each time .CR j is entered, the next later command in the history list is accessed. .TP .RC [\f2count\f1] + Equivalent to .CR j . .TP .RC [\f2count\f1] G The command number .I count is fetched. The default is the first command in the history list. .TP .CI / string Search backward through history for a previous command containing .IR string . .I string is terminated by a return or newline. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is null, the previous string is used. .TP .CI ? string Same as .CR / , but search in the forward direction. .TP .CR n Search for next match of the last pattern to the .CR / or .CR ? commands. .TP .CR N Search for next match of the last pattern to .CR / or .CR ? , but in reverse direction. .PD .RE .PP .B Text Modification Edit Commands .PP These commands will modify the line. .RS .TP 15 .PD 0 .CR a Enter insert mode after the current character. .TP .CR A Append text to the end of the line. Equivalent to .CR $a . .TP .RC [\f2count\f1] c \f2motion .TP .CR c [\f2count\f1]\f2motion Move cursor forward to the character position specified by .IR motion , deleting all characters between the original cursor position and the new position, and enter insert mode. If .I motion is .CR c , the entire line is deleted. .TP .CR C Delete from the current character through the end of line and enter insert mode. Equivalent to .CR c$ . .TP .CR S Equivalent to .CR cc . .TP .RC [\f2count\f1] d \f2motion .TP .CR d [\f2count\f1]\f2motion Move cursor to the character position specified by .IR motion , deleting all characters between the original cursor position and the new position. If .I motion is .CR d , the entire line will be deleted. .TP .CR D Delete from the current character through the end of line. Equivalent to .CR d$ . .TP .CR i Enter insert mode before the current character. .TP .CR I Enter insert mode before the beginning of the line. Equivalent to the two-character sequence .CR 0i . .TP .RC [\f2count\f1] P Insert the previous text modification before the cursor. .TP .RC [\f2count\f1] p Insert the previous text modification after the cursor. .TP .CR R Enter insert mode and replace characters on the screen with characters you type, overlay fashion. .TP .RC [\f2count\f1] r \f2c Replace the current character with .IR c . .TP .RC [\f2count\f1] x Delete the current character. .TP .RC [\f2count\f1] X Delete the preceding character. .TP .RC [\f2count\f1] . Repeat the previous text modification command. .TP .CR ~ Invert the case of the current character and advance the cursor. .TP .RC [\f2count\f1] _ Append the .I count word of the previous command at the current cursor location and enter insert mode at the end of the appended text. The last word is used if .I count is omitted. .TP .CR * Append an .CR * to the current word and attempt file name generation. If no match is found, ring the bell. If a match is found, replace the word with the matching string of file names and enter insert mode. .TP escape .TP .CR \e Attempt file name completion on the current word. Replace the current word with the longest common prefix of all file names matching the current word with an asterisk appended. If the match is unique, append a .CR / if the file is a directory or append a space if the file is not a directory. .PD .RE .PP .B Other Edit Commands .PP .RS .TP 15 .PD 0 .RC [\f2count\f1] y \f2motion .TP .CR y [\f2count\f1]\f2motion Yank current character through character that .I motion would move the cursor to and put them into the delete buffer. The text and cursor are unchanged. .TP .CR Y Yank from current position to end of line. Equivalent to .CR y$ . .TP .CR u Undo the last text-modifying command. .TP .CR U Undo all the text-modifying commands performed on the line. .TP .RC [\f2count\f1] v Execute the command .CI "fc \-e ${VISUAL:-${EDITOR:-vi}}" " count" in the input buffer. If .I count is omitted, the current line is used. This executes an editor with the current line as the input "file". When you exit from the editor, the result is executed. .TP .CR ^L Line feed and print current line. .TP .CR ^J Execute the current line, regardless of mode. (newline) .TP .CR ^M Execute the current line, regardless of mode. (return) .TP .CR # Insert a .CR # at the beginning of the current line and after each embedded newline, and execute the line. Useful for inserting the current command line in the history list without executing it. .TP .CR = List the file names that match the current word if an asterisk were appended to it. .TP .CI @ letter Search your alias list for an alias with the name .CI _ letter (underscore letter). If an alias of this name is defined, its value is executed as a command sequence on the current line. This provides a simple macro capability. .PD .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. If it is not defined or is empty, it defaults to the value of .CR LANG . .PP .CR LC_CTYPE determines the classification of characters as letters, and the characters matched by character class expressions in pattern matching notation. If it is not defined or is empty, it defaults to the value of .CR LANG . .PP If .CR LANG is not defined or is empty, it defaults to .CR C (see .IR lang (5)). .PP If any internationalization variable contains an invalid value, they all default to .CR C (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH RETURN VALUE Errors detected by the shell, such as syntax errors, cause the shell to return a nonzero exit status. Otherwise, the shell returns the exit status of the last command executed. See also the .CR exit special command. If the shell is being used noninteractively, the execution of the shell file is abandoned. Runtime errors detected by the shell are reported by printing the command or function name and the error condition. If the line number on which the error occurred is greater than one, the line number is also printed in brackets .RC ( [] ) after the command or function name. .\".SH EXAMPLES .\" none appropriate. .SH WARNINGS .PP .\" File descriptors 54 through 60 are used internally by the POSIX shell. File descriptors 24 through 30 are used internally by the POSIX shell. Applications using these and forking a subshell should not depend upon them surviving in the subshell or its descendants. .PP If a command that is a tracked alias is executed, and a command with the same name is installed in a directory in the search path before the directory where the original command was found, the shell will continue to load and execute the original command. Use the .CR \-t option of the .CR alias command to correct this situation. .PP If you move the current directory or one above it, .CR pwd may not give the correct response. Use the .CR cd command with a full path name to correct this situation. .PP Some very old shell scripts use a caret .RC ( ^ ) as a synonym for the pipe character .RC ( | ). .CR sh .I "does not" recognize the caret as a pipe character. .PP If a command is piped into a shell command, all variables set in the shell command are lost when the command completes. .PP Using the .CR fc built-in command within a compound command will cause the entire command to disappear from the history file. .PP The dot .RC ( . ) special command, as in .CI .\& " file\f1," reads the entire file before any commands are executed. Therefore, .CR alias and .CR unalias commands in the file will not apply to any functions defined in the file. .PP Traps are not processed while the shell is waiting for a foreground job. Thus, a trap on .CR SIGCHLD is not executed until the foreground job terminates. .PP The .CR export special command does not handle arrays properly. Only the first element of an array is exported to the environment. .PP Background processes started from a noninteractive shell cannot be accessed with job control commands. .PP The value of the .CR IFS variable in the user's environment affects the behavior of scripts. .SS Collating Order In an international environment, character ordering is determined by the value of .CR LC_COLLATE , rather than by the binary ordering of character values in the machine collating sequence. This brings with it certain attendant dangers, particularly when using range expressions in file name generation patterns. For example, the command, .IP .C "rm [a-z]*" .PP might be expected to match all file names beginning with a lowercase alphabetic character. However, if dictionary ordering is specified by .CR LC_COLLATE , it would also match file names beginning with an uppercase character (as well as those beginning with accented letters). Conversely, it would fail to match letters collated after .CR z in languages such as Danish or Norwegian. .PP The correct (and safe) way to match specific character classes in an international environment is to use a pattern (see .IR regexp (5)) of the form: .IP .C "rm [[:lower:]]*" .PP This uses .CR LC_CTYPE to determine character classes and works predictably for all supported languages and codesets. For shell scripts produced on noninternationalized systems (or without consideration for the above dangers), it is recommended that they be executed in a non-NLS environment. This requires that .CR LANG , .CR LC_COLLATE , and so on, be set to .CR C or not set at all. .SS History File Changes At HP-UX release B.10.10, the history file has a new internal magic number. This will cause a pre-B.10.10 history file to be discarded. Users who use multiple versions of HP-UX that NFS-mount the same directory that contains the history file (usually the home directory) may want to create a separate history file for each HP-UX version by setting the .CR HISTFILE parameter as: .IP .C "HISTFILE=$HOME/.sh_hist_$(uname \-r)" .PP Users on windowing systems may want to have separate history files for each window by setting the HISTFILE parameter as follows: .IP .C "HISTFILE=$HOME/.sh_hist$$" .PP A .CR cron job may be used to delete old history files. .PP The history file does not support mixing of locales in the same file. For users of multiple locales, you can assign a unique history file for each locale by setting .CR HISTFILE as: .IP .C "HISTFILE=$HOME/.sh_hist_${LANG}" .PP or include the process number in the .CR HISTFILE parameter as shown above. .SH AUTHOR .CR sh was developed by AT&T, OSF, and HP. .SH FILES .TP 30 .PD 0 .CR $HOME/.profile Read to set up user's custom environment .TP .CR /etc/passwd To find home directories .TP .CR /etc/profile Read to set up system environment .TP .CR /etc/suid_profile Security profile .TP .CR /tmp/sh* For here-documents .TP .CR /usr/bin/sh Shell executable program location .PD .SH SEE ALSO cat(1), cd(1), command(1), echo(1), ed(1), env(1), getopts(1), kill(1), ln(1), login(1), newgrp(1), printf(1), pwd(1), read(1), stty(1), test(1), time(1), umask(1), vi(1), dup(2), exec(2), fork(2), pipe(2), stty(2), ulimit(2), umask(2), wait(2), rand(3C), a.out(4), profile(4), environ(5), lang(5), regexp(5), signal(5). .SH STANDARDS CONFORMANCE .CR sh ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR . ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR : ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR break ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR case ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR continue ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR eval ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR exec ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR exit ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR export ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR for ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR if ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR read ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR return ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR set ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR shift ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR time ": SVID2, SVID3, XPG2, XPG3, XPG4" .br .CR trap ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR unset ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR until ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR while ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4sh\f1 \- shell based on POSIX.2@@@\f3sh-posix(1)\f1 .\" index@\f4alias\f1 \- substitute command and/or file name@@@\f3sh-posix(1)\f1 .\" index@\f4break\f1 \- exit from enclosing for/next loop@@@\f3sh-posix(1)\f1 .\" index@\f4case\f1 \- execute \f2list\f1 associated with \f2pattern\f1 that matches \f2word\f1@@@\f3sh-posix(1)\f1 .\" index@\f4cd\f1 \- change working directory@@@\f3sh-posix(1)\f1 .\" index@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@\f3sh-posix(1)\f1 .\" index@\f4echo\f1 \- echo (print) arguments@@@\f3sh-posix(1)\f1 .\" index@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@\f3sh-posix(1)\f1 .\" index@\f4exec\f1 \- execute command without creating new process@@@\f3sh-posix(1)\f1 .\" index@\f4exit\f1 \- exit shell with exit status@@@\f3sh-posix(1)\f1 .\" index@\f4export\f1 \- export variable names to environment of subsequent commands@@@\f3sh-posix(1)\f1 .\" index@\f4fc\f1 \- edit and execute previous command@@@\f3sh-posix(1)\f1 .\" index@\f4for\f1 \- execute a do list@@@\f3sh-posix(1)\f1 .\" index@\f4if\f1 \- execute command if previous command returns exit status 0@@@\f3sh-posix(1)\f1 .\" index@\f4jobs\f1 \- list active jobs@@@\f3sh-posix(1)\f1 .\" index@\f4kill\f1 \- terminate job or process@@@\f3sh-posix(1)\f1 .\" index@\f4let\f1 \- evaluate arithmetic expression@@@\f3sh-posix(1)\f1 .\" index@\f4newgrp\f1 \- equivalent to \f4exec newgrp\f1@@@\f3sh-posix(1)\f1 .\" index@\f4print\f1 \- output from shell@@@\f3sh-posix(1)\f1 .\" index@\f4pwd\f1 \- print current working directory@@@\f3sh-posix(1)\f1 .\" index@\f4read\f1 \- input and parse a line@@@\f3sh-posix(1)\f1 .\" index@\f4readonly\f1 \- mark names as unredefinable@@@\f3sh-posix(1)\f1 .\" index@\f4return\f1 \- shell function return to invoking script@@@\f3sh-posix(1)\f1 .\" index@\f4set\f1 \- set/define options and arguments@@@\f3sh-posix(1)\f1 .\" index@\f4shift\f1 \- shift \f2argv\f1 members one position to left@@@\f3sh-posix(1)\f1 .\" index@\f4test\f1 \- evaluate conditional expression@@@\f3sh-posix(1)\f1 .\" index@\f4time\f1, \f4times\f1 \- print summary of time used by processes@@@\f3sh-posix(1)\f1 .\" index@\f4trap\f1 \- trap specified signal@@@\f3sh-posix(1)\f1 .\" index@\f4typeset\f1 \- control leading blanks and parameter handling@@@\f3sh-posix(1)\f1 .\" index@\f4ulimit\f1 \- set size or time limits@@@\f3sh-posix(1)\f1 .\" index@\f4umask\f1 \- set permissions mask for creating new files@@@\f3sh-posix(1)\f1 .\" index@\f4unalias\f1 \- discard specified alias@@@\f3sh-posix(1)\f1 .\" index@\f4unset\f1 \- remove definition/setting of options and arguments@@@\f3sh-posix(1)\f1 .\" index@\f4until\f1 \- execute commands until expression is nonzero@@@\f3sh-posix(1)\f1 .\" index@\f4wait\f1 \- wait for child process@@@\f3sh-posix(1)\f1 .\" index@\f4whence\f1 \- define interpretation of name as a command@@@\f3sh-posix(1)\f1 .\" index@\f4while\f1 \- execute commands while expression is nonzero@@@\f3sh-posix(1)\f1 .\" .\" toc@\f3sh-posix(1)\f1:\0\0\f4sh\f1@@@shell, the standard/restricted command programming language .\" toc@\f4case\f1 \- label in a switch statement@@@see \f3sh-posix(1)\f1 .\" toc@\f4alias\f1 \- substitute command and/or file name@@@see \f3sh-posix(1)\f1 .\" toc@\f4break\f1 \- exit from enclosing for/next loop@@@see \f3sh-posix(1)\f1 .\" toc@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@see \f3sh-posix(1)\f1 .\" toc@\f4cd\f1 \- change working directory@@@see \f3sh-posix(1)\f1 .\" toc@\f4echo\f1 \- echo (print) arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@see \f3sh-posix(1)\f1 .\" toc@\f4exec\f1 \- execute command without creating new process@@@see \f3sh-posix(1)\f1 .\" toc@\f4exit\f1 \- exit shell with exit status@@@see \f3sh-posix(1)\f1 .\" toc@\f4export\f1 \- export variable names to environment of subsequent commands@@@see \f3sh-posix(1)\f1 .\" toc@\f4fc\f1 \- edit and execute previous command@@@see \f3sh-posix(1)\f1 .\" toc@\f4for\f1 \- execute a do list@@@see \f3sh-posix(1)\f1 .\" toc@\f4if\f1 \- execute command if previous command returns exit status 0@@@see \f3sh-posix(1)\f1 .\" toc@\f4jobs\f1 \- list active jobs@@@see \f3sh-posix(1)\f1 .\" toc@\f4kill\f1 \- terminate job or process@@@see \f3sh-posix(1)\f1 .\" toc@\f4let\f1 \- evaluate arithmetic expression@@@see \f3sh-posix(1)\f1 .\" toc@\f4newgrp\f1 \- equivalent to \f2exec newgrp\f1@@@see \f3sh-posix(1)\f1 .\" toc@\f4print\f1 \- output from shell@@@see \f3sh-posix(1)\f1 .\" toc@\f4pwd\f1 \- print current working directory@@@see \f3sh-posix(1)\f1 .\" toc@\f4read\f1 \- input and parse a line@@@see \f3sh-posix(1)\f1 .\" toc@\f4readonly\f1 \- mark names as unredefinable@@@see \f3sh-posix(1)\f1 .\" toc@\f4return\f1 \- shell function return to invoking script@@@see \f3sh-posix(1)\f1 .\" toc@\f4set\f1 \- set/define options and arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4shift\f1 \- shift \f2argv\f1 members one position to left@@@see \f3sh-posix(1)\f1 .\" toc@\f4test\f1 \- evaluate conditional expression@@@see \f3sh-posix(1)\f1 .\" toc@\f4trap\f1 \- trap specified signal@@@see \f3sh-posix(1)\f1 .\" toc@\f4time, times\f1 \- print summary of time used by processes@@@see \f3sh-posix(1)\f1 .\" toc@\f4typeset\f1 \- control leading blanks and parameter handling@@@see \f3sh-posix(1)\f1 .\" toc@\f4ulimit\f1 \- set size or time limits@@@see \f3sh-posix(1)\f1 .\" toc@\f4umask\f1 \- set permissions mask for creating new files@@@see \f3sh-posix(1)\f1 .\" toc@\f4unalias\f1 \- discard specified alias@@@see \f3sh-posix(1)\f1 .\" toc@\f4unset\f1 \- remove definition/setting of options and arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4wait\f1 \- wait for child process@@@see \f3sh-posix(1)\f1 .\" toc@\f4whence\f1 \- define interpretation of name as a command@@@see \f3sh-posix(1)\f1 .\" toc@\f4while\f1 \- execute commands while expression is nonzero@@@see \f3sh-posix(1)\f1 .\" toc@\f4until\f1 \- execute commands until expression is nonzero@@@see \f3sh-posix(1)\f1 .\" .\" links@sh-posix.1 alias.1 .\" links@sh-posix.1 bg.1 .\" links@sh-posix.1 fc.1 .\" links@sh-posix.1 fg.1 .\" links@sh-posix.1 jobs.1 .\" links@sh-posix.1 unalias.1 .\" $Header: bs.1,v 72.3 93/01/14 11:17:55 ssa Exp $ .TA b .TH bs 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bs \- a compiler/interpreter for modest-sized programs .SH SYNOPSIS .C bs .RI [ \|file .RI [ \|args\| ]\|] .SH DESCRIPTION .C bs is a remote descendant of .SM BASIC and .SM SNOBOL\c 4 with some C language added. .C bs is designed for programming tasks where program development time is as important as the resulting speed of execution. Formalities of data declaration and file/process manipulation are minimized. Line-at-a-time debugging, the .C trace and .C dump statements, and useful run-time error messages all simplify program testing. Furthermore, incomplete programs can be debugged; .I inner functions can be tested before .I outer functions have been written, and vice versa. .PP If .I file is specified on the command-line, it is used for input before any input is taken from the keyboard. By default, statements read from .I file are compiled for later execution. Likewise, statements entered from the keyboard are normally executed immediately (see .C compile and .C execute below). Unless the final operation is assignment, the result of an immediate expression statement is printed. .PP .C bs programs are made up of input lines. If the last character on a line is a .CR \e , the line is continued. .C bs accepts lines of the following form: .IP .I statement .br .I label\0statement .PP A label is a .I name (see below) followed by a colon. A label and a variable can have the same name. .PP A .C bs statement is either an expression or a keyword followed by zero or more expressions. Some keywords .RC ( clear , .CR compile , .CR ! , .CR execute , .CR include , .CR ibase , .CR obase , and .CR run ) are always executed as they are compiled. .SS Statement Syntax: .TP 15 .I expression The expression is executed for its side effects (value, assignment, or function call). The details of expressions follow the description of statement types below. .TP .C break .C break exits from the innermost .CR for / while loop. .TP .C clear Clears the symbol table and compiled statements. .C clear is executed immediately. .TP .CR compile \0[\f2expression\fP] Succeeding statements are compiled (overrides the immediate execution default). The optional expression is evaluated and used as a file name for further input. A .C clear is associated with this latter case. .C compile is executed immediately. .TP .C continue .C continue transfers to the loop-continuation of the current .CR for / while loop. .TP .CR dump \0[\f2name\fP] The name and current value of every non-local variable is printed. Optionally, only the named variable is reported. After an error or interrupt, the number of the last statement is displayed. The user-function trace is displayed after an error or .C stop that occurred in a function. .TP .C edit A call is made to the editor selected by the .C EDITOR environment variable if it is present, or .IR ed (1) if .C EDITOR is undefined or null. If the .I file argument is present on the command line, .I file is passed to the editor as the file to edit (otherwise no file name is used). Upon exiting the editor, a .C compile statement (and associated .CR clear ) is executed giving that file name as its argument. .TP .CR exit \0[\f2expression\fP] Return to system level. The expression is returned as process status. .TP .C execute Change to immediate execution mode (an interrupt has a similar effect). This statement does not cause stored statements to execute (see .C run below). .ne 8 .TP .CI for " name " = " expression expression statement" .PD 0 .TP .CI for " name " = " expression expression" .TP \h'.5i'\&... .TP .C next .PD .TP .CI for " expression " , " expression " , " expression statement" .PD 0 .TP .CI for " expression " , " expression " , " expression" .TP \h'.5i'\&... .TP .C next The .C for statement repetitively executes a statement (first form) or a group of statements (second form) under control of a named variable. The variable takes on the value of the first expression, then is incremented by one on each loop, not to exceed the value of the second expression. The third and fourth forms require three expressions separated by commas. The first of these is the initialization, the second is the test (true to continue), and the third is the loop-continuation action (normally an increment). .PD .TP .CR fun\0\f2f\fP\|( \|[\f2a\fP,\0...\|]\| ) \0[\|v,\0...\|] .PD 0 .TP \h'.5i'\&... .TP .C nuf .C fun defines the function name, arguments, and local variables for a user-written function. Up to ten arguments and local variables are allowed. Such names cannot be arrays, nor can they be .SM I/O associated. Function definitions cannot be nested. Calling an undefined function is permissible; see function calls below. .PD .TP .C freturn A way to signal the failure of a user-written function. See the interrogation operator .RC ( ? ) below. If interrogation is not present, .C freturn merely returns zero. When interrogation .I is active, .C freturn transfers to that expression (possibly by-passing intermediate function returns). .TP .CI goto \0name Control is passed to the internally stored statement with the matching label. .TP .CI ibase \0n .C ibase sets the input base (radix) to .IR n . The only supported values for .I n are the constants .CR 8 , .C 10 (the default), and .CR 16 . Hexadecimal values 10-15 are entered as .CR a - f . A leading digit is required (i.e., .C f0a must be entered as .CR 0f0a ). .C ibase (and .C obase discussed below) are executed immediately. .TP .CI if " expression statement" .PD 0 .TP .CI if \0expression .TP \h'.5i'... .TP .RC [ else ...] .TP .C fi The statement (first form) or group of statements (second form) is executed if the expression evaluates to non-zero. The strings .C 0 and \f3"\|"\f1 (null) evaluate as zero. In the second form, an optional .C else provides for a second group of statements to be executed when the first group is not. The only statement permitted on the same line with an .C else is an .CR if ; only other .CR fi s can be on the same line with a .CR fi . The concatenation of .C else and .C if into an .C elif is supported. Only a single .C fi is required to close an .CR if \0... \0elif \0... .RC [ \0else \0...\0] sequence. .PD .TP .CI include \0expression .I expression must evaluate to a file name. The file must contain .C bs source statements. Such statements become part of the program being compiled. .C include statements cannot be nested. .TP .CI obase \0n .C obase sets the output base to .I n (see .C ibase above). .TP .CI onintr \0label .PD 0 .TP .C onintr .C onintr provides program control of interrupts. In the first form, control passes to the label given, just as if a .C goto had been executed at the time .C onintr was executed. The effect of the statement is cleared after each interrupt. In the second form, an interrupt causes .C bs to terminate. .PD .TP .CR return \0[\f2expression\fP] The expression is evaluated and the result is passed back as the value of a function call. If no expression is given, zero is returned. .TP .C run The random number generator is reset. Control is passed to the first internal statement. If the .C run statement is contained in a file, it should be the last statement. .TP .C stop Execution of internal statements is stopped. .C bs reverts to immediate mode. .TP .CR trace \0[\f2expression\fP] The .C trace statement controls function tracing. If the expression is null (or evaluates to zero), tracing is turned off. Otherwise, a record of user-function calls/returns is printed. Each .C return decrements the .C trace .I expression value. .TP .CI while " expression statement" .PD 0 .TP 15 .CI while \0expression .TP \h'.5i'\&... .TP .C next .C while is similar to .C for except that only the conditional expression for loop-continuation is given. .PD .TP .CI ! " shell command" An immediate escape to the shell. .TP .CR # \0... This statement is ignored (treated as a comment). .SS Expression Syntax: .TP 15 name A name is used to specify a variable. Names are composed of a letter (uppercase or lowercase) optionally followed by letters and digits. Only the first six characters of a name are significant. Except for names declared in .I fun statements, all names are global to the program. Names can take on numeric (double float) values, string values, or can be associated with input/output (see the built-in function .IR open (\|) below). .TP name ( [expression [ , expression] ... ] ) Functions can be called by a name followed by the arguments in parentheses separated by commas. Except for built-in functions (listed below), the name must be defined with a .I fun statement. Arguments to functions are passed by value. If the function is undefined, the call history to the call of that function is printed, and a request for a return value (as an expression) is made. The result of that expression is taken to be the result of the undefined function. This permits debugging programs where not all the functions are yet defined. The value is read from the current input file. .TP name [ expression [ , expression ] ... ] This syntax is used to reference either arrays or tables (see built-in .I table functions below). For arrays, each expression is truncated to an integer and used as a specifier for the name. The resulting array reference is syntactically identical to a name; .C a[1,2] is the same as .CR a[1][2] . The truncated expressions are restricted to values between 0 and 32\|767. .TP number A number is used to represent a constant value. A number is written in Fortran style, and contains digits, an optional decimal point, and possibly a scale factor consisting of an .C e followed by a possibly signed exponent. .TP string Character strings are delimited by \f3"\fP characters. The .C \e escape character allows the double quote (\c .C \e\c \f3"\fP\c ), new-line .RC ( \en ), carriage return .RC ( \er ), backspace .RC (\eb), and tab .RC ( \et ) characters to appear in a string. Otherwise, .C \e stands for itself. .TP ( expression ) Parentheses are used to alter the normal order of evaluation. .TP ( expression , expression [ , expression ... ] ) [ expression ] The bracketed expression is used as a subscript to select a comma-separated expression from the parenthesized list. List elements are numbered from the left, starting at zero. .br The expression: .RS .IP .C "( False, True )[ a == b ]" .RE .IP has the value .C True if the comparison is true. .TP .CR ? \0expression The interrogation operator tests for the success of the expression rather than its value. At the moment, it is useful for testing end-of-file (see examples in the .I "Programming Tips" section below), the result of the .C eval built-in function, and for checking the return from user-written functions (see .CR freturn ). An interrogation ``trap'' (end-of-file, etc.) causes an immediate transfer to the most recent interrogation, possibly skipping assignment statements or intervening function levels. .TP .CR - \0expression The result is the negation of the expression. .TP .CR ++ \0name Increments the value of the variable (or array reference). The result is the new value. .TP .CR -\|- \0name Decrements the value of the variable. The result is the new value. .TP .CR ! expression The logical negation of the expression. Watch out for the shell escape command. .TP expression .I operator expression Common functions of two arguments are abbreviated by the two arguments separated by an operator denoting the function. Except for the assignment, concatenation, and relational operators, both operands are converted to numeric form before the function is applied. .SS Binary Operators \f1(in increasing precedence)\fP: .TP 15 .C = .C = is the assignment operator. The left operand must be a name or an array element. The result is the right operand. Assignment binds right to left, all other operators bind left to right. .TP .C _ .C _ (underscore) is the concatenation operator. .TP .C & | .C & (logical .SM AND\c ) has result zero if either of its arguments are zero. It has result one if both of its arguments are non-zero; .C | (logical .SM OR\c ) has result zero if both of its arguments are zero. It has result one if either of its arguments is non-zero. Both operators treat a null string as a zero. .TP .C "< <= > >= == != The relational operators .RC ( < : less than, .CR <= : less than or equal, .CR > : greater than, .CR >= : greater than or equal, .CR == : equal to, .CR != : not equal to) return one if their arguments are in the specified relation, or return zero otherwise. Relational operators at the same level extend as follows: .C a>b>c is equivalent to .IR "a>b & b>c" . A string comparison is made if both operands are strings. .TP .C + - Add and subtract. .TP .C * / % Multiply, divide, and remainder. .TP .C ^ Exponentiation. .ne 6 .SS Built-in Functions: .ce .I "Dealing with arguments" .TP 15 .CI arg( i ) is the value of the .IR i -th actual parameter on the current level of function call. At level zero, .I arg returns the .IR i -th command-line argument .RI ( arg (0) returns .CR bs ). .TP .C narg(\|) returns the number of arguments passed. At level zero, the command argument count is returned. .PP .ce .I "Mathematical" .TP 15 .CI abs( x ) is the absolute value of .IR x . .TP .CI atan( x ) is the arctangent of .IR x . Its value is between \(mi\(*p/2 and \(*p/2. .TP .CI ceil( x ) returns the smallest integer not less than .IR x . .TP .CI cos( x ) is the cosine of .I x (radians). .TP .CI exp( x ) is the exponential function of .IR x . .TP .CI floor( x ) returns the largest integer not greater than .IR x . .TP .CI log( x ) is the natural logarithm of .IR x . .ne 3 .TP .C rand(\|) is a uniformly distributed random number between zero and one. .TP .CI sin( x ) is the sine of .I x (radians). .TP .CI sqrt( x ) is the square root of .IR x . .PP .ce .I "String operations" .TP 15 .CI size( s ) the size (length in bytes) of .I s is returned. .TP .CI format( f , \0a ) returns the formatted value of .IR a . .I f is assumed to be a format specification in the style of .IR printf (3S). Only the .CR %\|...\|f , .CR %\|...\|e , and .C %\|...\|s types are safe. Since it is not always possible to know whether .C a is a number or a string when the .C format call is coded, coercing .C a to the type required by .C f by either adding zero (for .C e or .C f format) or concatenating .RC ( _ ) the null string (for .C s format) should be considered. .TP .CI index( x , \0y ) returns the number of the first position in .I x that any of the characters from .I y matches. No match yields zero. .TP .CI trans( s , \0f,\0t ) Translates characters of the source .I s from matching characters in .I f to a character in the same position in .IR t . Source characters that do not appear in .I f are copied to the result. If the string .I f is longer than .IR t , source characters that match in the excess portion of .I f do not appear in the result. .TP .CI substr( s , \0start,\0width ) returns the sub-string of .I s defined by the .IR start ing position and .IR width . .TP .CI match( string , \0pattern ) .TP .CI mstring( n ) The .I pattern is a regular expression according to the Basic Regular Expression definition (see .IR regexp (5)). .C mstring returns the .IR n -th (1 <= .I n <= 10) substring of the subject that occurred between pairs of the pattern symbols .C \e( and .C \e) for the most recent call to .IR match . To succeed, patterns must match the beginning of the string (as if all patterns began with .CR ^ ). The function returns the number of characters matched. For example: .RS .tr ~" .IP .C "match(~a123ab123~, ~.*\e([a-z]\e)~) == 6" .br .C mstring(1) == ~b~ .PP .RE .ce .I "File handling" .TP 15 .CI open( name , \0file,\0function ) .PD 0 .TP .CI close( name ) .I name argument must be a .C bs variable name (passed as a string). For the .CR open , the .I file argument can be: .RS .RS .TP 4 1. a 0 (zero), 1, or 2 representing standard input, output, or error output, respectively; .TP 2. a string representing a file name; or .TP 3. a string beginning with an .C ! representing a command to be executed (via .CR "sh -c" ). The .I function argument must be either .C r (read), .C w (write), .C W (write without new-line), or .C a (append). After a .CR close , .I name reverts to being an ordinary variable. If .I name was a pipe, a .C wait() is executed before the close completes (see .IR wait (2)). The .C bs exit command does not do such a wait. The initial associations are: .PD .RS .nf .IP .C "open(~get~, 0, ~r~)" .C "open(~put~, 1, ~w~)" .C "open(~puterr~, 2, ~w~)" .RE .fi .IP Examples are given in the following section. .RE .RE .TP .CI access( s , \0m ) executes .C access() (see .IR access (2)). .TP .CI ftype( s ) returns a single character file type indication: .C f for regular file, .C p for .SM FIFO (i.e., named pipe), .C d for directory, .C b for block special, or .C c for character special. .SS Tables .TP 15 .CI table( name , \0size ) A table in .C bs is an associatively accessed, single-dimension array. ``Subscripts'' (called keys) are strings (numbers are converted). The .I name argument must be a .C bs variable name (passed as a string). The .I size argument sets the minimum number of elements to be allocated. .C bs prints an error message and stops on table overflow. The result of .I table is .IR name . .TP 15 .CI item( name , \0i ) .PD 0 .TP 15 .C key() The .C item function accesses table elements sequentially (in normal use, there is no orderly progression of key values). Where the .C item function accesses values, the .C key function accesses the ``subscript'' of the previous .C item call. It fails (or in the absence of an .C interrogate operator, returns null) if there was no valid subscript for the previous .C item call. The .I name argument should not be quoted. Since exact table sizes are not defined, the interrogation operator should be used to detect end-of-table; for example: .PD .RS .nf .IP .C table(~t~, 100) \h'.4i'... .C "# If word contains ~party~, the following expression adds one" .C "# to the count of that word:" .C "++t[word]" \h'.4i'... .C "# To print out the the key/value pairs:" .C "for i = 0, ?(s = item(t, i)), ++i if key() put = key()_~:~_s" .RE .fi .IP If the interrogation operator is not used, the result of .C item is null if there are no further elements in the table. Null is, however, a legal ``subscript''. .TP .CI iskey( name , \0word ) .C iskey tests whether the key .I word exists in the table .I name and returns one for true, zero for false. .PP .ce .I "Odds and ends" .TP 15 .CI eval( s ) The string argument is evaluated as a .C bs expression. The function is handy for converting numeric strings to numeric internal form. .C eval can also be used as a crude form of indirection, as in: .RS .IP .C name = ~xyz~ .C eval(~++~_ name) .RE .IP which increments the variable .IR xyz . In addition, .C eval preceded by the interrogation operator permits the user to control .C bs error conditions. For example: .RS .IP .C "?eval(~open(\e~\s-1X\s+1\e~, \e~XXX\e~, \e~r\e~)~)" .RE .IP returns the value zero if there is no file named .C XXX (instead of halting the user's program). The following executes a .C goto to the label .C L (if it exists): .RS .IP .C label=~L~ .br .C "if !(?eval(~goto ~\(ul label)) puterr = ~no label~" .RE .tr ~~ .TP .CI plot( request , \0args ) If the .C tplot command is available, the .C plot function produces output on devices recognized by .CR tplot . The .I requests are as follows: .RS .RS .TP 35 .B Call .B Function .TP .CI plot(0, \0term ) causes further .I plot output to be piped into .I tplot with an argument of .CI -T term. .I term can be up to 40 characters in length. .TP .C plot(1) ``erases'' the plotter. .TP .CI plot(2, \0string ) labels the current point with .IR string . .TP .CI plot(3, " x1, y1, x2, y2" ) draws the line between .RI ( x1 , y1 ) and .RI ( x2 , y2 ). .TP .CI plot(4, " x, y, r" ) draws a circle with center .RI ( x , y ) and radius .IR r . .TP .CI plot(5, " x1, y1, x2, y2, x3, y3" ) draws an arc (counterclockwise) with center .RI ( x1 , y1 ) and endpoints .RI ( x2 , y2 ) and .RI ( x3 , y3 ). .TP .C plot(6) is not implemented. .TP .CI plot(7, " x, y" ) makes the current point .RI ( x , y ). .TP .CI plot(8, " x, y" ) draws a line from the current point to .RI ( x , y ). .TP .CI plot(9, \0x , \0y ) draws a point at .RI ( x , y ). .TP .CI plot(10, " string" ) sets the line mode to .IR string . .TP .CI plot(11, " x1, y1, x2, y2" ) makes .RI ( x1 , y1 ) the lower left corner of the plotting area and .RI ( x2 , y2 ) the upper right corner of the plotting area. .TP .CI plot(12, " x1, y1, x2, y2" ) causes subsequent x (y) coordinates to be multiplied by .I x1 .RI ( y1 ) and then added to .I x2 .RI ( y2 ) before they are plotted. The initial scaling is .CR "plot(12, 1.0, 1.0, 0.0, 0.0)" . .RE .IP Some requests do not apply to all plotters. All requests except zero and twelve are implemented by piping characters to .IR tplot . .PP Each statement executed from the keyboard re-invokes .CR tplot , making the results unpredictable if a complete picture is not done in a single operation. Plotting should thus be done either in a function or a complete program, so all the output can be directed to .C tplot in a single stream. .TP 15 .C last() in immediate mode, .C last returns the most recently computed value. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the collating sequence used in evaluating regular expressions. .PP .C LC_CTYPE determines the characters matched by character class expressions in regular expressions. .PP If .C LC_COLLATE or .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C bs behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte character code sets are supported. .SH EXAMPLES Using .C bs as a calculator .RC ( $ is the shell prompt): .RS .PP .nf .ift .ft 4 .ifn .ft 3 .ps +1 $ bs # Distance (inches) light travels in a nanosecond. 186000 * 5280 * 12 / 1e9 11.78496 \h'.8i'... .ift .sp .5v .ifn .sp # Compound interest (6% for 5 years on $1,000). int = .06 / 4 bal = 1000 for i = 1 5*4 bal = bal + bal*int bal - 1000 346.855007 \h'.8i'... .C exit .ft .ps .fi .RE .PP The outline of a typical .C bs program: .RS .PP .nf .ift .ft 4 .ifn .ft 3 .ps +1 # initialize things: var1 = 1 open("read", "infile", "r") \h'.8i'... # compute: while ?(str = read) \h'.8i'... next # clean up: close("read") \h'.8i'... # last statement executed (exit or stop): exit # last input line: run .ft .ps .fi .RE .PP Input/Output examples: .RS .PP .nf .ift .ft 4 .ifn .ft 3 .ps +1 # Copy file oldfile to file newfile. open("read", "oldfile", "r") open("write", "newfile", "w") \h'.8i'... while ?(write = read) \h'.8i'... # close "read" and "write": close("read") close("write") .ift .sp .5v .ifn .sp # Pipe between commands. open("ls", "!ls *", "r") open("pr", "!pr -2 -h 'List'", "w") while ?(pr = ls) ... \h'.8i'... # be sure to close (wait for) these: close("ls") close("pr") .ft .ps .fi .RE .SH WARNINGS The graphics mode .RC ( plot \0...) is not particularly useful unless the .C tplot command is available on your system. .PP .C bs is not tolerant of some errors. For example, mistyping a .C fun declaration is difficult to correct because a new definition cannot be made without doing a .CR clear . The best solution in such a case is to start by using the .C edit command. .SH SEE ALSO ed(1), sh(1), access(2), printf(3S), stdio(3S), lang(5), regexp(5). .PP See Section (3M) for a further description of the mathematical functions. .br .C pow() is used for exponentiation \(em see .IR exp (3M)); .br .C bs uses the Standard I/O package. .\" .\" index@\f4bs\f1 \- a compiler/interpreter for modest-sized programs@@@\f3bs(1)\f1 .\" index@compiler/interpreter for modest-sized programs@@@\f3bs(1)\f1 .\" index@interpreter/compiler for modest-sized programs@@@\f3bs(1)\f1 .\" index@modest-sized programs, compiler/interpreter for@@@\f3bs(1)\f1 .\" index@programs, a compiler/interpreter for modest-sized@@@\f3bs(1)\f1 .\" .\" toc@\f3bs(1)\f1:\0\0\f4bs\f1@@@a compiler/interpreter for modest-sized programs .\" .\" fileset_database@bs.1 USER-CMDS-MAN .\" $Header: cal.1,v 76.2 95/08/23 17:51:46 ssa Exp $ .\" cal.1,v 1.6 94/12/12 12:39:10 venu Exp $ .TA c .TH cal 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cal \- print calendar .SH SYNOPSIS .C cal .RI [\|[ \|month\| ] .IR year\| ] .SH DESCRIPTION .C cal prints a calendar for the specified year. If a month is also specified, a calendar just for that month is printed. If neither is specified, a calendar for the present month is printed. .I year can be between 1 and 9999. .I month is a decimal number between 1 and 12. The calendar produced is a Gregorian calendar. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not set or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .CR LC_CTYPE determines the locale for interpretation of sequences of bytes of text data as characters (e.g., single- verses multibyte characters in arguments and input files). .PP .C LC_TIME determines the format and contents of the calendar. .PP .C TZ determines the timezone used to calculate the value of the current month. .PP If any internationalization variable contains an invalid setting, .CR cal behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The command: .IP .C cal 9 1850 .PP prints the calendar for September, 1850 on the screen as follows: .nf .IP .C " September 1850" .C " S M Tu W Th F S" .C " 1 2 3 4 5 6 7" .C " 8 9 10 11 12 13 14" .C "15 16 17 18 19 20 21" .C "22 23 24 25 26 27 28" .C "29 30" .PP However, for XPG4 the output looks like below: .nf .IP .C " Sep 1850" .C "Sun Mon Tue Wed Thu Fri Sat" .C " 1 2 3 4 5 6 7" .C " 8 9 10 11 12 13 14" .C "15 16 17 18 19 20 21" .C "22 23 24 25 26 27 28" .C "29 30" .PP .SH WARNINGS The year is always considered to start in January even though this is historically naive. .PP Beware that .C cal 83 refers to the early Christian era, not the 20th century. .SH STANDARDS CONFORMANCE .CR cal ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" toc@\f3cal(1)\f1:\0\0\f4cal\f1@@@print calendar .\" .\" index@\f4cal\f1 \- print calendar@@@\f3cal(1)\f1 .\" index@calendar, print@@@\f3cal(1)\f1 .\" index@print calendar@@@\f3cal(1)\f1 .\" .\" $Header: calendar.1,v 72.7 94/11/30 15:42:14 ssa Exp $ .TA c .TH calendar 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME calendar \- reminder service .SH SYNOPSIS .C calendar .RC [ - ] .SH DESCRIPTION .C calendar consults the file .C calendar in the current directory and prints out lines containing today's or tomorrow's date anywhere in the line. On weekends, ``tomorrow'' extends through Monday. .PP When a .C - command-line argument is present, .C calendar searches for the file .C calendar in each user's home directory, and sends any positive results to the user by .C mail (see .IR mail (1)). Normally this is done daily in the early morning hours under the control of .C cron (see .IR cron (1M)). When invoked by .CR cron , .C calendar reads the first line in the .C calendar file to determine the user's environment. .PP Language-dependent information such as spelling and date format (described below) are determined by the user-specified .C LANG statement in the .C calendar file. This statement should be of the form .CI LANG= language where .I language is a valid language name (see .IR lang (5)). If this line is not in the .C calendar file, the action described in the .SM EXTERNAL INFLUENCES Environment Variable section is taken. .PP .C calendar is concerned with two fields: month and day. A month field can be expressed in three different formats: a string representing the name of the month (either fully spelled out or abbreviated), a numeric month, or an asterisk (representing any month). If the month is expressed as a string representing the name of the month, the first character can be either upper-case or lower-case; other characters must be lower-case. The spelling of a month name should match the string returned by calling .C nl_langinfo() (see .IR nl_langinfo (3C)). The day field is a numeric value for the day of the month. .SS "Month-Day Formats" If the month field is a string, it can be followed by zero or more blanks. If the month field is numeric, it must be followed by either a slash .RC ( / ) or a hyphen .RC ( - ). If the month field is an asterisk .RC ( * ), it must be followed by a slash .RC ( / ). The day field can be followed immediately by a blank or non-digit character. .PP .SS "Day-Month Formats" The day field is expressed as a numeral. What follows the day field is determined by the format of the month. If the month field is a string, the day field must be followed by zero or one dot .RC ( . ) followed by zero or more blanks. If the month field is a numeral, the day field must be followed by either a slash .RC ( / ) or a hyphen .RC ( - ). If the month field is an asterisk, the day field must be followed by a slash .RC ( / ). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_TIME determines the format and contents of date and time strings when no .C LANG statement is specified in the .C calendar file. .PP .C LANG determines the language in which messages are displayed. .PP If .C LC_TIME is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C calendar behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following .C calendar file illustrates several formats recognized by .IR calendar : .nf .IP .C LANG=en_US.roman8 .C "Friday, May 29th: group coffee meeting" .C "meeting with Boss on June 3." .C "3/30/87 - quarter end review" .C "4-26 Management council meeting at 1:00 pm" .C "It is first of the month ( */1 ); status report due." .fi .PP In the following .C calendar file, dates are expressed according to European English usage: .nf .IP .C "LANG=en_GB.roman8" .C "On 20 Jan. code review" .C "Jim's birthday is on the 3. February" .C "30/3/87 - quarter end review" .C "26-4 Management council meeting at 1:00 pm" .C "It is first of the month ( 1/* ); status report due." .fi .RE .SH WARNINGS To get reminder service, either your calendar must be public information or you must run .C calendar from your personal .C crontab file, independent of any .C calendar\0- run systemwide. Note that if you run .C calendar yourself, the calendar file need not reside in your home directory. .PP .CR calendar 's extended idea of ``tomorrow'' does not account for holidays. .SH AUTHOR .C calendar was developed by AT&T and HP. .SH FILES .TP 25 .C calendar .PD 0 .TP .C /tmp/cal* .TP .C /usr/lbin/calprog to figure out today's and tomorrow's dates .TP .C /usr/bin/crontab .TP .C /etc/passwd .PD .SH SEE ALSO cron(1M), nl_langinfo(3C), mail(1), environ(5). .SH STANDARDS CONFORMANCE .CR calendar ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4calendar\f1 \- reminder service@@@\f3calendar(1)\f1 .\" index@reminder service@@@\f3calendar(1)\f1 .\" index@service, reminder@@@\f3calendar(1)\f1 .\" .\" toc@\f3calendar(1)\f1:\0\0\f4calendar\f1@@@reminder service .\" .\" fileset_database@calendar.1 USER-CMDS-MAN .\" $Header: lp.1,v 76.1 95/08/23 17:55:12 ssa Exp $ .TA l .TH lp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lp, lpalt, cancel \- print/alter/cancel requests on an LP printer or plotter .SH SYNOPSIS .CR lp .RC \|[ -c ]\| .RC \|[ -d \f2dest\fP]\| .RC \|[ -m ]\| .RC \|[ -n \f2number\fP]\| .RC \|[ -o \f2option\fP]\| .RC \|[ -p \f2priority\fP]\| .RC \|[ -s ]\| .ifn .br \" force line break and indentation for nroff/man .ifn .CR "\0\0\0\0" \" makes a five-space intent .RC \|[ -t \f2title\fP]\| .RC \|[ -w ]\| .RI \|[ file \0...\&]\| .PP .CR lpalt .IR id .RC \|[ -d \f2dest\fP]\| .RC \|[ -i ]\| .RC \|[ -m ]\| .RC \|[ -n \f2number\fP]\| .RC \|[ -o \f2option\fP]\| .RC \|[ -p \f2priority\fP]\| .RC \|[ -s ]\| .ifn .br \" force line break and indentation for nroff/man .ifn .CR "\0\0\0\0" \" makes a five-space intent .RC \|[ -t \f2title\fP]\| .RC \|[ -w ]\| .PP .CR cancel .RI \|[ id \0...\&]\| .RI \|[ printer \0...\&]\| .RC \|[ -a ]\| .RC \|[ -e ]\| .RC \|[ -i ]\| .RC \|[ -u \f2user\fP]\| .SH DESCRIPTION The .CR lp command queues files for printing. The .CR lpalt command changes information in a queued request. The .CR cancel command deletes a queued request. .SS lp Command The .CR lp command arranges for the named files, .IR file \ ..., and associated information (collectively called a .IR request ) to be queued for output to a printer or plotter in the LP (line printer) subsystem. The process is called printing, regardless of the actual output device. .PP .CR lp associates a unique identifier with each request and writes it to standard output, using the message: .IP .CI "request id is\0" \&dest - sequence .CI ( fileinfo ) .PP The request .SM ID is .IC dest - sequence \f1, which can be used later to alter, cancel, or find the status of the request (see .CR lpalt and .CR cancel below, and .IR lpstat (1)). .PP For example, in the following message, .IP .CR "request id is pr47lf8e-2410 (1 file)" .PP the request .SM ID is .CR pr47lf8e-2410 . .SS lp Options and Arguments .CR lp recognizes the following options and arguments. The keyletter options can be specified in any order. The .IR file \0...\& names must be last. Blanks are not permitted between a keyletter and its argument. .TP 15 .IR file \0...\& Print each named file. If no file names are specified, standard input is assumed. The hyphen symbol .RC ( - ) also specifies standard input and can be intermixed on the command line with file names. Files are printed in the same order in which they are specified. .TP .CR -c Copy the named files to LP subsystem spooling directories. .IP Normally, the files are linked into a spool directory. The ownership and mode of the linked files remain unchanged. If the .CR -c option is given, or linking is not possible (perhaps because the printer is not physically attached to the local system or cluster), the files are copied into the spool directories. The ownership and mode of the copies are set to allow read access to owner .CR lp and group .CR bin only. .IP If the files are linked rather than copied, any changes made to the named files after the request is made but before it is printed will be reflected in the printed output. Standard input is always copied instead of linked. .TP 15 .CI -d dest Select .IR dest as the printer or class of printers that is to do the printing. If .IR dest is a printer, the request will be printed only on that specific printer. If .IR dest is a class, the request will be printed on the first available printer that is a member of the class. Under certain conditions (printer unavailability, file space limitation, etc.), requests for a specific .IR dest might not be accepted (see .IR accept (1M) and .IR lpadmin (1M)). .IP If the .CR -d option is omitted, .IR dest is taken from the environment variable .CR LPDEST . If that variable is unset or empty, the default queue is used, if one has been defined. If there is no default queue, or .CR LPDEST is set but invalid, .CR lp issues an error message and the request is not queued. Printer and class names and the default queue are defined by your LP subsystem administrator (see .IR lpadmin (1M) and .IR lpstat (1)). .TP .CR -m Send a mail message (see .IR mail (1)). to the user after the request has been printed. By default, no mail is sent upon normal completion of the print request. .TP .CI -n number Print .IR number copies of the output. The default is 1. .TP .CI -o option Specify a printer-dependent .IR option . You can specify several printer options by repeating the .CR -o option. For information about the options that are available for a printer supported on your system, see the interface script for the printer name in the .CR /etc/lp/interface directory. .TP .CI -p priority Set the priority of the print request. .IR priority must be in the range 0 (lowest priority) to 7 (highest priority). The priority is used to select the next spooled file for the targeted printer or class of printers. If the priority is less than the .IR fence , the minimum priority set for the printer, the print request is deferred until the fence is lowered or the priority is raised. The default for a printer queue is the default priority set by the .CR lpadmin or .CR lpfence command (see .IR lpadmin (1M) and .IR lpsched (1M)). The default for a class queue is the highest default priority among printers in the class. .TP .CR -s Suppress standard output messages from .CR lp such as "\c .CR "request\0id\0is\0" ...\&\c ". Error messages are still displayed on standard error. .TP .CI -t title Print .IR title on the banner page of the output. .TP .CR -w Write a message to the user's terminal after the request has been printed. If the user is not logged in or (for remote printing) if .CR rlpdaemon (see .IR rlpdaemon (1M)) is not running on the user's local system, mail will be sent instead. .SS lpalt Command The .CR lpalt command alters a request made by a previous .CR lp command, if it is not currently printing. (To requeue a currently printing request, use the .CR disable command (see .IR enable (1)) to stop the printer.) .SS lpalt Options .CR lpalt recognizes the following options and arguments, which can be specified in any order. Blanks are not permitted between a keyletter and its argument. .TP 15 .IR id Specifies the request to be altered. .IR id is a request .SM ID returned by .CR lp or .CR lpalt . .TP .CI -d dest Requeue the request to the named printer or class .IR dest . A new unique request .SM ID is written to standard output. .TP .CR -i Alter only local requests. .TP .CR -m Send mail upon normal completion of the print request. .TP .CI -n number Change the number of copies to .IR number . .TP .CI -o option Specify a printer-dependent .IR option . You can specify several printer options by repeating the .CR -o option. All .CR -o options from previous .CR lp and .CR lpalt commands for this request .SM ID are deleted. .TP .CI -p priority Change the request's priority to .IR priority . .TP .CR -s Suppress standard output messages from .CR lpalt such as "\c .CR "request\0id\0is\0" ...\&\c ". Error messages are still displayed on standard error. .TP .CI -t title Change the .IR title on the banner page of the output. .TP .CR -w Write a message to the user's terminal after the request has been printed. If the user is not logged in or (for remote printing) if .CR rlpdaemon (see .IR rlpdaemon (1M)). is not running on the user's local system, mail will be sent instead. .SS cancel Command The .CR cancel command cancels requests that were made with the .CR lp command, even if they are currently printing. At least one .IR id or .IR printer must be specified. .PP The cancellation of a request that is currently printing frees the printer to print its next available request. .SS cancel Options and Arguments .CR cancel recognizes the following options and arguments, which can be specified in any order. Blanks are not permitted between a keyletter and its argument. .TP 15 .IR id \0...\& Specifies one or more requests. .IR id is a request .SM ID returned by .CR lp or .CR lpalt . .TP .IR printer \0...\& Specifies one or more printers. .IR printer is the name of a printer, not a class. Either cancel the request that is currently printing on each .IR printer , or, if an .CR -a , .CR -e , or .CR -u option is specified, specify the printer on which to perform the corresponding operation. .TP .CR -a Remove all requests the user owns on each .IR printer . The owner is determined by the user's login name and the host name of the machine where the .CR lp command was invoked. .TP .CR -e Empty the spool queue of all requests for each .IR printer . Only users with appropriate privileges can use this option. .TP .CR -i Cancel only local requests. .TP .CI -u user Remove any requests belonging to .IR user . You can repeat the .CR -u option to specify more users. Only users with appropriate privileges can use this option. .SS Printing Overview .PP A printer can print requests from one or two destination queues: its own private queue and an optional class queue, which can serve one or more printers. The destination queues are set up with the .CR lpadmin command. The .CR lp command places a printing request into a printer or class destination queue as directed by a user. The .CR lpsched scheduler directs the requests from the destination queues to the printers. The .CR accept and .CR reject commands control whether .CR lp can place requests in the destination queues. The .CR enable and .CR disable commands control whether .CR lpsched can send a queued request to a printer. If a printer has two queues and one queue is rejecting requests, users can still direct requests to the other destination queue and have the requests printed. .CR lpstat reports the current status of the destination queues and the scheduler. See .IR enable (1), .IR lpstat (1), .IR accept (1M), and .IR lpadmin (1M). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not set or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .C LC_ALL determines the locale to use to override any values for locale categories specified by the setting of .C LANG or any environment variables beginning with .CR LC_ . .PP .CR LC_CTYPE determines the locale for interpretation of sequences of bytes of text data as characters (e.g., single- verses multibyte characters in arguments and input files). .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP .C LPDEST determines the output device or destination. If the .C LPDEST environment variable is not set, the .C PRINTER environment variable is used. The .CI -d " dest" option takes precedence over .CR LPDEST . Results are undefined when .C -d is not specified and .C LPDEST contains a value that is not a valid device or destination name. .PP .C PRINTER determines the output device or destination. If the .C LPDEST and .C PRINTER environment variables are not set, an unspecified output device is used. The .CI -d " dest" option and the .C LPDEST environment variable takes precedence over .CR PRINTER . Results are undefined when .C -d is not specified, .C LPDEST is unset, and .C PRINTER contains a value that is not a valid device or destination name. .PP If any internationalization variable contains an invalid setting, the commands behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH RETURN VALUE Exit values are: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR >0 Error condition occurred. .RE .PD .SH EXAMPLES For a HP2934A printer named .CR lp2 , configured with an interface script that defines the .CR -c option to cause the printer to print in a compressed mode, use the following command to print .CR myfile with compressed print on .CR lp2 : .IP .CI "lp -dlp2 -oc myfile" .PP .CR lp can be used at the end of a pipeline to print the results of a previous command. It is commonly used with the .CR pr command (see .IR pr (1)) to print formatted output. For a default printer, to format file .CR .profile into pages and print three copies of it: .IP .C "pr .profile | lp -n3" .SH WARNINGS A remote print request can be altered or cancelled only by the user who requested it, and only from the system from which the the original .CR lp command was issued. .PP If the restrict cancel feature (see .IR lpadmin (1M)) is enabled for the specified printer, a user can only alter or cancel requests owned by the user. .PP For a remote system, .CR lpalt cannot change .IR dest and .IR priority . .SH FILES .TP 35 .PD 0 .CR /etc/lp Directory of spooler configuration data .TP .CR /etc/lp/interface Directory of active LP device interface scripts .TP .CR /usr/lib/lp Directory of model and font file directories .TP .CR /var/adm/lp Directory of spooler log files .TP .CR /var/spool/lp Directory of LP spooling files and directories .PD .SH SEE ALSO enable(1), lpstat(1), mail(1), slp(1), accept(1M), lpadmin(1M), lpana(1M), lpsched(1M), mklp(1M), rcancel(1M), rlp(1M), rlpdaemon(1M), rlpstat(1M). .SH STANDARDS CONFORMANCE .CR lp ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR cancel ": SVID2, SVID3, XPG4" .\" .\" index@\f4lp\f1 \- print requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f4cancel\f1 \- cancel requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f4lpalt\f1 \- alter requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f1print requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f1cancel requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f1requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f1LP printer, print/alter/cancel requests@@@\f3lp(1)\f1 .\" index@\f1printer, LP, print/alter/cancel requests@@@\f3lp(1)\f1 .\" index@\f1plotter@@@see \f2printer\f1 .\" index@\f1line printer@@@see \f2printer\f1 .\" index@\f1spooling@@@see \f2printer\f1 .\" .\" toc@\f3lp(1)\f1:\0\0\f4cancel\f1, \f4lp\f1, \f4lpalt\f1@@@print/alter/cancel requests on an LP printer or plotter .\" toc@\f4cancel\f1:\0\0cancel requests on an LP printer or plotter@@@see \f3lp(1)\f1 .\" toc@\f4lpalt\f1:\0\0alter requests on an LP printer or plotter@@@see \f3lp(1)\f1 .\" .\" links@lp.1 cancel.1 .\" links@lp.1 lpalt.1 .\" $Header: capture.1,v 72.2 94/09/09 16:10:51 ssa Exp $ .TA c .TH capture 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME capture\ - Capture a window, region, or full screen and save it in a file .SH SYNOPSIS .CI /opt/screencapture/bin/capture \0 .SH DESCRIPTION .PP You can use the .C capture command to take a picture of part or all of your screen and save it as a file. This is also known as a window dump. .PP You can capture windows with or without borders, all of your screen, or part of your screen. This command allows you to save files in a variety of graphics formats, including uncompressed formats (such as XWD) and compressed formats (such as TIFF LZW). .PP For more details, use the help button provided. .SH AUTHOR .C capture was developed by .SM HP. .SH SEE ALSO sprint(1). .\" .\" index@\f2capture\f1 \- SharedPrint/UX@@@\f3capture(1)\f1 .\" index@capture@@@\f3capture(1)\f1 .\" index@SharedPrint/UX@@@\f3SharedPrint/UX(1)\f1 .\" .\" toc@\f3capture(1)\f1:\0\0\f2capture\f1@@@SharedPrint/UX .\" .\" fileset_database@capture.1 SCNCAP-MAN .\" $Header: cat.1,v 76.1 95/08/01 16:04:33 ssa Exp $ .TA c .TH cat 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cat \- concatenate, copy, and print files .SH SYNOPSIS .C cat .RC [ -benrstuv ] .IR file \0... .SH DESCRIPTION .C cat reads each .I file in sequence and writes it on the standard output. Thus: .IP .CI cat\0 file .PP prints .I file on the default standard output device; .IP .CI cat " file1 file2 " "> " file3 .PP concatenates .I file1 and .I file2, and places the result in .IR file3 . .PP If .C - is appears as a .I file argument, .C cat uses standard input. To combine standard input and other files, use a combination of .C - and .I file arguments. .SS Options .C cat recognizes the following options: .RS .TP 5 .C -b Omit line numbers from blank lines when .C -n option is specified. If this option is specified, the .C -n option is automatically selected. .TP .C -e Print a .C $ character at the end of each line (prior to the new-line). If this option is specified, the .C -v option is automatically selected. .TP .C -n Display output lines preceded by line numbers, numbered sequentially from 1. .TP .C -r Replace multiple consecutive empty lines with one empty line, so that there is never more than one empty line between lines containing characters. .TP .C -s Silent option. .C cat suppresses error messages about non-existent files, identical input and output, and write errors. Normally, input and output files cannot have identical names unless the file is a special file. .TP .C -t Print each tab character as .CR ^I . If this option is specified, the .C -v option is automatically selected. .TP .C -u Do not buffer output (handle character-by-character). Normally, output is buffered. .TP .C -v Cause non-printing characters (with the exception of tabs, new-lines and form-feeds) to be printed visibly. Control characters are printed using the form .CI ^ X .RI (Ctrl- X ), and the .SM DEL character (octal 0177) is printed as .C ^? (see .IR ascii (5)). Single-byte control characters whose most significant bit is set, are printed using the form .CI M-^ x, where .I x is the character specified by the seven low order bits. All other non-printing characters are printed as .CI M- x, where .I x is the character specified by the seven low order bits. This option is influenced by the .C LC_CTYPE environment variable and its corresponding code set. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C cat will behave as if all internationalization variables are set to "C". See .IR environ (5). .PP .C LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .PP .C LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .C LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .C NLSPATH determines the location of message catalogues for the processing of .C LC_MESSAGES. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE Exit values are: .RS 3 .TP 8 .B \00 Successful completion. .PD 0 .TP .B >0 Error condition occurred. .RE .PD .SH EXAMPLES To create a zero-length file, use any of the following: .IP .CI cat " /dev/null " "> " file .br .CI cp " /dev/null file" .br .CI touch \0file .PP The following prints .C ^I for all the occurrences of tab character in .I file1 .IP .CI "cat -t " file1 .PP To suppress error messages about files that do not exist, use: .IP .CI "cat -s" " file1 file2 file3 " > \0file .PP If .I file2 does not exist, the above command concatenates .IR file1 " and " file3 without reporting the error on .I file2. The result is the same if .C -s option is not used, except that .C cat displays the error message. .PP To view non-printable characters in .I file2, use: .IP .CI "cat -v " file2 .PP .SH WARNINGS Command formats such as .IP .CI cat " file1 file2 " "> " file1 .PP overwrites the data in .I file1 before the concatenation begins, thus destroying the file. Therefore, be careful when using shell special characters. .SH SEE ALSO cp(1), more(1), pg(1), pr(1), rmnl(1), ssp(1). .SH STANDARDS CONFORMANCE .CR cat ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4cat\f1 \- concatenate, copy, and print files@@@\f3cat(1)\f1 .\" index@concatenate, copy, and print files@@@\f3cat(1)\f1 .\" index@copy, concatenate, and print files@@@\f3cat(1)\f1 .\" index@print, copy, and concatenate files@@@\f3cat(1)\f1 .\" index@file: create zero-length file@@@\f3cat(1)\f1 .\" index@create zero-length file@@@\f3cat(1)\f1 .\" index@zero-length file, create@@@\f3cat(1)\f1 .\" .\" toc@\f3cat(1)\f1:\0\0\f4cat\f1@@@concatenate, copy, and print files .\" .\" fileset_database@cat.1 USER-CMDS-MAN .\" $Header: cc_bundled.1,v 72.2 94/07/27 10:26:05 ssa Exp $ .TA c .TH cc_bundled 1 "Bundled C Compiler \- Limited Functionality" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cc \- bundled C compiler .SH SYNOPSIS .C cc .RI [ options ] .I files .SH DESCRIPTION This manual page describes the Bundled C compiler. See .IR cc (1), online only, for a description of the ANSI-compliant HP-UX manual page. .PP This .CR cc accepts several types of arguments as .IR files : .RS .TP .BR .c " Suffix" Arguments whose names end with .CR .c are understood to be C source files. Each is compiled and the resulting object file is left in a file having the corresponding base name, .CR .o instead of .CR .c . However, if a single C file is compiled and linked, all in one step, the .CR .o file is deleted. .TP .BR .s " Suffix" Arguments whose names end with .CR .s are understood to be assembly source files and are assembled, producing a .CR .o file for each .CR .s file. .TP .CR .i " Suffix" Arguments whose names end with .CR .i are assumed to be the output of .CR cpp (see the .CR -P option below). They are compiled without invoking .CR cpp (see .IR cpp (1)). Each object file is left in a file having the corresponding base name, but suffixed with .CR .o instead of .CR .i . .TP .CI -l x "\f1 Form" Arguments of the form .CI -l x cause the linker to search the library .CI lib x .sl or .CI lib x .a in an attempt to resolve currently unresolved external references. Because a library is searched when its name is encountered, placement of a .CR -l is significant. If a file contains an unresolved external reference, the library containing the definition must be placed .I after the file on the command line. See .IR ld (1) for further details. .TP .CI -l:lib x . "suffix \f1Form" Arguments of the form .CI -l:lib x . suffix cause the linker to search the library .CI lib x .sl or .CI lib x .a (depending on .IR suffix ) in an attempt to resolve currently unresolved external references. It is similar to the .CR -l option except the current state of the .CR -Wl,-a option is not important. .ifn .bp .TP Other Suffixes All other arguments, such as those whose names end with .CR .o or .CR .a , are taken to be relocatable object files that are to be included in the link operation. .RE .PP Arguments and options can be passed to the compiler through the .CR CCOPTS environment variable as well as on the command line. The compiler reads the value of .CR CCOPTS and divides these options into two sets; options that appear before a vertical bar .RC ( | ), and options that appear after the vertical bar. The first set of options are placed before any of the command-line parameters to .CR cc ; the second set of options are placed after the command-line parameters to .CR cc . If the vertical bar is not present, all options are placed before the command-line parameters. For example (in .IR sh (1) notation), .nf .IP .C CCOPTS="-v \(or -lmalloc" .C export CCOPTS .C cc -w prog.c .fi .PP is equivalent to .IP .C cc -v -w prog.c -lmalloc .PP When set, the .CR TMPDIR environment variable specifies a directory to be used by the compiler for temporary files, overriding the default directory .CR /var/tmp . .SS Options The following options are the only options which are recognized by the bundled C compiler. .RS .TP 15 .C -c Suppress the link edit phase of the compilation, and force an object .RC ( .o ) file to be produced for each .CR .c file, even if only one program is compiled. Object files produced from C programs must be linked before being executed. .TP .C -C Prevent the preprocessor from stripping C-style comments. See .IR cpp (1) for details. .TP .PD 0 .CI -D name=def Define .I name to the preprocessor, as if by '#define'. See .IR cpp (1) for details. .TP .CI -D name .PD .TP .C -E Run only .CR cpp on the named C or assembly files, and send the result to the standard output. .TP .CI -I dir Change the algorithm used by the preprocessor for finding include files to also search in directory .IR dir . See .IR cpp (1) for details. .TP .CI -l x Refer to the .BR DESCRIPTION section. .TP .CI -L " dir" Change the algorithm used by the linker to search for .CI lib x .sl or .CI lib x .a \f1. The .CR -L option causes .CR cc to search in .IR dir before searching in the default locations. See .IR ld (1) for details. .TP .CI -o outfile Name the output file from the linker .IR outfile . The default name is .CR a.out . .TP .C -P Run only .CR cpp on the named C files and leave the result on corresponding files suffixed .CR .i . The .CR -P option is also passed along to .CR cpp . .TP .CI +R num Allow only the first .I num .CR register variables to actually have the .CR register class. Use this option when the register allocator issues the message: .RS .IP .C out of general registers .RE .TP .C -s Cause the output of the linker to be stripped of symbol table information. See .IR strip (1) for more details. The use of this option prevents the use of a symbolic debugger on the resulting program. See .IR ld (1) for more details. .TP .C -S Compile the named C files, and leave the assembly language output on corresponding files suffixed .CR .s . .TP .CI -t x , name Substitute subprocess .I x with .I name where .I x is one or more of a set of identifiers indicating the subprocess(es). This option works in two modes: 1) if .I x is a single identifier, .I name represents the full path name of the new subprocess; 2) if .I x is a set of identifiers, .I name represents a prefix to which the standard suffixes are concatenated to construct the full path names of the new subprocesses. .IP The .I x can take one or more of the values: .PP .RS 18 .PD 0 .TP 5 .C p Preprocessor (standard suffix is .CR cpp ) .TP 5 .C c Compiler (standard suffix is .CR ccom ) .TP 5 .C a Assembler (standard suffix is .CR as ) .TP 5 .C l Linker (standard suffix is .CR ld ) .RE .PD .TP 15 .CI -U name Remove any initial definition of .I name in the preprocessor. See .IR cpp (1) for details. .TP .C -v Enable verbose mode, which produces a step-by-step description of the compilation process on the standard error. .TP .CR -V Cause each invoked subprocess to print its version information to stdout. .TP .C -w Suppress warning messages. .TP .CI -W x , arglist Pass the comma-separated argument(s) in .I arglist to subprocess .IR x . The .CR -W option specification allows additional, implementation-specific options to be recognized by the compiler driver. For example, .RS .IP .C -Wl,-a,archive .RE .IP causes the linker to link with archive libraries instead of with shared libraries. See .IR ld (1) for details. .IP The .I x can assume one of the following values: .PP .RS 18 .PD 0 .TP 5 .C p Preprocessor .TP 5 .C a Assembler .TP 5 .C l Linker .RE .PD .PP Any other options encountered generate a warning to standard error. .PP Other arguments are assumed to be C-compatible object programs, typically produced by an earlier .CR cc run, or perhaps libraries of C-compatible routines. These programs, together with the results of any compilations specified, are linked (in the order given) to produce an executable program with the name .CR a.out . .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LC_CTYPE is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of .CR C (see .IR lang (5)) is used. If any internationalization variable contains an invalid setting, .CR cc behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .SS International Code Set Support Single byte and multibyte character code sets are supported. .SH DIAGNOSTICS The diagnostics produced by C itself are intended to be self-explanatory. Occasionally, messages may be produced by the preprocessor, assembler, or the link editor. .PP If any errors occur before .CR cc is completed, a nonzero value is returned. Otherwise, zero is returned. .SH EXAMPLES The example below compiles the C file .CR prog.c to create a .CR prog.o file, then invokes the .CR ld link editor to link .CR prog.o and .CR procedure.o with all of the C startup routines in .CR /usr/ccs/lib/crt0.o and library routines from the C library .CR libc.sl or .CR libc.a . The resulting executable program is placed in file .CR prog : .IP .C "cc prog.c procedure.o -o prog" .SH WARNINGS Options not recognized by .CR cc are not passed on to the link editor. The option .CI "-Wl," arg can be used to pass any such option to the link editor. .PP By default, the return value from a C program is completely random. The only two guaranteed ways to return a specific value are to explicitly call .CR exit() (see .IR exit (2)) or leave the function .CR main() with a .CI return \0expression ; construct. .SH FILES .PD 0 .ifn .TP 33 .ift .TP 45 .C file.c Input file .TP .C file.o Object file .TP .C a.out Linked executable output file .TP .C /var/tmp/ctm* Temporary files used by the compiler .TP .C /usr/ccs/bin/as Assembler (see .IR as (1)) .TP .C /usr/ccs/bin/ld Link editor (see .IR ld (1)) .TP .C /usr/ccs/lib/crt0.o Runtime startup .TP .C /usr/lib/libc.a Standard C library (archive version), see .I HP-UX Reference Section (3) .TP .C /usr/lib/libc.sl Standard C library (shared version), see .I HP-UX Reference Section (3) .TP .C /usr/include Standard directory for .CR #include files .PD .SS Bundled C Compiler Files .PD 0 .ifn .TP 33 .ift .TP 45 .C /usr/ccs/bin/cc C driver .TP .C /usr/ccs/lbin/ccom C compiler .TP .C /usr/lib/nls/msg/$LANG/cc.cat C compiler message catalog .TP .C /usr/ccs/lbin/cpp C preprocessor .PD .SH SEE ALSO .SS System Tools .TP 18 as(1) Translate assembly code to machine code. .PD 0 .TP cpp(1) Invoke the C language preprocessor. .TP ld(1) Invoke the link editor. .TP cc(1) The ANSI-compliant C compiler on HP-UX. .PD .SS Miscellaneous .TP 18 matherr(3M) Trap math errors. .PD 0 .TP fpgetround(3M) Floating-point mode control functions. .TP strip(1) Strip symbol and line number information from an object file. .TP crt0(3) Execution startup routine. .TP end(3C) Symbol of the last locations in program. .TP exit(2) Termination of a process. .PD .SS Tutorials and Standards Documents B. W. Kernighan and D. M. Ritchie, .IR "The C Programming Language" , Prentice-Hall, 1978. .\" .\" toc@\f3cc_bundled(1)\f1:\0\0\f4cc_bundled\f1@@@bundled C compiler\f1 .\" .\" index@\f4cc_bundled\f1 \- bundled C compiler@@@\f3cc_bundled(1)\f1 .\" index@\f1bundled C compiler@@@\f3cc_bundled(1)\f1 .\" index@\f1compiler, bundled C@@@\f3cc_bundled(1)\f1 .\" $Header: compact.1,v 72.3 93/01/14 11:36:09 ssa Exp $ .TA c .TH compact 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compact, uncompact, ccat \- compact and uncompact files, and cat them .SH SYNOPSIS .C compact .RI [ \|name \0...] .br .C uncompact .RI [ \|name \0...] .br .C ccat .RI [ \|file \0...] .SH DESCRIPTION .C compact compresses the named files using an adaptive Huffman code. If no file names are given, standard input is compacted and sent to the standard output. .C compact operates as an on-line algorithm. Each time a byte is read, it is encoded immediately according to the current prefix code. This code is an optimal Huffman code for the set of frequencies seen so far. It is unnecessary to attach a decoding tree in front of the compressed file because the encoder and the decoder start in the same state and stay synchronized. Furthermore, .C compact and .C uncompact can operate as filters. In particular, .IP .RC ... " | compact | uncompact | " ... .PP operates as a (very slow) no-op. .PP When an argument .I file is given, it is compacted, the resulting file is placed in .IC file .C\f1, and .I file is unlinked. The first two bytes of the compacted file code the fact that the file is compacted. These bytes are used to prohibit recompaction. .PP The amount of compression to be expected depends on the type of file being compressed. Typical file size reduction (in percent) through compression are: Text, 38%; Pascal Source, 43%; C Source, 36%; and Binary, 19%. .PP .C uncompact restores the original file from a file compressed by .C compact. If no file names are specified, standard input is uncompacted and sent to the standard output. .PP .C ccat cats the original file from a file compressed by .C compact, without uncompressing the file. .SS "Access Control Lists (ACLs) On systems that implement access control lists, when a new file is created with the effective user and group .SM ID of the caller, the original file's .SM ACL is copied to the new file after being altered to reflect any change in ownership (see .IR acl (5)). .SH WARNINGS On short-filename systems, the last segment of the file name must contain 12 or fewer characters to allow space for the appended .CR .C . .SH DEPENDENCIES .SS \s-1NFS\s0 Access control list entries of networked files are summarized (as returned in .C st_mode by .CR stat() ), but not copied to the new file (see .IR stat (2)). .SH FILES .TP 20 .C *.C compacted file created by compact, removed by uncompact .SH SEE ALSO compress(1), pack(1), acl(5). .br Gallager, Robert G., ``Variations on a Theme of Huffman,'' .I "I.E.E.E. Transactions on Information Theory," vol. IT-24, no. 6, November 1978, pp. 668 - 674. .SH AUTHOR .C compact was developed by Colin L. Mc Master. .\" .\" index@\f4compact\f1 \- compact files using Huffman code (see \f4pack\f1(1))@@@\f3compact(1)\f1 .\" index@\f4ccat\f1 \- uncompact and cat files using Huffman code (see \f4pack\f1(1))@@@\f3compact(1)\f1 .\" index@\f4uncompact\f1 \- uncompact Huffman coded files (see \f4pack\f1(1))@@@\f3compact(1)\f1 .\" index@compact files using Huffman code (see \f4pack(1)\f1)@@@\f3compact(1)\f1 .\" index@cat after uncompacting Huffman coded files (see \f4pack(1)\f1)@@@\f3compact(1)\f1 .\" index@uncompact previously compacted Huffman coded files (see \f4pack(1)\f1)@@@\f3compact(1)\f1 .\" .\" toc@\f3compact(1)\f1:\0\0\f4compact\f1, \f4uncompact\f1, \f4ccat\f1@@@compact and uncompact files, and cat them .\" toc@\f4uncompact\f1: uncompact files@@@see \f3compact(1)\f1 .\" toc@\f4ccat\f1: cat compacted files@@@see \f3compact(1)\f1 .\" .\" links@compact.1 uncompact.1 .\" links@compact.1 ccat.1 .\" .\" fileset_database@compact.1 USER-CMDS-MAN .\" $Header: cd.1,v 76.1 95/08/01 16:05:45 ssa Exp $ .TA c .TH cd 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cd \- change working directory .SH SYNOPSIS .C cd .RI [ \|directory\| ] .SH DESCRIPTION If .I directory is not specified, the value of shell parameter .C HOME is used as the new working directory. If .I directory specifies a complete path starting with .CR / , .CR . , .CR .\|. , .I directory becomes the new working directory. If neither case applies, .C cd tries to find the designated directory relative to one of the paths specified by the .C CDPATH shell variable. .C CDPATH has the same syntax as, and similar semantics to, the .C PATH shell variable. .C cd must have execute (search) permission in .IR directory . .PP .C cd exists only as a shell built-in command because a new process is created whenever a command is executed, making .C cd useless if written and processed as a normal system command. Moreover, different shells provide different implementations of .C cd as a built-in utility. Features of .C cd as described here may not be supported by all the shells. Refer to individual shell manual entries for differences. .PP If .C cd is called in a subshell or a separate utility execution environment such as: .IP find . -type d -exec cd {}; -exec foo {}; .IP (which invokes .C foo on accessible directories) .PP .C cd does not affect the current directory of the caller's environment. Another usage of .C cd as a stand-alone command is to obtain the exit status of the command. .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES Change the current working directory to the .C HOME directory from any location in the file system: .IP .C cd .PP Change to new current working directory .C foo residing in the current directory: .IP .C cd foo .PD 0 .PP or .IP .C cd ./foo .PD .PP Change to directory .C foobar residing in the current directory's parent directory: .IP .C cd ../foobar .PP Change to the directory whose absolute pathname is .CR /usr/local/lib/work.files : .IP .C cd /usr/local/lib/work.files .PP Change to the directory .CR proj1/schedule/staffing/proposals relative to home directory: .IP .C cd $HOME/proj1/schedule/staffing/proposals .SH VARIABLES The following environment variables affect the execution of cd: .TP 20 .C HOME The name of the home directory, used when no directory operand is specified. .PD 1 .TP .C CDPATH A colon-separated list of pathnames that refer to directories. If the directory operand does not begin with a slash .RC ( / ) character, and the first component is not dot or dot-dot, .C cd searches for .I directory relative to each directory named in the .C CDPATH variable, in the order listed. The new working directory is set to the first matching directory found. An empty string in place of a directory pathname represents the current directory. If .C CDPATH is not set, it is treated as if it was an empty string. .SH RETURN VALUE Upon completion, .C cd exits with one of the following values: .TP 20 .B \00 The directory was successfully changed. .PD 0 .TP .B >0 An error occurred. The working directory remains unchanged. .PD .SH SEE ALSO csh(1), pwd(1), ksh(1), sh-posix(1), sh(1), chdir(2). .SH STANDARDS CONFORMANCE .CR cd ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4cd\f1 \- change working directory@@@\f3cd(1)\f1 .\" index@change working directory@@@\f3cd(1)\f1 .\" index@directory, change working@@@\f3cd(1)\f1 .\" index@working directory, change@@@\f3cd(1)\f1 .\" .\" toc@\f3cd(1)\f1:\0\0\f4cd\f1@@@change working directory .\" .\" fileset_database@cd.1 USER-CMDS-MAN .\" $Header: cdc.1,v 72.5 94/04/27 11:31:10 ssa Exp $ .TA c .TH cdc 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cdc \- change the delta commentary of an \s-1SCCS\s+1 delta .SH SYNOPSIS .C cdc -r .SM .I SID .RC [ -m\c .RI [ \|mrlist\| ]\|] .RC [ -y\c .RI [ \|comment\| ]\|] .I files .SH DESCRIPTION The .CR cdc command changes the .BR "delta commentary" , for the .SM .I SID specified by the .CR -r option, of each named .SM SCCS file. .PP .I "Delta commentary" is defined to be the Modification Request .SM (MR) and comment information normally specified via the .IR delta (1) command .RC ( -m and .CR -y options). .PP If a directory is named, .CR cdc behaves as if each file in the directory were specified as a named file, except that non-\s-1SCCS\s+1 files (last component of the path name does not begin with .CR s. ) and unreadable files are silently ignored. If a name of .CR - is given, the standard input is read (see .SM WARNINGS\s0); each line of the standard input is taken to be the name of an .SM SCCS file to be processed. .SS Options Arguments to .CR cdc , which can appear in any order, consist of .I option arguments and file names. .PP All of the described .I option arguments apply independently to each named file: .RS .TP 15 .CI -r \s-1SID\s+1 Used to specify the .IR S \s-1CCS\s+1 .IR ID entification .SM (SID) string of a delta for which the delta commentary is to be changed. .TP .CR -m [\f2mrlist\fP] If the .SM SCCS file has the .CR v option set (see .IR admin (1)), a list of .SM MR numbers to be added and/or deleted in the delta commentary of the .SM .I SID specified by the .CR -r option .I may be supplied. A null .SM MR list has no effect. .IP .SM MR entries are added to the list of .SM MR\c s in the same manner as that of .IR delta (1). To delete an .SM MR, precede the .SM MR number with the character .CR ! (see .SM EXAMPLES\s0). If the .SM MR to be deleted is currently in the list of .SM MR\c s, it is removed and changed into a ``comment'' line. A list of all deleted .SM MR\c s is placed in the comment section of the delta commentary and preceded by a comment line stating that they were deleted. .IP If .CR -m is not used and the standard input is a terminal, the prompt .CR MRs? is issued on the standard output before the standard input is read; if the standard input is not a terminal, no prompt is issued. The .CR MRs? prompt always precedes the .CR comments? prompt (see .CR -y option). .IP .SM MR\c s in a list are separated by blanks and/or tab characters. An unescaped new-line character terminates the .SM MR\c s list. .IP Note that if the .CR v option has a value (see .IR admin (1)), it is treated as the name of a program (or shell procedure) that validates the correctness of the .SM MR numbers. If a non-zero exit status is returned from the .SM MR number validation program, .CR cdc terminates and the delta commentary remains unchanged. .TP .CR -y [\f2comment\fP] Arbitrary text used to replace the .I comment or .IR comment s already existing for the delta specified by the .CR -r option. Previous comments are kept and preceded by a comment line stating that they were changed. A null .I comment has no effect. .IP If .CR -y is not specified and the standard input is a terminal, the prompt .CR comments? is issued on the standard output before standard input is read; if standard input is not a terminal, no prompt is issued. An unescaped new-line character terminates the .I comment text. .RE .PP The exact permissions necessary to modify the .SM SCCS file are documented in .IR get (1). Simply stated, they are either: .RS .TP 3 \(bu If you made the delta, you can change its delta commentary, or .TP \(bu If you own the file and directory, you can modify the delta commentary. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS Use .IR sccshelp (1) for explanations. .SH EXAMPLES Add .CR bl78-12345 and .CR bl79-00001 to the .SM MR list, remove .CR bl77-54321 from the .SM MR list, and add the comment .CR trouble to delta 1.6 of .CR s.file : .tr ~" .IP .C "cdc -r1.6 -m~bl78-12345 !bl77-54321 bl79-00001~ -ytrouble s.file" .tr ~~ .PP The following does the same thing: .IP .C "cdc -r1.6 s.file" .br .C "MRs? !bl77-54321 bl78-12345 bl79-00001" .br .C "comments? trouble" .SH WARNINGS If .SM SCCS file names are supplied to the .CR cdc command via the standard input .RC ( - on the command line), the .CR -m and .CR -y options must also be used. .SH FILES .PD 0 .TP 10 .I x-file See .IR delta (1). .TP .I z-file See .IR delta (1). .PD .SH SEE ALSO admin(1), delta(1), get(1), sccshelp(1), prs(1), sccsfile(4). .\" .\" index@\f4cdc\f1 \- change the delta commentary of an \s-1SCCS\s+1 delta@@@\f3cdc(1)\f1 .\" index@change delta commentary of an \s-1SCCS\s+1 delta@@@\f3cdc(1)\f1 .\" index@delta commentary of an \s-1SCCS\s+1 delta, change@@@\f3cdc(1)\f1 .\" index@commentary of an \s-1SCCS\s+1 delta, change delta@@@\f3cdc(1)\f1 .\" index@\s-1SCCS\s+1 delta, change delta commentary of@@@\f3cdc(1)\f1 .\" .\" toc@\f3cdc(1)\f1:\0\0\f4cdc\f1@@@change the delta commentary of an \s-1SCCS\s+1 delta rcsfile(4), acl(5), rcsintro(5). .\" index@\f4co\f1 \- check out \s-1RCS\s+1 revisions@@@\f3co(1)\f1 .\" index@check out \s-1RCS\s+1 revisions@@@\f3co(1)\f1 .\" index@\s-1RCS\s+1: check out \s-1RCS\s+1 revisions@@@\f3co(1)\f1 .\" index@revisions, \s-1RCS\s+1, check out@@@\f3co(1)\f1 .\" .\" toc@\f3co(1)\f1:\0\0\f4co\f1@@@check out \s-1RCS\s+1 revisions .\" .\" fileset_database@cdc.1 USER-CMDS-MAN .\" $Header: chacl.1,v 78.2 96/04/09 12:32:55 ssa Exp $ .TA c .TH chacl 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chacl \- add, modify, delete, copy, or summarize access control lists (ACLs) of files .SH SYNOPSIS .C /usr/bin/chacl .IR "acl file " ... .br .C chacl -r .IR "acl file " ... .br .C chacl -d .IR "aclpatt file " ... .br .C chacl .C -f .I "fromfile tofile " ... .br .C chacl .CR -\| [ \|z\| \(or\c .CR \|Z\| \(or \|F\| ] .I file ... .SH DESCRIPTION .C chacl extends the capabilities of .IR chmod (1), by enabling the user to grant or restrict file access to additional specific users and/or groups. Traditional file access permissions, set when a file is created, grant or restrict access to the file's owner, group, and other users. These file access permissions (eg., .CR rwxrw-r-- ) are mapped into three base access control list entries: one entry for the file's owner .RI ( u\c .CR .%, .IR mode ), one for the file's group .RC ( %.\c .IR g , .IR mode ), and one for other users .RC ( %.%, .IR mode ). .PP .C chacl enables a user to designate up to thirteen additional sets of permissions (called optional access control list (\s-1ACL\s+1) entries) which are stored in the access control list of the file. .PP To use .IR chacl , the owner (or superuser) constructs an .IR acl , a set of .I "(user.group, mode)" mappings to associate with one or more files. A specific user and group can be referred to by either name or number; any user .RI ( u ), group .RI ( g ), or both can be referred to with a .CR % symbol, representing .IR any user or group. The \f3@\fP symbol specifies the file's owner or group. .PP Read, write, and execute/search .RC ( rwx ) .I modes are identical to those used by .IR chmod ; symbolic operators .RI ( op ) add .RC ( + ), remove .RC ( - ), or set .RC ( = ) access rights. The entire .I acl should be quoted if it contains whitespace or special characters. Although two variants for constructing the .I acl are available (and fully explained in .IR acl (5)), the following syntax is suggested: .IP .IR entry\| [, \0entry\| ]\0... .PP where the syntax for an .IR entry is .IP .IR "u.g op mode" [ "\|op mode\|" ]\0... .PP By default, .C chacl modifies existing .SM ACL\c s. It adds .SM ACL entries or modifies access rights in existing .SM ACL entries. If .I acl contains an .SM ACL entry already associated with a file, the entry's mode bits are changed to the new value given, or are modified by the specified operators. If the file's .SM ACL does not already contain the specified entry, that .SM ACL entry is added. .C chacl can also remove all access to files. Giving it a null .I acl argument means either ``no access'' (when using the .C -r option) or ``no changes.'' .PP For a summary of the syntax, run .C chacl without arguments. .PP If .I file is specified as .CR - , .CR chacl reads from standard input. .SS Options .C chacl recognizes the following options: .TP 15 .C -r Replace old .SM ACL\c s with the given .SM ACL. All optional .SM ACL entries are first deleted from the specified files's .SM ACL\c s, their base permissions are set to zero, and the new .SM ACL is applied. If .I acl does not contain an entry for the owner .RI ( u\c .CR .% ), the group .RC ( %.\c .IR g ), or other .RC ( %.% ) users of a file, that base .SM ACL entry's mode is set to zero (no access). The command affects all of the file's .SM ACL entries, but does not change the file's owner or group .SM ID. .IP In .IR chmod (1), the ``modify'' and ``replace'' operations are distinguished by the syntax (string or octal value). There is no corollary for .SM ACLs because they have a variable number of entries. Hence .C chacl modifies specific entries by default, and optionally replaces all entries. .TP .C -d Delete the specified entries from the .SM ACLs on all specified files. The .I aclpatt argument can be an exact .SM ACL or an .SM ACL pattern (see .IR acl (5)). .C "chacl -d" updates each file's .SM ACL only if entries are deleted from it. .IP If you attempt to delete a base .SM ACL entry from any file, the entry remains but its access mode is set to zero (no access). If you attempt to delete a non-existent .SM ACL entry from a file (that is, if an .SM ACL entry pattern matches no .SM ACL entry), .C chacl informs you of the error, continues, and eventually returns non-zero. .TP .CI -f\0 "fromfile tofile" Copy the .SM ACL from .I fromfile to the specified .IR tofile , transferring ownership, if necessary (see .IR acl (5), .IR chown (2), or .IR chownacl (3C)). .I fromfile can be .C - to represent standard input. .IP This option implies the .C -r option. If the owner and group of .I fromfile are identical to those of .IR tofile , .C chacl -f is identical to: .RS .IP .CR "chacl -r `lsacl fromfile` tofile " ... .RE .IP To copy an .SM ACL without transferring ownership, the above command is suggested instead of .CR "chacl -f" . .TP .C -z Delete (``zap'') all optional entries in the specified file's .SM ACL\c s, leaving only base entries. .TP .C -Z Delete (``zap'') all optional entries in the specified file's .SM ACL\c s, and set the access modes in all base entries to zero (no access). This is identical to replacing the old .SM ACL with a null .SM ACL: .RS .IP .CR "chacl -r '' file " ... .RE .IP or using .IR chmod (1), which deletes optional entries as a side effect: .RS .IP .CI "chmod 0 " file\0... .RE .TP .C -F Incorporate (``fold'') optional .SM ACL entries into base .SM ACL entries. The base .SM ACL entry's permission bits are altered, if necessary, to reflect the caller's effective access rights to the file; all optional entries, if any, are deleted. .IP For ordinary users, only the access mode of the owner base .SM ACL entry can be altered. Unlike .CR getaccess , the write bit is not turned off for a file on a read-only file system or a shared-text program being executed (see .IR getaccess (1)). .IP For super-users, only the execute mode bit in the owner base .SM ACL entry might be changed, only if the file is not an regular file or if an execute bit is not already set in a base .SM ACL entry mode, but is set in an optional .SM ACL entry mode. .PP .I acl also can be obtained from a string in a file: .IP .CI "chacl `cat file` " files\0... .PP Using \f3@\fP in .I acl to represent ``file owner or group'' can cause .C chacl to run more slowly because it must reparse the .SM ACL for each file (except with the .C -d option). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the language in which messages are displayed. .PP If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C chacl behaves as if all internationalization variables are set to "C". See .IR environ (5). .SH RETURN VALUE If .C chacl succeeds, it returns a value of zero. .PP If .C chacl encounters an error before it changes any file's .SM ACL, it prints an error message to standard error and returns 1. Such errors include invalid invocation, invalid syntax of .I acl .RI ( aclpatt ), a given user name or group name is unknown, or inability to get an .SM ACL from .I fromfile with the .C -f option. .PP If .C chacl cannot execute the requested operation, it prints an error message to standard error, continues, and later returns 2. This includes cases when a file does not exist, a file's .SM ACL cannot be altered, more .SM ACL entries would result than are allowed, or an attempt is made to delete a non-existing .SM ACL entry. .SH EXAMPLES The following command adds read access for user .C jpc in any group, and removes write access for any user in the files's groups, for files .C x and .CR y . .IP .ift \f4\s+1chacl "jpc.%+r, %.@-w" x y\fP\s0 .ifn \f3chacl "jpc.%+r, %.@-w" x y\fP .PP This command replaces the .SM ACL on the file open as standard input and on file .C test with one which only allows the file owner read and write access. .IP .ift \f4\s+1chacl -r '(@.%,rw-)' - test\fP\s0 .ifn \f3chacl -r '(@.%,rw-)' - test\fP .PP Delete from file .C myfile the specific access rights, if any, for user 165 in group 13. Note that this is different from adding an .SM ACL entry that restricts access for that user and group. The user's resulting access rights depend on the entries remaining in the .SM ACL. The command also deletes all entries for user .C jpc that have a read bit turned on (the asterisk can be used as a wildcard in the ACL pattern for user, group, or access mode): .IP .C "chacl -d '165.13, jpc.*+r' myfile" .PP Copy the .SM ACL from .C oldfile to .C slow/hare and .CR fast/tortoise . .IP .C "chacl -f oldfile slow/hare fast/tortoise" .PP Delete the optional .SM ACL entries, if any, on the file open as standard input. .IP .C "chacl -z -" .PP Deny all access to all files in the current directory whose names start with .CR a , .CR b , or .CR c : .IP .C "chacl -Z [a-c]*" .PP Incorporate the optional .SM ACL entries of a file .RC ( fun.stuff ) into the base ACL entries: .IP .C "chacl -F fun.stuff" .SH WARNINGS An .SM ACL string cannot contain more than 16 unique entries, even though converting \f3@\fP symbols to user or group names and combining redundant entries might result in fewer than 16 entries for some files. .SH DEPENDENCIES .C chacl will fail when the target file resides on a file system which does not support ACLs. .SS \s-1NFS\s0 Only the .C -F option is supported on remote files. .SH AUTHOR .C chacl was developed by HP. .SH SEE ALSO chmod(1), getaccess(1), lsacl(1), getacl(2), setacl(2), acl(5), glossary(9). .\" .\" index@\f4chacl\f1 \- add, modify, delete, copy, or summarize file access control lists (\s-1ACL\s+1s)@@@\f3chacl(1)\f1 .\" index@add, modify, delete, copy, or summarize file access control lists (\s-1ACL\s+1s)@@@\f3chacl(1)\f1 .\" index@modify, delete, copy, add, or summarize file access control lists (\s-1ACL\s+1s)@@@\f3chacl(1)\f1 .\" index@delete, copy, add, modify, or summarize file access control lists (\s-1ACL\s+1s)@@@\f3chacl(1)\f1 .\" index@copy, add, modify, delete, or summarize file access control lists (\s-1ACL\s+1s)@@@\f3chacl(1)\f1 .\" index@summarize, add, modify, delete, or copy file access control lists (\s-1ACL\s+1s)@@@\f3chacl(1)\f1 .\" index@access control lists; add, modify, delete, copy, or summarize@@@\f3chacl(1)\f1 .\" .\" toc@\f3chacl(1)\f1:\0\0\f4chacl\f1@@@add, modify, delete, copy, or summarize access control lists (ACLs) of files .\" .\" fileset_database@chacl.1 USER-CMDS-MAN .\" $Header: chatr.1,v 72.3 93/01/14 11:29:17 ssa Exp $ .TA c .TH chatr 1 .SH NAME chatr \- change program's internal attributes .SH SYNOPSIS .C chatr .RC [ -l .IR library\| ] .RC [ -n ] .RC [ -q ] .RC [ -M ] .RC [ -N ] .RC [ -s ] .RC [ -B .IR bind\| ] .RC [ +b .IR flag\| ] .RC [ +l .IR library\| ] .RC [ +pd .IR size\| ] .RC [ +pi .IR size\| ] .RC [ +k .IR flag\| ] .RC [ +r .IR flag\| ] .RC [ +s .IR flag\| ] .IR file \0... .SH DESCRIPTION .CR chatr , by default, prints each .IR file 's magic number and file attributes to the standard output. .SS Options .C chatr recognizes the following options: .RS .TP 15 .CI -l \0library Indicate that the specified shared library is subject to run-time path lookup if directory path lists are provided (see .C +s and .CR +b ). .TP .C -n Change .I file from demand loaded to shared .TP .C -q Change .I file from shared to demand loaded .TP .C -M Change .I file from EXEC_MAGIC to SHMEM_MAGIC. (This option is an interim solution until 64-bit addressability is available with a true 64-bit kernel.) .TP .C -N Change .I file from SHMEM_MAGIC to EXEC_MAGIC. (This option is an interim solution until 64-bit addressability is available with a true 64-bit kernel.) .TP .C -s Perform its operation silently. .TP .CI -B \0bind Select run-time binding behavior of a program using shared libraries. One of the major binding modes .C immediate or .C deferred must be specified. One or more of the binding modifiers .CR nonfatal , .CR verbose , or .C restricted can also be specified, each with a separate option. See the .I Programming on .SM .I HP-UX manual for a description of binding modes. .TP .CI +b \0flag Control whether the directory path list stored when the program was built can be used to locate shared libraries needed by the program. The two flag values, .C enable and .CR disable , respectively enable and disable use of the path list. See the .C +s option. .TP .CI +l \0library Indicate that the specified shared library is not subject to run-time path lookup if directory path lists are provided (see .C +s and .CR +b ). .TP .CI +pd \0size Request a particular virtual memory page size that should be used for data. Sizes of .C 4K, .C 16K, .C 64K, .C 256K, .C 1M, .C 4M, .C 16M, .C 64M, .C 256M, and .C L are supported. A size of .C L will result in using the largest page size available. The actual page size may vary if the requested size cannot be fulfilled. .TP .CI +pi \0size Request a particular virtual memory page size that should be used for instructions. See the .C +pd option for additional information. .TP .CI +k \0flag Request kernel assisted branch prediction. The flags .C enable and .C disable turn this request on and off, respectively. .TP .CI +r \0flag Request static branch prediction when executing this program. The flags .C enable and .C disable turn this request on and off, respectively. .TP .CI +s \0flag Control whether the directory path list specified with the .C SHLIB_PATH environment variable can be used to locate shared libraries needed by the program. The two flag values, .C enable and .CR disable, respectively enable and disable use of the environment variable. If both .C +s and .C +b are used, their relative order on the command line indicates which path list will be searched first. See the .C +b option. .RE .PP The term .B shared applies to the magic number .C SHARE_MAGIC while the term .B demand-loaded applies to the magic number .CR DEMAND_MAGIC . See .IR magic (4) and the .I "HP-UX Linker and Libraries Online User Guide" for more information. .PP Upon completion, .C chatr prints the file's old and new values to standard output unless .C -s is specified. .PP The .C +pd and .C +pi options only provide a hint for the virtual memory page size. The actual page sizes may vary. Under certain conditions, page size hints of .C L may result in better preformance, depending on the specific memory requirements of the application. .PP The performance of some applications may benefit from static branch prediction, others may not. The .C +r option provides a hint for using or avoiding this feature. .SH RETURN VALUE .C chatr returns zero on success. If the command line contents is syntactically incorrect, or one or more of the specified files cannot be acted upon, .C chatr returns the number of files whose attributes could not be modified. If no files are specified, .C chatr returns decimal 255. .SH EXTERNAL INFLUENCES .SS Environment Variables .PP The following internationalization variables affect the execution of .CR chatr : .PP .C LANG .RS Determines the locale category for native language, local customs and coded character set in the absence of .C LC_ALL and other .C LC_* environment variables. If .C LANG is not specified or is set to the empty string, a default of .C C (see .IR lang (5)) is used instead of .CR LANG . .RE .PP .C LC_ALL .RS Determines the values for all locale categories and has precedence over .C LANG and other .C LC_* environment variables. .RE .PP .C LC_CTYPE .RS Determines the locale category for character handling functions. .RE .PP .C LC_MESSAGES .RS Determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error. .RE .PP .C LC_NUMERIC .RS Determines the locale category for numeric formatting. .RE .PP .C NLSPATH .RS Determines the location of message catalogues for the processing of .CR LC_MESSAGES . .RE .PP If any internationalization variable contains an invalid setting, .C chatr behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .PP In addition, the following environment variable affects .CR chatr : .PP .C TMPDIR .RS Specifies a directory for temporary files (see .IR tmpnam (3S)). .RE .SH EXAMPLES Change .C a.out to demand-loaded .IP .C "chatr -q a.out" .PP Change binding mode of program file that uses shared libraries to immediate and nonfatal. Also enable usage of .C SHLIB_PATH environment variable: .IP .C "chatr -B immediate -B nonfatal +s enable a.out" .PP Disallow run-time path lookup for the shared library .C /usr/lib/libc.sl that the shared library .C libfoo.sl depends on: .IP .C "chatr +l /usr/lib/libc.sl libfoo.sl" .SH NOTES .C SHMEM_MAGIC is an interim solution until 64-bit addressability is available with a true 64-bit kernel. .PP .C SHMEM_MAGIC will not be supported on future HP implementations of 64-bit architectures (beyond PA2.0). Programs that need larger than 1.75 GB of shared memory on those architectures will have to be recompiled (as 64-bit executables) for those architectures. .PP Programs that are compiled as 64-bit executables on any 64-bit HP implementation (including PA 2.0) cannot be marked as SHMEM_MAGIC nor do they need to be as they will already have access to more than 1.75 GB of shared memory. .PP The additional 1 GB of shared memory that is available over other types of executables can be availed of only for system V shared memory and not other forms of shared memory (like memory mapped files). .SH AUTHOR .C chatr was developed by HP. .SH SEE ALSO .PD .SS System Tools: .TP 18 .IR ld(1) invoke the link editor .PD 0 .TP .IR cachectl(3C) flush and/or purge the cache .PD .SS Miscellaneous: .TP 18 .IR a.out(4) assembler, compiler, and linker output .PD 0 .TP .IR magic(4) magic number for HP-UX implementations .PD .SS Texts and Tutorials: .TP 18 .IR "How HP-UX Works: Concepts for the System Administrator" . .TP .IR "Programming on HP-UX" .\" .\" index@\f4chatr\f1 \- change program's internal attributes@@@\f3chatr(1)\f1 .\" index@attributes, change program's internal@@@\f3chatr(1)\f1 .\" index@change program's internal attributes@@@\f3chatr(1)\f1 .\" index@program's internal attributes, change@@@\f3chatr(1)\f1 .\" index@internal attributes, change program's@@@\f3chatr(1)\f1 .\" .\" toc@\f3chatr(1)\f1:\0\0\f4chatr\f1@@@change program's internal attributes .\" .\" fileset_database@chatr.1 USER-CMDS-MAN .\" $Header: checknr.1,v 72.3 93/01/14 11:30:43 ssa Exp $ .TA c .TH checknr 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME checknr \- check nroff/troff files .SH SYNOPSIS .C checknr .RC [ -s ] .RC [ -f ] .RC [ -a\c .CI . x1 . y1\c .CI . x2 . y2 \&... .CI . xn . yn\|\f1] .RC [ -c\c\c .CI . x1 . x2 . x3\c \|...c .CI . xn\|\f1] .RI [ \|file \0...\|] .SH DESCRIPTION .C checknr searches a list of .C nroff or .C troff input files for certain kinds of errors involving mismatched opening and closing delimiters and unknown commands. If no files are specified, .C checknr searches the standard input. .C checknr looks for the following: .RS .TP 3 \(bu Font changes using .CR \efx \0... \0\efP . .TP \(bu Size changes using .CR \esx \0... \0\es0 . .TP \(bu Macros that come in .IR open \0...\0 close forms, such as the .C .TS and .C .TE macros, which must appear in matched pairs. .RE .PP .C checknr knows about the .CR ms and .CR me macro packages. .SS Options .C checknr recognizes the following options: .RS .TP 6 .C -a Define additional macro pairs in the list. .C -a is followed by groups of six characters, each group defining a pair of macros. Each six characters consist of a period, the first macro name, another period, and the second macro name. For example, to define the pairs .C .BS and .CR .ES , and .C .XS and .CR .XE , use: .RS .IP .C -a.BS.ES.XS.XE .RE .IP No spaces are allowed between the option and its arguments. .TP .C -c Define commands that .C checknr would otherwise interpret as undefined. .TP .C -f Ignore .CI \ef x font changes. .TP .C -s Ignore .CI \es x size changes. .RE .SH EXTERNAL INFLUENCES .SS International Code Set Support Single-byte character code sets are supported. .SH DIAGNOSTICS .C checknr complains about unmatched delimiters, unrecognized commands, and bad command syntax. .SH EXAMPLES Check file .C sorting for errors that involve mismatched opening and closing delimiters and unknown commands, but disregard errors caused by font changes: .IP .C checknr -f sorting .SH WARNINGS .C checknr is designed for use on documents prepared with the intent of using .CR checknr , much the same as .C lint is used. It expects a certain document writing style for .CR \ef ... and .CR \es ... commands, in which each .CI \ef x is terminated with .C \efP and each .CI \es x is terminated with .CR \es0 . Although text files format properly when the next font or point size is coded directly instead of using .C \efP or .CR \es0 , such techniques produce complaints from .IR checknr . If files are to be examined by .IR checknr , the .C \efP and .C \es0 delimiting conventions should be used. .PP .C -a cannot be used to define single-character macro names. .PP .C checknr does not recognize certain reasonable constructs such as conditionals. .SH AUTHOR .C checknr was developed by the University of California, Berkeley. .SH SEE ALSO checkeq(1), lint(1), nroff(1). .\" .\" index@\f4checknr\f1 \- check nroff/troff files@@@\f3checknr(1)\f1 .\" index@check nroff/troff files@@@\f3checknr(1)\f1 .\" index@files: check nroff/troff files@@@\f3checknr(1)\f1 .\" index@nroff/troff files, check@@@\f3checknr(1)\f1 .\" index@troff/nroff files, check@@@\f3checknr(1)\f1 .\" .\" toc@\f3checknr(1)\f1:\0\0\f4checknr\f1@@@check nroff/troff files .\" .\" fileset_database@checknr.1 USER-CMDS-MAN .\" $Header: chfn.1,v 72.4 94/09/08 16:41:16 ssa Exp $ .TA c .TH chfn 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chfn \- change user information in password file; used by .CR finger .SH SYNOPSIS .CR chfn .RI [ login-name ] .SH DESCRIPTION The .CR chfn command changes the user information that is stored in the .CR /etc/passwd password file (see .IR passwd (4)) for the current logged-in user or for the user specified by .IR login-name . .PP The information is organized as four comma-separated subfields within the reserved (5th) field of the password file entry. It consists of the user's full name, location code, office phone number, and home phone number, in that order. This information is used by the .CR finger command and other programs (see .IR finger (1)). .PP .CR chfn prompts you for each subfield. The prompt includes a default value, which is enclosed in brackets. Accept the default value by pressing the Return key. To enter a blank subfield, type the word .CR none . .PP Run .CR finger after running .CR chfn to make sure the information was processed correctly. .SS Subfield Values .RS .TP 20 .CR Name Up to 1022 printing characters. .IP The .CR finger command and other utilities expand an .CR & found anywhere in this subfield by substituting the login name for it and shifting the first letter of the login name to uppercase. .RC ( chfn does not alter the input .CR & .) .TP .CR Location Up to 1022 printing characters. .TP .CR "Office Phone" Up to 25 printing characters. .IP .CR finger inserts appropriate hyphens if the value is all digits. .TP .CR "Home Phone" Up to 25 printing characters. .IP .CR finger inserts appropriate hyphens if the value is all digits. .RE .PP You must have appropriate privileges to use the optional .IR login-name argument to change another user's information. .SH EXAMPLES The following is a sample run. The user's input is shown in regular type. .nf .IP .CR "Name [Tracy Simmons]: \&" .CR "Location (Ex: 47U-P5) []: \&" 42L-P1 .CR "Office Phone (Ex: 1632) [77777]: \&" 71863 .CR "Home Phone (Ex: 9875432) [4085551546]: \&" none .fi .SH WARNINGS The encoding of office and extension information is installation-dependent. .PP For historical reasons, the user's name, etc., are stored in the .CR /etc/passwd file. This is an inappropriate place to store the information. .PP Because two users may try to write the .CR passwd file at once, a synchronization method was developed. On rare occasions, .CR chfn prints a message that the password file is busy. When this occurs, .CR chfn sleeps for a short time, then tries to write to the .CR passwd file again. .SH DEPENDENCIES .SS HP-UX Integrated Login Library .CR chfn can use the HP-UX Integrated Login Library, if it is configured. For further details, see .IR auth (5) and .IR auth.adm (1m). .PP The HP-UX Integrated Login typically uses the Distributed Computing Environment (DCE) for its user registry. The DCE user registry and its relationship to the HP-UX Integrated Login are described in .IR auth.dce (5). .SH AUTHOR .CR chfn was developed by the University of California, Berkeley. .SH FILES .CR /etc/passwd .br .CR /etc/ptmp .SH SEE ALSO chsh(1), finger(1), passwd(1), passwd(4). .PP HP-UX Integrated Login Library: auth.adm(1m), auth(5), auth.dce(5). .\" .\" toc@\f3chfn(1)\f1:\0\0\f4chfn\f1@@@change user information in password file; used by \f4finger\f1 .\" .\" index@\f4chfn\f1 \- change user information in password file; used by \f4finger\f1@@@\f3chfn(1)\f1 .\" index@change user information in password file; used by \f4finger\f1@@@\f3chfn(1)\f1 .\" index@user information in password file; used by \f4finger\f1, change@@@\f3chfn(1)\f1 .\" index@information in password file; used by \f4finger\f1, change@@@\f3chfn(1)\f1 .\" index@password file, information used by \f4finger\f1, change@@@\f3chfn(1)\f1 .\" index@\f4finger\f1, change information in password file@@@\f3chfn(1)\f1 .\" $Header: chown.1,v 76.3 95/08/01 16:09:14 ssa Exp $ .TA c .TH chown 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chown, chgrp \- change file owner or group .SH SYNOPSIS .CR chown .RC [ \-h ] .RC [ \-R ] .I owner\c .RC [ :\c .IR group ] .IR file \ ... .PP .CR chgrp .RC [ \-h ] .RC [ \-R ] .I group .IR file \ ... .SH DESCRIPTION The .CR chown command changes the owner ID of each specified .I file to .I owner and optionally the group ID of each specified .IR file to .IR group . .PP The .CR chgrp command changes the group ID of each specified .IR file to .IR group . .PP .I owner can be either a decimal user ID or a login name found in the .CR /etc/passwd file. .PP .I group can be either a decimal group ID or a group name found in the .CR /etc/group file. .PP In order to change the owner or group, you must own the file and have the CHOWN privilege (see .IR setprivgrp (1M)). If either command is invoked on a regular file by other than the superuser, the set-user-ID and set-group-ID bits of the file mode (04000 and 02000 respectively) are cleared. Note that a given user's or group's ability to use this command can be restricted by .CR setprivgrp (see .IR setprivgrp (1M)). .PP .SS "Access Control Lists \(mi HFS File Systems Only" Users can permit or deny specific individuals and groups to access a file by setting optional ACL entries in the file's access control list (see .IR acl (5)). When using .CR chown in conjunction with ACLs, if the new owner and/or group of a file does not have an optional ACL entry corresponding to .IC user .% and/or .CI %. group in the file's access control list, the file's access permission bits remain unchanged. However, if the new owner and/or group is already designated by an optional ACL entry of .IC user .% and/or .CI %. group in the file's ACL, .CR chown sets the corresponding file access permission bits (and the corresponding base ACL entries) to the permissions contained in that entry. .SS Options .CR chown and .CR chgrp recognize the following options: .RS .TP .CR \-h Change the owner or group of a symbolic link. .IP By default, the owner or group of the target file that a symbolic link points to is changed. With .CR \-h , the target file that the symbolic link points to is not affected. If the target file is a directory, and you specify .CR \-h and .CR \-R , recursion does not take place. .TP .CR \-R Recursively change the owner or group. For each .I file operand that names a directory, the owner or group of the directory and all files and subdirectories in the file hierarchy below it are changed. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C chown behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .CR chown and .CR chgrp return the following values: .RS .TP .CR \00 Successful completion. .PD 0 .TP .CR >0 An error condition occurred. .RE .PD .SH EXAMPLES The following command changes the owner of the file .CR jokes to .CR sandi : .IP .C "chown sandi jokes" .PP The following command searches the directory .CR design_notes and changes each file in that directory to owner .CR mark and group .CR users : .IP .C "chown \-R mark:users design_notes" .SH WARNINGS The default operation of .CR chown and .CR chgrp for symbolic links has changed as of HP-UX release 10.0. Use the .CR \-h option to get the former default operation. .SH FILES .CR /etc/group .br .CR /etc/passwd .SH SEE ALSO chmod(1), setprivgrp(1M), chown(2), group(4), passwd(4), acl(5). .SH STANDARDS CONFORMANCE .CR chown ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR chgrp ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" toc@\f3chown(1)\f1:\0\0\f4chown\f1, \f4chgrp\f1@@@change file owner or group .\" toc@\f4chgrp\f1: change file group@@@see \f3chown(1)\f1 .\" .\" index@\f4chown\f1 \- change file owner@@@\f3chown(1)\f1 .\" index@\f4chgrp\f1 \- change group of file@@@\f3chown(1)\f1 .\" index@change file owner or group@@@\f3chown(1)\f1 .\" index@file, change owner or group@@@\f3chown(1)\f1 .\" index@name of file owner or group, change@@@\f3chown(1)\f1 .\" index@owner of file, change@@@\f3chown(1)\f1 .\" index@group of file, change@@@\f3chown(1)\f1 .\" .\" links@chown.1 chgrp.1 .\" $Header: chkey.1,v 72.2 94/08/18 12:27:30 ssa Exp $ .TA c .TH chkey 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chkey \- create or change an encryption key .SH SYNOPSIS .C chkey .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .CR chkey prompts the user for a login password and uses this password to either create a new encryption key in the .IR publickey (4) database or change the user's existing key. .PP To create new encryption keys, .CR chkey requires an active entry for .I nobody in the .C /etc/publickey database. If the .I nobody entry is commented out, the .CR chkey function is limited to changes in existing encryption keys. .SH EXAMPLES .CR chkey .PP .C Generating new key for unix.node@domain. .PP .C Password: xxxxx .PP .C Sending key change request to hpindhsb... .PP .C Done. .PP .SH WARNINGS For .CR chkey to update the master NIS server's .CR /etc/publickey file, the master server must be running both the .CR rpc.ypupdated process and the keyserv process, .IR keyserv (1M) , and the NIS client must be running the keyserv process. .SH AUTHOR .CR chkey was developed by Sun Microsystems, Inc. .SH FILES .C /etc/publickey .SH SEE ALSO keylogin(1), keylogout(1), keyserv(1M), newkey(1M), publickey(4). .\" .\" index@\f4chkey\f1 \- create or change an encryption key@@@\f3chkey(1)\f1 .\" index@\f1create or change an encryption key@@@\f3chkey(1)\f1 .\" index@\f1publickey database, create or change an encryption key in@@@\f3chkey(1)\f1 .\" index@\f1encryption key, create or change@@@\f3chkey(1)\f1 .\" .\" toc@\f3chkey(1)\f1: \f4chkey\f1@@@create or change an encryption key .\" $Header: chmod.1,v 78.1 96/04/05 11:18:47 ssa Exp $ .TA c .TH chmod 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chmod \- change file mode access permissions .SH SYNOPSIS .CR /usr/bin/chmod .RC [ -A ] .RC [ -R ] .IR symbolic_mode_list \0 file \0... .SS Obsolescent form: .CR /usr/bin/chmod .RC [ -A ] .RC [ -R ] .IR numeric_mode \0 file \0... .SH DESCRIPTION The .CR chmod command changes the permissions of one or more .IR file s according to the value of .IR symbolic_mode_list or .IR numeric_mode . You can display the current permissions for a file with the .CR ls\ -l command (see .IR ls (1)). .SS Symbolic Mode List A .IR symbolic_mode_list is a comma-separated list of operations in the following form. Whitespace is not permitted. .IP .RI [ who ] op [ permission\c .RC ]\|[ , ...] .PP The variable fields can have the following values: .RS .TP 12 .IR who One or more of the following letters: .RS .RS .TP 5 .PD 0 .CR u Modify permissions for user (owner). .TP .CR g Modify permissions for group. .TP .CR o Modify permissions for others. .TP .CR a Modify permissions for all users .RC ( a is equivalent to .CR ugo ). .PD .RE .RE .TP .IR op Required; one of the following symbols: .RS .RS .TP 5 .CR + Add .IR permission to the existing file mode bits of .IR who . .PD 0 .TP .CR - Delete .IR permission from the existing file mode bits of .IR who . .TP .CR = Replace the existing mode bits of .IR who with .IR permission . .PD .RE .RE .TP .IR permission One or more of the following letters: .RS .RS .TP 5 .PD 0 .CR r Add or delete the read permission for .IR who . .TP .CR w Add or delete the write permission for .IR who . .TP .CR x Add or delete the execute file (search directory) permission for .IR who . .TP .CR s Add or delete the set-owner-id or set-group-id on file execution permission for .IR who . Useful only if .CR u or .CR g is expressed or implied in .IR who . .TP .CR t Add or delete the save-text-image on file execution (sticky bit) permission. Useful only if .CR u is expressed or implied in .IR who . See .IR chmod (2). .TP .CR X Conditionally add or delete the execute/search permission as follows: .\" * if file is a directory, then X equals x. .\" .\" * if file is not a directory, then if the current permissions contain .\" at least one x, then X equals x (i.e., set or clear the appropriate .\" execute permissions). .\" .\" * if file is not a directory, then if the current permissions DO NOT .\" contain at least one x, then DO NOT set (nothing to clear) any .\" execute permission. .RS .TP 3 \(bu If .IR file is a directory, add or delete the search permission to the existing file mode for .IR who . (Same as .CR x .) .TP \(bu If .IR file is not a directory, and the current file permissions include the execute permission .RC ( "ls -l" displays an .CR x or an .CR s ) for at least one of user, group, or other, then add or delete the execute file permission for .IR who . .TP \(bu If .IR file is not a directory, and no execute permissions are set in the current file mode, then do not change any execute permission. .RE .RE .PD .PP Or one only of the following letters: .RS .TP .PD 0 .CR u Copy the current user permissions to .IR who . .TP .CR g Copy the current group permissions to .IR who . .TP .CR o Copy the current other permissions to .IR who . .PD .RE .RE .RE .PP The operations are performed in the order specified, and can override preceding operations specified in the same command line. .PP If .IR who is omitted, the .CR r , .CR w , .CR x , and .CR X permissions are changed for all users if the changes are permitted by the current file mode creation mask (see .IR umask (1)). The .CR s and .CR t permissions are changed as if .CR a was specified in .IR who . .PP Omitting .IR permission is useful only when used with .CR = to delete all permissions. .br .if t .ne 13v .SS Numeric Mode (Obsolescent) Absolute permissions can be set by specifying a .IR numeric_mode , an octal number constructed from the logical OR (sum) of the following mode bits: .nf .PP Miscellaneous mode bits: .IP .CR "4000 " "(= " "u=s" ")\0\0Set-user-id on file execution (file only)" .CR "2000 " "(= " "g=s" ")\0\0Set-group-id on file execution" .CR "1000 " "(= " "u=t" ")\0\0Set sticky bit; see \f2chmod\f1(2)" .PP Permission mode bits: .IP .CR "0400 " "(= " "u=r" ")\0\0Read by owner" .CR "0200 " "(= " "u=w" ")\0\0Write by owner" .CR "0100 " "(= " "u=x" ")\0\0Execute (search in directory) by owner" .CR "0040 " "(= " "g=r" ")\0\0Read by group" .CR "0020 " "(= " "g=w" ")\0\0Write by group" .CR "0010 " "(= " "g=x" ")\0\0Execute/search by group" .CR "0004 " "(= " "o=r" ")\0\0Read by others" .CR "0002 " "(= " "o=w" ")\0\0Write by others" .CR "0001 " "(= " "o=x" ")\0\0Execute/search by others" .fi .SS Options .RS .TP .CR -A Preserve any optional access control list (ACL) entries associated with the file. By default, in conformance with the IEEE Standard POSIX 1003.1-1988, optional ACL entries are deleted. For information about access control lists, see .IR acl (5). .TP .CR -R Recursively change the file mode bits. For each .IR file operand that names a directory, .CR chmod alters the file mode bits of the named directory and all files and subdirectories in the file hierarchy below it. .RE .PP Only the owner of a file, or a user with appropriate privileges, can change its mode. .PP Only a user having appropriate privileges can set (or retain, if previously set) the sticky bit of a regular file. .PP In order to set the set-group-id on execution bit, the group of the file must correspond to your current group ID. .PP If .CR chmod is used on a symbolic link, the mode of the file referred to by the link is changed. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C chmod behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE Upon completion, .CR chmod returns one of the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR >0 An error condition occurred. .RE .PD .SH EXAMPLES Deny write permission to others: .IP .CI "chmod o-w \&" file .PP Make a file executable by everybody: .IP .CI "chmod a+x \&" file .PP Assign read and execute permission to everybody, and set the set-user-id bit: .IP .CI "chmod a=rx,u+s \&" file .PP Assign read and write permission to the file owner, and read permission to everybody else: .IP .PD 0 .CI "chmod u=rw,go=r \&" file .PP or .IP .CI "chmod 644 \&" file \0\0(obsolescent form) .PD .PP Traverse a directory subtree making all regular files readable by user and group only, and all executables and directories executable (searchable) by everyone: .IP .CI "chmod -R ug+r,o-r,a+X \&" pathname .PP If the current value of .CR umask is .CR 020 .RC ( "umask -S" displays .CR "u=rwx,g=rx,o=rwx" ; do not change write permission for group) and the current permissions for file .CR mytest are .CR 444 .RC ( a=r ), displayed by .CR ls\ -l as .CR -r--r--r-- , then the command .IP .C chmod +w mytest .PP sets the permissions to .CR 646 .RC ( uo=rw,g=r ), displayed by .CR ls\ -l as .CR -rw-r--rw- . .PP If the current value of .CR umask is .CR 020 .RC ( "umask -S" displays .CR "u=rwx,g=rx,o=rwx" ; do not change write permission for group) and the current permissions for file .CR mytest are .CR 666 .RC ( a=rw ), displayed by .CR ls\ -l as .CR -rw-rw-rw- , then the command .IP .C chmod -w mytest .PP sets the permissions to .CR 464 .RC ( uo=r,g=rw ), displayed by .CR ls\ -l as .CR -r--rw-r-- . .SH DEPENDENCIES The .CR -A option causes .CR chmod to fail on file systems that do not support ACLs. .SH AUTHOR .CR chmod was developed by AT&T and HP. .SH SEE ALSO chacl(1),\" STD ls(1), umask(1), chmod(2), acl(5).\" STD .SH STANDARDS CONFORMANCE .CR chmod ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4chmod\f1 \- change file mode access permissions@@@\f3chmod(1)\f1 .\" index@access permissions, change file mode@@@\f3chmod(1)\f1 .\" index@change file mode access permissions@@@\f3chmod(1)\f1 .\" index@file mode, change access permissions@@@\f3chmod(1)\f1 .\" index@context-dependent file@@@\f3chmod(1)\f1 .\" index@file, hidden@@@\f3chmod(1)\f1 .\" index@file: change file mode access permissions@@@\f3chmod(1)\f1 .\" index@file, context-dependent@@@\f3chmod(1)\f1 .\" index@hidden file@@@\f3chmod(1)\f1 .\" index@mode, change file access permissions@@@\f3chmod(1)\f1 .\" index@permissions, change file mode access@@@\f3chmod(1)\f1 .\" .\" toc@\f3chmod(1)\f1:\0\0\f4chmod\f1@@@change file mode access permissions .\" $Header: chown.1,v 76.3 95/08/01 16:09:14 ssa Exp $ .TA c .TH chown 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chown, chgrp \- change file owner or group .SH SYNOPSIS .CR chown .RC [ \-h ] .RC [ \-R ] .I owner\c .RC [ :\c .IR group ] .IR file \ ... .PP .CR chgrp .RC [ \-h ] .RC [ \-R ] .I group .IR file \ ... .SH DESCRIPTION The .CR chown command changes the owner ID of each specified .I file to .I owner and optionally the group ID of each specified .IR file to .IR group . .PP The .CR chgrp command changes the group ID of each specified .IR file to .IR group . .PP .I owner can be either a decimal user ID or a login name found in the .CR /etc/passwd file. .PP .I group can be either a decimal group ID or a group name found in the .CR /etc/group file. .PP In order to change the owner or group, you must own the file and have the CHOWN privilege (see .IR setprivgrp (1M)). If either command is invoked on a regular file by other than the superuser, the set-user-ID and set-group-ID bits of the file mode (04000 and 02000 respectively) are cleared. Note that a given user's or group's ability to use this command can be restricted by .CR setprivgrp (see .IR setprivgrp (1M)). .PP .SS "Access Control Lists \(mi HFS File Systems Only" Users can permit or deny specific individuals and groups to access a file by setting optional ACL entries in the file's access control list (see .IR acl (5)). When using .CR chown in conjunction with ACLs, if the new owner and/or group of a file does not have an optional ACL entry corresponding to .IC user .% and/or .CI %. group in the file's access control list, the file's access permission bits remain unchanged. However, if the new owner and/or group is already designated by an optional ACL entry of .IC user .% and/or .CI %. group in the file's ACL, .CR chown sets the corresponding file access permission bits (and the corresponding base ACL entries) to the permissions contained in that entry. .SS Options .CR chown and .CR chgrp recognize the following options: .RS .TP .CR \-h Change the owner or group of a symbolic link. .IP By default, the owner or group of the target file that a symbolic link points to is changed. With .CR \-h , the target file that the symbolic link points to is not affected. If the target file is a directory, and you specify .CR \-h and .CR \-R , recursion does not take place. .TP .CR \-R Recursively change the owner or group. For each .I file operand that names a directory, the owner or group of the directory and all files and subdirectories in the file hierarchy below it are changed. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C chown behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .CR chown and .CR chgrp return the following values: .RS .TP .CR \00 Successful completion. .PD 0 .TP .CR >0 An error condition occurred. .RE .PD .SH EXAMPLES The following command changes the owner of the file .CR jokes to .CR sandi : .IP .C "chown sandi jokes" .PP The following command searches the directory .CR design_notes and changes each file in that directory to owner .CR mark and group .CR users : .IP .C "chown \-R mark:users design_notes" .SH WARNINGS The default operation of .CR chown and .CR chgrp for symbolic links has changed as of HP-UX release 10.0. Use the .CR \-h option to get the former default operation. .SH FILES .CR /etc/group .br .CR /etc/passwd .SH SEE ALSO chmod(1), setprivgrp(1M), chown(2), group(4), passwd(4), acl(5). .SH STANDARDS CONFORMANCE .CR chown ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR chgrp ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" toc@\f3chown(1)\f1:\0\0\f4chown\f1, \f4chgrp\f1@@@change file owner or group .\" toc@\f4chgrp\f1: change file group@@@see \f3chown(1)\f1 .\" .\" index@\f4chown\f1 \- change file owner@@@\f3chown(1)\f1 .\" index@\f4chgrp\f1 \- change group of file@@@\f3chown(1)\f1 .\" index@change file owner or group@@@\f3chown(1)\f1 .\" index@file, change owner or group@@@\f3chown(1)\f1 .\" index@name of file owner or group, change@@@\f3chown(1)\f1 .\" index@owner of file, change@@@\f3chown(1)\f1 .\" index@group of file, change@@@\f3chown(1)\f1 .\" .\" links@chown.1 chgrp.1 .\" $Header: chsh.1,v 78.1 96/05/09 10:47:48 ssa Exp $ .TA c .TH chsh 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chsh \- change default login shell .SH SYNOPSIS .C chsh .I login-name .RI [ shell ] .SH DESCRIPTION The .C chsh command changes the login-shell field for a user's login name in the password file (see .IR passwd (1) and .IR passwd (4)). .SS Arguments .RS .TP 12 .IR login-name A login name defined in the local system's .CR /etc/passwd file. .TP .IR shell The absolute path name of a shell. If the file .CR /etc/shells exists, the new login shell must be listed in that file. Otherwise, you can specify one of the standard shells listed in the .IR getusershell (3C) manual entry. If .IR shell is omitted, it defaults to the POSIX shell, .CR /usr/bin/sh . .SH NETWORKING FEATURES .SS NFS File .CR /etc/passwd can be implemented as a Network Information Service (NIS) database. However, .CR chsh can change .CR /etc/passwd on the local system only. .SH EXAMPLES To change the login shell for user .CR voltaire to the default: .IP .C "chsh voltaire" .PP To change the login shelf for user .CR descartes to the C shell: .IP .C "chsh descartes /usr/bin/csh" .SH WARNINGS As many users may try to write the .CR /etc/passwd file simultaneously, a passwd locking mechanism was deviced. If this locking fails after subsequent retrying, .CR chsh terminates. .SH DEPENDENCIES .SS HP-UX Integrated Login Library .CR chsh can use the HP-UX Integrated Login Library, if it is configured. For further details, see .IR auth (5) and .IR auth.adm (1m). .PP The HP-UX Integrated Login typically uses the Distributed Computing Environment (DCE) for its user registry. The DCE user registry and its relationship to the HP-UX Integrated Login are described in .IR auth.dce (5). .SH AUTHOR .CR chsh was developed by HP and the University of California, Berkeley. .SH FILES .CR /etc/shells .br .CR /etc/ptmp .SH SEE ALSO chfn(1), csh(1), ksh(1), pam(1), passwd(1), sh(1), sh_bourne(1), sh_posix(1), getusershell(3C), passwd(4), shells(4). .PP HP-UX Integrated Login Library: auth.adm(1m), auth(5), auth.dce(5). .\" .\" toc@\f3chsh(1)\f1:\0\0\f4chsh\f1@@@change default login shell .\" .\" index@\f1change default login shell@@@\f3chsh(1)\f1 .\" index@\f1default login shell, change@@@\f3chsh(1)\f1 .\" index@\f1login shell, change default@@@\f3chsh(1)\f1 .\" index@\f1redefine default login shell@@@\f3chsh(1)\f1 .\" index@\f1shell, login, change default@@@\f3chsh(1)\f1 .\" index@\f4chsh\f1 \- change default login shell@@@\f3chsh(1)\f1 .\" index@\f4passwd\f1 file, change default login shell@@@\f3chsh(1)\f1 .\" $Header: ci.1,v 72.4 93/01/14 11:30:51 ssa Exp $ .TA c .TH ci 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ci \- check in \s-1RCS\s0 revisions .SH SYNOPSIS .C ci .RI [ \|options\| ] .I file ... .SH DESCRIPTION .C ci stores new revisions into .SM RCS files. Each file name ending in .C ,v is treated as an .SM RCS file; all others are assumed to be working files. .C ci deposits the contents of each working file into the corresponding .SM RCS file (see .IR rcsintro (5)). .PP If the .SM RCS file does not exist, .C ci creates it and deposits the contents of the working file as the initial revision. The default number is "1.1". The access list is initialized to empty. Instead of the log message, .C ci requests descriptive text (see the .C -t option below). .PP An .SM RCS file created by .C ci inherits the read and execute permissions from the working file. If the .SM RCS file exists, .C ci preserves its read and execute permissions. .C ci always turns off all write permissions of .SM RCS files. .PP The caller of the command must have read/write permission for the directories containing the .SM RCS file and the working file, and read permission for the .SM RCS file itself. A number of temporary files are created. A semaphore file is created in the directory containing the .SM RCS file. .C ci always creates a new .SM RCS file and unlinks the old one; therefore links to .SM RCS files are useless. .PP For .C ci to work, the user's login must be in the access list unless the access list is empty, the user is the owner of the file, or the user is super-user. .PP Normally, .C ci checks whether the revision to be deposited is different from the preceding one. If it is not different, .C ci either aborts the deposit (if .C -q is given) or asks whether to abort (if .C -q is omitted). A deposit can be forced with the .C -f option. .PP For each revision deposited, .C ci prompts for a log message. The log message should summarize the change and must be terminated with a line containing a single "." or a control-D. If several files are being checked in, .C ci asks whether or not to reuse the log message from the previous file. If the standard input is not a terminal, .C ci suppresses the prompt and uses the same log message for all files (see .C -m option below. .PP The number of the deposited revision can be given with any of the options .CR -r , .CR -f , .CR -k , .CR -l , .CR -u , or .C -q (see .C -r option below). .PP To add a new revision to an existing branch, the head revision on that branch must be locked by the caller. Otherwise, only a new branch can be created. This restriction is not enforced for the owner of the file, unless locking is set to .C strict (see .IR rcs (1)). A lock held by someone else can be broken with the .C rcs command (see .IR rcs (1)). .SS Options .TP 15 .CR -f [\|\f2rev\fP\|] Forces a deposit. The new revision is deposited even if it is not different from the preceding one. .TP .CR -k [\|\f2rev\fP\|] Searches the working file for keyword values to determine its revision number, creation date, author, and state (see .IR co (1)), and assigns these values to the deposited revision, rather than computing them locally. A revision number given with a command option overrides the number in the working file. This option is useful for software distribution. A revision that is sent to several sites should be checked in with the .C -k option at these sites to preserve its original number, date, author, and state. .TP .CR -l [\|\f2rev\fP\|] Works like .CR -r , except it performs an additional .C co -l for the deposited revision. Thus, the deposited revision is immediately checked out again and locked. This is useful for saving a revision although one wants to continue editing it after the check-in. .tr ~" .TP .CI -m~ msg ~ Uses the string .I msg as the log message for all revisions checked in. .TP .CI -n~ name ~ Assigns the symbolic name .I name to the checked-in revision. .C ci prints an error message if .I name is already assigned to another number. .TP .CI -N~ name ~ Same as .CR -n , except that it overrides a previous assignment of .IR name . .tr ~~ .TP .CR -q [\|\f2rev\fP\|] Quiet mode; diagnostic output is not printed. A revision that is not different from the preceding one is not deposited unless .C -f is given. .TP .CR -r [\|\f2rev\fP\|] Assigns the revision number .I rev to the checked-in revision, releases the corresponding lock, and deletes the working file. This is the default. .IP If .I rev is omitted, .C ci derives the new revision number from the caller's last lock. If the caller has locked the head revision of a branch, the new revision is added to the head of that branch and a new revision number is assigned to the new revision. The new revision number is obtained by incrementing the head revision number. If the caller locked a non-head revision, a new branch is started at the locked revision, and the number of the locked revision is incremented. The default initial branch and level numbers are 1. If the caller holds no lock, but is the owner of the file and locking is not set to .IR strict , the revision is added to the head of the trunk. .IP If .I rev indicates a revision number, it must be higher than the latest one on the branch to which .I rev belongs, or must start a new branch. .IP If .I rev indicates a branch instead of a revision, the new revision is added to the head of that branch. The level number is obtained by incrementing the head revision number of that branch. If .I rev indicates a non-existing branch, that branch is created with the initial revision numbered .IC rev .1\f1. .IP .SM NOTE: On the trunk, revisions can be added to the head, but not inserted. .tr ~" .TP .CI -s~ state ~ Sets the state of the checked-in revision to the identifier .IR state . .tr ~~ The default is .CR Exp . .TP .CR -t [\|\f2txtfile\fP\|] Writes descriptive text into the .SM RCS file (deletes the existing text). If .I txtfile is omitted, .C ci prompts the user for text from standard input that is terminated with a line containing a single .C . or Ctrl-D. Otherwise, the descriptive text is copied from the file .IR txtfile . During initialization, descriptive text is requested even if .C -t is not given. The prompt is suppressed if standard input is not a terminal. .TP .CR -u [\|\f2rev\fP\|] Similar to .CR -l , except that the deposited revision is not locked. This is useful if one wants to process (e.g., compile) the revision immediately after check in. .SS "Access Control Lists (\s-1ACL\s0s) Optional .SM ACL entries should not be added to .SM RCS files, because they might be deleted. .SH DIAGNOSTICS For each revision, .C ci prints the .SM RCS file, the working file, and the number of both the deposited and the preceding revision. The exit status always refers to the last file checked in, and is 0 if the operation was successful, 1 if unsuccessful. .SH EXAMPLES If the current directory contains a subdirectory .C RCS with an .SM RCS file .CR io.c,v , all of the following commands deposit the latest revision from .C io.c into .CR RCS/io.c,v : .nf .IP .C "ci io.c" .C "ci RCS/io.c,v" .C "ci io.c,v" .C "ci io.c RCS/io.c,v" .C "ci io.c io.c,v" .C "ci RCS/io.c,v io.c" .C "ci io.c,v io.c" .fi .PP Check in version 1.2 of .SM RCS file .CR foo.c,v , with the message .CR "Bug fix" : .IP .C "ci -r1.2 -m""Bug Fix"" foo.c,v" .SH WARNINGS The names of .SM RCS files are generated by appending .C ",v" to the end of the working file name. If the resulting .SM RCS file name is too long for the file system on which the .SM RCS file should reside, .C ci terminates with an error message. .PP The log message cannot exceed 2046 bytes. .PP A file with approximately 240 revisions may cause a hash table overflow. .C ci cannot add another revision to the file until some of the old revisions have been removed. Use the .C rcs -o (obsolete) command option to remove old revisions. .PP .SM RCS is designed to be used with .SM TEXT files only. Attempting to use .SM RCS with non-text (binary) files results in data corruption. .SH AUTHOR .C ci was developed by Walter F. Tichy. .SH SEE ALSO co(1), ident(1), rcs(1), rcsdiff(1), rcsmerge(1), rlog(1), rcsfile(4), acl(5), rcsintro(5). .\" .\" index@\f4ci\f1 \- check in \s-1RCS\s+1 revisions@@@\f3ci(1)\f1 .\" index@check in \s-1RCS\s+1 revisions@@@\f3ci(1)\f1 .\" index@\s-1RCS\s+1: check in \s-1RCS\s+1 revisions@@@\f3ci(1)\f1 .\" index@revisions, \s-1RCS\s+1, check in@@@\f3ci(1)\f1 .\" index@Revision Control System@@@(see \s-1RCS\s+1) .\" .\" toc@\f3ci(1)\f1:\0\0\f4ci\f1@@@check in \s-1RCS\s+1 revisions .\" .\" fileset_database@ci.1 USER-CMDS-MAN .\" $Header: cksum.1,v 76.2 95/08/23 17:52:21 ssa Exp $ .TA c .TH cksum 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cksum \- print file checksum and sizes .SH SYNOPSIS .C cksum .RI [ file\0 ...] .SH DESCRIPTION The .CR cksum command calculates and prints to standard output a checksum for each named file, and also prints the number of octets in each file. .PP .CR cksum uses a portable algorithm based on a 32-bit Cyclic Redundancy Check. This algorithm finds a broader spectrum of errors than the 16-bit algorithms used by .CR sum (see .IR sum (1)). The CRC is the sum of the following expressions, where .I x is each byte of the file. .IP .ifn \{x^32 + x^26 + x^23 +x^22 + x^16 + x^12 + x^11 + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x^1 + x^0\} .ift \{.IR x "\u\s-232\s+2\d +" .IR x "\u\s-226\s+2\d +" .IR x "\u\s-223\s+2\d +" .IR x "\u\s-222\s+2\d +" .IR x "\u\s-216\s+2\d +" .IR x "\u\s-212\s+2\d +" .IR x "\u\s-211\s+2\d +" .IR x "\u\s-210\s+2\d +" .IR x "\u\s-27\s+2\d +" .IR x "\u\s-25\s+2\d +" .IR x "\u\s-24\s+2\d +" .IR x "\u\s-22\s+2\d +" .IR x "\u\s-21\s+2\d +" .IR x \u\s-20\s+2\d\} .PP The results of the calculation are truncated to a 32-bit value. The number of bytes in the file is also printed. .PP Standard input is used if no file names are given. .PP .CR cksum is typically used to verify data integrity when copying files between systems. .SH EXTERNAL INFLUENCES .SS Environment Variables .PP .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not set or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .CR LC_CTYPE determines the locale for interpretation of sequences of bytes of text data as characters (e.g., single- verses multibyte characters in arguments and input files). .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If any internationalization variable contains an invalid setting, .C cksum behaves as if all internationalization variables are set to "C". See .IR environ (5). .SH RETURN VALUE Upon completion, .CR cksum returns one of the following values: .RS .TP 5 .C \00 All files were processed successfully. .TP .C >0 One or more files could not be read or another error occurred. .RE .PP If an inaccessible file is encountered, .CR cksum continues processing any remaining files, but the final exit status is affected. .SH SEE ALSO sum(1), wc(1), pdf(4). .SH STANDARDS CONFORMANCE .CR cksum ": XPG4, POSIX.2" .\" .\" index@\f4cksum\f1 \- print file checksum and sizes@@@\f3sum(1)\f1 .\" index@\f1perform Cyclical Redundancy Check on a file@@@\f3sum(1)\f1 .\" index@\f1Cyclical Redundancy Check on a file@@@\f3sum(1)\f1 .\" index@\f1files, print checksum and block count of a file@@@\f3sum(1)\f1 .\" index@\f1files, Cyclical Redundancy Check on a file@@@\f3sum(1)\f1 .\" index@\f1print checksum and block count of a file@@@\f3sum(1)\f1 .\" index@\f1checksum and block count of a file, print@@@\f3sum(1)\f1 .\" index@\f1block count and checksum of a file, print@@@\f3sum(1)\f1 .\" .\" toc@\f3cksum(1)\f1:\0\0\f4cksum\f1@@@print file checksum and sizes\f1 .\" $Header: clear.1,v 72.4 93/11/11 16:40:15 ssa Exp $ .TA c .TH clear 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clear \- clear terminal screen .SH SYNOPSIS .C clear .SH DESCRIPTION .C clear clears the terminal screen if it is possible to do so. It reads the .C TERM environment variable for the terminal type, then reads the appropriate .C terminfo database to determine how to clear the screen. .SH FILES .TP 25 .C /usr/share/lib/terminfo/?/* terminal database files .SH AUTHOR .C clear was developed by the University of California, Berkeley. .SH SEE ALSO terminfo(4). .\" .\" toc@\f3clear(1)\f1:\0\0\f4clear\f1@@@clear terminal screen .\" .\" index@\f4clear\f1 \- clear terminal screen@@@\f3clear(1)\f1 .\" index@erase terminal screen@@@\f3clear(1)\f1 .\" index@terminal screen, clear@@@\f3clear(1)\f1 .\" index@screen, clear terminal@@@\f3clear(1)\f1 .\" .\" fileset_database@clear.1 USER-CMDS-MAN .\" $Header: cmp.1,v 78.1 96/02/12 13:35:35 ssa Exp $ .TA c .TH cmp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cmp \- compare two files .SH SYNOPSIS .C cmp .RC [ -l ] .RC [ -s ] .I file1 file2 .SH DESCRIPTION .C cmp compares two files (if .I file1 or .I file2 is .CR - , the standard input is used). Under default options, .C cmp makes no comment if the files are the same; if they differ, it announces the byte and line number at which the difference occurred. If one file is an initial subsequence of the other, that fact is noted. .PP .C cmp recognizes the following options: .RS .TP 8 .C -l Print the byte number (decimal) and the differing bytes (octal) for each difference (byte numbering begins at 1 rather than 0). .TP .C -s Print nothing for differing files; return codes only. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the language in which messages are displayed. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C cmp behaves as if all internationalization variables are set to "C". See .IR environ(5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS .C cmp returns the following exit values: .RS .TP 6 .C 0 Files are identical. .PD 0 .TP .C 1 Files are not identical. .TP .C 2 Inaccessible or missing argument. .PD .RE .PP .C cmp prints the following warning if the comparison succeeds till the end of file of file1(file2) is reached. .RS .TP 6 .C cmp: EOF on file1(file2) .RS .SH SEE ALSO comm(1), diff(1). .SH STANDARDS CONFORMANCE .CR cmp ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" toc@\f3cmp(1)\f1:\0\0\f4cmp\f1@@@compare two files .\" .\" index@\f4cmp\f1 \- compare two files@@@\f3cmp(1)\f1 .\" index@\f1compare two files@@@\f3cmp(1)\f1 .\" index@\f1files: compare two files@@@\f3cmp(1)\f1 .\" index@\f1two files, compare@@@\f3cmp(1)\f1 .\" .\" $Header: co.1,v 72.4 93/01/14 11:31:15 ssa Exp $ .TA c .TH co 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME co \- check out \s-1RCS\s+1 revisions .SH SYNOPSIS .C co .RI [ \|options\| ] .I file ... .SH DESCRIPTION .C co retrieves revisions from .SM RCS files. Each file name ending in .C ,v is taken to be an .SM RCS file. All other files are assumed to be working files. .C co retrieves a revision from each .SM RCS file and stores it in the corresponding working file (see also .IR rcsintro (5)). .PP Revisions of an .SM RCS file can be checked out locked or unlocked. Locking a revision prevents overlapping updates. A revision checked out for reading or processing (e.g., compiling) need not be locked. A revision checked out for editing and later checked in must normally be locked. Locking a revision currently locked by another user fails (a lock can be broken with the .C rcs command, but poses inherent risks when independent changes are being made simultaneously (see .IR rcs (1)). .C co with locking requires the caller to be on the access list of the .SM RCS file unless: he is the owner of the file, a user with appropriate privileges, or the access list is empty. .C co without locking is not subject to access list restrictions. .PP A revision is selected by number, check-in date/time, author, or state. If none of these options are specified, the latest revision on the trunk is retrieved. When the options are applied in combination, the latest revision that satisfies all of them is retrieved. The options for date/time, author, and state retrieve a revision on the selected branch. The selected branch is either derived from the revision number (if given), or is the highest branch on the trunk. A revision number can be attached to the options .CR -l , .CR -p , .CR -q , or .CR -r . .PP The caller of the command must have write permission in the working directory, read permission for the .SM RCS file, and either read permission (for reading) or read/write permission (for locking) in the directory that contains the .SM RCS file. .PP The working file inherits the read and execute permissions from the .SM RCS file. In addition, the owner write permission is turned on, unless the file is checked out unlocked and locking is set to .C strict (see .IR rcs (1)). .PP If a file with the name of the working file exists already and has write permission, .C co aborts the check out if .C -q is given, or asks whether to abort if .C -q is not given. If the existing working file is not writable, it is deleted before the check out. .PP A number of temporary files are created. A semaphore file is created in the directory of the .SM RCS file to prevent simultaneous update. .PP A .C co command applied to an .SM RCS file with no revisions creates a zero-length file. .C co always performs keyword substitution (see below). .SS Options .TP 15 .CR -l [\|\f2rev\fP\|] Locks the checked out revision for the caller. If omitted, the checked out revision is not locked. See option .C -r for handling of the revision number .IR rev . .TP .CR -p [\|\f2rev\fP\|] Prints the retrieved revision on the standard output rather than storing it in the working file. This option is useful when .C co is part of a pipe. .TP .CR -q [\|\f2rev\fP\|] Quiet mode; diagnostics are not printed. .TP .CI -d date Retrieves the latest revision on the selected branch whose check in date/time is less than or equal to .IR date . The date and time may be given in free format and are converted to local time. Examples of formats for .IR date : .IP .TS tab(@); lI l. Tue\-PDT, 1981, 4pm Jul 21@(free format) Fri April 16 15:52:25 EST 1982@(output of \f2ctime\f1(3C)) 86/4/21 10:30am@(format: yy/mm/dd hh:mm:ss) .TE .IP Most fields in the date and time can be defaulted. .C co determines the defaults in the order year, month, day, hour, minute, and second (from most- to least-significant). At least one of these fields must be provided. For omitted fields that are of higher significance than the highest provided field, the current values are assumed. For all other omitted fields, the lowest possible values are assumed. For example, the date .C "20, 10:30" defaults to 10:30:00 of the 20th of the current month and current year. Date/time fields can be delimited by spaces or commas. If spaces are used, the string must be surrounded by double quotes. .TP 10 .CR -r [\|\f2rev\fP\|] Retrieves the latest revision whose number is less than or equal to .IR rev . If .I rev indicates a branch rather than a revision, the latest revision on that branch is retrieved. .I rev is composed of one or more numeric or symbolic fields separated by .CR .\| . The numeric equivalent of a symbolic field is specified with the .C ci -n and .C rcs -n commands (see .IR ci (1) and .IR rcs (1)). .TP .CI -s state Retrieves the latest revision on the selected branch whose state is set to .IR state . .TP .CR -w [\|\f2login\fP\|] Retrieves the latest revision on the selected branch that was checked in by the user with login name .IR login . If the argument .I login is omitted, the caller's login is assumed. .TP .CI -j joinlist Generates a new revision that is the result of the joining of the revisions on .IR joinlist . .I joinlist is a comma-separated list of pairs of the form .RC rev2 : rev3\f1, where .I rev2 and .I rev3 are (symbolic or numeric) revision numbers. For the initial pair, .I rev1 denotes the revision selected by the options .CR -l ,\0... ,\0-w . For all other pairs, .I rev1 denotes the revision generated by the previous pair. (Thus, the output of one join becomes the input to the next.) .IP For each pair, .C co joins revisions .I rev1 and .I rev3 with respect to .IR rev2 . This means that all changes that transform .I rev2 into .I rev1 are applied to a copy of .IR rev3 . This is particularly useful if .I rev1 and .I rev3 are the ends of two branches that have .I rev2 as a common ancestor. If .IR rev1 \0< \0rev2 \0< \0rev3 on the same branch, joining generates a new revision that is similar to .IR rev3 , but with all changes that lead from .I rev1 to .I rev2 undone. If changes from .I rev2 to .I rev1 overlap with changes from .I rev2 to .IR rev3 , .C co prints a warning and includes the overlapping sections, delimited as follows: .RS .IP .C <<<<<<< .br .I rev1 .br .C ======= .br .I rev3 .br .C >>>>>>> .RE .IP For the initial pair, .I rev2 can be omitted. The default is the common ancestor. If any of the arguments indicate branches, the latest revisions on those branches are assumed. If the .C -l option is present, the initial .I rev1 is locked. .SS Keyword Substitution Strings of the form .CI $ keyword $ and .CI $ keyword : \f1...\fP $ embedded in the text are replaced with strings of the form .CI $ keyword : \0value\0$\f1, where .I keyword and .I value are pairs listed below. Keywords may be embedded in literal strings or comments to identify a revision. .PP Initially, the user enters strings of the form .CI $ keyword $\f1. On check out, .C co replaces these strings with strings of the form .CI $ keyword : \0value\0$\f1. If a revision containing strings of the latter form is checked back in, the value fields are replaced during the next checkout. Thus, the keyword values are automatically updated on checkout. .PP Keywords and their corresponding values: .TP 15 .C $\&Author$ The login name of the user who checked in the revision. .TP .C $\&Date$ The date and time the revision was checked in. .TP .C $\&Header$ A standard header containing the .SM RCS file name, the revision number, the date, the author, and the state. .TP .C $\&Locker$ The login name of the user who locked the revision (empty if not locked). .TP .C $\&Log$ The log message supplied during checkin, preceded by a header containing the .SM RCS file name, the revision number, the author, and the date. Existing log messages are .I not replaced. Instead, the new log message is inserted after .CR $\&Log: ... $ . This is useful for accumulating a complete change log in a source file. .TP .C $\&Revision$ The revision number assigned to the revision. .TP .C $\&Source$ The full pathname of the .SM RCS file. .TP .C $\&State$ The state assigned to the revision with .C rcs -s or .CR "ci -s" . .SS "Access Control Lists (ACLs) .PP Optional ACL entries should not be added to .SM RCS files because they might be deleted. .SH DIAGNOSTICS The .SM RCS file name, the working file name, and the revision number retrieved are written to the diagnostic output. The exit status always refers to the last file checked out, and is 0 if the operation was successful, 1 if unsuccessful. .SH EXAMPLES Assume the current directory contains a subdirectory named .C RCS with an .SM RCS file named .CR io.c,v . Each of the following commands retrieves the latest revision from .C RCS\s0/io.c,v and stores it into .CR io.c : .nf .IP .C "co io.c" .C "co RCS/io.c,v" .C "co io.c,v" .C "co io.c RCS/io.c,v" .C "co io.c io.c,v" .C "co RCS/io.c,v io.c" .C "co io.c,v io.c" .fi .PP Check out version 1.1 of .SM RCS file .CR foo.c,v : .IP .C "co -r1.1 foo.c,v" .PP Check out version 1.1 of .SM RCS file .C foo.c,v to the standard output: .IP .C "co -p1.1 foo.c,v" .PP Check out the version of file .C foo.c,v that existed on September 18, 1992: .IP .C "co -d""92/09/18"" foo.c,v" .SH WARNINGS The .C co command generates the working file name by removing the .C ,v from the end of the .SM RCS file name. If the given .SM RCS file name is too long for the file system on which the .SM RCS file should reside, .C co terminates with an error message. .PP There is no way to suppress the expansion of keywords, except by writing them differently. In .C nroff and .CR troff , this is done by embedding the null-character .C \e& into the keyword. .PP The .C -d option gets confused in some circumstances, and accepts no date before 1970. .PP The .C -j option does not work for files containing lines consisting of a single .CR .\| . .PP .SM RCS is designed to be used with .I text files only. Attempting to use .SM RCS with non-text (binary) files results in data corruption. .SH AUTHOR .C co was developed by Walter F. Tichy. .SH SEE ALSO ci(1), ident(1), rcs(1), rcsdiff(1), rcsmerge(1), rlog(1), rcsfile(4), acl(5), rcsintro(5). .\" .\" index@\f4co\f1 \- check out \s-1RCS\s+1 revisions@@@\f3co(1)\f1 .\" index@check out \s-1RCS\s+1 revisions@@@\f3co(1)\f1 .\" index@\s-1RCS\s+1: check out \s-1RCS\s+1 revisions@@@\f3co(1)\f1 .\" index@revisions, \s-1RCS\s+1, check out@@@\f3co(1)\f1 .\" .\" toc@\f3co(1)\f1:\0\0\f4co\f1@@@check out \s-1RCS\s+1 revisions .\" .\" fileset_database@co.1 USER-CMDS-MAN .\" $Header: col.1,v 72.5 94/11/14 13:09:51 ssa Exp $ .TA c .TH col 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME col \- filter reverse line-feeds and backspaces .SH SYNOPSIS .C col .RC [ -blfxp ] .SH DESCRIPTION .C col reads from the standard input and writes onto the standard output. It performs the line overlays implied by reverse line feeds .SM (ASCII code .SM .CR ESC-7 ), and by forward and reverse half-line feeds .SM .RC ( ESC-9 and .SM .CR ESC-8 ). .C col is particularly useful for filtering multi-column output made with the .C nroff .C .rt command, and output resulting from use of the .C tbl preprocessor (see .IR nroff (1) and .IR tbl (1)). .PP If the .C -b option is given, .C col assumes that the output device in use is not capable of backspacing. In this case, if two or more characters are to appear in the same place, only the last one read is output. .PP If the .C -l option is given, .C col assumes the output device is a line printer (rather than a character printer) and removes backspaces in favor of multiply overstruck full lines. It generates the minimum number of print operations necessary to generate the required number of overstrikes. (All but the last print operation on a line are separated by carriage returns (\er); the last print operation is terminated by a newline (\en).) .PP Although .C col accepts half-line motions in its input, it normally does not emit them on output. Instead, text that would appear between lines is moved to the next lower full-line boundary. This treatment can be suppressed by the .C -f (fine) option; in this case, the output from .C col may contain forward half-line feeds .SM (ESC-9), but will still never contain either kind of reverse line motion. .PP Unless the .C -x option is given, .C col converts white space to tabs on output wherever possible to shorten printing time. .PP The .SM ASCII control characters .SM SO (\e016) and .SM SI (\e017) are assumed by .C col to start and end text in an alternate character set. The character set to which each input character belongs is remembered, and on output .SM SI and .SM SO characters are generated as appropriate to ensure that each character is printed in the correct character set. .PP On input, the only control characters accepted are space, backspace, tab, return, new-line, .SM SI , .SM SO , and .SM VT , (\e013), and .SM ESC followed by .CR 7 , .CR 8 , or .CR 9 . The .SM VT character is an alternate form of full reverse line-feed, included for compatibility with some earlier programs of this type. All other non-printing characters are ignored. .PP Normally, .C col ignores any unrecognized escape sequences found in its input; the .C -p option can be used to cause .C col to output these sequences as regular characters, subject to overprinting from reverse line motions. The use of this option is highly discouraged unless the user is fully aware of the textual position of the escape sequences. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C col will behave as if all internationalization variables are set to "C". See .IR environ (5). .PP .C LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .PP .C LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .C LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .C NLSPATH determines the location of message catalogues for the processing of .C LC_MESSAGES. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES .C col is used most often with .C nroff and .CR tbl . A common usage is: .IP .CI tbl " filename " "| nroff -man | col | more -s" .PP (very similar to the usual .IR man (1) command). This command allows vertical bars and outer boxes to be printed for tables. The file is run through the .C tbl preprocessor, and the output is then piped through .CR nroff , formatting the output using the .C -man macros. The formatted output is then piped through .CR col , which sets up the vertical bars and aligns the columns in the file. The file is finally piped through the .CR more command, which prints the output to the screen with underlining and highlighting substituted for italic and bold typefaces. The .C -s option deletes excess space from the output so that multiple blank lines are not printed to the screen. .SH SEE ALSO nroff(1), tbl(1), ul(1), man(5). .SH NOTES The input format accepted by .C col matches the output produced by .C nroff with either the .C -T37 or .C -Tlp options. Use .C -T37 (and the .C -f option of .CR col ) if the ultimate disposition of the output of .C col is a device that can interpret half-line motions, and .C -Tlp otherwise. .SH BUGS Cannot back up more than 128 lines. Cannot back up across page boundaries. .PP There is a maximum limit for the number of characters, including backspaces and overstrikes, on a line. The maximum limit is at least 800 characters. .PP Local vertical motions that would result in backing up over the first line of the document are ignored. As a result, the first line must not have any superscripts. .SH STANDARDS CONFORMANCE .CR col ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4col\f1 \- filter reverse line-feeds and backspaces from text@@@\f3col(1)\f1 .\" index@filter reverse line-feeds and backspaces from text@@@\f3col(1)\f1 .\" index@remove reverse line-feeds and backspaces from text@@@\f3col(1)\f1 .\" index@reverse line-feeds and backspaces, remove from text@@@\f3col(1)\f1 .\" index@backspaces and reverse line-feeds, remove from text@@@\f3col(1)\f1 .\" index@line-feeds, reverse, and backspaces, remove from text@@@\f3col(1)\f1 .\" .\" toc@\f3col(1)\f1:\0\0\f4col\f1@@@filter reverse line-feeds and backspaces .\" .\" fileset_database@col.1 USER-CMDS-MAN .\" $Header: comb.1,v 72.6 94/04/27 11:33:16 ssa Exp $ .TA c .TH comb 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME comb \- combine \s-1SCCS\s0 deltas .SH SYNOPSIS .C comb .RC [ -p\|\c .IR \s-1SID\s+1\| ] .RC [ -c\c .IR list\| ] .RC [ -o ] .RC [ -s ] .IR file \0... .SH DESCRIPTION The .CR comb command generates a shell procedure (see .IR sh (1)) which, when run, reconstructs the given .SM SCCS files. The reconstructed files are usually smaller than the original files. Arguments can be specified in any order, but all options apply to all named .SM SCCS files. If a directory is named, .CR comb behaves as though each file in the directory were specified as a named file, except that non-\c .SM SCCS files (last component of the path name does not begin with .CR s. ) and unreadable files are silently ignored. If a name of .CR - is given, the standard input is read; each line of the standard input is taken to be the name of an .SM SCCS file to be processed; non-\c .SM SCCS files and unreadable files are silently ignored. The generated shell procedure is written on the standard output. .SS Options .CR comb recognizes the following options. Each is explained as if only one named file is to be processed, but the effects of any option apply independently to each named file. .RS .TP 15 .CI -p \s-1SID\s+1 The .IR S "\s-1CCS\s0 " ID entification string .SM (SID) of the oldest delta to be preserved. All older deltas are discarded in the reconstructed file. .TP .CI -c list A .I list of deltas to be preserved (see .IR get (1) for the syntax of a .IR list ). All other deltas are discarded. .TP .CR -o For each .CR "get -e" generated, this option causes the reconstructed file to be accessed at the release of the delta to be created, otherwise the reconstructed file would be accessed at the most recent ancestor. Use of the .CR -o option can decrease the size of the reconstructed .SM SCCS file. It can also alter the shape of the delta tree of the original file. .TP .CR -s This option causes .CR comb to generate a shell procedure which, when run, produces a report giving, for each file: the file name, size (in blocks) after combining, original size (also in blocks), and percentage change computed by: .RS .IP 100 \(mu (original \(mi combined) / original .RE .IP It is recommended that this option be used before any .SM SCCS files are actually combined to determine exactly how much space is saved by the combining process. .RE .PP If no options are specified, .CR comb preserves only leaf deltas and the minimal number of ancestors needed to preserve the tree. .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS Use .IR sccshelp (1) for explanations. .SH EXAMPLES The command: .IP .CR "comb -c1.1,1.3,1.6 s.document > save_file" .PP creates a shell script named .CR save_file , which if executed, creates a new .CR s.document using only the deltas .CR 1.1 , .CR 1.3 , and .CR 1.6 from the old .CR s.document . The script overwrites the old .CR s.document ; thus, it might be wise to copy the original elsewhere. Here is an example of typical technique: .IP .C cp s.document s.save .br .C comb -c1.1,1.3,1.6 s.document > save_file .br .C sh save_file .SH WARNINGS .C comb may rearrange the shape of the tree of deltas. Combining files may or may not save space; in fact, it is possible for the reconstructed file to actually be larger than the original. .SH FILES .TP 25 .CI s.COMB????? Temporary file .TP .C comb????? Temporary file .PD .SH SEE ALSO admin(1), delta(1), get(1), sccshelp(1), prs(1), sh(1), sccsfile(4). .\" .\" index@\f4comb\f1 \- combine \s-1SCCS\s+1 deltas@@@\f3comb(1)\f1 .\" index@combine \s-1SCCS\s+1 deltas@@@\f3comb(1)\f1 .\" index@\s-1SCCS\s+1 deltas, combine@@@\f3comb(1)\f1 .\" index@\s-1SCCS\s+1: combine \s-1SCCS\s+1 deltas@@@\f3comb(1)\f1 .\" .\" toc@\f3comb(1)\f1:\0\0\f4comb\f1@@@combine \s-1SCCS\s+1 deltas .\" .\" fileset_database@comb.1 USER-CMDS-MAN .\" $Header: comm.1,v 76.2 95/08/01 16:14:38 ssa Exp $ .TA c .TH comm 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME comm \- select or reject lines common to two sorted files .SH SYNOPSIS .C comm .RC [ -\c .RC [ 123 ]\|] .I file1 file2 .SH DESCRIPTION .I comm reads .I file1 and .IR file2 , which should be ordered in increasing collating sequence (see .IR sort (1) and Environment Variables below), and produces a three-column output: .RS .TP 12 Column 1: Lines that appear only in .IR file1 , .PD 0 .TP Column 2: Lines that appear only in .IR file2 , .TP Column 3: Lines that appear in both files. .PD .RE .PP If .C - is used for .I file1 or .IR file2 , the standard input is used. .PP Options 1, 2, or 3 suppress printing of the corresponding column. Thus .C comm -12 prints only the lines common to the two files; .C comm -23 prints only lines in the first file but not in the second; .C comm -123 does nothing useful. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the collating sequence .C comm expects from the input files. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG determines the language in which messages are displayed. If .C LC_COLLATE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default. If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C comm behaves as if all internationalization variables are set to ``C''. See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following examples assume that .C file1 and .C file2 have been ordered in the collating sequence defined by the .C LC_COLLATE or .C LANG environment variable. .PP Print all lines common to .C file1 and .C file2 (in other words, print column 3): .IP .C comm -12 file1 file2 .PP Print all lines that appear in .C file1 but not in .CR file2 (in other words, print column 1): .IP .C comm -23 file1 file2 .PP Print all lines that appear in .C file2 but not in .CR file1 (in other words, print column 2): .IP .C comm -13 file1 file2 .SH SEE ALSO cmp(1), diff(1), sdiff(1), sort(1), uniq(1). .SH STANDARDS CONFORMANCE .CR comm ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4comm\f1 \- select/reject lines common to two sorted files@@@\f3comm(1)\f1 .\" index@files: select/reject lines common to two sorted files@@@\f3comm(1)\f1 .\" index@reject/select lines common to two sorted files@@@\f3comm(1)\f1 .\" index@select/reject lines common to two sorted files@@@\f3comm(1)\f1 .\" index@lines common to two sorted files, reject/select@@@\f3comm(1)\f1 .\" index@common to two sorted files, reject/select lines@@@\f3comm(1)\f1 .\" index@two sorted files, reject/select lines common to@@@\f3comm(1)\f1 .\" index@sorted files, reject/select lines common to two@@@\f3comm(1)\f1 .\" index@compare sorted files; reject/select common lines@@@\f3comm(1)\f1 .\" index@diff between sorted files; reject/select common lines@@@\f3comm(1)\f1 .\" .\" toc@\f3comm(1)\f1:\0\0\f4comm\f1@@@select or reject lines common to two sorted files .\" .\" $Header: command.1,v 76.1 95/08/01 16:15:32 ssa Exp $ .TA c .TH command 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME command \- execute a simple command .SH SYNOPSIS .C command .I command_name .RI [ argument \0... ] .SH DESCRIPTION .C command enables the shell to treat the arguments as a simple command, suppressing the shell function lookup. .PP If .I command_name is not the name of the function, the effect of .C command is the same as omitting .IR command . .SH OPERANDS .C command recognizes the following operands: .RS .TP 20 .I command_name The name of a HP-UX command or a shell built-in command. .TP .I argument One or more strings to be interpreted as arguments to .IR command_name . .RE .PP The .C command command is necessary to allow functions that have the same name as a command to call the command (instead of a recursive call to the function). .PP Nothing in the description of .C command is intended to imply that the command line is parsed any differently than any other simple command. For example, .IP .CI command \0a\0 | \0b\0 ; \0c .PP is not parsed in any special way that causes .C | or .C ; to be treated other than a pipe operator or semicolon or that prevents function lookup on .I b or .IR c . .SH EXTERNAL INFLUENCE .SS Environment Variables .C PATH determines the search path used during the command search. .SH RETURN VALUE .C command exits with one of the following values: .RS .TP 3 \(bu If .C command fails: .RS .RS .TP 8 .B 126 The utility specified by the .C command_name is found but not executable. .TP .B 127 An error occurred in the .I command utility or the utility specified by .C command_name is not found. .RE .RE .TP \(bu If .C command does not fail: .RS .RS .PP The exit status of .C command is the same as that of the simple command specified by the arguments: .IP .I command_name .RI [\| argument \0...\|] .RE .RE .RE .SH EXAMPLES Create a version of the .C cd command that always prints the name of the new working directory whenever it is used: .nf .IP .ift .ft 4 .ifn .ft 3 .ps +1 cd() { command "$@" >/dev/null pwd } .ft .ps .fi .PP Circumvent the redefined .C cd command above, and change directories without printing the name of the new working directory: .IP .C command cd .SH SEE ALSO getconf(1), sh-posix(1), confstr(2). .SH STANDARDS CONFORMANCE .CR command ": XPG4, POSIX.2" .\" .\" index@\f4command\f1 \- execute a simple command@@@\f3command(1)\f1 .\" index@execute a simple command@@@\f3command(1)\f1 .\" index@simple command, execute a@@@\f3command(1)\f1 .\" index@command, execute a simple@@@\f3command(1)\f1 .\" .\" toc@\f3cd(1)\f1:\0\0\f4command\f1@@@execute a simple command .\" .\" fileset_database@command.1 USER-CMDS-MAN .\" $Header: compact.1,v 72.3 93/01/14 11:36:09 ssa Exp $ .TA c .TH compact 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compact, uncompact, ccat \- compact and uncompact files, and cat them .SH SYNOPSIS .C compact .RI [ \|name \0...] .br .C uncompact .RI [ \|name \0...] .br .C ccat .RI [ \|file \0...] .SH DESCRIPTION .C compact compresses the named files using an adaptive Huffman code. If no file names are given, standard input is compacted and sent to the standard output. .C compact operates as an on-line algorithm. Each time a byte is read, it is encoded immediately according to the current prefix code. This code is an optimal Huffman code for the set of frequencies seen so far. It is unnecessary to attach a decoding tree in front of the compressed file because the encoder and the decoder start in the same state and stay synchronized. Furthermore, .C compact and .C uncompact can operate as filters. In particular, .IP .RC ... " | compact | uncompact | " ... .PP operates as a (very slow) no-op. .PP When an argument .I file is given, it is compacted, the resulting file is placed in .IC file .C\f1, and .I file is unlinked. The first two bytes of the compacted file code the fact that the file is compacted. These bytes are used to prohibit recompaction. .PP The amount of compression to be expected depends on the type of file being compressed. Typical file size reduction (in percent) through compression are: Text, 38%; Pascal Source, 43%; C Source, 36%; and Binary, 19%. .PP .C uncompact restores the original file from a file compressed by .C compact. If no file names are specified, standard input is uncompacted and sent to the standard output. .PP .C ccat cats the original file from a file compressed by .C compact, without uncompressing the file. .SS "Access Control Lists (ACLs) On systems that implement access control lists, when a new file is created with the effective user and group .SM ID of the caller, the original file's .SM ACL is copied to the new file after being altered to reflect any change in ownership (see .IR acl (5)). .SH WARNINGS On short-filename systems, the last segment of the file name must contain 12 or fewer characters to allow space for the appended .CR .C . .SH DEPENDENCIES .SS \s-1NFS\s0 Access control list entries of networked files are summarized (as returned in .C st_mode by .CR stat() ), but not copied to the new file (see .IR stat (2)). .SH FILES .TP 20 .C *.C compacted file created by compact, removed by uncompact .SH SEE ALSO compress(1), pack(1), acl(5). .br Gallager, Robert G., ``Variations on a Theme of Huffman,'' .I "I.E.E.E. Transactions on Information Theory," vol. IT-24, no. 6, November 1978, pp. 668 - 674. .SH AUTHOR .C compact was developed by Colin L. Mc Master. .\" .\" index@\f4compact\f1 \- compact files using Huffman code (see \f4pack\f1(1))@@@\f3compact(1)\f1 .\" index@\f4ccat\f1 \- uncompact and cat files using Huffman code (see \f4pack\f1(1))@@@\f3compact(1)\f1 .\" index@\f4uncompact\f1 \- uncompact Huffman coded files (see \f4pack\f1(1))@@@\f3compact(1)\f1 .\" index@compact files using Huffman code (see \f4pack(1)\f1)@@@\f3compact(1)\f1 .\" index@cat after uncompacting Huffman coded files (see \f4pack(1)\f1)@@@\f3compact(1)\f1 .\" index@uncompact previously compacted Huffman coded files (see \f4pack(1)\f1)@@@\f3compact(1)\f1 .\" .\" toc@\f3compact(1)\f1:\0\0\f4compact\f1, \f4uncompact\f1, \f4ccat\f1@@@compact and uncompact files, and cat them .\" toc@\f4uncompact\f1: uncompact files@@@see \f3compact(1)\f1 .\" toc@\f4ccat\f1: cat compacted files@@@see \f3compact(1)\f1 .\" .\" links@compact.1 uncompact.1 .\" links@compact.1 ccat.1 .\" .\" fileset_database@compact.1 USER-CMDS-MAN .\" $Header: compress.1,v 76.1 95/07/10 16:56:11 ssa Exp $ .TA c .TH compress 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compress, uncompress, zcat, compressdir, uncompressdir \- compress and expand data .SH SYNOPSIS .SS Compress Files .C compress .RC [ -d ] .RC [ -f|-z ] .RC [ -z ] .RC [ -v ] .RC [ -c ] .RC [ -V ] .RC [ -b .IR maxbits \|] .RI [ \|file \0...\|] .br .C uncompress .RC [ -f ] .RC [ -v ] .RC [ -c ] .RC [ -V ] .RI [ \|file \0...\|] .br .C zcat .RC [ -V ] .RI [ \|file \0...\|] .SS Compress Entire Directory Subtrees .C compressdir .RI [ \|options\| ] .RI [ \|directory \0...\|] .br .C uncompressdir .RI [ \|options\| ] .RI [ \|directory \0...\|] .SH DESCRIPTION The following commands compress and uncompress files and directory subtrees as indicated: .RS .TP 20 .C compress Reduce the size of the named .IR file s using adaptive Lempel-Ziv coding. If reduction is possible, each .I file is replaced by a new file of the same name with the suffix .CR .Z added to indicate that it is a compressed file. Original ownership, modes, access, and modification times are preserved. If no .I file is specified, or if .CR - is specified, standard input is compressed to the standard output. .TP .C uncompress Restore the compressed .IR file s to original form. Resulting files have the original filename, ownership, and permissions, and the .CR .Z filename suffix is removed. If no .I file is specified, or if .CR - is specified, standard input is uncompressed to the standard output. .TP .C zcat Restore the compressed .IR file s to original form and send the result to standard output. If no .I file is specified, or if .CR - is specified, standard input is uncompressed to the standard output. .TP .C compressdir Front-end processor. Recursively descend each specified .I directory subtree and use .CR compress to compress each file in .IR directory . Existing files are replaced by a compressed file having the same name plus the suffix .CR .Z , provided the resulting file is smaller than the original. If no directories are specified, compression is applied to all files starting with the current directory. .IP .I options may include any valid .CR compress command options (they are passed through to .CR compress ). To force compression of all files, even when the result is larger than the original file, use the .CR -f option. .TP .C uncompressdir Opposite of .CR compressdir . Restore compressed files to their original form. .I options may include any valid .CR uncompress command options (they are passed through to .CR uncompress ). .RE .PP The amount of compression obtained depends on the size of the input, the maximum number of bits .RI ( maxbits ) per code, and the distribution of common substrings. Typically, text such as source code or English is reduced by 50-60 percent. Compression is generally much better than that achieved by Huffman coding (as used in .CR pack ), or adaptive Huffman coding .RC ( compact ), and takes less time to compute. .SS Options These commands recognize the following options in the combinations shown above in .SM SYNOPSIS: .RS .TP 20 .C -d Decompress .IR file . .CR "compress -d" is equivalent to .CR uncompress . .TP .C -f Force compression of .IR file . This is useful for compressing an entire directory, even if some of the files do not actually shrink. If .CR -f is not given and .CR compress is run in the foreground, the user is prompted as to whether an existing file should be overwritten. .TP .C -z This is the same as the .C -f option except that it does not force compression when there is null compression. .TP .C -v Print a message describing the percentage of reduction for each file compressed. .TP .C -c Force .CR compress and .CR uncompress to write to the standard output; no files are changed. The nondestructive behavior of .CR zcat is identical to that of .CR "uncompress -c" . .TP .C -V Print the current version and compile options onto the standard error. .TP .CI -b \0maxbits Specify the maximum number of bits the .CR compress algorithm will use. The default is 16 and the range can be any integer between 9 and 16. .RE .PP .C compress uses the modified Lempel-Ziv algorithm popularized in .I "A Technique for High Performance Data Compression", Terry A. Welch, .I "IEEE Computer," vol. 17, no. 6 (June 1984), pages 8-19. Common substrings in the file are first replaced by 9-bit codes 257 and up. When code 512 is reached, the algorithm switches to 10-bit codes and continues to use more bits until the limit specified by the .CR -b flag is reached (default 16). .PP After the .I maxbits limit is attained, .CR compress periodically checks the compression ratio. If it is increasing, .CR compress continues to use the existing code dictionary. However, if the compression ratio is decreasing, .CR compress discards the table of substrings and rebuilds it from scratch. This allows the algorithm to adapt to the next "block" of the file. .PP Note that the .CR -b flag is omitted for .CR uncompress since the .I maxbits parameter specified during compression is encoded within the output, along with a magic number to ensure that neither decompression of random data nor recompression of compressed data is attempted. .SS "Access Control Lists" .C compress retains a file's access control list when compressing and expanding data. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .CR compress , .CR uncompress , and .C zcat behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE These commands return the following values upon completion: .RS .TP 5 .C 0 Completed successfully. .PD 0 .TP .C 2 Last file is larger after (attempted) compression. .TP .C 1 An error occurred. .PD .RE .SH DIAGNOSTICS .TP .C "Usage: compress [-f|-z] [-dvcV] [-b maxbits] [file ...]" Invalid options were specified on the command line. .TP .C "Missing maxbits" .I maxbits must follow .CR -b . .TP .IC file ": not in compressed format" The file specified to .CR uncompress has not been compressed. .TP .IC file ": compressed with " xx "bits, can only handle " yy "bits" .I file was compressed by a program that could deal with a higher value of .I maxbits than the compress code on this machine. Recompress the file with a lower value of .IR maxbits . .TP .IC file ": already has .Z suffix -- no change" The file is assumed to be already compressed. Rename the file and try again. .TP .IC file ": filename too long to tack on .Z" The output file name, which is the source file name with a .CR .Z extension, is too long for the file system on which the source file resides. Make the source file name shorter and try again. .TP .C "file already exists; do you wish to overwrite (y or n)?" Respond .CR y if you want the output to replace the existing file; otherwise, respond .CR n . .TP .C "uncompress: corrupt input" A .CR SIGSEGV violation was detected which usually means that the input file has been corrupted. .TP .CI "Compression: " xx . xx % Percentage of the input saved by compression. (Relevant only for .CR -v .) .TP .C "-- not a regular file: unchanged" When the input file is not a regular file (a directory for example), it is left unaltered. .TP .CI "-- has " xx "other links: unchanged" The input file has links and has been left unchanged. See .IR ln (1) for more information. .TP .C "-- file unchanged" No savings is achieved by compression. The input remains unaltered. .SH EXAMPLES Compress the file named .CR zenith and print compression information to the terminal: .RS .IP .C compress -v zenith .RE .PP The terminal display shows either a line resembling .IP .C "zenith: Compression: 23.55% -- replaced with zenith.Z" .PP indicating that the compressed file is 23.55% smaller than the original, or a line resembling .IP .C "zenith: Compression: -12.04% -- file unchanged" .PP indicating that an additional 12.04% space must be used to compress the file. .PP Undo the compression by typing either of the following commands: .RS .IP .C uncompress zenith.Z .IP .C compress -d zenith.Z .RE .PP This restores file .CR zenith.Z to its original uncompressed form and name. .PP .CR uncompress will perform on standard input if no files are specified. For example, to list a compressed tar file: .RS .IP .C "uncompress -c arch.tar.Z | tar -tvf - " .RE .SH WARNINGS Although compressed files are compatible between machines with large memory, .CR -b 12 should be used for file transfer to architectures with a small process data space (64K bytes or less). .SS \s-1NFS\s0 Access control lists of networked files are summarized (as returned in .CR st_mode by .CR stat() , but not copied to the new file (see .IR stat (2)). .SH AUTHOR .C compress was developed by Joseph M. Orost, Kenneth E. Turkowski, Spencer W. Thomas, and James A. Woods. .SH FILES .TP .C *.Z Compressed file created by .CR compress and removed by .CR uncompress . .SH SEE ALSO compact(1), pack(1), acl(5). .SH STANDARDS CONFORMANCE .CR compress ": XPG4" .\" index@\f4compress\f1, \f4uncompress\f1, \f4zcat\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4uncompress\f1, \f4compress\f1, \f4zcat\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4zcat\f1, \f4compress\f1, \f4uncompress\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4compressdir\f1, \f4uncompressdir\f1 \- compress or expand files in a directory@@@\f3compress(1)\f1 .\" index@\f4uncompressdir\f1, \f4compressdir\f1 \- compress or expand files in a directory@@@\f3compress(1)\f1 .\" index@\f1compress or expand data@@@\f3compress(1)\f1 .\" index@\f1expand or compress data@@@\f3compress(1)\f1 .\" index@\f1data, expand or compress@@@\f3compress(1)\f1 .\" index@\f1files: expand compressed files in a directory@@@\f3compress(1)\f1 .\" index@\f1files: expand compressed file@@@\f3compress(1)\f1 .\" index@\f1files: compress files in a directory@@@\f3compress(1)\f1 .\" index@\f1files: compress data in a file@@@\f3compress(1)\f1 .\" index@\f1directory: expand compressed files in a directory@@@\f3compress(1)\f1 .\" index@\f1directory: compress files in a directory@@@\f3compress(1)\f1 .\" .\" toc@\f3compress(1)\f1:\0\0\f4compress\f1, \f4compressdir\f1, \f4uncompress\f1, \f4uncompressdir\f1, \f4zcat\f1@@@compress and expand data .\" toc@\f4uncompress\f1 \- expand compressed data@@@see \f3compress(1)\f1 .\" toc@\f4uncompressdir\f1 \- expand compressed files in a directory@@@see \f3compress(1)\f1 .\" toc@\f4compressdir\f1 \- compress files in a directory@@@see \f3compress(1)\f1 .\" toc@\f4zcat\f1: expand and cat data@@@see \f3compress(1)\f1 .\" .\" links@compress.1 uncompress.1 .\" links@compress.1 zcat.1 .\" links@compress.1 compressdir.1 .\" links@compress.1 uncompressd.1 .\" .\" $Header: compress.1,v 76.1 95/07/10 16:56:11 ssa Exp $ .TA c .TH compress 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compress, uncompress, zcat, compressdir, uncompressdir \- compress and expand data .SH SYNOPSIS .SS Compress Files .C compress .RC [ -d ] .RC [ -f|-z ] .RC [ -z ] .RC [ -v ] .RC [ -c ] .RC [ -V ] .RC [ -b .IR maxbits \|] .RI [ \|file \0...\|] .br .C uncompress .RC [ -f ] .RC [ -v ] .RC [ -c ] .RC [ -V ] .RI [ \|file \0...\|] .br .C zcat .RC [ -V ] .RI [ \|file \0...\|] .SS Compress Entire Directory Subtrees .C compressdir .RI [ \|options\| ] .RI [ \|directory \0...\|] .br .C uncompressdir .RI [ \|options\| ] .RI [ \|directory \0...\|] .SH DESCRIPTION The following commands compress and uncompress files and directory subtrees as indicated: .RS .TP 20 .C compress Reduce the size of the named .IR file s using adaptive Lempel-Ziv coding. If reduction is possible, each .I file is replaced by a new file of the same name with the suffix .CR .Z added to indicate that it is a compressed file. Original ownership, modes, access, and modification times are preserved. If no .I file is specified, or if .CR - is specified, standard input is compressed to the standard output. .TP .C uncompress Restore the compressed .IR file s to original form. Resulting files have the original filename, ownership, and permissions, and the .CR .Z filename suffix is removed. If no .I file is specified, or if .CR - is specified, standard input is uncompressed to the standard output. .TP .C zcat Restore the compressed .IR file s to original form and send the result to standard output. If no .I file is specified, or if .CR - is specified, standard input is uncompressed to the standard output. .TP .C compressdir Front-end processor. Recursively descend each specified .I directory subtree and use .CR compress to compress each file in .IR directory . Existing files are replaced by a compressed file having the same name plus the suffix .CR .Z , provided the resulting file is smaller than the original. If no directories are specified, compression is applied to all files starting with the current directory. .IP .I options may include any valid .CR compress command options (they are passed through to .CR compress ). To force compression of all files, even when the result is larger than the original file, use the .CR -f option. .TP .C uncompressdir Opposite of .CR compressdir . Restore compressed files to their original form. .I options may include any valid .CR uncompress command options (they are passed through to .CR uncompress ). .RE .PP The amount of compression obtained depends on the size of the input, the maximum number of bits .RI ( maxbits ) per code, and the distribution of common substrings. Typically, text such as source code or English is reduced by 50-60 percent. Compression is generally much better than that achieved by Huffman coding (as used in .CR pack ), or adaptive Huffman coding .RC ( compact ), and takes less time to compute. .SS Options These commands recognize the following options in the combinations shown above in .SM SYNOPSIS: .RS .TP 20 .C -d Decompress .IR file . .CR "compress -d" is equivalent to .CR uncompress . .TP .C -f Force compression of .IR file . This is useful for compressing an entire directory, even if some of the files do not actually shrink. If .CR -f is not given and .CR compress is run in the foreground, the user is prompted as to whether an existing file should be overwritten. .TP .C -z This is the same as the .C -f option except that it does not force compression when there is null compression. .TP .C -v Print a message describing the percentage of reduction for each file compressed. .TP .C -c Force .CR compress and .CR uncompress to write to the standard output; no files are changed. The nondestructive behavior of .CR zcat is identical to that of .CR "uncompress -c" . .TP .C -V Print the current version and compile options onto the standard error. .TP .CI -b \0maxbits Specify the maximum number of bits the .CR compress algorithm will use. The default is 16 and the range can be any integer between 9 and 16. .RE .PP .C compress uses the modified Lempel-Ziv algorithm popularized in .I "A Technique for High Performance Data Compression", Terry A. Welch, .I "IEEE Computer," vol. 17, no. 6 (June 1984), pages 8-19. Common substrings in the file are first replaced by 9-bit codes 257 and up. When code 512 is reached, the algorithm switches to 10-bit codes and continues to use more bits until the limit specified by the .CR -b flag is reached (default 16). .PP After the .I maxbits limit is attained, .CR compress periodically checks the compression ratio. If it is increasing, .CR compress continues to use the existing code dictionary. However, if the compression ratio is decreasing, .CR compress discards the table of substrings and rebuilds it from scratch. This allows the algorithm to adapt to the next "block" of the file. .PP Note that the .CR -b flag is omitted for .CR uncompress since the .I maxbits parameter specified during compression is encoded within the output, along with a magic number to ensure that neither decompression of random data nor recompression of compressed data is attempted. .SS "Access Control Lists" .C compress retains a file's access control list when compressing and expanding data. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .CR compress , .CR uncompress , and .C zcat behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE These commands return the following values upon completion: .RS .TP 5 .C 0 Completed successfully. .PD 0 .TP .C 2 Last file is larger after (attempted) compression. .TP .C 1 An error occurred. .PD .RE .SH DIAGNOSTICS .TP .C "Usage: compress [-f|-z] [-dvcV] [-b maxbits] [file ...]" Invalid options were specified on the command line. .TP .C "Missing maxbits" .I maxbits must follow .CR -b . .TP .IC file ": not in compressed format" The file specified to .CR uncompress has not been compressed. .TP .IC file ": compressed with " xx "bits, can only handle " yy "bits" .I file was compressed by a program that could deal with a higher value of .I maxbits than the compress code on this machine. Recompress the file with a lower value of .IR maxbits . .TP .IC file ": already has .Z suffix -- no change" The file is assumed to be already compressed. Rename the file and try again. .TP .IC file ": filename too long to tack on .Z" The output file name, which is the source file name with a .CR .Z extension, is too long for the file system on which the source file resides. Make the source file name shorter and try again. .TP .C "file already exists; do you wish to overwrite (y or n)?" Respond .CR y if you want the output to replace the existing file; otherwise, respond .CR n . .TP .C "uncompress: corrupt input" A .CR SIGSEGV violation was detected which usually means that the input file has been corrupted. .TP .CI "Compression: " xx . xx % Percentage of the input saved by compression. (Relevant only for .CR -v .) .TP .C "-- not a regular file: unchanged" When the input file is not a regular file (a directory for example), it is left unaltered. .TP .CI "-- has " xx "other links: unchanged" The input file has links and has been left unchanged. See .IR ln (1) for more information. .TP .C "-- file unchanged" No savings is achieved by compression. The input remains unaltered. .SH EXAMPLES Compress the file named .CR zenith and print compression information to the terminal: .RS .IP .C compress -v zenith .RE .PP The terminal display shows either a line resembling .IP .C "zenith: Compression: 23.55% -- replaced with zenith.Z" .PP indicating that the compressed file is 23.55% smaller than the original, or a line resembling .IP .C "zenith: Compression: -12.04% -- file unchanged" .PP indicating that an additional 12.04% space must be used to compress the file. .PP Undo the compression by typing either of the following commands: .RS .IP .C uncompress zenith.Z .IP .C compress -d zenith.Z .RE .PP This restores file .CR zenith.Z to its original uncompressed form and name. .PP .CR uncompress will perform on standard input if no files are specified. For example, to list a compressed tar file: .RS .IP .C "uncompress -c arch.tar.Z | tar -tvf - " .RE .SH WARNINGS Although compressed files are compatible between machines with large memory, .CR -b 12 should be used for file transfer to architectures with a small process data space (64K bytes or less). .SS \s-1NFS\s0 Access control lists of networked files are summarized (as returned in .CR st_mode by .CR stat() , but not copied to the new file (see .IR stat (2)). .SH AUTHOR .C compress was developed by Joseph M. Orost, Kenneth E. Turkowski, Spencer W. Thomas, and James A. Woods. .SH FILES .TP .C *.Z Compressed file created by .CR compress and removed by .CR uncompress . .SH SEE ALSO compact(1), pack(1), acl(5). .SH STANDARDS CONFORMANCE .CR compress ": XPG4" .\" index@\f4compress\f1, \f4uncompress\f1, \f4zcat\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4uncompress\f1, \f4compress\f1, \f4zcat\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4zcat\f1, \f4compress\f1, \f4uncompress\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4compressdir\f1, \f4uncompressdir\f1 \- compress or expand files in a directory@@@\f3compress(1)\f1 .\" index@\f4uncompressdir\f1, \f4compressdir\f1 \- compress or expand files in a directory@@@\f3compress(1)\f1 .\" index@\f1compress or expand data@@@\f3compress(1)\f1 .\" index@\f1expand or compress data@@@\f3compress(1)\f1 .\" index@\f1data, expand or compress@@@\f3compress(1)\f1 .\" index@\f1files: expand compressed files in a directory@@@\f3compress(1)\f1 .\" index@\f1files: expand compressed file@@@\f3compress(1)\f1 .\" index@\f1files: compress files in a directory@@@\f3compress(1)\f1 .\" index@\f1files: compress data in a file@@@\f3compress(1)\f1 .\" index@\f1directory: expand compressed files in a directory@@@\f3compress(1)\f1 .\" index@\f1directory: compress files in a directory@@@\f3compress(1)\f1 .\" .\" toc@\f3compress(1)\f1:\0\0\f4compress\f1, \f4compressdir\f1, \f4uncompress\f1, \f4uncompressdir\f1, \f4zcat\f1@@@compress and expand data .\" toc@\f4uncompress\f1 \- expand compressed data@@@see \f3compress(1)\f1 .\" toc@\f4uncompressdir\f1 \- expand compressed files in a directory@@@see \f3compress(1)\f1 .\" toc@\f4compressdir\f1 \- compress files in a directory@@@see \f3compress(1)\f1 .\" toc@\f4zcat\f1: expand and cat data@@@see \f3compress(1)\f1 .\" .\" links@compress.1 uncompress.1 .\" links@compress.1 zcat.1 .\" links@compress.1 compressdir.1 .\" links@compress.1 uncompressd.1 .\" .\" $Header: convert.1,v 74.2 95/05/10 21:28:07 ssa Exp $ .TA c .TH convert 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME convert \- convert an audio file .SH SYNOPSIS .C /opt/audio/bin/convert \f1[\f2source_file target_file \f3-sfmt \f2format \f3-dfmt \f2format \f3-ddata \f2data_type \f3-srate \f2rate \f3-drate \f2rate \f3-schannels \f2number \f3-dchannels \f2number\f1] .SH DESCRIPTION This command converts audio files from one supported file format, data format, sampling rate, and number of channels to another. The unconverted file is retained as a source file. .TP .CI -sfmt \0format \0-dfmt \0format are the file formats for the source and destination files. Each .I format can be one of these: .RS .TP 10 .C au Sun file format .TP .C snd NeXT file format .TP .C wav Microsoft RIFF Waveform file format .TP .C u MuLaw format .TP .C al ALaw .TP .C l16 linear 16-bit format .TP .C lo8 offset (unsigned) linear 8-bit format .TP .C l8 linear 8-bit format .RE .IP If you omit .CR "-sfmt", .C convert uses the header or filename extension in the source file. You can omit .C -dfmt if you supply a filename extension for the destination file. .TP .CI -ddata \0data_type is the data type for the destination files. .I data_type can be one of these: .RS .TP .C u MuLaw .TP .C al ALaw .TP .C l16 linear 16-bit .TP .C lo8 offset (unsigned) linear 8-bit data .TP .C l8 linear 8-bit data .RE .IP If you omit .CR "-ddata", .C convert uses an appropriate data type, normally the data type of the source file. .TP .CI -srate \0rate \0-drate \0rate are the number of samples per second for the source and destination file. Typical sampling rates range from 8 to 11k (for voice quality) to 44,100 (for CD quality). You can use .C k to indicate thousands. For example, .C 8k means 8,000 samples per second. .IP If you omit .CR "-srate", .C convert uses a rate defined by the source file header or its filename extension. For a raw file with no extension, 8,000 is used. By playing the file, you can determine if 8,000 samples is too fast or too slow. .IP If you omit .CR "-drate", .C convert uses a sampling rate appropriate for the destination file format; if possible, it matches the sampling rate of the source file. .TP .CI -schannels \0number \0-dchannels \0number are the number of channels in the source and destination files. Use .C 1 for mono; .C 2 for stereo. If .C -schannels is omitted, .C convert uses the information in the header; for raw data files, it uses mono. .IP If .C -dchannels is omitted, .C convert matches what was used for the source file (through the header or .C -schannels option); for raw data files, it uses mono. .RE .SH EXAMPLES Convert a raw data file to a headered file. .IP .C cd /opt/audio/bin .br .C "convert beep.l16 beep.au" .PP Convert a raw data file to a headered file when the source has no extension, was sampled at 11,025 per second, and has stereo data. .IP .C cd /opt/audio/bin .br .C "convert beep beep.au -sfmt l16 -srate 11025 -schannels 2" .PP To save disk space, convert an audio file with CD quality sound to voice quality sound. .IP .C cd /opt/audio/bin .br .C "convert idea.au idea2.au -ddata u -drate 8k -dchannels 1" .SH AUTHOR .C convert was developed by .SM HP. .sp Sun is a trademark of Sun MicroSystems, Inc. .br NeXT is a trademark of NeXT Computers, Inc. .br Microsoft is a trademark of Microsoft Corporation. .SH SEE ALSO audio(5), asecure(1m), aserver(1m), attributes(1), send_sound(1). .PP .IR "Using the Audio Developer's Kit" .\" .\" index@\f4convert\f1 \- convert audio file@@@\f3convert(1)\f1 .\" index@\f1audio file, convert@@@\f3convert(1)\f1 .\" toc@\f3convert(1)\f1:\0\0\f4convert\f1@@@convert audio file .\" $Header: cp.1,v 76.2 95/08/01 16:22:43 ssa Exp $ .TA c .TH cp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cp \- copy files and directory subtrees .SH SYNOPSIS .C cp .RC [ -f \(or -i ] .RC [ -p ] .RC [ -e .I extarg ] .I file1 .I new_file .br .C cp .RC [ -f \(or -i ] .RC [ -p ] .RC [ -e .I extarg ] .I file1 .RI [ file2 \0...\|] .I dest_directory .br .C cp .RC [ -f \(or -i ] .RC [ -p ] .RC [ -R \(or -r ] .RC [ -e .I extarg ] .IR directory1\0 [ \|directory2\0 ...\|] .I dest_directory .SH DESCRIPTION .C cp copies: .RS .PP .PD 0 .TP 3 \(bu .I file1 to new or existing .IR new_file , .TP \(bu .I file1 to existing .IR dest_directory , .TP \(bu .IR file1 , .IR file2 ,\0... to existing .IR dest_directory , .TP \(bu directory subtree .IR directory1 , to new or existing .IR dest_directory . or .TP \(bu multiple directory subtrees .IR directory1 , .IR directory2 ,\0... to new or existing .IR dest_directory . .RE .PD .PP .C cp fails if .I file1 and .I new_file are the same (be cautious when using shell metacharacters). When destination is a directory, one or more files are copied into that directory. If two or more files are copied, the destination must be a directory. When copying a single file to a new file, if .I new_file exists, its contents are destroyed. .PP If the access permissions of the destination .I dest_directory or existing destination file .I new_file forbid writing, .C cp aborts and produces an error message ``cannot create .IR file ''. .PP To copy one or more directory subtrees to another directory, the .C -r option is required. The .C -r option is ignored if used when copying a file to another file or files to a directory. .PP If .I new_file is a link to an existing file with other links, .C cp overwrites the existing file and retains all links. If copying a file to an existing file, .C cp does not change existing file access permission bits, owner, or group. .PP When copying files to a directory or to a new file that does not already exist, .C cp creates a new file with the same file permission bits as .IR file1 , modified by the file creation mask of the user if the .C -p option was not specified, and then bitwise inclusively ORed with S_IRWXU. The owner and group of the new file or files are those of the user. The last modification time of .I new_file (and last access time, if .I new_file did not exist) and the last access time of the source .I file1 are set to the time the copy was made. .SS Options .TP 8 .C -i (interactive copy) Cause .C cp to write a prompt to standard error and wait for a response before copying a file that would overwrite an existing file. If the response from the standard input is affirmative, the file is copied if permissions allow the copy. If the .C -i (interactive) and .C -f (forced-copy) options are both specified, the .C -i option is ignored. .TP .C -f Force existing destination pathnames to be removed before copying, without prompting for confirmation. This option has the effect of destroying and replacing any existing file whose name and directory location conflicts with the name and location of the new file created by the copy operation. .TP .C -p (preserve permissions) Causes .C cp to preserve in the copy as many of the modification time, access time, file mode, user ID, and group ID as allowed by permissions. .TP .C -r (recursive subtree copy) Cause .C cp to copy the subtree rooted at each source directory to .IR dest_directory . If .I dest_directory exists, it must be a directory, in which case .C cp creates a directory within .I dest_directory with the same name as .I file1 and copies the subtree rooted at .I file1 to .IR dest_directory/file1 . An error occurs if .I dest_directory/file1 already exists. If .I dest_directory does not exist, .C cp creates it and copies the subtree rooted at .I file1 to .IR dest_directory . Note that .C cp -r cannot merge subtrees. .IP Usually normal files and directories are copied. Character special devices, block special devices, network special files, named pipes, symbolic links, and sockets are copied, if the user has access to the file; otherwise, a warning is printed stating that the file cannot be created, and the file is skipped. .IP .I dest_directory should not reside within .IR directory1 , nor should .I directory1 have a cyclic directory structure, since in both cases .C cp attempts to copy an infinite amount of data. .TP .C -R (recursive subtree copy) The .C -R option is identical to the .C -r option with the exception that directories copied by the .C -R option are created with read, write, and search permission for the owner. User and group permissions remain unchanged. .IP With the .C -R and .C -r options, in addition to regular files and directories, .C cp also copies FIFOs, character and block device files and symbolic links. Only superusers can copy device files. All other users get an error. Symbolic links are copied so the target points to the same location that the source did. .IP Warning: While copying a directory tree that has device special files, use the .CR -r option; otherwise, an infinite amount of data is read from the device special file and is duplicated as a special file in the destination directory occupying large file system space. .TP .CI -e \0extarg Specifies the handling of any extent attributes of the file[s] to be copied. .I extarg takes one of the following values. .RS .RS .TP 10 .PD0 .C warn Issues a warning message if extent attributes cannot be copied, but copies the file anyway. .TP .C ignore Does not copy the extent attributes. .TP .C force Fails to copy the file if the extent attribute can not be copied. .sp .PD .RE Extent attributes can not be copied if the files are being copied to a file system which does not support extent attributes or if that file system has a different block size than the original. If .C -e is not specified, the default value for .I extarg is .C warn. .RE .SS "Access Control Lists (ACLs)" .PP If .I new_file is a new file, or if a new file is created in .IR dest_directory , it inherits the access control list of the original .IR file1 , .IR file2 , etc., altered to reflect any difference in ownership between the two files (see .IR acl (5)). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text as single and/or multi-byte characters. .PP .C LANG and .C LC_CTYPE determine the local language equivalent of y (for yes/no queries). .PP .C LANG determines the language in which messages are displayed. .PP If .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG. If any internationalization variable contains an invalid setting, .C cp behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .br .ne 6 .SH EXAMPLES The following command moves the directory .I sourcedir and its contents to a new location .RI ( targetdir ) in the file system. Since .C cp creates the new directory, the destination directory .I targetdir should not already exist. .IP .CI "cp -r" " sourcedir targetdir " "&& rm -rf" " sourcedir" .PP The .C -r option copies the subtree (files and subdirectories) in directory .I sourcedir to directory .IR targetdir . The double ampersand .RB ( && ) causes a conditional action. If the operation on the left side of the .B && is successful, the right side is executed (and removes the old directory). If the operation on the left of the .B && is not successful, the old directory is not removed. .PP This example is equivalent to: .IP .CI mv " sourcedir targetdir" .PP To copy all files and directory subtrees in the current directory to an existing .IR targetdir , use: .IP .CI "cp -r * " targetdir .PP To copy all files and directory subtrees in .I sourcedir to .IR targetdir , use: .IP .CI "cp -r" " sourcedir" /* " targetdir" .PP Note that directory pathnames can precede both .I sourcedir and .IR targetdir . .PP To create a zero-length file, use any of the following: .IP .CI "cat /dev/null >" file .br .CI "cp /dev/null " file .br .CI touch \0file .SH DEPENDENCIES .SS NFS Access control lists of networked files are summarized (as returned in .C st_mode by .CR stat() ), but not copied to the new file. When using .C mv or .C ln on such files, a .C + is not printed after the mode value when asking for permission to overwrite a file. .SH AUTHOR .C cp was developed by AT&T, the University of California, Berkeley, and HP. .SH SEE ALSO cpio(1), ln(1), mv(1), rm(1), link(1M), lstat(2), readlink(2), stat(2), symlink(2), symlink(4), acl(5). .SH STANDARDS CONFORMANCE .CR cp ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4cp\f1 \- copy file, files, or directory subtree@@@\f3cp(1)\f1 .\" index@\f1copy file to a new or existing file@@@\f3cp(1)\f1 .\" index@\f1overwrite file with an existing file@@@\f3cp(1)\f1 .\" index@\f1copy multiple files to a directory@@@\f3cp(1)\f1 .\" index@\f1files: copy file to a new or existing file@@@\f3cp(1)\f1 .\" index@\f1files: overwrite file with an existing file@@@\f3cp(1)\f1 .\" index@\f1files: copy multiple files to a directory@@@\f3cp(1)\f1 .\" index@\f1files: copy directory subtree and files to another directory@@@\f3cp(1)\f1 .\" index@\f1directory: copy multiple files to a directory@@@\f3cp(1)\f1 .\" index@\f1directory: copy directory subtree and files to another directory@@@\f3cp(1)\f1 .\" index@\f1file: create zero-length file@@@\f3cp(1)\f1 .\" index@\f1create zero-length file@@@\f3cp(1)\f1 .\" index@\f1zero-length file, create@@@\f3cp(1)\f1 .\" .\" toc@\f3cp(1)\f1:\0\0\f4cp\f1@@@copy file, files, or directory subtree .\" .\" fileset_database@cp.1 USER-CMDS-MAN .\" $Header: cpio.1,v 78.1 96/01/22 22:18:46 ssa Exp $ .TA c .TH cpio 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cpio \- copy file archives in and out; duplicate directory trees .SH SYNOPSIS .CR "cpio\ -o" .RC [ -e .I extarg ] .RC [ achvxABC ]\| .PP .CR "cpio\ -i" [ bcdfmrstuvxBPRSU6 ]\| .RI \|[ pattern ...]\| .PP .CR "cpio\ -p" .RC [ -e .I extarg ] .RC [ adlmruvxU ]\| .I directory .SH DESCRIPTION The .CR cpio command saves and restores archives of files on magnetic tape, other devices, or a regular file, and copies files from one directory to another while replicating the directory tree structure. .TP 12 .CR "cpio\ -o" (copy out, export)\0 Read standard input to obtain a list of path names, and copy those files to standard output together with path name and status information. The output is padded to a 512-byte boundary. .TP .CR "cpio\ -i" (copy in, import)\0 Extract files from standard input, which is assumed to be the result of a previous .CR "cpio\ -o" . .IP If .IR pattern ..., is specified, only the files with names that match a .IR pattern according to the rules of Pattern Matching Notation (see .IR regexp (5)) are selected. A leading .CR ! on a pattern indicates that only those names that do .I not match the remainder of the pattern should be selected. Multiple patterns can be specified. The patterns are additive. If no .I pattern is specified, the default is .CR * (select all files). See the .CR f option, as well. .IP Extracted files are conditionally created and copied into the current directory tree, as determined by the options described below. The permissions of the files match the permissions of the original files when the archive was created by .CR "cpio\ -o" unless the .CR U option is used. File owner and group are that of the current user unless the user has appropriate privileges, in which case .CR cpio retains the owner and group of the files of the previous .CR "cpio\ -o" . .TP .CR "cpio\ -p" (passthrough)\0 Read standard input to obtain a list of path names of files which are then conditionally created and copied into the destination .IR directory tree as determined by the options described below. .IR directory must exist. Destination path names are interpreted relative to .IR directory . .SS Options .CR cpio recognizes the following options, which can be appended as appropriate to .CR -i , .CR -o , and .CR -p . Whitespace and hyphens are not permitted between these options and .CR -i , .CR -o , or .CR -p . .RS .TP 8 .CR a Reset access times of input files after they are copied. .TP .CR b Swap both bytes and half-words. Use only with .CR -i . See the .CR P option for details; see also the .CR s and .CR S options. .TP .CR c Write or read header information in .SM ASCII character form for portability. .TP .CR d Create directories as needed. .TP .CI -e \0extarg Specifies the handling of any extent attributes of the file(s) to be archived or copied. .I extarg takes one of the following values. .RS .RS .TP 10 .PD0 .C warn Archive or copy the file and issue a warning message if extent attributes cannot be preserved. .TP .C ignore Do not issue a warning message even if extent attributes cannot be preserved. .TP .C force Any file(s) with extent attributes will not be archived and a warning message will be issued. .sp .PD .RE When using the .CR -o option, extent attributes are not preserved in the archive. Furthermore, the .C -p option will not preserve extent attributes if the files are being copied to a file system that does not support extent attributes. If .C -e is not specified, the default value for .I extarg is .C warn. .RE .TP .CR f Copy in all files except those selected by .IR pattern .... .TP .CR h Follow symbolic links as though they were normal files or directories. Normally, .CR cpio archives the link. .TP .CR l Whenever possible, link files rather than copying them. This option does not destroy existing files. Use only with .CR -p . .TP .CR m Retain previous file modification time. This option does not affect directories that are being copied. .TP .CR r Rename files interactively. If the user types a null line, the file is skipped. .TP .CR s Swap all bytes of the file. Use only with .CR -i . See the .CR P option for details; see also the .CR s and .CR S options. .TP .CR t Print only a table of contents of the input. No files are created, read, or copied. .TP .CR u Copy unconditionally (normally, an older file does not replace a newer file with the same name). .TP .CR v Print a list of file names as they are processed. When used with the .CR t option, the table of contents has the format: .IP .IR numeric-mode\0owner-name\0blocks\0date-time\0filename .IP where .IR numeric-mode is the file privileges in numeric format, .IR owner-name is the name of the file owner, .IR blocks is the size of the file in 512-byte blocks, .IR date-time is the date and time the file was last modified, and .IR filename is the path name of the file as recorded in the archive. .TP .CR x Save or restore device special files. Since .CR mknod() is used to recreate these files on a restore, .CR -ix and .CR -px can be used only by users with appropriate privileges (see .IR mknod (2)). This option is intended for intrasystem (backup) use only. Restoring device files from previous versions of the OS, or from different systems can be very dangerous. .CR cpio may prevent the restoration of certain device files from the archive. .TP .CR A Suppress warning messages regarding optional access control list entries. .CR cpio does not back up optional access control list entries in a file's access control list (see .IR acl (5)). Normally, a warning message is printed for each file that has optional access control list entries. .TP .CR B Block input/output at 5120 bytes to the record (does not apply to .CR "cpio\ -p" ). This option is meaningful only with data directed to or from devices that support variable-length records such as magnetic tape. .TP .CR C Have .CR cpio checkpoint itself at the start of each volume. If .CR cpio is writing to a streaming tape drive with immediate-report mode enabled and a write error occurs, it normally aborts and exits with return code .CR 2 . With this option specified, .CR cpio instead automatically restarts itself from the checkpoint and rewrites the current volume. Alternatively, if .CR cpio is not writing to such a device and a write error occurs, .CR cpio normally continues with the next volume. With this option specified, however, the user can choose to either ignore the error or rewrite the current volume. .TP .CR P Read a file written on a .SM PDP-11 or .SM VAX system (with byte-swapping) that did not use the .CR c option. Use only with .CR -i . Files copied in this mode are not changed. Non-\c .SM ASCII files are likely to need further processing to be readable. This processing often requires knowledge of file contents, and thus cannot always be done by this program. The .CR b , .CR s , and .CR S options can be used when swapping all the bytes on the tape (rather than just in the headers) is appropriate. In general, text is best processed with .CR P and binary data with one of the other options. .IP (\c .SM PDP-11 and .SM VAX are registered trademarks of Digital Equipment Corporation.) .TP .CR R Resynchronize automatically when .CR cpio goes "out of phase", (see .SM DIAGNOSTICS\s0). .TP .CR S Swap all half-words in the file. Use only with .CR -i . See the .CR P option for details; see also the .CR b and .CR s options. .TP .CR U Use the process's file-mode creation mask (see .IR umask (2)) to modify the mode of files created, in the same manner as .IR creat (2). .TP .CR 6 Process a .SM UNIX Sixth-Edition-format file. Use only with .CR -i . .RE .PP Note that .CR cpio archives created using a raw device file must be read using a raw device file. .PP When the end of the tape is reached, .CR cpio prompts the user for a new special file and continues. .PP If you want to pass one or more metacharacters to .CR cpio without the shell expanding them, be sure to precede each of them with a backslash .RC ( \e ). .PP Device files written with the .CR -ox option (such as .CR /dev/tty03 ) do not transport to other implementations of .SM HP-UX. .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. .PP .CR LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, and the characters matched by character class expressions in pattern matching notation. .PP .CR LC_TIME determines the format and content of date and time strings output when listing the contents of an archive with the .CR v option. .PP .CR LANG determines the language in which messages are displayed. .PP If .CR LC_COLLATE , .CR LC_CTYPE , or .CR LC_TIME is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR cpio behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .CR cpio returns the following exit codes: .RS .TP .CR 0 Successful completion. Review standard error for files that could not be transferred. .TP .CR 1 Error during resynchronization. Some files may not have been recovered. .TP .CR 2 Out-of-phase error. A file header is corrupt or in the wrong format. .SH DIAGNOSTICS .PP .CR "Out of phase--get help" .br .tr ~" .CR "Perhaps the ~c~ option should" [ "n't" ] " be used" .br .tr ~~ .IP .CR "cpio\ -i" could not read the header of an archived file. The header is corrupt or it was written in a different format. Without the .CR R option, .CR cpio returns an exit code of .CR 2 . .IP If no file name has been displayed yet, the problem may be the format. Try specifying a different header format option: null for standard format; .CR c for .SM ASCII\s0; .CR b , .CR s , .CR P , or .CR S , for one of the byte-swapping formats; or .CR 6 for .SM UNIX Sixth Edition. .IP Otherwise, a header may be corrupt. Use the .CR R option to have .CR cpio attempt to resynchronize the file automatically. Resynchronizing means that .CR cpio tries to find the next good header in the archive file and continues processing from there. If .CR cpio tries to resynchronize from being out of phase, it returns an exit code of .CR 1 . .PP Other diagnostic messages are self-explanatory. .SH EXAMPLES .PP Copy the contents of a directory into a tape archive: .IP .C "ls | cpio -o > /dev/rmt/c0t0d0BEST" .PP Duplicate a directory hierarchy: .IP .C "cd olddir" .br .CI "find . -depth -print | cpio -pd " newdir .RE .PP The trivial case .IP .CR "find . -depth -print | cpio -oB >/dev/rmt/c0t0d0BEST" .PP can be handled more efficiently by: .IP .C find . -cpio /dev/rmt/c0t0d0BEST .SH WARNINGS .PP Because of industry standards and interoperability goals, .CR cpio does not support the archival of files larger than 2GB or files that have user/group IDs greater than 60K. Files with user/group IDs greater than 60K are archived and restored under the user/group ID of the current process. .PP Do not redirect the output of .CR cpio to a named .CR cpio archive file residing in the same directory as the original files belonging to that .CR cpio archive. This can cause loss of data. .PP .CR cpio strips any leading .CR ./ characters in the list of filenames piped to it. .PP Path names are restricted to .CR PATH_MAX characters (see .CR and .IR limits (5)). If there are too many unique linked files, the program runs out of memory to keep track of them. Thereafter, linking information is lost. Only users with appropriate privileges can copy special files. .PP .CR cpio tapes written on .SM HP machines with the .CR -ox [ c ] options can sometimes mislead (non-\c .SM HP\c ) versions of .CR cpio that do not support the .CR x option. If a non-\c .SM HP (or non-\c .SM AT&T\c ) version of .CR cpio happens to be modified so that the (\c .SM HP\c ) .CR cpio recognizes it as a device special file, a spurious device file might be created. .PP If .CR /dev/tty is not accessible, .CR cpio issues a complaint and exits. .PP The .CR -pd option does not create the directory typed on the command line. .PP The .CR -idr option does not make empty directories. .PP The .CR -plu option does not link files to existing files. .PP .SM POSIX defines a file named .CR TRAILER!!! as an end-of-archive marker. Consequently, if a file of that name is contained in a group of files being written by .CR "cpio\ -o" , the file is interpreted as end-of-archive, and no remaining files are copied. The recommended practice is to avoid naming files anything that resembles an end-of-archive file name. .PP To create a .SM POSIX\c -conforming .CR cpio archive, the .CR c option must be used. To read a .SM POSIX\c -conforming .CR cpio archive, the .CR c option must be used and the .CR b , .CR s , .CR S , and .CR 6 options should not be used. If the user does not have appropriate privileges, the .CR U option must also be used to get .SM POSIX\c -conforming behavior when reading an archive. Users with appropriate privileges should not use this option to get .SM POSIX\c -conforming behavior. .SS Using Cartridge Tape Drives For an explanation of the constraints on cartridge tapes, see .IR ct (7). .PP Using .CR cpio to write directly to a cartridge tape unit can severely damage the tape drive in a short amount of time, and is therefore strongly discouraged. The recommended method of writing to the cartridge tape unit is to use the .CR tcio command (see .IR tcio (1)) in conjunction with .CR cpio (note that the .CR B option must not be used by .CR cpio when .CR tcio is used). .CR tcio buffers data into larger pieces suitable for cartridge tapes. The .CR B option must be used when writing directly (that is, without using .CR tcio ) to a CS/80 cartridge tape unit. .SH DEPENDENCIES If the path given to .C cpio contains a symbolic link as the last element, this link is traversed and pathname resolution continues. .C cpio uses the symbolic link's target, rather than that of the link. .SH SEE ALSO ar(1), find(1), tar(1), tcio(1),\" STD cpio(4), acl(5), environ(5), lang(5), regexp(5). .SH STANDARDS CONFORMANCE .CR cpio ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4cpio\f1 \- copy file archives in and out@@@\f3cpio(1)\f1 .\" index@copy file archives in and out@@@\f3cpio(1)\f1 .\" index@files: copy file archives in and out@@@\f3cpio(1)\f1 .\" index@archives, copy file archives in and out@@@\f3cpio(1)\f1 .\" .\" toc@\f3cpio(1)\f1:\0\0\f4cpio\f1@@@copy file archives in and out .\" .\" $Header: cpp.1,v 76.1 95/06/29 11:59:00 ssa Exp $ .TA c .TH cpp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .tr %" \" % stands for " throughout this page. .SH NAME cpp \- the C language preprocessor .SH SYNOPSIS .CR /usr/ccs/lbin/cpp .RI \|[ option \0...]\0[ ifile .RI \|[ ofile ]\|] .SH DESCRIPTION .CR cpp is the C language preprocessor which is invoked as the first pass of any C compilation using the .CR cc command (see .IR cc (1)). Its purpose is to process .CR #include and conditional compilation instructions and macros. Thus the output of .CR cpp is designed to be in a form acceptable as input to the next pass of the C compiler. As the C language evolves, .CR cpp and the rest of the C compilation package will be modified to follow these changes. Therefore, the use of .CR cpp in other than this framework is not suggested. The preferred way to invoke .CR cpp is through the .CR cc command, since the functionality of .CR cpp may someday be moved elsewhere. See .IR m4 (1) for a general macro processor. .PP .CR cpp optionally accepts two file names as arguments. .I ifile and .I ofile are respectively the input and output for the preprocessor. They default to standard input and standard output if not specified. .SS Options The following options are recognized by .CR cpp : .TP 15 .CR -A Remove all predefined symbols that begin with a letter and .CR _HPUX_SOURCE . The user is expected to define .CR _POSIX_SOURCE or .CR _XOPEN_SOURCE when using this option. .TP .CR -C By default, .CR cpp strips C-style comments. If the .CR -C option is specified, all comments (except those found on .CR cpp directive lines) are passed along. .TP .PD 0 .CI -D name .TP .CI -D name = def Define .I name as if by a .CR #define directive. If no .CI = def is given, .I name is defined as .CR 1 . The .CR -D option has lower precedence than the .CR -U option. Thus, if the same name is used in both a .CR -U option and a .CR -D option, the name is undefined regardless of the order of the options. .PD .TP .CI -H nnn Change the internal macro definition table to be .I nnn bytes in size. The default buffer size is at least 8\|188 bytes. This option serves to eliminate ``Macro param too large'', ``Macro invocation too large'', ``Macro param too large after substitution'', ``Quoted macro param too large'', ``Macro buffer too small'', ``Input line too long'', and ``Catenated input line too long'' errors. .TP .C -h[\|\f2inclfile\fP\|] Generates included files and sents the results to the file .IR inclfile. If the argument .I inclfile is omitted, the result is sent to the standard error. .TP .CI -I dir Change the algorithm for searching for .CR #include files whose names do not begin with .CR / to look in .I dir before looking in the directories on the standard list. Thus, .CR #include files whose names are enclosed in double quotes .RC ( %% ) \" %->" are searched for first in the directory of the file containing the .CR #include line, then in directories named in .CR -I options in left-to-right order, and last in directories on a standard list. For .CR #include files whose names are enclosed in angle brackets .RC ( <> ), the directory of the file containing the .CR #include line is not searched. However, directory .I dir is still searched. .TP .C -M[\|\f2makefile\fP\|] Generates makefile dependencies and sends the results to the file .IR makefile. If the argument .I makefile is omitted, the result is sent to the standard error. .TP .CR -P Preprocess the input without producing the line-control information used by the next pass of the C compiler. .TP .CR -T .SM HP-UX no longer restricts preprocessor symbols to eight characters. The .CR -T option forces .CR cpp to use only the first eight characters for distinguishing different preprocessor names. This behavior is the same as preprocessors on some other systems with respect to the length of names, and is included for backward compatibility. .TP .CI -U name Remove any initial definition of .IR name , where .I name is a reserved symbol that is predefined by the particular preprocessor. The current list of these symbols includes: .RS .\" EDITORS PLEASE NOTE: The following formatting is designed to place .\" each name in a 15-space block with required .\" trailing spaces (except for _WSIO and _SIO, .\" which are shorter to conserve a output line). .\" The .TPs are different for nroff and troff .\" to improve the nroff output. .ift .na .ift .TP 23 .ifn .TP 23 Operating system: .CR "unix\|\ \ \ \ \ \ \ \ \ \ " .CR "_\|_unix\ \ \ \ \ \ \ " .ift .TP .ifn .TP 11 Hardware: .CR "hp9000s200\|\ \ \ \ " .CR "hp9000s300\|\ \ \ \ " .CR "_\|_hp9000s300\ \ " .CR "hp9000s500\|\ \ \ \ " .CR "hp9000s800\|\ \ \ \ " .CR "_\|_hp9000s800\ \ " .CR "hp9000ipc\|\ \ \ \ \ " .CR "hppa\|\ \ \ \ \ \ \ \ \ \ " .CR "_\|_hppa\ \ \ \ \ \ \ \ " .CR "_PA_RISC1_0\|\ \ \ " .CR "_PA_RISC1_1\|\ \ \ " .CR "_SIO\|\ \ \ \ " .CR "_WSIO" .ift .TP .ifn .TP 23 \s-1UNIX\s+1 systems variant: .CR "hpux\|\ \ \ \ \ \ \ \ \ \ " .CR "_\|_hpux\ \ \ \ \ \ \ \ " .CR "_HPUX_SOURCE\|\ \ " .CR "PWB\|\ \ \ \ \ \ \ \ \ \ \ " .CR "_PWB\|\ \ \ \ \ \ \ \ \ \ " .ift .TP .ifn .TP 11 .IR lint (1): .CR "lint\|\ \ \ \ \ \ \ \ \ \ " .CR "_\|_lint\ \ \ \ \ \ \ \ " .RE .ift .ad .IP In addition, all symbols that begin with an underscore and either an upper-case letter or another underscore are reserved. Other symbols may be defined by the .CR CCOPTS variable or other command-line options to the C compiler at compile time (see .IR cc (1)). All .SM HP-UX systems have the symbols .CR PWB , .CR hpux , .CR unix , .CR _PWB, .CR _\|_hpux , and .CR _\|_unix defined. Each system defines at least one hardware variant, as appropriate. The lint symbols are defined when .IR lint (1) is running. See .SM DEPENDENCIES. .PP Two special names are understood by .CR cpp . .CR _\|_LINE_\|_ is defined as the current line number (as a decimal integer) as counted by .CR cpp . .CR _\|_FILE_\|_ is defined as the current file name (as a C string) as known by .CR cpp . They can be used anywhere (including in macros) just as any other defined names. .SS Directives All .CR cpp directives start with lines begun by .CR # . Any number of blanks and tabs are allowed between the .CR # and the directive. The directives are: .PP .CI #define \0name\0token-string .IP "" 15 Replace subsequent instances of .I name with .IR token-string . .IR token-string can be null. .PP .CI #define \0name ( arg , \0...\c .CI , \0arg ) \0token-string .IP "" 15 Replace subsequent instances of .I name followed by a .CR ( , a list of comma-separated set of arguments, and a .CR ) by .IR token-string , where each occurrence of an .I arg in the .I token-string is replaced by the corresponding set of tokens in the comma-separated list. When a macro with arguments is expanded, the arguments are placed into the expanded .I token-string unchanged. After the entire .I token-string has been expanded, .CR cpp restarts its scan for names to expand at the beginning of the newly created .IR token-string . .IP Notice that there can be no space between .I name and the .CR ( . .PP .CR #endif \0[\f2text\fP] .IP "" 15 Ends a section of lines begun by a test directive .RC ( #if , .CR #ifdef , or .CR #ifndef ). Each test directive must have a matching .CR #endif . Any .I text occurring on the same line as the .CR #endif is ignored and thus may be used to mark matching .CR #if \(mi #endif pairs. This makes it easier, when reading the source, to match .CR #if , .CR #ifdef , and .CR #ifndef directives with their associated .CR #endif directive. .PP .CI #elif \0constant-expression .RS 15 .TP 15 Equivalent to: .CR #else .br .CI #if \0constant-expression .RE .PP .CR #else .IP "" 15 Reverses the notion of the test directive that matches this directive. Thus, if lines previous to this directive are ignored, the following lines appear in the output, and vice versa. .PP .CI #if \0constant-expression .IP "" 15 The lines following appear in the output if and only if the .I constant-expression evaluates to nonzero. All binary nonassignment C operators, the .CR ?: operator, the unary .CR - , .CR ! , and .CR ~ operators are all legal in .IR constant-expression . The precedence of the operators is the same as defined by the C language. .IP There is also a unary operator, .CR defined , which can be used in .I constant-expression in these two forms: .CI defined( name ) or .CI defined \0name\f1. This allows the use of .CR #ifdef and .CR #ifndef in an .CR #if directive. .IP Only these operators, integer constants, and names that are known by .CR cpp should be used in .IR constant-expression . In particular, the .CR sizeof operator is not available. .PP .CI #ifdef \0name .IP "" 15 The lines following appear in the output if and only if .I name has been the subject of a previous .CR #define without being the subject of an intervening .CR #undef . .PP .CI #ifndef \0name .IP "" 15 The lines following do not appear in the output if and only if .I name has been the subject of a previous .CR #define without being the subject of an intervening .CR #undef . .PP .CI "#include %" filename % \" %->" .br .CI "#include <" filename > .IP "" 15 Include at this point the contents of .I filename (which are then run through .CR cpp ). See the .CR -I option above for more detail. .PP .CI #line \0integer-constant\0 % filename % \" %->" .IP "" 15 Causes .CR cpp to generate line-control information for the next pass of the C compiler. .I integer-constant is the line number of the next line and .I filename is the file where it comes from. If .IR filename and the quotation marks are omitted, the current file name is unchanged. .PP .CI #undef " name" .IP "" 15 Cause the definition of .I name (if any) to be forgotten from now on. .PP The test directives and the possible .CR #else directives can be nested. .CR cpp supports names up to 255 characters in length. .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_CTYPE determines the interpretation of comments and string literals as single- or multibyte characters. .PP .CR LANG determines the language in which messages are displayed. .PP If .CR LC_CTYPE is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, it defaults to "C" (see .IR lang (5)). If any internationalization variable contains an invalid setting, .CR cpp behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH DIAGNOSTICS Error messages produced by .CR cpp are intended to be self-explanatory. The line number and filename where the error occurred are printed along with the diagnostic. .SH WARNINGS When newline characters were found in argument lists for macros to be expanded, previous versions of .CR cpp put out the newlines as they were found and expanded. The current version of .CR cpp replaces these newlines with blanks to alleviate problems that the previous versions had when this occurred. .SH DEPENDENCIES .SS Series 700 The symbols .CR hp9000s700 and .CR _\|_hp9000s700 are not reserved symbols recognized by the .CR -U option. They are supplied to .CR cpp either automatically by the compiler, or by the use of a compiler option. For example, on a Series 700 system, the command: .IP .C cc -v t.c .PP produces: .nf .IP .CR "/usr/ccs/lbin/cpp t.c /var/tmp/ctmAAAa29220 -D__hp9000s700 -D__hp9000s800 \&" ... .fi .PP (Also see the .CR -D option of the .CR cc command.) .SH FILES .TP 20 .CR /usr/include Standard directory for .CR #include files .SH SEE ALSO cc(1), m4(1). .SH NOTES The macro substitution scheme has been changed. Previous versions of .C cpp saved macros in a macro definition table whose table size is 128\|000 bytes by default. The current version of .C cpp replaces this macro definition table with several small buffers. The default size of the small buffers is 8\|188 bytes. .SH STANDARDS CONFORMANCE .CR cpp ": SVID2, SVID3, XPG2" .tr %% \" reset % definition .\" .\" index@\f4cpp\fP \- the C language preprocessor@@@\f3cpp(1)\f1 .\" index@C language preprocessor@@@\f3cpp(1)\f1 .\" index@C language, process \f4include\f1 and conditional instructions@@@\f3cpp(1)\f1 .\" index@language: C language preprocessor@@@\f3cpp(1)\f1 .\" index@preprocessor, C language@@@\f3cpp(1)\f1 .\" index@process C language \f4include\f1 and conditional instructions@@@\f3cpp(1)\f1 .\" index@\f4include\f1 and conditional instructions, process C language@@@\f3cpp(1)\f1 .\" .\" toc@\f3cpp(1)\f1:\0\0\f4cpp\fP@@@the C language preprocessor .\" .\" fileset_database@cpp.1 USER-CMDS-MAN .\" $Header: crontab.1,v 78.1 96/04/05 11:19:06 ssa Exp $ .TA c .TH crontab 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crontab \- user job file scheduler .SH SYNOPSIS .CR crontab .RI \|[ file ]\| .PP .CR "crontab -e" .PP .CR "crontab -l" .PP .CR "crontab -r" .SH DESCRIPTION The .CR crontab command manages a crontab file for the user. You can use a crontab file to schedule jobs that are executed automatically by .CR cron (see .IR cron (1M)) on a regular basis. The command has four forms: .RS .TP 18 .CR "crontab " \|[\f2file\fP] Create or replace your crontab file by copying the specified .IR file , or standard input if .IR file is omitted or - is specified as .IR file , into the crontab directory, .CR /var/spool/cron/crontabs . The name of your crontab file in the crontab directory is the same as your effective user name. .TP .CR "crontab -e" Edit a copy of your crontab file, or create an empty file to edit if the crontab file does not exist. When editing is complete, the file will be copied into the crontab directory as your crontab file. .TP .CR "crontab -l" List your crontab file. .TP .CR "crontab -r" Remove your crontab file from the crontab directory. .RE .PP The entries in a crontab file are lines of six fields each. The fields are separated by spaces or tabs. The lines have the following format: .IP .IR "minute hour monthday month weekday command" .PP The first five are integer patterns that specify when the sixth field, .IR command , should be executed. They can have the following ranges of values: .RS .TP 15 .IR minute The minute of the hour, .CR 0 \(mi 59 .TP .IR hour The hour of the day, .CR 0 \(mi 23 .TP .IR monthday The day of the month, .CR 1 \(mi 31 .TP .IR month The month of the year, .CR 1 \(mi 12 .TP .IR weekday The day of the week, .CR 0 \(mi 6 ,\ 0 =Sunday .RE .PP Each pattern can be either an asterisk .RC ( * ), meaning all legal values, or a list of elements separated by commas. An element is either a number in the ranges shown above, or two numbers in the range separated by a hyphen (meaning an inclusive range). Note that the specification of days can be made in two fields: .IR monthday and .IR weekday . If both are specified in an entry, they are cumulative. For example, .IP .CI "0 0 1,15 * 1 \&" command .PP runs .IR command at midnight on the first and fifteenth of each month, as well as every Monday. To specify days in only one field, set the other field to asterisk .RC ( * ). For example, .IP .CI "0 0 * * 1 \&" command .PP runs .IR command only on Mondays. .PP The sixth field, .IR command (the balance of a line including blanks in a crontab file), is a string that is executed by the shell at the specified times. A percent character .RC ( % ) in this field (unless escaped by a backslash .RC ( \e )) is translated to a newline character, dividing the field into "lines". Only the first "line" (up to a .CR % or end-of-line) of the command field is executed by the shell. Any other "lines" are made available to the command as standard input. .PP Blank lines and those whose first non-blank character is # will be ignored. .PP .CR cron invokes the command from the user's .CR HOME directory with the POSIX shell, .RC ( /usr/bin/sh ). It runs in the .CR c queue (see .IR queuedefs (4)). .PP .CR cron supplies a default environment for every shell, defining: .nf .IP .CI HOME= user's-home-directory .CI LOGNAME= user's-login-id .CR PATH=/usr/bin:/usr/sbin:. .CR SHELL=/usr/bin/sh .fi .PP Users who desire to have their .CR .profile executed must explicitly do so in the crontab entry or in a script called by the entry. .PP You can execute .CR crontab if your name appears in the file .CR /var/adm/cron/cron.allow . If that file does not exist, you can use .CR crontab if your name does not appear in the file .CR /var/adm/cron/cron.deny . If only .CR cron.deny exists and is empty, all users can use .CR crontab . If neither file exists, only the .CR root user can use .CR crontab . The .CR allow / deny files consist of one user name per line. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text within file as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C crontab behaves as if all internationalization variables are set to "C". See .IR environ (5). .CR EDITOR determines the editor to be invoked when .C -e option is specified. The default editor is vi. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .\" .SH EXAMPLES .\" The following is an example of a crontab file. .\" The particular features are noted by comments in the file. .SH WARNINGS Be sure to redirect the standard output and standard error from commands. If this is not done, any generated standard output or standard error is mailed to the user. .SH FILES .if t .TP 40 .if n .TP 30 .CR /var/adm/cron Main cron directory .PD 0 .TP .CR /var/adm/cron/cron.allow List of allowed users .TP .CR /var/adm/cron/cron.deny List of denied users .TP .CR /var/adm/cron/log Accounting information .TP .CR /var/spool/cron/crontabs Directory containing the crontab files .PD .SH SEE ALSO sh(1), cron(1M), queuedefs(4). .SH STANDARDS CONFORMANCE .CR crontab ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4crontab\f1 \- user crontab file operations@@@\f3crontab(1)\f1 .\" index@files: user crontab file operations@@@\f3crontab(1)\f1 .\" index@user crontab file operations@@@\f3crontab(1)\f1 .\" index@crontab file operations, user@@@\f3crontab(1)\f1 .\" index@create user crontab file@@@\f3crontab(1)\f1 .\" index@list user crontab file@@@\f3crontab(1)\f1 .\" index@remove user crontab file@@@\f3crontab(1)\f1 .\" index@delete user crontab file@@@\f3crontab(1)\f1 .\" .\" toc@\f3crontab(1)\f1:\0\0\f4crontab\f1@@@user crontab file operations .\" .\" $Header: crypt.1,v 72.3 93/01/14 11:31:07 ssa Exp $ .TA c .TH crypt 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crypt \- encode/decode files .SH SYNOPSIS .C crypt .RI [ \|password\| ] .SH DESCRIPTION .C crypt reads from the standard input and writes on the standard output. .I password is a key that selects a particular transformation. If no .I password is given, .C crypt demands a key from the terminal and turns off printing while the key is being typed in. .C crypt encrypts and decrypts with the same key: .IP .CI crypt " key " < clear " >" cypher .br .CI crypt " key " < cypher |pr .PP The latter command decrypts the file and prints the clear version. .PP Files encrypted by .C crypt are compatible with those treated by the .C ed editor in encryption mode (see .IR ed (1)). .PP Security of encrypted files depends on three factors: the fundamental method must be hard to solve; direct search of the key space must be infeasible; ``sneak paths'' by which keys or clear text can become visible must be minimized. .PP .C crypt implements a one-rotor machine designed along the lines of the German Enigma, but with a 256-element rotor. Methods of attack on such machines are known, but not widely; moreover the amount of work required is likely to be large. .PP The transformation of a key into the internal settings of the machine is deliberately designed to be expensive; i.e., to take a substantial fraction of a second to compute. However, if keys are restricted to, for example, three lowercase letters, then encrypted files can be read by expending only a substantial fraction of five minutes of machine time. .PP Since the key is an argument to the .C crypt command, it is potentially visible to users executing the .C ps or a derivative (see .IR ps (1)). .ig To minimize this possibility, .I crypt takes care to destroy any record of the key immediately upon entry. .. The choice of keys and key security are the most vulnerable aspect of .CR crypt . .SH EXAMPLES The following example demonstrates the use of .C crypt to edit a file that the user wants to keep strictly confidential: .nf .IP .C $ crypt plans.x .CI key: \0violet .C $ rm plans \h'.3i'... .C $ vi -x plans.x .CI key: \0violet \h'.3i'... .C :wq .C $ \h'.3i'... .C $ crypt , .CR & , or .CR | , at least this part of the expression must be placed within parentheses. The third form assigns the value of .I expression to the .IR index th argument of .IR name . Both .I name and its .IR index th component must already exist. .PD .IP The operators .CR *= , .CR += , etc., are available as in C. White space can optionally separate the .I name from the assignment operator. However, spaces are mandatory in separating components of .I expression which would otherwise be single words. .IP Special postfix .C ++ and .C -\|- operators increment and decrement .IR name , .\" ##################################################### .\" Same here. .\" ##################################################### respectively (e.g., .ifn \f3\@\0i++\f1). .ift \f4\s+1\@\0i++\fP\s0). .\" ##################################################### .SS Non-Built-In Command Execution When a command to be executed is not a built-in command, .C csh attempts to execute the command via .IR exec (2). Each word in the variable .I path names a directory in which the shell attempts to find the command (if the command does not begin with .CR / ). If neither .C -c nor .C -t is given, the shell hashes the names in these directories into an internal table so that an .I exec is attempted only in those directories where the command might possibly reside. This greatly speeds command location when a large number of directories are present in the search path. If this mechanism has been turned off (via .CR unhash ), or if .C -c or .C -t was given, or if any directory component of .I path does not begin with a .CR / , the shell concatenates the directory name and the given command name to form a path name of a file which it then attempts to execute. .PP Commands placed inside parentheses are always executed in a subshell. Thus .IP .C (cd ; pwd) .PP prints the .I home directory then returns to the current directory upon completion, whereas: .IP .C cd ; pwd .PP remains in the .I home directory upon completion. .PP When commands are placed inside parentheses, it is usually to prevent .I chdir from affecting the current shell. .PP If the file has execute permissions but is not an executable binary file, it is assumed to be a script file, which is a file of data for an interpreter that is executed as a separate process. .PP .C csh first attempts to load and execute the script file (see .IR exec (2)). If the first two characters of the script file are .CR #! , .IR exec (2) expects an interpreter path name to follow and attempts to execute the specified interpreter as a separate process to read the entire script file. .PP If no .CI #!\0interpreter is named, and there is an .I alias for the shell, the words of the .I alias are inserted at the beginning of the argument list to form the shell command. The first word of the .I alias should be the full path name of the command to be used. Note that this is a special, late-occurring case of .I alias substitution, which inserts words into the argument list without modification. .PP If no .CI #!\0interpreter is named and there is no shell .IR alias , but the first character of the file is .CR # , the interpreter named by the .C $shell variable is executed (note that this normally would be .CR /usr/bin/csh , unless the user has reset .CR $shell ). If .C $shell is not set, .C /usr/bin/csh is executed. .PP If no .CI !#\0interpreter is named, and there is no shell alias, and the first character of the file is not .CR # , .C /usr/bin/sh is executed to interpret the script file. .SS History Substitutions History substitutions enable you to repeat commands, use words from previous commands as portions of new commands, repeat arguments of a previous command in the current command, and fix spelling or typing mistakes in an earlier command. .PP History substitutions begin with an exclamation point .RC ( ! ). Substitutions can begin anywhere in the input stream, but .I cannot be nested. The exclamation point can be preceded by a backslash to cancel its special meaning. For convenience, an exclamation point is passed to the parser unchanged when it is followed by a blank, tab, newline, equal sign, or left parenthesis. Any input line that contains history substitution is echoed on the terminal before it is executed for verification. .PP Commands input from the terminal that consist of one or more words are saved on the history list. The history substitutions reintroduce sequences of words from these saved commands into the input stream. The number of previous commands saved is controlled by the .C history variable. The previous command is always saved, regardless of its value. Commands are numbered sequentially from 1. .PP You can refer to previous events by event number (such as .C !10 for event 10), relative event location (such as .C !-2 for the second previous event), full or partial command name (such as .C !d for the last event using a command with initial character .CR d ), and string expression (such as .C !?mic? referring to an event containing the characters .CR mic ). .PP These forms, without further modification, simply reintroduce the words of the specified events, each separated by a single blank. As a special case, .C !! is a re-do; it refers to the previous command. .PP To select words from a command, use a colon .RC ( : ) and a designator for the desired words after the event specification. The words of an input line are numbered from zero. The basic word designators are: .RS .TP 5 .C 0 First word (i.e., the command name itself). .TP .I n .IR n th word. .TP .C ^ First argument. (This is equivalent to .CR 1 .) .TP .C $ Last word. .TP .IR a - b Range of words from .I a through .IR b . Special cases are .CR -\f2y\fP , an abbreviation for ``word 0 through word .IR y ''; and .RC \f2x\fP - , which means ``word .I x up to, but not including, word .CR $ ''. .TP .C * Range from the second word through the last word. .TP .C % Used with a search sequence to substitute the immediately preceding matching word. .RE .PP The colon separating the command specification from the word designator can be omitted if the argument selector begins with a .CR ^ , .CR $ , .CR * , .CR - , or .CR % . .PP After word designator can be followed by a sequence of modifiers, each preceded by a colon. The following modifiers are defined: .RS .TP 5 .C h Use only the first component of a path name by removing all following components. .TP .C r Use the root file name by removing any trailing suffix (.xxx). .TP .C e Use the file name's trailing suffix .RC ( .\f2xxx\fP ) by removing the root name. .TP .CI s\0/ l / r substitute the value of .I r for the value .I l in the indicated command. .TP .C t Use only the final file name of a path name by removing all leading path name components. .TP .C & Repeat the previous substitution. .TP .C p Print the new command but do not execute it. .TP .C q Quote the substituted words, preventing further substitutions. .TP .C x Like .CR q , but break into words at blanks, tabs and newlines. .TP .C g Use a .CR g lobal command as a prefix to another modifier to cause the specified change to be made globally. All words in the command are changed, one change per word, and each string enclosed in single quotes .RC ( ' ) or double quotes .ifn (\|\f3"\fP\|) .ift (\|\f4\s+1"\fP\s0\|) is treated as a single word. .RE .PP Unless preceded by a .CR g , the modification is applied only to the first modifiable word. An error results if a substitution is attempted and cannot be completed (i.e., if you ask for a substitution of .C !11 on a history buffer containing only 10 commands). .PP The left hand side of substitutions are strings; not regular expressions in the sense of .SM HP-UX editors. Any character can be used as the delimiter in place of a slash .RB ( / ). Use a backslash to quote a delimiter character if it is used in the .I l or .I r string. The character .C & in the right-hand side is replaced by the text from the left. A .C \e also quotes .CR & . A null .I l string uses the previous string either from an .I l or from a contextual scan string .I s in .CI !? s ?\f1. The trailing delimiter in the substitution can be omitted if a new-line character follows immediately, as may the trailing .C ? in a contextual scan. .PP A history reference can be given without an event specification (as in .CR !$ ). In this case, the reference is to the previous command unless a previous history reference occurred on the same line, in which case this form repeats the previous reference. Thus .IP .C !?foo?^ !$ .PP gives the first and last arguments from the command matching .CR ?foo? . .PP A special abbreviation of a history reference occurs when the first non-blank character of an input line is a circumflex .RB ( ^ ). This is equivalent to .CR !:s^ , providing a convenient shorthand for substitutions on the text of the previous line. Thus .C ^lb^lib fixes the spelling of .C lib in the previous command. .PP Finally, a history substitution can be enclosed within curly braces .C {\0} if necessary to insulate it from the characters which follow. Thus, after .IP .C ls\0-ld\0~paul .PP one could execute .C !{l}a to do .IP ls\0-ld\0~paula .PP while .C !la would look for a command starting with .CR la . .SS "Quoting with Single and Double Quotes" The quotation of strings by single quotes .RB ( ' ) and double quotes .ifn (\|\f3"\fP\|) .ift (\|\f4\s+1"\fP\s0\|) can be used to prevent all or some of the remaining substitutions. Strings enclosed in single quotes are protected from any further interpretation. Strings enclosed in double quotes are still variable- and command-expanded as described below. .PP In both cases the resulting text becomes (all or part of) a single word. Only in one special case (see .I Command Substitution below) does a double-quoted string yield parts of more than one word; single-quoted strings never do. .SS Alias Substitution .C csh maintains a list of aliases that can be established, displayed, and modified by the .C alias and .C unalias commands. After a command line is scanned, it is parsed into distinct commands and the first word of each command, left-to-right, is checked to see if it has an alias. If it does, the text which is the alias for that command is reread with the history mechanism available as if that command was the previous input line. The resulting words replace the command and argument list. If no reference is made to the history list, the argument list is left unchanged. .PP Thus, if the alias for .C ls is .CR "ls -l" , the command .C ls /usr maps to .CR "ls -l /usr" , leaving the argument list undisturbed. Similarly, if the alias for .C lookup was .CR "grep !^ /etc/passwd" , .C lookup bill maps to .C "grep bill /etc/passwd" . .PP If an alias is found, the word transformation of the input text is performed and the aliasing process begins again on the re-formed input line. Looping is prevented if the first word of the new text is the same as the old by flagging it to prevent further aliasing. Other loops are detected and cause an error. .PP Note that the mechanism allows aliases to introduce parser metasyntax. Thus: .IP .C alias print 'pr \e!* | lp' .PP makes a command that uses .IR pr (1) to print its arguments on the line printer. .SS Expressions Some of the built-in commands take expressions in which the operators are similar to those of C, with the same precedence. These expressions appear in the .ifn \f3\@\f1, .ift \f4\s+1\@\fP\s0, .CR exit , .CR if , and .C while commands. The following operators are available (shown in order of increasing precedence): .IP .C "|| && | ^ & == != =~ !~ <= >= < > << >> + - * / % ! ~ ( )" .PP The following list shows the grouping of these operators. The precedence decreases from top to bottom in the list: .IP .ift .sp -1v .nf .C * / % .C + - .C << >> .C <= >= < > .C == != =~ !~ .fi .PP The operators .CR == , .CR != , .CR =~ , and .CR !~ compare their arguments as strings; all others operate on numbers. The operators .C =~ and .C !~ are similar to .C != and .CR == , except that the right-hand side is a .I pattern (containing .CR * s, .CR ? s, and instances of .CR [ ... ] \|) against which the left hand operand is matched. This reduces the need for use of the .C switch statement in shell scripts when all that is really needed is pattern matching. .PP Strings beginning with .C 0 are considered octal numbers. Null or missing arguments are considered .CR 0 . The result of all expressions are strings that represent decimal numbers. It is important to note that no two components of an expression can appear in the same word. These components should be surrounded by spaces except when adjacent to components of expressions that are syntactically significant to the parser: .CR - , .CR & , .CR | , .CR < , .CR > , .CR ( , and .CR ) . .PP Also available in expressions as primitive operands are command executions enclosed in curly braces .RC (\| {\0} \|) and file enquiries of the form .CR - \f2l\0filename\fP, where .I l is one of: .RS .TP 5 .C r read access .PD 0 .TP .C w write access .TP .C x execute access .TP .C e existence .TP .C o ownership .TP .C z zero size .TP .C f plain file .TP .C d directory .RE .PD .PP The specified .I filename is command- and file-name expanded then tested to see if it has the specified relationship to the real user. If the file does not exist or is inaccessible, all inquiries return false (0). Command executions succeed, returning true, if the command exits with status 0; otherwise they fail, returning false. If more detailed status information is required, the command should be executed outside of an expression and the .C status variable examined. .PP .SS Control of the Flow .C csh contains a number of commands that can be used to regulate the flow of control in command files (shell scripts) and (in limited but useful ways) from terminal input. These commands all operate by forcing the shell to reread or skip parts of its input and, due to the implementation, restrict the placement of some of the commands. .PP The .CR foreach , .CR switch , and .C while statements, as well as the .CR if - then - else form of the .C if statement require that the major keywords appear in a single simple command on an input line as shown below. .PP If the shell's input is not seekable, the shell buffers input whenever a loop is being read and performs seeks in this internal buffer to accomplish the rereading implied by the loop. (To the extent that this allows, backward .CR goto s succeed on non-seekable inputs.) .SS Signal Handling .C csh normally ignores .I quit signals. Jobs running in background mode are immune to signals generated from the keyboard, including hangups. Other signals have the values which the shell inherited from its parent. .CR csh 's handling of interrupts and terminate signals in shell scripts can be controlled by .IR onintr . Login shells catch the .I terminate signal; otherwise this signal is passed on to children from the state in the shell's parent. In no case are interrupts allowed when a login shell is reading the file .CR .logout . .SS Command Line Parsing .C csh splits input lines into words at blanks and tabs. The following exceptions (parser metacharacters) are considered separate words: .RS .TP 7 .C & ampersand; .PD 0 .TP .C | vertical bar; .TP .C ; semicolon; .TP .C < less-than sign; .TP .C > greater-than sign; .TP .C ( left parenthesis; .TP .C ) right parenthesis; .TP .C && double ampersand; .TP .C || double vertical bar; .TP .C << double less-than sign; .TP .C >> double greater-than sign; .TP .C # comment delimiter .PD .RE .PP The backslash .RC ( \e ) removes the special meaning of these parser metacharacters. A parser metacharacter preceded by a backslash is interpreted as its .SM ASCII value. A newline character .SM (ASCII 10) preceded by a backslash is equivalent to a blank. .PP Strings enclosed in single or double quotes form parts of a word. Metacharacters in these strings, including blanks and tabs, do not form separate words. Within pairs of backslashes or quotes, a newline preceded by a backslash gives a true newline character. .PP When .CR csh 's input is not a terminal, the .C # character introduces a comment terminated by a newline. .SS \s-1CSH VARIABLES\s0 .C csh maintains a set of variables. Each variable has a value equal to zero or more strings (words). Variables have names consisting of up to 80 letters and digits starting with a letter. The underscore character is considered a letter. The value of a variable may be displayed and changed by using the .C set and .C unset commands. Some of the variables are Boolean, that is, the shell does not care what their value is, only whether they are set or not. .PP Some operations treat variables numerically. The at sign .ifn (\f3@\fP) .ift (\f4\s+1@\fP\s0) command permits numeric calculations to be performed and the result assigned to a variable. The null string is considered to be zero, and any subsequent words of multi-word values are ignored. .PP After the input line is aliased and parsed, and before each command is executed, variable expansion is performed keyed by the dollar sign .RC ( $ ) character. Variable expansion can be prevented by preceding the dollar sign with a backslash character .RC ( \e ) except within double quotes .ifn (\f3"\fP) .ift (\f4\s+1"\s0\fP) where substitution .C always occurs. Variables are never expanded if enclosed in single quotes. Strings quoted by single quotes are interpreted later (see .IR "Command Substitution" ) so variable substitution does not occur there until later, if at all. A dollar sign is passed unchanged if followed by a blank, tab, or end-of-line. .PP Input/output redirections are recognized before variable expansion, and are variable expanded separately. Otherwise, the command name and entire argument list are expanded together. .PP Unless enclosed in double quotes or given the .C :q modifier, the results of variable substitution may eventually be command and file name substituted. Within double quotes, a variable whose value consists of multiple words expands to a portion of a single word, with the words of the variable's value separated by blanks. When the .C :q modifier is applied to a substitution, the variable expands to multiple words with each word separated by a blank and quoted to prevent later command or file name substitution. .PP The following metasequences are provided for introducing variable values into the shell input. Except as noted, it is an error to reference a variable that is not set. .RS .TP .5i .CI $ variable_name .PD 0 .TP .CI ${ variable_name } When interpreted, this sequence is replaced by the words of the value of the variable .IR variable_name , each separated by a blank. Braces insulate .I variable_name from subsequent characters that would otherwise be interpreted to be part of the variable name itself. .IP If .I variable_name is not a .C csh variable, but is set in the environment, that value is used. .RC Non- csh variables cannot be modified as shown below. .TP .CI $ variable_name\f1[\fPselector\f1]\fP .PD 0 .TP .CI ${ variable_name\f1[\fPselector\f1]\fP } This modification selects only some of the words from the value of .IR variable_name . The selector is subjected to variable substitution, and can consist of a single number or two numbers separated by a dash. The first word of a variable's value is numbered .CR 1 . If the first number of a range is omitted it defaults to .CR 1 . If the last member of a range is omitted it defaults to the total number of words in the variable .RC ( $# \f2variable_name\fP). An asterisk metacharacter used as a selector selects all words. .PD .TP .CI $# variable_name .PD 0 .TP .CI ${# variable_name } This form gives the number of words in the variable, and is useful for forms using a .RI [ selector ] option. .PD .TP .C $0 This form substitutes the name of the file from which command input is being read. An error occurs if the file name is not known. .TP .CI $ number .PD 0 .TP .CI ${ number } This form is equivalent to an indexed selection from the variable .C argv .RC ( $argv[ \f2number\fP ] ). .PD .TP .C $* This is equivalent to selecting all of .I argv .RC ( $argv[*] ). .RE .PP The modifiers .CR :h , .CR :t , .CR :r , .CR :q , and .CR :x can be applied to the substitutions above, as can CR :gh , CR :gt , and CR :gr . If curly braces .RC ( {\0} ) appear in the command form, the modifiers must appear within the braces. .I "The current implementation allows only one" .C : .I modifier on each .C $d .IR expansion . .PP The following substitutions cannot be modified with .C : modifiers: .RS .TP .5i .CI $? variable_name .PD 0 .TP .CI ${? variable_name } Substitutes the string .C 1 if .I variable_name is set, .C 0 if it is not. .PD .TP .C $?0 Substitutes .C 1 if the current input file name is known, .C 0 if it is not. .TP .C $$ Substitutes the (decimal) process number of the (parent) shell. .TP .C $< Substitutes a line from the standard input, with no further interpretation thereafter. It can be used to read from the keyboard in a shell script. .SS "Pre-Defined and Environment Variables" The following variables have special meaning to the shell. Of these .CR autologout , .CR argv , .CR cwd , .CR home , .CR path , .CR prompt , .CR shell , and .C status are always set by the shell. Except for .C cwd and .CR status , this setting occurs only at initialization (initial execution of .CR csh ). These variables are not modified unless modified explicitly by the user. .PP .C csh copies the .SM HP-UX environment variable .SM USER into the shell variable .CR user , the environment variable .C TERM into .CR term , the environment variable .C HOME into .CR home , and .C PATH into .CR path . .C csh copies these values back into the environment whenever the .C csh variables are reset. .PP In a windowed environment, if .C csh detects that the window has changed size, .C csh sets the environment variables .C LINES and .C COLUMNS to match the new window size. .RS .TP 15 .C argv This variable is set to the arguments of the .C csh command statement. It is from this variable that positional parameters are substituted; i.e., .C $1 is replaced by .CR $argv[1] , etc. .TP .C cdpath This variable gives a list of alternate directories searched to find subdirectories in .I chdir commands. .TP .C cwd This variable contains the absolute path name of the current working directory. Whenever changing directories (using .IR cd ), this variable is updated. .TP .C echo This variable is set by the .C -x command line option. If set, all built-in commands and their arguments are echoed to the standard output device just before being executed. Built-in commands are echoed before command and file name substitution, since these substitutions are then done selectively. For non-built-in commands, all expansions occur before echoing. .TP .C history This variable is used to create the command history buffer and to set its size. If this variable is not set, no command history is maintained and history substitutions cannot be made. Very large values of .C history can cause shell memory overflow. Values of 10 or 20 are normal. All commands, executable or not, are saved in the command history buffer. .TP .C home This variable contains the absolute path name to your home directory. The variable .C home is initialized from the .SM HP-UX environment. File name expansion of tilde .RC ( ~ ) refers to this variable. .TP .C ignoreeof If set, .C csh ignores end-of-file characters from input devices that are terminals. .C csh exits normally when it encounters the end-of-file condition .RC (CTRL- D typed as the first character on a command line). Setting .I ignoreeof prevents the current shell from being killed by an accidental .RC (CTRL- D . However, to prevent an infinite loop of .SM EOF input, .C csh terminates if it receives 26 consecutive .SM EOF\s0s. .TP .C mail This variable contains a list of the files where .C csh checks for your mail. .C csh periodically (default is 10 minutes) checks this variable before producing a prompt upon command completion. If the variable contains a file name that has been modified since the last check (resulting from mail being put in the file), .C csh prints .CR "You have new mail" . .IP If the first word of the value of .C mail is numeric, that number specifies a different mail checking interval in seconds. .IP If multiple mail files are specified, the shell says .C New mail in .IR file_name , where .I file_name is the file containing the mail. .TP .C noclobber This variable places restrictions on output redirection to ensure that files are not accidentally destroyed, and that commands using append redirection .RC ( >> ) refer to existing files. .TP .C noglob If set, file name expansion is inhibited. This is most useful in shell scripts that are not dealing with file names, or after a list of file names has been obtained and further expansions are not desirable. .TP .C nonomatch If set, it is no longer an error for a file name expansion to not match any existing files. If there is no match, the primitive pattern is returned. It is still an error for the primitive pattern to be malformed. For example, .C 'echo\0[' still gives an error. .TP .C notify If set, .C csh notifies you immediately (through your standard output device) of background job completions. The default is .C unset (indicate job completions just before printing a prompt). .TP .C path Each word of the path variable specifies a directory in which commands are to be sought for execution. A null word specifies your current working directory. If there is no .I path variable, only full path names can be executed. When .I path is not set and when users do not specify full path names, .C csh searches for the command through the directories .C . (current directory) and .CR /usr/bin . A .C csh which is given neither the .C -c nor the .C -t option normally hashes the contents of the directories in the .C path variable after reading .CR .cshrc , and each time the .C path variable is reset. If new commands are added to these directories while the shell is active, it is necessary to execute .C rehash for .C csh to access these new commands. .TP .C prompt This variable lets you select your own prompt character string. The prompt is printed before each command is read from an interactive terminal input. If a .C ! appears in the string, it is replaced by the current command history buffer event number unless a preceding .C \e is given. The default prompt is the percent sign .RC ( % ) for users and the .C # character for the super-user. .TP .C shell This variable contains the name of the file in which the .C csh program resides. This variable is used in forking shells to interpret files that have their execute bits set but which are not executable by the system. (See the description of .IR "Non-Built-In Command Execution" ). .TP .C status This variable contains the status value returned by the last command. If the command terminated abnormally, 0200 is added to the status variable's value. Built-in commands which terminated abnormally return exit status .CR 1 , and all other built-in commands set status to .CR 0 . .TP .C time This variable contains a numeric value that controls the automatic timing of commands. If set, .C csh prints, for any command taking more than the specified number of cpu seconds, a line of information to the standard output device giving user, system, and real execution times plus a utilization percentage. The utilization percentage is the ratio of user plus system times to real time. This message is printed after the command finishes execution. .TP .C verbose This variable is set by the .C -v command line option. If set, the words of each command are printed on the standard output device after history substitutions have been made. .RE .SS "Command and File name Substitution" The remaining substitutions, command and file name substitution, are applied selectively to the arguments of built-in commands. This means that portions of expressions that are not evaluated are not subjected to these expansions. For commands which are not internal to the shell, the command name is substituted separately from the argument list. This occurs very late, after input-output redirection is performed, and in a child of the main shell. .SS "Command Substitution" Command substitution is indicated by a command enclosed in grave accents (\|\(ga .\|.\|.\(ga\|). The output from such a command is normally broken into separate words at blanks, tabs and newlines, with null words being discarded; this text then replacing the original string. Within double quotes, only newlines force new words; blanks and tabs are preserved. .PP In any case, the single final newline does not force a new word. Note that it is thus possible for a command substitution to yield only part of a word, even if the command outputs a complete line. .SS "File name Substitution" Each command .I word is processed as a pattern for file name substitution, also known as .BR globbing , and replaced with a sorted list of file names which match the pattern. The form of the patterns is the Pattern Matching Notation defined by .IR regexp (5) with the following exceptions: .RS .TP 3 \(bu Non-matching lists in bracket expressions are not supported. .TP \(bu In a list of words specifying file name substitution it is an error for no pattern to match an existing file name, but it is not required for each pattern to match. .TP \(bu The metanotation \f3a{b,c,d}e\f1 is a shorthand for "abe ace ade". Left to right order is preserved, with results of matches being sorted separately at a low level to preserve this order. This construct may be nested. Thus: .RS .RS .IP .C ~source/s1/{oldls,ls}.c .RE .IP expands to .RS .IP .C /home/source/s1/oldls.c /home/source/s1/ls.c .RE .RE .IP whether or not these files exist, without any chance of error if the home directory for .C source is .CR /home/source . Similarly, .RS .RS .IP .C ../{memo,*box} .RE .IP might expand to .RS .IP .C ../memo\0../box\0../mbox .RE .IP (Note that .C memo was not sorted with the results of matching .CR *box .) As a special case, .CR { , .CR } , and .C {\|} are passed undisturbed. .SS "Input/Output" The standard input and standard output of a command can be redirected with the following syntax: .RS .TP 15 .CI < " name" Open file .I name (which is first variable, command and file name expanded) as the standard input. .TP .CI << " word" Read the shell input up to a line which is identical to .IR word . .I word is not subjected to variable, file name or command substitution, and each input line is compared to .I word before any substitutions are done on this input line. Unless a quoting .CR \e , .ifn \f3"\fP, .ifn \f4\s+1"\s0\fP, .CR ' , or \(ga appears in .IR word , variable and command substitution is performed on the intervening lines, allowing .C \e to quote .CR $ , .C \e and \(ga. Commands which are substituted have all blanks, tabs, and newlines preserved, except for the final newline which is dropped. The resultant text is placed in an anonymous temporary file which is given to the command as standard input. .TP .CI > " name" .PD 0 .TP .CI >! " name" .TP .CI >& " name" .TP .CI >&! " name" The file .I name is used as standard output. If the file does not exist, it is created; if the file exists, it is truncated, and its previous contents are lost. .PD .IP If the variable .C noclobber is set, the file must not exist or be a character special file (e.g., a terminal or .CR /dev/null ) or an error results. This helps prevent accidental destruction of files. In this case the exclamation point .RC ( ! ) forms can be used to suppress this check. .IP The forms involving the ampersand character .RC ( & ) route the standard error into the specified file as well as the standard output. .I name is expanded in the same way as < input file names are. .PD .TP .CI >> " name" .PD 0 .TP .CI >>& " name" .TP .CI >>! " name" .TP .CI >>&! " name" Uses file .I name as standard output the same as .CR > , but appends output to the end of the file. If the variable .C noclobber is set, it is an error for the file not to exist unless one of the .C ! forms is given. Otherwise, it is similar to .CR > . .RE .PD .PP A command receives the environment in which the shell was invoked as modified by the input-output parameters and the presence of the command in a pipeline. Thus, unlike some previous shells, commands executed from a shell script have no access to the text of the commands by default; rather they receive the original standard input of the shell. The .C << mechanism should be used to present inline data. This permits shell scripts to function as components of pipelines and allows the shell to block-read its input. .PP Diagnostic output can be directed through a pipe with the standard output. Simply use the form .C |& rather than .C | by itself. .SS \s-1CSH UTILITIES\s0 .SS "File Name Completion" In typing file names as arguments to commands, it is no longer necessary to type a complete name, only a unique abbreviation is necessary. When you want the system to try to match your abbreviation, press the .SM ESC key. The system then completes the file name for you, echoing the full name on your terminal. If the abbreviation does not match an available file name, the terminal's bell is sounded. The file name may be partially completed if the prefix matches several longer file names. In this case, the name is extended up to the ambiguous deviation, and the bell is sounded. .PP File name completion works equally well when other directories are addressed. In addition, the tilde .RC ( ~ ) convention for home directories is understood in this context. .SS "Viewing a File or Directory List" At any point in typing a command, you can request "what files are available" or "what files match my current specification". Thus, when you have typed: .IP .C %\0cd\0~speech/data/bench/fritz/ .PP you may wish to know what files or subdirectories exist (in .CR ~speech/data/bench/fritz ), without aborting the command you are typing. Typing .RC CTRL- D at this point lists the files available. Files are listed in multicolumn format, sorted by column. Directories and executable files are identified by a trailing .C / and .CR * , respectively. Once printed, the command is re-echoed for you to complete. Additionally, you may want to know which files match a prefix, the current file specification so far. If you had typed: .IP %\0cd\0~speech/data/bench/fr .PP followed by a .RC CTRL- D , all files and subdirectories whose prefix was .C fr in the directory .C ~speech/data/bench would be printed. Notice that the example before was simply a degenerate case of this with a null trailing file name. (The null string is a prefix of all strings.) Notice also that a trailing slash is required to pass to a new sub-directory for both file name completion and listing. Note that the degenerate case .IP .C %\0~^D .PP prints a full list of login names on the current system. .SS "Command Name Recognition" Command name recognition and completion works in the same manner as file name recognition and completion above. The current value of the environment variable .C PATH is used in searching for the command. For example .IP .C %\0newa\0[Escape] .PP might expand to .IP .C %\0newaliases .PP Also, .IP .C %\0new\0[Control]-[D] .PP lists all commands (along .CR PATH ) that begin with .CR new . As an option, if the shell variable .C listpathnum is set, a number indicating the index in .C PATH is printed next to each command on a [Control]-[D] listing. .SS Autologout A new shell variable has been added called .CR autologout . If the terminal remains idle (no character input) at the shell's top level for a number of minutes greater than the value assigned to .CR autologout , you are automatically logged off. The .C autologout feature is temporarily disabled while a command is executing. The initial value of .C autologout is 60. If unset or set to 0, .C autologout is entirely disabled. .SS Command Line Control A .C ^R re-prints the current command line; .C ^W erases the last word entered on the current command line. .SS Sanity C shell restores your terminal to a sane mode if it appears to return from some command in raw, cbreak, or noecho mode. .SS "Saving Your History Buffer" .C csh has the ability to save your history list between login sessions. If the shell variable .C savehist is set to a number, that number of command events from your history list is saved. For example, placing the line .IP .C set\0history=10\0savehist=10 .PP in your .C .cshrc file maintains a history buffer of length 10 and saves the entire list when you logout. When you log back in, the entire buffer is restored. The commands are saved in the file .C .history in your login directory. .SH EXTERNAL INFLUENCES .SS Environment Variables .SM LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name substitution. .PP .SM LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as letters, and the characters matched by character class expressions in pattern matching notation. .PP .SM LANG determines the language in which messages are displayed. .PP If .SM LC_COLLATE or .SM LC_CTYPE is not specified in the environment or is set to the empty string, the value of .SM LANG is used as a default for each unspecified or empty variable. If .SM LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .SM LANG. If any internationalization variable contains an invalid setting, .C csh behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS The .C .cshrc file should be structured such that it cannot generate any output on standard output or standard error, including occasions when it is invoked without an affiliated terminal. .IR rcp (1) causes .C .cshrc to be sourced, and any output generated by this file, even to standard error causes problems. Commands such as .IR stty (1) should be placed in .CR .login , not in .CR .cshrc , so that their output cannot affect .IR rcp (1). .PP .C csh has certain limitations. Words or environment variables can be no longer than 10240 characters. The system limits argument lists to 10240 characters. The number of arguments to a command which involves file name expansion is limited to one-sixth the number of characters allowed in an argument list. Command substitutions may substitute no more characters than are allowed in an argument list. .PP To detect looping, the shell restricts the number of .C alias substitutions on a single line to 20. .PP When a command is restarted from a stop, .C csh prints the directory it started in if it is different from the current directory; this can be misleading (i.e., wrong) because the job may have changed directories internally. .PP Shell built-in functions are not stoppable/restartable. Command sequences of the form .C a ; b ; c are also not handled gracefully when stopping is attempted. If you interrupt b, the shell then immediately executes c. This is especially noticeable if this expansion results from an .CR alias . It suffices to place the sequence of commands in parentheses to force it into a subshell; i.e., .CR "( a ; b ; c )" . .PP Because of the signal handling required by csh, interrupts are disabled just before a command is executed, and restored as the command begins execution. There may be a few seconds delay between when a command is given and when interrupts are recognized. .PP Control over tty output after processes are started is primitive; perhaps this will inspire someone to work on a good virtual terminal interface. In a virtual terminal interface much more interesting things could be done with output control. .PP Alias substitution is most often used to clumsily simulate shell procedures; shell procedures should be provided rather than aliases. .PP Commands within loops, prompted for by .CR ? , are not placed in the .I history list. Control structure should be parsed rather than being recognized as built-in commands. This would allow control commands to be placed anywhere, to be combined with .CR | , and to be used with .C & and .C ; metasyntax. .PP It should be possible to use the .C : modifiers on the output of command substitutions. All and more than one .C : modifier should be allowed on .C $ substitutions. .PP Terminal type is examined only the first time you attempt recognition. .PP To list all commands on the system along .CR PATH , enter .SM [Space]-[Ctrl]-[D]. .PP The csh metasequence .C !~ does not work. .PP In an international environment, character ordering is determined by the setting of .SM LC_COLLATE, rather than by the binary ordering of character values in the machine collating sequence. This brings with it certain attendant dangers, particularly when using range expressions in file name generation patterns. For example, the command, .IP .C rm [a-z]* .PP might be expected to match all file names beginning with a lowercase alphabetic character. However, if dictionary ordering is specified by .SM LC_COLLATE, it would also match file names beginning with an uppercase character (as well as those beginning with accented letters). Conversely, it would fail to match letters collated after .C z in languages such as Norwegian. .PP The correct (and safe) way to match specific character classes in an international environment is to use a pattern of the form: .IP .C rm [[:lower:]]* .PP This uses .C LC_CTYPE to determine character classes and works predictably for all supported languages and codesets. For shell scripts produced on non-internationalized systems (or without consideration for the above dangers), it is recommended that they be executed in a non-\c .SM NLS environment. This requires that .CR LANG , .CR LC_COLLATE , etc., be set to "C" or not set at all. .PP .C csh implements command substitution by creating a pipe between itself and the command. If the root file system is full, the substituted command cannot write to the pipe. As a result, the shell receives no input from the command, and the result of the substitution is null. In particular, using command substitution for variable assignment under such circumstances results in the variable being silently assigned a .SM NULL value. .PP Relative path changes (such as .CR "cd .." ), when in a symbolically linked directory, cause .CR csh 's knowledge of the working directory to be along the symbolic path instead of the physical path. .PP Prior to .SM HP-UX Release 9.0, .CR csh , when getting its input from a file, would exit immediately if unable to execute a command (such as if it was unable to find the command). Beginning at Release 9.0, .C csh continues on and attempts to execute the remaining commands in the file. However, if the old behavior is desired for compatibility purposes, set the environment variable .C EXITONERR to 1. .SH AUTHOR .C csh was developed by the University of California, Berkeley and HP. .SH FILES .TP 25 .C ~/.cshrc A csh script sourced (executed) at the beginning of execution by each shell. See .SM WARNINGS .TP .C ~/.login A csh script sourced (executed) by login shell, after .C .cshrc at login. .TP .C ~/.logout A csh script sourced (executed) by login shell, at logout. .TP .C /etc/passwd Source of home directories for .CR ~name . .TP .C /usr/bin/sh Standard shell, for shell scripts not starting with a .CR # . .TP .C /etc/csh.login A csh script sourced (executed) before .C ~/.cshrc and .C ~/.login when starting a csh login (analogous to .C /etc/profile in the Bourne shell). .TP .C /tmp/sh* Temporary file for .CR << . .SH "SEE ALSO" sh(1), access(2), exec(2), fork(2), pipe(2), umask(2), wait(2), tty(7), a.out(4), environ(5), lang(5), regexp(5). .PP .I C Shell tutorial in .I "Shells Users Guide" . .\" index@\f2csh\f1 \- a shell (command interpreter) with C-like syntax@@@\f3csh(1)\f1 .\" index@C-like syntax, a shell (command interpreter) with@@@\f3csh(1)\f1 .\" index@command interpreter (shell) with C-like syntax@@@\f3csh(1)\f1 .\" index@interpreter, command (shell) with C-like syntax@@@\f3csh(1)\f1 .\" index@shell (command interpreter) with C-like syntax@@@\f3csh(1)\f1 .\" index@syntax, a shell (command interpreter) with C-like@@@\f3csh(1)\f1 .\" index@alias \- substitute command and/or filename@@@\f3csh(1)\f1 .\" index@alloc \- show dynamic memory usage@@@\f3csh(1)\f1 .\" index@break \- exit from enclosing for/next loop@@@\f3csh(1)\f1 .\" index@breaksw \- break from switch and resume after endsw@@@\f3csh(1)\f1 .\" index@case \- label in a switch statement@@@\f3csh(1)\f1 .\" index@cd \- change working directory@@@\f3csh(1)\f1 .\" index@chdir \- change current working directory@@@\f3csh(1)\f1 .\" index@continue \- resume execution of nearest while or foreach@@@\f3csh(1)\f1 .\" index@default \- label default in switch statement@@@\f3csh(1)\f1 .\" index@dirs \- print the directory stack@@@\f3csh(1)\f1 .\" index@echo \- echo (print) arguments@@@\f3csh(1)\f1 .\" index@end \- terminate foreach or while loop@@@\f3csh(1)\f1 .\" index@endsw \- terminate switch statement@@@\f3csh(1)\f1 .\" index@eval \- read arguments as shell input and execute result@@@\f3csh(1)\f1 .\" index@exec \- execute command without creating new process@@@\f3csh(1)\f1 .\" index@exit \- exit shell with exit status@@@\f3csh(1)\f1 .\" index@foreach \- initiate repetitive loop@@@\f3csh(1)\f1 .\" index@glob \- echo without '\e\e' escapes@@@\f3csh(1)\f1 .\" index@goto \- continue execution on specified line@@@\f3csh(1)\f1 .\" index@hashstat \- print hash table effectiveness statistics@@@\f3csh(1)\f1 .\" index@history \- Display event history list@@@\f3csh(1)\f1 .\" index@if \- execute command if expression evaluates true@@@\f3csh(1)\f1 .\" index@jobs \- list active jobs@@@\f3csh(1)\f1 .\" index@kill \- send termination or specified signal to a process@@@\f3csh(1)\f1 .\" index@limit \- limit usage by current process@@@\f3csh(1)\f1 .\" index@login \- terminate login shell@@@\f3csh(1)\f1 .\" index@logout \- terminate login shell@@@\f3csh(1)\f1 .\" index@newgrp \- equivalent to \f3exec newgrp\f1@@@\f3csh(1)\f1 .\" index@nice \- alter command priority@@@\f3csh(1)\f1 .\" index@nohup \- ignore hangups during command execution@@@\f3csh(1)\f1 .\" index@notify \- notify user of change in job status@@@\f3csh(1)\f1 .\" index@onintr \- specify shell's treatment of interrupts@@@\f3csh(1)\f1 .\" index@popd \- pop directory stack@@@\f3csh(1)\f1 .\" index@pushd \- push directory stack@@@\f3csh(1)\f1 .\" index@rehash \- recompute internal hash table@@@\f3csh(1)\f1 .\" index@repeat \- execute command more than once@@@\f3csh(1)\f1 .\" index@set \- set/define flags and arguments@@@\f3csh(1)\f1 .\" index@setenv \- define environment variable@@@\f3csh(1)\f1 .\" index@shift \- shift \f2argv\f1 members one position to left@@@\f3csh(1)\f1 .\" index@source \- define source for command input@@@\f3csh(1)\f1 .\" index@switch \- define switch statement@@@\f3csh(1)\f1 .\" index@test \- evaluate conditional expression@@@\f3csh(1)\f1 .\" index@time \- print summary of time used by shell and children@@@\f3csh(1)\f1 .\" index@umask \- set permissions mask for creating new files@@@\f3csh(1)\f1 .\" index@unalias \- discard specified alias@@@\f3csh(1)\f1 .\" index@unhash \- disable use of internal hash tables@@@\f3csh(1)\f1 .\" index@unset \- remove definition/setting of flags and arguments@@@\f3csh(1)\f1 .\" index@unsetenv \- remove variable from environment@@@\f3csh(1)\f1 .\" index@wait \- wait for background processes@@@\f3csh(1)\f1 .\" index@while \- execute commands while expression is non-zero@@@\f3csh(1)\f1 .\" .\" toc@\f3csh(1)\f1:\0\0\f2csh\f1@@@a shell (command interpreter) with C-like syntax .\" toc@alias: substitute command and/or filename@@@see \f3csh(1)\f1 .\" toc@alloc: show dynamic memory usage@@@see \f3csh(1)\f1 .\" toc@break: exit from enclosing for/next loop@@@see \f3csh(1)\f1 .\" toc@breaksw: break from switch and resume after endsw@@@see \f3csh(1)\f1 .\" toc@case: label in a switch statement@@@see \f3csh(1)\f1 .\" toc@cd: change working directory@@@see \f3csh(1)\f1 .\" toc@chdir: change current working directory@@@see \f3csh(1)\f1 .\" toc@continue: resume execution of nearest while or foreach@@@see \f3csh(1)\f1 .\" toc@default: label default in switch statement@@@see \f3csh(1)\f1 .\" toc@dirs: print the directory stack@@@see \f3csh(1)\f1 .\" toc@echo: echo (print) arguments@@@see \f3csh(1)\f1 .\" toc@end: terminate foreach or while loop@@@see \f3csh(1)\f1 .\" toc@endsw: terminate switch statement@@@see \f3csh(1)\f1 .\" toc@eval: read arguments as shell input and execute resulting/@@@see \f3csh(1)\f1 .\" toc@exec: execute command without creating new process@@@see \f3csh(1)\f1 .\" toc@exit: exit shell with exit status@@@see \f3csh(1)\f1 .\" toc@foreach: initiate repetitive loop@@@see \f3csh(1)\f1 .\" toc@glob: echo without '\e\e' escapes@@@see \f3csh(1)\f1 .\" toc@goto: continue execution on specified line@@@see \f3csh(1)\f1 .\" toc@hashstat: print hash table effectiveness statistics@@@see \f3csh(1)\f1 .\" toc@history: Display event history list@@@see \f3csh(1)\f1 .\" toc@if: execute command if expression evaluates true@@@see \f3csh(1)\f1 .\" toc@jobs: list active jobs@@@see \f3csh(1)\f1 .\" toc@kill: send termination or specified signal to a process@@@see \f3csh(1)\f1 .\" toc@limit: limit usage by current process@@@see \f3csh(1)\f1 .\" toc@login: terminate login shell@@@see \f3csh(1)\f1 .\" toc@logout: terminate login shell@@@see \f3csh(1)\f1 .\" toc@newgrp: equivalent to \f3exec newgrp\f1@@@see \f3csh(1)\f1 .\" toc@nice: alter command priority@@@see \f3csh(1)\f1 .\" toc@nohup: ignore hangups during command execution@@@see \f3csh(1)\f1 .\" toc@notify: notify user of change in job status@@@see \f3csh(1)\f1 .\" toc@onintr: specify shell's treatment of interrupts@@@see \f3csh(1)\f1 .\" toc@popd: pop directory stack@@@see \f3csh(1)\f1 .\" toc@pushd: push directory stack@@@see \f3csh(1)\f1 .\" toc@rehash: recompute internal hash table@@@see \f3csh(1)\f1 .\" toc@repeat: execute command more than once@@@see \f3csh(1)\f1 .\" toc@set: set/define flags and arguments@@@see \f3csh(1)\f1 .\" toc@setenv: define environment variable@@@see \f3csh(1)\f1 .\" toc@shift: shift \f2argv\f1 members one position to left@@@see \f3csh(1)\f1 .\" toc@source: define source for command input@@@see \f3csh(1)\f1 .\" toc@switch: define switch statement@@@see \f3csh(1)\f1 .\" toc@test: evaluate conditional expression@@@see \f3csh(1)\f1 .\" toc@time: print summary of time used by shell and children@@@see \f3csh(1)\f1 .\" toc@umask: set permissions mask for creating new files@@@see \f3csh(1)\f1 .\" toc@unalias: discard specified alias@@@see \f3csh(1)\f1 .\" toc@unhash: disable use of internal hash tables@@@see \f3csh(1)\f1 .\" toc@unset: remove definition/setting of flags and arguments@@@see \f3csh(1)\f1 .\" toc@unsetenv: remove variable from environment@@@see \f3csh(1)\f1 .\" toc@wait: wait for background processes@@@see \f3csh(1)\f1 .\" toc@while: execute commands while expression is non-zero@@@see \f3csh(1)\f1 .\" .\" $Header: ppl.1,v 72.4 94/09/12 14:58:21 ssa Exp $ .TA p .TH ppl 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ppl \- point-to-point serial networking using SLIP or CSLIP .SH SYNOPSIS .C ppl .RC [ -o \(or -i ] .RC [ -t .IR tty\| ] .RC [ -v ] .RC [ -r .IR rtprio\| ] .RC [ -T .IR tracefile\| ] .RI [ \|remote_host\| ] .SH DESCRIPTION .C ppl extends the Internet Protocol .SM (IP) network over serial lines. It permits the use of hardwired, dial-out, or dial-in serial (tty) lines. .C ppl establishes a connection over the serial line, then runs an .B encapsulation protocol to transfer packets between the .SM IP network and the serial line. Once started, .C ppl can only be stopped by loss of the serial line (i.e. carrier failure indication from a modem), or by sending it a .C SIGTERM signal. .PP Currently .SM SLIP (Serial Line Internet Protocol), .SM CSLIP (Compressed Header .SM SLIP), and .SM ASLIP (Abbreviated .SM SLIP\s0) are the only encapsulation protocols available. .PP .C ppl can be configured in a number of ways. It behaves according to how it is configured and which command line options are used. Configuration is controlled by configuration files: .C ppl.remotes, .C ppl.ipool, and .C ppl.users. .C ppl can be configured to share .SM UUCP serial lines. .SS Options .TP 15 .C -i Initiate an incoming connection. Run the encapsulation protocol on the terminal device from which the program is invoked. This is the default if neither .C -o nor .C -i is specified. .TP .C -o Initiate an outgoing connection. The terminal on which the data pump is started is determined from configuration files, .SM UUCP, or the .C -t option. .TP .CI -t \0tty Specifies the .I tty on which the encapsulation protocol is started, .I only if a device name is not specified in configuration file .C ppl.remotes for the remote host. This option only applies when used with the .C -o option. .TP .C -v Verbose mode. This option is only available to the super-user. Verbose debugging information is displayed on the terminal and placed in the log. Secure information is included. .TP .CI -r \0rtprio Set real-time priority during data pump operation. .I rtprio can be a decimal number between 0 and 127. By default, .C ppl runs at a real-time priority of 110. .TP .CI -T \0tracefile Turns on tracing for the SLIP connection that ppl creates. Tracing is done in user space level by .C ppl. All data that are going from IP to the tty line and vice versa are traced. This option is different from the system tracing utility .C nettl, because this option is done for each connection in the user space. .C nettl performs tracing for the entire system. The contents of the .I tracefile are in human readable ASCII format. .TP .I remote_host Specifies the remote host to communicate with. Either a name or an Internet address (in dot notation) can be supplied. This must be the last argument on the command line. If none is supplied (with the .C -i option), ppl uses the users login name to find a remote host in the .C ppl.users file. .SS Dedicated Connections Dedicated connections are lines that are dedicated to .IR ppl . No getty/login is running on the local or remote end of the serial line. Such a line can be either hard-wired, dial-out, or dial-in. .PP Alternatively, .C ppl can run on lines that are used for other purposes; specifically, a getty/login on incoming lines, or shared with .SM UUCP on outgoing lines. .SS Dial-Out Connections To dial out from an .SM HP-UX system, use a command like: .IP .CI "ppl -o " remote_host .PP to establish a connection to a remote host. Any progress or error messages are directed to the users standard error. .C ppl accesses the .C ppl.remotes file to obtain information needed to establish the connection. If necessary, it also uses .SM UUCP files to select a line, acquire the phone number, and control the modem. Note that .C ppl uses various files created and maintained by the .SM UUCP system, but it does not use the .SM UUCP facility to handle inter-system communication. .PP The .SM UUCP line is selected as follows: .RS .TP 5 1. If the entry in the configuration file .C ppl.remotes does not contain a tty device name, .C ppl looks in the .SM UUCP .C Systems file for a tty device (and speed), based on the .C ppl.remotes entry .SM UUCP .I system name or .I remote host name. .TP 2. .C ppl then searches for the tty device name and speed in the .SM UUCP .C Devices file. This information is used for modem dialing instructions. .RE .PP After a successful connection is made, .C ppl makes itself into a ``daemon'' by detaching itself from the users tty group. The user gets back a shell prompt, and the .C ppl program runs in the background. The user can then perform network commands to the remote host. .SS Dial-In Connections To make a dial-in connection to an .SM HP-UX system, dial in on a serial line to the .SM HP-UX system, and log in as usual. Once logged in, the line can be converted from log-in to network use by running .CR ppl . The .C ppl program uses the login name to search .C ppl.users for a remote hostname. The remote hostname is used to access the .C ppl.remotes file to obtain all of the configuration information needed to start the desired protocol. Once the protocol starts, the users' local machine can begin packet transfers with .CR ppl . .C ppl never (voluntarily) exits, and therefore never returns a prompt. .PP Only one invocation of .C ppl is allowed to each remote host Internet address. .PP A unique local Internet address must be associated with each invocation of .CR ppl . This can be specified in the .C ppl.remotes file or it can be selected at run time from a pool of Internet addresses provided by .CR ppl.ipool. .SS SLIP over the DTC SLIP is supported over modem-to-DTC-LAN connections in binary mode up to 9600 baud for HP 9000/800 hosts. The SLIP configurations used over a mux connection should work over the DTC with the following exception. On the called host, the serial line parameter should be the device file name of a nailed DTC port as defined by the DDFA utility. .SS Log Files .C ppl keeps a log of its activities in .CR /var/ppl/log . .PP Another log can optionally be kept for creating bills or keeping track of serial line usage. If the file .C /var/ppl/bill exists, .C ppl adds an entry to this file each time it gracefully exits. The contents of the billing file are in human readable .SM ASCII form. The file is also program readable, suitable for export to various databases. It contains the following fields, separated by a semicolon (;) .CR \| : bill end time, bill start time, Local inetaddr, Remote inetaddr, login user name, tty name, and protocol. .PP The current status of all invocations of .C ppl are kept updated in the file .C /var/ppl/ptmp, if the file exists. .SS Lock Files .C ppl creates two lock files for each invocation of the program. These lock files serve three purposes: .RS .TP 3 \(bu They lock access to the Internet network address by encoding the Internet address (in hex) as part of the file name. .TP \(bu They contain various details about the connection. .TP \(bu They can be executed (by owner or root) as a shell script. When executed, they send a signal to .IR ppl , causing it to exit gracefully. .RE .PP Whenever .C ppl exits gracefully, it removes these lock files and releases resources. .PP If .C ppl uses a .SM UUCP line, it observes and creates .SM UUCP lock file protocol. .SS Gateway Packets .SM ASLIP is an abbreviated header enhancement to .SM SLIP. It provides throughput economy in non-gateway applications. One end of an .SM ASLIP line must act as a ``client''; the other end as a ``server''. Typically the client is a personal workstation; the server a larger machine. .PP The client sends non-gateway packets using .SM ASLIP and gateway packets using .SM SLIP. The server adapts its operation to the behavior of the client. .SM ASLIP operation must be specified in the .C ppl.remotes file. .SH FILES .PD 0 .TP 40 .C /etc/ppl/ppl.remotes all options for each remote connection .TP .C /etc/ppl/ppl.ipool pool of local Internet addresses that can be used .TP .C /etc/ppl/ppl.users translates users login name to a remote host .TP .CI /var/ppl/PPL. xxxx termination command file and lock file for local Internet address .TP .CI /var/ppl/ppl. xxxx termination command file and lock file for remote Internet address .TP .C /var/ppl/log audit trail and log file .TP .C /var/ppl/bill billing file (optional) .TP .C /var/ppl/ptmp status file (optional) .PD .SH AUTHOR .C ppl was developed by HP. .SH WARNINGS The log and bill files grow without bounds. .SH SEE ALSO pplstat(1), ppl.remotes(4), ppl.ipool(4), ppl.users(4), ppl.ptmp(4), .br .I Using Serial Line IP Protocols, .SM .I UUCP tutorial in .IR "Remote Access Users Guide" . .\" .\" index@\f4ppl\f1 \- point-to-point serial networking@@@\f3ppl(1)\f1 .\" index@point-to-point serial networking@@@\f3ppl(1)\f1 .\" index@serial networking, point-to-point@@@\f3ppl(1)\f1 .\" index@networking, point-to-point serial@@@\f3ppl(1)\f1 .\" .\" toc@\f3ppl(1)\f1:\0\0\f4ppl\f1@@@point-to-point serial networking .\" .\" links@ppl.1 slip.1 .\" links@ppl.1 cslip.1 .\" .\" fileset_database@ppl.1 USER-CMDS-MAN .\" $Header: csplit.1,v 76.2 95/08/01 16:25:39 ssa Exp $ .TA c .TH csplit 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME csplit \- context split .SH SYNOPSIS .C csplit .RC [ -s ] .RC [ -k ] .RC [ -f .IR prefix\| ] .RC [ -n .IR number ] .I file arg1 .RI [\|...\| argn\| ] .SH DESCRIPTION .C csplit reads .IR file , separates it into .IR n +1 sections as defined by the arguments .IR arg1 \ ... .IR argn , and places the results in separate files. The maximum number of arguments .RI ( arg1 through .IR argn ) allowed is 99 unless the .CI -n\0 number option is used to allow for more output file names. If the .CI -f\0 prefix option is specified, the resulting filenames are .IC prefix 00 through .I prefix\|NN where .I NN is the two-digit value of .I n using a leading zero if .I n is less than 10. If the .CI -f\0 prefix option is not specified, the default filenames .C xx00 through .CI xx NN are used. .I file is divided as follows: .IP .TS tab(;); cB cB cBw(3i) cB cB cB cf4 cI l. Default;Prefixed Filename;Filename;Contents _ xx00;prefix\f300\fP;T{ From start of \f2file\fP up to (but not including) the line referenced by \f2arg1\fP. T} xx01;prefix\f301\fP;T{ From the line referenced by \f2arg1\fP up to the line referenced by \f2arg2\fP. T} \|;\|;\h'.5i'. \|;\|;\h'.5i'. \|;\|;\h'.5i'. xx\f2NN\fP;prefix\f2NN\fP;T{ From the line referenced by \f2argn\fP to end of \f2file\fP. T} .TE .PP If the .I file argument is .CR - , standard input is used. .PP .C csplit supports the Basic Regular Expression syntax (see .IR regexp (5)). .SS Options .C csplit recognizes the following options: .RS .TP 15 .C -s Suppress printing of all character counts .RC ( csplit normally prints the character counts for each file created). .TP .C -k Leave previously created files intact .RC ( csplit normally removes created files if an error occurs). .TP .CI -f \0prefix Name created files .IC prefix 00 through .I prefixNN (default is .C xx00 through .CI xx NN\f1. .TP .CI -n\0 number The output file name suffix will use .I number digits instead of the default .C 2. This allows creation of more than 100 output files. .RE .PP Arguments .RI ( arg1 through .IR argn ) to .C csplit can be any combination of the following: .RS .TP 15 .CI / regexp / Create a file containing the section from the current line up to (but not including) the line matching the regular expression .IR regexp . The new current line becomes the line matching .IR regexp . .TP .CI / regexp /+ n .PD 0 .TP .CI / regexp /- n .sp -1v Create a file containing the section from the current line up to (but not including) the .IR n th before .RC ( - \f2n\fP) or after .RC ( + \f2n\fP) the line matching the regular expression .IR regexp . (e.g., .CR /Page/-5 ). The new current line becomes the line matching .ift .IR regexp \(+_ n .ifn \{.I regexp plus or minus .I n\} lines. .PD .TP .CI % regexp % equivalent to .CI / regexp /, except that no file is created for the section. .TP .I line_number Create a file from the current line up to (but not including) .IR line_number . The new current line becomes .IR line_number . .TP .CI { num } Repeat argument. This argument can follow any of the above argument forms. If it follows a .I regexp argument, that argument is applied .I num more times. If it follows .IR line_number , the file is split every .I line_number lines for .I num times from that point until end-of-file is reached or .I num expires. .RE .PP Enclose in appropriate quotes all .I regexp arguments containing blanks or other characters meaningful to the shell. Regular expressions must not contain embedded new-lines. .C csplit does not alter or remove the original file; it is the user's responsibility to remove it when appropriate. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the collating sequence used in evaluating regular expressions. .PP .C LC_CTYPE determines the characters matched by character class expressions in regular expressions. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_COLLATE or .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG. If any internationalization variable contains an invalid setting, .C csplit behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS Messages are self explanatory except for: .IP .C "arg - out of range" .PP which means that the given argument did not reference a line between the current position and the end of the file. This warning also occurs if the file is exhausted before the repeat count is. .SH EXAMPLES Create four files, .C cobol00 through .CR cobol03 . After editing the ``split'' files, recombine them back into the original file, destroying its previous contents. .IP .C "csplit -f cobol file '/procedure division/' /par5./ /par16./" .PP Perform editing operations .IP .C "cat cobol0[0-3] > file" .PP Split a file at every 100 lines, up to 10,000 lines (100 files). The .C -k option causes the created files to be retained if there are fewer than 10,000 lines (an error message is still printed). .IP .C "csplit -k file 100 '{99}'" .PP Assuming that .C prog.c follows the normal C coding convention of terminating routines with a .C } at the beginning of the line, create a file containing each separate C routine (up to 21) in .CR prog.c . .IP .C "csplit -k prog.c '%main(%' '/^}/+1' '{20}'" .SH SEE ALSO sh(1), split(1), environ(5), lang(5), regexp(5). .SH STANDARDS CONFORMANCE .CR csplit ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4csplit\f1 \- context split@@@\f3csplit(1)\f1 .\" index@files: context split@@@\f3csplit(1)\f1 .\" index@files: split file into multiple files@@@\f3csplit(1)\f1 .\" index@split file into multiple files@@@\f3csplit(1)\f1 .\" index@multiple files, split file into@@@\f3csplit(1)\f1 .\" .\" toc@\f3csplit(1)\f1:\0\0\f4csplit\f1@@@context split .\" $Header: ct.1,v 72.7 94/12/16 09:51:27 ssa Exp $ .TA c .TH ct 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ct \- spawn getty to a remote terminal (call terminal) .SH SYNOPSIS .C ct .RC [ -w .IR n\fP ] .RC [ -x .IR n\fP ] .RC [ -h ] .RC [ -v ] .RC [ -s .IR speed ] .IR telno ... .SH DESCRIPTION .CR ct dials .IR telno , the telephone number of a modem that is attached to a terminal, and spawns a .IR getty (1M) process to that terminal. .PP .CR ct tries each line listed in file .CR /etc/uucp/Devices until it finds an available line with appropriate attributes or runs out of entries. If no lines are free, .CR ct asks whether it should wait for a line, and if so, how many minutes it should wait before giving up. .CR ct searches again for an available line at one-minute intervals until the specified limit is exceeded. Note that normally, .CR ct disconnects the current tty line, so that the line can answer the incoming call. This is because .CR ct assumes that the current tty line is connected to the terminal to spawn the .CR getty process. .PP The .I telno argument specifies the telephone number, which can be composed of characters .CR 0 through .CR 9 , .CR - , .CR = , .CR * , and .CR # . Use equal signs to signify secondary dial tones and minus signs for delays at appropriate places. The maximum length of .I telno is 31 characters. If more than one telephone number is specified, .CR ct tries each in succession until one answers; this is useful for specifying alternate dialing paths. .PP When .CR ct disconnects the current line, .CR getty should not be spawned on this line if .CR ct is going to make use of the same line to reconnect. To do this, set the entry for this line in the .CR inittab file to .CR uugetty instead of .CR getty (see .IR inittab (4)). .SS Options .CR ct recognizes the following options and command-line arguments: .RS .TP 15 .CI -w n Instruct .CR ct to wait for a line a maximum of .I n number of minutes, if lines are busy. If this option is specified, .CR ct does not query the user about whether to wait for a line. .TP .CI -x n Produce detailed output from program execution on the standard error output. This option is used for debugging. The debugging level .I n is a single digit; the most useful value is .CR -x9 . .TP .CR -h Prevent .CR ct from disconnecting ("hanging up") the current tty line. This option is necessary if the user is using a different tty line than the one used by .CR ct to spawn the .CR getty . .TP .CR -v Verbose mode. The .CR -v option is used with the .CR -h option and causes .CR ct to send a running narrative to the standard error output stream. .TP .CI -s speed Set the data rate where .I speed is expressed in baud. The default rate is .CR 1200 . .RE .PP After the user on the destination terminal logs out, .CR ct prompts, .CR Reconnect? If the response begins with the letter .CR n the line is dropped. Otherwise, .CR getty is restarted and the .CR login: prompt is printed. .PP Of course, the destination terminal must be attached to a modem that can automatically answer incoming calls. .SH FILES .C /var/adm/ctlog .br .C /etc/uucp/Devices .SH SEE ALSO cu(1), login(1), uucp(1), getty(1M), uugetty(1M). .PP .\" .\" index@\f4ct\f1 \- spawn getty to remote terminal (call terminal)@@@\f3ct(1)\f1 .\" index@call terminal\- spawn getty to remote terminal@@@\f3ct(1)\f1 .\" index@getty to remote terminal, spawn (call terminal)@@@\f3ct(1)\f1 .\" index@remote terminal, spawn getty to (call terminal)@@@\f3ct(1)\f1 .\" index@spawn getty to remote terminal (call terminal)@@@\f3ct(1)\f1 .\" index@terminal: spawn getty to (call) remote terminal@@@\f3ct(1)\f1 .\" index@terminal, remote, spawn getty to (call terminal)@@@\f3ct(1)\f1 .\" .\" toc@\f3ct(1)\f1:\0\0\f4ct\f1@@@spawn getty to a remote terminal (call terminal) .\" .\" fileset_database@ct.1 USER-CMDS-MAN .\" $Header: ctags.1,v 76.1 95/08/01 16:29:03 ssa Exp $ .TA c .TH ctags 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctags \- create a tags file .SH SYNOPSIS .C ctags .RC [ -xvFBatwu ] .IR files \0... .SH DESCRIPTION .C ctags makes a tags file for .IR ex (1) (or .IR vi (1)) from the specified C, Pascal and F\s-2ORTRAN\s0 sources. A .B tags file gives the locations of specified objects (for C, functions, macros with argments, and typedefs; Pascal, procedures, programs and functions; F\s-2ORTRAN\s0, subroutines, programs and functions) in a group of files. Each line of the tags file contains the object name, the file in which it is defined, and an address specification for the object definition. Output is sorted in ascending collation order (see Environment Variables below). All objects except C .I typedefs are searched with a pattern, .I typedefs with a line number. Specifiers are given in separate fields on the line, separated by spaces or tabs. Using the .I tags file, .C ex can quickly find these objects' definitions. .RS .TP 8 .C -x Cause .C ctags to print a simple function index. This is done by assembling a list of function names, file names on which each function is defined, the line numbers where each function name occurs, and the text of each line. The list is then printed on the standard output. No .I tags file is created or changed. .TP .C -v Produce a page index on the standard output. This listing contains the function name, file name, and page number within that file (assuming 56-line pages to match .IR pr (1)). .RE .PP Files whose name ends in .C .c or .C .h are assumed to be C source files and are searched for C routine and macro definitions. Others are first examined to see if they contain any Pascal or F\s-2ORTRAN\s0 routine definitions; if not, they are processed again looking for C definitions. .PP Other options are: .RS .TP 8 .C -F Use forward searching patterns .RC ( / ... / ) (default). .TP .C -B Use backward searching patterns .RC ( ? ... ? ). .TP .C -a Add the information from the files to the .I tags file. Unlike re-building the .I tags file from the original files, this can cause the same symbol to be entered twice in the .I tags file. This option should be used with caution and then only in very special circumstances. .TP .C -t Create tags for typedefs. .TP .C -w Suppress warning diagnostics. .TP .C -u Update the specified files in .IR tags ; that is, all references to those files are deleted, and the new values are added to the file as in .C -a above. (Beware: this option is implemented in a way which is rather slow; it is usually faster to simply rebuild the .I tags file.) .RE .PP The tag .C main is treated specially in C programs. The tag formed is created by adding .C M to the beginning of name of the file, with any trailing .C .c removed, and leading pathname components also removed. This makes use of .C ctags practical in directories with more than one program. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the order in which the output is sorted. .PP .C LC_CTYPE determines the interpretation of the single- and/or multi-byte characters within comments and string literals. .PP If .C LC_COLLATE or .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C ctags behaves as if all internationalization variables are set to ``C''. See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported with the exception that multi-byte character file names are not supported. .SH DIAGNOSTICS .TP .C "Too many entries to sort." An attempt to get additional heap space failed; the sort could not be performed. .TP .CI "Unexpected end of function in file "file ", line " line . The tags file may be incorrect. .IP A .C } character was found unexpectedly in the first column. This can lead to incorrect entries in the .I tags file. .C ctags expects the source code to conform to the format as described on .IR cb (1). .TP .CI "Duplicate entry in file " file ", line " line ": name. Second entry ignored." The same name was detected twice in the same file. A .I tags entry was made only for the first name found. .TP .CI "Duplicate entry in files " file1 " and " file2 ": \f2name\fP (Warning only)." The same name was detected in two different files. A .I tags entry was made only for the first name found. .SH EXAMPLES Create a tags file named .C tags in the current directory for all C source .RC ( *.c ) files and all header .RC ( *.h ) files in the current directory: .IP .C "ctags *.[ch]" .PP Once the tags file exists in the current directory, it can be used with commands that support tag files (such as .C vi (see .IR vi (1)). .PP Use the tags file with .C vi to edit a particular function .C myfunc() located in one of the source files: .IP .C "vi -t myfunc" .PP While editing a C source file using .CR vi , use the .CR ex -mode tag command to edit function .CR myfunc() : .IP .C ":tag myfunc" .PP Use .C vi to find .C main() in file .CR myprog.c : .IP .C "vi -t Mmyprog" .PP While using .CR vi , find .C main() in file .C myprog.c (does not have to be the file currently being edited): .IP .C ":tag Mmyprog" .SH WARNINGS Recognition of .CR functions , .CR subroutines , and .C procedures for F\s-2ORTRAN\s0 and Pascal is done in a very simple way. No attempt is made to deal with block structure; if there are two Pascal procedures in different blocks with the same name, a warning message is generated. .PP The method of deciding whether to look for C or Pascal and \s-2FORTRAN\s0 functions is an approximation, and can be fooled by unusual programs. .PP .C ctags does not know about .C #ifdefs and Pascal types. .PP It relies on the input being well formed to detect .IR typedefs . .PP Use of .C -tx shows only the last line of typedefs. .PP .C ex is naive about .I tags files with several identical tags; it simply chooses the first entry its (non-linear) search finds with that tag. Such files can be created with either the .C -u or .C -a options or by editing a .I tags file. .PP If more than one (function) definition appears on a single line, only the first definition is indexed. .SH AUTHOR .C ctags was developed by the University of California, Berkeley. .SH FILES .TP 15 .C tags output tags file .TP .C OTAGS temporary file used by .C -u .SH SEE ALSO cb(1), ex(1), vi(1). .SH STANDARDS CONFORMANCE .CR ctags ": XPG4" .\" .\" index@\f4ctags\f1 \- create a tags file@@@\f3ctags(1)\f1 .\" index@create a tags file@@@\f3ctags(1)\f1 .\" index@files: create a tags file@@@\f3ctags(1)\f1 .\" index@tags file, create a@@@\f3ctags(1)\f1 .\" .\" toc@\f3ctags(1)\f1:\0\0\f4ctags\f1@@@create a tags file .\" .\" fileset_database@ctags.1 USER-CMDS-MAN .\" $Header: cu.1,v 78.1 96/01/03 15:01:18 ssa Exp $ .TA c .TH cu 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cu \- call another (\s-1UNIX\s+1) system; terminal emulator .SH SYNOPSIS .C cu .RC [ -s .IR speed\| ] .RC [ -l .IR line\| ] .RC [ -h ] .RC [ -q ] .RC [ -t ] .RC [ -d .IR level\| ] .RC [ -e \(or -o ] .RC [ -m ] .RC [ -n ] .RI [ \|telno\|\c .RI \(or \|systemname\c .RC \(or \|dir\| ] .SS XPG4 Syntax: .C cu .RC [ -s .IR speed\| ] .RC [ -l .IR line\| ] .RC [ -h ] .RC [ -q ] .RC [ -t ] .RC [ -d ] .RC [ -e \(or -o ] .RC [ -m ] .RC [ -n ] .RI [ \|telno\|\c .RI \(or \|systemname\c .RC \(or \|dir\| ] .SH DESCRIPTION .C cu calls up another system, which is usually a UNIX operating system, but can be a terminal or a non-UNIX operating system. .C cu manages all interaction between systems, including possible transfers of ASCII files. .SS Options .C cu recognizes the following options and command-line arguments: .RS .TP 15 .CI -s speed Specify the transmission speed (110, 150, 300, 600, 1200, 2400, 3600, 4800, 7200, 9600, 19200). The default value is 300. .TP .CI -l line Specify a device name to use as the communication line. This can be used to override searching for the first available line having the right speed. When the .C -l option is used without the .C -s option, the speed of a line is obtained from file .CR /etc/uucp/Devices . When the .C -l and .C -s options are used simultaneously, .C cu searches .C /etc/uucp/Devices to determine whether the requested speed for the requested line is available. If so, the connection is made at the requested speed; otherwise, an error message is printed and the call is not made. The specified device is usually a directly connected asynchronous line (such as .CR /dev/ttyapb ). In this case, a telephone number is not required, but the string .C dir can be used to specify that a dialer is not required. If the specified device is associated with an auto-dialer, a telephone number must be provided. .TP .C -h Emulate local echo, supporting calls to other computer systems that expect terminals to be set to half-duplex mode. .TP .C -q Use ENQ/ACK handshake (remote system sends ENQ, .C cu sends ACK\s0.) .TP .C -t Used when dialing an ASCII terminal that has been set to auto-answer. Appropriate mapping of carriage-return to carriage-return-line-feed pairs is set. .TP .CI -d level Print diagnostic traces. .I level is a number from 0-9, where higher .IR level s produce more detail in the diagnostic messages. .TP .CI -d (XPG4 only.) Print diagnostic traces. The level is always 9. .TP .CR -e \0( -o ) Generate even (odd) parity for data sent to the remote. .TP .C -m Specify a direct line that has modem controls. Modem controls are ignored by .CR cu . .TP .C -n Cause the telephone number that .C cu dials to be requested interactively from the user rather than taking it from the command line. .TP .I telno When using an automatic dialer, .I telno is the telephone number, with equal signs for secondary dial tone or minus signs for delays appropriately placed in the .I telno string. .TP .I systemname A UUCP system name can be used instead of a telephone number (see .IR uucp (1)); in this case, .C cu obtains an appropriate direct line or telephone number from .C /etc/uucp/Systems (including appropriate baud rate). .C cu dials each telephone number or direct line for .I systemname in the .C Systems file until a connection is made or all the entries are tried. .TP .C dir Using .C dir ensures that .C cu uses the line specified by the .C -l option. .RE .PP After making the connection, .C cu runs as two processes: .RS .TP 3 \(bu .I transmit process reads data from the standard input and, except for lines beginning with .CR ~ , passes it to the remote system; .TP \(bu .I receive process accepts data from the remote system and, except for lines beginning with .CR ~ , passes it to the standard output. .RE .PP Normally, an automatic DC\s03/\s-1DC\s01 protocol is used to control input from the remote to ensure that the buffer is not overrun. "Prompt handshaking" can be used to control transfer of ASCII files to systems that have no type-ahead capability but require data to be sent only after a prompt is given. This is described in detail below. Lines beginning with .C ~ have special meanings. .SS Transmit Process Commands The .I transmit process interprets the following commands: .RS .TP 15 .CR ~. , \0~.. Terminate the conversation. On hard-wired lines, .C ~. sends several EOF characters to log out the session, whereas .C ~.. suppresses the EOF sequence. In general the remote hard-wired machine is unaware of the disconnect if .C ~.. is used. On dial-up connections, .C ~. and .C ~.. do not differ. .TP .C ~! Escape to an interactive shell on the local system. .TP .CI ~! cmd\0... Run .I cmd on the local system (via .CR "sh -c" ). .TP .C ~& Similar to .C ~! but kill the receive process, restarting it upon return from the shell. This is useful for invoking sub-processes that read from the communication line where the receive process would otherwise compete for input. .TP .CI ~& cmd\0... Run .I cmd on the local system (via .CR "sh -c" ) and kill the receive process, restarting it later. .TP .CI ~| \|cmd Pipe incoming data from the remote system through the standard input to .I cmd on the local system. To terminate, reset with either a .C ~& or .C ~| command. .TP .C ~| Resets the receive process following a .CI ~|cmd command. .TP .CI ~$ cmd\0... Run .I cmd locally and send its output to the remote system. .TP .C ~%cd Change the directory on the local system. .IR Note : .C ~!cd causes the command to be run by a sub-shell, causing a return to the current directory upon completion. .TP .CI ~%take \0remote_source_file \0\f1[\fP \|local_destination_file\|\f1]\fP Copy file .I remote_source_file from the remote system to file .I local_destination_file on the local system. If .I local_destination_file is not specified, the .I remote_source_file argument is used in both places. .TP .CI ~%put \ local_source_file \ \f1[\fP \|remote_destination_file\|\f1] Copy file .I local_source_file on local system to file .I remote_destination_file on remote system. If .I remote_destination_file is not specified, the .I local_source_file argument is used in both places. .TP .CR ~~ \0... Send the line .CR ~ \0... to the remote system. If you use .C cu on the remote system to access a third remote system, send .C ~~. to cause the second remote .C cu to exit. .TP .C ~%break Transmit a BREAK to the remote system. .TP .C ~%nostop Toggle between DC3/DC1 input control protocol and no input control. This is useful if the remote system does not respond properly to the DC3 and DC1 characters. .TP .CI ~%< file Send the contents of the local file to the remote system using .I prompt handshaking. The specified file is read one line at a time, and each line is sent to the remote system when the .I prompt sequence is received. If no prompt is received by the time the .I prompt timeout occurs, the line is sent anyway. If the timeout is set to 0 seconds, or if the first character in the prompt sequence is a null character (\f3^@\fP), the handshake always appears to be satisfied immediately, regardless of whether or not the remote system generates a prompt. This capability is intended mainly to facilitate transfer of ASCII files from HP-UX to an HP 3000 system running MPE. This is usually accomplished by running the MPE .C FCOPY utility and giving the command .CI from=;to= destfile ;new and then running the .C cu input diversion to send the file to .C FCOPY which saves it in .IR destfile . This facility might be useful with other systems also, such as an HP 1000 running RTE. .TP .CI ~%setpt \0n Specify the number of seconds to wait for a prompt before giving up. The default is 2 seconds. Specifying a timeout of 0 seconds disables handshaking; that is, handshake appears to complete immediately. .TP .CI ~%setps \0xy Set the handshake prompt to the characters .IR xy . The default is DC1. The prompt can be any one or two characters. To specify a control character for .I x or .IR y , use the Ctrl-X form where a circumflex (ASCII 94) precedes the character, as in .CR ^X . A null character can be specified with \f3^@\f1. (A null first character in the prompt implies a "null" prompt, which always appears to be satisfied.) A circumflex is specified by .CR ^\|^ . .TP .CR ~%> [ > ]\f2file\fP Divert output from the remote system to the specified file until another .C ~%> command is given. When an output diversion is active, typing .C ~%> terminates it, whereas .C ~%> .I anotherfile terminates it and begins a new one. The output diversion remains active through a .C ~& subshell, but unpredictable results can occur if input/output diversions are intermixed with .C ~%take or .C ~%put. The .C ~%>> command appends to the named file. Note that these commands, which are interpreted by the .I transmit process, are unrelated to the .C ~> commands described below, which are interpreted by the receive process. .TP .CI ~ susp Suspend the .C cu session. .I susp is the suspend character set in the terminal when .C cu was invoked (usually .C ^Z \(em see .IR stty (1)). As in all other lines starting with tilde, a .CI ~ susp line must be terminated by pressing .BR Return . .SS Receive Process The .I receive process normally copies data from the remote system to its standard output. A line from the remote that begins with .C ~> initiates an output diversion to a file. The complete sequence is: .IP .CR ~> [ > ] : \|\f2file\fP .br zero or more lines to be written to .I file .br .C ~> .PP Data from the remote is diverted (or appended, if .C >> is used) to .IR file . The trailing .C ~> terminates the diversion. .PP The use of .C ~%put requires .IR stty (1) and .IR cat (1) on the remote side. It also requires that the current erase and kill characters on the remote system be identical to the current ones on the local system. Backslashes are inserted at appropriate places. .PP The use of .C ~%take requires that the remote system support the .C echo and .C cat commands (see .IR echo (1) and .IR cat (1). Also, .C stty tabs mode should be set on the remote system if tabs are being copied without expansion. When connecting to a machine that uses the eighth bit as a parity bit, .C stty istrip mode should be set on the local system. .PP When .C cu is used on system X to connect to system Y and subsequently used on system Y to connect to system Z, commands on system Y can be executed if .C ~~ is used. For example, using the keyboard on system X, .C uname can be executed on Z, X, and Y as follows where lines 1, 3, and 5 are keyboard commands, and lines 2, 4, and 6 are system responses: .nf .IP .C uname .C Z .C ~!uname .C X .C ~~!uname .C Y .fi .PP In general, .C ~ causes the command to be executed on the original machine; .C ~~ causes the command to be executed on the next machine in the chain. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the language in which messages are displayed. .PP If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C cu behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS Exit code is zero for normal exit; non-zero (various values) otherwise. .SH EXAMPLES To dial a system whose number is 9 201 555 1212 using 1200 baud: .IP .C "cu -s1200 9=2015551212" .PP If the speed is not specified, 300 is the default value. .PP To log in on a system connected by a direct line: .IP .CI "cu -l/dev/tty" XpX \0dir .PP To dial a system with the specific line and a specific speed: .IP .CI "cu -s1200 -l/dev/tty" XpX \0dir .RE .PP To dial a system using a specific line: .IP .CI "cu -l/dev/cul" XpX \02015551212 .PP To use a system name .RC ( yyyzzz ): .IP .C cu yyyzzz .PP To connect directly to a modem: .IP .CI "cu -l/dev/culXX -m dir cu -l/dev/cu1XX -m dir" .SH WARNINGS .C cu buffers input internally. .SH AUTHOR .C cu was developed by AT&T and HP. .SH FILES .nf .C /etc/uucp/Systems .C /etc/uucp/Devices .C /etc/uucp/Dialers .C /var/spool/locks/\s-1LCK\s+1..(tty-device) .C /dev/null .fi .SH SEE ALSO cat(1), ct(1), echo(1), stty(1), uname(1), uucp(1), uuname(1). .PP .SH STANDARDS CONFORMANCE .CR cu ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4cu\f1 \- call another \s-1(UNIX)\s0 system; terminal emulator@@@\f3cu(1)\f1 .\" index@call another \s-1(UNIX)\s0 system; terminal emulator@@@\f3cu(1)\f1 .\" index@\s-1(UNIX)\s0 system, call another; terminal emulator@@@\f3cu(1)\f1 .\" index@system, call another \s-1(UNIX)\s0; terminal emulator@@@\f3cu(1)\f1 .\" index@emulator, terminal; call another \s-1(UNIX)\s0 system@@@\f3cu(1)\f1 .\" index@terminal emulator; call another \s-1(UNIX)\s0 system@@@\f3cu(1)\f1 .\" .\" toc@\f3cu(1)\f1:\0\0\f4cu\f1@@@call another \s-1(UNIX)\s0 system; terminal emulator .\" .\" fileset_database@cu.1 USER-CMDS-MAN .\" $Header: cue.1,v 76.1 95/06/20 14:16:01 ssa Exp $ .TA c .TH cue 1 "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cue \- HP Character-Terminal User Environment \s-1(CUE)\s0 .SH SYNOPSIS .C /usr/bin/cue .\"[ .\".B \-D .\"screen_file .\"] .\".sp 1 .\".SH OPTIONS .\".PP .\".IP "\f3-file\fP \f2system_cueprofile\fP" .\"Allows a user to use the file specified rather than the general .\"\f2sys.cueprofile\fP. .SH DESCRIPTION .SM CUE provides an easy-to-use, attractive, customizable environment that allows users on Series 800 .SM HP-UX systems to easily identify themselves to the system and begin a work session. See .SM DEPENDENCIES for supported terminal types. .PP A menubar is available for changing the native language of the session, changing the type of session to start upon a successful login, or getting on-line help. To obtain context-sensitive help at any time, press the function key labeled .SM HELP .RI ( \|f\| 1\|). .PP A pulldown menu and function keys .RI ( \|f \|1- \|f \|8) are displayed, allowing the user to modify various options or to get help. Before the login is initiated, the user has the option of interactively changing the native language of the session and the type of session to start upon a successful login. .PP The default native language is C, but the language is easily modifiable by entering the Language Menu which is accessible by selecting the Configuration item in the menu bar. The native language can also be specified as a parameter to .CR cuegetty (see .IR cuegetty (1M)). .PP The default session type is the POSIX shell, .CR sh , but the session type can be easily changed to .CR tsm , .CR keysh , or .CR csh by entering the Session Type Menu which is accessible by selecting the Configuration item in the menu bar. .PP The following standard .CR login features are available: .RS .TP 3 \(bu password aging .TP \(bu logging invalid login attempts in .CR /var/adm/btmp .TP \(bu list of valid .I ttys for super-user login .\".TP .\"\(bu maximum number of users limited for restricted license .RE .PP .SM CUE displays a visual screen that prompts for the .I username and corresponding .IR password. If your username does not have a password, press the key to skip this field. Terminal echo is turned off (where possible) during typing of the password so that it will not appear on any written record of the session. After three unsuccessful login attempts, a .I hangup signal is issued. .PP If password aging has been invoked by the super-user on your behalf, your password may have expired. In this case, you will be diverted into .CR passwd to change it, after which you can attempt to login again. See .IR passwd (1). .PP If login is not successfully completed within a certain period of time (e.g., five minutes), the terminal may be silently disconnected. .PP After a successful login, the accounting files are updated, initializing the user and group ids, group access list, and working directory. If the session type chosen is .IR tsm , the .CR SHELL to start in each .I tsm session is determined from corresponding user entries in the .CR /etc/passwd file. .CR cue then forks the appropriate shell by using the last component of the shell pathname preceded by a .CR \- (for example, .CR \-sh or .CR \-ksh ). When the session type is invoked with its name preceded by a minus in this manner, the shell performs its own initialization, including execution of profile, login, or other initialization scripts. .PP For example, if the user login shell is .IR sh (1) or .IR ksh (1) the shell executes the profile files .CR /etc/profile and .CR $HOME/.profile if they exist (and possibly others as well). Depending on the contents of the profile files, messages regarding mail in your mail file or any messages you may have received since your last login may be displayed. At this point, .IR cuesession is started to perform accounting procedures, display messages, and start your session. .PP If .CR /var/adm/btmp is present, all unsuccessful login attempts are logged to this file. This feature is disabled if the file is not present. A summary of bad login attempts can be viewed by users with appropriate privileges by using .CR lastb , see .IR last (1M). .PP If .CR /etc/securetty is present, login security is in effect, meaning that only users with appropriate privileges are allowed to login successfully on the ttys listed in this file. Restricted ttys are listed by device name, one per line. Valid tty names are dependent on installation. Some examples could be .CR console , .CR tty01 , .CR ttya1 , etc. Note that this feature does not inhibit a normal user from using .CR su . .SS Starting Cue .PP There are several methods that can be used to start .CR cue . .RS .TP 3 \(bu An entry for .CR cuegetty can be placed in the .CR /etc/inittab file. See .IR cuegetty (1M)). This is the preferred method as the user does not need to do anything further to start .CR cue . .TP \(bu Start .CR cue from the command line by typing: .CR cue . .TP \(bu Start .CR cue by making it the last entry in the user's .CR .login configuration file. .PP Multiple .CR cue logins may run simultaneously on separate terminals attached to the same local host. .CR cuegetty can be configured in the .CR /etc/inittab file for all users. .\".PP .\"Multiple .\".I cuegetty(1M) .\"and .\".I getty(1)-login(1) .\"can be configured to run on specific user terminals providing that .\"terminals can be assured of receiving the same .\".I ttys .\"at each login. If this cannot be ensured and some .\"users don't want to run CUE, the CUE users can access .\"CUE via .\".I cue(1) .\"after the standard HP-UX .\".I login. .PP Remote users to the CUE system must access CUE by entering the .CR cue command at the command-line prompt or as the last item in the user's .CR .login configuration file. .SH EXTERNAL INFLUENCES .SS Environment Variables .CR cue invokes the user's session with the following default environment: .IP .CR CUESESSION is set to the session type selected .RS 20 valid values are : .TP 25 .C /usr/bin/sh POSIX Shell (DEFAULT) .TP .C /usr/bin/tsm manages up to 10 sessions at once .TP .C /usr/bin/keysh Easy Context-Sensitive Softkey Shell .TP .C /usr/bin/ksh Korn Shell .TP .C /usr/bin/csh C Shell .RE .RS .TP 15 .C HOME is set to the home directory of the user .TP .C LANG is set to the native language selected (C is the default) .TP .C LOGNAME is set to the user name .TP .C MAIL is set to .CR /var/mail/$LOGNAME .TP .C NLSPATH is set to the path applications search for NLS message catalogs, usually .CR /usr/lib/nls/%L/%N.cat .TP .C PATH is set to the path to be searched for commands .CR :/usr/bin .\" USER is set to the user name .TP .C SHELL is set to the user's default shell (from .CR /etc/passwd ) .\" TZ is set to the value of the \f3timeZone\fP resource .RE .PP Several methods are available to modify or add to this list depending on the desired scope of the resulting environment variable. .PP Basic environment variables can be set for all .SM CUE users on a system by setting the values in .CR /etc/profile and .CR /etc/csh.login . Personal environment variables can be set on a per-user basis in the script file .CR $HOME/.profile for .I sh and .I ksh users or .CR .cshrc for .I csh users. .PP Note that alias and function definitions need to be included in the file specified by .CR ENV for .IR ksh , as this file will be sourced for each invocation of the shell. For .I csh users, the .CR .cshrc file should be structured such that it cannot generate any output on standard output or standard error, including occasions when it is invoked without an affiliated terminal. The .CR rcp command sources the .CR .cshrc file and any output generated by this file, even to standard error, causes problems. Commands such as .CR stty should be placed in the .CR .login file, not in .CR .cshrc , so that their output cannot affect .CR rcp . .PP For users with appropriate privileges, .CR PATH is augmented to include .CR /etc . .ift .bp .SS VT320 Terminal Support Because the VT320 terminal has predefined local functions for keys labeled as F1, F2, F3 and F4, users should use following mapping when they desire to use function keys: .PP .RS .TP 20 HP or Wyse60 VT320 or HP 700/60 in VT320 mode .TP F1 PF2 .CR " !" .TP F2 PF1 .CR " !" .TP F3 space bar .TP F4 PF3 .CR " !" .TP F5 F10, [ EXIT ], F5 .CR " *" .TP F6 none .TP F7 F18, first unlabeled key to right of Pause/Break* .TP F8 F19, second unlabeled key to right of Pause/Break* .TP 5 .CR "*" - When using PC-AT keyboard with HP 700/60 in VT320 mode .TP .CR "!" - See "Configuration: HP 700/60 in DEC mode, or DEC terminals with PC-AT type keyboard" .RE .RS .PP Further, since DEC terminals do not support softkey menu, no such menu is displayed on these terminals. .PP Many applications tend to use TAB for forward navigation (moving from one field to another) and shift-TAB is used for backward navigation. Users having DEC terminals or using terminals in DEC emulation modes such as VT100 or VT320 may note that these terminals/emualtors may give out same character for TAB and shift-TAB. As such, it is impossible for an application to distinguish between TAB and shift-TAB, and both of them treated as if a TAB key was pressed. It might present slight overhead to users in case they want to go backwards. Now instead, they should complete rest of the inputs and get back to the desired field later. .PP .SS VT100 Terminal Support VT100 does not allow the (f1-f8) function keys to be configured. Therefore, the following keyboard mappings will apply to VT100 terminals: .RS .TP 20 HP or Wyse60 VT100 or HP 700/60 in VT100 mode .TP F1 PF2 .CR " !" .TP F2 PF1 .CR " !" .TP F3 space bar .TP F4 [PF3], [space bar] or [PF3], [=] .CR " !" .TP F5 return .TP F6 none .TP F7 none .TP F8 none .TP 5 .CR "!" - See "Configuration: HP 700/60 in DEC mode, or DEC terminals with PC-AT type keyboard" .RE .RS .PP Further, since DEC terminals do not support softkey menu, no such menu is displayed on these terminals. .PP Many applications tend to use TAB for forward navigation (moving from one field to another) and shift-TAB is used for backward navigation. Users having DEC terminals or using terminals in DEC emulation modes such as VT100 or VT320 may note that these terminals/emualtors may give out same character for TAB and shift-TAB. As such, it is impossible for an application to distinguish between TAB and shift-TAB, and both of them treated as if a TAB key was pressed. It might present slight overhead to users in case they want to go backwards. Now instead, they should complete rest of the inputs and get back to the desired field later. .PP .SS "Configuration: HP 700/60 terminal in DEC mode, or DEC terminal with PC-AT type keyboard" .PP Customers using the following configuration may want to be aware of the following keyboard difference. .PP It may be possible for a user with the "HP 700/60 terminal in DEC mode, or DEC terminal with PC-AT type keyboard" configuration to be told to press function key F1 through F4 to achieve some desired result. For HP 700/60 terminal in DEC mode or DEC terminals, these functions keys may be mapped onto PF1-PF4 keys. (see "Keyboard Mappings"). However, the PC-AT type keyboard does not provide PF1, PF2, PF3, or PF4 keys, as does the DEC/ANSI keyboard. .PP .B "Keyboard Mappings" .PP .RS .TP 20 "Num Lock" maps to "PF1" .TP "/" maps to "PF2" .TP "*" maps to "PF3" .TP "-" maps to "PF4" .RE .RS The "Num Lock", "/", "*", and "-" keys are located on the keyboard, in a row, above the number pad on the right side of the keyboard. Please note that although this keyboard is called a PC-AT type keyboard, it is supplied by HP. A PC-AT type keyboard can be recognized by location of ESC key at the left-top of the keyboard. .SS "Wyse60 Terminal Support" .PP On Wyse60, use DEL (located next to Backspace) key to backspace. On an HP 700/60 with a PC-AT type keyboard in Wyse60 mode, the DEL key is located in the bottom row on the number pad. .PP Wyse60 terminals provide a single line to display softkey labels unlike HP terminals which provide two lines. Sometimes this may result in truncated softkey labels. For example, "Help on Context" label for F1 may appear as "Help on C". Some standard labels for screen-oriented applications such as SAM and swinstall are as follows: .PP .RS .TP 35 On wyse60 may appear as .. means .TP Help On C Help On Context .TP Select/D Select/Deselect .TP Menubar Menubar on/off .RE .RS .SS Internationalization All screens, labels, and messages are localizable. The message catalog .CR cue.cat contains the localized representations of the default labels and messages. .CR cue will read the appropriate message catalog indicated by the .CR LANG environment variable and display the localized strings. By selecting a native language in the Language Menu, the language of the .SM CUE screens and the future work session can be specified. If the the message catalog exists for .CR cue in the language selected, .CR cue will be redisplayed in that language. If not, the .SM CUE screens will continue in the current language and the work session that is started after a successful login will be started in the language selected. In either case, the .CR LANG environment variable will be set appropriately for the resulting work session. .PP If .CR cue will be started on the command line or as the last item in the .CR .login file, the .SM CUE screens will be brought up using the language specified by the .CR LANG environment variable. If .SM CUE screens do not exist, then the default native language, C, will be used. .PP To use .CR cue with Asian languages, the .CR AWTERM environment variable must be set to .CR hpterm-asian . This will allow the text in Asian fonts to be displayed properly by .CR cue . .PP If .CR cue will be started by .CR cuegetty , it is possible to start up the .SM CUE Login Screens in a language other than the default, C, by invoking .CR cuegetty with the .CR \-L .IR nls_language option. Of course, .SM CUE screens and the .CR cue.cat file must exist for the .IR nls_language specified. .SH DEPENDENCIES .SM CUE is available only on Series 800 systems, and is compatible only with the following terminals: .IP HP\|700/92\h'.3i'HP\|700/94\h'.3i'HP\|2392\h'.3i'HP\|2394\h'.3i'VT\|320\h'.3i'VT\|100\h'.3i'WYSE\|60\h .SH FILES .PP .TP 40 .CR /var/adm/btmp history of bad login attempts .TP .CR /etc/logingroup group file \- defines group access lists .TP .CR /etc/motd message-of-the-day .TP .CR /etc/passwd password file \- defines users, passwords, and primary groups .TP .CR /etc/profile system profile (initialization for all users) .TP .CR /etc/securetty list of valid ttys for root login .TP .CR /etc/utmp users currently logged in .TP .CR /var/adm/wtmp history of logins, logouts, and date changes .TP .CI /var/mail/ your-name mailbox for user .IR your-name .TP .CR /usr/bin/cue .IR cue executable .TP .CR /usr/sbin/cuegetty .IR cuegetty executable .TP 50 .CR /usr/newconfig/etc/cue.inittab template for .IR /etc/inittab .TP 40 .CR /etc/cue.dm screen descriptions .TP .CR /usr/lbin/cuesession starts selected session type .TP .CR /usr/lib/nls/$LANG/cue.cat NLS message catalog .TP .CR /usr/share/man/man1.Z/cue.1 man page for .IR cue (1) .TP 50 .CR /usr/share/man/man1m.Z/cuegetty.1m man page for .IR cuegetty (1M) .SH SEE ALSO csh(1), cuegetty(1M), env(1), keysh(1), ksh(1), login(1), nlsinfo(1), passwd(1), sh(1), tsm(1), btmp(4), environ(5), hpnls(5), lang(5). .\" .\" toc@\f3cue(1)\f1:\0\0\f4cue\f1@@@HP Character-Terminal User Environment \s-1(CUE)\s0 .\" .\" index@\f4cue\f1 \- HP Character-Terminal User Environment \s-1(CUE)\s0@@@\f3cue(1)\f1 .\" index@\f1HP Character-Terminal User Environment \s-1(CUE)\s0@@@\f3cue(1)\f1 .\" index@\f1Character-Terminal User Environment \s-1(CUE)\s0, HP@@@\f3cue(1)\f1 .\" index@\f1User Environment \s-1(CUE)\s0, HP Character-Terminal@@@\f3cue(1)\f1 .\" index@\f1Environment \s-1(CUE)\s0, HP Character-Terminal User@@@\f3cue(1)\f1 .\" index@\s-1(CUE)\s0, HP Character-Terminal User Environment@@@\f3cue(1)\f1 .\" .\" index@\f1terminals, VT320, VT100, Wyse60@@@\f3cue(1)\f1 .\" index@\f1VT320 terminal@@@\f3cue(1)\f1 .\" index@\f1VT100 terminal@@@\f3cue(1)\f1 .\" index@\f1Wyse60 terminal@@@\f3cue(1)\f1 .\" .\" $Header: cut.1,v 76.1 95/08/01 16:30:58 ssa Exp $ .TA c .TH cut 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cut \- cut out (extract) selected fields of each line of a file .SH SYNOPSIS .C cut -c .I list .RI [ \|file " ...\|]" .br .C cut -b .I list .RC [ -n ] .RI [ \|file " ...\|]" .br .C cut -f .I list .RC [ -d .IR char\| ] .RC [ -s ] .RI [ \|file " ...\|]" .SH DESCRIPTION .C cut cuts out (extracts) columns from a table or fields from each line in a file; in data base parlance, it implements the projection of a relation. Fields as specified by .I list can be fixed length (defined in terms of character or byte position in a line when using the .C -c or .C -b option), or the length can vary from line to line and be marked with a field delimiter character such as the tab character (when using the .C -f option). .C cut can be used as a filter; if no files are given, the standard input is used. .PP When processing single-byte character sets, the .C -c and .C -b options are equivalent and produce identical results. When processing multi-byte character sets, when the .C -b and .C -n options are used together, their combined behavior is very similar, but not identical to the .C -c option. .SS Options Options are interpreted as follows: .RS .TP 15 .I list A comma-separated list of integer .I byte .RC (-b option), .I character .RC (-c option), or .I field .RC (-f option) numbers, in increasing order, with optional .C - to indicate ranges. For example: .RS .RS .TP .C 1,4,7 Positions 1, 4, and 7. .PD 0 .TP .C 1-3,8 Positions 1 through 3 and 8. .TP .C -5,10 Positions 1 through 5 and 10. .TP .C 3- Position 3 through last position. .PD .RE .RE .TP .CI -b \0list Cut based on a list of bytes. Each selected byte is output unless the .C -n option is also specified. .TP .CI -c \0list Cut based on character positions specified by .I list .RC ( "-c 1-72" extracts the first 72 characters of each line). .TP .CI -f \0list Where .I list is a list of fields assumed to be separated in the file by a delimiter character (see .CR -d ); for example, .C -f 1,7 copies the first and seventh field only. Lines with no field delimiters will be passed through intact (useful for table subheadings), unless .C -s is specified. .TP .CI -d \0char The character following .C -d is the field delimiter .CR ( -f option only). Default is .IR tab . Space or other characters with special meaning to the shell must be quoted. Adjacent field delimiters delimit null fields. .TP .C -n Do not split characters. If the high end of a range within a list is not the last byte of a character, that character is not included in the output. However, if the low end of a range within a list is not the first byte of a character, the entire character .I is included in the output." .TP .C -s Suppresses lines with no delimiter characters when using .C -f option. Unless .C -s is specified, lines with no delimiters appear in the output without alteration. .RE .SS Hints Use .C grep to extract text from a file based on text pattern recognition (using regular expressions). Use .C paste to merge files line-by-line in columnar format. To rearrange columns in a table in a different sequence, use .C cut and .CR paste . See .IR grep (1) and .IR paste (1) for more information. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text as single and/or multi-byte characters. .PP If .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C cut behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support The delimiter specified with the .C -d argument must be a single-byte character. Otherwise, single- and multi-byte character code sets are supported. .SH EXAMPLES Password file mapping of user \s-1ID\s+1 to user names: .IP .C "cut -d : -f 1,5 /etc/passwd" .PP Set environment variable .C name to current login name: .IP .ift \f4\s+1name=`who am i | cut -f 1 \-d " "`\fP\s0 .ifn \f3name=`who am i | cut -f 1 \-d " "`\fP .PP Convert file .C source containing lines of arbitrary length into two files where .C file1 contains the first 500 bytes (unless the 500th byte is within a multi-byte character), and .C file2 contains the remainder of each line: .IP .C "cut -b 1-500 -n source > file1" .br .C "cut -b 500- -n source > file2" .SH DIAGNOSTICS .TP 15 .C "line too long" Line length must not exceed .C LINE_MAX characters or fields, including the new-line character (see .IR limits (5). .TP .C "bad list for b/c/f option" Missing .CR -b , .CR -c , or .C -f option or incorrectly specified .IR list . No error occurs if a line has fewer fields than the .I list calls for. .TP .C "no fields" .I list is empty. .SH WARNINGS .C cut does not expand tabs. Pipe text through .IR expand (1) if tab expansion is required. .PP Backspace characters are treated the same as any other character. To eliminate backspace characters before processing by .CR cut , use the .C fold or .C col command (see .IR fold (1) and .IR col (1)). .SH AUTHOR .CR cut was developed by OSF and HP. .SH SEE ALSO grep(1), paste(1). .SH STANDARDS CONFORMANCE .CR cut ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4cut\f1 \- cut out selected fields of each line in a file@@@\f3cut(1)\f1 .\" index@extract selected fields of each line in a file@@@\f3cut(1)\f1 .\" index@fields of each line in a file, cut out (extract) selected@@@\f3cut(1)\f1 .\" index@files: cut out (extract) selected fields of each line in a file@@@\f3cut(1)\f1 .\" index@selected fields of each line in a file, cut out (extract)@@@\f3cut(1)\f1 .\" index@lines in a file, cut out (extract) selected fields of@@@\f3cut(1)\f1 .\" .\" toc@\f3cut(1)\f1:\0\0\f4cut\f1@@@cut out (extract) selected fields of each line of a file .\" $Header: date.1,v 76.3 95/08/23 16:59:38 ssa Exp $ .TA d .TH date 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" ------------------------------------------ .SH NAME date \- display or set the date and time .\" ------------------------------------------ .SH SYNOPSIS .CR date .RC [ \-u ] .PP .CR date .RC [ \-u ] .CI + format .PP .CR date .RC [ \-u ] .IR mmddhhmm [ yy ] .\" ------------------------------------------ .SH DESCRIPTION The .CR date command displays or sets the current HP-UX system clock date and time. Since the HP-UX system operates in Coordinated Universal Time (UTC), .CR date automatically converts to and from local standard or daylight/summer time, based on your .CR TZ environment variable. See "Environment Variables" in EXTERNAL INFLUENCES below. .\" ------------------------------------------ .SS "Options" .CR date recognizes the following option: .RS .TP .CR \-u Input and output values in Coordinated Universal Time (UTC), functionally equivalent to Greenwich Mean Time (GMT), instead of in local time. .RE .\" ------------------------------------------ .SS "Formats" The .CR date command has two forms for displaying the date and time and one form for setting them. .RS .TP 8 .CR date \0[ \-u ] .IP Display the current date and time. The output is the same as for the .CR %c formatting directive for all languages except the .CR C default language. See "Formatting Directives" and EXAMPLES below. .TP .CR date \0[ \-u ]\0 + \f2format\fP .RS .PP Display the current date and time according to formatting directives specified in .IR format , which is a string of zero or more formatting directives and ordinary characters. If it contains blanks, enclose it in apostrophes or quotation marks. .PP A formatting directive has the following syntax: .IP .CR % [\|[ - \(or 0 ]\f2width\fP][\c .CR . \f2prec\fP]\f2char\fP .PP where .I width specifies the field width, .I prec specifies the precision, and .I char is the directive code. See "Formatting Directives" and "Field Width and Precision" below for more details. .PP All ordinary characters are copied unchanged into the output string. .PP The output string is always terminated with a newline character. .PP If .CR + is specified and .I format is omitted, only a newline is output. .RE .TP .CR date \0[ \-u "]\0\f2mmddhhmm\f1[\f2yy\f1]" .IP Set the HP-UX system clock to the date and time specified. You require the superuser privilege. .IP If you include the .CR \-u option, the specified date and time is assumed to be in Coordinated Universal Time (UTC). .IP The numeric argument is interpreted left to right in two-digit pairs as follows: .RS .RS .TP .PD 0 .I mm Month number .RC [ 01 - 12 ]. .TP .I dd Day number in the month .RC [ 01 - 31 ]. .TP .I hh Hour number (24-hour system) .RC [ 00 - 23 ]. .TP .I mm Minute number .RC [ 00 - 59 ]. .TP .I yy Last two digits of the year number .RC [ 70 - 99 , .CR 00 - 69 " (1970-1999, 2000-2069)]." If omitted, the current year is used. .PD .RE .PP If you attempt to set the date backwards, .CR date generates the warning, .IP .CR "do you really want to run time backwards?[yes/no]" .PP Type .CR yes or the equivalent for your locale to set the clock backwards; anything else to cancel the command. .PP When .CR date is used to set the date, a pair of date change records is written to the file .CR /var/adm/wtmp . .PP (XPG4 only.) No warning is generated if date is set backwards. .PP .RE .RE .RE .\" ------------------------------------------ .ne 7 .SS "Formatting Directives" The following formatting directives, shown without the optional field width and precision specification, are replaced by the indicated characters. If a directive is not one of the following, the result is undefined. .PP The output for digits, characters, and words depends on the language/locale settings. See "Environment Variables" in EXTERNAL INFLUENCES below. .PP The examples assume that the .CR date command was executed on .\" Wed Jan 12 19:45:58 1994 Wednesday, January 12, 1994 at 7:45:58 p.m.\& Pacific Standard Time, using the .CR C default language. .RS .TP .CR %a Abbreviated weekday name. For example, .CR Wed . .TP .CR %A Full weekday name. For example, .CR Wednesday . .TP .CR %b Abbreviated month name. For example, .CR Jan . .TP .CR %B Full month name. For example, .CR January . .TP .CR %c Current date and time representation. For example, .CR "Wed Jan 12 19:45:58 1994" . .TP .CR %C Century (the year divided by 100 and truncated to an integer) as a two-digit decimal number .RC [ 00 - 99 ]. For example, .CR 19 . .TP .CR %d Day of the month as a two-digit decimal number .RC [ 01 - 31 ]. For example, .CR 12 . .TP .tr ~" .CR %e Day of the month as a two-character decimal number with leading space fill .RC [~ \01 ~-~ 31 ~]. For example, .CR 12 . .br .tr ~~ .TP .CR %E Combined Emperor/Era name and year. .\" For example, .TP .CR %H Hour (24-hour clock) as a two-digit decimal number .RC [ 00 - 23 ]. For example, .CR 19 . .TP .CR %I Hour (12-hour clock) as a two-digit decimal number .RC [ 01 - 12 ]. For example, .CR 07 . .TP .CR %j Day of the year as a three-digit decimal number .RC [ 001 - 366 ]. For example, .CR 012 . .TP .CR %m Month as a decimal two-digit number .RC [ 01 - 12 ]. For example, .CR 01 . .TP .CR %M Minute as a decimal two-digit number .RC [ 00 - 59 ]. For example, .CR 45 . .TP .CR %n Newline character. .TP .CR %N Emperor/Era name. .\" For example, .TP .CR %o Emperor/Era year. .\" For example, .TP .CR %p Equivalent of either AM or PM. For example, .CR PM . .TP .CR %S Second as a two-digit decimal number (allows for possible leap seconds) .RC [ 00 - 61 ]. For example, .CR 58 . .TP .CR %t Tab character. .TP .CR %u Weekday as a one-digit decimal number .RC [ 1 - 7 " (Monday-Sunday)]." For example, .CR 3 . .TP .CR %U Week number of the year (Sunday as the first day of the week) as a two-digit decimal number .RC [ 00 - 53 ]. All days that precede the first Sunday in the year are considered to be in week .CR 00 . For example, .CR 02 . .TP .CR %V Week number of the year (Monday as the first day of the week) as a two-digit decimal number .RC [ 01 - 53 ]. If the week containing January 1 has four or more days in the new year (January 1 is Thursday or sooner), it is designated as week .CR 01 ; otherwise, (January 1 is Friday or later), it is designated as week .CR 53 of the previous year, and the next week is week .CR 01 . For example, .CR 02 . .TP .CR %w Weekday as a one-digit decimal number .RC [ 0 - 6 " (Sunday-Saturday)]." For example, .CR 3 . .TP .CR %W Week number of the year (Monday as the first day of the week) as a two-digit decimal number .RC [ 00 - 53 ]. All days that precede the first Monday in the year are considered to be in week .CR 00 . For example, .CR 02 . .TP .CR %x Current date representation. For example, .CR 01/12/94 . .TP .CR %X Current time representation. For example, .CR 19:45:58 . .TP .CR %y Year without century as a two-digit decimal number .RC [ 00 - 99 ]. For example, .CR 93 . .TP .CR %Y Year with century as a four-digit decimal number .RC [ 1970 - 2069 ]. For example, .CR 1994 . .TP .CR %Z Time zone name (or no characters if time zone cannot be determined). For example, .CR PST . .TP .CR %% The .CR % character. .RE .SS Obsolescent Directives The following directives are provided for backward compatibility. It is recommended that the preceding directives be used instead. .RS .TP .CR %D Date in usual U.S.\& format. For example, .CR 01/12/94 . Use .CR %x or .CR %m/%d/%y instead. .TP .CR %F Full month name. For example, .CR January . Use .CR %B instead. .TP .CR %h Abbreviated month name. For example, .CR Jan . Use .CR %b instead. .TP .CR %r Time in 12-hour U.S.\& format. For example, .CR "07:45:58 PM" . Use .tr ~" .CR ~%I:%M:%S\ %p~ instead. .br .tr ~~ .TP .CR %T Time in 24-hour U.S.\& format. For example, .CR 19:45:58 . Use .CR %X or .CR %H:%M:%S instead. .TP .CR %z Time zone name (or no characters if time zone cannot be determined). For example, .CR PST . Use .CR %Z instead. .RE .\" ------------------------------------------ .SS "Modified Formatting Directives" Some Formatting Directives can be modified by the .C E and .C O modifier characters to indicate a different format or specification for the language specified in the .C LC_TIME environment variable. .PP If the corresponding keyword .RC ( era , .CR era_year , .CR era_d_fmt , and .CR alt_digit ) is not specified or not supported, the unmodified field descriptor value is used. The command .IP .CI "LC_ALL=" language "\& locale -ck era era_year era_d_fmt alt_digit" .PP displays the keywords and their values in the specified .IR language (see .IR locale (1)). .RS .TP 10 .CR %EC The name of the base year in alternate representation. .TP .C %Ex Alternate date representation. .TP .CR %Ey Offset from .CR %EC (year only) in the alternate representation. .TP .CR %Od Day of month using the alternate numeric symbols. .TP .CR %Oe Day of month using the alternate numeric symbols with leading space-character fill if applicable. .TP .CR %OH Hour (24-hour clock) using the alternate numeric symbols. .TP .CR %OI Hour (12-hour clock) using the alternate numeric symbols. .TP .CR %Om Month using the alternate numeric symbols. .TP .CR %OM Minutes using the alternate numeric symbols. .TP .CR %OS Seconds using the alternate numeric symbols. .TP .CR %OU Week number of the year (Sunday is the first day of the week) using the alternate numeric symbols. .TP .CR %Ow Weekday as number using the alternate numeric symbols .RC (Sunday= 0 ). .TP .CR %OW Weekday number of the year (Monday is the first day of the week) using the alternate numeric symbols. .TP .CR %Oy Year (offset from .CR %C ) in alternate representation. .RE .\" ------------------------------------------ .ne 8 .SS "Field Width and Precision" An optional field width and precision specification can immediately follow the initial .CR % of a formatting directive in the following order: .RS .TP 12 .RC "[" "\-" "\(or" "0" "]\f2width\fP" The decimal digit string .IR width specifies a .IR minimum field width in which the result of the conversion is right- or left-justified. The default is right-justified with space padding on the left. If the string starts with "\c .CR \-\c ", the result is left-justified with space padding on the right. If the string starts with "\c .CR 0\c ", the result is right-justified and padded with zeros on the left. .TP .CI \. prec The decimal digit string .IR prec specifies the .IR minimum number of digits to appear for the .CR d , .CR H , .CR I , .CR j , .CR m , .CR M , .CR o , .CR S , .CR U , .CR w , .CR W , .CR y , and .CR Y numeric directives. If a directive supplies fewer digits than specified by the precision, it will be expanded with leading zeros. .IP .IR prec specifies the .IR maximum number of characters to be used from the .CR a , .CR A , .CR b , .CR B , .CR c , .CR D , .CR E , .CR F , .CR h , .CR n , .CR N , .CR p , .CR r , .CR t , .CR T , .CR x , .CR X , .CR z , .CR Z , and .CR % text directives. If a directive supplies more characters than specified by the precision, excess characters are truncated on the right. .RE .PP If no field width or precision is specified for a .CR d , .CR H , .CR I , .CR m , .CR M , .CR S , .CR U , .CR W , or .CR y directive, the default is .CR .2 ; for the .CR j directive, the default is .CR .3 ; for .CR Y , the default is .CR .4 ; for .CR w , the default is .CR .1 . .\" ------------------------------------------ .SH EXTERNAL INFLUENCES .\" ------------------------------------------ .SS "Environment Variables" .PP .CR LC_CTYPE determines the interpretation of the bytes within the .IR format string as single- and/or multi-byte characters. .PP .CR LC_NUMERIC determines the characters used to form numbers for those directives that produce numbers in the output. The characters used are those defined by .CR alt_digit (see .IR locale (1) and .CR ALT_DIGIT in .IR langinfo (5)). .PP .CR LC_TIME determines the content (for example, the weekday names produced by the .CR %a directive) and format (for example, the current time representation produced by the .CR %X directive) of date and time strings output by the .CR date command. .PP .CR LC_MESSAGES determines the language in which messages (other than the date and time strings) are displayed. .PP If .CR LC_CTYPE , .CR LC_NUMERIC , .CR LC_TIME , or .CR LC_MESSAGES is not specified or is null, it defaults to the value of .CR LANG . .PP If .CR LANG is not specified or is null, it defaults to .CR C (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to .CR C (see .IR environ (5)). .PP .CR TZ determines the conversion between the system time in UTC and the time in the user's local time zone. See .IR environ (5) and .IR tztab (4). .CR TZ also determines the content (that is, the time-zone name produced by the .CR %z and .CR %Z directives) of date and time strings output by the .CR date command. .PP If .CR TZ is not set or is set to the empty string, its default value is .CR EST5EDT . .\" ------------------------------------------ .SS "International Code Set Support" Single- and multi-byte character code sets are supported. .\" ------------------------------------------ .SH DIAGNOSTICS The following messages may be displayed. .br .ne 4 .TP 8 .C bad conversion .IP The date/time specification is syntactically incorrect. Check that there are eight or ten decimal digits, with each pair in the correct range. .br .ne 3 .TP .CI "bad format character - \&" "c" .IP The character .IR c is not a valid format directive, field width specifier, or precision specifier. .br .ne 4 .TP .CR "do you really want to run time backwards?[yes/no]" .IP The date/time you specified is earlier than the current clock value. Type .CR yes (or the equivalent for your locale) to set the clock backwards; anything else to cancel the command. .br .ne 3 .TP .C no permission .IP You need the superuser privilege to change the date. .\" ------------------------------------------ .SH EXAMPLES .\" ------------------------------------------ .SS "Date in Different Languages" Display the date. In this example, the .CR TZ environment variable contains .CR PST8PDT , and the language environment variables are set as noted. .nf .ifn .PP .ift .IP .CR "date " \(-> " Fri Aug 20 15:03:37 PDT 1993 " "\(<- " C " (default)" .CR "date -u " \(-> " Fri Aug 20 22:03:37 UTC 1993 " "\(<- " C " (default)" .CR "date " \(-> " Fri, Aug 20, 1993 03:03:37 PM " "\(<- " en_US.roman8 " (U.S.\& English)" .CR "date " \(-> " Fri. 20 Aug, 1993 03:03:37 PM " "\(<- " en_GB.roman8 " (U.K.\& English)" .CR "date " \(-> " 20/08/1993 15.47.47 " "\(<- " pt_PT.roman8 " (Portuguese)" .fi .\" ------------------------------------------ .SS "Set Date" Set the date to Oct 8, 12:45 a.m. .IP .C date 10080045 .\" ------------------------------------------ .SS "Display Formatted Date" Display the current date and time using a format. Note the use of quotation marks due to the blanks in the format. .IP .C "date ""+DATE: %m/%d/%y%nTIME: %H:%M:%S""" .PP The output resembles the following: .IP .C "DATE: 10/08/87" .br .C "TIME: 12:45:05" .\" ------------------------------------------ .SS "Display Formatted Date Using Local Language Conversion" With the date as set in the "Set Date" example above and .CR LC_TIME set to .CR de_De.roman8 (German): .IP .C date +\'%-4.4h %2.1d %H:%M\' .PP generates output similar to: .IP .C "Okt 8 12:45" .PP where the month field is four characters long, flush-left, and space-padded on the right if the month name is shorter than four characters. The day field is two characters long, with leading zeros suppressed. .\" ------------------------------------------ .SH WARNINGS .PP The former HP-UX format directive .CR A has been changed to .CR W for ANSI compatibility. .PP Changing the date while the system is running in multiuser mode should be avoided to prevent disrupting user-scheduled and time sensitive programs and processes. Also, changing the date can cause .IR make (1) and the SCCS and .IR cron (1M) subsystems to behave in an unexpected manner. The .CR cron daemon should be killed prior to setting the date backwards, then restarted. SCCS files should be checked with the .CR val command (see .IR val (1)) if deltas have been made while the clock was wrongly set. .PP Currently, the maximum date supported is December 31, 2030 23:59:00 UTC. .\" Notes by allanp (940207). See also at(1) and crontab(1M). .\" (Exactly: Jan 19, 2038 03:14:07 UTC; rolls to Dec 13, 1901 20:45:52 UTC) .\" Probably related to the maximum 32-bit signed integer, 2147483647. .\" ------------------------------------------ .SH AUTHOR .CR date was developed by AT&T and HP. .\" ------------------------------------------ .SH FILES .CR /var/adm/wtmp .\" ------------------------------------------ .SH SEE ALSO locale(1), nlsinfo(1), stime(2), ctime(3C), strftime(3C), tztab(4), environ(5), lang(5), langinfo(5). .\" ------------------------------------------ .SH STANDARDS CONFORMANCE .CR date ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4date\f1 \- display or set the system-clock date and time@@@\f3date(1)\f1 .\" .\" index@\f1clock, system, display current date and time or set to new value@@@\f3date(1)\f1 .\" index@\f1Coordinated Universal Time (UTC)@@@\f3date(1)\f1 .\" index@\f1date, display current or set to new value@@@\f3date(1)\f1 .\" index@\f1display current system-clock date and time@@@\f3date(1)\f1 .\" index@\f1environment variable, \f4TZ\f1@@@\f3date(1)\f1 .\" index@\f1print current system-clock date and time@@@\f3date(1)\f1 .\" index@\f1set current system-clock date and time to new value@@@\f3date(1)\f1 .\" index@\f1show current system-clock date and time@@@\f3date(1)\f1 .\" index@\f1system clock, display current date and time or set to new value@@@\f3date(1)\f1 .\" index@\f1time zone display@@@\f3date(1)\f1 .\" index@\f1time, display current or set to new value@@@\f3date(1)\f1 .\" index@\f4TZ\f1 environment variable@@@\f3date(1)\f1 .\" index@\f1UTC, Coordinated Universal Time@@@\f3date(1)\f1 .\" .\" toc@\f3date(1)\f1:\0\0\f4date\f1@@@display or set the system-clock date and time .\" -*-Text-*- .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .\" .\" (c) Copyright 1987, Hewlett-Packard Company, all rights reserved. .\" .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .TH DATEBOOK 1 "" "" .ad b .SH NAME datebook \- calendar and reminder program for X11 .SH SYNOPSIS .B "datebook [-W] [-V] [-D \fIdate\fP] [-F \fIdatefile\fP]" .SH DESCRIPTION Datebook is a personal appointment calendar. It was written to solve the never ending problem of forgetting when you need to attend a meeting, go to the doctor, or phone home. Datebook provides calendar features, that let you enter and review events for a particular day or week, as well as reminder features that notify you before particular events. Each activity or appointment entered into Datebook is considered an event. Events that are specified with a time will generate alarms. In the X11 environment, an alarm will cause an alarm window to appear on the user's screen. This window will present the user with the option to acknowledge, delay (snooze) or delete the event in question. Outside of X11 the user can have datebook call a program or script when the alarm occurs (see AlarmNotify). Events can be classified into various event classes. Each class can have a different amount of time that the user will be warned in advance of the event. For example, for local meetings you might want 5 minutes warning, but if the meeting is offsite 30 minutes warning would be more appropriate. The class can also specify the time to "snooze" before repeating an alarm. The class can also be used to specify a bitmap to be displayed in the alarm window. .SH OPTIONS .TP 8 .B -W List the events for the next week to stdout. This option will not bring up X windows and will therefore work outside of X. .TP 8 .B -D \fIdate\fP This option is like the list week option, but it only lists the events for a particular date. This date should be in a simple date (month, day and year) like 12/14/89 or November 28. If used in combination with \fB-W\fP the week starting at \fIdate\fP will be listed. .TP 8 .B -F \fIdatefile\fP This option allows the user to start with one or more (one -F option per file) date files instead of the date files specified by the ~/.datebookrc file. .TP 8 .B -V Turns on the verbose mode. The program will print additional information about the program state. .SH Display The calendar window is composed of three parts: previous and next month buttons, a pull-down menu bar, and the calendar portion. There are two pull-down menus labeled "Cmds" and the name and year of the current month. The first allows access to a number of commands while the second can be used to display the calendar for different months. In the calendar portion, the left mouse button will select (highlight) a date and display a browser on that date. The browser window is also composed of three major parts, the event list portion, the buttons portion and the event specification portion. In the event list portion each line is composed of fields which summarize the event. The fields in the list are: the starting time of the event (if specified), the ending time of the event (if specified), and the first line of the event. The left mouse button in the event list portion will select an event, and display the complete event specification in the bottom portion of the window. The event specification is composed of the \fIDate Specification\fP, a \fIDescription\fP, an optional \fIstart time\fP , an optional \fIend time\fP, the \fIclass\fP of the event and the \fIfile\fP to which the event belongs. Between the list of events and the event specification is a row of buttons that operate on event list and the event specification. The \fICreate Event\fP button will create a new event from the specifications. The \fIDelete Selection\fP button will delete the event that is selected in the event list. The \fIClear Template\fP button will remove all data in the event specification portion but does not affect the event list. The \fIReplace Selection\fP button will substitute the data in the event specification portion for that in the currently selected event. On the browser title bar will be found a left and a right arrow. These can be used to browse the next or previous date, week or file (depending of the current browser contents). .SH $HOME/.\fIrcfile\fP Facets of the Datebook program not related to window appearance can be controlled by the appropriate entries in your ~/.\fIrcfile\fP. If the ~/.\fIrcfile\fP does not exist, then the file /usr/lib/X11/datebook/\fIrcfile\fP will be checked. Note that the rc file name depends on the name of the program. If the name is datebook then the files searched for are ~/.datebookrc and /usr/lib/X11/datebook/datebookrc, renaming datebook to be datebk would cause it to look in the files ~/.datebkrc and /usr/lib/X11/datebook/datebkrc respectively. .TP 8 .B DateFiles This is the single most important value as it allows the user to specify which event files to read in when the program is started. Some of these files will be owned by the user and others may be files that are common to a project, section, etc. The user will only be allowed to edit, delete from, or add to files that are \fBowned\fP by him. For this reason, at least one of the files in this list should be owned by the user. Defaults to ``~/.events''. A relative file name will be interpreted to be relative to $HOME. .TP 8 .B Snooze: Determines how many minutes to delay when the user responds to an alarm with the snooze button. At the end of that time the alarm will be redisplayed. This is the default snooze time. The snooze time can also be set on the basis of the event class. .TP 8 .B PrintWeek: Specifies a program that will read the data to be printed on its standard input and send it to a printer. This program must be written to parse the standard datebook week summary format. The programs \fBdbweek\fP and \fBdbweek_ps\fP (postscript) are shipped with datebook. .TP 8 .B PrintMonth: Specifies a program that will read the data to be printed on its standard input and send it to a printer. This program must be written to parse the standard datebook month summary format. The programs \fBdbmonth\fP and \fBdbmonth_ps\fP (postscript) are shipped with datebook. .TP 8 .B Morning: The Morning entry can be used to save some typing. When the user says the meeting is at 2:00, it is rare for this to mean 2 AM, and yet that is how the program will interpret this input without the setting of this entry. If the hour is less than 12, then 12 is added to it to map it into the PM range. This will only be used then to map times that are not specified with AM or PM. Morning must be an integer. .sp If Morning is not set, then the program will interpret and display time in 24 hour notation. .TP 8 .B AlarmNotify: When datebook is started from outside the X11 environment, this entry determines the program to call with the alarm message. After this program has been called, the alarm will be acknowledged. There is no way to snooze or to delete events from outside X11. .TP 8 .B Check How often (in seconds) should datebook check to see if it is the time for any event. .TP 8 .B Synchronize How many times should datebook check for alarms between checking to see if the date files need to be synchronized. If Check were 30 seconds and Synchronize were 2 then datebook would check the datefiles every minute. .TP 8 .B Hidden This entry is followed by the class names of events that should not show up in the calendar. They will display alarms in the normal fashion. A typical use for Hidden event classes would be an everyday event telling you to go home. Hidden classes also are not printed (Print Month, Print Week) or listed (-W, -D). .TP 8 .B Common This entry is followed by the class names of events that should not show up in the calendar. They will appear in the browser and will display alarms in the normal fashion. A typical use for Common event classes would be meetings that occur periodically (every Monday perhaps). The calendar could then highlight days with unusual (uncommon) events. .TP 8 .B Classes: This entry describes the event classes enclosed in {}'s. In the example .datebookrc below, one of the classes specified is ``meeting''. There is then an entry ``meeting: 10 2 stop Red''. This entry specifies that the user wishes to be notified 10 minutes before a meeting, to snooze 2 minutes, the stop bitmap to be used in the alarm window, and the stop bitmap to be red. The syntax of a class entry is: .nf \fBclassname\fP: \fIwarning\fP [\fIsnooze\fP [\fIbitmap\fP [\fIfg_color\fP [\fIbg_color\fP]]]] .fi where fg_color and bg_color specify what foreground and background colors to use to display the bitmap in the alarm window. .LP .ne 17 .nf One sample ~/.\fIrcfile\fP might look like: # this is my rc file DateFiles: .appts .birthdays /usr/lib/X11/datebook/holidays Snooze: 5 Morning: 6 Check: 30 Synchronize: 1 PrintWeek: dbweek "lp -or" PrintMonth: dbmonth | lp Hidden: nag Common: periodic Classes { periodic: 10 5 remind meeting: 10 2 stop Red offsite: 30 5 nag: 0 10 michael birthday: 0 5 cake trip: 0 5 camera } .fi .SH "Menu Commands" A number of commands are available via the pulldown menus. .TP 8 .B Version This command displays the version dialog. .TP 8 .B View Week Change the cursor to prompt the user for a week to view (browse). When the user picks a week, then the browser will be changed to display all events of that week. .TP 8 .B View File Browse the events that are contained in a particular date file. .TP 8 .B View Year Bring up the year at a glance window. Picking on a particular month in this window will change the monthly calendar to the month selected. .TP 8 .B Print Week Change the cursor to prompt the user for a week to print. When the user picks a week, then the week will be formatted and printed using the program specified by the PrintWeek entry in the ~/.\fIdatebookrc\fP file. .TP 8 .B Print Month The events for the currently displayed month will be formatted and printed using the program specified by the PrintMonth entry in the ~/.\fIdatebookrc\fP file. .TP 8 .B Write Events The user will not usually need to explicitly write events. They are written when the browser is closed or when the user quits the program. .TP 8 .B Synchronize Datefiles The user will not usually need to explicitly synchronize datefiles. The program will periodicly check to see if date files have been modified and will attempt to reparse and merge changed files. .TP 8 .B Highlight Classes This command displays a dialog that will allow the user to change whether any class is Common or not (see above). Common classes are not highlighted on the calendar. The most common way to use this dialog would be to make all but a certain class Common to see if for instance there where any birthdays or meetings this month. .TP 8 .B Quit Update all event files and exit the datebook program. .SH $HOME/.Xdefaults The visual appearance of the datebook windows is controlled by the .Xdefaults file in your home directory (or equivalent) and the file /usr/lib/X11/datebook/app-defaults/Datebook. It might be useful to look at the app-defaults file for Datebook to see what resources can be set, many are resources that are specific to the HP/Motif Widgets that datebook is built from. .TP 8 .B datebook.BitmapPath: Specifies the directories to look in to find bitmaps used for the event classes. The default path is "/usr/lib/X11/datebook/bitmaps". .TP 8 .B datebook.showDayNames: Indicates if daynames are to be shown the calendar window. Default is yes. .TP 8 .B datebook.showClock: Indicates if clock is to be shown the calendar window. Default is yes. .TP 8 .B datebook.traversalOn: Indicates if keyboard traversal is to be enabled in the text-edit widgets of the browser window. If set to \fBTrue\fP then the mouse will no longer control the which text-edit widget gets the keyboard input but rather the highlighted widget will get all keystrokes until one of the keyboard traversal keys is used. \fICntrl Next\fP is the standard way to traverse to the next widget. In datebook the \fIReturn\fP key will traverse to the next widget if the current widget can only hold a single line. In addition the \fItab\fP key will traverse to the next and \fIShift Tab\fP to the previous widget. .TP 8 .B datebook.colorToday: A boolean that indicates if the \fBdatebook.todayForground\fP and \fBdatebook.todayBackground\fP should be used to set the color of the button for today in the calendar window. .TP 8 .B datebook.todayForground: Indicates the foreground (text) color of the button for today in the calendar window. .TP 8 .B datebook.todayBackground: Indicates the background color of the button for today in the calendar window. .B datebook.colorEvents: A boolean that indicates if the \fBdatebook.eventForground\fP and \fBdatebook.eventBackground\fP should be used to set the color of the buttons that represent days that have events. Note that this variable does not affect the three dimensional look of the buttons which is always used. .TP 8 .B datebook.eventForground: Indicates the foreground (text) color of buttons in the calendar window that have scheduled events. .TP 8 .B datebook.todayBackground: Indicates the background color of the buttons in the calendar window that have scheduled events. .LP .ne 17 .nf One sample ~/.Xdefaults might look like: datebook.BitmapPath: /usr/lib/X11/datebook/bitmaps # use a bigger font for the clock datebook*clock*fontList: ncenR18 # color today yellow datebook.colorToday: yes datebook.todayForeground: black datebook.todayBackground: yellow # color event days a little darker than the rest datebook.colorEvents: yes datebook.eventForeground: black datebook.eventBackground: MediumSlateBlue # some overall colors datebook*topShadowColor: #B0D0FF datebook*Foreground: White datebook*Background: SlateBlue datebook*bottomShadowColor: DarkSlateBlue # Menus datebook*menub*background: SteelBlue datebook*menu*Background: SteelBlue datebook*menu*bottomShadowColor: MidnightBlue datebook*menu*topShadowColor: LightSteelBlue # the static text areas datebook*XmLabel*Foreground: Yellow # Places where you can type datebook*XmText*Background: MediumSlateBlue datebook*XmText*topShadowColor: LightSteelBlue datebook*XmText*bottomShadowColor: MidnightBlue .fi .SH Date SPECIFICATION The date specification for Datebook can take many forms. The simplest form is a single date. Periodic events can also be specified using some of the more advanced constructs. (The exact syntax is covered the the datebook(4) man page.) Some sample date specifications are: .nf March 18, 1989 2 weeks before 12/25/89 3rd weekday during 12/89 1 month after yesterday October 10 Monday 2nd Tuesday Aug 1 - Aug 5 Tuesday and Thursday between Jan 1 and Mar 15 Thursday after January 19 Everyday Everymonth 5 Tuesday except April 25 Every 2nd Tue starting 26 December 89 .fi The first four will be single events, the rest will be repeating events. .SH SEE ALSO datebook(4), calendar(1), cron(1) .\" -*-Text-*- .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .\" (c) Copyright 1989, Hewlett-Packard Company, all rights reserved. .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .TH DBMONTH_PS 1 "" "HP-UX" .ad b .SH NAME dbmonth \- datebook monthly calendar formatter for postscript printers .SH SYNOPSIS .B dbmonth_ps -p [-r radius] .SH DESCRIPTION This program formats the monthly summary format from the \fBdatebook\fP program for printing on a postscript printer. This program currently prints two consectutive months in landscape mode on an 8.5 x 11 inch sheet of paper. .SH OPTIONS .TP 8 .B -p \fIprinter cmd\fP this switch specifes the program to which the output is piped. There is no default. .TP 8 .B -r This option causes the output to be rotated 90 degrees. .SH SEE ALSO datebook(1), dbweek_ps(1), dbweek(1) .\" -*-Text-*- .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .\" (c) Copyright 1989, Hewlett-Packard Company, all rights reserved. .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .TH DBWEEK 1 "" "HP-UX" .ad b .SH NAME datebook \- Datebook weekly calendar formatter for laserjet printers .SH SYNOPSIS .B dbweek [-e] [-l] [\fIprinter\fP] .SH DESCRIPTION This program formats the weekly summary format from the \fBDatebook\fP program for printing on a laserjet printer. This program currently prints one week at a time in landscape mode. .SH OPTIONS .TP 8 .B -e Use european paper sizes instead of american (the default). .TP 8 .B -l Allign the summary to the left side of the page. .TP 8 .B \fIprinter\fP this option specifes the program to which the output is piped. The default is "lp -or". .SH SEE ALSO datebook(1), dbweek_ps(1) .\" -*-Text-*- .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .\" (c) Copyright 1989, Hewlett-Packard Company, all rights reserved. .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .TH DBWEEK_PS 1 "" "HP-UX" .ad b .SH NAME dbweek \- datebook weekly calendar formatter for postscript printers .SH SYNOPSIS .B dbweek_ps -p [-r radius] .SH DESCRIPTION This program formats the weekly summary format from the \fBdatebook\fP program for printing on a postscript printer. This program currently prints two consectutive weeks in landscape mode on an 8.5 x 11 inch sheet of paper. .SH OPTIONS .TP 8 .B -p \fIprinter cmd\fP this switch specifes the program to which the output is piped. There is no default. .TP 8 .B -r \fIradius\fP This option causes the boxes around the weekdays to be rounded with the specified radius. By default, square boxes are used. An example would be \fB-r 18\fB. The units are 1/72 of an inch (1 point). .SH SEE ALSO datebook(1), dbweek(1), dbmonth_ps(1) .\" $Header: dc.1,v 72.3 93/01/14 11:27:58 ssa Exp $ .TA d .TH dc 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dc \- desk calculator .SH SYNOPSIS .C dc .RI [ \|file\| ] .SH DESCRIPTION .C dc is an arbitrary precision arithmetic package. Ordinarily it operates on decimal integers, but one may specify an input base, output base, and a number of fractional digits to be maintained. (See .IR bc (1), a preprocessor for .C dc that provides infix notation and a C-like syntax that implements functions. .C bc also provides reasonable control structures for programs.) The overall structure of .C dc is a stacking (reverse Polish) calculator. If an argument is given, input is taken from that file until its end, then from the standard input. An end of file on standard input or the .C q command stop dc. The following constructions are recognized: .RS .TP 15 .I number The value of the number is pushed on the stack. A number is an unbroken string of the digits .CR 0 - 9 or .CR A - F . It can be preceded by an underscore .RC ( _ ) to input a negative number. Numbers can contain decimal points. .TP .C "+ - / * % ^" The top two values on the stack are added .RC ( + ), subtracted .RC ( - ), multiplied .RC ( * ), divided .RC ( / ), remaindered .RC ( % ), or exponentiated .RC ( ^ ). The two entries are popped off the stack; the result is pushed on the stack in their place. Any fractional part of an exponent is ignored and a warning generated. The remainder is calculated according to the current scale factor; it is not the integer modulus function. .C 7 % 3 yields .1 (one tenth) if scale is 1 because .C 7 / 3 is 2.3 with .1 as the remainder. .TP .CI s x The top of the stack is popped and stored into a register named .IR x , where .I x can be any character. If the .C s is capitalized, .I x is treated as a stack and the value is pushed on it. .TP .CI l x The value in register .I x is pushed on the stack. Register .I x is not altered. All registers start with zero value. If the .C l is capitalized, register .I x is treated as a stack and its top value is popped onto the main stack. .TP .C d The top value on the stack is duplicated. .TP .C p The top value on the stack is printed. The top value remains unchanged. .C P interprets the top of the stack as an .SM ASCII string, removes it, and prints it. .TP .C f All values on the stack are printed. .TP .C q exits the program. If executing a string, the recursion level is popped by two. If .C q is capitalized, the top value on the stack is popped and the string execution level is popped by that value. .TP .C x treats the top element of the stack as a character string and executes it as a string of .C dc commands. .TP .C X replaces the number on the top of the stack with its scale factor. .TP .CR [ \|...\| ] puts the bracketed .SM ASCII string onto the top of the stack. Strings can be nested by using nested pairs of brackets. .TP .CI < x \h'.2i'> x \h'.2i'= x .PD 0 .TP .CI !< x \h'.2i'!> x \h'.2i'!= x The top two elements of the stack are popped and compared. Register .I x is evaluated if they obey the stated relation. .PD .TP .C v Replaces the top element on the stack by its square root. Any existing fractional part of the argument is taken into account, but otherwise the scale factor is ignored. .TP .C ! Interprets the rest of the line as an .SM HP-UX system command (unless the next character is .CR < , .CR > , or .CR = , in which case appropriate relational operator above is used). .TP .C c All values on the stack are popped. .TP .C i The top value on the stack is popped and used as the number radix for further input. .TP .C I pushes the input base on the top of the stack. .TP .C o The top value on the stack is popped and used as the number radix for further output. See below for notes on output base. .TP .C O pushes the output base on the top of the stack. .TP .C k the top of the stack is popped, and that value is used as a non-negative scale factor: the appropriate number of places are printed on output, and maintained during multiplication, division, and exponentiation. The interaction of scale factor, input base, and output base will be reasonable if all are changed together. .TP .C K pushes the scale factor on the top of the stack. .TP .C z The stack level is pushed onto the stack. .TP .C Z replaces the number on the top of the stack with its length. .TP .C ? A line of input is taken from the input source (usually the terminal) and executed. .TP .CR ; " and " : Used by .C bc for array operations. .TP .C Y Generates debugging output for .C dc itself. .PP The input base may be any number, but only the digits 0-9 and A-F are available for input, thus limiting the usefulness of bases outside the range 1-16. All 16 possible digits may be used in any base; they always take their conventional values. .PP The output base may be any number. Bases in the range of 2-16 generate the "usual" results, with the letters A-F representing the values from 10 through 16. Bases 0 and 1 generate a string of .CR 1 s whose length is the value of the number. Base \(mi1 generates a similar string consisting of .CR d s. Other bases have each "digit" represented as a (multi-digit) decimal number giving the ordinal of that digit. Each "digit" is signed for negative bases. "Digits" are separated by spaces. Given the definition of output base, the command .C Op always yields "10" (in a representation appropriate to the base); .C O1-p yields useful information about the output base. .RE .SH DIAGNOSTICS .TP 25 .IC x " is unimplemented" Where .I x is an octal number. .TP .C stack empty There are insufficient elements on the stack to do what was asked. .TP .C Out of space The free list is exhausted (too many digits). .TP .C Out of headers Too many numbers are being kept around. .TP .C Out of pushdown Too many items are on the stack. .TP .C Nesting Depth There are too many levels of nested execution. .SH EXAMPLES This example prints the first ten values of n! (n factorial): .nf .IP .C [la1+dsa*pla10>y]sy .C 0sa1 .C lyx .fi .SH SEE ALSO bc(1). .PP .I "DC: An Interactive Desk Calculator" tutorial in .IR "Number Processing Users Guide" . .\" .\" index@\f4dc\f1 \- desk calculator@@@\f3dc(1)\f1 .\" index@arithmetic desk calculator@@@\f3dc(1)\f1 .\" index@desk calculator@@@\f3dc(1)\f1 .\" index@calculator, desk@@@\f3dc(1)\f1 .\" .\" toc@\f3dc(1)\f1:\0\0\f4dc\f1@@@desk calculator .\" .\" fileset_database@dc.1 USER-CMDS-MAN .\" $Header: dd.1,v 78.1 96/01/22 22:19:50 ssa Exp $ .TA d .TH dd 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dd \- convert, reblock, translate, and copy a (tape) file .SH SYNOPSIS .C dd .RI [ option\c .C =\c .IR value ]\0... .SH DESCRIPTION .CR dd copies the specified input file to the specified output with possible conversions. The standard input and output are used by default. Input and output block size can be specified to take advantage of raw physical I/O. .SS Options .CR dd recognizes the following .IC option = value pairs: .RS .TP 15 .CI if= file Input file name; default is standard input. .TP .CI of= file Output file name; default is standard output. The output file will be created using the same owner and group used by creat(). .TP .CI ibs= n Input block size is .I n bytes (default 512). .TP .CI obs= n Output block size is .I n bytes (default 512). .TP .CI bs= n Set both input and output block size to the same size, superseding .CR ibs and .CR obs . This option is particularly efficient if no conversion is specified, because no in-core copy is necessary. .TP .CI cbs= n Conversion buffer size is .I n .IR bytes . .TP .CI skip= n Skip .I n input blocks before starting copy. .TP .CI seek= n Seek .I n blocks from beginning of output file before copying. This option is ignored on a raw magnetic tape device. See .IR mt (1) for information about operations on raw magnetic tape devices. .TP .CI count= n Copy only .I n input blocks. .TP .CI conv= option Data conversion option. Use one of the following: .sp .5v .RS .RS .TP 18 .C conv=ascii Convert EBCDIC to ASCII. .TP .CR conv=ebcdic Convert ASCII to EBCDIC .TP .C conv=ibm Convert ASCII to EBCDIC using an alternate conversion table .TP .C conv=lcase Map US ASCII alphabetics to lowercase .TP .C conv=ucase Map US ASCII alphabetics to uppercase .TP .C conv=swab Swap every pair of bytes .TP .C conv=noerror Do not stop processing on an error .TP .C conv=sync Pad every input block to input block size (ibs) .TP .C conv=notrunc Do not truncate existing file on output .TP .C conv=block Convert input record to a fixed length specified by .C cbs .TP .C conv=unblock Convert fixed length records to variable length .TP .CR conv= ... , \0... Multiple comma-separated conversions .RE .RE .RE .PP Where sizes are required, .I n indicates a numerical value in bytes. Numbers can be specified using the forms: .RS .TP 10 .I n for .I n bytes .PD 0 .TP .IC n k for .I n Kbytes .RI ( n \(mu 1024), .TP .IC n b for .I n blocks .RI ( n \(mu 512), or .TP .IC n w for .I n words .RI ( n \(mu 2). .RE .PD .PP To indicate a product, use .C x to separate number pairs. .PP The .C cbs option is used when .CR block , .CR unblock , .CR ascii or .CR ebcdic conversion is specified. In case of .CR ascii , .I cbs characters are placed into the conversion buffer, converted to ASCII, trailing blanks are trimmed, and a new-line is added before sending the line to the output. In case of .CR ebcdic , ASCII characters are read into the conversion buffer, converted to EBCDIC, and blanks are added to make up an output block of size .IR cbs . .PP Upon completion, .CR dd reports the number of whole and partial input and output records. .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multibyte character code sets are supported. .SS Environment Variables The following environment variables will affect execution of .CR dd : .PP .CR LANG determines the locale when .CR LC_ALL and a corresponding variable (beginning with .CR LC_ ) do not specify a locale. .PP .CR LC_ALL determines the locale used to override any values set by .CR LANG or any environment variables beginning with .CR LC_ . .PP The .CR LC_CTYPE variable determines the locale for the interpretation of sequences of bytes of text data as characters ( single/multiple byte characters, upper/lower case characters ). .PP The .CR LC_MESSAGES variable determines the language in which messages should be written. .SH RETURN VALUE Exit values are: .RS .TP 8 .C \00 Successful completion. .PD 0 .TP .C >0 Error condition occurred. .RE .PD .SH DIAGNOSTICS .TP 25 .IC f + p " records in" Number of full and partial blocks read. .PD 0 .TP .IC f + p " records out" Number of full and partial blocks written. .PD .SH EXAMPLES Read an EBCDIC tape blocked ten 80-byte EBCDIC card images per block into an ASCII file named .CR x : .IP .C "dd if=/dev/rmt/c0t0d0BEST of=x ibs=800 cbs=80 conv=ascii,lcase" .PP Note the use of the raw magnetic tape device file. .CR dd is especially suited to I/O on raw physical devices because it allows reading and writing in arbitrary block sizes. .SH WARNINGS You may experience trouble writing directly to or reading directly from a cartridge tape. For best results, use .IR tcio (1) as an input or output filter. For example, use .IP .RC ...\0 |dd \0...\0 "|tcio -ovVS 256 /dev/rct/c4t1d0" .PP for output to a cartridge tape, or .IP .CR "tcio -ivS 256 /dev/rct/c4t1d0 |dd " \0...\0 | \0... .PP for input from a cartridge tape. .PP Some devices, such as 1/2-inch magnetic tapes, are incapable of seeking. Such devices must be positioned prior to running .CR dd by using .IR mt (1) or some other appropriate command. .PP ASCII and EBCDIC conversion tables are taken from the 256-character ACM standard, Nov, 1968. The .C ibm conversion, while less widely accepted as a standard, corresponds better to certain IBM print train conventions. There is no universal solution. .PP New-line characters are inserted only on conversion to ASCII; padding is done only on conversion to EBCDIC. These should be separate options. .PP If .CR if or .CR of refers to a raw disk, .CR bs should always be a multiple of sector size of disk. The default bs size used by .CR dd is 512 bytes. If sector size of disk is different from 512 bytes, a .CR bs multiple of sector size should be specified. The character special (raw) device file should always be used for devices. .PP It is entirely up to the user to insure there is enough room in the destination file, filesystem and/or device to contain the output since .CR dd(1) cannot pre-determine the required space after conversion. .SH SEE ALSO cp(1), mt(1), tr(1), disk(7), mt(7). .SH STANDARDS CONFORMANCE .CR dd ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4dd\f1 \- convert, reblock, translate, and copy a (tape) file@@@\f3dd(1)\f1 .\" index@convert, reblock, translate, and copy a (tape) file@@@\f3dd(1)\f1 .\" index@tape files: convert, reblock, translate, and copy@@@\f3dd(1)\f1 .\" index@alter contents of and copy a (tape) file@@@\f3dd(1)\f1 .\" index@reformat and copy a (tape) file@@@\f3dd(1)\f1 .\" index@change data format of and copy a (tape) file@@@\f3dd(1)\f1 .\" index@reblock, convert, translate and copy a (tape) file@@@\f3dd(1)\f1 .\" index@translate, convert, reblock and copy a (tape) file@@@\f3dd(1)\f1 .\" .\" toc@\f3dd(1)\f1:\0\0\f4dd\f1@@@convert, reblock, translate, and copy a (tape) file .\" .\" $Header: delta.1,v 76.2 95/08/01 17:12:46 ssa Exp $ .TA d .TH delta 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME delta \- make a delta (change) to an SCCS file .SH SYNOPSIS .C delta .RC [ -r .SM .I SID\c \|] .RC [ -s ] .RC [ -n ] .RC [ -g .IR list \|] .RC [ -m .IR mrlist \|] .RC [ -y .IR comment \|] .RC [ -p ] .I files .SH DESCRIPTION The .CR delta command is used to permanently introduce into the named .SM SCCS file changes that were made to the file retrieved by .CR get (called the .IR g-file , or generated file). See .IR get (1). .PP .CR delta makes a delta to each named .SM SCCS file. If a directory is named, .CR delta behaves as though each file in the directory was specified as a named file, except that non-\c .SM SCCS files (last component of the path name does not begin with .CR .s ) and unreadable files are silently ignored. If a name of .CR - is given, the standard input is read (see .SM WARNINGS\s0). Each line of the standard input is taken to be the name of an .SM SCCS file to be processed. .PP .CR delta may issue prompts on the standard output, depending upon certain options specified and flags (see .IR admin (1)) that may be present in the .SM SCCS file (see the .CR -m and .CR -y options below). .SS Options Option arguments apply independently to each named file. .RS .TP 15 .CI -r \s-1SID\s0 Uniquely identifies which delta is to be made to the .SM SCCS file. Use of this option is necessary only if two or more outstanding .CR get s for editing .RC ( "get -e" ) on the same .SM SCCS file were done by the same person (login name). The .SM .I SID value specified with the .CR -r option can be either the .SM .IR SID specified on the .CR get command line or the .SM .I SID to be made as reported by the .CR get command (see .IR get (1)). A diagnostic results if the specified .SM .I SID is ambiguous, or, if necessary and omitted on the command line. .TP .CR -s Suppresses issuing, on the standard output, of the created delta's .SM .I SID as well as the number of lines inserted, deleted and unchanged in the .SM SCCS file. .TP .CR -n Specifies retention of the edited .IR g-file (normally removed at completion of delta processing). .TP .CI -g list Specifies a .IR list (see .IR get (1) for the definition of .IR list ) of deltas which are to be .I ignored when the file is accessed at the change level .RI ( \s-1SID\s0 ) created by this delta. .TP .CR -m [\f2mrlist\fP] If the .SM SCCS file has the .CR v flag set (see .IR admin (1)), a Modification Request (\s-1MR\s0) number .I must be supplied as the reason for creating the new delta. .IP If .CR -m is not used and the standard input is a terminal, the prompt .C MR\s0s? is issued on the standard output before the standard input is read. If the standard input is not a terminal, no prompt is issued. The .C MR\s0s? prompt always precedes the .CR comments? prompt (see the .CR -y option). .IP .SM MR\s0s in a list are separated by blanks and/or tab characters. An unescaped new-line character terminates the .SM MR list. .IP Note that if the .CR v flag has a value (see .IR admin (1)), it is assumed to be the name of a program (or shell procedure) that is to validate the correctness of the .SM MR numbers. If a non-zero exit status is returned from the .SM MR number-validation program, .CR delta assumes that the .SM MR numbers were not all valid and terminates. .TP .CR -y [\f2comment\fP] Arbitrary text used to describe the reason for making the delta. A null string is considered a valid .IR comment . .IP If .CR -y is not specified and the standard input is a terminal, the prompt .CR comments? is issued on the standard output before the standard input is read. If the standard input is not a terminal, no prompt is issued. An unescaped new-line character terminates the comment text. .TP .C -p Causes .CR delta to print (on the standard output in a .IR diff (1) format) the .SM SCCS file differences before and after the delta is applied. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .CR LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR delta behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS Use .IR sccshelp (1) for explanations. .SH WARNINGS .SM SCCS files can be any length, but the number of lines in the text file itself cannot exceed 99\|999 lines. .PP Lines beginning with an .SM ASCII SOH character (octal 001) cannot be placed in the .SM SCCS file unless the .SM SOH is escaped. This character has special meaning to .SM SCCS (see .IR sccsfile (4)) and will cause an error. .PP A .CR get of many .SM SCCS files, followed by a .CR delta of those files, should be avoided when the .CR get generates a large amount of data. Instead, multiple .CR get / delta sequences should be used. .PP If the standard input .RC ( - ) is specified on the .CR delta command line, the .CR -m (if necessary) and .CR -y options .I must also be present. Omission of these options causes an error. .PP Comments are limited to text strings not exceeding 512 characters. .SH FILES All of the auxiliary files listed below, except for the .IR g-file , are created in the same directory as the .IR s-file (see .IR get (1)). The .IR g-file is created in the user's working directory. .RS .PD 0 .TP 25 .IR g-file Existed before the execution of .CR delta ; removed after completion of .CR delta (unless .CR -n was specified). .TP .IR p-file Existed before the execution of .CR delta ; may exist after completion of .CR delta . .TP .IR q-file Created during the execution of .CR delta ; removed after completion of .CR delta . .TP .IR x-file Created during the execution of .CR delta ; renamed to .SM SCCS file after completion of .CR delta . .TP .IR z-file Created during the execution of .CR delta ; removed during the execution of .CR delta . .TP .IR d-file Created during the execution of .CR delta ; removed after completion of .CR delta . .TP .CR /usr/bin/bdiff Program to compute differences between the file retrieved by .CR get and the .IR g-file . .PD .RE .SH SEE ALSO admin(1), bdiff(1), cdc(1), get(1), sccshelp(1), prs(1), rmdel(1), sccsfile(4). .SH STANDARDS CONFORMANCE .CR delta ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4delta\f1 \- make a delta (change) to an SCCS file@@@\f3delta(1)\f1 .\" index@\f1make a delta (change) to an SCCS file@@@\f3delta(1)\f1 .\" index@\f1SCCS: make a delta (change) to an SCCS file@@@\f3delta(1)\f1 .\" index@\f1files: make a delta (change) to an SCCS file@@@\f3delta(1)\f1 .\" index@\f1delta (change) to an SCCS file, make a@@@\f3delta(1)\f1 .\" index@\f1change (delta) to an SCCS file, make a@@@\f3delta(1)\f1 .\" .\" toc@\f3delta(1)\f1:\0\0\f4delta\f1@@@make a delta (change) to an SCCS file .\" .\" $Header: deroff.1,v 76.1 95/07/10 16:56:43 ssa Exp $ .TA d .TH deroff 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME deroff \- remove nroff, tbl, and neqn constructs .SH SYNOPSIS .C deroff .RC [ -m\c .IR x \|] .RC [ -w ] .RC [ -i ] .RI [ \|file \0...\|] .SH DESCRIPTION .C deroff reads each .I file in sequence and removes all .C nroff requests, macro calls, backslash constructs, .C neqn constructs (between .SM .C \&.EQ and .SM .C \&.EN lines, and between delimiters \(em see .IR neqn (1)), and .C tbl descriptions (see .IR tbl (1)), replacing them with white space (blanks and blank lines), and writes the remainder of the file on the standard output. .C deroff follows chains of included files .RC ( .so and .C .nx .CR nroff / troff formatter commands); if a file has already been included, a .C .so naming that file is ignored and a .C .nx naming that file terminates execution. If no input file is given, .C deroff reads the standard input. .PP The .C -m option can be followed by an .CR m , .CR s , or .CR l . The .C -mm option causes the macros be interpreted such that only running text is output (that is, no text from macro lines). The .C -ml option forces the .C -mm option and also causes deletion of lists associated with the .C mm macros. .PP If the .C -w option is given, the output is a word list, one ``word'' per line, with all other characters deleted. Otherwise, the output follows the original, with the deletions mentioned above. In text, a ``word'' is any multi-byte character string or any string that contains at least two letters and is composed of letters, digits, ampersands .RC ( & ), and apostrophes .RC ( ' ); In a macro call, however, a ``word'' is a multi-byte character string or a string that begins with at least two letters and contains a total of at least three letters. Delimiters are any characters other than letters, digits, apostrophes, and ampersands. Trailing apostrophes and ampersands are removed from ``words.'' .PP If the .C -i option is specified, .C deroff ignores the .C .so and .C .nx .CR nroff / troff commands. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text and filenames as single and/or multi-byte characters. Note that multi-byte punctuation characters are not recognized when using the .CR -w option. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C deroff behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS .C deroff is not a complete .C nroff interpreter; thus it can be confused by subtle constructs. Most such errors result in too much rather than too little output. .PP The .C -ml option does not handle nested lists correctly. .SH AUTHOR .C deroff was developed by the University of California, Berkeley. .SH SEE ALSO neqn(1), nroff(1), tbl(1). .\" .\" index@\f4deroff\f1 \- remove nroff, tbl, and neqn constructs@@@\f3deroff(1)\f1 .\" index@\f1constructs, nroff/troff, tbl, and neqn, remove@@@\f3deroff(1)\f1 .\" index@\f1neqn, tbl, and nroff/troff constructs, remove@@@\f3deroff(1)\f1 .\" index@\f1nroff/troff, tbl, and neqn constructs, remove@@@\f3deroff(1)\f1 .\" index@\f1troff/nroff, tbl, and neqn constructs, remove@@@\f3deroff(1)\f1 .\" index@\f1remove nroff/troff, tbl, and neqn constructs@@@\f3deroff(1)\f1 .\" index@\f1file: remove nroff/troff, tbl, and neqn constructs from@@@\f3deroff(1)\f1 .\" index@\f1strip nroff/troff, tbl, and neqn constructs from a file@@@\f3deroff(1)\f1 .\" index@\f1tbl, nroff/troff, and neqn constructs, remove@@@\f3deroff(1)\f1 .\" .\" toc@\f3deroff(1)\f1:\0\0\f4deroff\f1@@@remove nroff, tbl, and neqn constructs .\" .\" $Header: diff.1,v 76.2 95/08/23 17:52:58 ssa Exp $ .TA d .TH diff 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME diff \- differential file and directory comparator .SH SYNOPSIS .C diff .RC [ -C .IR n\| ] .RC [ -S .IR name\| ] .RC [ -lrs ] .RC [ -bcefhintw ] .I dir1 dir2 .br .C diff .RC [ -C .IR n\| ] .RC [ -S .IR name\| ] .RC [ -bcefhintw ] .I file1 file2 .br .C diff .RC [ -D .IR string\| ] .RC [ -biw ] .I file1 file2 .SH DESCRIPTION .SS Comparing Directories If both arguments are directories, .C diff sorts the contents of the directories by name, then runs the regular file .C diff algorithm (described below) on text files that have the same name in each directory but are different. Binary files that differ, common subdirectories, and files that appear in only one directory are listed. When comparing directories, the following options are recognized: .RS .TP 12 .C -l Long output format; each text file .C diff is piped through .C pr to paginate it (see .IR pr (1)). Other differences are remembered and summarized after all text file differences are reported. .TP .C -r Applies .C diff recursively to common subdirectories encountered. .TP .C -s .C diff reports files that are identical but otherwise not mentioned. .TP .CI -S \0name Starts a directory .C diff in the middle of the sorted directory, beginning with file .IR name . .SS Comparing Files When run on regular files, and when comparing text files that differ during directory comparison, .C diff tells what lines must be changed in the files to bring them into agreement. .C diff usually finds a smallest sufficient set of file differences. However, it can be misled by lines containing very few characters or by other situations. If neither .I file1 nor .I file2 is a directory, either can be specified as .CR - , in which case the standard input is used. If .I file1 is a directory, a file in that directory whose filename is the same as the filename of .I file2 is used (and vice versa). .PP There are several options for output format. The default output format contains lines resembling the following: .IP .I n1 .C a .IC n3 , n4 .br .IC n1 , n2 .C d .I n3 .br .IC n1 , n2 .C c .IC n3 , n4 .PP These lines resemble .C ed commands to convert .I file1 into .IR file2 . The numbers after the letters pertain to .IR file2 . In fact, by exchanging .C a for .C d and reading backwards one may ascertain equally how to convert .I file2 into .IR file1 . As in .CR ed , identical pairs where .IR n1 \|=\| n2 or .IR n3 \|=\| n4 are abbreviated as a single number. .PP Following each of these lines come all the lines that are affected in the first file flagged by .CR < , then all the lines that are affected in the second file flagged by .CR > . .PP Except for .CR -b , .CR -w , .CR -i , or .C -t which can be given with any of the others, the following options are mutually exclusive: .RS .TP 9 .C -e Produce a script of .CR a , .CR c , and .C d commands for the .C ed editor suitable for recreating .I file2 from .IR file1 . Extra commands are added to the output when comparing directories with .CR -e , so that the result is a shell script for converting text files common to the two directories from their state in .I dir1 to their state in .I dir2 (see .IR sh-bourne (1) .TP .C -f Produce a script similar to that of the .C -e option that is not useful with .C ed but is more readable by humans. .TP .C -n Produce a script similar to that of .CR -e , but in the opposite order, and with a count of changed lines on each insert or delete command. This is the form used by .C rcsdiff (see .IR rcsdiff (1)). .TP .C -c Produce a difference list with 3 lines of context. .C -c modifies the output format slightly: the output begins with identification of the files involved, followed by their creation dates, then each change separated by a line containing about twelve asterisks .RC ( \|*\| )s. Lines removed from .I file1 are marked with .CR - , and lines added to .I file2 are marked .CR + . Lines that change from one file to the other are marked in both files with with .CR ! . Changes that lie within 3 lines of each other in the file are grouped together on output. .TP .CI -C \0n Output format similar to .C -c but with .I n lines of context. .TP 9 .C -h Do a fast, half-hearted job. This option works only when changed stretches are short and well separated, but can be used on files of unlimited length. .TP .CI -D \0string Create a merged version of .I file1 and .I file2 on the standard output, with C preprocessor controls included so that a compilation of the result without defining .I string is equivalent to compiling .IR file1 , while compiling the result with .I string defined is equivalent to compiling .IR file2 . .TP .C -b Ignore trailing blanks (spaces and tabs) and treat other strings of blanks as equal. .TP .C -w Ignore all whitespace (blanks and tabs). For example, .C "if ( a == b )" and .C if(a==b) are treated as equal. .TP .C -i Ignores uppercase/lowercase differences. Thus .C A is treated the same as .CR a . .TP .C -t Expand tabs in output lines. Normal or .C -c output adds one or more characters to the front of each line. Resulting misalignment of indentation in the original source lines can make the output listing difficult to interpret. This option preserves original source file indentation. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not set or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .PP .C LC_CTYPE determines the space characters for the .C diff command, and the interpretation of text within file as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If any internationalization variable contains an invalid setting, .C diff and .C diffh behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported with the exception that .C diff and .C diffh do not recognize multi-byte alternative space characters. .SH RETURN VALUE Upon completion, .C diff returns with one of the following exit values: .RS .TP 8 .B \00 No differences were found. .TP .B \01 Differences were found. .TP .B >1 An error occurred. .RE .SH EXAMPLES The following command creates a script file .CR script : .IP .C "diff -e x1 x2 >script" .PP .C "w" is added to the end of the script in order to save the file: .IP .C "echo w >> script" .PP The script file can then be used to create the file .C x2 from the file .C x1 using the editor .C ed in the following manner: .IP .C "ed x1 < script" .PP The following command produces the difference output with 2 lines of context information before and after the line that was different: .IP .C "diff -C2 x1 x2" .PP The following command ignores all blanks and tabs and ignores uppercase-lowercase differences. .IP .C "diff -wi x1 x2" .SH WARNINGS Editing scripts produced by the .C -e or .C -f option are naive about creating lines consisting of a single dot .RC ( . ). .PP When comparing directories with the .CR -b , .CR -w , or .C -i options specified, .C diff first compares the files in the same manner as .CR cmp , then runs the .C diff algorithm if they are not equal. This may cause a small amount of spurious output if the files are identical except for insignificant blank strings or uppercase/lowercase differences. .PP The default algorithm requires memory allocation of roughly six times the size of the file. If sufficient memory is not available for handling large files, the .C -h option or .C bdiff can be used (see .IR bdiff (1)). .PP When run on directories with the .C -r option, .C diff recursively descends sub-trees. When comparing deep multi-level directories, more memory may be required than is currently available on the system. The amount of memory required depends on the depth of recursion and the size of the files. .SH AUTHOR .C diff was developed by AT&T, the University of California, Berkeley, and HP. .SH FILES .TP 30 .C /usr/lbin/diffh used by .C -h option .PD .SH SEE ALSO bdiff(1), cmp(1), comm(1), diff3(1), diffmk(1), dircmp(1), ed(1), more(1), nroff(1), rcsdiff(1), sccsdiff(1), sdiff(1), terminfo(4). .SH STANDARDS CONFORMANCE .CR diff ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4diff\f1, \f4diffh\f1 \- differential file comparator@@@\f3diff(1)\f1 .\" index@\f1differential file comparator@@@\f3diff(1)\f1 .\" index@\f1files: differential file comparator@@@\f3diff(1)\f1 .\" index@\f1files: find differences between two files@@@\f3diff(1)\f1 .\" index@\f1find differences between two files@@@\f3diff(1)\f1 .\" index@\f1differences between two files@@@\f3diff(1)\f1 .\" index@\f1compare two files and find differences@@@\f3diff(1)\f1 .\" .\" toc@\f3diff(1)\f1:\0\0\f4diff\f1, \f4diffh\f1@@@differential file comparator .\" toc@\f4diffh\f1: differential file comparator@@@see \f3diff(1)\f1 .\" .\" $Header: diff3.1,v 72.4 93/11/11 18:05:30 ssa Exp $ .TA d .TH diff3 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME diff3 \- 3-way differential file comparison .SH SYNOPSIS .C diff3 .RC [ -ex3 ] .I file1 file2 file3 .SH DESCRIPTION .C diff3 compares three versions of a file, and prints disagreeing ranges of text flagged with these codes: .RS .TP 10 .C ==== all three files differ .PD 0 .TP .C ====1 .I file1 is different .TP .C ====2 .I file2 is different .TP .C ====3 .I file3 is different .RE .PD .PP The type of change required to convert a given range of a given file to some other is indicated in one of these ways: .RS .TP 15 .IC f : n1 a Text is to be appended after line number .I n1 in file .IR f , where .I f = .CR 1 , .CR 2 , or .CR 3 . .TP .IC f : n1 , n2 c Text is to be changed in the range line .I n1 through line .IR n2 . If .I n1 = .IR n2 , the range can be abbreviated to .IR n1 . .RE .PP The original contents of the range follows immediately after a .C c indication. When the contents of two files are identical, the contents of the lower-numbered file is suppressed. .PP Under the .C -e option, .C diff3 produces a script for the .C ed editor that can be used to incorporate into .I file1 all changes between .I file2 and .I file3 (see .IR ed (1)); i.e., the changes that normally would be flagged .C ==== and .CR ====3 . Option .C -x .RC ( -3 ) produces a script to incorporate only changes flagged .C ==== .RC ( ====3 ). The following command applies the resulting script to .IR file1 . .IP .C "(cat script; echo '1,$p') | ed - file1" .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH FILES .C /var/tmp/d3* .br .C /usr/lbin/diff3prog .SH SEE ALSO diff(1). .SH WARNINGS Text lines that consist of a single .C . defeat .CR -e . .br Files longer than 64K bytes do not work. .\" .\" index@\f4diff3\f1 \- three-way differential file comparison@@@\f3diff3(1)\f1 .\" index@three-way differential file comparison@@@\f3diff3(1)\f1 .\" index@files: three-way differential file comparator@@@\f3diff3(1)\f1 .\" index@files: find differences among three files@@@\f3diff3(1)\f1 .\" index@find differences among three files@@@\f3diff3(1)\f1 .\" index@differences among three files@@@\f3diff3(1)\f1 .\" index@compare three files and find differences@@@\f3diff3(1)\f1 .\" .\" toc@\f3diff3(1)\f1:\0\0\f4diff3\f1@@@3-way differential file comparison .\" .\" fileset_database@diff3.1 USER-CMDS-MAN .\" $Header: diffmk.1,v 76.1 95/07/10 16:57:08 ssa Exp $ .TA d .TH diffmk 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME diffmk \- mark changes between two different versions of a file .SH SYNOPSIS .CR diffmk .I prevfile currfile markfile .SH DESCRIPTION .CR diffmk compares the previous version of a file with the current version and creates a file that includes .CR nroff / troff ``change mark'' commands. .I prevfile is the name of the previous version of the file and .I currfile is the name of the current version of the file. .CR diffmk generates .I markfile which contains all the lines of the .I currfile plus inserted formatter ``change mark'' .RC ( .mc ) requests. When .I markfile is formatted, changed or inserted text is shown by a .CR | character at the right margin of each line. The position of deleted text is shown by a single .CR * . .PP If the characters .CR | and .CR * are inappropriate, a copy of .CR diffmk can be edited to change them because .CR diffmk is a shell script. .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES A typical command line for comparing two versions of an .CR nroff / troff file and generating a file with the changes marked is: .IP .C "diffmk prevfile currfile markfile; nroff markfile | pr" .PP .CR diffmk can also be used to produce listings of C (or other) programs with changes marked. A typical command line for such use is: .IP .C "diffmk prevfile.c currfile.c markfile.c; nroff macs markfile.c | pr" .PP where the file .CR macs contains: .nf .IP .C .pl 1 .C .ll 77 .C .nf .C .eo .fi .PP The .CR .ll request can specify a different line length, depending on the nature of the program being printed. The .CR .eo request is probably needed only for C programs. .SH WARNINGS Aesthetic considerations may dictate manual adjustment of some output. .PP .CR diffmk does not differentiate between changes in text and changes in formatter request coding. Thus, file differences involving only formatting changes (such as replacing .CR .sp with .CR ".sp 2" in a text source file) with no change in actual text can produce change marks. .PP Although unlikely, certain combinations of formatting requests can cause change marks to either disappear or to mark too much. Manual intervention may be required because the subtleties of various formatting macro packages and preprocessors is beyond the scope of .CR diffmk . .CR tbl cannot tolerate .CR .mc commands in its input (see .IR tbl (1)), so any .CR .mc request that would appear inside a .CR .TS range is silently deleted. The script can be changed if this action is inappropriate, or .CR diffmk can be run on two files that have both been run through the .CR tbl preprocessor before any comparisons are made. .PP .CR diffmk uses .CR diff , and thus has the same limitations on file size and performance that .CR diff may impose (see .IR diff (1)). In particular the performance is nonlinear with the size of the file, and very large files (well over 1000 lines) may take extremely long to process. Breaking the file into smaller pieces may be advisable. .PP .CR diffmk also uses the .IR ed (1) editor. If the file is too large for .CR ed , .CR ed error messages may be embedded in the file. Again, breaking the file into smaller pieces may be advisable. .SH SEE ALSO diff(1), nroff(1). .\" .\" index@\f4diffmk\f1 \- mark differences between files@@@\f3diffmk(1)\f1 .\" index@\f1mark differences between two files@@@\f3diffmk(1)\f1 .\" index@\f1differences between two files, mark@@@\f3diffmk(1)\f1 .\" index@\f1compare two files and mark differences@@@\f3diffmk(1)\f1 .\" index@\f1files: compare two files and mark differences@@@\f3diffmk(1)\f1 .\" .\" toc@\f3diffmk(1)\f1:\0\0\f4diffmk\f1@@@mark differences between files .\" .\" $Header: dircmp.1,v 76.1 95/07/10 16:57:46 ssa Exp $ .TA d .TH dircmp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dircmp \- directory comparison .SH SYNOPSIS .C dircmp .RC [ -d ] .RC [ -s ] .RC [ -w\c .IR n\| ] .I dir1 dir2 .SH DESCRIPTION .C dircmp examines .I dir1 and .I dir2 and generates various tabulated information about the contents of the directories. Sorted listings of files that are unique to each directory are generated for all the options. If no option is entered, a sorted list is output indicating whether the filenames common to both directories have the same contents. .RS .TP 8 .C -d Compare the contents of files with the same name in both directories and output a list telling what must be changed in the two files to bring them into agreement. The list format is described in .IR diff (1). .TP .C -s Suppress messages about identical files. .TP .CI -w n Change the width of the output line to .I n characters. The default width is 72. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .SM LC_COLLATE determines the order in which the output is sorted. .PP If .C LC_COLLATE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default. If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C dircmp behaves as if all internationalization variables are set to ``C'' (see .IR environ (5)). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES Compare the two directories .C slate and .C sleet and produce a list of changes that would make the directories identical: .IP .C dircmp -d slate sleet .SH SEE ALSO cmp(1), diff(1). .SH STANDARDS CONFORMANCE .CR dircmp ": SVID2, SVID3, XPG2, XPG3" .\" .\" toc@\f3dircmp(1)\f1:\0\0\f4dircmp\f1@@@directory comparison .\" .\" index@\f4dircmp\f1 \- directory comparison@@@\f3dircmp(1)\f1 .\" index@\f1compare contents of two directories@@@\f3dircmp(1)\f1 .\" index@\f1contents of two directories, compare@@@\f3dircmp(1)\f1 .\" index@\f1directory: compare contents of two directories@@@\f3dircmp(1)\f1 .\" .\" $Header: basename.1,v 76.1 95/08/01 16:01:13 ssa Exp $ .TA b .TH basename 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME basename, dirname \- extract portions of path names .SH SYNOPSIS .C basename .I string .RI [ \|suffix\| ] .br .C dirname .RI [ \|string\| ] .SH DESCRIPTION .C basename deletes any prefix ending in .C / and the .I suffix (if present in .IR string ) from .IR string , and prints the result on the standard output. If .I string consists entirely of slash characters, .I string is set to a single slash character. If there are any trailing slash characters in .IR string , they are removed. If the suffix operand is present but not identical to the characters remaining in .IR string , but it is identical to a suffix of the characters remaining in .IR string , the suffix is removed from .IR string . .C basename is normally used inside command substitution marks .RC ( \|\` ... \`\| ) within shell procedures. .PP .C dirname delivers all but the last level of the path name in .IR string . If .I string does not contain a directory component, .C dirname returns .CR . , indicating the current working directory. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of string and, in the case of basename, suffix as single and/or multi-byte characters. .PP If .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C basename and .C dirname behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following shell script, invoked with the argument .CR /usr/src/cmd/cat.c , compiles the named file and moves the output to a file named .C cat in the current directory: .IP .C cc $1 .br .C "mv a.out `basename $1 .c`" .PP The following example sets the shell variable .C NAME to .CR /usr/src/cmd : .IP .C "NAME=\`dirname /usr/src/cmd/cat.c\`" .SH RETURNS .C basename and .C dirname return one of the following values: .RS .TP 8 .B 0 Successful completion. .TP .B 1 Incorrect number of command-line arguments. .SH SEE ALSO expr(1), sh(1). .SH STANDARDS CONFORMANCE .CR basename ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR dirname ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4basename\f1, \f4dirname\f1 \- extract portions of path names@@@\f3basename(1)\f1 .\" index@\f4dirname\f1, \f4basename\f1 \- extract portions of path names@@@\f3basename(1)\f1 .\" index@extract portions of path names@@@\f3basename(1)\f1 .\" index@portions of path names, extract@@@\f3basename(1)\f1 .\" index@path names, extract portions of@@@\f3basename(1)\f1 .\" index names: extract portions of path names \f3basename(1)\f1 .\" .\" toc@\f3basename(1)\f1:\0\0\f4basename\f1, \f4dirname\f1@@@extract portions of path names .\" toc@\f4dirname\f1: extract portions of path names@@@see \f3basename(1)\f1 .\" .\" links@basename.1 dirname.1 .\" .\" fileset_database@basename.1 USER-CMDS-MAN .\" $Header: enable.1,v 72.4 94/10/13 13:42:59 ssa Exp $ .TA e .TH enable 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME enable, disable \- enable/disable LP printers .SH SYNOPSIS .CR enable .I printers .PP .CR disable .RC [ \-c ] .RC [ \-r\c .RI [ reason ]\|] .I printers .SH DESCRIPTION The .CR enable command activates the named .IR printers , enabling them to print requests taken by .CR lp . Use .CR lpstat to find the status of printers (see .IR lp (1) and .IR lpstat (1)). .PP .CR disable deactivates the named .IR printers , disabling them from printing requests taken by .CR lp . By default, any requests that are currently printing on the designated printers are reprinted in their entirety either on the same printer or on another member of the same class. Use .CR lpstat to find the status of printers. .SS Options .CR disable recognizes the following options: .RS .TP 15 .CR \-c Cancel any requests that are currently printing on any of the designated printers. .TP .CR \-r [\f2reason\f1] Associate a .I reason with the deactivation of the printers. This reason applies to all printers mentioned up to the next .CR \-r option. If the .CR \-r option is not present or the .CR \-r option is given without a reason, a default .I reason is used. .I reason is reported by .CR lpstat . The maximum length of the .I reason message is 80 bytes. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to .CR C (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to .CR C (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH EXAMPLES Enable printer .CR snowwhite to accept requests: .IP .C "enable snowwhite" .PP Deactivate printer .CR snowwhite and cancel any logged jobs: .IP .C "disable \-c snowwhite" .SH WARNINGS If the restrict cancel feature (selected by the .CR "lpadmin \-orc" option \(em see .IR lpadmin (1M)) is enabled, .CR disable ignores the .CR \-c option. .PP .CR enable and .CR disable perform their operation on the local system only. .SH FILES .nf .CR /etc/lp/* .CR /usr/lib/lp/* .CR /var/adm/lp/* .CR /var/spool/lp/* .fi .SH SEE ALSO lp(1), lpstat(1), accept(1M), lpadmin(1M), lpsched(1M), rcancel(1M), rlp(1M), rlpdaemon(1M), rlpstat(1M). .\" .\" toc@\f3enable(1)\f1:\0\0\f4enable\f1, \f4disable\f1@@@enable/disable LP printers .\" toc@\f4disable\f1:\0\0disable LP printers@@@see \f3enable(1)\f1 .\" .\" index@\f4enable\f1 \- enable LP printers@@@\f3enable(1)\f1 .\" index@\f4disable\f1 \- disable LP printers@@@\f3enable(1)\f1 .\" index@\f1LP printers, enable/disable@@@\f3enable(1)\f1 .\" index@\f1printers, LP, enable/disable@@@\f3enable(1)\f1 .\" .\" links@enable.1 disable.1 .\" $Header: lpfilter.1,v 72.4 94/07/05 17:17:26 ssa Exp $ .TA l .TH lpfilter 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lpfilter, divpage, fontdl, lprpp, plotdvr, printstat, reverse \- filters invoked by lp interface scripts .SH SYNOPSIS .C /usr/lbin/divpage .RC [ -p \(or .CR -l ] .RC [ -h \(or .CR -q ] .RC [ -n\c .IR FontID\| ] .I filename .PP .C /usr/lbin/fontdl .RC [ -n\c .IR FontID\| ] .RC [ -l ] .RC [ -p ] .I filename .PP .C /usr/lbin/lprpp .RC [ -i ] .RC [ -o ] .RC [ -e ] .RC [ -l\c .IR nn\| ] .RC [ -n ] .RC [ -p ] .PP .C /usr/lbin/plotdvr .CI -l \|request_id .CI -u \|username .RC [ -e ] .RC [ -f ] .RC [ -i ] .I filename .PP .C /usr/sbin/printstat .CI -l \|request_id .CI -u \|username .I filename .PP .C /usr/sbin/reverse .RC [ -l .IR page_length\| ] .SS Remarks The structure of these filters is currently under review. They may become obsolete or be restructured in a future release. .SH DESCRIPTION Various filters are used by the .C lp subsystem to obtain specialized behavior for specific types of devices or data. This entry describes currently supported filters. .PP A number of these filters use a specified .I username and .I filename to determine the location of the user who originated the print message. .PP The .I filename is used to determine the .I hostname of the system where the request originated, and must have the form .RI [ dirname ]\c .CI /d?A \|nnnhostname or .RI [ dirname ]\c .CI /dA \|nnnnhostname\f1, where .I dirname is not a path name, but only the name of the basename's parent directory. .I filename meets this requirement when it is set to .C $6 in the interface script for the printer. .SS divpage Provides capabilities for printing multiple pages per sheet and selection of built-in fonts. .PP .C Options: .RS .TP 15 .C -p Set mode to portrait (default). .TP .C -l Set mode to landscape. .TP .C -h Print half pages (default). .TP .C -q Print quarter pages. .TP .CI -n \|FontID Use font number .IR FontID . Default is 0. Causes the string .CI \s-2\uE\dC\s0( \|Font\s-1ID\s0 X to be sent to the printer. .RE .SS fontdl .I fontdl downloads the font contained in .I filename to a printer connected to standard output. .PP .C Options: .RS .TP 15 .CI -n \|FontID Specifies the ID number by which the font will be referenced. Default is 0. .TP .C -l Specify landscape mode. Default is portrait. .TP .C -p Specifies proportional spacing. Default is fixed. .RE .SS lprpp This is a filter that converts backspace overstrike to line overprint with horizontal print positioning to enhance bold print. This functionality is required on printers such as the LaserJet, which cannot produce bold print by overstriking. .PP .C Options: .RS .TP 15 .C -i Converts to _ to italicize ANYCHAR. Also properly italicizes overstruck (bold) characters. Does .I not work correctly for "hashed-overstrike" such as: .br \0 .br \0\0\0\0\0\0_ .TP .C -o Prints only the odd numbered pages. Used with .C -e for double-sided printing. .TP .C -e Print only the even numbered pages. Used with .C -o for double sided printing. .TP .CI -l \|nn Specifies the page length, in lines. Default is 60 unless .I -n or .I -p is selected, in which case it is 66. .TP .C -n Specifies nroff mode for printing output of the .I nroff command. Prints 66 lines per page with the first line appearing on logical line 4 of the printer. .TP .C -p Specifies pr mode for printing output from the .I pr command. Prints 66 lines per page with the first line appearing on logical line 3 of the printer. .SS plotdvr HP-GL plotter filter. This filter scans the data for "PG" commands (paper feed). When this data is encountered, the filter strips it from the data stream and informs the requesting user of the need to change paper in the plotter. .PP Options: .RS .TP 15 .CI -l \|request_id Specifies the printer request ID and is used in various messages regarding the plot request. .TP .CI -u \|username The requesting user's login name, used to communicate with the user regarding the request. .TP .C -e Specifies the use of escape sequences, rather than HP-GL commands, to determine plotter status. .TP .C -f Plot without stopping for paper changes. The "PG" commands are not stripped from the data stream and the user is not notified of them. This option is used on plotters capable of automatic page feed. .TP .C -i Prevents initialization of the plotter. .RE .SS printstat Interrogates an RS232 printer as to its status, and does not return until the printer is ready. If the printer is .IR off-line , .IR "out of paper" , or .IR disconnected , the submitter of the print request is notified of this condition periodically until it is corrected. When the printer is ready to print, the command exits. .PP Standard input and standard output must both be connected to the serial printer device. .PP This program uses the .I send-status command .C \s-2\uE\dC\s0?\s-2\uD\d1\s0? to determine status. Not all serial printers respond to this command. Only the following configurations support this command: .RS .PP .TS box; cB | cB l | l. Printer Comments _ LaserJet Not supported LaserJetII Supported LaserJetIID Requires \s-1HP\|26013A\s0 module LaserJetIIP Not supported LaserJetIII Requires \s-1HP\|26013A\s0 module LaserJet2000 Not supported .TE .RE .PP .C Options: .RS .TP 15 .CI -l \|request-id Print request ID used in various communications with the user. .TP .CI -u \|username The requesting user's login name, used to communicate with the user regarding the request. .RE .SS reverse Prints the data appearing on the standard input in reverse page order to the standard output. This command can handle up to 2000 pages. .PP .C Options: .RS .TP 15 .CI -l \|page_length Specifies the page length, in lines. Default is 66. .RE .SH DIAGNOSTICS Error and diagnostic messages appear on the printed output, on the user's terminal, or are mailed to the user, depending on circumstances. .SH WARNINGS There is little consistency in the interface to these filters. .SH SEE ALSO lp(1), lpadmin(1). .PP .IR "HP-UX System Administration Manual" . .\" .\" index@\f4lpfilter\f1 \- filters invoked by lp interface scripts@@@\f3lpfilter(1)\f1 .\" index@\f4divpage\f1 \- divide pages for two-sided printing@@@\f3lpfilter(1)\f1 .\" index@\f4fontdl\f1 \- download fonts to printer@@@\f3lpfilter(1)\f1 .\" index@\f4hp2686a\f1 \- laserjet filter@@@\f3lpfilter(1)\f1 .\" index@\f4hp2934a\f1 \- character printer filter@@@\f3lpfilter(1)\f1 .\" index@\f4lprpp\f1 \- laserjet filter@@@\f3lpfilter(1)\f1 .\" index@\f4plotdvr\f1 \- plotter driver for lp@@@\f3lpfilter(1)\f1 .\" index@\f4printstat\f1 \- check status of serial printer@@@\f3lpfilter(1)\f1 .\" index@\f4reverse\f1 \- reverse printer pages for collating@@@\f3lpfilter(1)\f1 .\" .\" toc@\f3lpfilter(1)\f1:\0\0\f4lpfilter\f1@@@filters used by the lp interface scripts .\" .\" links@lpfilter.1 divpage.1 .\" links@lpfilter.1 fontdl.1 .\" links@lpfilter.1 lprpp.1 .\" links@lpfilter.1 plotdvr.1 .\" links@lpfilter.1 printstat.1 .\" links@lpfilter.1 reverse.1 .\" $Header: dmpxlt.1,v 72.2 94/09/20 15:42:51 ssa Exp $ .TA d .TH dmpxlt 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dmpxlt \- dump iconv translation tables to a readable format .SH SYNOPSIS .CR /usr/bin/dmpxlt .RC [ -f .IR output_filename "] [" input_filename ] .SH DESCRIPTION .C dmpxlt dumps the compiled version of the .C iconv codeset conversion tables into an ASCII-readable format that can be modified and used as input to .IR genxlt (1) to regenerate the table for .IR iconv (1) . .SS Options .C dmpxlt recognizes the following options: .RS .TP 22 .CI -f " output_filename" If this option is not selected, the data will be sent to standard output. .RE .PP .C dmpxlt will create an output file in the prescribed format, giving the filecode mapping between the two code sets, which can be edited and reused by .IR genxlt (1) to create new tables for .IR iconv (1) . The entries are in hexadecimal. .PP .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C dmpxlt will behave as if all internationalization variables are set to "C". See .IR environ (5). .PP .C LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .PP .C LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .C NLSPATH determines the location of message catalogues for the processing of .C LC_MESSAGES. .SS International Code Set Support Single and multi-byte character code sets are supported. .SH RETURN VALUE The following are exit values: .RS 3 .TP 8 .B \00 Successful completion. .PD 0 .TP .B >0 Error condition occurred. .RE .PD .SH EXAMPLES This example creates the source file .I genxlt_input from the table .CR roma8=iso81 : .IP .C "dmpxlt -f genxlt_input /usr/lib/nls/iconv/tables/roma8=iso81" .PP .SH FILES .TP 30 /usr/lib/nls/iconv/tables All tables must be installed in this directory. .SH SEE ALSO iconv(1), genxlt(1), iconv(3C), environ(5) lang(5). .\" toc@\f3dmpxlt(1)\f1: \0\0\f4dmpxlt\f1@@@ dump iconv translation tables to a readable format .\" index@\f4dmpxlt\f1 \- dump iconv translation tables to a readable format@@@\f3dmpxlt(1)\f1 .\" index@\f1 dump iconv translation tables to a readable format@@@\f3dmpxlt(1)\f1 .\" index@\f1 iconv translation tables to a readable format, dump@@@\f3dmpxlt(1)\f1 .\" index@\f1 translation tables to a readable format, dump iconv@@@\f3dmpxlt(1)\f1 .\" index@\f1 readable format, dump iconv translation tables to @@@\f3dmpxlt(1)\f1 .\" index@\f1 ASCII format, dump iconv translation tables to @@@\f3dmpxlt(1)\f1 .\" $Header: domainname.1,v 72.5 94/07/28 13:20:34 ssa Exp $ .TA d .TH domainname 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME domainname \- set or display name of Network Information Service domain .SH SYNOPSIS .C domainname .RI [ \|name_of_domain\| ] .SH DESCRIPTION Network Information Service (NIS) uses domain names to refer collectively to a group of hosts. Without an argument, .I domainname displays the name of the NIS domain. Only superuser can set the domain name by providing .IR name_of_domain . The domain name is usually set in the configuration file .CR /etc/rc.config.d/namesvrs, by setting the .CR NIS_DOMAIN variable. .SH DEPENDENCIES NIS servers use the NIS domain name as the name of a subdirectory of .CR /var/yp . Since the NIS domain name can be as long as 64 characters, .I name_of_domain may exceed the maximum file name length allowed on a given file system. If that length is exceeded, the subdirectory name becomes a truncated version of the NIS domain name. .PP The first 14 characters of all NIS domains on the network must be unique: truncated names should be checked to verify that they meet this requirement. .SH AUTHOR .C domainname was developed by Sun Microsystems, Inc. .SH SEE ALSO ypinit(1M), getdomainname(2), setdomainname(2). .\" .\" index@\f4domainname\f1 \- set or display NIS domain name@@@\f3domainname(1)\f1 .\" index@\f1set Network Information Service domain name@@@\f3domainname(1)\f1 .\" index@\f1display Network Information Service domain name@@@\f3domainname(1)\f1 .\" index@\f1Network Information Service domain name, set or display@@@\f3domainname(1)\f1 .\" index@\f1NIS domain name, set or display@@@\f3domainname(1)\f1 .\" index@\f1domain name, set or display Network Information Service@@@\f3domainname(1)\f1 .\" index@\f1name, set or display Network Information Service domain@@@\f3domainname(1)\f1 .\" .\" toc@\f3domainname(1)\f1:\0\0\f4domainname\f1@@@set or display NIS domain name .\" $Header: dos2ux.1,v 72.3 93/01/14 11:32:29 ssa Exp $ .TA d .TH dos2ux 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dos2ux, ux2dos \- convert \s-1ASCII\s+1 file format .SH SYNOPSIS .C dos2ux .I file ... .br .C ux2dos .I file ... .SH DESCRIPTION .C dos2ux and .C ux2dos read each specified .I file in sequence and write it to standard output, converting to .SM HP-UX format or to .SM DOS format, respectively. Each .I file can be either .SM DOS format or .SM HP-UX format for either command. .PP A .SM DOS file name is recognized by the presence of an embedded colon .RC ( : ) delimiter; see .IR dosif (4) for .SM DOS file naming conventions. .PP If no input file is given or if the argument .C - is encountered, .C dos2ux and .C ux2dos read from standard input. Standard input can be combined with other files. .SH EXAMPLES Print file .C myfile on the display: .IP .C "dos2ux myfile" .PP Convert .C file1 and .C file2 to .SM DOS format then concatenate them together, placing them in .CR file3 . .IP .C "ux2dos file1 file2 > file3" .SH RETURN VALUE .C dos2ux and .C ux2dos return .C 0 if successful or .C 2 if the command failed. The only possible failure is the inability to open a specified file, in which case the commands print a warning. .SH WARNINGS Command formats resembling: .IP .C "dos2ux file1 file2 > file1" .PP overwrite the data in .C file1 before the concatenation begins, causing a loss of the contents of .CR file1 . Therefore, be careful when using shell special characters. .SH SEE ALSO doschmod(1), doscp(1), dosdf(1), dosls(1), dosmkdir(1), dosrm(1), dosif(4). .\" .\" index@\f4dos2ux\f1, \f4ux2dos\f1 \- convert \s-1ASCII\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@\f4ux2dos\f1, \f4dos2ux\f1 \- convert \s-1ASCII\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@convert \s-1DOS\s+1 file to \s-1HP-UX ASCII\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@convert \s-1HP-UX ASCII\s+1 file to \s-1DOS\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@files: convert \s-1DOS\s+1 file to \s-1HP-UX ASCII\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@files: convert \s-1HP-UX ASCII\s+1 file to \s-1DOS\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@format: convert \s-1DOS\s+1 file to \s-1HP-UX ASCII\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@format: convert \s-1HP-UX ASCII\s+1 file to \s-1DOS\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@\s-1DOS\s+1 files: convert \s-1HP-UX ASCII\s+1 file to \s-1DOS\s+1 format@@@\f3dos2ux(1)\f1 .\" index@\s-1DOS\s+1 files: convert \s-1DOS\s+1 file to \s-1HP-UX ASCII\s+1 format@@@\f3dos2ux(1)\f1 .\" .\" toc@\f3dos2ux(1)\f1:\0\0\f4dos2ux\f1, \f4ux2dos\f1@@@convert \s-1ASCII\s+1 file format .\" toc@\f4ux2dos\f1: convert \s-1ASCII\s+1 file format@@@see \f3dos2ux(1)\f1 .\" .\" links@dos2ux.1 ux2dos.1 .\" .\" fileset_database@dos2ux.1 USER-CMDS-MAN .\" $Header: doschmod.1,v 72.4 94/09/20 15:43:53 ssa Exp $ .TA d .TH doschmod 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME doschmod \- change attributes of a \s-1DOS\s+1 file .SH SYNOPSIS .C doschmod .RC [ -u ] .I mode .IC device :\| file\0\f1... .SH DESCRIPTION .C doschmod is the .SM DOS counterpart of .C chmod (see .IR chmod (1)). .SS Options .C doschmod recognizes one option: .RS .TP 7 .C -u Disable argument case conversion. In the absence of this option, all .SM DOS file names are converted to uppercase. .RE .PP A .SM DOS file name is recognized by the presence of an embedded colon .RC ( : ) delimiter; see .IR dosif (4) for .SM DOS file naming conventions. .PP Metacharacters .CR * , .CR ? , and .CR [ \0...\0 ] can be used when specifying .SM DOS file names. These must be quoted when specifying a .SM DOS file name, because file name expansion must be performed by the .SM DOS utilities, not by the shell. DOS utilities expand file names as described in .IR regexp (5) under .I PATTERN MATCHING .IR NOTATION . .PP The attributes of each named file are changed according to .IR mode , which is an octal number in the range 000 to 0377. .IR mode is constructed from the logical .SM OR of the following modes: .RS .TP 10 200 Reserved. Do not use. .PD 0 .TP 100 Reserved. Do not use. .TP 040 Archive. Set whenever the file has been written to and closed. .TP 020 Directory. Do not modify. .TP 010 Volume Label. Do not modify. .TP 004 System file. Marks files that are part of the .SM DOS operating system. .TP 002 Hidden file. Marks files that do not appear in a .SM DOS directory listing using the .SM DOS .SM DIR command. .TP 001 Read-Only file. Marks files as read-only. .RE .PD .SH WARNINGS Specifying inappropriate .I mode values can make files and/or directories inaccessible, and in certain cases can damage the file system. To prevent such problems, do not change the mode of directories and volume labels. .PP Normal users should have no need to use .I mode bits other than 001, 002, and 040. .SH EXAMPLES Mark file .C /dev/rfd9122:memo.txt as a hidden file: .IP .C "doschmod 002 /dev/rfd9122:memo.txt" .PP Mark file .C driveC:autoexec.bat read-only: .IP .C "doschmod 001 driveC:autoexec.bat" .SH SEE ALSO chmod(1), dos2ux(1), doscp(1), dosdf(1), dosls(1), dosmkdir(1), dosrm(1), chmod(2), dosif(4). .\" .\" index@\f4doschmod\f1 \- change attributes of a \s-1DOS\s+1 file@@@\f3doschmod(1)\f1 .\" index@attributes of a \s-1DOS\s+1 file, change@@@\f3doschmod(1)\f1 .\" index@change attributes of a \s-1DOS\s+1 file@@@\f3doschmod(1)\f1 .\" index@\s-1DOS\s+1 files: change attributes of a \s-1DOS\s+1 file@@@\f3doschmod(1)\f1 .\" .\" toc@\f3doschmod(1)\f1:\0\0\f4doschmod\f1@@@change attributes of a \s-1DOS\s+1 file .\" $Header: doscp.1,v 72.4 94/09/20 15:44:13 ssa Exp $ .TA d .TH doscp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME doscp \- copy to or from \s-1DOS\s+1 files .SH SYNOPSIS .C doscp .RC [ -fvu ] .I "file1 file2" .br .C doscp .RC [ -fvu ] .I file1 .RI [ \|file2 \0...\|] .I directory .SH DESCRIPTION .C doscp is the .SM DOS counterpart of .C cp (see .IR cp (1)). .C doscp copies a .SM DOS file to a .SM DOS or .SM HP-UX file, an .SM HP-UX file to an .SM HP-UX or .SM DOS file, or .SM HP-UX or .SM DOS files to an .SM HP-UX or .SM DOS directory. The last name in the argument list is the destination file or directory. .PP A .SM DOS file name is recognized by the presence of an embedded colon .RC ( : ) delimiter; see .IR dosif (4) for .SM DOS file naming conventions. .PP Metacharacters .CR * , .CR ? , and .CR [ \0...\0 ] can be used when specifying both .SM HP-UX and .SM DOS file names. These must be quoted when specifying a .SM DOS file name, because file name expansion must be performed by the .SM DOS utilities, not by the shell. DOS utilities expand file names as described in .IR regexp (5) under .I PATTERN MATCHING .IR NOTATION . .PP The file name .C - (dash) is interpreted to mean standard input or standard output depending upon its position in the argument list. .SS Options .C doscp recognizes the following options: .RS .TP 7 .C -f Unconditionally write over an existing file. In the absence of this option, .C doscp asks permission to overwrite an existing .SM HP-UX file. .TP .C -v Verbose mode. .C doscp prints the source name. .TP .C -u Disable argument case conversion. In the absence of this option, all .SM DOS file names are converted to upper case. .RE .SH RETURN VALUE .C doscp returns 0 if all files are copied successfully. Otherwise, it prints a message to standard error and returns with a non-zero value. .SH EXAMPLES Copy the files in the .SM HP-UX directory .C abc to the .SM DOS volume stored as .SM HP-UX file .CR hard_disk : .IP .C "doscp abc/* hard_disk:" .PP Copy .SM DOS file .C /backup/log through the .SM HP-UX special file .C /dev/rfd9127 to .SM HP-UX file .C logcopy located in the current directory: .IP .C "doscp /dev/rfd9127:/backup/log \0logcopy" .PP Copy .SM DOS file .C zulu on the volume stored as .SM HP-UX file .C bb to standard output: .IP .C "doscp bb:zulu -" .PP Copy all files in directory .C /dameron with extension .C txt in the .SM DOS volume .C /dev/rdsk/c1t2d0 to the .SM HP-UX directory .C abacus located in the current directory: .IP .C "doscp '/dev/rdsk/c1t2d0:/dameron/*.txt' abacus" .SH WARNINGS .PP .CR doscp works more reliably if you use a raw device special file .RC ( /dev/rdsk/ ) than a block device special file. .PP To use SCSI floppy disk devices, the .CR sflop device driver must be configured into the kernel. (You can use the .CR ioscan command to verify the configuration.) .SH SEE ALSO cp(1), dos2ux(1), doschmod(1), dosdf(1), dosls(1), dosmkdir(1), dosrm(1), ioscan(1M) dosif(4). .\" .\" index@\f4doscp\f1 \- copy to or from \s-1DOS\s+1 files@@@\f3doscp(1)\f1 .\" index@copy to or from \s-1DOS\s+1 files@@@\f3doscp(1)\f1 .\" index@\s-1DOS\s+1 files: copy to or from@@@\f3doscp(1)\f1 .\" index@files: copy to or from \s-1DOS\s+1 files@@@\f3doscp(1)\f1 .\" .\" toc@\f3doscp(1)\f1:\0\0\f4doscp\f1@@@copy to or from \s-1DOS\s+1 files .\" $Header: dosdf.1,v 72.3 93/01/14 11:33:00 ssa Exp $ .TA d .TH dosdf 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dosdf \- report number of free disk clusters .SH SYNOPSIS .C dosdf .I device\c .RC [ : ] .SH DESCRIPTION .C dosdf is the .SM DOS counterpart of the .C df command (see .IR df (1)). It prints the cluster size in bytes and the number of free clusters on the specified .SM DOS volume. .SH SEE ALSO df(1), dos2ux(1), doschmod(1), doscp(1), dosls(1), dosmkdir(1), dosrm(1), dosif(4). .\" .\" toc@\f3dosdf(1)\f1:\0\0\f4dosdf\f1@@@report number of free disk clusters .\" .\" index@\f4dosdf\f1 \- report number of free \s-1DOS\s+1 disk clusters@@@\f3dosdf(1)\f1 .\" index@available \s-1DOS\s+1 disk clusters, report number of@@@\f3dosdf(1)\f1 .\" index@clusters, \s-1DOS\s+1 disk, report number of free@@@\f3dosdf(1)\f1 .\" index@disk clusters, \s-1DOS\s+1, report number of free@@@\f3dosdf(1)\f1 .\" index@disk space, \s-1DOS\s+1, report amount of available@@@\f3dosdf(1)\f1 .\" index@\s-1DOS\s+1 files: report number of free \s-1DOS\s+1 disk clusters@@@\f3dosdf(1)\f1 .\" index@free \s-1DOS\s+1 disk clusters, report number of@@@\f3dosdf(1)\f1 .\" index@number of free \s-1DOS\s+1 disk clusters, report@@@\f3dosdf(1)\f1 .\" index@report number of free \s-1DOS\s+1 disk clusters@@@\f3dosdf(1)\f1 .\" index@unused \s-1DOS\s+1 disk clusters, report number of@@@\f3dosdf(1)\f1 .\" .\" fileset_database@dosdf.1 USER-CMDS-MAN .\" $Header: dosls.1,v 72.4 94/09/20 15:53:32 ssa Exp $ .TA d .TH dosls 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dosls, dosll \- list contents of \s-1DOS\s+1 directories .SH SYNOPSIS .C dosls .RC [ -aAudl ] .IC device :\c .RI [ \|file\| ] \&... .br .C dosll .RC [ -aAudl ] .IC device :\c .RI [ \|file\| ] \&... .SH DESCRIPTION .C dosls is the .SM DOS counterpart of .C ls (see .IR ls (1)). .PP For each directory named, .C dosls lists the contents of that directory. For each file named, .C dosls repeats its name and any other information requested. If invoked by the name .CR dosll , the .C -l (ell) option is implied. .SS Options .C dosls and .C dosll recognizes the following options: .RS .TP 7 .C -a List all directory entries. In the absence of this option, hidden files, system files, and files whose names begin with a dot .RC ( . ) are not listed. .TP .C -A Same as .CR -a , except the current directory and the parent directory are not listed. For the superuser, this option defaults to being set, and is disabled by .CR -A . .TP .C -u Disable argument case conversion. In the absence of this option, all .SM DOS file names are converted to uppercase. .TP .C -d If an argument is a directory, list only its name. Often used with .C -l to get the status of a directory. .TP .C -l List in long format, giving file attribute, size in bytes, and the date and time of last modification for each file, as well as listing the .SM DOS volume label. Long listing is disabled if this option is used with the .C dosll command. .RE .PP A .SM DOS file name is recognized by the presence of an embedded colon .RC ( : ) delimiter; see .IR dosif (4) for .SM DOS file naming conventions. .PP Metacharacters .CR * , .CR ? , and .CR [ \0...\0 ] can be used when specifying .SM DOS file names. These must be quoted when specifying a .SM DOS file name, because file name expansion must be performed by the .SM DOS utilities, not by the shell. DOS utilities expand file names as described in .IR regexp (5) under .I PATTERN MATCHING .IR NOTATION . .SH EXAMPLES These examples assume that a .SM DOS directory structure exists on the device accessed through .SM HP-UX special file .CR /dev/rdsk/c2t1d0 . .PP The following example lists all of the files in the root directory of the .SM DOS directory structure: .IP .C "dosls -a /dev/rdsk/c2t1d0:" .PP The following example lists all of the files with extension .C bat in the root directory of the .SM DOS directory structure: .IP .C "dosls -a '/dev/rdsk/c2t1d0:*.bat'" .PP The following example produces a long-format listing of all the information about the .SM DOS directory .CR /dos/math , but does not list the files in the directory: .IP .C "dosls -ld /dev/rdsk/c2t1d0:/dos/math" .SH SEE ALSO dos2ux(1), doschmod(1), doscp(1), dosdf(1), dosmkdir(1), dosrm(1), ls(1), dosif(4). .\" .\" index@\f4dosls\f1, \f4dosll\f1 \- list contents of \s-1DOS\s+1 directories@@@\f3dosls(1)\f1 .\" index@\f4dosll\f1, \f4dosls\f1 \- list contents of \s-1DOS\s+1 directories@@@\f3dosls(1)\f1 .\" index@contents of \s-1DOS\s+1 directories, list@@@\f3dosls(1)\f1 .\" index@directory: list contents of \s-1DOS\s+1 directories@@@\f3dosls(1)\f1 .\" index@list contents of \s-1DOS\s+1 directories@@@\f3dosls(1)\f1 .\" index@\s-1DOS\s+1 files: list contents of \s-1DOS\s+1 directories@@@\f3dosls(1)\f1 .\" .\" toc@\f3dosls(1)\f1:\0\0\f4dosls\f1, \f4dosll\f1@@@list contents of \s-1DOS\s+1 directories .\" toc@\f4dosll\f1: list contents of \s-1DOS\s+1 directories@@@see \f3dosls(1)\f1 .\" .\" links@dosls.1 dosll.1 .\" $Header: dosls.1,v 72.4 94/09/20 15:53:32 ssa Exp $ .TA d .TH dosls 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dosls, dosll \- list contents of \s-1DOS\s+1 directories .SH SYNOPSIS .C dosls .RC [ -aAudl ] .IC device :\c .RI [ \|file\| ] \&... .br .C dosll .RC [ -aAudl ] .IC device :\c .RI [ \|file\| ] \&... .SH DESCRIPTION .C dosls is the .SM DOS counterpart of .C ls (see .IR ls (1)). .PP For each directory named, .C dosls lists the contents of that directory. For each file named, .C dosls repeats its name and any other information requested. If invoked by the name .CR dosll , the .C -l (ell) option is implied. .SS Options .C dosls and .C dosll recognizes the following options: .RS .TP 7 .C -a List all directory entries. In the absence of this option, hidden files, system files, and files whose names begin with a dot .RC ( . ) are not listed. .TP .C -A Same as .CR -a , except the current directory and the parent directory are not listed. For the superuser, this option defaults to being set, and is disabled by .CR -A . .TP .C -u Disable argument case conversion. In the absence of this option, all .SM DOS file names are converted to uppercase. .TP .C -d If an argument is a directory, list only its name. Often used with .C -l to get the status of a directory. .TP .C -l List in long format, giving file attribute, size in bytes, and the date and time of last modification for each file, as well as listing the .SM DOS volume label. Long listing is disabled if this option is used with the .C dosll command. .RE .PP A .SM DOS file name is recognized by the presence of an embedded colon .RC ( : ) delimiter; see .IR dosif (4) for .SM DOS file naming conventions. .PP Metacharacters .CR * , .CR ? , and .CR [ \0...\0 ] can be used when specifying .SM DOS file names. These must be quoted when specifying a .SM DOS file name, because file name expansion must be performed by the .SM DOS utilities, not by the shell. DOS utilities expand file names as described in .IR regexp (5) under .I PATTERN MATCHING .IR NOTATION . .SH EXAMPLES These examples assume that a .SM DOS directory structure exists on the device accessed through .SM HP-UX special file .CR /dev/rdsk/c2t1d0 . .PP The following example lists all of the files in the root directory of the .SM DOS directory structure: .IP .C "dosls -a /dev/rdsk/c2t1d0:" .PP The following example lists all of the files with extension .C bat in the root directory of the .SM DOS directory structure: .IP .C "dosls -a '/dev/rdsk/c2t1d0:*.bat'" .PP The following example produces a long-format listing of all the information about the .SM DOS directory .CR /dos/math , but does not list the files in the directory: .IP .C "dosls -ld /dev/rdsk/c2t1d0:/dos/math" .SH SEE ALSO dos2ux(1), doschmod(1), doscp(1), dosdf(1), dosmkdir(1), dosrm(1), ls(1), dosif(4). .\" .\" index@\f4dosls\f1, \f4dosll\f1 \- list contents of \s-1DOS\s+1 directories@@@\f3dosls(1)\f1 .\" index@\f4dosll\f1, \f4dosls\f1 \- list contents of \s-1DOS\s+1 directories@@@\f3dosls(1)\f1 .\" index@contents of \s-1DOS\s+1 directories, list@@@\f3dosls(1)\f1 .\" index@directory: list contents of \s-1DOS\s+1 directories@@@\f3dosls(1)\f1 .\" index@list contents of \s-1DOS\s+1 directories@@@\f3dosls(1)\f1 .\" index@\s-1DOS\s+1 files: list contents of \s-1DOS\s+1 directories@@@\f3dosls(1)\f1 .\" .\" toc@\f3dosls(1)\f1:\0\0\f4dosls\f1, \f4dosll\f1@@@list contents of \s-1DOS\s+1 directories .\" toc@\f4dosll\f1: list contents of \s-1DOS\s+1 directories@@@see \f3dosls(1)\f1 .\" .\" links@dosls.1 dosll.1 .\" $Header: dosmkdir.1,v 72.3 93/01/14 11:33:11 ssa Exp $ .TA d .TH dosmkdir 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dosmkdir \- make a \s-1DOS\s+1 directory .SH SYNOPSIS .C dosmkdir .RC [ -u ] .IC device : directory \&... .SH DESCRIPTION .C dosmkdir is the .SM DOS counterpart of the .C mkdir command (see .IR mkdir (1)). It creates specified directories. The standard entries, .C . for the directory itself and .CR .. for its parent, are made automatically. .TP There is one option: .RS .TP 7 .C -u Disable argument case conversion. In the absence of this option, all .SM DOS file names are converted to uppercase. .RE .PP A .SM DOS file name is recognized by the presence of an embedded colon .RC ( : ) delimiter; see .IR dosif (4) for .SM DOS file naming conventions. .SH DIAGNOSTICS .C dosmkdir returns 0 if all directories were successfully created. Otherwise, it prints a message to standard error and returns non-zero. .SH EXAMPLES Create an empty subdirectory named .C numbers under the directory .C /math/lib on the device accessed through .SM HP-UX special file .CR /dev/rfd9122 : .IP .C "dosmkdir /dev/rfd9122:/math/lib/numbers" .SH SEE ALSO dos2ux(1), doschmod(1), doscp(1), dosdf(1), dosls(1), dosrm(1), mkdir(1), dosif(4). .\" .\" toc@\f3dosmkdir(1)\f1:\0\0\f4dosmkdir\f1@@@make a \s-1DOS\s+1 directory .\" .\" index@\f4dosmkdir\f1 \- make a \s-1DOS\s+1 directory@@@\f3dosmkdir(1)\f1 .\" index@make a \s-1DOS\s+1 directory@@@\f3dosmkdir(1)\f1 .\" index@create a \s-1DOS\s+1 directory@@@\f3dosmkdir(1)\f1 .\" index@directory: create a \s-1DOS\s+1 directory@@@\f3dosmkdir(1)\f1 .\" index@\s-1DOS\s+1 files: create a \s-1DOS\s+1 directory@@@\f3dosmkdir(1)\f1 .\" .\" fileset_database@dosmkdir.1 USER-CMDS-MAN .\" $Header: dosrm.1,v 72.4 94/09/20 15:53:52 ssa Exp $ .TA d .TH dosrm 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dosrm, dosrmdir \- remove \s-1DOS\s+1 files or directories .SH SYNOPSIS .C dosrm .RC [ -friu ] .IC device : file \&... .br .C dosrmdir .RC [ -u ] .IC device : file \&... .SH DESCRIPTION .C dosrm and .C dosrmdir are .SM DOS counterparts of .C rm and .C rmdir (see .IR rm (1) and .IR rmdir (1), respectively). .PP .C dosrm removes the entries for one or more files from a directory. If a specified file is a directory, an error message is printed unless the optional argument .C -r is specified (see below). .PP .C dosrmdir removes entries for the named directories, provided they are empty. .SS Options .C dosrm and .C dosrmdir recognize the following options: .RS .TP 7 .C -f (force) Unconditionally remove the specified file, even if the file is marked read-only. .TP .C -r Cause .C dosrm to recursively delete the entire contents of a directory, followed by the directory itself. .C dosrm can recursively delete up to 17 levels of directories. .TP .C -i (interactive) Cause .C dosrm to ask whether or not to delete each file. If .C -r is also specified, .C dosrm asks whether to examine each directory encountered. .TP .C -u Disable argument case conversion. In the absence of this option, all .SM DOS file names are converted to uppercase. .RE .PP A .SM DOS file name is recognized by the presence of an embedded colon .RC ( : ) delimiter; see .IR dosif (4) for .SM DOS file naming conventions. .PP Metacharacters .CR * , .CR ? , and .CR [ \0...\0 ] can be used when specifying .SM DOS file names. These must be quoted when specifying a .SM DOS file name, because file name expansion must be performed by the .SM DOS utilities, not by the shell. DOS utilities expand file names as described in .IR regexp (5) under .I PATTERN MATCHING .IR NOTATION . .SH EXAMPLES These examples assume that a .SM DOS directory structure exists on the device accessed through the .SM HP-UX special file .CR /dev/rfd9122 . .PP Recursively comb through the .SM DOS directory .C /tmp and ask if each .SM DOS file should be removed forcibly (that is, with no file mode checks): .IP .C "dosrm -irf /dev/rfd9122:/tmp" .PP Remove the .SM DOS directory .C doug from the .SM DOS volume stored as .SM HP-UX file .CR hard_disk : .IP .C "dosrmdir hard_disk:doug" .SH SEE ALSO dos2ux(1), doschmod(1), doscp(1), dosdf(1), dosls(1), dosmkdir(1), rm(1), rmdir(1), dosif(4). .\" .\" index@\f4dosrm\f1, \f4dosrmdir\f1 \- remove \s-1DOS\s+1 files or directories@@@\f3dosrm(1)\f1 .\" index@\f4dosrmdir\f1, \f4dosrm\f1 \- remove \s-1DOS\s+1 files or directories@@@\f3dosrm(1)\f1 .\" index@directory: remove \s-1DOS\s+1 files or directories@@@\f3dosrm(1)\f1 .\" index@files: remove \s-1DOS\s+1 files or directories@@@\f3dosrm(1)\f1 .\" index@\s-1DOS\s+1 files: remove \s-1DOS\s+1 files or directories@@@\f3dosrm(1)\f1 .\" index@delete \s-1DOS\s+1 files or directories@@@\f3dosrm(1)\f1 .\" index@remove \s-1DOS\s+1 files or directories@@@\f3dosrm(1)\f1 .\" .\" toc@\f3dosrm(1)\f1:\0\0\f4dosrm\f1, \f4dosrmdir\f1@@@remove \s-1DOS\s+1 files or directories .\" toc@\f4dosrmdir\f1: remove \s-1DOS\s+1 directories@@@see \f3dosrm(1)\f1 .\" .\" links@dosrm.1 dosrmdir.1 .\" $Header: dosrm.1,v 72.4 94/09/20 15:53:52 ssa Exp $ .TA d .TH dosrm 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dosrm, dosrmdir \- remove \s-1DOS\s+1 files or directories .SH SYNOPSIS .C dosrm .RC [ -friu ] .IC device : file \&... .br .C dosrmdir .RC [ -u ] .IC device : file \&... .SH DESCRIPTION .C dosrm and .C dosrmdir are .SM DOS counterparts of .C rm and .C rmdir (see .IR rm (1) and .IR rmdir (1), respectively). .PP .C dosrm removes the entries for one or more files from a directory. If a specified file is a directory, an error message is printed unless the optional argument .C -r is specified (see below). .PP .C dosrmdir removes entries for the named directories, provided they are empty. .SS Options .C dosrm and .C dosrmdir recognize the following options: .RS .TP 7 .C -f (force) Unconditionally remove the specified file, even if the file is marked read-only. .TP .C -r Cause .C dosrm to recursively delete the entire contents of a directory, followed by the directory itself. .C dosrm can recursively delete up to 17 levels of directories. .TP .C -i (interactive) Cause .C dosrm to ask whether or not to delete each file. If .C -r is also specified, .C dosrm asks whether to examine each directory encountered. .TP .C -u Disable argument case conversion. In the absence of this option, all .SM DOS file names are converted to uppercase. .RE .PP A .SM DOS file name is recognized by the presence of an embedded colon .RC ( : ) delimiter; see .IR dosif (4) for .SM DOS file naming conventions. .PP Metacharacters .CR * , .CR ? , and .CR [ \0...\0 ] can be used when specifying .SM DOS file names. These must be quoted when specifying a .SM DOS file name, because file name expansion must be performed by the .SM DOS utilities, not by the shell. DOS utilities expand file names as described in .IR regexp (5) under .I PATTERN MATCHING .IR NOTATION . .SH EXAMPLES These examples assume that a .SM DOS directory structure exists on the device accessed through the .SM HP-UX special file .CR /dev/rfd9122 . .PP Recursively comb through the .SM DOS directory .C /tmp and ask if each .SM DOS file should be removed forcibly (that is, with no file mode checks): .IP .C "dosrm -irf /dev/rfd9122:/tmp" .PP Remove the .SM DOS directory .C doug from the .SM DOS volume stored as .SM HP-UX file .CR hard_disk : .IP .C "dosrmdir hard_disk:doug" .SH SEE ALSO dos2ux(1), doschmod(1), doscp(1), dosdf(1), dosls(1), dosmkdir(1), rm(1), rmdir(1), dosif(4). .\" .\" index@\f4dosrm\f1, \f4dosrmdir\f1 \- remove \s-1DOS\s+1 files or directories@@@\f3dosrm(1)\f1 .\" index@\f4dosrmdir\f1, \f4dosrm\f1 \- remove \s-1DOS\s+1 files or directories@@@\f3dosrm(1)\f1 .\" index@directory: remove \s-1DOS\s+1 files or directories@@@\f3dosrm(1)\f1 .\" index@files: remove \s-1DOS\s+1 files or directories@@@\f3dosrm(1)\f1 .\" index@\s-1DOS\s+1 files: remove \s-1DOS\s+1 files or directories@@@\f3dosrm(1)\f1 .\" index@delete \s-1DOS\s+1 files or directories@@@\f3dosrm(1)\f1 .\" index@remove \s-1DOS\s+1 files or directories@@@\f3dosrm(1)\f1 .\" .\" toc@\f3dosrm(1)\f1:\0\0\f4dosrm\f1, \f4dosrmdir\f1@@@remove \s-1DOS\s+1 files or directories .\" toc@\f4dosrmdir\f1: remove \s-1DOS\s+1 directories@@@see \f3dosrm(1)\f1 .\" .\" links@dosrm.1 dosrmdir.1 .\" $Header: du.1,v 76.1 95/08/03 17:17:43 ssa Exp $ .TA d .TH du 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME du \- summarize disk usage .SH SYNOPSIS .C du .RC [ -a \(or -s ] .RC [ -brx ] .RC [ -t .IR type\| ] .RI [ \|name \0...\|] .SH DESCRIPTION The .CR du command gives the number of 512-byte blocks allocated for all files and (recursively) directories within each directory and file specified by the .I name operands. The block count includes the indirect blocks of the file. A file with two or more links is counted only once. If .I name is missing, the current working directory is used. .PP By default, .CR du generates an entry only for the .I name operands and each directory contained within those hierarchies. .SS Options The .CR du command recognizes the following options: .RS .TP 15 .C -a Print entries for each file encountered in the directory hierarchies in addition to the normal output. .TP .C -b For each .I name operand that is a directory for which file system swap has been enabled, print the number of blocks the swap system is currently using. .TP .C -r Print messages about directories that cannot be read, files that cannot be accessed, etc. .CR du is normally silent about such conditions. .TP .C -s Print only the grand total of disk usage for each of the specified .I name operands. .TP .C -x Restrict reporting to only those files that have the same device as the file specified by the .I name operand. Disk usage is normally reported for the entire directory hierarchy below each of the given .I name operands. .TP .CI -t \0type Restrict reporting to file systems of the specified .IR type . (Example values for .IR type are .CR hfs , .CR cdfs , .C nfs, etc.) Multiple .CI -t \0type options can be specified. Disk usage is normally reported for the entire directory hierarchy below each of the given .I name operands. .RE .SH EXAMPLES Display disk usage for the current working directory and all directories below it, generating error messages for unreadable directories: .IP .C du -r .PP Display disk usage for the entire file system except for any .C cdfs or .C nfs mounted file systems: .IP .C du -t hfs / .PP Display disk usage for files on the root volume .RC ( / ) only. No usage statistics are collected for any other mounted file systems: .IP .C du -x / .SH WARNINGS Block counts are incorrect for files that contain holes. .SH SEE ALSO df(1M), bdf(1M), quot(1M). .SH STANDARDS CONFORMANCE .CR du ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4du\f1 \- summarize disk usage@@@\f3du(1)\f1 .\" index@report disk usage@@@\f3du(1)\f1 .\" index@show disk usage@@@\f3du(1)\f1 .\" index@summarize disk usage@@@\f3du(1)\f1 .\" index@disk usage, summarize@@@\f3du(1)\f1 .\" index@usage, summarize disk@@@\f3du(1)\f1 .\" .\" toc@\f3du(1)\f1:\0\0\f4du\f1@@@summarize disk usage .\" .\" fileset_database@du.1 USER-CMDS-MAN .\" $Header: findmsg.1,v 78.1 96/02/12 13:46:32 ssa Exp $ .TA f .TH findmsg 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME findmsg, dumpmsg \- create message catalog file for modification .SH SYNOPSIS .C findmsg .RC [ -aiv ] .RC [\|[ -D .IR sym\| ] .RC [ -U .IR sym\| ]] .IR file \0... .PP .C dumpmsg .IR file \0... .SH DESCRIPTION The .CR findmsg command extracts messages from a C program source .I file and writes them to the standard output in a format suitable for input to .CR gencat (see .IR gencat (1)). The input file will be preprocessed using .CR cpp (see .IR cpp (1)) in order to select print specifiers and handle .CR ifdef , .CR ifndef ... conditional .CR cpp primitives. If multiple input files are specified and the .CR -a option is not used, the files are processed sequentially such that message catalog comment lines identifying the input .I file are written before the output for each input .IR file . .PP The .CR findmsg command scans the source files for uncommented lines with one of the following three formats embedded within it: .IP .CI catgets( any_var ,NL_SETN, n ,\c .ifn \f3<\f2message\f3>)\f1 .ift \f4<\f2message\f4>)\f1 .RS .TP 25 .ifn \f3<\f2message\f3>\f1 .ift \f4<\f2message\f4>\f1 .CI "/* catgets " n " */ .TP .CI "/* catgets " n " */" .ifn \f3<\f2message\f3>\f1 .ift \f4<\f2message\f4>\f1 .RE .PP or any combination of these formats wholly contained on a single physical line. .ifn \f3<\f2message\f3>\f1 .ift \f4<\f2message\f4>\f1 could be a string constant or a combination of string constants and print specifiers (PRI*). Any number of spaces or tabs can separate the .CR catgets comment from the .IR message . The digit .IR n , which can be any valid message number (see .IR gencat (1)), is combined with the .I message string to produce a message catalog source line. The message source line is assigned to the set whose number is the current value of .CR NL_SETN as set by the last .CR #define directive encountered. If .CR NL_SETN has not yet been defined when a message line is found, the message is output without a set number specification. If more than one message is found belonging to the same set and message number, the last message found is output; any others are silently discarded. Conditional compilation and .CR #include instructions in the C source files are ignored. .SS Options .CR findmsg recognizes the following command-line options: .RS .TP 12 .C -a Merge identically numbered sets from multiple input files so that .CR gencat can process the .CR findmsg output. .TP .CI -D sym Define symbol .IR sym . .TP .CI -U sym Cause symbol .I sym to be undefined. .TP .C -i Consider all #ifdefs to extract messages from the input file. Options .C -D and .C -U will be used to select print specifiers if this option is not used. .TP .C -v Outputs all error messages issued by .CR cpp . By default, .CR findmsg does not display the error messages issued by .CR cpp . .RE .PP The .CR dumpmsg command extracts messages from a message catalog .I file created by .CR gencat . Messages are written to standard output in a format suitable for editing and re-input to .CR gencat . .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_CTYPE determines the interpretation of messages as single-byte and/or multi-byte characters. .PP .CR LC_MESSAGES determines the language in which messages are displayed. .PP If .CR LC_CTYPE or .CR LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of .CR C (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR findmsg and .CR dumpmsg behave as if all internationalization variables are set to .CR C . See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH WARNINGS The .CR findmsg command is HP proprietary, not portable to other vendors' systems, and will not be provided in future HP-UX releases. .SH AUTHOR .CR findmsg and .CR dumpmsg were developed by HP. .SH SEE ALSO findstr(1), gencat(1), insertmsg(1), catgets(3C). .\" .\" index@\f4findmsg\f1 \- create message catalog file for modification@@@\f3findmsg(1)\f1 .\" index@\f4dumpmsg\f1 \- create message catalog file for modification@@@\f3findmsg(1)\f1 .\" index@\f1catalog file, message, create for modification@@@\f3findmsg(1)\f1 .\" index@\f1create message catalog file for modification@@@\f3findmsg(1)\f1 .\" index@\f1file, create message catalog file for modification@@@\f3findmsg(1)\f1 .\" index@\f1message catalog file, create for modification@@@\f3findmsg(1)\f1 .\" index@\f1message catalog file, extract messages from @@@\f3findmsg(1)\f1 .\" index@\f1modification, create message catalog file for@@@\f3findmsg(1)\f1 .\" .\" toc@\f3findmsg(1)\f1:\0\0\f4findmsg\f1, \f4dumpmsg\f1@@@create message catalog file for modification\f1 .\" toc@\f4dumpmsg\f1:\0\0extract messages from message catalog file@@@\f1see \f3findmsg(1)\f1 .\" .\" links@findmsg.1 dumpmsg.1 .\" $Header: echo.1,v 76.1 95/08/03 17:19:15 ssa Exp $ .TA e .TH echo 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME echo \- echo (print) arguments .SH SYNOPSIS .C echo .RI [ \|arg\| ]\0... .SH DESCRIPTION .C echo writes its arguments separated by blanks and terminated by a new-line on the standard output. It also understands C-like escape conventions; beware of conflicts with the shell's use of .CR \e : .PP .RS .PD 0 .TP 10 .C \ea write an alert character .TP .C \eb backspace .TP .C \ec print line without appending a new-line .TP .C \ef form-feed .TP .C \en new-line .TP .C \er carriage return .TP .C \et tab .TP .C \ev vertical tab .TP .C \e\e backslash .TP .CI \e n the 8-bit character whose .SM ASCII code is the 1-, 2-, 3- or 4-digit octal number .IR n , whose first character must be a zero. .TP .CI \e0 num write an 8-bit value that is the zero-, one-, two- or three-digit octal number .I num .RE .PD .PP .C echo is useful for producing diagnostics in command files and for sending known data into a pipe. .SS Notes Berkeley .C echo differs from this implementation. The former does not implement the backslash escapes. However, the semantics of the .C \ec escape can be obtained by using the .C -n option. The echo command implemented as a built-in function of .C csh follows the Berkeley semantics (see .IR csh (1)). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of .I arg as single and/or multi-byte characters. .PP If .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C echo behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH AUTHOR .CR echo was developed by OSF and HP. .SH SEE ALSO sh(1). .SH BUGS No characters are printed after the first .CR \ec . This is not normally a problem. .SH STANDARDS CONFORMANCE .CR echo ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" toc@\f3echo(1)\f1:\0\0\f4echo\f1@@@echo (print) arguments .\" .\" index@\f4echo\f1 \- echo (print) arguments@@@\f3echo(1)\f1 .\" index@print (echo) arguments@@@\f3echo(1)\f1 .\" index@display (print) arguments@@@\f3echo(1)\f1 .\" index@arguments, echo (print)@@@\f3echo(1)\f1 .\" $Header: ed.1,v 76.1 95/08/07 11:29:45 ssa Exp $ .TA e .TH ed 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ed, red \- line-oriented text editor .SH SYNOPSIS .CR ed .RC [ -p .IR string ] .RC [ -s \(or - ] .RC [ -x ] .RI [ file ] .PP .CR red .RC [ -p .IR string ] .RC [ -s \(or - ] .RC [ -x ] .RI [ file ] .SH DESCRIPTION The .CR ed command executes a line-oriented text editor. It is most commonly used in scripts and noninteractive editing applications because, even though it can be used interactively, other editors such as .CR vi and .CR ex are typically easier to use in an interactive environment. .PP If .I file is specified, .CR ed performs an .CR e command (see below) on the named file; that is to say, the file is read into .CR ed 's buffer so that it can be edited. .SS Options The following options are recognized: .RS .TP 12 .CI -p \ string Use .I string as the prompt string when in command mode. By default, there is no prompt string. .TP .CR -s \(or - Suppress printing of byte counts by .CR e , .CR E , .CR r , and .CR w commands, and suppress the .CR !\& prompt after a .CR !\& .IR command . The .CR - option is obsolescent and will be removed in a future release. .TP .CR -x Perform an .CR X command first to handle an encrypted file. .RE .SS File Handling .CR ed operates on a copy of the file it is editing; changes made to the copy have no effect on the original file until a .CR w (write) command is given. The copy of the text being edited resides in a temporary file called the .IR buffer . There is only one buffer. .PP .CR red is a restricted version of .CR ed that only allows editing of files in the current directory and prohibits executing shell commands via .CI ! shell-command\f1. Attempts to bypass these restrictions result in the error message .CR "restricted shell" . .PP Both .CR ed and .CR red support the .IR fspec (4) formatting capability. After including a format specification as the first line of .I file and invoking .CR ed with the controlling terminal in .CR "stty -tabs" or .CR "stty tab3" mode (see .IR stty (1)), the specified tab stops are automatically used when scanning .IR file . For example, if the first line of a file contained .IP .C "<:t5,10,15 s72:>" .PP the tab stops would be set at columns 5, 10, and 15, and a maximum line length of 72 would be imposed. .PP .B Note: When you input text, .CR ed expands tab characters as they are typed to every eighth column as a default. .SS Editor Commands Structure Commands to .CR ed have a simple and regular structure: zero, one, or two .I addresses followed by a single-character .IR command , possibly followed by parameters to that command. These addresses specify one or more lines in the buffer. Every command that requires addresses has default addresses, so that the addresses can very often be omitted. .PP In general, only one command is allowed on a line. Append, change, and insert commands accept text input which is then placed in the buffer as appropriate. While .CR ed is accepting text following an append, change, or insert command, it is said to be in .IR "input mode" . While in input mode, .I no editor commands are recognized; all input is merely collected. To terminate input mode, type a period .RC ( . ) alone at the beginning of a line. .SS Regular Expressions .CR ed supports the Basic Regular Expression (RE) syntax (see .IR regexp (5)), with the following additions: .RS .TP 3 \(bu The null RE (for example, .CR // ) is equivalent to the last RE encountered. .TP \(bu If the closing delimiter of an RE or of a replacement string (for example, .CR / ) would be the last character before a newline, that delimiter can be omitted, in which case the addressed line is printed. The following pairs of commands are equivalent: .RS 6 .PP .ifn\{ .nf s/s1/s2 g/s1 ?s1 s/s1/s2/p g/s1/p ?s1? .fi \} .ift \{\" .TS lf4p+1w(1.5i) lf4p+1w(1.5i) lf4p+1w(1.5i). s/s1/s2 g/s1 ?s1 s/s1/s2/p g/s1/p ?s1? .TE \} .RE .RE .SS Line Addresses To understand line addressing, remember that .CR ed maintains a pointer to the .IR "current line" . Generally speaking, the current line is the last line affected by a command. The exact effect of a given command on the current line is discussed under the description of each command. Addresses are interpreted according to the following rules: .RS .TP 4 1. The character .CR .\& refers to the current line. .TP 2. The character .CR $ refers to the last line of the buffer. .TP 3. A decimal number .I n refers to the .IR n th line of the buffer. .TP 4. A .CI ' x refers to the line marked with the mark name character .IR x , which must be a lower-case letter. Lines are marked with the .CR k command described below. .TP 5. An RE enclosed by slashes (\c .CI / RE /\c ) refers to the first line found by searching forward from the line following the current line toward the end of the buffer and stopping at the first line containing a string matching the RE. If necessary, the search wraps around to the beginning of the buffer and continues up to and including the current line, so that the entire buffer is searched. (Also see WARNINGS below.) .TP 6. An RE enclosed by question marks (\c .CI ? RE ?\c ) addresses the first line found by searching backward from the line preceding the current line toward the beginning of the buffer and stopping at the first line containing a string matching the RE. If necessary, the search wraps around to the end of the buffer and continues up to and including the current line. (Also see WARNINGS below.) .TP 7. An address followed by a plus .RC ( + ) or minus .RC ( - ) sign followed by a decimal number specifies that address plus or minus the indicated number of lines. The plus sign can be omitted. .TP 8. If an address begins with .CR + or .CR - , the addition or subtraction is calculated with respect to the current line. For example, .CR -5 is interpreted as .CR .-5 . .TP 9. If an address ends with .CR + or .CR - , 1 is added to or subtracted from the address, respectively. As a consequence of this and rule 8 above, the address .CR - refers to the line preceding the current line. (To maintain compatibility with earlier versions of the editor, the circumflex .RC ( ^ ) and .CR - characters are interpreted identically when encountered in addresses.) Moreover, multiple trailing .CR + and .CR - characters have a cumulative effect, so .CR -- refers to the second line preceding the current line. .TP 10. For convenience, a comma .RC ( , ) represents the address pair .CR 1,$ , while a semicolon .RC ( ; ) represents the pair .CR .,$ . .RE .PP Commands require zero, one, or two addresses. Commands that do not use addresses treat the presence of an address as an error. Commands that accept one or two addresses assume default addresses when the number of addresses specified is insufficient. If more addresses are specified than a given command requires, the last one or two are used as appropriate. .PP Addresses are usually separated from each other by a comma .RC ( , ). They can also be separated by a semicolon .RC ( ; ), in which case the current line .RC ( . ) is set to the first address, after which the second address is calculated. This feature can be used to determine the starting line for forward and backward searches (see rules 5 and 6 above). The second address of any two-address sequence must correspond to a line in the buffer that follows the line corresponding to the first address. .SS Editor Commands In the following list of .CR ed commands, the default addresses are shown in parentheses (parentheses are not part of the address and should not be placed in an actual command except for other purposes). .PP It is generally illegal for more than one command to appear on a line. However, any command (except .CR e , .CR f , .CR r , or .CR w ) can be suffixed by .CR l , .CR n , or .CR p in which case the current line is respectively either listed, numbered, or printed, as discussed below under the .CR l , .CR n , and .CR p commands. .br .ne 4 .TP 15 .PD 0 .RC ( . ) a .TP .IR text .TP .CR . .sp -3v The .CR a (append) command reads .IR text and appends it after the addressed line. Upon completion, the new current line is the last inserted line, or, if no text was added, at the addressed line. Address 0 is legal for this command, causing the appended .IR text to be placed at the beginning of the buffer. .PD .br .ne 5 .TP .PD 0 .RC ( .,. ) c .TP .IR text .TP .CR . .sp -3v The .CR c (change) command deletes the addressed lines then accepts input text to replace the deleted lines. Upon completion, the new current line is the last line in .I text or, if no text was provided, at the first line after the deleted line or lines. .PD .TP .RC ( .,. ) d The .CR d (delete) command deletes the addressed lines from the buffer. Upon completion, the new current line is the first line following the deleted text, or the last line in the file if the deleted line or lines were at the end of the buffer. .TP .CI e \0file The .CR e (edit) command deletes the entire contents of the buffer, then reads in the named .IR file . Upon completion, the new current line is the last line in the buffer. If no file name is given, the remembered file name, if any, is used (see the .CR f command). The number of characters read is displayed, and .I file is remembered for possible use as a default file name in subsequent .CR e , .CR r , or .CR w commands. .IP If the .I file name starts with .CR ! , the rest of the line is interpreted as a shell command whose standard output is to be read. Such a shell command is not remembered as the current file name. .IP Also see DIAGNOSTICS below. .TP .CI E \0file The .CR E (forced edit) command is identical to .CR e except that no check is made to ensure that the current buffer has not been altered since the last .CR w command. .TP .CI f \0file If .I file is specified, the .CR f (file name) command changes the remembered file name to .IR file . Otherwise, it prints the remembered file name. .TP .RC ( 1,$ ) g/ \s-1\f2RE\fP\s0 "/\s-1\f2command-list\fP\s0" The .CR g (global) command first marks every line that matches the given RE. Then, for every such line, the given .I "command-list" is executed with the current line initially set to that line. A single command or the first of a list of commands appears on the same line as the global command. All lines of a multiple-line list except the last line must end with a backslash .RC ( \e ). .CR a , .CR i , and .CR c commands and associated input are permitted. The .CR .\& that normally terminates input mode can be omitted if it would be the last line of the .IR "command-list" . An empty .I "command-list" is equivalent to the .CR p command. The .CR g , .CR G , .CR v , and .CR V commands are not permitted in the .IR "command-list" . (Also see WARNINGS below.) .TP .RC ( 1,$ ) G/ \s-1\f2RE\fP\s0 / The interactive .CR G (Global) command first marks every line that matches the given RE. Then, for every such line, the line is printed, then the current line is changed to that line and one command (other than .CR a , .CR c , .CR i , .CR g , .CR G , .CR v , or .CR V ) can be input and executed. After executing that command, the next marked line is printed, and so on. A newline character acts as a null command, and an .CR & causes the re-execution of the most recent command executed within the current invocation of .CR G . Note that the commands input as part of the execution of the .CR G command may address and affect .I any lines in the buffer. The .CR G command can be terminated by an interrupt signal (ASCII DEL or BREAK). .TP .CR h The .CR h (help) command gives a short error message explaining the reason for the most recent .CR ?\& diagnostic. .TP .CR H The .CR H (Help) command causes .CR ed to enter a mode in which error messages are printed for all subsequent .CR ?\& diagnostics. It also explains the previous .CR ?\& if there was one. The .CR H command alternately turns this mode on and off. Initially, it is off. .br .ne4 .TP .RC ( . ) i .PD 0 .TP .IR text .TP .CR .\& .sp -3v The .CR i (insert) command inserts the given .I text before the addressed line. Upon completion, the current line is the last inserted line, or, if there were none, the addressed line. This command differs from the .CR a command only in the placement of the input text. Address 0 is not legal for this command. .PD .TP .RC ( .,.+1 ) j The .CR j (join) command joins contiguous lines by removing the appropriate newline characters. If exactly one address is given, this command does nothing. .TP .RC ( . ) k \f2x\fP The .CR k (mark) command marks the addressed line with the name .IR x , which must be a lower-case letter. The address .CI ' x then addresses this line. Upon completion, the new current line remains unchanged from before. .TP .RC ( .,. ) l The .CR l (list) command writes the addressed lines to standard output in a visually unambiguous form. Characters listed in the following table are written as the corresponding escape sequence. Nonprintable characters not in the table are written as a three-digit octal number (with a preceding backslash character) for each byte in the character (most significant byte first). .IP Long lines are folded with the point of folding indicated by writing a backslash character followed by a newline. The end of each line is marked with a .CR $ . An .CR l (ell) command can be appended to any command other than .CR e , .CR E , .CR f , .CR q , .CR Q , .CR r , .CR w , or .CR ! . The current line number is set to the address of the last line written. .ifn .PP .ift .IP .TS center tab(;); cB cB cB | cB cB cB cB cB cB | cB cB cB cf4p+1 l c | cf4p+1 l c . Escape;;ASCII;Escape;;ASCII Sequence;Represents;Name;Sequence;Represents;Name \e\e;backslash;\e;\er;carriage return;CR \ea;alert;BEL;\et;horizontal tab;HT \eb;backspace;BS;\ev;vertical tab;VT \ef;formfeed;FF .TE .TP 15 .RC ( .,. ) m \f2a\fP The .CR m (move) command repositions the addressed lines after the line addressed by .IR a . Address 0 is legal for .IR a , causing the addressed lines to be moved to the beginning of the file. It is an error if address .I a falls within the range of moved lines; Upon completion, the new current line is the last line moved. .TP .RC ( .,. ) n The .CR n (number) command prints the addressed lines, preceding each line by its line number and a tab character. Upon completion, the new current line is the last line printed. The .CR n command can be appended to any command other than .CR e , .CR f , .CR r , or .CR w . .TP .RC ( .,. ) p The .CR p (print) command prints the addressed lines. Upon completion, the new current line is the last line printed. The .CR p command may be appended to any other command other than .CR e , .CR E , .CR f , .CR q , .CR Q , .CR r , .CR w , or .CR ! . For example, .CR dp deletes the current line and prints the new current line. .TP .CR P The .CR P (prompt) command causes .CR ed to prompt with an asterisk .RC ( * ) (or with .I string if the .CR -p option was specified in the command line) for all subsequent commands. The .CR P command alternately turns this mode on and off. It is initially on if the .CR -p option was specified; otherwise, off. The current line number is unchanged. .TP .CR q The .CR q (quit) command causes .CR ed to exit. No automatic write of a file is done (but see DIAGNOSTICS below). .TP .CR Q The editor exits unconditionally without checking for changes in the buffer since the last .CR w command. .TP .RC ( $ ) r \0\f2file\fP The .CR r (read) command reads the specified .I file into the buffer after the addressed line. If no file name is given, the remembered file name, if any, is used (see the .CR e and .CR f commands). The remembered file name is not changed unless .I file is the very first file name mentioned since .CR ed was invoked. Address 0 is legal for .CR r and places the contents of .I file at the beginning of the buffer. If the read is successful, the number of characters read is displayed. Upon completion, the new current line is the last line read into the buffer. If the .I file name starts with .CR ! , the rest of the line is interpreted as a shell command whose standard output is to be read. For example, .C $r !ls appends a listing of files in the current directory to the end of the file being edited. A shell command is not remembered as the current file name. .TP .RC ( .,. ) s/ \s-1\f2RE\fP\s0 /\s-1\f2replacement\s0\fP/\s-1\f2flags\s0\fP The .CR s (substitute) command searches each addressed line for an occurrence of the specified RE. In each line in which a match is found, all (nonoverlapped) matched strings are replaced by .I replacement if the global replacement indicator .CR g appears after the command. If the global indicator does not appear, only the first occurrence of the matched string is replaced. If a number .I n appears after the command, only the .IR n th occurrence of the matched string on each addressed line is replaced. It is an error for the substitution to fail on all addressed lines. Any character other than space or newline can be used instead of .CR / to delimit the RE and .IR replacement . Upon completion, the new current line is the last line on which a substitution occurred. (Also see WARNINGS below.) .PD .IP If an ampersand .RC ( & ) appears in .IR replacement , it is replaced by the string matching the RE on the current line. The special meaning of .CR & in this context can be suppressed by preceding it with .CR \e . .IP As a more general feature, the characters .CI \e n\f1, where .I n is a digit, are replaced by the text matched by the .IR n th regular subexpression of the specified RE enclosed between .CR \e( and .CR \e) . When nested parenthesized subexpressions are present, .I n is determined by counting occurrences of .CR \e( , starting from the left. .IP When the character .CR % is the only character in .IR replacement , the .I replacement used in the most recent substitute command is used as the .I replacement in the current substitute command. The .CR % loses its special meaning when it is in a replacement string containing more than one character or when preceded by a .CR \e . .IP A line can be split by substituting a newline character into it. The newline in .I replacement must be escaped by preceding it by .CR \e . Such substitution cannot be done as part of a .CR g or .CR v command list. .IP The value of .I flags is zero or more of: .RS .RS .TP .I n Substitute for the .IR n th occurrence only of the RE found on each addressed line. .TP .CR g Substitute for all nonoverlapped occurrences of the RE on each addressed line. .TP .CR l Write to standard output the final line in which a substitution was made. The line is written in the format specified for the .CR l command. .TP .CR n Write to standard output the final line in which a substitution was made. The line is written in the format specified for the .CR n command. .TP .CR p Write to standard output the final line in which a substitution was made. The line is written in the format specified for the .CR p command. .RE .RE .TP .RC ( .,. ) t \f2a\fP Same as .CR m command, except that a copy of the addressed lines is placed after address .I a (which can be 0). Upon completion, the new current line is the last line of the copy. .TP .CR u The .CR u (undo) command nullifies the effect of the most recent command that modified anything in the buffer, that is, the most recent .CR a , .CR c , .CR d , .CR g , .CR G , .CR i , .CR j , .CR m , .CR r , .CR s , .CR t , .CR v , or .CR V command. All changes made to the buffer by a .CR g , .CR G , .CR v , or .CR V global command are "undone" as a single change; if no changes were made by the global command (such as with .CI g/ RE /p\c ), the .CR u command has no effect. The current line number is set to the value it had immediately before the command started. .TP .RC ( 1,$ ) v/ \s-1\f2RE\fP\s0 "/\s-1\f2command-list\fP\s0" The complement of the global command .CR g in that the lines marked during the first step are those that do .B not match the RE. .TP .RC ( 1,$ ) V/ \f2RE\fP / The complement of the interactive global command .CR G in that the lines marked during the first step are those that do .B not match the RE. .TP .RC ( 1,$ ) w \0\f2file\fP The .CR w (write) command writes the addressed lines into the named file. If the file does not exist, it is created with mode 666 (readable and writable by everyone), unless the current .CR umask setting dictates otherwise (see .IR umask (1). The remembered file name is not changed unless .I file is the very first file name encountered since .CR ed was invoked. If no file name is given, the remembered file name, if any, is used (see the .CR e and .CR f commands). Upon completion, the current line address is unchanged. If the command is successful, the number of characters written is displayed. .IP If the .I file name starts with .CR ! , the rest of the line is interpreted as a shell command whose standard input is the addressed lines. Such a shell command is not remembered as the current file name. .TP .CR X A key string is demanded from the standard input. Subsequent .CR e , .CR r , and .CR w commands will encrypt and decrypt the text with this key, using the algorithm of .IR crypt (1). An explicitly empty key turns off encryption. .TP .RC ( $ ) = The line number of the addressed line is displayed. The current line address is unchanged by this command. .TP .CI ! "shell-command" The remainder of the line after the .CR !\& is sent to the shell to be interpreted and executed as a command. Within the text of that command, the unescaped character .CR % is replaced with the remembered file name. If a .CR !\& appears as the first character of the shell command, it is replaced with the text of the previous shell command. Thus, .CR !!\& repeats the last shell command. If any expansion is performed, the expanded line is echoed. Upon completion, the current line address is unchanged. .TP .RC ( .+1 )\ \f2newline\fP An address alone on a line causes the addressed line to be printed. A newline alone is equivalent to .CR .+1p . This technique is useful for stepping forward through the buffer. .PP If an interrupt signal (ASCII DEL or BREAK) is sent, .CR ed prints a .CR ?\& and returns to its command level. .PP The following size limitations apply: 256 characters per global command list, 64 characters per file name, and 32 MB characters in the buffer. The limit on the number of lines depends on the amount of user memory: each line takes 1 word. .SH EXTERNAL INFLUENCES .SS Environment Variables .PP .CR SHELL determines the preferred command-line interpreter for use in all .CR ! -style commands. If this variable is null or not set, the POSIX shell, .CR /usr/bin/sh , is used (see .IR sh-posix (1)). .PP When set, .CR TMPDIR specifies a directory to be used for temporary files, overriding the default directory, .CR /tmp . .PP .CR LANG provides a default value for internationalization variables that are unset or null. If .CR LANG is unset or null, the default value is "C" (see .IR lang (5)). If any internationalization variable contains an invalid setting, all internationalization variables default to "C". See .IR environ (5). .PP If .CR LC_ALL is set to a nonempty string value, it overrides the values of all the other internationalization variables, including .CR LANG . .PP .CR LC_CTYPE determines the interpretation of text as single- and/or multibyte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .CR LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .CR NLSPATH determines the location of message catalogues for the processing of .CR LC_MESSAGES . .SS International Code Set Support Single- and multibyte character code sets are supported. .SH DIAGNOSTICS .RS .TP 8 .CR ?\& Command error. Use .CR h or .CR H to get a detailed explanation. .TP .CI ? file Inaccessible file. Use .CR h or .CR H to get a detailed explanation. .RE .PP If changes have been made in the buffer since the last .CR w command that wrote the entire buffer, .CR ed warns you if you attempt to destroy the buffer with an .CR e or .CR q command. .CR ed displays .CR ?\& or .CR "warning: expecting `w'" , then continues normal editing unless you enter a second .CR e or .CR q command, in which case the second command is executed. The .CR -s or .CR - command-line option inhibits this feature. .SH EXAMPLES Make a simple substitution in .CR file-1 from a shell script, changing the first occurrence of .CR abc in any line to .CR xyz , and save the changes in .CR file-2 . .nf .IP .C "cat - << EOF | ed -s file-1" .C "1,$ s/abc/xyz/" .C "w file-2" .C "q" .C "EOF" .fi .PP Note that, if a command fails, the editor exits immediately. .SH WARNINGS A .CR !\& command cannot be subject to a .CR g or a .CR v command. .PP The .CR !\& command and the .CR !\& escape from the .CR e , .CR r , and .CR w commands cannot be used if the the editor is invoked from a restricted shell (see .IR sh (1)). .PP The sequence .CR \en in a regular expression does not match a newline character. .PP The .CR l command does not handle DEL correctly. .PP Files encrypted directly with the .CR crypt command with the null key cannot be edited (see .IR crypt (1)). .PP If the editor input is coming from a command file (e.g., .CR "ed file < ed-cmd-file)" , the editor exits at the first failure of a command in the command file. .PP When reading a file, .CR ed discards ASCII NUL characters and all characters after the last newline. This can cause unexpected behavior when using regular expressions to search for character sequences containing NUL characters or text near end-of-file. .SH AUTHOR .CR ed was developed by HP and OSF. .SH FILES .TP 10 .CI /tmp/e p Temporary buffer file where .I p is the process number. .PD 0 .TP .CR ed.hup Work is saved here if the terminal is hung up. .PD .SH SEE ALSO awk(1), csh(1), crypt(1), ex(1), grep(1), ksh(1), sed(1), sh(1), sh-bourne(1), sh-posix(1), stty(1), vi(1), fspec(4), environ(5), lang(5), regexp(5). .PP The .CR ed section in .IR "Text Processing: User's Guide" . .SH STANDARDS CONFORMANCE .CR ed ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR red ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4ed\f1 \- line-oriented text editor@@@\f3ed(1)\f1 .\" index@\f4red\f1 \- restricted line-oriented text editor@@@\f3ed(1)\f1 .\" index@line-oriented text editor@@@\f3ed(1)\f1 .\" index@editor: line-oriented@@@\f3ed(1)\f1 .\" index@text editor: line-oriented@@@\f3ed(1)\f1 .\" .\" toc@\f3ed(1)\f1:\0\0\f4ed\f1, \f4red\f1@@@line-oriented text editor .\" toc@\f4red\f1:\0\0restricted line-oriented text editor@@@see \f3ed(1)\f1 .\" .\" links@ed.1 red.1 .\" $Header: ex.1,v 78.2 96/05/09 10:48:44 ssa Exp $ .TA e .TH ex 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ex, edit \- extended line-oriented text editor .SH SYNOPSIS .CR ex .RC [ - ] .RC [ -l ] .RC [ -r ] .RC [ -R ] .RC [ -t .IR tag ] .RC [ -v ] .RC [ -V ] .RC [ -w\c .IR size ] .RC [ -x ] .RC [ +\c .IR command ] .ifn .br .ifn \0\0\0\0 .RI [ file \0...] .PP .SS "XPG4 Synopsis" .CR ex .RC [ -rR ] .RC [ "-s " \(or .CR -v ] .\" .CR |\ -v ] .RC [ -c .IR command ] .RC [ -t .IR tag ] .RC [ -w .IR size ] .RI [ file " ...]" .PP .SS "Obsolescent Options" .PP .CR ex .RC [ -rR ] .RC [ - \(or .CR -v ] .\" .CR |\ -v ] .RC [+\c .IR command ] .RC [ -t .IR tag ] .RC [ -w .IR size ] .RI [ file " ...]" .PP .CR edit .RC [ - ] .RC [ -l ] .RC [ -r ] .RC [ -R ] .RC [ -t .IR tag ] .RC [ -v ] .RC [ -V ] .RC [ -w\c .IR size ] .RC [ -x ] .RC [ +\c .IR command ] .ifn .br .ifn \0\0\0\0 .RI [ file \0...] .SS Remarks The program names .CR ex , .CR edit , .CR vi , .CR view , and .CR vedit are separate personalities of the same program. This manual entry describes the behavior of the .CR ex / edit personality. On many HP-UX and other similar systems, .CR e is a synonym for .CR ex . .SH DESCRIPTION The .CR ex program is the line-oriented personality of a text editor that also supports screen-oriented editing (see .IR vi (1)). .PP (XPG4 only.) Certain block-mode terminals do not have all the capabilities necessary to support the complete .C ex definition, such as the full-screen editing commands (\c .CR visual mode or .CR open mode). When these commands cannot be supported on such terminals, this condition shall neither produce an error message such as "not an editor command" nor report a syntax error. .PP The .CR edit program is identical to .CR ex , except that some editor option defaults are altered to make the editor somewhat friendlier for beginning and casual users (see Editor Options below). .SS Options and Arguments .CR ex recognizes the following command-line options and arguments: .ifn .TP 10 .ift .TP 15 .CR - (Obsolescent) Suppress all interactive-user feedback. This is useful when editor commands are taken from scripts. .TP .CR "-s " (XPG4 only.) .IP Suppress all interactive-user feedback. This is useful when editor commands are taken from scripts. .IP Ignore the value of the .C TERM and any implementation terminal type and assume the terminal is a type incapable of supporting visual mode. .IP Suppress the use of the .C EXINIT environment variable and the reading of the .C .exrc file. .TP .CR -l Set the .CR lisp editor option (see Editor Options below). .TP .CR -r Recover the specified .IR file s after an editor or system crash. If no .I file is specified, a list of all saved files is printed. You must be the owner of the saved file in order to recover it (superuser cannot recover files owned by other users). .TP .CR -R Set the .CR readonly editor option to prevent overwriting a file inadvertently (see Editor Options below). .TP .CI -t " tag" (XPG4 only.) Edit the file containing the specified .IR tag and proceed as if the first command were .CR :tag .IR tag . The tags represented by the .C -t .I tag and the .C ta command is optional. It shall be provided on any system that also provides a confirming implementation of .CR ctags , Otherwise, the use of the .C -t produces undefined results. .IP Execute the .CR tag .IR tag command to load and position a predefined file. See the .CR tag command in Command Descriptions and the .CR tags editor option in Editor Options below. .TP .CR -v Invoke visual mode .RC ( vi ). .TP .CR -V Set verbose mode. Editor commands are displayed as they are executed when they are input from an .CR .exrc file or a source file (see the .CR source command in Command Descriptions below). .TP .CI -w " size" Set the value of the .CR window editor option to .IR size (see Editor Options below). If .I size is omitted, it defaults to .CR 3 . .TP .CR -x Set encryption mode. You are prompted for a key to initiate the creation or editing of an encrypted file (see the .CR crypt command in Command Descriptions below). .TP .CI -c " command" (XPG4 only.) .TP .CI + command (Obsolescent) Begin editing by executing the specified .CR ex search or positioning .IR command . .TP .I file Specify the file or files to be edited. If more than one .I file is specified, they are processed in the order given. If the .CR -r option is also specified, the files are read from the recovery area. .PP .RE (XPG4 only.) If both the .CR -t .IR tag and .CR -c .IR command options are given, the .CR -t .IR tag shall be processed first;i.e, the file containing the tag is selected by the .CR -t and then the command is executed. .PP .RE .SS Definitions .BR "Current file" . The name of the file being edited by .CR ex is called the current file. Text from the current file is read into a work area, and all editing changes are performed on this work area. Changes do not affect the original file until the work area is explicitly written back to the file. If the .CR % character is used as a file name, it is replaced by the current file name. .PP .BR "Alternate file" . The alternate file is the name of the last file mentioned in an editor command, or the previous current file name if the last file mentioned becomes the current file. If the .CR # character is used as a file name, it is replaced by the alternate file name. .PP .BR "Buffers" . Twenty-six buffers named .CR a through .CR z can be used for saving blocks of text during the edit. If the buffer name is specified in uppercase, text is appended to the existing buffer contents rather than overwriting it. .PP .BR "Readonly flag" . The .CR readonly flag can be cleared from within the editor by setting the .CR noreadonly editor option (see Editor Options below). Writing to a different file is allowed even when the .CR readonly flag is set. Also, a write can be forced to a .CR readonly file by using .CR !\& after the write command (see the .CR write command in Command Descriptions below). .PP .BR "Interrupt" . If an interrupt signal is received, and commands are being supplied from a keyboard, .CR ex returns to command mode. If editor commands are coming from a file, an interrupt signal causes .CR ex to abort. .PP .BR "System crash" . If the system crashes or .CR ex aborts due to an internal error or unexpected signal, .CR ex attempts to preserve the work area if any unwritten changes were made. Use the .CR -r command-line option to retrieve the saved changes. .PP .BR "Command mode/input mode" . .CR ex starts up in command mode, as indicated by the colon .RC ( : ) prompt. .CR ex switches to input mode whenever an .CR append , .CR change , or .CR insert command is encountered. To terminate input mode and return to command mode, type a period .RC ( . ) alone at the beginning of a line. .PP .BR "Comments" . Command lines beginning with a quotation mark (\c .C """\c" ) are ignored (this is useful for placing comments in an editor script). .PP .BR "Multiple commands" can be combined on a single line by separating them with a vertical bar character .RC ( | ). However, global commands, comments, and the shell escape command must be the last command on a line because they cannot be terminated by a .CR | character. .SS Addressing (XPG4 only.) Addressing in .C ex relates to the current line. In general, the current line shall be the last line affected by the command; the exact effect on the current line is discussed under the description of each command. When the buffer contains no lines, the current line shall be set to zero. .PP .CR ex recognizes the following line address forms: .RS .TP 15 .CR .\& Dot or period .RC ( . ) refers to the current line. There is always a current line whose position can be the result of an explicit movement command or the result of a command that affects multiple lines (in which case it is usually the last line affected). .TP .I n The .IR n th line in the work area. Lines are numbered sequentially, starting at line 1. .TP .CR $ The last line in the work area. .TP .CR % Abbreviation for .CR 1,$ , meaning the entire work area. .TP .PD 0 .CR + \f2n\f1,\0 + [ + ]...\& .TP .CR - \f2n\f1,\0 - [ - ]...\& .ift .sp -2v .PD An offset relative to the current line or the preceding line specification. .CR + means forward; .CR - means backward. For example, the forms .CR .+3 , .CR +3 , and .CR +++ are equivalent. .PD .TP .PD 0 .CI / re / .TP .CI ? re ?\& .sp -2v The line containing the pattern .IR re , scanning forward .RC ( / ) or backward .RC ( ? ). The trailing .CR / or .CR ?\& can be omitted if the line is only being displayed. If .I re is omitted, .CR ex uses the more recently set of either the scanning string or the substitution string (see Regular Expressions below). .PD .TP .CI ' x Lines can be marked using single lowercase letters (see the .CR mark command in Command Descriptions below). .CI ' x refers to the line marked with .IR x . In addition, the previous current line is marked before each nonrelative motion. This line can be referred to by using .CR ' for .I x (thus .CR '' refers to the previous current line). .IP (XPG4 only.) Commands require zero, one or two addresses. Commands that require zero addresses shall regard the presence of an address as an error. .RE .PP (XPG4 only.) Adjacent address in a .C range shall be separated from each other by a comma (,) or a semicolon(;). In the latter case, the current line(.) shall be set to the first address, and only then is the second address calculated. This feature can be ued to determine the starting line for forwards and backwards searches. The second address of any two-address sequence shall correspond to the first address. The first address shall be less than or equal to the second address. The first address shall be greater than or equal to the first line of the editing buffer, and the last address shall be less than or equal to the last line of the editing buffer. Any other case shall be an error. .RE .PP Addresses for commands consist of a series of line addresses (specified as above), separated by a comma .RC ( , ) or semicolon .RC ( ; ). Such address lists are evaluated left-to-right. When the separator is a semicolon, the current line is set to the value of the previous address before the next address is interpreted. If more addresses are given than the command requires, then all but the last one or two are ignored. Where a command requires two addresses, the first line addressed must precede the second one in the work area. A null (missing) address in a list defaults to the current line. .SS Regular Expression The editor maintains copies of two regular expression strings at all times: the substitution string, and the scanning string. The substitute command sets the substitution string to the regular expression used. Both the global-command and the regular-expression form of line addressing (see Addressing above) for all commands set the scanning string to the regular expression used. These strings are used as default regular expressions as described under Addressing, the .CR global command, and the .CR substitute command. .PP The editor supports Basic Regular Expressions (see .IR regexp (5)) with the following modifications: .RS .TP 12 .CR \e< The .CR \e< matches the beginning of a "word"; that is, the matched string must begin in a letter, digit, or underline, and must be preceded by the beginning of the line or a character other than the above. This construct can only be used at the beginning of a regular expression (as in .I \e The .CR \e> matches the end of a "word" (see previous paragraph). This construct can only be used at the end of a regular expression (as in .I word\e>), but not in the middle .I (word1\e> word2). .TP .CR ~ Match the replacement part of the last .CR substitute command. .TP .CI [ string ] The positional quoting within bracket expressions defined by Basic Regular Expressions is replaced by the use of the backslash .RC ( \e ) to quote bracket-expression special characters. .TP .CR nomagic When the editor option .CR nomagic is set, the only characters with special meanings are .CR ^ at the beginning of a pattern, .CR $ at the end of a pattern, and \e. The characters ., *, .CR [ , and .CR ~ lose their special meanings unless escaped by a .CR \e . .RE .SS Replacement Strings The character .CR & in the replacement string stands for the text matched by the pattern to be replaced. Use .CR \e& if the .CR nomagic editor option is set. .PP The character .CR ~ is replaced by the replacement part of the previous .CR substitute command. Use .CR \e~ if the .CR nomagic editor option is set. .PP The sequence .CI \e n\f1, where .I n is an integer, is replaced by the text matched by the subpattern enclosed in the .IR n th set of parentheses .CR \e( and .CR \e) . .PP The sequence .CR \eu (\c .CR \el ) causes the immediately following character in the replacement to be converted to uppercase (lowercase), if the character is a letter. The sequence .CR \eU (\c .CR \eL ) turns case conversion on, until the sequence .CR \eE or .CR \ee is encountered, or the end of the replacement string is reached. .br .ne 24 .SS Command Names and Abbreviations The following table summarizes the line-mode commands. The commands whose names are enclosed in parentheses are available only in their abbreviated forms. .PP .vs +1 .TS center box tab(;); lB lB | lB lB | lB lB lf4p+1 lf4p+1 | lf4p+1 lf4p+1 | lf4p+1 lf4p+1. Command;Abbr.;Command;Abbr.;Command;Abbr. _ abbreviate;ab;next;n;tag;ta append;a;number;nu #;unabbreviate;una args;ar;open;o;undo;u change;c;pop;\&;unmap;unm chdir;chd cd;preserve;pre;version;ve _ copy;co t;print;p;visual;vi crypt;cr X;put;pu;write;w wq delete;d;quit;q;xit;x edit;e ex;read;r;yank;ya file;f;recover;rec; _ global;g v;rewind;rew;\f1\s-1(execute buffer)\s+1;* @ insert;i;set;se;\f1\s-1(line number)\s+1;\&= join;j;shell;sh;\f1\s-1(left shift)\s+1;< list;l;source;so;\f1\s-1(right shift)\s+1;> map;\&;stop;st ^Z;\f1\s-1(scroll)\s+1;^D _ mark;ma k;substitute;s sr & ~;\f1\s-1(shell escape)\s+1;! move;m;suspend;su ^Z;\f1\s-1(window)\s+1;z .TE .vs .SS Command Descriptions In the following command descriptions, some arguments appear frequently. They are described below. .RS .TP 10 .I line A single line address, in any of the forms described in Addressing above. The default is the current line. .TP .I range A pair of line addresses separated by a comma or semicolon, as described in Addressing above. The default is the current line .RC ( .,. ). .TP .I count A positive integer specifying the number of lines to be affected by the command. The default is 1 or the number of lines in .IR range . .IP When .I count is specified, .I range is ineffective. Instead, only a line number should be specified to indicate the first line affected by the command. (If a range is given, the last line of the range is interpreted as the starting line for the command.) .TP .I flags One or more of the characters .CR # , .CR p , and .CR l . The corresponding command to print the line is executed after the command completes. Any number of .CR + or .CR - characters can also be given with these flags. The default is no flags. .RE .PP These modifiers are all optional. .PP When only a .I line or a .I range is specified (with a null command), the implied command is .CR print . If a null line is entered, the next line is printed (equivalent to .CR .+1p ) .TP 18 .IR buffer .BR "XPG4 Feature." One of a number of named areas for saving text. The named buffers are specified by the lowercase letters of the POSIX locale. Specifying .C buffer shall cause the area of the text affected by the command to be stored into the buffer as it was before the command took effect. This argument is also used on the .C put command and the visual mode "put" commands .RC ( p .RC "and " P ), to specify the buffer that shall provide the text to insert. .IP If the buffer name is specified in uppercase, and the buffer is to be modified, the buffer shall be appended to rather than being overwritten. If the buffer is not to be modified, the buffer name can be specified in lowercase or uppercase with the same results. There shall be also one unnamed buffer, which is the repository for all text deleteed or yanked when no buffer is specified. .IP There are also numbered buffers, 1 through 9, which shall be accessible only from visual mode. These buffers are special in that, in the visual mode, when deleted text is placed in the unnamed buffer, it also shall be placed in buffer 1, the previous contents buffer 1 shall be placed in buffer 2 and so on. Any text in the buffer 9 shall be lost. Text that is yanked into the unnamed buffer shall not modify the numbered buffers. Text cannot be placed directly into the numbered buffered, although it can be retrieved from them by using a visual mode "put" command with the buffer name given as s number. When the buffer modifier is not used in the commands below, the unnamed buffer shall be the default. .TP 18 .IR word .BR "XPG4 Feature." In the POSIX Locale, a .CR word consists of a maximal sequence of letters, digits and underscores, delimited at both ends by characters other than letters, digits, or underscores, or by the beginning or end of a word or the file. .CR ! A character that can be appended to the command to modify its operation, as detailed in the individual command descriptions. .IP If both a .CR count and .CR range is specified for a command that uses them, the number of lines affected shall be taken from the .CR count value rather than the .CR range . The starting line for the command shall be taken to be the first line addressed by the range. .IP When only a .CR line or .CR range is specified with no command, the implied command shall be either .CR print , .CR list , or .CR number ( .CR p , .CR l , or .CR # ). The command selected shall be the last of these three commands to be used. When no range or count is specified and the command line is a blank line, the current line shall be written, and the current line shall be set to .CR .+1 . .IP Zero or mode characters can precede or follow the addresses, count or command name. Any object following a command name (such as buffer, file etc) that begins with an alphabetic character shall be separated from the command name with at least one . .PP For each of the commands listed below, the command can be entered as the abbreviation (those characters in the Synopsis command word preceding the [), the full command (all characters shown for the command word, omitting the [ and ]), or any subset of the characters of the full command down to the abbreviation. .TP 18 .CR abbreviate .CR ab [ breviate ] .I word replacement .IP Add the named abbreviation to the current list. In visual mode, if .I word is typed as a complete word during input, it is replaced by the string .IR replacement . .TP .CR append .I line .CR a [ ppend ][ ! ] .IP Enter input mode; the input text is placed after the specified line. If line 0 is specified, the text is placed at the beginning of the work area. The last input line becomes the current line, or the target line if no lines are input. .IP Appending .CR !\& to the command toggles the .CR autoindent editor option setting for this insert only. .TP .CR args .CR ar [ gs ] .IP Prints the argument, placing the current argument between .CR [ and .CR ] . .TP .CR change .I range .CR c [ hange ][ ! ] .I count .IP Enter input mode; the input text replaces the specified lines. The last input line becomes the current line; if no lines are input, the effect is the same as a delete. .IP Appending .CR !\& to the command toggles the .CR autoindent editor option setting for this insert only. .TP .CR chdir .CR chd [ ir ][ ! ]\0[\c .IR directory ] .br .CR cd [ ! ]\0[\c .IR directory ] .IP Change the working directory to .IR directory . If .I directory is omitted, the value of the .CR HOME environment variable is used. If the work area has been modified since the last write and the name of the file being edited does not begin with a slash .RC ( / ), a warning is issued and the working directory is not changed. To force a change of directory in this case, append the character .CR !\& to the command. .TP .CR copy .I range .CR co [ py ] .I line\0flags .br .IC range " t " "line flags" .IP A copy of the specified lines .RI ( range ) is placed after the specified destination .IR line ; line 0 specifies that the lines are to be placed at the beginning of the work area. (The letter .CR t is an alternative abbreviation for the .CR copy command.) .TP .CR crypt .CR cr [ ypt ] .br .CR X .IP The user is prompted for a key with which to enter encryption mode. This command can also be used to change the key entered from a previous .CR crypt command or the .CR -x command line option. If no key is supplied in response to the prompt (that is, only carriage return is pressed), encryption mode is canceled and the work area is written out in plain-text form by subsequent write commands. .IP While in encryption mode, all file input is decrypted using the current key. However, while an input file is being processed, if a block of text (approximately 1024 bytes) is encountered that contains only 7-bit ASCII characters, that block of text is assumed to be plain-text and is not decrypted. All file output, except that piped via a .CR !\& shell escape to another command, is encrypted using the current key. .IP The temporary file used by the editor to manage the work area is not encrypted until the current work area is discarded (or written out) and editing begins on a new file. When creating a new file that requires encryption protection, ensure that the work area file is also encrypted by specifying the .CR -x option when invoking the editor. .TP .CR delete .I range .CR d [ elete ] .I buffer\ count .IP The specified lines are deleted from the work area. If a named .I buffer is specified, the deleted text is saved in it. If no buffer is specified, the unnamed buffer is used (that is, the buffer where the most recently deleted or yanked text is placed by default). The new current line is the line after the deleted lines or the last line of the file if the deleted lines were at the end of the file. .TP .CR edit .CR e [ dit ][ ! ] .RC [ + .IR line ] .I file .br .CR ex [ ! ] .RC [ + .IR line ] .I file .IP Begin editing a new file .RC ( ex is an alternative name for the .CR edit command). If the current work area has been modified since the last write, a warning is printed and the command is aborted. This action can be overridden by appending the character .CR !\& to the command .RC ( e!\& .IR file ). The current line is the last line of the work area unless it is executed from within .IR vi , in which case the current line is the first line of the work area. If the .CI + line option is specified, the current line is set to the specified position, where .I line can be a number (or .CR $ ) or specified as .CI / re or .CI ? re\f1. .TP .CR file .CR f [ ile ] .IP Print the current file name and other information, including the number of lines and the current position. .TP .CR global .I range .CR g [ lobal ][ ! ] .CI / re / .I command ...\& .br .I range .CR v .CI / re / .I command ...\& .IP Perform .I command on lines within .I range (or on the entire work area if no .I range is given) that contain .IR re . First mark the lines within the given .I range that match the pattern .IR re . If the pattern is omitted, the more recently set of either the substitution string or the scanning string is used (see Regular Expressions above). Then the given .IR command s are executed with .CR .\& set to each marked line. Any character other than a letter or a digit can be used to delimit the pattern instead of the .CR / . .IP .I command can be specified on multiple lines by hiding new-lines with a backslash. If .I command is omitted, each line is printed. .CR append , .CR change , and .CR insert commands are allowed; the terminating dot can be omitted if it ends .I command or .IR command s. The .CR visual command is also permitted (unless the .CR global command itself has been issued from visual mode), and takes input from the terminal. (If .I command contains a visual-mode command (that is, .CR open or .CR visual ), the visual-mode command must be terminated by the visual-mode .CR Q command in order to proceed to the next marked line.) .IP The .CR global command itself and the .CR undo command are not allowed in .IR command . The editor options .CR autoprint , .CR autoindent , and .CR report are inhibited. .IP Appending a .CR !\& to the .CR global command (that is, .CR g! \0...) or using the alternate name .CR v causes .I command to be run on the lines within .I range that do not match the pattern. .TP .CR insert .I line .CR i [ nsert ][ ! ] .IP Enter input mode; the input text is placed before the specified line. The last line input becomes the current line, or the line before the target line, if no lines are input. .IP Appending .CR !\& to the command toggles the .CR autoindent editor option setting for this insert only. .TP .CR join .I range .CR j [ oin ][ ! ] .I count\0flags .IP Join together the text from the specified lines into one line. White space is adjusted to provide at least one blank character (two if a period appears at the end of a line, or none if the first character of a line is a closing parenthesis .RC ( ) )). Extra white space at the beginning of a line is discarded. .IP Appending a .CR !\& to the command causes a simpler join with no white-space processing. .TP .CR list .I range .CR l [ ist ] .I ount\0flags .IP Print the specified lines with tabs displayed as .CR ^I and the end of each line marked with a trailing .CR $ . (The only useful flag is .CR # for line numbers.) The last line printed becomes the current line. .TP .CR map .CR map .RI key \(or\c .CR #\c .IR n .I action .br .CR map!\& .RI key \(or\c .CR #\c .IR n .I action .IP The .CR map and .CR map!\& commands define macros for use in visual mode. The first argument, .IR key , can be a single character or a multicharacter sequence. In the special sequence, .CI # n\f1, .I n is a digit referring to the function key .IR n . Special characters, whitespace, and newline must be escaped with a .CR ^V to be entered in the arguments. The .I key argument cannot contain a colon .RC ( : ) as its first character, nor can a multicharacter sequence begin with an alphabetic character. .IP Macros defined by .CR map are effective in visual command mode. Macros defined by .CR map!\& are effective in visual input mode. When .I key or the function key corresponding to .CI # n is entered, the editor interprets the operation as though .I action were typed. .IP The .CR map or .CR map!\& command without options displays the corresponding current list of macros. .IP See also the editor options .CR keyboardedit , .CR keyboardedit! , .CR timeout , and .CR timeoutlen in Editor Options below. .TP .CR mark .IC line .CR ma [ rk ] .I x .br .IC line " k " x .IP The specified line is given the specified mark .IR x , which must be a single lowercase letter .RC ( a - z ). .RI x must be preceded by a space or tab. The current line position is not affected. .CR k is an alternate name for .CR mark . .TP .CR move .I range .CR m [ ove ] .I line .IP Move the specified lines .RI ( range ) to follow the target .IR line . The first line moved becomes the current line. .TP .CR next .CR n [ ext ][ ! ]\0[ .IR file \0...] .IP The next file from the command line argument list is edited. Appending a .CR !\& to the command overrides the warning about the work area having been modified since the last write (and discards any changes unless the .CR autowrite editor option is set). The argument list can be replaced by specifying a new one on this command line. .TP .CR number .I range .CR nu [ mber ] .I count flags .br .IC "range " # " count flags" .IP (The .CR # character is an alternative abbreviation for the .CR number command.) Print the lines, each preceded by its line number (the only useful flag is .CR l ). The last line printed becomes the current line. .TP .CR open .I line .CR o [ pen ] .CI / re / .I flags .IP Enter open mode, which is similar to visual mode with a one-line window. All the visual-mode commands are available. If a match is found in .IR line for the optional regular expression, the cursor is placed at the start of the matching pattern. Use the visual mode command .CR Q to exit from open mode. For more information, see .IR vi (1). .TP .CR pop .CR pop [ ! ] .IP Load the file whose name is stored at the top of the tag stack and set the current line to the stored location. The top entry of the tag stack is deleted. (The current file name is placed on the stack when you execute the line mode .CR tag command or the visual mode .CR ^] command.) .IP .CR ! overrides the warning about the work area having been modified since the last write; any changes are discarded unless the .CR autowrite editor option is set). .TP .CR preserve .CR pre [ serve ] .IP The current editor work area is saved as if the system had just crashed. Use this command in emergencies, for example when a write does not work and the work area cannot be saved in any other way. Use the .CR -r command-line option to recover the file. After the file has been preserved, a mail message shall be sent to the user. The message shall contain the name of the file, the time of preservation and an .CR ex command that could be used to recover the file. Additional information may be included in the mail message. .TP .CR print .CI range .CR p [ rint ] .I count .IP Print the specified lines, with non-printing characters printed as control characters in the form .CR ^x ; DEL is represented as .CR ^? . The last line printed becomes the current line. .TP .CR put .I line .CR pu [ t ] .I buffer .IP Place deleted or "yanked" lines after .IR line . A buffer can be specified; otherwise, the text in the unnamed buffer (that is, the buffer in which deleted or yanked text is placed by default) is restored. The current line indicator shall be set to the first line put back. .TP .CR quit .CR q [ uit ][ ! ] .IP Terminate the edit. If the work area has been modified since the last write, a warning is printed and the command fails. To force termination without preserving changes, append .CR !\& to the command. .TP .CR read .I line .CR r [ ead ] .I file .IP Place a copy of the specified .I file in the work area after the target line (which can be line 0 to place text at the beginning). If no .I file is named, the current file is the default. If no current file exists, .I file becomes the current file. The last line read becomes the current line except in visual mode where the first line read becomes the current line. .IP If .CR file is given as .CI ! string\f1, .I string is interpreted as a system command and passed to the command interpreter; the resultant output is read into the work area. A blank or tab must precede the .CR ! . .TP .CR recover .CR rec [ over ][ ! ] .I file .IP Recover .I file from the save area, after an accidental hangup or a system crash. If the current work area has been modified since the last write, a warning is printed and the command is aborted. This action can be overridden by appending the character .CR !\& to the command .RC ( rec!\& .IR file ). .TP .CR rewind .CR rew [ ind ][ ! ] .IP The argument list is rewound, and the first file in the list is edited. This shall be equivalent to a .CR next command with the current argument list as its operands. If the current buffer has been modified since the last write, a warning shall be written and the command shall be aborted. Any warnings can be overridden by appending a .CR ! . The current indicator line shall be affected by the editor options, .CR autowrite and .CR writeany . .TP .CR set .CR se [ t ] .RC [ all ] .br .CR se [ t ] .RC [ no ]\f2boolean-option\f1 ? .br .CR se [ t ] .RC \f2value-option\f1[ ? ] .br .CR se [ t ] .IR boolean-option .br .CR se [ t ] .CI no boolean-option .br .CR se [ t ] .IC value-option = value .IP Set and display the values of the editor options (see Editor Options below). .IP With no arguments, the command prints those editor options whose values have been changed from the default settings. If .CR all is specified, it prints all current option values. .IP The second and third forms display the current value of the specified option. The .CR ?\& is necessary only for Boolean options. .IP The fourth form turns a Boolean option on. The fifth form turns a Boolean option off. .IP The sixth form assigns values to string and numeric options. Spaces and tabs in strings must be escaped with a leading backslash .RC ( \e ). .IP The last five forms can be combined; interpretation is left-to-right. .TP .CR shell .CR sh [ ell ] .IP Execute the command interpreter specified by the .CR shell editor option (see Editor Options below). Editing is resumed when you exit from the command interpreter. .TP .CR source .CR so [ urce ] .I file .IP Read and execute commands from the specified .IR file . .CR so commands can be nested. The maximum supported nesting depths is implementation defined, but shall be at least one. .TP .CR substitute .I range .CR s [ ubstitute ] .CI / re / repl / .I options count flags .br .IC "range " s " options count flags" .br .IC "range " & " options count flags" .br .IC "range " sr " options count flags" .br .IC "range " ~ " options count flags" .br .IC "range " s\e? repl .br .IC "range " s\e& repl .IP On each specified line, the first instance of the pattern .I re is replaced by the string .IR repl . (See Regular Expressions and Replacement Strings above.) Any character other than a letter or a digit can be used to delimit the pattern instead of the .CR / . .IP If you include the .CR g (global) option, all instances of the pattern in the line are substituted. .IP If you include the .CR c (confirm) option, you are queried about whether to perform each individual substitution, as follows: Before each substitution the line is displayed with the pattern to be replaced marked underneath with carets .RC ( ^ ). Type .CR y to cause the substitution to be performed; any other input to abort it. The last line substituted becomes the current line. .IP If the substitution pattern .I re is omitted .RC ( s// \f2repl / ), the more recently set of either the substitution string or the scanning string is used (see Regular Expressions above). .IP If the .CR s or .CR & forms of the command are used, the substitution pattern defaults to the previous substitution string and the replacement string defaults to the previous replacement string used. .IP If the .CR sr or .CR ~ forms of the command are used, the substitution pattern defaults to the more recently set of either the substitution string or the scanning string and the replacement string defaults to the previous replacement string used. .IP The form .CI s\e? repl is equivalent to .CI s/ scan-re / repl / \f1, where .I scan-re is the previous scanning string. .IP The form .CI s\e& repl is equivalent to .CI s/ subs-re / repl / \f1, where .I subs-re is the previous substitution string. .TP .PD 0 .CR suspend .CR su [ spend ][ ! ] .TP .CR stop .CR st [ op ][ ! ] .br .I susp .PD .IP Suspend the editor job and return to the calling shell. .CR stop and .I susp are equivalent to .CR suspend . .I susp is the user process control suspend character, which is typically the character .CR ^Z (ASCII SUB) (see .IR stty (1)). This command is disabled if the calling shell does not support job control or has disabled it. .IP The work area is written to the current file before the editor is suspended if the .CR autowrite editor option is set, the .CR readonly editor option is not set, and the work area has been modified since the last write. To override this action, append the .CR !\& character to the .CR suspend or .CR stop command. .TP .CR tag .CR ta [ g ][ ! ] .I tag .IP Search the files specified by the .CR tags editor option (see Editor Options below) sequentially until a tag definition for .I tag is found. If .I tag is found, load the associated file into the work area and set the current position to the address specified in the tag definition. .IP The work area is written to the current file before the new file is loaded if the new file is different from the current file, the .CR autowrite editor option is set, the .CR readonly editor option is not set, and the work area has been modified since the last write. To override this action, append the .CR !\& character to the command. .IP If the .CR tagstack editor option is set, the current file name and line number is pushed onto the tag stack for later recall with the line mode .CR pop command or the visual mode .CR ^] command. .TP .CR unabbreviate .CR una [ bbreviate ] .I word .IP Delete .I word from the list of abbreviations (see the .CR abbreviate command above). .TP .CR undo .CR u [ ndo ] .IP Reverse the changes made by the previous editing command. For this purpose, .CR global and .CR visual are considered single commands. Commands that affect the external environment, such as .CR write , .CR edit , and .CR next , cannot be undone. An .CR undo can itself be reversed. .TP .CR unmap .CR unm [ ap ][ ! ] .I key .IP The macro definition for .I key is removed (see the .CR map command above). .TP .CR version .CR ve [ rsion ] .IP Print the current version information for the editor. .TP .CR visual .I line .CR vi [ sual ] .I type count flags .IP Enter visual mode at the specified .IR line . .IP The .I type can be one of the characters .CR + , .CR - , .CR . , or .CR ^ , as in the .CR z (window) command, to specify the position of the specified line on the screen window The default is to place the line at the top of the screen window. .IP A .I count specifies an initial window size; the default is the value of the editor option .CR window . .IP The flags .CR # and .CR l (ell) cause the lines in the visual window to be displayed in the corresponding mode (see the .CR number and .CR list commands). .IP Use the .CR Q command to exit visual mode. For more information, see .IR vi (1). .TP .CR write .RI [ range ] .CR w [ rite ][ ! ][\c .CR >> ] .I file .br .RI [ range ] .CR wq [ ! ][ >> ] .I file .IP Write the specified lines (or the entire work area, if no .I range is given) out to .IR file , printing the number of lines and characters written. If .I file is not specified, the default is the current file (the command fails with an error message if there is no current file and no file is specified). .IP If an alternate file is specified and the file exists, the write fails, but can be forced by appending .CR !\& to the command. To append to an existing file, append .CR >> to the command. If the file does not exist, an error is reported. .IP If the file is specified as .CI ! string\f1, .I string is interpreted as a system command, the command interpreter is invoked, and the specified lines are passed as standard input to the command. .IP The command .CR wq is equivalent to a .CR w followed by a .CR q . .CR wq!\& is equivalent to .CR w!\& followed by .CR q . .CR wq>> is equivalent to .CR w>> followed by .CR q . .TP .CR xit .CR x [ it ][ ! ][\c .CR >> ] .I file .IP If changes have been made to the work area, a .CR write command is executed with any options (such as .CR ! , .CR >> , or .IR file ) used by the .CR write command. Then (in any case) the .CR quit command is executed. .TP .CR yank .I range .CR ya [ nk ] .I buffer count .IP Place the specified lines in the named .IR buffer . If no buffer is specified, the unnamed buffer is used (that is, the buffer where the most recently deleted or yanked text is placed by default). .TP (execute buffer) .CR * .RI [ buffer ] .br .CR @ .RI [ buffer ] .PD .IP Execute the contents of .I buffer as an editor command. .I buffer can be the letter of a named buffer .RC ( a \(mi z ) or .CR * or .CR @ . The .CR * and the .CR @ forms of this command are equivalent. If a buffer is not specified or .I buffer is .CR * or .CR @ , the buffer last named in a .CR * or .CR @ command is executed. .TP (line number) .IC "line " = " flags" .IP Print the line number of the specified .IR line . The default is the last line. The current line position is not affected. .TP (scroll) .CR ^D .IP Print the next .I n lines, where .I n is the value of the .CR scroll editor option. .TP (shell escape) .CI ! \ command .br .IC "range " ! " command" .IP Pass the remainder of the line after the .CR !\& to the system command interpreter for execution. A warning is issued if the work area has been changed since the last write. A single .CR !\& is printed when the command completes. The current line position is not affected. .IP Within the text of .IR command , .CR % and .CR # are expanded as file names, and .CR !\& is replaced with the text of the previous .CR !\& command. Thus, .CR !!\& repeats the previous .CR !\& command. When such expansion is performed, the expanded line is echoed. .IP If you specify .IR range , the specified lines are passed to the command interpreter as standard input. The output from the .I command replaces the specified lines. .TP (shift left) .IC "range " < " count flags" .IP Shift the specified lines to the left. The number of spaces to be deleted is determined by the editor option .CR shiftwidth . Only whitespace (blanks and tabs) is lost in shifting; other characters are not affected. The last line changed becomes the current line. .TP (shift right) .IC "range " > " count flags" .br Shift the specified lines to the right by inserting whitespace The number of spaces inserted is determined by the editor option .CR shiftwidth . The last line changed becomes the current line. .TP (window) .IC "line " z " type count flags" .IP The number of lines specified by .I count are displayed. The default for .I count is the value of the editor option .CR window . .IP If .I type is omitted, .I count lines following the specified .I line are printed. .IP If .I type is specified, it must be one of the following characters: .RS .TP .PD 0 .CR + Display a window of lines following the addressed line. .TP .CR - Place the addressed line at the bottom of the window of displayed lines. .TP .CR .\& Place the addressed line at the center of the window. .TP .CR ^ Display a window of lines that is two windows prior to the addressed line. .TP .CR = Display the addressed line at the center of the window with a line of dashes above and below the addressed line. .PD .RE .IP The last line printed becomes the current line, except for the .CR = , where the addressed line becomes the current line. .SS "Editor Options" The command .CR ex has a number of options that modify its behavior. These options have default settings, which can be changed using the .CR set command (see above). Options can also be set at startup by putting a .CR set command string in the environment variable .CR EXINIT , or in the file .CR .exrc in the .CR HOME directory, or in .CR .exrc in the current directory. If .CR EXINIT exists, the .CR .exrc file in the .CR HOME directory is not executed. If the current directory is not the .CR HOME directory and the .CR exrc editor option is set (see below), the .CR .exrc file in the current directory is executed after .CR EXINIT or the .CR HOME directory .CR .exrc . .PP The editor obtains the horizontal and vertical size of the terminal screen from the .CR terminfo database (see .IR terminfo (4)). These values can be overridden by setting the .CR UNIX95 environment variable, which specifies to use the XPG4 behavior for this command. .CR COLUMNS and .CR LINES environment variables. See the .CR window editor option below for more information. .PP The following table shows the defaults that differ for the various editor personalities: .PP .ne 6 .vs+1 .TS center tab(@); lB cB s s s s lB cB s s s s lf4p+1 lf4p+1 lf4p+1 lf4p+1 lf4p+1 lf4p+1 . Name@Default Editor Options \_@\_ edit @nomagic@ novice@noreadonly@report=1@ showmode ex @ magic@nonovice@noreadonly@report=5@noshowmode vedit@nomagic@ novice@noreadonly@report=1@ showmode vi @ magic@nonovice@noreadonly@report=5@noshowmode view @ magic@nonovice@ readonly@report=5@noshowmode .TE .vs .PP Editor options are Boolean unless otherwise specified. Abbreviations are shown in parentheses. .TP 20 .CR autoindent \0( ai ) Indent each line in input mode (using blanks and tabs) to align with the previous line. Indentation begins after the line appended, or before the line inserted or the first line changed. Additional indentation can be provided as usual. Succeeding lines are automatically indented to the new alignment. .IP Reducing the indent is achieved by typing .CR ^D one or more times: the cursor is moved back to the next multiple of .CR shiftwidth spaces for each .CR ^D . A .CR ^ followed by a .CR ^D removes all indentation temporarily for the current line. A .CR 0 followed by a .CR ^D removes all indentation. .IP Reversed by .CR noautoindent \0( noai ). The default is .CR noautoindent . .TP .CR autoprint \0( ap ) The current line is printed after each command that changes work area text. Autoprint is suppressed in .CR global commands. Reversed by .CR noautoprint \0( noap ). The default is .CR autoprint . .TP .CR autowrite \0( aw ) The work area is written out to the current file if the work area has been modified and a .CR next , .CR rewind , or .CR !\& command is given. Reversed by .CR noautowrite \0( noaw ). The default is .CR noautowrite . .TP .CR beautify \0( bf ) Cause all control characters other than tab, newline, and formfeed to be discarded from the input text. Reversed by .CR nobeautify \0( nobf ). The default is .CR nobeautify . .TP .CR directory= \f2dirname\f1\0( dir ) Specify the directory in which the editor work area should be placed. This option only takes effect when a new work area is created. It should be set in .CR EXINIT or .CR .exrc to affect the location of the work area file for the edit file specified on the command line. The default is .CR /var/tmp . .IP If the specified directory is set from .CR EXINIT or a .CR .exrc file and is not writable by the user, the editor quits; if set interactively by the user, the editor issues an error message. .TP .CR "doubleescape" When set, two consecutive ESC (escape) characters are required to leave input mode. In input mode, a single ESC character followed by a different character causes .CR vi to issue an audible or visual warning (see the .CR flash editor option) and insert both characters into the work area. Reversed by .CR nodoubleescape . The default is .CR nodoubleescape . .IP The character sequences transmitted by the keyboard editing keys of some terminals are identical to some sequences of .CR vi user commands. If the mapping of these keys is enabled (see the .CR keyboardedit and .CR keyboardedit!\& options), .CR vi might not be able to reliably distinguish between the character sequence transmitted by an editing key and the same character sequence typed by a user. This problem is most likely to occur when the user types ESC to terminate input mode immediately followed by another .CR vi command. If you set the .CR doubleescape option, the ambiguity of this case is removed. .TP .CR edcompatible \0( ed ) Cause the presence of .CR g and .CR c suffixes on substitute commands to be remembered, and toggled by repeating the suffixes. Reversed by .CR noedcompatible \0( noed ). The default is .CR noedcompatible . .TP .CR errorbells \0( eb ) When set, error messages are preceded with a bell only on terminals that do not support a standout or highlighting mode such as inverse video. If the terminal supports highlighting, the bell is never used prior to error messages and this option has no effect. Note that visual-mode errors are signaled by the bell (regardless of the setting of this option) without an accompanying error message. .IP Reversed by .CR noerrorbells \0( noeb ). The default is .CR noerrorbells . .TP .CR exrc When set, the .CR .exrc file in the current directory is processed during editor initialization if the current directory is not the .CR HOME directory. This option is not set by default and must be set in the .CR EXINIT environment variable or the .CR HOME directory .CR .exrc file to have any effect. See the Editor Options introductory text above. Reversed by .CR noexrc . The default is .CR noexrc . .TP .CR flash \0( fl ) When set, the screen flashes instead of beeping, provided an appropriate .CR flash_screen entry is present in the .CR /usr/share/lib/terminfo database for the terminal being used. Reversed by .CR noflash \0( nofl ). The default is .CR flash . .TP .CR hardtabs= \f2number\f1\0( ht ) Define the spacing between hardware tab settings and the number of spaces used by the system when expanding tab characters. Tab stops are placed in each column number (starting at the left edge of the screen) that corresponds to an integer multiple of .IR number . The default is .CR "hardtabs=8" . .TP .CR ignorecase \0( ic ) All uppercase characters in the text are mapped to lowercase in regular expression matching. Also, all uppercase characters in regular expressions are mapped to lowercase, except in character class specifications. Reversed by .CR noignorecase \0( noic ). The default is .CR noignorecase . .TP .CR keyboardedit When set, any keyboard editing key mappings that are loaded automatically at initialization for command-mode use are enabled. If not set, these mappings are disabled (but not deleted). Use the .CR map command to get a list of the currently enabled command-mode mappings. Reversed by .CR nokeyboardedit . The default is .CR keyboardedit . .TP .CR keyboardedit!\& When set, the keyboard editing key mappings automatically loaded at initialization for input mode use are enabled. If not set, these mappings are disabled (but not deleted). Use the .CR map!\& command to list the currently enabled input-mode mappings. Reversed by .CR nokeyboardedit! . The default is .CR nokeyboardedit!\& for terminals whose keyboard editing keys send HP-style escape sequences (an ESC followed by a single letter). The default is .CR keyboardedit!\& for all other terminals. .TP .CR "lisp" Modify .CR autoindent mode and the .CR ( , .CR ) , .CR [[ , .CR ]] , .CR { , and .CR } commands in visual mode for .CR lisp source code. Reversed by .CR nolisp . The default is .CR nolisp . .TP .CR list Display all printed lines with tabs shown as .CR ^I , and the end of line marked by a .CR $ . Reversed by .CR nolist . The default is .CR nolist . .TP .CR magic Affect the interpretation of characters in regular expressions and substitution replacement strings (see Regular Expressions and Replacement Strings above). Reversed by .CR nomagic . The .CR ex , .CR vi , and .CR view default is .CR magic . The .CR edit and .CR vedit default is .CR nomagic . .TP .CR mesg Allows other users to use the .CR write command (see .IR write (1)) to send messages to your terminal, possibly disrupting the screen display. Unsetting this option .RC ( nomesg ) blocks write permission to your terminal from other system users while you are using the editor. Reversed by .CR nomesg . The default is .CR mesg . .TP .CR modelines \0( ml ) If set when the editor reads in a file, any .CR ex commands embedded in the first five and last five lines of the file are executed after .CR .exrc and .CR EXINIT commands are processed but before editing control is given to the user. The .CR ex commands must be prefixed by .CR ex: or .CR vi: and terminated by .CR : in a single line. Any number of other characters with the exception of the colon .RC ( : ) can precede or follow the embedded command. Reversed by .CR nomodelines \0( noml ). The default is .CR nomodelines . .TP .CR novice Use the version of the editor available for novices, known as .CR edit or .CR vedit . Reversed by .CR nonovice . The .CR ex , .CR vi , and .CR view default is .CR nonovice . The .CR edit , and .CR vedit default is .CR novice . .TP .CR number \0( nu ) Cause lines to be printed with line numbers. Reversed by .CR nonumber \0( nonu ). The default is .CR nonumber . .TP .CR optimize \0( opt ) Suppress automatic carriage returns on terminals that do not support direct cursor addressing. This streamlines text output in certain situations such as when printing multiple lines that contain leading whitespace. Reversed by .CR nooptimize \0( noopt ). The default is .CR nooptimize . .TP .CR paragraphs= \f2pair-string\f1\0( para ) The value of this option is a string whose successive pairs of characters specify the names of text-processing macros that begin paragraphs. (A macro appears in the text in the form .CI . xx\f1, where the .CR .\& is the first character in the line.) .IP If any macros have a single-character name, use a space character to substitute for the missing second character in the name. To type a space character in such situations, precede the space with a backslash .RC ( \e ) to prevent the editor from interpreting it as a delimiter. .IP The default is .CR paragraphs=IPLPPPQPP\e\0LIpplpipnpbp . .TP .CR prompt When set, command mode input is prompted for with a colon .RC ( : ); when unset, no prompt is displayed. Reversed by .CR noprompt . The default is .CR prompt . .TP .CR readonly \0( ro ) Set the .CR readonly flag for the file being edited, thus preventing accidental overwriting at the end of the session. This option is equivalent to invoking .CR ex , .CR edit , .CR vi , or .CR vedit with the .CR -R option or using the .CR view command. Reversed by .CR noreadonly \0( noro ). The .CR ex , .CR edit , .CR vi , and .CR vedit default is .CR noreadonly . The .CR view default is .CR readonly . .TP .CR redraw Simulate an intelligent terminal on a dumb terminal. During input mode, lines are continuously reprinted as text is entered. Since this is likely to require a large amount of output to the terminal, it is useful only at high transmission speeds. If .CR noredraw is set, lines are reprinted only when input mode is terminated and deleted lines are marked with an .CR @ in the left margin. Reversed by .CR noredraw . The default is .CR redraw . .TP .CR remap If set, macro translation allows for macros defined in terms of other macros; translation continues until the final product is obtained. If unset, a one-step translation only is done. Reversed by .CR noremap . The default is .CR remap . .TP .CI report= n The value of .IR n gives the number of lines that must be changed by a command before a report is displayed on the number of lines affected. If .IR n is 5, then changes are reported for 6 or more lines. The .CR ex , .CR vi , and .CR view default is .CR report=5 . The .CR edit , and .CR vedit default is .CR report=1 . .TP .CI scroll= n The value of .IR n determines the number of lines scrolled by a .CR ^D command and the number of lines displayed by the .CR z command (twice the value of scroll). The default is half the value of the .CR window option. .TP .CI sections= pair-string The value of this option is a string, in that successive pairs of characters specify the names of text-processing macros that begin sections. See the .CR paragraphs editor option above. The default is .CR sections=NHSHH\e\0HUuhsh+c . .TP .CR shell= \f2filename\f1\0( sh ) Set the file name of the shell to be used for the .CR !\& shell escape and the .CR shell command. It defaults to the value of your .CR SHELL environment variable, if set, and otherwise to .CR /usr/bin/sh . .TP .CR shiftwidth= \f2n\f1\0( sw ) Sets the indentation step value used by .CR autoindent and the shift .RC ( < and .CR > ) commands. The default is .CR shiftwidth=8 . .TP .CR showmatch \0( sm ) In visual mode, jump momentarily to the matching .CR ( or .CR { when you type a .CR ) or .CR } , if the match is still on the screen. Reversed by .CR noshowmatch \0( nosm ). The default is .CR noshowmatch . .TP .CR showmode \0( smd ) Display the current editor mode (such as .CR "INPUT MODE" , .CR "REPLACE 1 CHAR" , .CR "REPLACE MODE" ) in the lower right-hand corner of the screen during visual and open mode. Reversed by .CR noshowmode \0( nosmd ). The .CR ex , .CR vi , and .CR view default is .CR noshowmode . The .CR edit , and .CR vedit default is .CR showmode . .TP .CR slowopen \0( slow ) In visual mode, .CR slowopen prevents screen updates during input to improve throughput on unintelligent terminals. Reversed by .CR noslowopen \0( noslow ). The default is .CR noslowopen . .TP .CR tabstop= \f2n\f1\0( ts ) Sets the spacing of the software tab stops used by the editor to expand tabs in the input file. The default is .CR tabstop=8 . .TP .CR taglength= \f2n\f1\0( tl ) Set the maximum number of characters that should be treated as significant in a tag. Characters beyond the limit are ignored. A value of zero means that all characters in the tag are significant. The default is .CR taglength=0 . .TP .CR tags= [\f2filename\0\f1]... Specify the tags files to be used by the .CR tag command and the .CR -t command-line option. The default is .CR "tags=tags /usr/lib/tags" , specifying the file .CR tags in the current directory and the file .CR /usr/lib/tags . File names are separated by whitespace. .IP Each line of a tags file contains the following three fields separated by whitespace: the tag name, the name of the file to be edited, and an address specification (see Addressing above). A .CR tags file must be sorted in order by tag name. .IP The .CR ctags command (see .IR ctags (1)) creates tags files from C, Pascal and FORTRAN source files. .TP .CR tagstack \0( tgst ) Enable the pushdown stack of activated tags. Reversed by .CR notagstack \0( notgst ). The default is .CR tagstack . .IP When you enter a line mode .CR tag command or visual mode .CR ^] command, the current line number and file name are stored on the tag stack. A future line mode .CR pop command or visual mode .CR ^T command will return to the stored file name at the stored line number. .IP If the tag stack is disabled and then reenabled again, the stack continues where it left off. The .CR pop command does not work when the tag stack is disabled. .TP .CI term= termtype Define the type of terminal being used with the editor. The default value is obtained from the .CR TERM environment variable. If .CR TERM is unset or null, .CR term is set to .CR unknown . There is no difference between the .CR term and .CR ttytype editor options. Setting either one results in both being changed. .TP .CR terse Use shorter error messages. Reversed by .CR noterse . The default is .CR noterse . .TP .CR timeout \0( to ) If set, require that all the characters of a multicharacter macro name (the first argument in a .CR map command) must be received within the amount of time specified by the .CR timeoutlen option in order to be accepted as a match for the macro name. If not set, no limit is placed on how long to wait for the completion of a macro name. Reversed by .CR notimeout \0( noto ). The default is .CR timeout . .TP .CI timeoutlen= n Set, in milliseconds (ms), the length of the macro timeout period (see the .CR timeout editor option). This option has no effect unless .CR timeout is set. The value of .IR n must be at least 1. The default is .CR timeoutlen=500 (half a second). .TP .CR ttytype= \f2termtype\f1\0( tty ) Define the type of terminal being used with the editor. See the .CR term editor option for details. There is no difference between the .CR term and .CR ttytype editor options. Setting either one results in both being changed. .TP .CR warn Before executing a .CR !\& or .CR shell command escape, display the message .CR "[No write since last change]" if the work area has been modified since it was last loaded or fully written to a file. Reversed by .CR nowarn . The default is .CR warn . .TP .CR window= \f2lines\f1\0( wi ) Set the number of lines in a text window in visual mode. The default value is one less than the size of your terminal screen (as defined by the .CR LINES environment variable, if set, or the entry for your terminal in the .IR terminfo (4) data base otherwise). However, if the terminal baud rate (see .IR stty (1) is set to less than 1200 or 2400, the default value is reduced to a maximum of 8 or 16 lines, respectively. The startup value can be specified with the .CR -w command-line option. .TP .CI w300= lines If the terminal baud rate is less than 1200, set the .CR window editor option to the value specified. .TP .CI w1200= lines If the terminal baud rate is greater than or equal to 1200 but less than 2400, set the .CR window editor option to the value specified. .TP .CI w9600= lines If the terminal baud rate is greater than or equal to 2400, set the .CR window editor option to the value specified. .TP .CR wrapmargin= \f2n\f1\0( wm ) In visual mode only, if .IR n is greater than zero, a newline is automatically inserted in an input line at a word boundary, so that lines end at least .IR n spaces from the right margin of the terminal screen. The default is .CR wrapmargin=0 . .TP .CR wrapscan \0( ws ) When set, editor searches using .CI / re / (or .CI ? re ?\f1) continue silently from the beginning (or end) of the file upon reaching the end (or beginning) of the file (that is, the scan "wraps around"). When unset, editor searches stop at the beginning or the end of the file, as appropriate. Reversed by .CR nowrapscan \0( nows ). The default is .CR wrapscan . .TP .CR writeany \0( wa ) Inhibits the checks otherwise made before write commands, allowing a write to any file (provided the system allows it). Reversed by .CR nowriteany \0( nowa ). The default is .CR nowriteany . .SH EXTERNAL INFLUENCES .SS Environment Variables .CR COLUMNS This variable shall override the system-selected horizontal screen size. .PP .CR LINES overrides the system-selected vertical screen size, used as the number of lines in a screenful and as the vertical screen size in visual mode. .PP .CR PATH determines the search path for the shell command specified in the editor commands, .CR shell, .CR read , and .CR write . .PP .CR SHELL is variable that shall be interpreted as the preferred command-line interpreter for use in .CR ! , .CR shell , .CR read , and other commands with an operand of the form .CR !string . For the .CR shell command, the program shall be invoked with the single argument .CR -i . For all others, it shall be invoked with the two arguments .C -c and string. If no .C SHELL environment variable is set, or it is set to a null string, the .C sh utility shall be used. .PP .CR TERM is a variable that shall be interpreted as the name of the terminal type. If this variable is unset or null, an unspecified default terminal type shall be used. .PP .CR EXINIT is a variable that shall be interpreted to contain a list of .C ex commands that are executed on editor startup, before reading the first file. The list can contain multiple commands by separating then using a vertical line (|) character. .PP .CR HOME shall be interpreted as a pathname of a directory that shall be searched for an editor startup file name .CR .exrc . .PP .CR LC_COLLATE determines the collating sequence used in evaluating regular expressions and in processing the .CR tags file. If it is not specified or is null, it defaults to the value of .CR LANG . .PP .CR LC_CTYPE determines the interpretation of text as single and/or multibyte characters, the classification of characters as uppercase or lowercase letters, the shifting of the case of letters, and the characters matched by character class expressions in regular expressions. If it is not specified or is null, it defaults to the value of .CR LANG . .PP .CR LANG determines the language in which messages are displayed. If it is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP .CR LC_ALL determines the locale to be used to override any values for locale categories specified by the setting of .C LANG or any environment variable (beginning with .C LC_ ). .PP .CR LC_MESSAGES determines the processing of affirmative responses and the language in which messages should be written. .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .PP When set, the .CR TMPDIR environment variable specifies a directory to be used for temporary files, overriding the default directory .CR /var/tmp . .SS International Code Set Support Single- and multibyte character code sets are supported. .SH ASYNCHRONOUS EVENTS (XPG4 Only) The following actions shall be taken upon receipt of signals: .TP .CR SIGINT When an interrupt occurs, .C ex shall alert the terminal and write a message. The current editor command shall be aborted, and .C ex shall return to the command level and prompt for another command. If the standard input is not a terminal device, .C ex shall exit at the interrupt and return a nonzero exit status. .PP .TP .CR SIGCONT The screen shall be refreshed. .PP .TP .CR SHIGHUP If the current buffer has changed since the last .C e or .C w command, .C ex shall attempt to save the current file in a state such that it can be recovered later by an .C ex -r command. .PP .RE The action taken for all other signals is unspecified. .SH EXTENDED DESCRIPTION (XPG4 Only) The pathname of the file being edited by .C ex is referred to as the .C current file. The text of the file shall be read into a working version of the file (called .C buffer in this clause), and all editing changes shall be performed on that version; the changes shall have no effect on the original file until an .C ex command causes the file to be written out. Lines in the buffer may be limited to { .C LINE_MAX } bytes, and an error message may be written if the limit is exceeded during editing. .PP The .C alternate pathname is the name of the last file mentioned in an editor command, or the previous current pathname if the last file mentioned became the current file. When the .C % appears in a pathname entered as part of a command argument, it shall be replaced by the altername pathname. Any character, including .C % and .C # shall retain its literal value when preceded by a backslash. .PP When an error occurs, .C ex shall alert ther terminal and write a message. .PP If the system crashes, .C ex shall attempt to preserve the buffer if any unwritten changes were made. The command-line option .C -r can be used to retrieve the saved changes. .PP During initialization (before the first file is read or any user commands from the terminal are processed), if the environment variable .C EXINIT is set, the editor shall execute .C ex commands contained in that variable. If the variable is not set, .C ex shall attempt to read commands from the .CR $HOME/.exrc . If and only if .C EXINIT or .C $HOME/.exrc sets the editor option exrc, ex finally shall attempt to read commands from a file .C .exrc in the current directory. In the event that .C EXINIT is not set and the current directory is the home directory of the user, any .C .exrc file shall only be processed once. No .C .exrc shall be read unless it is owned by the same user ID as the effective user ID of the process. After any .C .exrc files are processed, any commands specified by the .C -c option shall be processed. .PP By default, .C ex shall start in the command mode, which shall be indicated by the ":" prompt. The input mode can be entered by .CR append , .CR insert , or .CR change commands. There is one other mode, visual mode, in which full screen editing is available. This is described more fully under the .CR visual command. The command line can consist of multiple .C ex commands separated by vertical-line characters(|). The use of commands that enter input or visual modes in this manner, unless they are the final command on the line, produces undefined results. .PP Command lines beginning with the double-quote character (") shall be ignored. This can be used for comments in an editor script. .\" .SH EXAMPLES (none needed) .SH WARNINGS The .CR undo command causes all marks to be lost on lines that are changed and then restored. .PP The .CR z command prints a number of logical rather than physical lines. More than a screenful of output can result if long lines are present. .PP Null characters are discarded in input files and cannot appear in resultant files. .PP On some systems, the recovery of an edit file with the .CR -r option is possible only if certain system-dependent actions are taken when the system is restarted. .PP Edit preserve files can only be recovered on systems running the same HP-UX release in which they were preserved. Preserve files are not recoverable across different releases. .PP On HP terminals, the attribute field of any function key specified by a .CI "map #" "n ..." command should be set to .CR normal rather than to the default of .CR transmit . .PP For information about line length limits, file size limits, etc., see the WARNINGS section of .IR vi (1). .SH EXIT STATUS (XPG4 Only) The .CR ex utility shall exit with one of the following values: .TP .CR 0 Successful completion. .PP .TP .CR >0 An error occurred. .SH AUTHOR .CR ex was developed by the University of California, Berkeley. The 16-bit extensions to .CR ex are based in part on software of the Toshiba Corporation. .SH FILES .ifn .TP 30 .ift .TP 40 .PD 0 .CR $HOME/.exrc Primary editor initialization file .TP .CR ./.exrc Secondary editor initialization file .TP .CR /usr/lbin/expreserve Preserve command .TP .CR /usr/lbin/exrecover Recover command .TP .CR /usr/share/lib/terminfo/*/* Description of terminal capabilities .TP .CR /var/preserve Preservation directory .TP .CI /var/tmp/Ex nnnnn Editor temporary file .TP .CI /var/tmp/Rx nnnnn Named buffer temporary file .PD .SH SEE ALSO ctags(1), ed(1), stty(1), vi(1), write(1), terminfo(4), environ(5), lang(5), regexp(5). .TP .IR "The Ultimate Guide to the vi and ex Text Editors" , Benjamin/Cummings Publishing Company, Inc., ISBN 0-8053-4460-8, HP part number 97005-90015. .SH STANDARDS COMPLIANCE .CR ex ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4e\f1 \- extended line-oriented text editor@@@\f3ex(1)\f1 .\" index@\f4ex\f1 \- extended line-oriented text editor@@@\f3ex(1)\f1 .\" index@\f4edit\f1 \- beginner's line-oriented text editor@@@\f3ex(1)\f1 .\" index@\f1editor: extended line-oriented text editor@@@\f3ex(1)\f1 .\" index@\f1line-oriented text editor@@@\f3ex(1)\f1 .\" index@\f1text editor, line-oriented@@@\f3ex(1)\f1 .\" .\" toc@\f3ex(1)\f1:\0\0\f4edit\f1, \f4ex\f1@@@extended line-oriented text editor .\" toc@\f4edit\f1:\0\0extended line-oriented text editor@@@see \f3ex(1)\f1 .\" .\" links@ex.1 edit.1 .\" .\" $Header: grep.1,v 76.1 95/08/23 17:54:30 ssa Exp $ .TA g .TH grep 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME grep, egrep, fgrep \- search a file for a pattern .SH SYNOPSIS .SS Plain call with pattern .C grep .RC [ -E \|\(or\| -F ] .RC [ -c \(or -l \c .RC \(or -q ] .RC [ -insvx ] .I pattern .RI [ \|file \0...\|] .SS Call with (multiple) \(mie pattern .C grep .RC [ -E \|\(or\| -F ] .RC [ -c \(or -l \c .RC \(or -q ] .RC [ -binsvx ] .CI -e \0pattern\|\f1... .RC [ -e .IR pattern \|]\0... .ifn .br .ifn \0\0\0\0 .RI [ \|file \0...\|] .SS Call with \(mif file .C grep .RC [ -E \|\(or\| -F ] .RC [ -c \(or -l \c .RC \(or -q ] .RC [ -insvx ] .RC [ -f .IR pattern_\|file\| ] .RI [ \|file \0...\|] .SS Obsolescent: .C egrep .RC [ -cefilnsv ] .RI [ \|expression\| ] .RI [ \|file \0...\|] .PP .C fgrep .RC [ -cefilnsvx ] .RI [ \|strings\| ] .RI [ \|file \0...\|] .SH DESCRIPTION The .CR grep command searches the input text .I files (standard input default) for lines matching a pattern. Normally, each line found is copied to the standard output. .CR grep supports the Basic Regular Expression syntax (see .IR regexp (5)). The .CR -E option .RC ( egrep ) supports Extended Regular Expression (ERE) syntax (see .IR regexp (5)). The .CR -F option .RC ( fgrep ) searches for fixed .IR strings using the fast Boyer-Moore string searching algorithm. The .CR -E and .CR -F options treat newlines embedded in the .I pattern as alternation characters. A null expression or string matches every line. .PP The forms .CR egrep and .CR fgrep are maintained for backward compatibility. The use of the .CR -E and .CR -F options is recommended for portability. .SS Options .RS .TP 20 .C -E Extended regular expressions. Each pattern specified is a sequence of one or more EREs. The EREs can be separated by newline characters or given in separate .CR -e .I expression options. A pattern matches an input line if any ERE in the sequence matches the contents of the input line without its trailing newline character. The same functionality is obtained by using .CR egrep . .TP .C -F Fixed strings. Each pattern specified is a sequence of one or more strings. Strings can be separated by newline characters or given in separate .CR -e .I expression options. A pattern matches an input line if the line contains any of the strings in the sequence. The same functionality is obtained by using .CR fgrep . .TP .C -b Each line is preceded by the block number on which it was found. This is useful in locating disk block numbers by context. Block numbers are calculated by dividing by 512 the number of bytes that have been read from the file and rounding down the result. .TP .C -c Only a count of matching lines is printed. .TP .CI -e " expression" Same as a simple .I expression argument, but useful when the .I expression begins with a hyphen .RC ( \- ). Multiple .CR -e options can be used to specify multiple patterns; an input line is selected if it matches any of the specified patterns. .TP .CI -f " pattern_\|file" The regular .I expression .RC ( grep and .CR "grep -E" ) or .I strings list .RC ( "grep -F" ) is taken from the .IR pattern_\|file . .TP .C -i Ignore uppercase/lowercase distinctions during comparisons. .TP .C -l Only the names of files with matching lines are listed (once), separated by newlines. If standard input is searched, a path name of .CR \- is listed. .TP .C -n Each line is preceded by its relative line number in the file starting at 1. The line number is reset for each file searched. This option is ignored if .CR -c , .CR -b , .CR -l , or .CR -q is specified. .TP .C -q (Quiet) Do not write anything to the standard output, regardless of matching lines. Exit with zero status upon finding the first matching line. Overrides any options that would produce output. .TP .C -s Error messages produced for nonexistent or unreadable files are suppressed. .TP .C -v All lines but those matching are printed. .TP .C -x (eXact) Matches are recognized only when the entire input line matches the fixed string or regular expression. .RE .PP In all cases in which output is generated, the file name is output if there is more than one input file. Care should be taken when using the characters .CR $ , .CR * , .CR [ , .CR ^ , .CR | , .CR ( , .CR ) , and .CR \e in .IR expression , because they are also meaningful to the shell. It is safest to enclose the entire .I expression argument in single quotes .RC ( ' ... ' ). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not specified or is set to the empty string, a default of .C C (see .IR lang (5)) is used. .PP .CR LC_ALL determines the locale to use to override any values for locale categories specified by the settings of .C LANG or any environment variables beginning with .CR LC_ . .PP .C LC_COLLATE determines the collating sequence used in evaluating regular expressions. .PP .C LC_CTYPE determines the interpretation of text as single byte and/or multi-byte characters, the classification of characters as letters, the case information for the .C -i option, and the characters matched by character class expressions in regular expressions. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If any internationalization variable contains an invalid setting, the commands behave as if all internationalization variables are set to .CR C . See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH RETURN VALUE Upon completion, .CR grep returns one of the following values: .RS .TP 5 .C 0 One or more matches found. .PD 0 .TP .C 1 No match found. .TP .C 2 Syntax error or inaccessible file (even if matches were found). .PD .RE .SH EXAMPLES In the Bourne shell .RI ( sh (1)) the following example searches two files, finding all lines containing occurrences of any of four strings: .nf .IP .C "grep -F 'if" .C then .C else .CI fi' " file1 file2" .fi .PP Note that the single quotes are necessary to tell .C grep -F when the strings have ended and the file names have begun. .PP For the C shell (see .IR csh (1)) the following command can be used: .IP .C grep -F 'if\e .C then\e .C else\e .CI fi' " file1 file2" .PP To search a file named .CR address containing the following entries: .nf .IP .C "Ken 112 Warring St. Apt. A" .C "Judy 387 Bowditch Apt. 12" .C "Ann 429 Sixth St." .fi .PP the command: .IP .C grep Judy address .PP prints: .IP .C "Judy 387 Bowditch Apt. 12" .ift .br .ift .ne 6 .PP To search a file for lines that contain either a .CR Dec or .CR Nov , use either of the following commands: .IP .CI "grep -E '[Dd]ec|[Nn]ov' " file .IP .CI "egrep -i 'dec|nov' " file .PP Search all files in the current directory for the string .CR xyz : .IP .C grep xyz * .PP Search all files in the current directory subtree for the string .CR xyz , and ensure that no error occurs due to file name expansion exceeding system argument list limits: .IP .C "find . -type f -print |xargs grep xyz" .PP The previous example does not print the name of files where string .CR xyz appears. To force .CR grep to print file names, add a second argument to the .CR grep command portion of the command line: .IP .C "find . -type f -print |xargs grep xyz /dev/null" .PP In this form, the first file name is that produced by .CR find , and the second file name is the null file. .SH WARNINGS .PP (XPG4 only.) If the .CR -q option is specified, the exit status will be zero if an input line is selected, even if an error was detected. Otherwise, default actions will be performed. .SH SEE ALSO sed(1), sh(1), regcomp(3C), environ(5), lang(5), regexp(5). .SH STANDARDS CONFORMANCE .CR grep ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR egrep ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR fgrep ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4grep\f1 \- search a file for a pattern (compact algorithm)@@@\f3grep(1)\f1 .\" index@\f4egrep\f1 \- search a file for a pattern@@@\f3grep(1)\f1 .\" index@\f4fgrep\f1 \- search a file for a specific string (fast algorithm)@@@\f3grep(1)\f1 .\" index@\f1search a file for a string or expression@@@\f3grep(1)\f1 .\" index@\f1files, search a file for a string or expression@@@\f3grep(1)\f1 .\" index@\f1string or expression, search a file for a@@@\f3grep(1)\f1 .\" index@\f1expression or string, search a file for a@@@\f3grep(1)\f1 .\" .\" toc@\f3grep(1)\f1:\0\0\f4grep\f1, \f4egrep\f1, \f4fgrep\f1@@@search a file for a pattern\f1 .\" toc@\f4egrep\f1:\0\0search a file for a pattern@@@\f1see \f3grep(1)\f1 .\" toc@\f4fgrep\f1:\0\0search a file for a string (fast)@@@\f1see \f3grep(1)\f1 .\" .\" links@grep.1 egrep.1 .\" links@grep.1 fgrep.1 .\" $Header: elm.1,v 80.1 96/09/20 17:33:43 ssa Exp $ .\" .\"X : such comments mark items removed in 10.30 .\" .\"Q : such comments mark queries for the lab, etc. .TA e .TH elm 1 .SH NAME elm \- process electronic mail through a screen-oriented interface .SH SYNOPSIS .HP .CR elm .RC [ \-aKkmtVz ] .RC [ \-f .IR folder ] .HP .CR elm .RC [ \-s .IR subject ] .IR address-list .HP .CR elm .CR \-c .RI [ alias-list ] .HP .C elm \-h .HP .C elm \-v .SH DESCRIPTION The .CR elm program is a screen-oriented electronic mail processing system. It supports the industry-wide MIME standard for nontext mail, a special forms message and forms reply mechanism, and an easy-to-use alias system for individuals and groups. .CR elm operates in three principal modes: .RS 2 .TP 3 \(bu Interactive mode, running as an interactive mail interface program. (First syntax.) .TP \(bu Message mode, sending a single interactive message to a list of mail addresses from a shell command line. (Second syntax.) .TP \(bu File mode, sending a file or command output to a list of mail addresses via a command-line pipe or redirection. (Second syntax.) .RE .PP In all three cases, .CR elm honors the values that are set in your .CR elmrc initialization file, in your .CR elm alias database, and in the system .CR elm alias database. .PP The modes are described below in inverse order (shortest description to longest). .SS Options The following options are recognized: .RS .TP 15 .CR \-a Set .CR arrow=ON . Use the arrow .RC ( \-> ) instead of the inverse bar to mark the current item in the various indexes. This overrides the setting of the .CR arrow boolean variable (see the ELM CONFIGURATION section). .TP .CR \-c Check alias. Check the aliases in .I alias-list against your personal .CR elm alias database and the system .CR elm alias database. The results are written to standard output. Errors are reported first, in the form: .RS .IP .C "(alias ""\c" .I alias\c .C """ is unknown)" .RE .IP Successes are reported in a header-entry format, with group aliases replaced by their members, in the form: .RS .nf .IP .CI "Expands to: " alias-address " (" fullname ")," .CI " " alias-address " (" fullname ")," .CR " " ...\& .CI " " alias-address " (" fullname ")" .fi .RE .IP If there is no .IR fullname , the "\c .CI " (" fullname ")\c" " portion is omitted. .TP .CI \-f \0folder Folder file. Read mail from the .I folder file rather than from the incoming mailbox. A folder file is in the standard mail file format, as created by the mail system or saved by .CR elm itself. .TP .CR \-h Help. Display an annotated list of command-line options. .\" .IP .\" If other options are specified, .\" they are silently ignored, except for .\" .CR \-v , .\" which is executed instead if it is specified first. .TP .CR \-k Set .CR softkeys=OFF . Disable the use of softkeys (HP 2622 function keys). This overrides the setting of the .CR softkeys boolean variable (see the ELM CONFIGURATION section). .TP .CR \-K Set .CR keypad=OFF and .CR softkeys=OFF . Disable the use of softkeys and arrow cursor keys. If your terminal does not have the HP 2622 function key protocols, this option is required. This overrides the settings of the .CR keypad and .CR softkeys boolean variables (see the ELM CONFIGURATION section). .TP .CR \-m Set .CR menu=OFF . Do not display the command menus on several Interactive Mode screens. This overrides the setting of the .CR menu boolean variable (see the ELM CONFIGURATION section). .TP .CI \-s \0subject Subject. Specify the subject for a File Mode or Message Mode message. .\" .IP .\" If other options are specified, .\" they are silently ignored, .\" except .\" .CR \-h .\" or .\" .CR \-v , .\" which are executed instead. .TP .CR \-t Set .CR usetite=OFF . Do not use the .CR termcap .CR ti / te and .CR terminfo .CR cup cursor-positioning entries. This overrides the setting of the .CR usetite boolean variable (see the ELM CONFIGURATION section). .TP .CR \-V Verbose transmission. Pass outbound messages to the .CR sendmail mail transport agent using the .CR -v option (see .IR sendmail (1M)). .TP .CR \-v Version. Print out the .CR elm version information. This displays the revision number and build date as well as the compilation features that were specified or omitted. .\" .IP .\" If other options are specified, .\" they are silently ignored, except for .\" .CR \-h , .\" which is executed instead if it is specified first. .TP .CR \-z Zero. Do not enter .CR elm if there is no mail in the incoming mailbox. .RE .SS Operands The following operands are recognized: .RS .TP 15 .I address-list A blank-separated list of one or more mail addresses, your .CR elm user aliases, or .CR elm system aliases. .TP .I alias-list A blank-separated list of one or more of your .CR elm user aliases or .CR elm system aliases. .RE .SS Terminology The following terms are used throughout this manpage. .TP 10 .B "blank" .IP A space or a tab character, sometimes known as linear white space. .TP .B "body" .IP The body of a message. See .BR message . .TP .B "boolean variable" .IP See .BR "configuration variable" . .TP .B "configuration variable" .IP A boolean, numeric, or string variable that defines default behavior in the .CR elm mail system. See the ELM CONFIGURATION section. .TP .B "elm system alias text file" .IP The source file, .CR /var/mail/.elm/aliases.text , for the .CR elm system alias database. .TP .B "elm user alias text file" .IP The source file , .CR $HOME/.elm/aliases.text , for a user's own .CR elm alias database. .TP .B "elm user headers file" .IP A file, .CR $HOME/.elm/elmheaders , where a user can specify special header entries that are included in all outbound messages. .TP .B "elmrc configuration file" .IP A file, .CR $HOME/.elm/elmrc , that defines the initial values for .CR elm configuration variables. .TP .B "environment variable" .IP A global variable set in the shell that called .CR elm . See the EXTERNAL INFLUENCES section. .TP .B "folder" .IP A file that contains mail messages in the format created by .CR sendmail or .CR elm. .TP .B "full name" .IP The first and last name of a user, as extracted from an alias text file or from the .CR /etc/passwd file. .TP .B "header" .IP The header of a message. See .BR message . .TP .B "header entry" .IP An entry in the header portion of a message, sometimes called a header field. .TP .B "incoming mailbox" .IP The mailbox where you receive your mail, usually .CI /var/mail/ loginname\f1. .TP .B "mail directory" .IP The directory, defined by the .CR maildir string variable, where a user normally stores mail messages in folders. .TP .B "mail transport agent (MTA)" .IP The program that sends and receives mail messages to and from other systems. On HP-UX systems, the MTA is .CR sendmail (see .IR sendmail(1M)). .TP .B "mailcap" .IP A file that contains information on how to compose and display mail messages that are not just seven- and eight-bit ASCII characters. .TP .B "metamail" .IP A system program that processes nontext mail messages. .TP .B "message" .IP In a folder, a sequence of text lines comprised of a message delimiter, a header, and a body. The message delimiter is a line in the form: .RS .IP .CI From\0 sender\0date .RE .IP The .B header starts after the message delimiter and ends with the first null line. The .B body begins at the null line and ends at the next message delimiter. A body can have subsections, called .B attachments or .BR "body parts" , which have are comprised of a boundary delimiter, a header, and a body. This process can be recursive. See the METAMAIL CONFIGURATION section for more details. .TP .B "numeric variable" .IP See .BR "configuration variable" . .TP .B "sendmail alias database" .IP The alias database, .CR /etc/mail/aliases , that is used by the .CR sendmail MTA to direct local mail. .TP .B "signature file" .IP A file that is appended to your outbound messages, usually containing information about yourself. You can have two signature files, one for messages to your local machine and one for other messages. See the .CR localsignature and .CR remotesignature string variables. .TP .B "string variable" .IP See .BR "configuration variable" . .TP .B "user name" .IP Usually the login or mailbox name of someone you send mail to. .TP .B "variable" .IP See .B "configuration variable" and .BR "environment variable" . .SH FILE MODE If standard input is connected to a pipe or to a file, and an .I address-list is specified, .CR elm operates in File Mode. .PP The output of the previous command in the pipe, or the content of the file, is mailed to the members of the .IR address-list . The .I address-list is expanded, based on your .CR elm alias database and the system .CR elm alias database, and placed in the .CR To:\& header entry. .PP If .CR \-s is omitted or .I subject is null, .I subject defaults to: .IP .CR "no subject (file transmission)" .PP The expressed or default value of .I subject is placed in the .CR "Subject:\&" header entry. .PP See the EXAMPLES section. .SH MESSAGE MODE If standard input is connected to your terminal, and an .I address-list is specified, .CR elm operates in Message Mode. .PP The .I address-list is expanded, based on your .CR elm alias database and the system .CR elm alias database, and placed in the .CR To:\& header entry. The .CR To:\& header entry is displayed, in the same form as for the Message Menu .CR m (mail) command in Interactive Mode. .PP The value of .IR subject , if nonnull, or a null string, is placed in the .CR "Subject:\&" header entry and the .CR "Subject:\&" line is displayed for modification. .PP If .CR "askcc" is .CR "ON" in your .CR elmrc file, you are prompted for .CR "Copies to:\&" . .PP Then the editor defined by the .CR editor string variable (if a signature file is not added) or the .CR alteditor string variable (if a signature file is added) is started so that you can write your message. .PP When you leave your editor, you enter the Send Menu, as described for Interactive Mode. .PP If you choose the Send Menu .CR s (send) command, the message is sent and the program terminates. If you select the Send Menu .CR f (forget) command, the message is stored in .CR $HOME/Canceled.mail and the program terminates. If you select other commands, the appropriate action occurs. .PP See the EXAMPLES section. .SH INTERACTIVE MODE If standard input is connected to your terminal, and there is no .IR address-list , .CR elm operates in a screen-oriented Interactive Mode. .PP If you do not have a .CR $HOME/.elm directory, or if you do not have a mail directory, defined by the .CR maildir string variable, you are asked in turn if they should be created. You can answer .CR y for .IR yes , .CR n for .IR no , or .CR q for .IR quit . For .CR y or .CR n , the directories are created or not, as appropriate, and the program continues. For .CR q , the program terminates. .SS Overview When invoked, .CR elm reads customized variables from file .CR $HOME/.elm/elmrc (if it exists) to initialize parameters. This file can be saved from within .CR elm and some of these variables can also be modified with the Message Menu .CR o (option) command. .PP .CR elm first displays the Main or Message Menu, which shows index entries for the messages in your incoming mailbox or selected mail folder. Among other options, you can read, print, reply to, and forward these messages, as well as initiate new mail messages to other users. .PP You can also move to the Alias Menu, where you can create, modify, and delete your personal aliases. From the Alias Menu, you can select one or more of your aliases and send a message to the corresponding users. .PP When you send a message, you can include attachments in a number of formats, such as PostScript, images, audio, and video, as well as plain text. The attachments are managed separately, which can be convenient both for you and your correspondents. .SS Sending Messages When you send a message, you use the editor defined by the .CR editor or .CR alteditor string variable. If .CR builtin is your editor, a set of commands described in the Built-In Editor subsection is available while composing your message .PP If the .CR elmheaders file exists (see the Header File subsection), all nonblank lines in the file are copied to the headers of all outbound mail. This is useful for adding special information headers such as .CR Organization:\& , .CR Phone:\& , and so forth. .SS MIME Support .CR elm supports the MIME protocols for headers and messages (RFC 1521 and RFC 1522) enabling it to view and send mail containing other than normal ASCII text. For example, the mail contents can be audio, video, images, etc., or a combination of these. .PP This also enables conformance with SMTP (RFC 821), which allows only 7-bit characters in the message, by using MIME-encoding .RC ( base64 and .CR quoted-printable ) to convert 8-bit data to 7-bit. .PP .CR elm also provides a facility to view multipart MIME messages. If .CR elm receives a message whose type is not .CR text/plain , it invokes .CR metamail , which invokes the appropriate utility (for example, .CR ghostview , .CR xv , an audio editor, .CR mpeg ) to display the different mail parts according to the content type (for example, .CR application/postscript , .CR image , .CR audio , .CR video ). .SS Aliases .CR elm has its own alias system that supports both personal and system-wide aliases. Personal aliases are specific to a single user; system aliases are available to everyone on the system where the system aliases reside (see .IR newalias (1)). You can access the Alias Menu by executing the Message Menu .CR a (alias) command. You can then create and save an alias for the current message, create and check other aliases, and send messages to one or more aliases. .PP Aliases are limited to 2500 bytes. If you wish to create a group alias that is longer than 2500 bytes, please ask your system administrator to create it for you in the .CR sendmail system alias file, .CR /etc/mail/aliases (see .IR sendmail (1M)). .SH INTERACTIVE MODE MENUS AND COMMANDS This section begins with the Message Menu, which is the main screen for Interactive Mode. The rest of the menus are presented alphabetically. .SS Message Menu The Message Index is displayed on the Message Menu. You can use the following commands to manipulate and send messages. Some commands use a series of prompts to complete their action. You can use .BR Ctrl-D to cancel their operations. .PP The commands are: .RS .TP 15 .CI !\& command Shell Escape. Send .I command to the shell defined by the .CR shell string variable without leaving .CR elm . .TP .CR # Display all known information about the current message. .TP .CR $ Resynchronize the messages without leaving .CR elm . If there are any messages marked for deletion, you are asked if you want to delete them. If any messages are deleted or any status flags have changed, the messages are written back to the mailbox file. All tags are removed. .TP .CR % Display the computed return address of the current message. .TP .CR * Set the current message pointer to the last message. .TP .CR + Display the next message index page, when applicable. .TP .CR \- Display the previous message index page, when applicable. .TP .CI / pattern Pattern match. Search for .IR pattern in the .IR from and .IR subject fields of the current message index. The search starts at the current message and wraps around to the beginning of the index. The current message pointer is set to the first message that matches. Uppercase and lowercase are treated as equivalent. .TP .CI // pattern Pattern match. Search for .IR pattern through all the lines of the current folder. The search starts at the current message and wraps around to the beginning of the folder. The current message pointer is set to the first message that matches. Uppercase and lowercase are treated as equivalent. .TP .CR < Calendar. Scan message for calendar entries and add them to your calendar file. A calendar entry is defined as a line whose first nonblank characters are .CR \-> , as in: .RS .nf .IP .CI \-> calendar-entry .fi .RE .IP The delimiter .CR \-> and surrounding blanks are removed before the entry is added to the calendar file. Resultant blank lines are ignored. You can define the calendar file name in your .CR elmrc file or with the Options Menu. .TP .CR = Set the current message pointer to the first message. .TP .CR > Save in folder. Same as the Message Menu .CR s (save) command. .TP .CI ? key\f1\0... Help on key. Display a one-line description of what each .I key does. .CR ?\& displays a summary listing for each command available. A period .RC ( .\& ) returns you to the Message Menu. .TP .CR @ Display a summary of the messages indexed on the current screen. .TP .CR | Pipe the current message or the set of tagged messages through other filters as desired. Use the shell defined by the .CR shell string variable. .TP .I n New current message. Change the current message pointer to the one indexed as .IR n . If the message is not on the current page of headers, the appropriate page displayed. .TP .B Return Read current message. The screen is cleared and the current message is displayed by the pager defined by the .CR pager string variable. .TP .CR a Alias. Switch to the Alias Menu. .TP .CR b Bounce mail. This is similar to forwarding a message, except that you do not edit the message and the return address is set to the original sender's address, rather than to your address. .TP .CR c Change folder. This command is used to change the file whose messages are displayed on the Message Menu. You are asked for a file name. The file must be in message format; otherwise, .CR elm aborts. You can use the customary wildcards for your shell, as well as the following special names: .RS .TP 15 .CR !\& Your incoming mail folder. .TP .CR > Your received folder, defined by the .CR receivedmail string variable. .TP .CR < Your sent folder, defined by the .CR sentmail string variable. .TP .CR .\& The previously used folder. .TP .CI @ alias The default folder for the login name associated with the .I alias alias. .TP .CI = filename A file in the directory defined by the .CR maildir string variable. .RE .TP .CR C Copy message. Save the current message or the set of tagged messages to a folder. You are prompted for a file name with a default value. The default value is a file in the .CR maildir directory with the user name of the sender of the first message in the set being saved. Any tags are cleared. Unlike the .CR > and .CR s commands, the messages are not marked for deletion and the current message pointer is not moved. .TP .CR d Delete. Mark the current message for deletion. See also .BR Ctrl-D , .CR u , and .BR Ctrl-U . .TP .B Ctrl-D Delete. Mark all messages for deletion that contain a specified pattern in the .CR From:\& and .CR Subject:\& header entries. See also .CR d , .CR u , and .BR Ctrl-U . .TP .CR e Edit. Allows you to physically edit the current mail folder using the editor defined by the .CR editor string variable. When you exit from your editor, .CR elm resynchronizes your mail folder (see the .CR $ command). .TP .CR f Forward the current message. You are asked if you want to edit the outbound message. If you answer .CR y , the characters defined by the .CR prefix string variable are prefixed to each line of the message and the editor defined by the .CR editor string variable will be invoked to allow you to edit the message. If you answer .CR n , the characters are not prefixed and the editor will not be invoked. In either case, you are prompted for .CR To:\& recipients, allowed to edit the .CR Subject:\& header entry, and, if the .CR askcc boolean variable is .CR ON , you are prompted for .CR Cc:\& recipients. .IP If the .CR userlevel numeric variable is .CR 1 (intermediate) or .CR 2 (expert), and there was a previous sent or forgotten message in this session, you are asked if you would like to .IP .C "Recall last kept message instead? (y/n)" .IP If you answer .CR y , the previous message is returned to the send buffer. If you answer .CR n , the current message is copied into the send buffer and your signature file (if any) is appended. .IP Then the editor is invoked if you chose to edit the outbound message (above). When you leave the editor, or if it was not invoked, the Send Menu is displayed. .TP .CR g Group reply. The reply is automatically sent .CR To:\& the sender of the message, with .CR Cc:\& to all the original .CR To:\& and .CR Cc:\& recipients. Otherwise, the action is the same as for the .CR r command. .TP .CR h Same as .BR Return , except that the message is displayed with all headers. .TP .CR j Move down. Move the current message pointer down to the next message. .TP .CR J Move down. Move the current message pointer down to the next undeleted message. .TP .CR k Move up. Move the current message pointer up to the previous message. .TP .CR K Move up. Move the current message pointer up to the previous undeleted message. .TP .CR l \0(ell) Limit the displayed messages to those that contain certain string values. You are prompted with .CR "Enter\ criteria:\&" . To set, add to, or clear the limiting criteria, type one of: .RS .TP 20 .CR all Clear all the criteria and restore the normal display. .TP .CI from \0string Restrict to entries that contain .IR string in the .CR From:\& header. .TP .CI subject \0string Restrict to entries that contain .IR string in the .CR Subject:\& header. .TP .CI to \0string Restrict to entries that contain .IR string in the .CR To:\& header. .RE .IP You can add limiting criteria by repeating the .CR l command. .TP .B Ctrl-L Redraw the screen. .TP .CR m Mail. Send mail to one or more addresses. You are prompted for .CR To:\& recipients, a .CR Subject:\& and, if the .CR askcc boolean variable is .CR ON , .CR Cc:\& recipients. .IP If the .CR userlevel numeric variable is .CR 1 (intermediate) or .CR 2 (expert), and there was a previous sent or forgotten message in this session, you are asked if you would like to .IP .C "Recall last kept message instead? (y/n)" .IP If you answer .CR y , the previous message is returned to the send buffer. If you answer .CR n , the signature file (if any) is copied into the send buffer. .IP Then, the editor defined by the .CR editor string variable is invoked. After you exit from your editor, the Send Menu is displayed. .TP .CR n Next message. Advances the current message pointer to the next message, and displays that message as for the .BR Return command. .TP .CR o Options. Invokes the Options Menu, permitting you to change certain configuration options. The changeable options are defined by the .CR configoptions string variable. .TP .CR p Print. Print the current message or the set of tagged messages using the command defined by the .CR print string variable. The current message pointer does not move. Tagged messages remain tagged. .TP .CR q Quit. Gracefully terminate, performing message cleanup according to defined personal preferences. You can choose to actually delete messages marked for deletion. For your incoming mailbox, you can choose to keep undeleted mail in the mailbox or move it to the received folder defined by the .CR receivedmail string variable. .IP If the .CR ask boolean variable is .CR ON , you may be asked the following questions. The actions described are all performed after you have answered all the relevant questions. .RS .PP .C "Delete messages? (y/n)" .IP This question is asked if you have messages marked for deletion. The default answer is provided by the .CR alwaysdelete boolean variable .RC ( ON means .CR y (yes) and .CR OFF means .CR n (no)). .IP If you answer .CR y , all messages marked for deletion will be deleted. .IP If you answer .CR n , all messages marked for deletion will be restored to their former read, unread, or new state. .RE .RS .PP .C "Move read messages to ""received"" folder? (y/n)" .IP This question is asked if you are reading your incoming mailbox and if you have messages that have been read. The default answer is provided by the .CR alwaysstore boolean variable .RC ( ON means .CR y (yes) and .CR OFF means .CR n (no)). .IP If you answer .CR y , undeleted messages that have been read will be moved to the folder defined by the .CR receivedmail string variable and the next question will also be asked. .IP If you answer .CR n , all undeleted messages are returned to your incoming mailbox and the next question is not asked. .RE .RS .PP .C "Keep unread messages in incoming mailbox? (y/n)" .IP This question is asked if you are reading your incoming mailbox, if you answered .CR y to the .CR "Move read messages" ...\& question (or it was not asked), and if you have messages that have not been read. The default answer is provided by the .CR alwayskeep boolean variable .RC ( ON means .CR y (yes) and .CR OFF means .CR n (no)). .IP If you answer .CR y , all undeleted unread (new and old) messages are returned to your incoming mailbox. .IP If you answer .CR n , all undeleted unread messages will be moved to the folder defined by the .CR receivedmail string variable. .RE .IP If the .CR ask boolean variable is .CR OFF , the answers to the questions (which are not displayed) are taken automatically from the values of the .CR alwaysdelete , .CR alwaysstore , and .CR alwayskeep boolean variables, respectively. .TP .CR Q Quick quit. This is equivalent to executing the .CR q command with the .CR ask boolean variable set to .CR OFF . .TP .CR r Reply to the sender of the current message. If the .CR autocopy boolean variable is .CR OFF , you are asked if the source message should be copied into the edit buffer. If it is .CR ON , the message is copied automatically. If copied in, all lines from the message are preceded by the prefix string defined by the .CR prefix string variable. The .CR To:\& header is set to the sender of the message (or the address in the .CR Reply-To:\& header, if one was set), the .CR Subject:\& is set to the subject of the message, preceded by .CR Re:\& , and presented for you to edit. If the .CR askcc boolean variable is .CR ON , you are prompted for .CR Cc:\& recipients. Then, the editor defined by the .CR editor string variable is invoked. After you exit from your editor, the Send Menu is displayed. .TP .CR s Save in folder (same as .CR > ). Save the current message or the set of tagged messages to a folder. You are prompted for a file name with a default value. The default value is a file in the .CR maildir directory with the login name of the sender of the first message in the set being saved. Any tags are cleared and the messages are marked for deletion. The current message pointer is moved to the first undeleted message after the last saved message. .TP .CR t Tag toggle. Tag the current message for a later operation and move the current message pointer to the next undeleted message. The operation can be one of .CR | , .CR C , .CR p , and .CR s . .IP Or, remove the tag from a tagged message. See also the .BR Ctrl-T command. .TP .CR T Tag toggle. Tag the current message for a later operation and remain at the current message. The operation can be one of .CR | , .CR C , .CR p , and .CR s . .IP Or, remove the tag from a tagged message. See also the .BR Ctrl-T command. .TP .B Ctrl-T Tag all messages containing the specified pattern. Or remove the tags from all tagged messages. .IP If any messages are currently tagged, you are asked if the tags should be removed. Answer .CR y to remove the old tags; answer .CR n to keep them. In either case, you are prompted for a string to match in either the .CR From:\& or .CR Subject:\& line of each message. All messages that match the criterion are tagged. If you enter a null string (carriage-return alone), no more messages are tagged. .TP .CR u Undelete. Remove the deletion mark from the current message. See also .CR d , .BR Ctrl-D , and .BR Ctrl-U . .TP .B Ctrl-U Undelete. Remove any deletion mark from all messages that contain a specified pattern in the .CR From:\& and .CR Subject:\& header entries. See also .CR d , .BR Ctrl-D , and .CR u . .TP .CR v View attachments. Invoke the Attachment View Menu for the current message. .TP .CR x Exit. Exit without changing the mailbox. If changes are pending, such as deletions, you are asked if they can be abandoned. If you answer .CR y , the changes are abandoned and the program terminates. If you answer .CR n the exit is abandoned and you return to the Message Menu command prompt. .TP .CR X Exit immediately without changing the mailbox. All pending changes are abandoned. .RE .SS Message Index The messages in the current folder are indexed on the Message Menu, one per line, in the format: .IP .IC sssnum\0mmm\0d\0from\0 ( lines ) \0subject .PP defined as: .RS .TP 10 .I sss A three-character status field, described in the Message Status subsection. .TP .I num The ordinal message index number. .TP .I mmm The month from the last .CR "Date:\&" header entry, or from the .CR From message header. .TP .I d The day from the last .CR "Date:\&" header entry, or from the .CR From message header. .TP .I from Either the sender name from the last .CR "From:\&" header entry or from the .CR "From" message header. .TP .I lines The number of lines in the message. .TP .I subject The subject description from the first .CR "Subject:\&" header entry, truncated to fit your screen. .RE .PP The current message index entry is either highlighted in inverse video or marked in the left margin with an arrow .RC ( \-> ). See the .CR \-a option in the Options subsection and the .CR arrow string variable in the ELM CONFIGURATION section. .SS Message Status The first three characters of each message index entry describe the message status. Each can be blank or one of the values described below in descending order of precedence. .PP When a message has more than one status flag of a particular type set, the highest-precedence indicator is displayed on the index line. For example, if a forms message .RC ( F ) is also marked as company confidential .RC ( C ), the .CR C rather than the .CR F status character is displayed. .PP .B "Column One: Variable Status" .PP .RS .TP .CR D Deleted. The message is marked for deletion. .TP .CR E Expired. The date specified in the .CR Expires:\& header entry is older than today. .CR elm accepts the following date formats: .RS .if n .TP 15 .if t .TP 25 .PD 0 .CR "Mon, 11 Jun 90" (format produced by .CR elm in the Header Menu) .TP .CR "Jun 11, 90" .TP .CR "11 Jun, 90" .TP .CR 9006111324GMT .RI "(ISO X.400 format:\0" YYMMDDhhmmzzz ) .PD .RE .TP .CR N New. The message was received after your last .CR elm session or during the current session. The message has not been read. .TP .CR O Old. The message was received before or during your last .CR elm session. It was marked .CR N in your last session and it was not read. .TP \0 Blank. The message has been read. .RE .PP .B "Column Two: Permanent Status" .PP .RS .TP .CR C Confidential. The .CR "Sensitivity:\ 3 header entry is present. The message is considered company confidential, as specified by the ISO X.400 standard. You can set this value for outbound mail with the user-defined option of the Header Menu. .TP .CR U Urgent. The message contains a .CR Priority:\& header entry. .TP .CR P Private. The .CR Sensitivity:\ 2" header entry is present. The message is considered private, as specified by the ISO X.400 standard. You can set this value for outbound mail with the user-defined option of the Header Menu. .TP .CR A Action. The message contains an .CR Action:\& header entry. .TP .CR F Forms. The message is an .CR elm forms message. The message contains a .CR "Content-Type:\ mailform" header entry. .TP .CR M MIME. The message or its attachments is in a MIME format that can be displayed using .CR metamail . .TP .CR ?\& MIME. The message or its attachments is in a MIME format whose version is not supported. .TP \& Blank. Normal status. .RE .PP .B "Column Three: Tagged Status" .PP .RS .TP .CR + Tagged. Tagged messages are handled as a group by some commands. See .CR t and other commands in the Message Menu subsection. .TP \& Blank. The message is not tagged. .RE .SS Built-In Editor When you are composing an outbound message with the .CR builtin built-in editor, it prompts you for text lines with an empty line. Enter a period .RC ( .\& ) to end the message and continue with the Send Menu. .PP Built-in editor commands are lines that begin with an escape character, defined by the .CR escape string variable. The default escape character is tilde .RC ( ~ ). .PP .B Note: Some remote login programs use tilde as their default escape character when it is the first character on a line. (You can tell, because the tilde does not print.) Usually, the tilde is transmitted when you enter a second character that is not recognized by the program or when you enter a second tilde. See the program documentation for further information. .PP The built-in editor commands are: .RS .TP 20 .CR "~!" \0[\f2command\f1] Execute the shell .IR command , if one is given (as in .CR ~!ls ), or start an interactive shell, using the shell defined by the .CR shell string variable. .TP .CI ~< \0command Execute the shell .IR command and place the output of the command into the editor buffer. For example, "\c .CR "~< who\c" " inserts the output of the .CR who command in your message. .TP .CR ~?\& Print a brief help menu. .TP .CR ~~ Start a line with a single tilde .RC ( ~ ) character. .TP .CR ~b Prompt for changes to the Blind-Carbon-Copy .RC ( Bcc:\& ) list. .TP .CR ~c Prompt for changes to the Carbon-Copy .RC ( Cc:\& ) list. .TP .CR ~e Invoke the editor defined for the .CR easyeditor string variable on the message, if possible. .TP .CR ~f \0[\f2options\f1] Add the specified list of messages or the current message. This uses .CR readmail which means that all .CR readmail options are available (see .IR readmail (1)). .TP .CR ~h Prompt for changes to all the available headers .RC ( To:\& , .CR Cc:\& , .CR Bcc:\& , and .CR Subject:\& ). .TP .CR ~m \0[\f2options\f1] Same as .CR ~f , but each line is prefixed with the current prefix. See the .CR prefix string variable. .TP .CR ~o Prompt for the name of an editor to use on the message. .TP .CR ~p Print out the message as typed in so far. .TP .CI ~r \0filename Include (read in) the contents of the specified file. .TP .CR ~s Prompt for changes to the .CR Subject:\& line. .TP .CR ~t Prompt for changes to the .CR To:\& list. .TP .CR ~v Invoke the editor defined for the .CR visualeditor string variable on the message, if possible. .RE .SS Alias Menu The Alias Menu is invoked with the Message Menu .CR a command. The source text for your alias file is stored in the file .CR $HOME/.elm/aliases.text . You can edit this file directly or with the following commands. .PP The aliases currently compiled into your database and the system database are displayed in an indexed list similar to the Message Menu. The entry format is described in the Alias Index subsection. The index is sorted in the order defined by the .CR aliassortby string variable. .PP The commands are: .RS .TP 15 .CR $ Resynchronize your alias text file and your alias database by rebuilding the database from the text file by running .CR newalias . Aliases marked for deletion are removed, tagged aliases are untagged, and new and changed aliases are recognized. The alias screen is updated to reflect these changes. .TP .CR + Display the next alias index page, when applicable. .TP .CR \- Display the previous alias index page, when applicable. .TP .CI / pattern Pattern match. Search for .IR pattern in the alias and user name fields of the alias list. The search starts at the current alias and wraps around to the beginning of the alias list. The current alias pointer is set to the first alias that matches. Uppercase and lowercase are treated as equivalent. .TP .CI // pattern Pattern match. Search for .IR pattern through all the fields of the alias list (alias, user name, comment, and address). The search starts at the current alias and wraps around to the beginning of the alias list. The current alias pointer is set to the first alias that matches. Uppercase and lowercase are treated as equivalent. .CI / pattern Pattern match. This command allows you to search through all the alias and username entries in the alias list, starting at the current alias and continuing through the end. If the first character of the pattern is a .CR / , then the comment and the fully expanded address fields are also included in the search. The search is case-insensitive. This allows you to find a specific alias in a situation where there are a large number of aliases. .TP .CI ? key\f1\0... Help on key. Display a one-line description of what each .I key does. .CR ?\& displays a summary listing for each command available. A period .RC ( .\& ) returns you to the Alias Menu. .TP .CR a Alias current message. This allows you to create an alias that has the return address of the current message as the address field of the alias. It prompts for a unique alias name and allows you to edit the comment and address fields. .TP .CR c Change the current user alias. The old values of the alias fields are used as the defaults in the prompts for the new values. You cannot change the alias name. If the alias name is one of a multiple-alias record, it is removed from that record and stored as a separate record. The old alias is marked .CR N . Changes are effective after the next alias resynchronization. .TP .CR d Mark the current user alias for deletion. The deletions are made when you exit from the Alias Menu with an .CR q , .CR r , or .CR i command or you resynchronize your alias database with the .CR $ command. (You cannot delete a system alias in this way.) .TP .BR Ctrl-D Delete user aliases with a specified search pattern. .TP .CR e Edit your .CR aliases.text file, using the editor defined in the .CR editor string variable. Your aliases are resynchronized when you finish editing (see the .CR $ command). .TP .CR f Display a fully expanded alias. The currently selected alias is fully expanded and displayed. .TP .CR i , I See the Alias Menu .CR q and .CR Q commands. .TP .CR j Move down. Move the current alias pointer down to the next alias. .TP .CR J Move down. Move the current alias pointer down to the next undeleted alias. .TP .CR k Move up. Move the current alias pointer up to the previous alias. .TP .CR K Move up. Move the current alias pointer up to the previous undeleted alias. .TP .CR l \0(ell) Limit the displayed aliases to certain types or those that contain certain string values. You are prompted with .CR "Enter criteria:\&" . To set, add to, or clear the limiting criteria, type one of: .RS .TP 20 .CR all Clear all the criteria and restore the normal display. .TP .CI alias \0string Restrict to alias names containing .IR string . .TP .CI name \0string Restrict to full names (first name and last name) containing .IR string . .TP .CR group Restrict to group aliases (can include system and user aliases). .TP .CR person Restrict to person aliases (can include system and user aliases). .TP .CR system Restrict to system aliases (can include group and person aliases). .TP .CR user Restrict to system aliases (can include group and person aliases). .RE .IP You can add limiting criteria by repeating the .CR l command. .TP .BR Ctrl-L Redraw the screen. .TP .CR m Mail to the current alias or to the set of tagged aliases. The corresponding expanded addresses are placed in the .CR To:\& header entry, and processing continues as for the Message Menu .CR m (mail) command. The tags are cleared. .TP .CR n Make a user alias. .CR elm prompts for a unique alias name, then for an address. The information provided is added to your individual alias_text file .RC ( $HOME/.elm/aliases.text ), then added to the database. .TP .CR q Exit. Return to the Message Menu. If aliases are marked for deletion, you are asked if you want to delete them. The alias index pointer is retained. If the alias text file was changed, the database is resynchronized. .TP .CR Q Exit. Return to the Message Menu. If aliases are marked for deletion, the mark is retained and the alias is not deleted. The alias index pointer is retained. If the alias text file was changed, the database is resynchronized. .TP .CR r , R See the Alias Menu .CR q and .CR Q commands. .TP .CR t Tag the current alias for a later operation and move the current alias pointer to the next undeleted alias. The operation can be one of .CR c , .CR m , or .CR n . .IP Or, remove the tag from a tagged alias. See also the .BR Ctrl-T command. .TP .CR T Tag. Tag the current alias for a later operation and remain at the current alias. The operation can be one of .CR c , .CR m , or .CR n . .IP Or, remove the tag from a tagged alias. See also the .BR Ctrl-T command. .TP .BR Ctrl-T Tag all aliases containing a specified pattern for a later operation. The operation can be one of .CR c , .CR m , or .CR n . Or remove the tags from all tagged aliases. .IP If any aliases are currently tagged, you are asked if the tags should be removed. Answer .CR y to remove the old tags; answer .CR n to keep them. In either case, you are prompted for a string to match in either the alias name or user name fields of each alias. All aliases that match the criterion are tagged. If you enter a null string (carriage-return alone) no more aliases are tagged. .TP .CR u Undelete. Remove the deletion mark from the current alias. See also .CR d , .BR Ctrl-D , and .BR Ctrl-U . .TP .BR Ctrl-U Undelete. Remove any deletion mark from all messages that contain a specified pattern in the .CR From:\& and .CR Subject:\& header entries. See also .CR d , .BR Ctrl-D , and .CR u . .TP .CR v View. Display the .IR address-list for the current alias. .TP .CR x Exit from the alias menu without processing any deletions. Aliases marked for deletion are unmarked and .CR newalias is not run, even if alias additions have been made. .RE .SS Alias Index The aliases in the current database are indexed on the Alias Menu, one per line. The database values are defined in .IR newalias (1). .IP .IR ssnum\0fullname [\c .CR ,\c .IR \0comment ]\c .IR \0type\0 [\c .CR (S)\c .RI ] \0alias .PP defined as: .RS .TP 10 .I ss A two-character status field. The first character can be: .RS .TP .CR D Delete. The alias is marked for deletion. .TP .CR N New. The alias is new or changed in the alias text file but is not included in the current database. Resynchronization is needed. .TP \& Blank. The alias is in the current database. .RE .IP The second character can be: .RS .TP .CR + Tag. The alias is tagged. .TP \& Blank. The alias is not tagged. .RE .TP .IR num The index number of the alias. .TP .IR fullname The full name for the alias, as it will be used in an expanded address. It has the form: .RS .IP .IR firstname\0lastname .RE .RS .TP 10 .IR firstname The first name, from the alias database. .TP .IR lastname The last name, from the alias database. .RE .TP .IR comment Comment, from the alias database. .TP .IR type Type of alias. This is .CR Person for an alias with a single address or .CR Group for an alias with two or more addresses. .TP .CR (S) If present, the entry is from the .CR elm system alias database. If absent, the entry is from your personal alias database. .TP .IR alias The alias name. If the record has multiple alias names, there is one index entry per name. .RE .SS Attachment Configuration Menu The Attachment Configuration Menu is invoked with the Attachment Send Menu .CR a (add) or .CR m (modify) command. The menu displays the default or current specification for an attachment. If it is called with the .CR a command, it automatically prompts for a file name. The commands are: .RS .TP .CR d Description. The value is placed in a .CR Content-Description:\& body-part header entry. The default is the file name. .TP .CR e Content-Transfer-Encoding. This is the method by which the file is encoded to allow it to pass through various Mail Transport Agents. The choices are: .RS .TP .CR 7bit Unencoded, normal .CR US-ASCII text. .TP .CR 8bit Unencoded 8-bit characters with the high-order bit set. .TP .CR quoted-printable Text with control characters and high-order-bit characters converted to a string in the form .CI = hh\f1, where .I hh is the hexadecimal representation of the character. An .CR = at the end of a line indicates that the source line was broken into two lines. .TP .CR base64 Any file type with bits encoded in 6-bit groups and rendered in numeric order as the .CR US-ASCII characters .CR A \(mi Z , .CR a \(mi z , .CR 0 \(mi 9 , .CR + , and .CR / . The last line may be padded to a multiple of 4 characters with .CR = characters. .TP .CR binary Unencoded binary data. .RE .IP The value is placed in a .CR Content-Transfer-Encoding:\& body-part header entry. The default is .CR 7bit . .TP .CR f File name. The name of the file to be attached. .CR elm examines the file and sets the values of Content-Transfer-Encoding, Content-Disposition, and Content-Type accordingly. .TP .CR p Content-Disposition. The value is placed in a .CR Content-Disposition:\& body-part header entry. The default is .CI "attachment; filename=" filename\f1. .TP .CR t Content-Type. The type of the file and supporting parameters, in the form: .RS .nf .IP .RC \f2type\fP / \f2subtype\fP\0[ ;\0 \f2parameter\fP]... .fi .RE .IP The .IR type can be one of .CR application , .CR audio , .CR image , .CR message , .CR text , or .CR video , as defined in RFC 1521. Although .CR multipart is also a valid type, you cannot specify it directly; .CR elm provides it as necessary and handles messages that contain it. The value is placed in a .CR Content-Type:\& body-part header entry. The default is .CR "text/plain; charset=US-ASCII" . .IP Some common entries are described below. See the METAMAIL CONFIGURATION section for additional information. .RS .TP .CR text/ \f2subtype\fP\0[ "; charset=" \f2charset\fP] This is relatively readable text that may be formatted with embedded text characters, as for possible subtypes .CR richtext or .CR html . The default .I subtype is .CR plain (unformatted in any way). The default .I charset is .CR US-ASCII . .TP .CR application/octet-stream This is a catch-all for files such as program binary, or files that contain control characters or characters with high-order bits set. .TP .CR application/postscript The file can be displayed with a PostScript-equipped printer or viewer. .TP .CR message/rfc822 This specifies that the file is in message format, as described in the Terminology subsection. .TP .CR image/jpeg ,\0 image/gif These are picture formats that require a display program. .TP .CR audio/basic This is an audio format that requires a reproduction program. .TP .CR video/mpeg This is an audio/video format that requires a reproduction program. .RE .RE .SS Attachment Send Menu The Attachment Send Menu is invoked with the Send Menu .CR a command. This menu displays a list of the attachments that will be sent in a message, one per line, as described in the Attachment Index subsection. .PP The commands are: .RS .TP 15 .CR a Add attachments. Call the Attachment Configuration Menu and prompt for a file name. .TP .CR d Delete an attachment. .TP .CR e Edit an attachment. Call the editor associated with the attachment if it is editable. .TP .CR j Move the current attachment pointer down to the next attachment. .TP .CR k Move the current attachment pointer up to the previous attachment. .TP .B Ctrl-L Redraw the screen. .TP .CR m Modify the attributes of an attachment. Call the Attachment Configuration Menu. .TP .CR p Print an attachment. See the Message Menu .CR p (print) command. .TP .CR q Quit. Return to the Send Menu. .TP .CR s Save an attachment. See the Message Menu .CR C (copy) command. .RE .SS Attachment View Menu The Attachment View Menu is invoked with the Send Menu .CR v command. This menu displays a list of the attachments in a folder message, one per line, as described in the Attachment Index subsection. .PP The commands are: .RS .TP 15 .BR Return Display the current attachment. .TP .CR j Move the current attachment pointer down to the next attachment. .TP .CR k Move the current attachment pointer up to the previous attachment. .TP .B Ctrl-L Redraw the screen. .TP .CR p Print the attachment. See the Message Menu .CR p (print) command. .TP .CR q Quit. Return to the previous attachment level or the Message Menu. .TP .CR s Save the attachment. The attachment is saved in the form it was received, as with the Message Menu .CR s (save) command. .TP .CR v View the subattachment list, if any. .RE .SS Attachment Index Attachments are listed on the Attachment Send Menu and the Attachment View Menu in the following format: .IP .IC num\0filename \0( size )\0\c .IC format \0[ encoding ]\0 .PP defined as: .RS .TP 10 .I num The index number of the attachment. .TP .I filename The name of the attached file. .TP .I size The size of the attachment in bytes, computed from the file or the message. .TP .IC type / subtype The type and subtype of the attachment. This value is placed or found in a .CR Content-Type:\& header. .TP .I encoding The encoding type. This value is placed or found in a .CR Content-Transfer-Encoding:\& header. .RE .SS Header Menu The Header Menu is invoked with the Send Menu .CR h command. It allows you to add, change, and delete a set of common header entries in your message. In general, if an item is empty, it is not included in the message. .PP The commands are: .RS .TP 15 .BR Return Return to Send Menu. .TP .CI ! command Shell. Execute .I command with the shell defined by the .CR shell string variable. .TP .CR a .CR Action:\& header. Enter any string. If this entry is present in a received message, .CR elm displays an .CR A in the Permanent Status column of the Message Index. .TP .CR b .CR Bcc:\& header. Enter a list of aliases and actual addresses. Aliases are expanded and shown as addresses and user names. .TP .CR c .CR Cc:\& header. Enter a list of aliases and actual addresses. Aliases are expanded and shown as addresses and user names. .TP .CR d Domainize. Convert non-Internet addresses to Internet format. The UUCP .CR !\& format .IC \f1(\fPhost . domain ! user\f1) becomes the Internet .CR @ format .IC \f1(\fPuser @ host . domain\f1). If .CI \&. domain is omitted, it defaults to .CR \&.uucp . .TP .CR e .CR Expires:\& header. Enter any numeric value from 1 to 56 (8 weeks). If this entry is present in a received message, .CR elm displays an .CR E in the Variable Status column of the Message Index when the computed date has passed. .TP .CR i .CR In-Reply-To:\& header. Enter a string. .TP .CR n .CR Precedence:\& header. Enter a precedence name. If the .CR precedences string variable is set and nonnull, the name must be one defined by the variable. If the name is associated with a priority, and the .CR Priority:\& header is null, the priority value is inserted in the .CR Priority:\& header. If .CR precedences is null or not set, you can enter any value. .IP If the precedence name matches one defined in the .CR sendmail configuration file .CR /etc/mail/sendmail.cf , the transmission priority is modified accordingly. If there is no match, the priority is not changed. .TP .CR p .CR Priority:\& header. Enter a string. If this entry is present in a received message, .CR elm displays a .CR U in the Permanent Status column of the Message Index .TP .CR r .CR Reply-To:\& header. Enter a personal alias or a single address. If it is present, .CR elm and other mailers use this header instead of the .CR From:\& header when choosing the address for a reply (Message Menu .CR r (reply) command). .TP .CR s .CR Subject:\& header. Enter a string. .TP .CR t .CR To:\& header. Enter a list of aliases and actual addresses. Aliases are expanded and shown as addresses and user names. .TP .CR u User-defined header. Define your own header entry in the form: .RS .nf .IP .IC header-name :\0 header-string .fi .RE .IP .IC header-name :\& must not contain blanks. You can use this command to create a .CR Sensitivity:\& header entry, as described in the Message Status subsection, or a different header, but only one. See the Header Files subsection for another way to include user-defined header entries. .RE .SS Options Menu The Options Menu is invoked with the Message Menu .CR o command. It displays a list of the options, defined by the .CR configoptions string variable, that you can modify while .CR elm is running. Enter the appropriate letter (in upper- or lowercase) that is followed with a right parenthesis .RC ( ) ) and follow the directions on the screen. The full set of option prompts and the corresponding variables is listed below. The default options are marked with an .BR * . .RS .if n .TP 25 .if t .TP 30 .PD 0 .CR "A)rrow cursor" The .CR arrow string variable. .B * .TP .CR "B)order on copy" The .CR prefix string variable. .TP .CR "C)alendar file" The .CR calendar string variable. .B * .TP .CR "D)isplay mail using" The .CR pager string variable. .B * .TP .CR "E)ditor (primary)" The .CR editor string variable. .B * .TP .CR "F)older directory" The .CR maildir string variable. .B * .TP .CR "H)old sent message" The .CR copy boolean variable. .TP .CR "J) reply editor" The .CR alteditor string variable. .TP .CR "K) pause after pager" The .CR promptafter boolean variable. .TP .CR "A(l)ias Sorting" The .CR aliassortby string variable. .TP .CR "M)enu display" The .CR menu boolean variable. .B * .TP .CR "N)ames only" The .CR names boolean variable. .B * .TP .CR "O)utbound mail saved" The .CR sentmail string variable. .B * .TP .CR "P)rint mail using" The .CR print string variable. .B * .TP .CR "R)eply copies msg" The .CR autocopy boolean variable. .TP .CR "S)orting criteria" The .CR sortby string variable. .B * .TP .CR "T)ext editor (~e)" The .CR easyeditor string variable. .TP .CR "U)ser level" The .CR userlevel numeric variable. .B * .TP .CR "V)isual Editor (~v)" The .CR visualeditor string variable. .B * .TP .CR "W)ant Cc: prompt" The .CR askcc boolean variable. .TP .CR "Y)our full name" The .CR fullname string variable. .B * .TP .CR "Z) signature dashes" The .CR sigdashes boolean variable. .PD .RE .PP .B Note: The menu displays the first .IC screen-height -6 lines from the defined set. .IR screen-lines is the number of text lines on the screen. If an option is not displayed, it cannot be modified. .PP When you are done, enter one of the following values: .RS .TP .CR > Save the current configuration values in your configuration file, .CR $HOME/.elm/elmrc . If the file does not exist, it is created. This is a convenient way to make an configuration file that you can edit directly, as well as with the Options Menu. .TP .CR i , I Return to the Message Menu. .TP .CR q , Q Return to the Message Menu. .TP .CR x , X Exit immediately from .CR elm without changing the mailbox. All pending changes are abandoned. .RE .SS Send Menu The Send Menu is invoked when your outbound message has been prepared to be mailed after a Message Menu .CR f , .CR g , .CR m , or .CR r command or the Alias Menu .CR m command. .PP The commands are: .RS .TP 15 .CI ! command Shell. Execute a shell command. See the Message Menu .CR !\& (shell) command. .TP .CR a Attachments. Invoke the Attachments Send Menu. .TP .CR c Copy. Copy to a file. See the Message Menu .CR C (copy) command. .TP .CR e Edit. Invoke your editor, as defined by the .CR alteditor string variable, to revise the message. .TP .CR f Forget. Do not send the message. At user levels .CR 1 and .CR 2 , the message may be returned to the send buffer when you execute a subsequent Message Menu .CR f , .CR g , .CR m , or .CR r command or the Alias Menu .CR m command. .TP .CR h Edit the header entries. Invoke the Header Menu. .TP .CR m Make form. Convert the message to the forms message format. See the FORMS MESSAGES section. This command is only available if the .CR forms boolean variable is .CR ON and the .CR userlevel numeric variable is either .CR 1 or .CR 2 . .TP .CR s Send. Send the message. .RE .SH FORMS MESSAGES A feature that is unique to .CR elm is the ability to compose and reply to forms messages. .SS "Creating a Forms Message" .PP .RS 2 .TP 3 \(bu In your .CR elmrc file, set .CR forms=ON . .TP \(bu Set your .CR userlevel numeric variable to .CR 1 (moderately experienced) or .CR 2 (expert). You can do this in your .CR elmrc file or on the default Options Menu. .TP \(bu As you compose the message, define the fields to be filled in by the recipient with a colon .RC ( : ), followed by either the number of spaces allowed for the field value, or a newline to indicate that the field may fill the remainder of the line. .IP A colon on a line by itself indicates that the recipient will be prompted for multiline input. There can be no blanks before the colon. .IP Every line containing a colon is a prompt line. During the response process, all text starting at the first nonblank character after the last colon on each line is deleted and the line is evaluated for response fields. .TP \(bu After you have created the message, enter the Send Menu .CR m (make form) command to set up the special format. Then enter the Send Menu .CR s (send) command to send the message. .RE .PP .ne 12 Here is an example of a simple forms message: .RS .nf .PP .C "On-Line Phone and Address Database" .C "Please fill out and return as soon as possible." .C "Name:" .C "Manager:" .C "Department: Division:" .C "Your home address:" .C "Home phone number:" .C "Thank you for your cooperation." .fi .RE .SS "Replying to a Forms Message" When you receive a forms message, the message index entry is flagged with an .CR F status letter. You can view it in the normal way with the .B Return or .CR h commands. .PP To reply, use the Message Menu .CR r (reply) command (you cannot use the Message Menu .CR g (group reply) command). .CR elm prompts you for each field, with any text present between the fields displayed as appropriate. The example above is presented line-by-line; user input is in italic type: .RS .nf .PP .CI "On-Line Phone and Address Database" .CI "Please fill out and return as soon as possible." .CI "Name:" "my name" .CI "Manager:" "my manager" .CI "Department:" "my department" .CI "Division:" "my division" .CI "Your home address:" "home address" .CI "Home phone number:" "phone number" .CI "Thank you for your cooperation." .fi .RE .PP The received message would look like this: .RS .nf .PP .C "On-Line Phone and Address Database" .C "Please fill out and return as soon as possible." .C "Name: my name" .C "Manager: my manager" .C "Department: my department Division: my division" .C "" .C "Your home address: home address" .C "Home phone number: phone number" .C "Thank you for your cooperation." .fi .RE .SH HEADER FILE The .CR $HOME/.elm/elmheaders file provides you with a way to specify special information headers such as .CR Organization:\& , .CR Phone:\& , and so forth. The nonblank lines from this file are added to the headers of all outbound mail. .PP Entries in the .CR elmheaders file should have the following format: .IP .IC header-name :\0 header-string .PP .IC header-name :\& must not contain blanks. .IR header-string can be continued over several lines by preceding each continuation line with blanks, as indicated by the output below. .PP Within the .CR elmheaders file, you can use backquotes (left apostrophes) to execute shell commands when the file is read, so that an entry of the form: .IP .C "Operating-System: `uname \-a`" .PP would produce a header entry like: .RS .nf .PP .C "Operating-System:" .C " HP-UX hpulpc17 B.10.10 A 9000/710 2012505939 two-user license" .fi .RE .PP According to RFC 822, user-defined header names should begin with .CR X- or .CR x- . Otherwise, they risk having their usage overridden if the name is later standardized with some other meaning. .SS Defined Headers The following header names are defined for the message header in RFC 822 and RFC 1521. .RS .if n .TP 30 .if t .TP 40 .PD 0 .CR Bcc: " (822)" .CR Cc: " (822)" .TP .CR Comments: " (822)" .CR Content-Description: " (1521)" .TP .CR Content-ID: " (1521)" .CR Content-Transfer-Encoding: " (1521)" .TP .CR Content-Type: " (1521)" .CR Date: " (822)" .TP .CR Encrypted: " (822)" .CR From: " (822)" .TP .CR In-Reply-To: " (822)" .CR Keywords: " (822)" .TP .CR MIME-Version: " (1521)" .CR Message-ID: " (822)" .TP .CR Received: " (822)" .CR References: " (822)" .TP .CR Reply-To: " (822)" .CR Resent-Bcc: " (822)" .TP .CR Resent-Cc: " (822)" .CR Resent-Date: " (822)" .TP .CR Resent-From: " (822)" .CR Resent-Message-ID: " (822)" .TP .CR Resent-Reply-To: " (822)" .CR Resent-Sender: " (822)" .TP .CR Resent-To: " (822)" .CR Return-Path: " (822)" .TP .CR Sender: " (822)" .CR Subject: " (822)" .TP .CR To: " (822)" .CR X- \f2user-defined\fP : " (822)" .PD .RE .PP Other commonly used headers: .RS .if n .TP 30 .if t .TP 40 .PD 0 .CR Action:\& .CR Apparently-To:\& .TP .CR Content-Disposition:\& .CR Content-Length:\& .TP .CR Expires:\& .CR Mailer:\& .TP .CR Newsgroups:\& .CR Precedence:\& .TP .CR Priority:\& .CR Sensitivity:\& .TP .CR Status:\& .CR X-Mailer:\& .PD .RE .SH ELM CONFIGURATION .CR elm supports user configuration by means of the .CR $HOME/.elm/elmrc configuration file. You can create the configuration file with the Options Menu .CR > command. It can contain any combination of the string, numeric, and boolean variables described below. .SS String Variables String variables have the form .IP .IC string-name \0=\0 string-value .PP The following string variables are defined. .RS .TP 25 .CR aliassortby The sort order for the alias index in the Alias Menu. The recognized values are: .RS .TP 10 .PD 0 .CR alias Sort by alias name. .TP .CR name Sort by the full name of the alias, last name first. .TP .CR text Sort by the order of the aliases in the alias text file. .PD .RE .IP Prefix the value with .CR reverse- to reverse the sort order. The default is .CR name . .TP .CR alteditor The name of the editor to use for messages that have initial text (a copied message in a reply, a signature in any outbound message, etc.). when the .CR editor string variable is set to .CR none or .CR builtin . The default is the value of the .CR EDITOR environment variable, if set and nonnull, or .CR /usr/bin/vi otherwise. See also the .CR editor string variable. .TP .CR alternatives A list of other machine and user name combinations that you receive forwarded mail from. .CR elm uses this information when a group reply is being processed to ensure that a reply message is not sent to a user and/or machine address that would simply forward the reply message back to you. The default is none. .TP .CR attribution Attribution string for replies. When you reply to a message and include the message in the reply, this string is placed at the top of the message. The characters .CR %s are replaced by the full name of the author of the original message. The default is none. .IP For example: .CR "attribution = %s wrote:" . .TP .CR calendar The name of your calendar file. This is used in conjunction with the Message Menu .CR < (calendar) command, which scans messages for calendar entries. The default is .CR $HOME//calendar . .TP .CR charset The name of the character set used with the MIME .CR Content-Type:\& header for the .CR text/plain type. It can be any Internet-defined character set name that is a superset of .CR US-ASCII . The default is .CR US-ASCII . For example, .IP .C "Content-Type: text/plain; charset=US-ASCII" .TP .CR compatcharsets A list of Internet-defined character sets that are supersets of US-ASCII, so that messages with .CR charset=US-ASCII can be displayed without the help of .CR metamail . The default is a string containing the following values: .RS .nf .IP .CR Extended_UNIX_Code_Packed_Format_for_Japanese .CR ISO-2022-JP .CR ISO-8859-1 .CR ISO-8859-2 .CR ISO-8859-3 .CR ISO-8859-4 .CR ISO-8859-5 .CR ISO-8859-7 .CR ISO-8859-8 .CR ISO-8859-9 .CR KOI8-R .CR Shift_JIS .fi .RE .TP .CR configoptions A string of options that can be configured on the Options Menu. Specify the options as a single letter each, in the order they should be displayed. The default is "\c .CR "^_cdefsopyv_am_un\c" ". The defaults are marked below with an .BR * . .IP The option characters include: .RS .TP .PD 0 .CR ^ The menu title. .TP .CR _ A blank line. .TP .CR a The .CR arrow string variable. .B * .TP .CR b The .CR prefix string variable. .TP .CR c The .CR calendar string variable. .B * .TP .CR d The .CR pager string variable. .B * .TP .CR e The .CR editor string variable. .B * .TP .CR f The .CR maildir string variable. .B * .TP .CR h The .CR copy boolean variable. .TP .CR j The .CR alteditor string variable. .TP .CR k The .CR promptafter boolean variable. .TP .CR l The .CR aliassortby string variable. .TP .CR m The .CR menu boolean variable. .B * .TP .CR n The .CR names boolean variable. .B * .TP .CR o The .CR sentmail string variable. .B * .TP .CR p The .CR print string variable. .B * .TP .CR r The .CR autocopy boolean variable. .TP .CR s The .CR sortby string variable. .B * .TP .CR t The .CR easyeditor string variable. .TP .CR u The .CR userlevel numeric variable. .B * .TP .CR v The .CR visualeditor string variable. .B * .TP .CR w The .CR askcc boolean variable. .TP .CR y The .CR fullname string variable. .B * .TP .CR z The .CR sigdashes boolean variable. .PD .RE .TP .CR displaycharset The name of the character set supported by the display. This is independent of the .CR charset string variable. This is also copied to the .CR MM_CHARSET environment variable when .CR metamail is called. The default is .CR US-ASCII . .TP .CR easyeditor The name of the editor for the .CR ~e command of the built-in editor. See also the .CR editor string variable. The default is none. .TP .CR editor The name of the editor to use when creating new mail. The default is the value of the .CR EDITOR environment variable, if set and nonnull, or .CR /usr/bin/vi otherwise. .IP You can use .CR none or .CR builtin to specify the built-in editor. The built-in editor is available for all outbound mail that does not already have text in the send buffer (no forwarded message, no copied message in a reply, no signature in any outbound message, etc.). If there is text in the send buffer and .CR builtin is specified, the editor defined by the .CR alteditor variable is used instead. .IP See also the .CR alteditor , .CR easyeditor , and .CR visualeditor string variables. .TP .CR escape The escape character used in the built-in editor. The default is tilde .RC ( ~ ). .TP .CR fullname The name the mailer will use when sending mail from you. The default is the full name portion (everything up to the first comma) of the .CR pw_gecos field from your entry in the .CR /etc/passwd file. This field can be set with the .CR chfn command (see .IR chfn (1), .IR finger (1), and .IR passwd (4)). .TP .CR localsignature A signature file that is automatically appended to outbound mail to the local host before the editor is invoked. This usually contains personal data about the sender. See also the .CR remotesignature string variable. The default is none. .IP All the addresses in the .CR To:\& header must be apparently for the local host. Local addresses are those that, after any .CR elm alias conversion, do not contain a domain name. That is, they have only a user name (for example, .CR santaclaus ) or a user name and the local host name (for example, .CR santaclaus@northpole ). .IP .CR santaclaus@northpole.arcticsea.org is considered to be a remote address, even if it points to the local host. A user name that is readdressed by the .CR sendmail system alias list is treated as local if it matches the preceding criteria. .\"X .TP .\"X .CR mailbox .\"X This is where to put incoming mail after you've read it. .\"X When you answer .\"X .CR no .\"X .RC ( n ) .\"X to the .\"X .C "keep messages in incoming mailbox?" .\"X prompt, this is where the messages go. .\"X The default is .\"X .CR $HOME/mbox . .TP .CR maildir Your mail directory, where you usually store your folders for received and outbound mail. The default is .CR $HOME//Mail . .IP In .CR elm , you can use the .CR = metacharacter to specify this directory. For example, if you save a message to file .CR =/archive , the .CR = is expanded to the current value of .CR maildir . (The slash .RC ( / ) is optional.) .IP When you start .CR elm , if the directory specified by .CR maildir does not exist, you are asked if you want to create it. If you answer .CR y (yes), the directory is created, with access permissions set to .CR 700 . .TP .CR pager The program to display each message. The default is the value of the .CR PAGER environment variable, if set and nonnull, or the built-in pager, .CR builtin+ , otherwise. .IP The built-in pager, .CR builtin+ , also allows you to execute some Message Menu commands while you are viewing the message and it has some simple forward and backward scrolling commands. While it is active, enter .CR ?\& for a list of commands. An alternative is the .CR more utility. .TP .CR precedences A list of precedence values that you can place in a .CR Precedence:\& header entry in outbound mail, using the Header Menu. Each precedence value can be optionally paired with a priority value that is automatically placed in a .CR Priority:\& header entry, causing the received message to be marked as urgent. The default is none. .IP The HP-UX mail transport agent, .CR sendmail , recognizes this header. If the precedence value is defined by a .CR P control line in the .CR sendmail configuration file, .CR /etc/mail/sendmail.cf , the transmission priority of the message is adjusted accordingly. See .IR sendmail (1M). .IP The format of the entry is .RS .nf .IP .CR precedences\0=\0 \f2precedence\fP[ : \f2priority\fP]\0[\f2precedence\fP[ : \f2priority\fP]\|]\0...\& .fi .RE .IP .I precedence is a precedence name. The default list defined in .CR /etc/mail/sendmail.cf is: .RS .if n .TP 10 .if t .TP 25 .PD 0 .CR first-class Transmission priority 0, the default .TP .CR special-delivery Transmission priority 100 .TP .CR list Transmission priority \(mi30 .TP .CR bulk Transmission priority \(mi60 .TP .CR junk Transmission priority \(mi100 .PD .RE .IP .I priority is an arbitrary string that is placed in a .CR Priority:\& header entry. .TP .CR prefix The prefix for an included line in an outbound message. When you reply to a message or forward a message to another person, you can optionally include the original message. This prefix marks the included line. The default is .CR >_ (the .CR _ is interpreted as a space character). .TP .CR print The command to run when the .CR p (print) command is executed from various menus. There are two possible formats for this string: If the string contains the special variable .CR %s , the variable is replaced by the name of a temporary file that contains the messages, and the command is executed by the shell defined by the .CR shell string variable. If the string does not contain .CR %s , the temporary file name is appended to it, and the command is executed. The default is .RS .IP .C "cat %s | lp" .RE .TP .CR receivedmail The file where the received messages will be saved. The default is .CR =received , the file .CR received in the directory defined by .CR maildir . .TP .CR remotesignature A signature file that is automatically appended to all outbound mail to remote hosts before the editor is invoked. This usually contains personal data about the sender. See also the .CR localsignature string variable. The default is none. .IP If any of the addresses in the .CR To:\& header entry are not local, as described for the .CR localsignature string variable, the remote signature file is attached. .TP .CR savecharset The charset to be used to save a message in a folder. Possible values are .CR JIS , .CR SJIS , and .CR EUC . If a value is not specified, the message will be saved according to the locale of the user (given by the .CR LC_TYPE and/or .CR LANG environmental variables). This option is applicable only for the .CR Japanese locale. The default is none. .\"X .TP .\"X .CR savemail .\"X This is where outbound mail will have a copy silently saved. .\"X This will only be used if the .\"X .CR copy .\"X boolean variable is turned on. .\"X Also note that if the .\"X .CR savename .\"X feature is enabled, this filename may be ignored .\"X since the program first looks for a mailbox .\"X that has the same name as the login of the person .\"X you are sending to, using that instead if found. .\"X The default is .\"X .CR $HOME/mbox . .TP .CR sentmail The file where copies of outbound mail can be saved. One possibility is your incoming mailbox, .CI /var/mail/ loginname\f1. The default is .CR =sent , the file .CR sent in the directory defined by .CR maildir . .IP See the .CR copy boolean variable for further details. .TP .CR shell The shell to use for .CR !\& escapes and other such operations. The default is the value of the .CR SHELL environment variable, if set and nonnull, or .CR /usr/bin/ksh otherwise. .\"X .TP .\"X .CR signature .\"X A file to be automatically appended to all outbound mail .\"X before the editor is invoked. .\"X Alternatively, you can specify two signature files with the .\"X .CR localsignature .\"X and .\"X .CR remotesignature .\"X string variables. .\"X .CR elm .\"X will use the .\"X .CR localsignature .\"X file for local mail and the .\"X .CR remotesignature .\"X file for remote mail (mail sent to other hosts). .\"X There is no default. .TP .CR sortby The way to sort the index of the current folder. The choices are: .RS .TP 15 .CR from The name of the sender. .TP .CR sent The date the message was sent. .TP .CR received The date the message was received. .TP .CR subject The subject of the message. A leading .CR Re:\& (and some others) is ignored, so replies sort with original messages. .TP .CR lines The number of lines in the message. .TP .CR status The read status: blank, .CR O , and .CR N . .RE .IP You can prefix these values with .CR reverse- to reverse the order of the sort. The value can be modified on the Options Menu. The default is .CR reverse-sent . .TP .CR textencoding Type of encoding to put into the MIME .CR Content-Transfer-Encoding:\& header entry. The choices are .CR 7bit or .CR 8bit . The default is .CR 7bit . .TP .CR tmpdir Where to create temporary files. The default is the value of the .CR TMPDIR environment variable, if set and nonnull, or to .CR /tmp/ otherwise. .TP .CR visualeditor Name of the editor to use for the .CR ~v command of the built-in editor. The default is the value of the .CR VISUAL environment variable, if set and nonnull, or .CR /usr/bin/vi otherwise. .TP .CR weedout A list of header-entry initial strings that you don't want to see when you are reading mail. This list is made effective by setting the .CR weed boolean variable to .CR ON . .IP The list can continue for as many lines as desired, as long as the continued lines all have leading blanks. To include blanks in a string, enclose it in quotation marks (\c .C """\c" ). The strings you specify are normally appended to the default list, which is: .RS .nf .IP .CR >From .CR Apparently-To:\& .CR Content-Length .CR Content-Transfer-Encoding .CR Content-Type:\& .CR From .CR In-Reply-To:\& .CR MIME-Version .CR Mailer:\& .CR Message-Id:\& .CR Newsgroups:\& .CR Received:\& .CR References:\& .CR Status:\& .CR X-Mailer:\& .fi .RE .IP There are two special values: .RS .TP .CR *clear-weed-list* Clear the default list. The default headers are removed from the .CR weedout list, allowing you to completely define your own list. .TP .CR *end-of-user-headers* Mark the end of the .CR weedout list, in case any following lines could be mistaken for headers in the list. .RE .IP The default value of .CR weedout is .CR *end-of-user-headers* . .IP The underscore .RC ( _ ) character can be used to specify a space. .IP Note that .CR From weeds out both .CR From and .CR From:\& . If, for example, you want to weed out .CR From but not .CR From:\& , specify .CR *clear-weed-list* followed by .CR From_ and any other headers that you don't want to see. .RE .SS Numeric Variables Numeric variables have the form .IP .IC numeric-name \0=\0 numeric-value .PP The following numeric variables are defined. .RS .TP 25 .CR bounceback Threshold for returning copies of remote UUCP messages. If the destination host is greater than the specified number of hops (gateways) from your local host, the destination host sends you a copy of the message when it is received. If the value is .CR 0 , this feature is disabled. The default is .CR 0 . .TP .CR builtinlines Determines if the built-in pager should be used on some messages, even if you usually use an external pager, defined in the .CR pager string variable. There are two ways of defining whether the built-in pager should be used. .RS .TP 3 \(bu If you want to use the built-in pager on any message that is shorter than .IR n lines, set the value to .IR n . .TP \(bu If you want to use the built-in pager on any message that is .IR m lines shorter than the number of lines on your screen, set the value to .CI \- m\f1. .RE .IP If you set the value to .CR 0 , the message will always be sent through the external pager. The default is .CR \-3 . .TP .CR noencoding This enables you to send raw 8-bit or binary data when the mail transfer agent doesn't support the .CR 8BITMIME and the .CR \-B8BITMIME options. The default is .CR 0 . .RS .PP The possible values are: .RS .TP .CR 0 Always convert 8-bit and binary messages to 7-bit before sending them. .TP .CR 1 Convert 8-bit messages to 7-bit, but depend on .CR sendmail to handle binary messages. .TP .CR 2 Depend on .CR sendmail to handle both 8-bit and binary messages. .RE .RE .TP .CR readmsginc The value by which the .CI "Reading\ in\ \&" folder ",\ message:\&" counter is incremented while reading a new folder. If you set this value to a number larger than one, it will speed up the time it takes to read a large folder when you are using a slow terminal. The default is .CR 1 . .TP .CR sleepmsg The time in seconds that .CR elm will wait after displaying a diagnostic message before erasing it. The value can be .CR 0 or a positive integer. The default is .CR 2 . .TP .CR timeout The interval, in seconds, after which .CR elm rechecks the incoming mailbox for new mail. The default is .CR 600 (10 minutes). .TP .CR userlevel The relative level of your user sophistication. Acceptable values are: .RS .TP .CR 0 Novice user (the default). Command menus are a small verbose subset of the available commands. .TP .CR 1 Moderately experienced user. Command menus are a larger terse subset of the available commands. Outbound message commands allow you to recover previously unsent messages as the text of the current outbound message. .TP .CR 2 Expert. The features are the same as for .CR 1 . .RE .IP Level .CR 1 or .CR 2 is required if you want to send a forms message. .RE .SS Boolean Variables Boolean variables have the forms .RS .nf .PP .IC boolean-name =ON .IC boolean-name =OFF .fi .RE .PP The following boolean variables are defined. .RS .TP 25 .CR alwaysdelete If .CR ON , the default answer of the Message Menu .CR q (quit) prompt .RS .IP .C "Delete messages? (y/n)" .RE .IP is set to .CR y (yes). If .CR OFF , the default answer is set to .CR n (no). The default is .CR OFF . See the Message Menu .CR q command. .TP .CR alwayskeep If .CR ON , the default answer of the Message Menu .CR q (quit) prompt .RS .IP .CR "Keep unread messages in incoming mailbox? (y/n)" .RE .IP is set to .CR y (yes). If .CR OFF , the default answer is set to .CR n (no). The default is .CR ON . See the Message Menu .CR q command. .TP .CR alwaysstore If .CR ON , the default answer of the Message Menu .CR q (quit) prompt .RS .IP .C "Move read messages to ""received"" folder? (y/n)" .RE .IP is set to .CR y (yes). If .CR OFF , the default answer is set to .CR n (no). The default is .CR OFF . See the Message Menu .CR q command. .TP .CR arrow If .CR ON , use an arrow .RC ( \-> ) to mark the current item in a menu index. If .CR OFF , use an inverse bar. If the program is invoked with the .CR \-a command line option, .CR arrow is set to .CR ON . The default is .CR OFF . .TP .CR ask If .CR ON , you are asked the questions .RS .nf .IP .C "Delete messages? (y/n)" .C "Move read messages to ""received"" folder? (y/n)" .C "Keep unread messages in incoming mailbox? (y/n)" .fi .RE .IP (as appropriate) each time you leave the program with the Message Menu .CR q (quit) command. See that command for details of the process. If .CR OFF , or if you use the Message Menu .CR Q command, .CR elm uses the values defined by the .CR alwaysdelete , .CR alwaysstore , and .CR alwayskeep boolean variables, respectively, without prompting. The default is .CR ON . .\"X .TP .\"X .CR askbcc .\"X If turned on, the prompt .\"X .CR Blind-Copies-To:\& .\"X appears for each message. .\"X If .\"X .CR askbcc .\"X is .\"X .CR OFF , .\"X you can add a "bcc" list by .\"X .CR ~b .\"X in the built-in editor or by using the header editor. .\"X The default is .\"X .CR OFF . .TP .CR askcc If .CR ON , .CR elm prompts you for "carbon copies" with the prompt .CR "Copies To:\&" each time you send, forward, or reply to a message. If .CR OFF , the prompt is omitted. In either case, you can still explicitly include .CR Cc:\& addresses with the .CR ~c command in the built-in editor, or with the Header Menu commands. The default is .CR ON . .TP .CR autocopy If .CR ON , .CR elm automatically copies the text of the message you are replying to into the edit buffer. If .CR OFF , .CR elm prompts you with .CR "Copy message?" . The default is .CR OFF . .TP .CR confirmappend If .CR ON , you are asked to confirm before messages are appended to an existing file, whether it is a file in your mail directory or a file in another directory. If .CR OFF , see .CR confirmappend " and \&" confirmfiles " Operation" below. The default is .CR OFF . .TP .CR confirmcreate If .CR ON , you are asked to confirm before a new file is created. whether it is a file in your mail directory or a file in another directory. If .CR OFF , see .CR confirmcreate " and \&" confirmfolders " Operation" below. The default is .CR OFF . .TP .CR confirmfiles If .CR ON , you are asked to confirm before messages are appended to an existing file that is not in your mail directory. This does not affect files in your mail directory. If .CR OFF , see .CR confirmappend " and \&" confirmfiles " Operation" below. The default is .CR OFF . .TP .CR confirmfolders If .CR ON , you are asked to confirm before a new file is created in your mail directory. This does not affect files in other directories. If .CR OFF , see .CR confirmcreate " and \&" confirmfolders " Operation" below. The default is .CR OFF . .TP .CR confirmcreate " and \&" confirmfolders " Operation" .RS .TP 15 .CR confirmcreate=ON " and \&" confirmfolders=ON Confirm before creating a file in your mail directory. Confirm before creating a file another directory. .TP .CR ON " and \&" OFF Confirm before creating a file in your mail directory. Confirm before creating a file another directory. .TP .CR OFF " and \&" ON Confirm before creating a file in your mail directory. Do not confirm before creating a file another directory. .TP .CR OFF " and \&" OFF Do not confirm before creating a file in your mail directory. Do not confirm before creating a file another directory. .RE .TP .CR confirmappend " and \&" confirmfiles " Operation" .RS .TP 15 .CR confirmappend=ON " and \&" confirmfiles=ON Confirm before appending to a file in your mail directory. Confirm before appending to a file in another directory. .TP .CR ON " and \&" OFF Confirm before appending to a file in your mail directory. Confirm before appending to a file in another directory. .TP .CR OFF " and \&" ON Confirm before appending to a file in your mail directory. Do not confirm before appending to a file in another directory. .TP .CR OFF " and \&" OFF Do not confirm before appending to a file in your mail directory. Do not confirm before appending to a file in another directory. .RE .TP .CR copy If .CR ON , save silent copies of all outbound mail on the outbound step. If .CR OFF , do not save copies. The default is .CR OFF . .IP If .CR ON , and the .CR savename boolean variable is .CR ON , .CR elm first tries to save it to a file named as defined by .CR savename . If the file exists, the message is saved. If the file does not exist, but the .CR forcename boolean variable is .CR ON , the file is created and the message is saved. If .CR forcename=OFF , the message is saved to the file defined by the .CR sentmail string variable. If .CR savename=OFF , the message is saved to the file defined by the .CR sentmail string variable. .\"X .TP .\"X .CR expand .\"X If this flag is on, tabs in your message written are expanded to spaces. .\"X This ensures that your message is displayed in its original layout .\"X when displayed on a terminal screen having different tab settings. .\"X This flag can be changed without leaving .\"X .CR elm .\"X by changing the .\"X .CR T)abs-to-spaces .\"X field in the Option Menu. .\"X The default is .\"X .CR OFF . .TP .CR forcename If .CR ON , create the folder when saving outbound messages by the login name of the recipient, even if the folder doesn't already exist. If .CR OFF , do not create the folder. The default is .CR OFF . .IP See the .CR copy boolean variable for further details. .TP .CR forms If .CR ON , and the .CR userlevel numeric variable is .CR 1 or .CR 2 , you can create a forms message. The Send Menu .CR m (make form) command converts your message into a forms message. If .CR OFF , you cannot. The default is .CR ON . .TP .CR jisconversion If .CR ON , convert outbound mail to JIS (Japanese Industrial Standard) before sending it. If .CR OFF , do not convert it. This option is applicable only to the Japanese locales, .CR ja_JP.SJIS and .CR ja_JP.eucJP . The default is .CR OFF . .\"X .TP .\"X .CR keep .\"X By default, the mail system deletes mailboxes .\"X when you have removed everything from them. .\"X With this option .\"X .CR ON , .\"X it instead preserves them as zero-length files. .\"X The default is .\"X .CR OFF . .TP .CR keepempty If .CR ON , keep folders from which all the messages are deleted. If .CR OFF , delete empty folders. The default is .CR OFF . .TP .CR keypad If .CR ON , enable the HP 2622 terminal cursor keys. If .CR OFF , disable the cursor keys. If the program is invoked with the .CR \-K command line option, .CR keypad is set to .CR OFF . See also the .CR softkeys boolean variable. The default is .CR ON . .TP .CR menu If .CR OFF , this inhibits the menu display on all program screen displays. If .CR ON , the menus are displayed. If the program is invoked with the .CR \-m command line option, .CR menu is set to .CR OFF . The default is .CR ON . .TP .CR metoo If .CR ON , you are sent a copy of the message that you send to an alias that includes your name also. If .CR OFF , the copy is not sent. The default is .CR OFF . .TP .CR mimeforward If .CR ON , a forwarded message is sent as an attachment. If .CR OFF , a forwarded message is sent as part of the main message. The default is .CR ON . .TP .CR movepage If .CR ON , commands that move through the mailbox by pages (the .CR + and .CR \- commands) also move the current index pointer to the top of the new page of messages. If .CR OFF , moving through the pages does not alter the current message pointer location. The default is .CR ON . .TP .CR names If .CR ON , show only the user names when expanding the .CR To:\& aliases for an outbound message. If OFF , show the entire expanded addresses. The default is .CR ON . .TP .CR nohdrencoding If .CR ON , don't do RFC 1522 encoding for header values that contain 8-bit or multibyte characters. If .CR OFF , do the encoding. The default is .CR OFF . .TP .CR noheader If .CR ON , do not include the headers of messages when copying a message into a file buffer for replying to or forwarding. If .CR OFF , copy all headers. The default is .CR ON . .TP .CR noheaderfwd If .CR ON , do not include headers when copying a message into a file buffer for forwarding. If .CR OFF , copy all headers. For forwarding, this option overrides the setting of .CR noheader . The default is .CR OFF . .TP .CR pagemultipart If .CR ON , use the value of the .CR "pager" variable to display MIME multipart messages with unknown subparts or with unknown subtypes. If .CR OFF , call .CR metamail to view multipart messages. The default is .CR OFF . .TP .CR pointnew If .CR ON , automatically point to the first new message in your message index at start-up. If .CR OFF , point to the first message. In either case, if the start-up folder is not your incoming mailbox, or if there are no new messages, point to the first message. The default is .CR ON . .TP .CR promptafter If .CR ON , prompt for a command after the external pager exits. If .CR OFF , return to the calling menu. The default is .CR ON . .TP .CR resolve If .CR ON , move the pointer to the next message in the index, after deleting, undeleting, saving, or forwarding a message. If .CR OFF , keep the pointer at the current message. The default is .CR ON . .TP .CR savename If .CR ON , and you are saving a message, .CR elm constructs a suggested file name in your .CR maildir directory from the user name of the person who sent the message, in the form .CI = username\f1. If .CR OFF , no file name is suggested. .IP If .CR ON , and you are sending a message that will be saved, .CR elm constructs a file name based on the user name of the first entry in the .CR To:\& list, in the same form as above. If .CR OFF , no file name is constructed. See the .CR copy boolean variable for further details. .IP The default is .CR ON . .IP .TP .CR sigdashes If .CR ON , insert two dashes above the signature text, included from a local or remote signature file. This is a common convention. If .CR OFF , omit the dashes. The default is .CR ON . .TP .CR softkeys If .CR ON , enable the HP 2622 terminal function-key protocol. If .CR OFF , disable the function-key protocol. If the program is invoked with the .CR \-k or .CR \-K command line option, .CR softkeys is set to .CR OFF . See also the .CR keypad boolean variable. The default is .CR OFF . .TP .CR titles If .CR ON , title a displayed message with a line in the form: .RS .nf .IP .CI Message \0number / total\0sendername " " date\0time .fi .RE .IP .IR sendername , .IR date , and .IR time are extracted from the message headers in the manner described in Message Index. This is useful if you have suppressed the relevant header entries with the .CR weedout list. If .CR OFF , the message is not titled. The default is .CR ON . .TP .CR usetite If .CR ON , use the .CR termcap .CR ti / te and .CR terminfo .CR cup cursor-positioning entries (see .IR terminfo (4)). If .CR OFF , do not use those entries. If the program is invoked with the .CR \-t command line option, .CR usetite is set to .CR OFF . The default is .CR ON . .TP .CR weed If .CR ON , do not display the headers defined by .CR weedout variable when displaying a message for reading. If .CR OFF, display all headers. The default is .CR ON . .RE .SH METAMAIL CONFIGURATION .CR elm provides built-in support for the following Content-Types: .RS .TP .CR text/plain \0[ ;\0charset= \f2charset\fP] The text is all in the displayable character set .IR charset which defaults to .CR US-ASCII . .TP .CI multipart/mixed\0;\0boundary= boundary-string The message is composed of a number of individual "body parts", separated by .CI \-\- boundary-string\f1, each having optional headers defining Content-Type and Content-Transfer-Encoding. .TP .CI multipart/digest\0;\0boundary= boundary-string .TP .CI multipart/report\0;\0boundary= boundary-string .TP .CR message/rfc822 The message consists of another message in standard message format. .RE .PP .CR metamail is a system program that is invoked by .CR elm to manage the display of messages and attachments that are not displayable in ordinary ASCII text. .PP .CR metamail provides external support for other Content-Types, as defined in one or more .CR mailcap files. The system .CR mailcap file is .CR /etc/mail/mailcap . You can define your own default .CR mailcap file in .CR $HOME/.mailcap . You can also specify your own list of .CR mailcap files by setting the .CR MAILCAPS environment variable. The .CR mailcap files are searched in order until an entry is found that matches the Content-Type and any qualifications. .PP A minimum .CR mailcap entry consists of a line in the form: .RS .nf .PP .IC content-type \0;\0 command .fi .RE .PP The .I command is the command that you would type to view a file of the indicated Content-Type, with the string .CR %s replaced by a file name. For example, to view body part that was HTML source text and had the Content-Type .CR text/html , you could have the entry .RS .nf .PP .C "text/html; netscape %s" .fi .RE .PP Similarly, for a GIF image file, you could have the entry .RS .nf .PP .C "image/gif; xv %s" .fi .RE .PP RFC 1521 defines a number of Content-Types that .CR elm leaves for .CR metamail to handle: .RS .nf .PP .C text/richtext .C multipart/alternative .C multipart/parallel .C multipart/digest .C message/partial .C message/external-body .C image/jpeg .C image/gif .C audio/basic .C video/mpeg .C application/octet-stream .C application/postscript .fi .RE .PP Check the system .CR mailcap file for entries that handle many of them. .SH EXTERNAL INFLUENCES .SS Environment Variables .TP 15 .CR HOME Your home (login) directory. .TP .CR EDITOR If set and nonnull, provides a default value for the .CR alteditor and .CR editor string variables. .TP .CR LANG If set and nonnull, determines the language in which messages are displayed. The default is .CR C . See .IR environ (5). .\" .TP .\" .CR LC_TYPE .TP .CR MAILCAPS If set, defines the search path for .CR mailcap files used by .CR metamail . The default is .RS .nf .IP .C "$HOME/.mailcap:/etc/mail/mailcap .fi .RE .\" .TP .\" .CR MM_CHARSET .TP .CR PAGER If set and nonnull, provides a default value for the .CR pager string variable. .TP .CR SHELL If set and nonnull, provides a default value for the .CR shell string variable. .TP .CR TMPDIR If set and nonnull, provides a default value for the .CR tmpdir string variable. .TP .CR VISUAL If set and nonnull, provides a default value for the .CR visualeditor string variable. .SS International Code Set Support Single- and multibyte character code sets are supported. .SH EXAMPLES .SS Message Mode Example To send a message without loading the main .CR elm mail-processing program, use the simple command form consisting of the name of the program followed by the recipient's login name and optional address. .CR elm prompts for subject and copies, then starts an editor so you can compose the message (user responses are in italic type): .RS .nf .PP .BI $ "\0elm j_doe" .CI "To: doe (John Doe)" .CI "Subject: " "this is a test" .CI "Copies To: " "..." .I "...invokes editor, you compose message, then..." .CI "Your options now are:" .CI "a)ttachments e)dit message edit h)eader s)end it f)orget it." .CI "" .CI "What is your choice? " "s" .C "mail sent!" .fi .RE .PP If you "forget" the message, it is saved in .CR $HOME/Canceled.mail . .SS File Mode with Redirection To send a file by use of command-line redirection, use a command like: .IP .C "$ elm j_doe < help.c" .PP which reads file .CR help.c and sends it with the default subject. .SS File Mode with a Pipe To mail the output of a command and include a subject line: .IP .C "$ ls -a | elm \-s ""Directory Listing"" j_doe" .SH WARNINGS Using two separate mail programs to access the same mail file simultaneously (usually inadvertently from two separate windows) can cause unpredictable results. .SH AUTHOR .CR elm was developed by Hewlett-Packard Company. .SH FILES .if t .TP 45 .if n .TP 30 .PD 0 .CR $HOME/.elm Directory for the user's .CR elm alias, configuration, header, and other files .TP .CR $HOME/.elm/aliases User alias database data table .TP .CR $HOME/.elm/aliases.dir User alias database directory table .TP .CR $HOME/.elm/aliases.pag User alias database hash table .TP .CR $HOME/.elm/aliases.text User alias source text .TP .CR $HOME/.elm/elmheaders User-defined additional headers .TP .CR $HOME/.elm/elmrc User configuration file .TP .CR $HOME/Canceled.mail Canceled message in noninteractive use. .TP .CI /tmp/alias. pid Temporary file for deleting alias .TP .CI /tmp/form. pid Editor buffer for forms message .TP .CI /tmp/mbox. loginname Temporary mailbox for user .I logname .TP .CI /tmp/print. pid Temporary file for printing message .TP .CI /tmp/snd. pid Outgoing mail message edit buffer .TP .CI /tmp/sndh. pid Outgoing mail header edit buffer .TP .CR /usr/lib/nls/msg/C/elm.cat Location of the message catalog .TP .CR /usr/share/lib/elm/elmrc-info Comment file for .CR $HOME/.elm/elmrc file .TP .CR /var/mail Directory for incoming mail; .br \" OK for SGML conversion it must have mode .CR 755 and group ID .CR mail .TP .CR /var/mail/.elm Directory for .CR elm mailer system aliases .TP .CR /var/mail/.elm/aliases System alias database data table .TP .CR /var/mail/.elm/aliases.dir System alias database directory table .TP .CR /var/mail/.elm/aliases.pag System alias database hash table .TP .CR /var/mail/.elm/aliases.text System alias source text .TP .CI /var/mail/ loginname Incoming mailbox for user; .br \" OK for SGML conversion it must have mode .CR 660 and group ID .CR mail .TP .CI /var/mail/ loginname .lock Lock for mail directory .PD .SH SEE ALSO answer(1), chfn(1), elmalias(1), fastmail(1), finger(1), mailfrom(1), newalias(1), newmail(1), passwd(4), readmail(1), vi(1), sendmail(1M), environ(5). .TP 10 RFC 821 "Simple Mail Transfer Protocol (SMTP)" .TP RFC 822 "Standard for the Format of Internet Text Messages" .TP RFC 1521 "MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies" .TP RFC 1522 "MIME (Multipurpose Internet Mail Extensions) Part Two: Message Header Extensions for Non-ASCII Text" .\" .\" index@\f1alias database@@@\f3elm(1)\f1 .\" index@\f1alias text file@@@\f3elm(1)\f1 .\" index@\f1electronic mail, screen-oriented interface@@@\f3elm(1)\f1 .\" index@\f1mail, screen-oriented interface@@@\f3elm(1)\f1 .\" index@\f1MIME (Multipurpose Internet Mail Extensions)@@@\f3elm(1)\f1 .\" index@\f1Multipurpose Internet Mail Extensions (MIME)@@@\f3elm(1)\f1 .\" index@\f1process mail through screen-oriented interface@@@\f3elm(1)\f1 .\" index@\f1screen-oriented mail interface@@@\f3elm(1)\f1 .\" index@\f1system alias database@@@\f3elm(1)\f1 .\" index@\f1system alias text file@@@\f3elm(1)\f1 .\" index@\f1user alias database@@@\f3elm(1)\f1 .\" index@\f1user alias text file@@@\f3elm(1)\f1 .\" index@\f4elm\f1 \- process electronic mail through a screen-oriented interface@@@\f3elm(1)\f1 .\" .\" toc@\f3elm(1)\f1:\0\0\f4elm\f1@@@process electronic mail through a screen-oriented interface .\" $Header: elmalias.1,v 80.1 96/09/20 17:34:17 ssa Exp $ .TA e .TH elmalias 1 .SH NAME elmalias \- display and verify elm user and system aliases .SH SYNOPSIS .HP .CR elmalias .RC [ \-dersu ] .RC [ \-a \(or \-f .IR format\c .RC \(or \-n \(or \-v\c .RC \(or \-V ] .RI [ alias-name-list ] .SS Remarks The former functionality of the .CR elmalias command has been taken over by the .CR newalias command (see .IR newalias (1)). .SH DESCRIPTION The .CR elmalias command displays and verifies user and system .CR elm aliases. .PP The system database must have been created by the .CR newalias command (see .IR newalias (1)). The user database must have been created by either the .CR newalias command or the .CR elm mail system (see .IR elm (1)). If the same alias is in both databases, the user version is used. Missing database files are silently ignored. .PP Each database entry can have the following fields, which are described in detail in .IR newalias (1): .RS .TP 15 .I alias-list A list of one or more aliases for the entry. .TP .I address-list A list of one or more addresses for the entry. An address can be an alias from another entry's .IR alias-list . .TP .I comment An optional field containing information about the entry. This field is not included in outbound mail. .TP .I firstname An optional field interpreted as the first name of the person or group. It is used in .IR fullname . .TP .I lastname An optional field interpreted as the last name of the person or group. It is used in .IR fullname . .TP .I fullname A combination value made up from the .IR firstname and .IR lastname fields, in the form: .IR "firstname\ lastname" . .RE .PP .CR elmalias recognizes three types of alias names: .RS .TP 15 .CR person A database entry that has one address in .IR address-list . .CR elmalias assumes this address is a valid mailing address. .TP .CR group A database entry that has two or more addresses in .IR address-list . .CR elmalias assumes initially that these addresses are aliases to .CR person or .CR group entries. .TP .CR unknown An address in a .CR group entry or an alias in .IR alias-name-list that is not an alias in the database. In both cases, the item is reported as both the alias name and its address. .RE .PP With no options or operands, .CR elmalias displays the .IR address-list field for each alias in the two databases. If an entry has more than one alias, the .IR address-list field is displayed multiple times. .PP With an .IR alias-name-list and no options, .CR elmalias displays the .IR address-list field of each alias name in the list. If an alias name is not found in the databases, it is treated as .CR unknown , without comment. .SS Options .CR elmalias recognizes the following options: .RS .TP 15 .CR \-a Change the display to alias name followed by .IR address-list field. .TP .CR \-d Turn debugging on. .TP .CR \-e Fully expand .CR group aliases. This option can be used only when an .I alias-name-list is given. .IP If an address in a .CR group address list is an alias name, it is replaced by that alias entry. The process is recursive until the results are either .CR person or .CR unknown types. If a .CR group address is not an alias name, it is reported as both the alias name and the address, with type .CR unknown . Duplicate alias names are reported only once. .CR person entries are not expanded, even if their addresses are actually aliases. .TP .CI \-f \0format Display the .I format string for each alias name in the file or in the .IR alias-name-list . The following character pairs are replaced in the .I format by the corresponding value for each alias. .RS .TP .CR %a The alias name. .TP .CR %c The .IR comment field. .TP .CR %l The .IR lastname field. .TP .CR %n The .IR fullname value. .TP .CR %t The alias type: .CR person , .CR group , or .CR unknown . .TP .CR %v The .IR address-list field. .RE .TP .CR \-n Change the display to .IR address-list followed by .IR fullname , if any, in parentheses. .TP .CR \-r Report an error if a name in .I alias-name-list does not correspond to an alias in the database. Display a message for each unknown name and exit with a nonzero status. .TP .CR \-s Use the system alias database only, unless .CR \-u is also specified. .TP .CR \-u Use the user alias database only, unless .CR \-s is also specified. .TP .CR \-v Use a verbose output format. Change the display to alias name, followed by .IR address-list , followed by .IR fullname , if any, in parentheses. .TP .CR \-V Use a very verbose, multiline output format with the following titles, corresponding to the format codes of the .CR \-f option. If a field is empty, the title is omitted. .RS .nf .PP .C Alias: .C Address: .C Type: .C Name: .C Last Name: .C Comment: .fi .RE .RE .SH EXIT STATUS .CR elmalias sets the following exit status values: .RS .TP .CR \0\00 Normal completion. .TP .CR <>0 An error occurred. You may have specified: .RS .TP 3 .PD 0 \(bu An invalid option. .TP \(bu The .CR \-e option without an .IR alias-name-list . .TP \(bu The .CR \-f option without a .IR format . .TP \(bu The .CR \-r option with an unknown alias name in .IR alias-name-list . .PD .RE .RE .SH EXAMPLES Consider a user database that contains the following entries: .RS .nf .PP .C "# sample alias file" .C "mom = My Mommy, Work: x2468 = my_mother@a.computer" .C "dad,father,pop = Father; Dear, Work: x1357 = host!otherhost!dad" .C "parents = The Folks = mom dad parent@host" .C "siblings = The Kids = brother1" .C " brother2" .C " sister" .C "brother1 = Son; First = bro1@kid.computer" .fi .RE .IP Since .CR brother2 and .CR sister do not refer to alias entries, they are typed as .CR unknown. .PP .CR elmalias with no options or operands produces the following output. .RS .nf .PP .C "my_mother@a.computer" .C "host!otherhost!dad" .C "host!otherhost!dad" .C "host!otherhost!dad" .C "mom,dad,parent@host" .C "brother1,brother2,sister" .C "bro1@kid.computer" .fi .RE .PP .CR elmalias .CR \-v produces the alias names, address, and full name, as follows: .RS .nf .PP .C "mom my_mother@a.computer (My Mommy)" .C "dad host!otherhost!dad (Dear Father)" .C "father host!otherhost!dad (Dear Father)" .C "pop host!otherhost!dad (Dear Father)" .C "parents mom,dad,parent@host (The Folks)" .C "siblings brother1,brother2,sister (The Kids)" .C "brother1 bro1@kid.computer (First Son)" .fi .RE .PP To expand a set of aliases and format them with field titles, use the .CR \-e and .CR \-f options, as in the following command: .RS .nf .PP .C "elmalias -ef ""Alias: %a Address: %v Type: %t"" parents siblings" .fi .RE .PP producing: .RS .nf .PP .C "Alias: mom Address: my_mother@a.computer Type: Person" .C "Alias: dad Address: host!otherhost!dad Type: Person" .C "Alias: parent@host Address: parent@host Type: Unknown" .C "Alias: brother1 Address: bro1@kid.computer Type: Person" .C "Alias: brother2 Address: brother2 Type: Unknown" .C "Alias: sister Address: sister Type: Unknown" .fi .RE .SH AUTHOR .CR elmalias was developed by HP. .SH FILES .if n .TP 30 .if t .TP 40 .PD 0 .CR $HOME/.elm/aliases User alias database data table .TP .CR $HOME/.elm/aliases.dir User alias database directory table .TP .CR $HOME/.elm/aliases.pag User alias database hash table .TP .CR $HOME/.elm/aliases.text User alias source text .TP .CR /var/mail/.elm/aliases System alias database data table .TP .CR /var/mail/.elm/aliases.dir System alias database directory table .TP .CR /var/mail/.elm/aliases.pag System alias database hash table .TP .CR /var/mail/.elm/aliases.text System alias source text .PD .SH SEE ALSO elm(1), newalias(1). .\" .\" index@\f4elmalias\f1 \- display and verify \f4elm\f1 user and system aliases@@@\f3elmalias(1)\f1 .\" index@\f1display \f4elm\f1 user and system aliases@@@\f3elmalias(1)\f1 .\" index@\f1verify \f4elm\f1 user and system aliases@@@\f3elmalias(1)\f1 .\" index@\f4elm\f1 user and system aliases, verify and display@@@\f3elmalias(1)\f1 .\" index@\f1user aliases, \f4elm\f1, verify and display@@@\f3elmalias(1)\f1 .\" index@\f1system aliases, \f4elm\f1, verify and display@@@\f3elmalias(1)\f1 .\" index@\f1aliases, \f4elm\f1 user and system, verify and display@@@\f3elmalias(1)\f1 .\" .\" toc@\f3elmalias(1)\f1:\0\0\f4elmalias\f1@@@display/verify \f4elm\f1 user and system aliases .\" $Header: enable.1,v 72.4 94/10/13 13:42:59 ssa Exp $ .TA e .TH enable 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME enable, disable \- enable/disable LP printers .SH SYNOPSIS .CR enable .I printers .PP .CR disable .RC [ \-c ] .RC [ \-r\c .RI [ reason ]\|] .I printers .SH DESCRIPTION The .CR enable command activates the named .IR printers , enabling them to print requests taken by .CR lp . Use .CR lpstat to find the status of printers (see .IR lp (1) and .IR lpstat (1)). .PP .CR disable deactivates the named .IR printers , disabling them from printing requests taken by .CR lp . By default, any requests that are currently printing on the designated printers are reprinted in their entirety either on the same printer or on another member of the same class. Use .CR lpstat to find the status of printers. .SS Options .CR disable recognizes the following options: .RS .TP 15 .CR \-c Cancel any requests that are currently printing on any of the designated printers. .TP .CR \-r [\f2reason\f1] Associate a .I reason with the deactivation of the printers. This reason applies to all printers mentioned up to the next .CR \-r option. If the .CR \-r option is not present or the .CR \-r option is given without a reason, a default .I reason is used. .I reason is reported by .CR lpstat . The maximum length of the .I reason message is 80 bytes. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to .CR C (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to .CR C (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH EXAMPLES Enable printer .CR snowwhite to accept requests: .IP .C "enable snowwhite" .PP Deactivate printer .CR snowwhite and cancel any logged jobs: .IP .C "disable \-c snowwhite" .SH WARNINGS If the restrict cancel feature (selected by the .CR "lpadmin \-orc" option \(em see .IR lpadmin (1M)) is enabled, .CR disable ignores the .CR \-c option. .PP .CR enable and .CR disable perform their operation on the local system only. .SH FILES .nf .CR /etc/lp/* .CR /usr/lib/lp/* .CR /var/adm/lp/* .CR /var/spool/lp/* .fi .SH SEE ALSO lp(1), lpstat(1), accept(1M), lpadmin(1M), lpsched(1M), rcancel(1M), rlp(1M), rlpdaemon(1M), rlpstat(1M). .\" .\" toc@\f3enable(1)\f1:\0\0\f4enable\f1, \f4disable\f1@@@enable/disable LP printers .\" toc@\f4disable\f1:\0\0disable LP printers@@@see \f3enable(1)\f1 .\" .\" index@\f4enable\f1 \- enable LP printers@@@\f3enable(1)\f1 .\" index@\f4disable\f1 \- disable LP printers@@@\f3enable(1)\f1 .\" index@\f1LP printers, enable/disable@@@\f3enable(1)\f1 .\" index@\f1printers, LP, enable/disable@@@\f3enable(1)\f1 .\" .\" links@enable.1 disable.1 .\" $Header: env.1,v 76.2 95/08/03 17:26:26 ssa Exp $ .TA e .TH env 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME env \- set environment for command execution .SH SYNOPSIS .C env .RC [ - ] .RC [ -i ] .RI [ \|name .C = .IR value\| ]\0... .RI [ \|command .RI [ \|arguments\0...\|]\|] .SH DESCRIPTION .C env obtains the current .IR environment , modifies it according to its arguments, then executes the command with the modified environment. Arguments of the form .IC name = value are merged into the inherited environment before the command is executed. The .C -i option causes the inherited environment to be ignored completely so that the command is executed with exactly the environment specified by the arguments. The .C - option is obsolete and has the same effect as the .C -i option. .PP If no command is specified, the resulting environment is printed, one name-value pair per line. .SH RETURN VALUE If .I command is invoked, the exit status of .C env is the exit status of .IR command ; otherwise, .C env exits with one of the following values: .RS .TP 6 .B 0 .C env completed successfully. .PD 0 .TP .B 1-125 .C env encountered an error. .TP .B 126 .I command was found but could not be invoked. .TP .B 127 .I command could not be found. .PD .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C env behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNING The .C - option is obsolete. Use .C -i instead. .SH SEE ALSO sh(1), exec(2), profile(4), environ(5). .SH STANDARDS CONFORMANCE .CR env ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" toc@\f3env(1)\f1:\0\0\f4env\f1@@@set environment for command execution .\" .\" index@\f4env\f1 \- set environment for command execution@@@\f3env(1)\f1 .\" index@\f1set environment for command execution@@@\f3env(1)\f1 .\" index@\f1environment for command execution, set@@@\f3env(1)\f1 .\" index@\f1command execution, set (modify or redefine) environment for@@@\f3env(1)\f1 .\" index@\f1execution, commands, set environment for@@@\f3env(1)\f1 .\" index@\f1modify environment for command execution@@@\f3env(1)\f1 .\" index@\f1redefine environment for command execution@@@\f3env(1)\f1 .\" .\" $Header: eucset.1,v 76.1 95/07/10 16:58:32 ssa Exp $ .TA e .TH eucset 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME eucset \- sets and gets EUC code widths for ldterm .SH SYNOPSIS .C eucset .RC [ -p ] .PP .CR eucset .RC [\ [ -c .IR HP15-codeset ] .RC \ or .RI [ cswidth ]\ ] .SH DESCRIPTION The .CR eucset command sets or gets (reports) the encoding and display widths of the Extended UNIX Code (EUC) characters processed by the current input terminal. EUC is an encoding method for codesets composed of single or multiple bytes. It permits applications and the terminal hardware to use the 7-bit US ASCII code and up to three single byte or multibyte code sets simultaneously. .PP The .CR eucset command without any options, first tries to set the codeset to one of the four HP15 codesets . If unsuccessful, 7-bit US ASCII is used as the default codeset. This command must be used to specify any other EUC codesets, whether they are single byte or multibyte. See the WARNINGS section, for special warnings on the values of the .I cswidth argument. .SS Options The .CR eucset command recognizes the following options and arguments: .RS .TP 10 .C -p Displays the current settings of the EUC character widths for the terminal. .RE .RS .TP 10 .C -c Sets the codeset to one of the four HP15 codesets. The codesets supported are .CR SJIS, .CR \ CCDC, .CR \ GB, and .CR \ BIG5. .RE .SS EUC Code Set Classes EUC divides codesets into four classes. Each codeset has two characteristics: the number of bytes for encoding the characters in the codeset, and the number of display columns to display the characters in the codeset. All characters within a codeset possess the same characteristics. .RS .TP 3 \(bu Codeset 0 consists of all 7-bit, single byte ASCII characters. The most significant bit of each of these characters is 0 (zero). Characters in codeset 0 require one byte for encoding, and occupy one display column. These values are fixed for codeset 0 (zero). The 7-bit US ASCII code is the primary EUC codeset, which is available to users without direct specification. .ifn .bp .TP \(bu Codeset 1 is a supplementary EUC codeset. Codeset 1 characters have an initial byte whose most significant bit is 1. Characters in codeset 1 may require more than one byte for encoding, and may require more than one display column. The .CR eucset command must be used to set the characteristics for codeset 1. .TP \(bu Codesets 2 and 3 are supplementary EUC codesets. Characters in these codesets have an initial byte of SS2 or SS3, respectively. They require more than one byte for encoding, and may require more than one display column. The .CR eucset command must be used to set the characteristics for codesets 2 and 3. .RE .PP The .I cswidth argument in the .CR eucset command line is a character string that describes the character widths for codesets 1 through 3. This command does not allow the user to modify the settings for codeset 0. The character string is of the following format: .IP .C X1[:Y1],X2[:Y2],X3[:Y3] .PP The value .CR X1 is the number of bytes required to encode a character in codeset class 1. .CR Y1 is the number of display columns needed to display characters in this class. .CR X2 is the number of bytes required to encode a character in codeset 2, not counting the SS2 byte, and .CR Y2 is the number of display columns for codeset 2 characters. .CR X3 is the number of bytes needed to encode characters in codeset 3, not counting the SS3 byte, and .CR Y3 is the number of display columns required for these characters. The values for the column widths may be omitted if they are equal to the number of encoding bytes. If the encoding value of any of the EUC codesets is set to .CR 0 (zero), this indicates that the codeset does not exist. See the WARNINGS section for special warnings on the values of the .I cswidth argument. .PP If no .I cswidth argument is supplied, the .CR eucset command uses the value of the .CR CSWIDTH environment variable. If this variable is not present, the following default string is substituted: .IP .CI 1:1,0:0,0:0 .PP This default string designates that the environment uses a single byte EUC codeset that has characters in the EUC codeset 1 format. If the environment uses a multibyte EUC codeset in the codeset 1 format, single byte or multibyte EUC codesets in the codeset 2 or 3 format, or both, the default setting cannot be used. .SH EXTERNAL INFLUENCES .SS Environment Variables .TP 20 .C LANG Provide a default value for the internationalization variables that are unset or null. If .CR LANG is not specified or is set to the empty string, a default of .CR C (see .IR lang (5)) is used instead of .CR LANG . If any of the internationalization variables contain an invalid setting, .CR eucset behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .TP .C LC_ALL If set to a nonempty string value, override the values of all other internationalization variables. .TP .C LC_MESSAGES Determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .TP .C NLSPATH Determines the location of message catalogs for the processing of .CR LC_MESSAGES . .SH EXAMPLES To display the encoding and display widths for the EUC codesets 1 to 3 in your environment, enter: .IP .C eucset -p .PP Assuming .CR eucset has been previously used to set for .CR ja_JP.eucJP , the entry generates the following: .IP .C cswidth 2:2,1:1,2:2 .PP To change the current settings of the encoding and display widths for the EUC characters in codesets 1 and 2 to two bytes each, enter one of the following: .IP .C eucset 2:2,2:2,0:0 .IP .C eucset 2,2,0 .PP To set the encoding and display widths for the EUC characters in the locale .CR ja_JP.eucJP , enter: .IP .C eucset 2:2,1:1,2:2 .PP For .CR zh_TW.eucTW , enter: .IP .C eucset 2:2,3:2 .PP For .CR ko_KR.eucKR , enter: .IP .C eucset 2:2 .SH WARNINGS The .I cswidth argument does not include the SS2 or SS3 bytes in the byte width values. .PP This command is not specified by standards, may not be available on other vendor's systems, and may be subject to change or obsolescence in a future release. .SH AUTHOR .CR eucset was developed by OSF and HP. .SH SEE ALSO dtterm(1), ldterm(1). .\" toc@\f3eucset(1)\f1:\0\0\f4eucset\f1@@@set and get EUC code widths for ldterm\f1 .\" .\" index@\f4eucset\f1 \- set and get EUC code widths for ldterm@@@\f3eucset(1)\f1 .\" index@\f1ldterm, set and get EUC code widths for@@@\f3eucset(1)\f1 .\" index@\f1EUC, set and get code widths for ldterm@@@\f3eucset(1)\f1 .\" index@\f1code widths, set and get EUC for ldterm@@@\f3eucset(1)\f1 .\" $Header: ex.1,v 78.2 96/05/09 10:48:44 ssa Exp $ .TA e .TH ex 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ex, edit \- extended line-oriented text editor .SH SYNOPSIS .CR ex .RC [ - ] .RC [ -l ] .RC [ -r ] .RC [ -R ] .RC [ -t .IR tag ] .RC [ -v ] .RC [ -V ] .RC [ -w\c .IR size ] .RC [ -x ] .RC [ +\c .IR command ] .ifn .br .ifn \0\0\0\0 .RI [ file \0...] .PP .SS "XPG4 Synopsis" .CR ex .RC [ -rR ] .RC [ "-s " \(or .CR -v ] .\" .CR |\ -v ] .RC [ -c .IR command ] .RC [ -t .IR tag ] .RC [ -w .IR size ] .RI [ file " ...]" .PP .SS "Obsolescent Options" .PP .CR ex .RC [ -rR ] .RC [ - \(or .CR -v ] .\" .CR |\ -v ] .RC [+\c .IR command ] .RC [ -t .IR tag ] .RC [ -w .IR size ] .RI [ file " ...]" .PP .CR edit .RC [ - ] .RC [ -l ] .RC [ -r ] .RC [ -R ] .RC [ -t .IR tag ] .RC [ -v ] .RC [ -V ] .RC [ -w\c .IR size ] .RC [ -x ] .RC [ +\c .IR command ] .ifn .br .ifn \0\0\0\0 .RI [ file \0...] .SS Remarks The program names .CR ex , .CR edit , .CR vi , .CR view , and .CR vedit are separate personalities of the same program. This manual entry describes the behavior of the .CR ex / edit personality. On many HP-UX and other similar systems, .CR e is a synonym for .CR ex . .SH DESCRIPTION The .CR ex program is the line-oriented personality of a text editor that also supports screen-oriented editing (see .IR vi (1)). .PP (XPG4 only.) Certain block-mode terminals do not have all the capabilities necessary to support the complete .C ex definition, such as the full-screen editing commands (\c .CR visual mode or .CR open mode). When these commands cannot be supported on such terminals, this condition shall neither produce an error message such as "not an editor command" nor report a syntax error. .PP The .CR edit program is identical to .CR ex , except that some editor option defaults are altered to make the editor somewhat friendlier for beginning and casual users (see Editor Options below). .SS Options and Arguments .CR ex recognizes the following command-line options and arguments: .ifn .TP 10 .ift .TP 15 .CR - (Obsolescent) Suppress all interactive-user feedback. This is useful when editor commands are taken from scripts. .TP .CR "-s " (XPG4 only.) .IP Suppress all interactive-user feedback. This is useful when editor commands are taken from scripts. .IP Ignore the value of the .C TERM and any implementation terminal type and assume the terminal is a type incapable of supporting visual mode. .IP Suppress the use of the .C EXINIT environment variable and the reading of the .C .exrc file. .TP .CR -l Set the .CR lisp editor option (see Editor Options below). .TP .CR -r Recover the specified .IR file s after an editor or system crash. If no .I file is specified, a list of all saved files is printed. You must be the owner of the saved file in order to recover it (superuser cannot recover files owned by other users). .TP .CR -R Set the .CR readonly editor option to prevent overwriting a file inadvertently (see Editor Options below). .TP .CI -t " tag" (XPG4 only.) Edit the file containing the specified .IR tag and proceed as if the first command were .CR :tag .IR tag . The tags represented by the .C -t .I tag and the .C ta command is optional. It shall be provided on any system that also provides a confirming implementation of .CR ctags , Otherwise, the use of the .C -t produces undefined results. .IP Execute the .CR tag .IR tag command to load and position a predefined file. See the .CR tag command in Command Descriptions and the .CR tags editor option in Editor Options below. .TP .CR -v Invoke visual mode .RC ( vi ). .TP .CR -V Set verbose mode. Editor commands are displayed as they are executed when they are input from an .CR .exrc file or a source file (see the .CR source command in Command Descriptions below). .TP .CI -w " size" Set the value of the .CR window editor option to .IR size (see Editor Options below). If .I size is omitted, it defaults to .CR 3 . .TP .CR -x Set encryption mode. You are prompted for a key to initiate the creation or editing of an encrypted file (see the .CR crypt command in Command Descriptions below). .TP .CI -c " command" (XPG4 only.) .TP .CI + command (Obsolescent) Begin editing by executing the specified .CR ex search or positioning .IR command . .TP .I file Specify the file or files to be edited. If more than one .I file is specified, they are processed in the order given. If the .CR -r option is also specified, the files are read from the recovery area. .PP .RE (XPG4 only.) If both the .CR -t .IR tag and .CR -c .IR command options are given, the .CR -t .IR tag shall be processed first;i.e, the file containing the tag is selected by the .CR -t and then the command is executed. .PP .RE .SS Definitions .BR "Current file" . The name of the file being edited by .CR ex is called the current file. Text from the current file is read into a work area, and all editing changes are performed on this work area. Changes do not affect the original file until the work area is explicitly written back to the file. If the .CR % character is used as a file name, it is replaced by the current file name. .PP .BR "Alternate file" . The alternate file is the name of the last file mentioned in an editor command, or the previous current file name if the last file mentioned becomes the current file. If the .CR # character is used as a file name, it is replaced by the alternate file name. .PP .BR "Buffers" . Twenty-six buffers named .CR a through .CR z can be used for saving blocks of text during the edit. If the buffer name is specified in uppercase, text is appended to the existing buffer contents rather than overwriting it. .PP .BR "Readonly flag" . The .CR readonly flag can be cleared from within the editor by setting the .CR noreadonly editor option (see Editor Options below). Writing to a different file is allowed even when the .CR readonly flag is set. Also, a write can be forced to a .CR readonly file by using .CR !\& after the write command (see the .CR write command in Command Descriptions below). .PP .BR "Interrupt" . If an interrupt signal is received, and commands are being supplied from a keyboard, .CR ex returns to command mode. If editor commands are coming from a file, an interrupt signal causes .CR ex to abort. .PP .BR "System crash" . If the system crashes or .CR ex aborts due to an internal error or unexpected signal, .CR ex attempts to preserve the work area if any unwritten changes were made. Use the .CR -r command-line option to retrieve the saved changes. .PP .BR "Command mode/input mode" . .CR ex starts up in command mode, as indicated by the colon .RC ( : ) prompt. .CR ex switches to input mode whenever an .CR append , .CR change , or .CR insert command is encountered. To terminate input mode and return to command mode, type a period .RC ( . ) alone at the beginning of a line. .PP .BR "Comments" . Command lines beginning with a quotation mark (\c .C """\c" ) are ignored (this is useful for placing comments in an editor script). .PP .BR "Multiple commands" can be combined on a single line by separating them with a vertical bar character .RC ( | ). However, global commands, comments, and the shell escape command must be the last command on a line because they cannot be terminated by a .CR | character. .SS Addressing (XPG4 only.) Addressing in .C ex relates to the current line. In general, the current line shall be the last line affected by the command; the exact effect on the current line is discussed under the description of each command. When the buffer contains no lines, the current line shall be set to zero. .PP .CR ex recognizes the following line address forms: .RS .TP 15 .CR .\& Dot or period .RC ( . ) refers to the current line. There is always a current line whose position can be the result of an explicit movement command or the result of a command that affects multiple lines (in which case it is usually the last line affected). .TP .I n The .IR n th line in the work area. Lines are numbered sequentially, starting at line 1. .TP .CR $ The last line in the work area. .TP .CR % Abbreviation for .CR 1,$ , meaning the entire work area. .TP .PD 0 .CR + \f2n\f1,\0 + [ + ]...\& .TP .CR - \f2n\f1,\0 - [ - ]...\& .ift .sp -2v .PD An offset relative to the current line or the preceding line specification. .CR + means forward; .CR - means backward. For example, the forms .CR .+3 , .CR +3 , and .CR +++ are equivalent. .PD .TP .PD 0 .CI / re / .TP .CI ? re ?\& .sp -2v The line containing the pattern .IR re , scanning forward .RC ( / ) or backward .RC ( ? ). The trailing .CR / or .CR ?\& can be omitted if the line is only being displayed. If .I re is omitted, .CR ex uses the more recently set of either the scanning string or the substitution string (see Regular Expressions below). .PD .TP .CI ' x Lines can be marked using single lowercase letters (see the .CR mark command in Command Descriptions below). .CI ' x refers to the line marked with .IR x . In addition, the previous current line is marked before each nonrelative motion. This line can be referred to by using .CR ' for .I x (thus .CR '' refers to the previous current line). .IP (XPG4 only.) Commands require zero, one or two addresses. Commands that require zero addresses shall regard the presence of an address as an error. .RE .PP (XPG4 only.) Adjacent address in a .C range shall be separated from each other by a comma (,) or a semicolon(;). In the latter case, the current line(.) shall be set to the first address, and only then is the second address calculated. This feature can be ued to determine the starting line for forwards and backwards searches. The second address of any two-address sequence shall correspond to the first address. The first address shall be less than or equal to the second address. The first address shall be greater than or equal to the first line of the editing buffer, and the last address shall be less than or equal to the last line of the editing buffer. Any other case shall be an error. .RE .PP Addresses for commands consist of a series of line addresses (specified as above), separated by a comma .RC ( , ) or semicolon .RC ( ; ). Such address lists are evaluated left-to-right. When the separator is a semicolon, the current line is set to the value of the previous address before the next address is interpreted. If more addresses are given than the command requires, then all but the last one or two are ignored. Where a command requires two addresses, the first line addressed must precede the second one in the work area. A null (missing) address in a list defaults to the current line. .SS Regular Expression The editor maintains copies of two regular expression strings at all times: the substitution string, and the scanning string. The substitute command sets the substitution string to the regular expression used. Both the global-command and the regular-expression form of line addressing (see Addressing above) for all commands set the scanning string to the regular expression used. These strings are used as default regular expressions as described under Addressing, the .CR global command, and the .CR substitute command. .PP The editor supports Basic Regular Expressions (see .IR regexp (5)) with the following modifications: .RS .TP 12 .CR \e< The .CR \e< matches the beginning of a "word"; that is, the matched string must begin in a letter, digit, or underline, and must be preceded by the beginning of the line or a character other than the above. This construct can only be used at the beginning of a regular expression (as in .I \e The .CR \e> matches the end of a "word" (see previous paragraph). This construct can only be used at the end of a regular expression (as in .I word\e>), but not in the middle .I (word1\e> word2). .TP .CR ~ Match the replacement part of the last .CR substitute command. .TP .CI [ string ] The positional quoting within bracket expressions defined by Basic Regular Expressions is replaced by the use of the backslash .RC ( \e ) to quote bracket-expression special characters. .TP .CR nomagic When the editor option .CR nomagic is set, the only characters with special meanings are .CR ^ at the beginning of a pattern, .CR $ at the end of a pattern, and \e. The characters ., *, .CR [ , and .CR ~ lose their special meanings unless escaped by a .CR \e . .RE .SS Replacement Strings The character .CR & in the replacement string stands for the text matched by the pattern to be replaced. Use .CR \e& if the .CR nomagic editor option is set. .PP The character .CR ~ is replaced by the replacement part of the previous .CR substitute command. Use .CR \e~ if the .CR nomagic editor option is set. .PP The sequence .CI \e n\f1, where .I n is an integer, is replaced by the text matched by the subpattern enclosed in the .IR n th set of parentheses .CR \e( and .CR \e) . .PP The sequence .CR \eu (\c .CR \el ) causes the immediately following character in the replacement to be converted to uppercase (lowercase), if the character is a letter. The sequence .CR \eU (\c .CR \eL ) turns case conversion on, until the sequence .CR \eE or .CR \ee is encountered, or the end of the replacement string is reached. .br .ne 24 .SS Command Names and Abbreviations The following table summarizes the line-mode commands. The commands whose names are enclosed in parentheses are available only in their abbreviated forms. .PP .vs +1 .TS center box tab(;); lB lB | lB lB | lB lB lf4p+1 lf4p+1 | lf4p+1 lf4p+1 | lf4p+1 lf4p+1. Command;Abbr.;Command;Abbr.;Command;Abbr. _ abbreviate;ab;next;n;tag;ta append;a;number;nu #;unabbreviate;una args;ar;open;o;undo;u change;c;pop;\&;unmap;unm chdir;chd cd;preserve;pre;version;ve _ copy;co t;print;p;visual;vi crypt;cr X;put;pu;write;w wq delete;d;quit;q;xit;x edit;e ex;read;r;yank;ya file;f;recover;rec; _ global;g v;rewind;rew;\f1\s-1(execute buffer)\s+1;* @ insert;i;set;se;\f1\s-1(line number)\s+1;\&= join;j;shell;sh;\f1\s-1(left shift)\s+1;< list;l;source;so;\f1\s-1(right shift)\s+1;> map;\&;stop;st ^Z;\f1\s-1(scroll)\s+1;^D _ mark;ma k;substitute;s sr & ~;\f1\s-1(shell escape)\s+1;! move;m;suspend;su ^Z;\f1\s-1(window)\s+1;z .TE .vs .SS Command Descriptions In the following command descriptions, some arguments appear frequently. They are described below. .RS .TP 10 .I line A single line address, in any of the forms described in Addressing above. The default is the current line. .TP .I range A pair of line addresses separated by a comma or semicolon, as described in Addressing above. The default is the current line .RC ( .,. ). .TP .I count A positive integer specifying the number of lines to be affected by the command. The default is 1 or the number of lines in .IR range . .IP When .I count is specified, .I range is ineffective. Instead, only a line number should be specified to indicate the first line affected by the command. (If a range is given, the last line of the range is interpreted as the starting line for the command.) .TP .I flags One or more of the characters .CR # , .CR p , and .CR l . The corresponding command to print the line is executed after the command completes. Any number of .CR + or .CR - characters can also be given with these flags. The default is no flags. .RE .PP These modifiers are all optional. .PP When only a .I line or a .I range is specified (with a null command), the implied command is .CR print . If a null line is entered, the next line is printed (equivalent to .CR .+1p ) .TP 18 .IR buffer .BR "XPG4 Feature." One of a number of named areas for saving text. The named buffers are specified by the lowercase letters of the POSIX locale. Specifying .C buffer shall cause the area of the text affected by the command to be stored into the buffer as it was before the command took effect. This argument is also used on the .C put command and the visual mode "put" commands .RC ( p .RC "and " P ), to specify the buffer that shall provide the text to insert. .IP If the buffer name is specified in uppercase, and the buffer is to be modified, the buffer shall be appended to rather than being overwritten. If the buffer is not to be modified, the buffer name can be specified in lowercase or uppercase with the same results. There shall be also one unnamed buffer, which is the repository for all text deleteed or yanked when no buffer is specified. .IP There are also numbered buffers, 1 through 9, which shall be accessible only from visual mode. These buffers are special in that, in the visual mode, when deleted text is placed in the unnamed buffer, it also shall be placed in buffer 1, the previous contents buffer 1 shall be placed in buffer 2 and so on. Any text in the buffer 9 shall be lost. Text that is yanked into the unnamed buffer shall not modify the numbered buffers. Text cannot be placed directly into the numbered buffered, although it can be retrieved from them by using a visual mode "put" command with the buffer name given as s number. When the buffer modifier is not used in the commands below, the unnamed buffer shall be the default. .TP 18 .IR word .BR "XPG4 Feature." In the POSIX Locale, a .CR word consists of a maximal sequence of letters, digits and underscores, delimited at both ends by characters other than letters, digits, or underscores, or by the beginning or end of a word or the file. .CR ! A character that can be appended to the command to modify its operation, as detailed in the individual command descriptions. .IP If both a .CR count and .CR range is specified for a command that uses them, the number of lines affected shall be taken from the .CR count value rather than the .CR range . The starting line for the command shall be taken to be the first line addressed by the range. .IP When only a .CR line or .CR range is specified with no command, the implied command shall be either .CR print , .CR list , or .CR number ( .CR p , .CR l , or .CR # ). The command selected shall be the last of these three commands to be used. When no range or count is specified and the command line is a blank line, the current line shall be written, and the current line shall be set to .CR .+1 . .IP Zero or mode characters can precede or follow the addresses, count or command name. Any object following a command name (such as buffer, file etc) that begins with an alphabetic character shall be separated from the command name with at least one . .PP For each of the commands listed below, the command can be entered as the abbreviation (those characters in the Synopsis command word preceding the [), the full command (all characters shown for the command word, omitting the [ and ]), or any subset of the characters of the full command down to the abbreviation. .TP 18 .CR abbreviate .CR ab [ breviate ] .I word replacement .IP Add the named abbreviation to the current list. In visual mode, if .I word is typed as a complete word during input, it is replaced by the string .IR replacement . .TP .CR append .I line .CR a [ ppend ][ ! ] .IP Enter input mode; the input text is placed after the specified line. If line 0 is specified, the text is placed at the beginning of the work area. The last input line becomes the current line, or the target line if no lines are input. .IP Appending .CR !\& to the command toggles the .CR autoindent editor option setting for this insert only. .TP .CR args .CR ar [ gs ] .IP Prints the argument, placing the current argument between .CR [ and .CR ] . .TP .CR change .I range .CR c [ hange ][ ! ] .I count .IP Enter input mode; the input text replaces the specified lines. The last input line becomes the current line; if no lines are input, the effect is the same as a delete. .IP Appending .CR !\& to the command toggles the .CR autoindent editor option setting for this insert only. .TP .CR chdir .CR chd [ ir ][ ! ]\0[\c .IR directory ] .br .CR cd [ ! ]\0[\c .IR directory ] .IP Change the working directory to .IR directory . If .I directory is omitted, the value of the .CR HOME environment variable is used. If the work area has been modified since the last write and the name of the file being edited does not begin with a slash .RC ( / ), a warning is issued and the working directory is not changed. To force a change of directory in this case, append the character .CR !\& to the command. .TP .CR copy .I range .CR co [ py ] .I line\0flags .br .IC range " t " "line flags" .IP A copy of the specified lines .RI ( range ) is placed after the specified destination .IR line ; line 0 specifies that the lines are to be placed at the beginning of the work area. (The letter .CR t is an alternative abbreviation for the .CR copy command.) .TP .CR crypt .CR cr [ ypt ] .br .CR X .IP The user is prompted for a key with which to enter encryption mode. This command can also be used to change the key entered from a previous .CR crypt command or the .CR -x command line option. If no key is supplied in response to the prompt (that is, only carriage return is pressed), encryption mode is canceled and the work area is written out in plain-text form by subsequent write commands. .IP While in encryption mode, all file input is decrypted using the current key. However, while an input file is being processed, if a block of text (approximately 1024 bytes) is encountered that contains only 7-bit ASCII characters, that block of text is assumed to be plain-text and is not decrypted. All file output, except that piped via a .CR !\& shell escape to another command, is encrypted using the current key. .IP The temporary file used by the editor to manage the work area is not encrypted until the current work area is discarded (or written out) and editing begins on a new file. When creating a new file that requires encryption protection, ensure that the work area file is also encrypted by specifying the .CR -x option when invoking the editor. .TP .CR delete .I range .CR d [ elete ] .I buffer\ count .IP The specified lines are deleted from the work area. If a named .I buffer is specified, the deleted text is saved in it. If no buffer is specified, the unnamed buffer is used (that is, the buffer where the most recently deleted or yanked text is placed by default). The new current line is the line after the deleted lines or the last line of the file if the deleted lines were at the end of the file. .TP .CR edit .CR e [ dit ][ ! ] .RC [ + .IR line ] .I file .br .CR ex [ ! ] .RC [ + .IR line ] .I file .IP Begin editing a new file .RC ( ex is an alternative name for the .CR edit command). If the current work area has been modified since the last write, a warning is printed and the command is aborted. This action can be overridden by appending the character .CR !\& to the command .RC ( e!\& .IR file ). The current line is the last line of the work area unless it is executed from within .IR vi , in which case the current line is the first line of the work area. If the .CI + line option is specified, the current line is set to the specified position, where .I line can be a number (or .CR $ ) or specified as .CI / re or .CI ? re\f1. .TP .CR file .CR f [ ile ] .IP Print the current file name and other information, including the number of lines and the current position. .TP .CR global .I range .CR g [ lobal ][ ! ] .CI / re / .I command ...\& .br .I range .CR v .CI / re / .I command ...\& .IP Perform .I command on lines within .I range (or on the entire work area if no .I range is given) that contain .IR re . First mark the lines within the given .I range that match the pattern .IR re . If the pattern is omitted, the more recently set of either the substitution string or the scanning string is used (see Regular Expressions above). Then the given .IR command s are executed with .CR .\& set to each marked line. Any character other than a letter or a digit can be used to delimit the pattern instead of the .CR / . .IP .I command can be specified on multiple lines by hiding new-lines with a backslash. If .I command is omitted, each line is printed. .CR append , .CR change , and .CR insert commands are allowed; the terminating dot can be omitted if it ends .I command or .IR command s. The .CR visual command is also permitted (unless the .CR global command itself has been issued from visual mode), and takes input from the terminal. (If .I command contains a visual-mode command (that is, .CR open or .CR visual ), the visual-mode command must be terminated by the visual-mode .CR Q command in order to proceed to the next marked line.) .IP The .CR global command itself and the .CR undo command are not allowed in .IR command . The editor options .CR autoprint , .CR autoindent , and .CR report are inhibited. .IP Appending a .CR !\& to the .CR global command (that is, .CR g! \0...) or using the alternate name .CR v causes .I command to be run on the lines within .I range that do not match the pattern. .TP .CR insert .I line .CR i [ nsert ][ ! ] .IP Enter input mode; the input text is placed before the specified line. The last line input becomes the current line, or the line before the target line, if no lines are input. .IP Appending .CR !\& to the command toggles the .CR autoindent editor option setting for this insert only. .TP .CR join .I range .CR j [ oin ][ ! ] .I count\0flags .IP Join together the text from the specified lines into one line. White space is adjusted to provide at least one blank character (two if a period appears at the end of a line, or none if the first character of a line is a closing parenthesis .RC ( ) )). Extra white space at the beginning of a line is discarded. .IP Appending a .CR !\& to the command causes a simpler join with no white-space processing. .TP .CR list .I range .CR l [ ist ] .I ount\0flags .IP Print the specified lines with tabs displayed as .CR ^I and the end of each line marked with a trailing .CR $ . (The only useful flag is .CR # for line numbers.) The last line printed becomes the current line. .TP .CR map .CR map .RI key \(or\c .CR #\c .IR n .I action .br .CR map!\& .RI key \(or\c .CR #\c .IR n .I action .IP The .CR map and .CR map!\& commands define macros for use in visual mode. The first argument, .IR key , can be a single character or a multicharacter sequence. In the special sequence, .CI # n\f1, .I n is a digit referring to the function key .IR n . Special characters, whitespace, and newline must be escaped with a .CR ^V to be entered in the arguments. The .I key argument cannot contain a colon .RC ( : ) as its first character, nor can a multicharacter sequence begin with an alphabetic character. .IP Macros defined by .CR map are effective in visual command mode. Macros defined by .CR map!\& are effective in visual input mode. When .I key or the function key corresponding to .CI # n is entered, the editor interprets the operation as though .I action were typed. .IP The .CR map or .CR map!\& command without options displays the corresponding current list of macros. .IP See also the editor options .CR keyboardedit , .CR keyboardedit! , .CR timeout , and .CR timeoutlen in Editor Options below. .TP .CR mark .IC line .CR ma [ rk ] .I x .br .IC line " k " x .IP The specified line is given the specified mark .IR x , which must be a single lowercase letter .RC ( a - z ). .RI x must be preceded by a space or tab. The current line position is not affected. .CR k is an alternate name for .CR mark . .TP .CR move .I range .CR m [ ove ] .I line .IP Move the specified lines .RI ( range ) to follow the target .IR line . The first line moved becomes the current line. .TP .CR next .CR n [ ext ][ ! ]\0[ .IR file \0...] .IP The next file from the command line argument list is edited. Appending a .CR !\& to the command overrides the warning about the work area having been modified since the last write (and discards any changes unless the .CR autowrite editor option is set). The argument list can be replaced by specifying a new one on this command line. .TP .CR number .I range .CR nu [ mber ] .I count flags .br .IC "range " # " count flags" .IP (The .CR # character is an alternative abbreviation for the .CR number command.) Print the lines, each preceded by its line number (the only useful flag is .CR l ). The last line printed becomes the current line. .TP .CR open .I line .CR o [ pen ] .CI / re / .I flags .IP Enter open mode, which is similar to visual mode with a one-line window. All the visual-mode commands are available. If a match is found in .IR line for the optional regular expression, the cursor is placed at the start of the matching pattern. Use the visual mode command .CR Q to exit from open mode. For more information, see .IR vi (1). .TP .CR pop .CR pop [ ! ] .IP Load the file whose name is stored at the top of the tag stack and set the current line to the stored location. The top entry of the tag stack is deleted. (The current file name is placed on the stack when you execute the line mode .CR tag command or the visual mode .CR ^] command.) .IP .CR ! overrides the warning about the work area having been modified since the last write; any changes are discarded unless the .CR autowrite editor option is set). .TP .CR preserve .CR pre [ serve ] .IP The current editor work area is saved as if the system had just crashed. Use this command in emergencies, for example when a write does not work and the work area cannot be saved in any other way. Use the .CR -r command-line option to recover the file. After the file has been preserved, a mail message shall be sent to the user. The message shall contain the name of the file, the time of preservation and an .CR ex command that could be used to recover the file. Additional information may be included in the mail message. .TP .CR print .CI range .CR p [ rint ] .I count .IP Print the specified lines, with non-printing characters printed as control characters in the form .CR ^x ; DEL is represented as .CR ^? . The last line printed becomes the current line. .TP .CR put .I line .CR pu [ t ] .I buffer .IP Place deleted or "yanked" lines after .IR line . A buffer can be specified; otherwise, the text in the unnamed buffer (that is, the buffer in which deleted or yanked text is placed by default) is restored. The current line indicator shall be set to the first line put back. .TP .CR quit .CR q [ uit ][ ! ] .IP Terminate the edit. If the work area has been modified since the last write, a warning is printed and the command fails. To force termination without preserving changes, append .CR !\& to the command. .TP .CR read .I line .CR r [ ead ] .I file .IP Place a copy of the specified .I file in the work area after the target line (which can be line 0 to place text at the beginning). If no .I file is named, the current file is the default. If no current file exists, .I file becomes the current file. The last line read becomes the current line except in visual mode where the first line read becomes the current line. .IP If .CR file is given as .CI ! string\f1, .I string is interpreted as a system command and passed to the command interpreter; the resultant output is read into the work area. A blank or tab must precede the .CR ! . .TP .CR recover .CR rec [ over ][ ! ] .I file .IP Recover .I file from the save area, after an accidental hangup or a system crash. If the current work area has been modified since the last write, a warning is printed and the command is aborted. This action can be overridden by appending the character .CR !\& to the command .RC ( rec!\& .IR file ). .TP .CR rewind .CR rew [ ind ][ ! ] .IP The argument list is rewound, and the first file in the list is edited. This shall be equivalent to a .CR next command with the current argument list as its operands. If the current buffer has been modified since the last write, a warning shall be written and the command shall be aborted. Any warnings can be overridden by appending a .CR ! . The current indicator line shall be affected by the editor options, .CR autowrite and .CR writeany . .TP .CR set .CR se [ t ] .RC [ all ] .br .CR se [ t ] .RC [ no ]\f2boolean-option\f1 ? .br .CR se [ t ] .RC \f2value-option\f1[ ? ] .br .CR se [ t ] .IR boolean-option .br .CR se [ t ] .CI no boolean-option .br .CR se [ t ] .IC value-option = value .IP Set and display the values of the editor options (see Editor Options below). .IP With no arguments, the command prints those editor options whose values have been changed from the default settings. If .CR all is specified, it prints all current option values. .IP The second and third forms display the current value of the specified option. The .CR ?\& is necessary only for Boolean options. .IP The fourth form turns a Boolean option on. The fifth form turns a Boolean option off. .IP The sixth form assigns values to string and numeric options. Spaces and tabs in strings must be escaped with a leading backslash .RC ( \e ). .IP The last five forms can be combined; interpretation is left-to-right. .TP .CR shell .CR sh [ ell ] .IP Execute the command interpreter specified by the .CR shell editor option (see Editor Options below). Editing is resumed when you exit from the command interpreter. .TP .CR source .CR so [ urce ] .I file .IP Read and execute commands from the specified .IR file . .CR so commands can be nested. The maximum supported nesting depths is implementation defined, but shall be at least one. .TP .CR substitute .I range .CR s [ ubstitute ] .CI / re / repl / .I options count flags .br .IC "range " s " options count flags" .br .IC "range " & " options count flags" .br .IC "range " sr " options count flags" .br .IC "range " ~ " options count flags" .br .IC "range " s\e? repl .br .IC "range " s\e& repl .IP On each specified line, the first instance of the pattern .I re is replaced by the string .IR repl . (See Regular Expressions and Replacement Strings above.) Any character other than a letter or a digit can be used to delimit the pattern instead of the .CR / . .IP If you include the .CR g (global) option, all instances of the pattern in the line are substituted. .IP If you include the .CR c (confirm) option, you are queried about whether to perform each individual substitution, as follows: Before each substitution the line is displayed with the pattern to be replaced marked underneath with carets .RC ( ^ ). Type .CR y to cause the substitution to be performed; any other input to abort it. The last line substituted becomes the current line. .IP If the substitution pattern .I re is omitted .RC ( s// \f2repl / ), the more recently set of either the substitution string or the scanning string is used (see Regular Expressions above). .IP If the .CR s or .CR & forms of the command are used, the substitution pattern defaults to the previous substitution string and the replacement string defaults to the previous replacement string used. .IP If the .CR sr or .CR ~ forms of the command are used, the substitution pattern defaults to the more recently set of either the substitution string or the scanning string and the replacement string defaults to the previous replacement string used. .IP The form .CI s\e? repl is equivalent to .CI s/ scan-re / repl / \f1, where .I scan-re is the previous scanning string. .IP The form .CI s\e& repl is equivalent to .CI s/ subs-re / repl / \f1, where .I subs-re is the previous substitution string. .TP .PD 0 .CR suspend .CR su [ spend ][ ! ] .TP .CR stop .CR st [ op ][ ! ] .br .I susp .PD .IP Suspend the editor job and return to the calling shell. .CR stop and .I susp are equivalent to .CR suspend . .I susp is the user process control suspend character, which is typically the character .CR ^Z (ASCII SUB) (see .IR stty (1)). This command is disabled if the calling shell does not support job control or has disabled it. .IP The work area is written to the current file before the editor is suspended if the .CR autowrite editor option is set, the .CR readonly editor option is not set, and the work area has been modified since the last write. To override this action, append the .CR !\& character to the .CR suspend or .CR stop command. .TP .CR tag .CR ta [ g ][ ! ] .I tag .IP Search the files specified by the .CR tags editor option (see Editor Options below) sequentially until a tag definition for .I tag is found. If .I tag is found, load the associated file into the work area and set the current position to the address specified in the tag definition. .IP The work area is written to the current file before the new file is loaded if the new file is different from the current file, the .CR autowrite editor option is set, the .CR readonly editor option is not set, and the work area has been modified since the last write. To override this action, append the .CR !\& character to the command. .IP If the .CR tagstack editor option is set, the current file name and line number is pushed onto the tag stack for later recall with the line mode .CR pop command or the visual mode .CR ^] command. .TP .CR unabbreviate .CR una [ bbreviate ] .I word .IP Delete .I word from the list of abbreviations (see the .CR abbreviate command above). .TP .CR undo .CR u [ ndo ] .IP Reverse the changes made by the previous editing command. For this purpose, .CR global and .CR visual are considered single commands. Commands that affect the external environment, such as .CR write , .CR edit , and .CR next , cannot be undone. An .CR undo can itself be reversed. .TP .CR unmap .CR unm [ ap ][ ! ] .I key .IP The macro definition for .I key is removed (see the .CR map command above). .TP .CR version .CR ve [ rsion ] .IP Print the current version information for the editor. .TP .CR visual .I line .CR vi [ sual ] .I type count flags .IP Enter visual mode at the specified .IR line . .IP The .I type can be one of the characters .CR + , .CR - , .CR . , or .CR ^ , as in the .CR z (window) command, to specify the position of the specified line on the screen window The default is to place the line at the top of the screen window. .IP A .I count specifies an initial window size; the default is the value of the editor option .CR window . .IP The flags .CR # and .CR l (ell) cause the lines in the visual window to be displayed in the corresponding mode (see the .CR number and .CR list commands). .IP Use the .CR Q command to exit visual mode. For more information, see .IR vi (1). .TP .CR write .RI [ range ] .CR w [ rite ][ ! ][\c .CR >> ] .I file .br .RI [ range ] .CR wq [ ! ][ >> ] .I file .IP Write the specified lines (or the entire work area, if no .I range is given) out to .IR file , printing the number of lines and characters written. If .I file is not specified, the default is the current file (the command fails with an error message if there is no current file and no file is specified). .IP If an alternate file is specified and the file exists, the write fails, but can be forced by appending .CR !\& to the command. To append to an existing file, append .CR >> to the command. If the file does not exist, an error is reported. .IP If the file is specified as .CI ! string\f1, .I string is interpreted as a system command, the command interpreter is invoked, and the specified lines are passed as standard input to the command. .IP The command .CR wq is equivalent to a .CR w followed by a .CR q . .CR wq!\& is equivalent to .CR w!\& followed by .CR q . .CR wq>> is equivalent to .CR w>> followed by .CR q . .TP .CR xit .CR x [ it ][ ! ][\c .CR >> ] .I file .IP If changes have been made to the work area, a .CR write command is executed with any options (such as .CR ! , .CR >> , or .IR file ) used by the .CR write command. Then (in any case) the .CR quit command is executed. .TP .CR yank .I range .CR ya [ nk ] .I buffer count .IP Place the specified lines in the named .IR buffer . If no buffer is specified, the unnamed buffer is used (that is, the buffer where the most recently deleted or yanked text is placed by default). .TP (execute buffer) .CR * .RI [ buffer ] .br .CR @ .RI [ buffer ] .PD .IP Execute the contents of .I buffer as an editor command. .I buffer can be the letter of a named buffer .RC ( a \(mi z ) or .CR * or .CR @ . The .CR * and the .CR @ forms of this command are equivalent. If a buffer is not specified or .I buffer is .CR * or .CR @ , the buffer last named in a .CR * or .CR @ command is executed. .TP (line number) .IC "line " = " flags" .IP Print the line number of the specified .IR line . The default is the last line. The current line position is not affected. .TP (scroll) .CR ^D .IP Print the next .I n lines, where .I n is the value of the .CR scroll editor option. .TP (shell escape) .CI ! \ command .br .IC "range " ! " command" .IP Pass the remainder of the line after the .CR !\& to the system command interpreter for execution. A warning is issued if the work area has been changed since the last write. A single .CR !\& is printed when the command completes. The current line position is not affected. .IP Within the text of .IR command , .CR % and .CR # are expanded as file names, and .CR !\& is replaced with the text of the previous .CR !\& command. Thus, .CR !!\& repeats the previous .CR !\& command. When such expansion is performed, the expanded line is echoed. .IP If you specify .IR range , the specified lines are passed to the command interpreter as standard input. The output from the .I command replaces the specified lines. .TP (shift left) .IC "range " < " count flags" .IP Shift the specified lines to the left. The number of spaces to be deleted is determined by the editor option .CR shiftwidth . Only whitespace (blanks and tabs) is lost in shifting; other characters are not affected. The last line changed becomes the current line. .TP (shift right) .IC "range " > " count flags" .br Shift the specified lines to the right by inserting whitespace The number of spaces inserted is determined by the editor option .CR shiftwidth . The last line changed becomes the current line. .TP (window) .IC "line " z " type count flags" .IP The number of lines specified by .I count are displayed. The default for .I count is the value of the editor option .CR window . .IP If .I type is omitted, .I count lines following the specified .I line are printed. .IP If .I type is specified, it must be one of the following characters: .RS .TP .PD 0 .CR + Display a window of lines following the addressed line. .TP .CR - Place the addressed line at the bottom of the window of displayed lines. .TP .CR .\& Place the addressed line at the center of the window. .TP .CR ^ Display a window of lines that is two windows prior to the addressed line. .TP .CR = Display the addressed line at the center of the window with a line of dashes above and below the addressed line. .PD .RE .IP The last line printed becomes the current line, except for the .CR = , where the addressed line becomes the current line. .SS "Editor Options" The command .CR ex has a number of options that modify its behavior. These options have default settings, which can be changed using the .CR set command (see above). Options can also be set at startup by putting a .CR set command string in the environment variable .CR EXINIT , or in the file .CR .exrc in the .CR HOME directory, or in .CR .exrc in the current directory. If .CR EXINIT exists, the .CR .exrc file in the .CR HOME directory is not executed. If the current directory is not the .CR HOME directory and the .CR exrc editor option is set (see below), the .CR .exrc file in the current directory is executed after .CR EXINIT or the .CR HOME directory .CR .exrc . .PP The editor obtains the horizontal and vertical size of the terminal screen from the .CR terminfo database (see .IR terminfo (4)). These values can be overridden by setting the .CR UNIX95 environment variable, which specifies to use the XPG4 behavior for this command. .CR COLUMNS and .CR LINES environment variables. See the .CR window editor option below for more information. .PP The following table shows the defaults that differ for the various editor personalities: .PP .ne 6 .vs+1 .TS center tab(@); lB cB s s s s lB cB s s s s lf4p+1 lf4p+1 lf4p+1 lf4p+1 lf4p+1 lf4p+1 . Name@Default Editor Options \_@\_ edit @nomagic@ novice@noreadonly@report=1@ showmode ex @ magic@nonovice@noreadonly@report=5@noshowmode vedit@nomagic@ novice@noreadonly@report=1@ showmode vi @ magic@nonovice@noreadonly@report=5@noshowmode view @ magic@nonovice@ readonly@report=5@noshowmode .TE .vs .PP Editor options are Boolean unless otherwise specified. Abbreviations are shown in parentheses. .TP 20 .CR autoindent \0( ai ) Indent each line in input mode (using blanks and tabs) to align with the previous line. Indentation begins after the line appended, or before the line inserted or the first line changed. Additional indentation can be provided as usual. Succeeding lines are automatically indented to the new alignment. .IP Reducing the indent is achieved by typing .CR ^D one or more times: the cursor is moved back to the next multiple of .CR shiftwidth spaces for each .CR ^D . A .CR ^ followed by a .CR ^D removes all indentation temporarily for the current line. A .CR 0 followed by a .CR ^D removes all indentation. .IP Reversed by .CR noautoindent \0( noai ). The default is .CR noautoindent . .TP .CR autoprint \0( ap ) The current line is printed after each command that changes work area text. Autoprint is suppressed in .CR global commands. Reversed by .CR noautoprint \0( noap ). The default is .CR autoprint . .TP .CR autowrite \0( aw ) The work area is written out to the current file if the work area has been modified and a .CR next , .CR rewind , or .CR !\& command is given. Reversed by .CR noautowrite \0( noaw ). The default is .CR noautowrite . .TP .CR beautify \0( bf ) Cause all control characters other than tab, newline, and formfeed to be discarded from the input text. Reversed by .CR nobeautify \0( nobf ). The default is .CR nobeautify . .TP .CR directory= \f2dirname\f1\0( dir ) Specify the directory in which the editor work area should be placed. This option only takes effect when a new work area is created. It should be set in .CR EXINIT or .CR .exrc to affect the location of the work area file for the edit file specified on the command line. The default is .CR /var/tmp . .IP If the specified directory is set from .CR EXINIT or a .CR .exrc file and is not writable by the user, the editor quits; if set interactively by the user, the editor issues an error message. .TP .CR "doubleescape" When set, two consecutive ESC (escape) characters are required to leave input mode. In input mode, a single ESC character followed by a different character causes .CR vi to issue an audible or visual warning (see the .CR flash editor option) and insert both characters into the work area. Reversed by .CR nodoubleescape . The default is .CR nodoubleescape . .IP The character sequences transmitted by the keyboard editing keys of some terminals are identical to some sequences of .CR vi user commands. If the mapping of these keys is enabled (see the .CR keyboardedit and .CR keyboardedit!\& options), .CR vi might not be able to reliably distinguish between the character sequence transmitted by an editing key and the same character sequence typed by a user. This problem is most likely to occur when the user types ESC to terminate input mode immediately followed by another .CR vi command. If you set the .CR doubleescape option, the ambiguity of this case is removed. .TP .CR edcompatible \0( ed ) Cause the presence of .CR g and .CR c suffixes on substitute commands to be remembered, and toggled by repeating the suffixes. Reversed by .CR noedcompatible \0( noed ). The default is .CR noedcompatible . .TP .CR errorbells \0( eb ) When set, error messages are preceded with a bell only on terminals that do not support a standout or highlighting mode such as inverse video. If the terminal supports highlighting, the bell is never used prior to error messages and this option has no effect. Note that visual-mode errors are signaled by the bell (regardless of the setting of this option) without an accompanying error message. .IP Reversed by .CR noerrorbells \0( noeb ). The default is .CR noerrorbells . .TP .CR exrc When set, the .CR .exrc file in the current directory is processed during editor initialization if the current directory is not the .CR HOME directory. This option is not set by default and must be set in the .CR EXINIT environment variable or the .CR HOME directory .CR .exrc file to have any effect. See the Editor Options introductory text above. Reversed by .CR noexrc . The default is .CR noexrc . .TP .CR flash \0( fl ) When set, the screen flashes instead of beeping, provided an appropriate .CR flash_screen entry is present in the .CR /usr/share/lib/terminfo database for the terminal being used. Reversed by .CR noflash \0( nofl ). The default is .CR flash . .TP .CR hardtabs= \f2number\f1\0( ht ) Define the spacing between hardware tab settings and the number of spaces used by the system when expanding tab characters. Tab stops are placed in each column number (starting at the left edge of the screen) that corresponds to an integer multiple of .IR number . The default is .CR "hardtabs=8" . .TP .CR ignorecase \0( ic ) All uppercase characters in the text are mapped to lowercase in regular expression matching. Also, all uppercase characters in regular expressions are mapped to lowercase, except in character class specifications. Reversed by .CR noignorecase \0( noic ). The default is .CR noignorecase . .TP .CR keyboardedit When set, any keyboard editing key mappings that are loaded automatically at initialization for command-mode use are enabled. If not set, these mappings are disabled (but not deleted). Use the .CR map command to get a list of the currently enabled command-mode mappings. Reversed by .CR nokeyboardedit . The default is .CR keyboardedit . .TP .CR keyboardedit!\& When set, the keyboard editing key mappings automatically loaded at initialization for input mode use are enabled. If not set, these mappings are disabled (but not deleted). Use the .CR map!\& command to list the currently enabled input-mode mappings. Reversed by .CR nokeyboardedit! . The default is .CR nokeyboardedit!\& for terminals whose keyboard editing keys send HP-style escape sequences (an ESC followed by a single letter). The default is .CR keyboardedit!\& for all other terminals. .TP .CR "lisp" Modify .CR autoindent mode and the .CR ( , .CR ) , .CR [[ , .CR ]] , .CR { , and .CR } commands in visual mode for .CR lisp source code. Reversed by .CR nolisp . The default is .CR nolisp . .TP .CR list Display all printed lines with tabs shown as .CR ^I , and the end of line marked by a .CR $ . Reversed by .CR nolist . The default is .CR nolist . .TP .CR magic Affect the interpretation of characters in regular expressions and substitution replacement strings (see Regular Expressions and Replacement Strings above). Reversed by .CR nomagic . The .CR ex , .CR vi , and .CR view default is .CR magic . The .CR edit and .CR vedit default is .CR nomagic . .TP .CR mesg Allows other users to use the .CR write command (see .IR write (1)) to send messages to your terminal, possibly disrupting the screen display. Unsetting this option .RC ( nomesg ) blocks write permission to your terminal from other system users while you are using the editor. Reversed by .CR nomesg . The default is .CR mesg . .TP .CR modelines \0( ml ) If set when the editor reads in a file, any .CR ex commands embedded in the first five and last five lines of the file are executed after .CR .exrc and .CR EXINIT commands are processed but before editing control is given to the user. The .CR ex commands must be prefixed by .CR ex: or .CR vi: and terminated by .CR : in a single line. Any number of other characters with the exception of the colon .RC ( : ) can precede or follow the embedded command. Reversed by .CR nomodelines \0( noml ). The default is .CR nomodelines . .TP .CR novice Use the version of the editor available for novices, known as .CR edit or .CR vedit . Reversed by .CR nonovice . The .CR ex , .CR vi , and .CR view default is .CR nonovice . The .CR edit , and .CR vedit default is .CR novice . .TP .CR number \0( nu ) Cause lines to be printed with line numbers. Reversed by .CR nonumber \0( nonu ). The default is .CR nonumber . .TP .CR optimize \0( opt ) Suppress automatic carriage returns on terminals that do not support direct cursor addressing. This streamlines text output in certain situations such as when printing multiple lines that contain leading whitespace. Reversed by .CR nooptimize \0( noopt ). The default is .CR nooptimize . .TP .CR paragraphs= \f2pair-string\f1\0( para ) The value of this option is a string whose successive pairs of characters specify the names of text-processing macros that begin paragraphs. (A macro appears in the text in the form .CI . xx\f1, where the .CR .\& is the first character in the line.) .IP If any macros have a single-character name, use a space character to substitute for the missing second character in the name. To type a space character in such situations, precede the space with a backslash .RC ( \e ) to prevent the editor from interpreting it as a delimiter. .IP The default is .CR paragraphs=IPLPPPQPP\e\0LIpplpipnpbp . .TP .CR prompt When set, command mode input is prompted for with a colon .RC ( : ); when unset, no prompt is displayed. Reversed by .CR noprompt . The default is .CR prompt . .TP .CR readonly \0( ro ) Set the .CR readonly flag for the file being edited, thus preventing accidental overwriting at the end of the session. This option is equivalent to invoking .CR ex , .CR edit , .CR vi , or .CR vedit with the .CR -R option or using the .CR view command. Reversed by .CR noreadonly \0( noro ). The .CR ex , .CR edit , .CR vi , and .CR vedit default is .CR noreadonly . The .CR view default is .CR readonly . .TP .CR redraw Simulate an intelligent terminal on a dumb terminal. During input mode, lines are continuously reprinted as text is entered. Since this is likely to require a large amount of output to the terminal, it is useful only at high transmission speeds. If .CR noredraw is set, lines are reprinted only when input mode is terminated and deleted lines are marked with an .CR @ in the left margin. Reversed by .CR noredraw . The default is .CR redraw . .TP .CR remap If set, macro translation allows for macros defined in terms of other macros; translation continues until the final product is obtained. If unset, a one-step translation only is done. Reversed by .CR noremap . The default is .CR remap . .TP .CI report= n The value of .IR n gives the number of lines that must be changed by a command before a report is displayed on the number of lines affected. If .IR n is 5, then changes are reported for 6 or more lines. The .CR ex , .CR vi , and .CR view default is .CR report=5 . The .CR edit , and .CR vedit default is .CR report=1 . .TP .CI scroll= n The value of .IR n determines the number of lines scrolled by a .CR ^D command and the number of lines displayed by the .CR z command (twice the value of scroll). The default is half the value of the .CR window option. .TP .CI sections= pair-string The value of this option is a string, in that successive pairs of characters specify the names of text-processing macros that begin sections. See the .CR paragraphs editor option above. The default is .CR sections=NHSHH\e\0HUuhsh+c . .TP .CR shell= \f2filename\f1\0( sh ) Set the file name of the shell to be used for the .CR !\& shell escape and the .CR shell command. It defaults to the value of your .CR SHELL environment variable, if set, and otherwise to .CR /usr/bin/sh . .TP .CR shiftwidth= \f2n\f1\0( sw ) Sets the indentation step value used by .CR autoindent and the shift .RC ( < and .CR > ) commands. The default is .CR shiftwidth=8 . .TP .CR showmatch \0( sm ) In visual mode, jump momentarily to the matching .CR ( or .CR { when you type a .CR ) or .CR } , if the match is still on the screen. Reversed by .CR noshowmatch \0( nosm ). The default is .CR noshowmatch . .TP .CR showmode \0( smd ) Display the current editor mode (such as .CR "INPUT MODE" , .CR "REPLACE 1 CHAR" , .CR "REPLACE MODE" ) in the lower right-hand corner of the screen during visual and open mode. Reversed by .CR noshowmode \0( nosmd ). The .CR ex , .CR vi , and .CR view default is .CR noshowmode . The .CR edit , and .CR vedit default is .CR showmode . .TP .CR slowopen \0( slow ) In visual mode, .CR slowopen prevents screen updates during input to improve throughput on unintelligent terminals. Reversed by .CR noslowopen \0( noslow ). The default is .CR noslowopen . .TP .CR tabstop= \f2n\f1\0( ts ) Sets the spacing of the software tab stops used by the editor to expand tabs in the input file. The default is .CR tabstop=8 . .TP .CR taglength= \f2n\f1\0( tl ) Set the maximum number of characters that should be treated as significant in a tag. Characters beyond the limit are ignored. A value of zero means that all characters in the tag are significant. The default is .CR taglength=0 . .TP .CR tags= [\f2filename\0\f1]... Specify the tags files to be used by the .CR tag command and the .CR -t command-line option. The default is .CR "tags=tags /usr/lib/tags" , specifying the file .CR tags in the current directory and the file .CR /usr/lib/tags . File names are separated by whitespace. .IP Each line of a tags file contains the following three fields separated by whitespace: the tag name, the name of the file to be edited, and an address specification (see Addressing above). A .CR tags file must be sorted in order by tag name. .IP The .CR ctags command (see .IR ctags (1)) creates tags files from C, Pascal and FORTRAN source files. .TP .CR tagstack \0( tgst ) Enable the pushdown stack of activated tags. Reversed by .CR notagstack \0( notgst ). The default is .CR tagstack . .IP When you enter a line mode .CR tag command or visual mode .CR ^] command, the current line number and file name are stored on the tag stack. A future line mode .CR pop command or visual mode .CR ^T command will return to the stored file name at the stored line number. .IP If the tag stack is disabled and then reenabled again, the stack continues where it left off. The .CR pop command does not work when the tag stack is disabled. .TP .CI term= termtype Define the type of terminal being used with the editor. The default value is obtained from the .CR TERM environment variable. If .CR TERM is unset or null, .CR term is set to .CR unknown . There is no difference between the .CR term and .CR ttytype editor options. Setting either one results in both being changed. .TP .CR terse Use shorter error messages. Reversed by .CR noterse . The default is .CR noterse . .TP .CR timeout \0( to ) If set, require that all the characters of a multicharacter macro name (the first argument in a .CR map command) must be received within the amount of time specified by the .CR timeoutlen option in order to be accepted as a match for the macro name. If not set, no limit is placed on how long to wait for the completion of a macro name. Reversed by .CR notimeout \0( noto ). The default is .CR timeout . .TP .CI timeoutlen= n Set, in milliseconds (ms), the length of the macro timeout period (see the .CR timeout editor option). This option has no effect unless .CR timeout is set. The value of .IR n must be at least 1. The default is .CR timeoutlen=500 (half a second). .TP .CR ttytype= \f2termtype\f1\0( tty ) Define the type of terminal being used with the editor. See the .CR term editor option for details. There is no difference between the .CR term and .CR ttytype editor options. Setting either one results in both being changed. .TP .CR warn Before executing a .CR !\& or .CR shell command escape, display the message .CR "[No write since last change]" if the work area has been modified since it was last loaded or fully written to a file. Reversed by .CR nowarn . The default is .CR warn . .TP .CR window= \f2lines\f1\0( wi ) Set the number of lines in a text window in visual mode. The default value is one less than the size of your terminal screen (as defined by the .CR LINES environment variable, if set, or the entry for your terminal in the .IR terminfo (4) data base otherwise). However, if the terminal baud rate (see .IR stty (1) is set to less than 1200 or 2400, the default value is reduced to a maximum of 8 or 16 lines, respectively. The startup value can be specified with the .CR -w command-line option. .TP .CI w300= lines If the terminal baud rate is less than 1200, set the .CR window editor option to the value specified. .TP .CI w1200= lines If the terminal baud rate is greater than or equal to 1200 but less than 2400, set the .CR window editor option to the value specified. .TP .CI w9600= lines If the terminal baud rate is greater than or equal to 2400, set the .CR window editor option to the value specified. .TP .CR wrapmargin= \f2n\f1\0( wm ) In visual mode only, if .IR n is greater than zero, a newline is automatically inserted in an input line at a word boundary, so that lines end at least .IR n spaces from the right margin of the terminal screen. The default is .CR wrapmargin=0 . .TP .CR wrapscan \0( ws ) When set, editor searches using .CI / re / (or .CI ? re ?\f1) continue silently from the beginning (or end) of the file upon reaching the end (or beginning) of the file (that is, the scan "wraps around"). When unset, editor searches stop at the beginning or the end of the file, as appropriate. Reversed by .CR nowrapscan \0( nows ). The default is .CR wrapscan . .TP .CR writeany \0( wa ) Inhibits the checks otherwise made before write commands, allowing a write to any file (provided the system allows it). Reversed by .CR nowriteany \0( nowa ). The default is .CR nowriteany . .SH EXTERNAL INFLUENCES .SS Environment Variables .CR COLUMNS This variable shall override the system-selected horizontal screen size. .PP .CR LINES overrides the system-selected vertical screen size, used as the number of lines in a screenful and as the vertical screen size in visual mode. .PP .CR PATH determines the search path for the shell command specified in the editor commands, .CR shell, .CR read , and .CR write . .PP .CR SHELL is variable that shall be interpreted as the preferred command-line interpreter for use in .CR ! , .CR shell , .CR read , and other commands with an operand of the form .CR !string . For the .CR shell command, the program shall be invoked with the single argument .CR -i . For all others, it shall be invoked with the two arguments .C -c and string. If no .C SHELL environment variable is set, or it is set to a null string, the .C sh utility shall be used. .PP .CR TERM is a variable that shall be interpreted as the name of the terminal type. If this variable is unset or null, an unspecified default terminal type shall be used. .PP .CR EXINIT is a variable that shall be interpreted to contain a list of .C ex commands that are executed on editor startup, before reading the first file. The list can contain multiple commands by separating then using a vertical line (|) character. .PP .CR HOME shall be interpreted as a pathname of a directory that shall be searched for an editor startup file name .CR .exrc . .PP .CR LC_COLLATE determines the collating sequence used in evaluating regular expressions and in processing the .CR tags file. If it is not specified or is null, it defaults to the value of .CR LANG . .PP .CR LC_CTYPE determines the interpretation of text as single and/or multibyte characters, the classification of characters as uppercase or lowercase letters, the shifting of the case of letters, and the characters matched by character class expressions in regular expressions. If it is not specified or is null, it defaults to the value of .CR LANG . .PP .CR LANG determines the language in which messages are displayed. If it is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP .CR LC_ALL determines the locale to be used to override any values for locale categories specified by the setting of .C LANG or any environment variable (beginning with .C LC_ ). .PP .CR LC_MESSAGES determines the processing of affirmative responses and the language in which messages should be written. .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .PP When set, the .CR TMPDIR environment variable specifies a directory to be used for temporary files, overriding the default directory .CR /var/tmp . .SS International Code Set Support Single- and multibyte character code sets are supported. .SH ASYNCHRONOUS EVENTS (XPG4 Only) The following actions shall be taken upon receipt of signals: .TP .CR SIGINT When an interrupt occurs, .C ex shall alert the terminal and write a message. The current editor command shall be aborted, and .C ex shall return to the command level and prompt for another command. If the standard input is not a terminal device, .C ex shall exit at the interrupt and return a nonzero exit status. .PP .TP .CR SIGCONT The screen shall be refreshed. .PP .TP .CR SHIGHUP If the current buffer has changed since the last .C e or .C w command, .C ex shall attempt to save the current file in a state such that it can be recovered later by an .C ex -r command. .PP .RE The action taken for all other signals is unspecified. .SH EXTENDED DESCRIPTION (XPG4 Only) The pathname of the file being edited by .C ex is referred to as the .C current file. The text of the file shall be read into a working version of the file (called .C buffer in this clause), and all editing changes shall be performed on that version; the changes shall have no effect on the original file until an .C ex command causes the file to be written out. Lines in the buffer may be limited to { .C LINE_MAX } bytes, and an error message may be written if the limit is exceeded during editing. .PP The .C alternate pathname is the name of the last file mentioned in an editor command, or the previous current pathname if the last file mentioned became the current file. When the .C % appears in a pathname entered as part of a command argument, it shall be replaced by the altername pathname. Any character, including .C % and .C # shall retain its literal value when preceded by a backslash. .PP When an error occurs, .C ex shall alert ther terminal and write a message. .PP If the system crashes, .C ex shall attempt to preserve the buffer if any unwritten changes were made. The command-line option .C -r can be used to retrieve the saved changes. .PP During initialization (before the first file is read or any user commands from the terminal are processed), if the environment variable .C EXINIT is set, the editor shall execute .C ex commands contained in that variable. If the variable is not set, .C ex shall attempt to read commands from the .CR $HOME/.exrc . If and only if .C EXINIT or .C $HOME/.exrc sets the editor option exrc, ex finally shall attempt to read commands from a file .C .exrc in the current directory. In the event that .C EXINIT is not set and the current directory is the home directory of the user, any .C .exrc file shall only be processed once. No .C .exrc shall be read unless it is owned by the same user ID as the effective user ID of the process. After any .C .exrc files are processed, any commands specified by the .C -c option shall be processed. .PP By default, .C ex shall start in the command mode, which shall be indicated by the ":" prompt. The input mode can be entered by .CR append , .CR insert , or .CR change commands. There is one other mode, visual mode, in which full screen editing is available. This is described more fully under the .CR visual command. The command line can consist of multiple .C ex commands separated by vertical-line characters(|). The use of commands that enter input or visual modes in this manner, unless they are the final command on the line, produces undefined results. .PP Command lines beginning with the double-quote character (") shall be ignored. This can be used for comments in an editor script. .\" .SH EXAMPLES (none needed) .SH WARNINGS The .CR undo command causes all marks to be lost on lines that are changed and then restored. .PP The .CR z command prints a number of logical rather than physical lines. More than a screenful of output can result if long lines are present. .PP Null characters are discarded in input files and cannot appear in resultant files. .PP On some systems, the recovery of an edit file with the .CR -r option is possible only if certain system-dependent actions are taken when the system is restarted. .PP Edit preserve files can only be recovered on systems running the same HP-UX release in which they were preserved. Preserve files are not recoverable across different releases. .PP On HP terminals, the attribute field of any function key specified by a .CI "map #" "n ..." command should be set to .CR normal rather than to the default of .CR transmit . .PP For information about line length limits, file size limits, etc., see the WARNINGS section of .IR vi (1). .SH EXIT STATUS (XPG4 Only) The .CR ex utility shall exit with one of the following values: .TP .CR 0 Successful completion. .PP .TP .CR >0 An error occurred. .SH AUTHOR .CR ex was developed by the University of California, Berkeley. The 16-bit extensions to .CR ex are based in part on software of the Toshiba Corporation. .SH FILES .ifn .TP 30 .ift .TP 40 .PD 0 .CR $HOME/.exrc Primary editor initialization file .TP .CR ./.exrc Secondary editor initialization file .TP .CR /usr/lbin/expreserve Preserve command .TP .CR /usr/lbin/exrecover Recover command .TP .CR /usr/share/lib/terminfo/*/* Description of terminal capabilities .TP .CR /var/preserve Preservation directory .TP .CI /var/tmp/Ex nnnnn Editor temporary file .TP .CI /var/tmp/Rx nnnnn Named buffer temporary file .PD .SH SEE ALSO ctags(1), ed(1), stty(1), vi(1), write(1), terminfo(4), environ(5), lang(5), regexp(5). .TP .IR "The Ultimate Guide to the vi and ex Text Editors" , Benjamin/Cummings Publishing Company, Inc., ISBN 0-8053-4460-8, HP part number 97005-90015. .SH STANDARDS COMPLIANCE .CR ex ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4e\f1 \- extended line-oriented text editor@@@\f3ex(1)\f1 .\" index@\f4ex\f1 \- extended line-oriented text editor@@@\f3ex(1)\f1 .\" index@\f4edit\f1 \- beginner's line-oriented text editor@@@\f3ex(1)\f1 .\" index@\f1editor: extended line-oriented text editor@@@\f3ex(1)\f1 .\" index@\f1line-oriented text editor@@@\f3ex(1)\f1 .\" index@\f1text editor, line-oriented@@@\f3ex(1)\f1 .\" .\" toc@\f3ex(1)\f1:\0\0\f4edit\f1, \f4ex\f1@@@extended line-oriented text editor .\" toc@\f4edit\f1:\0\0extended line-oriented text editor@@@see \f3ex(1)\f1 .\" .\" links@ex.1 edit.1 .\" .\" $Header: expand.1,v 76.3 95/08/07 11:34:26 ssa Exp $ .TA e .TH expand 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME expand, unexpand \- expand tabs to spaces, and vice versa .SH SYNOPSIS .C expand .RC [ -t .IR tablist\| ] .RI [ \|file \0...\|] .PP .br .C unexpand .RC [ -a ] .RC [ -t .IR tablist\| ] .RI [ \|file \0...\|] .SS Obsolescent: .C expand .RC [ -\c .IR tabstop\| ] .RC [ -\c .IC tab1 , tab2 ,\c .RC ... , .IR tabn\| ] .RI [ \|file \0...\|] .SH DESCRIPTION .C expand processes the named files or the standard input and writes to the standard output with tabs changed into spaces. Backspace characters are preserved in the output, and the column count is decreased by one column for tab calculations. For proper tab calculation, if a multi-column character is to be "backspace'd", it should be followed by multiple backspace characters which equal to it's column width. If a tab character is found after the last tab position, it is replaced by a single space. .C expand is useful for preprocessing character files that contain tabs (before sorting, looking at specific columns, etc). .PP .C expand recognizes the following command-line options and arguments: .RS .TP 15 .RC [ -t \0\f2tablist\fP\|] .I tablist specifies where to set the tab positions instead of the default .CR 8 . .I tablist can take two forms. If it is a single number, tabs are set .I tablist spaces apart. .I tablist can also be a blank- or comma-separated list of increasing positions where tabs are to be set. .TP .RC [ - \f2tabstop\fP\|] This option is obsolescent and is equivalent to using .CI -t \0tabstop\f1. .TP .RC [ -\s-1\f2tab1\fP,\f2tab2\fP,\f1...\fP,\f2tabn\fP\s0\| ] This option is obsolescent and is equivalent to using .C -t .IR tab1 , tab2 ,\c .IC ... , tabn\f1. .RE .PP .C unexpand processes the named files or the standard input and writes to the standard output with spaces changed into tabs where possible. By default, only leading spaces and tabs are converted to maximal strings of tabs. The default tab position is every 8 characters. Backspace characters are preserved into the output, and the column count is decreased by one column for tab calculations. For proper tab calculation, if a multi-column character is to be "backspace'd", it should be followed by multiple backspace characters which equal to it's column width. .PP .C unexpand recognizes the following command-line options and arguments: .RS .TP 15 .C -a Tabs are inserted whenever they would compress the resultant file by replacing two or more spaces before a tab position. .TP .BI \-t \0tablist .I tablist specifies the tab positions. .I tablist can take two forms. If it is a single number, tabs are set every .I tablist spaces apart. If .I tablist is a blank- or comma-separated list of increasing positions, tabs are set at those locations. The .C -t option implies the .C -a option. If the .C -t option is not specified, the default is equivalent to specifying .C -t 8 except that .C -a is not implied for this case. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text as single and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C expand and .C unexpand behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported with the exception that .C unexpand do not recognize multi-byte alternative space characters. .SH STANDARDS CONFORMANCE .CR expand ": XPG4, POSIX.2" .PP .CR unexpand ": XPG4, POSIX.2" .\" .\" toc@\f3expand(1)\f1:\0\0\f4expand\f1, \f4unexpand\f1@@@expand tabs to spaces, and vice versa .\" toc \f4unexpand\f1: convert spaces to tabs see \f3expand(1)\f1 .\" .\" index@\f4expand\f1, \f4unexpand\f1 \- expand tabs to spaces, and vice versa@@@\f3expand(1)\f1 .\" index@\f4unexpand\f1, \f4expand\f1 \- expand tabs to spaces, and vice versa@@@\f3expand(1)\f1 .\" index@\f1convert tabs to spaces, and vice versa@@@\f3expand(1)\f1 .\" index@\f1tabs, convert to spaces and vice versa@@@\f3expand(1)\f1 .\" index@\f1spaces, convert to tabs and vice versa@@@\f3expand(1)\f1 .\" .\" links@expand.1 unexpand.1 .\" .\" $Header: expand_alias.1,v 78.3 96/05/09 11:11:48 ssa Exp $ .TA e .TH expand_alias 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME expand_alias \- Recursively expands the sendmail aliases .SH SYNOPSIS .C expand_alias .RC [ -r\c .IR max_recursion ] .RC [ -t ] .RC [ -tt ] .I alias .SH DESCRIPTION .CR Expand_alias is a shell script that recursively expands the .CR sendmail aliases. Through use of .CR "telnet host 25" and the .CR expn command, each alias is recursively expanded into its destination(s). Indentation is used to show each level of recursion. Because of the recursive use of .CR telnet , .CR expand_alias is slow. If the local .CR telnet cannot directly connect to a remote system, due to a firewall configuration, .CR expand_alias will not be able to succeed. If the local .CR telnet .\" ================== is to transparently connect across the firewall, .CR expand_alias will be able to contact sendmail daemons outside the firewall, allowing the alias to be more fully expanded. (For example, some local telnet clients use a .CR socksd located on the firewall to permit the local .CR telnet client to transparently connect to Internet hosts. If the local default .CR telnet uses a .CR socksd in such a manner, .CR expand_alias will use that .CR telnet functionality to more fully expand an alias.) .\" ================== .PP .IR max_recursion defaults to 10. After .IR max_recursion expansions, no further expansion is attempted. .PP If .CR \-t is specified, only the terminal aliases will be displayed. .PP .CR \-tt is similar to .CR \-t except that if a terminal line has a pipe, its printing is suppressed and the previous level of expansion is printed instead. .PP .SH EXAMPLES .CR "expand_alias root" .PP .CR "expand_alias root@cat" .PP .CR "expand_alias root@cat.cup.hp.com" .PP .CR "expand_alias root@cup.hp.com" .RE .PP .SH AUTHOR .CR expand_alias was developed by the Hewlett-Packard Company. .\" .\" index@\f4expand_alias\f1 \- recursively expands the sendmail aliases@@@\f3expand_alias(1)\f1 .\" index@\f1recursively expands the sendmail aliases@@@\f3expand_alias(1)\f1 .\" index@\f1sendmail aliases, recursively expands@@@\f3expand_alias(1)\f1 .\" index@\f1expands the sendmail aliases, recursively@@@\f3expand_alias(1)\f1 .\" .\" toc@\f3expand_alias(1)\f1:\0\0\f4expand_alias\f1@@@recursively expands the sendmail aliases .\" $Header: expr.1,v 76.1 95/08/07 11:35:09 ssa Exp $ .TA e .TH expr 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME expr \- evaluate arguments as an expression .SH SYNOPSIS .C expr .I arguments .SH DESCRIPTION .C expr takes .I arguments as an expression, evaluates, then writes the result on the standard output. Terms in the expression must be separated by blanks. Characters special to the shell must be escaped. Note that .CR 0 , rather than the null string, is returned to indicate a zero value. Strings containing blanks or other special characters should be quoted. Integer-valued arguments can be preceded by a unary minus sign. Internally, integers are treated as 32-bit, 2's complement numbers. .PP The operators and keywords are listed below. Characters that need to be escaped are preceded by .CR \e . The list is in order of increasing precedence with equal-precedence operators grouped within .C {} symbols. .RS .TP 15 .IC expr " \e| " expr returns the first .I expr if it is neither null nor .CR 0 , otherwise returns the second .IR expr . .TP .IC expr " \e& " expr\f1 returns the first .I expr if neither .I expr is null or .CR 0 , otherwise returns .CR 0 . .TP .IC expr \ = \ expr .PD 0 .TP .IC expr \ \e> \ expr .TP .IC expr \ \e>= \ expr .TP .IC expr \ \e< \ expr .TP .IC expr \ \e<= \ expr .TP .IC expr \ != \ expr .sp -3v returns the result of an integer comparison if both arguments are integers; otherwise returns the result of a lexical comparison (note that .C = and .C == are identical, in that both test for equality). .PD .TP .IC expr \ + \ expr addition of integer-valued arguments. .TP .IC expr \ - \ expr subtraction of integer-valued arguments. .TP .IC expr \ \e* \ expr multiplication of integer-valued arguments. .TP .IC expr \ / \ expr division of integer-valued arguments. .TP .IC expr \ % \ expr remainder of the integer-valued arguments. .TP .IC expr \ : \ expr The matching operator .C : compares the first argument with the second argument which must be a regular expression. .I expr supports the Basic Regular Expression syntax (see .IR regexp (5)), except that all patterns are ``anchored'' (i.e., begin with .CR ^ ) and, therefore, .C ^ is not a special character, in that context. Normally, the matching operator returns the number of characters matched .RB ( 0 on failure). Alternatively, the .CR \e( \|...\| \e) pattern symbols can be used to return a portion of the first argument. .TP .CI length \ expr The length of .IR expr . .TP .CI substr " expr expr expr" Takes the substring of the first .IR expr , starting at the character specified by the second .I expr for the length given by the third .IR expr . .TP .CI index " expr expr" Returns the position in the first .I expr which contains a character found in the second .IR expr . .TP .C match Match is a prefix operator equivalent to the infix operator .CR : . .TP .CR \e( \|...\| \e) Grouping symbols. Any expression can be placed within parentheses. Parentheses can be nested to a depth of .C EXPR_NEST_MAX as specified in the header file .RC < limits.h >. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the collating sequence used in evaluating regular expressions and the behavior of the relational operators when comparing string values. .PP .C LC_CTYPE determines the interpretation of text as single- and/or multi-byte characters, and the characters matched by character class expressions in regular expressions. .PP .C LANG determines the language in which messages are displayed. .PP If .C LC_COLLATE or .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C expr behaves as if all internationalization variables are set to "C" (see .IR environ (5)). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE As a side effect of expression evaluation, .I expr returns the following exit values: .RS .TP 7 .C " 0" Expression is neither null nor zero. .TP .C " 1" Expression is null or zero. .TP .C " 2" Invalid expression. .TP >2 An error occurred while evaluating the expression. .SH DIAGNOSTICS .TP 35 .C syntax error Operator or operand errors .TP .C non-numeric argument Arithmetic attempted on a string .SH EXAMPLES Add 1 to the shell variable .CR a : .IP .C "a=`expr $a + 1`" .PP For .C $a equal to either .C /usr/abc/file or just .CR file , return the last segment of a path name (i.e., .CR file ). Beware of .C / alone as an argument because .I expr interprets it as the division operator (see .SM WARNINGS below): .IP .C "expr $a : '.*/\e(.*\e)' \e| $a" .PP A better representation of the previous example. The addition of the .C // characters eliminates any ambiguity about the division operator and simplifies the whole expression: .IP .C "expr //$a : '.*/\e(.*\e)'" .PP Return the number of characters in .CR $VAR : .IP .C "expr \s-1$VAR\s+1 : '.*'" .SH WARNINGS After argument processing by the shell, .I expr cannot tell the difference between an operator and an operand except by the value. If .C $a is an .CR = , the command: .IP expr $a = '=' .PP resembles: .IP expr = = = .PP as the arguments are passed to .I expr (and they will all be taken as the .C = operator). The following works: .IP expr X$a = X= .SH AUTHOR .CR expr was developed by OSF and HP. .SH SEE ALSO sh(1), test(1), environ(5), lang(5), regexp(5). .SH STANDARDS CONFORMANCE .CR expr ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4expr\f1 \- evaluate arguments as an expression@@@\f3expr(1)\f1 .\" index@evaluate arguments as an expression@@@\f3expr(1)\f1 .\" index@arguments, evaluate as an expression@@@\f3expr(1)\f1 .\" .\" toc@\f3expr(1)\f1:\0\0\f4expr\f1@@@evaluate arguments as an expression .\" $Header: factor.1,v 72.3 93/01/14 11:33:24 ssa Exp $ .TA f .TH factor 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME factor, primes \- factor a number, generate large primes .SH SYNOPSIS .C factor .RI [ \|number\| ] .PP .C primes .RI [ \|start\| [ \|stop\| ]\|] .SH DESCRIPTION If no arguments are provided on the command line, .C factor waits for a number to be typed in. If a positive number is typed, it factors the number and print its prime factors; each one is printed the proper number of times. It then waits for another number. .C factor exits if it encounters a zero or any non-numeric character. .PP If an argument is provided on the command line, .C factor factors the number as above, then exits. .PP Maximum time to factor is proportional to .RI sqrt( n ) and occurs when .I n is prime or the square of a prime. .PP The largest number that can be dealt with by .C factor is 1.0e14. .PP .C primes prints prime numbers between a lower and upper bound. If no arguments are provided on the command line, .C primes waits for two numbers to be typed in. The first number is interpreted as the lower bound; the second as the upper bound. All prime numbers in the resulting inclusive range are printed. .PP If .I start is specified, all primes greater than or equal to .I start are printed. If both .I start and .I stop are given, all primes occurring in the inclusive range .I start through .I stop are printed. .PP .I start and .I stop values must be integers represented as long integers. .PP If the stop value is omitted in either case, .I primes runs either until overflow occurs or until it is stopped by typing the interrupt character. .PP The largest number that can be dealt with by .I primes is 2,147,483,647. .SH DIAGNOSTICS Both commands print .C Ouch when the input is out of range, illegal characters are encountered, or when .I start is greater than .IR stop . .SH EXAMPLES Print the prime factorization for the number 12: .IP .C factor 12 .PP Print all prime numbers between 0 and 20: .IP .C primes 0 20 .\" .\" index@\f4factor\f1, \f4primes\f1 \- factor a number, generate large primes@@@\f3factor(1)\f1 .\" index@\f4primes\f1, \f4factor\f1 \- factor a number, generate large primes@@@\f3factor(1)\f1 .\" index@factor a number, generate large primes@@@\f3factor(1)\f1 .\" index@generate large primes, factor a number@@@\f3factor(1)\f1 .\" .\" toc@\f3factor(1)\f1:\0\0\f4factor\f1, \f4primes\f1@@@factor a number, generate large primes .\" toc@\f4primes\f1: generate large prime numbers@@@see \f3factor(1)\f1 .\" .\" links@factor.1 primes.1 .\" .\" fileset_database@factor.1 USER-CMDS-MAN .\" $Header: true.1,v 76.1 95/08/07 10:04:50 ssa Exp $ .TA t .TH true 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME true, false \- return exit status zero or one respectively .SH SYNOPSIS .C true .PP .C false .SH DESCRIPTION The command .C true does nothing, and returns exit code zero. The command .C false does nothing, and returns exit code one. They are typically used to construct command procedures. .SH RETURN VALUE Exit values are: .RS .TP 8 .C \00 always from .IR true . .PD 0 .TP .C \01 always from .IR false . .RE .PD .SH EXAMPLES .PP This command loop repeats without end: .nf .IP .C while true .C " do" .CI " " command .C " done" .fi .SH WARNINGS .C true is typically used in shell scripts. Some shells provide a built-in version of .C true (and .CR false ) that is more efficient than the standalone versions. .SH SEE ALSO csh(1), ksh(1), sh(1), sh-bourne(1), sh-posix(1). .SH STANDARDS CONFORMANCE .CR true ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR false ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" toc@\f3true(1)\f1:\0\0\f4true\f1, \f4false\f1@@@return zero or non-zero exit status .\" toc@\f4false\f1: do nothing and return non-zero exit status@@@see \f3true(1)\f1 .\" .\" index@\f4true\f1 \- do nothing and return zero exit status@@@\f3true(1)\f1 .\" index@\f4false\f1 \- do nothing and return non-zero exit status@@@\f3true(1)\f1 .\" index@do nothing and return zero or non-zero exit status@@@\f3true(1)\f1 .\" index@nop (do nothing) and return zero or non-zero exit status@@@\f3true(1)\f1 .\" index@exit status, do nothing and return zero or non-zero@@@\f3true(1)\f1 .\" index@status, exit, do nothing and return zero or non-zero@@@\f3true(1)\f1 .\" .\" links@true.1 false.1 .\" .\" fileset_database@true.1 USER-CMDS-MAN .\" $Header: fastbind.1,v 78.2 96/01/03 15:07:35 ssa Exp $ .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .\" .\" File: fastbind.1 .\" Description: @(#) fastbind man page B.10.10 $Date: 96/01/03 15:07:35 $ .\" Author: Ken Sumrall, California Language Lab .\" .\" (c) Copyright 1996, Hewlett-Packard Company, all rights reserved. .\" .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .TA f .TH fastbind 1 .SH NAME fastbind \- Prepare an incomplete executable for faster program start-up .SH SYNOPSIS .C fastbind .RC [-nu] .IR incomplete-executable ... .SH DESCRIPTION .CR fastbind is a tool that can improve the start-up time of programs that use shared libraries (incomplete executables) by storing information about needed shared library symbols in the executable file. .PP .CR fastbind performs analysis on the symbols used to bind an executable and all of it's dependent shared libraries, and stores this information in the executable file. The next time the executable is run, the dynamic loader .CR /usr/lib/dld.sl will notice that this information is available, and it will use this fastbind information to bind the executable instead of the standard search method for binding the symbols. .PP Since .CR fastbind writes the fastbind information in the executable file, you must have write permission on the executable file. Also, if the executable file being analyzed is being run as another process, the file will be locked against modifications by the kernel, and .CR fastbind will fail. .PP If the shared libraries that an executable is dependent on are modified after the fastbind information is created, the dynamic loader will silently revert to standard search method for binding the symbols. The fastbind information can be re\-created by running .CR fastbind on the executable again. .CR fastbind will automatically erase the old fastbind information and generate the new one. .PP The .CR ld option .CR +fb can be used to instruct the linker to run the fastbind tool on an incomplete executable it has produced. .SS Environment Variables If .CR dld determines that the fastbind information is out of date, it will silently revert to standard search method for binding the symbols. If the environment variable .CR _HP_DLDOPTS is set to .CR -fbverbose the dynamic loader .CR /usr/lib/dld.sl will emit a warning message when the fastbind information is out of date. .PP The environment variable .CR _HP_DLDOPTS can be set to .CR -nofastbind to make the dynamic loader .CR /usr/lib/dld.sl ignore the fastbind information and revert to the standard search method for binding the symbols. .SS Options .PP .CR fastbind recognizes the following options: .RS .TP 12 .C -n Remove the fastbind information from the executable, returning it to the same state it was in before .CR fastbind was originally run on it. .TP 12 .C -u Normally, if .CR fastbind detects any unsatisfied symbols while building the fastbind information, it will generate an error message and not modify the executable file. When .CR fastbind is invoked with .CR -u option however, unresolved symbols are allowed. .SH EXTERNAL INFLUENCES .SS Environment Variables .PP The following internationalization variables affect the execution of .CR fastbind : .PP .C LANG .RS Determines the locale category for native language, local customs and coded character set in the absence of .CR LC_ALL and other .CR LC_* environment variables. If .CR LANG is not specified or is set to the empty string, a default of .CR C (see .IR lang (5)) is used instead of .CR LANG . .RE .PP .CR LC_ALL .RS Determines the values for all locale categories and has precedence over .CR LANG and other .CR LC_* environment variables. .RE .PP .CR LC_MESSAGES .RS Determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error. .RE .PP .CR LC_NUMERIC .RS Determines the locale category for numeric formatting. .RE .PP .CR LC_CTYPE .RS Determines the locale category for character handling functions. .RE .PP .CR NLSPATH .RS Determines the location of message catalogs for the processing of .CR LC_MESSAGES . .RE .PP If any internationalization variable contains an invalid setting, .CR fastbind behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .PP In addition, the following environment variable affects .CR fastbind : .PP .C TMPDIR .RS Specifies a directory for temporary files (see .IR tmpnam (3S)). .RE .SH DIAGNOSTICS .CR fastbind returns zero when the operation is successful. A non-zero return code indicates that an error occurred. .SH EXAMPLES To run .CR fastbind on the executable file .CR a.out enter: .IP .C fastbind a.out .PP To later remove the fastbind information from the executable file .CR a.out enter: .IP .C fastbind -n a.out .SH WARNINGS .CR fastbind does not work with EXEC_MAGIC executables. .PP .CR fastbind effectively enforces bind restricted and bind immediate. For example, consider an executable linked bind deferred, which calls a function foo() defined in an implicitly loaded library. Before the actual call is made, if it explicitly loads a shared library (using .IR shl_load (3X) with .CR BIND_FIRST ) having a definition for foo(), when foo() is finally called, it will be resolved from the explicitly loaded library. But after running fastbind, the symbol foo() will be resolved from the implicitly loaded library. .SH AUTHOR .CR fastbind was developed by Hewlett-Packard. .SH FILES .PD 0 .TP 35 .C a.out output file .TP .C /usr/lib/dld.sl dynamic loader .TP .C /usr/lib/nls/$LANG/fastbind.cat message catalog .TP .C /var/tmp/ld* temporary files .PD .SH SEE ALSO .SS System Tools: .TP 18 .IR ld(1) invoke the link editor .PP .SS Miscellaneous: .PD 0 .TP 18 .IR a.out(4) assembler, compiler, and linker output .PP .TP 18 .IR dld.sl(5) dynamic loader .PD .SS Texts and Tutorials: .TP 18 .IR "Programming on HP-UX" .PP .\" .\" index@\f4fastbind\f1 \- prepare an incomplete executable for faster program start-up@@@\f3fastbind(1)\f1 .\" index@\f1prepare an incomplete executable for faster program start-up@@@\f3fastbind(1)\f1 .\" index@\f1faster program start-up@@@\f3fastbind(1)\f1 .\" index@\f1program start-up, prepare for faster@@@\f3fastbind(1)\f1 .\" index@\f1incomplete executable, prepare for faster program start-up@@@\f3fastbind(1)\f1 .\" index@\f1executable, prepare for faster program start-up@@@\f3fastbind(1)\f1 .\" index@\f1shared libraries programs, prepare for faster program start-up@@@\f3fastbind(1)\f1 .\" .\" toc@\f3fastbind(1)\f1:\0\0\f4fastbind\f1@@@prepare an incomplete executable for faster program start-up .\" $Header: New Manpage $ .TA f .TH fastmail 1 .SH NAME fastmail \- quick batch mail interface .SH SYNOPSIS .HP .CR fastmail .RC [ \-b .IR bcc-list ] .RC [ \-c .IR cc-list ] .RC [ \-C .IR comments ] .RC [ \-f .IR from-name ] .if n .br -- OK for SGML .RC [ \-F .IR from-addr ] .RC [ \-i .IR in-reply-to ] .RC [ \-r .IR reply-to ] .if t .br -- OK for SGML .RC [ \-R .IR references ] .if n .br -- OK for SGML .RC [ \-s .IR subject ] .IR filename .IR address-list .SH DESCRIPTION The .CR fastmail command is a simple interface to the mail system that allows you to send a message without the overhead of an interactive mailer. It is particularly efficient in batch-processing mail to very large groups of people. .PP All addresses should be full e-mail addresses, .CR sendmail aliases in the .CR /usr/lib/aliases file, or local login names. .SS Options .CR fastmail recognizes the following options: .RS .TP 15 .CI \-b \0bcc-list Include a .CR Bcc:\& header entry. Send blind carbon copies to the comma-separated list of addresses in .IR bcc-list . .TP .CI \-c \0cc-list Include a .CR Cc:\& header entry. Send carbon copies to the comma-separated list of addresses in .IR cc-list . .TP .CI \-C \0comments Include a .CR Comments:\& header entry with the string value .IR comments . .TP .CR \-d Debug. Display information on processing steps. .TP .CI \-f \0from-name Replace the user name in the .CR From: header entry with .IR from-name . .IP If the user is .CR x@y , and the user name is .CR MrX , then the default .CR From: line is: .RS .nf .PP .C "From: x@y (MrX)". .fi .RE .IP The option .CR "-f Joe" changes it to: .RS .nf .PP .C "From: x@y (Joe)" .fi .RE .TP .CR \-F \0from-addr Replace the address in the .CR From:\& header entry with .IR from-addr . In the .CR \-f example above, .CR "\-F a@b" changes the original entry to .RS .nf .PP .C "From: a@b (MrX)" .fi .RE .TP .CI \-i \0in-reply-to Include the .CR In-Reply-To:\& header entry with the string value .IR in-reply-to . This is usually used to identify a message that you are replying to. .TP .CI \-r \0replyto Include the .CR Reply-To: header entry with the single address given in .IR replyto . This is the address where replies will usually be sent, instead of to the address given in the .CR From:\& header entry, very common with mailing lists. .TP .CI \-R \0references Include a .CR References:\& header entry containing the string value .IR references . .TP .CI \-s \0subject Include a .CR Subject:\& header entry containing the value .IR subject . If this option is omitted, the message is sent without a subject entry. .RE .SS Operands .CR fastmail recognizes the following operands: .RS .TP 15 .I address-list A list of one or more blank-separated addresses for the .CR To:\& header line. These are the principal recipients of the message. .TP .I filename Either the name of a file containing the message, or a dash .RC ( _ ) to read from standard input. .RE .SH EXAMPLES .SS A Fully Specified Command This command has every option specified. .RS .nf .PP .C "fastmail \e" .C " -b ""bcc1,bcc2,bcc3,bcc4"" \e" .C " -C ""Just a Comment"" \e" .C " -c ""cc1,cc2,cc3,cc4"" \e" .C " -d \e" .C " -F me@anotherhost.com \e" .C " -f My Name \e" .C " -i ""Your recent message"" \e" .C " -R REF:13579 \e" .C " -r oscar \e" .C " -s ""Testing fastmail"" \e" .C " message-file \e" .C " addr1 addr2 addr3 addr4" .fi .RE .PP The online execution displays the following debug messages: .RS .nf .PP .C "Mailing to addr1,addr2,addr3,addr4 cc1,cc2,cc3,cc4 bcc1,bcc2,bcc" .C "3,bcc4 [via sendmail]" .C "cat /tmp/fastmail.5578 message-file | /usr/sbin/sendmail addr1,a" .C "ddr2,addr3,addr4 cc1,cc2,cc3,cc4 bcc1,bcc2,bcc3,bcc4" .fi .RE .PP The received message has the following relevant header entries: .RS .nf .PP .C "From realsender@mycomputer.myhost.com Tue Oct 22 21:14:04 EDT 1996 .C "Subject: Testing fastmail" .C "From: me@anotherhost.com (My Name)" .C "Reply-To: oscar@mycomputer.myhost.com" .C "To: addr1@mycomputer.myhost.com, addr2@mycomputer.myhost.com," .C " addr3@mycomputer.myhost.com, addr4@mycomputer.myhost.com" .C "Cc: cc1@mycomputer.myhost.com, cc2@mycomputer.myhost.com," .C " cc3@mycomputer.myhost.com, cc4@mycomputer.myhost.com" .C "References: REF:13579" .C "In-Reply-To: Your recent message" .C "Comments: Just a Comment" .fi .RE .PP The .CR Bcc:\& header entry is not transmitted. .SS A Batch Process Suppose you are user .CR "big" on machine .CR "big-machine" and you have a shell script named .CR batch-mail that contains the following lines: .RS .PP .nf .C "# .C "# Batch Mail - batch mailing of a file to a LOT of users .C "# .C "# Usage: batch-mail """" """" .C " " .C "sender_copy=$LOGIN" .C "replyto=The-Mr-Big-list" .C " " .C "fastmail -b $sender_copy -r $replyto -f ""$1"" -s ""$2"" $3 person1" .C "sleep 10" .C "fastmail -r $replyto -f ""$1"" -s ""$2"" $3 person2" .C "sleep 10" .C "fastmail -r $replyto -f ""$1"" -s ""$2"" $3 person3" .C "sleep 10" .C "fastmail -r $replyto -f ""$1"" -s ""$2"" $3 person4" .fi .RE .PP The command: .IP .C "batch-mail ""Mr. Big"" ""Warning to all"" warning.text" .PP would mail a copy of the .CR warning.text file to .CR person1 , .CR person2 , .CR person3 , and .CR person4 , staggered ten seconds apart. .PP .CR "$LOGIN" would also silently receive a copy of the first message in the mail. Each resultant message would include the header lines: .RS .PP .nf .C "From: big@big-machine (Mr. Big)" .C "Subject: Warning to all" .C "Reply-To: The-Mr-Big-list" .fi .RE .SH FILES .TP 30 .PD 0 .C /usr/sbin/sendmail Sendmail transport. .TP .CI /tmp/fastmail. pid Temporary file. .PD .SH AUTHOR .CR fastmail was developed by HP. .SH SEE ALSO elm(1), sendmail(1M). .RS 0 .TP 10 RFC 822 "Standard for the Format of Internet Text Messages" .RE .\" $Header: sh-posix.1,v 76.4 95/11/02 14:15:41 ssa Exp $ .TA s .TH sh-posix 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sh, rsh \- standard and restricted POSIX.2-conformant command shells .SH SYNOPSIS .CR sh .RC [{ \- \(or + }\c .CR aefhikmnprstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [ \-c .IR string ] .IR arg ]...\& .PP .CR rsh .RC [{ \- \(or + }\c .CR aefhikmnprstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [ \-c .IR string ] .RI [ arg ]...\& .SS Remarks This shell is intended to conform to the shell specification of the POSIX.2 .I Shell and Utility standards. Check any standards conformance documents shipped with your system for information on the conformance of this shell to any other standards. .SS List of Subheadings in DESCRIPTION .\" .SS lines under DESCRIPTION (commands are vi/ex) .\" Extract header lines; copy to eof ":g/\.S[SH]/co$: .\" Delete extraneous leading and trailing headings .\" Delete .SS ":.,$s/....//" .\" Form into columns ":.,$!pr -3 -t -s@" .\" Replace pr tabs with blanks ":.,$s/[[:space:]]/ /g" .\" Move into place below. .TS tab(@); l l l . Shell Invocation@Tilde Substitution@Environment Options@Command Substitution@Functions rsh Restrictions@Parameter Substitution@Jobs Definitions@Blank Interpretation@Signals Commands@File Name Generation@Execution Simple Commands@Quoting@Command Reentry Compound Commands@Arithmetic Evaluation@Command Line Editing Special Commands@Prompting@emacs Editing Mode Comments@Conditional Expressions@vi Editing Mode Aliasing@Input/Output .TE .SH DESCRIPTION .CR sh is a command programming language that executes commands read from a terminal or a file. .PP .CR rsh is a restricted version of .CR sh . See the "rsh Restrictions" subsection below. .SS Shell Invocation If the shell is invoked by an .CI exec * () system call and the first character of argument zero (shell parameter .CR 0 ) is dash .RC ( \- ), the shell is assumed to be a login shell and commands are read first from .CR /etc/profile , then from either .CR .profile in the current directory or .CR $HOME/.profile if either file exists, and finally from the file named by performing parameter substitution on the value of the environment parameter .CR ENV , if the file exists. If the .CR \-s option is not present and an .I arg is, a path search is performed on the first .I arg to determine the name of the script to execute. When running .CR sh with .IR arg , the script .I arg must have read permission and any .CR setuid and .CR setgid settings will be ignored. Commands are read as described below. .PP Shell output, except for the output of some of the commands listed in the "Special Commands" subsection, is written to standard error (file descriptor 2). .SS Options The following options are interpreted by the shell when it is invoked. .TP 15 .CI \-c \0string Read commands from .IR string . .TP .CR \-i If .CR \-i is present or if the shell input and output are attached to a terminal (as reported by .CR tty() ), the shell is interactive. In this case .CR SIGTERM is ignored (so that .CR "kill 0" does not kill an interactive shell) and .CR SIGINT is caught and ignored (so that .CR wait is interruptible). In all cases, .CR SIGQUIT is ignored by the shell. See .IR signal (5). .TP .CR \-r The shell is a restricted shell. .TP .CR \-s If .CR \-s is present or if no arguments remain, commands are read from the standard input. .PP The remaining options and arguments are described under the .CR set command in the "Special Commands" subsection. .SS rsh Restrictions .CR rsh is used to set up login names and execution environments where capabilities are more controlled than those of the standard shell. The actions of .CR rsh are identical to those of .CR sh , except that the following are forbidden: .RS .TP 3 .PD 0 \(bu Changing directory (see the .CR cd special command and .IR cd (1)) .TP \(bu Setting the value of .CR SHELL , .CR ENV , or .CR PATH .TP \(bu Specifying path or command names containing .CR / .TP \(bu Redirecting output .RC ( > , .CR >| , .CR <> , and .CR >> ) .PD .RE .PP The restrictions above are enforced after the .CR .profile and .CR ENV files are interpreted. .PP When a command to be executed is found to be a shell procedure, .CR rsh invokes .CR sh to execute it. Thus, the end-user is provided with shell procedures accessible to the full power of the standard shell, while being restricted to a limited menu of commands. This scheme assumes that the end-user does not have write and execute permissions in the same directory. .PP These rules effectively give the writer of the .CR .profile file complete control over user actions, by performing guaranteed set-up actions and leaving the user in an appropriate directory (probably not the login directory). .PP The system administrator often sets up a directory of commands (usually .CR /usr/rbin ) that can be safely invoked by .CR rsh . HP-UX systems provide a restricted editor .CR red (see .IR ed (1)), suitable for restricted users. .SS Definitions .TP 20 .B metacharacter One of the following characters: .IP .CR "; & ( ) | < >" \0newline\0space\0tab .TP .B blank A tab or a space. .TP .B identifier A sequence of letters, digits, or underscores starting with a letter or underscore. Identifiers are used as names for .BR functions and .BR "named parameters" . .TP .B word A sequence of .B characters separated by one or more nonquoted .BR metacharacters . .TP .BR command A sequence of characters in the syntax of the shell language. The shell reads each command and carries out the desired action, either directly or by invoking separate utilities. .TP .B "special command" A command that is carried out by the shell without creating a separate process. Except for documented side effects, most special commands can be implemented as separate utilities. .TP .CR # Comment delimiter. A word beginning with .CR # and all following characters up to a newline are ignored. .TP .B parameter An .BR identifier , a decimal number, or one of the characters .CR ! , .CR # , .CR $ , .CR * , .CR \- , .CR ? , .CR @ , and .CR _ . See the "Parameter Substitution" subsection. .TP .B "named parameter" A .B parameter that can be assigned a value. See the "Parameter Substitution" subsection. .TP .B variable A .BR parameter . .TP .B "environment variable" A .BR parameter that is known outside the local shell, usually by means of the .CR export special command. .SS Commands A command can be a simple command that executes an executable file, a special command that executes within the shell, or a compound command that provides flow of control for groups of simple, special, and compound commands. .SS Simple Commands A simple command is a sequence of blank-separated words that may be preceded by a parameter assignment list. (See the "Environment" subsection). The first word specifies the name of the command to be executed. Except as specified below, the remaining words are passed as arguments to the invoked command. The command name is passed as argument .CR 0 (see .IR exec (2)). The .I value of a simple-command is its exit status if it terminates normally, or .CI 128+ errorstatus if it terminates abnormally (see .IR signal (5) for a list of .I errorstatus values). .PP A .B pipeline is a sequence of one or more commands separated by a bar .RC ( | ) and optionally preceded by an exclamation mark .RC ( ! ). The standard output of each command but the last is connected by a pipe (see .IR pipe (2)) to the standard input of the next command. Each command is run as a separate process; the shell waits for the last command to terminate. If .CR !\& does not precede the pipeline, the exit status of the pipeline is the exit status of the last command in the pipeline. Otherwise, the exit status of the pipeline is the logical negation of the exit status of the last command in the pipeline. .PP A .I list is a sequence of one or more pipelines separated by .CR ; , .CR & , .CR && , or .CR || , and optionally terminated by .CR ; , .CR & , or .CR |& . .RS .TP .CR ;\& Causes sequential execution of the preceding pipeline. An arbitrary number of newlines can appear in a .I list, instead of semicolons, to delimit commands. .TP .CR & Causes asynchronous execution of the preceding pipeline (that is, the shell does not wait for that pipeline to finish). .TP .CR |& Causes asynchronous execution of the preceding command or pipeline with a two-way pipe established to the parent shell. The standard input and output of the spawned command can be written to and read from by the parent shell using the .CR \-p option of the special commands .CR read and .CR print . .TP .CR && Causes the .I list following it to be executed only if the preceding pipeline returns a zero value. .TP .CR || Causes the .I list following it to be executed only if the preceding pipeline returns a nonzero value. .RE .PP Of these five symbols, .CR ; , .CR & , and .CR |& have equal precedence, which is lower than that of .CR && and .CR || . The symbols .CR && and .CR || also have equal precedence. .SS Compound Commands Unless otherwise stated, the value returned by a compound command is that of the last simple command executed in the compound command. The .CR ;\& segment separator can be replaced by one or more newlines. .PP The following keywords are recognized only as the first word of a command and when not quoted: .nf .RS .IP .C "! } elif for then" .C "[[ case else function time" .C "]] do esac if until" .C "{ done fi select while" .fi .RE .PP A compound command is one of the following. .PP .ne 3v .CR case \f2\0word\c .CR \0in \0[\|[ ; ]\0[ ( ]\c .IC \0pattern\0\f1[ | \0pattern\f1]... ) \0list\0\c .CR ;; ]...\0 ;\0esac .IP Execute the .I list associated with the first .I pattern that matches .IR word . The form of the patterns is identical to that used for file name generation (see the "File Name Generation" subsection). The .CR ;;\& case terminator cannot be replaced by newlines. .PP .ne 3v .CI for \0identifier\f1\0[ in \0word\f1\0...]\0\c .CR ;\0do \0\f2list\0 ;\0done .IP Set .I identifier to each .I word in sequence and execute the .CR do .IR list . If .CR in .IR word .RI ...\& is omitted, set .I identifier to each set positional parameter instead. See the "Parameter Substitution" subsection. Execution ends when there are no more positional parameters or words in the list. .PP .ne 4v .CI function \0identifier\0 { \0list\0 ;\0} .br .IC identifier \0()\0{ \0list\0 ;\0} .IP Define a function named by .IR identifier . A function is called by executing its identifier as a command. The body of the function is the .I list of commands between .CR { and .CR } . See the "Functions" subsection. .PP .ne 3v .CI if \0list\0 ;\0then \0list\0 ; \0\f1[\c .CI elif \0list\0 ;\0then \0list\0 ; \f1]...\&\0[\c .CI else \0list\0 ; \f1]\0 fi .IP Execute the .CR if .I list and, if its exit status is zero, execute the first .CR then .IR list . Otherwise, execute the .CR elif .I list (if any) and, if its exit status is zero, execute the next .CR then .IR list . Failing that, execute the .CR else .I list (if any). If no .CR else .I list or .CR then .I list is executed, .CR if returns a zero exit status. .PP .ne 3v .CI select \0identifier\0\f1[ in \0word\f1\0...\&]\0 ;\0do \0list\0\c .CI ;\0done .IP Print the set of .IR word s on standard error (file descriptor 2), each preceded by a number. If .CI in .IR word .RI ...\& is omitted, print the positional parameters instead (see the "Parameter Substitution" subsection). Print the .CR PS3 prompt and read a line from standard input into the parameter .CR REPLY . If this line consists of the number of one of the listed .IR word s, set .I identifier to the corresponding .IR word , execute .IR list , and repeat the .CR PS3 prompt. If the line is empty, print the selection list again, and repeat the .CR PS3 prompt. Otherwise, set .I identifier to null, execute .IR list , and repeat the .CR PS3 prompt. The select loop repeats until a .CR break special command or end-of-file is encountered. .PP .ne 3v .CI time \0pipeline .IP Execute the .I pipeline and print the elapsed time, the user time, and the system time on standard error. See also .IR time (1). .PP .ne 3v .CI "until\0" list "\0;\0do\0" list "\0;\0done" .IP Execute the .CR until .IR list . If the exit status of the last command in the list is nonzero, execute the .CR do .IR list and execute the .CR until .IR list again. When the exit status of the last command in the .CR until .I list is zero, terminate the loop. If no commands in the .CR do .I list are executed, .CR until returns a zero exit status. .PP .ne 3v .CI "while\0" list "\0;\0do\0" list "\0;\0done" .IP Execute the .CR while .IR list . If the exit status of the last command in the list is zero, execute the .CR do .IR list and execute the .CR while .IR list again. When the exit status of the last command in the .CR while .I list is nonzero, terminate the loop. If no commands in the .CR do .I list are executed, .CR while returns a nonzero exit status. .PP .ne 3v .CI ( "\0list\0" ) .IP Execute .I list in a separate environment. If two adjacent open parentheses are needed for nesting, a space must be inserted between them to avoid arithmetic evaluation. .PP .ne 3v .CI { "\0list\0" ";\0}" .IP Execute .IR list , but not in a separate environment. Note that .CR { is a keyword and requires a trailing blank to be recognized. .PP .ne 3v .CI [[ "\0expression\0" ]] .IP Evaluate .I expression and return a zero exit status when .I expression is true. See the "Conditional Expressions" subsection for a description of .IR expression . Note that .CR [[ and .CR ]] are keywords and require blanks between them and .IR expression . .SS Special Commands Special commands are simple commands that are executed in the shell process. They permit input/output redirection. Unless otherwise indicated, file descriptor 1 (standard output) is the default output location and the exit status, when there are no syntax errors, is zero. .PP Commands that are marked with \(dg or \(dg\(dg are treated specially in the following ways: .RS .TP 3 .PD 0 1. Variable assignment lists preceding the command remain in effect when the command completes. .TP 2. I/O redirections are processed after variable assignments. .TP 3. Errors cause a script that contains them to abort. .TP 4. Words following a command preceded by \(dg\(dg that are in the format of a variable assignment are expanded with the same rules as a variable assignment. This means that tilde substitution is performed after the .CR = sign and word-splitting and file-name generation are not performed. .PD .RE .PP .ne 3v \(dg .CR : \0[\f2arg\f1]...\& .IP (colon)\0 Only expand parameters. A zero exit status is returned. .PP .ne 3v \(dg .CI . \0file\f1\0[\f2arg\f1]...\& .IP (period)\0 Read and execute commands from .I file and return. The commands are executed in the current shell environment. The search path specified by .CR PATH is used to find the directory containing .IR file . If any arguments .I arg are given, they become the positional parameters. Otherwise, the positional parameters are unchanged. The exit status is the exit status of the last command executed. .PP .ne 3v \(dg\(dg .CR alias \0[ \-tx ]\0[\f2name\f1[\c .CI = value\f1]\|]...\& .IP With .IC name = value specified, define .I name as an alias and assign it the value .IR value . A trailing space in .I value causes the next word to be checked for alias substitution. .IP With .IC name = value omitted, print the list of aliases in the form .IC name = value on standard output. .IP With .I name specified without .CI = value\f1, print the specified alias. .IP With .CR \-t , set tracked aliases. The value of a tracked alias is the full path name corresponding to the given .IR name . The value of a tracked alias becomes undefined when the value of .CR PATH is reset, but the alias remains tracked. With .IC name = value omitted, print the list of tracked aliases in the form .IC name = pathname on standard output. .IP With .CR \-x , set exported aliases. An exported alias is defined across subshell environments. With .IC name = value omitted, print the list of exported aliases in the form .IC name = value on standard output. .IP Alias returns true unless a .I name is given for which no alias has been defined. .PP .ne 3v .CR bg \0[\f2job\f1]...\& .IP Put the specified .I jobs into the background. The current job is put in the background if .I job is unspecified. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v \(dg .CR break \0[\f2n\f1] .IP Exit from the enclosing .CR for , .CR select , .CR until , or .CR while loop, if any. If .I n is specified, exit from .I n levels. .PP .ne 4v .CR cd \0[ \-L \(or \-P ]\0[\f2arg\f1] .br .CI cd \0old\0new .IP In the first form, change the current working directory .RC ( PWD ) to .IR arg . If .I arg is .CR \- , the directory is changed to the previous directory .RC ( OLDPWD ). .IP With .CR \-L (default), preserve logical naming when treating symbolic links. .CR "cd \-L ..\&" moves the current directory one path component closer to the root directory. .IP With .CR \-P , preserve the physical path when treating symbolic links. .CR "cd \-P ..\&" changes the working directory to the actual parent directory of the current directory. .IP The shell parameter .CR HOME is the default .IR arg . The parameter .CR PWD is set to the current directory. .IP The shell parameter .CR CDPATH defines the search path for the directory containing .IR arg . Alternative directory names are separated by a colon .RC ( : ). If .CR CDPATH is null or undefined, the default value is the current directory. Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If .I arg begins with a .CR / , the search path is not used. Otherwise, each directory in the path is searched for .IR arg . See also .IR cd (1). .IP The second form of .CR cd substitutes the string .I new for the string .I old in the current directory name, .CR PWD , and tries to change to this new directory. .PP .ne 3v .CR command \0[\f2arg\f1]...\& .IP Treat .I arg as a command, but disable function lookup on .IR arg . See .IR command (1) for usage and description. .PP .ne 3v \(dg .CR continue \0[\f2n\f1] .IP Resume the next iteration of the enclosing .CR for , .CR select , .CR until , or .CR while loop. If .I n is specified, resume at the .IR n th enclosing loop. .PP .ne 3v .CR echo \0[\f2arg\f1]...\& .IP Print .I arg on standard output. See .IR echo (1) for usage and description. See also the .CR print special command. .PP .ne 3v \(dg .CR eval \0[\f2arg\f1]...\& .IP Read the arguments as input to the shell and execute the resulting commands. Allows parameter substitution for keywords and characters that would otherwise be unrecognized in the resulting commands. .PP .ne 3v \(dg .CR exec \0[\f2arg\f1]...\& .IP Parameter assignments remain in effect after the command completes. If .I arg is given, execute the command specified by the arguments in place of this shell without creating a new process. Input/output arguments may appear and affect the current process. If no arguments are given, modify file descriptors as prescribed by the input/output redirection list. In this case, any file descriptor numbers greater than 2 that are opened with this mechanism are closed when another program is invoked. .PP .ne 3v \(dg .CR exit \0[\f2n\f1] .IP Exit from the shell with the exit status specified by .IR n . If .I n is omitted, the exit status is that of the last command executed. An end-of-file also causes the shell to exit, except when a shell has the .CR ignoreeof option set. (See the .CR set special command.) .PP .ne 4v \(dg\(dg .CR export \0[\f2name\f1[ = \f2value\f1]\|]...\& .br \(dg\(dg .CR export\0\-p .IP Mark the given variable .IR name s for automatic export to the environment of subsequently executed commands. Optionally, assign values to the variables. .IP With .CR \-p , write the names and values of all exported variables to standard output, in a format with the proper use of quoting, so that it is suitable for re-input to the shell as commands that achieve the same exporting results. .PP .ne 6v .CR fc \0[ \-r ]\0[ \-e \0\f2ename\f1]\0[\f2first\f1\0[\f2last\f1]\|] .br .CR fc\0\-l \0[ \-nr ]\0[\f2first\f1\0[\f2last\f1]\|] .br .CR fc\0\-s \0[\f2old\f1 = \f2new\f1]\0[\f2first] .br .CR fc\0\-e\0\- \0[\f2old\f1 = \f2new\f1]\0[\f2command\f1] .IP List, or edit and reexecute, commands previously entered to an interactive shell. A range of commands from .I first to .I last is selected from the last .CR HISTSIZE commands typed at the terminal. The arguments .I first and .I last can be specified as a number or string. A given string is used to locate the most recent command. A negative number is used to offset the current command number. .IP With .CR \-l , list the commands on standard output. Without .CR \-l , invoke the editor program .I ename on a file containing these keyboard commands. If .I ename is not supplied, the value of the parameter .CR FCEDIT (default .CR /usr/bin/ed ) is used as the editor. Once editing has ended, the commands (if any) are executed. If .I last is omitted, only the command specified by .I first is used. If .I first is not specified, the default is the previous command for editing and \(mi16 for listing. .IP With .CR \-r , reverse the order of the commands. .IP With .CR \-n , suppress command numbers when listing. .IP With .CR \-s , reexecute the command without invoking an editor. .IP The .IC old = new argument replaces the first occurrence of string .IC old in the command to be reexecuted by the string .IR new . .PP .ne 3v .CR fg \0[\f2job\f1]...\& .IP Bring each .I job into the foreground in the order specified. If no .I job is specified, bring the current job into the foreground. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v .CR getopts \0\f2optstring\0name\f1\0[\f2arg\f1]...\& .IP Parse the argument list, or the positional parameters if no arguments, for valid options. On each execution, return the next option in .IR name . See .IR getopts (1) for usage and description. .IP An option begins with a .CR + or a .CR \- . An argument not beginning with .CR + or .CR \- , or the argument .CR \-\- , ends the options. .I optstring contains the letters that .CR getopts recognizes. If a letter is followed by a .CR : , that option is expected to have an argument. The options can be separated from the argument by blanks. .IP For an option specified as .CI \- letter\f1, .I name is set to .IR letter . For an option specified as .CI + letter\f1, .I name is set to .CI + letter\f1. The index of the next .I arg is stored in .CR OPTIND . The option argument, if any, is stored in .CR OPTARG . If no option argument is found, or the option found does not take an argument, .CR OPTARG is unset. .IP A leading .CR :\& in .I optstring causes .CR getopts to store the letter of an invalid option in .CR OPTARG , and to set .I name to .CR ?\& for an unknown option and to .CR :\& when a required option argument is missing. Otherwise, .CR getopts prints an error message. The exit status is nonzero when there are no more options. .PP .ne 4v .CR hash \0[\f2utility\f1]...\& .br .CR hash\0\-r .IP Affect the way the current shell environment remembers the locations of utilities. With .IR utility , add utility locations to a list of remembered locations. With no arguments, print the contents of the list. With .CR \-r , forget all previously remembered utility locations. .PP .ne 3v .CR jobs \0[ \-lnp ]\0[\f2job\f1]...\& .IP List information about each given job, or all active jobs if .I job is not specified. With .CR \-l , list process IDs in addition to the normal information. With .CR \-n , display only jobs that have stopped or exited since last notified. With .CR \-p , list only the process group. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 5v .CR kill \0[ \-s \0\f2signal\f1]\0\f2process\f1\0...\& .br .CR kill\0\-l .br .CR kill \0[ \- \f2signal\f1]\0\f2process\f1\0...\& .IP Send either signal 15 .RC ( SIGTERM , terminate) or the specified .I signal to the specified jobs or processes. See .IR kill (1) for usage and description. .IP With .CR \-l , list the signal names and numbers. .PP .ne 4v .CI let \0arg\f1\0... .br .CI (( \0arg\f1\0... )) .IP Evaluate each .I arg as a separate arithmetic expression. See the "Arithmetic Evaluation" subsection for a description of arithmetic expression evaluation. The exit status is 0 if the value of the last expression is nonzero, and 1 otherwise. .PP .ne 3v \(dg .CR newgrp \0[ \- ]\0[\f2group\f1] .IP Replace the current shell with a new one having .I group as the user's group. The default group is the user's login group. With .CR \- , the user's .CR .profile and .CR $ENV files are also executed. See .IR newgrp (1) for usage and description. Equivalent to .CI "exec\0newgrp" "\0arg\0\f1...." .PP .ne 3v .CR print \0[ \-nprRsu [\f2n\f1]\|]\0[\f2arg\f1]...\& .IP The shell output mechanism. With no options or with option .CR \- or .CR \-\- , print the arguments on standard output as described in .IR echo (1). See also .IR printf (1). .IP With .CR \-n , do not add a newline character to the output. .IP With .CR \-p , write the arguments onto the pipe of the process spawned with .CR |& instead of standard output. .IP With .CR \-R or .CR \-r (raw mode), ignore the escape conventions of .CR echo . With .CR \-R , print all subsequent arguments and options other than .CR \-n . .IP With .CR \-s , write the arguments into the history file instead of to standard output. .IP With .CR \-u , specify a one-digit file descriptor unit number .I n on which the output will be placed. The default is .CR 1 (standard output). .PP .ne 3v .CR pwd \0[ \-L \(or \-P ] .IP Print the name of the current working directory (equivalent to .CR "print\0\-r\0\-\0$PWD" ). With .CR \-L (the default), preserve the logical meaning of the current directory. With .CR \-P , preserve the physical meaning of the current directory if it is a symbolic link. See also the .CR cd special command, .IR cd (1), .IR ln (1), and .IR pwd (1). .PP .ne 3v .CR read \0[ \-prsu [\f2n\f1]\|]\0[\f2name\f1 ? \f2prompt\f1]\0[\f2name\f1]...\& .IP The shell input mechanism. Read one line (by default, from standard input) and break it up into words using the characters in .CR IFS as separators. The first word is assigned to the first .IR name , the second word to the second .IR name , and so on; the remaining words are assigned to the last .IR name . See also .IR read (1). The return code is .CR 0 , unless an end-of-file is encountered. .IP With .CR \-p , take the input line from the input pipe of a process spawned by the shell using .CR |& . An end-of-file with .CR \-p causes cleanup for this process so that another process can be spawned. .IP With .CR \-r (raw mode), a .CR \e at the end of a line does not signify line continuation. .IP With .CR \-s , save the input as a command in the history file. .IP With .CR \-u , specify a one-digit file descriptor unit to read from. The file descriptor can be opened with the .CR exec special command. The default value of .I n is .CR 0 (standard input). If .IR name is omitted, .CR REPLY is used as the default .IR name . .IP If the first argument contains a .CR ? , the remainder of the argument is used as a .I prompt when the shell is interactive. .IP If the given file descriptor is open for writing and is a terminal device, the prompt is placed on that unit. Otherwise, the prompt is issued on file descriptor 2 (standard error). .PP .ne 4v \(dg\(dg .CR readonly \0[\f2name\f1[ = \f2value\f1]\|]...\& .br \(dg\(dg .CR readonly\0\-p .IP Mark the given .IR name s read only. These names cannot be changed by subsequent assignment. .IP With .CR \-p , write the names and values of all read-only variables to standard output in a format with the proper use of quoting so that it is suitable for re-input to the shell as commands that achieve the same attribute-setting results. .PP .ne 3v \(dg .CR return \0[\f2n\f1] .IP Cause a shell function to return to the invoking script with the return status specified by .IR n . If .I n is omitted, the return status is that of the last command executed. Only the low 8 bits of .I n (decimal 0 to 255) are passed back to the caller. If .CR return is invoked while not in a function or a .CR .\& script (see the .CR .\& special command), it has the same effect as an .CR exit command. .PP .ne 3v .CR set .RC [{ \- \(or + }\c .CR abCefhkmnopstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [{ \- \(or + } A .IR name ]\0[ arg ]...\& .IP Set .RC ( \- ) or clear .RC ( + ) execution options or perform array assignments .RC ( \-A ,\ +A ). All options except .CR \-A and .CR +A can be supplied in a shell invocation (see the SYNOPSIS section and the "Shell Invocation" subsection). .IP Using .CR + instead of .CR \- before an option causes the option to be turned off. These options can also be used when invoking the shell. The current list of set single-letter options is contained in the shell variable .CR \- . It can be examined with the command .CR "echo $-" . .IP The .CR \- and .CR + options can be intermixed in the same command, except that there can be only one .CR \-A or .CR +A option. .IP Unless .CR \-A or .CR +A is specified, the remaining .I arg arguments are assigned consecutively to the positional parameters .CR 1 , .CR 2 ,\0.... .IP The .CR set command with neither arguments nor options displays the names and values of all shell parameters on standard output. See also .IR env (1). .IP The options are defined as follows. .RS .TP .CR \-A Array assignment. Unset the variable .I name and assign values sequentially from the list .IR arg . With .CR \+A , do not unset the variable .I name first. .TP .CR \-a Automatically export subsequently defined parameters. .TP .CR \-b Cause the shell to notify the user asynchronously of background jobs as they are completed. When the shell notifies the user that a job has been completed, it can remove the job's process ID from the list of those known in the current shell execution environment. .TP .CR \-C Prevent redirection .CR > from truncating existing files. Requires .CR >| to truncate a file when turned on. .TP .CR \-e Execute the .CR ERR trap, if set, and exit .I if a command has a nonzero exit status, and is not part of the compound list following a .CR if , .CR until , or .CR while keyword, and is not part of an AND or OR list, and is not a pipeline preceded by the .CR !\& reserved word. This mode is disabled while reading profiles. .TP .CR \-f Disable file name generation. .TP .CR \-h Specify that each command whose name is an .I identifier becomes a tracked alias when first encountered. .TP .CR \-k Place all parameter assignment arguments (not just those that precede the command name) into the environment for a command. .TP .CR \-m Run background jobs in a separate process group and print a line upon completion. The exit status of background jobs is reported in a completion message. This option is turned on automatically for interactive shells. .TP .CR \-n Read commands and check them for syntax errors, but do not execute them. The .CR \-n option is ignored for interactive shells. .TP .ne 5v .CR \-o Set an .I option argument from the following list. Repeat the .CR \-o option to specify additional .I option arguments. .RS .TP 15 .PD 0 .CR allexport Same as .CR \-a . .TP .CR bgnice Run all background jobs at a lower priority. .TP .CR errexit Same as .CR \-e . .TP .CR emacs Use a .CR emacs -style inline editor for command entry. .TP .CR gmacs Use a .CR gmacs -style inline editor for command entry. .TP .CR ignoreeof Do not exit from the shell on end-of-file .RI ( eof as defined by .CR stty ; default is .CR ^D ). The .CR exit special command must be used. .TP .CR keyword Same as .CR \-k . .TP .CR markdirs Append a trailing .CR / to all directory names resulting from file name generation. .TP .CR monitor Same as .CR \-m . .TP .CR noclobber Same as .CR \-C . .TP .CR noexec Same as .CR \-n . .TP .CR noglob Same as .CR \-f . .TP .CR nolog Do not save function definitions in history file. .TP .CR notify Same as .CR \-b . .TP .CR nounset Same as .CR \-u . .TP .CR privileged Same as .CR \-p . .TP .CR verbose Same as .CR \-v . .TP .CR trackall Same as .CR \-h . .TP .CR vi Use a .CR vi -style inline editor for command entry. .TP .CR viraw Process each character as it is typed in .CR vi mode. .TP .CR xtrace Same as .CR \-x . .PD .RE .TP .CR \-p Disable processing of the .CR $HOME/.profile file and uses the file .CR /etc/suid_profile instead of the .CR ENV file. This mode is on whenever the effective user ID (group ID) is not equal to the real user ID (group ID). Turning this off causes the effective user ID and group ID to be set to the real user ID and group ID. .TP .CR \-s Sort the positional parameters. .TP .CR \-t Exit after reading and executing one command. .TP .CR \-u Treat unset parameters as an error when substituting. .TP .CR \-v Print shell input lines as they are read. .TP .CR \-x Print commands and their arguments as they are executed. .TP .CR \- Turn off .CR \-x and .CR \-v options and stop examining arguments for options. .TP .CR \-\- Do not change any of the options; useful in setting parameter .CR 1 to a value beginning with .CR \- . If no arguments follow this option, the positional parameters are unset. .RE .PP .ne 3v \(dg .CR shift "\0[\f2n\f1]" .IP Rename the positional parameters from .IC n +1 \f1\0...\& to .CR 1 \0.... The default value of .I n is .CR 1 . .I n can be any arithmetic expression that evaluates to a nonnegative number less than or equal to .CR $# . .PP .ne 3v .CR test \0[\f2expr\f1] .IP Evaluate conditional expression .IR expr . See .IR test (1) for usage and description. The arithmetic comparison operators are not restricted to integers. They allow any arithmetic expression. The following additional primitive expressions are allowed: .RS .TP 20 .PD 0 .CI \-L \0file True if .I file is a symbolic link. .TP .CI \-e \0file True if .I file exists. .TP .IC file1\0 \-nt \0file2 True if .I file1 is newer than .IR file2 . .TP .IC file1\0 \-ot \0file2 True if .I file1 is older than .IR file2 . .TP .IC file1\0 \-ef \0file2 True if .I file1 has the same device and i-node number as .IR file2 . .PD .RE .PP .ne 3v \(dg .CR times .IP Print the accumulated user and system times for the shell and for processes run from the shell. .PP .ne 3v \(dg .CR trap \0[\f2arg\f1]\0[\f2sig\f1]...\& .IP Set .I arg as a command that is read and executed when the shell receives a .IR sig signal. (Note that .I arg is scanned once when the trap is set and once when the trap is taken.) Each .I sig can be given as the number or name of a signal. Letter case is ignored. For example, .CR 3 , .CR QUIT , .CR quit , and .CR SIGQUIT all specify the same signal. Use .CR "kill \-l" to get a list of signals. .IP Trap commands are executed in signal number order. Any attempt to set a trap on a signal that was ignored upon entering the current shell is ineffective. .IP If .I arg is .CR \- (or if .I arg is omitted and the first .I sig is numeric), reset all traps for each .I sig to their original values. .IP If .I arg is the null string .RC ( '' or \&\c .C """""\c" ), each .I sig is ignored by the shell and by the commands it invokes. .IP If .I sig is .CR DEBUG , then .I arg is executed after each command. If .I sig is .CR ERR , .I arg is executed whenever a command has a nonzero exit code. If .I sig is .CR 0 or .CR EXIT and the .CR trap statement is executed inside the body of a function, the command .I arg is executed after the function completes. If .I sig is .CR 0 or .CR EXIT for a .CR trap set outside any function, the command .I arg is executed on exit from the shell. .IP With no arguments, print a list of commands associated with each signal name. .PP .ne 4v \(dg\(dg .CR typeset \0[{ \- \(or + }\c .CR LRZfilrtux [\f2n\f1]\|]\0[\f2name\f1[ = \f2value\f1]\|]... .br \(dg\(dg .IC name = value .RC [\f2name = \f2value\f1]...\& .IP Assign types and a value to a local named parameter .IR name . See also the .CR export special command. Parameter assignments remain in effect after the command completes. When invoked inside a function, create a new instance of the parameter .IR name . The parameter value and type are restored when the function completes. .IP The following list of attributes can be specified. Use .CR \+ instead of .CR \- to turn the options off. .RS .TP .CR \-L Left justify and remove leading blanks from .IR value . If .I n is nonzero, it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. When .I name is assigned, the value is filled on the right with blanks or truncated, if necessary, to fit into the field. Leading zeros are removed if the .CR \-Z option is also set. The .CR \-R option is turned off. Flagged as .CI leftjust \0n\f1. .TP .CR \-R Right justify and fill with leading blanks. If .I n is nonzero, it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. The field is left-filled with blanks or truncated from the end if the parameter is reassigned. The .CR \-L option is turned off. Flagged as .CI rightjust \0n\f1. .TP .CR \-Z Right justify and fill with leading zeros if the first nonblank character is a digit and the .CR \-L option has not been set. If .I n is nonzero it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. Flagged as .CI zerofill \0n\f1 plus the flag for .CR \-L or .CR \-R . .TP .CR \-f Cause .I name to refer to function names rather than parameter names. No assignments can be made to the .I name declared with the .CR typeset statement. The only other valid options are .CR \-t (which turns on execution tracing for this function) and .CR \-x (which allows the function to remain in effect across shell procedures executed in the same process environment). Flagged as .CR function . .TP .CR \-i Parameter is an integer. This makes arithmetic faster. If .I n is nonzero it defines the output arithmetic base; otherwise, the first assignment determines the output base. Flagged as .CR integer \0[ base \0\f2n\f1]. .TP .CR \-l Convert all uppercase characters to lowercase. The uppercase .CR \-u option is turned off. Flagged as .CR lowercase . .TP .CR \-r Mark any given .I name as "read only". The name cannot be changed by subsequent assignment. Flagged as .CR readonly . .TP .CR \-t Tag the named parameters. Tags are user-definable and have no special meaning to the shell. Flagged as .CR tagged . .TP .CR \-u Convert all lowercase characters to uppercase characters. The lowercase .CR \-l option is turned off. Flagged as .CR uppercase . .TP .CR \-x Mark any given .I name for automatic export to the environment of subsequently executed commands. Flagged as .CR export . .RE .IP .CR typeset alone displays a list of parameter names, prefixed by any flags specified above. .IP .CR "typeset \-" displays the parameter names followed by their values. Specify one or more of the option letters to restrict the list. Some options are incompatible with others. .IP .CR "typeset +" displays the parameter names alone. Specify one or more of the option letters to restrict the list. Some options are incompatible with others. .PP .ne 3v .CR ulimit \0[ \-HSacdfnst ]\0[\f2limit\f1] .IP Set or display a resource limit. The limit for a specified resource is set when .IR limit is specified. The value of .IR limit can be a number in the unit specified with each resource, or the keyword .CR unlimited . .IP The .CR \-H and .CR \-S flags specify whether the hard limit or the soft limit is set for the given resource. A hard limit cannot be increased once it is set. A soft limit can be increased up to the hard limit. If neither .CR \-H nor .CR \-S is specified, the limit applies to both. The current resource limit is printed when .IR limit is omitted. In this case, the soft limit is printed unless .CR \-H is specified. When more than one resource is specified, the limit name and unit are printed before the value. .IP If no option is given, .CR \-f is assumed. .RS .TP .PD 0 .CR \-a List all of the current resource limits. .TP .CR \-c The number of 512-byte blocks in the size of core dumps. .TP .CR \-d The number of kilobytes in the size of the data area. .TP .CR \-f The number of 512-byte blocks in files written by child processes (files of any size can be read). .TP .CR \-n The number of file descriptors. .TP .CR \-s The number of kilobytes in the size of the stack area. .TP .CR \-t The number of seconds to be used by each process. .PD .RE .PP .ne 3v .CR umask \0[ \-S ]\0[\f2mask\f1] .IP Set the user file-creation mask .IR mask . .I mask can be either an octal number or a symbolic value as described in .IR umask (1). A symbolic value shows permissions that are unmasked. An octal value shows permissions that are masked off. .IP Without .I mask , print the current value of the mask. With .CR \-S , print the value in symbolic format. Without .CR \-S , print the value as an octal number. The output from either form can be used as the .I mask of a subsequent invocation of .CR umask . .PP .ne 4v .CI unalias \0name\f1\0...\& .br .CR unalias\0\-a .IP Remove each .IR name from the alias list. With .CR \-a , remove all .CR alias definitions from the current shell execution environment. .PP .ne 3v .CR unset \0[ \-fv ]\0\f2name\f1\0...\& .IP Remove the named shell parameters from the parameter list. Their values and attributes are erased. Read-only variables cannot be unset. With .CR \-f , .IR name s refer to function names. With .CR \-v , .IR name s refer to variable names. Unsetting .CR _ , .CR ERRNO , .CR LINENO , .CR MAILCHECK , .CR OPTARG , .CR OPTIND , .CR RANDOM , .CR SECONDS , and .CR TMOUT removes their special meaning, even if they are subsequently assigned to. .PP .ne 3v \(dg .CR wait \0[\f2job\f1] .IP Wait for the specified .I job to terminate or stop, and report its status. This status becomes the return code for the .CR wait command. Without .I job , wait for all currently active child processes to terminate or stop. The termination status returned is that of the last process. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v .CR whence \0[ \-pv ]\0\f2name\f1\0...\& .IP For each .IR name , indicate how it would be interpreted if used as a command name. With .CR \-v , produce a more verbose report. With .CR \-p do a path search for .IR name , disregarding any use as an alias, a function, or a reserved word. .SS Comments A .I word beginning with .CR # causes that word and all the following characters up to a newline to be ignored. .SS Aliasing The first word of each command is replaced by the text of an .CR alias , if an .CR alias for this word has been defined. An .CR alias name consists of any number of characters excluding metacharacters, quoting characters, file expansion characters, parameter and command substitution characters, and =. The replacement string can contain any valid shell script, including the metacharacters listed above. The first word of each command in the replaced text, other than any that are in the process of being replaced, will be tested for additional aliases. If the last character of the alias value is a .IR blank , the word following the alias is also checked for alias substitution. Aliases can be used to redefine special commands, but cannot be used to redefine the keywords listed in the "Compound Commands" subsection. Aliases can be created, listed, and exported with the .CR alias command and can be removed with the .CR unalias command. Exported aliases remain in effect for subshells but must be reinitialized for separate invocations of the shell (see the "Shell Invocation" subsection). .PP Aliasing is performed when scripts are read, not while they are executed. Therefore, for it to take effect, an .CR alias must be executed before the command referring to the alias is read. .PP Aliases are frequently used as a shorthand for full path names. An option to the aliasing facility allows the value of the alias to be automatically set to the full path name of the corresponding command. These aliases are called .I tracked aliases. The value of a .I tracked alias is defined the first time the identifier is read and becomes undefined each time the .CR PATH variable is reset. These aliases remain .I tracked so that the next reference will redefine the value. Several tracked aliases are compiled into the shell. The .CR \-h option of the .CR set command converts each command name that is an .I identifier into a tracked alias. .PP The following .I exported aliases are compiled into the shell but can be unset or redefined: .nf .IP .C autoload='typeset \-fu' .C command='command ' .C functions='typeset \-f' .C history='fc \-l' .C integer='typeset \-i' .C local=typeset .C nohup='nohup ' .C r='fc \-e \-' .C stop='kill \-STOP' .C suspend='kill \-STOP $$' .C type='whence \-v' .SS Tilde Substitution After alias substitution is performed, each word is checked to see if it begins with an unquoted tilde .RC ( ~ ). If it does, the word up to a .CR / is checked to see if it matches a user name in the .CR /etc/passwd file. If a match is found, the .CR ~ and the matched login name are replaced by the login directory of the matched user. If no match is found, the original text is left unchanged. A .CR ~ alone or before a .CR / is replaced by the value of the .CR HOME parameter. A .CR ~ followed by a .CR + or .CR \- is replaced by the value of the parameter .CR PWD and .CR OLDPWD , respectively. In addition, tilde substitution is attempted when the value of a parameter assignment begins with a .CR ~ . .SS Command Substitution The standard output from a command enclosed in parenthesis preceded by a dollar sign .RC ( $( ...\& ) ) or a pair of grave accents .RC ( ` ...\& ` ) can be used as part or all of a word; trailing newlines are removed. In the second (archaic) form, the string between the accents is processed for special quoting characters before the command is executed. See the "Quoting" subsection. The command substitution .CR "$(cat file)" can be replaced by the equivalent but faster .CR $(\0\c ". .TP .CR PS3 Selection prompt string used within a .CR select loop. If unset, it defaults to "\c .CR #?\0\c ". .TP .CR PS4 Execution trace string that precedes each line of an execution trace. See the .CR "set \-x" special command. If unset, it defaults to "\c .CR +\0\c ". .TP .CR SHELL The path name of the shell is kept in the environment. When invoked, the shell is restricted if the value of this variable contains an .CR r in the base name. .TP .CR TMOUT If set to a value greater than zero, the shell will terminate if a command is not entered within the prescribed number of seconds after issuing the .CR PS1 prompt. (Note that the shell can be compiled with a maximum bound for this value which cannot be exceeded.) .TP .CR VISUAL Invokes the corresponding option when the value of this variable ends in .CR emacs , .CR gmacs , or .CR vi . See the .CR "set \-o" special command. .PP The shell gives default values to .CR IFS , .CR MAILCHECK , .CR PATH , .CR PS1 , .CR PS2 , and .CR TMOUT . On the other hand, .CR MAIL , .CR ENV , .CR HOME , and .CR SHELL are never set automatically by the shell (although .CR HOME , .CR MAIL , and .CR SHELL are set by .CR login ; see .IR login (1)). .SS Blank Interpretation After parameter and command substitution, the results of substitution are scanned for field separator characters (defined in .CR IFS ), and split into distinct arguments when such characters are found. .CR sh retains explicit null arguments (\c .C """""" or .CR '' ) but removes implicit null arguments (those resulting from parameters that have null values). .SS File Name Generation Following substitution, each command .I word is processed as a pattern for file name expansion unless expansion has been disabled with the .CR "set \-f" special command. The form of the patterns is the Pattern Matching Notation defined in .IR regexp (5). The word is replaced with sorted file names matching the pattern. If no file name is found that matches the pattern, the word is left unchanged. .PP In addition to the notation described in .IR regexp (5), .CR sh recognizes composite patterns made up of one or more pattern lists separated from each other with a .CR | . Composite patterns can be formed with one or more of the following: .RS .TP 18 .PD 0 .CI ?( pattern-list ) Matches any one of the given patterns. .TP .CI *( pattern-list ) Matches zero or more occurrences of the given patterns. .TP .CI +( pattern-list ) Matches one or more occurrences of the given patterns. .TP .CI @( pattern-list ) Matches exactly one of the given patterns. .TP .CI !( pattern-list ) Matches anything, except one of the given patterns. .PD .RE .SS Quoting Each of the metacharacters (see the "Definitions" subsection) has a special meaning to the shell and terminates a word unless quoted. A character may be .B quoted (that is, made to stand for itself) by preceding it with a backslash .RC ( \e ). The pair .CR \e newline is ignored; the current and following lines are concatenated. .PP All characters enclosed between a pair of apostrophes .RC ( ' ...\& ' ) are quoted. An apostrophe cannot appear within apostrophes. .PP Parameter and command substitution occurs inside quotation marks (\c .C """\c" \&...\&\c .C """\c" ). .CR \e quotes the characters .CR \e , .CR ` , .C """\c" , and .CR $ . .PP Inside grave accent marks .RC ( ` ...\& ` ), .CR \e quotes the characters .CR \e , .CR ` , and .CR $ . If the grave accents occur within quotation marks, .CR \e also quotes the character .C """\c" \&. .PP The meanings of .CR $* and .CR $@ are identical when not quoted or when used as a parameter assignment value or as a file name. However, when used as a command argument, .C """\c" .CR $*\c .C """" is equivalent to .C """\c" .CI $1 d $2 d\f1...\&\c .C """\c" , whereas .C """\c" .CR $@\c .C """" is equivalent to .C """\c" .CR $1\c .C """\c" .IR d\c .C """\c" .CR $2\c .C """\c" .IR d ...\& (where .I d is the first character of .CR IFS ), .PP The special meaning of keywords or aliases can be removed by quoting any character of the name. The recognition of function names or special command names cannot be altered by quoting them. .SS Arithmetic Evaluation Integer arithmetic is provided with the special command .CR let . Evaluations are performed using long integer arithmetic. Constants take the form .IC base # n or .IR n , where .I base is a decimal number between two and thirty-six representing the arithmetic base and .I n is a number in that base. If .IC base # is omitted, base 10 is used. .PP An arithmetic expression uses the same syntax, precedence, and associativity of expression as the C language. All the integral operators, other than .CR ++ , .CR \-\- , .CR ?: , and .CR , are supported. Variables can be referenced by name within an arithmetic expression without using the parameter substitution syntax. When a variable is referenced, its value is evaluated as an arithmetic expression. .PP A variable can be typed as an integer with the .CR \-i option of the .CR typeset special command, as in .CI typeset\0-i \f1[\f2base\f1]\f2\0name\f1. Arithmetic evaluation is performed on the value of each assignment to a variable with the .CR \-i attribute. If you do not specify an arithmetic base, the first assignment to the variable determines the arithmetic base. This base is used when parameter substitution occurs. .PP Since many of the arithmetic operators require quoting, an alternative form of the .CR let command is provided. For any command beginning with .CR (( , all characters until the matching .CR )) are treated as a quoted expression. More precisely, .CR (( ...\& )) is equivalent to .CR let .C """\c" .RC ...\c .C """\c" .RC . .SS Prompting When used interactively, the shell prompts with the value of .CR PS1 before reading a command. Whenever a newline is received and further input is needed to complete a command, the secondary prompt (the value of .CR PS2 ) is issued. .SS Conditional Expressions A .B "conditional expression" is used with the .CR [[ compound command to test attributes of files and to compare strings. Word splitting and file name generation are not performed on the words between .CR [[ and .CR ]] . Each expression can be constructed from one or more of the following unary or binary expressions: .RS .TP 20 .PD 0 .CI \-a \0file True, if .I file exists. .TP .CI \-b \0file True, if .I file exists and is a block special file. .TP .CI \-c \0file True, if .I file exists and is a character special file. .TP .CI \-d \0file True, if .I file exists and is a directory. .TP .CI \-e \0file True, if .I file exists. .TP .CI \-f \0file True, if .I file exists and is an ordinary file. .TP .CI \-g \0file True, if .I file exists and has its setgid bit set. .TP .CI \-h \0file True, if .I file exists and is a symbolic link. .TP .CI \-k \0file True, if .I file exists and has its sticky bit set. .TP .CI \-n \0string True, if length of .I string is nonzero. .TP .CI \-o \0option True, if the set option named .I option is on. .TP .CI \-p \0file True, if .I file exists and is a fifo special file or a pipe. .TP .CI \-r \0file True, if .I file exists and is readable by current process. .TP .CI \-s \0file True, if .I file exists and has a size greater than zero. .TP .CI \-t \0fildes True, if file descriptor number .I fildes is open and is associated with a terminal device. .TP .CI \-u \0file True, if .I file exists and has its setuid bit set. .TP .CI \-w \0file True, if .I file exists and is writable by the current process. .TP .CI \-x \0file True, if .I file exists and is executable by the current process. If .I file exists and is a directory, then the current process has permission to search in the directory. .TP .CI \-z \0string True, if length of .I string is zero. .TP .CI \-L \0file True, if .I file exists and is a symbolic link. .TP .CI \-O \0file True, if .I file exists and is owned by the effective user ID of this process. .TP .CI \-G \0file True, if .I file exists and its group matches the effective group ID of this process. .TP .CI \-S \0file True, if .I file exists and is a socket. .TP .IC file1\0 \-nt \0file2 True, if .I file1 exists and is newer than .IR file2 . .TP .IC file1\0 \-ot \0file2 True, if .I file1 exists and is older than .IR file2 . .TP .IC file1\0 \-ef \0file2 True, if .I file1 and .I file2 exist and refer to the same file. .TP .IC string\0 = \0pattern True, if .I string matches .IR pattern . .TP .IC string\0 != \0pattern True, if .I string does not match .IR pattern . .TP .IC string\0 < \0string2 True, if .I string1 comes before .I string2 based on the ASCII value of their characters. .TP .IC string\0 > \0string2 True, if .I string1 comes after .I string2 based on the ASCII value of their characters. .TP .IC exp1\0 \-eq \0exp2 True, if .I exp1 is equal to .IR exp2 . .TP .IC exp1\0 \-ne \0exp2 True, if .I exp1 is not equal to .IR exp2 . .TP .IC exp1\0 \-lt \0exp2 True, if .I exp1 is less than .IR exp2 . .TP .IC exp1\0 \-gt \0exp2 True, if .I exp1 is greater than .IR exp2 . .TP .IC exp1\0 \-le \0exp2 True, if .I exp1 is less than or equal to .IR exp2 . .TP .IC exp1\0 \-ge \0exp2 True, if .I exp1 is greater than or equal to .IR exp2 . .PD .RE .PP A compound expression can be constructed from these primitives by using any of the following, listed in decreasing order of precedence. .RS .TP 20 .PD 0 .CI ( exp ) True, if .I exp is true. Used to group expressions. .TP .CI ! exp True, if .I exp is false. .TP .IC exp1\0 && \0exp2 True, if .I exp1 and .I exp2 are both true. .TP .IC exp1\0 || \0exp2 True, if either .I exp1 or .I exp2 is true. .PD .RE .SS Input/Output Before a command is executed, its input and output can be redirected using a special notation interpreted by the shell. The following can appear anywhere in a simple-command or may precede or follow a command and are not passed on to the invoked command. Command and parameter substitution occurs before .I word or .I digit is used, except as noted below. File name generation occurs only if the pattern matches a single file and blank interpretation is not performed. .RS .TP 15 .CI < word Use file .I word as standard input (file descriptor .CR 0 ). .TP .CI > word Use file .I word as standard output (file descriptor .CR 1 ). If the file does not exist, it is created. If the file exists, and the .CR noclobber option is on, an error occurs; otherwise, the file is truncated to zero length. .TP .CI >| word Same as .CR > , except that it overrides the .CR noclobber option. .TP .CI >> word Use file .I word as standard output. If the file exists, output is appended to it (by first searching for the end-of-file); otherwise, the file is created. .TP .CI <> word Open file .I word for reading and writing as standard input. .TP .CR << [ \- ]\f2word The shell input is read up to a line that matches .IR word , or to an end-of-file. No parameter substitution, command substitution or file name generation is performed on .IR word . The resulting document, called a .IR here-document , becomes the standard input. If any character of .I word is quoted, no interpretation is placed upon the characters of the document. Otherwise, parameter and command substitution occurs, .CR \e newline is ignored, and .CR \e must be used to quote the characters .CR \e , .CR $ , .CR ` , and the first character of .IR word . If .CR \- is appended to .CR << , all leading tabs are stripped from .I word and from the document. .TP .CI <& digit The standard input is duplicated from file descriptor .I digit (see .IR dup (2)). .TP .CI >& digit The standard output is duplicated to file descriptor .I digit (see .IR dup (2)). .TP .CR <&- The standard input is closed. .TP .CR >&- The standard output is closed. .TP .CR <&p The input from the coprocess is moved to standard input. .TP .CR >&p The output to the coprocess is moved to standard output. .RE .RE .PP If any of the above redirections is preceded by a digit .RC ( 0 to .CR 9 ), the file descriptor used is the one specified by the digit, instead of the default .CR 0 (standard input) or .CR 1 (standard output). For example: .IP .CR 2>&1 .PP means open file descriptor 2 for writing as a duplicate of file descriptor 1. Output directed to file descriptor 2 is written in the same location as output to file descriptor 1. .PP Order is significant in redirection. The shell evaluates each redirection in terms of the .RI ( "file descriptor" ", " file ) assignment at the time of evaluation. For example: .IP .CR 1> \f2fname\0 2>&1 .PP first assigns file descriptor 1 to file .IR fname . It then assigns file descriptor 2 to the file assigned to file descriptor 1 (that is, .IR fname ). .PP If the order of redirection is reversed, as in .IP .CR 2>&1\01> \f2fname .PP file descriptor 2 is assigned to the file assigned to file descriptor 1 (probably the terminal) and then file descriptor 1 is assigned to file .IR fname . .PP By using the redirection operators above, the input and output of a .I coprocess may be moved to a numbered file descriptor, allowing other commands to write to them and read from them. If the input of the current coprocess is moved to a numbered file descriptor, another coprocess may be started. .PP If a command is followed by .CR & and job control is inactive, the default standard input for the command is the empty file .CR /dev/null . Otherwise, the environment for the execution of a command contains the file descriptors of the invoking shell as modified by input/output specifications. .SS Environment The .B environment (see .IR environ (5)) is a list of name-value pairs passed to an executed program much like a normal argument list. The names must be identifiers and the values are character strings. The shell interacts with the environment in several ways. When invoked, the shell scans the environment and creates a parameter for each name found, gives it the corresponding value and marks it .CR export . Executed commands inherit the environment. If the user modifies the values of these parameters or creates new ones by using the .CR export or .CR "typeset \-x" special commands, the values become part of the environment. The environment seen by any executed command is thus composed of any name-value pairs originally inherited by the shell, whose values may be modified by the current shell, plus any additions which must be noted in .CR export or .CR "typeset \-x" commands. .PP The environment for any simple command or function can be augmented by prefixing it with one or more parameter assignments. A parameter assignment argument takes the form .IC identifier = value\f1. For example, both the following .IP .CI TERM=450 "\0cmd\0args" .IP .CI "(export TERM; TERM=450;" "\0cmd\0args" ) .PP are equivalent (as far as the execution of .I cmd is concerned, except for the special commands that are preceded by a dagger (\(dg)). .PP If the .CR \-k option is set, all parameter assignment arguments are placed in the environment, even if they occur after the command name. The following echo statement prints .CR "a=b c" . After the .CR \-k option is set, the second echo statement prints only .CR c : .nf .IP .CR "echo a=b c" \0\(->\0 "a=b c" .CR "set \-k" .CR "echo a=b c" \0\(->\0 "c" .fi .PP This feature is intended for use with scripts written for early versions of the shell and its use in new scripts is strongly discouraged. It is likely to disappear someday. .SS Functions The .CR function command (described in the "Compound Commands" subsection) defines shell functions. Shell functions are read and stored internally. Alias names are resolved when the function is read. Functions are executed like commands, with the arguments passed as positional parameters. (See the "Execution" subsection.) .PP Functions execute in the same process as the caller and share all files and current working directory with the caller. Traps defined by the caller are reset to their default action inside the function. A trap condition that is not caught or ignored by the function causes the function to terminate and the condition to be passed on to the caller. A trap on .CR EXIT set inside a function is executed after the function completes in the environment of the caller. Ordinarily, variables are shared between the calling program and the function. However, the .CR typeset special command can be used within a function to define local variables whose scope includes the current function and all functions it calls. .PP The .CR return special command is used to return from function calls. Errors within functions return control to the caller. .PP Function identifiers can be listed with the .CR +f option of the .CR typeset special command. Function identifiers and the associated text of the functions can be listed with the .CR \-f option. Functions can be undefined with the .CR \-f option of the .CR unset special command. .PP Ordinarily, functions are unset when the shell executes a shell script. The .CR \-xf option of the .CR typeset command allows a function to be exported to scripts that are executed without reinvoking the shell. Functions that must be defined across separate invocations of the shell should be placed in the .CR ENV file. .SS Jobs If the .CR monitor option of the .CR set command is turned on, an interactive shell associates a .I job with each pipeline. It keeps a table of current jobs, printed by the .CR jobs command, and assigns them small integer numbers. When a job is started asynchronously with .CR & , the shell prints a line that looks like: .IP .C "[1] 1234" .PP indicating that job number 1 was started asynchronously and had one (top-level) process whose process ID was 1234. .PP If you are running a job and wish to do something else, you can type the suspend character (the .CR susp character defined with .CR stty ; see .IR stty (1)) to send a .CR SIGSTOP signal to the current job. The shell then indicates that the job has been .CR Stopped , and prints another prompt. Then you can manipulate the state of this job by putting it in the background with the .CR bg command, running other commands, and eventually returning the job to the foreground with the .CR fg command. A suspend takes effect immediately and resembles an interrupt, since pending output and unread input are discarded when the suspend is entered. .PP A job running in the background stops if it tries to read from the terminal. Background jobs normally are allowed to produce output, but can be disabled with the .CR "stty tostop" command. If the user sets this terminal option, background jobs stop when trying to produce output. .PP There are several ways to refer to jobs in the shell. A job can be referred to by the process ID of any process in the job or by one of the following: .RS .TP 20 .PD 0 .CI % number The job with the given number. .TP .CI % string Any job whose command line begins with .IR string . .TP .CI %? string Any job whose command line contains .IR string . .TP .CI %% Current job. .TP .CI %+ Equivalent to .CR %% . .TP .CR %- Previous job. .PD .RE .PP The shell learns immediately when a process changes state. It informs the user when a job is blocked and prevented from further progress, but only just before it prints a prompt. .PP When the monitor mode is on, each background job that completes triggers any trap set for .CR SIGCHLD . .PP If you try to exit from shell while jobs are stopped, you are warned with the message .CR "You have stopped jobs." You can use the .CR jobs command to identify them. If you immediately try to exit again, the shell will not warn you a second time, and the stopped jobs will be terminated. .PP If you try to leave the shell while jobs are running, you are not warned. The shell exits silently and sets the parent of the running jobs to the .CR init process (number 1). .SS Signals The .CR SIGINT and .CR SIGQUIT signals for an invoked command are ignored if the command is followed by .CR & and the .CR monitor option is off. Otherwise, signals have the values inherited by the shell from its parent, with the exception of signal .CR SIGSEGV (but see also the .CR trap special command). .SS Execution Substitutions are made each time a command is executed. .CR sh checks the command name to determine whether it matches a special command. If it does, it is executed within the current shell process. .PP Next, .CR sh checks the command name to determine whether it matches one of the user-defined functions. If it does, .CR sh saves the positional parameters, then sets them to the arguments of the function call. The positional parameter .CR 0 is unchanged. When the function completes or issues a .CR return , .CR sh restores the positional parameter list and executes any trap set on .CR EXIT within the function. The value of a function is the value of the last command executed. A function is executed in the current shell process. .PP If a command name is not a user-defined function or a special command, .CR sh creates a process and attempts to execute the command using an .CI exec * () system call (see .IR exec (2)). .PP The shell parameter .CR PATH defines the search path for the directory containing the command. Alternative directory names are separated by a colon .RC ( : ). The default path is .CR /usr/bin:\& (specifying .CR /usr/bin , and the current directory, in that order). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign, between colon delimiters, or at the end of the path list. The search path is not used if the command name contains a .CR / . Otherwise, each directory in the path is searched for an executable file. If the file has execute permissions but is not a directory or an executable object code file, it is assumed to be a script file, which is a file of data for an interpreter. If the first two characters of the script file are .CR #! , .CI exec * () expects an interpreter path name to follow. .CI exec * () then attempts to execute the specified interpreter as a separate process to read the entire script file. If a call to .CI exec * () fails, .CR sh is spawned to interpret the script file. All nonexported aliases, functions, and named parameters are removed in this case. If the shell command file does not have read permission, or if the .CR setuid and/or .CR setgid bits are set on the file, the shell executes an agent to set up the permissions and execute the shell with the shell command file passed down as an open file. A parenthesized command is also executed in a subshell without removing nonexported quantities. .SS Command Reentry The text of the last .CR HISTSIZE (default 128) commands entered from a terminal device is saved in a history file. The file .CR $HOME/.sh_history is used if the .CR HISTFILE variable is not set or writable. A shell can access the commands of all interactive shells that use the same named .CR HISTFILE . The special command .CR fc is used to list or edit a portion of this file. The portion of the file to be edited or listed can be selected by number or by giving the first character or characters of the command. A single command or range of commands can be specified. If you do not specify an editor program as an argument to .CR fc , the value of the parameter .CR FCEDIT is used. If .CR FCEDIT is not defined, .CR /usr/bin/ed is used. The edited command is printed and reexecuted upon leaving the editor. The editor name .CR \- is used to skip the editing phase and to reexecute the command. In this case, a substitution parameter of the form .IC old = new can be used to modify the command before execution. For example, if .CR r is aliased to .CR "fc \-e \-" , typing .CR "r bad=good c" reexecutes the most recent command that starts with the letter .CR c and replaces the first occurrence of the string .CR bad with the string .CR good . .SS Command Line Editing Normally, each command line typed at a terminal device is followed by a newline or return. If one of the .CR emacs , .CR gmacs , .CR vi , or .CR viraw , options is set, you can edit the command line. An editing option is automatically selected each time the .CR VISUAL or .CR EDITOR variable is assigned a value ending in one of these option names. .PP The editing features require that the user's terminal accept return without line feed and that a space ("\ ") must overwrite the current character on the screen. ADM terminal users should set the "space\ \(mi\ advance" switch to "space". Hewlett-Packard terminal users should set the straps to "bcGHxZ\ etX". .PP The editing modes enable the user to look through a window at the current line. The default window width is 80, unless the value of .CR COLUMNS is defined. If the line is longer than the window width minus two, a mark displayed at the end of the window notifies the user. The mark is one of: .RS .TP .PD 0 .CR > The line extends to the right. .TP .CR < The line extends to the left. .TP .CR * The line extends to both sides of the window. .PD .RE .PP As the cursor moves and reaches the window boundaries, the window is centered about the cursor. .PP The search commands in each edit mode provide access to the history file. Only strings are matched, not patterns, although a leading .CR ^ in the string restricts the match to begin at the first character in the line. .SS emacs Editing Mode This mode is invoked by either the .CR emacs or .CR gmacs option. Their sole difference is their handling of .CR ^T . To edit, the user moves the cursor to the point needing correction and inserts or deletes characters or words. All editing commands are control characters or escape sequences. The notation for control characters is caret .RC ( ^ ) followed by a character. For example, .CR ^F is the notation for Control-F. This is entered by holding down the Ctrl (control) key and pressing .CR f . The shift key is .I not pressed. The notation .CR ^?\& indicates the delete (DEL) key. .PP The notation for escape sequences is .CR M- followed by a character. For example, .CR M-f (pronounced .IR "meta f" ) is entered by pressing the escape key (ESC) followed by pressing .CR f . .CR M-F is the notation for escape followed by shift (capital) .CR F . .PP All edit commands operate from any place on the line (not only at the beginning). Neither the return .RC ( ^M ) nor the newline .RC ( ^J ) key is entered after edit commands, except when noted. .RS .TP 15 .PD 0 .CR ^F Move cursor forward (right) one character. .TP .CR M-f Move cursor forward one word. (The editor's idea of a word is a string of characters consisting of only letters, digits and underscores.) .TP .CR ^B Move cursor backward (left) one character. .TP .CR M-b Move cursor backward one word. .TP .CR ^A Move cursor to start of line. .TP .CR ^E Move cursor to end of line. .TP .CI ^] char Move cursor forward to character .I char on current line. .TP .CI M-^] char Move cursor backward to character .I char on current line. .TP .CI ^X^X Interchange the cursor and mark. .TP .I erase Delete previous character. (User-defined erase character as defined by the .CR stty command, usually .CR ^H or .CR # .) .TP .CR ^D Delete current character. .TP .I eof Terminate the shell if the current line is null. (User-defined end-of-file character as defined by the .CR stty command, usually .CR ^D .) .TP .CI M-d Delete current word. .TP .CI M-^H Delete previous word. (meta-backspace) .TP .CI M-h Delete previous word. .TP .CI M-^?\& Delete previous word. (meta-delete) If your interrupt character is .CR ^?\& (DEL, the default), this command will not work. .TP .CI ^T In .CR emacs mode, transpose current character with next character. In .CR gmacs mode, transpose two previous characters. .TP .CI ^C Capitalize current character. .TP .CI M-c Capitalize current word. .TP .CI M-l Change the current word to lowercase. .TP .CI ^K Delete from the cursor to the end of the line. If preceded by a numerical parameter whose value is less that the current cursor position, then delete from the given position up to the cursor. If preceded by a numerical parameter whose value is greater than the current cursor position, then delete from the cursor up to the given position. .TP .CI ^W Kill from the cursor to the mark. .TP .CI M-p Push the region from the cursor to the mark on the stack. .TP .I kill Kill the entire current line. If two kill characters are entered in succession, all subsequent consecutive kill characters cause a line feed (useful when using paper terminals). (User-defined kill character as defined by the .CR stty command, usually .CR ^X or .CR @ .) .TP .CI ^Y Restore last item removed from line. (Yank item back to the line.) .TP .CI ^L Line feed and print current line. .TP .CR ^@ Set mark. (null character) .TP .CI M-\0 Set mark. (meta-space) .TP .CI ^J Execute the current line. (newline) .TP .CI ^M Execute the current line. (return) .TP .CI ^P Fetch previous command. Each time .CR ^P is entered, the previous command in the history list is accessed. .TP .CI ^N Fetch next command. Each time .CR ^N is entered the next command in the history list is accessed. .TP .CI M-< Fetch the least recent (oldest) history line. .TP .CI M-> Fetch the most recent (youngest) history line. .TP .CI ^R string Reverse search history for a previous command line containing .IR string . If a parameter of zero is given, the search is forward. .I string is terminated by a return or newline. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is omitted, the next command line containing the most recent .I string is accessed. In this case, a parameter of zero reverses the direction of the search. .TP .CR ^O Execute the current line and fetch the next line relative to current line from the history file. .TP .CI M- digits Define a numeric parameter. The digits are taken as a parameter to the next command. The commands that accept a parameter are .IR erase , .CR ^B , .CR ^C , .CR ^D , .CR ^F , .CR ^K , .CR ^N , .CR ^P , .CR ^R , .CR ^] , .CR M-^H , .CR M-. , .CR M-_ , .CR M-b , .CR M-c , .CR M-d , .CR M-f , .CR M-h , and .CR M-l . .TP .CI M- letter Your alias list is searched for an alias by the name .CI _ letter (underscore-letter). If an alias of this name is defined, its value is inserted on the input queue. This .I letter must not be one of the above metafunctions. .TP .CR M-. The last word of the previous command is inserted on the line. If preceded by a numeric parameter, the value of this parameter determines which word to insert rather than the last word. .TP .CR M-_ Same as .CR M-. . .TP .CR M-* Attempt file name generation on the current word. .TP .CR M-^[ File name completion. (meta-escape.) Replaces the current word with the longest common prefix of all file names matching the current word with an asterisk appended. If the match is unique, a .CR / is appended if the file is a directory and a space is appended if the file is not a directory. .TP .CR M-= List files matching current word pattern as if an asterisk were appended. .TP .CR ^U Multiply parameter of next command by 4. .TP .CR \e Escape next character. Editing characters and your erase, kill, and interrupt characters may be entered in a command line or in a search string, if preceded by a .CR \e . The .CR \e removes the next character's editing features (if any). .TP .CI ^V Display version of the shell. .TP .CI M-# Insert a .CR # at the beginning of the line and execute it. This causes a comment to be inserted in the history file. .PD .RE .SS vi Editing Mode The editor starts in insert mode until an escape (ESC) is received. This puts you in control mode in which you can move the cursor and perform editing commands. A return in either mode sends the line. .PP Most control commands accept an optional repeat .I count prior to the command. .PP In .CR vi mode on most systems, canonical processing is initially enabled and the command is echoed again if the speed is 1200 baud or greater and contains any control characters, or if less than one second has elapsed since the prompt was printed. The escape (ESC) character terminates canonical processing for the remainder of the command and you can then modify the command line. This scheme has the advantages of canonical processing with the typeahead echoing of raw mode. .PP Setting the .CR viraw option always disables canonical processing on the terminal. This mode is implicit for systems that do not support two alternate end-of-line delimiters, and may be helpful for certain terminals. .PP .B Insert Edit Commands .PP By default, the editor is in insert mode. .RS .TP 15 .PD 0 .I erase Delete previous inserted character. The .IR erase character is user-definable with the .CR stty command, usually set to .CR ^H . The system default is .CR # . .TP .I kill Delete all current inserted characters. The .IR kill character is user-definable with the .CR stty command, usually set to .CR ^X or .CR ^U . The system default is .CR @ . .TP .CR \e Escape the next .I erase or .I kill character. .TP .CR ^D Terminate the shell. .TP .CR ^V Escape next character. Editing characters and erase or kill characters may be entered in a command line or in a search string if preceded by a .CR ^V , which removes the next character's editing features (if any). .TP .CR ^W Delete the previous blank-separated word. .PD .RE .PP .B Motion Edit Commands .PP These commands move the cursor. The use of .IR count causes a repetition of the command the cited number of times. .RS .TP 15 .PD 0 .RC [\f2count\f1] l Cursor forward (right) one character. .TP .RC [\f2count\f1] w Cursor forward one alphanumeric word. .TP .RC [\f2count\f1] W Cursor forward to the beginning of the next word that follows a blank. .TP .RC [\f2count\f1] e Cursor forward to the end of the word. .TP .RC [\f2count\f1] E Cursor forward to end of the current blank-delimited word. .TP .RC [\f2count\f1] h Cursor backward (left) one character. .TP .RC [\f2count\f1] b Cursor backward one word. .TP .RC [\f2count\f1] B Cursor backward to preceding blank-separated word. .TP .RC [\f2count\f1] | Cursor to column .IR count . Default is 1. .TP .RC [\f2count\f1] f \f2c Find the next character .IR c in the current line. .TP .RC [\f2count\f1] F \f2c Find the previous character .IR c in the current line. .TP .RC [\f2count\f1] t \f2c Equivalent to .CI f c followed by .CR h . .TP .RC [\f2count\f1] T \f2c Equivalent to .CI F c followed by .CR l . .TP .RC [\f2count\f1] ; Repeat the last single-character find command, .CR f , .CR F , .CR t , or .CR T . .TP .RC [\f2count\f1] , Reverses the last single character find command. .TP .CR 0 Cursor to start of line. .TP .CR ^ Cursor to first nonblank character in line. .TP .CR $ Cursor to end of line. .PD .RE .PP .B History Search Commands .PP These commands access your command history file. .RS .TP 15 .PD 0 .RC [\f2count\f1] k Fetch previous command. Each time .CR k is entered, the next earlier command in the history list is accessed. .TP .RC [\f2count\f1] \- Equivalent to .CR k . .TP .RC [\f2count\f1] j Fetch next command. Each time .CR j is entered, the next later command in the history list is accessed. .TP .RC [\f2count\f1] + Equivalent to .CR j . .TP .RC [\f2count\f1] G The command number .I count is fetched. The default is the first command in the history list. .TP .CI / string Search backward through history for a previous command containing .IR string . .I string is terminated by a return or newline. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is null, the previous string is used. .TP .CI ? string Same as .CR / , but search in the forward direction. .TP .CR n Search for next match of the last pattern to the .CR / or .CR ? commands. .TP .CR N Search for next match of the last pattern to .CR / or .CR ? , but in reverse direction. .PD .RE .PP .B Text Modification Edit Commands .PP These commands will modify the line. .RS .TP 15 .PD 0 .CR a Enter insert mode after the current character. .TP .CR A Append text to the end of the line. Equivalent to .CR $a . .TP .RC [\f2count\f1] c \f2motion .TP .CR c [\f2count\f1]\f2motion Move cursor forward to the character position specified by .IR motion , deleting all characters between the original cursor position and the new position, and enter insert mode. If .I motion is .CR c , the entire line is deleted. .TP .CR C Delete from the current character through the end of line and enter insert mode. Equivalent to .CR c$ . .TP .CR S Equivalent to .CR cc . .TP .RC [\f2count\f1] d \f2motion .TP .CR d [\f2count\f1]\f2motion Move cursor to the character position specified by .IR motion , deleting all characters between the original cursor position and the new position. If .I motion is .CR d , the entire line will be deleted. .TP .CR D Delete from the current character through the end of line. Equivalent to .CR d$ . .TP .CR i Enter insert mode before the current character. .TP .CR I Enter insert mode before the beginning of the line. Equivalent to the two-character sequence .CR 0i . .TP .RC [\f2count\f1] P Insert the previous text modification before the cursor. .TP .RC [\f2count\f1] p Insert the previous text modification after the cursor. .TP .CR R Enter insert mode and replace characters on the screen with characters you type, overlay fashion. .TP .RC [\f2count\f1] r \f2c Replace the current character with .IR c . .TP .RC [\f2count\f1] x Delete the current character. .TP .RC [\f2count\f1] X Delete the preceding character. .TP .RC [\f2count\f1] . Repeat the previous text modification command. .TP .CR ~ Invert the case of the current character and advance the cursor. .TP .RC [\f2count\f1] _ Append the .I count word of the previous command at the current cursor location and enter insert mode at the end of the appended text. The last word is used if .I count is omitted. .TP .CR * Append an .CR * to the current word and attempt file name generation. If no match is found, ring the bell. If a match is found, replace the word with the matching string of file names and enter insert mode. .TP escape .TP .CR \e Attempt file name completion on the current word. Replace the current word with the longest common prefix of all file names matching the current word with an asterisk appended. If the match is unique, append a .CR / if the file is a directory or append a space if the file is not a directory. .PD .RE .PP .B Other Edit Commands .PP .RS .TP 15 .PD 0 .RC [\f2count\f1] y \f2motion .TP .CR y [\f2count\f1]\f2motion Yank current character through character that .I motion would move the cursor to and put them into the delete buffer. The text and cursor are unchanged. .TP .CR Y Yank from current position to end of line. Equivalent to .CR y$ . .TP .CR u Undo the last text-modifying command. .TP .CR U Undo all the text-modifying commands performed on the line. .TP .RC [\f2count\f1] v Execute the command .CI "fc \-e ${VISUAL:-${EDITOR:-vi}}" " count" in the input buffer. If .I count is omitted, the current line is used. This executes an editor with the current line as the input "file". When you exit from the editor, the result is executed. .TP .CR ^L Line feed and print current line. .TP .CR ^J Execute the current line, regardless of mode. (newline) .TP .CR ^M Execute the current line, regardless of mode. (return) .TP .CR # Insert a .CR # at the beginning of the current line and after each embedded newline, and execute the line. Useful for inserting the current command line in the history list without executing it. .TP .CR = List the file names that match the current word if an asterisk were appended to it. .TP .CI @ letter Search your alias list for an alias with the name .CI _ letter (underscore letter). If an alias of this name is defined, its value is executed as a command sequence on the current line. This provides a simple macro capability. .PD .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. If it is not defined or is empty, it defaults to the value of .CR LANG . .PP .CR LC_CTYPE determines the classification of characters as letters, and the characters matched by character class expressions in pattern matching notation. If it is not defined or is empty, it defaults to the value of .CR LANG . .PP If .CR LANG is not defined or is empty, it defaults to .CR C (see .IR lang (5)). .PP If any internationalization variable contains an invalid value, they all default to .CR C (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH RETURN VALUE Errors detected by the shell, such as syntax errors, cause the shell to return a nonzero exit status. Otherwise, the shell returns the exit status of the last command executed. See also the .CR exit special command. If the shell is being used noninteractively, the execution of the shell file is abandoned. Runtime errors detected by the shell are reported by printing the command or function name and the error condition. If the line number on which the error occurred is greater than one, the line number is also printed in brackets .RC ( [] ) after the command or function name. .\".SH EXAMPLES .\" none appropriate. .SH WARNINGS .PP .\" File descriptors 54 through 60 are used internally by the POSIX shell. File descriptors 24 through 30 are used internally by the POSIX shell. Applications using these and forking a subshell should not depend upon them surviving in the subshell or its descendants. .PP If a command that is a tracked alias is executed, and a command with the same name is installed in a directory in the search path before the directory where the original command was found, the shell will continue to load and execute the original command. Use the .CR \-t option of the .CR alias command to correct this situation. .PP If you move the current directory or one above it, .CR pwd may not give the correct response. Use the .CR cd command with a full path name to correct this situation. .PP Some very old shell scripts use a caret .RC ( ^ ) as a synonym for the pipe character .RC ( | ). .CR sh .I "does not" recognize the caret as a pipe character. .PP If a command is piped into a shell command, all variables set in the shell command are lost when the command completes. .PP Using the .CR fc built-in command within a compound command will cause the entire command to disappear from the history file. .PP The dot .RC ( . ) special command, as in .CI .\& " file\f1," reads the entire file before any commands are executed. Therefore, .CR alias and .CR unalias commands in the file will not apply to any functions defined in the file. .PP Traps are not processed while the shell is waiting for a foreground job. Thus, a trap on .CR SIGCHLD is not executed until the foreground job terminates. .PP The .CR export special command does not handle arrays properly. Only the first element of an array is exported to the environment. .PP Background processes started from a noninteractive shell cannot be accessed with job control commands. .PP The value of the .CR IFS variable in the user's environment affects the behavior of scripts. .SS Collating Order In an international environment, character ordering is determined by the value of .CR LC_COLLATE , rather than by the binary ordering of character values in the machine collating sequence. This brings with it certain attendant dangers, particularly when using range expressions in file name generation patterns. For example, the command, .IP .C "rm [a-z]*" .PP might be expected to match all file names beginning with a lowercase alphabetic character. However, if dictionary ordering is specified by .CR LC_COLLATE , it would also match file names beginning with an uppercase character (as well as those beginning with accented letters). Conversely, it would fail to match letters collated after .CR z in languages such as Danish or Norwegian. .PP The correct (and safe) way to match specific character classes in an international environment is to use a pattern (see .IR regexp (5)) of the form: .IP .C "rm [[:lower:]]*" .PP This uses .CR LC_CTYPE to determine character classes and works predictably for all supported languages and codesets. For shell scripts produced on noninternationalized systems (or without consideration for the above dangers), it is recommended that they be executed in a non-NLS environment. This requires that .CR LANG , .CR LC_COLLATE , and so on, be set to .CR C or not set at all. .SS History File Changes At HP-UX release B.10.10, the history file has a new internal magic number. This will cause a pre-B.10.10 history file to be discarded. Users who use multiple versions of HP-UX that NFS-mount the same directory that contains the history file (usually the home directory) may want to create a separate history file for each HP-UX version by setting the .CR HISTFILE parameter as: .IP .C "HISTFILE=$HOME/.sh_hist_$(uname \-r)" .PP Users on windowing systems may want to have separate history files for each window by setting the HISTFILE parameter as follows: .IP .C "HISTFILE=$HOME/.sh_hist$$" .PP A .CR cron job may be used to delete old history files. .PP The history file does not support mixing of locales in the same file. For users of multiple locales, you can assign a unique history file for each locale by setting .CR HISTFILE as: .IP .C "HISTFILE=$HOME/.sh_hist_${LANG}" .PP or include the process number in the .CR HISTFILE parameter as shown above. .SH AUTHOR .CR sh was developed by AT&T, OSF, and HP. .SH FILES .TP 30 .PD 0 .CR $HOME/.profile Read to set up user's custom environment .TP .CR /etc/passwd To find home directories .TP .CR /etc/profile Read to set up system environment .TP .CR /etc/suid_profile Security profile .TP .CR /tmp/sh* For here-documents .TP .CR /usr/bin/sh Shell executable program location .PD .SH SEE ALSO cat(1), cd(1), command(1), echo(1), ed(1), env(1), getopts(1), kill(1), ln(1), login(1), newgrp(1), printf(1), pwd(1), read(1), stty(1), test(1), time(1), umask(1), vi(1), dup(2), exec(2), fork(2), pipe(2), stty(2), ulimit(2), umask(2), wait(2), rand(3C), a.out(4), profile(4), environ(5), lang(5), regexp(5), signal(5). .SH STANDARDS CONFORMANCE .CR sh ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR . ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR : ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR break ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR case ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR continue ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR eval ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR exec ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR exit ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR export ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR for ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR if ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR read ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR return ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR set ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR shift ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR time ": SVID2, SVID3, XPG2, XPG3, XPG4" .br .CR trap ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR unset ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR until ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR while ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4sh\f1 \- shell based on POSIX.2@@@\f3sh-posix(1)\f1 .\" index@\f4alias\f1 \- substitute command and/or file name@@@\f3sh-posix(1)\f1 .\" index@\f4break\f1 \- exit from enclosing for/next loop@@@\f3sh-posix(1)\f1 .\" index@\f4case\f1 \- execute \f2list\f1 associated with \f2pattern\f1 that matches \f2word\f1@@@\f3sh-posix(1)\f1 .\" index@\f4cd\f1 \- change working directory@@@\f3sh-posix(1)\f1 .\" index@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@\f3sh-posix(1)\f1 .\" index@\f4echo\f1 \- echo (print) arguments@@@\f3sh-posix(1)\f1 .\" index@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@\f3sh-posix(1)\f1 .\" index@\f4exec\f1 \- execute command without creating new process@@@\f3sh-posix(1)\f1 .\" index@\f4exit\f1 \- exit shell with exit status@@@\f3sh-posix(1)\f1 .\" index@\f4export\f1 \- export variable names to environment of subsequent commands@@@\f3sh-posix(1)\f1 .\" index@\f4fc\f1 \- edit and execute previous command@@@\f3sh-posix(1)\f1 .\" index@\f4for\f1 \- execute a do list@@@\f3sh-posix(1)\f1 .\" index@\f4if\f1 \- execute command if previous command returns exit status 0@@@\f3sh-posix(1)\f1 .\" index@\f4jobs\f1 \- list active jobs@@@\f3sh-posix(1)\f1 .\" index@\f4kill\f1 \- terminate job or process@@@\f3sh-posix(1)\f1 .\" index@\f4let\f1 \- evaluate arithmetic expression@@@\f3sh-posix(1)\f1 .\" index@\f4newgrp\f1 \- equivalent to \f4exec newgrp\f1@@@\f3sh-posix(1)\f1 .\" index@\f4print\f1 \- output from shell@@@\f3sh-posix(1)\f1 .\" index@\f4pwd\f1 \- print current working directory@@@\f3sh-posix(1)\f1 .\" index@\f4read\f1 \- input and parse a line@@@\f3sh-posix(1)\f1 .\" index@\f4readonly\f1 \- mark names as unredefinable@@@\f3sh-posix(1)\f1 .\" index@\f4return\f1 \- shell function return to invoking script@@@\f3sh-posix(1)\f1 .\" index@\f4set\f1 \- set/define options and arguments@@@\f3sh-posix(1)\f1 .\" index@\f4shift\f1 \- shift \f2argv\f1 members one position to left@@@\f3sh-posix(1)\f1 .\" index@\f4test\f1 \- evaluate conditional expression@@@\f3sh-posix(1)\f1 .\" index@\f4time\f1, \f4times\f1 \- print summary of time used by processes@@@\f3sh-posix(1)\f1 .\" index@\f4trap\f1 \- trap specified signal@@@\f3sh-posix(1)\f1 .\" index@\f4typeset\f1 \- control leading blanks and parameter handling@@@\f3sh-posix(1)\f1 .\" index@\f4ulimit\f1 \- set size or time limits@@@\f3sh-posix(1)\f1 .\" index@\f4umask\f1 \- set permissions mask for creating new files@@@\f3sh-posix(1)\f1 .\" index@\f4unalias\f1 \- discard specified alias@@@\f3sh-posix(1)\f1 .\" index@\f4unset\f1 \- remove definition/setting of options and arguments@@@\f3sh-posix(1)\f1 .\" index@\f4until\f1 \- execute commands until expression is nonzero@@@\f3sh-posix(1)\f1 .\" index@\f4wait\f1 \- wait for child process@@@\f3sh-posix(1)\f1 .\" index@\f4whence\f1 \- define interpretation of name as a command@@@\f3sh-posix(1)\f1 .\" index@\f4while\f1 \- execute commands while expression is nonzero@@@\f3sh-posix(1)\f1 .\" .\" toc@\f3sh-posix(1)\f1:\0\0\f4sh\f1@@@shell, the standard/restricted command programming language .\" toc@\f4case\f1 \- label in a switch statement@@@see \f3sh-posix(1)\f1 .\" toc@\f4alias\f1 \- substitute command and/or file name@@@see \f3sh-posix(1)\f1 .\" toc@\f4break\f1 \- exit from enclosing for/next loop@@@see \f3sh-posix(1)\f1 .\" toc@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@see \f3sh-posix(1)\f1 .\" toc@\f4cd\f1 \- change working directory@@@see \f3sh-posix(1)\f1 .\" toc@\f4echo\f1 \- echo (print) arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@see \f3sh-posix(1)\f1 .\" toc@\f4exec\f1 \- execute command without creating new process@@@see \f3sh-posix(1)\f1 .\" toc@\f4exit\f1 \- exit shell with exit status@@@see \f3sh-posix(1)\f1 .\" toc@\f4export\f1 \- export variable names to environment of subsequent commands@@@see \f3sh-posix(1)\f1 .\" toc@\f4fc\f1 \- edit and execute previous command@@@see \f3sh-posix(1)\f1 .\" toc@\f4for\f1 \- execute a do list@@@see \f3sh-posix(1)\f1 .\" toc@\f4if\f1 \- execute command if previous command returns exit status 0@@@see \f3sh-posix(1)\f1 .\" toc@\f4jobs\f1 \- list active jobs@@@see \f3sh-posix(1)\f1 .\" toc@\f4kill\f1 \- terminate job or process@@@see \f3sh-posix(1)\f1 .\" toc@\f4let\f1 \- evaluate arithmetic expression@@@see \f3sh-posix(1)\f1 .\" toc@\f4newgrp\f1 \- equivalent to \f2exec newgrp\f1@@@see \f3sh-posix(1)\f1 .\" toc@\f4print\f1 \- output from shell@@@see \f3sh-posix(1)\f1 .\" toc@\f4pwd\f1 \- print current working directory@@@see \f3sh-posix(1)\f1 .\" toc@\f4read\f1 \- input and parse a line@@@see \f3sh-posix(1)\f1 .\" toc@\f4readonly\f1 \- mark names as unredefinable@@@see \f3sh-posix(1)\f1 .\" toc@\f4return\f1 \- shell function return to invoking script@@@see \f3sh-posix(1)\f1 .\" toc@\f4set\f1 \- set/define options and arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4shift\f1 \- shift \f2argv\f1 members one position to left@@@see \f3sh-posix(1)\f1 .\" toc@\f4test\f1 \- evaluate conditional expression@@@see \f3sh-posix(1)\f1 .\" toc@\f4trap\f1 \- trap specified signal@@@see \f3sh-posix(1)\f1 .\" toc@\f4time, times\f1 \- print summary of time used by processes@@@see \f3sh-posix(1)\f1 .\" toc@\f4typeset\f1 \- control leading blanks and parameter handling@@@see \f3sh-posix(1)\f1 .\" toc@\f4ulimit\f1 \- set size or time limits@@@see \f3sh-posix(1)\f1 .\" toc@\f4umask\f1 \- set permissions mask for creating new files@@@see \f3sh-posix(1)\f1 .\" toc@\f4unalias\f1 \- discard specified alias@@@see \f3sh-posix(1)\f1 .\" toc@\f4unset\f1 \- remove definition/setting of options and arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4wait\f1 \- wait for child process@@@see \f3sh-posix(1)\f1 .\" toc@\f4whence\f1 \- define interpretation of name as a command@@@see \f3sh-posix(1)\f1 .\" toc@\f4while\f1 \- execute commands while expression is nonzero@@@see \f3sh-posix(1)\f1 .\" toc@\f4until\f1 \- execute commands until expression is nonzero@@@see \f3sh-posix(1)\f1 .\" .\" links@sh-posix.1 alias.1 .\" links@sh-posix.1 bg.1 .\" links@sh-posix.1 fc.1 .\" links@sh-posix.1 fg.1 .\" links@sh-posix.1 jobs.1 .\" links@sh-posix.1 unalias.1 .\" $Header: sh-posix.1,v 76.4 95/11/02 14:15:41 ssa Exp $ .TA s .TH sh-posix 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sh, rsh \- standard and restricted POSIX.2-conformant command shells .SH SYNOPSIS .CR sh .RC [{ \- \(or + }\c .CR aefhikmnprstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [ \-c .IR string ] .IR arg ]...\& .PP .CR rsh .RC [{ \- \(or + }\c .CR aefhikmnprstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [ \-c .IR string ] .RI [ arg ]...\& .SS Remarks This shell is intended to conform to the shell specification of the POSIX.2 .I Shell and Utility standards. Check any standards conformance documents shipped with your system for information on the conformance of this shell to any other standards. .SS List of Subheadings in DESCRIPTION .\" .SS lines under DESCRIPTION (commands are vi/ex) .\" Extract header lines; copy to eof ":g/\.S[SH]/co$: .\" Delete extraneous leading and trailing headings .\" Delete .SS ":.,$s/....//" .\" Form into columns ":.,$!pr -3 -t -s@" .\" Replace pr tabs with blanks ":.,$s/[[:space:]]/ /g" .\" Move into place below. .TS tab(@); l l l . Shell Invocation@Tilde Substitution@Environment Options@Command Substitution@Functions rsh Restrictions@Parameter Substitution@Jobs Definitions@Blank Interpretation@Signals Commands@File Name Generation@Execution Simple Commands@Quoting@Command Reentry Compound Commands@Arithmetic Evaluation@Command Line Editing Special Commands@Prompting@emacs Editing Mode Comments@Conditional Expressions@vi Editing Mode Aliasing@Input/Output .TE .SH DESCRIPTION .CR sh is a command programming language that executes commands read from a terminal or a file. .PP .CR rsh is a restricted version of .CR sh . See the "rsh Restrictions" subsection below. .SS Shell Invocation If the shell is invoked by an .CI exec * () system call and the first character of argument zero (shell parameter .CR 0 ) is dash .RC ( \- ), the shell is assumed to be a login shell and commands are read first from .CR /etc/profile , then from either .CR .profile in the current directory or .CR $HOME/.profile if either file exists, and finally from the file named by performing parameter substitution on the value of the environment parameter .CR ENV , if the file exists. If the .CR \-s option is not present and an .I arg is, a path search is performed on the first .I arg to determine the name of the script to execute. When running .CR sh with .IR arg , the script .I arg must have read permission and any .CR setuid and .CR setgid settings will be ignored. Commands are read as described below. .PP Shell output, except for the output of some of the commands listed in the "Special Commands" subsection, is written to standard error (file descriptor 2). .SS Options The following options are interpreted by the shell when it is invoked. .TP 15 .CI \-c \0string Read commands from .IR string . .TP .CR \-i If .CR \-i is present or if the shell input and output are attached to a terminal (as reported by .CR tty() ), the shell is interactive. In this case .CR SIGTERM is ignored (so that .CR "kill 0" does not kill an interactive shell) and .CR SIGINT is caught and ignored (so that .CR wait is interruptible). In all cases, .CR SIGQUIT is ignored by the shell. See .IR signal (5). .TP .CR \-r The shell is a restricted shell. .TP .CR \-s If .CR \-s is present or if no arguments remain, commands are read from the standard input. .PP The remaining options and arguments are described under the .CR set command in the "Special Commands" subsection. .SS rsh Restrictions .CR rsh is used to set up login names and execution environments where capabilities are more controlled than those of the standard shell. The actions of .CR rsh are identical to those of .CR sh , except that the following are forbidden: .RS .TP 3 .PD 0 \(bu Changing directory (see the .CR cd special command and .IR cd (1)) .TP \(bu Setting the value of .CR SHELL , .CR ENV , or .CR PATH .TP \(bu Specifying path or command names containing .CR / .TP \(bu Redirecting output .RC ( > , .CR >| , .CR <> , and .CR >> ) .PD .RE .PP The restrictions above are enforced after the .CR .profile and .CR ENV files are interpreted. .PP When a command to be executed is found to be a shell procedure, .CR rsh invokes .CR sh to execute it. Thus, the end-user is provided with shell procedures accessible to the full power of the standard shell, while being restricted to a limited menu of commands. This scheme assumes that the end-user does not have write and execute permissions in the same directory. .PP These rules effectively give the writer of the .CR .profile file complete control over user actions, by performing guaranteed set-up actions and leaving the user in an appropriate directory (probably not the login directory). .PP The system administrator often sets up a directory of commands (usually .CR /usr/rbin ) that can be safely invoked by .CR rsh . HP-UX systems provide a restricted editor .CR red (see .IR ed (1)), suitable for restricted users. .SS Definitions .TP 20 .B metacharacter One of the following characters: .IP .CR "; & ( ) | < >" \0newline\0space\0tab .TP .B blank A tab or a space. .TP .B identifier A sequence of letters, digits, or underscores starting with a letter or underscore. Identifiers are used as names for .BR functions and .BR "named parameters" . .TP .B word A sequence of .B characters separated by one or more nonquoted .BR metacharacters . .TP .BR command A sequence of characters in the syntax of the shell language. The shell reads each command and carries out the desired action, either directly or by invoking separate utilities. .TP .B "special command" A command that is carried out by the shell without creating a separate process. Except for documented side effects, most special commands can be implemented as separate utilities. .TP .CR # Comment delimiter. A word beginning with .CR # and all following characters up to a newline are ignored. .TP .B parameter An .BR identifier , a decimal number, or one of the characters .CR ! , .CR # , .CR $ , .CR * , .CR \- , .CR ? , .CR @ , and .CR _ . See the "Parameter Substitution" subsection. .TP .B "named parameter" A .B parameter that can be assigned a value. See the "Parameter Substitution" subsection. .TP .B variable A .BR parameter . .TP .B "environment variable" A .BR parameter that is known outside the local shell, usually by means of the .CR export special command. .SS Commands A command can be a simple command that executes an executable file, a special command that executes within the shell, or a compound command that provides flow of control for groups of simple, special, and compound commands. .SS Simple Commands A simple command is a sequence of blank-separated words that may be preceded by a parameter assignment list. (See the "Environment" subsection). The first word specifies the name of the command to be executed. Except as specified below, the remaining words are passed as arguments to the invoked command. The command name is passed as argument .CR 0 (see .IR exec (2)). The .I value of a simple-command is its exit status if it terminates normally, or .CI 128+ errorstatus if it terminates abnormally (see .IR signal (5) for a list of .I errorstatus values). .PP A .B pipeline is a sequence of one or more commands separated by a bar .RC ( | ) and optionally preceded by an exclamation mark .RC ( ! ). The standard output of each command but the last is connected by a pipe (see .IR pipe (2)) to the standard input of the next command. Each command is run as a separate process; the shell waits for the last command to terminate. If .CR !\& does not precede the pipeline, the exit status of the pipeline is the exit status of the last command in the pipeline. Otherwise, the exit status of the pipeline is the logical negation of the exit status of the last command in the pipeline. .PP A .I list is a sequence of one or more pipelines separated by .CR ; , .CR & , .CR && , or .CR || , and optionally terminated by .CR ; , .CR & , or .CR |& . .RS .TP .CR ;\& Causes sequential execution of the preceding pipeline. An arbitrary number of newlines can appear in a .I list, instead of semicolons, to delimit commands. .TP .CR & Causes asynchronous execution of the preceding pipeline (that is, the shell does not wait for that pipeline to finish). .TP .CR |& Causes asynchronous execution of the preceding command or pipeline with a two-way pipe established to the parent shell. The standard input and output of the spawned command can be written to and read from by the parent shell using the .CR \-p option of the special commands .CR read and .CR print . .TP .CR && Causes the .I list following it to be executed only if the preceding pipeline returns a zero value. .TP .CR || Causes the .I list following it to be executed only if the preceding pipeline returns a nonzero value. .RE .PP Of these five symbols, .CR ; , .CR & , and .CR |& have equal precedence, which is lower than that of .CR && and .CR || . The symbols .CR && and .CR || also have equal precedence. .SS Compound Commands Unless otherwise stated, the value returned by a compound command is that of the last simple command executed in the compound command. The .CR ;\& segment separator can be replaced by one or more newlines. .PP The following keywords are recognized only as the first word of a command and when not quoted: .nf .RS .IP .C "! } elif for then" .C "[[ case else function time" .C "]] do esac if until" .C "{ done fi select while" .fi .RE .PP A compound command is one of the following. .PP .ne 3v .CR case \f2\0word\c .CR \0in \0[\|[ ; ]\0[ ( ]\c .IC \0pattern\0\f1[ | \0pattern\f1]... ) \0list\0\c .CR ;; ]...\0 ;\0esac .IP Execute the .I list associated with the first .I pattern that matches .IR word . The form of the patterns is identical to that used for file name generation (see the "File Name Generation" subsection). The .CR ;;\& case terminator cannot be replaced by newlines. .PP .ne 3v .CI for \0identifier\f1\0[ in \0word\f1\0...]\0\c .CR ;\0do \0\f2list\0 ;\0done .IP Set .I identifier to each .I word in sequence and execute the .CR do .IR list . If .CR in .IR word .RI ...\& is omitted, set .I identifier to each set positional parameter instead. See the "Parameter Substitution" subsection. Execution ends when there are no more positional parameters or words in the list. .PP .ne 4v .CI function \0identifier\0 { \0list\0 ;\0} .br .IC identifier \0()\0{ \0list\0 ;\0} .IP Define a function named by .IR identifier . A function is called by executing its identifier as a command. The body of the function is the .I list of commands between .CR { and .CR } . See the "Functions" subsection. .PP .ne 3v .CI if \0list\0 ;\0then \0list\0 ; \0\f1[\c .CI elif \0list\0 ;\0then \0list\0 ; \f1]...\&\0[\c .CI else \0list\0 ; \f1]\0 fi .IP Execute the .CR if .I list and, if its exit status is zero, execute the first .CR then .IR list . Otherwise, execute the .CR elif .I list (if any) and, if its exit status is zero, execute the next .CR then .IR list . Failing that, execute the .CR else .I list (if any). If no .CR else .I list or .CR then .I list is executed, .CR if returns a zero exit status. .PP .ne 3v .CI select \0identifier\0\f1[ in \0word\f1\0...\&]\0 ;\0do \0list\0\c .CI ;\0done .IP Print the set of .IR word s on standard error (file descriptor 2), each preceded by a number. If .CI in .IR word .RI ...\& is omitted, print the positional parameters instead (see the "Parameter Substitution" subsection). Print the .CR PS3 prompt and read a line from standard input into the parameter .CR REPLY . If this line consists of the number of one of the listed .IR word s, set .I identifier to the corresponding .IR word , execute .IR list , and repeat the .CR PS3 prompt. If the line is empty, print the selection list again, and repeat the .CR PS3 prompt. Otherwise, set .I identifier to null, execute .IR list , and repeat the .CR PS3 prompt. The select loop repeats until a .CR break special command or end-of-file is encountered. .PP .ne 3v .CI time \0pipeline .IP Execute the .I pipeline and print the elapsed time, the user time, and the system time on standard error. See also .IR time (1). .PP .ne 3v .CI "until\0" list "\0;\0do\0" list "\0;\0done" .IP Execute the .CR until .IR list . If the exit status of the last command in the list is nonzero, execute the .CR do .IR list and execute the .CR until .IR list again. When the exit status of the last command in the .CR until .I list is zero, terminate the loop. If no commands in the .CR do .I list are executed, .CR until returns a zero exit status. .PP .ne 3v .CI "while\0" list "\0;\0do\0" list "\0;\0done" .IP Execute the .CR while .IR list . If the exit status of the last command in the list is zero, execute the .CR do .IR list and execute the .CR while .IR list again. When the exit status of the last command in the .CR while .I list is nonzero, terminate the loop. If no commands in the .CR do .I list are executed, .CR while returns a nonzero exit status. .PP .ne 3v .CI ( "\0list\0" ) .IP Execute .I list in a separate environment. If two adjacent open parentheses are needed for nesting, a space must be inserted between them to avoid arithmetic evaluation. .PP .ne 3v .CI { "\0list\0" ";\0}" .IP Execute .IR list , but not in a separate environment. Note that .CR { is a keyword and requires a trailing blank to be recognized. .PP .ne 3v .CI [[ "\0expression\0" ]] .IP Evaluate .I expression and return a zero exit status when .I expression is true. See the "Conditional Expressions" subsection for a description of .IR expression . Note that .CR [[ and .CR ]] are keywords and require blanks between them and .IR expression . .SS Special Commands Special commands are simple commands that are executed in the shell process. They permit input/output redirection. Unless otherwise indicated, file descriptor 1 (standard output) is the default output location and the exit status, when there are no syntax errors, is zero. .PP Commands that are marked with \(dg or \(dg\(dg are treated specially in the following ways: .RS .TP 3 .PD 0 1. Variable assignment lists preceding the command remain in effect when the command completes. .TP 2. I/O redirections are processed after variable assignments. .TP 3. Errors cause a script that contains them to abort. .TP 4. Words following a command preceded by \(dg\(dg that are in the format of a variable assignment are expanded with the same rules as a variable assignment. This means that tilde substitution is performed after the .CR = sign and word-splitting and file-name generation are not performed. .PD .RE .PP .ne 3v \(dg .CR : \0[\f2arg\f1]...\& .IP (colon)\0 Only expand parameters. A zero exit status is returned. .PP .ne 3v \(dg .CI . \0file\f1\0[\f2arg\f1]...\& .IP (period)\0 Read and execute commands from .I file and return. The commands are executed in the current shell environment. The search path specified by .CR PATH is used to find the directory containing .IR file . If any arguments .I arg are given, they become the positional parameters. Otherwise, the positional parameters are unchanged. The exit status is the exit status of the last command executed. .PP .ne 3v \(dg\(dg .CR alias \0[ \-tx ]\0[\f2name\f1[\c .CI = value\f1]\|]...\& .IP With .IC name = value specified, define .I name as an alias and assign it the value .IR value . A trailing space in .I value causes the next word to be checked for alias substitution. .IP With .IC name = value omitted, print the list of aliases in the form .IC name = value on standard output. .IP With .I name specified without .CI = value\f1, print the specified alias. .IP With .CR \-t , set tracked aliases. The value of a tracked alias is the full path name corresponding to the given .IR name . The value of a tracked alias becomes undefined when the value of .CR PATH is reset, but the alias remains tracked. With .IC name = value omitted, print the list of tracked aliases in the form .IC name = pathname on standard output. .IP With .CR \-x , set exported aliases. An exported alias is defined across subshell environments. With .IC name = value omitted, print the list of exported aliases in the form .IC name = value on standard output. .IP Alias returns true unless a .I name is given for which no alias has been defined. .PP .ne 3v .CR bg \0[\f2job\f1]...\& .IP Put the specified .I jobs into the background. The current job is put in the background if .I job is unspecified. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v \(dg .CR break \0[\f2n\f1] .IP Exit from the enclosing .CR for , .CR select , .CR until , or .CR while loop, if any. If .I n is specified, exit from .I n levels. .PP .ne 4v .CR cd \0[ \-L \(or \-P ]\0[\f2arg\f1] .br .CI cd \0old\0new .IP In the first form, change the current working directory .RC ( PWD ) to .IR arg . If .I arg is .CR \- , the directory is changed to the previous directory .RC ( OLDPWD ). .IP With .CR \-L (default), preserve logical naming when treating symbolic links. .CR "cd \-L ..\&" moves the current directory one path component closer to the root directory. .IP With .CR \-P , preserve the physical path when treating symbolic links. .CR "cd \-P ..\&" changes the working directory to the actual parent directory of the current directory. .IP The shell parameter .CR HOME is the default .IR arg . The parameter .CR PWD is set to the current directory. .IP The shell parameter .CR CDPATH defines the search path for the directory containing .IR arg . Alternative directory names are separated by a colon .RC ( : ). If .CR CDPATH is null or undefined, the default value is the current directory. Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If .I arg begins with a .CR / , the search path is not used. Otherwise, each directory in the path is searched for .IR arg . See also .IR cd (1). .IP The second form of .CR cd substitutes the string .I new for the string .I old in the current directory name, .CR PWD , and tries to change to this new directory. .PP .ne 3v .CR command \0[\f2arg\f1]...\& .IP Treat .I arg as a command, but disable function lookup on .IR arg . See .IR command (1) for usage and description. .PP .ne 3v \(dg .CR continue \0[\f2n\f1] .IP Resume the next iteration of the enclosing .CR for , .CR select , .CR until , or .CR while loop. If .I n is specified, resume at the .IR n th enclosing loop. .PP .ne 3v .CR echo \0[\f2arg\f1]...\& .IP Print .I arg on standard output. See .IR echo (1) for usage and description. See also the .CR print special command. .PP .ne 3v \(dg .CR eval \0[\f2arg\f1]...\& .IP Read the arguments as input to the shell and execute the resulting commands. Allows parameter substitution for keywords and characters that would otherwise be unrecognized in the resulting commands. .PP .ne 3v \(dg .CR exec \0[\f2arg\f1]...\& .IP Parameter assignments remain in effect after the command completes. If .I arg is given, execute the command specified by the arguments in place of this shell without creating a new process. Input/output arguments may appear and affect the current process. If no arguments are given, modify file descriptors as prescribed by the input/output redirection list. In this case, any file descriptor numbers greater than 2 that are opened with this mechanism are closed when another program is invoked. .PP .ne 3v \(dg .CR exit \0[\f2n\f1] .IP Exit from the shell with the exit status specified by .IR n . If .I n is omitted, the exit status is that of the last command executed. An end-of-file also causes the shell to exit, except when a shell has the .CR ignoreeof option set. (See the .CR set special command.) .PP .ne 4v \(dg\(dg .CR export \0[\f2name\f1[ = \f2value\f1]\|]...\& .br \(dg\(dg .CR export\0\-p .IP Mark the given variable .IR name s for automatic export to the environment of subsequently executed commands. Optionally, assign values to the variables. .IP With .CR \-p , write the names and values of all exported variables to standard output, in a format with the proper use of quoting, so that it is suitable for re-input to the shell as commands that achieve the same exporting results. .PP .ne 6v .CR fc \0[ \-r ]\0[ \-e \0\f2ename\f1]\0[\f2first\f1\0[\f2last\f1]\|] .br .CR fc\0\-l \0[ \-nr ]\0[\f2first\f1\0[\f2last\f1]\|] .br .CR fc\0\-s \0[\f2old\f1 = \f2new\f1]\0[\f2first] .br .CR fc\0\-e\0\- \0[\f2old\f1 = \f2new\f1]\0[\f2command\f1] .IP List, or edit and reexecute, commands previously entered to an interactive shell. A range of commands from .I first to .I last is selected from the last .CR HISTSIZE commands typed at the terminal. The arguments .I first and .I last can be specified as a number or string. A given string is used to locate the most recent command. A negative number is used to offset the current command number. .IP With .CR \-l , list the commands on standard output. Without .CR \-l , invoke the editor program .I ename on a file containing these keyboard commands. If .I ename is not supplied, the value of the parameter .CR FCEDIT (default .CR /usr/bin/ed ) is used as the editor. Once editing has ended, the commands (if any) are executed. If .I last is omitted, only the command specified by .I first is used. If .I first is not specified, the default is the previous command for editing and \(mi16 for listing. .IP With .CR \-r , reverse the order of the commands. .IP With .CR \-n , suppress command numbers when listing. .IP With .CR \-s , reexecute the command without invoking an editor. .IP The .IC old = new argument replaces the first occurrence of string .IC old in the command to be reexecuted by the string .IR new . .PP .ne 3v .CR fg \0[\f2job\f1]...\& .IP Bring each .I job into the foreground in the order specified. If no .I job is specified, bring the current job into the foreground. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v .CR getopts \0\f2optstring\0name\f1\0[\f2arg\f1]...\& .IP Parse the argument list, or the positional parameters if no arguments, for valid options. On each execution, return the next option in .IR name . See .IR getopts (1) for usage and description. .IP An option begins with a .CR + or a .CR \- . An argument not beginning with .CR + or .CR \- , or the argument .CR \-\- , ends the options. .I optstring contains the letters that .CR getopts recognizes. If a letter is followed by a .CR : , that option is expected to have an argument. The options can be separated from the argument by blanks. .IP For an option specified as .CI \- letter\f1, .I name is set to .IR letter . For an option specified as .CI + letter\f1, .I name is set to .CI + letter\f1. The index of the next .I arg is stored in .CR OPTIND . The option argument, if any, is stored in .CR OPTARG . If no option argument is found, or the option found does not take an argument, .CR OPTARG is unset. .IP A leading .CR :\& in .I optstring causes .CR getopts to store the letter of an invalid option in .CR OPTARG , and to set .I name to .CR ?\& for an unknown option and to .CR :\& when a required option argument is missing. Otherwise, .CR getopts prints an error message. The exit status is nonzero when there are no more options. .PP .ne 4v .CR hash \0[\f2utility\f1]...\& .br .CR hash\0\-r .IP Affect the way the current shell environment remembers the locations of utilities. With .IR utility , add utility locations to a list of remembered locations. With no arguments, print the contents of the list. With .CR \-r , forget all previously remembered utility locations. .PP .ne 3v .CR jobs \0[ \-lnp ]\0[\f2job\f1]...\& .IP List information about each given job, or all active jobs if .I job is not specified. With .CR \-l , list process IDs in addition to the normal information. With .CR \-n , display only jobs that have stopped or exited since last notified. With .CR \-p , list only the process group. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 5v .CR kill \0[ \-s \0\f2signal\f1]\0\f2process\f1\0...\& .br .CR kill\0\-l .br .CR kill \0[ \- \f2signal\f1]\0\f2process\f1\0...\& .IP Send either signal 15 .RC ( SIGTERM , terminate) or the specified .I signal to the specified jobs or processes. See .IR kill (1) for usage and description. .IP With .CR \-l , list the signal names and numbers. .PP .ne 4v .CI let \0arg\f1\0... .br .CI (( \0arg\f1\0... )) .IP Evaluate each .I arg as a separate arithmetic expression. See the "Arithmetic Evaluation" subsection for a description of arithmetic expression evaluation. The exit status is 0 if the value of the last expression is nonzero, and 1 otherwise. .PP .ne 3v \(dg .CR newgrp \0[ \- ]\0[\f2group\f1] .IP Replace the current shell with a new one having .I group as the user's group. The default group is the user's login group. With .CR \- , the user's .CR .profile and .CR $ENV files are also executed. See .IR newgrp (1) for usage and description. Equivalent to .CI "exec\0newgrp" "\0arg\0\f1...." .PP .ne 3v .CR print \0[ \-nprRsu [\f2n\f1]\|]\0[\f2arg\f1]...\& .IP The shell output mechanism. With no options or with option .CR \- or .CR \-\- , print the arguments on standard output as described in .IR echo (1). See also .IR printf (1). .IP With .CR \-n , do not add a newline character to the output. .IP With .CR \-p , write the arguments onto the pipe of the process spawned with .CR |& instead of standard output. .IP With .CR \-R or .CR \-r (raw mode), ignore the escape conventions of .CR echo . With .CR \-R , print all subsequent arguments and options other than .CR \-n . .IP With .CR \-s , write the arguments into the history file instead of to standard output. .IP With .CR \-u , specify a one-digit file descriptor unit number .I n on which the output will be placed. The default is .CR 1 (standard output). .PP .ne 3v .CR pwd \0[ \-L \(or \-P ] .IP Print the name of the current working directory (equivalent to .CR "print\0\-r\0\-\0$PWD" ). With .CR \-L (the default), preserve the logical meaning of the current directory. With .CR \-P , preserve the physical meaning of the current directory if it is a symbolic link. See also the .CR cd special command, .IR cd (1), .IR ln (1), and .IR pwd (1). .PP .ne 3v .CR read \0[ \-prsu [\f2n\f1]\|]\0[\f2name\f1 ? \f2prompt\f1]\0[\f2name\f1]...\& .IP The shell input mechanism. Read one line (by default, from standard input) and break it up into words using the characters in .CR IFS as separators. The first word is assigned to the first .IR name , the second word to the second .IR name , and so on; the remaining words are assigned to the last .IR name . See also .IR read (1). The return code is .CR 0 , unless an end-of-file is encountered. .IP With .CR \-p , take the input line from the input pipe of a process spawned by the shell using .CR |& . An end-of-file with .CR \-p causes cleanup for this process so that another process can be spawned. .IP With .CR \-r (raw mode), a .CR \e at the end of a line does not signify line continuation. .IP With .CR \-s , save the input as a command in the history file. .IP With .CR \-u , specify a one-digit file descriptor unit to read from. The file descriptor can be opened with the .CR exec special command. The default value of .I n is .CR 0 (standard input). If .IR name is omitted, .CR REPLY is used as the default .IR name . .IP If the first argument contains a .CR ? , the remainder of the argument is used as a .I prompt when the shell is interactive. .IP If the given file descriptor is open for writing and is a terminal device, the prompt is placed on that unit. Otherwise, the prompt is issued on file descriptor 2 (standard error). .PP .ne 4v \(dg\(dg .CR readonly \0[\f2name\f1[ = \f2value\f1]\|]...\& .br \(dg\(dg .CR readonly\0\-p .IP Mark the given .IR name s read only. These names cannot be changed by subsequent assignment. .IP With .CR \-p , write the names and values of all read-only variables to standard output in a format with the proper use of quoting so that it is suitable for re-input to the shell as commands that achieve the same attribute-setting results. .PP .ne 3v \(dg .CR return \0[\f2n\f1] .IP Cause a shell function to return to the invoking script with the return status specified by .IR n . If .I n is omitted, the return status is that of the last command executed. Only the low 8 bits of .I n (decimal 0 to 255) are passed back to the caller. If .CR return is invoked while not in a function or a .CR .\& script (see the .CR .\& special command), it has the same effect as an .CR exit command. .PP .ne 3v .CR set .RC [{ \- \(or + }\c .CR abCefhkmnopstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [{ \- \(or + } A .IR name ]\0[ arg ]...\& .IP Set .RC ( \- ) or clear .RC ( + ) execution options or perform array assignments .RC ( \-A ,\ +A ). All options except .CR \-A and .CR +A can be supplied in a shell invocation (see the SYNOPSIS section and the "Shell Invocation" subsection). .IP Using .CR + instead of .CR \- before an option causes the option to be turned off. These options can also be used when invoking the shell. The current list of set single-letter options is contained in the shell variable .CR \- . It can be examined with the command .CR "echo $-" . .IP The .CR \- and .CR + options can be intermixed in the same command, except that there can be only one .CR \-A or .CR +A option. .IP Unless .CR \-A or .CR +A is specified, the remaining .I arg arguments are assigned consecutively to the positional parameters .CR 1 , .CR 2 ,\0.... .IP The .CR set command with neither arguments nor options displays the names and values of all shell parameters on standard output. See also .IR env (1). .IP The options are defined as follows. .RS .TP .CR \-A Array assignment. Unset the variable .I name and assign values sequentially from the list .IR arg . With .CR \+A , do not unset the variable .I name first. .TP .CR \-a Automatically export subsequently defined parameters. .TP .CR \-b Cause the shell to notify the user asynchronously of background jobs as they are completed. When the shell notifies the user that a job has been completed, it can remove the job's process ID from the list of those known in the current shell execution environment. .TP .CR \-C Prevent redirection .CR > from truncating existing files. Requires .CR >| to truncate a file when turned on. .TP .CR \-e Execute the .CR ERR trap, if set, and exit .I if a command has a nonzero exit status, and is not part of the compound list following a .CR if , .CR until , or .CR while keyword, and is not part of an AND or OR list, and is not a pipeline preceded by the .CR !\& reserved word. This mode is disabled while reading profiles. .TP .CR \-f Disable file name generation. .TP .CR \-h Specify that each command whose name is an .I identifier becomes a tracked alias when first encountered. .TP .CR \-k Place all parameter assignment arguments (not just those that precede the command name) into the environment for a command. .TP .CR \-m Run background jobs in a separate process group and print a line upon completion. The exit status of background jobs is reported in a completion message. This option is turned on automatically for interactive shells. .TP .CR \-n Read commands and check them for syntax errors, but do not execute them. The .CR \-n option is ignored for interactive shells. .TP .ne 5v .CR \-o Set an .I option argument from the following list. Repeat the .CR \-o option to specify additional .I option arguments. .RS .TP 15 .PD 0 .CR allexport Same as .CR \-a . .TP .CR bgnice Run all background jobs at a lower priority. .TP .CR errexit Same as .CR \-e . .TP .CR emacs Use a .CR emacs -style inline editor for command entry. .TP .CR gmacs Use a .CR gmacs -style inline editor for command entry. .TP .CR ignoreeof Do not exit from the shell on end-of-file .RI ( eof as defined by .CR stty ; default is .CR ^D ). The .CR exit special command must be used. .TP .CR keyword Same as .CR \-k . .TP .CR markdirs Append a trailing .CR / to all directory names resulting from file name generation. .TP .CR monitor Same as .CR \-m . .TP .CR noclobber Same as .CR \-C . .TP .CR noexec Same as .CR \-n . .TP .CR noglob Same as .CR \-f . .TP .CR nolog Do not save function definitions in history file. .TP .CR notify Same as .CR \-b . .TP .CR nounset Same as .CR \-u . .TP .CR privileged Same as .CR \-p . .TP .CR verbose Same as .CR \-v . .TP .CR trackall Same as .CR \-h . .TP .CR vi Use a .CR vi -style inline editor for command entry. .TP .CR viraw Process each character as it is typed in .CR vi mode. .TP .CR xtrace Same as .CR \-x . .PD .RE .TP .CR \-p Disable processing of the .CR $HOME/.profile file and uses the file .CR /etc/suid_profile instead of the .CR ENV file. This mode is on whenever the effective user ID (group ID) is not equal to the real user ID (group ID). Turning this off causes the effective user ID and group ID to be set to the real user ID and group ID. .TP .CR \-s Sort the positional parameters. .TP .CR \-t Exit after reading and executing one command. .TP .CR \-u Treat unset parameters as an error when substituting. .TP .CR \-v Print shell input lines as they are read. .TP .CR \-x Print commands and their arguments as they are executed. .TP .CR \- Turn off .CR \-x and .CR \-v options and stop examining arguments for options. .TP .CR \-\- Do not change any of the options; useful in setting parameter .CR 1 to a value beginning with .CR \- . If no arguments follow this option, the positional parameters are unset. .RE .PP .ne 3v \(dg .CR shift "\0[\f2n\f1]" .IP Rename the positional parameters from .IC n +1 \f1\0...\& to .CR 1 \0.... The default value of .I n is .CR 1 . .I n can be any arithmetic expression that evaluates to a nonnegative number less than or equal to .CR $# . .PP .ne 3v .CR test \0[\f2expr\f1] .IP Evaluate conditional expression .IR expr . See .IR test (1) for usage and description. The arithmetic comparison operators are not restricted to integers. They allow any arithmetic expression. The following additional primitive expressions are allowed: .RS .TP 20 .PD 0 .CI \-L \0file True if .I file is a symbolic link. .TP .CI \-e \0file True if .I file exists. .TP .IC file1\0 \-nt \0file2 True if .I file1 is newer than .IR file2 . .TP .IC file1\0 \-ot \0file2 True if .I file1 is older than .IR file2 . .TP .IC file1\0 \-ef \0file2 True if .I file1 has the same device and i-node number as .IR file2 . .PD .RE .PP .ne 3v \(dg .CR times .IP Print the accumulated user and system times for the shell and for processes run from the shell. .PP .ne 3v \(dg .CR trap \0[\f2arg\f1]\0[\f2sig\f1]...\& .IP Set .I arg as a command that is read and executed when the shell receives a .IR sig signal. (Note that .I arg is scanned once when the trap is set and once when the trap is taken.) Each .I sig can be given as the number or name of a signal. Letter case is ignored. For example, .CR 3 , .CR QUIT , .CR quit , and .CR SIGQUIT all specify the same signal. Use .CR "kill \-l" to get a list of signals. .IP Trap commands are executed in signal number order. Any attempt to set a trap on a signal that was ignored upon entering the current shell is ineffective. .IP If .I arg is .CR \- (or if .I arg is omitted and the first .I sig is numeric), reset all traps for each .I sig to their original values. .IP If .I arg is the null string .RC ( '' or \&\c .C """""\c" ), each .I sig is ignored by the shell and by the commands it invokes. .IP If .I sig is .CR DEBUG , then .I arg is executed after each command. If .I sig is .CR ERR , .I arg is executed whenever a command has a nonzero exit code. If .I sig is .CR 0 or .CR EXIT and the .CR trap statement is executed inside the body of a function, the command .I arg is executed after the function completes. If .I sig is .CR 0 or .CR EXIT for a .CR trap set outside any function, the command .I arg is executed on exit from the shell. .IP With no arguments, print a list of commands associated with each signal name. .PP .ne 4v \(dg\(dg .CR typeset \0[{ \- \(or + }\c .CR LRZfilrtux [\f2n\f1]\|]\0[\f2name\f1[ = \f2value\f1]\|]... .br \(dg\(dg .IC name = value .RC [\f2name = \f2value\f1]...\& .IP Assign types and a value to a local named parameter .IR name . See also the .CR export special command. Parameter assignments remain in effect after the command completes. When invoked inside a function, create a new instance of the parameter .IR name . The parameter value and type are restored when the function completes. .IP The following list of attributes can be specified. Use .CR \+ instead of .CR \- to turn the options off. .RS .TP .CR \-L Left justify and remove leading blanks from .IR value . If .I n is nonzero, it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. When .I name is assigned, the value is filled on the right with blanks or truncated, if necessary, to fit into the field. Leading zeros are removed if the .CR \-Z option is also set. The .CR \-R option is turned off. Flagged as .CI leftjust \0n\f1. .TP .CR \-R Right justify and fill with leading blanks. If .I n is nonzero, it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. The field is left-filled with blanks or truncated from the end if the parameter is reassigned. The .CR \-L option is turned off. Flagged as .CI rightjust \0n\f1. .TP .CR \-Z Right justify and fill with leading zeros if the first nonblank character is a digit and the .CR \-L option has not been set. If .I n is nonzero it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. Flagged as .CI zerofill \0n\f1 plus the flag for .CR \-L or .CR \-R . .TP .CR \-f Cause .I name to refer to function names rather than parameter names. No assignments can be made to the .I name declared with the .CR typeset statement. The only other valid options are .CR \-t (which turns on execution tracing for this function) and .CR \-x (which allows the function to remain in effect across shell procedures executed in the same process environment). Flagged as .CR function . .TP .CR \-i Parameter is an integer. This makes arithmetic faster. If .I n is nonzero it defines the output arithmetic base; otherwise, the first assignment determines the output base. Flagged as .CR integer \0[ base \0\f2n\f1]. .TP .CR \-l Convert all uppercase characters to lowercase. The uppercase .CR \-u option is turned off. Flagged as .CR lowercase . .TP .CR \-r Mark any given .I name as "read only". The name cannot be changed by subsequent assignment. Flagged as .CR readonly . .TP .CR \-t Tag the named parameters. Tags are user-definable and have no special meaning to the shell. Flagged as .CR tagged . .TP .CR \-u Convert all lowercase characters to uppercase characters. The lowercase .CR \-l option is turned off. Flagged as .CR uppercase . .TP .CR \-x Mark any given .I name for automatic export to the environment of subsequently executed commands. Flagged as .CR export . .RE .IP .CR typeset alone displays a list of parameter names, prefixed by any flags specified above. .IP .CR "typeset \-" displays the parameter names followed by their values. Specify one or more of the option letters to restrict the list. Some options are incompatible with others. .IP .CR "typeset +" displays the parameter names alone. Specify one or more of the option letters to restrict the list. Some options are incompatible with others. .PP .ne 3v .CR ulimit \0[ \-HSacdfnst ]\0[\f2limit\f1] .IP Set or display a resource limit. The limit for a specified resource is set when .IR limit is specified. The value of .IR limit can be a number in the unit specified with each resource, or the keyword .CR unlimited . .IP The .CR \-H and .CR \-S flags specify whether the hard limit or the soft limit is set for the given resource. A hard limit cannot be increased once it is set. A soft limit can be increased up to the hard limit. If neither .CR \-H nor .CR \-S is specified, the limit applies to both. The current resource limit is printed when .IR limit is omitted. In this case, the soft limit is printed unless .CR \-H is specified. When more than one resource is specified, the limit name and unit are printed before the value. .IP If no option is given, .CR \-f is assumed. .RS .TP .PD 0 .CR \-a List all of the current resource limits. .TP .CR \-c The number of 512-byte blocks in the size of core dumps. .TP .CR \-d The number of kilobytes in the size of the data area. .TP .CR \-f The number of 512-byte blocks in files written by child processes (files of any size can be read). .TP .CR \-n The number of file descriptors. .TP .CR \-s The number of kilobytes in the size of the stack area. .TP .CR \-t The number of seconds to be used by each process. .PD .RE .PP .ne 3v .CR umask \0[ \-S ]\0[\f2mask\f1] .IP Set the user file-creation mask .IR mask . .I mask can be either an octal number or a symbolic value as described in .IR umask (1). A symbolic value shows permissions that are unmasked. An octal value shows permissions that are masked off. .IP Without .I mask , print the current value of the mask. With .CR \-S , print the value in symbolic format. Without .CR \-S , print the value as an octal number. The output from either form can be used as the .I mask of a subsequent invocation of .CR umask . .PP .ne 4v .CI unalias \0name\f1\0...\& .br .CR unalias\0\-a .IP Remove each .IR name from the alias list. With .CR \-a , remove all .CR alias definitions from the current shell execution environment. .PP .ne 3v .CR unset \0[ \-fv ]\0\f2name\f1\0...\& .IP Remove the named shell parameters from the parameter list. Their values and attributes are erased. Read-only variables cannot be unset. With .CR \-f , .IR name s refer to function names. With .CR \-v , .IR name s refer to variable names. Unsetting .CR _ , .CR ERRNO , .CR LINENO , .CR MAILCHECK , .CR OPTARG , .CR OPTIND , .CR RANDOM , .CR SECONDS , and .CR TMOUT removes their special meaning, even if they are subsequently assigned to. .PP .ne 3v \(dg .CR wait \0[\f2job\f1] .IP Wait for the specified .I job to terminate or stop, and report its status. This status becomes the return code for the .CR wait command. Without .I job , wait for all currently active child processes to terminate or stop. The termination status returned is that of the last process. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v .CR whence \0[ \-pv ]\0\f2name\f1\0...\& .IP For each .IR name , indicate how it would be interpreted if used as a command name. With .CR \-v , produce a more verbose report. With .CR \-p do a path search for .IR name , disregarding any use as an alias, a function, or a reserved word. .SS Comments A .I word beginning with .CR # causes that word and all the following characters up to a newline to be ignored. .SS Aliasing The first word of each command is replaced by the text of an .CR alias , if an .CR alias for this word has been defined. An .CR alias name consists of any number of characters excluding metacharacters, quoting characters, file expansion characters, parameter and command substitution characters, and =. The replacement string can contain any valid shell script, including the metacharacters listed above. The first word of each command in the replaced text, other than any that are in the process of being replaced, will be tested for additional aliases. If the last character of the alias value is a .IR blank , the word following the alias is also checked for alias substitution. Aliases can be used to redefine special commands, but cannot be used to redefine the keywords listed in the "Compound Commands" subsection. Aliases can be created, listed, and exported with the .CR alias command and can be removed with the .CR unalias command. Exported aliases remain in effect for subshells but must be reinitialized for separate invocations of the shell (see the "Shell Invocation" subsection). .PP Aliasing is performed when scripts are read, not while they are executed. Therefore, for it to take effect, an .CR alias must be executed before the command referring to the alias is read. .PP Aliases are frequently used as a shorthand for full path names. An option to the aliasing facility allows the value of the alias to be automatically set to the full path name of the corresponding command. These aliases are called .I tracked aliases. The value of a .I tracked alias is defined the first time the identifier is read and becomes undefined each time the .CR PATH variable is reset. These aliases remain .I tracked so that the next reference will redefine the value. Several tracked aliases are compiled into the shell. The .CR \-h option of the .CR set command converts each command name that is an .I identifier into a tracked alias. .PP The following .I exported aliases are compiled into the shell but can be unset or redefined: .nf .IP .C autoload='typeset \-fu' .C command='command ' .C functions='typeset \-f' .C history='fc \-l' .C integer='typeset \-i' .C local=typeset .C nohup='nohup ' .C r='fc \-e \-' .C stop='kill \-STOP' .C suspend='kill \-STOP $$' .C type='whence \-v' .SS Tilde Substitution After alias substitution is performed, each word is checked to see if it begins with an unquoted tilde .RC ( ~ ). If it does, the word up to a .CR / is checked to see if it matches a user name in the .CR /etc/passwd file. If a match is found, the .CR ~ and the matched login name are replaced by the login directory of the matched user. If no match is found, the original text is left unchanged. A .CR ~ alone or before a .CR / is replaced by the value of the .CR HOME parameter. A .CR ~ followed by a .CR + or .CR \- is replaced by the value of the parameter .CR PWD and .CR OLDPWD , respectively. In addition, tilde substitution is attempted when the value of a parameter assignment begins with a .CR ~ . .SS Command Substitution The standard output from a command enclosed in parenthesis preceded by a dollar sign .RC ( $( ...\& ) ) or a pair of grave accents .RC ( ` ...\& ` ) can be used as part or all of a word; trailing newlines are removed. In the second (archaic) form, the string between the accents is processed for special quoting characters before the command is executed. See the "Quoting" subsection. The command substitution .CR "$(cat file)" can be replaced by the equivalent but faster .CR $(\0\c ". .TP .CR PS3 Selection prompt string used within a .CR select loop. If unset, it defaults to "\c .CR #?\0\c ". .TP .CR PS4 Execution trace string that precedes each line of an execution trace. See the .CR "set \-x" special command. If unset, it defaults to "\c .CR +\0\c ". .TP .CR SHELL The path name of the shell is kept in the environment. When invoked, the shell is restricted if the value of this variable contains an .CR r in the base name. .TP .CR TMOUT If set to a value greater than zero, the shell will terminate if a command is not entered within the prescribed number of seconds after issuing the .CR PS1 prompt. (Note that the shell can be compiled with a maximum bound for this value which cannot be exceeded.) .TP .CR VISUAL Invokes the corresponding option when the value of this variable ends in .CR emacs , .CR gmacs , or .CR vi . See the .CR "set \-o" special command. .PP The shell gives default values to .CR IFS , .CR MAILCHECK , .CR PATH , .CR PS1 , .CR PS2 , and .CR TMOUT . On the other hand, .CR MAIL , .CR ENV , .CR HOME , and .CR SHELL are never set automatically by the shell (although .CR HOME , .CR MAIL , and .CR SHELL are set by .CR login ; see .IR login (1)). .SS Blank Interpretation After parameter and command substitution, the results of substitution are scanned for field separator characters (defined in .CR IFS ), and split into distinct arguments when such characters are found. .CR sh retains explicit null arguments (\c .C """""" or .CR '' ) but removes implicit null arguments (those resulting from parameters that have null values). .SS File Name Generation Following substitution, each command .I word is processed as a pattern for file name expansion unless expansion has been disabled with the .CR "set \-f" special command. The form of the patterns is the Pattern Matching Notation defined in .IR regexp (5). The word is replaced with sorted file names matching the pattern. If no file name is found that matches the pattern, the word is left unchanged. .PP In addition to the notation described in .IR regexp (5), .CR sh recognizes composite patterns made up of one or more pattern lists separated from each other with a .CR | . Composite patterns can be formed with one or more of the following: .RS .TP 18 .PD 0 .CI ?( pattern-list ) Matches any one of the given patterns. .TP .CI *( pattern-list ) Matches zero or more occurrences of the given patterns. .TP .CI +( pattern-list ) Matches one or more occurrences of the given patterns. .TP .CI @( pattern-list ) Matches exactly one of the given patterns. .TP .CI !( pattern-list ) Matches anything, except one of the given patterns. .PD .RE .SS Quoting Each of the metacharacters (see the "Definitions" subsection) has a special meaning to the shell and terminates a word unless quoted. A character may be .B quoted (that is, made to stand for itself) by preceding it with a backslash .RC ( \e ). The pair .CR \e newline is ignored; the current and following lines are concatenated. .PP All characters enclosed between a pair of apostrophes .RC ( ' ...\& ' ) are quoted. An apostrophe cannot appear within apostrophes. .PP Parameter and command substitution occurs inside quotation marks (\c .C """\c" \&...\&\c .C """\c" ). .CR \e quotes the characters .CR \e , .CR ` , .C """\c" , and .CR $ . .PP Inside grave accent marks .RC ( ` ...\& ` ), .CR \e quotes the characters .CR \e , .CR ` , and .CR $ . If the grave accents occur within quotation marks, .CR \e also quotes the character .C """\c" \&. .PP The meanings of .CR $* and .CR $@ are identical when not quoted or when used as a parameter assignment value or as a file name. However, when used as a command argument, .C """\c" .CR $*\c .C """" is equivalent to .C """\c" .CI $1 d $2 d\f1...\&\c .C """\c" , whereas .C """\c" .CR $@\c .C """" is equivalent to .C """\c" .CR $1\c .C """\c" .IR d\c .C """\c" .CR $2\c .C """\c" .IR d ...\& (where .I d is the first character of .CR IFS ), .PP The special meaning of keywords or aliases can be removed by quoting any character of the name. The recognition of function names or special command names cannot be altered by quoting them. .SS Arithmetic Evaluation Integer arithmetic is provided with the special command .CR let . Evaluations are performed using long integer arithmetic. Constants take the form .IC base # n or .IR n , where .I base is a decimal number between two and thirty-six representing the arithmetic base and .I n is a number in that base. If .IC base # is omitted, base 10 is used. .PP An arithmetic expression uses the same syntax, precedence, and associativity of expression as the C language. All the integral operators, other than .CR ++ , .CR \-\- , .CR ?: , and .CR , are supported. Variables can be referenced by name within an arithmetic expression without using the parameter substitution syntax. When a variable is referenced, its value is evaluated as an arithmetic expression. .PP A variable can be typed as an integer with the .CR \-i option of the .CR typeset special command, as in .CI typeset\0-i \f1[\f2base\f1]\f2\0name\f1. Arithmetic evaluation is performed on the value of each assignment to a variable with the .CR \-i attribute. If you do not specify an arithmetic base, the first assignment to the variable determines the arithmetic base. This base is used when parameter substitution occurs. .PP Since many of the arithmetic operators require quoting, an alternative form of the .CR let command is provided. For any command beginning with .CR (( , all characters until the matching .CR )) are treated as a quoted expression. More precisely, .CR (( ...\& )) is equivalent to .CR let .C """\c" .RC ...\c .C """\c" .RC . .SS Prompting When used interactively, the shell prompts with the value of .CR PS1 before reading a command. Whenever a newline is received and further input is needed to complete a command, the secondary prompt (the value of .CR PS2 ) is issued. .SS Conditional Expressions A .B "conditional expression" is used with the .CR [[ compound command to test attributes of files and to compare strings. Word splitting and file name generation are not performed on the words between .CR [[ and .CR ]] . Each expression can be constructed from one or more of the following unary or binary expressions: .RS .TP 20 .PD 0 .CI \-a \0file True, if .I file exists. .TP .CI \-b \0file True, if .I file exists and is a block special file. .TP .CI \-c \0file True, if .I file exists and is a character special file. .TP .CI \-d \0file True, if .I file exists and is a directory. .TP .CI \-e \0file True, if .I file exists. .TP .CI \-f \0file True, if .I file exists and is an ordinary file. .TP .CI \-g \0file True, if .I file exists and has its setgid bit set. .TP .CI \-h \0file True, if .I file exists and is a symbolic link. .TP .CI \-k \0file True, if .I file exists and has its sticky bit set. .TP .CI \-n \0string True, if length of .I string is nonzero. .TP .CI \-o \0option True, if the set option named .I option is on. .TP .CI \-p \0file True, if .I file exists and is a fifo special file or a pipe. .TP .CI \-r \0file True, if .I file exists and is readable by current process. .TP .CI \-s \0file True, if .I file exists and has a size greater than zero. .TP .CI \-t \0fildes True, if file descriptor number .I fildes is open and is associated with a terminal device. .TP .CI \-u \0file True, if .I file exists and has its setuid bit set. .TP .CI \-w \0file True, if .I file exists and is writable by the current process. .TP .CI \-x \0file True, if .I file exists and is executable by the current process. If .I file exists and is a directory, then the current process has permission to search in the directory. .TP .CI \-z \0string True, if length of .I string is zero. .TP .CI \-L \0file True, if .I file exists and is a symbolic link. .TP .CI \-O \0file True, if .I file exists and is owned by the effective user ID of this process. .TP .CI \-G \0file True, if .I file exists and its group matches the effective group ID of this process. .TP .CI \-S \0file True, if .I file exists and is a socket. .TP .IC file1\0 \-nt \0file2 True, if .I file1 exists and is newer than .IR file2 . .TP .IC file1\0 \-ot \0file2 True, if .I file1 exists and is older than .IR file2 . .TP .IC file1\0 \-ef \0file2 True, if .I file1 and .I file2 exist and refer to the same file. .TP .IC string\0 = \0pattern True, if .I string matches .IR pattern . .TP .IC string\0 != \0pattern True, if .I string does not match .IR pattern . .TP .IC string\0 < \0string2 True, if .I string1 comes before .I string2 based on the ASCII value of their characters. .TP .IC string\0 > \0string2 True, if .I string1 comes after .I string2 based on the ASCII value of their characters. .TP .IC exp1\0 \-eq \0exp2 True, if .I exp1 is equal to .IR exp2 . .TP .IC exp1\0 \-ne \0exp2 True, if .I exp1 is not equal to .IR exp2 . .TP .IC exp1\0 \-lt \0exp2 True, if .I exp1 is less than .IR exp2 . .TP .IC exp1\0 \-gt \0exp2 True, if .I exp1 is greater than .IR exp2 . .TP .IC exp1\0 \-le \0exp2 True, if .I exp1 is less than or equal to .IR exp2 . .TP .IC exp1\0 \-ge \0exp2 True, if .I exp1 is greater than or equal to .IR exp2 . .PD .RE .PP A compound expression can be constructed from these primitives by using any of the following, listed in decreasing order of precedence. .RS .TP 20 .PD 0 .CI ( exp ) True, if .I exp is true. Used to group expressions. .TP .CI ! exp True, if .I exp is false. .TP .IC exp1\0 && \0exp2 True, if .I exp1 and .I exp2 are both true. .TP .IC exp1\0 || \0exp2 True, if either .I exp1 or .I exp2 is true. .PD .RE .SS Input/Output Before a command is executed, its input and output can be redirected using a special notation interpreted by the shell. The following can appear anywhere in a simple-command or may precede or follow a command and are not passed on to the invoked command. Command and parameter substitution occurs before .I word or .I digit is used, except as noted below. File name generation occurs only if the pattern matches a single file and blank interpretation is not performed. .RS .TP 15 .CI < word Use file .I word as standard input (file descriptor .CR 0 ). .TP .CI > word Use file .I word as standard output (file descriptor .CR 1 ). If the file does not exist, it is created. If the file exists, and the .CR noclobber option is on, an error occurs; otherwise, the file is truncated to zero length. .TP .CI >| word Same as .CR > , except that it overrides the .CR noclobber option. .TP .CI >> word Use file .I word as standard output. If the file exists, output is appended to it (by first searching for the end-of-file); otherwise, the file is created. .TP .CI <> word Open file .I word for reading and writing as standard input. .TP .CR << [ \- ]\f2word The shell input is read up to a line that matches .IR word , or to an end-of-file. No parameter substitution, command substitution or file name generation is performed on .IR word . The resulting document, called a .IR here-document , becomes the standard input. If any character of .I word is quoted, no interpretation is placed upon the characters of the document. Otherwise, parameter and command substitution occurs, .CR \e newline is ignored, and .CR \e must be used to quote the characters .CR \e , .CR $ , .CR ` , and the first character of .IR word . If .CR \- is appended to .CR << , all leading tabs are stripped from .I word and from the document. .TP .CI <& digit The standard input is duplicated from file descriptor .I digit (see .IR dup (2)). .TP .CI >& digit The standard output is duplicated to file descriptor .I digit (see .IR dup (2)). .TP .CR <&- The standard input is closed. .TP .CR >&- The standard output is closed. .TP .CR <&p The input from the coprocess is moved to standard input. .TP .CR >&p The output to the coprocess is moved to standard output. .RE .RE .PP If any of the above redirections is preceded by a digit .RC ( 0 to .CR 9 ), the file descriptor used is the one specified by the digit, instead of the default .CR 0 (standard input) or .CR 1 (standard output). For example: .IP .CR 2>&1 .PP means open file descriptor 2 for writing as a duplicate of file descriptor 1. Output directed to file descriptor 2 is written in the same location as output to file descriptor 1. .PP Order is significant in redirection. The shell evaluates each redirection in terms of the .RI ( "file descriptor" ", " file ) assignment at the time of evaluation. For example: .IP .CR 1> \f2fname\0 2>&1 .PP first assigns file descriptor 1 to file .IR fname . It then assigns file descriptor 2 to the file assigned to file descriptor 1 (that is, .IR fname ). .PP If the order of redirection is reversed, as in .IP .CR 2>&1\01> \f2fname .PP file descriptor 2 is assigned to the file assigned to file descriptor 1 (probably the terminal) and then file descriptor 1 is assigned to file .IR fname . .PP By using the redirection operators above, the input and output of a .I coprocess may be moved to a numbered file descriptor, allowing other commands to write to them and read from them. If the input of the current coprocess is moved to a numbered file descriptor, another coprocess may be started. .PP If a command is followed by .CR & and job control is inactive, the default standard input for the command is the empty file .CR /dev/null . Otherwise, the environment for the execution of a command contains the file descriptors of the invoking shell as modified by input/output specifications. .SS Environment The .B environment (see .IR environ (5)) is a list of name-value pairs passed to an executed program much like a normal argument list. The names must be identifiers and the values are character strings. The shell interacts with the environment in several ways. When invoked, the shell scans the environment and creates a parameter for each name found, gives it the corresponding value and marks it .CR export . Executed commands inherit the environment. If the user modifies the values of these parameters or creates new ones by using the .CR export or .CR "typeset \-x" special commands, the values become part of the environment. The environment seen by any executed command is thus composed of any name-value pairs originally inherited by the shell, whose values may be modified by the current shell, plus any additions which must be noted in .CR export or .CR "typeset \-x" commands. .PP The environment for any simple command or function can be augmented by prefixing it with one or more parameter assignments. A parameter assignment argument takes the form .IC identifier = value\f1. For example, both the following .IP .CI TERM=450 "\0cmd\0args" .IP .CI "(export TERM; TERM=450;" "\0cmd\0args" ) .PP are equivalent (as far as the execution of .I cmd is concerned, except for the special commands that are preceded by a dagger (\(dg)). .PP If the .CR \-k option is set, all parameter assignment arguments are placed in the environment, even if they occur after the command name. The following echo statement prints .CR "a=b c" . After the .CR \-k option is set, the second echo statement prints only .CR c : .nf .IP .CR "echo a=b c" \0\(->\0 "a=b c" .CR "set \-k" .CR "echo a=b c" \0\(->\0 "c" .fi .PP This feature is intended for use with scripts written for early versions of the shell and its use in new scripts is strongly discouraged. It is likely to disappear someday. .SS Functions The .CR function command (described in the "Compound Commands" subsection) defines shell functions. Shell functions are read and stored internally. Alias names are resolved when the function is read. Functions are executed like commands, with the arguments passed as positional parameters. (See the "Execution" subsection.) .PP Functions execute in the same process as the caller and share all files and current working directory with the caller. Traps defined by the caller are reset to their default action inside the function. A trap condition that is not caught or ignored by the function causes the function to terminate and the condition to be passed on to the caller. A trap on .CR EXIT set inside a function is executed after the function completes in the environment of the caller. Ordinarily, variables are shared between the calling program and the function. However, the .CR typeset special command can be used within a function to define local variables whose scope includes the current function and all functions it calls. .PP The .CR return special command is used to return from function calls. Errors within functions return control to the caller. .PP Function identifiers can be listed with the .CR +f option of the .CR typeset special command. Function identifiers and the associated text of the functions can be listed with the .CR \-f option. Functions can be undefined with the .CR \-f option of the .CR unset special command. .PP Ordinarily, functions are unset when the shell executes a shell script. The .CR \-xf option of the .CR typeset command allows a function to be exported to scripts that are executed without reinvoking the shell. Functions that must be defined across separate invocations of the shell should be placed in the .CR ENV file. .SS Jobs If the .CR monitor option of the .CR set command is turned on, an interactive shell associates a .I job with each pipeline. It keeps a table of current jobs, printed by the .CR jobs command, and assigns them small integer numbers. When a job is started asynchronously with .CR & , the shell prints a line that looks like: .IP .C "[1] 1234" .PP indicating that job number 1 was started asynchronously and had one (top-level) process whose process ID was 1234. .PP If you are running a job and wish to do something else, you can type the suspend character (the .CR susp character defined with .CR stty ; see .IR stty (1)) to send a .CR SIGSTOP signal to the current job. The shell then indicates that the job has been .CR Stopped , and prints another prompt. Then you can manipulate the state of this job by putting it in the background with the .CR bg command, running other commands, and eventually returning the job to the foreground with the .CR fg command. A suspend takes effect immediately and resembles an interrupt, since pending output and unread input are discarded when the suspend is entered. .PP A job running in the background stops if it tries to read from the terminal. Background jobs normally are allowed to produce output, but can be disabled with the .CR "stty tostop" command. If the user sets this terminal option, background jobs stop when trying to produce output. .PP There are several ways to refer to jobs in the shell. A job can be referred to by the process ID of any process in the job or by one of the following: .RS .TP 20 .PD 0 .CI % number The job with the given number. .TP .CI % string Any job whose command line begins with .IR string . .TP .CI %? string Any job whose command line contains .IR string . .TP .CI %% Current job. .TP .CI %+ Equivalent to .CR %% . .TP .CR %- Previous job. .PD .RE .PP The shell learns immediately when a process changes state. It informs the user when a job is blocked and prevented from further progress, but only just before it prints a prompt. .PP When the monitor mode is on, each background job that completes triggers any trap set for .CR SIGCHLD . .PP If you try to exit from shell while jobs are stopped, you are warned with the message .CR "You have stopped jobs." You can use the .CR jobs command to identify them. If you immediately try to exit again, the shell will not warn you a second time, and the stopped jobs will be terminated. .PP If you try to leave the shell while jobs are running, you are not warned. The shell exits silently and sets the parent of the running jobs to the .CR init process (number 1). .SS Signals The .CR SIGINT and .CR SIGQUIT signals for an invoked command are ignored if the command is followed by .CR & and the .CR monitor option is off. Otherwise, signals have the values inherited by the shell from its parent, with the exception of signal .CR SIGSEGV (but see also the .CR trap special command). .SS Execution Substitutions are made each time a command is executed. .CR sh checks the command name to determine whether it matches a special command. If it does, it is executed within the current shell process. .PP Next, .CR sh checks the command name to determine whether it matches one of the user-defined functions. If it does, .CR sh saves the positional parameters, then sets them to the arguments of the function call. The positional parameter .CR 0 is unchanged. When the function completes or issues a .CR return , .CR sh restores the positional parameter list and executes any trap set on .CR EXIT within the function. The value of a function is the value of the last command executed. A function is executed in the current shell process. .PP If a command name is not a user-defined function or a special command, .CR sh creates a process and attempts to execute the command using an .CI exec * () system call (see .IR exec (2)). .PP The shell parameter .CR PATH defines the search path for the directory containing the command. Alternative directory names are separated by a colon .RC ( : ). The default path is .CR /usr/bin:\& (specifying .CR /usr/bin , and the current directory, in that order). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign, between colon delimiters, or at the end of the path list. The search path is not used if the command name contains a .CR / . Otherwise, each directory in the path is searched for an executable file. If the file has execute permissions but is not a directory or an executable object code file, it is assumed to be a script file, which is a file of data for an interpreter. If the first two characters of the script file are .CR #! , .CI exec * () expects an interpreter path name to follow. .CI exec * () then attempts to execute the specified interpreter as a separate process to read the entire script file. If a call to .CI exec * () fails, .CR sh is spawned to interpret the script file. All nonexported aliases, functions, and named parameters are removed in this case. If the shell command file does not have read permission, or if the .CR setuid and/or .CR setgid bits are set on the file, the shell executes an agent to set up the permissions and execute the shell with the shell command file passed down as an open file. A parenthesized command is also executed in a subshell without removing nonexported quantities. .SS Command Reentry The text of the last .CR HISTSIZE (default 128) commands entered from a terminal device is saved in a history file. The file .CR $HOME/.sh_history is used if the .CR HISTFILE variable is not set or writable. A shell can access the commands of all interactive shells that use the same named .CR HISTFILE . The special command .CR fc is used to list or edit a portion of this file. The portion of the file to be edited or listed can be selected by number or by giving the first character or characters of the command. A single command or range of commands can be specified. If you do not specify an editor program as an argument to .CR fc , the value of the parameter .CR FCEDIT is used. If .CR FCEDIT is not defined, .CR /usr/bin/ed is used. The edited command is printed and reexecuted upon leaving the editor. The editor name .CR \- is used to skip the editing phase and to reexecute the command. In this case, a substitution parameter of the form .IC old = new can be used to modify the command before execution. For example, if .CR r is aliased to .CR "fc \-e \-" , typing .CR "r bad=good c" reexecutes the most recent command that starts with the letter .CR c and replaces the first occurrence of the string .CR bad with the string .CR good . .SS Command Line Editing Normally, each command line typed at a terminal device is followed by a newline or return. If one of the .CR emacs , .CR gmacs , .CR vi , or .CR viraw , options is set, you can edit the command line. An editing option is automatically selected each time the .CR VISUAL or .CR EDITOR variable is assigned a value ending in one of these option names. .PP The editing features require that the user's terminal accept return without line feed and that a space ("\ ") must overwrite the current character on the screen. ADM terminal users should set the "space\ \(mi\ advance" switch to "space". Hewlett-Packard terminal users should set the straps to "bcGHxZ\ etX". .PP The editing modes enable the user to look through a window at the current line. The default window width is 80, unless the value of .CR COLUMNS is defined. If the line is longer than the window width minus two, a mark displayed at the end of the window notifies the user. The mark is one of: .RS .TP .PD 0 .CR > The line extends to the right. .TP .CR < The line extends to the left. .TP .CR * The line extends to both sides of the window. .PD .RE .PP As the cursor moves and reaches the window boundaries, the window is centered about the cursor. .PP The search commands in each edit mode provide access to the history file. Only strings are matched, not patterns, although a leading .CR ^ in the string restricts the match to begin at the first character in the line. .SS emacs Editing Mode This mode is invoked by either the .CR emacs or .CR gmacs option. Their sole difference is their handling of .CR ^T . To edit, the user moves the cursor to the point needing correction and inserts or deletes characters or words. All editing commands are control characters or escape sequences. The notation for control characters is caret .RC ( ^ ) followed by a character. For example, .CR ^F is the notation for Control-F. This is entered by holding down the Ctrl (control) key and pressing .CR f . The shift key is .I not pressed. The notation .CR ^?\& indicates the delete (DEL) key. .PP The notation for escape sequences is .CR M- followed by a character. For example, .CR M-f (pronounced .IR "meta f" ) is entered by pressing the escape key (ESC) followed by pressing .CR f . .CR M-F is the notation for escape followed by shift (capital) .CR F . .PP All edit commands operate from any place on the line (not only at the beginning). Neither the return .RC ( ^M ) nor the newline .RC ( ^J ) key is entered after edit commands, except when noted. .RS .TP 15 .PD 0 .CR ^F Move cursor forward (right) one character. .TP .CR M-f Move cursor forward one word. (The editor's idea of a word is a string of characters consisting of only letters, digits and underscores.) .TP .CR ^B Move cursor backward (left) one character. .TP .CR M-b Move cursor backward one word. .TP .CR ^A Move cursor to start of line. .TP .CR ^E Move cursor to end of line. .TP .CI ^] char Move cursor forward to character .I char on current line. .TP .CI M-^] char Move cursor backward to character .I char on current line. .TP .CI ^X^X Interchange the cursor and mark. .TP .I erase Delete previous character. (User-defined erase character as defined by the .CR stty command, usually .CR ^H or .CR # .) .TP .CR ^D Delete current character. .TP .I eof Terminate the shell if the current line is null. (User-defined end-of-file character as defined by the .CR stty command, usually .CR ^D .) .TP .CI M-d Delete current word. .TP .CI M-^H Delete previous word. (meta-backspace) .TP .CI M-h Delete previous word. .TP .CI M-^?\& Delete previous word. (meta-delete) If your interrupt character is .CR ^?\& (DEL, the default), this command will not work. .TP .CI ^T In .CR emacs mode, transpose current character with next character. In .CR gmacs mode, transpose two previous characters. .TP .CI ^C Capitalize current character. .TP .CI M-c Capitalize current word. .TP .CI M-l Change the current word to lowercase. .TP .CI ^K Delete from the cursor to the end of the line. If preceded by a numerical parameter whose value is less that the current cursor position, then delete from the given position up to the cursor. If preceded by a numerical parameter whose value is greater than the current cursor position, then delete from the cursor up to the given position. .TP .CI ^W Kill from the cursor to the mark. .TP .CI M-p Push the region from the cursor to the mark on the stack. .TP .I kill Kill the entire current line. If two kill characters are entered in succession, all subsequent consecutive kill characters cause a line feed (useful when using paper terminals). (User-defined kill character as defined by the .CR stty command, usually .CR ^X or .CR @ .) .TP .CI ^Y Restore last item removed from line. (Yank item back to the line.) .TP .CI ^L Line feed and print current line. .TP .CR ^@ Set mark. (null character) .TP .CI M-\0 Set mark. (meta-space) .TP .CI ^J Execute the current line. (newline) .TP .CI ^M Execute the current line. (return) .TP .CI ^P Fetch previous command. Each time .CR ^P is entered, the previous command in the history list is accessed. .TP .CI ^N Fetch next command. Each time .CR ^N is entered the next command in the history list is accessed. .TP .CI M-< Fetch the least recent (oldest) history line. .TP .CI M-> Fetch the most recent (youngest) history line. .TP .CI ^R string Reverse search history for a previous command line containing .IR string . If a parameter of zero is given, the search is forward. .I string is terminated by a return or newline. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is omitted, the next command line containing the most recent .I string is accessed. In this case, a parameter of zero reverses the direction of the search. .TP .CR ^O Execute the current line and fetch the next line relative to current line from the history file. .TP .CI M- digits Define a numeric parameter. The digits are taken as a parameter to the next command. The commands that accept a parameter are .IR erase , .CR ^B , .CR ^C , .CR ^D , .CR ^F , .CR ^K , .CR ^N , .CR ^P , .CR ^R , .CR ^] , .CR M-^H , .CR M-. , .CR M-_ , .CR M-b , .CR M-c , .CR M-d , .CR M-f , .CR M-h , and .CR M-l . .TP .CI M- letter Your alias list is searched for an alias by the name .CI _ letter (underscore-letter). If an alias of this name is defined, its value is inserted on the input queue. This .I letter must not be one of the above metafunctions. .TP .CR M-. The last word of the previous command is inserted on the line. If preceded by a numeric parameter, the value of this parameter determines which word to insert rather than the last word. .TP .CR M-_ Same as .CR M-. . .TP .CR M-* Attempt file name generation on the current word. .TP .CR M-^[ File name completion. (meta-escape.) Replaces the current word with the longest common prefix of all file names matching the current word with an asterisk appended. If the match is unique, a .CR / is appended if the file is a directory and a space is appended if the file is not a directory. .TP .CR M-= List files matching current word pattern as if an asterisk were appended. .TP .CR ^U Multiply parameter of next command by 4. .TP .CR \e Escape next character. Editing characters and your erase, kill, and interrupt characters may be entered in a command line or in a search string, if preceded by a .CR \e . The .CR \e removes the next character's editing features (if any). .TP .CI ^V Display version of the shell. .TP .CI M-# Insert a .CR # at the beginning of the line and execute it. This causes a comment to be inserted in the history file. .PD .RE .SS vi Editing Mode The editor starts in insert mode until an escape (ESC) is received. This puts you in control mode in which you can move the cursor and perform editing commands. A return in either mode sends the line. .PP Most control commands accept an optional repeat .I count prior to the command. .PP In .CR vi mode on most systems, canonical processing is initially enabled and the command is echoed again if the speed is 1200 baud or greater and contains any control characters, or if less than one second has elapsed since the prompt was printed. The escape (ESC) character terminates canonical processing for the remainder of the command and you can then modify the command line. This scheme has the advantages of canonical processing with the typeahead echoing of raw mode. .PP Setting the .CR viraw option always disables canonical processing on the terminal. This mode is implicit for systems that do not support two alternate end-of-line delimiters, and may be helpful for certain terminals. .PP .B Insert Edit Commands .PP By default, the editor is in insert mode. .RS .TP 15 .PD 0 .I erase Delete previous inserted character. The .IR erase character is user-definable with the .CR stty command, usually set to .CR ^H . The system default is .CR # . .TP .I kill Delete all current inserted characters. The .IR kill character is user-definable with the .CR stty command, usually set to .CR ^X or .CR ^U . The system default is .CR @ . .TP .CR \e Escape the next .I erase or .I kill character. .TP .CR ^D Terminate the shell. .TP .CR ^V Escape next character. Editing characters and erase or kill characters may be entered in a command line or in a search string if preceded by a .CR ^V , which removes the next character's editing features (if any). .TP .CR ^W Delete the previous blank-separated word. .PD .RE .PP .B Motion Edit Commands .PP These commands move the cursor. The use of .IR count causes a repetition of the command the cited number of times. .RS .TP 15 .PD 0 .RC [\f2count\f1] l Cursor forward (right) one character. .TP .RC [\f2count\f1] w Cursor forward one alphanumeric word. .TP .RC [\f2count\f1] W Cursor forward to the beginning of the next word that follows a blank. .TP .RC [\f2count\f1] e Cursor forward to the end of the word. .TP .RC [\f2count\f1] E Cursor forward to end of the current blank-delimited word. .TP .RC [\f2count\f1] h Cursor backward (left) one character. .TP .RC [\f2count\f1] b Cursor backward one word. .TP .RC [\f2count\f1] B Cursor backward to preceding blank-separated word. .TP .RC [\f2count\f1] | Cursor to column .IR count . Default is 1. .TP .RC [\f2count\f1] f \f2c Find the next character .IR c in the current line. .TP .RC [\f2count\f1] F \f2c Find the previous character .IR c in the current line. .TP .RC [\f2count\f1] t \f2c Equivalent to .CI f c followed by .CR h . .TP .RC [\f2count\f1] T \f2c Equivalent to .CI F c followed by .CR l . .TP .RC [\f2count\f1] ; Repeat the last single-character find command, .CR f , .CR F , .CR t , or .CR T . .TP .RC [\f2count\f1] , Reverses the last single character find command. .TP .CR 0 Cursor to start of line. .TP .CR ^ Cursor to first nonblank character in line. .TP .CR $ Cursor to end of line. .PD .RE .PP .B History Search Commands .PP These commands access your command history file. .RS .TP 15 .PD 0 .RC [\f2count\f1] k Fetch previous command. Each time .CR k is entered, the next earlier command in the history list is accessed. .TP .RC [\f2count\f1] \- Equivalent to .CR k . .TP .RC [\f2count\f1] j Fetch next command. Each time .CR j is entered, the next later command in the history list is accessed. .TP .RC [\f2count\f1] + Equivalent to .CR j . .TP .RC [\f2count\f1] G The command number .I count is fetched. The default is the first command in the history list. .TP .CI / string Search backward through history for a previous command containing .IR string . .I string is terminated by a return or newline. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is null, the previous string is used. .TP .CI ? string Same as .CR / , but search in the forward direction. .TP .CR n Search for next match of the last pattern to the .CR / or .CR ? commands. .TP .CR N Search for next match of the last pattern to .CR / or .CR ? , but in reverse direction. .PD .RE .PP .B Text Modification Edit Commands .PP These commands will modify the line. .RS .TP 15 .PD 0 .CR a Enter insert mode after the current character. .TP .CR A Append text to the end of the line. Equivalent to .CR $a . .TP .RC [\f2count\f1] c \f2motion .TP .CR c [\f2count\f1]\f2motion Move cursor forward to the character position specified by .IR motion , deleting all characters between the original cursor position and the new position, and enter insert mode. If .I motion is .CR c , the entire line is deleted. .TP .CR C Delete from the current character through the end of line and enter insert mode. Equivalent to .CR c$ . .TP .CR S Equivalent to .CR cc . .TP .RC [\f2count\f1] d \f2motion .TP .CR d [\f2count\f1]\f2motion Move cursor to the character position specified by .IR motion , deleting all characters between the original cursor position and the new position. If .I motion is .CR d , the entire line will be deleted. .TP .CR D Delete from the current character through the end of line. Equivalent to .CR d$ . .TP .CR i Enter insert mode before the current character. .TP .CR I Enter insert mode before the beginning of the line. Equivalent to the two-character sequence .CR 0i . .TP .RC [\f2count\f1] P Insert the previous text modification before the cursor. .TP .RC [\f2count\f1] p Insert the previous text modification after the cursor. .TP .CR R Enter insert mode and replace characters on the screen with characters you type, overlay fashion. .TP .RC [\f2count\f1] r \f2c Replace the current character with .IR c . .TP .RC [\f2count\f1] x Delete the current character. .TP .RC [\f2count\f1] X Delete the preceding character. .TP .RC [\f2count\f1] . Repeat the previous text modification command. .TP .CR ~ Invert the case of the current character and advance the cursor. .TP .RC [\f2count\f1] _ Append the .I count word of the previous command at the current cursor location and enter insert mode at the end of the appended text. The last word is used if .I count is omitted. .TP .CR * Append an .CR * to the current word and attempt file name generation. If no match is found, ring the bell. If a match is found, replace the word with the matching string of file names and enter insert mode. .TP escape .TP .CR \e Attempt file name completion on the current word. Replace the current word with the longest common prefix of all file names matching the current word with an asterisk appended. If the match is unique, append a .CR / if the file is a directory or append a space if the file is not a directory. .PD .RE .PP .B Other Edit Commands .PP .RS .TP 15 .PD 0 .RC [\f2count\f1] y \f2motion .TP .CR y [\f2count\f1]\f2motion Yank current character through character that .I motion would move the cursor to and put them into the delete buffer. The text and cursor are unchanged. .TP .CR Y Yank from current position to end of line. Equivalent to .CR y$ . .TP .CR u Undo the last text-modifying command. .TP .CR U Undo all the text-modifying commands performed on the line. .TP .RC [\f2count\f1] v Execute the command .CI "fc \-e ${VISUAL:-${EDITOR:-vi}}" " count" in the input buffer. If .I count is omitted, the current line is used. This executes an editor with the current line as the input "file". When you exit from the editor, the result is executed. .TP .CR ^L Line feed and print current line. .TP .CR ^J Execute the current line, regardless of mode. (newline) .TP .CR ^M Execute the current line, regardless of mode. (return) .TP .CR # Insert a .CR # at the beginning of the current line and after each embedded newline, and execute the line. Useful for inserting the current command line in the history list without executing it. .TP .CR = List the file names that match the current word if an asterisk were appended to it. .TP .CI @ letter Search your alias list for an alias with the name .CI _ letter (underscore letter). If an alias of this name is defined, its value is executed as a command sequence on the current line. This provides a simple macro capability. .PD .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. If it is not defined or is empty, it defaults to the value of .CR LANG . .PP .CR LC_CTYPE determines the classification of characters as letters, and the characters matched by character class expressions in pattern matching notation. If it is not defined or is empty, it defaults to the value of .CR LANG . .PP If .CR LANG is not defined or is empty, it defaults to .CR C (see .IR lang (5)). .PP If any internationalization variable contains an invalid value, they all default to .CR C (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH RETURN VALUE Errors detected by the shell, such as syntax errors, cause the shell to return a nonzero exit status. Otherwise, the shell returns the exit status of the last command executed. See also the .CR exit special command. If the shell is being used noninteractively, the execution of the shell file is abandoned. Runtime errors detected by the shell are reported by printing the command or function name and the error condition. If the line number on which the error occurred is greater than one, the line number is also printed in brackets .RC ( [] ) after the command or function name. .\".SH EXAMPLES .\" none appropriate. .SH WARNINGS .PP .\" File descriptors 54 through 60 are used internally by the POSIX shell. File descriptors 24 through 30 are used internally by the POSIX shell. Applications using these and forking a subshell should not depend upon them surviving in the subshell or its descendants. .PP If a command that is a tracked alias is executed, and a command with the same name is installed in a directory in the search path before the directory where the original command was found, the shell will continue to load and execute the original command. Use the .CR \-t option of the .CR alias command to correct this situation. .PP If you move the current directory or one above it, .CR pwd may not give the correct response. Use the .CR cd command with a full path name to correct this situation. .PP Some very old shell scripts use a caret .RC ( ^ ) as a synonym for the pipe character .RC ( | ). .CR sh .I "does not" recognize the caret as a pipe character. .PP If a command is piped into a shell command, all variables set in the shell command are lost when the command completes. .PP Using the .CR fc built-in command within a compound command will cause the entire command to disappear from the history file. .PP The dot .RC ( . ) special command, as in .CI .\& " file\f1," reads the entire file before any commands are executed. Therefore, .CR alias and .CR unalias commands in the file will not apply to any functions defined in the file. .PP Traps are not processed while the shell is waiting for a foreground job. Thus, a trap on .CR SIGCHLD is not executed until the foreground job terminates. .PP The .CR export special command does not handle arrays properly. Only the first element of an array is exported to the environment. .PP Background processes started from a noninteractive shell cannot be accessed with job control commands. .PP The value of the .CR IFS variable in the user's environment affects the behavior of scripts. .SS Collating Order In an international environment, character ordering is determined by the value of .CR LC_COLLATE , rather than by the binary ordering of character values in the machine collating sequence. This brings with it certain attendant dangers, particularly when using range expressions in file name generation patterns. For example, the command, .IP .C "rm [a-z]*" .PP might be expected to match all file names beginning with a lowercase alphabetic character. However, if dictionary ordering is specified by .CR LC_COLLATE , it would also match file names beginning with an uppercase character (as well as those beginning with accented letters). Conversely, it would fail to match letters collated after .CR z in languages such as Danish or Norwegian. .PP The correct (and safe) way to match specific character classes in an international environment is to use a pattern (see .IR regexp (5)) of the form: .IP .C "rm [[:lower:]]*" .PP This uses .CR LC_CTYPE to determine character classes and works predictably for all supported languages and codesets. For shell scripts produced on noninternationalized systems (or without consideration for the above dangers), it is recommended that they be executed in a non-NLS environment. This requires that .CR LANG , .CR LC_COLLATE , and so on, be set to .CR C or not set at all. .SS History File Changes At HP-UX release B.10.10, the history file has a new internal magic number. This will cause a pre-B.10.10 history file to be discarded. Users who use multiple versions of HP-UX that NFS-mount the same directory that contains the history file (usually the home directory) may want to create a separate history file for each HP-UX version by setting the .CR HISTFILE parameter as: .IP .C "HISTFILE=$HOME/.sh_hist_$(uname \-r)" .PP Users on windowing systems may want to have separate history files for each window by setting the HISTFILE parameter as follows: .IP .C "HISTFILE=$HOME/.sh_hist$$" .PP A .CR cron job may be used to delete old history files. .PP The history file does not support mixing of locales in the same file. For users of multiple locales, you can assign a unique history file for each locale by setting .CR HISTFILE as: .IP .C "HISTFILE=$HOME/.sh_hist_${LANG}" .PP or include the process number in the .CR HISTFILE parameter as shown above. .SH AUTHOR .CR sh was developed by AT&T, OSF, and HP. .SH FILES .TP 30 .PD 0 .CR $HOME/.profile Read to set up user's custom environment .TP .CR /etc/passwd To find home directories .TP .CR /etc/profile Read to set up system environment .TP .CR /etc/suid_profile Security profile .TP .CR /tmp/sh* For here-documents .TP .CR /usr/bin/sh Shell executable program location .PD .SH SEE ALSO cat(1), cd(1), command(1), echo(1), ed(1), env(1), getopts(1), kill(1), ln(1), login(1), newgrp(1), printf(1), pwd(1), read(1), stty(1), test(1), time(1), umask(1), vi(1), dup(2), exec(2), fork(2), pipe(2), stty(2), ulimit(2), umask(2), wait(2), rand(3C), a.out(4), profile(4), environ(5), lang(5), regexp(5), signal(5). .SH STANDARDS CONFORMANCE .CR sh ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR . ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR : ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR break ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR case ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR continue ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR eval ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR exec ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR exit ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR export ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR for ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR if ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR read ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR return ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR set ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR shift ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR time ": SVID2, SVID3, XPG2, XPG3, XPG4" .br .CR trap ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR unset ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR until ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR while ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4sh\f1 \- shell based on POSIX.2@@@\f3sh-posix(1)\f1 .\" index@\f4alias\f1 \- substitute command and/or file name@@@\f3sh-posix(1)\f1 .\" index@\f4break\f1 \- exit from enclosing for/next loop@@@\f3sh-posix(1)\f1 .\" index@\f4case\f1 \- execute \f2list\f1 associated with \f2pattern\f1 that matches \f2word\f1@@@\f3sh-posix(1)\f1 .\" index@\f4cd\f1 \- change working directory@@@\f3sh-posix(1)\f1 .\" index@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@\f3sh-posix(1)\f1 .\" index@\f4echo\f1 \- echo (print) arguments@@@\f3sh-posix(1)\f1 .\" index@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@\f3sh-posix(1)\f1 .\" index@\f4exec\f1 \- execute command without creating new process@@@\f3sh-posix(1)\f1 .\" index@\f4exit\f1 \- exit shell with exit status@@@\f3sh-posix(1)\f1 .\" index@\f4export\f1 \- export variable names to environment of subsequent commands@@@\f3sh-posix(1)\f1 .\" index@\f4fc\f1 \- edit and execute previous command@@@\f3sh-posix(1)\f1 .\" index@\f4for\f1 \- execute a do list@@@\f3sh-posix(1)\f1 .\" index@\f4if\f1 \- execute command if previous command returns exit status 0@@@\f3sh-posix(1)\f1 .\" index@\f4jobs\f1 \- list active jobs@@@\f3sh-posix(1)\f1 .\" index@\f4kill\f1 \- terminate job or process@@@\f3sh-posix(1)\f1 .\" index@\f4let\f1 \- evaluate arithmetic expression@@@\f3sh-posix(1)\f1 .\" index@\f4newgrp\f1 \- equivalent to \f4exec newgrp\f1@@@\f3sh-posix(1)\f1 .\" index@\f4print\f1 \- output from shell@@@\f3sh-posix(1)\f1 .\" index@\f4pwd\f1 \- print current working directory@@@\f3sh-posix(1)\f1 .\" index@\f4read\f1 \- input and parse a line@@@\f3sh-posix(1)\f1 .\" index@\f4readonly\f1 \- mark names as unredefinable@@@\f3sh-posix(1)\f1 .\" index@\f4return\f1 \- shell function return to invoking script@@@\f3sh-posix(1)\f1 .\" index@\f4set\f1 \- set/define options and arguments@@@\f3sh-posix(1)\f1 .\" index@\f4shift\f1 \- shift \f2argv\f1 members one position to left@@@\f3sh-posix(1)\f1 .\" index@\f4test\f1 \- evaluate conditional expression@@@\f3sh-posix(1)\f1 .\" index@\f4time\f1, \f4times\f1 \- print summary of time used by processes@@@\f3sh-posix(1)\f1 .\" index@\f4trap\f1 \- trap specified signal@@@\f3sh-posix(1)\f1 .\" index@\f4typeset\f1 \- control leading blanks and parameter handling@@@\f3sh-posix(1)\f1 .\" index@\f4ulimit\f1 \- set size or time limits@@@\f3sh-posix(1)\f1 .\" index@\f4umask\f1 \- set permissions mask for creating new files@@@\f3sh-posix(1)\f1 .\" index@\f4unalias\f1 \- discard specified alias@@@\f3sh-posix(1)\f1 .\" index@\f4unset\f1 \- remove definition/setting of options and arguments@@@\f3sh-posix(1)\f1 .\" index@\f4until\f1 \- execute commands until expression is nonzero@@@\f3sh-posix(1)\f1 .\" index@\f4wait\f1 \- wait for child process@@@\f3sh-posix(1)\f1 .\" index@\f4whence\f1 \- define interpretation of name as a command@@@\f3sh-posix(1)\f1 .\" index@\f4while\f1 \- execute commands while expression is nonzero@@@\f3sh-posix(1)\f1 .\" .\" toc@\f3sh-posix(1)\f1:\0\0\f4sh\f1@@@shell, the standard/restricted command programming language .\" toc@\f4case\f1 \- label in a switch statement@@@see \f3sh-posix(1)\f1 .\" toc@\f4alias\f1 \- substitute command and/or file name@@@see \f3sh-posix(1)\f1 .\" toc@\f4break\f1 \- exit from enclosing for/next loop@@@see \f3sh-posix(1)\f1 .\" toc@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@see \f3sh-posix(1)\f1 .\" toc@\f4cd\f1 \- change working directory@@@see \f3sh-posix(1)\f1 .\" toc@\f4echo\f1 \- echo (print) arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@see \f3sh-posix(1)\f1 .\" toc@\f4exec\f1 \- execute command without creating new process@@@see \f3sh-posix(1)\f1 .\" toc@\f4exit\f1 \- exit shell with exit status@@@see \f3sh-posix(1)\f1 .\" toc@\f4export\f1 \- export variable names to environment of subsequent commands@@@see \f3sh-posix(1)\f1 .\" toc@\f4fc\f1 \- edit and execute previous command@@@see \f3sh-posix(1)\f1 .\" toc@\f4for\f1 \- execute a do list@@@see \f3sh-posix(1)\f1 .\" toc@\f4if\f1 \- execute command if previous command returns exit status 0@@@see \f3sh-posix(1)\f1 .\" toc@\f4jobs\f1 \- list active jobs@@@see \f3sh-posix(1)\f1 .\" toc@\f4kill\f1 \- terminate job or process@@@see \f3sh-posix(1)\f1 .\" toc@\f4let\f1 \- evaluate arithmetic expression@@@see \f3sh-posix(1)\f1 .\" toc@\f4newgrp\f1 \- equivalent to \f2exec newgrp\f1@@@see \f3sh-posix(1)\f1 .\" toc@\f4print\f1 \- output from shell@@@see \f3sh-posix(1)\f1 .\" toc@\f4pwd\f1 \- print current working directory@@@see \f3sh-posix(1)\f1 .\" toc@\f4read\f1 \- input and parse a line@@@see \f3sh-posix(1)\f1 .\" toc@\f4readonly\f1 \- mark names as unredefinable@@@see \f3sh-posix(1)\f1 .\" toc@\f4return\f1 \- shell function return to invoking script@@@see \f3sh-posix(1)\f1 .\" toc@\f4set\f1 \- set/define options and arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4shift\f1 \- shift \f2argv\f1 members one position to left@@@see \f3sh-posix(1)\f1 .\" toc@\f4test\f1 \- evaluate conditional expression@@@see \f3sh-posix(1)\f1 .\" toc@\f4trap\f1 \- trap specified signal@@@see \f3sh-posix(1)\f1 .\" toc@\f4time, times\f1 \- print summary of time used by processes@@@see \f3sh-posix(1)\f1 .\" toc@\f4typeset\f1 \- control leading blanks and parameter handling@@@see \f3sh-posix(1)\f1 .\" toc@\f4ulimit\f1 \- set size or time limits@@@see \f3sh-posix(1)\f1 .\" toc@\f4umask\f1 \- set permissions mask for creating new files@@@see \f3sh-posix(1)\f1 .\" toc@\f4unalias\f1 \- discard specified alias@@@see \f3sh-posix(1)\f1 .\" toc@\f4unset\f1 \- remove definition/setting of options and arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4wait\f1 \- wait for child process@@@see \f3sh-posix(1)\f1 .\" toc@\f4whence\f1 \- define interpretation of name as a command@@@see \f3sh-posix(1)\f1 .\" toc@\f4while\f1 \- execute commands while expression is nonzero@@@see \f3sh-posix(1)\f1 .\" toc@\f4until\f1 \- execute commands until expression is nonzero@@@see \f3sh-posix(1)\f1 .\" .\" links@sh-posix.1 alias.1 .\" links@sh-posix.1 bg.1 .\" links@sh-posix.1 fc.1 .\" links@sh-posix.1 fg.1 .\" links@sh-posix.1 jobs.1 .\" links@sh-posix.1 unalias.1 .\" $Header: grep.1,v 76.1 95/08/23 17:54:30 ssa Exp $ .TA g .TH grep 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME grep, egrep, fgrep \- search a file for a pattern .SH SYNOPSIS .SS Plain call with pattern .C grep .RC [ -E \|\(or\| -F ] .RC [ -c \(or -l \c .RC \(or -q ] .RC [ -insvx ] .I pattern .RI [ \|file \0...\|] .SS Call with (multiple) \(mie pattern .C grep .RC [ -E \|\(or\| -F ] .RC [ -c \(or -l \c .RC \(or -q ] .RC [ -binsvx ] .CI -e \0pattern\|\f1... .RC [ -e .IR pattern \|]\0... .ifn .br .ifn \0\0\0\0 .RI [ \|file \0...\|] .SS Call with \(mif file .C grep .RC [ -E \|\(or\| -F ] .RC [ -c \(or -l \c .RC \(or -q ] .RC [ -insvx ] .RC [ -f .IR pattern_\|file\| ] .RI [ \|file \0...\|] .SS Obsolescent: .C egrep .RC [ -cefilnsv ] .RI [ \|expression\| ] .RI [ \|file \0...\|] .PP .C fgrep .RC [ -cefilnsvx ] .RI [ \|strings\| ] .RI [ \|file \0...\|] .SH DESCRIPTION The .CR grep command searches the input text .I files (standard input default) for lines matching a pattern. Normally, each line found is copied to the standard output. .CR grep supports the Basic Regular Expression syntax (see .IR regexp (5)). The .CR -E option .RC ( egrep ) supports Extended Regular Expression (ERE) syntax (see .IR regexp (5)). The .CR -F option .RC ( fgrep ) searches for fixed .IR strings using the fast Boyer-Moore string searching algorithm. The .CR -E and .CR -F options treat newlines embedded in the .I pattern as alternation characters. A null expression or string matches every line. .PP The forms .CR egrep and .CR fgrep are maintained for backward compatibility. The use of the .CR -E and .CR -F options is recommended for portability. .SS Options .RS .TP 20 .C -E Extended regular expressions. Each pattern specified is a sequence of one or more EREs. The EREs can be separated by newline characters or given in separate .CR -e .I expression options. A pattern matches an input line if any ERE in the sequence matches the contents of the input line without its trailing newline character. The same functionality is obtained by using .CR egrep . .TP .C -F Fixed strings. Each pattern specified is a sequence of one or more strings. Strings can be separated by newline characters or given in separate .CR -e .I expression options. A pattern matches an input line if the line contains any of the strings in the sequence. The same functionality is obtained by using .CR fgrep . .TP .C -b Each line is preceded by the block number on which it was found. This is useful in locating disk block numbers by context. Block numbers are calculated by dividing by 512 the number of bytes that have been read from the file and rounding down the result. .TP .C -c Only a count of matching lines is printed. .TP .CI -e " expression" Same as a simple .I expression argument, but useful when the .I expression begins with a hyphen .RC ( \- ). Multiple .CR -e options can be used to specify multiple patterns; an input line is selected if it matches any of the specified patterns. .TP .CI -f " pattern_\|file" The regular .I expression .RC ( grep and .CR "grep -E" ) or .I strings list .RC ( "grep -F" ) is taken from the .IR pattern_\|file . .TP .C -i Ignore uppercase/lowercase distinctions during comparisons. .TP .C -l Only the names of files with matching lines are listed (once), separated by newlines. If standard input is searched, a path name of .CR \- is listed. .TP .C -n Each line is preceded by its relative line number in the file starting at 1. The line number is reset for each file searched. This option is ignored if .CR -c , .CR -b , .CR -l , or .CR -q is specified. .TP .C -q (Quiet) Do not write anything to the standard output, regardless of matching lines. Exit with zero status upon finding the first matching line. Overrides any options that would produce output. .TP .C -s Error messages produced for nonexistent or unreadable files are suppressed. .TP .C -v All lines but those matching are printed. .TP .C -x (eXact) Matches are recognized only when the entire input line matches the fixed string or regular expression. .RE .PP In all cases in which output is generated, the file name is output if there is more than one input file. Care should be taken when using the characters .CR $ , .CR * , .CR [ , .CR ^ , .CR | , .CR ( , .CR ) , and .CR \e in .IR expression , because they are also meaningful to the shell. It is safest to enclose the entire .I expression argument in single quotes .RC ( ' ... ' ). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not specified or is set to the empty string, a default of .C C (see .IR lang (5)) is used. .PP .CR LC_ALL determines the locale to use to override any values for locale categories specified by the settings of .C LANG or any environment variables beginning with .CR LC_ . .PP .C LC_COLLATE determines the collating sequence used in evaluating regular expressions. .PP .C LC_CTYPE determines the interpretation of text as single byte and/or multi-byte characters, the classification of characters as letters, the case information for the .C -i option, and the characters matched by character class expressions in regular expressions. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If any internationalization variable contains an invalid setting, the commands behave as if all internationalization variables are set to .CR C . See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH RETURN VALUE Upon completion, .CR grep returns one of the following values: .RS .TP 5 .C 0 One or more matches found. .PD 0 .TP .C 1 No match found. .TP .C 2 Syntax error or inaccessible file (even if matches were found). .PD .RE .SH EXAMPLES In the Bourne shell .RI ( sh (1)) the following example searches two files, finding all lines containing occurrences of any of four strings: .nf .IP .C "grep -F 'if" .C then .C else .CI fi' " file1 file2" .fi .PP Note that the single quotes are necessary to tell .C grep -F when the strings have ended and the file names have begun. .PP For the C shell (see .IR csh (1)) the following command can be used: .IP .C grep -F 'if\e .C then\e .C else\e .CI fi' " file1 file2" .PP To search a file named .CR address containing the following entries: .nf .IP .C "Ken 112 Warring St. Apt. A" .C "Judy 387 Bowditch Apt. 12" .C "Ann 429 Sixth St." .fi .PP the command: .IP .C grep Judy address .PP prints: .IP .C "Judy 387 Bowditch Apt. 12" .ift .br .ift .ne 6 .PP To search a file for lines that contain either a .CR Dec or .CR Nov , use either of the following commands: .IP .CI "grep -E '[Dd]ec|[Nn]ov' " file .IP .CI "egrep -i 'dec|nov' " file .PP Search all files in the current directory for the string .CR xyz : .IP .C grep xyz * .PP Search all files in the current directory subtree for the string .CR xyz , and ensure that no error occurs due to file name expansion exceeding system argument list limits: .IP .C "find . -type f -print |xargs grep xyz" .PP The previous example does not print the name of files where string .CR xyz appears. To force .CR grep to print file names, add a second argument to the .CR grep command portion of the command line: .IP .C "find . -type f -print |xargs grep xyz /dev/null" .PP In this form, the first file name is that produced by .CR find , and the second file name is the null file. .SH WARNINGS .PP (XPG4 only.) If the .CR -q option is specified, the exit status will be zero if an input line is selected, even if an error was detected. Otherwise, default actions will be performed. .SH SEE ALSO sed(1), sh(1), regcomp(3C), environ(5), lang(5), regexp(5). .SH STANDARDS CONFORMANCE .CR grep ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR egrep ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR fgrep ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4grep\f1 \- search a file for a pattern (compact algorithm)@@@\f3grep(1)\f1 .\" index@\f4egrep\f1 \- search a file for a pattern@@@\f3grep(1)\f1 .\" index@\f4fgrep\f1 \- search a file for a specific string (fast algorithm)@@@\f3grep(1)\f1 .\" index@\f1search a file for a string or expression@@@\f3grep(1)\f1 .\" index@\f1files, search a file for a string or expression@@@\f3grep(1)\f1 .\" index@\f1string or expression, search a file for a@@@\f3grep(1)\f1 .\" index@\f1expression or string, search a file for a@@@\f3grep(1)\f1 .\" .\" toc@\f3grep(1)\f1:\0\0\f4grep\f1, \f4egrep\f1, \f4fgrep\f1@@@search a file for a pattern\f1 .\" toc@\f4egrep\f1:\0\0search a file for a pattern@@@\f1see \f3grep(1)\f1 .\" toc@\f4fgrep\f1:\0\0search a file for a string (fast)@@@\f1see \f3grep(1)\f1 .\" .\" links@grep.1 egrep.1 .\" links@grep.1 fgrep.1 .\" $Header: file.1,v 76.2 95/08/03 17:38:46 ssa Exp $ .TA f .TH file 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME file \- determine file type .SH SYNOPSIS .C file .RC [ -m .IR mfile\| ] .RC [ -c\| ] .RC [ -f .IR ffile\| ] .IR file \0... .SH DESCRIPTION .C file performs a series of tests on each .I file in an attempt to classify it. If .I file appears to be an .SM ASCII file, .C file examines the first 512 bytes and tries to guess its language. If .I file is an executable .C a.out file, .C file prints the version stamp, provided it is greater than 0 (see the description of the .C -V option in .IR ld (1)). .PP .C file uses the file .C /etc/magic to identify files that have some sort of .IR "magic number" , that is, any file containing a numeric or string constant that indicates its type. Commentary at the beginning of .C /etc/magic explains the format. .SS Options .C file recognizes the following command-line options: .RS .TP 15 .CI -m \0mfile use alternate magic file .IR mfile . .TP .C -c Check the magic file for format errors. This validation is not normally carried out for reasons of efficiency. No file classification is done when this option is specified. .TP .CI -f \0ffile Obtain the list of files to be examined from file .IR ffile . .C file classifies each file whose name appears in .IR ffile . .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C file behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. However, all non-ASCII text files are identified as "data". .SH SEE ALSO ld(1). .SH STANDARDS CONFORMANCE .CR file ": SVID2, SVID3, XPG2, XPG4" .\" .\" toc@\f3file(1)\f1:\0\0\f4file\f1@@@determine file type .\" .\" index@\f4file\f1 \- determine file type@@@\f3file(1)\f1 .\" index@\f1files: determine file type@@@\f3file(1)\f1 .\" index@\f1determine file type@@@\f3file(1)\f1 .\" index@\f1type, determine file@@@\f3file(1)\f1 .\" .\" $Header: find.1,v 78.1 96/01/22 22:22:29 ssa Exp $ .TA f .TH find 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME find \- find files .SH SYNOPSIS .CR find .I pathname_list .RI [ expression ] .SH DESCRIPTION The .CR find command recursively descends the directory hierarchy for each path name in .I pathname_list (that is, one or more path names) seeking files that match a Boolean .I expression written in the primaries given below. By default, .CR find does not follow symbolic links. .PP The Boolean expression is evaluated using short-circuit evaluation. This means that whenever the result of a Boolean operation (AND or OR) is known from evaluating the left-hand argument, the right-hand argument is not evaluated. .PP In the descriptions of the primaries, the argument .I n represents a decimal integer; .CI + n means more than .IR n , .CI - n means less than .IR n , and .I n means exactly .IR n . .PP The following primaries are recognized: .TP 25 .CR -depth A position-independent term which causes descent of the directory hierarchy to be done so that all entries in a directory are acted on before the directory itself. This can be useful when .CR find is used with .IR cpio (1) to transfer files that are contained in directories without write permission. It is also useful when using .IR cpio (1) and the modification dates of directories must be preserved. Always true. .TP .CI -follow A position-independent term which causes .CR find to follow symbolic links. Always true. .TP .CI -fsonly \0FStype A position-independent term which causes .CR find to stop descending any directory whose file system is not of the type specified by .IR FStype , where .I FStype is one of .CR cdfs , .CR hfs , or .CR nfs , representing the CDFS, HFS, or NFS file system type, respectively. .IP In this context, mount points inherit the .IR FStype of their parent directory. This means that when .CR "-fsonly hfs" has been specified and .CR find encounters an NFS mount point that is mounted on an HFS file system, the mount point will be visited but entries below that mount point will not. It is important to note that when .CR "-fsonly nfs" has been specified, any HFS file systems that are beneath the mount point of an NFS file system are not traversed. Always true. .TP .CR -xdev A position-independent term that causes .CR find to avoid crossing any file system mount points that exist below starting points enumerated in .IR pathname_list . The mount point itself is visited, but entries below the mount point are not. Always true. .TP .CR -mountstop Identical to .CR -xdev . This primary is provided for backward compatibility only. .CR -xdev is preferred over .CR -mountstop . .TP .CI -name \0file True if .I file matches the last component of the current file name. The matching is performed according to Pattern Matching Notation (see .IR regexp (5)). .TP .CI -path \0file Same as .CR -name except the full path (as would be output by .CR -print) is used instead of just the base name. Note that .CR / characters are not treated as a special case. For example, .CR */.profile matches .CR ./home/fred/.profile . .TP .CR -perm \0[ - ]\f2mode In this primary, the argument .I mode is used to represent file mode bits. The argument is identical in format to the .I mode operand as described in .IR chmod (1), with the exception that the first character must not be the .CR - operator. When using the symbolic form of .IR mode , the starting template is assumed to have all file mode bits cleared. .IP If the leading minus is omitted, this primary is true when the file permission bits exactly match the value of .IR mode . Bits associated with the symbolic attributes .CR s (set-user-ID, set-group-ID) and .CR t (sticky bit) are ignored when the minus is omitted. .IP If .I mode is preceded by a minus, this primary is true if all of the bits that are set in .I mode are also set in the file permission bits. In this case, the bits associated with the symbolic attributes .CR s and .CR t are significant. .TP .CI -fstype \0FStype True if the file system to which the file belongs is of type .IR FStype , where .I FStype is one of .CR cdfs , .CR hfs , or .CR nfs , corresponding to the CDFS, HFS, or NFS file system type, respectively. .TP .CI -type \0c True if the type of the file is .IR c , where .I c is one of: .RS .RS .PD 0 .TP .CR f Regular file .TP .CR d Directory .TP .CR b Block special file .TP .CR c Character special file .TP .CR p FIFO (named pipe) .TP .CR l Symbolic link .TP .CR s Socket .TP .CR n Network special file .TP .CR M Mount point .PD .RE .RE .TP .CI -links \0n True if the file has .I n links. .TP .CI -user \0uname True if the file belongs to the user .IR uname . If .I uname is numeric and does not appear as a login name in the .CR /etc/passwd file, it is taken as a user ID. The .I uname operand can be preceded by a .CR + or .CR - to modify the comparison operation as described previously. .TP .CI -group \0gname True if the file belongs to the group .IR gname . If .I gname is numeric and does not appear in the .CR /etc/group file, it is taken as a group ID. The .I gname operand can be preceded by a .CR + or .CR - to modify the comparison operation as described previously. .TP .CR -nouser True if the file belongs to a user ID that is not listed in the password database. See .IR passwd (4). .TP .CR -nogroup True if the file belongs to a group ID that is not listed in the group database. See .IR group (4). .TP .CR -size \0\f2n\f1[ c ] True if the file is .I n blocks long. If .I n is followed by a .CR c , the size is in bytes. .TP .CI -atime \0n True if the file has been accessed in .I n days. The access time of directories in .I pathname_list is changed by .CR find itself. .TP .CI -mtime \0n True if the file has been modified in .I n days. .TP .CI -ctime \0n True if the file inode has been changed in .I n days. .TP .CI -newer \0file True if the current file has been modified more recently than the argument .IR file . .TP .CR -newer [\f2tv1\f1[\f2tv2\f1]\|]\0\f2file True if the indicated time value .RI ( tv1 ) of the current file is newer than the indicated time value .RI ( tv2 ) of .IR file . The time values .I tv1 and .I tv2 are each selected from the set of characters: .RS .RS .TP .PD 0 .CR a The time the file was last accessed .TP .CR c The time the inode of the file was last modified .TP .CR m The time the file was last modified .PD .RE .RE .IP If the .I tv2 character is omitted, it defaults to .CR m . Note that the .CR -newer option is equivalent to .CR -newermm . .RS .PP Syntax examples; .IP .CI -newera \0file .br .CI -newermc \0file .RE .TP .CI -inum \0n True if the file serial number (inode number) is .IR n . Note that file serial numbers are unique only within a given file system. Therefore, matching file serial numbers does not guarantee that the referenced files are the same unless you restrict the search to a single file system. .TP .CI -linkedto \0path True if the file is the same physical file as the file specified by .I path (i.e., linked to .IR path ). This primary is similar to .CR -inum , but correctly detects when a file is hard-linked to .IR path , even when multiple file systems are searched. .TP .CR -print Causes the current path name to be printed. Always true. .TP .CI -exec \0cmd True if the executed .I cmd returns a zero value as exit status. The end of .I cmd must be punctuated by a semicolon (semicolon is special to the shell and must be escaped). Any command argument .CR {} is replaced by the current path name. .TP .CI -ok \0cmd Same as .CR -exec except that the generated command line is printed with a question mark first, and is executed only if the user responds by typing .CR y . .TP .CI -cpio \0device Write the current file on .I device in .IR cpio (4) format (5120-byte records). The use of .CR -cpio implies .CR -depth . Always true. .TP .CR -ncpio Same as .CR -cpio but adds the .CR -c option to .CR cpio . The use of .CR -ncpio implies .CR -depth . Always true. .TP .CR -prune If the current entry is a directory, cause .CR find to skip that directory. This can be useful to avoid walking certain directories, or to avoid recursive loops when using .CR "cpio -p" . Note, however, that .CR -prune is useless if the .CR -depth option has also been given. See the description of .CR -only and the EXAMPLES section, below, for more information. Always true. .TP .CR -only This is a positive-logic version of .CR -prune . A .CR -prune is performed after every directory, unless .CR -only is successfully evaluated for that directory. As an example, the following three commands are equivalent: .nf .IP .C "find . -fsonly hfs -print" .C "find . -print -fstype hfs -only" .C "find . -print ! -fstype hfs -prune" .fi .IP Note, however, that .CR -only is useless if the .CR -depth option has also been given. Always true. .TP .CI ( \0expression\0 ) True if the parenthesized expression is true. The spaces are required. Parentheses are special to the shell and must be escaped, as in .CR \e( and .CR \e) . .PP Primaries can be combined by using the following operators (in order of decreasing precedence): .TP 30 .CI ! \0expression Logical NOT operator. True if .I expression is not true. .TP .IC expression\0\f1[ -a \f1]\f2\0expression Logical AND operator. True if both of the .IR expression s are true. .TP .IC expression\0 -o \0expression Logical OR operator. True if either or both of the .IR expression s are true. .PP If .I expression is omitted, or if none of .CR -print , .CR -ok , .CR -exec , .CR -cpio , or .CR -ncpio is specified, .CR -print is assumed. .SS "Access Control Lists" The .CR -acl primary enables the user to search for access control list entries. It is true if the file's access control list matches an access control list pattern or contains optional access control list entries (see .IR acl (5)). It has three forms: .TP 25 .CI -acl \0aclpatt Match all files whose access control list includes all (zero or more) pattern entries specified by the .I aclpatt pattern. .TP .CI "-acl =" aclpatt Match a file only if its access control list includes all (zero or more) pattern entries specified by the .I aclpatt pattern, and every entry in its access control list is matched by at least one pattern entry specified in the .I aclpatt pattern. .TP .CR "-acl opt" Match all files containing optional access control list entries. .PP The .I aclpatt string can be given as an operator or short form pattern; see .IR acl (5). .PP By default, .CR -acl is true for files whose access control lists include all the (zero or more) access control list patterns in .IR aclpatt . A file's access control list can also contain unmatched entries. .PP If .I aclpatt begins with .CR = , the remainder of the string must match all entries in a file's access control list. .PP The .I aclpatt string (by default, or the part following .CR = ) can be either an access control list or an access control list pattern. However, if it is an access control list, .I aclpatt must include at least the three base entries .RI (( user ".%, mode)," .RI (%. group ", mode)," and (%.%, mode)). .PP As a special case, if .I aclpatt is the word .CR opt , the primary is true for files with access control list entries. .SH EXTERNAL INFLUENCES .SS Environment Variables If an internationalization variable is not specified or is null, it defaults to the value of .CR LANG . .PP If .CR LANG is not specified or is null, it defaults to .CR C (see .IR lang (5)). .PP If .CR LC_ALL is set to a nonempty string value, it overrides the values of all the other internationalization variables. .PP If any internationalization variable contains an invalid setting, all internationalization variables default to .CR C (see .IR environ (5)). .PP .CR LC_CTYPE determines the interpretation of text as single and/or multibyte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .CR LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .CR NLSPATH determines the location of message catalogues for the processing of .CR LC_MESSAGES . .SS International Code Set Support Single- and multibyte character code sets are supported. .SH EXAMPLES Search the two directories .CR /example and .CR /new/example for files containing the string .CR "Where are you" and print the names of the files: .IP .C "find /example /new/example -exec grep -l 'Where are you' {} \e;" .PP Remove all files named .CR a.out or .CR *.o that have not been accessed for a week: .IP .C "find / \e( -name a.out -o -name '*.o' \e)" .C "-atime +7 -exec rm {} \e;" .IP Note that the spaces delimiting the escaped parentheses are required. .PP Print the names of all files on this machine. Avoid walking .CR nfs directories while still printing the .CR nfs mount points: .IP .C "find / -fsonly hfs -print" .PP Copy the entire file system to a disk mounted on .CR /Disk , avoiding the recursive copy problem. Both commands are equivalent (note the use of .CR -path instead of .CR -name ): .IP .C "cd /; find . ! -path ./Disk -only -print | cpio -pdxm /Disk" .IP .C "cd /; find . -path ./Disk -prune -o -print | cpio -pdxm /Disk" .PP Copy the root disk to a disk mounted on .CR /Disk , skipping all mounted file systems below .CR / . Note that .CR -xdev does not cause .CR / to be skipped, even though it is a mount point. This is because .CR / is the starting point and .CR -xdev only affects entries .CR below starting points. .IP .C "cd /; find . -xdev -print | cpio -pdm /Disk" .PP Change permissions on all regular files in a directory subtree to mode 444, and permissions on all directories to 555: .IP .CR find .RI < pathname > .C "-type f -print | xargs chmod 444" .br .CR find .RI < pathname > .C "-type d -print | xargs chmod 555" .IP Note that output from .CR find was piped to .IR xargs (1) instead of using the .CR -exec primary. This is because when a large number of files or directories is to be processed by a single command, the .CR -exec primary spawns a separate process for each file or directory, whereas .I xargs collects file names or directory names into multiple arguments to a single .I chmod command, resulting in fewer processes and greater system efficiency. .SS "Access Control List Examples" Find all files not owned by user .CR karl that have access control lists with at least one entry associated with .CR karl , and one entry for no specific user in group .CR bin with the read bit on and the write bit off: .IP .C "find / ! -user karl -acl 'karl.*, %.bin+r-w' -print" .PP Find all files that have a read bit set in any access control list entry: .IP .C "find / -acl '*.*+r' -print" .PP Find all files that have the write bit unset and execute bit set in every access control list entry: .IP .C "find / -acl '=*.*-w+x' -print" .PP Find all files that have optional access control list entries: .IP .C "find / -acl opt -print" .SH DEPENDENCIES .SS NFS The .CR -acl primary is always false for NFS files. .SH WARNINGS Because of interoperability goals, .CR cpio does not support archiving files larger than 2GB or files that have user/group IDs larger than 60,000 (60K). Files with user/group IDs greater than 60K are archived and restored under the user/group ID of the current process. .SH AUTHOR .CR find was developed by AT&T and HP. .SH FILES .TP 25 .PD 0 /etc/group Group names .TP /etc/mnttab Mount points .TP /etc/passwd User names .PD .SH SEE ALSO chacl(1), chmod(1), cpio(1), sh(1), test(1), xargs(1), mknod(2), stat(2), cpio(4), fs(4), group(4), passwd(4), acl(5),\"STD environ(5), lang(5), regexp(5). .SH STANDARDS CONFORMANCE .CR find ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4find\f1 \- find (search for) files@@@\f3find(1)\f1 .\" index@search for files@@@\f3find(1)\f1 .\" index@files: find (search for) files@@@\f3find(1)\f1 .\" index@search directory tree for files@@@\f3find(1)\f1 .\" index@directory: search directory tree for files@@@\f3find(1)\f1 .\" index@tree, search directory tree for files@@@\f3find(1)\f1 .\" .\" toc@\f3find(1)\f1:\0\0\f4find\f1@@@find files .\" $Header: findmsg.1,v 78.1 96/02/12 13:46:32 ssa Exp $ .TA f .TH findmsg 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME findmsg, dumpmsg \- create message catalog file for modification .SH SYNOPSIS .C findmsg .RC [ -aiv ] .RC [\|[ -D .IR sym\| ] .RC [ -U .IR sym\| ]] .IR file \0... .PP .C dumpmsg .IR file \0... .SH DESCRIPTION The .CR findmsg command extracts messages from a C program source .I file and writes them to the standard output in a format suitable for input to .CR gencat (see .IR gencat (1)). The input file will be preprocessed using .CR cpp (see .IR cpp (1)) in order to select print specifiers and handle .CR ifdef , .CR ifndef ... conditional .CR cpp primitives. If multiple input files are specified and the .CR -a option is not used, the files are processed sequentially such that message catalog comment lines identifying the input .I file are written before the output for each input .IR file . .PP The .CR findmsg command scans the source files for uncommented lines with one of the following three formats embedded within it: .IP .CI catgets( any_var ,NL_SETN, n ,\c .ifn \f3<\f2message\f3>)\f1 .ift \f4<\f2message\f4>)\f1 .RS .TP 25 .ifn \f3<\f2message\f3>\f1 .ift \f4<\f2message\f4>\f1 .CI "/* catgets " n " */ .TP .CI "/* catgets " n " */" .ifn \f3<\f2message\f3>\f1 .ift \f4<\f2message\f4>\f1 .RE .PP or any combination of these formats wholly contained on a single physical line. .ifn \f3<\f2message\f3>\f1 .ift \f4<\f2message\f4>\f1 could be a string constant or a combination of string constants and print specifiers (PRI*). Any number of spaces or tabs can separate the .CR catgets comment from the .IR message . The digit .IR n , which can be any valid message number (see .IR gencat (1)), is combined with the .I message string to produce a message catalog source line. The message source line is assigned to the set whose number is the current value of .CR NL_SETN as set by the last .CR #define directive encountered. If .CR NL_SETN has not yet been defined when a message line is found, the message is output without a set number specification. If more than one message is found belonging to the same set and message number, the last message found is output; any others are silently discarded. Conditional compilation and .CR #include instructions in the C source files are ignored. .SS Options .CR findmsg recognizes the following command-line options: .RS .TP 12 .C -a Merge identically numbered sets from multiple input files so that .CR gencat can process the .CR findmsg output. .TP .CI -D sym Define symbol .IR sym . .TP .CI -U sym Cause symbol .I sym to be undefined. .TP .C -i Consider all #ifdefs to extract messages from the input file. Options .C -D and .C -U will be used to select print specifiers if this option is not used. .TP .C -v Outputs all error messages issued by .CR cpp . By default, .CR findmsg does not display the error messages issued by .CR cpp . .RE .PP The .CR dumpmsg command extracts messages from a message catalog .I file created by .CR gencat . Messages are written to standard output in a format suitable for editing and re-input to .CR gencat . .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_CTYPE determines the interpretation of messages as single-byte and/or multi-byte characters. .PP .CR LC_MESSAGES determines the language in which messages are displayed. .PP If .CR LC_CTYPE or .CR LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of .CR C (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR findmsg and .CR dumpmsg behave as if all internationalization variables are set to .CR C . See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH WARNINGS The .CR findmsg command is HP proprietary, not portable to other vendors' systems, and will not be provided in future HP-UX releases. .SH AUTHOR .CR findmsg and .CR dumpmsg were developed by HP. .SH SEE ALSO findstr(1), gencat(1), insertmsg(1), catgets(3C). .\" .\" index@\f4findmsg\f1 \- create message catalog file for modification@@@\f3findmsg(1)\f1 .\" index@\f4dumpmsg\f1 \- create message catalog file for modification@@@\f3findmsg(1)\f1 .\" index@\f1catalog file, message, create for modification@@@\f3findmsg(1)\f1 .\" index@\f1create message catalog file for modification@@@\f3findmsg(1)\f1 .\" index@\f1file, create message catalog file for modification@@@\f3findmsg(1)\f1 .\" index@\f1message catalog file, create for modification@@@\f3findmsg(1)\f1 .\" index@\f1message catalog file, extract messages from @@@\f3findmsg(1)\f1 .\" index@\f1modification, create message catalog file for@@@\f3findmsg(1)\f1 .\" .\" toc@\f3findmsg(1)\f1:\0\0\f4findmsg\f1, \f4dumpmsg\f1@@@create message catalog file for modification\f1 .\" toc@\f4dumpmsg\f1:\0\0extract messages from message catalog file@@@\f1see \f3findmsg(1)\f1 .\" .\" links@findmsg.1 dumpmsg.1 .\" $Header: findstr.1,v 76.1 95/07/07 15:12:57 ssa Exp $ .TA f .TH findstr 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME findstr \- find strings for inclusion in message catalogs .SH SYNOPSIS .C findstr .IR file \0... .SH DESCRIPTION .C findstr examines files of C source code for uncommented string constants which it places, along with the surrounding quotes, on the standard output, preceding each by the file name, start position, and length. This information is used by .C insertmsg (see .IR insertmsg (1)). .C findstr does not output strings that are parameters of the .C catgets() routine (see .IR catgets (3C)). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of comments and string literals as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C findstr behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS .C findstr outputs initialization strings of static string variables. Calling .C insertmsg with these strings causes their replacement with a call to .C catgets() (see .IR catgets (3C)). Since the initializer must be a string, this assignment results in an invalid C declaration. For example, the following line: .IP .C static char *x[] = .C """\f2message\fP""" .PP is modified by .C insertmsg (see .IR insertmsg (1)) to: .IP .C static char *x[] = (catgets(catd,NL_SETN,1,"""\f2message\fP""")) .PP These strings should be manually removed from .C findstr output before being input to .CR insertmsg . .SH SEE ALSO insertmsg(1). .\" .\" toc@\f3findstr(1)\f1:\0\0\f4findstr\f1@@@find strings for inclusion in message catalogs .\" .\" index@\f4findstr\f1 \- find strings for inclusion in message catalogs@@@\f3findstr(1)\f1 .\" index@\f1find strings for inclusion in message catalogs@@@\f3findstr(1)\f1 .\" index@\f1strings, find for inclusion in message catalogs@@@\f3findstr(1)\f1 .\" index@\f1message catalogs, find strings for inclusion in@@@\f3findstr(1)\f1 .\" index@\f1catalogs, message, find strings for inclusion in@@@\f3findstr(1)\f1 .\" .\" $Header: finger.1,v 72.5 94/04/27 11:41:39 ssa Exp $ .TA f .TH finger 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME finger \- user information lookup program .SH SYNOPSIS .C finger .RI [ \|options\| ] .IR user_name \ ... .SH DESCRIPTION By default, .CR finger lists for each .I user_name on the system: .RS .TP 3 \(bu Login name, .PD 0 .TP \(bu Full given name, .TP \(bu Terminal write status (if write permission is denied), .TP \(bu Idle time, .TP \(bu Login time, .TP \(bu User's home directory and login shell, .TP \(bu Any plan the user has placed in file .CR .plan in their home directory, .TP \(bu Project on which they are working from the file .CR .project , also in the home directory, .TP \(bu office location and phone number (if known). .RE .PD .PP Idle time is in minutes if listed as a single integer, hours and minutes if a .CR : is present, or days and hours if a .CR d is present. Account names as well as first and last names of users are accepted. .PP .C finger can also be used to list users on a remote machine. The format for .I user_name is .IR user_name @ host . If .I user_name is not specified, the remote system (\c .SM HP-UX or non-\c .SM HP-UX\c ) uses its default standard format for listing user information. .SS Options .C finger recognizes the following options: .RS .TP 10 .C -b Suppress printing the user's home directory and shell. .TP .C -f Suppress printing the header that is normally printed in a short-format printout. .TP .C -f Suppress printing the .CR .project file in a long-format printout. .TP .C -i Force ``idle'' output format. Similar to short format except that only the login name, terminal, login time, and idle time are printed. .TP .C -l Force long output format. .TP .C -m Match arguments only on user name. .TP .C -p Suppress printing of the .CR .plan files .TP .C -q Force quick output format. Similar to short format except that only the login name, terminal, and login time are printed. .TP .C -R Print the user's host name. .TP .C -s Force short output format. .TP .C -w Suppress printing the full name in a short-format printout. .RE .\" .SH EXAMPLES (none needed) .SH WARNINGS Only the first line of the .CR .project file is printed. .SH AUTHOR .C finger was developed by the University of California, Berkeley. .SH FILES .PD 0 .TP 20 .C /etc/utmp who file .TP .C /var/adm/wtmp last login file .TP .C /etc/passwd for users names, offices, ... .TP .C ~/.plan plans .TP .C ~/.project projects .PD .SH SEE ALSO chfn(1), who(1). .\" index@\f4finger\f1 \- user information lookup program@@@\f3finger(1)\f1 .\" index@user information lookup program@@@\f3finger(1)\f1 .\" index@look up current user information@@@\f3finger(1)\f1 .\" index@information, current user, look up@@@\f3finger(1)\f1 .\" .\" toc@\f3finger(1)\f1:\0\0\f4finger\f1@@@user information lookup program .\" .\" fileset_database@finger.1 USER-CMDS-MAN .\" $Header: fold.1,v 76.2 95/08/03 17:47:23 ssa Exp $ .TA f .TH fold 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fold \- fold long lines for finite width output device .SH SYNOPSIS .C fold .RC [ -b ] .RC [ -s ] .RC [ -w .IR width\| ] .RI [ \|file \0...\|] .SS Obsolete form: .C fold .RC [ -s ] .RC [ -\c .IR width\| ] .RI [ \|file \0...\|] .SH DESCRIPTION The .C fold command is a filter that folds the contents of the specified files, breaking the lines to have a maximum of .I width column positions (or bytes, if the .C -b option is specified). The .C fold command breaks lines by inserting a newline character so that each output line is the maximum width possible that does not exceed the specified number of column positions (or bytes). A line cannot be broken in the middle of a character. If no files are specified or if a .I file name of .CR - is specified, the standard input is used. .PP The .C fold command is often used to send text files to line printers that truncate, rather than fold, lines wider than the printer is able to print. .PP If the backspace, tab, or carriage-return characters are encountered in the input, and the .C -b option is not specified, they are treated specially as follows: .RS .TP 17 Backspace The current count of line width is decremented by one, although the count never becomes negative. Thus, the character sequence .I character-backspace-character counts as using one column position, assuming both characters each occupy a single column position. .C fold does not insert a newline character immediately before or after any backspace character. .TP Tab Each tab character encountered advances the column position pointer to the next tab stop. Tab stops are set 8 columns apart at column positions 1, 9, 17, 25, 33, etc. .TP 17 Carriage-return The current count of line width is set to zero. .C fold does not insert a newline character immediately before or after any carriage-return character. .RE .PP Note that .C fold may affect any underlining that is present. .SS Options The .C fold command recognizes the following options and command-line arguments: .RS .TP 17 .C -b Count .I width in bytes rather than in column positions. .TP .C -s Break the line on the last blank character found before the specified number of column positions (or bytes). If none are found, break the line at the specified line length. .TP .CI -w \0width .PD 0 .TP .CI - width .sp -2v Specify the maximum line length, in column positions (or bytes if .C -b is specified). The default value is 80. .I width should be a multiple of 8 if tabs are present, or the tabs should be expanded using .CR expand before processing by .CR fold (see .IR expand (1)). The .CI - width option is obsolescent and may be removed in a future release. .PD .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .CR LC_CTYPE or .CR LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .CR fold behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH SEE ALSO expand(1). .SH STANDARDS CONFORMANCE .CR fold ": XPG4, POSIX.2" .\" .\" index@\f4fold\f1 \- fold long lines for finite-width output device@@@\f3fold(1)\f1 .\" index@\f1long lines, fold for finite-width output device@@@\f3fold(1)\f1 .\" index@\f1lines, long, fold for finite-width output device@@@\f3fold(1)\f1 .\" index@\f1finite-width output device, fold long lines for@@@\f3fold(1)\f1 .\" index@\f1output device, finite-width, fold long lines for@@@\f3fold(1)\f1 .\" .\" toc@\f3fold(1)\f1:\0\0\f4fold\f1@@@fold long lines for finite width output device .\" .\" $Header: lpfilter.1,v 72.4 94/07/05 17:17:26 ssa Exp $ .TA l .TH lpfilter 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lpfilter, divpage, fontdl, lprpp, plotdvr, printstat, reverse \- filters invoked by lp interface scripts .SH SYNOPSIS .C /usr/lbin/divpage .RC [ -p \(or .CR -l ] .RC [ -h \(or .CR -q ] .RC [ -n\c .IR FontID\| ] .I filename .PP .C /usr/lbin/fontdl .RC [ -n\c .IR FontID\| ] .RC [ -l ] .RC [ -p ] .I filename .PP .C /usr/lbin/lprpp .RC [ -i ] .RC [ -o ] .RC [ -e ] .RC [ -l\c .IR nn\| ] .RC [ -n ] .RC [ -p ] .PP .C /usr/lbin/plotdvr .CI -l \|request_id .CI -u \|username .RC [ -e ] .RC [ -f ] .RC [ -i ] .I filename .PP .C /usr/sbin/printstat .CI -l \|request_id .CI -u \|username .I filename .PP .C /usr/sbin/reverse .RC [ -l .IR page_length\| ] .SS Remarks The structure of these filters is currently under review. They may become obsolete or be restructured in a future release. .SH DESCRIPTION Various filters are used by the .C lp subsystem to obtain specialized behavior for specific types of devices or data. This entry describes currently supported filters. .PP A number of these filters use a specified .I username and .I filename to determine the location of the user who originated the print message. .PP The .I filename is used to determine the .I hostname of the system where the request originated, and must have the form .RI [ dirname ]\c .CI /d?A \|nnnhostname or .RI [ dirname ]\c .CI /dA \|nnnnhostname\f1, where .I dirname is not a path name, but only the name of the basename's parent directory. .I filename meets this requirement when it is set to .C $6 in the interface script for the printer. .SS divpage Provides capabilities for printing multiple pages per sheet and selection of built-in fonts. .PP .C Options: .RS .TP 15 .C -p Set mode to portrait (default). .TP .C -l Set mode to landscape. .TP .C -h Print half pages (default). .TP .C -q Print quarter pages. .TP .CI -n \|FontID Use font number .IR FontID . Default is 0. Causes the string .CI \s-2\uE\dC\s0( \|Font\s-1ID\s0 X to be sent to the printer. .RE .SS fontdl .I fontdl downloads the font contained in .I filename to a printer connected to standard output. .PP .C Options: .RS .TP 15 .CI -n \|FontID Specifies the ID number by which the font will be referenced. Default is 0. .TP .C -l Specify landscape mode. Default is portrait. .TP .C -p Specifies proportional spacing. Default is fixed. .RE .SS lprpp This is a filter that converts backspace overstrike to line overprint with horizontal print positioning to enhance bold print. This functionality is required on printers such as the LaserJet, which cannot produce bold print by overstriking. .PP .C Options: .RS .TP 15 .C -i Converts to _ to italicize ANYCHAR. Also properly italicizes overstruck (bold) characters. Does .I not work correctly for "hashed-overstrike" such as: .br \0 .br \0\0\0\0\0\0_ .TP .C -o Prints only the odd numbered pages. Used with .C -e for double-sided printing. .TP .C -e Print only the even numbered pages. Used with .C -o for double sided printing. .TP .CI -l \|nn Specifies the page length, in lines. Default is 60 unless .I -n or .I -p is selected, in which case it is 66. .TP .C -n Specifies nroff mode for printing output of the .I nroff command. Prints 66 lines per page with the first line appearing on logical line 4 of the printer. .TP .C -p Specifies pr mode for printing output from the .I pr command. Prints 66 lines per page with the first line appearing on logical line 3 of the printer. .SS plotdvr HP-GL plotter filter. This filter scans the data for "PG" commands (paper feed). When this data is encountered, the filter strips it from the data stream and informs the requesting user of the need to change paper in the plotter. .PP Options: .RS .TP 15 .CI -l \|request_id Specifies the printer request ID and is used in various messages regarding the plot request. .TP .CI -u \|username The requesting user's login name, used to communicate with the user regarding the request. .TP .C -e Specifies the use of escape sequences, rather than HP-GL commands, to determine plotter status. .TP .C -f Plot without stopping for paper changes. The "PG" commands are not stripped from the data stream and the user is not notified of them. This option is used on plotters capable of automatic page feed. .TP .C -i Prevents initialization of the plotter. .RE .SS printstat Interrogates an RS232 printer as to its status, and does not return until the printer is ready. If the printer is .IR off-line , .IR "out of paper" , or .IR disconnected , the submitter of the print request is notified of this condition periodically until it is corrected. When the printer is ready to print, the command exits. .PP Standard input and standard output must both be connected to the serial printer device. .PP This program uses the .I send-status command .C \s-2\uE\dC\s0?\s-2\uD\d1\s0? to determine status. Not all serial printers respond to this command. Only the following configurations support this command: .RS .PP .TS box; cB | cB l | l. Printer Comments _ LaserJet Not supported LaserJetII Supported LaserJetIID Requires \s-1HP\|26013A\s0 module LaserJetIIP Not supported LaserJetIII Requires \s-1HP\|26013A\s0 module LaserJet2000 Not supported .TE .RE .PP .C Options: .RS .TP 15 .CI -l \|request-id Print request ID used in various communications with the user. .TP .CI -u \|username The requesting user's login name, used to communicate with the user regarding the request. .RE .SS reverse Prints the data appearing on the standard input in reverse page order to the standard output. This command can handle up to 2000 pages. .PP .C Options: .RS .TP 15 .CI -l \|page_length Specifies the page length, in lines. Default is 66. .RE .SH DIAGNOSTICS Error and diagnostic messages appear on the printed output, on the user's terminal, or are mailed to the user, depending on circumstances. .SH WARNINGS There is little consistency in the interface to these filters. .SH SEE ALSO lp(1), lpadmin(1). .PP .IR "HP-UX System Administration Manual" . .\" .\" index@\f4lpfilter\f1 \- filters invoked by lp interface scripts@@@\f3lpfilter(1)\f1 .\" index@\f4divpage\f1 \- divide pages for two-sided printing@@@\f3lpfilter(1)\f1 .\" index@\f4fontdl\f1 \- download fonts to printer@@@\f3lpfilter(1)\f1 .\" index@\f4hp2686a\f1 \- laserjet filter@@@\f3lpfilter(1)\f1 .\" index@\f4hp2934a\f1 \- character printer filter@@@\f3lpfilter(1)\f1 .\" index@\f4lprpp\f1 \- laserjet filter@@@\f3lpfilter(1)\f1 .\" index@\f4plotdvr\f1 \- plotter driver for lp@@@\f3lpfilter(1)\f1 .\" index@\f4printstat\f1 \- check status of serial printer@@@\f3lpfilter(1)\f1 .\" index@\f4reverse\f1 \- reverse printer pages for collating@@@\f3lpfilter(1)\f1 .\" .\" toc@\f3lpfilter(1)\f1:\0\0\f4lpfilter\f1@@@filters used by the lp interface scripts .\" .\" links@lpfilter.1 divpage.1 .\" links@lpfilter.1 fontdl.1 .\" links@lpfilter.1 lprpp.1 .\" links@lpfilter.1 plotdvr.1 .\" links@lpfilter.1 printstat.1 .\" links@lpfilter.1 reverse.1 .\" $Header: forder.1,v 72.3 93/01/14 11:34:10 ssa Exp $ .TA f .TH forder 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME forder \- convert file data order .SH SYNOPSIS .C forder .RC [ -a ] .RC [ -l ] .RC [ -n ] .RI [ \|file \0...\|] .SH DESCRIPTION The text orientation (mode) of a file can be right-to-left (non-Latin) or left-to-right (Latin). This text orientation can affect the way data is arranged in the file. The data arrangements that result are called screen order and keyboard order. .C forder converts the order of characters in the file from screen order to keyboard order or vice versa. .PP .C forder reads the concatenation of input files (or standard input if none are given) and produces on standard output a converted version of its input. If .C - appears as an input file name, .C forder reads standard input at that point (use .C -\|- to delimit the end of options in such instances). .PP .C forder converts input files for all languages that are read from right-to-left. Unless the .C -a option is used, the command merely copies input files to standard output for languages that are read from left-to-right. .SS Options .C forder recognizes the following options: .RS .TP .C -a Convert file data order for languages read from left-to-right. .TP .C -l Identify the file as having been created in Latin mode. .TP .C -n Identify the file as having been created in non-Latin mode. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables The .C LANGOPTS environment variable determines the mode and order of the file. The syntax of .C LANGOPTS is: .IP .RI [ \|mode\| ]\ [ \|_order\| ] .PP where .I mode describes the mode of a file: .C l represents Latin mode, and .C n represents non-Latin mode. Non-Latin mode is assumed for values other than .C l and .CR n . The .I order describes the data order of a file: .C k is keyboard, and .C s is screen. Keyboard order is assumed for values other than .C k and .CR s . Mode information in .C LANGOPTS can be overridden from the command line. .PP The .C LC_ALL environment variable determines the direction of a language (left-to-right or right-to-left). .PP The .C LC_NUMERIC environment variable determines whether a language has alternative numbers. .PP The .C LANG environment variable determines the language in which messages are displayed. .SS International Code Set Support Single-byte character code sets are supported. .SH EXAMPLES The following command begins with .IR file1 , which exists in screen order, converts it to keyboard order, sorts the keyboard-ordered output, converts it back to screen order, and redirects the output to .IR file2 . Note that .C -n is given to inform .C forder that .I file1 was created in non-Latin mode. .IP .C forder -n file1 | sort | .C forder -n > file2 .SH WARNINGS It is the user's responsibility to ensure that the .C LANGOPTS environment variable accurately reflects the status of the file. .PP If present, alternative numbers always have a left-to-right orientation. .SH AUTHOR .C forder was developed by HP. .SH SEE ALSO environ(5), hpnls(5), strord(3C), nljust(1). .\" .\" index@convert file keyboard/display data order@@@\f3forder(1)\f1 .\" index@files: convert file keyboard/display data order@@@\f3forder(1)\f1 .\" index@keyboard/display data order, convert file@@@\f3forder(1)\f1 .\" index@display/keyboard data order, convert file@@@\f3forder(1)\f1 .\" index@data order for display/keyboard, convert file@@@\f3forder(1)\f1 .\" index@character sequences for display/keyboard, convert file data order@@@\f3forder(1)\f1 .\" .\" toc@\f3forder(1)\f1:\0\0\f4forder\f1@@@convert file data order .\" .\" fileset_database@forder.1 USER-CMDS-MAN .\" $Header: from.1,v 72.4 94/12/09 14:55:21 ssa Exp $ .TA f .TH from 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME from \- who is my mail from? .SH SYNOPSIS .C from .RC [ -s .IR sender\| ] .RI [ \|user\| ] .SH DESCRIPTION .C from prints the mail header lines in your mailbox file to show who sent you mail. If .I user is specified, .IR user 's mailbox is examined instead of your own. If the .C -s option is given, only headers of mail from .I sender are printed. .SH EXAMPLES List header lines for all current mail in your mailbox that was sent by .CR ken . .IP .C from -s ken .SH FILES .C /var/mail/* .SH AUTHOR .C from was developed by the University of California, Berkeley. .SH SEE ALSO biff(1), mail(1), prmail(1). .\" .\" toc@\f3from(1)\f1:\0\0\f4from\f1@@@who is my mail from? .\" .\" index@\f4from\f1 \- who is my mail from?@@@\f3from(1)\f1 .\" index@who is my mail from?@@@\f3from(1)\f1 .\" index@mail \- who is mine from?@@@\f3from(1)\f1 .\" .\" fileset_database@from.1 USER-CMDS-MAN .\" Copyright (c) 1991 X Consortium .\" .\" Permission is hereby granted, free of charge, to any person obtaining a .\" copy of this software and associated documentation files (the "Software"), .\" to deal in the Software without restriction, including without limitation .\" the rights to use, copy, modify, merge, publish, distribute, sublicense, .\" and/or sell copies of the Software, and to permit persons to whom the .\" Software furnished to do so, subject to the following conditions: .\" .\" The above copyright notice and this permission notice shall be included in .\" all copies or substantial portions of the Software. .\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL .\" THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, .\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF .\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE .\" SOFTWARE. .\" .\" Except as contained in this notice, the name of the X Consortium shall not .\" be used in advertising or otherwise to promote the sale, use or other .\" dealing in this Software without prior written authorization from the .\" X Consortium. .\" Copyright 1991 Network Computing Devices .\" .\" Permission to use, copy, modify, distribute, and sell this software and .\" its documentation for any purpose is hereby granted without fee, provided .\" that the above copyright notice appear in all copies and that both that .\" copyright notice and this permission notice appear in supporting .\" documentation, and that the name of Network Computing Devices .\" not be used in advertising or .\" publicity pertaining to distribution of the software without specific, .\" written prior permission. Network Computing Devices make .\" no representations about the .\" suitability of this software for any purpose. It is provided "as is" .\" without express or implied warranty. .\" $XConsortium: xfs.man /main/12 1995/12/15 14:03:46 gildea $ .TH XFS 1 "Release 6.1" "X Version 11" .SH NAME xfs \- X font server .SH SYNOPSIS .B "xfs" [\-config \fIconfiguration_file\fP] [\-port \fItcp_port\fP] .SH DESCRIPTION .PP .I Xfs is the X Window System font server. It supplies fonts to X Window System display servers. .SH "STARTING THE SERVER" The server is usually run by a system administrator, and started via boot files like \fI/etc/rc.local\fR. Users may also wish to start private font servers for specific sets of fonts. .SH "OPTIONS" .TP 8 .B \-config configuration_file Specifies the configuration file the font server will use. .TP 8 .B \-ls listen-socket Specifies a file descriptor which is already set up to be used as the listen socket. This option is only intended to be used by the font server itself when automatically spawning another copy of itself to handle additional connections. .TP 8 .B \-port tcp_port Specifies the TCP port number on which the server will listen for connections. .SH "SIGNALS" .TP 8 .I SIGTERM This causes the font server to exit cleanly. .TP 8 .I SIGUSR1 This signal is used to cause the server to re-read its configuration file. .TP 8 .I SIGUSR2 This signal is used to cause the server to flush any cached data it may have. .TP 8 .I SIGHUP This signal is used to cause the server to reset, closing all active connections and re-reading the configuration file. .SH "CONFIGURATION" The configuration language is a list of keyword and value pairs. Each keyword is followed by an '=' and then the desired value. .PP Recognized keywords include: .sp .\" .IP "cache-size (cardinal)" .\" Size in bytes of the font server cache. .IP "catalogue (list of string)" Ordered list of font path element names. Use of the keyword "catalogue" is very misleading at present, the current implementation only supports a single catalogue ("all"), containing all of the specified fonts. .IP "alternate-servers (list of string)" List of alternate servers for this font server. .IP "client-limit (cardinal)" Number of clients this font server will support before refusing service. This is useful for tuning the load on each individual font server. .IP "clone-self (boolean)" Whether this font server should attempt to clone itself when it reachs the client-limit. .IP "default-point-size (cardinal)" The default pointsize (in decipoints) for fonts that don't specify. The default is 120. .IP "default-resolutions (list of resolutions)" Resolutions the server supports by default. This information may be used as a hint for pre-rendering, and substituted for scaled fonts which do not specify a resolution. A resolution is a comma-separated pair of x and y resolutions in pixels per inch. Multiple resolutions are separated by commas. .IP "error-file (string)" Filename of the error file. All warnings and errors will be logged here. .IP "port (cardinal)" TCP port on which the server will listen for connections. .IP "use-syslog (boolean)" Whether syslog(3) (on supported systems) is to be used for errors. .IP "deferglyphs (string)" Set the mode for delayed fetching and caching of glyphs. Value is "none", meaning deferred glyphs is disabled, "all", meaning it is enabled for all fonts, and "16", meaning it is enabled only for 16-bits fonts. .\" .IP "trusted-clients (list of string)" .\" Those clients the fontserver will talk to. Others .\" will be refused for the initial connection. An empty .\" list means the server will talk to any client. .SH "EXAMPLE" .nf # # sample font server configuration file # # allow a max of 10 clients to connect to this font server client-limit = 10 # when a font server reaches its limit, start up a new one clone-self = on # alternate font servers for clients to use alternate-servers = hansen:7101,hansen:7102 # where to look for fonts # the first is a set of Speedo outlines, the second is a set of # misc bitmaps and the last is a set of 100dpi bitmaps # catalogue = /usr/X11R6/lib/X11/fonts/speedo, /usr/X11R6/lib/X11/fonts/misc, /usr/X11R6/lib/X11/fonts/100dpi/ # in 12 points, decipoints default-point-size = 120 # 100 x 100 and 75 x 75 default-resolutions = 100,100,75,75 use-syslog = off .fi .sp .SH "FONT SERVER NAMES" One of the following forms can be used to name a font server that accepts TCP connections: .sp .nf tcp/\fIhostname\fP:\fIport\fP tcp/\fIhostname\fP:\fIport\fP/\fIcataloguelist\fP .fi .PP The \fIhostname\fP specifies the name (or decimal numeric address) of the machine on which the font server is running. The \fIport\fP is the decimal TCP port on which the font server is listening for connections. The \fIcataloguelist\fP specifies a list of catalogue names, with '+' as a separator. .PP Examples: \fItcp/fs.x.org:7100\fP, \fItcp/18.30.0.212:7101/all\fP. .PP One of the following forms can be used to name a font server that accepts DECnet connections: .sp .nf decnet/\fInodename\fP::font$\fIobjname\fP decnet/\fInodename\fP::font$\fIobjname\fP/\fIcataloguelist\fP .fi .PP The \fInodename\fP specifies the name (or decimal numeric address) of the machine on which the font server is running. The \fIobjname\fP is a normal, case-insensitive DECnet object name. The \fIcataloguelist\fP specifies a list of catalogue names, with '+' as a separator. .PP Examples: \fIDECnet/SRVNOD::FONT$DEFAULT\fP, \fIdecnet/44.70::font$special/symbols\fP. .SH "SEE ALSO" X(1), \fIThe X Font Service Protocol\fP, .br \fIFont server implementation overview\fP .SH BUGS Multiple catalogues should be supported. .SH AUTHORS Dave Lemke, Network Computing Devices, Inc .br Keith Packard, Massachusetts Institute of Technology .\" $XConsortium: fstobdf.man /main/7 1995/12/15 14:00:09 gildea $ .\" Copyright 1990, Network Computing Devices .\" Copyright (c) 1990 X Consortium .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the .\" "Software"), to deal in the Software without restriction, including .\" without limitation the rights to use, copy, modify, merge, publish, .\" distribute, sublicense, and/or sell copies of the Software, and to .\" permit persons to whom the Software is furnished to do so, subject to .\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included .\" in all copies or substantial portions of the Software. .\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR .\" OTHER DEALINGS IN THE SOFTWARE. .\" .\" Except as contained in this notice, the name of the X Consortium shall .\" not be used in advertising or otherwise to promote the sale, use or .\" other dealings in this Software without prior written authorization .\" from the X Consortium. .TH FSTOBDF 1 "Release 6.1" "X Version 11" .SH NAME fstobdf \- generate BDF font from X font server .SH SYNOPSIS .B "fstobdf" [ .B \-server .I server ] .B \-fn .I fontname .SH DESCRIPTION The \fIfstobdf\fP program reads a font from a font server and prints a BDF file on the standard output that may be used to recreate the font. This is useful in testing servers, debugging font metrics, and reproducing lost BDF files. .SH OPTIONS .TP 8 .B \-server \fIservername\fP This option specifies the server from which the font should be read. .TP 8 .B \-fn \fIfontname\fP This option specifies the font for which a BDF file should be generated. .SH ENVIRONMENT .TP 8 .B FONTSERVER default server to use .SH "SEE ALSO" xfs(1), bdftopcf(1), fslsfonts(1) .SH AUTHOR Olaf Brandt, Network Computing Devices .br Dave Lemke, Network Computing Devices .br .sp Jim Fulton, MIT X Consortium .\" $Header: ftio.1,v 78.1 96/01/22 22:24:23 ssa Exp $ .TA f .TH ftio 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ftio \- faster tape I/O .SH SYNOPSIS .CR "ftio -o"\c \(or\c .CR -O .RC [ achpvxAELM ] .RC [ -B .IR blksize ] .RC [ -D .IR type ] .RC [ -e .IR extarg ] .ifn .br .ifn \0\0\0 .RC [ -K .IR comment ] .RC [ -L .IR filelist ] .ift .br .ift \0\0\0 .RC [ -N .IR datefile ] .RC [ -S .IR script ] .RC [ -T .IR tty ] .ifn .br .ifn \0\0\0 .RC [ -Z .IR nobufs ] .I tapedev .RI [ pathnames ] .RC [ -F .IR ignorenames ] .PP .CR "ftio -i"\c \(or\c .CR -I .RC [ cdfmptuvxAEMPR ] .RC [ -B .IR blksize ] .RC [ -S .IR script ] .RC [ -T .IR tty ] .ifn .br .ifn \0\0\0 .RC [ -Z .IR nobufs ] .I tapedev .RI [ patterns ] .PP .C ftio -g .RC [ v ] .I tapedev .RI [ patterns ] .SH DESCRIPTION .C ftio is a tool designed specifically for copying files to tape drives. It performs faster than either .C cpio or .C tar in comparable situations (see .IR cpio (1) and .IR tar (1)). .C ftio uses multiple processes (to read/write the file system and to write/read the tape device), with large amounts of memory sharing between processes as well as a large block size for reading and writing to the tape. .PP .C ftio is compatible with .C cpio in that output from .C cpio is always readable by .CR ftio , and output from .C ftio is readable by .CR cpio , except as explained in the "cpio Compatibility" section, later in the manpage. .PP .C ftio must be invoked with exactly one of the following options: .CR -o , .CR -O , .CR -i , .CR -I , or .CR -g . The .CR -o and .CR -O options specify that .CR ftio is writing "out" from file system to tape; the .CR -i and .CR -I options specify that .CR ftio is writing "in" from tape to file system. The .CR -o , .CR -O , .CR -i , and .CR -I options can be followed by modifiers that must appear immediately after the option with no spaces between the option and the modifier, as in .C ftio -idxE (see Modifiers section below). .PP .I tapedev specifies the name of a device special file for the tape device to which the output is written. A device on a remote machine can be specified in the form .IP .IC machine : device_special_file .PP .C ftio creates a server process from .CR /usr/sbin/rmt on the remote machine to access the tape device. If .C /usr/sbin/rmt does not exist on the remote system, .C ftio creates a server process from .CR /etc/rmt , on the remote machine to access the tape device. .SS Options .C ftio recognizes the following options: .RS .TP 15 .C -o Copy (out) files from the file system to .IR tapedev , including path name and status information. If .I pathnames are specified, .C ftio recursively descends .I pathnames looking for files, and copies those files to .IR tapedev . If .I pathnames are not specified, .C ftio reads the standard input to obtain a list of path names to copy. .CR ftio can copy to multiple tapes if required. For every tape used, .C ftio generates a tape header containing the current tape volume number, machine node name and type, operating system name, release and version numbers (all from the .C uname() system call; see .IR uname (2)), username of the person issuing the .CR ftio command, the time and date the command was executed, the number of consecutive times the current media has been used, a comment field, and other items used internally by .CR ftio . The tape header is separated from the main body of the tape archive by an end-of-file mark. The tape header can be read by invoking .C cat with the device file name as the first argument (see .IR cat (1)). Note, character and block device special files written with the .C -o option are not transportable to other .SM HP-UX implementations. .TP .C -O Copy out files in the same way as .CR "ftio -ocva" , when no modifiers are used with the .CR -O . However, if the .C .ftiorc file exists in the user's home directory, .C ftio opens this file and scans for lines preceded by .CR O= . Options defined on matching lines are passed to .C ftio as if they had been specified on the command line. See .SM EXAMPLES section. .TP .C -i Extract (copy into the file system) files from .IR tapedev , which is assumed to be a tape and the product of a previous .C ftio -o operation. Only files with names that match .IR patterns , according to the rules of Pattern Matching Notation (see .IR regexp (5)), are selected. In addition, a leading .C ! within a pattern indicates that only those names that do .I not match the remainder of the pattern should be selected. Multiple .I patterns can be specified. If no .I patterns are specified, the default for .I patterns is .C * (that is, select all files). The extracted files are conditionally created and copied into the current directory tree, based upon the options described below. The permissions of the files are those of the previous .C -o operation. .TP .C -I Extract (copy into the file system) files in the same way as for .CR "ftio -icdmv" , when no modifiers are used with the .CR -I . However, if the .C .ftiorc file exists in the user's home directory, .C ftio opens this file, and scans for lines preceded by .CR I= . Options defined on matching lines are passed to .C ftio as if they had been specified on the command line. See .SM EXAMPLES section. .TP .C -g Read the file list in .IR tapedev . If .I patterns is specified, only file names that match are printed. Note that file names are always preceded by the volume that .C ftio expected the file to be on when the file list was created; thus only the last volume is valid in this respect. .TP .CI -e \0extarg Specifies the handling of any extent attributes of the file[s] to be archived. Extent attributes cannot be preserved when archiving files with .C ftio. .I extarg takes one of the following values: .RS .RS .TP 10 .PD0 .C warn Issue a warning message and archive the file without extent attributes. .TP .C ignore A file with extent attributes will be archived, without preserving the extent attributes and without issuing a warning message. .TP .C force A file with extent attributes will not be archived and a warning message will be issued. .sp .PD .RE If .C -e is not specified, the default value for .I extarg is .CR warn . .RE .TP .CI -B \0blksize Specify the size (in bytes) of blocks written to tape. This number can end with .CR k , which specifies multiplication by 1024. The use of larger blocks generally improves performance and tape usage. The maximum allowable block size is limited by the tape drive used. A default of 16\|384 bytes is set because this is the maximum block size on most Hewlett-Packard tape drives. .TP .CI -D \0type Descend a directory recursively, only if the file system to which it belongs is .IR type , where .I type can be .CR hfs , .CR vxfs , or .CR nfs . .TP .CI -F \0ignorenames Arguments following .C -F specify .I patterns that should not be copied to the tape. The same rules apply to .I ignorenames as to .IR patterns ; see the earlier description for .CR "ftio -i" . .TP .CI -K \0comment Specify a comment to be placed in the .C ftio tape header. .TP .CI -L \0filelist Create a list of the files being backed up. .I filelist specifies the output file. If .I pathnames is specified, perform the file search and generate a list of files prior to actually commencing the backup. This list is then appended to the tape header of each tape in the backup as a list of files that .C ftio attempted to fit onto this tape. The last tape in the backup contains a catalog identifying where the files are in the archive set. If .I pathnames is not also specified, the file list is taken from standard input before the backup begins. In addition to generating file lists, the .C -L option implements tape checkpointing, allowing the backup to restart from a write failure on bad media. .TP .C -M Make fully compatible with .CR cpio . That is, do not generate or expect tape headers and change the default block size to 5120 bytes. (See the cpio Compatibility section below.) .TP .CI -N \0datefile Only files newer than the file specified in .I datefile are copied to tape. .TP .C -R Resynchronize automatically, when .C ftio goes out of phase. This is useful when restoring from a multi-tape backup from tapes other than the first. By default, .C ftio asks the user if resynchronization is required. .TP .CI -S \0script Specify a command to be invoked every time a tape is completed in a multi-tape backup. The command is invoked by the Bourne shell (see .IR sh-bourne (1) with the following arguments: .IR "script tape_no user_name" . .I script is the string argument .I script specified with the .C -S option. .I tape_no is the number of the tape required, and .I user_name is the user who invoked .CR ftio . Typically, the string .I script specifies a shell script which is used to notify the user that a tape change is required. .TP .CI -T " tty" Specify alternative to .CR /dev/tty . Normally .C /dev/tty is opened by .C ftio when terminal interaction is required. .TP .CI -Z \0nobufs Specify the number of .I blksize chunks of memory to use as buffer space between the two processes, where .I blksize is the size of blocks written to the tape. More chunks is usually better, but a point is reached where no improvement is gained, and performance might deteriorate as buffer space is swapped out of main memory. A default value of 16 is set for .IR nobufs , but using 32 or 64 might improve performance if your system is not heavily loaded. Best results are obtained when backups are performed with the system in single-user mode (see .IR shutdown (1M)). .RE .SS Modifiers The following modifiers can be used with certain options as indicated in the .SM SYNOPSIS: .RS .TP 8 .C a After files are copied to tape, reset their access time to appear as though the files were not accessed by .CR ftio . .TP .C c Write header information in .SM ASCII character form, for portability. .TP .C d When restoring files, create directories as needed. .TP .C f Copy in all files except those that match .IR patterns . .TP .C h Archive the files to which symbolic links point, as if they were normal files or directories. By default, .C ftio archives the link itself. .TP .C m Retain previous file modification time and ownership of file. Restoring modification time does not apply to directories that are being restored. .TP .C p At the end of the backup, print the number of blocks transferred, the total time taken (excluding tape rewind and reel-change time), and the effective transfer rate calculated from these figures. These values are printed at the end of each tape if .C p is specified twice. .TP .C t Print only a table of contents of the input. No files are created, read, or copied. .TP .C u Copy unconditionally (by default, .CR ftio does not replace a newer file with a older file of the same name). .TP .C v Be verbose. Print a list of file names and tape headers. When used with the .C t modifier, the table of contents looks the same as the output of the .C ls -l (ell) command (see .IR ls (1)). .TP .C x Save or restore device special files. .C ftio uses .IR mknod (2) to recreate these files during a restore operation. Thus, this modifier is restricted to users with appropriate privileges. This is intended for intrasystem (backup) use. Restoring device files onto a different system can be very dangerous. .TP .C A If copying from tape .RC ( -i or .C -I option), print all file names found on the tape archive, noting which files have been restored. This is useful when the user restores selected files, but wants to know which (if any) files are on the tape. .IP If copying to tape .RC ( -o or .C -O option), the .C A modifier suppresses warning messages regarding optional access control list entries. .IR ftio (1) does not back up optional access control list entries in a file's access control list (see .IR acl (5)). Normally, a warning message is printed for each file that has optional access control list entries. .TP .C E When archiving, store all files having absolute path names (that is, path names beginning with .CR / ) with path names relative to the root directory (in other words, remove the leading .CR / ). On restoration, any files in the archive that had an absolute path name before archiving are restored relative to the current directory. .TP .C L Same as the .C -L option, except that the file list is left in the current directory as the file .CR ftio.list , instead of the file named in .IR filelist . .TP .C P On restoration, use .C prealloc() to allocate disk space beforehand for the file (see .IR prealloc (2)). This vastly improves the localization of file fragments. .PP When end-of-tape is reached, .C ftio invokes .I script if the .C -S option was specified, rewinds the current tape, then asks the user to mount the next tape. .PP To pass one or more metacharacters to .C ftio without having the shell expand them, protect them either by preceding each of them with a backslash (as in .CR /usr\e* ), or enclosing them in protective single quotes (as in .CR '/usr*' ). .RE .SS cpio Compatibility .C ftio uses the same archive format as .CR cpio . However, by default .C ftio creates tape headers and uses a tape block size of 16KB. .C cpio by default uses 512-byte blocks. When used with the .C -B option, .C cpio uses 5120 byte blocks. To achieve full compatibility with .C cpio in either input or output mode, the user should specify the .C M modifier. .C ftio -oM creates a single- or multi-tape archive that has no tape headers, and, by default, the same block size as .C cpio .CR - [ o\c .RC \(or i ] B . An archive created by a .C cpio -oB command can be restored using .CR "ftio -iM" . If the .C M modifier of .C ftio is combined with a .C -B 512 block-size specification, full compatibility with .C cpio .CR - [ o \(or i ] (no .CR -B ) is achieved. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. .PP .C LC_CTYPE determines the characters matched by character class expressions in pattern matching notation. .PP .C LC_TIME determines the format and contents of date and time strings. .PP .C LANG determines the language in which messages are displayed. .PP If .C LC_COLLATE, .C LC_CTYPE, or .C LC_TIME is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of C (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C ftio behaves as if all internationalization variables are set to C. See .IR environ (5). .SS International Code Set Support Single-byte character code sets are supported. .SH EXAMPLES Copy the entire contents of the file system (including special files) onto tape drive .CR /dev/rmt/c0t0d0BEST : .IP .C ftio -ox /dev/rmt/c0t0d0BEST / .PP Restore all the files on .CR /dev/rmt/c0t0d0BEST , relative to the current directory: .IP .C ftio -idxE /dev/rmt/c0t0d0BEST .PP List the contents of a backup set created using .CR "ftio -o" . Note that use of the .C v modifier gives a more detailed listing, and displays the contents of tape headers. .IP .C ftio -itv /dev/rmt/c0t0d0BEST .PP Show how to use the .C .ftiorc file: .RS .PP Assume a .C .ftiorc file exists in the user's home directory and contains the following: .IP .C # Sample .ftiorc file. .br .C "I= cdmuvEpp -B 16k -S /usr/local/bin/ftio.change" .br .C "O= cavEpp -Z 8 -B 16k -S /usr/local/bin/ftio.change" .PP Invoke .C ftio with the following command line to back up the user's home directory and the operating system commands directory: .IP .C "ftio -O /dev/rmt/c0t0d0BEST /home/my_home /usr/sbin" .PP Specifying the .C -O option causes .C ftio to check the .C .ftiorc file for additional options. In this case, character headers are generated, access times are reset, a listing of the files copied are printed to standard output, all file names are copied to .C /dev/rmt/c0t0d0BEST with path names relative to .CR / , performance data is printed when the backup is complete (and at every tape change), and, if the backup goes beyond one media the script, .C /usr/local/bin/ftio.change is invoked by .C ftio after each media is completed. .RE .SH WARNINGS Because of industry standards and interoperability goals, .CR ftio does not support the archival of files larger than 2GB or files that have user/group IDs greater than 60K. Files with user/group IDs greater than 60K are archived and restored under the user/group ID of the current process. .PP .CR ftio operates using System V shared memory and semaphores. The resources committed to these functions are not freed automatically by the system when the process terminates. .C ftio does this only when it terminates normally, or when it terminates after receiving one the following signals: .CR SIGHUP , .CR SIGINT , .CR SIGTERM . Any other signal is handled in the default manner described by .IR signal (2). Note that the behavior for .C SIGKILL is to terminate the process without delay. Thus, if .C ftio receives a .C SIGKILL signal (as might be produced by the indiscriminate use of .C kill -9 (see .IR kill (1)), system resources used for shared memory and semaphores are not returned to the system. If it becomes necessary to terminate an invocation of .CR ftio , use .CR "kill -15" instead. Current system usage of shared memory and semaphores can be checked using the .C ipcs command (see .IR ipcs (1)). Committed resources can be removed using .C ipcrm (see .IR ipcrm (1)). .SH AUTHOR .C ftio was developed by HP. .SH SEE ALSO cpio(1), find(1), ipcs(1), ipcrm(1), kill(1), ls(1), rmt(1M), mknod(2), prealloc(2), signal(2), uname(2), acl(5), environ(5), lang(5), regexp(5), mt(7). .\" index@\f4ftio\f1 \- faster tape \s-1I/O\s+1@@@\f3ftio(1)\f1 .\" index@faster tape \s-1I/O\s+1@@@\f3ftio(1)\f1 .\" index@tape \s-1I/O\s+1, faster@@@\f3ftio(1)\f1 .\" index@\s-1I/O\s+1, faster tape@@@\f3ftio(1)\f1 .\" .\" toc@\f3ftio(1)\f1:\0\0\f4ftio\f1@@@faster tape I/O .\" $Header: ftp.1,v 72.5 94/12/09 14:55:33 ssa Exp $ .TA f .TH ftp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ftp \- file transfer program .SH SYNOPSIS .C ftp .RC [ -g ] .RC [ -i ] .RC [ -n ] .RC [ -v ] .RC [ -B .IR size ] .RI [ \|server-host\| ] .SH DESCRIPTION .C ftp is a user interface to the File Transfer Protocol. .C ftp copies files over a network connection between the local ``client'' host and a remote ``server'' host. .C ftp runs on the client host. .SS Options The .C ftp command supports the following options: .RS .TP .C -g Disable file name ``globbing''; see the .C glob command, below. By default, when this option is not specified, globbing is enabled. .TP .C -i Disable interactive prompting by multiple-file commands; see the .C prompt command, below. By default, when this option is not specified, prompting is enabled. .TP .C -n Disable ``auto-login''; see the .C open command, below. By default, when this option is not specified, auto-login is enabled. .TP .C -v Enable verbose output; see the .C verbose command, below. If this option is not specified, .C ftp displays verbose output only if the standard input is associated with a terminal. .TP .C -B Set the buffer size of the data socket to .I size blocks of 1024 bytes. The valid range for .I size is an integer from 1 to 64 (default is 56). .br .CR Note : A large buffer size will improve the performance of .C ftp on fast links (e.g., FDDI), but may cause long connection times on slow links (e.g., X.25). .RE .PP The name of the server host that .C ftp communicates with can be specified on the command line. If the server host is specified, .C ftp immediately opens a connection to the server host; see the .C open command, below. Otherwise, .C ftp waits for commands from the user. .PP File Transfer Protocol specifies file transfer parameters for .IR type , .IR mode , .IR form , and .IR struct . .C ftp supports the .CR ASCII , .CR binary , and .C tenex File Transfer Protocol .IR types . .C ASCII is the default FTP .IR type . (It should be noted though that, whenever .C ftp establishes a connection between two similar systems, it switches automatically to the more efficient .C binary type.) .C ftp supports only the default values for the file transfer parameters .I mode which defaults to .CR stream , .I form which defaults to .CR non-print , and .I struct which defaults to .CR file . .SH COMMANDS .C ftp supports the following commands. Command arguments with embedded spaces must be enclosed in quotes (for example, "argument with embedded spaces"). .TP .CR ! [\|\f2command\fP\0[\|\f2args\fP\|]\|] Invoke a shell on the local host. The .C SHELL environment variable specifies which shell program to invoke. .C ftp invokes .C /usr/bin/sh if .C SHELL is undefined. If .I command is specified, the shell executes it and returns to .CR ftp . Otherwise, an interactive shell is invoked. When the shell terminates, it returns to .CR ftp . .TP .CR $ " \f2macro-name\fP [\|\f2args\fP\|] Execute the macro .I macro-name that was defined with the .C macdef command. Arguments are passed to the macro unglobbed. .TP .CR account \0[\|\f2passwd\fP\|] Supply a supplemental password required by a remote system for access to resources once a login has been successfully completed. If no argument is included, the user is prompted for an account password in a non-echoing input mode. .TP .CR append \0\f2local-file\fP\0[\|\f2remote-file\fP\|] Copy .I local-file to the end of .IR remote-file . If .I remote-file is left unspecified, the local file name is used in naming the remote file after being altered by any .I ntrans or .I nmap setting. .TP .C ascii Set the file transfer .I type to network ASCII. This is the default type. .TP .C bell Sound a bell after each file transfer completes. .TP .C binary Set the file transfer .I type to .CR binary . .TP .C bye Close the connection to the server host if a connection was open, and exit. Typing an end-of-file (EOF) character also terminates and exits the session. .TP .C case Toggle remote computer file name case mapping during .C mget commands. When .C case is on (the default is off), remote computer file names with all letters in uppercase are written in the local directory with the letters mapped to lowercase. .TP .CI cd \0remote-directory Set the working directory on the server host to .IR remote-directory . .TP .C cdup Set the working directory on the server host to the parent of the current remote working directory. .TP .CI chmod \0mode\0file-name Change the permission modes of the file .I file-name on the remote system to .IR mode . .TP .C close Terminate the connection to the server host. The .C close command does not exit .CR ftp . Any defined macros are erased. .TP .C cr Toggle carriage return stripping during .C ascii type file retrieval. Records are denoted by a carriage-return/line-feed sequence during .C ascii type file transfer. When .C cr is on (the default), carriage returns are stripped from this sequence to conform with the UNIX single line-feed record delimiter. Records on non-\c UNIX remote systems may contain single line-feeds; when an .C ascii type transfer is made, these line-feeds can be distinguished from a record delimiter only when .C cr is off. .TP .CI delete " remote-file" Delete .IR remote-file . The .I remote-file can be an empty directory. No globbing is done. .TP .CR dir \0[\|\f2remote-directory\fP\|]\0[\|\f2local-file\fP\|] Write a .I remote-directory listing to standard output or optionally to .IR local-file . If neither .I remote-directory nor .I local-file is specified, list the remote working directory to standard output. If interactive prompting is on, .C ftp prompts the user to verify that the last argument is indeed the target file for .C dir output. Globbing characters are always expanded. .TP .C disconnect A synonym for .CR close . .TP .CI form \0format Set the file transfer .I form to .IR format . The only supported format is .C non-print .TP .CR get \0\f2remote-file\fP\0[\|\f2local-file\fP\|] Copy .I remote-file to .IR local-file . If .I local-file is unspecified, .C ftp uses the specified .I remote-file name as the .I local-file name, subject to alteration by the current .IR case , .IR ntrans , and .I nmap settings. .TP .C glob Toggle file name globbing. When file name globbing is enabled, .C ftp expands .IR csh (1) metacharacters in file and directory names. These characters are .CR * , .CR ? , .CR [ , .CR ] , .CR ~ , .CR { , and .CR } . The server host expands remote file and directory names. Globbing metacharacters are always expanded for the .C ls and .C dir commands. If globbing is enabled, metacharacters are also expanded for the multiple-file commands .CR mdelete , .CR mdir , .CR mget , .CR mls , and .CR mput. .TP .C hash Toggle printing of a hash-sign .RC ( # ) for each 1024 bytes transferred. .TP .CR help \0[\|\f2command\fP\|] Print an informative message about the .C ftp command called .IR ftp-command . If .I ftp-command is unspecified, print a list of all .C ftp commands. .TP .CR idle \0[\|\f2seconds\fP\|] Set the inactivity timer on the remote server to .I seconds seconds. If .I seconds is omitted, .C ftp prints the current inactivity timer. .TP .CR lcd \0[\|\f2local-directory\fP\|] Set the local working directory to .IR local-directory . If .I local-directory is unspecified, set the local working directory to the user's local home directory. .TP .CR ls \0[\|\f2remote-directory\fP\|]\0[\|\f2local-file\fP\|] Write a listing of .I remote-directory to .IR local-file . The listing includes any system-dependent information that the server chooses to include; for example, most UNIX systems produce output from the command .C ls -l (see also .CR nlist ). If neither .I remote-directory nor .I local-file is specified, list the remote working directory. If globbing is enabled, globbing metacharacters are expanded. .TP .CI macdef \0macro-name Define a macro. Subsequent lines are stored as the macro .IR macro-name ; an empty input line terminates macro input mode. There is a limit of 16 macros and 4096 total characters in all defined macros. Macros remain defined until a .C close command is executed. The macro processor interprets .C $ and .C \e as special characters. A .C $ followed by a number (or numbers) is replaced by the corresponding argument on the macro invocation command line. A .C $ followed by an .I i signals to the macro processor that the executing macro is to be looped. On the first pass .CI $ i is replaced by the first argument on the macro invocation command line, on the second pass it is replaced by the second argument, and so on. A .C \e followed by any character is replaced by that character. Use the .C \e to prevent special treatment of the .CR $ . .TP .CR mdelete \0[\|\f2remote-files\fP\|] Delete .IR remote-files . If globbing is enabled, globbing metacharacters are expanded. .TP .CI mdir \0remote-files\0local-file Write a listing of .I remote-files to .IR local-file . If globbing is enabled, globbing metacharacters are expanded. If interactive prompting is on, .C ftp prompts the user to verify that the last argument is indeed the target local file for .C mdir output. .TP .CI mget \0remote-files Copy .I remote-files to the local system. If globbing is enabled, globbing metacharacters are expanded. The resulting local file names are processed according to .IR case , .IR ntrans , and .I nmap settings. .TP .CI mkdir \0directory-name Create remote .IR directory-name . .TP .CI mls \0remote-files\0local-file Write an abbreviated listing of .I remote-files to .IR local-file . If globbing is enabled, globbing metacharacters are expanded. If interactive prompting is .IR on , .C ftp prompts the user to verify that the last argument is indeed the target local file for .C mls output. .TP .CR mode \0[\|\f2mode-name\fP\|] Set the FTP file transfer .I mode to .IR mode-name . The only supported mode is .CR stream . .TP .CI modtime \0remote-file Show the last modification time of .IR remote-file . .TP .CI mput \0local-files Copy .I local-files from the local system to the remote system. The remote files have the same name as the local files processed according to .I ntrans and .I nmap settings. If globbing is enabled, globbing characters are expanded. .TP .CI newer \0file-name Get the file only if the modification time of the remote file is more recent that the file on the current system. If the file does not exist on the current system, the remote file is considered .IR newer . Otherwise, this command is identical to .CR get . .TP .CR nlist \0[\|\f2remote-directory\fP\|]\0[\|\f2local-file\fP\|] Write an abbreviated listing of .I remote-directory to .IR local-file . If .I remote-directory is left unspecified, the current working directory is used. If interactive prompting is on, .C ftp prompts the user to verify that the last argument is indeed the target local file for .C nlist output. .TP .CR nmap \0[\|\f2inpattern\0outpattern\fP\|] Set or unset the filename mapping mechanism. If no arguments are specified, the filename mapping mechanism is unset. If arguments are specified, remote filenames are mapped during .C mput commands and .C put commands issued without a specified remote target filename. If arguments are specified, local filenames are mapped during .C mget commands and .C get commands issued without a specified local target filename. This command is useful when connecting to a non-\c UNIX remote computer with different file naming conventions or practices. The mapping follows the pattern set by .I inpattern and .IR outpattern . .I inpattern is a template for incoming filenames (which may have already been processed according to the .C ntrans and .C case settings). Variable templating is accomplished by including the sequences .CR $1 , .CR $2 ,\0..., .CR $9 in .IR inpattern . Use .C \e to prevent this special treatment of the .C $ character. All other characters are treated literally, and are used to determine the .C nmap .I inpattern variable values. For example, given .I inpattern .C $1.$2 and the remote file name .CR mydata.data , .C $1 would have the value .CR mydata , and .C $2 would have the value .CR data . The .I outpattern determines the resulting mapped filename. The sequences .CR $1 , .CR $2 ,\0..., .C $9 are replaced by any value resulting from the .I inpattern template. The sequence .C $0 is replaced by the original filename. Additionally, the sequence .CI [ seq1 , seq2 ] is replaced by .I seq1 if .I seq1 is not a null string; otherwise it is replaced by .IR seq2 . For example, the command .C "nmap $1.$2.$3 [$1,$2].[$2,file]" would yield the output filename .C myfile.data for input filenames .C myfile.data and .CR myfile.data.old , .C myfile.file for the input filename .CR myfile , and .C myfile.myfile for the input filename .CR .myfile . Spaces can be included in .IR outpattern , as in the example: .C "nmap $1 | sed ""s/ *$//"" > $1" . Use the .C \e character to prevent special treatment of the .CR $ , .CR [ , .CR ] , and .CR , characters. .TP .CR ntrans \0[\|\f2inchars\fP\0[\|\f2outchars\fP\|]\|] Set or unset the filename character translation mechanism. If no arguments are specified, the filename character translation mechanism is unset. If arguments are specified, characters in remote filenames are translated during .C mput commands and .C put commands issued without a specified remote target filename. If arguments are specified, characters in local filenames are translated during .C mget commands and .C get commands issued without a specified local target filename. This command is useful when connecting to a non-\c UNIX remote computer with different file naming conventions or practices. Characters in a filename matching a character in .I inchars are replaced with the corresponding character in .IR outchars . If the character's position in .I inchars is longer than the length of .IR outchars , the character is deleted from the file name. .TP .CR open \0\f2server-host\fP\0[\|\f2port-number\fP\|] Establish a connection to .IR server-host , using .I port-number (if specified). If .I auto-login is enabled, .C ftp attempts to log into the server host. .TP .C prompt Toggle interactive prompting. By default, .C ftp prompts the user for a yes or no response for each output file during multiple-file commands. If interactive prompting is disabled, .C ftp performs the command for all specified files. .TP .CI proxy \0ftp-command Execute an .C ftp command on a secondary control connection. This command allows simultaneous connection to two remote FTP servers for transferring files between the two servers. The first .C proxy command should be an .CR open , to establish the secondary control connection. Enter the command .C proxy ? to see other FTP commands executable on the secondary connection. The following commands behave differently when prefaced by .CR proxy : .C open does not define new macros during the auto-login process, .C close does not erase existing macro definitions, .C get and .C mget transfer files from the host on the primary control connection to the host on the secondary control connection, and .CR put , .CR mput , and .C append transfer files from the host on the secondary control connection to the host on the primary control connection. Third party file transfers depend upon support of the FTP protocol .C PASV command by the server on the secondary control connection. .TP .CR put \0\f2local-file\fP\0[\|\f2remote-file\fP\|] Copy .I local-file to .IR remote-file . If .I remote-file is unspecified, .C ftp assigns the .I local-file name, processed according to any .I ntrans or .I nmap settings, to the .I remote-file name. .TP .C pwd Write the name of the remote working directory to .IR stdout . .TP .C quit A synonym for .CR bye . .TP .CI quote \0arguments Send .IR arguments , verbatim, to the server host. See .IR ftpd (1M). .TP .CR recv \0\f2remote-file\fP\0[\|\f2local-file\fP\|] A synonym for .CR get . .TP .CR reget \0\f2remote-file\fP\0[\|\f2local-file\fP\|] .C reget acts like .CR get , except that if .I local-file exists and is smaller than .IR remote-file , .I local-file is presumed to be a partially transferred copy of .I remote-file and the transfer is continued from the apparent point of failure. This command is useful when transferring very large files over networks that tend to drop connections. .TP .CR rhelp \0[\|\f2command-name\fP\|] Request help from the server host. If .I command-name is specified, supply it to the server. See .IR ftpd (1M). .TP .CR rstatus \0[\|\f2file-name\fP\|] With no arguments, show status of remote machine. If .I file-name is specified, show status of .I file-name on remote machine. .TP .CI rename \0remote-from\0remote-to Rename .IR remote-from , which can be either a file or a directory, to .IR remote-to . .TP .C reset Clear reply queue. This command re-synchronizes command/reply sequencing with the remote FTP server. Resynchronization may be necessary following a violation of the FTP protocol by the remote server. .TP .CI restart \0marker Restart the immediately following .C get or .C put at the indicated .IR marker . On UNIX systems, marker is usually a byte offset into the file. .TP .CI rmdir \0remote-directory Delete .IR remote-directory . .I remote-directory must be an empty directory. .TP .C runique Toggle storing of files on the local system with unique filenames. If a file already exists with a name equal to the target local filename for a .C get or .C mget command, a .C .1 is appended to the name. If the resulting name matches another existing file, a .C .2 is appended to the original name. If this process continues up to .CR .99 , an error message is printed, and the transfer does not take place. .C ftp reports the unique filename. Note that .C runique does not affect local files generated from a shell command (see below). The default value is .CR off . .TP .CR send \0\f2local-file\fP\0[\|\f2remote-file\fP\|] A synonym for .CR put . .TP .C sendport Toggle the use of .C PORT commands. By default, .C ftp attempts to use a .C PORT command when establishing a connection for each data transfer. If the .C PORT command fails, .C ftp uses the default data port. When the use of .C PORT commands is disabled, .C ftp makes no attempt to use .C PORT commands for each data transfer. This is useful for certain FTP implementations that ignore .C PORT commands but (incorrectly) indicate that they've been accepted. See .IR ftpd (1M). Turning .C sendport off may cause delays in the execution of commands. .TP .CI site \0arguments Send .IR arguments , verbatim, to the server host as a .C SITE command. See .IR ftpd (1M). .TP .CI size \0remote-file Show the size of .IR remote-file . .TP .C status Show the current status of .CR ftp . .TP .CR struct \0[\|\f2struct-name\f1\|] Set the FTP file transfer .I struct to .IR struct-name . The only supported .I struct is .CR file . .TP .C sunique Toggle storing of files on remote machine under unique file names. The remote server reports the unique name. By default, .C sunique is .CR off . .TP .C system Show the type of operating system running on the remote machine. .TP .C tenex Set the FTP file transfer .I type to .CR tenex . .TP .CR type \0[\|\f2type-name\f1\|] Set the FTP file transfer .I type to .IR type-name . If .I type-name is unspecified, write the current .I type to .IR stdout . .CR Ascii , .CR binary , and .C tenex are the .IR type s currently supported. .TP .CR umask \0[\|\f2newmask\fP\|] Set the default umask on the remote server to .IR newmask . If .I newmask is omitted, the current umask is printed. .TP .CR user \0\f2user-name\fP\0[\|\f2password\fP\|]\0[\|\f2account\fP\|] Log into the server host on the current connection, which must already be open. A .C .netrc file in the user's local home directory can provide the .IR user-name , .IR password , and optionally the .IR account ; see .IR netrc (4). Otherwise .C ftp prompts the user for this information. The HP-UX FTP server does not require an .IR account . For security reasons, .C ftp always requires a password. It does not log into remote accounts that do not have a password. .TP .C verbose Toggle verbose output. If verbose output is enabled, .C ftp displays responses from the server host, and when a file transfer completes it reports statistics regarding the efficiency of the transfer. .TP .CR ? \0[\|\f2command\fP\|] A synonym for the .C help command. Prints the .C help information for the specified .IR command . .SS Aborting A File Transfer To abort a file transfer, use the terminal interrupt key (usually .BR Ctrl-C ). Sending transfers are halted immediately. .C ftp halts incoming (receive) transfers by first sending a FTP protocol .C ABOR command to the remote server, then discarding any further received data. The speed at which this is accomplished depends upon the remote server's support for .C ABOR processing. If the remote server does not support the .C ABOR command, an .C ftp> prompt does not appear until the remote server completes sending the requested file. .PP The terminal interrupt key sequence is ignored while .C ftp awaits a reply from the remote server. A long delay in this mode may result from the .C ABOR processing described above, or from unexpected behavior by the remote server, including violations of the FTP protocol. If the delay results from unexpected remote server behavior, the local .C ftp program must be killed manually. .SS File Naming Conventions Files specified as arguments to .C ftp commands are processed according to the following rules. .TP 3 \(bu If the file name .C - is specified, .C ftp uses the standard input (for reading) or standard output (for writing). .TP \(bu If the first character of the file name is .CR | , .C ftp interprets the remainder of the argument as a shell command. .C ftp forks a shell, using .C popen() (see .IR popen (3S)) with the supplied argument, and reads (writes) from standard output (standard input). If the shell command includes spaces, the argument must be quoted, as in: .RS .IP .ift \f4\s+1"| ls -lt"\f1\s0. .ifn \f3"| ls -lt"\f1. .RE .IP A particularly useful example of this mechanism is: .RS .IP .ift \f4\s+1"| dir . | more"\f1\s0. .ifn \f3"| dir . | more"\f1. .RE .TP \(bu Otherwise, if globbing is enabled, .C ftp expands local file names according to the rules used by the C shell (see .IR csh (1)); see the .C glob command, below. If the .C ftp command expects a single local file (e.g. .CR put ), only the first filename generated by the globbing operation is used. .TP \(bu For .C mget commands and .C get commands with unspecified local file names, the local filename is named the same as the remote filename, which may be altered by a .CR case , .CR ntrans , or .C nmap setting. The resulting filename may then be altered if .C runique is on. .TP \(bu For .C mput commands and .C put commands with unspecified remote file names, the remote filename is named the same as the local filename, which may be altered by a .C ntrans or .C nmap setting. The resulting filename may then be altered by the remote server if .C sunique is on. .SH WARNINGS Correct execution of many commands depends upon proper behavior by the remote server. .SH AUTHOR .C ftp was developed by the University of California, Berkeley. .SH SEE ALSO csh(1), rcp(1), ftpd(1M), netrc(4), ftpusers(4), hosts(4). .\" .\" index@\f4ftp\f1 \- file transfer program@@@\f3ftp(1)\f1 .\" index@\f1file transfer program@@@\f3ftp(1)\f1 .\" index@\f1transfer files between systems@@@\f3ftp(1)\f1 .\" index@\f1copy files between systems@@@\f3ftp(1)\f1 .\" index@\f1move files between systems@@@\f3ftp(1)\f1 .\" .\" toc@\f3ftp(1)\f1:\0\0\f4ftp\f1@@@file transfer program .\" .\" fileset_database@ftp.1 INETSVCS-MAN .\" $Header: gencat.1,v 72.6 94/11/14 15:19:03 ssa Exp $ .TA g .TH gencat 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gencat \- generate a formatted message catalog file .SH SYNOPSIS .C gencat .RC [ -l ] .I catfile .IR msgfile \0... .SH DESCRIPTION Message catalogs allow a program to process input and produce output according to local customs and languages. For details, see .IR "Native Language Support Users Guide" . .PP The .CR gencat command merges each message source .I msgfile into a formatted message catalog .I catfile that can be accessed by .CR catgets() (see .IR catgets (3C)). If .I catfile does not exist, it is created. If .I catfile exists, its messages are included in the new .IR catfile . If set and message numbers collide, the new message text in .I file replaces the old message text in .IR catfile . A .I msgfile consists of message, directive, and comment lines (all without leading spaces or tabs) described below. Except as noted, fields are separated by one or more space or tab characters. .PP If .CR - is specified as catalog file, standard output is used. .PP If .CR - is specified for an instance of message file, standard input is used. .RS .TP 23 .CI $set " s \f1[\fPcomment\f1]\fP A .CR $set directive specifies the set .IR s , of the messages that follow until the next .CR $set or end-of-file appears. The set number .I s is an unsigned integer in the range 1 through .CR NL_SETMAX . Any string following the set number is treated as a comment. If a .CR $set directive is not specified, messages are put in the default set .CR NL_SETD . .IP Set numbers must be in ascending order within a .I msgfile but need not be contiguous. .TP .CI $delset " s \f1[\fPcomment\f1]\fP" A .CR $delset directive deletes the message set identified by the set number .IR s , from an existing message catalog. Any string following the set number is treated as a comment. .TP .I m message_text A message line specifies a message number .IR m , and associated message text. The message number .I m is an unsigned integer in the range 1 through .CR NL_MSGMAX . The .I message_text is a C string, including spaces, tabs and \e (backslash) escapes, but by default without surrounding quotes (see .CR $quote directive below). The message number .I m is separated from the .I message_text by a single space or tab character. The .I message_text begins with the first character following the separator and ends at new-line. Extra spaces or tabs (including any trailing spaces or tabs) are considered part of the .IR message_text . .IP The .I message_text of a message line is stored in .I catfile with message number .I m and set number .I s specified by the most recent .CR $set directive. .IP Message numbers must be in ascending order within a set, but need not be contiguous. .IP Note that the space or tab separator distinguishes insertion of a null message from deletion of a message. If a message line has a number and separator but no text, the message number and an associated null message string are stored in .IR catfile . If a message line has a number but neither separator nor text, the message number and its associated message text are deleted from .IR catfile . .TP .C -l If the .C -l option is specified, the length of .I message_text must be no more than .CR MAX_BUFLEN \(mi 1 bytes. If the .CR -l option is not specified, the length of .I message_text must be no more than .C NL_TEXTMAX bytes. See .IR catgets (3C), for message length limits imposed by these routines. .TP .CR $quote " [\f2q comment\fP]" A .CR $quote directive specifies a quote character .IR q , used to surround .I message_text and make leading and trailing space visible in a message line. Any string following the specified quote character .I q is treated as a comment. By default, or if a quote character .I q not is supplied, quoting of .I message_text is not recognized. .TP .CI $ " comment" A .CR $ followed by a space or tab is treated as a comment and can appear anywhere in a file. A line consisting of zero or more spaces or tabs is treated as a comment line. .RE .PP .CR NL_TEXTMAX , .CR NL_SETMAX , and .CR NL_MSGMAX are defined in .CR . .CR NL_SETD is defined in .CR . .CR MAX_BUFLEN is defined in .CR . .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG provides a default value for the internationalization variables that are unset or null. If .CR LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .CR gencat will behave as if all internationalization variables are set to "C". See .IR environ (5). .PP .CR LC_ALL , if set to a non-empty string value, overrides the values of all of the other internationalization variables. .PP .CR LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .CR LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .CR NLSPATH determines the location of message catalogs for the processing of .CR LC_MESSAGES . .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS The .CR $quote directive is not currently supported on the HP MPE and RTE operating systems. .SH AUTHOR .CR gencat was developed by HP and the X/Open Company, Ltd. .SH SEE ALSO dumpmsg(1), findmsg(1), insertmsg(1), catgets(3C), catopen(3C). .PP .IR "Native Language Support Users Guide" . .SH STANDARDS CONFORMANCE .CR gencat ": XPG2, XPG3" .\" .\" index@\f4gencat\f1 \- generate a formatted message catalog file@@@\f3gencat(1)\f1 .\" index@\f1generate a formatted message catalog file@@@\f3gencat(1)\f1 .\" index@\f1formatted message catalog file, generate a@@@\f3gencat(1)\f1 .\" index@\f1message catalog file, generate a formatted@@@\f3gencat(1)\f1 .\" index@\f1catalog file, generate a formatted message@@@\f3gencat(1)\f1 .\" index@\f1file, generate a formatted message catalog@@@\f3gencat(1)\f1 .\" .\" toc@\f3gencat(1)\f1:\0\0\f4gencat\f1@@@generate a formatted message catalog file\f1 .\" $Header: genxlt.1,v 74.1 95/05/10 21:30:38 ssa Exp $ .TA g .TH genxlt 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME genxlt \- generate iconv translation tables .SH SYNOPSIS .C genxlt [ .C -f .I output_filename ] [ input_filename ] .SH DESCRIPTION .C genxlt generates a compiled, non-readable binary version of the iconv table that is suitable for use by .IR iconv (1) and .IR iconv (3C) . If .I input_filename or .I output_filename is not supplied, standard input and/or standard output will be used. .PP Since the output of .C genxlt is a binary, non-readable file, if the .C -f option is not used, the redirection symbol .C > maybe used to redirect the standard output to a file. .PP .SS Options .C genxlt recognizes the following options: .RS .TP 15 .CI -f " output_filename" If this option is not selected, the data will be sent to standard output, from where it could be redirected to a file. .RE .PP .C genxlt creates tables that are in a prescribed format and which can be interpreted by .IR iconv (3C) \'s default conversion routines. The input file has two columns, giving the filecode mapping between the two code sets. The entries are in hexadecimal. .PP The input file must be formatted as two columns of hexadecimal digits. Characters in the first column are translated into the characters in the second column. Lines preceded with .C # in the first column are ignored as comments on all lines except in the case of the following keywords: .I #Galley: and .I #What: .PP In addition to the data, which defines the filecode mapping, a .I Galley character (see .IR iconv (3C) ) may also be defined for that particular conversion. This is done by adding the line .CR #Galley: 0xnnnn" , to the beginning of the input file. The .C nnnn is any multi-byte character (see .BR EXAMPLES ). A .I What string (see .IR what (1) ), may also be defined in the input file using the entry .CR #What: . This string may contain information like version number, type of conversion, etc., which are not used in any way for the conversions. Note that if the .I What string is defined, it should appear before the .I Galley definition. .PP .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C genxlt will behave as if all internationalization variables are set to "C" (see .IR environ (5)). .PP If .C LC_ALL is set to a non-empty string value, it overrides the values of all the other internationalization variables. .PP .C LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .C NLSPATH determines the location of message catalogues for the processing of .CR LC_MESSAGES . .SS International Code Set Support Single and multi-byte character code sets are supported. .SH RETURN VALUE The exit values are: .RS 3 .TP 8 .C \00 Successful completion. .PD 0 .TP .C >0 Error condition occurred. .RE .PD .SH EXAMPLES This example compiles the .I iconv_input and puts the output binary in .CR /usr/lib/nls/iconv/tables/roma8=iso81. The following iconv statement uses the .I roma8=iso81 table to convert the .I data_file from code set .C roman8 to code set .CR iso8859-1 . .IP .C "% genxlt iconv_input > /usr/lib/nls/iconv/tables/roma8=iso81" .br .C "% iconv -f roma8 -t iso81 data_file" .br .PP This is an example of the input_file: .nf .IP .C "#What: CodesetA to CodesetB: version 1.0" .C "#Galley: 0xffff" .C "# the conversion data is as follows:" .C "0x01 0x01" .C "0x02 0x42" .C "..." .C "0xff87 0x4567" .C "..." .C "etc." .fi .PP .SH WARNINGS Because .CR genxlt will write over the existing table, it is wise to save the existing table into another file before using .CR genxlt . .PP Warnings are not given for incorrect data in the input_file. .PP You must have super-user privileges to install files in .CR /usr/lib/nls/iconv/tables . .SH FILES .PD 0 .TP 40 .C /usr/lib/nls/iconv/tables All tables must be installed in this directory. .SH SEE ALSO dmpxlt(1), iconv(1), iconv(3C). .SH STANDARDS COMPLIANCE .CR genxlt ": XPG4" .\" .\" toc@\f3genxlt(1)\f1:\0\0\f4genxlt\f1@@@generate iconv translation tables .\" .\" index@\f4genxlt\f1 \- generate iconv translation tables@@@\f3genxlt(1)\f1 .\" index@tables, generate iconv translation @@@\f3genxlt(1)\f1 .\" index@translation tables, generate iconv@@@\f3genxlt(1)\f1 .\" index@iconv translation tables, generate@@@\f3genxlt(1)\f1 .\" index@generate iconv translation tables@@@\f3genxlt(1)\f1 .\" .\" fileset_database@genxlt.1 USER-CMDS-MAN .\" $Header: get.1,v 76.2 95/08/03 17:48:51 ssa Exp $ .TA g .TH get 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME get \- get a version of an \s-1SCCS\s+1 file .SH SYNOPSIS .C get .RC [ -r .SM .IR SID\s0\| ] .RC [ -c .IR cutoff\| ] .IC [ -e ] .IC [ -b ] .RC [ -i .IR list\| ] .RC [ -x .IR list\| ] .RC [ -k ] .RC [ -l [ p ]\|] .RC [ -p ] .RC [ -s ] .RC [ -m ] .RC [ -n ] .RC [ -g ] .RC [ -t ] .RC [ -w .IR string \|] .RC [ -a .IR seq-number \|] .IR file \0... .SH DESCRIPTION The .CR get command generates an .SM ASCII text file from each named .SM SCCS file according to the specifications given by its option arguments, which begin with .CR - . The arguments can be specified in any order, but all option arguments apply to all named .SM SCCS files. If a directory is named, .CR get behaves as if each file in the directory was specified as a named file, except that non-\c .SM SCCS files (last component of the path name does not begin with .CR s. ) and unreadable files are silently ignored. If a file name of .CR - is given, the standard input is read and each line of the standard input is assumed to be the name of an .SM SCCS file to be processed. Again, non-\c .SM SCCS files and unreadable files are silently ignored. .PP The generated text is normally written into a file called the .I g-file whose name is derived from the .SM SCCS file name by simply removing the .CR s. prefix (see .SM FILES below). .SS Options Explanation of the option arguments below is based on processing only one .SM SCCS file. When processing multiple .SM SCCS files, the effects of any option argument applies independently to each named file. .RS .TP 15 .CI -r \s-1SID\s0 The .IR S "\s-1CCS\s+1 " ID entification string .SM (SID) of the version (delta) of an .SM SCCS file to be retrieved. Table 1 shows, for the most useful cases, which version of an .SM SCCS file is retrieved (as well as the .SM SID of the version to be eventually created by .CR delta if the .CR -e option is also used), as a function of the .SM SID specified (see .IR delta (1)). .TP .CI -c cutoff .I cutoff date-time, in the form: .RS .IP .SM .IR YY\| [ \|MM\| [ \|DD\| [\c .SM .IR \|HH\| [ \|MM\| [ \|SS\| ]\|]\|]\|]\|] .RE .IP No changes (deltas) to the .SM SCCS file which were created after the specified .I cutoff date-time are included in the generated .SM ASCII text file. Units omitted from the date-time default to their maximum possible values; that is, .CR -c7502 is equivalent to .CR -c750228235959 . Any number of non-numeric characters can separate the various 2-digit pieces of the .I cutoff date-time. This feature allows one to specify a .I cutoff date in the form: .CR "-c77/2/2 9:22:25" . Note that this implies that one can use the .CR %\&E% and .CR %\&U% identification keywords (see below) for nested .CR get s within, for example, a .CR send command (see .IR send (1)): .RS .IP .C ~!get\0\"-c%\&E%\0%\&U%\"\0s.file .RE .TP 15 .C -e Indicates that the .CR get is for the purpose of editing or making a change (delta) to the .SM SCCS file via a subsequent use of .CR delta . The .CR -e option used in a .CR get for a particular version .SM (SID) of the .SM SCCS file prevents further .CR get s for editing on the same .SM SID until .CR delta is executed or the .CR j (joint edit) flag is set in the .SM SCCS file (see .IR admin (1)). Concurrent use of .CR "get -e" for different .SM SID\c s is always allowed. Note, however, that only one user is permitted to do a concurrent .CR "get -e" (see .IR admin (1)). .IP If the .I g-file generated by .CR get with an .CR -e option is accidentally ruined in the process of editing it, it can be regenerated by re-executing the .CR get command with the .CR -k option in place of the .CR -e option. .IP .SM SCCS file protection specified via the ceiling, floor, and authorized user list stored in the .SM SCCS file (see .IR admin (1)) are enforced when the .CR -e option is used. .TP .CR -b Used with the .CR -e option to indicate that the new delta should have an .SM SID in a new branch as shown in Table 1. This option is ignored if the .CR b flag is not present in the file (see .IR admin (1)) or if the retrieved .I delta is not a leaf .IR delta . (A leaf .I delta is one that has no successors on the .SM SCCS file tree.) .IP Note: A branch .I delta can always be created from a non-leaf .IR delta . .TP .CI -i list A .I list of deltas to be included (forced to be applied) in the creation of the generated file. The .I list has the following syntax: .RS .IP .IC list\0 ::= \0range \(or .IC list , \0range .br .IC range\0 ::= \0\c .SM .I SID \(or .SM .I SID .C - .SM .I SID .RE .IP .SM SID, the .SM SCCS Identification of a delta, can be in any form shown in the ``\s-1SID\s+1 Specified'' column of Table 1. Partial .SM SID\s0s are interpreted as shown in the ``\s-1SID\s+1 Retrieved'' column of Table 1. See .SM WARNINGS. .TP .CI -x list A .I list of deltas to be excluded (forced not to be applied) in the creation of the generated file. See the .CR -i option for the .I list format. .TP .C -k Suppresses replacement of identification keywords (see below) in the retrieved text by their value. The .CR -k option is implied by the .CR -e option. .TP .CR -l [ p ] Causes a delta summary to be written into an .IR l-file . If .CR -lp is used, an .I l-file is not created; the delta summary is written on the standard output instead. See .SM FILES for the format of the .IR l-file . The user must have .I s-file read permission in order to use the .CR -l option. .TP .C -p Causes the text retrieved from the .SM SCCS file to be written on the standard output. No .I g-file is created. All output that normally goes to the standard output goes to file descriptor 2 (standard error) instead, unless the .CR -s option is used, in which case it disappears. .TP .CR -s Suppresses all output normally written on the standard output. However, fatal error messages (which always go to file descriptor 2) remain unaffected. .TP .CR -m Causes each text line retrieved from the .SM SCCS file to be preceded by the .SM SID of the delta that inserted the text line in the .SM SCCS file. The format is: .SM SID, followed by a horizontal tab, followed by the text line. .TP .CR -n Causes each generated text line to be preceded with the .CR %\&M% identification keyword value (see below). The format is: .CR %\&M% value, followed by a horizontal tab, followed by the text line. When both the .CR -m and .CR -n options are used, the format is: .CR %\&M% value, followed by a horizontal tab, followed by the .CR -m option-generated format. .TP .CR -g Suppresses the actual retrieval of text from the .SM SCCS file. It is primarily used to generate an .IR l-file , or to verify the existence of a particular .SM SID. .TP .CR -t Used to access the most recently created (``top'') delta in a given release (e.g., .CR -r1 ), or release and level (e.g., .CR -r1.2 ). .TP .CI -w \0string Substitute .I string for all occurrences of .C \&\@%\&M% when .CR get ting the file. .TP .CI -a seq-number The delta sequence number of the .SM SCCS file delta (version) to be retrieved (see .IR sccsfile (4)). This option is used by the .CR comb command (see .IR comb (1)); it is not a generally useful option, and should be avoided. If both the .CR -r and .CR -a options are specified, the .CR -a option is used. Care should be taken when using the .CR -a option in conjunction with the .CR -e option, because the .SM SID of the delta to be created may not be what one expects. The .CR -r option can be used with the .CR -a and .CR -e options to control the naming of the .SM SID of the delta to be created. .i0 .PP For each file processed, .CR get responds (on the standard output) with the .SM SID being accessed and with the number of lines retrieved from the .SM SCCS file. .PP If the .CR -e option is used, the .SM SID of the delta to be made appears after the .SM SID accessed and before the number of lines generated. If there is more than one named file, or if a directory or standard input is named, each file name is printed (preceded by a new-line) before it is processed. If the .CR -i option is used included deltas are listed following the notation ``Included''. If the .CR -x option is used, excluded deltas are listed following the notation ``Excluded''. .ne 10v .PP .in 0 .TS center, box ; CB s s s s c1 c1 c3 c3 c0 c c c c c l c l l l . TABLE 1. Determination of \s-1SCCS\s+1 Identification String .sp 1.5p _ \s-1SID\s+1* \f3\(mib\fP Option Other \s-1SID\s+1 \s-1SID\s+1 of Delta Specified Used\(dg Conditions Retrieved to be Created .sp 1.5p _ none\(dd no R defaults to mR mR.mL mR.(mL+1) none\(dd yes R defaults to mR mR.mL mR.mL.(mB+1).1 .sp 1.5p _ R no R > mR mR.mL R.1*** R no R = mR mR.mL mR.(mL+1) R yes R > mR mR.mL mR.mL.(mB+1).1 R yes R = mR mR.mL mR.mL.(mB+1).1 R \- R < mR and hR.mL** hR.mL.(mB+1).1 R does \f2not\fP exist R \- Trunk succ.# R.mL R.mL.(mB+1).1 in release > R and R exists .sp 1.5p R.L no No trunk succ. R.L R.(L+1) R.L yes No trunk succ. R.L R.L.(mB+1).1 R.L \- Trunk succ. R.L R.L.(mB+1).1 in release \(>= R .sp 1.5p _ R.L.B no No branch succ. R.L.B.mS R.L.B.(mS+1) R.L.B yes No branch succ. R.L.B.mS R.L.(mB+1).1 .sp 1.5p _ R.L.B.S no No branch succ. R.L.B.S R.L.B.(S+1) R.L.B.S yes No branch succ. R.L.B.S R.L.(mB+1).1 R.L.B.S \- Branch succ. R.L.B.S R.L.(mB+1).1 .sp 1.5p _ .TE .in \n(INu .PP .PD 0 .TP 10 * ``R'', ``L'', ``B'', and ``S'' are the ``release'', ``level'', ``branch'', and ``sequence'' components of the \s-1SID\s+1, respectively; ``m'' means ``maximum''. Thus, for example, ``R.mL'' means ``the maximum level number within release R''; ``R.L.(mB+1).1'' means ``the first sequence number on the .I new branch (i.e., maximum branch number plus one) of level L within release R''. Note that if the \s-1SID\s+1 specified is of the form ``R.L'', ``R.L.B'', or ``R.L.B.S'', each of the specified components .I must exist. .TP ** ``hR'' is the highest .I existing release that is lower than the specified, .IR nonexistent , release R. .TP *** This is used to force creation of the .I first delta in a .I new release. .TP # Successor. .TP \(dg The .CR -b option is effective only if the .CR b flag (see .IR admin (1)) is present in the file. An entry of .CR - means ``irrelevant''. .TP \(dd This case applies if the .CR d (default .SM SID\c ) flag is .I not present in the file. If the .CR d flag .I is present in the file, then the .SM SID obtained from the .CR d flag is interpreted as if it had been specified on the command line. Thus, one of the other cases in this table applies. .PD .SS "Identification Keywords" Identifying information is inserted into the text retrieved from the .SM SCCS file by replacing .I "identification keywords" with their value wherever they occur. The following keywords can be used in the text stored in an .SM SCCS file: .br .ne 5v .PP .PD 0 .TP 15 .B Keyword .B Value .TP .C %\&M% Module name: either the value of the .CR m flag in the file (see .IR admin (1)), or if absent, the name of the .SM SCCS file with the leading .CR s. removed. .TP .C %\&I% .SM SCCS identification .SM (SID) .RC ( %\&R%.%\&L%.%\&B%.%\&S% ) of the retrieved text. .TP .C %\&R% Release. .TP .C %\&L% Level. .TP .C %\&B% Branch. .TP .C %\&S% Sequence. .TP .C %\&D% Current date .SM (YY/MM/DD). .TP .C %\&H% Current date .SM (MM/DD/YY). .TP .C %\&T% Current time .SM (HH:MM:SS). .TP .C %\&E% Date newest applied delta was created .SM (YY/MM/DD). .TP .C %\&G% Date newest applied delta was created .SM (MM/DD/YY). .TP .C %\&U% Time newest applied delta was created .SM (HH:MM:SS). .TP .C %\&Y% Module type: value of the .CR t flag in the .SM SCCS file (see .IR admin (1)). .TP .C %\&F% .SM SCCS file name. .TP .C %\&P% Fully qualified .SM SCCS file name. .TP .C %\&Q% The value of the .CR q flag in the file (see .IR admin (1)). .TP .C %\&C% Current line number. This keyword is intended for identifying messages output by the program such as .CR "this should not have happened" type errors. It is .I not intended to be used on every line to provide sequence numbers. .TP .C %\&Z% The 4-character string .ifn \f3@\&(#)\fP .ifn \f4@\&(#)\fP recognizable by .CR what (see .IR what (1)). .TP .C %\&W% A shorthand notation for constructing .IR what (1) strings for .SM HP-UX system program files. .RS .IP .CI %\&W% = %\&Z%%\&M% horizontal-tab %\&I% .RE .TP .C %\&A% Another shorthand notation for constructing .IR what (1) strings for non-\c .SM HP-UX system program files. .RS .IP .C %\&A% = %\&Z%%\&Y% %\&M% %\&I%%\&Z% .RE .PD .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .CR LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR get behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS Use .IR sccshelp (1) for explanations. .SH WARNINGS If the effective user has write permission (either explicitly or implicitly) in the directory containing the .SM SCCS files, but the real user does not, then only one file can be named when the .CR -e option is used. .PP Unexpected results occur when using the .CR -i option to merge changes into sections of a file that have been (perhaps inadvertently) deleted and subsequently re-inserted into a file. .PP An .I l-file cannot be generated when .CR -g is used. In other words, .CR "-g -l" does not work. .SH FILES Several auxiliary files can be created by .CR get . These files are known generically as the .IR g-file , .IR l-file , .IR p-file , and .IR z-file . The letter before the hyphen is called the tag. An auxiliary file name is formed from the .SM SCCS file name: the last component of all .SM SCCS file names must be of the form .CI s. module-name\f1, the auxiliary files are named by replacing the leading .CR s with the tag. The .I g-file is an exception to this scheme: the .I g-file is named by removing the .CR s. prefix. For example, .CR s.xyz.c , the auxiliary file names would be .CR xyz.c , .CR l.xyz.c , .CR p.xyz.c , and .CR z.xyz.c , respectively. .PP The .IR g-file , which contains the generated text, is created in the current directory (unless the .CR -p option is used). A .I g-file is created in all cases, whether or not any lines of text were generated by the .CR get . It is owned by the real user. If the .CR -k option is used or implied its mode is 644; otherwise its mode is 444. Only the real user need have write permission in the current directory. .PP The .I l-file contains a table showing which deltas were applied in generating the retrieved text. The .I l-file is created in the current directory if the .CR -l option is used; its mode is 444 and it is owned by the real user. Only the real user need have write permission in the current directory. .PP Lines in the .I l-file have the following format: .RS .TP 4 1. A blank character if the delta was applied; .br .CR * otherwise. .TP 2. A blank character if the delta was applied or was not applied and ignored; .br .CR * if the delta was not applied and was not ignored. .TP 3. A code indicating a ``special'' reason why the delta was or was not applied: .RS .RS .TP 5 .CR I : Included. .PD 0 .TP .CR X : Excluded. .TP .CR C : Cut off (by a .CR -c option). .PD .RE .RE .TP 4. Blank. .TP 5 .SM SCCS identification (\s-1SID\s+1). .TP 6. Tab character. .TP 7. Creation date and time (in the form .SM YY/MM/DD HH:MM:SS\c ). .TP 8. Blank. .TP 9. Login name of person who created .IR delta . .PD .RE .IP The comments and .SM MR data follow on subsequent lines, indented one horizontal tab character. A blank line terminates each entry. .PP The .I p-file is used to pass information resulting from a .CR get with an .CR -e option along to .IR delta . Its contents are also used to prevent a subsequent execution of .CR get with an .CR -e option for the same .SM SID until .I delta is executed or the joint edit flag, .CR j , (see .IR admin (1)) is set in the .SM SCCS file. The .I p-file is created in the directory containing the .SM SCCS file and the effective user must have write permission in that directory. Its mode is 644 and it is owned by the effective user. The format of the .I p-file is: the gotten .SM SID, followed by a blank, followed by the .SM SID that the new delta will have when it is made, followed by a blank, followed by the login name of the real user, followed by a blank, followed by the date-time the .CR get was executed, followed by a blank and the .CR -i option argument if it was present, followed by a blank and the .CR -x option argument if it was present, followed by a new-line. There can be an arbitrary number of lines in the .I p-file at any time; no two lines can have the same new delta .SM SID. .PP The .I z-file serves as a .I lock-out mechanism against simultaneous updates. Its contents are the binary (2 bytes) process .SM ID of the command (i.e., .CR get\c ) that created it. The .I z-file is created in the directory containing the .SM SCCS file for the duration of .CR get . The same protection restrictions as those for the .I p-file apply for the .IR z-file . The .I z-file is created mode 444. .SH SEE ALSO admin(1), delta(1), sccshelp(1), prs(1), what(1), sccsfile(4). .SH STANDARDS CONFORMANCE .CR get ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4get\f1 \- get a version of an SCCS file@@@\f3get(1)\f1 .\" index@\f1files: get a version of an SCCS file@@@\f3get(1)\f1 .\" index@\f1SCCS: get a version of an SCCS file@@@\f3get(1)\f1 .\" index@\f1version of an SCCS file, get a@@@\f3get(1)\f1 .\" .\" toc@\f3get(1)\f1:\0\0\f4get\f1@@@get a version of an \s-1SCCS\s+1 file .\" .\" $Header: getaccess.1,v 72.3 93/01/14 11:34:44 ssa Exp $ .TA g .TH getaccess 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getaccess \- list access rights to file(s) .SH SYNOPSIS .C getaccess .RC [ -u .IR user\| ] .RC [ -g .IR user\| ] .IR group\| [\f3,\fP \|group\| ]\|...\|] .RC [ -n ] .IR file \0... .br .C getaccess -r .RC [ -n ] .IR file \0... .SH DESCRIPTION .C getaccess lists for the specified files the effective access rights of the caller (that is, for their effective user .SM ID, effective group .SM ID, and supplementary groups list). By default, the command prints a symbolic representation of the user's access rights to the named file: .C r or .C - for read/no read, .C w or .C - for write/no write, and .C x or .C - for execute/no execute (for directories, search/no search), followed by the file name. .SS Options .C getaccess recognizes the following options and command-line arguments: .RS .TP 15 .CI -u \0user List access for the given user instead of the caller. A .I user can be a known user name, a valid .SM ID number, or @, representing the file's owner .SM ID. If information about more than one file is requested, the value of @ can differ for each. .IP This option sets the user .SM ID only. The access check is made with the caller's effective group .SM ID and supplementary group .SM ID\c s unless .C -g is also specified. .TP .CR -g \0\f2group\fP\|[,\|\f2group\f1\|]\|...\|] List access for the given group(s) instead of the caller's effective group .SM ID and supplementary groups list. A .I group can be a known group name, a valid .SM ID number, or @, representing the file's group .SM ID. If information about more than one file is requested, the value of @ can differ for each. .TP .C -r List access using the caller's real user .SM ID, group .SM ID, and supplementary groups list, instead of effective .SM ID values. .TP .C -n List access rights numerically (octal digits .CR 0 ".." 7 instead of .CR rwx ) for each file requested. The bit values .CR R_OK , .CR W_OK , and .C X_OK are defined in the file .RC < unistd.h >. .RE .PP Checking access using access control lists is described in .IR acl (5). .PP In addition, the write bit is cleared for files on read-only file systems or shared-text programs being executed. The execute bit is not turned off for shared-text programs open for writing because it is not possible to ascertain whether a file open for writing is a shared-text program. .PP Processes with appropriate privileges have read and write access to all files. However, write access is denied for files on read-only file systems or shared-text programs being executed. Execute access is allowed if and only if the file is not a regular file or the execute bit is set in any of the file's .SM ACL entries. .PP To use .C getaccess successfully, the caller must have search access in every directory component of the path name of the .IR file . .C getaccess verifies search access first by using the caller's effective .SM IDs, regardless of the user and group .SM IDs specified. This is distinct from the case in which the caller can search the path but the user for whom access is being checked does not have access to the file. .PP Note: a file name argument of .C - has no special meaning (such as standard input) to .CR getaccess . .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the language in which messages are displayed. .PP If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C getaccess behaves as if all internationalization variables are set to "C". See .IR environ (5). .SH RETURN VALUE .C getaccess returns one of the following values: .RS .TP 5 .B 0 Successful completion. .TP .B 1 .C getaccess was invoked incorrectly or encountered an unknown user or group name. An appropriate message is printed to standard error. .TP .B 2 A file is nonexistent or unreachable (by the caller). .C getaccess prints an appropriate message to standard error, continues, then returns a value of 2 upon completion. .SH EXAMPLES The following command prints the caller's access rights to .I file1 using the file's group .SM ID instead of the caller's effective group .SM ID and groups list. .IP .C getaccess -g@ file1 .PP Here's how to check access by user .C ggd in groups .C red and .C 19 to all files in the current directory, with access rights expressed as octal values. .IP .C "getaccess -u ggd -g red,19 -n .* *" .PP Here's how to list access rights for all files under .CR mydir . .IP .C "find mydir -print | sort | xargs getaccess" .SH AUTHOR .C getaccess was developed by HP. .SH FILES .C /etc/passwd .br .C /etc/group .SH SEE ALSO chacl(1), lsacl(1), getaccess(2), glossary(9). .\" .\" index@\f4getaccess\f1 \- list access rights to file(s)@@@\f3getaccess(1)\f1 .\" index@list access rights to file(s)@@@\f3getaccess(1)\f1 .\" index@access rights to file(s), list@@@\f3getaccess(1)\f1 .\" index@rights, access, to file(s), list@@@\f3getaccess(1)\f1 .\" index@files: list access rights to file(s)@@@\f3getaccess(1)\f1 .\" .\" toc@\f3getaccess(1)\f1:\0\0\f4getaccess\f1@@@list access rights to file(s) .\" .\" fileset_database@getaccess.1 USER-CMDS-MAN .\" $Header: getconf.1,v 76.1 95/07/10 17:02:51 ssa Exp $ .TA g .TH getconf 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getconf \- get system configuration values .SH SYNOPSIS .C getconf .RI [ \|parameter_name\| ] .RI [ \|pathname\| ] .SH DESCRIPTION The .CR getconf command provides a program interface to the .IR confstr (3C), .IR pathconf (2), and .IR sysconf (2) libraries. .PP The .I parameter_name argument specifies the configuration value desired in .CR confstr() , .CR pathconf() , or .CR sysconf() . For .IR parameter_name , operand values listed in the table with .CR pathconf() as the underlying function, the .I pathname operand must also be supplied; otherwise, the .I pathname operand must not be supplied. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C getconf behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH RETURN VALUE The error codes returned by .CR getconf are: .RS .TP 5 .C 0 Success. A value corresponding to the operand was returned. .PD 0 .TP .C 1 One or more missing or extra operands. .TP .C 2 Operand was not recognized. .TP .C 3 .I pathname could not be accessed. .PD .RE .SH EXAMPLES Request the number of intervals per second: .IP .C getconf .C CLK_TCK .PP Request the maximum value of a file's link count: .IP .C getconf .C LINK_MAX .C /etc/passwd .PP Other supported inquiries include the following: .IP .TS tab(;); lf4p+1 lf4p+1 lf4p+1. ARG_MAX;_POSIX_CHILD_MAX;POSIX2_C_DEV BC_BASE_MAX;_POSIX_JOB_CONTROL;POSIX2_EXPR_NEST_MAX BC_DIM_MAX;_POSIX_NGROUPS_MAX;POSIX2_FORT_DEV BC_SCALE_MAX;_POSIX_OPEN_MAX;POSIX2_FORT_RUN BC_STRING_MAX;_POSIX_SAVED_IDS;POSIX2_LINE_MAX CHILD_MAX;_POSIX_SSIZE_MAX;POSIX2_LOCALEDEF CLK_TCK;_POSIX_STREAM_MAX;POSIX2_RE_DUP_MAX COLL_WEIGHTS_MAX;_POSIX_TZNAME_MAX;POSIX2_SW_DEV CS_PATH;_POSIX_VERSION;POSIX2_VERSION EXPR_NEST_MAX;POSIX2_BC_BASE_MAX;RE_DUP_MAX LINE_MAX;POSIX2_BC_DIM_MAX;SC_PASS_MAX NGROUPS_MAX;POSIX2_BC_SCALE_MAX;SC_XOPEN_VERSION OPEN_MAX;POSIX2_BC_STRING_MAX;STREAM_MAX PATH;POSIX2_COLL_WEIGHTS_MAX;TZNAME_MAX _POSIX_ARG_MAX;POSIX2_C_BIND CHARCLASS_NAME_MAX;CHAR_BIT;CHAR_MAX CHAR_MIN;NZERO;POSIX2_CHAR_TERM POSIX2_C_VERSION;POSIX_OPEN_MAX;POSIX_PATH_MAX POSIX_PIPE_BUF;POSIX_SAVED_IDS;POSIX_SSIZE_MAX POSIX_STREAM_MAX;POSIX_TZNAME_MAX;POSIX_VERSION SCHAR_MAX;SCHAR_MIN;INT_MAX INT_MIN;LONG_BIT;LONG_MAX LONG_MIN;MB_LEN_MAX;NL_NMAX NL_ARGMAX;NL_LANGMAX;NL_MSGMAX NL_SETMAX;NL_TEXTMAX;POSIX2_UPE POSIX_ARG_MAX;POSIX_CHILD_MAX;POSIX_JOB_CONTROL POSIX_LINK_MAX;POSIX_MAX_CANON;POSIX_MAX_INPUT POSIX_NAME_MAX;POSIX_NGROUPS_MAX;SHRT_MAX SHRT_MIN;SSIZE_MAX;TMP_MAX UCHAR_MAX;UINT_MAX;ULONG_MAX USHRT_MAX;WORD_BIT;XOPEN_VERSION XOPEN_XCU_VERSION;XOPEN_XPG2;XOPEN_XPG3 XOPEN_XPG4 .TE .PP Supported inquiries requiring the second parameter include: .IP .TS tab(;); lf4p+1 lf4p+1 lf4p+1. LINK_MAX;PIPE_BUF;_POSIX_NAME_MAX MAX_CANON;_POSIX_CHOWN_RESTRICTED;_POSIX_NO_TRUNC MAX_INPUT;_POSIX_LINK_MAX;_POSIX_PATH_MAX NAME_MAX;_POSIX_MAX_CANON;_POSIX_PIPE_BUF PATH_MAX;_POSIX_MAX_INPUT;_POSIX_VDISABLE POSIX_NO_TRUNC;POSIX_CHOWN_RESTRICTED;POSIX_VDISABLE .TE .RE .SH AUTHOR .CR getconf was developed by HP and POSIX. .SH SEE ALSO pathconf(2), sysconf(2), confstr(3C). .SH STANDARDS CONFORMANCE .CR getconf ": POSIX.2, XPG4" .\" .\" toc@\f3getconf(1)\f1:\0\0\f4getconf\f1@@@get POSIX configuration values\f1 .\" index@\f4getconf\f1 \- get POSIX configuration values@@@\f3getconf(1)\f1 .\" index@\f1POSIX configuration values, get@@@\f3getconf(1)\f1 .\" index@\f1configuration values, get POSIX@@@\f3getconf(1)\f1 .\" index@\f1values, get POSIX configuration@@@\f3getconf(1)\f1 .\" $Header: getopt.1,v 76.1 95/07/10 17:03:42 ssa Exp $ .TA g .TH getopt 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getopt \- parse command options .SH SYNOPSIS .C getopt .I optstring args .SH DESCRIPTION .C getopt is used to break up options in command lines for easy parsing by shell procedures and to check for legal options. .I optstring is a string of recognized option letters (see .IR getopt (3C)). If a letter is followed by a colon, the option is expected to have an argument which may or may not be separated from it by white space. .PP The positional parameters ($1 $2 ...\|) of the shell are reset so that each option is preceded by a .C - and is in its own positional parameter; each option argument is also parsed into its own positional parameter. .PP .C getopt recognizes two hyphens .RC ( -\|- ) to delimit the end of the options. If absent, .C getopt places .C -- at the end of the options. .PP The most common use of .C getopt is in the shell's .C set command (see the example below) where .C getopt converts the command line to a more easily parsed form. .C getopt writes the modified command line to the standard output. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. .PP If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C getopt behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH DIAGNOSTICS .C getopt prints an error message on the standard error when it encounters an option letter not included in .IR optstring . .SH EXAMPLES The following code fragment processes the arguments for a command that can take the options .C a or .CR b , and the option .C o which requires an argument: .nf .IP .C set -- `getopt abo: $*` .IP .C "if [ $? -ne 0 ]; then" .C " echo $USAGE" .C " exit 2" .C fi .IP .C "while [ $# -gt 0 ]; do" .C " case $1 in" .C " -a | -b)" .C " \s-1FLAG\s0=$1" .C " shift" .C " ;;" .C " -o)" .C " \s-1OARG\s0=$2" .C " shift 2" .C " ;;" .C " --)" .C " shift" .C " break" .C " ;;" .C " esac" .C done .fi .ss 12 .PP This code accepts any of the following as equivalent: .nf .IP .C "cmd -aoarg file file" .C "cmd -a -o arg file file" .C "cmd -oarg -a file file" .C "cmd -a -oarg -- file file" .fi .RE .SH WARNINGS .C getopt option arguments must not be null strings nor contain embedded blanks. .SH SEE ALSO sh(1), getopt(3C). .\" .\" index@\f4getopt\f1 \- parse command options@@@\f3getopt(1)\f1 .\" index@\f1parse command options@@@\f3getopt(1)\f1 .\" index@\f1command options, parse@@@\f3getopt(1)\f1 .\" index@\f1options, parse command@@@\f3getopt(1)\f1 .\" .\" toc@\f3getopt(1)\f1:\0\0\f4getopt\f1@@@parse command options .\" .\" $Header: getopts.1,v 76.1 95/08/03 17:51:25 ssa Exp $ .TA g .TH getopts 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getopts \- parse utility (command) options .SH SYNOPSIS .C getopts .I optstring name .RI [ \|arg\| \0...\|] .SH DESCRIPTION .C getopts is used to retrieve options and option-arguments from a list of parameters. .PP Each time it is invoked, .CR getopts places the value of the next option in the shell variable specified by the .CR name operand and the index of the next argument to be processed in the shell variable .CR OPTIND . Whenever the shell is invoked, .CR OPTIND is initialized to 1. .PP When the option requires an option-argument, .CR getopts places it in the shell variable .CR OPTARG . If no option was found, or if the option that was found does not have an option-argument, .CR OPTARG is unset. .PP If an option character not contained in the .I optstring operand is found where an option character is expected, the shell variable specified by .I name is set to the question-mark .RC ( ? ) character. In this case, if the first character in .I optstring is a colon .RC ( : ), the shell variable .CR OPTARG is set to the option character found, but no output is written to standard error; otherwise, the shell variable .CR OPTARG is unset and a diagnostic message is written to standard error. This condition is considered to be an error detected in the way arguments were presented to the invoking application, but is not an error in .CR getopts processing. .PP If an option-argument is missing: .RS .TP 3 \(bu If the first character of .I optstring is a colon, the shell variable specified by .I name is set to the colon character and the shell variable .CR OPTARG is set to the option character found. .TP \(bu Otherwise, the shell variable specified by .I name is set to the question-mark character, the shell variable .CR OPTARG is unset, and a diagnostic message is written to the standard error. This condition is considered to be an error detected in the way arguments are presented to the invoking application, but is not an error in .CR getopts processing; a diagnostic message is written as stated, but the exit status is zero. .RE .PP When the end of options is encountered, .CR getopts exits with a return value greater than zero. The shell variable .CR OPTIND is set to the index of the first nonoption-argument, where the first .CR -\|- argument is considered to be an option argument if there are no other non-option arguments appearing before it, or the value .CR $* + 1 if there are no nonoption-arguments; the .I name variable is set to the question-mark character. Any of the following identifies the end of options: the special option .CR -\|- , finding an argument that does not begin with a .CR - , or encountering an error. .PP The shell variables .CR OPTIND and .CR OPTARG are local to the caller of .CR getopts and are not exported by default. .PP The shell variable specified by the .I name operand, .CR OPTIND , and .CR OPTARG affect the current shell execution environment. .SS Operands The following operands are supported: .RS .TP 15 .I optstring A string containing the option characters recognized by the utility invoking .CR getopts . .TP .I name The name of a shell variable that is set by .CR getopts to the option character that was found. .RE .PP .C getopts by default parses positional parameters passed to the invoking shell procedures. If .I args are given, they are parsed instead of the positional parameters. .SH EXTERNAL INFLUENCES .SS Environment Variable The following environment variable affects the execution of the .CR getopts utility: .RS .TP 15 .C OPTIND Used by .CR getopts as the index of the next argument to be processed. .SH EXAMPLES Since .CR getopts affects the current shell execution environment, it is generally provided as a shell regular built-in. If it is called in a subshell or separate utility execution environment such as one of the following: .IP .nf .C (getopts abc value "$@") .C "nohup getopts ..." .C "find -exec getopts ...\e;" .fi .PP it does not affect the shell variables in the caller's environment. .PP Note that shell functions share .CR OPTIND with the calling shell even though the positional parameters are changed. Functions that use .CR getopts to parse their arguments should save the value of .CR OPTIND on entry and restore it before returning. However, there will be cases when a function must change .CR OPTIND for the calling shell. .PP The following example script parses and displays its arguments: .RS .PP .nf .ift .ft 4 .ifn .ft 3 .ps +1 aflag= bflag= .ift .sp .5v .ifn .sp while getopts ab: name do case $name in -a) aflag=1;; -b) bflag=1 bval="$OPTARG";; -?) printf "Usage: %s: [-a] [-b value] args\en" $0 exit 2;; esac done if [ ! -z "$aflag" ] ; then printf "Option -a specified\en" fi if [ ! -z "$bflag" ] ; then printf "Option -b "%s" specified\en" "$bval" fi shift $(($OPTIND -1)) printf "Remaining arguments are: %s\en" "$*" .ft .ps .fi .RE .SH SEE ALSO getopt(1), ksh(1), sh-posix(1), sh(1), getopt(3C). .SH STANDARDS CONFORMANCE .CR getopts ": XPG4, POSIX.2" .\" .\" toc@\f3getopts(1)\f1:\0\0\f4getopts\f1@@@parse utility (command) options .\" .\" index@\f4getopts\f1 \- parse utility (command) options@@@\f3getopts(1)\f1 .\" index@parse utility (command) options@@@\f3getopts(1)\f1 .\" index@utility options, parse@@@\f3getopts(1)\f1 .\" index@command options, parse@@@\f3getopts(1)\f1 .\" index@options, parse utility (command)@@@\f3getopts(1)\f1 .\" .\" fileset_database@getopts.1 USER-CMDS-MAN .\" $Header: getprivgrp.1,v 72.5 94/09/08 13:46:49 ssa Exp $ .TA g .TH getprivgrp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprivgrp \- get special attributes for group .SH SYNOPSIS .C getprivgrp .RC [ -g \(or\|\f2group_name\|\fP] .SH DESCRIPTION .C getprivgrp lists the access privileges of privileged groups set by .C setprivgrp (see .IR setprivgrp (1M)). If .I group_name is supplied, access privileges are listed for that group only. If the caller is not a member of .IR group_name , no information is displayed. If .C -g is used, .C getprivgrp lists access privileges that have been granted to all groups. Otherwise, access privileges are listed for all privileged groups to which the caller belongs. .PP The super-user is a member of all groups. Access privileges include .CR RTPRIO , .CR RTSCHED , .CR MLOCK , .CR CHOWN , .CR LOCKRDONLY , .CR SETRUGID , and .CR SERIALIZE . .SH AUTHOR .C getprivgrp was developed by HP. .SH SEE ALSO setprivgrp(1M), getprivgrp(2), privgrp(4). .\" .\" index@\f4getprivgrp\f1 \- get special attributes for group@@@\f3getprivgrp(1)\f1 .\" index@privgrp, get special attributes for group@@@\f3getprivgrp(1)\f1 .\" index@special attributes for group, get@@@\f3getprivgrp(1)\f1 .\" index@access privileges for group, list@@@\f3getprivgrp(1)\f1 .\" index@privileges for group, list access@@@\f3getprivgrp(1)\f1 .\" index@list access privileges for group@@@\f3getprivgrp(1)\f1 .\" index@attributes for group, get special@@@\f3getprivgrp(1)\f1 .\" index@group, get special attributes for@@@\f3getprivgrp(1)\f1 .\" .\" toc@\f3getprivgrp(1)\f1:\0\0\f4getprivgrp\f1@@@get special attributes for group .\" $Header: gprof.1,v 74.1 95/03/16 16:27:23 ssa Exp $ .TA g .TH gprof 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gprof \- display call graph profile data .SH SYNOPSIS .C gprof .RI [ options ] .RI [ a.out .RI [ gmon.out\| ...\|]\|] .SH DESCRIPTION The .CR gprof command produces an execution profile of C, Pascal, and FORTRAN programs. The effect of called routines is incorporated into the profile of each caller. Profile data is taken from the call graph profile file .RC ( gmon.out default) that is created by programs compiled with the .CR -G option of .CR cc , .CR pc , and .CR f77 (see .IR cc (1), .IR pc (1), and .IR f77 (1)). That option also links in versions of the library routines that are compiled for profiling. The symbol table in the named object file .RC ( a.out default) is read and correlated with the call graph profile file. If more than one profile file is specified, .CR gprof output shows the sum of the profile information in the given profile files. .PP First, a flat profile is given, similar to that provided by .CR prof (see .IR prof (1)). This listing gives the total execution times and call counts for each function in the program, sorted by decreasing time. .PP Next, these times are propagated along the edges of the call graph. .CR gprof discovers all cycles in the call graph. All calls made into the cycle share the time of that cycle. A second listing shows the functions sorted according to the time they represent including the time of their call graph descendants. Below each function entry is shown its (direct) call graph children, and how their times are propagated to this function. A similar display above the function shows how the time of this function and the time of its descendants are propagated to its (direct) call graph parents. .PP Cycles are also shown, with an entry for the cycle as a whole and a listing of the members of the cycle, each with their contributions to the time and call counts of the cycle. .SS Options The .CR gprof command recognizes the following options: .RS .TP 15 .C -a Suppress printing statically declared functions. If this option is given, all relevant information about the static function (such as time samples, calls to other functions, and calls from other functions) belongs to the function loaded just before the static function in the .CR a.out file. .TP .C -b Suppress printing a description of each field in the profile. .TP .CI -e \0name Suppress printing the graph profile entry for routine .I name and all its descendants (unless they have other ancestors that are not suppressed). More than one .CR -e option can be given. Only one .I name can be given with each .CR -e option. .TP .CI -E \0name Suppress printing the graph profile entry for routine .I name (and its descendants) as .CR -e above, and also exclude the time spent in .I name (and its descendants) from the total and percentage time computations. (For example, .C -E mcount .C -E mcleanup is the default.) .TP .CI -f \0name Print only the graph profile entry of the specified routine .I name and its descendants. More than one .CR -f option can be given. Only one .I name can be given with each .CR -f option. .TP .CI -F \0name Print only the graph profile entry of the routine .I name and its descendants (as .CR -f above) and also uses only the times of the printed routines in total time and percentage computations. More than one .CR -F option can be given. Only one .I name can be given with each .CR -F option. The .CR -F option overrides the .CR -E option. .TP .C -s Produce a profile file .CR gmon.sum that represents the sum of the profile information in all specified profile files. This summary profile file can be given to subsequent executions of .CR gprof (probably also with a .CR -s option) to accumulate profile data across several runs of an .CR a.out file. .TP .C -z Display routines that have zero usage (as indicated by call counts and accumulated time). .RE .PP The name of the file created by a profiled program is controlled by the environment variable .CR GPROFDIR . If .CR GPROFDIR is not set, .CR gmon.out is produced in the current directory when the program terminates. If .CR GPROFDIR=string , .CI string/ pid.progname is produced, where .I progname consists of .IR argv[0] with any path prefix removed, and .I pid is the program's process ID. If .CR GPROFDIR is set to a null string, no profiling output is produced. .SH WARNINGS Beware of quantization errors. The granularity of the sampling is shown, but remains statistical at best. It is assumed that the time for each execution of a function can be expressed by the total time for the function, divided by the number of times the function is called. Thus the time propagated along the call graph arcs to parents of that function is directly proportional to the number of times that arc is traversed. .PP Parents that are not profiled have the time of their profiled children propagated to them, but they appear to be spontaneously invoked in the call graph listing, and do not have their time propagated further. Similarly, signal catchers, even though profiled, appear to be spontaneous (although for more obscure reasons). Any profiled children of signal catchers should have their times propagated properly unless the signal catcher was invoked during the execution of the profiling routine, in which case all is lost. .PP The profiled program must call .CR exit() (see .IR exit (2)) or return normally, for the profiling information to be saved in the .CR gmon.out file. .SH DEPENDENCIES .C gprof cannot be used with dynamically linked executables. .SH AUTHOR .C gprof was developed by the University of California, Berkeley. .SH FILES .TP 35 .C a.out* Default object file. .PD 0 .TP .C gmon.out* Default dynamic call graph and profile. .TP .C gmon.sum* Summarized dynamic call graph and profile. .TP .C /usr/lib/gprof.callg* Call graph description. .TP .C /usr/lib/gprof.flat* Flat profile description. .PD .SH SEE ALSO cc(1), f77(1), pc(1), prof(1), exit(2), profil(2), crt0(3), monitor(3C). .PP .IR "gprof: A Call Graph Execution Profiler" ; Graham, S.L., Kessler, P.B., McKusick, M.K.; .PP .IR "Proceedings of the SIGPLAN '82 Symposium on Compiler Construction" ; SIGPLAN Notices; Vol. 17, No. 6, pp. 120-126, June 1982. .\" .\" index@\f4gprof\f1 \- display call graph execution profile data@@@\f3gprof(1)\f1 .\" index@\f1display call graph execution profile data@@@\f3gprof(1)\f1 .\" index@\f1call graph execution profile data, display@@@\f3gprof(1)\f1 .\" index@\f1subroutine call graph execution profile data, display@@@\f3gprof(1)\f1 .\" index@\f1graph and display execution profile data@@@\f3gprof(1)\f1 .\" index@\f1execution profile data, display call graph@@@\f3gprof(1)\f1 .\" index@\f1profile data, display call graph execution@@@\f3gprof(1)\f1 .\" .\" toc@\f3gprof(1)\f1:\0\0\f4gprof\f1@@@display call graph profile data\f1 .\" $Header: grep.1,v 76.1 95/08/23 17:54:30 ssa Exp $ .TA g .TH grep 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME grep, egrep, fgrep \- search a file for a pattern .SH SYNOPSIS .SS Plain call with pattern .C grep .RC [ -E \|\(or\| -F ] .RC [ -c \(or -l \c .RC \(or -q ] .RC [ -insvx ] .I pattern .RI [ \|file \0...\|] .SS Call with (multiple) \(mie pattern .C grep .RC [ -E \|\(or\| -F ] .RC [ -c \(or -l \c .RC \(or -q ] .RC [ -binsvx ] .CI -e \0pattern\|\f1... .RC [ -e .IR pattern \|]\0... .ifn .br .ifn \0\0\0\0 .RI [ \|file \0...\|] .SS Call with \(mif file .C grep .RC [ -E \|\(or\| -F ] .RC [ -c \(or -l \c .RC \(or -q ] .RC [ -insvx ] .RC [ -f .IR pattern_\|file\| ] .RI [ \|file \0...\|] .SS Obsolescent: .C egrep .RC [ -cefilnsv ] .RI [ \|expression\| ] .RI [ \|file \0...\|] .PP .C fgrep .RC [ -cefilnsvx ] .RI [ \|strings\| ] .RI [ \|file \0...\|] .SH DESCRIPTION The .CR grep command searches the input text .I files (standard input default) for lines matching a pattern. Normally, each line found is copied to the standard output. .CR grep supports the Basic Regular Expression syntax (see .IR regexp (5)). The .CR -E option .RC ( egrep ) supports Extended Regular Expression (ERE) syntax (see .IR regexp (5)). The .CR -F option .RC ( fgrep ) searches for fixed .IR strings using the fast Boyer-Moore string searching algorithm. The .CR -E and .CR -F options treat newlines embedded in the .I pattern as alternation characters. A null expression or string matches every line. .PP The forms .CR egrep and .CR fgrep are maintained for backward compatibility. The use of the .CR -E and .CR -F options is recommended for portability. .SS Options .RS .TP 20 .C -E Extended regular expressions. Each pattern specified is a sequence of one or more EREs. The EREs can be separated by newline characters or given in separate .CR -e .I expression options. A pattern matches an input line if any ERE in the sequence matches the contents of the input line without its trailing newline character. The same functionality is obtained by using .CR egrep . .TP .C -F Fixed strings. Each pattern specified is a sequence of one or more strings. Strings can be separated by newline characters or given in separate .CR -e .I expression options. A pattern matches an input line if the line contains any of the strings in the sequence. The same functionality is obtained by using .CR fgrep . .TP .C -b Each line is preceded by the block number on which it was found. This is useful in locating disk block numbers by context. Block numbers are calculated by dividing by 512 the number of bytes that have been read from the file and rounding down the result. .TP .C -c Only a count of matching lines is printed. .TP .CI -e " expression" Same as a simple .I expression argument, but useful when the .I expression begins with a hyphen .RC ( \- ). Multiple .CR -e options can be used to specify multiple patterns; an input line is selected if it matches any of the specified patterns. .TP .CI -f " pattern_\|file" The regular .I expression .RC ( grep and .CR "grep -E" ) or .I strings list .RC ( "grep -F" ) is taken from the .IR pattern_\|file . .TP .C -i Ignore uppercase/lowercase distinctions during comparisons. .TP .C -l Only the names of files with matching lines are listed (once), separated by newlines. If standard input is searched, a path name of .CR \- is listed. .TP .C -n Each line is preceded by its relative line number in the file starting at 1. The line number is reset for each file searched. This option is ignored if .CR -c , .CR -b , .CR -l , or .CR -q is specified. .TP .C -q (Quiet) Do not write anything to the standard output, regardless of matching lines. Exit with zero status upon finding the first matching line. Overrides any options that would produce output. .TP .C -s Error messages produced for nonexistent or unreadable files are suppressed. .TP .C -v All lines but those matching are printed. .TP .C -x (eXact) Matches are recognized only when the entire input line matches the fixed string or regular expression. .RE .PP In all cases in which output is generated, the file name is output if there is more than one input file. Care should be taken when using the characters .CR $ , .CR * , .CR [ , .CR ^ , .CR | , .CR ( , .CR ) , and .CR \e in .IR expression , because they are also meaningful to the shell. It is safest to enclose the entire .I expression argument in single quotes .RC ( ' ... ' ). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not specified or is set to the empty string, a default of .C C (see .IR lang (5)) is used. .PP .CR LC_ALL determines the locale to use to override any values for locale categories specified by the settings of .C LANG or any environment variables beginning with .CR LC_ . .PP .C LC_COLLATE determines the collating sequence used in evaluating regular expressions. .PP .C LC_CTYPE determines the interpretation of text as single byte and/or multi-byte characters, the classification of characters as letters, the case information for the .C -i option, and the characters matched by character class expressions in regular expressions. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If any internationalization variable contains an invalid setting, the commands behave as if all internationalization variables are set to .CR C . See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH RETURN VALUE Upon completion, .CR grep returns one of the following values: .RS .TP 5 .C 0 One or more matches found. .PD 0 .TP .C 1 No match found. .TP .C 2 Syntax error or inaccessible file (even if matches were found). .PD .RE .SH EXAMPLES In the Bourne shell .RI ( sh (1)) the following example searches two files, finding all lines containing occurrences of any of four strings: .nf .IP .C "grep -F 'if" .C then .C else .CI fi' " file1 file2" .fi .PP Note that the single quotes are necessary to tell .C grep -F when the strings have ended and the file names have begun. .PP For the C shell (see .IR csh (1)) the following command can be used: .IP .C grep -F 'if\e .C then\e .C else\e .CI fi' " file1 file2" .PP To search a file named .CR address containing the following entries: .nf .IP .C "Ken 112 Warring St. Apt. A" .C "Judy 387 Bowditch Apt. 12" .C "Ann 429 Sixth St." .fi .PP the command: .IP .C grep Judy address .PP prints: .IP .C "Judy 387 Bowditch Apt. 12" .ift .br .ift .ne 6 .PP To search a file for lines that contain either a .CR Dec or .CR Nov , use either of the following commands: .IP .CI "grep -E '[Dd]ec|[Nn]ov' " file .IP .CI "egrep -i 'dec|nov' " file .PP Search all files in the current directory for the string .CR xyz : .IP .C grep xyz * .PP Search all files in the current directory subtree for the string .CR xyz , and ensure that no error occurs due to file name expansion exceeding system argument list limits: .IP .C "find . -type f -print |xargs grep xyz" .PP The previous example does not print the name of files where string .CR xyz appears. To force .CR grep to print file names, add a second argument to the .CR grep command portion of the command line: .IP .C "find . -type f -print |xargs grep xyz /dev/null" .PP In this form, the first file name is that produced by .CR find , and the second file name is the null file. .SH WARNINGS .PP (XPG4 only.) If the .CR -q option is specified, the exit status will be zero if an input line is selected, even if an error was detected. Otherwise, default actions will be performed. .SH SEE ALSO sed(1), sh(1), regcomp(3C), environ(5), lang(5), regexp(5). .SH STANDARDS CONFORMANCE .CR grep ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR egrep ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR fgrep ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4grep\f1 \- search a file for a pattern (compact algorithm)@@@\f3grep(1)\f1 .\" index@\f4egrep\f1 \- search a file for a pattern@@@\f3grep(1)\f1 .\" index@\f4fgrep\f1 \- search a file for a specific string (fast algorithm)@@@\f3grep(1)\f1 .\" index@\f1search a file for a string or expression@@@\f3grep(1)\f1 .\" index@\f1files, search a file for a string or expression@@@\f3grep(1)\f1 .\" index@\f1string or expression, search a file for a@@@\f3grep(1)\f1 .\" index@\f1expression or string, search a file for a@@@\f3grep(1)\f1 .\" .\" toc@\f3grep(1)\f1:\0\0\f4grep\f1, \f4egrep\f1, \f4fgrep\f1@@@search a file for a pattern\f1 .\" toc@\f4egrep\f1:\0\0search a file for a pattern@@@\f1see \f3grep(1)\f1 .\" toc@\f4fgrep\f1:\0\0search a file for a string (fast)@@@\f1see \f3grep(1)\f1 .\" .\" links@grep.1 egrep.1 .\" links@grep.1 fgrep.1 .\" $Header: pwget.1,v 72.4 94/09/08 15:04:02 ssa Exp $ .TA p .TH pwget 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pwget, grget \- get password and group information .SH SYNOPSIS .C pwget .RC [ -n .I name \(or .C -u .IR uid\| ] .PP .C grget .RC [ -n .I name \(or .C -g .IR gid\| ] .SH DESCRIPTION .C pwget and .C grget locate and display information from .C /etc/passwd and .CR /etc/group . .PP The standard output of .C pwget contains lines of colon-separated password information whose format is the same as that used in the .C /etc/passwd file (see .IR passwd (4)). .PP The standard output of .C grget contains lines of colon-separated group information whose format is the same as that used in the .C /etc/group file (see .IR group (4)). .PP With no options, .C pwget and .C grget get all entries with .C getpwent() or .C getgrent() respectively, (see .IR getpwent (3C) and .IR getgrent (3C)), and output a line for each entry found. .SS Options When an option is given, only a single entry is printed. .PP The options for .I pwget are: .RS .TP 15 .CI -n \0name Output the first entry that matches .I name using .C getpwnam() (see .IR getpwent (3C)). .TP .CI -u \0uid Output the first entry that matches .I uid using .C getpwuid() (see .IR getpwent (3C)). .RE .PP The options for .C grget are: .RS .TP 15 .CI -n \0name Output the first entry that matches .I name using .C getgrnam() (see .IR getgrent (3C)). .TP .CI -g \0gid Output the first entry that matches .I gid using .C getgrgid() (see .IR getgrent (3C)). .RE .SH NETWORKING FEATURES .SS \s-1NFS\s0 If Network Information System .SM (NIS) is in use, these commands provide password and group information based on the .SM NIS version of the password and group databases in addition to the local password and group files. .SH RETURN VALUE These commands return .C 0 upon success, .C 1 when a specific search fails, and .C 2 upon error. .SH DEPENDENCIES .SS \s-1NFS\s+1: .SM WARNING: If the Network Information System network database is in use and the .SM NIS client daemon .RC ( ypbind ) is not bound to a .SM NIS server daemon (see .IR ypserv (1M)), these utilities will wait until such a binding is established. These commands can be terminated in this condition by sending a .C SIGINT signal to the process (see .IR kill (1)). .PP See .IR ypmatch (1), and .IR ypserv (1M). .SH AUTHOR .C pwget and .C grget were developed by HP. .SH FILES .TP 20 .C /etc/group local group data file .TP .C /etc/passwd local password data file .SH SEE ALSO getgrent(3C), getpwent(3C), group(4), passwd(4). .\" .\" index@\f4pwget\f1 \- get password information@@@\f3pwget(1)\f1 .\" index@\f4grget\f1 \- get group information@@@\f3pwget(1)\f1 .\" index@password information, get (\f4pwget\f1)@@@\f3pwget(1)\f1 .\" index@group information, get (\f4grget\f1)@@@\f3pwget(1)\f1 .\" .\" toc@\f3pwget(1)\f1:\0\0\f4pwget\f1, \f4grget\f1@@@get password and group information .\" toc@\f4grget\f1: get password and group information@@@see \f3pwget(1)\f1 .\" .\" links@pwget.1 grget.1 .\" .\" fileset_database@pwget.1 USER-CMDS-MAN .\" $Header: groups.1,v 72.3 93/01/14 11:34:53 ssa Exp $ .TA g .TH groups 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME groups \- show group memberships .SH SYNOPSIS .C groups .RC [ -p ] .RC [ -g ] .RC [ -l ] .RI [ \|user\| ] .SH DESCRIPTION .C groups shows the groups to which the caller or the optionally specified .I user belong. If invoked with no arguments, .C groups prints the current access list returned by .C getgroups() (see .IR getgroups (2)). .PP Each user belongs to a group specified in the password file .C /etc/passwd and possibly to other groups as specified in the files .C /etc/group and .CR /etc/logingroup . A user is granted the permissions of those groups specified in .C /etc/passwd and .C /etc/logingroup at login time. The permissions of the groups specified in .C /etc/group are normally available only with the use of .C newgrp (see .IR newgrp (1)). If a user name is specified with no options, .C groups prints the union of all these groups. .PP The .CR -p , .CR -g , and .C -l options limit the printed list to those groups specified in .CR /etc/passwd , .CR /etc/group , and .CR /etc/logingroup , respectively. If a user name is not specified with any of these options, .C cuserid() is called to determine the default user name (see .IR cuserid (3S)). .PP The printed list of groups is sorted in ascending collation order (see Environment Variables below). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the order in which the output is sorted. .PP If .C LC_COLLATE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default. If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C groups behaves as if all internationalization variables are set to ``C'' (see .IR environ (5)). .SH EXAMPLES Check file .C /etc/logingroup and display all groups to which user .C tim belongs: .IP .C groups -l tim .SH AUTHOR .C groups was developed by the University of California, Berkeley. .SH FILES .C /etc/group .br .C /etc/logingroup .br .C /etc/passwd .SH SEE ALSO id(1), newgrp(1), getgroups(2), initgroups(3C), cuserid(3S), group(4). .\" .\" index@\f4groups\f1 \- show group memberships@@@\f3groups(1)\f1 .\" index@show group memberships@@@\f3groups(1)\f1 .\" index@group memberships, show@@@\f3groups(1)\f1 .\" index@memberships, show group@@@\f3groups(1)\f1 .\" .\" toc@\f3groups(1)\f1:\0\0\f4groups\f1@@@show group memberships .\" .\" fileset_database@groups.1 USER-CMDS-MAN .\" $Header: spell.1,v 72.6 94/11/14 15:21:23 ssa Exp $ .TA s .TH spell 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME spell, hashmake, spellin, hashcheck \- find spelling errors .SH SYNOPSIS .C spell .RC [ -v ] .RC [ -b ] .RC [ -x ] .RC [ -l ] .RC [ -i ] .RC [ +\c .IR local_file \|] .RI [ \|files\| ] .PP .C /usr/lbin/spell/hashmake .PP .C /usr/lbin/spell/spellin .I n .PP .C /usr/lbin/spell/hashcheck .I spelling_list .SH DESCRIPTION The .CR spell command collects words from the named .I files and looks them up in a spelling list. Words that neither occur among nor are derivable (by applying certain inflections, prefixes, and/or suffixes) from words in the spelling list are printed on the standard output. If no .I files are named, words are collected from the standard input. .PP The .CR spell command ignores most .CR troff , .CR tbl , and .I eqn constructions. .SS Options The .CR spell command recognizes the following options: .RS .TP 15 .C -v All words not literally in the spelling list are printed, and plausible derivations from the words in the spelling list are indicated. .TP .C -b British spelling is checked. Besides preferring .CR centre , .CR colour , .CR programme , .CR speciality , .CR travelled , etc., this option insists upon .CR -ise in certain words, such as in .CR standardise . .TP .C -x Every plausible stem is printed with .CR = for each word. .RE .PP By default, .CR spell follows chains of included files much like .CR deroff (see .IR deroff (1)) which recognizes the .CR troff / nroff intrinsics .CR .so and .CR .nx , .I unless the names of such included files begin with .CR /usr/share/lib . If the .CR -l option is used, .CR spell follows the chains of .I all included files. With the .CR -i option, .CR spell ignores all chains of included files. .PP If the .CI + local_file option is used, words found in .I local_file are removed from .CR spell 's output. .I local_file is the name of a user-provided file containing a sorted list of words, one per line. With this option, the user can specify a set of words that are correct spellings (in addition to .IR spell 's own spelling list) for each job. .PP The spelling list is based on many sources, and while more haphazard than an ordinary dictionary, is also more effective with respect to proper names and popular technical words. Coverage of the specialized vocabularies of biology, medicine, and chemistry is light. .PP Pertinent auxiliary files can be specified by name arguments, indicated below with their default settings (see FILES and VARIABLES). Copies of all output are accumulated in the history file. The stop list filters out misspellings (such as .CR thier=thy-y+ier ) that would otherwise pass. .PP Three routines help maintain and check the hash lists used by .CR spell : .RS .TP 15 .C hashmake Reads a list of words from the standard input and writes the corresponding nine-digit hash code on the standard output. .TP .CI spellin \ n Reads .I n hash codes from the standard input and writes a compressed spelling list on the standard output. Information about the hash coding is printed on standard error. .TP .C hashcheck Reads a compressed .I spelling_list and recreates the nine-digit hash codes for all the words in it; it writes these codes on the standard output. .RE .SH EXAMPLES To check spelling of a single .IR word : .IP .CI echo " word " "| spell" .PP If .I word is spelled correctly, a prompt is returned. If it is spelled incorrectly, .I word is printed before the prompt is returned. To check spelling of multiple words, they can also be typed as a group on the same command line: .IP .CI echo " worda wordb wordc ... " "| spell" .PP To create a personal spelling list that incorporates the words already present in the default American spelling list file .CR /usr/share/dict/hlista : .nf .IP .C cat /usr/share/dict/hlista | /usr/lbin/spell/hashcheck >tmp1 .C /usr/lbin/spell/hashmake >tmp1 .C sort -u -o tmp1 tmp1 .C /usr/lbin/spell/spellin `wc -l hlista .fi .PP To modify the default British spelling list file .CR /usr/share/dict/hlistb , replace all occurrences of .CR hlista with .CR hlistb in the above example. .PP To add words to the default spelling list, change login to .CR root , change the current working directory to .CR /usr/share/dict and execute the commands listed in the above example. .SH WARNINGS The spelling list's coverage is uneven. When undertaking the use of .CR spell as a new tool, it may be advisable to monitor the output for several months to gather local additions. Typically, these are kept in a separate local file that is added to the hashed .I spelling_list via .CR spellin , as shown above. .PP The British spelling feature was developed by an American. .PP Start-up versions of files .CR hlista , .CR hlistb , and .CR hstop are available in directory .CR /usr/newconfig/usr/share/dict . If these files or a suitable equivalent are not present in directory .CR /usr/share/dict , .CR spell complains: .IP .C "spell: cannot initialize hash table" .br .C "spell: cannot initialize hash table" .SH FILES .TP 38 .CR /usr/share/dict/hlist [ ab ] Hashed spelling lists, American and British. .PD 0 .TP .C /usr/share/dict/hstop Hashed stop list. .TP .C /var/adm/spellhist History file. .TP .C /usr/lbin/spell/spellprog Executable program file. .PD .SH VARIABLES .TP 15 .C D_SPELL Your hashed spelling list (default is .CR D_SPELL=/usr/share/dict/hlist [ ab ]) .PD 0 .TP .C H_SPELL Spelling history (default is .CR H_SPELL=/var/adm/spellhist ). .TP .C S_SPELL Your hashed stop list (default is .CR S_SPELL=/usr/share/dict/hstop ). .TP .C TMPDIR Directory for temporary files; overrides the default .CR /tmp . .PD .SH SEE ALSO deroff(1), sed(1), sort(1), tbl(1), tee(1). .SH STANDARDS CONFORMANCE .CR spell ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4spell\f1 \- find spelling errors@@@\f3spell(1)\f1 .\" index@\f1find spelling errors@@@\f3spell(1)\f1 .\" index@\f1spelling errors, find@@@\f3spell(1)\f1 .\" index@\f1errors, find spelling@@@\f3spell(1)\f1 .\" index@\f4hashcheck\f1 \- convert spelling reference list words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f1convert spelling reference list words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f4hashmake\f1 \- convert text words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f1convert text words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f4spellin\f1 \- convert 9-digit hash codes to compressed spelling reference list@@@\f3spell(1)\f1 .\" index@convert 9-digit hash codes to compressed spelling reference list@@@\f3spell(1)\f1 .\" index@\f1hash codes, convert 9-digit to or from text for spell checking@@@\f3spell(1)\f1 .\" .\" toc@\f3spell(1)\f1:\0\0\f4spell\f1, \f4hashmake\f1, \f4spellin\f1, \f4hashcheck\f1@@@find spelling errors\f1 .\" toc@\f4hashmake\f1:\0\0convert words to 9-digit hashcodes@@@\f1see \f3spell(1)\f1 .\" toc@\f4spellin\f1:\0\0create compressed spelling list from hash codes@@@\f1see \f3spell(1)\f1 .\" toc@\f4hashcheck\f1\0\0create hash codes from compressed spelling list@@@\f1see \f3spell(1)\f1 .\" .\" links@spell.1 hashmake.1 .\" links@spell.1 spellin.1 .\" links@spell.1 hashcheck.1 .\" $Header: spell.1,v 72.6 94/11/14 15:21:23 ssa Exp $ .TA s .TH spell 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME spell, hashmake, spellin, hashcheck \- find spelling errors .SH SYNOPSIS .C spell .RC [ -v ] .RC [ -b ] .RC [ -x ] .RC [ -l ] .RC [ -i ] .RC [ +\c .IR local_file \|] .RI [ \|files\| ] .PP .C /usr/lbin/spell/hashmake .PP .C /usr/lbin/spell/spellin .I n .PP .C /usr/lbin/spell/hashcheck .I spelling_list .SH DESCRIPTION The .CR spell command collects words from the named .I files and looks them up in a spelling list. Words that neither occur among nor are derivable (by applying certain inflections, prefixes, and/or suffixes) from words in the spelling list are printed on the standard output. If no .I files are named, words are collected from the standard input. .PP The .CR spell command ignores most .CR troff , .CR tbl , and .I eqn constructions. .SS Options The .CR spell command recognizes the following options: .RS .TP 15 .C -v All words not literally in the spelling list are printed, and plausible derivations from the words in the spelling list are indicated. .TP .C -b British spelling is checked. Besides preferring .CR centre , .CR colour , .CR programme , .CR speciality , .CR travelled , etc., this option insists upon .CR -ise in certain words, such as in .CR standardise . .TP .C -x Every plausible stem is printed with .CR = for each word. .RE .PP By default, .CR spell follows chains of included files much like .CR deroff (see .IR deroff (1)) which recognizes the .CR troff / nroff intrinsics .CR .so and .CR .nx , .I unless the names of such included files begin with .CR /usr/share/lib . If the .CR -l option is used, .CR spell follows the chains of .I all included files. With the .CR -i option, .CR spell ignores all chains of included files. .PP If the .CI + local_file option is used, words found in .I local_file are removed from .CR spell 's output. .I local_file is the name of a user-provided file containing a sorted list of words, one per line. With this option, the user can specify a set of words that are correct spellings (in addition to .IR spell 's own spelling list) for each job. .PP The spelling list is based on many sources, and while more haphazard than an ordinary dictionary, is also more effective with respect to proper names and popular technical words. Coverage of the specialized vocabularies of biology, medicine, and chemistry is light. .PP Pertinent auxiliary files can be specified by name arguments, indicated below with their default settings (see FILES and VARIABLES). Copies of all output are accumulated in the history file. The stop list filters out misspellings (such as .CR thier=thy-y+ier ) that would otherwise pass. .PP Three routines help maintain and check the hash lists used by .CR spell : .RS .TP 15 .C hashmake Reads a list of words from the standard input and writes the corresponding nine-digit hash code on the standard output. .TP .CI spellin \ n Reads .I n hash codes from the standard input and writes a compressed spelling list on the standard output. Information about the hash coding is printed on standard error. .TP .C hashcheck Reads a compressed .I spelling_list and recreates the nine-digit hash codes for all the words in it; it writes these codes on the standard output. .RE .SH EXAMPLES To check spelling of a single .IR word : .IP .CI echo " word " "| spell" .PP If .I word is spelled correctly, a prompt is returned. If it is spelled incorrectly, .I word is printed before the prompt is returned. To check spelling of multiple words, they can also be typed as a group on the same command line: .IP .CI echo " worda wordb wordc ... " "| spell" .PP To create a personal spelling list that incorporates the words already present in the default American spelling list file .CR /usr/share/dict/hlista : .nf .IP .C cat /usr/share/dict/hlista | /usr/lbin/spell/hashcheck >tmp1 .C /usr/lbin/spell/hashmake >tmp1 .C sort -u -o tmp1 tmp1 .C /usr/lbin/spell/spellin `wc -l hlista .fi .PP To modify the default British spelling list file .CR /usr/share/dict/hlistb , replace all occurrences of .CR hlista with .CR hlistb in the above example. .PP To add words to the default spelling list, change login to .CR root , change the current working directory to .CR /usr/share/dict and execute the commands listed in the above example. .SH WARNINGS The spelling list's coverage is uneven. When undertaking the use of .CR spell as a new tool, it may be advisable to monitor the output for several months to gather local additions. Typically, these are kept in a separate local file that is added to the hashed .I spelling_list via .CR spellin , as shown above. .PP The British spelling feature was developed by an American. .PP Start-up versions of files .CR hlista , .CR hlistb , and .CR hstop are available in directory .CR /usr/newconfig/usr/share/dict . If these files or a suitable equivalent are not present in directory .CR /usr/share/dict , .CR spell complains: .IP .C "spell: cannot initialize hash table" .br .C "spell: cannot initialize hash table" .SH FILES .TP 38 .CR /usr/share/dict/hlist [ ab ] Hashed spelling lists, American and British. .PD 0 .TP .C /usr/share/dict/hstop Hashed stop list. .TP .C /var/adm/spellhist History file. .TP .C /usr/lbin/spell/spellprog Executable program file. .PD .SH VARIABLES .TP 15 .C D_SPELL Your hashed spelling list (default is .CR D_SPELL=/usr/share/dict/hlist [ ab ]) .PD 0 .TP .C H_SPELL Spelling history (default is .CR H_SPELL=/var/adm/spellhist ). .TP .C S_SPELL Your hashed stop list (default is .CR S_SPELL=/usr/share/dict/hstop ). .TP .C TMPDIR Directory for temporary files; overrides the default .CR /tmp . .PD .SH SEE ALSO deroff(1), sed(1), sort(1), tbl(1), tee(1). .SH STANDARDS CONFORMANCE .CR spell ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4spell\f1 \- find spelling errors@@@\f3spell(1)\f1 .\" index@\f1find spelling errors@@@\f3spell(1)\f1 .\" index@\f1spelling errors, find@@@\f3spell(1)\f1 .\" index@\f1errors, find spelling@@@\f3spell(1)\f1 .\" index@\f4hashcheck\f1 \- convert spelling reference list words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f1convert spelling reference list words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f4hashmake\f1 \- convert text words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f1convert text words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f4spellin\f1 \- convert 9-digit hash codes to compressed spelling reference list@@@\f3spell(1)\f1 .\" index@convert 9-digit hash codes to compressed spelling reference list@@@\f3spell(1)\f1 .\" index@\f1hash codes, convert 9-digit to or from text for spell checking@@@\f3spell(1)\f1 .\" .\" toc@\f3spell(1)\f1:\0\0\f4spell\f1, \f4hashmake\f1, \f4spellin\f1, \f4hashcheck\f1@@@find spelling errors\f1 .\" toc@\f4hashmake\f1:\0\0convert words to 9-digit hashcodes@@@\f1see \f3spell(1)\f1 .\" toc@\f4spellin\f1:\0\0create compressed spelling list from hash codes@@@\f1see \f3spell(1)\f1 .\" toc@\f4hashcheck\f1\0\0create hash codes from compressed spelling list@@@\f1see \f3spell(1)\f1 .\" .\" links@spell.1 hashmake.1 .\" links@spell.1 spellin.1 .\" links@spell.1 hashcheck.1 .\" $Header: head.1,v 76.2 95/08/03 17:53:27 ssa Exp $ .TA h .TH head 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME head \- give first few lines .SH SYNOPSIS .C head .RC [ -c \(or\c .CR -l ] .RC [ -n .IR count\| ] .RI [ \|file \0...\|] .PP .I Obsolescent: .br .C head .RC [ - \f2count\fP\|] .RI [ \|file \0...\|] .SH DESCRIPTION .C head prints on standard output the first .I count lines of each of the specified files, or of the standard input. If .I count is omitted it defaults to 10. .PP If multiple .I files are specified, .C head outputs before each file a line of this form: .IP .C ==> .I file .C <== .SS Options .TP 15 .C -c The quantity of output is measured in bytes. .TP .CI - count The number of units of output. This option is provided for backward compatibility (see .C -n below) and is mutually exclusive of all other options. .TP .C -l The quantity of output is measured in lines; this is the default. .TP .CI -n \0count The number of lines (default) or bytes output. .I count is an unsigned decimal integer. If .C -n (or .IR -count ) is not given, the default quantity is 10. This option provides the same functionality as the .CI - count option, but in a more standard way. Use of the .C -n option is recommended where portability between systems is important. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text within file as single and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C head behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH SEE ALSO tail(1). .SH STANDARDS CONFORMANCE .CR head ": SVID3, XPG4, POSIX.2" .\" .\" toc@\f3head(1)\f1:\0\0\f4head\f1@@@print first few lines in a file .\" .\" index@\f4head\f1 \- get first few lines in a file@@@\f3head(1)\f1 .\" index@\f1get first few lines in a file@@@\f3head(1)\f1 .\" index@\f1list first few lines in a file@@@\f3head(1)\f1 .\" index@\f1print first few lines in a file@@@\f3head(1)\f1 .\" index@\f1output first few lines in a file@@@\f3head(1)\f1 .\" index@\f1files: get first few lines in a file@@@\f3head(1)\f1 .\" index@\f1files: print first few lines in a file@@@\f3head(1)\f1 .\" index@\f1beginning of file, list first few lines at@@@\f3head(1)\f1 .\" index@\f1start of file, list first few lines at@@@\f3head(1)\f1 .\" .\" $Header: hostname.1,v 72.9 94/10/31 11:16:53 ssa Exp $ .TA h .TH hostname 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hostname \- set or display name of current host system .SH SYNOPSIS .CR hostname .RI [ name_of_host ] .SH DESCRIPTION The .CR hostname command displays the name of the current host, as given in the .CR gethostname() system call (see .IR gethostname (2)). Users who have appropriate privileges can set the hostname by giving the argument .IR name_of_host ; this is usually done in the startup script .CR /sbin/init.d/hostname . The .I name_of_host argument is restricted to .CR MAXHOSTNAMELEN characters as defined in .CR . .PP The system might be known by other names if networking products are supported. See the node manager documentation supplied with your system. .SH WARNINGS If the .I name_of_host argument is specified, the resulting host name change lasts only until the system is rebooted. To change the host name permanently, run the special initialization script .CR /sbin/set_parms (see .IR "Using Your HP Workstation" ). .PP Many types of networking services are supported on HP-UX, each of which uses a separately assigned system name and naming convention. To ensure predictable system behavior, it is essential that system names (also called host names or node names) be assigned in such a manner that they do not create conflicts when the various networking facilities interact with each other. .PP The system does not rely on a single system name in a specific location, partly because different services use dissimilar name formats as explained below. The .CR hostname and .CR uname commands assign system names as follows: .PP .ne 6v .ift \{.vs +2 .TS center box tab(;); lf3 | lf3 | lf3 | lf3 l | l | l | l . Node Name;Command;\f2name\fP Format;Used By _ .\" line -------------- Internet name;\f4hostname \f2name;\f2sys\f1[\f4.\f2x\f4.\f2y\f4.\f2z\f1...];ARPA and NFS Services .\" line -------------- UUCP name;\f4uname -S \f2name;\f2sys;\f4uucp \f1and related programs .TE .vs\} .ifn \{.nf +--------------+--------------+---------------+-----------------------+ |\f3Node Name\f1 |\f3Command\f1 |\f2name\f3 Format\f1 |\f3Used By\f1 | +--------------+--------------+---------------+-----------------------+ |Internet name |\f3hostname \f2name\f1 |\f2sys\f1[\f3.\f2x\f3.\f2y\f3.\f2z\f1...] |ARPA and NFS Services | |UUCP name |\f3uname -S \f2name\f1 |\f2sys\f1 |\f3uucp\f1, related programs | +--------------+--------------+---------------+-------- --------------+ .fi\} .PP where .I sys represents the assigned system name. It is .I strongly recommended that .I sys be identical for all commands and locations and that the optional .CI . x . y . z\f1...\& follow the specified notation for the particular ARPA/NFS environment. .PP Internet names are also frequently called host names or domain names (which are different from NFS domain names). Refer to .IR hostname (5) for more information about Internet naming conventions. .PP Whenever the system name is changed in any file or by the use of any of the above commands, it should also be changed in all other locations as well. Other files or commands in addition to those above (such as .CR /etc/uucp/Permissions if used to circumvent .CR uname , for example) may contain or alter system names. To ensure correct operation, they should also use the same system name. .PP System names are normally assigned by the .CR /sbin/init.d/hostname script at start-up, and should not be altered elsewhere. .SH AUTHOR .CR hostname was developed by the University of California, Berkeley. .SH SEE ALSO uname(1), gethostname(2), sethostname(2), uname(2), hostname(5). .PP .I "Using Your HP Workstation" .\" index@\f4hostname\f1 \- set or display name of current host system@@@\f3hostname(1)\f1 .\" index@\f1set name of current host system@@@\f3hostname(1)\f1 .\" index@\f1display name of current host system@@@\f3hostname(1)\f1 .\" index@\f1name of current host system, set or display@@@\f3hostname(1)\f1 .\" index@\f1current host system, set or display name of@@@\f3hostname(1)\f1 .\" index@\f1host system, set or display name of current@@@\f3hostname(1)\f1 .\" index@\f1system, set or display name of current host@@@\f3hostname(1)\f1 .\" index@\f1special initialization script, \f4/sbin/set_parms\f1@@@\f3hostname(1)\f1 .\" index@\f4/sbin/set_parms\f1 special initialization script@@@\f3hostname(1)\f1 .\" index@\f4set_parms\f1 special initialization script@@@\f3hostname(1)\f1 .\" .\" toc@\f3hostname(1)\f1:\0\0\f4hostname\f1@@@set or display name of current host system .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: hp.1,v 72.3 93/01/14 11:33:32 ssa Exp $ .TA h .TH hp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp \- handle special functions of HP\|2640 and HP\|2621-series terminals .SH SYNOPSIS .C hp .RC [ -e ] .RC [ -m ] .SH DESCRIPTION .C hp supports special functions of the Hewlett-Packard .SM HP 2640 and .SM HP 2621 series of terminals, with the primary purpose of producing accurate representations of most .C nroff output. A typical use is: .IP .CI "nroff -h " "files \|... " "| hp" .PP Regardless of the hardware options on a given terminal, .C hp tries to do sensible things with underlining and reverse line-feeds. If the terminal has the ``display enhancements'' feature, subscripts and superscripts can be indicated in distinct ways. If it has the ``mathematical-symbol'' feature, Greek and other special characters can be displayed. .SS Options .C hp recognizes the following options: .RS .TP 10 .C -e Specify that your terminal has the ``display enhancements'' feature, to make maximal use of the added display modes. Overstruck characters are presented in the Underline mode. Superscripts are shown in Half-bright mode, and subscripts in Half-bright, Underlined mode. If this flag is omitted, .C hp assumes that your terminal lacks the ``display enhancements'' feature. In this case, all overstruck characters, subscripts, and superscripts are displayed in Inverse Video mode; that is, dark-on-light, rather than light-on-dark. .TP .C -m Request minimization of output by removing new-lines. Any contiguous sequence of 3 or more new-lines is converted into a sequence of only 2 new-lines; that is, any number of successive blank lines produces only a single blank output line. This allows you to retain more actual text on the screen. .RE .SH DIAGNOSTICS .TP .C "line too long" The representation of a line exceeds 1,024 characters. .SH RETURN VALUE .C hp returns zero for normal termination, and 2 for all errors. .SH WARNINGS An ``overstriking sequence'' is defined as a printing character followed by a backspace followed by another printing character. In such sequences, if either printing character is an underscore, the other printing character is shown underlined or in Inverse Video; otherwise, only the first printing character is shown (again, underlined or in Inverse Video). Nothing special is done if a backspace is adjacent to an .SM ASCII control character. Sequences of control characters (e.g., reverse line-feeds, backspaces) can make text ``disappear''; in particular, tables generated by .C tbl that contain vertical lines will often be missing the lines of text that contain the ``foot'' of a vertical line, unless the input to .C hp is piped through .C col (see .IR col (1)). .PP Although some terminals do support numerical superscript characters, no attempt is made to display them. .SH SEE ALSO col(1), neqn(1), nroff(1), tbl(1). .\" .\" toc@\f3hp(1)\f1:\0\0\f4hp\f1@@@handle special functions of \s-1HP\s+1\|2640 and \s-1HP\s+1\|2621-series terminals .\" .\" index@\f4hp\f1 \- handle special functions of \s-1HP\s+1\|2640- and \s-1HP\s+1\|2621-series terminals@@@\f3hp(1)\f1 .\" index@handle special functions of \s-1HP\s+1\|2640- and \s-1HP\s+1\|2621-series terminals@@@\f3hp(1)\f1 .\" index@special functions of \s-1HP\s+1\|2640- and \s-1HP\s+1\|2621-series terminals, handle@@@\f3hp(1)\f1 .\" index@functions of \s-1HP\s+1\|2640- and \s-1HP\s+1\|2621-series terminals, handle special@@@\f3hp(1)\f1 .\" index@\s-1HP\s+1\|2640- and \s-1HP\s+1\|2621-series terminals, handle special functions of@@@\f3hp(1)\f1 .\" index@terminals, \s-1HP\s+1\|2640- and \s-1HP\s+1\|2621-series, handle special functions of@@@\f3hp(1)\f1 .\" .\" fileset_database@hp.1 USER-CMDS-MAN .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" .\" Add simple keeps to MAN macros so .TS/.TE will work .\" .de KS \" Keep start .br .in 0 .di KP .. .de KE \" Keep end .br .di .ne \\n(dnu .nr fI \\n(.u .nf .KP .if \\n(fI .fi .in .. .TH HPTERM 1X .ds )H Hewlett-Packard Company .ds ]W HP-UX HPTERM .SH NAME hpterm - X window system Hewlett-Packard terminal emulator. .sp 1 .SH SYNOPSIS .B hpterm [-toolkitoption] [-option] .sp 1 .SH DESCRIPTION The \fIhpterm\fP program is a terminal emulator for the X Window system. It provides a Term0 compatible terminal for programs that can't use the window system directly. It also emulates many of the block mode features of HP terminals. Refer to the WARNINGS section below for additional information about running block mode applications. .sp 1 .SH OPTIONS The \fIhpterm\fP terminal emulator accepts all of the standard X Toolkit command line options along with additional options all of which are listed below (if the option begins with a `+' instead of a `-', the option is restored to its default value): .TP 8 .BI \-b " number" This option specifies the size of the inner border (the distance between the outer edge of the character and the window border) in pixels. Associated resource: \fB*borderWidth\fP. .TP 8 .BI \-background " color" This option specifies the color to use for the background of the window. Associated resource: \fB*background\fP. .TP 8 .BI \-bd " color" This option specifies the color to use for the border of the window. Associated resource: \fB*borderColor\fP. .TP 8 .BI \-bg " color" This option specifies the color to use for the background of the window. Associated resource: \fB*background\fP. .TP 8 .BI \-borderwidth " number" This option specifies the width in pixels of the border surrounding the window. Associated resource: \fB*borderWidth\fP. .TP 8 .BI \-bs This option indicates that the "background" of the term0 text entry window should be the select color that corresponds to the specified background color. Associated resource: \fB*backgroundIsSelect\fP. .TP 8 .BI \+bs This option indicates that the "background" of the term0 text entry window should be the specified background. Associated resource: \fB*backgroundIsSelect\fP. .TP 8 .BI \-bw " number" This option specifies the width in pixels of the border surrounding the window. Associated resource: \fB*borderWidth\fP. .TP 8 .BI \-cr " color" This option specifies the color to use for the text cursor. Associated resource: \fB*cursorColor\fP. .TP 8 .BI \-display " display" This option specifies the X server to contact; see .IR "X" "(1)." Associated resource: none. .TP 8 .BI \-e " command \[arguments \.\.\.\]" This option specifies the command (and its command line arguments) to be run in the \fIhpterm\fP window. The default is to start the user's shell. \fBThis must be the last option on the command line.\fP Associated resource: none. .TP 8 .BI \-fb " fontset" This option specifies a font to be used when displaying bold (alternate) text. This font must be the same height and width as the normal (primary) font. If only one of the normal (primary) or bold (alternate) fonts is specified, it will be used for both fonts. The fontset should be specified as a Motif XmFontList(3X). Associated resource: \fB*userBoldFont\fP. .TP 8 .BI \-fg " color" This option specifies the color to use for displaying text. Associated resource: \fB*foreground\fP. .TP 8 .BI \-fn " fontset" This option specifies a font to be used when displaying normal (primary) text. If only one of the normal (primary) or bold (alternate) fonts is specified, it will be used for both fonts. The fontset should be specified as a Motif XmFontList(3X). Associated resource: \fB*userFont\fP. .TP 8 .BI \-font " fontset" This option specifies a font to be used when displaying normal (primary) text. If only one of the normal (primary) or bold (alternate) fonts is specified, it will be used for both fonts. The fontset should be specified as a Motif XmFontList(3X). This option is provided for backwards compatability only and will be removed in the next major release of HP-UX; use the \fB-fn\fP option instead. Associated resource: \fB*userFont\fP. .TP 8 .BI \-foreground " color" This option specifies the color to use for displaying text. Associated resource: \fB*foreground\fP. .TP 8 .BI \-geometry " geometry" This option specifies the preferred size and position of the \fIhpterm\fP window; see .IR "X" "(1)." Associated resource: \fBhpterm*geometry\fP. .TP 8 .B \-help This option will display a help message. Associated resource: none. .TP 8 .B \-i This option indicates that \fIhpterm\fP should supply the window manager with a bitmapped icon. Associated resource: \fBbitmapIcon\fP. .TP 8 .B \+i This option indicates that the window manager should generate its own icon for \fIhpterm\fP. Associated resource: \fBbitmapIcon\fP. .TP 8 .B \-iconic This option indicates that \fIhpterm\fP should be placed on the display in icon form. Associated resource: \fB*term0.iconic\fP. .TP 8 .B \+iconic This option indicates that \fIhpterm\fP should not be placed on the display in icon form. Associated resource: \fB*term0.iconic\fP. .TP 8 .B \-kshmode This option indicates that \fIhpterm\fP should convert characters entered with the extend key pressed into a two character sequence consisting of an ASCII escape followed by the un-extended character. Associated resource: \fB*kshMode\fP. .TP 8 .B \-l This option indicates that \fIhpterm\fP should send all terminal output to a log file as well as to the screen. Associated resource: \fB*logging\fP. .TP 8 .B \+l This option indicates that \fIhpterm\fP should not do logging. Associated resource: \fB*logging\fP. .TP 8 .BI \-lf " file" This option specifies the name of the file to which the output log described above is written. If \fIfile\fP begins with a pipe symbol (|), the rest of the string is assumed to be a command to be used as the endpoint of a pipe. The default filename is \fBHptermLog\fIXXXXX\fR (where \fIXXXXX\fP is the process id of \fIhpterm\fP) and is created in the directory from which \fIhpterm\fP was started. Associated resource: \fB*logFile\fP. .TP 8 .B \-ls This option indicates that the shell that is started in the \fIhpterm\fP window should be a login shell (i.e. the first character of argv[0] will be a dash, indicating to the shell that it should read the user's /etc/profile and .profile (for ksh and sh) or /etc/csh.login and .login (for csh). This option is ignored when the -e option is also used. Associated resource: \fB*loginShell\fP. .TP 8 .B \+ls This option indicates that the shell that is started should not be a login shell (i.e. it will be a normal ``subshell''). Associated resource: \fB*loginShell\fP. .TP 8 .B \-map This option indicates that \fIhpterm\fP should map (de-iconify) itself upon pty output if it is unmapped (iconified). An initial period of time during which \fIhpterm\fP will not map itself upon pty output may be specified via the \fBmapOnOutputDelay\fP resource. Associated resource: \fB*mapOnOutput\fP. .TP 8 .B \+map This option indicates that \fIhpterm\fP should not map (de-iconify) itself upon pty output if it is unmapped (iconified). Associated resource: \fB*mapOnOutput\fP. .TP 8 .B \-mb This option indicates that the pointer cursor should be put into blanking mode. In this mode, the cursor will turn on when the pointer is moved, and will be blanked either after a selectable number of seconds or after keyboard input has occurred. The delay is set via the \fBpointerBlankDelay\fP resource. Associated resource: \fB*pointerBlank\fP. .TP 8 .B \+mb This option indicates that the pointer cursor should remain on. Associated resource: \fB*pointerBlank\fP. .TP 8 .BI \-mc " mode" This option determines how \fIhpterm\fP will generate the foreground color, shadow colors, and shadow tiles of the scrollbar and softkey widgets. Valid modes are ``all'', ``shadow'', and ``none.'' Associated resource: \fB*makeColors\fP. .TP 8 .BI \-ms " color" This option specifies the color to be used for the pointer cursor. Associated resource: \fB*pointerColor\fP. .TP 8 .BI \-name " name" This option specifies the application name under which resources are to be obtained, rather than the default executable file name (``hpterm''). Associated resource: \fB.name\fP. .TP 8 .B \-reverse This option indicates that reverse video should be simulated by swapping the foreground and background colors. Associated resource: \fB*reverseVideo\fP. .TP 8 .B \-rv This option indicates that reverse video should be simulated by swapping the foreground and background colors. Associated resource: \fB*reverseVideo\fP. .TP 8 .B \+rv This option indicates that reverse video should not be simulated. Associated resource: \fB*reverseVideo\fP. .TP 8 .B \-sb This option indicates that a scrollbar should be displayed. Associated resource: \fB*scrollBar\fP. .TP 8 .B \+sb This option indicates that a scrollbar should not be displayed. Associated resource: \fB*scrollBar\fP. .TP 8 .BI \-sbbg " color" This option specifies the color to use for the background of the scrollbar window. Associated resource: \fB*scrollBar.background\fP. .TP 8 .BI \-sbfg " color" This option specifies the color to use for the foreground of the scrollbar window. This value will be ignored if the .B makeColors resource is set to \fBall\fR. Associated resource: \fB*scrollBar.foreground\fP. .TP 8 .BI \-skbg " color" This option specifies the color to use for the background of the softkey window. Associated resource: \fB*softkey.background\fP. .TP 8 .BI \-skfg " color" This option specifies the color to use for displaying softkey text. This value will be ignored if the .B makeColors resource is set to \fBall\fP. Associated resource: \fB*softkey.foreground\fP. .TP 8 .BI \-skfn " fontset" This option specifies a font to be used when displaying softkey text. The fontset should be specified as a Motif XmFontList(3X). Associated resource: \fB*softkey.userFont\fP. .TP 8 .BI \-sl " number[suffix]" This option indicates the number of off screen lines to be saved in the terminal buffer. If no suffix is included or the suffix is \fBl\fP, the total length of the terminal buffer will be \fInumber\fP plus the length of the terminal window. If the suffix is \fBs\fP the total length of the terminal buffer will be (\fInumber\fP plus one) times the length of the terminal window. Associated resource: \fB*saveLines\fP. .TP 8 .BI \-ti " name" This option specifies a name for \fIhpterm\fP to use when identifying itself to application programs. Refer to the WARNINGS section for additional information about using \fIhpterm\fP with block mode applications. Associated resource: \fB*termId\fP. .TP 8 .BI \-title " name" This option specifies a window title for \fIhpterm\fP. This string may be used by the window manager when displaying the application. Associated resource: \fB*title\fP. .TP 8 .BI \-tm " string" This option specifies a string containing terminal-setting keywords and the characters to which they may be bound. Associated resource: \fB*ttyModes\fP. .TP 8 .BI \-tn " name" This option specifies a name for \fIhpterm\fP to set the \fB$TERM\fP environment variable to. Associated resource: \fB*termName\fP. .TP 8 .B \-vb This option indicates that a visual bell is preferred over an audible one. Instead of ringing the terminal bell whenever a Control-G is received, the window will be flashed. Associated resource: \fB*visualBell\fP. .TP 8 .B \+vb This option indicates that a visual bell should not be used. Associated resource: \fB*visualBell\fP. .TP 8 .BI \-xrm " resourcestring" This option specifies a resource string to be used. This is especially useful for setting resources that do not have separate command line options. Associated resource: none. .TP 8 .B \-C This option indicates that the window should receive console output. The server must be authorized to receive console output. See ``XConsoles'' below for additional information. Associated resource: none. .TP 8 .BI \-S ccn This option specifies the last two letters of the name of a pseudoterminal to use in slave mode, and the file descriptor of the pseudoterminal's master. This allows \fIhpterm\fP to be used as an input and output channel for an existing program and is sometimes used in specialized applications such as \fIpam\fP(1). This option will only work with pty names of the form ``ttyxx.'' For example, ``-S p01'' specifies ``ttyp0'' on file descriptor 1. Associated resource: none. .TP 8 .BI \-S pty.fd This option specifies the unique portion of the name of a pseudoterminal to use in slave mode, and the file descriptor of the pseudoterminal's master. This allows \fIhpterm\fP to be used as an input and output channel for an existing program and is sometimes used in specialized applications such as \fIpam\fP(1). This option will work for all pty names. For example, ``-S p0.1'' specifies ``ttyp0'' on file descriptor 1 and ``-S p02.13'' specifies ``ttyp02'' on file descriptor 13. Associated resource: none. .TP 8 .PP The following command line arguments are provided for compatibility with older versions. They may not be supported in future releases as the X Toolkit provides standard options that accomplish the same task. .TP 8 .BI \# geometry This option specifies the preferred position of the icon window. It is shorthand for specifying the \fB*iconGeometry\fP resource. Associated resource: \fB.iconGeometry\fP. .TP 8 .BI \-T " string" This option specifies the title for \fIhpterm\fP's window. It is equivalent to \fB\-title\fP\& \fIstring\fP. Associated resource: \fB*title\fP. .TP 8 .BI \-n " string" This option specifies the icon name for \fIhpterm\fP's windows. It is shorthand for specifying the \fB*iconName\fP resource. Associated resource: \fB*iconName\fP. .TP 8 .B \-r This option indicates that reverse video should be simulated by swapping the foreground and background colors. It is equivalent to \fB\-reversevideo\fP or \fB\-rv\fP. Associated resource: \fB*reverseVideo\fP. .TP 8 .B \+r This option indicates that reverse video should not be simulated. It is equivalent to \fB+rv\fP. Associated resource: \fB*reverseVideo\fP. .TP 8 .BI \-w " number" This option specifies the width in pixels of the border surrounding the window. It is equivalent to \fB\-borderwidth\fP\& \fInumber\fP or \fB\-bw\fP\& \fInumber\fP. Associated resource: \fB*borderWidth\fP. .sp 1 .SH "RESOURCES" The .I hpterm window consists of a Motif shell widget which contains a form widget. The form widget contains a term0 widget, scrollbar widget, and softkey widget. Resources specific to the shell widget are: .sp 1 .KS .sp 1 .TS center; cB sss lB lB lB lB llll. hpterm Resource Set Name Class Type Default _ borderColor BorderColor Pixel black borderWidth BorderWidth int 2 geometry Geometry string iconGeometry IconGeometry string name Name string hpterm title Title string Terminal emulator .TE .sp 1 .KE .sp 1 .IP "\fBborderColor\fP" This resource defines the border color of the \fIhpterm\fP window. .IP "\fBborderWidth\fP" This resource specifies the width of the \fIhpterm\fP window border. This value may be modified by the window manager. .IP "\fBgeometry\fP" This resource specifies the preferred size and position of the \fIhpterm\fP window. .IP "\fBiconGeometry\fP" This resource specifies the preferred size and position of \fIhpterm\fP when iconified. It is not necessarily obeyed by all window managers. .IP "\fBname\fP" This resource specifies the name of the instance of the program. It is used when extracting resources from the resource database. .IP "\fBtitle\fP" This resource specifies the window title for \fIhpterm\fP. This string may be used by the window manager when displaying this application. .sp 1 .KS .sp 1 .TS center; cB sss lB lB lB lB llll. term0 Resource Set Name Class Type Default _ allowSendEvents AllowSendEvents Boolean FALSE background Background Pixel ``white'' backgroundIsSelect BackgroundIsSelect string FALSE bitmap Bitmap string bitmapIcon BitmapIcon Boolean FALSE boldFont UserBoldFont XmFontList dynamic copyLine CopyLine string ``right'' cursorColor Foreground Pixel ``black'' cut Cut string ``left'' dc1Handshake Dc1Handshake DC1Handshake ``auto'' flashBorder FlashBorder Boolean FALSE foreground Foreground Pixel ``black'' f\fIn\fPAttribute SoftkeyAttribute int 2 f\fIn\fPLabel SoftkeyLabel string see below f\fIn\fPString SoftkeyString string see below halfBrightInhibit HalfBrightInhibit Boolean FALSE iconic Iconic Boolean FALSE internalBorder BorderWidth int 2 kshMode KshMode Boolean FALSE logFile LogFile string ``HptermLog\fIXXXXX\fR'' logging Logging Boolean FALSE loginShell LoginShell Boolean FALSE makeColors MakeColors string ``none'' mapOnOutput AutoMap Boolean FALSE mapOnOutputDelay MapDelay int 0 paste Paste string ``middle'' pointerBlank PointerBlank Boolean FALSE pointerBlankDelay PointerBlankDelay int 3 pointerColor Foreground Pixel ``black'' pointerShape PointerShape string ``xterm'' reverseVideo ReverseVideo Boolean FALSE roman8 Roman8 Boolean TRUE saveLines SaveLines string ``1s'' scrollBar ScrollBar Boolean FALSE softkeyInitialize16 SoftkeyInitialize16 Boolean FALSE softkeyInitializeAll SoftkeyInitializeAll Boolean FALSE softkeyLast SoftkeyLast int 16 softkeySelect SoftkeySelect string ``left'' stickyNextCursor StickyCursor Boolean TRUE stickyPrevCursor StickyCursor Boolean TRUE termId TermId string ``hpterm'' termName TermName string ``hpterm'' ttyModes TtyModes string none userBoldFont UserBoldFont XmFontList dynamic userFont UserFont XmFontList dynamic visualBell VisualBell Boolean FALSE .TE .sp 1 .KE .PP .sp 1 .PP .IP "\fBallowSendEvents\fP" This resource defines whether synthetic key and button events (generated using the X protocol SendEvent request) should be interpreted or discarded. .IP "\fBbackground\fP" This resource defines the background color of the text window. .IP "\fBbackgroundIsSelect\fP" This resource controls the color used as the "background" of the term0 text entry window and defaults to False. When False, the background is the color specified. When True, the background is the "select color" that corresponds to the background. For visual consistency with other Motif-based applications, set this resource to True. .IP "\fBbitmap\fP" This resource defines whether \fIhpterm\fP will override its built in bitmap icon with a user specified bitmap icon. If the path does not begin with a ``/'' or ``./'', it will be processed relative to ``/usr/lib/X11/bitmaps''. .IP "\fBbitmapIcon\fP" This resource defines whether \fIhpterm\fP will supply the window manager with a bitmapped icon. The supplied bitmap may be ignored by the window manager. .IP "\fBboldFont\fP" This resource defines the font used for bold (alternate) text. This resource is provided for backwards compatability only and will be removed in the next major release of HP-UX; use the "\fBuserBoldFont\fP" resource instead. .IP "\fBcopyLine\fP" This resource defines the pointer button/modifier combination to be used to activate the CopyLine function. See ``POINTER USAGE'' below. .IP "\fBcursorColor\fP" This resource defines the text cursor color. The pointer cursor color is defined by the \fBpointerColor\fP resource. .IP "\fBcut\fP" This resource defines the pointer button/modifier combination to be used to activate the Cut function. See ``POINTER USAGE'' below. .IP "\fBdc1Handshake\fP" This resource controls how DC1/DC2 handshaking is enabled for transferring data between hpterm and the application requesting the data. This resource can have one of three values: ``auto'', ``enabled'', or ``disabled''. When set to ``disabled'', no handshaking is required for transferring data from hpterm to the application; when set to ``enabled'', the handshaking mode is controlled strictly by the state of the InhHndShk (strap G) and InhDC2 (strap H) flags. Setting \fBdc1Handshake\fP to ``auto'' causes hpterm to start out with DC1 handshaking initially disabled, it is automatically enabled the first time hpterm receives a DC1 character and is once again controlled by the state of the InhHndShk (strap G) and InhDC2 (strap H) flags. .IP "\fBflashBorder\fP" This resource defines whether \fIhpterm\fP window border will change color when the pointer cursor enters or leaves the window. .IP "\fBforeground\fP" This resource defines the foreground (text) color of the text window. .IP "\fBf\fIn\fBAttribute\fR" This resource defines the softkey attribute for softkey \fIn\fP (1 to \fBsoftkeyLast\fP). If \fBsoftkeyInitializeAll\fP is true, all softkey attributes can be initialized. If it is false, only the first \fBsoftkeyLast\fP / 2 softkey attributes can be initialized. .IP "\fBf\fIn\fBLabel\fR" This resource defines the softkey label for softkey \fIn\fP (1 to \fBsoftkeyLast\fP). If \fBsoftkeyInitializeAll\fP is true, all softkey labels can be initialized. If it is false, only the first \fBsoftkeyLast\fP / 2 softkey labels can be initialized. The default labels for softkeys 1 to \fBsoftkeyLast\fP / 2 are ``f1'' through ``f\fBsoftkeyLast\fP / 2''. The default labels for the remaining softkeys are empty if \fBsoftkeyInitializeAll\fP is false, otherwise they are ``f\fBsoftkeyLast\fP / 2 + 1'' through ``f\fBsoftkeyLast\fP''. .IP "\fBf\fIn\fBString\fR" This resource defines the softkey string for softkey \fIn\fP (1 to \fBsoftkeyLast\fP). If \fBsoftkeyInitializeAll\fP is true, all \fBsoftkeyLast\fP softkey strings can be initialized. If it is false, only the first \fBsoftkeyLast\fP / 2 softkey strings can be initialized. The default strings for softkeys 1 to 8 are ``p'' through ``w''; the default strings for the remaining softkeys are empty. .IP "\fBhalfBrightInhibit\fP" This resource defines whether half-bright enhancements will be not be generated. When true, full-bright characters will be used instead of half-bright characters. .IP "\fBiconic\fP" This resource defines whether \fIhpterm\fP will start up in iconic form. .IP "\fBinternalBorder\fP" This resource defines the number of pixels between the characters and the window border. .IP "\fBkshMode\fP" This resource defines whether \fIhpterm\fP will operate in ksh mode. In ksh mode, \fIhpterm\fP converts characters entered with the extend key pressed into a two-character sequence consisting of an ASCII escape followed by the un-extended character. .IP "\fBlogFile\fP" This resource defines the name of the file to which a terminal session is logged. The default is ``\fBHptermLog\fIXXXXX\fR'' (where \fIXXXXX\fP\& is the process id of \fIhpterm\fP). .IP "\fBlogging\fP" This resource defines whether a terminal session will be logged. It is also available at runtime via the Device Control menu. .IP "\fBloginShell\fP" This resource defines whether the shell to be run in the window will be started as a login shell (i.e., the first character of argv[0] will be a dash, indicating to the shell that it should read the user's /etc/profile and .profile (for ksh and sh) or /etc/csh.login and .login (for csh). .IP "\fBmakeColors\fP" This resource is provided for backward compatibility with older versions of hpterm; since it may not be supported in future releases, it is no longer recommended for use. This resource defines how the \fBbottomShadowColor\fP, \fBforeground\fP, and \fBtopShadowColor\fP resources of the scrollbar and softkey widgets will be generated and how the \fBforeground\fP resource of the term0 widget will be generated. If the value of this resource is ``all'', then \fIhpterm\fP will use the value of the \fBbackground\fP resource of the term0 widget to generate a value for the \fBforeground\fP, and the \fBbackground\fP resource of the softkey and scrollbar widgets to generate values for the \fBbottomShadowColor\fP, \fBforeground\fP, and \fBtopShadowColor\fP resources such that there is a 3-D look. In this case the \fBtopShadowTile\fP and \fBbottomShadowTile\fP are always set to ``foreground.'' If the \fBmakeColors\fP resource value is ``shadow'' the \fBbottomShadowColor\fP and \fBtopShadowColor\fP will be generated but \fBforeground\fP will not be generated. If the \fBmakeColors\fP resource value is set to ``none'' then no colors will be generated. .IP "\fBmapOnOutput\fP" This resource defines whether \fIhpterm\fP will map (de-iconify) itself upon pty output if it is unmapped (iconified). An initial period of time during which \fIhpterm\fP will not map itself upon pty output may be specified to allow \fIhpterm\fP to not map itself upon initial shell output. The delay is set via the \fBmapOnOutputDelay\fP resource. .IP "\fBmapOnOutputDelay\fP" This resource defines the number of seconds at startup during which \fIhpterm\fP will not map (de-iconify) itself upon pty output. .IP "\fBpaste\fP" This resource defines the pointer button/modifier combination to be used to activate the Paste function. See ``POINTER USAGE'' below. .IP "\fBpointerBlank\fP" This resource defines whether \fIhpterm\fP will put the pointer cursor into blanking mode. In blanking mode, the pointer cursor will turn on when the pointer is moved, and will be blanked either after a selectable number of seconds or after keyboard input has occurred. The delay is set via the \fBpointerBlankDelay\fP resource. .IP "\fBpointerBlankDelay\fP" This resource defines the number of seconds to wait before blanking the pointer cursor after the pointer has been moved. When set to ``0'', the pointer will be blanked only upon keyboard input. .IP "\fBpointerColor\fP" This resource defines the pointer cursor color. The text cursor color is defined by the \fBcursorColor\fP resource. .IP "\fPpointerShape\fP" This resource defines the pointer cursor shape. Valid cursor shapes may be found in the file ``/usr/include/X11/cursorfont.h.'' Shapes are specified as the name with the leading ``\fBXC_\fP'' dropped. Valid cursor shapes include ``left_ptr'', ``crosshair'', and ``xterm.'' .IP "\fBreverseVideo\fP" This resource defines whether reverse video will be simulated by swapping the foreground and background colors. .IP "\fBroman8\fP" This resource controls the mapping of keys to characters and is effective only for western european keyboards. Roman8 encoding is used when set to TRUE, ISO 8859-1 encoding is used when set to FALSE. (It is the user's responsibility to ensure that correctly encoded fonts are used; refer to the discussion on fonts in your \fBUsing the X Window System Manual\fP for more information on font characteristics.) .IP "\fBsaveLines\fP" This resource defines the number of lines in the terminal buffer beyond the length of the window. The resource value consists of a ``\fInumber\fP'' followed by an optional ``\fIsuffix\fP.'' If no \fIsuffix\fP is included or the \fIsuffix\fP is ``\fBl\fP'' the total length of the terminal buffer will be \fInumber \fPplus the length of the terminal window. If the suffix is ``\fBs\fP'' the total length of the terminal buffer will be (\fInumber\fP plus one) times the length of the terminal window. \fIHpterm\fB will try to maintain the same buffer to window ratio when the window is resized larger. .IP "\fBscrollBar\fP" This resource defines whether the scrollbar will be displayed. .IP "\fBsoftkeyInitialize16\fP" This resource enables initialization of all \fBsoftkeyLast\fP softkeys. If false, only the first \fBsoftkeyLast\fP / 2 softkeys can be initialized via resources. (This resource has been superceded by \fBsoftkeyInitializeAll\fP, and will be eliminated in the next release of HP-UX.) .IP "\fBsoftkeyInitializeAll\fP" This resource enables initialization of all \fBsoftkeyLast\fP softkeys. If false, only the first \fBsoftkeyLast\fP / 2 softkeys can be initialized via resources. .IP "\fBsoftkeyLast\fP" This resource tells \fIhpterm\fP the maximum number of user softkeys to recognize (16 or 24). The only valid values for this resource are 16 or 24; values greater than 16 are forced to 24, values less then 16 are forced to 16. .IP "\fBsoftkeySelect\fP" This resource defines the pointer button/modifier combination to be used for selecting softkeys. See ``POINTER USAGE'' below. .IP "\fBstickyNextCursor\fP" This resource defines whether the cursor should be homed when the \fBNext\fP key is pressed. When true, the cursor will be in the same screen position after the key is pressed that it was in before pressing the key. When false, the cursor will be moved to the upper left hand corner of the screen after the key is pressed. .IP "\fBstickyPrevCursor\fP" This resource defines whether the cursor should be homed when the \fBPrev\fP key is pressed. When true, the cursor will be in the same screen position after the key is pressed that it was in before pressing the key. When false, the cursor will be moved to the upper left hand corner of the screen after the key is pressed. .IP "\fBtermId\fP" This resource defines the name for \fIhpterm\fP to use when identifying itself to application programs. Refer to the WARNINGS section for additional information about using \fIhpterm\fP with block mode applications. .IP "\fBtermName\fP" This resource defines the string for setting the ``\fB$TERM\fP'' environment variable. .IP "\fBttyModes\fP" (class \fBTtyModes\fP) This resource specifies a string containing terminal-setting keywords and the characters to which they may be bound. Allowable keywords include: intr, quit, erase, kill, eof, eol, swtch, start, stop, brk, susp, dsusp, rprnt, flush, weras, and Inext. Control characters may be specified as ^char (e.g. ^c or ^u), and ^? may be used to indicate delete. This is very useful for overriding the default terminal settings without having to do an \fIstty\fP every time an \fIhpterm\fP is started. .IP "\fBuserBoldFont\fP" This resource defines the font used for bold (alternate) text. .IP "\fBuserFont\fP" This resource defines the font used for normal (primary) text. .IP "\fBvisualBell\fP" This resource defines whether a visible bell (i.e. flashing) should be used instead of an audible bell when Control-G is received. .PP The following resources are specified as part of the ``softkey'' widget (name ``softkey'', class ``Softkey''). For example, the softkey userFont resource would be specified one of: .KS .sp 1 .in 0 .TS center; l l. HPterm*softkey*userFont: hp8.8x16 HPterm*Softkey*userFont: hp8.8x16 *Softkey*UserFont: hp8.8x16 .TE .in .sp 1 .KE .PP Additional resources and information can be found in the .BR XmPrimitive (3X) and .BR CORE (3X) man pages along with additional information about the various shadow options. .sp 1 .KS .sp 1 .TS center; cB sss lB lB lB lB llll. Softkey Resource Set Name Class Type Default _ background Background Pixel ``white'' bottomShadowColor Foreground Pixel ``black'' (see below) bottomShadowTile BottomShadowTile string ``foreground'' (see below) foreground Foreground Pixel ``black'' (see below) topShadowColor Background Pixel ``white'' (see below) topShadowTile TopShadowTile string ``50_foreground'' (see below) userFont UserFont XmFontList dynamic .TE .sp 1 .KE .sp 1 .IP "\fBbackground\fP This resource defines the background color of the softkey window. .IP "\fBbottomShadowColor\fP This resource defines the color that is combined with the bottom shadow tile and foreground color to create a pixmap used to draw the bottom and right sides of the softkey borders. This may be overridden by the term0 \fBmakeColors\fP resource described above. .IP "\fBbottomShadowTile\fP This resource defines the tile used in creating the pixmap used for drawing the bottom and right shadows for the softkey borders. Valid tile names are described in .BR XmCreateTile (3X). This may be overridden by the term0 \fBmakeColors\fP resource described above. .IP "\fBforeground\fP" This resource defines the foreground (text) color of the softkey window. This may be overridden by the term0 \fBmakeColors\fP resource described above. .IP "\fBtopShadowColor\fP" This resource defines the color that is combined with the top shadow tile and foreground color to create a pixmap used to draw the top and left sides of the softkey borders. This may be overridden by the term0 \fBmakeColors\fP resource described above. .IP "\fBtopShadowTile\fP" This resource defines the tile used in creating the pixmap used for drawing the top and left shadows for the softkey borders. Valid tile names are described in .BR XmCreateTile (3X). This may be overridden by the term0 \fBmakeColors\fP resource described above. .IP "\fBuserFont\fP" This resource defines the font used for softkey text. The softkey font will default to the normal (primary) font of the text window. .sp .PP The following resources are specified as part of the ``Xmscrollbar'' widget (name ``scrollBar'', class ``ScrollBar''). Some example scrollbar resources are: .KS .sp 1 .in 0 .TS center; l l. HPterm*scrollBar*initialDelay: 10 HPterm*ScrollBar*RepeatRate: 10 *ScrollBar*Granularity: 1 hpterm*scrollBar*width: 20 .TE .in .sp 1 .KE .PP Additional resources and information can be found in the .BR XmPrimitive (3X), .BR XmScrollBar (3X), .BR XmValuator (3X), and .BR Core (3X) man pages along with additional information about the various shadow options. .sp 1 .KS .sp 1 .TS center; cB sss lB lB lB lB llll. Scrollbar Resource Set (name ``scrollBar'', class ``ScrollBar'') Name Class Type Default _ background Background Pixel ``white'' bottomShadowColor Foreground Pixel ``black'' (see below) bottomShadowTile BottomShadowTile string ``foreground'' (see below) foreground Foreground Pixel ``black'' (see below) granularity Granularity int 2 initialDelay InitialDelay int 500 repeatRate RepeatRate int 100 topShadowColor Background Pixel ``white'' (see below) topShadowTile TopShadowTile string ``50_foreground'' (see below) width Width int 10 .TE .sp 1 .KE .sp 1 .IP "\fBbackground\fP This resource defines the background color of the scrollbar window. .IP "\fBbottomShadowColor\fP This resource defines the color that is combined with the bottom shadow tile and foreground color to create a pixmap used to draw the bottom and right sides of the scrollbar borders. This may be overridden by the term0 \fBmakeColors\fP resource described above. .IP "\fBbottomShadowTile\fP This resource defines the tile used in creating the pixmap used for drawing the bottom and right shadows for the scrollbar borders. Valid tile names are described in .BR XmCreateTile (3X). This may be overridden by the term0 \fBmakeColors\fP resource described above. .IP "\fBforeground\fP" This resource defines the foreground color of the scrollbar window. This may be overridden by the term0 \fBmakeColors\fP resource described above. .IP "\fBgranularity\fP" This resource defines the number of lines to advance the slider when the button is being held down on an arrow. The value is defined in milliseconds. .IP "\fBinitialDelay\fP" This resource defines the delay to wait between the time the button is held down on an arrow before the slider starts its repetitive movement. The value is defined in milliseconds. .IP "\fBrepeatRate\fP" This resource defines the continuous repeat rate to use to move the slider while the button is being held down on an arrow. The value is also defined in milliseconds. .IP "\fBtopShadowColor\fP" This resource defines the color that is combined with the top shadow tile and foreground color to create a pixmap used to draw the top and left sides of the scrollbar borders. This may be overridden by the term0 \fBmakeColors\fP resource described above. .IP "\fBtopShadowTile\fP" This resource defines the tile used in creating the pixmap used for drawing the top and left shadows for the scrollbar borders. Valid tile names are described in .BR XmCreateTile (3X). This may be overridden by the term0 \fBmakeColors\fP resource described above. .IP "\fBwidth\fP" This resource defines the width of the scrollbar in pixels. .sp 1 .SH "POINTER USAGE" .I Hpterm allows you to cut and paste text within its own or other windows. All cutting and pasting is done using the PRIMARY selection. (To maintain compatability with previous versions of hpterm (and other applications that use cut buffers), the cutting and pasting is also done to/from the first global cut buffer. When pasting, .I hpterm gets its text from the PRIMARY selection; if the PRIMARY selection is not owned, or the current owner cannot supply the data as text, .I hpterm will try to get its data from the first global cut buffer.) The PRIMARY selection will be disowned (and the selected text unhighlighted) under the following conditions: .RS .2in .IP 1) .2in .ll -.2in the cursor is moved anywhere before the end of the selected region .IP 2) .2in .ll -.2in the beginning of the selected region is scrolled off the end of the terminal buffer .IP 3) .2in .ll -.2in the selected region is scrolled across the boundaries of the locked region when memory lock is enabled. .RE 1 .PP The default button assignments may be changed via various resource strings. The cut and paste functions and their default button assignments are: .IP \fBCut\fP .6in The left button is used to ``cut'' text into the cut buffer. Move the pointer to the beginning of the text to cut, press the button, move the cursor to the end of the region, and release the button. The ``cut'' text will not include the character currently under the pointer. .IP \fBPaste\fP The middle button ``pastes'' the text from the cut buffer, inserting it as keyboard input. .IP \fBCopyLine\fP The right hand button ``cuts'' the text from the pointer (at button release) through the end of line (including the new line), saving it in the cut buffer, and immediately ``pastes'' the line, inserting it as keyboard input. This provides a history mechanism. .PP The copyLine, cut, and paste key functions can be configured to any button and modifier combination desired via various resources. Each assignment consists of an optional combination of modifiers (``none'' or any combination of ``shift'', ``meta'', ``lock'', ``control'', ``mod1'', ..., ``mod5'' separated by blanks), followed by a ``|'' and the name of the button (``left'', ``middle'', ``right'', ``button1'', ..., ``button5''). For example, if it is desired for the cut function to be associated with the middle button with shift and control pressed, one could use the following resource line: .PP *cut: shift control | middle .PP For a full list of resource names, see ``RESOURCES'' above. .sp 1 .SH XCONSOLES It is possible to configure a system to allow redirection of console output (and input) to an \fIhpterm\fP window. If the ``-C'' option is used, \fIhpterm\fP will redirect console output (and input) if: .RS 8 .PP \fIHpterm\fP is displaying on the local system. \fIHpterm\fP must be running on the same system as the server that is displaying the window. .PP The display is authorized. The display number of the display name (see ``Display Specification'' in \fIX\fP(1)) must be authorized to take control of the console via the file ``/usr/etc/X11/Xconsoles.'' The file is parsed as follows: .RS 8 .PP A `#' and all following text on a line are ignored. .PP Blank lines are ignored. .PP Leading tabs and spaces are ignored. .PP A number matching the display number authorizes the server to redirect console output (and input). .PP An asterisk (`*') matches all display numbers and authorizes the server to redirect console output (and input). .RE .RE .PP If either condition is not met, a warning will be written to stderr and console output (and input) will not be redirected. .sp 1 .SH WARNINGS When running block mode applications, it may be necessary for \fIhpterm\fP to identify itself to application programs as some terminal other than ``hpterm.'' Most applications understand the terminal id ``2392A.'' Newer applications also understand the terminal id ``700/92'' while older applications may only understand the terminal id ``2622A.'' To set the terminal identification string, use the ``-ti'' command line option, the ``termId'' resource, or the ``TermId'' class. .PP Hpterm does not support line block mode. .PP \fIHpterm\fP does not fully support locales that contain 3 or 4 byte characters and will silently ignore any 3 or 4 byte characters in the data stream. \fIDtterm\fP is the recommended terminal emulator when operating in Asian EUC locales. .PP The overflow protect mode of memory lock is not supported. .sp 1 .SH ENVIRONMENT \fIHpterm\fP sets the environment variables ``\fB$LINES\fP'' and ``\fB$COLUMNS\fP'' to the number of lines and columns of the terminal screen. It also uses and sets the environment variable ``\fB$DISPLAY\fP'' to specify its server connection. The .IR resize (1) command may be used to reset ``\fB$LINES\fP'' and ``\fB$COLUMNS\fP'' after the window size has been changed. .sp 1 .SH ORIGIN Hewlett-Packard Company. .sp 1 .SH "SEE ALSO" \fIX(1), dtterm(1), resize(1), xset(1), xterm(1), Core(3X), XmFontList(3X), XmForm(3X), XmPrimitive(3X), XmScrollBar(3X), pty(4)\fP .\" $Header: hyphen.1,v 72.3 93/01/14 11:35:28 ssa Exp $ .TA h .TH hyphen 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hyphen \- find hyphenated words .SH SYNOPSIS .C hyphen .RI [ \|files\| ] .SH DESCRIPTION .C hyphen finds all the hyphenated words ending lines in .I files and prints them on the standard output. If no arguments are given, the standard input is used; thus, .C hyphen can be used as a filter. .SH EXAMPLES Prepare an .C nroff hyphenation proofreading file for .IR textfile . .IP .C mm textfile | hyphen .SH WARNINGS .C hyphen cannot cope with hyphenated .I italics (i.e., underlined) words; it often misses them completely or mangles them. .PP .C hyphen occasionally gets confused, but with no ill effects other than spurious extra output. .SH SEE ALSO mm(1), nroff(1). .\" .\" toc@\f3hyphen(1)\f1:\0\0\f4hyphen\f1@@@find hyphenated words .\" .\" index@\f4hyphen\f1 \- find hyphenated words@@@\f3hyphen(1)\f1 .\" index@find hyphenated words@@@\f3hyphen(1)\f1 .\" index@hyphenated words, find@@@\f3hyphen(1)\f1 .\" index@words, find hyphenated@@@\f3hyphen(1)\f1 .\" .\" fileset_database@hyphen.1 USER-CMDS-MAN .\" $Header: iconv.1,v 76.1 95/08/03 17:55:32 ssa Exp $ .TA i .TH iconv 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iconv \- code set conversion .SH SYNOPSIS .C iconv -f .I fromcode .C -t .I tocode .RI [ \|file \0...\|] .SH DESCRIPTION .C iconv converts the encoding of characters in the input files from the .I fromcode code set to the .I tocode code set, and writes the results on standard output. If no input files are given, .C iconv reads from standard input. If .C - appears as an input file name, .C iconv reads standard input at that point. .C -\|- can be used to delimit the end of options (see .IR getopt (3C)). .SS Options .C iconv recognizes the following options: .RS .TP 15 .CI -f " fromcode" Identify the code set corresponding to option argument .I fromcode as the code set that the input will be converted ``from''. .TP .CI -t " tocode" Identify the code set corresponding to option argument .I tocode as the code set that the input will be converted ``to''. .RE .PP The .I fromcode and .I tocode names can be any of the base and alias names listed in the iconv configuration file, /usr/lib/nls/iconv/config.iconv. See .IR iconv (3C) for details and the configuration file for a list of supported code set names. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C iconv will behave as if all internationalization variables are set to "C". See .IR environ (5). .PP .C LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .PP .C LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. During translation of the file, this variable is superseded by the use of the .I fromcode option-argument. .PP .C LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .C NLSPATH determines the location of message catalogues for the processing of .C LC_MESSAGES. .SS International Code Set Support Single and multi-byte character code sets are supported. .SH WARNINGS If an input character does not have a valid equivalent in the code set selected by the .C -t option (the "to" code set), it is mapped to the "galley character", if it has been defined for that conversion. (see .IR genxlt (1) and .IR iconv (3C) ). .PP If an input character does not belong to the code set selected by the .C -f option (the "from" code set), the command terminates. .SH EXAMPLES Convert the contents of file .C foo from code set Roman8 to .SM ISO 8859/1 and store the results in file .CR bar . .IP .C "iconv -f roman8 -t iso8859_1 foo > bar" .SH FILES /usr/lib/nls/iconv/config.iconv iconv configuration file .SH AUTHOR .C iconv was developed by HP. .SH SEE ALSO getopt(3C),iconv(3C) .SH STANDARDS CONFORMANCE .CR iconv ": XPG2, XPG3, XPG4" .\" .\" index@\f4iconv\f1 \- character code set conversion@@@\f3iconv(1)\f1 .\" index@character code set, convert to another@@@\f3iconv(1)\f1 .\" index@convert character code set to another@@@\f3iconv(1)\f1 .\" index@translate character code to another code set@@@\f3iconv(1)\f1 .\" index@code set conversion, character@@@\f3iconv(1)\f1 .\" .\" toc@\f3iconv(1)\f1:\0\0\f4iconv\f1@@@character code set conversion .\" .\" fileset_database@iconv.1 USER-CMDS-MAN .\" $Header: id.1,v 76.1 95/08/01 16:08:03 ssa Exp $ .TA i .TH id 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME id \- print user and group IDs and names .SH SYNOPSIS .CR id .RC [ -g \(or -u ] .RC [ -nr ] .RC [ -P ] .RI [ user ] .SH DESCRIPTION The .CR id command writes a message to standard output, giving the user and group IDs and names for the process. If the effective and real IDs are different, both are printed. .PP If the process has supplementary group affiliations (see .IR groups (1)), the supplementary group affiliations are also written. .PP If the .IR user operand is specified, and the user has appropriate privileges, the user and group IDs of the selected user are written. In this case, effective IDs are assumed to be identical to real IDs. .SS Options .PP The following options modify the behavior described above. .RS .TP .CR -g Display only the group ID. The default is the effective group ID; to modify, use the .CR -r option. If the process has supplementary group affiliations that are different from the effective group ID, display each such affiliation on the same line. The default is decimal format; to modify, use the .CR -n option. .TP .CR -n With .CR -u or .CR -g , display the name in character string format instead of the numeric ID. .TP .CR -r With .CR -u or .CR -g , display the real ID instead of the effective ID. .TP .CR -u Display only the user ID. The default is the effective user ID; to modify, use the .CR -r option. The default is decimal format; to modify, use the .CR -n option. .TP .CR -P Display the process resource group ID. See HP Process Resource Manager in DEPENDENCIES. .RE .SH EXAMPLES To display the current user and group data: .IP .C "id" .PP produces: .IP .C "uid=1834(allanp) gid=20(users) .PP To display the group ID number for the current user: .IP .C "id -g" .PP produces: .IP .C "20" .PP To display the group name for the current user: .IP .C "id -gn" .PP produces: .IP .C "users" .PP To display the user and group data for another user: .IP .C "id ralford .PP produces: .IP .C "uid=329(ralford) gid=20(users)" .PP if the user has appropriate privileges. Otherwise, it produces the data for the user. .SH AUTHOR .CR id was developed by HP and AT&T. .SH DEPENDENCIES .SS HP Process Resource Manager The .CR -P option requires that the optional HP Process Resource Manager (PRM) software be installed and configured. See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for the definition of the process resource group. .SH SEE ALSO groups(1), logname(1), getuid(2). .PP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR id ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4id\f1 \- print user and group IDs and names@@@\f3id(1)\f1 .\" index@\f1print user and group IDs and names@@@\f3id(1)\f1 .\" index@\f1user IDs and names, print@@@\f3id(1)\f1 .\" index@\f1group IDs and names, print@@@\f3id(1)\f1 .\" index@\f1IDs, print user and group@@@\f3id(1)\f1 .\" index@\f1names, print user and group@@@\f3id(1)\f1 .\" .\" toc@\f3id(1)\f1:\0\0\f4id\f1@@@print user and group IDs and names .\" $Header: ident.1,v 72.3 93/01/14 11:35:12 ssa Exp $ .TA i .TH ident 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ident \- identify files in \s+1RCS\s0 .SH SYNOPSIS .C ident .IR file \0... .SH DESCRIPTION .C ident searches the named files for all occurrences of the pattern .CI $ keyword :\f1...\fP$\f1, where .I keyword is one of the following: .RS .TP 20 .C Author .C Log .PD 0 .TP .C Date .C Revision .TP .C Header .C Source .TP .C Locker .C State .PD .RE .PP These patterns are normally inserted automatically by the .SM RCS .C co command, but can also be inserted manually (see .IR co (1)). .PP .C ident works on text files as well as object files. For example, if the C program in file .C f.c contains: .IP .C char rcsid[] = .C """$\&Header: Header information $"""; .PP and .C f.c is compiled into .CR f.o , the command: .IP .C "ident f.c f.o" .PP prints: .RS .TP 15 .C f.c: .br .C $\&Header: Header information $ .TP .C f.o: .br .C $\&Header: Header information $ .RE .SH AUTHOR .C ident was developed by Walter F. Tichy. .SH SEE ALSO ci(1), co(1), rcs(1), rcsdiff(1), rcsintro(5), rcsmerge(1), rlog(1), rcsfile(4). .\" .\" toc@\f3ident(1)\f1:\0\0\f4ident\f1@@@identify files in \s-1RCS\s+1 .\" .\" index@\f4ident\f1 \- identify files in Revision Control System@@@\f3ident(1)\f1 .\" index@identify files in Revision Control System@@@\f3ident(1)\f1 .\" index@\s-1RCS\s+1: identify files in Revision Control System@@@\f3ident(1)\f1 .\" .\" fileset_database@ident.1 USER-CMDS-MAN .\" $Header: idlookup.1,v 1.1.113.2 96/01/04 16:27:42 indnetwk Exp $ .TA i .TH idlookup 1 .SH NAME idlookup \- identify the user of a particular TCP connection .SH SYNOPSIS .C idlookup .I host-or-ip-number local-port foreign-port .SH DESCRIPTION .CR idlookup can be used to identify the user at the remote end of a TCP connection, assuming the host at the other end is running an Identification Server. .PP .IR host-or-ip-number is the name of the host at the other end of the connection, or its IP address. .PP .IR local-port and .IR foreign-port are the port numbers, or service names of the ports at the two ends of the connection. .PP .SH WARNING Note that the references to .IR local-port and .IR foreign-port follow the terminology in RFC931, and are from the point of view of the .B server rather than the user. .PP .SH AUTHOR .CR idlookup was originally written by Peter Eriksson. The manual page was originally written by Dave Sheild. .SH SEE ALSO sendmail(1M), identd(1M), .I RFC931. .\" .\" index@\f4idlookup\f1 \- identify the user of a particular TCP connection@@@\f3idlookup(1)\f1 .\" index@\f1identify the user of a particular TCP connection@@@\f3idlookup(1)\f1 .\" index@\f1user of a particular TCP connection, identify@@@\f3idlookup(1)\f1 .\" index@\f1TCP connection, identify user@@@\f3idlookup(1)\f1 .\" .\" toc@\f3idlookup(1)\f1:\0\0\f4idlookup\f1@@@identify the user of a particular TCP connection .\" $Header: ied.1,v 72.4 94/05/13 15:48:57 ssa Exp $ .TA i .TH ied 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ied \- input editor and command history for interactive programs .SH SYNOPSIS .C ied .RC [ -dirt ] .RC [ -h .IR file\| ] .RC [ -s .IR size\| ] .RC [ -p .IR prompt\| ] .ifn .br .ifn \h'.75i' .RC [ -k .IR charmap\| ] .I utility .RI [ \|arguments \0...\|] .SH DESCRIPTION .C ied is a utility command that is intended to act as an interface between the user and an interactive program such as bc, bs, or Bourne shell, providing most of the line editing and history functionality found in the Korn shell. .C ied interprets the .I utility name as the command to be executed, and passes .I arguments as the arguments to the utility. Subsequent input to .I utility then has access to editing and history functions very similar to those provided by .IR ksh . .PP .C ied monitors the state of the pty it uses to run the command, and, whenever the application it is running, changes the state from the state of the tty when .C ied started, .C ied becomes ``transparent''. This allows programs to do shell escapes to screen-smart programs. In general, .C ied should not in any way interfere with any action taken by any program for which it provides a front end. This includes Korn shell itself: in this case .C ied would provide history for any application that was run by .CR ksh , and .C ksh would provide its own independent history. In a useful extreme case, .C ied can be used as a front end to the login shell (which might be .C ksh or .CR csh ). In this case, all applications that use normal line editing gain line editing and history, sharing a single history. The shell would continue to have its own independent history if it provides such a mechanism. .PP When .C ied is in its transparent mode, no history is saved. In particular the .C ex mode of .C vi does not use normal line editing (rather, it simulates it) and .C ied cannot provide history in this case. The .C Subject: and address line editing of mailx also cannot be edited with .CR ied . .SS Options Several options and command-line arguments control .CR ied 's operation: .RS .TP 15 .C -d Debug mode. Print information about the operation of the program. It is best used to determine if a program puts .C ied into transparent mode unexpectedly. .TP .CI -h \0filename Keep the history in a file named .IR filename . If a file of that name already exists and is a history file, the latter part of it (the last .I size lines as specified by the .C -s option) is used as the initial value of the history. If the .C -h option is not used, the environment variable .C IEDHISTFILE is used to supply the name. If neither are present an unnamed temporary file is used, and no initial value is provided. .TP .C -i Force interactive mode. Normally .C ied simply .CR exec s the command to which it is asked to be a front end when the standard input is not a tty (this allows aliases to be used for commands used in shells without interfering with their operation). This option forces .C ied to remain as a front end, and all editing functions are in place. This permits a utility that behaves differently in interactive and batch modes to be driven from a pipe or file in interactive mode. This is particularly useful in testing commands that make this distinction. .TP .CI -k \0charmap .I charmap is a file of 256 or fewer lines. The line number in the file is the ordinal of a character as seen as input by .CR ied , and the character on the line is the character generated as output (and also used as editing characters). This allows remapping of (ordinary) keys such as for a Dvorak keyboard. Characters must start in column one of each line, and be represented as 1-4 characters followed by a space or the new-line character for the next line. Characters after the space are ignored as comments. Single-character entries represent themselves. Two-character entries where the first character is a circumflex .RC ( ^ ) converts the second character to the corresponding control character. Two-character sequences where the first character is backslash .RC ( \e ) use the C language conventions: .IP .ne 6v .TS center tab(;); lf4p+1 l lf4p+1 l. \en;newline;\es;space \e\e;escape;\e0;null \er;return;\ef;form feed \et;tab;\ev;vertical tab \eb;backspace .TE .IP Three- and four-character sequences must be .CI \e nn or .CI \e nnn\c , giving the octal value for the character. If .I charmap is less than 256 lines long, the remaining characters are mapped to themselves. .TP .CI -p \0prompt Many commands do not prompt when ready for input. .C ied approximates a prompting mechanism for such commands. This is not always perfectly successful, but for many commands it helps. In the worst case, the prompt is interspersed with output in the wrong location. .I prompt is a string as used in the format argument to .IR printf (3S). The only .C % conversions that can be included are up to one instance of .C %d which is converted to the sequential number of the command, and any number of occurrences of .C %% which is treated as a literal .C % character. Prompting is suppressed when .C ied is operating in transparent mode. .TP .C -r This sets "non-raw" mode. Normally .C ied uses its own editing capabilities when reading simple text. This causes .C ied to use tty line discipline most of the time. The disadvantage of the default mode is that more context switches and general processing are required. The advantage is that .C ied is more transparent. For example, to specifically send an end-of-file in the non-raw mode requires that the end-of-file character (usually Ctrl-D) be followed by a carriage return. Similarly the ``literal next'' function (Ctrl-V) cannot escape the line-erase and line-kill functions in non-raw mode. .TP .CI -s \0size This option specifies the size of the history buffer. When .C ied is started with an existing history file, approximately the last .I size lines are available to the history mechanism (the number is not guaranteed to be exactly .IR size ). Other lines in the file are retained until such time as .C ied is started on that history file and it exceeds approximately 4K bytes in size, at which time .C ied discards older entries at the beginning of the file until it is near 4 Kbytes in size. Since this occurs only at startup, history files can grow to be quite large between restarts. Larger values of .I size make the process image larger. .IP If .C -s is not specified, the value of the environment variable .C IEDHISTSIZE is used. If neither is specified, a default is used. .TP .C -t Set transparent mode. This forces .C ied to permanently be in transparent mode (as discussed above). It is primarily useful with .C -i for some classes of automated processing. In particular, it is useful for driving a command if the command takes as input what .C ied would interpret as editing characters. Thus with the appropriate combinations of .C -i and .CR -t , it is possible to drive an editor such as .C vi or a screen-smart application from a batch file. .RE .PP Should something go wrong with .CR ied , the .C SIGQUIT signal, repeated 3 times, usually aborts .CR ied . The exception is the case of a fully transparent application, where .C ied must be killed from another window or terminal. This is really relevant only when there is no way to direct the serviced process to terminate itself. .PP The editing capabilities of .C ied are essentially those found in .CR ksh . Only those that differ from .C ksh are described below. As in .CR ksh , the style of editing is determined from the environment variable .CR VISUAL , or from .C EDITOR if .C VISUAL is not specified. The value examined should end in .CR vi , .CR emacs , or .C gmacs to specify an editor type. If it does not, .C ied does no editing, and history is not accessible. .PP In vi mode: .RS .TP 20 .C J Join lines. Considering the most recently edited line (which is empty immediately after a line is sent to the application) to be the ``last line'' of the history, the current line being displayed from the history is appended to the end of the last line, and the position in the history is reset to be at the last line which is then displayed. A space is inserted between the old and new text on the last line. The cursor is left on that space. Because .CR ied 's understanding of line continuation is minimal, this is useful for editing long statements. .TP .C v Not supported. .TP .C V Not supported. .TP .C # Sends nothing to the application, but inserts the line in the history (useful for adding comments to history file). .TP .IC ,*,= (Filename expansion). Not supported. .TP \f3@\f1 Macro expansion. Not supported. .IP Note however that .C ksh has a rarely-used function .C _ that substitutes words from the previous line (this is not the macro .CR $_ , but rather an editor command). If a preceding .I count is given, it uses the .IR count th word of the last line. This is much more useful with .CR ied . .RE .PP In emacs/gmacs mode: .RS .TP 20 .CR M-* , \0M-= , \0M- \f2\fP (filename expansion) Not supported. .IP Note that the command .C M-. (and it's synonym .CR M-_ ) provide the same functionality as the vi mode .C _ command. .TP Macro expansion. Not supported. .TP .C ^O Although supported, it may not always appear correctly on the screen. The .C ^L command can be used to redraw the line. See below for the discussion on prompting. .RE .SH EXAMPLES Add interactive editing to the .C bc command: .IP .C ied bc .PP Execute .C vi on .C testfile using comands taken from .CR script : .IP .C "cat script | ied -i -t vi testfile" .PP Note that without the use of .CR ied , .C vi would misbehave because its standard input would not be a terminal device. In this case the .C -t is not required because .C vi puts itself in raw mode, but for an application that does not, .C -t might be required. .PP The command line .IP .C "ied -i -t grep '^x:' data_file | tee x_lines" .P searches the file .C data_file for lines beginning with .CR x: , sending one copy to the terminal and a second to file .CR x_lines , just like the command line .IP .C "grep '^x:' data_file | tee x_lines" .PP The difference is that in the command line without .CR ied , .C grep writes directly to a pipe, and thus buffers its output. If .C data_file is very large and not many lines match the pattern, output to the terminal is delayed. By using .CR ied , the output of .C grep goes to a pty instead, which causes .C grep to output each line as it is ready. .SH WARNINGS Since .C ied cannot know everything about every application, it is possible that it can become confused, with either the timing or the prompt being out of phase with the application. Since the use of .C ied is never required, it is the user's choice to determine whether the application is more usable with or without .CR ied . In general, however, programs that do not confuse .C ied are usually also the most likely to benefit from its use. .PP .C ied tries to intuit the currently active prompt when it is not providing one itself. However, this is not always successful. Even when it is successful, the timing of .C ied and the serviced command may occasionally confuse the output. The .C ^L commands in both emacs and vi modes redraw the edit line in a consistent fashion that can be used to create the next command. .SH AUTHOR .C ied was developed by HP. .SH SEE ALSO ksh(1). .\" .\" index@\f4ied\f1 \- input editor and command history for interactive programs@@@\f3ied(1)\f1 .\" index@input editor and command history for interactive programs@@@\f3ied(1)\f1 .\" index@editor and command history for interactive programs input@@@\f3ied(1)\f1 .\" index@command history and input editor for interactive programs@@@\f3ied(1)\f1 .\" index@history and input editor for interactive program commands@@@\f3ied(1)\f1 .\" index@interactive programs, input editor and command history for@@@\f3ied(1)\f1 .\" index@programs, input editor and command history for interactive@@@\f3ied(1)\f1 .\" .\" toc@\f3ied(1)\f1:\0\0\f4ied\f1@@@input editor and command history for interactive programs .\" .\" fileset_database@ied.1 USER-CMDS-MAN .\" $Header: imageview.1,v 74.1 95/05/10 21:48:31 ssa Exp $ .TA i .TH imageview 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME imageview \- display, manipulate, and print image files .SH SYNOPSIS .CI /opt/image/bin/imageview \0 .RC [ filename ] .RC [ -d .IC host :\c .IR number \|] .RC [ -g .IR geometry \|] .RC [ -o .IR orientation \|] .SH DESCRIPTION .C imageview displays bit-mapped image files on an X11 display on HP 9000 Series 700 or 800 systems. Through imageview's graphical user interface, which is based on .SM OSF\ /Motif, you can display and manipulate the image, and save certain changes you make. .PP If you have access to SharedPrint/UX printers, you can print the image from .CR "imageview". To set up SharedPrint/UX printers, see your administrator or .CR "setup_pr.sh(1m)". .PP The following table lists types of image files that can be displayed, what these files contain, the filename suffix (extension) .SM HP VUE uses to display the correct icon, and the file version supported. .ifn \{.PP .nf +-----+------------+-----------------------------------+-------------+ |File | VUE File | File Contents Version | |Type | Extension | Supported | +-----+------------+-----------------------------------+-------------+ |TIFF | .tif | PC, scanned, and FAX images | 5.0 (6.0 for| | | | | TIFF JPEG) | |JFIF | .jpg .jpeg | JPEG-compressed images | 8-R8 | |GIF | .gif | xv and xgif images | 87a, 89a | |XWD | .xwd | Pixmap images from xwd (Z format) | X11 | |XBM | .xbm .bm | Bitonal X bitmap images | X11 | |XPM | .xpm .pm | Color X pixmap images | 3.0 | |BMF | .bmf | Starbase bitmap images (Z format) | 1 | |PCX | .pcx | PC bitmap images | 3.0 | |BMP | .bmp | PC bitmap images | 3.0 | |IMG | .img | GEM PC Images | | +-----+------------+-----------------------------------+-------------+ .fi\} .ift \{.PP .TS center box tab(;); cB | cB | cB | cB cB | cB | cB | cB cp-1 | cf4 | l | l. File Type;VUE File;File Contents;Version ;Extension;;Supported _ TIFF;.tif;PC, scanned, and FAX images;5.0 (6.0 for ;;;TIFF JPEG) JFIF;.jpg\0\0.jpeg;JPEG-compressed images;8-R8 GIF;.gif;xv and xgif images;87a, 89a XWD;.xwd;Pixmap images from xwd (Z format);X11 XBM;.xbm\0\0.bm;Bitonal X bitmap images;X11 XPM;.xpm\0\0.pm;Color X pixmap images;3.0 BMF;.bmf;Starbase bitmap images (Z format);1 PCX;.pcx;PC bitmap images; 3.0 BMP;.bmp;PC bitmap images; 3.0 IMG;.img;GEM images .TE\} .PP The TIFF images you can view may be in uncompressed format, or any of the following compressed formats: .SM JPEG, LZW, G3, CCITT/G3, CCITT/G4, or Packbits. .PP The .I filename argument is an absolute or relative pathname of a file containing one or more images in a supported format and can contain .CR * and .C ? pattern specifiers. If .I filename resolves to more than one file, .C imageview displays the first file found. .SS Options .C imageview recognizes the following options: .RS .ift .TP 20 .ifn .TP 10 .CI -d \0host : number Specifies the display to use. Arguments are: .RS .RS .TP 15 .I host Name of the host machine. .TP .I number Number of the display. .RE .RE .IP If the .C -d option is omitted, .C imageview uses the value of the .C DISPLAY environment variable. .TP .CI -g \0geometry Specifies the position and maximum size of the viewer window. The viewer window consists of an image window framed by a menu and control panel. The syntax for .I geometry is the standard X geometry syntax; see .IR X (1) in the reference section of .IR "Using the X Window System" . .IP If the .C -g option is omitted, .C imageview creates a window that matches the image size. If the image is too large for the display, .C imageview creates the largest window possible without changing the ratio of image height to image width. .TP .CI -o \0orientation Sets the initial orientation of the image. .I orientation is one of the following: .RS .RS .TP 15 .C landscape Rotate the image 90 degrees clockwise before displaying. .TP .C portrait Do not rotate the image. .RE .RE .IP If the .C -o option is omitted, .C -o portrait is used. .RE .SH EXAMPLES Display the file .C rgb.tif in the current directory and rotate the first image found 90 degrees clockwise. .IP .C "imageview rgb.tif -o landscape" .PD .SH AUTHOR .C imageview was developed by HP. .SH SEE ALSO sprint(1), spadmin(1m), setup_pr.sh(1m), .br X(1) in .IR "Using the X Window System" . .\" .\" index@\f4imageview\fP \- display bit-mapped file images on an X11 display@@@\f3imageview(1)\f1 .\" index@display bit-mapped file images on an X11 display@@@\f3imageview(1)\f1 .\" index@\s-1TIFF\s0 file images on an X11 display, display@@@\f3imageview(1)\f1 .\" index@file images on an X11 display, display \s-1TIFF\s0@@@\f3imageview(1)\f1 .\" index@images on an X11 display, display \s-1TIFF\s0 file@@@\f3imageview(1)\f1 .\" index@X11 display, display \s-1TIFF\s0 file images on an@@@\f3imageview(1)\f1 .\" index@X11 graphics, display \s-1TIFF\s0 file images on X11 display@@@\f3imageview(1)\f1 .\" index@graphics, display \s-1TIFF\s0 file images on X11 display@@@\f3imageview(1)\f1 .\" .\" toc@\f3imageview(1)\f1:\0\0\f4imageview\fP@@@display bit-mapped images file on an X11 display .\" .\" links@imageview.1 ImageView.1 .\" .\" fileset_database@imageview.1 IMAGE-MAN .\" $Header: insertmsg.1,v 76.1 95/07/10 17:04:47 ssa Exp $ .TA i .TH insertmsg 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insertmsg \- use findstr(1) output to insert calls to catgets(3C) .SH SYNOPSIS .C insertmsg .RC [ -h ] .RC [ -n\f2number\| ] .RC [ -i\f2amount\| ] .RC [ -s\f2number\| ] .I stringlist .SH DESCRIPTION .C insertmsg examines the file .IR stringlist , which is assumed to be the output of .C findstr after subsequent editing to remove any strings that do not need to be localized (see .IR findstr (1)). If the .C -h option is specified, .C insertmsg places the following lines at the beginning of each file named in .I stringlist: .nf .IP .C #ifndef NLS .C #define catgets(i,sn,mn,s) (s) .C #else NLS .CI #define NL_SETN \0number .C #include .C #endif NLS .fi .PP where .I number is a set number defined by the .C -s option; the default is .CR 1 . For each string in .IR stringlist , .C insertmsg surrounds the string in the corresponding file with an expression of the form: .IP .CI (catgets(catd,NL_SETN, msg_num ,\c .ifn \fe"\fP\f2default string\fP\f3"))\fP .ift \f4\s+1"\fP\s0\f2default string\fP\f4\s+1"))\fP\s0 .PP The .I default string is the original string referenced by the line in .IR stringlist , and .I msg_num is replaced by the message number assigned to that string. The assigned message numbers begin with the number defined by the .C -n option and are incremented by the amount defined by the .C -i option. The default is .C 1 for both the starting message number and the increment. If .IC name .c is the file to be modified, as specified within the .I stringlist file, .I insertmsg places the modified source in .CI nl_ name .c\f1. The user must then manually edit the file .CI nl_ name .c to insert the following statements: .IP .C nl_catd catd; .br .C catd = catopen(" .I appropriate message catalog .C """,0); .PP The data type .C nl_catd is defined in .RC < nl_types.h > and .C catd is a parameter to the calls to .IR catgets , which are inserted for each string from .IR stringlist . .PP .C insertmsg also sends to the standard output a file that can be used as input to .C gencat (see .IR gencat (1)). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C insertmsg behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS If .C insertmsg does not find opening or closing double quotes where required in the strings file, it prints .C "insertmsg exiting : lost in strings file" and aborts. If this happens, check the strings file to ensure that the lines that have been kept there have not been altered. .SH WARNINGS If the .C -h option is not used, it may be necessary to manually add the following statement to the file created by .CR insertmsg : .IP .C #include .PP .C insertmsg inserts a pointer to a static area that is overwritten on each call. .SH AUTHOR .C insertmsg was developed by HP. .SH SEE ALSO findstr(1), gencat(1), catgets(3C), catopen(3C). .\" .\" index@\f4insertmsg\f1 \- use \f4findstr\f1(1) output to insert calls to \f4catgets\f1(3C)@@@\f3insertmsg(1)\f1 .\" index@\f4findstr\f1(1) output, use to insert calls to \f4catgets\f1(3C)@@@\f3insertmsg(1)\f1 .\" index@\f1insert calls to \f4catgets\f1(3C) based on \f4findstr\f1(1) output@@@\f3insertmsg(1)\f1 .\" index@\f4catgets\f1(3C), insert calls to based on \f4findstr\f1(1) output@@@\f3insertmsg(1)\f1 .\" .\" toc@\f3insertmsg(1)\f1:\0\0\f4insertmsg\f1@@@use findstr(1) output to insert calls to catgets(3C) .\" .\" $Header: intro.1,v 72.4 94/12/08 16:32:49 ssa Exp $ .TA a .TH intro 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME intro \- introduction to command utilities and application programs .SH DESCRIPTION This section describes commands accessible by users, as opposed to system calls in Section (2) or library routines in Section (3), which are accessible by user programs. .SS Command Syntax Unless otherwise noted, commands described in this section accept options and other arguments according to the following syntax: .IP .I name .RI [ \|option\| ( \|s\| )\|] .RI [ \|cmd_arg\| ( \|s\| )\|] .PP where the elements are defined as follows: .RS .TP 10 .I name Name of an executable file. .TP .I option One or more .IR option s can appear on a command line. Each takes one of the following forms: .RS .ift .RS .TP 15 .CI - no_arg_letter A single letter representing an option without an argument. .TP .CI - no_arg_letters Two or more single-letter options combined into a single command-line argument. .TP .CI - arg_letter\f1<>\fPopt_arg A single-letter option followed by a required argument where: .RS .ift .RS .TP 15 .I arg_letter is the single letter representing an option that requires an argument, .TP .I opt_arg is an argument (character string) satisfying the preceding .IR arg_letter , .TP <> represents optional white space. .RE .RE .ift .RE .ift .RE .PD .TP .I cmd_arg Path name (or other command argument) .I not beginning with .CR - , or .C - by itself indicating the standard input. If two or more .IR cmd_arg s appear, they must be separated by white space. .RE .SS Manual Entry Formats All manual entries follow an established topic format, but not all topics are included in each entry. .TP 20 .CR NAME Gives the name(s) of the entry and briefly states its purpose. .TP .CR SYNOPSIS Summarizes the use of the entry or program entity being described. A few conventions are used: .IP .C Computer font strings are literals, and are to be typed exactly as they appear in the manual (except for parameters in the SYNOPSIS section of entries in Sections 2 and 3). .IP .IR Italic strings represent substitutable argument names and names of manual entries found elsewhere in the manual. .IP Square brackets [] around an argument name indicate that the argument is optional. .IP Ellipses (...) are used to show that the previous argument can be repeated. .IP A final convention is used by the commands themselves. An argument beginning with a dash (-), a plus sign (+), or an equal sign (=) is often taken to be some sort of option argument, even if it appears in a postion where a file name could appear. Therefore it is unwise to have file names that begin with -, +, or =. .TP .CR DESCRIPTION Discusses the function and behavior of each entry. .TP .C EXTERNAL INFLUENCES Information under this heading pertains to programming for various spoken languages. Typical entries indicate support for single- and/or multi-byte characters, the effect of language-related environment variables on system behavior, and other related information. .TP .C NETWORKING FEATURES Information under this heading is applicable only if you are using the networking feature described there (such as NFS). .TP .C RETURN VALUE Discusses various values returned upon completion of program calls. .TP .C DIAGNOSTICS Discusses diagnostics indications that may be produced. Self-explanatory messages are not listed. .TP .C ERRORS Lists error conditions and their corresponding error message or return value. .TP .C EXAMPLES Provides examples of typical usage, where appropriate. .TP .C WARNINGS Points out potential pitfalls. .TP .C DEPENDENCIES Points out variations in HP-UX operation that are related to the user or specific hardware or hardware combinations. .TP .C AUTHOR Indicate the origin of the software documented by the manual entry. .TP .C FILES Lists file names that are built into the program or command. .TP .C SEE ALSO Provides pointers to related topics. .TP .C BUGS Discusses known bugs and deficiencies, occasionally suggesting fixes. .TP .C STANDARDS CONFORMANCE This section lists the standard specifications to which the HP-UX component conforms. .RE .SH RETURN VALUE Upon termination, each command returns two bytes of status, one supplied by the system giving the cause for termination, and (in the case of ``normal'' termination) one supplied by the program (for descriptions, see .IR wait (2) and .IR exit (2)). The system-supplied byte is 0 for normal termination. The byte provided by the program is customarily 0 for successful execution and non-zero to indicate errors or failure such as incorrect parameters in the command line, or bad or inaccessible data. Values returned are usually called variously ``exit code'', ``exit status'', ``return code'', or ``return value'', and are described only where special conventions are involved. .SH WARNINGS Some commands produce unexpected results when processing files containing null characters. These commands often treat text input lines as strings, and therefore become confused when they encounter a null character (the string terminator) within a line. .SH SEE ALSO getopt(1), exit(2), wait(2), getopt(3C), hier(5). .PP The introduction to this manual. .\" .\" index@\f4intro\f1 \- introduction to command utilities and application programs@@@\f3intro(1)\f1 .\" .\" toc@\f3intro(1)\f1:\0\0\f4intro\f1@@@introduction to command utilities and application programs .\" .\" fileset_database@intro.1 USER-CMDS-MAN .\" $Header: vis.1,v 76.1 95/07/11 13:47:55 ssa Exp $ .TA v .TH vis 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vis, inv \- make unprintable and non-ASCII characters in a file visible or invisible .SH SYNOPSIS .C vis .RC [ -n ] .RC [ -s ] .RC [ -t ] .RC [ -u ] .RC [ -x ] .IR file \ .\|.\|. .br .C inv .RC [ -n ] .RC [ -s ] .RC [ -t ] .RC [ -u ] .RC [ -x ] .IR file \ .\|.\|. .SH DESCRIPTION .C vis reads characters from each .I file in sequence and writes them to the standard output, converting those that are not printable or not ASCII into a visible form. .I inv performs the inverse function, reading printable characters from each .IR file , returning them to non-printable or non-ASCII form, if appropriate, then writing them to standard output; .PP Non-printable ASCII characters are represented using C-like escape conventions: .RS .PD 0 .TP 8 .C \e\e backslash .TP .C \eb backspace .TP .C \ee escape .TP .C \ef form-feed .TP .C \en new-line .TP .C \er carriage return .TP .C \es space .TP .C \et horizontal tab .TP .C \ev vertical tab .TP .CI \e n the character whose .SM ASCII code is the 3-digit octal number .IR n . .TP .CI \ex n the character whose .SM ASCII code is the 2-digit hexadecimal number .IR n . .RE .PD .PP Non-ASCII single- or multi-byte characters are examined one byte at a time. For each byte, if it can be displayed as an ASCII character, it is treated as if it is an ASCII character; Otherwise, it is represented in the following conventions: .RS .PD 0 .TP 8 .CI \e n the 8-bit character whose code value is the 3-digit octal number .IR n . .TP .CI \ex n the 8-bit character whose code value is the 2-digit hexadecimal number .IR n . .RE .PD .PP Space, horizontal-tab, and new-line characters can be treated as printable (and therefore passed unaltered to the output) or non-printable depending on the options selected. Backslash, although printable, is expanded by .IR vis , to a pair of backslashes so that when they are passed back through .IR inv , they convert back to a single backslash. .PP If no input file is given, or if the argument .C - is encountered, .C vis and .I inv read from the standard input. .SS Options .C vis and .C inv recognize the following options: .RS .TP 8 .C -n Treat new-line, space, and horizontal tab as non-printable characters. .C vis expands them visibly as .CR \en , .CR \es , and .CR \et , rather than passing them directly to the output. .C inv discards these characters, expecting only the printable expansions. New-line characters are inserted by .C vis every 16 bytes so that the output will be in a form that is usable by most editors. .TP .C -s Make .C vis and .C inv silent about non-existent files, identical input and output, and write errors. Normally, no input file can be the same as the output file unless it is a special file. .TP .C -t Treat horizontal-tab and space characters as non-printable in the same manner that .C -n treats them. .TP .C -u Cause output to be unbuffered (byte-by-byte); normally, output is buffered. .TP .C -x Cause .C vis output to be in hexadecimal form rather than the default octal form. Either form is accepted to .C inv as input. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the language in which messages are displayed. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH AUTHOR .C vis was developed by HP. .SH SEE ALSO cat(1), echo(1), od(1). .SH WARNINGS Redirecting output to an input file destroys the original data. Therefore, command forms such as .IP .C vis\0file1\0file2\0>file1 .PP should be avoided unless the source file can be safely discarded. .\" .\" index@\f4vis\f1 \- make unprintable and non-ASCII characters in a file visible@@@\f3vis(1)\f1 .\" index@\f4inv\f1 \- make unprintable and non-ASCII characters in a file invisible@@@\f3vis(1)\f1 .\" index@\f1make unprintable and non-ASCII characters in a file visible or invisible@@@\f3vis(1)\f1 .\" index@\f1files: make unprintable and non-ASCII characters in a file visible or invisible@@@\f3vis(1)\f1 .\" index@\f1unprintable characters in a file, make visible or invisible@@@\f3vis(1)\f1 .\" index@\f1non-ASCII characters in a file, make visible or invisible@@@\f3vis(1)\f1 .\" index@\f1characters in a file, unprintable and non-ASCII, make visible or invisible@@@\f3vis(1)\f1 .\" .\" toc@\f3vis(1)\f1:\0\0\f4vis\f1, \f4inv\f1@@@make unprintable and non-ASCII characters in a file visible or invisible .\" toc@\f4inv\f1: make unprintable and non-ASCII characters in a file invisible@@@see \f3vis(1)\f1 .\" .\" links@vis.1 inv.1 .\" .\" $Header: iostat.1,v 72.5 94/11/29 13:24:48 ssa Exp $ .TA i .TH iostat 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iostat \- report \s-1I/O\s0 statistics .SH SYNOPSIS .C iostat .RC [ -t ] .RI [ \|interval .RI [ \|count\| ]\|] .SH DESCRIPTION .C iostat iteratively reports .SM I/O statistics for each active disk on the system. Disk data is arranged in a four-column format: .RS .TP 25 .C Column Heading .C Interpretation .PD 0 .TP .C \h'.3i'device Device name .TP .C \h'.3i'bps Kilobytes transferred per second .TP .C \h'.3i'sps Number of seeks per second .TP .C \h'.3i'msps Milliseconds per average seek .RE .PD .PP If two or more disks are present, data is presented on successive lines for each disk. .PP To compute this information, seeks, data transfer completions, and the number of words transferred are counted for each disk. Also, the state of each disk is examined .C HZ times per second (as defined in .RC < sys/param.h >) and a tally is made if the disk is active. These numbers can be combined with the transfer rates of each device to determine average seek times for each device. .PP With the advent of new disk technologies, such as data striping, where a single data transfer is spread across several disks, the number of milliseconds per average seek becomes impossible to compute accurately. At best it is only an approximation, varying greatly, based on several dynamic system conditions. For this reason and to maintain backward compatibility, the milliseconds per average seek ( .C msps ) field is set to the value 1.0. .SS Options .C iostat recognizes the following options and command-line arguments: .RS .TP 12 .C -t Report terminal statistics as well as disk statistics. Terminal statistics include: .RS .RS .TP 7 .C tin Number of characters read from terminals. .PD 0 .TP .C tout Number of characters written to terminals. .TP .C us Percentage of time system has spent in user mode. .TP .C ni Percentage of time system has spent in user mode running low-priority .RI ( nice ) processes. .TP .C sy Percentage of time system has spent in system mode. .TP .C id Percentage of time system has spent idling. .RE .RE .PD .TP .I interval Display successive lines which are summaries of the last .I interval seconds. The first line reported is for the time since a reboot and each subsequent line is for the last interval only. .TP .I count Repeat the statistics .I count times. .SH EXAMPLES Show current .SM I/O statistics for all disks: .IP .C iostat .PP Display .SM I/O statistics for all disks every 10 seconds until .SM INTERRUPT or .SM QUIT is pressed: .IP .C iostat 10 .PP Display .SM I/O statistics for all disks every 10 seconds and terminate after 5 successive readings: .IP .C iostat 10 5 .PP Display .SM I/O statistics for all disks every 10 seconds, also show terminal and processor statistics, and terminate after 5 successive readings: .IP .C iostat -t 10 5 .SH WARNINGS Users of .C iostat must not rely on the exact field widths and spacing of its output, as these will vary depending on the system, the release of HP-UX, and the data to be displayed. .SH AUTHOR .C iostat was developed by the University of California, Berkeley, and HP. .SH FILES .C /usr/include/sys/param.h .SH SEE ALSO vmstat(1). .\" .\" index@\f4iostat\f1 \- report \s-1I/O\s+1 statistics@@@\f3iostat(1)\f1 .\" index@report \s-1I/O\s+1 statistics@@@\f3iostat(1)\f1 .\" index@\s-1I/O\s+1 statistics, report@@@\f3iostat(1)\f1 .\" index@statistics, report \s-1I/O\s+1@@@\f3iostat(1)\f1 .\" .\" toc@\f3iostat(1)\f1:\0\0\f4iostat\f1@@@report \s-1I/O\s+1 statistics .\" $Header: ipcrm.1,v 72.5 94/11/14 15:19:23 ssa Exp $ .TA i .TH ipcrm 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ipcrm \- remove a message queue, semaphore set, or shared memory identifier .SH SYNOPSIS .CR ipcrm .RI [ option ]... .SH DESCRIPTION The .CR ipcrm command removes one or more specified message queue, semaphore set, or shared memory identifiers. .SS Options The identifiers are specified by the following .IR option s: .RS .TP 15 .CI -m \0shmid Remove the shared memory identifier .IR shmid from the system. The shared memory segment and data structure associated with it are destroyed after the last detach. .TP .CI -q \0msqid Remove the message queue identifier .IR msqid from the system and destroy the message queue and data structure associated with it. .TP .CI -s \0semid Remove the semaphore identifier .IR semid from the system and destroy the set of semaphores and data structure associated with it. .TP .CI -M \0shmkey Remove the shared memory identifier, created with key .IR shmkey , from the system. The shared memory segment and data structure associated with it are destroyed after the last detach. .TP .CI -Q \0msgkey Remove the message queue identifier, created with key .IR msgkey , from the system and destroy the message queue and data structure associated with it. .TP .CI -S \0semkey Remove the semaphore identifier, created with key .IR semkey , from the system and destroy the set of semaphores and data structure associated with it. .RE .PP The details of the removals are described in .CR msgctl (2), .CR shmctl (2), and .CR semctl (2). The identifiers and keys can be found by using .CR ipcs (see .CR ipcs (1)). .SH SEE ALSO ipcs(1), msgctl(2), msgget(2), msgop(2), semctl(2), semget(2), semop(2), shmctl(2), shmget(2), shmop(2). .SH STANDARDS CONFORMANCE .CR ipcrm ": SVID2, SVID3" .\" .\" toc@\f3ipcrm(1)\f1:\0\0\f4ipcrm\f1@@@remove a message queue, semaphore set or shared memory id .\" .\" index@\f4ipcrm\f1 \- remove a message queue, semaphore set, or shared memory identifier@@@\f3ipcrm(1)\f1 .\" index@remove a message queue, semaphore set, or shared memory identifier@@@\f3ipcrm(1)\f1 .\" index@message queue identifier, remove@@@\f3ipcrm(1)\f1 .\" index@semaphore set identifier, remove@@@\f3ipcrm(1)\f1 .\" index@shared memory identifier, remove@@@\f3ipcrm(1)\f1 .\" $Header: ipcs.1,v 72.8 94/11/14 15:19:24 ssa Exp $ .TA i .TH ipcs 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ipcs \- report status of interprocess communication facilities .SH SYNOPSIS .CR ipcs .RC [ -mqs ] .RC [ -abcopt ] .RC [ -C .IR corefile ] .RC [ -N .IR namelist ] .SH DESCRIPTION .CR ipcs displays certain information about active interprocess communication facilities. With no options, .RC ipcs displays information in short format for the message queues, shared memory segments, and semaphores that are currently active in the system. .SS Options The following options restrict the display to the corresponding facilities. .RS .TP 15 (none) This is equivalent to .CR -mqs . .TP .CR -m Display information about active shared memory segments. .TP .CR -q Display information about active message queues. .TP .CR -s Display information about active semaphores. .RE .PP The following options add columns of data to the display. See "Column Description" below. .RS .TP 15 (none) Display default columns: for all facilities: .CR T , .CR ID , .CR KEY , .CR MODE , .CR OWNER , .CR GROUP . .TP .CR -a Display all columns, as appropriate. This is equivalent to .CR -bcopt . .TP .CR -b Display largest-allowable-size information: for message queues: .CR QBYTES ; for shared memory segments: .CR SEGSZ ; for semaphores: .CR NSEMS . .TP .CR -c Display creator's login name and group name: for all facilities: .CR CREATOR , .CR CGROUP . .TP .CR -o Display information on outstanding usage: for message queues: .CR CBYTES , .CR QNUM ; for shared memory segments: .CR NATTCH . .TP .CR -p Display process number information: for message queues: .CR LSPID , .CR LRPID ; for shared memory segments: .CR CPID , .CR LPID . .TP .CR -t Display time information: for all facilities: .CR CTIME ; for message queues: .CR STIME , .CR RTIME ; for shared memory segments: .CR ATIME , .CR DTIME ; for semaphores: .CR OTIME . .RE .PP The following options redefine the sources of information. .RS .TP 15 .CI -C \0corefile Use file .IR corefile in place of .CR /dev/kmem . .TP .CI -N \0namelist Use file .IR namelist in place of .CR /stand/vmunix . .RE .SS Column Descriptions The column headings and the meaning of the columns in an .CR ipcs listing are given below. The columns are printed from left to right in the order shown below. .RS .ifn .TP 10 .ift .TP 15 .CR T Facility type: .RS .RS .TP .PD 0 .CR m Shared memory segment .TP .CR q Message queue .TP .CR s Semaphore .RE .RE .PD .TP .CR ID The identifier for the facility entry. .TP .CR KEY The key used as an argument to .CR msgget() , .CR semget() , or .CR shmget() to create the facility entry. (Note: The key of a shared memory segment is changed to .CR IPC_PRIVATE when the segment has been removed until all processes attached to the segment detach it.) .TP .CR MODE The facility access modes and flags: The mode consists of 11 characters that are interpreted as follows: .IP The first two characters can be: .RS .RS .TP .PD 0 .CR R A process is waiting on a .CR msgrcv() . .TP .CR S A process is waiting on a .CR msgsnd() . .TP .CR D The associated shared memory segment has been removed. It will disappear when the last process attached to the segment detaches it. .TP .CR C The associated shared memory segment is to be cleared when the first attach is executed. .TP .CR - The corresponding special flag is not set. .RE .RE .PD .IP The next 9 characters are interpreted as three sets of three characters each. The first set refers to the owner's permissions, the next to permissions of others in the group of the facility entry, and the last to all others. .IP Within each set, the first character indicates permission to read, the second character indicates permission to write or alter the facility entry, and the last character is currently unused. .RS .RS .TP .CR r Read permission is granted. .PD 0 .TP .CR w Write permission is granted. .TP .CR a Alter permission is granted. .TP .CR - The indicated permission is not granted. .PD .RE .RE .TP .CR OWNER The login name of the owner of the facility entry. .TP .CR GROUP The group name of the group of the owner of the facility entry. .TP .CR CREATOR The login name of the creator of the facility entry. .TP .CR CGROUP The group name of the group of the creator of the facility entry. .TP .CR CBYTES The number of bytes in messages currently outstanding on the associated message queue. .TP .CR QNUM The number of messages currently outstanding on the associated message queue. .TP .CR QBYTES The maximum number of bytes allowed in messages outstanding on the associated message queue. .TP .CR LSPID The process ID of the last process to send a message to the associated message queue. .TP .CR LRPID The process ID of the last process to receive a message from the associated message queue. .TP .CR STIME The time the last .CR msgsnd() message was sent to the associated message queue. .TP .CR RTIME The time the last .CR msgrcv() message was received from the associated message queue. .TP .CR CTIME The time when the associated facility entry was created or changed. .TP .CR NATTCH The number of processes attached to the associated shared memory segment. .TP .CR SEGSZ The size of the associated shared memory segment. .TP .CR CPID The process ID of the creating process of the shared memory segment. .TP .CR LPID The process ID of the last process to attach or detach the shared memory segment. .TP .CR ATIME The time the last .CR shmat() attach was completed to the associated shared memory segment. .TP .CR DTIME The time the last .CR shmdt() detach was completed on the associated shared memory segment. .TP .CR NSEMS The number of semaphores in the set associated with the semaphore entry. .TP .CR OTIME The time the last .CR semop() semaphore operation was completed on the set associated with the semaphore entry. .RE .SH WARNINGS .CR ipcs produces only an approximate indication of actual system status because system processes are continually changing while .CR ipcs is acquiring the requested information. .PP Do not rely on the exact field widths and spacing of the output, as these will vary depending on the system, the release of HP-UX, and the data to be displayed. .SH FILES .PD 0 .TP 20 .CR /dev/kmem Kernel virtual memory .TP .CR /etc/group Group names .TP .CR /etc/passwd User names .TP .CR /stand/vmunix System namelist .PD .SH SEE ALSO msgop(2), semop(2), shmop(2). .SH STANDARDS CONFORMANCE .CR ipcs ": SVID2, SVID3" .\" .\" index@\f1communication facilities, interprocess, report status@@@\f3ipcs(1)\f1 .\" index@\f1facilities, interprocess communication, report status@@@\f3ipcs(1)\f1 .\" index@\f1interprocess communication facilities, report status@@@\f3ipcs(1)\f1 .\" index@\f1message queues, report status@@@\f3ipcs(1)\f1 .\" index@\f1report status of interprocess communication facilities@@@\f3ipcs(1)\f1 .\" index@\f1semaphores, report status@@@\f3ipcs(1)\f1 .\" index@\f1shared memory segments, report status@@@\f3ipcs(1)\f1 .\" index@\f1status of interprocess communication facilities, report@@@\f3ipcs(1)\f1 .\" index@\f4ipcs\f1 \- report status of interprocess communication facilities@@@\f3ipcs(1)\f1 .\" .\" toc@\f3ipcs(1)\f1:\0\0\f4ipcs\f1@@@report status of interprocess communication facilities .\" $Header: sh-posix.1,v 76.4 95/11/02 14:15:41 ssa Exp $ .TA s .TH sh-posix 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sh, rsh \- standard and restricted POSIX.2-conformant command shells .SH SYNOPSIS .CR sh .RC [{ \- \(or + }\c .CR aefhikmnprstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [ \-c .IR string ] .IR arg ]...\& .PP .CR rsh .RC [{ \- \(or + }\c .CR aefhikmnprstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [ \-c .IR string ] .RI [ arg ]...\& .SS Remarks This shell is intended to conform to the shell specification of the POSIX.2 .I Shell and Utility standards. Check any standards conformance documents shipped with your system for information on the conformance of this shell to any other standards. .SS List of Subheadings in DESCRIPTION .\" .SS lines under DESCRIPTION (commands are vi/ex) .\" Extract header lines; copy to eof ":g/\.S[SH]/co$: .\" Delete extraneous leading and trailing headings .\" Delete .SS ":.,$s/....//" .\" Form into columns ":.,$!pr -3 -t -s@" .\" Replace pr tabs with blanks ":.,$s/[[:space:]]/ /g" .\" Move into place below. .TS tab(@); l l l . Shell Invocation@Tilde Substitution@Environment Options@Command Substitution@Functions rsh Restrictions@Parameter Substitution@Jobs Definitions@Blank Interpretation@Signals Commands@File Name Generation@Execution Simple Commands@Quoting@Command Reentry Compound Commands@Arithmetic Evaluation@Command Line Editing Special Commands@Prompting@emacs Editing Mode Comments@Conditional Expressions@vi Editing Mode Aliasing@Input/Output .TE .SH DESCRIPTION .CR sh is a command programming language that executes commands read from a terminal or a file. .PP .CR rsh is a restricted version of .CR sh . See the "rsh Restrictions" subsection below. .SS Shell Invocation If the shell is invoked by an .CI exec * () system call and the first character of argument zero (shell parameter .CR 0 ) is dash .RC ( \- ), the shell is assumed to be a login shell and commands are read first from .CR /etc/profile , then from either .CR .profile in the current directory or .CR $HOME/.profile if either file exists, and finally from the file named by performing parameter substitution on the value of the environment parameter .CR ENV , if the file exists. If the .CR \-s option is not present and an .I arg is, a path search is performed on the first .I arg to determine the name of the script to execute. When running .CR sh with .IR arg , the script .I arg must have read permission and any .CR setuid and .CR setgid settings will be ignored. Commands are read as described below. .PP Shell output, except for the output of some of the commands listed in the "Special Commands" subsection, is written to standard error (file descriptor 2). .SS Options The following options are interpreted by the shell when it is invoked. .TP 15 .CI \-c \0string Read commands from .IR string . .TP .CR \-i If .CR \-i is present or if the shell input and output are attached to a terminal (as reported by .CR tty() ), the shell is interactive. In this case .CR SIGTERM is ignored (so that .CR "kill 0" does not kill an interactive shell) and .CR SIGINT is caught and ignored (so that .CR wait is interruptible). In all cases, .CR SIGQUIT is ignored by the shell. See .IR signal (5). .TP .CR \-r The shell is a restricted shell. .TP .CR \-s If .CR \-s is present or if no arguments remain, commands are read from the standard input. .PP The remaining options and arguments are described under the .CR set command in the "Special Commands" subsection. .SS rsh Restrictions .CR rsh is used to set up login names and execution environments where capabilities are more controlled than those of the standard shell. The actions of .CR rsh are identical to those of .CR sh , except that the following are forbidden: .RS .TP 3 .PD 0 \(bu Changing directory (see the .CR cd special command and .IR cd (1)) .TP \(bu Setting the value of .CR SHELL , .CR ENV , or .CR PATH .TP \(bu Specifying path or command names containing .CR / .TP \(bu Redirecting output .RC ( > , .CR >| , .CR <> , and .CR >> ) .PD .RE .PP The restrictions above are enforced after the .CR .profile and .CR ENV files are interpreted. .PP When a command to be executed is found to be a shell procedure, .CR rsh invokes .CR sh to execute it. Thus, the end-user is provided with shell procedures accessible to the full power of the standard shell, while being restricted to a limited menu of commands. This scheme assumes that the end-user does not have write and execute permissions in the same directory. .PP These rules effectively give the writer of the .CR .profile file complete control over user actions, by performing guaranteed set-up actions and leaving the user in an appropriate directory (probably not the login directory). .PP The system administrator often sets up a directory of commands (usually .CR /usr/rbin ) that can be safely invoked by .CR rsh . HP-UX systems provide a restricted editor .CR red (see .IR ed (1)), suitable for restricted users. .SS Definitions .TP 20 .B metacharacter One of the following characters: .IP .CR "; & ( ) | < >" \0newline\0space\0tab .TP .B blank A tab or a space. .TP .B identifier A sequence of letters, digits, or underscores starting with a letter or underscore. Identifiers are used as names for .BR functions and .BR "named parameters" . .TP .B word A sequence of .B characters separated by one or more nonquoted .BR metacharacters . .TP .BR command A sequence of characters in the syntax of the shell language. The shell reads each command and carries out the desired action, either directly or by invoking separate utilities. .TP .B "special command" A command that is carried out by the shell without creating a separate process. Except for documented side effects, most special commands can be implemented as separate utilities. .TP .CR # Comment delimiter. A word beginning with .CR # and all following characters up to a newline are ignored. .TP .B parameter An .BR identifier , a decimal number, or one of the characters .CR ! , .CR # , .CR $ , .CR * , .CR \- , .CR ? , .CR @ , and .CR _ . See the "Parameter Substitution" subsection. .TP .B "named parameter" A .B parameter that can be assigned a value. See the "Parameter Substitution" subsection. .TP .B variable A .BR parameter . .TP .B "environment variable" A .BR parameter that is known outside the local shell, usually by means of the .CR export special command. .SS Commands A command can be a simple command that executes an executable file, a special command that executes within the shell, or a compound command that provides flow of control for groups of simple, special, and compound commands. .SS Simple Commands A simple command is a sequence of blank-separated words that may be preceded by a parameter assignment list. (See the "Environment" subsection). The first word specifies the name of the command to be executed. Except as specified below, the remaining words are passed as arguments to the invoked command. The command name is passed as argument .CR 0 (see .IR exec (2)). The .I value of a simple-command is its exit status if it terminates normally, or .CI 128+ errorstatus if it terminates abnormally (see .IR signal (5) for a list of .I errorstatus values). .PP A .B pipeline is a sequence of one or more commands separated by a bar .RC ( | ) and optionally preceded by an exclamation mark .RC ( ! ). The standard output of each command but the last is connected by a pipe (see .IR pipe (2)) to the standard input of the next command. Each command is run as a separate process; the shell waits for the last command to terminate. If .CR !\& does not precede the pipeline, the exit status of the pipeline is the exit status of the last command in the pipeline. Otherwise, the exit status of the pipeline is the logical negation of the exit status of the last command in the pipeline. .PP A .I list is a sequence of one or more pipelines separated by .CR ; , .CR & , .CR && , or .CR || , and optionally terminated by .CR ; , .CR & , or .CR |& . .RS .TP .CR ;\& Causes sequential execution of the preceding pipeline. An arbitrary number of newlines can appear in a .I list, instead of semicolons, to delimit commands. .TP .CR & Causes asynchronous execution of the preceding pipeline (that is, the shell does not wait for that pipeline to finish). .TP .CR |& Causes asynchronous execution of the preceding command or pipeline with a two-way pipe established to the parent shell. The standard input and output of the spawned command can be written to and read from by the parent shell using the .CR \-p option of the special commands .CR read and .CR print . .TP .CR && Causes the .I list following it to be executed only if the preceding pipeline returns a zero value. .TP .CR || Causes the .I list following it to be executed only if the preceding pipeline returns a nonzero value. .RE .PP Of these five symbols, .CR ; , .CR & , and .CR |& have equal precedence, which is lower than that of .CR && and .CR || . The symbols .CR && and .CR || also have equal precedence. .SS Compound Commands Unless otherwise stated, the value returned by a compound command is that of the last simple command executed in the compound command. The .CR ;\& segment separator can be replaced by one or more newlines. .PP The following keywords are recognized only as the first word of a command and when not quoted: .nf .RS .IP .C "! } elif for then" .C "[[ case else function time" .C "]] do esac if until" .C "{ done fi select while" .fi .RE .PP A compound command is one of the following. .PP .ne 3v .CR case \f2\0word\c .CR \0in \0[\|[ ; ]\0[ ( ]\c .IC \0pattern\0\f1[ | \0pattern\f1]... ) \0list\0\c .CR ;; ]...\0 ;\0esac .IP Execute the .I list associated with the first .I pattern that matches .IR word . The form of the patterns is identical to that used for file name generation (see the "File Name Generation" subsection). The .CR ;;\& case terminator cannot be replaced by newlines. .PP .ne 3v .CI for \0identifier\f1\0[ in \0word\f1\0...]\0\c .CR ;\0do \0\f2list\0 ;\0done .IP Set .I identifier to each .I word in sequence and execute the .CR do .IR list . If .CR in .IR word .RI ...\& is omitted, set .I identifier to each set positional parameter instead. See the "Parameter Substitution" subsection. Execution ends when there are no more positional parameters or words in the list. .PP .ne 4v .CI function \0identifier\0 { \0list\0 ;\0} .br .IC identifier \0()\0{ \0list\0 ;\0} .IP Define a function named by .IR identifier . A function is called by executing its identifier as a command. The body of the function is the .I list of commands between .CR { and .CR } . See the "Functions" subsection. .PP .ne 3v .CI if \0list\0 ;\0then \0list\0 ; \0\f1[\c .CI elif \0list\0 ;\0then \0list\0 ; \f1]...\&\0[\c .CI else \0list\0 ; \f1]\0 fi .IP Execute the .CR if .I list and, if its exit status is zero, execute the first .CR then .IR list . Otherwise, execute the .CR elif .I list (if any) and, if its exit status is zero, execute the next .CR then .IR list . Failing that, execute the .CR else .I list (if any). If no .CR else .I list or .CR then .I list is executed, .CR if returns a zero exit status. .PP .ne 3v .CI select \0identifier\0\f1[ in \0word\f1\0...\&]\0 ;\0do \0list\0\c .CI ;\0done .IP Print the set of .IR word s on standard error (file descriptor 2), each preceded by a number. If .CI in .IR word .RI ...\& is omitted, print the positional parameters instead (see the "Parameter Substitution" subsection). Print the .CR PS3 prompt and read a line from standard input into the parameter .CR REPLY . If this line consists of the number of one of the listed .IR word s, set .I identifier to the corresponding .IR word , execute .IR list , and repeat the .CR PS3 prompt. If the line is empty, print the selection list again, and repeat the .CR PS3 prompt. Otherwise, set .I identifier to null, execute .IR list , and repeat the .CR PS3 prompt. The select loop repeats until a .CR break special command or end-of-file is encountered. .PP .ne 3v .CI time \0pipeline .IP Execute the .I pipeline and print the elapsed time, the user time, and the system time on standard error. See also .IR time (1). .PP .ne 3v .CI "until\0" list "\0;\0do\0" list "\0;\0done" .IP Execute the .CR until .IR list . If the exit status of the last command in the list is nonzero, execute the .CR do .IR list and execute the .CR until .IR list again. When the exit status of the last command in the .CR until .I list is zero, terminate the loop. If no commands in the .CR do .I list are executed, .CR until returns a zero exit status. .PP .ne 3v .CI "while\0" list "\0;\0do\0" list "\0;\0done" .IP Execute the .CR while .IR list . If the exit status of the last command in the list is zero, execute the .CR do .IR list and execute the .CR while .IR list again. When the exit status of the last command in the .CR while .I list is nonzero, terminate the loop. If no commands in the .CR do .I list are executed, .CR while returns a nonzero exit status. .PP .ne 3v .CI ( "\0list\0" ) .IP Execute .I list in a separate environment. If two adjacent open parentheses are needed for nesting, a space must be inserted between them to avoid arithmetic evaluation. .PP .ne 3v .CI { "\0list\0" ";\0}" .IP Execute .IR list , but not in a separate environment. Note that .CR { is a keyword and requires a trailing blank to be recognized. .PP .ne 3v .CI [[ "\0expression\0" ]] .IP Evaluate .I expression and return a zero exit status when .I expression is true. See the "Conditional Expressions" subsection for a description of .IR expression . Note that .CR [[ and .CR ]] are keywords and require blanks between them and .IR expression . .SS Special Commands Special commands are simple commands that are executed in the shell process. They permit input/output redirection. Unless otherwise indicated, file descriptor 1 (standard output) is the default output location and the exit status, when there are no syntax errors, is zero. .PP Commands that are marked with \(dg or \(dg\(dg are treated specially in the following ways: .RS .TP 3 .PD 0 1. Variable assignment lists preceding the command remain in effect when the command completes. .TP 2. I/O redirections are processed after variable assignments. .TP 3. Errors cause a script that contains them to abort. .TP 4. Words following a command preceded by \(dg\(dg that are in the format of a variable assignment are expanded with the same rules as a variable assignment. This means that tilde substitution is performed after the .CR = sign and word-splitting and file-name generation are not performed. .PD .RE .PP .ne 3v \(dg .CR : \0[\f2arg\f1]...\& .IP (colon)\0 Only expand parameters. A zero exit status is returned. .PP .ne 3v \(dg .CI . \0file\f1\0[\f2arg\f1]...\& .IP (period)\0 Read and execute commands from .I file and return. The commands are executed in the current shell environment. The search path specified by .CR PATH is used to find the directory containing .IR file . If any arguments .I arg are given, they become the positional parameters. Otherwise, the positional parameters are unchanged. The exit status is the exit status of the last command executed. .PP .ne 3v \(dg\(dg .CR alias \0[ \-tx ]\0[\f2name\f1[\c .CI = value\f1]\|]...\& .IP With .IC name = value specified, define .I name as an alias and assign it the value .IR value . A trailing space in .I value causes the next word to be checked for alias substitution. .IP With .IC name = value omitted, print the list of aliases in the form .IC name = value on standard output. .IP With .I name specified without .CI = value\f1, print the specified alias. .IP With .CR \-t , set tracked aliases. The value of a tracked alias is the full path name corresponding to the given .IR name . The value of a tracked alias becomes undefined when the value of .CR PATH is reset, but the alias remains tracked. With .IC name = value omitted, print the list of tracked aliases in the form .IC name = pathname on standard output. .IP With .CR \-x , set exported aliases. An exported alias is defined across subshell environments. With .IC name = value omitted, print the list of exported aliases in the form .IC name = value on standard output. .IP Alias returns true unless a .I name is given for which no alias has been defined. .PP .ne 3v .CR bg \0[\f2job\f1]...\& .IP Put the specified .I jobs into the background. The current job is put in the background if .I job is unspecified. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v \(dg .CR break \0[\f2n\f1] .IP Exit from the enclosing .CR for , .CR select , .CR until , or .CR while loop, if any. If .I n is specified, exit from .I n levels. .PP .ne 4v .CR cd \0[ \-L \(or \-P ]\0[\f2arg\f1] .br .CI cd \0old\0new .IP In the first form, change the current working directory .RC ( PWD ) to .IR arg . If .I arg is .CR \- , the directory is changed to the previous directory .RC ( OLDPWD ). .IP With .CR \-L (default), preserve logical naming when treating symbolic links. .CR "cd \-L ..\&" moves the current directory one path component closer to the root directory. .IP With .CR \-P , preserve the physical path when treating symbolic links. .CR "cd \-P ..\&" changes the working directory to the actual parent directory of the current directory. .IP The shell parameter .CR HOME is the default .IR arg . The parameter .CR PWD is set to the current directory. .IP The shell parameter .CR CDPATH defines the search path for the directory containing .IR arg . Alternative directory names are separated by a colon .RC ( : ). If .CR CDPATH is null or undefined, the default value is the current directory. Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If .I arg begins with a .CR / , the search path is not used. Otherwise, each directory in the path is searched for .IR arg . See also .IR cd (1). .IP The second form of .CR cd substitutes the string .I new for the string .I old in the current directory name, .CR PWD , and tries to change to this new directory. .PP .ne 3v .CR command \0[\f2arg\f1]...\& .IP Treat .I arg as a command, but disable function lookup on .IR arg . See .IR command (1) for usage and description. .PP .ne 3v \(dg .CR continue \0[\f2n\f1] .IP Resume the next iteration of the enclosing .CR for , .CR select , .CR until , or .CR while loop. If .I n is specified, resume at the .IR n th enclosing loop. .PP .ne 3v .CR echo \0[\f2arg\f1]...\& .IP Print .I arg on standard output. See .IR echo (1) for usage and description. See also the .CR print special command. .PP .ne 3v \(dg .CR eval \0[\f2arg\f1]...\& .IP Read the arguments as input to the shell and execute the resulting commands. Allows parameter substitution for keywords and characters that would otherwise be unrecognized in the resulting commands. .PP .ne 3v \(dg .CR exec \0[\f2arg\f1]...\& .IP Parameter assignments remain in effect after the command completes. If .I arg is given, execute the command specified by the arguments in place of this shell without creating a new process. Input/output arguments may appear and affect the current process. If no arguments are given, modify file descriptors as prescribed by the input/output redirection list. In this case, any file descriptor numbers greater than 2 that are opened with this mechanism are closed when another program is invoked. .PP .ne 3v \(dg .CR exit \0[\f2n\f1] .IP Exit from the shell with the exit status specified by .IR n . If .I n is omitted, the exit status is that of the last command executed. An end-of-file also causes the shell to exit, except when a shell has the .CR ignoreeof option set. (See the .CR set special command.) .PP .ne 4v \(dg\(dg .CR export \0[\f2name\f1[ = \f2value\f1]\|]...\& .br \(dg\(dg .CR export\0\-p .IP Mark the given variable .IR name s for automatic export to the environment of subsequently executed commands. Optionally, assign values to the variables. .IP With .CR \-p , write the names and values of all exported variables to standard output, in a format with the proper use of quoting, so that it is suitable for re-input to the shell as commands that achieve the same exporting results. .PP .ne 6v .CR fc \0[ \-r ]\0[ \-e \0\f2ename\f1]\0[\f2first\f1\0[\f2last\f1]\|] .br .CR fc\0\-l \0[ \-nr ]\0[\f2first\f1\0[\f2last\f1]\|] .br .CR fc\0\-s \0[\f2old\f1 = \f2new\f1]\0[\f2first] .br .CR fc\0\-e\0\- \0[\f2old\f1 = \f2new\f1]\0[\f2command\f1] .IP List, or edit and reexecute, commands previously entered to an interactive shell. A range of commands from .I first to .I last is selected from the last .CR HISTSIZE commands typed at the terminal. The arguments .I first and .I last can be specified as a number or string. A given string is used to locate the most recent command. A negative number is used to offset the current command number. .IP With .CR \-l , list the commands on standard output. Without .CR \-l , invoke the editor program .I ename on a file containing these keyboard commands. If .I ename is not supplied, the value of the parameter .CR FCEDIT (default .CR /usr/bin/ed ) is used as the editor. Once editing has ended, the commands (if any) are executed. If .I last is omitted, only the command specified by .I first is used. If .I first is not specified, the default is the previous command for editing and \(mi16 for listing. .IP With .CR \-r , reverse the order of the commands. .IP With .CR \-n , suppress command numbers when listing. .IP With .CR \-s , reexecute the command without invoking an editor. .IP The .IC old = new argument replaces the first occurrence of string .IC old in the command to be reexecuted by the string .IR new . .PP .ne 3v .CR fg \0[\f2job\f1]...\& .IP Bring each .I job into the foreground in the order specified. If no .I job is specified, bring the current job into the foreground. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v .CR getopts \0\f2optstring\0name\f1\0[\f2arg\f1]...\& .IP Parse the argument list, or the positional parameters if no arguments, for valid options. On each execution, return the next option in .IR name . See .IR getopts (1) for usage and description. .IP An option begins with a .CR + or a .CR \- . An argument not beginning with .CR + or .CR \- , or the argument .CR \-\- , ends the options. .I optstring contains the letters that .CR getopts recognizes. If a letter is followed by a .CR : , that option is expected to have an argument. The options can be separated from the argument by blanks. .IP For an option specified as .CI \- letter\f1, .I name is set to .IR letter . For an option specified as .CI + letter\f1, .I name is set to .CI + letter\f1. The index of the next .I arg is stored in .CR OPTIND . The option argument, if any, is stored in .CR OPTARG . If no option argument is found, or the option found does not take an argument, .CR OPTARG is unset. .IP A leading .CR :\& in .I optstring causes .CR getopts to store the letter of an invalid option in .CR OPTARG , and to set .I name to .CR ?\& for an unknown option and to .CR :\& when a required option argument is missing. Otherwise, .CR getopts prints an error message. The exit status is nonzero when there are no more options. .PP .ne 4v .CR hash \0[\f2utility\f1]...\& .br .CR hash\0\-r .IP Affect the way the current shell environment remembers the locations of utilities. With .IR utility , add utility locations to a list of remembered locations. With no arguments, print the contents of the list. With .CR \-r , forget all previously remembered utility locations. .PP .ne 3v .CR jobs \0[ \-lnp ]\0[\f2job\f1]...\& .IP List information about each given job, or all active jobs if .I job is not specified. With .CR \-l , list process IDs in addition to the normal information. With .CR \-n , display only jobs that have stopped or exited since last notified. With .CR \-p , list only the process group. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 5v .CR kill \0[ \-s \0\f2signal\f1]\0\f2process\f1\0...\& .br .CR kill\0\-l .br .CR kill \0[ \- \f2signal\f1]\0\f2process\f1\0...\& .IP Send either signal 15 .RC ( SIGTERM , terminate) or the specified .I signal to the specified jobs or processes. See .IR kill (1) for usage and description. .IP With .CR \-l , list the signal names and numbers. .PP .ne 4v .CI let \0arg\f1\0... .br .CI (( \0arg\f1\0... )) .IP Evaluate each .I arg as a separate arithmetic expression. See the "Arithmetic Evaluation" subsection for a description of arithmetic expression evaluation. The exit status is 0 if the value of the last expression is nonzero, and 1 otherwise. .PP .ne 3v \(dg .CR newgrp \0[ \- ]\0[\f2group\f1] .IP Replace the current shell with a new one having .I group as the user's group. The default group is the user's login group. With .CR \- , the user's .CR .profile and .CR $ENV files are also executed. See .IR newgrp (1) for usage and description. Equivalent to .CI "exec\0newgrp" "\0arg\0\f1...." .PP .ne 3v .CR print \0[ \-nprRsu [\f2n\f1]\|]\0[\f2arg\f1]...\& .IP The shell output mechanism. With no options or with option .CR \- or .CR \-\- , print the arguments on standard output as described in .IR echo (1). See also .IR printf (1). .IP With .CR \-n , do not add a newline character to the output. .IP With .CR \-p , write the arguments onto the pipe of the process spawned with .CR |& instead of standard output. .IP With .CR \-R or .CR \-r (raw mode), ignore the escape conventions of .CR echo . With .CR \-R , print all subsequent arguments and options other than .CR \-n . .IP With .CR \-s , write the arguments into the history file instead of to standard output. .IP With .CR \-u , specify a one-digit file descriptor unit number .I n on which the output will be placed. The default is .CR 1 (standard output). .PP .ne 3v .CR pwd \0[ \-L \(or \-P ] .IP Print the name of the current working directory (equivalent to .CR "print\0\-r\0\-\0$PWD" ). With .CR \-L (the default), preserve the logical meaning of the current directory. With .CR \-P , preserve the physical meaning of the current directory if it is a symbolic link. See also the .CR cd special command, .IR cd (1), .IR ln (1), and .IR pwd (1). .PP .ne 3v .CR read \0[ \-prsu [\f2n\f1]\|]\0[\f2name\f1 ? \f2prompt\f1]\0[\f2name\f1]...\& .IP The shell input mechanism. Read one line (by default, from standard input) and break it up into words using the characters in .CR IFS as separators. The first word is assigned to the first .IR name , the second word to the second .IR name , and so on; the remaining words are assigned to the last .IR name . See also .IR read (1). The return code is .CR 0 , unless an end-of-file is encountered. .IP With .CR \-p , take the input line from the input pipe of a process spawned by the shell using .CR |& . An end-of-file with .CR \-p causes cleanup for this process so that another process can be spawned. .IP With .CR \-r (raw mode), a .CR \e at the end of a line does not signify line continuation. .IP With .CR \-s , save the input as a command in the history file. .IP With .CR \-u , specify a one-digit file descriptor unit to read from. The file descriptor can be opened with the .CR exec special command. The default value of .I n is .CR 0 (standard input). If .IR name is omitted, .CR REPLY is used as the default .IR name . .IP If the first argument contains a .CR ? , the remainder of the argument is used as a .I prompt when the shell is interactive. .IP If the given file descriptor is open for writing and is a terminal device, the prompt is placed on that unit. Otherwise, the prompt is issued on file descriptor 2 (standard error). .PP .ne 4v \(dg\(dg .CR readonly \0[\f2name\f1[ = \f2value\f1]\|]...\& .br \(dg\(dg .CR readonly\0\-p .IP Mark the given .IR name s read only. These names cannot be changed by subsequent assignment. .IP With .CR \-p , write the names and values of all read-only variables to standard output in a format with the proper use of quoting so that it is suitable for re-input to the shell as commands that achieve the same attribute-setting results. .PP .ne 3v \(dg .CR return \0[\f2n\f1] .IP Cause a shell function to return to the invoking script with the return status specified by .IR n . If .I n is omitted, the return status is that of the last command executed. Only the low 8 bits of .I n (decimal 0 to 255) are passed back to the caller. If .CR return is invoked while not in a function or a .CR .\& script (see the .CR .\& special command), it has the same effect as an .CR exit command. .PP .ne 3v .CR set .RC [{ \- \(or + }\c .CR abCefhkmnopstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [{ \- \(or + } A .IR name ]\0[ arg ]...\& .IP Set .RC ( \- ) or clear .RC ( + ) execution options or perform array assignments .RC ( \-A ,\ +A ). All options except .CR \-A and .CR +A can be supplied in a shell invocation (see the SYNOPSIS section and the "Shell Invocation" subsection). .IP Using .CR + instead of .CR \- before an option causes the option to be turned off. These options can also be used when invoking the shell. The current list of set single-letter options is contained in the shell variable .CR \- . It can be examined with the command .CR "echo $-" . .IP The .CR \- and .CR + options can be intermixed in the same command, except that there can be only one .CR \-A or .CR +A option. .IP Unless .CR \-A or .CR +A is specified, the remaining .I arg arguments are assigned consecutively to the positional parameters .CR 1 , .CR 2 ,\0.... .IP The .CR set command with neither arguments nor options displays the names and values of all shell parameters on standard output. See also .IR env (1). .IP The options are defined as follows. .RS .TP .CR \-A Array assignment. Unset the variable .I name and assign values sequentially from the list .IR arg . With .CR \+A , do not unset the variable .I name first. .TP .CR \-a Automatically export subsequently defined parameters. .TP .CR \-b Cause the shell to notify the user asynchronously of background jobs as they are completed. When the shell notifies the user that a job has been completed, it can remove the job's process ID from the list of those known in the current shell execution environment. .TP .CR \-C Prevent redirection .CR > from truncating existing files. Requires .CR >| to truncate a file when turned on. .TP .CR \-e Execute the .CR ERR trap, if set, and exit .I if a command has a nonzero exit status, and is not part of the compound list following a .CR if , .CR until , or .CR while keyword, and is not part of an AND or OR list, and is not a pipeline preceded by the .CR !\& reserved word. This mode is disabled while reading profiles. .TP .CR \-f Disable file name generation. .TP .CR \-h Specify that each command whose name is an .I identifier becomes a tracked alias when first encountered. .TP .CR \-k Place all parameter assignment arguments (not just those that precede the command name) into the environment for a command. .TP .CR \-m Run background jobs in a separate process group and print a line upon completion. The exit status of background jobs is reported in a completion message. This option is turned on automatically for interactive shells. .TP .CR \-n Read commands and check them for syntax errors, but do not execute them. The .CR \-n option is ignored for interactive shells. .TP .ne 5v .CR \-o Set an .I option argument from the following list. Repeat the .CR \-o option to specify additional .I option arguments. .RS .TP 15 .PD 0 .CR allexport Same as .CR \-a . .TP .CR bgnice Run all background jobs at a lower priority. .TP .CR errexit Same as .CR \-e . .TP .CR emacs Use a .CR emacs -style inline editor for command entry. .TP .CR gmacs Use a .CR gmacs -style inline editor for command entry. .TP .CR ignoreeof Do not exit from the shell on end-of-file .RI ( eof as defined by .CR stty ; default is .CR ^D ). The .CR exit special command must be used. .TP .CR keyword Same as .CR \-k . .TP .CR markdirs Append a trailing .CR / to all directory names resulting from file name generation. .TP .CR monitor Same as .CR \-m . .TP .CR noclobber Same as .CR \-C . .TP .CR noexec Same as .CR \-n . .TP .CR noglob Same as .CR \-f . .TP .CR nolog Do not save function definitions in history file. .TP .CR notify Same as .CR \-b . .TP .CR nounset Same as .CR \-u . .TP .CR privileged Same as .CR \-p . .TP .CR verbose Same as .CR \-v . .TP .CR trackall Same as .CR \-h . .TP .CR vi Use a .CR vi -style inline editor for command entry. .TP .CR viraw Process each character as it is typed in .CR vi mode. .TP .CR xtrace Same as .CR \-x . .PD .RE .TP .CR \-p Disable processing of the .CR $HOME/.profile file and uses the file .CR /etc/suid_profile instead of the .CR ENV file. This mode is on whenever the effective user ID (group ID) is not equal to the real user ID (group ID). Turning this off causes the effective user ID and group ID to be set to the real user ID and group ID. .TP .CR \-s Sort the positional parameters. .TP .CR \-t Exit after reading and executing one command. .TP .CR \-u Treat unset parameters as an error when substituting. .TP .CR \-v Print shell input lines as they are read. .TP .CR \-x Print commands and their arguments as they are executed. .TP .CR \- Turn off .CR \-x and .CR \-v options and stop examining arguments for options. .TP .CR \-\- Do not change any of the options; useful in setting parameter .CR 1 to a value beginning with .CR \- . If no arguments follow this option, the positional parameters are unset. .RE .PP .ne 3v \(dg .CR shift "\0[\f2n\f1]" .IP Rename the positional parameters from .IC n +1 \f1\0...\& to .CR 1 \0.... The default value of .I n is .CR 1 . .I n can be any arithmetic expression that evaluates to a nonnegative number less than or equal to .CR $# . .PP .ne 3v .CR test \0[\f2expr\f1] .IP Evaluate conditional expression .IR expr . See .IR test (1) for usage and description. The arithmetic comparison operators are not restricted to integers. They allow any arithmetic expression. The following additional primitive expressions are allowed: .RS .TP 20 .PD 0 .CI \-L \0file True if .I file is a symbolic link. .TP .CI \-e \0file True if .I file exists. .TP .IC file1\0 \-nt \0file2 True if .I file1 is newer than .IR file2 . .TP .IC file1\0 \-ot \0file2 True if .I file1 is older than .IR file2 . .TP .IC file1\0 \-ef \0file2 True if .I file1 has the same device and i-node number as .IR file2 . .PD .RE .PP .ne 3v \(dg .CR times .IP Print the accumulated user and system times for the shell and for processes run from the shell. .PP .ne 3v \(dg .CR trap \0[\f2arg\f1]\0[\f2sig\f1]...\& .IP Set .I arg as a command that is read and executed when the shell receives a .IR sig signal. (Note that .I arg is scanned once when the trap is set and once when the trap is taken.) Each .I sig can be given as the number or name of a signal. Letter case is ignored. For example, .CR 3 , .CR QUIT , .CR quit , and .CR SIGQUIT all specify the same signal. Use .CR "kill \-l" to get a list of signals. .IP Trap commands are executed in signal number order. Any attempt to set a trap on a signal that was ignored upon entering the current shell is ineffective. .IP If .I arg is .CR \- (or if .I arg is omitted and the first .I sig is numeric), reset all traps for each .I sig to their original values. .IP If .I arg is the null string .RC ( '' or \&\c .C """""\c" ), each .I sig is ignored by the shell and by the commands it invokes. .IP If .I sig is .CR DEBUG , then .I arg is executed after each command. If .I sig is .CR ERR , .I arg is executed whenever a command has a nonzero exit code. If .I sig is .CR 0 or .CR EXIT and the .CR trap statement is executed inside the body of a function, the command .I arg is executed after the function completes. If .I sig is .CR 0 or .CR EXIT for a .CR trap set outside any function, the command .I arg is executed on exit from the shell. .IP With no arguments, print a list of commands associated with each signal name. .PP .ne 4v \(dg\(dg .CR typeset \0[{ \- \(or + }\c .CR LRZfilrtux [\f2n\f1]\|]\0[\f2name\f1[ = \f2value\f1]\|]... .br \(dg\(dg .IC name = value .RC [\f2name = \f2value\f1]...\& .IP Assign types and a value to a local named parameter .IR name . See also the .CR export special command. Parameter assignments remain in effect after the command completes. When invoked inside a function, create a new instance of the parameter .IR name . The parameter value and type are restored when the function completes. .IP The following list of attributes can be specified. Use .CR \+ instead of .CR \- to turn the options off. .RS .TP .CR \-L Left justify and remove leading blanks from .IR value . If .I n is nonzero, it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. When .I name is assigned, the value is filled on the right with blanks or truncated, if necessary, to fit into the field. Leading zeros are removed if the .CR \-Z option is also set. The .CR \-R option is turned off. Flagged as .CI leftjust \0n\f1. .TP .CR \-R Right justify and fill with leading blanks. If .I n is nonzero, it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. The field is left-filled with blanks or truncated from the end if the parameter is reassigned. The .CR \-L option is turned off. Flagged as .CI rightjust \0n\f1. .TP .CR \-Z Right justify and fill with leading zeros if the first nonblank character is a digit and the .CR \-L option has not been set. If .I n is nonzero it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. Flagged as .CI zerofill \0n\f1 plus the flag for .CR \-L or .CR \-R . .TP .CR \-f Cause .I name to refer to function names rather than parameter names. No assignments can be made to the .I name declared with the .CR typeset statement. The only other valid options are .CR \-t (which turns on execution tracing for this function) and .CR \-x (which allows the function to remain in effect across shell procedures executed in the same process environment). Flagged as .CR function . .TP .CR \-i Parameter is an integer. This makes arithmetic faster. If .I n is nonzero it defines the output arithmetic base; otherwise, the first assignment determines the output base. Flagged as .CR integer \0[ base \0\f2n\f1]. .TP .CR \-l Convert all uppercase characters to lowercase. The uppercase .CR \-u option is turned off. Flagged as .CR lowercase . .TP .CR \-r Mark any given .I name as "read only". The name cannot be changed by subsequent assignment. Flagged as .CR readonly . .TP .CR \-t Tag the named parameters. Tags are user-definable and have no special meaning to the shell. Flagged as .CR tagged . .TP .CR \-u Convert all lowercase characters to uppercase characters. The lowercase .CR \-l option is turned off. Flagged as .CR uppercase . .TP .CR \-x Mark any given .I name for automatic export to the environment of subsequently executed commands. Flagged as .CR export . .RE .IP .CR typeset alone displays a list of parameter names, prefixed by any flags specified above. .IP .CR "typeset \-" displays the parameter names followed by their values. Specify one or more of the option letters to restrict the list. Some options are incompatible with others. .IP .CR "typeset +" displays the parameter names alone. Specify one or more of the option letters to restrict the list. Some options are incompatible with others. .PP .ne 3v .CR ulimit \0[ \-HSacdfnst ]\0[\f2limit\f1] .IP Set or display a resource limit. The limit for a specified resource is set when .IR limit is specified. The value of .IR limit can be a number in the unit specified with each resource, or the keyword .CR unlimited . .IP The .CR \-H and .CR \-S flags specify whether the hard limit or the soft limit is set for the given resource. A hard limit cannot be increased once it is set. A soft limit can be increased up to the hard limit. If neither .CR \-H nor .CR \-S is specified, the limit applies to both. The current resource limit is printed when .IR limit is omitted. In this case, the soft limit is printed unless .CR \-H is specified. When more than one resource is specified, the limit name and unit are printed before the value. .IP If no option is given, .CR \-f is assumed. .RS .TP .PD 0 .CR \-a List all of the current resource limits. .TP .CR \-c The number of 512-byte blocks in the size of core dumps. .TP .CR \-d The number of kilobytes in the size of the data area. .TP .CR \-f The number of 512-byte blocks in files written by child processes (files of any size can be read). .TP .CR \-n The number of file descriptors. .TP .CR \-s The number of kilobytes in the size of the stack area. .TP .CR \-t The number of seconds to be used by each process. .PD .RE .PP .ne 3v .CR umask \0[ \-S ]\0[\f2mask\f1] .IP Set the user file-creation mask .IR mask . .I mask can be either an octal number or a symbolic value as described in .IR umask (1). A symbolic value shows permissions that are unmasked. An octal value shows permissions that are masked off. .IP Without .I mask , print the current value of the mask. With .CR \-S , print the value in symbolic format. Without .CR \-S , print the value as an octal number. The output from either form can be used as the .I mask of a subsequent invocation of .CR umask . .PP .ne 4v .CI unalias \0name\f1\0...\& .br .CR unalias\0\-a .IP Remove each .IR name from the alias list. With .CR \-a , remove all .CR alias definitions from the current shell execution environment. .PP .ne 3v .CR unset \0[ \-fv ]\0\f2name\f1\0...\& .IP Remove the named shell parameters from the parameter list. Their values and attributes are erased. Read-only variables cannot be unset. With .CR \-f , .IR name s refer to function names. With .CR \-v , .IR name s refer to variable names. Unsetting .CR _ , .CR ERRNO , .CR LINENO , .CR MAILCHECK , .CR OPTARG , .CR OPTIND , .CR RANDOM , .CR SECONDS , and .CR TMOUT removes their special meaning, even if they are subsequently assigned to. .PP .ne 3v \(dg .CR wait \0[\f2job\f1] .IP Wait for the specified .I job to terminate or stop, and report its status. This status becomes the return code for the .CR wait command. Without .I job , wait for all currently active child processes to terminate or stop. The termination status returned is that of the last process. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v .CR whence \0[ \-pv ]\0\f2name\f1\0...\& .IP For each .IR name , indicate how it would be interpreted if used as a command name. With .CR \-v , produce a more verbose report. With .CR \-p do a path search for .IR name , disregarding any use as an alias, a function, or a reserved word. .SS Comments A .I word beginning with .CR # causes that word and all the following characters up to a newline to be ignored. .SS Aliasing The first word of each command is replaced by the text of an .CR alias , if an .CR alias for this word has been defined. An .CR alias name consists of any number of characters excluding metacharacters, quoting characters, file expansion characters, parameter and command substitution characters, and =. The replacement string can contain any valid shell script, including the metacharacters listed above. The first word of each command in the replaced text, other than any that are in the process of being replaced, will be tested for additional aliases. If the last character of the alias value is a .IR blank , the word following the alias is also checked for alias substitution. Aliases can be used to redefine special commands, but cannot be used to redefine the keywords listed in the "Compound Commands" subsection. Aliases can be created, listed, and exported with the .CR alias command and can be removed with the .CR unalias command. Exported aliases remain in effect for subshells but must be reinitialized for separate invocations of the shell (see the "Shell Invocation" subsection). .PP Aliasing is performed when scripts are read, not while they are executed. Therefore, for it to take effect, an .CR alias must be executed before the command referring to the alias is read. .PP Aliases are frequently used as a shorthand for full path names. An option to the aliasing facility allows the value of the alias to be automatically set to the full path name of the corresponding command. These aliases are called .I tracked aliases. The value of a .I tracked alias is defined the first time the identifier is read and becomes undefined each time the .CR PATH variable is reset. These aliases remain .I tracked so that the next reference will redefine the value. Several tracked aliases are compiled into the shell. The .CR \-h option of the .CR set command converts each command name that is an .I identifier into a tracked alias. .PP The following .I exported aliases are compiled into the shell but can be unset or redefined: .nf .IP .C autoload='typeset \-fu' .C command='command ' .C functions='typeset \-f' .C history='fc \-l' .C integer='typeset \-i' .C local=typeset .C nohup='nohup ' .C r='fc \-e \-' .C stop='kill \-STOP' .C suspend='kill \-STOP $$' .C type='whence \-v' .SS Tilde Substitution After alias substitution is performed, each word is checked to see if it begins with an unquoted tilde .RC ( ~ ). If it does, the word up to a .CR / is checked to see if it matches a user name in the .CR /etc/passwd file. If a match is found, the .CR ~ and the matched login name are replaced by the login directory of the matched user. If no match is found, the original text is left unchanged. A .CR ~ alone or before a .CR / is replaced by the value of the .CR HOME parameter. A .CR ~ followed by a .CR + or .CR \- is replaced by the value of the parameter .CR PWD and .CR OLDPWD , respectively. In addition, tilde substitution is attempted when the value of a parameter assignment begins with a .CR ~ . .SS Command Substitution The standard output from a command enclosed in parenthesis preceded by a dollar sign .RC ( $( ...\& ) ) or a pair of grave accents .RC ( ` ...\& ` ) can be used as part or all of a word; trailing newlines are removed. In the second (archaic) form, the string between the accents is processed for special quoting characters before the command is executed. See the "Quoting" subsection. The command substitution .CR "$(cat file)" can be replaced by the equivalent but faster .CR $(\0\c ". .TP .CR PS3 Selection prompt string used within a .CR select loop. If unset, it defaults to "\c .CR #?\0\c ". .TP .CR PS4 Execution trace string that precedes each line of an execution trace. See the .CR "set \-x" special command. If unset, it defaults to "\c .CR +\0\c ". .TP .CR SHELL The path name of the shell is kept in the environment. When invoked, the shell is restricted if the value of this variable contains an .CR r in the base name. .TP .CR TMOUT If set to a value greater than zero, the shell will terminate if a command is not entered within the prescribed number of seconds after issuing the .CR PS1 prompt. (Note that the shell can be compiled with a maximum bound for this value which cannot be exceeded.) .TP .CR VISUAL Invokes the corresponding option when the value of this variable ends in .CR emacs , .CR gmacs , or .CR vi . See the .CR "set \-o" special command. .PP The shell gives default values to .CR IFS , .CR MAILCHECK , .CR PATH , .CR PS1 , .CR PS2 , and .CR TMOUT . On the other hand, .CR MAIL , .CR ENV , .CR HOME , and .CR SHELL are never set automatically by the shell (although .CR HOME , .CR MAIL , and .CR SHELL are set by .CR login ; see .IR login (1)). .SS Blank Interpretation After parameter and command substitution, the results of substitution are scanned for field separator characters (defined in .CR IFS ), and split into distinct arguments when such characters are found. .CR sh retains explicit null arguments (\c .C """""" or .CR '' ) but removes implicit null arguments (those resulting from parameters that have null values). .SS File Name Generation Following substitution, each command .I word is processed as a pattern for file name expansion unless expansion has been disabled with the .CR "set \-f" special command. The form of the patterns is the Pattern Matching Notation defined in .IR regexp (5). The word is replaced with sorted file names matching the pattern. If no file name is found that matches the pattern, the word is left unchanged. .PP In addition to the notation described in .IR regexp (5), .CR sh recognizes composite patterns made up of one or more pattern lists separated from each other with a .CR | . Composite patterns can be formed with one or more of the following: .RS .TP 18 .PD 0 .CI ?( pattern-list ) Matches any one of the given patterns. .TP .CI *( pattern-list ) Matches zero or more occurrences of the given patterns. .TP .CI +( pattern-list ) Matches one or more occurrences of the given patterns. .TP .CI @( pattern-list ) Matches exactly one of the given patterns. .TP .CI !( pattern-list ) Matches anything, except one of the given patterns. .PD .RE .SS Quoting Each of the metacharacters (see the "Definitions" subsection) has a special meaning to the shell and terminates a word unless quoted. A character may be .B quoted (that is, made to stand for itself) by preceding it with a backslash .RC ( \e ). The pair .CR \e newline is ignored; the current and following lines are concatenated. .PP All characters enclosed between a pair of apostrophes .RC ( ' ...\& ' ) are quoted. An apostrophe cannot appear within apostrophes. .PP Parameter and command substitution occurs inside quotation marks (\c .C """\c" \&...\&\c .C """\c" ). .CR \e quotes the characters .CR \e , .CR ` , .C """\c" , and .CR $ . .PP Inside grave accent marks .RC ( ` ...\& ` ), .CR \e quotes the characters .CR \e , .CR ` , and .CR $ . If the grave accents occur within quotation marks, .CR \e also quotes the character .C """\c" \&. .PP The meanings of .CR $* and .CR $@ are identical when not quoted or when used as a parameter assignment value or as a file name. However, when used as a command argument, .C """\c" .CR $*\c .C """" is equivalent to .C """\c" .CI $1 d $2 d\f1...\&\c .C """\c" , whereas .C """\c" .CR $@\c .C """" is equivalent to .C """\c" .CR $1\c .C """\c" .IR d\c .C """\c" .CR $2\c .C """\c" .IR d ...\& (where .I d is the first character of .CR IFS ), .PP The special meaning of keywords or aliases can be removed by quoting any character of the name. The recognition of function names or special command names cannot be altered by quoting them. .SS Arithmetic Evaluation Integer arithmetic is provided with the special command .CR let . Evaluations are performed using long integer arithmetic. Constants take the form .IC base # n or .IR n , where .I base is a decimal number between two and thirty-six representing the arithmetic base and .I n is a number in that base. If .IC base # is omitted, base 10 is used. .PP An arithmetic expression uses the same syntax, precedence, and associativity of expression as the C language. All the integral operators, other than .CR ++ , .CR \-\- , .CR ?: , and .CR , are supported. Variables can be referenced by name within an arithmetic expression without using the parameter substitution syntax. When a variable is referenced, its value is evaluated as an arithmetic expression. .PP A variable can be typed as an integer with the .CR \-i option of the .CR typeset special command, as in .CI typeset\0-i \f1[\f2base\f1]\f2\0name\f1. Arithmetic evaluation is performed on the value of each assignment to a variable with the .CR \-i attribute. If you do not specify an arithmetic base, the first assignment to the variable determines the arithmetic base. This base is used when parameter substitution occurs. .PP Since many of the arithmetic operators require quoting, an alternative form of the .CR let command is provided. For any command beginning with .CR (( , all characters until the matching .CR )) are treated as a quoted expression. More precisely, .CR (( ...\& )) is equivalent to .CR let .C """\c" .RC ...\c .C """\c" .RC . .SS Prompting When used interactively, the shell prompts with the value of .CR PS1 before reading a command. Whenever a newline is received and further input is needed to complete a command, the secondary prompt (the value of .CR PS2 ) is issued. .SS Conditional Expressions A .B "conditional expression" is used with the .CR [[ compound command to test attributes of files and to compare strings. Word splitting and file name generation are not performed on the words between .CR [[ and .CR ]] . Each expression can be constructed from one or more of the following unary or binary expressions: .RS .TP 20 .PD 0 .CI \-a \0file True, if .I file exists. .TP .CI \-b \0file True, if .I file exists and is a block special file. .TP .CI \-c \0file True, if .I file exists and is a character special file. .TP .CI \-d \0file True, if .I file exists and is a directory. .TP .CI \-e \0file True, if .I file exists. .TP .CI \-f \0file True, if .I file exists and is an ordinary file. .TP .CI \-g \0file True, if .I file exists and has its setgid bit set. .TP .CI \-h \0file True, if .I file exists and is a symbolic link. .TP .CI \-k \0file True, if .I file exists and has its sticky bit set. .TP .CI \-n \0string True, if length of .I string is nonzero. .TP .CI \-o \0option True, if the set option named .I option is on. .TP .CI \-p \0file True, if .I file exists and is a fifo special file or a pipe. .TP .CI \-r \0file True, if .I file exists and is readable by current process. .TP .CI \-s \0file True, if .I file exists and has a size greater than zero. .TP .CI \-t \0fildes True, if file descriptor number .I fildes is open and is associated with a terminal device. .TP .CI \-u \0file True, if .I file exists and has its setuid bit set. .TP .CI \-w \0file True, if .I file exists and is writable by the current process. .TP .CI \-x \0file True, if .I file exists and is executable by the current process. If .I file exists and is a directory, then the current process has permission to search in the directory. .TP .CI \-z \0string True, if length of .I string is zero. .TP .CI \-L \0file True, if .I file exists and is a symbolic link. .TP .CI \-O \0file True, if .I file exists and is owned by the effective user ID of this process. .TP .CI \-G \0file True, if .I file exists and its group matches the effective group ID of this process. .TP .CI \-S \0file True, if .I file exists and is a socket. .TP .IC file1\0 \-nt \0file2 True, if .I file1 exists and is newer than .IR file2 . .TP .IC file1\0 \-ot \0file2 True, if .I file1 exists and is older than .IR file2 . .TP .IC file1\0 \-ef \0file2 True, if .I file1 and .I file2 exist and refer to the same file. .TP .IC string\0 = \0pattern True, if .I string matches .IR pattern . .TP .IC string\0 != \0pattern True, if .I string does not match .IR pattern . .TP .IC string\0 < \0string2 True, if .I string1 comes before .I string2 based on the ASCII value of their characters. .TP .IC string\0 > \0string2 True, if .I string1 comes after .I string2 based on the ASCII value of their characters. .TP .IC exp1\0 \-eq \0exp2 True, if .I exp1 is equal to .IR exp2 . .TP .IC exp1\0 \-ne \0exp2 True, if .I exp1 is not equal to .IR exp2 . .TP .IC exp1\0 \-lt \0exp2 True, if .I exp1 is less than .IR exp2 . .TP .IC exp1\0 \-gt \0exp2 True, if .I exp1 is greater than .IR exp2 . .TP .IC exp1\0 \-le \0exp2 True, if .I exp1 is less than or equal to .IR exp2 . .TP .IC exp1\0 \-ge \0exp2 True, if .I exp1 is greater than or equal to .IR exp2 . .PD .RE .PP A compound expression can be constructed from these primitives by using any of the following, listed in decreasing order of precedence. .RS .TP 20 .PD 0 .CI ( exp ) True, if .I exp is true. Used to group expressions. .TP .CI ! exp True, if .I exp is false. .TP .IC exp1\0 && \0exp2 True, if .I exp1 and .I exp2 are both true. .TP .IC exp1\0 || \0exp2 True, if either .I exp1 or .I exp2 is true. .PD .RE .SS Input/Output Before a command is executed, its input and output can be redirected using a special notation interpreted by the shell. The following can appear anywhere in a simple-command or may precede or follow a command and are not passed on to the invoked command. Command and parameter substitution occurs before .I word or .I digit is used, except as noted below. File name generation occurs only if the pattern matches a single file and blank interpretation is not performed. .RS .TP 15 .CI < word Use file .I word as standard input (file descriptor .CR 0 ). .TP .CI > word Use file .I word as standard output (file descriptor .CR 1 ). If the file does not exist, it is created. If the file exists, and the .CR noclobber option is on, an error occurs; otherwise, the file is truncated to zero length. .TP .CI >| word Same as .CR > , except that it overrides the .CR noclobber option. .TP .CI >> word Use file .I word as standard output. If the file exists, output is appended to it (by first searching for the end-of-file); otherwise, the file is created. .TP .CI <> word Open file .I word for reading and writing as standard input. .TP .CR << [ \- ]\f2word The shell input is read up to a line that matches .IR word , or to an end-of-file. No parameter substitution, command substitution or file name generation is performed on .IR word . The resulting document, called a .IR here-document , becomes the standard input. If any character of .I word is quoted, no interpretation is placed upon the characters of the document. Otherwise, parameter and command substitution occurs, .CR \e newline is ignored, and .CR \e must be used to quote the characters .CR \e , .CR $ , .CR ` , and the first character of .IR word . If .CR \- is appended to .CR << , all leading tabs are stripped from .I word and from the document. .TP .CI <& digit The standard input is duplicated from file descriptor .I digit (see .IR dup (2)). .TP .CI >& digit The standard output is duplicated to file descriptor .I digit (see .IR dup (2)). .TP .CR <&- The standard input is closed. .TP .CR >&- The standard output is closed. .TP .CR <&p The input from the coprocess is moved to standard input. .TP .CR >&p The output to the coprocess is moved to standard output. .RE .RE .PP If any of the above redirections is preceded by a digit .RC ( 0 to .CR 9 ), the file descriptor used is the one specified by the digit, instead of the default .CR 0 (standard input) or .CR 1 (standard output). For example: .IP .CR 2>&1 .PP means open file descriptor 2 for writing as a duplicate of file descriptor 1. Output directed to file descriptor 2 is written in the same location as output to file descriptor 1. .PP Order is significant in redirection. The shell evaluates each redirection in terms of the .RI ( "file descriptor" ", " file ) assignment at the time of evaluation. For example: .IP .CR 1> \f2fname\0 2>&1 .PP first assigns file descriptor 1 to file .IR fname . It then assigns file descriptor 2 to the file assigned to file descriptor 1 (that is, .IR fname ). .PP If the order of redirection is reversed, as in .IP .CR 2>&1\01> \f2fname .PP file descriptor 2 is assigned to the file assigned to file descriptor 1 (probably the terminal) and then file descriptor 1 is assigned to file .IR fname . .PP By using the redirection operators above, the input and output of a .I coprocess may be moved to a numbered file descriptor, allowing other commands to write to them and read from them. If the input of the current coprocess is moved to a numbered file descriptor, another coprocess may be started. .PP If a command is followed by .CR & and job control is inactive, the default standard input for the command is the empty file .CR /dev/null . Otherwise, the environment for the execution of a command contains the file descriptors of the invoking shell as modified by input/output specifications. .SS Environment The .B environment (see .IR environ (5)) is a list of name-value pairs passed to an executed program much like a normal argument list. The names must be identifiers and the values are character strings. The shell interacts with the environment in several ways. When invoked, the shell scans the environment and creates a parameter for each name found, gives it the corresponding value and marks it .CR export . Executed commands inherit the environment. If the user modifies the values of these parameters or creates new ones by using the .CR export or .CR "typeset \-x" special commands, the values become part of the environment. The environment seen by any executed command is thus composed of any name-value pairs originally inherited by the shell, whose values may be modified by the current shell, plus any additions which must be noted in .CR export or .CR "typeset \-x" commands. .PP The environment for any simple command or function can be augmented by prefixing it with one or more parameter assignments. A parameter assignment argument takes the form .IC identifier = value\f1. For example, both the following .IP .CI TERM=450 "\0cmd\0args" .IP .CI "(export TERM; TERM=450;" "\0cmd\0args" ) .PP are equivalent (as far as the execution of .I cmd is concerned, except for the special commands that are preceded by a dagger (\(dg)). .PP If the .CR \-k option is set, all parameter assignment arguments are placed in the environment, even if they occur after the command name. The following echo statement prints .CR "a=b c" . After the .CR \-k option is set, the second echo statement prints only .CR c : .nf .IP .CR "echo a=b c" \0\(->\0 "a=b c" .CR "set \-k" .CR "echo a=b c" \0\(->\0 "c" .fi .PP This feature is intended for use with scripts written for early versions of the shell and its use in new scripts is strongly discouraged. It is likely to disappear someday. .SS Functions The .CR function command (described in the "Compound Commands" subsection) defines shell functions. Shell functions are read and stored internally. Alias names are resolved when the function is read. Functions are executed like commands, with the arguments passed as positional parameters. (See the "Execution" subsection.) .PP Functions execute in the same process as the caller and share all files and current working directory with the caller. Traps defined by the caller are reset to their default action inside the function. A trap condition that is not caught or ignored by the function causes the function to terminate and the condition to be passed on to the caller. A trap on .CR EXIT set inside a function is executed after the function completes in the environment of the caller. Ordinarily, variables are shared between the calling program and the function. However, the .CR typeset special command can be used within a function to define local variables whose scope includes the current function and all functions it calls. .PP The .CR return special command is used to return from function calls. Errors within functions return control to the caller. .PP Function identifiers can be listed with the .CR +f option of the .CR typeset special command. Function identifiers and the associated text of the functions can be listed with the .CR \-f option. Functions can be undefined with the .CR \-f option of the .CR unset special command. .PP Ordinarily, functions are unset when the shell executes a shell script. The .CR \-xf option of the .CR typeset command allows a function to be exported to scripts that are executed without reinvoking the shell. Functions that must be defined across separate invocations of the shell should be placed in the .CR ENV file. .SS Jobs If the .CR monitor option of the .CR set command is turned on, an interactive shell associates a .I job with each pipeline. It keeps a table of current jobs, printed by the .CR jobs command, and assigns them small integer numbers. When a job is started asynchronously with .CR & , the shell prints a line that looks like: .IP .C "[1] 1234" .PP indicating that job number 1 was started asynchronously and had one (top-level) process whose process ID was 1234. .PP If you are running a job and wish to do something else, you can type the suspend character (the .CR susp character defined with .CR stty ; see .IR stty (1)) to send a .CR SIGSTOP signal to the current job. The shell then indicates that the job has been .CR Stopped , and prints another prompt. Then you can manipulate the state of this job by putting it in the background with the .CR bg command, running other commands, and eventually returning the job to the foreground with the .CR fg command. A suspend takes effect immediately and resembles an interrupt, since pending output and unread input are discarded when the suspend is entered. .PP A job running in the background stops if it tries to read from the terminal. Background jobs normally are allowed to produce output, but can be disabled with the .CR "stty tostop" command. If the user sets this terminal option, background jobs stop when trying to produce output. .PP There are several ways to refer to jobs in the shell. A job can be referred to by the process ID of any process in the job or by one of the following: .RS .TP 20 .PD 0 .CI % number The job with the given number. .TP .CI % string Any job whose command line begins with .IR string . .TP .CI %? string Any job whose command line contains .IR string . .TP .CI %% Current job. .TP .CI %+ Equivalent to .CR %% . .TP .CR %- Previous job. .PD .RE .PP The shell learns immediately when a process changes state. It informs the user when a job is blocked and prevented from further progress, but only just before it prints a prompt. .PP When the monitor mode is on, each background job that completes triggers any trap set for .CR SIGCHLD . .PP If you try to exit from shell while jobs are stopped, you are warned with the message .CR "You have stopped jobs." You can use the .CR jobs command to identify them. If you immediately try to exit again, the shell will not warn you a second time, and the stopped jobs will be terminated. .PP If you try to leave the shell while jobs are running, you are not warned. The shell exits silently and sets the parent of the running jobs to the .CR init process (number 1). .SS Signals The .CR SIGINT and .CR SIGQUIT signals for an invoked command are ignored if the command is followed by .CR & and the .CR monitor option is off. Otherwise, signals have the values inherited by the shell from its parent, with the exception of signal .CR SIGSEGV (but see also the .CR trap special command). .SS Execution Substitutions are made each time a command is executed. .CR sh checks the command name to determine whether it matches a special command. If it does, it is executed within the current shell process. .PP Next, .CR sh checks the command name to determine whether it matches one of the user-defined functions. If it does, .CR sh saves the positional parameters, then sets them to the arguments of the function call. The positional parameter .CR 0 is unchanged. When the function completes or issues a .CR return , .CR sh restores the positional parameter list and executes any trap set on .CR EXIT within the function. The value of a function is the value of the last command executed. A function is executed in the current shell process. .PP If a command name is not a user-defined function or a special command, .CR sh creates a process and attempts to execute the command using an .CI exec * () system call (see .IR exec (2)). .PP The shell parameter .CR PATH defines the search path for the directory containing the command. Alternative directory names are separated by a colon .RC ( : ). The default path is .CR /usr/bin:\& (specifying .CR /usr/bin , and the current directory, in that order). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign, between colon delimiters, or at the end of the path list. The search path is not used if the command name contains a .CR / . Otherwise, each directory in the path is searched for an executable file. If the file has execute permissions but is not a directory or an executable object code file, it is assumed to be a script file, which is a file of data for an interpreter. If the first two characters of the script file are .CR #! , .CI exec * () expects an interpreter path name to follow. .CI exec * () then attempts to execute the specified interpreter as a separate process to read the entire script file. If a call to .CI exec * () fails, .CR sh is spawned to interpret the script file. All nonexported aliases, functions, and named parameters are removed in this case. If the shell command file does not have read permission, or if the .CR setuid and/or .CR setgid bits are set on the file, the shell executes an agent to set up the permissions and execute the shell with the shell command file passed down as an open file. A parenthesized command is also executed in a subshell without removing nonexported quantities. .SS Command Reentry The text of the last .CR HISTSIZE (default 128) commands entered from a terminal device is saved in a history file. The file .CR $HOME/.sh_history is used if the .CR HISTFILE variable is not set or writable. A shell can access the commands of all interactive shells that use the same named .CR HISTFILE . The special command .CR fc is used to list or edit a portion of this file. The portion of the file to be edited or listed can be selected by number or by giving the first character or characters of the command. A single command or range of commands can be specified. If you do not specify an editor program as an argument to .CR fc , the value of the parameter .CR FCEDIT is used. If .CR FCEDIT is not defined, .CR /usr/bin/ed is used. The edited command is printed and reexecuted upon leaving the editor. The editor name .CR \- is used to skip the editing phase and to reexecute the command. In this case, a substitution parameter of the form .IC old = new can be used to modify the command before execution. For example, if .CR r is aliased to .CR "fc \-e \-" , typing .CR "r bad=good c" reexecutes the most recent command that starts with the letter .CR c and replaces the first occurrence of the string .CR bad with the string .CR good . .SS Command Line Editing Normally, each command line typed at a terminal device is followed by a newline or return. If one of the .CR emacs , .CR gmacs , .CR vi , or .CR viraw , options is set, you can edit the command line. An editing option is automatically selected each time the .CR VISUAL or .CR EDITOR variable is assigned a value ending in one of these option names. .PP The editing features require that the user's terminal accept return without line feed and that a space ("\ ") must overwrite the current character on the screen. ADM terminal users should set the "space\ \(mi\ advance" switch to "space". Hewlett-Packard terminal users should set the straps to "bcGHxZ\ etX". .PP The editing modes enable the user to look through a window at the current line. The default window width is 80, unless the value of .CR COLUMNS is defined. If the line is longer than the window width minus two, a mark displayed at the end of the window notifies the user. The mark is one of: .RS .TP .PD 0 .CR > The line extends to the right. .TP .CR < The line extends to the left. .TP .CR * The line extends to both sides of the window. .PD .RE .PP As the cursor moves and reaches the window boundaries, the window is centered about the cursor. .PP The search commands in each edit mode provide access to the history file. Only strings are matched, not patterns, although a leading .CR ^ in the string restricts the match to begin at the first character in the line. .SS emacs Editing Mode This mode is invoked by either the .CR emacs or .CR gmacs option. Their sole difference is their handling of .CR ^T . To edit, the user moves the cursor to the point needing correction and inserts or deletes characters or words. All editing commands are control characters or escape sequences. The notation for control characters is caret .RC ( ^ ) followed by a character. For example, .CR ^F is the notation for Control-F. This is entered by holding down the Ctrl (control) key and pressing .CR f . The shift key is .I not pressed. The notation .CR ^?\& indicates the delete (DEL) key. .PP The notation for escape sequences is .CR M- followed by a character. For example, .CR M-f (pronounced .IR "meta f" ) is entered by pressing the escape key (ESC) followed by pressing .CR f . .CR M-F is the notation for escape followed by shift (capital) .CR F . .PP All edit commands operate from any place on the line (not only at the beginning). Neither the return .RC ( ^M ) nor the newline .RC ( ^J ) key is entered after edit commands, except when noted. .RS .TP 15 .PD 0 .CR ^F Move cursor forward (right) one character. .TP .CR M-f Move cursor forward one word. (The editor's idea of a word is a string of characters consisting of only letters, digits and underscores.) .TP .CR ^B Move cursor backward (left) one character. .TP .CR M-b Move cursor backward one word. .TP .CR ^A Move cursor to start of line. .TP .CR ^E Move cursor to end of line. .TP .CI ^] char Move cursor forward to character .I char on current line. .TP .CI M-^] char Move cursor backward to character .I char on current line. .TP .CI ^X^X Interchange the cursor and mark. .TP .I erase Delete previous character. (User-defined erase character as defined by the .CR stty command, usually .CR ^H or .CR # .) .TP .CR ^D Delete current character. .TP .I eof Terminate the shell if the current line is null. (User-defined end-of-file character as defined by the .CR stty command, usually .CR ^D .) .TP .CI M-d Delete current word. .TP .CI M-^H Delete previous word. (meta-backspace) .TP .CI M-h Delete previous word. .TP .CI M-^?\& Delete previous word. (meta-delete) If your interrupt character is .CR ^?\& (DEL, the default), this command will not work. .TP .CI ^T In .CR emacs mode, transpose current character with next character. In .CR gmacs mode, transpose two previous characters. .TP .CI ^C Capitalize current character. .TP .CI M-c Capitalize current word. .TP .CI M-l Change the current word to lowercase. .TP .CI ^K Delete from the cursor to the end of the line. If preceded by a numerical parameter whose value is less that the current cursor position, then delete from the given position up to the cursor. If preceded by a numerical parameter whose value is greater than the current cursor position, then delete from the cursor up to the given position. .TP .CI ^W Kill from the cursor to the mark. .TP .CI M-p Push the region from the cursor to the mark on the stack. .TP .I kill Kill the entire current line. If two kill characters are entered in succession, all subsequent consecutive kill characters cause a line feed (useful when using paper terminals). (User-defined kill character as defined by the .CR stty command, usually .CR ^X or .CR @ .) .TP .CI ^Y Restore last item removed from line. (Yank item back to the line.) .TP .CI ^L Line feed and print current line. .TP .CR ^@ Set mark. (null character) .TP .CI M-\0 Set mark. (meta-space) .TP .CI ^J Execute the current line. (newline) .TP .CI ^M Execute the current line. (return) .TP .CI ^P Fetch previous command. Each time .CR ^P is entered, the previous command in the history list is accessed. .TP .CI ^N Fetch next command. Each time .CR ^N is entered the next command in the history list is accessed. .TP .CI M-< Fetch the least recent (oldest) history line. .TP .CI M-> Fetch the most recent (youngest) history line. .TP .CI ^R string Reverse search history for a previous command line containing .IR string . If a parameter of zero is given, the search is forward. .I string is terminated by a return or newline. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is omitted, the next command line containing the most recent .I string is accessed. In this case, a parameter of zero reverses the direction of the search. .TP .CR ^O Execute the current line and fetch the next line relative to current line from the history file. .TP .CI M- digits Define a numeric parameter. The digits are taken as a parameter to the next command. The commands that accept a parameter are .IR erase , .CR ^B , .CR ^C , .CR ^D , .CR ^F , .CR ^K , .CR ^N , .CR ^P , .CR ^R , .CR ^] , .CR M-^H , .CR M-. , .CR M-_ , .CR M-b , .CR M-c , .CR M-d , .CR M-f , .CR M-h , and .CR M-l . .TP .CI M- letter Your alias list is searched for an alias by the name .CI _ letter (underscore-letter). If an alias of this name is defined, its value is inserted on the input queue. This .I letter must not be one of the above metafunctions. .TP .CR M-. The last word of the previous command is inserted on the line. If preceded by a numeric parameter, the value of this parameter determines which word to insert rather than the last word. .TP .CR M-_ Same as .CR M-. . .TP .CR M-* Attempt file name generation on the current word. .TP .CR M-^[ File name completion. (meta-escape.) Replaces the current word with the longest common prefix of all file names matching the current word with an asterisk appended. If the match is unique, a .CR / is appended if the file is a directory and a space is appended if the file is not a directory. .TP .CR M-= List files matching current word pattern as if an asterisk were appended. .TP .CR ^U Multiply parameter of next command by 4. .TP .CR \e Escape next character. Editing characters and your erase, kill, and interrupt characters may be entered in a command line or in a search string, if preceded by a .CR \e . The .CR \e removes the next character's editing features (if any). .TP .CI ^V Display version of the shell. .TP .CI M-# Insert a .CR # at the beginning of the line and execute it. This causes a comment to be inserted in the history file. .PD .RE .SS vi Editing Mode The editor starts in insert mode until an escape (ESC) is received. This puts you in control mode in which you can move the cursor and perform editing commands. A return in either mode sends the line. .PP Most control commands accept an optional repeat .I count prior to the command. .PP In .CR vi mode on most systems, canonical processing is initially enabled and the command is echoed again if the speed is 1200 baud or greater and contains any control characters, or if less than one second has elapsed since the prompt was printed. The escape (ESC) character terminates canonical processing for the remainder of the command and you can then modify the command line. This scheme has the advantages of canonical processing with the typeahead echoing of raw mode. .PP Setting the .CR viraw option always disables canonical processing on the terminal. This mode is implicit for systems that do not support two alternate end-of-line delimiters, and may be helpful for certain terminals. .PP .B Insert Edit Commands .PP By default, the editor is in insert mode. .RS .TP 15 .PD 0 .I erase Delete previous inserted character. The .IR erase character is user-definable with the .CR stty command, usually set to .CR ^H . The system default is .CR # . .TP .I kill Delete all current inserted characters. The .IR kill character is user-definable with the .CR stty command, usually set to .CR ^X or .CR ^U . The system default is .CR @ . .TP .CR \e Escape the next .I erase or .I kill character. .TP .CR ^D Terminate the shell. .TP .CR ^V Escape next character. Editing characters and erase or kill characters may be entered in a command line or in a search string if preceded by a .CR ^V , which removes the next character's editing features (if any). .TP .CR ^W Delete the previous blank-separated word. .PD .RE .PP .B Motion Edit Commands .PP These commands move the cursor. The use of .IR count causes a repetition of the command the cited number of times. .RS .TP 15 .PD 0 .RC [\f2count\f1] l Cursor forward (right) one character. .TP .RC [\f2count\f1] w Cursor forward one alphanumeric word. .TP .RC [\f2count\f1] W Cursor forward to the beginning of the next word that follows a blank. .TP .RC [\f2count\f1] e Cursor forward to the end of the word. .TP .RC [\f2count\f1] E Cursor forward to end of the current blank-delimited word. .TP .RC [\f2count\f1] h Cursor backward (left) one character. .TP .RC [\f2count\f1] b Cursor backward one word. .TP .RC [\f2count\f1] B Cursor backward to preceding blank-separated word. .TP .RC [\f2count\f1] | Cursor to column .IR count . Default is 1. .TP .RC [\f2count\f1] f \f2c Find the next character .IR c in the current line. .TP .RC [\f2count\f1] F \f2c Find the previous character .IR c in the current line. .TP .RC [\f2count\f1] t \f2c Equivalent to .CI f c followed by .CR h . .TP .RC [\f2count\f1] T \f2c Equivalent to .CI F c followed by .CR l . .TP .RC [\f2count\f1] ; Repeat the last single-character find command, .CR f , .CR F , .CR t , or .CR T . .TP .RC [\f2count\f1] , Reverses the last single character find command. .TP .CR 0 Cursor to start of line. .TP .CR ^ Cursor to first nonblank character in line. .TP .CR $ Cursor to end of line. .PD .RE .PP .B History Search Commands .PP These commands access your command history file. .RS .TP 15 .PD 0 .RC [\f2count\f1] k Fetch previous command. Each time .CR k is entered, the next earlier command in the history list is accessed. .TP .RC [\f2count\f1] \- Equivalent to .CR k . .TP .RC [\f2count\f1] j Fetch next command. Each time .CR j is entered, the next later command in the history list is accessed. .TP .RC [\f2count\f1] + Equivalent to .CR j . .TP .RC [\f2count\f1] G The command number .I count is fetched. The default is the first command in the history list. .TP .CI / string Search backward through history for a previous command containing .IR string . .I string is terminated by a return or newline. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is null, the previous string is used. .TP .CI ? string Same as .CR / , but search in the forward direction. .TP .CR n Search for next match of the last pattern to the .CR / or .CR ? commands. .TP .CR N Search for next match of the last pattern to .CR / or .CR ? , but in reverse direction. .PD .RE .PP .B Text Modification Edit Commands .PP These commands will modify the line. .RS .TP 15 .PD 0 .CR a Enter insert mode after the current character. .TP .CR A Append text to the end of the line. Equivalent to .CR $a . .TP .RC [\f2count\f1] c \f2motion .TP .CR c [\f2count\f1]\f2motion Move cursor forward to the character position specified by .IR motion , deleting all characters between the original cursor position and the new position, and enter insert mode. If .I motion is .CR c , the entire line is deleted. .TP .CR C Delete from the current character through the end of line and enter insert mode. Equivalent to .CR c$ . .TP .CR S Equivalent to .CR cc . .TP .RC [\f2count\f1] d \f2motion .TP .CR d [\f2count\f1]\f2motion Move cursor to the character position specified by .IR motion , deleting all characters between the original cursor position and the new position. If .I motion is .CR d , the entire line will be deleted. .TP .CR D Delete from the current character through the end of line. Equivalent to .CR d$ . .TP .CR i Enter insert mode before the current character. .TP .CR I Enter insert mode before the beginning of the line. Equivalent to the two-character sequence .CR 0i . .TP .RC [\f2count\f1] P Insert the previous text modification before the cursor. .TP .RC [\f2count\f1] p Insert the previous text modification after the cursor. .TP .CR R Enter insert mode and replace characters on the screen with characters you type, overlay fashion. .TP .RC [\f2count\f1] r \f2c Replace the current character with .IR c . .TP .RC [\f2count\f1] x Delete the current character. .TP .RC [\f2count\f1] X Delete the preceding character. .TP .RC [\f2count\f1] . Repeat the previous text modification command. .TP .CR ~ Invert the case of the current character and advance the cursor. .TP .RC [\f2count\f1] _ Append the .I count word of the previous command at the current cursor location and enter insert mode at the end of the appended text. The last word is used if .I count is omitted. .TP .CR * Append an .CR * to the current word and attempt file name generation. If no match is found, ring the bell. If a match is found, replace the word with the matching string of file names and enter insert mode. .TP escape .TP .CR \e Attempt file name completion on the current word. Replace the current word with the longest common prefix of all file names matching the current word with an asterisk appended. If the match is unique, append a .CR / if the file is a directory or append a space if the file is not a directory. .PD .RE .PP .B Other Edit Commands .PP .RS .TP 15 .PD 0 .RC [\f2count\f1] y \f2motion .TP .CR y [\f2count\f1]\f2motion Yank current character through character that .I motion would move the cursor to and put them into the delete buffer. The text and cursor are unchanged. .TP .CR Y Yank from current position to end of line. Equivalent to .CR y$ . .TP .CR u Undo the last text-modifying command. .TP .CR U Undo all the text-modifying commands performed on the line. .TP .RC [\f2count\f1] v Execute the command .CI "fc \-e ${VISUAL:-${EDITOR:-vi}}" " count" in the input buffer. If .I count is omitted, the current line is used. This executes an editor with the current line as the input "file". When you exit from the editor, the result is executed. .TP .CR ^L Line feed and print current line. .TP .CR ^J Execute the current line, regardless of mode. (newline) .TP .CR ^M Execute the current line, regardless of mode. (return) .TP .CR # Insert a .CR # at the beginning of the current line and after each embedded newline, and execute the line. Useful for inserting the current command line in the history list without executing it. .TP .CR = List the file names that match the current word if an asterisk were appended to it. .TP .CI @ letter Search your alias list for an alias with the name .CI _ letter (underscore letter). If an alias of this name is defined, its value is executed as a command sequence on the current line. This provides a simple macro capability. .PD .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. If it is not defined or is empty, it defaults to the value of .CR LANG . .PP .CR LC_CTYPE determines the classification of characters as letters, and the characters matched by character class expressions in pattern matching notation. If it is not defined or is empty, it defaults to the value of .CR LANG . .PP If .CR LANG is not defined or is empty, it defaults to .CR C (see .IR lang (5)). .PP If any internationalization variable contains an invalid value, they all default to .CR C (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH RETURN VALUE Errors detected by the shell, such as syntax errors, cause the shell to return a nonzero exit status. Otherwise, the shell returns the exit status of the last command executed. See also the .CR exit special command. If the shell is being used noninteractively, the execution of the shell file is abandoned. Runtime errors detected by the shell are reported by printing the command or function name and the error condition. If the line number on which the error occurred is greater than one, the line number is also printed in brackets .RC ( [] ) after the command or function name. .\".SH EXAMPLES .\" none appropriate. .SH WARNINGS .PP .\" File descriptors 54 through 60 are used internally by the POSIX shell. File descriptors 24 through 30 are used internally by the POSIX shell. Applications using these and forking a subshell should not depend upon them surviving in the subshell or its descendants. .PP If a command that is a tracked alias is executed, and a command with the same name is installed in a directory in the search path before the directory where the original command was found, the shell will continue to load and execute the original command. Use the .CR \-t option of the .CR alias command to correct this situation. .PP If you move the current directory or one above it, .CR pwd may not give the correct response. Use the .CR cd command with a full path name to correct this situation. .PP Some very old shell scripts use a caret .RC ( ^ ) as a synonym for the pipe character .RC ( | ). .CR sh .I "does not" recognize the caret as a pipe character. .PP If a command is piped into a shell command, all variables set in the shell command are lost when the command completes. .PP Using the .CR fc built-in command within a compound command will cause the entire command to disappear from the history file. .PP The dot .RC ( . ) special command, as in .CI .\& " file\f1," reads the entire file before any commands are executed. Therefore, .CR alias and .CR unalias commands in the file will not apply to any functions defined in the file. .PP Traps are not processed while the shell is waiting for a foreground job. Thus, a trap on .CR SIGCHLD is not executed until the foreground job terminates. .PP The .CR export special command does not handle arrays properly. Only the first element of an array is exported to the environment. .PP Background processes started from a noninteractive shell cannot be accessed with job control commands. .PP The value of the .CR IFS variable in the user's environment affects the behavior of scripts. .SS Collating Order In an international environment, character ordering is determined by the value of .CR LC_COLLATE , rather than by the binary ordering of character values in the machine collating sequence. This brings with it certain attendant dangers, particularly when using range expressions in file name generation patterns. For example, the command, .IP .C "rm [a-z]*" .PP might be expected to match all file names beginning with a lowercase alphabetic character. However, if dictionary ordering is specified by .CR LC_COLLATE , it would also match file names beginning with an uppercase character (as well as those beginning with accented letters). Conversely, it would fail to match letters collated after .CR z in languages such as Danish or Norwegian. .PP The correct (and safe) way to match specific character classes in an international environment is to use a pattern (see .IR regexp (5)) of the form: .IP .C "rm [[:lower:]]*" .PP This uses .CR LC_CTYPE to determine character classes and works predictably for all supported languages and codesets. For shell scripts produced on noninternationalized systems (or without consideration for the above dangers), it is recommended that they be executed in a non-NLS environment. This requires that .CR LANG , .CR LC_COLLATE , and so on, be set to .CR C or not set at all. .SS History File Changes At HP-UX release B.10.10, the history file has a new internal magic number. This will cause a pre-B.10.10 history file to be discarded. Users who use multiple versions of HP-UX that NFS-mount the same directory that contains the history file (usually the home directory) may want to create a separate history file for each HP-UX version by setting the .CR HISTFILE parameter as: .IP .C "HISTFILE=$HOME/.sh_hist_$(uname \-r)" .PP Users on windowing systems may want to have separate history files for each window by setting the HISTFILE parameter as follows: .IP .C "HISTFILE=$HOME/.sh_hist$$" .PP A .CR cron job may be used to delete old history files. .PP The history file does not support mixing of locales in the same file. For users of multiple locales, you can assign a unique history file for each locale by setting .CR HISTFILE as: .IP .C "HISTFILE=$HOME/.sh_hist_${LANG}" .PP or include the process number in the .CR HISTFILE parameter as shown above. .SH AUTHOR .CR sh was developed by AT&T, OSF, and HP. .SH FILES .TP 30 .PD 0 .CR $HOME/.profile Read to set up user's custom environment .TP .CR /etc/passwd To find home directories .TP .CR /etc/profile Read to set up system environment .TP .CR /etc/suid_profile Security profile .TP .CR /tmp/sh* For here-documents .TP .CR /usr/bin/sh Shell executable program location .PD .SH SEE ALSO cat(1), cd(1), command(1), echo(1), ed(1), env(1), getopts(1), kill(1), ln(1), login(1), newgrp(1), printf(1), pwd(1), read(1), stty(1), test(1), time(1), umask(1), vi(1), dup(2), exec(2), fork(2), pipe(2), stty(2), ulimit(2), umask(2), wait(2), rand(3C), a.out(4), profile(4), environ(5), lang(5), regexp(5), signal(5). .SH STANDARDS CONFORMANCE .CR sh ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR . ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR : ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR break ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR case ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR continue ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR eval ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR exec ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR exit ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR export ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR for ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR if ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR read ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR return ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR set ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR shift ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR time ": SVID2, SVID3, XPG2, XPG3, XPG4" .br .CR trap ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR unset ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR until ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR while ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4sh\f1 \- shell based on POSIX.2@@@\f3sh-posix(1)\f1 .\" index@\f4alias\f1 \- substitute command and/or file name@@@\f3sh-posix(1)\f1 .\" index@\f4break\f1 \- exit from enclosing for/next loop@@@\f3sh-posix(1)\f1 .\" index@\f4case\f1 \- execute \f2list\f1 associated with \f2pattern\f1 that matches \f2word\f1@@@\f3sh-posix(1)\f1 .\" index@\f4cd\f1 \- change working directory@@@\f3sh-posix(1)\f1 .\" index@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@\f3sh-posix(1)\f1 .\" index@\f4echo\f1 \- echo (print) arguments@@@\f3sh-posix(1)\f1 .\" index@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@\f3sh-posix(1)\f1 .\" index@\f4exec\f1 \- execute command without creating new process@@@\f3sh-posix(1)\f1 .\" index@\f4exit\f1 \- exit shell with exit status@@@\f3sh-posix(1)\f1 .\" index@\f4export\f1 \- export variable names to environment of subsequent commands@@@\f3sh-posix(1)\f1 .\" index@\f4fc\f1 \- edit and execute previous command@@@\f3sh-posix(1)\f1 .\" index@\f4for\f1 \- execute a do list@@@\f3sh-posix(1)\f1 .\" index@\f4if\f1 \- execute command if previous command returns exit status 0@@@\f3sh-posix(1)\f1 .\" index@\f4jobs\f1 \- list active jobs@@@\f3sh-posix(1)\f1 .\" index@\f4kill\f1 \- terminate job or process@@@\f3sh-posix(1)\f1 .\" index@\f4let\f1 \- evaluate arithmetic expression@@@\f3sh-posix(1)\f1 .\" index@\f4newgrp\f1 \- equivalent to \f4exec newgrp\f1@@@\f3sh-posix(1)\f1 .\" index@\f4print\f1 \- output from shell@@@\f3sh-posix(1)\f1 .\" index@\f4pwd\f1 \- print current working directory@@@\f3sh-posix(1)\f1 .\" index@\f4read\f1 \- input and parse a line@@@\f3sh-posix(1)\f1 .\" index@\f4readonly\f1 \- mark names as unredefinable@@@\f3sh-posix(1)\f1 .\" index@\f4return\f1 \- shell function return to invoking script@@@\f3sh-posix(1)\f1 .\" index@\f4set\f1 \- set/define options and arguments@@@\f3sh-posix(1)\f1 .\" index@\f4shift\f1 \- shift \f2argv\f1 members one position to left@@@\f3sh-posix(1)\f1 .\" index@\f4test\f1 \- evaluate conditional expression@@@\f3sh-posix(1)\f1 .\" index@\f4time\f1, \f4times\f1 \- print summary of time used by processes@@@\f3sh-posix(1)\f1 .\" index@\f4trap\f1 \- trap specified signal@@@\f3sh-posix(1)\f1 .\" index@\f4typeset\f1 \- control leading blanks and parameter handling@@@\f3sh-posix(1)\f1 .\" index@\f4ulimit\f1 \- set size or time limits@@@\f3sh-posix(1)\f1 .\" index@\f4umask\f1 \- set permissions mask for creating new files@@@\f3sh-posix(1)\f1 .\" index@\f4unalias\f1 \- discard specified alias@@@\f3sh-posix(1)\f1 .\" index@\f4unset\f1 \- remove definition/setting of options and arguments@@@\f3sh-posix(1)\f1 .\" index@\f4until\f1 \- execute commands until expression is nonzero@@@\f3sh-posix(1)\f1 .\" index@\f4wait\f1 \- wait for child process@@@\f3sh-posix(1)\f1 .\" index@\f4whence\f1 \- define interpretation of name as a command@@@\f3sh-posix(1)\f1 .\" index@\f4while\f1 \- execute commands while expression is nonzero@@@\f3sh-posix(1)\f1 .\" .\" toc@\f3sh-posix(1)\f1:\0\0\f4sh\f1@@@shell, the standard/restricted command programming language .\" toc@\f4case\f1 \- label in a switch statement@@@see \f3sh-posix(1)\f1 .\" toc@\f4alias\f1 \- substitute command and/or file name@@@see \f3sh-posix(1)\f1 .\" toc@\f4break\f1 \- exit from enclosing for/next loop@@@see \f3sh-posix(1)\f1 .\" toc@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@see \f3sh-posix(1)\f1 .\" toc@\f4cd\f1 \- change working directory@@@see \f3sh-posix(1)\f1 .\" toc@\f4echo\f1 \- echo (print) arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@see \f3sh-posix(1)\f1 .\" toc@\f4exec\f1 \- execute command without creating new process@@@see \f3sh-posix(1)\f1 .\" toc@\f4exit\f1 \- exit shell with exit status@@@see \f3sh-posix(1)\f1 .\" toc@\f4export\f1 \- export variable names to environment of subsequent commands@@@see \f3sh-posix(1)\f1 .\" toc@\f4fc\f1 \- edit and execute previous command@@@see \f3sh-posix(1)\f1 .\" toc@\f4for\f1 \- execute a do list@@@see \f3sh-posix(1)\f1 .\" toc@\f4if\f1 \- execute command if previous command returns exit status 0@@@see \f3sh-posix(1)\f1 .\" toc@\f4jobs\f1 \- list active jobs@@@see \f3sh-posix(1)\f1 .\" toc@\f4kill\f1 \- terminate job or process@@@see \f3sh-posix(1)\f1 .\" toc@\f4let\f1 \- evaluate arithmetic expression@@@see \f3sh-posix(1)\f1 .\" toc@\f4newgrp\f1 \- equivalent to \f2exec newgrp\f1@@@see \f3sh-posix(1)\f1 .\" toc@\f4print\f1 \- output from shell@@@see \f3sh-posix(1)\f1 .\" toc@\f4pwd\f1 \- print current working directory@@@see \f3sh-posix(1)\f1 .\" toc@\f4read\f1 \- input and parse a line@@@see \f3sh-posix(1)\f1 .\" toc@\f4readonly\f1 \- mark names as unredefinable@@@see \f3sh-posix(1)\f1 .\" toc@\f4return\f1 \- shell function return to invoking script@@@see \f3sh-posix(1)\f1 .\" toc@\f4set\f1 \- set/define options and arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4shift\f1 \- shift \f2argv\f1 members one position to left@@@see \f3sh-posix(1)\f1 .\" toc@\f4test\f1 \- evaluate conditional expression@@@see \f3sh-posix(1)\f1 .\" toc@\f4trap\f1 \- trap specified signal@@@see \f3sh-posix(1)\f1 .\" toc@\f4time, times\f1 \- print summary of time used by processes@@@see \f3sh-posix(1)\f1 .\" toc@\f4typeset\f1 \- control leading blanks and parameter handling@@@see \f3sh-posix(1)\f1 .\" toc@\f4ulimit\f1 \- set size or time limits@@@see \f3sh-posix(1)\f1 .\" toc@\f4umask\f1 \- set permissions mask for creating new files@@@see \f3sh-posix(1)\f1 .\" toc@\f4unalias\f1 \- discard specified alias@@@see \f3sh-posix(1)\f1 .\" toc@\f4unset\f1 \- remove definition/setting of options and arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4wait\f1 \- wait for child process@@@see \f3sh-posix(1)\f1 .\" toc@\f4whence\f1 \- define interpretation of name as a command@@@see \f3sh-posix(1)\f1 .\" toc@\f4while\f1 \- execute commands while expression is nonzero@@@see \f3sh-posix(1)\f1 .\" toc@\f4until\f1 \- execute commands until expression is nonzero@@@see \f3sh-posix(1)\f1 .\" .\" links@sh-posix.1 alias.1 .\" links@sh-posix.1 bg.1 .\" links@sh-posix.1 fc.1 .\" links@sh-posix.1 fg.1 .\" links@sh-posix.1 jobs.1 .\" links@sh-posix.1 unalias.1 .\" $Header: join.1,v 76.1 95/08/03 17:56:51 ssa Exp $ .TA j .TH join 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME join \- relational database operator .SH SYNOPSIS .C join .RI [ \|options\| ] .I file1 file2 .SH DESCRIPTION .C join forms, on the standard output, a join of the two relations specified by the lines of .I file1 and .IR file2 . If .I file1 or .I file2 is .CR - , the standard input is used. .PP .I file1 and .I file2 must be sorted in increasing collating sequence (see Environment Variables below) on the fields on which they are to be joined; normally the first in each line. .PP The output contains one line for each pair of lines in .I file1 and .I file2 that have identical join fields. The output line normally consists of the common field followed by the rest of the line from .IR file1 , then the rest of the line from .IR file2 . .PP The default input field separators are space, tab, or new-line. In this case, multiple separators count as one field separator, and leading separators are ignored. The default output field separator is a space. .PP Some of the below options use the argument .IR n . This argument should be a .C 1 or a .C 2 referring to either .I file1 or .IR file2 , respectively. .SS Options .PP .TP 12 .CI -a \0n In addition to the normal output, produce a line for each unpairable line in file .IR n , where .I n is .C 1 or .CR 2 . .TP .CI -e \0s Replace empty output fields by string .IR s . .TP .CI -j \0m Join on field .I m of both files. The argument .I m must be delimited by space characters. This option and the following two are provided for backward compatibility. Use of the .C -1 and .C -2 options ( see below ) is recommended for portability. .TP .CI -j1 \0m Join on field .I m of .I file1. .TP .CI -j2 \0m Join on field .I m of .I file2. .TP .CI -o \0list Each output line comprises the fields specified in .IR list , each element of which has the form .IC n . m\f1, where .I n is a file number and .I m is a field number. The common field is not printed unless specifically requested. .TP .CI -t \0c Use character .I c as a separator (tab character). Every appearance of .I c in a line is significant. The character .I c is used as the field separator for both input and output. .TP .CI -v \0file_number Instead of the default output, produce a line only for each unpairable line in .IR file_number , where .I file_number is .C 1 or .CR 2 . .TP .CI -1 \0f Join on field .I f of file 1. Fields are numbered starting with 1. .TP .CI -2 \0f Join on field .I f of file 2. Fields are numbered starting with 1. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the collating sequence .C join expects from input files. .PP .C LC_CTYPE determines the alternative blank character as an input field separator, and the interpretation of data within files as single and/or multi-byte characters. .C LC_CTYPE also determines whether the separator defined through the .C -t option is a single- or multi-byte character. .PP If .C LC_COLLATE or .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C join behaves as if all internationalization variables are set to ``C'' (see .IR environ (5)). .SS International Code Set Support Single- and multi-byte character code sets are supported with the exception that multi-byte-character file names are not supported. .SH EXAMPLES The following command line joins the password file and the group file, matching on the numeric group .SM ID, and outputting the login name, the group name, and the login directory. It is assumed that the files have been sorted in the collating sequence defined by the .C LC_COLLATE or .C LANG environment variable on the group .SM ID fields. .IP .C "join -1 4 -2 3 -o 1.1 2.1 1.6 -t: /etc/passwd /etc/group" .PP The following command produces an output consisting all possible combinations of lines that have identical first fields in the two sorted files .I sf1 and .IR sf2 , with each line consisting of the first and third fields from .C sorted_file1 and the second and fourth fields from .CR sorted_file2 : .IP .C "join -j1 1 -j2 1 -o 1.1, 2.2, 1.3, 2.4 sorted_file1 sorted_file2" .SH WARNINGS With default field separation, the collating sequence is that of .CR "sort -b" ; with .CR -t , the sequence is that of a plain sort. .PP The conventions of .CR join , .CR sort , .CR comm , .CR uniq , and .CR awk are incongruous. .PP Numeric filenames may cause conflict when the .C -o option is used immediately before listing filenames. .SH AUTHOR .CR join was developed by OSF and HP. .SH SEE ALSO awk(1), comm(1), sort(1), uniq(1). .SH STANDARDS CONFORMANCE .CR join ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4join\f1 \- relational database operator@@@\f3join(1)\f1 .\" index@relational database, join two relations in@@@\f3join(1)\f1 .\" index@database, relational, join two relations in@@@\f3join(1)\f1 .\" .\" toc@\f3join(1)\f1:\0\0\f4join\f1@@@relational database operator .\" $Header: kermit.1,v 80.2 97/01/12 08:04:30 ssa Exp $ .\" kermit.1 6.0.192 96/09/06 Columbia University .TH kermit 1 "HP-UX C-Kermit" .SH NAME kermit \- C-Kermit 6.0.192 communications software for serial and network connections: modem dialing, file transfer and management, terminal connection, character-set translation, and script programming. .SH SYNOPSIS .C kermit .RI [\| command-file \|] .RI [\| options \|...\|] .SH DESCRIPTION .I Kermit is a family of file transfer, management, and communication software programs from Columbia University available for most computers and operating systems. The version of Kermit for Hewlett-Packard HP-UX, called .GT "C-Kermit" , supports both serial connections (direct or dialed) and TCP/IP connections. C-Kermit can be thought of as a user-friendly and powerful alternative to cu, tip, uucp, ftp, and telnet; a single package for both network and serial communications, offering automation, convenience, and language features not found in the other packages, and having a great deal in common with its cousins, C-Kermit on other UNIX platforms, Kermit 95 for Windows 95 and NT and OS/2, MS-DOS Kermit for PCs with DOS and Windows 3.x, and IBM Mainframe Kermit-370 for VM/CMS, MVS/TSO, and CICS. C-Kermit itself also runs on Digital VMS, Data General AOS/VS, Stratus VOS, OS-9, QNX, the BeBox, Plan 9, the Commodore Amiga, and elsewhere. Together, C-Kermit, Kermit 95, MS-DOS Kermit, and IBM Mainframe Kermit offer a consistent and nearly universal approach to inter-computer communications. .PP C-Kermit 6.0.192 is Copyright (C) 1985, 1996 by the Trustees of Columbia University in the City of New York. The C-Kermit software may not be, in whole or in part, licensed or sold for profit as a software product itself, nor may it be included in or distributed with commercial products or otherwise distributed by commercial concerns to their clients or customers without written permission of the Office of Kermit Development and Distribution, Columbia University. This copyright notice must not be removed, altered, or obscured. .PP C-Kermit 6.0.192 is included with HP-UX 10.0 and later HP-UX releases by Hewlett-Packard in partnership with the Office of Kermit Development and Distribution, Columbia University. .PP C-Kermit 6.0 is thoroughly documented in the book .CT "Using C-Kermit" by Frank da Cruz and Christine M. Gianone, Digital Press, Second Edition, 1997; see REFERENCES at the end of this manual page. This manual page is not a substitute for the book. If you are a serious user of C-Kermit, particularly if plan to write C-Kermit script programs, you should purchase the manual. Book sales are the primary source of funding for the nonprofit Kermit Project. .PP Any new features added since the most recent edition of the book was published are documented in the online file .IR "ckcker.upd" . Hints, tips, limitations, restrictions are listed in .IR "ckcker.bwr" (general C-Kermit) and .IR "ckuker.bwr" (UNIX-specific); see FILES below. Please consult all of these references before reporting problems or asking for technical support. .PP Kermit software is available for hundreds of different computers and operating systems from Columbia University. For best file-transfer results, please use C-Kermit in conjunction with real Columbia University Kermit software on other computers, such as Kermit 95 for Windows 95 and NT or MS-DOS Kermit for DOS 3.x or Windows. See CONTACTS below. .SH "MODES OF OPERATION" C-Kermit can be used in two "modes": remote and local. In .GT "remote mode" , you connect to the HP-UX system from a desktop computer and transfer files between your desktop computer and HP-UX C-Kermit. In that case, connection establishment (dialing, TELNET connection, etc.) is handled by the Kermit program on your desktop computer. .PP In .GT "local mode" , C-Kermit establishes a connection to another computer by direct serial connection, by dialing a modem, or by making a network connection. When used in local mode, C-Kermit gives you a terminal connection to the remote computer, using your actual terminal, emulator, or UNIX workstation terminal window or console driver for specific terminal emulation. .PP C-Kermit also has two types of commands: the familiar UNIX-style command-line options, and an interactive dialog with a prompt. .GT "Command-line options" give you access to a small but useful subset of C-Kermit's features for terminal connection and file transfer, plus the ability to pipe files into or out of Kermit for transfer. .PP .GT "Interactive commands" give you access to dialing, script programming, character-set translation, and, in general, detailed control and display of all C-Kermit's features. Interactive commands can also be collected into command files or macros. .SH "STARTING C-KERMIT" You can start C-Kermit by typing "/usr/bin/kermit", or just "kermit" if your PATH includes "/usr/bin", possibly followed by command-line options. If there are no "action options" on the command line (explained below), C-Kermit starts in interactive command mode; you will see a greeting message and then the "C-Kermit>" prompt. If you do include action options on the command line, C-Kermit takes the indicated actions and then exits directly back to UNIX. Either way, C-Kermit executes the commands in its initialization file, .CR "/usr/share/lib/kermit/ckermit.ini" , before it executes any other commands, unless you have included the `\|\c .C \-Y\c \&\|' (uppercase) command-line option, which means to skip the initialization file, or you have included the `\|\c .C -y \c \&\| .IR "filename" \c \&\|' option to specify an alternative initialization file. .SH "FILE TRANSFER" Here is the most common scenario for Kermit file transfer. Many other methods are possible, most of them more convenient, but this basic method should work in all cases. .RS .TP 3 \(bu Start Kermit on your local computer and establish a connection to the remote computer. If C-Kermit is on your local computer, use the sequence SET MODEM TYPE .IR "modem-name" \c \&\|, SET LINE .IR "device-name" \c \&\|, SET SPEED .IR "bits-per-second" \c \&\|, and DIAL .IR "phone-number" if you are dialing; SET LINE and SPEED for direct connections; SET NETWORK .IR "network-type" and SET HOST .IR "host-name-or-address" for network connections. .TP \(bu SET any other necessary communication parameters, such as PARITY, DUPLEX, and FLOW-CONTROL. .TP \(bu Give the CONNECT command. .TP \(bu Log in to the remote computer. .TP \(bu Start Kermit on the remote computer, give it any desired SET commands for file-, communication-, or protocol-related parameters. If you will be transferring binary files, give the command SET FILE TYPE BINARY to the Kermit program that will be sending them. .TP \(bu To .GT download a file or file group, give the remote Kermit a SEND command, following by a filename or "wildcard" file specification, for example: .RS 10 .nf .P .C "send oofa.txt # (send one file)" .C "send oofa.* # (send a group of files)" .fi .RE .IP To .GT upload a file or files, give the remote Kermit a RECEIVE command. The sending Kermit will tell the receiving Kermit the name (and other attributes) of each file. .TP \(bu Escape back to the Kermit program on your local (desktop) computer. If your local computer is running C-Kermit, type Ctrl-\e c (Control-backslash followed by the letter 'c') (on NeXT workstations, use Ctrl-] c). If MS-DOS or OS/2 or Windows Kermit, use Alt-x (hold down the Alt key, press 'x'). Now you should see your local Kermit program's prompt. .TP \(bu If you will be transferring binary files, give the command SET FILE TYPE BINARY to the Kermit program that is sending the files. .TP \(bu If you are .EM downloading files, tell the local Kermit program to RECEIVE. If you are .EM "uploading", give your local Kermit program a SEND command, specifying a filename or wildcard file specification. In other words, tell the .EM remote Kermit program what to do first, SEND or RECEIVE, then escape back to the .IR local Kermit and give it the opposite command, RECEIVE or SEND. .TP \(bu When the transfer is complete, give a CONNECT command. Now you are talking to Kermit on the remote computer again. Type EXIT to get back to the command prompt on the remote computer. When you are finished using the remote computer, log out and then (if necessary) escape back to Kermit on your local computer. Then you can make another connection or EXIT from the local Kermit program. .RE .PP C-Kermit's file transfer protocol defaults are deliberately conservative, resulting in file transfer that almost always works, but might be somewhat slow. To increase file transfer performance on computers and connections that permit it, use SET RECEIVE PACKET-LENGTH to increase the packet length, SET WINDOW to increase the packet window size, and use SET PREFIXING to reduce the overhead of control-character prefixing. (Hint: try the .CR FAST command to enable all these performance options at once.) On serial connections, use hardware flow control (SET FLOW RTS/CTS) if available, rather than software (XON/XOFF) flow control. On TCP/IP connections, SET FLOW NONE. For details, including benchmarks, read Chapter 12 of .CT "Using C-Kermit" . .SH OTHER FEATURES C-Kermit includes features too numerous to be explained in a man page. For further information about connection establishment, modem dialing, networks, terminal connection, key mapping, logging, file transfer options and features, troubleshooting, client/server operation, character-set translation during terminal connection and file transfer, "raw" up- and downloading of files, macro construction, script programming, convenience features, and shortcuts, plus numerous tables, examples, and illustrations, please consult .CT "Using C-Kermit" . .SH HELP .PP C-Kermit has extensive built-in help. You can find out what commands exist by typing ? at the C-Kermit> prompt. You can type HELP at the C-Kermit> prompt for "getting-started" message, or HELP followed by the name of a particular command for information about that command, for example: .RS .nf .P .C "help send" .C "help set file" .fi .RE .P You can type ? anywhere within a command to get brief help about the current command field. You can also type the INTRO command to get a brief introduction to C-Kermit, and the NEWS command to find out what's new in your version. Finally, you can use the BUG command to learn how to report bugs. .SH "ENTERING COMMANDS" You can use upper or lower case for interactive-mode commands, but remember that UNIX filenames are case-sensitive. You can abbreviate commands as long as the abbreviation matches only one possibility. While typing a command, you can use the following editing characters: .RS 0 Plain .IP Delete, Backspace, or Rubout erases the rightmost character. .PD 0 .IP Ctrl-W erases the rightmost "word". .IP Ctrl-U erases the current command line. .IP Ctrl-R redisplays the current command. .IP Ctrl-P recalls a previous command (scrolls back in command buffer). .IP Ctrl-N scrolls forward in a scrolled-back command buffer. .IP Ctrl-C cancels the current command. .IP Tab, Esc, or Ctrl-I tries to complete the current keyword or filename. .IP ? gives help about the current field. .RE .PD .P To enter the command and make it execute, press the Return or Enter key. .SH BACKSLASH NOTATION Within an interactive command, the "\e" character (backslash) is a prefix used to enter special quantities, including ordinary characters that would otherwise be illegal. At the end of a line, \e or - (dash) makes the next line a continuation of the current line. Other than that, the character following the \e identifies what the special quantity is: .RS .TP 25n % A user-defined simple (scalar) variable such as \e%a or \e%1 .PD 0 .TP & an array reference such as \e&a[3] .TP $ an environment variable such as \e$(TERM) .TP v (or V) a built-in variable such as \ev(time) .TP f (or F) a function such as \eFsubstring(\e%a,3,2) .TP d (or D) a decimal (base 10) number (1 to 3 digits, 0..255) such as \ed27 .TP o (or O) an octal (base 8) number (1 to 3 digits, 0..377) such as \eo33 .TP x (or X) a hexadecimal (base 16) number (2 digits, 00..ff) like \ex1b .TP \e the backslash character itself .TP b (or B) the BREAK signal (OUTPUT command only) .TP l (or L) a Long BREAK signal (OUTPUT only) .TP n (or N) a NUL (0) character (OUTPUT only) .TP a decimal digit a 1-, 2-, or 3-digit decimal number, such as \e27 .TP {} used for grouping, e.g. \e{27}123 .TP anything else: following character taken literally. .RE .PD .P Note that numbers turn into the character with that binary code (0-255), so you can use \e7 for a bell, \e13 for carriage return, \e10 for linefeed. For example, to have C-Kermit send a BELL to your screen, type: .IP .C "echo \e7" .SH "COMMAND LIST" The commands most commonly used, and important for beginners to know, are marked with "*": .SS Program Management .RS 0 .TP 30n BUG Learn how to report bugs. .PD 0 .TP CHECK See if a particular feature is configured. .TP CLOSE Close a log or other local file. .TP COMMENT Introduce a full-line comment. .TP DATE Display current date and time. .TP * EXIT Leave the program, return to UNIX. .TP * HELP Display a help message for a given command. .TP * INTRO Print a brief introduction to C-Kermit. .TP LOG Open a log file -- debugging, packet, session, transaction. .TP PUSH Invoke local system's interactive command interpreter. .TP QUIT Synonym for EXIT. .TP REDIRECT Redirect standard I/O of command to communication device. .TP RUN Run a program or system command. .TP SET COMMAND Command-related parameters: bytesize, recall buffer size. .TP SET DEBUG Log or display debugging information. .TP SET EXIT Items related to C-Kermit's action upon exit or SET LINE/HOST. .TP SET PROMPT The C-Kermit program's interactive command prompt. .TP SHOW EXIT Display SET EXIT parameters. .TP SHOW FEATURES Show features that C-Kermit was built with. .TP SHOW VERSIONS Show version numbers of each source module. .TP SUSPEND Suspend Kermit (use only if shell supports job control!). .TP * SHOW Display values of SET parameters. .TP * TAKE Execute commands from a file. .TP VERSION Display the C-Kermit program version number. .TP Z Synonym for SUSPEND. .TP Ctrl-C Interrupt a C-Kermit command in progress. .TP Ctrl-Z Synonym for SUSPEND. .TP ; or # Introduce a full-line or trailing comment. .TP ! or @ Synonym for RUN. .TP < Synonym for REDIRECT. .RE .PD .SS Connection Establishment and Release .RS 0 .TP 30n * DIAL Dial a telephone number. .PD 0 .TP * HANGUP Hang up the phone or network connection. .TP PAD Command for X.25 PAD (SunOS / Solaris / VOS only). .TP PING Check status of remote TCP/IP host. .TP REDIAL Dial the most recently DIALed number again. .TP SET CARRIER Treatment of carrier on terminal connections. .TP * SET DIAL Parameters related to modem dialing. .TP * SET FLOW Communication line flow control: AUTO, RTS/CTS, XON/XOFF, etc. .TP * SET HOST Specify remote network host name or address. .TP * SET LINE Specify serial communication device name, like /dev/cul0p0. .TP * SET MODEM TYPE Specify type of modem on SET LINE device, like HAYES. .TP * SET NETWORK Network type, TCP/IP or X.25 (SunOS / Solaris / VOS only). .TP SET TCP Specify TCP protocol options (advanced). .TP SET TELNET Specify TELNET protocol options. .TP SET PAD X.25 X.3 PAD parameters (SunOS / Solaris / VOS only). .TP * SET PARITY Character parity (none, even, etc.) for communications. .TP * SET SPEED Serial communication device speed, e.g. 2400, 9600, 57600. .TP SET X.25 Specify X.25 connection parameters (SunOS / Solaris / VOS only). .TP SHOW COMM Display all communications settings. .TP SHOW DIAL Display SET DIAL values. .TP SHOW MODEM Display modem type, signals, etc. .TP SHOW NETWORK Display network-related items. .TP * TELNET = SET NETWORK TCP/IP, SET HOST ..., CONNECT. .TP TELOPT Send a TELNET option negotiation (advanced). .RE .PD .SS Terminal Connection .RS 0 .TP 30n * C Special abbreviation for CONNECT. .PD 0 .TP * CONNECT Establish a terminal connection to a remote computer. .TP SET COMMAND Bytesize between C-Kermit and your keyboard and screen. .TP * SET DUPLEX Specify which side echoes during CONNECT. .TP SET ESCAPE Prefix for "escape commands" during CONNECT. .TP SET KEY Key mapping and macros for use in CONNECT mode. .TP SET TERMINAL Terminal connection items: bytesize, character-set, echo, etc. .TP SHOW ESCAPE Display current CONNECT-mode escape character. .TP SHOW KEY Display keycode and assigned value or macro. .TP SHOW TERMINAL Display SET TERMINAL items. .TP * Ctrl-\e CONNECT-mode escape character, followed by another character: .RS 35 Plain .IP C to return to C-Kermit> prompt. .IP B to send BREAK signal. .IP ? to see other options. .RE .RE .PD .SS File Transfer .RS 0 .TP 30n ADD Add a file specification to the SEND-LIST. .PD 0 .TP LOG SESSION Download a file with no error checking. .TP MOVE Send a file and then delete it. .TP MMOVE Multiple MOVE - accepts a list of files, separated by spaces. .PD 0 .TP MSEND Multiple SEND - accepts a list of files, separated by spaces. .TP * RECEIVE Passively wait for files to arrive from other Kermit. .TP * R Special abbreviation for RECEIVE. .TP * SEND Send files. .TP * S Special abbreviation for SEND. .TP REGET Continue an incomplete download from a server. .TP RESEND Continue an incomplete transmission. .TP PSEND Send part of a file. .TP SET ATTRIB Control transmission of file attributes. .TP * SET BLOCK Choose error-checking level, 1, 2, or 3. .TP SET BUFFERS Size of send and receive packet buffers. .TP SET PREFIX Which control characters to "unprefix" during file transfer. .TP SET DELAY How long to wait before sending first packet. .TP SET DESTINATION DISK, PRINTER, or SCREEN for incoming files. .TP * SET FILE Transfer mode (type), character-set, collision action, etc. .TP * SET RECEIVE Parameters for inbound packets: packet-length, etc. .TP SET REPEAT Repeat-count compression parameters. .TP SET RETRY Packet retransmission limit. .TP SET SEND Parameters for outbound packets: length, etc. .TP SET HANDSHAKE Communication line half-duplex packet turnaround character. .TP SET LANGUAGE Enable language-specific character-set translations. .TP SET SESSION-LOG File type for session log, text or binary. .TP SET TRANSFER File transfer parameters: character-set, display, etc. .TP SET TRANSMIT Control aspects of TRANSMIT command execution. .TP SET UNKNOWN Specify handling of unknown character sets. .TP * SET WINDOW File transfer packet window size, 1-31. .TP SHOW ATTRIB Display SET ATTRIBUTE values. .TP SHOW CONTROL Display control-character prefixing map. .TP * SHOW FILE Display file-related settings. .TP SHOW PROTOCOL Display protocol-related settings. .TP SHOW LANGUAGE Display language-related settings. .TP SHOW TRANSMIT Display SET TRANSMIT values. .TP * STATISTICS Display statistics about most recent file transfer. .TP TRANSMIT Upload a file with no error checking. .TP XMIT Synonym for TRANSMIT. .RE .PD .SS File Management .RS 0 .TP 30n * CD Change Directory. .PD 0 .TP * DELETE Delete a file or files. .TP * DIRECTORY Display a directory listing. .TP MAIL Send a file to other Kermit, to be delivered as e-mail. .TP PRINT Print a local file on a local printer. .TP * PWD Display current working directory. .TP RENAME Change the name of a local file. .TP SET PRINTER Choose printer device. .TP SPACE Display current disk space usage. .TP SHOW CHARACTER-SETS Display character-set translation info. .TP TRANSLATE Translate a local file's character set. .TP TYPE Display a file on the screen. .TP XLATE Synonym for TRANSLATE. .RE .PD .SS Client/Server Operation .RS 0 .TP 30n BYE Terminate a remote Kermit server and log out its job. .PD 0 .TP DISABLE Disallow access to selected features during server operation. .TP E-PACKET Send an Error packet. .TP ENABLE Allow access to selected features during server operation. .TP FINISH Instruct a remote Kermit server to exit, but not log out. .TP G Special abbreviation for GET. .TP GET Get files from a remote Kermit server. .TP RETRIEVE Like GET but server deletes files after. .TP REMOTE xxx Command for server, can be redirected with > or |. .TP REMOTE CD Tell remote Kermit server to change its directory. .TP REMOTE ASSIGN Assign a variable. .TP REMOTE DELETE Tell server to delete a file. .TP REMOTE DIRECTORY Ask server for a directory listing. .TP REMOTE HELP Ask server to send a help message. .TP REMOTE HOST Ask server to ask its host to execute a command. .TP REMOTE KERMIT Send an interactive Kermit command to the server. .TP REMOTE LOGIN Authenticate yourself to a remote Kermit server. .TP REMOTE LOGOUT Log out from a Kermit server previously LOGIN'd to. .TP REMOTE PRINT Print a local file on the server's printer. .TP REMOTE QUERY Get value of a variable. .TP REMOTE SET Send a SET command to a remote server. .TP REMOTE SPACE Ask server how much disk space it has left. .TP REMOTE TYPE Ask server to display a file on your screen. .TP REMOTE WHO Ask server for a "who" or "finger" listing. .TP SERVER Be a Kermit server. .TP SET SERVER Parameters for server operation. .TP SHOW SERVER Show SET SERVER, ENABLE/DISABLE items. .RE .PD .SS Script programming .RS 0 .TP 30n ASK Prompt the user, store user's reply in a variable. .PD 0 .TP ASKQ Like ASK, but does not echo (useful for passwords). .TP ASSIGN Assign an evaluated string to a variable or macro. .TP CLEAR Clear communication device input buffer. .TP CLOSE Close a log or other local file. .TP DECLARE Declare an array. .TP DECREMENT Subtract one (or other number) from a variable. .TP DEFINE Define a variable or macro. .TP DO Execute a macro ("DO" can be omitted). .TP ECHO Display text on the screen. .TP ELSE Used with IF. .TP END A command file or macro. .TP EVALUATE An arithmetic expression. .TP FOR Execute commands repeatedly in a counted loop. .TP FORWARD GOTO in the forward direction only. .TP GETC Issue a prompt, get one character from keyboard. .TP GETOK Ask question, get Yes or No answer, set SUCCESS or FAILURE. .TP GOTO Go to a labeled command in a command file or macro. .TP IF Conditionally execute the following command. .TP INCREMENT Add one (or other number) to a variable. .TP INPUT Match characters from another computer against a given text. .TP LOCAL Declares local variables in a macro. .TP MINPUT Like INPUT, but allows several match strings. .TP MSLEEP Sleep for given number of milliseconds. .TP OPEN Open a local file for reading or writing. .TP O Special abbreviation for OUTPUT. .TP OUTPUT Send text to another computer. .TP PAUSE Do nothing for a given number of seconds. .TP READ Read a line from a local file into a variable. .TP REINPUT Reexamine text previously received from another computer. .TP RETURN Return from a user-defined function. .TP SCRIPT Execute a UUCP-style login script. .TP SET ALARM Set a timer to be used with IF ALARM; SHOW ALARM shows it. .TP SET CASE Treatment of alphabetic case in string comparisons. .TP SET COMMAND QUOTING turns on/off interpretation of backslash notation. .TP SET COUNT For counted loops. .TP SET INPUT Control behavior of INPUT command. .TP SET MACRO Control aspects of macro execution. .TP SET TAKE Control aspects of TAKE file execution. .TP SHOW ARGUMENTS Display arguments to current macro. .TP SHOW ARRAYS Display information about active arrays. .TP SHOW COUNT Display current COUNT value. .TP SHOW FUNCTIONS List names of available \ef() functions. .TP SHOW GLOBALS List defined global variables \e%a..\e%z. .TP SHOW MACROS List one or more macro definitions. .TP SHOW SCRIPTS Show script-related settings. .TP SHOW VARIABLES Display values all \ev() variables. .TP SLEEP Sleep for given number of seconds. .TP STOP Stop executing macro or command file, return to prompt. .TP UNDEFINE Undefine a variable. .TP WAIT Wait for the specified modem signals. .TP WHILE Execute commands repeatedly while a condition is true. .TP WRITE Write material to a local file. .TP WRITE-LINE Write a line (record) to a local file. .TP WRITELN Synonym for WRITE-LINE. .TP XECHO Like ECHO but no CRLF at end. .TP XIF Extended IF command. .RE .PD .SH "BUILT-IN VARIABLES" Built-in variables are referred to by \ev(name), can be used in any command, usually used in script programming. They cannot be changed. Type SHOW VARIABLES for a current list. .RS 0 .TP 30n \ev(argc) Number of arguments in current macro .PD 0 .TP \ev(args) Number of program command-line arguments .TP \ev(charset) Current file character-set .TP \ev(cmdfile) Name of current command file, if any .TP \ev(cmdlevel) Current command level .TP \ev(cmdsource) Where command are currently coming from, macro, file, etc. .TP \ev(cols) Number of screen columns .TP \ev(connection) Connection type: serial, tcp/ip, etc. .TP \ev(count) Current COUNT value .TP \ev(cps) Speed of most recent file transfer in chars per second .TP \ev(cpu) CPU type C-Kermit was built for .TP \ev(crc16) 16-bit CRC of most recent file transfer .TP \ev(d$ac) SET DIAL AREA-CODE value .TP \ev(d$cc) SET DIAL COUNTRY-CODE value .TP \ev(d$ip) SET DIAL INTL-PREFIX value .TP \ev(d$lc) SET DIAL LD-PREFIX value .TP \ev(date) Date as 8 Feb 1993 .TP \ev(day) Day of week .TP \ev(directory) Current/default directory .TP \ev(dialstatus) Return code from DIAL command (0 = OK, 22 = BUSY, etc.) .TP \ev(download) Current download directory if any .TP \ev(errno) Current "errno" (system error number) value .TP \ev(errstring) Error message string associated with errno .TP \ev(evaluate) Result of most recent EVALUATE command .TP \ev(exitstatus) Current EXIT status (0 = good, nonzero = something failed) .TP \ev(filespec) Filespec given in most recent SEND/RECEIVE/GET command .TP \ev(fsize) Size of file most recently transferred .TP \ev(ftype) SET FILE TYPE value (text, binary) .TP \ev(home) Home directory .TP \ev(host) Computer host name (computer where C-Kermit is running) .TP \ev(input) Current INPUT buffer contents .TP \ev(inchar) Character most recently INPUT .TP \ev(incount) How many characters arrived during last INPUT .TP \ev(inidir) Directory where initialization file was found .TP \ev(instatus) Status of most recent INPUT command .TP \ev(line) Current communications device, set by LINE or HOST .TP \ev(local) 0 if in remote mode, 1 if in local mode .TP \ev(macro) Name of currently executing macro, if any .\" =========== .TP \ev(minput) Result of most recent MINPUT command .TP \ev(modem) Current modem type .TP \ev(m_aa_off) Modem command to turn autoanswer off .TP \ev(m_aa_on) Modem command to turn autoanswer on .TP \ev(m_dc_off) Modem command to turn data compression off .TP \ev(m_dc_on) Modem command to turn data compression on .TP \ev(m_dial) Telephone number most recently dialed .TP \ev(m_ec_off) Modem command to turn error correction off .TP \ev(m_ec_on) Modem command to turn error correction on .TP \ev(m_fc_hw) Modem command to turn hardware flow control on .TP \ev(m_fc_no) Modem command to turn flow control off .TP \ev(m_fc_sw) Modem command to turn software flow control on .TP \ev(m_hup) Modem command to hang up connection .TP \ev(m_init) Modem initialization string .TP \ev(m_pulse) Modem command to select pulse dialing .TP \ev(m_tone) Modem command to select tone dialing .\" =========== .TP \ev(ndate) Current date as 19930208 (yyyymmdd) .TP \ev(nday) Numeric day of week (0 = Sunday) .TP \ev(newline) System-independent newline character or sequence .TP \ev(ntime) Current local time in seconds since midnight (noon = 43200) .TP \ev(packetlen) Current SET RECEIVE PACKET-LENGTH value .TP \ev(parity) Current parity setting .TP \ev(platform) Specific machine and/or operating system .TP \ev(program) Name of this program ("C-Kermit") .\" =========== .TP \ev(query) Result of most recent REMOTE QUERY command .TP \ev(protocol) Currently selected file transfer protocol .\" =========== .TP \ev(return) Most recent RETURN value .\" =========== .TP \ev(rows) Number of rows on the terminal screen .TP \ev(speed) Current speed, if known, or "unknown" .TP \ev(status) 0 or 1 (SUCCESS or FAILURE of previous command) .\" =========== .TP \ev(sysid) Kermit attribute code for system ID .\" =========== .TP \ev(system) UNIX .TP \ev(terminal) Terminal type .TP \ev(tfsize) Total size of file group most recently transferred .TP \ev(time) Time as 13:45:23 (hh:mm:ss) .\" =========== .TP \ev(tmpdir) Temporary directory .TP \ev(ttyfd) File descriptor of current communication device .TP \ev(version) Numeric version of Kermit, e.g. 501190. .\" =========== .TP \ev(window) Current window size (SET WINDOW value) .RE .PD .SH "BUILT-IN FUNCTIONS" Builtin functions are invoked as \eFname(args), can be used in any command, and are usually used in script programs. Type SHOW FUNCTIONS for a current list. .RS 0 .TP 30n \eFbasename(file) basename of file .PD 0 .TP \eFbreak(s,c) left substring of s up to first occurrence of char c .TP \eFcapitalize(s) uppercase first letter of s and lowercase the rest .TP \eFcharacter(arg) convert numeric arg to character .TP \eFchecksum(s) 32-bit arithmetic checksum of string s .PD 0 .TP \eFcode(char) numeric code for character .TP \eFcontents(v) return current definition of variable .TP \eFcrc16(s) 16-bit CRC of string s .TP \eFdate(filename) return file's modification date/time .TP \eFdefinition(m) return current definition of macro .TP \eFeval(expr) evaluate arithmetic expression .TP \eFexecute(m,a,b,..) execute macro "m" with arguments "a", "b", etc. .TP \eFfiles(f) number of files matching file spec .TP \eFhexify(s) translate s into a hexadecimal string .TP \eFindex(a1,a2,a3) position of string a2 in a1, starting at pos a3 .TP \eFipaddress(s) returns first IP address from string s .TP \eFlength(arg) length of the string "arg" .TP \eFliteral(arg) copy argument literally, no evaluation .TP \eFlower(arg) convert to lower case .TP \eFlpad(text,n,c) left pad text to length n with char c .TP \eFltrim(s) Trim whitespace from left of s .TP \eFmax(a1,a2) max of two numbers .TP \eFmin(a1,a2) min of two numbers .TP \eFmodulus(n1,n2) modulus n2 of integer n1 .TP \eFnextfile() next file name from list in last \eFfiles() .TP \eFpathname(file) full pathname of file .TP \eFrepeat(a1,a2) repeat a1 a2 times .TP \eFreplace(a1,a2,a3) replace a2 by a3 in a1 .TP \eFreverse(arg) reverse characters in arg .TP \eFright(a1,a2) rightmost a2 characters of string a1 .TP \eFrindex(a1,a2,a3) like \eFindex, but searching from right .TP \eFrpad(text,n,c) right pad text to length n with char c .TP \eFsize(filename) return file's length in bytes .TP \eFspan(a1,a2) left substring of a1 containing only chars from a2 .TP \eFsubstr(a1,a2,a3) substring of a1, starts at a2, length a3 .TP \eFtod2secs(s) converts hh:mm:ss to seconds since midnight .TP \eFtrim(s) removes trailing whitespace from s .TP \eFunhexify(s) converts a hexadecimal string s back to original .TP \eFupper(s) converts s to upper case .TP \eFverify(a1,a2,n) returns index of first char in a2 that is not in a1 starting at position n of a2. .RE .PD .PP \eFeval() allows the following operators in the expression. The expression can contain variables. Only integer arithmetic is supported. Precedences are shown as numbers, 1 is highest precedence, 6 is lowest. .PP .in +5n .TS l l l. ( ) 1 parentheses n ! 2 factorial ~ n 3 logical NOT - n 4 negative n ^ n 4 power n * n 5 multiplication n / n 5 division n % n 5 modulus n & n 5 logical AND n + n 6 plus n - n 6 minus n | n 6 logical OR n # n 6 exclusive OR n @ n 6 greatest common divisor .TE .in -5n .SH "COMMAND LINE OPTIONS" C-Kermit accepts commands (or "options") on the command line, in the time-honored UNIX style. Alphabetic case is significant. All options are optional. If one or more action options are included, Kermit exits immediately after executing the command-line options, otherwise it enters interactive command mode. .RS .nf .P \f4kermit\fP [\f2filename\fP] [\f4-\f2x\fP \f2arg\fP\f1 [\f4-\f2x\fP \f2arg\fP\f1]...[\f4-\f2yyy\fP\f1]...]] .fi .RE where: .RS 0 Plain .IP .I filename is the name of a command file to execute, .IP .CI - x is an option requiring an argument, .IP .CI - y an option with no argument. .RE .SS Actions .RS 0 .TP 30n -s files send files .PD 0 .TP -s - send files from stdin .TP -r receive files .TP -k receive files to stdout .TP -x enter server mode .TP -f finish remote server .TP -g files get remote files from server (quote wildcards) .TP -a name alternate file name, used with -s, -r, -g .TP -c connect (before file transfer), used with -l or -j .TP -n connect (after file transfer), used with -l or -j .RE .PD .SS Settings .RS 0 .TP 30n -l line communication line device (to make a serial connection) .PD 0 .TP -l n open file descriptor of communication device .TP -j host TCP/IP network host name (to make a network connection) .TP -J host connect like TELNET, exit when connection closes .TP -l n open file descriptor of TCP/IP connection (n = number) .TP -X X.25 network address .TP -Z open file descriptor of X.25 connection .TP -o n X.25 closed user group call info .TP -u X.25 reverse-charge call .TP -q quiet during file transfer .TP -8 8-bit clean .TP -i transfer files in binary mode .TP -T transfer files in text mode .TP -b bps serial line speed, e.g. 1200 .TP -m name modem type, e.g. hayes .TP -p x parity, x = e,o,m,s, or n .TP -t half duplex, xon handshake .TP -e n receive packet-length .TP -v n window size .TP -Q Quick file-transfer settings .TP -w write over files of same name, do not backup old file .TP -D n delay n seconds before sending a file .RE .PD .SS Other .RS 0 .TP 30n -y name alternate init file name .PD 0 .TP -Y Skip init file .TP -R Advise C-Kermit it will be used only in remote mode .TP -d log debug info to file debug.log .TP -S Stay, do not exit, after action command .TP -C "cmds" Interactive-mode commands, comma-separated .TP -z Force foreground operation .TP -B Force background (batch) operation .TP -h print command-line option help screen .TP = Ignore all text that follows .RE .PD .SS Examples Remote-mode example (C-Kermit is on the far end): send file .C oofa.bin in binary mode .RC ( -i ) using a window size of 4 .RC ( "-v 4" ): .IP .C "kermit -v 4 -i -s oofa.bin" .P Local-mode example (C-Kermit makes the connection): make a 19200-bps direct connection out through .CR /dev/tty0p0 , CONNECT .RC ( -c ) so you can log in and, presumably start a remote Kermit program and tell it to send a file, RECEIVE the file .RC ( -r ), then CONNECT back .RC ( -n ) so you can finish up and log out: .IP .C "kermit -l /dev/tty0p0 -b 19200 -c -r -n" .P For dialing out, you must specify a modem type, and you might have to use a different device name: .IP .C "kermit -m hayes -l /dev/cul0p0 -b 2400 -c -r -n" .SH FILES .PD 0 .RS 0 .TP 50n .C $HOME/.mykermrc Your personal C-Kermit customization file. .TP .C $HOME/.kdd Your personal dialing directory. .TP .C $HOME/.ksd Your personal services directory. .TP .C /usr/share/lib/kermit/READ.ME Overview of HP-UX C-Kermit, please read .TP .C /usr/share/lib/kermit/ckermit.ini System-wide initialization file .TP .C /usr/share/lib/kermit/ckermod.ini Sample customization file .TP .C /usr/share/lib/kermit/ckermit.kdd Sample dialing directory .TP .C /usr/share/lib/kermit/ckermit.ksd Sample services directory .TP .C /usr/share/lib/kermit/ckcker.upd Supplement to "Using C-Kermit" .TP .C /usr/share/lib/kermit/ckcker.bwr C-Kermit "beware" file - hints & tips .TP .C /usr/share/lib/kermit/ckuker.bwr UNIX-specific beware file .TP .C /usr/share/lib/kermit/ckedemo.ini Macros from "Using C-Kermit" .TP .C /usr/share/lib/kermit/ckevt.ini Macros from "Using C-Kermit" .TP .C /usr/share/lib/kermit/ckepager.ksc Alpha pager script .TP .C /var/spool/locks/LCK..* UUCP lockfiles .RE .PD .PP To make .GT "personalized customizations" , copy the file /usr/share/lib/kermit/ckermod.ini file to your home directory, make any desired changes, and rename it to .CR ".mykermrc" . .P You may also create a personalized .GT "dialing directory" like the sample one in /usr/share/lib/kermit/ckermit.kdd. Your personalized dialing directory should be stored in your home directory as .CR ".kdd" and your personal network directory as .CR ".knd" . See Chapters 5 and 6 of .CT "Using C-Kermit" for details. .P And you may also create a personalized .GT "services directory" like the sample one in /usr/share/lib/kermit/ckermit.ksd. Your personalized services directory should be stored in your home directory as .CR ".ksd" . See Chapter 7 of .CT "Using C-Kermit" for instructions. .P The demonstration files illustrate C-Kermit's script programming constructs; they are discussed in chapters 17-19 of the book. You can run them by typing the appropriate TAKE command at the C-Kermit> prompt, for example: "take /usr/share/lib/kermit/ckedemo.ini". .PD .SH AUTHORS Frank da Cruz, Columbia University, with contributions from hundreds of other volunteer programmers all over the world. See Acknowledgements in .CT "Using C-Kermit" . .SH REFERENCES .TP Frank da Cruz and Christine M. Gianone, .CT "Using C-Kermit" , Second Edition, 1997, 622 pages, Digital Press / Butterworth-Heinemann, 225 Wildwood Street, Woburn, MA 01801, USA. ISBN 1-55558-164-1. (In the USA, call +1 800 366-2665 to order Digital Press books.) Also available in a German edition from Verlag Heinze Heise, Hannover. .TP Frank da Cruz, .CT "Kermit, A File Transfer Protocol" , Digital Press / Butterworth-Heinemann, Woburn, MA, USA (1987). ISBN 0-932376-88-6. The Kermit file transfer protocol specification. .TP Christine M. Gianone, .CT "Using MS-DOS Kermit" , Digital Press / Butterworth-Heinemann, Woburn, MA, USA (1992). ISBN 1-5558-082-3. Also available in a German edition from Heise, and a French edition from Heinz Schiefer & Cie, Versailles. .TP .CT "Kermit News" , Issues 4 (1990) and 5 (1993), Columbia University, for detailed discussions of Kermit file transfer performance. .SH DIAGNOSTICS The diagnostics produced by .I C-Kermit itself are intended to be self-explanatory. In addition, every command returns a SUCCESS or FAILURE status that can be tested by IF FAILURE or IF SUCCESS. In addition, the program itself returns an exit status code of 0 upon successful operation or nonzero if any of various operations failed. .SH BUGS See the comp.protocols.kermit.* newsgroups on Usenet for discussion, or the files, ckcker.bwr and ckuker.bwr, for a list of bugs, hints, tips. etc. Report bugs via e-mail to .CR kermit-support@columbia.edu . .SH CONTACTS For more information about Kermit software and documentation, visit the Kermit Web site: .PP .CR http://www.columbia.edu/kermit/ .PP Or write to: .RS .nf .P The Kermit Project Columbia University 612 West 115th Street New York, NY 10025-7221 USA .fi .RE .P Or send e-mail to .CR kermit@columbia.edu . Or call +1 212 854-3703. Or fax +1 212 663-8202. .\" .\" index@\f4kermit\f1 \- communication software for serial and network connections@@@\f3kermit(1)\f1 .\" index@\f1communication software for serial and network connections@@@\f3kermit(1)\f1 .\" toc@\f3kermit(1)\f1:\0\0\f4kermit\f1@@@communication software for serial and network connections .\" $Header: keylogin.1,v 72.3 94/09/19 15:58:31 ssa Exp $ .TA k .TH keylogin 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME keylogin \- decrypt and store a user's secret key .SH SYNOPSIS .C keylogin .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .CR keylogin prompts the user for a login password, which it uses to decrypt the user's secret key. The decrypted key is then stored by the local keyserv process, .CR keyserv. .PP Normally, .CR login does this work when the user logs onto the system; .CR keylogin may be required if the user logs in without a password. .SH EXAMPLES .C keylogin .PP .C Password: xxxxx .SH WARNINGS For .CR keylogin to succeed, both NIS and the keyserv process, .CR keyserv , must be running. .SH AUTHOR .CR keylogin was developed by Sun Microsystems, Inc. .SH SEE ALSO .PP chkey(1), login(1), keylogout(1), keyserv(1M), newkey(1M), publickey(4). .\" .\" index@\f4keylogin\f1 \- decrypt and store secret key@@@\f3keylogin(1)\f1 .\" index@\f1decrypt and store secret key@@@\f3keylogin(1)\f1 .\" index@\f1secret key, decrypt and store@@@\f3keylogin(1)\f1 .\" .\" toc@\f3keylogin(1)\f1:\0\0\f4keylogin\f1@@@decrypt and store secret key .\" $Header: keylogout.1,v 72.3 94/09/19 15:58:54 ssa Exp $ .TA k .TH keylogout 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME keylogout \- delete a secret key .SH SYNOPSIS .C keylogout .RC [ -f ] .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .CR keylogout deletes the key stored in the .C keyserv process. .PP Further access to the key is revoked and background and scheduled jobs that need secure RPC services will fail. Current session keys may remain valid, however, until they expire or are refreshed. .SS Options The .CR keylogout routine supports the following option: .RS .TP .C -f Forces the removal of root's secret key. If performed on a NFS server, this will disable secure NFS. .RE .SH WARNINGS For .CR keylogout to succeed, NIS and the keyserv process, .CR keyserv , must be running. .PP Trying to execute .CR keylogout from root will produce the following warning if the .C -f option is not used: .RS .TP .C "keylogout by root would break all servers that use secure rpc!" .TP .C "root may use keylogout -f to do this (at our own risk!)" .RE .PP Adding the .CR keylogout command to a user's .CR .logout file is not recommended, since a single copy of the key is maintained for each machine and will affect other sessions on the same machine. .SH AUTHOR .CR keylogout was developed by Sun Microsystems, Inc. .SH SEE ALSO chkey(1), login(1), keylogin(1), keyserv(1M), newkey(1M), publickey(4). .\" .\" index@\f4keylogout\f1 \- delete secret key@@@\f3keylogout(1)\f1 .\" index@\f1delete secret key@@@\f3keylogout(1)\f1 .\" index@\f1secret key, delete@@@\f3keylogout(1)\f1 .\" .\" toc@\f3keylogout(1)\f1:\0\0\f4keylogout\f1@@@delete secret key .\" $Header: keysh.1,v 72.6 94/09/06 15:03:49 ssa Exp $ .TA k .TH keysh 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME keysh \- context-sensitive softkey shell .SH SYNOPSIS .C keysh .SH DESCRIPTION .C keysh is an extension of the standard Korn-shell (for a description of the basic Korn-shell functionality, see .IR ksh (1)). .PP .C keysh uses hierarchical softkey menus and context-sensitive help to aid users in building command-lines, combining the power of the Korn-shell with the ease-of-use of a menu system. .PP And .C keysh is entirely data-driven, allowing its menus and help to be easily extended as needed. .PP Note that during .C keysh invocation, the environment variable .C $TERM must specify the terminal type, as defined in the .IR terminfo (4) database (see .SM ENVIRONMENT VARIABLES below). .SH COMMAND ENTRY .C keysh continually parses the command-line and always presents the user with an appropriate set of .I current choices on the softkey labels. .PP The user can select these softkeys to create readable .I softkey commands on the command-line. .C keysh automatically translates these softkey commands into equivalent .SM .I HP-UX .I commands prior to executing them. .PP Alternatively, the user can ignore the softkeys altogether in favor of entering the traditional .SM HP-UX commands directly, as when using the Korn-shell. .PP During command entry, .C keysh ordinarily displays a .I status-line near the bottom of the screen. This status-line contains information such as the host name, current directory, and time and date. .PP Whenever the user .I must perform an action to complete the current softkey command, .C keysh temporarily displays a .I prompt message in place of the status-line. This message briefly describes the required action. .SS Softkey Types .C keysh presents four basic softkey types: .RS .TP 15 .C --Help-- Selecting the .C --Help-- softkey causes .C keysh to display help information associated with the next selected softkey, rather than actually performing its action. .TP .C --More-- If there are more current choices than there are softkeys, .C keysh breaks the choices into banks and displays a special .C --More-- softkey along with the first bank. Selecting the .C --More-- softkey causes .C keysh to display the next bank of softkeys in sequence, eventually cycling back to the first. .TP .RI < param > .I parameter softkeys are displayed as a name enclosed between a pair of less-than and greater-than symbols. They indicate that the user-supplied text (such as a file name) should be entered into the command-line at that point, rather than actually selecting the softkey. (Actually selecting the softkey only causes .C keysh to display a hint message on the status line; the command-line remains unchanged.) .TP .C option All other softkeys are .I option softkeys that can be used to insert the corresponding command or option name into the command-line. .PP Softkeys can be selected from left to right. .SS Editing The Command-Line .C keysh supports the normal Korn-shell command-line editing modes. In addition, .C keysh also recognizes the cursor movement and editing keys found on most terminals, as defined in the .IR terminfo (4) database. These include: .TP 20 Clear the screen and command-line. If the screen is scrolled, clear only from the cursor position to the end of scrolling memory. .TP Clear from the cursor position to the end of the command-line. .TP Clear the entire command-line. .TP Translate any softkey commands in the current command-line and then edit the result. .TP Delete the character under the cursor. .TP Toggle between insert and overwrite modes. .TP Recall the previous/next command from the history buffer. .TP Move the cursor left/right. .TP Move the cursor to the beginning/end of the command-line. .TP If no key is present, perform the function (see above). Otherwise, if no .C --Help-- softkey is present, perform the .C --Help-- function (also see above). Otherwise, perform the normal tab function. .TP Move the cursor to the beginning of the previous word. .TP Redraw the lower lines of the screen and restore any necessary terminal modes. .SS Visible Softkey Commands If the .C visibles configuration option is enabled (see .SM CONFIGURATION below), .C keysh displays a list of configured softkey commands on the softkey labels whenever it is expecting a new command. This is the the top-level softkey menu. .PP If the user selects one of these softkey commands, .C keysh inserts its command name into the command-line then displays a sub-menu listing the command's major parameters and/or options. .PP The user can then (from left to right) select option softkeys and/or enter text in place of parameter softkeys. .C keysh automatically navigates the hierarchical softkey menu, always presenting the user with an appropriate set of current choices on the softkey labels. .PP Note that .C keysh automatically redisplays the top-level softkey menu when it detects that a command separator (such as a pipe or semi-colon) has been entered, thus allowing the user to use softkeys for subsequent commands on the command-line as well as the first. .SS Invisible Softkey Commands If the .C invisibles configuration option is enabled (see .SM CONFIGURATION below) and .C keysh recognizes a traditional .SM HP-UX command being entered, it gives the user one last chance to use the softkeys by again presenting an appropriate set of current choices on the softkey labels. As with the top-level softkey menu options, the user can choose to ignore the softkeys in favor of entering the traditional .SM HP-UX options directly. .SS Backup Softkeys If the .C backups configuration option is enabled (see .SM CONFIGURATION below), .C keysh displays the .I backup softkeys and programs the terminal function keys appropriately whenever it has no other softkeys to display (such as when a command is running). These provide the traditional static softkey control which many users may be used to. .SS Traditional HP-UX Commands If the user enters a traditional .SM HP-UX command when .C keysh is displaying its top-level softkey menu, .C keysh simply displays the backup softkeys and allows the user to proceed. .PP If .C keysh subsequently detects a command separator, it again redisplays the top-level softkey menu. .SS Softkey Command Syntax Errors Many softkey commands present the user with a set of softkey options from which exactly one (or at least one) .I must be selected. If the user fails to do this, .C keysh treats it as a syntax error, displaying an error message and not accepting the command until the error has been corrected. .PP Similarly, many softkey commands require that the user enter one or more softkey parameters before the command is semantically complete. If the user fails to do this, .C keysh again treats it as a syntax error. .SS Softkey Command Redirections The user can append redirection symbols (such as a less-than or greater-than symbol followed by a file name) following a softkey command. These are appended .I verbatim to the translated .SM HP-UX command. .SH USING KEYSH WITH TERMINAL SESSION MANAGER When operating under the Terminal Session Manager (see .IR tsm (1)), .C keysh displays the .C tsm softkeys instead of the backup softkeys. If desired, this interaction can be overridden by setting the .C $KEYTSM environment variable (see .SM ENVIRONMENT VARIABLES below). .PP When operating under .CR tsm , .C keysh also automatically displays the .C tsm window number in the status-line. .SH CONFIGURATION All .C keysh configuration functions are accessed through the top-level .C Keysh_config softkey command or .C kc built-in command. These functions include: .RS .TP 3 \(bu adding, placing, and deleting softkeys, .PD 0 .TP \(bu specifying backup softkeys, .TP \(bu selecting global options, .TP \(bu selecting status-line items, .TP \(bu restarting keysh, .TP \(bu writing configuration changes, and .TP \(bu undoing other configuration changes. .RE .PD .PP Each time the user changes .CR keysh 's configuration, .C keysh automatically updates the user's .C $HOME/.keyshrc file. Upon subsequent invocations, .C keysh automatically reconfigures itself as configured previously. .SS Adding, Placing, And Deleting Softkeys Any of the standard softkeys (see .SM STANDARD SOFTKEY DEFINITIONS below) can be added to the top-level softkey menu using the .C kc softkey add command. If desired, an alternate softkey label may be specified (usually in place of a cryptic .SM HP-UX command name) using the .C with_label option. .PP By default, added softkeys are placed at the end of the last .C --More-- bank of the top-level softkey menu. This placement can be overridden using the .C and_place option of the .C kc softkey add command or using the .C kc softkey move command. .PP In addition to the standard softkeys, custom softkeys can also be added from custom softkey files using the .C from_user or .C from_file options. For a description of the softkey file format, see .IR softkeys (4). .PP Note that any time a softkey is added from a particular softkey file, all of the remaining softkeys from that file are automatically loaded for use as invisible softkey commands. All softkeys from a file can also be loaded for use as invisible softkey commands using the .C kc softkey add invisibles command. .PP Any of the softkeys in the top-level softkey menu can be deleted using the .C kc softkey delete command. .SS Specifying Backup Softkeys Backup softkeys are typically specified in the user's .C $HOME/.softkeys file. The basic backup softkey definition line resembles: .IP .C backup softkey """\c .I \c .C """ literal """\c .I \c .C """; .PP Where .RI < softkey > is the softkey label to display and .RI < string > is the text string to program the terminal function key with. A maximum of eight backup softkeys can be specified. .PP Note that backup softkeys must be explicitly added using the .C kc softkey add backups command before .C keysh can program them. .SS Selecting Global Options Various global options can be configured using the .C kc option command, including: .RS .TP 15 .C backups Enable or disable the programming of the backup softkeys. .TP .C help Enable or disable the .C --Help-- softkey. .TP .C invisibles Enable or disable the recognition of invisible softkey commands. .TP .C prompts Enable or disable the automatic generation of prompt messages. When enabled, .C keysh displays a prompt message whenever the user .I must perform an action to complete the current softkey command. This message briefly describes the required action. .TP .C selectors Enable or disable the use of keyboard selectors. When enabled, .C keysh displays an upper-case selector character in each softkey label. Typing the unquoted (upper-case) character selects the softkey just as if its corresponding function key had been pressed. Quoting the selector character in any way restores its traditional meaning. Selector keys are intended to be used on terminals that do not support a sufficient number of softkeys. .TP .C translations Enable or disable the display of HP-UX command translations. .TP .C visibles Enable or disable the presentation and recognition of visible softkey commands. .RE .SS Selecting Status-Line Items Various information items can be configured into the status-line displayed at the bottom of the screen using the .C kc status_line command, including: .RS .TP 15 .C host_name The host name. .TP .C user_name The user name. .TP .C current_dir The current directory. .TP .C mail_status The mail status based on the .C $MAIL environment variable (i.e., .CR "No mail" , .CR "You have mail" , or .CR "You have new mail" ). .TP .C date The date. .TP .C time The time of day. .RE .PP In addition, the .C $KEYSH environment variable, if set, is always displayed first in the status-line. .SS Restarting Keysh .C keysh can be forced to reread the .C $HOME/.keyshrc file with the .C kc restart command. This command is typically used to update a .C keysh to a new configuration specified in another window. .PP .C keysh can also be forced to remove the .C $HOME/.keyshrc file and restart from the default user configuration with the .C kc restart default command. .SS Writing Configuration Changes .C keysh can be forced to rewrite the .C $HOME/.keyshrc file with the .C kc write command. .SS Undoing Other Configuration Changes .C keysh can also be forced to rewrite the .C $HOME/.keyshrc file with its original contents, thus undoing all configuration changes made since .C keysh was invoked, using the .C kc undo command. .SS Scaling Keysh Functionalities .C keysh provides a scalable set of functionalities which can be tailored to suit personal preferences. .PP For users who are familiar with the .SM HP-UX command names (though not necessarily with the command options) or for users who prefer to usually have the .C tsm softkeys visible, the command .C kc options visibles off prevents .C keysh from displaying its top-level softkey menu while waiting for a command; instead, it displays the backup softkeys or .C tsm softkeys, as appropriate. .RC ( keysh start-up time can then be decreased significantly by editing the .C $HOME/.keyshrc file and removing the lines which add visible softkeys.) .PP For users who are also familiar with the .SM HP-UX command options, the command .C kc options invisibles off prevents .C keysh from displaying softkey menus for invisible softkey commands, also. .PP And for users who have no need for the backup softkeys, the command .C kc options backups off prevents .C keysh from ever programming the backup softkeys. .PP Note that if .CR visibles , .CR invisibles , and .C backups are all turned off, .C keysh performs .I no softkey processing at all. .C keysh effectively transforms into a Korn-shell which displays a status-line and recognizes the cursor movement and editing keys. .SH EXAMPLES To add the .C od (see .IR od (1)) softkey to the end of the top-level softkey menu and label it .CR Octal_dump , .IP .C "kc softkey add od with_label Octal_dump" .PP To add the .IR paste (1) softkey to the beginning of the top-level softkey menu and label it .CR Paste , .IP .C "kc softkey add paste and_place as_first_softkey" .PP To add the custom emacs softkey from the file .C ~rpt/.softkeys to the top-level softkey menu immediately before the .C ls (see .IR ls (1)) softkey, .IP .C "kc softkey add emacs from_user rpt and_place before_softkey ls" .PP To add all invisible softkeys from the file .CR ~rpt/.softkeys , .IP .C "kc softkey add invisibles from_user rpt" .PP To add the backup softkeys from the file .CR $HOME/.softkeys , .IP .C "kc softkey add backups" .PP To delete the .C Edit_file softkey from the top-level softkey menu, .IP .C "kc softkey delete Edit_file" .PP To disable the .C --Help-- softkey, .IP .C "kc options help off" .PP To configure the user name into the status-line, .IP .C "kc status_line user_name on" .PP To configure the exit-value of the last command executed into the status-line, .IP .C KEYSH="\e${?#0}" .PP To list the ten largest files in the current directory, .IP .C "ls long_format | Sort_lines numerically reverse_order" .C " starting_at_field 5 | head" .SH STANDARD SOFTKEY DEFINITIONS .CR Copy_files , .CR Move_files , .CR Print_files , .CR Set_file_attribs , .CR Switch . .PP .CR adjust , .CR ar , .CR bdf , .CR cal , .CR cancel , .CR cat , .CR cd , .CR cdb , .CR chatr , .CR chgrp , .CR chmod , .CR chown , .CR cmp , .CR col , .CR comm , .CR cpio , .CR cut , .CR dd , .CR df , .CR diff , .CR dircmp , .CR disable , .CR du , .CR elm , .CR enable , .CR exit , .CR find , .CR fold , .CR grep , .CR head , .CR jobs , .CR kill , .CR lp , .CR lpstat , .CR ls , .CR mailx , .CR make , .CR man , .CR mkdir , .CR more , .CR nm , .CR nroff , .CR od , .CR paste , .CR pg , .CR pr , .CR ps , .CR remsh , .CR rlogin , .CR rm , .CR rmdir , .CR sdiff , .CR set , .CR shar , .CR sort , .CR tail , .CR tar , .CR tcio , .CR tee , .CR touch , .CR tr , .CR umask , .CR uname , .CR vi , .CR wc , .CR who , .CR write , .CR xd , .CR xdb . .SH ENVIRONMENT VARIABLES .TP 15 .C TERM Specifies the terminal type, as defined in the .IR terminfo (4) database. This variable must be either part of .CR keysh 's invocation environment or it must be set within one of the standard Korn-shell start-up files. .TP .C COLUMNS Specifies the number of columns in the terminal screen if different than the .IR terminfo (4) default. .TP .C LINES Specifies the number of lines in the terminal screen if not the same as the .IR terminfo (4) default. .TP .C PAGER Specifies the preferred pager to be used to display help. The default is .C more (see .CR more (1)). .TP .C TZ Specifies the time-zone to be used for time and date representations on the status-line. The default is .CR en_US.roman8 . .TP .C KEYBEL Specifies the character sequence sent to the terminal by .C keysh to ring the bell. The default is .CR ^G . .TP .C KEYENV Specifies an alternate .C keysh configuration file. The default is .CR $HOME/.keyshrc . .TP .C KEYESC Specifies the maximum allowable delay between characters (in milliseconds) if they are to be treated as part of a terminal escape sequence. The default is 350 ms. .TP .C KEYKSH If set, specifies that .C keysh should mimic the behavior of the Korn-shell as closely as possible. No softkeys or status-line are displayed. This mode is particularly useful over slow modem lines. .TP .C KEYLOC If set, specifies that .C keysh should leave the terminal keypad in local mode while commands are being entered. This mimics the behavior of the Korn-shell. .TP .C KEYPS1 If set, specifies that .C keysh should not reset the initial values of .CR $PS1 , .CR $PS2 , and .CR $PS3 . Note that .C $PS1 must be a constant character string in order for .C keysh to recognize it and provide subsequent softkey assistance. .TP .C KEYSH Specifies arbitrary text to be included in the .C keysh status-line. .TP .C KEYSIM If set, specifies that .C keysh should always simulate softkey labels and not use the built-in labels on .SM HP terminals. .TP .C KEYTSM If set, specifies that .C keysh should .I not use the .C tsm softkeys when .C tsm is running. In this case, the user can either use the .CR "tsm hotkey" , the backup softkeys, or the .C Switch softkey command (see .SM STANDARD SOFTKEY DEFINITIONS above) to switch .C tsm windows. .SH KSH DIFFERENCES .C keysh is an extension of .IR ksh (1) with the following exceptions: .SS Screen Updates .C keysh optimizes its display output to take advantage of available terminal capabilities. Unlike the Korn-shell which often has to redraw large portions of the command-line, .C keysh can simply insert or delete characters at the appropriate screen position. .PP This makes .C keysh significantly faster over slow modem lines, especially if the .C $KEYKSH environment variable is set (see .SM ENVIRONMENT VARIABLES above). .SS Emacs-Mode Editing The new .C v command performs the function of the vi-mode .C v command. .PP An initial .C ^N command recalls the history line .I following the history line executed as the previous command. This provides an easy mechanism to repeat a sequence of history commands. .PP .C gmacs editing mode is not supported; .C emacs editing mode follows the .SM GNU emacs (18.54) definition of .CR ^T . .PP The \f3^@\fP and .RC "n ^K" commands are not supported. .PP The .CI M- and .CI M-] alias functions are not supported (in lieu of true softkey support). .SS Vi-Mode Editing The new .C o command performs the function of the emacs-mode .C ^O command. .PP An initial .C j command recalls the history line .I following the history line executed as the previous command. This provides an easy mechanism to repeat a sequence of history commands. .PP The .C | command is not supported. .PP The \f3@\f2\f1 alias function is not supported (in lieu of true softkey support). .PP The .C u command performs an emacs-style nested undo; .CR u performs a traditional vi-style undo. .SH WARNINGS .C keysh requires that the .C $TERM environment variable be set appropriately in your .C $HOME/.profile file. It also requires that .C $LINES and .C $COLUMNS be set appropriately if running on a non-standard size terminal. Otherwise, an error message or a garbled screen display results. .PP .C keysh requires that option softkeys be selected from left to right. When editing a command-line, it is possible to back up and insert a softkey out-of-order -- resulting in a command error. .PP .C keysh initializes .CR $PS1 , .CR $PS2 , and .C $PS3 and types them .I read-only \(em do not change them. Instead, use .C $KEYSH to display additional status information. .PP .C keysh normally maintains the .C $HOME/.keyshrc file without user intervention; however, start-up errors may occasionally occur and persist. In this case, either execute the command .C kc restart default (to remove the file and revert to the default user configuration) or execute the command .C kc write (to rewrite the file with the current configuration). .PP .C keysh assumes that HP-UX commands are not heavily aliased; otherwise unexpected command translations may occur. .PP .C keysh neglects the effects of the Korn-shell expansion mechanisms when counting command-line parameters, causing it to occasionally underestimate the true number of parameters specified. The .RC * emacs-mode or vi-mode editing command can often be used to pre-expand these parameters. .PP The .RC v emacs-mode editing command and .C v vi-mode editing command cannot be used to edit (pre-translated) softkey commands, since no subsequent command translation can occur. .PP Adding a large number of softkeys can cause .C keysh to overflow a 1-Mbyte Korn-shell data size limitation, causing disconcerting behavior. .PP .C keysh can only program the function keys on terminals whose .IR terminfo (4) entry defines the .C pfkey capability; similarly, it can only use hardware softkey labels on terminals whose .IR terminfo (4) entry defines the .C pln capability (along with specifying .C lh equal to 2). .PP The default value for .C $KEYESC was chosen to provide reasonable response in both local and networked environments. If keysh misinterprets quickly typed emacs-mode or vi-mode editing commands as terminal escape sequences, it may be necessary to decrease this value. .PP Specifying a .C \en (new-line) in the literal key sequence for a backup softkey causes undesired results on .SM HP terminals; use a .C \er (carriage-return) instead. .PP .C keysh does not display .C tsm softkeys when simulating softkey labels. .PP A limited number of environment variables and arguments are exported to the pager when displaying help. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the language in which softkeys and messages are displayed. .PP .C LC_TIME determines the format and contents of date and time strings in the status-line. .SS International Code Set Support Single-byte character code sets are supported. .SH AUTHOR .C keysh was developed by HP and AT&T. .SH FILES .TP 32 .C /usr/bin/keysh main executable .TP .C /usr/lib/keysh/builtins .C Keysh_config softkey definition file .TP .C /usr/lib/keysh/$LANG/softkeys standard softkey definitions file .TP .C /usr/lib/keysh/$LANG/keyshrc default user configuration file .TP .C /usr/lib/nls/$LANG/keysh.cat message catalog .TP .C $HOME/.keyshrc user configuration file .TP .C $HOME/.softkeys user softkey definitions file .SH SEE ALSO ksh(1), tsm(1), softkeys(4), terminfo(4). .\" .\" index@\f4keysh\f1 \- context-sensitive softkey shell@@@\f3keysh(1)\f1 .\" index@context-sensitive softkey shell@@@\f3keysh(1)\f1 .\" index@softkey shell, context-sensitive@@@\f3keysh(1)\f1 .\" index@shell, context-sensitive softkey@@@\f3keysh(1)\f1 .\" .\" toc@\f3keysh(1)\f1:\0\0\f4keysh\f1@@@context-sensitive softkey shell .\" $Header: kill.1,v 76.1 95/08/03 17:58:28 ssa Exp $ .TA k .TH kill 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME kill \- send a signal to a process; terminate a process .SH SYNOPSIS .CR kill .RC \|[ -s .IR signame ]\| \0pid\0 ... .PP .CR kill .RC \|[ -s .IR signum ]\| \0pid\0 ... .PP .CR "kill -l" .SS Obsolescent Versions: .CI "kill -" signame\0pid\0\f1...\fP .PP .CI "kill -" signum\0pid\0\f1...\fP .SH DESCRIPTION The .CR kill command sends a signal to each process specified by a .I pid process identifier. The default signal is .CR SIGTERM , which normally terminates processes that do not trap or ignore the signal. .PP .IR pid is a process identifier, an unsigned or negative integer that can be one of the following: .RS .TP .RC > \00 The number of a process. .TP .RC = \00 All processes, except special system processes, whose process group .SM ID is equal to the process group .SM ID of the sender. .TP .RC = -1 All processes, except special system processes, if the user has appropriate privileges. Otherwise, all processes, except special system processes, whose real or effective user .SM ID is the same as the user .SM ID of the sending process. .TP .RC < -1 All processes, except special system processes, whose process group .SM ID is equal to the absolute value of .IR pid and whose real or effective user .SM ID is the same as the user of the sending process. .RE .PP Process numbers can be found with the .CR ps command (see .IR ps (1)) and with the built-in .CR jobs command available in some shells. .SS Options .CR kill recognizes the following options: .RS .TP 18 .CR -l \0\0\0\0(ell) List all values of .IR signame supported by the implementation. No signals are sent with this option. The symbolic names of the signals (without the .CR SIG prefix) are written to standard output, separated by spaces and newlines. .TP .CI -s \0signame Send the specified signal name. The default is .CR SIGTERM , number .CR 15 . .IR signame can be specified in upper- and/or lowercase, with or without the .CR SIG prefix. These values can be obtained by using the .CR -l option. The symbolic name .CR SIGNULL represents signal value zero. See "Signal Names and Numbers" below. .TP .CI -s \0signum Send the specified decimal signal number. The default is .CR 15 , .CR SIGTERM . See "Signal Names and Numbers" below. .TP .CI - signame (Obsolescent.) Equivalent to .CI -s \0signame\f1. .TP .CI - signum (Obsolescent.) Equivalent to .CI -s \0signum\f1. .SS Signal Names and Numbers The following table describes a few of the more common signals that can be useful from a terminal. For a complete list and a full description, see the header file .CR and the manual entry .IR signal (5). .PP .TS center tab(@); cf2 cf2 lf3 lf3 cf4p+1 lf4p+1 lf1 lf1 . signum@signame@Name@Description _ 0@SIGNULL@Null@Check access to \f2pid\fP 1@SIGHUP@Hangup@Terminate; can be trapped 2@SIGINT@Interrupt@Terminate; can be trapped 3@SIGQUIT@Quit@Terminate with core dump; can be trapped 9@SIGKILL@Kill@Forced termination; cannot be trapped 15@SIGTERM@Terminate@Terminate; can be trapped 24@SIGSTOP@Stop@Pause the process; cannot be trapped 25@SIGTSTP@Terminal stop@Pause the process; can be trapped 26@SIGCONT@Continue@Run a stopped process .TE .PP .CR SIGNULL .RC ( 0 ), the null signal, invokes error checking but no signal is actually sent. This can be used to test the validity or existence of .IR pid . .PP .CR SIGTERM .RC ( 15 ), the (default) terminate signal, can be trapped by the receiving process, allowing the receiver to execute an orderly shutdown or to ignore the signal entirely. For orderly operations, this is the perferred choice. .PP .CR SIGKILL .RC ( 9 ), the kill signal, forces a process to terminate immediately. Since .CR SIGKILL cannot be trapped or ignored, it is useful for terminating a process that does not respond to .CR SIGTERM . .PP .PP The receiving process must belong to the user of the sending process, unless the user has appropriate privileges. .PP As a single special case, the continue signal .SM SIGCONT can be sent to any process that is a member of the same session as the sending process. .SH RETURN VALUE Upon completion, .CR kill returns with one of the following values: .RS .TP 5 .CR \00 At least one matching process was found for each .I pid operand, and the specified signal was successfully processed for at least one matching process. .TP .CR >0 An error occurred. .SH EXAMPLES .PP The command: .IP .C kill 6135 .PP signals process number 6135 to terminate. This gives the process an opportunity to exit gracefully (removing temporary files, etc.). .PP The following equivalent commands: .nf .IP .C kill -s SIGKILL 6135 .C kill -s KILL 6135 .C kill -s 9 6135 .C kill -SIGKILL 6135 .C kill -KILL 6135 .C kill -9 6135 .fi .PP terminate process number 6135 abruptly by sending a .CR SIGKILL signal to the process. This tells the kernel to remove the process immediately. .SH WARNINGS If a process hangs during some operation (such as I/O) so that it is never scheduled, it cannot die until it is allowed to run. Thus, such a process may never go away after the kill. Similarly, defunct processes (see .IR ps (1)) may have already finished executing, but remain on the system until their parent reaps them (see .IR wait (2)). Using .CR kill to send signals to them has no effect. .PP Some non-\c .SM HP-UX implementations provide .CR kill only as a shell built-in command. .SH DEPENDENCIES This manual entry describes the external command .CR /usr/bin/kill and the built-in .CR kill command of the POSIX shell (see .IR sh-posix (1)). Other shells, such as C and Korn (see .IR csh (1) and .IR ksh (1) respectively), also provide .CR kill as a built-in command. The syntax for and output from these built-ins may be different. .SH SEE ALSO csh(1), ksh(1), ps(1), sh(1), sh-bourne(1), sh-posix(1), kill(2), wait(2), signal(5). .SH STANDARDS CONFORMANCE .CR kill ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f1process, send signal to@@@\f3kill(1)\f1 .\" index@\f1process, terminate@@@\f3kill(1)\f1 .\" index@\f1send signal to process@@@\f3kill(1)\f1 .\" index@\f1signal to process@@@\f3kill(1)\f1 .\" index@\f1terminate a process@@@\f3kill(1)\f1 .\" index@\f4kill\f1 \- send signal to process; terminate process@@@\f3kill(1)\f1 .\" .\" toc@\f3kill(1)\f1:\0\0\f4kill\f1@@@\f1send a signal to a process; terminate a process .\" .\" fileset_database@kill.1 UX-CORE-MAN .\" $Header: ksh.1,v 76.1 95/07/11 17:25:25 ssa Exp $ .\" DSD434580 history file compatibility across various releases .TA k .TH ksh 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.10: April 1997 .SH NAME ksh, rksh \- shell, the standard/restricted command programming language .SH SYNOPSIS .C ksh .RC [\| \(+-aefhikmnoprstuvx ] .RC [\| \(+-\|o .IR option \|]\0... .RC [\| -\|c .IR string \|] .RI [\| arg\0 ...\|] .br .C rksh .RC [\| \(+-aefhikmnoprstuvx ] .RC [\| \(+-\|o .IR option \|]\0... .RC [\| -\|c .IR string \|] .RI [\| arg\0 ...\|] .SH DESCRIPTION .C ksh is a command programming language that executes commands read from a terminal or a file. .C rksh is a restricted version of the command interpreter .CR ksh , used to set up login names and execution environments whose capabilities are more controlled than those of the standard shell. See .I Invoking ksh and .I Special Commands sections later in this entry for details about command line options and arguments, particularly the .C set command. .SS Definitions .TP 15 .B metacharacter One of the following characters: .IP .CI "; & ( ) | < >" " new-line space tab" .TP .B blank A tab or space character. .TP .B identifier A sequence of letters, digits, or underscores starting with a letter or underscore. Identifiers are used as names for .B functions and .BR "named parameters" . .TP .B word A sequence of characters separated by one or more non-quoted metacharacters . .TP .B command A sequence of characters in the syntax of the shell language. The shell reads each command and carries out the desired action, either directly or by invoking separate utilities. .TP .B special command A command that is carried out by the shell without creating a separate process. Often called ``built-in commands''. Except for documented side effects, most special commands can be implemented as separate utilities. .TP .C # The .C # character is interpreted as the beginning of a comment. See .I Quoting below. .SS Commands A .B simple-command is a sequence of blank-separated words that can be preceded by a parameter assignment list. (See .I Environment below). The first word specifies the name of the command to be executed. Except as specified below, the remaining words are passed as arguments to the invoked command. The command name is passed as argument 0 (see .IR exec (2)). The .B value of a simple-command is its exit status if it terminates normally, or (octal) 200+\c .B status if it terminates abnormally (see .IR signal (5) for a list of status values). .PP A .B pipeline is a sequence of one or more .B commands separated by .CR | . The standard output of each command except the last is connected by a pipe (see .IR pipe (2)) to the standard input of the next command. Each command is run as a separate process; the shell waits for the last command to terminate. The exit status of a pipeline is the exit status of the last command in the pipeline. .PP A .B list is a sequence of one or more pipelines separated by .CR ; , .CR & , .CR && , or .CR || , and optionally terminated by .CR ; , .CR & , or .CR |& . Of these five symbols, .CR ; , .CR & , and .CR |& have equal precedence. .C && and .C || have a higher but also equal precedence. A semicolon .RC ( ; ) causes sequential execution of the preceding pipeline; an ampersand .RC ( & ) causes asynchronous execution of the preceding pipeline (that is, the shell does not wait for that pipeline to finish). The symbol .C |& causes asynchronous execution of the preceding command or pipeline with a two-way pipe established to the parent shell (known as a co-process). The standard input and output of the spawned command can be written to and read from by the parent shell using the .C -p option of the special commands .C read and .C print described later. The symbol .C && .RC (\| || ) causes the .I list following it to be executed only if the preceding pipeline returns a zero (non-zero) value. An arbitrary number of new-lines can appear in a .IR list , instead of semicolons, to delimit commands. .PP A .B command is either a simple-command or one of the following. Unless otherwise stated, the value returned by a command is that of the last simple-command executed in the command. .TP 15 .CR for\0 \f2identifier\fP\0[\| in " \f2word\fP ...\|] " "do \f2list\fP done" Each time .C for is executed, .I identifier is set to the next .I word taken from the .C in .I word list. If .CI in " word" \&... is omitted, .C for executes the .C do .I list once for each positional parameter set (see .I Parameter Substitution below). Execution ends when there are no more words in the list. .TP .CR select\0 \f2identifier\fP\0[\| in\0\f2word\fP ...\|] " do \f2list\fP done" A .C select command prints on standard error (file descriptor 2), the set of .IR word s, each preceded by a number. If .CI in " word" \&... is omitted, the positional parameters are used instead (see .I Parameter Substitution below). The .C PS3 prompt is printed and a line is read from the standard input. If this line consists of the number of one of the listed .IR word s, the value of the parameter .I identifier is set to the .I word corresponding to this number. If this line is empty, the selection list is printed again. Otherwise the value of the parameter .I identifier is set to null. The contents of the line read from standard input is saved in the parameter .CR REPLY . The .I list is executed for each selection until a .C break or end-of-file .RI ( eof ) is encountered. .TP .CR "case \f2\s-1word\s0\fP in \f1\s-1[\|[\|\fP\s0(" "\|] \f2pattern\fP [\| " | "\f2pattern\fP\|] ... " ") \f2\s-1list\s0\fP ;;\fR\s-1\|] ...\s0\fP esac" '''\" \s-1 and \s0 in above line are to compensate for larger point '''\" size used for .C font. A .C case command executes the .I list associated with the first .I pattern that matches .IR word . The form of the patterns is identical to that used for file name generation (see .I File Name Generation below). .TP .CR "if \f2\s-1list\s0\fP then \f2list\fP \f1\s-1[\|\fP\s0elif \f2\s-1list\s0\fP then" " \f2list\fP\|] ... [\|" "else \f2\s-1list\s0\fP" \|] fi '''\" \s-1 and \s0 in above line are to compensate for larger point '''\" size used for .C font. The .I list following .C if is executed and, if it returns a zero exit status, the .I list following the first .C then is executed. Otherwise, the .I list following .C elif is executed and, if its value is zero, the .I list following the next .C then is executed. Failing that, the .C else .I list is executed. If no .C else .I list or .C then .I list is executed, .C if returns a zero exit status. .TP .PD 0 .CI while \0list \0do \0list \0done .TP .CI until \0list \0do \0list \0done A .C while command repeatedly executes the .C while .IR list , and if the exit status of the last command in the list is zero, executes the .C do .IR list ; otherwise the loop terminates. If no commands in the .C do .I list are executed, .C while returns a zero exit status; .C until can be used in place of .C while to negate the loop termination test. .PD .TP .CI (\| list \|) Execute .I list in a separate environment. If two adjacent open parentheses are needed for nesting, a space must be inserted to avoid arithmetic evaluation as described below. .TP .CI {\| \0list \|;} Execute .IR list , but not in a separate environment. Note that .C { is a keyword and requires a trailing blank to be recognized. .TP .CI [[\| \0expression\0 \|]] Evaluates .I expression and returns a zero exit status when .I expression is true. See .I Conditional Expressions below, for a description of .IR expression . Note that .C [[ and .C ]] are keywords and require blanks between them and .IR expression . .TP .PD 0 .CI function \0identifier \0{\| list \|;} .TP .IC identifier \0()\0{\| list \|;} .PD Define a function referred to by .IR identifier . The body of the function is the .I list of commands between .C { and .C } (see .I Functions below). .TP .CI time \0pipeline .I pipeline is executed and the elapsed time, user time, and system time are printed on standard error. .PP The following keywords are recognized only as the first word of a command and when not quoted: .IP .C "if then else elif fi case esac for while" .C "until do done { } function select time [[ ]]" .SS Comments A word beginning with .C # causes that word and all subsequent characters up to a new-line to be ignored. .SS Aliasing The first word of each command is replaced by the text of an .BR alias , if an alias for this word has been defined. An .B alias name consists of any number of characters excluding metacharacters, quoting characters, file expansion characters, parameter and command substitution characters, and .CR = . The replacement string can contain any valid shell script, including the metacharacters listed above. The first word of each command in the replaced text, other than any that are in the process of being replaced, is tested for additional aliases. If the last character of the alias value is a .IR blank , the word following the alias is also checked for alias substitution. Aliases can be used to redefine special built-in commands, but cannot be used to redefine the keywords listed above. Aliases can be created, listed, and exported with the .C alias command and can be removed with the .C unalias command. Exported aliases remain in effect for subshells but must be reinitialized for separate invocations of the shell (see .I Invoking ksh below). .PP .I Aliasing is performed when scripts are read, not while they are executed. Therefore, for it to take effect, .C alias must be executed before the command referring to the alias is read. .PP Aliases are frequently used as a shorthand for full path names. An option to the aliasing facility allows the value of the alias to be automatically set to the full path name of the corresponding command. These aliases are called .IR "tracked aliases" . The value of a tracked alias is defined the first time the identifier is read and becomes undefined each time the .C PATH variable is reset. These aliases remain tracked so that the next reference redefines the value. Several tracked aliases are compiled into the shell. The .C -h option of the .C set command converts each command name that is an .I identifier into a tracked alias. .PP The following .I exported aliases are compiled into the shell but can be unset or redefined: .IP .ift .sp -1v .nf .C autoload='typeset -fu' .C false='let 0' .C functions='typeset -f' .C hash='alias -t -' .C history='fc -l' .C integer='typeset -i' .C nohup='nohup ' .C r='fc -e -' .C stop='kill -STOP' .C suspend='kill -STOP $$' .C true=':' .C type='whence -v' .fi .SS Tilde Substitution After alias substitution is performed, each word is checked to see if it begins with an unquoted .CR ~ . If it does, the word up to a .C / is checked to see if it matches a user name in the .C /etc/passwd file. If a match is found, the .C ~ and the matched login name are replaced by the login directory of the matched user. This is called a tilde substitution. If no match is found, the original text is left unchanged. A .CR ~ , alone or before a .CR / , is replaced by the value of the .C HOME parameter. A .C ~ followed by a .C + or .C - is replaced by the value of the parameter .C PWD and .CR OLDPWD , respectively. In addition, tilde substitution is attempted when the value of a parameter assignment begins with a .CR ~ . .SS Command Substitution The standard output from a command enclosed in parenthesis preceded by a dollar sign .RC (\| $(\f2command\fP) \|) or a pair of back single quotes (accent grave) .RC (\| \(ga\f2command\fP\(ga \|) can be used as part or all of a word; trailing new-lines are removed. In the second (archaic) form, the string between the quotes is processed for special quoting characters before the command is executed (see .I Quoting below). The command substitution .C $(cat file) can be replaced by the equivalent but faster .CR "$( followed by a space character. .TP .C PS3 Selection prompt string used within a .C select loop, by default .C #? followed by a space character. .TP .C PS4 The value of this variable is expanded for parameter substitution and precedes each line of an execution trace. If .C PS4 is unset, the execution trace prompt is .C + followed by a space character. .TP .C SHELL The path name of the shell is kept in the environment. When invoked, the shell is restricted if the value of this variable contains an .C r in the basename. .TP .C TMOUT If set to a value greater than zero, the shell terminates if a command is not entered within the prescribed number of seconds after issuing the .C PS1 prompt. .TP .C VISUAL Invokes the corresponding option when the value of this variable ends in .IR emacs , .IR gmacs , or .I vi (see .C set in .I Special Commands below). .PD .RE .PP The shell gives default values to .CR PATH , .CR PS1 , .CR PS2 , .CR MAILCHECK , .CR TMOUT , and .CR IFS . .CR HOME , .CR SHELL , .CR ENV , and .C MAIL are never set automatically by the shell (although .CR HOME , .CR SHELL , and .CR MAIL are set by .IR login (1)). .SS Blank Interpretation After parameter and command substitution, the results of substitution are scanned for field separator characters (found in .CR IFS ), and split into distinct arguments where such characters are found. .C ksh retains explicit null arguments .RC ( "\|" or .CR '\|' ) but removes implicit null arguments (those resulting from .I parameters that have no values). .SS File Name Generation Following substitution, each command .I word is processed as a pattern for file name expansion unless the .C -f option has been .CR set . The form of the patterns is the Pattern Matching Notation defined by .IR regexp (5). The word is replaced with sorted file names matching the pattern. If no file name is found that matches the pattern, the word is left unchanged. .PP In addition to the notation described in .IR regexp (5), .C ksh recognizes composite patterns made up of one or more pattern lists separated from each other with a .CR | . Composite patterns can be formed with one or more of the following: .RS .TP 20 .CI ?( pattern-list ) Optionally matches any one of the given patterns. .TP .CI *( pattern-list ) Matches zero or more occurrences of the given patterns. .TP .CI +( pattern-list ) Matches one or more occurrences of the given patterns. .TP .ifn \f3\&@\&(\fP\f2pattern-list\fP\f3)\fP .ift \f4\s+1\&@\&\s-1(\fP\f2pattern-list\fP\f4)\fP Matches exactly one of the given patterns. .TP .CI !( pattern-list ) Matches anything, except one of the given patterns. .RE .SS Quoting Each of the .I metacharacters listed above (See .I Definitions above) has a special meaning to the shell and causes termination of a word unless quoted. A character can be .I quoted (i.e., made to stand for itself) by preceding it with a .CR \e . The pair .CI \e new-line is ignored. All characters enclosed between a pair of single quote marks .RC ( '\|' ), are quoted. A single quote cannot appear within single quotes. Inside double quote marks .ifn (\f3""\fP), .ift (\f4"\|"\fP), parameter and command substitution occurs and .C \e quotes the characters .CR \e , .CR \(ga , .ifn \f3"\fP, .ift \f4"\fP, and .CR $ . .C $* and .ifn \f3\s+1$@\s0\fP .ift \f4\s+1$@\s0\fP have identical meanings when not quoted or when used as a parameter assignment value or as a file name. However, when used as a command argument, .C "$*" is equivalent to .ifn \f3"$1\fP\f2d\fP\f3\|$2\fP\f2d\fP\...\f3"\fP, .ift \f4"$1\fP\f2d\fP\f4\|$2\fP\f2d\fP\|...\f4"\fP, where .I d is the first character of the .C IFS parameter, whereas .ifn \f3"$\s+1@"\s0\fP .ift \f4"$\s+1@"\s0\fP is equivalent to .C "$1"\| .C "$2"\| \&...\|. Inside back single quote (accent grave) marks .RC ( \(ga\|\(ga ) .C \e quotes the characters .CR \e , .CR \(ga , and .CR $ . If the back single quotes occur within double quotes, .CR \e also quotes the character .ifn \f3"\fP. .ift \f4"\fP. .PP The special meaning of keywords or aliases can be removed by quoting any character of the keyword. The recognition of function names or special command names listed below cannot be altered by quoting them. .SS Arithmetic Evaluation The ability to perform integer arithmetic is provided with the special command .CR let . Evaluations are performed using long arithmetic. Constants take the form .RC [\|\f2base\fP # \|]\f2n\fP, where .I base is a decimal number between two and thirty-six representing the arithmetic base and .I n is a number in that base. If .I base is omitted, base 10 is used. .PP An arithmetic expression uses the same syntax, precedence, and associativity of expression of the C language. All the integral operators, other than .CR ++ , .CR -\|- , .CR ?: , and .C , are supported. Variables can be referenced by name within an arithmetic expression without using the parameter substitution syntax. When a variable is referenced, its value is evaluated as an arithmetic expression. .PP An internal integer representation of a .I variable can be specified with the .C -i option of the .C typeset special command. Arithmetic evaluation is performed on the value of each assignment to a variable with the .C -i attribute. If you do not specify an arithmetic base, the first assignment to the variable determines the arithmetic base. This base is used when parameter substitution occurs. .PP Since many of the arithmetic operators require quoting, an alternative form of the .C let command is provided. For any command beginning with .CR (( , all characters until the matching .C )) are treated as a quoted expression. More precisely, .CR (( \&...\& )) is equivalent to .C let .ifn \f3"\fP\|...\f3"\fP. .ift \f4"\fP\|...\f4"\fP. .SS Prompting When used interactively, the shell prompts with the value of .C PS1 before reading a command. If at any time a new-line is typed and further input is needed to complete a command, the secondary prompt (the value of .CR PS2 ) is issued. .SS Conditional Expressions. A .I conditional expression is used with the .C [[ compound command to test attributes of files and to compare strings. Word splitting and file name generation are not performed on the words between .C [[ and .CR ]] . Each expression can be constructed from one or more of the following unary or binary expressions: .RS .TP 20 .CI -a \0file True if .I file exists. .PD 0 .TP .CI -b \0file True if .I file exists and is a block special file. .TP .CI -c \0file True if .I file exists and is a character special file. .TP .CI -d \0file True if .I file exists and is a directory. .TP .CI -f \0file True if .I file exists and is an ordinary file. .TP .CI -g \0file True if .I file exists and is has its setgid bit set. .TP .CI -h \0file True if .I file exists and is a a symbolic link. .TP .CI -k \0file True if .I file exists and is has its sticky bit set. .TP .CI -n \0string True if length of .I string is non-zero. .TP .CI -o \0option True if option named .I option is on. .TP .CI -p \0file True if .I file exists and is a fifo special file or a pipe. .TP .CI -r \0file True if .I file exists and is readable by current process. .TP .CI -s \0file True if .I file exists and has size greater than zero. .TP .CI -t \0fildes True if file descriptor number .I fildes is open and associated with a terminal device. .TP .CI -u \0file True if .I file exists and is has its setuid bit set. .TP .CI -w \0file True if .I file exists and is writable by current process. .TP .CI -x \0file True if .I file exists and is executable by current process. If .I file exists and is a directory, the current process has permission to search in the directory. .TP .CI -z \0string True if length of .I string is zero. .TP .CI -H \0file True if .I file exists and is a hidden directory (see .IR cdf (4)). .TP .CI -L \0file True if .I file exists and is a symbolic link. .TP .CI -O \0file True if .I file exists and is owned by the effective user .SM ID of this process. .TP .CI -G \0file True if .I file exists and its group matches the effective group .SM ID of this process. .TP .CI -S \0file True if .I file exists and is a socket. .TP .IC file1 \0-nt \0file2 True if .I file1 exists and is newer than .IR file2 . .TP .IC file1 \0-ot \0file2 True if .I file1 exists and is older than .IR file2 . .TP .IC file1 \0-ef \0file2 True if .I file1 and .I file2 exist and refer to the same file. .TP .IC string \0= \0pattern True if .I string matches .IR pattern . .TP .IC string \0!= \0pattern True if .I string does not match .IR pattern . .TP .IC string1 \0< \0string2 True if .I string1 comes before .I string2 based on .SM ASCII value of their characters. .TP .IC string1 \0> \0string2 True if .I string1 comes after .I string2 based on .SM ASCII value of their characters. .TP .IC exp1 \0-eq \0exp2 True if .I exp1 is equal to .IR exp2 . .TP .IC exp1 \0-ne \0exp2 True if .I exp1 is not equal to .IR exp2 . .TP .IC exp1 \0-lt \0exp2 True if .I exp1 is less than .IR exp2 . .TP .IC exp1 \0-gt \0exp2 True if .I exp1 is greater than .IR exp2 . .TP .IC exp1 \0-le \0exp2 True if .I exp1 is less than or equal to .IR exp2 . .TP .IC exp1 \0-ge \0exp2 True if .I exp1 is greater than or equal to .IR exp2 . .PD .RE .PP A compound expression can be constructed from these primitives by using any of the following, listed in decreasing order of precedence. .RS .TP 35 .CI ( expression ) True, if .I expression is true. Used to group expressions. .PD 0 .TP .CI ! \0expression True if .I expression is false. .TP .IC expression1 \0&& \0expression2 True, if .I expression1 and .I expression2 are both true. .TP .IC expression1 \0|| \0expression2 True, if either .I expression1 or .I expression2 is true. .PD .RE .SS Input/Output Before a command is executed, its input and output can be redirected using a special notation interpreted by the shell. The following can appear anywhere in a simple-command or can precede or follow a command and are not passed on to the invoked command. Command and parameter substitution occurs before .I word or .I digit is used, except as noted below. File name generation occurs only if the pattern matches a single file and blank interpretation is not performed. .RS .TP 15 .CI < word Use file .I word as standard input (file descriptor .CR 0 ). .TP .CI > word Use file .I word as standard output (file descriptor .CR 1 ). If the file does not exist, it is created. If the file exists, and the .C noclobber option is on, an error occurs; otherwise, the file is truncated to zero length. .TP .CI >| word Sames as .CR > , except that it overrides the .C noclobber option. .TP .CI >> word Use file .I word as standard output. If the file exists, output is appended to it (by first searching for the end-of-file); otherwise, the file is created. .TP .CI <> word Open file .I word for reading and writing as standard input. If the file does not exist it is created. .TP .CR << [\| - \|]\f2word\fP The shell input is read up to a line that matches .IR word , or to an end-of-file. No parameter substitution, command substitution, or file name generation is performed on .IR word . The resulting document, called a .IR here-document , becomes the standard input. If any character of .I word is quoted, no interpretation is placed upon the characters of the document. Otherwise, parameter and command substitution occurs, .CI \e new-line is ignored, and .C \e must be used to quote the characters .CR \e , .CR $ , .CR \(ga , and the first character of .IR word . If .C - is appended to .CR << , all leading tabs are stripped from .I word and from the document. .TP .CI <& digit The standard input is duplicated from file descriptor .I digit (see .IR dup (2)). .TP .CI >& digit The standard output is duplicated to file descriptor .I digit (see .IR dup (2)). .TP .C <&- The standard input is closed. .TP .C >&- The standard output is closed. .TP .C <&p The input from the co-process is moved to standard input. .TP .C >&p The output to the co-process is moved to standard output. .RE .PP If one of the above is preceded by a digit, the file descriptor number cited is that specified by the digit (instead of the default .C 0 or .CR 1 ). For example: .IP .RC \&... \02>&1 .PP means file descriptor 2 is to be opened for writing as a duplicate of file descriptor 1. .PP Redirection order is significant because the shell evaluates redirections referencing file descriptors in terms of the currently open file associated with the specified file descriptor at the time of evaluation. For example: .IP .RC ... \01>\f2fname\fP\02>&1 .PP first assigns file descriptor 1 (standard output) to file .IR fname , then assigns file descriptor 2 (standard error) to the file assigned to file descriptor 1; i.e., .IR fname . On the other hand, if the order of redirection is reversed as follows: .IP .RC ... \02>&1\01>\f2fname\fP .PP file descriptor 2 is assigned to the current standard output (user terminal unless a different assignment is inherited). File descriptor 1 is then reassigned to file .I fname without changing the assignment of file descriptor 2. .PP The input and output of a .I co-process can be moved to a numbered file descriptor allowing other commands to write to them and read from them using the above redirection operators. If the input of the current .I co-process is moved to a numbered file descriptor, another .I co-process can be started. .PP If a command is followed by .C & and job control is inactive, the default standard input for the command is the empty file .CR /dev/null . Otherwise, the environment for the execution of a command contains the file descriptors of the invoking shell as modified by input/output specifications. .SS Environment The .B environment (see .IR environ (5)) is a list of name-value pairs passed to an executed program much like a normal argument list. The names must be .B identifiers and the values are character strings. The shell interacts with the environment in several ways. When invoked, the shell scans the environment and creates a parameter for each name found, gives it the corresponding value, and marks it .IR export . Executed commands inherit the environment. If the user modifies the values of these parameters or creates new ones by using the .C export or .C typeset -x commands, the values become part of the environment. The environment seen by any executed command is thus composed of any name-value pairs originally inherited by the shell whose values can be modified by the current shell, plus any additions which must be noted in .C export or .C typeset -x commands. .PP The environment for any .I simple-command or function can be augmented by prefixing it with one or more parameter assignments. A parameter assignment argument takes the form .IC identifier = value\f1. For example, .IP .CI TERM=450 \0cmd\0args .PP and .IP .CI (export\0TERM;\0TERM=450; \0cmd\0args ) .PP are equivalent (as far as the above execution of .I cmd is concerned except for special commands listed below that are preceded by a dagger). .PP If the .C -k option is set, all parameter assignment arguments are placed in the environment, even if they occur after the command name. The following echo statement prints .CR "a=b c" . After the .C -k option is set, the second echo statement prints only .CR c : .IP .C echo a=b c .br .C set -k .br .C echo a=b c .PP This feature is intended for use with scripts written for early versions of the shell, and its use in new scripts is strongly discouraged. It is likely to disappear someday. .SS Functions The .C function keyword (described in the .I Commands section above) is used to define shell functions. Shell functions are read and stored internally. Alias names are resolved when the function is read. Functions are executed like commands, with the arguments passed as positional parameters (see .I Execution below). .PP Functions execute in the same process as the caller except that command substitution of a function creates a new process. Functions share all files and present working directory with the caller. Traps caught by the caller are reset to their default action inside the function. If a function does not catch or specifically ignore a trap condition, the function terminates and the condition is passed on to the caller. A trap on .C EXIT set inside a function is executed after the function completes in the environment of the caller. Ordinarily, variables are shared between the calling program and the function. However, the .C typeset special command used within a function defines local variables whose scope includes the current function and all functions it calls. .PP The special command .C return is used to return from function calls. Errors within functions return control to the caller. .PP Function identifiers can be listed with the .C +f option of the .C typeset special command. Function identifiers and the associated text of the functions can be listed with the .C -f option. Functions can be undefined with the .C -f option of the .C unset special command. .PP Ordinarily, functions are unset when the shell executes a shell script. The .C -xf option of the .C typeset command allows a function to be exported to scripts that are executed without reinvoking the shell. Functions that must be defined across separate invocations of the shell should be placed in the .C ENV file. .SS Jobs If the .C monitor option of the .C set command is turned on, an interactive shell associates a .B job with each pipeline. It keeps a table of current jobs, printed by the .C jobs command, and assigns them small integer numbers. When a job is started asynchronously with .CR & , the shell prints a line resembling: .IP .C [1] 1234 .PP indicating that job number 1 was started asynchronously and had one (top-level) process whose process .SM ID was 1234. .PP If you are running a job and want to do something else, type the suspend character (usually .C ^Z (Ctrl-Z)) to send a .SM STOP signal to the current job. The shell then indicates that the job has been `Stopped', and prints another prompt. The state of this job can be manipulated by using the .C bg command to put it in the background, running other commands (while it is stopped or running in the background), and eventually restarting or returning the job to the foreground by using the .C fg command. A .C ^Z takes effect immediately and resembles an interrupt, since pending output and unread input are discarded when .C ^Z is typed. .PP A job run in the background stops if it tries to read from the terminal. Background jobs normally are allowed to produce output, but can be disabled by giving the .C stty tostop command. If the user sets this tty option, background jobs stop when trying to produce output. .PP There are several ways to refer to jobs in the shell. A job can be referred to by the process .SM ID of any process in the job or by one of the following: .RS .TP 20 .CI % number The job with the given number. .PD 0 .TP .CI % string Any job whose command line begins with .IR string . .TP .CI %? string Any job whose command line contains .IR string . .TP .C %% Current job. .TP .C %+ Equivalent to .CR %% . .TP .C %- Previous job. .PD .RE .PP The shell learns immediately when a process changes state. It informs the user when a job is blocked and prevented from further progress, but only just before it prints a prompt. .PP When the monitor mode is on, each background job that completes triggers any trap set for .CR CHLD . .PP Attempting to leave the shell while jobs are running or stopped produces the warning, .CR "You have stopped (running) jobs" . Use the .C jobs command to identify them. An immediate attempt to exit again terminates the stopped jobs; the shell does not produce a warning the second time. .SS Signals The .SM INT and .SM QUIT signals for an invoked command are ignored if the command is followed by .C & and the .C monitor option is off. Otherwise, signals have the values inherited by the shell from its parent, with the exception of signal 11 (but see also the .C trap command below). .SS Execution Substitutions are made each time a command is executed. If the command name matches one of the .I Special Commands listed below, it is executed within the current shell process. Next, .C ksh checks the command name to determine whether it matches one of the user-defined functions. If it does, .C ksh saves the positional parameters and then sets them to the arguments of the .I function call. The positional parameter .C 0 is set to the function name. When the .I function completes or issues a .CR return , .C ksh restores the positional parameter list and executes any trap set on .C EXIT within the function. The value of a .I function is the value of the last command executed. A function is executed in the current shell process. If a command name is not a .I special command or a user-defined .IR function , .C ksh creates a process and attempts to execute the command using .C exec (see .IR exec (2)). .PP The shell parameter .C PATH defines the search path for the directory containing the command. Alternative directory names are separated by a colon .RC ( : ). The default path is .C /usr/bin: (specifying .CR /usr/bin and the current directory in that order). Note that the current directory is specified by a null path name which can appear immediately after the equals sign, between colon delimiters, or at the end of the path list. The search path is not used if the command name contains a .CR / . Otherwise, each directory in the path is searched for an executable file. If the file has execute permissions but is not a directory or an executable object code file, it is assumed to be a script file, which is a file of data for an interpreter. If the first two characters of the script file are .CR #! , .C exec (see .IR exec (2)) expects an interpreter path name to follow. .CR exec then attempts to execute the specified interpreter as a separate process to read the entire script file. If a call to .C exec fails, .C /usr/bin/ksh is spawned to interpret the script file. All non-exported aliases, functions, and named parameters are removed in this case. If the shell command file does not have read permission, or if the .I setuid and/or .I setgid bits are set on the file, the shell executes an agent to set up the permissions and execute the shell with the shell command file passed down as an open file. A parenthesized command is also executed in a sub-shell without removing non-exported quantities. .SS Command Re-entry The text of the last .C HISTSIZE (default 128) commands entered from a terminal device is saved in a .I history file. The file .C $HOME/.sh_history is used if the .C HISTFILE variable is not set or writable. A shell can access the commands of all .I interactive shells that use the same named .CR HISTFILE . The special command .C fc is used to list or edit a portion of this file. The portion of the file to be edited or listed can be selected by number or by giving the first character or characters of the command. A single command or range of commands can be specified. If no editor program is specified as an argument to .CR fc , the value of the .C FCEDIT parameter is used. If .C FCEDIT is not defined, .C /usr/bin/ed is used. The edited command is printed and re-executed upon leaving the editor. The editor name .C - is used to skip the editing phase and to re-execute the command. In this case a substitution parameter of the form .IC old = new can be used to modify the command before execution. For example, if .C r is aliased to .CR "fc -e -" , typing .C r bad=good c re-executes the most recent command that starts with the letter .CR c and replaces the first occurrence of the string .C bad with the string .CR good . .SS Special Commands The following simple-commands are executed in the shell process. They permit input/output redirection. Unless otherwise indicated, file descriptor 1 is the default output location and the exit status, when there are no syntax errors, is zero. Commands that are preceded by .B \(dg or .B \(dg\(dg are treated specially in the following ways: .RS .TP 4 1. Variable assignment lists preceding the command remain in effect when the command completes. .PD 0 .TP 2. I/O redirections are processed after variable assignments. .TP 3. Errors cause a script that contains them to abort. .TP 4. Words following a command preceded by \(dg\(dg that are in the format of a variable assignment are expanded with the same rules as a variable assignment. This means that tilde substitution is performed after the .C = sign and word splitting and file name generation are not performed. .PD .RE .TP 15 .CR "\(dg : " [\|\f2arg\fP\0...\|] The command only expands parameters. A zero exit code is returned. .TP .CR "\(dg . \f2file\fP " [\|\f2arg\fP\0...\|] Read and execute commands from .I file and return. The commands are executed in the current shell environment. The search path specified by .C PATH is used to find the directory containing .IR file . If any arguments .I arg are given, they become the positional parameters. Otherwise the positional parameters are unchanged. The exit status is the exit status of the last command executed. It is not necessary that the execute permission bit be set for .IR file . .TP .CR "\(dg\(dg alias " [\| -tx "\|] [\|\f2name\fP[" = \f2value\fP\|]\0...\|] .C alias with no arguments prints the list of aliases in the form .IC name = value on standard output. An .I alias is defined for each name whose .I value is given. A trailing space in .I value causes the next word to be checked for alias substitution. The .C -t option is used to set and list tracked aliases. The value of a tracked alias is the full path name corresponding to the given .IR name . The value of a tracked alias becomes undefined when the value of .C PATH is reset, but the alias remains tracked. Without the .C -t option, for each .I name in the argument list for which no .I value is given, the name and value of the alias is printed. The .C -x option is used to set or print exported aliases. An exported alias is defined across sub-shell environments. Alias returns true unless a .I name is given for which no alias has been defined. .TP .CR bg\0 [\|\f2job\fP\0...\|] Puts the specified .I jobs into the background. The current job is put in the background if .I job is unspecified. See .I Jobs for a description of the format of .IR job . .TP .CR "\(dg break " [\|\f2n\fP\|] Exit from the enclosing .CR for , .CR while , .CR until , or .C select loop, if any. If .I n is specified, break .I n levels. .TP .CR "\(dg continue " [\|\f2n\fP\|] Resume the next iteration of the enclosing .CR for , .CR while , .CR until , or .C select loop. If .I n is specified, resume at the .IR n -th enclosing loop. .TP .CR cd\0 [\| -L \(or -P "\|] [\|\f2arg\fP\|] .PD 0 .TP .CI cd " old new" .PD This command can take either of two forms. In the first form it changes the current directory to .IR arg . If .I arg is .C - the directory is changed to the previous directory. The .C -L option (default) preserves logical naming when treating symbolic links. .C cd -L .. moves the current directory one path component closer to the root directory. The .C -P option preserves the physical path when treating symbolic links. .C cd -P .. changes the working directory to the parent directory of the current directory. The shell parameter .C HOME is the default .IR arg . The parameter .C PWD is set to the current directory. The shell parameter .C CDPATH defines the search path for the directory containing .IR arg . Alternative directory names are separated by a colon .RC ( : ). If .C CDPATH is null or undefined, the default value is the current directory. Note that the current directory is specified by a null path name which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If .I arg begins with a .CR / , the search path is not used. Otherwise, each directory in the path is searched for .IR arg . .IP The second form of .C cd substitutes the string .I new for the string .I old in the current directory name, .C PWD and tries to change to this new directory. .IP The .C cd command cannot be executed by .CR rksh . .TP .CR echo\0 [\|\f2arg\fP\0...\|] See .IR echo (1) for usage and description. .TP .CR "\(dg eval " [\|\f2arg\fP\0...\|] Reads the arguments as input to the shell and executes the resulting command(s). .TP .CR "\(dg exec " [\|\f2arg\fP\0...\|] Parameter assignments remain in effect after the command completes. If .I arg is given, the command specified by the arguments is executed in place of this shell without creating a new process. Input/output arguments can appear and affect the current process. If no arguments are given, the effect of this command is to modify file descriptors as prescribed by the input/output redirection list. In this case, any file descriptor numbers greater than 2 opened with this mechanism are closed when invoking another program. .TP .CR "\(dg exit " [\|\f2n\fP\|] Causes the shell to exit with the exit status specified by .IR n . If .I n is omitted, the exit status is that of the last command executed. An end-of-file also causes the shell to exit, except when a shell has the .I ignoreeof option set (see .C set below). .TP .CR "\(dg\(dg export " [\|\f2name\fP\0[ = \f2value\fP\|]\0...\|] The given .IR name s are marked for automatic export to the .I environment of subsequently executed commands. .TP .CR fc\0 [\| -e\f2ename\fP "\|] [\|" -nlr \|]\0[\|\f2first\fP\0[\|\f2last\fP\|]\|] .PD 0 .TP .CR "fc -e - " [\|\f2old\fP = "\f2new\fP\|] [\|\f2command\fP\|]" .PD In the first form, a range of commands from .I first to .I last is selected from the last .C HISTSIZE commands typed at the terminal. The arguments .I first and .I last can be specified as a number or string. A given string is used to locate the most recent command. A negative number is used to offset the current command number. The .C -l option causes the commands to be listed on standard output. Otherwise, the editor program .I ename is invoked on a file containing these keyboard commands. If .I ename is not supplied, the value of the parameter .C FCEDIT (default .CR /usr/bin/ed ) is used as the editor. Once editing has ended, the commands (if any) are executed. If .I last is omitted, only the command specified by .I first is used. If .I first is not specified, the default is the previous command for editing and \(mi16 for listing. The .C -r option reverses the order of the commands and the .C -n option suppresses command numbers when listing. In the latter, the .I command is re-executed after the substitution .IC old = new is performed. .TP .CR fg\0 [\|\f2job\fP\0...\|] Brings each .I job into the foreground in the order specified. If no .I job is specified, the current job is brought into the foreground. See .I Jobs for a description of the format of .IR job . .TP .CR getopts\0\f2optstring\0name\fP\0 [\|\f2arg\fP\0...\] Checks .I arg for legal options. If .I arg is omitted, the positional parameters are used. An option argument begins with a .C + or a .CR - . An option not beginning with .C + or .CR - , or the argument .C -\|- ends the options. .I optstring contains the letters that .I getopts recognizes. If a letter is followed by a .CR : , that option is expected to have an argument. The options can be separated from the argument by blanks. .IP .C getopts places the next option letter it finds inside variable .IR name each time it is invoked with a .C + preceding it when .I arg begins with a .CR + . The index of the next .I arg is stored in .CR OPTIND . The option argument, if any, gets stored in .CR OPTARG . .IP A leading .C : in .I optstring causes .C getopts to store the letter of an invalid option in .CR OPTARG , and to set .I name to .C ? for an unknown option and to .C : when a required option is missing. Otherwise, .C getopts prints an error message. The exit status is non-zero when there are no more options. .TP .CR jobs\0 [\| -lnp "\|] [\|\f2job\fP\0...\|]" Lists information about each given job; or all active jobs if .I job is omitted. The .C -l option lists process ids in addition to the normal information. The .C -n option only displays jobs that have stopped or exited since last notified. The .C -p option causes only the process group to be listed. See .I Jobs for a description of the format of .IR job . .TP .CR kill\0 [\| -\f2sig\fP \|]\0\f2process\fP\0... Sends either the .SM TERM (terminate) signal or the specified signal to the specified jobs or processes. Signals are given either by number or name (as given in .IR signal (5), stripped of the prefix .CR SIG ). The signal names are listed by .CR "kill -l" . No default exists; merely typing .C kill does not affect the current job. If the signal being sent is .C TERM (terminate) or .C HUP (hangup), the job or process is sent a .C CONT (continue) signal when stopped. The .I process argument can be either a process .SM ID or job. If the first argument to .C kill is a negative integer, it is interpreted as a .I sig argument and not as a process group. .TP .CI let \0arg\0\f1... Each .I arg is a separate .IR "arithmetic expression" to be evaluated. See .I "Arithmetic Evaluation" above, for a description of arithmetic expression evaluation. The exit status is 0 if the value of the last expression is non-zero, and 1 otherwise. .TP .CR "\(dg newgrp " [\|\f2arg\fP\0...\|] Equivalent to .CI "exec newgrp" " arg" \&.... .TP .CR print [\| -Rnprsu [\|\f2n\fP\|]\|]\0[\|\f2arg\fP\0...\|] The shell output mechanism. With no options or with option .C - or .CR -\|- the arguments are printed on standard output as described by .IR echo (1). Raw mode, .C -R or .CR -r , ignores the escape conventions of .IR echo . The .C -R option prints all subsequent arguments and options other than .CR -n . The .C -p option causes the arguments to be written onto the pipe of the process spawned with .C |& instead of standard output. The .C -s option causes the arguments to be written onto the history file instead of standard output. The .C -u option can be used to specify a one-digit file descriptor unit number .I n on which the output is to be placed. The default is 1. If the option .C -n is used, no new-line character is added to the output. .TP .CR pwd\0 [\| -L \(or -P \|] With no arguments prints the current working directory (equivalent to .CR "print -r - $PWD" ). The .C -L option (default) preserves the logical meaning of the current directory and .C -P preserves the physical meaning of the current directory if it is a symbolic link (see .C cd and .IR ln (1)). .TP .CR read\0 [\| -prsu "[\|\f2n\fP\|]\|] [\|\f2name\fP\|] [" ? "\f2prompt\fP\|] [\|\f2name\fP\0...\|] The shell input mechanism. One line is read and broken up into words using the characters in .C IFS as separators. In .C -r raw mode, .C \e at the end of a line does not signify line continuation. The first word is assigned to the first .IR name , the second word to the second .IR name , etc., with remaining words assigned to the last .IR name . The .C -p option causes the input line to be taken from the input pipe of a process spawned by the shell using .CR |& . If the .C -s option is present, the input is saved as a command in the history file. The option .C -u can be used to specify a one-digit file descriptor unit to read from. The file descriptor can be opened with the .C exec special command. The default value of .I n is .CR 0 . If .IR name is omitted, .C REPLY is used as the default .IR name. The return code is .CR 0 , unless an end-of-file is encountered. An end-of-file with the .C -p option causes cleanup for this process so that another process can be spawned. If the first argument contains a .CR ? , the remainder of this word is used as a .I prompt when the shell is interactive. If the given file descriptor is open for writing and is a terminal device, the prompt is placed on this unit. Otherwise the prompt is issued on file descriptor 2. The return code is .CR 0 , unless an end-of-file is encountered. .TP .CR "\(dg\(dg readonly " [\|\f2name\fP[\| = \f2value\fP\|]\0...\|] The given .IR names are marked read-only and these names cannot be changed by subsequent assignment. .TP .CR "\(dg return " [\|\f2n\fP\|] Causes a shell .I function to return to the invoking script with the return status specified by .IR n . If .I n is omitted, the return status is that of the last command executed. Only the low 8 bits of .I n are passed back to the caller. If .C return is invoked while not in a .I function or executing a script by the .C . (dot) built-in command, it has the same effect as an .C exit command. .TP .CR "set \f1[\fP\|\(+-aefhkmnopstuvx\|\f1|\fP\|\(+-o \f2option\fP" \|]\0...\0[\| \(+-A " \f2name\fP\|] [\|\f2arg\fP ...\|]" The following options are used for this command: .RS .RS .PD 0 .TP 8 .C -A Array assignment. Unset the variable .I name and assign values sequentially from the list .IR arg . If .C +A is used, the variable .I name is not unset first. .TP .C -a All subsequent defined parameters are automatically exported. .TP .C -e If the shell is non-interactive and if a command fails, execute the .C ERR trap, if set, and exit immediately. This mode is disabled while reading profiles. .TP .C -f Disables file name generation. .TP .C -h Each command whose name is an .I identifier becomes a tracked alias when first encountered. .TP .C -k All parameter assignment arguments (not just those that precede the command name) are placed in the environment for a command. .TP .C -m Background jobs are run in a separate process group and a line is printed upon completion. The exit status of background jobs is reported in a completion message. This option is turned on automatically for interactive shells. .TP .C -n Read commands and check them for syntax errors, but do not execute them. The .C -n option is ignored for interactive shells. .TP .C -o The .C -o argument takes any of several .I option names, but only one .I option can be specified with each .C -o option. If none is supplied, the current option settings are printed. The .C -o argument .I option names follow: .RS .PD .TP 18 .C allexport Same as .CR -a . .PD 0 .TP .C bgnice All background jobs are run at a lower priority. .TP .C errexit Same as .CR -e . .TP .C emacs Activates an .C emacs-\c style in-line editor for command entry. .TP .C gmacs Activates a .C gmacs-\c style in-line editor for command entry. .TP .C ignoreeof The shell does not exit on end-of-file. The command .C exit must be used. .TP .C keyword Same as .CR -k . .TP .C markdirs All directory names resulting from file name generation have a trailing .C / appended. .TP .C monitor Same as .CR -m . .TP .C noclobber Prevents redirection .C > from truncating existing files. Requires .C >| to truncate a file when turned on. .TP .C noexec Same as .CR -n . .TP .C noglob Same as .CR -f . .TP .C nolog Do not save function definitions in history file. .TP .C nounset Same as .CR -u . .TP .C privileged Same as .CR -p . .TP .C verbose Same as .CR -v . .TP .C trackall Same as .CR -h . .TP .C vi Activates the insert mode of a .C vi-\c style in-line editor until you press the .SM ESC key which puts you in move mode. A return sends the line. .TP .C viraw Each character is processed as it is typed in .C vi mode. .TP .C xtrace Same as .CR -x . .PD .RE .RE .TP .C -p Disables processing of the .C $HOME/.profile file and uses the file .C /etc/suid_profile instead of the .C ENV file. This mode is on whenever the effective uid (gid) is not equal to the real uid (gid). Turning this off causes the effective uid and gid to be set to the real uid and gid. .PD 0 .TP .C -s Sort the positional parameters. .TP .C -t Exit after reading and executing one command. .TP .C -u Treat unset parameters as an error when substituting. .TP .C -v Print shell input lines as they are read. .TP .C -x Print commands and their arguments as they are executed. .TP .C - Turns off .C -x and .C -v options and stops examining arguments for options. .TP .C -\|- Do not change any of the options; useful in setting .C $1 to a value beginning with .CR - . If no arguments follow this option, the positional parameters are unset. .PD .RE .IP Using .C + instead of .C - before a option causes the option to be turned off. These options can also be used when invoking the shell. The current set of options can be examined by using .CR $- . .IP Unless .C -A is specified, the remaining .I arg arguments are positional parameters and are assigned consecutively to .CR $1 , .CR $2 , \&...\|. If neither arguments nor options are given, the values of all names are printed on the standard output. .TP .CR "\(dg shift " [\|\f2n\fP\|] The positional parameters from .CI $ n +1 \&... are renamed .CR $1 \0...\|; default .I n is 1. The parameter .I n can be any arithmetic expression that evaluates to a non-negative number less than or equal to .CR $# . .TP .CR test\0 [\|\f2expr\fP\|] Evaluate conditional expression .IR expr . See .IR test (1) for usage and description. The arithmetic comparison operators are not restricted to integers. They allow any arithmetic expression. Four additional primitive expressions are allowed: .RS .RS .TP 20 .CI -L \0file True if .I file is a symbolic link. .PD 0 .TP .IC file1 \0-nt \0file2 True if .I file1 is newer than .IR file2 . .TP .IC file1 \0-ot \0file2 True if .I file1 is older than .IR file2 . .TP .IC file1 \0-ef \0file2 True if .I file1 has the same device and i-node number as .IR file2 . .PD .RE .RE .TP .C \(dg times Print the accumulated user and system times for the shell and for processes run from the shell. .TP .CR "\(dg trap " [\|\f2arg\fP\|]\0[\|\f2sig\fP\0...\|] .I arg is a command read and executed when the shell receives signal(s) .IR sig . (Note that .I arg is scanned once when the trap is set and once when the trap is taken.) Each .I sig can be given as a number or name of the signal. Trap commands are executed in signal number order. Any attempt to set a trap on a signal that was ignored upon entering the current shell has no effect. If .I arg is omitted or is .CR - , all traps for .I sig are reset to their original values. If .I arg is the null string, this signal is ignored by the shell and by the commands it invokes. If .I sig is .CR DEBUG , .I arg is executed after each command. If .I sig is .CR ERR , .I arg is executed whenever a command has a non-zero exit code. If .I sig is .C 0 or .C EXIT and the .C trap statement is executed inside the body of a function, the command .I arg is executed after the function completes. If .I sig is .C 0 or .C EXIT for a .C trap set outside any function, the command .I arg is executed on exit from the shell. The .C trap command with no arguments prints a list of commands associated with each signal number. .TP .CR "\(dg\(dg typeset " [\| \(+-LRZfilrtux "[\|\f2n\fP\|]\|] [\|\f2name\fP[\| = \f2value\fP\|]\|]\0... Parameter assignments remain in effect after the command completes. When invoked inside a function, a new instance of the parameter .I name is created. The parameter value and type are restored when the function completes. The following list of attributes can be specified: .RS .RS .PD 0 .TP .C -L Left justify and remove leading blanks from .IR value . If .I n is non-zero, it defines the width of the field. Otherwise, it is determined by the width of the value of first assignment. When the .I name is assigned, the value is filled on the right with blanks or truncated, if necessary, to fit into the field. Leading zeros are removed if the .C -Z option is also set. The .C -R option is turned off. .TP .C -R Right justify and fill with leading blanks. If .I n is non-zero, it defines the width of the field. Otherwise, it is determined by the width of the value of first assignment. The field is left-filled with blanks or truncated from the end if the parameter is reassigned. The .C -L option is turned off. .TP .C -Z Right justify and fill with leading zeros if the first non-blank character is a digit and the .C -L option has not been set. If .I n is non-zero, it defines the width of the field. Otherwise, it is determined by the width of the value of first assignment. .TP .C -f Cause .I name to refer to function names rather than parameter names. No assignments can be made to the .I name declared with the .C typeset statement. The only other valid options are .C -t (which turns on execution tracing for this function) and .C -x (which allows the function to remain in effect across shell procedures executed in the same process environment). .TP .C -i Parameter is an integer. This makes arithmetic faster. If .I n is non-zero, it defines the output arithmetic base; otherwise the first assignment determines the output base. .TP .C -l Convert all uppercase characters to lowercase. The uppercase .C -u option is turned off. .TP .C -r Any given .I name is marked "read only" and cannot be changed by subsequent assignment. .TP .C -t Tag the named parameters. Tags are user definable and have no special meaning to the shell. .TP .C -u Convert all lowercase characters to uppercase characters. The lowercase .C -l option is turned off. .TP .C -x Mark any given .I name for automatic export to the environment of subsequently executed commands. .PD .IP Using .C + instead of .C - causes these options to be turned off. If no .I name arguments are given but options are specified, a list of names (and optionally the values) of the parameters that have these options set is printed. Using .C + instead of .C - retains the values to be printed. If neither names nor options are given, the names and attributes of all parameters are printed. .RE .RE .TP .CR ulimit\0 [\|\f2n\fP\|] If .I n is given, impose a size limit of .I n 512 byte blocks on files written by child processes (files of any size can be read). If .I n is not given, the current limit is printed. .TP .CR umask\0 [\|\f2mask\fP\|] The user file-creation mask is set to .I mask (see .IR umask (2)). .I mask can either be an octal number or a symbolic value as described in .IR chmod (1). If a symbolic value is given, the new umask value is the complement of the result of applying .I mask to the complement of the previous umask value. If .I mask is omitted, the current value of the mask is printed. .TP .CI unalias\0 name\f1\0... The .IR parameters given by the list of .IR name s are removed from the .I alias list. .TP .CR unset\0 [\| -f \|]\0\f2name\fP\0... The parameters given by the list of .IR name s are unassigned; that is, their values and attributes are erased. Read-only variables cannot be unset. If the .C -f option is set, .IR name s refer to function names. Unsetting .CR ERRNO , .CR LINENO , .CR MAILCHECK , .CR OPTARG , .CR OPTIND , .CR RANDOM , .CR SECONDS , .CR TMOUT , and .C _ removes their special meaning even if they are subsequently assigned to. .TP .CR "\(dg wait " [\|\f2job\fP\|] Wait for the specified .I job to terminate or stop, and report its status. This status becomes the return code for the .C wait command. If .I job is not given, .C wait waits for all currently active child processes to terminate or stop. The termination status returned is that of the last process. See .I Jobs for a description of the format of a .IR job . .TP .CR whence\0 [\| -pv \|]\0\f2name\fP\0... For each .IR name , indicate how it would be interpreted if used as a command name. The .C -v option produces a more verbose report. The .C -p option does a path search for .I name even if .I name is an alias, a function, or a reserved word. .ifn .SS Invoking ksh .ift .SS Invoking \f4\s+1ksh\s0\f1 If the shell is invoked by .C exec (see .IR exec (2)), and the first character of argument zero .RC ( $0 ) is .CR - , the shell is assumed to be a login shell and commands are read first from .CR /etc/profile . The expression .C ${HOME:-.}/.profile is then evaluated and an attempt to open the resulting filename is made. If the file is opened successfully, the file is read. Next, commands are read from the file named by performing parameter substitution on the value of the environment parameter .CR ENV , if the file exists. If the .C -s option is not present and .I arg is, a path search is performed on the first .I arg to determine the name of the script to execute. When running .C ksh with .IR arg , the script .I arg must have read permission and any .I setuid and .I getgid settings are ignored. Commands are then read as described below. The following options are interpreted by the shell when it is invoked: .RS .TP 15 .CI -c \0string If the .C -c option is present, commands are read from .IR string . .PD 0 .TP .C -s If the .C -s option is present or if no arguments remain, commands are read from the standard input. Shell output, except for the output of some of the .I Special commands listed above, is written to file descriptor 2. .TP .C -i If the .C -i option is present or if the shell input and output are attached to a terminal (as reported by .IR tty (3C)), the shell is interactive. In this case .SM SIGTERM is ignored (so that .C kill 0 does not kill an interactive shell) and .SM SIGINT +1 is caught and ignored (so that .C wait is interruptible). In all cases, .SM SIGQUIT is ignored by the shell. (See .IR signal (5).) .TP .C -r If the .C -r option is present, the shell is a restricted shell. .PD .RE .PP The remaining options and arguments are described under the .C set command above. .ifn .SS rksh Only .ift .SS \f4\s+1rksh\s0\fP Only .C rksh is used to set up login names and execution environments where capabilities are more controlled than those of the standard shell. The actions of .C rksh are identical to those of .CR ksh , except that the following are forbidden: .RS .TP 3 \(bu Changing directory (see .IR cd (1)) .PD 0 .TP \(bu Setting the value of .CR SHELL , .CR ENV , or .C PATH .TP \(bu Specifying path or command names containing .C / .TP \(bu Redirecting output .RC ( > , .CR >| , .CR <> , and .CR >> ) .PD .RE .PP The restrictions above are enforced after the .C .profile and .C ENV files are interpreted. .PP When a command to be executed is found to be a shell procedure, .C rksh invokes .C ksh to execute it. Thus, the end-user is provided with shell procedures accessible to the full power of the standard shell, while being restricted to a limited menu of commands. This scheme assumes that the end-user does not have write and execute permissions in the same directory. .PP These rules effectively give the writer of the .C .profile file complete control over user actions, by performing guaranteed set-up actions and leaving the user in an appropriate directory (probably not the login directory). .PP The system administrator often sets up a directory of commands (usually .CR /usr/rbin ) that can be safely invoked by .CR rksh . .SM HP-UX systems provide a restricted editor .I red (see .IR ed (1)), suitable for restricted users. .SH COMMAND-LINE EDITING .SS In-line Editing Options Normally, each command line typed at a terminal device is followed by a new-line (carriage-return or line-feed). If either the .CR emacs , .CR gmacs , or .C vi option is set, the user can edit the command line. An editing option is automatically selected each time the .C VISUAL or .C EDITOR variable is assigned a value ending in either of these option names. .PP The editing features require that the user's terminal accept Return as carriage return without line feed and that a space character must overwrite the current character on the screen. .SM ADM terminal users should set the ``space/advance'' switch to ``space''. Hewlett-Packard terminal users should set the straps to ``bcGHxZ\ etX''. .PP The editing modes enable the user to look through a window at the current line. The default window width is 80, unless the value of .C COLUMNS is defined. If the line is longer than the window width minus two, a mark displayed at the end of the window notifies the user. The mark is a .CR > , .CR < , or .C * if the line extends respectively on the right, left, or both side(s) of the window. As the cursor moves and reaches the window boundaries, the window is centered about the cursor. .PP The search commands in each edit mode provide access to the history file. Only strings are matched, not patterns, although a leading .C ^ in the string restricts the match to begin at the first character in the line. .SS Emacs Editing Mode This mode is invoked by either the .C emacs or .C gmacs option. Their sole difference is their handling of .CR ^T . To edit, the user moves the cursor to the point needing correction and inserts or deletes characters or words. All editing commands are control characters or escape sequences. The notation for control characters is circumflex .RB ( ^ ) followed by the character. For example, .C ^F is the notation for .RC Ctrl- F . This is entered by pressing the .C f key while holding down the Ctrl (control) key. The Shift key is .I not pressed. (The notation .C ^? indicates the .SM DEL (delete) key.) .PP The notation for escape sequences is .I M- followed by a character. For example, .IC M- f (pronounced Meta f) is entered by depressing .SM ESC (ASCII 033 ) followed by .CR f . .IC M- F would be the notation for .SM ESC followed by Shift (capital) .CR F . .PP All edit commands operate from any place on the line (not only at the beginning). Neither the Return nor the Line Feed key is entered after edit commands, except when noted. .PP .TP 15 .C ^F Move cursor forward (right) one character. .PD 0 .TP .IC M- f Move cursor forward one word. (The editor's idea of a word is a string of characters consisting of only letters, digits and underscores.) .TP .C ^B Move cursor backward (left) one character. .TP .IC M- b Move cursor backward one word. .TP .C ^A Move cursor to start of line. .TP .C ^E Move cursor to end of line. .TP .CI ^] char Move cursor forward to character .I char on current line. .TP .IC M- ^]\f2char\fP Move cursor backward to character .I char on current line. .TP .C ^X^X Interchange the cursor and mark. .TP .I erase (User defined erase character as defined by the .IR stty (1) command, usually .C ^H or .CR # .) Delete previous character. .TP .C ^D Delete current character. .TP .I eof End-of-file character, normally .CR ^D , terminates the shell if the current line is null. .TP .IC M- d Delete current word. .TP .IC M- ^H (Meta-backspace) Delete previous word. .TP .IC M- h Delete previous word. .TP .IC M- ^? (Meta-\c .SM DEL\c ) Delete previous word (if interrupt character is .C ^? (\c .SM DEL, the default) this command does not work). .TP .C ^T Transpose current character with next character in .C emacs mode. Transpose two previous characters in .C gmacs mode. .TP .C ^C Capitalize current character. .TP .IC M- c Capitalize current word. .TP .IC M- l Change the current word to lowercase. .TP .C ^K Delete from the cursor to the end of the line. If preceded by a numerical parameter whose value is less that the current cursor position, delete from the given position up to the cursor. If preceded by a numerical parameter whose value is greater than the current cursor position, from the cursor up to the given position. .TP .C ^W Kill from the cursor to the mark. .TP .IC M- p Push the region from the cursor to the mark on the stack. .TP .I kill (User-defined kill character, as defined by the .IR stty (1) command, usually .C ^G or .ifn \f3\s+1@\s0\fP.) .ift \f4\s+1@\s0\fP.) Kill the entire current line. If two .I kill characters are entered in succession, all subsequent consecutive kill characters cause a line feed (useful when using paper terminals). .TP .C ^Y Restore last item removed from line (yank item back to the line). .TP .C ^L Line feed and print current line. .TP .ifn \f3^\s+1@\s0\fP .ift \f4^\s+1@\s0\fP (Null character) Set mark. .TP .IR M- space (Meta space) Set mark. .TP .C ^J (New\ line) Execute the current line. .TP .C ^M (Return) Execute the current line. .TP .C ^P Fetch previous command. Each time .C ^P is entered, the next previous command in the history list is accessed. .TP .C ^N Fetch next command. Each time .C ^N is entered the next command in the history list is accessed. .TP .IC M- < Fetch the least recent (oldest) history line. .TP .IC M- > Fetch the most recent (youngest) history line. .TP .CI ^R string Reverse search history for a previous command line containing .I string. If a parameter of zero is given, the search is forward. .I string is terminated by a Return or New-Line. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is omitted, the next command line containing the most recent .I string is accessed. In this case a parameter of zero reverses the direction of the search. .TP .C ^O Operate - Execute the current line and fetch from the history file the next line relative to current line. .TP .I M-digits (Escape) Define numeric parameter, the digits are taken as a parameter to the next command. The commands that accept a parameter are .CR ^F , .CR ^B , .IR erase , .CR ^C , .CR ^D , .CR ^K , .CR ^R , .CR ^P , .CR ^N , .CR ^] , .IC M- .\f1, .IC M- _\f1, .IC M- b\f1, .IC M- c\f1, .IC M- d\f1, .IC M- f\f1, .IC M- h\f1, .IC M- l and .IC M- ^H\f1. .TP .I M-letter Softkey. User's alias list is searched for an alias by the name .CI _ letter and if an alias of this name is defined, its value is inserted on the input queue. This .I letter must not be one of the above meta-functions. .TP .IC M- . The last word of the previous command is inserted on the line. If preceded by a numeric parameter, the value of this parameter determines which word to insert rather than the last word. .TP .IC M- _ Same as .IC M- .\f1. .TP .IC M- * Attempt file-name generation on the current word. .TP .IR M- \s-1ESC\s0 File-name completion. Replaces the current word with the longest common prefix of all filenames matching the current word with an asterisk appended. If the match is unique, a .C / is appended if the file is a directory and a space is appended if the file is not a directory. .TP .IC M- = List files matching current word pattern as if an asterisk were appended. .TP .C ^U Multiply parameter of next command by 4. .TP .C \e Escape next character. Editing characters, the user's erase, kill and interrupt (normally .CR ^? ) characters can be entered in a command line or in a search string if preceded by a .CR \e . The .C \e removes the next character's editing features (if any). .TP .C ^V Display version of the shell. .TP .IC M- # Insert a .C # at the beginning of the line and execute it. This causes a comment to be inserted in the history file. .PD .SS Vi Editing Mode There are two typing modes. Entering a command puts you into .I input mode. To edit, the user enters .I control mode by pressing .SM ESC and moves the cursor to the point needing correction, then inserts or deletes characters or words. Most control commands accept an optional repeat .I count prior to the command. .PP In vi mode on most systems, canonical processing is initially enabled and the command is echoed again if the speed is 1200 baud or greater and contains any control characters, or if less than one second has elapsed since the prompt was printed. The .SM ESC character terminates canonical processing for the remainder of the command and the user can then modify the command line. This scheme has the advantages of canonical processing with the type-ahead echoing of raw mode. .PP Setting the .C viraw option always disables canonical processing on the terminal. This mode is implicit for systems that do not support two alternate end-of-line delimiters, and can be helpful for certain terminals. .SS "Input Edit Commands" By default the editor is in input mode. .TP 15 .PD 0 .I erase Delete previous character. .RI ( erase is a user-defined erase character, as defined by the .IR stty (1) command, usually .C ^H or .CR # .) .TP .CI ^W Delete the previous blank separated word. .TP .CI ^D Terminate the shell. .TP .CI ^V Escape next character. Editing characters, erase or kill characters can be entered in a command line or in a search string if preceded by a .CR ^V . .C ^V removes the next character's editing features (if any). .TP .CI \e Escape the next .I erase or .I kill character. .PD .SS "Motion Edit Commands" These commands move the cursor. The designation .RI [ count ] causes a repetition of the command the cited number of times. .RS .TP 15 .PD 0 .RC [\f2count\fP] l Cursor forward (right) one character. .TP .RC [\f2count\fP] w Cursor forward one alphanumeric word. .TP .RC [\f2count\fP] W Cursor to the beginning of the next word that follows a blank. .TP .RC [\f2count\fP] e Cursor to end of word. .TP .RC [\f2count\fP] E Cursor to end of the current blank-delimited word. .TP .RC [\f2count\fP] h Cursor backward (left) one character. .TP .RC [\f2count\fP] b Cursor backward one word. .TP .RC [\f2count\fP] B Cursor to preceding blank separated word. .TP .RC [\f2count\fP] | Cursor to column .IR count . Default is 1. .TP .RC [\f2count\fP] f\f2c\fP Find the next character .I c in the current line. .TP .RC [\f2count\fP] F\f2c\fP Find the previous character .I c in the current line. .TP .RC [\f2count\fP] t\f2c\fP Equivalent to .C f followed by .CR h . .TP .RC [\f2count\fP] T\f2c\fP Equivalent to .C F followed by .CR l . .TP .RC [\f2count\fP] ; Repeats the last single character find command, .CR f , .CR F , .CR t , or .CR T . .TP .RC [\f2count\fP] , Reverses the last single character find command. .TP .C 0 Cursor to start of line. .TP .C ^ Cursor to first nonblank character in line. .TP .C $ Cursor to end of line. .RE .SS "Search Edit Commands" These commands access your command history. .RS .TP 18 .RC [\f2count\fP] k Fetch previous command. Each time .C k is pressed, the next earlier command in the history list is accessed. .TP .RC [\f2count\fP] - Equivalent to .CR k . .TP .RC [\f2count\fP] j Fetch next command. Each time .C j is entered, the next later command in the history list is accessed. .TP .RC [\f2count\fP] + Equivalent to .CR j . .TP .RC [\f2count\fP] G The command number .I count is fetched. The default is the first command in the history list. .TP .CI / string Search backward through history for a previous command containing .IR string . .I string is terminated by a "Return" or "New-line". If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is null, the previous string is used. .TP .CI ? string Same as .C / but search in the forward direction. .TP .C n Search for next match of the last pattern to .C / or .C ? commands. .TP .C N Search for next match of the last pattern to .C / or .CR ? , but in reverse direction. Search history for the .I string entered by the previous .C / command. .RE .SS "Text Modification Edit Commands" These commands modify the line. .RS .TP 18 .C a Enter input mode and enter text after the current character. .TP .C A Append text to the end of the line. Equivalent to .CR $a . .TP .RC [\f2count\fP] c\f2motion\fP .TP .CR c [\f2count\fP]\f2motion\fP Move cursor to the character position specified by .IR motion , deleting all characters between the original cursor position and new position, and enter input mode. If .I motion is .CR c , the entire line is deleted and input mode entered. .TP .C C Delete the current character through the end of line and enter input mode. Equivalent to .CR c$ . .TP .C S Equivalent to .CR cc . .TP .C D Delete the current character through end of line. Equivalent to .CR d$ . .TP .RC [\f2count\fP] d\f2motion\fP .TP .CR d [\f2count\fP]\f2motion\fP Move cursor to the character position specified by .IR motion , deleting all characters between the original cursor position and new position. If .I motion is .CR d , the entire line is deleted. .TP .C i Enter input mode and insert text before the current character. .TP .C I Insert text before the beginning of the line. Equivalent to the two-character sequence .CR 0i . .TP .RC [\f2count\fP] P Place the previous text modification before the cursor. .TP .RC [\f2count\fP] p Place the previous text modification after the cursor. .TP .C R Enter input mode and replace characters on the screen with characters you type in overlay fashion. .TP .RC [\f2count\f3] r\f2c\fP Replace the current character with .IR c . .TP .RC [\f2count\fP] x Delete current character. .TP .RC [\f2count\fP] X Delete preceding character. .TP .RC [\f2count\fP] . Repeat the previous text modification command. .TP .RC [\f2count\fP] ~ Invert the case of the current character and advance the cursor. .TP .RC [\f2count\fP] _ Causes the .I count word of the previous command to be appended at the current cursor location and places the editor in input mode at the end of the appended text. The last word is used if .I count is omitted. .TP .C * Appends an .C * to the current word and attempts file name generation. If no match is found, the bell rings. If a match is found, the word is replaced by the matching string and the command places the editor in input mode. .TP .SM .B ESC .TP .C \e Attempt file name completion on the current word. Replaces the current word with the longest common prefix of all filenames matching the current word with an asterisk appended. If the match is unique, a .C / is appended if the file is a directory and a space is appended if the file is not a directory. .RE .SS "Other Edit Commands" .RS .TP 18 .RC [\f2count\fP] y\f2motion\fP .TP .CR y [\f2count\fP]\f2motion\fP Yank current character through character that .I motion would move the cursor to and puts them into the delete buffer. The text and cursor are unchanged. .TP .C Y Yanks from current position to end of line. Equivalent to .CR y$ . .TP .C u Undo the last text modifying command. .TP .C U Undo all the text modifying commands performed on the line. .TP [\f2count\fP]\f3v\fP Returns the command .CI "fc -e ${VISUAL:-${EDITOR:-vi}}" " count" in the input buffer. If .I count is omitted, the current line is used. .TP .CI ^L Line feed and print current line. Has effect only in control mode. .TP .CI ^J (New\ line) Execute the current line, regardless of mode. .TP .CI ^M (Return) Execute the current line, regardless of mode. .TP .C # Equivalent to .CI I# followed by .BR Return . Sends the line after inserting a .C # in front of the line and after each new-line. Useful for inserting the current command line in the history list without executing it. .TP .C = List the filenames that match the current word if an asterisk were appended to it. .TP .ifn \f3\s+1@\s0\fP\f2letter\fP .ift \f4\s+1@\s0\fP\f2letter\fP The user's alias list is searched for an alias by the name .CI _ letter and if an alias of this name is defined, its value is inserted on the input queue for processing. .PD .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .SM LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. .PP .SM LC_CTYPE determines the classification of characters as letters, and the characters matched by character class expressions in pattern matching notation. .PP If .SM LC_COLLATE or .SM LC_CTYPE is not specified in the environment or is set to the empty string, the value of .SM LANG is used as a default for each unspecified or empty variable. If .SM LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .SM LANG. If any internationalization variable contains an invalid setting, .C ksh behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte character code sets are supported. .SH RETURN VALUE Errors detected by the shell, such as syntax errors, cause the shell to return a non-zero exit status. Otherwise, the shell returns the exit status of the last command executed (also see the .C exit command above). If the shell is being used non-interactively, execution of the shell file is abandoned. Runtime errors detected by the shell are reported by printing the command or function name and the error condition. If the line number on which the error occurred is greater than one, the line number is also printed in brackets .RC ( [\|] ) after the command or function name. .SH WARNINGS File descriptors 10 and 54 through 60 are used internally by the Korn Shell. Applications using these and forking a subshell should not depend upon them surviving in the subshell or its descendants. .PP If a command which is a .I "tracked alias" is executed, and a command with the same name is installed in a directory in the search path before the directory where the original command was found, the shell continues to load and execute the original command. Use the .C -t option of the .C alias command to correct this situation. .PP If you move the current directory or one above it, .C pwd may not give the correct response. Use the .C cd command with a full path name to correct this situation. .PP Some very old shell scripts contain a caret .RC ( ^ ) as a synonym for the pipe character .RC ( | ). Note however, .C ksh does not recognize the caret as a pipe character. .PP If a command is piped into a shell command, all variables set in the shell command are lost when the command completes. .PP Using the .C fc built-in command within a compound command causes the entire command to disappear from the history file. .PP The built-in command \f3\|.\fP \f2file\fP reads the entire file before any commands are executed. Therefore, .C alias and .C unalias commands in the file do not apply to any functions defined in the file. .PP Traps are not processed while the shell is waiting for a foreground job. Thus, a trap on .C CHLD is not executed until the foreground job terminates. .PP The .C export built-in command does not handle arrays properly. Only the first element of an array is exported to the .IR environment . .PP Background processes started from a non-interactive shell cannot be accessed by using job control commands. .PP In an international environment, character ordering is determined by the setting of .SM LC_COLLATE, rather than by the binary ordering of character values in the machine collating sequence. This brings with it certain attendant dangers, particularly when using range expressions in file name generation patterns. For example, the command, .IP .C rm [a-z]* .PP might be expected to match all file names beginning with a lowercase alphabetic character. However, if dictionary ordering is specified by .SM LC_COLLATE, it would also match file names beginning with an uppercase character (as well as those beginning with accented letters). Conversely, it would fail to match letters collated after .C z in languages such as Danish or Norwegian. .PP The correct (and safe) way to match specific character classes in an international environment is to use a pattern of the form: .IP .C rm [[:lower:]]* .PP This uses .SM LC_CTYPE to determine character classes and works predictably for all supported languages and codesets. For shell scripts produced on non-internationalized systems (or without consideration for the above dangers), it is recommended that they be executed in a non-\c .SM NLS environment. This requires that .SM LANG, LC_COLLATE, etc., be set to "C" or not set at all. .PP Be aware that the value of the .C IFS variable in the user's environment affects the behavior of scripts. .PP .C ksh implements command substitution by creating a pipe between itself and the command. If the root file system is full, the substituted command cannot write to the pipe. As a result, the shell receives no input from the command, and the result of the substitution is null. In particular, using command substitution for variable assignment under such circumstances results in the variable being silently assigned a .SM NULL value. .PP .SH AUTHOR .C ksh was developed by AT&T. .SH FILES .TP 30 .PD 0 .C /etc/passwd to find home directories .TP .C /etc/profile read to set up system environment .TP .C /etc/suid_profile security profile .TP .C $HOME/.profile read to set up user's custom environment .TP .C /tmp/sh\(** for here-documents .PD .SH SEE ALSO cat(1), cd(1), echo(1), env(1), test(1), umask(1), vi(1), dup(2), exec(2), fork(2), gtty(2), pipe(2), signal(5), umask(2), ulimit(2), wait(2), rand(3C), a.out(4), profile(4), environ(5), lang(5), #ifdef B1 regexp(5), privilege(5). #else regexp(5). #endif .\" .\" index@\f4ksh\f1 \- Korn shell command programming language@@@\f3ksh(1)\f1 .\" index@\f4rksh\f1 \- restricted Korn shell command programming language@@@\f3ksh(1)\f1 .\" index@alias \- substitute command and/or filename@@@\f3ksh(1)\f1 .\" index@break \- exit from enclosing for/next loop@@@\f3ksh(1)\f1 .\" index@case \- execute \f2list\f1 associated with \f2pattern\f1 that matches \f2word\f1@@@\f3ksh(1)\f1 .\" index@cd \- change working directory@@@\f3ksh(1)\f1 .\" index@continue \- resume next iteration of enclosing for/next loop@@@\f3ksh(1)\f1 .\" index@echo \- echo (print) arguments@@@\f3ksh(1)\f1 .\" index@eval \- read arguments as shell input and execute resulting commands@@@\f3ksh(1)\f1 .\" index@exec \- execute command without creating new process@@@\f3ksh(1)\f1 .\" index@exit \- exit shell with exit status@@@\f3ksh(1)\f1 .\" index@export \- export variable names to environment of subsequent commands@@@\f3ksh(1)\f1 .\" index@fc \- edit and execute previous command@@@\f3ksh(1)\f1 .\" index@for \- execute a do list@@@\f3ksh(1)\f1 .\" index@if \- execute command if previous command returns exit status 0@@@\f3ksh(1)\f1 .\" index@jobs \- list active jobs@@@\f3ksh(1)\f1 .\" index@kill \- terminate job or process@@@\f3ksh(1)\f1 .\" index@let \- evaluate arithmetic expression@@@\f3ksh(1)\f1 .\" index@newgrp \- equivalent to \f3exec newgrp\f1@@@\f3ksh(1)\f1 .\" index@print \- output from shell@@@\f3ksh(1)\f1 .\" index@pwd \- print current working directory@@@\f3ksh(1)\f1 .\" index@read \- input and parse a line@@@\f3ksh(1)\f1 .\" index@readonly \- mark names as unredefinable@@@\f3ksh(1)\f1 .\" index@return \- shell function return to invoking script@@@\f3ksh(1)\f1 .\" index@set \- set/define options and arguments@@@\f3ksh(1)\f1 .\" index@shift \- shift \f2argv\f1 members one position to left@@@\f3ksh(1)\f1 .\" index@test \- evaluate conditional expression@@@\f3ksh(1)\f1 .\" index@time, times \- print summary of time used by processes@@@\f3ksh(1)\f1 .\" index@trap \- trap specified signal@@@\f3ksh(1)\f1 .\" index@typeset \- control leading blanks and parameter handling@@@\f3ksh(1)\f1 .\" index@ulimit \- set size or time limits@@@\f3ksh(1)\f1 .\" index@umask \- set permissions mask for creating new files@@@\f3ksh(1)\f1 .\" index@unalias \- discard specified alias@@@\f3ksh(1)\f1 .\" index@unset \- remove definition/setting of options and arguments@@@\f3ksh(1)\f1 .\" index@until \- execute commands until expression is non-zero@@@\f3ksh(1)\f1 .\" index@wait \- wait for child process@@@\f3ksh(1)\f1 .\" index@whence \- define interpretation of name as a command@@@\f3ksh(1)\f1 .\" index@while \- execute commands while expression is non-zero@@@\f3ksh(1)\f1 .\" .\" toc@\f3ksh(1)\f1:\0\0\f2ksh\f1, \f2rksh\f1@@@shell, the standard/restricted command programming language .\" toc@\f2rksh\f1: restricted Korn shell command programming language@@@see \f3ksh(1)\f1 .\" toc@case: label in a switch statement@@@see \f3ksh(1)\f1 .\" toc@alias: substitute command and/or filename@@@see \f3ksh(1)\f1 .\" toc@break: exit from enclosing for/next loop@@@see \f3ksh(1)\f1 .\" toc@continue: resume next iteration of enclosing for/next loop@@@see \f3ksh(1)\f1 .\" toc@cd: change working directory@@@see \f3ksh(1)\f1 .\" toc@echo: echo (print) arguments@@@see \f3ksh(1)\f1 .\" toc@eval: read arguments as shell input and execute resulting commands@@@see \f3ksh(1)\f1 .\" toc@exec: execute command without creating new process@@@see \f3ksh(1)\f1 .\" toc@exit: exit shell with exit status@@@see \f3ksh(1)\f1 .\" toc@export: export variable names to environment of subsequent commands@@@see \f3ksh(1)\f1 .\" toc@fc: edit and execute previous command@@@see \f3ksh(1)\f1 .\" toc@for: execute a do list@@@see \f3ksh(1)\f1 .\" toc@if: execute command if previous command returns exit status 0@@@see \f3ksh(1)\f1 .\" toc@jobs: list active jobs@@@see \f3ksh(1)\f1 .\" toc@kill: terminate job or process@@@see \f3ksh(1)\f1 .\" toc@let: evaluate arithmetic expression@@@see \f3ksh(1)\f1 .\" toc@newgrp: equivalent to \f2exec newgrp\f1@@@see \f3ksh(1)\f1 .\" toc@print: output from shell@@@see \f3ksh(1)\f1 .\" toc@pwd: print current working directory@@@see \f3ksh(1)\f1 .\" toc@read: input and parse a line@@@see \f3ksh(1)\f1 .\" toc@readonly: mark names as unredefinable@@@see \f3ksh(1)\f1 .\" toc@return: shell function return to invoking script@@@see \f3ksh(1)\f1 .\" toc@set: set/define options and arguments@@@see \f3ksh(1)\f1 .\" toc@shift: shift \f2argv\f1 members one position to left@@@see \f3ksh(1)\f1 .\" toc@test: evaluate conditional expression@@@see \f3ksh(1)\f1 .\" toc@trap: trap specified signal@@@see \f3ksh(1)\f1 .\" toc@time, times: print summary of time used by processes@@@see \f3ksh(1)\f1 .\" toc@typeset: control leading blanks and parameter handling@@@see \f3ksh(1)\f1 .\" toc@ulimit: set size or time limits@@@see \f3ksh(1)\f1 .\" toc@umask: set permissions mask for creating new files@@@see \f3ksh(1)\f1 .\" toc@unalias: discard specified alias@@@see \f3ksh(1)\f1 .\" toc@unset: remove definition/setting of options and arguments@@@see \f3ksh(1)\f1 .\" toc@wait: wait for child process@@@see \f3ksh(1)\f1 .\" toc@whence: define interpretation of name as a command@@@see \f3ksh(1)\f1 .\" toc@while: execute commands while expression is non-zero@@@see \f3ksh(1)\f1 .\" toc@until: execute commands until expression is non-zero@@@see \f3ksh(1)\f1 .\" .\" links@ksh.1 rksh.1 .\" $Header: ls.1,v 76.2 95/08/23 17:56:11 ssa Exp $ .TA l .TH ls 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ls, l, ll, lsf, lsr, lsx \- list contents of directories .SH SYNOPSIS .CR ls .RC [ \-abcdefgilmnopqrstuxACFLR1 ] .RI [ names ] .PP .CR l .RI [ ls_options ] .RI [ names ] .br .CR ll .RI [ ls_options ] .RI [ names ] .br .CR lsf .RI [ ls_options ] .RI [ names ] .br .CR lsr .RI [ ls_options ] .RI [ names ] .br .CR lsx .RI [ ls_options ] .RI [ names ] .SH DESCRIPTION For each directory argument, the .CR ls command lists the contents of the directory. For each file argument, .CR ls repeats its name and any other information requested. The output is sorted in ascending collation order by default (see Environment Variables below). When no argument is given, the current directory is listed. When several arguments are given, the arguments are first sorted appropriately, but file arguments appear before directories and their contents. .PP If you are a user with appropriate privileges, all files except .CR . and .CR .. are listed by default. .PP There are three major listing formats. The format chosen depends on whether the output is going to a login device (determined by whether output device file is a .I tty device), and can also be controlled by option flags. The default format for a login device is to list the contents of directories in multicolumn format, with entries sorted vertically by column. (When individual file names (as opposed to directory names) appear in the argument list, those file names are always sorted across the page rather than down the page in columns because individual file names can be arbitrarily long.) If the standard output is not a login device, the default format is to list one entry per line. The .CR \-C and .CR \-x options enable multicolumn formats, and the .CR \-m option enables stream output format in which files are listed across the page, separated by commas. In order to determine output formats for the .CR \-C , .CR \-x , and .CR \-m options, .CR ls uses an environment variable, .CR COLUMNS , to determine the number of character positions available on each output line. If this variable is not set, the .I terminfo database is used to determine the number of columns, based on the environment variable .CR TERM . If this information cannot be obtained, 80 columns is assumed. .SS Options .CR ls recognizes the following options: .RS .TP 6 .CR \-a List all entries; usually entries whose names begin with a period .RC ( . ) are not listed. .TP .CR \-b Force printing of nongraphic characters to be in the octal .CI \e ddd notation. .TP .CR \-c Use time of last modification of the inode (file created, mode changed, etc.) for sorting .RC ( \-t ) or printing .RC ( \-l (ell)). .TP .CR \-d If an argument is a directory, list only its name (not its contents); often used with .CR \-l (ell) to get the status of a directory. .TP .CR \-e Print the extent attributes of the file. If any of the files has a extent attribute, this option prints the extent size, space reserved and allocation flags. This option must be used with the .CR \-l (ell) option. .TP .CR \-f Force each argument to be interpreted as a directory and list the name found in each slot. This option disables .CR \-l (ell), .CR \-t , .CR \-s , and .CR \-r , and enables .CR \-a ; the order is the order in which entries appear in the directory. .TP .CR \-g Same as .CR \-l , (ell) except that only the group is printed (owner is omitted). If both .CR \-l (ell) and .CR \-g are specified, the owner is not printed. .TP .CR \-i For each file, print the inode number in the first column of the report. When used in multicolumn output, the number precedes the file name in each column. .TP .CR \-l (ell) List in long format, giving mode, number of links, owner, group, size in bytes, and time of last modification for each file (see further DESCRIPTION and Access Control Lists below). If the time of last modification is greater than six months ago, or any time in the future, the year is substituted for the hour and minute of the modification time. If the file is a special file, the size field contains the major and minor device numbers rather than a size. .TP .CR \-m Stream output format. .TP .CR \-n The same as .CR \-l , (ell) except that the owner's UID and group's GID numbers are printed, rather than the associated character strings. .TP .CR \-o The same as .CR \-l , (ell) except that only the owner is printed (group is omitted). (If both .CR \-l (ell) and .CR \-o are specified, the group is not printed). .TP .CR \-p Put a slash .RC ( / ) after each file name if that file is a directory. .TP .CR \-q Force printing of nongraphic characters in file names as the character .RC ( ? ). .TP .CR \-r Reverse the order of sort to get reverse (descending) collation or oldest first, as appropriate. .TP .CR \-s Give size in blocks, including indirect blocks, for each entry. The first entry printed is the total number of blocks in the directory. When used in multicolumn output, the number of blocks precedes the file name in each column. .TP .CR \-t Sort by time modified (latest first) before sorting alphabetically. .TP .CR \-u Use time of last access instead of last modification for sorting .RC ( \-t option) or printing .RC ( \-l (ell) option). .TP .CR \-x Multicolumn output with entries sorted across rather than down the page. .TP .CR \-A The same as .CR \-a , except that the current directory "." and parent directory ".." are not listed. For a user with appropriate privileges, this flag defaults to ON, and is turned off by .CR \-A . .TP .CR \-C Multicolumn output with entries sorted down the columns. .TP .CR \-F Put a slash .RC ( / ) after each file name if that file is a directory or a symbolic link to a directory; put an asterisk .RC ( * ) after each file name if that file is executable; put an at sign (\f3@\f1) after each file name if that file is a symbolic link to a file; put a vertical bar .RC ( | ) after each file name if that file is a FIFO. .TP .CR \-L If the argument is a symbolic link, list the file or directory to which the link refers rather than the link itself. .TP .CR \-R Recursively list subdirectories encountered. .TP .CR \-1 (one) The file names will be listed in single column format regardless of the output device. This forces single column format to the user's terminal. .RE .PP Specifying more than one of the options in the following mutually exclusive pairs is not considered an error: .CR \-C and .CR \-l (ell), .CR \-m and .CR \-l (ell), .CR \-x and .CR \-l (ell), .CR \-C and .CR \-1 (one), .CR \-c and .CR \-u . .PP .CR ls is normally known by several shorthand-version names for the various formats: .RS .TP 6 .CR l equivalent to .CR "ls \-m" . .PD 0 .TP .CR ll equivalent to .CR "ls \-l" (ell). .TP .CR lsf equivalent to .CR "ls \-F" . .TP .CR lsr equivalent to .CR "ls \-R" . .TP .CR lsx equivalent to .CR "ls \-x" . .RE .PD .PP The shorthand notations are implemented as links to .CR ls . Option arguments to the shorthand versions behave exactly as if the long form above had been used with the additional arguments. .PP .B "Mode Bits Interpretation (\-l option)" .br The mode printed in listings produced by the .CR \-l (ell) option consists of 10 characters. The first character indicates the entry type: .RS .TP 6 .CR d Directory .PD 0 .TP .CR b Block special file .TP .CR c Character special file .TP .CR l Symbolic link .TP .CR p Fifo (also called a "named pipe") special file .TP .CR n Network special file .TP .CR s socket .TP .CR \- Ordinary file. .RE .PD .PP The next 9 characters are interpreted as three sets of three bits each which identify access permissions for owner, group, and others as follows: .IP .nf .if t \{ .sp -1v .cs R 19 __________________ \d0400 read by owner (\f3r\f1 or \f3\(mi\f1) | ________________ \d0200 write by owner (\f3w\f1 or \f3\(mi\f1) | | ______________ \d0100 execute (search directory) by owner\ (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | ____________ \d0040 read by group (\f3w\f1 or \f3\(mi\f1) | | | | __________ \d0020 write by group (\f3r\f1 or \f3\(mi\f1) | | | | | ________ \d0010 execute/search by group\ (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | | | | ______ \d0004 read by others (\f3r\f1 or \f3\(mi\f1) | | | | | | | ____ \d0002 write by others (\f3w\f1 or \f3\(mi\f1) | | | | | | | | __ \d0001 execute/search by others\ (\f3x\f1, \f3t\f1, \f3T\f1, or \f3\(mi\f1) | | | | | | | | | r w x r w x r w x .cs R .fi \} .if n \{ +------------------ 0400 read by owner (\f3r\f1 or \f3\(mi\f1) | +---------------- 0200 write by owner (\f3w\f1 or \f3\(mi\f1) | | +-------------- 0100 execute (search directory) by owner | | | (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | +------------ 0040 read by group (\f3r\f1 or \f3\(mi\f1) | | | | +---------- 0020 write by group (\f3w\f1 or \f3\(mi\f1) | | | | | +-------- 0010 execute/search by group | | | | | | (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | | | | +------ 0004 read by others (\f3r\f1 or \f3\(mi\f1) | | | | | | | +---- 0002 write by others (\f3w\f1 or \f3\(mi\f1) | | | | | | | | +-- 0001 execute/search by others | | | | | | | | | (\f3x\f1, \f3t\f1, \f3T\f1, or \f3\(mi\f1) | | | | | | | | | r w x r w x r w x .fi \} .PP Mode letters are interpreted as follows: .RS .TP 7 .CR \- Permission .I not granted in corresponding position. .TP .CR r Read permission granted to corresponding user class. .TP .CR w Write permission granted to corresponding user class. .TP .CR x Execute (or search in directory) permission granted to corresponding user class. .TP .CR s Execute (search) permission granted to corresponding user class. In addition, SUID (Set User ID) permission granted for owner, or SGID (Set Group ID) permission granted for group, as indicated by position. .TP .CR S Same as .CR s except that execute (search) permission is denied to corresponding user class. .TP .CR t (last position only) Execute (search) permission granted to others and "sticky bit" is set (see .IR chmod (2) .CR S_ISVTX description). .TP .CR T Same as .CR t except execute (search directory) permission denied to others. .RE .PP When an option is specified that results in a listing of directory and/or file sizes in bytes or blocks (such as the .CR \-s or .CR \-l (ell) option), a total count of blocks, including indirect blocks, is also printed at the beginning of the listing. .SS "Access Control Lists (ACLs)" If a file has optional ACL entries, the .CR \-l (ell) option displays a plus sign .RC ( + ) after the file's permissions. The permissions shown are a summary representation of the file's access control list, as returned by .CR stat() in the .I st_mode field (see .IR stat (2)). To list the contents of an access control list, use the .CR lsacl command (see .IR lsacl (1) and .IR acl (5)). .SH EXTERNAL INFLUENCES .SS Environment Variables If the .CR COLUMNS variable is set, .CR ls uses the width provided in determining positioning of columnar output. .PP .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not set or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .CR LC_COLLATE determines the order in which the output is sorted. .PP .CR LC_CTYPE determines which characters are classified as nongraphic for the .CR \-b and .CR \-q options, and the interpretation of single- and/or multibyte characters within file names. .PP .CR LC_TIME determines the date and time strings output by the .CR \-g , .CR \-l (ell), .CR \-n , and .CR \-o options. .PP .C LC_MESSAGES determines the language in which messages (other than the date and time strings) are displayed. .PP If any internationalization variable contains an invalid setting, .CR ls behaves as if all internationalization variables are set to "C" (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .br .ne 3v .SH RETURN VALUE .CR ls exits with one of the following values: .RS .TP 5 .CR \00 All input files were listed successfully. .TP .CR >0 .CR ls was aborted because errors occurred when accessing files. The following conditions cause an error: .RS 8 .TP 3 \(bu Specified file not found. .TP \(bu User has no permission to read the directory. .TP \(bu Process could not get enough memory. .TP \(bu Invalid option specified. .RE .RE .SH EXAMPLES Print a long listing of all the files in the current working directory (including the file sizes). List the most recently modified (youngest) file first, followed by the next older file, and so forth, to the oldest. Files whose names begin with a .CR . are also printed. .IP .C "ls \-alst" .SH WARNINGS Setting options based on whether the output is a login .RI ( tty ) device is undesirable because .CR "ls \-s" is very different from .CR "ls \-s | lp" . On the other hand, not using this setting makes old shell scripts that used .CR ls almost inevitably fail. .PP Unprintable characters in file names may confuse the columnar output options. .SH DEPENDENCIES .TP 5 NFS The .CR \-l (ell) option does not display a plus sign .RC ( + ) after the access permission bits of networked files to represent existence of optional access control list entries. .SH AUTHOR .CR ls was developed by AT&T, the University of California, Berkeley and HP. .SH FILES .TP 25 .CR /etc/passwd to get user IDs for .CR "ls \-l" (ell) and .CR "ls \-o" . .PD 0 .TP .CR /etc/group to get group IDs for .CR "ls \-l" (ell) and .CR "ls \-g" . .TP .CR /usr/share/lib/terminfo/?/* to get terminal information. .PD .SH SEE ALSO chmod(1), find(1), lsacl(1), stat(2), acl(5). .SH STANDARDS CONFORMANCE .CR ls ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4l\f1 \(mi list directory contents in stream output format@@@\f3ls(1)\f1 .\" index@\f4ls\f1 \(mi list directory contents@@@\f3ls(1)\f1 .\" index@\f4lsf\f1 \(mi list directory contents, showing subdirectories and executable files@@@\f3ls(1)\f1 .\" index@\f4ll\f1 \(mi list directory contents in long format@@@\f3ls(1)\f1 .\" index@\f4lsr\f1 \(mi recursively list directory contents and subtrees@@@\f3ls(1)\f1 .\" index@\f4lsx\f1 \(mi list directory contents, sort across page instead of down@@@\f3ls(1)\f1 .\" index@list contents of directory@@@\f3ls(1)\f1 .\" index@directory: list contents of directory@@@\f3ls(1)\f1 .\" index@contents of directory, list@@@\f3ls(1)\f1 .\" index@executable files in directory, list@@@\f3ls(1)\f1 .\" index@subdirectories in directory, list@@@\f3ls(1)\f1 .\" .\" toc@\f3ls(1)\f1:\0\0\f4ls\f1, \f4l\f1, \f4ll\f1, \f4lsf\f1, \f4lsr\f1, \f4lsx\f1@@@list contents of directories .\" toc@\f4l\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4ll\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsf\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsr\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsx\f1: list contents of directories@@@see \f3ls(1)\f1 .\" .\" links@ls.1 l.1 .\" links@ls.1 ll.1 .\" links@ls.1 lsf.1 .\" links@ls.1 lsr.1 .\" links@ls.1 lsx.1 .\" $Header: last.1,v 72.2 94/09/21 09:28:13 ssa Exp $ .TA l .TH last 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME last, lastb \- indicate last logins of users and ttys .SH SYNOPSIS .B /usr/bin/last .RB [ \|-R\| ] .RB [ \|-\f2count\fP\| ] .RI [ \|name " ...\|] .RI [ \|tty " ...\|] .PP .B /usr/bin/lastb .RB [ \|-R\| ] .RB [ \|-\f2count\fP\| ] .RI [ \|name " ...\|] .RI [ \|tty " ...\|] .SH DESCRIPTION The .CR last command searches backwards through the file .CR /var/adm/wtmp (which contains a record of all logins and logouts) for information about a user, a tty, or any group of users and ttys. Arguments specify names of users or ttys of interest. The names of ttys can be given fully or abbreviated. For example, .CR "last 0" is the same as .CR "last tty0" . If multiple arguments are given, the information that applies to any of the arguments is printed. For example, .CR "last root console" lists all of .CR root 's sessions as well as all sessions on the console terminal. The .CR last command prints the sessions of the specified users and ttys, most recent first, indicating when the session began, the duration of the session, and the tty on which the session took place. .CR last indicates if the session is still in progress or if it was cut short by a reboot. .PP The pseudo-user .CR reboot logs each time the system reboots. Thus, .CR "last reboot" is a useful command for evaluating the relative time between system reboots. .PP If .CR last is interrupted, it indicates how far the search has progressed in .CR wtmp . If interrupted by a quit signal (generated by a Ctrl-\e), .CR last indicates how far the search has progressed, then continues the search. .PP The .CR lastb command searches backwards through the database file .CR /var/adm/btmp to display bad login information. Access to .CR /var/adm/btmp should be restricted to users with appropriate privileges (owned by and readable only by .CR root ) because it may contain password information. .SS Options The .CR last and .CR lastb commands recognize the following options and arguments: .RS .TP 10 (none) If no arguments are specified, .CR last prints a record of all logins and logouts in reverse order, most recent first. .TP .CR -R When used with .CR last and .CR lastb , .CR -R displays the user's host name as it is stored in the files .CR /var/adm/wtmp and .CR /var/adm/btmp , respectively. The host name is displayed between the tty name and the user's login time. .TP .CI - count Limits the report to .I count lines. .RE .SH AUTHOR .CR last was developed by the University of California, Berkeley and HP. .SH FILES .TP 20 .CR /var/adm/btmp Bad login database .PD 0 .TP .CR /var/adm/wtmp Login database .PD .SH SEE ALSO login(1), utmp(4). .\" toc@\f3last(1)\f1:\0\0\f4last\f1, \f4lastb\f1@@@indicate last logins of users and ttys\f1 .\" toc@\f4lastb\f1:\0\0indicate last bad logins of users and ttys@@@\f1see \f3last(1)\f1 .\" index@\f4last\f1 \- indicate last logins of users and ttys@@@\f3last(1)\f1 .\" index@\f4lastb\f1 \- indicate last bad logins of users and ttys@@@\f3last(1)\f1 .\" index@\f1reboots, evaluate time between@@@\f3last(1)\f1 .\" index@\f1time between reboots, evaluate@@@\f3last(1)\f1 .\" index@\f1last logins of users and ttys, indicate@@@\f3last(1)\f1 .\" index@\f1logins of users and ttys, indicate last@@@\f3last(1)\f1 .\" index@\f1users and ttys, indicate last logins of@@@\f3last(1)\f1 .\" index@\f1ttys and users, indicate last logins of@@@\f3last(1)\f1 .\" .\" links@last.1 lastb.1 .\" $Header: last.1,v 72.2 94/09/21 09:28:13 ssa Exp $ .TA l .TH last 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME last, lastb \- indicate last logins of users and ttys .SH SYNOPSIS .B /usr/bin/last .RB [ \|-R\| ] .RB [ \|-\f2count\fP\| ] .RI [ \|name " ...\|] .RI [ \|tty " ...\|] .PP .B /usr/bin/lastb .RB [ \|-R\| ] .RB [ \|-\f2count\fP\| ] .RI [ \|name " ...\|] .RI [ \|tty " ...\|] .SH DESCRIPTION The .CR last command searches backwards through the file .CR /var/adm/wtmp (which contains a record of all logins and logouts) for information about a user, a tty, or any group of users and ttys. Arguments specify names of users or ttys of interest. The names of ttys can be given fully or abbreviated. For example, .CR "last 0" is the same as .CR "last tty0" . If multiple arguments are given, the information that applies to any of the arguments is printed. For example, .CR "last root console" lists all of .CR root 's sessions as well as all sessions on the console terminal. The .CR last command prints the sessions of the specified users and ttys, most recent first, indicating when the session began, the duration of the session, and the tty on which the session took place. .CR last indicates if the session is still in progress or if it was cut short by a reboot. .PP The pseudo-user .CR reboot logs each time the system reboots. Thus, .CR "last reboot" is a useful command for evaluating the relative time between system reboots. .PP If .CR last is interrupted, it indicates how far the search has progressed in .CR wtmp . If interrupted by a quit signal (generated by a Ctrl-\e), .CR last indicates how far the search has progressed, then continues the search. .PP The .CR lastb command searches backwards through the database file .CR /var/adm/btmp to display bad login information. Access to .CR /var/adm/btmp should be restricted to users with appropriate privileges (owned by and readable only by .CR root ) because it may contain password information. .SS Options The .CR last and .CR lastb commands recognize the following options and arguments: .RS .TP 10 (none) If no arguments are specified, .CR last prints a record of all logins and logouts in reverse order, most recent first. .TP .CR -R When used with .CR last and .CR lastb , .CR -R displays the user's host name as it is stored in the files .CR /var/adm/wtmp and .CR /var/adm/btmp , respectively. The host name is displayed between the tty name and the user's login time. .TP .CI - count Limits the report to .I count lines. .RE .SH AUTHOR .CR last was developed by the University of California, Berkeley and HP. .SH FILES .TP 20 .CR /var/adm/btmp Bad login database .PD 0 .TP .CR /var/adm/wtmp Login database .PD .SH SEE ALSO login(1), utmp(4). .\" toc@\f3last(1)\f1:\0\0\f4last\f1, \f4lastb\f1@@@indicate last logins of users and ttys\f1 .\" toc@\f4lastb\f1:\0\0indicate last bad logins of users and ttys@@@\f1see \f3last(1)\f1 .\" index@\f4last\f1 \- indicate last logins of users and ttys@@@\f3last(1)\f1 .\" index@\f4lastb\f1 \- indicate last bad logins of users and ttys@@@\f3last(1)\f1 .\" index@\f1reboots, evaluate time between@@@\f3last(1)\f1 .\" index@\f1time between reboots, evaluate@@@\f3last(1)\f1 .\" index@\f1last logins of users and ttys, indicate@@@\f3last(1)\f1 .\" index@\f1logins of users and ttys, indicate last@@@\f3last(1)\f1 .\" index@\f1users and ttys, indicate last logins of@@@\f3last(1)\f1 .\" index@\f1ttys and users, indicate last logins of@@@\f3last(1)\f1 .\" .\" links@last.1 lastb.1 .\" $Header: lastcomm.1,v 72.4 94/08/25 14:07:34 ssa Exp $ .TA l .TH lastcomm 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lastcomm \- show last commands executed in reverse order .SH SYNOPSIS .C lastcomm .RI [ command name "]\0... .RI [ user name ]\0... .RI [ terminal name ]\0... .SH DESCRIPTION .CR lastcomm gives information on previously executed commands. If no arguments are specified, .CR lastcomm prints information about all the commands recorded during the current accounting file's lifetime. If called with arguments, only accounting entries with a matching command name, user name, or terminal name are printed. For example, to produce a listing of all executions of commands named .CR a.out by user .CR root on terminal .CR ttyd0 use: .IP .C lastcomm a.out root ttyd0 .PP For each process entry, the following are printed. .RS .TP 3 \(bu Name of the user who ran the process. .TP \(bu Flags, as accumulated by the accounting facilities in the system. .TP \(bu Command name under which the process was called. .TP \(bu Amount of cpu time used by the process (in seconds). .TP \(bu What time the process started. .RE .PP Flags are encoded as follows: .RS .TP 6 .CR S Command was executed by a user who has appropriate privileges. .TP .CR F Command ran after a fork, but without a following .IR exec . .TP .CR D Command terminated with the generation of a .CR core file. .TP .CR X Command was terminated with the signal .SM SIGTERM. .RE .SH AUTHOR .CR lastcomm was developed by the University of California, Berkeley. .SH SEE ALSO last(1), acct(4), core(4). .\" .\" toc@\f3lastcomm(1)\f1:\0\0\f4lastcomm\f1@@@show last commands executed in reverse order .\" .\" index@\f4lastcomm\f1 \- show last commands executed in reverse order@@@\f3lastcomm(1)\f1 .\" index@commands, show last executed in reverse order@@@\f3lastcomm(1)\f1 .\" index@last commands executed, show in reverse order@@@\f3lastcomm(1)\f1 .\" index@reverse order, show last commands executed in@@@\f3lastcomm(1)\f1 .\" $Header: $ .TA l .TH ld 1 .SH NAME ld \- link editor .SH SYNOPSIS .C ld .RC [ -bdmnqrstvxzEGINOPQSTVZ ] .RC [ +b .IR path_list\| ] .RC [ +cg .IR pathname\| ] .RC [ +df .IR file\| ] .RC [ +dpd ] .RC [ +dpv ] .RC [ +e .IR symbol\| ]\ .\|.\|. .RC [ +h .IR internal_name\| ] .RC [ +help ] .RC [ +n ] .RC [ +pgm .IR name\| ] .RC [ +s ] .RC [ +FP .IR flag\| ] .RC [ +I .IR symbol\| ] .RC [ +O [ .IR no \| .RC ] fastaccess ] .RC [ +O [ .IR no \| .RC ] procelim ] .RC [ +Ostaticprediction ] .RC [ -a .IR search\| ] .RC [ -c .IR filename\| ] .RC [ -e .IR epsym\| ] .RC [ -h .IR symbol\| ]\ .\|.\|. .RC [ -l\c .I x \(or .IR file\| ]\ ... .RC [ -l: .IR library\| ] .RC [ -o .IR outfile\| ] .RC [ -u .IR symbol\| ]\ .\|.\|. .RC [ -y .IR symbol\| ]\ .\|.\|. .RC [ -A .IR name\| ] .RC [ -B .IR bind\| ] .RC [ -C\c .I n .RC [ -D .IR offset\| ] .RC [ -L .IR dir\| ]\ .\|.\|. .RC [ -R .IR offset\| ] .RC [ -X .IR num\| ] .RC [ +v[no]shlibunsats ] .RC [ +vallcompatwarnings ] .RC [ +v[no]compatwarnings ] .SH DESCRIPTION .C ld takes one or more object files or libraries as input and combines them to produce a single (usually executable) file. In doing so it resolves references to external symbols, assigns final addresses to procedures and variables, revises code and data to reflect new addresses (a process called "relocation"), and updates symbolic debug information when present in the file. By default, .C ld produces an executable file that can be run by the .SM HP-UX loader .C exec() (see .IR exec (2)). Alternatively, the linker can generate a relocatable file that is suitable for further processing by .C ld (see .C -r below). It can also generate a shared library (see .C -b below). The linker marks the output file non-executable if there are any duplicate symbols or any unresolved external references remain. .C ld may or may not generate an output file if any other errors occur during its operation. .C ld recognizes three kinds of input files: object files created by the compilers, assembler, or linker (also known as .C .o files), shared libraries created by the linker, and archives of object files (called archive libraries). An archive library contains a table of all the externally-visible symbols from its component object files. (The archiver command .IR ar (1) creates and maintains this index.) .C ld uses this table to resolve references to external symbols. .PP .C ld processes files in the same order as they appear on the command line. It includes code and data from an archive library element if and only if that object module provides a definition for a currently unresolved reference within the user's program. It is common practice to list libraries following the names of all simple object files on the command line. .PP Code and data from shared libraries is never copied into an executable program. The dynamic loader .C /usr/lib/dld.sl is invoked at startup time by the startup file .C crt0.o if a program uses shared libraries. Identical copies of .C crt0.o can be found in either .C /usr/ccs/lib/crt0.o or .CR /opt/langtools/lib/crt0.o . The dynamic loader attaches each required library to the process and resolves all symbolic references between the program and its libraries. The text segment of a shared library is shared among all processes that use the library; each process using the library receives its own copy of the data segment. .PP .C ld recursively examines the dependencies of shared libraries used by a program that was created by .CR ld . If .C ld does not find a supporting shared library at the path recorded in the dependency list of a shared library, and if the dependency is the result of an .C \-l argument used when the shared library was created, .C ld will search all the directories that it would search for a library that was specified with .C \-l (see .C \-L and .CR LPATH ). .SS Environment Variables Arguments can be passed to the linker through the .C LDOPTS environment variable as well as on the command line. The linker gets the value of .C LDOPTS and places its contents before any arguments on the command line. .PP The .C LD_PXDB environment variable defines the full execution path for the debug preprocessor .CR pxdb . The default value is .CR /opt/langtools/bin/pxdb . .C ld invokes .C pxdb on its output file if that file is executable and contains debug information. To defer invocation of .C pxdb until the first debug session, set .C LD_PXDB to .CR /dev/null . .PP The .C LPATH environment variable can be used to specify default directories to search for library files. See the .C -l option. .SS Options .PP .C ld recognizes the following options: .RS .TP 15 .CI -a " search" Specify whether shared or archive libraries are searched with the .C -l option. The value of .I search should be one of .CR archive , .CR shared , .CR archive_shared , .CR shared_archive , or .CR default . This option can appear more than once, interspersed among .C -l options, to control the searching for each library. The default is to use the shared version of a library if one is available, or the archive version if not. .IP If either .C archive or .C shared is active, only the specified library type is accepted. .IP If .CR archive_shared is active, the archive form is preferred, but the shared form is allowed. .IP If .CR shared_archive is active, the shared form is preferred but the archive form is allowed. .TP .CR -b Create a shared library rather than a normal executable file. Object files processed with this option must contain .B position-independent code (\s-1PIC\s0). See the discussion of .SM PIC in .IR cc (1), .IR CC (1) [part of the optional C++ compiler documentation], .IR f77 (1), .IR pc (1), .IR as (1), and .I Linker and Libraries Online User Guide. .TP .CI -c " filename" Read ld options from a file. Each line contains zero or more arguments separated by white space. Each line in the file, including the last line, must end with a newline character. A .C # character implies that the rest of the line is a comment. To escape a .C # character, use the sequence .CR ## . .TP .CR -d Force definition of ``common'' storage; that is, assign addresses and sizes, for .CR -r output. .TP .CI -e " epsym" Set the default entry point address for the output file to be that of the symbol .IR epsym . (This option only applies to executable files.) .TP .CI -h " symbol" Prior to writing the symbol table to the output file, mark this name as ``local'' so that it is no longer externally visible. This ensures that this particular entry will not clash with a definition in another file during future processing by .CR ld . .IP More than one .I symbol can be specified, but .C -h must precede each one. If used when building a shared library or program, this option prevents the named symbol from being visible to the dynamic loader. .TP .CI -l x Search a library .CI lib x .a or .CI lib x .sl\f1, where .I x is one or more characters. The current state of the .C -a option determines whether the archive .RC ( .a ) or shared .RC ( .sl ) version of a library is searched. Because a library is searched when its name is encountered, the placement of a .C -l is significant. By default, libraries are located in .C /usr/lib and .C /usr/ccs/lib. If the environment variable .C LPATH is present in the user's environment, it should contain a colon-separated list of directories to search. These directories are searched instead of the default directories, but .C -L options can still be used. If a program uses shared libraries, the dynamic loader .C /usr/lib/dld.sl will attempt to load each library from the same directory in which it was found at link time (see the .C +s and .C +b options). .TP .CI -l: " library" Search the library specified. Similar to the .C -l option except the current state of the .C -a option is not important. The library name must contain the prefix .CR lib and end with a suffix of .CR .a or .CR .sl . .TP .C -m Produce a load map on the standard output. .TP .C -n Generate an executable output file with file type .CR SHARE_MAGIC . This is the default. This option is incompatible with .C -N and .CR -q . .TP .CI -o " outfile" Produce an output object file named .I outfile .RC ( a.out if .C -o .I outfile is not specified). .TP .C -q Generate an executable output file with file type .CR DEMAND_MAGIC . This option is incompatible with .CR -n , .CR -N , and .CR -Q . .TP .CR -r Retain relocation information in the output file for subsequent re-linking. The .C ld command does not report undefined symbols. This option cannot be used when building a shared library ( .CR -b ) or in conjunction with .CR -A . .TP .CR -s Strip the output file of all symbol table, relocation, and debug support information. This might impair or prevent the use of a symbolic debugger on the resulting program. This option is incompatible with .CR -r . (The .IR strip (1) command also removes this information.) .TP .CR -t Print a trace (to standard output) of each input file as .C ld processes it. .TP .CI -u " symbol" Enter .I symbol as an undefined symbol in the symbol table. The resulting unresolved reference is useful for linking a program solely from object files in a library. More than one .I symbol can be specified, but each must be preceded by .CR -u . .TP .CR -v Display verbose messages during linking. For each library module that is loaded, the linker indicates which symbol caused that module to be loaded. .TP .CR -x Strip local symbols from the output file. This reduces the size of the output file without impairing the effectiveness of object file utilities. This option is incompatible with the .CR -r option . Note: use of .CR -x might affect the use of a debugger. .TP .CI -y " symbol" Indicate each file in which .I symbol appears. More than one .I symbol can be specified, but each must be preceded by .CR -y . .TP .CR -z Arrange for run-time dereferencing of null pointers to produce a .C SIGSEGV signal. (This is the complement of the .C -Z option.) .TP .CI -A " name" This option specifies incremental loading. Linking is arranged so that the resulting object can be read into an already executing program. The argument .I name specifies a file whose symbol table provides the basis for defining additional symbols. Only newly linked material is entered into the text and data portions of .CR a.out , but the new symbol table reflects all symbols defined before and after the incremental load. Also, the .C -R option can be used in conjunction with .CR -A , which allows the newly linked segment to commence at the corresponding address. The default starting address is the old value of .CR _end . The .C -A option is incompatible with .C -r and .CR -b . Also note that a program that dynamically loads code with .C ld -A cannot use shared libraries. See the .CR +help option or the .I Programming on .SM .I HP-UX manual for a description of this option. This option may be obsoleted in future releases. .TP .CI -B " bind" Select run-time binding behavior of a program using shared libraries or the binding preference in building a shared library. The most common values for .I bind are: .RS .TP .C deferred Bind addresses on first reference rather than at program start-up time. This is the default. .TP .C immediate Bind addresses of all symbols immediately upon loading the library. Commonly followed by .C -B nonfatal to allow procedure calls that cannot be resolved at program start-up to be resolved on first reference. .RS .PP Since .C -B nonfatal suppresses messages about unresolved symbols, also specify .C -B verbose to display those messages. .PP See the example below. .RE .TP .C nonfatal If also using .CR "-B immediate" , for code symbols that could not be bound at program startup, defer binding them until they are referenced. See description of .C -B immediate above. .RS .PP Since .C -B nonfatal suppresses messages about unresolved symbols, also specify .C -B verbose to display those messages. .RE .TP .C restricted Causes the search for a symbol definition to be restricted to those symbols that were visible when the library was loaded. .TP .C symbolic Used only when building a shared library (with the .C -b option), this option causes all unresolved symbols inside a library to be resolved internally. By default, unresolved symbols are resolved by either definitions in the library or outside of the library. .TP .C verbose Display verbose messages when binding symbols. This is the default except when .C -B nonfatal is specified. In that case, .C -B verbose must be explicitly specified to get verbose messages. .PP See the .CR +help option or the .I Programming on .SM .I HP-UX manual for more information on the uses of binding modes. .RE .TP .CI -C n Set the maximum parameter-checking level to .IR n . The default maximum is 3. See the language manuals for the meanings of the parameter-checking level. This option may be obsoleted in future releases. .TP .CI -D " offset" Set the origin (in hexadecimal) for the data segment. .TP .CR -E Mark all symbols defined by a program for export to shared libraries. By default, .C ld marks only those symbols that are actually referenced by a shared library seen at link time. .TP .CR -G Strip all unloadable data from the output file. This option is typically used to strip debug information. .TP .C -I Instrument the code to collect profile information upon execution. The profile data gathered during program execution can be used in conjunction with the .C -P option. Programs linked with this option should use the startup file .C /opt/langtools/lib/icrt0.o instead of .CR crt0.o . This option should not be used with the .CR -P , .CR -A , .CR "-O" , or .CR +O options. .TP .CI -L " dir" Search for .CI lib x .a or .CI lib x .sl in .I dir before looking in default locations. More than one directory can be specified, but each must be preceded by .CR -L . The .C -L option is effective only if it precedes the .C -l option on the command line. .TP .CR -N Generate an executable output file with file type .CR EXEC_MAGIC . This option is incompatible with .C -n and .CR -q . This option causes the data to be placed immediately following the text, and makes the text writable. Files of this type cannot be shared. .TP .C -O Turn on linker optimizations. Currently the optimizations include the elimination of unnecessary .C ADDIL instructions from the code in the executable file, and the removal of dead procedures. .IP .C -O is passed to the linker by the compilers when the .C +O4 compiler option is selected. .IP For more details on linker optimizations refer to the .CR +help option or the .I Programming on .SM .I HP-UX manual. .TP .C -P Examine the data file produced by an instrumented program (see the .C -I option) to perform profile based optimizations on the code. This option should not be used with the .CR -A option. .TP .CR -Q Generate an executable output file with file type .C EXEC_MAGIC or .CR SHARE_MAGIC , depending on whether .C -N or .C -n is specified. This is the default. This option is incompatible with .CR -q . .TP .CI -R " offset" Set the origin (in hexadecimal) for the text (i.e., code) segment. .TP .C -S Generate an Initial Program Loader (IPL) auxiliary header for the output file, instead of the default HP-UX auxiliary header. .TP .C -T Save the load data and relocation information in temporary files instead of in memory during linking. This option reduces the virtual memory requirements of the linker. If the .C TMPDIR environment variable is set, the temporary files are created in the specified directory, rather than in .CR /var/tmp . .TP .C -V Output a message giving information about the version of .C ld being used. .TP .CI -X " num" This option is obsolete. .\" DK DEBUG obsolete option .\"Define the initial size for the linker's global symbol table. .\"This reduces link time for very large programs, .\"especially those with a large number of external symbols. .TP .C -Z Allow run-time dereferencing of null pointers. See the discussions of .C -Z and .IR pointers in .IR cc (1). (This is the complement of the .C -z option.) .TP .CI +b " path_list" Specify a colon-separated list of directories to be searched at program run-time to locate shared libraries needed by the executable output file that were specified with either the .C -l or .C -l: option. An argument consisting of a single colon .RC ( : ) indicates that .C ld should build the list using all the directories specified by the .C -L option and the .C LPATH environment variable (see the .C +s option). .TP .CI +cg " pathname" Specify the use of .I pathname as the code generator for compiling ISOMs to SOMs. See the discussion of profile based optimization for more information. .TP .CI "+df" " file" Used together with the .C -P option, this option specifies that .I file should be used as the profile database file. The default value is .CR flow.data . See the discussion of the .C FLOW_DATA environment variable for more information. .TP .C +dpv Display verbose messages regarding procedures which have been removed due to dead procedure elimination. The symbol name, input object file, and the size (in bytes) of the deleted procedure are displayed. The total size (in bytes) of the deleted procedures is also displayed. .TP .CI +e " symbol" When building a shared library or program, mark the symbol for export to the dynamic loader. Only symbols explicitly marked are exported. When building a shared library, calls to symbols that are not exported are resolved internally. .TP .CI +fb Instructs the linker to run the fastbind tool on the executable it has produced. The executable should be linked with shared libraries. For more details refer to .IR fastbind (1), the .CR +help option, or the .I Programming on .SM .I HP-UX manual. .TP .CI +fbu Pass the .CR -u option to the fastbind tool. For more details refer to .IR fastbind (1), the .CR +help option, or the .I Programming on .SM .I HP-UX manual. .TP .CI +h " internal_name" When building a shared library, record .IR internal_name as the name of the library. When the library is used to link another executable file (program or shared library), this .IR internal_name is recorded in the library list of the resulting output file instead of the file system pathname of the input shared library. .IP If .IR internal_name is a fully-qualified pathname, it is recorded .C as is in the library list of any executable file it is subsequently linked against. If .IR internal_name is a relative pathname or no directory component was specified, .IR internal_name is .C appended to the file system directory component of the input shared library in the library list of any executable file it is subsequently linked against. .IP If more than one +h option is seen on the link line, the first one is used and a warning message is emitted. .TP .C +help Starts the .IR "HP-UX Linker and Libraries Online User Guide" which comes with some HP compilers. (You must be running the X window system and your .C $DISPLAY environment variable must be set to the name of your workstation or X terminal.) For more information, refer to the .I Programming on .SM .I HP-UX manual. See .IR manuals (5) for ordering information. .TP .C +n Causes the linker to load all object modules before searching any archive or shared libraries. Then it searches the archive and shared libraries specified on the command line in left to right order. Repeats the left to right search of the libraries on the command line until there are no more unsatisfied symbols, or the last search added no new definitions. This option is useful if two libraries are specified that have symbol dependencies on each other. .TP .CI "+pgm" " name" Used together with the .C -P option, this option specifies that .I name should be used as the look-up name in the profile database file. The default is the basename of the output file (specified by the .C -o option.) .TP .C +s Indicates that at run-time, the shared library loader can use the environment variable .C SHLIB_PATH to locate shared libraries needed by the executable output file that were specified with either the .C -l or .C -l: option. The .C SHLIB_PATH environment variable should be set to a colon-separated list of directories. If both .C +s and .C +b are used, their relative order on the command line indicates which path list will be searched first (see the .C +b option). .TP .CI +vallcompatwarnings Show more detail for any warnings about compatability issues. By default, only a terse message is printed. See the .C WARNINGS section below for further details. .TP .CI +v[no]compatwarnings Enable [disable] printing warnings about compatibility issues between systems. This includes any functionality which may change in future releases. The default is .CR +vcompatwarnings . See the .C WARNINGS section below for further details. .TP .CI +v[no]shlibunsats Enable [disable] printing a list of unsatisfied symbols used by shared libraries. The default is .CR +vnoshlibunsats . Some unsatisfied symbols reported by the linker are not required at run time because the modules which reference the symbols are not used. .TP .CI +FP " flag" Specify how the environment for floating-point operations should be initialized at program start-up. By default, all behaviors are disabled. The following flags are supported (upper case flag enables; lower case flag disables): .RS .RS .TP 10 .CR V \0( v ) Trap on invalid floating-point operations .TP .CR Z \0( z ) Trap on divide by zero .TP .CR O \0( o ) Trap on floating-point overflow .TP .CR U \0( u ) Trap on floating-point underflow .TP .CR I \0( i ) Trap on floating-point operations that produce inexact results. .TP .CR D \0( d ) Enable sudden underflow (flush to zero) of denormalized values. .IP .B Note: Enabling sudden underflow is an undefined operation on .SM PA-RISC 1.0-based systems, but it is defined on all subsequent versions of .SM PA-RISC. Selecting this flag enables sudden underflow only if it is available on the processor being used at run-time. .RE .RE .IP To dynamically change these settings at run-time, see .IR fpgetround (3M). .TP .CI +I " symbol" Specify the name of the initializer function when building a shared library. A shared library may have multiple initializers specified. Initializers are executed in the order that they are specified. .\"See the For more details on the initializer function, refer to the .CR +help option or the .I Programming on .SM .I HP-UX manual. .\".I HP-UX .\"manual for a description of the initializer function. .TP .CI +O[no]fastaccess Enable [disable] fast access to global data. The linker rearranges the data to further reduce the number of .C ADDIL instructions in the executable. .IP This optimization may reveal some subtle programming errors related to assumptions about data layout. This optimization can occur at optimization levels 2, 3 and 4. The default is .CI +Onofastaccess at optimization levels 2 and 3, and .CI +Ofastaccess at optimization level 4. .TP .CI +O[no]procelim Enable [disable] the elimination of procedures that are not referenced by the application. The default is .CI +Onoprocelim . Procedure elimination can occur at any optimization level, including level 0. For more details refer to the .CR +help option or the .I Programming on .SM .I HP-UX manual. .TP .CI +Ostaticprediction Meaningful only on PA 2.0 architecture, this option sets the branch prediction bit in the output executable file's auxiliary header. .RE .SS Defaults Unless otherwise directed, .C ld names its output .CR a.out . The .C -o option overrides this. Executable output files are of type .CR SHARE_MAGIC . The default state of .C -a is to search shared libraries if available, archive libraries otherwise. The default bind behavior is .CR deferred . .PP The default value of the .CR -Z / -z option is .CR -Z . .SH EXTERNAL INFLUENCES .SS Environment Variables .PP The following internationalization variables affect the execution of .CR ld : .PP .C LANG .RS Determines the locale category for native language, local customs and coded character set in the absence of .C LC_ALL and other .C LC_* environment variables. If .C LANG is not specified or is set to the empty string, a default of .C C (see .IR lang (5)) is used instead of .CR LANG . .RE .PP .C LC_ALL .RS Determines the values for all locale categories and has precedence over .C LANG and other .C LC_* environment variables. .RE .PP .C LC_MESSAGES .RS Determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error. .RE .PP .C LC_NUMERIC .RS Determines the locale category for numeric formatting. .RE .PP .C LC_CTYPE .RS Determines the locale category for character handling functions. .RE .PP .C NLSPATH .RS Determines the location of message catalogs for the processing of .CR LC_MESSAGES . .RE .PP If any internationalization variable contains an invalid setting, .C ld behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .PP In addition, the following environment variable affects .CR ld : .PP .C TMPDIR .RS Specifies a directory for temporary files (see .IR tmpnam (3S)). .RE .SH DIAGNOSTICS .C ld returns zero when the link is successful. A non-zero return code indicates that an error occurred. .SH EXAMPLES Link part of a C program for later processing by .CR ld . (Note the .C .o suffix for the output object file; this is an .SM HP-UX convention for indicating a linkable object file): .IP .C "ld -r file1.o file2.o -o prog.o" .PP Link a simple F\s-2ORTRAN\s0 program for use with the .C dde symbolic debugger (see .IR dde (1)). Output file name is .C a.out since there is no .C -o option in the command line. .IP .C "ld /usr/ccs/lib/crt0.o ftn.o -lcl -lisamstub -lc /opt/langtools/lib/end.o" .PP Create a shared library: .IP .C "ld -b -o libfunc.sl func1.o func2.o func3.o" .PP Create a shared library with an internal name: .IP .C "ld -b -o libfoo1.1 foo1.o foo2.o +h libfoo1.1" .PP Link a program with .C libfunc.sl but use the archive version of the C library. Specify the immediate binding mode together with the nonfatal modifier and allow verbose diagnostics to be displayed: .IP .C "ld /usr/ccs/lib/crt0.o -B immediate -B nonfatal -B verbose program.o -L .\e" .br .C " -lfunc -a archive -lc" .PP Link a Pascal program: .IP .C "ld /usr/ccs/lib/crt0.o main.o -lcl -lm -lc" .PP Note that in the above examples, .C /usr/ccs/lib/crt0.o can be replaced by .CR /opt/langtools/lib/crt0.o . .SH WARNINGS .C ld recognizes several names as having special meanings. The symbol .C _end is reserved by the linker to refer to the first address beyond the end of the program's address space. Similarly, the symbol .C _edata refers to the first address beyond the initialized data, and the symbol .C _etext refers to the first address beyond the program text. The linker treats a user definition of any of these symbols as an error. The symbols .CR end , .CR edata , and .C etext are also defined by the linker, but only if the program contains a reference to these symbols and does not define them (see .IR end (3C) for details). .PP Through its options, the link editor gives users great flexibility. However, those who invoke the linker directly must assume some added responsibilities. Input options should ensure the following properties for programs: .RS .TP 3 \(bu When the link editor is called through .IR cc (1), a start-up routine is linked with the user's program. This routine calls .IR exit (2) after execution of the main program. If users call .C ld directly, they must ensure that the program always calls .IR exit (\|) rather than falling through the end of the entry routine. .TP \(bu When linking for use with the symbolic debugger .IR dde , the user must ensure that the program contains a routine called .CR main . Also, the user must link in the file .C /opt/langtools/lib/end.o as the last file named on the command line. .RE .PP There is no guarantee that the linker will pick up files from archive libraries and include them in the final program in the same relative order that they occur within the library. .PP The linker emits warnings where ever it detects any compatibility issues. Among other things, these issues include architectural ones, as well as functionality that may change over time. Some of these include: .RS .TP 2 \(bu Linking a PA 2.0 object file, which will not run on a PA 1.x system. .TP \(bu Incremental loading with the .C -A option. .TP \(bu Procedure call parameter and return type checking, including the .C -C option. .TP \(bu Symbols with the same name but different types, such as CODE and DATA. .TP \(bu Checking of unsatisfied symbols by the linker, which sometimes skips certain object files from an archived library. This warning is only given if the .C -v option is also provided. .TP \(bu Versioning of objects within a shared library. .RE .PP These messages can be turned off with the .C +vnocompatwarnings option. .SH ADVANCED FEATURES The linker searches for the symbol .C $START$ as the program entry point. This symbol is defined in the file .CR crt0.o , which should be the first file loaded for all programs regardless of source language. Use the .C -e option to select a different entry point. .PP By default, the data segment begins at offset 0x40001000. Since certain optimizations are now performed in the page previous to 0x40001000, some applications will not function as before if the start of the data segment is set to be within the range 0x40000000 through 0x40001000. .PP When invoking .C ld directly to link a C program whose .C main procedure is located in a library, the .C -u main option should be used to force the linker to load .C main from the library, since this symbol is not actually referenced until the .C _start routine is loaded from the C library. When using .IR cc (1) to link the program, the compiler automatically passes this option to the linker. Because of this behavior, do not use .I cc to link a program containing a F\s-2ORTRAN\s0 or Pascal main program; use .I f77 or .I pc instead. .PP Executable files generated with the .C -N option cannot be shared. Typically, .C -N is used when rebuilding the kernel or when preparing an image for dynamic loading. For these files, the data segment begins on the next page following the text segment. This option can also be used if a process needs more virtual data address space than is available with .C SHARE_MAGIC and .C DEMAND_MAGIC files. .PP When the .CR -A option is used to do an incremental link, the linker generates extra code where a procedure call crosses a quadrant boundary (a quadrant is one gigabyte, or one fourth of the addressing space). Text is normally in the first quadrant and data is in the second quadrant. When an object file is intended to be read into an already-executing program, both its code and data must be placed in the second quadrant, since the first quadrant is set to read-only. Procedure calls from one quadrant to the other require the extra code, called inter-space calling stubs. The linker generates an ``export'' stub for the entry point designated in the incremental link, and ``import'' stubs for each procedure in the basis program that is called by the new object file. The import stubs require the existence of a routine in the basis program called .CR _sr4export , which is supplied in .CR crt0.o . If a procedure in the basis program is called indirectly by the new object file, the linker cannot detect the crossing of the quadrant boundary, and therefore will not generate the needed stub. A special version of .C $$dyncall placed in .\".C /usr/lib/dyncall.o .C /usr/ccs/lib/dyncall.o is provided for handling the inter-quadrant branch. This routine should be linked in when the .C -A option is in effect. .PP .C ld treats both duplicate symbols and unresolved symbols in the same manner: an output file is generated and marked as non-executable if errors occur during its operation (see .SM DESCRIPTION\s0). .PP The default file type is .CR SHARE_MAGIC . See the .CR +help option or the .I Programming on .SM .I HP-UX manual for a discussion of the various file types. .PP The linker works in conjunction with the compilers to support profile-based optimization: transformations that use profile data gathered from previous runs of a program to improve run-time performance. Profile data collection and profile-based optimizations can be performed within the bodies of procedures compiled with the .C +I option to .\".C cc .CR cc , .CR CC , or .CR f77 (see .\".IR cc (1) .\"and .\".IR f77 (1)). .IR cc (1), .IR f77 (1), and .IR CC (1)) [part of the optional C++ compiler documentation]. For example, code can be repositioned within procedures so that fewer branches are executed and better code locality is achieved. The linker can also instrument calls between procedures, even if they were not compiled with the .C +I option. After profile data is collected, the program can be relinked and the linker will reposition the procedures to further improve code locality. See the .CR -I , .CR -P , .CR +cg , .CR +df , and .C +pgm options above. Also see the discussion of profile-based optimization from the .CR +help option or the .I Programming on .SM .I HP-UX manual. .PP Object files that are compiled with the .C +I or .C +P option (see .IR cc (1), .IR CC (1), and .IR f77 (1)) contain intermediate code instead of .SM PA-RISC object code. The linker then invokes a .SM PA-RISC code generator on these files before linking them into the executable file. Because of this, linking object files compiled with .C +I or .C +P may take significantly more time than linking ordinary object files. The object files that are generated by compiling the intermediate code are written to the directory specified by the .C TMPDIR environment variable, or .\".C /tmp .C /var/tmp if .C TMPDIR is not specified. The object files are deleted before the linker exits. .PP The following environment variables are related to profile-based optimization: .RS .TP 20 .C FLOW_DATA An instrumented executable (see the .C -I option) writes out the profile data to a database file named .C flow.data in the current directory. The name and location of this file can be specified by setting .C FLOW_DATA to the desired path name. The profile data is stored in the database file under a look-up name that is the same as the basename of the executable file specified at run-time. A single .C flow.data file can hold profile data for multiple program files. .TP .C FLOW_DATA_DIR Obsolete environment variable. Do not use. .RE .PP .SH AUTHOR .C ld was developed by AT&T, the University of California, Berkeley, and HP. .SH FILES .TP 40 .C /usr/lib/lib* system archive and shared libraries .TP .C /usr/ccs/lib* development archive and shared libraries .TP .C a.out output file .TP .C /usr/lib/dld.sl dynamic loader .TP .C /opt/langtools/lib/end.o for use with the .C dde debugger .TP 40 .C /usr/ccs/lib/crt0.o run-time startup .TP 40 .C /opt/langtools/lib/crt0.o Identical to .C /usr/ccs/lib/crt0.o .TP .\".C /usr/lib/dyncall.o .C /usr/ccs/lib/dyncall.o used with .C -A option links .TP .C /opt/langtools/lib/mcrt0.o run-time startup with profiling (see .IR prof (1)) .TP .C /usr/lib/milli.a millicode library automatically searched by .C ld .TP .C /opt/langtools/lib/gcrt0.o run-time start-up with profiling (see .IR gprof (1)) .TP .C /opt/langtools/lib/icrt0.o run-time start-up with profiling (see discussion of profile based optimization above.) .TP .C /opt/langtools/lib/scrt0.o startup for profiling shared libraries for profile based optimization. .TP .C /usr/lib/nls/$LANG/ld.cat message catalog .TP .C /var/tmp/ld* temporary files .TP .C flow.data file containing profile data generated by running an instrumented executable .TP .C /usr/ccs/bin/fdp program for creating the procedure link order from a profile database file created by an instrumented executable; forked by the .C -P option .TP .C /usr/ccs/lbin/uccom .SM PA-RISC code generator for the C language .TP .C /opt/fortran/lbin/uf77pass1 .SM PA-RISC code generator for the F\s-2ORTRAN\s0 language .TP .C /opt/langtools/lbin/ucomp .\".C /usr/ccs/lbin/ucomp Default .SM PA-RISC code generator .PD .SH SEE ALSO .PD .SS Profiling and Debugging Tools: .TP 18 adb(1) absolute debugger .PD 0 .TP gprof(1) display call graph profile data .TP prof(1) display profile data .TP dde(1) C, C++, FORTRAN, and Pascal symbolic debugger .PD .SS System Tools: .TP 18 ar(1) create archived libraries .PD 0 .TP CC(1) invoke the HP-UX C++ compiler .TP cc(1) invoke the HP-UX C compiler .TP chatr(1) change program's internal attributes .TP exec(2) execute a file .TP f77(1) invoke the HP-UX FORTRAN compiler .TP fastbind(1) invoke the fastbind tool .TP nm(1) print name list of object file .TP pc(1) invoke the HP-UX Pascal compiler .TP strip(1) strip symbol and line number information from an object file .PD .SS Miscellaneous: .TP 18 a.out(4) assembler, compiler, and linker output .PD 0 .TP ar(4) archive format .TP crt0(3) execution startup routine .TP dld.sl(5) dynamic loader .TP end(3C) symbol of the last locations in program .PD .SS Texts and Tutorials: .TP 18 .PD 0 .IR "HP-UX Linker and Libraries Online User Guide" (See the .CR +help option) .TP .IR "Programming on HP-UX" (See .IR manuals (5) for ordering information) .PD .SH STANDARDS CONFORMANCE .CR ld ": SVID2, SVID3, XPG2, XPG4" .\" index@\f4ld\f1 \- link editor@@@\f3ld(1)\f1 .\" index@\f1link editor@@@\f3ld(1)\f1 .\" index@\f1relocatable file, generate from object files and libraries@@@\f3ld(1)\f1 .\" index@\f1executable file, generate from object files and libraries@@@\f3ld(1)\f1 .\" index@\f1libraries and object files, generate single executable file from@@@\f3ld(1)\f1 .\" index@\f1object files and libraries, generate single executable file from@@@\f3ld(1)\f1 .\" index@\f1shared libraries, generate from object files@@@\f3ld(1)\f1 .\" index@\f1dynamic loader, binding behavior@@@\f3ld(1)\f1 .\" .\" toc@\f3ld(1)\f1:\0\0\f4ld\f1@@@link editor .\" .\" $Header: leave.1,v 72.4 94/07/03 14:05:40 ssa Exp $ .TA l .TH leave 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME leave \- remind you when you have to leave .SH SYNOPSIS .C leave .RI [ \|hhmm\| ] .SH DESCRIPTION The .CR leave command waits until the specified time, then reminds you to leave. You are reminded 5 minutes and 1 minute before the actual time, at the time, and every minute thereafter. When you log off, .CR leave exits. .PP The time of day is in the form .IR hhmm , where .I hh is a time in hours (which can range from 0 through 11 or 0 through 24 hours), and .I mm is the number of minutes after the specified hour. If the value of .I hh is greater than 11 (24-hour clock time), the specified value is reduced by 12 to a new value in the range of 0 through 11, thus ensuring that the alarm time is always set to activate within the next 12 hours. For example, if .I hhmm is 1350 and the current time is 4:00 PM (1600), the 1350 value is changed to 150 and the alarm is set for 1:50 AM, nine hours and 50 minutes later. On the other hand, if it is 9:00 AM and .I hhmm is specified as 2200 (10:00 PM), the value used is converted to 1000 and the alarm is set for one hour later instead of 13 hours as specified. .PP If no argument is provided, .CR leave prompts with .IP .C "When do you have to leave?" .PP A reply of newline causes .CR leave to exit; otherwise the reply is assumed to be a time. This form is suitable for inclusion in a .CR .login or .CR .profile file. .PP The .CR leave command ignores interrupts, quits, and terminate signals. To get rid of it you should either log off or use .CR "kill -9" giving its process ID. .SH EXAMPLES The command .IP .C leave 1204 .PP sends an alarm (a beep) to your terminal to remind you that you have to leave at 12:04 and reminds you that you are late at one minute intervals after 12:04. .SH WARNINGS The .CR leave command checks to see if a user has logged out by checking the .CR /etc/utmp file every 100 seconds. If a user logs out and logs back in to the same tty before .CR leave makes its periodic check, .CR leave may not know that the user has logged out. .SH AUTHOR .CR leave was developed by the University of California, Berkeley. .SH FILES .C /etc/utmp .SH SEE ALSO calendar(1). .\" .\" toc@\f3leave(1)\f1:\0\0\f4leave\f1@@@remind you when you have to leave\f1 .\" .\" index@\f4leave\f1 \- remind you when you have to leave@@@\f3leave(1)\f1 .\" index@\f1remind you when you have to leave@@@\f3leave(1)\f1 .\" index@\f1notify you when it is time to leave@@@\f3leave(1)\f1 .\" index@\f1time to leave, notify you when it is@@@\f3leave(1)\f1 .\" $Header: lifcp.1,v 72.4 94/07/05 16:14:07 ssa Exp $ .TA l .TH lifcp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lifcp \- copy to or from LIF files .SH SYNOPSIS .B lifcp .RB [ \|\-T\c .IR xxx\| ] .RB [ \|\-L\c .IR xxx\| ] .RB [ \|\-v\c .IR xxx\| ] .RB [ \|\-a\| ] .RB [ \|\-b\| ] .RB [ \|\-i .IR xxx\| ] .RB [ \|\-r\| ] .RB [ \|\-t\| ] .I file1 file2 .br .B lifcp .RB [ \|\-T\c .IR xxx\| ] .RB [ \|\-L\c .IR xxx\| ] .RB [ \|\-v\c .IR xxx\| ] .RB [ \|\-a\| ] .RB [ \|\-b\| ] .RB [ \|\-i\c .IR xxx\| ] .RB [ \|\-r\| ] .RB [ \|\-t\| ] .RI [ \|\c .I file1 file2 \&...\|] .I directory .SH DESCRIPTION .I lifcp copies a LIF file to an HP-UX file, an HP-UX file to a LIF file, or a LIF file to another LIF file. It also copies a list of (HP-UX/LIF) files to a (LIF/HP-UX) directory. The last name on the argument list is the destination file or directory. .PP Options can be used singly or combined in any order before the file names. The space between option and argument is optional. .RS .TP 12 .BI \-T xxx Used only when copying files to a LIF volume. This option forces the file type of the LIF directory entry to be set to the argument given. The argument can be decimal, octal or hex, using standard "C" notation. .TP .BI \-L xxx Used only when copying files to a LIF volume. This option will set the "last volume flag" to .I xxx (0 or 1). The default "last volume flag" is .BR 1 . .TP .BI \-v xxx Used only when copying files to a LIF volume. This option sets the "volume number" to .IR xxx . The default "volume number" is one. .TP .B \-a This option forces a ASCII mode of copying regardless of the file type. When copying in ASCII mode from HP-UX to LIF the default file type is BINARY (1). (For details on available modes of copying refer to .IR lif (4)). This option has no effect when copying from LIF to LIF. .TP .B \-b This option forces a BINARY mode of copying regardless of the file type. When copying in BINARY mode from HP-UX to LIF the default file type is BINARY (\-2). (For details on available modes of copying refer to .IR lif (4)). This option has no effect when copying from LIF to LIF. .TP .BI \-i xxx Used only when copying files to a LIF volume. This option sets the "implementation" field of the LIF directory entry to the argument given. The argument value can be decimal, octal or hex, using standard "C" notation. The "implementation" field can only be set for file types \-2001 to \-100000 (octal). The "implementation" field is set to zero for all interchange file types and for file types \-2 to \-200 (octal). Note that the "implementation" value controls the attributes of the LIF file with regard to protection and record sizes. .B lifls \-l or .B lifls \-i can be used to determine the "implementation" value of a file. .TP .B \-r Forces RAW mode copying regardless of file type. When copying in RAW mode from HP-UX to LIF the default file type is BIN (\-23951). .B \-T option overrides the default file type. (various modes of copying are explained in .IR lif (4).) \-r option has no effect in LIF to LIF copy operations. .TP .B \-t causes HP-UX file names to be translated to a name acceptable by a LIF utility; that is, all lowercase letters are converted to uppercase and all other characters except numerics are changed to an underscore (_). If the HP-UX file name starts with a nonletter, the file name is preceded by the capital letter X. Thus, for example, if two files named colon (:) and semicolon (;), were copied, both of them would be translated to X_. File names are truncated to a maximum of 10 characters. When copying a LIF file to an HP-UX or LIF file, .B \-t has no effect. Omitting .B \-t causes an error to be generated if an improper name is used. .RE .PP .ne 10 The default copying modes when copying from LIF to HP-UX are summarized in the following table: .IP .TS lB | lB lp-1 | lp-1. File Type Default Copying Mode _ ASCII ASCII BINARY BINARY BIN RAW \s+1other\s0 RAW .TE .PP When copying from HP-UX to LIF, the default copying mode is ASCII and an ASCII file is created. .PP When copying from LIF to LIF, if no options are specified, then all the LIF directory fields and file contents are duplicated from source to destination. .PP A LIF file name is recognized by the embedded colon (:) delimiter (see .IR lif (4) for LIF file naming conventions). A LIF directory is recognized by a trailing colon. If an HP-UX file name containing a colon is used, the colon must be escaped with two backslash characters (\\\\) (the shell removes one of them). .PP The file name .B \- (dash) is interpreted to mean standard input or standard output, depending on its position in the argument list. This is particularly useful if the data requires nonstandard translation. When copying from standard input, if no other name can be found, the name "STDIN" is used. .PP LIF file naming conventions are known only to the LIF utilities. Since file name expansion is done by the shell, this mechanism cannot be used for expanding LIF file names. .PP .B "Do not mount the special file while using" .IB lifcp . .SH DIAGNOSTICS .I lifcp returns exit code 0 if the file is copied successfully. Otherwise it prints a diagnostic and returns nonzero. .SH EXAMPLES Copy HP-UX file .B abc to LIF file .B CDE on LIF volume .B lifvol which is actually an HP-UX file initialized to be a LIF volume: .IP .B "lifcp abc lifvol:CDE" .PP Copy all the HP-UX files in the current directory to the LIF volume .B lifvol which is present in the parent directory. File names are translated to appropriate LIF file names. .IP .B lifcp \-t \(** ../lifvol: .PP Copy all the HP-UX object files in the current directory to the LIF volume .IR lifvol . Copying mode is RAW and LIF file types are set to \-5555. .IP .B lifcp \-r \-T \-5555 \-t \(**.o lifvol: .PP Copy all the object files in the current directory to the LIF volume .BR lifvol . Copying mode is BINARY and LIF BINARY files are created. .IP .B "lifcp \-r \-T 0xffffe961 \-i 0x20200080 bdat lifvol:BDAT" .PP Copy a BDAT file, without a password, from a BASIC WorkStation to an HP-UX LIF volume .BR lifvol . Note that .B \-i controls protection and record size attributes. The file type for a BDAT file is \-5791 (or 0xffffe961) and its record size is 256 bytes per record. .IP .B lifcp \-b \(**.o lifvol: .PP Copy all files in the current directory to the LIF volume .B lifvol in the .B root directory. Copying mode is RAW and LIF file types are set to BIN. .IP .B lifcp \-r \-t \(** /lifvol: .PP Copy file .B abc: to LIF file .B CDE in .BR lifvol . .IP .B lifcp abc\e\e: lifvol:CDE .PP Copy files .B abc and .B def to LIF files .B ABC and .B DEF within .BR lifvol . .IP .B lifcp \-t abc def lifvol: .PP Copy LIF file .B ABC within .B lifvol to file .B ABC within current directory. .IP .B lifcp lifvol:ABC . .PP Copy standard input to LIF file .B A_FILE on LIF volume .BR /dev/dsk/c0t6d0 . .IP .B lifcp \- /dev/dsk/c0t6d0:A_FILE .PP Copy LIF file .B ABC in .B lifvol to LIF file .B CDE on .B /dev/dsk/c0t6d0 . .IP .B lifcp lifvol:ABC /dev/dsk/c0t6d0:CDE .PP Copy the output of .I pr to the LIF file .BR ABC . .IP .B pr abc | lifcp \- lifvol:ABC .PP Copy the output of .I pr to the LIF volume .BR lifvol . LIF file .B STDIN is created since no files names are specified. .IP .B pr abc | lifcp \- lifvol: .PP Copy LIF file .B ABC in .B lifvol to .IR "standard output" . .IP .B lifcp lifvol:ABC \- .PP Copy all files in current directory to LIF files of the same name on LIF volume .B lifvol (may cause errors if file names in the current directory do not obey LIF naming conventions!). .IP .B lifcp \(** ../lifvol: .SH DEPENDENCIES .TP .5i Series 700/800 The following option is also supported: .RS .TP 15 .BI \-K nnn forces each file copied in to begin on a .I nnn \(mu 1024-byte boundary from the beginning of the volume. This is useful when files are used for Series 700/800 boot media. This option has no effect when copying from a LIF volume. .SH AUTHOR .I lifcp was developed by the Hewlett-Packard Company. .SH SEE ALSO lifinit(1), lifls(1), lifrename(1), lifrm(1), lif(4). .\" index@\f4lifcp\f1 \- copy to or from LIF files@@@\f3lifcp(1)\f1 .\" index@\f1LIF files, copy to or from@@@\f3lifcp(1)\f1 .\" index@\f1copy to or from LIF files@@@\f3lifcp(1)\f1 .\" .\" toc@\f3lifcp(1)\f1:\0\0\f2lifcp\f1@@@copy to or from LIF files .\" $Header: lifinit.1,v 72.5 94/07/05 16:15:12 ssa Exp $ .TA l .TH lifinit 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lifinit \- write LIF volume header on file .SH SYNOPSIS .C lifinit .RC [ -v\c .IR nnn\| ] .RC [ -d\c .IR nnn\| ] .RC [ -n .IR string\| ] .RC [ -s\c .IR nnn\| ] .RC [ -l\c .IR nnn\| ] .RC [ -e\c .IR nnn\| ] .I file .SH DESCRIPTION .C lifinit writes a LIF volume header on a volume or file. .SS Options .C lifinit recognizes the following options and command-line arguments which can appear in any order: .RS .TP 11 .CI -v nnn Sets volume size to .I nnn bytes. If .I nnn is not a multiple of 256, it is rounded down to the next such multiple. .TP .CI -d nnn Sets directory size to .I nnn file entries. If .I nnn is not an integer multiple of 8, it is rounded up to next such multiple. .TP .CI -n \0string Sets the volume name to be .IR string . If the .C -n option is not specified, the volume name is set to the last component of the path name specified by .IR file . A legal LIF volume name is 6 characters long and is limited to uppercase letters (A-Z), digits (0-9) and the underscore character (_). The first character (if any) must be a letter. The utility automatically performs translation to create legal LIF volume names. Therefore, all lowercase letters are converted to uppercase, and all other characters except numeric and underscore are replaced with a capital letter .CR X . If the volume name does not start with a letter, the volume name is preceded by a capital letter .CR X . The volume name is also right-padded with spaces or truncated as needed to be six characters long. If .C -n is used with no .IR string , the default volume name is set to 6 spaces. .TP .CI -s nnn set the initial system load (ISL) start address to .I nnn in the volume label. This is useful when building boot media for Series 700/800 systems. .TP .CI -l nnn specifies the length in bytes of the ISL code in the LIF volume. .TP .CI -e nnn set the ISL entry point to .I nnn bytes from the beginning of the ISL. For example, specifying .C -e3272 means that the ISL entry point is 3272 (decimal) bytes from the beginning of the ISL object module. .TP .CI -K nnn forces the directory start location to be the nearest multiple of .I nnn \(mu 1024 bytes from the beginning of the volume. This is necessary for booting Series 700/800 systems from LIF media. .RE .PP If .I file does not exist, a regular HP-UX disk file is created and initialized. .PP The default values for volume size are 256 kilobytes for regular files, and the actual capacity of the device for device files. .PP The default directory size is a function of the volume size. A percentage of the volume size is allocated to the volume directory as follows: .PP .TS center; cB | cB c | c. Volume Size Directory Size _ < 2MB ~1.3% > 2MB ~0.5% .TE .PP Each directory entry occupies 32 bytes of storage. The actual directory space is subject to the rounding rules stated above. .PP .I "Do not mount the special file while using" .CR lifinit . .SH RETURN VALUE .C lifinit returns exit code 0 if the volume is initialized successfully. Otherwise it prints a diagnostic message and returns nonzero. .SH EXAMPLES Initialize file .C x to be a LIF volume containing 500\|000 bytes with 10 directory file entries: .IP .C lifinit -v500000 -d10 x .PP Initialize device .C /dev/rdsk/c0t6d0 as a LIF volume using default initialization conditions (device must not be a mounted file system device): .IP .C lifinit /dev/rdsk/c0t6d0 .SH WARNINGS To prevent media corruption, do not terminate .I lifinit once it has started executing. .SH AUTHOR .C lifinit was developed by HP. .SH SEE ALSO lifcp(1), lifls(1), lifrename(1), lifrm(1), lif(4). .\" .\" index@\f4lifinit\f1 \- write LIF volume header on file@@@\f3lifinit(1)\f1 .\" index@\f1LIF files, write LIF volume header on file@@@\f3lifinit(1)\f1 .\" index@\f1write LIF volume header on file@@@\f3lifinit(1)\f1 .\" index@\f1volume header on LIF file, write@@@\f3lifinit(1)\f1 .\" .\" toc@\f3lifinit(1)\f1:\0\0\f4lifinit\f1@@@write LIF volume header on file .\" $Header: lifls.1,v 78.1 96/02/12 14:02:53 ssa Exp $ .TA l .TH lifls 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lifls \- list contents of a LIF directory .SH SYNOPSIS .C lifls .RC [ \|option\| ] .I name .SH DESCRIPTION .C lifls lists the contents of a LIF directory on standard output. The default output format lists file names in multiple columns (similar to .IR ls (1), except unsorted) if standard output is a character special file. If standard output is not a tty device, the output format is one file name per line. .I name is a path name to an HP-UX file containing a LIF volume and optional file name. If .I name is a volume name, the entire volume is listed. If .I name is of the form .IC volume : file\f1, only the file is listed. The following options are available, and only one option should be specified with a given command: .RS .TP 8 .C -l List in long format, giving volume name, volume size, directory start, directory size, file type, file size, file start, "implementation" field (in hex), date created, last volume, and volume number. .TP .C -C Force multiple column output format regardless of standard output type. .TP .C -L Return the content of the "last volume flag" in decimal. .TP .C -i Return the content of the "implementation" field in hex. .TP .C -v Return the content of the "volume number" in decimal. .TP .CI -b \0blist Report only on files using block numbers specified on the command line in .I blist, a comma separated list of block numbers in DEV_BSIZE units. .RE .PP .I "Do not mount the special file while using" .CR lifls . .SH DIAGNOSTICS .C lifls returns zero if the directory was listed successfully. Otherwise it prints a diagnostic and returns nonzero. .SH EXAMPLES .C lifls -C /dev/rdsk/c0t6d0 .SH AUTHOR .C lifls was developed by HP. .SH SEE ALSO lifcp(1), lifinit(1), lifrename(1), lifrm(1), lif(4). .\" .\" index@\f4lifls\f1 \- list contents of a LIF directory@@@\f3lifls(1)\f1 .\" index@\f1LIF files, list contents of a LIF directory@@@\f3lifls(1)\f1 .\" index@\f1list contents of a LIF directory@@@\f3lifls(1)\f1 .\" index@\f1LIF directory, list contents of a@@@\f3lifls(1)\f1 .\" .\" toc@\f3lifls(1)\f1:\0\0\f4lifls\f1@@@list contents of a LIF directory .\" $Header: lifrename.1,v 72.4 94/07/05 16:18:02 ssa Exp $ .TA l .TH lifrename 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lifrename \- rename LIF files .SH SYNOPSIS .C lifrename .I oldfile newfile .SH DESCRIPTION .I oldfile is a full LIF file specifier (see .IR lif (4) for details) for the file to be renamed (e.g. .CR liffile:A_FILE ). .I newfile is new name to be given to the file (only the file name portion). This operation does not include copy or delete. Old file names must match the name of the file to be renamed, even if that file name is not a legal LIF name. .PP .I "Do not mount the special file while using" .CR lifrename . .SH DIAGNOSTICS .C lifrename returns zero if the file name is changed successfully. Otherwise it prints a diagnostic and returns nonzero. .SH EXAMPLES .C lifrename liffile:A_FILE B_FILE .br .C lifrename /dev/dsk/c0t6d0:ABC CDE .SH AUTHOR .C lifrename was developed by HP. .SH SEE ALSO lifcp(1), lifinit(1), lifls(1), lifrm(1), lif(4). .\" index@\f4lifrename\f1 \- rename LIF files@@@\f3lifrename(1)\f1 .\" index@\f1LIF files, rename@@@\f3lifrename(1)\f1 .\" index@\f1rename LIF files@@@\f3lifrename(1)\f1 .\" .\" toc@\f3lifrename(1)\f1:\0\0\f4lifrename\f1@@@rename LIF files .\" $Header: lifrm.1,v 72.4 94/07/05 16:10:26 ssa Exp $ .TA l .TH lifrm 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lifrm \- remove a LIF file .SH SYNOPSIS .C lifrm .IR file1 " ... " filen .SH DESCRIPTION .C lifrm removes one or more entries from a LIF volume. File name specifiers are as described in .IR lif (4). .PP .I "Do not mount the special file while using" .CR lifrm . .SH DIAGNOSTICS .C lifrm returns zero if the file is removed successfully. Otherwise it prints a diagnostic and returns nonzero. .SH EXAMPLES .C lifrm liffile:MAN .br .C lifrm /dev/rdsk/c0t6d0:F .SH AUTHOR .C lifrm was developed by HP. .SH SEE ALSO lifcp(1), lifinit(1), lifls(1), lifrename(1), lif(4). .\" .\" index@\f4lifrm\f1 \- remove a LIF file@@@\f3lifrm(1)\f1 .\" index@\f1LIF files, remove@@@\f3lifrm(1)\f1 .\" index@\f1remove a LIF file@@@\f3lifrm(1)\f1 .\" .\" toc@\f3lifrm(1)\f1:\0\0\f4lifrm\f1@@@remove a LIF file .\" $Header: line.1,v 72.4 94/11/14 15:19:32 ssa Exp $ .TA l .TH line 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME line \- read one line from user input .SH SYNOPSIS .C line .RC [ -t .IR timeout\| ] .SH DESCRIPTION .C line copies one line (up to a new-line) from the standard input and writes it on the standard output. It returns an exit code of 1 on .SM EOF and always prints at least a new-line. It is often used within shell files to read from the user's terminal. .SS Options .C line recognizes the following command-line option: .RS .TP 12 .CI -t \0timeout Timeout after .I timeout seconds where .I timeout is an integer value (if a non-integer value is specified, it is converted to an integer; i.e., rounded down). A blank is required between .C -t and the .I timeout argument. This option is not documented in .SM POSIX and other industry standards, and should not be used in portable applications. .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following lines in a shell script prompt for a file name and display information about the file: .nf .IP .C "echo 'Enter file name: \ec'" .C reply=`line` .C ls -l $reply .fi .PP To limit the response time to 10 seconds, use the form: .IP .C reply=`line -t 10` .PP then test for no response. If no response occurs before timeout expires, a default behavior should be provided. .SH SEE ALSO sh(1), read(2). .SH STANDARDS CONFORMANCE .CR line ": SVID2, SVID3, XPG2, XPG3" .\" .\" toc@\f3line(1)\f1:\0\0\f4line\f1@@@read one line from user input .\" .\" index@\f4line\f1 \- read one line from user input@@@\f3line(1)\f1 .\" index@read one line from user input@@@\f3line(1)\f1 .\" index@input single line from user keyboard@@@\f3line(1)\f1 .\" index@line, single, input from user keyboard@@@\f3line(1)\f1 .\" .\" fileset_database@line.1 USER-CMDS-MAN .\" $Header: listusers.1,v 72.2 94/07/01 17:43:27 ssa Exp $ .TA l .TH listusers 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME listusers \- display user login data .SH SYNOPSIS .C listusers .RC [ -g .IR groups ] .RC [ -l .IR logins ] .SH DESCRIPTION The .CR listusers command displays data concerning user logins. The output shows the user login and the .CR /etc/passwd comment field value (e.g., user name, etc.). The default displays data about all user logins. .SS Options The .CR listusers command supports the following options: .RS .TP 15 .CI "-g " groups Display all users belonging to .IR groups , sorted by login. A comma separated list specifies multiple groups. .TP .CI "-l " logins Display the requested .IR logins . A comma separated list specifies multiple logins. .RE .PP A user login has a .SM UID of 100 or greater. .PP When the .CR -l and .CR -g options are combined, a user login is only displayed once, even though the login may belong to multiple specified groups. .SH EXAMPLES List all user logins. .IP .C listusers .PP List all user logins in the group .CR cmds and the users .CR bob ", " john " and " otto , removing all duplicates. .IP .C listusers -g cmds -l bob,john,otto .SH FILES .C /etc/passwd .br .C /etc/group .SH SEE ALSO passwd(1), logins(1M), passwd(1M), group(4), passwd(4). .SH STANDARDS COMPLIANCE .CR listusers ": SVID3" .\" toc@\f3listusers(1M)\f1:\0\0\f4listusers\f1@@@display user login data\f1 .\" index@\f4listusers\f1 \- display user login data@@@\f3listusers(1M)\f1 .\" index@\f1display user login data@@@\f3listusers(1M)\f1 .\" index@\f1user login, display data@@@\f3listusers(1M)\f1 .\" index@\f1login, display data for user@@@\f3listusers(1M)\f1 .\" $Header: ls.1,v 76.2 95/08/23 17:56:11 ssa Exp $ .TA l .TH ls 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ls, l, ll, lsf, lsr, lsx \- list contents of directories .SH SYNOPSIS .CR ls .RC [ \-abcdefgilmnopqrstuxACFLR1 ] .RI [ names ] .PP .CR l .RI [ ls_options ] .RI [ names ] .br .CR ll .RI [ ls_options ] .RI [ names ] .br .CR lsf .RI [ ls_options ] .RI [ names ] .br .CR lsr .RI [ ls_options ] .RI [ names ] .br .CR lsx .RI [ ls_options ] .RI [ names ] .SH DESCRIPTION For each directory argument, the .CR ls command lists the contents of the directory. For each file argument, .CR ls repeats its name and any other information requested. The output is sorted in ascending collation order by default (see Environment Variables below). When no argument is given, the current directory is listed. When several arguments are given, the arguments are first sorted appropriately, but file arguments appear before directories and their contents. .PP If you are a user with appropriate privileges, all files except .CR . and .CR .. are listed by default. .PP There are three major listing formats. The format chosen depends on whether the output is going to a login device (determined by whether output device file is a .I tty device), and can also be controlled by option flags. The default format for a login device is to list the contents of directories in multicolumn format, with entries sorted vertically by column. (When individual file names (as opposed to directory names) appear in the argument list, those file names are always sorted across the page rather than down the page in columns because individual file names can be arbitrarily long.) If the standard output is not a login device, the default format is to list one entry per line. The .CR \-C and .CR \-x options enable multicolumn formats, and the .CR \-m option enables stream output format in which files are listed across the page, separated by commas. In order to determine output formats for the .CR \-C , .CR \-x , and .CR \-m options, .CR ls uses an environment variable, .CR COLUMNS , to determine the number of character positions available on each output line. If this variable is not set, the .I terminfo database is used to determine the number of columns, based on the environment variable .CR TERM . If this information cannot be obtained, 80 columns is assumed. .SS Options .CR ls recognizes the following options: .RS .TP 6 .CR \-a List all entries; usually entries whose names begin with a period .RC ( . ) are not listed. .TP .CR \-b Force printing of nongraphic characters to be in the octal .CI \e ddd notation. .TP .CR \-c Use time of last modification of the inode (file created, mode changed, etc.) for sorting .RC ( \-t ) or printing .RC ( \-l (ell)). .TP .CR \-d If an argument is a directory, list only its name (not its contents); often used with .CR \-l (ell) to get the status of a directory. .TP .CR \-e Print the extent attributes of the file. If any of the files has a extent attribute, this option prints the extent size, space reserved and allocation flags. This option must be used with the .CR \-l (ell) option. .TP .CR \-f Force each argument to be interpreted as a directory and list the name found in each slot. This option disables .CR \-l (ell), .CR \-t , .CR \-s , and .CR \-r , and enables .CR \-a ; the order is the order in which entries appear in the directory. .TP .CR \-g Same as .CR \-l , (ell) except that only the group is printed (owner is omitted). If both .CR \-l (ell) and .CR \-g are specified, the owner is not printed. .TP .CR \-i For each file, print the inode number in the first column of the report. When used in multicolumn output, the number precedes the file name in each column. .TP .CR \-l (ell) List in long format, giving mode, number of links, owner, group, size in bytes, and time of last modification for each file (see further DESCRIPTION and Access Control Lists below). If the time of last modification is greater than six months ago, or any time in the future, the year is substituted for the hour and minute of the modification time. If the file is a special file, the size field contains the major and minor device numbers rather than a size. .TP .CR \-m Stream output format. .TP .CR \-n The same as .CR \-l , (ell) except that the owner's UID and group's GID numbers are printed, rather than the associated character strings. .TP .CR \-o The same as .CR \-l , (ell) except that only the owner is printed (group is omitted). (If both .CR \-l (ell) and .CR \-o are specified, the group is not printed). .TP .CR \-p Put a slash .RC ( / ) after each file name if that file is a directory. .TP .CR \-q Force printing of nongraphic characters in file names as the character .RC ( ? ). .TP .CR \-r Reverse the order of sort to get reverse (descending) collation or oldest first, as appropriate. .TP .CR \-s Give size in blocks, including indirect blocks, for each entry. The first entry printed is the total number of blocks in the directory. When used in multicolumn output, the number of blocks precedes the file name in each column. .TP .CR \-t Sort by time modified (latest first) before sorting alphabetically. .TP .CR \-u Use time of last access instead of last modification for sorting .RC ( \-t option) or printing .RC ( \-l (ell) option). .TP .CR \-x Multicolumn output with entries sorted across rather than down the page. .TP .CR \-A The same as .CR \-a , except that the current directory "." and parent directory ".." are not listed. For a user with appropriate privileges, this flag defaults to ON, and is turned off by .CR \-A . .TP .CR \-C Multicolumn output with entries sorted down the columns. .TP .CR \-F Put a slash .RC ( / ) after each file name if that file is a directory or a symbolic link to a directory; put an asterisk .RC ( * ) after each file name if that file is executable; put an at sign (\f3@\f1) after each file name if that file is a symbolic link to a file; put a vertical bar .RC ( | ) after each file name if that file is a FIFO. .TP .CR \-L If the argument is a symbolic link, list the file or directory to which the link refers rather than the link itself. .TP .CR \-R Recursively list subdirectories encountered. .TP .CR \-1 (one) The file names will be listed in single column format regardless of the output device. This forces single column format to the user's terminal. .RE .PP Specifying more than one of the options in the following mutually exclusive pairs is not considered an error: .CR \-C and .CR \-l (ell), .CR \-m and .CR \-l (ell), .CR \-x and .CR \-l (ell), .CR \-C and .CR \-1 (one), .CR \-c and .CR \-u . .PP .CR ls is normally known by several shorthand-version names for the various formats: .RS .TP 6 .CR l equivalent to .CR "ls \-m" . .PD 0 .TP .CR ll equivalent to .CR "ls \-l" (ell). .TP .CR lsf equivalent to .CR "ls \-F" . .TP .CR lsr equivalent to .CR "ls \-R" . .TP .CR lsx equivalent to .CR "ls \-x" . .RE .PD .PP The shorthand notations are implemented as links to .CR ls . Option arguments to the shorthand versions behave exactly as if the long form above had been used with the additional arguments. .PP .B "Mode Bits Interpretation (\-l option)" .br The mode printed in listings produced by the .CR \-l (ell) option consists of 10 characters. The first character indicates the entry type: .RS .TP 6 .CR d Directory .PD 0 .TP .CR b Block special file .TP .CR c Character special file .TP .CR l Symbolic link .TP .CR p Fifo (also called a "named pipe") special file .TP .CR n Network special file .TP .CR s socket .TP .CR \- Ordinary file. .RE .PD .PP The next 9 characters are interpreted as three sets of three bits each which identify access permissions for owner, group, and others as follows: .IP .nf .if t \{ .sp -1v .cs R 19 __________________ \d0400 read by owner (\f3r\f1 or \f3\(mi\f1) | ________________ \d0200 write by owner (\f3w\f1 or \f3\(mi\f1) | | ______________ \d0100 execute (search directory) by owner\ (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | ____________ \d0040 read by group (\f3w\f1 or \f3\(mi\f1) | | | | __________ \d0020 write by group (\f3r\f1 or \f3\(mi\f1) | | | | | ________ \d0010 execute/search by group\ (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | | | | ______ \d0004 read by others (\f3r\f1 or \f3\(mi\f1) | | | | | | | ____ \d0002 write by others (\f3w\f1 or \f3\(mi\f1) | | | | | | | | __ \d0001 execute/search by others\ (\f3x\f1, \f3t\f1, \f3T\f1, or \f3\(mi\f1) | | | | | | | | | r w x r w x r w x .cs R .fi \} .if n \{ +------------------ 0400 read by owner (\f3r\f1 or \f3\(mi\f1) | +---------------- 0200 write by owner (\f3w\f1 or \f3\(mi\f1) | | +-------------- 0100 execute (search directory) by owner | | | (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | +------------ 0040 read by group (\f3r\f1 or \f3\(mi\f1) | | | | +---------- 0020 write by group (\f3w\f1 or \f3\(mi\f1) | | | | | +-------- 0010 execute/search by group | | | | | | (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | | | | +------ 0004 read by others (\f3r\f1 or \f3\(mi\f1) | | | | | | | +---- 0002 write by others (\f3w\f1 or \f3\(mi\f1) | | | | | | | | +-- 0001 execute/search by others | | | | | | | | | (\f3x\f1, \f3t\f1, \f3T\f1, or \f3\(mi\f1) | | | | | | | | | r w x r w x r w x .fi \} .PP Mode letters are interpreted as follows: .RS .TP 7 .CR \- Permission .I not granted in corresponding position. .TP .CR r Read permission granted to corresponding user class. .TP .CR w Write permission granted to corresponding user class. .TP .CR x Execute (or search in directory) permission granted to corresponding user class. .TP .CR s Execute (search) permission granted to corresponding user class. In addition, SUID (Set User ID) permission granted for owner, or SGID (Set Group ID) permission granted for group, as indicated by position. .TP .CR S Same as .CR s except that execute (search) permission is denied to corresponding user class. .TP .CR t (last position only) Execute (search) permission granted to others and "sticky bit" is set (see .IR chmod (2) .CR S_ISVTX description). .TP .CR T Same as .CR t except execute (search directory) permission denied to others. .RE .PP When an option is specified that results in a listing of directory and/or file sizes in bytes or blocks (such as the .CR \-s or .CR \-l (ell) option), a total count of blocks, including indirect blocks, is also printed at the beginning of the listing. .SS "Access Control Lists (ACLs)" If a file has optional ACL entries, the .CR \-l (ell) option displays a plus sign .RC ( + ) after the file's permissions. The permissions shown are a summary representation of the file's access control list, as returned by .CR stat() in the .I st_mode field (see .IR stat (2)). To list the contents of an access control list, use the .CR lsacl command (see .IR lsacl (1) and .IR acl (5)). .SH EXTERNAL INFLUENCES .SS Environment Variables If the .CR COLUMNS variable is set, .CR ls uses the width provided in determining positioning of columnar output. .PP .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not set or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .CR LC_COLLATE determines the order in which the output is sorted. .PP .CR LC_CTYPE determines which characters are classified as nongraphic for the .CR \-b and .CR \-q options, and the interpretation of single- and/or multibyte characters within file names. .PP .CR LC_TIME determines the date and time strings output by the .CR \-g , .CR \-l (ell), .CR \-n , and .CR \-o options. .PP .C LC_MESSAGES determines the language in which messages (other than the date and time strings) are displayed. .PP If any internationalization variable contains an invalid setting, .CR ls behaves as if all internationalization variables are set to "C" (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .br .ne 3v .SH RETURN VALUE .CR ls exits with one of the following values: .RS .TP 5 .CR \00 All input files were listed successfully. .TP .CR >0 .CR ls was aborted because errors occurred when accessing files. The following conditions cause an error: .RS 8 .TP 3 \(bu Specified file not found. .TP \(bu User has no permission to read the directory. .TP \(bu Process could not get enough memory. .TP \(bu Invalid option specified. .RE .RE .SH EXAMPLES Print a long listing of all the files in the current working directory (including the file sizes). List the most recently modified (youngest) file first, followed by the next older file, and so forth, to the oldest. Files whose names begin with a .CR . are also printed. .IP .C "ls \-alst" .SH WARNINGS Setting options based on whether the output is a login .RI ( tty ) device is undesirable because .CR "ls \-s" is very different from .CR "ls \-s | lp" . On the other hand, not using this setting makes old shell scripts that used .CR ls almost inevitably fail. .PP Unprintable characters in file names may confuse the columnar output options. .SH DEPENDENCIES .TP 5 NFS The .CR \-l (ell) option does not display a plus sign .RC ( + ) after the access permission bits of networked files to represent existence of optional access control list entries. .SH AUTHOR .CR ls was developed by AT&T, the University of California, Berkeley and HP. .SH FILES .TP 25 .CR /etc/passwd to get user IDs for .CR "ls \-l" (ell) and .CR "ls \-o" . .PD 0 .TP .CR /etc/group to get group IDs for .CR "ls \-l" (ell) and .CR "ls \-g" . .TP .CR /usr/share/lib/terminfo/?/* to get terminal information. .PD .SH SEE ALSO chmod(1), find(1), lsacl(1), stat(2), acl(5). .SH STANDARDS CONFORMANCE .CR ls ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4l\f1 \(mi list directory contents in stream output format@@@\f3ls(1)\f1 .\" index@\f4ls\f1 \(mi list directory contents@@@\f3ls(1)\f1 .\" index@\f4lsf\f1 \(mi list directory contents, showing subdirectories and executable files@@@\f3ls(1)\f1 .\" index@\f4ll\f1 \(mi list directory contents in long format@@@\f3ls(1)\f1 .\" index@\f4lsr\f1 \(mi recursively list directory contents and subtrees@@@\f3ls(1)\f1 .\" index@\f4lsx\f1 \(mi list directory contents, sort across page instead of down@@@\f3ls(1)\f1 .\" index@list contents of directory@@@\f3ls(1)\f1 .\" index@directory: list contents of directory@@@\f3ls(1)\f1 .\" index@contents of directory, list@@@\f3ls(1)\f1 .\" index@executable files in directory, list@@@\f3ls(1)\f1 .\" index@subdirectories in directory, list@@@\f3ls(1)\f1 .\" .\" toc@\f3ls(1)\f1:\0\0\f4ls\f1, \f4l\f1, \f4ll\f1, \f4lsf\f1, \f4lsr\f1, \f4lsx\f1@@@list contents of directories .\" toc@\f4l\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4ll\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsf\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsr\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsx\f1: list contents of directories@@@see \f3ls(1)\f1 .\" .\" links@ls.1 l.1 .\" links@ls.1 ll.1 .\" links@ls.1 lsf.1 .\" links@ls.1 lsr.1 .\" links@ls.1 lsx.1 .\" $Header: ln.1,v 76.2 95/08/03 17:59:41 ssa Exp $ .TA l .TH ln 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ln \- link files and directories .SH SYNOPSIS .CR ln .RC [ \-f ] .RC [ \-i ] .RC [ \-s ] .I file1 .I new_file .PP .CR ln .RC [ \-f ] .RC [ \-i ] .RC [ \-s ] .I file1 .RI [ file2 \0...] .I dest_directory .PP .CR ln .RC [ \-f ] .RC [ \-i ] .RC [ \-s ] .I directory1 .RI [ directory2 \0...] .I dest_directory .SH DESCRIPTION The .CR ln command links: .RS .TP 3 \(bu .I file1 to a new or existing .IR new_file , .TP \(bu .I file1 to a new or existing file named .I file1 in existing .IR dest_directory , .TP \(bu .IR file1 , .IR file2 ,\0... to new or existing files of the same name in existing .IR dest_directory , .TP \(bu .IR directory1 , .IR directory2 ,\0... to new directories of the same name in existing .I dest_directory, .TP \(bu or it creates symbolic links between files or between directories. .RE .PP If links are to .IR dest_directory , corresponding file or directory names in that directory are linked to .IR file1 , .IR file2 ,\0..., or .IR directory1 , .IR directory2 ,\0..., etc., as appropriate. If two or more existing files or directories (excluding destination file name .IR new_file ) are specified, the destination must be a directory. If .I new_file already exists as a regular file (or link to another file), its contents (or the existing link) and its ACL are destroyed only if the .CR \-f option is specified. The ACL on the .I new_file after the link is the same as that of the .I source_file file. .PP If the .CR \-f and .CR \-i options are specified and the link being created is the name of an existing link or ordinary file and the access permissions of the file forbid writing, .CR ln asks permission to overwrite the file. If the access permissions of the directory forbid writing, .CR ln aborts and returns with the error message: .IP .CI "cannot unlink " new_file .PP (even if the file is an ordinary file and not a link to another file). When asking for permission to overwrite an existing file or link, .CR ln prints the mode (see .IR chmod (2) and .BR "Access Control Lists" below), followed by the first letters of the words .CR yes and .CR no in the current native language, prompting for a response, and reading one line from the standard input. If the response is affirmative and is permissible, the operation occurs; if not, the command proceeds to the next source file, if any. .PP Hard links and symbolic links are created with the same ownerships and permissions as the file or directory to which they are linked. If ownership or permissions are changed on a link, file, or directory, the same changes appear on corresponding hard and symbolic links. The .CR ln command does not permit hard links to a directory. .PP If .I file1 is a file and .I new_file is a link to an existing file or an existing file with other links, .I new_file is disassociated from the existing file and links and linked to .IR file1 . When .CR ln creates a link to a new or existing file name, ownerships and permissions are always identical to those for the file to which it is linked. If .CR chown , .CR chgrp , or .CR chmod is used to change ownership or permissions of a file or link, the change applies to the file and all associated links. The last modification time and last access time of the file and all associated links are identical (see .IR chown (1), .IR chgrp (1), and .IR chmod (1)). .PP For a discussion of symbolic links, see .IR symlink (4). .SS Options The .CR ln command recognizes the following options: .RS .TP 8 .CR \-f Force existing destination path names to be removed to allow the link. .TP .CR \-i Write a prompt to the standard error output requesting confirmation for each link that would overwrite an existing file. This option takes effect only if used in conjunction with the .CR \-f option. .TP .CR \-s Cause .CR ln to create symbolic links instead of the usual hard links. A symbolic link contains the name of the file to which it is linked. The referenced file is used when an .CR open() operation is performed on the link (see .IR open (2)). A .CR stat() on a symbolic link returns the linked-to file; an .CR lstat() must be performed to obtain information about the link (see .IR stat (2)). A .CR readlink() call can be used to read the contents of the symbolic link (see .IR readlink (2)). Symbolic links may span file systems and refer to directories. .RE .SS "Access Control Lists (ACLs)" If optional ACL entries are associated with .IR new_file , .CR ln displays a plus sign .RC ( + ) after the access mode when asking permission to overwrite the file. .PP If .I new_file is a new file, it inherits the access control list of .IR file1 , altered to reflect any difference in ownership between the two files (see .IR acl (5)). .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_CTYPE determines the interpretation of text as single byte and/or multibyte characters. .PP .CR LANG and .CR LC_CTYPE determine the local language equivalent of .CR y (for yes/no queries). .PP .CR LANG determines the language in which messages are displayed. .PP If .CR LC_CTYPE is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of .CR C (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR ln behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .SS International Code Set Support Single byte and multibyte character code sets are supported. .SH EXAMPLES The following command creates .CR file1 and .CR file2 in .CR dest_dir , which are linked back to the original files .CR file1 and .CR file2 : .IP .C "ln \-f file1 file2 dest_dir" .PP If .CR file1 and/or .CR file2 exists in the destination directory, it is removed and replaced by a link to .CR file1 or .CR file2 , respectively. If existing file .CR file1 or .CR file2 is a link to another file or a file with links, the existing file remains. Only the link is broken and replaced by a new link to .CR file1 or .CR file2 . .SH WARNINGS .CR ln does not create hard links across file systems. .SH DEPENDENCIES .SS NFS Access control lists of networked files are summarized (as returned in .CR st_mode by .CR stat() ), but not copied to the new file. When using .CR ln on such files, a .CR + is not printed after the mode value when asking for permission to overwrite a file. .SH AUTHOR .CR ln was developed by AT&T, the University of California, Berkeley and HP. .SH SEE ALSO cp(1), cpio(1), mv(1), rm(1), link(1M), readlink(2), stat(2), symlink(2), symlink(4), acl(5).\"STD .SH STANDARDS CONFORMANCE .CR ln ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4ln\f1 \- link files and directories@@@\f3ln(1)\f1 .\" index@\f1symbolic links between files or directories, create@@@\f3ln(1)\f1 .\" index@\f1link existing file to new file name@@@\f3ln(1)\f1 .\" .\" NOTE: DO NOT remove the space between the word "links" and .\" the @@@ in the next index entry. This will cause .\" errors in the checkout link processing, as the checkout .\" script searches on the string "links" followed by either .\" an "@" or a - pv .\" .\" index@\f1link directories using symbolic links @@@\f3ln(1)\f1 .\" index@\f1file, link existing file to a new file name@@@\f3ln(1)\f1 .\" index@\f1directory, symbolic links between directories, create@@@\f3ln(1)\f1 .\" toc@\f3ln(1)\f1:\0\0\f4ln\f1@@@link files and directories\f1 .\" $Header: locale.1,v 76.1 95/08/03 18:06:32 ssa Exp $ .TA l .TH locale 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME locale \- get locale-specific (NLS) information .SH SYNOPSIS .C locale .RC [ -a \(or -m ] .PP .C locale .RC [ -ck ] .IR name \0... .SH DESCRIPTION The .CR locale command displays information about the current locale or about available locales. .PP When invoked without arguments, .CR locale displays the name and actual or implied value of each of the locale-related environment variables in the order shown below, one per line: .nf .IP .C LANG .C LC_CTYPE .C LC_COLLATE .C LC_MONETARY .C LC_NUMERIC .C LC_TIME .C LC_MESSAGES .C LC_ALL .fi .PP An actual value is the value the variable actually has in the user's environment. An implied value is derived from the value of another variable. Implied values are displayed enclosed in double quotes, while actual values are unquoted. .PP The determination of implied values is that if the variable .CR LC_ALL is present and has a non-null value, that is the actual value for .CR LC_ALL , and all of the other variables take its value as an implied value. If .CR LC_ALL is not set, all of the .CR LC_* variables that are set are shown with their value as an actual value. Any that have no value are shown with the value of the .CR LANG environment variable as their implied value. .CR LC_ALL is displayed as .CR LC_ALL=\en if it has no value. .PP The .CR locale command can take multiple arguments, which may be locale category names, locale keywords, or the special word .CR charmap (see .IR localedef (1M) for a description of locale keywords and charmaps). If an argument is a keyword, the value associated with that keyword in the current environment is displayed and possibly other information, depending on selected options. If an argument is a category name (i.e., .CR LC_* ), the values of all keywords defined in that category are displayed. If an argument is the special word .CR charmap , the charmap file (if any) that was used in the definition of the current locale is displayed. .ifn .bp .PP Non-printable characters are printed as hexadecimal values in the form, .IP "\exhh" .PP except that if a different escape character has been defined for the locale, it is displayed instead of the "\e". .SS Options The following options are available: .RS .TP 10 .C -a List all available locales. These are the possible meaningful values that can be assigned to .CR LANG or any of the .CR LC_* variables on the system. They are dependent upon which locales have been installed on the system. By default, the locales in .CR /usr/lib/nls/loc/locales are listed. .TP .C -c Display names of locale categories that have been selected either explicitly or by giving a keyword contained therein. This option may be used with the .CR -k option. .TP .C -k Display names of keywords that have been selected either explicitly or by providing their containing category as an argument. Keyword names and values are displayed as: .RS .IP .CR "=" .RE .IP Without the .CR -k option, only the values are displayed. This option can be used with the .CR -c option. .TP 10 .C -m Display a list of available charmap files on the system. See .IR localedef (1M) for a definition of charmap files and their usage. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG provides a default value for the internationalization variables that are unset or null. If .CR LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .CR locale will behave as if all internationalization variables are set to "C". See .IR environ (5). .PP .CR LC_ALL , when set to a non-empty string value, overrides the values of all other internationalization variables. .ifn .bp .PP .CR LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .CR LC_MESSAGES determines the locale that should be used to affect the format and content of diagnostic messages written to standard error, and informative messages written to standard output. .PP .CR NLSPATH determines the location of message catalog for the processing of .CR LC_MESSAGES . .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE The .CR locale command exits with one of the following values: .RS .TP 5 .C \00 All requested information was found and displayed successfully. .TP .C >0 An error occurred in either finding or displaying the information. .RE .SH EXAMPLES If the locale environment variables are set as: .nf .IP .C LANG=fr_FR.iso88591 .C LC_COLLATE=C .fi .PP the command: .IP .CR locale .PP gives the following output: .nf .IP .C LANG=fr_FR.iso88591 .C LC_CTYPE="fr_FR.iso88591" .C LC_COLLATE=C .C LC_MONETARY="fr_FR.iso88591" .C LC_NUMERIC="fr_FR.iso88591" .C LC_TIME="fr_FR.iso88591" .C LC_MESSAGES="fr_FR.iso88591" .C LC_ALL= .fi .ifn .bp .PP The command: .IP .C "LC_ALL=POSIX locale -ck decimal_point" .PP produces: .IP .C "LC_NUMERIC decimal_point="".""" .PP If .CR LANG is set to .CR POSIX and no other locale variables are set, the command: .IP .C "locale LC_NUMERIC" .PP produces: .nf .IP .C """.\&""" .C """""" .C """""" .fi .PP which correspond to the keywords .IR decimal_point , .IR thousands_sep , .IR grouping , and .IR alt_digit . .SH SEE ALSO localedef(1M), localeconv(3C), nl_langinfo(3C), setlocale(3C), charmap(4), localedef(4), environ(5), lang(5). .SH STANDARDS CONFORMANCE .CR locale ": XPG4, POSIX.2" .\" .\" toc@\f3locale(1)\f1:\0\0\f4locale\f1@@@get locale-specific (NLS) information\f1 .\" .\" index@\f4locale\f1 \- get locale-specific (NLS) information@@@\f3locale(1)\f1 .\" index@\f1get locale-specific (NLS) information@@@\f3locale(1)\f1 .\" index@\f1locale-specific (NLS) information, get@@@\f3locale(1)\f1 .\" index@\f1NLS information, get locale-specific@@@\f3locale(1)\f1 .\" index@\f1information, get locale-specific (NLS)@@@\f3locale(1)\f1 .\" $Header: lock.1,v 72.3 93/01/14 11:16:13 ssa Exp $ .TA l .TH lock 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lock \- reserve a terminal .SH SYNOPSIS .C lock .SH DESCRIPTION .C lock requests a password from the user, then prints .C LOCKED on the terminal and refuses to relinquish the terminal until the password is repeated. If the user forgets the password, the only recourse is to log in elsewhere and kill the lock process. .\" .\" toc@\f3lock(1)\f1:\0\0\f4lock\f1@@@reserve a terminal .\" .\" index@\f4lock\f1 \- protect terminal from use by others@@@\f3lock(1)\f1 .\" index@lock terminal against use by others@@@\f3lock(1)\f1 .\" index@protect terminal from use by others@@@\f3lock(1)\f1 .\" index@prevent terminal use by others@@@\f3lock(1)\f1 .\" index@terminal, lock against use by others@@@\f3lock(1)\f1 .\" .\" fileset_database@lock.1 USER-CMDS-MAN .\" $Header: logger.1,v 76.3 95/08/03 18:11:48 ssa Exp $ .TA l .TH logger 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME logger \- make entries in the system log .SH SYNOPSIS .C logger .RC [ -t .IR tag ] .RC [ -p .IR pri ] .RC [ -i ] .RC [ -f .IR file ] .RI [ message \|...\|] .SH DESCRIPTION The .CR logger command provides a program interface to the .CR syslog() system log module (see .IR syslog (3C)). .PP A message can be given on the command line, which is logged immediately, or a file is read and each line is logged. If no .I file or .I message is specified, the contents of the standard input are logged. .SS Options The .CR logger command recognizes the following command-line options and arguments: .RS .TP 15 .CI -t \0tag Mark every line in the log with the specified .IR tag . The default is the value returned by .CR getlogin() (see .IR getlogin (3C)). If .CR getlogin() returns NULL, .CR syslog is the default. .TP .CI -p \0pri Enter the message with the specified priority. The priority can be specified numerically or as a .IC facility . level pair. For example, .CR "-p local3.info" logs the message or messages as .CR info rmational level in the .CR local3 facility. The default is .CR user.notice . .TP .C -i Log the process ID of the logger process with each line. .TP .CI -f \0file Log the contents of the specified file. .TP .I message The message to log; if not specified, the file specified by the .CR -f option or standard input is logged. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C logger behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES Send the message .CR "System rebooted" to the .CR syslogd daemon: .IP .C logger System rebooted .PP Send output from the .CR users command (see .IR users (1) to the .CR syslogd daemon, marked as level .CR info and facility .CR local0 . The message is tagged with the string .CR USERS : .IP .C "users | logger -p local0.info -t USERS" .PP Send the message .CR "System going down immediately!!!" to the .CR syslog daemon, at the .CR emerg level and .CR user facility: .IP .C logger -p user.emerg """System going down immediately!!!""" .SH WARNINGS The .CR logger command has no effect if the .CR syslogd daemon (see .IR syslogd (1M)) is not running on the system. .PP Messages written in locales other than the \s-1POSIX/C\s+1 locale are not supported. .SH AUTHOR .CR logger was developed by the University of California, Berkeley. .SH SEE ALSO syslogd(1M), getlogin(3C), syslog(3C). .SH STANDARDS CONFORMANCE .CR logger ": XPG4, POSIX.2" .\" .\" index@\f4logger\f1 \- make entries in the system log@@@\f3logger(1)\f1 .\" index@\f1system log, make entries in@@@\f3logger(1)\f1 .\" index@\f1messages to system log, send@@@\f3logger(1)\f1 .\" index@\f1standard input to system log, send@@@\f3logger(1)\f1 .\" index@\f1files, send to system log@@@\f3logger(1)\f1 .\" .\" toc@\f3logger(1)\f1:\0\0\f4logger\f1@@@make entries in the system log\f1 .\" $Header: login.1,v 78.1 96/01/03 15:33:38 ssa Exp $ .TA l .TH login 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME login \- sign on; start terminal session .SH SYNOPSIS .CR login .RI [ name .RI [ env-var " ...]\|]" .SH DESCRIPTION The .CR login command is used at the beginning of each terminal session to properly identify the prospective user. .CR login can be invoked as a user command, or by the system when an incoming connection is first established. .CR login is also invoked by the system when a previous user shell terminates but the terminal does not disconnect. .PP If .CR login is invoked as a command it must replace the initial command interpreter (user's login shell). This is accomplished by typing: .IP .C "exec login" .PP from the user shell. .PP If .IR name is not specified on the command line, .CR login prompts with .CR login: for the login name and, if required, .CR Password: for the corresponding password. Terminal echo is turned off (where possible) during typing of the password so that it will not appear on any written record of the session. If the login name provided is not valid, .CR login requests a password. This is done to make it more difficult for an unauthorized user to log in to the system by trial and error. After three unsuccessful login attempts, a .CR HANGUP signal is issued. .PP On a trusted system, the .CR login program prints the last successful and unsuccessful login times and terminal devices. If the account does not have a password, and the authentication profile for the account requires one, .CR login starts the .CR passwd program to establish one for the account. .PP As a security precaution, some installations use an option that requires a second "dialup" password. This occurs only for dialup connections, and is prompted with the message .CR "dialup password:" . Both passwords must be correct for a successful login. See .IR dialups (4) for details on dialup security. .PP If password aging has been invoked on the user's behalf by a user with appropriate privileges, the user's password may have expired. In this case, the user will be diverted into .CR passwd to change it, after which the user can attempt to log in again (see .IR passwd (1)). .PP If a login is not successfully completed within a certain period of time (e.g., one minute), the terminal is silently disconnected. .PP After a successful login, the accounting files are updated, user and group IDs, group access list, and working directory are initialized, and the user's command interpreter (shell) is determined from corresponding user entries in the files .CR /etc/passwd and .CR /etc/logingroup (see .IR passwd (4) and .IR group (4)). If .CR /etc/passwd does not specify a shell for the user name, .CR /usr/bin/sh is used by default. .CR login then forks the appropriate shell by using the last component of the shell pathname preceded by a .CR - (for example, .CR -sh or .CR -ksh ). When the command interpreter is invoked with its name preceded by a minus in this manner, the shell performs its own initialization, including execution of profile, login, or other initialization scripts. .PP For example, if the user login shell is the Bourne, Korn, or POSIX shell (see .IR sh-bourne (1), .IR ksh (1), or .IR sh-posix (1), respectively), the shell executes the profile files .CR /etc/profile and .CR $HOME/.profile if they exist (and possibly others as well, depending on what the profile files contain). Depending on what these profile files contain, messages regarding mail in the user's mail file or any messages the user may have received since the user's last login may be displayed. .PP If the command name field is .CR * , a .CR chroot() to the directory named in the directory field of the entry is performed. At that point .CR login is re-executed at the new level which must have its own root structure, including a .CR /usr/bin/login command and an .CR /etc/passwd file. .PP For the normal user, the basic environment variables (see .IR environ (5)) are initialized to: .nf .IP .PD 0 .CI HOME= login_directory .CI LOGNAME= login_name .CI MAIL=/var/mail/ login_name .CI PATH=:/usr/bin .CI SHELL= login_shell .PD .fi .PP .IR login_directory , .IR login_name , and .IR login_shell are taken from the corresponding fields of the .CR passwd file entry (see .IR passwd (4)). .PP For superuser, .CR PATH is set to: .IP .CR PATH=:/usr/sbin:/usr/bin:/sbin .PP In the case of a remote login, the environment variable .CR TERM is also set to the remote user's terminal type. .PP The environment can be expanded or modified by supplying additional arguments to .CR login , either at execution time or when .CR login requests the user's login name. The arguments can take either the form .IR value or .IC varname = value\f1, where .IR varname is a new or existing environment variable name .IR value is a value to be assigned to an enviroment variable. .PP An argument in the first form (without an equals sign) is placed in the environment as if it were entered in the form .IP .CI L n = value .PP where .IR n is a number starting at 0 that is incremented each time a new variable name is required. .PP An argument in the second form (with an equals sign) is placed into the environment without modification. .PP If the variable name .RC ( L \f2n or .IR varname ) already appears in the environment, the new value replaces the older one. .PP There are two exceptions. The variables .CR PATH and .CR SHELL cannot be changed. This prevents users logged in with restricted shell environments from spawning secondary shells that are not restricted. .PP Both .CR login and .CR getty understand simple single-character quoting conventions. Typing a backslash in front of a character quotes it and allows the inclusion of such things as spaces and tabs. .PP If .CR /var/adm/btmp is present, all unsuccessful login attempts are logged to that file. This feature is disabled if the file is not present. The .CR lastb command, (see .IR last (1)), displays a summary of bad login attempts for users with read access to .CR btmp . .PP If the .CR /etc/securetty file is present, login security is in effect. Only user .CR root is allowed to log in successfully on the ttys listed in this file. Restricted ttys are listed by device name, one per line. Valid tty names are dependent on installation. An example is .nf .IP .CR console .CR tty01 .CR ttya1 etc. .fi .PP Note that this feature does not inhibit a normal user from using the .CR su command (see .IR su (1)). .SH SECURITY FEATURES On a trusted system, .CR login prohibits the user from logging in if any of the following are true: .RS .TP 3 \(bu The password for the account has expired and the user cannot successfully change the password. .TP \(bu The password lifetime for the account has passed. .TP \(bu The time between the last login and the current time exceeds the time allowed for login intervals. .TP \(bu The administrative lock on the account has been set. .TP \(bu The maximum number of unsuccessful login attempts for the account has been exceeded. .TP \(bu The maximum number of unsuccessful login attempts for the terminal has been exceeded. .TP \(bu The administrative lock on the terminal has been set. .TP \(bu The terminal has an authorized user list and the user is not on it. .TP \(bu The terminal has time of day restrictions and the current time is not within the allowable period. .RE .PP On a trusted system, .CR login always allows user .CR root to log in on the console unless .CR /etc/securetty exists and does not contain .CR console . .SH DIAGNOSTICS The following diagnostics appear if the associated condition occurs: .PP .C ".rhosts is a soft link" .IP The personal equivalence file is a symbolic link. .PP .C "Bad .rhosts ownership" .IP The personal equivalence file is not owned by the local user or by a user with appropriate privileges. .PP .C "Bad group id" .IP .CR setgid() failed (see .IR setgid (2)). .PP .C "Bad user id" .IP .CR setuid() failed (see .IR setgid (2)). .PP .C "Cannot open password file" .IP Consult system administrator. .PP .C "Locuser too long" .IP The indicated string was too long for .CR login 's internal buffer. .PP .C "Login incorrect" .IP User name and password cannot be matched. .PP .C "No /usr/bin/login or /etc/login on root" .IP Attempted to log in to a subdirectory root that does not have a subroot login command. That is, the .CR passwd file entry had shell path .CR * , but the system cannot find a .CR login command under the given home directory. .PP .C "No directory" .IP Consult system administrator. .PP .C "No Root Directory" .IP Attempted to log in to a subdirectory root that does not exist. That is, the .CR passwd file entry had shell path .CR * , but the system cannot .CR chroot to the given home directory. .PP .C "No shell" .IP The user shell .RC ( /usr/bin/sh if shell name is null in .CR /etc/passwd ) could not be started with the .CR exec command. Consult system administrator. .PP .tr ~" .C "No utmp entry. You must exec ~login~ from the lowest level ~sh~" .br .tr ~~ .IP Attempted to execute .CR login as a command without using the shell's .CR exec internal command or from other than the initial shell. The current shell is terminated. .PP .C "Remuser too long" .IP The indicated string was too long for .CR login 's internal buffer. .PP .C "Terminal type too long" .IP The indicated string was too long for .CR login 's internal buffer. .PP .CI "Unable to change to directory " name .IP Cannot .CR chdir to the user's home directory. .PP .C "Your password has expired. Choose a new one" .IP Password aging is enabled and the user's password has expired. .SH WARNINGS If .CR /etc/group is linked to .CR /etc/logingroup , and group membership for the user trying to log in is managed by the Network Information Service (NIS), and no NIS server is able to respond, .CR login waits until a server does respond. .br .ne 3 .SH DEPENDENCIES .SS HP-UX Integrated Login Library .CR login can use the HP-UX Integrated Login Library, if it is configured. For further details, see .IR auth (5) and .IR auth.adm (1M). .PP The HP-UX Integrated Login typically uses the Distributed Computing Environment (DCE) for its user registry. The DCE user registry and its relationship to the HP-UX Integrated Login are described in .IR auth.dce (5). .SS HP Process Resource Manager If the optional HP Process Resource Manager (PRM) software is installed and configured, the login shell is launched in the user's initial process resource group. If the user's initial group is not defined, the shell runs in the user default group .RC ( PRMID=1 ). See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for a description of how the user's initial process resource group is determined. .SH AUTHOR .CR login was developed by AT&T and HP. .SH FILES .if n .TP 20 .if t .TP 30 .PD 0 .CR $HOME/.profile Personal profile (individual user initialization) .TP .CR $HOME/.rhosts Personal equivalence file for the remote login server .TP .CR /etc/d_passwd Dialup security encrypted passwords .TP .CR /etc/dialups Lines which require dialup security .TP .CR /etc/hosts.equiv System list of equivalent hosts allowing logins without passwords .TP .CR /etc/logingroup Group file \(em defines group access lists .TP .CR /etc/motd Message-of-the-day .TP .CR /etc/passwd Password file \(em defines users, passwords, and primary groups .TP .CR /etc/profile System profile (initialization for all users) .TP .CR /etc/securetty List of valid ttys for root login .TP .CR /etc/utmp Users currently logged in .TP .CR /tcb/files/auth/*/* The trusted system password database .TP .CR /var/adm/btmp History of bad login attempts .TP .CR /var/adm/wtmp History of logins, logouts, and date changes .TP .CI /var/mail/ login_name Mailbox for user .IR login_name .PD .SH VARIABLES .if n .TP 20 .if t .TP 30 .PD 0 .CR HOME User's home directory. .TP .CR MAIL Where to look for mail. .TP .CR PATH Path to be searched for commands. .TP .CR SHELL Which command interpreter is being used. .TP .CR TERM User's terminal type. .TP .IR varname User-specified named variables. .TP .CI L n User-specified unnamed variables. .PD .SH SEE ALSO csh(1), groups(1), ksh(1), last(1), mail(1), newgrp(1), passwd(1), sh(1), sh-bourne(1), sh-posix(1), su(1), getty(1M), initgroups(3C), dialups(4), group(4), passwd(4), profile(4), utmp(4), environ(5). .PP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide" . .PP HP-UX Integrated Login Library: auth.adm(1M), auth(5), auth.dce(5). .\" .\" toc@\f3login(1)\f1:\0\0\f4login\f1@@@sign on; start terminal session .\" .\" index@\f1log in to system@@@\f3login(1)\f1 .\" index@\f1login directory@@@\f3login(1)\f1 .\" index@\f1login name@@@\f3login(1)\f1 .\" index@\f1mail file@@@\f3login(1)\f1 .\" index@\f1PRM@@@\f2see \f1Process Resource Manager .\" index@\f1Process Resource Manager@@@\f3login(1)\f1 .\" index@\f1session, start terminal@@@\f3login(1)\f1 .\" index@\f1sign on@@@\f3login(1)\f1 .\" index@\f1start terminal session@@@\f3login(1)\f1 .\" index@\f1system, log in to@@@\f3login(1)\f1 .\" index@\f1terminal session, start@@@\f3login(1)\f1 .\" index@\f4btmp\f1 file@@@\f3login(1)\f1 .\" index@\f4dialups\f1 file@@@\f3login(1)\f1 .\" index@\f4group\f1 file@@@\f3login(1)\f1 .\" index@\f4HOME\f1 environment variable@@@\f3login(1)\f1 .\" index@\f4hosts.equiv\f1 file@@@\f3login(1)\f1 .\" index@\f4logingroup\f1 file@@@\f3login(1)\f1 .\" index@\f4login\f1 \- sign on; start terminal session@@@\f3login(1)\f1 .\" index@\f4LOGNAME\f1 environment variable@@@\f3login(1)\f1 .\" index@\f4MAIL\f1 environment variable@@@\f3login(1)\f1 .\" index@\f4motd\f1 file@@@\f3login(1)\f1 .\" index@\f4passwd\f1 file@@@\f3login(1)\f1 .\" index@\f4PATH\f1 environment variable@@@\f3login(1)\f1 .\" index@\f4profile\f1 file@@@\f3login(1)\f1 .\" index@\f4securetty\f1 file@@@\f3login(1)\f1 .\" index@\f4SHELL\f1 environment variable@@@\f3login(1)\f1 .\" index@\f4utmp\f1 file@@@\f3login(1)\f1 .\" index@\f4wtmp\f1 file@@@\f3login(1)\f1 .\" index@\f4\&.profile\f1 file@@@\f3login(1)\f1 .\" index@\f4\&.rhosts\f1 file@@@\f3login(1)\f1 .\" $Header: logname.1,v 76.1 95/08/03 18:13:25 ssa Exp $ .TA l .TH logname 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME logname \- get login name .SH SYNOPSIS .C logname .SH DESCRIPTION .C logname writes the user's login name to standard output. The login name is equivalent to that returned by .C getlogin() (see .IR getlogin (2)). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the language in which diagnostic messages are displayed. .SH FILES .C /etc/profile .SH SEE ALSO env(1), login(1), getlogin(3C), logname(3C), environ(5). .SH STANDARDS CONFORMANCE .CR logname ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" .\" index@\f4logname\f1 \- get login name@@@\f3logname(1)\f1 .\" index@get login name@@@\f3logname(1)\f1 .\" index@login name, get@@@\f3logname(1)\f1 .\" index@name, get login@@@\f3logname(1)\f1 .\" .\" toc@\f3logname(1)\f1:\0\0\f4logname\f1@@@get login name .\" .\" fileset_database@logname.1 USER-CMDS-MAN .\" $Header: lorder.1,v 72.5 94/11/14 15:19:50 ssa Exp $ .TA l .TH lorder 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lorder \- find ordering relation for an object library .SH SYNOPSIS .C lorder .RI [ \|files\| ] .SH DESCRIPTION The input consists of one or more object or archive library .I files (see .IR ar (1)) placed on the command line or read from standard input. The standard output is a list of pairs of object file names, meaning that the first file of the pair refers to external identifiers defined in the second. Output can be processed by .C tsort to find an ordering of a library suitable for one-pass access by .C ld (see .IR tsort (1) and .IR ld (1)). Note that the link editor .C ld is capable of multiple passes over an archive in the archive format and does not require that .C lorder be used when building an archive. Using the .C lorder command may, however, allow for a slightly more efficient access of the archive during the link edit process. .PP The symbol table maintained by .C ar allows .C ld to randomly access symbols and files in the archive, making the use of .C lorder unnecessary when building archive libraries (see .IR ar(1)). .SH EXTERNAL INFLUENCES .SS Environment Variables .PP The following internationalization variables affect the execution of .CR lorder : .PP .C LANG .RS Determines the locale category for native language, local customs and coded character set in the absence of .C LC_ALL and other .C LC_* environment variables. If .C LANG is not specified or is set to the empty string, a default of .C C (see .IR lang (5)) is used instead of .CR LANG . .RE .PP .C LC_ALL .RS Determines the values for all locale categories and has precedence over .C LANG and other .C LC_* environment variables. .RE .PP .C LC_COLLATE .RS Determines the locale category for character collation. .RE .PP .C LC_CTYPE .RS Determines the locale category for character handling functions. .RE .PP .C LC_MESSAGES .RS Determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error. .RE .PP .C LC_NUMERIC .RS Determines the locale category for numeric formatting. .RE .PP .C NLSPATH .RS Determines the location of message catalogues for the processing of .CR LC_MESSAGES . .RE .PP If any internationalization variable contains an invalid setting, .C lorder behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES Build a new library from existing .C .o files: .IP .C "ar cr library `lorder *.o | tsort`" .PP When creating libraries with so many objects that the shell cannot properly handle the .C *.o expansion, the following technique may prove useful: .IP .C "ls | grep '.o$' | lorder | tsort | xargs ar cq library" .SH WARNINGS Object files whose names do not end with .C .o are overlooked, even when contained in library archives. Their global symbols and references are attributed to some other file. .SH FILES .TP 25 .C /var/tmp/*symref, temporary files .PD 0 .TP .C /var/tmp/*symdef .PD .SH SEE ALSO .PD .SS System Tools: .TP 18 .IR ar(1) create archived libraries .PD 0 .TP .IR ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 .IR tsort(1) produce an ordered list of items (topological sort) .PD .SH STANDARDS CONFORMANCE .CR lorder ": SVID2, SVID3, XPG2" .\" .\" toc@\f3lorder(1)\f1:\0\0\f4lorder\f1@@@find ordering relation for an object library .\" .\" index@\f4lorder\f1 \- find ordering relation for an object code library@@@\f3lorder(1)\f1 .\" index@find ordering relation for files in an object code library@@@\f3lorder(1)\f1 .\" index@files, object code: find ordering relation for files in an object code library@@@\f3lorder(1)\f1 .\" index@files, object code: optimum sequence for object code files in a library, find@@@\f3lorder(1)\f1 .\" index@ordering relation for files in an object code library, find@@@\f3lorder(1)\f1 .\" index@link editor, find correct ordering of object code files for single pass@@@\f3lorder(1)\f1 .\" index@optimum sequence for object code files in a library, find@@@\f3lorder(1)\f1 .\" index@sequence for object code files in a library, find optimum@@@\f3lorder(1)\f1 .\" index@object code files in a library, find optimum sequence for@@@\f3lorder(1)\f1 .\" index@code files, object, in a library, find optimum sequence for@@@\f3lorder(1)\f1 .\" .\" fileset_database@lorder.1 USER-CMDS-MAN .\" $Header: lp.1,v 76.1 95/08/23 17:55:12 ssa Exp $ .TA l .TH lp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lp, lpalt, cancel \- print/alter/cancel requests on an LP printer or plotter .SH SYNOPSIS .CR lp .RC \|[ -c ]\| .RC \|[ -d \f2dest\fP]\| .RC \|[ -m ]\| .RC \|[ -n \f2number\fP]\| .RC \|[ -o \f2option\fP]\| .RC \|[ -p \f2priority\fP]\| .RC \|[ -s ]\| .ifn .br \" force line break and indentation for nroff/man .ifn .CR "\0\0\0\0" \" makes a five-space intent .RC \|[ -t \f2title\fP]\| .RC \|[ -w ]\| .RI \|[ file \0...\&]\| .PP .CR lpalt .IR id .RC \|[ -d \f2dest\fP]\| .RC \|[ -i ]\| .RC \|[ -m ]\| .RC \|[ -n \f2number\fP]\| .RC \|[ -o \f2option\fP]\| .RC \|[ -p \f2priority\fP]\| .RC \|[ -s ]\| .ifn .br \" force line break and indentation for nroff/man .ifn .CR "\0\0\0\0" \" makes a five-space intent .RC \|[ -t \f2title\fP]\| .RC \|[ -w ]\| .PP .CR cancel .RI \|[ id \0...\&]\| .RI \|[ printer \0...\&]\| .RC \|[ -a ]\| .RC \|[ -e ]\| .RC \|[ -i ]\| .RC \|[ -u \f2user\fP]\| .SH DESCRIPTION The .CR lp command queues files for printing. The .CR lpalt command changes information in a queued request. The .CR cancel command deletes a queued request. .SS lp Command The .CR lp command arranges for the named files, .IR file \ ..., and associated information (collectively called a .IR request ) to be queued for output to a printer or plotter in the LP (line printer) subsystem. The process is called printing, regardless of the actual output device. .PP .CR lp associates a unique identifier with each request and writes it to standard output, using the message: .IP .CI "request id is\0" \&dest - sequence .CI ( fileinfo ) .PP The request .SM ID is .IC dest - sequence \f1, which can be used later to alter, cancel, or find the status of the request (see .CR lpalt and .CR cancel below, and .IR lpstat (1)). .PP For example, in the following message, .IP .CR "request id is pr47lf8e-2410 (1 file)" .PP the request .SM ID is .CR pr47lf8e-2410 . .SS lp Options and Arguments .CR lp recognizes the following options and arguments. The keyletter options can be specified in any order. The .IR file \0...\& names must be last. Blanks are not permitted between a keyletter and its argument. .TP 15 .IR file \0...\& Print each named file. If no file names are specified, standard input is assumed. The hyphen symbol .RC ( - ) also specifies standard input and can be intermixed on the command line with file names. Files are printed in the same order in which they are specified. .TP .CR -c Copy the named files to LP subsystem spooling directories. .IP Normally, the files are linked into a spool directory. The ownership and mode of the linked files remain unchanged. If the .CR -c option is given, or linking is not possible (perhaps because the printer is not physically attached to the local system or cluster), the files are copied into the spool directories. The ownership and mode of the copies are set to allow read access to owner .CR lp and group .CR bin only. .IP If the files are linked rather than copied, any changes made to the named files after the request is made but before it is printed will be reflected in the printed output. Standard input is always copied instead of linked. .TP 15 .CI -d dest Select .IR dest as the printer or class of printers that is to do the printing. If .IR dest is a printer, the request will be printed only on that specific printer. If .IR dest is a class, the request will be printed on the first available printer that is a member of the class. Under certain conditions (printer unavailability, file space limitation, etc.), requests for a specific .IR dest might not be accepted (see .IR accept (1M) and .IR lpadmin (1M)). .IP If the .CR -d option is omitted, .IR dest is taken from the environment variable .CR LPDEST . If that variable is unset or empty, the default queue is used, if one has been defined. If there is no default queue, or .CR LPDEST is set but invalid, .CR lp issues an error message and the request is not queued. Printer and class names and the default queue are defined by your LP subsystem administrator (see .IR lpadmin (1M) and .IR lpstat (1)). .TP .CR -m Send a mail message (see .IR mail (1)). to the user after the request has been printed. By default, no mail is sent upon normal completion of the print request. .TP .CI -n number Print .IR number copies of the output. The default is 1. .TP .CI -o option Specify a printer-dependent .IR option . You can specify several printer options by repeating the .CR -o option. For information about the options that are available for a printer supported on your system, see the interface script for the printer name in the .CR /etc/lp/interface directory. .TP .CI -p priority Set the priority of the print request. .IR priority must be in the range 0 (lowest priority) to 7 (highest priority). The priority is used to select the next spooled file for the targeted printer or class of printers. If the priority is less than the .IR fence , the minimum priority set for the printer, the print request is deferred until the fence is lowered or the priority is raised. The default for a printer queue is the default priority set by the .CR lpadmin or .CR lpfence command (see .IR lpadmin (1M) and .IR lpsched (1M)). The default for a class queue is the highest default priority among printers in the class. .TP .CR -s Suppress standard output messages from .CR lp such as "\c .CR "request\0id\0is\0" ...\&\c ". Error messages are still displayed on standard error. .TP .CI -t title Print .IR title on the banner page of the output. .TP .CR -w Write a message to the user's terminal after the request has been printed. If the user is not logged in or (for remote printing) if .CR rlpdaemon (see .IR rlpdaemon (1M)) is not running on the user's local system, mail will be sent instead. .SS lpalt Command The .CR lpalt command alters a request made by a previous .CR lp command, if it is not currently printing. (To requeue a currently printing request, use the .CR disable command (see .IR enable (1)) to stop the printer.) .SS lpalt Options .CR lpalt recognizes the following options and arguments, which can be specified in any order. Blanks are not permitted between a keyletter and its argument. .TP 15 .IR id Specifies the request to be altered. .IR id is a request .SM ID returned by .CR lp or .CR lpalt . .TP .CI -d dest Requeue the request to the named printer or class .IR dest . A new unique request .SM ID is written to standard output. .TP .CR -i Alter only local requests. .TP .CR -m Send mail upon normal completion of the print request. .TP .CI -n number Change the number of copies to .IR number . .TP .CI -o option Specify a printer-dependent .IR option . You can specify several printer options by repeating the .CR -o option. All .CR -o options from previous .CR lp and .CR lpalt commands for this request .SM ID are deleted. .TP .CI -p priority Change the request's priority to .IR priority . .TP .CR -s Suppress standard output messages from .CR lpalt such as "\c .CR "request\0id\0is\0" ...\&\c ". Error messages are still displayed on standard error. .TP .CI -t title Change the .IR title on the banner page of the output. .TP .CR -w Write a message to the user's terminal after the request has been printed. If the user is not logged in or (for remote printing) if .CR rlpdaemon (see .IR rlpdaemon (1M)). is not running on the user's local system, mail will be sent instead. .SS cancel Command The .CR cancel command cancels requests that were made with the .CR lp command, even if they are currently printing. At least one .IR id or .IR printer must be specified. .PP The cancellation of a request that is currently printing frees the printer to print its next available request. .SS cancel Options and Arguments .CR cancel recognizes the following options and arguments, which can be specified in any order. Blanks are not permitted between a keyletter and its argument. .TP 15 .IR id \0...\& Specifies one or more requests. .IR id is a request .SM ID returned by .CR lp or .CR lpalt . .TP .IR printer \0...\& Specifies one or more printers. .IR printer is the name of a printer, not a class. Either cancel the request that is currently printing on each .IR printer , or, if an .CR -a , .CR -e , or .CR -u option is specified, specify the printer on which to perform the corresponding operation. .TP .CR -a Remove all requests the user owns on each .IR printer . The owner is determined by the user's login name and the host name of the machine where the .CR lp command was invoked. .TP .CR -e Empty the spool queue of all requests for each .IR printer . Only users with appropriate privileges can use this option. .TP .CR -i Cancel only local requests. .TP .CI -u user Remove any requests belonging to .IR user . You can repeat the .CR -u option to specify more users. Only users with appropriate privileges can use this option. .SS Printing Overview .PP A printer can print requests from one or two destination queues: its own private queue and an optional class queue, which can serve one or more printers. The destination queues are set up with the .CR lpadmin command. The .CR lp command places a printing request into a printer or class destination queue as directed by a user. The .CR lpsched scheduler directs the requests from the destination queues to the printers. The .CR accept and .CR reject commands control whether .CR lp can place requests in the destination queues. The .CR enable and .CR disable commands control whether .CR lpsched can send a queued request to a printer. If a printer has two queues and one queue is rejecting requests, users can still direct requests to the other destination queue and have the requests printed. .CR lpstat reports the current status of the destination queues and the scheduler. See .IR enable (1), .IR lpstat (1), .IR accept (1M), and .IR lpadmin (1M). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not set or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .C LC_ALL determines the locale to use to override any values for locale categories specified by the setting of .C LANG or any environment variables beginning with .CR LC_ . .PP .CR LC_CTYPE determines the locale for interpretation of sequences of bytes of text data as characters (e.g., single- verses multibyte characters in arguments and input files). .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP .C LPDEST determines the output device or destination. If the .C LPDEST environment variable is not set, the .C PRINTER environment variable is used. The .CI -d " dest" option takes precedence over .CR LPDEST . Results are undefined when .C -d is not specified and .C LPDEST contains a value that is not a valid device or destination name. .PP .C PRINTER determines the output device or destination. If the .C LPDEST and .C PRINTER environment variables are not set, an unspecified output device is used. The .CI -d " dest" option and the .C LPDEST environment variable takes precedence over .CR PRINTER . Results are undefined when .C -d is not specified, .C LPDEST is unset, and .C PRINTER contains a value that is not a valid device or destination name. .PP If any internationalization variable contains an invalid setting, the commands behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH RETURN VALUE Exit values are: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR >0 Error condition occurred. .RE .PD .SH EXAMPLES For a HP2934A printer named .CR lp2 , configured with an interface script that defines the .CR -c option to cause the printer to print in a compressed mode, use the following command to print .CR myfile with compressed print on .CR lp2 : .IP .CI "lp -dlp2 -oc myfile" .PP .CR lp can be used at the end of a pipeline to print the results of a previous command. It is commonly used with the .CR pr command (see .IR pr (1)) to print formatted output. For a default printer, to format file .CR .profile into pages and print three copies of it: .IP .C "pr .profile | lp -n3" .SH WARNINGS A remote print request can be altered or cancelled only by the user who requested it, and only from the system from which the the original .CR lp command was issued. .PP If the restrict cancel feature (see .IR lpadmin (1M)) is enabled for the specified printer, a user can only alter or cancel requests owned by the user. .PP For a remote system, .CR lpalt cannot change .IR dest and .IR priority . .SH FILES .TP 35 .PD 0 .CR /etc/lp Directory of spooler configuration data .TP .CR /etc/lp/interface Directory of active LP device interface scripts .TP .CR /usr/lib/lp Directory of model and font file directories .TP .CR /var/adm/lp Directory of spooler log files .TP .CR /var/spool/lp Directory of LP spooling files and directories .PD .SH SEE ALSO enable(1), lpstat(1), mail(1), slp(1), accept(1M), lpadmin(1M), lpana(1M), lpsched(1M), mklp(1M), rcancel(1M), rlp(1M), rlpdaemon(1M), rlpstat(1M). .SH STANDARDS CONFORMANCE .CR lp ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR cancel ": SVID2, SVID3, XPG4" .\" .\" index@\f4lp\f1 \- print requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f4cancel\f1 \- cancel requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f4lpalt\f1 \- alter requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f1print requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f1cancel requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f1requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f1LP printer, print/alter/cancel requests@@@\f3lp(1)\f1 .\" index@\f1printer, LP, print/alter/cancel requests@@@\f3lp(1)\f1 .\" index@\f1plotter@@@see \f2printer\f1 .\" index@\f1line printer@@@see \f2printer\f1 .\" index@\f1spooling@@@see \f2printer\f1 .\" .\" toc@\f3lp(1)\f1:\0\0\f4cancel\f1, \f4lp\f1, \f4lpalt\f1@@@print/alter/cancel requests on an LP printer or plotter .\" toc@\f4cancel\f1:\0\0cancel requests on an LP printer or plotter@@@see \f3lp(1)\f1 .\" toc@\f4lpalt\f1:\0\0alter requests on an LP printer or plotter@@@see \f3lp(1)\f1 .\" .\" links@lp.1 cancel.1 .\" links@lp.1 lpalt.1 .\" $Header: lp.1,v 76.1 95/08/23 17:55:12 ssa Exp $ .TA l .TH lp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lp, lpalt, cancel \- print/alter/cancel requests on an LP printer or plotter .SH SYNOPSIS .CR lp .RC \|[ -c ]\| .RC \|[ -d \f2dest\fP]\| .RC \|[ -m ]\| .RC \|[ -n \f2number\fP]\| .RC \|[ -o \f2option\fP]\| .RC \|[ -p \f2priority\fP]\| .RC \|[ -s ]\| .ifn .br \" force line break and indentation for nroff/man .ifn .CR "\0\0\0\0" \" makes a five-space intent .RC \|[ -t \f2title\fP]\| .RC \|[ -w ]\| .RI \|[ file \0...\&]\| .PP .CR lpalt .IR id .RC \|[ -d \f2dest\fP]\| .RC \|[ -i ]\| .RC \|[ -m ]\| .RC \|[ -n \f2number\fP]\| .RC \|[ -o \f2option\fP]\| .RC \|[ -p \f2priority\fP]\| .RC \|[ -s ]\| .ifn .br \" force line break and indentation for nroff/man .ifn .CR "\0\0\0\0" \" makes a five-space intent .RC \|[ -t \f2title\fP]\| .RC \|[ -w ]\| .PP .CR cancel .RI \|[ id \0...\&]\| .RI \|[ printer \0...\&]\| .RC \|[ -a ]\| .RC \|[ -e ]\| .RC \|[ -i ]\| .RC \|[ -u \f2user\fP]\| .SH DESCRIPTION The .CR lp command queues files for printing. The .CR lpalt command changes information in a queued request. The .CR cancel command deletes a queued request. .SS lp Command The .CR lp command arranges for the named files, .IR file \ ..., and associated information (collectively called a .IR request ) to be queued for output to a printer or plotter in the LP (line printer) subsystem. The process is called printing, regardless of the actual output device. .PP .CR lp associates a unique identifier with each request and writes it to standard output, using the message: .IP .CI "request id is\0" \&dest - sequence .CI ( fileinfo ) .PP The request .SM ID is .IC dest - sequence \f1, which can be used later to alter, cancel, or find the status of the request (see .CR lpalt and .CR cancel below, and .IR lpstat (1)). .PP For example, in the following message, .IP .CR "request id is pr47lf8e-2410 (1 file)" .PP the request .SM ID is .CR pr47lf8e-2410 . .SS lp Options and Arguments .CR lp recognizes the following options and arguments. The keyletter options can be specified in any order. The .IR file \0...\& names must be last. Blanks are not permitted between a keyletter and its argument. .TP 15 .IR file \0...\& Print each named file. If no file names are specified, standard input is assumed. The hyphen symbol .RC ( - ) also specifies standard input and can be intermixed on the command line with file names. Files are printed in the same order in which they are specified. .TP .CR -c Copy the named files to LP subsystem spooling directories. .IP Normally, the files are linked into a spool directory. The ownership and mode of the linked files remain unchanged. If the .CR -c option is given, or linking is not possible (perhaps because the printer is not physically attached to the local system or cluster), the files are copied into the spool directories. The ownership and mode of the copies are set to allow read access to owner .CR lp and group .CR bin only. .IP If the files are linked rather than copied, any changes made to the named files after the request is made but before it is printed will be reflected in the printed output. Standard input is always copied instead of linked. .TP 15 .CI -d dest Select .IR dest as the printer or class of printers that is to do the printing. If .IR dest is a printer, the request will be printed only on that specific printer. If .IR dest is a class, the request will be printed on the first available printer that is a member of the class. Under certain conditions (printer unavailability, file space limitation, etc.), requests for a specific .IR dest might not be accepted (see .IR accept (1M) and .IR lpadmin (1M)). .IP If the .CR -d option is omitted, .IR dest is taken from the environment variable .CR LPDEST . If that variable is unset or empty, the default queue is used, if one has been defined. If there is no default queue, or .CR LPDEST is set but invalid, .CR lp issues an error message and the request is not queued. Printer and class names and the default queue are defined by your LP subsystem administrator (see .IR lpadmin (1M) and .IR lpstat (1)). .TP .CR -m Send a mail message (see .IR mail (1)). to the user after the request has been printed. By default, no mail is sent upon normal completion of the print request. .TP .CI -n number Print .IR number copies of the output. The default is 1. .TP .CI -o option Specify a printer-dependent .IR option . You can specify several printer options by repeating the .CR -o option. For information about the options that are available for a printer supported on your system, see the interface script for the printer name in the .CR /etc/lp/interface directory. .TP .CI -p priority Set the priority of the print request. .IR priority must be in the range 0 (lowest priority) to 7 (highest priority). The priority is used to select the next spooled file for the targeted printer or class of printers. If the priority is less than the .IR fence , the minimum priority set for the printer, the print request is deferred until the fence is lowered or the priority is raised. The default for a printer queue is the default priority set by the .CR lpadmin or .CR lpfence command (see .IR lpadmin (1M) and .IR lpsched (1M)). The default for a class queue is the highest default priority among printers in the class. .TP .CR -s Suppress standard output messages from .CR lp such as "\c .CR "request\0id\0is\0" ...\&\c ". Error messages are still displayed on standard error. .TP .CI -t title Print .IR title on the banner page of the output. .TP .CR -w Write a message to the user's terminal after the request has been printed. If the user is not logged in or (for remote printing) if .CR rlpdaemon (see .IR rlpdaemon (1M)) is not running on the user's local system, mail will be sent instead. .SS lpalt Command The .CR lpalt command alters a request made by a previous .CR lp command, if it is not currently printing. (To requeue a currently printing request, use the .CR disable command (see .IR enable (1)) to stop the printer.) .SS lpalt Options .CR lpalt recognizes the following options and arguments, which can be specified in any order. Blanks are not permitted between a keyletter and its argument. .TP 15 .IR id Specifies the request to be altered. .IR id is a request .SM ID returned by .CR lp or .CR lpalt . .TP .CI -d dest Requeue the request to the named printer or class .IR dest . A new unique request .SM ID is written to standard output. .TP .CR -i Alter only local requests. .TP .CR -m Send mail upon normal completion of the print request. .TP .CI -n number Change the number of copies to .IR number . .TP .CI -o option Specify a printer-dependent .IR option . You can specify several printer options by repeating the .CR -o option. All .CR -o options from previous .CR lp and .CR lpalt commands for this request .SM ID are deleted. .TP .CI -p priority Change the request's priority to .IR priority . .TP .CR -s Suppress standard output messages from .CR lpalt such as "\c .CR "request\0id\0is\0" ...\&\c ". Error messages are still displayed on standard error. .TP .CI -t title Change the .IR title on the banner page of the output. .TP .CR -w Write a message to the user's terminal after the request has been printed. If the user is not logged in or (for remote printing) if .CR rlpdaemon (see .IR rlpdaemon (1M)). is not running on the user's local system, mail will be sent instead. .SS cancel Command The .CR cancel command cancels requests that were made with the .CR lp command, even if they are currently printing. At least one .IR id or .IR printer must be specified. .PP The cancellation of a request that is currently printing frees the printer to print its next available request. .SS cancel Options and Arguments .CR cancel recognizes the following options and arguments, which can be specified in any order. Blanks are not permitted between a keyletter and its argument. .TP 15 .IR id \0...\& Specifies one or more requests. .IR id is a request .SM ID returned by .CR lp or .CR lpalt . .TP .IR printer \0...\& Specifies one or more printers. .IR printer is the name of a printer, not a class. Either cancel the request that is currently printing on each .IR printer , or, if an .CR -a , .CR -e , or .CR -u option is specified, specify the printer on which to perform the corresponding operation. .TP .CR -a Remove all requests the user owns on each .IR printer . The owner is determined by the user's login name and the host name of the machine where the .CR lp command was invoked. .TP .CR -e Empty the spool queue of all requests for each .IR printer . Only users with appropriate privileges can use this option. .TP .CR -i Cancel only local requests. .TP .CI -u user Remove any requests belonging to .IR user . You can repeat the .CR -u option to specify more users. Only users with appropriate privileges can use this option. .SS Printing Overview .PP A printer can print requests from one or two destination queues: its own private queue and an optional class queue, which can serve one or more printers. The destination queues are set up with the .CR lpadmin command. The .CR lp command places a printing request into a printer or class destination queue as directed by a user. The .CR lpsched scheduler directs the requests from the destination queues to the printers. The .CR accept and .CR reject commands control whether .CR lp can place requests in the destination queues. The .CR enable and .CR disable commands control whether .CR lpsched can send a queued request to a printer. If a printer has two queues and one queue is rejecting requests, users can still direct requests to the other destination queue and have the requests printed. .CR lpstat reports the current status of the destination queues and the scheduler. See .IR enable (1), .IR lpstat (1), .IR accept (1M), and .IR lpadmin (1M). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not set or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .C LC_ALL determines the locale to use to override any values for locale categories specified by the setting of .C LANG or any environment variables beginning with .CR LC_ . .PP .CR LC_CTYPE determines the locale for interpretation of sequences of bytes of text data as characters (e.g., single- verses multibyte characters in arguments and input files). .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP .C LPDEST determines the output device or destination. If the .C LPDEST environment variable is not set, the .C PRINTER environment variable is used. The .CI -d " dest" option takes precedence over .CR LPDEST . Results are undefined when .C -d is not specified and .C LPDEST contains a value that is not a valid device or destination name. .PP .C PRINTER determines the output device or destination. If the .C LPDEST and .C PRINTER environment variables are not set, an unspecified output device is used. The .CI -d " dest" option and the .C LPDEST environment variable takes precedence over .CR PRINTER . Results are undefined when .C -d is not specified, .C LPDEST is unset, and .C PRINTER contains a value that is not a valid device or destination name. .PP If any internationalization variable contains an invalid setting, the commands behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH RETURN VALUE Exit values are: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR >0 Error condition occurred. .RE .PD .SH EXAMPLES For a HP2934A printer named .CR lp2 , configured with an interface script that defines the .CR -c option to cause the printer to print in a compressed mode, use the following command to print .CR myfile with compressed print on .CR lp2 : .IP .CI "lp -dlp2 -oc myfile" .PP .CR lp can be used at the end of a pipeline to print the results of a previous command. It is commonly used with the .CR pr command (see .IR pr (1)) to print formatted output. For a default printer, to format file .CR .profile into pages and print three copies of it: .IP .C "pr .profile | lp -n3" .SH WARNINGS A remote print request can be altered or cancelled only by the user who requested it, and only from the system from which the the original .CR lp command was issued. .PP If the restrict cancel feature (see .IR lpadmin (1M)) is enabled for the specified printer, a user can only alter or cancel requests owned by the user. .PP For a remote system, .CR lpalt cannot change .IR dest and .IR priority . .SH FILES .TP 35 .PD 0 .CR /etc/lp Directory of spooler configuration data .TP .CR /etc/lp/interface Directory of active LP device interface scripts .TP .CR /usr/lib/lp Directory of model and font file directories .TP .CR /var/adm/lp Directory of spooler log files .TP .CR /var/spool/lp Directory of LP spooling files and directories .PD .SH SEE ALSO enable(1), lpstat(1), mail(1), slp(1), accept(1M), lpadmin(1M), lpana(1M), lpsched(1M), mklp(1M), rcancel(1M), rlp(1M), rlpdaemon(1M), rlpstat(1M). .SH STANDARDS CONFORMANCE .CR lp ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR cancel ": SVID2, SVID3, XPG4" .\" .\" index@\f4lp\f1 \- print requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f4cancel\f1 \- cancel requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f4lpalt\f1 \- alter requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f1print requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f1cancel requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f1requests on an LP printer@@@\f3lp(1)\f1 .\" index@\f1LP printer, print/alter/cancel requests@@@\f3lp(1)\f1 .\" index@\f1printer, LP, print/alter/cancel requests@@@\f3lp(1)\f1 .\" index@\f1plotter@@@see \f2printer\f1 .\" index@\f1line printer@@@see \f2printer\f1 .\" index@\f1spooling@@@see \f2printer\f1 .\" .\" toc@\f3lp(1)\f1:\0\0\f4cancel\f1, \f4lp\f1, \f4lpalt\f1@@@print/alter/cancel requests on an LP printer or plotter .\" toc@\f4cancel\f1:\0\0cancel requests on an LP printer or plotter@@@see \f3lp(1)\f1 .\" toc@\f4lpalt\f1:\0\0alter requests on an LP printer or plotter@@@see \f3lp(1)\f1 .\" .\" links@lp.1 cancel.1 .\" links@lp.1 lpalt.1 .\" $Header: lpfilter.1,v 72.4 94/07/05 17:17:26 ssa Exp $ .TA l .TH lpfilter 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lpfilter, divpage, fontdl, lprpp, plotdvr, printstat, reverse \- filters invoked by lp interface scripts .SH SYNOPSIS .C /usr/lbin/divpage .RC [ -p \(or .CR -l ] .RC [ -h \(or .CR -q ] .RC [ -n\c .IR FontID\| ] .I filename .PP .C /usr/lbin/fontdl .RC [ -n\c .IR FontID\| ] .RC [ -l ] .RC [ -p ] .I filename .PP .C /usr/lbin/lprpp .RC [ -i ] .RC [ -o ] .RC [ -e ] .RC [ -l\c .IR nn\| ] .RC [ -n ] .RC [ -p ] .PP .C /usr/lbin/plotdvr .CI -l \|request_id .CI -u \|username .RC [ -e ] .RC [ -f ] .RC [ -i ] .I filename .PP .C /usr/sbin/printstat .CI -l \|request_id .CI -u \|username .I filename .PP .C /usr/sbin/reverse .RC [ -l .IR page_length\| ] .SS Remarks The structure of these filters is currently under review. They may become obsolete or be restructured in a future release. .SH DESCRIPTION Various filters are used by the .C lp subsystem to obtain specialized behavior for specific types of devices or data. This entry describes currently supported filters. .PP A number of these filters use a specified .I username and .I filename to determine the location of the user who originated the print message. .PP The .I filename is used to determine the .I hostname of the system where the request originated, and must have the form .RI [ dirname ]\c .CI /d?A \|nnnhostname or .RI [ dirname ]\c .CI /dA \|nnnnhostname\f1, where .I dirname is not a path name, but only the name of the basename's parent directory. .I filename meets this requirement when it is set to .C $6 in the interface script for the printer. .SS divpage Provides capabilities for printing multiple pages per sheet and selection of built-in fonts. .PP .C Options: .RS .TP 15 .C -p Set mode to portrait (default). .TP .C -l Set mode to landscape. .TP .C -h Print half pages (default). .TP .C -q Print quarter pages. .TP .CI -n \|FontID Use font number .IR FontID . Default is 0. Causes the string .CI \s-2\uE\dC\s0( \|Font\s-1ID\s0 X to be sent to the printer. .RE .SS fontdl .I fontdl downloads the font contained in .I filename to a printer connected to standard output. .PP .C Options: .RS .TP 15 .CI -n \|FontID Specifies the ID number by which the font will be referenced. Default is 0. .TP .C -l Specify landscape mode. Default is portrait. .TP .C -p Specifies proportional spacing. Default is fixed. .RE .SS lprpp This is a filter that converts backspace overstrike to line overprint with horizontal print positioning to enhance bold print. This functionality is required on printers such as the LaserJet, which cannot produce bold print by overstriking. .PP .C Options: .RS .TP 15 .C -i Converts to _ to italicize ANYCHAR. Also properly italicizes overstruck (bold) characters. Does .I not work correctly for "hashed-overstrike" such as: .br \0 .br \0\0\0\0\0\0_ .TP .C -o Prints only the odd numbered pages. Used with .C -e for double-sided printing. .TP .C -e Print only the even numbered pages. Used with .C -o for double sided printing. .TP .CI -l \|nn Specifies the page length, in lines. Default is 60 unless .I -n or .I -p is selected, in which case it is 66. .TP .C -n Specifies nroff mode for printing output of the .I nroff command. Prints 66 lines per page with the first line appearing on logical line 4 of the printer. .TP .C -p Specifies pr mode for printing output from the .I pr command. Prints 66 lines per page with the first line appearing on logical line 3 of the printer. .SS plotdvr HP-GL plotter filter. This filter scans the data for "PG" commands (paper feed). When this data is encountered, the filter strips it from the data stream and informs the requesting user of the need to change paper in the plotter. .PP Options: .RS .TP 15 .CI -l \|request_id Specifies the printer request ID and is used in various messages regarding the plot request. .TP .CI -u \|username The requesting user's login name, used to communicate with the user regarding the request. .TP .C -e Specifies the use of escape sequences, rather than HP-GL commands, to determine plotter status. .TP .C -f Plot without stopping for paper changes. The "PG" commands are not stripped from the data stream and the user is not notified of them. This option is used on plotters capable of automatic page feed. .TP .C -i Prevents initialization of the plotter. .RE .SS printstat Interrogates an RS232 printer as to its status, and does not return until the printer is ready. If the printer is .IR off-line , .IR "out of paper" , or .IR disconnected , the submitter of the print request is notified of this condition periodically until it is corrected. When the printer is ready to print, the command exits. .PP Standard input and standard output must both be connected to the serial printer device. .PP This program uses the .I send-status command .C \s-2\uE\dC\s0?\s-2\uD\d1\s0? to determine status. Not all serial printers respond to this command. Only the following configurations support this command: .RS .PP .TS box; cB | cB l | l. Printer Comments _ LaserJet Not supported LaserJetII Supported LaserJetIID Requires \s-1HP\|26013A\s0 module LaserJetIIP Not supported LaserJetIII Requires \s-1HP\|26013A\s0 module LaserJet2000 Not supported .TE .RE .PP .C Options: .RS .TP 15 .CI -l \|request-id Print request ID used in various communications with the user. .TP .CI -u \|username The requesting user's login name, used to communicate with the user regarding the request. .RE .SS reverse Prints the data appearing on the standard input in reverse page order to the standard output. This command can handle up to 2000 pages. .PP .C Options: .RS .TP 15 .CI -l \|page_length Specifies the page length, in lines. Default is 66. .RE .SH DIAGNOSTICS Error and diagnostic messages appear on the printed output, on the user's terminal, or are mailed to the user, depending on circumstances. .SH WARNINGS There is little consistency in the interface to these filters. .SH SEE ALSO lp(1), lpadmin(1). .PP .IR "HP-UX System Administration Manual" . .\" .\" index@\f4lpfilter\f1 \- filters invoked by lp interface scripts@@@\f3lpfilter(1)\f1 .\" index@\f4divpage\f1 \- divide pages for two-sided printing@@@\f3lpfilter(1)\f1 .\" index@\f4fontdl\f1 \- download fonts to printer@@@\f3lpfilter(1)\f1 .\" index@\f4hp2686a\f1 \- laserjet filter@@@\f3lpfilter(1)\f1 .\" index@\f4hp2934a\f1 \- character printer filter@@@\f3lpfilter(1)\f1 .\" index@\f4lprpp\f1 \- laserjet filter@@@\f3lpfilter(1)\f1 .\" index@\f4plotdvr\f1 \- plotter driver for lp@@@\f3lpfilter(1)\f1 .\" index@\f4printstat\f1 \- check status of serial printer@@@\f3lpfilter(1)\f1 .\" index@\f4reverse\f1 \- reverse printer pages for collating@@@\f3lpfilter(1)\f1 .\" .\" toc@\f3lpfilter(1)\f1:\0\0\f4lpfilter\f1@@@filters used by the lp interface scripts .\" .\" links@lpfilter.1 divpage.1 .\" links@lpfilter.1 fontdl.1 .\" links@lpfilter.1 lprpp.1 .\" links@lpfilter.1 plotdvr.1 .\" links@lpfilter.1 printstat.1 .\" links@lpfilter.1 reverse.1 .\" $Header: lpfilter.1,v 72.4 94/07/05 17:17:26 ssa Exp $ .TA l .TH lpfilter 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lpfilter, divpage, fontdl, lprpp, plotdvr, printstat, reverse \- filters invoked by lp interface scripts .SH SYNOPSIS .C /usr/lbin/divpage .RC [ -p \(or .CR -l ] .RC [ -h \(or .CR -q ] .RC [ -n\c .IR FontID\| ] .I filename .PP .C /usr/lbin/fontdl .RC [ -n\c .IR FontID\| ] .RC [ -l ] .RC [ -p ] .I filename .PP .C /usr/lbin/lprpp .RC [ -i ] .RC [ -o ] .RC [ -e ] .RC [ -l\c .IR nn\| ] .RC [ -n ] .RC [ -p ] .PP .C /usr/lbin/plotdvr .CI -l \|request_id .CI -u \|username .RC [ -e ] .RC [ -f ] .RC [ -i ] .I filename .PP .C /usr/sbin/printstat .CI -l \|request_id .CI -u \|username .I filename .PP .C /usr/sbin/reverse .RC [ -l .IR page_length\| ] .SS Remarks The structure of these filters is currently under review. They may become obsolete or be restructured in a future release. .SH DESCRIPTION Various filters are used by the .C lp subsystem to obtain specialized behavior for specific types of devices or data. This entry describes currently supported filters. .PP A number of these filters use a specified .I username and .I filename to determine the location of the user who originated the print message. .PP The .I filename is used to determine the .I hostname of the system where the request originated, and must have the form .RI [ dirname ]\c .CI /d?A \|nnnhostname or .RI [ dirname ]\c .CI /dA \|nnnnhostname\f1, where .I dirname is not a path name, but only the name of the basename's parent directory. .I filename meets this requirement when it is set to .C $6 in the interface script for the printer. .SS divpage Provides capabilities for printing multiple pages per sheet and selection of built-in fonts. .PP .C Options: .RS .TP 15 .C -p Set mode to portrait (default). .TP .C -l Set mode to landscape. .TP .C -h Print half pages (default). .TP .C -q Print quarter pages. .TP .CI -n \|FontID Use font number .IR FontID . Default is 0. Causes the string .CI \s-2\uE\dC\s0( \|Font\s-1ID\s0 X to be sent to the printer. .RE .SS fontdl .I fontdl downloads the font contained in .I filename to a printer connected to standard output. .PP .C Options: .RS .TP 15 .CI -n \|FontID Specifies the ID number by which the font will be referenced. Default is 0. .TP .C -l Specify landscape mode. Default is portrait. .TP .C -p Specifies proportional spacing. Default is fixed. .RE .SS lprpp This is a filter that converts backspace overstrike to line overprint with horizontal print positioning to enhance bold print. This functionality is required on printers such as the LaserJet, which cannot produce bold print by overstriking. .PP .C Options: .RS .TP 15 .C -i Converts to _ to italicize ANYCHAR. Also properly italicizes overstruck (bold) characters. Does .I not work correctly for "hashed-overstrike" such as: .br \0 .br \0\0\0\0\0\0_ .TP .C -o Prints only the odd numbered pages. Used with .C -e for double-sided printing. .TP .C -e Print only the even numbered pages. Used with .C -o for double sided printing. .TP .CI -l \|nn Specifies the page length, in lines. Default is 60 unless .I -n or .I -p is selected, in which case it is 66. .TP .C -n Specifies nroff mode for printing output of the .I nroff command. Prints 66 lines per page with the first line appearing on logical line 4 of the printer. .TP .C -p Specifies pr mode for printing output from the .I pr command. Prints 66 lines per page with the first line appearing on logical line 3 of the printer. .SS plotdvr HP-GL plotter filter. This filter scans the data for "PG" commands (paper feed). When this data is encountered, the filter strips it from the data stream and informs the requesting user of the need to change paper in the plotter. .PP Options: .RS .TP 15 .CI -l \|request_id Specifies the printer request ID and is used in various messages regarding the plot request. .TP .CI -u \|username The requesting user's login name, used to communicate with the user regarding the request. .TP .C -e Specifies the use of escape sequences, rather than HP-GL commands, to determine plotter status. .TP .C -f Plot without stopping for paper changes. The "PG" commands are not stripped from the data stream and the user is not notified of them. This option is used on plotters capable of automatic page feed. .TP .C -i Prevents initialization of the plotter. .RE .SS printstat Interrogates an RS232 printer as to its status, and does not return until the printer is ready. If the printer is .IR off-line , .IR "out of paper" , or .IR disconnected , the submitter of the print request is notified of this condition periodically until it is corrected. When the printer is ready to print, the command exits. .PP Standard input and standard output must both be connected to the serial printer device. .PP This program uses the .I send-status command .C \s-2\uE\dC\s0?\s-2\uD\d1\s0? to determine status. Not all serial printers respond to this command. Only the following configurations support this command: .RS .PP .TS box; cB | cB l | l. Printer Comments _ LaserJet Not supported LaserJetII Supported LaserJetIID Requires \s-1HP\|26013A\s0 module LaserJetIIP Not supported LaserJetIII Requires \s-1HP\|26013A\s0 module LaserJet2000 Not supported .TE .RE .PP .C Options: .RS .TP 15 .CI -l \|request-id Print request ID used in various communications with the user. .TP .CI -u \|username The requesting user's login name, used to communicate with the user regarding the request. .RE .SS reverse Prints the data appearing on the standard input in reverse page order to the standard output. This command can handle up to 2000 pages. .PP .C Options: .RS .TP 15 .CI -l \|page_length Specifies the page length, in lines. Default is 66. .RE .SH DIAGNOSTICS Error and diagnostic messages appear on the printed output, on the user's terminal, or are mailed to the user, depending on circumstances. .SH WARNINGS There is little consistency in the interface to these filters. .SH SEE ALSO lp(1), lpadmin(1). .PP .IR "HP-UX System Administration Manual" . .\" .\" index@\f4lpfilter\f1 \- filters invoked by lp interface scripts@@@\f3lpfilter(1)\f1 .\" index@\f4divpage\f1 \- divide pages for two-sided printing@@@\f3lpfilter(1)\f1 .\" index@\f4fontdl\f1 \- download fonts to printer@@@\f3lpfilter(1)\f1 .\" index@\f4hp2686a\f1 \- laserjet filter@@@\f3lpfilter(1)\f1 .\" index@\f4hp2934a\f1 \- character printer filter@@@\f3lpfilter(1)\f1 .\" index@\f4lprpp\f1 \- laserjet filter@@@\f3lpfilter(1)\f1 .\" index@\f4plotdvr\f1 \- plotter driver for lp@@@\f3lpfilter(1)\f1 .\" index@\f4printstat\f1 \- check status of serial printer@@@\f3lpfilter(1)\f1 .\" index@\f4reverse\f1 \- reverse printer pages for collating@@@\f3lpfilter(1)\f1 .\" .\" toc@\f3lpfilter(1)\f1:\0\0\f4lpfilter\f1@@@filters used by the lp interface scripts .\" .\" links@lpfilter.1 divpage.1 .\" links@lpfilter.1 fontdl.1 .\" links@lpfilter.1 lprpp.1 .\" links@lpfilter.1 plotdvr.1 .\" links@lpfilter.1 printstat.1 .\" links@lpfilter.1 reverse.1 .\" $Header: lpstat.1,v 78.1 96/04/05 11:28:55 ssa Exp $ .TA l .TH lpstat 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lpstat \- report line printer status information .SH SYNOPSIS .C lpstat .RC [ -drst ] .RC [ -a\c .RI [ list ]] .RC [ -c\c .RI [ list ]] .RC [ -o\c .RI [ list ]] .RC [ -p\c .RI [ list ]] .RC [ -u\c .RI [ list ]] .RC [ -v\c .RI [ list ]] .RC [ ID ...] .SH DESCRIPTION The .CR lpstat utility writes to standard output information about the current status of the line printer system. .PP If no arguments are given, .CR lpstat writes the status of all requests made to .CR lp by the user that are still in the output queue. .SH OPTIONS The .CR lpstat utility supports the XBD specification, Section 10.2, Utility Syntax Guidelines, except the option-arguments are optional and cannot be presented as separate arguments. .PP Some of the options below can be followed by an optional list that can be in one of two forms: a list of items separated from one another by a comma, or a quoted list of items separated from one another by a comma or one or more blank characters, or combinations of both. See EXAMPLES. .PP The omission of a list following such options causes all information relevant to the option to be written to standard output; for example: .IP .C lpstat -o .PP writes the status of all output requests that are still in the output queue. .RS .TP 12 .CR -a [\|\f2list\fP\|] Write the acceptance status of destinations for output requests. The .IR list argument is a list of intermixed printer names and class names. .TP .CR -c [\|\f2list\fP\|] Write the class names and their members. The .IR list argument is a list of class names. .TP .C -d Write the system default destination for output requests. .TP .CR -o [\|\f2list\fP\|] Write the status of output requests. The .IR list argument is a list of intermixed printer names, class names and request IDs. .TP .CR -p [\|\f2list\fP\|] Write the status of printers. The .IR list argument is a list of printer names. .TP .CR -r Write the status of the line printer request scheduler. .TP .CR -s Write a status summary, including the status of the line printer scheduler, the system default destination, a list of class names and their members and a list of printers and their associated devices. .TP .CR -t Write all status information. .TP .CR -u [\|\f2list\fP\|] Write the status of output requests for users. The .IR list argument is a list of login names. .TP .CR -v [\|\f2list\fP\|] Write the names of printers and the pathnames of the devices associated with them. The list argument is a list of printer names. .SH OPERANDS The following operand is supported: .RS .TP 12 .C ID A request ID, as returned by .CR lp . .SH STDIN Not used. .SH INPUT FILES None. .SH ENVIRONMENT VARIABLES The following environment variables affect the execution of .CR lpstat : .RS .TP 25 .C LANG Provide a default value for the internationalisation variables that are unset or null. If .CR LANG is unset or null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined. .TP .C LC_ALL If set to a non-empty string value, override the values of all the other internationalisation variables. .TP .C LC_CTYPE Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments). .TP .C LC_MESSAGES Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error, and informative messages written to standard output. .TP .C LC_TIME Determine the format of date and time strings output when displaying line printer status information with the .CR -a , .CR -o , .CR -p , .CR -t , or .CR -u options. .TP .C NLSPATH Determine the location of message catalogues for the processing of .CR LC_MESSAGES. .TP .CR TZ Determine the timezone used with date and time strings. .SH ASYNCHRONOUS EVENTS Default. .SH STDOUT The standard output is a text file containing the information described in OPTIONS, in an unspecified format. .SH STDERR Used only for diagnostic messages. .SH OUTPUT FILES None. .SH EXTENDED DESCRIPTION None. .SH EXIT STATUS The following exit values are returned: .RS .TP .nf 0 Successful completion. .TP >0 An error occurred. .fi .SH CONSEQUENCES OF ERRORS Default. .SH APPLICATION USAGE The .CR lpstat utility cannot reliably determine the status of print requests in all conceivable circumstances. When the printer is under the control of another operating system or resides on a remote system across a network, it need not be possible to determine the status of the print job after it has left the control of the local operating system. Even on local printers, spooling hardware in the printer may make it appear that the print job has been completed long before the final page is printed. .SH EXAMPLES .RS .TP 1. Obtain the status of two printers, the pathnames of two printers, a list of all class names and the status of the request named HiPri-33: .IP lpstat -plaser1,laser4 -v"laser2 laser3" -c HiPri-33 .TP 2. Obtain user print job status using the obsolescent mixed blank and comma form: .IP lpstat -u"ddg,gmv, maw" .SH FUTURE DIRECTIONS A version of .CR lpstat that fully supports the XBD specification, Section 10.2, Utility Syntax Guidelines may be introduced in a future issue. .SH SEE ALSO cancel, lp. .SH CHANGE HISTORY First released in Issue 2. .SS Issue 3 The operation of this utility in an 8-bit transparent manner has been noted. .PP The operation of this utility in an internationalised environment has been described. .SS Issue 4 Format reorganised. .PP Exceptions to Utility Syntax Guidelines conformance noted. .PP Internationalised environment variable support mandated. .SH STANDARDS CONFORMANCE .CR lpstat ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" $Header: lpstat.1,v 78.1 96/04/05 11:28:55 ssa Exp $ .TA l .TH lpstat 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH DESCRIPTION Any arguments that are not .I options are assumed to be request .I ids (as returned by .CR lp ). .C lpstat prints the status of such requests. .I options can appear in any order and can be repeated and intermixed with other arguments. .RS .TP 12 .CR -i Inhibit the reporting of remote status. .TP .CR -o [\|\f2list\fP\|] Also see the .C -i option. .TP .C -t Print all status information. Same as specifying .CR -r , .CR -s , .CR -a , .CR -p , .CR -o . See the .C -i option. .RE .SS Security Restriction Only users who have the .C lp subsystem authorization or the .C printqueue secondary subsystem authorization can view the entire queue. Unauthorized users can view only their own jobs whose sensitivity levels are dominated by the user's current sensitivity level. .PP The .C allowmacaccess privilege allows viewing jobs at higher sensitivity levels. .SH EXAMPLES Check whether your job is queued: .IP .C lpstat .PP Check the relative position of a queued job: .IP .C lpstat -t .PP Verify that the job scheduler is running: .IP .C lpstat -r .SH FILES .nf .C /var/spool/lp/* .C /var/adm/lp/* .C /etc/lp/* .C /usr/lib/lp/* .fi .SH SEE ALSO enable(1), lp(1), rlpstat(1M). .SH STANDARDS CONFORMANCE .CR lpstat ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4lpstat\f1 \- print \s-1LP\s+1 request status information@@@\f3lpstat(1)\f1 .\" index@print \s-1LP\s+1 request status information@@@\f3lpstat(1)\f1 .\" index@\s-1LP\s+1 requests: print status information@@@\f3lpstat(1)\f1 .\" index@requests, \s-1LP\s+1@@@see \s-1LP\s+1 requests .\" index@status information, \s-1LP\s+1 request, print@@@\f3lpstat(1)\f1 .\" .\" toc@\f3lpstat(1)\f1:\0\0\f4lpstat\f1@@@print \s-1LP\s+1 status information .\" $Header: ls.1,v 76.2 95/08/23 17:56:11 ssa Exp $ .TA l .TH ls 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ls, l, ll, lsf, lsr, lsx \- list contents of directories .SH SYNOPSIS .CR ls .RC [ \-abcdefgilmnopqrstuxACFLR1 ] .RI [ names ] .PP .CR l .RI [ ls_options ] .RI [ names ] .br .CR ll .RI [ ls_options ] .RI [ names ] .br .CR lsf .RI [ ls_options ] .RI [ names ] .br .CR lsr .RI [ ls_options ] .RI [ names ] .br .CR lsx .RI [ ls_options ] .RI [ names ] .SH DESCRIPTION For each directory argument, the .CR ls command lists the contents of the directory. For each file argument, .CR ls repeats its name and any other information requested. The output is sorted in ascending collation order by default (see Environment Variables below). When no argument is given, the current directory is listed. When several arguments are given, the arguments are first sorted appropriately, but file arguments appear before directories and their contents. .PP If you are a user with appropriate privileges, all files except .CR . and .CR .. are listed by default. .PP There are three major listing formats. The format chosen depends on whether the output is going to a login device (determined by whether output device file is a .I tty device), and can also be controlled by option flags. The default format for a login device is to list the contents of directories in multicolumn format, with entries sorted vertically by column. (When individual file names (as opposed to directory names) appear in the argument list, those file names are always sorted across the page rather than down the page in columns because individual file names can be arbitrarily long.) If the standard output is not a login device, the default format is to list one entry per line. The .CR \-C and .CR \-x options enable multicolumn formats, and the .CR \-m option enables stream output format in which files are listed across the page, separated by commas. In order to determine output formats for the .CR \-C , .CR \-x , and .CR \-m options, .CR ls uses an environment variable, .CR COLUMNS , to determine the number of character positions available on each output line. If this variable is not set, the .I terminfo database is used to determine the number of columns, based on the environment variable .CR TERM . If this information cannot be obtained, 80 columns is assumed. .SS Options .CR ls recognizes the following options: .RS .TP 6 .CR \-a List all entries; usually entries whose names begin with a period .RC ( . ) are not listed. .TP .CR \-b Force printing of nongraphic characters to be in the octal .CI \e ddd notation. .TP .CR \-c Use time of last modification of the inode (file created, mode changed, etc.) for sorting .RC ( \-t ) or printing .RC ( \-l (ell)). .TP .CR \-d If an argument is a directory, list only its name (not its contents); often used with .CR \-l (ell) to get the status of a directory. .TP .CR \-e Print the extent attributes of the file. If any of the files has a extent attribute, this option prints the extent size, space reserved and allocation flags. This option must be used with the .CR \-l (ell) option. .TP .CR \-f Force each argument to be interpreted as a directory and list the name found in each slot. This option disables .CR \-l (ell), .CR \-t , .CR \-s , and .CR \-r , and enables .CR \-a ; the order is the order in which entries appear in the directory. .TP .CR \-g Same as .CR \-l , (ell) except that only the group is printed (owner is omitted). If both .CR \-l (ell) and .CR \-g are specified, the owner is not printed. .TP .CR \-i For each file, print the inode number in the first column of the report. When used in multicolumn output, the number precedes the file name in each column. .TP .CR \-l (ell) List in long format, giving mode, number of links, owner, group, size in bytes, and time of last modification for each file (see further DESCRIPTION and Access Control Lists below). If the time of last modification is greater than six months ago, or any time in the future, the year is substituted for the hour and minute of the modification time. If the file is a special file, the size field contains the major and minor device numbers rather than a size. .TP .CR \-m Stream output format. .TP .CR \-n The same as .CR \-l , (ell) except that the owner's UID and group's GID numbers are printed, rather than the associated character strings. .TP .CR \-o The same as .CR \-l , (ell) except that only the owner is printed (group is omitted). (If both .CR \-l (ell) and .CR \-o are specified, the group is not printed). .TP .CR \-p Put a slash .RC ( / ) after each file name if that file is a directory. .TP .CR \-q Force printing of nongraphic characters in file names as the character .RC ( ? ). .TP .CR \-r Reverse the order of sort to get reverse (descending) collation or oldest first, as appropriate. .TP .CR \-s Give size in blocks, including indirect blocks, for each entry. The first entry printed is the total number of blocks in the directory. When used in multicolumn output, the number of blocks precedes the file name in each column. .TP .CR \-t Sort by time modified (latest first) before sorting alphabetically. .TP .CR \-u Use time of last access instead of last modification for sorting .RC ( \-t option) or printing .RC ( \-l (ell) option). .TP .CR \-x Multicolumn output with entries sorted across rather than down the page. .TP .CR \-A The same as .CR \-a , except that the current directory "." and parent directory ".." are not listed. For a user with appropriate privileges, this flag defaults to ON, and is turned off by .CR \-A . .TP .CR \-C Multicolumn output with entries sorted down the columns. .TP .CR \-F Put a slash .RC ( / ) after each file name if that file is a directory or a symbolic link to a directory; put an asterisk .RC ( * ) after each file name if that file is executable; put an at sign (\f3@\f1) after each file name if that file is a symbolic link to a file; put a vertical bar .RC ( | ) after each file name if that file is a FIFO. .TP .CR \-L If the argument is a symbolic link, list the file or directory to which the link refers rather than the link itself. .TP .CR \-R Recursively list subdirectories encountered. .TP .CR \-1 (one) The file names will be listed in single column format regardless of the output device. This forces single column format to the user's terminal. .RE .PP Specifying more than one of the options in the following mutually exclusive pairs is not considered an error: .CR \-C and .CR \-l (ell), .CR \-m and .CR \-l (ell), .CR \-x and .CR \-l (ell), .CR \-C and .CR \-1 (one), .CR \-c and .CR \-u . .PP .CR ls is normally known by several shorthand-version names for the various formats: .RS .TP 6 .CR l equivalent to .CR "ls \-m" . .PD 0 .TP .CR ll equivalent to .CR "ls \-l" (ell). .TP .CR lsf equivalent to .CR "ls \-F" . .TP .CR lsr equivalent to .CR "ls \-R" . .TP .CR lsx equivalent to .CR "ls \-x" . .RE .PD .PP The shorthand notations are implemented as links to .CR ls . Option arguments to the shorthand versions behave exactly as if the long form above had been used with the additional arguments. .PP .B "Mode Bits Interpretation (\-l option)" .br The mode printed in listings produced by the .CR \-l (ell) option consists of 10 characters. The first character indicates the entry type: .RS .TP 6 .CR d Directory .PD 0 .TP .CR b Block special file .TP .CR c Character special file .TP .CR l Symbolic link .TP .CR p Fifo (also called a "named pipe") special file .TP .CR n Network special file .TP .CR s socket .TP .CR \- Ordinary file. .RE .PD .PP The next 9 characters are interpreted as three sets of three bits each which identify access permissions for owner, group, and others as follows: .IP .nf .if t \{ .sp -1v .cs R 19 __________________ \d0400 read by owner (\f3r\f1 or \f3\(mi\f1) | ________________ \d0200 write by owner (\f3w\f1 or \f3\(mi\f1) | | ______________ \d0100 execute (search directory) by owner\ (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | ____________ \d0040 read by group (\f3w\f1 or \f3\(mi\f1) | | | | __________ \d0020 write by group (\f3r\f1 or \f3\(mi\f1) | | | | | ________ \d0010 execute/search by group\ (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | | | | ______ \d0004 read by others (\f3r\f1 or \f3\(mi\f1) | | | | | | | ____ \d0002 write by others (\f3w\f1 or \f3\(mi\f1) | | | | | | | | __ \d0001 execute/search by others\ (\f3x\f1, \f3t\f1, \f3T\f1, or \f3\(mi\f1) | | | | | | | | | r w x r w x r w x .cs R .fi \} .if n \{ +------------------ 0400 read by owner (\f3r\f1 or \f3\(mi\f1) | +---------------- 0200 write by owner (\f3w\f1 or \f3\(mi\f1) | | +-------------- 0100 execute (search directory) by owner | | | (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | +------------ 0040 read by group (\f3r\f1 or \f3\(mi\f1) | | | | +---------- 0020 write by group (\f3w\f1 or \f3\(mi\f1) | | | | | +-------- 0010 execute/search by group | | | | | | (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | | | | +------ 0004 read by others (\f3r\f1 or \f3\(mi\f1) | | | | | | | +---- 0002 write by others (\f3w\f1 or \f3\(mi\f1) | | | | | | | | +-- 0001 execute/search by others | | | | | | | | | (\f3x\f1, \f3t\f1, \f3T\f1, or \f3\(mi\f1) | | | | | | | | | r w x r w x r w x .fi \} .PP Mode letters are interpreted as follows: .RS .TP 7 .CR \- Permission .I not granted in corresponding position. .TP .CR r Read permission granted to corresponding user class. .TP .CR w Write permission granted to corresponding user class. .TP .CR x Execute (or search in directory) permission granted to corresponding user class. .TP .CR s Execute (search) permission granted to corresponding user class. In addition, SUID (Set User ID) permission granted for owner, or SGID (Set Group ID) permission granted for group, as indicated by position. .TP .CR S Same as .CR s except that execute (search) permission is denied to corresponding user class. .TP .CR t (last position only) Execute (search) permission granted to others and "sticky bit" is set (see .IR chmod (2) .CR S_ISVTX description). .TP .CR T Same as .CR t except execute (search directory) permission denied to others. .RE .PP When an option is specified that results in a listing of directory and/or file sizes in bytes or blocks (such as the .CR \-s or .CR \-l (ell) option), a total count of blocks, including indirect blocks, is also printed at the beginning of the listing. .SS "Access Control Lists (ACLs)" If a file has optional ACL entries, the .CR \-l (ell) option displays a plus sign .RC ( + ) after the file's permissions. The permissions shown are a summary representation of the file's access control list, as returned by .CR stat() in the .I st_mode field (see .IR stat (2)). To list the contents of an access control list, use the .CR lsacl command (see .IR lsacl (1) and .IR acl (5)). .SH EXTERNAL INFLUENCES .SS Environment Variables If the .CR COLUMNS variable is set, .CR ls uses the width provided in determining positioning of columnar output. .PP .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not set or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .CR LC_COLLATE determines the order in which the output is sorted. .PP .CR LC_CTYPE determines which characters are classified as nongraphic for the .CR \-b and .CR \-q options, and the interpretation of single- and/or multibyte characters within file names. .PP .CR LC_TIME determines the date and time strings output by the .CR \-g , .CR \-l (ell), .CR \-n , and .CR \-o options. .PP .C LC_MESSAGES determines the language in which messages (other than the date and time strings) are displayed. .PP If any internationalization variable contains an invalid setting, .CR ls behaves as if all internationalization variables are set to "C" (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .br .ne 3v .SH RETURN VALUE .CR ls exits with one of the following values: .RS .TP 5 .CR \00 All input files were listed successfully. .TP .CR >0 .CR ls was aborted because errors occurred when accessing files. The following conditions cause an error: .RS 8 .TP 3 \(bu Specified file not found. .TP \(bu User has no permission to read the directory. .TP \(bu Process could not get enough memory. .TP \(bu Invalid option specified. .RE .RE .SH EXAMPLES Print a long listing of all the files in the current working directory (including the file sizes). List the most recently modified (youngest) file first, followed by the next older file, and so forth, to the oldest. Files whose names begin with a .CR . are also printed. .IP .C "ls \-alst" .SH WARNINGS Setting options based on whether the output is a login .RI ( tty ) device is undesirable because .CR "ls \-s" is very different from .CR "ls \-s | lp" . On the other hand, not using this setting makes old shell scripts that used .CR ls almost inevitably fail. .PP Unprintable characters in file names may confuse the columnar output options. .SH DEPENDENCIES .TP 5 NFS The .CR \-l (ell) option does not display a plus sign .RC ( + ) after the access permission bits of networked files to represent existence of optional access control list entries. .SH AUTHOR .CR ls was developed by AT&T, the University of California, Berkeley and HP. .SH FILES .TP 25 .CR /etc/passwd to get user IDs for .CR "ls \-l" (ell) and .CR "ls \-o" . .PD 0 .TP .CR /etc/group to get group IDs for .CR "ls \-l" (ell) and .CR "ls \-g" . .TP .CR /usr/share/lib/terminfo/?/* to get terminal information. .PD .SH SEE ALSO chmod(1), find(1), lsacl(1), stat(2), acl(5). .SH STANDARDS CONFORMANCE .CR ls ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4l\f1 \(mi list directory contents in stream output format@@@\f3ls(1)\f1 .\" index@\f4ls\f1 \(mi list directory contents@@@\f3ls(1)\f1 .\" index@\f4lsf\f1 \(mi list directory contents, showing subdirectories and executable files@@@\f3ls(1)\f1 .\" index@\f4ll\f1 \(mi list directory contents in long format@@@\f3ls(1)\f1 .\" index@\f4lsr\f1 \(mi recursively list directory contents and subtrees@@@\f3ls(1)\f1 .\" index@\f4lsx\f1 \(mi list directory contents, sort across page instead of down@@@\f3ls(1)\f1 .\" index@list contents of directory@@@\f3ls(1)\f1 .\" index@directory: list contents of directory@@@\f3ls(1)\f1 .\" index@contents of directory, list@@@\f3ls(1)\f1 .\" index@executable files in directory, list@@@\f3ls(1)\f1 .\" index@subdirectories in directory, list@@@\f3ls(1)\f1 .\" .\" toc@\f3ls(1)\f1:\0\0\f4ls\f1, \f4l\f1, \f4ll\f1, \f4lsf\f1, \f4lsr\f1, \f4lsx\f1@@@list contents of directories .\" toc@\f4l\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4ll\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsf\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsr\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsx\f1: list contents of directories@@@see \f3ls(1)\f1 .\" .\" links@ls.1 l.1 .\" links@ls.1 ll.1 .\" links@ls.1 lsf.1 .\" links@ls.1 lsr.1 .\" links@ls.1 lsx.1 .\" $Header: lsacl.1,v 72.4 94/04/27 14:05:51 ssa Exp $ .TA l .TH lsacl 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lsacl \- list access control lists (ACLs) of files .SH SYNOPSIS .C /usr/bin/lsacl .RC [ -l ] .I file ... .SH DESCRIPTION .C lsacl lists access control lists (\c .SM ACL\c s) of one or more files in symbolic, ``short'' form, one file's .SM ACL per line of output, followed by the file name; see .IR acl (5) for .SM ACL syntax. .SS Options .C lsacl recognizes the following option: .RS .TP 6 .C -l Print .SM ACL\c s in long form. Each file's .SM ACL can be more than one line long, and is always preceded by file name, colon, and newline. Consecutive file names are separated by blank lines. .RE .PP If a hyphen .RC ( - ) is given as a file name argument, .C lsacl prints the .SM ACL for the standard input. By default, it prints the file name as .CR - . For the .C -l option it prints a file name of .CR . .PP Unlike .CR ls , .C lsacl cannot list .SM ACL\c s of files in subdirectories automatically or list the .SM ACL entries of the files in the current directory by default. A good way to do the latter is: .IP .C lsacl * .PP or .IP .C lsacl .* * .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the language in which messages are displayed. .PP If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C lsacl behaves as if all internationalization variables are set to "C". See .IR environ (5). .SH RETURN VALUE If .C lsacl succeeds, it returns zero. If invoked incorrectly, it returns a value of .CR 1 . If .C lsacl is unable to read the .SM ACL for a specified file, it prints an error message to standard error, continues, and later returns a value of .CR 2 . .SH EXAMPLES List the .SM ACL for the file .CR dir/file1 : .IP .C lsacl dir/file1 .PP List .SM ACL\c s for all files in the current directory, in long form. .IP .C lsacl -l .* * .PP List .SM ACL\c s for all files under .CR mydir : .IP .C "find mydir -print | sort | xargs lsacl" .SH DEPENDENCIES .C lsacl will fail when the target file resides on a file system which does not support ACLs. .SS \s-1NFS\s0: .C lsacl is not supported on remote files. .SH AUTHOR .C lsacl was developed by HP. .SH SEE ALSO chacl(1), getaccess(1), ls(1), getacl(2), acl(5). .\" .\" index@\f4lsacl\f1 \- list access control lists (\s-1ACL\s+1s) of files@@@\f3lsacl(1)\f1 .\" index@list access control lists (\s-1ACL\s+1s) of files@@@\f3lsacl(1)\f1 .\" index@files: list access control lists (\s-1ACL\s+1s) of files@@@\f3lsacl(1)\f1 .\" index@access control lists (\s-1ACL\s+1s) of files, list@@@\f3lsacl(1)\f1 .\" .\" toc@\f3lsacl(1)\f1:\0\0\f4lsacl\f1@@@list access control lists (\s-1ACL\s+1s) of files .\" .\" fileset_database@lsacl.1 USER-CMDS-MAN .\" $Header: ls.1,v 76.2 95/08/23 17:56:11 ssa Exp $ .TA l .TH ls 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ls, l, ll, lsf, lsr, lsx \- list contents of directories .SH SYNOPSIS .CR ls .RC [ \-abcdefgilmnopqrstuxACFLR1 ] .RI [ names ] .PP .CR l .RI [ ls_options ] .RI [ names ] .br .CR ll .RI [ ls_options ] .RI [ names ] .br .CR lsf .RI [ ls_options ] .RI [ names ] .br .CR lsr .RI [ ls_options ] .RI [ names ] .br .CR lsx .RI [ ls_options ] .RI [ names ] .SH DESCRIPTION For each directory argument, the .CR ls command lists the contents of the directory. For each file argument, .CR ls repeats its name and any other information requested. The output is sorted in ascending collation order by default (see Environment Variables below). When no argument is given, the current directory is listed. When several arguments are given, the arguments are first sorted appropriately, but file arguments appear before directories and their contents. .PP If you are a user with appropriate privileges, all files except .CR . and .CR .. are listed by default. .PP There are three major listing formats. The format chosen depends on whether the output is going to a login device (determined by whether output device file is a .I tty device), and can also be controlled by option flags. The default format for a login device is to list the contents of directories in multicolumn format, with entries sorted vertically by column. (When individual file names (as opposed to directory names) appear in the argument list, those file names are always sorted across the page rather than down the page in columns because individual file names can be arbitrarily long.) If the standard output is not a login device, the default format is to list one entry per line. The .CR \-C and .CR \-x options enable multicolumn formats, and the .CR \-m option enables stream output format in which files are listed across the page, separated by commas. In order to determine output formats for the .CR \-C , .CR \-x , and .CR \-m options, .CR ls uses an environment variable, .CR COLUMNS , to determine the number of character positions available on each output line. If this variable is not set, the .I terminfo database is used to determine the number of columns, based on the environment variable .CR TERM . If this information cannot be obtained, 80 columns is assumed. .SS Options .CR ls recognizes the following options: .RS .TP 6 .CR \-a List all entries; usually entries whose names begin with a period .RC ( . ) are not listed. .TP .CR \-b Force printing of nongraphic characters to be in the octal .CI \e ddd notation. .TP .CR \-c Use time of last modification of the inode (file created, mode changed, etc.) for sorting .RC ( \-t ) or printing .RC ( \-l (ell)). .TP .CR \-d If an argument is a directory, list only its name (not its contents); often used with .CR \-l (ell) to get the status of a directory. .TP .CR \-e Print the extent attributes of the file. If any of the files has a extent attribute, this option prints the extent size, space reserved and allocation flags. This option must be used with the .CR \-l (ell) option. .TP .CR \-f Force each argument to be interpreted as a directory and list the name found in each slot. This option disables .CR \-l (ell), .CR \-t , .CR \-s , and .CR \-r , and enables .CR \-a ; the order is the order in which entries appear in the directory. .TP .CR \-g Same as .CR \-l , (ell) except that only the group is printed (owner is omitted). If both .CR \-l (ell) and .CR \-g are specified, the owner is not printed. .TP .CR \-i For each file, print the inode number in the first column of the report. When used in multicolumn output, the number precedes the file name in each column. .TP .CR \-l (ell) List in long format, giving mode, number of links, owner, group, size in bytes, and time of last modification for each file (see further DESCRIPTION and Access Control Lists below). If the time of last modification is greater than six months ago, or any time in the future, the year is substituted for the hour and minute of the modification time. If the file is a special file, the size field contains the major and minor device numbers rather than a size. .TP .CR \-m Stream output format. .TP .CR \-n The same as .CR \-l , (ell) except that the owner's UID and group's GID numbers are printed, rather than the associated character strings. .TP .CR \-o The same as .CR \-l , (ell) except that only the owner is printed (group is omitted). (If both .CR \-l (ell) and .CR \-o are specified, the group is not printed). .TP .CR \-p Put a slash .RC ( / ) after each file name if that file is a directory. .TP .CR \-q Force printing of nongraphic characters in file names as the character .RC ( ? ). .TP .CR \-r Reverse the order of sort to get reverse (descending) collation or oldest first, as appropriate. .TP .CR \-s Give size in blocks, including indirect blocks, for each entry. The first entry printed is the total number of blocks in the directory. When used in multicolumn output, the number of blocks precedes the file name in each column. .TP .CR \-t Sort by time modified (latest first) before sorting alphabetically. .TP .CR \-u Use time of last access instead of last modification for sorting .RC ( \-t option) or printing .RC ( \-l (ell) option). .TP .CR \-x Multicolumn output with entries sorted across rather than down the page. .TP .CR \-A The same as .CR \-a , except that the current directory "." and parent directory ".." are not listed. For a user with appropriate privileges, this flag defaults to ON, and is turned off by .CR \-A . .TP .CR \-C Multicolumn output with entries sorted down the columns. .TP .CR \-F Put a slash .RC ( / ) after each file name if that file is a directory or a symbolic link to a directory; put an asterisk .RC ( * ) after each file name if that file is executable; put an at sign (\f3@\f1) after each file name if that file is a symbolic link to a file; put a vertical bar .RC ( | ) after each file name if that file is a FIFO. .TP .CR \-L If the argument is a symbolic link, list the file or directory to which the link refers rather than the link itself. .TP .CR \-R Recursively list subdirectories encountered. .TP .CR \-1 (one) The file names will be listed in single column format regardless of the output device. This forces single column format to the user's terminal. .RE .PP Specifying more than one of the options in the following mutually exclusive pairs is not considered an error: .CR \-C and .CR \-l (ell), .CR \-m and .CR \-l (ell), .CR \-x and .CR \-l (ell), .CR \-C and .CR \-1 (one), .CR \-c and .CR \-u . .PP .CR ls is normally known by several shorthand-version names for the various formats: .RS .TP 6 .CR l equivalent to .CR "ls \-m" . .PD 0 .TP .CR ll equivalent to .CR "ls \-l" (ell). .TP .CR lsf equivalent to .CR "ls \-F" . .TP .CR lsr equivalent to .CR "ls \-R" . .TP .CR lsx equivalent to .CR "ls \-x" . .RE .PD .PP The shorthand notations are implemented as links to .CR ls . Option arguments to the shorthand versions behave exactly as if the long form above had been used with the additional arguments. .PP .B "Mode Bits Interpretation (\-l option)" .br The mode printed in listings produced by the .CR \-l (ell) option consists of 10 characters. The first character indicates the entry type: .RS .TP 6 .CR d Directory .PD 0 .TP .CR b Block special file .TP .CR c Character special file .TP .CR l Symbolic link .TP .CR p Fifo (also called a "named pipe") special file .TP .CR n Network special file .TP .CR s socket .TP .CR \- Ordinary file. .RE .PD .PP The next 9 characters are interpreted as three sets of three bits each which identify access permissions for owner, group, and others as follows: .IP .nf .if t \{ .sp -1v .cs R 19 __________________ \d0400 read by owner (\f3r\f1 or \f3\(mi\f1) | ________________ \d0200 write by owner (\f3w\f1 or \f3\(mi\f1) | | ______________ \d0100 execute (search directory) by owner\ (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | ____________ \d0040 read by group (\f3w\f1 or \f3\(mi\f1) | | | | __________ \d0020 write by group (\f3r\f1 or \f3\(mi\f1) | | | | | ________ \d0010 execute/search by group\ (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | | | | ______ \d0004 read by others (\f3r\f1 or \f3\(mi\f1) | | | | | | | ____ \d0002 write by others (\f3w\f1 or \f3\(mi\f1) | | | | | | | | __ \d0001 execute/search by others\ (\f3x\f1, \f3t\f1, \f3T\f1, or \f3\(mi\f1) | | | | | | | | | r w x r w x r w x .cs R .fi \} .if n \{ +------------------ 0400 read by owner (\f3r\f1 or \f3\(mi\f1) | +---------------- 0200 write by owner (\f3w\f1 or \f3\(mi\f1) | | +-------------- 0100 execute (search directory) by owner | | | (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | +------------ 0040 read by group (\f3r\f1 or \f3\(mi\f1) | | | | +---------- 0020 write by group (\f3w\f1 or \f3\(mi\f1) | | | | | +-------- 0010 execute/search by group | | | | | | (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | | | | +------ 0004 read by others (\f3r\f1 or \f3\(mi\f1) | | | | | | | +---- 0002 write by others (\f3w\f1 or \f3\(mi\f1) | | | | | | | | +-- 0001 execute/search by others | | | | | | | | | (\f3x\f1, \f3t\f1, \f3T\f1, or \f3\(mi\f1) | | | | | | | | | r w x r w x r w x .fi \} .PP Mode letters are interpreted as follows: .RS .TP 7 .CR \- Permission .I not granted in corresponding position. .TP .CR r Read permission granted to corresponding user class. .TP .CR w Write permission granted to corresponding user class. .TP .CR x Execute (or search in directory) permission granted to corresponding user class. .TP .CR s Execute (search) permission granted to corresponding user class. In addition, SUID (Set User ID) permission granted for owner, or SGID (Set Group ID) permission granted for group, as indicated by position. .TP .CR S Same as .CR s except that execute (search) permission is denied to corresponding user class. .TP .CR t (last position only) Execute (search) permission granted to others and "sticky bit" is set (see .IR chmod (2) .CR S_ISVTX description). .TP .CR T Same as .CR t except execute (search directory) permission denied to others. .RE .PP When an option is specified that results in a listing of directory and/or file sizes in bytes or blocks (such as the .CR \-s or .CR \-l (ell) option), a total count of blocks, including indirect blocks, is also printed at the beginning of the listing. .SS "Access Control Lists (ACLs)" If a file has optional ACL entries, the .CR \-l (ell) option displays a plus sign .RC ( + ) after the file's permissions. The permissions shown are a summary representation of the file's access control list, as returned by .CR stat() in the .I st_mode field (see .IR stat (2)). To list the contents of an access control list, use the .CR lsacl command (see .IR lsacl (1) and .IR acl (5)). .SH EXTERNAL INFLUENCES .SS Environment Variables If the .CR COLUMNS variable is set, .CR ls uses the width provided in determining positioning of columnar output. .PP .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not set or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .CR LC_COLLATE determines the order in which the output is sorted. .PP .CR LC_CTYPE determines which characters are classified as nongraphic for the .CR \-b and .CR \-q options, and the interpretation of single- and/or multibyte characters within file names. .PP .CR LC_TIME determines the date and time strings output by the .CR \-g , .CR \-l (ell), .CR \-n , and .CR \-o options. .PP .C LC_MESSAGES determines the language in which messages (other than the date and time strings) are displayed. .PP If any internationalization variable contains an invalid setting, .CR ls behaves as if all internationalization variables are set to "C" (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .br .ne 3v .SH RETURN VALUE .CR ls exits with one of the following values: .RS .TP 5 .CR \00 All input files were listed successfully. .TP .CR >0 .CR ls was aborted because errors occurred when accessing files. The following conditions cause an error: .RS 8 .TP 3 \(bu Specified file not found. .TP \(bu User has no permission to read the directory. .TP \(bu Process could not get enough memory. .TP \(bu Invalid option specified. .RE .RE .SH EXAMPLES Print a long listing of all the files in the current working directory (including the file sizes). List the most recently modified (youngest) file first, followed by the next older file, and so forth, to the oldest. Files whose names begin with a .CR . are also printed. .IP .C "ls \-alst" .SH WARNINGS Setting options based on whether the output is a login .RI ( tty ) device is undesirable because .CR "ls \-s" is very different from .CR "ls \-s | lp" . On the other hand, not using this setting makes old shell scripts that used .CR ls almost inevitably fail. .PP Unprintable characters in file names may confuse the columnar output options. .SH DEPENDENCIES .TP 5 NFS The .CR \-l (ell) option does not display a plus sign .RC ( + ) after the access permission bits of networked files to represent existence of optional access control list entries. .SH AUTHOR .CR ls was developed by AT&T, the University of California, Berkeley and HP. .SH FILES .TP 25 .CR /etc/passwd to get user IDs for .CR "ls \-l" (ell) and .CR "ls \-o" . .PD 0 .TP .CR /etc/group to get group IDs for .CR "ls \-l" (ell) and .CR "ls \-g" . .TP .CR /usr/share/lib/terminfo/?/* to get terminal information. .PD .SH SEE ALSO chmod(1), find(1), lsacl(1), stat(2), acl(5). .SH STANDARDS CONFORMANCE .CR ls ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4l\f1 \(mi list directory contents in stream output format@@@\f3ls(1)\f1 .\" index@\f4ls\f1 \(mi list directory contents@@@\f3ls(1)\f1 .\" index@\f4lsf\f1 \(mi list directory contents, showing subdirectories and executable files@@@\f3ls(1)\f1 .\" index@\f4ll\f1 \(mi list directory contents in long format@@@\f3ls(1)\f1 .\" index@\f4lsr\f1 \(mi recursively list directory contents and subtrees@@@\f3ls(1)\f1 .\" index@\f4lsx\f1 \(mi list directory contents, sort across page instead of down@@@\f3ls(1)\f1 .\" index@list contents of directory@@@\f3ls(1)\f1 .\" index@directory: list contents of directory@@@\f3ls(1)\f1 .\" index@contents of directory, list@@@\f3ls(1)\f1 .\" index@executable files in directory, list@@@\f3ls(1)\f1 .\" index@subdirectories in directory, list@@@\f3ls(1)\f1 .\" .\" toc@\f3ls(1)\f1:\0\0\f4ls\f1, \f4l\f1, \f4ll\f1, \f4lsf\f1, \f4lsr\f1, \f4lsx\f1@@@list contents of directories .\" toc@\f4l\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4ll\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsf\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsr\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsx\f1: list contents of directories@@@see \f3ls(1)\f1 .\" .\" links@ls.1 l.1 .\" links@ls.1 ll.1 .\" links@ls.1 lsf.1 .\" links@ls.1 lsr.1 .\" links@ls.1 lsx.1 .\" $Header: ls.1,v 76.2 95/08/23 17:56:11 ssa Exp $ .TA l .TH ls 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ls, l, ll, lsf, lsr, lsx \- list contents of directories .SH SYNOPSIS .CR ls .RC [ \-abcdefgilmnopqrstuxACFLR1 ] .RI [ names ] .PP .CR l .RI [ ls_options ] .RI [ names ] .br .CR ll .RI [ ls_options ] .RI [ names ] .br .CR lsf .RI [ ls_options ] .RI [ names ] .br .CR lsr .RI [ ls_options ] .RI [ names ] .br .CR lsx .RI [ ls_options ] .RI [ names ] .SH DESCRIPTION For each directory argument, the .CR ls command lists the contents of the directory. For each file argument, .CR ls repeats its name and any other information requested. The output is sorted in ascending collation order by default (see Environment Variables below). When no argument is given, the current directory is listed. When several arguments are given, the arguments are first sorted appropriately, but file arguments appear before directories and their contents. .PP If you are a user with appropriate privileges, all files except .CR . and .CR .. are listed by default. .PP There are three major listing formats. The format chosen depends on whether the output is going to a login device (determined by whether output device file is a .I tty device), and can also be controlled by option flags. The default format for a login device is to list the contents of directories in multicolumn format, with entries sorted vertically by column. (When individual file names (as opposed to directory names) appear in the argument list, those file names are always sorted across the page rather than down the page in columns because individual file names can be arbitrarily long.) If the standard output is not a login device, the default format is to list one entry per line. The .CR \-C and .CR \-x options enable multicolumn formats, and the .CR \-m option enables stream output format in which files are listed across the page, separated by commas. In order to determine output formats for the .CR \-C , .CR \-x , and .CR \-m options, .CR ls uses an environment variable, .CR COLUMNS , to determine the number of character positions available on each output line. If this variable is not set, the .I terminfo database is used to determine the number of columns, based on the environment variable .CR TERM . If this information cannot be obtained, 80 columns is assumed. .SS Options .CR ls recognizes the following options: .RS .TP 6 .CR \-a List all entries; usually entries whose names begin with a period .RC ( . ) are not listed. .TP .CR \-b Force printing of nongraphic characters to be in the octal .CI \e ddd notation. .TP .CR \-c Use time of last modification of the inode (file created, mode changed, etc.) for sorting .RC ( \-t ) or printing .RC ( \-l (ell)). .TP .CR \-d If an argument is a directory, list only its name (not its contents); often used with .CR \-l (ell) to get the status of a directory. .TP .CR \-e Print the extent attributes of the file. If any of the files has a extent attribute, this option prints the extent size, space reserved and allocation flags. This option must be used with the .CR \-l (ell) option. .TP .CR \-f Force each argument to be interpreted as a directory and list the name found in each slot. This option disables .CR \-l (ell), .CR \-t , .CR \-s , and .CR \-r , and enables .CR \-a ; the order is the order in which entries appear in the directory. .TP .CR \-g Same as .CR \-l , (ell) except that only the group is printed (owner is omitted). If both .CR \-l (ell) and .CR \-g are specified, the owner is not printed. .TP .CR \-i For each file, print the inode number in the first column of the report. When used in multicolumn output, the number precedes the file name in each column. .TP .CR \-l (ell) List in long format, giving mode, number of links, owner, group, size in bytes, and time of last modification for each file (see further DESCRIPTION and Access Control Lists below). If the time of last modification is greater than six months ago, or any time in the future, the year is substituted for the hour and minute of the modification time. If the file is a special file, the size field contains the major and minor device numbers rather than a size. .TP .CR \-m Stream output format. .TP .CR \-n The same as .CR \-l , (ell) except that the owner's UID and group's GID numbers are printed, rather than the associated character strings. .TP .CR \-o The same as .CR \-l , (ell) except that only the owner is printed (group is omitted). (If both .CR \-l (ell) and .CR \-o are specified, the group is not printed). .TP .CR \-p Put a slash .RC ( / ) after each file name if that file is a directory. .TP .CR \-q Force printing of nongraphic characters in file names as the character .RC ( ? ). .TP .CR \-r Reverse the order of sort to get reverse (descending) collation or oldest first, as appropriate. .TP .CR \-s Give size in blocks, including indirect blocks, for each entry. The first entry printed is the total number of blocks in the directory. When used in multicolumn output, the number of blocks precedes the file name in each column. .TP .CR \-t Sort by time modified (latest first) before sorting alphabetically. .TP .CR \-u Use time of last access instead of last modification for sorting .RC ( \-t option) or printing .RC ( \-l (ell) option). .TP .CR \-x Multicolumn output with entries sorted across rather than down the page. .TP .CR \-A The same as .CR \-a , except that the current directory "." and parent directory ".." are not listed. For a user with appropriate privileges, this flag defaults to ON, and is turned off by .CR \-A . .TP .CR \-C Multicolumn output with entries sorted down the columns. .TP .CR \-F Put a slash .RC ( / ) after each file name if that file is a directory or a symbolic link to a directory; put an asterisk .RC ( * ) after each file name if that file is executable; put an at sign (\f3@\f1) after each file name if that file is a symbolic link to a file; put a vertical bar .RC ( | ) after each file name if that file is a FIFO. .TP .CR \-L If the argument is a symbolic link, list the file or directory to which the link refers rather than the link itself. .TP .CR \-R Recursively list subdirectories encountered. .TP .CR \-1 (one) The file names will be listed in single column format regardless of the output device. This forces single column format to the user's terminal. .RE .PP Specifying more than one of the options in the following mutually exclusive pairs is not considered an error: .CR \-C and .CR \-l (ell), .CR \-m and .CR \-l (ell), .CR \-x and .CR \-l (ell), .CR \-C and .CR \-1 (one), .CR \-c and .CR \-u . .PP .CR ls is normally known by several shorthand-version names for the various formats: .RS .TP 6 .CR l equivalent to .CR "ls \-m" . .PD 0 .TP .CR ll equivalent to .CR "ls \-l" (ell). .TP .CR lsf equivalent to .CR "ls \-F" . .TP .CR lsr equivalent to .CR "ls \-R" . .TP .CR lsx equivalent to .CR "ls \-x" . .RE .PD .PP The shorthand notations are implemented as links to .CR ls . Option arguments to the shorthand versions behave exactly as if the long form above had been used with the additional arguments. .PP .B "Mode Bits Interpretation (\-l option)" .br The mode printed in listings produced by the .CR \-l (ell) option consists of 10 characters. The first character indicates the entry type: .RS .TP 6 .CR d Directory .PD 0 .TP .CR b Block special file .TP .CR c Character special file .TP .CR l Symbolic link .TP .CR p Fifo (also called a "named pipe") special file .TP .CR n Network special file .TP .CR s socket .TP .CR \- Ordinary file. .RE .PD .PP The next 9 characters are interpreted as three sets of three bits each which identify access permissions for owner, group, and others as follows: .IP .nf .if t \{ .sp -1v .cs R 19 __________________ \d0400 read by owner (\f3r\f1 or \f3\(mi\f1) | ________________ \d0200 write by owner (\f3w\f1 or \f3\(mi\f1) | | ______________ \d0100 execute (search directory) by owner\ (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | ____________ \d0040 read by group (\f3w\f1 or \f3\(mi\f1) | | | | __________ \d0020 write by group (\f3r\f1 or \f3\(mi\f1) | | | | | ________ \d0010 execute/search by group\ (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | | | | ______ \d0004 read by others (\f3r\f1 or \f3\(mi\f1) | | | | | | | ____ \d0002 write by others (\f3w\f1 or \f3\(mi\f1) | | | | | | | | __ \d0001 execute/search by others\ (\f3x\f1, \f3t\f1, \f3T\f1, or \f3\(mi\f1) | | | | | | | | | r w x r w x r w x .cs R .fi \} .if n \{ +------------------ 0400 read by owner (\f3r\f1 or \f3\(mi\f1) | +---------------- 0200 write by owner (\f3w\f1 or \f3\(mi\f1) | | +-------------- 0100 execute (search directory) by owner | | | (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | +------------ 0040 read by group (\f3r\f1 or \f3\(mi\f1) | | | | +---------- 0020 write by group (\f3w\f1 or \f3\(mi\f1) | | | | | +-------- 0010 execute/search by group | | | | | | (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | | | | +------ 0004 read by others (\f3r\f1 or \f3\(mi\f1) | | | | | | | +---- 0002 write by others (\f3w\f1 or \f3\(mi\f1) | | | | | | | | +-- 0001 execute/search by others | | | | | | | | | (\f3x\f1, \f3t\f1, \f3T\f1, or \f3\(mi\f1) | | | | | | | | | r w x r w x r w x .fi \} .PP Mode letters are interpreted as follows: .RS .TP 7 .CR \- Permission .I not granted in corresponding position. .TP .CR r Read permission granted to corresponding user class. .TP .CR w Write permission granted to corresponding user class. .TP .CR x Execute (or search in directory) permission granted to corresponding user class. .TP .CR s Execute (search) permission granted to corresponding user class. In addition, SUID (Set User ID) permission granted for owner, or SGID (Set Group ID) permission granted for group, as indicated by position. .TP .CR S Same as .CR s except that execute (search) permission is denied to corresponding user class. .TP .CR t (last position only) Execute (search) permission granted to others and "sticky bit" is set (see .IR chmod (2) .CR S_ISVTX description). .TP .CR T Same as .CR t except execute (search directory) permission denied to others. .RE .PP When an option is specified that results in a listing of directory and/or file sizes in bytes or blocks (such as the .CR \-s or .CR \-l (ell) option), a total count of blocks, including indirect blocks, is also printed at the beginning of the listing. .SS "Access Control Lists (ACLs)" If a file has optional ACL entries, the .CR \-l (ell) option displays a plus sign .RC ( + ) after the file's permissions. The permissions shown are a summary representation of the file's access control list, as returned by .CR stat() in the .I st_mode field (see .IR stat (2)). To list the contents of an access control list, use the .CR lsacl command (see .IR lsacl (1) and .IR acl (5)). .SH EXTERNAL INFLUENCES .SS Environment Variables If the .CR COLUMNS variable is set, .CR ls uses the width provided in determining positioning of columnar output. .PP .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not set or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .CR LC_COLLATE determines the order in which the output is sorted. .PP .CR LC_CTYPE determines which characters are classified as nongraphic for the .CR \-b and .CR \-q options, and the interpretation of single- and/or multibyte characters within file names. .PP .CR LC_TIME determines the date and time strings output by the .CR \-g , .CR \-l (ell), .CR \-n , and .CR \-o options. .PP .C LC_MESSAGES determines the language in which messages (other than the date and time strings) are displayed. .PP If any internationalization variable contains an invalid setting, .CR ls behaves as if all internationalization variables are set to "C" (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .br .ne 3v .SH RETURN VALUE .CR ls exits with one of the following values: .RS .TP 5 .CR \00 All input files were listed successfully. .TP .CR >0 .CR ls was aborted because errors occurred when accessing files. The following conditions cause an error: .RS 8 .TP 3 \(bu Specified file not found. .TP \(bu User has no permission to read the directory. .TP \(bu Process could not get enough memory. .TP \(bu Invalid option specified. .RE .RE .SH EXAMPLES Print a long listing of all the files in the current working directory (including the file sizes). List the most recently modified (youngest) file first, followed by the next older file, and so forth, to the oldest. Files whose names begin with a .CR . are also printed. .IP .C "ls \-alst" .SH WARNINGS Setting options based on whether the output is a login .RI ( tty ) device is undesirable because .CR "ls \-s" is very different from .CR "ls \-s | lp" . On the other hand, not using this setting makes old shell scripts that used .CR ls almost inevitably fail. .PP Unprintable characters in file names may confuse the columnar output options. .SH DEPENDENCIES .TP 5 NFS The .CR \-l (ell) option does not display a plus sign .RC ( + ) after the access permission bits of networked files to represent existence of optional access control list entries. .SH AUTHOR .CR ls was developed by AT&T, the University of California, Berkeley and HP. .SH FILES .TP 25 .CR /etc/passwd to get user IDs for .CR "ls \-l" (ell) and .CR "ls \-o" . .PD 0 .TP .CR /etc/group to get group IDs for .CR "ls \-l" (ell) and .CR "ls \-g" . .TP .CR /usr/share/lib/terminfo/?/* to get terminal information. .PD .SH SEE ALSO chmod(1), find(1), lsacl(1), stat(2), acl(5). .SH STANDARDS CONFORMANCE .CR ls ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4l\f1 \(mi list directory contents in stream output format@@@\f3ls(1)\f1 .\" index@\f4ls\f1 \(mi list directory contents@@@\f3ls(1)\f1 .\" index@\f4lsf\f1 \(mi list directory contents, showing subdirectories and executable files@@@\f3ls(1)\f1 .\" index@\f4ll\f1 \(mi list directory contents in long format@@@\f3ls(1)\f1 .\" index@\f4lsr\f1 \(mi recursively list directory contents and subtrees@@@\f3ls(1)\f1 .\" index@\f4lsx\f1 \(mi list directory contents, sort across page instead of down@@@\f3ls(1)\f1 .\" index@list contents of directory@@@\f3ls(1)\f1 .\" index@directory: list contents of directory@@@\f3ls(1)\f1 .\" index@contents of directory, list@@@\f3ls(1)\f1 .\" index@executable files in directory, list@@@\f3ls(1)\f1 .\" index@subdirectories in directory, list@@@\f3ls(1)\f1 .\" .\" toc@\f3ls(1)\f1:\0\0\f4ls\f1, \f4l\f1, \f4ll\f1, \f4lsf\f1, \f4lsr\f1, \f4lsx\f1@@@list contents of directories .\" toc@\f4l\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4ll\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsf\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsr\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsx\f1: list contents of directories@@@see \f3ls(1)\f1 .\" .\" links@ls.1 l.1 .\" links@ls.1 ll.1 .\" links@ls.1 lsf.1 .\" links@ls.1 lsr.1 .\" links@ls.1 lsx.1 .\" $Header: ls.1,v 76.2 95/08/23 17:56:11 ssa Exp $ .TA l .TH ls 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ls, l, ll, lsf, lsr, lsx \- list contents of directories .SH SYNOPSIS .CR ls .RC [ \-abcdefgilmnopqrstuxACFLR1 ] .RI [ names ] .PP .CR l .RI [ ls_options ] .RI [ names ] .br .CR ll .RI [ ls_options ] .RI [ names ] .br .CR lsf .RI [ ls_options ] .RI [ names ] .br .CR lsr .RI [ ls_options ] .RI [ names ] .br .CR lsx .RI [ ls_options ] .RI [ names ] .SH DESCRIPTION For each directory argument, the .CR ls command lists the contents of the directory. For each file argument, .CR ls repeats its name and any other information requested. The output is sorted in ascending collation order by default (see Environment Variables below). When no argument is given, the current directory is listed. When several arguments are given, the arguments are first sorted appropriately, but file arguments appear before directories and their contents. .PP If you are a user with appropriate privileges, all files except .CR . and .CR .. are listed by default. .PP There are three major listing formats. The format chosen depends on whether the output is going to a login device (determined by whether output device file is a .I tty device), and can also be controlled by option flags. The default format for a login device is to list the contents of directories in multicolumn format, with entries sorted vertically by column. (When individual file names (as opposed to directory names) appear in the argument list, those file names are always sorted across the page rather than down the page in columns because individual file names can be arbitrarily long.) If the standard output is not a login device, the default format is to list one entry per line. The .CR \-C and .CR \-x options enable multicolumn formats, and the .CR \-m option enables stream output format in which files are listed across the page, separated by commas. In order to determine output formats for the .CR \-C , .CR \-x , and .CR \-m options, .CR ls uses an environment variable, .CR COLUMNS , to determine the number of character positions available on each output line. If this variable is not set, the .I terminfo database is used to determine the number of columns, based on the environment variable .CR TERM . If this information cannot be obtained, 80 columns is assumed. .SS Options .CR ls recognizes the following options: .RS .TP 6 .CR \-a List all entries; usually entries whose names begin with a period .RC ( . ) are not listed. .TP .CR \-b Force printing of nongraphic characters to be in the octal .CI \e ddd notation. .TP .CR \-c Use time of last modification of the inode (file created, mode changed, etc.) for sorting .RC ( \-t ) or printing .RC ( \-l (ell)). .TP .CR \-d If an argument is a directory, list only its name (not its contents); often used with .CR \-l (ell) to get the status of a directory. .TP .CR \-e Print the extent attributes of the file. If any of the files has a extent attribute, this option prints the extent size, space reserved and allocation flags. This option must be used with the .CR \-l (ell) option. .TP .CR \-f Force each argument to be interpreted as a directory and list the name found in each slot. This option disables .CR \-l (ell), .CR \-t , .CR \-s , and .CR \-r , and enables .CR \-a ; the order is the order in which entries appear in the directory. .TP .CR \-g Same as .CR \-l , (ell) except that only the group is printed (owner is omitted). If both .CR \-l (ell) and .CR \-g are specified, the owner is not printed. .TP .CR \-i For each file, print the inode number in the first column of the report. When used in multicolumn output, the number precedes the file name in each column. .TP .CR \-l (ell) List in long format, giving mode, number of links, owner, group, size in bytes, and time of last modification for each file (see further DESCRIPTION and Access Control Lists below). If the time of last modification is greater than six months ago, or any time in the future, the year is substituted for the hour and minute of the modification time. If the file is a special file, the size field contains the major and minor device numbers rather than a size. .TP .CR \-m Stream output format. .TP .CR \-n The same as .CR \-l , (ell) except that the owner's UID and group's GID numbers are printed, rather than the associated character strings. .TP .CR \-o The same as .CR \-l , (ell) except that only the owner is printed (group is omitted). (If both .CR \-l (ell) and .CR \-o are specified, the group is not printed). .TP .CR \-p Put a slash .RC ( / ) after each file name if that file is a directory. .TP .CR \-q Force printing of nongraphic characters in file names as the character .RC ( ? ). .TP .CR \-r Reverse the order of sort to get reverse (descending) collation or oldest first, as appropriate. .TP .CR \-s Give size in blocks, including indirect blocks, for each entry. The first entry printed is the total number of blocks in the directory. When used in multicolumn output, the number of blocks precedes the file name in each column. .TP .CR \-t Sort by time modified (latest first) before sorting alphabetically. .TP .CR \-u Use time of last access instead of last modification for sorting .RC ( \-t option) or printing .RC ( \-l (ell) option). .TP .CR \-x Multicolumn output with entries sorted across rather than down the page. .TP .CR \-A The same as .CR \-a , except that the current directory "." and parent directory ".." are not listed. For a user with appropriate privileges, this flag defaults to ON, and is turned off by .CR \-A . .TP .CR \-C Multicolumn output with entries sorted down the columns. .TP .CR \-F Put a slash .RC ( / ) after each file name if that file is a directory or a symbolic link to a directory; put an asterisk .RC ( * ) after each file name if that file is executable; put an at sign (\f3@\f1) after each file name if that file is a symbolic link to a file; put a vertical bar .RC ( | ) after each file name if that file is a FIFO. .TP .CR \-L If the argument is a symbolic link, list the file or directory to which the link refers rather than the link itself. .TP .CR \-R Recursively list subdirectories encountered. .TP .CR \-1 (one) The file names will be listed in single column format regardless of the output device. This forces single column format to the user's terminal. .RE .PP Specifying more than one of the options in the following mutually exclusive pairs is not considered an error: .CR \-C and .CR \-l (ell), .CR \-m and .CR \-l (ell), .CR \-x and .CR \-l (ell), .CR \-C and .CR \-1 (one), .CR \-c and .CR \-u . .PP .CR ls is normally known by several shorthand-version names for the various formats: .RS .TP 6 .CR l equivalent to .CR "ls \-m" . .PD 0 .TP .CR ll equivalent to .CR "ls \-l" (ell). .TP .CR lsf equivalent to .CR "ls \-F" . .TP .CR lsr equivalent to .CR "ls \-R" . .TP .CR lsx equivalent to .CR "ls \-x" . .RE .PD .PP The shorthand notations are implemented as links to .CR ls . Option arguments to the shorthand versions behave exactly as if the long form above had been used with the additional arguments. .PP .B "Mode Bits Interpretation (\-l option)" .br The mode printed in listings produced by the .CR \-l (ell) option consists of 10 characters. The first character indicates the entry type: .RS .TP 6 .CR d Directory .PD 0 .TP .CR b Block special file .TP .CR c Character special file .TP .CR l Symbolic link .TP .CR p Fifo (also called a "named pipe") special file .TP .CR n Network special file .TP .CR s socket .TP .CR \- Ordinary file. .RE .PD .PP The next 9 characters are interpreted as three sets of three bits each which identify access permissions for owner, group, and others as follows: .IP .nf .if t \{ .sp -1v .cs R 19 __________________ \d0400 read by owner (\f3r\f1 or \f3\(mi\f1) | ________________ \d0200 write by owner (\f3w\f1 or \f3\(mi\f1) | | ______________ \d0100 execute (search directory) by owner\ (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | ____________ \d0040 read by group (\f3w\f1 or \f3\(mi\f1) | | | | __________ \d0020 write by group (\f3r\f1 or \f3\(mi\f1) | | | | | ________ \d0010 execute/search by group\ (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | | | | ______ \d0004 read by others (\f3r\f1 or \f3\(mi\f1) | | | | | | | ____ \d0002 write by others (\f3w\f1 or \f3\(mi\f1) | | | | | | | | __ \d0001 execute/search by others\ (\f3x\f1, \f3t\f1, \f3T\f1, or \f3\(mi\f1) | | | | | | | | | r w x r w x r w x .cs R .fi \} .if n \{ +------------------ 0400 read by owner (\f3r\f1 or \f3\(mi\f1) | +---------------- 0200 write by owner (\f3w\f1 or \f3\(mi\f1) | | +-------------- 0100 execute (search directory) by owner | | | (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | +------------ 0040 read by group (\f3r\f1 or \f3\(mi\f1) | | | | +---------- 0020 write by group (\f3w\f1 or \f3\(mi\f1) | | | | | +-------- 0010 execute/search by group | | | | | | (\f3x\f1, \f3s\f1, \f3S\f1, or \f3\(mi\f1) | | | | | | +------ 0004 read by others (\f3r\f1 or \f3\(mi\f1) | | | | | | | +---- 0002 write by others (\f3w\f1 or \f3\(mi\f1) | | | | | | | | +-- 0001 execute/search by others | | | | | | | | | (\f3x\f1, \f3t\f1, \f3T\f1, or \f3\(mi\f1) | | | | | | | | | r w x r w x r w x .fi \} .PP Mode letters are interpreted as follows: .RS .TP 7 .CR \- Permission .I not granted in corresponding position. .TP .CR r Read permission granted to corresponding user class. .TP .CR w Write permission granted to corresponding user class. .TP .CR x Execute (or search in directory) permission granted to corresponding user class. .TP .CR s Execute (search) permission granted to corresponding user class. In addition, SUID (Set User ID) permission granted for owner, or SGID (Set Group ID) permission granted for group, as indicated by position. .TP .CR S Same as .CR s except that execute (search) permission is denied to corresponding user class. .TP .CR t (last position only) Execute (search) permission granted to others and "sticky bit" is set (see .IR chmod (2) .CR S_ISVTX description). .TP .CR T Same as .CR t except execute (search directory) permission denied to others. .RE .PP When an option is specified that results in a listing of directory and/or file sizes in bytes or blocks (such as the .CR \-s or .CR \-l (ell) option), a total count of blocks, including indirect blocks, is also printed at the beginning of the listing. .SS "Access Control Lists (ACLs)" If a file has optional ACL entries, the .CR \-l (ell) option displays a plus sign .RC ( + ) after the file's permissions. The permissions shown are a summary representation of the file's access control list, as returned by .CR stat() in the .I st_mode field (see .IR stat (2)). To list the contents of an access control list, use the .CR lsacl command (see .IR lsacl (1) and .IR acl (5)). .SH EXTERNAL INFLUENCES .SS Environment Variables If the .CR COLUMNS variable is set, .CR ls uses the width provided in determining positioning of columnar output. .PP .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not set or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .CR LC_COLLATE determines the order in which the output is sorted. .PP .CR LC_CTYPE determines which characters are classified as nongraphic for the .CR \-b and .CR \-q options, and the interpretation of single- and/or multibyte characters within file names. .PP .CR LC_TIME determines the date and time strings output by the .CR \-g , .CR \-l (ell), .CR \-n , and .CR \-o options. .PP .C LC_MESSAGES determines the language in which messages (other than the date and time strings) are displayed. .PP If any internationalization variable contains an invalid setting, .CR ls behaves as if all internationalization variables are set to "C" (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .br .ne 3v .SH RETURN VALUE .CR ls exits with one of the following values: .RS .TP 5 .CR \00 All input files were listed successfully. .TP .CR >0 .CR ls was aborted because errors occurred when accessing files. The following conditions cause an error: .RS 8 .TP 3 \(bu Specified file not found. .TP \(bu User has no permission to read the directory. .TP \(bu Process could not get enough memory. .TP \(bu Invalid option specified. .RE .RE .SH EXAMPLES Print a long listing of all the files in the current working directory (including the file sizes). List the most recently modified (youngest) file first, followed by the next older file, and so forth, to the oldest. Files whose names begin with a .CR . are also printed. .IP .C "ls \-alst" .SH WARNINGS Setting options based on whether the output is a login .RI ( tty ) device is undesirable because .CR "ls \-s" is very different from .CR "ls \-s | lp" . On the other hand, not using this setting makes old shell scripts that used .CR ls almost inevitably fail. .PP Unprintable characters in file names may confuse the columnar output options. .SH DEPENDENCIES .TP 5 NFS The .CR \-l (ell) option does not display a plus sign .RC ( + ) after the access permission bits of networked files to represent existence of optional access control list entries. .SH AUTHOR .CR ls was developed by AT&T, the University of California, Berkeley and HP. .SH FILES .TP 25 .CR /etc/passwd to get user IDs for .CR "ls \-l" (ell) and .CR "ls \-o" . .PD 0 .TP .CR /etc/group to get group IDs for .CR "ls \-l" (ell) and .CR "ls \-g" . .TP .CR /usr/share/lib/terminfo/?/* to get terminal information. .PD .SH SEE ALSO chmod(1), find(1), lsacl(1), stat(2), acl(5). .SH STANDARDS CONFORMANCE .CR ls ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4l\f1 \(mi list directory contents in stream output format@@@\f3ls(1)\f1 .\" index@\f4ls\f1 \(mi list directory contents@@@\f3ls(1)\f1 .\" index@\f4lsf\f1 \(mi list directory contents, showing subdirectories and executable files@@@\f3ls(1)\f1 .\" index@\f4ll\f1 \(mi list directory contents in long format@@@\f3ls(1)\f1 .\" index@\f4lsr\f1 \(mi recursively list directory contents and subtrees@@@\f3ls(1)\f1 .\" index@\f4lsx\f1 \(mi list directory contents, sort across page instead of down@@@\f3ls(1)\f1 .\" index@list contents of directory@@@\f3ls(1)\f1 .\" index@directory: list contents of directory@@@\f3ls(1)\f1 .\" index@contents of directory, list@@@\f3ls(1)\f1 .\" index@executable files in directory, list@@@\f3ls(1)\f1 .\" index@subdirectories in directory, list@@@\f3ls(1)\f1 .\" .\" toc@\f3ls(1)\f1:\0\0\f4ls\f1, \f4l\f1, \f4ll\f1, \f4lsf\f1, \f4lsr\f1, \f4lsx\f1@@@list contents of directories .\" toc@\f4l\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4ll\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsf\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsr\f1: list contents of directories@@@see \f3ls(1)\f1 .\" toc@\f4lsx\f1: list contents of directories@@@see \f3ls(1)\f1 .\" .\" links@ls.1 l.1 .\" links@ls.1 ll.1 .\" links@ls.1 lsf.1 .\" links@ls.1 lsr.1 .\" links@ls.1 lsx.1 .\" $Header: m4.1,v 76.1 95/08/23 17:56:48 ssa Exp $ .TA m .TH m4 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME m4 \- macro processor .SH SYNOPSIS .CR m4 .RI [ options ] .RI [ file \0...] .SH DESCRIPTION .CR m4 is a macro processor intended as a front end for Ratfor, C, and other languages. Each of the argument files is processed in order; if there are no files, or if a file name is .CR - , standard input is read. The processed text is written to standard output. .SS Options .CR m4 recognizes the following options: .RS .TP 10 .CR -e Operate interactively. Interrupts are ignored and the output is unbuffered. Using this mode may be very difficult. .TP .CR -s Enable line sync output for the C preprocessor .RC ( # "line ...)" .TP .CI -B int Change the size of the push-back and argument collection buffers from the default of 4,096. .TP .CI -H int Change the size of the symbol table hash array from the default of 199. The size should be prime. .TP .CI -S int Change the size of the call stack from the default of 100 slots. Macros take three slots, and nonmacro arguments take one. .TP .CI -T int Change the size of the token buffer from the default of 512 bytes. .PP To be effective, the options listed above must appear before any file names and before any .CR -D or .CR -U options. .TP 10 .CI -D name\f1[\fP = val\f1]\fP Define .I name as .I val or as null if .IR val is omitted. .TP .CI -U name Undefine .IR name . .RE .SS Macro Calls Macro calls have the form: .IP .IC name ( arg1 , arg2 ,\c .IC ... , argn ) .PP The left parenthesis .RC ( ( ) must immediately follow the name of the macro. If the name of a defined macro is not followed by a .CR ( , it is deemed to be a call of that macro with no arguments. Potential macro names consist of alphabetic letters, digits, and underscore .RC ( _ ); the first character cannot be a digit. .PP Leading unquoted blanks, tabs, and newlines are ignored while collecting arguments. Left and right single quotes .RC ( \` and .CR \' ) are used to quote strings. The value of a quoted string is the string stripped of the quotes. .PP When a macro name is recognized, its arguments are collected by searching for a matching right parenthesis. If fewer arguments are supplied than are in the macro definition, the trailing arguments are taken to be null. Macro evaluation proceeds normally during the collection of the arguments, and any commas or right parentheses which happen to turn up within the value of a nested call are as effective as those in the original input text. After argument collection, the value of the macro is pushed back onto the input stream and rescanned. .SS Built-In Macro Names .CR m4 makes available the following built-in macros. They can be redefined, but, once this is done, the original meaning is lost. Their values are null unless otherwise stated. .TP 18 .CR changecom Change left and right comment markers from the default .CR # and newline. With no arguments, the comment mechanism is effectively disabled. With one argument, the left marker becomes the argument and the right marker becomes newline. With two arguments, both markers are affected. Comment markers may be up to five characters long. .TP .CR changequote Change quote symbols to the first and second arguments. The symbols may be up to five characters long. .CR changequote without arguments restores the original values (i.e., .CR \` and .CR \' ). .TP .CR decr Returns the value of its argument decremented by 1. .TP .CR define The second argument is installed as the value of the macro whose name is the first argument. Each occurrence of .CI $ n in the replacement text, where .I n is a digit, is replaced by the .IR n th argument. Argument 0 is the name of the macro; missing arguments are replaced by the null string; .CR $# is replaced by the number of arguments; .CR $* is replaced by a list of all the arguments separated by commas; .CR $@ is equivalent to .CR $* , but each argument is quoted (with the current quotes). .TP .CR defn Returns the quoted definition of its arguments. It is useful for renaming macros, especially built-ins. .TP .CR divert .CR m4 maintains 10 output streams, numbered 0 to 9. The final output is the concatenation of the streams in numerical order; initially, stream 0 is the current stream. The .CR divert macro changes the current output stream to its (digit-string) argument. Output diverted to a stream other than 0 through 9 is discarded. .TP .CR divnum Returns the value of the current output stream. .TP .CR dnl Reads and discards characters up to and including the next newline. .TP .CR dumpdef Prints current names and definitions, for the named items, or for all if no arguments are given. .TP .CR errprint Prints its argument on the diagnostic output file. .TP .CR eval Evaluates its argument as an arithmetic expression, using 32-bit arithmetic. Operators include .CR + , .CR - , .CR * , .CR / , .CR % , .CR ** " (exponentiation)," .RC "bitwise " & , .CR | , .CR ^ , and .CR ~ , relationals, and parentheses. Octal and hexadecimal numbers may be specified as in C. The second argument specifies the radix for the result; the default is 10. The third argument may be used to specify the minimum number of digits in the result. .TP .CR ifdef If the first argument is defined, the value is the second argument; otherwise the third. If there is no third argument, the value is null. The word .CR unix is predefined on HP-UX system versions of .CR m4 . .TP .CR ifelse Has three or more arguments. If the first argument is the same string as the second, then the value is the third argument. If not, and if there are more than four arguments, the process is repeated with arguments 4, 5, 6 and 7. Otherwise, the value is either the fourth string, or, if it is not present, null. .TP .CR include Returns the contents of the file named in the argument. .TP .CR incr Returns the value of its argument incremented by 1. The value of the argument is calculated by interpreting an initial digit-string as a decimal number. .TP .CR index Returns the position in its first argument where the second argument begins (zero origin), or \(mi1 if the second argument does not occur. .TP .CR len Returns the number of characters in its argument. .TP .CR m4exit Causes immediate exit from .CR m4 . Argument 1, if given, is the exit code; the default is 0. .TP .CR m4wrap Argument 1 is pushed back at final EOF; for example: .CR m4wrap(\`cleanup()\') .TP .CR maketemp Fills in a string of .CR XXXXX in its argument with the current process ID. .TP .CR popdef Removes current definition of its arguments, exposing the previous one, if any. .TP .CR pushdef Similar to .CR define , but saves any previous definition. .TP .CR shift Returns all but its first argument. The other arguments are quoted and pushed back with commas in between. The quoting nullifies the effect of the extra scan that will subsequently be performed. .TP .CR sinclude Identical to .CR include , except that it says nothing if the file is inaccessible. .TP .CR substr Returns a substring of its first argument. The second argument is a zero-origin number selecting the first character; the third argument indicates the length of the substring. A missing third argument is taken to be large enough to extend to the end of the first string. .TP .CR syscmd Executes the HP-UX system command given in the first argument. No value is returned. .TP .CR sysval Is the return code from the last call to .CR syscmd . .TP .CR traceoff Turns off trace globally and for any macros specified. Macros specifically traced by .CR traceon can be untraced only by specific calls to .CR traceoff . .TP .CR traceon With no arguments, turns on tracing for all macros (including built-ins). Otherwise, turns on tracing for named macros. .TP .CR translit Transliterates the characters in its first argument from the set given by the second argument to the set given by the third. No abbreviations are permitted. .TP .CR undefine Removes the definition of the macro named in its argument. .TP .CR undivert Causes immediate output of text from diversions named as arguments, or all diversions if no argument. Text may be undiverted into another diversion. Undiverting discards the diverted text. .PP .PP (XPG4 only.) It is an error to specify an argument containing any non-numeric character for the built-in-macros: .CR "decr" , " divert" , .CR "incr" , " m4exit" , .CR "substr" , " undivert" , and .CR eval . .\" .SH EXAMPLES (none appropriate) .SH SEE ALSO cc(1), cpp(1), ratfor(1). .SH STANDARDS CONFORMANCE .CR m4 ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f1C macro processor@@@\f3m4(1)\f1 .\" index@\f1language macro processor@@@\f3m4(1)\f1 .\" index@\f1macro processor for C, Ratfor and other programming languages@@@\f3m4(1)\f1 .\" index@\f1processor for C, Ratfor and other programming language macros@@@\f3m4(1)\f1 .\" index@\f1programming language macro processor@@@\f3m4(1)\f1 .\" index@\f1Ratfor macro processor@@@\f3m4(1)\f1 .\" index@\f4m4\f1 \- macro processor@@@\f3m4(1)\f1 .\" .\" toc@\f3m4(1)\f1:\0\0\f4m4\f1@@@macro processor .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: mail.1,v 72.5 94/11/14 15:19:57 ssa Exp $ .TA m .TH mail 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mail, rmail \- send mail to users or read mail .SH SYNOPSIS .C mail .RC [ + ] .RC [ -epqr ] .RC [ -f .IR file\| ] .PP .C mail .RC [ -dt ] .IR person \0... .PP .C rmail .RC [ -dt ] .IR person \0... .SS Remarks: See .IR mailx (1) and .IR elm (1) for an enhanced user mail interface. .SH DESCRIPTION The .C mail command, when used without arguments, prints the user's mail, message-by-message, in last-in, first-out order. .PP For each message, .C mail prints a .C ? prompt and reads a line from the standard input to determine the disposition of the message. Commands that automatically proceed to the next message exit from .C mail if .C mail already on the last message. .SS Commands .C mail supports the following commands: .RS .TP 15 Go on to next message. Exit if already on last message. .TP .C + Same as . .TP .C n Same as . .TP .C d Delete message and go on to next message. .TP .C p Print message again. .TP .C - Go back to previous message. .TP .CR s \0[\|\f2files\fP\|] Save message in the named .I files (default is .CR mbox ), mark the message for deletion from the user's .IR mailfile , and proceed to next message. .TP .CR y \0[\|\f2files\fP\|] Same as .CR s \0[\|\f2files\fP\|]. .TP .CR w \0[\|\f2files\fP\|] Save message without its header (the ``From ...'' line), in the named .I files (default is .CR mbox ), mark the message for deletion, and go on to next message. .TP .CI m \0person \0\f1... Mail the message to each named .IR person , mark the message for deletion, and go on to next message. .TP .C q Put undeleted mail back in the .C mailfile and stop. .TP .SM .CR EOT \0\s0(Ctrl-D) Same as .CR q . .TP .C x Abort. Leave original .C mailfile unchanged and stop. .TP .CI ! command Escape to the command interpreter and execute .IR command . .TP .C ? Print a command summary. .TP .C * Same as .CR ? . .RE .SS Command-Line Options The following command-line options alter printing of the mail: .RS .TP 15 .C + Cause messages to be printed in first-in, first-out order. .TP .C -e Suppresses printing of mail and returns the exit value: .RS .nf .IP 0 = Mail present 1 = No mail 2 = Other error .fi .RE .TP 15 .C -p Prints all mail without prompting for disposition. .TP .C -q Causes .C mail to terminate if an interrupt is received. Normally an interrupt only causes the termination of the printing of the current message. .TP .C -r Same as .CR + . .TP .CI -f \0file Causes .C mail to use .I file (for example, .CR mbox ) instead of the default .IR mailfile . .TP .C -t Causes the outbound message to be preceded by each .I person the mail is sent to. A .I person is usually a user name recognized by .C login (see .IR login (1)). If a .I person being sent mail is not recognized, or if .C mail is interrupted during input, the file .C dead.letter will be saved to allow editing and resending. Note that .C dead.letter is regarded as a temporary file in that it is recreated every time needed, erasing the previous contents of .CR dead.letter . .TP .C -d Causes .C mail to deliver mail directly. This isolates .C mail from making routing decisions, and allows it to be used as a local delivery agent. Typically this option is used by auto-routing facilities when they deliver mail locally. .RE .PP When .IR person s are named, .C mail takes the standard input up to an end-of-file (or up to a line consisting of just a .CR . ) and adds it to each .IR person 's .IR mailfile . The message is preceded by the sender's name and a postmark. .PP To denote a recipient on a remote system, prefix .I person by the system name and exclamation mark (see .IR uucp (1)). Everything after the first exclamation mark in .I person is interpreted by the remote system. In particular, if .I person contains additional exclamation marks, it can denote a sequence of machines through which the message is to be sent on the way to its ultimate destination. For example, specifying .C a!b!cde as a recipient's name causes the message to be sent to user .C b!cde on system .CR a . System .C a then interprets that destination as a request to send the message to user .C cde on system .CR b . This might be useful, for instance, if the sending system can access system .C a but not system .CR b . .C mail does not use .C uucp if the remote system is the local system name (i.e., localsystem!user). .PP The .C mailfile can be manipulated in two ways to alter the function of .CR mail . The .I other permissions of the file can be read-write, read-only, or neither read nor write to allow different levels of privacy. If changed to other than the default, the file is preserved, even when empty, to perpetuate the desired permissions. The file can also contain the first line: .IP .C Forward to .I person .PP which causes all mail sent to the owner of the .C mailfile to be forwarded to .IR person . This is especially useful for forwarding all of a person's mail to a given machine in a multiple-machine environment. In order for forwarding to work properly the .C mailfile should have "mail" as group .SM ID, and the group permission should be read-write. .PP .C rmail only permits the sending of mail. .C uucp uses .C rmail as a security precaution. .PP When a user logs in, the command .C mail -e can be used to detect the presence of mail, if any, and so indicate. When terminating, .C mail produces a notification message if new mail arrived while .C mail was running. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_TIME determines the format and contents of the displayed date and time strings. .PP If .C LC_TIME is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C mail behaves as if all internationalization variables are set to "C". See .IR environ (5). .PP When set, the .C TMPDIR environment variable specifies a directory to be used for temporary files, overriding the default directory .CR /tmp . .SS International Code Set Support Between .SM HP-UX systems, single- and multi-byte character code sets are supported within mail text. Headers are restricted to characters from the 7-bit .SM USASCII code set (see .IR ascii (5)). .SH WARNINGS Conditions sometimes result in a failure to remove a lock file. .PP After an interrupt, the next message may not be printed. To force printing, type a .CR p . .PP Lines that look like postmarks in the message (that is, ``From\0...'') are preceded by .CR > . .PP .C mail treats a line consisting solely of a dot .RC (\| . \|) as the end of the message, except when the .C rmail -d command is used. .PP The maximum allowable line length in mail messages is .C BUFSIZ bytes as defined in .CR /usr/include/stdio.h . If line length exceeds this limit, .C mail truncates the line starting at beginning-of-line, and uses only the trailing .C BUFSIZ characters. .PP Using two separate mail programs to access the same mail file simultaneously (usually inadvertently from two separate windows) can cause unpredictable results. .SH FILES .TP 25 .C /var/mail/*.lock Lock for mail directory .PD 0 .TP .C dead.letter Unmailable text .TP .C /tmp/ma* Temporary file .TP .C $MAIL Variable containing path name of .C mailfile .TP .C $HOME/mbox Saved mail .TP .C /etc/passwd To identify sender and locate persons .TP .C /var/mail Directory for incoming mail .br (mode .CR 775 , group .SM ID .CR mail ) .TP .CI /var/mail/ user Incoming mail for .IR user ; that is, the .B mailfile .br (mode .CR 660 , group .SM ID .CR mail ) .PD .SH SEE ALSO login(1), mailx(1), uucp(1), write(1). .SH STANDARDS CONFORMANCE .CR mail ": SVID2, SVID3, XPG2, XPG3" .PP .CR rmail ": SVID2, SVID3" .\" .\" index@\f4mail\f1 \- send mail to users or read mail@@@\f3mail(1)\f1 .\" index@\f4rmail\f1 \- restricted mailer (send only)@@@\f3mail(1)\f1 .\" index@restricted mailer (send only)@@@\f3mail(1)\f1 .\" index@send mail to users or read mail@@@\f3mail(1)\f1 .\" index@read mail or send mail to users@@@\f3mail(1)\f1 .\" .\" toc@\f3mail(1)\f1:\0\0\f4mail\f1, \f4rmail\f1@@@send mail to users or read mail .\" toc@\f4rmail\f1: send mail to users or read mail@@@see \f3mail(1)\f1 .\" .\" links@mail.1 rmail.1 .\" .\" fileset_database@mail.1 USER-CMDS-MAN .\" $Header: mailfrom.1,v 80.1 96/09/04 20:54:05 ssa Exp $ .TA m .TH mailfrom 1 .SH NAME mailfrom \- summarize mail folders by subject and sender .SH SYNOPSIS .C mailfrom .RC [ -hnQqStv ] .RC [ -s .IR status ] .RI [ folder \(or username ]... .SH DESCRIPTION The .CR mailfrom command outputs one line per message in the form: .IP .I from .RI [ subject ] .PP where .I from is the name of the person the message is from, and .I subject is the subject of the message, if present. If .CR mailfrom determines that the message is from you, the .I from portion will read .CI To \0user\f1, where .IR user is the user the message was sent to. This happens when you receive a copy of a letter you sent. .PP If a .I folder is specified, the program reads that folder rather than the default mailbox, normally .CI /var/mail/ username\f1. See the Operands subsection below. .SS Options .CR mailfrom recognizes the following options: .RS .TP 15 .CR -h Print a brief help message summarizing the options. .TP .CR -n Number the messages using the same numbering scheme used by .CR readmail . .TP .CR -Q Very quiet mode. Only error messages are produced. This option is useful in shell scripts, where only the success or failure of the program is important, and output is not desired. .TP .CR -q Quiet mode. Output only a one-line summary for each mailbox or folder specified. .TP .CR -S Summarize the number of messages by message status in each mailbox or folder. If you want just a summary line, use this in conjunction with the -q option. .TP .CI \-s \0status Only display headers from messages with the given status. .IR status can be one of .CR new , .CR old , .CR read , or .CR unread . .CR old and .CR unread are equivalent. The .CR -s option can be repeated to print header information from more than one category, for example, only new and unread messages. The values can be abbreviated to their first letters. .TP .CR -t Tidy mode. If the .I from field is long enough to displace the .I subject field from its normal start column, move the subject down onto the next line. .TP .CR -v Verbose mode. Print a descriptive header before listing the contents of each mailbox or folder. .RE .SS Operands .CR mailfrom recognizes the following optional operands: .RS .TP 15 .IR folder \(or username A file name or the login name of a mail user on your system. You can use the .CI = filename format to specify a folder in your mail directory, defined by the .CR maildir string variable in your .CR elmrc configuration file. .IP .CR mailfrom searches for the value as a file name relative to your current directory. Then, if the file name is not an absolute path, it searches for the value relative to the incoming mailbox directory, .CR /var/mail . The first file found is selected. You must have read access to the file. .RE .SH EXIT STATUS .CR mailfrom returns the following values: .RS .TP .CR 0 Messages matching .IR status are present. .TP .CR 1 No messages matching .IR status are present, but there are some messages. .TP .CR 2 There are no messages at all. .TP .CR 3 An error occurred. .RE .PP If multiple mailboxes or folders are specified, the exit status only applies to the last one examined. This can be used in scripts to determine what kind of mail a user has. .SH DIAGNOSTICS .PP .C You have no mail. .IP There are no messages in your incoming mailbox. .PP .C You have no new mail. .IP You have messages, but none is new. .PP .IC username "\0has no mail." .IP There are no messages in .IR username 's incoming mailbox. messages are in your incoming mailbox. .PP .CI "You have\0" n "\0new messages,\0" u "\0unread messages,\0\c" .IC r "\0read messages." .IP One line summary of your incoming mailbox, when you use the .CR -q and .CR -S options. .SH EXAMPLES Display header information from all the messages in your mailbox. .IP .C mailfrom .PP Display header information from all new messages in your mailbox. .IP .C mailfrom -s new .PP Assuming you have the proper file permissions to read .CR guest 's mail, print out header information from all new and unread messages in .CR guest 's incoming mailbox. .IP .C mailfrom -s new -s unread guest .PP Print only a one line summary of how many new, unread, and read messages are in your incoming mailbox. .IP .C mailfrom -q -S .SH FILES .TP 25 .C "$HOME/.elm/elmrc" Your .CR elm configuration file. .TP .C "/var/mail" Directory of incoming mailboxes. .SH AUTHOR .CR mailfrom was developed by HP. .SH SEE ALSO elm(1), mail(1), mailx(1), readmail(1). .\" .\" toc@\f3mailfrom(1)\f1:\0\0\f4mailfrom\f1@@@summarize mail folders by subject and sender .\" .\" index@\f4mailfrom\f1 \- summarize mail folders by subject and sender@@@\f3mailfrom(1)\f1 .\" index@mail folders, summarize by subject and sender@@@\f3mailfrom(1)\f1 .\" index@from, who is mail from@@@\f3mailfrom(1)\f1 .\" Copyright (c) 1983, 1997 Eric P. Allman .\" Copyright (c) 1985, 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)mailq.1 8.5 (Berkeley) 2/1/97 .\" .TH mailq 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: August 1997 .SH NAME .B mailq \- print the mail queue .SH SYNOPSIS .B mailq .RC [ -v ] .SH DESCRIPTION .B Mailq prints a summary of the mail messages queued for future delivery. .PP The first line printed for each message shows the internal identifier used on this host for the message, the size of the message in bytes, the date and time the message was accepted into the queue, and the envelope sender of the message. The second line shows the error message that caused this message to be retained in the queue; it will not be present if the message is being processed for the first time. The following lines show message recipients, one per line. .PP .B Mailq is identical to ``sendmail -bp''. .PP The options are as follows: .TP .B \-v Print verbose information. This adds the priority of the message and a single character indicator (``+'' or blank) indicating whether a warning message has been sent on the first line of the message. Additionally, extra lines may be intermixed with the recipients indicating the ``controlling user'' information; this shows who will own any programs that are executed on behalf of this message and the name of the alias this command expanded from, if any. .PP .SH RETURN VALUE The .B mailq utility exits 0 on success, and >0 if an error occurs. .SH SEE ALSO sendmail(1M). .SH HISTORY The .B mailq command appeared in 4.0BSD. .\" @(#)mailstats.1 8.1 (Berkeley) 9/21/96 .TH mailstats 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: August 1997 .SH NAME .B mailstats \- display mail statistics .SH SYNOPSIS .B mailstats .RC [ -o ] .RC [ -C .IR \|cffile\| ] .RC [ -f .IR \|stfile\| ] .SH DESCRIPTION The .B mailstats utility displays the current mail statistics. .PP First, the time at which statistics started being kept is displayed, in the format specified by ctime(3C). Then, the statistics for each mailer are displayed on a single line, each with the following whitespace separated fields: .PP .TP 25 .CR M The mailer number. .TP .CR msgsfr Number of messages from the mailer. .TP .CR bytes_from Kbytes from the mailer. .TP .CR msgsto Number of messages to the mailer. .TP .CR bytes_to Kbytes to the mailer. .TP .CR Mailer The name of the mailer. .PP After this display, a line totaling the values for all of the mailers is displayed, separated from the previous information by a line containing only equals (``='') characters. .PP The options are as follows: .TP .B \-C Read the specified file instead of the default .B sendmail ``cf'' file. .TP .B \-f Read the specified statistics file instead of the statistics file specified in the .B sendmail ``cf'' file. .TP .B \-o Don't display the name of the mailer in the output. .SH RETURN VALUE The .B mailstats utility exits 0 on success, and >0 if an error occurs. .SH FILES .TP 25 /etc/mail/sendmail.cf The default .B sendmail ``cf'' file. .TP /etc/mail/sendmail.st The default .B sendmail statistics file. .SH SEE ALSO mailq(1), sendmail(1M). .\" $Header: mailx.1,v 1.2.113.3 97/08/05 21:53:46 madhut Exp $ .TA m .TH mailx 1 .SH NAME mailx \- interactive message processing system .SH SYNOPSIS .SS Send mode: .C mailx .RC [ -FUm ] .RC [ -s .IR subject\| ] .RC [ -r .IR address\| ] .RC [ -h .IR number\| ] .IR address \0... .SS Receive mode: .C mailx -e .br .C mailx .RC [ -UHiNn ] .RC [ -u .IR user\| ] .br .C mailx -f .RC [ -UHiNn ] .RI [ \|filename\| ] .SS Obsolescent: .C mailx .RC [ -f .IR filename\| ] .RC [ -UHiNn ] .SH DESCRIPTION .C mailx provides a comfortable, flexible environment for sending and receiving messages electronically. When reading mail, .C mailx provides commands to facilitate saving, deleting, and responding to messages. When sending mail, .C mailx allows editing, reviewing and other modification of the message as it is created. .PP Incoming mail for each user is stored in a standard file called the .B system mailbox for that user. When using .C mailx to read messages, the system mailbox is used unless an alternate mailbox file is specified by using the .C -f option with or without a specific filename. As incoming messages are read from the system mailbox, they are marked to be moved to a secondary file for storage (unless specific action is taken) so that the messages need not be seen again. This secondary file is called the .I mbox and is usually located in the user's .C HOME directory (see .C MBOX description under .SM ENVIRONMENT VARIABLES below for a description of this file and other environment variables used by .CR mailx ). Messages remain in this file until specifically removed. .PP Command-line options start with a hyphen .RC ( - ), and any other arguments are assumed to be destinations (recipients). If no recipients are specified, .C mailx attempts to read messages from the system mailbox. .PP Recipient addresses specified on the command line must total less than 1024 characters in length. You may declare an .CR alias or .CR group (see .SM COMMANDS below) to specify a recipient address or list of addresses of up to 8191 characters, and use that alias or group name (though each address in the list must still be less than 1024 characters). If you wish to specify a list of recipient addresses of greater length than this, have your system administrator declare an alias or group in the system alias file .C /etc/mail/aliases and use that alias name instead. .SS Options .C mailx recognizes the following command-line options: .RS .TP 15 .C -e Test for presence of mail. .C mailx prints nothing and exits with a successful return code if there is mail to read. Sometimes used in login scripts such as .C $HOME/.profile to check for mail during login. .TP .C -f Read messages from .I filename instead of the user's system mailbox. If .I filename is not specified, the secondary .I mbox is used. .TP .C -F Record the message in a file named after the first recipient. Overrides the .C record environment variable, if set. .TP .CI -h \0number The number of network "hops" made so far. This is provided for network software to prevent infinite delivery loops. .TP .C -H Print header summary only. .TP .C -i Ignore interrupts. Also see the description of the .C ignore environment below. .TP .C -n Do not initialize from the system default .C mailx.rc file. .TP .C -m Do not add MIME header lines .I Mime Version, Content Type & .I Content Encoding to the header information while sending mails. .TP .C -N Do not print initial header summary. .TP .CI -r \0address Pass .I address to network delivery software. All tilde commands are disabled. .TP .CI -s \0subject Set the Subject header field to .IR subject . .TP .CI -u \0user Read .IR user 's .IR mailbox . Can be used only if read access to .IR user 's mailbox is not read protected. .TP .C -U Convert .SM UUCP\c -style addresses to Internet standards. Overrides the .C conv environment variable. .TP .C -d Turn on debugging output. Neither particularly interesting nor recommended. .RE .PP When reading mail, .C mailx operates in .BR "command mode" . A header summary of the first several messages is displayed, followed by a prompt indicating that .C mailx can accept regular commands (see .SM COMMANDS below). When sending mail, .C mailx operates in .BR "input mode" . If no subject is specified on the command line, a prompt for the subject is printed. As the message is typed, .C mailx reads the message and stores it in a temporary file. Commands can be entered by beginning a line with the tilde .RC ( ~ ) escape character followed by a single command letter and optional arguments. See .SM TILDE ESCAPES for a summary of these commands. .PP The behavior of .C mailx at any given time is governed by a set of .BR "environment variables" ; flags and valued parameters that are set and cleared by using the .CR se t and .CR uns et commands. See .SM ENVIRONMENT VARIABLES below for a summary of these parameters. .PP Recipients listed on the command line can be of three types: login names, shell commands, or alias groups. Login names can be any network address, including mixed network addressing. If the recipient name begins with a pipe symbol .RC ( | ), the rest of the name is assumed to be a shell command to pipe the message through. This provides an automatic interface with any program that reads the standard input, such as .C lp (see .IR lp (1)) for recording outgoing mail on paper. Alias groups are set by the .CR a lias command (see .SM COMMANDS below) and are lists of recipients of any type. .PP Regular commands are of the form .IP .RI [ \|command\| ] .RI [ \|msglist\| ] .RI [ \|arguments\| ] .PP If no command is specified in command mode, .CR p rint is assumed. In input mode, commands are recognized by the escape character (tilde unless redefined by the .C escape environment variable), and lines not treated as commands are treated as input for the message. .PP Each message is assigned a sequential number, and there is always the notion of a .BR "current message" , marked by a .C > in the header summary. Many commands take an optional list of messages .RI ( msglist ) to operate on, which defaults to the current message. A .I msglist is a list of message specifications separated by spaces. The message list can include: .RS .TP 10 .I n Message number .IR n . .TP .C . The current message. .TP .C ^ The first undeleted message. .TP .C $ The last message. .TP .C * All messages. .TP .IC n - m An inclusive range of message numbers, .I n through .IR m , where n is less than m. .TP .I user All messages from .IR user . .TP .CI / string All messages with .I string in the subject line (uppercase-lowercase differences are ignored). .TP .CI : c All messages of type .IR c , where .I c is one of: .RS .RS .TP .C d deleted messages .TP .C n new messages .TP .C o old messages .TP .C r read messages .TP .C u unread messages .RE .RE .IP Note that the context of the command determines whether this type of message specification makes sense. .RE .PP Other arguments are usually arbitrary strings whose usage depends on the command involved. File names, where expected, are expanded using normal shell conventions (see .IR sh (1)). Special characters are recognized by certain commands, and are documented with the commands below. .PP At start-up time, .C mailx reads commands from a system-wide file .RC ( /usr/share/lib/mailx.rc ) to initialize certain parameters, then from a private start-up file .RC ( $HOME/.mailrc ) for personalized variables. Most regular commands are legal inside start-up files, the most common use being to set up initial display options and alias lists. The following commands are not legal in the start-up file: .CR ! , .CR C opy, .CR e dit, .CR fo llowup, .CR F ollowup, .CR ho ld, .CR m ail, .CR pre serve, .CR r eply, .CR R eply, .CR sh ell, and .CR v isual. Any errors in the start-up file cause the remaining lines in the file to be ignored. .SH COMMANDS The following is a complete list of .C mailx commands: .PP .TP 20 .CI ! \0command Escape to the shell. See the description of the .C SHELL environment variable below. .TP .CI # \0comment Null command (comment). Useful in .C .mailrc files. .TP .C = Print the current message number. .TP .C ? Print a summary of commands. .TP Advance to next message and .CR p rint. If this is the first command entered, the first unread message is printed. (To read the current message, use .CR p rint.) .TP .CR a lias\0\f2alias\0name\|\fP... .PD 0 .TP .CR g roup\0\f2alias\0name\|\fP... Declare an alias for the given names. The names are substituted when .I alias is used as a recipient. Useful in the .C .mailrc file. .PD .TP .CR alt ernates\0\f2name\|\fP... Declares a list of alternate names for your login. When responding to a message, these names are removed from the list of recipients for the response. With no arguments, .CR alt ernates prints the current list of alternate names. See also .C allnet under .SM ENVIRONMENT VARIABLES. .TP .CR cd \0[\|\f2directory\fP\|] .PD 0 .TP .CR ch dir\0[\|\f2directory\fP\|] Change directory. If .I directory is not specified, .C $HOME is used. .PD .TP .CR c opy\0[\|\f2filename\fP\|] .PD 0 .TP .CR c opy\0[\|\f2msglist\fP\|]\0\f2filename\fP Copy messages to the file without marking the messages as saved. Otherwise equivalent to the .CR s ave command. .PD .TP .CR C opy\0[\|\f2msglist\fP\|] Save the specified messages in a file whose name is derived from the author of the message to be saved, without marking the messages as saved. Otherwise equivalent to the .CR S ave command. .TP .CR d elete\0[\|\f2msglist\fP\|] Delete messages from the .IR mailbox . If .C autoprint is set, the next message after the last one deleted is printed (see .SM ENVIRONMENT VARIABLES\c ). See also .CR dp . .TP .CR di scard\0[\|\f2header-field\fP\0...] .PD 0 .TP .CR ig nore\0[\|\f2header-field\fP\0...] Suppresses printing of the specified header fields when displaying messages on the screen. Examples of header fields to ignore are "status" and "cc." The fields are included when the message is saved. The .CR P rint and .CR T ype commands override this command. .PD .TP .CR dp [\|\f2msglist\fP\|] .PD 0 .TP .CR dt [\|\f2msglist\fP\|] Delete the specified messages from the mailbox and print the next message after the last one deleted. Roughly equivalent to a .CR d elete command followed by a .CR p rint command. .PD .TP .CR ec ho\0\f2string\fP\0... Echo the given string or strings (similar to .C echo \(mi see .IR echo (1)). .TP .CR e dit\0[\|\f2msglist\f1\|] Edit the given messages. The messages are placed in a temporary file and the .C EDITOR variable is used to get the name of the editor (see .SM ENVIRONMENT VARIABLES\ ). Default editor is .I ed (see .IR ed (1)). .TP .CR ex it .TP .CR x it Exit from .CR mailx , without changing the mailbox. No messages are saved in the .I mbox (see also .CR q uit). .TP .CR fi le\0[\|\f2filename\fP\|] .PD 0 .TP .CR fold er\0[\|\f2filename\fP\|] Quit from the current file of messages and read in the specified file. Several special characters are recognized when used as file names, and substitutions are made as follows: .PD .RS .RS .TP 10 .C % the current mailbox. .PD 0 .TP .CI % \|user the mailbox for .IR user . .TP .C # the previous file. .TP .C & the current .IR mbox . .PD .RE .RE .IP Default file is the current mailbox. .TP .C folders Print the names of the files in the directory set by the .C folder variable (see .SM ENVIRONMENT VARIABLES\c ). .TP .CR fo llowup\0[\|\f2message\fP\|] Respond to a message and record the response in a file whose name is derived from the author of the message. Overrides the .C record variable, if set. See also the .CR F ollowup, .CR S ave, and .CR C opy commands and .C outfolder (see .SM ENVIRONMENT VARIABLES\c ). .TP .CR F ollowup\0[\|\f2msglist\fP\|] Respond to the first message in the .IR msglist , sending the message to the author of each message in the .IR msglist . The subject line is extracted from the first message and the response is recorded in a file whose name is derived from the author of the first message. See also the .CR fo llowup, .CR S ave, and .CR C opy commands and .C outfolder (see .SM ENVIRONMENT VARIABLES\c ). .TP .CR f rom\0[\|\f2msglist\fP\|] Print the header summary for the specified messages. .TP .CR g roup\0\f2alias\0name\fP\|... .PD 0 .TP .CR a lias\0\f2alias\0name\fP\|... Declare an alias for the given names. The names are substituted when .I alias is used as a recipient. Useful in the .C .mailrc file. .PD .TP .CR h eaders\0[\|\f2message\fP\|] Prints the page of headers which includes the message specified. The .C screen variable sets the number of headers per page (see .SM ENVIRONMENT VARIABLES\c ). See also the .C z command. .TP .CR hel p Prints a summary of commands. .TP .CR ho ld\0[\|\f2msglist\fP\|] .PD 0 .TP .CR pre serve\0[\|\f2msglist\fP\|] Holds the specified messages in the .IR mailbox . .PD .TP .CR i f\0 s \(or r .PD 0 .TP .IR \0\0mail-command s .TP .CR el se .TP .IR \0\0mail-command s .TP .CR en dif Conditional execution, where .C s executes the accompanying .IR mail-command s, up to an .CR el se or .CR en dif if the program is in send mode, and .C r causes the accompanying .IR mail-command s to be executed only in receive mode. Intended for use in .C .mailrc files. .TP .CR ig nore\0\f2header-field\fP\0... .PD 0 .TP .CR di scard\0\f2header-field\fP\0... Suppresses printing of the specified header fields when displaying messages on the screen. Examples of header fields to ignore are .C status and .CR cc . All fields are included when the message is saved. The .CR P rint and .CR T ype commands override this command. .PD .TP .CR l ist Prints all commands available. No explanation is given. .TP .CR m ail\0\f2name\f1\0... Mail a message to the specified users. .TP .CR mb ox\0[\|\f2msglist\fP\|] Arrange for the given messages to end up in the standard .I mbox save file when .C mailx terminates normally. See .C MBOX description under .SM ENVIRONMENT VARIABLES for a description of this file. See also the .CR ex it and .CR q uit commands. .TP .CR n ext\0[\|\f2message\fP\|] Go to next message matching .IR message . A .I msglist can be specified, but in this case the first valid message in the list is the only one used. This is useful for jumping to the next message from a specific user since the name would be interpreted as a command in the absence of a real command. See the discussion of .IR msglist s above for a description of possible message specifications. .TP .CR pi pe\0[\|\f2msglist\fP\|]\0[\|\f2command\fP\|] .PD 0 .TP .CR | \0[\|\f2msglist\fP\|]\0[\|\f2command\fP\|] Pipe messages in .I msglist through the specified .IR command . Each message is treated as if it were read. If .I msglist is not specified, the current message is used. If .I command is not specified, the command specified by the current value of the .C cmd variable is used. If .I msglist is specified, .I command must also be specified. If the .C page variable is set, a form feed character is inserted after each message (see .SM ENVIRONMENT VARIABLES\c ). .PD .TP .CR pre serve\0[\|\f2msglist\fP\|] .PD 0 .TP .CR ho ld\0[\|\f2msglist\fP\|] Preserve the specified messages in the .IR mailbox . .PD .TP .CR P rint\0[\|\f2msglist\fP\|] .PD 0 .TP .CR T ype\0[\|\f2msglist\fP\|] Print the specified messages on the screen, including all header fields. Overrides suppression of fields by the .CR ig nore command. .TP .CR p rint\0[\|\f2msglist\fP\|] .PD 0 .TP .CR t ype\0[\|\f2msglist\fP\|] Print the specified messages. If .C crt is set, messages longer than the number of lines specified by the .C crt variable are paged through the command specified by the .C PAGER variable. The default command is .C pg (see .IR pg (1)), but many users prefer .C more (see .IR more (1) \(mi see .SM ENVIRONMENT VARIABLES\c ). .PD .TP .CR q uit Exit from .CR mailx , storing messages that were read in .I mbox and unread messages in the user's system mailbox. Messages that have been explicitly saved in a file are deleted. .TP .CR R eply\0[\|\f2msglist\fP\|] .PD 0 .TP .CR R espond\0[\|\f2msglist\fP\|] Send a response to the author of each message in the .IR msglist . The subject line is taken from the first message. If .C record is set to a file name, the response is saved at the end of that file (see .SM ENVIRONMENT VARIABLES\c ). .PD .TP .CR r eply\0[\|\f2message\fP\|] .PD 0 .TP .CR r espond\0[\|\f2message\fP\|] Reply to the specified message, including all other recipients of the message. If .C record is set to a file name, the response is saved at the end of that file (see .SM ENVIRONMENT VARIABLES\c ). .PD .TP .CR S ave\0[\|\f2msglist\fP\|] Save the specified messages in a file whose name is derived from the author of the first message. The name of the file is based on the author's name with all network addressing stripped off. See also the .CR C opy, .CR fo llowup, and .CR F ollowup commands and .C outfolder (see .SM ENVIRONMENT VARIABLES\c ). .TP .CR s ave\0[\|\f2filename\fP\|] .PD 0 .TP .CR s ave\0[\|\f2msglist\fP\|]\0\f2filename\fP Save the specified messages in the given file. The file is created if it does not exist. The message is deleted from the .I mailbox when .C mailx terminates unless .C keepsave is set (see .SM ENVIRONMENT VARIABLES and the .CR ex it and .CR q uit commands). .PD .TP .CR se t .PD 0 .TP .CR se t\0\f2name\fP .TP .CR se t\0\f2name\fP=\f2string\fP .TP .CR se t\0\f2name\fP=\f2number\fP Define a variable called .IR name . The variable can be given a null, string, or numeric value. .CR Se t by itself prints all defined variables and their values (see .SM ENVIRONMENT VARIABLES for detailed descriptions of the .C mailx variables). .PD .TP .CR sh ell Invoke an interactive shell (see .C SHELL under .SM ENVIRONMENT VARIABLES\c ). .TP .CR si ze\0[\|\f2msglist\fP\|] Print the size in characters of the specified messages. .TP .CR so urce\0\f2filename\f1 Read commands from the given file and return to command mode. .TP .CR to p\0[\|\f2msglist\fP\|] Print the top few lines of the specified messages. If the .C toplines variable is set, it is interpreted as the number of lines to print (see .SM ENVIRONMENT VARIABLES\c ). The default is 5. .TP .CR tou ch\0[\|\f2msglist\fP\|] Touch the specified messages. If any message in .I msglist is not specifically saved in a file, it is placed in the .I mbox upon normal termination. See .CR ex it and .CR q uit. .TP .CR T ype\0[\|\f2msglist\fP\|] .PD 0 .TP .CR P rint\0[\|\f2msglist\fP\|] Print the specified messages on the screen, including all header fields. Overrides suppression of fields by the .CR ig nore command. .PD .TP .CR t ype\0[\|\f2msglist\fP\|] .PD 0 .TP .CR p rint\0[\|\f2msglist\fP\|] Print the specified messages. If .C crt is set, messages longer than the number of lines specified by the .C crt variable are paged through the command specified by the .C PAGER variable. The default command is .IR pg (1) but many users prefer .IR more (1) (see .SM ENVIRONMENT VARIABLES\c ). .PD .TP .CR una lias\0\f2alias\f1 Discard the specified .I alias names. .TP .CR u ndelete\0[\|\f2msglist\fP\|] Restore the specified deleted messages. Restores only messages that were deleted in the current mail session. If .C autoprint is set, the last message of those restored is printed (see .SM ENVIRONMENT VARIABLES\c ). .TP .CR uns et\0\f2name\f1 ... Cause the specified variables to be erased. If the variable was a shell variable imported from the execution environment, it cannot be erased. .TP .CR ve rsion Prints the current version and release date. .TP .CR v isual\0[\|\f2msglist\fP\|] Edit the given messages with a screen editor. The messages are placed in a temporary file and the .C VISUAL variable is used to get the name of the editor (see .SM ENVIRONMENT VARIABLES\c ). .TP .CR w rite\0[\|\f2msglist\fP\|]\0\f2filename\f1 Write the given messages on the specified file, except for the header (the "From ..." line) and trailing blank line. Otherwise equivalent to the .CR s ave command. .TP .CR x it .PD 0 .TP .CR ex it Exit from .CR mailx , without changing the .IR mailbox . No messages are saved in the .I mbox (see also .CR q uit). .PD .TP .CR z [ \|+ \(or -\| ] Scroll the header display forward or backward one screen-full. The number of headers displayed is set by the .C screen variable (see .SM ENVIRONMENT VARIABLES\c ). .SH TILDE ESCAPES The following commands can be used only when in input mode, by beginning a line with the tilde escape character .RC ( ~ ). See .C escape .SM (ENVIRONMENT VARIABLES) for changing this special character. .PP .TP 20 .CI ~! \|command Escape to the shell. .TP .C ~. Simulate end of file (terminate message input). .TP .CR ~: \f2mail-command\f1 .PD 0 .TP .CR ~_\0 \f2mail-command\f1 Perform the command-level request. Valid only when sending a message while reading mail. .PD .TP .C ~? Print a summary of tilde escapes. .TP .C ~A Insert the autograph string .C Sign into the message (see .SM ENVIRONMENT VARIABLES\c ). .TP .C ~a Insert the autograph string .C sign into the message (see .SM ENVIRONMENT VARIABLES\c ). .TP .CI ~b \0name\0... Add .I name to the blind carbon copy (Bcc) list. .TP .CI ~c \0name\0... Add .I name to the carbon copy (Cc) list. .TP .C ~d Read in the .C dead.letter file. See .C DEAD (under .SM ENVIRONMENT VARIABLES\c ) for a description of this file. .TP .C ~e Invoke the editor on the partial message. Also see the .C EDITOR environment variable description below. .TP .CR ~f \0[\|\f2msglist\fP\|] Forward the specified messages. The messages are inserted into the message without alteration. .TP .C ~h Prompt for Subject line and To, Cc, and Bcc lists. If the field is displayed with an initial value, it can be edited as if you had just typed it. .TP .CI ~i \0string Insert the value of the named variable into the text of the message. For example, .C ~A is equivalent to .CR ~i\0Sign . .TP .CR ~m \0[\|\f2msglist\fP\|] Insert the specified messages into the letter, shifting the new text to the right one tab stop. Valid only when sending a message while reading mail. .TP .C ~p Print the message being entered. .TP .C ~q Quit (terminate) input mode by simulating an interrupt. If the body of the message is not null, the partial message is saved in .CR dead.letter . See the description of the .C DEAD environment variable below for a description of this file. .TP .CI ~R \0name\0... Add .I name to the Reply-To list. .TP .CI ~r \0filename .PD 0 .TP .CI ~< \0filename .TP .CI ~ sequence. .PP Target lines with their associated command lines are called .IR rules . .PP .SM .B MACROS: .br Lines of the form .IC string1 " = " string2 are macro definitions. Macros can be defined anywhere in the makefile, but are usually grouped together at the beginning. .I string1 is the macro name; .I string2 is the macro value. .I string2 is defined as all characters up to a comment character or an unescaped new-line. Spaces and tabs immediately to the left and right of the .CR = are ignored. Subsequent appearances of .CI $( string1 ) anywhere in the makefile (except in comments) are replaced by .IR string2 . The parentheses are optional if a single character macro name is used and there is no substitute sequence. An optional substitute sequence, .CI $( string1 .RC [ :\c .IC subst1 =\c .RI [ \|subst2\| ]\|]\c .CR ) can be specified, which causes all nonoverlapping occurrences of .I subst1 at the end of substrings in the value of .I string1 to be replaced by .IR subst2 . Substrings in a macro value are delimited by blanks, tabs, new-line characters, and beginnings of lines. For example, if .IP .CR OBJS .C = file1.o file2.o file3.o .PP then .IP .CR $(OBJS:.o=.c) .PP evaluates to .IP .C file1.c file2.c file3.c .PP Macro values can contain references to other macros (see WARNINGS): .IP .CR ONE .CR = 1 .IP .CR TWELVE .C = $(ONE)2 .PP The value of .CR $(TWELVE) is set to .CR $(ONE)2 but when it is used in a target, command, or include line, it is expanded to .CR 12 . If the value of .CR ONE is subsequently changed by another definition further down in the makefile or on the command line, any references to .CR $(TWELVE) reflect this change. .PP Macro definitions can also be specified on the command line and override any definitions in the makefile. .PP (XPG4 only. Macros on the command line are added to the .CR MAKEFLAGS environment variable. Macros defined in the .CR MAKEFLAGS environment variable, but without any command line macro, adds the macro to the environment overwriting any existing environment variable of the same name.) .PP Certain macros are automatically defined for .CR make (see Built-in Macros). See the Environment section for a discussion of the order in which macro definitions are treated. .PP The value assigned to a macro can be overridden by a conditional macro definition. A conditional macro definition takes on the form .IC target " := " string1 " = " string2. When the target line associated with target is being processed, the macro value specified in the conditional macro definition is in effect. If .I string1 is previously defined, the new value of .I string1 will override the previous definition. The new value of string1 takes effect when target or any dependents of target are being processed. .PP .SM .B INCLUDE LINES: .br If the string .CR include appears as the first seven letters of a line in a makefile, and is followed by one or more space or tab characters, the rest of the line is assumed to be a file name and is read and processed by the current invocation of .CR make as another makefile after any macros in the filename have been expanded. .SS General Description .CR make executes commands previously placed in a makefile to update one or more target names. Target names are typically names of programs. If no .CR -f option is specified, the filenames .CR makefile , .CR Makefile , .CR s.makefile , .CR SCCS/s.makefile , .CR s.Makefile and .CR SCCS/s.Makefile are tried in that order. If .C -f - is specified, the standard input is used. More than one .CR -f option can be specified. The makefile arguments are processed in the order specified. A space between the .CR -f and the filename .CR must be present, and multiple makefile names must each have their own .CR -f option preceding them. The contents of a makefile override the built-in rules and macros if they are present. .PP If no target names are specified on the command line, .CR make updates the first target in the (first) makefile that is not an inference rule. A target is updated only if it depends on files that are newer than the target. Missing files are deemed to be out-of-date. All dependents of a target are recursively updated, if necessary, before the target is updated. This effects a depth-first update of the dependency tree for the target. .PP If a target does not have any dependents specified after the separator on the target line .RI ( "explicit dependents" ), any shell commands associated with that target are executed if the target is out-of-date. .PP A target line can have either a single or double colon between the target name or names and any explicit dependent names. A target name can appear on more than one target line, but all of those lines must be of the same (single- or double-colon) type. For the usual single-colon case, at most one of these target lines can have explicit commands associated with it. If the target is out-of-date with any of its dependents on any of the lines, the explicit commands are executed, if they are specified, or else a default rule can be executed. For the double-colon case, explicit commands can be associated with more than one of the target lines containing the target name; if the target is out-of-date with any of the dependents on a particular line, the commands for that line are executed. A built-in rule may also be executed. .PP Target lines and their associated shell command lines are also referred to as .BR rules . Hash marks .RC ( # ) and new-line characters surround comments anywhere in the makefile except in rules. Comments in the rules depend on the setting of the .CR SHELL macro. .PP The following makefile says that .CR pgm depends on two files: .CR a.o and .CR b.o , and that they in turn depend on their corresponding source files .RC ( a.c and .CR b.c ) and a common file .CR incl.h : .IP .CR OBJS .C = a.o b.o .IP .C pgm: $(OBJS) .br .C " cc $(OBJS) -o pgm" .IP .C a.o: incl.h a.c .br .C " cc -c a.c" .IP .C b.o: incl.h b.c .br .C " cc -c b.c" .PP Command lines are executed one at a time, each by its own shell. Each command line can have one or more of the following prefixes: .CR - , \f3@\f1, or .CR + . These prefixes are explained below. .PP Commands returning non-zero status normally terminate .CR make . The .CR -i option or the presence of the special target .CR .IGNORE in the makefile cause .CR make to continue executing the makefile regardless of how many command lines cause errors, although the error messages are still printed on standard output. If .CR - is present at the beginning of a command line, any error returned by that line is printed to standard output but .CR make does not terminate. The prefix .CR - can be used to selectively ignore errors in a makefile. If the .CR -k option is specified and a command line returns an error status, work is abandoned on the current target, but continues on other branches that do not depend on that target. If the .CR -k option is present in the .CR MAKEFLAGS environment variable, processing can be returned to the default by specifying the .CR -S option. .PP The .CR -n option specifies printing of a command line without execution. However, if the command line has the string .CR $(MAKE) or .CR ${MAKE} in it or .CR + as a prefix, the line is always executed (see discussion of the .CR MAKEFLAGS macro under Environment). The .CR -t (touch) option updates the modified date of a file without executing any commands. .PP A command line is normally printed before it is executed, but if the line has a \f3@\f1 at the beginning, printing is suppressed. The .CR -s option or the presence of the special target .CR .SILENT: in the makefile suppresses printing of all command lines. The \f3@\f1 can be used to selectively turn off printing. Everything printed by .CR make (except the initial tab) is passed directly to the shell without alteration. Thus, .IP .C echo a\e .br .CR b .PP produces .IP .CR ab .PP just as the shell would. .PP The .CR -b option allows old makefiles (those written for the old version of .CR make ) to run without errors. The old version of .CR make assumed that if a target did not have any explicit commands associated with it, the user intended the command to be null, and would not execute any .CR .DEFAULT rule that might have been defined. The current version of .CR make operates in this mode by default. However, the current version of .CR make provides a .CR -B option which turns this mode off so that if a target does not have explicit commands associated with it and a .CR .DEFAULT rule is defined, the .CR .DEFAULT rule is executed. Note that the .CR -b and .CR -B options have no effect on the search and possible location and execution of an appropriate inference rule for the target. The search for a built-in inference rule other than .CR .DEFAULT is always performed. .PP The signals .CR SIGINT , .CR SIGQUIT , .CR SIGHUP , and .CR SIGTERM (see .IR signal (5)) cause the target to be deleted unless the target depends on the special name .CR .PRECIOUS . .SS Options The following is a brief description of all options and some special names. Options can occur in any order. They can be specified separately, or together with one .CR - , except for the .CR -f option. .TP 15 .CR -b Compatibility mode for old (Version 7) makefiles. This option is turned on by default. .TP .CR -B Turn off compatibility mode for old (Version 7) makefiles. .TP .CR -d Debug mode. Print out detailed information on files and times examined. (This is very verbose and is intended for debugging the .CR make command itself.) .TP .CR -e Environment variables override assignments within makefiles . .TP .CI -f " makefile" Description file name, referred to as the makefile. A file name of .CR - denotes the standard input. The contents of the makefile override the built-in rules and macros if they are present. Note that the space between .CR -f and .I makefile .CR must be present. Multiple instances of this option are allowable (except for .CR "-f -" ), and are processed in the order specified. .TP .CR -p Write to standard output the complete set of macro definitions and target descriptions. .TP .CR -i Ignore error codes returned by invoked commands. This mode is also entered if the special target name .CR .IGNORE appears in the makefile. .TP .CR -k When a command returns nonzero status, abandon work on the current entry, but continue on other branches that do not depend on that target. This is the opposite of .CR -S . If both .CR -k and .CR -S are specified, the last one specified is used. .TP .CR -n No execute mode. Print commands, but do not execute them. Even lines beginning with an \f3@\f1 are printed. However, lines that contain the string .CR $(MAKE) or .CR ${MAKE} or that have .CR + as a prefix to the command are executed. .TP .CR -q Question. The .CR make command returns a zero or non-zero status code, depending on whether the target file is or is not up-to-date. Targets are not updated with this option. .TP .CR -r Clear suffix list and do not use the built-in rules. .TP .CR -s Silent mode. Command lines are not printed to standard output before their execution. This mode is also entered if the special target name .CR .SILENT appears in the makefile. .TP .CR -S Terminate if an error occurs while executing the commands to bring a target up-to-date. This is the default and the opposite of .CR -k. If both .CR -k and .CR -S are specified, the last one given is used. This enables overriding the presence of the .CR k flag in the .CR MAKEFLAGS environment variable. .TP .CR -t Touch the target files (causing them to be up-to-date) rather than issue the usual commands. .TP .RC [\f2macro_name\fP= \f2value\f1] Zero or more command line macro definitions can be specified. See the Macros section. .TP .RI [ names ] Zero or more target names that appear in the makefile. Each target so specified is updated by .CR make . If no names are specified, .CR make updates the first target in the makefile that is not an inference rule. .SS Environment All variables defined in the environment (see .IR environ (5)) are read by .CR make and are treated and processed as macro definitions, with the exception of the .CR SHELL environment variable which is always ignored. .CR make automatically sets .CR SHELL to .CR /usr/bin/sh . Variables with no definition or empty string definitions are included by .CR make . .PP There are four possible sources of macro definitions which are read in the following order: internal (default), current environment, the makefile(s), and command line. Because of this order of processing, macro assignments in a makefile override environment variables. The .CR -e option allows the environment to override the macro assignments in a makefile. Command-line macro definitions always override any other definitions. .PP The .CR MAKEFLAGS environment variable is processed by .CR make on the assumption that it contains any legal input option (except .CR -f , .CR -p , and .CR -d ) defined for the command line. The .CR MAKEFLAGS variable can also be specified in the makefile. .PP (XPG4 only. .CR MAKEFLAGS in the makefile replaces the .CR MAKEFLAGS environment variable. Command line options have precedence over .CR MAKEFLAGS environment variable.) .PP If .CR MAKEFLAGS is not defined in either of these places, .CR make constructs the variable for itself, puts the options specified on the command line and any default options into it, and passes it on to invocations of commands. Thus, .CR MAKEFLAGS always contains the current input options. This proves very useful for recursive .CR make s. Even when the .CR -n option is specified, command lines containing the string .CR $(MAKE) or .CR ${MAKE} are executed; hence, one can perform a .C make -n recursively on an entire software system to see what would have been executed. This is possible because the .CR -n is put into .CR MAKEFLAGS and passed to the recursive invocations of .CR $(MAKE) or .CR ${MAKE} . This is one way of debugging all of the makefiles for a software project without actually executing any of the commands. .PP Each of the commands in the rules is given to a shell to be executed. The shell used is the shell command interpreter (see .IR sh (1)), or the one specified in the makefile by the .CR SHELL macro. To ensure the same shell is used each time a makefile is executed, the line: .IP .CR SHELL=/usr/bin/sh .PP or a suitable equivalent should be put in the macro definition section of the makefile. .SS Suffixes Target and/or dependent names often have suffixes. Knowledge about certain suffixes is built into .CR make and used to identify appropriate inference rules to be applied to update a target (see the section on Inference Rules). The current default list of suffixes is: .IP .C ".o .c .c~ .C .C~ .cxx .cxx~ .cpp .cpp~ .cc .cc~" .br .C ".y .y~ .l .l~ .s .s~ .sh .sh~" .br .C ".h .h~ .H .H~ .p .p~ .f .f~ .r .r~" .PP These suffixes are defined as the dependents of the special built-in target .CR .SUFFIXES . This is done automatically by .CR make . .PP Additional suffixes can be specified in a makefile as the dependents list for .CR .SUFFIXES . These additional values are added to the default values. Multiple suffix lists accumulate. The order of the suffix list is significant (see the Inference Rules section). If the user wishes to change the order of the suffixes, he must first define .CR .SUFFIXES with a null dependent list, which clears the current value for .CR .SUFFIXES , and then define .CR .SUFFIXES with the suffixes in the desired order. The list of suffixes built into .CR make on any machine can be displayed by: .IP .C make -fp - 2>/dev/null /dev/null /dev/null >>>>>> file3 .PP If there are overlaps, edit the result in .I file1 and delete one of the alternatives. .PP This command is particularly useful for revision control, especially if .I file1 and .I file3 are the ends of two branches that have .I file2 as a common ancestor. .SH EXAMPLES A typical use for .C merge is as follows: .RS .TP 5 1. To merge an .SM RCS branch into the trunk, first check out the three different versions from .SM RCS (see .IR co (1)) and rename them for their revision numbers: 5.2, 5.11, and 5.2.3.3. File 5.2.3.3 is the end of an .SM RCS branch that split off the trunk at file 5.2. .TP 2. For this example, assume file 5.11 is the latest version on the trunk, and is also a revision of the "original" file, 5.2. Merge the branch into the trunk with the command: .RS .IP .C merge 5.11 5.2 5.2.3.3 .RE .TP 3. File 5.11 now contains all changes made on the branch and the trunk, and has markings in the file to show all overlapping changes. .TP 4. Edit file 5.11 to correct the overlaps, then use the .C ci command to check the file back in (see .IR ci (1)). .SH WARNINGS .C merge uses the .IR ed (1) system editor. Therefore, the file size limits of .IR ed (1) apply to .CR merge . .SH AUTHOR .C merge was developed by Walter F. Tichy. .SH SEE ALSO diff3(1), diff(1), rcsmerge(1), co(1). .\" .\" index@\f4merge\f1 \- three-way file merge@@@\f3merge(1)\f1 .\" index@files: three-way file merge@@@\f3merge(1)\f1 .\" index@three-way file merge@@@\f3merge(1)\f1 .\" .\" toc@\f3merge(1)\f1:\0\0\f4merge\f1@@@three-way file merge .\" .\" fileset_database@merge.1 USER-CMDS-MAN .\" $Header: mesg.1,v 76.2 95/08/03 18:28:48 ssa Exp $ .TA m .TH mesg 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mesg \- permit or deny messages to terminal .SH SYNOPSIS .C mesg n .br .C mesg y .br .C mesg g .br .C mesg .SH DESCRIPTION The command form .C mesg n forbids messages via .C write by revoking non-user write permission on the user's terminal (see .IR write (1)). The command form .C mesg g reinstates permissions so that only legitimate commands (such as .IR write (1)) can be used by other users to send messages. .C mesg y allows any application to send messages to the user's terminal (that is, without restrictions). .C mesg without any other argument reports the current state without changing it. .SH RETURN VALUE .C mesg returns the following values: .RS .TP 5 .B 0 Messages are receivable. .PD 0 .TP .B 1 Messages are not receivable. .TP .B 2 An error occurred. .PD .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C mesg behaves as if all internationalization variables are set to "C". See .IR environ (5). .SH FILES .C /dev/tty* .SH SEE ALSO write(1). .SH STANDARDS CONFORMANCE .CR mesg ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" toc@\f3mesg(1)\f1:\0\0\f4mesg\f1@@@permit or deny messages to terminal .\" .\" index@\f4mesg\f1 \- permit or deny \f4write\f1(1) messages from other users to terminal@@@\f3mesg(1)\f1 .\" index@permit or deny \f4write\f1(1) messages from other users to terminal@@@\f3mesg(1)\f1 .\" index@deny or permit \f4write\f1(1) messages from other users to terminal@@@\f3mesg(1)\f1 .\" index@\f4write\f1(1) messages from other users to terminal, deny or permit@@@\f3mesg(1)\f1 .\" index@\f1messages from other users to terminal, deny or permit \f4write\f1(1)@@@\f3mesg(1)\f1 .\" index@\f1incoming messages from other users to terminal, deny or permit \f4write\f1(1)@@@\f3mesg(1)\f1 .\" index@\f1terminal, deny or permit \f4write\f1(1) messages from other users to@@@\f3mesg(1)\f1 .\" .\" $Header: mkdir.1,v 76.1 95/08/07 11:39:08 ssa Exp $ .TA m .TH mkdir 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mkdir \- make a directory .SH SYNOPSIS .C mkdir .RC [ -p ] .RC [ -m .IR mode\| ] .IR dirname \0... .SH DESCRIPTION .C mkdir creates specified directories in mode 0777 (possibly altered by .C umask unless specified otherwise by a .CI -m \0mode option (see .IR umask (1)). Standard entries, .C . (for the directory itself) and .C .. (for its parent) are created automatically. If .I dirname already exists, .C mkdir exits with a diagnostic message, and the directory is not changed. .SS Options .C mkdir recognizes the following command-line options: .RS .TP 15 .CI -m \0mode After creating the directory as specified, the file permissions are set to .IR mode , which is a symbolic mode string as defined for .C chmod (see .IR chmod (1)). The .C umask(1) has precedence over .CR -m . .TP .C -p Intermediate directories are created as necessary. Otherwise, the full path prefix of .I dirname must already exist. .C mkdir requires write permission in the parent directory. .IP For each directory name in the pathname prefix of the .I dirname argument that is not the name of an existing directory, the specified directory is created using the current .C umask setting, except that the equivalent of .C chmod u+wx is done on each component to ensure that .C mkdir can create lower directories regardless of the setting of .CR umask . Each directory name in the pathname prefix of the .I dirname argument that matches an existing directory is ignored without error. If an intermediate path component exists, but has permissions set to prevent writing or searching, .C mkdir fails with an error message. If the .I dirname argument (including pathname prefix) names an existing directory, .C mkdir fails with an error message. .IP If the .C -m option is used, the directory specified by .I dirname (excluding directories in the pathname prefix) is created with the permissions specified by .IR mode . .RE .PP Only .C LINK_MAX subdirectories can be created (see .IR limits (5)). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C mkdir will behave as if all internationalization variables are set to "C". See .IR environ (5). .PP .C LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .PP .C LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .C LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .C NLSPATH determines the location of message catalogues for the processing of .C LC_MESSAGES. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS .C mkdir returns exit code 0 if all directories were successfully made. Otherwise, it prints a diagnostic and returns non-zero. .SH EXAMPLES Create directory .C gem beneath existing directory .C raw in the current directory: .IP .C mkdir raw/gem .PP Create directory path .C raw/gem/diamond underneath the current directory and set permissions on directory .C diamond to read-only for all users .RC ( a=r ): .IP .C mkdir -p -m """a=r""" raw/gem/diamond .PP which is equivalent to (see .IR chmod (1)): .IP .C mkdir -p -m 444 raw/gem/diamond .PP If directories .C raw or .C raw and .C gem already exist, only the missing directories in the specified path are created. .SH SEE ALSO rm(1), sh(1), umask(1). .SH STANDARDS CONFORMANCE .CR mkdir ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4mkdir\f1 \- make a directory@@@\f3mkdir(1)\f1 .\" index@make a directory@@@\f3mkdir(1)\f1 .\" index@create a directory@@@\f3mkdir(1)\f1 .\" index@directory: create a directory@@@\f3mkdir(1)\f1 .\" .\" toc@\f3mkdir(1)\f1:\0\0\f4mkdir\f1@@@make a directory .\" .\" $Header: mkfifo.1,v 76.1 95/08/23 17:57:33 ssa Exp $ .TA m .TH mkfifo 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mkfifo \- make \s-1FIFO\s+1 (named pipe) special files .SH SYNOPSIS .C mkfifo .RC [ -p ] .RC [ -m .IR mode\| ] .IR filename " ..." .SH DESCRIPTION .C mkfifo creates the .SM FIFO special files named by its operand list. The operands are taken sequentially in the order specified and, if the user has write permission in the appropriate directory, the .SM FIFO is created with permissions 0666 modified by the user's file mode creation mask (see .IR umask (2)). .PP The specific actions performed are equivalent to calling .IP .CI "mkfifo(" filename ", 0666)" .PP for each filename in the operand list (see .IR mkfifo (2)). .SS Options .C mkfifo recognizes the following command-line options: .RS .TP 15 .CI -m " mode" After creating the .SM FIFO special file, set the permission bits of the new file to the specified .I mode value. The .I mode option argument is a symbolic mode string as defined in .IR chmod (1). .PP (XPG4 Only.) In the symbolic mode strings, the operators .CR + and .CR - will be interpreted relative to an initial mode of a=rw. .TP .C -p Create any missing intermediate path name components. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .C LC_ALL determines the locale to use to override any values for locale categories specified by the settings of .C LANG or any environment variables beginning with .CR LC_ . .PP .C LC_CTYPE determines the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments). .PP If any internationalization variable contains an invalid setting, .C mkfifo behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte character code sets are supported. .SH RETURN VALUE .C mkfifo returns zero if invoked with at least one operand and if all .SM FIFO special files were created successfully. Otherwise, it prints a diagnostic message and returns non-zero. .SH EXAMPLES The following command creates a .SM FIFO special file named .C peacepipe in the current directory: .IP .C mkfifo peacepipe .SH SEE ALSO chmod(1), umask(1), mknod(1M), mkfifo(3C). .SH STANDARDS CONFORMANCE .CR mkfifo ": XPG3, XPG4, POSIX.2" .\" .\" toc@\f3mkfifo(1)\f1:\0\0\f4mkfifo\f1@@@make FIFO (named pipe) special files .\" .\" index@\f4mkfifo\f1 \- make FIFO (named pipe) special files@@@\f3mkfifo(1)\f1 .\" index@\f1make FIFO (named pipe) special files@@@\f3mkfifo(1)\f1 .\" index@\f1FIFO (named pipe) special files, make@@@\f3mkfifo(1)\f1 .\" index@\f1(named pipe) special files, make FIFO@@@\f3mkfifo(1)\f1 .\" index@\f1special files, make FIFO (named pipe)@@@\f3mkfifo(1)\f1 .\" .\" $XConsortium: mkfontdir.man /main/12 1995/12/15 14:00:50 gildea $ .\" Copyright (c) 1993, 1994 X Consortium .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the .\" "Software"), to deal in the Software without restriction, including .\" without limitation the rights to use, copy, modify, merge, publish, .\" distribute, sublicense, and/or sell copies of the Software, and to .\" permit persons to whom the Software is furnished to do so, subject to .\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included .\" in all copies or substantial portions of the Software. .\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR .\" OTHER DEALINGS IN THE SOFTWARE. .\" .\" Except as contained in this notice, the name of the X Consortium shall .\" not be used in advertising or otherwise to promote the sale, use or .\" other dealings in this Software without prior written authorization .\" from the X Consortium. .TH MKFONTDIR 1 "Release 6.1" "X Version 11" .SH NAME mkfontdir, fonts.dir, fonts.scale, fonts.alias \- create an index of X font files in a directory .SH SYNOPSIS .B "mkfontdir" [\fIdirectory-name\fP .\|.\|. ] .SH DESCRIPTION For each directory argument, \fImkfontdir\fP reads all of the font files in the directory searching for properties named "FONT", or (failing that) the name of the file stripped of its suffix. These are converted to lower case and used as font names, and, along with the name of the font file, are written out to the file "fonts.dir" in the directory. The X server and font server use "fonts.dir" to find font files. .PP The kinds of font files read by \fImkfontdir\fP depend on configuration parameters, but typically include PCF (suffix ".pcf"), SNF (suffix ".snf") and BDF (suffix ".bdf"). If a font exists in multiple formats, .I mkfontdir will first choose PCF, then SNF and finally BDF. .PP The first line of fonts.dir gives the number of fonts in the file. The remaining lines list the fonts themselves, one per line, in two fields. First is the name of the font file, followed by a space and the name of the font. .SH "SCALABLE FONTS" Because scalable font files do not usually include the X font name, the file "fonts.scale" can be used to name the scalable fonts in the directory. The fonts listed in it are copied to fonts.dir by \fImkfontdir\fP. "fonts.scale" has the same format as the "fonts.dir" file. .SH "FONT NAME ALIASES" The file "fonts.alias", which can be put in any directory of the font-path, is used to map new names to existing fonts, and should be edited by hand. The format is two white-space separated columns, the first containing aliases and the second containing font-name patterns. Lines beginning with "!" are comment lines and are ignored. .PP If neither the alias nor the value specifies the size fields of the font name, this is a scalable alias. A font name of any size that matches this alias will be mapped to the same size of the font that the alias resolves to. .PP When a font alias is used, the name it references is searched for in the normal manner, looking through each font directory in turn. This means that the aliases need not mention fonts in the same directory as the alias file. .PP To embed white space in either name, simply enclose it in double-quote marks; to embed double-quote marks (or any other character), precede them with back-slash: .PP .nf "magic-alias with spaces" "\\"font name\\" with quotes" regular-alias fixed .fi .PP If the string "FILE_NAMES_ALIASES" stands alone on a line, each file-name in the directory (stripped of its suffix) will be used as an alias for that font. .SH FILES .TP 15 .B fonts.dir List of fonts in the directory and the files they are stored in. Created by \fImkfontdir\fP. Read by the X server and font server each time the font path is set (see xset(1)). .TP 15 .B fonts.scale List of scalable fonts in the directory. Contents are copied to fonts.dir by \fImkfontdir\fP. .TP 15 .B fonts.alias List of font name aliases. Read by the X server and font server each time the font path is set (see xset(1)). .SH "SEE ALSO" X(1), Xserver(1), xfs(1), xset(1) .\" $Header: mkmf.1,v 72.5 94/11/02 11:47:40 ssa Exp $ .TA m .TH mkmf 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mkmf \- make a makefile .SH SYNOPSIS .C mkmf .RC [ -acdeil\| ] .RC [ -f .IR makefile\| ] .RC [ -F .IR template\| ] .RC [ -M .IR language\| ] .RI [ \|macroname\f3=\fPvalue \ \|...\|] .SH DESCRIPTION The .CR mkmf command creates a makefile that informs the .CR make command how to construct and maintain programs and libraries (see .IR make (1)). After gathering up all source code file names in the current working directory and inserting them into the makefile, .CR mkmf scans source code files for included files and generates dependency information that is appended to the makefile. Source code files are identified by their file name suffixes. .CR mkmf recognizes the following suffixes: .RS .TP 8 .C .c C .PD 0 .TP .C .C C+\h'-.1v'+ .TP .C .f F\s-2ORTRAN\s0 .TP .C .h Include files .TP .C .i Pascal include files .TP .C .l Lex or Lisp .TP .C .o Object files .TP .C .p Pascal .TP .C .r Ratfor .TP .C .s Assembler .TP .C .y Yacc .PD .RE .PP The .CR mkmf command checks for an existing makefile before creating one. If no .CR -f option is present, .CR mkmf tries the makefiles .CR makefile and .CR Makefile , respectively. .PP After the makefile has been created, arbitrary changes can be made using a text editor. .CR mkmf can also be used to re-edit the macro definitions in the makefile, regardless of changes that may have been made since it was created. .PP By default, .CR mkmf creates a program makefile. To create a makefile that handles libraries, the .CR -l option must be used. .PP .SS Make Requests Given a makefile created by .CR mkmf , .CR make recognizes the following requests: .RS .TP 12 .C all Compile and load a program or library. .TP .C clean Remove all object and core files. .TP .C clobber Remove all files that can be regenerated. .TP .C depend Update included file dependencies in a makefile. .TP .C echo List the names of the source code files on standard output. .TP .C extract Extract all object files from the library and place them in the same directory as the source code files. The library is not altered. .TP .C index Print an index of functions on standard output. .TP .C install Compile and load the program or library and move it to its destination directory. .TP .C print Print source code files on standard output. .TP .C tags Create a tags file for the .CR ex editor (see .IR ex (1) and .IR ctags (1)), for C, Pascal, and Fortran source code files. .TP .C update Recompile only if there are source code files that are newer than the program or library, link and install the program or library. .RE .PP Several requests can be given simultaneously. For example, to (1) compile and link a program, (2) move the program to its destination directory, and (3) remove any unnecessary object files, use: .IP .C make install clean .SS Macro Definitions .C mkmf understands the following macro definitions: .RS .TP 15 .C CFLAGS C compiler flags. After searching for included files in the directory currently being processed, .CR mkmf searches in directories named in .CR -I compiler options and then in the .CR /usr/include directory. .TP .C COMPILESYSTYPE Location of .CR /usr/include . If the .CR COMPILESYSTYPE macro or environment variable is defined, .CR mkmf searches for included files in .CR /$COMPILESYSTYPE/usr/include instead of .CR /usr/include . .TP .C CXXFLAGS C+\h'-.1v'+ compiler flags. After searching for included files in the directory currently being processed, .CR mkmf searches in directories named in .CR -I compiler options and then in the .CR /usr/include/CC directory, followed by the .CR /usr/include directory. .TP .C DEST Directory where the program or library is to be installed. .TP .C EXTHDRS List of included files external to the current directory. .CR mkmf automatically updates this macro definition in the makefile if dependency information is being generated. .TP .C FFLAGS Fortran compiler flags. After searching for included files in the directory currently being processed, .CR mkmf searches in directories named in .CR -I compiler options, then in the .CR /usr/include directory. .TP .C HDRS List of included files in the current directory. .CR mkmf automatically updates this macro definition in the makefile. .TP .CR INSTALL Installation program name. .TP .CR LD Link editor name. .TP .C LDFLAGS Link editor flags. .TP .C LIBRARY Library name. This macro also implies the .CR -l option. .TP .C LIBS List of libraries needed by the link editor to resolve external references. .TP .C MAKEFILE Makefile name. .TP .C OBJS List of object files. .CR mkmf automatically updates this macro definition in the makefile. .TP .C PROGRAM Program name. .TP .C SRCS List of source code files. .CR mkmf automatically updates this macro definition in the makefile. .TP .C SUFFIX List of additional file name suffixes for .CR mkmf to know about. .TP .C SYSHDRS List of included files found in the .CR /usr/include directory hierarchy. .CR mkmf automatically updates this macro definition in the makefile if dependency information is being generated. If .CR SYSHDRS is omitted from the makefile, .CR mkmf does not generate .CR /usr/include dependencies. .RE .PP Both these and any other macro definitions already within the makefile can be replaced by definitions on the command line in the form .IC macroname = value\f1. For example, to change the C compiler flags and the program name, type the following line: .IP .ift \f4\s+1mkmf "CFLAGS=-I../include -O" PROGRAM=mkmf\f1\s0 .ifn \f3mkmf "CFLAGS=-I../include -O" PROGRAM=mkmf\f1 .PP Note that macro definitions such as .CR CFLAGS with blanks in them must be enclosed in double quote (\f3"\f1) marks. .SS Environment The environment is read by .CR mkmf . All variables are assumed to be macro definitions with the exception of .CR HDRS , .CR EXTHDRS , .CR SRCS , and .CR OBJS . Environment variables are processed after command line macro definitions and the macro definitions in a .IR makefile . The .CR -e option forces the environment to override the macro definitions in a .IR makefile . .SS File Name Suffixes .CR mkmf can recognize additional file name suffixes, or ignore ones that it already recognizes, by specifying suffix descriptions in the .CR SUFFIX macro definition. Each suffix description takes the form .CI . suffix : tI where .I t is a character indicating the contents of the file .RC ( \|s = source file, .CR o = object file, .CR h = header file, .CR x = executable file) and .I I is an optional character indicating the include syntax for header files .RC ( C = C syntax, .C C++ = C syntax plus the addition of .CR /usr/include/CC as a standard search directory, .CR F = Fortran and Ratfor syntax, .CR P = Pascal syntax). The following list shows the default configuration for .CR mkmf: .RS .TP 12 .C .c:sC C .PD 0 .TP .C .C:sC++ C+\h'-.1v'+ .TP .C .f:sF Fortran .TP .C .h:h Include files .TP .C .i:h Pascal include files .TP .C .l:sC Lex or Lisp .TP .C .o:o Object files .TP .C .p:sP Pascal .TP .C .r:sF Ratfor .TP .C .s:s Assembler .TP .C .y:sC Yacc .PD .RE .PP For example, to change the object file suffix to .CR .obj , undefine the Pascal include file suffix, and prevent Fortran files from being scanned for included files, the .CR SUFFIX macro definition could be: .IP .C "SUFFIX = .obj:o .i: .f:s" .SS Include Statement Syntax The syntax of include statements for C, C+\h'-.1v'+, Fortran, and Pascal source code are of the form: .RS .TP 10 .B \C/C+\h'-.1v'+: .br .C #include """\f2\s-1filename\s0\fP""" .br .CI #include \0filename .IP where .CR # must be the first character in the line. .TP .B Fortran: .br .CI "$include '\0 filename '$ .br .CI "$INCLUDE '\0 filename '$ .IP where .CR $ must be the first character in the line. Alternatively, the .CR $ can be omitted if the include statement starts in column 7. In either case the trailing .CR $ can be omitted. .TP .B Pascal: .br .CI "$include '\0 filename '$ .br .br .CI "$INCLUDE '\0 filename '$ .br .IP where .CR $ must be the first character in the line and the trailing .C $ is optional. .RE .SS User-defined Templates If .CR mkmf cannot find a makefile within the current directory, it normally uses one of the standard makefile templates, .CR C.p or .CR C.l , in .CR /usr/ccs/lib/mf unless the user has alternative .CR C.p or .CR C.l template files in a directory .CR $PROJECT/lib/mf where .CR $PROJECT is the absolute path name of the directory assigned to the .CR PROJECT environment variable. .SS Options .C mkmf recognizes the following options: .RS .TP 15 .C -a Include source files beginning with a .CR . in the makefile. .TP .CR -c Suppress ``\c .CR creating .I makefile .CR from \0...'' message. .TP .CR -d Turn off scanning of source code for .CR include files. Old dependency information is left untouched in the makefile. .TP .CR -e Environment variables override macro definitions within .IR makefile s. .TP .CI -f \0makefile Specify an alternative .I makefile file name. The default file name is .CR Makefile . .TP .CR -i Prompt the user for the name of the program or library and the directory where it is to be installed. If a carriage-return is typed in response to each of these queries, .CR mkmf assumes that the default program name is .CR a.out or the default library name is .CR lib.a , and the destination directory is the current directory. .TP .CR -l Force the makefile to be a library makefile. .TP .CI -F \0template Specify an alternative makefile template path name. The path name can be relative or absolute. .TP .CI -M \0language Specify an alternative .IR language -specific makefile template. The default language is C and the corresponding program and library makefile templates are .CR C.p and .CR C.l , respectively. .CR mkmf looks for these templates in .CR /usr/ccs/lib/mf or .CR $PROJECT/lib/mf . .RE .SH DIAGNOSTICS Exit status 0 is normal. Exit status 1 indicates an error. .SH WARNINGS The name of the makefile is included as a macro definition within the makefile and must be changed if the makefile is renamed. .PP Since executable files are dependent on libraries, standard library abbreviations must be expanded to full path names within the .CR LIBS macro definition in the makefile. .PP Generated dependency information appears after a line in the makefile beginning with .CR ### . This line must not be removed, nor must any other information be inserted in the makefile below this line. .PP The name of a program or library must not conflict with any predefined target names in a makefile. It is especially important to avoid the the name .CR update to prevent .CR make from recursively executing itself an infinite number of times. .SH AUTHOR .CR mkmf was developed by the University of California, Berkeley. .SH FILES .TP 35 .C /usr/ccs/lib/mf/C.p Standard program makefile template .PD 0 .TP .C /usr/ccs/lib/mf/C.l Standard library makefile template .TP .C $PROJECT/lib/mf/C.p User-defined program makefile template .TP .C $PROJECT/lib/mf/C.l User-defined library makefile template .PD .SH SEE ALSO ar(1), ctags(1), ld(1), make(1). .PP "Automatic Generation of Make Dependencies", \f2Software\-Practice and Experience\fP, Walden, K., vol. 14, no. 6, pp. 575-585, June 1984. .\" .\" index@\f4mkmf\f1 \- make a makefile@@@\f3mkmf(1)\f1 .\" index@make a makefile@@@\f3mkmf(1)\f1 .\" index@build a makefile@@@\f3mkmf(1)\f1 .\" index@create a makefile@@@\f3mkmf(1)\f1 .\" index@makefile, create a@@@\f3mkmf(1)\f1 .\" .\" toc@\f3mkmf(1)\f1:\0\0\f4mkmf\f1@@@make a makefile .\" .\" fileset_database@mkmf.1 USER-CMDS-MAN .\" $Header: mkmsgs.1,v 72.3 94/07/22 11:27:15 ssa Exp $ .TA m .TH mkmsgs 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mkmsgs \- create message files for use by gettxt() .SH SYNOPSIS .CR mkmsgs .RC [ -o ] .RC [ -i .IR locale ] .I textfile msgfile .SH DESCRIPTION The .CR mkmsgs command takes as input a file of localized text strings and generates a message file that can be accessed by the .IR gettxt (3C) routine. .IR textfile is the name of the file that contains the text strings. .I msgfile is the name of the output message file. .CR mkmsgs appends the suffix .CR .cat to the message file name. The combined length of the file name should be less than 14 bytes for short file name file system. The .I msgfile file should not contain a colon since it will confuse the formatting routines. .PP The .I textfile file contains the localized text strings. The text strings are separated by a newline character. The text strings are processed sequentially and copied to the .I msgfile message file. An empty line in the input results in a corresponding empty message written to the .I msgfile message file. .SS Options The .CR mkmsgs command supports the following options: .RS .TP 15 .CR -o Overwrite the .I msgfile message file if it exists. .TP .CI -i " locale" The .I msgfile message file is installed in the system-wide localization directory corresponding to the specified .IR locale . Only a user with the appropriate privileges can create or overwrite the message file in that directory. The directory will be created if it does not exist. .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_CTYPE determines the interpretation of messages as single- and/or multibyte characters. .PP Messages are issued in .CR LANG if it is set to a valid language and .CR LANG messages are available. Otherwise "C" locale messages are issued. .PP If .CR LC_CTYPE is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR mkmsgs behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH EXAMPLES The following example shows the format of the input text strings: .nf .IP .C global %s not found\en .C \en\en\en\en .C \et%s, %d, %d,typ = %d, disp = '%s'\en .fi .SH WARNINGS .CR mkmsgs is provided for SVID3 compatibility only. The user is encouraged to use the NLS mechanism developed by HP and the X/Open Company, Ltd. .SH SEE ALSO gencat(1), gettxt(3C), setlocale(3C). .SH STANDARDS COMPLIANCE .CR mkmsgs ": SVID3" .\" .\" toc@\f3mkmsgs(1)\f1:\0\0\f4mkmsgs\f1@@@create message files for use by gettxt()\f1 .\" .\" index@\f4mkmsgs\f1 \- create message files for use by gettxt()@@@\f3mkmsgs(1)\f1 .\" index@\f1create message files for use by gettxt()@@@\f3mkmsgs(1)\f1 .\" index@\f1message files, create for use by gettxt()@@@\f3mkmsgs(1)\f1 .\" index@\f1gettxt(), create message files for use by@@@\f3mkmsgs(1)\f1 .\" $Header: mkstr.1,v 72.3 93/01/14 11:36:47 ssa Exp $ .TA m .TH mkstr 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mkstr \- extract error messages from C source into a file .SH SYNOPSIS .C mkstr .RC [ - ] .IR "messagefile prefix file" \0... .SH DESCRIPTION .C mkstr examines a C program and creates a file containing error message strings used by the program. Programs with many error diagnostics can be made much smaller by referring to places in the file, and reduce system overhead in running the program. .PP .C mkstr processes each of the specified .IR file s, placing a revised version of each in a file whose name consists of the specified .I prefix concatenated in front of the original name. A typical usage of .I mkstr would be .IP .C mkstr mystrings xx *.c .PP This command would cause all the error messages from the C source files in the current directory to be placed in the file .I mystrings and revised copies of the source for these files to be placed in files whose names are prefixed with .I xx. .PP When processing the error messages in the source for transfer to the message file, .C mkstr searches for the string .C error( in the input file. Each time it is encountered, the C string starting after the leading quote is placed in the message file, followed by a null character and a new-line character. The null character terminates the message so that it can be easily used when retrieved, and the new-line character makes it possible to conveniently list the error message file (using .CR cat , .CR more , etc. \(em see .IR cat (1) and .IR more (1)) to review its contents. .PP The modified copy of the input file is identical to the original, except that each occurrence of any string that was moved to the error message file is replaced by an offset pointer usable by .C lseek to retrieve the message. .PP If the command line includes the optional .CR - , extracted error messages are placed at the end of the specified message file (append) instead of overwriting it. This enables you to process individual files that are part of larger programs that have been previously processed by .C mkstr without reprocessing all the files. .PP All functions used by the original program whose names end in "error" that also can take a constant string as their first argument should be rewritten so that they search for the string in the error message file. .PP For example, a program based on the previous example usage would resemble the following: .nf .IP .C #include .C #include .C #include .IP .C char errfile[] = """mystrings"""; .IP .C error(offset, a2, a3, a4) .C int offset, a1, a2, a3; .C { .C " char msg[256];" .C " static int fd = -1;" .IP .C " if (fd < 0) {" .C " fd = open(errfile, O_RDONLY);" .C " if (fd < 0) {" .C " perror(errfile);" .C " exit(1);" .C " }" .C " } .IP .C " if (lseek(fd, (off_t) offset, 0) |\|| read(fd, msg, 256) <= 0) {" .ifn \f3\0\0\0\0\0\0\0\0printf("? Can't find error message in %s:\en", errfile);\fP .ift \f4\s+1\0\0\0\0\0\0\0\0printf("? Can't find error message in %s:\en", errfile);\fP\s0 .C " perror(errfile); .C " exit(1); .C " }" .IP .C " printf(msg, a1, a2, a3);" .C } .fi .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of comments and string literals as single- and/or multi-byte characters. .PP If .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C mkstr behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported within file names, comments, and string literals. .SH SEE ALSO lseek(2), perror(3C), xstr(1). .SH BUGS Strings in calls to functions whose names end in .CR error , notably .CR perror() , may be replaced with offsets by .CR mkstr . .PP Calls to error functions whose first argument is not a string constant are left unmodified without warning. .\" .\" index@\f4mkstr\f1 \- extract error messages from C source into a file@@@\f3mkstr(1)\f1 .\" index@optimization \- extract error messages from C source into a file@@@\f3mkstr(1)\f1 .\" index@extract error messages from C source into a file@@@\f3mkstr(1)\f1 .\" index@error messages, extract from C source into a file@@@\f3mkstr(1)\f1 .\" index@messages, error, extract from C source into a file@@@\f3mkstr(1)\f1 .\" index@C source, extract error messages from into a file@@@\f3mkstr(1)\f1 .\" index@source, C, extract error messages from into a file@@@\f3mkstr(1)\f1 .\" index@error message file, extract error messages from C source into@@@\f3mkstr(1)\f1 .\" index@files: error message file, extract error messages from C source into@@@\f3mkstr(1)\f1 .\" .\" toc@\f3mkstr(1)\f1:\0\0\f4mkstr\f1@@@extract error messages from C source into a file .\" .\" fileset_database@mkstr.1 USER-CMDS-MAN .\" $Header: mktemp.1,v 72.3 93/01/14 11:27:33 ssa Exp $ .TA m .TH mktemp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mktemp \- make a name for a temporary file .SH SYNOPSIS .C mktemp .RC [ -c ] .RC [ -d .IR directory_name\| ] .RC [ -p .IR prefix\| ] .SH DESCRIPTION .C mktemp makes a name that is suitable for use as the pathname of a temporary file, and writes that name to the standard output. The name is chosen such that it does not duplicate the name of an existing file. If the .C -c option is specified, a zero-length file is created with the generated name. .PP The name generated by .C mktemp is the concatenation of a directory name, a slash .RC ( \|/\| ), the value of the .C LOGNAME environment variable truncated to .C {NAME_MAX} \(mi 6 characters, and the process .SM ID of the invoking process. .PP The directory name is chosen as follows: .RS .TP 5 1. If the .C -d option is specified, .I directory_name is used. .TP 2. Otherwise, if the .C TMPDIR environment variable is set and a string that would yield a unique name can be obtained by using the value of that variable as a directory name, this value is used. .TP 3. Otherwise, if a string that would yield a unique name can be obtained using .C /tmp as the directory, .C /tmp is used. .TP 4. Otherwise, .C . (current directory) is used. .RE .PP If the .C -p option is specified, .I prefix is used instead of the value of the .C LOGNAME environment variable for name generation. .SH RETURN VALUE .C mktemp returns zero on successful completion and non-zero if syntax, file access, or file creation errors were encountered or a unique pathname could not be generated. .SH SEE ALSO mktemp(3C), umask(1). .\" .\" toc@\f3mktemp(1)\f1:\0\0\f4mktemp\f1@@@make a name for a temporary file .\" .\" index@\f4mktemp\f1 \- make a name for a temporary file@@@\f3mktemp(1)\f1 .\" index@make a name for a temporary file@@@\f3mktemp(1)\f1 .\" index@files: name for a temporary file, make a@@@\f3mktemp(1)\f1 .\" index@files: temporary file, make a name for a@@@\f3mktemp(1)\f1 .\" index@name for a temporary file, make@@@\f3mktemp(1)\f1 .\" index@temporary file, make a name for a@@@\f3mktemp(1)\f1 .\" .\" fileset_database@mktemp.1 USER-CMDS-MAN .\" $Header: uupath.1,v 72.4 94/07/25 15:54:31 ssa Exp $ .TA u .TH uupath 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uupath, mkuupath \- access and manage the pathalias database .SH SYNOPSIS .C uupath .RC [ -f .IR pathsfile\| ] .I mailaddress .PP .C mkuupath .RC [ -v ] .I pathsfile .SH DESCRIPTION .C uupath provides electronic message routing by expanding a simple .SM UUCP address into a full .SM UUCP path (see .IR uucp (1)). For example, .IC host ! user could be expanded into .IC hostA ! hostB ! host\c .CI ! user\f1. .PP .C uupath expands an address by parsing .I mailaddress for the dominant host (see below) and looking up the host in the appropriate .C pathalias database (see .IR pathalias (1)). If the host is found in the database, the expanded address is written to the standard output. If the host is not found, .C uupath writes the original address to the standard output and returns an exit status of 1. .C uupath expects .I mailaddress to be in .SM UUCP format .RI ( host\c .CR ! ... !\c .IC hostZ ! user\f1) or .SM ARPANET format (\f2user\f3@\f2host\f1). .PP The .C -f option opens the .C pathalias database based on .I pathsfile rather than the default database based on .CR /usr/lib/mail/paths . This database must be a database created by .CR mkuupath , consisting of the two files .IC pathsfile .dir and .IC pathsfile .pag\f1. .PP The dominant host is the left-most .SM UUCP host in .IR mailaddress . If no .SM UUCP host is found (no .C ! is in the address), .C uupath assumes that the address is in the simple .SM ARPANET format \f2user\f3@\f2host\f1. If the address does not match either format, .C uupath writes the original address to the standard output and returns an exit status of 1. .PP .C mkuupath constructs a mail routing database by using the .I pathsfile data file obtained from .C pathalias (see .IR pathalias (1)). as input. The recommended .I pathsfile location is .CR /usr/lib/mail/paths , because this is the default database used by .CR uupath . The database files .IC pathsfile .dir and .IC pathsfile .pag are created by .CR mkuupath . If these files already exist, they must be removed prior to running .CR mkuupath . .PP The .C -v option specifies verbose mode, which writes a line to the standard output for each entry written to the database. .SH DIAGNOSTICS .C uupath returns an exit status of 1 and writes the original .I mailaddress to the standard output if the address is not found or is incorrectly formatted. .C uupath returns an exit status of 2 and prints a diagnostic message if the database files are not accessible, or if improper parameters are given. Otherwise, .C uupath returns an exit status of 0. .PP If the database files .IC pathsfile .dir and .IC pathsfile .pag already exist prior to running .CR mkuupath , the message .CI mkuupath: " pathsfile" ".dir: File exists" is displayed. These files must be removed before running .CR mkuupath . .SH AUTHOR .C uupath was developed by University of California, Berkeley. .SH FILES .nf .C /usr/lib/mail/paths .C /usr/lib/mail/paths.dir .C /usr/lib/mail/paths.pag .fi .SH SEE ALSO pathalias(1), uucp(1). .\" .\" index@\f4uupath\f1, \f4mkuupath\f1 \- access and manage the pathalias database@@@\f3uupath(1)\f1 .\" index@\f4mkuupath\f1, \f4uupath\f1 \- access and manage the pathalias database@@@\f3uupath(1)\f1 .\" index@access and manage the pathalias database@@@\f3uupath(1)\f1 .\" index@manage the pathalias database, access and@@@\f3uupath(1)\f1 .\" index@pathalias database, access and manage the@@@\f3uupath(1)\f1 .\" index@database, pathalias, access and manage the@@@\f3uupath(1)\f1 .\" .\" toc@\f3uupath(1)\f1:\0\0\f4uupath\f1, \f4mkuupath\f1@@@access and manage the pathalias database .\" toc@\f4mkuupath\f1: manage the pathalias database@@@see \f3uupath(1)\f1 .\" .\" links@uupath.1 mkuupath.1 .\" .\" fileset_database@uupath.1 USER-CMDS-MAN .\" $Header: mm.1,v 72.4 94/09/13 15:15:11 ssa Exp $ .TA m .TH mm 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mm, osdd \- print documents formatted with the mm macros .SH SYNOPSIS .C mm .RI [ \|options\| ] .RI [ \|files\| ] .PP .C osdd .RI [ \|options\| ] .RI [ \|files\| ] .SH DESCRIPTION .C mm can be used to format and print documents using .C nroff and the .C mm text-formatting macro package (see .IR nroff (1)). It has options to specify preprocessing by .C tbl and/or .CR neqn , (see .IR tbl (1) and .IR neqn (1)), and postprocessing by various terminal-oriented output filters. The proper pipelines and the required arguments and flags for .C nroff and .C mm are generated, depending on the options selected. .PP .C osdd is equivalent to the command .CR "mm -mosd" . .SS Options .C mm recognizes the following .I options and command-line arguments. Any other arguments or options (such as .CR -rC3 ) are passed to .C nroff or to .CR mm , as appropriate. Such options can occur in any order, but they must appear before the .I files arguments. If no arguments are given, .C mm prints a list of its options. .RS .TP 9 .CI -T term Specifies the type of output terminal; for a list of recognized values for .IR term , type .CR "help term2" . If this option is .I not used, .C mm uses the value of the shell variable .C $TERM from the environment (see .IR profile (4) and .IR environ (5)) as the value of .I term if .C $TERM is set; otherwise, .C mm uses .C 450 as the value of .IR term . If several terminal types are specified, the last one is used. .TP .C -12 Indicates that the document is to be produced in 12-pitch. Can be used when .C $TERM is set to one of .CR 300 , .CR 300s , .CR 450 , and .CR 1620 . (The pitch switch on the .SM DASI 300 and 300s terminals must be manually set to .C 12 if this option is used.) .TP .C -c Causes .C mm to invoke .IR col (1); note that .IR col (1) is invoked automatically by .C mm unless .I term is one of .CR 300 , .CR 300s , .CR 450 , .CR 37 , .CR 4000a , .CR 382 , .CR 4014 , .CR tek , .CR 1620 , and .CR X . .TP .C -e Causes .C mm to invoke .CR neqn . .TP .C -t Causes .C mm to invoke .CR tbl . .TP .C -E Invokes the .C -e option of .CR nroff . .RE .SH DIAGNOSTICS .C mm sends the message .C mm: no input file if none of the arguments is a readable file and .C mm is not used as a filter. .SH EXAMPLES Assuming that the shell variable .C $TERM is set in the environment to .CR 450 , the two command lines below are equivalent: .IP .C mm -t -rC3 -12 ghh* .br .C "tbl ghh* | nroff -cm -T450-12 -h -rC3 .PP .C mm reads the standard input when .C - is specified instead of any file names (mentioning other files along with .C - leads to disaster). This option allows .C mm to be used as a filter, as in this example: .IP .C "cat dws | mm -" .SS Hints .TP 3 \(bu .C mm invokes .C nroff with the .C -h option. With this option, .C nroff assumes that the terminal has tabs set every 8 character positions. .TP \(bu Use the .CI -o list option of .C nroff to specify ranges of pages to be output. Note, however, that .CR mm , if invoked with one or more of the .CR -e , .CR -t , and .C - options, .I together with the .CI -o list option of .C nroff may cause a harmless ``broken pipe'' diagnostic if the last page of the document is not specified in .IR list . .TP \(bu If you use the .C -s option of .C nroff (to stop between pages of output), use line-feed (rather than return or new-line) to restart the output. The .C -s option of .C nroff does not work with the .C -c option of .CR mm , or if .C mm automatically invokes .C col (see .C -c option above and .CR col (1)). .TP \(bu If you specify an incorrect output terminal type, .C mm produces (often subtle) unpredictable results. However, if you are redirecting output into a file, use the .C -T37 option, then use the appropriate terminal filter when actually printing the formatted file. .SH SEE ALSO col(1), env(1), nroff(1), tbl(1), profile(4), mm(5), term(5). .PP .C mm section in .I "Text Formatting: User's Guide" . .\" .\" index@\f4mm\f1 \- print or check documents formatted with the \f4mm\f1 macros@@@\f3mm(1)\f1 .\" index@\f4osdd\f1 \- print or check documents formatted with the \f4mm\f1 macros@@@\f3mm(1)\f1 .\" index@print or check documents formatted with the \f4mm\f1 macros@@@\f3mm(1)\f1 .\" index@check or print documents formatted with the \f4mm\f1 macros@@@\f3mm(1)\f1 .\" index@formatters: check or print documents formatted with the \f4mm\f1 macros@@@\f3mm(1)\f1 .\" index@documents, format and print using the \f4mm\f1 macros@@@\f3mm(1)\f1 .\" index@macros, check or print documents formatted using \f4mm\f1@@@\f3mm(1)\f1 .\" .\" toc@\f3mm(1)\f1:\0\0\f4mm\f1, \f4osdd\f1@@@print/check documents formatted with the mm macros .\" toc@\f4osdd\f1:\0\0print/check documents formatted with the mm macros@@@\f1see \f3mm(1)\f1 .\" .\" links@mm.1 osdd.1 .\" $Header: model.1,v 72.2 94/09/21 09:29:39 ssa Exp $ .TA m .TH model 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME model \- print detailed hardware model information .SH SYNOPSIS .C model .PP .SH DESCRIPTION .C model prints the machine hardware model. Its output is similar to that of .C uname -m with possible additional information. There are several systems for which .C uname -m returns the same value. The .IR model (1) command can be used to distinguish between the different systems. .SH EXAMPLES Executing the command .C model produces output resembling the following: .IP .C "9000/715/50" .PP This example indicates an .SM HP\|\c 9000 Model 715 with a 50 MHz clock. .RE .SH SEE ALSO uname(1) .\" .\" index@\f4model\f1 \- print name of current \s-1HP-UX\s+1 version@@@\f3model(1)\f1 .\" index@print name of current \s-1HP-UX\s+1 model@@@\f3model(1)\f1 .\" index@name of current \s-1HP-UX\s+1 model, print@@@\f3model(1)\f1 .\" index@name of current \s-1HP-UX\s+1 model, print@@@\f3model(1)\f1 .\" index@current \s-1HP-UX\s+1 model, print name of@@@\f3model(1)\f1 .\" index@\s-1HP-UX\s+1 model, print name of current@@@\f3model(1)\f1 .\" index@model, print name of current \s-1HP-UX\s+1@@@\f3model(1)\f1 .\" .\" toc@\f3model(1)\f1:\0\0\f4model\f1 print name of current \s-1HP-UX\s+1 version .\" $Header: more.1,v 76.1 95/08/04 15:38:26 ssa Exp $ .TA m .TH more 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME more, page \- file perusal filter for crt viewing .SH SYNOPSIS .C more .RC[ -n ] .RC[ -cdefisuvz ] .RC[ -n .IR number\| ] .RC[ -p .IR command\| ] .RC[ -t .IR tagstring\| ] .RC[ -x .IR tabs\| ] .RC[ -W .IR option\| ] .RC[ +\c .IR linenumber\| ] .RC[ +/\c .IR pattern\| ] .RI [ \|name " ...\|]" .PP .C page .RC[ -n ] .RC[ -cdefisuvz ] .RC[ -n .IR number\| ] .RC[ -p .IR command\| ] .RC[ -t .IR tagstring\| ] .RC[ -x .IR tabs\| ] .RC[ -W .IR option\| ] .RC[ +\c .IR linenumber\fP\| ] .RC[ +/\c .IR pattern\fP\| ] .RI [ \|name " ...\|]" .SH REMARKS: .C pg is preferred in some standards and has some added functionality, but does not support character highlighting (see .IR pg (1)). .SH DESCRIPTION .C more is a filter for examining continuous text, one screenful at a time, on a soft-copy terminal. It is quite similar to .CR pg , and is retained primarily for backward compatibility. .C more normally pauses after each screenful, printing the filename at the bottom of the screen. To display one more line, press .CI . To display another screenful press .CI . Other possibilities are described later. .PP .C more and .C page differ only slightly. .C more scrolls the screen upward as it prints the next page. .C page clears the screen and prints a new screenful of text when it prints a new page. Both provide one line of overlap between screenfuls. .PP .I name can be a filename or .CR - , specifying standard input. .C more processes file arguments in the order given. .PP .C more supports the Basic Regular Expression syntax (see .IR regexp (5)). .PP .C more recognizes the following command line options: .RS .TP 15 .CI -n \0number Set the number of lines in the display window to .I number, a positive decimal integer. The default is one line less than the the number of lines displayed by the terminal; on a screen that displays 24 lines, the default is 23. The .CI -n flag overrides any values obtained from the environment. .TP .CI - n Same as .CI -n \0number except that the number of lines is set to .I n. .TP .C -c Draw each page by beginning at the top of the screen, and erase each line just before drawing on it. This avoids scrolling the screen, making it easier to read while .C more is writing. This option is ignored if the terminal has no clear-to-end-of-line capability. .TP .C -d Prompt user with the message .C "Press space to continue, q to quit, h for help" at the end of each screenful. This is useful if .C more is being used as a filter in some setting, such as a training class, where many users might be unsophisticated. .TP .C -e Exit immediately after writing the last line of the last file in the argument list .TP .C -f Count logical lines, rather than screen lines. That is, long lines are not folded. This option is recommended if .I nroff output is being piped through .IR ul , since the latter can generate escape sequences. These escape sequences contain characters that would ordinarily occupy screen positions, but which do not print when sent to the terminal as part of an escape sequence. Thus .C more might assume lines are longer than they really are, and fold lines erroneously. .TP .C -i Perform pattern matching in searches without regard to case. .TP .C -s Squeeze multiple blank lines from the output, producing only one blank line. Especially helpful when viewing .I nroff output, this option maximizes the useful information present on the screen. .TP .C -u Normally, .C more handles underlining and bold such as produced by .I nroff in a manner appropriate to the particular terminal: if the terminal supports underlining or has a highlighting (usually inverse-video) mode, .C more outputs appropriate escape sequences to enable underlining, else highlighting mode, for underlined information in the source file. If the terminal supports highlighting, .C more uses that mode information that should be printed in boldface type. The .C -u option suppresses this processing, as do the "ul" and "os" terminfo flags. .TP .C -v Do not display nonprinting characters graphically; by default, all non-ASCII and control characters (except .CI , .CI , and .CI ) are displayed visibly in the form .CI ^X for .CI , or .CI M-x for non-ASCII character .CI x . .TP .C -z Same as not specifying .CI -v , with the exception of displaying .CI as .CI ^H , .CI as .CI ^M , and .CI as .CI ^I . .TP .CI -p \0command Execute the .C more command initially in the .IR command argument for each file examined. If the command is a positioning command, such as a line number or a regular expression search, sets the current position to represent the final results of the command, without writing any intermediate lines of the file. If the positioning command is unsuccessful, the first line in the file is the current position. .TP .CI -t \0tagstring Write the screenful of the file containing the tag named by the .IR tagstring argument. The specified tag appears in the current position. If both .C -p and .C -t options are specified, .C more processes .C -t first; that is, the file containing the .I tagstring is selected by .C -t and then the command is executed. .TP .CI -x \0tabs Set the tabstops every .IR tabs position. The default value for the .IR tabs argument is 8. .TP .CI -W \0option Provides optional extensions to the .C more command. Currently, the following two options are supported: .IP \0 15 .PD 0 .C notite .IP \0 20 Prevents .PD .C more from sending the terminal initialization string before displaying the file. This argument also prevents .C more from sending the terminal de-initialization string before exiting. .IP \0 15 .PD 0 .C tite .IP \0 20 Causes .PD .C more to send the initialization and de-initialization strings. This is the default. .TP .CI + linenumber Start listing such that the current position is set to .IR linenumber . .TP .CI +/ pattern Start listing such that the current position is set to the line matching the regular expression .IR pattern . .RE .PP The number of lines available per screen is determined by the .C -n option, if present or by examining values in the environment. The actual number of lines written is one less than this number, as the last line of the screen is used to write a user prompt and user input. .PP The number of columns available per line is determined by examining values in the environment. .C more writes lines containing more characters than would fit into this number of columns by breaking the line into one more logical lines where each of these lines but the last contains the number of characters needed to fill the columns. The logical lines are written independently of each other; that is, commands affecting a single line affect them separately. .PP While determining the number of lines and the number of columns, if the methods described above do not yield any number then .C more uses terminfo descriptor files (see .IR term (4)). If this also fails then the number of lines is set to 24 and the number of columns to 80. .PP When standard output is a terminal and .C -u is not specified, .C more treats backspace characters and carriage-return characters specially. .RS .TP 3 \(bu A character, followed first by a backspace character, then by an underscore (_), causes that character to be written as underlined text, if the terminal supports that. An underscore, followed first by a backspace character, then any character, also causes that character to be written as underlined text, if the terminal supports that. .TP 3 \(bu A backspace character that appears between two identical printable characters causes the first of those two characters to be written as emboldened text, if the terminal type supports that, and the second to be discarded. Immediately subsequent occurrences of backspaces/character pairs for that same character is also discarded. .TP 3 \(bu Other backspace character sequences is written directly to the terminal, which generally causes the character preceding the backspace character to be suppressed in the display. .TP 3 \(bu A carriage-return character at the end of a line is ignored, rather than being written as a control character. .RE .PP If the standard output is not a terminal device, .C more always exits when it reaches end-of-file on the last file in its argument list. Otherwise, for all files but the last, .C more prompts, with an indication that it has reached the end of file, along with the name of the next file. For the last file specified, or for the standard input if no file is specified, .C more prompts, indicating end-fo-file, and accept additional commands. If the next command specifies forward scrolling, .C more will exit. If the .C -e option is specified, .C more will exit immediately after writing the last line of the last file. .PP .C more uses the environment variable .SM .C MORE to preset any flags desired. The .C MORE variable thus sets a string containing flags and arguments, preceded with hyphens and blank-character-separated as on the command line. Any command-line flags or arguments are processed after those in the .C MORE variable, as if the command line were as follows: .PP .IP .C more $MORE .I flags arguments .PP For example, to view files using the .C -c mode of operation, the shell command sequence .IP .C "MORE='-c' ; export MORE" or the .I csh command .IP .C "setenv MORE -c" .PP causes all invocations of .CR more , including invocations by programs such as .I man and .IR msgs , to use this mode. The command sequence that sets up the .SM .C MORE environment variable is usually placed in the .I .profile or .I .cshrc file. .PP In the following descriptions, the .I current position refers to two things: .RS .TP 3 \(bu the position of the current line on the screen .TP 3 \(bu the line number (in the file) of the current line on the screen .RE .PP The line on the screen corresponding to the current position is the third line on the screen. If this is not possible (there are fewer than three lines to display or this is the first page of the file, or it is the last page of the file), then the current position is either the first or last line on the screen. .PP Other sequences that can be typed when .C more pauses, and their effects, are as follows .RI ( i is an optional integer argument, defaulting to 1): .RS .PP .PD 0 .IC i .PP .IR i\| j .PP .IC i .PP .TP 15 .PD .IC i Scroll forward .I i lines. The default .I i for .C is one screenful; for .C j and .C it is one line. The entire .I i lines are written, even if .I i is more than the screen size. At end-of-file, .C causes .C more to continue with the next file in the list, or exits if the current file is the last file in the list. .PP .PD 0 .IC i d .PP .TP 15 .PD .IC i Scroll forward .I i lines, with a default of one half of the screen size. If .I i is specified, it becomes the new default for subsequent .C d and .C u commands. .PP .PD 0 .IC i u .TP 15 .IC i .PD Scrolls backward .I i lines, with a default of one half of the screen size. If .I i is specified, it becomes the new default for subsequent .C d and .C u commands. .PP .PD 0 .IC i k .TP 15 .PD .IC i Scrolls backward .I i lines, with a default of one line. The entire .I i lines are written, even if .I i is more than the screen size. .TP .IC i z Display .I i more lines and sets the new window (screenful) size to .I i . .TP .IC i g Go to line .I i in the file, with a default of 1 (beginning of file). Scroll or rewrite the screen so that the line is at the current position. If .I i is not specified, then .C more displays the first screenful in the file. .TP .IC i G Go to line .I i in the file, with a default of the end of the file. If .I i is not specified, scrolls or rewrites screen so that the last line in the file is at the bottom of the screen. If .I i is specified, scrolls or rewrites the screen so that the line is at the current position. .TP .IC i s Skip forward .I i lines, with a default of 1, and write the next screenful beginning at that point. If .I i would cause the current position to be such that less than one screenful would be written, the last screenful in the file is written. .PP .PD 0 .IC i f .TP 15 .PD .IC i Move forward .I i lines, with a default of one screenful. At end-of-file, .C more will continue with the next file in the list, or exit if the current file is the last file in the list. .PP .PD 0 .IC i b .TP 15 .PD .IC i Move backward .I i lines, with a default of one screenful. If .I i is more than the screen size, only the final screenful will be written. .PP .PD 0 .CR q ", "Q ", .CR :q ", " :Q ", " .TP 15 .CR ZZ .PD Exit from .CR more . .PP .PD 0 .C = .PP .C :f .TP 15 .PD .C Write the name of the file currently being examined, the number relative to the total number of files there are to examine, the current line number, the current byte number, and the total bytes to write and what percentage of the file precedes the current position. All of these items reference the first byte of the line after the last line written. .TP .C v Invoke an editor to edit the current file being examined. The name of the editor is taken from the environment variable .CR EDITOR , or default to .CR vi . If .C EDITOR represents either .C vi or .CR ex , the editor is invoked with options such that the current editor line is the physical line corresponding to the current position in .C more at the time of the invocation. .PP .IP \| 15 When the editor exits, .C more resumes on the current file by rewriting the screen with the current line as the current position. .TP .C h Display a description of all the .C more commands. .TP .IC i\| / [ ! ] expression Search forward in the file for the .IR i -th line containing the regular expression .I expression. The default value for .I i is 1. The search starts at the line following the current position. If the search is successful, the screen is modified so that the searched-for line is in the current position. The null regular expression .RC ( / ) repeats the search using the previous regular expression. If the character .C ! is included, the lines for searching are those that do not contain .I expression. .PP .IP \| 15 If there are less than .I i occurrences of .I expression, and the input is a file rather than a pipe, then the position in the file remains unchanged. .PP .IP \| 15 The user's erase and kill characters can be used to edit the regular expression. Erasing back past the first column cancels the search command. .TP .IC i\| ? [ ! ] expression Same as .CR / , but searches backward in the file for the .I i th line containing the regular expression .I expression. .TP .IC i n Repeat the previous search for the .IR i -th line (default 1) containing the last .I expression (or not containing the last .I expression, if the previous search was .C /! or .CR ?! ). .TP .IC i N Repeat the search for the opposite direction of the previous search for the .IR i -th line (default 1) containing the last .I expression .TP .C \'\' (single quotes) Return to the position from which the last large movement command was executed ( "large movement" is defined as any movement of more than a screenful of lines). If no such movements have been made, return to the beginning of the file. .TP .CI ! command Invoke a shell with .IR command . The characters .C % and .C ! in .I command are replaced with the current file name and the previous shell command, respectively. If there is no current file name, .C % is not expanded. The sequences .C \e% and .C \e! are replaced by .C % and .C ! respectively. .PP .PD 0 .CI :e \0[file] .TP 15 .PD .CI E \0[file] Examine a new file. If the .I file argument is not specified, the "current" file (see the .C :n and .C :p commands) from the list of files in the command line is re-examined. The filename is subjected to the process of shell word expansions. If .I file is a .C # (number sign) character, the previously examined file is re-examined. .TP .IC i :n Examine the next file. If .I i is specified, examines the .IR i -th next file specified in the command line. .TP .IC i :p Examine the previous file. If a number .I i is specified, examines the .IR i -th previous file specified in the command line. .TP .CI :t \0tagstring Go to the supplied .I tagstring and scroll or rewrite the screen with that line in the current position. .TP .CI m \0letter Mark the current position with the specified letter, where .I letter represents the name of one of the lower-case letters of the portable character set. .TP .CI ' \0letter Return to the position that was previously marked with the specified .I letter, making that line the current position. .PP .PD 0 .C r .TP 15 .PD .C Refresh the screen. .TP .C R Refresh the screen, discarding any buffered input. .RE .PP The commands take effect immediately; i.e., it is not necessary to press .CR . Up to the time when the command character itself is given, the line-kill character can be used to cancel the numerical argument being formed. .PP If the standard output is not a teletype, .C more is equivalent to .IR cat (1). .PP .C more supports the .C SIGWINCH signal, and redraws the screen in response to window size changes. .SH EXTERNAL INFLUENCES .SS Environment Variables .TP 15 .C COLUMNS Overrides the system-selected horizontal screen size. .TP .C EDITOR Used by the .C v command to select an editor. .TP .C LANG Provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C more will behave as if all internationalization variables are set to "C". See .IR environ (5). .TP .C LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .TP .C LC_CTYPE Determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .TP .C LC_MESSAGES Determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .TP .C NLSPATH Determines the location of message catalogues for the processing of .C LC_MESSAGES. .TP .C LINES Overrides the system-selected vertical screen size, used as the number of lines in a screenful. The .C -n option takes precedence over the .C LINES variable for determining the number of lines in a screenful. .TP .C MORE Determines a string containing options, preceded with hyphens and blank-character-separated as on the command line. Any command-line options are processed after those in the .C MORE variable. The .C MORE variable takes precedence over the .C TERM and .C LINES variables for determining the number of lines in a screenful. .TP .C TERM Determines the name of the terminal type. .RE .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES To view a simple file, use: .IP .CI more " filename" .PP To preview .I nroff output, use a command resembling: .IP .C "nroff -mm +2 doc.n | more -s" .PP If the file contains tables, use: .IP .CI "tbl " file " | nroff -mm | col | more -s" .PP To display file .C stuff in a fifteen line-window and convert multiple adjacent blank lines into a single blank line: .IP .CI " more -s -n 15 " stuff .PP To examine each file with its last screenful: .IP .CI " more -p G " "file1 file2" .PP To examine each file starting with line 100 in the current position (third line, so line 98 is the first line written): .IP .CI " more -p 100g " "file1 file2" .PP To examine the file that contains the tagstring .I tag with line 30 in the current position: .IP .C more -t tag -p 30g .PD .SH WARNINGS Standard error, file descriptor 2, is normally used for input during interactive use and should not be redirected (see Input/Output section in the manpage of the shell in use). .SH FILES .TP 30 .C /usr/share/lib/terminfo/?/* compiled terminal capability data base .PD .SH AUTHOR .C more was developed by Mark Nudleman, University of California, Berkeley, OSF, and HP. .SH SEE ALSO csh(1), man(1), pg(1), sh(1), term(4), terminfo(4), environ(5), lang(5), regexp(5). .SH STANDARDS CONFORMANCE .CR more ": XPG4" .\" index@\f2more\f1 \- file perusal filter for crt viewing@@@\f3more(1)\f1 .\" index@\f2page\f1 \- file perusal filter for crt viewing@@@\f3more(1)\f1 .\" index@display file on \s-1CRT\s+1 terminals@@@\f3more(1)\f1 .\" index@files: display file on \s-1CRT\s+1 terminals@@@\f3more(1)\f1 .\" index@file perusal filter for \s-1CRT\s+1 terminals@@@\f3more(1)\f1 .\" index@peruse file on \s-1CRT\s+1 terminals@@@\f3more(1)\f1 .\" index@\s-1CRT\s+1 terminals, peruse file on@@@\f3more(1)\f1 .\" index@terminals, \s-1CRT\s+1, peruse file on@@@\f3more(1)\f1 .\" index@soft-copy terminals, peruse file on@@@\f3more(1)\f1 .\" .\" toc@\f3more(1)\f1:\0\0\f2more\f1, \f2page\f1@@@file perusal filter for crt viewing .\" toc@\f2page\f1: file perusal filter for crt viewing@@@see \f3more(1)\f1 .\" .\" links@more.1 page.1 .\" $Header: mt.1,v 72.5 94/11/30 10:12:15 ssa Exp $ .TA m .TH mt 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mt \- magnetic tape manipulating program .SH SYNOPSIS .C mt .RC [ -t .IR tapename\| ] .I command .RI [ \|count\| ] .SH DESCRIPTION .C mt is used to give commands to the tape drive. If .I tapename is not specified, the environment variable .C TAPE is used; if .C TAPE is not defined, the default drive is used. .PP .C mt winds the tape in the requested direction (forward or backward), stopping after the specified .I count EOF marks or records are passed. If .I count is not specified, one is assumed. Each EOF mark counts as one record. When winding backwards, the tape always stops at the BOT marker, regardless of the number remaining in .IR count . .PP .C mt accepts the following .IR command s: .RS .TP 10 .C eof Write .I count EOF marks. .TP .C fsf Forward space .I count files. .TP .C fsr Forward space .I count records. .TP .C bsf Backward space .I count files. .TP .C bsr Backward space .I count records. .TP .C rew Rewind tape. .TP .C offl Rewind tape and go offline. .TP .C eod Seek to end of data (\c DDS and QIC drives only). .TP .C smk Write .I count setmarks (\c DDS drives only). .TP .C fss Forward space .I count setmarks (\c DDS drives only). .TP .C bss Backward space .I count setmarks (\c DDS drives only). .RE .PP Spacing operations (back or forward space file or record) leave the tape positioned past the object being spaced to in the direction of motion. That is, backspacing a file leaves the the tape positioned before the file mark, forward spacing a file leaves the tape positioned after the file mark. This is consistent with all classical usage on tapes. .SH FILES .TP 20 .C /dev/rmt/* Raw magnetic tape interface .PD 0 .TP .C /dev/rmt/0mnb Default tape interface .PD .SH WARNINGS Only raw, no rewind Berkeley type devices should be specified. This type of device will not reposition the tape upon close. eg, .CR /dev/rmt/0mnb . Please refer to .IR mt (7) for more details. .PP It is possible to wind the tape beyond the EOT marker and off the end of the reel. .SH EXAMPLES Rewind the tape associated with the device file .CR /dev/rmt/0mnb : .IP .C "mt -t /dev/rmt/0mnb rew" .SH AUTHOR .C mt was developed by the University of California, Berkeley. .SH SEE ALSO dd(1), mt(7). .\" index@\f4mt\f1 \- magnetic tape manipulating program@@@\f3mt(1)\f1 .\" index@magnetic tape manipulating program@@@\f3mt(1)\f1 .\" index@manipulate magnetic tape drive@@@\f3mt(1)\f1 .\" index@write end-of-file marks on magnetic tape@@@\f3mt(1)\f1 .\" index@rewind magnetic tape@@@\f3mt(1)\f1 .\" index@move magnetic tape forward or backward by files or records@@@\f3mt(1)\f1 .\" index@files or records, move magnetic tape forward or backward by@@@\f3mt(1)\f1 .\" index@records or files, move magnetic tape forward or backward by@@@\f3mt(1)\f1 .\" .\" toc@\f3mt(1)\f1:\0\0\f4mt\f1@@@magnetic tape manipulating program .\" .\" fileset_database@mt.1 USER-CMDS-MAN .\" $Header: mv.1,v 76.1 95/08/04 15:40:00 ssa Exp $ .TA m .TH mv 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mv \- move or rename files and directories .SH SYNOPSIS .CR mv .RC \|[ -f \(or -i ]\| .RC \|[ -e .IR extarg ]\| .IR file1 .IR new-file .PP .CR mv .RC \|[ -f \(or -i ]\| .RC \|[ -e .IR extarg ]\| .IR file1 .RI \|[ "file2 " ...]\| .IR dest-directory .PP .CR mv .RC \|[ -f \(or -i ]\| .RC \|[ -e .IR extarg ]\| .IR directory1 .RI \|[ "\|directory2 ...\|" ]\| .IR dest-directory .SH DESCRIPTION The .CR mv command moves: .RS .TP 3 \(bu One file .RI ( file1 ) to a new or existing file .RI ( new-file ). .TP \(bu One or more files .RI ( file1 ", [" file2 ",\0...])" to an existing directory .RI ( dest-directory ). .TP \(bu One or more directory subtrees .RI ( directory1 ", [" directory2 ",\0...])" to a new or existing directory .RI ( dest-directory ). .RE .PP Moving .IR file1 to .IR new-file is used to rename a file within a directory or to relocate a file within a file system or across different file systems. When the destination is a directory, one or more files are moved into that directory. If two or more files are moved, the destination must be a directory. When moving a single file to a new file, if .IR new-file exists, its contents are destroyed. .PP If the access permissions of the destination .IR dest-directory or existing destination file .IR new-file forbid writing, .CR mv asks permission to overwrite the file. This is done by printing the mode (see .IR chmod (2) and Access Control Lists below), followed by the first letters of the words .IR yes and .IR no in the language of the current locale, prompting for a response, and reading one line from the standard input. If the response is affirmative and the action is permissible, the operation occurs; if not, the command proceeds to the next source file, if any. .PP If .IR file1 is a file and .IR new-file is a link to another file with other links, the other links remain and .IR new-file becomes a new file. If .IR file1 is a file with links or a link to a file, the existing file or link remains intact, but the name is changed to .IR new-file which may or may not be in the directory where .IR file1 resided, depending on directory path names used in the .CR mv command. The last access and modification times of the file or files being moved remain unchanged. .SS Options .CR mv recognizes the following options: .RS .TP 15 .C -f Perform .CR mv commands without prompting for permission. This option is assumed when the standard input is not a terminal. .TP .C -i Causes .CR mv to write a prompt to standard output before moving a file that would overwrite an existing file. If the response from the standard input is affirmative, the file is moved if permissions allow the move. .TP .CI -e \0extarg Specifies the handling of any extent attributes of the files(s) to be moved. .IR extarg can be one of the following values: .RS .RS .TP 12 .CR warn Issue a warning message if extent attributes cannot be preserved, but move the file anyway. .TP .CR ignore Do not preserve extent attributes. .TP .CR force Do not move the file if the extent attributes cannot be preserved. .TP .CR " " If multiple source files are specified with a single target directory, .CR mv will move the files that either do not have extent attributes or that have extent attributes that can be preserved. .CR mv will not move the files if it cannot preserve their extent attributes. .RE .IP Extent attributes cannot be preserved if the files are being moved to a file system that does not support extent attributes or if that file system has a different block size than the original. If .CR -e is not specified, the default value for .IR extarg is .CR warn . .RE .RE .SS "Access Control Lists (ACLs)" If optional ACL entries are associated with .IR new-file , .CR mv displays a plus sign .RC ( + ) after the access mode when asking permission to overwrite the file. .PP If .IR new-file is a new file, it inherits the access control list of .IR file1 , altered to reflect any difference in ownership between the two files (see .IR acl (5)). .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_CTYPE determines the interpretation of text as single byte and/or multibyte characters. .PP .CR LANG and .CR LC_CTYPE determine the local language equivalent of y (for yes/no queries). .PP .CR LANG determines the language in which messages are displayed. .PP If .CR LC_CTYPE is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of .CR C (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR mv behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .SS International Code Set Support Single character and multibyte character code sets are supported. .SH EXAMPLES Rename a file in the current directory: .IP .C "mv old-filename new-filename" .PP Rename a directory in the current directory: .IP .C "mv old-dirname new-dirname" .PP Rename a file in the current directory whose name starts with a nonprinting control character or a character that is special to the shell, such as .CR - and .CR * (extra care may be required depending on the situation): .IP .C "mv ./bad-filename new-filename" .br .C "mv ./?bad-filename new-filename" .br .C "mv ./*bad-filename new-filename" .PP Move directory .CR sourcedir and its contents to a new location .RC ( targetdir ) in the file system (upon completion, a subdirectory named .CR sourcedir resides in directory .CR targetdir ): .IP .C "mv sourcedir targetdir" .PP Move all files and directories (including links) in the current directory to a new location underneath .CR targetdir : .IP .C "mv * targetdir .PP Move all files and directories (including links) in .CR sourcedir to a new location underneath .CR targetdir .RC ( sourcedir and .CR targetdir are in separate directory paths): .IP .C "mv sourcedir/* targetdir" .SH WARNINGS If .IR file1 and .IR new-file exist on different file systems, .CR mv copies the file and deletes the original. In this case the mover becomes the owner and any linking relationship with other files is lost. .CR mv cannot carry hard links across file systems. If .IR file1 is a directory, .CR mv copies the entire directory structure onto the destination file system and deletes the original. .PP .CR mv .IR cannot be used to perform the following operations: .RS .TP 3 \(bu Rename either the current working directory or its parent directory using the .CR . or .CR .. notation. .TP \(bu Rename a directory to a new name identical to the name of a file contained in the same parent directory. .RE .SH DEPENDENCIES .SS NFS Access control lists of networked files are summarized (as returned in .IR st_mode by .IR stat (2)), but not copied to the new file. When using .CR mv on such files, a .CR + is not printed after the mode value when asking for permission to overwrite a file. .SH AUTHOR .CR mv was developed by AT&T, the University of California, Berkeley and HP. .SH SEE ALSO cp(1), cpio(1), ln(1), rm(1), link(1M), lstat(2), readlink(2), stat(2), symlink(2), symlink(4), acl(5). \" STD .SH STANDARDS CONFORMANCE .CR mv ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f1change the name of a file@@@\f3mv(1)\f1 .\" index@\f1directory, move directory subtree and files to another directory@@@\f3mv(1)\f1 .\" index@\f1directory, move multiple files to another directory@@@\f3mv(1)\f1 .\" index@\f1directory, rename directory@@@\f3mv(1)\f1 .\" index@\f1files, change name of a file@@@\f3mv(1)\f1 .\" index@\f1files, move directory subtree and files to another directory@@@\f3mv(1)\f1 .\" index@\f1files, move file to new location@@@\f3mv(1)\f1 .\" index@\f1files, move multiple files to another directory@@@\f3mv(1)\f1 .\" index@\f1files, overwrite file with an existing file@@@\f3mv(1)\f1 .\" index@\f1files, rename directory@@@\f3mv(1)\f1 .\" index@\f1files, rename file@@@\f3mv(1)\f1 .\" index@\f1move file to new location@@@\f3mv(1)\f1 .\" index@\f1move multiple files to another directory@@@\f3mv(1)\f1 .\" index@\f1name of a file, change@@@\f3mv(1)\f1 .\" index@\f1overwrite file with an existing file@@@\f3mv(1)\f1 .\" index@\f1rename directory@@@\f3mv(1)\f1 .\" index@\f1rename file@@@\f3mv(1)\f1 .\" index@\f4mv\f1 \- move or rename files and directories@@@\f3mv(1)\f1 .\" ENDINDEX .\" .\" toc@\f3mv(1)\f1:\0\0\f4mv\f1@@@move or rename files and directories .\" ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH mwm 1X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fImwm\fP \- The Motif Window Manager .SH SYNOPSIS .nf .sS \fImwm\fP [ \fBoptions\fP ] .sE .SH DESCRIPTION .fi \fImwm\fP is an X Window System client that provides window management functionality and some session management functionality. It provides functions that facilitate control (by the user and the programmer) of elements of window state such as placement, size, icon/normal display, and input-focus ownership. It also provides session management functions such as stopping a client. .SS Options .IP "\fI\-display\fP\ \fBdisplay\fP" This option specifies the display to use; see \fBX(1)\fP. .IP "\fI\-xrm\fP\ \fBresourcestring\fP" This option specifies a resource string to use. .IP "\fI\-multiscreen\fP" This option causes \fImwm\fP to manage all screens on the display. The default is to manage only a single screen. .IP "\fI\-name\fP\ \fBname\fP" This option causes \fImwm\fP to retrieve its resources using the specified name, as in \fBname*resource\fP. .IP "\fI\-screens\fP\ \fBname\ [name\ [...]]\fP" This option specifies the resource names to use for the screens managed by \fImwm\fP. If \fImwm\fP is managing a single screen, only the first name in the list is used. If \fImwm\fP is managing multiple screens, the names are assigned to the screens in order, starting with screen 0. Screen 0 gets the first name, screen 1 the second name, and so on. .SS Appearance The following sections describe the basic default behaviors of windows, icons, the icon box, input focus, and window stacking. The appearance and behavior of the window manager can be altered by changing the configuration of specific resources. Resources are defined under the heading "X DEFAULTS." .SS Screens By default, \fImwm\fP manages only the single screen specified by the \fI\-display\fP option or the DISPLAY environment variable (by default, screen 0). If the \fI\-multiscreen\fP option is specified or if the \fImultiScreen\fP resource is True, \fImwm\fP tries to manage all the screens on the display. .PP When \fImwm\fP is managing multiple screens, the \fI\-screens\fP option can be used to give each screen a unique resource name. The names are separated by blanks, for example, \fI\-screens\fP mwm0 mwm1. If there are more screens than names, resources for the remaining screens will be retrieved using the first name. By default, the screen number is used for the screen name. .nL .ne 15 .SS Windows Default \fImwm\fP window frames have distinct components with associated functions: .IP "\fITitle\ Area\fP" In addition to displaying the client's title, the title area is used to move the window. To move the window, place the pointer over the title area, press button 1 and drag the window to a new location. By default, a wire frame is moved during the drag to indicate the new location. When the button is released, the window is moved to the new location. .IP "\fITitle\ Bar\fP" The title bar includes the title area, the minimize button, the maximize button, and the window menu button. In shaped windows, such as round windows, the title bar floats above the window. .IP "\fIMinimize\ Button\fP" To turn the window into an icon, click button 1 on the minimize button (the frame box with a \fBsmall\fP square in it). .IP "\fIMaximize\ Button\fP" To make the window fill the screen (or enlarge to the largest size allowed by the configuration files), click button 1 on the maximize button (the frame box with a \fBlarge\fP square in it). .IP "\fIWindow\ Menu\ Button\fP" The window menu button is the frame box with a horizontal bar in it. To pull down the window menu, press button 1. While pressing, drag the pointer on the menu to your selection, then release the button when your selection is highlighted. Pressing button 3 in the title bar or resize border handles also posts the window menu. Alternately, you can click button 1 to pull down the menu and keep it posted; then position the pointer and select. You can also post the window menu by pressing or . Double-clicking button 1 with the pointer on the window menu button closes the window. The following table lists the contents of the window menu. .PP .ne 3i .sp 1 .in 0 .KS .TS center; cbss lb lb lb l l l. Default Window Menu Selection Accelerator Description _ Restore Alt+F5 T{ Restores the window to its size .nL before minimizing or maximizing T} Move Alt+F7 T{ Allows the window to be moved .nL with keys or mouse T} Size Alt+F8 Allows the window to be resized Minimize Alt+F9 Turns the window into an icon Maximize Alt+F10 Makes the window fill the screen Lower Alt+F3 T{ Moves window to bottom of window stack T} Close Alt+F4 Causes client to terminate .TE .KE .in .sp 1 .IP "\fIResize\ Border\ Handles\fP" To change the size of a window, move the pointer over a resize border handle (the cursor changes), press button 1, and drag the window to a new size. When the button is released, the window is resized. While dragging is being done, a rubber-band outline is displayed to indicate the new window size. .IP "\fIMatte\fP" An optional matte decoration can be added between the client area and the window frame. A matte is not actually part of the window frame. There is no functionality associated with a matte. .SS Icons Icons are small graphic representations of windows. A window can be minimized (iconified) using the minimize button on the window frame. Icons provide a way to reduce clutter on the screen. .PP .ne 6 Pressing mouse button 1 when the pointer is over an icon causes the icon's window menu to pop up. Releasing the button (press + release without moving mouse = click) causes the menu to stay posted. The menu contains the following selections: .P .ne 2.5i .sp 1 .in 0 .KS .TS center; cbss lb lb lb l l l . Icon Window Menu Selection Accelerator Description _ Restore Alt+F5 Opens the associated window Move Alt+F7 Allows the icon to be moved with keys Size Alt+F8 Inactive (not an option for icons) Minimize Alt+F9 Inactive (not an option for icons) Maximize Alt+F10 T{ Opens the associated window and makes it fill the screen T} Lower Alt+F3 Moves icon to bottom of icon stack Close Alt+F4 Removes client from \fImwm\fP management .TE .KE .in .sp 1 .PP Note that pressing button 3 over an icon also causes the icon's window menu to pop up. To make a menu selection, drag the pointer over the menu and release button 3 when the desired item is highlighted. .PP Double-clicking button 1 on an icon invokes the \fIf.restore_and_raise\fP function and restores the icon's associated window to its previous state. For example, if a maximized window is iconified, then double-clicking button 1 restores it to its maximized state. Double-clicking button 1 on the icon box's icon opens the icon box and allows access to the contained icons. (In general, double-clicking a mouse button is a quick way to perform a function.) Pressing or (the pop-up menu key) causes the icon window menu of the currently selected icon to pop up. .SS "Icon Box" When icons begin to clutter the screen, they can be packed into an icon box. (To use an icon box, \fImwm\fP must be started with the icon box configuration already set.) The icon box is a \fImwm\fP window that holds client icons. It includes one or more scroll bars when there are more window icons than the icon box can show at the same time. .PP .ne 2i Icons in the icon box can be manipulated with the mouse. The following table summarizes the behavior of this interface. Button actions apply whenever the pointer .ne 4 is on any part of the icon. Note that double-clicking an icon in the icon box invokes the \fIf.restore_and_raise\fP function. .P .ne 2.5i .sp 1 .in 0 .KS .TS tab( ),center; lb lb l l. Button Action Description _ Button 1 click Selects the icon Button 1 double-click T{ Normalizes (opens) the associated window .br Raises an already open window to the top of the stack T} Button 1 drag Moves the icon Button 3 press Causes the menu for that icon to pop up Button 3 drag T{ Highlights items as the pointer moves across the menu T} .TE .KE .in .sp 1 .PP Pressing mouse button 3 when the pointer is over an icon causes the menu for that icon to pop up. .P .ne 3i .wH .in 0 .sp 1 .in 0 .KS .TS center; cbss lb lb lb l l l . Icon Menu for the Icon Box Selection Accelerator Description _ Restore Alt+F5 Opens the associated window (if not already open) Move Alt+F7 Allows the icon to be moved with keys Size\ Alt+F8 Inactive Minimize Alt+F9 Inactive Maximize Alt+F10 T{ Opens the associated window (if not already open) and maximizes its size T} Lower Alt+F3 Inactive Close Alt+F4 Removes client from \fImwm\fP management .TE .KE .in .sp 1 .wH .in .PP To pull down the window menu for the icon box itself, press button 1 with the pointer over the menu button for the icon box. The window menu of the icon box differs from the window menu of a client window: The "Close" selection is replaced with the "PackIcons Shift+Alt+F7" selection. When selected, PackIcons packs the icons in the box to achieve neat rows with no empty slots. .PP .ne 3 You can also post the window menu by pressing or . Pressing (the pop-up menu key) causes the icon window menu of the currently selected icon to pop up. .SS "Input Focus" \fImwm\fP supports (by default) a keyboard input focus policy of explicit selection. This means when a window is selected to get keyboard input, it continues to get keyboard input until the window is withdrawn from window management, another window is explicitly selected to get keyboard input, or the window is iconified. Several resources control the input focus. The client window with the keyboard input focus has the active window appearance with a visually distinct window frame. .PP The following tables summarize the keyboard input focus selection behavior: .P .ne 2i .sp 1 .in 0 .KS .TS center; lb lb lb l l l. Button Action Object Function Description _ Button 1 press Window / window frame Keyboard focus selection Button 1 press Icon Keyboard focus selection .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; lb lb l l. Key Action Function Description _ [Alt][Tab] T{ Move input focus to next window in window stack (available only in explicit focus mode) T} _ [Alt][Shift][Tab] T{ Move input focus to previous window in window stack (available only in explicit focus mode) T} .TE .KE .in .sp 1 .SS "Window Stacking" There are two types of window stacks: global window stacks and an application's local family window stack. .P The global stacking order of windows may be changed as a result of setting the keyboard input focus, iconifying a window, or performing a window manager window stacking function. When keyboard focus policy is explicit the default value of the \fIfocusAutoRaise\fP resource is True. This causes a window to be raised to the top of the stack when it receives input focus, for example, by pressing button 1 on the title bar. The key actions defined in the previous table will thus raise the window receiving focus to the top of the stack. .P In pointer mode, the default value of \fIfocusAutoRaise\fP is False, that is, the window stacking order is not changed when a window receives keyboard input focus. The following key actions can be used to cycle through the global window stack. .sp 1 .in 0 .KS .TS center; lb lb l l. Key Action Function Description _ [Alt][ESC] Place top window on bottom of stack [Alt][Shift][ESC] Place bottom window on top of stack .TE .KE .in .sp 1 .P By default, a window's icon is placed on the bottom of the stack when the window is iconified; however, the default can be changed by the \fIlowerOnIconify\fP resource. .P Transient windows (secondary windows such a dialog boxes) stay above their parent windows by default. However, an application's local family stacking order may be changed to allow a transient window to be placed below its parent top-level window. The following parameters show the modification of the stacking order for the \fIf.lower\fP function. .P .IP "\fIf.lower\fP" Lowers the transient window within the family (staying above the parent) and lowers the family in the global window stack. .IP "\fIf.lower\fP\ [\fIwithin\fP]" Lowers the transient window within the family (staying above the parent) but does not lower the family in the global window stack. .IP "\fIf.lower\fP\ [\fIfreeFamily\fP]" Lowers the window free from its family stack (below the parent), but does not lower the family in the global window stack. .P The parameters \fIwithin\fP and \fIfreeFamily\fP can also be used with \fIf.raise\fP and \fIf.raise_lower\fP. .SS "X Defaults" \fImwm\fP is configured from its resource database. This database is built from the following sources. They are listed in order of precedence, low to high: .P .na .wH .in +3n /usr/lib/X11/app-defaults/Mwm .nL $HOME/Mwm .nL RESOURCE_MANAGER root window property or $HOME/.Xdefaults .nL XENVIRONMENT variable or $HOME/.Xdefaults-\fBhost\fP .nL \fImwm\fP command line options .ad .wH .in -3n .P The file names /usr/lib/X11/app-defaults/Mwm and $HOME/Mwm represent customary locations for these files. The actual location of the system-wide class resource file may depend on the XFILESEARCHPATH environment variable and the current language environment. The actual location of the user-specific class resource file may depend on the XUSERFILESEARCHPATH and XAPPLRESDIR environment variables and the current language environment. .PP Entries in the resource database may refer to other resource files for specific types of resources. These include files that contain bitmaps, fonts, and \fImwm\fP specific resources such as menus and behavior specifications (for example, button and key bindings). .PP \fIMwm\fP is the resource class name of \fImwm\fP and \fImwm\fP is the default resource name used by \fImwm\fP to look up resources. the \fI\-screens\fP command line option specifies resource names, such as "mwm_b+w" and "mwm_color".) In the following discussion of resource specification, "Mwm" and "mwm" (and the aliased \fImwm\fP resource names) can be used interchangeably, but "mwm" takes precedence over "Mwm". .PP \fImwm\fP uses the following types of resources: .PP \fBComponent Appearance Resources:\fP .PP These resources specify appearance attributes of window manager user interface components. They can be applied to the appearance of window manager menus, feedback windows (for example, the window reconfiguration feedback window), client window frames, and icons. .PP \fBGeneral Appearance and Behavior Resources:\fP .PP These resources specify \fImwm\fP appearance and behavior (for example, window management policies). They are not set separately for different \fImwm\fP user interface components. .PP .ne 4i \fBClient Specific Resources:\fP .PP These \fImwm\fP resources can be set for a particular client window or class of client windows. They specify client-specific icon and client window frame appearance and behavior. .PP .ne 6 Resource identifiers can be either a resource name (for example, foreground) or a resource class (for example, Foreground). If the value of a resource is a filename and if the filename is prefixed by " /", then it is relative to the path contained in the HOME environment variable (generally the user's home directory). .SS "Component Appearance Resources" The syntax for specifying component appearance resources that apply to window manager icons, menus, and client window frames is .P .na .wH .in +5n \fIMwm*\fBresource_id\fP .wH .in -5n .ad .P For example, \fIMwm*foreground\fP is used to specify the foreground color for \fImwm\fP menus, icons, client window frames, and feedback dialogs. .PP The syntax for specifying component appearance resources that apply to a particular \fImwm\fP component is .P .na .wH .in +5n \fIMwm*\fP[\fImenu\fP\fIicon\fP\fIclient\fP\fIfeedback\fP]\fI*\fBresource_id\fP .wH .in -5n .ad .PP If \fBmenu\fP is specified, the resource is applied only to \fImwm\fP menus; if \fBicon\fP is specified, the resource is applied to icons; and if \fBclient\fP is specified, the resource is applied to client window frames. For example, \fIMwm*icon*foreground\fP is used to specify the foreground color for \fImwm\fP icons, \fIMwm*menu*foreground\fP specifies the foreground color for \fImwm\fP menus, and \fIMwm*client*foreground\fP is used to specify the foreground color for \fImwm\fP client window frames. .PP The appearance of the title area of a client window frame (including window management buttons) can be separately configured. The syntax for configuring the title area of a client window frame is .PP .wH .in +4 \fIMwm*client*title*\fBresource_id\fP .wH .in -4 .PP For example, \fIMwm*client*title*foreground\fP specifies the foreground color for the title area. Defaults for title area resources are based on the values of the corresponding client window frame resources. .PP .ne 6 The appearance of menus can be configured based on the name of the menu. The syntax for specifying menu appearance by name is .PP .wH .in +4 \fIMwm*menu*\fBmenu_name\fI*\fBresource_id\fP .wH .in -4 .PP For example, \fIMwm*menu*my_menu*foreground\fP specifies the foreground color for the menu named \fImy_menu\fP. The user can also specify resources for window manager menu components, that is, the gadgets which comprise the menu. These may include for example, a menu title, title separator, one or more buttons, and separators. If a menu contains more than one instance of a class, such as multiple PushButtonGadgets, the name of the first instance is "PushButtonGadget1", the second is "PushButtonGadget2", and so on. The following list identifies the naming convention used for window manager menu components: .TP \(bu Menu Title LabelGadget \- "TitleName" .TP \(bu Menu Title SeparatorGadget \- "TitleSeparator" .TP \(bu CascadeButtonGadget \- "CascadeButtonGadget" .TP \(bu PushButtonGadget \- "PushButtonGadget" .TP \(bu SeparatorGadget \- "SeparatorGadget" .P Refer to the man page for each class for a list of resources which can be specified. .PP The following component appearance resources that apply to all window manager parts can be specified: .P .ne 3.5i .wH .in -1 .sp 1 .in 0 .KS .TS center; cb sss lb lb lb lb l l l l. Component Appearance Resources \- All Window Manager Parts Name Class Value Type Default _ background Background color varies\(dg backgroundPixmap BackgroundPixmap string\(dg\(dg varies\(dg bottomShadowColor Foreground color varies\(dg bottomShadowPixmap BottomShadowPixmap string\(dg\(dg varies\(dg fontList FontList string\(dg\(dg\(dg "fixed" foreground Foreground color varies\(dg saveUnder SaveUnder T/F F topShadowColor Background color varies\(dg topShadowPixmap TopShadowPixmap string\(dg\(dg varies\(dg .TE .KE .in .sp 1 .P \(dgThe default is chosen based on the visual type of the screen. .nL \(dg\(dgImage name. See \fIXmInstallImage(3X)\fP. .nL \(dg\(dg\(dgX11 X Logical Font Description .wH .in .IP "\fIbackground\fP\ (class\ \fIBackground\fP)" This resource specifies the background color. Any legal X color may be specified. The default value is chosen based on the visual type of the screen. .P .ne 2i .IP "\fIbackgroundPixmap\fP\ (class\ \fIBackgroundPixmap\fP)" This resource specifies the background Pixmap of the \fImwm\fP decoration when the window is inactive (does not have the keyboard focus). The default value is chosen based on the visual type of the screen. .IP "\fIbottomShadowColor\fP\ (class\ \fIForeground\fP)" This resource specifies the bottom shadow color. This color is used for the lower and right bevels of the window manager decoration. Any legal X color may be specified. The default value is chosen based on the visual type of the screen. .IP "\fIbottomShadowPixmap\fP\ (class\ \fIBottomShadowPixmap\fP)" This resource specifies the bottom shadow Pixmap. This Pixmap is used for the lower and right bevels of the window manager decoration. The default is chosen based on the visual type of the screen. .IP "\fIfontList\fP\ (class\ \fIFontList\fP)" This resource specifies the font used in the window manager decoration. The character encoding of the font should match the character encoding of the strings that are used. The default is "fixed." .IP "\fIforeground\fP\ (class\ \fIForeground\fP)" This resource specifies the foreground color. The default is chosen based on the visual type of the screen. .IP "\fIsaveUnder\fP\ (class\ \fISaveUnder\fP)" This is used to indicate whether "save unders" are used for \fImwm\fP components. For this to have any effect, save unders must be implemented by the X server. If save unders are implemented, the X server saves the contents of windows obscured by windows that have the save under attribute set. If the saveUnder resource is True, \fImwm\fP will set the save under attribute on the window manager frame of any client that has it set. If saveUnder is False, save unders will not be used on any window manager frames. The default value is False. .IP "\fItopShadowColor\fP\ (class\ \fIBackground\fP)" This resource specifies the top shadow color. This color is used for the upper and left bevels of the window manager decoration. The default is chosen based on the visual type of the screen. .IP "\fItopShadowPixmap\ (\fP\ class\ \fITopShadowPixmap)\fP" This resource specifies the top shadow Pixmap. This Pixmap is used for the upper and left bevels of the window manager decoration. The default is chosen based on the visual type of the screen. .PP The following component appearance resources that apply to frame and icons can be specified: .wH .ps .P .ne 3i .wH .in -4 .sp 1 .in 0 .KS .TS center; cb sss lb lb lb lb l l l l . Frame and Icon Components Name Class Value Type Default _ activeBackground Background color varies\(dg activeBackgroundPixmap BackgroundPixmap string\(dg\(dg varies\(dg activeBottomShadowColor Foreground color varies\(dg activeBottomShadowPixmap BottomShadowPixmap string\(dg\(dg varies\(dg activeForeground Foreground color varies\(dg activeTopShadowColor Background color varies\(dg activeTopShadowPixmap TopShadowPixmap string\(dg\(dg varies\(dg .TE .KE .in .sp 1 .P \(dgThe default is chosen based on the visual type of the screen. .nL \(dg\(dgSee \fIXmInstallImage(3X)\fP. .P .wH .in .IP "\fIactiveBackground\fP\ (class\ \fIBackground\fP)" This resource specifies the background color of the \fImwm\fP decoration when the window is active (has the keyboard focus). The default is chosen based on the visual type of the screen. .IP "\fIactiveBackgroundPixmap\fP\ (class\ \fIActiveBackgroundPixmap\fP)" This resource specifies the background Pixmap of the \fImwm\fP decoration when the window is active (has the keyboard focus). The default is chosen based on the visual type of the screen. .IP "\fIactiveBottomShadowColor\fP\ (class\ \fIForeground\fP)" This resource specifies the bottom shadow color of the \fImwm\fP decoration when the window is active (has the keyboard focus). The default is chosen based on the visual type of the screen. .IP "\fIactiveBottomShadowPixmap\fP\ (class\ \fIBottomShadowPixmap\fP)" This resource specifies the bottom shadow Pixmap of the \fImwm\fP decoration when the window is active (has the keyboard focus). The default is chosen based on the visual type of the screen. .IP "\fIactiveForeground\fP\ (class\ \fIForeground\fP)" This resource specifies the foreground color of the \fImwm\fP decoration when the window is active (has the keyboard focus). The default is chosen based on the visual type of the screen. .IP "\fIactiveTopShadowColor\fP\ (class\ \fIBackground\fP)" This resource specifies the top shadow color of the \fImwm\fP decoration when the window is active (has the keyboard focus). The default is chosen based on the visual type of the screen. .IP "\fIactiveTopShadowPixmap\fP\ (class\ \fITopShadowPixmap\fP)" This resource specifies the top shadow Pixmap of the \fImwm\fP decoration when the window is active (has the keyboard focus). The default is chosen based on the visual type of the screen. .SS "General Appearance and Behavior Resources" The syntax for specifying general appearance and behavior resources is .P .na .wH .in +5n \fIMwm*\fBresource_id\fP .wH .in -5n .ad .PP For example, \fIMwm*keyboardFocusPolicy\fP specifies the window manager policy for setting the keyboard focus to a particular client window. .PP The following general appearance and behavior resources can be specified: .PP .wH .in 0 .sp 1 .in 0 .KS .TS center; cb sss lb lb lb lb l l l l . General Appearance and Behavior Resources Name Class Value Type Default _ autoKeyFocus AutoKeyFocus T/F T autoRaiseDelay AutoRaiseDelay millisec 500 bitmapDirectory BitmapDirectory directory T{ /usr/include/\e .nL X11/bitmaps T} buttonBindings ButtonBindings string T{ "DefaultBut\e .nL tonBindings" T} cleanText CleanText T/F T clientAutoPlace ClientAutoPlace T/F T colormapFocusPolicy ColormapFocusPolicy string keyboard configFile ConfigFile file .mwmrc deiconifyKeyFocus DeiconifyKeyFocus T/F T doubleClickTime DoubleClickTime millisec. T{ multi-click .nL time T} enableWarp enableWarp T/F T enforceKeyFocus EnforceKeyFocus T/F T fadeNormalIcon FadeNormalIcon T/F F feedbackGeometry FeedbackGeometry string T{ center on .nL screen T} frameBorderWidth FrameBorderWidth pixels varies iconAutoPlace IconAutoPlace T/F T iconBoxGeometry IconBoxGeometry string 6x1+0-0 iconBoxName IconBoxName string iconbox iconBoxSBDisplayPolicy IconBoxSBDisplayPolicy string all iconBoxTitle IconBoxTitle XmString Icons iconClick IconClick T/F T iconDecoration IconDecoration string varies iconImageMaximum IconImageMaximum wxh 50x50 iconImageMinimum IconImageMinimum wxh 16x16 iconPlacement IconPlacement string left bottom iconPlacementMargin IconPlacementMargin pixels varies interactivePlacement InteractivePlacement T/F F keyBindings KeyBindings string T{ "DefaultKey\e .nL Bindings" T} keyboardFocusPolicy KeyboardFocusPolicy string explicit limitResize LimitResize T/F T lowerOnIconify LowerOnIconify T/F T maximumMaximumSize MaximumMaximumSize wxh (pixels) T{ 2X screen .nL w&h T} moveThreshold MoveThreshold pixels 4 moveOpaque MoveOpaque T/F F multiScreen MultiScreen T/F F passButtons PassButtons T/F F passSelectButton PassSelectButton T/F T positionIsFrame PositionIsFrame T/F T positionOnScreen PositionOnScreen T/F T quitTimeout QuitTimeout millisec. 1000 raiseKeyFocus RaiseKeyFocus T/F F resizeBorderWidth ResizeBorderWidth pixels varies resizeCursors ResizeCursors T/F T screens Screens string varies showFeedback ShowFeedback string all startupKeyFocus StartupKeyFocus T/F T transientDecoration TransientDecoration string T{ menu .nL title T} transientFunctions TransientFunctions string T{ \-minimize .nL \-maximize T} useIconBox UseIconBox T/F F wMenuButtonClick WMenuButtonClick T/F T wMenuButtonClick2 WMenuButtonClick2 T/F T .TE .KE .in .sp 1 .wH .in .IP "\fIautoKeyFocus\fP\ (class\ \fIAutoKeyFocus\fP)" This resource is available only when the keyboard input focus policy is explicit. If autoKeyFocus is given a value of True, then when a window with the keyboard input focus is withdrawn from window management or is iconified, the focus is set to the previous window .ne 4 that had the focus. If the value given is False, there is no automatic setting of the keyboard input focus. It is recommended that both \fIautoKeyFocus\fP and \fIstartupKeyFocus\fP be True to work with tear off menus. The default value is True. .IP "\fIautoRaiseDelay\fP\ (class\ \fIAutoRaiseDelay\fP)" This resource is available only when the focusAutoRaise resource is True and the keyboard focus policy is pointer. The autoRaiseDelay resource specifies the amount of time (in milliseconds) that \fImwm\fP will wait before raising a window after it gets the keyboard focus. The default value of this resource is 500 (ms). .IP "\fIbitmapDirectory\fP\ (class\ \fIBitmapDirectory\fP)" This resource identifies a directory to be searched for bitmaps referenced by \fImwm\fP resources. This directory is searched if a bitmap is specified without an absolute pathname. The default value for this resource is /usr/include/X11/bitmaps. The directory /usr/include/X11/bitmaps represents the customary locations for this directory. The actual location of this directory may vary on some systems. If the bitmap is not found in the specified directory, XBMLANGPATH is searched. .IP "\fIbuttonBindings\fP\ (class\ \fIButtonBindings\fP)" This resource identifies the set of button bindings for window management functions. The named set of button bindings is specified in the \fImwm\fP resource description file. These button bindings are \fBmerged\fP with the built-in default bindings. The default value for this resource is "DefaultButtonBindings". .IP "\fIcleanText\fP\ (class\ \fICleanText\fP)" This resource controls the display of window manager text in the client title and feedback windows. If the default value of True is used, the text is drawn with a clear (no stipple) background. This makes text easier to read on monochrome systems where a backgroundPixmap is specified. Only the stippling in the area immediately around the text is cleared. If False, the text is drawn directly on top of the existing background. .IP "\fIclientAutoPlace\fP\ (class\ \fIClientAutoPlace\fP)" This resource determines the position of a window when the window has not been given a program- or user-specified position. With a value of True, windows are positioned with the top left corners of the frames offset horizontally and vertically. A value of False causes the currently configured .ne 4 position of the window to be used. In either case, \fImwm\fP will attempt to place the windows totally on-screen. The default value is True. .IP "\fIcolormapFocusPolicy\fP\ (class\ \fIColormapFocusPolicy\fP)" This resource indicates the colormap focus policy that is to be used. If the resource value is explicit, a colormap selection action is done on a client window to set the colormap focus to that window. If the value is pointer, the client window containing the pointer has the colormap focus. If the value is keyboard, the client window that has the keyboard input focus has the colormap focus. The default value for this resource is keyboard. .IP "\fIconfigFile\fP\ (class\ \fIConfigFile\fP)" The resource value is the pathname for an \fImwm\fP resource description file. .PP If the pathname begins with " /", \fImwm\fP considers it to be relative to the user's home directory (as specified by the HOME environment variable). If the LANG environment variable is set, \fImwm\fP looks for $HOME/$LANG/\fBconfigFile\fP. If that file does not exist or if LANG is not set, \fImwm\fP looks for $HOME/\fBconfigFile\fP. .PP If the \fIconfigFile\fP pathname does not begin with /, \fImwm\fP considers it to be relative to the current working directory. .PP If the \fIconfigFile\fP resource is not specified or if that file does not exist, \fImwm\fP uses several default paths to find a configuration file. If the LANG environment variable is set, \fImwm\fP looks for the configuration file first in $HOME/$LANG/.mwmrc. If that file does not exist or if LANG is not set, \fImwm\fP looks for $HOME/.mwmrc. If that file does not exist and if LANG is set, \fImwm\fP next looks for the file system.mwmrc in the $LANG subdirectory of an implementation-dependent directory. (The default for this directory, if not changed by the implementation, is /usr/lib/X11.) If that file does not exist or if LANG is not set, \fImwm\fP looks for the file system.mwmrc in the same implementation-dependent directory. .IP "\fIdeiconifyKeyFocus\fP\ (class\ \fIDeiconifyKeyFocus\fP)" This resource applies only when the keyboard input focus policy is explicit. If a value of True is used, a window receives the keyboard input focus when it is normalized (deiconified). True is the default value. .nL .ne 4 .IP "\fIdoubleClickTime\fP\ (class\ \fIDoubleClickTime\fP)" This resource is used to set the maximum time (in ms) between the clicks (button presses) that make up a double-click. The default value of this resource is the display's multi-click time. .IP "\fIenableWarp\fP\ (class\ \fIEnableWarp\fP)" The default value of this resource, True, causes \fImwm\fP to warp the pointer to the center of the selected window during keyboard-controlled resize and move operations. Setting the value to False causes \fImwm\fP to leave the pointer at its original place on the screen, unless the user explicitly moves it with the cursor keys or pointing device. .IP "\fIenforceKeyFocus\fP\ (class\ \fIEnforceKeyFocus\fP)" If this resource is given a value of True, the keyboard input focus is always explicitly set to selected windows even if there is an indication that they are "globally active" input windows. (An example of a globally active window is a scroll bar that can be operated without setting the focus to that client.) If the resource is False, the keyboard input focus is not explicitly set to globally active windows. The default value is True. .IP "\fIfadeNormalIcon\fP\ (class\ \fIFadeNormalIcon\fP)" If this resource is given a value of True, an icon is grayed out whenever it has been normalized (its window has been opened). The default value is False. .IP "\fIfeedbackGeometry\fP\ (class\ \fIFeedbackGeometry\fP)" This resource sets the position of the move and resize feedback window. If this resource is not specified, the default is to place the feedback window at the center of the screen. The value of the resource is a standard window geometry string with the following syntax: .P .sp 1 .in 0 .KS .TS tab( ); l l . [\fI=\fP]{\fI+-\fP}\fBxoffset\fP{\fI+-\fP}\fByoffset\fP] .TE .KE .in .sp 1 .IP "\fIframeBorderWidth\fP\ (class\ \fIFrameBorderWidth\fP)" This resource specifies the width (in pixels) of a client window frame border without resize handles. The border width includes the 3-D shadows. The default value is based on the size and resolution of the screen. .IP "\fIiconAutoPlace\fP\ (class\ \fIIconAutoPlace\fP)" This resource indicates whether the window manager arranges icons in a particular area of the screen or places each icon where the window was when it was iconified. The value True indicates that icons are arranged in a particular area of the screen, determined by the iconPlacement resource. The value False indicates that an icon is placed at the location of the window when it is iconified. The default is True. .IP "\fIiconBoxGeometry\fP\ (class\ \fIIconBoxGeometry\fP)" This resource indicates the initial position and size of the icon box. The value of the resource is a standard window geometry string with the following syntax: .P .sp 1 .in 0 .KS .TS tab( ); l l . [\fI=\fP][\fBwidth\fIx\fBheight\fP][{\fI+-\fP}\fBxoffset\fP{\fI+-\fP}\fByoffset\fP] .TE .KE .in .sp 1 .P If the offsets are not provided, the iconPlacement policy is used to determine the initial placement. The units for width and height are columns and rows. .P The actual screen size of the icon box window depends on the iconImageMaximum (size) and iconDecoration resources. The default value for size is (6 * iconWidth + padding) wide by (1 * iconHeight + padding) high. The default value of the location is +0 -0. .IP "\fIiconBoxName\fP\ (class\ \fIIconBoxName\fP)" This resource specifies the name that is used to look up icon box resources. The default name is "iconbox". .IP "\fIiconBoxSBDisplayPolicy\fP\ (class\ \fIIconBoxSBDisplayPolicy\fP)" This resource specifies the scroll bar display policy of the window manager in the icon box. The resource has three possible values: all, vertical, and horizontal. The default value, "all", causes both vertical and horizontal scroll bars always to appear. The value "vertical" causes a single vertical scroll bar to appear in the icon box and sets the orientation of the icon box to horizontal (regardless of the iconBoxGeometry specification). The value "horizontal" causes .ne 3 a single horizontal scroll bar to appear in the icon box and sets the orientation of the icon box to vertical (regardless of the iconBoxGeometry specification). .IP "\fIiconBoxTitle\fP\ (class\ \fIIconBoxTitle\fP)" This resource specifies the name that is used in the title area of the icon box frame. The default value is "Icons". .IP "\fIiconClick\fP\ (class\ \fIIconClick\fP)" When this resource is given the value of True, the system menu is posted and left posted when an icon is clicked. The default value is True. .IP "\fIiconDecoration\fP\ (class\ \fIIconDecoration\fP)" This resource specifies the general icon decoration. The resource value is label (only the label part is displayed) or image (only the image part is displayed) or label image (both the label and image parts are displayed). A value of activelabel can also be specified to get a label (not truncated to the width of the icon) when the icon is selected. The default icon decoration for icon box icons is that each icon has a label part and an image part (label image). The default icon decoration for stand alone icons is that each icon has an active label part, a label part, and an image part (activelabel label image). .IP "\fIiconImageMaximum\fP\ (class\ \fIIconImageMaximum\fP)" This resource specifies the maximum size of the icon \fBimage\fP. The resource value is \fBwidth\fIx\fBheight\fP (for example, 64x64). The maximum supported size is 128x128. The default value of this resource is 50x50. .IP "\fIiconImageMinimum\fP\ (class\ \fIIconImageMinimum\fP)" This resource specifies the minimum size of the icon \fBimage\fP. The resource value is \fBwidth\fIx\fBheight\fP (for example, 32x50). The minimum supported size is 16x16. The default value of this resource is 16x16. .IP "\fIiconPlacement\fP\ (class\ \fIIconPlacement\fP)" This resource specifies the icon placement scheme to be used. The resource value has the following syntax: .P .na .wH .in +5n \fBprimary_layout secondary_layout [tight]\fP .wH .in -5n .ad .P The layout values are one of the following: .P .ne 1.5i .sp 1 .in 0 .KS .TS center; lb lb l l. Value Description _ top Lay the icons out top to bottom. bottom Lay the icons out bottom to top. left Lay the icons out left to right. right Lay the icons out right to left. .TE .KE .in .sp 1 .PP A horizontal (vertical) layout value should not be used for both the \fBprimary_layout\fP and the \fBsecondary_layout\fP (for example, don't use top for the \fBprimary_layout\fP and bottom for the \fBsecondary_layout\fP). The \fBprimary_layout\fP indicates whether, when an icon placement is done, the icon is placed in a row or a column and the direction of placement. The \fBsecondary_layout\fP indicates where to place new rows or columns. For example, top right indicates that icons should be placed top to bottom on the screen and that columns should be added from right to left on the screen. The default placement is left bottom (icons are placed left to right on the screen, with the first row on the bottom of the screen, and new rows added from the bottom of the screen to the top of the screen). A \fBtight\fP value places icons with zero spacing in between icons. This value is useful for aesthetic reasons, as well as X-terminals with small screens. .IP "\fIiconPlacementMargin\fP\ (class\ \fIIconPlacementMargin\fP)" This resource sets the distance between the edge of the screen and the icons that are placed along the edge of the screen. The value should be greater than or equal to 0. A default value (see below) is used if the value specified is invalid. The default value for this resource is equal to the space between icons as they are placed on the screen (this space is based on maximizing the number of icons in each row and column). .IP "\fIinteractivePlacement\fP\ (class\ \fIInteractivePlacement\fP)" This resource controls the initial placement of new windows on the screen. If the value is True, the pointer shape changes before a new window is placed on the screen to indicate to the user that a position should be selected for the upper-left hand corner of the window. If the value is False, windows are placed according to the initial window configuration attributes. The default value of this resource is False. .IP "\fIkeyBindings\fP\ (class\ \fIKeyBindings\fP)" This resource identifies the set of key bindings for window management functions. If specified, these key bindings \fBreplace\fP the built-in default bindings. The named set of key bindings is specified in \fImwm\fP resource description file. The default value for this resource is "DefaultKeyBindings". .IP "\fIkeyboardFocusPolicy\fP\ (class\ \fIKeyboardFocusPolicy\fP)" If set to pointer, the keyboard focus policy is to have the keyboard focus set to the client window that contains the pointer (the pointer could also be in the client window decoration that \fImwm\fP adds). If set to explicit, the policy is to have the keyboard focus set to a client window when the user presses button 1 with the pointer on the client window or any part of the associated \fImwm\fP decoration. The default value for this resource is explicit. .IP "\fIlimitResize\fP\ (class\ \fILimitResize\fP)" If this resource is True, the user is not allowed to resize a window to greater than the maximum size. The default value for this resource is True. .IP "\fIlowerOnIconify\fP\ (class\ \fILowerOnIconify\fP)" If this resource is given the default value of True, a window's icon appears on the bottom of the window stack when the window is minimized (iconified). A value of False places the icon in the stacking order at the same place as its associated window. The default value of this resource is True. .IP "\fImaximumMaximumSize\fP\ (class\ \fIMaximumMaximumSize\fP)" This resource is used to limit the maximum size of a client window as set by the user or client. The resource value is \fBwidth\fIx\fBheight\fP (for example, 1024x1024) where the width and height are in pixels. The default value of this resource is twice the screen width and height. .IP "\fImoveOpaque\fP\ (class\ \fIMoveOpaque\fP)" This resource controls whether the actual window is moved or a rectangular outline of the window is moved. A default value of False displays a rectangular outline on moves. .IP "\fImoveThreshold\fP\ (class\ \fIMoveThreshold\fP)" This resource is used to control the sensitivity of dragging operations that move windows and icons. The value of this resource is the number of pixels that the locator is moved with a button down before the move operation is initiated. This is used to prevent window/icon .ne 3 movement when you click or double-click and there is unintentional pointer movement with the button down. The default value of this resource is 4 (pixels). .IP "\fImultiScreen\fP\ (class\ \fIMultiScreen\fP)" This resource, if True, causes \fImwm\fP to manage all the screens on the display. If False, \fImwm\fP manages only a single screen. The default value is False. .IP "\fIpassButtons\fP\ (class\ \fIPassButtons\fP)" This resource indicates whether or not button press events are passed to clients after they are used to do a window manager function in the client context. If the resource value is False, the button press is not passed to the client. If the value is True, the button press is passed to the client window. The window manager function is done in either case. The default value for this resource is False. .IP "\fIpassSelectButton\fP\ (class\ \fIPassSelectButton\fP)" This resource indicates whether or not to pass the select button press events to clients after they are used to do a window manager function in the client context. If the resource value is False, then the button press will not be passed to the client. If the value is True, the button press is passed to the client window. The window manager function is done in either case. The default value for this resource is True. .IP "\fIpositionIsFrame\fP\ (class\ \fIPositionIsFrame\fP)" This resource indicates how client window position information (from the WM_NORMAL_HINTS property and from configuration requests) is to be interpreted. If the resource value is True, the information is interpreted as the position of the MWM client window frame. If the value is False, it is interpreted as being the position of the client area of the window. The default value of this resource is True. .IP "\fIpositionOnScreen\fP\ (class\ \fIPositionOnScreen\fP)" This resource is used to indicate that windows should initially be placed (if possible) so that they are not clipped by the edge of the screen (if the resource value is True). If a window is larger than the size of the screen, at least the upper-left corner of the window is on-screen. If the resource value is False, windows are placed in the requested position even if totally off-screen. The default value of this resource is True. .IP "\fIquitTimeout\fP\ (class\ \fIQuitTimeout\fP)" This resource specifies the amount of time (in milliseconds) that \fImwm\fP will wait for a client to update the WM_COMMAND property after \fImwm\fP has sent the WM_SAVE_YOURSELF message. The default value of this resource is 1000 (ms). (Refer to the f.kill function description for additional information.) .IP "\fIraiseKeyFocus\fP\ (class\ \fIRaiseKeyFocus\fP)" This resource is available only when the keyboard input focus policy is explicit. When set to True, this resource specifies that a window raised by means of the f.normalize_and_raise function also receives the input focus. The default value of this resource is False. .IP "\fIresizeBorderWidth\fP\ (class\ \fIResizeBorderWidth\fP)" This resource specifies the width (in pixels) of a client window frame border with resize handles. The specified border width includes the 3-D shadows. The default value is based on the size and resolution of the screen. .IP "\fIresizeCursors\fP\ (class\ \fIResizeCursors\fP)" This is used to indicate whether the resize cursors are always displayed when the pointer is in the window size border. If True, the cursors are shown, otherwise the window manager cursor is shown. The default value is True. .IP "\fIscreens\fP\ (class\ \fIScreens\fP)" This resource specifies the resource names to use for the screens managed by \fImwm\fP. If \fImwm\fP is managing a single screen, only the first name in the list is used. If \fImwm\fP is managing multiple screens, the names are assigned to the screens in order, starting with screen 0. Screen 0 gets the first name, screen 1 the second name, and so on. The default screen names are 0, 1, and so on. .nL .ne 6 .IP "\fIshowFeedback\fP\ (class\ \fIShowFeedback\fP)" This resource controls whether or not feedback windows or confirmation dialogs are displayed. A feedback window shows a client window's initial placement and shows position and size during move and resize operations. Confirmation dialogs can be displayed for certain operations. .PP The value for this resource is a list of names of the feedback options to be enabled or disabled; the names must be separated by a space. If an option is preceded by a minus sign, that option is excluded from the list. The \fBsign\fP of the first item in the list determines the initial set of options. If the sign of the first option is minus, \fImwm\fP assumes all options are present and starts subtracting from that set. If the sign of the first decoration is plus (or not specified), \fImwm\fP starts with no options and builds up a list from the resource. .PP The names of the feedback options are shown below: .P .ne 2i .sp 1 .in 0 .KS .TS center; lB lB l l. Name Description _ all Show all feedback (Default value) behavior Confirm behavior switch kill Confirm on receipt of KILL signal move Show position during move none Show no feedback placement Show position and size during initial placement quit Confirm quitting \fImwm\fP resize Show size during resize restart Confirm \fImwm\fP restart .TE .KE .in .sp 1 .PP .ne 15 The following command line illustrates the syntax for showFeedback: .PP .sp 1 .in 0 .KS .TS tab( ); l l . \fIMwm*showFeedback: placement resize behavior restart\fP .TE .KE .in .sp 1 .PP This resource specification provides feedback for initial client placement and resize, and enables the dialog boxes to confirm the restart and set behavior functions. It disables feedback for the move function. The default value for this resource is all. .IP "\fIstartupKeyFocus\fP\ (class\ \fIStartupKeyFocus\fP)" This resource is available only when the keyboard input focus policy is explicit. When given the default value of True, a window gets the keyboard input focus when the window is mapped (that is, initially managed by the window manager). It is recommended that both \fIautoKeyFocus\fP and \fIstartupKeyFocus\fP be True to work with tear off menus. The default value is True. .IP "\fItransientDecoration\fP\ (class\ \fITransientDecoration\fP)" This controls the amount of decoration that \fImwm\fP puts on transient windows. The decoration specification is exactly the same as for the \fIclientDecoration\fP (client specific) resource. Transient windows are identified by the WM_TRANSIENT_FOR property, which is added by the client to indicate a relatively temporary window. The default value for this resource is menu title (that is, transient windows have frame borders and a titlebar with a window menu button). .PP An application can also specify which decorations \fImwm\fP should apply to its windows. If it does so, \fImwm\fP applies only those decorations indicated by both the application and the \fItransientDecoration\fP resource. Otherwise, \fImwm\fP applies the decorations indicated by the \fItransientDecoration\fP resource. For more information see the description of \fIXmNmwmDecorations\fP on the \fIVendorShell(3X)\fP reference page. .IP "\fItransientFunctions\fP\ (class\ \fITransientFunctions\fP)" This resource is used to indicate which window management functions are applicable (or not applicable) to transient windows. The function specification is exactly the same as for the \fIclientFunctions\fP (client specific) resource. The default value for this resource is -minimize -maximize. .PP An application can also specify which functions \fImwm\fP should apply to its windows. If it does so, \fImwm\fP applies only those functions indicated by both the application and the \fItransientFunctions\fP resource. Otherwise, \fImwm\fP applies the functions indicated by the \fItransientFunctions\fP resource. For more information see the description of \fIXmNmwmFunctions\fP on the \fIVendorShell(3X)\fP reference page. .IP "\fIuseIconBox\fP\ (class\ \fIUseIconBox\fP)" If this resource is given a value of True, icons are placed in an icon box. When an icon box is not used, the icons are placed on the root window (default value). .nL .ne 15 .IP "\fIwMenuButtonClick\fP\ (class\ \fIWMenuButtonClick\fP)" This resource indicates whether a click of the mouse when the pointer is over the window menu button posts and leaves posted the window menu. If the value given this resource is True, the menu remains posted. True is the default value for this resource. .IP "\fIwMenuButtonClick2\fP\ (class\ \fIWMenuButtonClick2\fP)" When this resource is given the default value of True, a double-click action on the window menu button does an f.kill function. .nL .ne 2i .SS "Client Specific Resources" The syntax for specifying client specific resources is .P .na .wH .in +5n \fIMwm*\fBclient_name_or_class\fI*\fBresource_id\fP .wH .in -5n .ad .P For example, \fIMwm*mterm*windowMenu\fP is used to specify the window menu to be used with mterm clients. The syntax for specifying client specific resources for all classes of clients is .P .na .wH .in +5n \fIMwm*\fBresource_id\fP .wH .in -5n .ad .P Specific client specifications take precedence over the specifications for all clients. For example, \fIMwm*windowMenu\fP is used to specify the window menu to be used for all classes of clients that don't have a window menu specified. .P The syntax for specifying resource values for windows that have an unknown name and class (that is, windows that do not have a WM_CLASS property associated with them) is .P .na .wH .in +5n \fIMwm*defaults*\fBresource_id\fP .wH .in -5n .ad .PP For example, \fIMwm*defaults*iconImage\fP is used to specify the icon image to be used for windows that have an unknown name and class. .PP .ne 4 The following client specific resources can be specified: .PP .wH .in 0 .sp 1 .in 0 .KS .TS center; cb sss lb lb lb lb l l l l . Client Specific Resources Name Class Value Type Default _ clientDecoration ClientDecoration string all clientFunctions ClientFunctions string all focusAutoRaise FocusAutoRaise T/F varies iconImage IconImage pathname (image) iconImageBackground Background color T{ icon .nL background T} iconImageBottomShadowColor Foreground color T{ icon bottom .nL shadow T} iconImageBottomShadowPixmap T{ BottomShadow- .nL Pixmap T} color T{ icon bottom .nL shadow .nL pixmap T} iconImageForeground Foreground color varies iconImageTopShadowColor Background color T{ icon top .nL shadow .nL color T} iconImageTopShadowPixmap T{ TopShadow- .nL Pixmap T} color T{ icon top .nL shadow .nL pixmap T} matteBackground Background color background matteBottomShadowColor Foreground color T{ bottom .nL shadow .nL color T} matteBottomShadowPixmap T{ BottomShadow- .nL Pixmap T} color T{ bottom .nL shadow .nL pixmap T} matteForeground Foreground color foreground matteTopShadowColor Background color T{ top shadow .nL color T} matteTopShadowPixmap T{ TopShadow- .nL Pixmap T} color T{ top shadow .nL pixmap T} matteWidth MatteWidth pixels 0 maximumClientSize MaximumClientSize T{ wxh .nL vertical .nL horizontal T} T{ fill the .nL screen T} useClientIcon UseClientIcon T/F F usePPosition UsePPosition string nonzero windowMenu WindowMenu string T{ "Default- .nL Window- .nL Menu" T} .TE .KE .in .sp 1 .wH .in .PP .IP "\fIclientDecoration\fP\ (class\ \fIClientDecoration\fP)" This resource controls the amount of window frame decoration. The resource is specified as a list of decorations to specify their inclusion in the frame. If a decoration is preceded by a minus sign, that decoration is excluded from the frame. The \fBsign\fP of the first item in the list determines the initial amount of decoration. If the sign of the first decoration is minus, \fImwm\fP assumes all decorations are present and starts subtracting from that set. If the sign of the first decoration is plus (or not specified), then \fImwm\fP starts with no decoration and builds up a list from the resource. .PP An application can also specify which decorations \fImwm\fP should apply to its windows. If it does so, \fImwm\fP applies only those decorations indicated by both the application and the \fIclientDecoration\fP resource. Otherwise, \fImwm\fP applies the decorations indicated by the \fIclientDecoration\fP resource. For more information see the description of \fIXmNmwmDecorations\fP on the \fIVendorShell(3X)\fP reference page. .nL .ne 25 .sp 1 .in 0 .KS .TS- center; lb lb l l. Name Description _ all Include all decorations (default value) border Window border maximize Maximize button (includes title bar) minimize Minimize button (includes title bar) none No decorations resizeh Border resize handles (includes border) menu Window menu button (includes title bar) title Title bar (includes border) .TE .KE .in .sp 1 .P Examples: .P \fIMwm*XClock.clientDecoration: -resizeh -maximize\fP .P This removes the resize handles and maximize button from XClock windows. .P \fIMwm*XClock.clientDecoration: menu minimize border\fP .P This does the same thing as above. Note that either \fImenu\fP or \fIminimize\fP implies \fItitle\fP. .IP "\fIclientFunctions\fP\ (class\ \fIClientFunctions\fP)" This resource is used to indicate which \fImwm\fP functions are applicable (or not applicable) to the client window. The value for the resource is a list of functions. If the first function in the list has a minus sign in front of it, then \fImwm\fP starts with all functions and subtracts from that set. If the first function in the list has a plus sign in front of it, then \fImwm\fP starts with no functions and builds up a list. Each function in the list must be preceded by the appropriate plus or minus sign and separated from the next function by a space. .PP An application can also specify which functions \fImwm\fP should apply to its windows. If it does so, \fImwm\fP applies only those functions indicated by both the application and the \fIclientFunctions\fP resource. Otherwise, \fImwm\fP applies the functions indicated by the \fIclientFunctions\fP resource. For more information see the description of \fIXmNmwmFunctions\fP on the \fIVendorShell(3X)\fP reference page. .PP .ne 25 The table below lists the functions available for this resource: .P .ne 2.5i .sp 1 .in 0 .KS .TS center; lb lb l l. Name Description _ all Include all functions (default value) none No functions resize f.resize move f.move minimize f.minimize maximize f.maximize close f.kill .TE .KE .in .sp 1 .P .ne 3i .IP "\fIfocusAutoRaise\fP\ (class\ \fIFocusAutoRaise\fP)" When the value of this resource is True, clients are raised when they get the keyboard input focus. If the value is False, the stacking of windows on the display is not changed when a window gets the keyboard input focus. The default value is True when the keyboardFocusPolicy is explicit and False when the keyboardFocusPolicy is pointer. .IP "\fIiconImage\fP\ (class\ \fIIconImage\fP)" This resource can be used to specify an icon image for a client (for example, "Mwm*myclock*iconImage"). The resource value is a pathname for a bitmap file. The value of the (client specific) useClientIcon resource is used to determine whether or not user supplied icon images are used instead of client supplied icon images. The default value is to display a built-in window manager icon image. .IP "\fIiconImageBackground\fP\ (class\ \fIBackground\fP)" This resource specifies the background color of the icon image that is displayed in the image part of an icon. The default value of this resource is the icon background color (that is, specified by "Mwm*background or Mwm*icon*background). .nL .ne 15 .IP "\fIiconImageBottomShadowColor\fP\ (class\ \fIForeground\fP)" This resource specifies the bottom shadow color of the icon image that is displayed in the image part of an icon. The default value of this resource is the icon bottom shadow color (that is, specified by Mwm*icon*bottomShadowColor). .IP "\fIiconImageBottomShadowPixmap\fP\ (class\ \fIBottomShadowPixmap\fP)" This resource specifies the bottom shadow Pixmap of the icon image that is displayed in the image part of an icon. The default value of this resource is the icon bottom shadow Pixmap (that is, specified by Mwm*icon*bottomShadowPixmap). .IP "\fIiconImageForeground\fP\ (class\ \fIForeground\fP)" This resource specifies the foreground color of the icon image that is displayed in the image part of an icon. The default value of this resource varies depending on the icon background. .nL .ne 3i .IP "\fIiconImageTopShadowColor\fP\ (class\ \fIBackground\fP)" This resource specifies the top shadow color of the icon image that is displayed in the image part of an icon. The default value of this resource is the icon top shadow color (that is, specified by Mwm*icon*topShadowColor). .IP "\fIiconImageTopShadowPixmap\fP\ (class\ \fITopShadowPixmap\fP)" This resource specifies the top shadow Pixmap of the icon image that is displayed in the image part of an icon. The default value of this resource is the icon top shadow pixmap (that is, specified by Mwm*icon*topShadowPixmap). .IP "\fImatteBackground\fP\ \ (class\ \fIBackground\fP)" This resource specifies the background color of the matte, when \fImatteWidth\fP is positive. The default value of this resource is the client background color (that is, specified by "Mwm*background or Mwm*client*background). .IP "\fImatteBottomShadowColor\fP\ (class\ \fIForeground\fP)" This resource specifies the bottom shadow color of the matte, when \fImatteWidth\fP is positive. The default value of this resource is the client bottom shadow color (that is, specified by "Mwm*bottomShadowColor or Mwm*client*bottomShadowColor). .nL .ne 15 .IP "\fImatteBottomShadowPixmap\fP\ (class\ \fIBottomShadowPixmap\fP)" This resource specifies the bottom shadow Pixmap of the matte, when \fImatteWidth\fP is positive. The default value of this resource is the client bottom shadow pixmap (that is, specified by .na "Mwm*bottomShadowPixmap or Mwm*client*bottomShadowPixmap). .ad .IP "\fImatteForeground\fP\ (class\ \fIForeground\fP)" This resource specifies the foreground color of the matte, when \fImatteWidth\fP is positive. The default value of this resource is the client foreground color (that is, specified by "Mwm*foreground or Mwm*client*foreground). .nL .ne 3i .IP "\fImatteTopShadowColor\fP\ (class\ \fIBackground\fP)" This resource specifies the top shadow color of the matte, when \fImatteWidth\fP is positive. The default value of this resource is the client top shadow color (that is, specified by "Mwm*topShadowColor or Mwm*client*topShadowColor). .IP "\fImatteTopShadowPixmap\fP\ (class\ \fITopShadowPixmap\fP)" This resource specifies the top shadow pixmap of the matte, when \fImatteWidth\fP is positive. The default value of this resource is the client top shadow .ne 10 pixmap (that is, specified by "Mwm*topShadowPixmap or Mwm*client*topShadowPixmap). .IP "\fImatteWidth\fP\ (class\ \fIMatteWidth\fP)" This resource specifies the width of the optional matte. The default value is 0, which effectively disables the matte. .IP "\fImaximumClientSize\fP\ (class\ \fIMaximumClientSize\fP)" This resource is either a size specification or a direction that indicates how a client window is to be maximized. The resource value can be specified as a size specification \fBwidth\fIx\fBheight\fP. The width and height are interpreted in the units that the client uses (for example, for terminal emulators this is generally characters). Alternately, "vertical" or "horizontal" can be specified to indicate the direction in which the client maximizes. .PP If this resource is not specified, the maximum size from the WM_NORMAL_HINTS property is used if set. Otherwise the default value is the size where the client window with window management borders fills the screen. When the maximum client size is not determined by the maximumClientSize resource, the maximumMaximumSize resource value is used as a constraint on the maximum size. .IP "\fIuseClientIcon\fP\ (class\ \fIUseClientIcon\fP)" If the value given for this resource is True, a client-supplied icon image takes precedence over a user-supplied icon image. The default value is False, giving the user-supplied icon image higher precedence than the client-supplied icon image. .IP "\fIusePPosition\fP\ (class\ \fIUsePPosition\fP)" This resource specifies whether Mwm honors program specified position \fIPPosition\fP specified in the WM_NORMAL_HINTS property in the absence of an user specified position. Setting this resource to on, causes \fImwm\fP to always honor program specified position. Setting this resource to off, causes \fImwm\fP to always ignore program specified position. Setting this resource to the default value of nonzero cause \fImwm\fP to honor program specified position other than (0,0). .IP "\fIwindowMenu\fP\ (class\ \fIWindowMenu\fP)" This resource indicates the name of the menu pane that is posted when the window menu is popped up (usually by pressing button 1 on the window menu button on the client window frame). Menu panes are specified in the MWM resource description file. Window menus can be customized on a client class basis by specifying resources of the form \fIMwm*\fBclient_name_or_class\fI*windowMenu\fP (see "Mwm Resource Description File Syntax"). The default value of this resource is "DefaultWindowMenu". .SS "Resource Description File" .PP The MWM resource description file is a supplementary resource file that contains resource descriptions that are referred to by entries in the defaults files (.Xdefaults, app-defaults/Mwm). It contains descriptions of resources that are to be used by \fImwm\fP, and that cannot be easily encoded in the defaults files (a bitmap file is an analogous type of resource description file). A particular \fImwm resource descriptionfile\fP can be selected using the \fIconfigFile\fP resource. .P .nL .ne 20 The following types of resources can be described in the \fImwm\fP resource description file: .IP "\fIButtons\fP" Window manager functions can be bound (associated) with button events. .IP "\fIKeys\fP" Window manager functions can be bound (associated) with key press events. .IP "\fIMenus\fP" Menu panes can be used for the window menu and other menus posted with key bindings and button bindings. .SS "mwm Resource Description File Syntax" The \fImwm\fP resource description file is a standard text file that contains items of information separated by blanks, tabs, and newline characters. Blank lines are ignored. Items or characters can be quoted to avoid special interpretation (for example, the comment character can be quoted to prevent it from being interpreted as the comment character). A quoted item can be contained in double quotes (\fI"\fP). Single characters can be quoted by preceding them by the backslash character (\fI\\\fP). All text from an unquoted \fI#\fP to the end of the line is regarded as a comment and is not interpreted as part of a resource description. If \fI!\fP is the first character in a line, the line is regarded as a comment. If a line ends in a backslash character (\fI\\\fP), the next line is considered a continuation of that line. Window manager functions can be accessed with button and key bindings, .ne 10 and with window manager menus. Functions are indicated as part of the specifications for button and key binding sets, and menu panes. The function specification has the following syntax: .P .ne 1i .sp 1 .in 0 .KS .TS tab( ), center; ll. \fBfunction\fP = \fBfunction_name\fP [\fBfunction_args\fP] \fBfunction_name\fP = \fBwindow manager function\fP \fBfunction_args\fP = {\fBquoted_item\fI \fBunquoted_item\fP} .TE .KE .in .sp 1 .P The following functions are supported. If a function is specified that isn't one of the supported functions, then it is interpreted by \fImwm\fP as \fBf.nop\fP. .IP "\fIf.beep\fP" This function causes a beep. .IP "\fIf.circle_down\fP\ [\fIicon\fP\ \ \fIwindow\fP]" This function causes the window or icon that is on the top of the window stack to be put on the bottom of the window stack (so that it no longer obscures any other window or icon). This function affects only those windows and icons that obscure other windows and icons, or that are obscured by other windows and icons. Secondary windows (that is, transient windows) are restacked with their associated primary window. Secondary windows always stay on top of the associated primary window and there can be no other primary windows between the secondary windows and their primary window. If an \fIicon\fP function argument is specified, the function applies only to icons. If a \fIwindow\fP function argument is specified, the function applies only to windows. .IP "\fIf.circle_up\fP\ [\fIicon\fP\ \ \fIwindow\fP]" This function raises the window or icon on the bottom of the window stack (so that it is not obscured by any other windows). This function affects only those windows and icons that obscure other windows and icons, or that are obscured by other windows and icons. Secondary windows (that is, transient windows) are restacked with their associated primary window. If an \fBicon\fP function argument is specified, the function applies only to icons. If a \fBwindow\fP function argument is specified, the function applies only to windows. .nL .ne 2i .IP "\fIf.exec\fP\ or\ \fI!\fP" This function causes \fBcommand\fP to be executed (using the value of the MWMSHELL environment variable if it is set, otherwise the value of the SHELL environment variable if it is set, otherwise \fB/bin/sh\fP). The \fI!\fP notation can be used in place of the \fIf.exec\fP function name. .IP "\fIf.focus_color\fP" This function sets the colormap focus to a client window. If this function is done in a root context, the default colormap (set up by the \fBX Window System\fP for the screen where MWM is running) is installed and there is no specific client window colormap focus. This function is treated as \fBf.nop\fP if colormapFocusPolicy is not explicit. .IP "\fIf.focus_key\fP" This function sets the keyboard input focus to a client window or icon. This function is treated as \fBf.nop\fP if keyboardFocusPolicy is not explicit or the function is executed in a root context. .IP "\fIf.kill\fP" This function is used to terminate a client. If the WM_DELETE_WINDOW protocol is set up, the client is sent a client message event, indicating that the client window should be deleted. If the WM_SAVE_YOURSELF protocol is set up, the client is sent a client message event, indicating that the client needs to prepare to be terminated. If the client does not have the WM_DELETE_WINDOW or WM_SAVE_YOURSELF protocol set up, this function causes a client's X connection to be terminated (usually resulting in termination of the client). Refer to the description of the quitTimeout resource and the WM_PROTOCOLS property. .IP "\fIf.lower\fP\ [\fI\-\fBclient\fP \fIwithin\fP\ \ \fIfreeFamily\fP]" This function lowers a primary window to the bottom of the global window stack (where it obscures no other window) and lowers the secondary window (transient window or dialog box) within the client family. The arguments to this function are mutually exclusive. .PP The \fBclient\fP argument indicates the name or class of a client to lower. If the \fBclient\fP argument is not specified, the context that the function was invoked in indicates the window or icon to lower. .PP Specifying \fIwithin\fP lowers the secondary window within the family (staying above the parent) but does not lower the client family in the global window stack. .PP Specifying \fIfreeFamily\fP lowers the window to the bottom of the global windows stack from its local family stack. .IP "\fIf.maximize\fP" This function causes a client window to be displayed with its maximum size. .IP "\fIf.menu\fP" This function associates a cascading (pull-right) menu with a menu pane entry or a menu with a button or key binding. The \fBmenu_name\fP function argument identifies the menu to be used. .IP "\fIf.minimize\fP" This function causes a client window to be minimized (iconified). When a window is minimized when no icon box is used, its icon is placed on the bottom of the window stack (so that it obscures no other window). If an icon box is used, the client's icon changes to its iconified form inside the icon box. Secondary windows (that is, transient windows) are minimized with their associated primary window. There is only one icon for a primary window and all its secondary windows. .IP "\fIf.move\fP" This function causes a client window to be interactively moved. .IP "\fIf.next_cmap\fP" This function installs the next colormap in the list of colormaps for the window with the colormap focus. .IP "\fIf.next_key\fP\ [\fIicon\fP\ \ \fIwindow\fP\ \ \fItransient\fP]" This function sets the keyboard input focus to the next window/icon in the set of windows/icons managed by the window manager (the ordering of this set is based on the stacking of windows on the screen). This function is treated as \fBf.nop\fP if keyboardFocusPolicy is not explicit. The keyboard input focus is moved only to windows that do not have an associated secondary window that is application modal. If the \fItransient\fP argument is specified, transient (secondary) windows are traversed (otherwise, if only \fIwindow\fP is specified, traversal is done only to the last focused window in a transient group). If an \fIicon\fP function argument is specified, the function applies only to icons. If a \fIwindow\fP function argument is specified, the function applies only to windows. .IP "\fIf.nop\fP" This function does nothing. .IP "\fIf.normalize\fP" This function causes a client window to be displayed with its normal size. Secondary windows (that is, transient windows) are placed in their normal state along with their associated primary window. .nL .ne 10 .IP "\fIf.normalize_and_raise\fP" This function causes the corresponding client window to be displayed with its normal size and raised to the top of the window stack. Secondary windows (that is, transient windows) are placed in their normal state along with their associated primary window. .IP "\fIf.pack_icons\fP" This function is used to relayout icons (based on the layout policy being used) on the root window or in the icon box. In general this causes icons to be "packed" into the icon grid. .nL .ne 10 .IP "\fIf.pass_keys\fP" This function is used to enable/disable (toggle) processing of key bindings for window manager functions. When it disables key binding processing, all keys are passed on to the window with the keyboard input focus and no window manager functions are invoked. If the \fBf.pass_keys\fP function is invoked with a key binding to disable key-binding processing, the same key binding can be used to enable key-binding processing. .IP "\fIf.post_wmenu\fP" This function is used to post the window menu. If a key is used to post the window menu and a window menu button is present, the window menu is automatically placed with its top-left corner at the bottom-left corner of the window menu button for the client window. If no window menu button is present, the window menu is placed at the top-left corner of the client window. .IP "\fIf.prev_cmap\fP" This function installs the previous colormap in the list of colormaps for the window with the colormap focus. .IP "\fIf.prev_key\fP\ [\fIicon\fP\ \ \fIwindow\fP\ \ \fItransient\fP]" This function sets the keyboard input focus to the previous window/icon in the set of windows/icons managed by the window manager (the ordering of this set is based on the stacking of windows on the screen). This function is treated as \fBf.nop\fP if keyboardFocusPolicy is not explicit. The keyboard input focus is moved only to windows that do not have an associated secondary window that is application modal. If the \fBtransient\fP argument is specified, transient (secondary) windows are traversed (otherwise, if only \fBwindow\fP is specified, traversal is done only to the last focused window in a transient group). If an \fBicon\fP function argument is specified, the function applies only to icons. If an \fBwindow\fP function argument is specified, the function applies only to windows. .IP "\fIf.quit_mwm\fP" This function terminates \fImwm\fP (but NOT the X window system). .nL .ne 8 .IP "\fIf.raise\fP\ [\fI\-\fBclient\fP \fIwithin freeFamily]\fP" This function raises a primary window to the top of the global window stack (where it is obscured by no other window) and raises the secondary window (transient window or dialog box) within the client family. The arguments to this function are mutually exclusive. .PP The \fBclient\fP argument indicates the name or class of a client to lower. If the \fBclient\fP is not specified, the context that the function was invoked in indicates the window or icon to lower. .PP Specifying \fIwithin\fP raises the secondary window within the family but does not raise the client family in the global window stack. .PP Specifying \fIfreeFamily\fP raises the window to the top of its local family stack and raises the family to the top of the global window stack. .IP "\fIf.raise_lower\fP\ [\fIwithin freeFamily]\fP" This function raises a primary window to the top of the global window stack if it is partially obscured by another window; otherwise, it lowers the window to the bottom of the window stack. The arguments to this function are mutually exclusive. .PP Specifying \fIwithin\fP raises a secondary window within the family (staying above the parent window), if it is partially obscured by another window in the application's family; otherwise, it lowers the window to the bottom of the family stack. It has no effect on the global window stacking order. .PP Specifying \fIfreeFamily\fP raises the window to the top of its local family stack, if obscured by another window, and raises the family to the top of the global window stack; otherwise, it lowers the window to the bottom of its local family stack and lowers the family to the bottom of the global window stack. .IP "\fIf.refresh\fP" This function causes all windows to be redrawn. .IP "\fIf.refresh_win\fP" This function causes a client window to be redrawn. .IP "\fIf.resize\fP" This function causes a client window to be interactively resized. .IP "\fIf.restore\fP" This function restores the previous state of an icon's associated window. If a maximized window is iconified, then \fIf.restore\fP restores it to its maximized state. If a normal window is iconified, then \fIf.restore\fP restores it to its normalized state. .IP "\fIf.restore_and_raise\fP" This function restores the previous state of an icon's associated window and raises the window to the top of the window stack. If a maximized window is iconified, then \fIf.restore_and_raise\fP restores it to its maximized state and raises it to the top of the window stack. If a normal window is iconified, then \fIf.restore_and_raise\fP restores it to its normalized state and raises it to the top of the window stack. .IP "\fIf.restart\fP" This function causes \fImwm\fP to be restarted (effectively terminated and re-executed). .IP "\fIf.screen\fP\ [\fInext\fP \fIprev\fP \fIback\fP \fBscreen_number\fP]" This function causes the pointer to be warp to a specific screen number or to the \fInext\fP, \fIprevious\fP, or last visited (\fIback\fP) screen. The arguments to this function are mutually exclusive. .PP The \fBscreen_number\fP argument indicates the screen number that the pointer is to be warped. Screens are numbered starting from screen 0. .PP Specifying \fInext\fP cause the pointer to warp to the next managed screen (skipping over any unmanaged screens). .PP Specifying \fIprev\fP cause the pointer to warp to the previous managed screen (skipping over any unmanaged screens). .PP Specifying \fIback\fP cause the pointer to warp to the last visited screen. .IP "\fIf.send_msg\fP\ \fBmessage_number\fP" This function sends a client message of the type _MOTIF_WM_MESSAGES with the \fBmessage_type\fP indicated by the \fBmessage_number\fP function argument. The client message is sent only if \fBmessage_number\fP is included in the client's _MOTIF_WM_MESSAGES property. A menu item label is grayed out if the menu item is used to do \fBf.send_msg\fP of a message that is not included in the client's _MOTIF_WM_MESSAGES property. .IP "\fIf.separator\fP" This function causes a menu separator to be put in the menu pane at the specified location (the label is ignored). .nL .ne 10 .IP "\fIf.set_behavior\fP" This function causes the window manager to restart with the default behavior (if a custom behavior is configured) or revert to the custom behavior. By default this is bound to \fIShift\ Ctrl\ Meta\ !\fP. .IP "\fIf.title\fP" This function inserts a title in the menu pane at the specified location. .PP Each function may be constrained as to which resource types can specify the function (for example, menu pane) and also what context the function can be used in (for example, the function is done to the selected client window). Function contexts are .IP "\fIroot\fP" No client window or icon has been selected as an object for the function. .IP "\fIwindow\fP" A client window has been selected as an object for the function. This includes the window's title bar and frame. Some functions are applied only when the window is in its normalized state (for example, \fBf.maximize\fP) or its maximized state (for example, \fBf.normalize\fP). .IP "\fIicon\fP" An icon has been selected as an object for the function. .PP If a function's context has been specified as \fIiconwindow\fP and the function is invoked in an icon box, the function applies to the icon box, not to the icons inside. .PP If a function is specified in a type of resource where it is not supported or is invoked in a context that does not apply, the function is treated as \fBf.nop\fP. The following table indicates the resource types and function contexts in which window manager functions apply. .P .wH .in 0 .sp 1 .in 0 .KS .TS center; l l l. \fIFunction\fP \fIContexts\fP \fIResources\fP _ f.beep root, icon, window button, key, menu f.circle_down root, icon, window button, key, menu f.circle_up root, icon, window button, key, menu f.exec root, icon, window button, key, menu f.focus_color root, icon, window button, key, menu f.focus_key root, icon, window button, key, menu f.kill icon, window button, key, menu f.lower icon, window button, key, menu f.maximize icon, window(normal) button, key, menu f.menu root, icon, window button, key, menu f.minimize window button, key, menu f.move icon, window button, key, menu f.next_cmap root, icon, window button, key, menu f.next_key root, icon, window button, key, menu f.nop root, icon, window button, key, menu f.normalize icon, window(maximized) button, key, menu f.normalize_and_raise icon, window button, key, menu f.pack_icons root, icon, window button, key, menu f.pass_keys root, icon, window button, key, menu f.post_wmenu root, icon, window button, key f.prev_cmap root, icon, window button, key, menu f.prev_key root, icon, window button, key, menu f.quit_mwm root, icon, window button, key, menu (root only) f.raise icon, window button, key, menu f.raise_lower icon, window button, key, menu f.refresh root, icon, window button, key, menu f.refresh_win window button, key, menu f.resize window button, key, menu f.restore icon, window button, key, menu f.restore_and_raise icon, window button, key, menu f.restart root, icon, window button, key, menu (root only) f.screen root, icon, window button, key, menu f.send_msg icon, window button, key, menu f.separator root, icon, window menu f.set_behavior root, icon, window button, key, menu f.title root, icon, window menu .TE .KE .in .sp 1 .SS "Window Manager Event Specification" Events are indicated as part of the specifications for button and key-binding sets, and menu panes. .PP Button events have the following syntax: .PP .wH .in +4 .sp 1 .in 0 .KS .TS tab( ); l l. \fBbutton\fP = [\fBmodifier_list\fP]\fI<\fBbutton_event_name\fI>\fP \fBmodifier_list\fP = \fBmodifier_name\fP {\fBmodifier_name\fP} .TE .KE .in .sp 1 .wH .in -4 .PP All modifiers specified are interpreted as being exclusive (this means that only the specified modifiers can be present when the button event occurs). The following table indicates the values that can be used for \fBmodifier_name\fP.\*F .wH .FS .wH .FS The [Alt] key is frequently labeled [Extend] or [Meta]. Alt and Meta can be used interchangeably in event specification. .wH .FE .wH .FE .P .ne 2.5i .sp 1 .in 0 .KS .TS center; lfI lfI l l. \fIModifier\fP \fIDescription\fP _ Ctrl Control Key Shift Shift Key Alt Alt/Meta Key Meta Meta/Alt Key Lock Lock Key Mod1 Modifier1 Mod2 Modifier2 Mod3 Modifier3 Mod4 Modifier4 Mod5 Modifier5 .TE .KE .in .sp 1 .PP .ne 10 The following table indicates the values that can be used for \fBbutton_event_name\fP. .P .ne 4i .sp 1 .in 0 .KS .TS center; lfI lfI l l. \fIButton\fP \fIDescription\fP _ Btn1Down Button 1 Press Btn1Up Button 1 Release Btn1Click Button 1 Press and Release Btn1Click2 Button 1 Double-Click Btn2Down Button 2 Press Btn2Up Button 2 Release Btn2Click Button 2 Press and Release Btn2Click2 Button 2 Double-Click Btn3Down Button 3 Press Btn3Up Button 3 Release Btn3Click Button 3 Press and Release Btn3Click2 Button 3 Double-Click Btn4Down Button 4 Press Btn4Up Button 4 Release Btn4Click Button 4 Press and Release Btn4Click2 Button 4 Double-Click Btn5Down Button 5 Press Btn5Up Button 5 Release Btn5Click Button 5 Press and Release Btn5Click2 Button 5 Double-Click .TE .KE .in .sp 1 .PP .ne 2i Key events that are used by the window manager for menu mnemonics and for binding to window manager functions are single key presses; key releases are ignored. Key events have the following syntax: .PP .wH .in +4 .sp 1 .in 0 .KS .TS tab( ); l l. \fBkey\fP = [\fBmodifier_list\fP]\fI\fBkey_name\fP \fBmodifier_list\fP = \fBmodifier_name\fP {\fBmodifier_name\fP} .TE .KE .in .sp 1 .wH .in -4 .PP All modifiers specified are interpreted as being exclusive (this means that only the specified modifiers can be present when the key event occurs). Modifiers for keys .ne 7 are the same as those that apply to buttons. The \fBkey_name\fP is an X11 keysym name. Keysym names can be found in the keysymdef.h file (remove the \fBXK_\fP prefix). .SS "Button Bindings" The \fIbuttonBindings\fP resource value is the name of a set of button bindings that are used to configure window manager behavior. A window manager function can be done when a button press occurs with the pointer over a framed client window, an icon, or the root window. The context for indicating where the button press applies is also the context for invoking the window manager function when the button press is done (significant for functions that are context sensitive). .PP The button binding syntax is .P .na .wH .in +5n \fIButtons\fP \fBbindings_set_name\fP .nL \fI{\fP .nL \fBbutton\fP \fBcontext\fP \fBfunction\fP .nL \fBbutton\fP \fBcontext\fP \fBfunction\fP .nL . .nL . .nL \fBbutton\fP \fBcontext\fP \fBfunction\fP .nL \fI}\fP .wH .in -5n .ad .PP .ne 2i The syntax for the \fBcontext\fP specification is .P .sp 1 .in 0 .KS .TS tab( ), center; ll. \fBcontext\fP = \fBobject\fP[\fI\ \ \fBcontext\fP] \fBobject\fP = \fIroot icon window title frame border app\fP .TE .KE .in .sp 1 .P The context specification indicates where the pointer must be for the button binding to be effective. For example, a context of \fIwindow\fP indicates that the pointer must be over a client window or window management frame for the button binding to be effective. The \fIframe\fP context is for the window management frame around a client window (including the border and titlebar), the \fIborder\fP context is for the border part of the window management frame .ne 15 (not including the titlebar), the \fItitle\fP context is for the title area of the window management frame, and the \fIapp\fP context is for the application window (not including the window management frame). .P If an \fBf.nop\fP function is specified for a button binding, the button binding is not done. .SS "Key Bindings" The \fIkeyBindings\fP resource value is the name of a set of key bindings that are used to configure window manager behavior. A window manager function can be done when a particular key is pressed. The context in which the key binding applies is indicated in the key binding specification. The valid contexts are the same as those that apply to button bindings. .P The key binding syntax is .P .na .wH .in +5n \fIKeys\fP \fBbindings_set_name\fP .nL \fI{\fP .nL \fBkey\fP \fBcontext\fP \fBfunction\fP .nL \fBkey\fP \fBcontext\fP \fBfunction\fP .nL . .nL . .nL \fBkey\fP \fBcontext\fP \fBfunction\fP .nL \fI}\fP .wH .in -5n .ad .PP If an \fBf.nop\fP function is specified for a key binding, the key binding is not done. If an \fBf.post_wmenu\fP or \fBf.menu\fP function is bound to a key, \fImwm\fP will automatically use the same key for removing the menu from the screen after it has been popped up. .PP The \fBcontext\fP specification syntax is the same as for button bindings. For key bindings, the \fIframe\fP, \fItitle\fP, \fIborder\fP, and \fIapp\fP contexts are equivalent to the \fIwindow\fP context. The context for a key event is the window or icon that has the keyboard input focus (\fIroot\fP if no window or icon has the keyboard input focus). .nL .ne 8 .SS "Menu Panes" Menus can be popped up using the \fBf.post_wmenu\fP and \fBf.menu\fP window manager functions. The context for window manager functions that are done from a menu is \fBroot\fP, \fBicon\fP or \fBwindow\fP depending on how the menu was popped up. In the case of the \fBwindow\fP menu or menus popped up with a key binding, the location of the keyboard input focus indicates the context. For menus popped up using a button binding, the context of the button binding is the context of the menu. .P The menu pane specification syntax is .P .na .wH .in +5n \fIMenu\fP \fBmenu_name\fP .nL \fI{\fP .nL \fBlabel\fP [\fBmnemonic\fP] [\fBaccelerator\fP] \fBfunction\fP .nL \fBlabel\fP [\fBmnemonic\fP] [\fBaccelerator\fP] \fBfunction\fP .nL . .nL . .nL \fBlabel\fP [\fBmnemonic\fP] [\fBaccelerator\fP] \fBfunction\fP .nL \fI}\fP .wH .in -5n .ad .PP Each line in the \fBMenu\fP specification identifies the label for a menu item and the function to be done if the menu item is selected. Optionally a menu button mnemonic and a menu button keyboard accelerator may be specified. Mnemonics are functional only when the menu is posted and keyboard traversal applies. .PP The \fBlabel\fP may be a string or a bitmap file. The label specification has the following syntax: .P .sp 1 .in 0 .KS .TS tab( ), center; ll. \fBlabel\fP = \fBtext\fI \fBbitmap_file\fP \fBbitmap_file\fP = \fI@\fBfile_name\fP \fBtext\fP = \fBquoted_item\fI \fBunquoted_item\fP .TE .KE .in .sp 1 .P The string encoding for labels must be compatible with the menu font that is used. Labels are greyed out for menu items that do the \fBf.nop\fP function or an invalid function or a function that doesn't apply in the current context. .P .ne 5 A \fBmnemonic\fP specification has the following syntax .P .wH .in +4 .sp 1 .in 0 .KS .TS tab( ); l l. \fBmnemonic\fP = \fI_\fBcharacter\fP .TE .KE .in .sp 1 .wH .in -4 .PP The first matching \fBcharacter\fP in the label is underlined. If there is no matching \fBcharacter\fP in the label, no mnemonic is registered with the window manager for that label. Although the \fBcharacter\fP must exactly match a character in the label, the mnemonic does not execute if any modifier (such as Shift) is pressed with the character key. .PP The \fBaccelerator\fP specification is a key event specification with the same syntax as is used for key bindings to window manager functions. .SS Environment \fImwm\fP uses the environment variable HOME specifying the user's home directory. .PP \fImwm\fP uses the environment variable LANG specifying the user's choice of language for the \fImwm\fP message catalog and the \fImwm\fP resource description file. .PP \fImwm\fP uses the environment variables XFILESEARCHPATH, XUSERFILESEARCHPATH, XAPPLRESDIR, XENVIRONMENT, LANG, and HOME in determining search paths for resource defaults files. \fImwm\fP may also use XBMLANGPATH to search for bitmap files. .PP \fImwm\fP reads the $HOME/.motifbind file if it exists to install a virtual key bindings property on the root window. For more information on the content of the \&.motifbind file, see \fIVirtualBindings(3X)\fP. .PP .ne 2i \fImwm\fP uses the environment variable MWMSHELL (or SHELL, if MWMSHELL is not set), specifying the shell to use when executing commands via the \fBf.exec\fP function. .nL .ne 15 .SH Files .na \fI/usr/lib/X11/$LANG/system.mwmrc\fP .nL \fI/usr/lib/X11/system.mwmrc\fP .nL \fI/usr/lib/X11/app-defaults/Mwm\fP .nL \fI$HOME/Mwm\fP .nL \fI$HOME/.Xdefaults\fP .nL \fI$HOME/$LANG/.mwmrc\fP .nL \fI$HOME/.mwmrc\fP .nL \fI$HOME/.motifbind\fP .ad .SH RELATED INFORMATION .na \fIVendorShell(3X)\fP, \fIVirtualBindings(3X)\fP, \fIX(1)\fP, and \fIXmInstallImage(3X)\fP. .ad .\" $Header: neqn.1,v 78.1 96/02/12 16:31:22 ssa Exp $ .TA n .TH neqn 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME neqn \- format mathematical text for nroff .SH SYNOPSIS .CR neqn .RC [ -d .IR xy\| ] .RC [ -s .IR n\| ] .RC [ -f .IR n\| ] .RC [ -p .IR n\| ] .RI [ \|file \ ...\|] .SS Note The output of .CR neqn is very device-dependent. See the "WARNINGS" section. .SH DESCRIPTION .CR neqn is a preprocessor for .CR nroff (see .IR nroff (1)) for typesetting mathematical text on typewriter-like terminals. Its invocation is almost always of the following two forms or equivalent: .IP .CI neqn \0files\0 "| nroff | col" .IP .CI tbl \0files\0 "| neqn | nroff | col" .PP If no files are specified (or if .CR \- is specified instead of .IR file ), .CR neqn reads from standard input. A line beginning with .CR .EQ marks the start of an equation. The end of an equation is marked by a line beginning with .CR .EN . Neither of these lines is altered, which means that they can be defined in macro packages to get centering, numbering, etc. .PP It is also possible to designate two characters as .IR delimiters ; subsequent text between delimiters is then treated as .CR neqn input. Delimiters can be set to characters .I x and .I y with the command-line argument .CI -d xy or (more commonly) with the sequence .nf .IP .CR .EQ .CI delim \0xy .CR .EN .fi .PP The left and right delimiters can be the same character; the dollar sign .RC ( $ ) is often used as such a delimiter. Delimiters are turned off by .CR "delim off" (see the "WARNINGS" section). All text that is neither between delimiters nor between .CR .EQ and .CR .EN is passed through untouched. .EQ delim $$ .EN .PP Tokens within .CR neqn equations are separated by spaces, tabs, newlines, braces, double quotes, tildes, and circumflexes. Braces .RC ( {} ) are used for grouping; generally speaking, anywhere a single character such as .I x can appear, a complicated construction enclosed in braces can be used instead. Tilde .RC ( ~ ) represents a full space in the output; circumflex, .RC ( ^ ) half as much. .br .ift .vs +1p .br .ne 11 .SS Subscripts and Superscripts Subscripts and superscripts are produced using .CR sub and .CR sup as follows: .RS .ifn .TP 50 .ift .TP 70 .B Source Text .B Result .TP .C "x sub j" $x sub j$ .TP .C "a sub k sup 2" $a sub k sup 2$ .TP .C "e sup {x sup 2 + y sup 2}" $e sup {x sup 2 + y sup 2}$ .RE .br .ne 08 .SS Fractions Fractions are produced by using .CR over : .RS .ifn .TP 50 .ift .TP 70 .B Source Text .B Result .TP .C "a over b" $a over b$ .RE .br .ne 9 .SS Square Roots .CR sqrt produces square roots: .RS .ifn .TP 50 .ift .TP 70 .B Source Text .B Result .TP .C "1 over sqrt {ax sup 2+bx+c}" $1 over sqrt {ax sup 2 +bx+c}$ .RE .br .ne 9 .SS Upper and Lower Limits The keywords .CR from and .CR to specify lower and upper limits: .RS .ifn .TP 50 .ift .TP 70 .B Source Text .B Result .TP .C "lim from {n -> inf } sum from 0 to n x sub i" $lim from {n -> inf} ~ sum from 0 to n ~ x sub i$ .RE .br .ne 11 .SS Brackets and Braces Left and right brackets, braces, and such, of proper height are made with .CR left and .CR right : .RS .ifn .TP 50 .ift .TP 70 .B Source Text .B Result .TP .PD 0 .C "left [ {x sup 2 + y sup 2}" .TP .C " over alpha right ] ~=~ 1" .sp -2 \" hey! it works! $left [ {x sup 2 + y sup 2} over alpha right ] ~=~ 1$ .PD .RE .PP Legal characters after .CR left and .CR right are braces, brackets, bars, .CR c and .CR f for ceiling and floor, and .C """""" for nothing at all (useful for a right-side-only bracket). A .CR left .I char need not have a matching .CR right .IR char . .br .ne 9 .SS Vertical Piles Vertical piles of .I elements are made with .CR pile , .CR lpile , .CR cpile , and .CR rpile : .RS .ifn .TP 50 .ift .TP 70 .B Source Text .B Result .TP .C "pile {a above bb above ccc}" $pile {a above bb above ccc}$ .RE .PP Piles can have arbitrary numbers of elements; .CR lpile left justifies, .CR pile and .CR cpile center (but with different vertical spacing), and .CR rpile right justifies. .br .ne 12 .SS Matrices and Determinants Matrices are made with .CR matrix : .RS .ifn .TP 50 .ift .TP 70 .B Source Text .B Result .TP .PD 0 .C "left | { matrix {" .TP .C " lcol { x sub i above y sub 2 }" .TP .C " ccol { 1 above 234 } } } right |" .sp -2 $left | { matrix { lcol { x sub i above y sub 2 } ccol { 1 above 234 } } } right |$ .PD .RE .PP In addition, there is .CR rcol for a right-justified column. .br .ne 12 .SS Diacritical Marks Diacritical marks are made with .CR dot , .CR dotdot , .CR hat , .CR tilde , .CR bar , .CR vec , .CR dyad , and .CR under : .RS .ifn .TP 50 .ift .TP 70 .B Source Text .B Result .TP .C "x dot = f(t) bar" $x dot = f(t) bar$ .TP .C "y dotdot bar ~=~ n under" $y dotdot bar ~=~ n under$ .TP .C "x vec ~=~ y dyad" $x vec ~=~ y dyad$ .RE .if t .vs .EQ delim off .EN .SS Point Sizes and Fonts Point sizes and fonts can be changed with .CR size .I n or .CR size .CR + | \- \f2n\f1, .CR roman , .CR italic , .CR bold , and .CR font .IR n . Point sizes and fonts can be changed globally in a document by .CR gsize .I n and .CR gfont .IR n , or by the command-line arguments .CI -s n and .CI -f n\f1. .PP Normally, subscripts and superscripts are reduced by 3 points from the previous size; this can be changed by the command-line argument .CI -p n\f1. .SS Vertical Alignment Successive display arguments can be lined up. Place .CR mark before the desired lineup point in the first equation; place .CR lineup at the place that is to line up vertically in subsequent equations. .SS Shorthand Forms Shorthand forms can be defined or existing keywords redefined with .CR define : .IP .CI define \0thing\0%\0replacement\0% .PP defines a new token called .I thing that is replaced by .I replacement whenever it appears thereafter. The .I % can be any character that does not occur in .IR replacement . .SS Other Keywords Keywords such as .CR sum .EQ ( sum ), .EN .CR int .EQ ( int ), .EN .CR inf .EQ ( inf ), .EN and shorthands such as .CR >= .EQ (>=), .EN .CR != .EQ ( != ), .EN and .CR -> .EQ (->) .EN are recognized. Greek letters are spelled out in uppercase or lowercase as desired, as in .CR alpha .EQ ( alpha ) .EN or .CR GAMMA .EQ ( GAMMA ). .EN Mathematical words such as .CR sin , .CR cos , and .CR log are made Roman automatically. .CR nroff four-character escapes such as .CR \e(dd (\(dd) and .CR \e(bu (\(bu) can be used anywhere. .SS Verbatim Text Strings enclosed in double quotes (\c .C """\c" .I string\c .C """\c" ) are passed through untouched; this permits keywords to be entered as text, and can be used to communicate with .CR nroff when other methods fail. Details are given in the manuals cited below. .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_CTYPE determines the interpretation of text as single- or multibyte characters. .PP .CR LANG determines the language in which messages are displayed. .PP If .CR LC_CTYPE is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR neqn behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH WARNINGS To embolden digits, parentheses, etc., it is necessary to quote them, as in .C "bold ""12.3""\c .RI . Also see the "WARNINGS" section in .IR nroff (1). .PP Good practice dictates that if a delimiter is specified in a file, the .CR "delim off" directive should be included at the end of the file to prevent undesirable behavior when processing multiple files where a subsequent file may contain the delimiter character as part of regular text. .PP To properly display equations on terminal screens and other devices that do not support reverse line feeds, .CR nroff output should be piped through .CR col (see .IR col (1)). .PP The display on devices that do not support partial linefeeds is often difficult to understand; Greek characters and other symbols are often not well supported and can mismatched printing of bold words on the same line (see a printed version of the "Other Keywords" subsection above). Consider using "computer-program" coding instead. .SH SEE ALSO col(1), mm(1), nroff(1), tbl(1), mm(5). .PP .IR "Typesetting Mathematics \(mi User's Guide" , by B.W. Kernighan and L.L. Cherry. .PP .IR "New Graphic Symbols for EQN and NEQN" , by C. Scrocca. .EQ delim off .EN .\" index@\f4neqn\f1 \- format mathematical text for nroff@@@\f3neqn(1)\f1 .\" index@format: format mathematical text for nroff@@@\f3neqn(1)\f1 .\" index@preprocess mathematical text for nroff@@@\f3neqn(1)\f1 .\" index@mathematical text, preprocess and format for nroff@@@\f3neqn(1)\f1 .\" index@text, mathematical, preprocess and format for nroff@@@\f3neqn(1)\f1 .\" .\" toc@\f3neqn(1)\f1:\0\0\f4neqn\f1@@@format mathematical text for nroff .\" .\" fileset_database@neqn.1 USER-CMDS-MAN .\" $Header: netstat.1,v 78.1 95/12/20 11:01:35 ssa Exp $ .TA n .TH netstat 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME netstat \- show network status .SH SYNOPSIS .C netstat .RC [ -aAn ] .RC [ -f .IR address-family\| ] .RI [ \|system\| .RI [ \|core\| ] ] .br .C netstat .RC [ -mMnrsv ] .RC [ -f .IR address-family\| ] .RC [ -p .IR protocol\| ] .RI [ \|system\| .RI [ \|core\| ] ] .br .C netstat .RC [ -gin ] .RC [ -I .IR interface\| ] .RI [ \|interval\| ] .RI [ \|system\| .RI [ \|core\| ] ] .SH DESCRIPTION .C netstat displays statistics for network interfaces and protocols, as well as the contents of various network-related data structures. The output format varies according to the options selected. Some options are ignored when used in combination with other options. Generally, the .C netstat command takes one of the three forms shown above: .RS .TP 3 \(bu The first form of the command displays a list of active sockets for each protocol. .TP \(bu The second form displays the contents of one of the other network data structures according to the option selected. .TP \(bu The third form displays configuration information for each network interface. It also displays network traffic data on configured network interfaces, optionally updated at each .IR interval , measured in seconds. .RE .PP Options are interpreted as follows: .RS .TP 18 .C -a Show the state of all sockets, including passive sockets used by server processes. When .C netstat is used without any options (except .C -A and .CR -n ), only active sockets are shown. This option does not show the state of X.25 programmatic access sockets. The option is ignored if the .CR -g , .CR -i , .CR -I , .CR -m , .CR -M , .CR \-p , .CR -r , .C -s or .I interval option is specified. .TP .C -A Show the address of the protocol control block associated with sockets. This option is used for debugging. It does not show the X.25 programmatic access control blocks. This option is ignored if the .CR -g , .CR -i , .CR -I , .CR -m , .CR -M , .CR \-p , .CR \-r , .C -s or .I interval option is specified. .TP .CI -f \0address-family Show statistics or address control block for only the specified .IR address-family . The following address families are recognized: .C inet for .CR AF_INET , and .C unix for .CR AF_UNIX . This option applies to the .CR -a , .C -A and .C -s options. .TP .C -g Show multicast information for network interfaces. Only the address family .C AF_INET is recognized by this option. This option may be combined with the .C -i option to display both kinds of information. The option is ignored if the .CR -m , .C -M or .C -p option is specified. .TP .C -i Show the state of network interfaces. Interfaces that are statically configured into a system, but not located at boot time, are not shown. This option is ignored if the .CR -m , .C -M or .C -p option is specified. .TP .CI -I \0interface Show information about the specified interface only. This option applies to the .C -g and .C -i options. .TP .C -m Show statistics recorded by network memory management routines. If this option is specified, all other options are ignored. .TP .C -M Show the multicast routing tables. When .C -s is used with the .C -M option, .C netstat displays multicast routing statistics instead. This option is ignored if the .C -m or .C -p option is specified. .TP .C -n Show network addresses as numbers. Normally, .C netstat interprets addresses and attempts to display them symbolically. This option applies to the .CR -a , .CR -A , .CR -i , .C -r and .C -v options. .TP .CI -p \0protocol Show statistics for the specified protocol. The following protocols are recognized: .CR tcp , .CR udp , .CR ip , .CR icmp , .CR igmp , .CR arp , and .CR probe . This option is ignored if the .C -m option is specified. .TP .C -r Show the routing tables. When .C -v is used with the .C -r option, .C netstat also displays the network masks in the route entries. When .C -s is used with the .C -r option, .C netstat displays routing statistics instead. This option is ignored if the .CR -g , .CR -m , .CR -M , .CR -i , .CR -I , .C -p or .I interval option is specified. .TP .C -s Show statistics for all protocols. When this option is used with the .C -r option, .C netstat displays routing statistics instead. When this option is used with the .C -M option, .C netstat displays multicast routing statistics instead. This option is ignored if the .CR -g , .CR -i , .CR -I , .CR -m , .C -p or .I interval option is specified. .TP .C -v Show additional routing information. When .C -v is used with the .C -r option, .C netstat also displays the network masks in the route entries. This option only applies to the .C -r option. .RE .PP The arguments .I system and .I core allow substitutes for the defaults, .C /stand/vmunix and .CR /dev/kmem . .PP If no options or only the .C -A or .C -n option is specified, .C netstat displays the status of only active sockets. The display of active and passive sockets status shows the local and remote addresses, send and receive queue sizes (in bytes), protocol, and the internal state of the protocol. Address formats are of the form .IC host . port , or .IC network . port if the host portion of a socket address is zero. When known, the host and network addresses are displayed symbolically by using .C gethostbyname() and .CR getnetbyname() , respectively (see .IR gethostbyname (3N) and .IR getnetbyname (3N)). If a symbolic name for an address is unknown, or if the .C -n option is specified, the address is displayed numerically according to the address family. For more information regarding the Internet ``dot format'', refer to .IR inet (3N). Unspecified or ``wildcard'' addresses and ports appear as an asterisk .RC ( * ). .PP The interface display provides a table of cumulative statistics regarding packets transferred, errors, and collisions. The network addresses of the interface and the maximum transmission unit (\|MTU\|) are also displayed. When the .I interval argument is specified, .C netstat displays a running count of statistics related to network interfaces. This display consists of a column for the primary interface (the first interface found during auto-configuration) and a column summarizing information for all interfaces. To replace the primary interface with another interface, use the .C -I option. The first line of each screen of information contains a summary since the system was last rebooted. Subsequent lines of output show values accumulated over the preceding interval. .PP The routing table display indicates the available routes and their status. Each route consists of a destination host or network, a netmask and a gateway to use in forwarding packets. The .C Flags field shows whether the route is up .RC ( U ), whether the route is to a gateway .RC ( G ), whether the route is a host or network route (with or without .CR H ), whether the route was created dynamically .RC ( D ) by a redirect or by Path MTU Discovery, and whether a gateway route has been modified .RC ( M ), or it has been marked doubtful .RC ( ? ) due to the lack of a timely ARP response. .PP The .C Netmask field shows the mask to be applied to the destination IP address of an IP packet to be forwarded. The result will be compared with the destination address in the route entry. If they are the same, then the route is one of the candidates for routing this IP packet. If there are several candidate routes, then the route with the longest .C Netmask field (contiguous 1's starting from the leftmost bit position) will be chosen. (see .CR routing (7).) .PP The .C Gateway field shows the address of the immediate gateway for reaching the destination. It can be the address of the outgoing interface if the destination is on a directly connected network. .PP The .C Refs field shows the current number of active uses of the route. Connection-oriented protocols normally hold on to a single route for the duration of a connection, while connectionless protocols normally obtain a route just while sending a particular message. The .C Use field shows a count of the number of packets sent using the route. The .C Interface field identifies which network interface is used for the route. .PP The .C Pmtu and .C PmtuTime fields apply only to host routes. The .C Pmtu field for network and default routes is the same as the MTU of the network interface used for the route. If the route is created with a static PMTU value (see .IR route (1M)), the corresponding .C PmtuTime field contains the word .CR perm , and the PMTU value permanently overrides the interface MTU. If the route is created dynamically .RC ( D in the .C Flags field), the value in the corresponding .C PmtuTime field is the number of minutes remaining before the PMTU expires. When the PMTU expires, the system rediscovers the current PMTU for the route, in case it has changed. The .C PmtuTime field is left blank when the PMTU is identical to the MTU of the interface. An asterisk .RC (*) in the .C Pmtu field indicates that user has disabled the PMTU Discovery for the route. .SH DEPENDENCIES .SS X.25: .C -A and .C -a options do not list X.25 programmatic access information. .SH AUTHOR .C netstat was developed by the University of California, Berkeley. .SH SEE ALSO hosts(4), networks(4), gethostbyname(3N), getnetbyname(3N), protocols(4), route(1M), services(4). .\" .\" index@\f4netstat\f1 \- show network status@@@\f3netstat(1)\f1 .\" index@show network status@@@\f3netstat(1)\f1 .\" index@display network status@@@\f3netstat(1)\f1 .\" index@return network status@@@\f3netstat(1)\f1 .\" index@get network status@@@\f3netstat(1)\f1 .\" index@network status show@@@\f3netstat(1)\f1 .\" index@status show network@@@\f3netstat(1)\f1 .\" .\" toc@\f3netstat(1)\f1:\0\0\f4netstat\f1@@@show network status .\" .\" fileset_database@netstat.1 USER-CMDS-MAN .\" $Header: $ .TA n .TH newalias 1 .SH NAME newalias \- install new elm aliases for user or system .SH SYNOPSIS .HP .CR newalias .RC [ -g ] .SS Remarks .CR newalias replaces the former functionality of the .CR elmalias command. .SH DESCRIPTION The .CR newalias command creates new alias database files from an alias text file for use by .CR elm and other programs. For user aliases, this functionality can also be performed from the Alias Menu of the .CR elm program (see .IR elm (1)). .SS Options .CR newalias recognizes the following option: .RS .TP .CR \-g Global. The program updates the system alias files instead of a user's alias files. .RE .SS Operation Without the .CR \-g option, .CR newalias updates a user's alias files, based on an input file named .IP .C "$HOME/.elm/aliases.text" .PP Upon finding the file, it creates the output files named .RS .PP .nf .C "$HOME/.elm/aliases" .C "$HOME/.elm/aliases.dir" .C "$HOME/.elm/aliases.pag" .fi .RE .PP With the .CR \-g option, .CR newalias updates the system alias files, based on an input file named .IP .C "/var/mail/.elm/aliases.text" .PP Upon finding the file, it creates the output files named .RS .PP .nf .C "/var/mail/.elm/aliases" .C "/var/mail/.elm/aliases.dir" .C "/var/mail/.elm/aliases.pag" .fi .RE .PP In either case, you need read access to the .CR aliases.text file and write access to the other files and the .CR \&.elm directory. .SS Text File Entries Each entry in either .CR aliases.text file is expected to be in the following format: .IP .RC \f2alias-list\fP "\0=\0\c" .RC [\f2lastname\0\fP[ ";\0\c" .RC \f2firstname\fP]\|]\0[ ",\0\c" .RC \f2comment\fP] "\0=\0" \f2address-list\fP .PP A personal or individual alias has only one address in .IR address-list , as in: .RS .nf .PP .C "dave, taylor = Dave Taylor = taylor@company.com" .C " " .C "j_smith = Smith; John, 408-555-1212 =johns@pocahontas.gov" .fi .RE .PP A group alias has two or more addresses in .IR address-list , as in: .RS .nf .PP .C "gurus = Unix Gurus = alan, john, dave, mike," .C " richard, larry, t_richardson" .C " " .C "unix = Unix people = gurus, taylor, jonboy" .fi .RE .PP Entries can be continued over several lines; the continuation lines must start with a blank (a space or tab). .PP A comment is any line starting with a number sign .RC ( # ). It is ignored. .PP Blank lines and comments can be interspersed within entries. .PP The delimiters have the following precedence: .RS 2 .TP 3 \(bu The first and second equal signs .RC ( = ) mark the end of the .IR alias-list and the beginning of the .IR address-list , respectively. Both equal signs are required. .TP \(bu The first comma .RC ( , ) after the first equal sign and before the second equal sign marks the beginning of the .IR comment field. .TP \(bu The first semicolon .RC ( ; ) after the first equal sign and before the next comma or second equal sign marks the beginning of the .IR firstname field. .RE .PP The field names are defined as follows: .RS .TP 15 .I address-list A blank- or comma-separated list of one or more mail addresses, personal alias names, and/or group alias names. .IP In practice, each item is tested first as an alias name. If it is not an alias name, it is assumed to be a mail address. A mail address can be in Internet form .RC ( user@host.domain ), in UUCP form .RC ( host.domain!user ), or in .CR sendmail alias form (see .IR sendmail (1M)). It can also be the name of a local mail user, which is appended with the local host name in Internet form. .TP .I alias-list A blank- or comma-separated list of alias names. Each name identifies the same alias entry. An alias name can be made up of letters .RC ( A \(mi Z , .CR a \(mi z ), digits .RC ( 0 \(mi 9 ), underscores .RC ( _ ), dashes .RC ( - ), and periods .RC ( . ). Alias names are not case-sensitive, so .CR dave and .CR Dave are equivalent. .TP .I comment A string containing any information you wish about the entry, such as location and phone numbers. It is displayed in the Alias Menu of the .CR elm program, but .CR elm does not transmit it in a mail message. This field can contain any characters except an unquoted equal sign .RC ( = ). See the Quoting Characters subsection. .TP .I firstname The first name of the person (or group). It is combined with .IR lastname to form the .IR fullname . This field can contain any characters except an unquoted equal sign .RC ( = ) or an unquoted comma .RC ( , ). See the Quoting Characters subsection. .IP The only first name in the examples above is .CR John in .CR "Smith; John" . .TP .I lastname The last name of the person (or group). It is combined with .IR firstname to form the .IR fullname . This field can contain any characters except an unquoted equal sign .RC ( = ), an unquoted semicolon .RC ( ; ), or an unquoted comma .RC ( , ). See the Quoting Characters subsection. .IP The last names in the examples above are .CR Dave "\ " Taylor , .CR Smith , .CR Unix "\ " Gurus , and .CR Unix "\ " people . .TP .I fullname The combination of .IR "firstname lastname" . It is usually sent in a mail header in parentheses after the address. It is also displayed in the Alias Menu of the .CR elm program and by the .CR elmalias command (see .IR elm (1) and .IR elmalias (1)). .RE .SS Quoting Characters You can include normally excluded characters in .IR firstname , .IR lastname , .IR comment , and mail addresses in .IR address-list by escaping each character with a backslash .RC ( \e ) or by enclosing the string in quotation marks (\f3\f4\s+1"\s0\f1). To include a quotation mark or a backslash, escape it with a backslash, whether inside or outside quotation marks. .SH FILES .if t .TP 40 .if n .TP 30 .PD 0 .CR $HOME/.elm/aliases User alias database data table .TP .CR $HOME/.elm/aliases.dir User alias database directory table .TP .CR $HOME/.elm/aliases.pag User alias database hash table .TP .CR $HOME/.elm/aliases.text User alias source text .TP .CR /var/mail/.elm/aliases System alias database data table .TP .CR /var/mail/.elm/aliases.dir System alias database directory table .TP .CR /var/mail/.elm/aliases.pag System alias database hash table .TP .CR /var/mail/.elm/aliases.text System alias source text .PD .SH AUTHOR .CR newalias was developed by HP. .SH SEE ALSO elm(1), elmalias(1), mail(1), mailx(1). .\" .\" toc@\f3newalias(1)\f1:\0\0f4newalias\f1@@@install new \f4elm\f1 aliases for user or system .\" index@\f4newalias\f1 \- install new \f4elm\f1 aliases for user or system@@@\f3newalias(1)\f1 .\" index@\f1install new \f4elm\f1 aliases for user or system@@@\f3newalias(1)\f1 .\" index@\f1alias: install new \f4elm\f1 aliases for user or system@@@\f3newalias(1)\f1 .\" index@\f1user alias: install new \f4elm\f1 aliases@@@\f3newalias(1)\f1 .\" index@\f1system alias: install new \f4elm\f1 aliases@@@\f3newalias(1)\f1 .\" index@\f1full name: in \f4elm\f1 aliases@@@\f3newalias(1)\f1 .\" index@\f1user name: in \f4elm\f1 aliases@@@\f3newalias(1)\f1 .\" $Header: newform.1,v 72.3 93/01/14 11:36:44 ssa Exp $ .TA n .TH newform 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME newform \- change or reformat a text file .SH SYNOPSIS .C newform .RC [ -i .IR tabspec\|\fP] .RC [ -o .IR tabspec\|\fP] .RC [ -l .IR n\| ] .RC [ -b .IR n\| ] .RC [ -e .IR n\| ] .RC [ -c .IR char\| ] .RC [ -p .IR n\| ] .RC [ -a .IR n\| ] .RC [ -f ] .RC [ -s ] .RI [ \|files\| ] .SH DESCRIPTION .C newform reads lines from the named .IR files , or the standard input if no input file is named, and reproduces the lines on the standard output. Lines are reformatted in accordance with command line options in effect. .PP Except for .CR -s , command line options can appear in any order, can be repeated, and can be intermingled with the optional .IR files . Command line options are processed in the order specified. This means that option sequences such as .C -e 15 -l 60 yield results different from .CR "-l 60 -e 15" . Options are applied to all .I files on the command line. .SS Options .C newform recognizes the following options: .RS .TP 15 .CI -i tabspec Input tab specification: expands tabs to spaces, according to the tab specifications given. .I Tabspec recognizes all tab specification forms described in .IR tabs (1). In addition, .I tabspec can be .CR -- , in which .C newform assumes that the tab specification is to be found in the first line read from the standard input (see .IR fspec (4)). If no .I tabspec is given, .I tabspec defaults to .CR -8 . A .I tabspec of .C -0 expects no tabs; if any are found, they are treated as .CR -1 . .TP .CI -o tabspec Output tab specification: replaces spaces with tabs, according to the tab specifications given. The tab specifications are the same as for .CI -i tabspec\f1. If no .I tabspec is given, .I tabspec defaults to .CR -8 . A .I tabspec of .C -0 means that no spaces will be converted to tabs on output. .TP .CI -l n Set the effective line length to .I n characters. If .I n is not entered, .C -l defaults to 72. The default line length without the .C -l option is 80 characters. Note that tabs and backspaces are treated as single characters (use .C -i to expand tabs to spaces). .TP .CI -b n Truncate .I n characters from the beginning of the line when the line length is greater than the effective line length (see .CI -l n\f1).\fP Default is to truncate the number of characters necessary to obtain the effective line length. The default value is used when .C -b with no .I n is used. This option can be used to delete the sequence numbers from a .SM COBOL program as follows: .RS .IP .C newform -l1 -b7 .I file-name .RE .IP The .C -l1 must be used to set the effective line length shorter than any existing line in the file so that the .C -b option is activated. .TP .CI -e n Same as .CI -b n except that characters are truncated from the end of the line. .TP .CI -c k Change the prefix/append character to .IR k . Default character for .I k is a space. .TP .CI -p n Prefix .I n characters (see .CI -c k\f1) to the beginning of a line when the line length is less than the effective line length. Default is to prefix the number of characters necessary to obtain the effective line length. .TP .CI -a n Same as .CI -p n except characters are appended to the end of a line. .TP .C -f Write the tab specification format line on the standard output before any other lines are output. The tab specification format line which is printed will correspond to the format specified in the .I last .C -o option. If no .C -o option is specified, the line which is printed contains the default specification of .CR -8 . .TP .C -s Shears off leading characters on each line up to the first tab and places up to 8 of the sheared characters at the end of the line. If more than 8 characters (not counting the first tab) are sheared, the eighth character is replaced by a .C * and any characters to the right of it are discarded. The first tab is always discarded. .IP An error message and program exit occur if this option is used on a file without a tab on each line. The characters sheared off are saved internally until all other options specified are applied to that line. The characters are then added at the end of the processed line. .IP For example, to convert a file with leading digits, one or more tabs, and text on each line, to a file beginning with the text, all tabs after the first expanded to spaces, padded with spaces out to column 72 (or truncated to column 72), and the leading digits placed starting at column 73, the command would be: .RS .IP .C "newform -s -i -l -a -e" .I file-name .RE .RE .SH RETURN VALUE .C newform returns one of the following values upon completion: .RS .TP 5 .B 0 No errors encountered. .TP .B 1 An error occurred. .SH DIAGNOSTICS All diagnostics are fatal. .RS .TP .CR usage: \0\|... .C newform was called with a bad option. .TP .C "not -s format" There was no tab on one line. .TP .C "can't open file" Self-explanatory. .TP .C "internal line too long" A line exceeds 512 characters after being expanded in the internal work buffer. .TP .C "tabspec in error" A tab specification is incorrectly formatted, or specified tab stops are not ascending. .TP .C "tabspec indirection illegal" A .I tabspec read from a file (or standard input) must not contain a .I tabspec referencing another file (or standard input). .RE .SH WARNINGS .C newform normally only keeps track of physical characters; however, for the .C -i and .C -o options, .C newform keeps track of backspaces in order to line up tabs in the appropriate logical columns. .PP .C newform does not prompt the user if a .I tabspec is to be read from the standard input (by use of .C -i-- or .CR -o-- ). .PP If the .C -f option is used, and the last .C -o option specified was .CR -o-- , and was preceded by either a .C -o-- or a .CR -i-- , the tab specification format line will be incorrect. .SH SEE ALSO fspec(4), csplit(1), tabs(1). .\" index@\f4newform\f1 \- change or reformat a text file@@@\f3newform(1)\f1 .\" index@change or reformat a text file@@@\f3newform(1)\f1 .\" index@files: change or reformat a text file@@@\f3newform(1)\f1 .\" index@reformat or change a text file@@@\f3newform(1)\f1 .\" index@text file, change or reformat a@@@\f3newform(1)\f1 .\" index swap up to eight characters (to first tab in line) to end of line \f3newform(1)\f1 .\" index@truncate text line to specified maximum length@@@\f3newform(1)\f1 .\" index truncate text from beginning of line to specified column \f3newform(1)\f1 .\" index@expand text line to specified length@@@\f3newform(1)\f1 .\" index@prefix characters to obtain text line of specified length@@@\f3newform(1)\f1 .\" index@append characters to obtain text line of specified length@@@\f3newform(1)\f1 .\" index@shear characters from beginning of line and move to end of line@@@\f3newform(1)\f1 .\" .\" toc@\f3newform(1)\f1:\0\0\f4newform\f1@@@change or reformat a text file .\" .\" fileset_database@newform.1 USER-CMDS-MAN .\" $Header: newgrp.1,v 76.1 95/08/04 16:08:54 ssa Exp $ .TA n .TH newgrp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME newgrp \- switch to a new group .SH SYNOPSIS .CR newgrp .RC \|[ - ]\| .RI \|[ group ]\| .SH DESCRIPTION The .CR newgrp command changes your group .SM ID without changing your user .SM ID and replaces your current shell with a new one. .PP If you specify .IR group , the change is successful if .IR group exists and either your user .SM ID is a member of the new .IR group , or .IR group has a password and you can supply it from the terminal. .PP If you omit .IR group , .CR newgroup changes to the group specified in your entry in the password file, .CR /etc/passwd . .PP Whether the group is changed successfully or not, or the new group is the same as the old one or not, .CR newgrp proceeds to replace your current shell with the one specified in the shell field of your password file entry. If that field is empty, .CR newgrp uses the POSIX shell, .CR /usr/bin/sh (see .IR sh-posix (1)). .PP If you specify .CR - (hyphen) as the first argument, the new shell starts up as if you had just logged in. If you omit .CR - , the new shell starts up as if you had invoked it as a subshell. .PP You remain logged in and the current directory is unchanged, but calculations of access permissions to files are performed with respect to the new real and effective group .SM ID\s0s. .PP Exported variables retain their values and are passed to the new shell. All unexported variables are deleted, but the new shell may reset them to default values. .PP Since the current process is replaced when the new shell is started, exiting from the new shell has the same effect as exiting from the shell in which .CR newgrp was executed. .SH EXTERNAL INFLUENCES .SS International Code Set Support Characters from the 7-bit .SM USASCII code set are supported in group names (see .IR ascii (5)). .SH DIAGNOSTICS The .CR newgrp command issues the following error messages: .TP 30 .CR Sorry Your user .SM ID does not qualify as a group member. .TP .C "Unknown group" The group name does not exist in .CR /etc/group . .TP .C "Permission denied" If a password is required, it must come from a terminal. .TP .C "You have no shell" Standard input is not a terminal file, causing the new shell to fail. .SH EXAMPLES To change from your current group to group .CR users without executing the login routines: .IP .C "newgrp users" .PP To change from your current group to group .CR users and execute the login routines: .IP .C "newgrp - users" .SH WARNINGS There is no convenient way to enter a password into .CR /etc/group . .PP The use of group passwords is not recommended because, by their very nature, they encourage poor security practices. Group passwords may be eliminated in future .SM HP-UX releases. .SH FILES .TP 25 .PD 0 .CR /etc/group System group file .TP .CR /etc/passwd System password file .PD .SH SEE ALSO csh(1), ksh(1), login(1), sh-bourne(1), sh-posix(1), group(4), passwd(4), environ(5). .SH STANDARDS CONFORMANCE .CR newgrp ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4newgrp\f1 \- switch to a new group@@@\f3newgrp(1)\f1 .\" index@switch to a new group@@@\f3newgrp(1)\f1 .\" index@group, log in to a new@@@\f3newgrp(1)\f1 .\" index@change current login to a new group@@@\f3newgrp(1)\f1 .\" .\" toc@\f3newgrp(1)\f1:\0\0\f4newgrp\f1@@@switch to a new group .\" $Header: newmail.1,v 80.2 96/10/24 11:47:17 ssa Exp $ .TA n .TH newmail 1 .SH NAME newmail \- notify users of new mail in mailboxes .SH SYNOPSIS .CR newmail .RC [ \-i .IR interval ] .RC [ \-w ] .RI [ file-spec ]... .SH DESCRIPTION The .CR newmail utility monitors your incoming mailbox or the specified mail folders. .PP The basic operation is that the program checks the folders each .I interval seconds (default 60) and lists any new mail that has arrived in any of the mailboxes, indicating the sender's name, and the subject of the message. .PP Without any options, .CR newmail runs in the background at a default interval of 60 seconds to monitor the user's incoming mailbox. So that they are suitable for display on an already active screen, messages are prefixed with a pair of pointer characters as follows: .RS .nf .PP .CI ">> Mail from \&" sender-name \0-\0\& subject-of-message .CI ">> Priority \&" sender-name \0-\0\& subject-of-message .fi .RE .PP If there is no subject, the message .CR "(No Subject Specified)" is displayed. If there is more than one folder, output lines are prefixed by the .I folder-name or the prefix string specified by .IR file-spec . .PP .CR newmail runs until you log out or explicitly kill it. It can internally reset itself if the mailbox shrinks in size and then grows again. .SS Options .CR newmail recognizes the following options: .RS .TP 15 .CI \-i \0interval Set the time interval between mailbox checks to the value specified, in seconds. The default is 60. .IP .I interval must be less than .if n 2^32 .if t 2\u\s-232\s+2\d \" OK for SGML seconds. If it is set to less than 10 seconds, .CR newmail warns that such short intervals are not recommended. .TP .CR \-w Run the program within the current window in the foreground with a more succinct output format. .IP The output formats become: .RS .nf .PP .CI "Mail from \&" sender-name \0-\0\& subject-of-message .CI "Priority \&" sender-name \0-\0\& subject-of-message .fi .RE .RE .SS Operands .CR newmail recognizes the following operand: .RS .TP 15 .I file-spec Specifies the name of a folder and an optional prefix string, in the form: .RS .nf .PP .RC \f2foldername\fP[ = \f2prefix-string\fP] .fi .RE .IP Metacharacters such as .CR + , .CR = , and .CR % indicate the folder directory. The default is the value of the environment variable .CR MAILDIR or .CR $HOME/Mail . .RE .SH EXAMPLES Check incoming mailbox every 60 seconds: .IP .CR newmail .PP Check incoming mailboxes of .CR joe and .CR root every 15 seconds for new messages. .IP .C "newmail -i 15 joe root" .PP Monitor the incoming mailbox of user .CR mary and the folder in your mail directory called .CR postmaster . Prefix all new messages in the incoming mailbox of .CR mary with the string .CR Mary , and the new messages in the folder .CR postmaster with .CR POBOX . Also, monitor folder .CR /tmp/mbox : .IP .C "newmail ""mary=Mary"" +postmaster=POBOX /tmp/mbox" .SH AUTHOR .CR newmail was developed by HP. .\" .\" index@\f4newmail\f1 \- notify users of new mail in mailboxes@@@\f3newmail(1)\f1 .\" index@\f1notify users of new mail in mailboxes@@@\f3newmail(1)\f1 .\" index@\f1mailboxes, notify users of new mail in@@@\f3newmail(1)\f1 .\" index@\f1mail, notify users of new@@@\f3newmail(1)\f1 .\" index@\f1users, notify of new mail in mailboxes@@@\f3newmail(1)\f1 .\" .\" toc@\f3newmail(1)\f1:\0\0\f4newmail\f1@@@notify users of new mail in mailboxes .\" .\" $Header: news.1,v 72.5 94/11/14 15:20:09 ssa Exp $ .TA n .TH news 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME news \- print news items .SH SYNOPSIS .C news .RC [ -a ] .RC [ -n ] .RC [ -s ] .RI [ \|items\| ] .SH DESCRIPTION .C news is used to keep the user informed of current events. By convention, these events are described by files in the directory .CR /var/news . .PP When invoked without arguments, .C news prints the contents of all current files in .CR /var/news , most recent first, with each preceded by an appropriate header. .C news stores the ``currency'' time as the modification date of a file named .C .news_time in the user's home directory (the identity of this directory is determined by the environment variable .CR $HOME ); only files more recent than this currency time are considered ``current.'' .SS Options .C news recognizes the following options: .RS .TP 10 .C -a Print all items, regardless of currency. The stored time is not changed. .TP .C -n Report the names of the current items without printing their contents, and without changing the stored time. .TP .C -s Report how many current items exist without printing their names or contents, and without changing the stored time. It is useful to include such an invocation of .I news in one's .C .profile file, or in the system's .CR /etc/profile . .RE .PP All other arguments are assumed to be specific news items that are to be printed. .PP If an interrupt is typed during the printing of a news item, printing stops and the next item is started. Another interrupt within one second of the first causes the program to terminate. .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH FILES .C /var/news/* .br .C $HOME/.news_time .br .C /etc/profile .SH SEE ALSO mail(1), profile(4), environ(5). .SH STANDARDS CONFORMANCE .CR news ": SVID2, SVID3, XPG2" .\" .\" toc@\f3news(1)\f1:\0\0\f4news\f1@@@print news items .\" .\" index@\f4news\f1 \- print news items@@@\f3news(1)\f1 .\" index@print news items@@@\f3news(1)\f1 .\" .\" fileset_database@news.1 USER-CMDS-MAN .\" $Header: nice.1,v 76.1 95/07/11 13:45:17 ssa Exp $ .TA n .TH nice 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nice \- run a command at nondefault priority .SH SYNOPSIS .CR nice .RC [ - \f2priority_change\f1] .IR command .RI [ command_args ] .br .CR nice .RC [ -n \0\f2priority_change\f1] .IR command .RI [ command_args ] .SH DESCRIPTION The .CR nice command executes .IR command at a nondefault CPU scheduling priority. (The name is derived from being "nice" to other system users by running large programs at lower priority.) .SS Arguments The command-line arguments are as follows: .RS .TP 16 .C -n \0\f2priority_change\f1 .TP 16 .IR priority_change The difference between the system nice value (relative priority) of the current (or parent) process and the actual system nice value at which .IR command is to run. .IP An unsigned value increases the system nice value for .IR command , causing it to run at lower priority. .IP A negative value requires superuser privileges, and assigns a lower system nice value (higher priority) to .IR command . If the current process is not privileged, the value is silently treated as if it were 0. .IP If the value of .IR priority_change would result in a system nice value outside the range 0 through 39, the corresponding limit value of 0 or 39 is used instead. .IP Note that a positive .IR priority_change (lower priority) has a single .CR - option character before the numeric value; a negative (higher priority) .IR priority_change has two: the option character followed by the minus sign .RC ( -- ). If .CI - priority_change is not specified, it defaults to .CR 10 . .TP .IR command A program, HP-UX command, user shell script, etc. to be executed at the nondefault priority. .IR command can be run as a foreground or background process. .IP If .IR command is run as a background process, any nice .IR priority_change made by the shell .RC ( ksh executes all background processes via .CR "nice -4" ) is in addition to that specified in the .CR nice command line. .TP .IR command_args Any arguments recognized by .IR command . .SS Process Priorities All processes have an associated system nice value which is used to compute the instantaneous-priority of the process when it is scheduled to run. Normally, all processes inherit the system nice value of their parent process when they are spawned. The shell .RC ( sh , .CR csh , .CR ksh , etc.) can create a child process with a different priority from the current shell process by spawning the child process via the .CR nice command. If the .IR priority_change value is unsigned (positive), the child process is nicer (lower in priority) relative to the parent. If the .IR priority_change value is negative, the child process runs at a higher priority with a greater share of available system resources. To spawn a higher priority child process, the parent process must be owned by a user who has the appropriate privileges. .PP At boot-up, the system starts the .CR init process at a system nice value of 20 (system default). On most systems, all processes (down to the login shells) inherit this priority. Starting from their individual login shell processes, users can alter the system nice value of descendent processes to as much as 39, or, with appropriate privileges, as little as 0. A system nice value of 0 establishes an extremely high priority, whereas a value of 39 indicates a very low priority. .PP Ordinary users can only increase the system nice value of any child process relative to the current process; i.e., .IR priority_change must be a positive (unsigned) value, resulting in a lower priority. To start a child process at a lower system nice value (higher priority) than the current process, the user must have the appropriate privileges, regardless of the relative nice-priority value desired. .PP For example, using the command .IP .C nice ksh .PP from a login shell whose current nice value is 20 spawns a subshell with a system nice value of 30. Attempting to use .IP .C nice --2 ksh .PP from the new shell to spawn another subshell whose system nice value would be 28, is rejected (unless the user has appropriate privileges), even though the resulting system nice value would be less than the priority of the original login shell process. .PP The system nice value for current processes is listed under the .CR NI column produced by the .CR ps\ -l command (see .CR ps (1)). .SS Background Processes Foreground processes are run at same system nice value as the parent shell. Background processes spawned by .CR ksh run at the equivalent of a .CR nice\ -4 by default. If a background process is started via .CR nice from .CR ksh , any .IR priority_change specified in the .CR nice command is added to default .CR "nice\ -4" . Thus the command .IP .CI "nice 12 " command \0& .PP runs at a system nice value of 36 if executed from .CR ksh . .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C nice behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .CR nice returns the value returned by .IR command . .SH EXAMPLES The following examples assume the current process is running with a system nice value of 20 and .CR nice is executed from the Korn shell (see .CR ksh (1)). .PP Run a program named .CR prog in the current directory at the default .IR priority_change of 10 (system nice value of 30): .IP .CI "nice ./prog " prog_args .PP Run the same program in the background using a system nice value of 36 .RI ( priority_change =12 plus 4 for the Korn shell): .IP .CI "nice -12 ./prog \&" prog_args " &" .PP As a user with appropriate privileges, run .CR prog as a foreground process with a system nice value of 6: .IP .CI "nice --14 ./prog " prog_args .SH WARNINGS The C shell, .CR csh , has a built-in .CR nice command with different syntax. See .CR csh (1) for details. .SH SEE ALSO csh(1), ksh(1), nohup(1), renice(1), nice(2). .SH STANDARDS CONFORMANCE .CR nice ": SVID2, SVID3, XPG4" .\" .\" index@\f4nice\f1 \- run a command at nondefault priority@@@\f3nice(1)\f1 .\" index@\f1run a command at nondefault priority@@@\f3nice(1)\f1 .\" index@\f1command, run at nondefault priority@@@\f3nice(1)\f1 .\" index@\f1nondefault priority, run a command at@@@\f3nice(1)\f1 .\" index@\f1priority, run a command at nondefault@@@\f3nice(1)\f1 .\" .\" toc@\f3nice(1)\f1:\0\0\f4nice\f1@@@run a command at nondefault priority .\" $Header: nl.1,v 76.1 95/08/23 17:58:24 ssa Exp $ .TA n .TH nl 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl \- line numbering filter .SH SYNOPSIS .C nl .RC [ -b\c .IR type\| ] .RC [ -h\c .IR type\| ] .RC [ -f\c .IR type\| ] .RC [ -p ] .RC [ -v\c .IR start#\| ] .RC [ -i\c .IR incr\| ] .RC [ -s\c .IR sep\| ] .RC [ -w\c .IR width\| ] .RC [ -n\c .IR format\| ] .RC [ -l\c .IR num\| ] .RC [ -d\c .IR delim\| ] .RI [ \|file\| ] .SH DESCRIPTION .C nl reads lines from the named .I file or the standard input if no .I file is named and reproduces the lines on the standard output. Lines are numbered on the left in accordance with the command options in effect. .PP .C nl views the text it reads in terms of logical pages. Line numbering is reset at the start of each logical page. A logical page consists of a header, a body, and a footer section. Empty sections are valid. Different line numbering options are independently available for header, body, and footer (e.g., no numbering of header and footer lines while numbering blank lines only in the body). .PP The start of logical page sections are signaled by input lines containing nothing but the following delimiter character(s): .IP .TS tab (@); lB | lB aB | a. Line contents@Start of _ \e:\e:\e:@header \e:\e:@body \e:@footer .TE .PP Unless told otherwise, .C nl assumes the text being read is in a single logical page body. .PP Command options can appear in any order and can be intermingled with an optional file name. Only one file can be named. .C nl recognizes the following options: .RS .TP 12 .CI -b type Specifies which logical page body lines are to be numbered. Recognized .I types and their meanings are: .RS .RS .TP 12 .C a number all lines; .PD 0 .TP .C t number lines with printable text only; .TP .C n no line numbering; .TP .CI p string number only lines that contain the regular expression specified in .IR string . Basic Regular Expression syntax is supported (see .IR regexp (5)). .RE .RE .PD .IP The default .I type for logical page body is .C t (text lines numbered). .TP .CI -h type Same as .CI -b type except for header. Default .I type for logical page header is .C n (no lines numbered). .TP .CI -f type Same as .CI -b type except for footer. Default for logical page footer is .C n (no lines numbered). .TP .C -p Do not restart numbering at logical page delimiters. .TP .CI -v start# .I start# is the initial value used to number logical page lines. Default is .CR 1 . .TP .CI -i incr .I incr is the increment value used to number logical page lines. Default is .CR 1 . .TP .CI -s sep .I sep is the character or characters used in separating the line number and the corresponding text line. Default .I sep is a tab. .TP .CI -w width .I width is the number of character columns to be used for the line number. Default .I width is .CR 6 . .TP .CI -n format .I format is the line numbering format. Recognized values are: .RS .RS .TP 6 .C ln left justified, leading zeroes suppressed; .PD 0 .TP .C rn right justified, leading zeroes suppressed; .TP .C rz right justified, leading zeroes kept. .RE .RE .PD .IP Default .I format is .C rn (right justified). .TP .CI -l num .I num is the number of consecutive blank lines to be treated and numbered as a single line. For example, .C -l3 results in every third adjacent blank line being numbered if the appropriate .CR -ha , .CR -ba , and/or .C -fa option is set. Default is .CR 1 . .TP .CI -d xx The delimiter characters specifying the start of a logical page section can be changed from the default characters .RC ( \e: ) to two user-specified characters. If only one character is entered, the second character remains the default character .RC ( : ). No space should appear between the .C -d and the delimiter characters, however, this restriction is not there for .C XPG4 compliant .CR nl . To define a backslash as the delimiter, use two backslashes. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the collating sequence used in evaluating regular expressions. .PP .C LC_CTYPE determines the characters matched by character class expressions in regular expressions. .PP If .C LC_COLLATE or .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C nl behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte character code sets are supported. .SH EXAMPLES Number .C file1 starting at line number 10, using an increment of ten. The logical page delimiters are .C ! and .CR + : .IP .C nl -v10 -i10 -d!+ file1 .SH SEE ALSO pr(1), environ(5), lang(5), regexp(5). .SH STANDARDS CONFORMANCE .CR nl ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4nl\f1 \- line numbering filter@@@\f3nl(1)\f1 .\" index@\f1line numbering filter@@@\f3nl(1)\f1 .\" index@\f1numbering filter, line@@@\f3nl(1)\f1 .\" index@\f1filter, line numbering@@@\f3nl(1)\f1 .\" index@\f1files: add line number in front of each line in a file@@@\f3nl(1)\f1 .\" index@\f1add line number in front of each line in a file@@@\f3nl(1)\f1 .\" index@\f1line numbers, add in front of each line in a file@@@\f3nl(1)\f1 .\" .\" toc@\f3nl(1)\f1:\0\0\f4nl\f1@@@line numbering filter .\" .\" $Header: nljust.1,v 72.4 94/09/08 14:55:23 ssa Exp $ .TA n .TH nljust 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nljust \- justify lines, left or right, for printing .SH SYNOPSIS .C nljust .RC [ -acilnt ] .RC [ -d .IR digits\| ] .RC [ -e .IR seq\| ] .RC [ -j .IR just\| ] .RC [ -m .IR mode\| ] .RC [ -o .IR order\| ] .RC [ -r .IR margin\| ] .RC [ -w .IR width\| ] .RC [ -x .IR ck\| ] .RI [ \|file \0...\|] .SH DESCRIPTION .C nljust formats for printing data written in languages with a right-to-left orientation. It is designed to be used with the .C pr and the .C lp commands (see .IR pr (1) and .IR lp (1)). .PP .C nljust reads the concatenation of input files (or standard input if none are given) and produces on standard output a right-to-left formatted version of its input. If .C - appears as an input file name, .C nljust reads standard input at that point. Use .C -\|- to delimit the end of options. .PP .C nljust formats input files for all languages that are read from right to left. For languages that have a left-to-right orientation, the command merely copies input files to standard output. .SS Options .C nljust recognizes the following options: .RS .TP 12 .C -a Justify data for all languages, including those having a left-to-right text orientation. By default only right-to-left language data is justified. For all other languages, input files are directly copied to standard output. .TP .C -c Select enhanced printer shapes for some Arabic characters. With this option, two-character combinations of laam and alif are replaced by a single character. .TP .C -i Triggers ISO 8859-6 interpretation of the data. .TP .CI -d \0digits Processes digits for output as hindi, western, or both. .I digits can be .CR h , .CR w , or both. .TP .CI -e \0seq Use .I seq as the escape sequence to select the primary character set. This escape sequence is used by languages that have too many characters to be accommodated by .SM ASCII in a single 256-character set. In these cases, the .I seq escape sequence can be used to select the non-\c .SM ASCII character set. The .I escape character itself (0x1b) is not given on the command line. Hewlett-Packard escape sequences are used by default. .TP .CI -j \0just If .I just is .CR l , left justify print lines. If .I just is .CR r , right-justify print lines starting from the (designated or default) print width column. The default is right justification. .TP .C -l Replace leading spaces with alternative spaces. Some right-to-left character sets have a non-\c .SM ASCII or alternative space. This option can be useful when filtering .C pr -n output (see .IR pr (1)). With right justification, the .C -l option causes line numbers to be placed immediately to the right of the tab character. Without the .C -l option, right justification causes line numbers to be placed at the print-width column. By default, leading spaces are not replaced by alternative spaces. .TP .CI -m \0mode Indicate .I mode of any file to be formatted. Mode refers to the text orientation of the file when it was created (see .IR hpnls (5) for more details). If .I mode is .CR l , assume Latin mode. If .I mode is .CR n , assume non-Latin mode. By default, mode information is obtained from the .C LANGOPTS environment variable. .TP .C -n Do not terminate lines containing printable characters with a new-line. By default, print lines are terminated by new-lines. .TP .CI -o \0order Indicate data .I order of any file to be formatted. The text orientation of a file can affect the way its data is arranged (see .IR hpnls (5) for more details). If .I order is .CR k , assume keyboard order. If .I order is .CR s , assume screen order. By default, order information is obtained from the .C LANGOPTS environment variable. .TP .C -t Truncate print lines that do not fit the designated or default line length. Print lines are folded (that is, wrapped to next line) by default. .TP .CI -x \0ck Expand input tabs to column positions .IR k +1, .IR 2* k +1, .IR 3* k +1, etc. Tab characters in the input are expanded to the appropriate number of spaces. If .I k is 0 or is omitted, default tab settings at every eighth position is assumed. If .I cd (any non-digit character) is given, it is treated as the input tab character. The default for .I c is the tab character. .C nljust always expands input tabs. This option provides a way to change the tab character and setting. If this option is specified, at least one of the parameters .I c or .I k must be given. .TP .CI -r \0margin Designate a number as the print .IR margin . The print margin is the column where truncation or folding takes place. The print margin determines how many characters appear on a single line and can never exceed the print width. The print margin is relative to the justification. If the print margin is 80, folding or truncation occurs at column 80 starting from the right during a right justification. Similarly, folding or truncation occurs at column 80 starting from the left during a left justification. By default, the print margin is set to column 80. .TP .CI -w \0width Designates a number as the print .IR width . The print width is the maximum number of columns in the print line. Print width determines the start of text during a right justification. The larger the print width, the further to the right the text will start. By default, an 80-column print width is used. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables The .C LANGOPTS environment variable determines the mode and order of the file. The syntax of .C LANGOPTS is .RI [ \|mode\| ]\|[ \|_order\| ]. .I mode describes the mode of a file where .C l represents Latin mode and .C n represents non-Latin mode. Non-Latin mode is assumed for values other than .C l and .CR n . .I order describes the data order of a file where .C k is keyboard and .C s is screen. Keyboard order is assumed for values other than .C k and .CR s . Mode and order information in .C LANGOPTS can be overridden from the command line. .PP The .C LC_ALL environment variable determines the direction of a language (left-to-right or right-to-left) and whether context analysis of characters is necessary. .PP The .C LC_NUMERIC environment variable determines whether a language has alternative numbers. .PP The .C LANG environment variable determines the language in which messages are displayed. .SS International Code Set Support Single-byte character code sets are supported. .SH EXAMPLES Right justify .C file1 on a 132-column printer with a print margin at column 80 (the default): .IP .C "nljust -w 132 file1 | lp" .PP Right justify .C pr output of .C file2 with line numbers on a 132-column printer with a print margin at column 132: .IP .C "pr -n file2 | nljust -w 132 -r 132 | lp" .SH WARNINGS If .C pr with line numbers .RC ( -n option) is piped to .CR nljust , the separator character must be a tab (0x09). .PP It is the user's responsibility to ensure that the .C LANGOPTS environment variable accurately reflects the status of the file. .PP Mode and justification must be consistent. Only non-Latin-mode files can be right justified in a meaningful way. Similarly, only Latin-mode files can be safely left justified. If mode and justification do not match, the results are undefined. .PP If present, alternative numbers always have a left-to-right orientation. .SH AUTHOR .C nljust was developed by HP. .SH SEE ALSO forder(1), lp(1), pr(1), strord(3C), hpnls(5). .\" .\" index@\f4nljust\f1 \- justify lines left or right for \s-1NLS\s+1 printing@@@\f3nljust(1)\f1 .\" index@\s-1NLS\s+1: justify lines left or right for \s-1NLS\s+1 printing@@@\f3nljust(1)\f1 .\" index@justify lines left or right for \s-1NLS\s+1 printing@@@\f3nljust(1)\f1 .\" index@lines, justify left or right for \s-1NLS\s+1 printing@@@\f3nljust(1)\f1 .\" index@left or right justify lines for \s-1NLS\s+1 printing@@@\f3nljust(1)\f1 .\" index@right or left justify lines for \s-1NLS\s+1 printing@@@\f3nljust(1)\f1 .\" .\" toc@\f3nljust(1)\f1:\0\0\f4nljust\f1@@@justify lines, left or right, for printing .\" $Header: nm.1,v 78.1 96/04/05 11:33:07 ssa Exp $ .TA n .TH nm 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nm \- print name list of common object file .SH SYNOPSIS .CR /usr/ccs/bin/nm .RC [ \-AefghnNqrTuvV ] .RC [ \-d \(or \-o\c .RC \(or \-x ] .RC [ \-p \(or \-P ] .RC [ \-t .IR format ] .IR file \0... .SH DESCRIPTION The .CR nm command displays the symbol table of each object file, .IR file . .PP .I file can be a relocatable object file or an executable object file, or it can be an archive of relocatable or executable object files. .PP There are three general output formats: the default (neither .CR \-p nor .CR \-P specified), .CR \-p specified, and .CR \-P specified. The output formats are described after the "Options" subsection. .PP .SS Options .CR nm recognizes the following options: .RS .TP 15 .CR \-A Prefix each output line with the name of the object file or archive, .IR file . Equivalent to .CR \-r . .TP .CR \-d Display the .I value and .I size of a symbol in decimal. This is the default for the default format or the .CR \-p format. Equivalent to .CR "-t\ d" . .TP .CR \-e Display only .CR external and .CR static symbols. This option is ignored (see .CR \-f ). .TP .CR \-f Display full output. This option is in force by default. .TP .CR \-g Display only .CR external (global) symbol information. .TP .CR \-h Do not display the output header data. .TP .CR \-n Sort symbols by .IR name , in ascending collation order, before they are printed. This is the default. See "Environment Variables" in EXTERNAL INFLUENCES below. .TP .CR \-N Display symbols in the order in which they appear in the symbol table. .TP .CR \-o Display the .I value and .I size of a symbol in octal. Equivalent to .CR "-t\ o" . .TP .CR \-p Display information in a blank-separated output format. Each symbol .I name is preceded by its value (blanks if undefined) and one of the letters .CR U (undefined), .CR A (absolute), .CR T (text symbol), .CR D (data symbol), .CR B (bss symbol), or .CR C (common symbol). If the symbol is local (nonexternal), the type letter is in lowercase. If the symbol is a secondary definition, the type letter is followed by the letter .CR S . Note that .CR \-p is not compatible with .CR \-P . .TP .CR \-P Display information in a portable output format, as specified below, to standard output. Note that .CR \-P is not compatible with .CR \-p . .TP .CR \-q Silence some warning messages. .TP .CR \-r Prefix each output line with the name of the object file or archive, .IR file . Equivalent to .CR \-A . .TP .CI \-t \0format Display each numeric value in the specified format. .I format can be one of: .RS .TP .CR d Display the .I value and .I size of a symbol in decimal. This is the default for the default format or the .CR \-p format. Equivalent to .CR "-d" . .TP .CR o Display the .I value and .I size of a symbol in octal. Equivalent to .CR "-o" . .TP .CR x Display the .I value and .I size of a symbol in hexadecimal. This is the default for the .CR \-P format. Equivalent to .CR "-x" . .RE .TP .CR \-T Truncate every name that would otherwise overflow its column and place an asterisk as the last character in the displayed name to mark it as truncated. If .CR \-A or .CR \-r is also specified, the .IR file prefix is truncated first. .IP By default, .CR nm prints the entire name of the symbols listed. Since object files can have symbol names with an arbitrary number of characters, a name that is longer than the width of the column set aside for names will overflow its column, forcing every column after the name to be misaligned. .TP .CR \-u Display undefined symbols only. .TP .CR \-v Sort symbols by .I value before they are printed. .TP .CR \-V Display the executing version of the .CR nm command on standard error. .TP .CR \-x Display the .I value and .I size of a symbol in hexadecimal. This is the default for the .CR \-P format. Equivalent to .CR "-t\ x" . .RE .SS Default Output Format If the default (neither the .CR \-p nor the .CR \-P option) output format is specified, each symbol has the following columns, separated by vertical bars .RC ( | ). The default for numbers is decimal .RC ( \-d or .CR "\-t\ d" ). .PP If decimal: .IP .C """%20s|%10d|%6s|%7s|%s""," .IC name , .IC value , .IC scope , .IC type , .IC subspace .PP If octal: .IP .C """%20s|%012o|%6s|%7s|%s""," .IC name , .IC value , .IC scope , .IC type , .IC subspace .PP If hexadecimal: .IP .C """%20s|0x%08x|%6s|%7s|%s""," .IC name , .IC value , .IC scope , .IC type , .IC subspace .PP .RS The descriptions are explained below: .TP 15 .I name The name of the symbol. .TP .I value Its value expressed as an offset or an address depending on its storage class. .TP .I scope The scope of the symbol .RC ( external , .CR sdef , .CR static , or .CR undefined ). The .CR sdef scope indicates an external symbol that is flagged as a secondary definition. .TP .I type The type of the symbol .RC ( absolute , .CR arg_ext , .CR code , .CR data , .CR entry , .CR milli_ext , .CR millicode , .CR module , .CR null , .CR oct_dis , .CR plabel , .CR pri_prog , .CR sec_prog , .CR storage , .CR stub , .CR sym_ext ). .TP .I subspace The subspace to which the symbol belongs. .RE .SS Output Format for \(mip If the .CR \-p option is specified, information is displayed using the following portable C-language formats. The default for numbers is decimal .RC ( \-d or .CR "\-t\ d" ). .PP If decimal: .C """%010d %s %s""," .IC value , .IC type , .IC name .PP If octal: .C """%012o %s %s""," .IC value , .IC type , .IC name .PP If hexadecimal: .C """0x%08x %s %s""," .IC value , .IC type , .IC name .PP If .CR \-A or .CR \-r , the line is preceded by: .C """%20s:""," .IC file .RE .SS Output Format for \(miP If the .CR \-P option is specified, information is displayed using the following portable C-language formats. The default for numbers is hexadecimal .RC ( \-x or .CR "\-t\ x" ). In the format string, .CR %s represents string output; .CR %d represents decimal output; .CR %o represents octal output; .CR %x represents hexadecimal output; .CR \en represents newline; all other characters represent themselves. .RS 2 .TP 3 \(bu If decimal is specified: .RS .IP .C """%s%s %s %d %d\en""," .IC library-object , .IC name , .IC type , .IC value , .I size .RE .TP \(bu If octal is specified: .RS .IP .C """%s%s %s %o %o\en""," .IC library-object , .IC name , .IC type , .IC value , .I size .RE .TP \(bu If hexadecimal is specified, or by default: .RS .IP .C """%s%s %s %x %x\en""," .IC library-object , .IC name , .IC type , .IC value , .I size .RE .RE .PP where .I library-object is a string preformatted as follows: .RS 2 .TP 3 \(bu If .CR \-A and .CR \-r are not specified, .I library-object is an empty string. .TP \(bu If .CR \-A or .CR \-r is specified, and the corresponding .I file operand does not name a library: .RS .IP .C """%s: ""," .I file .RE .TP \(bu If .CR \-A or .CR \-r is specified and the corresponding .I file operand names a library, .I object-file names the object file in the library containing the symbol being described: .RS .IP .C """%s[%s]: ""," .IC file , .I object-file .RE .RE .PP If .CR \-A and .CR \-r are not specified, and if more than one .I file operand is specified, or if a single .I file operand that names a library is specified, then .CR nm prints a line identifying the object containing the symbols before the lines containing those symbols, in one of the following forms: .RS 2 .TP 3 \(bu If the corresponding .I file operand does not name a library: .RS .IP .C """%s:\en""," .I file .RE .TP \(bu If the corresponding .I file operand names a library, .I object-file names the object file in the library containing the symbol being described: .RS .IP .C """%s[%s]:\en""," .IC file , .I object-file .RE .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .PP The following internationalization variables affect the execution of .CR nm : .PP .CR LANG determines the locale category for native language, local customs and coded character set in the absence of .CR LC_ALL or other .CI LC_ * environment variables. If .CR LANG is not specified or is null, it defaults to .CR C (see .IR lang (5)). .RE .PP .CR LC_ALL , if set to a nonempty string value, determines the values for all locale categories and has precedence over .C LANG and other .C LC_* environment variables. .RE .PP .CR LC_COLLATE determines the locale category for character collation. .PP .CR LC_CTYPE determines the locale category for character handling functions. .PP .CR LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error. .PP .CR LC_NUMERIC determines the locale category for numeric formatting. .PP .CR NLSPATH determines the location of message catalogues for processing .CR LC_MESSAGES . .PP If an internationalization variable is not specified or is null, it defaults to the value of .CR LANG . .PP If .CR LANG is not specified or is null, it defaults to .CR C (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, then all internationalization variables default to .CR C (see .IR environ (5)). .SS International Code Set Support Single-byte character code sets are supported. .SH EXAMPLES Display which object files have undefined references for the symbol .CR leap : .IP .C "nm \-rup *.o | grep leap" .PP Display which object files have a definition for the text symbol leap: .IP .C "nm \-rp *.o | awk '{ if ($3 == ""T"" && $4 == ""leap"") { print $0 } }'" .SH WARNINGS By default, .CR nm now sorts symbols by name (the .CR \-n option). To turn off sorting, use the .CR \-N option. .PP Some options added for standards conformance duplicate the functionality of options that previously existed. This duplication has been retained for backward compatibility. .SH SEE ALSO .PD .SS System Tools .TP 20 .PD 0 cc(1) HP-UX ANSI C compiler .TP ld(1) Link editor .PD .SS Miscellaneous .TP 20 .PD 0 crt0(3) Execution startup routine .TP end(3C) Symbol of the last locations in program .PD .SH STANDARDS CONFORMANCE .CR nm ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4nm\f1 \- print name list of common object file@@@\f3nm(1)\f1 .\" index@name list (symbol table) of object code file, print@@@\f3nm(1)\f1 .\" index@print name list of object code file@@@\f3nm(1)\f1 .\" index@print symbol table for object code file@@@\f3nm(1)\f1 .\" index@symbol table for object code file, print@@@\f3nm(1)\f1 .\" index@table, symbol, for object code file, print@@@\f3nm(1)\f1 .\" index@object code file, print symbol table (name list) for@@@\f3nm(1)\f1 .\" .\" toc@\f3nm(1)\f1:\0\0\f4nm\f1@@@print name list of common object file .\" $Header: nohup.1,v 76.2 95/08/04 16:11:01 ssa Exp $ .TA n .TH nohup 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nohup \- run a command immune to hangups .SH SYNOPSIS .C nohup command [ arguments ] .SH DESCRIPTION .C nohup executes .I command with hangups and quits ignored. If output is not redirected by the user, both standard output and standard error are sent to .CR nohup.out . If .C nohup.out is not writable in the current directory, output is redirected to .CR $HOME/nohup.out ; otherwise, .C nohup fails. If a file is created, the file's permission bits will be set to .C S_IRUSR | S_IWUSR. .PP If output from .C nohup is redirected to a terminal, or is not redirected at all, the output is sent to .CR nohup.out . .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C nohup behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES It is frequently desirable to apply .CR nohup to pipelines or lists of commands. This can be done only by placing pipelines and command lists in a single file, called a shell script. To run the script using .CR nohup : .IP .C nohup sh file .PP .C nohup features apply to the entire contents of .IR file . If the shell script .I file is to be executed often, the need to type .C sh can be eliminated by setting execute permission on .IR file . The script can also be run in the background with interrupts ignored (see .IR sh (1)): .IP .C nohup file & .PP .I file typically contains normal keyboard command sequences that one would want to continue running in case the terminal disconnects, such as: .IP .C "tbl ofile | eqn | nroff > nfile" .SH WARNINGS Be careful to place punctuation properly. For example, in the command form: .IP .C nohup command1; command2 .PP .C nohup applies only to .IR command1 . To correct the problem, use the command form: .IP .C nohup (command1; command2) .PP Be careful of where standard error is redirected. The following command may put error messages on tape, making it unreadable: .IP .C "nohup cpio -o /dev/rmt/c0t0d0BEST&" .PP whereas .IP .C "nohup cpio -o /dev/rmt/c0t0d0BEST 2>errors&" .PP puts the error messages into file .CR errors . .SH EXIT STATUS The following exit values are returned: .RS .TP 10 .C 126 The command specified by .IR command was found but could not be invoked .TP .C 127 An error occurred in the nohup utility or the specified .IR command could not be found .RE .IP Otherwise, the exit status of nohup will be that of the command specified. .SH SEE ALSO chmod(1), nice(1), sh(1), signal(5). .SH STANDARDS CONFORMANCE .CR nohup ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4nohup\f1 \- run a command immune to hangups@@@\f3nohup(1)\f1 .\" index@\f1run a command immune to hangups@@@\f3nohup(1)\f1 .\" index@\f1command, run immune to hangups@@@\f3nohup(1)\f1 .\" index@\f1hangups, run a command immune to@@@\f3nohup(1)\f1 .\" .\" toc@\f3nohup(1)\f1:\0\0\f4nohup\f1@@@run a command immune to hangups .\" $Header: nroff.1,v 76.1 95/07/05 17:36:12 ssa Exp $ .TA n .TH nroff 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nroff \- format text .SH SYNOPSIS .C nroff .RI [ \|options\| ] .IR file \0... .SH DESCRIPTION .C nroff is a text formatting program that interprets source text contained in .I file and prepares it for printing on typewriter-like devices and line printers. If .I file name is .C - or not specified, standard input is used as source text. .PP If the file contains plain text with no formatter requests, .CR nroff uses default line lengths and page dimensions to produce readable output, outputting a blank line for each blank line encountered in the input, and filling and adjusting text to both margins. .CR nroff ignores any lines in the source text that begin with a period .RC ( . ) but are not valid .CR nroff formatter requests. .PP .C nroff formatting capabilities are described in the tutorial cited below. .SS Source File Preparation Document source file preparation is usually easier when text is coded using macro packages such as .IR mm (1) which provide a high-level interface for headings, page footers, lists, and other features, rather than coding the file with inherently low-level .CR nroff requests. .SS Options .C nroff recognizes the following command-line .IR options , which can appear in any order but must appear before the .I file argument: .RS .TP 15 .CI -o list Print only pages whose page numbers appear in the .I list of numbers and ranges, separated by commas. A range .IC n - m means pages .I n through .IR m ; an initial .CI - n means from the beginning to page .IR n ; and a final .IC n - means from .I n to the end. (See WARNINGS below.) .TP .CI -n n Number first generated page .IR n . .TP .CI -s n Stop every .I n pages. .CR nroff halts .I after every .I n pages (default .IR n =1) to allow paper loading or changing, and resumes upon receipt of a line-feed or new-line (new-lines do not work in pipelines, such as with .CR mm ). When .CR nroff halts between pages, an ASCII .CR BEL is sent to the terminal. .TP .CI -r aN Set register .I a (which must have a one-character name) to .IR N . .TP .C -i Read standard input after .I files are exhausted. .TP .C -q Invoke the simultaneous input-output mode of the .CR .rd request. .TP .C -z Print only messages generated by .CR .tm (terminal message) requests. .TP .CI -m name Precede the input .I files with the non-compiled (\c ASCII text) macro file .RS .IP .CI /usr/lib/nls/ LANG /tmac/tmac. name\f1 .RE .IP where .I LANG is the value of the .CR LANG environment variable. If .CR LANG is not set or .RS .IP .CI /usr/lib/nls/ LANG /tmac/tmac. name .RE .IP does not exist, the following file is used instead: .RS .IP .CI /usr/share/lib/tmac/tmac. name .RE .TP .CI -T name Prepare output for specified terminal. Known .IR name s are as follows: .RS .RS .TP 8 .C 37 for the (default) TELETYPE Model 37 terminal .PD 0 .TP .C tn300 for the GE TermiNet 300 (or any terminal without half-line capability) .TP .C 300s for the DASI 300s .TP .C 300 for the DASI 300 .TP .C 450 for the DASI 450 .TP .C lp for a (generic) ASCII line printer .TP .C 382 for the DTC-382 .TP .C 4000A for the Trendata 4000A .TP .C 832 for the Anderson Jacobson 832 .TP .C X for a (generic) EBCDIC printer .TP .C 2631 for the Hewlett-Packard 2631 line printer .TP .C klp for a (generic) 16-bit character printer having ratio of 2 to 3 in 8-bit and 16-bit character width .TP .C lj for Hewlett-Packard PCL3 and newer laser printers. .PD .RE .RE .TP .C -e Produce equally-spaced words in adjusted lines, using the full resolution of the particular terminal. .TP .C -h Use output tabs during horizontal spacing to speed output and reduce output character count. Tab settings are assumed to be every eight nominal character widths. .TP .CI -u n Set the emboldening factor (number of character overstrikes) for the third font position (bold) to .IR n , or to zero if .I n is missing. .TP .C -P If this option is specified on the command line, it allows the use of the special feature provided by some Asian printers which prints two column wide characters in 3/2 column wide boxes. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text as single and/or multi-byte characters. .PP .C LANG is used to determine the search path for the .CR -m option. .CR LANG also determines the language in which messages are displayed. .PP If .CR LC_CTYPE is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR nroff behaves as if all internationalization variables are set to "C". See .IR environ (5). .SH EXAMPLES The following command prints the first five pages of the document whose .CR nroff source file is .IR filename : .IP .CI "nroff -o-5 " filename .PP Note that there should not be a space between the .CR o and the .CR - or the .CR - and the .CR 5 . .PP To print only pages 1, 3, and 4 type: .IP .CI "nroff -o1,3,4 " filename .SH WARNINGS When .CR nroff is used with the .CI -o list option inside a pipeline, it may cause a harmless "broken pipe" diagnostic if the last page of the document is not specified in .IR list . .SH FILES .TP 35 .C /usr/share/lib/macros/* Standard macro files .PD 0 .TP .C /usr/share/lib/term/* Terminal driving tables for .CR nroff .TP .C /usr/share/lib/suftab Suffix hyphenation tables .TP .C /usr/share/lib/tmac/tmac.* Standard macro files and pointers .PD .SH SEE ALSO col(1), mm(1), neqn(1), soelim(1), ul(1), man(5). .PP .C nroff/troff tutorial in the .IR "Text Formatting Users Guide" . .\" .\" index@\f4nroff\f1 \- format text@@@\f3nroff(1)\f1 .\" index@format: format text file for CRT or line-printer output@@@\f3nroff(1)\f1 .\" index@formatters: format text file for CRT or line-printer output@@@\f3nroff(1)\f1 .\" index@files, text: format text file for CRT or line-printer output@@@\f3nroff(1)\f1 .\" index@text file for CRT or line-printer output, format@@@\f3nroff(1)\f1 .\" index@CRT or line-printer output, format text file for@@@\f3nroff(1)\f1 .\" index@line-printer or CRT output, format text file for@@@\f3nroff(1)\f1 .\" .\" toc@\f3nroff(1)\f1:\0\0\f4nroff\f1@@@format text .\" .\" fileset_database@nroff.1 USER-CMDS-MAN .\" $Header: nslookup.1,v 76.2 95/05/30 09:30:41 ssa Exp $ .TA n .TH nslookup 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nslookup \- query name servers interactively .SH SYNOPSIS .C nslookup .RI [ -option \0...] .I host-to-find .RI [ \|server\| ] .br .C nslookup .RI [ -option \0...] .RC [ - .RI [ \|server\| ]\|] .SH DESCRIPTION .C nslookup is a program to query Internet domain name servers. .C nslookup has been extended to follow the configured name resolution algorithm of the host and to query NIS, as well as, DNS and host tables. .PP Both an interactive and non-interactive mode are available with .C nslookup. Interactive mode allows the user to query a name server for information about various hosts and domains, or print a list of hosts in the domain. Non-interactive mode is used to query a name server for information about one host or domain. .PP By default, .C nslookup accesses name services for name and address resolution based on the policy information obtained from the switch configuration file (see .IR switch(4)). When the policy is set to use NIS or .CR /etc/hosts first, or when DNS is first but unavailable, then .C nslookup will only provide a limited command set (a .C help command while in this situation will show what actions are possible when querying NIS or .CR /etc/hosts .) To override the switch policy and query DNS servers directly, the .C server command can be used to specify a nameserver. This same overriding of the switch policy can also be done by providing a nameserver as the second argument on the command line. In this case, .C nslookup will ignore the switch policy and directly query nameservers, until a .I reset command is issued. Whenever an action is taken that causes the switch policy to be overridden, a warning message is displayed. .SH ARGUMENTS .PP Interactive mode is entered in the following cases: .RS .TP 3 \(bu No arguments are given. .TP \(bu The first argument is a hyphen .RC ( - ). The optional second argument is a host name or Internet (IP) address of a name server. .RE .PP Non-interactive mode is used when the name of the host to be looked up is given as the first argument. The optional second argument is a host name or Internet address of a name server. .PP Options listed under the .C set command below can be specified one per line in the .C .nslookuprc file in the user's home directory. Alternatively, these options may be specified on the command line by prefixing them with a hyphen and they must precede other command line arguments. For example, to change the default query type to host information, and the initial timeout to 10 seconds, type: .IP .C "nslookup -query=hinfo -timeout=10" .PP The command line option .C -swdebug may be used to debug syntactic errors in the switch configuration file. This option turns on tracing during initialization, causing the switch module to print out a trace of the scan and parse actions on the "hosts" entry (see .IR switch(4)) in the .C /etc/nsswitch.conf file. .SS Interactive Commands Commands can be interrupted at any time by using the interrupt character. To exit, type a Ctrl-D (EOF) or type .CR exit . To treat a built-in command as a host name, precede it with an escape character .RC ( \e ). When using NIS or the host table, only host names and Internet addresses are allowed as commands. An unrecognized command is interpreted as a host name. .PP .TP 15 .IR host\0 [ server ] Look up information for .I host using the current default server or using .I server if specified. If .I host is an Internet address and the query type is .C A or .CR PTR , the name of the host is returned. If .I host is a name and does not have a trailing period, one or more domains are appended to the name (this behavior depends on the state of the .C set options .CR domain , .CR srchlist , .CR defname , and .CR search ). Answers from a name server's cache are labeled ``non-authoritative.'' .TP .CI server\0 domain .PD 0 .TP .CI lserver\0 domain Change the default server to .IR domain . .C lserver uses the initial server to look up information about .I domain while .C server uses the current default server. When .C server is used while the current name service being pointed to is either NIS or .CR /etc/hosts , then the switch policy will be overridden until a .C reset is issued. .PD .TP .C root Changes the default server to the server for the root of the domain name space. Currently, the host .C ns.nic.ddn.mil is used (this command is a synonym for .CR lserver ns.nic.ddn.mil). The name of the root server can be changed with the .C set root command. .TP .C policy Prints out the policy read from the switch configuration file. The number of name services specified in the file are shown, as well as the order and criteria on how the name services are to be used. The four statuses of the criteria are represented by the four positions within the square brackets. The order of the statuses are: SUCCESS, NOTFOUND, UNAVAIL and TRYAGAIN. The two actions of the criteria are represented by the two possible letters used in the four status positions: .C R for return and .C C for continue. .TP .CR finger \0[\|\f2name\f1\|]\0[ > \0\f2filename\f1\|] .PD 0 .TP .CR finger \0[\|\f2name\f1\|]\0[ >> \0\f2filename\f1\|] Connects with the finger server on the current host. The current host is defined when a previous lookup for a host was successful and returned address information (see the .C set querytype=A command). .I name is optional. .C > and .C >> can be used to redirect output in the usual manner. .PD .TP .CR ls \0[\|\f2option\f1\|]\0\f2domain\f1\0[ > \0\f2filename\f1\|] .PD 0 .TP .CR ls \0[\|\f2option\f1\|]\0\f2domain\f1\0[ >> \0\f2filename\f1\|] List the information available for .IR domain , optionally creating or appending to .IR filename . The default output contains host names and their Internet addresses. .I option can be one of the following: .PD .RS .RS .TP 15 .CI -t \0querytype lists all records of the specified type (see .I querytype below). .TP .C -a lists aliases of hosts in the domain (synonym for .CR -t\0CNAME ). .TP .C -d lists all records for the domain (synonym for .CR -t\0ANY ). .TP .C -h lists CPU and operating system information for the domain (synonym for .CR -t\0HINFO ). .TP .C -s lists well-known services of hosts in the domain (synonym for .CR -t\0WKS ). .RE .RE .IP When output is directed to a file, .C # characters are printed for every 50 records received from the server. .TP .CI view \0filename Sorts and lists the output of previous .C ls command(s) using .C more (see .IR more (1)). .TP .C help .PD 0 .TP .C ? Prints a brief summary of commands. .PD .TP .C exit Exits the program. .TP .C reset Returns to the use of the configured name service switch policy and resets to use the original nameservers. .TP .CR set \0\f2keyword\f1[ = \f2value\f1\|] This command is used to change state information that affects the lookups. Valid keywords are: .RS .RS .TP 15 .C all Prints the current values of the various options to .CR set . Information about the current default server and host is also printed. .TP .CR cl [ ass ] = \f2value\f1 Change the query class to one of: .RS .RS .TP 10 .C IN the Internet class. .TP .C CHAOS the Chaos class. .TP .C HESIOD the MIT Athena Hesiod class. .TP .C ANY wildcard (any of the above). .RE .RE .IP The class specifies the protocol group of the information. .br (Default = .CR IN ) .TP .ift .RC [\f4\s+1no\s0\f1] deb [\f4\s+1ug\s0\f1] .ifn .RC [\f3no\f1] deb [\f3ug\f1] Turn debugging mode on. More information is printed about the packet sent to the server and the resulting answer. .br (Default = .CR nodebug ) .TP .RC [ no ] d2 Turn exhaustive debugging mode on. Essentially all fields of every packet are printed. .br (Default = .CR nod2 ) .TP .ift .RC [\f4\s+1no\s0\f1] def [\f4\s+1name\s0\f1] .ifn .RC [\f3no\f1] def [\f3name\f1] If set, append the default domain name to a single-component lookup request (i.e., one that does not contain a period character). .br (Default = .CR defname ) .TP .CR do [ main ] = \f2name\f1 Change the default domain name to .IR name . The default domain name is appended to a lookup request, depending on the state of the .C defname and .C search options. The domain search list contains the parents of the default domain if it has at least two components in its name. For example, if the default domain is .CR CC.Berkeley.EDU , the search list is .C CC.Berkeley.EDU and .CR Berkeley.EDU . Use the .C set srchlist command to specify a different list. Use the .C set all command to display the list. .br (Default = value from hostname, .C /etc/resolv.conf or .CR LOCALDOMAIN ) .TP .ift .RC [\f4\s+1no\s0\f1] ig [\f4\s+1nore\s0\f1] .ifn .RC [\f3no\f1] ig [\f3nore\f1] Ignore truncation errors. .br (Default = .CR noignore ) .TP .CR q [ uerytype ] = \f2value\f1 .PD 0 .TP .CR ty [ pe ] = \f2value\f1 Change the type of information returned from a query to one of: .PD .RS .RS .TP 12 .C A Host's Internet address .TP .C ANY All types of data .TP .C CNAME Canonical name for an alias .TP .C GID Group ID .TP .C HINFO Host CPU and operating system type .TP .C MB Mailbox domain name .TP .C MG Mail group member .TP .C MINFO Mailbox or mail list information .TP .C MR Mail rename domain name .TP .C MX Mail exchanger .TP .C NS Name server for the named zone .TP .C PTR Host name if the query is an Internet address, otherwise the pointer to other information. .TP .C SOA Start of authority record .TP .C TXT Text information .TP .C UID User ID .TP .C UINFO User information .TP .C WKS Well-known service description .RE .RE .TP .CR po [ rt ] = \f2value\f1 Change the default TCP/UDP name server port to .IR value . .br (Default = 53) .TP .ift .RC [\f4\s+1no\s0\f1] rec [\f4\s+1urse\s0\f1] .ifn .RC [\f3no\f1] rec [\f3urse\f1] Tell the name server to query other servers if it does not have the information. .br (Default = .CR recurse ) .TP .CR ret [ ry ] = \f2number\f1 Set the number of retries to .IR number . When a reply to a request is not received within a certain amount of time (changed with .CR "set timeout" ), the timeout period is doubled and the request is resent. The retry value controls how many times a request is resent before giving up. .br (Default = 4) .TP .CR ro [ ot ] = \f2host\f1 Change the name of the root server to .IR host . This affects the .C root command. .br (Default = .CR ns.nic.ddn.mil ) .TP \f3[no]sea[rch]\f1 If the lookup request contains at least one period but doesn't end with a trailing period, append the domain names in the domain search list to the request until an answer is received. See .IR hostname (5). .br (Default = .CR search ) .TP .CR srchl [ ist ]= \f2name1/name2/...\f1 Change the default domain name to .I name1 and the domain search list to .IR name1 , .IR name2 , etc. A maximum of 6 names separated by slashes .RC ( \|/\| ) can be specified. For example, .RS .IP .C set srchlist=lcs.MIT.EDU/ai.MIT.EDU/MIT.EDU .RE .IP sets the domain to .C lcs.MIT.EDU and the search list to the three names. This command overrides the default domain name and search list of the .C set domain command. Use the .C set all command to display the list. .br (Default = value based on hostname, .C /etc/resolv.conf or .CR LOCALDOMAIN ) .TP \f3[no]swtr[ace]\f1 When set, this flag causes .C nslookup to print out information about the sources used for resolving a name or an address lookup. This flag traces the behavior generated by the switch policy (see .IR switch(4)). .br (Default = .CR noswtrace ) .TP .CR t [ imeout ] = \f2number\f1 Change the initial timeout interval for waiting for a reply to .I number seconds. Each retry doubles the timeout period. .br (Default = 5 seconds) .TP .ift .RC [\f4\s+1no\s0\f1] v [\f4\s+1c\s0\f1] .ifn .RC [\f3no\f1] v [\f3c\f1] Always use a virtual circuit when sending requests to the server. .br (Default = .CR novc ) .RE .SH DIAGNOSTICS If the lookup request was not successful, an error message is printed. Possible errors are: .RS .TP .C Time-out The server did not respond to a request after a certain amount of time (changed with .C set timeout=\c .IR value ) and a certain number of retries (changed with .C set retry=\c .IR value ). .TP .C No response from server No name server is running on the server machine. .TP .C No records The server does not have resource records of the current query type for the host, although the host name is valid. The query type is specified with the .C set querytype command. .TP .C Non-existent domain The host or domain name does not exist. .TP .C Connection refused .PD 0 .TP .C Network is unreachable The connection to the name server could not be made at the present time. .PD .TP .C Server failure The name server found an internal inconsistency in its database and could not return a valid answer. .TP .C Refused The name server refused to service the request. .TP .C Format error The name server found that the request packet was not in the proper format. .RE .SH AUTHOR .C nslookup was developed by the University of California, Berkeley. .SH FILES .PD 0 .TP 30 .C /etc/resolv.conf Initial domain name and name server addresses .TP .C $HOME/.nslookuprc User's initial options .PD .SH SEE ALSO named(1M), resolver(3N), resolver(4), switch(4), hostname(5), .PP RFC1034, RFC1035 .\" .\" index@\f4nslookup\f1 \- query name servers interactively@@@\f3nslookup(1)\f1 .\" index@\f1query name servers interactively@@@\f3nslookup(1)\f1 .\" index@\f1name servers, query interactively@@@\f3nslookup(1)\f1 .\" index@\f1servers, name, query interactively@@@\f3nslookup(1)\f1 .\" .\" toc@\f3nslookup(1)\f1:\0\0\f4nslookup\f1@@@query name servers interactively .\" .\" fileset_database@nslookup.1 INETSVCS-MAN .\" $Header: od.1,v 76.1 95/08/23 17:32:12 ssa Exp $ .TA o .TH od 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME od, xd \- octal and hexadecimal dump .SH SYNOPSIS .IP .CR "od" .RC [ -v ] .RC [ -A .IR address_base \|] .RC [ -j .IR skip \|] .RC [ -N .IR count \|] .RC [ -t .IR type_string \|]\0... .RI [ \|file \0...\|] .IP .C xd .RC [ -v ] .RC [ -A .IR address_base \|] .RC [ -j .IR skip \|] .RC [ -N .IR count \|] .RC [ -t .IR type_string \|]\0... .RI [ \|file \0...\|] .PP The following pre-\c .SM POSIX usage is also supported. .IP .C od .RC [ -bcdosx ] .RI [ \|file\| ] .RC [\|[ + ]\|[ 0x ]\c .I offset\c .RC [ . ]\|[ b ]\|] .br .C xd .RC [ -bcdosx ] .RI [ \|file\| ] .RC [\|[ + ]\|[ 0x ]\c .I offset\c .RC [ . ]\|[ b ]\|] .SH DESCRIPTION .C od and .C xd concatenate one or more input .IR file s and write their contents to standard output in a user-specified format. If .I file is not specified, the standard input is used. .SS Options and Arguments .C od and .C xd recognize the following options and command-line arguments: .RS .TP 18 .CI -A \0address_base Specify the input offset base. .I address_base is a single character that defines which format the offset base is written in: .RS .RS .TP .C d Decimal format. .PD 0 .TP .C o Octal format. .TP .C x Hexadecimal format. .TP .C n Do not write the offset. .RE .RE .PD .TP .CI -j \0skip Jump over .I skip bytes from the beginning of the input. .C od seeks past the first .I skip bytes in the concatenated input files. If the combined input is not at least .I skip bytes long, .C od writes a diagnostic message to standard error and exits with a non-zero exit status. By default, .I skip is interpreted as a .I decimal number. If .I skip has a leading .C 0x or .CR 0X , it is interpreted as a .I hexadecimal number; a leading .C 0 indicates that .I skip is an .I octal number. .IP If the value of .I skip is followed by a .CR b , .CR k , or .CR m , it is interpreted as a multiple of 512, 1024, or 1048576, respectively. .TP .CI -N \0count Format no more than .I count bytes of input. .IP By default, .I count is interpreted as a .I decimal number. A leading .C 0x or .C 0X indicates that .I count is a .I hexadecimal number; a leading .C 0 identifies an .I octal value. .IP If .I count bytes of input are not available (after successfully skipping if .CI -j skip is specified), the input that is available is formatted. .TP .CI -t \0type_string .I type_string is a string defining the types to be used when writing the input data. .IP The string can contain any of the following type-specification characters: .RS .RS .TP 8 .C a named character , .PD 0 .TP .C c character , .TP .C d signed decimal , .TP .C f floating point , .TP .C o octal , .TP .C u unsigned decimal , .TP .C x hexadecimal , .RE .RE .PD .IP Type specification characters .CR d , .CR f , .CR o , .CR u , and .CR x can be followed by an optional .I unsigned decimal integer specifying the number of bytes to be transformed by each instance of the output type, or by an optional .CR C , .CR S , .CR I , or .CR L indicating that the conversion should be applied to an item of type .IR char , .IR short , .IR int , or .IR long , respectively. .IP Type specification character .C f can be followed by an optional .CR F , .CR D , or .C L indicating that the conversion should be applied to an item of type .IR float , .IR double , or .IR "long double" , respectively. .IP Multiple types can be concatenated within the same .I type_string and multiple .C -t options can be specified. Output lines are written for each type specified in the order in which the type specification characters appear. .TP .CI -v Write all input data. Without the .C -v option, any number of groups of output lines, that would be identical to the immediately preceding group of output lines (except for the byte offsets), are replaced with a line containing only an asterisk .RC ( * ). .TP .I file Pathname of one or more input files to be processed. If .I file is not specified, the standard input is used. .IP Input files can be any file type. .RE .SH DESCRIPTION OF PRE-POSIX USAGE .C od and .C xd dump .I file in one or more formats as selected by the first argument. If the first argument is missing, the default is .C -o for .CR od ; .C -x for .CR xd . An offset field is inserted at the beginning of each line. For .CR od , the offset is in octal, for .CR xd , the offset is in hexadecimal. .SS Options .C od and .C xd recognize the following format options: .RS .TP 6 .C -b Interpret bytes in octal (hexadecimal). .TP .C -c Interpret bytes in .SM ASCII. Certain non-graphic characters appear as C escapes: .RC null= \e0 , .RC backspace= \eb , .RC form-feed= \ef , .RC new-line= \en , .RC return= \er , .RC tab= \et ; others appear as 3-digit octal numbers. .TP .C -d Interpret 16-bit words in decimal. .TP .C -o Interpret 16-bit words in octal. .TP .C -s Interpret 16-bit words in signed decimal. .TP .C -x Interpret 16-bit words in hexadecimal. .RE .PP .I file specifies which file is to be dumped. If .I file is not specified, the standard input is used. .PP .I offset specifies the offset in the file where dumping is to commence, and is normally interpreted as octal bytes. Interpretation can be altered as follows: .RS .TP 3 \(bu .I offset must be preceded by .CR + if the file argument is omitted. .PD 0 .TP \(bu .I offset preceded by .B 0x is interpreted in hexadecimal. .TP \(bu .I offset followed by .C . is interpreted in decimal. .TP \(bu .I offset followed by .C b is interpreted in blocks of 512 bytes. .RS .PD .PP Dumping continues until end-of-file. .SH EXAMPLES Write hexadecimal bytes and the corresponding octal values to the standard output in blocks of 16 bytes in one line, by transforming the data from the input file .CR file1 : .IP .C od -tx1oC file1 .PP The following commands write one line each of the types .IR character , .IR "signed decimal integer" , and .IR float , in the order given, transforming 100 bytes of data starting from fifteenth byte offset in the file .CR file1 : .IP .C "od -j14 -N100 -tc -tdfF file1" .IP .C "od -j0xe -N100 -tcd4fF file1" .PP Write one line each of the types .IR "unsigned integer" , .IR "named character" , and .IR "long double" , with the offsets written in hexadecimal and forcing a write, even on lines that are identical to the immediately preceding group of output lines: .IP .C "od -v -Ax -tuafL file1" .SH WARNINGS When the output format is of floating-point type; i.e., when using the .CR "-t fD" , .CR "-t fL" , or .C -t f options: .RS .TP 3 \(bu If the input bytes cannot be transformed into a valid floating point number, a floating point exception might occur. In that case, the output is printed as a string containing some non-numeric characters and program execution continues. .TP \(bu When the number of input bytes used for transformation is set to 1 with the type specifier characters .CR d , .CR o , .CR u , or .CR x , only the least-significant seven bits of each byte are used. .TP \(bu When one or more of the .CR -A , .CR -j , .CR -N , or .C -t options is specified, an operand starting with the first character as a plus-sign .RC ( + ) or the first character as numeric is interpreted as a file name. .RE .PP (XPG4 only. Multiple types can be specified by using multiple .CR "-bcdox" options. Output lines are written for each type specified in the order in which the types are specified.) .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C od will behave as if all internationalization variables are set to "C". See .IR environ (5). .PP .C LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .PP .C LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .C LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .C NLSPATH determines the location of message catalogues for the processing of .CR LC_MESSAGES . .PP .SS International Code Set Support Single- and multi-byte character code sets are supported. Multi-byte data is displayed as multi-byte values. .SH RETURN VALUE Exit values are: .TP .B \00 Successful completion. .PD 0 .TP .C >0 Error condition occurred. .PD .SH SEE ALSO adb(1). .SH STANDARDS CONFORMANCE .CR od ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4od\f1 \- octal file dump@@@\f3od(1)\f1 .\" index@\f4xd\f1 \- hexadecimal file dump@@@\f3od(1)\f1 .\" index@octal file dump@@@\f3od(1)\f1 .\" index@hexadecimal file dump@@@\f3od(1)\f1 .\" index@dump file in octal or hexadecimal format@@@\f3od(1)\f1 .\" index@files: dump file in octal or hexadecimal format@@@\f3od(1)\f1 .\" .\" toc@\f3od(1)\f1:\0\0\f4od\f1, \f4xd\f1@@@octal and hexadecimal dump .\" toc@\f4xd\f1: hexadecimal dump@@@see \f3od(1)\f1 .\" .\" links@od.1 xd.1 .\" .\" $Header: on.1,v 72.3 93/01/14 11:48:29 ssa Exp $ .TA o .TH on 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME on \- execute command on remote host with environment similar to local .SH SYNOPSIS .C on .RC [ -i \(or .CR -n ] .RC [ -d ] .I host .RI [ \|command .RI [ \|argument \|]\0...\0] .SH DESCRIPTION .C on executes a command on a remote host, using an environment similar to that of the invoking user where: .RS .TP 10 .I host specifies the name of the host on which to execute the command. .TP .I command specifies the command to execute on .I host .RE .PP If .I command is not specified, .C on starts a shell on .IR host . .IR argument \0... is a list of arguments for .IR command . .PP The user's environment variables are copied to the remote host, and the file system containing the user's current working directory is .SM NFS mounted on the remote host (see .IR nfs (7)). The command is executed on the remote host in the user's current working directory. .PP Commands using relative path names that reference file system objects within the user's current working file system have the same behavior as running the command on the client. The behavior of commands using relative path names that cross the file system boundary or commands using absolute path names depends on the organization of the remote host's file system. .PP Implicit and explicit use of environment variables may also cause a command's behavior to be dependent on the organization of the remote host's file system. For example, the .C $PATH environment variable usually contains absolute path names. .PP Standard input, output and error of the remote command are connected to the appropriate file descriptors on the client. .PP The remote execution daemon .RC ( rexd ) does not allow .C root to execute a remote command. .PP The signals .CR SIGINT , .CR SIGTERM , and .C SIGQUIT are propagated to the remote command. .C SIGTSTP and .C SIGSTOP are ignored by the remote command. All other signals are delivered to the .C on command. .PP In order to execute a remote command, the remote host must be configured to execute .C rexd (see .IR rexd (1M)). .SS Options .C on recognizes the following options: .RS .TP 8 .C -i Interactive mode. This option is required for commands that must communicate with a terminal such as .CR vi , .CR ksh , or .CR more . Terminal mode changes are propagated to the .C rexd server. The standard input for an interactive .C on command must be a tty device. The .C -i and .C -n options are mutually exclusive. .TP .C -d Debug mode. Print diagnostic messages during startup of the .C on command. These messages are useful for detecting configuration problems if the .C on command to a specific host is failing. .TP .C -n No input mode. This option causes the remote command to get end-of-file .SM (EOF) when it reads from standard input, instead of connecting the standard input of the .C on command to the standard input of the remote command. The .C -n option is required when running commands in the background. The .C -n and .C -i options are mutually exclusive. .SH DIAGNOSTICS .TP 10 .CI "on: unknown host " host The host name .I host was not found in the hosts database. .TP .CI "on: cannot connect to server on " host The host .I host is down, unreachable on the network, or not running .CR rexd . .TP .CI "on: can't find " current_dir A problem occurred trying to find the user's current working directory .RI ( \|current_dir\| ). .TP .CI "on: can't locate mount point for " current_dir A problem occurred trying to determine the mount point of the user's current working directory .RI ( \|current_dir\| ). .TP .C "on: standard input (stdin) is not a tty" The standard input (stdin) of the .C on command with the .C -i option is not a tty device. .TP .CI "on " server ": rexd: " message Errors that occur on the server .I server are propagated back to the client. These messages are documented in the .SM DIAGNOSTICS section of .IR rexd (1M). .SH AUTHOR .C on was developed by Sun Microsystems, Inc. .SH SEE ALSO exports(4), rexd(1M). .\" .\" index@\f4on\f1 \- execute command on a remote host@@@\f3on(1)\f1 .\" index@execute command on a remote host@@@\f3on(1)\f1 .\" index@command on a remote host, execute@@@\f3on(1)\f1 .\" index@remote host, execute command on a@@@\f3on(1)\f1 .\" index@host, remote, execute command on a@@@\f3on(1)\f1 .\" .\" toc@\f3on(1)\f1:\0\0\f4on\f1@@@execute a command on a remote host; environment similar to local environment. .\" .\" fileset_database@on.1 USER-CMDS-MAN .\" $Header: mm.1,v 72.4 94/09/13 15:15:11 ssa Exp $ .TA m .TH mm 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mm, osdd \- print documents formatted with the mm macros .SH SYNOPSIS .C mm .RI [ \|options\| ] .RI [ \|files\| ] .PP .C osdd .RI [ \|options\| ] .RI [ \|files\| ] .SH DESCRIPTION .C mm can be used to format and print documents using .C nroff and the .C mm text-formatting macro package (see .IR nroff (1)). It has options to specify preprocessing by .C tbl and/or .CR neqn , (see .IR tbl (1) and .IR neqn (1)), and postprocessing by various terminal-oriented output filters. The proper pipelines and the required arguments and flags for .C nroff and .C mm are generated, depending on the options selected. .PP .C osdd is equivalent to the command .CR "mm -mosd" . .SS Options .C mm recognizes the following .I options and command-line arguments. Any other arguments or options (such as .CR -rC3 ) are passed to .C nroff or to .CR mm , as appropriate. Such options can occur in any order, but they must appear before the .I files arguments. If no arguments are given, .C mm prints a list of its options. .RS .TP 9 .CI -T term Specifies the type of output terminal; for a list of recognized values for .IR term , type .CR "help term2" . If this option is .I not used, .C mm uses the value of the shell variable .C $TERM from the environment (see .IR profile (4) and .IR environ (5)) as the value of .I term if .C $TERM is set; otherwise, .C mm uses .C 450 as the value of .IR term . If several terminal types are specified, the last one is used. .TP .C -12 Indicates that the document is to be produced in 12-pitch. Can be used when .C $TERM is set to one of .CR 300 , .CR 300s , .CR 450 , and .CR 1620 . (The pitch switch on the .SM DASI 300 and 300s terminals must be manually set to .C 12 if this option is used.) .TP .C -c Causes .C mm to invoke .IR col (1); note that .IR col (1) is invoked automatically by .C mm unless .I term is one of .CR 300 , .CR 300s , .CR 450 , .CR 37 , .CR 4000a , .CR 382 , .CR 4014 , .CR tek , .CR 1620 , and .CR X . .TP .C -e Causes .C mm to invoke .CR neqn . .TP .C -t Causes .C mm to invoke .CR tbl . .TP .C -E Invokes the .C -e option of .CR nroff . .RE .SH DIAGNOSTICS .C mm sends the message .C mm: no input file if none of the arguments is a readable file and .C mm is not used as a filter. .SH EXAMPLES Assuming that the shell variable .C $TERM is set in the environment to .CR 450 , the two command lines below are equivalent: .IP .C mm -t -rC3 -12 ghh* .br .C "tbl ghh* | nroff -cm -T450-12 -h -rC3 .PP .C mm reads the standard input when .C - is specified instead of any file names (mentioning other files along with .C - leads to disaster). This option allows .C mm to be used as a filter, as in this example: .IP .C "cat dws | mm -" .SS Hints .TP 3 \(bu .C mm invokes .C nroff with the .C -h option. With this option, .C nroff assumes that the terminal has tabs set every 8 character positions. .TP \(bu Use the .CI -o list option of .C nroff to specify ranges of pages to be output. Note, however, that .CR mm , if invoked with one or more of the .CR -e , .CR -t , and .C - options, .I together with the .CI -o list option of .C nroff may cause a harmless ``broken pipe'' diagnostic if the last page of the document is not specified in .IR list . .TP \(bu If you use the .C -s option of .C nroff (to stop between pages of output), use line-feed (rather than return or new-line) to restart the output. The .C -s option of .C nroff does not work with the .C -c option of .CR mm , or if .C mm automatically invokes .C col (see .C -c option above and .CR col (1)). .TP \(bu If you specify an incorrect output terminal type, .C mm produces (often subtle) unpredictable results. However, if you are redirecting output into a file, use the .C -T37 option, then use the appropriate terminal filter when actually printing the formatted file. .SH SEE ALSO col(1), env(1), nroff(1), tbl(1), profile(4), mm(5), term(5). .PP .C mm section in .I "Text Formatting: User's Guide" . .\" .\" index@\f4mm\f1 \- print or check documents formatted with the \f4mm\f1 macros@@@\f3mm(1)\f1 .\" index@\f4osdd\f1 \- print or check documents formatted with the \f4mm\f1 macros@@@\f3mm(1)\f1 .\" index@print or check documents formatted with the \f4mm\f1 macros@@@\f3mm(1)\f1 .\" index@check or print documents formatted with the \f4mm\f1 macros@@@\f3mm(1)\f1 .\" index@formatters: check or print documents formatted with the \f4mm\f1 macros@@@\f3mm(1)\f1 .\" index@documents, format and print using the \f4mm\f1 macros@@@\f3mm(1)\f1 .\" index@macros, check or print documents formatted using \f4mm\f1@@@\f3mm(1)\f1 .\" .\" toc@\f3mm(1)\f1:\0\0\f4mm\f1, \f4osdd\f1@@@print/check documents formatted with the mm macros .\" toc@\f4osdd\f1:\0\0print/check documents formatted with the mm macros@@@\f1see \f3mm(1)\f1 .\" .\" links@mm.1 osdd.1 .\" $Header: pack.1,v 72.4 94/11/14 15:20:30 ssa Exp $ .TA p .TH pack 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pack, pcat, unpack \- compress and expand files .SH SYNOPSIS .C pack .RC [ - ] .RC [ -f ] .IR name \0... .PP .C pcat .IR name \0... .PP .C unpack .IR name \0... .SH DESCRIPTION .C pack attempts to store the specified files in a compressed form. Wherever possible, each input file .I name is replaced by a packed file .IC name .z with the same ownership, modes, and access and modification times. The .C -f option forces packing of .IR name . This is useful for causing an entire directory to be packed even if some of the files do not benefit. If .C pack is successful, .I name is removed. Packed files can be restored to their original form using .C unpack or .CR pcat . .PP .C pack uses Huffman (minimum redundancy) codes on a byte-by-byte basis. If the .C - argument is used, an internal flag is set that causes the number of times each byte is used, its relative frequency, and the code for the byte to be printed on the standard output. Additional occurrences of .C - in place of .I name cause the internal flag to be set and reset. .PP The amount of compression obtained depends on the size of the input file and the character frequency distribution. Because a decoding tree forms the first part of each .C .z file, it is usually not worthwhile to pack files smaller than three blocks unless the character frequency distribution is very skewed such as in printer plots or pictures. .PP Typically, text files are reduced to 60-75% of their original size. Load modules, which use a larger character set and have a more uniform distribution of characters, show little compression, the packed versions being about 90% of the original size. .PP .C pack returns a value that is the number of files that it failed to compress. .PP No packing occurs if: .RS .TP 3 \(bu The file appears to be already packed. .PD 0 .TP \(bu The file name has more than 12 characters and the file system is configured as a short filename system. .TP \(bu The file has links. .TP \(bu The file is a directory. .TP \(bu The file cannot be opened. .TP \(bu The file is empty. .TP \(bu No disk storage blocks will be saved by packing. .TP \(bu A file called .IC name .z already exists. .TP \(bu The .C .z file cannot be created. .TP \(bu An I/O error occurred during processing. .RE .PD .PP On short-filename systems, the last segment of the file name must contain no more than 12 characters to allow space for the appended .C .z extension. Directories cannot be compressed. .PP .C pcat does for packed files what .IR cat (1) does for ordinary files, except that .C pcat cannot be used as a filter. The specified files are unpacked and written to the standard output. Thus to view a packed file named .IC name .z use: .IP .C pcat name.z .PP or simply: .IP .C pcat name .PP To make an unpacked copy (named .IR file ) of a packed file named .IC name .z without destroying .IC name .z\f1) use the command: .IP .C pcat name >file .PP .C pcat returns the number of files it was unable to unpack. Failure may occur if: .RS .TP 3 \(bu The file name (exclusive of the .CR .z ) has more than 12 characters; .PD 0 .TP \(bu The file cannot be opened; .TP \(bu The file does not appear to have been created by .IR pack . .RE .PD .PP .C unpack expands files created by .CR pack . For each file .I name specified in the command, a search is made for a file called .IC name .z (or just .I name if .I name ends in .CR .z ). If this file appears to be a packed file, it is replaced by its expanded version. The new file has the .C .z suffix stripped from its name, and has the same access modes, access and modification dates, and owner as those of the packed file. .PP .C unpack returns a value that is the number of files it was unable to unpack. Failure may occur for the reasons given for .CR pcat , as well as for the following: .RS .TP 3 \(bu A file with the ``unpacked'' name already exists; .PD 0 .TP \(bu The unpacked file cannot be created. .RE .PD .SS "Access Control Lists (ACLs) .C pack retains all entries in a file's access control list when compressing and expanding it (see .IR acl (5)). .SH DEPENDENCIES .SS \s-1NFS\s0 Optional access control list entries of networked files are summarized (as returned in .C st_mode by .CR stat() , but not copied to the new file (see .IR stat (2)). .SH SEE ALSO cat(1), compact(1), compress(1), acl(5). .SH STANDARDS CONFORMANCE .CR pack ": SVID2, SVID3, XPG2, XPG3" .PP .CR pcat ": SVID2, SVID3, XPG2, XPG3" .PP .CR unpack ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4pack\f1 \- compress (pack) files using Huffman code (see \f4compact\f1(1)@@@\f3pack(1)\f1 .\" index@\f4pcat\f1 \- expand (unpack) and cat Huffman coded file (see \f4compact\f1(1)@@@\f3pack(1)\f1 .\" index@\f4unpack\f1 \- expand Huffman coded files created by \f4pack\f1 (see \f4compact\f1(1)@@@\f3pack(1)\f1 .\" .\" toc@\f3pack(1)\f1:\0\0\f4pack\f1, \f4pcat\f1, \f4unpack\f1@@@compress and expand files .\" toc@\f4pcat\f1: compress and expand files@@@see \f3pack(1)\f1 .\" toc@\f4unpack\f1: compress and expand files@@@see \f3pack(1)\f1 .\" .\" links@pack.1 pcat.1 .\" links@pack.1 unpack.1 .\" .\" fileset_database@pack.1 USER-CMDS-MAN .\" $Header: more.1,v 76.1 95/08/04 15:38:26 ssa Exp $ .TA m .TH more 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME more, page \- file perusal filter for crt viewing .SH SYNOPSIS .C more .RC[ -n ] .RC[ -cdefisuvz ] .RC[ -n .IR number\| ] .RC[ -p .IR command\| ] .RC[ -t .IR tagstring\| ] .RC[ -x .IR tabs\| ] .RC[ -W .IR option\| ] .RC[ +\c .IR linenumber\| ] .RC[ +/\c .IR pattern\| ] .RI [ \|name " ...\|]" .PP .C page .RC[ -n ] .RC[ -cdefisuvz ] .RC[ -n .IR number\| ] .RC[ -p .IR command\| ] .RC[ -t .IR tagstring\| ] .RC[ -x .IR tabs\| ] .RC[ -W .IR option\| ] .RC[ +\c .IR linenumber\fP\| ] .RC[ +/\c .IR pattern\fP\| ] .RI [ \|name " ...\|]" .SH REMARKS: .C pg is preferred in some standards and has some added functionality, but does not support character highlighting (see .IR pg (1)). .SH DESCRIPTION .C more is a filter for examining continuous text, one screenful at a time, on a soft-copy terminal. It is quite similar to .CR pg , and is retained primarily for backward compatibility. .C more normally pauses after each screenful, printing the filename at the bottom of the screen. To display one more line, press .CI . To display another screenful press .CI . Other possibilities are described later. .PP .C more and .C page differ only slightly. .C more scrolls the screen upward as it prints the next page. .C page clears the screen and prints a new screenful of text when it prints a new page. Both provide one line of overlap between screenfuls. .PP .I name can be a filename or .CR - , specifying standard input. .C more processes file arguments in the order given. .PP .C more supports the Basic Regular Expression syntax (see .IR regexp (5)). .PP .C more recognizes the following command line options: .RS .TP 15 .CI -n \0number Set the number of lines in the display window to .I number, a positive decimal integer. The default is one line less than the the number of lines displayed by the terminal; on a screen that displays 24 lines, the default is 23. The .CI -n flag overrides any values obtained from the environment. .TP .CI - n Same as .CI -n \0number except that the number of lines is set to .I n. .TP .C -c Draw each page by beginning at the top of the screen, and erase each line just before drawing on it. This avoids scrolling the screen, making it easier to read while .C more is writing. This option is ignored if the terminal has no clear-to-end-of-line capability. .TP .C -d Prompt user with the message .C "Press space to continue, q to quit, h for help" at the end of each screenful. This is useful if .C more is being used as a filter in some setting, such as a training class, where many users might be unsophisticated. .TP .C -e Exit immediately after writing the last line of the last file in the argument list .TP .C -f Count logical lines, rather than screen lines. That is, long lines are not folded. This option is recommended if .I nroff output is being piped through .IR ul , since the latter can generate escape sequences. These escape sequences contain characters that would ordinarily occupy screen positions, but which do not print when sent to the terminal as part of an escape sequence. Thus .C more might assume lines are longer than they really are, and fold lines erroneously. .TP .C -i Perform pattern matching in searches without regard to case. .TP .C -s Squeeze multiple blank lines from the output, producing only one blank line. Especially helpful when viewing .I nroff output, this option maximizes the useful information present on the screen. .TP .C -u Normally, .C more handles underlining and bold such as produced by .I nroff in a manner appropriate to the particular terminal: if the terminal supports underlining or has a highlighting (usually inverse-video) mode, .C more outputs appropriate escape sequences to enable underlining, else highlighting mode, for underlined information in the source file. If the terminal supports highlighting, .C more uses that mode information that should be printed in boldface type. The .C -u option suppresses this processing, as do the "ul" and "os" terminfo flags. .TP .C -v Do not display nonprinting characters graphically; by default, all non-ASCII and control characters (except .CI , .CI , and .CI ) are displayed visibly in the form .CI ^X for .CI , or .CI M-x for non-ASCII character .CI x . .TP .C -z Same as not specifying .CI -v , with the exception of displaying .CI as .CI ^H , .CI as .CI ^M , and .CI as .CI ^I . .TP .CI -p \0command Execute the .C more command initially in the .IR command argument for each file examined. If the command is a positioning command, such as a line number or a regular expression search, sets the current position to represent the final results of the command, without writing any intermediate lines of the file. If the positioning command is unsuccessful, the first line in the file is the current position. .TP .CI -t \0tagstring Write the screenful of the file containing the tag named by the .IR tagstring argument. The specified tag appears in the current position. If both .C -p and .C -t options are specified, .C more processes .C -t first; that is, the file containing the .I tagstring is selected by .C -t and then the command is executed. .TP .CI -x \0tabs Set the tabstops every .IR tabs position. The default value for the .IR tabs argument is 8. .TP .CI -W \0option Provides optional extensions to the .C more command. Currently, the following two options are supported: .IP \0 15 .PD 0 .C notite .IP \0 20 Prevents .PD .C more from sending the terminal initialization string before displaying the file. This argument also prevents .C more from sending the terminal de-initialization string before exiting. .IP \0 15 .PD 0 .C tite .IP \0 20 Causes .PD .C more to send the initialization and de-initialization strings. This is the default. .TP .CI + linenumber Start listing such that the current position is set to .IR linenumber . .TP .CI +/ pattern Start listing such that the current position is set to the line matching the regular expression .IR pattern . .RE .PP The number of lines available per screen is determined by the .C -n option, if present or by examining values in the environment. The actual number of lines written is one less than this number, as the last line of the screen is used to write a user prompt and user input. .PP The number of columns available per line is determined by examining values in the environment. .C more writes lines containing more characters than would fit into this number of columns by breaking the line into one more logical lines where each of these lines but the last contains the number of characters needed to fill the columns. The logical lines are written independently of each other; that is, commands affecting a single line affect them separately. .PP While determining the number of lines and the number of columns, if the methods described above do not yield any number then .C more uses terminfo descriptor files (see .IR term (4)). If this also fails then the number of lines is set to 24 and the number of columns to 80. .PP When standard output is a terminal and .C -u is not specified, .C more treats backspace characters and carriage-return characters specially. .RS .TP 3 \(bu A character, followed first by a backspace character, then by an underscore (_), causes that character to be written as underlined text, if the terminal supports that. An underscore, followed first by a backspace character, then any character, also causes that character to be written as underlined text, if the terminal supports that. .TP 3 \(bu A backspace character that appears between two identical printable characters causes the first of those two characters to be written as emboldened text, if the terminal type supports that, and the second to be discarded. Immediately subsequent occurrences of backspaces/character pairs for that same character is also discarded. .TP 3 \(bu Other backspace character sequences is written directly to the terminal, which generally causes the character preceding the backspace character to be suppressed in the display. .TP 3 \(bu A carriage-return character at the end of a line is ignored, rather than being written as a control character. .RE .PP If the standard output is not a terminal device, .C more always exits when it reaches end-of-file on the last file in its argument list. Otherwise, for all files but the last, .C more prompts, with an indication that it has reached the end of file, along with the name of the next file. For the last file specified, or for the standard input if no file is specified, .C more prompts, indicating end-fo-file, and accept additional commands. If the next command specifies forward scrolling, .C more will exit. If the .C -e option is specified, .C more will exit immediately after writing the last line of the last file. .PP .C more uses the environment variable .SM .C MORE to preset any flags desired. The .C MORE variable thus sets a string containing flags and arguments, preceded with hyphens and blank-character-separated as on the command line. Any command-line flags or arguments are processed after those in the .C MORE variable, as if the command line were as follows: .PP .IP .C more $MORE .I flags arguments .PP For example, to view files using the .C -c mode of operation, the shell command sequence .IP .C "MORE='-c' ; export MORE" or the .I csh command .IP .C "setenv MORE -c" .PP causes all invocations of .CR more , including invocations by programs such as .I man and .IR msgs , to use this mode. The command sequence that sets up the .SM .C MORE environment variable is usually placed in the .I .profile or .I .cshrc file. .PP In the following descriptions, the .I current position refers to two things: .RS .TP 3 \(bu the position of the current line on the screen .TP 3 \(bu the line number (in the file) of the current line on the screen .RE .PP The line on the screen corresponding to the current position is the third line on the screen. If this is not possible (there are fewer than three lines to display or this is the first page of the file, or it is the last page of the file), then the current position is either the first or last line on the screen. .PP Other sequences that can be typed when .C more pauses, and their effects, are as follows .RI ( i is an optional integer argument, defaulting to 1): .RS .PP .PD 0 .IC i .PP .IR i\| j .PP .IC i .PP .TP 15 .PD .IC i Scroll forward .I i lines. The default .I i for .C is one screenful; for .C j and .C it is one line. The entire .I i lines are written, even if .I i is more than the screen size. At end-of-file, .C causes .C more to continue with the next file in the list, or exits if the current file is the last file in the list. .PP .PD 0 .IC i d .PP .TP 15 .PD .IC i Scroll forward .I i lines, with a default of one half of the screen size. If .I i is specified, it becomes the new default for subsequent .C d and .C u commands. .PP .PD 0 .IC i u .TP 15 .IC i .PD Scrolls backward .I i lines, with a default of one half of the screen size. If .I i is specified, it becomes the new default for subsequent .C d and .C u commands. .PP .PD 0 .IC i k .TP 15 .PD .IC i Scrolls backward .I i lines, with a default of one line. The entire .I i lines are written, even if .I i is more than the screen size. .TP .IC i z Display .I i more lines and sets the new window (screenful) size to .I i . .TP .IC i g Go to line .I i in the file, with a default of 1 (beginning of file). Scroll or rewrite the screen so that the line is at the current position. If .I i is not specified, then .C more displays the first screenful in the file. .TP .IC i G Go to line .I i in the file, with a default of the end of the file. If .I i is not specified, scrolls or rewrites screen so that the last line in the file is at the bottom of the screen. If .I i is specified, scrolls or rewrites the screen so that the line is at the current position. .TP .IC i s Skip forward .I i lines, with a default of 1, and write the next screenful beginning at that point. If .I i would cause the current position to be such that less than one screenful would be written, the last screenful in the file is written. .PP .PD 0 .IC i f .TP 15 .PD .IC i Move forward .I i lines, with a default of one screenful. At end-of-file, .C more will continue with the next file in the list, or exit if the current file is the last file in the list. .PP .PD 0 .IC i b .TP 15 .PD .IC i Move backward .I i lines, with a default of one screenful. If .I i is more than the screen size, only the final screenful will be written. .PP .PD 0 .CR q ", "Q ", .CR :q ", " :Q ", " .TP 15 .CR ZZ .PD Exit from .CR more . .PP .PD 0 .C = .PP .C :f .TP 15 .PD .C Write the name of the file currently being examined, the number relative to the total number of files there are to examine, the current line number, the current byte number, and the total bytes to write and what percentage of the file precedes the current position. All of these items reference the first byte of the line after the last line written. .TP .C v Invoke an editor to edit the current file being examined. The name of the editor is taken from the environment variable .CR EDITOR , or default to .CR vi . If .C EDITOR represents either .C vi or .CR ex , the editor is invoked with options such that the current editor line is the physical line corresponding to the current position in .C more at the time of the invocation. .PP .IP \| 15 When the editor exits, .C more resumes on the current file by rewriting the screen with the current line as the current position. .TP .C h Display a description of all the .C more commands. .TP .IC i\| / [ ! ] expression Search forward in the file for the .IR i -th line containing the regular expression .I expression. The default value for .I i is 1. The search starts at the line following the current position. If the search is successful, the screen is modified so that the searched-for line is in the current position. The null regular expression .RC ( / ) repeats the search using the previous regular expression. If the character .C ! is included, the lines for searching are those that do not contain .I expression. .PP .IP \| 15 If there are less than .I i occurrences of .I expression, and the input is a file rather than a pipe, then the position in the file remains unchanged. .PP .IP \| 15 The user's erase and kill characters can be used to edit the regular expression. Erasing back past the first column cancels the search command. .TP .IC i\| ? [ ! ] expression Same as .CR / , but searches backward in the file for the .I i th line containing the regular expression .I expression. .TP .IC i n Repeat the previous search for the .IR i -th line (default 1) containing the last .I expression (or not containing the last .I expression, if the previous search was .C /! or .CR ?! ). .TP .IC i N Repeat the search for the opposite direction of the previous search for the .IR i -th line (default 1) containing the last .I expression .TP .C \'\' (single quotes) Return to the position from which the last large movement command was executed ( "large movement" is defined as any movement of more than a screenful of lines). If no such movements have been made, return to the beginning of the file. .TP .CI ! command Invoke a shell with .IR command . The characters .C % and .C ! in .I command are replaced with the current file name and the previous shell command, respectively. If there is no current file name, .C % is not expanded. The sequences .C \e% and .C \e! are replaced by .C % and .C ! respectively. .PP .PD 0 .CI :e \0[file] .TP 15 .PD .CI E \0[file] Examine a new file. If the .I file argument is not specified, the "current" file (see the .C :n and .C :p commands) from the list of files in the command line is re-examined. The filename is subjected to the process of shell word expansions. If .I file is a .C # (number sign) character, the previously examined file is re-examined. .TP .IC i :n Examine the next file. If .I i is specified, examines the .IR i -th next file specified in the command line. .TP .IC i :p Examine the previous file. If a number .I i is specified, examines the .IR i -th previous file specified in the command line. .TP .CI :t \0tagstring Go to the supplied .I tagstring and scroll or rewrite the screen with that line in the current position. .TP .CI m \0letter Mark the current position with the specified letter, where .I letter represents the name of one of the lower-case letters of the portable character set. .TP .CI ' \0letter Return to the position that was previously marked with the specified .I letter, making that line the current position. .PP .PD 0 .C r .TP 15 .PD .C Refresh the screen. .TP .C R Refresh the screen, discarding any buffered input. .RE .PP The commands take effect immediately; i.e., it is not necessary to press .CR . Up to the time when the command character itself is given, the line-kill character can be used to cancel the numerical argument being formed. .PP If the standard output is not a teletype, .C more is equivalent to .IR cat (1). .PP .C more supports the .C SIGWINCH signal, and redraws the screen in response to window size changes. .SH EXTERNAL INFLUENCES .SS Environment Variables .TP 15 .C COLUMNS Overrides the system-selected horizontal screen size. .TP .C EDITOR Used by the .C v command to select an editor. .TP .C LANG Provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C more will behave as if all internationalization variables are set to "C". See .IR environ (5). .TP .C LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .TP .C LC_CTYPE Determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .TP .C LC_MESSAGES Determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .TP .C NLSPATH Determines the location of message catalogues for the processing of .C LC_MESSAGES. .TP .C LINES Overrides the system-selected vertical screen size, used as the number of lines in a screenful. The .C -n option takes precedence over the .C LINES variable for determining the number of lines in a screenful. .TP .C MORE Determines a string containing options, preceded with hyphens and blank-character-separated as on the command line. Any command-line options are processed after those in the .C MORE variable. The .C MORE variable takes precedence over the .C TERM and .C LINES variables for determining the number of lines in a screenful. .TP .C TERM Determines the name of the terminal type. .RE .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES To view a simple file, use: .IP .CI more " filename" .PP To preview .I nroff output, use a command resembling: .IP .C "nroff -mm +2 doc.n | more -s" .PP If the file contains tables, use: .IP .CI "tbl " file " | nroff -mm | col | more -s" .PP To display file .C stuff in a fifteen line-window and convert multiple adjacent blank lines into a single blank line: .IP .CI " more -s -n 15 " stuff .PP To examine each file with its last screenful: .IP .CI " more -p G " "file1 file2" .PP To examine each file starting with line 100 in the current position (third line, so line 98 is the first line written): .IP .CI " more -p 100g " "file1 file2" .PP To examine the file that contains the tagstring .I tag with line 30 in the current position: .IP .C more -t tag -p 30g .PD .SH WARNINGS Standard error, file descriptor 2, is normally used for input during interactive use and should not be redirected (see Input/Output section in the manpage of the shell in use). .SH FILES .TP 30 .C /usr/share/lib/terminfo/?/* compiled terminal capability data base .PD .SH AUTHOR .C more was developed by Mark Nudleman, University of California, Berkeley, OSF, and HP. .SH SEE ALSO csh(1), man(1), pg(1), sh(1), term(4), terminfo(4), environ(5), lang(5), regexp(5). .SH STANDARDS CONFORMANCE .CR more ": XPG4" .\" index@\f2more\f1 \- file perusal filter for crt viewing@@@\f3more(1)\f1 .\" index@\f2page\f1 \- file perusal filter for crt viewing@@@\f3more(1)\f1 .\" index@display file on \s-1CRT\s+1 terminals@@@\f3more(1)\f1 .\" index@files: display file on \s-1CRT\s+1 terminals@@@\f3more(1)\f1 .\" index@file perusal filter for \s-1CRT\s+1 terminals@@@\f3more(1)\f1 .\" index@peruse file on \s-1CRT\s+1 terminals@@@\f3more(1)\f1 .\" index@\s-1CRT\s+1 terminals, peruse file on@@@\f3more(1)\f1 .\" index@terminals, \s-1CRT\s+1, peruse file on@@@\f3more(1)\f1 .\" index@soft-copy terminals, peruse file on@@@\f3more(1)\f1 .\" .\" toc@\f3more(1)\f1:\0\0\f2more\f1, \f2page\f1@@@file perusal filter for crt viewing .\" toc@\f2page\f1: file perusal filter for crt viewing@@@see \f3more(1)\f1 .\" .\" links@more.1 page.1 .\" $Header: passwd.1,v 78.3 96/02/27 12:08:55 ssa Exp $ .TA p .TH passwd 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME passwd \- change login password .SH SYNOPSIS .CR passwd .RC \|[ -F \0\f2file\f1]\| .RI \|[ name ]\| .PP .CR passwd .RC [ -f ] .RC [ -n .IR min\| ] .RC [ -x .IR max\| ] .RC [ -w .IR warn\| ] .IR name\| .SH DESCRIPTION The .CR passwd command installs or changes the password associated with the login .IR name . If .IR name is omitted, it defaults to the invoking user's login name. .CR passwd uses .IR getlogin (3C) to determine the invoking user's name. .PP The default password file is .CR /etc/passwd . You can use the .CR -F option to choose an alternate password file. You must have read and write permission for the alternate file. .PP Ordinary users can change only the password corresponding to their own login .IR name . If there is an old password, .CR passwd prompts for it. Then it prompts for the new password twice. The first time the new password is entered, .CR passwd checks to see if the old password has "aged" sufficiently. If "aging" is insufficient, the new password is rejected and .CR passwd terminates; see .IR passwd (4). .PP Assuming "aging" is sufficient, a check is made to ensure that the new password meets construction requirements. When the new password is entered a second time, the two copies of the new password are compared. If the two copies differ, .CR passwd repeats the cycle of prompting for the new password, at most twice. .PP .PP Passwords must be constructed to meet the following requirements: .RS .TP 3 \(bu A password must have at least six characters. Only the first eight characters are significant in an untrusted system. .TP \(bu Characters must be from the 7-bit .SM USASCII character set; letters from the English alphabet. .TP \(bu A password must contain at least two uppercase and/or lowercase letters and at least one numeric or special character. .TP \(bu A password must differ from the user's login .IR name and any reverse or circular shift of that login .IR name . For comparison purposes, an uppercase letter and its corresponding lowercase equivalent are treated as identical. .TP \(bu A new password must differ from the old one by at least three characters (one character in a trusted system). For comparison purposes, an uppercase letter and its corresponding lowercase equivalent are treated as identical. .RE .PP A superuser is a user whose effective user .SM ID is zero; see .IR id (1), and .IR su (1). Superusers can change any password and are not forced to comply with password aging. In an untrusted system superusers are not forced to comply with password construction requirements, and .CR passwd does not prompt a superuser for the old password. A superuser can create a null password by entering a carriage return in response to the prompt for a new password. .PP A superuser can also modify password aging characteristics associated with the user .IR name using the following options: .TP 10 .C -f This option forces the user to enter a new password on the next login. .TP .CI -n " min" This option determines the minimum number of days, .IR min, that must transpire before the user can change the password. .TP .CI -w " warn" This option specifies the number of days, .IR warn, prior to the password expiring when the user will be notified that the password needs to be changed. This option is only enabled when your system has been converted to a trusted, secure system. Refer to the .I HP-UX System Administration Tasks Manual on how to convert your HP-UX to a trusted, secure system. .TP .CI -x " max" This option determines the maximum number of days, .IR max, a password can remain unchanged. The user must enter another password after that number of days has transpired, known as the password .I "expiration time". .PP The .IR min and .IR max arguments are each represented in units of days. These arguments will be rounded up to the nearest week on a non-trusted HP-UX system. If your system is then converted to a trusted system, the number of days will be based on those weeks. If you only supply one of the two arguments, .CR passwd checks to see if the other one already exists. If it does not exist, then it defaults it to zero for you. .PP .SH NETWORKING FEATURES .C passwd can use the HP-UX Integrated Login Library, if configured. For a complete description of using and administering HP-UX Integrated Login, see .IR auth (5) and .IR auth.admin (1M). .PP HP-UX Integrated Login typically uses the Distributed Computing Environment (DCE) for its user registry. For a complete description of the DCE user registry and its relationship with HP-UX Integrated Login, see .IR auth.dce (5). .PP .SH SECURITY FEATURES This section applies only to a trusted system. It describes additional capabilities and restrictions. .PP Additional restrictions which apply to superusers include: prompted for supersuer passwords, null passwords must have been allowed explicitly, all other password construction requirements, and prompted for "user number", if it exists. .PP When you use .C passwd on a trusted system, the system prompts for the existing password (if any), and begins a password solicitation dialog that depends on the type of password generation the system administrator has enabled on your account. There are four possible options for password generation: .RS .TP 25 .B \(bu random syllables: A pronounceable password made up of meaningless syllables. .TP .B \(bu random characters: An unpronounceable password made up of random characters from the character set. .TP .B \(bu random letters: An unpronounceable password made up of random letters from the alphabet. .TP .B \(bu user-supplied: A user-supplied password, subject to length and triviality restrictions. .RE .PP Passwords can be longer than eight characters. The system administrator specifies a maximum password length guideline for the 3 system generated options. The minimum password length depends on several parameters that the system administrator sets in the authentication databases. The system warns you if you choose a password that is too short or too long. .PP The system requires a .I "minimum time" to elapse before you can change a password. This prevents you from reusing an old password too soon. .PP A password expires after a period of time known as the .IR "expiration time" . The system warns you when the expiration time is drawing near. .PP A password dies after a period of time known as the .IR "password lifetime" . After the lifetime passes, the account is locked until the system administrator re-enables it. After unlocking, you must change your password again before you can use your account. .PP The system administrator can individually enable accounts with no passwords. If your account can be run without a password, and if you are allowed to pick your password, you can type carriage-return at the .CR "New\ password:" prompt. .PP You can change your own password if the system administrator has enabled any of the password generation options for your account. .SH EXAMPLES Change the password expiration date of .C user to 42 days: .IP .C "passwd -x 42 user" .PP Change the minimum time between password changes of .C user1 to 7 days: .IP .C "passwd -n 7 user1" .PP Force .C user2 to establish a new password on the next login that will expire in 70 days and prohibit the user from changing the password until 7 days have transpired: .IP .C "passwd -f -x 70 -n 7 user2" .SH EXTERNAL INFLUENCES .SS International Code Set Support Characters from single-byte character code sets are supported in passwords. .SH FILES .TP 30 .PD 0 .CR /etc/passwd Standard password file used by HP-UX. .TP .CR /tcb/files/auth/*/* Protected password database used when system is converted to trusted system. .PD .SH SEE ALSO auth(5), auth.adm(1M), auth.dce(5), chfn(1), id(1), login(1), su(1), crypt(3C), getlogin(3C), passwd(4). .SH STANDARDS CONFORMANCE .CR passwd ": SVID2, SVID3, XPG2" .\" .\" index@\f4passwd\f1 \- change login password@@@\f3passwd(1)\f1 .\" index@\f1change login password@@@\f3passwd(1)\f1 .\" index@\f1login password, change@@@\f3passwd(1)\f1 .\" index@\f1password, change login@@@\f3passwd(1)\f1 .\" index@\f1password generation@@@\f3passwd(1)\f1 .\" index@\f1password expiration@@@\f3passwd(1)\f1 .\" index@\f1system administrator@@@\f3passwd(1)\f1 .\" index@\f1administrator, system@@@\f3passwd(1)\f1 .\" index@\f1superuser@@@\f3passwd(1)\f1 .\" .\" toc@\f3passwd(1)\f1:\0\0\f4passwd\f1@@@change login password .\" .\" $Header: paste.1,v 76.1 95/08/23 17:33:11 ssa Exp $ .TA p .TH paste 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME paste \- merge same lines of several files or subsequent lines of one file .SH SYNOPSIS .C paste .IR "file1 file2" \0... .br .C paste -d .IR "list file1 file2" \0... .br .C paste -s .RC [ -d .IR list\| ] .IR "file1 file2" \0... .SH DESCRIPTION In the first two forms, .C paste concatenates corresponding lines of the given input files .IR file1 , .IR file2 , etc. It treats each file as a column or columns in a table and pastes them together horizontally (parallel merging). In other words, it is the horizontal counterpart of .IR cat (1) which concatenates vertically; i.e., one file after the other. In the .C -s option form above, .C paste replaces the function of an older command with the same name by combining subsequent lines of the input file (serial merging). In all cases, lines are glued together with the .I tab character, or with characters from an optionally specified .IR list . Output is to standard output, so .C paste can be used as the start of a pipe, or as a filter if .C - is used instead of a file name. .SS .C paste recognizes the following options and command-line arguments: .RS .TP 10 .C -d Without this option, the new-line characters of all but the last file (or last line in case of the .C -s option) are replaced by a .I tab character. This option allows replacing the .I tab character by one or more alternate characters (see below). .TP .I list One or more characters immediately following .C -d replace the default .I tab as the line concatenation character. The list is used circularly; i.e., when exhausted, it is reused. In parallel merging (that is, no .C -s option), the lines from the last file are always terminated with a new-line character, not from the .IR list . The list can contain the special escape sequences: .C \en (new-line), .C \et (tab), .C \e\e (backslash), and .C \e0 (empty string, not a null character). Quoting may be necessary if characters have special meaning to the shell. (For example, to get one backslash, use .C -d"\e\e\e\e"\c ). .TP .C -s Merge subsequent lines rather than one from each input file. Use .I tab for concatenation, unless a .I list is specified with the .C -d option. Regardless of the .IR list , the very last character of the file is forced to be a new-line. .TP .C - Can be used in place of any file name to read a line from the standard input (there is no prompting). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the locale for the interpretation of text as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .CR LC_CTYPE or .CR LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .CR paste behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE These commands return the following values upon completion: .RS .TP 5 .C 0 Completed successfully. .TP .C >0 An error occurred. .SH EXAMPLES .PP List directory in one column: .IP .C ls | paste -d" """ - .PP List directory in four columns .IP .C ls | paste "- - - -" .PP Combine pairs of lines into lines .IP .C paste -s -d"\et\en" file .SS Notes .CR "pr -t -m" ... works similarly, but creates extra blanks, tabs and new-lines for a nice page layout. .SH DIAGNOSTICS .TP 25 .C too many files Except for the .C -s option, no more than .C OPEN_MAX \(mi 3 input files can be specified (see .IR limits (5)). .SH AUTHOR .CR paste was developed by OSF and HP. .SH SEE ALSO cut(1), grep(1), pr(1). .SH STANDARDS CONFORMANCE .CR paste ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4paste\f1 \- merge corresponding lines of several files or subsequent lines of one file@@@\f3paste(1)\f1 .\" index@combine corresponding lines of several files or subsequent lines of one file@@@\f3paste(1)\f1 .\" index@join corresponding lines of several files or subsequent lines of one file@@@\f3paste(1)\f1 .\" index@merge corresponding lines of several files or subsequent lines of one file@@@\f3paste(1)\f1 .\" index@files: merge corresponding lines of several files or subsequent lines of one file@@@\f3paste(1)\f1 .\" index@lines, merge corresponding lines of several files or subsequent lines of one file@@@\f3paste(1)\f1 .\" .\" toc@\f3paste(1)\f1:\0\0\f4paste\f1@@@merge same lines of several files or subsequent lines of one file .\" $Header: patch.1,v 76.3 95/11/02 14:09:23 ssa Exp $ .de Sh .br .ne 5 .PP \f3\\$1\f1 .PP .. .de Sp .if t .sp .5v .if n .sp .. ''' ''' Set up \*(-- to give an unbreakable dash; ''' string Tr holds user defined translation string. ''' Bell System Logo is used as a dummy character. ''' .ie n \{\ .tr \(bs-\*(Tr .ds -- \(bs- .if (\n(.H=4u)&(1m=24u) .ds -- \(bs\h'-12u'\(bs\h'-12u'-\" diablo 10 pitch .if (\n(.H=4u)&(1m=20u) .ds -- \(bs\h'-12u'\(bs\h'-8u'-\" diablo 12 pitch .ds L" "" .ds R" "" .ds L' ' .ds R' ' 'br\} .el\{\ .ds -- \(em\| .tr \*(Tr .ds L" `` .ds R" '' .ds L' ` .ds R' ' 'br\} .TA p .TH patch 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME patch - a program for applying a diff file to an original .SH SYNOPSIS .B For non-XPG4 version .sp .C patch .RI [ options ] .I orig patchfile .RC [ + [ .IR options ] .IR orig ] .sp but usually just .sp .C patch .CI < patchfile .sp .B For XPG4 version .sp .CR patch .RC [ \-blNR ] .RC [ \-c|\-e|\-n ] .RC [ \-d .IR dir ] .RC [ \-D .IR define ] .RC [ \-i .IR patchfile ] .PD 0 .ifn .IP .RC [ \-o .IR outfile ] .RC [ \-p .IR num ] .ift .IP .RC [ \-r .IR rejectfile ] .RI [ file ] .PD .SH DESCRIPTION .I Patch will take a patch file containing any of the three forms of difference listing produced by the .I diff program (normal, context or in the style of ed) and apply those differences to an original file, producing a patched version. By default, the patched version is put in place of the original, with the original file backed up to the same name with the extension \*(L".orig\*(R", or as specified by the .CR -b switch. Note that functionality of this option varies for XPG4 version. You may also specify where you want the output to go with a .CR -o switch. If .I patchfile is omitted, or is a hyphen, the patch will be read from standard input. For XPG4 version, patchfile has to be specified as argument to .CR -i switch. If this option is omitted or a hyphen is specified as argument, the patch will read from standard input. .PP Upon startup, patch will attempt to determine the type of the diff listing, unless over-ruled by a .CR -c , .CR -e , or .CR -n switch. Context diffs and normal diffs are applied by the .I patch program itself, while ed diffs are simply fed to the .I ed editor via a pipe. .PP .I patch will try to skip any leading garbage, apply the diff, and then skip any trailing garbage. Thus you could feed an article or message containing a diff listing to .IR patch , and it should work. If the entire diff is indented by a consistent amount, this will be taken into account. .PP With context diffs, and to a lesser extent with normal diffs, .I patch can detect when the line numbers mentioned in the patch are incorrect, and will attempt to find the correct place to apply each hunk of the patch. As a first guess, it takes the line number mentioned for the hunk, plus or minus any offset used in applying the previous hunk. If that is not the correct place, .I patch will scan both forwards and backwards for a set of lines matching the context given in the hunk. First .I patch looks for a place where all lines of the context match. If no such place is found, and it's a context diff, and the maximum fuzz factor is set to 1 or more, then another scan takes place ignoring the first and last line of context. If that fails, and the maximum fuzz factor is set to 2 or more, the first two and last two lines of context are ignored, and another scan is made. (The default maximum fuzz factor is 2.) Note that for XPG4 version maximum fuzz factor can not be specified as an option and the default maximum fuzz factor is used. If .I patch cannot find a place to install that hunk of the patch, it will put the hunk out to a reject file, which normally is the name of the output file plus \*(L".rej\*(R". (Note that the rejected hunk will come out in context diff form whether the input patch was a context diff or a normal diff. If the input was a normal diff, many of the contexts will simply be null.) The line numbers on the hunks in the reject file may be different than in the patch file: they reflect the approximate location patch thinks the failed hunks belong in the new file rather than the old one. .PP As each hunk is completed, you will be told whether the hunk succeeded or failed, and which line (in the new file) .I patch thought the hunk should go on. If this is different from the line number specified in the diff you will be told the offset. A single large offset MAY be an indication that a hunk was installed in the wrong place. You will also be told if a fuzz factor was used to make the match, in which case you should also be slightly suspicious. Note that XPG4 version does not support verbose option. So, most of the diagnostic messages are not printed for this version. However user queries will always be displayed. .PP If no original file is specified on the command line, .I patch will try to figure out from the leading garbage what the name of the file to edit is. In the header of a context diff, the filename is found from lines beginning with \*(L"***\*(R" or \*(L"---\*(R", with the shortest name of an existing file winning. Only context diffs have lines like that, but if there is an \*(L"Index:\*(R" line in the leading garbage, .I patch will try to use the filename from that line. The context diff header takes precedence over an Index line. If no filename can be intuited from the leading garbage, you will be asked for the name of the file to patch. .PP (If the original file cannot be found, but a suitable SCCS or RCS file is handy, .I patch will attempt to get or check out the file.) .PP Additionally, if the leading garbage contains a \*(L"Prereq: \*(R" line, .I patch will take the first word from the prerequisites line (normally a version number) and check the input file to see if that word can be found. If not, .I patch will ask for confirmation before proceeding. .PP The upshot of all this is that you should be able to say, while in a news interface, the following: .IP .C | patch -d /usr/src/local/blurfl .PP and patch a file in the blurfl directory directly from the article containing the patch. .PP If the patch file contains more than one patch, .I patch will try to apply each of them as if they came from separate patch files. This means, among other things, that it is assumed that the name of the file to patch must be determined for each diff listing, and that the garbage before each diff listing will be examined for interesting things such as filenames and revision level, as mentioned previously. You can give switches (and another original file name) for the second and subsequent patches by separating the corresponding argument lists by a \*(L'+\*(R'. (The argument list for a second or subsequent patch may not specify a new patch file, however.) .PP With XPG4 version, processing of multiple patches varies considerably. You can not specify different options for different patches. Options remain same for all the patches. This also affects the contents of output file specified with .B -o option. See the description of this option for more details. .PP .I Patch recognizes the following switches: .TP 5 .C \-b causes the next argument to be interpreted as the backup extension, to be used in place of \*(L".orig\*(R". (For XPG4 version this option varies. With this option no argument is required and the option only enables the backup process. Always default extension is used.) .TP 5 .C \-c forces .I patch to interpret the patch file as a context diff. .TP 5 .C \-d causes .I patch to interpret the next argument as a directory, and cd to it before doing anything else. .TP 5 .C \-D causes .I patch to use the "#ifdef...#endif" construct to mark changes. The argument following will be used as the differentiating symbol. Note that, unlike the C compiler, there must be a space between the .C \-D and the argument. (For XPG4 version this option varies. With this version "#ifndef" constructor is not used.) .TP 5 .C \-e forces .I patch to interpret the patch file as an ed script. .TP 5 .C \-f forces .I patch to assume that the user knows exactly what he or she is doing, and to not ask any questions. It does not suppress commentary, however. Use .C \-s for that. (This option is not supported by XPG4 version.) .TP 5 .C \-F \f2number\f1 sets the maximum fuzz factor. This switch only applied to context diffs, and causes .I patch to ignore up to that many lines in looking for places to install a hunk. Note that a larger fuzz factor increases the odds of a faulty patch. The default fuzz factor is 2, and it may not be set to more than the number of lines of context in the context diff, ordinarily 3. (This option is not supported by XPG4 version.) .TP 5 .C \-i This option is supported only by XPG4 version. It causes next argument to be interpreted as the patch file name. .TP 5 .C \-l causes the pattern matching to be done loosely, in case the tabs and spaces have been munged in your input file. Any sequence of whitespace in the pattern line will match any sequence in the input file. Normal characters must still match exactly. Each line of the context must still match a line in the input file. .TP 5 .C \-n forces .I patch to interpret the patch file as a normal diff. .TP 5 .C \-N causes .I patch to ignore patches that it thinks are reversed or already applied. See also .CR \-R . .TP 5 .C \-o causes the next argument to be interpreted as the output file name. There are some added features for the XPG4 version. Multiple patches for a single file will be applied to the intermediate versions of the file created by any previous patches, and will result in multiple,concatenated versions of the file being written to output file. .TP 5 .C \-p \f2number\f1 sets the pathname strip count, which controls how pathnames found in the patch file are treated, in case the you keep your files in a different directory than the person who sent out the patch. The strip count specifies how many backslashes are to be stripped from the front of the pathname. (Any intervening directory names also go away.) For example, supposing the filename in the patch file was .IP .C " /u/howard/src/blurfl/blurfl.c" .IP setting .CR \-p or .CR \-p0 gives the entire pathname unmodified, .CR \-p1 gives .IP .C " u/howard/src/blurfl/blurfl.c" .IP without the leading slash, .CR \-p4 gives .IP .C " blurfl/blurfl.c" .IP and not specifying .CR \-p at all just gives you "blurfl.c". Whatever you end up with is looked for either in the current directory, or the directory specified by the .CR \-d switch. .TP 5 .C \-r causes the next argument to be interpreted as the reject file name. .TP 5 .C \-R tells .I patch that this patch was created with the old and new files swapped. (Yes, I'm afraid that does happen occasionally, human nature being what it is.) .I Patch will attempt to swap each hunk around before applying it. Rejects will come out in the swapped format. The .CR \-R switch will not work with ed diff scripts because there is too little information to reconstruct the reverse operation. .Sp If the first hunk of a patch fails, .I patch will reverse the hunk to see if it can be applied that way. If it can, you will be asked if you want to have the .CR \-R switch set. If it can't, the patch will continue to be applied normally. (Note: this method cannot detect a reversed patch if it is a normal diff and if the first command is an append (i.e. it should have been a delete) since appends always succeed, due to the fact that a null context will match anywhere. Luckily, most patches add or change lines rather than delete them, so most reversed normal diffs will begin with a delete, which will fail, triggering the heuristic.) .TP 5 .C \-s makes .I patch do its work silently, unless an error occurs. (This option is not supported by XPG4 version.) .TP 5 .C \-S causes .I patch to ignore this patch from the patch file, but continue on looking for the next patch in the file. Thus .IP .C "patch -S + -S + 1 An error occurred. .PD .PP For non-XPG4 version exit values vary as follows: .TP 4 .C 0 Successful completion or one or more lines were written to a reject file. .PD 0 .TP .C 1 An error occurred. .PD .SH DIAGNOSTICS Too many to list here, but generally indicative that .I patch couldn't parse your patch file. .PP The message \*(L"Hmm...\*(R" indicates that there is unprocessed text in the patch file and that .I patch is attempting to intuit whether there is a patch in that text and, if so, what kind of patch it is. .PP Note that only few diagnostic messages are printed for XPG4 version, since it does not support verbose option. .SH WARNINGS .I Patch cannot tell if the line numbers are off in an ed script, and can only detect bad line numbers in a normal diff when it finds a \*(L"change\*(R" or a \*(L"delete\*(R" command. A context diff using fuzz factor 3 may have the same problem. Until a suitable interactive interface is added, you should probably do a context diff in these cases to see if the changes made sense. Of course, compiling without errors is a pretty good indication that the patch worked, but not always. .PP .I Patch usually produces the correct results, even when it has to do a lot of guessing. However, the results are guaranteed to be correct only when the patch is applied to exactly the same version of the file that the patch was generated from. .SH FILES .C /var/tmp/patch* .SH SEE ALSO diff(1), ed(1). .SH NOTES FOR PATCH SENDERS There are several things you should bear in mind if you are going to be sending out patches. First, you can save people a lot of grief by keeping a patchlevel.h file which is patched to increment the patch level as the first diff in the patch file you send out. If you put a Prereq: line in with the patch, it won't let them apply patches out of order without some warning. Second, make sure you've specified the filenames right, either in a context diff header, or with an Index: line. If you are patching something in a subdirectory, be sure to tell the patch user to specify a .CR \-p switch as needed. Third, you can create a file by sending out a diff that compares a null file to the file you want to create. This will only work if the file you want to create doesn't exist already in the target directory. Fourth, take care not to send out reversed patches, since it makes people wonder whether they already applied the patch. Fifth, while you may be able to get away with putting 582 diff listings into one file, it is probably wiser to group related patches into separate files in case something goes haywire. .SH BUGS Could be smarter about partial matches, excessively \&deviant offsets and swapped code, but that would take an extra pass. .PP If code has been duplicated (for instance with #ifdef OLDCODE ... #else ... #endif), .I patch is incapable of patching both versions, and, if it works at all, will likely patch the wrong one, and tell you that it succeeded to boot. .PP If you apply a patch you've already applied, .I patch will think it is a reversed patch, and offer to un-apply the patch. This could be construed as a feature. .PP One more thing to be noted with respect to XPG4 version of .I patch. If you are using multiple patches for different files, group patches that have to be applied to a single file. Otherwise, intermediate versions of the previous patches of a file will not be used for the current patch. .SH STANDARDS CONFORMANCE .CR patch: " XPG4" .\" index@\f4patch()\f1 \- program for applying a diff file to an original@@@\f3patch(1)\f1 .\" index@\f1applying a diff file to an original@@@\f3patch(1)\f1 .\" index@\f1diff file to an original, applying@@@\f3patch(1)\f1 .\" index@\f1original, applying a diff file to@@@\f3patch(1)\f1 .\" .\" toc@\f3patch(1)\f1:\0\0\f4patch()\f1@@@applying a diff file to an original .\" $Header: pathalias.1,v 72.3 93/01/14 11:37:04 ssa Exp $ .TA p .TH pathalias 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pathalias \- electronic address router .SH SYNOPSIS .C pathalias .RC [ -ivcDf ] .RC [ -l .IR host\| ] .RC [ -d .IR link\| ] .RC [ -t .IR link\| ] .RI [ \|files\| ] .SH DESCRIPTION .C pathalias computes the shortest paths and corresponding routes from one host (computer system) to all other known, reachable hosts. .C pathalias reads host-to-host connectivity information on standard input or in the named .IR files , and writes a list of host-route pairs on the standard output. .SS Options .C pathalias recognizes the following options and command-line arguments: .RS .TP 10 .C -i Ignore case: map all host names to lowercase. By default, case is significant. .TP .C -c Print costs. Print the path cost (see below) before each host-route pair. .TP .C -v Verbose. Report some statistics on the standard error output. .TP .C -D Terminal domains. Domain members are terminal. .TP .C -f First hop cost. The printed cost is the cost to the first relay in a path instead of the cost of the path itself; implies (and overrides) the .C -c option. .TP .CI -l \0host Set local host name to .IR host . By default, .C pathalias discovers the local host name in a system-dependent way. .TP .CI -d \0link Declare a dead link, host, or network (see below). If .I link is of the form .CR host1!host2 , the link from host1 to host2 is treated as an extremely high cost (i.e., .CR DEAD ) link. If .I link is a single host name, that host is treated as dead and is used as an intermediate host of last resort on any path. If .I link is a network name, the network requires a gateway. .TP .CI -t \0link Trace input for link, host, or network on the standard error output. The form of .I link is as above. .PP The public domain version of .C pathalias includes two undocumented options that are briefly described in the Special Options section below. .SS Input Format A line beginning with white space continues the preceding line. Anything following .C # on an input line is ignored. .PP A list of host-to-host connections consists of a ``from'' host in column 1, followed by white space, followed by a comma-separated list of ``to' hosts, called .IR links . A link may be preceded or followed by a network character to use in the route. Valid network characters are .C ! (default), \f3@\fP, .CR : , and .CR % . A link (and network character, if present) may be followed by a ``cost'' enclosed in parentheses. Costs can be arbitrary arithmetic expressions involving numbers, parentheses, .CR + , .CR - , .CR * , and .CR / . Negative costs are prohibited. The following symbolic costs are recognized: .RS .PP .TS center tab(;); af4 a l. LOCAL;25;(local-area network connection) DEDICATED;100;(high speed dedicated link) DIRECT;200;(toll-free call) DEMAND;300;(long-distance call) HOURLY;500;(hourly poll) EVENING;2000;(time restricted call) DAILY;5000;(daily poll, also called \s-1POLLED\s0) WEEKLY;30000;(irregular poll) .TE .RE .PP In addition, .C DEAD is a very large number (effectively infinite), and .C HIGH and .C LOW are \(mi5 and +5 respectively, for baud-rate or quality bonuses/penalties, and .C FAST is -80, for adjusting costs of links that use high-speed (9.6 Kbaud or more) modems. These symbolic costs represent an imperfect measure of bandwidth, monetary cost, and frequency of connections. For most mail traffic, it is important to minimize the number of hosts in a route, thus, .IR e.g. , .C HOURLY is far greater than .C DAILY divided by 24. If no cost is given, a default of 4000 is used. .PP For the most part, arithmetic expressions that mix symbolic constants other than .CR HIGH , .CR LOW , and .C FAST make no sense. For example, if a host calls a local neighbor whenever there is work, and additionally polls every evening, the cost is .C DIRECT, .I not .CR DIRECT+EVENING . .PP Some examples: .nf .IP .C "down princeton!(DEDICATED), tilt," .ift .ft 4 .ifn .ft 3 .ps +1 %thrash(LOCAL) princeton topaz!(DEMAND+LOW) topaz @rutgers(LOCAL+1) .ft .ps .fi .PP If a link is encountered more than once, the least-cost occurrence dictates the cost and network character. Links are treated as bidirectional but asymmetric: for each link declared in the input, a .C DEAD reverse link is assumed. .PP If the ``to'' host in a link is surrounded by angle brackets, the link is considered .IR terminal , and further links beyond this one are heavily penalized. For example, with input .nf .IP .C "seismo (10), research(100), ihnp4(10)" .C "research allegra(10)" .C "ihnp4 allegra(50)" .fi .PP the path from .C seismo to .C research is direct, but the path from .C seismo to .C allegra uses .C ihnp4 as a relay; not .CR research . .PP The set of names by which a host is known by its neighbors is called its .IR aliases . Aliases are declared as follows: .IP .IC name = alias , \0alias\0... .RE .PP The name used in the route to or through aliased hosts is the name by which the host is known to its predecessor in the route. .PP Fully connected networks, such as the .SM ARPANET or a local-area network, are declared as follows: .PP .RS .CI net\0=\0{ "host, host, ..." } .RE .PP The host-list can be preceded or followed by a routing character .RC ( ! by default), and can be followed by a cost (4000 by default). The network name is optional; if not given, .C pathalias creates one. .nf .IP .C "etherhosts = {rahway, milan, joliet}!(LOCAL)" .ift .ft 4 .ifn .ft 3 .ps +1 ringhosts = @{gimli, alida, almo}(DEDICATED) = {etherhosts, ringhosts}(0) .ft .ps .fi .PP The routing character used in a route to a network member is the one encountered when ``entering'' the network. See also the sections on .I gateways and .IR domains . .PP Connection data can be given while hiding host names by declaring .IP .CI private\0{ "host, host, ..." } .PP .C pathalias does not generate routes for private hosts, but can produce routes through them. The scope of a private declaration extends from the declaration to the end of the input file in which it appears, or to a private declaration with an empty host list, whichever comes first. The latter scope rule offers a way to retain the semantics of private declarations when reading from the standard input. .PP Dead hosts, links, or networks can be presented in the input stream by declaring .IP .CI dead\0{ arg , \0... } .PP where .I arg has the same form as the argument to the .C -d option. .PP To force a specific cost for a link, delete all prior declarations with .IP .CI delete\0{ host1 ! host2 } .PP and declare the link as desired. To delete a host and all its links, use .IP .CI delete\0{ host } .PP Error diagnostics refer to the file in which the error was found. To alter the file name, use .IP .CI file\0{ filename } .PP Fine-tuning is possible by adjusting the weights of all links from a given host, as in .IP .CI adjust\0{ host1 , \0host-2 (LOW), .IC host3 (-1)} .PP If no cost is given, a default of 4000 is used. .PP Input from compressed (and uncompressed) files can be piped into .C pathalias with the following script. .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 for i in $*; do case $i in *.Z) echo "file {`expr $i : '\(.*\).Z'`} zcat $i ;; *) echo "file {$i}" cat $i ;; esac echo "private {}" done .ft .ps .fi .SS Output Format A list of host-route pairs is written to the standard output, where route is a string appropriate for use with .C printf() (see .IR printf (3S)), .IR such as .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 rutgers princeton!topaz!%s@rutgers .ft .ps .fi .RE .PP The .C %s in the route string should be replaced by the user name at the destination host (this task is normally performed by a mailer). .PP Except for .I domains (see below), the name of a network is never used in routes. Thus, in the earlier example, the path from .C rahway to .C milan would be .CR milan!%s , not .CR etherhosts!milan!%s . .SS Gateways A network is represented by a pseudo-host and a set of network members. Links from the members to the network have the weight given in the input, while the cost from the network to the members is zero. If a network is declared dead, the member-to-network links are marked dead, which effectively prohibits access to the network from its members. .PP However, if the input also shows an explicit link from any host to the network, then that host can be used as a gateway (in particular, the gateway need not be a network member). .PP For example, suppose .C CSNET is declared dead on the command line and the input contains .nf .IP .C CSNET = {...} .C "csnet-relay CSNET" .fi .PP Then routes to .C CSNET hosts will use .C csnet-relay as a gateway. .SS Domains A network whose name begins with .C . is called a domain. Domains are presumed to require gateways; i.e., they are .CR DEAD . The route given by a path through a domain is similar to that for a network, but here the domain name is appended to the end of the name of the next host. Subdomains are permitted. For example: .nf .IP .C "harvard .EDU # harvard is gateway to .EDU domain" .C ".EDU = {.BERKELEY, .UMICH}" .C ".BERKELEY = {ernie}" .fi .PP yields .IP .C "ernie ...!harvard!ernie.BERKELEY.EDU!%s" .PP Output is given for the nearest gateway to a domain; e.g., the example above gives .IP .C ".EDU ...!harvard!%s" .PP Output is given for a subdomain if it has a different route than its parent domain, or if all its ancestor domains are private. .PP If the .C -D option is given on the command line, .C pathalias treats a link from a domain to a host member of that domain as terminal. This property extends to host members of subdomains, etc., and discourages routes that use any domain member as a relay. .SS Special Options The public domain version of .C pathalias includes two undocumented options that rewrite named files with intermediate data of limited usage. Here are brief descriptions: .RS .TP 15 .CI -g \0file Dump graph edges into .I file in the form .IC host > host for simple connections and \f2host\f3@\f1\c .I host for network connections (from hosts to networks only). .TP .CI -s \0file Dump shortest path tree into .I file in the form .I host\c [\f3@\fP\c .RI ] host [\c .CR ! ] (\c .IC cost )\c , including both connections from hosts to networks and from networks to hosts. This data may be useful for generating lists of one-way connections. .SH BUGS The .C -i option should be the default. .PP The order of arguments is significant. In particular, .C -i and .C -t should appear early in the command line. .PP .C pathalias can generate hybrid (i.e., ambiguous) routes, which are abhorrent and most certainly should not be given as examples in a manual entry. Experienced mappers largely shun '@' when preparing input; this is historical, but also reflects .SM UUCP\c \&'s simplistic syntax for source routes. .PP Mixed-mode paths are ambiguous because the precedence of @ versus ! is not specified, varies from host to host, and is configurable. They should rarely be used. .PP Multiple @s in routes are prohibited by many mailers. To circumvent this restriction, mailers instead support the ``magic %'' rule, described below. When .C pathalias would otherwise generate a path containing multiple @s, it instead generates a path to which the ``magic %'' rule can be correctly applied. .PP Basically, the ``magic %'' rule for generating paths is ``when constructing a path that would require multiple @s, replace all but the right-most @ with .CR % . .PP When a mailer that supports the ``magic %'' rule receives a message that was routed to it via ..path..@host, it processes the route as follows: .RS .TP 4 1. Remove the trailing "@host" part of the route. .TP 2. Examine the remaining route from right to left, proceeding to the next step when a "!" is seen. If a `%' is seen, change it to `@' and proceed to the next step immediately. .TP 3. Continue processing the message using the modified route. If the modified route contains both `!' and `@' characters, the exact selection of the next host to route the message is governed by the specific precedence of `!' vs. `@' at this host. .RS .PP For example, if a host, .CR jazz.nonesuch.com , received a message with a path .C foo!joe%castle.hrh.gov.uk\c \f3@\fP\c .CR jazz.nonesuch.com , the mailer would convert the path to .C foo!joe\c \f3@\fP\c .CR castle.hrh.gov.uk , and then forward it appropriately. If the host were configured such that `!' were of higher precedence than `@', the message would be forwarded to host .CR foo , which would then deliver the message to .C joe\c \f3@\fP\c .CR castle.hrh.gov.uk . If instead .C jazz.nonesuch.com were configured with `@' as higher in precedence, it would forward the message to host .CR castle.hrh.gov.uk , which would then deliver it to .CR foo!joe . (Clearly, .C pathalias could only correctly generate such a path if it knew the precedence at host .CR jazz.nonesuch.com ; since the database does not contain that information, such paths from .C pathalias should be viewed with suspicion.) .PP The .C -D option suppresses insignificant routes to domain members. This is benign, perhaps even beneficial, but confusing, since the behavior is undocumented and somewhat unpredictable. .SH AUTHOR .C pathalias was developed by Peter Honeyman and Steven M. Bellovin. .SH FILES .TP 38 .C newsgroup comp.mail.maps Likely location of some input files. .SH SEE ALSO P.Honeyman and S.M. Bellovin, .SM .I PATHALIAS .I or .I "The Care and Feeding of Relative Addresses", in .IR "Proc. Summer USENIX Conf." , Atlanta, 1986. .\" .\" index@\f4pathalias\f1 \- electronic address router@@@\f3pathalias(1)\f1 .\" index@electronic address router@@@\f3pathalias(1)\f1 .\" index@address router, electronic@@@\f3pathalias(1)\f1 .\" index@router, electronic address@@@\f3pathalias(1)\f1 .\" index@compute shortest path and route between hosts@@@\f3pathalias(1)\f1 .\" index@shortest path and route between hosts, compute@@@\f3pathalias(1)\f1 .\" index@hosts, compute shortest path and route between@@@\f3pathalias(1)\f1 .\" index@path and route between hosts, compute shortest@@@\f3pathalias(1)\f1 .\" index@route and path between hosts, compute shortest@@@\f3pathalias(1)\f1 .\" .\" toc@\f3pathalias(1)\f1:\0\0\f4pathalias\f1@@@electronic address router .\" .\" fileset_database@pathalias.1 USER-CMDS-MAN .\" $Header: pathchk.1,v 76.2 95/08/07 11:39:55 ssa Exp $ .TA p .TH pathchk 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pathchk \- check path names .SH SYNOPSIS .C pathchk .RC [ -p ] .IR pathname ... .SH DESCRIPTION The .CR pathchk command checks that one or more path names are valid and portable. By default, the .CR pathchk command checks each component of each path name specified by the .I pathname parameter based on the underlying file system. An error message is written for each path name operand that: .RS .TP 3 \(bu is longer than that allowed by the system. .TP \(bu contains any component longer than that allowed by the system. .TP \(bu contains any component in a directory that is not searchable. .TP \(bu contains any character in any component that is not valid in its containing directory. .RE .PP It is not considered an error if one or more components of a path name do not exist, as long as a file matching the path name specified by the .I pathname parameter could be created that does not violate any of the checks above. .PP More extensive portability checks are performed when the .CR -p flag is specified. .SS Options The .CR pathchk command supports the following option: .RS .TP 8 .C -p Performs path name checks based on POSIX portability standards instead of the underlying file system. An error message is written for each path name that: .RS .RS .TP 3 \(bu is longer than .CR _POSIX_PATH_MAX bytes. .TP \(bu contains any component longer than .CR _POSIX_NAME_MAX bytes. .TP \(bu contains any character in any component that is not in the portable file name character set. .RE .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C pathchk behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH RETURN VALUE Upon successful completion, .CR pathchk returns zero; otherwise it returns nonzero to indicate an error. .SH EXAMPLES To check the validity and portability of the .IP .C /users/mary/work/tempfiles .PP path name on your system, use: .IP .C pathchk /users/mary/work/tempfiles .PP To check the validity and portability of the .IP .C /users/mary/temp .PP path name for POSIX standards, use: .IP .C pathchk -p /users/mary/temp .SH STANDARDS CONFORMANCE .CR pathchk ": XPG4, POSIX.2" .\" .\" toc@\f3pathchk(1)\f1:\0\0\f4pathchk\f1@@@check path names\f1 .\" .\" index@\f4pathchk\f1 \- check path names@@@\f3pathchk(1)\f1 .\" index@\f1path names, check@@@\f3pathchk(1)\f1 .\" $Header: pax.1,v 78.1 96/01/22 22:25:25 ssa Exp $ ...\" (c) Copyright 1990, 1991, 1992, 1993 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" OSF/1 1.2 ...\"build rmifdef ...\" ...\" ...\"build rmifdef tbl eqn .TH pax "1" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME .PP pax \- Extracts, writes, and lists archive files .SH SYNOPSIS .PP .SS Listing Member Files of Archived Files .PP .C pax .RC [ -cdnv ] .RC [ -f .IR archive\| ] .RC [ -s .IR replstr\| \0]\ ...\| .RI [ \|pattern \0...\|] .SS Extracting Archive Files .PP .C pax -r .RC [ -cdiknuvy ] .RC [ -f .IR archive\| ] .RC [ -p .IR string\| \0]\ ...\| .RC [ -s .IR replstr\| \0]\ ...\| .RI [ \|pattern \0...\|] .SS Writing Archive Files .PP .C pax -w .RC [ -adituvXy ] .RC [ -b .IR blocking\| ] .RC [ -f .IR archive\| ] .RC [ -s .IR replstr\| \0]\ ...\| .RC [ -x .IR format\| ] .RI [ \|file \0...\|] .SS Copying Files .C pax -r -w .RC [ -diklntuvXy ] .RC [ -p .IR string\| \0]\ ...\| .RC [ -s .IR replstr\| \0]\ ...\| .RI [ \|file \0...\|] .I directory .PP The .C pax command extracts, writes, and lists members of archive files. It also copies files and directory hierarchies. .SH OPTIONS .PP .TP 15 .C -a Appends files to the end of the archive. Certain devices might not support appending. .TP .CI -b \0blocking Specifies the block size for output to be the positive decimal integer of bytes specified by the .I blocking argument. The block size value cannot exceed 32,256. Blocking is automatically determined on input. .IP Do not specify a value for the .I blocking argument larger than 32768. Default blocking when creating archives depends on the archive format. (See the .C -x flag description.) .TP .C -c Matches all file or archive members except those specified by the .I pattern or .I file arguments. .TP .C -d Causes directories being copied or archived, or archived directories being extracted, to match only the directory or archived directory itself and not the contents of the directory or archived directory. .TP .CI -f \0archive Specifies the path of an archive file to be used instead of standard input (when the .C -w flag is not specified) or the standard output (when the .C -w flag is specified but the .C -r flag is not). When specified with the .C -a flag, any files written to the archive are appended to the end of the archive. .TP .C -i Renames files or archives interactively. For each archive member that matches the .I pattern argument or file that matches a .I file argument, a prompt is written to the terminal .IC ( /dev/tty ) that contains the name of a file or archive member. A line is then read from the terminal. If this line is empty, the file or archive member is skipped. If this line consists of a dot, the file or archive member is processed with no modification to its name. Otherwise, its name is replaced with the contents of the line. The .C pax command immediately exits with a nonzero exit status if an End-of-File is encountered when reading a response or if it cannot read or write to the terminal. .TP .C -k Prevents the .C pax command from writing over existing files. .TP .C -l Links files when copying files. When both .C -r and .C -w are specified, hard links are established between the source and destination file hierarchies whenever possible. .TP .C -n Selects the first archive member that matches each .I pattern argument. No more than one archive member is matched for each pattern (although members of type directory will still match the file hierarchy rooted at that file). .TP .CI -p \0string Specifies one or more file characteristics to be retained or discarded on extraction. The .I string argument consists of the characters .CI a , .CI e , .CI m , .CI o , and .CI p . Multiple characteristics can be concatenated within the same string and multiple .C -p flags can be specified. The specification flags have the following meanings: .RS 15 .TP .C a Does not retain file-access times. .TP .C e Retains the user ID, group ID, access permission, access time, and modification time. .TP .C m Does not retain file-modification times. .TP .C o Retains the user ID and the group ID. .TP .C p Retains the access permission. .RE .IP Note that "retain" means that an attribute stored in the archive is given to the extracted file, subject to the permissions of the invoking process; otherwise, the attribute is determined as part of the normal file creation action. .IP If neither the .C e nor the .C o flag is specified, or the user ID and group ID are not retained, the .C pax command does not set the .C S_ISUID and .C S_ISGID bits of the access permission. If the retention of any of these items fails, the .C pax command writes a diagnostic message to standard error. Failure to retain any of the items affects the exit status, but does not cause the extracted file to be deleted. If specification flags are duplicated or conflict with each other, the ones given last take precedence. For example, if .C -p eme is specified, file-modification times are retained. .TP .C -r Reads an archive file from the standard input. .TP .C -s Modifies file-member or archive-member names specified by the .I pattern or .I file arguments according to the substitution expression .IR replstr , using the syntax of the .C ed command. The substitution expression has the following format: .RS 15 .IP .CI -s/ old / new /\c .RC [ gp ] .RE .IP where as in the .C ed command, .I old is a basic regular expression and .I new can contain an .I & (ampersand), .CI \e n .RI ( n is a digit) back references, or subexpression matching. The .I old string can also contain newline characters. .IP Any nonnull character can be used as a delimiter (the .C / (slash) character is the delimiter in the previous format). Multiple .C -s flag expressions can be specified; the expressions are applied in the order specified, terminating with the first successful substitution. The optional trailing .C g character performs as in the .C ed command. The optional trailing .C p character causes successful substitutions to be written to the standard error. File-member or archive-member names that substitute to the empty string are ignored when reading and writing archives. .TP .C -t Causes the access times of the archived files to be the same as they were before being read by the .C pax command. .TP .C -u Ignores files that are older (having a less recent file modification time) than a preexisting file or archive member with the same name. .IP When extracting files ( .C -r flag), an archive member with the same name as a file in the file system is extracted if the archive member is newer than the file. .IP When writing files to an archive file ( .C -w flag), an archive member with the same name as a file in the file system is superseded if the file is newer than the archive member. .IP When copying files to a destination directory ( .C -rw flags), the file in the destination hierarchy is replaced by the file in the source hierarchy or by a link to the file in the source hierarchy if the file in the source hierarchy is newer. .TP .C -v Writes information about the process. If neither the .C -r or .C -w flags are specified, the .C -v flag produces a verbose table of contents that resembles the output of .CR ls \0-l ; otherwise, archive-member pathnames are written to standard error. .TP .C -w Writes files to the standard output in the specified archive format. .TP .CI -x \0format Specifies the output archive format. The .C pax command recognizes the following formats: .RS 15 .TP 15 .C cpio Extended .C cpio interchange format. The default blocking value for this format for character special archive files is 5120. Blocking values from 512 to 32,256 in increments of 512 are supported. .TP .C ustar Extended .C tar interchange format. This is the default output archive format. The default blocking value for this format for character special archive files is 10240. Blocking values from 512 to 32,256 in increments of 512 are supported. .RE .IP Any attempt to append to an archive file in a format different from the existing archive format causes the .C pax command to exit immediately with a nonzero exit status. .TP .C -X When traversing the file hierarchy specified by a pathname, the .C pax command does not descend into directories that have a different device ID. .TP .C -y Prompts interactively for the disposition of each file. Substitutions specified by .C -s flags are performed before you are prompted for disposition. An EOF marker or an input line starting with the character .C q causes .C pax to exit. Otherwise, an input line starting with anything other than .C y causes the file to be ignored. This flag cannot be used in conjunction with the .C -i flag. .RE .SS Option Interaction and Processing Order .PP The flags that operate on the names of files or archive members ( .CR -c , .CR -i , .CR -n , .CR -s , .CR -u , and .CR -v ) interact as follows. .PP When extracting files .RC ( -r flag), archive members are selected, using the modified names, according to the user-specified pattern arguments as modified by the .CR -c , .CR -n , and .CR -u flags. Then, any .C -s and .C -i flags modify, in that order, the names of the selected files. The .C -v flag writes the names resulting from these modifications. .PP When writing files to an archive file .RC ( -w flag), or when copying files, the files are selected according to the user-specified pathnames as modified by the .C -n and .C -u flags. Then, any .C -s and .C -i flags modify, in that order, the names resulting from these modifications. The .C -v flag writes the names resulting from these modifications. .PP If both the .C -u and .C -n flags are specified, the .C pax command does not consider a file selected unless it is newer than the file to which it is compared. .SH DESCRIPTION .PP The .C pax command extracts and writes member files of archive files; writes lists of the member files of archives; and copies directory hierarchies. The .C -r and .C -w flags specify the archive operation performed by the .C pax command. .PP The .I pattern argument specifies a pattern that matches one or more paths of archive members. A .C \e (backslash) character is not recognized in the .I pattern argument and it prevents the subsequent character from having any special meaning. If no .I pattern argument is specified, all members are selected in the archive. .PP If a .I pattern argument is specified, but no archive members are found that match the pattern specified, the .C pax command detects the error, exits with a nonzero exit status, and writes a diagnostic message. .PP The .C pax command can read both .C tar and .C cpio archives. In the case of .CR cpio , this means that .C pax can read ASCII archives (which are created with .CR cpio \0-c ) and binary archives (which are created without the .C -c flag). The supported archive formats are automatically detected on input. .PP .C pax can also write archives that .C tar and .C cpio can read; by default, .C pax writes archives in the .C ustar extended .C tar interchange format. .C pax also writes ASCII .C cpio archives; use the .C -x cpio flag to specify this extended .C cpio output format. .SS Listing Member Files of Archived Files .PP When neither the .C -r nor the .C -w flags are specified, the .C pax command writes the names of the members of the archive file read from the standard input, with pathnames matching the specified patterns, to the standard output. If a named file is a directory, the file hierarchy contained in the directory is also written. You can specify the .C pax command without the .C -r or .C -w flags with the .CR -c , .CR -d , .CR -f , .CR -n , .CR -s , and .C -v flags, and with the .I pattern argument. .PP If neither the .C -r or .C -w flags are included, .C pax lists the contents of the specified archive, one file per line. .C pax lists hard link pathnames as follows: .RS .IC pathname == linkname .RE .C pax lists symbolic link pathnames as follows: .RS .IC pathname -> linkname .RE In both of the preceding cases, .I pathname is the name of the file that is being extracted, and .I linkname is the name of a file that appeared earlier in the archive. .PP If the .C -v flag is specified, the listing of hard link pathnames is output in the .I ls -l command format. .SS "Extracting Archive Files .PP When the .C -r flag is specified, but the .C -w flag is not, the .C pax command extracts the members of an archive file read from the standard input, and with pathnames matching the .I pattern argument if one is specified. If an extracted file is a directory, the file hierarchy contained in the directory is also extracted. The extracted files are created relative to the current file hierarchy. The .C -r flag can be specified with the .CR -c , .CR -d , .CR -f , .CR -n , .CR -s , and .C -v flags, and a .I pattern argument. .PP The access and modification times of the extracted files are the same as the archived files. The access permissions of the extracted files remain as archived unless affected by the user's default file creation mode. The .C S_ISUID and .C S_ISGID bits of the extracted files are cleared. .PP If intermediate directories are necessary to extract an archive member, the .C pax command creates the directories with access permissions set as the bitwise inclusive OR of the values of the .CR S_IRWXU , .CR S_IRWXG , and .CR S_IRWXO options. .PP If the selected archive format supports the specification of linked files (both the .C tar and .C cpio formats do), it is an error if these files cannot be linked when the archive is extracted. .C pax informs you of the error and continues processing. .SS "Writing Archive Files .PP When the .C -w flag is specified and the .C -r flag is not, the .C pax command writes the contents of the files specified by the .I file arguments to the standard output in an archive format. If no .I file arguments are specified, a list of files to copy, one per line, is read from the standard input. When the .I file argument specifies a directory, all of the files contained in the directory are written. The .C -w flag can be specified with the .CR -b , .CR -d , .CR -f , .CR -i , .CR -s , .CR -t , .CR -u , .CR -v , .CR -x , and .C -X flags and with .I file arguments. .PP If .C -w is specified, but no files are specified, standard input is used. If neither .C -f or .C -w are specified, standard input must be an archive file. .SS "Copying Files .PP When both the .C -r and .C -w flags are specified, the .C pax command copies the files specified by the .I file arguments to the destination directory specified by the .I directory argument. If no file arguments are specified, a list of files to copy, one per line, is read from the standard input. If a specified file is a directory, the file hierarchy contained in the directory is also copied. The .C -r and .C -w flags can be specified with the .CR -d , .CR -i , .CR -k , .CR -l , .CR -p , .CR -n , .CR -s , .CR -t , .CR -u , .CR -v , and .C -X flags and with the .I file arguments. A .I directory argument must be specified. .PP Copied files are the same as if they were written to an archive file and subsequently extracted, except that there may be hard links between the original and the copied files. .SH RETURN VALUE The .C pax command returns a value of 0 (zero) if all files were successfully processed; otherwise, .C pax returns a value greater than 0 (zero). .SH EXAMPLES .PP To copy the contents of the current directory to the tape drive, enter: .IP .C "pax -w -f /dev/rmt/0m ." .PP To copy the .C olddir directory hierarchy to .C newdir enter: .IP .C mkdir \0newdir .br .C cd \0olddir .br .C "pax -rw olddir newdir" .PP To read the archive .CR a.pax , with all files rooted in the directory .C /usr in the archive extracted relative to the current directory, enter: .IP .C "pax -r -s ',//*usr//*,,' -f a.pax" .PP All of the preceding examples create archives in .C tar format. .PP The following pairs of commands demonstrate conversions from .C cpio and .C tar to .CR pax . In all cases, the examples show comparable command-line usage rather than identical output formats. The .C -x flag can be specified to the .C pax commands shown here, producing archives to select specific output formats: .IP .C "ls * | cpio -ocv" .br .C pax -wdv * .PP .IP .C "find /mydir -type f -print | cpio -oc" .br .C "find /mydir -type f -print | pax -w" .PP .IP .C cpio -icdum < archive .br .C pax -r < archive .PP .IP .C "(cd /fromdir;find . -print) | cpio -pdlum /todir" .br .C "pax -rwl /fromdir /todir" .PP .IP .C "tar cf archive *" .br .C "pax -w -f archive *" PP .IP .C "tar xfv - < archive" .br .C "pax -rv < archive" .PP .IP .C "(cd /fromdir; tar cf - . ) | (cd /todir; tar xf -)" .br .C "pax -rw /fromdir /todir" .PP .SS Notes When you use the .C -i flag (interactively renames files) on files to which there are hard links, .C pax does .I not create hard links to the renamed files. .SH WARNINGS Because of industry standards and interoperability goals, .CR pax does not support the archival of files larger than 2GB or files that have user/group IDs greater than 60K. Files with user/group IDs greater than 60K are archived and restored under the user/group ID of the current process. .PP .SH AUTHOR .C pax was developed by Mark H. Colburn, OSF, and HP. .SH SEE ALSO ed(1), tar(4). .SH STANDARDS CONFORMANCE .CR pax ": XPG4, POSIX.2" .\" .PP This implementation of pax is based upon a .C POSIX.2 draft specification. HP intends to update pax to meet the final POSIX.2 Standard once it completes, and thus the pax implementation is likely to change in a future release of HP-UX, possibly in ways incompatible with the current implementation. HP recommends using the current implementation only if absolutely necessary. .\" .\" index@\f4pax\f1 \- portable archive exchange@@@\f3pax(1)\f1 .\" index@portable archive exchange@@@\f3pax(1)\f1 .\" index@archive exchange, portable@@@\f3pax(1)\f1 .\" index@exchange, portable archive@@@\f3pax(1)\f1 .\" index@files: read portable archive@@@\f3pax(1)\f1 .\" index@files: write portable archive@@@\f3pax(1)\f1 .\" index@directory: read portable archive@@@\f3pax(1)\f1 .\" index@directory: write portable archive@@@\f3pax(1)\f1 .\" .\" toc@\f3pax(1)\f1:\0\0\f4pax\f1@@@portable archive exchange .\" $Header: pack.1,v 72.4 94/11/14 15:20:30 ssa Exp $ .TA p .TH pack 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pack, pcat, unpack \- compress and expand files .SH SYNOPSIS .C pack .RC [ - ] .RC [ -f ] .IR name \0... .PP .C pcat .IR name \0... .PP .C unpack .IR name \0... .SH DESCRIPTION .C pack attempts to store the specified files in a compressed form. Wherever possible, each input file .I name is replaced by a packed file .IC name .z with the same ownership, modes, and access and modification times. The .C -f option forces packing of .IR name . This is useful for causing an entire directory to be packed even if some of the files do not benefit. If .C pack is successful, .I name is removed. Packed files can be restored to their original form using .C unpack or .CR pcat . .PP .C pack uses Huffman (minimum redundancy) codes on a byte-by-byte basis. If the .C - argument is used, an internal flag is set that causes the number of times each byte is used, its relative frequency, and the code for the byte to be printed on the standard output. Additional occurrences of .C - in place of .I name cause the internal flag to be set and reset. .PP The amount of compression obtained depends on the size of the input file and the character frequency distribution. Because a decoding tree forms the first part of each .C .z file, it is usually not worthwhile to pack files smaller than three blocks unless the character frequency distribution is very skewed such as in printer plots or pictures. .PP Typically, text files are reduced to 60-75% of their original size. Load modules, which use a larger character set and have a more uniform distribution of characters, show little compression, the packed versions being about 90% of the original size. .PP .C pack returns a value that is the number of files that it failed to compress. .PP No packing occurs if: .RS .TP 3 \(bu The file appears to be already packed. .PD 0 .TP \(bu The file name has more than 12 characters and the file system is configured as a short filename system. .TP \(bu The file has links. .TP \(bu The file is a directory. .TP \(bu The file cannot be opened. .TP \(bu The file is empty. .TP \(bu No disk storage blocks will be saved by packing. .TP \(bu A file called .IC name .z already exists. .TP \(bu The .C .z file cannot be created. .TP \(bu An I/O error occurred during processing. .RE .PD .PP On short-filename systems, the last segment of the file name must contain no more than 12 characters to allow space for the appended .C .z extension. Directories cannot be compressed. .PP .C pcat does for packed files what .IR cat (1) does for ordinary files, except that .C pcat cannot be used as a filter. The specified files are unpacked and written to the standard output. Thus to view a packed file named .IC name .z use: .IP .C pcat name.z .PP or simply: .IP .C pcat name .PP To make an unpacked copy (named .IR file ) of a packed file named .IC name .z without destroying .IC name .z\f1) use the command: .IP .C pcat name >file .PP .C pcat returns the number of files it was unable to unpack. Failure may occur if: .RS .TP 3 \(bu The file name (exclusive of the .CR .z ) has more than 12 characters; .PD 0 .TP \(bu The file cannot be opened; .TP \(bu The file does not appear to have been created by .IR pack . .RE .PD .PP .C unpack expands files created by .CR pack . For each file .I name specified in the command, a search is made for a file called .IC name .z (or just .I name if .I name ends in .CR .z ). If this file appears to be a packed file, it is replaced by its expanded version. The new file has the .C .z suffix stripped from its name, and has the same access modes, access and modification dates, and owner as those of the packed file. .PP .C unpack returns a value that is the number of files it was unable to unpack. Failure may occur for the reasons given for .CR pcat , as well as for the following: .RS .TP 3 \(bu A file with the ``unpacked'' name already exists; .PD 0 .TP \(bu The unpacked file cannot be created. .RE .PD .SS "Access Control Lists (ACLs) .C pack retains all entries in a file's access control list when compressing and expanding it (see .IR acl (5)). .SH DEPENDENCIES .SS \s-1NFS\s0 Optional access control list entries of networked files are summarized (as returned in .C st_mode by .CR stat() , but not copied to the new file (see .IR stat (2)). .SH SEE ALSO cat(1), compact(1), compress(1), acl(5). .SH STANDARDS CONFORMANCE .CR pack ": SVID2, SVID3, XPG2, XPG3" .PP .CR pcat ": SVID2, SVID3, XPG2, XPG3" .PP .CR unpack ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4pack\f1 \- compress (pack) files using Huffman code (see \f4compact\f1(1)@@@\f3pack(1)\f1 .\" index@\f4pcat\f1 \- expand (unpack) and cat Huffman coded file (see \f4compact\f1(1)@@@\f3pack(1)\f1 .\" index@\f4unpack\f1 \- expand Huffman coded files created by \f4pack\f1 (see \f4compact\f1(1)@@@\f3pack(1)\f1 .\" .\" toc@\f3pack(1)\f1:\0\0\f4pack\f1, \f4pcat\f1, \f4unpack\f1@@@compress and expand files .\" toc@\f4pcat\f1: compress and expand files@@@see \f3pack(1)\f1 .\" toc@\f4unpack\f1: compress and expand files@@@see \f3pack(1)\f1 .\" .\" links@pack.1 pcat.1 .\" links@pack.1 unpack.1 .\" .\" fileset_database@pack.1 USER-CMDS-MAN .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: pg.1,v 74.1 95/03/23 18:06:07 ssa Exp $ .TA p .TH pg 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pg \- file perusal filter for soft-copy terminals .SH SYNOPSIS .C pg .RC [ -\c .IR number\| ] .RC [ -p\c .IR string\| ] .RC [ -cefns\| ] .RC [ +\c .IR linenumber\| ] .RC [ +/\c .IR \|pattern\| ] .RI [ \|file \ ...\|] .SS Remarks .C pg and .C more are both used in similar situations (see .IR more (1)). Text highlighting features supported by .C more are not available from .CR pg . However, .C pg has some useful features not provided by .CR more . .SH DESCRIPTION .C pg is a .I text file filter that allows the examination of .I files one screenful at a time on a soft-copy terminal. If .C - is used as a .I file argument, or .C pg detects .SM NULL arguments in the comand line, the standard input is used. Each screenful is followed by a prompt. To display a new page, press .BR Return . Other possibilities are enumerated below. .PP This command is different from other paginators such as .C more in that it can back up for reviewing something that has already passed. The method for doing this is explained below. .PP In order to determine terminal attributes, .C pg scans the .C terminfo data base for the terminal type specified by the environment variable .C TERM (see .IR terminfo (4)). If .C TERM is not defined, terminal type .C dumb is assumed. .SS Options .C pg recognizes the following command line options: .RS .TP 15 .CI - number .I number is an integer specifying the size (in lines) of the window that .C pg is to use instead of the default (on a terminal containing 24 lines, the default window size is 23). .TP .CI -p \0string Causes .C pg to use .I string as the prompt. If the prompt string contains a .CR %d , the first occurrence of .C %d in the prompt is replaced by the current page number when the prompt is issued. The default prompt string is a colon .RC ( : ). .TP .C -c Home the cursor and clear the screen before displaying each page. This option is ignored if .C clear_screen is not defined in the .C terminfo data base for this terminal type. .TP .C -e Causes .C pg to .I not pause at the end of each file. .TP .C -f Normally, .C pg splits lines longer than the screen width, but some sequences of characters in the text being displayed (such as escape sequences for underlining) generate undesirable results. The .C -f option inhibits .C pg from splitting lines. .TP .C -n Normally, commands must be terminated by a new-line character. This option causes an automatic end-of-command as soon as a command letter is entered. .TP .C -s Causes .C pg to print all messages and prompts in standout mode (usually inverse video). .TP .CI + linenumber Start display at .IR linenumber . .TP .CI +/ pattern / Start up at the first line containing text that matches the regular expression .IR pattern . .RE .PP .C pg looks in the environment variable .C PG to preset any flags desired. For example, if you prefer to view files using the .C -c mode of operation, the Bourne-shell command sequence .C "PG=\'-c\' ; export PG" or the C-shell command .C "setenv PG -c" causes all invocations of .CR pg , including invocations by programs such as .C man and .CR msgs , to use this mode. The command sequence to set up the .C PG environment variable is normally placed in the user .C .profile or .C .cshrc file. .PP The responses that can be typed when .C pg pauses can be divided into three categories: those causing further perusal, those that search, and those that modify the perusal environment. .PP Commands that cause further perusal normally take a preceding .IR address , an optionally signed number indicating the point from which further text should be displayed. This .I address is interpreted either in pages or lines, depending on the command. A signed .I address specifies a point relative to the current page or line; an unsigned .I address specifies an address relative to the beginning of the file. Each command has a default address that is used if none is provided. .PP Perusal commands and their defaults are as follows: .RS .TP 15 .RI (+1)< newline "> or <" blank > Displays one page. The address is specified in pages. .TP .RC "(+1) " l With a relative address, .C pg simulates scrolling the screen, forward or backward, the number of lines specified. With an absolute address .C pg prints a screenful beginning at the specified line. .TP .RC "(+1) " d " or " ^D Simulates scrolling a half-screen forward or backward. .RE .PP The following perusal commands take no .IR address : .RS .TP 15 .CR . " or " ^L Typing a single period causes the current page of text to be redisplayed. .TP .C $ Displays the last windowful in the file. Use with caution when the input is a pipe. .RE .PP The following commands are available for searching for text patterns in the text. The Basic Regular Expression syntax (see .IR regexp (5)) is supported. Regular expressions must always be terminated by a new-line character, even if the .C -n option is specified. .RS .TP 15 .IC i / pattern / Search forward for the .IR i th (default .IR i =1) occurrence of .IR pattern . Searching begins immediately after the current page and continues to the end of the current file, without wrap-around. .TP .IC i ^ pattern ^ .PD 0 .TP .IC i ? pattern ? Search backwards for the .IR i th (default .IR i =1) occurrence of .IR pattern . Searching begins immediately before the current page and continues to the beginning of the current file, without wrap-around. The .C ^ notation is useful for Adds 100 terminals which cannot properly handle the .CR ? . .RE .PD .PP After searching, .C pg normally displays the line found at the top of the screen. This can be modified by appending .C m or .C b to the search command to leave the line found in the middle or at the bottom of the window from now on. The suffix .C t can be used to restore the original situation. .PP .C pg users can modify the perusal environment with the following commands: .RS .TP 15 .IC i n Begin perusing the .IR i th next file in the command line. The .I i is an unsigned number, default value is 1. .TP .IC i p Begin perusing the .IR i th previous file in the command line. .I i is an unsigned number, default is 1. .TP .IC i w Display another window of text. If .I i is present, set the window size to .IR i . .TP .CI s \0filename Save the input in the named file. Only the current file being perused is saved. The white space between the .C s and .I filename is optional. This command must always be terminated by a new-line character, even if the .C -n option is specified. .TP .C h Help by displaying an abbreviated summary of available commands. .TP .CR q " or " Q " Quit .IR pg . .TP .CI ! command .I command is passed to the shell, whose name is taken from the .C SHELL environment variable. If this is not available, the default shell is used. This command must always be terminated by a new-line character, even if the .C -n option is specified. .RE .PP To cause .C pg to stop sending output and display the prompt at any time when output is being sent to the terminal, press the quit key (normally Ctrl-\e) or the interrupt (break) key. Any one of the above commands can then be entered in the normal manner. Unfortunately, some output is lost when this is done, due to the fact that any characters waiting in the terminal's output queue are flushed when the quit signal occurs. .PP If the standard output is not a terminal, .C pg is functionally equivalent to .C cat (see .IR cat (1)), except that a header is printed before each file if more than one file is specified. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the collating sequence used in evaluating regular expressions. .PP .C LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, and the characters matched by character class expressions in regular expressions. .PP .C LANG determines the language in which messages are displayed. .PP If .C LC_COLLATE or .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C pg behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLEs To use .C pg when reading system news: .IP .ifn \f3news | pg -p "(Page %d):"\f1 .ift \f4\s+1news | pg -p "(Page %d):"\f1\s0 .SH WARNINGS If terminal tabs are not set every eight positions, undesirable results may occur. .PP When using .C pg as a filter with another command that changes the terminal .SM I/O options (such as .IR crypt (1)), terminal settings may not be restored correctly. .PP While waiting for terminal input, .C pg responds to .CR BREAK , .CR DEL , and .C ^ by terminating execution. Between prompts, however, these signals interrupt .IR pg 's current task and place the user in prompt mode. These should be used with caution when input is being read from a pipe, because an interrupt is likely to terminate the other commands in the pipeline. .PP Users of .C more will find that the .C z and .C f commands are available, and that the terminal .CR / , .CR ^ , or .C ? can be omitted from the pattern search commands. .SH FILES .TP 40 .C /usr/share/lib/terminfo/?/* terminal information data base .PD 0 .TP .C /tmp/pg* temporary file when input is from a pipe .PD .SH SEE ALSO crypt(1), grep(1), more(1), terminfo(4), environ(5), lang(5), regexp(5). .SH STANDARDS CONFORMANCE .CR pg ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4pg\f1 \- file perusal filter for soft-copy terminals@@@\f3pg(1)\f1 .\" index@display file on soft-copy terminals@@@\f3pg(1)\f1 .\" index@files: display file on soft-copy terminals@@@\f3pg(1)\f1 .\" index@file perusal filter for soft-copy terminals@@@\f3pg(1)\f1 .\" index@peruse file on soft-copy terminals@@@\f3pg(1)\f1 .\" index@soft-copy terminals, peruse file on@@@\f3pg(1)\f1 .\" .\" toc@\f3pg(1)\f1:\0\0\f4pg\f1@@@file perusal filter for soft-copy terminals .\" .\" fileset_database@pg.1 USER-CMDS-MAN .\" $Header: lpfilter.1,v 72.4 94/07/05 17:17:26 ssa Exp $ .TA l .TH lpfilter 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lpfilter, divpage, fontdl, lprpp, plotdvr, printstat, reverse \- filters invoked by lp interface scripts .SH SYNOPSIS .C /usr/lbin/divpage .RC [ -p \(or .CR -l ] .RC [ -h \(or .CR -q ] .RC [ -n\c .IR FontID\| ] .I filename .PP .C /usr/lbin/fontdl .RC [ -n\c .IR FontID\| ] .RC [ -l ] .RC [ -p ] .I filename .PP .C /usr/lbin/lprpp .RC [ -i ] .RC [ -o ] .RC [ -e ] .RC [ -l\c .IR nn\| ] .RC [ -n ] .RC [ -p ] .PP .C /usr/lbin/plotdvr .CI -l \|request_id .CI -u \|username .RC [ -e ] .RC [ -f ] .RC [ -i ] .I filename .PP .C /usr/sbin/printstat .CI -l \|request_id .CI -u \|username .I filename .PP .C /usr/sbin/reverse .RC [ -l .IR page_length\| ] .SS Remarks The structure of these filters is currently under review. They may become obsolete or be restructured in a future release. .SH DESCRIPTION Various filters are used by the .C lp subsystem to obtain specialized behavior for specific types of devices or data. This entry describes currently supported filters. .PP A number of these filters use a specified .I username and .I filename to determine the location of the user who originated the print message. .PP The .I filename is used to determine the .I hostname of the system where the request originated, and must have the form .RI [ dirname ]\c .CI /d?A \|nnnhostname or .RI [ dirname ]\c .CI /dA \|nnnnhostname\f1, where .I dirname is not a path name, but only the name of the basename's parent directory. .I filename meets this requirement when it is set to .C $6 in the interface script for the printer. .SS divpage Provides capabilities for printing multiple pages per sheet and selection of built-in fonts. .PP .C Options: .RS .TP 15 .C -p Set mode to portrait (default). .TP .C -l Set mode to landscape. .TP .C -h Print half pages (default). .TP .C -q Print quarter pages. .TP .CI -n \|FontID Use font number .IR FontID . Default is 0. Causes the string .CI \s-2\uE\dC\s0( \|Font\s-1ID\s0 X to be sent to the printer. .RE .SS fontdl .I fontdl downloads the font contained in .I filename to a printer connected to standard output. .PP .C Options: .RS .TP 15 .CI -n \|FontID Specifies the ID number by which the font will be referenced. Default is 0. .TP .C -l Specify landscape mode. Default is portrait. .TP .C -p Specifies proportional spacing. Default is fixed. .RE .SS lprpp This is a filter that converts backspace overstrike to line overprint with horizontal print positioning to enhance bold print. This functionality is required on printers such as the LaserJet, which cannot produce bold print by overstriking. .PP .C Options: .RS .TP 15 .C -i Converts to _ to italicize ANYCHAR. Also properly italicizes overstruck (bold) characters. Does .I not work correctly for "hashed-overstrike" such as: .br \0 .br \0\0\0\0\0\0_ .TP .C -o Prints only the odd numbered pages. Used with .C -e for double-sided printing. .TP .C -e Print only the even numbered pages. Used with .C -o for double sided printing. .TP .CI -l \|nn Specifies the page length, in lines. Default is 60 unless .I -n or .I -p is selected, in which case it is 66. .TP .C -n Specifies nroff mode for printing output of the .I nroff command. Prints 66 lines per page with the first line appearing on logical line 4 of the printer. .TP .C -p Specifies pr mode for printing output from the .I pr command. Prints 66 lines per page with the first line appearing on logical line 3 of the printer. .SS plotdvr HP-GL plotter filter. This filter scans the data for "PG" commands (paper feed). When this data is encountered, the filter strips it from the data stream and informs the requesting user of the need to change paper in the plotter. .PP Options: .RS .TP 15 .CI -l \|request_id Specifies the printer request ID and is used in various messages regarding the plot request. .TP .CI -u \|username The requesting user's login name, used to communicate with the user regarding the request. .TP .C -e Specifies the use of escape sequences, rather than HP-GL commands, to determine plotter status. .TP .C -f Plot without stopping for paper changes. The "PG" commands are not stripped from the data stream and the user is not notified of them. This option is used on plotters capable of automatic page feed. .TP .C -i Prevents initialization of the plotter. .RE .SS printstat Interrogates an RS232 printer as to its status, and does not return until the printer is ready. If the printer is .IR off-line , .IR "out of paper" , or .IR disconnected , the submitter of the print request is notified of this condition periodically until it is corrected. When the printer is ready to print, the command exits. .PP Standard input and standard output must both be connected to the serial printer device. .PP This program uses the .I send-status command .C \s-2\uE\dC\s0?\s-2\uD\d1\s0? to determine status. Not all serial printers respond to this command. Only the following configurations support this command: .RS .PP .TS box; cB | cB l | l. Printer Comments _ LaserJet Not supported LaserJetII Supported LaserJetIID Requires \s-1HP\|26013A\s0 module LaserJetIIP Not supported LaserJetIII Requires \s-1HP\|26013A\s0 module LaserJet2000 Not supported .TE .RE .PP .C Options: .RS .TP 15 .CI -l \|request-id Print request ID used in various communications with the user. .TP .CI -u \|username The requesting user's login name, used to communicate with the user regarding the request. .RE .SS reverse Prints the data appearing on the standard input in reverse page order to the standard output. This command can handle up to 2000 pages. .PP .C Options: .RS .TP 15 .CI -l \|page_length Specifies the page length, in lines. Default is 66. .RE .SH DIAGNOSTICS Error and diagnostic messages appear on the printed output, on the user's terminal, or are mailed to the user, depending on circumstances. .SH WARNINGS There is little consistency in the interface to these filters. .SH SEE ALSO lp(1), lpadmin(1). .PP .IR "HP-UX System Administration Manual" . .\" .\" index@\f4lpfilter\f1 \- filters invoked by lp interface scripts@@@\f3lpfilter(1)\f1 .\" index@\f4divpage\f1 \- divide pages for two-sided printing@@@\f3lpfilter(1)\f1 .\" index@\f4fontdl\f1 \- download fonts to printer@@@\f3lpfilter(1)\f1 .\" index@\f4hp2686a\f1 \- laserjet filter@@@\f3lpfilter(1)\f1 .\" index@\f4hp2934a\f1 \- character printer filter@@@\f3lpfilter(1)\f1 .\" index@\f4lprpp\f1 \- laserjet filter@@@\f3lpfilter(1)\f1 .\" index@\f4plotdvr\f1 \- plotter driver for lp@@@\f3lpfilter(1)\f1 .\" index@\f4printstat\f1 \- check status of serial printer@@@\f3lpfilter(1)\f1 .\" index@\f4reverse\f1 \- reverse printer pages for collating@@@\f3lpfilter(1)\f1 .\" .\" toc@\f3lpfilter(1)\f1:\0\0\f4lpfilter\f1@@@filters used by the lp interface scripts .\" .\" links@lpfilter.1 divpage.1 .\" links@lpfilter.1 fontdl.1 .\" links@lpfilter.1 lprpp.1 .\" links@lpfilter.1 plotdvr.1 .\" links@lpfilter.1 printstat.1 .\" links@lpfilter.1 reverse.1 .\" $Header: ppl.1,v 72.4 94/09/12 14:58:21 ssa Exp $ .TA p .TH ppl 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ppl \- point-to-point serial networking using SLIP or CSLIP .SH SYNOPSIS .C ppl .RC [ -o \(or -i ] .RC [ -t .IR tty\| ] .RC [ -v ] .RC [ -r .IR rtprio\| ] .RC [ -T .IR tracefile\| ] .RI [ \|remote_host\| ] .SH DESCRIPTION .C ppl extends the Internet Protocol .SM (IP) network over serial lines. It permits the use of hardwired, dial-out, or dial-in serial (tty) lines. .C ppl establishes a connection over the serial line, then runs an .B encapsulation protocol to transfer packets between the .SM IP network and the serial line. Once started, .C ppl can only be stopped by loss of the serial line (i.e. carrier failure indication from a modem), or by sending it a .C SIGTERM signal. .PP Currently .SM SLIP (Serial Line Internet Protocol), .SM CSLIP (Compressed Header .SM SLIP), and .SM ASLIP (Abbreviated .SM SLIP\s0) are the only encapsulation protocols available. .PP .C ppl can be configured in a number of ways. It behaves according to how it is configured and which command line options are used. Configuration is controlled by configuration files: .C ppl.remotes, .C ppl.ipool, and .C ppl.users. .C ppl can be configured to share .SM UUCP serial lines. .SS Options .TP 15 .C -i Initiate an incoming connection. Run the encapsulation protocol on the terminal device from which the program is invoked. This is the default if neither .C -o nor .C -i is specified. .TP .C -o Initiate an outgoing connection. The terminal on which the data pump is started is determined from configuration files, .SM UUCP, or the .C -t option. .TP .CI -t \0tty Specifies the .I tty on which the encapsulation protocol is started, .I only if a device name is not specified in configuration file .C ppl.remotes for the remote host. This option only applies when used with the .C -o option. .TP .C -v Verbose mode. This option is only available to the super-user. Verbose debugging information is displayed on the terminal and placed in the log. Secure information is included. .TP .CI -r \0rtprio Set real-time priority during data pump operation. .I rtprio can be a decimal number between 0 and 127. By default, .C ppl runs at a real-time priority of 110. .TP .CI -T \0tracefile Turns on tracing for the SLIP connection that ppl creates. Tracing is done in user space level by .C ppl. All data that are going from IP to the tty line and vice versa are traced. This option is different from the system tracing utility .C nettl, because this option is done for each connection in the user space. .C nettl performs tracing for the entire system. The contents of the .I tracefile are in human readable ASCII format. .TP .I remote_host Specifies the remote host to communicate with. Either a name or an Internet address (in dot notation) can be supplied. This must be the last argument on the command line. If none is supplied (with the .C -i option), ppl uses the users login name to find a remote host in the .C ppl.users file. .SS Dedicated Connections Dedicated connections are lines that are dedicated to .IR ppl . No getty/login is running on the local or remote end of the serial line. Such a line can be either hard-wired, dial-out, or dial-in. .PP Alternatively, .C ppl can run on lines that are used for other purposes; specifically, a getty/login on incoming lines, or shared with .SM UUCP on outgoing lines. .SS Dial-Out Connections To dial out from an .SM HP-UX system, use a command like: .IP .CI "ppl -o " remote_host .PP to establish a connection to a remote host. Any progress or error messages are directed to the users standard error. .C ppl accesses the .C ppl.remotes file to obtain information needed to establish the connection. If necessary, it also uses .SM UUCP files to select a line, acquire the phone number, and control the modem. Note that .C ppl uses various files created and maintained by the .SM UUCP system, but it does not use the .SM UUCP facility to handle inter-system communication. .PP The .SM UUCP line is selected as follows: .RS .TP 5 1. If the entry in the configuration file .C ppl.remotes does not contain a tty device name, .C ppl looks in the .SM UUCP .C Systems file for a tty device (and speed), based on the .C ppl.remotes entry .SM UUCP .I system name or .I remote host name. .TP 2. .C ppl then searches for the tty device name and speed in the .SM UUCP .C Devices file. This information is used for modem dialing instructions. .RE .PP After a successful connection is made, .C ppl makes itself into a ``daemon'' by detaching itself from the users tty group. The user gets back a shell prompt, and the .C ppl program runs in the background. The user can then perform network commands to the remote host. .SS Dial-In Connections To make a dial-in connection to an .SM HP-UX system, dial in on a serial line to the .SM HP-UX system, and log in as usual. Once logged in, the line can be converted from log-in to network use by running .CR ppl . The .C ppl program uses the login name to search .C ppl.users for a remote hostname. The remote hostname is used to access the .C ppl.remotes file to obtain all of the configuration information needed to start the desired protocol. Once the protocol starts, the users' local machine can begin packet transfers with .CR ppl . .C ppl never (voluntarily) exits, and therefore never returns a prompt. .PP Only one invocation of .C ppl is allowed to each remote host Internet address. .PP A unique local Internet address must be associated with each invocation of .CR ppl . This can be specified in the .C ppl.remotes file or it can be selected at run time from a pool of Internet addresses provided by .CR ppl.ipool. .SS SLIP over the DTC SLIP is supported over modem-to-DTC-LAN connections in binary mode up to 9600 baud for HP 9000/800 hosts. The SLIP configurations used over a mux connection should work over the DTC with the following exception. On the called host, the serial line parameter should be the device file name of a nailed DTC port as defined by the DDFA utility. .SS Log Files .C ppl keeps a log of its activities in .CR /var/ppl/log . .PP Another log can optionally be kept for creating bills or keeping track of serial line usage. If the file .C /var/ppl/bill exists, .C ppl adds an entry to this file each time it gracefully exits. The contents of the billing file are in human readable .SM ASCII form. The file is also program readable, suitable for export to various databases. It contains the following fields, separated by a semicolon (;) .CR \| : bill end time, bill start time, Local inetaddr, Remote inetaddr, login user name, tty name, and protocol. .PP The current status of all invocations of .C ppl are kept updated in the file .C /var/ppl/ptmp, if the file exists. .SS Lock Files .C ppl creates two lock files for each invocation of the program. These lock files serve three purposes: .RS .TP 3 \(bu They lock access to the Internet network address by encoding the Internet address (in hex) as part of the file name. .TP \(bu They contain various details about the connection. .TP \(bu They can be executed (by owner or root) as a shell script. When executed, they send a signal to .IR ppl , causing it to exit gracefully. .RE .PP Whenever .C ppl exits gracefully, it removes these lock files and releases resources. .PP If .C ppl uses a .SM UUCP line, it observes and creates .SM UUCP lock file protocol. .SS Gateway Packets .SM ASLIP is an abbreviated header enhancement to .SM SLIP. It provides throughput economy in non-gateway applications. One end of an .SM ASLIP line must act as a ``client''; the other end as a ``server''. Typically the client is a personal workstation; the server a larger machine. .PP The client sends non-gateway packets using .SM ASLIP and gateway packets using .SM SLIP. The server adapts its operation to the behavior of the client. .SM ASLIP operation must be specified in the .C ppl.remotes file. .SH FILES .PD 0 .TP 40 .C /etc/ppl/ppl.remotes all options for each remote connection .TP .C /etc/ppl/ppl.ipool pool of local Internet addresses that can be used .TP .C /etc/ppl/ppl.users translates users login name to a remote host .TP .CI /var/ppl/PPL. xxxx termination command file and lock file for local Internet address .TP .CI /var/ppl/ppl. xxxx termination command file and lock file for remote Internet address .TP .C /var/ppl/log audit trail and log file .TP .C /var/ppl/bill billing file (optional) .TP .C /var/ppl/ptmp status file (optional) .PD .SH AUTHOR .C ppl was developed by HP. .SH WARNINGS The log and bill files grow without bounds. .SH SEE ALSO pplstat(1), ppl.remotes(4), ppl.ipool(4), ppl.users(4), ppl.ptmp(4), .br .I Using Serial Line IP Protocols, .SM .I UUCP tutorial in .IR "Remote Access Users Guide" . .\" .\" index@\f4ppl\f1 \- point-to-point serial networking@@@\f3ppl(1)\f1 .\" index@point-to-point serial networking@@@\f3ppl(1)\f1 .\" index@serial networking, point-to-point@@@\f3ppl(1)\f1 .\" index@networking, point-to-point serial@@@\f3ppl(1)\f1 .\" .\" toc@\f3ppl(1)\f1:\0\0\f4ppl\f1@@@point-to-point serial networking .\" .\" links@ppl.1 slip.1 .\" links@ppl.1 cslip.1 .\" .\" fileset_database@ppl.1 USER-CMDS-MAN .\" $Header: pplstat.1,v 72.4 94/09/12 16:02:53 ssa Exp $ .TA p .TH pplstat 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pplstat \- give status of each invocation of \f2ppl\f1(1) .SH SYNOPSIS .C pplstat .RC [ -l ] .RC [ -n ] .SH DESCRIPTION .C pplstat displays connection information for each current invocation of .C ppl (see .IR ppl (1)). The tty device file, Internet addresses, user who invoked .CR ppl , and other useful information are provided. .C pplstat displays each record in the .C ptmp file that is not marked idle (see .IR ppl.ptmp (4)). .PP Information can be displayed in two formats. By default, an abbreviated table format is displayed with one entry per line like the following: .IP .C "User TTY When Protocol Local Remote" .br .C "guest tty0 024 19:22 CSLIP packard hewlett" .PP The .C -l option causes a more verbose, multi-line format like: .nf .IP .C "log_name guest" .C "rhost_name hewlett" .C "system_name packard" .C "Linetaddr packard" .C "Rinetaddr 15.255.136.5" .C "netmask 255.0.0.0" .C "tty /dev/tty0" .C "ni /dev/ni0" .C "status CSLIP" .C "killfile (r) /var/ppl/ppl.0fff8804" .C "killfile (l) /var/ppl/PPL.0fff8806" .C "start_time Mon Jan 24 19:22:18 1994" .fi .SS Options .C pplstat recognizes the following options: .RS .TP 8 .C -l Produce a long-form display. .TP .C -n Print host and network addresses in Internet dot notation. .RE .SH FILES .C /var/ppl/ptmp(4) .SH AUTHOR .C pplstat was developed by HP. .SH SEE ALSO ppl(1), ppl.ptmp(4). .\" .\" index@\f4pplstat\f1 \- give status of each invocation of \f4ppl\f1@@@\f3pplstat(1)\f1 .\" index@status of each invocation of \f4ppl\f1, give@@@\f3pplstat(1)\f1 .\" index@\f4ppl\f1, give status of each invocation of@@@\f3pplstat(1)\f1 .\" .\" toc@\f3pplstat(1)\f1:\0\0\f4pplstat\f1@@@give status of each invocation of ppl .\" .\" fileset_database@pplstat.1 USER-CMDS-MAN .\" $Header: pr.1,v 76.1 95/07/11 13:45:51 ssa Exp $ .TA p .TH pr 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pr \- print files .SH SYNOPSIS .C pr .RI [ options ] .RI [ files ] .SH DESCRIPTION The .CR pr command prints the named files on the standard output. If .I file is .CR - , or if no files are specified, the standard input is assumed. By default, the listing is separated into pages, each headed by the page number, a date and time, and the name of the file. .PP By default, columns are of equal width, separated by at least one space; lines that do not fit are truncated. If the .CR -s option is used, lines are not truncated and columns are separated by the separation character. .PP If the standard output is associated with a terminal, error messages are withheld until .CR pr has completed printing. .SS Options The following .I options can be used singly or combined in any order: .RS .TP 10 .CI + k Begin printing with page .I k (default is 1). .TP .CI - k Produce .IR k -column output (default is 1). This option should not be used with .CR -m . The options .CR -e and .CR -i are assumed for multi-column output. .TP .CI -c \0k Produce .IR k -column output, same as .CI - k. .TP .C -a Print multi-column output across the page. This option is appropriate only with the .CI - k option. .TP .C -m Merge and print all files simultaneously, one per column (overrides the .CI - k and .CR -a options). .TP .C -d Double space the output. .TP .CI -e ck Expand .I input tabs to character positions .IR k +1, .RI 2\(mu k +1, .RI 3\(mu k +1, etc. If .I k is 0 or is omitted, default tab settings at every eighth position are assumed. Tab characters in the input are expanded into the appropriate number of spaces. If .I c (any nondigit character) is given, it is treated as the input tab character (default for .I c is the tab character). .TP .CI -i ck In .IR output , replace white space wherever possible by inserting tabs to character positions .IR k +1, .RI 2\(mu k +1, .RI 3\(mu k +1, etc. If .I k is 0 or is omitted, default tab settings at every eighth position are assumed. If .I c (any nondigit character) is given, it is treated as the output tab character (default for .I c is the tab character). .TP .CI -n ck Provide .IR k -digit line numbering (default for .I k is 5). The number occupies the first .IR k +1 character positions of each column of normal output or each line of .CR -m output. If .I c (any nondigit character) is given, it is appended to the line number to separate it from whatever follows (default for .I c is a tab). .TP .CI -w k Set the width of a line to .I k character positions (default is 72 for equal-width, multi-column output; no limit otherwise). Width specifications are only effective for multi-columnar output. .TP .CI -o k Offset each line by .I k character positions (default is 0). The number of character positions per line is the sum of the width and offset. .TP .CI -l k Set the length of a page to .I k lines (default is 66). If .I k is less than what is needed for the page header and trailer, the .CR -t option is in effect; that is, header and trailer lines are suppressed in order to make room for text. .C .TP .C -h Use the next argument as the header to be printed instead of the file name. .TP .C -p Pause before beginning each page if the output is directed to a terminal .RC ( pr rings the bell at the terminal and waits for a .BR Return ). .TP .C -F Use form-feed character for new pages (default is to use a sequence of line-feeds). Pause before beginning the first page if the standard output is associated with a terminal. .TP .C -f Same as .CR -F . Provided for backwards compatibility. .TP .C -r Print no diagnostic reports on failure to open files. .TP .C -t Print neither the five-line identifying header nor the five-line trailer normally supplied for each page. Quit printing after the last line of each file without spacing to the end of the page. .TP .CI -s c Separate columns by the single character .I c instead of by the appropriate number of spaces (default for .I c is a tab). .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_CTYPE determines the interpretation of text and the arguments associated with the .CR -e , .CR -i , .CR -n , and .CR -s options as single-byte and/or multi-byte characters. .PP .CR LC_TIME determines the format and contents of date and time strings. .PP .CR LC_MESSAGES determines the language in which messages are displayed. .PP If .CR LC_CTYPE , .CR LC_TIME , or .CR LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of .CR C (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .CR pr behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH RETURN VALUE The .CR pr returns the following values upon completion: .RS .TP 8 .C \00 Successful completion. .PD 0 .TP .C >0 One or more of the input .I files do not exist or cannot be opened. .RE .PD .SH EXAMPLES Print .CR file1 and .CR file2 as a double spaced, three column listing headed by ``file list'': .IP .C pr -3dh .C "file list" .C file1 file2 .PP Write .CR file1 on .CR file2 , expanding tabs to columns 10, 19, 28, 37, .\|.\|. : .IP .C "pr -e9 -t file2" .PP Print .CR file1 in default format with nonblank lines numbered down the left side: .IP .C "nl file1 |pr" .SH FILES .TP 20 .C /dev/tty .SH SEE ALSO cat(1), lp(1), nl(1), ul(1). .SH STANDARDS CONFORMANCE .CR pr ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4pr\f1 \- format and print files@@@\f3pr(1)\f1 .\" index@\f1format and print files@@@\f3pr(1)\f1 .\" index@\f1print files, format and@@@\f3pr(1)\f1 .\" index@\f1output (format and print) files@@@\f3pr(1)\f1 .\" index@\f1files, format and print@@@\f3pr(1)\f1 .\" .\" toc@\f3pr(1)\f1:\0\0\f4pr\f1@@@format and print files\f1 .\" @(#)praliases.1 8.1 (Berkeley) 9/21/96 .TH praliases 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: August 1997 .SH NAME .B praliases \- display system mail aliases .SH SYNOPSIS .B praliases .RC [ -f .IR file \| ] .SH DESCRIPTION The .B praliases utility displays the current system aliases, one per line, in no particular order. .PP The options are as follows: .TP 10 .C -f Read the specified file instead of the default .B sendmail system aliases file. .SH RETURN VALUE The .B praliases utility exits 0 on success, and >0 if an error occurs. .SH FILES .TP 25 /etc/mail/aliases The default .B sendmail system aliases file. .TP /etc/mail/aliases.db The database version of the .IR /etc/mail/aliases file. .SH SEE ALSO mailq(1), sendmail(1M). .\" $Header: prealloc.1,v 72.3 93/01/14 11:37:38 ssa Exp $ .TA p .TH prealloc 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME prealloc \- preallocate disk storage .SH SYNOPSIS .C prealloc .I name size .SH DESCRIPTION .C prealloc preallocates at least .I size bytes of disk space for an ordinary file .IR name , creating the file if .I name does not already exist. The space is allocated in an implementation-dependent fashion for fast sequential reads and writes of the file. .PP .C prealloc fails and no disk space is allocated if .I name already exists and is not an ordinary file of zero length, if insufficient space is left on disk, or if .I size exceeds the maximum file size or the file size limit of the process (see .IR ulimit (2)). The file is zero-filled. .SH DIAGNOSTICS .C prealloc returns one of the following values upon completion: .RS .TP 8 .B 0 Successful completion. .PD 0 .TP .B 1 .I name already exists and is not an ordinary file of zero length. .TP .B 2 There is insufficient room on the disk. .TP .B 3 .I size exceeds file size limits. .SH EXAMPLES The following example preallocates 50\|000 bytes for the file .CR myfile : .IP .C prealloc myfile 50000 .SH WARNINGS Allocation of file space is highly dependent on current disk usage. A successful return does not indicate how fragmented the file actually might be if the disk is approaching its capacity. .SH AUTHOR .C prealloc was developed by HP. .SH SEE ALSO prealloc(2), ulimit(2). .\" .\" toc@\f3prealloc(1)\f1:\0\0\f4prealloc\f1@@@preallocate disk storage .\" .\" index@\f4prealloc\f1 \- preallocate disk storage@@@\f3prealloc(1)\f1 .\" index@preallocate space for a disk storage file@@@\f3prealloc(1)\f1 .\" index@allocate reserved space for a disk storage file@@@\f3prealloc(1)\f1 .\" index@reserve disk space@@@\f3prealloc(1)\f1 .\" index@disk storage space, preallocate@@@\f3prealloc(1)\f1 .\" index@storage, preallocate disk@@@\f3prealloc(1)\f1 .\" .\" fileset_database@prealloc.1 USER-CMDS-MAN .\" $Header: factor.1,v 72.3 93/01/14 11:33:24 ssa Exp $ .TA f .TH factor 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME factor, primes \- factor a number, generate large primes .SH SYNOPSIS .C factor .RI [ \|number\| ] .PP .C primes .RI [ \|start\| [ \|stop\| ]\|] .SH DESCRIPTION If no arguments are provided on the command line, .C factor waits for a number to be typed in. If a positive number is typed, it factors the number and print its prime factors; each one is printed the proper number of times. It then waits for another number. .C factor exits if it encounters a zero or any non-numeric character. .PP If an argument is provided on the command line, .C factor factors the number as above, then exits. .PP Maximum time to factor is proportional to .RI sqrt( n ) and occurs when .I n is prime or the square of a prime. .PP The largest number that can be dealt with by .C factor is 1.0e14. .PP .C primes prints prime numbers between a lower and upper bound. If no arguments are provided on the command line, .C primes waits for two numbers to be typed in. The first number is interpreted as the lower bound; the second as the upper bound. All prime numbers in the resulting inclusive range are printed. .PP If .I start is specified, all primes greater than or equal to .I start are printed. If both .I start and .I stop are given, all primes occurring in the inclusive range .I start through .I stop are printed. .PP .I start and .I stop values must be integers represented as long integers. .PP If the stop value is omitted in either case, .I primes runs either until overflow occurs or until it is stopped by typing the interrupt character. .PP The largest number that can be dealt with by .I primes is 2,147,483,647. .SH DIAGNOSTICS Both commands print .C Ouch when the input is out of range, illegal characters are encountered, or when .I start is greater than .IR stop . .SH EXAMPLES Print the prime factorization for the number 12: .IP .C factor 12 .PP Print all prime numbers between 0 and 20: .IP .C primes 0 20 .\" .\" index@\f4factor\f1, \f4primes\f1 \- factor a number, generate large primes@@@\f3factor(1)\f1 .\" index@\f4primes\f1, \f4factor\f1 \- factor a number, generate large primes@@@\f3factor(1)\f1 .\" index@factor a number, generate large primes@@@\f3factor(1)\f1 .\" index@generate large primes, factor a number@@@\f3factor(1)\f1 .\" .\" toc@\f3factor(1)\f1:\0\0\f4factor\f1, \f4primes\f1@@@factor a number, generate large primes .\" toc@\f4primes\f1: generate large prime numbers@@@see \f3factor(1)\f1 .\" .\" links@factor.1 primes.1 .\" .\" fileset_database@factor.1 USER-CMDS-MAN .\" $Header: printenv.1,v 72.3 93/01/14 11:37:31 ssa Exp $ .TA p .TH printenv 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME printenv \- print out the environment .SH SYNOPSIS .C printenv .RI [ \|name\| ] .SH DESCRIPTION .C printenv prints out the values of the variables in the environment. If a .I name is specified, only its value is printed. .SH RETURN VALUE If a .I name is specified and it is not defined in the environment, .C printenv returns 1; otherwise it returns zero. .SH SEE ALSO sh(1), environ(5), csh(1). .\" .\" toc@\f3printenv(1)\f1:\0\0\f4printenv\f1@@@print out the environment .\" .\" index@\f4printenv\f1 \- print out the environment@@@\f3printenv(1)\f1 .\" index@print out the environment@@@\f3printenv(1)\f1 .\" index@environment, print out the@@@\f3printenv(1)\f1 .\" index@variables, environment, print value of@@@\f3printenv(1)\f1 .\" .\" fileset_database@printenv.1 USER-CMDS-MAN .\" $Header: printf.1,v 76.1 95/08/23 17:34:14 ssa Exp $ .TA p .TH printf 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME printf \- format and print arguments .SH SYNOPSIS .C printf .I format .RI [ \|arg \ ...\|] .SH DESCRIPTION .C printf writes formatted arguments to the standard output. The .I arg arguments are formatted under control of the .I format operand. .PP .I format is a character string patterned after the formatting conventions of .IR printf (3C), and contains the following types of objects: .RS .TP 20 .I characters Characters that are not .I escape sequences or .I conversion specifications (as described below) are copied to standard output. .TP .I escape sequences These are interpreted as non-graphic characters: .RS .RS .TP .C \ea alert .PD 0 .TP .C \eb backspace .TP .C \ec print line without appending a new-line .TP .C \ef form-feed .TP .C \en new-line .TP .C \er carriage return .TP .C \et tab .TP .C \ev vertical tab .TP .C \e' single quote character .TP .C \e\e backslash .TP .CI \e n the 8-bit character whose .SM ASCII code is the 1-, 2-, 3-, or 4-digit octal number .IR n , whose first character must be a zero. .RE .RE .PD .TP .I conversion specification Specifies the output format of each argument ( see below). .PP Arguments following .I format are interpreted as strings if the corresponding format is either .C c or .CR s ; otherwise they are treated as constants. .SS Conversion Specifications Each conversion specification is introduced by the percent character .CR % . After the .C % character, the following can appear in the sequence indicated: .RS .TP 12 .I flags Zero or more .IR flags , in any order, which modify the meaning of the conversion specification. The flag characters and their meanings are: .RS .RS .TP 10 .C - The result of the conversion is left-justified within the field. .TP .C + The result of a signed conversion always begins with a sign, .C + or .CR - . .TP If the first character of a signed conversion is not a sign, a space character is prefixed to the result. This means that if the space flag and .C + flag both appear, the space flag is ignored. .TP .C # The value is to be converted to an ``alternate form''. For .CR c , .CR d , .CR i , .CR u , and .C s conversions, this flag has no effect. For .C o conversion, it increases the precision to force the first digit of the result to be a zero. For .C x or .C X conversion, a non-zero result has .C 0x or .C 0X prefixed to it. For .CR e , .CR E , .CR f , .CR g , and .C G conversions, the result always contains a radix character, even if no digits follow the radix character. For .C g and .C G conversions, trailing zeros are not removed from the result, contrary to usual behavior. .RE .RE .TP .I field width An optional string of decimal digits to specify a minimum .IR "field width" . For an output field, if the converted value has fewer characters than the field width, it is padded on the left (or right, if the left-adjustment flag, .C - has been given) to the field width. .TP .I precision The .I precision specifies the minimum number of digits to appear for the .CR d , .CR o , .CR i , .CR u , .CR x , or .CR X conversions (the field is padded with leading zeros), the number of digits to appear after the radix character for the .C e and .C f conversions, the maximum number of significant digits for the .C g conversion, or the maximum number of characters to be printed from a string in s conversion. The precision takes the form of a period .C . followed by a decimal digit string. A null digit string is treated as a zero. .TP .I conversion characters A .I conversion character indicates the type of conversion to be applied: .RS .RS .TP 8 .CR d , i , .PD 0 .TP .CR o , u , .TP .CR x , X .sp -3v The integer argument is printed a signed decimal .RC ( d or .CR i ), unsigned octal .RC ( o ), unsigned decimal .RC ( u ), or unsigned hexadecimal notation .RC ( x and .CR X ). The .C x conversion uses the numbers and letters .CR 0123456789abcdef , and the .C X conversion uses the numbers and letters .CR 0123456789ABCDEF . The .I precision component of the argument specifies the minimum number of digits to appear. If the value being converted can be represented in fewer digits than the specified minimum, it is expanded with leading zeroes. The default precision is 1. The result of converting a zero value with a precision of 0 is no characters. .PD .TP .C f The floating-point number argument is printed in decimal notation in the style .RC [ - ]\c .IC ddd\| r ddd\c , where the number of digits after the radix character, .CR r , is equal to the .I precision specification. If the .I precision is omitted from the argument, six digits are output; if the .I precision is explicitly 0, no radix appears. .TP .CR e , E The floating-point-number argument is printed in the style .RC [ - ]\c .IC d r ddd e\(+- dd\c , where there is one digit before the radix character, and the number of digits after it is equal to the precision. When the precision is missing, six digits are produced; if the precision is 0, no radix character appears. The .C E conversion character produces a number with .C E introducing the exponent instead of .CR e . The exponent always contains at least two digits. However, if the value to be printed requires an exponent greater than two digits, additional exponent digits are printed as necessary. .TP .CR g , G The floating-point-number argument is printed in style .C f or .C e (or int style .C E in the case of a .C G conversion character), with the precision specifying the number of significant digits. The style used depends on the value converted; style .C e is used only if the exponent resulting from the conversion is less than .C -h or greater than or equal to the precision. Trailing zeros are remove from the result. A radix character appears only if it is followed by a digit. .TP .C c The first character of the argument is printed. .TP .C s The argument is taken to be a string, and characters from the string are printed until the end of the string or the number of characters indicated by the .I precision specification of the argument is reached. If the precision is omitted from the argument, it is interpreted as infinite and all characters up to the end of the string are printed. .TP .C % Print a .C % character; no argument is converted. .TP .C b Similar to the .C s conversion specifier, except that the string can contain backslash-escape sequences which are then converted to the characters they represent. .RE .RE .IP In no case does a nonexistent or insufficient field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is simply expanded to contain the conversion result. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of .I arg as single and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .I printf behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .C printf exits with one of the following values: .RS .TP .B \00 Successful completion; .TP .B >0 Errors occurred. The exit value is increased by one for each error that occurred up to a maximum of 255. .RE .SH DIAGNOSTICS If an argument cannot be converted into a form suitable for the corresponding conversion specification, or for any other reason cannot be correctly printed, a diagnostic message is printed to standard error, the argument is output as a string form as it was given on the command line, and the exit value is incremented. .SH EXAMPLES The following command prints the number 123 in octal, hexadecimal and floating point formats in their alternate form .IP .ift .ft 4 .ifn .ft 3 .ps +1 printf "%#o, %#x, %#X, %#f, %#g, %#e\en" 123 123 123 123 123 123 .ft .ps resulting in the following output .IP .C "0173, 0x7b, 0X7B, 123.000000, 123.000, 1.230000e+02" .PP Print the outputs with their corresponding field widths and precision: .IP .ift .ft 4 .ifn .ft 3 .ps +1 .nf printf "%.6d, %10.6d, %.6f, %.6e, %.6s\en" 123 123 1.23 123.4 MoreThanSix .fi .ft .ps .PP resulting in the following output .IP .C "000123, 000123, 1.230000, 1.234000e+02, MoreTh" .SH SEE ALSO echo(1), printf(3S). .SH STANDARDS CONFORMANCE .CR printf ": XPG4, POSIX.2" .\" .\" index@\f4printf\f1 \- print formatted arguments@@@\f3printf(1)\f1 .\" index@print formatted arguments@@@\f3printf(1)\f1 .\" index@display (print) formatted arguments@@@\f3printf(1)\f1 .\" index@format and print arguments@@@\f3printf(1)\f1 .\" index@arguments, print formatted@@@\f3printf(1)\f1 .\" .\" toc@\f3printf(1)\f1:\0\0\f4echo\f1@@@print formatted arguments .\" $Header: lpfilter.1,v 72.4 94/07/05 17:17:26 ssa Exp $ .TA l .TH lpfilter 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lpfilter, divpage, fontdl, lprpp, plotdvr, printstat, reverse \- filters invoked by lp interface scripts .SH SYNOPSIS .C /usr/lbin/divpage .RC [ -p \(or .CR -l ] .RC [ -h \(or .CR -q ] .RC [ -n\c .IR FontID\| ] .I filename .PP .C /usr/lbin/fontdl .RC [ -n\c .IR FontID\| ] .RC [ -l ] .RC [ -p ] .I filename .PP .C /usr/lbin/lprpp .RC [ -i ] .RC [ -o ] .RC [ -e ] .RC [ -l\c .IR nn\| ] .RC [ -n ] .RC [ -p ] .PP .C /usr/lbin/plotdvr .CI -l \|request_id .CI -u \|username .RC [ -e ] .RC [ -f ] .RC [ -i ] .I filename .PP .C /usr/sbin/printstat .CI -l \|request_id .CI -u \|username .I filename .PP .C /usr/sbin/reverse .RC [ -l .IR page_length\| ] .SS Remarks The structure of these filters is currently under review. They may become obsolete or be restructured in a future release. .SH DESCRIPTION Various filters are used by the .C lp subsystem to obtain specialized behavior for specific types of devices or data. This entry describes currently supported filters. .PP A number of these filters use a specified .I username and .I filename to determine the location of the user who originated the print message. .PP The .I filename is used to determine the .I hostname of the system where the request originated, and must have the form .RI [ dirname ]\c .CI /d?A \|nnnhostname or .RI [ dirname ]\c .CI /dA \|nnnnhostname\f1, where .I dirname is not a path name, but only the name of the basename's parent directory. .I filename meets this requirement when it is set to .C $6 in the interface script for the printer. .SS divpage Provides capabilities for printing multiple pages per sheet and selection of built-in fonts. .PP .C Options: .RS .TP 15 .C -p Set mode to portrait (default). .TP .C -l Set mode to landscape. .TP .C -h Print half pages (default). .TP .C -q Print quarter pages. .TP .CI -n \|FontID Use font number .IR FontID . Default is 0. Causes the string .CI \s-2\uE\dC\s0( \|Font\s-1ID\s0 X to be sent to the printer. .RE .SS fontdl .I fontdl downloads the font contained in .I filename to a printer connected to standard output. .PP .C Options: .RS .TP 15 .CI -n \|FontID Specifies the ID number by which the font will be referenced. Default is 0. .TP .C -l Specify landscape mode. Default is portrait. .TP .C -p Specifies proportional spacing. Default is fixed. .RE .SS lprpp This is a filter that converts backspace overstrike to line overprint with horizontal print positioning to enhance bold print. This functionality is required on printers such as the LaserJet, which cannot produce bold print by overstriking. .PP .C Options: .RS .TP 15 .C -i Converts to _ to italicize ANYCHAR. Also properly italicizes overstruck (bold) characters. Does .I not work correctly for "hashed-overstrike" such as: .br \0 .br \0\0\0\0\0\0_ .TP .C -o Prints only the odd numbered pages. Used with .C -e for double-sided printing. .TP .C -e Print only the even numbered pages. Used with .C -o for double sided printing. .TP .CI -l \|nn Specifies the page length, in lines. Default is 60 unless .I -n or .I -p is selected, in which case it is 66. .TP .C -n Specifies nroff mode for printing output of the .I nroff command. Prints 66 lines per page with the first line appearing on logical line 4 of the printer. .TP .C -p Specifies pr mode for printing output from the .I pr command. Prints 66 lines per page with the first line appearing on logical line 3 of the printer. .SS plotdvr HP-GL plotter filter. This filter scans the data for "PG" commands (paper feed). When this data is encountered, the filter strips it from the data stream and informs the requesting user of the need to change paper in the plotter. .PP Options: .RS .TP 15 .CI -l \|request_id Specifies the printer request ID and is used in various messages regarding the plot request. .TP .CI -u \|username The requesting user's login name, used to communicate with the user regarding the request. .TP .C -e Specifies the use of escape sequences, rather than HP-GL commands, to determine plotter status. .TP .C -f Plot without stopping for paper changes. The "PG" commands are not stripped from the data stream and the user is not notified of them. This option is used on plotters capable of automatic page feed. .TP .C -i Prevents initialization of the plotter. .RE .SS printstat Interrogates an RS232 printer as to its status, and does not return until the printer is ready. If the printer is .IR off-line , .IR "out of paper" , or .IR disconnected , the submitter of the print request is notified of this condition periodically until it is corrected. When the printer is ready to print, the command exits. .PP Standard input and standard output must both be connected to the serial printer device. .PP This program uses the .I send-status command .C \s-2\uE\dC\s0?\s-2\uD\d1\s0? to determine status. Not all serial printers respond to this command. Only the following configurations support this command: .RS .PP .TS box; cB | cB l | l. Printer Comments _ LaserJet Not supported LaserJetII Supported LaserJetIID Requires \s-1HP\|26013A\s0 module LaserJetIIP Not supported LaserJetIII Requires \s-1HP\|26013A\s0 module LaserJet2000 Not supported .TE .RE .PP .C Options: .RS .TP 15 .CI -l \|request-id Print request ID used in various communications with the user. .TP .CI -u \|username The requesting user's login name, used to communicate with the user regarding the request. .RE .SS reverse Prints the data appearing on the standard input in reverse page order to the standard output. This command can handle up to 2000 pages. .PP .C Options: .RS .TP 15 .CI -l \|page_length Specifies the page length, in lines. Default is 66. .RE .SH DIAGNOSTICS Error and diagnostic messages appear on the printed output, on the user's terminal, or are mailed to the user, depending on circumstances. .SH WARNINGS There is little consistency in the interface to these filters. .SH SEE ALSO lp(1), lpadmin(1). .PP .IR "HP-UX System Administration Manual" . .\" .\" index@\f4lpfilter\f1 \- filters invoked by lp interface scripts@@@\f3lpfilter(1)\f1 .\" index@\f4divpage\f1 \- divide pages for two-sided printing@@@\f3lpfilter(1)\f1 .\" index@\f4fontdl\f1 \- download fonts to printer@@@\f3lpfilter(1)\f1 .\" index@\f4hp2686a\f1 \- laserjet filter@@@\f3lpfilter(1)\f1 .\" index@\f4hp2934a\f1 \- character printer filter@@@\f3lpfilter(1)\f1 .\" index@\f4lprpp\f1 \- laserjet filter@@@\f3lpfilter(1)\f1 .\" index@\f4plotdvr\f1 \- plotter driver for lp@@@\f3lpfilter(1)\f1 .\" index@\f4printstat\f1 \- check status of serial printer@@@\f3lpfilter(1)\f1 .\" index@\f4reverse\f1 \- reverse printer pages for collating@@@\f3lpfilter(1)\f1 .\" .\" toc@\f3lpfilter(1)\f1:\0\0\f4lpfilter\f1@@@filters used by the lp interface scripts .\" .\" links@lpfilter.1 divpage.1 .\" links@lpfilter.1 fontdl.1 .\" links@lpfilter.1 lprpp.1 .\" links@lpfilter.1 plotdvr.1 .\" links@lpfilter.1 printstat.1 .\" links@lpfilter.1 reverse.1 .\" $Header: prmail.1,v 72.4 94/12/09 15:04:25 ssa Exp $ .TA p .TH prmail 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME prmail \- print out mail in the incoming mailbox file .SH SYNOPSIS .C prmail .RI [ user \0...\|] .SH DESCRIPTION .C prmail prints the mail which waits for you or the specified user in the incoming mailbox file. The mailbox file is not disturbed. .PP .C prmail is functionally similar to the command: .IP .CI "cat /var/mail/" mailfile " | more" .PP or .IP .CI "cat /var/mail/" mailfile " | pg" .PP depending upon the setting of the user's .C PAGER environment variable .SH FILES .TP 20 .C /var/mail/* incoming mailbox files .SH AUTHOR .C prmail was developed by the University of California, Berkeley. .SH SEE ALSO from(1), mail(1). .\" .\" toc@\f3prmail(1)\f1:\0\0\f4prmail\f1@@@print out mail in the incoming mailbox file .\" .\" index@\f4prmail\f1 \- print out mail in the incoming mailbox file@@@\f3prmail(1)\f1 .\" index@print out mail in the incoming mailbox file@@@\f3prmail(1)\f1 .\" index@mail in the incoming mailbox file, print out@@@\f3prmail(1)\f1 .\" index@incoming mailbox file, print out mail in the@@@\f3prmail(1)\f1 .\" index@mailbox file, print out mail in the incoming@@@\f3prmail(1)\f1 .\" index@file, print out mail in the incoming mailbox@@@\f3prmail(1)\f1 .\" .\" fileset_database@prmail.1 USER-CMDS-MAN .\" $Header: prof.1,v 72.5 94/11/29 13:25:05 ssa Exp $ .TA p .TH prof 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME prof \- display profile data .SH SYNOPSIS .C prof .RC [ -tcan ] .RC [ -ox ] .RC [ -g ] .RC [ -z ] .RC [ -h ] .RC [ -s ] .RC [ -m .IR mdata\| ] .RI [ \|prog\| ] .SH DESCRIPTION .C prof interprets a profile file produced by .C monitor() (see .IR monitor (3C)). The symbol table in the object file .I prog .RC ( a.out by default) is read and correlated with a profile file .RC ( mon.out by default). For each external text symbol, the percentage of time spent executing between the address of that symbol and the address of the next is printed, together with the number of times that function was called and the average number of milliseconds per call. .PP The mutually exclusive options .CR t , .CR c , .CR a , and .C n determine the type of sorting of the output lines: .RS .TP 12 .C -t Sort by decreasing percentage of total time (default). .TP .C -c Sort by decreasing number of calls. .TP .C -a Sort by increasing symbol address. .TP .C -n Sort by symbol name in ascending collation order (see Environment Variables below). .RE .PP The mutually exclusive options .C o and .C x specify the printing of the address of each symbol monitored: .RS .TP 12 .C -o Print each symbol address (in octal) along with the symbol name. .TP .C -x Print each symbol address (in hexadecimal) along with the symbol name. .RE .PP The following options can be used in any combination: .RS .TP 12 .C -g Include non-global symbols (static functions). .TP .C -z Include all symbols in the profile range (see .IR monitor (3C)), even if associated with zero number of calls and zero time. .TP .C -h Suppress the heading normally printed on the report. (This is useful if the report is to be processed further.) .TP .C -s Print a summary of several of the monitoring parameters and statistics on the standard error output. .TP .CI -m \0mdata Use file .I mdata instead of .C mon.out as the input profile file. .RE .PP A program creates a profile file if it has been loaded using the .C cc -p option (see .IR cc (1)). This option to the .C cc command arranges for calls to .C monitor() at the beginning and end of execution (see .IR monitor (3C)). It is the call to the .C monitor command at the end of execution that causes a profile file to be written. The number of calls to a function is tallied if the .C -p option was used when the file containing the function was compiled. .PP The name of the file created by a profiled program is controlled by the environment variable .CR PROFDIR . If .C PROFDIR is not set, .C mon.out is produced in the directory current when the program terminates. If .CR PROFDIR=string , .C string/pid.progname is produced, where .I progname consists of argv[0] with any path prefix removed, and .I pid is the program's process .SM ID. If .CR PROFDIR is set to a null string, no profiling output is produced. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the collating order output by the .C -n option. .PP If .C LC_COLLATE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default. If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C prof behaves as if all internationalization variables are set to ``C'' (see .IR environ (5)). .SH WARNINGS The times reported in successive identical runs may show variances of 20% or more, because of varying cache-hit ratios due to sharing of the cache with other processes. Even if a program seems to be the only one using the machine, hidden background or asynchronous processes may blur the data. In rare cases, the clock ticks initiating recording of the program counter may ``beat'' with loops in a program, grossly distorting measurements. .PP Call counts are always recorded precisely, however. .PP Only programs that call .C exit() (see .IR exit (2)) or return from .C main cause a profile file to be produced, unless a final call to .C monitor() is explicitly coded. .PP The use of the .C cc -p option to invoke profiling imposes a limit of 600 functions that can have call counters established during program execution. For more counters, call .C monitor() directly. If this limit is exceeded, other data is overwritten and the .C mon.out file is corrupted. The number of call counters used is reported automatically by the .C prof command whenever the number exceeds 5/6 of the maximum. .SH FILES .TP 20 .C mon.out for profile .PD 0 .TP .C a.out for namelist .PD .SH SEE ALSO cc(1), exit(2), profil(2), crt0(3), end(3C), monitor(3C). .SH STANDARDS CONFORMANCE .CR prof ": SVID2, SVID3, XPG2" .\" .\" index@\f4prof\f1 \- display monitor profile data@@@\f3prof(1)\f1 .\" index@display monitor profile data@@@\f3prof(1)\f1 .\" index@monitor profile data, display@@@\f3prof(1)\f1 .\" index@profile data, display monitor@@@\f3prof(1)\f1 .\" .\" toc@\f3prof(1)\f1:\0\0\f4prof\f1@@@display profile data .\" .\" fileset_database@prof.1 USER-CMDS-MAN .\" $Header: prs.1,v 76.1 95/07/10 17:08:30 ssa Exp $ .TA p .TH prs 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME prs \- print and summarize an \s-1SCCS\s+1 file .SH SYNOPSIS .C prs .RC [ -d\0 \c .RI \| dataspec \|] .RC [ -r\c .RI [ \|\s-1SID\s0\| ]\|] .RC [ -e ] .RC [ -l ] .RC [ -c\0 \c .RI \| cutoff \|] .RC [ -a ] .IR file \0... .SH DESCRIPTION The .C prs command prints, on the standard output, parts or all of an .SM SCCS file (see .IR sccsfile (4)) in a user-supplied format. If a directory is named, .C prs behaves as though each file in the directory were specified as a named file, except that non-\c .SM SCCS files (last component of the path name does not begin with .CR s. ), and unreadable files are silently ignored. If a name of .C - is given, the standard input is read; each line of the standard input is taken to be the name of an .SM SCCS file or directory to be processed; non-\c .SM SCCS files and unreadable files are silently ignored. A .C -- on the command line implies that all following arguments are file/directory names. .PP Arguments to .CR prs , which can appear in any order, consist of options and file names. .SS Options All of the described options apply independently to each named file: .RS .TP 15 .CR -d\0 \f2dataspec\f1 Used to specify the output data specification. .I dataspec is a string consisting of .SM SCCS file .I "data keywords" (see Data Keywords below) interspersed with optional user-supplied text. .TP .CR -r [\f2\s-1SID\s0\f1] Used to specify the .IR S "CCS " ID entification .SM .RI ( SID ) string of a delta for which information is desired. If no .SM .I SID is specified, the .SM .I SID of the most recently created delta is assumed. If an .SM .I SID is specified, it must agree exactly with an .SM .I SID in the file (that is, the .SM .I SID structure used by .C get does not work here \(em see .IR get (1)). .TP .C -e Requests information for all deltas created .I earlier than and including the delta designated via the .C -r option or the date given by the .C -c option. .TP .C -l Requests information for all deltas created .I later than and including the delta designated via the .C -r option or the date given by the .C -c option. .TP .CR -c\0 \f2cutoff\f1 Cutoff date-time, in the form .RS .IP YY\|[\|MM\|[\|DD\|[\|HH\|[\|MM\|[SS\|]\|]\|]\|]\|] .RE .IP Units omitted from the date-time default to their maximum possible values. Thus, .C -c7502 is equivalent to .CR -c750228235959 . One or more non-numeric characters can be used to separate the various 2-digit segments of the cutoff date (for example .CR "-c77/2/2 9:22:25" ). .TP .C -a Requests printing of information for both removed, i.e., delta type = .IR R , (see .IR rmdel (1)) and existing, that is, delta type = .IR D , deltas. If the .C -a option is not specified, information is provided for existing deltas only. .RE .PP If no option letters (or only .CR -a ) are given, .C prs prints the file name using the default .I dataspec and the .C -e option. This produces information on all deltas. .SS "Data Keywords" Data keywords specify which parts of an .SM SCCS file are to be retrieved and output. All parts of an .SM SCCS file (see .IR sccsfile (4)) have an associated data keyword. There is no limit on the number of times a data keyword can appear in a .IR dataspec . .PP The information printed by .C prs consists of: (1) the user-supplied text; and (2) appropriate values (extracted from the .SM SCCS file) substituted for the recognized data keywords in the order of appearance in the .IR dataspec . The format of a data keyword value is either .I Simple (S), in which keyword substitution is direct, or .I "Multi-line" (M), in which keyword substitution is followed by a carriage return. .PP User-supplied text is any text other than recognized data keywords. Escapes can be used as follows: .IP .TS tab(;); l c l c. backslash;\e\e;form feed;\ef backspace;\eb;new-line;\en carriage-return;\er;single quote;\e\' colon;\e:;tab;\et .TE .PP The default .I dataspec is: .IP ":Dt:\et:DL:\enMRs:\en:MR:\s-1COMMENTS\s0:\en:C:" .PP .ift \{.br .bp\} .TS center ; cfB s s s s cfB lBw(1.9i) cB cB cB cfB lBw cB cB cB cf4 l c c c . \s-1SCCS\s0 File Data Keywords .sp .2v \& \& File Keyword Data Item Section Value Fmt _ :Dt: Delta information Delta Table See below* S :DL: Delta line statistics " \f3:Li:/:Ld:/:Lu:\fP S :Li: Lines inserted by Delta " nnnnn S :Ld: Lines deleted by Delta " nnnnn S :Lu: Lines unchanged by Delta " nnnnn S :DT: Delta type " \f2D\fP or \f2R\fP S :I: \s-1SCCS ID\s0 string \s-1(SID)\s0 " \f3:R:.:L:.:B:.:S:\fP S :R: Release number " nnnn S :L: Level number " nnnn S :B: Branch number " nnnn S :S: Sequence number " nnnn S :D: Date Delta created " \f3:Dy:/:Dm:/:Dd:\fP S :Dy: Year Delta created " nn S :Dm: Month Delta created " nn S :Dd: Day Delta created " nn S :T: Time Delta created " \f3:Th:::Tm:::Ts:\fP S :Th: Hour Delta created " nn S :Tm: Minutes Delta created " nn S :Ts: Seconds Delta created " nn S :P: Programmer who created Delta " logname S :DS: Delta sequence number " nnnn S :DP: Predecessor Delta seq-no. " nnnn S :DI: T{ Seq # of deltas incl, excl, ign T} " \f3:Dn:/:Dx:/:Dg:\fP S :Dn: Deltas included (seq #) " \f3:DS: :DS:\|...\fP S :Dx: Deltas excluded (seq #) " \f3:DS: :DS:\|...\fP S :Dg: Deltas ignored (seq #) " \f3:DS: :DS:\|...\fP S :MR: MR numbers for delta " text M :C: Comments for delta " text M :UN: User names User name text M :FL: Flag list Flags text M :Y: Module type flag " text S :MF: MR validation flag " \f2yes\fP or \f2no\fP S :MP: MR validation pgm name " text S :KF: Keyword error/warning flag " \f2yes\fP or \f2no\fP S :KV: Keyword validation string " text S :BF: Branch flag " \f2yes\fP or \f2no\fP S :J: Joint edit flag " \f2yes\fP or \f2no\fP S :LK: Locked releases " \f3:R:\|...\fP S :Q: User defined keyword " text S :M: Module name " text S :FB: Floor boundary " \f3:R:\fP S :CB: Ceiling boundary " \f3:R:\fP S :Ds: Default \s-1SID\s0 " \f3:I:\fP S :ND: Null delta flag " \f2yes\fP or \f2no\fP S :FD: File descriptive text Comments text M :BD: Body Body text M :GB: Gotten body " text M :W: A form of \f2what\fP(1) string N/A \f3:Z::M:\et:I:\fP S :A: A form of \f2what\fP(1) string N/A \f3:Z::Y: :M: :I::Z:\fP S :Z: \f2what\fP(1) string delimiter N/A \f3@\&(#)\fP S :F: SCCS file name N/A text S :PN: SCCS file path name N/A text S .TE .IP * \f3:Dt: = :DT: :I: :D: :T: :P: :DS: :DP:\fP .PP If no option letters (or only .CR -a ) are given, .C prs prints the file name, using the default .IR dataspec , and the .C -e option; thus, information on all deltas is produced. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of dataspec as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C prs behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH DIAGNOSTICS Use .IR sccshelp (1) for explanations. .SH EXAMPLES The entry .IP .C "prs \-d""Users and/or user IDs for :F: are :\en:UN:"" s.file" .PP may produce on the standard output: .IP .C Users and/or user IDs for s.file are: .br .C xyz .br .C 131 .br .C abc .PP The entry .IP .C "prs \-d""Newest delta for pgm :M:: :I: Created :D: By :P:"" \-r s.file" .PP may produce on the standard output: .IP .C Newest delta for pgm main.c: 3.7 Created 77/12/1 By cas .fi .PP As a .I "special case" (when no specifications for selecting or printing are given) .IP .C prs s.file .PP may produce on the standard output: .IP .RS .nf .C D 1.1 77/12/1 00:00:00 cas 1 000000/00000/00000 .C MRs: .C bl78-12345 .C bl79-54321 .C COMMENTS: .C "this is the comment line for s.file initial delta" .fi .RE .PP for each delta table entry of the ``D'' type. The only option argument allowed to be used with the .I "special case" is the .CR -a option. .PP .SH FILES .RE .C /tmp/pr????? .i0 .SH SEE ALSO admin(1), delta(1), get(1), sccshelp(1), sccsfile(4). .br .SH STANDARDS CONFORMANCE .CR prs ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4prs\f1 \- print and summarize an SCCS file@@@\f3prs(1)\f1 .\" index@\f1SCCS: print and summarize an SCCS file@@@\f3prs(1)\f1 .\" index@\f1print and summarize an SCCS file@@@\f3prs(1)\f1 .\" index@\f1files: print and summarize an SCCS file@@@\f3prs(1)\f1 .\" index@\f1summarize and print an SCCS file@@@\f3prs(1)\f1 .\" .\" toc@\f3prs(1)\f1:\0\0\f4prs\f1@@@print and summarize an \s-1SCCS\s+1 file .\" .\" $Header: ps.1,v 76.1 95/07/24 16:21:54 ssa Exp $ .TA p .TH ps 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ps \- report process status .SH SYNOPSIS .CR ps .RC [ \-adeflP ] .RC [ \-g .IR grplist ] .RC [ \-p .IR proclist ] .RC [ \-R .IR prmgrplist ] .RC [ \-t .IR termlist ] .RC [ \-u .IR uidlist ] .SH XPG4 SYNOPSIS .CR ps .RC [ \-aAcdefHjlP ] .RC [ \-C .IR cmdlist ] .RC [ \-g .IR grplist ] .RC [ \-G .IR gidlist ] .RC [ \-n .IR namelist ] .RC [ \-o .IR format ] .RC [ \-p .IR proclist ] .RC [ \-R .IR prmgrplist ] .RC [ \-s .IR sidlist ] .RC [ \-t .IR termlist ] .RC [ \-u .IR uidlist ] .RC [ \-U .IR uidlist ] .SH DESCRIPTION .CR ps prints information about selected processes. Use options to specify which processes to select and what information to print about them. .SS Process Selection Options .PP Use the following options to choose which processes should be selected. .PP NOTE: If an option is used in both the default (standard HP-UX) and XPG4 environments, the description provided here documents the default behavior. Refer to the .CR UNIX95 variable under EXTERNAL INFLUENCES for additional information on XPG4 behavior. .RS .TP 15 (none) Select those processes associated with the current terminal. .TP .CR \-A (XPG4 Only.) Select all processes. (Synonym for .CR \-e .) .TP .CR \-a Select all processes except process group leaders and processes not associated with a terminal. .TP .CI \-C \0cmdlist (XPG4 Only.) Select processes executing a command with a basename given in .IR cmdlist . .TP .CR \-d Select all processes except process group leaders. .TP .CR \-e Select all processes. .TP .CI \-g \0grplist Select processes whose process group leaders are given in .IR grplist . .TP .CI \-G \0gidlist (XPG4 Only.) Select processes whose real group ID numbers or group names are given in .IR gidlist . .TP .CI \-n \0namelist (XPG4 Only.) This option is ignored; its presence is allowed for standards compliance. .TP .CI \-p \0proclist Select processes whose process ID numbers are given in .IR proclist . .TP .CI \-R \0prmgrplist Select processes belonging to PRM process resource groups whose names or ID numbers are given in .IR prmgrplist . See DEPENDENCIES. .TP .CI \-s \0sidlist (XPG4 Only.) Select processes whose session leaders are given in .IR sidlist . (Synonym for .CR \-g ). .TP .CI \-t \0termlist Select processes associated with the terminals given in .IR termlist . Terminal identifiers can be specified in one of two forms: the device's file name (such as .CR tty04 ) or if the device's file name starts with .CR tty , just the rest of it (such as .CR 04 ). If the device's file is in a directory other than .CR /dev or .CR /dev/pty , the terminal identifier must include the name of the directory under .CR /dev that contains the device file (such as .CR pts/5 ). .TP .CI \-u \0uidlist Select processes whose effective user ID numbers or login names are given in .IR uidlist . .TP .CI \-U \0uidlist (XPG4 Only.) Select processes whose real user ID numbers or login names are given in .IR uidlist . .RE .PP If any of the .CR \-a , .CR \-A , .CR \-d , or .CR \-e options is specified, the .CR \-C , .CR \-g , .CR \-G , .CR \-p , .CR \-R , .CR \-t , .CR \-u , and .CR \-U options are ignored. .PP If more than one of .CR \-a , .CR \-A , .CR \-d , and .CR \-e are specified, the least restrictive option takes effect. .PP If more than one of the .CR \-C , .CR \-g , .CR \-G , .CR \-p , .CR \-R , .CR \-t , .CR \-u , and .CR \-U options are specified, processes will be selected if they match any of the options specified. .PP The lists used as arguments to the .CR \-C , .CR \-g , .CR \-G , .CR \-p , .CR \-R , .CR \-t , .CR \-u , and .CR \-U options can be specified in one of two forms: .RS .TP 3 \(bu A list of identifiers separated from one another by a comma. .TP \(bu A list of identifiers enclosed in quotation marks (\c .C """\c" ) and separated from one another by a comma and/or one or more spaces. .RE .SS Output Format Options Use the following options to control which columns of data are included in the output listing. The options are cumulative. .RS .TP 15 .\" PID TTY TIME COMMAND (none) The default columns are: .CR pid , .CR tty , .CR time , and .CR comm , in that order. .TP .\" UID PID PPID C STIME TTY TIME COMMAND .CR \-f Show columns .CR user , .CR pid , .CR ppid , .CR cpu , .CR stime , .CR tty , .CR time , and .CR args , in that order. .TP .\" F S UID PID PPID C PRI NI ADDR SZ WCHAN TTY TIME COMD .CR \-l Show columns .CR flags , .CR state , .CR uid , .CR pid , .CR ppid , .CR cpu , .CR intpri , .CR nice , .CR addr , .CR sz , .CR wchan , .CR tty , .CR time , and .CR comm , in that order. .TP .CR \-fl Show columns .CR flags , .CR state , .CR user , .CR pid , .CR ppid , .CR cpu , .CR intpri , .CR nice , .CR addr , .CR sz , .CR wchan , .CR stime , .CR tty , .CR time , and .CR args , in that order. .TP .CR \-c (XPG4 Only.) Remove columns .CR cpu and .CR nice ; replace column .CR intpri with columns .CR cls and .CR pri . .TP .CR \-j (XPG4 Only.) Add columns .CR pgid and .CR sid after column .CR ppid (or .CR pid , if .CR ppid is not being displayed). .TP .CR \-P Add column .CR prmid (for .CR \-l ) or .CR prmgrp (for .CR \-f or .CR \-fl ) immediately before column .CR pid . See DEPENDENCIES. .TP .CI \-o \0format (XPG4 Only.) .I format is a comma- or space-separated list of the columns to display, in the order they should be displayed. (Valid column names are listed below.) A column name can optionally be followed by an equals sign .RC ( = ) and a string to use as the heading for that column. (Any commas or spaces after the equals sign will be taken as a part of the column heading; if more columns are desired, they must be specified with additional .CR \-o options.) The width of the column will be the greater of the width of the data to be displayed and the width of the column heading. If an empty column heading is specified for every heading, no heading line will be printed. This option overrides options .CR \-c , .CR \-f , .CR \-j , .CR \-l , and .CR \-P ; if they are specified, they are ignored. .TP .CR \-H (XPG4 Only.) Shows the process hierarchy. Each process is displayed under its parent, and the contents of the .CR args or .CR comm column for that process is indented from that of its parent. Note that this option is expensive in both memory and speed. .RE .PP The column names and their meanings are given below. Except where noted, the default heading for each column is the uppercase form of the column name. .RS .TP 15 .CR addr The memory address of the process, if resident; otherwise, the disk address. .TP .CR args The command line given when the process was created. This column should be the last one specified, if it is desired. Only a subset of the command line is saved by the kernel; as much of the command line will be displayed as is available. The output in this column may contain spaces. The default heading for this column is .CR COMMAND if .CR \-o is specified and .CR CMD otherwise. .TP .CR cls Process scheduling class, see .IR rtsched (1). .TP .CR comm The command name. The output in this column may contain spaces. The default heading for this column is .CR COMMAND if .CR \-o is specified and .CR CMD otherwise. .TP .CR cpu Processor utilization for scheduling. The default heading for this column is .CR C . .TP .CR etime Elapsed time of the process. The default heading for this column is .CR ELAPSED . .TP .CR flags Flags (octal and additive) associated with the process: .RS .RS .TP .PD 0 .CR \00 Swapped .TP .CR \01 In core .TP .CR \02 System process .TP .CR \04 Locked in core (e.g., for physical I/O) .TP .CR 10 Being traced by another process .TP .CR 20 Another tracing flag .PD .RE .RE .IP The default heading for this column is .CR F . .TP .CR intpri The priority of the process as it is stored internally by the kernel. This column is provided for backward compatibility and its use is not encouraged. .TP .CR gid The group ID number of the effective process owner. .TP .CR group The group name of the effective process owner. .TP .CR nice Nice value; used in priority computation (see .IR nice (1)). The default heading for this column is .CR NI . .TP .CR pcpu The percentage of CPU time used by this process during the last scheduling interval. The default heading for this column is .CR %CPU . .TP .CR pgid The process group ID number of the process group to which this process belongs. .TP .CR pid The process ID number of the process. .TP .CR ppid The process ID number of the parent process. .TP .CR pri The priority of the process. The meaning of the value depends on the process scheduling class; see .CR cls , above, and .IR rtsched (1). .TP .CR prmid The PRM process resource group ID number. .TP .CR prmgrp The PRM process resource group name. .TP .CR rgid The group ID number of the real process owner. .TP .CR rgroup The group name of the real process owner. .TP .CR ruid The user ID number of the real process owner. .TP .CR ruser The login name of the real process owner. .TP .CR sid The session ID number of the session to which this process belongs. .TP .CR state The state of the process: .RS .RS .TP .PD 0 .CR 0 Nonexistent .TP .CR S Sleeping .TP .CR W Waiting .TP .CR R Running .TP .CR I Intermediate .TP .CR Z Terminated .TP .CR T Stopped .TP .CR X Growing .PD .RE .RE .IP The default heading for this column is .CR S . .TP .CR stime Starting time of the process. If the elapsed time is greater than 24 hours, the starting date is displayed instead. .TP .CR sz The size in physical pages of the core image of the process, including text, data, and stack space. Physical page size is defined by .CR _SC_PAGE_SIZE in the header file .CR (see .IR sysconf (2) and .IR unistd (5)). .TP .CR time The cumulative execution time for the process. .TP .CR tty The controlling terminal for the process. The default heading for this column is .CR TT if .CR -o is specified and .CR TTY otherwise. .TP .CR uid The user ID number of the effective process owner. .TP .CR user The login name of the effective process owner. .TP .CR vsz The size in kilobytes (1024 byte units) of the core image of the process. See column .CR sz , above. .TP .CR wchan The event for which the process is waiting or sleeping; if there is none, a hyphen (-) is displayed. .RE .SS Notes .CR ps prints the command name and arguments given at the time of the process was created. If the process changes its arguments while running (by writing to its .I argv array), these changes are not displayed by .CR ps . .PP A process that has exited and has a parent, but has not yet been waited for by the parent, is marked .CR (see .BR "zombie process" in .IR exit (2)). .PP The time printed in the .CR stime column, and used in computing the value for the .CR etime column, is the time when the process was forked, .I not the time when it was modified by .CI exec * () \f1. .PP To make the .CR ps output safer to display and easier to read, all control characters in the .CR comm and .CR args columns are displayed as "visible" equivalents in the customary control character format, .CI ^ x\f1. .SH EXTERNAL INFLUENCES .SS Environment Variables .CR UNIX95 specifies to use the XPG4 behavior for this command. The changes for XPG4 include support for the entire option set specified above and include the following behavioral changes: .RS .TP 2 \(bu The .CR TIME column format changes from .CR "mmmm:ss" to .CR "[dd-]hh:mm:ss" . .TP \(bu When the .CR comm , .CR args , .CR user , and .CR prmgrp fields are included by default or the .CR -f or .CR -l flags are used, the column headings of those fields change to .CR CMD , .CR CMD , .CR USER , and .CR PRMGRP , respectively. .TP \(bu .CR -a , .CR -d , and .CR -g will select processes based on session rather than on process group. .TP \(bu The uid or user column displayed by .CR -f or .CR -l will display effective user rather than real user. .TP \(bu The .CR -u option will select users based on effective UID rather than real UID. .TP \(bu The .CR -C and .CR -H options, while they are not part of the XPG4 standard, are enabled. .RE .PP .CR LC_TIME determines the format and contents of date and time strings. If it is not specified or is null, it defaults to the value of .CR LANG . .PP If .CR LANG is not specified or is null, it defaults to .CR C (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to .CR C (see .IR environ (5)). .SS International Code Set Support Single-byte character code sets are supported. .SH EXAMPLES Generate a full listing of all processes currently running on your machine: .IP .C "ps \-ef" .PP To see if a certain process exists on the machine, such as the .CR cron clock daemon, check the far right column for the command name, .CR cron , or try .IP .C "ps \-f \-C cron" .SH WARNINGS Things can change while .CR ps is running; the picture it gives is only a snapshot in time. Some data printed for defunct processes is irrelevant. .PP If two special files for terminals are located at the same select code, that terminal may be reported with either name. The user can select processes with that terminal using either name. .PP Users of .C ps must not rely on the exact field widths and spacing of its output, as these will vary depending on the system, the release of HP-UX, and the data to be displayed. .SH DEPENDENCIES .SS HP Process Resource Manager The .CR \-P and .CR \-R options require the optional HP Process Resource Manager (PRM) software to be installed and configured. See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for the definition of "process resource group." .PP If HP PRM is not installed and configured and .CR \-P or .CR \-R is specified, a warning message is displayed and (for .CR \-P ) hyphens (-) are displayed in the .CR prmid and .CR prmgrp columns. .SH FILES .PD 0 .TP 35 .CR /dev Directory of terminal device files .TP .CR /etc/passwd User ID information .TP .CR /var/adm/ps_data Internal data structure .PD .SH SEE ALSO kill(1), nice(1), acctcom(1M), exec(2), exit(2), fork(2), sysconf(2), unistd(5). .PP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide". .SH STANDARDS COMPLIANCE .CR ps ": SVID2, XPG2, XPG3, XPG4" .\" .\" index@\f4ps\f1 \- report process status@@@\f3ps(1)\f1 .\" index@\f1report process status@@@\f3ps(1)\f1 .\" index@\f1process status, report@@@\f3ps(1)\f1 .\" index@\f1status, report process@@@\f3ps(1)\f1 .\" index@\f1list current processes@@@\f3ps(1)\f1 .\" index@\f1current processes, list@@@\f3ps(1)\f1 .\" index@\f1PRM@@@\f2see \f1Process Resource Manager .\" index@\f1Process Resource Manager@@@\f3ps(1)\f1 .\" .\" toc@\f3ps(1)\f1:\0\0\f4ps\f1@@@report process status .\" $Header: ptx.1,v 72.5 94/05/24 16:17:20 ssa Exp $ .TA p .TH ptx 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ptx \- permuted index .SH SYNOPSIS .C ptx .RI [ \|options\| ] .RI [ \|input \0[ \|output\| ]\|] .SH DESCRIPTION .C ptx generates the file .I output that can be processed with a text formatter to produce a permuted index of file .I input (standard input and output default). It has three phases: the first does the permutation, generating one line for each keyword in an input line. The keyword is rotated to the front. The permuted file is then sorted (see .IR sort (1) and Environment Variables below). Finally, the sorted lines are rotated so the keyword comes at the middle of each line. .C ptx output is in the form: .br .IP \&\f3.xx\fP "tail" "before keyword" "keyword and after" "head" .PP where .C .xx is assumed to be an .C nroff or .C troff macro provided by the user, or provided by the .C mptx macro package (see .SM NOTES below). The .I "before keyword" and .I "keyword and after" fields incorporate as much of the line as will fit around the keyword when it is printed. .I tail and .IR head , at least one of which is always the empty string, are wrapped-around pieces small enough to fit in the unused space at the opposite end of the line. .PP The following .I options can be applied: .RS .TP 12 .C -f Fold uppercase and lowercase letters for sorting. .TP .C -t Prepare the output for the phototypesetter by using a line length of 100. .TP .CI -w \0n Use the next argument, .IR n , as the length of the output line. The default line length is 72 characters for .C nroff and 100 for .CR troff . .TP .CI -g \0n Use the next argument, .IR n , as the number of characters that .C ptx will reserve in its calculations for each gap among the four parts of the line as finally printed. The default gap is 3. .TP .CI -o \0only Use as keywords only the words given in the .I only file. .TP .CI -i \0ignore Do not use as keywords any words given in the .I ignore file. If the .C -i and .C -o options are missing, use .C /usr/lib/eign as the .I ignore file. .TP .CI -b \0break Use the characters in the .I break file to separate words. Tab, new-line, and space characters are .I always used as break characters. Punctuation characters are treated as part of the word in the absence of this option. .TP .C -r Take any leading non-blank characters of each input line to be a reference identifier (as to a page or chapter), separate from the text of the line. Attach that identifier as a 5th field on each output line. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the order in which the output is sorted. .PP .C LC_CTYPE determines the default break characters. .PP If .C LC_COLLATE or .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C ptx behaves as if all internationalization variables are set to ``C'' (see .IR environ (5)). .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS Line length counts do not account for overstriking or proportional spacing. .PP Lines containing tildes .RC ( ~ ) are botched because .C ptx uses that character internally. .SH FILES .C /usr/lib/eign .br .C /usr/bin/sort .br .C /usr/share/lib/tmac/tmac.ptx .SH NOTES The .C mptx macro package is not provided as part of the .SM HP-UX operating system. It is part of the Documenters Work Bench (\c .SM DWB\c ) software package originally developed by .SM AT&T which has been ported to HP\|9000 systems by various third-party software suppliers including Elan Computer Group, Inc. of Mountain View California and others. .PP Permuted indexes produced by using .C ptx usually have a 4-column format that some users prefer and others dislike greatly. The two-column format index provided in this manual is created by processing index entries that are hidden as comments at the end of each manual entry file. .SH SEE ALSO nroff(1), mm(5). .\" .\" index@\f4ptx\f1 \- generate permuted index@@@\f3ptx(1)\f1 .\" index@generate permuted index@@@\f3ptx(1)\f1 .\" index@permuted index, generate@@@\f3ptx(1)\f1 .\" index@index, generate permuted@@@\f3ptx(1)\f1 .\" .\" toc@\f3ptx(1)\f1:\0\0\f4ptx\f1@@@permuted index .\" .\" fileset_database@ptx.1 USER-CMDS-MAN .\" $Header: tty.1,v 76.1 95/08/07 10:06:18 ssa Exp $ .TA t .TH tty 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tty, pty \- get the name of the terminal .SH SYNOPSIS .C tty .RC [ -s ] .PP .C pty .RC [ -s ] .SH DESCRIPTION .C tty and .C pty print the path name of the user's terminal. The .C -s option inhibits printing of the terminal path name and any diagnostics, providing a means to test only the exit code. .SH RETURN VALUE Exit status codes for .C tty are: .RS .TP 8 .B 2 Invalid options were specified, .PD 0 .TP .B 1 The standard input is not a terminal or pseudo-terminal, .TP .B 0 The standard input is a terminal or pseudo-terminal. .PD .RE .PP Exit status codes for .C pty are: .RS .TP 8 .PD 0 .B 2 Invalid options were specified, .TP .B 1 The standard input is not a pseudo-terminal, .TP .B 0 The standard input is a pseudo-terminal. .PD .RE .SH DIAGNOSTICS .TP 10 .C "not a tty" standard input is not a terminal or pseudo-terminal for .CR tty . .TP .C "not a pty" standard input is not a pseudo-terminal for .CR pty . .SH AUTHOR .C tty was developed by AT&T. .C pty was developed by HP. .SH STANDARDS CONFORMANCE .CR tty ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" toc@\f3tty(1)\f1:\0\0\f4tty\f1, \f4pty\f1@@@get the name of the terminal .\" toc@\f4pty\f1: get the name of the pseudo-terminal@@@see \f3tty(1)\f1 .\" .\" index@\f4tty\f1 \- get the name of the user's terminal or pseudo-terminal@@@\f3tty(1)\f1 .\" index@\f4pty\f1 \- get the name of the user's pseudo-terminal@@@\f3tty(1)\f1 .\" index@get name of the user's terminal or pseudo-terminal@@@\f3tty(1)\f1 .\" index@name of the user's terminal or pseudo-terminal, get@@@\f3tty(1)\f1 .\" index@user's terminal or pseudo-terminal, get name of@@@\f3tty(1)\f1 .\" index@terminal or pseudo-terminal, get name of user's@@@\f3tty(1)\f1 .\" index@pseudo-terminal, get name of user's terminal or@@@\f3tty(1)\f1 .\" .\" links@tty.1 pty.1 .\" .\" fileset_database@tty.1 USER-CMDS-MAN .\" $Header: pwd.1,v 76.2 95/08/04 16:19:05 ssa Exp $ .TA p .TH pwd 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pwd \- working directory name .SH SYNOPSIS .C pwd .SH DESCRIPTION .C pwd prints the path name of the working (current) directory. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C pwd behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS .TP 8 .C Cannot open .. .PD 0 .TP .C Read error in .. Possible file system trouble; contact system administrator. .PD .TP .C "pwd: cannot access parent directories" Current directory has been removed (usually by a different process). Use .C cd command to move to a valid directory (see .IR cd (1)). .SH EXAMPLES This command lists the path of the current working directory. If your home directory were .C /mnt/staff and the command .C cd camp/nevada were executed from the home directory, typing .C pwd would produce the following: .IP .C /mnt/staff/camp/nevada .SH AUTHOR .C pwd was developed by AT&T and HP. .SH SEE ALSO cd(1). .SH STANDARDS CONFORMANCE .CR pwd ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" toc@\f3pwd(1)\f1:\0\0\f4pwd\f1@@@working directory name .\" .\" index@\f4pwd\f1 \- print working directory name@@@\f3pwd(1)\f1 .\" index@\f1print working directory name@@@\f3pwd(1)\f1 .\" index@\f1directory: print working directory name@@@\f3pwd(1)\f1 .\" index@\f1working directory name, print@@@\f3pwd(1)\f1 .\" index@\f1directory name, print working@@@\f3pwd(1)\f1 .\" index@\f1name, print working directory@@@\f3pwd(1)\f1 .\" .\" $Header: pwget.1,v 72.4 94/09/08 15:04:02 ssa Exp $ .TA p .TH pwget 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pwget, grget \- get password and group information .SH SYNOPSIS .C pwget .RC [ -n .I name \(or .C -u .IR uid\| ] .PP .C grget .RC [ -n .I name \(or .C -g .IR gid\| ] .SH DESCRIPTION .C pwget and .C grget locate and display information from .C /etc/passwd and .CR /etc/group . .PP The standard output of .C pwget contains lines of colon-separated password information whose format is the same as that used in the .C /etc/passwd file (see .IR passwd (4)). .PP The standard output of .C grget contains lines of colon-separated group information whose format is the same as that used in the .C /etc/group file (see .IR group (4)). .PP With no options, .C pwget and .C grget get all entries with .C getpwent() or .C getgrent() respectively, (see .IR getpwent (3C) and .IR getgrent (3C)), and output a line for each entry found. .SS Options When an option is given, only a single entry is printed. .PP The options for .I pwget are: .RS .TP 15 .CI -n \0name Output the first entry that matches .I name using .C getpwnam() (see .IR getpwent (3C)). .TP .CI -u \0uid Output the first entry that matches .I uid using .C getpwuid() (see .IR getpwent (3C)). .RE .PP The options for .C grget are: .RS .TP 15 .CI -n \0name Output the first entry that matches .I name using .C getgrnam() (see .IR getgrent (3C)). .TP .CI -g \0gid Output the first entry that matches .I gid using .C getgrgid() (see .IR getgrent (3C)). .RE .SH NETWORKING FEATURES .SS \s-1NFS\s0 If Network Information System .SM (NIS) is in use, these commands provide password and group information based on the .SM NIS version of the password and group databases in addition to the local password and group files. .SH RETURN VALUE These commands return .C 0 upon success, .C 1 when a specific search fails, and .C 2 upon error. .SH DEPENDENCIES .SS \s-1NFS\s+1: .SM WARNING: If the Network Information System network database is in use and the .SM NIS client daemon .RC ( ypbind ) is not bound to a .SM NIS server daemon (see .IR ypserv (1M)), these utilities will wait until such a binding is established. These commands can be terminated in this condition by sending a .C SIGINT signal to the process (see .IR kill (1)). .PP See .IR ypmatch (1), and .IR ypserv (1M). .SH AUTHOR .C pwget and .C grget were developed by HP. .SH FILES .TP 20 .C /etc/group local group data file .TP .C /etc/passwd local password data file .SH SEE ALSO getgrent(3C), getpwent(3C), group(4), passwd(4). .\" .\" index@\f4pwget\f1 \- get password information@@@\f3pwget(1)\f1 .\" index@\f4grget\f1 \- get group information@@@\f3pwget(1)\f1 .\" index@password information, get (\f4pwget\f1)@@@\f3pwget(1)\f1 .\" index@group information, get (\f4grget\f1)@@@\f3pwget(1)\f1 .\" .\" toc@\f3pwget(1)\f1:\0\0\f4pwget\f1, \f4grget\f1@@@get password and group information .\" toc@\f4grget\f1: get password and group information@@@see \f3pwget(1)\f1 .\" .\" links@pwget.1 grget.1 .\" .\" fileset_database@pwget.1 USER-CMDS-MAN .\" $Header: quota.1,v 76.1 95/07/10 17:09:26 ssa Exp $ .TA q .TH quota 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME quota \- display disk usage and limits .SH SYNOPSIS .CR quota .RC \|[ -v ]\| .RI \|[ user \0... ]\| .SH DESCRIPTION The .CR quota command displays the disk usage and limits for one or more .IR user s. Without the .CR -v option, it displays information only when the usage exceeds the limits. .PP .IR user is a user name or a numeric .SM UID\s0. The default is the login user name. .PP Only users with appropriate privileges can view the limits of other users. .SS Options The .CR quota command recognizes the following option: .RS .TP 15 .CR -v Display the statistics whether they exceed limits or not. Note that no usage statistics exist if no quota is set. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C quota behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH AUTHOR Disk Quotas were developed by the University of California, Berkeley, Sun Microsystems, Inc., and HP. .SH FILES .TP 20 .IC directory /quotas Quota statistics static storage for a file system, where .I directory is the root of the file system as specified to the .CR mount command (see .IR mount (1M)). .PD 0 .TP .CR /etc/mnttab List of currently mounted file systems .PD .SH SEE ALSO quota(5). .\" .\" toc@\f3quota(1)\f1:\0\0\f4quota\f1@@@display disk usage and limits .\" .\" index@\f4quota\f1 \- display disk usage and limits@@@\f3quota(1)\f1 .\" index@\f1display disk usage and limits@@@\f3quota(1)\f1 .\" index@\f1disk usage and limits, display@@@\f3quota(1)\f1 .\" index@\f1file system: display disk usage and limits quota@@@\f3quota(1)\f1 .\" .\" $Header: ranlib.1,v 74.1 95/05/10 21:55:43 ssa Exp $ .TA r .TH ranlib 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ranlib \- regenerate archive symbol table .SH SYNOPSIS .C ranlib .I archive ... .SH DESCRIPTION .C ranlib regenerates the symbol tables of the specified archives. It is equivalent to executing .C ar qs archive on each of the archives. After using the .C z modifier of .CR ar , the symbol table of an archive must be regenerated before it can be used. .SH EXTERNAL INFLUENCES .SS Environment Variables .PP The following internationalization variables affect the execution of .CR ranlib : .PP .C LANG .RS Determines the locale category for native language, local customs and coded character set in the absence of .C LC_ALL and other .C LC_* environment variables. If .C LANG is not specified or is set to the empty string, a default of .C C (see .IR lang (5)) is used instead of .CR LANG . .RE .PP .C LC_ALL .RS Determines the values for all locale categories and has precedence over .C LANG and other .C LC_* environment variables. .RE .PP .C LC_CTYPE .RS Determines the locale category for character handling functions. .RE .PP .C LC_MESSAGES .RS Determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error. .RE .PP .C LC_NUMERIC .RS Determines the locale category for numeric formatting. .RE .PP .C LC_TIME .RS Determines the format and contents of date and time formatting. .RE .PP .C NLSPATH .RS Determines the location of message catalogues for the processing of .CR LC_MESSAGES . .RE .PP If any internationalization variable contains an invalid setting, .C ranlib behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .PP In addition, the following environment variable affects .CR ranlib : .PP .C TMPDIR .RS Specifies a directory for temporary files (see .IR tmpnam (3S)). .SH SEE ALSO .PD .SS System Tools: .TP 18 .IR ar(1) create archived libraries .PD .SS Miscellaneous: .TP 18 .IR ar(4) archive format .PD 0 .TP .IR strip(1) strip symbol and line number information from an object file .PD .\" .\" toc@\f3ranlib(1)\f1:\0\0\f4ranlib\f1@@@regenerate archive symbol table .\" .\" index@\f4ranlib(1)\f1 \- regenerate archive symbol table@@@\f3ranlib(1)\f1 .\" index@\f1archive symbol table, regenerate@@@\f3ranlib(1)\f1 .\" index@\f1symbol table, regenerate archive@@@\f3ranlib(1)\f1 .\" .\" $Header: rcp.1,v 72.4 94/09/22 14:16:57 ssa Exp $ .TA r .TH rcp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rcp \- remote file copy .SH SYNOPSIS .SS Copy Single File .CR rcp .RC [ -p ] .I source_file1 dest_file .SS Copy Multiple Files .CR rcp .RC [ -p ] .I source_file1 .RI [ source_file2 ]...\& .I dest_dir .SS "Copy One or More Directory Subtrees .CR rcp .RC [ -p ] .CR -r .I source_dir1 .RI [ source_dir2 ]...\& .I dest_dir .SS "Copy Files and Directory Subtrees .CR rcp .RC [ -p ] .CR -r .I file_or_dir1 .RI [ file_or_dir2 ]...\& .I dest_dir .SH DESCRIPTION The .CR rcp command copies files, directory subtrees, or a combination of files and directory subtrees from one or more systems to another. In many respects, it is similar to the .CR cp command (see .IR cp (1)). .PP To use .CR rcp , you must have read access to files being copied, and read and search (execute) permission on all directories in the directory path. .SS Options and Arguments .CR rcp recognizes the following options and arguments: .RS .TP 15 .I source_file .PD 0 .TP .I source_dir .sp -2v .PD The name of an existing file or directory on a local or remote machine that you want copied to the specified destination. Source file and directory names are constructed as follows: .RS .IP .IC user_name @ hostname : pathname /\fP\s-1filename .RE .IP or .RS .IP .IC user_name @ hostname : pathname /\fP\s-1dirname .RE .IP Component parts of file and directory names are described below. If multiple existing files and/or directory subtrees are specified .RI ( source_file1 , .IR source_file2 ,\0..., etc.), the destination must be a directory. Shell file name expansion is allowed on both local and remote systems. Multiple files and directory subtrees can be copied from one or more systems to a single destination directory with a single command. .TP .I dest_file The name of the destination file. If host name and path name are not specified, the existing file is copied into a file named .I dest_file in the current directory on the local system. If .I dest_file already exists and is writable, the existing file is overwritten. Destination file names are constructed the same way as source files except that file name expansion characters cannot be used. .TP .I dest_dir The name of the destination directory. If host name and path name are not specified, the existing file is copied into a directory named .I dest_dir in the current directory on the local system. If .I dest_dir already exists in the specified directory path (or current directory if not specified), a new directory named .I dest_dir is created underneath the existing directory named .IR dest_dir . Destination directory names are constructed the same way as source directory tree names except that file name expansion characters cannot be used. .TP .I file_or_dir If a combination of files and directories are specified for copying (either explicitly or by file name expansion), only files are copied unless the .CR -r option is specified. If the .CR -r option is present, all files and directory subtrees whose names match the specified .I file_or_dir name are copied. .TP .CR -p Preserve (duplicate) modification times and modes (permissions) of source files, ignoring the current setting of the .CR umask file creation mode mask. If this option is specified, .CR rcp preserves the sticky bit only if the target user is superuser. .IP If the .CR -p option is not specified, .CR rcp preserves the mode and owner of .I dest_file if it already exists; otherwise .CR rcp uses the mode of the source file modified by the .CR umask on the destination host. Modification and access times of the destination file are set to the time when the copy was made. .TP .CR -r Recursively copy directory subtrees rooted at the source directory name. If any directory subtrees are to be copied, .CR rcp recursively copies each subtree rooted at the specified source directory name to directory .IR dest_dir . If .I source_dir is being copied to an existing directory of the same name, .CR rcp creates a new directory .I source_dir within .I dest_dir and copies the subtree rooted at .I source_dir to .IC dest_dir / source_dir\f1. If .I dest_dir does not exist, .CR rcp creates it and copies the subtree rooted at .I source_dir to .IR dest_dir . .RE .SS Constructing File and Directory Names As indicated above, file and directory names contain one, two, or four component parts: .RS .TP 13 .I user_name Login name to be used for accessing directories and files on remote system. .TP .I hostname Hostname of remote system where directories and files are located. .TP .I pathname Absolute directory path name or directory path name relative to the login directory of user .IR user_name . .TP .I filename Actual name of source or destination file. File name expansion is allowed on source file names. .TP .I dirname Actual name of source or destination directory subtree. File name expansion is allowed on source directory names. .RE .PP Each .I file or .I directory argument is either a remote file name of the form .IC hostname : path\f1, or a local file name (with a slash .RC ( / ) before any colon .RC ( : )). .I hostname can be either an official host name or an alias (see .IR hosts (4)). If .I hostname is of the form .IC ruser @ rhost\f1, .I ruser is used on the remote host instead of the current user name. An unspecified .I path (that is, .IC hostname : \f1) refers to the remote user's login directory. If .I path does not begin with .CR / , it is interpreted relative to the remote user's login directory on .IR hostname . Shell metacharacters in remote .IR paths can be quoted with backslash .RC ( \e ), single quotes .RC ( '' ), or double quotes (\c .C """""\c" ), so that they will be interpreted remotely. .PP The .CR rcp routine does not prompt for passwords. The current local user name or any user name specified via .I ruser must exist on .I rhost and allow remote command execution via .IR remsh (1) and .IR rcmd (3). .IR remshd (1M) must be executable on the remote host. .PP Third-party transfers in the form: .IP .C "rcp ruser1@rhost1:path1 ruser2@rhost2:path2" .PP are performed as: .IP .C "remsh rhost1 -l ruser1 rcp path1 ruser2@rhost2:path2" .PP Therefore, for a such a transfer to succeed, .I ruser2 on .I rhost2 must allow access by .I ruser1 from .I rhost1 (see .IR hosts.equiv (4)). .SH WARNINGS The .CR rcp routine is confused by any output generated by commands in a .CR .cshrc file on the remote host (see .IR csh (1)). .PP Copying a file onto itself, for example: .IP .C "rcp path `hostname`:path" .PP may produce inconsistent results. The current HP-UX version of .CR rcp simply copies the file over itself. However, some implementations of .CR rcp , including some earlier HP-UX implementations, corrupt the file. In addition, the same file may be referred to in multiple ways, for example, via hard links, symbolic links, or NFS. It is not guaranteed that .CR rcp will correctly copy a file over itself in all cases. .PP Implementations of .CR rcp based on the 4.2BSD version (including the implementations of .CR rcp prior to HP-UX 7.0) require that remote users be specified as .IR rhost . ruser . If the first remote host specified in a third party transfer .RI ( rhost1 in the example below) uses this older syntax, the command must have the form: .IP .C "rcp ruser1@rhost1:path1 rhost2.ruser2:path2" .PP since the target is interpreted by .IR rhost1 . A common problem that is encountered is when two remote files are to be copied to a remote target that specifies a remote user. If the two remote source systems, .I rhost1 and .IR rhost2 , each expect a different form for the remote target, the command: .IP .C "rcp rhost1:path1 rhost2:path2 rhost3.ruser3:path3" .PP will certainly fail on one of the source systems. Perform such a transfer using two separate commands. .SH AUTHOR .CR rcp was developed by the University of California, Berkeley. .SH SEE ALSO cp(1), ftp(1), remsh(1), remshd(1M), rcmd(3), hosts(4), hosts.equiv(4). .PP .CR ftp chapter in .IR "Using Internet Services" . .\" .\" index@\f4rcp\fP \- remote file copy@@@\f3rcp(1)\fP .\" index@remote file copy@@@\f3rcp(1)\fP .\" index@file copy, remote@@@\f3rcp(1)\fP .\" index@copy files to or from remote system@@@\f3rcp(1)\fP .\" index@files: copy to or from remote system@@@\f3rcp(1)\fP .\" index@copy files to or from remote system@@@\f3rcp(1)\fP .\" .\" toc@\f3rcp(1)\fP:\0\0\f4rcp\fP@@@remote file copy .\" $Header: rcs.1,v 78.1 96/02/12 14:11:49 ssa Exp $ .TA r .TH rcs 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rcs \- change \s-1RCS\s0 file attributes .SH SYNOPSIS .C rcs .RI [ \|options\| ] .IR file \0... .SH DESCRIPTION .C rcs creates new .SM RCS files or changes attributes of existing ones. An .SM RCS file contains multiple revisions of text, an access list, a change log, descriptive text, and some control attributes. For .C rcs to work, the user's login name must be on the access list, except if the access list is empty, if the user is the owner of the file or the superuser, or if the .C -i option is present. .PP The user of the command must have read/write permission for the directory containing the .SM RCS file and read permission for the .SM RCS file itself. .C rcs creates a semaphore file in the same directory as the .SM RCS file to prevent simultaneous update. For changes, .C rcs always creates a new file. On successful completion, .C rcs deletes the old one and renames the new one. This strategy makes links to .SM RCS files useless. .PP Files ending in .C ,v are .SM RCS files; all others are working files. If a working file is given, .C rcs tries to find the corresponding .SM RCS file first in directory .CR ./RCS , then in the current directory, as explained in .IR rcsintro (5). .SS Options .C rcs recognizes the following options: .RS .TP 15 .CI -a logins Appends the login names appearing in the comma-separated list .I logins to the access list of the .SM RCS file. .TP .CI -A oldfile Appends the access list of .I oldfile to the access list of the .SM RCS file. .tr ~" .TP .CI -c~ string ~ Sets the comment leader to .IR string . .tr ~~ The comment leader is printed before every log message line generated by the keyword .C $\&Log$ during check out (see .IR co (1)). This is useful for programming languages without multi-line comments. During .C rcs -i or initial .CR ci , the comment leader is guessed from the suffix of the working file. Note, a comment leader is inserted at the beginning of each line of log information. The comment leader is determined by the suffix used with the file name, as in foo.c, or foo.sh, or foo.p. Note you can specify a different comment leader through the "rcs" command. The following table shows the comment leader associated with each file name suffix: .PP .vs +1 .TS center tab(+); lB lB lB l ln ln. SUFFIX+FILES+Comment Character _ c+c+'*' C+C Header+'*' sh+shell+'#' s+Assembly+'#' p+pascal+'*' r+ratfor+'#' e+efl+'#' l+lex+'*' y+yacc+'*' yr+yacc-rarfor+'*' ye+yacc-efl+'*' ml+mocklisp+';' mac+macro+';' f+fortran+'c' ms+ms-macros+'\' me+me-macros+'\' ""+empty suffix+'#' nil+unknown suffix+'""' .TE .vs .TP .CR -e [\|\f2logins\f1\|] Erases the login names appearing in the comma-separated list .I logins from the access list of the .SM RCS file. If .I logins is omitted, the entire access list is erased. .TP .C -i Creates and initializes a new .SM RCS file, but does not deposit any revision. If the .SM RCS file has no path prefix, .C rcs tries to place it first into the subdirectory .CR ./RCS , then into the current directory. If the .SM RCS file already exists, an error message is printed. .TP .CR -l [\|\f2rev\fP\|] Locks the revision with number .IR rev . If a branch is given, the latest revision on that branch is locked. If .I rev is omitted, the latest revision on the trunk is locked. Locking prevents overlapping changes. A lock is removed with .C ci or .C rcs -u (see below). .TP .C -L Sets locking to .CR strict . Strict locking means that the owner of an .SM RCS file is not exempt from locking for check in. This option should be used for files that are shared. .TP .CR -n \f2name\fP[ : [\|\f2rev\f1\|]\|] Associates the symbolic name .I name with the branch or revision .IR rev . .C rcs prints an error message if .I name is already associated with another number. If .I rev is omitted, the symbolic name is associated with the latest revision on the trunk. If .CI : rev is omitted, the symbolic name is deleted. .TP .CR -N \f2name\fP[ : [\|\f2rev\f1\|]\|] Same as .CR -n , except that it overrides a previous assignment of .IR name . .TP .CI -o range Deletes ("obsoletes") the revisions given by .IR range . A range consisting of a single revision number means that revision. A range consisting of a branch number means the latest revision on that branch. A range of the form .IR rev1 \(mi rev2 means revisions .I rev1 to .I rev2 on the same branch, .CI - rev means from the beginning of the branch containing .I rev up to and including .IR rev , and .RC rev - means from revision .I rev to the head of the branch containing .IR rev . None of the outdated revisions can have branches or locks. .TP .C -q Quiet mode; diagnostics are not printed. .TP .CR -s \f2state\fP[ : \f2rev\|\fP] Sets the state attribute of the revision .I rev to .IR state . If .I rev is omitted, the latest revision on the trunk is assumed. If .I rev is a branch number, the latest revision on that branch is assumed. Any identifier is acceptable for .IR state . A useful set of states is .C Exp (for experimental), .C Stab (for stable), and .C Rel (for released). By default, .C ci sets the state of a revision to .CR Exp . .TP .CR -t \|[\|\f2txtfile\fP\|] Writes descriptive text into the .SM RCS file (deletes the existing text). If .I txtfile is omitted, .C rcs prompts the user for text supplied from the standard input, terminated with a line containing a single .C . or Ctrl-D. Otherwise, the descriptive text is copied from the file .IR txtfile . If the .C -i option is present, descriptive text is requested even if .C -t is not given. The prompt is suppressed if the standard input is not a terminal. .TP .CR -u \|[\|\f2rev\fP\|] Unlocks the revision with number .IR rev . If a branch is given, the latest revision on that branch is unlocked. If .I rev is omitted, the latest lock held by the user is removed. Normally, only the locker of a revision may unlock it. Somebody else unlocking a revision breaks the lock. This causes a mail message to be sent to the original locker. The message contains a commentary solicited from the breaker. The commentary is terminated with a line containing a single .C . or Control-D. .TP .C -U Sets locking to non-strict. Non-strict locking means that the owner of a file need not lock a revision for check in. This option should .I not be used for files that are shared. The default .RC ( -L or .CR -U ) is determined by the system administrator. .RE .SS "Access Control Lists (ACLs) Do not add optional .SM ACL entries to an .SM RCS file, because they are deleted when the file is updated. The resulting access modes for the new file might not be as desired. .SH DIAGNOSTICS The .SM RCS filename and the revisions outdated are written to the diagnostic output. The exit status always refers to the last .SM RCS file operated upon, and is 0 if the operation was successful; 1 if unsuccessful. .SH EXAMPLES Add the names .CR jane , .CR mary , .CR dave , and .C jeff to the access list of .SM RCS file .CR vision,v : .IP .C rcs -ajane,mary,dave,jeff vision .PP Set the comment leader to .IC tab * for file .CR vision : .IP .C "rcs -c'\f2tab\fP*' vision" .PP Associate the symbolic name .C sso/6_0 with revision .C 38.1 of file .CR vision : .IP .C rcs -Nsso/6_0:38.1 vision .PP Lock revision .C 38.1 of file .C vision,v so that only the locker is permitted to check in (see .IR ci (1)) the next revision of the file. This command prevents two or more people from simultaneously revising the same file and inadvertently overwriting each other's work. .IP .C rcs -l38.1 vision,v .SH WARNINGS All .C rcs command options are available to anyone whose name appears in the file access list, including those to add and delete names in the access list, change strict locking, etc. If these options must be restricted, other security methods should be employed. Also see previous note regarding Access Control Lists. .SH AUTHOR .C rcs was developed by Walter F. Tichy. .SH SEE ALSO co(1), ci(1), rcsdiff(1), rcsmerge(1), rlog(1), rcsfile(4), acl(5), rcsintro(5). .\" .\" index@\f4rcs\f1 \- change \s-1RCS\s+1 file attributes@@@\f3rcs(1)\f1 .\" index@\s-1RCS\s+1: change \s-1RCS\s+1 file attributes@@@\f3rcs(1)\f1 .\" index@change \s-1RCS\s+1 file attributes@@@\f3rcs(1)\f1 .\" index@\s-1RCS\s+1 file attributes, change@@@\f3rcs(1)\f1 .\" index@attributes, change \s-1RCS\s+1 file@@@\f3rcs(1)\f1 .\" .\" toc@\f3rcs(1)\f1:\0\0\f4rcs\f1@@@change \s-1RCS\s+1 file attributes .\" .\" $Header: rcsdiff.1,v 72.4 93/01/14 11:37:34 ssa Exp $ .TA r .TH rcsdiff 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rcsdiff \- compare\s-1RCS\s0 revisions .SH SYNOPSIS .C rcsdiff .RC [ -bcefhn ] .RC [ -r\c .IR rev1\| ] .RC [ -r\c .IR rev2\| ] .IR file \0... .SH DESCRIPTION .C rcsdiff compares two revisions of each given .SM RCS file and creates output very similar to .C diff (see .IR diff (1)). A file name ending in .C ,v is an .SM RCS file name, otherwise it is a working file name. .C rcsdiff derives the working file name from the .SM RCS file name and vice versa, as explained in .IR rcsintro (5). Pairs consisting of both an .SM RCS and a working file name can also be specified. .PP .C rcsdiff recognizes the following options: .RS .TP 6 .C -b Same as described in .IR diff (1); .TP .C -e Same as described in .IR diff (1); .TP .C -f Same as described in .IR diff (1); .TP .C -h Same as described in .IR diff (1); .TP .C -n Generate an edit script of the format used by .SM RCS. .TP .CR -c [\|\f2n\fP\|] Generate a diff with lines of context. The default is to present 3 lines of context. To change, specify .IR n ; for example, .C -c10 gives 10 lines of context. .IP .C -c modifies the output format slightly from the normal .IR diff (1) output. The ``context'' output begins with identification of the files involved and their creation dates, then each change is separated by a line with a dozen .C * (asterisks). Lines removed from .I file1 are marked with .C - (dashes); those added to .I file2 with .C + (pluses). Lines that are changed from one file to the other are marked in both files with .C ! (exclamation marks). .RE .PP If both .I rev1 and .I rev2 are omitted, .C rcsdiff compares the latest revision on the trunk with the contents of the corresponding working file. This is useful for determining what was changed since the last check-in. .PP If .I rev1 is given, but .I rev2 is omitted, .C rcsdiff compares revision .I rev1 of the .SM RCS file with the contents of the corresponding working file. .PP If both .I rev1 and .I rev2 are given, .C rcsdiff compares revisions .I rev1 and .I rev2 of the .SM RCS file. .PP Both .I rev1 and .I rev2 can be given numerically or symbolically. .SH EXAMPLES Compare the latest trunk revision of .SM RCS file .C f.c,v and the contents of working file .CR f.c : .IP .C rcsdiff f.c .PP Compare the revisions 1.1 and 1.2 in the .SM RCS file .CR foo.c,v : .IP .C "rcsdiff -r1.1 -r1.2 foo.c" .SH AUTHOR .C rcsdiff was developed by Walter F. Tichy. .SH SEE ALSO ci(1), co(1), diff(1), ident(1), rcs(1), rcsmerge(1), rlog(1), rcsfile(4), rcsintro(5). .\" .\" index@\f4rcsdiff\f1 \- compare \s-1RCS\s+1 revisions@@@\f3rcsdiff(1)\f1 .\" index@\s-1RCS\s+1: compare \s-1RCS\s+1 revisions@@@\f3rcsdiff(1)\f1 .\" index@compare \s-1RCS\s+1 revisions@@@\f3rcsdiff(1)\f1 .\" index@revisions, compare \s-1RCS\s+1@@@\f3rcsdiff(1)\f1 .\" .\" toc@\f3rcsdiff(1)\f1:\0\0\f4rcsdiff\f1@@@compare \s-1RCS\s+1 revisions .\" .\" fileset_database@rcsdiff.1 USER-CMDS-MAN .\" $Header: rcsmerge.1,v 72.3 93/01/14 11:38:24 ssa Exp $ .TA r .TH rcsmerge 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rcsmerge \- merge \s-1RCS\s0 revisions .SH SYNOPSIS .C rcsmerge .CI -r rev1 .RC [ -r\c .IR \|rev2\| ] .RC [ -p ] .I file .SH DESCRIPTION .C rcsmerge incorporates the changes between .I rev1 and .I rev2 of an .SM RCS file into the corresponding working file. If .C -p is given, the result is printed on the standard output; otherwise the result overwrites the working file. .PP A file name ending in .C ,v is an .SM RCS file name; otherwise it is a working file name. .C rcsmerge derives the working file name from the .SM RCS file name and vice versa, as explained in .IR rcsintro (5). A pair consisting of both an .SM RCS and a working file name can also be specified. .PP .I rev1 cannot be omitted. If .I rev2 is omitted, the latest revision on the trunk is assumed. Both .I rev1 and .I rev2 can be given numerically or symbolically. .PP .C rcsmerge prints a warning if there are overlaps, and delimits the overlapping regions as explained for the .C -j option of .IR co (1). The command is useful for incorporating changes into a checked-out revision. .SH EXAMPLES Suppose you have released revision 2.8 of .CR f.c . Assume furthermore that you just completed revision 3.4 when you receive updates to release 2.8 from someone else. To combine the updates to 2.8 and your changes between 2.8 and 3.4, put the updates to 2.8 into file .C f.c and execute: .IP .C rcsmerge -p -r2.8 -r3.4 f.c >f.merged.c .PP Then examine .CR f.merged.c . Alternatively, if you want to save the updates to 2.8 in the .SM RCS file, check them in as revision 2.8.1.1 and execute .CR "co -j" : .IP .C ci -r2.8.1.1 f.c .br .C co -r3.4 -j2.8:2.8.1.1 f.c .PP As another example, the following command undoes the changes between revision 2.4 and 2.8 in your currently checked out revision in .CR f.c : .IP .C rcsmerge -r2.8 -r2.4 f.c .PP Note the order of the arguments, and that .C f.c is overwritten. .SH WARNINGS .C rcsmerge does not work for files that contain lines with a single .CR . \|. .SH AUTHOR .C rcsmerge was developed by Walter F. Tichy. .SH SEE ALSO ci(1), co(1), merge(1), ident(1), rcs(1), rcsdiff(1), rlog(1), rcsfile(4). .\" .\" index@\f4rcsmerge\f1 \- merge \s-1RCS\s+1 revisions@@@\f3rcsmerge(1)\f1 .\" index@\s-1RCS\s+1: merge \s-1RCS\s+1 revisions@@@\f3rcsmerge(1)\f1 .\" index@merge \s-1RCS\s+1 revisions@@@\f3rcsmerge(1)\f1 .\" index@\s-1RCS\s+1 revisions, merge@@@\f3rcsmerge(1)\f1 .\" .\" toc@\f3rcsmerge(1)\f1:\0\0\f4rcsmerge\f1@@@merge \s-1RCS\s+1 revisions .\" .\" fileset_database@rcsmerge.1 USER-CMDS-MAN .\" $Header: rdist.1,v 72.3 94/12/09 15:04:59 ssa Exp $ .TA r .TH rdist 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rdist \- remote file distribution program .SH SYNOPSIS .C rdist [ .C \-bhinqvwyMR ] [ .CI \-f \0distfile ] [ .CI \-d \0var = value ] [ .CI \-m \0host ] [ .I label... ] .br .C rdist [ .C \-bhinqvwyMR ] .CI -c \0name... [ .I login\c @]\c .I host\c [:\c .I dest\c ] .ad b .SH DESCRIPTION .C rdist facilitates the maintaining of identical copies of files over multiple hosts. It preserves the owner, group, mode, and modification time of files if possible and can update programs that are executing. .TP 12 .CI -f \0distfile Specify a .I distfile for .C rdist to execute. .I distfile contains a sequence of entries that specify the files to be copied, the destination hosts, and what operations to perform to do the updating. The format of .I distfile is described in detail later. If .I distfile is .CR \- , the standard input is used. If no .C \-f option is present, the program looks first for a file called .CR distfile , then .CR Distfile in the local host's working directory to use as the input. .TP .CI -d\0 "var=value" Define .I var to have .IR value . The .C -d option is used to define variable definitions in the .IR distfile . .I value can be an empty string, one name, or a list of name separated by tabs and/or spaces and enclosed by a pair of parentheses. .TP .CI -m \0host Limit which machines are to be updated. Multiple .C -m arguments can be given to limit updates to a subset of hosts that are listed in the .IR distfile . .TP .I label Label of a command to execute. The label must be defined in .IR destfile . .TP .CI -c \0name... The .C \-c option forces .C rdist to interpret the remaining arguments as a small .IR distfile . The equivalent distfile is as follows. .nf .ti +.5i ( \f2name\fP ... ) -> [\f2login\fP@]\f2host\fP .ti +1i install [\f2dest\fP] ; .fi .TP .C \-n Print the commands without executing them. This option is useful for debugging .IR distfile . .TP .C \-q Quiet mode. Files that are being modified are normally printed on standard output. The .B \-q option suppresses this. .TP .C \-R Remove extraneous files. If a directory is being updated, any files that exist on the remote host that do not exist in the master directory are removed. This is useful for maintaining truly identical copies of directories. .TP .C \-h Follow symbolic links. Copy the file that the link points to rather than the link itself. .TP .C \-i Ignore unresolved links. .C rdist will normally try to maintain the link structure of files being transferred and warn the user if it cannot find all the links. .TP .C \-v Verify that the files are up to date on all the hosts. Any files that are out of date will be displayed but no files will be changed nor any mail sent. .TP .C \-w Whole mode. The whole file name is appended to the destination directory name. Normally, only the last component of a name is used when renaming files. This will preserve the directory structure of the files being copied instead of flattening the directory structure. For example, renaming a list of files such as ( .C dir1/f1 dir2/f2 ) to .C dir3 would create files .C dir3/dir1/f1 and .C dir3/dir2/f2 instead of .C dir3/f1 and .CR dir3/f2 . .TP .C \-y Younger mode. Files are normally updated if their .I mtime and .I size (see .IR stat (2)) disagree. The .C \-y option causes .C rdist not to update files that are younger than the master copy. This can be used to prevent newer copies on other hosts from being replaced. A warning message is printed for files which are newer than the master copy. .TP .C \-b Binary comparison. Perform a binary comparison and update files if they differ rather than comparing dates and sizes. .TP .C \-M Check that mode, ownership, and group are the same in addition to any other form of comparison that is in effect. This option will cause files to be replaced but will only correct the problem with a directory and print a warning message. .PP The .I distfile used by .C rdist contains a sequence of entries that specify the files to be copied, the destination hosts, and what operations to perform to do the updating. Each entry has one of the following formats. .nf .in +.5i .IR variable_name \0= \0name_list .RI [ label :] \0source_list \0\-> " destination_list command_list" .RI [ label :] \0source_list \0:: " time_stamp_file command_list" .in .fi The first format is used for defining variables. The second format is used for distributing files to other hosts. The third format is used for making lists of files on the local host that have been changed since some given date. (See .CR EXAMPLES .) .TP 10 .I variable_name Specify the name of a variable. .TP .I name_list List of names (such as list of hosts or lists of files) separated by tabs and/or spaces and enclosed by parentheses. .TP .I source_list Specify a list of files and/or directories on the local host to be used as the master copy for distribution. Each file in the .I source_list is added to a list for changes, .I if the file is out of date on the host that is being updated (second format), or .I if the file is newer than the time stamp file (third format). .I source_list may contain a single name, or multiple names separated by tabs and/or spaces and enclosed by parentheses. .TP .I destination_list List of hosts to which these files are to be copied. .I destination_list may contain a single name, or multiple names separated by tabs and/or spaces and enclosed by parentheses. .TP .I time_stamp_file Specify a given date to generate a list of files on the local host that were modified since that date. .TP .IR label : Labels are optional. They are used to identify a command for partial updates. .TP .I command_list Specifies a list of commands to be performed. .IP The command list consists of zero or more commands of the following format. .in +.5i .CR install " [" .IR options ] \0opt_dest_name \c .C ; .br .CI notify \0name_list ; .br .CI except \0name_list ; .br .CI except_pat \0pattern_list ; .br .CI special " name_list string" ; .in .IP The .C install command is used to copy out-of-date files and/or directories. Each source file is copied to each host in the destination list. Directories are recursively copied in the same way. .I opt_dest_name is an optional parameter to rename files. If no .C install command appears in the command list or the destination name is not specified, .I source_list is used. Directories in the path name will be created if they do not exist on the remote host. To help prevent disasters, a non-empty directory on a target will never be replaced with a regular file or a symbolic link. However, under the .C -R option a non-empty directory will be removed if the corresponding filename is completely absent on the master host. The .I options are .CR -b , -h , -i , -v , -w, -y , -M , and .CR -R , and have the same semantics as options on the command line, except that they only apply to the files in the specified .IR source_list . The login name used on the destination host is the same as on the local host, unless the destination name is of the form "login@host". .IP The .C notify command is used to mail the list of files updated (and any errors that may have occurred) to the listed names, in .IR name_list . If no .C @ appears in the name, the destination host is appended to the name (e.g., name1@host, name2@host, ...). .IP The .C except command is used to update all of the files in the source list, .I except for the files listed in .IR name_list . This is usually used to copy everything in a directory except certain files. .IP The .C except_pat command is like the .C except command except that .I pattern_list is a list of regular expressions (see .IR ed (1) for details). If one of the patterns matches some string within a file name, that file will be ignored. Note that since the backslash .RC ( \e ) is a quote character, it must be doubled to become part of the regular expression. Variables are expanded in .I pattern_list but not shell file pattern matching characters. To include a .CR $ , it must be escaped with the backslash. .IP The .C special command is used to specify .IR sh (1) commands that are to be executed on the remote host after the file in .I name_list is updated or installed. If the .I name_list is omitted then the shell commands will be executed for every file updated or installed. The shell variable `FILE' is set to the current filename before executing the commands in .IR string . .I string starts and ends with double quotes (") and can cross multiple lines in .IR distfile . Multiple commands to the shell should be separated by semi-colons .RC ( ; ). Commands are executed in the user's home directory on the host being updated. The .C special command can be used, for example, to rebuild private databases after a program has been updated. Shell variables cannot be used in the command because there is no escape mechanism for the .C $ character. .PP Newlines, tabs, and blanks are only used as separators and are otherwise ignored. Comments begin with .C # and end with a newline. .PP A generalized way of dynamically building variable lists is provided by using a backquote syntax much like the shell. In this way, arbitrary commands that generate stdout with space-separated words may be used to build the list (see the use of .C cat command in the examples). .PP Variables to be expanded begin with .C $ followed by the variable name enclosed in curly braces. .PP The shell meta-characters .CR [ , .CR ] , .CR { , .CR } , .CR * , and .C ? are recognized and expanded (on the local host only) in the same way as .IR csh (1). They can be escaped with a backslash. The .C ~ character is also expanded in the same way as .IR csh but is expanded separately on the local and destination hosts. When the .C \-w option is used with a file name that begins with .CR ~ , everything except the home directory is appended to the destination name. File names which do not begin with .C / or .C ~ use the destination user's home directory as the root directory for the rest of the file name. .SH EXAMPLES The following is a small example. .nf .in +.5i HOSTS = ( matisse root@arpa ) FILES = ( /usr/lib /usr/bin /usr/local/games /usr/include/{*.h,{sys,rpc*,arpa}/*.h} /usr/man/man? `cat ./std-files` ) EXLIB = ( Mail.rc aliases aliases.dir aliases.pag crontab dshrc sendmail.cf sendmail.fc sendmail.hf sendmail.st uucp vfont ) ${FILES} -> ${HOSTS} install -R ; except /usr/lib/${EXLIB} ; except /usr/local/games/lib ; special /usr/sbin/sendmail " /usr/sbin/sendmail -bz" ; srcs: /usr/local/src -> arpa except_pat ( \e\e.o$ /SCCS\e$ ) ; IMAGEN = (ips dviimp catdvi) imagen: /usr/local/${IMAGEN} -> arpa install /usr/local/lib ; notify ralph ; ${FILES} :: stamp.cory notify root@cory ; .in .fi .SH AUTHOR .C rdist was developed by the University of California, Berkeley. .SH FILES .TP 30 .PD 0 .C distfile Input command file. .TP .C /tmp/rdist* Temporary file for update lists. .PD .SH HISTORY .C rdist appeared in the 4.3 Berkeley Software Distribution. .SH "SEE ALSO" sh(1), csh(1), stat(2) .SH DIAGNOSTICS A complaint about mismatch of rdist version numbers may mean that an executable .C rdist is not in the shell's path on the remote system. .SH BUGS Source files must reside on the local host where .C rdist is executed. .PP There is no easy way to have a special command executed after all files in a directory have been updated. .PP Variable expansion only works for name lists and in the .C special command string; there should be a general macro facility. .PP .C rdist aborts on files that have a negative mtime (before Jan 1, 1970). .PP .C rdist does carry the atime when installing a file but will preserve it on an updated file. .PP There should be a `force' option to allow replacement of non-empty directories by regular files or symlinks. .\" .\" index@\f4rdist\f1 \- remote file distribution program@@@\f3rdist(1)\f1 .\" index@\f1remote file distribution@@@\f3rdist(1)\f1 .\" index@\f1file distribution to remote hosts@@@\f3rdist(1)\f1 .\" index@\f1update files on remote hosts@@@\f3rdist(1)\f1 .\" .\" toc@\f3rdist(1)\f1:\0\0\f4rdist\f1@@@remote file distribution .\" .\" fileset_database@rdist.1 INETSVCS-MAN .\" $Header: read.1,v 76.1 95/08/04 16:21:24 ssa Exp $ .TA r .TH read 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME read \- read a line from standard input .SH SYNOPSIS .C read .RC [ -r ] .IR var \0... .SH DESCRIPTION .C read reads a single line from standard input. The line is split into fields as when processed by the shell (refer to shells in .SM SEE ALSO\c ); the first field is assigned to the first variable .IR var , the second field to the second variable .IR var , and so forth. If there are more fields than there are specified .I var operands, the remaining fields and their intervening separators are assigned to the last .IR var . If there are more .IR var s than fields, the remaining .IR var s are set to empty strings. .PP The setting of variables specified by the .I var operands affect the current shell execution environment. .PP Standard input to .C read can be redirected from a text file. .PP Since .C read affects the current shell execution environment, it is usually provided as a normal shell special (built-in) command. Thus, if it is called in a subshell or separate utility execution environment similar to the following, it does not affect the shell variables in the caller's environment: .nf .IP .C (read foo) .C nohup read .... .C find . -exec read ... ; .fi .SS Options and Arguments .C read recognizes the following options and command-line arguments: .RS .TP 15 .C -r Do not treat a backslash character in any special way. Consider each backslash to be part of the input line. .TP .I var The name of an existing or non-existing shell variable. .SH EXTERNAL INFLUENCES .SS Environment Variables .C IFS determines the internal field separators used to delimit fields. .SH RETURN VALUE .C read exits with one of the following values: .RS .TP .B \00 Successful completion. .TP .B >0 End-of-file was detected or an error occurred. .RE .SH EXAMPLES Print a file with the first field of each line moved to the end of the line. .nf .IP .ift .ft 4 .ifn .ft 3 .ps +1 while read -r xx yy do printf "%s %s \\n" "$yy" "$xx" done < input_file .ft .ps .SH SEE ALSO csh(1), ksh(1), sh-posix(1), sh(1). .SH STANDARDS CONFORMANCE .CR read ": SVID2, XPG2, XPG3, XPG4, POSIX.2 FIPS" .\" .\" toc \f3read(1)\f1:\0\0\f4read\f1 read a line from standard input .\" .\" index@\f4read\f1 \- read a line from standard input@@@\f3read(1)\f1 .\" index@read a line from standard input@@@\f3read(1)\f1 .\" index@line from standard input, read a@@@\f3read(1)\f1 .\" index@standard input, read a line from@@@\f3read(1)\f1 .\" index@input, read a line from standard@@@\f3read(1)\f1 .\" .\" fileset_database@read.1 USER-CMDS-MAN .\" $Header: readmail.1,v 80.2 96/10/20 19:00:48 ssa Exp $ .TA r .TH readmail 1 .SH NAME readmail \- read mail from a mail folder or incoming mailbox .SH SYNOPSIS .HP .CR readmail .RC [ -ahnp ] .RC [ -f .IR folder ] .RI [ number-list \(or pattern ] .SH DESCRIPTION The .CR readmail program displays messages from your incoming mailbox or a specified mail folder. .PP Within the .CR elm mail system (see .IR elm (1) with no operands and optionally the .CR \-h or .CR \-n option, .CR readmail displays the appropriate headers and the body of the current message. .PP With the .IR number-list operand and no options, .CR readmail displays the corresponding messages and a summary of the headers from your incoming mailbox. .PP With the .IR pattern operand and no options, .CR readmail displays the first message that matches the pattern and a summary of the headers from your incoming mailbox. .SS Options .CR readmail supports the following options. .RS .TP 15 .CR \-a Print all messages that match .IR pattern . If no pattern was specified, this option is ignored. .TP .CI -f \0folder Use file .I folder for the operations instead of the incoming mailbox. .TP .CR -h Include the entire header of the matched message or messages when displaying their text. The default is to display the .CR From:\& , .CR Date:\& , and .CR Subject:\& lines only. .TP .CR -n Exclude all headers. .TP .CR -p Put formfeeds (Control-L) between message headers. This is useful when printing sets of messages. .RE .SS Operands .CR readmail supports the following operands. .RS .TP 15 .I number-list A blank-separated list of the ordinal locations of messages in the mail file (i.e., their "message numbers"), up to 25 at a time. The character .CR $ means the last message in the mail file. Similarly, .CR * represents every message in the file (i.e., .CR "1 2 3 " ... " $" ) .IP The message numbers are sorted into ascending order. Thus, .CR "1 3 2" produces the same output as .CR "1 2 3" . .TP .I pattern A string that is present in one of the messages. This pattern can be typed in directly (no quotes) if the words are separated by a single space in the actual message. The pattern matching is case sensitive, so .CR Hello and .CR hello are not equivalent. Leading digits (on the first word) are not permitted; however, you can precede them with a space and quote the entire string, if the space occurs in the message, as in .C """ 1st item of business"""\c \&. .RE .SH EXAMPLES If you are using .CR vi to reply to a message from within the .CR elm mail system, you can insert the text of the current message with the command: .IP .C ":r !readmail" .PP If you define an alias similar to: .RS .nf .PP .CR "alias rd='readmail $ | page'" "\0\0\0 (Bourne, Korn, or POSIX shell)" .CR "alias rd 'readmail $ | page'" "\0\0\0 (C shell)" .fi .RE .PP you can use it with a program such .CR newmail to peruse mail as it arrives, without needing to start a mail system (see .IR newmail (1)). .SH AUTHOR .CR readmail was developed by HP. .SH FILES .TP 35 .PD 0 .CI /var/mail/ loginname Incoming mailbox .TP .C $HOME/.elm/readmail Temporary file for .CR elm .PD .SH SEE ALSO elm(1), newmail(1), vi(1). .\" .\" index@\f4readmail\f1 \- read mail from specified mail folder@@@\f3readmail(1)\f1 .\" index@mail, read from specified mail folder@@@\f3readmail(1)\f1 .\" index@mail folder, read mail from specified@@@\f3readmail(1)\f1 .\" .\" toc@\f3readmail(1)\f1:\0\0\f4readmail\f1@@@read mail from a mail folder or incoming mailbox .\" .\" $Header: ed.1,v 76.1 95/08/07 11:29:45 ssa Exp $ .TA e .TH ed 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ed, red \- line-oriented text editor .SH SYNOPSIS .CR ed .RC [ -p .IR string ] .RC [ -s \(or - ] .RC [ -x ] .RI [ file ] .PP .CR red .RC [ -p .IR string ] .RC [ -s \(or - ] .RC [ -x ] .RI [ file ] .SH DESCRIPTION The .CR ed command executes a line-oriented text editor. It is most commonly used in scripts and noninteractive editing applications because, even though it can be used interactively, other editors such as .CR vi and .CR ex are typically easier to use in an interactive environment. .PP If .I file is specified, .CR ed performs an .CR e command (see below) on the named file; that is to say, the file is read into .CR ed 's buffer so that it can be edited. .SS Options The following options are recognized: .RS .TP 12 .CI -p \ string Use .I string as the prompt string when in command mode. By default, there is no prompt string. .TP .CR -s \(or - Suppress printing of byte counts by .CR e , .CR E , .CR r , and .CR w commands, and suppress the .CR !\& prompt after a .CR !\& .IR command . The .CR - option is obsolescent and will be removed in a future release. .TP .CR -x Perform an .CR X command first to handle an encrypted file. .RE .SS File Handling .CR ed operates on a copy of the file it is editing; changes made to the copy have no effect on the original file until a .CR w (write) command is given. The copy of the text being edited resides in a temporary file called the .IR buffer . There is only one buffer. .PP .CR red is a restricted version of .CR ed that only allows editing of files in the current directory and prohibits executing shell commands via .CI ! shell-command\f1. Attempts to bypass these restrictions result in the error message .CR "restricted shell" . .PP Both .CR ed and .CR red support the .IR fspec (4) formatting capability. After including a format specification as the first line of .I file and invoking .CR ed with the controlling terminal in .CR "stty -tabs" or .CR "stty tab3" mode (see .IR stty (1)), the specified tab stops are automatically used when scanning .IR file . For example, if the first line of a file contained .IP .C "<:t5,10,15 s72:>" .PP the tab stops would be set at columns 5, 10, and 15, and a maximum line length of 72 would be imposed. .PP .B Note: When you input text, .CR ed expands tab characters as they are typed to every eighth column as a default. .SS Editor Commands Structure Commands to .CR ed have a simple and regular structure: zero, one, or two .I addresses followed by a single-character .IR command , possibly followed by parameters to that command. These addresses specify one or more lines in the buffer. Every command that requires addresses has default addresses, so that the addresses can very often be omitted. .PP In general, only one command is allowed on a line. Append, change, and insert commands accept text input which is then placed in the buffer as appropriate. While .CR ed is accepting text following an append, change, or insert command, it is said to be in .IR "input mode" . While in input mode, .I no editor commands are recognized; all input is merely collected. To terminate input mode, type a period .RC ( . ) alone at the beginning of a line. .SS Regular Expressions .CR ed supports the Basic Regular Expression (RE) syntax (see .IR regexp (5)), with the following additions: .RS .TP 3 \(bu The null RE (for example, .CR // ) is equivalent to the last RE encountered. .TP \(bu If the closing delimiter of an RE or of a replacement string (for example, .CR / ) would be the last character before a newline, that delimiter can be omitted, in which case the addressed line is printed. The following pairs of commands are equivalent: .RS 6 .PP .ifn\{ .nf s/s1/s2 g/s1 ?s1 s/s1/s2/p g/s1/p ?s1? .fi \} .ift \{\" .TS lf4p+1w(1.5i) lf4p+1w(1.5i) lf4p+1w(1.5i). s/s1/s2 g/s1 ?s1 s/s1/s2/p g/s1/p ?s1? .TE \} .RE .RE .SS Line Addresses To understand line addressing, remember that .CR ed maintains a pointer to the .IR "current line" . Generally speaking, the current line is the last line affected by a command. The exact effect of a given command on the current line is discussed under the description of each command. Addresses are interpreted according to the following rules: .RS .TP 4 1. The character .CR .\& refers to the current line. .TP 2. The character .CR $ refers to the last line of the buffer. .TP 3. A decimal number .I n refers to the .IR n th line of the buffer. .TP 4. A .CI ' x refers to the line marked with the mark name character .IR x , which must be a lower-case letter. Lines are marked with the .CR k command described below. .TP 5. An RE enclosed by slashes (\c .CI / RE /\c ) refers to the first line found by searching forward from the line following the current line toward the end of the buffer and stopping at the first line containing a string matching the RE. If necessary, the search wraps around to the beginning of the buffer and continues up to and including the current line, so that the entire buffer is searched. (Also see WARNINGS below.) .TP 6. An RE enclosed by question marks (\c .CI ? RE ?\c ) addresses the first line found by searching backward from the line preceding the current line toward the beginning of the buffer and stopping at the first line containing a string matching the RE. If necessary, the search wraps around to the end of the buffer and continues up to and including the current line. (Also see WARNINGS below.) .TP 7. An address followed by a plus .RC ( + ) or minus .RC ( - ) sign followed by a decimal number specifies that address plus or minus the indicated number of lines. The plus sign can be omitted. .TP 8. If an address begins with .CR + or .CR - , the addition or subtraction is calculated with respect to the current line. For example, .CR -5 is interpreted as .CR .-5 . .TP 9. If an address ends with .CR + or .CR - , 1 is added to or subtracted from the address, respectively. As a consequence of this and rule 8 above, the address .CR - refers to the line preceding the current line. (To maintain compatibility with earlier versions of the editor, the circumflex .RC ( ^ ) and .CR - characters are interpreted identically when encountered in addresses.) Moreover, multiple trailing .CR + and .CR - characters have a cumulative effect, so .CR -- refers to the second line preceding the current line. .TP 10. For convenience, a comma .RC ( , ) represents the address pair .CR 1,$ , while a semicolon .RC ( ; ) represents the pair .CR .,$ . .RE .PP Commands require zero, one, or two addresses. Commands that do not use addresses treat the presence of an address as an error. Commands that accept one or two addresses assume default addresses when the number of addresses specified is insufficient. If more addresses are specified than a given command requires, the last one or two are used as appropriate. .PP Addresses are usually separated from each other by a comma .RC ( , ). They can also be separated by a semicolon .RC ( ; ), in which case the current line .RC ( . ) is set to the first address, after which the second address is calculated. This feature can be used to determine the starting line for forward and backward searches (see rules 5 and 6 above). The second address of any two-address sequence must correspond to a line in the buffer that follows the line corresponding to the first address. .SS Editor Commands In the following list of .CR ed commands, the default addresses are shown in parentheses (parentheses are not part of the address and should not be placed in an actual command except for other purposes). .PP It is generally illegal for more than one command to appear on a line. However, any command (except .CR e , .CR f , .CR r , or .CR w ) can be suffixed by .CR l , .CR n , or .CR p in which case the current line is respectively either listed, numbered, or printed, as discussed below under the .CR l , .CR n , and .CR p commands. .br .ne 4 .TP 15 .PD 0 .RC ( . ) a .TP .IR text .TP .CR . .sp -3v The .CR a (append) command reads .IR text and appends it after the addressed line. Upon completion, the new current line is the last inserted line, or, if no text was added, at the addressed line. Address 0 is legal for this command, causing the appended .IR text to be placed at the beginning of the buffer. .PD .br .ne 5 .TP .PD 0 .RC ( .,. ) c .TP .IR text .TP .CR . .sp -3v The .CR c (change) command deletes the addressed lines then accepts input text to replace the deleted lines. Upon completion, the new current line is the last line in .I text or, if no text was provided, at the first line after the deleted line or lines. .PD .TP .RC ( .,. ) d The .CR d (delete) command deletes the addressed lines from the buffer. Upon completion, the new current line is the first line following the deleted text, or the last line in the file if the deleted line or lines were at the end of the buffer. .TP .CI e \0file The .CR e (edit) command deletes the entire contents of the buffer, then reads in the named .IR file . Upon completion, the new current line is the last line in the buffer. If no file name is given, the remembered file name, if any, is used (see the .CR f command). The number of characters read is displayed, and .I file is remembered for possible use as a default file name in subsequent .CR e , .CR r , or .CR w commands. .IP If the .I file name starts with .CR ! , the rest of the line is interpreted as a shell command whose standard output is to be read. Such a shell command is not remembered as the current file name. .IP Also see DIAGNOSTICS below. .TP .CI E \0file The .CR E (forced edit) command is identical to .CR e except that no check is made to ensure that the current buffer has not been altered since the last .CR w command. .TP .CI f \0file If .I file is specified, the .CR f (file name) command changes the remembered file name to .IR file . Otherwise, it prints the remembered file name. .TP .RC ( 1,$ ) g/ \s-1\f2RE\fP\s0 "/\s-1\f2command-list\fP\s0" The .CR g (global) command first marks every line that matches the given RE. Then, for every such line, the given .I "command-list" is executed with the current line initially set to that line. A single command or the first of a list of commands appears on the same line as the global command. All lines of a multiple-line list except the last line must end with a backslash .RC ( \e ). .CR a , .CR i , and .CR c commands and associated input are permitted. The .CR .\& that normally terminates input mode can be omitted if it would be the last line of the .IR "command-list" . An empty .I "command-list" is equivalent to the .CR p command. The .CR g , .CR G , .CR v , and .CR V commands are not permitted in the .IR "command-list" . (Also see WARNINGS below.) .TP .RC ( 1,$ ) G/ \s-1\f2RE\fP\s0 / The interactive .CR G (Global) command first marks every line that matches the given RE. Then, for every such line, the line is printed, then the current line is changed to that line and one command (other than .CR a , .CR c , .CR i , .CR g , .CR G , .CR v , or .CR V ) can be input and executed. After executing that command, the next marked line is printed, and so on. A newline character acts as a null command, and an .CR & causes the re-execution of the most recent command executed within the current invocation of .CR G . Note that the commands input as part of the execution of the .CR G command may address and affect .I any lines in the buffer. The .CR G command can be terminated by an interrupt signal (ASCII DEL or BREAK). .TP .CR h The .CR h (help) command gives a short error message explaining the reason for the most recent .CR ?\& diagnostic. .TP .CR H The .CR H (Help) command causes .CR ed to enter a mode in which error messages are printed for all subsequent .CR ?\& diagnostics. It also explains the previous .CR ?\& if there was one. The .CR H command alternately turns this mode on and off. Initially, it is off. .br .ne4 .TP .RC ( . ) i .PD 0 .TP .IR text .TP .CR .\& .sp -3v The .CR i (insert) command inserts the given .I text before the addressed line. Upon completion, the current line is the last inserted line, or, if there were none, the addressed line. This command differs from the .CR a command only in the placement of the input text. Address 0 is not legal for this command. .PD .TP .RC ( .,.+1 ) j The .CR j (join) command joins contiguous lines by removing the appropriate newline characters. If exactly one address is given, this command does nothing. .TP .RC ( . ) k \f2x\fP The .CR k (mark) command marks the addressed line with the name .IR x , which must be a lower-case letter. The address .CI ' x then addresses this line. Upon completion, the new current line remains unchanged from before. .TP .RC ( .,. ) l The .CR l (list) command writes the addressed lines to standard output in a visually unambiguous form. Characters listed in the following table are written as the corresponding escape sequence. Nonprintable characters not in the table are written as a three-digit octal number (with a preceding backslash character) for each byte in the character (most significant byte first). .IP Long lines are folded with the point of folding indicated by writing a backslash character followed by a newline. The end of each line is marked with a .CR $ . An .CR l (ell) command can be appended to any command other than .CR e , .CR E , .CR f , .CR q , .CR Q , .CR r , .CR w , or .CR ! . The current line number is set to the address of the last line written. .ifn .PP .ift .IP .TS center tab(;); cB cB cB | cB cB cB cB cB cB | cB cB cB cf4p+1 l c | cf4p+1 l c . Escape;;ASCII;Escape;;ASCII Sequence;Represents;Name;Sequence;Represents;Name \e\e;backslash;\e;\er;carriage return;CR \ea;alert;BEL;\et;horizontal tab;HT \eb;backspace;BS;\ev;vertical tab;VT \ef;formfeed;FF .TE .TP 15 .RC ( .,. ) m \f2a\fP The .CR m (move) command repositions the addressed lines after the line addressed by .IR a . Address 0 is legal for .IR a , causing the addressed lines to be moved to the beginning of the file. It is an error if address .I a falls within the range of moved lines; Upon completion, the new current line is the last line moved. .TP .RC ( .,. ) n The .CR n (number) command prints the addressed lines, preceding each line by its line number and a tab character. Upon completion, the new current line is the last line printed. The .CR n command can be appended to any command other than .CR e , .CR f , .CR r , or .CR w . .TP .RC ( .,. ) p The .CR p (print) command prints the addressed lines. Upon completion, the new current line is the last line printed. The .CR p command may be appended to any other command other than .CR e , .CR E , .CR f , .CR q , .CR Q , .CR r , .CR w , or .CR ! . For example, .CR dp deletes the current line and prints the new current line. .TP .CR P The .CR P (prompt) command causes .CR ed to prompt with an asterisk .RC ( * ) (or with .I string if the .CR -p option was specified in the command line) for all subsequent commands. The .CR P command alternately turns this mode on and off. It is initially on if the .CR -p option was specified; otherwise, off. The current line number is unchanged. .TP .CR q The .CR q (quit) command causes .CR ed to exit. No automatic write of a file is done (but see DIAGNOSTICS below). .TP .CR Q The editor exits unconditionally without checking for changes in the buffer since the last .CR w command. .TP .RC ( $ ) r \0\f2file\fP The .CR r (read) command reads the specified .I file into the buffer after the addressed line. If no file name is given, the remembered file name, if any, is used (see the .CR e and .CR f commands). The remembered file name is not changed unless .I file is the very first file name mentioned since .CR ed was invoked. Address 0 is legal for .CR r and places the contents of .I file at the beginning of the buffer. If the read is successful, the number of characters read is displayed. Upon completion, the new current line is the last line read into the buffer. If the .I file name starts with .CR ! , the rest of the line is interpreted as a shell command whose standard output is to be read. For example, .C $r !ls appends a listing of files in the current directory to the end of the file being edited. A shell command is not remembered as the current file name. .TP .RC ( .,. ) s/ \s-1\f2RE\fP\s0 /\s-1\f2replacement\s0\fP/\s-1\f2flags\s0\fP The .CR s (substitute) command searches each addressed line for an occurrence of the specified RE. In each line in which a match is found, all (nonoverlapped) matched strings are replaced by .I replacement if the global replacement indicator .CR g appears after the command. If the global indicator does not appear, only the first occurrence of the matched string is replaced. If a number .I n appears after the command, only the .IR n th occurrence of the matched string on each addressed line is replaced. It is an error for the substitution to fail on all addressed lines. Any character other than space or newline can be used instead of .CR / to delimit the RE and .IR replacement . Upon completion, the new current line is the last line on which a substitution occurred. (Also see WARNINGS below.) .PD .IP If an ampersand .RC ( & ) appears in .IR replacement , it is replaced by the string matching the RE on the current line. The special meaning of .CR & in this context can be suppressed by preceding it with .CR \e . .IP As a more general feature, the characters .CI \e n\f1, where .I n is a digit, are replaced by the text matched by the .IR n th regular subexpression of the specified RE enclosed between .CR \e( and .CR \e) . When nested parenthesized subexpressions are present, .I n is determined by counting occurrences of .CR \e( , starting from the left. .IP When the character .CR % is the only character in .IR replacement , the .I replacement used in the most recent substitute command is used as the .I replacement in the current substitute command. The .CR % loses its special meaning when it is in a replacement string containing more than one character or when preceded by a .CR \e . .IP A line can be split by substituting a newline character into it. The newline in .I replacement must be escaped by preceding it by .CR \e . Such substitution cannot be done as part of a .CR g or .CR v command list. .IP The value of .I flags is zero or more of: .RS .RS .TP .I n Substitute for the .IR n th occurrence only of the RE found on each addressed line. .TP .CR g Substitute for all nonoverlapped occurrences of the RE on each addressed line. .TP .CR l Write to standard output the final line in which a substitution was made. The line is written in the format specified for the .CR l command. .TP .CR n Write to standard output the final line in which a substitution was made. The line is written in the format specified for the .CR n command. .TP .CR p Write to standard output the final line in which a substitution was made. The line is written in the format specified for the .CR p command. .RE .RE .TP .RC ( .,. ) t \f2a\fP Same as .CR m command, except that a copy of the addressed lines is placed after address .I a (which can be 0). Upon completion, the new current line is the last line of the copy. .TP .CR u The .CR u (undo) command nullifies the effect of the most recent command that modified anything in the buffer, that is, the most recent .CR a , .CR c , .CR d , .CR g , .CR G , .CR i , .CR j , .CR m , .CR r , .CR s , .CR t , .CR v , or .CR V command. All changes made to the buffer by a .CR g , .CR G , .CR v , or .CR V global command are "undone" as a single change; if no changes were made by the global command (such as with .CI g/ RE /p\c ), the .CR u command has no effect. The current line number is set to the value it had immediately before the command started. .TP .RC ( 1,$ ) v/ \s-1\f2RE\fP\s0 "/\s-1\f2command-list\fP\s0" The complement of the global command .CR g in that the lines marked during the first step are those that do .B not match the RE. .TP .RC ( 1,$ ) V/ \f2RE\fP / The complement of the interactive global command .CR G in that the lines marked during the first step are those that do .B not match the RE. .TP .RC ( 1,$ ) w \0\f2file\fP The .CR w (write) command writes the addressed lines into the named file. If the file does not exist, it is created with mode 666 (readable and writable by everyone), unless the current .CR umask setting dictates otherwise (see .IR umask (1). The remembered file name is not changed unless .I file is the very first file name encountered since .CR ed was invoked. If no file name is given, the remembered file name, if any, is used (see the .CR e and .CR f commands). Upon completion, the current line address is unchanged. If the command is successful, the number of characters written is displayed. .IP If the .I file name starts with .CR ! , the rest of the line is interpreted as a shell command whose standard input is the addressed lines. Such a shell command is not remembered as the current file name. .TP .CR X A key string is demanded from the standard input. Subsequent .CR e , .CR r , and .CR w commands will encrypt and decrypt the text with this key, using the algorithm of .IR crypt (1). An explicitly empty key turns off encryption. .TP .RC ( $ ) = The line number of the addressed line is displayed. The current line address is unchanged by this command. .TP .CI ! "shell-command" The remainder of the line after the .CR !\& is sent to the shell to be interpreted and executed as a command. Within the text of that command, the unescaped character .CR % is replaced with the remembered file name. If a .CR !\& appears as the first character of the shell command, it is replaced with the text of the previous shell command. Thus, .CR !!\& repeats the last shell command. If any expansion is performed, the expanded line is echoed. Upon completion, the current line address is unchanged. .TP .RC ( .+1 )\ \f2newline\fP An address alone on a line causes the addressed line to be printed. A newline alone is equivalent to .CR .+1p . This technique is useful for stepping forward through the buffer. .PP If an interrupt signal (ASCII DEL or BREAK) is sent, .CR ed prints a .CR ?\& and returns to its command level. .PP The following size limitations apply: 256 characters per global command list, 64 characters per file name, and 32 MB characters in the buffer. The limit on the number of lines depends on the amount of user memory: each line takes 1 word. .SH EXTERNAL INFLUENCES .SS Environment Variables .PP .CR SHELL determines the preferred command-line interpreter for use in all .CR ! -style commands. If this variable is null or not set, the POSIX shell, .CR /usr/bin/sh , is used (see .IR sh-posix (1)). .PP When set, .CR TMPDIR specifies a directory to be used for temporary files, overriding the default directory, .CR /tmp . .PP .CR LANG provides a default value for internationalization variables that are unset or null. If .CR LANG is unset or null, the default value is "C" (see .IR lang (5)). If any internationalization variable contains an invalid setting, all internationalization variables default to "C". See .IR environ (5). .PP If .CR LC_ALL is set to a nonempty string value, it overrides the values of all the other internationalization variables, including .CR LANG . .PP .CR LC_CTYPE determines the interpretation of text as single- and/or multibyte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .CR LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .CR NLSPATH determines the location of message catalogues for the processing of .CR LC_MESSAGES . .SS International Code Set Support Single- and multibyte character code sets are supported. .SH DIAGNOSTICS .RS .TP 8 .CR ?\& Command error. Use .CR h or .CR H to get a detailed explanation. .TP .CI ? file Inaccessible file. Use .CR h or .CR H to get a detailed explanation. .RE .PP If changes have been made in the buffer since the last .CR w command that wrote the entire buffer, .CR ed warns you if you attempt to destroy the buffer with an .CR e or .CR q command. .CR ed displays .CR ?\& or .CR "warning: expecting `w'" , then continues normal editing unless you enter a second .CR e or .CR q command, in which case the second command is executed. The .CR -s or .CR - command-line option inhibits this feature. .SH EXAMPLES Make a simple substitution in .CR file-1 from a shell script, changing the first occurrence of .CR abc in any line to .CR xyz , and save the changes in .CR file-2 . .nf .IP .C "cat - << EOF | ed -s file-1" .C "1,$ s/abc/xyz/" .C "w file-2" .C "q" .C "EOF" .fi .PP Note that, if a command fails, the editor exits immediately. .SH WARNINGS A .CR !\& command cannot be subject to a .CR g or a .CR v command. .PP The .CR !\& command and the .CR !\& escape from the .CR e , .CR r , and .CR w commands cannot be used if the the editor is invoked from a restricted shell (see .IR sh (1)). .PP The sequence .CR \en in a regular expression does not match a newline character. .PP The .CR l command does not handle DEL correctly. .PP Files encrypted directly with the .CR crypt command with the null key cannot be edited (see .IR crypt (1)). .PP If the editor input is coming from a command file (e.g., .CR "ed file < ed-cmd-file)" , the editor exits at the first failure of a command in the command file. .PP When reading a file, .CR ed discards ASCII NUL characters and all characters after the last newline. This can cause unexpected behavior when using regular expressions to search for character sequences containing NUL characters or text near end-of-file. .SH AUTHOR .CR ed was developed by HP and OSF. .SH FILES .TP 10 .CI /tmp/e p Temporary buffer file where .I p is the process number. .PD 0 .TP .CR ed.hup Work is saved here if the terminal is hung up. .PD .SH SEE ALSO awk(1), csh(1), crypt(1), ex(1), grep(1), ksh(1), sed(1), sh(1), sh-bourne(1), sh-posix(1), stty(1), vi(1), fspec(4), environ(5), lang(5), regexp(5). .PP The .CR ed section in .IR "Text Processing: User's Guide" . .SH STANDARDS CONFORMANCE .CR ed ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR red ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4ed\f1 \- line-oriented text editor@@@\f3ed(1)\f1 .\" index@\f4red\f1 \- restricted line-oriented text editor@@@\f3ed(1)\f1 .\" index@line-oriented text editor@@@\f3ed(1)\f1 .\" index@editor: line-oriented@@@\f3ed(1)\f1 .\" index@text editor: line-oriented@@@\f3ed(1)\f1 .\" .\" toc@\f3ed(1)\f1:\0\0\f4ed\f1, \f4red\f1@@@line-oriented text editor .\" toc@\f4red\f1:\0\0restricted line-oriented text editor@@@see \f3ed(1)\f1 .\" .\" links@ed.1 red.1 .\" $Header: remsh.1,v 72.5 94/12/09 15:05:46 ssa Exp $ .TA r .TH remsh 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME remsh \- execute from a remote shell .SH SYNOPSIS .C remsh .I host .RC [ -l .IR username\| ] .RC [ -n ] .I command .br .I host .RC [ -l .IR username\| ] .RC [ -n ] .I command .PP .C rexec .I host .RC [ -l .IR username\| ] .RC [ -n ] .I command .SH DESCRIPTION .CR remsh connects to the specified .I host and executes the specified .IR command . The host name can be either the official name or an alias as understood by .CR gethostbyname() (see .IR gethostent (3N) and .IR hosts (4)). .CR remsh copies its standard input .RC ( stdin ) to the remote command, and the standard output of the remote command to its standard output .RC ( stdout ), and the standard error of the remote command to its standard error .RC ( stderr ). Hangup, interrupt, quit, terminate, and broken pipe signals are propagated to the remote command. .CR remsh exits when the sockets associated with .CR stdout and .CR stderr of the remote command are closed. This means that .CR remsh normally terminates when the remote command does (see .IR remshd (1M)). .PP By default, .CR remsh uses the following path when executing the specified .IR command : .IP .C "/usr/bin:/usr/ccs/bin:/usr/bin/X11:" .PP .CR remsh uses the default remote login shell with the .CR -c option to execute the remote command. If the default remote shell is .IR csh , csh sources the remote .CR .cshrc file before the command. .CR remsh cannot be used to run commands that require a terminal interface (such as .CR vi ) or commands that read their standard error (such as .CR more ). In such cases, use .CR rlogin or .CR telnet instead (see .IR rlogin (1) and .IR telnet (1)). .PP The remote account name used is the same as your local account name, unless you specify a different remote name with the .CR -l option. This remote account name must be equivalent to the originating account; no provision is made for specifying a password with a command. For more details about .IR equivalent hosts and how to specify them, see .IR hosts.equiv (4). The files inspected by .CR remshd on the remote host are .CR /etc/hosts.equiv and .CR $HOME/.rhosts (see .IR remshd (1M)). .PP If .IR command , is not specified, instead of executing a single command, you will be logged in on the remote host using .CR rlogin (see .IR rlogin (1)). Any .CR rlogin options typed in on the command line are transmitted to .CR rlogin . If .IR command is specified, options specific to .CR rlogin are ignored by .CR remsh . .PP By default, .CR remsh reads its standard input and sends it to the remote command because .CR remsh has no way to determine whether the remote command requires input. The .CR -n option redirects standard input to .CR remsh from .CR /dev/null . This is useful when running a shell script containing a .CR remsh command, since otherwise remsh may use input not intended for it. The .CR -n option is also useful when running .CR remsh in the background from a job control shell, .CR /usr/bin/csh or .CR /usr/bin/ksh . Otherwise, .CR remsh stops and waits for input from the terminal keyboard for the remote command. .CR /usr/bin/sh automatically redirects its input from .CR /dev/null when jobs are run in the background. .PP Host names for remote hosts can also be commands (linked to .CR remsh ) in the directory .CR /usr/hosts . If this directory is specified in the .CR $PATH environment variable, you can omit .CR remsh . For example, if .CR remotehost is the name of a remote host, .CR /usr/hosts/remotehost is linked to .CR remsh , and if .C /usr/hosts is in your search path, the command .IP .CR remotehost " command" .PP executes .CR command on .CR remotehost , and the command .IP .CR remotehost .PP is equivalent to .IP .CR rlogin " remotehost" .PP The .CR rexec command, a link to .CR remsh , works the same as .CR remsh except that it uses the .CR rexec() library routine and .CR rexecd for command execution (see .IR rexec (3N) and .IR rexecd (1M)). .CR rexec prompts for a password before executing the command instead of using .CR hosts.equiv for authentication. It should be used in instances where a password to a remote account is known but there are insufficient permissions for .CR remsh . .SH EXAMPLES Shell metacharacters that are not quoted are interpreted on the local host; quoted metacharacters are interpreted on the remote host. Thus the command line: .IP .C "remsh otherhost cat remotefile >> localfile" .PP appends the remote file .CR remotefile to the local file .CR localfile , while the command line .tr ~" .IP .C "remsh otherhost cat remotefile ~>>~ otherremotefile" .PP appends .CR remotefile to the remote file .CR otherremotefile . .tr ~~ .PP If the remote shell is .CR /usr/bin/sh , the following command line sets up the environment for the remote command before executing the remote command: .IP .C "remsh otherhost . .profile 2>&- \e; command" .PP The .CR 2>&- throws away error messages generated by executing .CR .profile when .IR stdin and .IR stdout are not a terminal. .PP The following command line runs .CR remsh in the background on the local system, and the output of the remote command comes to your terminal asynchronously: .IP .C "remsh otherhost -n command &" .PP The background .CR remsh completes when the remote command does. .PP The following command line causes .CR remsh to return immediately without waiting for the remote command to complete: .tr ~" .IP .C "remsh otherhost -n ~command 1>&- 2>&- &~" .PP (See .IR remshd (1M) and .IR sh (1)). If your login shell on the remote system is .IR csh , use the following form instead: .PP .RS 5 .C "remsh otherhost -n ~sh -c \e~command 1>&- 2>&- &\e~~" .RE .tr ~~ .SH RETURN VALUE If .CR remsh fails to set up the secondary socket connection, it returns 2. If it fails in some other way, it returns 1. If it fully succeeds in setting up a connection with .CR remshd , it returns 0 once the remote command has completed. Note that the return value of .CR remsh bears no relation to the return value of the remote command. .SH DIAGNOSTICS Besides the errors listed below, errors can also be generated by the library functions .C rcmd() and .C rresvport() which are used by .CR remsh (see .IR rcmd (3N)). Those errors are preceded by the name of the library function that generated them. .CR remsh can produce the following diagnostic messages: .RS .TP .C "rlogin: ..." Error in executing .C rlogin .RC ( rlogin is executed when the user does not specify any commands to be executed). This is followed by the error message specifying why the execution failed. .TP .C "shell/tcp: Unknown service" The ``shell'' service specification is not present in the .C /etc/services file. .TP .C "Can't establish stderr" .CR remsh cannot establish secondary socket connection for .CR stderr . .TP .IC "" : \0... Error in executing system call. Appended to this error is a message specifying the cause of the failure. .TP .CI "There is no entry for you (user ID " uid ") in /etc/passwd" Check with the system administrator to see if your entry in the password file has been deleted by mistake. .SH WARNINGS For security reasons, the .CR /etc/hosts.equiv and .CR .rhosts files should exist, even if empty, and should be readable and writable only by the owner. Note also that all information, including any passwords asked for, is passed unencrypted between the two hosts. .PP If .CR remsh is run with an interactive command it hangs. .SH DEPENDENCIES .CR remsh is the same service as .CR rsh on BSD systems. The name was changed due to a conflict with the existing System V command .CR rsh (restricted shell). .SH AUTHOR .CR remsh was developed by the University of California, Berkeley. .SH FILES .PD 0 .TP 19 .C /usr/hosts/* for version of the command invoked only with hostname .PD .SH SEE ALSO rlogin(1), remshd(1M), rexecd(1M), gethostent(3N), rcmd(3N), rexec(3N), hosts.equiv(4), hosts(4). .\" .\" index@\f4remsh\f1 \- execute from a remote shell@@@\f3remsh(1)\f1 .\" index@\f1execute from a remote shell@@@\f3remsh(1)\f1 .\" index@\f1remote shell, execute from a@@@\f3remsh(1)\f1 .\" index@\f1shell, remote, execute from a@@@\f3remsh(1)\f1 .\" .\" toc@\f3remsh(1)\f1:\0\0\f4remsh\f1@@@execute from a remote shell .\" .\" fileset_database@remsh.1 INETSVCS-MAN .\" $Header: tset.1,v 78.1 96/04/05 11:35:28 ssa Exp $ .TA t .TH tset 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tset, reset \- terminal-dependent initialization .SH SYNOPSIS .C tset .RI [ \|options\| ] .RC [ -m .RI [ \|ident\| ] .RI [ "\|test baudrate\|" ] .CR : \f2type\fP\|]\0... .RI [ \|type\| ] .PP .CR reset .SH DESCRIPTION .C tset sets up the terminal when logging in on an .SM HP-UX system. It does terminal-dependent processing, such as setting erase and kill characters, setting or resetting delays, and sending any sequences needed to properly initialize the terminal. It first determines the .I type of terminal involved, then does the necessary initializations and mode settings. The type of terminal attached to each .SM HP-UX port is specified in the .C /etc/ttytype data base. Type names for terminals can be found in the files under the .C /usr/share/lib/terminfo directory (see .IR terminfo (4)). If a port is not wired permanently to a specific terminal (not hardwired), it is given an appropriate generic identifier, such as .CR dialup . .PP .C reset performs a similar function, setting the terminal to a sensible default state. .PP In the case where no arguments are specified, .C tset simply reads the terminal type out of the environment variable .SM TERM and re-initializes the terminal. The rest of this manual entry concerns itself with mode and environment initialization, typically done once at login, and options used at initialization time to determine the terminal type and set up terminal modes. .PP When used in a startup script .RC ( .profile for Bourne shell, Korn shell, and .SM POSIX shell users, see .IR sh (1) and .IR ksh (1)), or .C .login for .IR csh (1) users) it is desirable to give information about the type of terminal that will normally be used on ports that are not hardwired. These ports are identified in .C /etc/ttytype as .C dialup or .CR plugboard , etc. To specify what terminal type you usually use on these ports, the .C -m (map) option flag is followed by the appropriate port type identifier, an optional baud rate specification, and the terminal type. (The effect is to "map" from some conditions to a terminal type; that is, to tell .CR tset that ``If I am on this kind of port, I will probably be on this kind of terminal''.) If more than one mapping is specified, the first applicable mapping prevails. A missing port type identifier matches all identifiers. A .I baudrate is specified as with .C stty (see .IR stty (1)), and is compared with the speed of the diagnostic output (which should be the control terminal). The baud rate .I test can be any combination of .CR > , .CR = , .CR < , \f3@\f1, and .CR !. \f3@\f1 is a synonym for .CR = , and .C ! inverts the sense of the test. To avoid problems with metacharacters, it is best to place the entire argument to .C -m within single quotes; users of .IR csh (1) must also put a .C \e before any .C ! used. .PP Thus, .IP .C "tset -m 'dialup>300:2622' -m 'dialup:2624' -m 'plugboard:?2623'" .PP causes the terminal type to be set to an .SM HP 2622 if the port in use is a dialup at a speed greater than 300 baud, or to an .SM HP 2624 if the port is otherwise a dialup (i.e. at 300 baud or less). If the .I type finally determined by .C tset begins with a question mark, the user is asked for verification that the type indicated is really the one desired. A null response means to use that type; otherwise, another type can be entered. Thus, in the above case, if the user is on a plugboard port, he or she will be asked whether or not he or she is actually using an HP 2623. .PP If no mapping applies and a final .I type option, not preceded by a .CR -m , is given on the command line, that type is used. Otherwise, the identifier found in the .C /etc/ttytype data base is taken to be the terminal type. The latter should always be the case for hardwired ports. .PP It is usually desirable to return the terminal type, as finally determined by .IR tset , and information about the terminal's capabilities to a shell's environment. This can be done using the .C -s option. From Bourne shell .RI ( sh (1)), the command: .IP .C eval `tset -s \f2options\fP...` .PP or using the C shell, .RI ( csh (1)): .IP .C "set noglob; eval `tset -s \f2options...\fP`" .PP These commands cause .C tset to generate as output a sequence of shell commands which place the variable .C TERM in the environment; see .IR environ (5). .PP Once the terminal type is known, .C tset engages in terminal mode setting. This normally involves sending an initialization sequence to the terminal, setting the single character erase (and optionally the full line erase or line-kill) characters, and setting special character delays. Tab and new-line expansion are turned off during transmission of the terminal initialization sequence. .PP On terminals that can backspace but not overstrike (such as a .SM CRT\s0), and when the erase character is the default erase character .RC ( # on standard systems), the erase character is changed to Back space .RC ( ^H ). .SS Options .C tset recognizes the following options: .RS .TP 8 .CI -e c Set the erase character to be the named character .IR c ; .I c defaults to .C ^H .SM (BACKSPACE). The character .I c can either be typed directly, or entered using circumflex notation used here (e.g., the circumflex notation for control-H is .CR ^H ; in Bourne shell the .C ^ character should be escaped .RC ( \e^ )). .TP .CI -k c Set the kill character to .IR c . The default .I c is .CR ^X . If .I c is not specified, the kill character remains unchanged unless the original value of the kill character is null, In which case the kill character is set to \f3@\f1. .TP .C - Report terminal type. Whatever type is decided on is reported. If no other flags are given, the only effect is to write the terminal type on the standard output. Has no effect if used with .CR -s . .TP .C -s Generate appropriate commands (depending on current .C SHELL environment variable) to set .CR TERM . .TP .C -I Suppress transmitting terminal initialization strings. .TP .C -Q Suppress printing the .C Erase set to and .C Kill set to messages. .TP .C -A Ask the user for the .C TERM type. .TP .C -S Output the strings that would be assigned to .C TERM in the environment rather than generating commands for a shell. In Bourne shell, the following is an alternate way of setting .CR TERM : .RS .IP .C "set -- `tset -S ...`" .br .C TERM=$1 .RE .TP .C -h Force a read of .CR /etc/ttytype . When .C -h is not specified, the terminal type is determined by reading the environment unless some mapping is specified. .RE .PP For compatibility with earlier versions of .CR tset , the following flags are accepted, but their use is discouraged: .RS .TP .C -r Report to the user in addition to other flags. .TP .CI -E c Set the erase character to .I c only if the terminal can backspace. .I c defaults to .CR ^H . .RE .PP In addition to capabilities described in .C terminfo (see .IR termio (7) and .IR terminfo (4)), the following boolean terminfo capabilities are understood by .C tset and .CR reset , and can be included in the terminfo database for the purpose of terminal setup: .RS .TP 8 .C UC ``Uppercase'' mode sets character mapping for terminals that support only uppercase characters. Equivalent to .CR "stty lcase" . .TP .C LC ``Lowercase'' mode permits input and output of lowercase characters. Equivalent to .CR "stty -lcase" . .TP .C EP Set ``even parity''. Equivalent to .CR "stty parenb -parodd .TP .C OP Set ``odd parity''. Equivalent to .CR "stty parenb parodd" . .TP .C NL Set ``new line'' mode. Equivalent to .CR "stty onlret" . .TP .C HD Set ``half-duplex'' mode. Equivalent to .CR "stty -echo" . .TP .C pt Set ``print tabs'' mode. Equivalent to .CR "stty tabs" . .RE .SH EXAMPLES These examples all assume the Bourne shell .RI ( sh-bourne (1)). Note that a typical use of .C tset in a .C .profile also uses the .C -e and .C -k options, and often the .C -m or .C -Q options as well. These options have been omitted here to keep the examples small. .PP Assume, for the moment, that you are on an .SM HP\|2622. This is suitable for typing by hand but not for a .C .profile unless you are .I always on a 2622. .IP .C "export TERM; TERM=`tset - 2622`" .PP Assume you have an .SM HP\|2623 at home which you dial up on, but your office terminal is hardwired and known in .CR /etc/ttytype . .IP .C "export TERM; TERM=`tset - -m dialup:2623`" .PP Suppose you are accessing the system through a switching network that can connect any system to any incoming modem line in an arbitrary combination, making it nearly impossible to key on what port you are coming in on. Your office terminal is an .SM HP\|2622, and your home terminal is an .SM HP\|2623 running at 1200 baud on dial-up switch ports. Sometimes you use someone else's terminal at work, so you want it to verify what terminal type you have at high speeds, but at 1200 baud you are always on a 2623. Note the placement of the question mark and the quotes to protect the .C > and .C ? from interpretation by the shell. .nf .IP .SM .C "export TERM; TERM=`tset - -m 'switch>1200:?2622' -m 'switch<=1200:2623'`" .fi .PP All of the above entries fall back on the terminal type specified in .C /etc/ttytype if none of the conditions hold. The following entry is appropriate if you always dial up, always at the same baud rate, on many different kinds of terminals. Your most common terminal is an .SM HP\|2622. It always asks you what kind of terminal you are on, defaulting to 2622. .IP .C "export TERM; TERM=`tset - ?2622`" .PP If the file .C /etc/ttytype is not properly installed and you want to key entirely on the baud rate, the following can be used: .IP .C export TERM; TERM=`tset - -m '>1200:2624' 2622` .SH FILES .TP 35 .PD 0 .C /etc/ttytype port-name to terminal-type mapping data base; .TP .C /usr/share/lib/terminfo/?/* terminal information data base. .PD .SH VARIABLES .TP 10 .C SHELL if .CR csh , generate .C csh commands; otherwise generate .C sh (Bourne or .SM POSIX shell) commands. .TP .C TERM the (canonical) terminal name. .SH AUTHOR .C tset was developed by the University of California, Berkeley. .SH SEE ALSO csh(1), sh(1), stty(1), ttytype(4), environ(5). .\" .\" index@\f4tset\f1 \- terminal-dependent initialization@@@\f3tset(1)\f1 .\" index@initialize terminal based on terminal type@@@\f3tset(1)\f1 .\" index@terminal, initialize based on terminal type@@@\f3tset(1)\f1 .\" .\" toc@\f3tset(1)\f1:\0\0\f4tset\f1@@@terminal-dependent initialization .\" .\" links@tset.1 reset.1 .\" .\" fileset_database@tset.1 USER-CMDS-MAN .\" $XConsortium: resize.man /main/11 1995/12/15 14:01:01 gildea $ .TH RESIZE 1 "Release 6.1" "X Version 11" .SH NAME resize \- set TERMCAP and terminal settings to current xterm window size .SH SYNOPSIS .B resize [ \fB\-u\fP | \fB\-c\fP ] [ \fB\-s\fP [ \fIrow col\fP ] ] .SH DESCRIPTION .I Resize prints a shell command for setting the TERM and TERMCAP environment variables to indicate the current size of \fIxterm\fP window from which the command is run. For this output to take effect, \fIresize\fP must either be evaluated as part of the command line (usually done with a shell alias or function) or else redirected to a file which can then be read in. From the C shell (usually known as \fI/bin/csh\fP), the following alias could be defined in the user's \fI.cshrc\fP: .sp .nf % alias rs 'set noglob; eval \fC`\fPresize\fC`\fP' .fi .sp After resizing the window, the user would type: .sp .nf % rs .fi .sp Users of versions of the Bourne shell (usually known as \fI/bin/sh\fP) that don't have command functions will need to send the output to a temporary file and the read it back in with the ``.'' command: .sp .nf $ resize > /tmp/out $ .\0/tmp/out .fi .SH OPTIONS The following options may be used with \fIresize\fP: .TP 8 .B \-u This option indicates that Bourne shell commands should be generated even if the user's current shell isn't \fI/bin/sh\fP. .TP 8 .B \-c This option indicates that C shell commands should be generated even if the user's current shell isn't \fI/bin/csh\fP. .TP 8 .B \-s \fR[\fIrows columns\fP] This option indicates that Sun console escape sequences will be used instead of the special \fIxterm\fP escape code. If \fIrows\fP and \fIcolumns\fP are given, \fIresize\fP will ask the \fIxterm\fP to resize itself. However, the window manager may choose to disallow the change. .SH FILES .TP 15 /etc/termcap for the base termcap entry to modify. .TP 15 ~/.cshrc user's alias for the command. .SH "SEE ALSO" csh(1), tset(1), xterm(1) .SH AUTHORS Mark Vandevoorde (MIT-Athena), Edward Moy (Berkeley) .br Copyright (c) 1984, 1985 by X Consortium .br See .IR X (1) for a complete copyright notice. .SH BUGS The \fB\-u\fP or \fB\-c\fP must appear to the left of \fB\-s\fP if both are specified. .\" $Header: rev.1,v 72.3 93/01/14 11:37:54 ssa Exp $ .TA r .TH rev 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rev \- reverse lines of a file .SH SYNOPSIS .C rev .RI [ \|file\| ]\ ... .SH DESCRIPTION .C rev copies the named files to the standard output, reversing the order of characters in every line. If no file is specified, the standard input is copied. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text as single- and/or multi-byte characters. .PP If .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .I rev behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" toc@\f3rev(1)\f1:\0\0\f4rev\f1@@@reverse lines of a file .\" .\" index@\f4rev\f1 \- reverse the text character sequence in each line of a file@@@\f3rev(1)\f1 .\" index@reverse the left-to-right text character sequence in each line of a file@@@\f3rev(1)\f1 .\" index@files: reverse the left-to-right text character sequence in each line of a file@@@\f3rev(1)\f1 .\" index@text processors: reverse the left-to-right text character sequence in each line of a file@@@\f3rev(1)\f1 .\" index@swap the left-to-right text character sequence in each line of a file@@@\f3rev(1)\f1 .\" index@left-to-right text character sequence in each line of a file, reverse the@@@\f3rev(1)\f1 .\" .\" fileset_database@rev.1 USER-CMDS-MAN .\" $Header: lpfilter.1,v 72.4 94/07/05 17:17:26 ssa Exp $ .TA l .TH lpfilter 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lpfilter, divpage, fontdl, lprpp, plotdvr, printstat, reverse \- filters invoked by lp interface scripts .SH SYNOPSIS .C /usr/lbin/divpage .RC [ -p \(or .CR -l ] .RC [ -h \(or .CR -q ] .RC [ -n\c .IR FontID\| ] .I filename .PP .C /usr/lbin/fontdl .RC [ -n\c .IR FontID\| ] .RC [ -l ] .RC [ -p ] .I filename .PP .C /usr/lbin/lprpp .RC [ -i ] .RC [ -o ] .RC [ -e ] .RC [ -l\c .IR nn\| ] .RC [ -n ] .RC [ -p ] .PP .C /usr/lbin/plotdvr .CI -l \|request_id .CI -u \|username .RC [ -e ] .RC [ -f ] .RC [ -i ] .I filename .PP .C /usr/sbin/printstat .CI -l \|request_id .CI -u \|username .I filename .PP .C /usr/sbin/reverse .RC [ -l .IR page_length\| ] .SS Remarks The structure of these filters is currently under review. They may become obsolete or be restructured in a future release. .SH DESCRIPTION Various filters are used by the .C lp subsystem to obtain specialized behavior for specific types of devices or data. This entry describes currently supported filters. .PP A number of these filters use a specified .I username and .I filename to determine the location of the user who originated the print message. .PP The .I filename is used to determine the .I hostname of the system where the request originated, and must have the form .RI [ dirname ]\c .CI /d?A \|nnnhostname or .RI [ dirname ]\c .CI /dA \|nnnnhostname\f1, where .I dirname is not a path name, but only the name of the basename's parent directory. .I filename meets this requirement when it is set to .C $6 in the interface script for the printer. .SS divpage Provides capabilities for printing multiple pages per sheet and selection of built-in fonts. .PP .C Options: .RS .TP 15 .C -p Set mode to portrait (default). .TP .C -l Set mode to landscape. .TP .C -h Print half pages (default). .TP .C -q Print quarter pages. .TP .CI -n \|FontID Use font number .IR FontID . Default is 0. Causes the string .CI \s-2\uE\dC\s0( \|Font\s-1ID\s0 X to be sent to the printer. .RE .SS fontdl .I fontdl downloads the font contained in .I filename to a printer connected to standard output. .PP .C Options: .RS .TP 15 .CI -n \|FontID Specifies the ID number by which the font will be referenced. Default is 0. .TP .C -l Specify landscape mode. Default is portrait. .TP .C -p Specifies proportional spacing. Default is fixed. .RE .SS lprpp This is a filter that converts backspace overstrike to line overprint with horizontal print positioning to enhance bold print. This functionality is required on printers such as the LaserJet, which cannot produce bold print by overstriking. .PP .C Options: .RS .TP 15 .C -i Converts to _ to italicize ANYCHAR. Also properly italicizes overstruck (bold) characters. Does .I not work correctly for "hashed-overstrike" such as: .br \0 .br \0\0\0\0\0\0_ .TP .C -o Prints only the odd numbered pages. Used with .C -e for double-sided printing. .TP .C -e Print only the even numbered pages. Used with .C -o for double sided printing. .TP .CI -l \|nn Specifies the page length, in lines. Default is 60 unless .I -n or .I -p is selected, in which case it is 66. .TP .C -n Specifies nroff mode for printing output of the .I nroff command. Prints 66 lines per page with the first line appearing on logical line 4 of the printer. .TP .C -p Specifies pr mode for printing output from the .I pr command. Prints 66 lines per page with the first line appearing on logical line 3 of the printer. .SS plotdvr HP-GL plotter filter. This filter scans the data for "PG" commands (paper feed). When this data is encountered, the filter strips it from the data stream and informs the requesting user of the need to change paper in the plotter. .PP Options: .RS .TP 15 .CI -l \|request_id Specifies the printer request ID and is used in various messages regarding the plot request. .TP .CI -u \|username The requesting user's login name, used to communicate with the user regarding the request. .TP .C -e Specifies the use of escape sequences, rather than HP-GL commands, to determine plotter status. .TP .C -f Plot without stopping for paper changes. The "PG" commands are not stripped from the data stream and the user is not notified of them. This option is used on plotters capable of automatic page feed. .TP .C -i Prevents initialization of the plotter. .RE .SS printstat Interrogates an RS232 printer as to its status, and does not return until the printer is ready. If the printer is .IR off-line , .IR "out of paper" , or .IR disconnected , the submitter of the print request is notified of this condition periodically until it is corrected. When the printer is ready to print, the command exits. .PP Standard input and standard output must both be connected to the serial printer device. .PP This program uses the .I send-status command .C \s-2\uE\dC\s0?\s-2\uD\d1\s0? to determine status. Not all serial printers respond to this command. Only the following configurations support this command: .RS .PP .TS box; cB | cB l | l. Printer Comments _ LaserJet Not supported LaserJetII Supported LaserJetIID Requires \s-1HP\|26013A\s0 module LaserJetIIP Not supported LaserJetIII Requires \s-1HP\|26013A\s0 module LaserJet2000 Not supported .TE .RE .PP .C Options: .RS .TP 15 .CI -l \|request-id Print request ID used in various communications with the user. .TP .CI -u \|username The requesting user's login name, used to communicate with the user regarding the request. .RE .SS reverse Prints the data appearing on the standard input in reverse page order to the standard output. This command can handle up to 2000 pages. .PP .C Options: .RS .TP 15 .CI -l \|page_length Specifies the page length, in lines. Default is 66. .RE .SH DIAGNOSTICS Error and diagnostic messages appear on the printed output, on the user's terminal, or are mailed to the user, depending on circumstances. .SH WARNINGS There is little consistency in the interface to these filters. .SH SEE ALSO lp(1), lpadmin(1). .PP .IR "HP-UX System Administration Manual" . .\" .\" index@\f4lpfilter\f1 \- filters invoked by lp interface scripts@@@\f3lpfilter(1)\f1 .\" index@\f4divpage\f1 \- divide pages for two-sided printing@@@\f3lpfilter(1)\f1 .\" index@\f4fontdl\f1 \- download fonts to printer@@@\f3lpfilter(1)\f1 .\" index@\f4hp2686a\f1 \- laserjet filter@@@\f3lpfilter(1)\f1 .\" index@\f4hp2934a\f1 \- character printer filter@@@\f3lpfilter(1)\f1 .\" index@\f4lprpp\f1 \- laserjet filter@@@\f3lpfilter(1)\f1 .\" index@\f4plotdvr\f1 \- plotter driver for lp@@@\f3lpfilter(1)\f1 .\" index@\f4printstat\f1 \- check status of serial printer@@@\f3lpfilter(1)\f1 .\" index@\f4reverse\f1 \- reverse printer pages for collating@@@\f3lpfilter(1)\f1 .\" .\" toc@\f3lpfilter(1)\f1:\0\0\f4lpfilter\f1@@@filters used by the lp interface scripts .\" .\" links@lpfilter.1 divpage.1 .\" links@lpfilter.1 fontdl.1 .\" links@lpfilter.1 lprpp.1 .\" links@lpfilter.1 plotdvr.1 .\" links@lpfilter.1 printstat.1 .\" links@lpfilter.1 reverse.1 .TH RGB 1 "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .SH NAME rgb - X Window System color database creator. .SH SYNOPSIS .B rgb [\fIfilename\fP] [\fI" " new-line space tab" .TP .B blank A tab or space character. .TP .B identifier A sequence of letters, digits, or underscores starting with a letter or underscore. Identifiers are used as names for .B functions and .BR "named parameters" . .TP .B word A sequence of characters separated by one or more non-quoted metacharacters . .TP .B command A sequence of characters in the syntax of the shell language. The shell reads each command and carries out the desired action, either directly or by invoking separate utilities. .TP .B special command A command that is carried out by the shell without creating a separate process. Often called ``built-in commands''. Except for documented side effects, most special commands can be implemented as separate utilities. .TP .C # The .C # character is interpreted as the beginning of a comment. See .I Quoting below. .SS Commands A .B simple-command is a sequence of blank-separated words that can be preceded by a parameter assignment list. (See .I Environment below). The first word specifies the name of the command to be executed. Except as specified below, the remaining words are passed as arguments to the invoked command. The command name is passed as argument 0 (see .IR exec (2)). The .B value of a simple-command is its exit status if it terminates normally, or (octal) 200+\c .B status if it terminates abnormally (see .IR signal (5) for a list of status values). .PP A .B pipeline is a sequence of one or more .B commands separated by .CR | . The standard output of each command except the last is connected by a pipe (see .IR pipe (2)) to the standard input of the next command. Each command is run as a separate process; the shell waits for the last command to terminate. The exit status of a pipeline is the exit status of the last command in the pipeline. .PP A .B list is a sequence of one or more pipelines separated by .CR ; , .CR & , .CR && , or .CR || , and optionally terminated by .CR ; , .CR & , or .CR |& . Of these five symbols, .CR ; , .CR & , and .CR |& have equal precedence. .C && and .C || have a higher but also equal precedence. A semicolon .RC ( ; ) causes sequential execution of the preceding pipeline; an ampersand .RC ( & ) causes asynchronous execution of the preceding pipeline (that is, the shell does not wait for that pipeline to finish). The symbol .C |& causes asynchronous execution of the preceding command or pipeline with a two-way pipe established to the parent shell (known as a co-process). The standard input and output of the spawned command can be written to and read from by the parent shell using the .C -p option of the special commands .C read and .C print described later. The symbol .C && .RC (\| || ) causes the .I list following it to be executed only if the preceding pipeline returns a zero (non-zero) value. An arbitrary number of new-lines can appear in a .IR list , instead of semicolons, to delimit commands. .PP A .B command is either a simple-command or one of the following. Unless otherwise stated, the value returned by a command is that of the last simple-command executed in the command. .TP 15 .CR for\0 \f2identifier\fP\0[\| in " \f2word\fP ...\|] " "do \f2list\fP done" Each time .C for is executed, .I identifier is set to the next .I word taken from the .C in .I word list. If .CI in " word" \&... is omitted, .C for executes the .C do .I list once for each positional parameter set (see .I Parameter Substitution below). Execution ends when there are no more words in the list. .TP .CR select\0 \f2identifier\fP\0[\| in\0\f2word\fP ...\|] " do \f2list\fP done" A .C select command prints on standard error (file descriptor 2), the set of .IR word s, each preceded by a number. If .CI in " word" \&... is omitted, the positional parameters are used instead (see .I Parameter Substitution below). The .C PS3 prompt is printed and a line is read from the standard input. If this line consists of the number of one of the listed .IR word s, the value of the parameter .I identifier is set to the .I word corresponding to this number. If this line is empty, the selection list is printed again. Otherwise the value of the parameter .I identifier is set to null. The contents of the line read from standard input is saved in the parameter .CR REPLY . The .I list is executed for each selection until a .C break or end-of-file .RI ( eof ) is encountered. .TP .CR "case \f2\s-1word\s0\fP in \f1\s-1[\|[\|\fP\s0(" "\|] \f2pattern\fP [\| " | "\f2pattern\fP\|] ... " ") \f2\s-1list\s0\fP ;;\f1\s-1\|] ...\s0\fP esac" '''\" \s-1 and \s0 in above line are to compensate for larger point '''\" size used for .C font. A .C case command executes the .I list associated with the first .I pattern that matches .IR word . The form of the patterns is identical to that used for file name generation (see .I File Name Generation below). .TP .CR "if \f2\s-1list\s0\fP then \f2list\fP \f1\s-1[\|\fP\s0elif \f2\s-1list\s0\fP then" " \f2list\fP\|] ... [\|" "else \f2\s-1list\s0\fP" \|] fi '''\" \s-1 and \s0 in above line are to compensate for larger point '''\" size used for .C font. The .I list following .C if is executed and, if it returns a zero exit status, the .I list following the first .C then is executed. Otherwise, the .I list following .C elif is executed and, if its value is zero, the .I list following the next .C then is executed. Failing that, the .C else .I list is executed. If no .C else .I list or .C then .I list is executed, .C if returns a zero exit status. .TP .PD 0 .CI while \0list \0do \0list \0done .TP .CI until \0list \0do \0list \0done A .C while command repeatedly executes the .C while .IR list , and if the exit status of the last command in the list is zero, executes the .C do .IR list ; otherwise the loop terminates. If no commands in the .C do .I list are executed, .C while returns a zero exit status; .C until can be used in place of .C while to negate the loop termination test. .PD .TP .CI (\| list \|) Execute .I list in a separate environment. If two adjacent open parentheses are needed for nesting, a space must be inserted to avoid arithmetic evaluation as described below. .TP .CI {\| \0list \|;} Execute .IR list , but not in a separate environment. Note that .C { is a keyword and requires a trailing blank to be recognized. .TP .CI [[\| \0expression\0 \|]] Evaluates .I expression and returns a zero exit status when .I expression is true. See .I Conditional Expressions below, for a description of .IR expression . Note that .C [[ and .C ]] are keywords and require blanks between them and .IR expression . .TP .PD 0 .CI function \0identifier \0{\| list \|;} .TP .IC identifier \0()\0{\| list \|;} .PD Define a function referred to by .IR identifier . The body of the function is the .I list of commands between .C { and .C } (see .I Functions below). .TP .CI time \0pipeline .I pipeline is executed and the elapsed time, user time, and system time are printed on standard error. .PP The following keywords are recognized only as the first word of a command and when not quoted: .IP .C "if then else elif fi case esac for while" .C "until do done { } function select time [[ ]]" .SS Comments A word beginning with .C # causes that word and all subsequent characters up to a new-line to be ignored. .SS Aliasing The first word of each command is replaced by the text of an .BR alias , if an alias for this word has been defined. An .B alias name consists of any number of characters excluding metacharacters, quoting characters, file expansion characters, parameter and command substitution characters, and .CR = . The replacement string can contain any valid shell script, including the metacharacters listed above. The first word of each command in the replaced text, other than any that are in the process of being replaced, is tested for additional aliases. If the last character of the alias value is a .IR blank , the word following the alias is also checked for alias substitution. Aliases can be used to redefine special built-in commands, but cannot be used to redefine the keywords listed above. Aliases can be created, listed, and exported with the .C alias command and can be removed with the .C unalias command. Exported aliases remain in effect for subshells but must be reinitialized for separate invocations of the shell (see .I Invoking ksh below). .PP .I Aliasing is performed when scripts are read, not while they are executed. Therefore, for it to take effect, .C alias must be executed before the command referring to the alias is read. .PP Aliases are frequently used as a shorthand for full path names. An option to the aliasing facility allows the value of the alias to be automatically set to the full path name of the corresponding command. These aliases are called .IR "tracked aliases" . The value of a tracked alias is defined the first time the identifier is read and becomes undefined each time the .C PATH variable is reset. These aliases remain tracked so that the next reference redefines the value. Several tracked aliases are compiled into the shell. The .C -h option of the .C set command converts each command name that is an .I identifier into a tracked alias. .PP The following .I exported aliases are compiled into the shell but can be unset or redefined: .IP .ift .sp -1v .nf .C autoload='typeset -fu' .C false='let 0' .C functions='typeset -f' .C hash='alias -t -' .C history='fc -l' .C integer='typeset -i' .C nohup='nohup ' .C r='fc -e -' .C stop='kill -STOP' .C suspend='kill -STOP $$' .C true=':' .C type='whence -v' .fi .SS Tilde Substitution After alias substitution is performed, each word is checked to see if it begins with an unquoted .CR ~ . If it does, the word up to a .C / is checked to see if it matches a user name in the .C /etc/passwd file. If a match is found, the .C ~ and the matched login name are replaced by the login directory of the matched user. This is called a tilde substitution. If no match is found, the original text is left unchanged. A .CR ~ , alone or before a .CR / , is replaced by the value of the .C HOME parameter. A .C ~ followed by a .C + or .C - is replaced by the value of the parameter .C PWD and .CR OLDPWD , respectively. In addition, tilde substitution is attempted when the value of a parameter assignment begins with a .CR ~ . .SS Command Substitution The standard output from a command enclosed in parenthesis preceded by a dollar sign .RC (\| $(\f2command\fP) \|) or a pair of back single quotes (accent grave) .RC (\| \(ga\f2command\fP\(ga \|) can be used as part or all of a word; trailing new-lines are removed. In the second (archaic) form, the string between the quotes is processed for special quoting characters before the command is executed (see .I Quoting below). The command substitution .C $(cat file) can be replaced by the equivalent but faster .CR "$( followed by a space character. .TP .C PS3 Selection prompt string used within a .C select loop, by default .C #? followed by a space character. .TP .C PS4 The value of this variable is expanded for parameter substitution and precedes each line of an execution trace. If .C PS4 is unset, the execution trace prompt is .C + followed by a space character. .TP .C SHELL The path name of the shell is kept in the environment. When invoked, the shell is restricted if the value of this variable contains an .C r in the basename. .TP .C TMOUT If set to a value greater than zero, the shell terminates if a command is not entered within the prescribed number of seconds after issuing the .C PS1 prompt. .TP .C VISUAL Invokes the corresponding option when the value of this variable ends in .IR emacs , .IR gmacs , or .I vi (see .C set in .I Special Commands below). .PD .RE .PP The shell gives default values to .CR PATH , .CR PS1 , .CR PS2 , .CR MAILCHECK , .CR TMOUT , and .CR IFS . .CR HOME , .CR SHELL , .CR ENV , and .C MAIL are never set automatically by the shell (although .CR HOME , .CR SHELL , and .CR MAIL are set by .IR login (1)). .SS Blank Interpretation After parameter and command substitution, the results of substitution are scanned for field separator characters (found in .CR IFS ), and split into distinct arguments where such characters are found. .C ksh retains explicit null arguments .RC ( "\|" or .CR '\|' ) but removes implicit null arguments (those resulting from .I parameters that have no values). .SS File Name Generation Following substitution, each command .I word is processed as a pattern for file name expansion unless the .C -f option has been .CR set . The form of the patterns is the Pattern Matching Notation defined by .IR regexp (5). The word is replaced with sorted file names matching the pattern. If no file name is found that matches the pattern, the word is left unchanged. .PP In addition to the notation described in .IR regexp (5), .C ksh recognizes composite patterns made up of one or more pattern lists separated from each other with a .CR | . Composite patterns can be formed with one or more of the following: .RS .TP 20 .CI ?( pattern-list ) Optionally matches any one of the given patterns. .TP .CI *( pattern-list ) Matches zero or more occurrences of the given patterns. .TP .CI +( pattern-list ) Matches one or more occurrences of the given patterns. .TP .ifn \f3\&@\&(\fP\f2pattern-list\fP\f3)\fP .ift \f4\s+1\&@\&\s-1(\fP\f2pattern-list\fP\f4)\fP Matches exactly one of the given patterns. .TP .CI !( pattern-list ) Matches anything, except one of the given patterns. .RE .SS Quoting Each of the .I metacharacters listed above (See .I Definitions above) has a special meaning to the shell and causes termination of a word unless quoted. A character can be .I quoted (i.e., made to stand for itself) by preceding it with a .CR \e . The pair .CI \e new-line is ignored. All characters enclosed between a pair of single quote marks .RC ( '\|' ), are quoted. A single quote cannot appear within single quotes. Inside double quote marks .ifn (\f3""\fP), .ift (\f4"\|"\fP), parameter and command substitution occurs and .C \e quotes the characters .CR \e , .CR \(ga , .ifn \f3"\fP, .ift \f4"\fP, and .CR $ . .C $* and .ifn \f3\s+1$@\s0\fP .ift \f4\s+1$@\s0\fP have identical meanings when not quoted or when used as a parameter assignment value or as a file name. However, when used as a command argument, .C "$*" is equivalent to .ifn \f3"$1\fP\f2d\fP\f3\|$2\fP\f2d\fP\...\f3"\fP, .ift \f4"$1\fP\f2d\fP\f4\|$2\fP\f2d\fP\|...\f4"\fP, where .I d is the first character of the .C IFS parameter, whereas .ifn \f3"$\s+1@"\s0\fP .ift \f4"$\s+1@"\s0\fP is equivalent to .C "$1"\| .C "$2"\| \&...\|. Inside back single quote (accent grave) marks .RC ( \(ga\|\(ga ) .C \e quotes the characters .CR \e , .CR \(ga , and .CR $ . If the back single quotes occur within double quotes, .CR \e also quotes the character .ifn \f3"\fP. .ift \f4"\fP. .PP The special meaning of keywords or aliases can be removed by quoting any character of the keyword. The recognition of function names or special command names listed below cannot be altered by quoting them. .SS Arithmetic Evaluation The ability to perform integer arithmetic is provided with the special command .CR let . Evaluations are performed using long arithmetic. Constants take the form .RC [\|\f2base\fP # \|]\f2n\fP, where .I base is a decimal number between two and thirty-six representing the arithmetic base and .I n is a number in that base. If .I base is omitted, base 10 is used. .PP An arithmetic expression uses the same syntax, precedence, and associativity of expression of the C language. All the integral operators, other than .CR ++ , .CR -\|- , .CR ?: , and .C , are supported. Variables can be referenced by name within an arithmetic expression without using the parameter substitution syntax. When a variable is referenced, its value is evaluated as an arithmetic expression. .PP An internal integer representation of a .I variable can be specified with the .C -i option of the .C typeset special command. Arithmetic evaluation is performed on the value of each assignment to a variable with the .C -i attribute. If you do not specify an arithmetic base, the first assignment to the variable determines the arithmetic base. This base is used when parameter substitution occurs. .PP Since many of the arithmetic operators require quoting, an alternative form of the .C let command is provided. For any command beginning with .CR (( , all characters until the matching .C )) are treated as a quoted expression. More precisely, .CR (( \&...\& )) is equivalent to .C let .ifn \f3"\fP\|...\f3"\fP. .ift \f4"\fP\|...\f4"\fP. .SS Prompting When used interactively, the shell prompts with the value of .C PS1 before reading a command. If at any time a new-line is typed and further input is needed to complete a command, the secondary prompt (the value of .CR PS2 ) is issued. .SS Conditional Expressions. A .I conditional expression is used with the .C [[ compound command to test attributes of files and to compare strings. Word splitting and file name generation are not performed on the words between .C [[ and .CR ]] . Each expression can be constructed from one or more of the following unary or binary expressions: .RS .TP 20 .CI -a \0file True if .I file exists. .PD 0 .TP .CI -b \0file True if .I file exists and is a block special file. .TP .CI -c \0file True if .I file exists and is a character special file. .TP .CI -d \0file True if .I file exists and is a directory. .TP .CI -f \0file True if .I file exists and is an ordinary file. .TP .CI -g \0file True if .I file exists and is has its setgid bit set. .TP .CI -h \0file True if .I file exists and is a a symbolic link. .TP .CI -k \0file True if .I file exists and is has its sticky bit set. .TP .CI -n \0string True if length of .I string is non-zero. .TP .CI -o \0option True if option named .I option is on. .TP .CI -p \0file True if .I file exists and is a fifo special file or a pipe. .TP .CI -r \0file True if .I file exists and is readable by current process. .TP .CI -s \0file True if .I file exists and has size greater than zero. .TP .CI -t \0fildes True if file descriptor number .I fildes is open and associated with a terminal device. .TP .CI -u \0file True if .I file exists and is has its setuid bit set. .TP .CI -w \0file True if .I file exists and is writable by current process. .TP .CI -x \0file True if .I file exists and is executable by current process. If .I file exists and is a directory, the current process has permission to search in the directory. .TP .CI -z \0string True if length of .I string is zero. .TP .CI -H \0file True if .I file exists and is a hidden directory (see .IR cdf (4)). .TP .CI -L \0file True if .I file exists and is a symbolic link. .TP .CI -O \0file True if .I file exists and is owned by the effective user .SM ID of this process. .TP .CI -G \0file True if .I file exists and its group matches the effective group .SM ID of this process. .TP .CI -S \0file True if .I file exists and is a socket. .TP .IC file1 \0-nt \0file2 True if .I file1 exists and is newer than .IR file2 . .TP .IC file1 \0-ot \0file2 True if .I file1 exists and is older than .IR file2 . .TP .IC file1 \0-ef \0file2 True if .I file1 and .I file2 exist and refer to the same file. .TP .IC string \0= \0pattern True if .I string matches .IR pattern . .TP .IC string \0!= \0pattern True if .I string does not match .IR pattern . .TP .IC string1 \0< \0string2 True if .I string1 comes before .I string2 based on .SM ASCII value of their characters. .TP .IC string1 \0> \0string2 True if .I string1 comes after .I string2 based on .SM ASCII value of their characters. .TP .IC exp1 \0-eq \0exp2 True if .I exp1 is equal to .IR exp2 . .TP .IC exp1 \0-ne \0exp2 True if .I exp1 is not equal to .IR exp2 . .TP .IC exp1 \0-lt \0exp2 True if .I exp1 is less than .IR exp2 . .TP .IC exp1 \0-gt \0exp2 True if .I exp1 is greater than .IR exp2 . .TP .IC exp1 \0-le \0exp2 True if .I exp1 is less than or equal to .IR exp2 . .TP .IC exp1 \0-ge \0exp2 True if .I exp1 is greater than or equal to .IR exp2 . .PD .RE .PP A compound expression can be constructed from these primitives by using any of the following, listed in decreasing order of precedence. .RS .TP 35 .CI ( expression ) True, if .I expression is true. Used to group expressions. .PD 0 .TP .CI ! \0expression True if .I expression is false. .TP .IC expression1 \0&& \0expression2 True, if .I expression1 and .I expression2 are both true. .TP .IC expression1 \0|| \0expression2 True, if either .I expression1 or .I expression2 is true. .PD .RE .SS Input/Output Before a command is executed, its input and output can be redirected using a special notation interpreted by the shell. The following can appear anywhere in a simple-command or can precede or follow a command and are not passed on to the invoked command. Command and parameter substitution occurs before .I word or .I digit is used, except as noted below. File name generation occurs only if the pattern matches a single file and blank interpretation is not performed. .RS .TP 15 .CI < word Use file .I word as standard input (file descriptor .CR 0 ). .TP .CI > word Use file .I word as standard output (file descriptor .CR 1 ). If the file does not exist, it is created. If the file exists, and the .C noclobber option is on, an error occurs; otherwise, the file is truncated to zero length. .TP .CI >| word Sames as .CR > , except that it overrides the .C noclobber option. .TP .CI >> word Use file .I word as standard output. If the file exists, output is appended to it (by first searching for the end-of-file); otherwise, the file is created. .TP .CI <> word Open file .I word for reading and writing as standard input. If the file does not exist it is created. .TP .CR << [\| - \|]\f2word\fP The shell input is read up to a line that matches .IR word , or to an end-of-file. No parameter substitution, command substitution, or file name generation is performed on .IR word . The resulting document, called a .IR here-document , becomes the standard input. If any character of .I word is quoted, no interpretation is placed upon the characters of the document. Otherwise, parameter and command substitution occurs, .CI \e new-line is ignored, and .C \e must be used to quote the characters .CR \e , .CR $ , .CR \(ga , and the first character of .IR word . If .C - is appended to .CR << , all leading tabs are stripped from .I word and from the document. .TP .CI <& digit The standard input is duplicated from file descriptor .I digit (see .IR dup (2)). .TP .CI >& digit The standard output is duplicated to file descriptor .I digit (see .IR dup (2)). .TP .C <&- The standard input is closed. .TP .C >&- The standard output is closed. .TP .C <&p The input from the co-process is moved to standard input. .TP .C >&p The output to the co-process is moved to standard output. .RE .PP If one of the above is preceded by a digit, the file descriptor number cited is that specified by the digit (instead of the default .C 0 or .CR 1 ). For example: .IP .RC \&... \02>&1 .PP means file descriptor 2 is to be opened for writing as a duplicate of file descriptor 1. .PP Redirection order is significant because the shell evaluates redirections referencing file descriptors in terms of the currently open file associated with the specified file descriptor at the time of evaluation. For example: .IP .RC ... \01>\f2fname\fP\02>&1 .PP first assigns file descriptor 1 (standard output) to file .IR fname , then assigns file descriptor 2 (standard error) to the file assigned to file descriptor 1; i.e., .IR fname . On the other hand, if the order of redirection is reversed as follows: .IP .RC ... \02>&1\01>\f2fname\fP .PP file descriptor 2 is assigned to the current standard output (user terminal unless a different assignment is inherited). File descriptor 1 is then reassigned to file .I fname without changing the assignment of file descriptor 2. .PP The input and output of a .I co-process can be moved to a numbered file descriptor allowing other commands to write to them and read from them using the above redirection operators. If the input of the current .I co-process is moved to a numbered file descriptor, another .I co-process can be started. .PP If a command is followed by .C & and job control is inactive, the default standard input for the command is the empty file .CR /dev/null . Otherwise, the environment for the execution of a command contains the file descriptors of the invoking shell as modified by input/output specifications. .SS Environment The .B environment (see .IR environ (5)) is a list of name-value pairs passed to an executed program much like a normal argument list. The names must be .B identifiers and the values are character strings. The shell interacts with the environment in several ways. When invoked, the shell scans the environment and creates a parameter for each name found, gives it the corresponding value, and marks it .IR export . Executed commands inherit the environment. If the user modifies the values of these parameters or creates new ones by using the .C export or .C typeset -x commands, the values become part of the environment. The environment seen by any executed command is thus composed of any name-value pairs originally inherited by the shell whose values can be modified by the current shell, plus any additions which must be noted in .C export or .C typeset -x commands. .PP The environment for any .I simple-command or function can be augmented by prefixing it with one or more parameter assignments. A parameter assignment argument takes the form .IC identifier = value\f1. For example, .IP .CI TERM=450 \0cmd\0args .PP and .IP .CI (export\0TERM;\0TERM=450; \0cmd\0args ) .PP are equivalent (as far as the above execution of .I cmd is concerned except for special commands listed below that are preceded by a dagger). .PP If the .C -k option is set, all parameter assignment arguments are placed in the environment, even if they occur after the command name. The following echo statement prints .CR "a=b c" . After the .C -k option is set, the second echo statement prints only .CR c : .IP .C echo a=b c .br .C set -k .br .C echo a=b c .PP This feature is intended for use with scripts written for early versions of the shell, and its use in new scripts is strongly discouraged. It is likely to disappear someday. .SS Functions The .C function keyword (described in the .I Commands section above) is used to define shell functions. Shell functions are read and stored internally. Alias names are resolved when the function is read. Functions are executed like commands, with the arguments passed as positional parameters (see .I Execution below). .PP Functions execute in the same process as the caller except that command substitution of a function creates a new process. Functions share all files and present working directory with the caller. Traps caught by the caller are reset to their default action inside the function. If a function does not catch or specifically ignore a trap condition, the function terminates and the condition is passed on to the caller. A trap on .C EXIT set inside a function is executed after the function completes in the environment of the caller. Ordinarily, variables are shared between the calling program and the function. However, the .C typeset special command used within a function defines local variables whose scope includes the current function and all functions it calls. .PP The special command .C return is used to return from function calls. Errors within functions return control to the caller. .PP Function identifiers can be listed with the .C +f option of the .C typeset special command. Function identifiers and the associated text of the functions can be listed with the .C -f option. Functions can be undefined with the .C -f option of the .C unset special command. .PP Ordinarily, functions are unset when the shell executes a shell script. The .C -xf option of the .C typeset command allows a function to be exported to scripts that are executed without reinvoking the shell. Functions that must be defined across separate invocations of the shell should be placed in the .C ENV file. .SS Jobs If the .C monitor option of the .C set command is turned on, an interactive shell associates a .B job with each pipeline. It keeps a table of current jobs, printed by the .C jobs command, and assigns them small integer numbers. When a job is started asynchronously with .CR & , the shell prints a line resembling: .IP .C [1] 1234 .PP indicating that job number 1 was started asynchronously and had one (top-level) process whose process .SM ID was 1234. .PP If you are running a job and want to do something else, type the suspend character (usually .C ^Z (Ctrl-Z)) to send a .SM STOP signal to the current job. The shell then indicates that the job has been `Stopped', and prints another prompt. The state of this job can be manipulated by using the .C bg command to put it in the background, running other commands (while it is stopped or running in the background), and eventually restarting or returning the job to the foreground by using the .C fg command. A .C ^Z takes effect immediately and resembles an interrupt, since pending output and unread input are discarded when .C ^Z is typed. .PP A job run in the background stops if it tries to read from the terminal. Background jobs normally are allowed to produce output, but can be disabled by giving the .C stty tostop command. If the user sets this tty option, background jobs stop when trying to produce output. .PP There are several ways to refer to jobs in the shell. A job can be referred to by the process .SM ID of any process in the job or by one of the following: .RS .TP 20 .CI % number The job with the given number. .PD 0 .TP .CI % string Any job whose command line begins with .IR string . .TP .CI %? string Any job whose command line contains .IR string . .TP .C %% Current job. .TP .C %+ Equivalent to .CR %% . .TP .C %- Previous job. .PD .RE .PP The shell learns immediately when a process changes state. It informs the user when a job is blocked and prevented from further progress, but only just before it prints a prompt. .PP When the monitor mode is on, each background job that completes triggers any trap set for .CR CHLD . .PP Attempting to leave the shell while jobs are running or stopped produces the warning, .CR "You have stopped (running) jobs" . Use the .C jobs command to identify them. An immediate attempt to exit again terminates the stopped jobs; the shell does not produce a warning the second time. .SS Signals The .SM INT and .SM QUIT signals for an invoked command are ignored if the command is followed by .C & and the .C monitor option is off. Otherwise, signals have the values inherited by the shell from its parent, with the exception of signal 11 (but see also the .C trap command below). .SS Execution Substitutions are made each time a command is executed. If the command name matches one of the .I Special Commands listed below, it is executed within the current shell process. Next, .C ksh checks the command name to determine whether it matches one of the user-defined functions. If it does, .C ksh saves the positional parameters and then sets them to the arguments of the .I function call. The positional parameter .C 0 is set to the function name. When the .I function completes or issues a .CR return , .C ksh restores the positional parameter list and executes any trap set on .C EXIT within the function. The value of a .I function is the value of the last command executed. A function is executed in the current shell process. If a command name is not a .I special command or a user-defined .IR function , .C ksh creates a process and attempts to execute the command using .C exec (see .IR exec (2)). .PP The shell parameter .C PATH defines the search path for the directory containing the command. Alternative directory names are separated by a colon .RC ( : ). The default path is .C /usr/bin: (specifying .CR /usr/bin and the current directory in that order). Note that the current directory is specified by a null path name which can appear immediately after the equals sign, between colon delimiters, or at the end of the path list. The search path is not used if the command name contains a .CR / . Otherwise, each directory in the path is searched for an executable file. If the file has execute permissions but is not a directory or an executable object code file, it is assumed to be a script file, which is a file of data for an interpreter. If the first two characters of the script file are .CR #! , .C exec (see .IR exec (2)) expects an interpreter path name to follow. .CR exec then attempts to execute the specified interpreter as a separate process to read the entire script file. If a call to .C exec fails, .C /usr/bin/ksh is spawned to interpret the script file. All non-exported aliases, functions, and named parameters are removed in this case. If the shell command file does not have read permission, or if the .I setuid and/or .I setgid bits are set on the file, the shell executes an agent to set up the permissions and execute the shell with the shell command file passed down as an open file. A parenthesized command is also executed in a sub-shell without removing non-exported quantities. .SS Command Re-entry The text of the last .C HISTSIZE (default 128) commands entered from a terminal device is saved in a .I history file. The file .C $HOME/.sh_history is used if the .C HISTFILE variable is not set or writable. A shell can access the commands of all .I interactive shells that use the same named .CR HISTFILE . The special command .C fc is used to list or edit a portion of this file. The portion of the file to be edited or listed can be selected by number or by giving the first character or characters of the command. A single command or range of commands can be specified. If no editor program is specified as an argument to .CR fc , the value of the .C FCEDIT parameter is used. If .C FCEDIT is not defined, .C /usr/bin/ed is used. The edited command is printed and re-executed upon leaving the editor. The editor name .C - is used to skip the editing phase and to re-execute the command. In this case a substitution parameter of the form .IC old = new can be used to modify the command before execution. For example, if .C r is aliased to .CR "fc -e -" , typing .C r bad=good c re-executes the most recent command that starts with the letter .CR c and replaces the first occurrence of the string .C bad with the string .CR good . .SS Special Commands The following simple-commands are executed in the shell process. They permit input/output redirection. Unless otherwise indicated, file descriptor 1 is the default output location and the exit status, when there are no syntax errors, is zero. Commands that are preceded by .B \(dg or .B \(dg\(dg are treated specially in the following ways: .RS .TP 4 1. Variable assignment lists preceding the command remain in effect when the command completes. .PD 0 .TP 2. I/O redirections are processed after variable assignments. .TP 3. Errors cause a script that contains them to abort. .TP 4. Words following a command preceded by \(dg\(dg that are in the format of a variable assignment are expanded with the same rules as a variable assignment. This means that tilde substitution is performed after the .C = sign and word splitting and file name generation are not performed. .PD .RE .TP 15 .CR "\(dg : " [\|\f2arg\fP\0...\|] The command only expands parameters. A zero exit code is returned. .TP .CR "\(dg . \f2file\fP " [\|\f2arg\fP\0...\|] Read and execute commands from .I file and return. The commands are executed in the current shell environment. The search path specified by .C PATH is used to find the directory containing .IR file . If any arguments .I arg are given, they become the positional parameters. Otherwise the positional parameters are unchanged. The exit status is the exit status of the last command executed. It is not necessary that the execute permission bit be set for .IR file . .TP .CR "\(dg\(dg alias " [\| -tx "\|] [\|\f2name\fP[" = \f2value\fP\|]\0...\|] .C alias with no arguments prints the list of aliases in the form .IC name = value on standard output. An .I alias is defined for each name whose .I value is given. A trailing space in .I value causes the next word to be checked for alias substitution. The .C -t option is used to set and list tracked aliases. The value of a tracked alias is the full path name corresponding to the given .IR name . The value of a tracked alias becomes undefined when the value of .C PATH is reset, but the alias remains tracked. Without the .C -t option, for each .I name in the argument list for which no .I value is given, the name and value of the alias is printed. The .C -x option is used to set or print exported aliases. An exported alias is defined across sub-shell environments. Alias returns true unless a .I name is given for which no alias has been defined. .TP .CR bg\0 [\|\f2job\fP\0...\|] Puts the specified .I jobs into the background. The current job is put in the background if .I job is unspecified. See .I Jobs for a description of the format of .IR job . .TP .CR "\(dg break " [\|\f2n\fP\|] Exit from the enclosing .CR for , .CR while , .CR until , or .C select loop, if any. If .I n is specified, break .I n levels. .TP .CR "\(dg continue " [\|\f2n\fP\|] Resume the next iteration of the enclosing .CR for , .CR while , .CR until , or .C select loop. If .I n is specified, resume at the .IR n -th enclosing loop. .TP .CR cd\0 [\| -L \(or -P "\|] [\|\f2arg\fP\|] .PD 0 .TP .CI cd " old new" .PD This command can take either of two forms. In the first form it changes the current directory to .IR arg . If .I arg is .C - the directory is changed to the previous directory. The .C -L option (default) preserves logical naming when treating symbolic links. .C cd -L .. moves the current directory one path component closer to the root directory. The .C -P option preserves the physical path when treating symbolic links. .C cd -P .. changes the working directory to the parent directory of the current directory. The shell parameter .C HOME is the default .IR arg . The parameter .C PWD is set to the current directory. The shell parameter .C CDPATH defines the search path for the directory containing .IR arg . Alternative directory names are separated by a colon .RC ( : ). If .C CDPATH is null or undefined, the default value is the current directory. Note that the current directory is specified by a null path name which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If .I arg begins with a .CR / , the search path is not used. Otherwise, each directory in the path is searched for .IR arg . .IP The second form of .C cd substitutes the string .I new for the string .I old in the current directory name, .C PWD and tries to change to this new directory. .IP The .C cd command cannot be executed by .CR rksh . .TP .CR echo\0 [\|\f2arg\fP\0...\|] See .IR echo (1) for usage and description. .TP .CR "\(dg eval " [\|\f2arg\fP\0...\|] Reads the arguments as input to the shell and executes the resulting command(s). .TP .CR "\(dg exec " [\|\f2arg\fP\0...\|] Parameter assignments remain in effect after the command completes. If .I arg is given, the command specified by the arguments is executed in place of this shell without creating a new process. Input/output arguments can appear and affect the current process. If no arguments are given, the effect of this command is to modify file descriptors as prescribed by the input/output redirection list. In this case, any file descriptor numbers greater than 2 opened with this mechanism are closed when invoking another program. .TP .CR "\(dg exit " [\|\f2n\fP\|] Causes the shell to exit with the exit status specified by .IR n . If .I n is omitted, the exit status is that of the last command executed. An end-of-file also causes the shell to exit, except when a shell has the .I ignoreeof option set (see .C set below). .TP .CR "\(dg\(dg export " [\|\f2name\fP\0[ = \f2value\fP\|]\0...\|] The given .IR name s are marked for automatic export to the .I environment of subsequently executed commands. .TP .CR fc\0 [\| -e\f2ename\fP "\|] [\|" -nlr \|]\0[\|\f2first\fP\0[\|\f2last\fP\|]\|] .PD 0 .TP .CR "fc -e - " [\|\f2old\fP = "\f2new\fP\|] [\|\f2command\fP\|]" .PD In the first form, a range of commands from .I first to .I last is selected from the last .C HISTSIZE commands typed at the terminal. The arguments .I first and .I last can be specified as a number or string. A given string is used to locate the most recent command. A negative number is used to offset the current command number. The .C -l option causes the commands to be listed on standard output. Otherwise, the editor program .I ename is invoked on a file containing these keyboard commands. If .I ename is not supplied, the value of the parameter .C FCEDIT (default .CR /usr/bin/ed ) is used as the editor. Once editing has ended, the commands (if any) are executed. If .I last is omitted, only the command specified by .I first is used. If .I first is not specified, the default is the previous command for editing and \(mi16 for listing. The .C -r option reverses the order of the commands and the .C -n option suppresses command numbers when listing. In the latter, the .I command is re-executed after the substitution .IC old = new is performed. .TP .CR fg\0 [\|\f2job\fP\0...\|] Brings each .I job into the foreground in the order specified. If no .I job is specified, the current job is brought into the foreground. See .I Jobs for a description of the format of .IR job . .TP .CR getopts\0\f2optstring\0name\fP\0 [\|\f2arg\fP\0...\] Checks .I arg for legal options. If .I arg is omitted, the positional parameters are used. An option argument begins with a .C + or a .CR - . An option not beginning with .C + or .CR - , or the argument .C -\|- ends the options. .I optstring contains the letters that .I getopts recognizes. If a letter is followed by a .CR : , that option is expected to have an argument. The options can be separated from the argument by blanks. .IP .C getopts places the next option letter it finds inside variable .IR name each time it is invoked with a .C + preceding it when .I arg begins with a .CR + . The index of the next .I arg is stored in .CR OPTIND . The option argument, if any, gets stored in .CR OPTARG . .IP A leading .C : in .I optstring causes .C getopts to store the letter of an invalid option in .CR OPTARG , and to set .I name to .C ? for an unknown option and to .C : when a required option is missing. Otherwise, .C getopts prints an error message. The exit status is non-zero when there are no more options. .TP .CR jobs\0 [\| -lnp "\|] [\|\f2job\fP\0...\|]" Lists information about each given job; or all active jobs if .I job is omitted. The .C -l option lists process ids in addition to the normal information. The .C -n option only displays jobs that have stopped or exited since last notified. The .C -p option causes only the process group to be listed. See .I Jobs for a description of the format of .IR job . .TP .CR kill\0 [\| -\f2sig\fP \|]\0\f2process\fP\0... Sends either the .SM TERM (terminate) signal or the specified signal to the specified jobs or processes. Signals are given either by number or name (as given in .IR signal (5), stripped of the prefix .CR SIG ). The signal names are listed by .CR "kill -l" . No default exists; merely typing .C kill does not affect the current job. If the signal being sent is .C TERM (terminate) or .C HUP (hangup), the job or process is sent a .C CONT (continue) signal when stopped. The .I process argument can be either a process .SM ID or job. If the first argument to .C kill is a negative integer, it is interpreted as a .I sig argument and not as a process group. .TP .CI let \0arg\0\f1... Each .I arg is a separate .IR "arithmetic expression" to be evaluated. See .I "Arithmetic Evaluation" above, for a description of arithmetic expression evaluation. The exit status is 0 if the value of the last expression is non-zero, and 1 otherwise. .TP .CR "\(dg newgrp " [\|\f2arg\fP\0...\|] Equivalent to .CI "exec newgrp" " arg" \&.... .TP .CR print [\| -Rnprsu [\|\f2n\fP\|]\|]\0[\|\f2arg\fP\0...\|] The shell output mechanism. With no options or with option .C - or .CR -\|- the arguments are printed on standard output as described by .IR echo (1). Raw mode, .C -R or .CR -r , ignores the escape conventions of .IR echo . The .C -R option prints all subsequent arguments and options other than .CR -n . The .C -p option causes the arguments to be written onto the pipe of the process spawned with .C |& instead of standard output. The .C -s option causes the arguments to be written onto the history file instead of standard output. The .C -u option can be used to specify a one-digit file descriptor unit number .I n on which the output is to be placed. The default is 1. If the option .C -n is used, no new-line character is added to the output. .TP .CR pwd\0 [\| -L \(or -P \|] With no arguments prints the current working directory (equivalent to .CR "print -r - $PWD" ). The .C -L option (default) preserves the logical meaning of the current directory and .C -P preserves the physical meaning of the current directory if it is a symbolic link (see .C cd and .IR ln (1)). .TP .CR read\0 [\| -prsu "[\|\f2n\fP\|]\|] [\|\f2name\fP\|] [" ? "\f2prompt\fP\|] [\|\f2name\fP\0...\|] The shell input mechanism. One line is read and broken up into words using the characters in .C IFS as separators. In .C -r raw mode, .C \e at the end of a line does not signify line continuation. The first word is assigned to the first .IR name , the second word to the second .IR name , etc., with remaining words assigned to the last .IR name . The .C -p option causes the input line to be taken from the input pipe of a process spawned by the shell using .CR |& . If the .C -s option is present, the input is saved as a command in the history file. The option .C -u can be used to specify a one-digit file descriptor unit to read from. The file descriptor can be opened with the .C exec special command. The default value of .I n is .CR 0 . If .IR name is omitted, .C REPLY is used as the default .IR name. The return code is .CR 0 , unless an end-of-file is encountered. An end-of-file with the .C -p option causes cleanup for this process so that another process can be spawned. If the first argument contains a .CR ? , the remainder of this word is used as a .I prompt when the shell is interactive. If the given file descriptor is open for writing and is a terminal device, the prompt is placed on this unit. Otherwise the prompt is issued on file descriptor 2. The return code is .CR 0 , unless an end-of-file is encountered. .TP .CR "\(dg\(dg readonly " [\|\f2name\fP[\| = \f2value\fP\|]\0...\|] The given .IR names are marked read-only and these names cannot be changed by subsequent assignment. .TP .CR "\(dg return " [\|\f2n\fP\|] Causes a shell .I function to return to the invoking script with the return status specified by .IR n . If .I n is omitted, the return status is that of the last command executed. Only the low 8 bits of .I n are passed back to the caller. If .C return is invoked while not in a .I function or executing a script by the .C . (dot) built-in command, it has the same effect as an .C exit command. .TP .CR "set \f1[\fP\|\(+-aefhkmnopstuvx\|\f1|\fP\|\(+-o \f2option\fP" \|]\0...\0[\| \(+-A " \f2name\fP\|] [\|\f2arg\fP ...\|]" The following options are used for this command: .RS .RS .PD 0 .TP 8 .C -A Array assignment. Unset the variable .I name and assign values sequentially from the list .IR arg . If .C +A is used, the variable .I name is not unset first. .TP .C -a All subsequent defined parameters are automatically exported. .TP .C -e If the shell is non-interactive and if a command fails, execute the .C ERR trap, if set, and exit immediately. This mode is disabled while reading profiles. .TP .C -f Disables file name generation. .TP .C -h Each command whose name is an .I identifier becomes a tracked alias when first encountered. .TP .C -k All parameter assignment arguments (not just those that precede the command name) are placed in the environment for a command. .TP .C -m Background jobs are run in a separate process group and a line is printed upon completion. The exit status of background jobs is reported in a completion message. This option is turned on automatically for interactive shells. .TP .C -n Read commands and check them for syntax errors, but do not execute them. The .C -n option is ignored for interactive shells. .TP .C -o The .C -o argument takes any of several .I option names, but only one .I option can be specified with each .C -o option. If none is supplied, the current option settings are printed. The .C -o argument .I option names follow: .RS .PD .TP 18 .C allexport Same as .CR -a . .PD 0 .TP .C bgnice All background jobs are run at a lower priority. .TP .C errexit Same as .CR -e . .TP .C emacs Activates an .C emacs-\c style in-line editor for command entry. .TP .C gmacs Activates a .C gmacs-\c style in-line editor for command entry. .TP .C ignoreeof The shell does not exit on end-of-file. The command .C exit must be used. .TP .C keyword Same as .CR -k . .TP .C markdirs All directory names resulting from file name generation have a trailing .C / appended. .TP .C monitor Same as .CR -m . .TP .C noclobber Prevents redirection .C > from truncating existing files. Requires .C >| to truncate a file when turned on. .TP .C noexec Same as .CR -n . .TP .C noglob Same as .CR -f . .TP .C nolog Do not save function definitions in history file. .TP .C nounset Same as .CR -u . .TP .C privileged Same as .CR -p . .TP .C verbose Same as .CR -v . .TP .C trackall Same as .CR -h . .TP .C vi Activates the insert mode of a .C vi-\c style in-line editor until you press the .SM ESC key which puts you in move mode. A return sends the line. .TP .C viraw Each character is processed as it is typed in .C vi mode. .TP .C xtrace Same as .CR -x . .PD .RE .RE .TP .C -p Disables processing of the .C $HOME/.profile file and uses the file .C /etc/suid_profile instead of the .C ENV file. This mode is on whenever the effective uid (gid) is not equal to the real uid (gid). Turning this off causes the effective uid and gid to be set to the real uid and gid. .PD 0 .TP .C -s Sort the positional parameters. .TP .C -t Exit after reading and executing one command. .TP .C -u Treat unset parameters as an error when substituting. .TP .C -v Print shell input lines as they are read. .TP .C -x Print commands and their arguments as they are executed. .TP .C - Turns off .C -x and .C -v options and stops examining arguments for options. .TP .C -\|- Do not change any of the options; useful in setting .C $1 to a value beginning with .CR - . If no arguments follow this option, the positional parameters are unset. .PD .RE .IP Using .C + instead of .C - before a option causes the option to be turned off. These options can also be used when invoking the shell. The current set of options can be examined by using .CR $- . .IP Unless .C -A is specified, the remaining .I arg arguments are positional parameters and are assigned consecutively to .CR $1 , .CR $2 , \&...\|. If neither arguments nor options are given, the values of all names are printed on the standard output. .TP .CR "\(dg shift " [\|\f2n\fP\|] The positional parameters from .CI $ n +1 \&... are renamed .CR $1 \0...\|; default .I n is 1. The parameter .I n can be any arithmetic expression that evaluates to a non-negative number less than or equal to .CR $# . .TP .CR test\0 [\|\f2expr\fP\|] Evaluate conditional expression .IR expr . See .IR test (1) for usage and description. The arithmetic comparison operators are not restricted to integers. They allow any arithmetic expression. Four additional primitive expressions are allowed: .RS .RS .TP 20 .CI -L \0file True if .I file is a symbolic link. .PD 0 .TP .IC file1 \0-nt \0file2 True if .I file1 is newer than .IR file2 . .TP .IC file1 \0-ot \0file2 True if .I file1 is older than .IR file2 . .TP .IC file1 \0-ef \0file2 True if .I file1 has the same device and i-node number as .IR file2 . .PD .RE .RE .TP .C \(dg times Print the accumulated user and system times for the shell and for processes run from the shell. .TP .CR "\(dg trap " [\|\f2arg\fP\|]\0[\|\f2sig\fP\0...\|] .I arg is a command read and executed when the shell receives signal(s) .IR sig . (Note that .I arg is scanned once when the trap is set and once when the trap is taken.) Each .I sig can be given as a number or name of the signal. Trap commands are executed in signal number order. Any attempt to set a trap on a signal that was ignored upon entering the current shell has no effect. If .I arg is omitted or is .CR - , all traps for .I sig are reset to their original values. If .I arg is the null string, this signal is ignored by the shell and by the commands it invokes. If .I sig is .CR DEBUG , .I arg is executed after each command. If .I sig is .CR ERR , .I arg is executed whenever a command has a non-zero exit code. If .I sig is .C 0 or .C EXIT and the .C trap statement is executed inside the body of a function, the command .I arg is executed after the function completes. If .I sig is .C 0 or .C EXIT for a .C trap set outside any function, the command .I arg is executed on exit from the shell. The .C trap command with no arguments prints a list of commands associated with each signal number. .TP .CR "\(dg\(dg typeset " [\| \(+-LRZfilrtux "[\|\f2n\fP\|]\|] [\|\f2name\fP[\| = \f2value\fP\|]\|]\0... Parameter assignments remain in effect after the command completes. When invoked inside a function, a new instance of the parameter .I name is created. The parameter value and type are restored when the function completes. The following list of attributes can be specified: .RS .RS .PD 0 .TP .C -L Left justify and remove leading blanks from .IR value . If .I n is non-zero, it defines the width of the field. Otherwise, it is determined by the width of the value of first assignment. When the .I name is assigned, the value is filled on the right with blanks or truncated, if necessary, to fit into the field. Leading zeros are removed if the .C -Z option is also set. The .C -R option is turned off. .TP .C -R Right justify and fill with leading blanks. If .I n is non-zero, it defines the width of the field. Otherwise, it is determined by the width of the value of first assignment. The field is left-filled with blanks or truncated from the end if the parameter is reassigned. The .C -L option is turned off. .TP .C -Z Right justify and fill with leading zeros if the first non-blank character is a digit and the .C -L option has not been set. If .I n is non-zero, it defines the width of the field. Otherwise, it is determined by the width of the value of first assignment. .TP .C -f Cause .I name to refer to function names rather than parameter names. No assignments can be made to the .I name declared with the .C typeset statement. The only other valid options are .C -t (which turns on execution tracing for this function) and .C -x (which allows the function to remain in effect across shell procedures executed in the same process environment). .TP .C -i Parameter is an integer. This makes arithmetic faster. If .I n is non-zero, it defines the output arithmetic base; otherwise the first assignment determines the output base. .TP .C -l Convert all uppercase characters to lowercase. The uppercase .C -u option is turned off. .TP .C -r Any given .I name is marked "read only" and cannot be changed by subsequent assignment. .TP .C -t Tag the named parameters. Tags are user definable and have no special meaning to the shell. .TP .C -u Convert all lowercase characters to uppercase characters. The lowercase .C -l option is turned off. .TP .C -x Mark any given .I name for automatic export to the environment of subsequently executed commands. .PD .IP Using .C + instead of .C - causes these options to be turned off. If no .I name arguments are given but options are specified, a list of names (and optionally the values) of the parameters that have these options set is printed. Using .C + instead of .C - retains the values to be printed. If neither names nor options are given, the names and attributes of all parameters are printed. .RE .RE .TP .CR ulimit\0 [\|\f2n\fP\|] If .I n is given, impose a size limit of .I n 512 byte blocks on files written by child processes (files of any size can be read). If .I n is not given, the current limit is printed. .TP .CR umask\0 [\|\f2mask\fP\|] The user file-creation mask is set to .I mask (see .IR umask (2)). .I mask can either be an octal number or a symbolic value as described in .IR chmod (1). If a symbolic value is given, the new umask value is the complement of the result of applying .I mask to the complement of the previous umask value. If .I mask is omitted, the current value of the mask is printed. .TP .CI unalias\0 name\f1\0... The .IR parameters given by the list of .IR name s are removed from the .I alias list. .TP .CR unset\0 [\| -f \|]\0\f2name\fP\0... The parameters given by the list of .IR name s are unassigned; that is, their values and attributes are erased. Read-only variables cannot be unset. If the .C -f option is set, .IR name s refer to function names. Unsetting .CR ERRNO , .CR LINENO , .CR MAILCHECK , .CR OPTARG , .CR OPTIND , .CR RANDOM , .CR SECONDS , .CR TMOUT , and .C _ removes their special meaning even if they are subsequently assigned to. .TP .CR "\(dg wait " [\|\f2job\fP\|] Wait for the specified .I job to terminate or stop, and report its status. This status becomes the return code for the .C wait command. If .I job is not given, .C wait waits for all currently active child processes to terminate or stop. The termination status returned is that of the last process. See .I Jobs for a description of the format of a .IR job . .TP .CR whence\0 [\| -pv \|]\0\f2name\fP\0... For each .IR name , indicate how it would be interpreted if used as a command name. The .C -v option produces a more verbose report. The .C -p option does a path search for .I name even if .I name is an alias, a function, or a reserved word. .ifn .SS Invoking ksh .ift .SS Invoking \f4\s+1ksh\s0\f1 If the shell is invoked by .C exec (see .IR exec (2)), and the first character of argument zero .RC ( $0 ) is .CR - , the shell is assumed to be a login shell and commands are read first from .CR /etc/profile . The expression .C ${HOME:-.}/.profile is then evaluated and an attempt to open the resulting filename is made. If the file is opened successfully, the file is read. Next, commands are read from the file named by performing parameter substitution on the value of the environment parameter .CR ENV , if the file exists. If the .C -s option is not present and .I arg is, a path search is performed on the first .I arg to determine the name of the script to execute. When running .C ksh with .IR arg , the script .I arg must have read permission and any .I setuid and .I getgid settings are ignored. Commands are then read as described below. The following options are interpreted by the shell when it is invoked: .RS .TP 15 .CI -c \0string If the .C -c option is present, commands are read from .IR string . .PD 0 .TP .C -s If the .C -s option is present or if no arguments remain, commands are read from the standard input. Shell output, except for the output of some of the .I Special commands listed above, is written to file descriptor 2. .TP .C -i If the .C -i option is present or if the shell input and output are attached to a terminal (as reported by .IR tty (3C)), the shell is interactive. In this case .SM SIGTERM is ignored (so that .C kill 0 does not kill an interactive shell) and .SM SIGINT +1 is caught and ignored (so that .C wait is interruptible). In all cases, .SM SIGQUIT is ignored by the shell. (See .IR signal (5).) .TP .C -r If the .C -r option is present, the shell is a restricted shell. .PD .RE .PP The remaining options and arguments are described under the .C set command above. .ifn .SS rksh Only .ift .SS \f4\s+1rksh\s0\fP Only .C rksh is used to set up login names and execution environments where capabilities are more controlled than those of the standard shell. The actions of .C rksh are identical to those of .CR ksh , except that the following are forbidden: .RS .TP 3 \(bu Changing directory (see .IR cd (1)) .PD 0 .TP \(bu Setting the value of .CR SHELL , .CR ENV , or .C PATH .TP \(bu Specifying path or command names containing .C / .TP \(bu Redirecting output .RC ( > , .CR >| , .CR <> , and .CR >> ) .PD .RE .PP The restrictions above are enforced after the .C .profile and .C ENV files are interpreted. .PP When a command to be executed is found to be a shell procedure, .C rksh invokes .C ksh to execute it. Thus, the end-user is provided with shell procedures accessible to the full power of the standard shell, while being restricted to a limited menu of commands. This scheme assumes that the end-user does not have write and execute permissions in the same directory. .PP These rules effectively give the writer of the .C .profile file complete control over user actions, by performing guaranteed set-up actions and leaving the user in an appropriate directory (probably not the login directory). .PP The system administrator often sets up a directory of commands (usually .CR /usr/rbin ) that can be safely invoked by .CR rksh . .SM HP-UX systems provide a restricted editor .I red (see .IR ed (1)), suitable for restricted users. .SH COMMAND-LINE EDITING .SS In-line Editing Options Normally, each command line typed at a terminal device is followed by a new-line (carriage-return or line-feed). If either the .CR emacs , .CR gmacs , or .C vi option is set, the user can edit the command line. An editing option is automatically selected each time the .C VISUAL or .C EDITOR variable is assigned a value ending in either of these option names. .PP The editing features require that the user's terminal accept Return as carriage return without line feed and that a space character must overwrite the current character on the screen. .SM ADM terminal users should set the ``space/advance'' switch to ``space''. Hewlett-Packard terminal users should set the straps to ``bcGHxZ\ etX''. .PP The editing modes enable the user to look through a window at the current line. The default window width is 80, unless the value of .C COLUMNS is defined. If the line is longer than the window width minus two, a mark displayed at the end of the window notifies the user. The mark is a .CR > , .CR < , or .C * if the line extends respectively on the right, left, or both side(s) of the window. As the cursor moves and reaches the window boundaries, the window is centered about the cursor. .PP The search commands in each edit mode provide access to the history file. Only strings are matched, not patterns, although a leading .C ^ in the string restricts the match to begin at the first character in the line. .SS Emacs Editing Mode This mode is invoked by either the .C emacs or .C gmacs option. Their sole difference is their handling of .CR ^T . To edit, the user moves the cursor to the point needing correction and inserts or deletes characters or words. All editing commands are control characters or escape sequences. The notation for control characters is circumflex .RB ( ^ ) followed by the character. For example, .C ^F is the notation for .RC Ctrl- F . This is entered by pressing the .C f key while holding down the Ctrl (control) key. The Shift key is .I not pressed. (The notation .C ^? indicates the .SM DEL (delete) key.) .PP The notation for escape sequences is .I M- followed by a character. For example, .IC M- f (pronounced Meta f) is entered by depressing .SM ESC (ASCII 033 ) followed by .CR f . .IC M- F would be the notation for .SM ESC followed by Shift (capital) .CR F . .PP All edit commands operate from any place on the line (not only at the beginning). Neither the Return nor the Line Feed key is entered after edit commands, except when noted. .PP .TP 15 .C ^F Move cursor forward (right) one character. .PD 0 .TP .IC M- f Move cursor forward one word. (The editor's idea of a word is a string of characters consisting of only letters, digits and underscores.) .TP .C ^B Move cursor backward (left) one character. .TP .IC M- b Move cursor backward one word. .TP .C ^A Move cursor to start of line. .TP .C ^E Move cursor to end of line. .TP .CI ^] char Move cursor forward to character .I char on current line. .TP .IC M- ^]\f2char\fP Move cursor backward to character .I char on current line. .TP .C ^X^X Interchange the cursor and mark. .TP .I erase (User defined erase character as defined by the .IR stty (1) command, usually .C ^H or .CR # .) Delete previous character. .TP .C ^D Delete current character. .TP .I eof End-of-file character, normally .CR ^D , terminates the shell if the current line is null. .TP .IC M- d Delete current word. .TP .IC M- ^H (Meta-backspace) Delete previous word. .TP .IC M- h Delete previous word. .TP .IC M- ^? (Meta-\c .SM DEL\c ) Delete previous word (if interrupt character is .C ^? (\c .SM DEL, the default) this command does not work). .TP .C ^T Transpose current character with next character in .C emacs mode. Transpose two previous characters in .C gmacs mode. .TP .C ^C Capitalize current character. .TP .IC M- c Capitalize current word. .TP .IC M- l Change the current word to lowercase. .TP .C ^K Delete from the cursor to the end of the line. If preceded by a numerical parameter whose value is less that the current cursor position, delete from the given position up to the cursor. If preceded by a numerical parameter whose value is greater than the current cursor position, from the cursor up to the given position. .TP .C ^W Kill from the cursor to the mark. .TP .IC M- p Push the region from the cursor to the mark on the stack. .TP .I kill (User-defined kill character, as defined by the .IR stty (1) command, usually .C ^G or .ifn \f3\s+1@\s0\fP.) .ift \f4\s+1@\s0\fP.) Kill the entire current line. If two .I kill characters are entered in succession, all subsequent consecutive kill characters cause a line feed (useful when using paper terminals). .TP .C ^Y Restore last item removed from line (yank item back to the line). .TP .C ^L Line feed and print current line. .TP .ifn \f3^\s+1@\s0\fP .ift \f4^\s+1@\s0\fP (Null character) Set mark. .TP .IR M- space (Meta space) Set mark. .TP .C ^J (New\ line) Execute the current line. .TP .C ^M (Return) Execute the current line. .TP .C ^P Fetch previous command. Each time .C ^P is entered, the next previous command in the history list is accessed. .TP .C ^N Fetch next command. Each time .C ^N is entered the next command in the history list is accessed. .TP .IC M- < Fetch the least recent (oldest) history line. .TP .IC M- > Fetch the most recent (youngest) history line. .TP .CI ^R string Reverse search history for a previous command line containing .I string. If a parameter of zero is given, the search is forward. .I string is terminated by a Return or New-Line. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is omitted, the next command line containing the most recent .I string is accessed. In this case a parameter of zero reverses the direction of the search. .TP .C ^O Operate - Execute the current line and fetch from the history file the next line relative to current line. .TP .I M-digits (Escape) Define numeric parameter, the digits are taken as a parameter to the next command. The commands that accept a parameter are .CR ^F , .CR ^B , .IR erase , .CR ^C , .CR ^D , .CR ^K , .CR ^R , .CR ^P , .CR ^N , .CR ^] , .IC M- .\f1, .IC M- _\f1, .IC M- b\f1, .IC M- c\f1, .IC M- d\f1, .IC M- f\f1, .IC M- h\f1, .IC M- l and .IC M- ^H\f1. .TP .I M-letter Softkey. User's alias list is searched for an alias by the name .CI _ letter and if an alias of this name is defined, its value is inserted on the input queue. This .I letter must not be one of the above meta-functions. .TP .IC M- . The last word of the previous command is inserted on the line. If preceded by a numeric parameter, the value of this parameter determines which word to insert rather than the last word. .TP .IC M- _ Same as .IC M- .\f1. .TP .IC M- * Attempt file-name generation on the current word. .TP .IR M- \s-1ESC\s0 File-name completion. Replaces the current word with the longest common prefix of all filenames matching the current word with an asterisk appended. If the match is unique, a .C / is appended if the file is a directory and a space is appended if the file is not a directory. .TP .IC M- = List files matching current word pattern as if an asterisk were appended. .TP .C ^U Multiply parameter of next command by 4. .TP .C \e Escape next character. Editing characters, the user's erase, kill and interrupt (normally .CR ^? ) characters can be entered in a command line or in a search string if preceded by a .CR \e . The .C \e removes the next character's editing features (if any). .TP .C ^V Display version of the shell. .TP .IC M- # Insert a .C # at the beginning of the line and execute it. This causes a comment to be inserted in the history file. .PD .SS Vi Editing Mode There are two typing modes. Entering a command puts you into .I input mode. To edit, the user enters .I control mode by pressing .SM ESC and moves the cursor to the point needing correction, then inserts or deletes characters or words. Most control commands accept an optional repeat .I count prior to the command. .PP In vi mode on most systems, canonical processing is initially enabled and the command is echoed again if the speed is 1200 baud or greater and contains any control characters, or if less than one second has elapsed since the prompt was printed. The .SM ESC character terminates canonical processing for the remainder of the command and the user can then modify the command line. This scheme has the advantages of canonical processing with the type-ahead echoing of raw mode. .PP Setting the .C viraw option always disables canonical processing on the terminal. This mode is implicit for systems that do not support two alternate end-of-line delimiters, and can be helpful for certain terminals. .SS "Input Edit Commands" By default the editor is in input mode. .TP 15 .PD 0 .I erase Delete previous character. .RI ( erase is a user-defined erase character, as defined by the .IR stty (1) command, usually .C ^H or .CR # .) .TP .CI ^W Delete the previous blank separated word. .TP .CI ^D Terminate the shell. .TP .CI ^V Escape next character. Editing characters, erase or kill characters can be entered in a command line or in a search string if preceded by a .CR ^V . .C ^V removes the next character's editing features (if any). .TP .CI \e Escape the next .I erase or .I kill character. .PD .SS "Motion Edit Commands" These commands move the cursor. The designation .RI [ count ] causes a repetition of the command the cited number of times. .RS .TP 15 .PD 0 .RC [\f2count\fP] l Cursor forward (right) one character. .TP .RC [\f2count\fP] w Cursor forward one alphanumeric word. .TP .RC [\f2count\fP] W Cursor to the beginning of the next word that follows a blank. .TP .RC [\f2count\fP] e Cursor to end of word. .TP .RC [\f2count\fP] E Cursor to end of the current blank-delimited word. .TP .RC [\f2count\fP] h Cursor backward (left) one character. .TP .RC [\f2count\fP] b Cursor backward one word. .TP .RC [\f2count\fP] B Cursor to preceding blank separated word. .TP .RC [\f2count\fP] | Cursor to column .IR count . Default is 1. .TP .RC [\f2count\fP] f\f2c\fP Find the next character .I c in the current line. .TP .RC [\f2count\fP] F\f2c\fP Find the previous character .I c in the current line. .TP .RC [\f2count\fP] t\f2c\fP Equivalent to .C f followed by .CR h . .TP .RC [\f2count\fP] T\f2c\fP Equivalent to .C F followed by .CR l . .TP .RC [\f2count\fP] ; Repeats the last single character find command, .CR f , .CR F , .CR t , or .CR T . .TP .RC [\f2count\fP] , Reverses the last single character find command. .TP .C 0 Cursor to start of line. .TP .C ^ Cursor to first nonblank character in line. .TP .C $ Cursor to end of line. .RE .SS "Search Edit Commands" These commands access your command history. .RS .TP 18 .RC [\f2count\fP] k Fetch previous command. Each time .C k is pressed, the next earlier command in the history list is accessed. .TP .RC [\f2count\fP] - Equivalent to .CR k . .TP .RC [\f2count\fP] j Fetch next command. Each time .C j is entered, the next later command in the history list is accessed. .TP .RC [\f2count\fP] + Equivalent to .CR j . .TP .RC [\f2count\fP] G The command number .I count is fetched. The default is the first command in the history list. .TP .CI / string Search backward through history for a previous command containing .IR string . .I string is terminated by a "Return" or "New-line". If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is null, the previous string is used. .TP .CI ? string Same as .C / but search in the forward direction. .TP .C n Search for next match of the last pattern to .C / or .C ? commands. .TP .C N Search for next match of the last pattern to .C / or .CR ? , but in reverse direction. Search history for the .I string entered by the previous .C / command. .RE .SS "Text Modification Edit Commands" These commands modify the line. .RS .TP 18 .C a Enter input mode and enter text after the current character. .TP .C A Append text to the end of the line. Equivalent to .CR $a . .TP .RC [\f2count\fP] c\f2motion\fP .TP .CR c [\f2count\fP]\f2motion\fP Move cursor to the character position specified by .IR motion , deleting all characters between the original cursor position and new position, and enter input mode. If .I motion is .CR c , the entire line is deleted and input mode entered. .TP .C C Delete the current character through the end of line and enter input mode. Equivalent to .CR c$ . .TP .C S Equivalent to .CR cc . .TP .C D Delete the current character through end of line. Equivalent to .CR d$ . .TP .RC [\f2count\fP] d\f2motion\fP .TP .CR d [\f2count\fP]\f2motion\fP Move cursor to the character position specified by .IR motion , deleting all characters between the original cursor position and new position. If .I motion is .CR d , the entire line is deleted. .TP .C i Enter input mode and insert text before the current character. .TP .C I Insert text before the beginning of the line. Equivalent to the two-character sequence .CR 0i . .TP .RC [\f2count\fP] P Place the previous text modification before the cursor. .TP .RC [\f2count\fP] p Place the previous text modification after the cursor. .TP .C R Enter input mode and replace characters on the screen with characters you type in overlay fashion. .TP .RC [\f2count\f3] r\f2c\fP Replace the current character with .IR c . .TP .RC [\f2count\fP] x Delete current character. .TP .RC [\f2count\fP] X Delete preceding character. .TP .RC [\f2count\fP] . Repeat the previous text modification command. .TP .RC [\f2count\fP] ~ Invert the case of the current character and advance the cursor. .TP .RC [\f2count\fP] _ Causes the .I count word of the previous command to be appended at the current cursor location and places the editor in input mode at the end of the appended text. The last word is used if .I count is omitted. .TP .C * Appends an .C * to the current word and attempts file name generation. If no match is found, the bell rings. If a match is found, the word is replaced by the matching string and the command places the editor in input mode. .TP .SM .B ESC .TP .C \e Attempt file name completion on the current word. Replaces the current word with the longest common prefix of all filenames matching the current word with an asterisk appended. If the match is unique, a .C / is appended if the file is a directory and a space is appended if the file is not a directory. .RE .SS "Other Edit Commands" .RS .TP 18 .RC [\f2count\fP] y\f2motion\fP .TP .CR y [\f2count\fP]\f2motion\fP Yank current character through character that .I motion would move the cursor to and puts them into the delete buffer. The text and cursor are unchanged. .TP .C Y Yanks from current position to end of line. Equivalent to .CR y$ . .TP .C u Undo the last text modifying command. .TP .C U Undo all the text modifying commands performed on the line. .TP [\f2count\fP]\f3v\fP Returns the command .CI "fc -e ${VISUAL:-${EDITOR:-vi}}" " count" in the input buffer. If .I count is omitted, the current line is used. .TP .CI ^L Line feed and print current line. Has effect only in control mode. .TP .CI ^J (New\ line) Execute the current line, regardless of mode. .TP .CI ^M (Return) Execute the current line, regardless of mode. .TP .C # Equivalent to .CI I# followed by .BR Return . Sends the line after inserting a .C # in front of the line and after each new-line. Useful for inserting the current command line in the history list without executing it. .TP .C = List the filenames that match the current word if an asterisk were appended to it. .TP .ifn \f3\s+1@\s0\fP\f2letter\fP .ift \f4\s+1@\s0\fP\f2letter\fP The user's alias list is searched for an alias by the name .CI _ letter and if an alias of this name is defined, its value is inserted on the input queue for processing. .PD .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .SM LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. .PP .SM LC_CTYPE determines the classification of characters as letters, and the characters matched by character class expressions in pattern matching notation. .PP If .SM LC_COLLATE or .SM LC_CTYPE is not specified in the environment or is set to the empty string, the value of .SM LANG is used as a default for each unspecified or empty variable. If .SM LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .SM LANG. If any internationalization variable contains an invalid setting, .C ksh behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte character code sets are supported. .SH RETURN VALUE Errors detected by the shell, such as syntax errors, cause the shell to return a non-zero exit status. Otherwise, the shell returns the exit status of the last command executed (also see the .C exit command above). If the shell is being used non-interactively, execution of the shell file is abandoned. Runtime errors detected by the shell are reported by printing the command or function name and the error condition. If the line number on which the error occurred is greater than one, the line number is also printed in brackets .RC ( [\|] ) after the command or function name. .SH WARNINGS File descriptors 10 and 54 through 60 are used internally by the Korn Shell. Applications using these and forking a subshell should not depend upon them surviving in the subshell or its descendants. .PP If a command which is a .I "tracked alias" is executed, and a command with the same name is installed in a directory in the search path before the directory where the original command was found, the shell continues to load and execute the original command. Use the .C -t option of the .C alias command to correct this situation. .PP If you move the current directory or one above it, .C pwd may not give the correct response. Use the .C cd command with a full path name to correct this situation. .PP Some very old shell scripts contain a caret .RC ( ^ ) as a synonym for the pipe character .RC ( | ). Note however, .C ksh does not recognize the caret as a pipe character. .PP If a command is piped into a shell command, all variables set in the shell command are lost when the command completes. .PP Using the .C fc built-in command within a compound command causes the entire command to disappear from the history file. .PP The built-in command \f3\|.\fP \f2file\fP reads the entire file before any commands are executed. Therefore, .C alias and .C unalias commands in the file do not apply to any functions defined in the file. .PP Traps are not processed while the shell is waiting for a foreground job. Thus, a trap on .C CHLD is not executed until the foreground job terminates. .PP The .C export built-in command does not handle arrays properly. Only the first element of an array is exported to the .IR environment . .PP Background processes started from a non-interactive shell cannot be accessed by using job control commands. .PP In an international environment, character ordering is determined by the setting of .SM LC_COLLATE, rather than by the binary ordering of character values in the machine collating sequence. This brings with it certain attendant dangers, particularly when using range expressions in file name generation patterns. For example, the command, .IP .C rm [a-z]* .PP might be expected to match all file names beginning with a lowercase alphabetic character. However, if dictionary ordering is specified by .SM LC_COLLATE, it would also match file names beginning with an uppercase character (as well as those beginning with accented letters). Conversely, it would fail to match letters collated after .C z in languages such as Danish or Norwegian. .PP The correct (and safe) way to match specific character classes in an international environment is to use a pattern of the form: .IP .C rm [[:lower:]]* .PP This uses .SM LC_CTYPE to determine character classes and works predictably for all supported languages and codesets. For shell scripts produced on non-internationalized systems (or without consideration for the above dangers), it is recommended that they be executed in a non-\c .SM NLS environment. This requires that .SM LANG, LC_COLLATE, etc., be set to "C" or not set at all. .PP Be aware that the value of the .C IFS variable in the user's environment affects the behavior of scripts. .PP .C ksh implements command substitution by creating a pipe between itself and the command. If the root file system is full, the substituted command cannot write to the pipe. As a result, the shell receives no input from the command, and the result of the substitution is null. In particular, using command substitution for variable assignment under such circumstances results in the variable being silently assigned a .SM NULL value. .PP At HP-UX version B10.10, the history file has a new internal magic number. This will cause a pre-10.10 history file to be discarded. Users who use multiple versions of HP-UX that NFS mount the same directory that contains the history file (usually the home directory) may want to have a separate history file for each HP-UX version by setting the HISTFILE parameter as: .IP .C HISTFILE=$HOME/.sh_hist_`uname -r` .PP Users on windowing systems may want to have separate history files for each window by setting the HISTFILE parameter as follows: .IP .C HISTFILE=$HOME/.sh_hist$$ .PP A cron job may be used to expire old history files. .PP .SH AUTHOR .C ksh was developed by AT&T. .SH FILES .TP 30 .PD 0 .C /etc/passwd to find home directories .TP .C /etc/profile read to set up system environment .TP .C /etc/suid_profile security profile .TP .C $HOME/.profile read to set up user's custom environment .TP .C /tmp/sh\(** for here-documents .PD .SH SEE ALSO cat(1), cd(1), echo(1), env(1), test(1), umask(1), vi(1), dup(2), exec(2), fork(2), gtty(2), pipe(2), signal(5), umask(2), ulimit(2), wait(2), rand(3C), a.out(4), profile(4), environ(5), lang(5), regexp(5). .\" .\" index@\f4ksh\f1 \- Korn shell command programming language@@@\f3ksh(1)\f1 .\" index@\f4rksh\f1 \- restricted Korn shell command programming language@@@\f3ksh(1)\f1 .\" index@alias \- substitute command and/or filename@@@\f3ksh(1)\f1 .\" index@break \- exit from enclosing for/next loop@@@\f3ksh(1)\f1 .\" index@case \- execute \f2list\f1 associated with \f2pattern\f1 that matches \f2word\f1@@@\f3ksh(1)\f1 .\" index@cd \- change working directory@@@\f3ksh(1)\f1 .\" index@continue \- resume next iteration of enclosing for/next loop@@@\f3ksh(1)\f1 .\" index@echo \- echo (print) arguments@@@\f3ksh(1)\f1 .\" index@eval \- read arguments as shell input and execute resulting commands@@@\f3ksh(1)\f1 .\" index@exec \- execute command without creating new process@@@\f3ksh(1)\f1 .\" index@exit \- exit shell with exit status@@@\f3ksh(1)\f1 .\" index@export \- export variable names to environment of subsequent commands@@@\f3ksh(1)\f1 .\" index@fc \- edit and execute previous command@@@\f3ksh(1)\f1 .\" index@for \- execute a do list@@@\f3ksh(1)\f1 .\" index@if \- execute command if previous command returns exit status 0@@@\f3ksh(1)\f1 .\" index@jobs \- list active jobs@@@\f3ksh(1)\f1 .\" index@kill \- terminate job or process@@@\f3ksh(1)\f1 .\" index@let \- evaluate arithmetic expression@@@\f3ksh(1)\f1 .\" index@newgrp \- equivalent to \f3exec newgrp\f1@@@\f3ksh(1)\f1 .\" index@print \- output from shell@@@\f3ksh(1)\f1 .\" index@pwd \- print current working directory@@@\f3ksh(1)\f1 .\" index@read \- input and parse a line@@@\f3ksh(1)\f1 .\" index@readonly \- mark names as unredefinable@@@\f3ksh(1)\f1 .\" index@return \- shell function return to invoking script@@@\f3ksh(1)\f1 .\" index@set \- set/define options and arguments@@@\f3ksh(1)\f1 .\" index@shift \- shift \f2argv\f1 members one position to left@@@\f3ksh(1)\f1 .\" index@test \- evaluate conditional expression@@@\f3ksh(1)\f1 .\" index@time, times \- print summary of time used by processes@@@\f3ksh(1)\f1 .\" index@trap \- trap specified signal@@@\f3ksh(1)\f1 .\" index@typeset \- control leading blanks and parameter handling@@@\f3ksh(1)\f1 .\" index@ulimit \- set size or time limits@@@\f3ksh(1)\f1 .\" index@umask \- set permissions mask for creating new files@@@\f3ksh(1)\f1 .\" index@unalias \- discard specified alias@@@\f3ksh(1)\f1 .\" index@unset \- remove definition/setting of options and arguments@@@\f3ksh(1)\f1 .\" index@until \- execute commands until expression is non-zero@@@\f3ksh(1)\f1 .\" index@wait \- wait for child process@@@\f3ksh(1)\f1 .\" index@whence \- define interpretation of name as a command@@@\f3ksh(1)\f1 .\" index@while \- execute commands while expression is non-zero@@@\f3ksh(1)\f1 .\" .\" toc@\f3ksh(1)\f1:\0\0\f2ksh\f1, \f2rksh\f1@@@shell, the standard/restricted command programming language .\" toc@\f2rksh\f1: restricted Korn shell command programming language@@@see \f3ksh(1)\f1 .\" toc@case: label in a switch statement@@@see \f3ksh(1)\f1 .\" toc@alias: substitute command and/or filename@@@see \f3ksh(1)\f1 .\" toc@break: exit from enclosing for/next loop@@@see \f3ksh(1)\f1 .\" toc@continue: resume next iteration of enclosing for/next loop@@@see \f3ksh(1)\f1 .\" toc@cd: change working directory@@@see \f3ksh(1)\f1 .\" toc@echo: echo (print) arguments@@@see \f3ksh(1)\f1 .\" toc@eval: read arguments as shell input and execute resulting commands@@@see \f3ksh(1)\f1 .\" toc@exec: execute command without creating new process@@@see \f3ksh(1)\f1 .\" toc@exit: exit shell with exit status@@@see \f3ksh(1)\f1 .\" toc@export: export variable names to environment of subsequent commands@@@see \f3ksh(1)\f1 .\" toc@fc: edit and execute previous command@@@see \f3ksh(1)\f1 .\" toc@for: execute a do list@@@see \f3ksh(1)\f1 .\" toc@if: execute command if previous command returns exit status 0@@@see \f3ksh(1)\f1 .\" toc@jobs: list active jobs@@@see \f3ksh(1)\f1 .\" toc@kill: terminate job or process@@@see \f3ksh(1)\f1 .\" toc@let: evaluate arithmetic expression@@@see \f3ksh(1)\f1 .\" toc@newgrp: equivalent to \f2exec newgrp\f1@@@see \f3ksh(1)\f1 .\" toc@print: output from shell@@@see \f3ksh(1)\f1 .\" toc@pwd: print current working directory@@@see \f3ksh(1)\f1 .\" toc@read: input and parse a line@@@see \f3ksh(1)\f1 .\" toc@readonly: mark names as unredefinable@@@see \f3ksh(1)\f1 .\" toc@return: shell function return to invoking script@@@see \f3ksh(1)\f1 .\" toc@set: set/define options and arguments@@@see \f3ksh(1)\f1 .\" toc@shift: shift \f2argv\f1 members one position to left@@@see \f3ksh(1)\f1 .\" toc@test: evaluate conditional expression@@@see \f3ksh(1)\f1 .\" toc@trap: trap specified signal@@@see \f3ksh(1)\f1 .\" toc@time, times: print summary of time used by processes@@@see \f3ksh(1)\f1 .\" toc@typeset: control leading blanks and parameter handling@@@see \f3ksh(1)\f1 .\" toc@ulimit: set size or time limits@@@see \f3ksh(1)\f1 .\" toc@umask: set permissions mask for creating new files@@@see \f3ksh(1)\f1 .\" toc@unalias: discard specified alias@@@see \f3ksh(1)\f1 .\" toc@unset: remove definition/setting of options and arguments@@@see \f3ksh(1)\f1 .\" toc@wait: wait for child process@@@see \f3ksh(1)\f1 .\" toc@whence: define interpretation of name as a command@@@see \f3ksh(1)\f1 .\" toc@while: execute commands while expression is non-zero@@@see \f3ksh(1)\f1 .\" toc@until: execute commands until expression is non-zero@@@see \f3ksh(1)\f1 .\" .\" links@ksh.1 rksh.1 .\" $Header: rlog.1,v 72.4 93/01/14 11:37:49 ssa Exp $ .TA r .TH rlog 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rlog \- print log messages and other information on \s-1RCS\s0 files .SH SYNOPSIS .C rlog .RI [ \|options\| ] .IR file \0... .SH DESCRIPTION .C rlog prints information about .SM RCS files. Files ending in .C ,v are .SM RCS files; all others are working files. If a working file is given, .C rlog tries to find the corresponding .SM RCS file first in directory .CR ./RCS , then in the current directory, as explained in .IR rcsintro (5). .PP .C rlog prints the following information for each .SM RCS file: .SM RCS file name, working file name, head (i.e., the number of the latest revision on the trunk), access list, locks, symbolic names, suffix, total number of revisions, number of revisions selected for printing, and descriptive text. This is followed by entries for the selected revisions in reverse chronological order for each branch. For each revision, .C rlog prints revision number, author, date/time, state, number of lines added/deleted (with respect to the previous revision), locker of the revision (if any), and log message. Without options, .C rlog prints complete information. The options below restrict this output. .SS Options .C rlog recognizes the following options: .RS .TP 15 .CI -d dates Print information about revisions whose check-in date and time fall within the ranges given by the semicolon-separated list of .IR dates . A range of the form .IC d1 < d2 or .IC d2 > d1 selects the revisions that were deposited between .I d1 and .I d2 (inclusive). A range of the form .CI < d or .IC d > selects all revisions dated .I d or earlier. A range of the form .IC d < or .CI > d selects all revisions dated .I d or later. A range of the form .I d selects the single, latest revision dated .I d or earlier. The date/time strings .IR d , .IR d1 , and .I d2 are in the free format explained in .IR co (1). Quoting is normally necessary, especially for .C < and .CR > . Note that the separator is a semicolon. .TP .C -h Print only .SM RCS file name, working file name, head, access list, locks, symbolic names, and suffix. .TP .CR -l [\|\f2lockers\fP\|] Print information about locked revisions. If the comma-separated list .I lockers of login names is given, only the revisions locked by the given login names are printed. If the list is omitted, all locked revisions are printed. .TP .C -L Ignore .SM RCS files that have no locks set; convenient in combination with .CR -R , .CR -h , or .CR -l . .TP .CI -r revisions Print information about revisions given in the comma-separated list .I revisions of revisions and ranges. A range .IR rev1 - rev2 means revisions .I rev1 to .I rev2 on the same branch, .CI - rev means revisions from the beginning of the branch up to and including .IR rev , and .IC rev - means revisions starting with .I rev to the head of the branch containingw .IR rev . An argument that is a branch means all revisions on that branch. A range of branches means all revisions on the branches in that range. .TP .C -R Print only the name of the .SM RCS file; convenient for translating a working file name into an .SM RCS file name. .TP .CI -s states Print information about revisions whose state attributes match one of the states given in the comma-separated list .IR states . .TP .C -t Print the same as .CR -h , plus the descriptive text. .TP .CR -w [\|\f2logins\fP\|] Prints information about revisions checked in by users whose login names appearing in the comma-separated list .IR logins . If .I logins is omitted, the user's login is assumed. .RE .PP .C rlog prints the intersection of the revisions selected with the options .CR -d , .CR -l , .CR -s , .CR -w , and .CR -r . .SH EXAMPLES Print the names of all .SM RCS files in the subdirectory named .C RCS that have locks: .IP .C "rlog -L -R RCS/*,v" .PP Print the headers of those files: .IP .C "rlog -L -h RCS/*,v" .PP Print the headers plus the log messages of the locked revisions: .IP .C "rlog -L -l RCS/*,v" .PP Print complete log information: .IP .C rlog RCS/*,v .PP Print the header and log messages of all revisions checked in after 1:00am on December 25th, 1991: .IP .C "rlog -d"">92/12/25, 1:00"" RCS/*,v" .PP Print the header and log messages of those revisions that were created between 10:00am and 2:00pm on July 4th, 1992: .IP .C "rlog -d""92/07/04, 10:00 > 92/07/04, 14:00"" RCS/*,v" .SH DIAGNOSTICS The exit status always refers to the last .SM RCS file operated upon, and is 0 if the operation was successful, 1 if unsuccessful. .SH AUTHOR .C rlog was developed by Walter F. Tichy. .SH SEE ALSO ci(1), co(1), ident(1), rcs(1), rcsdiff(1), rcsmerge(1), rcsfile(4), rcsintro(5). .\" .\" index@\f4rlog\f1 \- print log messages and other information about \s-1RCS\s+1 files@@@\f3rlog(1)\f1 .\" index@\s-1RCS\s+1: print log messages and other information about \s-1RCS\s+1 files@@@\f3rlog(1)\f1 .\" index@print log messages and other information about \s-1RCS\s+1 files@@@\f3rlog(1)\f1 .\" index@log messages and other information about \s-1RCS\s+1 files, print@@@\f3rlog(1)\f1 .\" .\" toc@\f3rlog(1)\f1:\0\0\f4rlog\f1@@@print log messages and other information on \s-1RCS\s+1 files .\" .\" fileset_database@rlog.1 USER-CMDS-MAN .\" $Header: rlogin.1,v 78.1 96/02/12 14:12:11 ssa Exp $ .TA r .TH rlogin 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rlogin \- remote login .SH SYNOPSIS .CR rlogin .I rhost .RC [ \-7 ] .RC [ \-8 ] .RC [ \-e\c .IR e ] .RC [ \-l .IR username ] .PP .I rhost .RC [ \-7 ] .RC [ \-8 ] .RC [ \-e\c .IR e ] .RC [ \-l .IR username ] .SH DESCRIPTION The .CR rlogin command connects your terminal on the local host to the remote host .RI ( rhost ). .CR rlogin acts as a virtual terminal to the remote system. The host name .I rhost can be either the official name or an alias as listed in the file .CR /etc/hosts (see .IR hosts (4)). .PP In a manner similar to the .CR remsh command (see .IR remsh (1)), .CR rlogin allows a user to log in on an equivalent remote host, .IR rhost , bypassing the normal login/password sequence. For more information about equivalent hosts and how to specify them in the files .CR /etc/hosts.equiv and .CR .rhosts , see .IR hosts.equiv (4). The searching of the files .CR /etc/hosts.equiv and .CR .rhosts occurs on the remote host, and the .CR .rhosts file must be owned by the remote user account or by a remote superuser. .PP If the originating user account is not equivalent to the remote user account, the originating user is prompted for the password of the remote account. If this fails, a login name and password are prompted for, as when .CR login is used (see .IR login (1)). .PP The terminal type specified by the current .CR TERM environment variable is propagated across the network and used to set the initial value of your .CR TERM environment variable on the remote host. Your terminal baud rate is also propagated to the remote host, and is required by some systems to set up the pseudo-terminal used by .CR rlogind (see .IR rlogind (1M)). .PP All echoing takes place at the remote site, so that (except for delays) the remote login is transparent. .PP If at any time .CR rlogin is unable to read from or write to the socket connection on the remote host, the message .CR "Connection closed" is printed on standard error and .CR rlogin exits. .SS Options .CR rlogin recognizes the following options. Note that the options follow the .I rhost argument. .RS .TP 15 .CR \-7 Set the character size to seven bits. The eighth bit of each byte sent is set to zero (space parity). .TP .CR \-8 Use an eight-bit data path. This is the default HP-UX behavior. .IP To use eight-bit characters, the terminal must be configured to generate either eight-bit characters with no parity, or seven bit characters with space parity. The HP-UX implementation of .CR rlogind (see .IR rlogind (1M)) interprets seven bit characters with even, odd, or mark parity as eight-bit non-USASCII characters. You may also need to reconfigure the remote host appropriately (see .IR stty (1) and .IR tty (7)). Some remote hosts may not provide the necessary support for eight-bit characters. In this case, or if it is not possible to disable parity generation by the local terminal, use the .CR \-7 option. .TP .CI \-e e Set the escape character to .IR e . There is no space separating the option letter and the argument character. To start a line with the escape character, two of the escape characters must be entered. The default escape character is tilde .RC ( ~ ). Some characters may conflict with your terminal configuration, such as .CR ^S , .CR ^Q , or backspace. Using one of these as the escape character may not be possible or may cause problems communicating with the remote host (see .IR stty (1) and .IR tty (7)). .TP .CI \-l \0username Set the user login name on the remote host to .IR username . The default name is the current account name of the user invoking .CR rlogin . .RE .SS Escape Sequences .CR rlogin can be controlled with two-character escape sequences, in the form .IR ex , where .IR e is the escape character and .IR x is a code character described below. Escape sequences are recognized only at the beginning of a line of input. The default escape character is tilde .RC ( ~ ). It can be changed with the .CR \-e option. .PP The following escape sequences are recognized: .RS .TP .I ey If .I y is NOT a code character described below, pass the escape character and .I y as characters to the remote host. .TP .IR ee Pass the escape character as a character to the remote host. .TP .IC e .\& Disconnect from the remote host. .TP .IC e !\& Escape to a subshell on the local host. Use .CR exit to return to the remote host. .PP If .CR rlogin is run from a shell that supports job control (see .IR csh (1), .IR ksh (1), and .IR sh-posix (1)), escape sequences can be used to suspend .CR rlogin . The following escape sequences assume that .CR ^Z and .CR ^Y are set as the user's .CR susp and .CR dsusp characters, respectively (see .IR stty (1) and .IR termio (7)). .TP .IC e ^Z Suspend the .CR rlogin session and return the user to the shell that invoked .CR rlogin . The .CR rlogin job can be resumed with the .CR fg command (see .IR csh (1), .IR ksh (1), and .IR sh-posix (1)). .IC e ^Z suspends both .CR rlogin processes: the one transmitting user input to the remote login, and the one displaying output from the remote login. .TP .IC e ^Y Suspend the .CR rlogin session and return the user to the shell that invoked .CR rlogin . The .CR rlogin job can be resumed with the .CR fg command (see .IR csh (1), .IR ksh (1), and .IR sh-posix (1)). .IC e ^Y suspends only the input process; output from the remote login continues to be displayed. .RE .PP If you "daisy-chain" remote logins (for example, you .CR rlogin from host A to host B and then .CR rlogin from host B to host C) without setting unique escape characters, you can repeat the escape character until it reaches your chosen destination. For example, the first escape character, .IR e , is seen as an escape character on host A; the second .IR e is passed as a normal character by host A and seen as an escape character on host B; a third .IR e is passed as a normal character by hosts A and B and accepted as a normal character by host C. .SS Remote Host Name As Command The system administrator can arrange for more convenient access to a remote host .RI ( rhost ) by linking .CR remsh to .CI /usr/hosts/ rhost\f1, allowing use of the remote host name .RI ( rhost ) as a command (see .IR remsh (1)). For example, if .CR remotehost is the name of a remote host and .CR /usr/hosts/remotehost is linked to .CR remsh , and if .CR /usr/hosts is in your search path, the command: .IP .C "remotehost" .PP is equivalent to: .IP .C "rlogin remotehost" .SH RETURN VALUES .CR rlogin sends an error message to standard error and returns a nonzero value if an error occurs before the connection to the remote host is completed. Otherwise, it returns a zero. .SH DIAGNOSTICS Diagnostics can occur from both the local and remote hosts. Those that occur on the local host before the connection is completely established are written to standard error. Once the connection is established, any error messages from the remote host are written to standard output, like any other data. .TP .C "login/tcp: Unknown service" .IP .CR rlogin was unable to find the login service listed in the .CR /etc/services database file. .TP .CI "There is no entry for you (user ID \&" username ") in /etc/passwd" .IP .CR rlogin was unable to find your user ID in the password file. .IP .IR "Next Step" : Contact your system administrator. .TP .IC "system call" : \f1... An error occurred when .CR rlogin attempted the indicated system call. See the appropriate manual entry for information about the error. .SH EXAMPLES Log in as the same user on the remote host .CR remote : .IP .C "rlogin remote" .PP Set the escape character to a .CR ! , use a seven-bit data connection, and attempt a login as user .CR guest on host .CR remhost : .IP .C "rlogin remhost -e! -7 -l guest" .PP Assuming that your system administrator has set up the links in .CR /usr/hosts , the following is equivalent to the previous command: .IP .C "remhost -e! -7 -l guest" .SH WARNINGS For security purposes, the .CR /etc/hosts.equiv and .CR .rhosts files should exist, even if they are empty. These files should be readable and writable only by the owner. See .IR host.equiv (4) for more information. .PP Note also that all information, including any passwords asked for, is passed unencrypted between the two hosts. .PP .CR rlogin is unable to transmit the Break key as an interrupt signal to the remote system, regardless of whether the user has set .CR "stty brkint" on the local system. The key assigned to .CR SIGINT with the command .CI "stty intr" \0c should be used instead (see .IR stty (1)). .SH AUTHOR .CR rlogin was developed by the University of California, Berkeley. .SH FILES .TP 30 .PD 0 .CR $HOME/.rhosts User's private equivalence list .TP .CR /etc/hosts.equiv List of equivalent hosts .TP .CR /usr/hosts/* For .IR rhost version of the command .PD .SH SEE ALSO csh(1), ksh(1), login(1), remsh(1), sh(1), sh-bourne(1), sh-posix(1), stty(1), telnet(1), rlogind(1M), hosts(4), hosts.equiv(4), inetd.conf(4), services(4), termio(7), tty(7). .\" .\" index@\f4rlogin\f1 \- remote login@@@\f3rlogin(1)\f1 .\" index@\f1remote login@@@\f3rlogin(1)\f1 .\" index@\f1login, remote@@@\f3rlogin(1)\f1 .\" .\" toc@\f3rlogin(1)\f1:\0\0\f4rlogin\f1@@@remote login .\" $Header: rm.1,v 76.1 95/08/04 16:40:47 ssa Exp $ .TA r .TH rm 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rm \- remove files or directories .SH SYNOPSIS .CR rm .RC \|[ -f \(or -i ]\| .RC \|[ -Rr ]\| .IR file \0... .SH DESCRIPTION The .CR rm command removes the entries for one or more files from a directory. If an entry was the last link to the file, the file is destroyed. Removal of a file requires write and search (execute) permission in its directory, but no permissions on the file itself. However, if the sticky bit is set on the directory containing the file, only the owner of the file, the owner of the directory, or a user having appropriate privileges can remove the file. .PP If a user does not have write permission for a file to be removed and standard input is a terminal, a prompt containing the file name and its permissions is printed requesting that the removal of the file be confirmed (see Access Control Lists below). A line is then read from standard input. If that line begins with .CR y the file is deleted; otherwise, the file remains. No questions are asked when the .CR -f option is given or if standard input is not a terminal. .PP If .IR file is of type directory, and the .CR -f option is not specified, and either the permissions of .IR file do not permit writing and standard input is a terminal or the .CR -i option is specified, .CR rm writes a prompt to standard error and reads a line from standard input. If the response does not begin with .CR y , it does nothing more with the current file and goes on to any remaining files. .SS Options .CR rm recognizes the following options: .RS .TP .CR -f Force each file or directory to be removed without prompting for confirmation, regardless of the permissions of the entry. This option also suppresses diagnostic messages regarding nonexistent operands. .IP This option does not suppress any diagnostic messages other than those regarding nonexistent operands. To suppress all error message and interactive prompts, the .CR -f option should be used while redirecting standard error output to .CR /dev/null . .IP This option ignores any previous occurrence of the .CR -i option. .TP .CR -i Write a prompt to standard error requesting confirmation before removing each entry. .IP This option ignores any previous occurrence of the .CR -f option. .TP .CR -R For each argument that is a directory, this option causes .CR rm to recursively delete the entire contents of that directory before removing the directory itself. When used in conjunction with the .CR -i option, .CR rm asks whether to examine each directory before interactively removing files in that directory and again afterward to confirm removing the directory itself. .IP The .CR -R option will descend to arbitrary depths in a file hierarchy and will not fail due to path length limitations unless the length of file name, .CR file specified by the user exceeds system limitations. .TP .CR -r Equivalent to .CR -R . .SS "Access Control Lists If a file has optional .SM ACL entries, .CR rm displays a plus sign .RC ( + ) after the file's permissions. The permissions shown summarize the file's .CR st_mode value returned by .CR stat() (see .IR stat (2)). See also .IR acl (5). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C rm will behave as if all internationalization variables are set to "C". See .IR environ (5). .PP .C LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .PP .C LC_CTYPE determines the interpretation of file names as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .C LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .C NLSPATH determines the location of message catalogues for the processing of .C LC_MESSAGES. .SS International Code Set Support Single- and multibyte character code sets are supported. .SH DIAGNOSTICS Generally self-explanatory. Note that the .CR -f option does not suppress all diagnostic messages. .PP It is forbidden to remove the file .CR .. , in order to avoid the consequences of using a command such as: .IP .C "rm -r .* .PP If a designated file is a directory, an error comment is printed unless the .CR -R or .CR -r option is used. .SH EXAMPLES Remove files with a prompt for verification: .IP .C "rm -i file1 file2 .PP Remove all the files in a directory: .IP .C "rm -i mydirectory/* .PP Note that the previous command removes files only, and does not remove any directories in .CR mydirectory . .PP Remove a file in the current directory whose name starts with .CR - or .CR * or some other character that is special to the shell: .IP .C "rm ./-filename" .br .C "rm \e*filename" .br etc. .PP Remove a file in the current directory whose name starts with some strange (usually nonprinting, invisible) character or perhaps has spaces at the beginning or end of the filename, prompting for confirmation: .IP .C "rm -i *filename* .PP If .CR *filename* is not unique in the directory, enter .CR n when each of the other files is prompted. .PP A powerful and dangerous command to remove a directory is: .IP .C "rm -fR directoryname .PP or .IP .C "rm -Rf directoryname .PP which removes all files and directories from .CR directoryname without any prompting for verification to remove the files or the directories. This command should only be used when you are absolutely certain that all the files and directories in .CR directoryname as well as .CR directoryname itself are to be removed. .SH DEPENDENCIES .SS NFS .CR rm does not display a plus sign .RC ( + ) to indicate the existence of optional access control list entries when asking for confirmation before removing a networked file. .SH SEE ALSO rmdir(1), unlink(2), acl(5).\" STD .SH STANDARDS CONFORMANCE .CR rm ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4rm\f1 \- remove files or directories@@@\f3rm(1)\f1 .\" index@files: remove@@@\f3rm(1)\f1 .\" index@remove a file or directory@@@\f3rm(1)\f1 .\" index@kill a file or directory@@@\f3rm(1)\f1 .\" index@delete a file or directory@@@\f3rm(1)\f1 .\" index@eliminate a file or directory@@@\f3rm(1)\f1 .\" .\" toc@\f3rm(1)\f1:\0\0\f4rm\f1@@@remove files or directories .\" .\" fileset_database@rm.1 UX-CORE-MAN .\" $Header: mail.1,v 72.5 94/11/14 15:19:57 ssa Exp $ .TA m .TH mail 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mail, rmail \- send mail to users or read mail .SH SYNOPSIS .C mail .RC [ + ] .RC [ -epqr ] .RC [ -f .IR file\| ] .PP .C mail .RC [ -dt ] .IR person \0... .PP .C rmail .RC [ -dt ] .IR person \0... .SS Remarks: See .IR mailx (1) and .IR elm (1) for an enhanced user mail interface. .SH DESCRIPTION The .C mail command, when used without arguments, prints the user's mail, message-by-message, in last-in, first-out order. .PP For each message, .C mail prints a .C ? prompt and reads a line from the standard input to determine the disposition of the message. Commands that automatically proceed to the next message exit from .C mail if .C mail already on the last message. .SS Commands .C mail supports the following commands: .RS .TP 15 Go on to next message. Exit if already on last message. .TP .C + Same as . .TP .C n Same as . .TP .C d Delete message and go on to next message. .TP .C p Print message again. .TP .C - Go back to previous message. .TP .CR s \0[\|\f2files\fP\|] Save message in the named .I files (default is .CR mbox ), mark the message for deletion from the user's .IR mailfile , and proceed to next message. .TP .CR y \0[\|\f2files\fP\|] Same as .CR s \0[\|\f2files\fP\|]. .TP .CR w \0[\|\f2files\fP\|] Save message without its header (the ``From ...'' line), in the named .I files (default is .CR mbox ), mark the message for deletion, and go on to next message. .TP .CI m \0person \0\f1... Mail the message to each named .IR person , mark the message for deletion, and go on to next message. .TP .C q Put undeleted mail back in the .C mailfile and stop. .TP .SM .CR EOT \0\s0(Ctrl-D) Same as .CR q . .TP .C x Abort. Leave original .C mailfile unchanged and stop. .TP .CI ! command Escape to the command interpreter and execute .IR command . .TP .C ? Print a command summary. .TP .C * Same as .CR ? . .RE .SS Command-Line Options The following command-line options alter printing of the mail: .RS .TP 15 .C + Cause messages to be printed in first-in, first-out order. .TP .C -e Suppresses printing of mail and returns the exit value: .RS .nf .IP 0 = Mail present 1 = No mail 2 = Other error .fi .RE .TP 15 .C -p Prints all mail without prompting for disposition. .TP .C -q Causes .C mail to terminate if an interrupt is received. Normally an interrupt only causes the termination of the printing of the current message. .TP .C -r Same as .CR + . .TP .CI -f \0file Causes .C mail to use .I file (for example, .CR mbox ) instead of the default .IR mailfile . .TP .C -t Causes the outbound message to be preceded by each .I person the mail is sent to. A .I person is usually a user name recognized by .C login (see .IR login (1)). If a .I person being sent mail is not recognized, or if .C mail is interrupted during input, the file .C dead.letter will be saved to allow editing and resending. Note that .C dead.letter is regarded as a temporary file in that it is recreated every time needed, erasing the previous contents of .CR dead.letter . .TP .C -d Causes .C mail to deliver mail directly. This isolates .C mail from making routing decisions, and allows it to be used as a local delivery agent. Typically this option is used by auto-routing facilities when they deliver mail locally. .RE .PP When .IR person s are named, .C mail takes the standard input up to an end-of-file (or up to a line consisting of just a .CR . ) and adds it to each .IR person 's .IR mailfile . The message is preceded by the sender's name and a postmark. .PP To denote a recipient on a remote system, prefix .I person by the system name and exclamation mark (see .IR uucp (1)). Everything after the first exclamation mark in .I person is interpreted by the remote system. In particular, if .I person contains additional exclamation marks, it can denote a sequence of machines through which the message is to be sent on the way to its ultimate destination. For example, specifying .C a!b!cde as a recipient's name causes the message to be sent to user .C b!cde on system .CR a . System .C a then interprets that destination as a request to send the message to user .C cde on system .CR b . This might be useful, for instance, if the sending system can access system .C a but not system .CR b . .C mail does not use .C uucp if the remote system is the local system name (i.e., localsystem!user). .PP The .C mailfile can be manipulated in two ways to alter the function of .CR mail . The .I other permissions of the file can be read-write, read-only, or neither read nor write to allow different levels of privacy. If changed to other than the default, the file is preserved, even when empty, to perpetuate the desired permissions. The file can also contain the first line: .IP .C Forward to .I person .PP which causes all mail sent to the owner of the .C mailfile to be forwarded to .IR person . This is especially useful for forwarding all of a person's mail to a given machine in a multiple-machine environment. In order for forwarding to work properly the .C mailfile should have "mail" as group .SM ID, and the group permission should be read-write. .PP .C rmail only permits the sending of mail. .C uucp uses .C rmail as a security precaution. .PP When a user logs in, the command .C mail -e can be used to detect the presence of mail, if any, and so indicate. When terminating, .C mail produces a notification message if new mail arrived while .C mail was running. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_TIME determines the format and contents of the displayed date and time strings. .PP If .C LC_TIME is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C mail behaves as if all internationalization variables are set to "C". See .IR environ (5). .PP When set, the .C TMPDIR environment variable specifies a directory to be used for temporary files, overriding the default directory .CR /tmp . .SS International Code Set Support Between .SM HP-UX systems, single- and multi-byte character code sets are supported within mail text. Headers are restricted to characters from the 7-bit .SM USASCII code set (see .IR ascii (5)). .SH WARNINGS Conditions sometimes result in a failure to remove a lock file. .PP After an interrupt, the next message may not be printed. To force printing, type a .CR p . .PP Lines that look like postmarks in the message (that is, ``From\0...'') are preceded by .CR > . .PP .C mail treats a line consisting solely of a dot .RC (\| . \|) as the end of the message, except when the .C rmail -d command is used. .PP The maximum allowable line length in mail messages is .C BUFSIZ bytes as defined in .CR /usr/include/stdio.h . If line length exceeds this limit, .C mail truncates the line starting at beginning-of-line, and uses only the trailing .C BUFSIZ characters. .PP Using two separate mail programs to access the same mail file simultaneously (usually inadvertently from two separate windows) can cause unpredictable results. .SH FILES .TP 25 .C /var/mail/*.lock Lock for mail directory .PD 0 .TP .C dead.letter Unmailable text .TP .C /tmp/ma* Temporary file .TP .C $MAIL Variable containing path name of .C mailfile .TP .C $HOME/mbox Saved mail .TP .C /etc/passwd To identify sender and locate persons .TP .C /var/mail Directory for incoming mail .br (mode .CR 775 , group .SM ID .CR mail ) .TP .CI /var/mail/ user Incoming mail for .IR user ; that is, the .B mailfile .br (mode .CR 660 , group .SM ID .CR mail ) .PD .SH SEE ALSO login(1), mailx(1), uucp(1), write(1). .SH STANDARDS CONFORMANCE .CR mail ": SVID2, SVID3, XPG2, XPG3" .PP .CR rmail ": SVID2, SVID3" .\" .\" index@\f4mail\f1 \- send mail to users or read mail@@@\f3mail(1)\f1 .\" index@\f4rmail\f1 \- restricted mailer (send only)@@@\f3mail(1)\f1 .\" index@restricted mailer (send only)@@@\f3mail(1)\f1 .\" index@send mail to users or read mail@@@\f3mail(1)\f1 .\" index@read mail or send mail to users@@@\f3mail(1)\f1 .\" .\" toc@\f3mail(1)\f1:\0\0\f4mail\f1, \f4rmail\f1@@@send mail to users or read mail .\" toc@\f4rmail\f1: send mail to users or read mail@@@see \f3mail(1)\f1 .\" .\" links@mail.1 rmail.1 .\" .\" fileset_database@mail.1 USER-CMDS-MAN .\" $Header: rmdel.1,v 76.2 95/08/23 17:35:39 ssa Exp $ .TA r .TH rmdel 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rmdel \- remove a delta from an \s-1SCCS\s0 file .SH SYNOPSIS .C rmdel -r .SM .I SID .IR file \0... .SH DESCRIPTION The .C rmdel command removes the delta specified by the .SM .I SID from each named .SM SCCS file. The delta to be removed must be the newest (most recent) delta in its branch in the delta chain of each named .SM SCCS file. In addition, the .SM SID specified must .I not be that of a version being edited for the purpose of making a delta (i.e., if a .I p-file (see .IR get (1)) exists for the named .SM SCCS file, the .SM SID specified must .I not appear in any entry of the .IR p-file ). .PP If a directory is named, .C rmdel behaves as though each file in the directory were specified as a named file, except that non-\c .SM SCCS files (last component of the path name does not begin with .CR s. ) and unreadable files are silently ignored. If a name of .C - is given, the standard input is read; each line of the standard input is taken to be the name of an .SM SCCS file or directory to be processed; non-\c .SM SCCS files and unreadable files are silently ignored. When .C -- is specified on the command line, all following arguments are treated as file names. .PP The permissions to remove a delta are either (1) if you make a delta you can remove it; or (2) if you own the file and directory you can remove a delta. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the locale for the interpretation of text as single-byte and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP .C LC_MESSAGES also determines the local language equivalent of the affirmative string ("yes"). .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C rmdel behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH DIAGNOSTICS Use .IR sccshelp (1) for explanations. .SH FILES .TP 15 .C x.file See .IR delta (1). .TP .C z.file See .IR delta (1). .SH SEE ALSO delta(1), get(1), sccshelp(1), prs(1), sccsfile(4). .SH STANDARDS CONFORMANCE .CR rmdel ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4rmdel\f1 \- remove a delta from an SCCS file@@@\f3rmdel(1)\f1 .\" index@\f1SCCS: remove a delta from an SCCS file@@@\f3rmdel(1)\f1 .\" index@\f1files: remove a delta from an SCCS file@@@\f3rmdel(1)\f1 .\" index@\f1remove a delta from an SCCS file@@@\f3rmdel(1)\f1 .\" index@\f1delta from an SCCS file, remove a@@@\f3rmdel(1)\f1 .\" .\" toc@\f3rmdel(1)\f1:\0\0\f4rmdel\f1@@@remove a delta from an \s-1SCCS\s+1 file .\" .\" $Header: rmdir.1,v 72.4 94/04/27 11:28:30 ssa Exp $ .TA r .TH rmdir 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rmdir \- remove directories .SH SYNOPSIS .C rmdir .RC [ -f | -i ] .RC [ -p ] .IR dir \0... .SH DESCRIPTION .C rmdir removes the directory entry for each .I dir operand that refers to an empty directory. .PP Directories are removed in the order specified. Consequently, if a directory and a subdirectory of that directory are both specified as arguments, the subdirectory must be specified before the parent directory so that the parent directory will be empty when .C rmdir tries to remove it. Removal of a directory requires write and search (execute) permission in its parent directory, but no permissions on the directory itself; but if the sticky bit is set on the parent directory, only the owner of the directory, the owner of the parent directory, or a user having appropriate privileges can remove the directory. .SS Options .C rmdir recognizes the following options: .RS .TP .C -f Force each directory to be removed without prompting for confirmation, regardless of the presence of the .C -i option. This option also suppresses diagnostic messages regarding non-existent operands. .IP This option does not suppress any diagnostic messages other than those regarding non-existent operands. To suppress all error message and interactive prompts, the .C -f option should be used while redirecting the standard error output to .CR /dev/null . .IP This option ignores any previous occurrence of the .CR -i option. .TP .C -i Write a prompt to the standard error output requesting confirmation before removing each directory. .IP This option ignores any previous occurrence of the .CR -f option. .TP .C -p Path removal. If, after removing a directory with more than one pathname component, the parent directory of that directory is now empty, .C rmdir removes the empty parent directory. This continues until .C rmdir encounters a non-empty parent directory, or until all components of the original pathname have been removed. .IP When used in conjunction with the .C -i option, .C rmdir asks whether to remove each directory component of a path. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C rmdir will behave as if all internationalization variables are set to "C". See .IR environ (5). .PP .C LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .PP .C LC_CTYPE determines the interpretation of .IR dir names as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .C LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .C NLSPATH determines the location of message catalogues for the processing of .C LC_MESSAGES. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS Generally self-explanatory. Note that the .C -f option does not suppress all diagnostic messages. .SH EXAMPLES To remove directories with a prompt for verification: .IP .C rmdir -i .I directories .PP To remove as much as possible of a path, type: .IP .CI "rmdir -p " component1 / component2 / dir .SH SEE ALSO rm(1), rmdir(2), stat(2). .SH STANDARDS CONFORMANCE .IR rmdir ": SVID2, XPG2, XPG3, XPG4" .\" .\" index@\f4rmdir\f1 \- remove directories@@@\f3rmdir(1)\f1 .\" index@directory: remove directory@@@\f3rmdir(1)\f1 .\" index@remove directory@@@\f3rmdir(1)\f1 .\" index@kill a directory@@@\f3rmdir(1)\f1 .\" index@delete a directory@@@\f3rmdir(1)\f1 .\" index@eliminate a directory@@@\f3rmdir(1)\f1 .\" .\" toc@\f3rmdir(1)\f1:\0\0\f4rmdir\f1@@@remove directories .\" .\" fileset_database@rmdir.1 USER-CMDS-MAN .\" $Header: rmnl.1,v 72.3 93/01/14 11:17:15 ssa Exp $ .TA r .TH rmnl 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rmnl \- remove extra new-line characters from file .SH SYNOPSIS .C rmnl .SH DESCRIPTION .C rmnl removes all blank lines from a file (except at beginning of file as explained below), and is useful for removing excess white space from files for display on a .SM CRT terminal. Groups of two or more successive \en (new-line) characters are reduced to a single \en character, effectively eliminating all blank lines in the file .I except that one or more blank lines at the beginning of a file remain as a single blank line. .PP To remove redundant blank lines rather than all blank lines, use .IR ssp (1). .PP To remove all blank lines from a file including beginning of file, use .C rmnl piped to .CR ssp , or .C ssp piped to .CR rmnl . .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH SEE\ ALSO man(1), ssp(1). .\" .\" toc@\f3rmnl(1)\f1:\0\0\f4rmnl\f1@@@remove extra new-line characters from file .\" .\" index@\f4rmnl\f1 \- remove extra new-line characters from file@@@\f3rmnl(1)\f1 .\" index@remove extra new-line characters from file@@@\f3rmnl(1)\f1 .\" index@files: remove all blank lines from file@@@\f3rmnl(1)\f1 .\" index@remove all blank lines from file@@@\f3rmnl(1)\f1 .\" index@blank lines, remove all from file@@@\f3rmnl(1)\f1 .\" .\" fileset_database@rmnl.1 USER-CMDS-MAN ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. * ...\" All rights reserved. * ...\" ******************************************************************** .cS .nr H1 1 -- Commented out because it undesirably reset a chapter counter. .cE ...\" .rm zA .rm zZ .TH rpc_intro 1 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .SH NAME .PP \*Lrpc_intro\*O - Introduction to the DCE RPC programmer commands .SH "DESCRIPTION" .PP DCE RPC provides the following programmer commands: .iX "programmer commands" .iX "RPC" "programmer commands" .iX "DCE RPC" "programmer commands" .iX "commands" "for RPC programmers" .ad l .ML .LI The \*Lidl\*O command invokes the Interface Definition Language (IDL) compiler to convert an interface definition, written in IDL, to output files. .iX "\*Lidl\*O command" .iX "commands" "\*Lidl\*O" .iX "IDL compiler" .iX "Interface Definition Language compiler" .zA "def,10534,R1.1,remove NCS compatibility documentation" .zZ "def,10534,R1.1,remove NCS compatibility documentation" .LI The \*Luuidgen\*O command creates a UUID string that you assign to an object to uniquely distinguish it from other objects. .iX "\*Luuidgen\*O command" .iX "commands" "\*Luuidgen\*O" .LE .ad b .PP See each command's reference page for further information. .SS IDL Base Data Types and IDL-to-C Type Mappings .PP .iX "data types" "of IDL" .iX "data types" "IDL-to-C mappings" .iX "IDL" "base data types" .iX "IDL" "IDL-to-C data-type mappings" ...\" ***************** ...\" WRITER'S NOTE: The remainder of this section, begining with ...\" The following table lists the IDL base data type specifiers. ...\" is shared with the rpc_intro(3) reference page. ...\" Changes to either copy of the text apply to both copies. ...\" ***************** The following table lists the IDL base data type specifiers. Where applicable, the table shows the size of the corresponding transmittable type and the type macro emitted by the IDL compiler for resulting declarations. .iX "\*Lidl_\*O macros" .iX "macros" "\*Lidl_\*O" .PP ...\" .TB "Base Data Type Specifiers \(em rpc_intro(1)" .TS center, box, tab(@); cb s s s s cb cb lb | lb | lb lb lb lb | lb | lb lb | lb | lb | l | lb. Base Data Type Specifiers \(em rpc_intro(1) _ @Specifier@@@Type Macro (sign)@(size)@(type)@Size@Emitted by idl _ @small@int@8 bits@idl_small_int @short@int@16 bits@idl_short_int @long@int@32 bits@idl_long_int @hyper@int@64 bits@idl_hyper_int unsigned@small@int@8 bits@idl_usmall_int unsigned@short@int@16 bits@idl_ushort_int unsigned@long@int@32 bits@idl_ulong_int unsigned@hyper@int@64 bits@idl_uhyper_int @@float@32 bits@idl_short_float @@double@64 bits@idl_long_float @@char@8 bits@idl_char @@boolean@8 bits@idl_boolean @@byte@8 bits@idl_byte @@void@\(em@idl_void_p_t @@handle_t@\(em@\(em .TE .PP Note that you can use the \*Lidl_\*O macros in the code you write for an application to ensure that your type declarations are consistent with those in the stubs, even when the application is ported to another platform. The \*Lidl_\*O macros are especially useful when passing constant values to RPC calls. For maximum portability, all constants passed to RPC calls declared in your network interfaces should be cast to the appropriate type because the size of integer constants (like the size of the \*Lint\*O data type) is unspecified in the C language. .PP The \*Lidl_\*O macros are defined in \*Ldce/idlbase.h\*O, which is included by header files that the IDL compiler generates. .iX "\*Lidlbase.h\*O" .br .ne 1.5i .SH "RELATED INFORMATION" .PP .ad l .zA "def,10534,R1.1,remove NCS compatibility doc" Commands: \*Lidl(1)\*O, \*Luuidgen(1)\*O. .PP Messages: \*(Tg. .PP Books: \*(Dg. .ad b .zZ "def,10534,R1.1,remove NCS compatibility doc" .\" $Header: rpcgen.1,v 72.4 94/09/15 15:24:03 ssa Exp $ .TA r .TH rpcgen 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rpcgen \- an \s-1RPC\s+1 protocol compiler .SH SYNOPSIS .C rpcgen .I infile .br .C rpcgen -h .RC [ -o .IR outfile\| ] .RI [ \|infile\| ] .br .C rpcgen -c .RC [ -o .IR outfile\| ] .RI [ \|infile\| ] .br .C rpcgen -s .I transport .RC [ -u ] .RC [ -o .IR outfile\| ] .RI [ \|infile\| ] .br .C rpcgen -l .RC [ -o .IR outfile\| ] .RI [ \|infile\| ] .br .C rpcgen -m .RC [ -o .IR outfile\| ] .RI [ \|infile\| ] .br .CR rpcgen " [\c" .C -D\c .IR name [\c .CI = value \c ]] .RC [ -u ] .RC [ -I " " .RC [ -K " " .IR seconds\| ]] .RC [ -L ] .RC [ -T ] .I infile .SH DESCRIPTION .C rpcgen is a tool that generates .C C code to implement an .SM RPC protocol. The input to .C rpcgen is a language similar to .C C known as .SM RPC (Remote Procedure Call) Language. Information about .SM RPC Language syntax is available in .IR "Power Programming with RPC" . .PP .C rpcgen is normally used in the first synopsis shown above where it takes an input file and generates five output files. If the .I infile is named .CR proto.x , .C rpcgen generates a header file in .CR proto.h , .SM XDR routines in .CR proto_xdr.c , server-side stubs in .CR proto_svc.c , and client-side stubs in .CR proto_clnt.c , and RPC dispatch table in .CR proto_tbl.i . .PP The synopsis forms requiring .CR -h , .CR -c , .CR -s , .CR -l , or .CR -m are used when only a particular output file is needed. Their usage is described in the Options section below. .PP The RPC dispatch table is intended for use of more sophisticated RPC servers. The entries in the RPC dispatch table contain: .IP + pointers to the service routine corresponding to that procedure .br + a pointer to the input and output arguments .br + the size of these routines .PP A server can use the dispatch table to check authorization and then to execute the service routine; a client library may use it to deal with the details of storage management and XDR data conversion. .PP The input file is processed by .C cpp before being interpreted by .C rpcgen (see .IR cpp (1)), meaning that all standard .C cpp directives are available for use in an .C rpcgen input file. Preprocessing by .C cpp is done for each output file created. For each type of output file, .C rpcgen defines a special .C cpp symbol for use by the .C rpcgen programmer: .RS .TP 15 .C RPC_HDR defined when compiling into header files .PD 0 .TP .C RPC_XDR defined when compiling into .SM XDR routines .TP .C RPC_SVC defined when compiling into server-side stubs .TP .C RPC_CLNT defined when compiling into client-side stubs .TP .C RPC_TBL defined when compiling into dispatch tables .PD .RE .PP In addition, .C rpcgen does preprocessing of its own. Any line beginning with .C % is passed directly into the output file, uninterpreted by .CR rpcgen . By using the .C cpp symbols mentioned above, you can pass text into a specific output file. .PP To provide customized .SM XDR routines for customized data types, you can declare data objects to be of a data type that is undefined to .CR rpcgen . .C rpcgen passes them through to the .C .h file it creates. You are responsible for providing the definition of such data types in user-supplied files. For every data type that is undefined, .C rpcgen assumes that there exists a routine with the name .C xdr_ prefixed to the name of the undefined type. .SS Options .C rpcgen recognizes the following options and command-line arguments: .RS .TP 18 .C -c Compile into .SM XDR routines. .TP .C -h Compile into .C C data-definitions (a header file) .TP .C -l Compile into client-side stubs. .TP .CI -s \0transport Compile into server-side stubs, using the specified transport. The supported transports are .C udp and .CR tcp . This option can be invoked more than once so as to compile a server that serves multiple transports. If .C rpcgen is called without options, the server-side code that is generated can serve both .C udp and .C tcp transports. .TP .C -m Compile into server-side stubs, but do not produce a .C main() routine. This option is useful if you want to supply your own .C main() . .TP .CI -o \0outfile Specify the name of the output file. If none is specified, standard output is used .RC ( -c , .CR -h , .CR -l , .CR -m , and .C -s modes only). .TP .C -u When the server-side stub is produced, additional code to handle signals is generated. On reception of a signal, this signal handler code unmaps the server program from the port mapper before the server terminates. This code is added only if a .C main() routine is produced in the server-side stub. The .C -u option must not be specified with the .CR -c , .CR -h , .CR -l , or .C -m options. .TP .CI -D \|name\f1[\f4=\f2value\f1] Define a symbol. Equivalent to the #define directive in the source. If no .I value is given, .I value is defined as 1. .TP .C -I Compile support for .C inetd(1M) in the server side stubs. Such servers can be self-started by .CR inetd . When the server is self-started, it backgrounds itself by default. A special define symbol RPC_SVC_FG can be used to run the server process in foreground, or the user may simply compile without the .C -I option. .TP .CI -K \0seconds By default, services created using .C rpcgen and invoked through port monitors wait 120 seconds after servicing a request before exiting. That interval can be changed using the .C -K flag. To create a server that exits immediately upon servicing a request, use .C -K 0. To create a server that never exits, the appropriate argument is .C -K -1. .TP .C -L When the servers are started in foreground, use .C syslog(3) to log the server errors instead of printing them on the standard error. .TP .C -T Generate the code to support RPC dispatch tables. .RE .PP The following signals are trapped: .CR SIGHUP , .CR SIGINT , .CR SIGQUIT , and .CR SIGTERM . .SH EXAMPLES The following example generates all five output files: .CR prot.h , .CR prot_clnt.c , .CR prot_svc.c , .CR prot_xdr.c , and .CR prot_tbl.i . .IP .C rpcgen -T prot.x .PP The following example generates .CR prot.h , .CR prot_xdr.c , .CR prot_clnt.c , and the server stub .CR prot_svc.c , which supports the server started by .CR inetd(1M) . .IP .C rpcgen -I prot.x .PP The following example sends the C data-definitions (header) to the standard output. .IP .C rpcgen -h prot.x .PP To create the server side stubs for the .CR tcp protocol and send the output to .CR prot_svc.c , use .IP .C rpcgen -s tcp -o prot_svc.c prot.x .SH WARNINGS Nesting of structures is not supported. Instead, structures can be declared at the top-level and their names used inside other structures to achieve the same effect. .PP Name clashes can occur when using program definitions, since the apparent scoping does not really apply. Most of these can be avoided by giving unique names for programs, versions, procedures and types. .SH AUTHOR .C rpcgen was developed by Sun Microsystems, Inc. and HP. .SH SEE ALSO .I "Power Programming with RPC" .\" .\" index@compilers, rpcgen; generate RPC protocols, C header files@@@\f3rpcgen(1)\f1 .\" index@\f4rpcgen\f1; generate \s-1RPC\s+1 protocols, C header files@@@\f3rpcgen(1)\f1 .\" index@generate \s-1RPC\s+1 protocols, C header files@@@\f3rpcgen(1)\f1 .\" index@\s-1RPC\s+1 protocols, generate C header files@@@\f3rpcgen(1)\f1 .\" index@generate C header files@@@\f3rpcgen(1)\f1 .\" index@C header files, generate@@@\f3rpcgen(1)\f1 .\" index@header files, C, generate@@@\f3rpcgen(1)\f1 .\" index@files, C header, generate@@@\f3rpcgen(1)\f1 .\" .\" toc@\f3rpcgen(1)\f1:\0\0\f4rpcgen\f1@@@an \s-1RPC\s+1 protocol compiler .\" $Header: sh-bourne.1,v 74.1 95/03/23 17:36:32 ssa Exp $ .TA s .TH sh-bourne 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sh, rsh \- Bourne shell, the standard/restricted command programming language .SH SYNOPSIS .C sh .RC [ -\|-acefhiknrstuvx \0...\|] .RI [ \|arg \0...\|] .br .C rsh .RC [ -\|-acefhiknrstuvx \0...\|] .RI [ \|arg \0...\|] .SH DESCRIPTION .C sh is a command programming language that executes commands read from a terminal or a file. .C rsh is a restricted version of the standard command interpreter .CR sh ; it is used to set up login names and execution environments whose capabilities are more controlled than those of the standard shell. See ``Invocation'' and ``Special Commands'' sections later in this entry for details about command line options and arguments, particularly the .C set command. .SS Definitions A .B blank is a tab or a space character. A .B name is a sequence of letters, digits, or underscores beginning with a letter or underscore. A .B parameter is a name, a digit, or any of the characters .CR * , .ifn \f3@\f1, .ift \f4@\f1, .CR # , .CR ? , .CR - , .CR $ , and .CR ! . .SS Commands A .B simple-command is a sequence of non-blank .B words separated by .BR blanks . The first word specifies the name of the command to be executed. Except as specified below, the remaining words are passed as arguments to the invoked command. The command name is passed as argument 0 (see .IR exec (2)). The .B value of a simple-command is its exit status if it terminates normally, or (octal) 200+\c .B status if it terminates abnormally (see .IR signal (5) for a list of status values). .PP A .B pipeline is a sequence of one or more .B commands separated by .C | (or, for historical compatibility, by .CR ^ ). The standard output of each command except the last is connected by a .IR pipe (2) to the standard input of the next command. Each command is run as a separate process and the shell waits for the last command to terminate. The exit status of a pipeline is the exit status of the last command. .PP A .B list is a sequence of one or more pipelines separated by .CR ; , .CR & , .CR && , or .CR |\|| , and optionally terminated by .C ; or .CR & . Of these four symbols, .C ; and .C & have equal precedence, which is lower than that of .C && and .CR |\|| . The symbols .C && and .C |\|| also have equal precedence. A semicolon .RC ( ; ) causes sequential execution of the preceding pipeline; an ampersand .RC ( & ) causes asynchronous execution of the preceding pipeline (i.e., the shell does .I not wait for that pipeline to finish). The symbol .C && .RC (\| |\|| ) causes the .I list following it to be executed only if the preceding pipeline returns a zero (non-zero) exit status. An arbitrary number of new-line characters instead of semicolons can appear in a .B list to delimit commands. .PP A .B command is either a simple-command or one of the following. Unless otherwise stated, the value returned by a command is that of the last simple-command executed in the command. .PP .TP 15 .if n \f3for\fP \f2name\fP [\| \f3in\fP \f2word\fP ... \|] \f3do\fP \f2list\fP \f3done\fP .ift \f4for\fP \f2name\fP [\| \f4in\fP \f2word\fP ... \|] \f4do\fP \f2list\fP \f3done\fP Each time a .C for command is executed, .I name is set to the next .I word taken from the .C in .I word list. If .CI in " word" \&... is omitted, the .C for command executes the .CI do \0list once for each positional parameter that is set (see .I Parameter Substitution below). Execution ends when there are no more words in the list. .TP .ifn \{\f3case\fP \f2word\fP \f3in\fP [\|\f2pattern\fP [\|\(bv \ \f2pattern\fP\|] ... \f3)\fP \f2list\fP \f3;;\fP\|] ... \f3esac\fP\} .ift \{\f4case\fP \f2word\fP \f4in\fP [\|\f2pattern\fP [\|\f4| \ \f2pattern\fP\|] ... \f4)\fP \f2list\fP \f4;;\fP\|] ... \f4esac\fP\} A .C case command executes the .I list associated with the first .I pattern that matches .IR word . The form of the patterns is the Pattern Matching Notation as qualified for the .C case command (see .IR regexp (5)). .TP .if n \{\f3if\fP \f2list\fP \f3then\fP \f2list\fP [\| \ \f3elif\fP \f2list\fP \f3then\fP \f2list\fP \|] ... \ [\| \f3else\fP \f2list\fP \|] \f3f\&i\fP\} .if t \{\f4if\fP \f2list\fP \f4then\fP \f2list\fP \ [\|\f4elif\fP \f2list\fP \f4then\fP \f2list\fP\|] ... \ [\|\f4else\fP \f2list\fP\|] \f4f\&i\fP\} The .I list following .C if is executed and, if it returns a zero exit status, the .I list following the first .C then is executed. Otherwise, the .I list following .C elif is executed and, if its value is zero, the .I list following the next .C then is executed. Failing that, the .C else .I list is executed. If no .C else .I list or .C then .I list is executed, the .C if command returns a zero exit status. .TP .CI while \0list \0do \0list \0done A .C while command repeatedly executes the .C while .I list and, if the exit status of the last command in the list is zero, executes the .C do .IR list ; otherwise the loop terminates. If no commands in the .C do .I list are executed, the .C while command returns a zero exit status; .C until can be used in place of .C while to negate the loop termination test. .TP .CI ( \|list\| ) Execute .I list in a sub-shell. .TP .CI { \|list\| ;} The purpose of using braces is to allow the aggregate output from .I list to be redirected elsewhere. If redirection is used as in: .RS .IP .CI { \|list ;\|}\0> \|file .RE .IP a subshell is created to execute .IR list . This implies that any shell variables set, created, or modified within the .C {\|} do not retain their values outside the .CR {\|} . If no redirection is used, a subshell is not created, and shell modifications made within the .C {\|} are preserved. .TP .IC name \0(\|)\0{ \|list ;\|} Define a function which is referenced by .I name. The body of the function is the .I list of commands between .C { and .CR } . Execution of functions is described below (see ``Execution''). .PP The following words are recognized only as the first word of a command, and when not quoted: .IP .C "if then else elif fi case esac for while until do done { }" .SS Comments A word beginning with .C # causes that word and all the following characters up to a new-line character to be ignored. .SS Command Substitution The standard output from a command enclosed in a pair of grave accents .RC ( \(ga\|\(ga ) can be used as part or all of a word; trailing new-lines are removed. .SS Parameter Substitution The .C $ character is used to introduce substitutable .IR parameters . There are two types of parameters, positional and keyword. If .I parameter is a digit, it is a positional parameter. Positional parameters can be assigned values by .CR set . Keyword parameters (also known as variables) can be assigned values by writing: .IP .IC name = value [\|\c .IC name = value\c \|] ... .PP Pattern-matching is not performed on .IR value . Having a function and a variable with the same .I name is not allowed. .PP .TP 15 .CI ${ \|parameter\| } The value, if any, of the parameter is substituted. Braces are required only when .I parameter is followed by a letter, digit, or underscore that is not to be interpreted as part of its name. If .I parameter is .C * or .ifn \f3@\f1, .ift \f4@\f1, all positional parameters, starting with .CR $1 , are substituted (separated by spaces). Parameter .C $0 is set from argument zero when the shell is invoked. .TP .CI ${ parameter :- word } If .I parameter is set and is non-null, substitute its value; otherwise substitute .IR word . .TP .CI ${ parameter := word } If .I parameter is not set or is null, set it to .IR word ; the value of the parameter is then substituted. Positional parameters cannot be assigned to in this way. .TP .CI ${ parameter :? word } If .I parameter is set and is non-null, substitute its value; otherwise, print .I word and exit from the shell. If .I word is omitted, the message ``parameter null or not set'' is printed. .TP .CI ${ parameter :+ word } If .I parameter is set and is non-null, substitute .IR word ; otherwise substitute nothing. .PP In the above, .I word is not evaluated unless it is to be used as the substituted string. Thus, in the following example, .C pwd is executed only if .C d is not set or is null: .IP .C echo \|${d:-\(gapwd\(ga} .PP If the colon .RC ( : ) is omitted from the above expressions, the shell only checks whether .I parameter is set or not. .PP The following parameters are automatically set by the shell: .RS .TP 15 .C # The number of positional parameters in decimal. .TP .C - Flags supplied to the shell on invocation or by the .C set command. .TP .C ? The decimal value returned by the last synchronously executed command. .TP .C $ The process id of the last separately-invoked shell (i.e., a shell arising from direct invocation or .CR #! ). This parameter is not updated for subshells arising from .CR (\|) , command substitution, etc. .TP .C ! The process number of the last background command invoked. .TP .C LINES .PD 0 .TP .C COLUMNS The number of lines and columns in the current display area. These parameters are set only under specific circumstances. See .IR Signals . .PD .RE .PP The following parameters are used by the shell: .RS .TP 15 .C HOME The default argument (home directory) for the .C cd command. .TP .C PATH The search path for commands (see ``Execution'' below). Users executing under .C rsh cannot change .CR PATH . .TP .C CDPATH The search path for the .C cd command. .TP .C MAIL If this parameter is set to the name of a mail file .I and the .C MAILPATH parameter is not set, the shell informs the user of the arrival of mail in the specified file. .TP .C MAILCHECK This parameter specifies how often (in seconds) the shell will check for the arrival of mail in the files specified by the .C MAILPATH or .C MAIL parameters. The default value is 600 seconds (10 minutes). If set to 0, the shell checks before each prompt. .TP .C MAILPATH A colon .RC ( : )-\c separated list of file names. If this parameter is set, the shell informs the user of the arrival of mail in any of the specified files. Each file name can be followed by .C % and a message to be printed when the modification time changes. The default message is .CR "you have mail" . .TP .C PS1 Primary prompt string, by default .RC `` "$ \|" ''. .TP .C PS2 Secondary prompt string, by default .RC `` "> \|" ''. .TP .C IFS Internal field separators, normally .BR space , .BR tab , and .BR new-line . .TP .C SHACCT If this parameter is set to the name of a file writable by the user, the shell writes an accounting record in the file for each shell procedure executed. Accounting routines such as .IR acctcom (1M) and .IR acctcms (1M) can be used to analyze the data collected. .TP .C SHELL When the shell is invoked, it scans the environment (see ``Environment'' below) for this name. If it is found and there is an .C r in the file name part of its value, the shell becomes a restricted shell. .C SHELL is also used by some processors to determine which command interpreter to run. .PD .RE .PP The shell gives default values to .CR PATH , .CR PS1 , .CR PS2 , .CR MAILCHECK , and .CR IFS . .C HOME and .C MAIL are set by .IR login (1). .SS Blank Interpretation After parameter and command substitution, the results of substitution are scanned for internal field separator characters (those found in .CR IFS ) and split into distinct arguments where such characters are found. Explicit null arguments .ifn (\f3"\|"\fP or \f3'\|'\fP) .ift (\f4"\|"\fP or \f4\'\|\'\fP) are retained. Implicit null arguments (those resulting from .I parameters that have no values) are removed. .SS File Name Generation Following substitution, each command .I word is processed as a pattern for file name expansion. The form of the patterns is the Pattern Matching Notation defined by .IR regexp (5). .SS Quoting The following characters have a special meaning to the shell and cause termination of a word unless quoted: .IP .CR ; , .CR & , .CR ( , .CR ) , .CR | , .CR ^ , .CR < , .CR > , .IR new-line , .IR space , .IR tab , .C # (comment) .PP A character can be .B quoted (i.e., made to stand for itself) by preceding it with a .CR \e . The pair .CI \e new-line is ignored. All characters enclosed between a pair of single quote marks .RC ( \'\|\' ), except a single quote, are quoted. Inside double quote marks .ifn (\f3"\|"\fP), .ift (\f4"\|"\fP), parameter and command substitution occurs and .C \e quotes the characters .CR \e , .CR \(ga , .ifn \f3"\fP, .ift \f4"\fP, and .CR $ . .ifn \f3"$*"\fP .ift \f4"$*"\fP is equivalent to .ifn \f3"$1 \|$2\fP \|...\f3"\fP, .ift \f4"$1 \|$2\fP \|...\f4"\fP, whereas .ifn \f3"$@"\fP .ift \f4"$@"\fP is equivalent to .ifn \f3"$1""$2"\fP .ift \f4"$1""$2"\fP \&...\|. .SS Prompting When used interactively, the shell prompts with the value of .C PS1 before reading a command. If at any time a new-line is typed and further input is needed to complete a command, the secondary prompt (i.e., the value of .CR PS2\s0 ) is issued. .SS Input/Output Before a command is executed, its input and output can be redirected using a special notation interpreted by the shell. The following can appear anywhere in a simple-command or can precede or follow a .I command and are .I not passed on to the invoked command; substitution occurs before .I word or .I digit is used: .RS .TP 14 .CI < word Use file .I word as standard input (file descriptor 0). .TP .CI > word Use file .I word as standard output (file descriptor 1). If the file does not exist then it is created; otherwise, it is truncated to zero length. .TP .CI >> word Use file .I word as standard output. If the file exists then output is appended to it (by first seeking to the end-of-file); otherwise, the file is created. .TP .CR << [ - ] \f2word\fP The shell input is read up to a line that is the same as .IR word , or to an end-of-file. The resulting document becomes the standard input. If any character of .I word is quoted, no interpretation is placed upon the characters of the document; otherwise, parameter and command substitution occurs, (unescaped) .CI \e new-line is ignored, and .C \e must be used to quote the characters .CR \e , .CR $ , .CR \(ga , and the first character of .IR word . If .C - is appended to .CR << , all leading tabs are stripped from .I word and from the document. .TP .CI <& digit Use the file associated with file descriptor .I digit as standard input. Similarly for the standard output using .CI >& digit (see .IR dup (2)). Note that .I digit must be in the range 0 through 9. .TP .C <&- The standard input is closed. Similarly for the standard output using .CR >&- . .RE .PP If any of the above is preceded by a digit in the range 0 through 9, the file descriptor that becomes associated with the file is that specified by the digit (rather than the default 0 or 1). For example: .IP .RC \&... \02>&1 .PP associates file descriptor 2 with the file currently associated with file descriptor 1. Note that this type of .SM I/O redirection is necessary when .I synchronously collecting standard output and standard error output in the same file. Redirecting standard output and standard error separately causes asynchronous collection of data at the destination (information written to standard output can be subsequently over-written by information written to standard error and vice-versa). .PP The order in which redirections are specified is significant. The shell evaluates redirections left-to-right. For example: .IP .CI ...\01> xxx \02>&1 .PP first associates file descriptor 1 with file .IR xxx . It associates file descriptor 2 with the file associated with file descriptor 1 (i.e. .IR xxx ). If the order of redirections is reversed, file descriptor 2 is associated with the terminal (assuming file descriptor 1 was originally) and file descriptor 1 is associated with file .IR xxx . .PP If a command is followed by .CR & , the default standard input for the command is the empty file .CR /dev/null . Otherwise, the environment for executing a command contains the file descriptors of the invoking shell as modified by input/output specifications. .PP Redirection of output is not allowed in the restricted shell. .SS Environment The .B environment (see .IR environ (5)) is a list of name-value pairs that is passed to an executed program in the same way as a normal argument list. The shell interacts with the environment in several ways. On invocation, the shell scans the environment and creates a parameter for each name found, giving it the corresponding value. Executed commands inherit the same environment. If the user modifies the value of any of these parameters or creates new parameters, none of these affects the environment unless the .C export command is used to bind the shell's parameter to the environment (see also .CR "set -a" ). To remove a parameter from the environment, use the .C unset command. The environment seen by any executed command is thus composed of any unmodified name-value pairs originally inherited by the shell, minus any pairs removed by .CR unset , plus any modifications or additions, all of which must be noted in .C export commands. .PP The environment for any .I simple-command can be augmented by prefixing it with one or more assignments to parameters. Thus: .IP .CI TERM=450 \0cmd .PP and .IP .CI "(export TERM; TERM=450;" \0cmd ) .PP are equivalent (as far as the execution of .I cmd is concerned). .PP If the .C -k option is set, .I all keyword arguments are placed in the environment, even if they occur after the command name. The following first prints .C "a=b c" and then .CR c : .IP .C echo \|a=b \|c .br .C set -k .br .C echo \|a=b \|c .RE .SS Signals The .C INTERRUPT and .C QUIT signals for an invoked command are ignored if the command is followed by .C & and the command does not override the .C SIGINT and .C SIGQUIT signal settings it inherited from .CR /usr/old/bin/sh ; otherwise signals have the values inherited by the shell from its parent, with the exception of signal 11 (but see also the .C trap command below). .PP If a .SM SIGWINCH signal is received, .C sh determines the new size of the display area and resets the values of the .C LINES and .C COLUMNS variables appropriately. Note that the value of either variable is modified only if that variable exists at the time .SM SIGWINCH is received. .C sh does not create these variables. Any traps set on .SM SIGWINCH are executed immediately after .C LINES and .C COLUMNS are reset. .SS Execution Each time a command is executed, the above substitutions are carried out. If the command name matches one of the .I Special Commands listed below, it is executed in the shell process. If the command name does not match a .IR "Special Command" , but matches the name of a defined function, the function is executed in the shell process (note how this differs from the execution of shell procedures). The positional parameters .CR $1 , .CR $2 , \&...\|. are set to the arguments of the function. If the command name matches neither a .I Special Command nor the name of a defined function, a new process is created and an attempt is made to execute the command via .IR exec (2). .PP The shell parameter .C PATH defines the search path for the directory containing the command. Alternative directory names are separated by a colon .RC ( : ). The default path is .C :/usr/bin (specifying the current directory and .CR /usr/bin , in that order). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If the command name contains a .C / the search path is not used (such commands are not executed by the restricted shell). Otherwise, each directory in the path is searched for an executable file. If the file has execute permissions but is not a directory or an executable object code file, it is assumed to be a script file which is a file of data for an interpreter. If the first two characters of the script file are .CR #! , .C exec (see .IR exec (2)) expects an interpreter path name to follow. .C exec then attempts to execute the specified interpreter as a separate process to read the entire script file. If a call to .C exec fails, .C /usr/old/bin/sh is spawned to interpret the script file. .PP A parenthesized command is also executed in a sub-shell. The location in the search path where a command was found is remembered by the shell (to help avoid unnecessary .CR exec s later). If the command was found in a relative directory, its location must be re-determined whenever the current directory changes. The shell forgets all remembered locations whenever the .C PATH variable is changed or the .C hash -r command is executed (see below). .SS Special Commands The following commands are executed in the shell process. Input/output redirection is permitted for these commands. File descriptor 1 is the default output location. .TP 20 .C : No effect; the command does nothing. A zero exit code is returned. .TP .CI .\0 file Read and execute commands from .I file and return. The search path specified by .C PATH is used to find the directory containing .IR file . Note that this command does not spawn another shell to execute .IR file , and thus differs in behavior and output from executing .I file as a shell script. It is not necessary that the execute permission bit be set for .IR file . .TP .CR break\0 [\|\f2n\fP\|] Exit from the enclosing .C for or .C while loop, if any. If .I n is specified, break .I n levels. .TP .CR continue\0 [\|\f2n\fP\|] Resume the next iteration of the enclosing .C for or .C while loop. If .I n is specified, resume at the .IR n -th enclosing loop. .TP .CR cd\0 [\|\f2arg\fP\|] Change the current directory to .IR arg . The shell parameter .C HOME is the default .IR arg . The shell parameter .C CDPATH defines the search path for the directory containing .IR arg . Alternative directory names are separated by a colon .RC ( : ). The default path is null (meaning the current directory). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If .I arg begins with a .C / the search path is not used. Otherwise, each directory in the path is searched for .IR arg . The .C cd command cannot be executed by .CR rsh . .TP .CR echo\0 [\|\f2arg\fP\0...\|] Echo arguments. See .IR echo (1) for usage and description. .TP .CR eval\0 [\|\f2arg\fP\0...\|] The arguments are read as input to the shell and the resulting command(s) executed. .TP .CR exec\0 [\|\f2arg\fP\0...\|] The command specified by the arguments is executed in place of this shell without creating a new process. Input/output arguments can appear and, if no other arguments are given, cause the shell input/output to be modified. .TP .CR exit\0 [\|\f2n\fP\|] Causes a shell to exit with the exit status specified by .IR n . If .I n is omitted, the exit status is that of the last command executed (an end-of-file also causes the shell to exit.) .TP .CR export\0 [\|\f2name\fP\0...\|] The given .IR name s are marked for automatic export to the .I environment of subsequently-executed commands. If no arguments are given, a list of names currently included in the environment are printed. Function names .I cannot be exported. .TP .CR hash\0 [ -r ]\0[\|\f2name\fP\0...\|] For each .IR name , the location in the search path of the command specified by .I name is determined and remembered by the shell. The .C -r option causes the shell to forget all remembered locations. If no arguments are given, information about remembered commands is presented. .I hits is the number of times a command has been invoked by the shell process. .I cost is a measure of the work required to locate a command in the search path. Certain situations require that the stored location of a command be recalculated. Commands for which this will be done are indicated by an asterisk .RC (\| * \|) adjacent to the .I hits information. .I cost is incremented when the recalculation is done. .TP .CR newgrp\0 [\|\f2arg\fP\0...\|] Equivalent to .CI "exec newgrp" " arg" \&...\|. See .IR newgrp (1) for usage and description. .TP .C pwd Print the current working directory. .CI read \0name\0\f1... One line is read from the standard input and the first word is assigned to the first .IR name , the second word to the second .IR name , etc., with leftover words assigned to the last .IR name . The return code is 0 unless an end-of-file is encountered. .IP Note that although the read command is a built-in command and is generally executed directly by the shell, this is not the case when it is used in a pipeline. In a pipeline, a new shell is forked to execute the read command with the result that any shell variables set are not available to the parent shell when the pipeline is finished. This has the effect of making the read command useless in a pipeline. .TP .CR readonly\0 [\|\f2name\fP\0...\|] The given .IR name s are marked .I readonly and the values of the these .IR name s cannot be changed by subsequent assignment. If no arguments are given, a list of all .I readonly names is printed. .TP .CR return\0 [\|\f2n\fP\|] Causes a function to exit with the return value specified by .IR n . If .I n is omitted, the return status is that of the last command executed. .TP .CR set\0 [ -\|-aefhkntuvx\0 [\|\f2arg\fP\0...\|]\|] .C set sets or unsets options, and resets the values of the positional parameters to the args given, if any. The option list is terminated by the first argument that does not begin with .C - or .CR + , or upon encountering an argument consisting entirely of .CR -\|- . Recognized options are: .RS .RS .TP .C -a Mark variables which are modified or created for export. .TP .C -e Exit immediately if a command exits with a non-zero exit status. .TP .C -f Disable file name generation .TP .C -h Locate and remember function commands as functions are defined (function commands are normally located when the function is executed). .TP .C -k All keyword arguments are placed in the environment for a command, not just those that precede the command name. .TP .C -n Read commands but do not execute them. .TP .C -t Exit after reading and executing one command. .TP .C -u Treat unset variables as an error when substituting. .TP .C -v Print shell input lines as they are read. .TP .C -x Print commands and their arguments as they are executed. .TP .C -\|- Do not change any of the options; useful when .C $1 is to be set to a string beginning with .C - or .CR + . .RE .RE .IP Using .C \+ rather than .C - causes these options to be unset. These options can also be used upon invocation of the shell. The current set of options can be found in .CR $- . The remaining arguments are positional parameters and are assigned, in order, to .CR $1 , .CR $2 , \&...\|. If no arguments are given, the values of all names are printed. .TP .CR shift\0 [\|\f2n\fP\|] The positional parameters from .C $n+1 \&... are renamed .C $1 \&...\|. If .I n is not given, it is assumed to be 1. .TP .C test Evaluate conditional expressions. See .IR test (1) for usage and description. Note that .CR [\| ... \|] in an .C if .I list is interpreted the same as .CR test\0 ...\|. There must be blanks around the brackets. .TP .C times Print the accumulated user and system times for processes run from the shell. .TP .CR trap\0 [\|\f2arg\fP\|]\0[\|\f2n\fP\|]\0... The command .I arg is a command to be read and executed when the shell receives signal(s) .IR n . (Note that .I arg is scanned once when the trap is set and once when the trap is taken.) Trap commands are executed in order of signal number. Any attempt to set a trap on a signal that was ignored on entry to the current shell is ineffective. An attempt to trap on signal 11 (memory fault) or signal 18 (death of child) produces an error. If .I arg is absent then all trap(s) .I n are reset to their original values. If .I arg is the null string, this signal is ignored by the shell and by the commands it invokes. If .I n is 0, the command .I arg is executed on exit from the shell. The .B trap command with no arguments prints a list of commands associated with each signal number. .TP .CR type\0 [\|\f2name\fP\0...\|] For each .IR name , indicate how it would be interpreted if used as a command name. .TP .CR ulimit\0 [ -f\0 [\|\f2n\fP\|]\|] If the .CI -f " n" option is used, a size limit of .I n blocks is imposed on files written by child processes (files of any size can be read). If .I n is not specified, the current limit is printed. If no option is specified, .C -f is assumed. .TP .CR umask\0 [\|\f2nnn\fP\|] The user file-creation mask is set to .I nnn (see .IR umask (2)). If .I nnn is omitted, the current value of the mask is printed. .TP .CR unset\0 [\|\f2name\fP\0...\|] For each .IR name , remove the corresponding variable or function. The variables .CR PATH , .CR PS1 , .CR PS2 , .CR MAILCHECK , and .C IFS cannot be unset. .TP .CR wait \0[\|\f2n\fP\|] Wait for the specified process and report its termination status. If .I n is not given all currently active child processes are waited for and the return code is zero. .PP .SS Invocation Options can be specified in a single argument or in multiple arguments, but in all cases each option argument must begin with .CR - . (All options except .CR c , .CR s , .CR i , and .C r can also be prefaced with a .CR + , which turns off the associated option or options, but this is redundant when invoking a new shell because all options are turned off by default). .PP If the first character of argument zero is .CR - , commands are initially read from .CR /etc/profile , then from .CR $HOME/.profile , if the files exist. Thereafter, commands are read as described below. .PP The options below are interpreted by the shell at invocation (thus they cannot be used with the .C set command). Unless the .C -c or .C -s option is specified, the first non-option argument is assumed to be the name of a file containing commands, and the remaining arguments are passed as positional parameters to that command file. .RS .TP 10 .CI -c "\| string" If the .C -c option is present then commands are read from .IR string . .TP .C -s If the .C -s option is present or if no arguments remain, commands are read from the standard input. Any remaining arguments specify the positional parameters. Shell output (except for "Special Commands" ) is written to file descriptor 2. .TP .C -i If the .C -i option is present or if the shell input and output are attached to a terminal, this shell is .IR interactive . In this case .SM TERMINATE is ignored (so that .C kill 0 does not kill an interactive shell) and .SM INTERRUPT is caught and ignored (so that .C wait is interruptible). In all cases, .SM QUIT is ignored by the shell. .TP .C -r If the .C -r option is present the shell is a restricted shell. .RE .PP The remaining options and arguments are described under the .C set command above. .ifn .SS rsh Only .ift .SS \f4rsh\fP Only .C rsh is used to set up login names and execution environments whose capabilities are more controlled than those of the standard shell. The actions of .C rsh are identical to those of .CR sh , except that the following are disallowed: .RS .TP 3 \(bu Changing directory (see .IR cd (1)), .PD 0 .TP \(bu Setting the value of .CR $PATH, .TP \(bu Specifying path or command names containing .CR / , .TP \(bu Redirecting output .RC ( > and .CR >> ). .PD .RE .PP The restrictions above are enforced after .C .profile is interpreted. .PP When a command to be executed is found to be a shell procedure, .C rsh invokes .C sh to execute it. Thus, it is possible to provide to the end-user shell procedures that have access to the full power of the standard shell, while imposing a limited menu of commands; this scheme assumes that the end-user does not have write and execute permissions in the same directory. .PP The net effect of these rules is that the writer of the .C .profile has complete control over user actions, by performing guaranteed setup actions and leaving the user in an appropriate directory (probably .I not the login directory). .PP The system administrator often sets up a directory of commands (such as .CR /usr/rbin ) that can be safely invoked by .CR rsh . Commands such as .CR vi , .CR sh , .CR ksh , .CR csh , and such that can break .C rsh restrictions should not be included in that directory. Some systems also provide a restricted editor .CR red . .SH EXTERNAL INFLUENCES .SS Environment Variables .SM LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. .PP .SM LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as letters, and the characters matched by character class expressions in pattern matching notation. .PP .SM LANG determines the language in which messages are displayed. .PP If .SM LC_COLLATE or .SM LC_CTYPE is not specified in the environment or is set to the empty string, the value of .SM LANG is used as a default for each unspecified or empty variable. If .SM LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .SM LANG. If any internationalization variable contains an invalid setting, .C sh behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE The error codes returned by the shell are: .RS .TP 5 .B 0 Success. .PD 0 .TP .B 1 Built-in command failure (see .IR Special Commands ). .TP .B 2 Syntax error. .TP .B 3 Signal received that is not trapped. .PD .RE .PP If the shell is non-interactive, it terminates and passes one of the above as its exit status. If it is interactive, it does not terminate, but .C $? is set to one of the above values. .PP Whenever a child process of the shell dies due to a signal, the shell returns an exit status of 80 hexadecimal plus the number of the signal. .\".SH EXAMPLES .\" None appropriate. .SH WARNINGS If a command is executed and a command having the same name is installed in a directory in the search path before the directory where the original command was found, the shell continues to .C exec the original command. Use the .C hash command to correct this situation. .PP When the shell encounters .CR >> , it does not open the file in append mode. Instead, it opens the file for writing and seeks to the end. .PP If you move the current directory or one above it, .C pwd cannot give the correct response. Use the .C cd command with a full path name to correct this situation. .PP The command .C readonly (without arguments) produces the same output as the command .CR export . .PP Failure (non-zero exit status) of a special command preceding a .C |\|| symbol prevents the .I list following .C |\|| from executing. .PP In an international environment, character ordering is determined by the setting of .SM LC_COLLATE, rather than by the binary ordering of character values in the machine collating sequence. This brings with it certain attendant dangers, particularly when using range expressions in file-name-generation patterns. For example, the command, .IP .C rm [a-z]* .PP might be expected to match all file names beginning with a lowercase alphabetic character. However, if dictionary ordering is specified by .SM LC_COLLATE, it also matches file names beginning with an uppercase character (as well as those beginning with accented letters). Conversely, it fails to match letters collated after .C z in languages such as Norwegian. .PP The correct (and safe) way to match specific character classes in an international environment is to use a pattern of the form: .IP .C rm [[:lower:]]* .PP This uses .SM LC_CTYPE to determine character classes and works predictably for all supported languages and codesets. For shell scripts produced on non-internationalized systems (or without consideration for the above dangers), it is recommended that they be executed in a non-\c .SM NLS environment. This requires that .SM LANG, LC_COLLATE, etc., be set to "C" or not set at all. .PP .C sh implements command substitution by creating a pipe between itself and the command. If the root file system is full, the substituted command cannot write to the pipe. As a result, the shell receives no input from the command, and the result of the substitution is null. In particular, using command substitution for variable assignment under such circumstances results in the variable being silently assigned a .SM NULL value. .PP The signal .SM SIGSEGV should not be blocked when executing .CR sh . .PP .C sh reserves file descriptor 59 for internal use. Reducing the number of available file descriptors below 60 causes .C sh to fail. .PP Each time a function is executed in a shell script, any arguments given to the function overwrite the values of the positional parameters for the entire script. If the values of the positional parameters must be preserved, they must be explicitly saved before each function call. .SH AUTHOR .C sh was developed by AT&T and HP. .SH FILES .C $HOME/.profile .br .C /dev/null .br .C /etc/profile .br .C /tmp/sh* .SH SEE ALSO cd(1), echo(1), env(1), login(1), newgrp(1), pwd(1), test(1), umask(1), acctcms(1M), acctcom(1M), dup(2), exec(2), fork(2), pipe(2), ulimit(2), umask(2), wait(2), a.out(4), profile(4), environ(5), lang(5), regexp(5), signal(5). .PP .I Bourne Shell tutorial in .I "Shells Users Guide" . .SH STANDARDS CONFORMANCE .CR . ": SVID2, SVID3, XPG2, XPG3" .PP .CR : ": SVID2, SVID3, XPG2, XPG3" .PP .CR break ": SVID2, SVID3, XPG2, XPG3" .PP .CR case ": SVID2, SVID3, XPG2, XPG3" .PP .CR continue ": SVID2, SVID3, XPG2, XPG3" .PP .CR eval ": SVID2, SVID3, XPG2, XPG3" .PP .CR exec ": SVID2, SVID3, XPG2, XPG3" .PP .CR exit ": SVID2, SVID3, XPG2, XPG3" .PP .CR export ": SVID2, SVID3, XPG2, XPG3" .PP .CR for ": SVID2, SVID3, XPG2, XPG3" .PP .CR if ": SVID2, SVID3, XPG2, XPG3" .PP .CR read ": SVID2, SVID3, XPG2, XPG3" .PP .CR return ": SVID2, SVID3, XPG2, XPG3" .PP .CR rsh ": SVID2, SVID3" .PP .CR set ": SVID2, SVID3, XPG2, XPG3" .PP .CR sh ": SVID2, SVID3, XPG2, XPG3" .PP .CR shift ": SVID2, SVID3, XPG2, XPG3" .PP .CR time ": SVID2, SVID3, XPG2, XPG3" .PP .CR trap ": SVID2, SVID3, XPG2, XPG3" .PP .CR unset ": SVID2, SVID3, XPG2, XPG3" .PP .CR until ": SVID2, SVID3, XPG2, XPG3" .PP .CR while ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4sh\f1 \- shell, the standard command programming language@@@\f3sh(1)\f1 .\" index@\f4rsh\f1 \- rshell, the restricted command programming language@@@\f3sh(1)\f1 .\" index@Bourne shell@@@\f3sh(1)\f1 .\" index@shell, Bourne@@@\f3sh(1)\f1 .\" index@\f4rsh\f1 \- restricted shell command programming language@@@\f3sh(1)\f1 .\" index@\f4break\f1 \- exit from enclosing for/next loop@@@\f3sh(1)\f1 .\" index@\f4cd\f1 \- change working directory@@@\f3sh(1)\f1 .\" index@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@\f3sh(1)\f1 .\" index@\f4echo\f1 \- echo (print) arguments@@@\f3sh(1)\f1 .\" index@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@\f3sh(1)\f1 .\" index@\f4exec\f1 \- execute command without creating new process@@@\f3sh(1)\f1 .\" index@\f4exit\f1 \- exit shell with exit status@@@\f3sh(1)\f1 .\" index@\f4export\f1 \- export variable names to environment of subsequent commands@@@\f3sh(1)\f1 .\" index@\f4hash\f1 \- remember command location in search path@@@\f3sh(1)\f1 .\" index@\f4newgrp\f1 \- equivalent to \f3exec newgrp\f1@@@\f3sh(1)\f1 .\" index@\f4pwd\f1 \- working directory name@@@\f3sh(1)\f1 .\" index@\f4read\f1 \- read line from standard input@@@\f3sh(1)\f1 .\" index@\f4readonly\f1 \- mark \f2name\f1 as read-only@@@\f3sh(1)\f1 .\" index@\f4return\f1 \- exit function with return value@@@\f3sh(1)\f1 .\" index@\f4set\f1 \- set/define options and arguments@@@\f3sh(1)\f1 .\" index@\f4shift\f1 \- shift positional parameters to next lower position@@@\f3sh(1)\f1 .\" index@\f4time\f1 \- print accumulated shell and children process times@@@\f3sh(1)\f1 .\" index@\f4times\f1 \- print accumulated user and system process times@@@\f3sh(1)\f1 .\" index@\f4trap\f1 \- execute command upon receipt of signal@@@\f3sh(1)\f1 .\" index@\f4type\f1 \- show interpretation of \f2name\f1 as if a command@@@\f3sh(1)\f1 .\" index@\f4ulimit\f1 \- impose file size limit for child processes@@@\f3sh(1)\f1 .\" index@\f4umask\f1 \- set permissions mask for creating new files@@@\f3sh(1)\f1 .\" index@\f4unset\f1 \- remove definition/setting of options and arguments@@@\f3sh(1)\f1 .\" index@\f4wait\f1 \- wait for process and report termination status@@@\f3sh(1)\f1 .\" .\" toc@\f3sh(1)\f1:\0\0\f4sh\f1, \f4rsh\f1@@@shell, the standard/restricted command programming language .\" toc@\f4rsh\f1 \- restricted shell command programming language@@@see \f3sh(1)\f1 .\" toc@\f4break\f1 \- exit from enclosing for/next loop@@@see \f3sh(1)\f1 .\" toc@\f4cd\f1 \- change working directory@@@see \f3sh(1)\f1 .\" toc@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@see \f3sh(1)\f1 .\" toc@\f4echo\f1 \- echo (print) arguments@@@see \f3sh(1)\f1 .\" toc@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@see \f3sh(1)\f1 .\" toc@\f4exec\f1 \- execute command without creating new process@@@see \f3sh(1)\f1 .\" toc@\f4exit\f1 \- exit shell with exit status@@@see \f3sh(1)\f1 .\" toc@\f4export\f1 \- export variable names to environment of subsequent commands@@@see \f3sh(1)\f1 .\" toc@\f4hash\f1 \- remember command location in search path@@@see \f3sh(1)\f1 .\" toc@\f4newgrp\f1 \- equivalent to \f3exec newgrp\f1@@@see \f3sh(1)\f1 .\" toc@\f4pwd\f1 \- working directory name@@@see \f3sh(1)\f1 .\" toc@\f4read\f1 \- read line from standard input@@@see \f3sh(1)\f1 .\" toc@\f4readonly\f1 \- mark \f2name\f1 as read-only@@@see \f3sh(1)\f1 .\" toc@\f4return\f1 \- exit function with return value@@@see \f3sh(1)\f1 .\" toc@\f4set\f1 \- set/define options and arguments@@@see \f3sh(1)\f1 .\" toc@\f4shift\f1 \- shift positional parameters to next lower position@@@see \f3sh(1)\f1 .\" toc@\f4time\f1 \- print accumulated shell and children process times@@@see \f3sh(1)\f1 .\" toc@\f4times\f1 \- print accumulated user and system process times@@@see \f3sh(1)\f1 .\" toc@\f4trap\f1 \- execute command upon receipt of signal@@@see \f3sh(1)\f1 .\" toc@\f4type\f1 \- show interpretation of \f2name\f1 as if a command@@@see \f3sh(1)\f1 .\" toc@\f4ulimit\f1 \- impose file size limit for child processes@@@see \f3sh(1)\f1 .\" toc@\f4umask\f1 \- set permissions mask for creating new files@@@see \f3sh(1)\f1 .\" toc@\f4unset\f1 \- remove definition/setting of options and arguments@@@see \f3sh(1)\f1 .\" toc@\f4wait\f1 \- wait for process and report termination status@@@see \f3sh(1)\f1 .\" .\" links@sh-bourne.1 rsh-bourne.1 .\" .\" fileset_database@sh-bourne.1 USER-CMDS-MAN .\" $Header: rtprio.1,v 72.4 93/01/14 11:38:35 ssa Exp $ .TA r .TH rtprio 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtprio \- execute process with real-time priority .SH SYNOPSIS .C rtprio .I priority command .RI [ \|arguments\| ] .br .C rtprio .I priority .CI - pid .br .C rtprio -t .I command .RI [ \|arguments\| ] .br .C rtprio -t .CI - pid .SH DESCRIPTION .C rtprio executes .I command with a real-time priority, or changes the real-time priority of currently executing process .IR pid . Real-time priorities range from zero (highest) to 127 (lowest). Real-time processes are not subject to priority degradation, and are all of greater (scheduling) importance than non-real-time processes. See .IR rtprio (2) for more details. .PP If .C -t is specified instead of a real-time .IR priority , .C rtprio executes .I command with a timeshare (non-real-time) priority, or changes the currently executing process .I pid from a possibly real-time priority to a timeshare priority. The former is useful to spawn a timeshare priority command from a real-time priority shell. .PP If .C -t is not specified, .I command is not scheduled, or .IR pid 's real-time priority is not changed, if the user is not a member of a group having .C PRIV_RTPRIO access and is not the user with appropriate privileges. When changing the real-time priority of a currently executing process, the effective user .SM ID of the calling process must be the user with appropriate privileges, or the real or effective user .SM ID must match the real or saved user .SM ID of the process to be modified. .SH RETURN VALUE .C rtprio returns exit status 0 if .I command is successfully scheduled or if .IR pid 's real-time priority is successfully changed, 1 if .I command is not executable or .I pid does not exist, and 2 if .I command .RI ( pid ) lacks real-time capability, or the invoker's effective user .SM ID is not a user who has appropriate privileges, or the real or effective user or the real or effective user .SM ID does not match the real or saved user .SM ID of the process being changed. .SH EXAMPLES Execute file .C a.out at a real-time priority of 100: .IP .C rtprio 100 a.out .PP Set the currently running process pid 24217 to a real-time priority of 40: .IP .C rtprio 40 -24217 .SH AUTHOR .C rtprio was developed by HP. .SH SEE ALSO setprivgrp(1M), getprivgrp(2), rtprio(2). .\" .\" index@\f4rtprio\f1 \- execute process with real-time priority@@@\f3rtprio(1)\f1 .\" index@execute process with real-time priority@@@\f3rtprio(1)\f1 .\" index@process, execute, with real-time priority@@@\f3rtprio(1)\f1 .\" index@real-time priority, execute process with@@@\f3rtprio(1)\f1 .\" index@priority, real-time, execute process with@@@\f3rtprio(1)\f1 .\" .\" toc@\f3rtprio(1)\f1:\0\0\f4rtprio\f1@@@execute process with real-time priority .\" .\" fileset_database@rtprio.1 USER-CMDS-MAN .\" $Header: rtsched.1,v 72.2 94/09/21 09:34:52 ssa Exp $ .TA r .TH rtsched 1 "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtsched \- execute process with real-time priority .SH SYNOPSIS .C rtsched -s .I scheduler .C -p .I priority command .RI [ \|arguments\| ] .br .C "rtsched [ -s" .I scheduler .C "] -p" .I priority .C "-P" .CI pid .br .SH DESCRIPTION .C Rtsched executes .I command with POSIX or HP-UX real-time priority, or changes the real-time priority of currently executing process .IR pid . .PP All POSIX real-time priority processes are of greater scheduling importance than processes with HP-UX real-time or HP-UX timeshare priority. All HP-UX real-time priority processes are of greater scheduling importance than HP-UX timeshare priority processes, but are of lesser importance than POSIX real-time processes. Neither POSIX nor HP-UX real-time processes are subject to degradation. POSIX real-time processes may be scheduled with one of three different POSIX real-time schedulers: SCHED_FIFO, SCHED_RR, or SCHED_RR2. See .IR rtsched (2) for details. .PP .C Rtsched is a superset of .C rtprio. See .IR rtprio (1). .SS Options .TP 15 .CR "-s scheduler" Specify the desired scheduler: .TS center, tab(|); l l. POSIX real-time schedulers:|SCHED_FIFO |SCHED_RR |SCHED_RR2 .sp HP-UX real-time scheduler:|SCHED_RTPRIO .sp HP-UX timeshare scheduler:|SCHED_HPUX .TE .TP 15 .CI -p "\0priority" Specify priority range; any integer within the inclusive priority range of the corresponding scheduler. .CI -p "\0priority" is required for all schedulers except SCHED_HPUX. If scheduler is SCHED_HPUX, the .I priority argument is ignored. The default .I priority range of each scheduler is as follows: .sp .RS .TS center, tab(|); l r r. scheduler|highest priority|lowest priority _ SCHED_FIFO|31|0 SCHED_RR|31|0 SCHED_RR2|31|0 SCHED_RTPRIO|0|127 SCHED_HPUX|N/A|N/A .TE .RE .IP .BR Note : Higher numerical values for the .I priority represent higher priorities under POSIX real-time schedulers, whereas lower numerical values for the .I priority represent higher priorities under HP-UX real-time scheduler. .TP 15 .CR -P Specify an already executing process ID .RI ( pid ). .PP .I Command is not scheduled, or .IR pid 's real-time priority is not changed, if the user is not a member of a group having .C PRIV_RTSCHED access and is not the user with appropriate privileges. When changing the real-time priority of a currently executing process, the effective user .SM ID of the calling process must be the user with appropriate privileges, or the real or effective user .SM ID must match the real or saved user .SM ID of the process to be modified. .SH RETURN VALUE .C rtsched returns exit status: .RS .TP 8 .B 0 if .I command is successfully scheduled or if .IR pid 's real-time priority is successfully changed; .TP .B 1 if .I command is not executable, .I pid does not exist, or .I priority is not within the priority range for the corresponding scheduler; .TP .B 2 if .I command .RI ( pid ) lacks real-time capability, or the invoker's effective user .SM ID is not a user who has appropriate privileges, or the real or effective user or the real or effective user .SM ID does not match the real or saved user .SM ID of the process being changed; or .TP .B 5 if rtsched encountered an internal error or if rtsched is not supported by this release. .SH EXAMPLES .PP Execute file .C a.out with SCHED_FIFO at a priority of 10: .IP .C rtsched -s SCHED_FIFO -p 10 a.out .sp .PP Execute file .C a.out with SCHED_RTPRIO at a priority of 127 (this is synonymous to .CR "rtprio 127 a.out" ): .IP .C rtsched -s SCHED_RTPRIO -p 127 a.out .sp .PP Execute file .C a.out with the SCHED_HPUX scheduler: .IP .C rtsched -s SCHED_HPUX a.out .PP This is useful to spawn a timeshare priority command from a real-time priority shell. .sp .PP Set the currently running process pid 24217 to execute with SCHED_RR2 at a priority of 20: .IP .C "rtsched -s SCHED_RR2 -p 20 -P 24217" .sp .PP Now change its priority to 10 using the same scheduler: .IP .C rtsched -p 10 -P 24217 .SH WARNINGS .I Priority values used by .C rtsched may differ from those used by other commands. For example, .IR ps (1) displays the internal representation of priority values. .SH AUTHOR .C rtsched was developed by HP. .SH SEE ALSO rtprio(1), setprivgrp(1M), getprivgrp(2), rtprio(2), rtsched(2). .\" .\" index@\f4rtsched\f1 \- execute process with POSIX real-time priority@@@\f3rtsched(1)\f1 .\" index@execute process with POSIX real-time priority@@@\f3rtsched(1)\f1 .\" index@process, execute, with POSIX real-time priority@@@\f3rtsched(1)\f1 .\" index@POSIX real-time priority, execute process with@@@\f3rtsched(1)\f1 .\" index@priority, POSIX real-time, execute process with@@@\f3rtsched(1)\f1 .\" .\" toc@\f3rtsched(1)\f1:\0\0\f4rtsched\f1@@@execute process with POSIX real-time priority .\" $Header: rup.1,v 72.4 94/08/31 10:39:56 ssa Exp $ .TA r .TH rup 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rup \- show host status of local machines (RPC version) .SH SYNOPSIS .C rup .RC [ -h ] .RC [ -l ] .RC [ -t ] .RI [ host \0...] .SH DESCRIPTION .CR rup gives a status similar to .CR uptime for remote machines. It broadcasts on the local network and displays the responses it receives. Though the listing is normally in the order responses are received, the order can be changed by using command-line options. The broadcast process takes about two minutes. .PP When .I host arguments are given, instead of broadcasting, .CR rup only queries the list of specified hosts. .PP A remote host only responds if it is running the .CR rstatd daemon (see .IR rstatd (1M)). .SS Options .CR rup recognizes the following command-line options: .RS .TP 8 .CR -h Sort the display alphabetically by host name. .TP .CR -l Sort the display by load average. .TP .CR -t Sort the display by up time. .RE .SH WARNINGS Broadcasting does not work through gateways; therefore, .CR rup does not report information about machines that are reachable only through gateways. .SH DIAGNOSTICS The exit code of .CR rup is the number of errors (eg. bad host names) encountered; zero for success. .SH AUTHOR .CR rup was developed by Sun Microsystems, Inc. .SH FILES .CR /etc/inetd.conf .SH SEE ALSO ruptime(1), inetd(1M), rstatd(1M), services(4). .\" .\" index@\f4rup\f1: show host status of local machines (\s-1RPC\s+1 version)@@@\f3rup(1)\f1 .\" index@host status of local machines (\s-1RPC\s+1 version), show@@@\f3rup(1)\f1 .\" index@status, host, of local machines (\s-1RPC\s+1 version), show@@@\f3rup(1)\f1 .\" index@local machines (\s-1RPC\s+1 version), show host status of@@@\f3rup(1)\f1 .\" index@machines (\s-1RPC\s+1 version), show host status of local@@@\f3rup(1)\f1 .\" .\" toc@\f3rup(1)\f1: \f4rup\f1@@@show host status of local machines (RPC version) .\" $Header: ruptime.1,v 72.5 94/12/09 15:06:50 ssa Exp $ .TA r .TH ruptime 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ruptime \- show status of local machines .SH SYNOPSIS .C ruptime .RC [ -a ] .RC [ -r ] .RC [ -l ] .RC [ -t ] .RC [ -u ] .SH DESCRIPTION .CR ruptime outputs a status line for each machine on the local network that is running the .CR rwho daemon. .CR ruptime 's status lines are formed from packets broadcast once every 3 minutes between .CR rwho daemons (see .IR rwhod (1M)) on each host on the network. Each status line has a field for the name of the machine, the status of the machine (up or down), how long the machine has been up or down, the number of users logged into the machine, and the 1-, 5- and 15-minute load averages for the machine when the packet was sent. .PP The status of the machine is reported as ``up'' unless no report has been received from the machine for 11 minutes or more. .PP The length of time that the machine has been up is shown as: .IP .IC days + hours : minutes .PP Load averages are the average number of jobs in the run queue over the last 1-, 5- and 15-minute intervals when the packet was sent. .PP An example status line output by .CR ruptime might be: .IP .C "machine1 up 1+5:15, 7 users, load 1.47, 1.16, 0.80" .PP The above status line would be interpreted as follows: .PP .CR machine1 is presently ``up'' and has been up for 1 day, 5 hours and 15 minutes. It currently has 7 users logged in. Over the last 1-minute interval, an average of 1.47 jobs were in the run queue. Over the last 5-minute interval, an average of 1.16 jobs were in the run queue. Over the last 15-minute interval, an average of 0.80 jobs were in the run queue. .PP If a user has not used the system for an hour or more, the user is considered idle. Idle users are not shown unless the .CR -a option is specified. .SS Options If no options are specified, the listing is sorted by host name. Options change sorting order as follows: .RS .TP 8 .C -l Sort by load average. .TP .C -t Sort by up time. .TP .C -u Sort by the number of users. .TP .C -r Reverse the sort order. .RE .SH DIAGNOSTICS .TP 5 .C "no hosts!?!" No status report files in .CR /var/spool/rwho . .IR "Next Step" : Ask the system administrator to check whether the .CR rwho daemon is running. .SH AUTHOR .CR ruptime was developed by the University of California, Berkeley. .SH FILES .TP 35 .C /var/spool/rwho/whod.* Data files .SH SEE ALSO rwho(1), rwhod(1M). .\" .\" toc@\f3ruptime(1)\f1:\0\0\f4ruptime\f1@@@show status of local machines .\" .\" index@\f4ruptime\f1 \- show status of local machines@@@\f3ruptime(1)\f1 .\" index@\f1status of local machines, show@@@\f3ruptime(1)\f1 .\" index@\f1local machines, show status of@@@\f3ruptime(1)\f1 .\" index@\f1machines, show status of local@@@\f3ruptime(1)\f1 .\" .\" fileset_database@ruptime.1 INETSVCS-MAN .\" $Header: rusers.1,v 72.4 94/08/31 10:40:32 ssa Exp $ .TA r .TH rusers 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rusers \- determine who is logged in on machines on local network .SH SYNOPSIS .C rusers .RC [ -a ] .RC [ -h ] .RC [ -i ] .RC [ -l ] .RC [ -u ] .RI [ host \0...] .SH DESCRIPTION .CR rusers produces output similar to the "quick" option of .IR who (1), but for remote machines. It broadcasts on the local network and prints the responses it receives. Though the listing is normally in the order that responses are received, the order can be changed by specifying a command-line option. The broadcast process takes about two minutes. .PP When .I host arguments are given, instead of broadcasting, .CR rusers only queries the list of specified hosts. .PP For each machine, the default is to print a line listing the host name and all users on that host. When the .CR -l option is given, .CR rusers uses an output format similar to .IR rwho (1). If a user has not typed on the system for a minute or more, the idle time is reported. .PP A remote host only responds if it is running the .IR rusersd (1M) daemon. .SS Options .CR rusers recognizes the following command-line options: .RS .TP 8 .CR -a Give a report for a machine even if no users are logged in on it. .TP .CR -h Sort alphabetically by host name. .TP .CR -i Sort by idle time. .TP .CR -l Give a longer listing in the style of .CR who -R (see .IR who (1)). .TP .CR -u Sort by number of users. .RE .SH RETURN VALUE .CR rusers returns exit code zero if no errors are encountered; otherwise it returns the number of errors found. .SH AUTHOR .CR rusers was developed by Sun Microsystems, Inc. .SH WARNINGS Broadcasting does not work through gateways; therefore, .CR rusers does not report information about machines that are reached only through gateways. .SH FILES .CR /etc/inetd.conf .SH SEE ALSO rwho(1), who(1), inetd(1M), rusersd(1M). .\" .\" index@\f4rusers\f1: determine who is logged in on local network machines@@@\f3rusers(1)\f1 .\" index@determine who is logged in on local network machines@@@\f3rusers(1)\f1 .\" index@who is logged in on local network machines, determine@@@\f3rusers(1)\f1 .\" index@logged in on local network machines, determine who is@@@\f3rusers(1)\f1 .\" index@local network machines, determine who is logged in on@@@\f3rusers(1)\f1 .\" index@machines, determine who is logged in on local network@@@\f3rusers(1)\f1 .\" .\" toc@\f3rusers(1)\f1: \f4rusers\f1@@@determine who is logged onto machines on the local network .\" $Header: rwho.1,v 72.4 94/07/05 11:04:11 ssa Exp $ .TA r .TH rwho 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rwho \- show who is logged in on local machines .SH SYNOPSIS .C rwho .RC [ -a ] .SH DESCRIPTION .C rwho produces output similar to the output of the .SM HP-UX .C who command for all machines on the local network that are running the .C rwho daemon (see .IR who (1) and .IR rwhod (1M)). If .C rwhod has not received a report from a machine for 11 minutes, .C rwho assumes the machine is down and .C rwho does not report users last known to be logged into that machine. .PP .CR rwho 's output line has fields for the name of the user, the name of the machine, the user's terminal line, the time the user logged in, and the amount of time the user has been idle. Idle time is shown as: .IP .IC hours : minutes .PP If a user has not typed to the system for a minute or more, .C rwho reports this as idle time. If a user has not typed to the system for an hour or more, the user is omitted from .CR rwho 's output unless the .C -a flag is given. .PP An example output line from .C rwho would look similar to: .IP .C "joe_user machine1:tty0p1 Sep 12 13:28 :11" .PP This output line could be interpreted as .C joe_user is logged into .C machine1 and his terminal line is .CR tty0p1 . .C joe_user has been logged on since September 12 at 13:28 (1:28 p.m.). .C joe_user has not typed anything into .C machine1 for 11 minutes. .SH WARNINGS .CR rwho 's output becomes unwieldy when the number of users for each machine on the local network running .C rwhod becomes large. One line of output occurs for each user on each machine on the local network that is running .CR rwhod . .SH AUTHOR .C rwho was developed by the University of California, Berkeley. .SH FILES .TP 33 .C /var/spool/rwho/whod.* Information about other machines. .RE .SH SEE ALSO ruptime(1), rusers(1), rwhod(1M). .\" .\" index@\f4rwho\f1 \- show who is logged in on local machines@@@\f3rwho(1)\f1 .\" index@show who is logged in on local machines@@@\f3rwho(1)\f1 .\" index@who is logged in on local machines, show@@@\f3rwho(1)\f1 .\" index@logged in on local machines, show who is@@@\f3rwho(1)\f1 .\" index@local machines, show who is logged in on@@@\f3rwho(1)\f1 .\" index@machines, show who is logged in on local@@@\f3rwho(1)\f1 .\" .\" toc@\f3rwho(1)\f1:\0\0\f4rwho\f1@@@show who is logged in on local machines .\" .\" fileset_database@rwho.1 INETSVCS-MAN .\" $Header: sact.1,v 76.1 95/08/04 16:44:27 ssa Exp $ .TA s .TH sact 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sact \- print current SCCS file editing activity .SH SYNOPSIS .C sact .IR file \0... .SH DESCRIPTION The .C sact command informs the user of any impending deltas to a named .SM SCCS file. This situation occurs when .C get -e has been previously executed without a subsequent execution of .C delta (see .IR delta (1) and .IR get (1)). If a directory is named on the command line, .C sact behaves as though each file in the directory were specified as a named file, except that non-\c .SM SCCS files (last component of path name does not begin with .CR s. ) and unreadable files are silently ignored. If a name of .C - is given, the standard input is read with each line being taken as the name of an .SM SCCS file to be processed. .PP The output for each named file consists of five fields separated by spaces. .RS .TP 12 Field 1 .SM SID of a delta that currently exists in the .SM SCCS file to which changes will be made to make the new delta. .TP 12 Field 2 .SM SID for the new delta to be created. .TP 12 Field 3 Logname of the user making the delta (i.e., executed a .C get for editing). .TP 12 Field 4 Date when .C get -e was executed. .TP 12 Field 5 Time when .C get -e was executed. .RE .SH DIAGNOSTICS Use .IR sccshelp (1) for explanations. .SH SEE ALSO delta(1), get(1), sccshelp(1), unget(1). .SH STANDARDS CONFORMANCE .CR sact ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" toc@\f3sact(1)\f1:\0\0\f4sact\f1@@@print current \s-1SCCS\s+1 file editing activity .\" .\" index@\f4sact\f1 \- print current \s-1SCCS\s+1 file editing activity@@@\f3sact(1)\f1 .\" index@\s-1SCCS\s+1: print current \s-1SCCS\s+1 file editing activity@@@\f3sact(1)\f1 .\" index@\f1print current \s-1SCCS\s+1 file editing activity@@@\f3sact(1)\f1 .\" index@\f1current \s-1SCCS\s+1 file editing activity, print@@@\f3sact(1)\f1 .\" index@\f1file editing activity, print current \s-1SCCS\s+1@@@\f3sact(1)\f1 .\" index@\f1editing activity, print current \s-1SCCS\s+1 file@@@\f3sact(1)\f1 .\" index@\f1activity, print current \s-1SCCS\s+1 file editing@@@\f3sact(1)\f1 .\" .\" $Header: samlog_view.1,v 72.2 94/08/12 11:22:43 ssa Exp $ .TA s .TH samlog_viewer 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME samlog_viewer \- a tool for viewing and saving the SAM logfile .SH SYNOPSIS .C /usr/sam/bin/samlog_viewer .RC [ -s .IR MMDDhhmm [ YY ]\|] .RC [ -e .IR MMDDhhmm [ YY ]\|] .ifn .br .ifn \0\0\0\0 .RC [ -l .CR SDVC ] .ift .br .ift \0\0\0\0 .RC [ -u .IR user ] .RC [ -o .IR ofile ] .RC [ -t ] .RC [ -n ] .RI [ file ] .SH DESCRIPTION The .CR samlog_viewer command enables the viewing of part or all of the SAM logfile (or another file containing data in the same format) at varying levels of detail. This tool is run by SAM whenever the .CR "View SAM Log" option is chosen. It can also be run independently of SAM, in either interactive or noninteractive mode. .PP The .CR samlog_viewer command executes in either interactive or noninteractive mode, depending on the options given. In noninteractive mode, .CR samlog_viewer filters the source file and writes the resulting data either to stdout or to a destination file. In interactive mode, .CR samlog_viewer displays a graphical user interface enabling you to try different combinations of filtering, save one or more versions of the source file to other files, scroll back and forth among the logfile entries, etc. .PP Under no circumstances is .CR samlog_viewer destructive to the contents of the SAM logfile (or whatever source file is specified by .IR file ). The contents of the source file are filtered and displayed (or output) according to the settings of the available filters. Multiple instances of .CR samlog_viewer can be run simultaneously without harmful effects. .SS Filters .CR samlog_viewer supports three types of filters: level of detail, date/time, and user filters. These filters can be used in combination to provide highly selective logfile viewing. .PP The level of detail filters control how much detail is displayed. The SAM logfile may contain entries of many different types. The entry types currently supported are: summary, detail, verbose, error, and note. The level of detail filters display some or all of these entry types, depending on which filter is chosen. The level of detail filters are: .RS .TP 20 .C Summary Displays only the higher level messages. These include .IR summary , .IR error , and .IR note (warnings, other entries worthy of special attention) entry types. .TP .C Detail Includes .CR Summary level of detail, and adds .IR detail log entries. If no level of detail is specified, this is the default. .TP .C Verbose Includes .CR Detail level of detail, and adds .IR verbose log entries. .TP .C Commands Only Displays only the literal commands that were executed. These commands may include HP-UX commands as well as SAM commands and scripts. .RE .PP The date/time filters are used to ask for entries written since a specific date/time, before a specific date/time, or both. .PP The user filters are for viewing only those entries written by a particular user. If invoked with the .CR -u option, its argument is used as the user whose entries should be shown. If .CR -u is not specified, then the value of the environment variable .CR SAM_RESTRICTED_USER is used as the name of the user. If neither .CR -u or .CR SAM_RESTRICTED_USER is present, then no user filtering is done and entries from all users are shown. If both .CR -u and .CR SAM_RESTRICTED_USER are in effect, the .CR -u option overrides the setting of the environment variable. .PP If user filtering is selected, either by the .CR SAM_RESTRICTED_USER environment variable or by the .CR -u option, .CR samlog_viewer displays only entries made by that user and disallows any changes to the user filtering. This is useful for allowing nonprivileged users to run .CR samlog_viewer and see only those entries that pertain to them. Otherwise, .CR samlog_viewer allows the user filtering to be changed, or completely disabled, from its interactive filtering screen. .SS Options The following options enable you to set up filtering and other attributes. If .CR samlog_viewer runs interactively, these attributes may also be set and modified in the various supported menus and displays. The available options are: .RS .TP 25 .CI -s " MMDDhhmm" \f1[\f2YY\f1] The .CR -s option sets the start date/time filter to the date/time given by its argument. The date/time is specified in the same way as it is for the .CR date command (see .IR date (1)): .RS .RS .TP 7 .I MM Month specified as a two digit number (e.g., .CR 08 ). .TP .IR DD Day specified as a two digit number. .TP .IR hh Hour specified as a two digit number (24-hour clock form). .TP .IR mm Minute specified as a two digit number. .TP .IR YY The last two digits of the desired year. If this is not specified, the current year is used. .RE .PP If no start time is given, the beginning of the log is used as the start time. .RE .TP 20 .CI -e " MMDDhhmm" \f1[\f2YY\f1] The .CR -e option sets the end date/time filter to the date/time given by its argument. The date and time is specified as described above for the .CR -s option. If no end time is given, then an end date/time of infinity (no end time) is used. .TP .C -l SDVC The .CR -l option sets the desired level of detail. One of the letters .CR SDVC must be specified as the required argument. The level of detail is set as follows: .RS .nf .IP .CR S " = " Summary .CR D " = " Detail .CR V " = " Verbose" .CR C " = " "Commands Only" .fi .PP If the .CR -l option is not specified, the .CR Detail level of detail is used by default. .RE .TP .CI -u " user" The .CR -u option sets the user filter to the user name or user ID specified by .IR user . Only entries logged by this user are displayed. If the .CR -u option is omitted, entries logged by all users are displayed by default. .TP .CI -o " ofile" The .CR -o option causes the filtered output to be written to the output file .IR ofile . The .CR -o option implies the .CR -n option described below. If .IR ofile is .CR - , the output is written to stdout. If .CR -o is omitted, the output is written to either stdout (if .CR -n is specified) or to the interactive .CR samlog_viewer display (if .CR -n is omitted). .TP .C -t The .CR -t option enables automatic timestamping. If specified, each log entry is tagged with the time of day at which it was written. Timestamping is disabled by default. .TP .C -n The .CR -n option forces noninteractive behavior. If specified, .CR samlog_viewer runs noninteractively, using the default or specified values for all supported options and source/destination files. .TP .IR file Specifies the name of the file from which log data is read. The format of the data in the specified file must be the same as that used for raw SAM logfile data. If omitted, the SAM logfile is read. If .IR file is .CR - , stdin is read and .CR samlog_viewer runs noninteractively. If given, .IR file must be the last argument specified on the command line. .RE .SH EXAMPLES Capture the current contents of the SAM logfile using default filtering, and put into the file .CR "sam.out" : .IP .C samlog_viewer -n >sam.out .PP The following example does the same thing: .IP .C samlog_viewer -o sam.out .PP View only the commands executed by SAM on behalf of user .CR tom , between 8am June 5, 1994 and 10pm August 14, 1994, and view the data interactively: .IP .C samlog_viewer -s 0605080094 -e 0814220094 -lC -u tom .PP Noninteractively read data from stdin, timestamp it, and save the result in a file called .CR stdin.out : .IP .C cat datafile | samlog_viewer -t -o stdin.out - .PP Do the same as above, but instead have the data appear on stdout: .IP .C cat datafile | samlog_viewer -t -o - - .PP or .IP .C cat datafile | samlog_viewer -tn - .ifn .bp .SH FILES .TP 30 .C /var/sam/log/samlog SAM logfile. .PD 0 .TP .C /var/sam/log/samlog.old Archived version of .CR samlog , created when the logfile is automatically trimmed by SAM when its size becomes too large. Its contents are included in the log entries read by .CR samlog_viewer . .TP .C /tmp/LFV_ Temporary files used by .CR samlog_viewer . .TP .PD .C /tmp/LFV_RUN .PD .\" toc@\f3samlog_viewer(1)\f1:\0\0\f4samlog_viewer\f1@@@tool for viewing and saving the SAM logfile\f1 .\" .\" index@\f4samlog_viewer\f1 \- tool for viewing and saving the SAM logfile@@@\f3samlog_viewer(1)\f1 .\" index@\f1SAM logfile, tool for viewing and saving@@@\f3samlog_viewer\f1 .\" index@\f1viewing, saving SAM logfile tool@@@\f3samlog_viewer\f1 .\" index@\f1saving, viewing SAM logfile tool@@@\f3samlog_viewer\f1 .\" index@\f1logfile, viewing and saving SAM@@@\f3samlog_viewer\f1 ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" .rm zA .rm zZ .TH sams 1 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "enh,8441,R1.1,new ref page" .iX "commands" "\*Lsams\*O" .iX "\*Lsams\*O command" .iX "messages" "system files" "\*Lsams\*O command" .iX "files" "\*Lsams\*O" .SH NAME .PP \*Lsams\*O \- Builds DCE message system files .iX "\*Lsams\*O command" "synopsis" .SH SYNOPSIS .PP .iX "directories" "\*Lsams\*O command" .sS \*Lsams\*O \*O[\*L\-d \*Vdest_dir\*O] \*O[\*L\-f\*O] \*O[\*L\-I \*Vinterface\*O] \*O[\*L\-m\*O] \*O[\*L\-n \*Voutput_name\*O] .br \*O[\*L\-o \*Voutput_files\*O] \*O[\*L\-s \*Vsort_style\*O] \*O[\*L\-t \*Vtable\*O] \*O[\*L\-x\*O] \*Vfile\*O .sE .SH ARGUMENTS .VL 8m .LI "\*L\-d \*Vdest_dir\*O" Specifies the directory in which files are to be created. The default is the current directory. .LI "\*L-f\*O" Turns off text-field filtering for the \*L\*O construct (described below). .LI "\*L-I \*Vinterface\*O" Names the IDL \*Linterface\*O that is to contain \*Lconst\*O declarations for all message numbers. .LI "\*L-m\*O" Generates one documentation file for each message. Each filename is named by the symbolic message code. .LI "\*L-n \*Voutput_name\*O" Specifies the base name of the output files. See below. .LI "\*L-o \*Voutput_list\*O" Specifies which files to generate. See below. The default is to generate all files. .LI "\*L-s \*Vsort_style\*O" Specifies the order in which documentation entries are to be generated. The order is indicated by one of the following letters: .VL 5m .LI "\*La\*O" Alphabetic by message name. .LI "\*Ln\*O" Numeric by message number. .LI "\*Lt\*O" Alphabetic by message text. .LE .LI "\*L-t \*Vtable\*O" Generates an in-core message table that includes only those messages that are in the specified \*Vtable\*O. The default is to include all messages. .LI "\*L-x\*O" Checks each message string that contains more than one \*Lprintf\*O-style argument specification to make sure that it follows the XPG4 convention of \*L%\*Vd\*L$\*O, where \*Vd\*O is a digit. Note that message text should normally not have to use the XPG4 conventions because \*Lsams\*O will automatically insert them when generating the catalog. .LE .PP .SH DESCRIPTION .PP The \*Lsams\*O utility reads the specified input file and creates a number of output files. The name \*Lsams\*O stands for .iX "symbols" "\*Lsams\*O command" .iX "messages" "strings" "\*Lsams\*O command" .iX "files" "input" "\*Lsams\*O command" .iX "files" "output" "\*Lsams\*O command" ``symbols and message strings'', which is what the program manipulates. The input file consists of keywords, numbers, and text. Whitespace, except in quoted strings, is used only to separate tokens. If the text is a simple word, it can be entered unquoted. Text that is a keyword or that spans multiple lines must be enclosed within quotes. Within such quoted text, leading and trailing newlines are ignored, and the usual C escapes (for example, \*L\et\*O for a tab) are accepted. In addition, spaces and tabs after a newline are ignored. If you need leading whitespace, use the two-character sequence \*L\en\*O followed by the spaces. .PP An unquoted \*L#\*O (number sign) introduces a comment. Everything from the \*L#\*O to the end of the line is ignored. .SS "Generated Output" .PP A DCE message identifier is a 32-bit number that is divided into three parts: a technology, a component, and the message code. The technology and component fields are assigned by OSF; the message code is assigned by \*Lsams\*O or specified in the input file. .PP The technology and component determine the name of all files generated by \*Lsams\*O, including the message catalog. The \*Ldce_msg\*O routines know how to parse a message identifier and reconstruct the message catalog name and retrieve the desired text by using the code field. .PP For DCE and DFS source code, the technology will be ``dce'' or ``dfs'' and the component will be a three-letter name. For application code, the technology is part of the component, which is a number specified by OSF, but the word ``dce'' is always used. .PP .iX "files" "output" The \*Lsams\*O utility creates a number of output files, as specified by the \*L\-o\*O flag. This flag takes a set of letters, picked from the following table. The \*Lcomponent\*O (and \*Ltechnology\*O) headers determine part of the file names. This can be overridden by using the \*L-n\*O flag to specify the base name. Note that this does not replace the name under which the message catalog must be installed. .iX "files" "message" .iX "files" "header" .iX "files" "catalog" .iX "files" "manpage" .iX "files" "problem determination" .iX "files" "serviceability table" .iX "files" "header file" "serviceability" For example, given \*Ldce\*O as the technology and \*LXXX\*O as the component name, the following files would be created: .iS .ta \w'Letter 'u +\w'dceXXXmsg.sml 'u Letter File Description c dceXXX.cat \*OCatalog created by gencat; the message file is assumed to have already been generated \*Ld dceXXXmsg.man \*OSubset of a Unix-style manpage \*Lh dceXXXmsg.h \*OHeader file mapping codes to message numbers \*Li interface.idl \*OIDL file defining message identifier constants \*Lm dceXXX.msg \*OMessage file for gencat program \*Lp dceXXXmsg.sml \*OProblem determination guide \*Ls dceXXXsvc.c \*OServiceability table \*LS dceXXXsvc.h \*OServiceability header file \*Lt dceXXXmsg.c \*OTable mapping message numbers to short text; this is the in-core table of default message texts \*Lu dceXXXmac.h \*OServiceability-use convenience macros \*Lx dceXXX.idx \*OIndex file for building a problem determination book .iE .SS "Input format" .PP The input file is divided into three parts; the second part is optional. .PP The first part of the input file specifies a set of headers in the following format: .iX "headers" .sS \*Vheader value\*O .sE They must be chosen from the following set: .VL .LI "\*Lcollection size \*Vvalue\*O" The number of messages in each collection (see below). The default value is 100. .LI "\*Lcomponent \*Vcomp\*O" The name of the component for which the messages are being generated for the DCE or DFS technology provided by OSF. Component names must be three characters long. .LI "\*Lcomponent code \*Vvalue\*O" The numeric value of the component, for application code. .LI "\*Ldefault \*Vflags\*O" The default flags that should be assigned to all messages that do not specify their own flags. The flags should be chosen from the following set: .VL .LI "\*Lincatalog\*O" Put the message in the message catalog .LI "\*Lintable\*O" Put the message in the in-core text table .LI "\*Llongtext\*O" Message text is long, usually meaning it will not be returned as a status code, but instead used only as a message to be displayed to the user .LI "\*Lundocumented\*O" Do not put this message in any generated documentation files (that is, man pages or Problem Determination Guide) .LI "\*Lobsolete\*O" Reserve a number for this message but do not output any reference to it .LI "\*Lreserved\*O" Same action as \*Lobsolete\*O .LE .PP Each flag may be preceeded by the word \*Lnot\*O or a \*L!\*O (exclamation point) to reverse its meaning. This header is optional; the default value is \*Lintable incatalog not\ undocumented not\ obsolete\*O. .LI "\*Ltechnology \*Vtech\*O" The name of the technology provided by OSF for which the messages are being generated. This header may be omitted; the default value is \*Ldce\*O. Technology names must be three characters long. .LI "\*Lvalue \*Vstart\*O" The low-order bits of the status code to be assigned to messages. This header may be omitted; the default value is 1. .LI "\*Ltable \*Vvarname\*O" The name of the in-core message table that is created. This header may be omitted; the default value is \*VXXX\*L_msg_table\*O where \*VXXX\*O is the component name or just \*Lmsg_table\*O for application code. .LE .PP .iX "header file" .iX "files" "header" A typical header might look like this: .iS .ta \w'component 'u technology dce component dts table dts_msg_table .iE .PP The optional second part of the input file is used to specify the DCE serviceability table and handle. It should appear in the following format: .iX "serviceability table" "\*Lsams\*O command" .sS \*Lserviceability table \*Vname \*Lhandle \*Vhandle_name .nL \*Lstart\*O \*Vsubcomponent_list\*O .nL \*Lend\*O .sE The \*Ltable\*O specifies the name of the subcomponent table, as described in the \*Lservice.idl\*O interface. The \*Lhandle\*O field specifies the name of the serviceability handle to be used with this component. (For more information, see \*Ldce_svc_register(3)\*O.) .PP The \*Vsubcomponent_list\*O argument is a series of lines in the following format: .sS \*Lsub-component \*Vtable_index subcomp full_descr_id\*O .sE .iX "\*L#define\*O" Where \*Vtable_index\*O is the name of a \*L#define\*O (put in the serviceability header file) that will be used as the subscript into the table. The \*Vsubcomp\*O part is a single word (in quotes, if needed, so that it will not be mistaken for a \*Lsams\*O keyword) that names the subcomponent and is used to ``group'' related messages. The \*Vfull_descr_id\*O is the \*Lcode\*O for the message that contains the full description of the subcomponent. For example: .oS serviceability table dst_svc_table handle dts_svc_handle start sub-component dts_s_general "general" dts_i_svc_general sub-component dts_s_provider "provider" dts_i_svc_provider end .oE This indicates that there are two subcomponents. .PP Note that each sub-component must have an entry somewhere in the third part of the file that is a standard message code that contains the full text describing the sub-component. For example: .oS .ta \w'sub-component 'u ## Messages for serviceability table start !intable undocumented code dts_i_svc_general text "General administrative actions" end start !intable undocumented code dts_i_svc_provider text "Interactions with time-providers" end .oE .PP The third part of the input file is usually the largest part. It consists of a series of records where each record specifies one message. Each record is of the following form: .sS \*Lstart \*O[\*Vflags\*O] .nL \*Vfield_list\*O .nL \*Lend\*O .sE The \*Vflags\*O are optional and are described for the \*Ldefault\*O header above. If specified, they are used instead of the default value. A common mistake is to believe that they act as additions to the \*Ldefault\*O flags specified in the first part of the file. .PP The \*Vfield_list\*O is a set of key-value pairs from the following list: .VL .LI "\*Laction \*Vtext\*O" The text describes the action that should be taken when this error occurs. The text appears in the generated documentation. This field is optional and ignored if the message is undocumented. .LI "\*Lattributes \*Vtext\*O" The text describes the attributes for this message. If this field and the \*Lsub-component\*O field described below are both present, then a convenience macro will be generated that provides all of the arguments to the serviceability messaging routine. This is described in more detail below. .LI "\*Lcode \*Vname \*O[\*L=\*Vvalue\*O]" This is the symbolic name of the message. It is used to create a header file that has \*L#define\*O statements that map all symbolic message names to their numeric value. It also appears in the generated documentation. An optional value may be given when needed to ensure compatibility with older message versions. By default, values are assigned by a simple counter in the order in which messages appear in the file. .LI "\*Lengineer \*Vtext\*O" This is used to specify the software engineer responsible for the code where this message could occur. This field is optional and is never output. .LI "\*Lexplanation \*Vtext\*O" This is a verbose description of the message; it can be blank if the message is not for an error condition. It appears in the documentation files and should provide additional information that can be used for fault isolation. This field is optional if the message is undocumented. .LI "\*Lnotes \*Vtext\*O" Optional notes for translators. This text, if it exists, appears as comments in the message catalog. .LI "\*Lsub-component \*Vtable_index\*O" This field is used in conjunction with the \*Lattributes\*O field. It specifies which subcomponent the message is assigned to. The \*Vtable_index\*O must be one of the indices that is specified in the serviceability table portion of the file. .LI "\*Ltables (\*Vname\*O ...\*L)" If a single component is used for several executables, the message table can get unreasonably large, containing texts that will never be used. This keyword may be used to specify a space-separated list of tables for which the message is appropriate; the table to be generated is specified by the \*L\-t\*O flag. If this keyword is not used or if the \*L\-t\*O flag is not given, then the message will appear in the table. Otherwise, the message will appear in the table only if the table specified by the flag is also specified on this line. .LI "\*Ltext \*Vtext\*O" The message itself. It is stored in the in-core message table (unless the \*Lnot intable\*O flag is given) and in the message catalog. It is intended to be returned by \*Ldce_error_inq_text(\|)\*O and related routines (see \*Ldce_msg_intro(3)\*O). Unless the \*Llongtext\*O flag is given, the text must be shorter than the size of the \*Ldce_error_string_t\*O typedef defined in \*Ldce/dce_error.h\*O. .LI "\&" The text field is used as a \*Lprintf\*O-style format string and is generated in documentation. To support this dual-use, \*Lsams\*O provides a \*L\*O construct. When generating message strings to be used in a program, the ``a'' text is used; when generating documentation, the ``b'' text is used. For example .iS text "Function <%s|func> failed, status=<0x%8.8lx|code>" .iE If the text includes a space, you must enclose it in double quotes. Newlines are removed and whitespace is changed to one space. To write a single less-then sign, prefix it with a backslash. .LE .PP Two typical message records might look like this: .oS .ta \w'sub-component 'u start code dts_s_ok text "Successful completion" notes "Ok, yes, etc." explanation "Operation performed." action "None required." end start code dts_s_bad_timestring text "Invalid time string" explanation "The given string could not be parsed as a valid time specification." action "Correct input and try again." end .oE .PP In addition, the following constructs are accepted, but ignored. This is for compatibility with other systems that might need such fields: .iS \*Ladministrator response \*Vtext\*O \*Loperator response \*Vtext\*O \*Lprogrammer response \*Vtext\*O \*Lseverity \*Vtext\*O \*Lsystem response \*Vtext\*O \*Luser response \*Vtext\*O \*Lvendor \*Vname text\*O .iE .PP Many messages can also be assigned to a single subcomponent and used with a single set of attributes. This is the largest part of the serviceabilty work. If a message has both the \*Lattributes\*O and \*Lsub-component\*O fields specified, then a convenience macro will be generated that specifies the initial parameters to the \*Ldce_svc_printf(\|)\*O call. .PP Here is a sample message definition: .oS .ta \w'sub-component 'u start code dts_s_out_of_range attributes "svc_c_sev_fatal | svc_c_action_exit_bad" sub-component dts_s_provider text "illegal value %ld from %s provider" explanation "Received illegal value from local time provider." action "Fix provider and restart server." end .oE An example of using it to generate a serviceability message is this: .oS dce_svc_printf(DTS_S_OUT_OF_RANGE_MSG, 123, "Sundial"); .oE .SS "Allowing for Growth" .PP It is good practice to group related messages together, but you should leave space to allow additional messages to be added later. The \*Lsams\*O utility provides two ways to do this. .PP First, the message numbering can be explicitly set using the following construct: .iS \*Lset value = \*Vnumber\*O .iE .PP Note that the number used in this construct specifies the code field as in the \*Lvalue\*O header, and not the full message identifier, as can be assigned by giving a value in the \*Lcode\*O field. .PP Second, messages can group into a collection, which is similar to an XPG4 message catalog set. To indicate the start of a collection use the following construct: .iS \*Lstart collection \*Vnumber\*O .iE .PP This is equivalent to using the first construct, except that the \*Vnumber\*O is multiplied by the collection size. A common practice is to have at least one collection for each serviceability sub-component. .SH RELATED INFORMATION Functions: \*Ldce_error_inq_text(3)\*O, \*Ldce_svc_printf(3)\*O. .sp .4v Commands: \*Lgencat(1)\*O in the \*EOSF/1 Command Reference\*O. .zZ "enh,8441,R1.1,new ref page" .\" $Header: sccs.1,v 76.1 95/07/10 17:12:08 ssa Exp $ ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (OSF/1). See /usr/include/COPYRIGHT.OSF1 . .TA s .TH sccs 1 "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sccs - front-end utility program for SCCS commands .SH SYNOPSIS .C sccs .RC [ -r ] .RC [ -d .IR rootpath\| ] .RC [ -p .IR dirpath\| ] .I command .RI [ \|options\| ] .RI [ file \0...\|] .SH DESCRIPTION .PP The .C sccs command is a straightforward front end to the various programs comprising the Source Code Control System. It includes the capability of running set-user-id to another user to allow shared access to the SCCS files. .C sccs reduces the need to explicitly reference the SCCS filenames. The SCCS filenames are generated by prepending the string .C SCCS/s. to the working .I files specified. The default SCCS subdirectory name can be overridden with the .C -p .I dirpath option. .PP The .I command supplied to the .C sccs command can either be an SCCS program or a pseudo command. The SCCS programs that .C sscs handles include .C admin, cdc, comb, delta, get, help, .C prs, rmdel, sact, unget, val, what and .C sccsdiff. The pseudo commands are: .RS .TP 12 .C check Prints a list of all files being edited. Returns a non-zero exit status if a file is being edited. The intent is to allow an 'install' entry in a makefile to verify that everything is included in the SCCS file before a version is installed. See the .C info pseudo command for a description of the .C -b, .CI -u \0user and .C -U options. .TP 12 .C clean Removes all files from the current directory or the named directory that can be recreated from the SCCS files. Does not remove files that are in the process of being edited. If .C -b is given, branches (i.e. SID's with three or more components) are ignored in determining which files are being edited. Therefore, any edits on branches can be lost. .TP 12 .C create Creates the initial SCCS file, taking the contents from .I file. Any options to .C admin are accepted. If the files are created successfully, the original files are renamed with a .C , (comma) on the front. Read-only copies are retrieved with .C get. The renamed files should be removed after you have verified that the SCCS files have been created successfully. .TP 12 .C delget Runs .C delta on the named files and then .C get the new versions. The new versions of the files have expanded identification keywords, and cannot be edited. The .RC [ -mprsy ] options are passed to .C delta, and the .RC [ -bceiklsx ] options are passed to .C get. .TP 12 .C deledit Equivalent to .C delget, except that the .C get phase includes the .C -e option. .TP 12 .C diffs Gives a .C diff listing between the current version of the files being edited and the versions in SCCS format. The .RC [ -rcixt ] options are passed to .C get. The .RC [ -lsefhb ] options are passed to .C diff. The .C -C option is passed to .C diff as .C -c. .TP 12 .C edit Equivalent to .C get -e. .TP 12 .C enter Equivalent to .C create, except .C get is omitted. This pseudo command is useful when you want to run the .C edit command immediately after creating the SCCS file. .TP 12 .C fix Removes a named delta, but leaves a copy of the delta in the current directory. The .CI -r \0SID option is required and must point to a leaf in the source tree. Since a record of the changes is not preserved, .C fix should be used carefully. .TP 12 .C info Lists all the files being edited. The .C -b option ignores branches in determining which files are being edited. The .CI -u \0user option lists only the files being edited by .I user. The .C -U option is equivalent to .CI -u \0current_user. .TP 12 .C print Prints information about named files. Equivalent to .C prs -a followed by .C get -p -m -s. .TP 12 .C tell Lists all the files being edited, with a newline after each entry. See the .C info section for a description of the .C -b, .CI -u \0user and .C -U options. .TP 12 .C unedit Equivalent to .C unget. Any changes made since the last .C get are lost. Use with caution. .RE .PP Certain commands, .C admin, cdc, check, clean, diffs, .C info, rmdel, sccsdiff, and .C tell cannot use the set-user-id feature, as this would allow anyone to change the authorizations. These commands are always run as the real user. .SS Options .PP The .I options supplied to the SCCS commands are documented in the corresponding SCCS man pages. The .I options supplied to the pseudo commands are documented in the above section. All other options preceding .I command are documented as follows: .RS .TP 15 .C -r Runs .C sccs as the real user rather than the effective user .C sccs is set-user-id to. .TP 15 .CI -d \0rootpath Gives the pathname to be used as the root directory for the SCCS files. .I rootpath defaults to the current directory. This flag takes precedence over the PROJECTDIR environment variable. .TP 15 .CI -p \0dirpath Specifies the pathname for the SCCS files. The default is the SCCS directory. .I dirpath is appended to .I rootpath and is inserted before the final component of the pathname. .RE .PP The command .C sccs -d /usr -p cmd .C get src/b converts to .C get /usr/src/cmd/s.b. This can be used to create aliases. For example, the command .C alias syssccs="sccs -p /usr/src/cmd" makes .C syssccs an alias that can be used in commands like .C syssccs get b. .SH EXTERNAL INFLUENCES .SS Environment Variables .PP If the .C PROJECTDIR environment variable is set, its value is used to determine the .CI -d \0rootpath option value for .I rootpath. If .C PROJECTDIR begins with a / (slash), the value is used directly; otherwise, the value is assume to be a login name and the home directory corresponding to login name is examined for a subdirectory named .C src or .C source. If found, this directory path is used. Otherwise, the value is used as a relative path name. .PP .C LC_CTYPE determines the interpretation of text within file as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C sccs behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH EXAMPLES .PP To create a new SCCS file: .ti +5 sccs create file .PP To get a file for editing, edit it, create a new delta and get file for editing: .nf .in +5 sccs edit file.c ex file.c sccs deledit file.c .in -5 .PP To get a file from another directory (/usr/src/cmd/SCCS/s.cc.c): .ti +5 sccs -d /usr/src get cmd/cc.c .PP To make a delta of a large number of files in the current directory, enter: .ti +5 sccs delta *.c .PP To get a list of files being edited that are not on branches, enter: .ti +5 sccs info -b .PP To get a list of files being edited by you, enter: .ti +5 sccs tell -u .fi .PP In a makefile, to get source files from an SCCS file if it does not already exist, enter: .nf .in +5 SRCS = $ (SRCS) : sccs get $(REL) $@ .fi .in -5 .SH RETURN VALUE A successful completion returns 0. On error, .C sccs exists with a value from or the exit value from the .I command that was invoked. The only exception is the .C check pseudo command which returns a non-zero exit status if a file is being edited. .SH SEE ALSO .PP admin(1), cdc(1), comb(1), delta(1), get(1), prs(1), rmdel(1), sact(1), sccsdiff(1), sccshelp(1), unget(1), val(1), vc(1), what(1), sccsfile(4). .PP .I SCCS: Source Code Control System chapter in .IR "Programming on HP-UX" . .SH STANDARDS CONFORMANCE .CR sccs ": XPG4" .\" toc@\f3sccs(1)\f1:\0\0\f4sccs\f1@@@utility program for SCCS commands .\" index@\f4sccs\f1 \- utility program for SCCS commands @@@\f3sccs(1)\f1 .\" index@\f1utility program for SCCS commands @@@\f3sccs(1)\f1 .\" index@\f1program for SCCS commands @@@\f3sccs(1)\f1 .\" index@\f1SCCS commands, utility program for @@@\f3sccs(1)\f1 .\" $Header: sccsdiff.1,v 72.5 94/04/27 11:56:40 ssa Exp $ .TA s .TH sccsdiff 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sccsdiff \- compare two versions of an SCCS file .SH SYNOPSIS .C sccsdiff .CI -r\c .SM .I SID\s01 .CI -r\c .SM .I SID\s02 .RC [ -p ] .RC [ -s\c .IR n\| ] .I file \0... .SH DESCRIPTION The .C sccsdiff command compares two versions of an .SM SCCS file, and generates the differences between the two versions. Any number of .SM SCCS files may be specified, but arguments apply to all files. .RS .TP 15 .CI -r \s-1SID\s+1? .SM .I SID\s01 and .SM .I SID\s02 specify the deltas of an .SM SCCS file that are to be compared. Versions are passed to .C bdiff in the order given (see .IR bdiff (1)). The .SM SID\c s accepted, and the corresponding version retrieved for the comparison are the same as for .C get (see .IR get (1)). .TP .C -p Pipe output for each file through .C pr (see .IR pr (1)). .TP .CI -s n .I n is the file segment size that .C bdiff passes to .C diff (see .IR diff (1)). This is useful when .C diff fails due to a high system load. .RE .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported with the exception that multi-byte-character file names are not supported. .SH DIAGNOSTICS .TP 10 .IC file ": No differences" The two versions are identical. .PP Use .IR sccshelp (1) for explanations. .SH FILES .TP 20 .C /tmp/get????? Temporary files .SH SEE ALSO bdiff(1), diff(1), get(1), pr(1), sccshelp(1). .\" .\" toc@\f3sccsdiff(1)\f1:\0\0\f4sccsdiff\f1@@@compare two versions of an \s-1SCCS\s+1 file .\" .\" index@\f4sccsdiff\f1 \- compare two versions of an \s-1SCCS\s+1 file@@@\f3sccsdiff(1)\f1 .\" index@\s-1SCCS\s+1: compare two versions of an \s-1SCCS\s+1 file@@@\f3sccsdiff(1)\f1 .\" index@files: compare two versions of an \s-1SCCS\s+1 file@@@\f3sccsdiff(1)\f1 .\" index@compare two versions of an \s-1SCCS\s+1 file@@@\f3sccsdiff(1)\f1 .\" index@versions of an \s-1SCCS\s+1 file, compare two@@@\f3sccsdiff(1)\f1 .\" .\" fileset_database@sccsdiff.1 USER-CMDS-MAN .\" $Header: sccshelp.1,v 72.3 94/06/27 16:59:26 ssa Exp $ .TA s .TH sccshelp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sccshelp \- ask for help on SCCS commands .SH SYNOPSIS .CR sccshelp .RI \|[ arg ]\ ...\& .SH DESCRIPTION The .CR sccshelp command finds information to explain a message from an SCCS command or to explain the use of a SCCS command. Zero or more arguments can be supplied. If no arguments are given, .CR sccshelp prompts for one: .IP .CR "What is the message number or SCCS command name?" .PP The arguments can be either message numbers (which normally appear in parentheses following messages) or command names, of one of the following types: .RS .TP 10 type 1 Begins with nonnumerics, ends in numerics. The nonnumeric prefix is usually an abbreviation for the program or set of routines which produced the message (e.g., .CR ge6 , for message 6 from the .CR get command). .TP type 2 Does not contain numerics (as a command, such as .CR get ). .TP type 3 Is all numeric (e.g., .CR 212 ). .RE .PP The response of the program is the explanatory information related to the argument, if there is any. .PP You can use .CR sccshelp to support other commands by means of the .CR helploc file. To do this, create help files in the appropriate format and add the location of the helpfiles to .CR /usr/share/lib/sccshelp/helploc . .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_CTYPE determines the interpretation of text as single- and/or multibyte characters. .PP .CR LANG determines the language in which messages are displayed. .PP If .CR LC_CTYPE is not specified or is null, it defaults to the value of .CR LANG . If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). If any internationalization variable contains an invalid setting, all internationalization variables default to "C". See .IR environ (5). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH DIAGNOSTICS .TP .CI "There is not a place to look for help on the subject of " arg .TP .CI "There is not any help available on the subject of " arg .PP When all else fails, try .CR "sscshelp stuck" . .SH EXAMPLES If you enter the SCCS .CR get command without parameters, you would get the message: .IP .C "ERROR: missing file arg (cm3)" .PP If you request help for the command: .IP .C "sccshelp get" .PP it displays: .nf .IP .C "get:" .C " get [-r] [-c] [-i] [-x] [-a]" .C " [-k] [-e] [-l

] [-p] [-m] [-n] [-s] [-b] [-g] [-t]" .C " [-w] file ..." .fi .PP If you request help for the error number: .IP .C "sccshelp cm3" .PP it displays: .nf .IP .C "cm3:" .C """missing file arg""" .C "You left off the name of the file to be processed." .fi .SH WARNINGS Only SCCS commands currently use .CR sccshelp . .SH FILES .ifn .TP 33 .ift .TP 45 .CR /usr/share/lib/sccshelp Directory containing files of message text .TP .CR /usr/share/lib/sccshelp/cmds List of commands supported by sccshelp .TP .CR /usr/share/lib/sccshelp/helploc File containing the locations of help files that are not in the .CR /usr/share/lib/sccshelp directory .\" .\" toc@\f3sccshelp(1)\f1:\0\0\f4sccshelp\f1@@@help for SCCS commands .\" .\" index@\f4sccshelp\f1 \- help for SCCS commands@@@\f3sccshelp(1)\f1 .\" index@help for SCCS commands@@@\f3sccshelp(1)\f1 .\" index@SCCS command help@@@\f3sccshelp(1)\f1 .\" $Header: script.1,v 72.4 93/11/11 21:14:57 ssa Exp $ .TA s .TH script 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME script \- make typescript of terminal session .SH SYNOPSIS .C script .RC [ -a ] .RI [ \|file\| ] .SH DESCRIPTION .C script makes a typescript of everything printed on your terminal. It starts a shell named by the .C SHELL environment variable, or by default .CR /usr/bin/sh , and silently records a copy of output to your terminal from that shell or its descendents, using a pseudo-terminal device (see .IR pty (7)). .PP All output is written to .IR file , or appended to .I file if the .C -a option is given. If no file name is given, the output is saved in a file named .CR typescript . The recording can be sent to a line printer later with .IR lp (1), or reviewed safely with the .C -v option of .IR cat (1). .PP The recording ends when the forked shell exits (or the user ends the session by typing "exit") or the shell and all its descendents close the pseudo-terminal device. .PP This program is useful when operating a .SM CRT display and a hard-copy record of the dialog is desired. It can also be used for a simple form of session auditing. .PP .C script respects the convention for login shells as described in .IR su (1), .IR sh (1), and .IR ksh (1). Thus, if it is invoked with a command name beginning with a hyphen .RC ( - ) (that is, .CR -script ), .C script passes a basename to the shell that is also preceded by a hyphen. .SH EXAMPLES Save everything printed on the user's screen into file .CR scott : .IP .C script scott .PP Append a copy of everything printed to the user's screen to file .CR temp : .IP .C script -a temp .SH WARNINGS A command such as .CR "cat scott" , which displays the contents of the destination file, should not be issued while executing .C script because it would cause .C script to log the output of the .C cat command to itself until all available disk space is filled. Other commands, such as .IR more (1), can cause the same problem but to a lesser degree. .PP .C script records all received output in the .IR file , including typing errors, backspaces, and cursor motions. Note that it does not record typed characters; only echoed characters. Thus passwords are not recorded in the .IR file . Responses other than simple echoes (such as output from screen-oriented editors and .C ksh command editing) are recorded as they appeared in the original session. .SH AUTHOR .C script was developed by the University of California, Berkeley and HP. .\" .\" index@\f4script\f1 \- make typescript of terminal session@@@\f3script(1)\f1 .\" index@typescript of terminal session, record@@@\f3script(1)\f1 .\" index@terminal session, record typescript of@@@\f3script(1)\f1 .\" index@session, record typescript of terminal output during@@@\f3script(1)\f1 .\" index \s-1CRT\s+1 terminal, record displayed output simultaneously in a file \f3script(1)\f1 .\" index record displayed \s-1CRT\s+1 terminal output simultaneously in a file \f3script(1)\f1 .\" index displayed \s-1CRT\s+1 terminal output, record, simultaneously in a file \f3script(1)\f1 .\" index copy displayed \s-1CRT\s+1 terminal output simultaneously in a file \f3script(1)\f1 .\" .\" toc@\f3script(1)\f1:\0\0\f4script\f1@@@make typescript of terminal session .\" .\" fileset_database@script.1 USER-CMDS-MAN .\" $Header: sdiff.1,v 72.4 93/01/14 11:39:18 ssa Exp $ .TA s .TH sdiff 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sdiff \- side-by-side difference program .SH SYNOPSIS .C sdiff .RI [ \|options \0...\|] .I file1 file2 .SH DESCRIPTION .C sdiff uses the output of .IR diff (1) to produce a side-by-side listing of two files, indicating those lines that are different. Each line of the two files is printed with a blank gutter between them if the lines are identical, a .C < in the gutter if the line only exists in .IR file1 , a .C > in the gutter if the line only exists in .IR file2 , and a .C | for lines that are different. .PP For example: .PP .TS center tab(@); cI c cI. abc@|@xyz abc@\&@abc bca@< cba@< dcb@\&@dcb \&@>@cde .TE .SS Options .C sdiff recognizes the following options: .RS .TP 12 .CI -w \0n Use the next argument, .IR n , as the width of the output line. The default line length is 130 characters. .TP .C -l Only print on the left side when lines are identical. .TP .C -s Do not print identical lines. .TP .CI -o \0output Use the next argument, .IR output , as the name of a third file that is created as a user-controlled merging of .I file1 and .IR file2 . Identical lines of .I file1 and .I file2 are copied to .IR output . Sets of differences, as produced by .IR diff (1), are printed; where a set of differences share a common gutter character. After printing each set of differences, .C sdiff prompts the user with a .C % and waits for one of the following user-typed commands: .RS .RS .TP 5 .C l append the left column to the output file .TP .C r append the right column to the output file .TP .C s turn on silent mode; do not print identical lines .TP .C v turn off silent mode .TP .C e\0l call the editor with the left column .TP .C e\0r call the editor with the right column .TP .C e\0b call the editor with the concatenation of left and right .TP .C e call the editor with a zero length file .TP .C q exit from the program .RE .RE .IP On exit from the editor, the resulting file is concatenated on the end of the .I output file. .RE .SH EXAMPLES Print a side-by-side diff of two versions of a file on a printer capable of printing 132 columns: .IP .C "sdiff -w132 prog.c.old prog.c | lp -dlineprinter" .PP Retrieve the most recently checked in version of a file from .SM RCS and compare it with the version currently checked out: .IP .C "co -p prog.c > /tmp/$$; sdiff /tmp/$$ prog.c | more; rm /tmp/$$" .SH SEE ALSO diff(1), ed(1). .\" .\" index@\f4sdiff\f1 \- compare two files and show differences side-by-side@@@\f3sdiff(1)\f1 .\" index@files: compare two files and show differences side-by-side@@@\f3sdiff(1)\f1 .\" index@show file differences side-by-side@@@\f3sdiff(1)\f1 .\" index@compare two files and show differences side-by-side@@@\f3sdiff(1)\f1 .\" index@differences between files, show side-by-side@@@\f3sdiff(1)\f1 .\" .\" toc@\f3sdiff(1)\f1:\0\0\f4sdiff\f1@@@side-by-side difference program .\" .\" fileset_database@sdiff.1 USER-CMDS-MAN .\" $Header: sed.1,v 76.1 95/08/07 11:42:59 ssa Exp $ .TA s .TH sed 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sed \- stream text editor .SH SYNOPSIS .C sed .RC [ -n ] .I script .RI [ \|file \0...\|] .PP .C sed .RC [ -n ] .RC [ -e .IR script\| ]\0...\& .RC [ -f .IR script_file\| ]\0...\& .RI [ \|file \0...\|] .SH DESCRIPTION .C sed copies the named text .IR file s (standard input default) to the standard output, edited according to a script containing up to 100 commands. Only complete input lines are processed. Any input text at the end of a file that is not terminated by a new-line character is ignored. .SS Options .C sed recognizes the following options: .RS .TP 12 .CI -f \0script_file Take script from file .IR script_file . .TP .CI -e \0script Edit according to .IR script . If there is just one .C -e option and no .C -f options, the flag .C -e can be omitted. .TP .C -n Suppress the default output. .RE .PP .C sed interprets all .CI -e script and .CI -f script_file arguments in the order given. Use caution, if mixing .C -e and .C -f options, to avoid unpredictable or incorrect results. .SS Command Scripts A script consists of editor commands, one per line, of the following form: .IP .RI [ \|address .RC [ \|, .IR address\| ]\|] .I function .RI [ \|arguments\| ] .PP In normal operation, .C sed cyclically copies a line of input into a .I pattern space (unless there is something left after a .C D command), applies in sequence all commands whose .I addresses select that pattern space, and, at the end of the script, copies the pattern space to the standard output (except under .CR -n ) and deletes the pattern space. .PP Some of the commands use a .I hold space to save all or part of the .I pattern space for subsequent retrieval. .SS Command Addresses An .I address is either a decimal number that counts input lines cumulatively across files, a .C $ which addresses the last line of input, or a context address; that is, a .CI / "regular expression" / in the style of .IR ed (1) modified thus: .RS .TP 3 \(bu In a context address, the construction .CI \e "?regular expression?" \f1, where .I ? is any character, is identical to .CI / "regular expression" /\f1. Note that in the context address .CR \exabc\exdefx , the second .C x stands for itself, so that the regular expression is .CR abcxdef . .TP \(bu The escape sequence .C \en matches a new-line character embedded in the pattern space. .TP \(bu A period .RC ( . ) matches any character except the terminal new-line of the pattern space. .TP \(bu A command line with no addresses selects every pattern space. .TP \(bu A command line with one address selects each pattern space that matches the address. .TP \(bu A command line with two addresses selects the inclusive range from the first pattern space that matches the first address through the next pattern space that matches the second (if the second address is a number less than or equal to the line number first selected, only one line is selected). Thereafter the process is repeated, looking again for the first address. .RE .PP .C sed supports Basic Regular Expression syntax (see .IR regexp (5)). .PP Editing commands can also be applied to only non-selected pattern spaces by use of the negation function .C ! (described below). .SS Command Functions In the following list of functions, the maximum number of permissible addresses for each function is indicated in parentheses. Other function elements are interpreted as follows: .RS .TP 12 .I text One or more lines, all but the last of which end with .C \e to hide the new-line. Backslashes in .I text are treated like backslashes in the replacement string of an .C s command, and can be used to protect initial blanks and tabs against the stripping that is done on every script line. .TP .I rfile Must terminate the command line, and must be preceded by exactly one blank. .TP .I wfile Must terminate the command line, and must be preceded by exactly one blank. Each .I wfile is created before processing begins. There can be at most 10 distinct .I wfile arguments. .RE .PP .C sed recognizes the following functions: .PP .PD 0 .TP 12 .RC (1) \|a\e .PD 0 .TP .I text Append. Place .I text on the output before reading next input line. .PD .TP .RC (2) \|b " \f2label\fP" Branch to the .C : command bearing .IR label . If no .I label is specified, branch to the end of the script. .TP .RC (2) \|c\e .PD 0 .TP .I text Change. Delete the pattern space. With 0 or 1 address or at the end of a 2-address range, place .I text on the output. Start the next cycle. .PD .TP .RC (2) \|d Delete pattern space and start the next cycle. .TP .RC (2) \|D Delete initial segment of pattern space through first new-line and start the next cycle. .TP .RC (2) \|g Replace contents of the pattern space with contents of the hold space. .TP .RC (2) \|G Append contents of hold space to the pattern space. .TP .RC (2) \|h Replace contents of the hold space with contents of the pattern space. .TP .RC (2) \|H Append the contents of the pattern space to the hold space. .TP .RC (1) \|i\e .PD 0 .TP .I text Insert. Place .I text on the standard output. .PD .TP .RC (2) \|l List the pattern space on the standard output in an unambiguous form. Non-printing characters are spelled in three-digit octal number format (with a preceding backslash), and long lines are folded. .TP .RC (2) \|n Copy the pattern space to the standard output if the default output has not been suppressed (by the .C -n option on the command line or the .C #n command in the .I script file). Replace the pattern space with the next line of input. .TP .RC (2) \|N Append the next line of input to the pattern space with an embedded new-line. (The current line number changes.) .TP .RC (2) \|p Print. Copy the pattern space to the standard output. .TP .RC (2) \|P Copy the initial segment of the pattern space through the first new-line to the standard output. .TP .RC (1) \|q Quit. Branch to the end of the script. Do not start a new cycle. .TP .RC (1) \|r " \f2rfile\fP" Read contents of .I rfile and place on output before reading the next input line. .TP .CI \f1(2)\fP\|s\|/ "regular expression" / replacement / flags Substitute .I replacement string for instances of .I regular expression in the pattern space. Any character can be used instead of .CR / . For a fuller description see .IR ed (1). .I flags is zero or more of: .RS 15 .TP 12 .I n .IR n \|=\|1-2048 .RC ( LINE_MAX ). Substitute for just the .IR n th occurrence of .I regular expression in the pattern space. .TP .C g Global. Substitute for all non-overlapping instances of .I regular expression rather than just the first one. .TP .C p Print the pattern space if a replacement was made and the default output has been suppressed (by the .C -n option on the command line or the .C #n command in the .I script file). .TP .CI w " wfile" Write. Append the pattern space to .I wfile if a replacement was made. .RE .TP 12 .RC (2) \|t " \f2label\fP" Test. Branch to the .C : command bearing the .I label if any substitutions have been made since the most recent reading of an input line or execution of a .CR t . If .I label is empty, branch to the end of the script. .TP .RC (2) \|w " \f2wfile\fP" Write. Append the pattern space to .IR wfile . .TP .RC (2) \|x Exchange the contents of the pattern and hold spaces. .TP .CI \f1(2)\fP\|y/ string1 / string2 / Transform. Replace all occurrences of characters in .I string1 with the corresponding character in .IR string2 . The lengths of .I string1 and .I string2 must be equal. .TP .CI \f1(2)\fP! " function" Don't. Apply the .I function (or group, if .I function is .CR {\| ) only to lines .I not selected by the address or addresses. .TP .CI \f1(0)\fP\|: " label" This command does nothing; it bears a .I label for .C b and .C t commands to branch to. .TP .RC (1) \|= Place the current line number on the standard output as a line. .TP .RC (2) \|{ Execute the following commands through a matching .C } only when the pattern space is selected. The syntax is: .nf .IP .C { cmd1 .C cmd2 .C cmd3 .C \0\&. .C \0\&. .C \0\&. .C } .fi .TP (0) An empty command is ignored. .TP .RC (0) \|# If a .C # appears as the first character on the first line of a script file, that entire line is treated as a comment with one exception: If the character after the .C # is an .CR n , the default output is suppressed. The rest of the line after .C #n is also ignored. A script file must contain at least one non-comment line. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C sed will behave as if all internationalization variables are set to "C". See .IR environ (5). .PP .C LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .PP .C LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .C LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .C NLSPATH determines the location of message catalogues for the processing of .C LC_MESSAGES. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES Make a simple substitution in a file from the command line or from a shell script, changing .C abc to .CR xyz : .IP .C sed 's/abc/xyz/' file1 >file1.out .PP Same as above but use shell or environment variables .C var1 and .C var2 in search and replacement strings: .IP .ifn \f3sed "s/$var1/$var2/" file1 >file1.out\f1 .ift \f4\s+1sed "s/$var1/$var2/" file1 >file1.out\f1\s0 .PP or .IP .C sed 's/'$var1'/'$var2'/' file1 >file1.out .PP Multiple substitutions in a single command: .IP .C sed -e 's/abc/xyz/' -e 's/lmn/rst/' file1 >file1.out .PP or .IP .C sed -e 's/abc/xyz/' \e .br .C -e 's/lmn/rst/' \e .br .C file1 >file1.out .SH WARNINGS .C sed limits command scripts to a total of not more than 100 commands. .PP The hold space is limited to 8192 characters. .PP .C sed processes only text files. See the glossary for a definition of text files and their limitations. .SH AUTHOR .CR sed was developed by OSF and HP. .SH SEE ALSO awk(1), ed(1), grep(1), environ(5), lang(5), regexp(5). .PP .CR sed : .I A Non-Interactive Streaming Editor tutorial in the .IR "Text Processing Users Guide" . .SH STANDARDS CONFORMANCE .CR sed ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4sed\f1 \- streaming text editor@@@\f3sed(1)\f1 .\" index@editor: streaming (non-interactive) text editor@@@\f3sed(1)\f1 .\" index@text editors@@@see editor .\" index@streaming text editor@@@\f3sed(1)\f1 .\" .\" toc@\f3sed(1)\f1:\0\0\f4sed\f1@@@stream text editor .\" $Header: send_sound.1,v 74.1 95/05/10 22:02:12 ssa Exp $ .TA s .TH send_sound 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME send_sound \- play an audio file .SH SYNOPSIS .C /opt/audio/bin/send_sound \f1[\f3-format_switch \f3-server \f2system \f3-loop \f2number \f3-pri \f2priority \f3-srate \f2rate \f3-prate \f2rate \f3-stereo\f1] .SH DESCRIPTION This command plays an audio file. .C send_sound is the command used when you double-click an audio file from the HP VUE File Manager. The file begins playing, according to the settings of the Audio Control Panel. .TP 15 .I -format_switch is one these formats: .RS .TP 10 .C au Sun file format .TP .C snd NeXT file format .TP .C wav Microsoft RIFF Waveform file format .TP .C u MuLaw format .TP .C al ALaw .TP .C l16 linear 16-bit format .TP .C lo8 offset (unsigned) linear 8-bit format .TP .C l8 linear 8-bit format .RE .IP If you omit the filename with this option, .C send_sound plays the audio data from .C stdin. .TP .CI -server \0system plays the file on the output of an audio server identified by .I system which is either a system name or a TCP/IP address. .TP .CI -loop \0number plays the file the .I number of times you supply. Note that you cannot use this option if the source is .C stdin; a filename is required. .TP .CI -pri \0priority plays file with the .I priority you supply, either .C urgent, hi, normal, or .C lo. .TP .CI -srate \0rate sets the sample .I rate of the source audio. .TP .CI -prate \0rate plays the audio file at the sampling .I rate you enter. .TP .C -stereo plays a stereo file. This option is needed only for a raw data file with stereo data. .SH AUTHOR .C send_sound was developed by .SM HP. .br NeXT is a trademark of NeXT Computers, Inc. .br Microsoft is a trademark of Microsoft Corporation. .SH SEE ALSO audio(5), asecure(1m), aserver(1m), attributes(1), convert(1). .\" .\" index@\f4send_sound\f1 \- play audio file@@@\f3send_sound(1)\f1 .\" index@\f1play audio file@@@\f3send_sound(1)\f1 .\" index@\f1audio file, play@@@\f3send_sound(1)\f1 .\" toc@\f3send_sound(1)\f1:\0\0\f4send_sound\f1@@@play audio file .\" $Header: serialize.1,v 72.2 94/07/22 15:49:53 ssa Exp $ .TA s .TH serialize 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME serialize \- force target process to run serially with other processes .SH SYNOPSIS .C serialize .I command .RI [ command_args ] .PP .C serialize .RC [ -t ] .RC [ -p .IR pid ] .SH DESCRIPTION The .CR serialize command is used to force the target process to run serially with other processes also marked by this command. The target process can be referred to by .IR pid value, or it can be invoked directly on the .IR command. Once a process has been marked by .CR serialize , the process stays marked until process completion unless .CR serialize is reissued on the serialized process with the .CR -t option. The .CR -t option causes the .IR pid specified with the .CR -p option to return to normal timeshare scheduling algorithms. .PP This call is used to improve process throughput, since process throughput usually increases for large processes when they are executed serially instead of allowing each program to run for only a short period of time. By running large processes one at a time, the system makes more efficient use of the CPU as well as system memory, since each process does not end up constantly faulting in its working set, to only have the pages stolen when another process starts running. As long as there is enough memory in the system, processes marked by .CR serialize behave no differently from other processes in the system. However, once memory becomes tight, processes marked by .CR serialize are run one at a time with the highest priority processes being run first. Each process will run for a finite interval of time before another serialized process is allowed to run. .SS Options .CR serialize supports the following options: .RS .TP 10 .C -t Indicates the process specified by .IR pid should be returned to timeshare scheduling. .TP .C -p Indicates the .IR pid of the target process. .RE .PP If neither option is specified, .CR serialize is invoked on the command line passed in. .ifn .bp .SH RETURN VALUE .CR serialize returns the following value: .RS .TP 5 .C 0 Successful completion. .PD 0 .TP .C 1 Invalid .IR pid specification, nonnumeric entry, or <= PID_MAXSYS. .TP .C 2 Could not execute the specified command. .TP .C 3 No such process. .TP .C 4 Must be root or a member of a group having SERIALIZE privilege to execute .CR serialize . .RE .PD .SH ERRORS .CR serialize fails under the following condition and sets .CR errno (see .IR errno (2)) to the following value: .RS .TP 15 [ESRCH] The .IR pid passed in does not exist. .SH EXAMPLES Use .CR serialize to force a database application to run serially with other processes marked for serialization: .IP .C "serialize database_app" .PP Force a currently running process with a .IR pid value of 215 to run serially with other processes marked for serialization: .IP .C "serialize -p 215" .PP Return a process previously marked for serialization to normal timeshare scheduling. The .IR pid of the target process for this example is .CR 174 : .IP .C "serialize -t -p 174" .SH WARNINGS The user has no way of forcing an execution order on serialized processes. .SH AUTHOR .CR serialize was developed by HP. .SH SEE ALSO setprivgrp(1M), getprivgrp(2), serialize(2), privilege(5). .\" .\" toc@\f3serialize(1)\f1:\0\0\f4serialize\f1@@@force target process to run serially with other processes\f1 .\" .\" index@\f4serialize\f1 \- force target process to run serially with other processes@@@\f3serialize(1)\f1 .\" index@\f1target process, force to run serially with other processes @@@\f3serialize(1)\f1 .\" index@\f1process, force target to run serially with other processes @@@\f3serialize(1)\f1 .\" $Header: sh-bourne.1,v 74.1 95/03/23 17:36:32 ssa Exp $ .TA s .TH sh-bourne 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sh, rsh \- Bourne shell, the standard/restricted command programming language .SH SYNOPSIS .C sh .RC [ -\|-acefhiknrstuvx \0...\|] .RI [ \|arg \0...\|] .br .C rsh .RC [ -\|-acefhiknrstuvx \0...\|] .RI [ \|arg \0...\|] .SH DESCRIPTION .C sh is a command programming language that executes commands read from a terminal or a file. .C rsh is a restricted version of the standard command interpreter .CR sh ; it is used to set up login names and execution environments whose capabilities are more controlled than those of the standard shell. See ``Invocation'' and ``Special Commands'' sections later in this entry for details about command line options and arguments, particularly the .C set command. .SS Definitions A .B blank is a tab or a space character. A .B name is a sequence of letters, digits, or underscores beginning with a letter or underscore. A .B parameter is a name, a digit, or any of the characters .CR * , .ifn \f3@\f1, .ift \f4@\f1, .CR # , .CR ? , .CR - , .CR $ , and .CR ! . .SS Commands A .B simple-command is a sequence of non-blank .B words separated by .BR blanks . The first word specifies the name of the command to be executed. Except as specified below, the remaining words are passed as arguments to the invoked command. The command name is passed as argument 0 (see .IR exec (2)). The .B value of a simple-command is its exit status if it terminates normally, or (octal) 200+\c .B status if it terminates abnormally (see .IR signal (5) for a list of status values). .PP A .B pipeline is a sequence of one or more .B commands separated by .C | (or, for historical compatibility, by .CR ^ ). The standard output of each command except the last is connected by a .IR pipe (2) to the standard input of the next command. Each command is run as a separate process and the shell waits for the last command to terminate. The exit status of a pipeline is the exit status of the last command. .PP A .B list is a sequence of one or more pipelines separated by .CR ; , .CR & , .CR && , or .CR |\|| , and optionally terminated by .C ; or .CR & . Of these four symbols, .C ; and .C & have equal precedence, which is lower than that of .C && and .CR |\|| . The symbols .C && and .C |\|| also have equal precedence. A semicolon .RC ( ; ) causes sequential execution of the preceding pipeline; an ampersand .RC ( & ) causes asynchronous execution of the preceding pipeline (i.e., the shell does .I not wait for that pipeline to finish). The symbol .C && .RC (\| |\|| ) causes the .I list following it to be executed only if the preceding pipeline returns a zero (non-zero) exit status. An arbitrary number of new-line characters instead of semicolons can appear in a .B list to delimit commands. .PP A .B command is either a simple-command or one of the following. Unless otherwise stated, the value returned by a command is that of the last simple-command executed in the command. .PP .TP 15 .if n \f3for\fP \f2name\fP [\| \f3in\fP \f2word\fP ... \|] \f3do\fP \f2list\fP \f3done\fP .ift \f4for\fP \f2name\fP [\| \f4in\fP \f2word\fP ... \|] \f4do\fP \f2list\fP \f3done\fP Each time a .C for command is executed, .I name is set to the next .I word taken from the .C in .I word list. If .CI in " word" \&... is omitted, the .C for command executes the .CI do \0list once for each positional parameter that is set (see .I Parameter Substitution below). Execution ends when there are no more words in the list. .TP .ifn \{\f3case\fP \f2word\fP \f3in\fP [\|\f2pattern\fP [\|\(bv \ \f2pattern\fP\|] ... \f3)\fP \f2list\fP \f3;;\fP\|] ... \f3esac\fP\} .ift \{\f4case\fP \f2word\fP \f4in\fP [\|\f2pattern\fP [\|\f4| \ \f2pattern\fP\|] ... \f4)\fP \f2list\fP \f4;;\fP\|] ... \f4esac\fP\} A .C case command executes the .I list associated with the first .I pattern that matches .IR word . The form of the patterns is the Pattern Matching Notation as qualified for the .C case command (see .IR regexp (5)). .TP .if n \{\f3if\fP \f2list\fP \f3then\fP \f2list\fP [\| \ \f3elif\fP \f2list\fP \f3then\fP \f2list\fP \|] ... \ [\| \f3else\fP \f2list\fP \|] \f3f\&i\fP\} .if t \{\f4if\fP \f2list\fP \f4then\fP \f2list\fP \ [\|\f4elif\fP \f2list\fP \f4then\fP \f2list\fP\|] ... \ [\|\f4else\fP \f2list\fP\|] \f4f\&i\fP\} The .I list following .C if is executed and, if it returns a zero exit status, the .I list following the first .C then is executed. Otherwise, the .I list following .C elif is executed and, if its value is zero, the .I list following the next .C then is executed. Failing that, the .C else .I list is executed. If no .C else .I list or .C then .I list is executed, the .C if command returns a zero exit status. .TP .CI while \0list \0do \0list \0done A .C while command repeatedly executes the .C while .I list and, if the exit status of the last command in the list is zero, executes the .C do .IR list ; otherwise the loop terminates. If no commands in the .C do .I list are executed, the .C while command returns a zero exit status; .C until can be used in place of .C while to negate the loop termination test. .TP .CI ( \|list\| ) Execute .I list in a sub-shell. .TP .CI { \|list\| ;} The purpose of using braces is to allow the aggregate output from .I list to be redirected elsewhere. If redirection is used as in: .RS .IP .CI { \|list ;\|}\0> \|file .RE .IP a subshell is created to execute .IR list . This implies that any shell variables set, created, or modified within the .C {\|} do not retain their values outside the .CR {\|} . If no redirection is used, a subshell is not created, and shell modifications made within the .C {\|} are preserved. .TP .IC name \0(\|)\0{ \|list ;\|} Define a function which is referenced by .I name. The body of the function is the .I list of commands between .C { and .CR } . Execution of functions is described below (see ``Execution''). .PP The following words are recognized only as the first word of a command, and when not quoted: .IP .C "if then else elif fi case esac for while until do done { }" .SS Comments A word beginning with .C # causes that word and all the following characters up to a new-line character to be ignored. .SS Command Substitution The standard output from a command enclosed in a pair of grave accents .RC ( \(ga\|\(ga ) can be used as part or all of a word; trailing new-lines are removed. .SS Parameter Substitution The .C $ character is used to introduce substitutable .IR parameters . There are two types of parameters, positional and keyword. If .I parameter is a digit, it is a positional parameter. Positional parameters can be assigned values by .CR set . Keyword parameters (also known as variables) can be assigned values by writing: .IP .IC name = value [\|\c .IC name = value\c \|] ... .PP Pattern-matching is not performed on .IR value . Having a function and a variable with the same .I name is not allowed. .PP .TP 15 .CI ${ \|parameter\| } The value, if any, of the parameter is substituted. Braces are required only when .I parameter is followed by a letter, digit, or underscore that is not to be interpreted as part of its name. If .I parameter is .C * or .ifn \f3@\f1, .ift \f4@\f1, all positional parameters, starting with .CR $1 , are substituted (separated by spaces). Parameter .C $0 is set from argument zero when the shell is invoked. .TP .CI ${ parameter :- word } If .I parameter is set and is non-null, substitute its value; otherwise substitute .IR word . .TP .CI ${ parameter := word } If .I parameter is not set or is null, set it to .IR word ; the value of the parameter is then substituted. Positional parameters cannot be assigned to in this way. .TP .CI ${ parameter :? word } If .I parameter is set and is non-null, substitute its value; otherwise, print .I word and exit from the shell. If .I word is omitted, the message ``parameter null or not set'' is printed. .TP .CI ${ parameter :+ word } If .I parameter is set and is non-null, substitute .IR word ; otherwise substitute nothing. .PP In the above, .I word is not evaluated unless it is to be used as the substituted string. Thus, in the following example, .C pwd is executed only if .C d is not set or is null: .IP .C echo \|${d:-\(gapwd\(ga} .PP If the colon .RC ( : ) is omitted from the above expressions, the shell only checks whether .I parameter is set or not. .PP The following parameters are automatically set by the shell: .RS .TP 15 .C # The number of positional parameters in decimal. .TP .C - Flags supplied to the shell on invocation or by the .C set command. .TP .C ? The decimal value returned by the last synchronously executed command. .TP .C $ The process id of the last separately-invoked shell (i.e., a shell arising from direct invocation or .CR #! ). This parameter is not updated for subshells arising from .CR (\|) , command substitution, etc. .TP .C ! The process number of the last background command invoked. .TP .C LINES .PD 0 .TP .C COLUMNS The number of lines and columns in the current display area. These parameters are set only under specific circumstances. See .IR Signals . .PD .RE .PP The following parameters are used by the shell: .RS .TP 15 .C HOME The default argument (home directory) for the .C cd command. .TP .C PATH The search path for commands (see ``Execution'' below). Users executing under .C rsh cannot change .CR PATH . .TP .C CDPATH The search path for the .C cd command. .TP .C MAIL If this parameter is set to the name of a mail file .I and the .C MAILPATH parameter is not set, the shell informs the user of the arrival of mail in the specified file. .TP .C MAILCHECK This parameter specifies how often (in seconds) the shell will check for the arrival of mail in the files specified by the .C MAILPATH or .C MAIL parameters. The default value is 600 seconds (10 minutes). If set to 0, the shell checks before each prompt. .TP .C MAILPATH A colon .RC ( : )-\c separated list of file names. If this parameter is set, the shell informs the user of the arrival of mail in any of the specified files. Each file name can be followed by .C % and a message to be printed when the modification time changes. The default message is .CR "you have mail" . .TP .C PS1 Primary prompt string, by default .RC `` "$ \|" ''. .TP .C PS2 Secondary prompt string, by default .RC `` "> \|" ''. .TP .C IFS Internal field separators, normally .BR space , .BR tab , and .BR new-line . .TP .C SHACCT If this parameter is set to the name of a file writable by the user, the shell writes an accounting record in the file for each shell procedure executed. Accounting routines such as .IR acctcom (1M) and .IR acctcms (1M) can be used to analyze the data collected. .TP .C SHELL When the shell is invoked, it scans the environment (see ``Environment'' below) for this name. If it is found and there is an .C r in the file name part of its value, the shell becomes a restricted shell. .C SHELL is also used by some processors to determine which command interpreter to run. .PD .RE .PP The shell gives default values to .CR PATH , .CR PS1 , .CR PS2 , .CR MAILCHECK , and .CR IFS . .C HOME and .C MAIL are set by .IR login (1). .SS Blank Interpretation After parameter and command substitution, the results of substitution are scanned for internal field separator characters (those found in .CR IFS ) and split into distinct arguments where such characters are found. Explicit null arguments .ifn (\f3"\|"\fP or \f3'\|'\fP) .ift (\f4"\|"\fP or \f4\'\|\'\fP) are retained. Implicit null arguments (those resulting from .I parameters that have no values) are removed. .SS File Name Generation Following substitution, each command .I word is processed as a pattern for file name expansion. The form of the patterns is the Pattern Matching Notation defined by .IR regexp (5). .SS Quoting The following characters have a special meaning to the shell and cause termination of a word unless quoted: .IP .CR ; , .CR & , .CR ( , .CR ) , .CR | , .CR ^ , .CR < , .CR > , .IR new-line , .IR space , .IR tab , .C # (comment) .PP A character can be .B quoted (i.e., made to stand for itself) by preceding it with a .CR \e . The pair .CI \e new-line is ignored. All characters enclosed between a pair of single quote marks .RC ( \'\|\' ), except a single quote, are quoted. Inside double quote marks .ifn (\f3"\|"\fP), .ift (\f4"\|"\fP), parameter and command substitution occurs and .C \e quotes the characters .CR \e , .CR \(ga , .ifn \f3"\fP, .ift \f4"\fP, and .CR $ . .ifn \f3"$*"\fP .ift \f4"$*"\fP is equivalent to .ifn \f3"$1 \|$2\fP \|...\f3"\fP, .ift \f4"$1 \|$2\fP \|...\f4"\fP, whereas .ifn \f3"$@"\fP .ift \f4"$@"\fP is equivalent to .ifn \f3"$1""$2"\fP .ift \f4"$1""$2"\fP \&...\|. .SS Prompting When used interactively, the shell prompts with the value of .C PS1 before reading a command. If at any time a new-line is typed and further input is needed to complete a command, the secondary prompt (i.e., the value of .CR PS2\s0 ) is issued. .SS Input/Output Before a command is executed, its input and output can be redirected using a special notation interpreted by the shell. The following can appear anywhere in a simple-command or can precede or follow a .I command and are .I not passed on to the invoked command; substitution occurs before .I word or .I digit is used: .RS .TP 14 .CI < word Use file .I word as standard input (file descriptor 0). .TP .CI > word Use file .I word as standard output (file descriptor 1). If the file does not exist then it is created; otherwise, it is truncated to zero length. .TP .CI >> word Use file .I word as standard output. If the file exists then output is appended to it (by first seeking to the end-of-file); otherwise, the file is created. .TP .CR << [ - ] \f2word\fP The shell input is read up to a line that is the same as .IR word , or to an end-of-file. The resulting document becomes the standard input. If any character of .I word is quoted, no interpretation is placed upon the characters of the document; otherwise, parameter and command substitution occurs, (unescaped) .CI \e new-line is ignored, and .C \e must be used to quote the characters .CR \e , .CR $ , .CR \(ga , and the first character of .IR word . If .C - is appended to .CR << , all leading tabs are stripped from .I word and from the document. .TP .CI <& digit Use the file associated with file descriptor .I digit as standard input. Similarly for the standard output using .CI >& digit (see .IR dup (2)). Note that .I digit must be in the range 0 through 9. .TP .C <&- The standard input is closed. Similarly for the standard output using .CR >&- . .RE .PP If any of the above is preceded by a digit in the range 0 through 9, the file descriptor that becomes associated with the file is that specified by the digit (rather than the default 0 or 1). For example: .IP .RC \&... \02>&1 .PP associates file descriptor 2 with the file currently associated with file descriptor 1. Note that this type of .SM I/O redirection is necessary when .I synchronously collecting standard output and standard error output in the same file. Redirecting standard output and standard error separately causes asynchronous collection of data at the destination (information written to standard output can be subsequently over-written by information written to standard error and vice-versa). .PP The order in which redirections are specified is significant. The shell evaluates redirections left-to-right. For example: .IP .CI ...\01> xxx \02>&1 .PP first associates file descriptor 1 with file .IR xxx . It associates file descriptor 2 with the file associated with file descriptor 1 (i.e. .IR xxx ). If the order of redirections is reversed, file descriptor 2 is associated with the terminal (assuming file descriptor 1 was originally) and file descriptor 1 is associated with file .IR xxx . .PP If a command is followed by .CR & , the default standard input for the command is the empty file .CR /dev/null . Otherwise, the environment for executing a command contains the file descriptors of the invoking shell as modified by input/output specifications. .PP Redirection of output is not allowed in the restricted shell. .SS Environment The .B environment (see .IR environ (5)) is a list of name-value pairs that is passed to an executed program in the same way as a normal argument list. The shell interacts with the environment in several ways. On invocation, the shell scans the environment and creates a parameter for each name found, giving it the corresponding value. Executed commands inherit the same environment. If the user modifies the value of any of these parameters or creates new parameters, none of these affects the environment unless the .C export command is used to bind the shell's parameter to the environment (see also .CR "set -a" ). To remove a parameter from the environment, use the .C unset command. The environment seen by any executed command is thus composed of any unmodified name-value pairs originally inherited by the shell, minus any pairs removed by .CR unset , plus any modifications or additions, all of which must be noted in .C export commands. .PP The environment for any .I simple-command can be augmented by prefixing it with one or more assignments to parameters. Thus: .IP .CI TERM=450 \0cmd .PP and .IP .CI "(export TERM; TERM=450;" \0cmd ) .PP are equivalent (as far as the execution of .I cmd is concerned). .PP If the .C -k option is set, .I all keyword arguments are placed in the environment, even if they occur after the command name. The following first prints .C "a=b c" and then .CR c : .IP .C echo \|a=b \|c .br .C set -k .br .C echo \|a=b \|c .RE .SS Signals The .C INTERRUPT and .C QUIT signals for an invoked command are ignored if the command is followed by .C & and the command does not override the .C SIGINT and .C SIGQUIT signal settings it inherited from .CR /usr/old/bin/sh ; otherwise signals have the values inherited by the shell from its parent, with the exception of signal 11 (but see also the .C trap command below). .PP If a .SM SIGWINCH signal is received, .C sh determines the new size of the display area and resets the values of the .C LINES and .C COLUMNS variables appropriately. Note that the value of either variable is modified only if that variable exists at the time .SM SIGWINCH is received. .C sh does not create these variables. Any traps set on .SM SIGWINCH are executed immediately after .C LINES and .C COLUMNS are reset. .SS Execution Each time a command is executed, the above substitutions are carried out. If the command name matches one of the .I Special Commands listed below, it is executed in the shell process. If the command name does not match a .IR "Special Command" , but matches the name of a defined function, the function is executed in the shell process (note how this differs from the execution of shell procedures). The positional parameters .CR $1 , .CR $2 , \&...\|. are set to the arguments of the function. If the command name matches neither a .I Special Command nor the name of a defined function, a new process is created and an attempt is made to execute the command via .IR exec (2). .PP The shell parameter .C PATH defines the search path for the directory containing the command. Alternative directory names are separated by a colon .RC ( : ). The default path is .C :/usr/bin (specifying the current directory and .CR /usr/bin , in that order). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If the command name contains a .C / the search path is not used (such commands are not executed by the restricted shell). Otherwise, each directory in the path is searched for an executable file. If the file has execute permissions but is not a directory or an executable object code file, it is assumed to be a script file which is a file of data for an interpreter. If the first two characters of the script file are .CR #! , .C exec (see .IR exec (2)) expects an interpreter path name to follow. .C exec then attempts to execute the specified interpreter as a separate process to read the entire script file. If a call to .C exec fails, .C /usr/old/bin/sh is spawned to interpret the script file. .PP A parenthesized command is also executed in a sub-shell. The location in the search path where a command was found is remembered by the shell (to help avoid unnecessary .CR exec s later). If the command was found in a relative directory, its location must be re-determined whenever the current directory changes. The shell forgets all remembered locations whenever the .C PATH variable is changed or the .C hash -r command is executed (see below). .SS Special Commands The following commands are executed in the shell process. Input/output redirection is permitted for these commands. File descriptor 1 is the default output location. .TP 20 .C : No effect; the command does nothing. A zero exit code is returned. .TP .CI .\0 file Read and execute commands from .I file and return. The search path specified by .C PATH is used to find the directory containing .IR file . Note that this command does not spawn another shell to execute .IR file , and thus differs in behavior and output from executing .I file as a shell script. It is not necessary that the execute permission bit be set for .IR file . .TP .CR break\0 [\|\f2n\fP\|] Exit from the enclosing .C for or .C while loop, if any. If .I n is specified, break .I n levels. .TP .CR continue\0 [\|\f2n\fP\|] Resume the next iteration of the enclosing .C for or .C while loop. If .I n is specified, resume at the .IR n -th enclosing loop. .TP .CR cd\0 [\|\f2arg\fP\|] Change the current directory to .IR arg . The shell parameter .C HOME is the default .IR arg . The shell parameter .C CDPATH defines the search path for the directory containing .IR arg . Alternative directory names are separated by a colon .RC ( : ). The default path is null (meaning the current directory). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If .I arg begins with a .C / the search path is not used. Otherwise, each directory in the path is searched for .IR arg . The .C cd command cannot be executed by .CR rsh . .TP .CR echo\0 [\|\f2arg\fP\0...\|] Echo arguments. See .IR echo (1) for usage and description. .TP .CR eval\0 [\|\f2arg\fP\0...\|] The arguments are read as input to the shell and the resulting command(s) executed. .TP .CR exec\0 [\|\f2arg\fP\0...\|] The command specified by the arguments is executed in place of this shell without creating a new process. Input/output arguments can appear and, if no other arguments are given, cause the shell input/output to be modified. .TP .CR exit\0 [\|\f2n\fP\|] Causes a shell to exit with the exit status specified by .IR n . If .I n is omitted, the exit status is that of the last command executed (an end-of-file also causes the shell to exit.) .TP .CR export\0 [\|\f2name\fP\0...\|] The given .IR name s are marked for automatic export to the .I environment of subsequently-executed commands. If no arguments are given, a list of names currently included in the environment are printed. Function names .I cannot be exported. .TP .CR hash\0 [ -r ]\0[\|\f2name\fP\0...\|] For each .IR name , the location in the search path of the command specified by .I name is determined and remembered by the shell. The .C -r option causes the shell to forget all remembered locations. If no arguments are given, information about remembered commands is presented. .I hits is the number of times a command has been invoked by the shell process. .I cost is a measure of the work required to locate a command in the search path. Certain situations require that the stored location of a command be recalculated. Commands for which this will be done are indicated by an asterisk .RC (\| * \|) adjacent to the .I hits information. .I cost is incremented when the recalculation is done. .TP .CR newgrp\0 [\|\f2arg\fP\0...\|] Equivalent to .CI "exec newgrp" " arg" \&...\|. See .IR newgrp (1) for usage and description. .TP .C pwd Print the current working directory. .CI read \0name\0\f1... One line is read from the standard input and the first word is assigned to the first .IR name , the second word to the second .IR name , etc., with leftover words assigned to the last .IR name . The return code is 0 unless an end-of-file is encountered. .IP Note that although the read command is a built-in command and is generally executed directly by the shell, this is not the case when it is used in a pipeline. In a pipeline, a new shell is forked to execute the read command with the result that any shell variables set are not available to the parent shell when the pipeline is finished. This has the effect of making the read command useless in a pipeline. .TP .CR readonly\0 [\|\f2name\fP\0...\|] The given .IR name s are marked .I readonly and the values of the these .IR name s cannot be changed by subsequent assignment. If no arguments are given, a list of all .I readonly names is printed. .TP .CR return\0 [\|\f2n\fP\|] Causes a function to exit with the return value specified by .IR n . If .I n is omitted, the return status is that of the last command executed. .TP .CR set\0 [ -\|-aefhkntuvx\0 [\|\f2arg\fP\0...\|]\|] .C set sets or unsets options, and resets the values of the positional parameters to the args given, if any. The option list is terminated by the first argument that does not begin with .C - or .CR + , or upon encountering an argument consisting entirely of .CR -\|- . Recognized options are: .RS .RS .TP .C -a Mark variables which are modified or created for export. .TP .C -e Exit immediately if a command exits with a non-zero exit status. .TP .C -f Disable file name generation .TP .C -h Locate and remember function commands as functions are defined (function commands are normally located when the function is executed). .TP .C -k All keyword arguments are placed in the environment for a command, not just those that precede the command name. .TP .C -n Read commands but do not execute them. .TP .C -t Exit after reading and executing one command. .TP .C -u Treat unset variables as an error when substituting. .TP .C -v Print shell input lines as they are read. .TP .C -x Print commands and their arguments as they are executed. .TP .C -\|- Do not change any of the options; useful when .C $1 is to be set to a string beginning with .C - or .CR + . .RE .RE .IP Using .C \+ rather than .C - causes these options to be unset. These options can also be used upon invocation of the shell. The current set of options can be found in .CR $- . The remaining arguments are positional parameters and are assigned, in order, to .CR $1 , .CR $2 , \&...\|. If no arguments are given, the values of all names are printed. .TP .CR shift\0 [\|\f2n\fP\|] The positional parameters from .C $n+1 \&... are renamed .C $1 \&...\|. If .I n is not given, it is assumed to be 1. .TP .C test Evaluate conditional expressions. See .IR test (1) for usage and description. Note that .CR [\| ... \|] in an .C if .I list is interpreted the same as .CR test\0 ...\|. There must be blanks around the brackets. .TP .C times Print the accumulated user and system times for processes run from the shell. .TP .CR trap\0 [\|\f2arg\fP\|]\0[\|\f2n\fP\|]\0... The command .I arg is a command to be read and executed when the shell receives signal(s) .IR n . (Note that .I arg is scanned once when the trap is set and once when the trap is taken.) Trap commands are executed in order of signal number. Any attempt to set a trap on a signal that was ignored on entry to the current shell is ineffective. An attempt to trap on signal 11 (memory fault) or signal 18 (death of child) produces an error. If .I arg is absent then all trap(s) .I n are reset to their original values. If .I arg is the null string, this signal is ignored by the shell and by the commands it invokes. If .I n is 0, the command .I arg is executed on exit from the shell. The .B trap command with no arguments prints a list of commands associated with each signal number. .TP .CR type\0 [\|\f2name\fP\0...\|] For each .IR name , indicate how it would be interpreted if used as a command name. .TP .CR ulimit\0 [ -f\0 [\|\f2n\fP\|]\|] If the .CI -f " n" option is used, a size limit of .I n blocks is imposed on files written by child processes (files of any size can be read). If .I n is not specified, the current limit is printed. If no option is specified, .C -f is assumed. .TP .CR umask\0 [\|\f2nnn\fP\|] The user file-creation mask is set to .I nnn (see .IR umask (2)). If .I nnn is omitted, the current value of the mask is printed. .TP .CR unset\0 [\|\f2name\fP\0...\|] For each .IR name , remove the corresponding variable or function. The variables .CR PATH , .CR PS1 , .CR PS2 , .CR MAILCHECK , and .C IFS cannot be unset. .TP .CR wait \0[\|\f2n\fP\|] Wait for the specified process and report its termination status. If .I n is not given all currently active child processes are waited for and the return code is zero. .PP .SS Invocation Options can be specified in a single argument or in multiple arguments, but in all cases each option argument must begin with .CR - . (All options except .CR c , .CR s , .CR i , and .C r can also be prefaced with a .CR + , which turns off the associated option or options, but this is redundant when invoking a new shell because all options are turned off by default). .PP If the first character of argument zero is .CR - , commands are initially read from .CR /etc/profile , then from .CR $HOME/.profile , if the files exist. Thereafter, commands are read as described below. .PP The options below are interpreted by the shell at invocation (thus they cannot be used with the .C set command). Unless the .C -c or .C -s option is specified, the first non-option argument is assumed to be the name of a file containing commands, and the remaining arguments are passed as positional parameters to that command file. .RS .TP 10 .CI -c "\| string" If the .C -c option is present then commands are read from .IR string . .TP .C -s If the .C -s option is present or if no arguments remain, commands are read from the standard input. Any remaining arguments specify the positional parameters. Shell output (except for "Special Commands" ) is written to file descriptor 2. .TP .C -i If the .C -i option is present or if the shell input and output are attached to a terminal, this shell is .IR interactive . In this case .SM TERMINATE is ignored (so that .C kill 0 does not kill an interactive shell) and .SM INTERRUPT is caught and ignored (so that .C wait is interruptible). In all cases, .SM QUIT is ignored by the shell. .TP .C -r If the .C -r option is present the shell is a restricted shell. .RE .PP The remaining options and arguments are described under the .C set command above. .ifn .SS rsh Only .ift .SS \f4rsh\fP Only .C rsh is used to set up login names and execution environments whose capabilities are more controlled than those of the standard shell. The actions of .C rsh are identical to those of .CR sh , except that the following are disallowed: .RS .TP 3 \(bu Changing directory (see .IR cd (1)), .PD 0 .TP \(bu Setting the value of .CR $PATH, .TP \(bu Specifying path or command names containing .CR / , .TP \(bu Redirecting output .RC ( > and .CR >> ). .PD .RE .PP The restrictions above are enforced after .C .profile is interpreted. .PP When a command to be executed is found to be a shell procedure, .C rsh invokes .C sh to execute it. Thus, it is possible to provide to the end-user shell procedures that have access to the full power of the standard shell, while imposing a limited menu of commands; this scheme assumes that the end-user does not have write and execute permissions in the same directory. .PP The net effect of these rules is that the writer of the .C .profile has complete control over user actions, by performing guaranteed setup actions and leaving the user in an appropriate directory (probably .I not the login directory). .PP The system administrator often sets up a directory of commands (such as .CR /usr/rbin ) that can be safely invoked by .CR rsh . Commands such as .CR vi , .CR sh , .CR ksh , .CR csh , and such that can break .C rsh restrictions should not be included in that directory. Some systems also provide a restricted editor .CR red . .SH EXTERNAL INFLUENCES .SS Environment Variables .SM LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. .PP .SM LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as letters, and the characters matched by character class expressions in pattern matching notation. .PP .SM LANG determines the language in which messages are displayed. .PP If .SM LC_COLLATE or .SM LC_CTYPE is not specified in the environment or is set to the empty string, the value of .SM LANG is used as a default for each unspecified or empty variable. If .SM LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .SM LANG. If any internationalization variable contains an invalid setting, .C sh behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE The error codes returned by the shell are: .RS .TP 5 .B 0 Success. .PD 0 .TP .B 1 Built-in command failure (see .IR Special Commands ). .TP .B 2 Syntax error. .TP .B 3 Signal received that is not trapped. .PD .RE .PP If the shell is non-interactive, it terminates and passes one of the above as its exit status. If it is interactive, it does not terminate, but .C $? is set to one of the above values. .PP Whenever a child process of the shell dies due to a signal, the shell returns an exit status of 80 hexadecimal plus the number of the signal. .\".SH EXAMPLES .\" None appropriate. .SH WARNINGS If a command is executed and a command having the same name is installed in a directory in the search path before the directory where the original command was found, the shell continues to .C exec the original command. Use the .C hash command to correct this situation. .PP When the shell encounters .CR >> , it does not open the file in append mode. Instead, it opens the file for writing and seeks to the end. .PP If you move the current directory or one above it, .C pwd cannot give the correct response. Use the .C cd command with a full path name to correct this situation. .PP The command .C readonly (without arguments) produces the same output as the command .CR export . .PP Failure (non-zero exit status) of a special command preceding a .C |\|| symbol prevents the .I list following .C |\|| from executing. .PP In an international environment, character ordering is determined by the setting of .SM LC_COLLATE, rather than by the binary ordering of character values in the machine collating sequence. This brings with it certain attendant dangers, particularly when using range expressions in file-name-generation patterns. For example, the command, .IP .C rm [a-z]* .PP might be expected to match all file names beginning with a lowercase alphabetic character. However, if dictionary ordering is specified by .SM LC_COLLATE, it also matches file names beginning with an uppercase character (as well as those beginning with accented letters). Conversely, it fails to match letters collated after .C z in languages such as Norwegian. .PP The correct (and safe) way to match specific character classes in an international environment is to use a pattern of the form: .IP .C rm [[:lower:]]* .PP This uses .SM LC_CTYPE to determine character classes and works predictably for all supported languages and codesets. For shell scripts produced on non-internationalized systems (or without consideration for the above dangers), it is recommended that they be executed in a non-\c .SM NLS environment. This requires that .SM LANG, LC_COLLATE, etc., be set to "C" or not set at all. .PP .C sh implements command substitution by creating a pipe between itself and the command. If the root file system is full, the substituted command cannot write to the pipe. As a result, the shell receives no input from the command, and the result of the substitution is null. In particular, using command substitution for variable assignment under such circumstances results in the variable being silently assigned a .SM NULL value. .PP The signal .SM SIGSEGV should not be blocked when executing .CR sh . .PP .C sh reserves file descriptor 59 for internal use. Reducing the number of available file descriptors below 60 causes .C sh to fail. .PP Each time a function is executed in a shell script, any arguments given to the function overwrite the values of the positional parameters for the entire script. If the values of the positional parameters must be preserved, they must be explicitly saved before each function call. .SH AUTHOR .C sh was developed by AT&T and HP. .SH FILES .C $HOME/.profile .br .C /dev/null .br .C /etc/profile .br .C /tmp/sh* .SH SEE ALSO cd(1), echo(1), env(1), login(1), newgrp(1), pwd(1), test(1), umask(1), acctcms(1M), acctcom(1M), dup(2), exec(2), fork(2), pipe(2), ulimit(2), umask(2), wait(2), a.out(4), profile(4), environ(5), lang(5), regexp(5), signal(5). .PP .I Bourne Shell tutorial in .I "Shells Users Guide" . .SH STANDARDS CONFORMANCE .CR . ": SVID2, SVID3, XPG2, XPG3" .PP .CR : ": SVID2, SVID3, XPG2, XPG3" .PP .CR break ": SVID2, SVID3, XPG2, XPG3" .PP .CR case ": SVID2, SVID3, XPG2, XPG3" .PP .CR continue ": SVID2, SVID3, XPG2, XPG3" .PP .CR eval ": SVID2, SVID3, XPG2, XPG3" .PP .CR exec ": SVID2, SVID3, XPG2, XPG3" .PP .CR exit ": SVID2, SVID3, XPG2, XPG3" .PP .CR export ": SVID2, SVID3, XPG2, XPG3" .PP .CR for ": SVID2, SVID3, XPG2, XPG3" .PP .CR if ": SVID2, SVID3, XPG2, XPG3" .PP .CR read ": SVID2, SVID3, XPG2, XPG3" .PP .CR return ": SVID2, SVID3, XPG2, XPG3" .PP .CR rsh ": SVID2, SVID3" .PP .CR set ": SVID2, SVID3, XPG2, XPG3" .PP .CR sh ": SVID2, SVID3, XPG2, XPG3" .PP .CR shift ": SVID2, SVID3, XPG2, XPG3" .PP .CR time ": SVID2, SVID3, XPG2, XPG3" .PP .CR trap ": SVID2, SVID3, XPG2, XPG3" .PP .CR unset ": SVID2, SVID3, XPG2, XPG3" .PP .CR until ": SVID2, SVID3, XPG2, XPG3" .PP .CR while ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4sh\f1 \- shell, the standard command programming language@@@\f3sh(1)\f1 .\" index@\f4rsh\f1 \- rshell, the restricted command programming language@@@\f3sh(1)\f1 .\" index@Bourne shell@@@\f3sh(1)\f1 .\" index@shell, Bourne@@@\f3sh(1)\f1 .\" index@\f4rsh\f1 \- restricted shell command programming language@@@\f3sh(1)\f1 .\" index@\f4break\f1 \- exit from enclosing for/next loop@@@\f3sh(1)\f1 .\" index@\f4cd\f1 \- change working directory@@@\f3sh(1)\f1 .\" index@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@\f3sh(1)\f1 .\" index@\f4echo\f1 \- echo (print) arguments@@@\f3sh(1)\f1 .\" index@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@\f3sh(1)\f1 .\" index@\f4exec\f1 \- execute command without creating new process@@@\f3sh(1)\f1 .\" index@\f4exit\f1 \- exit shell with exit status@@@\f3sh(1)\f1 .\" index@\f4export\f1 \- export variable names to environment of subsequent commands@@@\f3sh(1)\f1 .\" index@\f4hash\f1 \- remember command location in search path@@@\f3sh(1)\f1 .\" index@\f4newgrp\f1 \- equivalent to \f3exec newgrp\f1@@@\f3sh(1)\f1 .\" index@\f4pwd\f1 \- working directory name@@@\f3sh(1)\f1 .\" index@\f4read\f1 \- read line from standard input@@@\f3sh(1)\f1 .\" index@\f4readonly\f1 \- mark \f2name\f1 as read-only@@@\f3sh(1)\f1 .\" index@\f4return\f1 \- exit function with return value@@@\f3sh(1)\f1 .\" index@\f4set\f1 \- set/define options and arguments@@@\f3sh(1)\f1 .\" index@\f4shift\f1 \- shift positional parameters to next lower position@@@\f3sh(1)\f1 .\" index@\f4time\f1 \- print accumulated shell and children process times@@@\f3sh(1)\f1 .\" index@\f4times\f1 \- print accumulated user and system process times@@@\f3sh(1)\f1 .\" index@\f4trap\f1 \- execute command upon receipt of signal@@@\f3sh(1)\f1 .\" index@\f4type\f1 \- show interpretation of \f2name\f1 as if a command@@@\f3sh(1)\f1 .\" index@\f4ulimit\f1 \- impose file size limit for child processes@@@\f3sh(1)\f1 .\" index@\f4umask\f1 \- set permissions mask for creating new files@@@\f3sh(1)\f1 .\" index@\f4unset\f1 \- remove definition/setting of options and arguments@@@\f3sh(1)\f1 .\" index@\f4wait\f1 \- wait for process and report termination status@@@\f3sh(1)\f1 .\" .\" toc@\f3sh(1)\f1:\0\0\f4sh\f1, \f4rsh\f1@@@shell, the standard/restricted command programming language .\" toc@\f4rsh\f1 \- restricted shell command programming language@@@see \f3sh(1)\f1 .\" toc@\f4break\f1 \- exit from enclosing for/next loop@@@see \f3sh(1)\f1 .\" toc@\f4cd\f1 \- change working directory@@@see \f3sh(1)\f1 .\" toc@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@see \f3sh(1)\f1 .\" toc@\f4echo\f1 \- echo (print) arguments@@@see \f3sh(1)\f1 .\" toc@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@see \f3sh(1)\f1 .\" toc@\f4exec\f1 \- execute command without creating new process@@@see \f3sh(1)\f1 .\" toc@\f4exit\f1 \- exit shell with exit status@@@see \f3sh(1)\f1 .\" toc@\f4export\f1 \- export variable names to environment of subsequent commands@@@see \f3sh(1)\f1 .\" toc@\f4hash\f1 \- remember command location in search path@@@see \f3sh(1)\f1 .\" toc@\f4newgrp\f1 \- equivalent to \f3exec newgrp\f1@@@see \f3sh(1)\f1 .\" toc@\f4pwd\f1 \- working directory name@@@see \f3sh(1)\f1 .\" toc@\f4read\f1 \- read line from standard input@@@see \f3sh(1)\f1 .\" toc@\f4readonly\f1 \- mark \f2name\f1 as read-only@@@see \f3sh(1)\f1 .\" toc@\f4return\f1 \- exit function with return value@@@see \f3sh(1)\f1 .\" toc@\f4set\f1 \- set/define options and arguments@@@see \f3sh(1)\f1 .\" toc@\f4shift\f1 \- shift positional parameters to next lower position@@@see \f3sh(1)\f1 .\" toc@\f4time\f1 \- print accumulated shell and children process times@@@see \f3sh(1)\f1 .\" toc@\f4times\f1 \- print accumulated user and system process times@@@see \f3sh(1)\f1 .\" toc@\f4trap\f1 \- execute command upon receipt of signal@@@see \f3sh(1)\f1 .\" toc@\f4type\f1 \- show interpretation of \f2name\f1 as if a command@@@see \f3sh(1)\f1 .\" toc@\f4ulimit\f1 \- impose file size limit for child processes@@@see \f3sh(1)\f1 .\" toc@\f4umask\f1 \- set permissions mask for creating new files@@@see \f3sh(1)\f1 .\" toc@\f4unset\f1 \- remove definition/setting of options and arguments@@@see \f3sh(1)\f1 .\" toc@\f4wait\f1 \- wait for process and report termination status@@@see \f3sh(1)\f1 .\" .\" links@sh-bourne.1 rsh-bourne.1 .\" .\" fileset_database@sh-bourne.1 USER-CMDS-MAN .\" $Header: sh-posix.1,v 80.1 96/10/17 10:33:49 ssa Exp $ .\" DSDe430514, DSDe430222, DSDe434580: .\" The posix shell was not compliant with the POSIX specification .\" in two ways: the handling of traps within functions was incorrect, .\" and several of the builtin commands were incorrectly causing the shell .\" to exit when they contained syntax errors. This is appropriate for .\" special builtins, but not for regular builtins. When the changes were .\" made to the software, it was necessary to change the manpage to .\" accurately reflect how traps work, and to properly identify which .\" builtin commands are regular and which are special. (In many cases, .\" the special builtin commands are different than those in ksh.) .\" Some minor technical inaccuracies were also corrected. .TA s .TH sh-posix 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.10: April 1997 .SH NAME sh, rsh \- standard and restricted POSIX.2-conformant command shells .SH SYNOPSIS .CR sh .RC [{ \- \(or + }\c .CR aefhikmnprstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [ \-c .IR string ] .IR arg ]...\& .PP .CR rsh .RC [{ \- \(or + }\c .CR aefhikmnprstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [ \-c .IR string ] .RI [ arg ]...\& .SS Remarks This shell is intended to conform to the shell specification of the POSIX.2 .I Shell and Utility standards. Check any standards conformance documents shipped with your system for information on the conformance of this shell to any other standards. .SS List of Subheadings in DESCRIPTION .\" .SS lines under DESCRIPTION (commands are vi/ex) .\" Extract header lines; copy to eof ":g/\.S[SH]/co$: .\" Delete extraneous leading and trailing headings .\" Delete .SS ":.,$s/....//" .\" Form into columns ":.,$!pr -3 -t -s@" .\" Replace pr tabs with blanks ":.,$s/[[:space:]]/ /g" .\" Move into place below. .TS tab(@); l l l . Shell Invocation@Tilde Substitution@Environment Options@Command Substitution@Functions rsh Restrictions@Parameter Substitution@Jobs Definitions@Blank Interpretation@Signals Commands@File Name Generation@Execution Simple Commands@Quoting@Command Reentry Compound Commands@Arithmetic Evaluation@Command Line Editing Special Commands@Prompting@emacs Editing Mode Comments@Conditional Expressions@vi Editing Mode Aliasing@Input/Output .TE .SH DESCRIPTION .CR sh is a command programming language that executes commands read from a terminal or a file. .PP .CR rsh is a restricted version of .CR sh . See the "rsh Restrictions" subsection below. .SS Shell Invocation If the shell is invoked by an .CI exec * () system call and the first character of argument zero (shell parameter .CR 0 ) is dash .RC ( \- ), the shell is assumed to be a login shell and commands are read first from .CR /etc/profile , then from either .CR .profile in the current directory or .CR $HOME/.profile if either file exists, and finally from the file named by performing parameter substitution on the value of the environment parameter .CR ENV , if the file exists. If the .CR \-s option is not present and an .I arg is, a path search is performed on the first .I arg to determine the name of the script to execute. When running .CR sh with .IR arg , the script .I arg must have read permission and any .CR setuid and .CR setgid settings will be ignored. Commands are read as described below. .PP Shell output, except for the output of some of the commands listed in the "Special Commands" subsection, is written to standard error (file descriptor 2). .SS Options The following options are interpreted by the shell when it is invoked. .TP 15 .CI \-c \0string Read commands from .IR string . .TP .CR \-i If .CR \-i is present or if the shell input and output are attached to a terminal (as reported by .CR tty() ), the shell is interactive. In this case .CR SIGTERM is ignored and .CR SIGINT is caught and ignored (so that .CR wait is interruptible). In all cases, .CR SIGQUIT is ignored by the shell. See .IR signal (5). .TP .CR \-r The shell is a restricted shell. .TP .CR \-s If .CR \-s is present or if no arguments remain, commands are read from the standard input. .PP The remaining options and arguments are described under the .CR set command in the "Special Commands" subsection. .SS rsh Restrictions .CR rsh is used to set up login names and execution environments where capabilities are more controlled than those of the standard shell. The actions of .CR rsh are identical to those of .CR sh , except that the following are forbidden: .RS .TP 3 .PD 0 \(bu Changing directory (see the .CR cd special command and .IR cd (1)) .TP \(bu Setting the value of .CR SHELL , .CR ENV , or .CR PATH .TP \(bu Specifying path or command names containing .CR / .TP \(bu Redirecting output .RC ( > , .CR >| , .CR <> , and .CR >> ) .PD .RE .PP The restrictions above are enforced after the .CR .profile and .CR ENV files are interpreted. .PP When a command to be executed is found to be a shell procedure, .CR rsh invokes .CR sh to execute it. Thus, the end-user is provided with shell procedures accessible to the full power of the standard shell, while being restricted to a limited menu of commands. This scheme assumes that the end-user does not have write and execute permissions in the same directory. .PP These rules effectively give the writer of the .CR .profile file complete control over user actions, by performing guaranteed set-up actions and leaving the user in an appropriate directory (probably not the login directory). .PP The system administrator often sets up a directory of commands (usually .CR /usr/rbin ) that can be safely invoked by .CR rsh . HP-UX systems provide a restricted editor .CR red (see .IR ed (1)), suitable for restricted users. .SS Definitions .TP 20 .B metacharacter One of the following characters: .IP .CR "; & ( ) | < >" \0newline\0space\0tab .TP .B blank A tab or a space. .TP .B identifier A sequence of letters, digits, or underscores starting with a letter or underscore. Identifiers are used as names for .BR functions and .BR "named parameters" . .TP .B word A sequence of .B characters separated by one or more nonquoted .BR metacharacters . .TP .BR command A sequence of characters in the syntax of the shell language. The shell reads each command and carries out the desired action, either directly or by invoking separate utilities. .TP .B "special command" A command that is carried out by the shell without creating a separate process. Except for documented side effects, most special commands can be implemented as separate utilities. .TP .CR # Comment delimiter. A word beginning with .CR # and all following characters up to a newline are ignored. .TP .B parameter An .BR identifier , a decimal number, or one of the characters .CR ! , .CR # , .CR $ , .CR * , .CR \- , .CR ? , .CR @ , and .CR _ . See the "Parameter Substitution" subsection. .TP .B "named parameter" A .B parameter that can be assigned a value. See the "Parameter Substitution" subsection. .TP .B variable A .BR parameter . .TP .B "environment variable" A .BR parameter that is known outside the local shell, usually by means of the .CR export special command. .SS Commands A command can be a simple command that executes an executable file, a special command that executes within the shell, or a compound command that provides flow of control for groups of simple, special, and compound commands. .SS Simple Commands A simple command is a sequence of blank-separated words that may be preceded by a parameter assignment list. (See the "Environment" subsection). The first word specifies the name of the command to be executed. Except as specified below, the remaining words are passed as arguments to the invoked command. The command name is passed as argument .CR 0 (see .IR exec (2)). The .I value of a simple-command is its exit status if it terminates normally, or .CI 128+ errorstatus if it terminates abnormally (see .IR signal (5) for a list of .I errorstatus values). .PP A .B pipeline is a sequence of one or more commands separated by a bar .RC ( | ) and optionally preceded by an exclamation mark .RC ( ! ). The standard output of each command but the last is connected by a pipe (see .IR pipe (2)) to the standard input of the next command. Each command is run as a separate process; the shell waits for the last command to terminate. If .CR !\& does not precede the pipeline, the exit status of the pipeline is the exit status of the last command in the pipeline. Otherwise, the exit status of the pipeline is the logical negation of the exit status of the last command in the pipeline. .PP A .I list is a sequence of one or more pipelines separated by .CR ; , .CR & , .CR && , or .CR || , and optionally terminated by .CR ; , .CR & , or .CR |& . .RS .TP .CR ;\& Causes sequential execution of the preceding pipeline. An arbitrary number of newlines can appear in a .I list, instead of semicolons, to delimit commands. .TP .CR & Causes asynchronous execution of the preceding pipeline (that is, the shell does not wait for that pipeline to finish). .TP .CR |& Causes asynchronous execution of the preceding command or pipeline with a two-way pipe established to the parent shell. The standard input and output of the spawned command can be written to and read from by the parent shell using the .CR \-p option of the special commands .CR read and .CR print . .TP .CR && Causes the .I list following it to be executed only if the preceding pipeline returns a zero value. .TP .CR || Causes the .I list following it to be executed only if the preceding pipeline returns a nonzero value. .RE .PP Of these five symbols, .CR ; , .CR & , and .CR |& have equal precedence, which is lower than that of .CR && and .CR || . The symbols .CR && and .CR || also have equal precedence. .SS Compound Commands Unless otherwise stated, the value returned by a compound command is that of the last simple command executed in the compound command. The .CR ;\& segment separator can be replaced by one or more newlines. .PP The following keywords are recognized only as the first word of a command and when not quoted: .nf .RS .IP .C "! } elif for then" .C "[[ case else function time" .C "]] do esac if until" .C "{ done fi select while" .fi .RE .PP A compound command is one of the following. .PP .ne 3v .CR case \f2\0word\c .CR \0in \0[\|[ ; ]\0[ ( ]\c .IC \0pattern\0\f1[ | \0pattern\f1]... ) \0list\0\c .CR ;; ]...\0 ;\0esac .IP Execute the .I list associated with the first .I pattern that matches .IR word . The form of the patterns is identical to that used for file name generation (see the "File Name Generation" subsection). The .CR ;;\& case terminator cannot be replaced by newlines. .PP .ne 3v .CI for \0identifier\f1\0[ in \0word\f1\0...]\0\c .CR ;\0do \0\f2list\0 ;\0done .IP Set .I identifier to each .I word in sequence and execute the .CR do .IR list . If .CR in .IR word .RI ...\& is omitted, set .I identifier to each set positional parameter instead. See the "Parameter Substitution" subsection. Execution ends when there are no more positional parameters or words in the list. .PP .ne 4v .CI function \0identifier\0 { \0list\0 ;\0} .br .IC identifier \0()\0{ \0list\0 ;\0} .IP Define a function named by .IR identifier . A function is called by executing its identifier as a command. The body of the function is the .I list of commands between .CR { and .CR } . See the "Functions" subsection. .PP .ne 3v .CI if \0list\0 ;\0then \0list\0 ; \0\f1[\c .CI elif \0list\0 ;\0then \0list\0 ; \f1]...\&\0[\c .CI else \0list\0 ; \f1]\0 fi .IP Execute the .CR if .I list and, if its exit status is zero, execute the first .CR then .IR list . Otherwise, execute the .CR elif .I list (if any) and, if its exit status is zero, execute the next .CR then .IR list . Failing that, execute the .CR else .I list (if any). If no .CR else .I list or .CR then .I list is executed, .CR if returns a zero exit status. .PP .ne 3v .CI select \0identifier\0\f1[ in \0word\f1\0...\&]\0 ;\0do \0list\0\c .CI ;\0done .IP Print the set of .IR word s on standard error (file descriptor 2), each preceded by a number. If .CI in .IR word .RI ...\& is omitted, print the positional parameters instead (see the "Parameter Substitution" subsection). Print the .CR PS3 prompt and read a line from standard input into the parameter .CR REPLY . If this line consists of the number of one of the listed .IR word s, set .I identifier to the corresponding .IR word , execute .IR list , and repeat the .CR PS3 prompt. If the line is empty, print the selection list again, and repeat the .CR PS3 prompt. Otherwise, set .I identifier to null, execute .IR list , and repeat the .CR PS3 prompt. The select loop repeats until a .CR break special command or end-of-file is encountered. .PP .ne 3v .CI time \0pipeline .IP Execute the .I pipeline and print the elapsed time, the user time, and the system time on standard error. See also .IR time (1). .PP .ne 3v .CI "until\0" list "\0;\0do\0" list "\0;\0done" .IP Execute the .CR until .IR list . If the exit status of the last command in the list is nonzero, execute the .CR do .IR list and execute the .CR until .IR list again. When the exit status of the last command in the .CR until .I list is zero, terminate the loop. If no commands in the .CR do .I list are executed, .CR until returns a zero exit status. .PP .ne 3v .CI "while\0" list "\0;\0do\0" list "\0;\0done" .IP Execute the .CR while .IR list . If the exit status of the last command in the list is zero, execute the .CR do .IR list and execute the .CR while .IR list again. When the exit status of the last command in the .CR while .I list is nonzero, terminate the loop. If no commands in the .CR do .I list are executed, .CR while returns a nonzero exit status. .PP .ne 3v .CI ( "\0list\0" ) .IP Execute .I list in a separate environment. If two adjacent open parentheses are needed for nesting, a space must be inserted between them to avoid arithmetic evaluation. .PP .ne 3v .CI { "\0list\0" ";\0}" .IP Execute .IR list , but not in a separate environment. Note that .CR { is a keyword and requires a trailing blank to be recognized. .PP .ne 3v .CI [[ "\0expression\0" ]] .IP Evaluate .I expression and return a zero exit status when .I expression is true. See the "Conditional Expressions" subsection for a description of .IR expression . Note that .CR [[ and .CR ]] are keywords and require blanks between them and .IR expression . .SS Special Commands Special commands are simple commands that are executed in the shell process. They permit input/output redirection. Unless otherwise indicated, file descriptor 1 (standard output) is the default output location and the exit status, when there are no syntax errors, is zero. .PP Commands that are marked with \(dg are treated specially in the following ways: .RS .TP 3 .PD 0 1. Variable assignment lists preceding the command remain in effect when the command completes. .TP 2. I/O redirections are processed after variable assignments. .TP 3. Errors cause a script that contains them to abort. .PD .RE .PP Words following commands marked with \(dd that are in the format of a variable assignment are expanded with the same rules as a variable assignment. This means that tilde substitution is performed after the .CR = sign and word-splitting and file-name generation are not performed. .PP .ne 3v \(dg .CR : \0[\f2arg\f1]...\& .IP (colon)\0 Only expand parameters. A zero exit status is returned. .PP .ne 3v \(dg .CI . \0file\f1\0[\f2arg\f1]...\& .IP (period)\0 Read and execute commands from .I file and return. The commands are executed in the current shell environment. The search path specified by .CR PATH is used to find the directory containing .IR file . If any arguments .I arg are given, they become the positional parameters. Otherwise, the positional parameters are unchanged. The exit status is the exit status of the last command executed. .PP .ne 3v \(dd .CR alias \0[ \-tx ]\0[\f2name\f1[\c .CI = value\f1]\|]...\& .IP With .IC name = value specified, define .I name as an alias and assign it the value .IR value . A trailing space in .I value causes the next word to be checked for alias substitution. .IP With .IC name = value omitted, print the list of aliases in the form .IC name = value on standard output. .IP With .I name specified without .CI = value\f1, print the specified alias. .IP With .CR \-t , set tracked aliases. The value of a tracked alias is the full path name corresponding to the given .IR name . The value of a tracked alias becomes undefined when the value of .CR PATH is reset, but the alias remains tracked. With .IC name = value omitted, print the list of tracked aliases in the form .IC name = pathname on standard output. .IP With .CR \-x , set exported aliases. An exported alias is defined across subshell environments. With .IC name = value omitted, print the list of exported aliases in the form .IC name = value on standard output. .IP Alias returns true unless a .I name is given for which no alias has been defined. .PP .ne 3v .CR bg \0[\f2job\f1]...\& .IP Put the specified .I jobs into the background. The current job is put in the background if .I job is unspecified. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v \(dg .CR break \0[\f2n\f1] .IP Exit from the enclosing .CR for , .CR select , .CR until , or .CR while loop, if any. If .I n is specified, exit from .I n levels. .PP .ne 4v .CR cd \0[ \-L \(or \-P ]\0[\f2arg\f1] .br .CI cd \0old\0new .IP In the first form, change the current working directory .RC ( PWD ) to .IR arg . If .I arg is .CR \- , the directory is changed to the previous directory .RC ( OLDPWD ). .IP With .CR \-L (default), preserve logical naming when treating symbolic links. .CR "cd \-L ..\&" moves the current directory one path component closer to the root directory. .IP With .CR \-P , preserve the physical path when treating symbolic links. .CR "cd \-P ..\&" changes the working directory to the actual parent directory of the current directory. .IP The shell parameter .CR HOME is the default .IR arg . The parameter .CR PWD is set to the current directory. .IP The shell parameter .CR CDPATH defines the search path for the directory containing .IR arg . Alternative directory names are separated by a colon .RC ( : ). If .CR CDPATH is null or undefined, the default value is the current directory. Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If .I arg begins with a .CR / , the search path is not used. Otherwise, each directory in the path is searched for .IR arg . See also .IR cd (1). .IP The second form of .CR cd substitutes the string .I new for the string .I old in the current directory name, .CR PWD , and tries to change to this new directory. .PP .ne 3v .CR command \0[\f2arg\f1]...\& .IP Treat .I arg as a command, but disable function lookup on .IR arg . See .IR command (1) for usage and description. .PP .ne 3v \(dg .CR continue \0[\f2n\f1] .IP Resume the next iteration of the enclosing .CR for , .CR select , .CR until , or .CR while loop. If .I n is specified, resume at the .IR n th enclosing loop. .PP .ne 3v .CR echo \0[\f2arg\f1]...\& .IP Print .I arg on standard output. See .IR echo (1) for usage and description. See also the .CR print special command. .PP .ne 3v \(dg .CR eval \0[\f2arg\f1]...\& .IP Read the arguments as input to the shell and execute the resulting commands. Allows parameter substitution for keywords and characters that would otherwise be unrecognized in the resulting commands. .PP .ne 3v \(dg .CR exec \0[\f2arg\f1]...\& .IP Parameter assignments remain in effect after the command completes. If .I arg is given, execute the command specified by the arguments in place of this shell without creating a new process. Input/output arguments may appear and affect the current process. If no arguments are given, modify file descriptors as prescribed by the input/output redirection list. In this case, any file descriptor numbers greater than 2 that are opened with this mechanism are closed when another program is invoked. .PP .ne 3v \(dg .CR exit \0[\f2n\f1] .IP Exit from the shell with the exit status specified by .IR n . If .I n is omitted, the exit status is that of the last command executed. An end-of-file also causes the shell to exit, except when a shell has the .CR ignoreeof option set. (See the .CR set special command.) .PP .ne 4v \(dg\(dd .CR export \0[\f2name\f1[ = \f2value\f1]\|]...\& .br \(dg\(dd .CR export\0\-p .IP Mark the given variable .IR name s for automatic export to the environment of subsequently executed commands. Optionally, assign values to the variables. .IP With .CR \-p , write the names and values of all exported variables to standard output, in a format with the proper use of quoting, so that it is suitable for re-input to the shell as commands that achieve the same exporting results. .PP .ne 6v .CR fc \0[ \-r ]\0[ \-e \0\f2ename\f1]\0[\f2first\f1\0[\f2last\f1]\|] .br .CR fc\0\-l \0[ \-nr ]\0[\f2first\f1\0[\f2last\f1]\|] .br .CR fc\0\-s \0[\f2old\f1 = \f2new\f1]\0[\f2first] .br .CR fc\0\-e\0\- \0[\f2old\f1 = \f2new\f1]\0[\f2command\f1] .IP List, or edit and reexecute, commands previously entered to an interactive shell. A range of commands from .I first to .I last is selected from the last .CR HISTSIZE commands typed at the terminal. The arguments .I first and .I last can be specified as a number or string. A given string is used to locate the most recent command. A negative number is used to offset the current command number. .IP With .CR \-l , list the commands on standard output. Without .CR \-l , invoke the editor program .I ename on a file containing these keyboard commands. If .I ename is not supplied, the value of the parameter .CR FCEDIT (default .CR /usr/bin/ed ) is used as the editor. Once editing has ended, the commands (if any) are executed. If .I last is omitted, only the command specified by .I first is used. If .I first is not specified, the default is the previous command for editing and \(mi16 for listing. .IP With .CR \-r , reverse the order of the commands. .IP With .CR \-n , suppress command numbers when listing. .IP With .CR \-s , reexecute the command without invoking an editor. .IP The .IC old = new argument replaces the first occurrence of string .IC old in the command to be reexecuted by the string .IR new . .PP .ne 3v .CR fg \0[\f2job\f1]...\& .IP Bring each .I job into the foreground in the order specified. If no .I job is specified, bring the current job into the foreground. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v .CR getopts \0\f2optstring\0name\f1\0[\f2arg\f1]...\& .IP Parse the argument list, or the positional parameters if no arguments, for valid options. On each execution, return the next option in .IR name . See .IR getopts (1) for usage and description. .IP An option begins with a .CR + or a .CR \- . An argument not beginning with .CR + or .CR \- , or the argument .CR \-\- , ends the options. .I optstring contains the letters that .CR getopts recognizes. If a letter is followed by a .CR : , that option is expected to have an argument. The options can be separated from the argument by blanks. .IP For an option specified as .CI \- letter\f1, .I name is set to .IR letter . For an option specified as .CI + letter\f1, .I name is set to .CI + letter\f1. The index of the next .I arg is stored in .CR OPTIND . The option argument, if any, is stored in .CR OPTARG . If no option argument is found, or the option found does not take an argument, .CR OPTARG is unset. .IP A leading .CR :\& in .I optstring causes .CR getopts to store the letter of an invalid option in .CR OPTARG , and to set .I name to .CR ?\& for an unknown option and to .CR :\& when a required option argument is missing. Otherwise, .CR getopts prints an error message. The exit status is nonzero when there are no more options. .PP .ne 4v \(dd .CR hash \0[\f2utility\f1]...\& .br \(dd .CR hash\0\-r .IP Affect the way the current shell environment remembers the locations of utilities. With .IR utility , add utility locations to a list of remembered locations. With no arguments, print the contents of the list. With .CR \-r , forget all previously remembered utility locations. .PP .ne 3v .CR jobs \0[ \-lnp ]\0[\f2job\f1]...\& .IP List information about each given job, or all active jobs if .I job is not specified. With .CR \-l , list process IDs in addition to the normal information. With .CR \-n , display only jobs that have stopped or exited since last notified. With .CR \-p , list only the process group. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 5v .CR kill \0[ \-s \0\f2signal\f1]\0\f2process\f1\0...\& .br .CR kill\0\-l .br .CR kill \0[ \- \f2signal\f1]\0\f2process\f1\0...\& .IP Send either signal 15 .RC ( SIGTERM , terminate) or the specified .I signal to the specified jobs or processes. See .IR kill (1) for usage and description. .IP With .CR \-l , list the signal names and numbers. .PP .ne 4v .CI let \0arg\f1\0... .br .CI (( \0arg\f1\0... )) .IP Evaluate each .I arg as a separate arithmetic expression. See the "Arithmetic Evaluation" subsection for a description of arithmetic expression evaluation. The exit status is 0 if the value of the last expression is nonzero, and 1 otherwise. .PP .ne 3v \(dg .CR newgrp \0[ \- ]\0[\f2group\f1] .IP Replace the current shell with a new one having .I group as the user's group. The default group is the user's login group. With .CR \- , the user's .CR .profile and .CR $ENV files are also executed. See .IR newgrp (1) for usage and description. Equivalent to .CI "exec\0newgrp" "\0arg\0\f1...." .PP .ne 3v .CR print \0[ \-nprRsu [\f2n\f1]\|]\0[\f2arg\f1]...\& .IP The shell output mechanism. With no options or with option .CR \- or .CR \-\- , print the arguments on standard output as described in .IR echo (1). See also .IR printf (1). .IP With .CR \-n , do not add a newline character to the output. .IP With .CR \-p , write the arguments onto the pipe of the process spawned with .CR |& instead of standard output. .IP With .CR \-R or .CR \-r (raw mode), ignore the escape conventions of .CR echo . With .CR \-R , print all subsequent arguments and options other than .CR \-n . .IP With .CR \-s , write the arguments into the history file instead of to standard output. .IP With .CR \-u , specify a one-digit file descriptor unit number .I n on which the output will be placed. The default is .CR 1 (standard output). .PP .ne 3v .CR pwd \0[ \-L \(or \-P ] .IP Print the name of the current working directory (equivalent to .CR "print\0\-r\0\-\0$PWD" ). With .CR \-L (the default), preserve the logical meaning of the current directory. With .CR \-P , preserve the physical meaning of the current directory if it is a symbolic link. See also the .CR cd special command, .IR cd (1), .IR ln (1), and .IR pwd (1). .PP .ne 3v .CR read \0[ \-prsu [\f2n\f1]\|]\0[\f2name\f1 ? \f2prompt\f1]\0[\f2name\f1]...\& .IP The shell input mechanism. Read one line (by default, from standard input) and break it up into words using the characters in .CR IFS as separators. The first word is assigned to the first .IR name , the second word to the second .IR name , and so on; the remaining words are assigned to the last .IR name . See also .IR read (1). The return code is .CR 0 , unless an end-of-file is encountered. .IP With .CR \-p , take the input line from the input pipe of a process spawned by the shell using .CR |& . An end-of-file with .CR \-p causes cleanup for this process so that another process can be spawned. .IP With .CR \-r (raw mode), a .CR \e at the end of a line does not signify line continuation. .IP With .CR \-s , save the input as a command in the history file. .IP With .CR \-u , specify a one-digit file descriptor unit to read from. The file descriptor can be opened with the .CR exec special command. The default value of .I n is .CR 0 (standard input). If .IR name is omitted, .CR REPLY is used as the default .IR name . .IP If the first argument contains a .CR ? , the remainder of the argument is used as a .I prompt when the shell is interactive. .IP If the given file descriptor is open for writing and is a terminal device, the prompt is placed on that unit. Otherwise, the prompt is issued on file descriptor 2 (standard error). .PP .ne 4v \(dg\(dd .CR readonly \0[\f2name\f1[ = \f2value\f1]\|]...\& .br \(dg\(dd .CR readonly\0\-p .IP Mark the given .IR name s read only. These names cannot be changed by subsequent assignment. .IP With .CR \-p , write the names and values of all read-only variables to standard output in a format with the proper use of quoting so that it is suitable for re-input to the shell as commands that achieve the same attribute-setting results. .PP .ne 3v \(dg .CR return \0[\f2n\f1] .IP Cause a shell function to return to the invoking script with the return status specified by .IR n . If .I n is omitted, the return status is that of the last command executed. Only the low 8 bits of .I n (decimal 0 to 255) are passed back to the caller. If .CR return is invoked while not in a function or a .CR .\& script (see the .CR .\& special command), it has the same effect as an .CR exit command. .PP .ne 3v \(dg .CR set .RC [{ \- \(or + }\c .CR abCefhkmnopstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [{ \- \(or + } A .IR name ]\0[ arg ]...\& .IP Set .RC ( \- ) or clear .RC ( + ) execution options or perform array assignments .RC ( \-A ,\ +A ). All options except .CR \-A and .CR +A can be supplied in a shell invocation (see the SYNOPSIS section and the "Shell Invocation" subsection). .IP Using .CR + instead of .CR \- before an option causes the option to be turned off. These options can also be used when invoking the shell. The current list of set single-letter options is contained in the shell variable .CR \- . It can be examined with the command .CR "echo $-" . .IP The .CR \- and .CR + options can be intermixed in the same command, except that there can be only one .CR \-A or .CR +A option. .IP Unless .CR \-A or .CR +A is specified, the remaining .I arg arguments are assigned consecutively to the positional parameters .CR 1 , .CR 2 ,\0.... .IP The .CR set command with neither arguments nor options displays the names and values of all shell parameters on standard output. See also .IR env (1). .IP The options are defined as follows. .RS .TP .CR \-A Array assignment. Unset the variable .I name and assign values sequentially from the list .IR arg . With .CR \+A , do not unset the variable .I name first. .TP .CR \-a Automatically export subsequently defined parameters. .TP .CR \-b Cause the shell to notify the user asynchronously of background jobs as they are completed. When the shell notifies the user that a job has been completed, it can remove the job's process ID from the list of those known in the current shell execution environment. .TP .CR \-C Prevent redirection .CR > from truncating existing files. Requires .CR >| to truncate a file when turned on. .TP .CR \-e Execute the .CR ERR trap, if set, and exit .I if a command has a nonzero exit status, and is not part of the compound list following a .CR if , .CR until , or .CR while keyword, and is not part of an AND or OR list, and is not a pipeline preceded by the .CR !\& reserved word. This mode is disabled while reading profiles. .TP .CR \-f Disable file name generation. .TP .CR \-h Specify that each command whose name is an .I identifier becomes a tracked alias when first encountered. .TP .CR \-k Place all parameter assignment arguments (not just those that precede the command name) into the environment for a command. .TP .CR \-m Run background jobs in a separate process group and print a line upon completion. The exit status of background jobs is reported in a completion message. This option is turned on automatically for interactive shells. .TP .CR \-n Read commands and check them for syntax errors, but do not execute them. The .CR \-n option is ignored for interactive shells. .TP .ne 5v .CR \-o Set an .I option argument from the following list. Repeat the .CR \-o option to specify additional .I option arguments. .RS .TP 15 .PD 0 .CR allexport Same as .CR \-a . .TP .CR bgnice Run all background jobs at a lower priority. .TP .CR errexit Same as .CR \-e . .TP .CR emacs Use a .CR emacs -style inline editor for command entry. .TP .CR gmacs Use a .CR gmacs -style inline editor for command entry. .TP .CR ignoreeof Do not exit from the shell on end-of-file .RI ( eof as defined by .CR stty ; default is .CR ^D ). The .CR exit special command must be used. .TP .CR keyword Same as .CR \-k . .TP .CR markdirs Append a trailing .CR / to all directory names resulting from file name generation. .TP .CR monitor Same as .CR \-m . .TP .CR noclobber Same as .CR \-C . .TP .CR noexec Same as .CR \-n . .TP .CR noglob Same as .CR \-f . .TP .CR nolog Do not save function definitions in history file. .TP .CR notify Same as .CR \-b . .TP .CR nounset Same as .CR \-u . .TP .CR privileged Same as .CR \-p . .TP .CR verbose Same as .CR \-v . .TP .CR trackall Same as .CR \-h . .TP .CR vi Use a .CR vi -style inline editor for command entry. .TP .CR viraw Process each character as it is typed in .CR vi mode (always on). .TP .CR xtrace Same as .CR \-x . .PD .RE .TP .CR \-p Disable processing of the .CR $HOME/.profile file and uses the file .CR /etc/suid_profile instead of the .CR ENV file. This mode is on whenever the effective user ID (group ID) is not equal to the real user ID (group ID). Turning this off causes the effective user ID and group ID to be set to the real user ID and group ID. .TP .CR \-s Sort the positional parameters. .TP .CR \-t Exit after reading and executing one command. .TP .CR \-u Treat unset parameters as an error when substituting. .TP .CR \-v Print shell input lines as they are read. .TP .CR \-x Print commands and their arguments as they are executed. .TP .CR \- Turn off .CR \-x and .CR \-v options and stop examining arguments for options. .TP .CR \-\- Do not change any of the options; useful in setting parameter .CR 1 to a value beginning with .CR \- . If no arguments follow this option, the positional parameters are unset. .RE .PP .ne 3v \(dg .CR shift "\0[\f2n\f1]" .IP Rename the positional parameters from .IC n +1 \f1\0...\& to .CR 1 \0.... The default value of .I n is .CR 1 . .I n can be any arithmetic expression that evaluates to a nonnegative number less than or equal to .CR $# . .PP .ne 3v .CR test \0[\f2expr\f1] .IP Evaluate conditional expression .IR expr . See .IR test (1) for usage and description. The arithmetic comparison operators are not restricted to integers. They allow any arithmetic expression. The following additional primitive expressions are allowed: .RS .TP 20 .PD 0 .CI \-L \0file True if .I file is a symbolic link. .TP .CI \-e \0file True if .I file exists. .TP .IC file1\0 \-nt \0file2 True if .I file1 is newer than .IR file2 . .TP .IC file1\0 \-ot \0file2 True if .I file1 is older than .IR file2 . .TP .IC file1\0 \-ef \0file2 True if .I file1 has the same device and i-node number as .IR file2 . .PD .RE .PP .ne 3v \(dg .CR times .IP Print the accumulated user and system times for the shell and for processes run from the shell. .PP .ne 3v \(dg .CR trap \0[\f2arg\f1]\0[\f2sig\f1]...\& .IP Set .I arg as a command that is read and executed when the shell receives a .IR sig signal. (Note that .I arg is scanned once when the trap is set and once when the trap is taken.) Each .I sig can be given as the number or name of a signal. Letter case is ignored. For example, .CR 3 , .CR QUIT , .CR quit , and .CR SIGQUIT all specify the same signal. Use .CR "kill \-l" to get a list of signals. .IP Trap commands are executed in signal number order. Any attempt to set a trap on a signal that was ignored upon entering the current shell is ineffective. Traps remain in effect for a given shell until explicitly changed with another .CR trap command; that is, a trap set within a function will remain in effect even after the function returns. .IP If .I arg is .CR \- (or if .I arg is omitted and the first .I sig is numeric), reset all traps for each .I sig to their original values. .IP If .I arg is the null string .RC ( '' or \&\c .C """""\c" ), each .I sig is ignored by the shell and by the commands it invokes. .IP If .I sig is .CR DEBUG , then .I arg is executed after each command. If .I sig is .CR ERR , .I arg is executed whenever a command has a nonzero exit code. If .I sig is .CR 0 or .CR EXIT, the command .I arg is executed on exit from the shell. .IP With no arguments, print a list of commands associated with each signal name. .IP .PP .ne 4v \(dd .CR typeset \0[{ \- \(or + }\c .CR LRZfilrtux [\f2n\f1]\|]\0[\f2name\f1[ = \f2value\f1]\|]... .br .IC name = value .RC [\f2name = \f2value\f1]...\& .IP Assign types and a value to a local named parameter .IR name . See also the .CR export special command. Parameter assignments remain in effect after the command completes. When invoked inside a function, create a new instance of the parameter .IR name . The parameter value and type are restored when the function completes. .IP The following list of attributes can be specified. Use .CR \+ instead of .CR \- to turn the options off. .RS .TP .CR \-L Left justify and remove leading blanks from .IR value . If .I n is nonzero, it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. When .I name is assigned, the value is filled on the right with blanks or truncated, if necessary, to fit into the field. Leading zeros are removed if the .CR \-Z option is also set. The .CR \-R option is turned off. Flagged as .CI leftjust \0n\f1. .TP .CR \-R Right justify and fill with leading blanks. If .I n is nonzero, it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. The field is left-filled with blanks or truncated from the end if the parameter is reassigned. The .CR \-L option is turned off. Flagged as .CI rightjust \0n\f1. .TP .CR \-Z Right justify and fill with leading zeros if the first nonblank character is a digit and the .CR \-L option has not been set. If .I n is nonzero it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. Flagged as .CI zerofill \0n\f1 plus the flag for .CR \-L or .CR \-R . .TP .CR \-f Cause .I name to refer to function names rather than parameter names. No assignments can be made to the .I name declared with the .CR typeset statement. The only other valid options are .CR \-t (which turns on execution tracing for this function) and .CR \-x (which allows the function to remain in effect across shell procedures executed in the same process environment). Flagged as .CR function . .TP .CR \-i Parameter is an integer. This makes arithmetic faster. If .I n is nonzero it defines the output arithmetic base; otherwise, the first assignment determines the output base. Flagged as .CR integer \0[ base \0\f2n\f1]. .TP .CR \-l Convert all uppercase characters to lowercase. The uppercase .CR \-u option is turned off. Flagged as .CR lowercase . .TP .CR \-r Mark any given .I name as "read only". The name cannot be changed by subsequent assignment. Flagged as .CR readonly . .TP .CR \-t Tag the named parameters. Tags are user-definable and have no special meaning to the shell. Flagged as .CR tagged . .TP .CR \-u Convert all lowercase characters to uppercase characters. The lowercase .CR \-l option is turned off. Flagged as .CR uppercase . .TP .CR \-x Mark any given .I name for automatic export to the environment of subsequently executed commands. Flagged as .CR export . .RE .IP .CR typeset alone displays a list of parameter names, prefixed by any flags specified above. .IP .CR "typeset \-" displays the parameter names followed by their values. Specify one or more of the option letters to restrict the list. Some options are incompatible with others. .IP .CR "typeset +" displays the parameter names alone. Specify one or more of the option letters to restrict the list. Some options are incompatible with others. .PP .ne 3v .CR ulimit \0[ \-HSacdfnst ]\0[\f2limit\f1] .IP Set or display a resource limit. The limit for a specified resource is set when .IR limit is specified. The value of .IR limit can be a number in the unit specified with each resource, or the keyword .CR unlimited . .IP The .CR \-H and .CR \-S flags specify whether the hard limit or the soft limit is set for the given resource. A hard limit cannot be increased once it is set. A soft limit can be increased up to the hard limit. If neither .CR \-H nor .CR \-S is specified, the limit applies to both. The current resource limit is printed when .IR limit is omitted. In this case, the soft limit is printed unless .CR \-H is specified. When more than one resource is specified, the limit name and unit are printed before the value. .IP If no option is given, .CR \-f is assumed. .RS .TP .PD 0 .CR \-a List all of the current resource limits. .TP .CR \-c The number of 512-byte blocks in the size of core dumps. .TP .CR \-d The number of kilobytes in the size of the data area. .TP .CR \-f The number of 512-byte blocks in files written by child processes (files of any size can be read). .TP .CR \-n The number of file descriptors. .TP .CR \-s The number of kilobytes in the size of the stack area. .TP .CR \-t The number of seconds to be used by each process. .PD .RE .PP .ne 3v .CR umask \0[ \-S ]\0[\f2mask\f1] .IP Set the user file-creation mask .IR mask . .I mask can be either an octal number or a symbolic value as described in .IR umask (1). A symbolic value shows permissions that are unmasked. An octal value shows permissions that are masked off. .IP Without .I mask , print the current value of the mask. With .CR \-S , print the value in symbolic format. Without .CR \-S , print the value as an octal number. The output from either form can be used as the .I mask of a subsequent invocation of .CR umask . .PP .ne 4v .CI unalias \0name\f1\0...\& .br .CR unalias\0\-a .IP Remove each .IR name from the alias list. With .CR \-a , remove all .CR alias definitions from the current shell execution environment. .PP .ne 3v \(dg .CR unset \0[ \-fv ]\0\f2name\f1\0...\& .IP Remove the named shell parameters from the parameter list. Their values and attributes are erased. Read-only variables cannot be unset. With .CR \-f , .IR name s refer to function names. With .CR \-v , .IR name s refer to variable names. Unsetting .CR _ , .CR ERRNO , .CR LINENO , .CR MAILCHECK , .CR OPTARG , .CR OPTIND , .CR RANDOM , .CR SECONDS , and .CR TMOUT removes their special meaning, even if they are subsequently assigned to. .PP .ne 3v .CR wait \0[\f2job\f1] .IP Wait for the specified .I job to terminate or stop, and report its status. This status becomes the return code for the .CR wait command. Without .I job , wait for all currently active child processes to terminate or stop. The termination status returned is that of the last process. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v .CR whence \0[ \-pv ]\0\f2name\f1\0...\& .IP For each .IR name , indicate how it would be interpreted if used as a command name. With .CR \-v , produce a more verbose report. With .CR \-p do a path search for .IR name , disregarding any use as an alias, a function, or a reserved word. .SS Comments A .I word beginning with .CR # causes that word and all the following characters up to a newline to be ignored. .SS Aliasing The first word of each command is replaced by the text of an .CR alias , if an .CR alias for this word has been defined. An .CR alias name consists of any number of characters excluding metacharacters, quoting characters, file expansion characters, parameter and command substitution characters, and =. The replacement string can contain any valid shell script, including the metacharacters listed above. The first word of each command in the replaced text, other than any that are in the process of being replaced, will be tested for additional aliases. If the last character of the alias value is a .IR blank , the word following the alias is also checked for alias substitution. Aliases can be used to redefine special commands, but cannot be used to redefine the keywords listed in the "Compound Commands" subsection. Aliases can be created, listed, and exported with the .CR alias command and can be removed with the .CR unalias command. Exported aliases remain in effect for subshells but must be reinitialized for separate invocations of the shell (see the "Shell Invocation" subsection). .PP Aliasing is performed when scripts are read, not while they are executed. Therefore, for it to take effect, an .CR alias must be executed before the command referring to the alias is read. .PP Aliases are frequently used as a shorthand for full path names. An option to the aliasing facility allows the value of the alias to be automatically set to the full path name of the corresponding command. These aliases are called .I tracked aliases. The value of a .I tracked alias is defined the first time the identifier is read and becomes undefined each time the .CR PATH variable is reset. These aliases remain .I tracked so that the next reference will redefine the value. Several tracked aliases are compiled into the shell. The .CR \-h option of the .CR set command converts each command name that is an .I identifier into a tracked alias. .PP The following .I exported aliases are compiled into the shell but can be unset or redefined: .nf .IP .C autoload='typeset \-fu' .C command='command ' .C functions='typeset \-f' .C history='fc \-l' .C integer='typeset \-i' .C local=typeset .C nohup='nohup ' .C r='fc \-e \-' .C stop='kill \-STOP' .C suspend='kill \-STOP $$' .C type='whence \-v' .SS Tilde Substitution After alias substitution is performed, each word is checked to see if it begins with an unquoted tilde .RC ( ~ ). If it does, the word up to a .CR / is checked to see if it matches a user name in the .CR /etc/passwd file. If a match is found, the .CR ~ and the matched login name are replaced by the login directory of the matched user. If no match is found, the original text is left unchanged. A .CR ~ alone or before a .CR / is replaced by the value of the .CR HOME parameter. A .CR ~ followed by a .CR + or .CR \- is replaced by the value of the parameter .CR PWD and .CR OLDPWD , respectively. In addition, tilde substitution is attempted when the value of a parameter assignment begins with a .CR ~ . .SS Command Substitution The standard output from a command enclosed in parenthesis preceded by a dollar sign .RC ( $( ...\& ) ) or a pair of grave accents .RC ( ` ...\& ` ) can be used as part or all of a word; trailing newlines are removed. In the second (archaic) form, the string between the accents is processed for special quoting characters before the command is executed. See the "Quoting" subsection. The command substitution .CR "$(cat file)" can be replaced by the equivalent but faster .CR $(\0\c ". .TP .CR PS3 Selection prompt string used within a .CR select loop. If unset, it defaults to "\c .CR #?\0\c ". .TP .CR PS4 Execution trace string that precedes each line of an execution trace. See the .CR "set \-x" special command. If unset, it defaults to "\c .CR +\0\c ". .TP .CR SHELL The path name of the shell is kept in the environment. When invoked, the shell is restricted if the value of this variable contains an .CR r in the base name. .TP .CR TMOUT If set to a value greater than zero, the shell will terminate if a command is not entered within the prescribed number of seconds after issuing the .CR PS1 prompt. (Note that the shell can be compiled with a maximum bound for this value which cannot be exceeded.) .TP .CR VISUAL Invokes the corresponding option when the value of this variable ends in .CR emacs , .CR gmacs , or .CR vi . See the .CR "set \-o" special command. .PP The shell gives default values to .CR IFS , .CR MAILCHECK , .CR PATH , .CR PS1 , .CR PS2 , and .CR TMOUT . On the other hand, .CR MAIL , .CR ENV , .CR HOME , and .CR SHELL are never set automatically by the shell (although .CR HOME , .CR MAIL , and .CR SHELL are set by .CR login ; see .IR login (1)). .SS Blank Interpretation After parameter and command substitution, the results of substitution are scanned for field separator characters (defined in .CR IFS ), and split into distinct arguments when such characters are found. .CR sh retains explicit null arguments (\c .C """""" or .CR '' ) but removes implicit null arguments (those resulting from parameters that have null values). .SS File Name Generation Following substitution, each command .I word is processed as a pattern for file name expansion unless expansion has been disabled with the .CR "set \-f" special command. The form of the patterns is the Pattern Matching Notation defined in .IR regexp (5). The word is replaced with sorted file names matching the pattern. If no file name is found that matches the pattern, the word is left unchanged. .PP In addition to the notation described in .IR regexp (5), .CR sh recognizes composite patterns made up of one or more pattern lists separated from each other with a .CR | . Composite patterns can be formed with one or more of the following: .RS .TP 18 .PD 0 .CI ?( pattern-list ) Matches any one of the given patterns. .TP .CI *( pattern-list ) Matches zero or more occurrences of the given patterns. .TP .CI +( pattern-list ) Matches one or more occurrences of the given patterns. .TP .CI @( pattern-list ) Matches exactly one of the given patterns. .TP .CI !( pattern-list ) Matches anything, except one of the given patterns. .PD .RE .SS Quoting Each of the metacharacters (see the "Definitions" subsection) has a special meaning to the shell and terminates a word unless quoted. A character may be .B quoted (that is, made to stand for itself) by preceding it with a backslash .RC ( \e ). The pair .CR \e newline is ignored; the current and following lines are concatenated. .PP All characters enclosed between a pair of apostrophes .RC ( ' ...\& ' ) are quoted. An apostrophe cannot appear within apostrophes. .PP Parameter and command substitution occurs inside quotation marks (\c .C """\c" \&...\&\c .C """\c" ). .CR \e quotes the characters .CR \e , .CR ` , .C """\c" , and .CR $ . .PP Inside grave accent marks .RC ( ` ...\& ` ), .CR \e quotes the characters .CR \e , .CR ` , and .CR $ . If the grave accents occur within quotation marks, .CR \e also quotes the character .C """\c" \&. .PP The meanings of .CR $* and .CR $@ are identical when not quoted or when used as a parameter assignment value or as a file name. However, when used as a command argument, .C """\c" .CR $*\c .C """" is equivalent to .C """\c" .CI $1 d $2 d\f1...\&\c .C """\c" , whereas .C """\c" .CR $@\c .C """" is equivalent to .C """\c" .CR $1\c .C """\c" .IR d\c .C """\c" .CR $2\c .C """\c" .IR d ...\& (where .I d is the first character of .CR IFS ), .PP The special meaning of keywords or aliases can be removed by quoting any character of the name. The recognition of function names or special command names cannot be altered by quoting them. .SS Arithmetic Evaluation Integer arithmetic is provided with the special command .CR let . Evaluations are performed using long integer arithmetic. Constants take the form .IC base # n or .IR n , where .I base is a decimal number between two and thirty-six representing the arithmetic base and .I n is a number in that base. If .IC base # is omitted, base 10 is used. .PP An arithmetic expression uses the same syntax, precedence, and associativity of expression as the C language. All the integral operators, other than .CR ++ , .CR \-\- , .CR ?: , and .CR , are supported. Variables can be referenced by name within an arithmetic expression without using the parameter substitution syntax. When a variable is referenced, its value is evaluated as an arithmetic expression. .PP A variable can be typed as an integer with the .CR \-i option of the .CR typeset special command, as in .CI typeset\0-i \f1[\f2base\f1]\f2\0name\f1. Arithmetic evaluation is performed on the value of each assignment to a variable with the .CR \-i attribute. If you do not specify an arithmetic base, the first assignment to the variable determines the arithmetic base. This base is used when parameter substitution occurs. .PP Since many of the arithmetic operators require quoting, an alternative form of the .CR let command is provided. For any command beginning with .CR (( , all characters until the matching .CR )) are treated as a quoted expression. More precisely, .CR (( ...\& )) is equivalent to .CR let .C """\c" .RC ...\c .C """\c" .RC . .SS Prompting When used interactively, the shell prompts with the value of .CR PS1 before reading a command. Whenever a newline is received and further input is needed to complete a command, the secondary prompt (the value of .CR PS2 ) is issued. .SS Conditional Expressions A .B "conditional expression" is used with the .CR [[ compound command to test attributes of files and to compare strings. Word splitting and file name generation are not performed on the words between .CR [[ and .CR ]] . Each expression can be constructed from one or more of the following unary or binary expressions: .RS .TP 20 .PD 0 .CI \-a \0file True, if .I file exists. .TP .CI \-b \0file True, if .I file exists and is a block special file. .TP .CI \-c \0file True, if .I file exists and is a character special file. .TP .CI \-d \0file True, if .I file exists and is a directory. .TP .CI \-e \0file True, if .I file exists. .TP .CI \-f \0file True, if .I file exists and is an ordinary file. .TP .CI \-g \0file True, if .I file exists and has its setgid bit set. .TP .CI \-h \0file True, if .I file exists and is a symbolic link. .TP .CI \-k \0file True, if .I file exists and has its sticky bit set. .TP .CI \-n \0string True, if length of .I string is nonzero. .TP .CI \-o \0option True, if the set option named .I option is on. .TP .CI \-p \0file True, if .I file exists and is a fifo special file or a pipe. .TP .CI \-r \0file True, if .I file exists and is readable by current process. .TP .CI \-s \0file True, if .I file exists and has a size greater than zero. .TP .CI \-t \0fildes True, if file descriptor number .I fildes is open and is associated with a terminal device. .TP .CI \-u \0file True, if .I file exists and has its setuid bit set. .TP .CI \-w \0file True, if .I file exists and is writable by the current process. .TP .CI \-x \0file True, if .I file exists and is executable by the current process. If .I file exists and is a directory, then the current process has permission to search in the directory. .TP .CI \-z \0string True, if length of .I string is zero. .TP .CI \-L \0file True, if .I file exists and is a symbolic link. .TP .CI \-O \0file True, if .I file exists and is owned by the effective user ID of this process. .TP .CI \-G \0file True, if .I file exists and its group matches the effective group ID of this process. .TP .CI \-S \0file True, if .I file exists and is a socket. .TP .IC file1\0 \-nt \0file2 True, if .I file1 exists and is newer than .IR file2 . .TP .IC file1\0 \-ot \0file2 True, if .I file1 exists and is older than .IR file2 . .TP .IC file1\0 \-ef \0file2 True, if .I file1 and .I file2 exist and refer to the same file. .TP .IC string\0 = \0pattern True, if .I string matches .IR pattern . .TP .IC string\0 != \0pattern True, if .I string does not match .IR pattern . .TP .IC string\0 < \0string2 True, if .I string1 comes before .I string2 based on the ASCII value of their characters. .TP .IC string\0 > \0string2 True, if .I string1 comes after .I string2 based on the ASCII value of their characters. .TP .IC exp1\0 \-eq \0exp2 True, if .I exp1 is equal to .IR exp2 . .TP .IC exp1\0 \-ne \0exp2 True, if .I exp1 is not equal to .IR exp2 . .TP .IC exp1\0 \-lt \0exp2 True, if .I exp1 is less than .IR exp2 . .TP .IC exp1\0 \-gt \0exp2 True, if .I exp1 is greater than .IR exp2 . .TP .IC exp1\0 \-le \0exp2 True, if .I exp1 is less than or equal to .IR exp2 . .TP .IC exp1\0 \-ge \0exp2 True, if .I exp1 is greater than or equal to .IR exp2 . .PD .RE .PP A compound expression can be constructed from these primitives by using any of the following, listed in decreasing order of precedence. .RS .TP 20 .PD 0 .CI ( exp ) True, if .I exp is true. Used to group expressions. .TP .CI ! exp True, if .I exp is false. .TP .IC exp1\0 && \0exp2 True, if .I exp1 and .I exp2 are both true. .TP .IC exp1\0 || \0exp2 True, if either .I exp1 or .I exp2 is true. .PD .RE .SS Input/Output Before a command is executed, its input and output can be redirected using a special notation interpreted by the shell. The following can appear anywhere in a simple-command or may precede or follow a command and are not passed on to the invoked command. Command and parameter substitution occurs before .I word or .I digit is used, except as noted below. File name generation occurs only if the pattern matches a single file and blank interpretation is not performed. .RS .TP 15 .CI < word Use file .I word as standard input (file descriptor .CR 0 ). .TP .CI > word Use file .I word as standard output (file descriptor .CR 1 ). If the file does not exist, it is created. If the file exists, and the .CR noclobber option is on, an error occurs; otherwise, the file is truncated to zero length. .TP .CI >| word Same as .CR > , except that it overrides the .CR noclobber option. .TP .CI >> word Use file .I word as standard output. If the file exists, output is appended to it (by first searching for the end-of-file); otherwise, the file is created. .TP .CI <> word Open file .I word for reading and writing as standard input. .TP .CR << [ \- ]\f2word The shell input is read up to a line that matches .IR word , or to an end-of-file. No parameter substitution, command substitution or file name generation is performed on .IR word . The resulting document, called a .IR here-document , becomes the standard input. If any character of .I word is quoted, no interpretation is placed upon the characters of the document. Otherwise, parameter and command substitution occurs, .CR \e newline is ignored, and .CR \e must be used to quote the characters .CR \e , .CR $ , .CR ` , and the first character of .IR word . If .CR \- is appended to .CR << , all leading tabs are stripped from .I word and from the document. .TP .CI <& digit The standard input is duplicated from file descriptor .I digit (see .IR dup (2)). .TP .CI >& digit The standard output is duplicated to file descriptor .I digit (see .IR dup (2)). .TP .CR <&- The standard input is closed. .TP .CR >&- The standard output is closed. .TP .CR <&p The input from the coprocess is moved to standard input. .TP .CR >&p The output to the coprocess is moved to standard output. .RE .RE .PP If any of the above redirections is preceded by a digit .RC ( 0 to .CR 9 ), the file descriptor used is the one specified by the digit, instead of the default .CR 0 (standard input) or .CR 1 (standard output). For example: .IP .CR 2>&1 .PP means open file descriptor 2 for writing as a duplicate of file descriptor 1. Output directed to file descriptor 2 is written in the same location as output to file descriptor 1. .PP Order is significant in redirection. The shell evaluates each redirection in terms of the .RI ( "file descriptor" ", " file ) assignment at the time of evaluation. For example: .IP .CR 1> \f2fname\0 2>&1 .PP first assigns file descriptor 1 to file .IR fname . It then assigns file descriptor 2 to the file assigned to file descriptor 1 (that is, .IR fname ). .PP If the order of redirection is reversed, as in .IP .CR 2>&1\01> \f2fname .PP file descriptor 2 is assigned to the file assigned to file descriptor 1 (probably the terminal) and then file descriptor 1 is assigned to file .IR fname . .PP By using the redirection operators above, the input and output of a .I coprocess may be moved to a numbered file descriptor, allowing other commands to write to them and read from them. If the input of the current coprocess is moved to a numbered file descriptor, another coprocess may be started. .PP If a command is followed by .CR & and job control is inactive, the default standard input for the command is the empty file .CR /dev/null . Otherwise, the environment for the execution of a command contains the file descriptors of the invoking shell as modified by input/output specifications. .SS Environment The .B environment (see .IR environ (5)) is a list of name-value pairs passed to an executed program much like a normal argument list. The names must be identifiers and the values are character strings. The shell interacts with the environment in several ways. When invoked, the shell scans the environment and creates a parameter for each name found, gives it the corresponding value and marks it .CR export . Executed commands inherit the environment. If the user modifies the values of these parameters or creates new ones by using the .CR export or .CR "typeset \-x" special commands, the values become part of the environment. The environment seen by any executed command is thus composed of any name-value pairs originally inherited by the shell, whose values may be modified by the current shell, plus any additions which must be noted in .CR export or .CR "typeset \-x" commands. .PP The environment for any simple command or function can be augmented by prefixing it with one or more parameter assignments. A parameter assignment argument takes the form .IC identifier = value\f1. For example, both the following .IP .CI TERM=450 "\0cmd\0args" .IP .CI "(export TERM; TERM=450;" "\0cmd\0args" ) .PP are equivalent (as far as the execution of .I cmd is concerned, except for the special commands that are preceded by a dagger (\(dg)). .PP If the .CR \-k option is set, all parameter assignment arguments are placed in the environment, even if they occur after the command name. The following echo statement prints .CR "a=b c" . After the .CR \-k option is set, the second echo statement prints only .CR c : .nf .IP .CR "echo a=b c" \0\(->\0 "a=b c" .CR "set \-k" .CR "echo a=b c" \0\(->\0 "c" .fi .PP This feature is intended for use with scripts written for early versions of the shell and its use in new scripts is strongly discouraged. It is likely to disappear someday. .SS Functions The .CR function command (described in the "Compound Commands" subsection) defines shell functions. Shell functions are read and stored internally. Alias names are resolved when the function is read. Functions are executed like commands, with the arguments passed as positional parameters. (See the "Execution" subsection.) .PP Functions execute in the same process as the caller and share all files and current working directory with the caller. Traps defined by the caller remain in effect within the function until another .CR trap command is executed. Traps set within a function remain in effect after the function returns. Ordinarily, variables are shared between the calling program and the function. However, the .CR typeset special command can be used within a function to define local variables whose scope includes the current function and all functions it calls. .PP The .CR return special command is used to return from function calls. Errors within functions return control to the caller. .PP Function identifiers can be listed with the .CR +f option of the .CR typeset special command. Function identifiers and the associated text of the functions can be listed with the .CR \-f option. Functions can be undefined with the .CR \-f option of the .CR unset special command. .PP Ordinarily, functions are unset when the shell executes a shell script. The .CR \-xf option of the .CR typeset command allows a function to be exported to scripts that are executed without reinvoking the shell. Functions that must be defined across separate invocations of the shell should be placed in the .CR ENV file. .SS Jobs If the .CR monitor option of the .CR set command is turned on, an interactive shell associates a .I job with each pipeline. It keeps a table of current jobs, printed by the .CR jobs command, and assigns them small integer numbers. When a job is started asynchronously with .CR & , the shell prints a line that looks like: .IP .C "[1] 1234" .PP indicating that job number 1 was started asynchronously and had one (top-level) process whose process ID was 1234. .PP If you are running a job and wish to do something else, you can type the suspend character (the .CR susp character defined with .CR stty ; see .IR stty (1)) to send a .CR SIGSTOP signal to the current job. The shell then indicates that the job has been .CR Stopped , and prints another prompt. Then you can manipulate the state of this job by putting it in the background with the .CR bg command, running other commands, and eventually returning the job to the foreground with the .CR fg command. A suspend takes effect immediately and resembles an interrupt, since pending output and unread input are discarded when the suspend is entered. .PP A job running in the background stops if it tries to read from the terminal. Background jobs normally are allowed to produce output, but can be disabled with the .CR "stty tostop" command. If the user sets this terminal option, background jobs stop when trying to produce output. .PP There are several ways to refer to jobs in the shell. A job can be referred to by the process ID of any process in the job or by one of the following: .RS .TP 20 .PD 0 .CI % number The job with the given number. .TP .CI % string Any job whose command line begins with .IR string . .TP .CI %? string Any job whose command line contains .IR string . .TP .CI %% Current job. .TP .CI %+ Equivalent to .CR %% . .TP .CR %- Previous job. .PD .RE .PP The shell learns immediately when a process changes state. It informs the user when a job is blocked and prevented from further progress, but only just before it prints a prompt. .PP When the monitor mode is on, each background job that completes triggers any trap set for .CR SIGCHLD . .PP If you try to exit from shell while jobs are stopped, you are warned with the message .CR "You have stopped jobs." You can use the .CR jobs command to identify them. If you immediately try to exit again, the shell will not warn you a second time, and the stopped jobs will be terminated. .PP If you try to leave the shell while jobs are running, you are not warned. The shell exits silently and sets the parent of the running jobs to the .CR init process (number 1). .SS Signals The .CR SIGINT and .CR SIGQUIT signals for an invoked command are ignored if the command is followed by .CR & and the .CR monitor option is off. Otherwise, signals have the values inherited by the shell from its parent, with the exception of signal .CR SIGSEGV (but see also the .CR trap special command). .SS Execution Substitutions are made each time a command is executed. .CR sh checks the command name to determine whether it matches a special command. If it does, it is executed within the current shell process. .PP Next, .CR sh checks the command name to determine whether it matches one of the user-defined functions. If it does, .CR sh saves the positional parameters, then sets them to the arguments of the function call. The positional parameter .CR 0 is unchanged. When the function completes or issues a .CR return , .CR sh restores the positional parameter list. The value of a function is the value of the last command executed. A function is executed in the current shell process. .PP If a command name is not a user-defined function or a special command, .CR sh creates a process and attempts to execute the command using an .CI exec * () system call (see .IR exec (2)). .PP The shell parameter .CR PATH defines the search path for the directory containing the command. Alternative directory names are separated by a colon .RC ( : ). The default path is .CR /usr/bin:\& (specifying .CR /usr/bin , and the current directory, in that order). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign, between colon delimiters, or at the end of the path list. The search path is not used if the command name contains a .CR / . Otherwise, each directory in the path is searched for an executable file. If the file has execute permissions but is not a directory or an executable object code file, it is assumed to be a script file, which is a file of data for an interpreter. If the first two characters of the script file are .CR #! , .CI exec * () expects an interpreter path name to follow. .CI exec * () then attempts to execute the specified interpreter as a separate process to read the entire script file. If a call to .CI exec * () fails, .CR sh is spawned to interpret the script file. All nonexported aliases, functions, and named parameters are removed in this case. If the shell command file does not have read permission, or if the .CR setuid and/or .CR setgid bits are set on the file, the shell executes an agent to set up the permissions and execute the shell with the shell command file passed down as an open file. A parenthesized command is also executed in a subshell without removing nonexported quantities. .SS Command Reentry The text of the last .CR HISTSIZE (default 128) commands entered from a terminal device is saved in a history file. The file .CR $HOME/.sh_history is used if the .CR HISTFILE variable is not set or writable. A shell can access the commands of all interactive shells that use the same named .CR HISTFILE . The special command .CR fc is used to list or edit a portion of this file. The portion of the file to be edited or listed can be selected by number or by giving the first character or characters of the command. A single command or range of commands can be specified. If you do not specify an editor program as an argument to .CR fc , the value of the parameter .CR FCEDIT is used. If .CR FCEDIT is not defined, .CR /usr/bin/ed is used. The edited command is printed and reexecuted upon leaving the editor. The editor name .CR \- is used to skip the editing phase and to reexecute the command. In this case, a substitution parameter of the form .IC old = new can be used to modify the command before execution. For example, if .CR r is aliased to .CR "fc \-e \-" , typing .CR "r bad=good c" reexecutes the most recent command that starts with the letter .CR c and replaces the first occurrence of the string .CR bad with the string .CR good . .SS Command Line Editing Normally, each command line typed at a terminal device is followed by a newline or return. If one of the .CR emacs , .CR gmacs , .CR vi , or .CR viraw , options is set, you can edit the command line. An editing option is automatically selected each time the .CR VISUAL or .CR EDITOR variable is assigned a value ending in one of these option names. .PP The editing features require that the user's terminal accept return without line feed and that a space ("\ ") must overwrite the current character on the screen. ADM terminal users should set the "space\ \(mi\ advance" switch to "space". Hewlett-Packard terminal users should set the straps to "bcGHxZ\ etX". .PP The editing modes enable the user to look through a window at the current line. The default window width is 80, unless the value of .CR COLUMNS is defined. If the line is longer than the window width minus two, a mark displayed at the end of the window notifies the user. The mark is one of: .RS .TP .PD 0 .CR > The line extends to the right. .TP .CR < The line extends to the left. .TP .CR * The line extends to both sides of the window. .PD .RE .PP As the cursor moves and reaches the window boundaries, the window is centered about the cursor. .PP The search commands in each edit mode provide access to the history file. Only strings are matched, not patterns, although a leading .CR ^ in the string restricts the match to begin at the first character in the line. .SS emacs Editing Mode This mode is invoked by either the .CR emacs or .CR gmacs option. Their sole difference is their handling of .CR ^T . To edit, the user moves the cursor to the point needing correction and inserts or deletes characters or words. All editing commands are control characters or escape sequences. The notation for control characters is caret .RC ( ^ ) followed by a character. For example, .CR ^F is the notation for Control-F. This is entered by holding down the Ctrl (control) key and pressing .CR f . The shift key is .I not pressed. The notation .CR ^?\& indicates the delete (DEL) key. .PP The notation for escape sequences is .CR M- followed by a character. For example, .CR M-f (pronounced .IR "meta f" ) is entered by pressing the escape key (ESC) followed by pressing .CR f . .CR M-F is the notation for escape followed by shift (capital) .CR F . .PP All edit commands operate from any place on the line (not only at the beginning). Neither the return .RC ( ^M ) nor the newline .RC ( ^J ) key is entered after edit commands, except when noted. .RS .TP 15 .PD 0 .CR ^F Move cursor forward (right) one character. .TP .CR M-f Move cursor forward one word. (The editor's idea of a word is a string of characters consisting of only letters, digits and underscores.) .TP .CR ^B Move cursor backward (left) one character. .TP .CR M-b Move cursor backward one word. .TP .CR ^A Move cursor to start of line. .TP .CR ^E Move cursor to end of line. .TP .CI ^] char Move cursor forward to character .I char on current line. .TP .CI M-^] char Move cursor backward to character .I char on current line. .TP .CI ^X^X Interchange the cursor and mark. .TP .I erase Delete previous character. (User-defined erase character as defined by the .CR stty command, usually .CR ^H or .CR # .) .TP .CR ^D Delete current character. .TP .I eof Terminate the shell if the current line is null. (User-defined end-of-file character as defined by the .CR stty command, usually .CR ^D .) .TP .CI M-d Delete current word. .TP .CI M-^H Delete previous word. (meta-backspace) .TP .CI M-h Delete previous word. .TP .CI M-^?\& Delete previous word. (meta-delete) If your interrupt character is .CR ^?\& (DEL, the default), this command will not work. .TP .CI ^T In .CR emacs mode, transpose current character with next character. In .CR gmacs mode, transpose two previous characters. .TP .CI ^C Capitalize current character. .TP .CI M-c Capitalize current word. .TP .CI M-l Change the current word to lowercase. .TP .CI ^K Delete from the cursor to the end of the line. If preceded by a numerical parameter whose value is less that the current cursor position, then delete from the given position up to the cursor. If preceded by a numerical parameter whose value is greater than the current cursor position, then delete from the cursor up to the given position. .TP .CI ^W Kill from the cursor to the mark. .TP .CI M-p Push the region from the cursor to the mark on the stack. .TP .I kill Kill the entire current line. If two kill characters are entered in succession, all subsequent consecutive kill characters cause a line feed (useful when using paper terminals). (User-defined kill character as defined by the .CR stty command, usually .CR ^X or .CR @ .) .TP .CI ^Y Restore last item removed from line. (Yank item back to the line.) .TP .CI ^L Line feed and print current line. .TP .CR ^@ Set mark. (null character) .TP .CI M-\0 Set mark. (meta-space) .TP .CI ^J Execute the current line. (newline) .TP .CI ^M Execute the current line. (return) .TP .CI ^P Fetch previous command. Each time .CR ^P is entered, the previous command in the history list is accessed. .TP .CI ^N Fetch next command. Each time .CR ^N is entered the next command in the history list is accessed. .TP .CI M-< Fetch the least recent (oldest) history line. .TP .CI M-> Fetch the most recent (youngest) history line. .TP .CI ^R string Reverse search history for a previous command line containing .IR string . If a parameter of zero is given, the search is forward. .I string is terminated by a return or newline. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is omitted, the next command line containing the most recent .I string is accessed. In this case, a parameter of zero reverses the direction of the search. .TP .CR ^O Execute the current line and fetch the next line relative to current line from the history file. .TP .CI M- digits Define a numeric parameter. The digits are taken as a parameter to the next command. The commands that accept a parameter are .IR erase , .CR ^B , .CR ^C , .CR ^D , .CR ^F , .CR ^K , .CR ^N , .CR ^P , .CR ^R , .CR ^] , .CR M-^H , .CR M-. , .CR M-_ , .CR M-b , .CR M-c , .CR M-d , .CR M-f , .CR M-h , and .CR M-l . .TP .CI M- letter Your alias list is searched for an alias by the name .CI _ letter (underscore-letter). If an alias of this name is defined, its value is inserted on the input queue. This .I letter must not be one of the above metafunctions. .TP .CR M-. The last word of the previous command is inserted on the line. If preceded by a numeric parameter, the value of this parameter determines which word to insert rather than the last word. .TP .CR M-_ Same as .CR M-. . .TP .CR M-* Attempt file name generation on the current word. .TP .CR M-^[ File name completion. (meta-escape.) Replaces the current word with the longest common prefix of all file names matching the current word with an asterisk appended. If the match is unique, a .CR / is appended if the file is a directory and a space is appended if the file is not a directory. .TP .CR M-= List files matching current word pattern as if an asterisk were appended. .TP .CR ^U Multiply parameter of next command by 4. .TP .CR \e Escape next character. Editing characters and your erase, kill, and interrupt characters may be entered in a command line or in a search string, if preceded by a .CR \e . The .CR \e removes the next character's editing features (if any). .TP .CI ^V Display version of the shell. .TP .CI M-# Insert a .CR # at the beginning of the line and execute it. This causes a comment to be inserted in the history file. .PD .RE .SS vi Editing Mode The editor starts in insert mode until an escape (ESC) is received. This puts you in control mode in which you can move the cursor and perform editing commands. A return in either mode sends the line. .PP Most control commands accept an optional repeat .I count prior to the command. .PP In .CR vi mode on most systems, canonical processing is initially enabled and the command is echoed again if the speed is 1200 baud or greater and contains any control characters, or if less than one second has elapsed since the prompt was printed. The escape (ESC) character terminates canonical processing for the remainder of the command and you can then modify the command line. This scheme has the advantages of canonical processing with the typeahead echoing of raw mode. .PP Setting the .CR viraw option always disables canonical processing on the terminal. This mode is implicit for systems that do not support two alternate end-of-line delimiters, and may be helpful for certain terminals. .PP .B Insert Edit Commands .PP By default, the editor is in insert mode. .RS .TP 15 .PD 0 .I erase Delete previous inserted character. The .IR erase character is user-definable with the .CR stty command, usually set to .CR ^H . The system default is .CR # . .TP .I kill Delete all current inserted characters. The .IR kill character is user-definable with the .CR stty command, usually set to .CR ^X or .CR ^U . The system default is .CR @ . .TP .CR \e Escape the next .I erase or .I kill character. .TP .CR ^D Terminate the shell. .TP .CR ^V Escape next character. Editing characters and erase or kill characters may be entered in a command line or in a search string if preceded by a .CR ^V , which removes the next character's editing features (if any). .TP .CR ^W Delete the previous blank-separated word. .PD .RE .PP .B Motion Edit Commands .PP These commands move the cursor. The use of .IR count causes a repetition of the command the cited number of times. .RS .TP 15 .PD 0 .RC [\f2count\f1] l Cursor forward (right) one character. .TP .RC [\f2count\f1] w Cursor forward one alphanumeric word. .TP .RC [\f2count\f1] W Cursor forward to the beginning of the next word that follows a blank. .TP .RC [\f2count\f1] e Cursor forward to the end of the word. .TP .RC [\f2count\f1] E Cursor forward to end of the current blank-delimited word. .TP .RC [\f2count\f1] h Cursor backward (left) one character. .TP .RC [\f2count\f1] b Cursor backward one word. .TP .RC [\f2count\f1] B Cursor backward to preceding blank-separated word. .TP .RC [\f2count\f1] | Cursor to column .IR count . Default is 1. .TP .RC [\f2count\f1] f \f2c Find the next character .IR c in the current line. .TP .RC [\f2count\f1] F \f2c Find the previous character .IR c in the current line. .TP .RC [\f2count\f1] t \f2c Equivalent to .CI f c followed by .CR h . .TP .RC [\f2count\f1] T \f2c Equivalent to .CI F c followed by .CR l . .TP .RC [\f2count\f1] ; Repeat the last single-character find command, .CR f , .CR F , .CR t , or .CR T . .TP .RC [\f2count\f1] , Reverses the last single character find command. .TP .CR 0 Cursor to start of line. .TP .CR ^ Cursor to first nonblank character in line. .TP .CR $ Cursor to end of line. .PD .RE .PP .B History Search Commands .PP These commands access your command history file. .RS .TP 15 .PD 0 .RC [\f2count\f1] k Fetch previous command. Each time .CR k is entered, the next earlier command in the history list is accessed. .TP .RC [\f2count\f1] \- Equivalent to .CR k . .TP .RC [\f2count\f1] j Fetch next command. Each time .CR j is entered, the next later command in the history list is accessed. .TP .RC [\f2count\f1] + Equivalent to .CR j . .TP .RC [\f2count\f1] G The command number .I count is fetched. The default is the first command in the history list. .TP .CI / string Search backward through history for a previous command containing .IR string . .I string is terminated by a return or newline. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is null, the previous string is used. .TP .CI ? string Same as .CR / , but search in the forward direction. .TP .CR n Search for next match of the last pattern to the .CR / or .CR ? commands. .TP .CR N Search for next match of the last pattern to .CR / or .CR ? , but in reverse direction. .PD .RE .PP .B Text Modification Edit Commands .PP These commands will modify the line. .RS .TP 15 .PD 0 .CR a Enter insert mode after the current character. .TP .CR A Append text to the end of the line. Equivalent to .CR $a . .TP .RC [\f2count\f1] c \f2motion .TP .CR c [\f2count\f1]\f2motion Move cursor forward to the character position specified by .IR motion , deleting all characters between the original cursor position and the new position, and enter insert mode. If .I motion is .CR c , the entire line is deleted. .TP .CR C Delete from the current character through the end of line and enter insert mode. Equivalent to .CR c$ . .TP .CR S Equivalent to .CR cc . .TP .RC [\f2count\f1] d \f2motion .TP .CR d [\f2count\f1]\f2motion Move cursor to the character position specified by .IR motion , deleting all characters between the original cursor position and the new position. If .I motion is .CR d , the entire line will be deleted. .TP .CR D Delete from the current character through the end of line. Equivalent to .CR d$ . .TP .CR i Enter insert mode before the current character. .TP .CR I Enter insert mode before the beginning of the line. Equivalent to the two-character sequence .CR 0i . .TP .RC [\f2count\f1] P Insert the previous text modification before the cursor. .TP .RC [\f2count\f1] p Insert the previous text modification after the cursor. .TP .CR R Enter insert mode and replace characters on the screen with characters you type, overlay fashion. .TP .RC [\f2count\f1] r \f2c Replace the current character with .IR c . .TP .RC [\f2count\f1] x Delete the current character. .TP .RC [\f2count\f1] X Delete the preceding character. .TP .RC [\f2count\f1] . Repeat the previous text modification command. .TP .CR ~ Invert the case of the current character and advance the cursor. .TP .RC [\f2count\f1] _ Append the .I count word of the previous command at the current cursor location and enter insert mode at the end of the appended text. The last word is used if .I count is omitted. .TP .CR * Append an .CR * to the current word and attempt file name generation. If no match is found, ring the bell. If a match is found, replace the word with the matching string of file names and enter insert mode. .TP escape .TP .CR \e Attempt file name completion on the current word. Replace the current word with the longest common prefix of all file names matching the current word with an asterisk appended. If the match is unique, append a .CR / if the file is a directory or append a space if the file is not a directory. .PD .RE .PP .B Other Edit Commands .PP .RS .TP 15 .PD 0 .RC [\f2count\f1] y \f2motion .TP .CR y [\f2count\f1]\f2motion Yank current character through character that .I motion would move the cursor to and put them into the delete buffer. The text and cursor are unchanged. .TP .CR Y Yank from current position to end of line. Equivalent to .CR y$ . .TP .CR u Undo the last text-modifying command. .TP .CR U Undo all the text-modifying commands performed on the line. .TP .RC [\f2count\f1] v Execute the command .CI "fc \-e ${VISUAL:-${EDITOR:-vi}}" " count" in the input buffer. If .I count is omitted, the current line is used. This executes an editor with the current line as the input "file". When you exit from the editor, the result is executed. .TP .CR ^L Line feed and print current line. .TP .CR ^J Execute the current line, regardless of mode. (newline) .TP .CR ^M Execute the current line, regardless of mode. (return) .TP .CR # Insert a .CR # at the beginning of the current line and after each embedded newline, and execute the line. Useful for inserting the current command line in the history list without executing it. .TP .CR = List the file names that match the current word if an asterisk were appended to it. .TP .CI @ letter Search your alias list for an alias with the name .CI _ letter (underscore letter). If an alias of this name is defined, its value is executed as a command sequence on the current line. This provides a simple macro capability. .PD .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. If it is not defined or is empty, it defaults to the value of .CR LANG . .PP .CR LC_CTYPE determines the classification of characters as letters, and the characters matched by character class expressions in pattern matching notation. If it is not defined or is empty, it defaults to the value of .CR LANG . .PP If .CR LANG is not defined or is empty, it defaults to .CR C (see .IR lang (5)). .PP If any internationalization variable contains an invalid value, they all default to .CR C (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH RETURN VALUE Errors detected by the shell, such as syntax errors, cause the shell to return a nonzero exit status. Otherwise, the shell returns the exit status of the last command executed. See also the .CR exit special command. If the shell is being used noninteractively, the execution of the shell file is abandoned. Runtime errors detected by the shell are reported by printing the command or function name and the error condition. If the line number on which the error occurred is greater than one, the line number is also printed in brackets .RC ( [] ) after the command or function name. .\".SH EXAMPLES .\" none appropriate. .SH WARNINGS .PP Some file descriptors are used internally by the POSIX shell. For HP-UX releases 10.10 and beyond, file descriptors 24 through 30 are reserved. HP-UX releases 10.00 and 10.01 reserve descriptors 54 through 60. Applications using these and forking a subshell should not depend upon them surviving in the subshell or its descendants. .PP If a command that is a tracked alias is executed, and a command with the same name is installed in a directory in the search path before the directory where the original command was found, the shell will continue to load and execute the original command. Use the .CR \-t option of the .CR alias command to correct this situation. .PP If you move the current directory or one above it, .CR pwd may not give the correct response. Use the .CR cd command with a full path name to correct this situation. .PP Some very old shell scripts use a caret .RC ( ^ ) as a synonym for the pipe character .RC ( | ). .CR sh .I "does not" recognize the caret as a pipe character. .PP If a command is piped into a shell command, all variables set in the shell command are lost when the command completes. .PP Using the .CR fc built-in command within a compound command will cause the entire command to disappear from the history file. .PP The dot .RC ( . ) special command, as in .CI .\& " file\f1," reads the entire file before any commands are executed. Therefore, .CR alias and .CR unalias commands in the file will not apply to any functions defined in the file. .PP Traps are not processed while the shell is waiting for a foreground job. Thus, a trap on .CR SIGCHLD is not executed until the foreground job terminates. .PP The .CR export special command does not handle arrays properly. Only the first element of an array is exported to the environment. .PP Background processes started from a noninteractive shell cannot be accessed with job control commands. .PP The value of the .CR IFS variable in the user's environment affects the behavior of scripts. .SS Collating Order In an international environment, character ordering is determined by the value of .CR LC_COLLATE , rather than by the binary ordering of character values in the machine collating sequence. This brings with it certain attendant dangers, particularly when using range expressions in file name generation patterns. For example, the command, .IP .C "rm [a-z]*" .PP might be expected to match all file names beginning with a lowercase alphabetic character. However, if dictionary ordering is specified by .CR LC_COLLATE , it would also match file names beginning with an uppercase character (as well as those beginning with accented letters). Conversely, it would fail to match letters collated after .CR z in languages such as Danish or Norwegian. .PP The correct (and safe) way to match specific character classes in an international environment is to use a pattern (see .IR regexp (5)) of the form: .IP .C "rm [[:lower:]]*" .PP This uses .CR LC_CTYPE to determine character classes and works predictably for all supported languages and codesets. For shell scripts produced on noninternationalized systems (or without consideration for the above dangers), it is recommended that they be executed in a non-NLS environment. This requires that .CR LANG , .CR LC_COLLATE , and so on, be set to .CR C or not set at all. .SS History File Changes .PP The history file does not support mixing of locales in the same file. For users of multiple locales, you can assign a unique history file for each locale by setting .CR HISTFILE as: .IP .C "HISTFILE=$HOME/.sh_hist_${LANG}" .PP or include the process number in the .CR HISTFILE parameter as shown above. .SH AUTHOR .CR sh was developed by AT&T, OSF, and HP. .SH FILES .TP 30 .PD 0 .CR $HOME/.profile Read to set up user's custom environment .TP .CR /etc/passwd To find home directories .TP .CR /etc/profile Read to set up system environment .TP .CR /etc/suid_profile Security profile .TP .CR /tmp/sh* For here-documents .TP .CR /usr/bin/sh Shell executable program location .PD .SH SEE ALSO cat(1), cd(1), command(1), echo(1), ed(1), env(1), getopts(1), kill(1), ln(1), login(1), newgrp(1), printf(1), pwd(1), read(1), stty(1), test(1), time(1), umask(1), vi(1), dup(2), exec(2), fork(2), pipe(2), stty(2), ulimit(2), umask(2), wait(2), rand(3C), a.out(4), profile(4), environ(5), lang(5), regexp(5), signal(5). .SH STANDARDS CONFORMANCE .CR sh ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR . ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR : ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR break ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR case ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR continue ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR eval ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR exec ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR exit ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR export ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR for ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR if ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR read ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR return ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR set ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR shift ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR time ": SVID2, SVID3, XPG2, XPG3, XPG4" .br .CR trap ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR unset ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR until ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR while ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4sh\f1 \- shell based on POSIX.2@@@\f3sh-posix(1)\f1 .\" index@\f4alias\f1 \- substitute command and/or file name@@@\f3sh-posix(1)\f1 .\" index@\f4break\f1 \- exit from enclosing for/next loop@@@\f3sh-posix(1)\f1 .\" index@\f4case\f1 \- execute \f2list\f1 associated with \f2pattern\f1 that matches \f2word\f1@@@\f3sh-posix(1)\f1 .\" index@\f4cd\f1 \- change working directory@@@\f3sh-posix(1)\f1 .\" index@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@\f3sh-posix(1)\f1 .\" index@\f4echo\f1 \- echo (print) arguments@@@\f3sh-posix(1)\f1 .\" index@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@\f3sh-posix(1)\f1 .\" index@\f4exec\f1 \- execute command without creating new process@@@\f3sh-posix(1)\f1 .\" index@\f4exit\f1 \- exit shell with exit status@@@\f3sh-posix(1)\f1 .\" index@\f4export\f1 \- export variable names to environment of subsequent commands@@@\f3sh-posix(1)\f1 .\" index@\f4fc\f1 \- edit and execute previous command@@@\f3sh-posix(1)\f1 .\" index@\f4for\f1 \- execute a do list@@@\f3sh-posix(1)\f1 .\" index@\f4if\f1 \- execute command if previous command returns exit status 0@@@\f3sh-posix(1)\f1 .\" index@\f4jobs\f1 \- list active jobs@@@\f3sh-posix(1)\f1 .\" index@\f4kill\f1 \- terminate job or process@@@\f3sh-posix(1)\f1 .\" index@\f4let\f1 \- evaluate arithmetic expression@@@\f3sh-posix(1)\f1 .\" index@\f4newgrp\f1 \- equivalent to \f4exec newgrp\f1@@@\f3sh-posix(1)\f1 .\" index@\f4print\f1 \- output from shell@@@\f3sh-posix(1)\f1 .\" index@\f4pwd\f1 \- print current working directory@@@\f3sh-posix(1)\f1 .\" index@\f4read\f1 \- input and parse a line@@@\f3sh-posix(1)\f1 .\" index@\f4readonly\f1 \- mark names as unredefinable@@@\f3sh-posix(1)\f1 .\" index@\f4return\f1 \- shell function return to invoking script@@@\f3sh-posix(1)\f1 .\" index@\f4set\f1 \- set/define options and arguments@@@\f3sh-posix(1)\f1 .\" index@\f4shift\f1 \- shift \f2argv\f1 members one position to left@@@\f3sh-posix(1)\f1 .\" index@\f4test\f1 \- evaluate conditional expression@@@\f3sh-posix(1)\f1 .\" index@\f4time\f1, \f4times\f1 \- print summary of time used by processes@@@\f3sh-posix(1)\f1 .\" index@\f4trap\f1 \- trap specified signal@@@\f3sh-posix(1)\f1 .\" index@\f4typeset\f1 \- control leading blanks and parameter handling@@@\f3sh-posix(1)\f1 .\" index@\f4ulimit\f1 \- set size or time limits@@@\f3sh-posix(1)\f1 .\" index@\f4umask\f1 \- set permissions mask for creating new files@@@\f3sh-posix(1)\f1 .\" index@\f4unalias\f1 \- discard specified alias@@@\f3sh-posix(1)\f1 .\" index@\f4unset\f1 \- remove definition/setting of options and arguments@@@\f3sh-posix(1)\f1 .\" index@\f4until\f1 \- execute commands until expression is nonzero@@@\f3sh-posix(1)\f1 .\" index@\f4wait\f1 \- wait for child process@@@\f3sh-posix(1)\f1 .\" index@\f4whence\f1 \- define interpretation of name as a command@@@\f3sh-posix(1)\f1 .\" index@\f4while\f1 \- execute commands while expression is nonzero@@@\f3sh-posix(1)\f1 .\" .\" toc@\f3sh-posix(1)\f1:\0\0\f4sh\f1@@@shell, the standard/restricted command programming language .\" toc@\f4case\f1 \- label in a switch statement@@@see \f3sh-posix(1)\f1 .\" toc@\f4alias\f1 \- substitute command and/or file name@@@see \f3sh-posix(1)\f1 .\" toc@\f4break\f1 \- exit from enclosing for/next loop@@@see \f3sh-posix(1)\f1 .\" toc@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@see \f3sh-posix(1)\f1 .\" toc@\f4cd\f1 \- change working directory@@@see \f3sh-posix(1)\f1 .\" toc@\f4echo\f1 \- echo (print) arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@see \f3sh-posix(1)\f1 .\" toc@\f4exec\f1 \- execute command without creating new process@@@see \f3sh-posix(1)\f1 .\" toc@\f4exit\f1 \- exit shell with exit status@@@see \f3sh-posix(1)\f1 .\" toc@\f4export\f1 \- export variable names to environment of subsequent commands@@@see \f3sh-posix(1)\f1 .\" toc@\f4fc\f1 \- edit and execute previous command@@@see \f3sh-posix(1)\f1 .\" toc@\f4for\f1 \- execute a do list@@@see \f3sh-posix(1)\f1 .\" toc@\f4if\f1 \- execute command if previous command returns exit status 0@@@see \f3sh-posix(1)\f1 .\" toc@\f4jobs\f1 \- list active jobs@@@see \f3sh-posix(1)\f1 .\" toc@\f4kill\f1 \- terminate job or process@@@see \f3sh-posix(1)\f1 .\" toc@\f4let\f1 \- evaluate arithmetic expression@@@see \f3sh-posix(1)\f1 .\" toc@\f4newgrp\f1 \- equivalent to \f2exec newgrp\f1@@@see \f3sh-posix(1)\f1 .\" toc@\f4print\f1 \- output from shell@@@see \f3sh-posix(1)\f1 .\" toc@\f4pwd\f1 \- print current working directory@@@see \f3sh-posix(1)\f1 .\" toc@\f4read\f1 \- input and parse a line@@@see \f3sh-posix(1)\f1 .\" toc@\f4readonly\f1 \- mark names as unredefinable@@@see \f3sh-posix(1)\f1 .\" toc@\f4return\f1 \- shell function return to invoking script@@@see \f3sh-posix(1)\f1 .\" toc@\f4set\f1 \- set/define options and arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4shift\f1 \- shift \f2argv\f1 members one position to left@@@see \f3sh-posix(1)\f1 .\" toc@\f4test\f1 \- evaluate conditional expression@@@see \f3sh-posix(1)\f1 .\" toc@\f4trap\f1 \- trap specified signal@@@see \f3sh-posix(1)\f1 .\" toc@\f4time, times\f1 \- print summary of time used by processes@@@see \f3sh-posix(1)\f1 .\" toc@\f4typeset\f1 \- control leading blanks and parameter handling@@@see \f3sh-posix(1)\f1 .\" toc@\f4ulimit\f1 \- set size or time limits@@@see \f3sh-posix(1)\f1 .\" toc@\f4umask\f1 \- set permissions mask for creating new files@@@see \f3sh-posix(1)\f1 .\" toc@\f4unalias\f1 \- discard specified alias@@@see \f3sh-posix(1)\f1 .\" toc@\f4unset\f1 \- remove definition/setting of options and arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4wait\f1 \- wait for child process@@@see \f3sh-posix(1)\f1 .\" toc@\f4whence\f1 \- define interpretation of name as a command@@@see \f3sh-posix(1)\f1 .\" toc@\f4while\f1 \- execute commands while expression is nonzero@@@see \f3sh-posix(1)\f1 .\" toc@\f4until\f1 \- execute commands until expression is nonzero@@@see \f3sh-posix(1)\f1 .\" .\" links@sh-posix.1 alias.1 .\" links@sh-posix.1 bg.1 .\" links@sh-posix.1 fc.1 .\" links@sh-posix.1 fg.1 .\" links@sh-posix.1 jobs.1 .\" links@sh-posix.1 unalias.1 .\" $Header: sh.1,v 74.1 95/03/23 17:37:57 ssa Exp $ .TA s .TH sh 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sh \- overview of various system shells .SH SYNOPSIS .SS POSIX Shell: .C sh .ift .RC [ \(+-aefhikmnoprstuvx ] .ifn .RC [ +-aefhikmnoprstuvx ] .ift .RC [ \(+-o .ifn .RC [ +-o .IR option ]\0... .RC [ -c .IR string ] .RI [ arg\0 ... ] .br .C rsh .ift .RC [ \(+-aefhikmnoprstuvx ] .ifn .RC [ +-aefhikmnoprstuvx ] .ift .RC [ \(+-o .ifn .RC [ +-o .IR option ]\0... .RC [ -c .IR string ] .RI [ arg\0 ... ] .SS Bourne Shell: .C sh .RC [ -\|-acefhiknrstuvx \0...\|] .RI [ \|arg \0...\|] .br .C rsh .RC [ -\|-acefhiknrstuvx \0...\|] .RI [ \|arg \0...\|] .SS Korn Shell: .C ksh .ift .RC [ \(+-aefhikmnoprstuvx ] .ifn .RC [ +-aefhikmnoprstuvx ] .ift .RC [\| \(+-\|o .ifn .RC [\| +-o .IR option \|]\0... .RC [ -c .IR string \|] .RI [\| arg\0 ...\|] .br .C rksh .ift .RC [ \(+-aefhikmnoprstuvx ] .ifn .RC [ +-aefhikmnoprstuvx ] .ift .RC [ \(+-o .ifn .RC [ +-o .IR option \|]\0... .RC [ -c .IR string \|] .RI [\| arg\0 ...\|] .SS C Shell: .C csh .RC [ -cefinstvxTVX ] .RI [ \|command_file\| ] .RI [ \|argument_list\| \0...\|] .SS Key Shell: .C keysh .SH DESCRIPTION .SS Remarks: The .SM POSIX\c \&.2 standard requires that, on a .SM POSIX\c -compliant system, executing the command .C sh activates the .SM POSIX shell (located in file .C /usr/bin/sh on .SM HP-UX systems), and executing the command .C man sh produces an on-line manual entry that displays the syntax of the .SM POSIX shell command-line. .PP However, the .C sh command has historically been associated with the conventional Bourne shell, which could confuse some users. To meet standards requirements and also clarify the relationships of the various shells and where they reside on the system, this entry provides command-line syntax and a brief description of each shell, and lists the names of the manual entries where each shell is described in greater detail. .SS Shell Descriptions The .SM HP-UX operating system supports the following shells: .RS .TP 10 .C sh .SM POSIX\c -conforming command programming language and command interpreter residing in file .CR /usr/bin/sh . Can execute commands read from a terminal or a file. This shell conforms to current .SM POSIX standards in effect at the time the .SM HP-UX system release was introduced, and is similar to the Korn shell in many respects. Similar in many respects to the Korn shell, the .SM POSIX shell contains a history mechanism, supports job control, and provides various other useful features. .TP .C sh Bourne-shell command programming language and commands interpreter residing in file .CR /usr/old/bin/sh . Can execute commands read from a terminal or a file. This shell lacks many features contained in the .SM POSIX and Korn shells. The Bourne shell will be obsoleted. Users are strongly encouraged to switch to the POSIX shell. The Bourne shell will still be available as .CR /usr/old/bin/sh , for those users have to use it. .TP .C ksh Korn-shell command programming language and commands interpreter residing in file .CR /usr/bin/ksh . Can execute commands read from a terminal or a file. This shell, like the .SM POSIX shell, contains a history mechanism, supports job control, and provides various other useful features. .TP .C csh A command language interpreter that incorporates a command history buffer, C-language-like syntax, and job control facilities. .TP .C rsh Restricted version of the POSIX or Bourne shell command interpreter. Sets up a login name and execution environment whose capabilities are more controlled (restricted) than normal user shells. .TP .C rksh restricted version of the Korn-shell command interpreter Sets up a login name and execution environment whose capabilities are more controlled (restricted) than normal user shells. .TP .C keysh An extension of the standard Korn Shell that uses hierarchical softkey menus and context-sensitive help. .PP .TS center box tab(;); cBw(1.2i) |cBw(1.7i) a |af4p+1. To obtain:; Use the command: _ \s-1POSIX\s0 Shell;/usr/bin/sh \f1...\fP Korn Shell;/usr/bin/ksh \f1...\fP C Shell;/usr/bin/csh \f1...\fP Key Shell;/usr/bin/keysh Bourne Shell;/usr/old/bin/sh \f1...\fP .TE .RE .PP These shells can also be the default invocation, depending on the entry in the .C /etc/passwd file. See also .IR chsh (1). .PP Whether the .C sh command invokes the Bourne Shell or the .SM POSIX Shell depends on the setting of the .C PATH environment variable. .PP The default .C PATH in file .C /etc/profile is set to invoke the .SM POSIX shell. .\" .SH EXAMPLES .\" none appropriate .SH WARNINGS Many manual entries contain descriptions of shell behavior or describe program or application behavior similar to ``the shell'' with a reference to ``see .IR sh (1)''. .PP .SH SEE ALSO For more information on the various individual shells, see: .TP 15 .IR sh-bourne (1) Bourne Shell .RC ( /usr/old/bin/sh ) description. .PD 0 .TP .IR ksh (1) Korn Shell .RC ( /usr/bin/ksh ) description. .TP .IR sh-posix (1) .SM POSIX Shell .RC ( /usr/bin/sh ) description. .TP .IR csh (1) C Shell .RC ( /usr/bin/csh ) description. .TP .IR keysh (1) Key Shell .RC ( /usr/bin/keysh ) description. .PD .\" .\" toc@\f3sh(1)\f1:\0\0\f4sh\fP@@@overview of various system shells .\" .\" index@\f4sh\fP \- overview of various system shells@@@\f3sh(1)\f1 .\" index@overview of various system shells@@@\f3sh(1)\f1 .\" index@system shells, overview of various@@@\f3sh(1)\f1 .\" index@shells, overview of various system@@@\f3sh(1)\f1 .\" .\" fileset_database@sh.1 USER-CMDS-MAN .\" $Header: shar.1,v 76.1 95/06/12 17:20:35 ssa Exp $ .TA s .TH shar 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shar \- make a shell archive package .SH SYNOPSIS .CR shar .RI [ options ] .RI [ file \(or dir ]\0...\& .CR > .I package .SH DESCRIPTION The .CR shar command bundles the named files and directories into a single distribution package suitable for mailing or moving. The files can contain any data, including executables. The resulting package, written to standard output, is a shell script file that can be edited (to add messages at the beginning, etc.). .PP To unpack .IR package , use the .IR sh (1) command with the package name as an argument as follows: .IP .CI sh \0package .PP When unpacking, the files and directories in .I package are written to the path names recorded in the archive. .PP If a directory is specified and the .CR \-d option is not given, all files beneath that directory are archived. .PP If a special file is specified, the appropriate .CR mknod commands are emitted to recreate the file (see .IR mknod (1)). .PP .CR shar protects the contained files from mail processing, if necessary, by inserting an \f3@\f1 character at the beginning of each line. If the file contains unusual data, the data is transformed into .CR uuencode format, and a .CR uudecode script is included in .I package so that the package can still be unpacked correctly by .CR sh . See WARNINGS for more information about mailers and file modifications. .PP Access modes are preserved for both directories and files. .SS Options .CR shar recognizes the following options: .RS .TP 10 .CR \-a Assume that files can be shipped, regardless of their contents; do not protect them specially. .CR shar is conservative, and might decide to .CR uuencode a file containing special characters (such as Ctrl-G) that the user knows do not need protection. .TP .CR \-A Suppress warning messages regarding optional access control list entries. .CR shar does not archive optional access control list entries in a file's access control list (see .IR acl (5)). Normally, a warning message is printed for each file having optional access control list entries. .TP .CR \-b Archive files under their base names, regardless of the original path names specified. The contents are thus unpacked into the current directory instead of to the originally specified path names. This allows you to archive files from many directories but unpack them into a single directory. It also allows you to unpack, for example, .CR /usr/share/lib/termcap into .CR ./termcap instead of overwriting the original one in .CR /etc . .TP .CR \-c Append to the package a simple data-integrity check using .CR wc to ensure that the contents were not damaged in transit (see .IR wc (1)). This check is performed automatically after unpacking. Also see WARNINGS below. .TP .CR \-C Insert a line of the form .CR "\-\-\- cut here \-\-\-" before the archive. .TP .CR \-d If a directory is specified, do not transmit its contents, but rather only create the empty directory. .TP .CI \-D dir Cause the archive to contain code that notifies the user if his or her current directory is not the same as .IR dir , which must be an absolute path. If the user is not in .IR dir , the unpacking can be continued by responding .CR yes to the archive's question. .TP .CR \-e Cause the archive to contain code that prevents .CR shar from unpacking files that would overwrite existing files. .TP .CI \-f file Read a list of file names from .I file and archive those files as if they were given as arguments. .TP .CR \-h Follow symbolic links as if they were normal files or directories. If this option is not specified, .CR shar archives the link. .TP .CR \-m Retain modification and access times on files when they are unpacked. .TP .CR \-o Preserve user and group ownership on files and directories. .TP .CR \-r Cause the archive to contain code requiring that the user unpacking it be .CR root . This is useful for processing system archives. .TP .CR \-s Perform error checking using .CR sum (see .IR sum (1)). Both .CR \-c and .CR \-s can be specified for better error checking. Also see WARNINGS below. .TP .CR \-t Write diagnostics and messages directly to your terminal instead of to the standard error. This is useful when invoking .CR shar from programs (such as .CR vi that normally combine standard error with standard output. Specifying .CR \-t also invokes the .CR \-v (verbose) option. .TP .CR \-u Assume that the remote site has .CR uudecode for unpacking. If this option is not specified, a version of .CR uudecode is sent and compiled if any non-ASCII files are archived. .TP .CR \-v Announce archived file names as they are packed. The .CR \-t option determines the destination for these announcements. .TP .CR \-Z Compress files using .CR compress (see .IR compress (1)). .RE .PP Most options are flagged in the header of the resulting package, thereby recording the format of the archive. The name of the archiver, system, and time/date of the archive are also recorded in the header. .SH EXAMPLES To archive all files under your home directory, type: .IP .C "cd; shar \-cmos ." .PP or .IP .C "shar \-cmos $HOME" .PP To preserve your .CR /dev directory, type: .IP .C "shar \-mor /dev >save_dev_files" .PP To send your newest programs in directory .CR newstuff in your home directory to a friend, type: .IP .C "cd; shar \-cmos newstuff | mailx \-s 'new source' friend" .SH RETURN VALUE .CR shar returns zero if successful; nonzero if problems with arguments occur. .SH DIAGNOSTICS If the .CR \-b option is specified, .CR shar refuses to archive directories. .SH WARNINGS The modification and access time restoration does not take time zones into account. .PP Files with newline characters in their names scramble the table of contents. .PP Non-ASCII files with white space in their names do not unpack. .PP If a mailer such as .IR elm (1) is used to transfer .I package to another system and the mailer is configured to expand tabs (by default or otherwise), any file in the archive will be modified if it contains tabs. If the .CR \-c or .CR \-s option is used to create the archive, the data-integrity check will fail during unpacking of any files in .I package that contain tab characters that were converted to spaces. (Some mailers that expand tabs when transferring files over a network may or may not expand tabs when transferring files to the sender or other users on the local system.) If an editor is used to modify any of the files in .IR package , the data-integrity check will also fail for the files that were changed. .SH AUTHOR .CR shar was invented in the public domain. This version of .CR shar was developed by HP. .SH FILES .TP 25 .PD 0 .CR /dev/tty .TP .CR /tmp/unpack$$* (for unpacking non-ASCII files) .PD .SH SEE ALSO ar(1), compress(1), cpio(1), find(1), tar(1), acl(5). .\" .\" index@\f4shar\f1 \- make a shell archive package@@@\f3shar(1)\f1 .\" index@make a shell archive package@@@\f3shar(1)\f1 .\" index@shell archive package, make a@@@\f3shar(1)\f1 .\" index@archive package, make an@@@\f3shar(1)\f1 .\" .\" toc@\f3shar(1)\f1:\0\0\f4shar\f1@@@make a shell archive package .\" $Header: shl.1,v 72.6 94/11/14 15:21:17 ssa Exp $ .TA s .TH shl 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shl \- shell layer manager .SH SYNOPSIS .C shl .SH DESCRIPTION .CR shl provides a means for interacting with more than one shell from a single terminal by using shell layers. A layer is a shell that is bound to a virtual device. The virtual device can be manipulated like an actual terminal by using .CR stty and .CR ioctl() (see .IR stty (1) and .IR ioctl (2)). Each layer has its own process group ID. The user controls these layers by using the commands described below. .PP The current layer is the layer that can receive input from the keyboard. Other layers attempting to read from the keyboard are blocked. Output from multiple layers is multiplexed onto the terminal. To block the output of a layer when it is not current, the .CR stty option .CR loblk can be set within the layer. .PP The .CR stty character .CR swtch (set to .CR ^Z if \s-1NUL\s+1) is used to switch control to .CR shl from a layer. .CR shl has its own prompt, .CR >>> , to distinguish it from a layer. .SS Definitions A .I name is a sequence of characters delimited by a space, tab, or new-line character. Only the first eight characters are significant. When provided as an argument to the .CR create , .CR login , or .CR name commands, .I name cannot be of the form .I n or .CI ( n )\f1, where .I n is a decimal number. .SS Commands The following commands can be issued from the .CR shl prompt level. Any unique prefix is accepted. .TP 15 .CR create \0[ - [\|\f2name\f1\|]\0\(or\0\f2name\f1\0[\|\f2command\f1\|]\|] Create a layer called .I name and make it the current layer. If no argument is given, a layer is created with a name of the form .CI ( n )\f1, where .I n is the number of the next available slot in an internal table. Future references to this layer can be made with or without the parentheses. If .I name is followed by a command, that command is executed in the layer instead of a shell. If .CR - is the first argument, a ``login shell'' is created in the layer. The shell prompt variable .CR PS1 is set to the name of the layer followed by a space. .TP .CR login \0[\|\f2name\fP\|] Create a layer called .I name and make it the current layer. If no argument is given, a layer is created with a name of the form .CI ( n )\f1, where .I n is the number of the next available slot in an internal table. Future references to this layer can be made with or without the parentheses. .I name is a ``login'' type of layer in which the user receives a prompt for user name and password. .TP .CR name \0[\|\f2oldname\fP\|]\0\f2newname\fP Rename the layer .IR oldname , calling it .IR newname . If .I oldname is not specified, the current layer name is changed. .TP .CR ! \0[\|\f2command\fP\|] Invoke a sub-shell and execute .IR command . If no .I command is given, a shell is executed according to the .CR SHELL environment variable. .TP .CI block \0name\f1\0[\|\fPname\f1\0...\|]\fP For each .IR name , block the output of the corresponding layer when it is not the current layer. This is equivalent to setting the .CR stty loblk option within the layer. .TP .CI delete \0name\f1\0[\|\fPname\f1\0...\|]\fP For each .IR name , delete the corresponding layer. All processes in the process group of the layer are sent the .CR SIGHUP signal (see .IR signal (5)). .TP .CR help " (or " ? ) Print the syntax of the .CR shl commands. .TP .CR layers \0[ -l ]\0[\|\f2name\fP\0...\|] For each .IR name , list the layer name and its process group. The .CR -l option produces a .IR ps (1)-like listing. If no arguments are given, information is presented for all existing layers. .TP .CR resume \0[\|\f2name\fP\|] Change the status of the layer referred to by .I name to that of current layer. If no argument is given, the last existing current layer is changed. .TP .CR toggle Change the status of the previous current layer to that of current layer. .TP .CI unblock \0name\0\f1[\fP\|name\|\f1\0...\|]\fP For each .IR name , do not block the output of the corresponding layer when it is not the current layer. This is equivalent to setting the .CR stty -loblk option within the layer. .TP .CR quit Exit .CR shl . All layers are sent the .CR SIGHUP signal. .TP .I name Change the status of the layer referred to by .I name to that of current layer. Any unique prefix is accepted. .SH WARNINGS .SS Commands The behavior of the .CR block and .CR unblock .CR shl commands is not guaranteed when the SHELL environment variable is set to .CR /usr/bin/csh (for .IR csh (1)) or .CR /usr/bin/ksh (for .IR ksh (1)), or when the shell saves and restores the tty state (defined in .IR termio (7)) before and after each command is invoked interactively from that shell. For both .CR /usr/bin/csh and .CR /usr/bin/ksh , the .CR loblk or .CR -loblk options of .CR stty can be used from within the layer to block or unblock the output of that layer. .PP .SS Ptydaemon For .CR shl to function properly, the .CR ptydaemon process must be running on the system. If your system has been installed with the Desktop HP-UX product, then .CR ptydaemon will not be started by default. In order to start this daemon, change .I PTYDAEMON_START from a "0" to a "1" in the .CR /etc/rc.config.d/ptydaemon file. The system must either be rebooted for this change to take effect, or you can manually start this daemon by typing : .PP .RS 4 .CR /usr/sbin/ptydaemon .RE .PP Note that .CR ptydaemon will also be disabled if the .I DesktopConfig.LITECONFIG fileset has been installed on the system, or if the system administrator has previously run the .CR SAM utility and selected the .I Apply Lite HP-UX Configuration Action from within any of .CR SAM's .I Kernel Configuration screens. .SH DEPENDENCIES .SS Series 800 The .CR login command is not currently supported. .\" source code does not exclude 700 from this command at 8.0 .SH FILES .TP 15 .CR $SHELL Variable containing path name of the shell to use (default is .CR /usr/bin/sh ). .SH SEE ALSO sh(1), stty(1), ioctl(2), signal(5). .SH STANDARDS CONFORMANCE .CR shl ": SVID2, SVID3, XPG2" .\" .\" index@\f4shl\f1 \- shell layer manager@@@\f3shl(1)\f1 .\" index@shell layer manager@@@\f3shl(1)\f1 .\" index@manager, shell layer@@@\f3shl(1)\f1 .\" .\" toc@\f3shl(1)\f1:\0\0\f4shl\f1@@@shell layer manager .\" .\" fileset_database@shl.1 USER-CMDS-MAN .\" $Header: size.1,v 72.6 94/11/14 15:21:19 ssa Exp $ .TA s .TH size 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME size \- print section sizes of object files .SH SYNOPSIS .CR size .RC [ -d ] .RC [ -o ] .RC [ -x ] .RC [ -V ] .RC [ -v ] .I files .SH DESCRIPTION .C size produces section size information for each section in the object files. The size of the text, data and bss (uninitialized data) sections are printed along with the total size of the object file. If an archive file is input to the .C size command, the information for all archive members is displayed. .SS Options .C size recognizes the following options: .RS .TP 8 .C -d Print sizes in decimal. This is the default. .TP .C -o Print sizes in octal. .TP .C -x Print sizes in hexadecimal. .TP .C -V Print version information about the .C size command. .TP .C -v Print a verbose list of the subspaces in the object files. Each subspace is listed on a separate line with its size, physical address, and virtual address. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .PP The following internationalization variables affect the execution of .CR size : .PP .C LANG .RS Determines the locale category for native language, local customs and coded character set in the absence of .C LC_ALL and other .C LC_* environment variables. If .C LANG is not specified or is set to the empty string, a default of .C C (see .IR lang (5)) is used instead of .CR LANG . .RE .PP .C LC_ALL .RS Determines the values for all locale categories and has precedence over .C LANG and other .C LC_* environment variables. .RE .PP .C LC_MESSAGES .RS Determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error. .RE .PP .C LC_NUMERIC .RS Determines the locale category for numeric formatting. .RE .PP .C LC_CTYPE .RS Determines the locale category for character handling functions. .RE .PP .C NLSPATH .RS Determines the location of message catalogues for the processing of .CR LC_MESSAGES . .RE .PP If any internationalization variable contains an invalid setting, .C size behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .PP .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS .TP 30 .CI "size: " name ": cannot open" .I name cannot be read. .TP 30 .CI "size: " name ": bad magic" .I name is not an appropriate object file. .SH EXAMPLES Compare the sizes of the text, data, and bss sections for two versions of a program: .IP .C "size ./version1 ./version2" .SH SEE ALSO .PD .SS System Tools: .TP 18 .IR as(1) translate assembly code to machine code .PD 0 .TP .IR cc(1) invoke the HP-UX C compiler .TP .IR ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 .IR a.out(4) assembler, compiler, and linker output .PD 0 .TP .IR ar(4) archive format .PD .SH STANDARDS CONFORMANCE .CR size ": SVID2, SVID3, XPG2" .\" .\" index@\f4size\f1 \- print section sizes and allocation space of object files@@@\f3size(1)\f1 .\" index@object files, print section sizes and allocation space of@@@\f3size(1)\f1 .\" index@files: print section sizes and allocation space of object files@@@\f3size(1)\f1 .\" index@print section sizes and allocation space of object files@@@\f3size(1)\f1 .\" index@section sizes and allocation space of object files, print@@@\f3size(1)\f1 .\" index@allocation space of object files, print section sizes and@@@\f3size(1)\f1 .\" index@text allocation space of object files, print section sizes and@@@\f3size(1)\f1 .\" index@data allocation space of object files, print section sizes and@@@\f3size(1)\f1 .\" index@bss (uninitialized data) allocation space of object files, print section sizes and@@@\f3size(1)\f1 .\" .\" toc@\f3size(1)\f1:\0\0\f4size\f1@@@print section sizes of object files .\" .\" fileset_database@size.1 USER-CMDS-MAN .\" $Header: sleep.1,v 76.1 95/08/04 17:03:16 ssa Exp $ .TA s .TH sleep 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sleep \- suspend execution for an interval .SH SYNOPSIS .C sleep .I time .SH DESCRIPTION .C sleep suspends execution for .I time seconds. It is used to execute a command after a certain amount of time, as in: .IP .C (sleep 105; \f2command\fP)& .PP or to execute a command periodically, as in: .nf .IP .C while true .C do .I " command" .C " sleep 37" .C done .fi .SH RETURN VALUE .C sleep exits with one of the following values: .RS .TP 5 .B 0 The execution was successfully suspended for .I time seconds, or a .SM SIGALRM signal was received. .TP 5 .B >0 If the .I time operand is missing, is not a decimal integer, is negative, or is greater than .CR UINT_MAX , .C sleep returns with exit status 2. .RE .SH SEE ALSO alarm(2), sleep(3C). .SH STANDARDS CONFORMANCE .CR sleep ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" toc@\f3sleep(1)\f1:\0\0\f4sleep\f1@@@suspend execution for an interval .\" .\" index@\f4sleep\f1 \- suspend execution for a time interval@@@\f3sleep(1)\f1 .\" index@suspend execution for a time interval@@@\f3sleep(1)\f1 .\" index@time interval, suspend execution for a@@@\f3sleep(1)\f1 .\" index@interval, suspend execution for a time@@@\f3sleep(1)\f1 .\" index@execution, suspend for a time interval@@@\f3sleep(1)\f1 .\" index@pause execution for a time interval@@@\f3sleep(1)\f1 .\" .\" fileset_database@sleep.1 USER-CMDS-MAN .\" $Header: ppl.1,v 72.4 94/09/12 14:58:21 ssa Exp $ .TA p .TH ppl 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ppl \- point-to-point serial networking using SLIP or CSLIP .SH SYNOPSIS .C ppl .RC [ -o \(or -i ] .RC [ -t .IR tty\| ] .RC [ -v ] .RC [ -r .IR rtprio\| ] .RC [ -T .IR tracefile\| ] .RI [ \|remote_host\| ] .SH DESCRIPTION .C ppl extends the Internet Protocol .SM (IP) network over serial lines. It permits the use of hardwired, dial-out, or dial-in serial (tty) lines. .C ppl establishes a connection over the serial line, then runs an .B encapsulation protocol to transfer packets between the .SM IP network and the serial line. Once started, .C ppl can only be stopped by loss of the serial line (i.e. carrier failure indication from a modem), or by sending it a .C SIGTERM signal. .PP Currently .SM SLIP (Serial Line Internet Protocol), .SM CSLIP (Compressed Header .SM SLIP), and .SM ASLIP (Abbreviated .SM SLIP\s0) are the only encapsulation protocols available. .PP .C ppl can be configured in a number of ways. It behaves according to how it is configured and which command line options are used. Configuration is controlled by configuration files: .C ppl.remotes, .C ppl.ipool, and .C ppl.users. .C ppl can be configured to share .SM UUCP serial lines. .SS Options .TP 15 .C -i Initiate an incoming connection. Run the encapsulation protocol on the terminal device from which the program is invoked. This is the default if neither .C -o nor .C -i is specified. .TP .C -o Initiate an outgoing connection. The terminal on which the data pump is started is determined from configuration files, .SM UUCP, or the .C -t option. .TP .CI -t \0tty Specifies the .I tty on which the encapsulation protocol is started, .I only if a device name is not specified in configuration file .C ppl.remotes for the remote host. This option only applies when used with the .C -o option. .TP .C -v Verbose mode. This option is only available to the super-user. Verbose debugging information is displayed on the terminal and placed in the log. Secure information is included. .TP .CI -r \0rtprio Set real-time priority during data pump operation. .I rtprio can be a decimal number between 0 and 127. By default, .C ppl runs at a real-time priority of 110. .TP .CI -T \0tracefile Turns on tracing for the SLIP connection that ppl creates. Tracing is done in user space level by .C ppl. All data that are going from IP to the tty line and vice versa are traced. This option is different from the system tracing utility .C nettl, because this option is done for each connection in the user space. .C nettl performs tracing for the entire system. The contents of the .I tracefile are in human readable ASCII format. .TP .I remote_host Specifies the remote host to communicate with. Either a name or an Internet address (in dot notation) can be supplied. This must be the last argument on the command line. If none is supplied (with the .C -i option), ppl uses the users login name to find a remote host in the .C ppl.users file. .SS Dedicated Connections Dedicated connections are lines that are dedicated to .IR ppl . No getty/login is running on the local or remote end of the serial line. Such a line can be either hard-wired, dial-out, or dial-in. .PP Alternatively, .C ppl can run on lines that are used for other purposes; specifically, a getty/login on incoming lines, or shared with .SM UUCP on outgoing lines. .SS Dial-Out Connections To dial out from an .SM HP-UX system, use a command like: .IP .CI "ppl -o " remote_host .PP to establish a connection to a remote host. Any progress or error messages are directed to the users standard error. .C ppl accesses the .C ppl.remotes file to obtain information needed to establish the connection. If necessary, it also uses .SM UUCP files to select a line, acquire the phone number, and control the modem. Note that .C ppl uses various files created and maintained by the .SM UUCP system, but it does not use the .SM UUCP facility to handle inter-system communication. .PP The .SM UUCP line is selected as follows: .RS .TP 5 1. If the entry in the configuration file .C ppl.remotes does not contain a tty device name, .C ppl looks in the .SM UUCP .C Systems file for a tty device (and speed), based on the .C ppl.remotes entry .SM UUCP .I system name or .I remote host name. .TP 2. .C ppl then searches for the tty device name and speed in the .SM UUCP .C Devices file. This information is used for modem dialing instructions. .RE .PP After a successful connection is made, .C ppl makes itself into a ``daemon'' by detaching itself from the users tty group. The user gets back a shell prompt, and the .C ppl program runs in the background. The user can then perform network commands to the remote host. .SS Dial-In Connections To make a dial-in connection to an .SM HP-UX system, dial in on a serial line to the .SM HP-UX system, and log in as usual. Once logged in, the line can be converted from log-in to network use by running .CR ppl . The .C ppl program uses the login name to search .C ppl.users for a remote hostname. The remote hostname is used to access the .C ppl.remotes file to obtain all of the configuration information needed to start the desired protocol. Once the protocol starts, the users' local machine can begin packet transfers with .CR ppl . .C ppl never (voluntarily) exits, and therefore never returns a prompt. .PP Only one invocation of .C ppl is allowed to each remote host Internet address. .PP A unique local Internet address must be associated with each invocation of .CR ppl . This can be specified in the .C ppl.remotes file or it can be selected at run time from a pool of Internet addresses provided by .CR ppl.ipool. .SS SLIP over the DTC SLIP is supported over modem-to-DTC-LAN connections in binary mode up to 9600 baud for HP 9000/800 hosts. The SLIP configurations used over a mux connection should work over the DTC with the following exception. On the called host, the serial line parameter should be the device file name of a nailed DTC port as defined by the DDFA utility. .SS Log Files .C ppl keeps a log of its activities in .CR /var/ppl/log . .PP Another log can optionally be kept for creating bills or keeping track of serial line usage. If the file .C /var/ppl/bill exists, .C ppl adds an entry to this file each time it gracefully exits. The contents of the billing file are in human readable .SM ASCII form. The file is also program readable, suitable for export to various databases. It contains the following fields, separated by a semicolon (;) .CR \| : bill end time, bill start time, Local inetaddr, Remote inetaddr, login user name, tty name, and protocol. .PP The current status of all invocations of .C ppl are kept updated in the file .C /var/ppl/ptmp, if the file exists. .SS Lock Files .C ppl creates two lock files for each invocation of the program. These lock files serve three purposes: .RS .TP 3 \(bu They lock access to the Internet network address by encoding the Internet address (in hex) as part of the file name. .TP \(bu They contain various details about the connection. .TP \(bu They can be executed (by owner or root) as a shell script. When executed, they send a signal to .IR ppl , causing it to exit gracefully. .RE .PP Whenever .C ppl exits gracefully, it removes these lock files and releases resources. .PP If .C ppl uses a .SM UUCP line, it observes and creates .SM UUCP lock file protocol. .SS Gateway Packets .SM ASLIP is an abbreviated header enhancement to .SM SLIP. It provides throughput economy in non-gateway applications. One end of an .SM ASLIP line must act as a ``client''; the other end as a ``server''. Typically the client is a personal workstation; the server a larger machine. .PP The client sends non-gateway packets using .SM ASLIP and gateway packets using .SM SLIP. The server adapts its operation to the behavior of the client. .SM ASLIP operation must be specified in the .C ppl.remotes file. .SH FILES .PD 0 .TP 40 .C /etc/ppl/ppl.remotes all options for each remote connection .TP .C /etc/ppl/ppl.ipool pool of local Internet addresses that can be used .TP .C /etc/ppl/ppl.users translates users login name to a remote host .TP .CI /var/ppl/PPL. xxxx termination command file and lock file for local Internet address .TP .CI /var/ppl/ppl. xxxx termination command file and lock file for remote Internet address .TP .C /var/ppl/log audit trail and log file .TP .C /var/ppl/bill billing file (optional) .TP .C /var/ppl/ptmp status file (optional) .PD .SH AUTHOR .C ppl was developed by HP. .SH WARNINGS The log and bill files grow without bounds. .SH SEE ALSO pplstat(1), ppl.remotes(4), ppl.ipool(4), ppl.users(4), ppl.ptmp(4), .br .I Using Serial Line IP Protocols, .SM .I UUCP tutorial in .IR "Remote Access Users Guide" . .\" .\" index@\f4ppl\f1 \- point-to-point serial networking@@@\f3ppl(1)\f1 .\" index@point-to-point serial networking@@@\f3ppl(1)\f1 .\" index@serial networking, point-to-point@@@\f3ppl(1)\f1 .\" index@networking, point-to-point serial@@@\f3ppl(1)\f1 .\" .\" toc@\f3ppl(1)\f1:\0\0\f4ppl\f1@@@point-to-point serial networking .\" .\" links@ppl.1 slip.1 .\" links@ppl.1 cslip.1 .\" .\" fileset_database@ppl.1 USER-CMDS-MAN .\" $Header: slp.1,v 72.4 93/01/14 11:46:12 ssa Exp $ .TA s .TH slp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slp \- set printing options for a non-serial printer .SH SYNOPSIS .C slp .RC [ -a ] .RC [ -b ] .RC [ -c .IR cols\| ] .RC [ -d ] .RC [ -i .IR indent\| ] .RC [ -k ] .RC [ -l .IR lines\| ] .RC [ -n ] .RC [ -o ] .RC [ -r ] .RC [ -C .IR pages\| ] .RC [ -O .IR pages\| ] .SH DESCRIPTION .C slp sets printer formatting options such as the number of lines per page, number of characters per line, and indentation. These characteristics are controlled by the printer driver as described in .IR lp (7). .C slp acts on the current standard output. .SS Options .C slp recognizes the following options and arguments: .RS .TP 15 .C -a Report all option settings. .TP .C -b Specify a character printer where backspace characters pass through the driver unchanged. The absence of this option indicates a line printer. The driver takes the necessary action to accommodate backspace characters. .TP .C -o Resets the printer back to line-printer mode. .TP .CI -c cols Limit the number of columns to be printed to .IR cols . Characters beyond the specified limit are truncated. .TP .C -d Reset options to default for the device. This action is not taken until the next open occurs on the device. .TP .CI -i indent Indent .I indent columns before printing the first column. .TP .C -k Select cooked mode. Cooked mode must be used with a cooked device special file which is identified by an lp mnemonic that is not preceded by the character .CR r . .TP .CI -l lines Specify the number of .I lines per page. The last new-line character of each page is changed to a form-feed. .TP .C -n Set the page size to infinity. Since the last new-line of the page is never encountered, no new-line characters are changed to form-feeds. .TP .C -r Select a raw mode for graphics dumps. All other options are ignored except .CR -a . If the .C -r option is not given, .C -k is assumed. .TP .CI -C pages Eject zero or more .I pages after the final close of the device. .TP .CI -O pages Eject zero or more .I pages when the device is opened. .SH EXAMPLES In a typical case, the printer is set to 80 columns, no indentation, with no form-feeds between pages: .IP .C slp -c80 -i0 -n >/dev/lp .SH WARNINGS Use of the .C slp command in conjunction with the .C lp spooler (see .IR lp (1)) might cause undesirable side effects. The spooler model files make assumptions regarding the configuration and can get confused when the default values are altered. Although most options can be altered without difficulty, special problems sometimes result from adjusting the number of lines and the number of columns per page. .SH AUTHOR .C slp was developed by HP. .SH SEE ALSO lp(1), ioctl(2), lp(7). .\" .\" index@\f2slp\f1 \- set printing options for a non-serial printer@@@\f3slp(1)\f1 .\" index@set printing options for a non-serial printer@@@\f3slp(1)\f1 .\" index@printing options for a non-serial printer, set@@@\f3slp(1)\f1 .\" index@options for a non-serial printer, set printing@@@\f3slp(1)\f1 .\" index@printer, set printing options for a non-serial@@@\f3slp(1)\f1 .\" .\" toc@\f3slp(1)\f1:\0\0\f2slp\f1@@@set printing options for a non-serial printer .\" .\" fileset_database@slp.1 USER-CMDS-MAN .\" $Header: sna.1,v 72.3 93/01/14 11:47:24 ssa Exp $ .TA s .TH sna 1 "Requires Optional \s-1SNA\s0 Networking Software" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sna3179g, sna3270, sna3770, liblu62.a \- IBM* 3179G/3192G, 3270, 3777 terminal emulator and \s-1APPC API\s0 .SS Remarks: The following descriptions are provided as a very brief overview of selected .SM SNA (Systems Network Architecture) utilities that are available as optional software for use with the .SM HP-UX operating system. For more information refer to system documentation provided with the software. For purchasing information, contact your nearest .SM HP Sales and Support Office. .SH DESCRIPTION .TP 15 .C sna3179g .SM IBM 3179G color graphics display terminal emulator. .C sna3179g runs in the foreground as an X11 Window System client program. To start .CR sna3179g , the .SM SNA\s0Link product, .CR snanuc , must be running. Refer to the .SM .I HP-UX SNA\c .I 3179G and Gateway/\s-1SNA3179G\s0 Reference Manual for more detailed information. .TP .C sna3270 Provides the standard subset functionality of an .SM IBM 3278 terminal or .SM IBM 3287 Printer. Connection to the .SM SNA host is provided through .C snanuc which must be running before .C sna3270 can be used. These two processes together make the .SM HP 9000 system appear to the rest of the .SM SNA network to be a 3274 Cluster Controller with attached 3278 Display Stations and 3287 Printers. Additionally, sna3270 is capable of handling double-byte characters using .SM IBM\s0's Double-Byte Character Set .SM (DBCS) protocol. Supported .SM DBCS languages include Traditional Chinese, Japanese, and Korean. .TP .C sna3770 Emulates the major features of an .SM IBM 3777 Model 1 Communications Terminal. Software emulation of a card reader, card punch, printer, basic exchange data sets (diskette), and console provide the capability for remote job entry and file transfer to an .SM SNA host. .IP The .C sna3770 command starts one or more background monitors which send files queued by .IR send3770 (1) and receive files sent by the .SM SNA host. It also does any necessary initialization of .SM SNA3770 system files. .TP .C liblu62.a Gives application programmers working on an .SM HP 9000 the means to implement Advanced Program-to-Program Communications .SM (APPC) applications distributed between an .SM HP 9000 and an .SM IBM\c -compatible host. .C liblu62.a is a set of library functions which allow .SM HP 9000 programmers to create .SM APPC applications, commonly called Transaction Programs (\c .SM TP\c s), that can exchange data and control information with cooperating .SM TP\s0s on the host. .SH SEE ALSO .SM SNA system software documentation provided with optional .SM SNA software. .PP .TP 2 * .SM IBM is a trademark of International Business Machines Corporation. .\" .\" index@\f4sna3179g\f1, \f4sna3270\f1, \f4sna3770\f1 \- \s-1IBM\s0 3179G/3192G, 3270, 3777 terminal emulator@@@\f3sna(1)\f1 .\" index@\f4liblu62.a\f1(1) \- \s-1IBM APPC\s0 (Advanced Program-to-Program Communications) \s-1API\s0@@@see \f3sna(1)\f1 .\" index@\s-1IBM\s0 3179G/3192G, 3270, 3777 terminal emulator@@@\f3sna(1)\f1 .\" index@3179G/3192G, 3270, 3777 terminal emulator, \s-1IBM\s0@@@\f3sna(1)\f1 .\" index@3270, 3777 terminal emulator, \s-1IBM\s0 3179G/3192G,@@@\f3sna(1)\f1 .\" index@3777 terminal emulator, \s-1IBM\s0 3179G/3192G, 3270,@@@\f3sna(1)\f1 .\" index@terminal emulator, \s-1IBM\s0 3179G/3192G, 3270, 3777@@@\f3sna(1)\f1 .\" index@emulator, \s-1IBM\s0 3179G/3192G, 3270, 3777 terminal@@@\f3sna(1)\f1 .\" .\" toc@\f3sna(1)\f1:\0\0\f4sna3179g\f1, \f4sna3270\f1, \f4sna3770\f1@@@\s-1IBM\s0 3179G/3192G, 3270, 3777 terminal emulator .\"toc \f4liblu62.a\f1(1) \- \s-1IBM APPC\s0 (Advanced Program-to-Program Communications) \s-1API\s0 see \f3sna(1)\f1 .\" .\" fileset_database@sna.1 USER-CMDS-MAN .\" $Header: soelim.1,v 72.6 94/11/02 16:18:59 ssa Exp $ .TA s .TH soelim 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME soelim \- eliminate .so's from nroff input .SH SYNOPSIS .C soelim .RI [ \|file \0...\|] .SH DESCRIPTION .C soelim reads the specified files or the standard input and performs the textual inclusion implied by .C nroff directives of the form .IP .CI .so \0some_file .PP when they appear at the beginning of input lines. This is useful when using programs such as .IR tbl (1) that do not normally do this, allowing placement of individual tables or other text objects in separate files to be run as a part of a large document. .PP An argument consisting of a single minus .RC ( - ) is taken to be a file name corresponding to the standard input. .PP Note that inclusion can be suppressed by using .C ' instead of .C . at the start of the line as in: .IP .C 'so /usr/share/lib/tmac/tmac.s .SH EXAMPLES .C soelim is often used in a context similar to the following: .IP .C "soelim exum?.n | tbl | nroff -mm | col | lp" .SH WARNINGS The format of the source commands must involve no strangeness \(em exactly one blank must precede and no blanks follow the file name. .SH SEE\ ALSO more(1), nroff(1), tbl(1). .\" .\" toc@\f3soelim(1)\f1:\0\0\f4soelim\f1@@@eliminate .so's from nroff input .\" .\" index@\f4soelim\f1 \- eliminate .so's from \f4nroff\f1 input@@@\f3soelim(1)\f1 .\" index@eliminate .so's from \f4nroff\f1 input@@@\f3soelim(1)\f1 .\" index@\&.so's from \f4nroff\f1 input, eliminate@@@\f3soelim(1)\f1 .\" index@\f4nroff\f1 input, eliminate .so's from@@@\f3soelim(1)\f1 .\" .\" fileset_database@soelim.1 USER-CMDS-MAN .\" $Header: softbench.1,v 72.3 93/01/14 11:52:51 ssa Exp $ .TA s .TH softbench 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME softbench \- SoftBench Software Development Environment .SH DESCRIPTION The .B SoftBench and .B Encapsulator products are designed to improve programmer and team productivity by providing a software development environment that: .RS .TP 3 \(bu Facilitates rapid, interactive program development and simplifies program maintenance and porting in a distributed computing environment. .TP \(bu Is easy to learn and use. .TP \(bu Can be easily customized to leverage a customer's existing environment, processes and tools. .RE .SS SoftBench SoftBench is an integrated set of X11/Motif window-based programming tools and a Tool Integration Platform. Together they provide an integrated software development environment targeted at the program construction, test, and maintenance phases of software development. .PP The SoftBench product is composed of: .RS 3 .TP 3 \(bu A language-sensitive .B Program Editor and .B Program Builder to support rapid, interactive program construction. .TP \(bu A .B Static Analyzer and .B Program Debugger for understanding the structure and behavior of complex applications in order to support program test, maintenance, and porting. .TP \(bu A .B Development Manager used to manage the versions of files the SoftBench tools operate on. .RE .PP SoftBench programming tools are integrated via services that include: .RS 3 .TP 3 \(bu A tool communication architecture designed to support a task-oriented environment of cooperative tools. .TP \(bu Support for a distributed software development environment allowing remote tool execution and remote data access. .TP \(bu A graphical, OSF/Motif user interface. .TP \(bu A pervasive, interactive help system. .RE .SS Encapsulator Encapsulator delivers the customizability benefit of SoftBench. It allows users to customize and extend the SoftBench environment by: .RS 3 .TP \(bu Automating custom development processes. Encapsulator is used to define actions to be executed whenever specific events occur in the SoftBench environment. .TP \(bu Adding the SoftBench graphical user interface to existing .SM HP-UX utilities, customer tools, and third-party tools. .RE .PP These extensions are made to the environment without modifying the source code of the tools that are encapsulated. .SS Product Information SoftBench and Encapsulator run on .SM HP 9000 Series 300/400 and .SM HP 9000 Series 700/800 computers under .SM HP-UX and on other platforms. Contact your .SM HP Sales Representative for ordering information. .SH AUTHOR SoftBench was developed by HP. .SH SEE ALSO The following references are contained in other manuals shipped with SoftBench software, and are not included in this manual. .IP softbench (1), encapsulate (1), encaprun (1), softbench (5), softbuild (1), softdebug (1), softdm (1), softedit (1), softeditsrv (1), softmsg (1), softstatic (1). .SH INTERNATIONAL SUPPORT SoftBench supports both 8-bit and 16-bit languages. .\" .\" index@\f4softbench\f1 \- SoftBench Software Development Environment@@@\f3softbench(1)\f1 .\" index@SoftBench Software Development Environment@@@\f3softbench(1)\f1 .\" index@Software Development Environment, SoftBench@@@\f3softbench(1)\f1 .\" index@Environment, SoftBench Software Development@@@\f3softbench(1)\f1 .\" .\" toc@\f3softbench(1)\f1:\0\0\f4softbench\f1@@@SoftBench Software Development Environment .\" .\" fileset_database@softbench.1 USER-CMDS-MAN .\" $Header: sort.1,v 76.1 95/08/23 17:36:55 ssa Exp $ .TA s .TH sort 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sort \- sort or merge files .SH SYNOPSIS .C sort .RC [ -m ] .RC [ -o .IR output\| ] .RC [ -bdfinruM ] .RC [ -t .IR char\| ] .RC [ -k .IR keydef\| ] .RC [ -y .RI [ kmem\| ]\|] .RC [ -z .IR recsz\| ] .RC [ -T .IR dir\| ] .RI [ \|file \0...\|] .PP .C sort .RC [ -c ] .RC [ -AbdfinruM ] .RC [ -t .IR char\| ] .RC [ -k .IR keydef\| ] .RC [ -y .RI [ \|kmem\| ]\|] .RC [ -z .IR recsz\| ] .RC [ -T .IR dir\| ] .RI [ file \0...\|] .SH DESCRIPTION .C sort performs one of the following functions: .RS .TP 4 1. Sorts lines of all the named files together and writes the result to the specified output. .TP 2. Merges lines of all the named (presorted) files together and writes the result to the specified output. .TP 3. Checks that a single input file is correctly presorted. .RE .PP The standard input is read if .C - is used as a file name or no input files are specified. .PP Comparisons are based on one or more sort keys extracted from each line of input. By default, there is one sort key, the entire input line. Ordering is lexicographic by characters using the collating sequence of the current locale. If the locale is not specified or is set to the .C POSIX locale, then ordering is lexicographic by bytes in machine-collating sequence. If the locale includes multi-byte characters, single-byte characters are machine-collated before multi-byte characters. .SS Behavior Modification Options The following options alter the default behavior: .RS .TP 12 .C -A Sorts on a byte-by-byte basis using each character's encoded value. On some systems, extended characters will be considered negative values, and so sort before ASCII characters. If you are sorting ASCII characters in a non-C/POSIX locale, this flag performs much faster. .TP .C -c Check that the single input file is sorted according to the ordering rules. No output is produced; the exit code is set to indicate the result. .TP .C -m Merge only; the input files are assumed to be already sorted. .TP .CI -o \0output The argument given is the name of an output file to use instead of the standard output. This file can be the same as one of the input files. .TP .C -u Unique: suppress all but one in each set of lines having equal keys. If used with the .C -c option, check to see that there are no lines with duplicate keys, in addition to checking that the input file is sorted. .TP .CI -y \0\f1[\fPkmem\f1]\fP The amount of main memory used by the sort can have a large impact on its performance. If this option is omitted, .C sort begins using a system default memory size, and continues to use more space as needed. If this option is presented with a value, .IR kmem , .C sort starts using that number of kilobytes of memory, unless the administrative minimum or maximum is violated, in which case the corresponding extremum will be used. Thus, .CI -y \00 is guaranteed to start with minimum memory. By convention, .C -y (with no argument) starts with maximum memory. .TP .CI -z \0recsz The size of the longest line read is recorded in the sort phase so that buffers can be allocated during the merge phase. If the sort phase is omitted via the .C -c or .C -m options, a popular system default size will be used. Lines longer than the buffer size will cause .C sort to terminate abnormally. Supplying the actual number of bytes in the longest line to be merged (or some larger value) will prevent abnormal termination. .TP .CI -T \0dir Use .I dir as the directory for temporary scratch files rather than the default directory, which is is one of the following, tried in order: the directory as specified in the .C TMPDIR environment variable; .CR /var/tmp , and finally, .CR /tmp . .RE .SS Ordering Rule Options When ordering options appear before restricted sort key specifications, the ordering rules are applied globally to all sort keys. When attached to a specific sort key (described below), the ordering options override all global ordering options for that key. .PP The following options override the default ordering rules: .RS .TP 12 .C -d Quasi-dictionary order: only alphanumeric characters and blanks (spaces and tabs), as defined by .C LC_CTYPE are significant in comparisons (see .IR environ (5)). .IP (XPG4 only.) The behavior is undefined for a sort key to which -i or -n also applies. .TP .C -f Fold letters. Prior to being compared, all lowercase letters are effectively converted into their uppercase equivalents, as defined by .CR LC_CTYPE . .TP .C -i In non-numeric comparisons, ignore all characters which are non-printable, as defined by .CR LC_CTYPE . For the .SM ASCII character set, octal character codes 001 through 037 and 0177 are ignored. .TP .C -n The sort key is restricted to an initial numeric string consisting of optional blanks, an optional minus sign, zero or more digits with optional radix character, and optional thousands separators. The radix and thousands separator characters are defined by .CR LC_NUMERIC . The field is sorted by arithmetic value. An empty (missing) numeric field is treated as arithmetic zero. Leading zeros and plus or minus signs on zeros do not affect the ordering. The .C -n option implies the .C -b option (see below). .TP .C -r Reverse the sense of comparisons. .TP .C -M Compare as months. The first several non-blank characters of the field are folded to uppercase and compared with the .IR langinfo (5) items .C ABMON_1 < .C ABMON_2 < ... < .CR ABMON_12 . An invalid field is treated as being less than .C ABMON_1 string. For example, American month names are compared such that .C JAN < .C FEB < ... < .CR DEC . An invalid field is treated as being less than all months. The .C -M option implies the .C -b option (see below). .RE .SS Field Separator Options The treatment of field separators can be altered using the options: .RS .TP 12 .CI -t \0char Use .I char as the field separator character; .I char is not considered to be part of a field (although it can be included in a sort key). Each occurrence of .I char is significant (for example, .RI < char >< char > delimits an empty field). If .C -t is not specified, characters will be used as default field separators; each maximal sequence of characters that follows a non- character is a field separator. .TP .C -b Ignore leading blanks when determining the starting and ending positions of a restricted sort key. If the .C -b option is specified before the first .C -k option .RC ( +\c .I pos1 argument), it is applied to all .C -k options .RC ( +\c .I pos1 arguments). Otherwise, the .C -b option can be attached independently to each .C -k .I field_start or .I field_end option .RC ( +\c .I pos1 or .RC ( -\c .I pos2 argument; see below). Note that the .C -b option is only effective when restricted sort key specifications are given. .RE .SS Restricted Sort Key .RS .TP 12 .CI -k \0keydef The .I keydef argument defines a restricted sort key. The format of this definition is .RS .IP .IR field_start\| [ \|type\| ]\|[\c .CI , field_end\|\c .RI [ \|type\| ]\|] .RE .IP which defines a key field beginning at .I field_start and ending at .I field_end. The characters at positions .I field_start and .I field_end are included in the key field, providing that .I field_end does not precede .I field_start. A missing .I field_end means the end of the line. Fields and characters within fields are numbered starting with .CR 1 . Note that this is different than the obsolete form of restricted sort keys, where numbering starts at .CR 0 . See .SM WARNINGS below. .IP Specifying .I field_start and .I field_end involves the notion of a field, a minimal sequence of characters followed by a field separator or a new-line. By default, the first blank of a sequence of blanks acts as the field separator. All blanks in a sequence of blanks are considered to be part of the next field; for example, all blanks at the beginning of a line are considered to be part of the first field. .IP The arguments .I field_start and .I field_end each have the form .IC m . n which are optionally followed by one or more of the .I type options .CR b , .CR d , .CR f , .CR i , .CR n , .CR r , or .CR M . These modifiers have the functionality for this key only, that their command-line counterparts have for the entire record. .IP A .I field_start position specified by .IC m . n is interpreted to mean the .IR n th character in the .IR m th field. A missing .I n means .CR .1 , indicating the first character of the .IR m th field. If the .C -b option is in effect, .I n is counted from the first non-blank character in the .IR m th field. .IP A .I field_end position specified by .IC m . n is interpreted to mean the .IR n th character in the .IR m th field. If .I n is missing, the .IR m th field ends at the last character of the field. If the .C -b option is in effect, .I n is counted from the first non- character in the .IR m th field. .IP Multiple .C -k options are permitted and are significant in command line order. A maximum of 9 .C -k options can be given. If no .C -k option is specified, a default sort key of the entire line is used. When there are multiple sort keys, later keys are compared only after all earlier keys compare equal. Lines that otherwise compare equal are ordered with all bytes significant. If all the specified keys compare equal, the entire record is used as the final key. .IP The .C -k option is intended to replace the obsolete .RC [ +\c .I pos1 .RC [ +\c .IR pos2\| ]\|] notation, using .I field_start and .I field_end respectively. The fully specified .RC [ +\c .I pos1 .RC [ +\c .IR pos2\| ]\|] form: .RS .IP .CI + w . x - y\c .CI . z .RE .IP is equivalent to: .RS .IP .C -k .IC w +1. x +1, y .0 (if .I z =\|= 0) .br .C -k .IC w +1. x +1, y +1.\c .I z (if .I z > 0) .RE .RE .SS Obsolete Restricted Sort Key The notation .CI + pos1 .CI - pos2 restricts a sort key to one beginning at .I pos1 and ending at .IR pos2 . The characters at positions .I pos1 and .I pos2 are included in the sort key (provided that .I pos2 does not precede .IR pos1 ). A missing .CI - pos2 means the end of the line. .PP Specifying .I pos1 and .I pos2 involves the notion of a field, a minimal sequence of characters followed by a field separator or a new-line. By default, the first blank (space or tab) of a sequence of blanks acts as the field separator. All blanks in a sequence of blanks are considered to be part of the next field; for example, all blanks at the beginning of a line are considered to be part of the first field. .PP .I pos1 and .I pos2 each have the form .IC m . n optionally followed by one or more of the flags .CR bdfinrM . A starting position specified by .CI + m . n is interpreted to mean character .IR n +1 in field .IR m +1. A missing .CI . n means .CR . 0, indicating the first character of field .IR m +1. If the .C b flag is in effect, .I n is counted from the first non-blank in field .IR m +1; .CI + m .0b refers to the first non-blank character in field .IR m +1. .PP A last position specified by .CI - m . n is interpreted to mean the .IR n th character (including separators) after the last character of the .I m th field. A missing .CI . n means .CR . 0, indicating the last character of the .IR m th field. If the .C b flag is in effect, .I n is counted from the last leading blank in field .IR m +1; .CI - m .1b refers to the first non-blank in field .IR m +1. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the default ordering rules applied to the sort. .PP .CR LC_CTYPE determines the locale for interpretation of sequences of bytes of text data as characters (e.g., single- verses multibyte characters in arguments and input files) and the behavior of character classification for the .CR -b , .CR -d , .CR -f , .CR -i , and .C -n options. .PP .C LC_NUMERIC determines the definition of the radix and thousands separator characters for the .C -n option. .PP .C LC_TIME determines the month names for the .C -M option. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP .C LC_ALL determines the locale to use to override the values of all the other internationalization variables. .PP .C NLSPATH determines the location of message catalogs for the processing of .CR LC_MESSAGES . .PP .C LANG provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. .PP If any of the internationalization variables contains an invalid setting, .C sort behaves as if all internationalization variables are set to "C". See .IR environ (5). .PP .SS "International Code Set Support" Single- and multi-byte character code sets are supported. .SH EXAMPLES Sort the contents of .C infile with the second field as the sort key: .IP .C "sort -k 2,2 infile" .PP Sort, in reverse order, the contents of .C infile1 and .CR infile2 , placing the output in .C outfile and using the first two characters of the second field as the sort key: .IP .C "sort -r -o outfile -k 2.1,2.2 infile1 infile2" .PP Sort, in reverse order, the contents of .C infile1 and .CR infile2 , using the first non-blank character of the fourth field as the sort key: .IP .C "sort -r -k 4.1b,4.1b infile1 infile2" .PP Print the password file .RC ( /etc/passwd ) sorted by numeric user .SM ID (the third colon-separated field): .IP .C "sort -t: -k 3n,3 /etc/passwd" .PP Print the lines of the presorted file .CR infile , suppressing all but the first occurrence of lines having the same third field: .IP .C "sort -mu -k 3,3 infile" .SH DIAGNOSTICS .C sort exits with one of the following values: .RS .TP 5 .B \00 All input files were output successfully, or .C -c was specified and the input file was correctly presorted. .TP .B \01 Under the .C -c option, the file was not ordered as specified, or if the .C -c and .C -u options were both specified, two input lines were found with equal keys. This exit status is not returned if the .C -c option is not used. .TP .B >1 An error occurred such as when one or more input lines are too long. .RE .PP When the last line of an input file is missing a new-line character, .C sort appends one, prints a warning message, and continues. .PP If an error occurs when accessing the tables that contain the collation rules for the specified language, .C sort prints a warning message and defaults to the .C POSIX locale. .PP If a .CR -d , .CR -f , or .C -i option is specified for a language with multi-byte characters, .C sort prints a warning message and ignores the option. .SH WARNINGS Numbering of fields and characters within fields .RC ( -k option) has changed to conform to the .SM POSIX standard. Beginning at .SM HP-UX Release 9.0, the .C -k option numbers fields and characters within fields, starting with .CR 1 . Prior to .SM HP-UX Release 9.0, numbering started at .CR 0 . .PP A field separator specified by the .C -t option is recognized only if it is a single-byte character. .PP The character type classification categories .CR alpha , .CR digit , .CR space , and .C print are not defined for multi-byte characters. For languages with multi-byte characters, all characters are significant in comparisons. .SH FILES .C /var/tmp/stm??? .br .C /tmp/stm??? .SH AUTHOR .CR sort was developed by OSF and HP. .SH SEE ALSO comm(1), join(1), uniq(1), collate8(4), environ(5), hpnls(5), lang(5). .SH STANDARDS CONFORMANCE .CR sort ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4sort\f1 \- sort and/or merge files@@@\f3sort(1)\f1 .\" index@files: sort and/or merge files@@@\f3sort(1)\f1 .\" index@sort and/or merge files@@@\f3sort(1)\f1 .\" index@merge and/or sort files@@@\f3sort(1)\f1 .\" .\" toc@\f3sort(1)\f1:\0\0\f4sort\f1@@@sort or merge files .\" $Header: spell.1,v 72.6 94/11/14 15:21:23 ssa Exp $ .TA s .TH spell 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME spell, hashmake, spellin, hashcheck \- find spelling errors .SH SYNOPSIS .C spell .RC [ -v ] .RC [ -b ] .RC [ -x ] .RC [ -l ] .RC [ -i ] .RC [ +\c .IR local_file \|] .RI [ \|files\| ] .PP .C /usr/lbin/spell/hashmake .PP .C /usr/lbin/spell/spellin .I n .PP .C /usr/lbin/spell/hashcheck .I spelling_list .SH DESCRIPTION The .CR spell command collects words from the named .I files and looks them up in a spelling list. Words that neither occur among nor are derivable (by applying certain inflections, prefixes, and/or suffixes) from words in the spelling list are printed on the standard output. If no .I files are named, words are collected from the standard input. .PP The .CR spell command ignores most .CR troff , .CR tbl , and .I eqn constructions. .SS Options The .CR spell command recognizes the following options: .RS .TP 15 .C -v All words not literally in the spelling list are printed, and plausible derivations from the words in the spelling list are indicated. .TP .C -b British spelling is checked. Besides preferring .CR centre , .CR colour , .CR programme , .CR speciality , .CR travelled , etc., this option insists upon .CR -ise in certain words, such as in .CR standardise . .TP .C -x Every plausible stem is printed with .CR = for each word. .RE .PP By default, .CR spell follows chains of included files much like .CR deroff (see .IR deroff (1)) which recognizes the .CR troff / nroff intrinsics .CR .so and .CR .nx , .I unless the names of such included files begin with .CR /usr/share/lib . If the .CR -l option is used, .CR spell follows the chains of .I all included files. With the .CR -i option, .CR spell ignores all chains of included files. .PP If the .CI + local_file option is used, words found in .I local_file are removed from .CR spell 's output. .I local_file is the name of a user-provided file containing a sorted list of words, one per line. With this option, the user can specify a set of words that are correct spellings (in addition to .IR spell 's own spelling list) for each job. .PP The spelling list is based on many sources, and while more haphazard than an ordinary dictionary, is also more effective with respect to proper names and popular technical words. Coverage of the specialized vocabularies of biology, medicine, and chemistry is light. .PP Pertinent auxiliary files can be specified by name arguments, indicated below with their default settings (see FILES and VARIABLES). Copies of all output are accumulated in the history file. The stop list filters out misspellings (such as .CR thier=thy-y+ier ) that would otherwise pass. .PP Three routines help maintain and check the hash lists used by .CR spell : .RS .TP 15 .C hashmake Reads a list of words from the standard input and writes the corresponding nine-digit hash code on the standard output. .TP .CI spellin \ n Reads .I n hash codes from the standard input and writes a compressed spelling list on the standard output. Information about the hash coding is printed on standard error. .TP .C hashcheck Reads a compressed .I spelling_list and recreates the nine-digit hash codes for all the words in it; it writes these codes on the standard output. .RE .SH EXAMPLES To check spelling of a single .IR word : .IP .CI echo " word " "| spell" .PP If .I word is spelled correctly, a prompt is returned. If it is spelled incorrectly, .I word is printed before the prompt is returned. To check spelling of multiple words, they can also be typed as a group on the same command line: .IP .CI echo " worda wordb wordc ... " "| spell" .PP To create a personal spelling list that incorporates the words already present in the default American spelling list file .CR /usr/share/dict/hlista : .nf .IP .C cat /usr/share/dict/hlista | /usr/lbin/spell/hashcheck >tmp1 .C /usr/lbin/spell/hashmake >tmp1 .C sort -u -o tmp1 tmp1 .C /usr/lbin/spell/spellin `wc -l hlista .fi .PP To modify the default British spelling list file .CR /usr/share/dict/hlistb , replace all occurrences of .CR hlista with .CR hlistb in the above example. .PP To add words to the default spelling list, change login to .CR root , change the current working directory to .CR /usr/share/dict and execute the commands listed in the above example. .SH WARNINGS The spelling list's coverage is uneven. When undertaking the use of .CR spell as a new tool, it may be advisable to monitor the output for several months to gather local additions. Typically, these are kept in a separate local file that is added to the hashed .I spelling_list via .CR spellin , as shown above. .PP The British spelling feature was developed by an American. .PP Start-up versions of files .CR hlista , .CR hlistb , and .CR hstop are available in directory .CR /usr/newconfig/usr/share/dict . If these files or a suitable equivalent are not present in directory .CR /usr/share/dict , .CR spell complains: .IP .C "spell: cannot initialize hash table" .br .C "spell: cannot initialize hash table" .SH FILES .TP 38 .CR /usr/share/dict/hlist [ ab ] Hashed spelling lists, American and British. .PD 0 .TP .C /usr/share/dict/hstop Hashed stop list. .TP .C /var/adm/spellhist History file. .TP .C /usr/lbin/spell/spellprog Executable program file. .PD .SH VARIABLES .TP 15 .C D_SPELL Your hashed spelling list (default is .CR D_SPELL=/usr/share/dict/hlist [ ab ]) .PD 0 .TP .C H_SPELL Spelling history (default is .CR H_SPELL=/var/adm/spellhist ). .TP .C S_SPELL Your hashed stop list (default is .CR S_SPELL=/usr/share/dict/hstop ). .TP .C TMPDIR Directory for temporary files; overrides the default .CR /tmp . .PD .SH SEE ALSO deroff(1), sed(1), sort(1), tbl(1), tee(1). .SH STANDARDS CONFORMANCE .CR spell ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4spell\f1 \- find spelling errors@@@\f3spell(1)\f1 .\" index@\f1find spelling errors@@@\f3spell(1)\f1 .\" index@\f1spelling errors, find@@@\f3spell(1)\f1 .\" index@\f1errors, find spelling@@@\f3spell(1)\f1 .\" index@\f4hashcheck\f1 \- convert spelling reference list words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f1convert spelling reference list words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f4hashmake\f1 \- convert text words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f1convert text words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f4spellin\f1 \- convert 9-digit hash codes to compressed spelling reference list@@@\f3spell(1)\f1 .\" index@convert 9-digit hash codes to compressed spelling reference list@@@\f3spell(1)\f1 .\" index@\f1hash codes, convert 9-digit to or from text for spell checking@@@\f3spell(1)\f1 .\" .\" toc@\f3spell(1)\f1:\0\0\f4spell\f1, \f4hashmake\f1, \f4spellin\f1, \f4hashcheck\f1@@@find spelling errors\f1 .\" toc@\f4hashmake\f1:\0\0convert words to 9-digit hashcodes@@@\f1see \f3spell(1)\f1 .\" toc@\f4spellin\f1:\0\0create compressed spelling list from hash codes@@@\f1see \f3spell(1)\f1 .\" toc@\f4hashcheck\f1\0\0create hash codes from compressed spelling list@@@\f1see \f3spell(1)\f1 .\" .\" links@spell.1 hashmake.1 .\" links@spell.1 spellin.1 .\" links@spell.1 hashcheck.1 .\" $Header: spell.1,v 72.6 94/11/14 15:21:23 ssa Exp $ .TA s .TH spell 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME spell, hashmake, spellin, hashcheck \- find spelling errors .SH SYNOPSIS .C spell .RC [ -v ] .RC [ -b ] .RC [ -x ] .RC [ -l ] .RC [ -i ] .RC [ +\c .IR local_file \|] .RI [ \|files\| ] .PP .C /usr/lbin/spell/hashmake .PP .C /usr/lbin/spell/spellin .I n .PP .C /usr/lbin/spell/hashcheck .I spelling_list .SH DESCRIPTION The .CR spell command collects words from the named .I files and looks them up in a spelling list. Words that neither occur among nor are derivable (by applying certain inflections, prefixes, and/or suffixes) from words in the spelling list are printed on the standard output. If no .I files are named, words are collected from the standard input. .PP The .CR spell command ignores most .CR troff , .CR tbl , and .I eqn constructions. .SS Options The .CR spell command recognizes the following options: .RS .TP 15 .C -v All words not literally in the spelling list are printed, and plausible derivations from the words in the spelling list are indicated. .TP .C -b British spelling is checked. Besides preferring .CR centre , .CR colour , .CR programme , .CR speciality , .CR travelled , etc., this option insists upon .CR -ise in certain words, such as in .CR standardise . .TP .C -x Every plausible stem is printed with .CR = for each word. .RE .PP By default, .CR spell follows chains of included files much like .CR deroff (see .IR deroff (1)) which recognizes the .CR troff / nroff intrinsics .CR .so and .CR .nx , .I unless the names of such included files begin with .CR /usr/share/lib . If the .CR -l option is used, .CR spell follows the chains of .I all included files. With the .CR -i option, .CR spell ignores all chains of included files. .PP If the .CI + local_file option is used, words found in .I local_file are removed from .CR spell 's output. .I local_file is the name of a user-provided file containing a sorted list of words, one per line. With this option, the user can specify a set of words that are correct spellings (in addition to .IR spell 's own spelling list) for each job. .PP The spelling list is based on many sources, and while more haphazard than an ordinary dictionary, is also more effective with respect to proper names and popular technical words. Coverage of the specialized vocabularies of biology, medicine, and chemistry is light. .PP Pertinent auxiliary files can be specified by name arguments, indicated below with their default settings (see FILES and VARIABLES). Copies of all output are accumulated in the history file. The stop list filters out misspellings (such as .CR thier=thy-y+ier ) that would otherwise pass. .PP Three routines help maintain and check the hash lists used by .CR spell : .RS .TP 15 .C hashmake Reads a list of words from the standard input and writes the corresponding nine-digit hash code on the standard output. .TP .CI spellin \ n Reads .I n hash codes from the standard input and writes a compressed spelling list on the standard output. Information about the hash coding is printed on standard error. .TP .C hashcheck Reads a compressed .I spelling_list and recreates the nine-digit hash codes for all the words in it; it writes these codes on the standard output. .RE .SH EXAMPLES To check spelling of a single .IR word : .IP .CI echo " word " "| spell" .PP If .I word is spelled correctly, a prompt is returned. If it is spelled incorrectly, .I word is printed before the prompt is returned. To check spelling of multiple words, they can also be typed as a group on the same command line: .IP .CI echo " worda wordb wordc ... " "| spell" .PP To create a personal spelling list that incorporates the words already present in the default American spelling list file .CR /usr/share/dict/hlista : .nf .IP .C cat /usr/share/dict/hlista | /usr/lbin/spell/hashcheck >tmp1 .C /usr/lbin/spell/hashmake >tmp1 .C sort -u -o tmp1 tmp1 .C /usr/lbin/spell/spellin `wc -l hlista .fi .PP To modify the default British spelling list file .CR /usr/share/dict/hlistb , replace all occurrences of .CR hlista with .CR hlistb in the above example. .PP To add words to the default spelling list, change login to .CR root , change the current working directory to .CR /usr/share/dict and execute the commands listed in the above example. .SH WARNINGS The spelling list's coverage is uneven. When undertaking the use of .CR spell as a new tool, it may be advisable to monitor the output for several months to gather local additions. Typically, these are kept in a separate local file that is added to the hashed .I spelling_list via .CR spellin , as shown above. .PP The British spelling feature was developed by an American. .PP Start-up versions of files .CR hlista , .CR hlistb , and .CR hstop are available in directory .CR /usr/newconfig/usr/share/dict . If these files or a suitable equivalent are not present in directory .CR /usr/share/dict , .CR spell complains: .IP .C "spell: cannot initialize hash table" .br .C "spell: cannot initialize hash table" .SH FILES .TP 38 .CR /usr/share/dict/hlist [ ab ] Hashed spelling lists, American and British. .PD 0 .TP .C /usr/share/dict/hstop Hashed stop list. .TP .C /var/adm/spellhist History file. .TP .C /usr/lbin/spell/spellprog Executable program file. .PD .SH VARIABLES .TP 15 .C D_SPELL Your hashed spelling list (default is .CR D_SPELL=/usr/share/dict/hlist [ ab ]) .PD 0 .TP .C H_SPELL Spelling history (default is .CR H_SPELL=/var/adm/spellhist ). .TP .C S_SPELL Your hashed stop list (default is .CR S_SPELL=/usr/share/dict/hstop ). .TP .C TMPDIR Directory for temporary files; overrides the default .CR /tmp . .PD .SH SEE ALSO deroff(1), sed(1), sort(1), tbl(1), tee(1). .SH STANDARDS CONFORMANCE .CR spell ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4spell\f1 \- find spelling errors@@@\f3spell(1)\f1 .\" index@\f1find spelling errors@@@\f3spell(1)\f1 .\" index@\f1spelling errors, find@@@\f3spell(1)\f1 .\" index@\f1errors, find spelling@@@\f3spell(1)\f1 .\" index@\f4hashcheck\f1 \- convert spelling reference list words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f1convert spelling reference list words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f4hashmake\f1 \- convert text words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f1convert text words to 9-digit hash codes for \f4spell\f1@@@\f3spell(1)\f1 .\" index@\f4spellin\f1 \- convert 9-digit hash codes to compressed spelling reference list@@@\f3spell(1)\f1 .\" index@convert 9-digit hash codes to compressed spelling reference list@@@\f3spell(1)\f1 .\" index@\f1hash codes, convert 9-digit to or from text for spell checking@@@\f3spell(1)\f1 .\" .\" toc@\f3spell(1)\f1:\0\0\f4spell\f1, \f4hashmake\f1, \f4spellin\f1, \f4hashcheck\f1@@@find spelling errors\f1 .\" toc@\f4hashmake\f1:\0\0convert words to 9-digit hashcodes@@@\f1see \f3spell(1)\f1 .\" toc@\f4spellin\f1:\0\0create compressed spelling list from hash codes@@@\f1see \f3spell(1)\f1 .\" toc@\f4hashcheck\f1\0\0create hash codes from compressed spelling list@@@\f1see \f3spell(1)\f1 .\" .\" links@spell.1 hashmake.1 .\" links@spell.1 spellin.1 .\" links@spell.1 hashcheck.1 .\" $Header: split.1,v 76.2 95/08/23 17:37:50 ssa Exp $ .TA s .TH split 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME split \- split a file into pieces .SH SYNOPSIS .C split .RC [ -l .IR line_count\| ] .RC [ -a .IR suffix_length\| ] .RI [ \|file .RI [ \|name\| ]] .PP .C split .RC [ -b .I n\c .RC [ k \(or m ]\|] .RC [ -a .IR suffix_length\| ] .RI [ \|file .RI [ \|name\| ]] .PP .I Obsolescent: .br .C split .RC [ -\c .IR n\fP\| ] .RI [ \|file .RI [ \|name\| ]\|] .SH DESCRIPTION .C split reads .I file and writes it in pieces (default 1000 lines) onto a set of output files. The name of the first output file is .I name with .C aa appended, and so on lexicographically, up to .C zz (only .SM ASCII letters are used, a maximum of 676 files). If no output .I name is given, .C x is the default. .PP If no input .I file is given, or if .C - is given instead, the standard input file is used. .SH OPTIONS .C split recognizes the following command-line options and arguments: .RS .TP 15 .CI -l \0line_count The input file is split into pieces .I line_count lines in size. .TP .CI -a \0suffix_length .I suffix_length letters are used to form the suffix of the output filenames. This option allows creation of more than 676 output files. The output file names created cannot exceed the maximum file name length allowed in the directory containing the files. .TP .CI -b \0n The input file is split into pieces .I n bytes in size. .TP .CI -b \0n k The input file is split into pieces .I n \(mu 1024 bytes in size. No space separates the .I n from the .CR k . .TP .CI -b \0n m The input file is split into pieces .I n \(mu 1\|048\|576 bytes in size. No space separates the .I n from the .CR m . .TP .CI - n The input file is split into pieces .I n lines in size. This option is obsolescent and is equivalent to using the .CI -l \0line_count option. .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_CTYPE determines the locale for the interpretation of text as single- and/or multi-byte characters. .PP .CR LC_MESSAGES determines the language in which messages are displayed. .PP If .CR LC_CTYPE or .CR LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C split behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH SEE ALSO bfs(1), csplit(1). .SH "STANDARDS CONFORMANCE" .CR split ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" index@\f4split\f1 \- split a file into multiple \f2n\f1-line pieces@@@\f3split(1)\f1 .\" index@\f1split a file into multiple \f2n\f1-line pieces@@@\f3split(1)\f1 .\" index@\f1multiple \f2n\f1-line pieces, split a file into@@@\f3split(1)\f1 .\" index@\f1files: split a file into multiple \f2n\f1-line pieces@@@\f3split(1)\f1 .\" index@\f1files: break a single file into multiple files@@@\f3split(1)\f1 .\" index@\f1break a file into multiple \f2n\f1-line pieces@@@\f3split(1)\f1 .\" index@\f1separate a file into multiple \f2n\f1-line pieces@@@\f3split(1)\f1 .\" .\" toc@\f3split(1)\f1:\0\0\f4split\f1@@@split a file into pieces .\" .\" $Header: ssp.1,v 72.3 93/01/14 11:17:07 ssa Exp $ .TA s .TH ssp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ssp \- remove multiple line-feeds from output .SH SYNOPSIS .C ssp .SH DESCRIPTION .C ssp (single-space) removes redundant blank lines from the standard input and sends the result to the standard output. All blank lines at the beginning of a file are removed, and all multiple blank lines elsewhere in the file (including end-of-file) are reduced to a single blank line. .PP .C ssp is typically used in pipelines such as .IP .C nroff -ms file1 | ssp .PP .C ssp is equivalent to the 4.2BSD .C cat -s command. .PP To remove all blank lines from a file except at beginning of file, use .C rmnl (see .IR rmnl (1)). To remove all blank lines from a file including beginning of file, use .C rmnl piped to .CR ssp , or .C ssp piped to .CR rmnl . .SH SEE ALSO cat(1), rmnl(1). .\" .\" toc@\f3ssp(1)\f1:\0\0\f4ssp\f1@@@remove multiple line-feeds from output .\" .\" index@\f4ssp\f1 \- remove multiple line-feeds from output@@@\f3ssp(1)\f1 .\" index@remove multiple line-feeds from output@@@\f3ssp(1)\f1 .\" index@multiple line-feeds, remove from output@@@\f3ssp(1)\f1 .\" index@multiple adjacent blank lines, reduce to single blank line@@@\f3ssp(1)\f1 .\" index@eliminate multiple adjacent blank lines, reduce to single blank line@@@\f3ssp(1)\f1 .\" index@reduce multiple adjacent blank lines to single blank line@@@\f3ssp(1)\f1 .\" index@files: reduce multiple adjacent blank lines to single blank line@@@\f3ssp(1)\f1 .\" index@blank lines, reduce multiple adjacent to single blank line@@@\f3ssp(1)\f1 .\" index@lines, reduce multiple adjacent blank to single blank line@@@\f3ssp(1)\f1 .\" index@line-feeds, remove multiple from output@@@\f3ssp(1)\f1 .\" .\" fileset_database@ssp.1 USER-CMDS-MAN .TH STCONV 1M "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.0 July 1994 .SH NAME stconv - Utility to convert scalable type symbol set map formats .SH SYNOPSIS .B stconv \fIinfile\fP [-hmq] [-d \fImapdir\fP] [-to \fIACG|HPMSL|other\fP] .SH DESCRIPTION .P The \fIstconv\fP utility is used to convert scalable typeface symbol set maps (\fB.sym\fP files) for Intellifont fonts from one symbol list numbering format to another. The installation default symbol sets map their respective symbols into appropriate HP Master Symbol List character codes (the default format provided in \fB.ifo\fP typeface libraries). Since it is possible, however, to use \fIstload(1M)\fP to generate \fB.ifo\fP libraries that use some other symbol list numbering (such as native Agfa Compugraphic \fBACG\fP numbering), \fIstconv\fP provides a way to modify existing \fB.sym\fP files to map characters to non-MSL numbers. .P A \fIsymbol list\fP assigns a unique numeric value to each individual character in the global collection of characters available from a specific typeface manufacturer. The specific numbering scheme used is usually unique to that vendor, and typically identifies hundreds or even thousands of characters. A \fIsymbol set\fP (or \fIcharacter set\fP) is generally a particular subset of characters taken from this master collection, with each character being assigned another unique code in accordance with the some specific registry/encoding scheme (such as ISO8859 Latin-1 or HP Roman-8). In this respect, the \fB.sym\fP files used by the HP Scalable Type subsystem are actually \fIsymbol set maps\fP, equating all the character codes comprising a specific character set registry/encoding to the corresponding character numbers of a particular typeface vendor's symbol list. .P Intellifont format scalable typeface libraries are commercially available with HP Master Symbol List character numbering (HPMSL) in products obtained from the HP MasterType Library, and with Agfa Compugraphic symbol list numbering (ACG) for products from the Agfa Typeface Library. .SH OPTIONS There are several command line parameters which are described below. .TP 8 .B \fIinfile\fP Required name of the \fB.sym\fP file to be converted. .TP 8 .B \-d \fImapdir\fP Specifies the name of the directory containing the symbol list conversion map (see below). This directory should contain the file \fBACG-HPMSL\fP, plus any optional additional symbol list maps. If unspecified, \fIstconv\fP looks for an appropriate map in \fI/usr/lib/X11/fonts/stadmin/ifo/charsets\fP. The file \fBACG-HPMSL\fP defines the translation between Agfa Compugraphic symbol list numbering and HP Master Symbol List numbering. .TP 8 .B \-h Requests help. .TP 8 .B \-m Requests that \fIstconv\fP list the conversion map. .TP 8 .B \-q Requests that \fIstconv\fP should run quietly. .TP 8 .B \-to \fIformat\fP Specifies the new symbol list format. The installation-default symbol sets use \fBHPMSL\fP format; to generate a symbol set for native Agfa Compugraphic symbol list character codes, you should specify \fB-to ACG\fP. .ne 6 .SH EXAMPLES .TP 8 .B stconv -to ACG roman8.sym >acgr8.sym .br This reads the HPMSL symbol map \fBroman8.sym\fP, and writes the ACG version to \fBacgr8.sym\fP via stdout redirection. The new symbol map can subsequently be used to generate an HP Roman-8 font from an Agfa Typeface Library product. .SH SYMBOL LIST CONVERSION MAPS A \fIsymbol list conversion map\fP defines the translation of character numbers between two different symbol lists. The map is a simple text file contain two columns of character codes: the first column is the first format's character code, the second column is the second format's character code. Lines that begin with anything other than two distinct values are ignored. The name of the conversion must be the names of the two formats concantenated together with a hyphen, with care taken to insure the name before the hyphen reflects the numbering scheme used in the first column, and the name after the hyphen reflects the numbering scheme used in the second column. A single conversion map file is sufficient for converting a symbol list of either format into a symbol list of the opposite format. As an example, the first few lines of the file \fBACG-HPMSL\fP are: .NF # ACG-HPMSL # First column is ACG number # Second column is corresponding HPMSL number 1 86 2 81 3 74 4 80 .FI .SH FILES \fIStconv\fP takes input only from the specified file, and always sends output to \fBstdout\fP. .SH NOTE \fIStconv\fP supports only the \fB.sym\fR files used for Intellifont scalable fonts, and has no application to other types of scalable fonts (such as Type 1). .SH "SEE ALSO" stlicense(1M), stmkfont(1), stmkdirs(1), stload(1M) .SH COPYRIGHT (c) Copyright 1990, Hewlett-Packard Company .br See \fIX(1)\fP for a full statement of rights and permissions. .TH STLICENSE 1M "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.0 July 1994 .SH NAME stlicense - server access control program for X .SH SYNOPSIS .B stlicense [-v] [-fp directory] {-fn typeface | -pr product} [[+-]netdev ...] .SH DESCRIPTION .PP The \fIstlicense\fR program is run interactively by the font administrator to give devices attached to hosts on the network, \fBnetdev\fPs, access to typefaces. Responsibility for maintaining security rests with users .IR "root" "," .IR "bin" "," and the owners of the font directories. .SH OPTIONS \fIstlicense\fR accepts the command line options described below. .TP 8 .BI "-fp " "directory" The path of directories to search for the specified product or typeface. The directories must have the suffix .st or they will be ignored. If several directories are specified, they are separated by the colon (":") character. Stlicense will search the path until it finds a directory that contains the specified product or typeface. It will use that directory for all of its operations. If no \fB-fp\fP option is specifies, the value of environment variable \fBSTPATH\fP is used. If neither \fB-fp\fP nor \fBSTPATH\fP is present, the default path is \fB/usr/lib/X11/fonts/ifo.st\fR. .TP 8 .BI "-fn " "typeface" The typeface being licensed. It is specified as an XLFD font name. The entire font name does not have to be specified. The program will use the first typeface whose name matches the name specified. .TP 8 .BI "-pr " "product" Specifying a product instead of a typeface provides a convenient way to license collections of typefaces. Product names are established when typefaces are loaded. Use either the \fB-fn\fR or the \fB-pr\fR option, but never both. One of them must be present for license additions or removals. .TP 8 .B "-v " The verbose option controls the number of messages returned. By default, stlicense prints messages only when a request could not be fulfilled. With the verbose option, status messages are printed for all licensing requests. .TP 8 .B "-help " If this is the only option specified, a brief message listing the valid options to \fIstlicense\fP will be printed. .TP 8 .BI "+" "netdev" The netdev is granted a license to the product or typeface specified. Adding a product license to the netdev means adding licenses to all of the typefaces which comprise the product. .TP 8 .PP The netdev is specified in the form \fIhost\fB:\fIdevice. \fRThe host name is a node on the network. They can be discless nodes, workstations, and the like. The device, usually a printer, is attached to the host. The name of the device must be a valid file name. .TP 8 .PP Special host STSYSTEM refers to all nodes on the network; typefaces licensed to STSYSTEM are available to every host. Special device DISPLAYS refers to all servers running on the host. Special device PRINTERS refers to all printers connected to the host. .TP 8 .PP The \fIhost\fP defaults to the host on which \fIstlicense\fP is running. The \fIdevice\fP defaults to DISPLAYS. Adding a product license to a netdev which already has a license for the product causes the netdev's fonts.dir file to be updated with the current definition of the product. .PP .TP 8 .BI "-" "netdev" The license for specified typeface or product is removed from this netdev. .PP .TP 8 .I "netdev" The products/typefaces licensed for this netdev are displayed. If the -pr or -fn option is specified, stlicense reports whether the specified product or typeface is licensed for this netdev. In the case of typefaces, only those that have been individually licensed with the -fn option (that is, not licensed as part of a product with the -pr option) can be queried by this option. .sp As with addition and removal of licenses, the \fIhost\fP and \fIdevice\fP portions of the \fInetdev\fP specification default to `hostname` and DISPLAYS (respectively). So running \fIstlicense\fR without any [+|-]\fInetdev\fP arguments is identical to specifying an argument of `hostname`:DISPLAYS; licensing information is returned for device DISPLAYS for the host on which \fIstlicense\fP is running. .SH FILES This program updates the netdev's license files in the \fBlicenses\fP subdirectory of the typeface directory (\fB*.st\fP). It creates and deletes licensing files as necessary. If files for the netdev do not exist, it creates them. Deleting the last license from a netdev will cause the netdev's licensing files to be deleted. .PP Hosts have directories in \fBlicenses\fP. Devices have directories within their host's directory. Typefaces available to the netdev are stored in \fBfonts.dir\fP. Product licenses issued to the netdev are stored in \fBproducts.dir\fP. .PP The typefaces that comprise valid products are specified in the \fBproducts\fP directory of typeface directories (\fB*.st\fP). .SH EXAMPLES .B stlicense -pr builtin +STSYSTEM:DISPLAYS .sp .5 Licenses the Intellifont fonts contained in the product "builtin" (and listed in /usr/lib/X11/fonts/ifo.st/products/builtin) for all displays. .B stlicense -fp /usr/lib/X11/fonts/type1.st -pr builtin +STSYSTEM:DISPLAYS .sp .5 Licenses the Type 1 fonts contained in the product "builtin" (and listed in /usr/lib/X11/fonts/type1.st/products/builtin) for all displays. .SH "SEE ALSO" stload (1M), stmkfont(1), stconv(1M), stmkdirs(1) .SH COPYRIGHT Copyright 1990, Hewlett-Packard Company .br See \fIX(1)\fP for a full statement of rights and permissions. .TH STLOAD 1M "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.0 July 1994 .SH NAME stload - Utility to load Scalable Type outlines .SH SYNOPSIS .B stload [options] \fIdirectory|filespec...\fP .SH DESCRIPTION .P The \fIstload\fP utility creates scalable typeface libraries (\fB.ifo\fP files) from Agfa Compugraphic Font Access and Interchange Standard (CG/FAIS) data. (An FAIS library on floppy disk or CD-ROM media is the common means of distribution for scalable typeface products that is compatible with the HP Font Server and Scalable Typeface subsystem implementation. It is also is the distribution format used by HP Type Director/DOS and the HP MasterType library of scalable typeface floppy disks.) \fIStload\fP also simplifies the installation of new symbol sets and existing \fB.ifo\fP files from an archive repository, creates Tagged Font Metric \fB.tfm\fP files, and establishes new product entries in the Scalable Typeface licensing structure. \fIStload\fP should generally be run interactively by the system font administrator to load new scalable typefaces into a Scalable Typeface directory. .P Several typefaces come bundled with the Scalable Typeface system and are automatically installed with the product; additional typefaces may be acquired separately. Since new typefaces are generally distributed on MS-DOS floppy media, the system administrator may need to use utilities such as \fIdoscp\fP or \fIcp\fP to transfer the typeface files from the distribution media to a temporary location on the target system. CG/FAIS file naming conventions prohibit multiple CG/FAIS diskettes from being copied into a common repository, so you should create a unique directory on the host system to contain each CG/FAIS diskette you load. Once all of the CG/FAIS typeface files have been loaded onto the target system, \fIstload\fP is used to compile them into \fB.ifo\fP scalable typeface libraries and install the libraries in an appropriate \fItypefaces\fP directory. .P \fIStload\fP does not grant licensed access to newly-installed typefaces. Font administrators must use the \fIstlicense\fP utility to give devices access to new typefaces. .SH OPTIONS There are several command line options which are described below. .TP 8 .B \fIdirectory|filespec\fP This is a required parameter specifying the name of the directory or filespec of the data to be loaded. You may specify one or more directories containing the FAIS data extracted from a typeface distribution diskette, or one or more repositories containing \fB.ifo\fP and/or \fB.sym\fP files, or explicit or wildcarded filespecs of existing \fB.ifo\fP and/or \fB.sym\fP files. .TP 8 .B \-d \fImapdir\fP Specifies the directory containing the symbol list map required by the \fB-to \fIformat\fR option. This directory must contain the file \fBACG-HPMSL\fP, plus any optional additional symbol list maps. If left unspecified, \fIstload\fP assumes the symbol list maps can be found in \fI/usr/lib/X11/fonts/stadmin/ifo/charsets\fP. .TP 8 .B \-dos Specifies that the typeface library should be written as a TypeDirector/DOS \fB.typ\fP file. Typefaces libraries written in this format cannot be used by the HP-UX Scalable Type subsystem, but have the feature of being expandable -- you can add new typefaces to an existing DOS format library. (See ``EXAMPLES'' below for more details.) .TP 8 .B \-f \fIlibname\fP Specifies the name of the scalable typeface library into which FAIS data should be loaded. Normally, loading from FAIS data generates a separate \fB.ifo\fP or \fB.typ\fP library file for each typeface, and each library file's name indicates that particular typeface's ID and character complement code. The \fB-f\fP option overrides this automatic naming convention and lets you add typefaces into a single library with any arbitrary name. .TP 8 .B \-fp \fIpath\fP Specifies the name of the base directory under which \fItypefaces\fP, \fImetrics\fP, and \fIproducts\fP directories should be used as the target directories for typeface, metric, and product definition files. These directories will be created as necessary if they don't already exist. Any attempt to load typeface, metric, and product definition files elsewhere by using the \fB-o\fP option will be ignored. (If neither the \fB-fp\fP nor \fB-o\fP options are specified, the default base directory is \fI/usr/lib/X11/fonts/ifo.st\fP. See \fB-o\fP below for more option information.) .sp Note that \fB-fp\fP does \fInot\fP affect where \fB.sym\fP files will be loaded. Unless you use the \fB-o\fP option to direct them elsewhere, symbol sets will still be installed into \fI/usr/lib/X11/fonts/stadmin/ifo/charsets\fP. .TP 8 .B \-h Requests help. \fBStload\fP will print out a command line syntax summary and a list of command line switch options. No other processing will take place. .TP 8 .B \-id[,id...] Identifies one or more specific typefaces to be loaded from CG/FAIS data. Normally, \fIstload\fP installs all of the typefaces it can find, loading each typeface into its own \fB.ifo\fP file. If you wish to install only one or two specific faces, you must use this option. (Specific typeface numbers can be determined by using \fBstload -list\fP to examine the contents of the FAIS directory; the "Face" column reveals typeface IDs.) .TP 8 .B \-link Causes \fIstload\fP to install files in the output directory by making \fIhard links\fP back to the original repository in \fIdirectory\fP. Note that this works only when loading \fB.sym\fP files and pre-existing \fB.ifo\fP files. The default behavior (when this option is not specified) is to copy the \fB.ifo\fP and \fB.sym\fP files unmodified to the output directory. All \fB.ifo\fP files loaded from FAIS data are created as new files in the output directory. .TP 8 .B \-list Prints a list of the data located in \fIdirectory\fP on the standard output device. The directory may contain either FAIS data, \fB.ifo\fP typeface libraries, or \fB.sym\fP symbol set files. No other processing takes place. .TP 8 .B \-o \fIpath\fP Specifies the name of the output directory in which to write the final \fB.ifo\fP, \fB.sym\fP, and \fB.tfm\fP files. If the directory does not exist, \fIstload\fP will attempt to create it. If left unspecified, these files will be written to the following default output directories: .NF write \fB.ifo\fP files to \fI/usr/lib/X11/fonts/ifo.st/typefaces\fP write \fB.sym\fP files to \fI/usr/lib/X11/fonts/stadmin/ifo/charsets\fP write \fB.tfm\fP files to \fI/usr/lib/X11/fonts/ifo.st/metrics\fP .FI .TP 8 .B \-p \fIproduct-number\fP Associates a product number with newly-loaded typefaces (\fB.ifo\fP files). Although this can be any arbitrary filename-sized string, it should reflect the product number printed on the typeface distribution package and media. The \fIstlicense\fP utility requires this product number in order to license loaded typefaces for use with specific devices. Product numbers are written into a \fIproducts\fP directory at the same directory level as the \fB.ifo\fP output directory. For example, if you specified the \fB-o\fP \fIpath\fP option, product numbers will be written to \fIpath/../products\fP; if you do not specify the any output directory, product numbers will be written to files in \fI/usr/lib/X11/fonts/ifo.st/products\fP. The \fIproducts\fP directory will be automatically created if it does not already exist. .TP 8 .B \-sym Causes \fIstload\fP to install files the output directory by making \fIsymbolic links\fP back to the original repository in \fIdirectory\fP rather than by copying the original files. Note that this works only for loading \fB.sym\fP files and pre-existing \fB.ifo\fP files. All \fB.ifo\fP files loaded from FAIS data are created as new files in the output directory. .TP 8 .B \-tfm Causes \fIstload\fP to update Tagged Font Metric \fB.tfm\fP files in the output directory (or in \fI/usr/lib/X11/fonts/ifo.st/metrics\fP if no output directory is specified). .TP 8 .B \-to \fIformat\fP Specifies the symbol list that should be used for assigning character ID codes when loading FAIS data. If left unspecified, character IDs will be assigned in accordance with the HP Master Symbol List (HPMSL); to retain Agfa Compugraphic (native FAIS) ID numbers, you should specify \fB-to ACG\fP. .TP 8 .B \-u Specifies that the \fB.dir\fP files should \fInot\fP be updated. Stload normally automatically uses the \fIstmkdirs\fP utility to update the \fBfonts.dir\fP, \fBcharsets.dir\fP, and \fBmetrics.dir\fP files in the output directory or directories. The \fB-tfm\fP option should not be used with this option, since \fB-tfm\fP requires current \fBfonts.dir\fR files for correct operation. .TP 8 .B \-v Specifies that \fBstload\fP should run verbosely. .SH EXAMPLES .TP 8 \fBstload -p C2050A#D15 .\fP Compiles the CG/FAIS data in the current directory and puts the resulting .ifo files in \fI/usr/lib/X11/fonts/ifo.st/typefaces.\fP Existing .ifo files in the current directory will also be copied; existing .sym files will be copied into \fI/usr/lib/X11/fonts/stadmin/ifo/charsets\fP; appropriate .tfm files will be added to \fI/usr/lib/X11/fonts/ifo.st/metrics.\fP The product number required for future licensing of these typefaces by \fBstlicense\fP is C2050A#D15. \fBFonts.dir\fP, \fBcharsets.dir\fP, and \fBmetrics.dir\fP are updated to reflect the additions. .ne 6 .TP 8 \fBstload -o . -dos -f big3.ifo -92500 times\fP .nf .in -4 \fBstload -o . -dos -f big3.ifo -93717 courier\fP \fBstload -o . -p BIG3 -f big3.ifo -92041 univers\fP .in +4 .fi Compiles three different CG/FAIS typefaces into a single .ifo library. The library must be explicitly named to prevent stload from assigning names, and all but the last typeface must be loaded in DOS format to keep the library expandable. The final invocation loads the last typeface, converts the complete DOS library into true .ifo format, and makes the typefaces licensable via the product name BIG3. .TP 8 \fBstload -list /usr/lib/X11/fonts/ifo.st/typefaces\fP Lists all of the typefaces currently contained in \fI/usr/lib/X11/fonts/ifo.st/typefaces.\fP .SH FILES Remember that \fIstload\fP requires write access to the directory that will contain the compiled typeface libraries. This implies that only the system font administrator should be able to add typefaces to the typeface collection in \fI/usr/lib/X11/fonts/ifo.st/typefaces\fP. The files \fIfonts.dir\fP, \fIcharsets.dir\fP, and \fImetrics.dir\fP will be automatically updated to reflect additions. Typeface licenses are not modified. .SH RESTRICTIONS Stload can process a maximum of 20000 glyphs per typeface. .SH "SEE ALSO" stlicense(1M), stmkfont(1), stmkdirs(1), stconv(1M) .SH COPYRIGHT (c) Copyright 1990, Hewlett-Packard Company .br See \fIX(1)\fP for a full statement of rights and permissions. .TH STMKDIRS 1 "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.0 July 1994 .SH NAME stmkdirs - Utility to build Scalable Type ``.dir'' and ``.tfm'' files. .SH SYNOPSIS .B stmkdirs [options] \fIdirectory\fP [\fIdirectory\fP ...] .SH DESCRIPTION .P The \fIstmkdirs\fR utility is used to support Intellifont and Type 1 scalable fonts. It creates the \fBfonts.dir\fR, \fBcharsets.dir\fR, and \fBmetrics.dir\fR files used by the Font Server and Scalable Type subsystem. .P \fIStmkdirs\fR supports scalable typefaces as follows: .TP 8 .B Intellifont \&\fIStmkdirs\fR can be used to generate \fBfonts.dir\fR files containing entries for Intellifont outline files, \fBcharsets.dir\fR files cataloging character sets for Intellifont fonts, Tagged Font Metrics (\fB.tfm\fR) files describing font metrics for Intellifont outlines, and \&\fBmetrics.dir\fR files cataloging \fB.tfm\fR files. .TP 8 .B Type 1 \&\fIStmkdirs\fR can generate \fBfonts.dir\fR files containing entries for Type 1 outline files. .SH OPTIONS There are several command line options which are described below. .TP 8 .B \fIdirectory\fP This specifies the names of one or more directories to be processed. At least one \fIdirectory\fP parameter must be specified. \fIStmkdirs\fR will create whatever \fI.dir\fR files are needed in a directory: if a directory contains bitmapped fonts or font outlines, it will create or update \fBfonts.dir\fR; if character set files, \fBcharsets.dir\fR; if TFM files, \fBmetrics.dir\fR. .TP 8 .B \-d \fIdirectory\fP Specifies the directory containing default character set (.sym) files and the symbol list map (such as \fBACG-HPMSL\fP) required by the \fB-tfm \fIdirectory\fR option in order to construct TFM files. If left unspecified, \fIstmkdirs\fP assumes the this directory to be \fI/usr/lib/X11/fonts/stadmin/ifo/charsets\fP. Character set files will be taken from this directory only if none are found in any of the processed directories. .TP 8 .B \-sl \fIsyms\fR The \fB-sl\fR switch informs \fIstmkdirs\fR that the font library (.ifo) files being processed conform to some symbol list other than HP Master Symbol List (HPMSL). This information is necessary for generation of correct TFM files. For example, for a font loaded by \fIstload\fR with the ACG symbol list, \fB-sl ACG\fR should be used in the \fIstmkdirs\fR invocation to ensure placing correct information in the TFM files. .TP 8 .B \-tfm \fIdirectory\fP The \fB-tfm\fP switch instructs \fIstmkdirs\fP to build Tagged Font Metrics (TFM) files in the specified directory. TFM files contain font metrics information used by some applications to determine information such as character spacing. Data in the TFM files is gleaned from typeface library \fB.ifo\fP files and from character set \fB.sym\fP files; TFM files will not be built if \fIstmkdirs\fR does not find the required library and character set files. (If \&\fIstmkdirs\fR does not find character set files in any of the directories it processes, it will use the character set files in /usr/lib/X11/fonts/stadmin/ifo/charsets unless pointed elsewhere via the \fB-d\fP option). TFM files are generated only for Intellifont outlines. .P The default behavior of \fIstmkdirs\fR is to attempt to generate complete \fBfonts.dir\fR, \fBcharsets.dir\fR, and \fBmetrics.dir\fR files in all directories specified. You can cause certain items to \&\fInot\fP be generated or included in the final files by using ``-'' suppression options. Similarly, to generate \fIonly\fP certain items, you should use one or more ``+'' options. .P The command line is processed from left to right, making it possible for you to apply different options to different directories all in the same command. To avoid confusing behavior you should therefore take care to specify all switch options \fIbefore\fP specifying directory names. .P Data inclusion and exclusion switches include: .TP 8 .B \+c Requests that \fBcharsets.dir\fP be generated. .TP 8 .B \-c Requests that \fBcharsets.dir\fP \fInot\fP be generated. .TP 8 .B \+f Requests that \fBfonts.dir\fP be generated and should include \fB.ifo\fP scalable typeface libraries as well as other bitmap fonts (those normally found by \fImkfontdir\fP). This is equivalent to requesting \fB+mo\fP. .TP 8 .B \-f Requests that \fBfonts.dir\fP \fInot\fP be generated. .TP 8 .B \+m Requests that \fBfonts.dir\fP be generated and should include bitmap fonts (those normally found by \fImkfontdir\fP). .TP 8 .B \-m Requests that bitmap fonts (those normally found by \fImkfontdir\fP) be \fIexcluded\fP from any newly generated \fBfonts.dir\fP. .TP 8 .B \+o Requests that \fBfonts.dir\fP be generated and should include \fB.ifo\fP scalable typeface libraries. .TP 8 .B \-o Requests that \fB.ifo\fP, \fB.pfa\fP, and \fB.pfb\fP scalable typeface libraries be \fIexcluded\fP from any newly generated \fBfonts.dir\fP. .TP 8 .B \+r Requests that \fBmetrics.dir\fP be generated. .TP 8 .B \-r Requests that \fBmetrics.dir\fP \fInot\fP be generated. .P Additional switches include: .TP 8 .B \-a Ensures that any symbol set catalogued in \fBcharsets.dir\fP can be used with any \fB.ifo\fP scalable typeface library catalogued in \fBfonts.dir\fP. (Normally, the Font Server recognizes only combinations in which the typeface library actually contains all or most of the glyphs specified by the symbol set.) .TP 8 .B \-b Suppress creation of backup files. Normally, whenever \fIstmkdirs\fP constructs a new \fBfonts.dir\fP, \fBcharsets.dir\fP, or \&\fBmetrics.dir\fR file, any pre-existing old version of that file is renamed (to its original name with a tilde ``~'' appended) rather than overwritten. The \fB-b\fP option disables this feature. .TP 8 .B \-h Print usage information on stdout. .SH "STMKDIRS VERSUS MKFONTDIR" When generating \fBfonts.dir\fR files, \fIstmkdirs\fR acts like an extended version of the \fImkfontdir(1)\fR utility. In addition to recognizing the bitmapped font files handled by \fImkfontdir\fR, \&\fIstmkdirs\fR recognizes Intellifont (\fB.ifo\fR) and Type 1 (\fB.pfa\fR and \&\fB.pfb\fR) font files, and adds entries for them to the \fIfonts.dir\fR file. .P As with \fImkfontdir\fR, the \fIfonts.scale\fR can be used to add entries for file types not recognized by \fIstmkdirs\fR. However, \&\fIfonts.scale\fR is not needed for Intellifont and Type 1 scalable fonts. .SH EXAMPLES .TP 8 .B stmkdirs -tfm /usr/lib/X11/fonts/ifo.st/metrics /usr/lib/X11/fonts/ifo.st/typefaces Requests that \fBfonts.dir\fP and, if appropriate, \fBcharsets.dir\fP files be built in \fI/usr/lib/X11/fonts/ifo.st/typefaces\fP. In addition, the \fB-tfm\fP switch requests that \fB.tfm\fP files plus an appropriate \fBmetrics.dir\fP file be built in \fI/usr/lib/X11/fonts/ifo.st/metrics\fP. .TP 8 .B stmkdirs /usr/lib/X11/fonts/type1.st/typefaces Generates a \fBfonts.dir\fR in the /usr/lib/X11/fonts/type1.st/typefaces directories. .SH "SEE ALSO" stlicense(1M), stmkfont(1), stload(1M) .SH COPYRIGHT Copyright 1990, Hewlett-Packard Company .br See \fIX(1)\fP for a full statement of rights and permissions. .TH STMKFONT 1 "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.0 July 1994 .SH NAME stmkfont - Scalable Typeface font compiler to create X and PCL fonts .SH SYNOPSIS .B stmkfont [options] .I xlfdname .SH DESCRIPTION The \fIstmkfont\fR utility is a bit-mapped font generator for creating X and PCL fonts from Intellifont scalable typeface data. By specifying desired font characteristics via an \fIX Logical Font Description\fR (XLFD) name, the user can instruct \fIstmkfont\fR to generate an almost limitless variety of font flavors from one or more Agfa Compugraphic Intellifont typeface libraries. Possible output formats are \fBBDF\fR, and \fBPCL\fR for various HP printers. .SH REQUIRED PARAMETERS .TP 8 .B \fIxlfdname\fR The last argument on the command line is always assumed to be the \fIrequired XLFD name\fR. The XLFD name is the means by which you specify the typeface, font size, and additional treatments for the final font. (See \fBxlfd(3)\fR for information on XLFD construction). The XLFD name should begin with a field-delimiter hyphen and specify from one to fourteen contiguous fields. If less than 14 fields are given, \fIstmkfont\fR will automatically append wildcard fields to fill the name out to fourteen. \fIStmkfont\fR then attempts to qualify the XLFD name by looking for a matching scalable typeface descriptor in \fBfonts.dir\fR, and upon finding a one, proceeds to build the font. .SH SWITCH OPTIONS .TP 8 .B \-C Output a catalog of typeface/character set combinations on stderr. For the given XLFD specification, \fIstmkfont\fR will generate a list of fully qualified XLFD names that reflect the various typefaces and character sets that could be used to construct a final font. No font is generated when this option is used. .TP 8 .B \-I Send additional status information to stderr, such as the requested and final XLFD names, return status of the underlying \fIstmkfont()\fR call, and a list of characters that either failed font generation or were not in the symbol set. .TP 8 .B \-P Send ``one\-percent progress dots'' to stderr. As \fIstmkfont\fR constructs the final font, it will output a stream of period characters at regular time intervals. Exactly 100 periods will be output; when the 100th dot has been sent, the font is ready. .TP 8 .B \-S If one of the PCL output formats is requested, this option causes \fIstmkfont\fR to output to stderr the PCL selection string required to select the resulting font on the PCL printer. .TP 8 .B \-T Suppress temporary output file. In its normal mode of operation, \fIstmkfont\fR takes time to ``dribble'' output into a \fB/tmp\fR tempfile, and then quickly ``burst'' copy the complete tempfile to the actual output file or device. While this file re-copy does cause \fIstmkfont\fR to take somewhat longer to produce results, it minimizes the amount of time that a parent process must spend ``listening'' to \fIstmkfont\fR's output. If overall speed is more critical than time spent actually writing the final output, this switch can be used to bypass the tempfile and ``dribble'' output directly to the final destination. .TP 8 .B \-V Requests that a fully qualified XLFD name be sent to stderr without continuing to generate final output. .TP 8 \fB\-cf \fICharsetFile\fR .in -4 .nf \fB\-cp \fICharsetPath\fR .fi .in +4 These options allow you to specify the subdirectory (under one of the database directories) and/or filename of a symbol set mapping file. Once \fIstmkfont\fR has determined the name of the scalable typeface library it will use, it extracts the filename extension from the library's name, and uses it in conjunction with \fICharsetPath\fR, \fICharsetFile\fR, and the database directory trees \fIPrimary\fR and \fIAlternate\fR to locate an appropriate character set map. \fIStmkfont\fR will look for \fICharsetFile\fR (or \fBcharsets.dir\fR) in several directories, in the following order: .nf 1. \fIPrimary\fB/\fITypefaceExtension\fB/\fICharsetPath\fR 2. \fIAlternate\fB/\fITypefaceExtension\fB/\fICharsetPath\fR 3. {\fISTPATH\fR}\fB/\fITypefaceExtension\fB/\fICharsetPath\fR .fi If left unspecified, the default \fICharsetPath\fR is \fBcharsets\fR, and the default \fICharsetFile\fR is determined by scanning the above directories for \fBcharsets.dir\fR, then using the \fBCharset Registry\fR and \fBCharset Encoding\fR properties of the XLFD name to extract from it a charset map filename. \fINote: In the above directory search hierarchy there should normally exist only one charsets.dir file. Stmkfont will stop searching when the first charsets.dir is encountered. If that charsets.dir does not contain an appropriate registry/encoding to match the XLFD name, stmkfont will be unable to generate the requested font.\fR .sp In practice, the character sets are usually found in the \fIAlternate\fR directory's \fICharsetPath\fR subdirectory. When this product is installed, for example, the character sets are placed in the \fB/usr/lib/X11/fonts/stadmin/ifo/charsets\fR directory, where \fIstmkfont\fR finds them with the default \fIAlternate\fR and \fICharsetPath\fR values. .sp The \fIAlternate\fR directory is also the customary home of the \fBmisc/st.dev\fR file used by \fIstmkfont\fR to determine PCL printer characteristics. .sp Because the \fIAlternate\fR directory is the customary home of many important typeface-independent files, it is usually inadvisable to use the \fB-d2\fR option. .TP 8 \fB\-d1 \fIPrimary\fR .in -4 .nf \fB\-d2 \fIAlternate\fR .fi .in +4 Whenever \fIstmkfont\fR must open a typeface library, a character set map, or a \fB*.dir\fR control file, it searches through several directories in a specific order until either the required file is found, or the list of search directories are exhausted. These \fIdatabase directories\fR and the order in which they are searched are as follows: .nf 1. \fIPrimary\fR (default \fB/usr/lib/X11/fonts/ifo.st\fR) 2. \fIAlternate\fR (default \fB/usr/lib/X11/fonts/stadmin\fR) 3. {\fISTPATH\fR} (environment variable)\fR .fi The \fB-d1\fR and \fB-d2\fR options let you change the \fIPrimary\fR and \fIAlternate\fR database directories. If a requested file cannot be found based on either of these two paths, additional places to look can be specified by using the \fBSTPATH\fR environment variable. .sp In practice, typefaces are usually found in the \fIPrimary\fR directory, and character sets are found in the \fIAlternate\fR directory's \fICharsetPath\fR directory (see below). .TP 8 \fB\-dv \fIdevice\fR Specifies the device for which a font is to be made, in the format \fIhost:device\fR. If not specified or partly specified (\fIhost:\fR or \fI:device\fR), \fIhost\fR defaults to the executing machine's hostname, and device defaults to PRINTERS or DISPLAYS (depending on the output format specified). See \fIstlicense(1)\fR for further information on the format of the \fIdevice\fR parameter. .TP 8 \fB\-f \fIformat\fR Specifies the output format for the requested font, which must be one of the following: \fBBDF\fR or one of the supported PCL printer formats. Output formats currently supported are: \fBLJPLUS\fR, \fBLJII\fR, \fBLJ2000\fR, \fBLJIIP\fR, \fBLJIII\fR (bitmapped fonts for various models of LaserJet), \fBPJXL\fR (bitmapped fonts for the PaintJet XL), and \fBPCLEO\fR (scalable fonts for the LaserJet III). Bitmapped fonts reflect any transformations (such as emboldening and obliqueing) requested in the \fIxlfdname\fR argument; scalable fonts (PCLEO format) do not. .sp If left unspecified, output format is BDF. .TP 8 \fB\-h\fR There is no \fB-h\fP option. For online help, run \fIstmkfont\fP without any parameters. .TP 8 \fB\-nf \fIfonts.dir\fR .in -4 .nf \fB\-ns \fIcharsets.dir\fR \fB\-nt \fItypefaces.dir\fR .fi .in +4 These three options allow you to specify alternate names for the three control files that may be used by \fIstmkfont\fR. \fBfonts.dir\fR contains a list of typeface library files and the XLFD ``outline'' name descriptions of those typefaces. \fBcharsets.dir\fR contains associates character set registry, encoding, and requirements with particular character set map files. \fBtypefaces.dir\fR assigns ``official'' names to individual Agfa Compugraphic typeface IDs. .TP 8 \fB\-nv \fIname\fR Specifies an alternate environment variable name to use instead of \fBSTPATH\fR. .TP 8 \fB\-o \fIoutfile\fR This option specifies the output file. Default is stdout. .TP 8 .B \-q Run quietly (suppress error messages). .TP 8 .B \-v Similar to the \fB\-V\fR option, \fB\-v\fR requests that a fully qualified XLFD name be sent to stderr before \fIstmkfont\fR begins generating glyphs. The string will be terminated with a newline character and stderr will be flushed before any glyph output appears. .TP 8 .B \-w This option causes all bitmap output data to be suppressed, resulting in only header and trailer information being generated. Header metrics will accurately reflect the entire font that would have been emitted, but the character count will show zero. .PP .SH ENVIRONMENT .TP 8 .B STPATH \fISTPATH\fR specifies the last\-resort paths to be searched when looking for typeface libraries, character set mapping files, and \fB*.dir\fR files. Searching \fISTPATH\fR is only considered if requested files are not found in the \fIPrimary\fR or \fIAlternate\fR paths (normally, \fB/usr/lib/X11/fonts/ifo.st\fR and \fB/usr/lib/X11/fonts/stadmin\fR). \fISTPATH\fR has a format similar to the \fIPATH\fR variable, consisting of one or more paths concatenated together with colons. .SH "ABOUT XLFD NAMES" If the \fIxlfdname\fR argument contains any embedded blanks the entire XLFD name should be enclosed in quotes. Also, while it is good practice to always specify \fIsomething\fR in all XLFD fields, null fields (double dashes) are permissible and will be treated as though they contain asterisk wildcards. Certain fields of the XLFD name will ``default'' if specified as zero or wild: .nf Point Size (field 8) - default value is 120 (12 point) X resolution (field 9) - \kadefault value is 100 dots per inch (BDF) \h'|\nau'default value is printer resolution (PCL) Y resolution (field 10) - \kadefault value is 100 dots per inch (BDF) \h'|\nau'default value is printer resolution (PCL) .fi Resolution of other fields containing wildcards depends wholly on the contents and ordering of data in \fBfonts.dir\fR and \fBcharsets.dir\fR. .SH "ABOUT THE VARIOUS PCL FORMATS" The PCL bitmapped output formats for the various LaserJet printers are identical. \fIStmkfont\fR uses the format specified with the \fI-f\fR option to ensure that the font will work within the restrictions imposed by the target printer. For example, the LJPLUS printer cannot handle the large glyphs allowed by the other models, nor can it handle character sets that define glyphs for the control characters. .SH EXAMPLES To generate a BDF file for a 14-point/110 DPI ``cg times'' font using the iso8859-1 character set: .sp .5 .nf stmkfont "-agfa-cg times-normal-r-normal-*-*-140-110-110-*-*-iso8859-1" .fi .sp To generate the same font for a LaserJet II: .sp .5 .nf stmkfont -f LJII "-agfa-cg times-normal-r-normal-*-*-140-*-*-*-*-iso8859-1" .fi .sp .5 Note that the resolution fields will default to the printer's 300 DPI resolution. The output will be a LaserJet II font \fIwithout\fR the font management sequences for assigning font ID and for making the font temporary or permanent. .sp To search for fonts in a directory ``$HOME/fonts'' containing scalable fonts and a fonts.dir directory: .sp .5 .nf stmkfont -d1 "$HOME/fonts" "-agfa-cg times-normal-r----140-----hp-roman8" .fi .sp .5 Note here that empty fields are simply run together as a string of dashes. While this is an unrecommended departure from the XLFD format standard, \fIstmkfont\fP will allow such a specification and treats the empty fields as though they contain asterisk wildcards. .sp .5 .SH FILES .in +2 .nf /usr/lib/X11/fonts/stadmin/ifo/charsets/charsets.dir /usr/lib/X11/fonts/ifo.st/typefaces/fonts.dir /usr/lib/X11/fonts/stadmin/misc/st.dev .fi .in -2 .SH NOTE \fIStmkfont\fR supports only Intellifont scalable fonts; it cannot be used to generate fonts from Type 1 or any other format of scalable outlines. .SH ERRORS .TP 8 \fBTypeface does not contain an HP alias\fR The typeface file does not contain sufficient information to construct a PCL font. .TP 8 \fBLJPLUS printer does not support this charset\fR A character set was requested that cannot be used on the LaserJet Plus printer. Any character set that defines glyphs for characters 0-31 or 128-159 cannot be used on the LaserJet Plus printer. .TP 8 \fBFont too large for printer\fR The requested font size is larger than can be handled by the target printer. .PP .SH "SEE ALSO" mkfontdir(1), stmkdirs(1), stlicense(1M), stload(1M) .SH COPYRIGHT (C) Copyright 1990 Hewlett-Packard Company .\" $Header: strings.1,v 76.1 95/08/23 17:38:37 ssa Exp $ .TA s .TH strings 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strings \- find the printable strings in an object or other binary file .SH SYNOPSIS .C strings .RC [ -a ] .RC [ -t .IR format\| ] .RC [ -n .IR number\| ] .RI [ \|file\| ]\ ... .PP .I Obsolescent: .br .C strings .RC [ -a ] .RC [ -o ] .RC [ -\c .IR number\| ] .RI [ \|file\| ]\ ... .SH DESCRIPTION .C strings looks for ASCII strings in a file. If no .I file is specified, standard input is used. A string is any sequence of four or more printing characters ending with a newline or null character. .PP .C strings is useful for identifying random object files and many other things. .SS Options .C strings recognizes the following options: .RS .TP 15 .C -a By default, .I strings looks only in the initialized data space of object files (as recognized by their magic numbers). If this flag is used, the entire file is inspected. This flag is always set if standard input is being read or the file is not recognized as an object file. For backward compatibility, .C - is understood as a synonym for .CR -a . .TP .CI -t \ format Write each string preceded by its byte offset from the start of the file. The format is dependent on the single character used as the .I format option-argument: .RS .RS .TP .I d The offset is written in decimal. .TP .I o The offset is written in octal. .TP .I x The offset is written in hexadecimal. .RE .RE .TP .CI -n \ number Specify .I number as the minimum string length, rather than the default 4. .TP .C -o Each string is preceded by its offset in the file (in octal). This option is obsolescent and is equivalent to specifying the .CI -t \ o option. .TP .CI - number Specify .I number as the minimum string length, rather than the default 4. This option is obsolescent and is equivalent to using the .C -n .I number option. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the locale for the interpretation of text as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .CR LC_CTYPE or .CR LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP .C NLSPATH Determine the location of message catalogues for the processing of .CR LC_MESSAGES. .PP If any internationalization variable contains an invalid setting, .C strings behaves as if all internationalization variables are set to "C". See .IR environ (5). .SH WARNINGS The algorithm for identifying strings is extremely primitive. .SH AUTHOR .C strings was developed by the University of California, Berkeley. .SH SEE ALSO od(1). .SH STANDARDS CONFORMANCE .CR strings ": XPG4, POSIX.2" .\" .\" index@\f4strings\f1 \- find the printable strings in an object, or other binary, file@@@\f3strings(1)\f1 .\" index@\f1files, find the printable strings in an object or other binary file@@@\f3strings(1)\f1 .\" index@\f1find the printable strings in an object or other binary file@@@\f3strings(1)\f1 .\" index@\f1binary or object file, find the printable strings in an@@@\f3strings(1)\f1 .\" index@\f1object or binary file, find the printable strings in an@@@\f3strings(1)\f1 .\" index@\f1printable strings in an object or other binary file, find the@@@\f3strings(1)\f1 .\" .\" toc@\f3strings(1)\f1:\0\0\f4strings\f1@@@find the printable strings in an object or other binary file .\" $Header: strip.1,v 76.1 95/08/04 17:05:30 ssa Exp $ .TA s .TH strip 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strip \- strip symbol and line number information from an object file .SH SYNOPSIS .C strip .RC [ -l ] .RC [ -x ] .RC [ -r ] .RC [ -V ] .IR filename \ ... .SH DESCRIPTION .C strip removes the symbol table and line number information from object files, including archives. Thereafter, no symbolic debugging access is available for that file; thus, this command is normally run only on production modules that have been debugged and tested. The effect is nearly identical to using the .C -s option of .IR ld . .SS Options The amount of information stripped from the symbol table can be controlled by using any of the following options: .RS .TP 8 .C -l Strip line number information only; do not strip any symbol table information. .TP .C -x Do not strip static or external symbol information. .IP Note that the .C -l and .C -x options are synonymous because the symbol table contains only static and external symbols. Either option strips only symbolic debugging information and unloadable data. .TP .C -r Reset the relocation indexes into the symbol table. This option allows .C strip to be run on relocatable files, in which case the effect is also to strip only symbolic debugging information and unloadable data. .TP .C -V Print the version of the strip command on the standard error output. .RE .PP If there are any relocation entries in the object file and any symbol table information is to be stripped, .C strip complains and terminates without stripping .I filename unless the .C -r option is used. .PP If .C strip is executed on an archive file (see .IR ar (4)), the archive symbol table is removed. The archive symbol table must be restored by executing .C ar with its .C s operator (see .IR ar (1)) before the archive can be used by the .C ld command (se .IR ld (1)). .C strip instructs the user with appropriate warning messages when this situation arises. .PP The purpose of this command is to reduce file storage overhead consumed by the object file. .SH EXTERNAL INFLUENCES .SS Environment Variables .PP The following internationalization variables affect the execution of .CR size : .PP .C LANG .RS Determines the locale category for native language, local customs and coded character set in the absence of .C LC_ALL and other .C LC_* environment variables. If .C LANG is not specified or is set to the empty string, a default of .C C (see .IR lang (5)) is used instead of .CR LANG . .RE .PP .C LC_ALL .RS Determines the values for all locale categories and has precedence over .C LANG and other .C LC_* environment variables. .RE .PP .C LC_MESSAGES .RS Determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error. .RE .PP .C LC_NUMERIC .RS Determines the locale category for numeric formatting. .RE .PP .C LC_CTYPE .RS Determines the locale category for character handling functions. .RE .PP .C NLSPATH .RS Determines the location of message catalogues for the processing of .CR LC_MESSAGES . .RE .PP If any internationalization variable contains an invalid setting, .C strip behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .PP In addition, the following environment variable affects .CR strip : .PP .C TMPDIR .RS Specifies a directory for temporary files (see .IR tmpnam (3S)). .RE .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS .TP 30 .CI "strip: " name ": cannot open" .I name cannot be read. .TP .CI "strip: " name ": bad magic" .I name is not an appropriate object file. .TP .CI "strip: " name ": relocation entries present; cannot strip" .I name contains relocation entries and the .C -r option was not specified. Symbol table information cannot be stripped. .SH EXAMPLES Strip symbol table and debug information from the shared library .C libfoo.sl in the current directory to reduce its size. Symbol information required to use the library is preserved: .IP .C "strip ./libfoo.sl" .SH FILES .TP 30 .C /var/tmp/SGSstrp* temporary files .SH SEE ALSO .PD .SS System Tools: .TP 18 .IR ar(1) create archived libraries .PD 0 .TP .IR as(1) translate assembly code to machine code .TP .IR cc(1) invoke the HP-UX C compiler .TP .IR ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 .IR a.out(4) assembler, compiler, and linker output .PD 0 .TP .IR ar(4) archive format .PD .SH STANDARDS CONFORMANCE .CR strip ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4strip\f1 \- strip symbol and line number information from an object file@@@\f3strip(1)\f1 .\" index@files: strip symbol and line number information from an object file@@@\f3strip(1)\f1 .\" index@strip symbol and line number information from an object file@@@\f3strip(1)\f1 .\" index@object file, strip symbol and line number information from@@@\f3strip(1)\f1 .\" index@symbol and line number information, strip from an object file@@@\f3strip(1)\f1 .\" index@line number and symbol information, strip from an object file@@@\f3strip(1)\f1 .\" index@remove symbol and line number information from an object file@@@\f3strip(1)\f1 .\" .\" toc@\f3strip(1)\f1:\0\0\f4strip\f1@@@strip symbol and line number information from an object file .\" .\" fileset_database@strip.1 USER-CMDS-MAN .\" $Header: stty.1,v 76.1 95/08/04 17:24:33 ssa Exp $ .TA s .TH stty 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME stty \- set the options for a terminal port .SH SYNOPSIS .C stty .RC [ "-a \(or -g" \(or .IR options\| ] .SH DESCRIPTION .C stty sets or reports current settings of certain terminal I/O options for the device that is the current standard input. The command takes four forms: .RS .TP 20 .C stty Report the settings of a system-defined set of options; .TP .C stty -a Report all of current option settings; .TP .C stty -g Report current settings in a form that can be used as an argument to another .C stty command. .TP .CI stty \ options Set terminal I/O options as defined by .IR options . .RE .PP For detailed information about the modes listed below from Control Modes through Local Modes as they relate to asynchronous lines, see .IR termio (7). For detailed information about the modes listed under Hardware Flow Control Modes below, see .IR termiox (7). .PP Options in the Combination Modes group are implemented using options in the previous groups. Note that many combinations of options make no sense, but no sanity checking is performed. .PP .I options are selected from the following: .SS Control Modes .TP 25 .CI rows \0number Set the terminal window row size equal to .IR number . .TP .CI columns \0number Set the terminal window column size (width) equal to .IR number . .C cols can be used as an abbreviation for .CR columns . .TP .CR parenb " (" -parenb ) Enable (disable) parity generation and detection. .TP .CR parodd " (" -parodd ) Select odd (even) parity. .TP .C "cs5 cs6 cs7 cs8" Select character size (see .IR termio (7)). .TP .C 0 Hang up phone line immediately. .TP .C "50 75 110 134.5 150 200 300 600 900 1200 1800 2400" .PD 0 .TP .C "3600 4800 7200 9600 19200 38400 57600 115200 230400 exta extb" Set terminal baud rate to the number given, if possible (some hardware interfaces do not support all of the speeds listed here). Speeds above 38400 are supported on Series 700 only. .PD .TP .CI ispeed " number" Set terminal input baud rate to .IR number . If .I number is zero, the input baud rate is set to the value of the output baud rate. .TP .CI ospeed " number" Set terminal output baud rate to .IR number . If .I number is zero, the modem control lines are released, which in turn disconnects the line. .TP .CR hupcl " (" -hupcl ) Hang up (do not hang up) modem connection on last close. .TP .CR hup " (" -hup ) Same as .CR hupcl " (" -hupcl ). .TP .CR cstopb " (" -cstopb ) Use two (one) stop bits per character. .TP .CR cread " (" -cread ) Enable (disable) the receiver. .TP .CR crts " (" -crts ) Enable (disable) request-to-send. .TP .CR clocal " (" -clocal ) Assume a line without (with) modem control. .TP .CR loblk " (" -loblk ) Block (do not block) output from a noncurrent layer. .SS Input Modes .TP 25 .CR ignbrk " (" -ignbrk ) Ignore (do not ignore) break on input. .TP .CR ienqak " (" -ienqak ) Enable (disable) ENQ-ACK Handshaking. .TP .CR brkint " (" -brkint ) Signal (do not signal) INTR on break. .TP .CR ignpar " (" -ignpar ) Ignore (do not ignore) parity errors. .TP .CR parmrk " (" -parmrk ) Mark (do not mark) parity errors (see .IR termio (7)). .TP .CR inpck " (" -inpck ) Enable (disable) input parity checking. .TP .CR istrip " (" -istrip ) Strip (do not strip) input characters to seven bits. .TP .CR inlcr " (" -inlcr ) Map (do not map) newline character to carriage return (CR) on input. .TP .CR igncr " (" -igncr ) Ignore (do not ignore) CR on input. .TP .CR icrnl " (" -icrnl ) Map (do not map) CR to a newline character on input. .TP .CR iuclc " (" -iuclc ) Map (do not map) uppercase alphabetic characters to lowercase on input. .TP .CR ixon " (" -ixon ) Enable (disable) START/STOP output control. Output is stopped by sending an ASCII DC3 and started by sending an ASCII DC1. .TP .CR ixany " (" -ixany ) Allow any character (only DC1) to restart output. .TP .CR ixoff " (" -ixoff ) Request that the system send (not send) START/STOP characters when the input queue is nearly empty/full. .TP .CR imaxbel " (" -imaxbel ) Echo (do not echo) BEL when the input line is too long. .SS Output Modes .TP 25 .CR opost " (" -opost ) Post-process output (do not post-process output; ignore all other output modes). .TP .CR olcuc " (" -olcuc ) Map (do not map) lowercase alphabetics to uppercase on output. .TP .CR onlcr " (" -onlcr ) Map (do not map) newline character to a carriage-return/newline character sequence on output. .TP .CR ocrnl " (" -ocrnl ) Map (do not map) CR to newline character on output. .TP .CR onocr " (" -onocr ) Do not (do) output CRs at column zero. .TP .CR onlret " (" -onlret ) On the terminal, a newline character performs (does not perform) the CR function. .TP .CR ofill " (" -ofill ) Use fill characters (use timing) for delays. .TP .CR ofdel " (" -ofdel ) Fill characters are DELs ( NULs). .TP .C cr0 cr1 cr2 cr3 Select style of delay for carriage returns (see .IR termio (7)). .TP .C nl0 nl1 Select style of delay for newline characters (see .IR termio (7)). .TP .C tab0 tab1 tab2 tab3 Select style of delay for horizontal tabs (see .IR termio (7). .TP .C bs0 bs1 Select style of delay for backspaces (see .IR termio (7)). .TP .C ff0 ff1 Select style of delay for form-feeds (see .IR termio (7)). .TP .C vt0 vt1 Select style of delay for vertical tabs (see .IR termio (7)). .SS Local Modes .TP 25 .CR isig " (" -isig ) Enable (disable) the checking of characters against the special control characters INTR and QUIT. .TP .CR icanon " (" -icanon ) Enable (disable) canonical input (ERASE and KILL processing). .TP .CR iexten " (" -iexten ) Enable (disable) any implementation-defined special control characters not currently controlled by .IR icanon , .IR isig , or .IR ixon . .TP .CR xcase " (" -xcase ) Canonical (unprocessed) uppercase and lowercase presentation. .TP .CR echo " (" -echo ) Echo back (do not echo back) every character typed. .TP .CR echoe " (" -echoe ) Echo (do not echo) ERASE character as a backspace-space-backspace string. Note: this mode erases the ERASEed character on many CRT terminals. However, it does .I not keep track of column position and, as a result, may not correctly erase escaped characters, tabs, and backspaces. .TP .CR echok " (" -echok ) Echo (do not echo) a newline character after a KILL character. .TP .CR lfkc " (" -lfkc ) (obsolete) Same as .CR echok " (" -echok ). .TP .CR echonl " (" -echonl ) Echo (do not echo) newline character. .TP .CR noflsh " (" -noflsh ) Disable (enable) flush after INTR or QUIT. .TP .CR echoctl " (" -echoctl ) Echo (do not echo) control characters as ^char, delete as ^? .TP .CR echoprt " (" -echoprt ) Echo (do not echo) erase character as character is erased. .TP .CR echoke " (" -echoke ) BS-SP-BS erase (do not BS-SP-BS erase) entire line on line kill. .TP .CR flusho " (" -flusho ) Output is (is not) being flushed. .TP .CR pendin " (" -pendin ) Retype (do not retype) pending output at next read or input character. .TP .CR tostop " (" -tostop ) Enable (disable) generation of SIGTTOU signals when background jobs attempt output. .SS Hardware Flow Control Modes The following options are reserved for use with those devices that support hardware flow control through the termiox interface. If the functionality is supported, this interface must be used. .TP 25 .CR rtsxoff " (" -rtsxoff) enable (disable) RTS hardware flow control on input (see .IR termiox (7)) .TP .CR ctsxon " (" -ctsxon) enable (disable) CTS hardware flow control on output (see .IR termiox (7)) .SS Control Assignments .TP 25 .I control-character c Set .I control-character to .IR c , where .I control-character is .CR erase , .CR kill ", .CR intr , .CR quit , .CR eof , .CR eol , .CR eol2 , .CR werase , .CR lnext , .CR min , or .CR time .RC ( min and .C time are used with .CR -icanon ; see .IR termio (7)). For systems that support job control, .C susp and .C dsusp characters can also be set. For systems that support shell layers (see .IR shl (1)) .C swtch can also be set. If .I c is preceded by an (escaped from the shell) circumflex .RC ( ^ ), the value used is the corresponding control character (for example, .C ^d represents .BR Ctrl-d ); .RC ^? is interpreted as DEL and .RC ^- is interpreted as undefined. .TP .CI line " i" Set line discipline to .I i where the value of .I i ranges from zero through 127 decimal (See .IR termio (7)). .ne 6 .SS Combination Modes .TP 25 .CR evenp " or " parity Enable .C parenb and .CR cs7 . .TP .C oddp Enable .CR parenb , .CR cs7 , and .CR parodd . .TP .CR -parity ", " -evenp ", or " -oddp Disable .C parenb and set .CR cs8 . .TP .CR raw " (" -raw " or " cooked ) Enable (disable) raw input and output (no ERASE, KILL, INTR, QUIT, EOT, or output post processing). See WARNINGS. .TP .CR nl " (" -nl ) Unset (set) .C icrnl and .C onlcr . In addition .C -nl unsets .CR inlcr , .CR igncr , .CR ocrnl , and .CR onlret . .TP .CR lcase " (" -lcase ) Set (unset) .CR xcase , .CR iuclc , and .CR olcuc . .TP .CR LCASE " (" -LCASE ) Same as .C lcase .RC ( -lcase ). .TP .CR tabs " (" -tabs " or " tab3 ) Preserve (expand to spaces) tabs when printing. .TP .C ek Reset ERASE and KILL characters back to default .C # and \f3@\f1. .TP .C sane Reset all modes to some reasonable values. .TP .C term Set all modes suitable for the terminal type .IR term , where .I term is one of .CR tty33 , .CR tty37 , .CR vt05 , .CR tn300 , .CR ti700 , .CR hp , or .CR tek . .SS Reporting Functions .TP 25 .C size Print terminal window size to standard output in a rows-and-columns format. .SS Control Character Default Assignments The control characters are assigned default values when the terminal port is opened, see .IR termio (7). The default values used are those specified by the System V Interface Definition, Third Edition (SVID3), except for the .CR werase and .CR lnext control characters, which are set to .CR _POSIX_VDISABLE to maintain binary compatibility with previous releases of HP-UX. .PP The default values for the control characters may be changed by a user with root capability by using .C stty and redirecting stdin to the device .CR /dev/ttyconf . Any of the four command forms specified in the Description section above may be used. However, only the control character defaults will be reported or altered. It will have no effect on the defaults for any of the other modes. .PP Note that these defaults will be used for all terminal ports in the system, except the system console, and the changes will not become effective for a particular port until it is (re)opened. The new defaults will not become effective for the system console until a system boot takes place. .PP Care should be exercised when re-assigning the control character defaults. Control character values should be tested with applications before assigning them as a default value. .TP 25 .SH EXTERNAL INFLUENCES .SS Environment Variables .SM LC_CTYPE determines the valid control characters for printing. .PP If .SM LC_CTYPE is not specified in the environment or is set to the empty string, the value of LANG is used as a default for each unspecified or empty variable. If LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of LANG. If any internationalization variable contains an invalid setting, .C stty behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte character code sets are supported. .SH EXAMPLES The command: .IP \f3stty kill '^X' intr '^C'\f1 .PP sets the delete-line character to .C ^X (Ctrl-X) and the interrupt character to .CR ^C . This command is usually found in the .C .login or .C .profile file so that .C ^X and .C ^C need not be set by the user at each login session. .PP The command: .IP \f3stty kill '^X' intr '^C' werase '^W' 0 One or more files could not be read or some other error occurred. .RE .PP If an inaccessible file is encountered, .C sum continues processing any remaining files, but the final exit status is affected. .SH DIAGNOSTICS Read error conditions are indistinguishable from end of file on most devices; check the block or byte count. .SH "SEE ALSO" cksum(1), wc(1), pdf(4). .SH STANDARDS CONFORMANCE .CR sum ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4sum\f1 \- print checksum and block count of a file@@@\f3sum(1)\f1 .\" index@files: print checksum and block count of a file@@@\f3sum(1)\f1 .\" index@print checksum and block count of a file@@@\f3sum(1)\f1 .\" index@checksum and block count of a file, print@@@\f3sum(1)\f1 .\" index@block count and checksum of a file, print@@@\f3sum(1)\f1 .\" .\" toc@\f3sum(1)\f1:\0\0\f2sum\f1@@@print checksum and block count of a file ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" ...\" ...\" ...\" ...\" ...\" ...\" ...\" ...\" ...\" .rm zA .rm zZ .TH svcdumplog "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lsvcdumplog\*O command" ...\" ---------------------------------------------------------------------- .SH NAME ...\" ---------------------------------------------------------------------- \*Lsvcdumplog\*O \- Prints contents of a binary serviceability log file ...\" ---------------------------------------------------------------------- .SH "SYNOPSIS" ...\" ---------------------------------------------------------------------- .sS \*Lsvcdumplog\*O [\*L-s \*Vnum_of_entries\*O] \*Vlogfile\*O .sE ...\" ---------------------------------------------------------------------- .SH "OPTIONS" ...\" ---------------------------------------------------------------------- .VL 1.5i .LI "\*L-s\ \*Vnum_of_entries\*O" The \*L-s\*O flag tells \*Lsvcdumplog\*O to skip the first \*Vnum_of_entries\*O log entries before printing, where \*Vnum_of_entries\*O is a number. .LE ...\" ...\" ...\" ...\" ---------------------------------------------------------------------- .SH "DESCRIPTION" ...\" ---------------------------------------------------------------------- ...\" .PP The \*Lsvcdumplog\*O program will print the contents of a binary log file. ...\" .PP DCE components log important information about their activities and state via the DCE serviceability interface. The log messages can be routed as desired via the \*Ldcecp\*O \*Llog\*O object. The messages can also be written in either binary or in text format (information about specifying message format can be found in \*Lsvcroute(5)\*O). When binary format has been specified for a component's messages, each log entry will be written as a binary record of data defined (in \*Ldce/svclog.h\*O) as the contents of the serviceability \*Lprolog\*O structure. The \*Lsvcdumplog\*O utility will print the contents of such a binary log file as readable text. ...\" ...\" ...\" ...\" ...\" ---------------------------------------------------------------------- .SH "RELATED INFORMATION" ...\" ---------------------------------------------------------------------- .PP \*Ldce_svc_log_get(3)\*O, \*Ldce_svc_log_close(3)\*O, \*Ldce_svc_log_open(3)\*O, \*Ldce_svc_log_rewind(3)\*O, \*Lsvcroute(5)\*O, \*Llog(1m)\*O ...\" .PP Books: \*VOSF DCE Porting and Testing Guide\*O, \*VOSF DCE Application Development Guide\*O ...\" ...\" ...\" ...\" ---------------------------------------------------------------------- .\" $Header: tabs.1,v 78.1 96/04/05 11:34:52 ssa Exp $ .TA t .TH tabs 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tabs \- set tabs on a terminal .SH SYNOPSIS .C tabs .RI [ \|tabspec\| ] .RC [ +m .IR n \|] .RC [ -T .IR type \|] .SH DESCRIPTION .C tabs sets the tab stops on the user's terminal according to the tab specification .IR tabspec , after clearing any previous settings. The user's terminal must have remotely-settable hardware tabs. .PP If you are using a non-HP terminal, you should keep in mind that behavior will vary for some tab settings. .PP Four types of tab specification are accepted for .IR tabspec : ``canned'', repetitive, arbitrary, and file. If no .C tabspec is given, the default value is .CR -8 ; i.e., .SM HP-UX ``standard'' tabs. The lowest column number is 1. Note that for .IR tabs , column 1 always refers to the left-most column on a terminal, even one whose column markers begin at 0. .PP .RS .TP 12 .CI - code Gives the name of one of a set of ``canned'' tabs. Recognized .IR code s and their meanings are as follows: .RS .RS .TP 6 .C -a 1,10,16,36,72 .br Assembler, .SM IBM S/370, first format .TP .C -a2 1,10,16,40,72 .br Assembler, .SM IBM S/370, second format .TP .C -c 1,8,12,16,20,55 .br .SM COBOL, normal format .TP .C -c2 1,6,10,14,49 .br .SM COBOL compact format (columns 1-6 omitted). Using this code, the first typed character corresponds to card column 7, one space gets you to column 8, and a tab reaches column 12. Files using this tab setup should have .CR tabs specify a format specification file as defined by .CI -\|- file below. The .IR file should have the following format specification: .RS .IP .C "<:t-c2 m6 s66 d:>" .RE .TP .C -c3 1,6,10,14,18,22,26,30,34,38,42,46,50,54,58,62,67 .br .SM COBOL compact format (columns 1-6 omitted), with more tabs than .C -c2. This is the recommended format for .SM COBOL. The appropriate format specification is: .RS .IP .C "<:t-c3 m6 s66 d:>" .RE .TP .C -f 1,7,11,15,19,23 .br F\s-2ORTRAN\s0 .TP .C -p 1,5,9,13,17,21,25,29,33,37,41,45,49,53,57,61 .br .SM PL/I .TP .C -s 1,10,55 .br .SM SNOBOL .TP .C -u 1,12,20,44 .br .SM UNIVAC 1100 Assembler .RE .RE .RE .PP In addition to these ``canned'' formats, three other types exist: .RS .TP 12 .CI - n A repetitive specification requests tabs at columns .RI 1+ n , .RI 1+2\|\(mu\| n , etc. Of particular importance is the value .CR -8 : this represents the .SM HP-UX ``standard'' tab setting, and is the most likely tab setting to be found at a terminal. It is required for use with the .C nroff -h option for high-speed output (see .IR nroff (1)). Another special case is the value .CR -0 , implying no tabs at all. .TP .IC n1 , n2 ,\f1... The arbitrary format permits the user to type any chosen set of numbers, separated by commas, in ascending order. Up to 40 numbers are allowed. If any number (except the first one) is preceded by a plus sign, it is taken as an increment to be added to the previous value. Thus, the tab lists 1,10,20,30 and 1,10,+10,+10 are considered identical. .TP .CI -\|- file If the name of a file is given, .C tabs reads the first line of the file, searching for a format specification. If it finds one there, it sets the tab stops according to it, otherwise it sets them as .CR -8 . This type of specification can be used to ensure that a tabbed file is printed with correct tab settings, and is suitable for use with the .C pr command (see .IR pr (1)): .RS .IP .C "tabs -- file; pr file" .RE .RE .PP Any of the following can be used also; if a given option occurs more than once, the last value given takes effect: .RS .TP 12 .CI -T type .C tabs usually needs to know the type of terminal in order to set tabs and always needs to know the type to set margins. .I type is a name listed in .IR term (5). If no .C -T option is supplied, .C tabs searches for the .C $TERM value in the .I environment (see .IR environ (5)). If no .I type can be found, .C tabs tries a sequence that works for many terminals. .TP .CI +m n The margin argument can be used for some terminals. It causes all tabs to be moved over .I n columns by making column .I n+1 the left margin. If .C +m is given without a value of .IR n , the value assumed is 10. The normal (left-most) margin on most terminals is obtained by .CR +m0 . The margin for most terminals is reset only when the .C +m option is given explicitly. .RE .PP Tab and margin setting is performed via the standard output. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text within file as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C tabs behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS .TP .C illegal tabs Arbitrary tabs are ordered incorrectly. .TP .C illegal increment A zero or missing increment found in an arbitrary specification. .TP .C unknown tab code A ``canned'' code cannot be found. .TP .C can't open .CI -- file option was used and file cannot be opened. .TP .C file indirection .CI -- file option was used and the specification in that file points to yet another file. Indirection of this form is not permitted. .SH WARNINGS There is no consistency among different terminals regarding ways of clearing tabs and setting the left margin. .PP It is generally impossible to usefully change the left margin without also setting tabs. .PP .C tabs clears only 20 tabs (on terminals requiring a long sequence), but is willing to set 64. .SH SEE ALSO nroff(1), pr(1), tset(1), environ(5), term(5). .SH STANDARDS CONFORMANCE .CR tabs ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4tabs\f1 \- set tabs on a terminal@@@\f3tabs(1)\f1 .\" index@\f1set tabs on a terminal@@@\f3tabs(1)\f1 .\" index@\f1terminal, set tabs on a@@@\f3tabs(1)\f1 .\" .\" toc@\f3tabs(1)\f1:\0\0\f4tabs\f1@@@set tabs on a terminal .\" .\" $Header: tail.1,v 76.2 95/08/23 17:40:27 ssa Exp $ .\" Copyright: Hewlett-Packard Company .TA t .TH tail 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tail \- deliver the last part of a file .SH SYNOPSIS .C tail .RC [ -f ] .RC [ -b .IR number\| ] .RI [ \|file\| ] .br .C tail .RC [ -f ] .RC [ -c .IR number\| ] .RI [ \|file\| ] .br .C tail .RC [ -f ] .RC [ -n .IR number\| ] .RI [ \|file\| ] .SS Obsolescent: .br .C tail .ift .RC [ \(+- [\f2\|number\|\fP]\|\c .ifn .RC [ +- [\f2\|number\|\fP]\|\c .RC [ l \(or b\c .RC \(or c ] .RC [ -f ] .RI [ \|file\| ] .SH DESCRIPTION .C tail copies the named .I file to the standard output beginning at a designated place. If no .I file is named, standard input is used. .SS Command Forms .C tail can be used in three forms as indicated above: .RS .TP 22 .CI "tail -b " number\f1... Copy file starting at .I number blocks from end or beginning of file. .TP .CI "tail -c " number\f1... Copy file starting at .I number bytes from end or beginning of file. .TP .CI "tail -n " number\f1... .PD 0 .TP \h'.3i'or .TP .CI "tail " number\f1... Copy file starting at .I number lines from end or beginning of file. .PD .RE .PP .C tail with no options specified is equivalent to .CR "tail -n 10" \|...\|. .SS Options and Command-Line Arguments .C tail recognizes the following options and command-line arguments: .RS .TP 15 .C -f Follow option. If the input file is a regular file or if .I file specifies a .SM FIFO, do not terminate after the last line of the input file has been copied, but read and copy further bytes from the input file when they become available .RC ( tail enters an endless loop wherein it sleeps for one second then attempts to read and copy further records from the input file). This is useful when monitoring text being written to a file by another process. If no .I file argument is specified and the input is a pipe .SM (FIFO), the .C -f option is ignored. .TP .I number Decimal integer indicating quantity of output to be copied, measured in units specified by accompanying option. If .I number is preceded by a .C + character, copy operation starts .I number units from beginning of file. If .I number is preceded by a .C - character or the option name, copy operation starts .I number units from end of file. If .I number is not preceded by a .CR b , .CR c , or .C n option, .C -n is assumed. If both the option and .I number are not specified, .C -n 10 is assumed. .TP .CI "-b " \|number Copy file beginning .I number 512-byte blocks from end or beginning of file. If .I number is not specified, .C -b 10 is assumed. See .I number description above. .TP .CI "-c " \|number Copy file beginning .I number bytes from end or beginning of file. If .I number is not specified, .C -c 10 is assumed. See .I number description above. .TP .CI "-n " \|number Copy file beginning .I number lines from end or beginning of file. If .I number is not specified, .C -n 10 is assumed. See .I number description above. .TP .I file Name of file to be copied. If not specified, the standard input is used. .RE .PP If the .C -c option is specified, the input file can contain arbitrary data. Otherwise, the input file should be a text file. .SS Obsolescent Form In the obsolescent form, option letters can be concatenated after the .I number argument to select blocks, bytes, or lines. If this syntax is used, .ift .CI \(+- number .ifn .CI +- number must be the first argument given. If .I number is not specified, \(mi10 is assumed. This version is provided for backward compatibility only. The forms discussed previously are recommended for portability. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments and input files). .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C tail behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. However, the .C b and .C c options can break multi-byte characters and should be used with caution in a multi-byte locale environment. .SH EXAMPLES Print the last three lines in file .C file1 to the standard output, and leave .C tail in ``follow'' mode: .IP .C "tail -fn 3 file1" .br \h'.3i'or .br .C "tail -3 -f file1" .PP Print the last 15 bytes of file .C logfile followed by any lines that are appended to .C logfile after .C tail is initiated until it is killed: .IP .C "tail -fc15 logfile" .br \h'.3i'or .br .C "tail -f -c 15 logfile" .PP Three ways to print an entire file: .IP .C "tail -b +1 file" .br .C "tail -c +1 file" .br .C "tail -n +1 file" .SH WARNINGS Tails relative to end-of-file are stored in a 20-Kbyte buffer, and thus are limited in length. Therefore, be wary of the results when piping output from other commands into .CR tail . .PP Various kinds of anomalous behavior may occur with character special files. .SH SEE ALSO dd(1), head(1). .SH STANDARDS CONFORMANCE .CR tail ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4tail\f1 \- get lines from last part of a file@@@\f3tail(1)\f1 .\" index@\f1get lines from last part of a file@@@\f3tail(1)\f1 .\" index@\f1list lines from last part of a file@@@\f3tail(1)\f1 .\" index@\f1files: get lines from last part of a file@@@\f3tail(1)\f1 .\" index@\f1last part of a file, get lines from@@@\f3tail(1)\f1 .\" index@\f1end part of a file, get lines from@@@\f3tail(1)\f1 .\" .\" toc@\f3tail(1)\f1:\0\0\f4tail\f1@@@deliver the last part of a file .\" .\" $Header: talk.1,v 76.1 95/08/04 17:29:08 ssa Exp $ .TA t .TH talk 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" Copyright (c) 1983, 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)talk.1 8.1 (Berkeley) 6/6/93 .\" .SH NAME talk \- talk to another user .SH SYNOPSIS .C talk .I talk_party .RI [ \|ttyname\| ] .SH DESCRIPTION The .CR talk utility is a two-way, screen-oriented communication program. .PP The command argument .I talk_party can take one the following forms: .sp .RS .br .IR user .br .IR user @ host .br .IR host ! user .br .IR host : user .br .IR host . user .br .RE .sp where .I user is a login name and .I host is a host name. .PP The optional command argument, .IR ttyname , can be used to specify the terminal to be used when contacting a user who is logged in more than once. In absence of this argument, .CR talk will try to contact the user on the user's most recently used terminal. .PP When first invoked, .CR talk sends the following message to the party it tries to connect to .RI ( callee ): .PP .LI Message from .RI Talk_Daemon@ callee_host ... .br talk: connection requested by .IR caller @ caller_host .br talk: respond with: talk .IR caller @ caller_host .PP At this point, the recipient of the message can reply by typing: .sp .RS talk .IR caller @ caller_host . .RE .PP Once communication is established, the two parties can type simultaneously, with their output displayed in separate regions of the screen. Characters are processed as follows: .TP 3 \(bu Typing characters from LC_CTYPE classifications .B print or .B space will cause those characters to be sent to the recipient's terminal. .TP \(bu Typing -L will cause the sender's screen to be refreshed. .TP \(bu Typing the erase, kill or kill word character will delete the last character, line or word on the sender's terminal, with the action propagated to the recipient's terminal. .TP \(bu Typing the interrupt character will terminate the local .I talk utility. Once the .I talk session has been terminated on one side, the other side of the .I talk session will be notified that the session has been terminated and will be able to do nothing except exit. .TP \(bu Other non-printable characters typed on the sender's terminal are converted to printable characters before they are sent to the recipient's terminal. .PP Permission to be a recipient of a .CR talk message can be denied or granted by using the .CR mesg utility. However, a user may need other privileges to be able to access other users' terminals. The .CR talk utility will fail when the user lacks the appropriate privileges. .SH SEE ALSO mesg(1), who(1), write(1). .SH STANDARDS CONFORMANCE .CR talk ": XPG4" .\" .\" toc@\f3talk(1)\f1:\0\0\f4talk\f1@@@talk to another user .\" .\" index@\f4talk\f1 \- talk to another user@@@\f3talk(1)\f1 .\" index@\f1talk to another user@@@\f3talk(1)\f1 .\" $Header: tar.1,v 78.1 96/01/22 22:27:31 ssa Exp $ .TA t .TH tar 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tar \- tape file archiver .SH SYNOPSIS .CR tar .RC [ - ]\f2key .RI [ arg \0...] .RI [ file \(or .CI -C \0directory\f1]\0... .SH DESCRIPTION The .CR tar command saves and restores archives of files on a magnetic tape, a flexible disk, or a regular file. The default archive file is .CR /dev/rmt/0m . See the .CR -f option below. Its actions are controlled by the .IR key argument. .SS Arguments .TP 14 .IR key is a string of characters containing an optional version letter, exactly one function letter, and possibly one or more function modifiers, specified in any order. Whitespace is not permitted in .IR key . The .IR key string can be preceded by a hyphen .RC ( - ), as when specifying options in other HP-UX commands, but it is not necessary. .TP .IR arg \0...\& The .CR b and .CR f function modifiers each require an .IR arg argument (see below). If both .CR b and .CR f are specified, the order of the .IR arg arguments must match the order of the modifiers. If specified, the .IR arg arguments must be separated from the key and each other by whitespace. .TP .IR file specifies a file being saved or restored. If .IR file is a directory name, it refers to the files and (recursively) the subdirectories contained in that directory. .TP .CI "-C " directory causes .CR tar to perform a .CR chdir() to .IR directory (see .IR chdir (2)). Subsequent .IR file and .CI "-C " directory arguments must be relative to .IR directory . This allows multiple directories not related by a close or common parent to be archived using short relative path names. .PP The value of .IR file is stored in the archive. The value of .IR directory is not stored. .SS Version Keys .PP The version portion of the .IR key determines the format in which .CR tar writes the archive. .CR tar can read either format regardless of the version. The version is specified by one of the following letters: .RS .TP .CR N Write a POSIX format archive. This format allows file names of up to 256 characters in length, and correctly archives and restores the following file types: regular files, character and block special devices, links, symbolic links, directories, and FIFO special files. It also stores the user and group name of each file and attempts to use these names to determine the user-ID and group-ID of a file when restoring it with the .CR p function modifier. This is the default format. .TP .CR O Write a pre-POSIX format archive. .RE .SS Function Keys .PP The function portion of the .IR key is specified by exactly one of the following letters: .RS .TP .CR c Create a new archive. Write from the beginning of the archive instead of appending after the last file. Any previous information in the archive is overwritten. .TP .CR r Add the named .IR file to the end of the archive. The same blocking factor used to create the archive must be used to append to it. .TP .CR t List the names of all the files in the archive. Adding the .CR v function modifier expands this listing to include the file modes and owner numbers. The names of all files are listed each time they occur on the tape. .TP .CR u Add any named .IR file to the archive if it is not already present or has been modified since it was last written in the archive. The same blocking factor used to create the archive must be used to update it. .TP .CR x Extract the named .IR file from the archive and restore it to the system. If a named .IR file matches a directory whose contents were written to the archive, this directory is (recursively) extracted. If a named .IR file on tape does not exist on the system, the .IR file is created as follows: .RS .RS 3 .TP 3 \(bu The user, group, and other protections are restored from the tape. .TP \(bu The modification time is restored from the tape unless the .CR m function modifier is specified. .TP \(bu The file user ID and group ID are normally those of the restoring process. .TP \(bu The set-user-ID, set-group-ID, and sticky bits are not set automatically. The .CR o and .CR p function modifiers control the restoration of protection; see below for more details. .RE .RE .IP If the files exist, their modes are not changed, but the set-user-id, set-group-id and sticky bits are cleared. If no .IR file argument is given, the entire content of the archive is extracted. Note that if several files with the same name are on the archive, the last one overwrites all earlier ones. .RE .SS Function Modifier Keys .PP The following function modifiers can be used in addition to the function letters listed above (note that some modifiers are incompatible with some functions): .RS .TP .CR A Suppress warning messages that .CR tar did not archive a file's access control list. By default, .CR tar writes a warning message for each file with optional ACL entries. .TP .CR b Use the next .IR arg argument as the blocking factor for archive records. The default is 20; the maximum is at least 20. However, if the .CR f\ - modifier is used to specify standard input, the default blocking factor is 1. .IP The blocking factor is determined automatically when reading nine-track tapes (key letters .CR x and .CR t ). On nine-track tapes, the physical tape record length is the same as the block size. The block size is defined as the logical record size times the blocking factor (number of logical records per block). .IP The blocking factor must be specified when reading flexible disks and cartridge tapes if they were written with a blocking factor other than the default. .IP If a .CR tar file is read using a blocking factor not equal to the one used when the file was written, an error may occur at the end of the file but there may or may not be an actual error in the read. To prevent this problem, a blocking factor of .CR 1 can be used, although performance may be reduced somewhat. .IP .CR tar writes logical records of 512 bytes, independent of how logical records may be defined elsewhere by other programs (such as variable-length records (lines) within an ASCII text file). .TP .CR e Fail if the extent attributes are present in the files to be archived. If .CR tar fails for this reason, the partially created destination file is not be removed. .TP .CI f Use the next .IR arg argument as the name of the archive instead of the default, .CR /dev/rmt/0m . If the name of the file is .CR - , .CR tar writes to standard output or reads from standard input, whichever is appropriate, and the default blocking factor becomes 1. Thus, .CR tar can be used as the head or tail of a pipeline (see EXAMPLES). .TP .CR h Force .CR tar to follow symbolic links as if they were normal files or directories. Normally, .CR tar does not follow symbolic links. .TP .CR l Tell .CR tar to complain if it cannot resolve all of the links to the files being saved. If .CR l is not specified, no error messages are printed. .TP .CR m Tell .CR tar not to restore the modification time written on the archive. The modification time of the file will be the time of extraction. .TP .CR o Suppress writing certain directory information that older versions of .CR tar cannot handle on input. .CR tar normally writes information specifying owners and modes of directories in the archive. Earlier versions of .CR tar , when encountering this information, give error messages of the form: .RS .IP .IC name " - cannot create" .RE .IP When .CR o is used for reading, it causes the extracted .IR file to take on the user and group IDs of the user running the program rather than those on the tape. This is the default for the ordinary user and can be overridden, to the extent that system protections allow, by using the .CR p function modifier. .TP .CR p Cause .IR file to be restored to the original modes and ownerships written on the archive, if possible. This is the default for the superuser, and can be overridden by the .CR o function modifier. If system protections prevent the ordinary user from executing .CR chown() , the error is ignored, and the ownership is set to that of the restoring process (see .IR chown (2)). The set-user-id, set-group-id, and sticky bit information are restored as allowed by the protections defined by .CR chmod() if the .CR chown() operation above succeeds. .TP .IR n\|d Specify a particular nine-track tape drive and density, where .IR n is a tape drive number: .CR 0 \(mi 7 , and .IR d is the density: .CR l = low (800 bpi); .CR m = medium (1600 bpi); .CR h = high (6250 bpi). This modifier selects the drive on which the nine-track tape is mounted. The default is .CR 0m . .TP .CR v Normally, .CR tar does its work silently. The .CR v (verbose) function modifier causes .CR tar to type the name of each file it treats, preceded by the function letter. With the .CR t function, .CR v gives more information about the archive entries than just the name. .TP .CR V Same as the .CR v function modifier except that, when using the .CR t option, .CR tar also prints out a letter indicating the type of the archived file. .TP .CR w Cause .CR tar to print the action being taken, followed by the name of the file, then wait for the user's confirmation. If the user answers .CR y , the action is performed. Any other input means "no". .RE .PP When end-of-tape is reached, .CR tar prompts the user for a new special file and continues. .PP If a nine-track tape drive is used as the output device, it must be configured in Berkeley-compatibility mode (see .IR mt (7)). .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_TIME determines the format and contents of date and time strings output when listing the contents of an archive with the .CR -v option. .PP .CR LANG determines the language equivalent of .CR y (for yes/no queries). .PP If .CR LC_TIME is not specified in the environment or is set to the empty string, the value of .CR LANG is used as the default. .PP If .CR LANG is not specified or is set to the empty string, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, .CR tar behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH ERRORS .CR tar issues self-explanatory messages about bad key characters, tape read/write errors, and if not enough memory is available to hold the link tables. .SH EXAMPLES Create a new archive on .CR /dev/rfd.0 and copy .CR file1 and .CR file2 onto it, using the default blocking factor of 20. The .IR key is made up of one function letter .RC ( c ) and two function modifiers .RC ( v and .CR f ): .IP .C "tar cvf /dev/rfd.0 file1 file2" .PP Archive files from .CR /usr/include and .CR /etc : .IP .C "tar cv -C /usr/include -C /etc" .PP Use .CR tar in a pipeline to copy the entire file system hierarchy under .IR fromdir to .IR todir : .IP .CI "cd \&" fromdir " ; tar cf - . | ( cd \&" todir " ; tar xf -i )" .PP Archive all files and directories in directory .CR my_project in the current directory to a file called .CR my_project.TAR , also in the current directory: .IP .C "tar -cvf my_project.TAR my_project" .SH WARNINGS Because of industry standards and interoperability goals, .CR tar does not support the archival of files larger than 2GB or files that have user/group IDs greater than 60K. Files with user/group IDs greater than 60K are archived and restored under the user/group ID of the current process. .PP The default version has changed from .CR O to .CR N , beginning with HP-UX Release 8.0. .PP Due to internal limitations in the header structure, not all file names of fewer than 256 characters fit when using the .CR N version key. If a file name does not fit, .CR tar prints a message and does not archive the file. .PP Link names are still limited to 100 characters when using the .CR N version key. .PP There is no way to ask for the .IR n -th occurrence of a file. .PP Tape errors are handled ungracefully. .PP The .CR u function key can be slow. .PP If the archive is a file on disk, flexible disk, or cartridge tape, and if the blocking factor specified on output is not the default, the same blocking factor must be specified on input, because the blocking factor is not explicitly stored in the archive. Updating or appending to the archive without following this rule can destroy it. .PP Some previous versions of .CR tar have claimed to support the selective listing of file names using the .CR t function key with a list. This appears to be an error in the documentation because the capability does not appear in the original source code. .PP There is no way to restore an absolute path name to a relative position. .PP .CR tar always pads information written to an archive up to the next multiple of the block size. Therefore, if you are creating a small archive and write out one block of information, .CR tar reports that one block was written, but the actual size of the archive might be larger if the .CR b function modifier is used. .PP Note that .CR "tar\ c0m" is not the same as .CR "tar\ cm0" . .PP Do not create archives on block special devices. Attempting to do so can causes excessive wear, leading to premature drive hardware failure. .SH DEPENDENCIES .SS Series 700/800 The .CR r and .CR u function keys are not supported on QIC or 8mm devices. If these options are used with QIC or 8mm devices, .CR tar fails and displays the message: .IP .CR "tar: option not supported for this device" .SH AUTHOR .CR tar was developed by AT&T, the University of California, Berkeley, HP, and POSIX. .SH FILES .CR /dev/rmt/* .br .CR /dev/rfd.* .br .CR /tmp/tar* .SH SEE ALSO ar(1), cpio(1), acl(5),\" STD mt(7). .SH STANDARDS CONFORMANCE .CR tar ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4tar\f1 \- tape file archiver@@@\f3tar(1)\f1 .\" index@tape file archiver@@@\f3tar(1)\f1 .\" index@archiver for tape files@@@\f3tar(1)\f1 .\" index@file archiver, tape@@@\f3tar(1)\f1 .\" index@archiver, tape file@@@\f3tar(1)\f1 .\" .\" toc@\f3tar(1)\f1:\0\0\f4tar\f1@@@tape file archiver .\" $Header: tbl.1,v 74.1 95/05/10 22:04:53 ssa Exp $ .TA t .TH tbl 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tbl \- format tables for nroff .SH SYNOPSIS .C tbl .RC [ -TX ] .RI [ \|file \0...\|] .SH DESCRIPTION .C tbl is a preprocessor that formats tables for .IR nroff (1). The input files are copied to the standard output, except for lines between .C .TS and .C .TE command lines, which are assumed to describe tables and are re-formatted by .CR tbl . (The .C .TS and .C .TE command lines are not altered by .CR tbl ). .PP .C .TS is followed by global options. The available global options are: .PP .RS .PD 0 .TP 10 .C center center the table (default is left-adjust); .TP .C expand make the table as wide as the current line length; .TP .C box enclose the table in a box; .TP .C doublebox enclose the table in a double box; .TP .C allbox enclose each item of the table in a box; .TP .CI "tab (" x ) use the character .I x instead of a tab to separate items in a line of input data. .RE .PD .PP The global options, if any, are terminated with a semi-colon .RC ( ; ). .PP Next come lines describing the format of each line of the table. Each such format line describes one line of the actual table, except that the last format line (which must end with a period) describes .I all remaining lines of the table. Each column of each line of the table is described by a single key-letter, optionally followed by specifiers that determine the font and point size of the corresponding item, indicate where vertical bars are to appear between columns, or determine column width, inter-column spacing, etc. The available key-letters are: .RS .PD 0 .TP .C c center item within the column; .TP .C r right-adjust item within the column; .TP .C l left-adjust item within the column; .TP .C n numerically adjust item in the column: units positions of numbers are aligned vertically; .TP .C s span previous item on the left into this column; .TP .C a center longest line in this column, then left-adjust all other lines in this column with respect to that centered line; .TP .C ^ span down previous entry in this column; .TP .C _ replace this entry with a horizontal line; .TP .C = replace this entry with a double horizontal line. .RE .PD .PP The characters .C B and .C I stand for the bold (font position 3) and italic (font position 2) fonts, respectively; the character .C | indicates a vertical line between columns. .PP The format lines are followed by lines containing the actual data for the table, followed finally by .CR .TE . Within such data lines, data items are normally separated by tab characters. .PP If a data line consists of only .C _ or .CR = , a single or double line, respectively, is drawn across the table at that point; if a .I "single item" in a data line consists of only .C _ or .CR = , then that item is replaced by a single or double line. .PP The .C -TX option forces .C tbl to use only full vertical line motions, making the output more suitable for devices that cannot generate partial vertical line motions (such as line printers). .PP If no file names are given as arguments (or if .C - is specified as the last argument), .C tbl reads the standard input, and thus can be used as a filter. When used with .CR neqn , .C tbl should be used first to minimize the volume of data passed through pipes (see .IR neqn (1)). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text as single- and/or multi-byte characters. .PP .C LC_NUMERIC determines the radix character used in numerical data. .PP .C LANG determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_NUMERIC is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG .IP is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C tbl behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES If we redefine the tab character to a semicolon, then the input: .nf .IP .C .TS .C "center box tab(;) ; .C "cB s s" .C "cI | cI s" .C "^ | c c" .C "l | n n. .C "Household Population" .C _ .C Town;Households .C ;Number;Size .C = .C Bedminster;789;3.26 .C Bernards Twp.;3087;3.74 .C Bernardsville;2018;3.30 .C Bound Brook;3425;3.04 .C Bridgewater;7897;3.81 .C Far Hills;240;3.19 .C .TE .fi .RE .PP yields: .RS .PP .TS center box tab(;); cB s s cI | cI s ^ | c c l | n n . Household Population _ Town;Households ;Number;Size = Bedminster;789;3.26 Bernards Twp.;3087;3.74 Bernardsville;2018;3.30 Bound Brook;3425;3.04 Bridgewater;7897;3.81 Far Hills;240;3.19 .TE .RE .PP The .C tbl command is used most often with .C nroff and .C col (see .IR col (1)). A common usage is: .RS .C "tbl filename | nroff -m" macro_package_name " | col" .RE .SH WARNINGS See WARNINGS under .IR nroff (1). .SH SEE ALSO col(1), mm(1), neqn(1), nroff(1), soelim(1), mm(5). .PP .C tbl tutorial in .I "Text Formatters Users Guide." .\" .\" index@\f4tbl\f1 \- table preprocessor for \f4nroff\f1@@@\f3tbl(1)\f1 .\" index@\f1table preprocessor for \f4nroff\f1@@@\f3tbl(1)\f1 .\" index@\f1preprocess tables for \f4nroff\f1@@@\f3tbl(1)\f1 .\" index@\f4nroff\f1, preprocess tables for@@@\f3tbl(1)\f1 .\" .\" toc@\f3tbl(1)\f1:\0\0\f4tbl\f1@@@format tables for nroff .\" .\" $Header: tcio.1,v 72.5 94/04/28 11:49:52 ssa Exp $ .TA t .TH tcio 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tcio \- Command Set 80 \s-1CS/80\s+1 Cartridge Tape Utility .SH SYNOPSIS .CR "tcio -o" [ dervVZ ] .RC [ -l .I number .RC [ -n .IR limit\| ]\|] .RC [ -S .IR buffersize\| ] .RC [ -T .IR tty\| ] .I file .PP .CR "tcio -i" [ drvZ ] .RC [ -l .I number .RC [ -n .IR limit\| ]\|] .RC [ -S .IR buffersize\| ] .RC [ -T .IR tty\| ] .I file .PP .CR "tcio -u" [ rvV ] .RC [ -l .IR number\| ] .RC [ -m .IR blocknumber\| ] .I file .SH DESCRIPTION .C tcio is designed to optimize the data transfer rate between certain cartridge tape units and the controlling computer. When used in conjunction with other utilities (such as .CR cpio ) a significant improvement in throughput can be obtained, in addition to reducing the wear and tear on the tape cartridges and drives. With autochanger mechanisms, .C tcio provides the capability of loading a specified cartridge, or automatically switching to successive cartridges as needed. With the utility operation, .C tcio provides functions that are unique to cartridge tapes. .PP .C tcio commands take one of the following forms: .RS .TP 12 .C tcio -o (copy out) Reads the standard input and writes the data to the .SM CS/80 Cartridge Tape Unit specified by .IR file . .TP .C tcio -i (copy in) Reads the .SM CS/80 Cartridge Tape Unit specified by .I file and writes the data to the standard output. .TP .C tcio -u (utility) Performs utility functions on the cartridge tape, such as unload, mark, and/or verify the cartridge. .RE .PP In all cases, .I file must refer to a character special file associated with a .SM CS/80 cartridge tape unit. .PP During input and output operations, .C tcio enables immediate report mode on cartridge tape units that support this mode (see .SM DEPENDENCIES\s0). During writing, this mode enables the drive to complete a write transaction with the host before the data has actually been written to the tape from the drive's buffer. This allows the host to start gathering data for the next write request while the data for the previous request is still in the process of being written. During reading, this mode enables the drive to read ahead after completing a host read request. This allows the drive to gather data for future read requests while the host is still processing data from the previous read request. Under favorable conditions, immediate report mode allows the drive to stream the tape continuously across multiple read/write requests, rather than having to reposition the tape between each read/write request. See .IR ct (7) for more information. .PP By default, .C tcio writes a tape mark in the first block on each tape to prevent the tape from being image restored onto a disk. It also uses the last block on each tape to hold a flag indicating whether or not the tape is the last tape in a multi-tape sequence. .SS Options Every .C tcio command must be followed by a .CR -o , .CR -i , or .C -u option to indicate the type of operation being performed. In addition, the following command options are recognized. They can be specified in any order, but all must precede the .I file name. Options without parameters can be listed individually (each preceded by a .CR - ) or grouped together. Options with parameters require the parameter, and must be listed individually. .RS .TP 15 .C -d Print a checksum to standard error. The checksum is a 32-bit unsigned addition of all bytes written to or read from the tape, providing an extra check of data validity (in addition to tape verification). The checksum value is only reported to the user, and is not written on the media; thus, the user must manually record and check it. The checksum is valid .I only if the same number of bytes are read from the tape as were written to it; in other words, the checksum as a data verification test is meaningless unless the .C -e option was used when writing the tape. This option is independent of the verbose modifier. .TP .C -e Cause a tape mark to be written on the nearest 1024-byte boundary following the end of the data. When a tape containing an end-of-data tape mark is read back, the read terminates upon encountering the tape mark. Thus, by using this option, the checksums generated by the input and output operations are guaranteed to agree. .TP .C -r Unload the tape from the drive. On autochanger units, the tape is returned to the magazine. .TP .C -v Verbose mode; prints information and error messages to standard error. .TP .C -V This option turns off tape verification. Some cartridge tape units (see .SM DEPENDENCIES\s0) provide hardware for verifying the data output to the tape (called "read-while-write"). For these units software-driven verification is somewhat redundant, and this option is suggested as a means of reducing wear on tape heads and transport mechanisms. However, read-while-write verification does not completely eliminate all risk of data loss, so software verification may still be desired in situations where data preservation is critically important. .IP For drives that do not have the read-while-write hardware, a separate verification operation is suggested. Thus, it is recommended that this option not be used with drives that do not support read-while-write. .TP .C -Z Prevents .C tcio from writing a file mark in the first and last blocks. This option should be used with care because a tape without a tape mark in block zero can be image-restored to a disk. .TP .CI -l \0number This option is intended solely for autochanging tape drives. For input or output operations .RC ( -i or .CR -o ) the .C -l option selects the cartridge specified by .I number from the magazine as the first cartridge used in the transfer. For utility operations .RC ( -u option), .C tcio loads the cartridge specified by .I number into the drive. (Note: the autochanger must be in selective mode for the autochanger options to work properly.) Whitespace between .C -l and .I number is optional. .TP .CI -m \0blocknumber This option writes a tape mark on a tape at the specified block. A tape mark in block zero of the tape prevents it from being image-restored to a disk. Whitespace between .C -m and .I blocknumber is optional. .TP .CI -n \0limit This option specifies the maximum number of cartridges to be allowed in a multitape transfer. It applies only to autochanger type units, and must be preceded by the .C -l option. Thus, .C -l starts the transfer by loading cartridge .I number and uses at most .I limit cartridges. If .C -l is specified without .CR -n , .C tcio quietly assumes all remaining cartridges (in ascending order) in the magazine. Whitespace between .C -n and .I limit is optional. .TP .CI -S \0buffersize Enable specification of buffer size. This option forces allocation of a block of memory to be used in reading or writing the tape. The size of the buffer in bytes is 1024 times the value specified for .IR buffersize . If .I buffersize is less than 4, it is silently increased to 4. A .I buffersize greater than 64 is silently decreased to 64. If .I buffersize is not specified, .C tcio allocates a 64K-byte buffer. Whitespace between .C -S and .I buffersize is optional. .IP On tape units that support immediate report, a significant performance increase can often be obtained by using a smaller buffer. 8 Kbytes is the recommended buffer size for these units. On tape units that do not support the immediate report mode, or on tape units that share a controller with a disk (see .SM DEPENDENCIES\s0) that is simultaneously being accessed, an increase in performance can usually be obtained with a larger buffer. 64K bytes, the default, is the recommended buffer size for these units. .TP .CI -T \0tty Specify .I tty as an alternative to .CR /dev/tty . Normally .C /dev/tty is opened by .C tcio when terminal interaction is required. The specified file .I tty is opened instead of .CR /dev/tty . Whitespace between .C -T and .I tty is optional. If no input device is available, use .CR /dev/null . .SH EXAMPLES Copy the contents of a directory into an archive: .IP .C ls\0|\0cpio\0-o\0|\0tcio\0-o\0/dev/rct/c4t1d0 .PP Restore it: .IP .C tcio\0-i\0/dev/rct/c4t1d0\0|\0cpio\0-i .PP Unload the cartridge from the drive (without verifying the tape): .IP .C tcio -urV /dev/rct/c4t1d0 .PP Copy all files in the current directory to the tape specified by the device file > .CR /dev/rct/c4t1d0 . The device has a read-while-write head, so verify is turned off; a buffer size (option .CR -S) of 8 blocks (8 Kbytes) is to be used: .IP .C "ls | cpio -o | tcio -oV -S 8 /dev/rct/c4t1d0" .PP Assume that the cartridge tape unit is an autochanger on controller 2, with 8 tapes in the magazine. Start writing with cartridge 3, and use at most 4 cartridges before prompting the user for additional media: .IP .C "find usr -cpio | tcio -oV -S 8 -l 3 -n 4 /dev/rct/c2t0d0" .SH DEPENDENCIES .SS HP\|7941CT, HP\|9144A, HP\|9145A, and HP\|35401 These cartridge tape devices contain read-while-write hardware and support immediate report mode. .SS HP\|7942, HP\|7946 These cartridge tape devices contain read-while-write hardware and support immediate report mode. Use of a small buffer size is not recommended with these shared-controller devices when simultaneous access to the disk is also required because the intervening disk accesses prevent proper tape streaming. .SS HP\|7908, HP\|7911, HP\|7912, and HP\|7914 These cartridge tape devices do not contain read-while-write hardware, and therefore do not support immediate report mode. .SH AUTHOR .C tcio was developed by HP. .SH SEE ALSO ct(7). .PP .I HP-UX System Administrator Manuals. .\" .\" index@\f4tcio\f1 \- Command Set 80 Cartridge Tape Utility@@@\f3tcio(1)\f1 .\" index@Command Set 80 Cartridge Tape \s-1I/O\s+1 Utility@@@\f3tcio(1)\f1 .\" index@\s-1CS/80\s+1 Cartridge Tape \s-1I/O\s+1 Utility@@@\f3tcio(1)\f1 .\" index@Cartridge Tape \s-1I/O\s+1 Utility, \s-1CS/80\s+1@@@\f3tcio(1)\f1 .\" index@Tape Cartridge \s-1I/O\s+1 Utility, \s-1CS/80\s+1@@@\f3tcio(1)\f1 .\" .\" toc@\f3tcio(1)\f1:\0\0\f4tcio\f1@@@Command Set 80 Cartridge Tape Utility .\" .\" fileset_database@tcio.1 USER-CMDS-MAN .\" $Header: tee.1,v 76.2 95/08/04 17:30:30 ssa Exp $ .TA t .TH tee 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tee \- pipe fitting .SH SYNOPSIS .C tee .RC [ -i ] .RC [ -a ] .RI [ \|file\| ]\0... .SH DESCRIPTION The .CR tee command transcribes the standard input to the standard output and makes copies in the .IR files . .SH OPTIONS .RS .TP 10 .CR -i This option ignores interrupts. .TP .CR -a This option appends the output to the .I files rather than overwriting the .IR files . .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C tee behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE The .CR tee command returns zero upon successful completion, or nonzero if the command fails. .SH EXAMPLES Write a list of users to the screen and also append the list to the file .CR hunt : .IP .C who | tee -a hunt .SH STANDARDS CONFORMANCE .CR tee ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" toc@\f3tee(1)\f1:\0\0\f4tee\f1@@@pipe fitting\f1 .\" .\" index@\f4tee\f1 \- pipe fitting@@@\f3tee(1)\f1 .\" index@\f1pipe fitting@@@\f3tee(1)\f1 .\" index@\f1files, send copy of standard output to specified file@@@\f3tee(1)\f1 .\" index@\f1send copy of standard output to specified file@@@\f3tee(1)\f1 .\" index@\f1copy of standard output, send to specified file@@@\f3tee(1)\f1 .\" index@\f1standard output, send copy of to specified file@@@\f3tee(1)\f1 .\" index@\f1output, standard, send copy of to specified file@@@\f3tee(1)\f1 .\" $Header: telnet.1,v 78.1 96/05/09 11:03:54 ssa Exp $ .TA t .TH telnet 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME telnet \- user interface to the \s-1TELNET\s+1 protocol .SH SYNOPSIS .C telnet .RI [\|[ \|options \|] \|host .RI [ \|port\| ]\|] .SH DESCRIPTION .C telnet is used to communicate with another host using the TELNET protocol. If .C telnet is invoked without arguments, it enters command mode, indicated by its prompt .RC ( telnet> ). In this mode, it accepts and executes the commands listed below. If .C telnet is invoked with arguments, it performs an .C open command (see below) with those arguments. .PP Once a connection has been opened, .C telnet enters an input mode. The input mode will be either ``character at a time'' or ``line by line'', depending on what the remote system supports. .PP In ``character at a time'' mode, most text typed is immediately sent to the remote host for processing. .PP In ``line by line'' mode, all text is echoed locally, and (normally) only completed lines are sent to the remote host. The ``local echo character'' (initially .CR ^E ) can be used to turn off and on the local echo (this would mostly be used to enter passwords without the password being echoed). .PP In either mode, if the .C localchars toggle is TRUE (the default in line mode; see below), the user's .C quit and .C intr characters are trapped locally, and sent as TELNET protocol sequences to the remote side. There are options (see .C toggle autoflush and .C toggle autosynch below) which cause this action to flush subsequent output to the terminal (until the remote host acknowledges the TELNET sequence) and flush previous terminal input (in the case of .C quit and .CR intr ). .PP While connected to a remote host, .C telnet command mode can be entered by typing the .C telnet ``escape character'' (initially .CR ^] ). When in command mode, the normal terminal editing conventions are available. .PP .C telnet supports eight-bit characters when communicating with the server on the remote host. To use eight-bit characters you may need to reconfigure your terminal or the remote host appropriately (see .IR stty (1)). Furthermore, you may have to use the .C binary toggle to enable an 8-bit data stream between .C telnet and the remote host. Note that some remote hosts may not provide the necessary support for eight-bit characters. .PP If, at any time, .C telnet is unable to read from or write to the server over the connection, the message .C "Connection closed by foreign host." is printed on standard error. .C telnet then exits with a value of 1. .PP .CR telnet supports the TAC User ID (also known as the TAC Access Control System, or TACACS User ID) option. Enabling the option on a host server allows the user to .CR telnet into that host without being prompted for a second login sequence. The TAC User ID option uses the same security mechanism as .CR rlogin for authorizing acces by remote hosts and users. The system administrator must enable the (telnetd) option only on systems which are designated as participating hosts. The system administrator must also assign to each user of TAC User ID the very same UID on every system for which he is allowed to use the feature. (See .IR telnetd (1M) and the .IR "System Administration Tasks" manual, PN 2355-90051.) .PP The following .C telnet options are available: .TP 10 .C -8 Enable cs8 (8 bit transfer) on local tty. .TP .C -e\|c Set the .C telnet command mode escape character to be .CR ^c instead of its default value of .CR ^] . .TP .C -l Disable the TAC User ID option if enabled on the client, to cause the user to be prompted for login username and password. Omitting the -l option executes the default setting. .SS Commands The following commands are available in command mode. You need only type enough of each command to uniquely identify it (this is also true for arguments to the .CR mode , .CR set , .CR toggle , and .C display commands). .TP 15 .CR open \0\f2host\f1\0\|[\f2\|port\f1\|] Open a connection to the named host at the indicated port. If no port is specified, .C telnet attempts to contact a TELNET server at the standard TELNET port. The hostname can be either the official name or an alias as understood by .C gethostbyname() (see .IR gethostent (3N)), or an Internet address specified in the dot notation as described in .IR hosts (4). If no hostname is given, .C telnet prompts for one. .TP .C close Close a TELNET session. If the session was started from command mode, .C telnet returns to command mode; otherwise .C telnet exits. .TP .C quit Close any open TELNET session and exit .CR telnet . An end of file (in command mode) will also close a session and exit. .TP .C z Suspend .CR telnet . If .C telnet is run from a shell that supports job control, (such as .IR csh (1) or .IR ksh (1)), the .C z command suspends the TELNET session and returns the user to the shell that invoked .CR telnet . The job can then be resumed with the .C fg command (see .IR csh (1) or .IR ksh (1)). .TP .CI mode \0mode Change .CR telnet 's user input mode to .IR mode , which can be .C character (for ``character at a time'' mode) or .C line (for ``line by line'' mode). The remote host is asked for permission to go into the requested mode. If the remote host is capable of entering that mode, the requested mode is entered. In .C character mode, .C telnet sends each character to the remote host as it is typed. In .C line mode, .C telnet gathers user input into lines and transmits each line to the remote host when the user types carriage return, linefeed, or EOF (normally .CR ^D ; see .IR stty (1)). Note that setting line-mode also sets local echo. Applications that expect to interpret user input character by character (such as .CR more , .CR csh , .CR ksh , and .CR vi ) do not work correctly in line mode. .TP .C status Show current status of .CR telnet . .C telnet reports the current escape character. If .C telnet is connected, it reports the host to which it is connected and the current .CR mode. If .C telnet is not connected to a remote host, it reports .C No connection. Once .C telnet has been connected, it reports the local flow control toggle value. .TP .CR display \0[\|\f2argument\f1\0...\|] Displays all or some of the .C set and .C toggle values (see below). .TP .CR ? \0[\|\f2command\f1\|] Get help. With no arguments, .C telnet prints a help summary. If a command is specified, .C telnet prints the help information available about that command only. Help information is limited to a one-line description of the command. .TP .CR ! \0[\|\f2shell_command\f1\|] Shell escape. The .C SHELL environment variable is checked for the name of a shell to use to execute the command. If no .I shell_command is specified, a shell is started and connected to the user's terminal. If .C SHELL is undefined, .C /usr/bin/sh is used. .TP .CI send \0arguments Sends one or more special character sequences to the remote host. Each .I argument can have any of the following values (multiple .IR argument s can be specified with each .C send command): .RS .RS .TP 10 .C escape Sends the current .C telnet escape character (initially .CR ^] ). .TP .C synch Sends the TELNET SYNCH sequence. This sequence causes the remote system to discard all previously typed (but not yet read) input. This sequence is sent as TCP urgent data (and may not work to some systems -- if it doesn't work, a lower case ``r'' may be echoed on the terminal). .TP .C brk Sends the TELNET BRK (Break) sequence, which may have significance to the remote system. .TP .C ip Sends the TELNET IP (Interrupt Process) sequence, which should cause the remote system to abort the currently running process. .TP .C ao Sends the TELNET AO (Abort Output) sequence, which should cause the remote system to flush all output .I from the remote system .I to the user's terminal. .TP .C ayt Sends the TELNET AYT (Are You There) sequence, to which the remote system may or may not choose to respond. .TP .C ec Sends the TELNET EC (Erase Character) sequence, which should cause the remote system to erase the last character entered. .TP .C el Sends the TELNET EL (Erase Line) sequence, which should cause the remote system to erase the line currently being entered. .TP .C ga Sends the TELNET GA (Go Ahead) sequence, which likely has no significance to the remote system. .TP .C nop Sends the TELNET NOP (No OPeration) sequence. .TP .C ? Prints out help information for the .C send command. .RE .RE .TP .CI set \0variable_name\0value Set any one of a number of .C telnet variables to a specific value. The special value .C off turns off the function associated with the variable. The values of variables can be shown by using the .C display command. The following .IR variable_name s can be specified: .RS .TP .C echo This is the value (initially .CR ^E ) which, when in line-by-line mode, toggles between doing local echoing of entered characters (for normal processing), and suppressing echoing of entered characters (for entering, for example, a password). .TP .C escape This is the .C telnet escape character (initially .CR ^] ) which causes entry into .C telnet command mode (when connected to a remote system). .TP .C interrupt If .C telnet is in .C localchars mode (see .C toggle .C localchars below) and the .I interrupt character is typed, a TELNET IP sequence (see .C send ip above) is sent to the remote host. The initial value for the interrupt character is taken to be the terminal's .C intr character. .TP .C quit If .C telnet is in .C localchars mode (see .C toggle .C localchars below) and the .C quit character is typed, a TELNET BRK sequence (see .C send brk above) is sent to the remote host. The initial value for the quit character is taken to be the terminal's .C quit character. .TP .C flushoutput If .C telnet is in .C localchars mode (see .C toggle localchars below) and the .C flushoutput character is typed, a TELNET AO sequence (see .C send ao above) is sent to the remote host. The initial value for the flush character is .CR ^O . .TP .C erase If .C telnet is in .C localchars mode (see .C toggle localchars below), .I and if .C telnet is operating in character-at-a-time mode, then when this character is typed, a TELNET EC sequence (see .C send ec above) is sent to the remote system. The initial value for the erase character is taken to be the terminal's .C erase character. .TP .C kill If .C telnet is in .C localchars mode (see .C toggle localchars below), .I and if .C telnet is operating in character-at-a-time mode, then when this character is typed, a TELNET EL sequence (see .C send el above) is sent to the remote system. The initial value for the kill character is taken to be the terminal's .C kill character. .TP .C eof If .C telnet is operating in line-by-line mode, entering this character as the first character on a line causes this character to be sent to the remote system. The initial value of the .C eof character is taken to be the terminal's .C eof character. .RE .TP .CI toggle \0arguments\0... Toggle (between TRUE and FALSE ) various flags that control how .C telnet responds to events. More than one argument can be specified. The state of these flags can be shown by using the .C display command. Valid arguments are: .RS .RS .TP .C localchars .br If TRUE, the .CR flush , .CR interrupt , .CR quit , .CR erase , and .C kill characters (see .C set above) are recognized locally, and transformed into appropriate TELNET control sequences (respectively .CR ao , .CR ip , .CR brk , .CR ec , and .CR el ; see .C send above). The initial value for this toggle is .C TRUE in line-by-line mode, and .C FALSE in character-at-a-time mode. .TP .C autoflush If .C autoflush and .C localchars are both TRUE, whenever the .CR ao , .CR intr , or .C quit characters are recognized (and transformed into TELNET sequences \(mi see .C set above for details), .C telnet refuses to display any data on the user's terminal until the remote system acknowledges (via a TELNET .I Timing Mark option) that it has processed those TELNET sequences. The initial value for this toggle is TRUE. .TP .C autosynch If .C autosynch and .C localchars are both TRUE, when either the .C intr or .C quit character is typed (see .C set above for descriptions of the .C intr and .C quit characters), the resulting TELNET sequence sent is followed by the TELNET SYNCH sequence. This procedure .I should cause the remote system to begin discarding all previously typed input until both of the TELNET sequences have been read and acted upon. The initial value of this toggle is FALSE. .TP .C binary Enable or disable the TELNET BINARY option on both input and output. This option should be enabled in order to send and receive 8-bit characters to and from the TELNET server. .TP .C crlf If TRUE, end-of-line sequences are sent as an ASCII carriage-return and line-feed pair. If FALSE, end-of-line sequences are sent as an ASCII carriage-return and NUL character pair. The initial value for this toggle is FALSE. .TP .C crmod Toggle carriage return mode. When this mode is enabled, any carriage return characters received from the remote host are mapped into a carriage return and a line feed. This mode does not affect those characters typed by the user; only those received. This mode is only required for some hosts that require the client to do local echoing, but output ``naked'' carriage returns. The initial value for this toggle is FALSE. .TP .C echo Toggle local echo mode or remote echo mode. In local echo mode, user input is echoed to the terminal by the local .C telnet before being transmitted to the remote host. In remote echo, any echoing of user input is done by the remote host. Applications that handle echoing of user input themselves, such as C shell, Korn shell, and .C vi (see .IR csh (1), .IR ksh (1), and .IR vi (1)), do not work correctly with local echo. .TP .C options Toggle viewing of TELNET options processing. When options viewing is enabled, all TELNET option negotiations are displayed. Options sent by .C telnet are displayed as .CR ``SENT'' , while options received from the TELNET server are displayed as .CR ``RCVD'' . The initial value for this toggle is FALSE. .TP .C netdata Toggles the display of all network data (in hexadecimal format). The initial value for this toggle is FALSE. .TP .C ? Displays the legal .C toggle commands. .RE .RE .SH RETURN VALUE In the event of an error, or if the TELNET connection is closed by the remote host, .C telnet returns a value of 1. Otherwise it returns zero (0). .SH DIAGNOSTICS The following diagnostic messages are displayed by .CR telnet : .RS .TP .C "telnet/tcp: Unknown service" .C telnet was unable to find the TELNET service entry in the .IR services (4) database. .TP .IC hostname :\0Unknown\0host .C telnet was unable to map the host name to an Internet address. Your next step should be to contact the system administrator to check whether there is an entry for the remote host in the .C hosts database (see .IR hosts (4)). .TP .C "?Invalid command" An invalid command was typed in .C telnet command mode. .TP .IC "system call" >:\0 \f1... An error occurred in the specified system call. See the appropriate manual entry for a description of the error. .SH AUTHOR .C telnet was developed by the University of California, Berkeley. .SH SEE ALSO csh(1), ksh(1), login(1), rlogin(1), stty(1), telnetd(1M), hosts(4), services(4), termio(7). .\" .\" index@\f4telnet\f1 \- user interface to the \s-1TELNET\s+1 protocol@@@\f3telnet(1)\f1 .\" index@\f1user interface to the \s-1TELNET\s+1 protocol@@@\f3telnet(1)\f1 .\" index@\f1interface to the \s-1TELNET\s+1 protocol, user@@@\f3telnet(1)\f1 .\" index@\f1TELNET protocol, user interface to the@@@\f3telnet(1)\f1 .\" index@\f1protocol, user interface to the \s-1TELNET\s+1@@@\f3telnet(1)\f1 .\" .\" toc@\f3telnet(1)\f1:\0\0\f4telnet\f1@@@user interface to the \s-1TELNET\s+1 protocol .\" .\" fileset_database@telnet.1 INETSVCS-MAN .\" $Header: test.1,v 76.1 95/08/04 17:32:05 ssa Exp $ .TA t .TH test 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME test \- condition evaluation command .SH SYNOPSIS .C test .I expr .br .CI [ \0expr\0 ] .SH DESCRIPTION The .CR test command evaluates the expression .I expr and, if its value is True, returns a zero (true) exit status; otherwise, a nonzero (false) exit status is returned. .CR test also returns a nonzero exit status if there are no arguments. The following primitives are used to construct .IR expr : .RS .TP 15 .CI -r \0file True if .I file exists and is readable. .TP .CI -w \0file True if .I file exists and is writable. .TP .CI -x \0file True if .I file exists and is executable. .TP .CI -f \0file True if .I file exists and is a regular file. .TP .CI -d \0file True if .I file exists and is a directory. .TP .CI -c \0file True if .I file exists and is a character special file. .TP .CI -b \0file True if .I file exists and is a block special file. .TP .CI -p \0file True if .I file exists and is a named pipe (fifo). .TP .CI -u \0file True if .I file exists and its set-user-ID bit is set. .TP .CI -g \0file True if .I file exists and its set-group-ID bit is set. .TP .CI -k \0file True if .I file exists and its sticky bit is set. .TP .CI -s \0file True if .I file exists and has a size greater than zero. .TP .CI -h \0file True if .I file exists and is a symbolic link. .TP .CR -t \0[\|\f2fildes\f1\|] True if the open file whose file descriptor number is .I fildes (1 by default) is associated with a terminal device. .TP .CI -z \0s1 True if the length of string .I s1 is zero. .TP .CI -n \0s1 True if the length of the string .I s1 is non-zero. .TP .IC s1\0 = \0s2 True if strings .I s1 and .I s2 are identical. .TP .IC s1\0 != \0s2 True if strings .I s1 and .I s2 are .I not identical. .TP .I s1 True if .I s1 is .I not the null string. .TP .IC n1\0 -eq \0n2 True if the integers .I n1 and .I n2 are algebraically equal. Any of the comparisons .CR -ne , .CR -gt , .CR -ge , .CR -lt , and .CR -le can be used in place of .CR -eq . .RE .PP These primaries can be combined with the following operators: .RS .TP 15 .C ! Unary negation operator. .TP .C -a Binary AND operator. .TP .C -o Binary OR operator .RC ( -a has higher precedence than .CR -o ). .TP .CI ( \0expr\0 ) Parentheses for grouping. .RE .PP Note that all the operators and flags are separate arguments to .CR test . Note also that parentheses are significant to the shell and therefore must be escaped. .PP .C test is interpreted directly by the shell, and therefore does not exist as a separate executable program. .SH EXTERNAL INFLUENCES .SS International Code Set Support Single byte and multibyte character code sets are supported. .ift .br .ift .ne 62 .SH EXAMPLES Exit if there are not two or three arguments: .IP .C "if [ $# -l2 2 -o $# -gt 3 ]; then exit 1; fi" .PP Create a new file containing the text string .CR default if the file does not already exist: .IP .C "[ ! -f thisfile ] && echo default > thisfile" .PP Wait for myfile to become non-readable: .nf .IP .C while test -r myfile .C do .C " sleep 30" .C done .C echo '"myfile" is no longer readable' .fi .SH WARNINGS When the .CR [ form of this command is used, the matching .CR ] must be the final argument, and both must be separate arguments from the arguments they enclose (white space delimiters required. .PP Parentheses and other special shell metacharacters intended to be handled by test must be escaped or quoted when invoking .CR test from a shell. .PP Avoid such problems when comparing strings by inserting a non-operator character at the beginning of both operands: .IP .C test \&"X$response" = \&"Xexpected string" .PP This approach does not work with numeric comparisons or the unary operators because it would affect the operand being checked. .SH AUTHOR .CR test was developed by the University of California, Berkeley and HP. .SH SEE ALSO find(1), sh(1). .SH STANDARDS CONFORMANCE .CR test ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR [ ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4test\f1 \- evaluate condition for true or false@@@\f3test(1)\f1 .\" index@\f1evaluate condition for true or false@@@\f3test(1)\f1 .\" index@\f1true/false evaluate condition for@@@\f3test(1)\f1 .\" index@\f1false/true evaluate condition for@@@\f3test(1)\f1 .\" index@\f1condition, evaluate for true/false@@@\f3test(1)\f1 .\" .\" toc@\f3test(1)\f1:\0\0\f4test\f1@@@condition evaluation command\f1 .\" $Header: tftp.1,v 72.4 94/07/05 11:56:48 ssa Exp $ .TA t .TH tftp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tftp \- trivial file transfer program .SH SYNOPSIS .C tftp .RI [ \|host\| ] .SH DESCRIPTION .C tftp is the user interface to the Internet TFTP (Trivial File Transfer Protocol), that allows users to transfer files to and from a remote machine. The remote .I host can be specified on the command line, in which case .C tftp uses .I host as the default host for future transfers (see the .C connect command below). .SS Commands Once .C tftp is running, it issues the prompt .C tftp> and recognizes the following commands: .RS .TP 12 .CR connect \0\f2host-name\fP\0[\|\f2port\fP\|] Set the .I host (and optionally .IR port ) for transfers. Note that the TFTP protocol, unlike the FTP protocol, does not maintain connections between transfers; thus, the .C connect command does not actually create a connection, but merely remembers what host is to be used for transfers. You do not have to use the .C connect command; the remote host can be specified as part of the .C get or .C put commands. .TP .CI mode \0transfer-mode Set the mode for transfers; .I transfer-mode can be one of .C ascii or .C binary (default is .CR ascii ). .TP .CI put \0file .PD 0 .TP .CI put \0localfile\0remotefile .TP .CI put " file1 file2 ... fileN remotedirectory" Put a file or set of files to the specified remote file or directory. The destination can be in one of two forms: a filename on the remote host if the host has already been specified, or a string of the form .IC host : filename to specify both a host and filename at the same time. If the latter form is used, the hostname specified becomes the default for future transfers. If the remote-directory form is used, the remote host is assumed to be a UNIX\s0-like machine. .PD .TP .CI get \0filename .PD 0 .TP .CI get \0remotename\0localname .TP .CI get " file1 file2 ... fileN" Get a file or set of files from the specified .IR source s. .I source can be in one of two forms: a filename on the remote host if the host has already been specified, or a string of the form .IC host : filename to specify both a host and filename at the same time. If the latter form is used, the last hostname specified becomes the default for future transfers. .PD .TP .C quit Exit .CR tftp . Typing the end-of-file character also causes an exit. .TP .C verbose Toggle verbose mode. .TP .C trace Toggle packet tracing. .TP .C status Show current status. .TP .CI rexmt " retransmission-timeout" Set the per-packet retransmission timeout, in seconds. .TP .CI timeout " total-transmission-timeout" Set the total transmission timeout, in seconds. .TP .C ascii Shorthand for "mode ascii" .TP .C binary Shorthand for "mode binary" .TP .CR ? \ [\|\f2command-name\fP\|...\|] Print help information. .SH WARNINGS Since there is no user-login or validation within the TFTP protocol, the remote site probably has some sort of file-access restrictions in place. The exact methods are specific to each site and are therefore difficult to document here. .SH AUTHOR .C tftp was developed by the University of California, Berkeley. .SH SEE ALSO tftpd(1m). .\" .\" index@\f4tftp\f1 \- trivial file transfer program@@@\f3tftp(1)\f1 .\" index@\f1trivial file transfer program@@@\f3tftp(1)\f1 .\" index@\f1file transfer program, trivial@@@\f3tftp(1)\f1 .\" index@\f1transfer program, trivial file@@@\f3tftp(1)\f1 .\" .\" toc@\f3tftp(1)\f1:\0\0\f4tftp\f1@@@trivial file transfer program .\" .\" fileset_database@tftp.1 INETSVCS-MAN .\" $Header: time.1,v 76.1 95/08/23 17:46:15 ssa Exp $ .TA t .TH time 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME time \- time a command .SH SYNOPSIS .C time .I command .PP .PP (XPG4 only.) .CR time .RC [ -p ] .I utility .RI [ argument... ] .SH DESCRIPTION .I command is executed. Upon completion, .C time prints the elapsed time during the command, the time spent in the system, and the time spent executing the command. Times are reported in seconds. .PP Execution time can depend on the performance of the memory in which the program is running. .PP The times are printed on standard error. .PP .SS Options .CR time recognizes the following option: .RS .TP 6 .CR -p (XPG4 only.) Writes the timing statistics to standard error. .SH SEE ALSO sh(1), timex(1), times(2). .SH STANDARDS CONFORMANCE .CR time ": SVID2, XPG2, XPG3, XPG4, POSIX.2 " .\" .\" toc@\f3time(1)\f1:\0\0\f4time\f1@@@time a command .\" .\" index@\f4time\f1 \- measure time used to execute a command@@@\f3time(1)\f1 .\" index@measure time used to execute a command@@@\f3time(1)\f1 .\" index@execute a command, measure time used to@@@\f3time(1)\f1 .\" index@command, measure time used to execute a@@@\f3time(1)\f1 .\" $Header: timex.1,v 72.6 94/11/14 15:21:46 ssa Exp $ .TA t .TH timex 1 "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME timex \- time a command; report process data and system activity .SH SYNOPSIS .C timex .RC [ -o ] .RC [ -p [ fhkmrt ]\|] .RC [ -s ] .I command .SH DESCRIPTION .C timex reports in seconds the elapsed time, user time, and system time spent in execution of the given .IR command . Optionally, process accounting data for .I command and all its children can be listed or summarized, and total system activity during the execution interval can be reported. .PP The output of .C timex is written on the standard error. .SS Options .RS .TP 15 .C -o Report the total number of blocks read or written and total characters transferred by .I command and all its children. .TP .CR -p [ fhkmrt ] List process accounting records for .I command and all its children. The suboptions .CR f , .CR h , .CR k , .CR m , .CR r , and .C t modify the data items reported. They behave as defined in .IR acctcom (1M). The number of blocks read or written and the number of characters transferred are always reported. .TP .C -s Report total system activity (not just that due to .IR command ) that occurred during the execution interval of .IR command . All the data items listed in .IR sar (1) are reported. .RE .SH EXAMPLES A simple example: .IP .C timex -ops sleep 60 .PP A terminal session of arbitrary complexity can be measured by timing a sub-shell: .IP .C timex -opskmt sh .RS .IP .I session commands .RE .IP .SM EOT .SH WARNINGS Process records associated with .I command are selected from the accounting file .C /var/adm/pacct by inference, since process genealogy is not available. Background processes having the same user-\c .SM ID, terminal-\c .SM ID, and execution time window are spuriously included. .SH SEE ALSO sar(1), acctcom(1M). .SH STANDARDS CONFORMANCE .CR timex ": SVID2, SVID3" .\" .\" toc@\f3timex(1)\f1:\0\0\f4timex\f1@@@time a command; report process data and system activity .\" .\" index@\f4timex\f1 \- time a command; report process accounting data and system activity@@@\f3timex(1)\f1 .\" index@time a command; report process accounting data and system activity@@@\f3timex(1)\f1 .\" index@command, report execution time of, process accounting data and system activity@@@\f3timex(1)\f1 .\" $Header: top.1,v 72.3 93/01/14 11:42:10 ssa Exp $ .TA t .TH top 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME top \- display and update information about the top processes on the system .SH SYNOPSIS .C top .RC [ -s .IR time\| ] .RC [ -d .IR count\| ] .RC [ -q ] .RC [ -u ] .RC [ -n .IR number\| ] .SH DESCRIPTION .C top displays the top processes on the system and periodically updates the information. Raw .SM CPU percentage is used to rank the processes. .SS Options .C top recognizes the following command-line options: .RS .TP 12 .CI -s \0time Set the delay between screen updates to .I time seconds. The default delay between updates is 5 seconds. .TP .CI -d \0count Show only .I count displays, then exit. A display is considered to be one update of the screen. This option is used to select the number of displays to be shown before the program exits. .TP .C -q This option runs the .C top program at the same priority as if it is executed via a .C nice -20 command so that it will execute faster (see .IR nice (1)). This can be very useful in discovering any system problem when the system is very sluggish. This option is accessibly only to users who have appropriate privileges. .TP .C -u User .SM ID (uid) numbers are displayed instead of usernames. This improves execution speed by eliminating the additional time required to map uid numbers to user names. .TP .CI -n \0number Show only .I number processes per screen. Note that this option is ignored if .I number is greater than the maximum number of processes that can be displayed per screen. .RE .SS Screen-Control Commands When displaying multiple-screen data, .C top recognizes the following keyboard screen-control commands: .RS .TP 12 .C j Display next screen if the current screen is not the last screen. .TP .C k Display previous screen if the current screen is not the first screen. .TP .C t Display the first (top) screen. .RE .SS Program Termination To exit the program and resume normal user activities, type .C q at any time. .SS Display Description Three general classes of information are displayed by .CR top : .RS .TP 5 .C System Data: The first few lines at the top of the display show general information about the state of the system, including: .RS .RS .TP 3 \(bu System name and current time. .TP \(bu Load averages in the last one, five, and fifteen minutes. .TP \(bu Number of existing processes and the number of processes in each state (sleeping, waiting, running, starting, zombie, and stopped). .TP \(bu Percentage of time spent in each of the processor states (user, nice, system, idle, interrupt and swapper) per processor on the system. .TP \(bu Average value for each of the processor states (only on multi-processor systems). .RE .RE .TP .C Memory Data Includes virtual and real memory in use (with the amount of memory considered "active" in parentheses) and the amount of free memory. .TP .C Process Data Information about individual processes on the system. When process data cannot fit on a single screen, .C top divides the data into two or more screens. To view multiple-screen data, use the .CR j , .CR k , and .C t commands described previously. Note that the system- and memory-data displays are present in each screen of multiple-screen process data. .IP Process data is displayed in a format similar to that used by .IR ps (1): .RS .RS .TP 12 .C CPU Processor number on which the process is executing (only on multi-processor systems). .TP .C TTY Terminal interface used by the process. .TP .C PID Process .SM ID number. .TP .C USERNAME Name of the owner of the process. When the .C -u option is specified, the user .SM ID (uid) is displayed instead of .CR USERNAME . .TP .C PRI Current priority of the process. .TP .C NI Nice value ranging from \(mi20 to +20. .TP .C SIZE Total size of the process in kilobytes. This includes text, data, and stack. .TP .C RES Resident size of the process in kilobytes. The resident size information is, at best, an approximate value. .TP .C STATE Current state of the process. The various states are .CR sleep , .CR wait , .CR run , .CR idl , .CR zomb , or .CR stop . .TP .C TIME Number of system and .SM CPU seconds the process has consumed. .TP .C %WCPU Weighted .SM CPU (central processing unit) percentage. .TP .C %CPU Raw .SM CPU percentage. This field is used to sort the top processes. .TP .C COMMAND Name of the command the process is currently running. .RE .RE .SH EXAMPLES .C top can be executed with or without command-line options. To display five screens of data at two-second intervals then automatically exit, use: .IP .C top -s2 -d5 .SH AUTHOR .C top was developed by HP and William LeFebvre of Rice University. .\" .\" toc@\f3top(1)\f1:\0\0\f4top\f1@@@display and update information about top processes on system .\" .\" index@\f4top\f1 \- display and update information about top processes on system@@@\f3top(1)\f1 .\" index@display and update information about top processes on system@@@\f3top(1)\f1 .\" index@information about top processes on system, display and update@@@\f3top(1)\f1 .\" index@processes on system, display and update information about top@@@\f3top(1)\f1 .\" index@system, display and update information about top processes on@@@\f3top(1)\f1 .\" .\" fileset_database@top.1 USER-CMDS-MAN .\" $Header: touch.1,v 76.2 95/08/04 17:33:07 ssa Exp $ .TA t .TH touch 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME touch \- update access, modification, and/or change times of file .SH SYNOPSIS .C touch .RC [ -amc ] .RC [ -r .I ref_file\| ] .RC [ -t .IR time\| ] .I file_name\f1 ... .SS Obsolescent: .C touch .I time_str .I file_name\f1 ... .SH DESCRIPTION .C touch updates the access, modification, and last-change times of each argument. The file name is created if it does not exist. If no time is specified (see .IR date (1)) the current time is used. .PP The .C -r and .C -t options are mutually exclusive. .SS Options The following options are available: .RS .TP 10 .C -a Change the access time of .I file_name to .IR time , or to the current time if .I time is not specified. Do not change the modification time unless .C -m is also specified. .TP .C -m Change the modification time of .I file_name to .IR time , or to the current time if .I time is not specified. Do not change the access time unless .C -a is also specified. .TP .C -c Silently prevent .C touch from creating the file if it did not previously exist. Do not write any diagnostic messages concerning this condition. .TP .CI -r \0ref_file Use the corresponding time of .I ref_file instead of the current time. .TP .CI -t \0time Use the specified .I time instead of the current time. The option argument is a decimal number of the form: .IP [\|[\|\s-1CC\s+1\|]\|\s-1YY\s+1\|]\|\s-1MMDD\s+1hhmm\|[\|.\s-1SS\s+1\|] .IP where each two digits represents the following: .RS 15 .TP 8 .SM .I CC The first two digits of the year. .TP .SM .I YY The second two digits of the year. .TP .SM .I MM The month of the year (01-12). .TP .SM .I DD The day of the month (01-31). .TP .I hh The hour of the day (00-23). .TP .I mm The minute of the hour (00-59). .TP .SM .I SS The second of the minute (00-61). .RE .IP If neither .SM .I CC nor .SM .I YY is given, the current year is assumed. If .SM .I YY is specified, but .SM .I CC is not, .SM .I CC is derived as follows: .RS .IP .TS l l c c. If \f2\s-1YY\s0\fP is: \f2\s-1CC\s0\fP becomes: _ 69-99 19 00-68 20 .TE .RE .IP If the resulting time value precedes the Epoch (00:00:00 January 1, 1970 Greenwich Mean Time), .C touch exits immediately with an error status. .IP The range for .SM SS is 00 through 61 rather than 00 through 59 to accommodate leap seconds. If .SM SS is 60 or 61, and the resulting time, as affected by the .C TZ environment variable, does not refer to a leap second, the resulting time is one second after a time where .SM SS is 59. If .SM SS is not given a value, it is assumed to be 0. .RE .PP The syntax shown by the second .SM SYNOPSIS line is recognized when neither the .C -r option, the .C -t option, nor the .C -\|- option delimiter is specified, and the first operand consists of all decimal digits. This operand is interpreted as the .I time argument instead of as a file name. However, in this case, .I time_str is assumed to be of the form: .IP \s-1MMDD\s+1hhmm\|[\|\s-1YY\s+1\|] .PP This is for backward compatibility. The .C -t form given above is recommended for future portability. The .C -\|- option delimiter can be used before the first .I file_name if there is a possibility that .I file_name consists of all digits, in order to ensure that the first syntax is used. .PP .C touch succeeds .I only when invoked by the .I owner of the file if any of the following are true: .RS .TP 3 \(bu A time is specified, .TP \(bu Only the access time of the file is being updated, or .TP \(bu Only the modification time of the file is being updated. .RE .PP In addition, .C touch succeeds when invoked by a user with write permission on the file if both of the following are true: .RS .TP 3 \(bu No time is specified, .I and .TP \(bu .I Both the access time and modification time of the file are being updated. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .TP .C TZ If the time is specified via the .C -t option, .C TZ is used to interpret the time for the specified time zone. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C touch behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .C touch returns zero if all .I file_name arguments were successfully changed. .PP .C touch returns non-zero and prints out a diagnostic message if an invalid time or a time earlier than the Epoch was specified with the .C -t option, or if the .C -r and .C -t options were both specified, or if one or more of the .I file_name arguments could not be accessed. .SH EXAMPLES The following command sets the modification and access times of the file named "bastille" to midnight, July 14, 1989, creating the file if it does not already exist. .IP .C "touch -t 8907140000 bastille" .PP The following command does the same thing using the backward-compatible syntax: .IP .C "touch 0714000089 bastille" .PP The following command sets the time of the two files named "0714000089" and "bastille" to the current time, creating them if they do not exist: .IP .C "touch -- 0714000089 bastille" .PP To create a zero-length file, use any of the following: .IP .CI touch \0file .br .CI "cat /dev/null >" file .br .CI "cp /dev/null " file .SH DEPENDENCIES .SS \s-1NFS\s0: An attempt to touch a file owned by the super-user on a remote server might fail, even if the invoking user has write permission on the file. .SH SEE ALSO date(1), utime(2). .SH STANDARDS CONFORMANCE .CR touch ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4touch\f1 \- update access, modification, and/or change times of a file@@@\f3touch(1)\f1 .\" index@\f1update access, modification, and/or change times of a file@@@\f3touch(1)\f1 .\" index@\f1access, modification, and/or change times of a file, update@@@\f3touch(1)\f1 .\" index@\f1modification, access, and/or change times of a file, update@@@\f3touch(1)\f1 .\" index@\f1change, access, and/or modification times of a file, update@@@\f3touch(1)\f1 .\" index@\f1file: create zero-length file@@@\f3touch(1)\f1 .\" index@\f1create zero-length file@@@\f3touch(1)\f1 .\" index@\f1zero-length file, create@@@\f3touch(1)\f1 .\" .\" toc@\f3touch(1)\f1:\0\0\f4touch\f1@@@update access, modification, and/or change times of file .\" .\" $Header: tput.1,v 76.1 95/08/04 17:35:11 ssa Exp $ .TA t .TH tput 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tput \- query terminfo database .SH SYNOPSIS .C tput .RC [ -T .IR type ] .I capname \|.\|.\|. .PP .C tput .RC [ -T .IR type ] .I capname .RI [ parms \|.\|.\|.\|] .PP .C tput -S .SH DESCRIPTION The .CR tput command uses the .CR terminfo database to make terminal-dependent capabilities and information available to the shell (see .IR terminfo (4)). The .CR tput command outputs a string if the attribute .RI ( "capname" ) is of type string, or an integer if the attribute is of type integer. If the attribute is of type boolean, .CR tput simply sets the exit code .RC ( 0 for TRUE, .CR 1 for FALSE), and produces no output. .SS Command-line Arguments The .CR tput command recognizes the following command-line arguments: .RS .TP 15 .CI -T type Indicates the type of terminal. Normally this flag is unnecessary because the default is taken from the environment variable .CR TERM . .TP .I capname Indicates the attribute from the .CR terminfo database. See .IR terminfo (4). In addition, the following .I capnames are supported: .RS .RS .TP 10 .C clear Echo the clear-screen sequence for the current terminal. .TP .C init Echo the initialize sequence for the current terminal. .TP .C reset Echo the sequence that will reset the current terminal. .RE .RE .TP 15 .I parms If the .I capname takes optional numeric parameters, the .IR parms will be placed in the string output by .CR tput . .TP .C -S The .I capnames are read from stdin and multiple .I capnames are allowed. Only one .I capname is allowed per line when reading from stdin. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_ALL determines the locale to use. This overrides settings of other environment variables. .PP .CR LC_MESSAGES determines the language to use for messages. .PP .CR TERM determines the terminal type if the .CR -T option is not specified. .SH EXAMPLES Echo clear-screen sequence for the current terminal. .IP .C tput clear .PP Print the number of columns for the current terminal. .IP .C tput cols .PP Print the number of columns for the 70092 terminal. .IP .C tput -T70092 cols .PP Set shell variable .CR bold to stand-out-mode sequence for current terminal. .IP .C bold=`tput smso` .PP This might be followed by a prompt: .IP .ifn \f3echo "${bold}Please type in your name: \ec"\fP .ift \f4\s+1echo "${bold}Please type in your name: \ec"\fP\s0 .PP Set exit code to indicate if current terminal is a hard copy terminal. .IP .C tput hc .ift .br .ift .ne 8 .PP Clear the screen, move the cursor to line 10, column 20 and turn on bold. .IP .C tput -S <4 An error occurred. .RE .PD .PP If the exit code is .CR 0 , a .CR \(mi1 is printed if a capability name of type integer is requested for a terminal that has no entry for that capability name in the .CR terminfo database (such as .CR "tput -Thp70092 vt" ). .SH FILES .TP 40 .C /usr/share/lib/terminfo/?/* Terminfo data base .TP .C /usr/include/curses.h Definition files .TP .C /usr/include/term.h .PD .SH SEE ALSO stty(1), untic(1M), terminfo(4). .SH STANDARDS CONFORMANCE .CR tput ": SVID2, SVID3, XPG4" .\" .\" index@\f4tput\f1 \- query the terminfo database@@@\f3tput(1)\f1 .\" index@\f1query the terminfo database@@@\f3tput(1)\f1 .\" index@\f1access the terminfo database@@@\f3tput(1)\f1 .\" index@\f1terminal capabilities, get from terminfo database@@@\f3tput(1)\f1 .\" index@\f1capabilities, terminal, get from terminfo database@@@\f3tput(1)\f1 .\" .\" toc@\f3tput(1)\f1:\0\0\f4tput\f1@@@query terminfo database\f1 .\" $Header: tr.1,v 76.1 95/08/07 10:02:39 ssa Exp $ .TA t .TH tr 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tr \- translate characters .SH SYNOPSIS .C tr .RC [ -Acs ] .I string1 .I string2 .PP .C tr .C -s .RC [ -Ac ] .I string1 .PP .C tr .C -d .RC [ -Ac ] .I string1 .PP .C tr .C -ds .RC [ -Ac ] .I string1 .I string1 .SH DESCRIPTION .C tr copies the standard input to the standard output with substitution or deletion of selected characters. Input characters from .I string1 are replaced with the corresponding characters in .I string2. If necessary, .I string1 and .I string2 can be quoted to avoid pattern matching by the shell. .PP .C tr recognizes the following command line options: .RS .TP 15 .C -A Translates on a byte-by-byte basis. When this flag is specified .C tr does not support extended characters. .TP .C -c Complements the set of characters in .IR string1, which is the set of all characters in the current character set, as defined by the current setting of .CI LC_CTYPE , except for those actually specified in the .I string1 argument. These characters are placed in the array in ascending collation sequence, as defined by the current setting of .CI LC_COLLATE . .TP .C -d Deletes all occurrences of input characters or collating elements found in the array specified in .IR string1 . .IP \0 15 If .C -c and .C -d are both specified, all characters except those specified by .I string1 are deleted. The contents of .I string2 are ignored, unless .C -s is also specified. Note, however, that the same string cannot be used for both the .C -d and the .C -s flags; when both flags are specified, both .I string1 (used for deletion) and .I string2 (used for squeezing) are required. .IP \0 15 If .C -d is not specified, each input character or collating element found in the array specified by .I string1 is replaced by the character or collating element in the same relative position specified by .IR string2 . .TP .C -s Replaces any character specified in .I string1 that occurs as a string of two or more repeating characters as a single instance of the character in .IR string2 . .IP \0 15 If the .I string2 contains a character class, the argument's array contains all of the characters in that character class. For example: .IP \0 15 .CR "tr -s " ' "[:space:]" ' .IP \0 15 In a case conversion, however, the .I string2 array contains only those characters defined as the second characters in each of the .C toupper or .C tolower character pairs, as appropriate. For example: .IP \0 15 .CR "tr -s " ' "[:upper:]" "' '" "[:lower:]" ' .RE .PP The following abbreviation conventions can be used to introduce ranges of characters, repeated characters or single-character collating elements into the strings: .RS .TP 15 .IR c1 - c2 \0or .PD 0 .TP .CI [ c1-c2 ] .sp -2v Stands for the range of collating elements .I c1 through .IR c2 , inclusive, as defined by the current setting of the .C LC_COLLATE locale category. .PD .TP .CI [: class :] \f1or .PD 0 .TP .CI [[: class :]] .sp -2v Stands for all the characters belonging to the defined character class, as defined by the current setting of .C LC_CTYPE locale category. The following character class names will be accepted when specified in .IR string1 : .CR alnum , .CR alpha , .CR blank , .CR cntrl . .CR digit , .CR graph , .CR lower , .CR print , .CR punct , .CR space , .CR upper , or .CR xdigit , Character classes are expanded in collation order. .PD .IP \0 15 When the .C -d and .C -s flags are specified together, any of the character class names are accepted in .IR string2 ; otherwise, only character class names .C lower or .C upper are accepted in .I string2 and then only if the corresponding character class .IC ( upper and .CI lower , respectively) is specified in the same relative position in .IR string1 . Such a specification is interpreted as a request for case conversion. .IP \0 15 When .C [:lower:] appears in .I string1 and .C [:upper:] appears in .IR string2 , the arrays contain the characters from the .C toupper mapping in the .C LC_CTYPE category of the current locale. When .C [:upper:] appears in .I string1 and .C [:lower:] appears in .IR string2 , the arrays contain the characters from the .C tolower mapping in the .C LC_CTYPE category of the current locale. .TP .CI [= c =] \f1or .PD 0 .TP .CR [[= c =]] .sp -2v Stands for all the characters or collating elements belonging to the same equivalence class as .IR c , as defined by the current setting of .C LC_COLLATE locale category. An equivalence class expression is allowed only in .IR string1 , or in .I string2 when it is being used by the combined .C -d and .C -s options. .PD .TP .CI [ a * n ] Stands for .I n repetitions of .IR a . If the first digit of .I n is .CR 0 , .I n is considered octal; otherwise, .I n is treated as a decimal value. A zero or missing .I n is interpreted as large enough to extend .IR string2 "-based" sequence to the length of the .IR string1 "-based" sequence. .RE .PP The escape character .C \e can be used as in the shell to remove special meaning from any character in a string. In addition, .C \e followed by 1, 2, or 3 octal digits represents the character whose .SM ASCII code is given by those digits. .PP An .SM ASCII NUL character in .I string1 or .I string2 can be represented only as an escaped character; i.e. as .CR \e000 , but is treated like other characters and translated correctly if so specified. .SM NUL characters in the input are not stripped out unless the option .ift \f4\s+1\-d "\e000"\fP\s0 .ifn \f3\-d "\e000"\fP is given. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C tr will behave as if all internationalization variables are set to "C". See .IR environ (5). .PP .C LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .PP .C LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .C LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .C NLSPATH determines the location of message catalogues for the processing of .C LC_MESSAGES. .SH RETURN VALUE .C tr exits with one of the following values: .RS .TP 5 .B \00 All input was processed successfully. .TP .B >0 An error occurred. .RE .SH EXAMPLES For the .SM ASCII character set and default collation sequence, create a list of all the words in .IR file1 , one per line in .IR file2 , where a word is taken to be a maximal string of alphabetics. Quote the strings to protect the special characters from interpretation by the shell ( 012 is the .SM ASCII code for a new-line (line feed) character: .IP .ift \f4\s+1tr -cs "[A-Z][a-z]" "[\e012*]" file2\fP\s0 .ifn \f3tr -cs "[A-Z][a-z]" "[\e012*]" file2\fP .PP Same as above, but for all character sets and collation sequences: .IP .ift \f4\s+1tr -cs "[:alpha:]" "[\\012*]" file2\fP\s0 .ifn \f3tr -cs "[:alpha:]" "[\\012*]" file2\fP .PP Translate all lower case characters in .I file1 to upper case and write the result to standard output. .RS .IP .ift \f4\s+1tr "[:lower:]" "[:upper:]" file2\fP\s0 .ifn \f3tr "[=e=]" "[e*]" file2\fP .RE .PP Translate each digit in .I file1 to a .C # (number sign), and write the result to .I file2. .IP .ift \f4\s+1tr "0-9" "[#*]" file2\fP\s0 .ifn \f3tr "0-9" "[#*]" file2\fP .RE .PP The .C * (asterisk) tells .C tr to repeat the .C # (number sign) enough times to make the second string as long as the first one. .PP .SH AUTHOR .CR tr was developed by OSF and HP. .SH SEE ALSO ed(1), sh(1), ascii(5), environ(5), lang(5), regexp(5). .SH STANDARDS CONFORMANCE .CR tr ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4tr\f1 \- translate selected characters@@@\f3tr(1)\f1 .\" index@selected characters, alter, delete, modify, substitute, translate@@@\f3tr(1)\f1 .\" index@characters, alter, delete, modify, substitute, or translate@@@\f3tr(1)\f1 .\" index@alter selected characters@@@\f3tr(1)\f1 .\" index@change selected characters@@@\f3tr(1)\f1 .\" index@delete selected characters@@@\f3tr(1)\f1 .\" index@modify selected characters@@@\f3tr(1)\f1 .\" index@replace selected characters@@@\f3tr(1)\f1 .\" index@substitute selected characters@@@\f3tr(1)\f1 .\" index@translate selected characters@@@\f3tr(1)\f1 .\" .\" toc@\f3tr(1)\f1:\0\0\f4tr\f1@@@translate characters .\" $Header: true.1,v 76.1 95/08/07 10:04:50 ssa Exp $ .TA t .TH true 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME true, false \- return exit status zero or one respectively .SH SYNOPSIS .C true .PP .C false .SH DESCRIPTION The command .C true does nothing, and returns exit code zero. The command .C false does nothing, and returns exit code one. They are typically used to construct command procedures. .SH RETURN VALUE Exit values are: .RS .TP 8 .C \00 always from .IR true . .PD 0 .TP .C \01 always from .IR false . .RE .PD .SH EXAMPLES .PP This command loop repeats without end: .nf .IP .C while true .C " do" .CI " " command .C " done" .fi .SH WARNINGS .C true is typically used in shell scripts. Some shells provide a built-in version of .C true (and .CR false ) that is more efficient than the standalone versions. .SH SEE ALSO csh(1), ksh(1), sh(1), sh-bourne(1), sh-posix(1). .SH STANDARDS CONFORMANCE .CR true ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR false ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" toc@\f3true(1)\f1:\0\0\f4true\f1, \f4false\f1@@@return zero or non-zero exit status .\" toc@\f4false\f1: do nothing and return non-zero exit status@@@see \f3true(1)\f1 .\" .\" index@\f4true\f1 \- do nothing and return zero exit status@@@\f3true(1)\f1 .\" index@\f4false\f1 \- do nothing and return non-zero exit status@@@\f3true(1)\f1 .\" index@do nothing and return zero or non-zero exit status@@@\f3true(1)\f1 .\" index@nop (do nothing) and return zero or non-zero exit status@@@\f3true(1)\f1 .\" index@exit status, do nothing and return zero or non-zero@@@\f3true(1)\f1 .\" index@status, exit, do nothing and return zero or non-zero@@@\f3true(1)\f1 .\" .\" links@true.1 false.1 .\" .\" fileset_database@true.1 USER-CMDS-MAN .\" $Header: tset.1,v 78.1 96/04/05 11:35:28 ssa Exp $ .TA t .TH tset 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tset, reset \- terminal-dependent initialization .SH SYNOPSIS .C tset .RI [ \|options\| ] .RC [ -m .RI [ \|ident\| ] .RI [ "\|test baudrate\|" ] .CR : \f2type\fP\|]\0... .RI [ \|type\| ] .PP .CR reset .SH DESCRIPTION .C tset sets up the terminal when logging in on an .SM HP-UX system. It does terminal-dependent processing, such as setting erase and kill characters, setting or resetting delays, and sending any sequences needed to properly initialize the terminal. It first determines the .I type of terminal involved, then does the necessary initializations and mode settings. The type of terminal attached to each .SM HP-UX port is specified in the .C /etc/ttytype data base. Type names for terminals can be found in the files under the .C /usr/share/lib/terminfo directory (see .IR terminfo (4)). If a port is not wired permanently to a specific terminal (not hardwired), it is given an appropriate generic identifier, such as .CR dialup . .PP .C reset performs a similar function, setting the terminal to a sensible default state. .PP In the case where no arguments are specified, .C tset simply reads the terminal type out of the environment variable .SM TERM and re-initializes the terminal. The rest of this manual entry concerns itself with mode and environment initialization, typically done once at login, and options used at initialization time to determine the terminal type and set up terminal modes. .PP When used in a startup script .RC ( .profile for Bourne shell, Korn shell, and .SM POSIX shell users, see .IR sh (1) and .IR ksh (1)), or .C .login for .IR csh (1) users) it is desirable to give information about the type of terminal that will normally be used on ports that are not hardwired. These ports are identified in .C /etc/ttytype as .C dialup or .CR plugboard , etc. To specify what terminal type you usually use on these ports, the .C -m (map) option flag is followed by the appropriate port type identifier, an optional baud rate specification, and the terminal type. (The effect is to "map" from some conditions to a terminal type; that is, to tell .CR tset that ``If I am on this kind of port, I will probably be on this kind of terminal''.) If more than one mapping is specified, the first applicable mapping prevails. A missing port type identifier matches all identifiers. A .I baudrate is specified as with .C stty (see .IR stty (1)), and is compared with the speed of the diagnostic output (which should be the control terminal). The baud rate .I test can be any combination of .CR > , .CR = , .CR < , \f3@\f1, and .CR !. \f3@\f1 is a synonym for .CR = , and .C ! inverts the sense of the test. To avoid problems with metacharacters, it is best to place the entire argument to .C -m within single quotes; users of .IR csh (1) must also put a .C \e before any .C ! used. .PP Thus, .IP .C "tset -m 'dialup>300:2622' -m 'dialup:2624' -m 'plugboard:?2623'" .PP causes the terminal type to be set to an .SM HP 2622 if the port in use is a dialup at a speed greater than 300 baud, or to an .SM HP 2624 if the port is otherwise a dialup (i.e. at 300 baud or less). If the .I type finally determined by .C tset begins with a question mark, the user is asked for verification that the type indicated is really the one desired. A null response means to use that type; otherwise, another type can be entered. Thus, in the above case, if the user is on a plugboard port, he or she will be asked whether or not he or she is actually using an HP 2623. .PP If no mapping applies and a final .I type option, not preceded by a .CR -m , is given on the command line, that type is used. Otherwise, the identifier found in the .C /etc/ttytype data base is taken to be the terminal type. The latter should always be the case for hardwired ports. .PP It is usually desirable to return the terminal type, as finally determined by .IR tset , and information about the terminal's capabilities to a shell's environment. This can be done using the .C -s option. From Bourne shell .RI ( sh (1)), the command: .IP .C eval `tset -s \f2options\fP...` .PP or using the C shell, .RI ( csh (1)): .IP .C "set noglob; eval `tset -s \f2options...\fP`" .PP These commands cause .C tset to generate as output a sequence of shell commands which place the variable .C TERM in the environment; see .IR environ (5). .PP Once the terminal type is known, .C tset engages in terminal mode setting. This normally involves sending an initialization sequence to the terminal, setting the single character erase (and optionally the full line erase or line-kill) characters, and setting special character delays. Tab and new-line expansion are turned off during transmission of the terminal initialization sequence. .PP On terminals that can backspace but not overstrike (such as a .SM CRT\s0), and when the erase character is the default erase character .RC ( # on standard systems), the erase character is changed to Back space .RC ( ^H ). .SS Options .C tset recognizes the following options: .RS .TP 8 .CI -e c Set the erase character to be the named character .IR c ; .I c defaults to .C ^H .SM (BACKSPACE). The character .I c can either be typed directly, or entered using circumflex notation used here (e.g., the circumflex notation for control-H is .CR ^H ; in Bourne shell the .C ^ character should be escaped .RC ( \e^ )). .TP .CI -k c Set the kill character to .IR c . The default .I c is .CR ^X . If .I c is not specified, the kill character remains unchanged unless the original value of the kill character is null, In which case the kill character is set to \f3@\f1. .TP .C - Report terminal type. Whatever type is decided on is reported. If no other flags are given, the only effect is to write the terminal type on the standard output. Has no effect if used with .CR -s . .TP .C -s Generate appropriate commands (depending on current .C SHELL environment variable) to set .CR TERM . .TP .C -I Suppress transmitting terminal initialization strings. .TP .C -Q Suppress printing the .C Erase set to and .C Kill set to messages. .TP .C -A Ask the user for the .C TERM type. .TP .C -S Output the strings that would be assigned to .C TERM in the environment rather than generating commands for a shell. In Bourne shell, the following is an alternate way of setting .CR TERM : .RS .IP .C "set -- `tset -S ...`" .br .C TERM=$1 .RE .TP .C -h Force a read of .CR /etc/ttytype . When .C -h is not specified, the terminal type is determined by reading the environment unless some mapping is specified. .RE .PP For compatibility with earlier versions of .CR tset , the following flags are accepted, but their use is discouraged: .RS .TP .C -r Report to the user in addition to other flags. .TP .CI -E c Set the erase character to .I c only if the terminal can backspace. .I c defaults to .CR ^H . .RE .PP In addition to capabilities described in .C terminfo (see .IR termio (7) and .IR terminfo (4)), the following boolean terminfo capabilities are understood by .C tset and .CR reset , and can be included in the terminfo database for the purpose of terminal setup: .RS .TP 8 .C UC ``Uppercase'' mode sets character mapping for terminals that support only uppercase characters. Equivalent to .CR "stty lcase" . .TP .C LC ``Lowercase'' mode permits input and output of lowercase characters. Equivalent to .CR "stty -lcase" . .TP .C EP Set ``even parity''. Equivalent to .CR "stty parenb -parodd .TP .C OP Set ``odd parity''. Equivalent to .CR "stty parenb parodd" . .TP .C NL Set ``new line'' mode. Equivalent to .CR "stty onlret" . .TP .C HD Set ``half-duplex'' mode. Equivalent to .CR "stty -echo" . .TP .C pt Set ``print tabs'' mode. Equivalent to .CR "stty tabs" . .RE .SH EXAMPLES These examples all assume the Bourne shell .RI ( sh-bourne (1)). Note that a typical use of .C tset in a .C .profile also uses the .C -e and .C -k options, and often the .C -m or .C -Q options as well. These options have been omitted here to keep the examples small. .PP Assume, for the moment, that you are on an .SM HP\|2622. This is suitable for typing by hand but not for a .C .profile unless you are .I always on a 2622. .IP .C "export TERM; TERM=`tset - 2622`" .PP Assume you have an .SM HP\|2623 at home which you dial up on, but your office terminal is hardwired and known in .CR /etc/ttytype . .IP .C "export TERM; TERM=`tset - -m dialup:2623`" .PP Suppose you are accessing the system through a switching network that can connect any system to any incoming modem line in an arbitrary combination, making it nearly impossible to key on what port you are coming in on. Your office terminal is an .SM HP\|2622, and your home terminal is an .SM HP\|2623 running at 1200 baud on dial-up switch ports. Sometimes you use someone else's terminal at work, so you want it to verify what terminal type you have at high speeds, but at 1200 baud you are always on a 2623. Note the placement of the question mark and the quotes to protect the .C > and .C ? from interpretation by the shell. .nf .IP .SM .C "export TERM; TERM=`tset - -m 'switch>1200:?2622' -m 'switch<=1200:2623'`" .fi .PP All of the above entries fall back on the terminal type specified in .C /etc/ttytype if none of the conditions hold. The following entry is appropriate if you always dial up, always at the same baud rate, on many different kinds of terminals. Your most common terminal is an .SM HP\|2622. It always asks you what kind of terminal you are on, defaulting to 2622. .IP .C "export TERM; TERM=`tset - ?2622`" .PP If the file .C /etc/ttytype is not properly installed and you want to key entirely on the baud rate, the following can be used: .IP .C export TERM; TERM=`tset - -m '>1200:2624' 2622` .SH FILES .TP 35 .PD 0 .C /etc/ttytype port-name to terminal-type mapping data base; .TP .C /usr/share/lib/terminfo/?/* terminal information data base. .PD .SH VARIABLES .TP 10 .C SHELL if .CR csh , generate .C csh commands; otherwise generate .C sh (Bourne or .SM POSIX shell) commands. .TP .C TERM the (canonical) terminal name. .SH AUTHOR .C tset was developed by the University of California, Berkeley. .SH SEE ALSO csh(1), sh(1), stty(1), ttytype(4), environ(5). .\" .\" index@\f4tset\f1 \- terminal-dependent initialization@@@\f3tset(1)\f1 .\" index@initialize terminal based on terminal type@@@\f3tset(1)\f1 .\" index@terminal, initialize based on terminal type@@@\f3tset(1)\f1 .\" .\" toc@\f3tset(1)\f1:\0\0\f4tset\f1@@@terminal-dependent initialization .\" .\" links@tset.1 reset.1 .\" .\" fileset_database@tset.1 USER-CMDS-MAN .\" $Header: tsm.1,v 72.3 93/01/14 11:42:42 ssa Exp $ .TA t .TH tsm 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tsm \- Terminal Session Manager .SH SYNOPSIS .C tsm .SH DESCRIPTION .C tsm allows a user to interact with more than one shell or application (session) from a single terminal. Each session is bound to a virtual device emulating the physical terminal. The emulation includes maintaining display state, softkeys, and terminal modes for each session. The virtual device can be manipulated like the actual terminal by using .C stty and .C ioctl (see .IR stty (1) and .IR ioctl (2)). Additionally .C tsm supports cut and paste between sessions, and provides an interface for a local lp device. Each session has its own process group .SM ID. .SS Definitions A session is .I current if it is being displayed and is the recipient of keyboard input. .PP The .I standard search path is: .nf .IP .C ./ .C $HOME .C $TSMPATH .C /usr/tsm/ .fi .PP Configuration files and such are searched for in the order indicated and defined by these paths. .SS Commands There are two methods of interacting with .CR tsm : a pull-down menu, and a command line interface. The pull-down menu (when configured) can be activated from a session by pressing the .B tsm menu hot key (default is .CR ^T ) and should be self explanatory. The command line interface can be activated by pressing the .B tsm hot key (default is .CR ^W ) in a session. Pressing a ``hot key'' twice passes the ``hot key'' character to the session instead of activating .C tsm command or menu mode. .PP Commands to .C tsm generally have single character invocation, in some cases the user is prompted for more input. The following commands can be issued from the .C tsm prompt level: .RS .TP 8 .CR 0 - 9 Pressing a number at the command prompt selects the session of the same number to become the current session. .TP .C + Select the next higher numbered session. .TP .C - Select the next lower numbered session. .TP .C l Select the last session. .TP .C ? Display a help screen describing .C tsm commands. .TP .C c Copy (cut): Three types: .RS .RS .TP 3 \(bu Text (Lines including new-lines). This is the default. Select with .C T when cut prompt is displayed. .TP \(bu String (Lines strung together with white space in place of new-lines). Select with .C T when cut prompt is displayed. .TP \(bu Block (A rectangle). Select with .C T when cut prompt is displayed. .RE .RE .IP The user is prompted for the "cut extents". The extents are defined by using arrow keys or the keys .CR u , .CR d , .CR l , and .C r to move the cursor as desired. Pressing the space bar aborts the cut operation. The selected text is placed in the .B cut buffer Trailing whitespace and character attribute information are ignored. .TP .C p Paste: the contents of the .B cut buffer is echoed to the current session as if it were typed from the keyboard. .TP .C r Run a program as a new session. The user is prompted for the program name. .TP .C s Start a new session containing a shell. .TP .C o Output the current display to a printer (screen dump). The print mechanism is specified in a file named .C .tsmprint searched for in the standard way. Character attribute information is ignored. .TP .C k Load the softkeys of the current session from a file. To load TSM defaults, specify ``file'' .CR + . To load terminal defaults, specify ``file'' .CR - . .TP .C g Same as .C k above but softkeys are loaded ``globally'' into all sessions. .TP .C x Access extended tsm commands as described in the .C tsm reference manual or on the .C tsm help screen. .TP .C q Quit .CR tsm : .C SIGHUP is sent to all processes started under .CR tsm , and .C tsm exits. .RE .SH EXTERNAL INFLUENCES In general .C tsm environment variables must be set prior to .C tsm invocation. .C TSMLP is the .IR lp (1) name of a printer that gets its output redirected to the printer port of the terminal. .PP .C TSMTPATH specifies an alternate search path for tsm files. .PP .C TSMTERM specifies an alternate terminal information file to be used by .C tsm instead of that specified by TERM. .C TSMHOTKEY specifies an alternate .C tsm hotkey for invocation ot the .C tsm command line. .SH WARNINGS Some operations are not supported on certain terminals. .SH AUTHOR .C tsm was developed by Structured Software Solutions, Inc. .SH FILES .TP 30 /usr/tsm/.tsm tsm main configuration file (default). Copy to .C $HOME for user customization. .TP .C /usr/tsm/.tsmkeys .C tsm softkey configuration file (default). Copy to .C $HOME for user customization. .TP .C /usr/tsm/term/* terminal description files .SH SEE ALSO tsm.info(1), tsm.command(1), tsm.lpadmin(3M), shl(1). .\" .\" index@\f4tsm\f1 \- Terminal Session Manager@@@\f3tsm(1)\f1 .\" index@Terminal Session Manager@@@\f3tsm(1)\f1 .\" index@Session Manager, Terminal@@@\f3tsm(1)\f1 .\" index@Manager, Terminal Session@@@\f3tsm(1)\f1 .\" .\" toc@\f3tsm(1)\f1:\0\0\f4tsm\f1@@@Terminal Session Manager .\" .\" fileset_database@tsm.1 USER-CMDS-MAN .\" $Header: tsm.command.1,v 72.3 93/01/14 11:47:32 ssa Exp $ .TA t .TH tsm.command 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tsm.command \- send commands to the Terminal Session Manager \s-1(TSM)\s0 .SH SYNOPSIS .C /usr/tsm/bin/tsm.command .I command .SH DESCRIPTION .C tsm.command is used to send a command string programmaticly to the Terminal Session Manager .SM (TSM), as if the string were typed on the .SM TSM command line. .C tsm.command fails unless it is run from inside a .SM TSM session. Actions caused by .C tsm.command affect only the instance of .SM TSM that .C tsm.command is run under. .I command can have any value that is a valid key sequence for the .SM TSM command line. The sequence should not include the "hotkey" character that normally initiates the command line mode of .SM TSM. The sequence should end at the point where .SM TSM exits command mode. If it ends prematurely .SM TSM behaves as though escape was pressed, which exits command mode, usually canceling the command. .C \er should be used to indicate a return key. If no arguments are given on the command line, the program prompts for input from the user. If a .C ^C terminates the sequence, the remainder of the sequence is accepted from the user. .SH AUTHOR .C tsm.command was developed by Structured Software Solutions, Inc. .SH SEE ALSO tsm(1). .\" .\" toc@\f3tsm.command(1)\f1:\0\0\f4tsm.command\f1@@@send commands to Terminal Session Manager .\" .\" index@\f4tsm.command\f1 \- send commands to Terminal Session Manager @@@\f3tsm.command(1)\f1 .\" index@send commands to Terminal Session Manager@@@\f3tsm.command(1)\f1 .\" index@commands to Terminal Session Manager, send@@@\f3tsm.command(1)\f1 .\" .\" fileset_database@tsm.command.1 USER-CMDS-MAN .\" $Header: tsm.info.1,v 72.4 94/07/01 13:22:33 ssa Exp $ .TA t .TH tsm.info 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tsm.info \- get Terminal Session Manager state information .SH SYNOPSIS .C /usr/tsm/bin/tsm.info .I request .SH DESCRIPTION .CR tsm.info is used to obtain information about TSM. When run from inside a TSM session it returns valid information; otherwise it fails with a nonzero error code. Information returned is written to standard output. .I request can have any of the following values: .RS .TP 25 .CR is_a_window Successful (returns zero) if executed from a TSM session, nonzero error code otherwise. .TP .CR session_number Writes the session number of the session the .CR tsm.info command is executed in. .TP .CR current_session_number Writes the session_number of the TSM session the user currently has active. .TP .CR active_session_numbers Writes the session numbers (separated by whitespace) of all active sessions (sessions not idle). .TP .CR idle_session_numbers Writes the session numbers (separated by whitespace) of all idle sessions. .TP .CR program_name Writes the program name (as assigned in .I .tsm or with .CR tsm.command ) of the session the .CR tsm.info command is executed in. .TP .CI program_name_n Writes the program name of session .CR n . .RE .SH AUTHOR .CR tsm.info was developed by Structured Software Solutions, Inc. .SH SEE ALSO tsm(1) .\" .\" toc@\f3tsm.info(1)\f1:\0\0\f4tsm.info\f1@@@get Terminal Session Manager state information .\" .\" index@\f4tsm.info\f1 \- get Terminal Session Manager state information@@@\f3tsm.info(1)\f1 .\" index@get Terminal Session Manager state information@@@\f3tsm.info(1)\f1 .\" index@Terminal Session Manager state information, get@@@\f3tsm.info(1)\f1 .\" index@Session Manager state information, get Terminal@@@\f3tsm.info(1)\f1 .\" index@Manager state information, get Terminal Session@@@\f3tsm.info(1)\f1 .\" index@state information, get Terminal Session Manager@@@\f3tsm.info(1)\f1 .\" index@information, get Terminal Session Manager state@@@\f3tsm.info(1)\f1 .\" .\" fileset_database@tsm.info.1 USER-CMDS-MAN .\" $Header: tsort.1,v 76.2 95/08/23 17:47:01 ssa Exp $ .TA t .TH tsort 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tsort \- topological sort .SH SYNOPSIS .C tsort .RI [ \|file\| ] .SH DESCRIPTION .C tsort produces on the standard output a totally ordered list of items consistent with a partial ordering of items mentioned in the input text .IR file . If no .I file is specified, the standard input is understood. .C tsort is generally used in conjunction with the .C lorder command to sort the objects to be installed in a library by .C ar (see .IR lorder (1) and .IR ar (1)). .PP The input consists of pairs of text items (nonempty strings) separated by blanks. Pairs of different items indicate ordering. Pairs of identical items indicate presence, but not ordering. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the locale for the interpretation of text as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C tsort behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS .TP .C Odd data There is an odd number of fields in the input file. .SH WARNINGS Libraries and object files cannot be .CR tsort ed directly. .PP .C tsort uses a quadratic algorithm that is not considered worth fixing given its typical use of ordering a library archive file. .SH SEE ALSO lorder(1). .SH STANDARDS CONFORMANCE .CR tsort ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" toc@\f3tsort(1)\f1:\0\0\f4tsort\f1@@@topological sort .\" .\" index@\f4tsort\f1 \- topological sort@@@\f3tsort(1)\f1 .\" index@\f1topological sort@@@\f3tsort(1)\f1 .\" index@\f1sort, topological@@@\f3tsort(1)\f1 .\" .\" $Header: tty.1,v 76.1 95/08/07 10:06:18 ssa Exp $ .TA t .TH tty 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tty, pty \- get the name of the terminal .SH SYNOPSIS .C tty .RC [ -s ] .PP .C pty .RC [ -s ] .SH DESCRIPTION .C tty and .C pty print the path name of the user's terminal. The .C -s option inhibits printing of the terminal path name and any diagnostics, providing a means to test only the exit code. .SH RETURN VALUE Exit status codes for .C tty are: .RS .TP 8 .B 2 Invalid options were specified, .PD 0 .TP .B 1 The standard input is not a terminal or pseudo-terminal, .TP .B 0 The standard input is a terminal or pseudo-terminal. .PD .RE .PP Exit status codes for .C pty are: .RS .TP 8 .PD 0 .B 2 Invalid options were specified, .TP .B 1 The standard input is not a pseudo-terminal, .TP .B 0 The standard input is a pseudo-terminal. .PD .RE .SH DIAGNOSTICS .TP 10 .C "not a tty" standard input is not a terminal or pseudo-terminal for .CR tty . .TP .C "not a pty" standard input is not a pseudo-terminal for .CR pty . .SH AUTHOR .C tty was developed by AT&T. .C pty was developed by HP. .SH STANDARDS CONFORMANCE .CR tty ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" toc@\f3tty(1)\f1:\0\0\f4tty\f1, \f4pty\f1@@@get the name of the terminal .\" toc@\f4pty\f1: get the name of the pseudo-terminal@@@see \f3tty(1)\f1 .\" .\" index@\f4tty\f1 \- get the name of the user's terminal or pseudo-terminal@@@\f3tty(1)\f1 .\" index@\f4pty\f1 \- get the name of the user's pseudo-terminal@@@\f3tty(1)\f1 .\" index@get name of the user's terminal or pseudo-terminal@@@\f3tty(1)\f1 .\" index@name of the user's terminal or pseudo-terminal, get@@@\f3tty(1)\f1 .\" index@user's terminal or pseudo-terminal, get name of@@@\f3tty(1)\f1 .\" index@terminal or pseudo-terminal, get name of user's@@@\f3tty(1)\f1 .\" index@pseudo-terminal, get name of user's terminal or@@@\f3tty(1)\f1 .\" .\" links@tty.1 pty.1 .\" .\" fileset_database@tty.1 USER-CMDS-MAN .\" $Header: ttytype.1,v 72.4 93/01/14 11:19:37 ssa Exp $ .TA t .TH ttytype 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ttytype \- terminal identification program .SH SYNOPSIS .C ttytype .RC [ -apsv ] .RC [ -t .IR type\| ] .SH DESCRIPTION .C ttytype automatically identifies the current terminal type by sending an identification request sequence to the terminal. This method works for local, modem, and remote terminal connections, as well as for the .C hpterm and .C xterm terminal emulators. .PP Once the terminal has been identified, .C ttytype prints the terminal's type to the standard output (see .IR terminfo (4)). This string is usually used as the value for the .C TERM environment variable. .PP If .C ttytype is unable to determine the correct terminal type, it prompts the user for the correct terminal identification string. .SS Options .C ttytype recognizes the following options: .RS .TP 12 .C -a Causes .C ttytype to return an .SM ID of "unknown" instead of prompting for the terminal type if auto-identification fails. If this option is not present, .C ttytype interactively prompts the user for the terminal type if it is unable to determine the correct type automatically. .TP .C -p Causes .C ttytype to prompt for the terminal type before it sends the terminal identification request sequence. If the user responds with only a carriage return, .C ttytype proceeds with the automatic terminal identification process. Any other response is taken as the correct terminal type. Note that the .C LINES and .C COLUMNS variables are not set if the user manually enters a terminal type. .IP The .C -p option is normally used only for terminals that do not behave well when presented with .CR ttytype 's terminal identification request sequence. It gives the user a chance to respond with the correct terminal type before any escape sequences are sent that could have an adverse effect on the terminal. .IP The .C -a option can be used in conjunction with the .C -p option. The .C -a option only inhibits interactive prompting after .C ttytype has failed to identify the terminal by other means. .TP .C -s Tells .C ttytype to print a series of shell commands to set the .CR TERM , .CR LINES , and .C COLUMNS environment variables to appropriate values. In addition, the variable .C ERASE is set to the two-character sequence representing the appropriate erase character for the terminal (\c .SM DEL for .SM ANSI terminals, backspace for all others). This two-character sequence can then be used as an argument to .C stty or .C tset (see .IR stty (1) and .IR tset (1)). .IP The .C SHELL environment variable is consulted to see which shell syntax to use for setting the environment variables. This output is normally used with a command of the form: .RS .IP .C eval `ttytype -s` .RE .TP .CI -t \0type .C ttytype normally attempts identification of Wyse, .SM ANSI and .SM HP terminals. The .C -t .I type argument can be used to restrict the inquiry to that required for terminals of the specified type. The accepted types are .CR ansi , .CR hp , and .CR wyse . Multiple .C -t options can be specified. .TP .C -v Enable verbose messages to standard error. .SH EXAMPLES .C ttytype is most commonly used as part of the login sequence. The following shell script fragment can be used during login shell initialization: .nf .IP .ift .ft 4 # # If TERM is not set, see if our port is listed in /etc/ttytype. # If /etc/ttytype doesn't have information for our port, run # ttytype(1) to try to determine the type of terminal we have. # # To have ttytype(1) prompt for the terminal type before trying # to automatically identify the terminal, add the "-p" option # to the "ttytype -s" command below. # if [ -z "$TERM" -o "$TERM" = network ]; then unset TERM eval `tset -s -Q` if [ -z "$TERM" -o "$TERM" = unknown ]; then eval `ttytype -s` tset -Q -e ${ERASE:-\e^h} $TERM fi fi .ift .ft .fi .SH NOTES Use of the .C -s option is highly recommended because many terminals support variable-size displays. This option provides the only means for automatically configuring the user environment in such a manner that applications can handle these terminals correctly. Note that .C LINES and .C COLUMNS are not set if the .C -p option is used and the user manually enters a terminal type. .PP The following steps are performed in the order indicated when identifying a terminal: .RS .TP 3 1. .C ttytype tries the Wyse 30/50/60 id request sequence. .TP 2. .C ttytype tries the standard .SM ANSI id request sequence. If a response is received, it is converted to a string according to an internal table. .TP 3. .C ttytype tries the .SM HP id request sequence. .TP 4. If none of the above steps succeed, .C ttytype prompts interactively for the correct terminal type unless the .C -a option has been given. .RE .PP .C ttytype may skip one or more of the first three steps, depending on the presence of .C -t options. .PP The .SM HP ID\c -request sequence can switch some .SM ANSI terminals into an unexpected operating mode. Recovery from such a condition sometimes requires cycling power on the terminal. To avoid this problem, .C ttytype always sends the .SM HP identification sequence last. .SH WARNINGS The terminal identification sequences sent by .C ttytype can cause unexpected behavior on terminals other than the Wyse 30/50/60, standard .SM ANSI or .SM HP terminals. If you have such terminals in your configuration, use the .C -t or .C -p options to prevent .C ttytype from sending sequences that cause unexpected behavior. .SH AUTHOR .C ttytype was developed by HP. .SH SEE ALSO csh(1), ksh(1), sh(1), stty(1), ttytype(4), environ(5). .\" .\" index@\f4ttytype\f1 \- terminal identification program@@@\f3ttytype(1)\f1 .\" index@identify terminal type@@@\f3ttytype(1)\f1 .\" index@terminal, identify type@@@\f3ttytype(1)\f1 .\" .\" toc@\f3ttytype(1)\f1:\0\0\f4ttytype\f1@@@terminal identification program .\" .\" fileset_database@ttytype.1 USER-CMDS-MAN .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: ul.1,v 72.4 94/05/24 16:21:07 ssa Exp $ .TA u .TH ul 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ul \- do underlining .SH SYNOPSIS .C ul .RC [ -t .IR terminal\| ] .RC [ -i ] .RI [ \|name \ ...\|] .SH DESCRIPTION .C ul reads the named files (or standard input if none are given) and translates occurrences of underscores to the sequence which indicates underlining for the terminal in use, as specified by the environment variable .CR TERM . The .C -t option overrides the terminal type specified in the environment. The .IR terminfo (4) file corresponding to .C TERM is read to determine the appropriate sequences for underlining. If the terminal is incapable of underlining, but is capable of a standout mode, the standout mode is used instead. If the terminal can overstrike, or handles underlining automatically, .C ul degenerates to .CR cat . If the terminal cannot underline, underlining is ignored. .PP The .C -i option causes .C ul to indicate underlining onto by a separate line containing appropriate dashes .CR - ; this is useful when you want to look at the underlining present in an .C nroff output stream on a .SM CRT terminal. .SH WARNINGS .C nroff usually outputs a series of backspaces and underlines intermixed with the text to indicate underlining. No attempt is made to optimize the backward motion. .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported with the exception that multi-byte-character file names are not supported. .SH FILES .TP 35 .C /usr/share/lib/terminfo/?/* terminal capability files .SH AUTHOR .C ul was developed by the University of California, Berkeley. .SH SEE ALSO col(1), man(1), nroff(1). .\" .\" toc@\f3ul(1)\f1:\0\0\f4ul\f1@@@do underlining .\" .\" index@\f4ul\f1 \- do underlining on terminal@@@\f3ul(1)\f1 .\" index@convert underscores to underlining on terminal@@@\f3ul(1)\f1 .\" index@underscores, convert to underlining on terminal@@@\f3ul(1)\f1 .\" index@underlining on terminal, convert underscores to@@@\f3ul(1)\f1 .\" index@terminal, convert underscores to underlining on@@@\f3ul(1)\f1 .\" .\" fileset_database@ul.1 USER-CMDS-MAN .\" $Header: umask.1,v 78.1 96/04/05 11:35:51 ssa Exp $ .TA u .TH umask 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME umask \- set or display the file mode creation mask .SH SYNOPSIS .SS \f2Set Mask: .CI "umask \&" mask .SS \f2Display Mask: .CR "umask \&" \|[ -S ]\| .SH DESCRIPTION The .CR umask command sets the value of the file mode creation mask or displays the current one. The mask affects the initial value of the file mode (permission) bits for subsequently created files. .SS Setting the File Mode Creation Mask The .CI "umask " mask command sets a new file mode creation mask for the current shell execution environment. .IR mask can be a symbolic or numeric (obsolescent) value. .PP A symbolic mask provides a flexible way of modifying the mask permission bits individually or as a group. A numeric mask specifies all the permission bits at one time. .PP When a mask is specified, no output is written to standard output. .PP .B "Symbolic Mask Value" .PP A symbolic .IR mask replaces or modifies the current file mode creation mask. It is specified as specified as a comma-separated list of operations in the following format. Whitespace is not permitted. .IP .RI [ who ][ operator ][ permissions\c .RI ][ , ...] .PP The fields can have the following values: .RS .TP 15 .IR who One or more of the following letters: .RS .RS .TP .PD 0 .CR u Modify permissions for user (owner). .TP .CR g Modify permissions for group. .TP .CR o Modify permissions for others. .PD .RE .RE .IP Or: .RS .RS .TP .CR a Modify permissions for all .RC ( a = .CR ugo ). .RE .RE .TP .IR operator One of the following symbols: .RS .RS .TP .PD 0 .CR + Add .IR permissions to the existing mask for .IR who . .TP .CR - Delete .IR permissions from the existing mask for .IR who . .TP .CR = Replace the existing mask for .IR who with .IR permissions . .PD .RE .RE .TP .IR permissions One or more of the following letters: .RS .RS .TP .PD0 .CR r The read permission. .TP .CR w The write permission. .TP .CR x The execute/search permission. .PD .RE .RE .RE .PP If one or two of the fields are omitted, the following table applies: .PP .TS center tab(@) ; lf3 lf3 | lf3 lf3 lf2 lf1 | lf1 lf1 . Format Entered@Effect@Input@Equals _ .\"--------------- who@Delete current permissions for \f2who@T{ .CR g T}@T{ .CR g= T} .\"--------------- operator@No action@T{ .CR - T}@(none) .\"--------------- permissions@T{ .IC "\f1Equal to: " a\^+ \^permissions T}@T{ .CR rw T}@T{ .CR a+rw T} .\"--------------- T{ .IC who\^ = T}@Delete current permissions for \f2who@T{ .CR u= T}@T{ .CR u= T} .\"--------------- T{ .IC who\^ + T}@No action@T{ .CR u+ T}@(none) .\"--------------- T{ .IC who\^ - T}@No action@T{ .CR u- T}@(none) .\"--------------- who\^permissions@T{ .IC "\f1Equal to: \f2who\^" = \^permissions T}@T{ .CR ux T}@T{ .CR u=x T} .\"--------------- operator\^permissions@T{ .IC "\f1Equal to: " a \^operator\^permissions T}@T{ .CR -rw T}@T{ .CR a-rw T} .\"--------------- .TE .PP .ne13v .B "Numeric Mask Value (Obsolescent)" .PP A numeric .IR mask replaces the current file mode creation mask. It is specified as an unsigned octal integer, constructed from the logical .SM OR (sum) of the following mode bits (leading zeros can be omitted): .RS .nf .IP .CR "0400 " "( " "a=rwx,u-r" ")\0\0Read by owner" .CR "0200 " "( " "a=rwx,u-w" ")\0\0Write by owner" .CR "0100 " "( " "a=rwx,u-x" ")\0\0Execute (search in directory) by owner" .CR "0040 " "( " "a=rwx,g-r" ")\0\0Read by group" .CR "0020 " "( " "a=rwx,g-w" ")\0\0Write by group" .CR "0010 " "( " "a=rwx,g-x" ")\0\0Execute/search by group" .CR "0004 " "( " "a=rwx,o-r" ")\0\0Read by others" .CR "0002 " "( " "a=rwx,o-w" ")\0\0Write by others" .CR "0001 " "( " "a=rwx,o-x" ")\0\0Execute/search by others" .fi .RE .SS Displaying the Current Mask Value To display the current file mode creation mask value, use one of the commands: .RS .TP 15 .CR "umask -S" Print the current file mode creation mask in a symbolic format: .RS .IP .CR u= [ r ][ w ][\c .CR x ] ,g= [ r ][\c .CR w ][ x ] ,o= [\c .CR r ][ w ][ x ] .RE .IP The characters .CR r (read), .CR w (write), and .CR x (execute/search) represent the bits that are clear in the mask for .CR u (user/owner), .CR g (group), and .CR o (other). All other bits are set. .TP .CR umask Print the current file mode creation mask as an octal value. .IP The zero bits in the numeric value correspond to the displayed .CR r , .CR w , and .CR x permission characters in the symbolic value. The one bits in the numeric value correspond to the missing permission characters in the symbolic value. .IP Depending on implementation, the display consists of one to four octal digits; the first digit is always zero (see .SM DEPENDENCIES\s0). The rightmost three digits (leading zeros implied as needed) represent the bits that are set or clear in the mask. .RE .PP Both forms produce output that can be used as the .IR mask argument to set the mask in a subsequent .CR umask command. .SS General Operation .PP When a new file is created (see .IR creat (2)), each bit that is set in the file mode creation mask causes the corresponding permission bit in the the file mode to be cleared (disabled). Conversely, bits that are clear in the mask allow the corresponding file mode bits to be enabled in newly created files. .PP For example, the mask .CR "u=rwx,g=rx,o=rx" .RC ( "022" ) disables group and other write permissions. As a result, files normally created with a file mode shown by the .CR "ls -l" command as .CR -rwxrwxrwx .RC ( 777 ) become mode .CR -rwxr-xr-x .RC ( 755 ); while files created with file mode .CR -rw-rw-rw- .RC ( 666 ) become mode .CR -rw-r--r-- .RC ( 644 ). .PP Note that the file creation mode mask does not affect the set-user-id, set-group-id, or "sticky" bits. .PP The file creation mode mask is also used by the .CR chmod command (see .IR chmod (1)). .PP Since .CR umask affects the current shell execution environment, it is generally provided as a shell regular built-in (see .SM DEPENDENCIES\s0. .PP If .CR umask is called in a subshell or separate utility execution environment, such as one of the following: .IP .C "(umask 002)" .br .CR "nohup umask \&" ... .br .CR "find . -exec umask \&" ... .PP it does not affect the file mode creation mask of the calling environment. .PP The default mask is .CR u=rwx,g=rwx,o=rwx .RC ( 000 ). .br .ne7v .SH RETURN VALUE .CR umask exits with one of the following values: .RS .TP .CR \00 The file mode creation mask was successfully changed or no .IR mask operand was supplied. .TP .CR >0 An error occurred. .RE .br .ne9v .SH EXAMPLES In these examples, each line show an alternate way of accomplishing the same task. .PP Set the .CR umask value to produce read and write permissions for the file's owner and read permissions for all others .RC ( "ls -l" displays .CR -rw-r--r-- on newly created files): .IP .CR "umask u=rwx,g=rx,o=rx \&" "symbolic mode" .br .CR "umask a=rx,u+w \&" "symbolic mode" .br .CR "umask 022 \&" "numeric mode" .PP Set the .CR umask value to produce read, and write permissions for the file's owner, read-only for others users in the same group, and no access to others .RC ( -rw-r----- ): .IP .CR "umask a-rwx,u+rw,g+r \&" "symbolic mode" .br .CR "umask 137 \&" "numeric mode" .PP Set the .CR umask value to deny read, write, and execute permissions to everyone .RC ( ---------- ): .IP .CR "umask a= \&" "symbolic mode" .br .CR "umask 777 \&" "numeric mode" .PP Add the write permission to the current mask for everyone (there is no equivalent numeric mode): .IP .CR "umask a+w \&" "symbolic mode" .SH WARNINGS .PP If you set a mask that prevents read or write access for the user (owner), many programs, such as editors, that create temporary files will fail because they cannot access the file data. .SH DEPENDENCIES The .CR umask command is implemented both as a separate executable file .RC ( /usr/bin/umask ) and as built-in shell commands. .SS POSIX Shell and Separate File All features are supported (see .IR sh-posix (1). The numeric mask display uses a minimum of two digits. .SS Korn Shell The .CR -S option is not supported in the Korn shell built-in command (see .IR ksh (1). The numeric mask display uses a minimum of two digits. .SS C Shell The .CR -S option and symbolic mask values are not supported in the C shell built-in command (see .IR csh (1). The numeric mask display uses a minimum of one digit. .SS Bourne Shell The .CR -S option and symbolic mask values are not supported in the Bourne shell built-in command (see .IR sh-bourne (1). The numeric mask display always consists of four digits. .SH SEE ALSO chmod(1), csh(1), ksh(1), sh-posix(1), sh(1), chmod(2), creat(2), umask(2). .SH STANDARDS CONFORMANCE .CR umask ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4umask\f1 \- set access permissions mode mask for file-creation@@@\f3umask(1)\f1 .\" index@set access permissions mode mask for file-creation@@@\f3umask(1)\f1 .\" index@access permissions mode mask for file-creation, set@@@\f3umask(1)\f1 .\" index@permissions mode mask for file-creation, set access@@@\f3umask(1)\f1 .\" index@mode mask for file-creation, set access permissions@@@\f3umask(1)\f1 .\" index@mask for file-creation, set access permissions mode@@@\f3umask(1)\f1 .\" index@file creation, set access permissions mode mask for@@@\f3umask(1)\f1 .\" .\" toc@\f3umask(1)\f1:\0\0\f4umask\f1@@@set file-creation mode mask .\" .\" fileset_database@umask.1 UX-CORE-MAN .\" $Header: umodem.1,v 72.6 94/12/16 09:55:17 ssa Exp $ .TA u .TH umodem 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME umodem \- XMODEM-protocol file transfer program .SH SYNOPSIS .CR umodem .RI [ options ] .IR files \0... .br .C umodem -c .SH DESCRIPTION .CR umodem is a file transfer program that incorporates the well-known XMODEM protocol used on CP/M systems and on the HP 110 portable computer. .SS Options .CR umodem recognizes the following options and command-line arguments: .RS .TP 12 .CR -1 (one) Employ TERM II FTP 1. .TP .CR -3 Enable TERM FTP 3 (CP/M UG). .TP .CR -7 Enable 7-bit transfer mask. .TP .CR -a Turn on ARPA Net flag. .TP .CR -c Enter command mode. .TP .CR -d Do not delete .CR umodem.log before starting. .TP .CR -l (ell) Turn on entry logging. .TP .CR -m Allow overwriting of files. .TP .CR -p Print all messages. .TP .CR -r [ t \(or b ] Receive file. Specify .CR t for text, or .CR b for binary. .TP .CR -s [ t \(or b ] Send file. Specify .CR t for text, or .CR b for binary. .TP .CR -y Display file status only. .TP .I files Name of file or files to be transferred. .SH EXAMPLES Receive a text file: .IP .CI "umodem -rt7 " file .PP Receive a binary file: .IP .CI "umodem -rb " file .PP Send a text file: .IP .CI "umodem -st7 " file .PP Send a binary file: .IP .CI "umodem -sb " file .SH AUTHOR .CR umodem is in the public domain. .SH SEE ALSO cu(1), kermit(1), uucp(1). .\" .\" index@\f4umodem\f1 \- \s-1XMODEM\s+1-protocol file transfer program@@@\f3umodem(1)\f1 .\" index@\s-1XMODEM\s+1-protocol file transfer program@@@\f3umodem(1)\f1 .\" index@file transfer program, \s-1XMODEM\s+1-protocol@@@\f3umodem(1)\f1 .\" index@transfer files using \s-1XMODEM\s+1-protocol@@@\f3umodem(1)\f1 .\" .\" toc@\f3umodem(1)\f1:\0\0\f4umodem\f1@@@\s-1XMODEM\s+1-protocol file transfer program .\" $Header: sh-posix.1,v 76.4 95/11/02 14:15:41 ssa Exp $ .TA s .TH sh-posix 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sh, rsh \- standard and restricted POSIX.2-conformant command shells .SH SYNOPSIS .CR sh .RC [{ \- \(or + }\c .CR aefhikmnprstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [ \-c .IR string ] .IR arg ]...\& .PP .CR rsh .RC [{ \- \(or + }\c .CR aefhikmnprstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [ \-c .IR string ] .RI [ arg ]...\& .SS Remarks This shell is intended to conform to the shell specification of the POSIX.2 .I Shell and Utility standards. Check any standards conformance documents shipped with your system for information on the conformance of this shell to any other standards. .SS List of Subheadings in DESCRIPTION .\" .SS lines under DESCRIPTION (commands are vi/ex) .\" Extract header lines; copy to eof ":g/\.S[SH]/co$: .\" Delete extraneous leading and trailing headings .\" Delete .SS ":.,$s/....//" .\" Form into columns ":.,$!pr -3 -t -s@" .\" Replace pr tabs with blanks ":.,$s/[[:space:]]/ /g" .\" Move into place below. .TS tab(@); l l l . Shell Invocation@Tilde Substitution@Environment Options@Command Substitution@Functions rsh Restrictions@Parameter Substitution@Jobs Definitions@Blank Interpretation@Signals Commands@File Name Generation@Execution Simple Commands@Quoting@Command Reentry Compound Commands@Arithmetic Evaluation@Command Line Editing Special Commands@Prompting@emacs Editing Mode Comments@Conditional Expressions@vi Editing Mode Aliasing@Input/Output .TE .SH DESCRIPTION .CR sh is a command programming language that executes commands read from a terminal or a file. .PP .CR rsh is a restricted version of .CR sh . See the "rsh Restrictions" subsection below. .SS Shell Invocation If the shell is invoked by an .CI exec * () system call and the first character of argument zero (shell parameter .CR 0 ) is dash .RC ( \- ), the shell is assumed to be a login shell and commands are read first from .CR /etc/profile , then from either .CR .profile in the current directory or .CR $HOME/.profile if either file exists, and finally from the file named by performing parameter substitution on the value of the environment parameter .CR ENV , if the file exists. If the .CR \-s option is not present and an .I arg is, a path search is performed on the first .I arg to determine the name of the script to execute. When running .CR sh with .IR arg , the script .I arg must have read permission and any .CR setuid and .CR setgid settings will be ignored. Commands are read as described below. .PP Shell output, except for the output of some of the commands listed in the "Special Commands" subsection, is written to standard error (file descriptor 2). .SS Options The following options are interpreted by the shell when it is invoked. .TP 15 .CI \-c \0string Read commands from .IR string . .TP .CR \-i If .CR \-i is present or if the shell input and output are attached to a terminal (as reported by .CR tty() ), the shell is interactive. In this case .CR SIGTERM is ignored (so that .CR "kill 0" does not kill an interactive shell) and .CR SIGINT is caught and ignored (so that .CR wait is interruptible). In all cases, .CR SIGQUIT is ignored by the shell. See .IR signal (5). .TP .CR \-r The shell is a restricted shell. .TP .CR \-s If .CR \-s is present or if no arguments remain, commands are read from the standard input. .PP The remaining options and arguments are described under the .CR set command in the "Special Commands" subsection. .SS rsh Restrictions .CR rsh is used to set up login names and execution environments where capabilities are more controlled than those of the standard shell. The actions of .CR rsh are identical to those of .CR sh , except that the following are forbidden: .RS .TP 3 .PD 0 \(bu Changing directory (see the .CR cd special command and .IR cd (1)) .TP \(bu Setting the value of .CR SHELL , .CR ENV , or .CR PATH .TP \(bu Specifying path or command names containing .CR / .TP \(bu Redirecting output .RC ( > , .CR >| , .CR <> , and .CR >> ) .PD .RE .PP The restrictions above are enforced after the .CR .profile and .CR ENV files are interpreted. .PP When a command to be executed is found to be a shell procedure, .CR rsh invokes .CR sh to execute it. Thus, the end-user is provided with shell procedures accessible to the full power of the standard shell, while being restricted to a limited menu of commands. This scheme assumes that the end-user does not have write and execute permissions in the same directory. .PP These rules effectively give the writer of the .CR .profile file complete control over user actions, by performing guaranteed set-up actions and leaving the user in an appropriate directory (probably not the login directory). .PP The system administrator often sets up a directory of commands (usually .CR /usr/rbin ) that can be safely invoked by .CR rsh . HP-UX systems provide a restricted editor .CR red (see .IR ed (1)), suitable for restricted users. .SS Definitions .TP 20 .B metacharacter One of the following characters: .IP .CR "; & ( ) | < >" \0newline\0space\0tab .TP .B blank A tab or a space. .TP .B identifier A sequence of letters, digits, or underscores starting with a letter or underscore. Identifiers are used as names for .BR functions and .BR "named parameters" . .TP .B word A sequence of .B characters separated by one or more nonquoted .BR metacharacters . .TP .BR command A sequence of characters in the syntax of the shell language. The shell reads each command and carries out the desired action, either directly or by invoking separate utilities. .TP .B "special command" A command that is carried out by the shell without creating a separate process. Except for documented side effects, most special commands can be implemented as separate utilities. .TP .CR # Comment delimiter. A word beginning with .CR # and all following characters up to a newline are ignored. .TP .B parameter An .BR identifier , a decimal number, or one of the characters .CR ! , .CR # , .CR $ , .CR * , .CR \- , .CR ? , .CR @ , and .CR _ . See the "Parameter Substitution" subsection. .TP .B "named parameter" A .B parameter that can be assigned a value. See the "Parameter Substitution" subsection. .TP .B variable A .BR parameter . .TP .B "environment variable" A .BR parameter that is known outside the local shell, usually by means of the .CR export special command. .SS Commands A command can be a simple command that executes an executable file, a special command that executes within the shell, or a compound command that provides flow of control for groups of simple, special, and compound commands. .SS Simple Commands A simple command is a sequence of blank-separated words that may be preceded by a parameter assignment list. (See the "Environment" subsection). The first word specifies the name of the command to be executed. Except as specified below, the remaining words are passed as arguments to the invoked command. The command name is passed as argument .CR 0 (see .IR exec (2)). The .I value of a simple-command is its exit status if it terminates normally, or .CI 128+ errorstatus if it terminates abnormally (see .IR signal (5) for a list of .I errorstatus values). .PP A .B pipeline is a sequence of one or more commands separated by a bar .RC ( | ) and optionally preceded by an exclamation mark .RC ( ! ). The standard output of each command but the last is connected by a pipe (see .IR pipe (2)) to the standard input of the next command. Each command is run as a separate process; the shell waits for the last command to terminate. If .CR !\& does not precede the pipeline, the exit status of the pipeline is the exit status of the last command in the pipeline. Otherwise, the exit status of the pipeline is the logical negation of the exit status of the last command in the pipeline. .PP A .I list is a sequence of one or more pipelines separated by .CR ; , .CR & , .CR && , or .CR || , and optionally terminated by .CR ; , .CR & , or .CR |& . .RS .TP .CR ;\& Causes sequential execution of the preceding pipeline. An arbitrary number of newlines can appear in a .I list, instead of semicolons, to delimit commands. .TP .CR & Causes asynchronous execution of the preceding pipeline (that is, the shell does not wait for that pipeline to finish). .TP .CR |& Causes asynchronous execution of the preceding command or pipeline with a two-way pipe established to the parent shell. The standard input and output of the spawned command can be written to and read from by the parent shell using the .CR \-p option of the special commands .CR read and .CR print . .TP .CR && Causes the .I list following it to be executed only if the preceding pipeline returns a zero value. .TP .CR || Causes the .I list following it to be executed only if the preceding pipeline returns a nonzero value. .RE .PP Of these five symbols, .CR ; , .CR & , and .CR |& have equal precedence, which is lower than that of .CR && and .CR || . The symbols .CR && and .CR || also have equal precedence. .SS Compound Commands Unless otherwise stated, the value returned by a compound command is that of the last simple command executed in the compound command. The .CR ;\& segment separator can be replaced by one or more newlines. .PP The following keywords are recognized only as the first word of a command and when not quoted: .nf .RS .IP .C "! } elif for then" .C "[[ case else function time" .C "]] do esac if until" .C "{ done fi select while" .fi .RE .PP A compound command is one of the following. .PP .ne 3v .CR case \f2\0word\c .CR \0in \0[\|[ ; ]\0[ ( ]\c .IC \0pattern\0\f1[ | \0pattern\f1]... ) \0list\0\c .CR ;; ]...\0 ;\0esac .IP Execute the .I list associated with the first .I pattern that matches .IR word . The form of the patterns is identical to that used for file name generation (see the "File Name Generation" subsection). The .CR ;;\& case terminator cannot be replaced by newlines. .PP .ne 3v .CI for \0identifier\f1\0[ in \0word\f1\0...]\0\c .CR ;\0do \0\f2list\0 ;\0done .IP Set .I identifier to each .I word in sequence and execute the .CR do .IR list . If .CR in .IR word .RI ...\& is omitted, set .I identifier to each set positional parameter instead. See the "Parameter Substitution" subsection. Execution ends when there are no more positional parameters or words in the list. .PP .ne 4v .CI function \0identifier\0 { \0list\0 ;\0} .br .IC identifier \0()\0{ \0list\0 ;\0} .IP Define a function named by .IR identifier . A function is called by executing its identifier as a command. The body of the function is the .I list of commands between .CR { and .CR } . See the "Functions" subsection. .PP .ne 3v .CI if \0list\0 ;\0then \0list\0 ; \0\f1[\c .CI elif \0list\0 ;\0then \0list\0 ; \f1]...\&\0[\c .CI else \0list\0 ; \f1]\0 fi .IP Execute the .CR if .I list and, if its exit status is zero, execute the first .CR then .IR list . Otherwise, execute the .CR elif .I list (if any) and, if its exit status is zero, execute the next .CR then .IR list . Failing that, execute the .CR else .I list (if any). If no .CR else .I list or .CR then .I list is executed, .CR if returns a zero exit status. .PP .ne 3v .CI select \0identifier\0\f1[ in \0word\f1\0...\&]\0 ;\0do \0list\0\c .CI ;\0done .IP Print the set of .IR word s on standard error (file descriptor 2), each preceded by a number. If .CI in .IR word .RI ...\& is omitted, print the positional parameters instead (see the "Parameter Substitution" subsection). Print the .CR PS3 prompt and read a line from standard input into the parameter .CR REPLY . If this line consists of the number of one of the listed .IR word s, set .I identifier to the corresponding .IR word , execute .IR list , and repeat the .CR PS3 prompt. If the line is empty, print the selection list again, and repeat the .CR PS3 prompt. Otherwise, set .I identifier to null, execute .IR list , and repeat the .CR PS3 prompt. The select loop repeats until a .CR break special command or end-of-file is encountered. .PP .ne 3v .CI time \0pipeline .IP Execute the .I pipeline and print the elapsed time, the user time, and the system time on standard error. See also .IR time (1). .PP .ne 3v .CI "until\0" list "\0;\0do\0" list "\0;\0done" .IP Execute the .CR until .IR list . If the exit status of the last command in the list is nonzero, execute the .CR do .IR list and execute the .CR until .IR list again. When the exit status of the last command in the .CR until .I list is zero, terminate the loop. If no commands in the .CR do .I list are executed, .CR until returns a zero exit status. .PP .ne 3v .CI "while\0" list "\0;\0do\0" list "\0;\0done" .IP Execute the .CR while .IR list . If the exit status of the last command in the list is zero, execute the .CR do .IR list and execute the .CR while .IR list again. When the exit status of the last command in the .CR while .I list is nonzero, terminate the loop. If no commands in the .CR do .I list are executed, .CR while returns a nonzero exit status. .PP .ne 3v .CI ( "\0list\0" ) .IP Execute .I list in a separate environment. If two adjacent open parentheses are needed for nesting, a space must be inserted between them to avoid arithmetic evaluation. .PP .ne 3v .CI { "\0list\0" ";\0}" .IP Execute .IR list , but not in a separate environment. Note that .CR { is a keyword and requires a trailing blank to be recognized. .PP .ne 3v .CI [[ "\0expression\0" ]] .IP Evaluate .I expression and return a zero exit status when .I expression is true. See the "Conditional Expressions" subsection for a description of .IR expression . Note that .CR [[ and .CR ]] are keywords and require blanks between them and .IR expression . .SS Special Commands Special commands are simple commands that are executed in the shell process. They permit input/output redirection. Unless otherwise indicated, file descriptor 1 (standard output) is the default output location and the exit status, when there are no syntax errors, is zero. .PP Commands that are marked with \(dg or \(dg\(dg are treated specially in the following ways: .RS .TP 3 .PD 0 1. Variable assignment lists preceding the command remain in effect when the command completes. .TP 2. I/O redirections are processed after variable assignments. .TP 3. Errors cause a script that contains them to abort. .TP 4. Words following a command preceded by \(dg\(dg that are in the format of a variable assignment are expanded with the same rules as a variable assignment. This means that tilde substitution is performed after the .CR = sign and word-splitting and file-name generation are not performed. .PD .RE .PP .ne 3v \(dg .CR : \0[\f2arg\f1]...\& .IP (colon)\0 Only expand parameters. A zero exit status is returned. .PP .ne 3v \(dg .CI . \0file\f1\0[\f2arg\f1]...\& .IP (period)\0 Read and execute commands from .I file and return. The commands are executed in the current shell environment. The search path specified by .CR PATH is used to find the directory containing .IR file . If any arguments .I arg are given, they become the positional parameters. Otherwise, the positional parameters are unchanged. The exit status is the exit status of the last command executed. .PP .ne 3v \(dg\(dg .CR alias \0[ \-tx ]\0[\f2name\f1[\c .CI = value\f1]\|]...\& .IP With .IC name = value specified, define .I name as an alias and assign it the value .IR value . A trailing space in .I value causes the next word to be checked for alias substitution. .IP With .IC name = value omitted, print the list of aliases in the form .IC name = value on standard output. .IP With .I name specified without .CI = value\f1, print the specified alias. .IP With .CR \-t , set tracked aliases. The value of a tracked alias is the full path name corresponding to the given .IR name . The value of a tracked alias becomes undefined when the value of .CR PATH is reset, but the alias remains tracked. With .IC name = value omitted, print the list of tracked aliases in the form .IC name = pathname on standard output. .IP With .CR \-x , set exported aliases. An exported alias is defined across subshell environments. With .IC name = value omitted, print the list of exported aliases in the form .IC name = value on standard output. .IP Alias returns true unless a .I name is given for which no alias has been defined. .PP .ne 3v .CR bg \0[\f2job\f1]...\& .IP Put the specified .I jobs into the background. The current job is put in the background if .I job is unspecified. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v \(dg .CR break \0[\f2n\f1] .IP Exit from the enclosing .CR for , .CR select , .CR until , or .CR while loop, if any. If .I n is specified, exit from .I n levels. .PP .ne 4v .CR cd \0[ \-L \(or \-P ]\0[\f2arg\f1] .br .CI cd \0old\0new .IP In the first form, change the current working directory .RC ( PWD ) to .IR arg . If .I arg is .CR \- , the directory is changed to the previous directory .RC ( OLDPWD ). .IP With .CR \-L (default), preserve logical naming when treating symbolic links. .CR "cd \-L ..\&" moves the current directory one path component closer to the root directory. .IP With .CR \-P , preserve the physical path when treating symbolic links. .CR "cd \-P ..\&" changes the working directory to the actual parent directory of the current directory. .IP The shell parameter .CR HOME is the default .IR arg . The parameter .CR PWD is set to the current directory. .IP The shell parameter .CR CDPATH defines the search path for the directory containing .IR arg . Alternative directory names are separated by a colon .RC ( : ). If .CR CDPATH is null or undefined, the default value is the current directory. Note that the current directory is specified by a null path name, which can appear immediately after the equal sign or between the colon delimiters anywhere else in the path list. If .I arg begins with a .CR / , the search path is not used. Otherwise, each directory in the path is searched for .IR arg . See also .IR cd (1). .IP The second form of .CR cd substitutes the string .I new for the string .I old in the current directory name, .CR PWD , and tries to change to this new directory. .PP .ne 3v .CR command \0[\f2arg\f1]...\& .IP Treat .I arg as a command, but disable function lookup on .IR arg . See .IR command (1) for usage and description. .PP .ne 3v \(dg .CR continue \0[\f2n\f1] .IP Resume the next iteration of the enclosing .CR for , .CR select , .CR until , or .CR while loop. If .I n is specified, resume at the .IR n th enclosing loop. .PP .ne 3v .CR echo \0[\f2arg\f1]...\& .IP Print .I arg on standard output. See .IR echo (1) for usage and description. See also the .CR print special command. .PP .ne 3v \(dg .CR eval \0[\f2arg\f1]...\& .IP Read the arguments as input to the shell and execute the resulting commands. Allows parameter substitution for keywords and characters that would otherwise be unrecognized in the resulting commands. .PP .ne 3v \(dg .CR exec \0[\f2arg\f1]...\& .IP Parameter assignments remain in effect after the command completes. If .I arg is given, execute the command specified by the arguments in place of this shell without creating a new process. Input/output arguments may appear and affect the current process. If no arguments are given, modify file descriptors as prescribed by the input/output redirection list. In this case, any file descriptor numbers greater than 2 that are opened with this mechanism are closed when another program is invoked. .PP .ne 3v \(dg .CR exit \0[\f2n\f1] .IP Exit from the shell with the exit status specified by .IR n . If .I n is omitted, the exit status is that of the last command executed. An end-of-file also causes the shell to exit, except when a shell has the .CR ignoreeof option set. (See the .CR set special command.) .PP .ne 4v \(dg\(dg .CR export \0[\f2name\f1[ = \f2value\f1]\|]...\& .br \(dg\(dg .CR export\0\-p .IP Mark the given variable .IR name s for automatic export to the environment of subsequently executed commands. Optionally, assign values to the variables. .IP With .CR \-p , write the names and values of all exported variables to standard output, in a format with the proper use of quoting, so that it is suitable for re-input to the shell as commands that achieve the same exporting results. .PP .ne 6v .CR fc \0[ \-r ]\0[ \-e \0\f2ename\f1]\0[\f2first\f1\0[\f2last\f1]\|] .br .CR fc\0\-l \0[ \-nr ]\0[\f2first\f1\0[\f2last\f1]\|] .br .CR fc\0\-s \0[\f2old\f1 = \f2new\f1]\0[\f2first] .br .CR fc\0\-e\0\- \0[\f2old\f1 = \f2new\f1]\0[\f2command\f1] .IP List, or edit and reexecute, commands previously entered to an interactive shell. A range of commands from .I first to .I last is selected from the last .CR HISTSIZE commands typed at the terminal. The arguments .I first and .I last can be specified as a number or string. A given string is used to locate the most recent command. A negative number is used to offset the current command number. .IP With .CR \-l , list the commands on standard output. Without .CR \-l , invoke the editor program .I ename on a file containing these keyboard commands. If .I ename is not supplied, the value of the parameter .CR FCEDIT (default .CR /usr/bin/ed ) is used as the editor. Once editing has ended, the commands (if any) are executed. If .I last is omitted, only the command specified by .I first is used. If .I first is not specified, the default is the previous command for editing and \(mi16 for listing. .IP With .CR \-r , reverse the order of the commands. .IP With .CR \-n , suppress command numbers when listing. .IP With .CR \-s , reexecute the command without invoking an editor. .IP The .IC old = new argument replaces the first occurrence of string .IC old in the command to be reexecuted by the string .IR new . .PP .ne 3v .CR fg \0[\f2job\f1]...\& .IP Bring each .I job into the foreground in the order specified. If no .I job is specified, bring the current job into the foreground. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v .CR getopts \0\f2optstring\0name\f1\0[\f2arg\f1]...\& .IP Parse the argument list, or the positional parameters if no arguments, for valid options. On each execution, return the next option in .IR name . See .IR getopts (1) for usage and description. .IP An option begins with a .CR + or a .CR \- . An argument not beginning with .CR + or .CR \- , or the argument .CR \-\- , ends the options. .I optstring contains the letters that .CR getopts recognizes. If a letter is followed by a .CR : , that option is expected to have an argument. The options can be separated from the argument by blanks. .IP For an option specified as .CI \- letter\f1, .I name is set to .IR letter . For an option specified as .CI + letter\f1, .I name is set to .CI + letter\f1. The index of the next .I arg is stored in .CR OPTIND . The option argument, if any, is stored in .CR OPTARG . If no option argument is found, or the option found does not take an argument, .CR OPTARG is unset. .IP A leading .CR :\& in .I optstring causes .CR getopts to store the letter of an invalid option in .CR OPTARG , and to set .I name to .CR ?\& for an unknown option and to .CR :\& when a required option argument is missing. Otherwise, .CR getopts prints an error message. The exit status is nonzero when there are no more options. .PP .ne 4v .CR hash \0[\f2utility\f1]...\& .br .CR hash\0\-r .IP Affect the way the current shell environment remembers the locations of utilities. With .IR utility , add utility locations to a list of remembered locations. With no arguments, print the contents of the list. With .CR \-r , forget all previously remembered utility locations. .PP .ne 3v .CR jobs \0[ \-lnp ]\0[\f2job\f1]...\& .IP List information about each given job, or all active jobs if .I job is not specified. With .CR \-l , list process IDs in addition to the normal information. With .CR \-n , display only jobs that have stopped or exited since last notified. With .CR \-p , list only the process group. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 5v .CR kill \0[ \-s \0\f2signal\f1]\0\f2process\f1\0...\& .br .CR kill\0\-l .br .CR kill \0[ \- \f2signal\f1]\0\f2process\f1\0...\& .IP Send either signal 15 .RC ( SIGTERM , terminate) or the specified .I signal to the specified jobs or processes. See .IR kill (1) for usage and description. .IP With .CR \-l , list the signal names and numbers. .PP .ne 4v .CI let \0arg\f1\0... .br .CI (( \0arg\f1\0... )) .IP Evaluate each .I arg as a separate arithmetic expression. See the "Arithmetic Evaluation" subsection for a description of arithmetic expression evaluation. The exit status is 0 if the value of the last expression is nonzero, and 1 otherwise. .PP .ne 3v \(dg .CR newgrp \0[ \- ]\0[\f2group\f1] .IP Replace the current shell with a new one having .I group as the user's group. The default group is the user's login group. With .CR \- , the user's .CR .profile and .CR $ENV files are also executed. See .IR newgrp (1) for usage and description. Equivalent to .CI "exec\0newgrp" "\0arg\0\f1...." .PP .ne 3v .CR print \0[ \-nprRsu [\f2n\f1]\|]\0[\f2arg\f1]...\& .IP The shell output mechanism. With no options or with option .CR \- or .CR \-\- , print the arguments on standard output as described in .IR echo (1). See also .IR printf (1). .IP With .CR \-n , do not add a newline character to the output. .IP With .CR \-p , write the arguments onto the pipe of the process spawned with .CR |& instead of standard output. .IP With .CR \-R or .CR \-r (raw mode), ignore the escape conventions of .CR echo . With .CR \-R , print all subsequent arguments and options other than .CR \-n . .IP With .CR \-s , write the arguments into the history file instead of to standard output. .IP With .CR \-u , specify a one-digit file descriptor unit number .I n on which the output will be placed. The default is .CR 1 (standard output). .PP .ne 3v .CR pwd \0[ \-L \(or \-P ] .IP Print the name of the current working directory (equivalent to .CR "print\0\-r\0\-\0$PWD" ). With .CR \-L (the default), preserve the logical meaning of the current directory. With .CR \-P , preserve the physical meaning of the current directory if it is a symbolic link. See also the .CR cd special command, .IR cd (1), .IR ln (1), and .IR pwd (1). .PP .ne 3v .CR read \0[ \-prsu [\f2n\f1]\|]\0[\f2name\f1 ? \f2prompt\f1]\0[\f2name\f1]...\& .IP The shell input mechanism. Read one line (by default, from standard input) and break it up into words using the characters in .CR IFS as separators. The first word is assigned to the first .IR name , the second word to the second .IR name , and so on; the remaining words are assigned to the last .IR name . See also .IR read (1). The return code is .CR 0 , unless an end-of-file is encountered. .IP With .CR \-p , take the input line from the input pipe of a process spawned by the shell using .CR |& . An end-of-file with .CR \-p causes cleanup for this process so that another process can be spawned. .IP With .CR \-r (raw mode), a .CR \e at the end of a line does not signify line continuation. .IP With .CR \-s , save the input as a command in the history file. .IP With .CR \-u , specify a one-digit file descriptor unit to read from. The file descriptor can be opened with the .CR exec special command. The default value of .I n is .CR 0 (standard input). If .IR name is omitted, .CR REPLY is used as the default .IR name . .IP If the first argument contains a .CR ? , the remainder of the argument is used as a .I prompt when the shell is interactive. .IP If the given file descriptor is open for writing and is a terminal device, the prompt is placed on that unit. Otherwise, the prompt is issued on file descriptor 2 (standard error). .PP .ne 4v \(dg\(dg .CR readonly \0[\f2name\f1[ = \f2value\f1]\|]...\& .br \(dg\(dg .CR readonly\0\-p .IP Mark the given .IR name s read only. These names cannot be changed by subsequent assignment. .IP With .CR \-p , write the names and values of all read-only variables to standard output in a format with the proper use of quoting so that it is suitable for re-input to the shell as commands that achieve the same attribute-setting results. .PP .ne 3v \(dg .CR return \0[\f2n\f1] .IP Cause a shell function to return to the invoking script with the return status specified by .IR n . If .I n is omitted, the return status is that of the last command executed. Only the low 8 bits of .I n (decimal 0 to 255) are passed back to the caller. If .CR return is invoked while not in a function or a .CR .\& script (see the .CR .\& special command), it has the same effect as an .CR exit command. .PP .ne 3v .CR set .RC [{ \- \(or + }\c .CR abCefhkmnopstuvx ] .RC [{ \- \(or + } o .IR option ]...\& .RC [{ \- \(or + } A .IR name ]\0[ arg ]...\& .IP Set .RC ( \- ) or clear .RC ( + ) execution options or perform array assignments .RC ( \-A ,\ +A ). All options except .CR \-A and .CR +A can be supplied in a shell invocation (see the SYNOPSIS section and the "Shell Invocation" subsection). .IP Using .CR + instead of .CR \- before an option causes the option to be turned off. These options can also be used when invoking the shell. The current list of set single-letter options is contained in the shell variable .CR \- . It can be examined with the command .CR "echo $-" . .IP The .CR \- and .CR + options can be intermixed in the same command, except that there can be only one .CR \-A or .CR +A option. .IP Unless .CR \-A or .CR +A is specified, the remaining .I arg arguments are assigned consecutively to the positional parameters .CR 1 , .CR 2 ,\0.... .IP The .CR set command with neither arguments nor options displays the names and values of all shell parameters on standard output. See also .IR env (1). .IP The options are defined as follows. .RS .TP .CR \-A Array assignment. Unset the variable .I name and assign values sequentially from the list .IR arg . With .CR \+A , do not unset the variable .I name first. .TP .CR \-a Automatically export subsequently defined parameters. .TP .CR \-b Cause the shell to notify the user asynchronously of background jobs as they are completed. When the shell notifies the user that a job has been completed, it can remove the job's process ID from the list of those known in the current shell execution environment. .TP .CR \-C Prevent redirection .CR > from truncating existing files. Requires .CR >| to truncate a file when turned on. .TP .CR \-e Execute the .CR ERR trap, if set, and exit .I if a command has a nonzero exit status, and is not part of the compound list following a .CR if , .CR until , or .CR while keyword, and is not part of an AND or OR list, and is not a pipeline preceded by the .CR !\& reserved word. This mode is disabled while reading profiles. .TP .CR \-f Disable file name generation. .TP .CR \-h Specify that each command whose name is an .I identifier becomes a tracked alias when first encountered. .TP .CR \-k Place all parameter assignment arguments (not just those that precede the command name) into the environment for a command. .TP .CR \-m Run background jobs in a separate process group and print a line upon completion. The exit status of background jobs is reported in a completion message. This option is turned on automatically for interactive shells. .TP .CR \-n Read commands and check them for syntax errors, but do not execute them. The .CR \-n option is ignored for interactive shells. .TP .ne 5v .CR \-o Set an .I option argument from the following list. Repeat the .CR \-o option to specify additional .I option arguments. .RS .TP 15 .PD 0 .CR allexport Same as .CR \-a . .TP .CR bgnice Run all background jobs at a lower priority. .TP .CR errexit Same as .CR \-e . .TP .CR emacs Use a .CR emacs -style inline editor for command entry. .TP .CR gmacs Use a .CR gmacs -style inline editor for command entry. .TP .CR ignoreeof Do not exit from the shell on end-of-file .RI ( eof as defined by .CR stty ; default is .CR ^D ). The .CR exit special command must be used. .TP .CR keyword Same as .CR \-k . .TP .CR markdirs Append a trailing .CR / to all directory names resulting from file name generation. .TP .CR monitor Same as .CR \-m . .TP .CR noclobber Same as .CR \-C . .TP .CR noexec Same as .CR \-n . .TP .CR noglob Same as .CR \-f . .TP .CR nolog Do not save function definitions in history file. .TP .CR notify Same as .CR \-b . .TP .CR nounset Same as .CR \-u . .TP .CR privileged Same as .CR \-p . .TP .CR verbose Same as .CR \-v . .TP .CR trackall Same as .CR \-h . .TP .CR vi Use a .CR vi -style inline editor for command entry. .TP .CR viraw Process each character as it is typed in .CR vi mode. .TP .CR xtrace Same as .CR \-x . .PD .RE .TP .CR \-p Disable processing of the .CR $HOME/.profile file and uses the file .CR /etc/suid_profile instead of the .CR ENV file. This mode is on whenever the effective user ID (group ID) is not equal to the real user ID (group ID). Turning this off causes the effective user ID and group ID to be set to the real user ID and group ID. .TP .CR \-s Sort the positional parameters. .TP .CR \-t Exit after reading and executing one command. .TP .CR \-u Treat unset parameters as an error when substituting. .TP .CR \-v Print shell input lines as they are read. .TP .CR \-x Print commands and their arguments as they are executed. .TP .CR \- Turn off .CR \-x and .CR \-v options and stop examining arguments for options. .TP .CR \-\- Do not change any of the options; useful in setting parameter .CR 1 to a value beginning with .CR \- . If no arguments follow this option, the positional parameters are unset. .RE .PP .ne 3v \(dg .CR shift "\0[\f2n\f1]" .IP Rename the positional parameters from .IC n +1 \f1\0...\& to .CR 1 \0.... The default value of .I n is .CR 1 . .I n can be any arithmetic expression that evaluates to a nonnegative number less than or equal to .CR $# . .PP .ne 3v .CR test \0[\f2expr\f1] .IP Evaluate conditional expression .IR expr . See .IR test (1) for usage and description. The arithmetic comparison operators are not restricted to integers. They allow any arithmetic expression. The following additional primitive expressions are allowed: .RS .TP 20 .PD 0 .CI \-L \0file True if .I file is a symbolic link. .TP .CI \-e \0file True if .I file exists. .TP .IC file1\0 \-nt \0file2 True if .I file1 is newer than .IR file2 . .TP .IC file1\0 \-ot \0file2 True if .I file1 is older than .IR file2 . .TP .IC file1\0 \-ef \0file2 True if .I file1 has the same device and i-node number as .IR file2 . .PD .RE .PP .ne 3v \(dg .CR times .IP Print the accumulated user and system times for the shell and for processes run from the shell. .PP .ne 3v \(dg .CR trap \0[\f2arg\f1]\0[\f2sig\f1]...\& .IP Set .I arg as a command that is read and executed when the shell receives a .IR sig signal. (Note that .I arg is scanned once when the trap is set and once when the trap is taken.) Each .I sig can be given as the number or name of a signal. Letter case is ignored. For example, .CR 3 , .CR QUIT , .CR quit , and .CR SIGQUIT all specify the same signal. Use .CR "kill \-l" to get a list of signals. .IP Trap commands are executed in signal number order. Any attempt to set a trap on a signal that was ignored upon entering the current shell is ineffective. .IP If .I arg is .CR \- (or if .I arg is omitted and the first .I sig is numeric), reset all traps for each .I sig to their original values. .IP If .I arg is the null string .RC ( '' or \&\c .C """""\c" ), each .I sig is ignored by the shell and by the commands it invokes. .IP If .I sig is .CR DEBUG , then .I arg is executed after each command. If .I sig is .CR ERR , .I arg is executed whenever a command has a nonzero exit code. If .I sig is .CR 0 or .CR EXIT and the .CR trap statement is executed inside the body of a function, the command .I arg is executed after the function completes. If .I sig is .CR 0 or .CR EXIT for a .CR trap set outside any function, the command .I arg is executed on exit from the shell. .IP With no arguments, print a list of commands associated with each signal name. .PP .ne 4v \(dg\(dg .CR typeset \0[{ \- \(or + }\c .CR LRZfilrtux [\f2n\f1]\|]\0[\f2name\f1[ = \f2value\f1]\|]... .br \(dg\(dg .IC name = value .RC [\f2name = \f2value\f1]...\& .IP Assign types and a value to a local named parameter .IR name . See also the .CR export special command. Parameter assignments remain in effect after the command completes. When invoked inside a function, create a new instance of the parameter .IR name . The parameter value and type are restored when the function completes. .IP The following list of attributes can be specified. Use .CR \+ instead of .CR \- to turn the options off. .RS .TP .CR \-L Left justify and remove leading blanks from .IR value . If .I n is nonzero, it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. When .I name is assigned, the value is filled on the right with blanks or truncated, if necessary, to fit into the field. Leading zeros are removed if the .CR \-Z option is also set. The .CR \-R option is turned off. Flagged as .CI leftjust \0n\f1. .TP .CR \-R Right justify and fill with leading blanks. If .I n is nonzero, it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. The field is left-filled with blanks or truncated from the end if the parameter is reassigned. The .CR \-L option is turned off. Flagged as .CI rightjust \0n\f1. .TP .CR \-Z Right justify and fill with leading zeros if the first nonblank character is a digit and the .CR \-L option has not been set. If .I n is nonzero it defines the width of the field; otherwise, it is determined by the width of the value of first assignment. Flagged as .CI zerofill \0n\f1 plus the flag for .CR \-L or .CR \-R . .TP .CR \-f Cause .I name to refer to function names rather than parameter names. No assignments can be made to the .I name declared with the .CR typeset statement. The only other valid options are .CR \-t (which turns on execution tracing for this function) and .CR \-x (which allows the function to remain in effect across shell procedures executed in the same process environment). Flagged as .CR function . .TP .CR \-i Parameter is an integer. This makes arithmetic faster. If .I n is nonzero it defines the output arithmetic base; otherwise, the first assignment determines the output base. Flagged as .CR integer \0[ base \0\f2n\f1]. .TP .CR \-l Convert all uppercase characters to lowercase. The uppercase .CR \-u option is turned off. Flagged as .CR lowercase . .TP .CR \-r Mark any given .I name as "read only". The name cannot be changed by subsequent assignment. Flagged as .CR readonly . .TP .CR \-t Tag the named parameters. Tags are user-definable and have no special meaning to the shell. Flagged as .CR tagged . .TP .CR \-u Convert all lowercase characters to uppercase characters. The lowercase .CR \-l option is turned off. Flagged as .CR uppercase . .TP .CR \-x Mark any given .I name for automatic export to the environment of subsequently executed commands. Flagged as .CR export . .RE .IP .CR typeset alone displays a list of parameter names, prefixed by any flags specified above. .IP .CR "typeset \-" displays the parameter names followed by their values. Specify one or more of the option letters to restrict the list. Some options are incompatible with others. .IP .CR "typeset +" displays the parameter names alone. Specify one or more of the option letters to restrict the list. Some options are incompatible with others. .PP .ne 3v .CR ulimit \0[ \-HSacdfnst ]\0[\f2limit\f1] .IP Set or display a resource limit. The limit for a specified resource is set when .IR limit is specified. The value of .IR limit can be a number in the unit specified with each resource, or the keyword .CR unlimited . .IP The .CR \-H and .CR \-S flags specify whether the hard limit or the soft limit is set for the given resource. A hard limit cannot be increased once it is set. A soft limit can be increased up to the hard limit. If neither .CR \-H nor .CR \-S is specified, the limit applies to both. The current resource limit is printed when .IR limit is omitted. In this case, the soft limit is printed unless .CR \-H is specified. When more than one resource is specified, the limit name and unit are printed before the value. .IP If no option is given, .CR \-f is assumed. .RS .TP .PD 0 .CR \-a List all of the current resource limits. .TP .CR \-c The number of 512-byte blocks in the size of core dumps. .TP .CR \-d The number of kilobytes in the size of the data area. .TP .CR \-f The number of 512-byte blocks in files written by child processes (files of any size can be read). .TP .CR \-n The number of file descriptors. .TP .CR \-s The number of kilobytes in the size of the stack area. .TP .CR \-t The number of seconds to be used by each process. .PD .RE .PP .ne 3v .CR umask \0[ \-S ]\0[\f2mask\f1] .IP Set the user file-creation mask .IR mask . .I mask can be either an octal number or a symbolic value as described in .IR umask (1). A symbolic value shows permissions that are unmasked. An octal value shows permissions that are masked off. .IP Without .I mask , print the current value of the mask. With .CR \-S , print the value in symbolic format. Without .CR \-S , print the value as an octal number. The output from either form can be used as the .I mask of a subsequent invocation of .CR umask . .PP .ne 4v .CI unalias \0name\f1\0...\& .br .CR unalias\0\-a .IP Remove each .IR name from the alias list. With .CR \-a , remove all .CR alias definitions from the current shell execution environment. .PP .ne 3v .CR unset \0[ \-fv ]\0\f2name\f1\0...\& .IP Remove the named shell parameters from the parameter list. Their values and attributes are erased. Read-only variables cannot be unset. With .CR \-f , .IR name s refer to function names. With .CR \-v , .IR name s refer to variable names. Unsetting .CR _ , .CR ERRNO , .CR LINENO , .CR MAILCHECK , .CR OPTARG , .CR OPTIND , .CR RANDOM , .CR SECONDS , and .CR TMOUT removes their special meaning, even if they are subsequently assigned to. .PP .ne 3v \(dg .CR wait \0[\f2job\f1] .IP Wait for the specified .I job to terminate or stop, and report its status. This status becomes the return code for the .CR wait command. Without .I job , wait for all currently active child processes to terminate or stop. The termination status returned is that of the last process. See the "Jobs" subsection for a description of the format of .IR job . .PP .ne 3v .CR whence \0[ \-pv ]\0\f2name\f1\0...\& .IP For each .IR name , indicate how it would be interpreted if used as a command name. With .CR \-v , produce a more verbose report. With .CR \-p do a path search for .IR name , disregarding any use as an alias, a function, or a reserved word. .SS Comments A .I word beginning with .CR # causes that word and all the following characters up to a newline to be ignored. .SS Aliasing The first word of each command is replaced by the text of an .CR alias , if an .CR alias for this word has been defined. An .CR alias name consists of any number of characters excluding metacharacters, quoting characters, file expansion characters, parameter and command substitution characters, and =. The replacement string can contain any valid shell script, including the metacharacters listed above. The first word of each command in the replaced text, other than any that are in the process of being replaced, will be tested for additional aliases. If the last character of the alias value is a .IR blank , the word following the alias is also checked for alias substitution. Aliases can be used to redefine special commands, but cannot be used to redefine the keywords listed in the "Compound Commands" subsection. Aliases can be created, listed, and exported with the .CR alias command and can be removed with the .CR unalias command. Exported aliases remain in effect for subshells but must be reinitialized for separate invocations of the shell (see the "Shell Invocation" subsection). .PP Aliasing is performed when scripts are read, not while they are executed. Therefore, for it to take effect, an .CR alias must be executed before the command referring to the alias is read. .PP Aliases are frequently used as a shorthand for full path names. An option to the aliasing facility allows the value of the alias to be automatically set to the full path name of the corresponding command. These aliases are called .I tracked aliases. The value of a .I tracked alias is defined the first time the identifier is read and becomes undefined each time the .CR PATH variable is reset. These aliases remain .I tracked so that the next reference will redefine the value. Several tracked aliases are compiled into the shell. The .CR \-h option of the .CR set command converts each command name that is an .I identifier into a tracked alias. .PP The following .I exported aliases are compiled into the shell but can be unset or redefined: .nf .IP .C autoload='typeset \-fu' .C command='command ' .C functions='typeset \-f' .C history='fc \-l' .C integer='typeset \-i' .C local=typeset .C nohup='nohup ' .C r='fc \-e \-' .C stop='kill \-STOP' .C suspend='kill \-STOP $$' .C type='whence \-v' .SS Tilde Substitution After alias substitution is performed, each word is checked to see if it begins with an unquoted tilde .RC ( ~ ). If it does, the word up to a .CR / is checked to see if it matches a user name in the .CR /etc/passwd file. If a match is found, the .CR ~ and the matched login name are replaced by the login directory of the matched user. If no match is found, the original text is left unchanged. A .CR ~ alone or before a .CR / is replaced by the value of the .CR HOME parameter. A .CR ~ followed by a .CR + or .CR \- is replaced by the value of the parameter .CR PWD and .CR OLDPWD , respectively. In addition, tilde substitution is attempted when the value of a parameter assignment begins with a .CR ~ . .SS Command Substitution The standard output from a command enclosed in parenthesis preceded by a dollar sign .RC ( $( ...\& ) ) or a pair of grave accents .RC ( ` ...\& ` ) can be used as part or all of a word; trailing newlines are removed. In the second (archaic) form, the string between the accents is processed for special quoting characters before the command is executed. See the "Quoting" subsection. The command substitution .CR "$(cat file)" can be replaced by the equivalent but faster .CR $(\0\c ". .TP .CR PS3 Selection prompt string used within a .CR select loop. If unset, it defaults to "\c .CR #?\0\c ". .TP .CR PS4 Execution trace string that precedes each line of an execution trace. See the .CR "set \-x" special command. If unset, it defaults to "\c .CR +\0\c ". .TP .CR SHELL The path name of the shell is kept in the environment. When invoked, the shell is restricted if the value of this variable contains an .CR r in the base name. .TP .CR TMOUT If set to a value greater than zero, the shell will terminate if a command is not entered within the prescribed number of seconds after issuing the .CR PS1 prompt. (Note that the shell can be compiled with a maximum bound for this value which cannot be exceeded.) .TP .CR VISUAL Invokes the corresponding option when the value of this variable ends in .CR emacs , .CR gmacs , or .CR vi . See the .CR "set \-o" special command. .PP The shell gives default values to .CR IFS , .CR MAILCHECK , .CR PATH , .CR PS1 , .CR PS2 , and .CR TMOUT . On the other hand, .CR MAIL , .CR ENV , .CR HOME , and .CR SHELL are never set automatically by the shell (although .CR HOME , .CR MAIL , and .CR SHELL are set by .CR login ; see .IR login (1)). .SS Blank Interpretation After parameter and command substitution, the results of substitution are scanned for field separator characters (defined in .CR IFS ), and split into distinct arguments when such characters are found. .CR sh retains explicit null arguments (\c .C """""" or .CR '' ) but removes implicit null arguments (those resulting from parameters that have null values). .SS File Name Generation Following substitution, each command .I word is processed as a pattern for file name expansion unless expansion has been disabled with the .CR "set \-f" special command. The form of the patterns is the Pattern Matching Notation defined in .IR regexp (5). The word is replaced with sorted file names matching the pattern. If no file name is found that matches the pattern, the word is left unchanged. .PP In addition to the notation described in .IR regexp (5), .CR sh recognizes composite patterns made up of one or more pattern lists separated from each other with a .CR | . Composite patterns can be formed with one or more of the following: .RS .TP 18 .PD 0 .CI ?( pattern-list ) Matches any one of the given patterns. .TP .CI *( pattern-list ) Matches zero or more occurrences of the given patterns. .TP .CI +( pattern-list ) Matches one or more occurrences of the given patterns. .TP .CI @( pattern-list ) Matches exactly one of the given patterns. .TP .CI !( pattern-list ) Matches anything, except one of the given patterns. .PD .RE .SS Quoting Each of the metacharacters (see the "Definitions" subsection) has a special meaning to the shell and terminates a word unless quoted. A character may be .B quoted (that is, made to stand for itself) by preceding it with a backslash .RC ( \e ). The pair .CR \e newline is ignored; the current and following lines are concatenated. .PP All characters enclosed between a pair of apostrophes .RC ( ' ...\& ' ) are quoted. An apostrophe cannot appear within apostrophes. .PP Parameter and command substitution occurs inside quotation marks (\c .C """\c" \&...\&\c .C """\c" ). .CR \e quotes the characters .CR \e , .CR ` , .C """\c" , and .CR $ . .PP Inside grave accent marks .RC ( ` ...\& ` ), .CR \e quotes the characters .CR \e , .CR ` , and .CR $ . If the grave accents occur within quotation marks, .CR \e also quotes the character .C """\c" \&. .PP The meanings of .CR $* and .CR $@ are identical when not quoted or when used as a parameter assignment value or as a file name. However, when used as a command argument, .C """\c" .CR $*\c .C """" is equivalent to .C """\c" .CI $1 d $2 d\f1...\&\c .C """\c" , whereas .C """\c" .CR $@\c .C """" is equivalent to .C """\c" .CR $1\c .C """\c" .IR d\c .C """\c" .CR $2\c .C """\c" .IR d ...\& (where .I d is the first character of .CR IFS ), .PP The special meaning of keywords or aliases can be removed by quoting any character of the name. The recognition of function names or special command names cannot be altered by quoting them. .SS Arithmetic Evaluation Integer arithmetic is provided with the special command .CR let . Evaluations are performed using long integer arithmetic. Constants take the form .IC base # n or .IR n , where .I base is a decimal number between two and thirty-six representing the arithmetic base and .I n is a number in that base. If .IC base # is omitted, base 10 is used. .PP An arithmetic expression uses the same syntax, precedence, and associativity of expression as the C language. All the integral operators, other than .CR ++ , .CR \-\- , .CR ?: , and .CR , are supported. Variables can be referenced by name within an arithmetic expression without using the parameter substitution syntax. When a variable is referenced, its value is evaluated as an arithmetic expression. .PP A variable can be typed as an integer with the .CR \-i option of the .CR typeset special command, as in .CI typeset\0-i \f1[\f2base\f1]\f2\0name\f1. Arithmetic evaluation is performed on the value of each assignment to a variable with the .CR \-i attribute. If you do not specify an arithmetic base, the first assignment to the variable determines the arithmetic base. This base is used when parameter substitution occurs. .PP Since many of the arithmetic operators require quoting, an alternative form of the .CR let command is provided. For any command beginning with .CR (( , all characters until the matching .CR )) are treated as a quoted expression. More precisely, .CR (( ...\& )) is equivalent to .CR let .C """\c" .RC ...\c .C """\c" .RC . .SS Prompting When used interactively, the shell prompts with the value of .CR PS1 before reading a command. Whenever a newline is received and further input is needed to complete a command, the secondary prompt (the value of .CR PS2 ) is issued. .SS Conditional Expressions A .B "conditional expression" is used with the .CR [[ compound command to test attributes of files and to compare strings. Word splitting and file name generation are not performed on the words between .CR [[ and .CR ]] . Each expression can be constructed from one or more of the following unary or binary expressions: .RS .TP 20 .PD 0 .CI \-a \0file True, if .I file exists. .TP .CI \-b \0file True, if .I file exists and is a block special file. .TP .CI \-c \0file True, if .I file exists and is a character special file. .TP .CI \-d \0file True, if .I file exists and is a directory. .TP .CI \-e \0file True, if .I file exists. .TP .CI \-f \0file True, if .I file exists and is an ordinary file. .TP .CI \-g \0file True, if .I file exists and has its setgid bit set. .TP .CI \-h \0file True, if .I file exists and is a symbolic link. .TP .CI \-k \0file True, if .I file exists and has its sticky bit set. .TP .CI \-n \0string True, if length of .I string is nonzero. .TP .CI \-o \0option True, if the set option named .I option is on. .TP .CI \-p \0file True, if .I file exists and is a fifo special file or a pipe. .TP .CI \-r \0file True, if .I file exists and is readable by current process. .TP .CI \-s \0file True, if .I file exists and has a size greater than zero. .TP .CI \-t \0fildes True, if file descriptor number .I fildes is open and is associated with a terminal device. .TP .CI \-u \0file True, if .I file exists and has its setuid bit set. .TP .CI \-w \0file True, if .I file exists and is writable by the current process. .TP .CI \-x \0file True, if .I file exists and is executable by the current process. If .I file exists and is a directory, then the current process has permission to search in the directory. .TP .CI \-z \0string True, if length of .I string is zero. .TP .CI \-L \0file True, if .I file exists and is a symbolic link. .TP .CI \-O \0file True, if .I file exists and is owned by the effective user ID of this process. .TP .CI \-G \0file True, if .I file exists and its group matches the effective group ID of this process. .TP .CI \-S \0file True, if .I file exists and is a socket. .TP .IC file1\0 \-nt \0file2 True, if .I file1 exists and is newer than .IR file2 . .TP .IC file1\0 \-ot \0file2 True, if .I file1 exists and is older than .IR file2 . .TP .IC file1\0 \-ef \0file2 True, if .I file1 and .I file2 exist and refer to the same file. .TP .IC string\0 = \0pattern True, if .I string matches .IR pattern . .TP .IC string\0 != \0pattern True, if .I string does not match .IR pattern . .TP .IC string\0 < \0string2 True, if .I string1 comes before .I string2 based on the ASCII value of their characters. .TP .IC string\0 > \0string2 True, if .I string1 comes after .I string2 based on the ASCII value of their characters. .TP .IC exp1\0 \-eq \0exp2 True, if .I exp1 is equal to .IR exp2 . .TP .IC exp1\0 \-ne \0exp2 True, if .I exp1 is not equal to .IR exp2 . .TP .IC exp1\0 \-lt \0exp2 True, if .I exp1 is less than .IR exp2 . .TP .IC exp1\0 \-gt \0exp2 True, if .I exp1 is greater than .IR exp2 . .TP .IC exp1\0 \-le \0exp2 True, if .I exp1 is less than or equal to .IR exp2 . .TP .IC exp1\0 \-ge \0exp2 True, if .I exp1 is greater than or equal to .IR exp2 . .PD .RE .PP A compound expression can be constructed from these primitives by using any of the following, listed in decreasing order of precedence. .RS .TP 20 .PD 0 .CI ( exp ) True, if .I exp is true. Used to group expressions. .TP .CI ! exp True, if .I exp is false. .TP .IC exp1\0 && \0exp2 True, if .I exp1 and .I exp2 are both true. .TP .IC exp1\0 || \0exp2 True, if either .I exp1 or .I exp2 is true. .PD .RE .SS Input/Output Before a command is executed, its input and output can be redirected using a special notation interpreted by the shell. The following can appear anywhere in a simple-command or may precede or follow a command and are not passed on to the invoked command. Command and parameter substitution occurs before .I word or .I digit is used, except as noted below. File name generation occurs only if the pattern matches a single file and blank interpretation is not performed. .RS .TP 15 .CI < word Use file .I word as standard input (file descriptor .CR 0 ). .TP .CI > word Use file .I word as standard output (file descriptor .CR 1 ). If the file does not exist, it is created. If the file exists, and the .CR noclobber option is on, an error occurs; otherwise, the file is truncated to zero length. .TP .CI >| word Same as .CR > , except that it overrides the .CR noclobber option. .TP .CI >> word Use file .I word as standard output. If the file exists, output is appended to it (by first searching for the end-of-file); otherwise, the file is created. .TP .CI <> word Open file .I word for reading and writing as standard input. .TP .CR << [ \- ]\f2word The shell input is read up to a line that matches .IR word , or to an end-of-file. No parameter substitution, command substitution or file name generation is performed on .IR word . The resulting document, called a .IR here-document , becomes the standard input. If any character of .I word is quoted, no interpretation is placed upon the characters of the document. Otherwise, parameter and command substitution occurs, .CR \e newline is ignored, and .CR \e must be used to quote the characters .CR \e , .CR $ , .CR ` , and the first character of .IR word . If .CR \- is appended to .CR << , all leading tabs are stripped from .I word and from the document. .TP .CI <& digit The standard input is duplicated from file descriptor .I digit (see .IR dup (2)). .TP .CI >& digit The standard output is duplicated to file descriptor .I digit (see .IR dup (2)). .TP .CR <&- The standard input is closed. .TP .CR >&- The standard output is closed. .TP .CR <&p The input from the coprocess is moved to standard input. .TP .CR >&p The output to the coprocess is moved to standard output. .RE .RE .PP If any of the above redirections is preceded by a digit .RC ( 0 to .CR 9 ), the file descriptor used is the one specified by the digit, instead of the default .CR 0 (standard input) or .CR 1 (standard output). For example: .IP .CR 2>&1 .PP means open file descriptor 2 for writing as a duplicate of file descriptor 1. Output directed to file descriptor 2 is written in the same location as output to file descriptor 1. .PP Order is significant in redirection. The shell evaluates each redirection in terms of the .RI ( "file descriptor" ", " file ) assignment at the time of evaluation. For example: .IP .CR 1> \f2fname\0 2>&1 .PP first assigns file descriptor 1 to file .IR fname . It then assigns file descriptor 2 to the file assigned to file descriptor 1 (that is, .IR fname ). .PP If the order of redirection is reversed, as in .IP .CR 2>&1\01> \f2fname .PP file descriptor 2 is assigned to the file assigned to file descriptor 1 (probably the terminal) and then file descriptor 1 is assigned to file .IR fname . .PP By using the redirection operators above, the input and output of a .I coprocess may be moved to a numbered file descriptor, allowing other commands to write to them and read from them. If the input of the current coprocess is moved to a numbered file descriptor, another coprocess may be started. .PP If a command is followed by .CR & and job control is inactive, the default standard input for the command is the empty file .CR /dev/null . Otherwise, the environment for the execution of a command contains the file descriptors of the invoking shell as modified by input/output specifications. .SS Environment The .B environment (see .IR environ (5)) is a list of name-value pairs passed to an executed program much like a normal argument list. The names must be identifiers and the values are character strings. The shell interacts with the environment in several ways. When invoked, the shell scans the environment and creates a parameter for each name found, gives it the corresponding value and marks it .CR export . Executed commands inherit the environment. If the user modifies the values of these parameters or creates new ones by using the .CR export or .CR "typeset \-x" special commands, the values become part of the environment. The environment seen by any executed command is thus composed of any name-value pairs originally inherited by the shell, whose values may be modified by the current shell, plus any additions which must be noted in .CR export or .CR "typeset \-x" commands. .PP The environment for any simple command or function can be augmented by prefixing it with one or more parameter assignments. A parameter assignment argument takes the form .IC identifier = value\f1. For example, both the following .IP .CI TERM=450 "\0cmd\0args" .IP .CI "(export TERM; TERM=450;" "\0cmd\0args" ) .PP are equivalent (as far as the execution of .I cmd is concerned, except for the special commands that are preceded by a dagger (\(dg)). .PP If the .CR \-k option is set, all parameter assignment arguments are placed in the environment, even if they occur after the command name. The following echo statement prints .CR "a=b c" . After the .CR \-k option is set, the second echo statement prints only .CR c : .nf .IP .CR "echo a=b c" \0\(->\0 "a=b c" .CR "set \-k" .CR "echo a=b c" \0\(->\0 "c" .fi .PP This feature is intended for use with scripts written for early versions of the shell and its use in new scripts is strongly discouraged. It is likely to disappear someday. .SS Functions The .CR function command (described in the "Compound Commands" subsection) defines shell functions. Shell functions are read and stored internally. Alias names are resolved when the function is read. Functions are executed like commands, with the arguments passed as positional parameters. (See the "Execution" subsection.) .PP Functions execute in the same process as the caller and share all files and current working directory with the caller. Traps defined by the caller are reset to their default action inside the function. A trap condition that is not caught or ignored by the function causes the function to terminate and the condition to be passed on to the caller. A trap on .CR EXIT set inside a function is executed after the function completes in the environment of the caller. Ordinarily, variables are shared between the calling program and the function. However, the .CR typeset special command can be used within a function to define local variables whose scope includes the current function and all functions it calls. .PP The .CR return special command is used to return from function calls. Errors within functions return control to the caller. .PP Function identifiers can be listed with the .CR +f option of the .CR typeset special command. Function identifiers and the associated text of the functions can be listed with the .CR \-f option. Functions can be undefined with the .CR \-f option of the .CR unset special command. .PP Ordinarily, functions are unset when the shell executes a shell script. The .CR \-xf option of the .CR typeset command allows a function to be exported to scripts that are executed without reinvoking the shell. Functions that must be defined across separate invocations of the shell should be placed in the .CR ENV file. .SS Jobs If the .CR monitor option of the .CR set command is turned on, an interactive shell associates a .I job with each pipeline. It keeps a table of current jobs, printed by the .CR jobs command, and assigns them small integer numbers. When a job is started asynchronously with .CR & , the shell prints a line that looks like: .IP .C "[1] 1234" .PP indicating that job number 1 was started asynchronously and had one (top-level) process whose process ID was 1234. .PP If you are running a job and wish to do something else, you can type the suspend character (the .CR susp character defined with .CR stty ; see .IR stty (1)) to send a .CR SIGSTOP signal to the current job. The shell then indicates that the job has been .CR Stopped , and prints another prompt. Then you can manipulate the state of this job by putting it in the background with the .CR bg command, running other commands, and eventually returning the job to the foreground with the .CR fg command. A suspend takes effect immediately and resembles an interrupt, since pending output and unread input are discarded when the suspend is entered. .PP A job running in the background stops if it tries to read from the terminal. Background jobs normally are allowed to produce output, but can be disabled with the .CR "stty tostop" command. If the user sets this terminal option, background jobs stop when trying to produce output. .PP There are several ways to refer to jobs in the shell. A job can be referred to by the process ID of any process in the job or by one of the following: .RS .TP 20 .PD 0 .CI % number The job with the given number. .TP .CI % string Any job whose command line begins with .IR string . .TP .CI %? string Any job whose command line contains .IR string . .TP .CI %% Current job. .TP .CI %+ Equivalent to .CR %% . .TP .CR %- Previous job. .PD .RE .PP The shell learns immediately when a process changes state. It informs the user when a job is blocked and prevented from further progress, but only just before it prints a prompt. .PP When the monitor mode is on, each background job that completes triggers any trap set for .CR SIGCHLD . .PP If you try to exit from shell while jobs are stopped, you are warned with the message .CR "You have stopped jobs." You can use the .CR jobs command to identify them. If you immediately try to exit again, the shell will not warn you a second time, and the stopped jobs will be terminated. .PP If you try to leave the shell while jobs are running, you are not warned. The shell exits silently and sets the parent of the running jobs to the .CR init process (number 1). .SS Signals The .CR SIGINT and .CR SIGQUIT signals for an invoked command are ignored if the command is followed by .CR & and the .CR monitor option is off. Otherwise, signals have the values inherited by the shell from its parent, with the exception of signal .CR SIGSEGV (but see also the .CR trap special command). .SS Execution Substitutions are made each time a command is executed. .CR sh checks the command name to determine whether it matches a special command. If it does, it is executed within the current shell process. .PP Next, .CR sh checks the command name to determine whether it matches one of the user-defined functions. If it does, .CR sh saves the positional parameters, then sets them to the arguments of the function call. The positional parameter .CR 0 is unchanged. When the function completes or issues a .CR return , .CR sh restores the positional parameter list and executes any trap set on .CR EXIT within the function. The value of a function is the value of the last command executed. A function is executed in the current shell process. .PP If a command name is not a user-defined function or a special command, .CR sh creates a process and attempts to execute the command using an .CI exec * () system call (see .IR exec (2)). .PP The shell parameter .CR PATH defines the search path for the directory containing the command. Alternative directory names are separated by a colon .RC ( : ). The default path is .CR /usr/bin:\& (specifying .CR /usr/bin , and the current directory, in that order). Note that the current directory is specified by a null path name, which can appear immediately after the equal sign, between colon delimiters, or at the end of the path list. The search path is not used if the command name contains a .CR / . Otherwise, each directory in the path is searched for an executable file. If the file has execute permissions but is not a directory or an executable object code file, it is assumed to be a script file, which is a file of data for an interpreter. If the first two characters of the script file are .CR #! , .CI exec * () expects an interpreter path name to follow. .CI exec * () then attempts to execute the specified interpreter as a separate process to read the entire script file. If a call to .CI exec * () fails, .CR sh is spawned to interpret the script file. All nonexported aliases, functions, and named parameters are removed in this case. If the shell command file does not have read permission, or if the .CR setuid and/or .CR setgid bits are set on the file, the shell executes an agent to set up the permissions and execute the shell with the shell command file passed down as an open file. A parenthesized command is also executed in a subshell without removing nonexported quantities. .SS Command Reentry The text of the last .CR HISTSIZE (default 128) commands entered from a terminal device is saved in a history file. The file .CR $HOME/.sh_history is used if the .CR HISTFILE variable is not set or writable. A shell can access the commands of all interactive shells that use the same named .CR HISTFILE . The special command .CR fc is used to list or edit a portion of this file. The portion of the file to be edited or listed can be selected by number or by giving the first character or characters of the command. A single command or range of commands can be specified. If you do not specify an editor program as an argument to .CR fc , the value of the parameter .CR FCEDIT is used. If .CR FCEDIT is not defined, .CR /usr/bin/ed is used. The edited command is printed and reexecuted upon leaving the editor. The editor name .CR \- is used to skip the editing phase and to reexecute the command. In this case, a substitution parameter of the form .IC old = new can be used to modify the command before execution. For example, if .CR r is aliased to .CR "fc \-e \-" , typing .CR "r bad=good c" reexecutes the most recent command that starts with the letter .CR c and replaces the first occurrence of the string .CR bad with the string .CR good . .SS Command Line Editing Normally, each command line typed at a terminal device is followed by a newline or return. If one of the .CR emacs , .CR gmacs , .CR vi , or .CR viraw , options is set, you can edit the command line. An editing option is automatically selected each time the .CR VISUAL or .CR EDITOR variable is assigned a value ending in one of these option names. .PP The editing features require that the user's terminal accept return without line feed and that a space ("\ ") must overwrite the current character on the screen. ADM terminal users should set the "space\ \(mi\ advance" switch to "space". Hewlett-Packard terminal users should set the straps to "bcGHxZ\ etX". .PP The editing modes enable the user to look through a window at the current line. The default window width is 80, unless the value of .CR COLUMNS is defined. If the line is longer than the window width minus two, a mark displayed at the end of the window notifies the user. The mark is one of: .RS .TP .PD 0 .CR > The line extends to the right. .TP .CR < The line extends to the left. .TP .CR * The line extends to both sides of the window. .PD .RE .PP As the cursor moves and reaches the window boundaries, the window is centered about the cursor. .PP The search commands in each edit mode provide access to the history file. Only strings are matched, not patterns, although a leading .CR ^ in the string restricts the match to begin at the first character in the line. .SS emacs Editing Mode This mode is invoked by either the .CR emacs or .CR gmacs option. Their sole difference is their handling of .CR ^T . To edit, the user moves the cursor to the point needing correction and inserts or deletes characters or words. All editing commands are control characters or escape sequences. The notation for control characters is caret .RC ( ^ ) followed by a character. For example, .CR ^F is the notation for Control-F. This is entered by holding down the Ctrl (control) key and pressing .CR f . The shift key is .I not pressed. The notation .CR ^?\& indicates the delete (DEL) key. .PP The notation for escape sequences is .CR M- followed by a character. For example, .CR M-f (pronounced .IR "meta f" ) is entered by pressing the escape key (ESC) followed by pressing .CR f . .CR M-F is the notation for escape followed by shift (capital) .CR F . .PP All edit commands operate from any place on the line (not only at the beginning). Neither the return .RC ( ^M ) nor the newline .RC ( ^J ) key is entered after edit commands, except when noted. .RS .TP 15 .PD 0 .CR ^F Move cursor forward (right) one character. .TP .CR M-f Move cursor forward one word. (The editor's idea of a word is a string of characters consisting of only letters, digits and underscores.) .TP .CR ^B Move cursor backward (left) one character. .TP .CR M-b Move cursor backward one word. .TP .CR ^A Move cursor to start of line. .TP .CR ^E Move cursor to end of line. .TP .CI ^] char Move cursor forward to character .I char on current line. .TP .CI M-^] char Move cursor backward to character .I char on current line. .TP .CI ^X^X Interchange the cursor and mark. .TP .I erase Delete previous character. (User-defined erase character as defined by the .CR stty command, usually .CR ^H or .CR # .) .TP .CR ^D Delete current character. .TP .I eof Terminate the shell if the current line is null. (User-defined end-of-file character as defined by the .CR stty command, usually .CR ^D .) .TP .CI M-d Delete current word. .TP .CI M-^H Delete previous word. (meta-backspace) .TP .CI M-h Delete previous word. .TP .CI M-^?\& Delete previous word. (meta-delete) If your interrupt character is .CR ^?\& (DEL, the default), this command will not work. .TP .CI ^T In .CR emacs mode, transpose current character with next character. In .CR gmacs mode, transpose two previous characters. .TP .CI ^C Capitalize current character. .TP .CI M-c Capitalize current word. .TP .CI M-l Change the current word to lowercase. .TP .CI ^K Delete from the cursor to the end of the line. If preceded by a numerical parameter whose value is less that the current cursor position, then delete from the given position up to the cursor. If preceded by a numerical parameter whose value is greater than the current cursor position, then delete from the cursor up to the given position. .TP .CI ^W Kill from the cursor to the mark. .TP .CI M-p Push the region from the cursor to the mark on the stack. .TP .I kill Kill the entire current line. If two kill characters are entered in succession, all subsequent consecutive kill characters cause a line feed (useful when using paper terminals). (User-defined kill character as defined by the .CR stty command, usually .CR ^X or .CR @ .) .TP .CI ^Y Restore last item removed from line. (Yank item back to the line.) .TP .CI ^L Line feed and print current line. .TP .CR ^@ Set mark. (null character) .TP .CI M-\0 Set mark. (meta-space) .TP .CI ^J Execute the current line. (newline) .TP .CI ^M Execute the current line. (return) .TP .CI ^P Fetch previous command. Each time .CR ^P is entered, the previous command in the history list is accessed. .TP .CI ^N Fetch next command. Each time .CR ^N is entered the next command in the history list is accessed. .TP .CI M-< Fetch the least recent (oldest) history line. .TP .CI M-> Fetch the most recent (youngest) history line. .TP .CI ^R string Reverse search history for a previous command line containing .IR string . If a parameter of zero is given, the search is forward. .I string is terminated by a return or newline. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is omitted, the next command line containing the most recent .I string is accessed. In this case, a parameter of zero reverses the direction of the search. .TP .CR ^O Execute the current line and fetch the next line relative to current line from the history file. .TP .CI M- digits Define a numeric parameter. The digits are taken as a parameter to the next command. The commands that accept a parameter are .IR erase , .CR ^B , .CR ^C , .CR ^D , .CR ^F , .CR ^K , .CR ^N , .CR ^P , .CR ^R , .CR ^] , .CR M-^H , .CR M-. , .CR M-_ , .CR M-b , .CR M-c , .CR M-d , .CR M-f , .CR M-h , and .CR M-l . .TP .CI M- letter Your alias list is searched for an alias by the name .CI _ letter (underscore-letter). If an alias of this name is defined, its value is inserted on the input queue. This .I letter must not be one of the above metafunctions. .TP .CR M-. The last word of the previous command is inserted on the line. If preceded by a numeric parameter, the value of this parameter determines which word to insert rather than the last word. .TP .CR M-_ Same as .CR M-. . .TP .CR M-* Attempt file name generation on the current word. .TP .CR M-^[ File name completion. (meta-escape.) Replaces the current word with the longest common prefix of all file names matching the current word with an asterisk appended. If the match is unique, a .CR / is appended if the file is a directory and a space is appended if the file is not a directory. .TP .CR M-= List files matching current word pattern as if an asterisk were appended. .TP .CR ^U Multiply parameter of next command by 4. .TP .CR \e Escape next character. Editing characters and your erase, kill, and interrupt characters may be entered in a command line or in a search string, if preceded by a .CR \e . The .CR \e removes the next character's editing features (if any). .TP .CI ^V Display version of the shell. .TP .CI M-# Insert a .CR # at the beginning of the line and execute it. This causes a comment to be inserted in the history file. .PD .RE .SS vi Editing Mode The editor starts in insert mode until an escape (ESC) is received. This puts you in control mode in which you can move the cursor and perform editing commands. A return in either mode sends the line. .PP Most control commands accept an optional repeat .I count prior to the command. .PP In .CR vi mode on most systems, canonical processing is initially enabled and the command is echoed again if the speed is 1200 baud or greater and contains any control characters, or if less than one second has elapsed since the prompt was printed. The escape (ESC) character terminates canonical processing for the remainder of the command and you can then modify the command line. This scheme has the advantages of canonical processing with the typeahead echoing of raw mode. .PP Setting the .CR viraw option always disables canonical processing on the terminal. This mode is implicit for systems that do not support two alternate end-of-line delimiters, and may be helpful for certain terminals. .PP .B Insert Edit Commands .PP By default, the editor is in insert mode. .RS .TP 15 .PD 0 .I erase Delete previous inserted character. The .IR erase character is user-definable with the .CR stty command, usually set to .CR ^H . The system default is .CR # . .TP .I kill Delete all current inserted characters. The .IR kill character is user-definable with the .CR stty command, usually set to .CR ^X or .CR ^U . The system default is .CR @ . .TP .CR \e Escape the next .I erase or .I kill character. .TP .CR ^D Terminate the shell. .TP .CR ^V Escape next character. Editing characters and erase or kill characters may be entered in a command line or in a search string if preceded by a .CR ^V , which removes the next character's editing features (if any). .TP .CR ^W Delete the previous blank-separated word. .PD .RE .PP .B Motion Edit Commands .PP These commands move the cursor. The use of .IR count causes a repetition of the command the cited number of times. .RS .TP 15 .PD 0 .RC [\f2count\f1] l Cursor forward (right) one character. .TP .RC [\f2count\f1] w Cursor forward one alphanumeric word. .TP .RC [\f2count\f1] W Cursor forward to the beginning of the next word that follows a blank. .TP .RC [\f2count\f1] e Cursor forward to the end of the word. .TP .RC [\f2count\f1] E Cursor forward to end of the current blank-delimited word. .TP .RC [\f2count\f1] h Cursor backward (left) one character. .TP .RC [\f2count\f1] b Cursor backward one word. .TP .RC [\f2count\f1] B Cursor backward to preceding blank-separated word. .TP .RC [\f2count\f1] | Cursor to column .IR count . Default is 1. .TP .RC [\f2count\f1] f \f2c Find the next character .IR c in the current line. .TP .RC [\f2count\f1] F \f2c Find the previous character .IR c in the current line. .TP .RC [\f2count\f1] t \f2c Equivalent to .CI f c followed by .CR h . .TP .RC [\f2count\f1] T \f2c Equivalent to .CI F c followed by .CR l . .TP .RC [\f2count\f1] ; Repeat the last single-character find command, .CR f , .CR F , .CR t , or .CR T . .TP .RC [\f2count\f1] , Reverses the last single character find command. .TP .CR 0 Cursor to start of line. .TP .CR ^ Cursor to first nonblank character in line. .TP .CR $ Cursor to end of line. .PD .RE .PP .B History Search Commands .PP These commands access your command history file. .RS .TP 15 .PD 0 .RC [\f2count\f1] k Fetch previous command. Each time .CR k is entered, the next earlier command in the history list is accessed. .TP .RC [\f2count\f1] \- Equivalent to .CR k . .TP .RC [\f2count\f1] j Fetch next command. Each time .CR j is entered, the next later command in the history list is accessed. .TP .RC [\f2count\f1] + Equivalent to .CR j . .TP .RC [\f2count\f1] G The command number .I count is fetched. The default is the first command in the history list. .TP .CI / string Search backward through history for a previous command containing .IR string . .I string is terminated by a return or newline. If .I string is preceded by a .CR ^ , the matched line must begin with .IR string . If .I string is null, the previous string is used. .TP .CI ? string Same as .CR / , but search in the forward direction. .TP .CR n Search for next match of the last pattern to the .CR / or .CR ? commands. .TP .CR N Search for next match of the last pattern to .CR / or .CR ? , but in reverse direction. .PD .RE .PP .B Text Modification Edit Commands .PP These commands will modify the line. .RS .TP 15 .PD 0 .CR a Enter insert mode after the current character. .TP .CR A Append text to the end of the line. Equivalent to .CR $a . .TP .RC [\f2count\f1] c \f2motion .TP .CR c [\f2count\f1]\f2motion Move cursor forward to the character position specified by .IR motion , deleting all characters between the original cursor position and the new position, and enter insert mode. If .I motion is .CR c , the entire line is deleted. .TP .CR C Delete from the current character through the end of line and enter insert mode. Equivalent to .CR c$ . .TP .CR S Equivalent to .CR cc . .TP .RC [\f2count\f1] d \f2motion .TP .CR d [\f2count\f1]\f2motion Move cursor to the character position specified by .IR motion , deleting all characters between the original cursor position and the new position. If .I motion is .CR d , the entire line will be deleted. .TP .CR D Delete from the current character through the end of line. Equivalent to .CR d$ . .TP .CR i Enter insert mode before the current character. .TP .CR I Enter insert mode before the beginning of the line. Equivalent to the two-character sequence .CR 0i . .TP .RC [\f2count\f1] P Insert the previous text modification before the cursor. .TP .RC [\f2count\f1] p Insert the previous text modification after the cursor. .TP .CR R Enter insert mode and replace characters on the screen with characters you type, overlay fashion. .TP .RC [\f2count\f1] r \f2c Replace the current character with .IR c . .TP .RC [\f2count\f1] x Delete the current character. .TP .RC [\f2count\f1] X Delete the preceding character. .TP .RC [\f2count\f1] . Repeat the previous text modification command. .TP .CR ~ Invert the case of the current character and advance the cursor. .TP .RC [\f2count\f1] _ Append the .I count word of the previous command at the current cursor location and enter insert mode at the end of the appended text. The last word is used if .I count is omitted. .TP .CR * Append an .CR * to the current word and attempt file name generation. If no match is found, ring the bell. If a match is found, replace the word with the matching string of file names and enter insert mode. .TP escape .TP .CR \e Attempt file name completion on the current word. Replace the current word with the longest common prefix of all file names matching the current word with an asterisk appended. If the match is unique, append a .CR / if the file is a directory or append a space if the file is not a directory. .PD .RE .PP .B Other Edit Commands .PP .RS .TP 15 .PD 0 .RC [\f2count\f1] y \f2motion .TP .CR y [\f2count\f1]\f2motion Yank current character through character that .I motion would move the cursor to and put them into the delete buffer. The text and cursor are unchanged. .TP .CR Y Yank from current position to end of line. Equivalent to .CR y$ . .TP .CR u Undo the last text-modifying command. .TP .CR U Undo all the text-modifying commands performed on the line. .TP .RC [\f2count\f1] v Execute the command .CI "fc \-e ${VISUAL:-${EDITOR:-vi}}" " count" in the input buffer. If .I count is omitted, the current line is used. This executes an editor with the current line as the input "file". When you exit from the editor, the result is executed. .TP .CR ^L Line feed and print current line. .TP .CR ^J Execute the current line, regardless of mode. (newline) .TP .CR ^M Execute the current line, regardless of mode. (return) .TP .CR # Insert a .CR # at the beginning of the current line and after each embedded newline, and execute the line. Useful for inserting the current command line in the history list without executing it. .TP .CR = List the file names that match the current word if an asterisk were appended to it. .TP .CI @ letter Search your alias list for an alias with the name .CI _ letter (underscore letter). If an alias of this name is defined, its value is executed as a command sequence on the current line. This provides a simple macro capability. .PD .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_COLLATE determines the collating sequence used in evaluating pattern matching notation for file name generation. If it is not defined or is empty, it defaults to the value of .CR LANG . .PP .CR LC_CTYPE determines the classification of characters as letters, and the characters matched by character class expressions in pattern matching notation. If it is not defined or is empty, it defaults to the value of .CR LANG . .PP If .CR LANG is not defined or is empty, it defaults to .CR C (see .IR lang (5)). .PP If any internationalization variable contains an invalid value, they all default to .CR C (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH RETURN VALUE Errors detected by the shell, such as syntax errors, cause the shell to return a nonzero exit status. Otherwise, the shell returns the exit status of the last command executed. See also the .CR exit special command. If the shell is being used noninteractively, the execution of the shell file is abandoned. Runtime errors detected by the shell are reported by printing the command or function name and the error condition. If the line number on which the error occurred is greater than one, the line number is also printed in brackets .RC ( [] ) after the command or function name. .\".SH EXAMPLES .\" none appropriate. .SH WARNINGS .PP .\" File descriptors 54 through 60 are used internally by the POSIX shell. File descriptors 24 through 30 are used internally by the POSIX shell. Applications using these and forking a subshell should not depend upon them surviving in the subshell or its descendants. .PP If a command that is a tracked alias is executed, and a command with the same name is installed in a directory in the search path before the directory where the original command was found, the shell will continue to load and execute the original command. Use the .CR \-t option of the .CR alias command to correct this situation. .PP If you move the current directory or one above it, .CR pwd may not give the correct response. Use the .CR cd command with a full path name to correct this situation. .PP Some very old shell scripts use a caret .RC ( ^ ) as a synonym for the pipe character .RC ( | ). .CR sh .I "does not" recognize the caret as a pipe character. .PP If a command is piped into a shell command, all variables set in the shell command are lost when the command completes. .PP Using the .CR fc built-in command within a compound command will cause the entire command to disappear from the history file. .PP The dot .RC ( . ) special command, as in .CI .\& " file\f1," reads the entire file before any commands are executed. Therefore, .CR alias and .CR unalias commands in the file will not apply to any functions defined in the file. .PP Traps are not processed while the shell is waiting for a foreground job. Thus, a trap on .CR SIGCHLD is not executed until the foreground job terminates. .PP The .CR export special command does not handle arrays properly. Only the first element of an array is exported to the environment. .PP Background processes started from a noninteractive shell cannot be accessed with job control commands. .PP The value of the .CR IFS variable in the user's environment affects the behavior of scripts. .SS Collating Order In an international environment, character ordering is determined by the value of .CR LC_COLLATE , rather than by the binary ordering of character values in the machine collating sequence. This brings with it certain attendant dangers, particularly when using range expressions in file name generation patterns. For example, the command, .IP .C "rm [a-z]*" .PP might be expected to match all file names beginning with a lowercase alphabetic character. However, if dictionary ordering is specified by .CR LC_COLLATE , it would also match file names beginning with an uppercase character (as well as those beginning with accented letters). Conversely, it would fail to match letters collated after .CR z in languages such as Danish or Norwegian. .PP The correct (and safe) way to match specific character classes in an international environment is to use a pattern (see .IR regexp (5)) of the form: .IP .C "rm [[:lower:]]*" .PP This uses .CR LC_CTYPE to determine character classes and works predictably for all supported languages and codesets. For shell scripts produced on noninternationalized systems (or without consideration for the above dangers), it is recommended that they be executed in a non-NLS environment. This requires that .CR LANG , .CR LC_COLLATE , and so on, be set to .CR C or not set at all. .SS History File Changes At HP-UX release B.10.10, the history file has a new internal magic number. This will cause a pre-B.10.10 history file to be discarded. Users who use multiple versions of HP-UX that NFS-mount the same directory that contains the history file (usually the home directory) may want to create a separate history file for each HP-UX version by setting the .CR HISTFILE parameter as: .IP .C "HISTFILE=$HOME/.sh_hist_$(uname \-r)" .PP Users on windowing systems may want to have separate history files for each window by setting the HISTFILE parameter as follows: .IP .C "HISTFILE=$HOME/.sh_hist$$" .PP A .CR cron job may be used to delete old history files. .PP The history file does not support mixing of locales in the same file. For users of multiple locales, you can assign a unique history file for each locale by setting .CR HISTFILE as: .IP .C "HISTFILE=$HOME/.sh_hist_${LANG}" .PP or include the process number in the .CR HISTFILE parameter as shown above. .SH AUTHOR .CR sh was developed by AT&T, OSF, and HP. .SH FILES .TP 30 .PD 0 .CR $HOME/.profile Read to set up user's custom environment .TP .CR /etc/passwd To find home directories .TP .CR /etc/profile Read to set up system environment .TP .CR /etc/suid_profile Security profile .TP .CR /tmp/sh* For here-documents .TP .CR /usr/bin/sh Shell executable program location .PD .SH SEE ALSO cat(1), cd(1), command(1), echo(1), ed(1), env(1), getopts(1), kill(1), ln(1), login(1), newgrp(1), printf(1), pwd(1), read(1), stty(1), test(1), time(1), umask(1), vi(1), dup(2), exec(2), fork(2), pipe(2), stty(2), ulimit(2), umask(2), wait(2), rand(3C), a.out(4), profile(4), environ(5), lang(5), regexp(5), signal(5). .SH STANDARDS CONFORMANCE .CR sh ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR . ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR : ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR break ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR case ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR continue ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR eval ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR exec ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR exit ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR export ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR for ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR if ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR read ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR return ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR set ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR shift ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR time ": SVID2, SVID3, XPG2, XPG3, XPG4" .br .CR trap ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR unset ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR until ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .br .CR while ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4sh\f1 \- shell based on POSIX.2@@@\f3sh-posix(1)\f1 .\" index@\f4alias\f1 \- substitute command and/or file name@@@\f3sh-posix(1)\f1 .\" index@\f4break\f1 \- exit from enclosing for/next loop@@@\f3sh-posix(1)\f1 .\" index@\f4case\f1 \- execute \f2list\f1 associated with \f2pattern\f1 that matches \f2word\f1@@@\f3sh-posix(1)\f1 .\" index@\f4cd\f1 \- change working directory@@@\f3sh-posix(1)\f1 .\" index@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@\f3sh-posix(1)\f1 .\" index@\f4echo\f1 \- echo (print) arguments@@@\f3sh-posix(1)\f1 .\" index@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@\f3sh-posix(1)\f1 .\" index@\f4exec\f1 \- execute command without creating new process@@@\f3sh-posix(1)\f1 .\" index@\f4exit\f1 \- exit shell with exit status@@@\f3sh-posix(1)\f1 .\" index@\f4export\f1 \- export variable names to environment of subsequent commands@@@\f3sh-posix(1)\f1 .\" index@\f4fc\f1 \- edit and execute previous command@@@\f3sh-posix(1)\f1 .\" index@\f4for\f1 \- execute a do list@@@\f3sh-posix(1)\f1 .\" index@\f4if\f1 \- execute command if previous command returns exit status 0@@@\f3sh-posix(1)\f1 .\" index@\f4jobs\f1 \- list active jobs@@@\f3sh-posix(1)\f1 .\" index@\f4kill\f1 \- terminate job or process@@@\f3sh-posix(1)\f1 .\" index@\f4let\f1 \- evaluate arithmetic expression@@@\f3sh-posix(1)\f1 .\" index@\f4newgrp\f1 \- equivalent to \f4exec newgrp\f1@@@\f3sh-posix(1)\f1 .\" index@\f4print\f1 \- output from shell@@@\f3sh-posix(1)\f1 .\" index@\f4pwd\f1 \- print current working directory@@@\f3sh-posix(1)\f1 .\" index@\f4read\f1 \- input and parse a line@@@\f3sh-posix(1)\f1 .\" index@\f4readonly\f1 \- mark names as unredefinable@@@\f3sh-posix(1)\f1 .\" index@\f4return\f1 \- shell function return to invoking script@@@\f3sh-posix(1)\f1 .\" index@\f4set\f1 \- set/define options and arguments@@@\f3sh-posix(1)\f1 .\" index@\f4shift\f1 \- shift \f2argv\f1 members one position to left@@@\f3sh-posix(1)\f1 .\" index@\f4test\f1 \- evaluate conditional expression@@@\f3sh-posix(1)\f1 .\" index@\f4time\f1, \f4times\f1 \- print summary of time used by processes@@@\f3sh-posix(1)\f1 .\" index@\f4trap\f1 \- trap specified signal@@@\f3sh-posix(1)\f1 .\" index@\f4typeset\f1 \- control leading blanks and parameter handling@@@\f3sh-posix(1)\f1 .\" index@\f4ulimit\f1 \- set size or time limits@@@\f3sh-posix(1)\f1 .\" index@\f4umask\f1 \- set permissions mask for creating new files@@@\f3sh-posix(1)\f1 .\" index@\f4unalias\f1 \- discard specified alias@@@\f3sh-posix(1)\f1 .\" index@\f4unset\f1 \- remove definition/setting of options and arguments@@@\f3sh-posix(1)\f1 .\" index@\f4until\f1 \- execute commands until expression is nonzero@@@\f3sh-posix(1)\f1 .\" index@\f4wait\f1 \- wait for child process@@@\f3sh-posix(1)\f1 .\" index@\f4whence\f1 \- define interpretation of name as a command@@@\f3sh-posix(1)\f1 .\" index@\f4while\f1 \- execute commands while expression is nonzero@@@\f3sh-posix(1)\f1 .\" .\" toc@\f3sh-posix(1)\f1:\0\0\f4sh\f1@@@shell, the standard/restricted command programming language .\" toc@\f4case\f1 \- label in a switch statement@@@see \f3sh-posix(1)\f1 .\" toc@\f4alias\f1 \- substitute command and/or file name@@@see \f3sh-posix(1)\f1 .\" toc@\f4break\f1 \- exit from enclosing for/next loop@@@see \f3sh-posix(1)\f1 .\" toc@\f4continue\f1 \- resume next iteration of enclosing for/next loop@@@see \f3sh-posix(1)\f1 .\" toc@\f4cd\f1 \- change working directory@@@see \f3sh-posix(1)\f1 .\" toc@\f4echo\f1 \- echo (print) arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4eval\f1 \- read arguments as shell input and execute resulting commands@@@see \f3sh-posix(1)\f1 .\" toc@\f4exec\f1 \- execute command without creating new process@@@see \f3sh-posix(1)\f1 .\" toc@\f4exit\f1 \- exit shell with exit status@@@see \f3sh-posix(1)\f1 .\" toc@\f4export\f1 \- export variable names to environment of subsequent commands@@@see \f3sh-posix(1)\f1 .\" toc@\f4fc\f1 \- edit and execute previous command@@@see \f3sh-posix(1)\f1 .\" toc@\f4for\f1 \- execute a do list@@@see \f3sh-posix(1)\f1 .\" toc@\f4if\f1 \- execute command if previous command returns exit status 0@@@see \f3sh-posix(1)\f1 .\" toc@\f4jobs\f1 \- list active jobs@@@see \f3sh-posix(1)\f1 .\" toc@\f4kill\f1 \- terminate job or process@@@see \f3sh-posix(1)\f1 .\" toc@\f4let\f1 \- evaluate arithmetic expression@@@see \f3sh-posix(1)\f1 .\" toc@\f4newgrp\f1 \- equivalent to \f2exec newgrp\f1@@@see \f3sh-posix(1)\f1 .\" toc@\f4print\f1 \- output from shell@@@see \f3sh-posix(1)\f1 .\" toc@\f4pwd\f1 \- print current working directory@@@see \f3sh-posix(1)\f1 .\" toc@\f4read\f1 \- input and parse a line@@@see \f3sh-posix(1)\f1 .\" toc@\f4readonly\f1 \- mark names as unredefinable@@@see \f3sh-posix(1)\f1 .\" toc@\f4return\f1 \- shell function return to invoking script@@@see \f3sh-posix(1)\f1 .\" toc@\f4set\f1 \- set/define options and arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4shift\f1 \- shift \f2argv\f1 members one position to left@@@see \f3sh-posix(1)\f1 .\" toc@\f4test\f1 \- evaluate conditional expression@@@see \f3sh-posix(1)\f1 .\" toc@\f4trap\f1 \- trap specified signal@@@see \f3sh-posix(1)\f1 .\" toc@\f4time, times\f1 \- print summary of time used by processes@@@see \f3sh-posix(1)\f1 .\" toc@\f4typeset\f1 \- control leading blanks and parameter handling@@@see \f3sh-posix(1)\f1 .\" toc@\f4ulimit\f1 \- set size or time limits@@@see \f3sh-posix(1)\f1 .\" toc@\f4umask\f1 \- set permissions mask for creating new files@@@see \f3sh-posix(1)\f1 .\" toc@\f4unalias\f1 \- discard specified alias@@@see \f3sh-posix(1)\f1 .\" toc@\f4unset\f1 \- remove definition/setting of options and arguments@@@see \f3sh-posix(1)\f1 .\" toc@\f4wait\f1 \- wait for child process@@@see \f3sh-posix(1)\f1 .\" toc@\f4whence\f1 \- define interpretation of name as a command@@@see \f3sh-posix(1)\f1 .\" toc@\f4while\f1 \- execute commands while expression is nonzero@@@see \f3sh-posix(1)\f1 .\" toc@\f4until\f1 \- execute commands until expression is nonzero@@@see \f3sh-posix(1)\f1 .\" .\" links@sh-posix.1 alias.1 .\" links@sh-posix.1 bg.1 .\" links@sh-posix.1 fc.1 .\" links@sh-posix.1 fg.1 .\" links@sh-posix.1 jobs.1 .\" links@sh-posix.1 unalias.1 .\" $Header: uname.1,v 76.1 95/08/07 10:09:14 ssa Exp $ .\" NOTE: If this page changes, uname.2 probably changes too. .TA u .TH uname 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uname \- display information about computer system; set node name (system name) .SH SYNOPSIS .CR uname .RC [ -ailmnrsv ] .PP .CR uname .RC [ -S .IR nodename ] .SH DESCRIPTION In the first form above, the .CR uname command displays selected information about the current computer system, derived from the .CR utsname structure (see .IR uname (2)). .PP In the second form, .CR uname sets the node name (system name) that is used in the .CR utsname structure. .SS Options .CR uname recognizes the options listed below. If you enter several options, the output is always in the order shown for the .CR -a option. .RS .TP 15 none Equivalent to .CR -s . .TP .CR -a Display the options below in the following order, separated by blanks. .RS .IP .C "-s -n -r -v -m -i -l" .\" HP-UX hptac3a A.09.09 A 9000/720 53914141 two-user license .\" HP-UX hpulpcu4 A.09.01 C 9000/750 2015986034 32-user license .\" -i 2015986034 .\" -l 32-user license .\" -m 9000/750 .\" -n hpulpcu4 .\" -r A.09.01 .\" -s HP-UX .\" -v C .RE .TP .CR -i Display the machine identification number (or the node name, if the machine identification number cannot be determined). .TP .CR -l Display the license level of the operating system. 128-, 256-, and unlimited-user licenses are shown as .CR "unlimited-user license" . .TP .CR -m Display the machine hardware and model names. .TP .CR -n Display the node name (system name) by which the system is usually known in a UUCP network. See WARNINGS. .TP .CR -r Display the current release level of the operating system. .TP .CR -s Display the name of the operating system. On standard HP-UX systems, this option always displays .CR HP-UX . .TP .CR -v Display the current version level of the operating system. .TP .CI -S \0nodename Change the node name (system name) to .IR nodename . .I nodename is restricted to .CR UTSLEN-1 characters (see .IR uname (2)). See WARNINGS. Only users with appropriate privileges can use the .CR -S option. .SH EXAMPLES When you execute the command .CR "uname\ -a" , it produces output like the following: .IP .C "HP-UX myhost A.09.01 C 9000/750 2015986034 32-user license" .\" -i 2015986034 .\" -l 32-user license .\" -m 9000/750 .\" -n hpulpcu4 .\" -r A.09.01 .\" -s HP-UX .\" -v C .PP The displayed fields are interpreted as follows: .RS .TP 25 .CR HP-UX The operating system name (option .CR -s ). .TP .CR myhost The UUCP network system name by which the system is known .RC ( -n ). .TP .CR A.09.01 The operating system release identifier .RC ( -r ). .TP .CR C The operating system version identifier .RC ( -v ). .TP .CR 9000/750 The machine and model numbers .RC ( -m ). .TP .CR 2015986034 The machine identification number .RC ( -i ). .TP .CR "32-user license" The operating system license level .RC ( -l ). .RE .SH WARNINGS Many types of networking services are supported on HP-UX, each of which uses a separately assigned system name and naming convention. To ensure predictable system behavior, it is essential that system names (also called host names or node names) be assigned in such a manner that they do not create conflicts when the various networking facilities interact with each other. .PP The system does not rely on a single system name in a specific location, partly because different services use dissimilar name formats as explained below. The .CR hostname and .CR uname commands assign system names as follows: .PP .ne 6v .ift \{.vs +2 .TS center box tab(;); lf3 | lf3 | lf3 | lf3 l | l | l | l . Node Name;Command;\f2name\fP Format;Used By _ .\" line -------------- Internet name;\f4hostname \f2name;\f2sys\f1[\f4.\f2x\f4.\f2y\f4.\f2z\f1...];ARPA and NFS Services .\" line -------------- UUCP name;\f4uname -S \f2name;\f2sys;\f4uucp \f1and related programs .TE .vs\} .ifn \{.nf +--------------+--------------+---------------+-----------------------+ |\f3Node Name\f1 |\f3Command\f1 |\f2name\f3 Format\f1 |\f3Used By\f1 | +--------------+--------------+---------------+-----------------------+ |Internet name |\f3hostname \f2name\f1 |\f2sys\f1[\f3.\f2x\f3.\f2y\f3.\f2z\f1...] |ARPA and NFS Services | |UUCP name |\f3uname -S \f2name\f1 |\f2sys\f1 |\f3uucp\f1, related programs | +--------------+--------------+---------------+-------- --------------+ .fi\} .PP where .I sys represents the assigned system name. It is .I strongly recommended that .I sys be identical for all commands and locations and that the optional .CI . x . y . z\f1...\& follow the specified notation for the particular ARPA/NFS environment. .PP Internet names are also frequently called host names or domain names (which are different from NFS domain names). Refer to .IR hostname (5) for more information about Internet naming conventions. .PP Whenever the system name is changed in any file or by the use of any of the above commands, it should also be changed in all other locations as well. Other files or commands in addition to those above (such as .CR /etc/uucp/Permissions if used to circumvent .CR uname , for example) may contain or alter system names. To ensure correct operation, they should also use the same system name. .PP System names are normally assigned by the .CR /sbin/init.d/hostname script at start-up, and should not be altered elsewhere. .SH SEE ALSO hostname(1), setuname(1M), gethostname(2), sethostname(2), uname(2), hostname(5). .SH STANDARDS CONFORMANCE .CR uname ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f1display information about computer system@@@\f3uname(1)\f1 .\" index@\f1license level of operating system, display@@@\f3uname(1)\f1 .\" index@\f1machine identification, display@@@\f3uname(1)\f1 .\" index@\f1machine number, display@@@\f3uname(1)\f1 .\" index@\f1name of operating system, display@@@\f3uname(1)\f1 .\" index@\f1node name, display/set@@@\f3uname(1)\f1 .\" index@\f1computer system information, display@@@\f3uname(1)\f1 .\" index@\f1operating system information, display@@@\f3uname(1)\f1 .\" index@\f1operating system name, display@@@\f3uname(1)\f1 .\" index@\f1computer system, set node name@@@\f3uname(1)\f1 .\" index@\f1release of operating system, display@@@\f3uname(1)\f1 .\" index@\f1set node name@@@\f3uname(1)\f1 .\" index@\f1set system name@@@\f3uname(1)\f1 .\" index@\f1system information, display@@@\f3uname(1)\f1 .\" index@\f1name of operating system, display@@@\f3uname(1)\f1 .\" index@\f1system name, display/set@@@\f3uname(1)\f1 .\" index@\f1release level of operating system, display@@@\f3uname(1)\f1 .\" index@\f1version level of operating system, display@@@\f3uname(1)\f1 .\" index@\f1system, display information@@@\f3uname(1)\f1 .\" index@\f1system, set node name@@@\f3uname(1)\f1 .\" index@\f4uname\f1 \- display information about computer system; set node name (system name)@@@\f3uname(1)\f1 .\" .\" toc@\f3uname(1)\f1:\0\0\f4uname\f1@@@display information about computer system; set node name (system name) .\" $Header: compact.1,v 72.3 93/01/14 11:36:09 ssa Exp $ .TA c .TH compact 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compact, uncompact, ccat \- compact and uncompact files, and cat them .SH SYNOPSIS .C compact .RI [ \|name \0...] .br .C uncompact .RI [ \|name \0...] .br .C ccat .RI [ \|file \0...] .SH DESCRIPTION .C compact compresses the named files using an adaptive Huffman code. If no file names are given, standard input is compacted and sent to the standard output. .C compact operates as an on-line algorithm. Each time a byte is read, it is encoded immediately according to the current prefix code. This code is an optimal Huffman code for the set of frequencies seen so far. It is unnecessary to attach a decoding tree in front of the compressed file because the encoder and the decoder start in the same state and stay synchronized. Furthermore, .C compact and .C uncompact can operate as filters. In particular, .IP .RC ... " | compact | uncompact | " ... .PP operates as a (very slow) no-op. .PP When an argument .I file is given, it is compacted, the resulting file is placed in .IC file .C\f1, and .I file is unlinked. The first two bytes of the compacted file code the fact that the file is compacted. These bytes are used to prohibit recompaction. .PP The amount of compression to be expected depends on the type of file being compressed. Typical file size reduction (in percent) through compression are: Text, 38%; Pascal Source, 43%; C Source, 36%; and Binary, 19%. .PP .C uncompact restores the original file from a file compressed by .C compact. If no file names are specified, standard input is uncompacted and sent to the standard output. .PP .C ccat cats the original file from a file compressed by .C compact, without uncompressing the file. .SS "Access Control Lists (ACLs) On systems that implement access control lists, when a new file is created with the effective user and group .SM ID of the caller, the original file's .SM ACL is copied to the new file after being altered to reflect any change in ownership (see .IR acl (5)). .SH WARNINGS On short-filename systems, the last segment of the file name must contain 12 or fewer characters to allow space for the appended .CR .C . .SH DEPENDENCIES .SS \s-1NFS\s0 Access control list entries of networked files are summarized (as returned in .C st_mode by .CR stat() ), but not copied to the new file (see .IR stat (2)). .SH FILES .TP 20 .C *.C compacted file created by compact, removed by uncompact .SH SEE ALSO compress(1), pack(1), acl(5). .br Gallager, Robert G., ``Variations on a Theme of Huffman,'' .I "I.E.E.E. Transactions on Information Theory," vol. IT-24, no. 6, November 1978, pp. 668 - 674. .SH AUTHOR .C compact was developed by Colin L. Mc Master. .\" .\" index@\f4compact\f1 \- compact files using Huffman code (see \f4pack\f1(1))@@@\f3compact(1)\f1 .\" index@\f4ccat\f1 \- uncompact and cat files using Huffman code (see \f4pack\f1(1))@@@\f3compact(1)\f1 .\" index@\f4uncompact\f1 \- uncompact Huffman coded files (see \f4pack\f1(1))@@@\f3compact(1)\f1 .\" index@compact files using Huffman code (see \f4pack(1)\f1)@@@\f3compact(1)\f1 .\" index@cat after uncompacting Huffman coded files (see \f4pack(1)\f1)@@@\f3compact(1)\f1 .\" index@uncompact previously compacted Huffman coded files (see \f4pack(1)\f1)@@@\f3compact(1)\f1 .\" .\" toc@\f3compact(1)\f1:\0\0\f4compact\f1, \f4uncompact\f1, \f4ccat\f1@@@compact and uncompact files, and cat them .\" toc@\f4uncompact\f1: uncompact files@@@see \f3compact(1)\f1 .\" toc@\f4ccat\f1: cat compacted files@@@see \f3compact(1)\f1 .\" .\" links@compact.1 uncompact.1 .\" links@compact.1 ccat.1 .\" .\" fileset_database@compact.1 USER-CMDS-MAN .\" $Header: compress.1,v 76.1 95/07/10 16:56:11 ssa Exp $ .TA c .TH compress 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compress, uncompress, zcat, compressdir, uncompressdir \- compress and expand data .SH SYNOPSIS .SS Compress Files .C compress .RC [ -d ] .RC [ -f|-z ] .RC [ -z ] .RC [ -v ] .RC [ -c ] .RC [ -V ] .RC [ -b .IR maxbits \|] .RI [ \|file \0...\|] .br .C uncompress .RC [ -f ] .RC [ -v ] .RC [ -c ] .RC [ -V ] .RI [ \|file \0...\|] .br .C zcat .RC [ -V ] .RI [ \|file \0...\|] .SS Compress Entire Directory Subtrees .C compressdir .RI [ \|options\| ] .RI [ \|directory \0...\|] .br .C uncompressdir .RI [ \|options\| ] .RI [ \|directory \0...\|] .SH DESCRIPTION The following commands compress and uncompress files and directory subtrees as indicated: .RS .TP 20 .C compress Reduce the size of the named .IR file s using adaptive Lempel-Ziv coding. If reduction is possible, each .I file is replaced by a new file of the same name with the suffix .CR .Z added to indicate that it is a compressed file. Original ownership, modes, access, and modification times are preserved. If no .I file is specified, or if .CR - is specified, standard input is compressed to the standard output. .TP .C uncompress Restore the compressed .IR file s to original form. Resulting files have the original filename, ownership, and permissions, and the .CR .Z filename suffix is removed. If no .I file is specified, or if .CR - is specified, standard input is uncompressed to the standard output. .TP .C zcat Restore the compressed .IR file s to original form and send the result to standard output. If no .I file is specified, or if .CR - is specified, standard input is uncompressed to the standard output. .TP .C compressdir Front-end processor. Recursively descend each specified .I directory subtree and use .CR compress to compress each file in .IR directory . Existing files are replaced by a compressed file having the same name plus the suffix .CR .Z , provided the resulting file is smaller than the original. If no directories are specified, compression is applied to all files starting with the current directory. .IP .I options may include any valid .CR compress command options (they are passed through to .CR compress ). To force compression of all files, even when the result is larger than the original file, use the .CR -f option. .TP .C uncompressdir Opposite of .CR compressdir . Restore compressed files to their original form. .I options may include any valid .CR uncompress command options (they are passed through to .CR uncompress ). .RE .PP The amount of compression obtained depends on the size of the input, the maximum number of bits .RI ( maxbits ) per code, and the distribution of common substrings. Typically, text such as source code or English is reduced by 50-60 percent. Compression is generally much better than that achieved by Huffman coding (as used in .CR pack ), or adaptive Huffman coding .RC ( compact ), and takes less time to compute. .SS Options These commands recognize the following options in the combinations shown above in .SM SYNOPSIS: .RS .TP 20 .C -d Decompress .IR file . .CR "compress -d" is equivalent to .CR uncompress . .TP .C -f Force compression of .IR file . This is useful for compressing an entire directory, even if some of the files do not actually shrink. If .CR -f is not given and .CR compress is run in the foreground, the user is prompted as to whether an existing file should be overwritten. .TP .C -z This is the same as the .C -f option except that it does not force compression when there is null compression. .TP .C -v Print a message describing the percentage of reduction for each file compressed. .TP .C -c Force .CR compress and .CR uncompress to write to the standard output; no files are changed. The nondestructive behavior of .CR zcat is identical to that of .CR "uncompress -c" . .TP .C -V Print the current version and compile options onto the standard error. .TP .CI -b \0maxbits Specify the maximum number of bits the .CR compress algorithm will use. The default is 16 and the range can be any integer between 9 and 16. .RE .PP .C compress uses the modified Lempel-Ziv algorithm popularized in .I "A Technique for High Performance Data Compression", Terry A. Welch, .I "IEEE Computer," vol. 17, no. 6 (June 1984), pages 8-19. Common substrings in the file are first replaced by 9-bit codes 257 and up. When code 512 is reached, the algorithm switches to 10-bit codes and continues to use more bits until the limit specified by the .CR -b flag is reached (default 16). .PP After the .I maxbits limit is attained, .CR compress periodically checks the compression ratio. If it is increasing, .CR compress continues to use the existing code dictionary. However, if the compression ratio is decreasing, .CR compress discards the table of substrings and rebuilds it from scratch. This allows the algorithm to adapt to the next "block" of the file. .PP Note that the .CR -b flag is omitted for .CR uncompress since the .I maxbits parameter specified during compression is encoded within the output, along with a magic number to ensure that neither decompression of random data nor recompression of compressed data is attempted. .SS "Access Control Lists" .C compress retains a file's access control list when compressing and expanding data. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .CR compress , .CR uncompress , and .C zcat behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE These commands return the following values upon completion: .RS .TP 5 .C 0 Completed successfully. .PD 0 .TP .C 2 Last file is larger after (attempted) compression. .TP .C 1 An error occurred. .PD .RE .SH DIAGNOSTICS .TP .C "Usage: compress [-f|-z] [-dvcV] [-b maxbits] [file ...]" Invalid options were specified on the command line. .TP .C "Missing maxbits" .I maxbits must follow .CR -b . .TP .IC file ": not in compressed format" The file specified to .CR uncompress has not been compressed. .TP .IC file ": compressed with " xx "bits, can only handle " yy "bits" .I file was compressed by a program that could deal with a higher value of .I maxbits than the compress code on this machine. Recompress the file with a lower value of .IR maxbits . .TP .IC file ": already has .Z suffix -- no change" The file is assumed to be already compressed. Rename the file and try again. .TP .IC file ": filename too long to tack on .Z" The output file name, which is the source file name with a .CR .Z extension, is too long for the file system on which the source file resides. Make the source file name shorter and try again. .TP .C "file already exists; do you wish to overwrite (y or n)?" Respond .CR y if you want the output to replace the existing file; otherwise, respond .CR n . .TP .C "uncompress: corrupt input" A .CR SIGSEGV violation was detected which usually means that the input file has been corrupted. .TP .CI "Compression: " xx . xx % Percentage of the input saved by compression. (Relevant only for .CR -v .) .TP .C "-- not a regular file: unchanged" When the input file is not a regular file (a directory for example), it is left unaltered. .TP .CI "-- has " xx "other links: unchanged" The input file has links and has been left unchanged. See .IR ln (1) for more information. .TP .C "-- file unchanged" No savings is achieved by compression. The input remains unaltered. .SH EXAMPLES Compress the file named .CR zenith and print compression information to the terminal: .RS .IP .C compress -v zenith .RE .PP The terminal display shows either a line resembling .IP .C "zenith: Compression: 23.55% -- replaced with zenith.Z" .PP indicating that the compressed file is 23.55% smaller than the original, or a line resembling .IP .C "zenith: Compression: -12.04% -- file unchanged" .PP indicating that an additional 12.04% space must be used to compress the file. .PP Undo the compression by typing either of the following commands: .RS .IP .C uncompress zenith.Z .IP .C compress -d zenith.Z .RE .PP This restores file .CR zenith.Z to its original uncompressed form and name. .PP .CR uncompress will perform on standard input if no files are specified. For example, to list a compressed tar file: .RS .IP .C "uncompress -c arch.tar.Z | tar -tvf - " .RE .SH WARNINGS Although compressed files are compatible between machines with large memory, .CR -b 12 should be used for file transfer to architectures with a small process data space (64K bytes or less). .SS \s-1NFS\s0 Access control lists of networked files are summarized (as returned in .CR st_mode by .CR stat() , but not copied to the new file (see .IR stat (2)). .SH AUTHOR .C compress was developed by Joseph M. Orost, Kenneth E. Turkowski, Spencer W. Thomas, and James A. Woods. .SH FILES .TP .C *.Z Compressed file created by .CR compress and removed by .CR uncompress . .SH SEE ALSO compact(1), pack(1), acl(5). .SH STANDARDS CONFORMANCE .CR compress ": XPG4" .\" index@\f4compress\f1, \f4uncompress\f1, \f4zcat\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4uncompress\f1, \f4compress\f1, \f4zcat\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4zcat\f1, \f4compress\f1, \f4uncompress\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4compressdir\f1, \f4uncompressdir\f1 \- compress or expand files in a directory@@@\f3compress(1)\f1 .\" index@\f4uncompressdir\f1, \f4compressdir\f1 \- compress or expand files in a directory@@@\f3compress(1)\f1 .\" index@\f1compress or expand data@@@\f3compress(1)\f1 .\" index@\f1expand or compress data@@@\f3compress(1)\f1 .\" index@\f1data, expand or compress@@@\f3compress(1)\f1 .\" index@\f1files: expand compressed files in a directory@@@\f3compress(1)\f1 .\" index@\f1files: expand compressed file@@@\f3compress(1)\f1 .\" index@\f1files: compress files in a directory@@@\f3compress(1)\f1 .\" index@\f1files: compress data in a file@@@\f3compress(1)\f1 .\" index@\f1directory: expand compressed files in a directory@@@\f3compress(1)\f1 .\" index@\f1directory: compress files in a directory@@@\f3compress(1)\f1 .\" .\" toc@\f3compress(1)\f1:\0\0\f4compress\f1, \f4compressdir\f1, \f4uncompress\f1, \f4uncompressdir\f1, \f4zcat\f1@@@compress and expand data .\" toc@\f4uncompress\f1 \- expand compressed data@@@see \f3compress(1)\f1 .\" toc@\f4uncompressdir\f1 \- expand compressed files in a directory@@@see \f3compress(1)\f1 .\" toc@\f4compressdir\f1 \- compress files in a directory@@@see \f3compress(1)\f1 .\" toc@\f4zcat\f1: expand and cat data@@@see \f3compress(1)\f1 .\" .\" links@compress.1 uncompress.1 .\" links@compress.1 zcat.1 .\" links@compress.1 compressdir.1 .\" links@compress.1 uncompressd.1 .\" .\" $Header: compress.1,v 76.1 95/07/10 16:56:11 ssa Exp $ .TA c .TH compress 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compress, uncompress, zcat, compressdir, uncompressdir \- compress and expand data .SH SYNOPSIS .SS Compress Files .C compress .RC [ -d ] .RC [ -f|-z ] .RC [ -z ] .RC [ -v ] .RC [ -c ] .RC [ -V ] .RC [ -b .IR maxbits \|] .RI [ \|file \0...\|] .br .C uncompress .RC [ -f ] .RC [ -v ] .RC [ -c ] .RC [ -V ] .RI [ \|file \0...\|] .br .C zcat .RC [ -V ] .RI [ \|file \0...\|] .SS Compress Entire Directory Subtrees .C compressdir .RI [ \|options\| ] .RI [ \|directory \0...\|] .br .C uncompressdir .RI [ \|options\| ] .RI [ \|directory \0...\|] .SH DESCRIPTION The following commands compress and uncompress files and directory subtrees as indicated: .RS .TP 20 .C compress Reduce the size of the named .IR file s using adaptive Lempel-Ziv coding. If reduction is possible, each .I file is replaced by a new file of the same name with the suffix .CR .Z added to indicate that it is a compressed file. Original ownership, modes, access, and modification times are preserved. If no .I file is specified, or if .CR - is specified, standard input is compressed to the standard output. .TP .C uncompress Restore the compressed .IR file s to original form. Resulting files have the original filename, ownership, and permissions, and the .CR .Z filename suffix is removed. If no .I file is specified, or if .CR - is specified, standard input is uncompressed to the standard output. .TP .C zcat Restore the compressed .IR file s to original form and send the result to standard output. If no .I file is specified, or if .CR - is specified, standard input is uncompressed to the standard output. .TP .C compressdir Front-end processor. Recursively descend each specified .I directory subtree and use .CR compress to compress each file in .IR directory . Existing files are replaced by a compressed file having the same name plus the suffix .CR .Z , provided the resulting file is smaller than the original. If no directories are specified, compression is applied to all files starting with the current directory. .IP .I options may include any valid .CR compress command options (they are passed through to .CR compress ). To force compression of all files, even when the result is larger than the original file, use the .CR -f option. .TP .C uncompressdir Opposite of .CR compressdir . Restore compressed files to their original form. .I options may include any valid .CR uncompress command options (they are passed through to .CR uncompress ). .RE .PP The amount of compression obtained depends on the size of the input, the maximum number of bits .RI ( maxbits ) per code, and the distribution of common substrings. Typically, text such as source code or English is reduced by 50-60 percent. Compression is generally much better than that achieved by Huffman coding (as used in .CR pack ), or adaptive Huffman coding .RC ( compact ), and takes less time to compute. .SS Options These commands recognize the following options in the combinations shown above in .SM SYNOPSIS: .RS .TP 20 .C -d Decompress .IR file . .CR "compress -d" is equivalent to .CR uncompress . .TP .C -f Force compression of .IR file . This is useful for compressing an entire directory, even if some of the files do not actually shrink. If .CR -f is not given and .CR compress is run in the foreground, the user is prompted as to whether an existing file should be overwritten. .TP .C -z This is the same as the .C -f option except that it does not force compression when there is null compression. .TP .C -v Print a message describing the percentage of reduction for each file compressed. .TP .C -c Force .CR compress and .CR uncompress to write to the standard output; no files are changed. The nondestructive behavior of .CR zcat is identical to that of .CR "uncompress -c" . .TP .C -V Print the current version and compile options onto the standard error. .TP .CI -b \0maxbits Specify the maximum number of bits the .CR compress algorithm will use. The default is 16 and the range can be any integer between 9 and 16. .RE .PP .C compress uses the modified Lempel-Ziv algorithm popularized in .I "A Technique for High Performance Data Compression", Terry A. Welch, .I "IEEE Computer," vol. 17, no. 6 (June 1984), pages 8-19. Common substrings in the file are first replaced by 9-bit codes 257 and up. When code 512 is reached, the algorithm switches to 10-bit codes and continues to use more bits until the limit specified by the .CR -b flag is reached (default 16). .PP After the .I maxbits limit is attained, .CR compress periodically checks the compression ratio. If it is increasing, .CR compress continues to use the existing code dictionary. However, if the compression ratio is decreasing, .CR compress discards the table of substrings and rebuilds it from scratch. This allows the algorithm to adapt to the next "block" of the file. .PP Note that the .CR -b flag is omitted for .CR uncompress since the .I maxbits parameter specified during compression is encoded within the output, along with a magic number to ensure that neither decompression of random data nor recompression of compressed data is attempted. .SS "Access Control Lists" .C compress retains a file's access control list when compressing and expanding data. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .CR compress , .CR uncompress , and .C zcat behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE These commands return the following values upon completion: .RS .TP 5 .C 0 Completed successfully. .PD 0 .TP .C 2 Last file is larger after (attempted) compression. .TP .C 1 An error occurred. .PD .RE .SH DIAGNOSTICS .TP .C "Usage: compress [-f|-z] [-dvcV] [-b maxbits] [file ...]" Invalid options were specified on the command line. .TP .C "Missing maxbits" .I maxbits must follow .CR -b . .TP .IC file ": not in compressed format" The file specified to .CR uncompress has not been compressed. .TP .IC file ": compressed with " xx "bits, can only handle " yy "bits" .I file was compressed by a program that could deal with a higher value of .I maxbits than the compress code on this machine. Recompress the file with a lower value of .IR maxbits . .TP .IC file ": already has .Z suffix -- no change" The file is assumed to be already compressed. Rename the file and try again. .TP .IC file ": filename too long to tack on .Z" The output file name, which is the source file name with a .CR .Z extension, is too long for the file system on which the source file resides. Make the source file name shorter and try again. .TP .C "file already exists; do you wish to overwrite (y or n)?" Respond .CR y if you want the output to replace the existing file; otherwise, respond .CR n . .TP .C "uncompress: corrupt input" A .CR SIGSEGV violation was detected which usually means that the input file has been corrupted. .TP .CI "Compression: " xx . xx % Percentage of the input saved by compression. (Relevant only for .CR -v .) .TP .C "-- not a regular file: unchanged" When the input file is not a regular file (a directory for example), it is left unaltered. .TP .CI "-- has " xx "other links: unchanged" The input file has links and has been left unchanged. See .IR ln (1) for more information. .TP .C "-- file unchanged" No savings is achieved by compression. The input remains unaltered. .SH EXAMPLES Compress the file named .CR zenith and print compression information to the terminal: .RS .IP .C compress -v zenith .RE .PP The terminal display shows either a line resembling .IP .C "zenith: Compression: 23.55% -- replaced with zenith.Z" .PP indicating that the compressed file is 23.55% smaller than the original, or a line resembling .IP .C "zenith: Compression: -12.04% -- file unchanged" .PP indicating that an additional 12.04% space must be used to compress the file. .PP Undo the compression by typing either of the following commands: .RS .IP .C uncompress zenith.Z .IP .C compress -d zenith.Z .RE .PP This restores file .CR zenith.Z to its original uncompressed form and name. .PP .CR uncompress will perform on standard input if no files are specified. For example, to list a compressed tar file: .RS .IP .C "uncompress -c arch.tar.Z | tar -tvf - " .RE .SH WARNINGS Although compressed files are compatible between machines with large memory, .CR -b 12 should be used for file transfer to architectures with a small process data space (64K bytes or less). .SS \s-1NFS\s0 Access control lists of networked files are summarized (as returned in .CR st_mode by .CR stat() , but not copied to the new file (see .IR stat (2)). .SH AUTHOR .C compress was developed by Joseph M. Orost, Kenneth E. Turkowski, Spencer W. Thomas, and James A. Woods. .SH FILES .TP .C *.Z Compressed file created by .CR compress and removed by .CR uncompress . .SH SEE ALSO compact(1), pack(1), acl(5). .SH STANDARDS CONFORMANCE .CR compress ": XPG4" .\" index@\f4compress\f1, \f4uncompress\f1, \f4zcat\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4uncompress\f1, \f4compress\f1, \f4zcat\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4zcat\f1, \f4compress\f1, \f4uncompress\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4compressdir\f1, \f4uncompressdir\f1 \- compress or expand files in a directory@@@\f3compress(1)\f1 .\" index@\f4uncompressdir\f1, \f4compressdir\f1 \- compress or expand files in a directory@@@\f3compress(1)\f1 .\" index@\f1compress or expand data@@@\f3compress(1)\f1 .\" index@\f1expand or compress data@@@\f3compress(1)\f1 .\" index@\f1data, expand or compress@@@\f3compress(1)\f1 .\" index@\f1files: expand compressed files in a directory@@@\f3compress(1)\f1 .\" index@\f1files: expand compressed file@@@\f3compress(1)\f1 .\" index@\f1files: compress files in a directory@@@\f3compress(1)\f1 .\" index@\f1files: compress data in a file@@@\f3compress(1)\f1 .\" index@\f1directory: expand compressed files in a directory@@@\f3compress(1)\f1 .\" index@\f1directory: compress files in a directory@@@\f3compress(1)\f1 .\" .\" toc@\f3compress(1)\f1:\0\0\f4compress\f1, \f4compressdir\f1, \f4uncompress\f1, \f4uncompressdir\f1, \f4zcat\f1@@@compress and expand data .\" toc@\f4uncompress\f1 \- expand compressed data@@@see \f3compress(1)\f1 .\" toc@\f4uncompressdir\f1 \- expand compressed files in a directory@@@see \f3compress(1)\f1 .\" toc@\f4compressdir\f1 \- compress files in a directory@@@see \f3compress(1)\f1 .\" toc@\f4zcat\f1: expand and cat data@@@see \f3compress(1)\f1 .\" .\" links@compress.1 uncompress.1 .\" links@compress.1 zcat.1 .\" links@compress.1 compressdir.1 .\" links@compress.1 uncompressd.1 .\" .\" $Header: expand.1,v 76.3 95/08/07 11:34:26 ssa Exp $ .TA e .TH expand 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME expand, unexpand \- expand tabs to spaces, and vice versa .SH SYNOPSIS .C expand .RC [ -t .IR tablist\| ] .RI [ \|file \0...\|] .PP .br .C unexpand .RC [ -a ] .RC [ -t .IR tablist\| ] .RI [ \|file \0...\|] .SS Obsolescent: .C expand .RC [ -\c .IR tabstop\| ] .RC [ -\c .IC tab1 , tab2 ,\c .RC ... , .IR tabn\| ] .RI [ \|file \0...\|] .SH DESCRIPTION .C expand processes the named files or the standard input and writes to the standard output with tabs changed into spaces. Backspace characters are preserved in the output, and the column count is decreased by one column for tab calculations. For proper tab calculation, if a multi-column character is to be "backspace'd", it should be followed by multiple backspace characters which equal to it's column width. If a tab character is found after the last tab position, it is replaced by a single space. .C expand is useful for preprocessing character files that contain tabs (before sorting, looking at specific columns, etc). .PP .C expand recognizes the following command-line options and arguments: .RS .TP 15 .RC [ -t \0\f2tablist\fP\|] .I tablist specifies where to set the tab positions instead of the default .CR 8 . .I tablist can take two forms. If it is a single number, tabs are set .I tablist spaces apart. .I tablist can also be a blank- or comma-separated list of increasing positions where tabs are to be set. .TP .RC [ - \f2tabstop\fP\|] This option is obsolescent and is equivalent to using .CI -t \0tabstop\f1. .TP .RC [ -\s-1\f2tab1\fP,\f2tab2\fP,\f1...\fP,\f2tabn\fP\s0\| ] This option is obsolescent and is equivalent to using .C -t .IR tab1 , tab2 ,\c .IC ... , tabn\f1. .RE .PP .C unexpand processes the named files or the standard input and writes to the standard output with spaces changed into tabs where possible. By default, only leading spaces and tabs are converted to maximal strings of tabs. The default tab position is every 8 characters. Backspace characters are preserved into the output, and the column count is decreased by one column for tab calculations. For proper tab calculation, if a multi-column character is to be "backspace'd", it should be followed by multiple backspace characters which equal to it's column width. .PP .C unexpand recognizes the following command-line options and arguments: .RS .TP 15 .C -a Tabs are inserted whenever they would compress the resultant file by replacing two or more spaces before a tab position. .TP .BI \-t \0tablist .I tablist specifies the tab positions. .I tablist can take two forms. If it is a single number, tabs are set every .I tablist spaces apart. If .I tablist is a blank- or comma-separated list of increasing positions, tabs are set at those locations. The .C -t option implies the .C -a option. If the .C -t option is not specified, the default is equivalent to specifying .C -t 8 except that .C -a is not implied for this case. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text as single and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C expand and .C unexpand behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported with the exception that .C unexpand do not recognize multi-byte alternative space characters. .SH STANDARDS CONFORMANCE .CR expand ": XPG4, POSIX.2" .PP .CR unexpand ": XPG4, POSIX.2" .\" .\" toc@\f3expand(1)\f1:\0\0\f4expand\f1, \f4unexpand\f1@@@expand tabs to spaces, and vice versa .\" toc \f4unexpand\f1: convert spaces to tabs see \f3expand(1)\f1 .\" .\" index@\f4expand\f1, \f4unexpand\f1 \- expand tabs to spaces, and vice versa@@@\f3expand(1)\f1 .\" index@\f4unexpand\f1, \f4expand\f1 \- expand tabs to spaces, and vice versa@@@\f3expand(1)\f1 .\" index@\f1convert tabs to spaces, and vice versa@@@\f3expand(1)\f1 .\" index@\f1tabs, convert to spaces and vice versa@@@\f3expand(1)\f1 .\" index@\f1spaces, convert to tabs and vice versa@@@\f3expand(1)\f1 .\" .\" links@expand.1 unexpand.1 .\" .\" $Header: unget.1,v 76.1 95/07/10 17:12:48 ssa Exp $ .\" Copyright Hewlett-Packard Company .TA u .TH unget 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME unget \- undo a previous get of an SCCS file .SH SYNOPSIS .C unget .RC [ -r .SM .I SID\c ] .RC [ -s ] .RC [ -n ] .IR file \0... .SH DESCRIPTION The .CR unget command undoes the effect of a .CR "get -e" done prior to creating the intended new delta. If .IR file is a directory name, .CR unget treats each file in the directory as a file to be processed, except that non-\c .SM SCCS files and unreadable files are silently ignored. If .CR - is specified for .IR file , the standard input is read with each line being taken as the name of an .SM SCCS file to be processed. Refer to .IR sact (1), which describes how to determine what deltas are currently binding for an s-file. .SS Options .CR unget recognizes the following options and command-line arguments. Options and arguments apply independently to each named .IR file . .RS .TP 12 .CI -r \0SID Uniquely identifies which delta is no longer wanted (this would have been specified by .CR get as the ``new delta''). This option is necessary only if two or more outstanding .CR get s for editing on the same .SM SCCS file were done by the same person (login name). .CR unget prints a diagnostic message if the specified .SM .I SID is ambiguous, or if it is required but not present on the command line (see .IR sact (1)). .TP .C -s Silent option. Suppress printing the intended delta's .SM .I SID on the standard output. .TP .C -n Retain the file deposited in the current directory by the previous .CR get . Normally this file is removed by .CR unget . .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C unget behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH DIAGNOSTICS Use .IR sccshelp (1) for explanations. .SH WARNINGS Only the user who did the corresponding .CR "get -e" can execute .CR unget . Any other user must either use .CR su to change user .SM ID to that user (see .IR su (1)), or edit the .IR p-file directly (which can be done either by the .IR s-file owner or a user who has appropriate privileges). .SH FILES .TP 20 .IR p-file See .IR delta (1). .PD 0 .TP .IR g-file See .IR delta (1). .PD .SH SEE ALSO delta(1), get(1), sccshelp(1), sact(1). .SH STANDARDS CONFORMANCE .CR unget ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4unget\f1 \- undo a previous get of an SCCS file@@@\f3unget(1)\f1 .\" index@\f1SCCS: undo a previous get of an SCCS file@@@\f3unget(1)\f1 .\" index@\f1undo a previous get of an SCCS file@@@\f3unget(1)\f1 .\" index@\f1previous get of an SCCS file, undo a@@@\f3unget(1)\f1 .\" index@\f1get of an SCCS file, undo a previous@@@\f3unget(1)\f1 .\" index@\f1files: undo a previous get of an SCCS file@@@\f3unget(1)\f1 .\" .\" toc@\f3unget(1)\f1:\0\0\f4unget\f1@@@undo a previous get of an \s-1SCCS\s+1 file .\" .\" $Header: unifdef.1,v 72.4 94/08/26 16:08:24 ssa Exp $ .TA u .TH unifdef 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME unifdef \- remove preprocessor lines .SH SYNOPSIS .C unifdef .RC [ -clt ] .RC [\|[ -D .IR sym\| ] .RC [ -U .IR sym\| ] .RC [ -iD .IR sym\| ] .RC [ -iU .IR sym\| ]\|]\0...\0 .RI [ \|file\| ] .SH DESCRIPTION .C unifdef simulates some of the actions of .C cpp in interpreting C language preprocessor command lines (see .IR cpp (1)). For .CR unifdef , a valid preprocessor command line contains as its first character a .C # and one of the following keywords: .CR ifdef , .CR ifndef , .CR if , .CR else , or .CR endif . The .C # character and its associated keyword must appear on the same line, but they can be separated by spaces, tabs, and commented text. When appropriate, the portions of code surrounded by and including the targeted preprocessor directives are removed, and the resultant text is written to the standard output. .PP Unlike .CR cpp , .C unifdef does not insert included files, interpret macros, or strip comment lines. This means, among other things, that .C #define and .C #undef macros occurring within the input text are not interpreted. .PP Since .C unifdef is language-independent, it can be used for processing source files for languages other than the C language. For example, .C unifdef can be used on F\s-2ORTRAN\s0 language source files, provided the C language preprocessor commands are used. .SS Options .C unifdef recognizes the following command-line options: .RS .TP 12 .C -c Complement the normal behavior by printing only the rejected lines. .TP .CI -iD sym Ignore text delimited by .C #ifdef .IR sym . In other words, text that would otherwise be affected by some action is not touched when found within the context of a preprocessor command using .IR sym . .TP .CI -iU sym Ignore text delimited by .C #ifndef .IR sym . .TP .C -l Replace rejected lines with blank lines in the text written to the standard output. .TP .C -t Treat the input source as plain text. C-language comment and quoting constructs are not recognized. .TP .CI -D sym Define symbol .IR sym . .TP .CI -U sym Cause symbol .I sym to be undefined. .RE .SH RETURN VALUE The .CR unifdef command returns the following exit values: .RS .TP 12 0 Output is an exact copy of the input. .TP 1 Output is not an exact copy of the input. .TP 2 The .CR unifdef command fails. The failure might be due to a premature EOF or to an inappropriate .CR else , .CR elif , or .CR endif . .RE .SH EXAMPLES Assume file .C foo.f contains the following: .nf .IP .C " PROGRAM TEST1" .C " INTEGER I, J" .C "#ifdef ANSI77" .C " DO I=1,10" .C "#else" .C " DO 100 I=1,10" .C "#endif" .C " J=J+1" .C "#if defined (DEBUG) || defined (TEST)" .C " PRINT *,J" .C "#endif" .C "#ifdef ANSI77" .C " ENDDO" .C "#else" .C " 100 CONTINUE" .C "#endif" .C " END" .fi .PP The command sequence: .IP .C "unifdef -DANSI77 -UDEBUG -DTEST foo.f > /tmp/foo.f" .PP produces the following result in file .CR /tmp/foo.f : .nf .IP .C PROGRAM TEST1 .C INTEGER I, J .C DO I=1,10 .C J=J+1 .C PRINT *,J .C ENDDO .C END .fi .SH WARNINGS Any symbol name defined in the file must be specified in the .CR unifdef command line; otherwise, .CR unifdef will ignore the line. .SH AUTHOR .C unifdef was developed in the public domain. .SH SEE ALSO cpp(1). .\" .\" index@\f4unifdef\f1 \- remove preprocessor lines@@@\f3unifdef(1)\f1 .\" index@text processors: remove preprocessor lines@@@\f3unifdef(1)\f1 .\" index@remove preprocessor lines@@@\f3unifdef(1)\f1 .\" index@preprocessor lines, remove@@@\f3unifdef(1)\f1 .\" index@lines, remove preprocessor@@@\f3unifdef(1)\f1 .\" .\" toc@\f3unifdef(1)\f1:\0\0\f4unifdef\f1@@@remove preprocessor lines .\" $Header: uniq.1,v 76.1 95/08/23 17:47:48 ssa Exp $ .TA u .TH uniq 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uniq \- report repeated lines in a file .SH SYNOPSIS .C uniq .RC [ -udc .RC [ -f .IR fields\| ] .RC [ -s .IR chars\| ] .RI [ \|input_file .RI [ \|output_file\| ]\|] .SH DESCRIPTION .C uniq reads the input text file .IR input_file , comparing adjacent lines, and copies the result to .IR output_file . If .I input_file is not specified, the standard input and standard output are used. If .I input_file is specified, but .I output_file is not, results are printed to standard output. .I input_file and .I output_file must not be the same file. .SS Line-Comparison Options .C uniq recognizes the following options when comparing adjacent lines: .RS .TP 8 .C -u Print .I only those lines that are .I not repeated in the original file. .TP .C -d Print .I one copy only of each repeated line in the input file. .TP .C -c Generate an output report in default style except that each line is preceded by a count of the number of times it occurred. If this option is specified, the .C -u and .C -d options are ignored if either or both are also present. .RE .PP If none of the options .CR u , .CR d , or .C c are present, .C uniq prints the results of the union of the .C -u and .C -d options, producing a copy of the original input file with the second and succeeding copies of any repeated lines removed. (Note that repeated lines must be adjacent in order to be found \(em see .IR sort (1)). .SS Field-Skip Options .PP Two options are provided for skipping an initial portion of each line when making comparisons: .RS .TP 15 .CI -f \0fields Ignore the first .I fields fields, together with any blanks before each. .I fields is a positive decimal integer. A field is defined as a string of non-space, non-tab characters separated by tabs and/or spaces from its neighbors. .TP .CI -s \0chars Ignore the first .I chars characters. .I chars is a positive decimal integer. Each line in the input is assumed to be terminated with a new line character for purposes of comparison. Fields are skipped before characters. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE must be equal to the value it had when the input files were sorted. .PP .C LC_CTYPE determines the interpretation of text within files as single- and/or multi-byte characters, and defines a space character when the .C -f or .C -s option is used. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .CR LC_COLLATE , .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C uniq behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE Exit values are: .RS .TP 8 .B \00 Successful completion. .PD 0 .TP .B >0 Error condition occurred. .RE .PD .SH AUTHOR .CR uniq was developed by OSF and HP. .SH SEE ALSO comm(1), sort(1). .SH STANDARDS CONFORMANCE .CR uniq ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4uniq\f1 \- report adjacent repeated lines in a file@@@\f3uniq(1)\f1 .\" index@files: report adjacent repeated lines in a file@@@\f3uniq(1)\f1 .\" index@files: eliminate adjacent repeated lines in a file@@@\f3uniq(1)\f1 .\" index@count adjacent repeated lines in a file@@@\f3uniq(1)\f1 .\" index@repeated (adjacent) lines in a file, count, extract, or eliminate@@@\f3uniq(1)\f1 .\" index@find adjacent repeated lines in a file@@@\f3uniq(1)\f1 .\" index@report adjacent repeated lines in a file@@@\f3uniq(1)\f1 .\" index@eliminate adjacent repeated lines in a file@@@\f3uniq(1)\f1 .\" index@lines in a file, report adjacent repeated@@@\f3uniq(1)\f1 .\" index@extract non-repeated lines from a file@@@\f3uniq(1)\f1 .\" .\" toc@\f3uniq(1)\f1:\0\0\f4uniq\f1@@@report repeated lines in a file .\" $Header: units.1,v 74.1 95/05/10 22:06:46 ssa Exp $ .TA u .TH units 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME units \- conversion program .SH SYNOPSIS .C units .RC [ - .IR file ] .SH DESCRIPTION .C units converts quantities expressed in various standard scales to their equivalents in other scales. It works interactively as follows: .RS .TP 20 .B System Prompt .B User Response .TP .C You have: .C inch .PD 0 .TP .C You want: .C cm .PD .RE .PP The system responds with two factors; one used if multiplying (preceded by .CR * ), the other if dividing (preceded by .CR / ): .IP .C * 2.540000e+00 .br .C / 3.937008e-01 .RE .PP After providing the conversion factors, .C units prompts for the next set of values. To terminate .CR units , press the interrupt character as defined for your login. .PP A quantity is specified as a multiplicative combination of units optionally preceded by a numeric multiplier. Powers are indicated by suffixed positive integers, and division by the usual sign: .RS .TP 20 .B System Prompt .B User Response .TP .C You have: .C 15 lbs force/in2 .PD 0 .TP .C You want: .C atm .PD .RE .PP The system responds with: .IP .C * 1.020689e+00 .br .C / 9.797299e-01 .PP .C units only does multiplicative scale changes; thus it can convert Kelvin to Rankine, but not Celsius to Fahrenheit. Most familiar units, abbreviations, and metric prefixes are recognized, together with a generous leavening of exotica and a few constants of nature including: .RS .PD 0 .TP 10 .C pi ratio of circumference to diameter .TP .C c speed of light .TP .C e charge on an electron .TP .C g acceleration of gravity .TP .C force same as .CR g , .TP .C mole Avogadro's number, .TP .C water pressure head per unit height of water, .TP .C au astronomical unit. .PD .RE .PP Units must be provided in lowercase only. .C pound is not recognized as a unit of mass; .C lb is. Compound names are run together, (e.g., .ift .nh .CR lightyear ). .ift .hy British units that differ from their .SM U.S.\& counterparts are prefixed thus: .CR brgallon . For a complete list of units, examine the file: .IP .C /usr/share/lib/unittab .PP An alternate unit database file can be specified for use with the .CI - \0file option. .C units looks in this file rather than the default .C /usr/share/lib/unittab for the table of conversions. This must be in the same format as .CR /usr/share/lib/unittab . This is useful in defining your own units and conversions. .SH WARNINGS The monetary exchange rates are out of date. .SH FILES .C /usr/share/lib/unittab .\" index@\f4units\f1 \- convert units of measure@@@\f3units(1)\f1 .\" index@convert units of measure@@@\f3units(1)\f1 .\" index@units of measure, convert@@@\f3units(1)\f1 .\" index@measure, convert units of@@@\f3units(1)\f1 .\" index@metric system, convert units to or from@@@\f3units(1)\f1 .\" .\" toc@\f3units(1)\f1:\0\0\f4units\f1@@@conversion program .\" .\" fileset_database@units.1 USER-CMDS-MAN .\" $Header: pack.1,v 72.4 94/11/14 15:20:30 ssa Exp $ .TA p .TH pack 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pack, pcat, unpack \- compress and expand files .SH SYNOPSIS .C pack .RC [ - ] .RC [ -f ] .IR name \0... .PP .C pcat .IR name \0... .PP .C unpack .IR name \0... .SH DESCRIPTION .C pack attempts to store the specified files in a compressed form. Wherever possible, each input file .I name is replaced by a packed file .IC name .z with the same ownership, modes, and access and modification times. The .C -f option forces packing of .IR name . This is useful for causing an entire directory to be packed even if some of the files do not benefit. If .C pack is successful, .I name is removed. Packed files can be restored to their original form using .C unpack or .CR pcat . .PP .C pack uses Huffman (minimum redundancy) codes on a byte-by-byte basis. If the .C - argument is used, an internal flag is set that causes the number of times each byte is used, its relative frequency, and the code for the byte to be printed on the standard output. Additional occurrences of .C - in place of .I name cause the internal flag to be set and reset. .PP The amount of compression obtained depends on the size of the input file and the character frequency distribution. Because a decoding tree forms the first part of each .C .z file, it is usually not worthwhile to pack files smaller than three blocks unless the character frequency distribution is very skewed such as in printer plots or pictures. .PP Typically, text files are reduced to 60-75% of their original size. Load modules, which use a larger character set and have a more uniform distribution of characters, show little compression, the packed versions being about 90% of the original size. .PP .C pack returns a value that is the number of files that it failed to compress. .PP No packing occurs if: .RS .TP 3 \(bu The file appears to be already packed. .PD 0 .TP \(bu The file name has more than 12 characters and the file system is configured as a short filename system. .TP \(bu The file has links. .TP \(bu The file is a directory. .TP \(bu The file cannot be opened. .TP \(bu The file is empty. .TP \(bu No disk storage blocks will be saved by packing. .TP \(bu A file called .IC name .z already exists. .TP \(bu The .C .z file cannot be created. .TP \(bu An I/O error occurred during processing. .RE .PD .PP On short-filename systems, the last segment of the file name must contain no more than 12 characters to allow space for the appended .C .z extension. Directories cannot be compressed. .PP .C pcat does for packed files what .IR cat (1) does for ordinary files, except that .C pcat cannot be used as a filter. The specified files are unpacked and written to the standard output. Thus to view a packed file named .IC name .z use: .IP .C pcat name.z .PP or simply: .IP .C pcat name .PP To make an unpacked copy (named .IR file ) of a packed file named .IC name .z without destroying .IC name .z\f1) use the command: .IP .C pcat name >file .PP .C pcat returns the number of files it was unable to unpack. Failure may occur if: .RS .TP 3 \(bu The file name (exclusive of the .CR .z ) has more than 12 characters; .PD 0 .TP \(bu The file cannot be opened; .TP \(bu The file does not appear to have been created by .IR pack . .RE .PD .PP .C unpack expands files created by .CR pack . For each file .I name specified in the command, a search is made for a file called .IC name .z (or just .I name if .I name ends in .CR .z ). If this file appears to be a packed file, it is replaced by its expanded version. The new file has the .C .z suffix stripped from its name, and has the same access modes, access and modification dates, and owner as those of the packed file. .PP .C unpack returns a value that is the number of files it was unable to unpack. Failure may occur for the reasons given for .CR pcat , as well as for the following: .RS .TP 3 \(bu A file with the ``unpacked'' name already exists; .PD 0 .TP \(bu The unpacked file cannot be created. .RE .PD .SS "Access Control Lists (ACLs) .C pack retains all entries in a file's access control list when compressing and expanding it (see .IR acl (5)). .SH DEPENDENCIES .SS \s-1NFS\s0 Optional access control list entries of networked files are summarized (as returned in .C st_mode by .CR stat() , but not copied to the new file (see .IR stat (2)). .SH SEE ALSO cat(1), compact(1), compress(1), acl(5). .SH STANDARDS CONFORMANCE .CR pack ": SVID2, SVID3, XPG2, XPG3" .PP .CR pcat ": SVID2, SVID3, XPG2, XPG3" .PP .CR unpack ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4pack\f1 \- compress (pack) files using Huffman code (see \f4compact\f1(1)@@@\f3pack(1)\f1 .\" index@\f4pcat\f1 \- expand (unpack) and cat Huffman coded file (see \f4compact\f1(1)@@@\f3pack(1)\f1 .\" index@\f4unpack\f1 \- expand Huffman coded files created by \f4pack\f1 (see \f4compact\f1(1)@@@\f3pack(1)\f1 .\" .\" toc@\f3pack(1)\f1:\0\0\f4pack\f1, \f4pcat\f1, \f4unpack\f1@@@compress and expand files .\" toc@\f4pcat\f1: compress and expand files@@@see \f3pack(1)\f1 .\" toc@\f4unpack\f1: compress and expand files@@@see \f3pack(1)\f1 .\" .\" links@pack.1 pcat.1 .\" links@pack.1 unpack.1 .\" .\" fileset_database@pack.1 USER-CMDS-MAN .\" $Header: uptime.1,v 78.1 95/12/20 11:21:04 ssa Exp $ .TA u .TH uptime 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uptime, w \- show how long system has been up, and/or who is logged in and what they are doing .SH SYNOPSIS .CR uptime .RC [ -hlsuw ] .RC [ user ] .PP .CR w .RC [ -hlsuw ] .RC [ user ] .SH DESCRIPTION .CR uptime prints the current time, the length of time the system has been up, the number of users logged on to the system, and the average number of jobs in the run queue over the last 1, 5, and 15 minutes. .PP .CR w is linked to .CR uptime and prints the same output as .CR "uptime -w" , displaying a summary of the current activity on the system. .SS Options .CR uptime and .CR w recognize the following options: .RS .TP .CR -h Suppress the first line and the heading line. This option should not be used with the .CR -u option. This option assumes the use of the .CR -w option to .CR uptime . .RE .RS .TP .CR -l Use long output. This option assumes the use of the .CR -w option to .CR uptime . .RE .RS .TP .CR -s Use the short form of output for displaying terminal information. The terminal name is abbreviated; the login time and CPU times are suppressed. .RE .RS .TP .CR -u Print only the first line describing the overall state of the system. This is the default for the .CR uptime command. .RE .RS .TP .CR -w Print a summary of the current activity on the system for each user. This is the default for the .CR w command. .RE .SH EXAMPLES The command: .IP .CR uptime .PP produces text resembling the following: .IP .C "2:30pm up 14days, 2:39, 33 users, load average: 1.71, 1.88, 1.80" .PP depending upon the current status of the system. .SH AUTHOR .CR uptime was developed by the University of California, Berkeley. .\" .\" toc@\f3uptime(1)\f1:\0\0\f4uptime\f1, \f4w\f1@@@show how long system has been up .\" .\" index@\f4uptime\f1 \- show how long system has been up@@@\f3uptime(1)\f1 .\" index@\f4w\f1 \- show how long system has been up@@@\f3uptime(1)\f1 .\" index@show how long system has been up@@@\f3uptime(1)\f1 .\" index@system up time, show@@@\f3uptime(1)\f1 .\" .\" links@uptime.1 w.1 .\" $Header: users.1,v 72.4 94/06/30 15:17:51 ssa Exp $ .TA u .TH users 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME users \- compact list of users who are on the system .SH SYNOPSIS .C users .SH DESCRIPTION .C users lists the login names of the users currently on the system in a compact, one-line format. .PP The login names are sorted in ascending collation order (see Environment Variables below). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the order in which the output is sorted. .PP If .C LC_COLLATE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default. If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .I users behaves as if all internationalization variables are set to ``C'' (see .IR environ (5)). .SH AUTHOR .C users was developed by the University of California, Berkeley and HP. .SH FILES .C /etc/utmp .SH SEE ALSO who(1). .\" .\" toc@\f3users(1)\f1:\0\0\f4users\f1@@@compact list of users who are on the system .\" .\" index@\f4users\f1 \- compact list of users currently on the system@@@\f3users(1)\f1 .\" index@compact list of users currently on the system@@@\f3users(1)\f1 .\" index@list users currently on the system@@@\f3users(1)\f1 .\" index@users currently on the system, list@@@\f3users(1)\f1 .\" index@system, list users currently on the@@@\f3users(1)\f1 .\" .\" fileset_database@users.1 USER-CMDS-MAN .\" $Header: uucp.1,v 72.6 94/11/14 15:22:12 ssa Exp $ .TA u .TH uucp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uucp, uulog, uuname \- UNIX system to UNIX system copy .SH SYNOPSIS .C uucp .RI [ \|options\| ] .I source_files destination_file .PP .C uulog .CI -f " system" .RC [ -x\| ] .RC [ -\c .IR number\| ] .PP .C uulog .RC [ -s .IR system\| ]\0... .RC [ -x\| ] .RC [ -\c .IR number\| ] .PP .C uuname .RC [ -l ] .SH DESCRIPTION .SS uucp .C uucp copies files named by the .I source_files argument to the destination identified by the .I destination_file argument. When copying files to or from a remote system, .I source_files and .I destination_file can be a path name on the local system, or have the form: .IP .IC system_name ! path_name .PP where .I system_name is the name of a remote system in a list of system names known to .CR uucp . When copying files to (but not from) a remote system, .I system_name can also be a chained list of remote system names such as: .IP .IC system_name ! system_name ! ... !\c .IC system_name ! path_name .PP in which case an attempt is made to send the file, via the specified route, to the destination. Care should be taken to ensure that intermediate nodes in the route are configured to forward information (see .SM WARNINGS below for restrictions). .PP The shell metacharacters .CR ? , .C \(** and .C [\|.\|.\|.\|] appearing in .I path_name are expanded on the appropriate system. .PP .I path_name can be one of: .RS .TP 3 \(bu A full path name. .TP \(bu A path name preceded by .CI ~ user where .I user is a login name on the specified system and .CI ~ user is replaced by that user's login directory. (If an invalid login is specified, the default public directory .RC ( /var/spool/uucppublic ) is used instead. .TP \(bu A path name preceded by .CI ~/ destination where .I destination is appended to .CR /var/spool/uucppublic . .IP NOTE: This destination is treated as a file name unless more than one file is being transferred by this request or the destination is already a directory. To ensure that .I destination is a directory, append a .C / to the destination argument. For example, .C ~/dan/ as the destination argument causes directory .C /var/spool/uucppublic/dan to be created if it does not already exist, and places the requested file or files in that directory. .TP \(bu Anything else is prefixed by the current directory. .RE .PP If an erroneous path name is specified for the remote system, the copy fails. If .I destination_file is a directory, the file-name part of the .I source_file argument is used. .PP .C uucp preserves execute permissions across the transmission and sets read and write permissions to 0666 (see .IR chmod (2) and Access Control Lists below). .SS Options .C uucp recognizes the following options: .RS .TP 15 .C -c Do not copy local file to the spool directory for transfer to the remote machine (default). .TP .C -C Force the copy of local files to the spool directory for transfer. .TP .C -d Make all necessary directories for the file copy (default). .TP .C -f Do not make intermediate directories for the file copy. .TP .CI -g grade .I grade is a single letter or number. A lower .SM ASCII sequence value for .I grade causes the job to be transmitted earlier in a given conversation between systems. .TP .C -j Output the .SM ASCII job identification string on standard output. This job identification can be used by .C uustat to obtain the status or terminate a job (see .IR uustat (1)). .TP .CI -m file Send mail to the requester when the copy is completed. .TP .CI -n user Notify .I user on the remote system that a file was sent. .TP .C -r Do not start the file transfer; just queue the job. .TP .CI -s file Report status of the transfer to .IR file . Note that .I file must be a full path name. .TP .CI -x debug_level Produce debugging on standard output. .I debug_level is a number between 0 and 9; higher numbers give more information. .RE .SS uulog .C uulog queries a log file of .CR uucp transactions in a file .C /var/uucp/.Log/uucico/\c .IR system . .PP The following options cause .C uulog to print logging information: .RS .TP 15 .CI -s " system" Print information about work involving .IR system . .TP .CI -f " system" Do a .C tail -f (see .IR tail (1)) of the file transfer log for .IR system . .RE .PP Other options used in conjunction with the .C -s and .C -f options above are: .RS .TP 15 .CI -x Search for the given system in the .CI /var/uucp/.Log/uuxqt/ system file instead of in the .I uucico log file. .TP .CI - number Do a .IR tail (1) command of .I number lines. .RE .SS uuname .C uuname lists the .C uucp names of known systems. .C uuname -l returns the local system's default name. .SS Access Control Lists (\s-1ACL\s0s) A file's optional .SM ACL entries are not preserved across .C uucp transmission. Instead, new files have a summary of the access modes (as returned in .C st_mode by .CR stat() ; see .IR stat (2)). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_TIME determines the format and contents of date and time strings displayed by .C uucp and .C uulog commands. .PP .C LANG determines the language in which messages are displayed by .C uucp and .C uuname commands. .PP If .C LC_TIME is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR uucp , .CR uulog , and .C uuname behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported with the exception that multi-byte-character file names are not supported. .SH WARNINGS The domain of remotely accessible files can (and for obvious security reasons, usually should) be severely restricted. In most cases, you cannot fetch files by path name from a remote system. Ask a responsible person on the remote system to send them to you. For the same reasons, you probably cannot send files to arbitrary path names. As distributed, remotely accessible files are those whose names begin .C /var/spool/uucppublic (equivalent to .CR ~/ ). .PP All files received by .C uucp are owned by .CR uucp . .PP The .C -m option only works when sending files or when receiving a single file. Receiving multiple files specified by special shell characters .C ? * .CR [ \|...\| ] does not activate the .C -m option. .PP Protected files and files in protected directories owned by the requester can be sent by .CR uucp . However, if the requester is root and the directory is not searchable by .C other or the file is not readable by .CR other , the request fails. .PP .SH FILES .PD 0 .TP 25 .C /etc/uucp configuration files .TP .C /var/uucp log and error files .TP .C /var/spool/uucp spool directories .TP .C /var/spool/locks lock files .TP .C /var/spool/uucppublic public directory for receiving and sending .PD .SH SEE ALSO mail(1), uux(1), chmod(2), stat(2), acl(5). .PP .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .SH STANDARDS CONFORMANCE .CR uucp ": SVID2, SVID3, XPG2, XPG3" .PP .CR uulog ": SVID2, SVID3, XPG2, XPG3" .PP .CR uuname ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4uucp\f1, \f4uulog\f1, \f4uuname\f1 \- \s-1UNIX\s+1 system to \s-1UNIX\s+1 system copy@@@\f3uucp(1)\f1 .\" index@\f4uulog\f1 \- access \f4uucp\f1 and \f4uux\f1 transactions summary log@@@\f3uucp(1)\f1 .\" index@access \f4uucp\f1 and \f4uux\f1 transactions summary log@@@\f3uucp(1)\f1 .\" index@\f4uucp\f1 and \f4uux\f1 transactions summary log, access@@@\f3uucp(1)\f1 .\" index@summary log of \f4uucp\f1 and \f4uux\f1 transactions, access@@@\f3uucp(1)\f1 .\" index@log of \f4uucp\f1 and \f4uux\f1 transactions, access summary@@@\f3uucp(1)\f1 .\" index@\f4uux\f1 and \f4uucp\f1 transactions summary log, access@@@\f3uucp(1)\f1 .\" index@\f4uuname\f1 \- list names of known uucp systems@@@\f3uucp(1)\f1 .\" index@list names of known uucp systems@@@\f3uucp(1)\f1 .\" index@names of known uucp systems, list@@@\f3uucp(1)\f1 .\" index@known uucp systems, list names of@@@\f3uucp(1)\f1 .\" index@uucp systems, list names of known@@@\f3uucp(1)\f1 .\" index@systems, uucp, list names of known@@@\f3uucp(1)\f1 .\" .\" toc@\f3uucp(1)\f1:\0\0\f4uucp\f1, \f4uulog\f1, \f4uuname\f1@@@\s-1UNIX\s+1 system to \s-1UNIX\s+1 system copy .\" toc@\f4uulog\f1: access \s-1UUCP\s+1 summary logs@@@see \f3uucp(1)\f1 .\" toc@\f4uuname\f1: list known \s-1UUCP\s+1 systems@@@see \f3uucp(1)\f1 .\" .\" links@uucp.1 uulog.1 .\" links@uucp.1 uuname.1 .\" .\" fileset_database@uucp.1 USER-CMDS-MAN .\" $Header: uuencode.1,v 76.1 95/08/23 17:48:29 ssa Exp $ .TA u .TH uuencode 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uuencode, uudecode \- encode/decode a binary file for transmission by mailer .SH SYNOPSIS .C uuencode .RI [ \|source\| ] .I remotedest .br .C uudecode .RI [ \|file\| ] .SH DESCRIPTION .C uuencode and .C uudecode can be used to send a binary file to another machine by means of such services as .CR elm (1), .CR mailx (1), or .CR uucp (1) (see .IR elm (1), .IR mailx (1), and .IR uucp (1)). .PP .C uuencode takes the named source file (default standard input) and produces an encoded version on the standard output. The encoding uses only printing .SM ASCII characters, includes the original mode of the input file, and preserves the value of the remotedest argument which is the intended name for the file when it is restored later on the remote system. .PP .C uudecode reads an encoded file, ignores any leading and trailing lines added by mailers, and recreates the original file with the specified mode and name. .PP The encoded file is an ordinary .SM ASCII text file and can be edited with any text editor to change the mode or remote name. .SH EXAMPLES To encode and send a compiled program .C foo to user .CR friend : .IP .C "uuencode foo foo | mailx -s 'new program' friend" .PP After receiving the mail message, user .C friend can decode the program by first saving the message in a file .C foo.mail and executing the command: .IP .C "uudecode foo.mail" .SH WARNINGS The file is expanded by 35% (three bytes become four plus control information) causing it to take longer to transmit. .PP The user on the remote system who is invoking .C uudecode (often .CR uucp ) must have write permission for the specified file. .PP If an encoded file has the same name as the destination name specified in it, .C uudecode starts overwriting the encoded file before decoding is completed. .SH SEE ALSO elm(1), mail(1), mailx(1), shar(1), uucp(1), uux(1), uuencode(4). .SH STANDARDS CONFORMANCE .CR uuencode,uudecode ": XPG4, POSIX.2" .\" .\" toc@\f3uuencode(1)\f1:\0\0\f4uuencode\f1, \f4uudecode\f1@@@encode/decode a binary file for transmission by mailer .\" toc@\f4uudecode\f1 \- decode a file encoded by \f4uuencode\f1@@@see \f3uuencode(1)\f1 .\" .\" index@\f4uuencode\f1 \- encode a binary file for transmission by mailer@@@\f3uuencode(1)\f1 .\" index@encode a binary file for transmission by mailer@@@\f3uuencode(1)\f1 .\" index@\f4uudecode\f1 \- decode a file encoded by \f4uuencode\f1@@@\f3uuencode(1)\f1 .\" index@decode a file encoded by \f4uuencode\f1@@@\f3uuencode(1)\f1 .\" index@file: convert binary file to \s-1ASCII\s0 for transmission by mailer@@@\f3uuencode(1)\f1 .\" index@file: decode a file encoded by \f4uuencode\f1@@@\f3uuencode(1)\f1 .\" index@convert binary file to \s-1ASCII\s0 for transmission by mailer@@@\f3uuencode(1)\f1 .\" index@\s-1ASCII\s0, convert binary file to, for transmission by mailer@@@\f3uuencode(1)\f1 .\" index@binary file, convert to \s-1ASCII\s0 for transmission by mailer@@@\f3uuencode(1)\f1 .\" index@mailer, convert binary file to \s-1ASCII\s0 for transmission by@@@\f3uuencode(1)\f1 .\" .\" links@uuencode.1 uudecode.1 .\" .\" $Header: uuencode.1,v 76.1 95/08/23 17:48:29 ssa Exp $ .TA u .TH uuencode 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uuencode, uudecode \- encode/decode a binary file for transmission by mailer .SH SYNOPSIS .C uuencode .RI [ \|source\| ] .I remotedest .br .C uudecode .RI [ \|file\| ] .SH DESCRIPTION .C uuencode and .C uudecode can be used to send a binary file to another machine by means of such services as .CR elm (1), .CR mailx (1), or .CR uucp (1) (see .IR elm (1), .IR mailx (1), and .IR uucp (1)). .PP .C uuencode takes the named source file (default standard input) and produces an encoded version on the standard output. The encoding uses only printing .SM ASCII characters, includes the original mode of the input file, and preserves the value of the remotedest argument which is the intended name for the file when it is restored later on the remote system. .PP .C uudecode reads an encoded file, ignores any leading and trailing lines added by mailers, and recreates the original file with the specified mode and name. .PP The encoded file is an ordinary .SM ASCII text file and can be edited with any text editor to change the mode or remote name. .SH EXAMPLES To encode and send a compiled program .C foo to user .CR friend : .IP .C "uuencode foo foo | mailx -s 'new program' friend" .PP After receiving the mail message, user .C friend can decode the program by first saving the message in a file .C foo.mail and executing the command: .IP .C "uudecode foo.mail" .SH WARNINGS The file is expanded by 35% (three bytes become four plus control information) causing it to take longer to transmit. .PP The user on the remote system who is invoking .C uudecode (often .CR uucp ) must have write permission for the specified file. .PP If an encoded file has the same name as the destination name specified in it, .C uudecode starts overwriting the encoded file before decoding is completed. .SH SEE ALSO elm(1), mail(1), mailx(1), shar(1), uucp(1), uux(1), uuencode(4). .SH STANDARDS CONFORMANCE .CR uuencode,uudecode ": XPG4, POSIX.2" .\" .\" toc@\f3uuencode(1)\f1:\0\0\f4uuencode\f1, \f4uudecode\f1@@@encode/decode a binary file for transmission by mailer .\" toc@\f4uudecode\f1 \- decode a file encoded by \f4uuencode\f1@@@see \f3uuencode(1)\f1 .\" .\" index@\f4uuencode\f1 \- encode a binary file for transmission by mailer@@@\f3uuencode(1)\f1 .\" index@encode a binary file for transmission by mailer@@@\f3uuencode(1)\f1 .\" index@\f4uudecode\f1 \- decode a file encoded by \f4uuencode\f1@@@\f3uuencode(1)\f1 .\" index@decode a file encoded by \f4uuencode\f1@@@\f3uuencode(1)\f1 .\" index@file: convert binary file to \s-1ASCII\s0 for transmission by mailer@@@\f3uuencode(1)\f1 .\" index@file: decode a file encoded by \f4uuencode\f1@@@\f3uuencode(1)\f1 .\" index@convert binary file to \s-1ASCII\s0 for transmission by mailer@@@\f3uuencode(1)\f1 .\" index@\s-1ASCII\s0, convert binary file to, for transmission by mailer@@@\f3uuencode(1)\f1 .\" index@binary file, convert to \s-1ASCII\s0 for transmission by mailer@@@\f3uuencode(1)\f1 .\" index@mailer, convert binary file to \s-1ASCII\s0 for transmission by@@@\f3uuencode(1)\f1 .\" .\" links@uuencode.1 uudecode.1 .\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" * ...\" HP/DIGITAL CONFIDENTIAL ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** .wH ""(DCE RPC) .wH "(prod) -- DCE RPC" ...\" .rm zA .rm zZ .TH "uuidgen" "1" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "DCE RPC entity" "\*Luuidgen\*O command" ...\" .iX "\*Luuidgen\*O command" .iX "commands" "\*Luuidgen\*O" .iX "UUID" .iX "identifiers" "generator" .iX "identifiers" "\*Luuidgen\*O command" .iX "-: UUID" "Universal Unique Identifier" .wH "(prod) -- DCE RPC" .SH NAME .PP \*Luuidgen\*O - Generates a Universal Unique Identifier (UUID) .wH "" .SH "SYNOPSIS" .PP .sS \*Luuidgen\*O \*O[\*Vargument\*O] \&.\&.\&. .sE .wH "" .br .ne 1.5i .SH "Arguments" .PP .iX "\*Luuidgen\*O command" "arguments" .VL 2m .zA "def,11138,R1.1,add -c option" .LI "\*L\-c\*O" Allows you to supply an existing UUID that \*Luuidgen\*O then outputs in the format you specify. This option is especially useful in combination with the \*L-s\*O option for converting an existing UUID into a C structure. .PP You must specify the \*L-c\*O option at the end of the \*Luuidgen\*O command line; all options that follow \*L-c\*O are ignored. .zZ "def,11138,R1.1,add -c option" .LI "\*L\-i\*O" .iX "IDL" "file template" "\*Luuidgen\*O command" .iX "\*Luuidgen\*O command" "IDL" Produces an Interface Definition Language (IDL) file template and includes the generated UUID string in the template. .LI "\*L\-o \*Vfilename\*O" Redirects the generated UUID string to the file you specify. .LI "\*L\-s\*O" Generates a UUID string as an initialized C structure. .zA "def,10534,R1.1,remove NCS compatibility doc" ...\".LI "\*L\-t \*Vold_style_uuid_string\*O" ...\".iX "UUID" "old format" ...\".iX "UUID" "new format" ...\".iX "format for UUID" ...\"Translates the old\-style (NCS Version 1) UUID string format to ...\"the new\-style string format. .zZ "def,10534,R1.1,remove NCS compatibility doc" .LI "\*L\-v\*O" .iX "version number" "UUID generator" Displays the version number of the UUID generator, but does not generate a UUID. .iX "UUID" "version number" .LI "\*L\-h\*O" Displays information about the \*Luuidgen\*O command arguments. The arguments \*L\-h\*O and \*L\-?\*O can be used interchangeably. .LI "\*L\-?\*O" Displays information about the \*Luuidgen\*O command arguments. The arguments \*L\-?\*O and \*L\-h\*O can be used interchangeably. .LI "\*L\-n \*Vnumber_of_uuid_strings\*O" Generates a specified number of UUID strings. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Luuidgen\*O command creates a UUID string that you assign to an object to uniquely identify it. One such use is in the UUID interface attribute of an IDL interface definition. The format for representing a UUID string consists of eight hexadecimal digits followed by a dash, followed by three groups of four hexadecimal digits separated by dashes, followed by a dash and twelve hexadecimal digits: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS 01234567-89ab-cdef-0123-456789abcdef .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .br .ne 1.5i .SH "FILES" .PP The locations of files have the following pathnames: .iX "files" "\*Luuidgen\*O command" .VL 20m .LI "\*Edceshared\*L/bin/uuidgen\*O" Generator .LI "\*Edceshared\*L/nls/msg/\*ELANG\*L/uuidgen.cat\*O" Generator error messages .LE .PP .wH "" .br .ne 1.5i .SH "EXAMPLES" .PP .AL .LI Generate a UUID string: .iS \*C$\*L uuidgen .iE .zA "defect,6742,R1.0.2,lowercase UUIDs" .oS 23c67e00-71b6-11c9-9dfc-08002b0ecef1 .oE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .LI Generate a partial template, containing a generated UUID string, to be used to develop an interface definition: .iS \*C$\*L uuidgen -i .iE .zA "defect,6742,R1.0.2,lowercase UUIDs" .oS [ uuid(828bf780-71b6-11c9-b5a8-08002b0ecef1), version (1.0) ] interface INTERFACENAME { } .oE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .LI Convert a UUID string from the old\-style format to the new format: .iS \*C$\*L uuidgen -t 34DC23469EAF.AB.A2.01.7C.5F.2C.ED.A3 .iE .zA "defect,6742,R1.0.2,lowercase UUIDs" .oS 34dc2346-9eaf-0000-aba2-017c5f2ceda3 .oE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .LI Generate four UUID strings: .iS \*C$\*L uuidgen -n 4 .iE .zA "defect,6742,R1.0.2,lowercase UUIDs" .oS 612c0b00-71b8-11c9-973a-08002b0ecef1 612c0b01-71b8-11c9-973a-08002b0ecef1 612c0b02-71b8-11c9-973a-08002b0ecef1 612c0b03-71b8-11c9-973a-08002b0ecef1 .oE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .zA "def,11138,R1.1,add -c option" .LI Convert a UUID into a C structure: .iS \*C$\*L uuidgen -s -c 1251ace6-93al-11cd-95ad-0800097086e4 .iE .oS = { /* 1251ace6-93al-11cd-95ad-0800097086e4 */ 0x1251ace6, 0x93al, 0x11cd, 0x95, 0xad {0x08, 0x00, 0x09, 0x70, 0x86, 0xe4} }; .oE .zZ "def,11138,R1.1,add -c option" .LE .wH "" .\" $Header: uucp.1,v 72.6 94/11/14 15:22:12 ssa Exp $ .TA u .TH uucp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uucp, uulog, uuname \- UNIX system to UNIX system copy .SH SYNOPSIS .C uucp .RI [ \|options\| ] .I source_files destination_file .PP .C uulog .CI -f " system" .RC [ -x\| ] .RC [ -\c .IR number\| ] .PP .C uulog .RC [ -s .IR system\| ]\0... .RC [ -x\| ] .RC [ -\c .IR number\| ] .PP .C uuname .RC [ -l ] .SH DESCRIPTION .SS uucp .C uucp copies files named by the .I source_files argument to the destination identified by the .I destination_file argument. When copying files to or from a remote system, .I source_files and .I destination_file can be a path name on the local system, or have the form: .IP .IC system_name ! path_name .PP where .I system_name is the name of a remote system in a list of system names known to .CR uucp . When copying files to (but not from) a remote system, .I system_name can also be a chained list of remote system names such as: .IP .IC system_name ! system_name ! ... !\c .IC system_name ! path_name .PP in which case an attempt is made to send the file, via the specified route, to the destination. Care should be taken to ensure that intermediate nodes in the route are configured to forward information (see .SM WARNINGS below for restrictions). .PP The shell metacharacters .CR ? , .C \(** and .C [\|.\|.\|.\|] appearing in .I path_name are expanded on the appropriate system. .PP .I path_name can be one of: .RS .TP 3 \(bu A full path name. .TP \(bu A path name preceded by .CI ~ user where .I user is a login name on the specified system and .CI ~ user is replaced by that user's login directory. (If an invalid login is specified, the default public directory .RC ( /var/spool/uucppublic ) is used instead. .TP \(bu A path name preceded by .CI ~/ destination where .I destination is appended to .CR /var/spool/uucppublic . .IP NOTE: This destination is treated as a file name unless more than one file is being transferred by this request or the destination is already a directory. To ensure that .I destination is a directory, append a .C / to the destination argument. For example, .C ~/dan/ as the destination argument causes directory .C /var/spool/uucppublic/dan to be created if it does not already exist, and places the requested file or files in that directory. .TP \(bu Anything else is prefixed by the current directory. .RE .PP If an erroneous path name is specified for the remote system, the copy fails. If .I destination_file is a directory, the file-name part of the .I source_file argument is used. .PP .C uucp preserves execute permissions across the transmission and sets read and write permissions to 0666 (see .IR chmod (2) and Access Control Lists below). .SS Options .C uucp recognizes the following options: .RS .TP 15 .C -c Do not copy local file to the spool directory for transfer to the remote machine (default). .TP .C -C Force the copy of local files to the spool directory for transfer. .TP .C -d Make all necessary directories for the file copy (default). .TP .C -f Do not make intermediate directories for the file copy. .TP .CI -g grade .I grade is a single letter or number. A lower .SM ASCII sequence value for .I grade causes the job to be transmitted earlier in a given conversation between systems. .TP .C -j Output the .SM ASCII job identification string on standard output. This job identification can be used by .C uustat to obtain the status or terminate a job (see .IR uustat (1)). .TP .CI -m file Send mail to the requester when the copy is completed. .TP .CI -n user Notify .I user on the remote system that a file was sent. .TP .C -r Do not start the file transfer; just queue the job. .TP .CI -s file Report status of the transfer to .IR file . Note that .I file must be a full path name. .TP .CI -x debug_level Produce debugging on standard output. .I debug_level is a number between 0 and 9; higher numbers give more information. .RE .SS uulog .C uulog queries a log file of .CR uucp transactions in a file .C /var/uucp/.Log/uucico/\c .IR system . .PP The following options cause .C uulog to print logging information: .RS .TP 15 .CI -s " system" Print information about work involving .IR system . .TP .CI -f " system" Do a .C tail -f (see .IR tail (1)) of the file transfer log for .IR system . .RE .PP Other options used in conjunction with the .C -s and .C -f options above are: .RS .TP 15 .CI -x Search for the given system in the .CI /var/uucp/.Log/uuxqt/ system file instead of in the .I uucico log file. .TP .CI - number Do a .IR tail (1) command of .I number lines. .RE .SS uuname .C uuname lists the .C uucp names of known systems. .C uuname -l returns the local system's default name. .SS Access Control Lists (\s-1ACL\s0s) A file's optional .SM ACL entries are not preserved across .C uucp transmission. Instead, new files have a summary of the access modes (as returned in .C st_mode by .CR stat() ; see .IR stat (2)). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_TIME determines the format and contents of date and time strings displayed by .C uucp and .C uulog commands. .PP .C LANG determines the language in which messages are displayed by .C uucp and .C uuname commands. .PP If .C LC_TIME is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR uucp , .CR uulog , and .C uuname behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported with the exception that multi-byte-character file names are not supported. .SH WARNINGS The domain of remotely accessible files can (and for obvious security reasons, usually should) be severely restricted. In most cases, you cannot fetch files by path name from a remote system. Ask a responsible person on the remote system to send them to you. For the same reasons, you probably cannot send files to arbitrary path names. As distributed, remotely accessible files are those whose names begin .C /var/spool/uucppublic (equivalent to .CR ~/ ). .PP All files received by .C uucp are owned by .CR uucp . .PP The .C -m option only works when sending files or when receiving a single file. Receiving multiple files specified by special shell characters .C ? * .CR [ \|...\| ] does not activate the .C -m option. .PP Protected files and files in protected directories owned by the requester can be sent by .CR uucp . However, if the requester is root and the directory is not searchable by .C other or the file is not readable by .CR other , the request fails. .PP .SH FILES .PD 0 .TP 25 .C /etc/uucp configuration files .TP .C /var/uucp log and error files .TP .C /var/spool/uucp spool directories .TP .C /var/spool/locks lock files .TP .C /var/spool/uucppublic public directory for receiving and sending .PD .SH SEE ALSO mail(1), uux(1), chmod(2), stat(2), acl(5). .PP .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .SH STANDARDS CONFORMANCE .CR uucp ": SVID2, SVID3, XPG2, XPG3" .PP .CR uulog ": SVID2, SVID3, XPG2, XPG3" .PP .CR uuname ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4uucp\f1, \f4uulog\f1, \f4uuname\f1 \- \s-1UNIX\s+1 system to \s-1UNIX\s+1 system copy@@@\f3uucp(1)\f1 .\" index@\f4uulog\f1 \- access \f4uucp\f1 and \f4uux\f1 transactions summary log@@@\f3uucp(1)\f1 .\" index@access \f4uucp\f1 and \f4uux\f1 transactions summary log@@@\f3uucp(1)\f1 .\" index@\f4uucp\f1 and \f4uux\f1 transactions summary log, access@@@\f3uucp(1)\f1 .\" index@summary log of \f4uucp\f1 and \f4uux\f1 transactions, access@@@\f3uucp(1)\f1 .\" index@log of \f4uucp\f1 and \f4uux\f1 transactions, access summary@@@\f3uucp(1)\f1 .\" index@\f4uux\f1 and \f4uucp\f1 transactions summary log, access@@@\f3uucp(1)\f1 .\" index@\f4uuname\f1 \- list names of known uucp systems@@@\f3uucp(1)\f1 .\" index@list names of known uucp systems@@@\f3uucp(1)\f1 .\" index@names of known uucp systems, list@@@\f3uucp(1)\f1 .\" index@known uucp systems, list names of@@@\f3uucp(1)\f1 .\" index@uucp systems, list names of known@@@\f3uucp(1)\f1 .\" index@systems, uucp, list names of known@@@\f3uucp(1)\f1 .\" .\" toc@\f3uucp(1)\f1:\0\0\f4uucp\f1, \f4uulog\f1, \f4uuname\f1@@@\s-1UNIX\s+1 system to \s-1UNIX\s+1 system copy .\" toc@\f4uulog\f1: access \s-1UUCP\s+1 summary logs@@@see \f3uucp(1)\f1 .\" toc@\f4uuname\f1: list known \s-1UUCP\s+1 systems@@@see \f3uucp(1)\f1 .\" .\" links@uucp.1 uulog.1 .\" links@uucp.1 uuname.1 .\" .\" fileset_database@uucp.1 USER-CMDS-MAN .\" $Header: uucp.1,v 72.6 94/11/14 15:22:12 ssa Exp $ .TA u .TH uucp 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uucp, uulog, uuname \- UNIX system to UNIX system copy .SH SYNOPSIS .C uucp .RI [ \|options\| ] .I source_files destination_file .PP .C uulog .CI -f " system" .RC [ -x\| ] .RC [ -\c .IR number\| ] .PP .C uulog .RC [ -s .IR system\| ]\0... .RC [ -x\| ] .RC [ -\c .IR number\| ] .PP .C uuname .RC [ -l ] .SH DESCRIPTION .SS uucp .C uucp copies files named by the .I source_files argument to the destination identified by the .I destination_file argument. When copying files to or from a remote system, .I source_files and .I destination_file can be a path name on the local system, or have the form: .IP .IC system_name ! path_name .PP where .I system_name is the name of a remote system in a list of system names known to .CR uucp . When copying files to (but not from) a remote system, .I system_name can also be a chained list of remote system names such as: .IP .IC system_name ! system_name ! ... !\c .IC system_name ! path_name .PP in which case an attempt is made to send the file, via the specified route, to the destination. Care should be taken to ensure that intermediate nodes in the route are configured to forward information (see .SM WARNINGS below for restrictions). .PP The shell metacharacters .CR ? , .C \(** and .C [\|.\|.\|.\|] appearing in .I path_name are expanded on the appropriate system. .PP .I path_name can be one of: .RS .TP 3 \(bu A full path name. .TP \(bu A path name preceded by .CI ~ user where .I user is a login name on the specified system and .CI ~ user is replaced by that user's login directory. (If an invalid login is specified, the default public directory .RC ( /var/spool/uucppublic ) is used instead. .TP \(bu A path name preceded by .CI ~/ destination where .I destination is appended to .CR /var/spool/uucppublic . .IP NOTE: This destination is treated as a file name unless more than one file is being transferred by this request or the destination is already a directory. To ensure that .I destination is a directory, append a .C / to the destination argument. For example, .C ~/dan/ as the destination argument causes directory .C /var/spool/uucppublic/dan to be created if it does not already exist, and places the requested file or files in that directory. .TP \(bu Anything else is prefixed by the current directory. .RE .PP If an erroneous path name is specified for the remote system, the copy fails. If .I destination_file is a directory, the file-name part of the .I source_file argument is used. .PP .C uucp preserves execute permissions across the transmission and sets read and write permissions to 0666 (see .IR chmod (2) and Access Control Lists below). .SS Options .C uucp recognizes the following options: .RS .TP 15 .C -c Do not copy local file to the spool directory for transfer to the remote machine (default). .TP .C -C Force the copy of local files to the spool directory for transfer. .TP .C -d Make all necessary directories for the file copy (default). .TP .C -f Do not make intermediate directories for the file copy. .TP .CI -g grade .I grade is a single letter or number. A lower .SM ASCII sequence value for .I grade causes the job to be transmitted earlier in a given conversation between systems. .TP .C -j Output the .SM ASCII job identification string on standard output. This job identification can be used by .C uustat to obtain the status or terminate a job (see .IR uustat (1)). .TP .CI -m file Send mail to the requester when the copy is completed. .TP .CI -n user Notify .I user on the remote system that a file was sent. .TP .C -r Do not start the file transfer; just queue the job. .TP .CI -s file Report status of the transfer to .IR file . Note that .I file must be a full path name. .TP .CI -x debug_level Produce debugging on standard output. .I debug_level is a number between 0 and 9; higher numbers give more information. .RE .SS uulog .C uulog queries a log file of .CR uucp transactions in a file .C /var/uucp/.Log/uucico/\c .IR system . .PP The following options cause .C uulog to print logging information: .RS .TP 15 .CI -s " system" Print information about work involving .IR system . .TP .CI -f " system" Do a .C tail -f (see .IR tail (1)) of the file transfer log for .IR system . .RE .PP Other options used in conjunction with the .C -s and .C -f options above are: .RS .TP 15 .CI -x Search for the given system in the .CI /var/uucp/.Log/uuxqt/ system file instead of in the .I uucico log file. .TP .CI - number Do a .IR tail (1) command of .I number lines. .RE .SS uuname .C uuname lists the .C uucp names of known systems. .C uuname -l returns the local system's default name. .SS Access Control Lists (\s-1ACL\s0s) A file's optional .SM ACL entries are not preserved across .C uucp transmission. Instead, new files have a summary of the access modes (as returned in .C st_mode by .CR stat() ; see .IR stat (2)). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_TIME determines the format and contents of date and time strings displayed by .C uucp and .C uulog commands. .PP .C LANG determines the language in which messages are displayed by .C uucp and .C uuname commands. .PP If .C LC_TIME is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR uucp , .CR uulog , and .C uuname behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported with the exception that multi-byte-character file names are not supported. .SH WARNINGS The domain of remotely accessible files can (and for obvious security reasons, usually should) be severely restricted. In most cases, you cannot fetch files by path name from a remote system. Ask a responsible person on the remote system to send them to you. For the same reasons, you probably cannot send files to arbitrary path names. As distributed, remotely accessible files are those whose names begin .C /var/spool/uucppublic (equivalent to .CR ~/ ). .PP All files received by .C uucp are owned by .CR uucp . .PP The .C -m option only works when sending files or when receiving a single file. Receiving multiple files specified by special shell characters .C ? * .CR [ \|...\| ] does not activate the .C -m option. .PP Protected files and files in protected directories owned by the requester can be sent by .CR uucp . However, if the requester is root and the directory is not searchable by .C other or the file is not readable by .CR other , the request fails. .PP .SH FILES .PD 0 .TP 25 .C /etc/uucp configuration files .TP .C /var/uucp log and error files .TP .C /var/spool/uucp spool directories .TP .C /var/spool/locks lock files .TP .C /var/spool/uucppublic public directory for receiving and sending .PD .SH SEE ALSO mail(1), uux(1), chmod(2), stat(2), acl(5). .PP .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .SH STANDARDS CONFORMANCE .CR uucp ": SVID2, SVID3, XPG2, XPG3" .PP .CR uulog ": SVID2, SVID3, XPG2, XPG3" .PP .CR uuname ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4uucp\f1, \f4uulog\f1, \f4uuname\f1 \- \s-1UNIX\s+1 system to \s-1UNIX\s+1 system copy@@@\f3uucp(1)\f1 .\" index@\f4uulog\f1 \- access \f4uucp\f1 and \f4uux\f1 transactions summary log@@@\f3uucp(1)\f1 .\" index@access \f4uucp\f1 and \f4uux\f1 transactions summary log@@@\f3uucp(1)\f1 .\" index@\f4uucp\f1 and \f4uux\f1 transactions summary log, access@@@\f3uucp(1)\f1 .\" index@summary log of \f4uucp\f1 and \f4uux\f1 transactions, access@@@\f3uucp(1)\f1 .\" index@log of \f4uucp\f1 and \f4uux\f1 transactions, access summary@@@\f3uucp(1)\f1 .\" index@\f4uux\f1 and \f4uucp\f1 transactions summary log, access@@@\f3uucp(1)\f1 .\" index@\f4uuname\f1 \- list names of known uucp systems@@@\f3uucp(1)\f1 .\" index@list names of known uucp systems@@@\f3uucp(1)\f1 .\" index@names of known uucp systems, list@@@\f3uucp(1)\f1 .\" index@known uucp systems, list names of@@@\f3uucp(1)\f1 .\" index@uucp systems, list names of known@@@\f3uucp(1)\f1 .\" index@systems, uucp, list names of known@@@\f3uucp(1)\f1 .\" .\" toc@\f3uucp(1)\f1:\0\0\f4uucp\f1, \f4uulog\f1, \f4uuname\f1@@@\s-1UNIX\s+1 system to \s-1UNIX\s+1 system copy .\" toc@\f4uulog\f1: access \s-1UUCP\s+1 summary logs@@@see \f3uucp(1)\f1 .\" toc@\f4uuname\f1: list known \s-1UUCP\s+1 systems@@@see \f3uucp(1)\f1 .\" .\" links@uucp.1 uulog.1 .\" links@uucp.1 uuname.1 .\" .\" fileset_database@uucp.1 USER-CMDS-MAN .\" $Header: uupath.1,v 72.4 94/07/25 15:54:31 ssa Exp $ .TA u .TH uupath 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uupath, mkuupath \- access and manage the pathalias database .SH SYNOPSIS .C uupath .RC [ -f .IR pathsfile\| ] .I mailaddress .PP .C mkuupath .RC [ -v ] .I pathsfile .SH DESCRIPTION .C uupath provides electronic message routing by expanding a simple .SM UUCP address into a full .SM UUCP path (see .IR uucp (1)). For example, .IC host ! user could be expanded into .IC hostA ! hostB ! host\c .CI ! user\f1. .PP .C uupath expands an address by parsing .I mailaddress for the dominant host (see below) and looking up the host in the appropriate .C pathalias database (see .IR pathalias (1)). If the host is found in the database, the expanded address is written to the standard output. If the host is not found, .C uupath writes the original address to the standard output and returns an exit status of 1. .C uupath expects .I mailaddress to be in .SM UUCP format .RI ( host\c .CR ! ... !\c .IC hostZ ! user\f1) or .SM ARPANET format (\f2user\f3@\f2host\f1). .PP The .C -f option opens the .C pathalias database based on .I pathsfile rather than the default database based on .CR /usr/lib/mail/paths . This database must be a database created by .CR mkuupath , consisting of the two files .IC pathsfile .dir and .IC pathsfile .pag\f1. .PP The dominant host is the left-most .SM UUCP host in .IR mailaddress . If no .SM UUCP host is found (no .C ! is in the address), .C uupath assumes that the address is in the simple .SM ARPANET format \f2user\f3@\f2host\f1. If the address does not match either format, .C uupath writes the original address to the standard output and returns an exit status of 1. .PP .C mkuupath constructs a mail routing database by using the .I pathsfile data file obtained from .C pathalias (see .IR pathalias (1)). as input. The recommended .I pathsfile location is .CR /usr/lib/mail/paths , because this is the default database used by .CR uupath . The database files .IC pathsfile .dir and .IC pathsfile .pag are created by .CR mkuupath . If these files already exist, they must be removed prior to running .CR mkuupath . .PP The .C -v option specifies verbose mode, which writes a line to the standard output for each entry written to the database. .SH DIAGNOSTICS .C uupath returns an exit status of 1 and writes the original .I mailaddress to the standard output if the address is not found or is incorrectly formatted. .C uupath returns an exit status of 2 and prints a diagnostic message if the database files are not accessible, or if improper parameters are given. Otherwise, .C uupath returns an exit status of 0. .PP If the database files .IC pathsfile .dir and .IC pathsfile .pag already exist prior to running .CR mkuupath , the message .CI mkuupath: " pathsfile" ".dir: File exists" is displayed. These files must be removed before running .CR mkuupath . .SH AUTHOR .C uupath was developed by University of California, Berkeley. .SH FILES .nf .C /usr/lib/mail/paths .C /usr/lib/mail/paths.dir .C /usr/lib/mail/paths.pag .fi .SH SEE ALSO pathalias(1), uucp(1). .\" .\" index@\f4uupath\f1, \f4mkuupath\f1 \- access and manage the pathalias database@@@\f3uupath(1)\f1 .\" index@\f4mkuupath\f1, \f4uupath\f1 \- access and manage the pathalias database@@@\f3uupath(1)\f1 .\" index@access and manage the pathalias database@@@\f3uupath(1)\f1 .\" index@manage the pathalias database, access and@@@\f3uupath(1)\f1 .\" index@pathalias database, access and manage the@@@\f3uupath(1)\f1 .\" index@database, pathalias, access and manage the@@@\f3uupath(1)\f1 .\" .\" toc@\f3uupath(1)\f1:\0\0\f4uupath\f1, \f4mkuupath\f1@@@access and manage the pathalias database .\" toc@\f4mkuupath\f1: manage the pathalias database@@@see \f3uupath(1)\f1 .\" .\" links@uupath.1 mkuupath.1 .\" .\" fileset_database@uupath.1 USER-CMDS-MAN .\" $Header: uuto.1,v 76.1 95/08/07 10:13:15 ssa Exp $ .TA u .TH uuto 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uuto, uupick \- public UNIX system to UNIX system file copy .SH SYNOPSIS .C uuto .RI [ \|options\| ] .I source-files destination .br .C uupick .RC [ -s .IR system\| ] .SH DESCRIPTION .C uuto sends .I source-files to .IR destination . .C uuto uses the .C uucp facility to send files (see .IR uucp (1)), while allowing the local system to control the file access. A source-file name is a path name on your machine. Destination has the form: .IP .IC system ! user .PP where .I system is taken from a list of system names that .C uucp knows about (see .C uuname in .IR uucp (1) manual entry). .I user is the login name of someone on the specified system. .PP .C uuto recognizes the following options: .RS .TP 8 .C -p Copy the source file into the spool directory immediately, and send the copy. .TP .C -m Send mail to the requester when the copy is complete. .RE .PP The files (or sub-trees if directories are specified) are sent to .SM .I PUBDIR on .IR system , where .SM .I PUBDIR is the .SM UUCP public directory .RC ( /var/spool/uucppublic ). Specifically the files are sent to .IP .SM .I PUBDIR\c .CI /receive/ user / mysystem /files\f1. .PP The recipient is notified by electronic mail when the files arrive. .PP .C uupick accepts or rejects the files transmitted to the recipient. Specifically, .C uupick searches .SM .I PUBDIR for files destined for the user. For each entry (file or directory) found, the following message is printed on the standard output: .IP .C from .IC system : .RC [ file .IR file-name\| ] .RC [ dir .IR dirname\| ] .C ? .PP .C uupick then reads a line from the standard input to determine the disposition of the file: .RS .TP 16 Go on to next entry. .TP .C d Delete the entry. .TP .CR m \0[\|\f2dir\fP\|] Move the entry to named directory .I dir (current directory is default). Note that, if the current working directory is desired for .IR dir , do .I not specify any parameter with .CR m . A construction such as .C m. is erroneous, and results in loss of data. .TP .CR a \0[\|\f2dir\fP\|] Same as .C m except move all the files sent from .IR system . .TP .C p Print the contents of the file. .TP .C q Stop. .TP .SM EOT\s0 (control-D) Same as .CR q . .TP .CI ! command Escape to the shell to execute .IR command . .TP .C * Print a command summary. .RE .PP .C uupick invoked with the .CI -s system option searches only the .SM .I PUBDIR for files sent from .IR system . .SH WARNINGS To send files that begin with a dot (such as .CR .profile ) the filename must contain a corresponding dot. For example: .CR .profile , .CR .prof* , and .C .profil? are correct, whereas .C *prof* and .C ?profile are incorrect. .PP .SH FILES .TP 10 .SM .I PUBDIR .C /var/spool/uucppublic \0\0\0 public directory .SH SEE ALSO mail(1), uuclean(1M), uucp(1), uustat(1), uux(1). .PP .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .SH STANDARDS CONFORMANCE .CR uuto ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR uupick ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4uuto\f1 \- public \s-1UNIX\s+1 system to \s-1UNIX\s+1 system file copy@@@\f3uuto(1)\f1 .\" index@\f4uupick\f1 \- accept or reject files sent by \f4uuto\f1@@@\f3uuto(1)\f1 .\" index@public \s-1UNIX\s+1 system to \s-1UNIX\s+1 system file copy@@@\f3uuto(1)\f1 .\" index@\s-1UNIX\s+1 system to \s-1UNIX\s+1 system file copy, public@@@\f3uuto(1)\f1 .\" index@system to \s-1UNIX\s+1 system file copy, public \s-1UNIX\s+1@@@\f3uuto(1)\f1 .\" index@file copy, public \s-1UNIX\s+1 system to \s-1UNIX\s+1 system@@@\f3uuto(1)\f1 .\" index@copy file, public \s-1UNIX\s+1 system to \s-1UNIX\s+1 system@@@\f3uuto(1)\f1 .\" .\" toc@\f3uuto(1)\f1:\0\0\f4uuto\f1, \f4uupick\f1@@@public \s-1UNIX\s+1 system to \s-1UNIX\s+1 system file copy .\" toc@\f4uupick\f1: accept or reject incoming \s-1UUCP\s+1 messages@@@see \f3uuto(1)\f1 .\" .\" links@uuto.1 uupick.1 .\" .\" fileset_database@uuto.1 USER-CMDS-MAN .\" $Header: uustat.1,v 76.1 95/08/07 10:11:53 ssa Exp $ .TA u .TH uustat 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uustat \- uucp status inquiry and job control .SH SYNOPSIS .C uustat -a .br .C uustat -m .br .C uustat -p .br .C uustat -q .br .C uustat -k .IR jobid \|] .br .C uustat -r .IR jobid \|] .br .C uustat .RC [ -s\c .IR sys \|] .RC [ -u\c .IR user \|] .SH DESCRIPTION .C uustat displays the status of, or cancels, previously specified .C uucp commands, or provide general status on .C uucp connections to other systems (see .IR uucp (1)). Only one of the following options can be specified with .C uustat per command execution: .RS .TP 10 .C -a Output all jobs in queue. .TP .C -m Report the status of accessibility of all machines. .TP .C -p Execute a .C ps -flp for all the process .SM ID\c s that are in the lock files. .TP .C -q List the jobs queued for each machine. If a status file exists for the machine, its date, time and status information are reported. In addition, if a number appears in .C (\|) next to the number of .C C or .C X files it is the age in days of the oldest .C C. or .C X. file for that system. The Retry field is the number of hours until the next possible call. The Count field is the number of failure attempts. Note that for systems with a moderate number of outstanding jobs, this could take 30 seconds or more of real time to execute. As an example of the output produced by .C "uustat -q" : .RS .IP .C "eagle 3C 04/07-11:07 NO DEVICES AVAILABLE" .br .C "mh3bs3 2C 07/07-10:42 SUCCESSFUL" .RE .IP The above output tells how many command files are waiting for each system. Each command file can have zero or more files to be sent (a command file with no files to be sent causes the .C uucp system to call the remote system and see if work is waiting). The date and time refer to the previous interaction with the system followed by the status of interaction. .TP .CI -k \0jobid Kill the .C uucp request whose job identification is .IR jobid . The killed .C uucp request must belong to the person issuing the .C uustat command unless the command is executed by the super-user. .TP .CI -r \0jobid Rejuvenate .IR jobid . The files associated with .I jobid are touched so that their modification time is set to the current time. This prevents the cleanup daemon from deleting the job until the jobs modification time reaches the limit imposed by the cleanup daemon. .RE .PP The following options can be used singly or together but cannot be used with the options listed above: .RS .TP 10 .CI -s \0sys Report the status of all .C uucp requests for remote system .IR sys . .TP .CI -u \0user Report the status of all .C uucp requests issued by .IR user . .PP Output for both the .C -s and .C -u options has the following format: .nf .IP .C "eaglen0000 4/07-11:01:03 (POLL)" .C "eagleN1bd7 4/07-11:07 S eagle dan 522 /usr/dan/A" .C "eagleC1bd8 4/07-11:07 S eagle dan 59 D.3b2a12cd4924" .C " 4/07-11:07 S eagle dan rmail mike" .fi .PP With the .C -s and .C -u options, the first field is the .I jobid of the job. This is followed by the date and time. The next field is either an .C S or .CR R , depending on whether the job is to send or request a file. The next field is the destination system name. This is followed by the user .SM ID of the user who queued the job. The next field contains the size of the file, or in the case of a remote execution the name of the command (such as .C rmail which is the command used for remote mail). When the size appears in this field, the file name is also given. This can either be the name given by the user or an internal name (such as .CR D.3b2alce4924 ) that is created for data files associated with remote execution .RC ( rmail in this example). .RE .PP When no options are given, .C uustat outputs the status of all .C uucp requests issued by the current user. The format used is the same as with the .C -s or .C -u options. .PP .SH EXTERNAL INFLUENCES .SS Environment Variables .PP .C LC_TIME determines the format and contents of date and time strings. .PP .C LANG determines the language in which messages are displayed. .PP If .C LC_TIME is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C uustat behaves as if all internationalization variables are set to "C". See .IR environ (5). .SH FILES .TP 30 .C /var/spool/uucp/* spool directories .SH SEE ALSO uucp(1). .PP .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .SH STANDARDS CONFORMANCE .CR uustat ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4uustat\f1 \- uucp status inquiry and job control@@@\f3uustat(1)\f1 .\" index@\f4uucp\f1 status inquiry and job control@@@\f3uustat(1)\f1 .\" index@status inquiry and job control, \f4uucp\f1@@@\f3uustat(1)\f1 .\" index@job control, \f4uucp\f1 status inquiry and@@@\f3uustat(1)\f1 .\" index@control, \f4uucp\f1 status inquiry and job@@@\f3uustat(1)\f1 .\" .\" toc@\f3uustat(1)\f1:\0\0\f4uustat\f1@@@uucp status inquiry and job control .\" .\" fileset_database@uustat.1 USER-CMDS-MAN .\" $Header: uuto.1,v 76.1 95/08/07 10:13:15 ssa Exp $ .TA u .TH uuto 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uuto, uupick \- public UNIX system to UNIX system file copy .SH SYNOPSIS .C uuto .RI [ \|options\| ] .I source-files destination .br .C uupick .RC [ -s .IR system\| ] .SH DESCRIPTION .C uuto sends .I source-files to .IR destination . .C uuto uses the .C uucp facility to send files (see .IR uucp (1)), while allowing the local system to control the file access. A source-file name is a path name on your machine. Destination has the form: .IP .IC system ! user .PP where .I system is taken from a list of system names that .C uucp knows about (see .C uuname in .IR uucp (1) manual entry). .I user is the login name of someone on the specified system. .PP .C uuto recognizes the following options: .RS .TP 8 .C -p Copy the source file into the spool directory immediately, and send the copy. .TP .C -m Send mail to the requester when the copy is complete. .RE .PP The files (or sub-trees if directories are specified) are sent to .SM .I PUBDIR on .IR system , where .SM .I PUBDIR is the .SM UUCP public directory .RC ( /var/spool/uucppublic ). Specifically the files are sent to .IP .SM .I PUBDIR\c .CI /receive/ user / mysystem /files\f1. .PP The recipient is notified by electronic mail when the files arrive. .PP .C uupick accepts or rejects the files transmitted to the recipient. Specifically, .C uupick searches .SM .I PUBDIR for files destined for the user. For each entry (file or directory) found, the following message is printed on the standard output: .IP .C from .IC system : .RC [ file .IR file-name\| ] .RC [ dir .IR dirname\| ] .C ? .PP .C uupick then reads a line from the standard input to determine the disposition of the file: .RS .TP 16 Go on to next entry. .TP .C d Delete the entry. .TP .CR m \0[\|\f2dir\fP\|] Move the entry to named directory .I dir (current directory is default). Note that, if the current working directory is desired for .IR dir , do .I not specify any parameter with .CR m . A construction such as .C m. is erroneous, and results in loss of data. .TP .CR a \0[\|\f2dir\fP\|] Same as .C m except move all the files sent from .IR system . .TP .C p Print the contents of the file. .TP .C q Stop. .TP .SM EOT\s0 (control-D) Same as .CR q . .TP .CI ! command Escape to the shell to execute .IR command . .TP .C * Print a command summary. .RE .PP .C uupick invoked with the .CI -s system option searches only the .SM .I PUBDIR for files sent from .IR system . .SH WARNINGS To send files that begin with a dot (such as .CR .profile ) the filename must contain a corresponding dot. For example: .CR .profile , .CR .prof* , and .C .profil? are correct, whereas .C *prof* and .C ?profile are incorrect. .PP .SH FILES .TP 10 .SM .I PUBDIR .C /var/spool/uucppublic \0\0\0 public directory .SH SEE ALSO mail(1), uuclean(1M), uucp(1), uustat(1), uux(1). .PP .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .SH STANDARDS CONFORMANCE .CR uuto ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR uupick ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4uuto\f1 \- public \s-1UNIX\s+1 system to \s-1UNIX\s+1 system file copy@@@\f3uuto(1)\f1 .\" index@\f4uupick\f1 \- accept or reject files sent by \f4uuto\f1@@@\f3uuto(1)\f1 .\" index@public \s-1UNIX\s+1 system to \s-1UNIX\s+1 system file copy@@@\f3uuto(1)\f1 .\" index@\s-1UNIX\s+1 system to \s-1UNIX\s+1 system file copy, public@@@\f3uuto(1)\f1 .\" index@system to \s-1UNIX\s+1 system file copy, public \s-1UNIX\s+1@@@\f3uuto(1)\f1 .\" index@file copy, public \s-1UNIX\s+1 system to \s-1UNIX\s+1 system@@@\f3uuto(1)\f1 .\" index@copy file, public \s-1UNIX\s+1 system to \s-1UNIX\s+1 system@@@\f3uuto(1)\f1 .\" .\" toc@\f3uuto(1)\f1:\0\0\f4uuto\f1, \f4uupick\f1@@@public \s-1UNIX\s+1 system to \s-1UNIX\s+1 system file copy .\" toc@\f4uupick\f1: accept or reject incoming \s-1UUCP\s+1 messages@@@see \f3uuto(1)\f1 .\" .\" links@uuto.1 uupick.1 .\" .\" fileset_database@uuto.1 USER-CMDS-MAN .\" $Header: uux.1,v 76.1 95/08/07 10:14:38 ssa Exp $ .TA u .TH uux 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uux \- UNIX system to UNIX system command execution .SH SYNOPSIS .C uux .RI [ \|options\| ] .I command-string .SH DESCRIPTION .C uux gathers zero or more files from various systems, executes a command on a specified system, then sends standard output to a file on a specified system. Note that, for security reasons, many installations limit the list of commands executable on behalf of an incoming request from .CR uux . Many sites will permit little more than the receipt of mail (see .IR mail (1), .IR mailx (1), and .IR elm (1)) via .CR uux . .PP The .I command-string is made up of one or more arguments that look like a shell command line, except that the command and file names may be prefixed by .IC system-name !\f1. A null .I system-name is interpreted as the local system. .PP File names can be one of the following: .RS .TP 3 \(bu A full path name; .TP \(bu A path name preceded by .CI ~ xxx where .I xxx is a login name on the specified system and is replaced by that user's login directory. Note that if an invalid login is specified, the default will be to the public directory .RC ( /var/spool/uucppublic ); .TP \(bu A path name preceded by .CI ~/ destination where .I destination is appended to .CR /var/spool/uucppublic . .TP \(bu A simple file name (which is prefixed by the current directory). See .IR uucp (1) for details. .RE .PP For example, the command .IP .C uux "!diff usg!/usr/dan/file1 pwba!/a4/dan/file2 > !~/dan/file.diff" .PP gets files .C file1 and .C file2 from machines .C usg and .CR pwba , and executes a .IR diff (1) command, placing the results in .C file.diff in the local directory .CR /var/spool/uucppublic . .PP Any special shell characters such as .CR < , .CR > , .CR ; , or .C | should be quoted, either by quoting the entire .IR command-string , or quoting the special characters as individual arguments. .PP .C uux attempts to get all files to the execution system. For files that are output files, the file name must be escaped using parentheses. For example, the command .IP .C "uux a!cut -f1 b!/usr/file \e(c!/usr/file\e) .PP gets .C /usr/file from system .C b and sends it to system .CR a , performs a .C cut command on the file, and sends the result of the cut command to system .CR c . .PP .C uux notifies you if the requested command on the remote system was disallowed. The list of commands allowed is specified in the .C Permissions file in .CR /etc/uucp . The response comes by remote mail from the remote machine. .PP .C uux recognizes the following .IR options : .RS .TP 15 .C - The standard input to .C uux is made the standard input to the .IR command-string . .TP .CI -a name Use .I name as the user identification replacing the initiator user-\c .SM ID (notification is returned to the user). .TP .C -b Return whatever standard input was provided to the .C uux command if the exit status is non-zero. .TP .C -c Do not copy the local file to the spool directory for transfer to the remote machine (default). .TP .C -C Force the copy of local files to the spool directory for transfer. .TP .CI -g grade .I grade is a single letter/number; lower .SM ASCII sequence characters cause the job to be transmitted earlier during a particular conversation. .TP .CI -j Output the .I jobid (the job identification .SM ASCII string) on the standard output. This job identification can be used by .C uustat to obtain the status or terminate a job (see .IR uustat (1)). .TP .C -n Do not notify the user if the command fails. .TP .C -r Do not start the file transfer, just queue the job. .TP .CI -s file Report status of the transfer in .IR file . .TP .CI -x debug_level Produce debugging output on standard output. The .I debug_level is a number between 0 and 9. The higher the number, the more detailed the information returned. .TP .C -z Send success notification to user. .RE .SH WARNINGS Only the first command of a shell pipeline can have a .IC system-name !\f1. All other commands are executed on the system of the first command. .PP The use of the shell metacharacter .C * will probably not do what you want it to do. The shell tokens .C << and .C >> are not implemented. .PP The execution of commands on remote systems takes place in an execution directory known to the .SM UUCP subsystem. All files required for the execution are put into this directory unless they already reside on that machine. Therefore, the simple file name (without path or machine reference) must be unique within the .C uux request. The following command does .I not work: .IP .C uux "a!diff b!/usr/dan/xyz c!/usr/dan/xyz > !xyz.diff" .PP but the command: .IP .C uux "a!diff a!/usr/dan/xyz c!/usr/dan/xyz > !xyz.diff" .PP works (if .C diff is a permitted command). .PP Protected files and files that are in protected directories that are owned by the requester can be sent in commands using .CR uux . However, if the requester is .CR root , and the directory is not searchable by .CR other , the request fails. .PP .SH FILES .TP 27 .C /etc/uucp configuration files .PD 0 .TP .C /var/uucp log and error files .TP .C /var/spool/uucp spool directories .TP .C /var/spool/locks lock files .TP .C /var/spool/uucppublic public directory .PD .SH SEE ALSO mail(1), uuclean(1M), uucp(1). .PP .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .SH STANDARDS CONFORMANCE .CR uux ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4uux\f1 \- \s-1UNIX\s+1 system to \s-1UNIX\s+1 system command execution@@@\f3uux(1)\f1 .\" index@\s-1UNIX\s+1 system to \s-1UNIX\s+1 system command execution@@@\f3uux(1)\f1 .\" index@system to \s-1UNIX\s+1 system command execution, \s-1UNIX\s+1@@@\f3uux(1)\f1 .\" index@command execution, \s-1UNIX\s+1 system to \s-1UNIX\s+1 system@@@\f3uux(1)\f1 .\" index@execution of commands, \s-1UNIX\s+1 system to \s-1UNIX\s+1 system@@@\f3uux(1)\f1 .\" .\" toc@\f3uux(1)\f1:\0\0\f4uux\f1@@@\s-1UNIX\s+1 system to \s-1UNIX\s+1 system command execution .\" .\" fileset_database@uux.1 USER-CMDS-MAN .\" $Header: dos2ux.1,v 72.3 93/01/14 11:32:29 ssa Exp $ .TA d .TH dos2ux 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dos2ux, ux2dos \- convert \s-1ASCII\s+1 file format .SH SYNOPSIS .C dos2ux .I file ... .br .C ux2dos .I file ... .SH DESCRIPTION .C dos2ux and .C ux2dos read each specified .I file in sequence and write it to standard output, converting to .SM HP-UX format or to .SM DOS format, respectively. Each .I file can be either .SM DOS format or .SM HP-UX format for either command. .PP A .SM DOS file name is recognized by the presence of an embedded colon .RC ( : ) delimiter; see .IR dosif (4) for .SM DOS file naming conventions. .PP If no input file is given or if the argument .C - is encountered, .C dos2ux and .C ux2dos read from standard input. Standard input can be combined with other files. .SH EXAMPLES Print file .C myfile on the display: .IP .C "dos2ux myfile" .PP Convert .C file1 and .C file2 to .SM DOS format then concatenate them together, placing them in .CR file3 . .IP .C "ux2dos file1 file2 > file3" .SH RETURN VALUE .C dos2ux and .C ux2dos return .C 0 if successful or .C 2 if the command failed. The only possible failure is the inability to open a specified file, in which case the commands print a warning. .SH WARNINGS Command formats resembling: .IP .C "dos2ux file1 file2 > file1" .PP overwrite the data in .C file1 before the concatenation begins, causing a loss of the contents of .CR file1 . Therefore, be careful when using shell special characters. .SH SEE ALSO doschmod(1), doscp(1), dosdf(1), dosls(1), dosmkdir(1), dosrm(1), dosif(4). .\" .\" index@\f4dos2ux\f1, \f4ux2dos\f1 \- convert \s-1ASCII\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@\f4ux2dos\f1, \f4dos2ux\f1 \- convert \s-1ASCII\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@convert \s-1DOS\s+1 file to \s-1HP-UX ASCII\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@convert \s-1HP-UX ASCII\s+1 file to \s-1DOS\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@files: convert \s-1DOS\s+1 file to \s-1HP-UX ASCII\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@files: convert \s-1HP-UX ASCII\s+1 file to \s-1DOS\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@format: convert \s-1DOS\s+1 file to \s-1HP-UX ASCII\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@format: convert \s-1HP-UX ASCII\s+1 file to \s-1DOS\s+1 file format@@@\f3dos2ux(1)\f1 .\" index@\s-1DOS\s+1 files: convert \s-1HP-UX ASCII\s+1 file to \s-1DOS\s+1 format@@@\f3dos2ux(1)\f1 .\" index@\s-1DOS\s+1 files: convert \s-1DOS\s+1 file to \s-1HP-UX ASCII\s+1 format@@@\f3dos2ux(1)\f1 .\" .\" toc@\f3dos2ux(1)\f1:\0\0\f4dos2ux\f1, \f4ux2dos\f1@@@convert \s-1ASCII\s+1 file format .\" toc@\f4ux2dos\f1: convert \s-1ASCII\s+1 file format@@@see \f3dos2ux(1)\f1 .\" .\" links@dos2ux.1 ux2dos.1 .\" .\" fileset_database@dos2ux.1 USER-CMDS-MAN .\" $Header: vacation.1,v 72.5 94/07/21 11:39:25 ssa Exp $ .TA v .TH vacation 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vacation \- return ``I am not here'' indication .SH SYNOPSIS .C vacation -i .PP .C vacation .RC [\| .RC [ -a .IR alias \|]\0...\|] .I login .SH DESCRIPTION The .CR vacation program returns a message to the sender of a message telling them that you are currently not reading your mail. The intended use is in a .CR .forward file in .CR $HOME . For example, your .CR .forward file might contain: .IP .C "\eeric, ""|/usr/bin/vacation -a allman eric""" .PP which would send messages to you (assuming your login name was .CR eric ) and reply to any messages for .CR eric or .CR allman . The \e preceding .CR eric is required to force direct delivery to .CR eric 's mailbox and prevent an infinite loop through the .CR .forward file. The double quotes are needed to tell .IR sendmail (1M) to treat the enclosed as a unit, rather than separate recipients. It is also important to specify the full path for the vacation program, and there must be no white space between the \(or character and the start of the path name. .PP No message is sent unless .I login or an .I alias supplied using the .CR -a option is a substring of either the .CR To: or .CR Cc: headers of the mail. No messages from .CR ???-REQUEST , .CR Postmaster , .CR UUCP , .CR MAILER , or .CR MAILER-DAEMON are replied to, nor is a notification sent if a .CR "Precedence: bulk" or .CR "Precedence: junk" line is included in the mail headers. Only one message per week is sent to each unique sender (at each unique host system). The people who have sent you messages are recorded in a database in the files .CR .vacation.pag and .CR .vacation.dir in your home directory. .PP The .CR vacation program expects a file .CR .vacation.msg , in your home directory, containing a message to be sent back to each sender. It should be an entire message (including headers). For example, it might say: .nf .IP .\" DO NOT REMOVE Eric Allman's NAME FROM THIS EXAMPLE (contractual .\" obligation to UCB). Joe Kalash's name used with permission. .\" >From: eric@ucbmonet.Berkeley.EDU (Eric Allman) Subject: I am on vacation X-Delivered-By-The-Graces-Of: The vacation program Precedence: bulk .IP I am on vacation until July 22. If you have something urgent, please contact Joe Kalash . --eric .fi .PP Header lines in this file must be left justified and must not be preceded by any other lines, including blank lines (see .IR sendmail (1M)). If there is no .CR .vacation.msg file, .CR vacation uses the following file (if it exists): .IP .C /usr/share/lib/vacation.def .PP Otherwise, it logs an error. .PP .CR vacation reads the first line from the standard input (the incoming mail message in the example .CR .forward file above) for a UNIX style .CR From line to determine the sender. .IR sendmail (1M) includes this .CR From line automatically, and its absence indicates non-mail input. .SS Options The .CR vacation program supports the following options: .RS .TP 15 .C -i Initializes the vacation database files. This option should be used before modifying a .CR .forward file. .TP .CI -a " alias" Identifies another name that can legitimately appear in the .CR To: line of the mail header instead of your login name. More than one .CR -a option can be specified. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which error messages are printed. .ift .bp .SH DIAGNOSTICS On error, .CR vacation exits with a value from .CR and causes .CR sendmail to report an error back to the sender of the original message. Errors such as the absence of .CR .vacation.msg or calling .CR vacation with incorrect arguments, are logged using .CR syslogd on the system where .CR vacation actually runs (see .IR syslogd (1M)). The .CR syslog file .RC ( /var/adm/syslog/mail.log by default \(mi see .CR /etc/syslog.conf and .IR syslogd (1M) for customizations) should be inspected when .CR vacation generates mailer error messages. .PP Remember that if the machine is configured for shared mail, inbound mail is handled at the mail server rather than on mail client nodes. This means that .CR syslog diagnostics appear in the mail server's .CR syslog ; not the client's .CR syslog . .SH WARNINGS Errors in the .CR .forward file can lead to loss of mail and infinite mail loops. .PP Always send test mail to yourself after configuring .CR vacation to be sure that it is working properly. This is akin to checking telephone forwarding before leaving for an extended period, and can prevent loss of messages. .SH AUTHOR .CR vacation was developed by Eric Allman and the University of California, Berkeley. .SH FILES .TP 42 .C $HOME/.vacation.dir Database file. .PD 0 .TP .C $HOME/.vacation.msg Message to send. .TP .C $HOME/.vacation.pag Database file. .TP .C /usr/share/lib/vacation.def System-wide default header and message. .TP .C /etc/syslog.conf Dictates where error messages are recorded. .PD .SH SEE ALSO sendmail(1M), syslog(1M), ndbm(3). .\" .\" index@\f4vacation\f1 \- return ``I am not here'' indication@@@\f3vacation(1)\f1 .\" index@\f1mail response: ``I am not here'' indication@@@\f3vacation(1)\f1 .\" .\" toc@\f3vacation(1)\f1:\0\0\f4vacation\f1@@@return ``I am not here'' indication\f1 .\" $Header: val.1,v 76.1 95/07/10 17:13:08 ssa Exp $ .\" Copyright Hewlett-Packard Company .TA v .TH val 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME val \- validate \s-1SCCS\s+1 file .SH SYNOPSIS .C val - .PP .C val .RC [ -s ] .RC [ -r .IR SID ] .RC [ -m .IR name\| ] .RC [ -y .IR type\| ] .RC [ -v ] .I files .SH DESCRIPTION The .CR val command reads one or more .IR file s to determine whether each file read is an SCCS file meeting the characteristics specified by the optional argument list. Command-line options may appear in any order, and are described below. .SS Options The .CR val command recognizes the following options and command-line arguments. The effects of each option apply independently to each specified .IR file . .RS .TP 15 .C -s Silent option. Suppress diagnostic messages normally generated on the standard output when an error is encountered while processing any specified .IR file . .TP .CI -r \0SID Check existence of revision .I SID in .I file where .I SID .RI ( S CCS .I ID\c entification string) is an SCCS delta number. .I SID is first checked to ensure that it is unambiguous and valid before checking .IR file . For example, .C *-r1 is ambiguous because it physically does not exist but implies 1.1, 1.2, etc., which may exist; .C *-r1.0 and .C *-r1.1.0 are invalid because they have a zero suffix which never appears in a valid delta number. .TP .CI -m \0name .I name is compared with the SCCS .C %\&M% keyword in .IR file . .TP .CI -y \0type .I type is compared with the SCCS .CR %\&Y% keyword in .IR file . .TP .C -v Verbose option. Prints additional detailed diagnostic messages on the standard output for any corruption detected while processing each named .IR file . The messages are intended for use with the information contained in .IR sccsfile (4) when fixing the file. .TP .I file One or more SCCS files to be processed. If .CR - is used as a .I file argument, .CR val reads the standard input until an end-of-file condition is encountered. Each line read is independently processed as if it were a command-line argument list. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of text within file as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C val behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH RETURN VALUE The 8-bit code returned by .CR val is a disjunction of the possible errors; i. e., can be interpreted as a bit string where (moving from left to right) set bits are interpreted as follows: .RS .TP .B Bit .B Interpretation .PD 0 .TP \00 Missing .I file argument; .TP \01 Unknown or duplicate option argument; .TP \02 Corrupt SCCS file; .TP \03 Cannot open .I file or .I file is not an SCCS file; .TP \04 .I SID is invalid or ambiguous; .TP \05 .I SID does not exist; .TP \06 .CI % Y % does not match .CR -y .I type argument; .TP \07 .CI % M % does not match .C -m .I name argument; .RE .PD .PP Note that .CR val can process two or more files on a given command line, and in turn can process multiple command lines (when reading the standard input). In these cases an aggregate code is returned; a logical .CR OR of the codes generated for each command line and file processed. .SH DIAGNOSTICS .CR val generates diagnostic messages on the standard output for each command line and file processed, and also returns a single 8-bit code upon exit as described earlier under RETURN VALUE. Use the .IR sccshelp (1) command for explanations. .SH SEE ALSO admin(1), delta(1), get(1), sccshelp(1), prs(1), sccsfile(4). .SH STANDARDS CONFORMANCE .CR val ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4val\f1 \- validate an SCCS file@@@\f3val(1)\f1 .\" index@\f1validate an SCCS file@@@\f3val(1)\f1 .\" index@\f1SCCS: validate an SCCS file@@@\f3val(1)\f1 .\" index@\f1file, validate an SCCS file@@@\f3val(1)\f1 .\" .\" toc@\f3val(1)\f1:\0\0\f4val\f1@@@validate SCCS file .\" $Header: machid.1,v 76.1 95/07/10 17:16:19 ssa Exp $ .TA m .TH machid 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hp9000s200, hp9000s300, hp9000s500, hp9000s800, pdp11, u3b, u3b2, u3b5, u3b10, u370, vax \- provide truth value about processor type .SH SYNOPSIS .nf .C hp9000s200 .C hp9000s300 .C hp9000s400 .C hp9000s500 .C hp9000s700 .C hp9000s800 .C hp-mc680x0 .C hp-pa .C pdp11 .C u3b .C u3b2 .C u3b5 .C u3b10 .C u370 .C vax .fi .SH DESCRIPTION The following commands return a true value (exit code 0) if the a processor type matches the command name. Otherwise a false value (exit code non-zero) is returned. These commands are commonly used within .C make makefiles and shell procedures to improve portability of applications (see .IR make (1)). .PP .TS center box tab(;); cB | lB || cB | lB cf4 | l || cf4 | l. Command;True for:;Command;True for: _ hp9000s200;Series 200; pdp11;\s-1PDP\s0-11/45 or \s-1PDP\s0-11/70 hp9000s300;Series 300; u3b;3B20 computer hp9000s400;Series 400; u3b2;3B2 computer hp9000s500;Series 500; u3b5;3B5 computer hp9000s700;Series 700; u3b10;3B10 computer hp9000s800;Series 800/700; u370;IBM System/370 computer hp-mc680x0;Series 200, 300, or 400; vax;\s-1VAX\s0-11/750 or \s-1VAX\s0-11/780 hp-pa;Series 700 or 800; ; .TE .SH EXAMPLES Given a shell script that must behave differently when run on an HP 9000 Series 700 or 800 system, select the correct code segment to be executed: .nf .IP .C "if hp9000s800" .C "then" .C " # system is Series 700 or 800." .C " if hp9000s700" .C " then" .IP .C " # System is Series 700" .IP .I "\h'1.5i'Series 700 code fragment goes here" .C " else" .C " # System is Series 800" .IP .I "\h'1.5i'Series 800 code fragment goes here" .IP .C " fi" .C "fi" .fi .SH WARNINGS .C hp9000s800 always returns true on both Series 800 and Series 700 systems. Therefore, when using this command in scripts to determine hardware type, always use both .C hp9000s800 and .C hp9000s700 in the appropriate sequence to ensure correct results (see .SM EXAMPLES\c ). .SH SEE ALSO make(1), sh(1), test(1), true(1). .\" .\" toc@\f3machid(1)\f1:\0\0\f4hp9000s200\f1, \f4hp9000s300\f1, \f4hp9000s500\f1, \f4hp9000s800\f1,\n\f4pdp11\f1, \f4u3b\f1, \f4u3b5\f1, \f4vax\f1@@@provide truth value about processor type .\" toc@\f4hp9000s200\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s300\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s500\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp9000s800\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-mc680x0\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4hp-pa\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4pdp11\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b5\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4vax\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" toc@\f4u3b2\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u3b10\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" toc@\f4u370\f1: provide truth value about processor type@@@see \f3machid(1)\f1 .\" .\" index@\f4machid\f1 \- provide truth value about processor type@@@\f3machid(1)\f1 .\" index@\f4hp9000s200\f1 \- is processor an \s-1HP\|9000\s0 Series 200?@@@\f3machid(1)\f1 .\" index@\f4hp9000s300\f1 \- is processor an \s-1HP\|9000\s0 Series 300?@@@\f3machid(1)\f1 .\" index@\f4hp9000s500\f1 \- is processor an \s-1HP\|9000\s0 Series 500?@@@\f3machid(1)\f1 .\" index@\f4hp9000s800\f1 \- is processor an \s-1HP\|9000\s0 Series 800?@@@\f3machid(1)\f1 .\" index@\f4pdp11\f1 \- is processor a pdp11?@@@\f3machid(1)\f1 .\" index@\f4u3b\f1 \- is processor a \s-1U3B\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b5\f1 \- is processor a \s-1U3B5\s0?@@@\f3machid(1)\f1 .\" index@\f4vax\f1 \- is processor a \s-1VAX\s0?@@@\f3machid(1)\f1 .\" .\" index@\f4u3b2\f1 \- is processor a \s-1U3B2\s0?@@@\f3machid(1)\f1 .\" index@\f4u3b10\f1 \- is processor a \s-1U3B10\s0?@@@\f3machid(1)\f1 .\" index@\f4u370\f1 \- is processor an IBM \s-1370\s0?@@@\f3machid(1)\f1 .\" .\" links@machid.1 hp9000s200.1 .\" links@machid.1 hp9000s300.1 .\" links@machid.1 hp9000s400.1 .\" links@machid.1 hp9000s500.1 .\" links@machid.1 hp9000s700.1 .\" links@machid.1 hp9000s800.1 .\" links@machid.1 hp-mc680x0.1 .\" links@machid.1 hp-pa.1 .\" links@machid.1 pdp11.1 .\" links@machid.1 u3b.1 .\" links@machid.1 u3b5.1 .\" links@machid.1 vax.1 .\" .\" links@machid.1 u3b2.1 .\" links@machid.1 u3b10.1 .\" links@machid.1 u370.1 .\" .\" fileset_database@machid.1 USER-CMDS-MAN .\" $Header: vc.1,v 72.4 94/09/15 15:44:08 ssa Exp $ .TA v .TH vc 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vc \- substitutes assigned values in place of identification keywords. .SH SYNOPSIS .C vc .RC [ -a ] .RC [ -t ] .RC [ -c .IR char\| ] .RC [ -s ] .RI [ \|keyword\f1=\fPvalue \0... \0keyword\f1=\fPvalue\| ] .SH DESCRIPTION The .CR vc , or .I version control command copies lines from the standard input to the standard output under control of command line .I arguments and .I control statements encountered in the standard input. In the process of performing the copy operation, user declared .I keywords can be replaced by their string .I value when they appear in plain text and/or control statements. The copying of lines from the standard input to the standard output is conditional, based on tests of keyword values specified in control statements or on .C vc command arguments. .PP Replacement of keywords by values is done whenever a keyword surrounded by control characters is encountered on a version control statement. The .C -a option forces replacement of keywords in .I all lines of text. An uninterpreted control character can be included in a value by preceding it with .CR \e . If a literal .C \e is desired, it too must be preceded by .CR \e . .PP The .C vc command is part of the SCCS (Source Code Control System) command suite. .SS Options .C vc recognizes the following options and arguments: .RS .TP 10 .C -a Replace keywords surrounded by control characters with their assigned value in .I all text lines and not just in .C vc statements. .TP .C -t Ignore all characters from the beginning of a line up to and including the first .I tab character for the purpose of detecting a control statement. If one is found, all characters up to and including the .I tab are discarded. .TP .CI -c char Specify a control character to be used in place of .CR : . .TP .C -s Silence warning messages (not errors) that are normally printed on the diagnostic output. .RE .SS Control Statements A control statement is a single line beginning with a control character, and the default control character is colon .RC ( : ) (Unless the .C -t and .C -c options are used [See above]). Input lines beginning with a backslash .RC ( \e ) followed by the control character are not control lines, and are copied to the standard output with the backslash removed. Lines beginning with a backslash followed by a non-control character are copied in their entirety. .PP A keyword is composed of 9 or fewer alphanumeric characters of which the first character is alphabetic. A value is any .SM ASCII string that can be created using .C ed (see .IR ed (1)); a numeric value is an unsigned string of digits. Keyword values must not contain spaces or tabs. .PP Version control statements occur in the following forms: .RS .TP 18 \f3:\f1dcl keyword[, ..., keyword] Used to declare keywords. All keywords must be declared. .TP \f3:\f1asg keyword\f3=\f1value Used to assign values to keywords. An .C asg statement overrides the assignment for the corresponding keyword on the .C vc command line and all previous .CR asg s for that keyword. Keywords declared, but not assigned values have null values. .nf .TP .CR : "if condition" .C "..." .fi .TP .CR : end Used to skip lines of the standard input. If the condition is true, all lines between the .I if statement and the matching .I end statement are copied to the standard output. If the condition is false, all intervening lines are discarded, including control statements. Note that intervening .I if statements and matching .I end statements are recognized solely for the purpose of maintaining the proper .I if-end matching. .IP .ne 9 The syntax of a condition may include the following: .RS .RS .TP 10 \f3::\f1= [ "not" ] .PD 0 .TP \f3::\f1= | "|" .TP \f3::\f1= | "&" .TP \f3::\f1= "(" ")" | .TP \f3::\f1= "=" | "!=" | "<" | ">" .TP \f3::\f1= | .PD .RE .RE .IP The following are available operators and their meanings: .RS .RS .TP 10 .C = equal .PD 0 .TP .C != not equal .TP .C & and .TP .C | or .TP .C > greater than .TP .C < less than .TP .C ( ) used for logical groupings .TP .C not allowed only immediately after the .IR if , and when present, inverts the value of the entire condition .PD .RE .RE .IP The .C > and .C < operate only on unsigned integer values (such as .C : 012 > 12 is false). All other operators take strings as arguments (for example, .C : 012 != 12 is true). The precedence of the operators (from highest to lowest) is as follows: .RS .IP .C = != > < \h'.3i'all of equal precedence .br followed by .C & and then .CR | . .PP Parentheses can be used to alter the order of precedence. Values must be separated from operators or parentheses by at least one space or tab. .RE .TP .CR :: text Used for keyword replacement on lines that are copied to the standard output. The two leading control characters are removed, and keywords surrounded by control characters in text are replaced by their value before the line is copied to the output file. This action is independent of the .C -a option. .TP .CR : on .PD 0 .TP .CR : off Turn on or off keyword replacement on all lines. .PD .TP .CR : ctl char Change the control character to char. .TP .CR : msg message Prints the given message on the diagnostic output. .TP .CR : err message Prints the given message followed by: .RS .IP .C "ERROR: err statement on line \f3...\fP (915)" .RE .IP on the diagnostic output. .C vc halts execution and returns an exit code of 1. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of keywords, values, the control character assigned through .C ctl and within text as single- and/or multi-byte characters. .PP .C LANG determines the language in which messages are displayed. .PP If .C LC_CTYPE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C vc behaves as if all internationalization variables are set to "C". See .IR environ (5). .SH RETURN VALUE .C vc returns 0 on normal completion; 1 if an error occurs. .SH DIAGNOSTICS Use .IR sccshelp (1) for explanations. .SH SEE ALSO ed(1), sccshelp(1). .\" .\" index@\f4vc\f1 \- version control@@@\f3vc(1)\f1 .\" index@version control@@@\f3vc(1)\f1 .\" index@control, version@@@\f3vc(1)\f1 .\" .\" toc@\f3vc(1)\f1:\0\0\f4vc\f1@@@version control .\" $Header: vi.1,v 78.1 96/02/12 14:21:12 ssa Exp $ .TA v .TH vi 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vi, view, vedit \- screen-oriented (visual) text editor .SH SYNOPSIS .CR vi .RC [ - ] .RC [ -l ] .RC [ -r ] .RC [ -R ] .RC [ -t .IR tag ] .RC [ -v ] .RC [ -V ] .RC [ -w\c .IR size ] .RC [ -x ] .RC [ +\c .IR command ] .RI [ file " ...]" .PP .SS "XPG4 Synopsis" .CR vi .RC [ -rR ] .RC [ -c .IR command ] .RC [ -t .IR tag ] .RC [ -w .IR size ] .RI [ file " ...]" .PP .SS Obsolescent Options .PP .CR vi .RC [ -rR ] .RC [+\c .IR command ] .RC [ -t .IR tag ] .RC [ -w .IR size ] .RI [ file " ...]" .PP .CR view .RC [ - ] .RC [ -l ] .RC [ -r ] .RC [ -R ] .RC [ -t .IR tag ] .RC [ -v ] .RC [ -V ] .RC [ -w\c .IR size ] .RC [ -x ] .RC [ +\c .IR command ] .RI [ file " ...]" .PP .CR vedit .RC [ - ] .RC [ -r ] .RC [ -R ] .RC [ -l ] .RC [ -t .IR tag ] .RC [ -v ] .RC [ -V ] .RC [ -w\c .IR size ] .RC [ -x ] .RC [ +\c .IR command ] .RI [ file " ...]" .SS Remarks The program names .CR ex , .CR edit , .CR vi , .CR view , and .CR vedit are separate personalities of the same program. This manual entry describes the behavior of the .CR vi / view / vedit personality. .SH DESCRIPTION The .CR vi (visual) program is a display-oriented text editor that is based on the underlying .CR ex line editor (see .IR ex (1)). It is possible to switch back and forth between the two and to execute .CR ex commands from within .CR vi . The line-editor commands and the editor options are described in .IR ex (1). Only the visual mode commands are described here. .PP The .CR view program is identical to .CR vi except that the .CR readonly editor option is set (see .IR ex (1)). .PP The .CR vedit program is somewhat friendlier for beginners and casual users. The .CR report editor option is set to .CR 1 , and the .CR nomagic , .CR novice , and .CR showmode editor options are set. .PP In .CR vi , the terminal screen acts as a window into a memory copy of the file being edited. Changes made to the file copy are reflected in the screen display. The position of the cursor on the screen indicates the position within the file copy. .PP The environment variable .CR TERM must specify a terminal type that is defined in the .CR terminfo database (see .IR terminfo (4)). Otherwise, a message is displayed and the line-editor is invoked. .PP As with .CR ex , editor initialization scripts can be placed in the environment variable .CR EXINIT , or in the file .CR .exrc in the current or home directory. .SS Options and Arguments .CR vi recognizes the following command-line options and arguments: .RS .ifn .TP 10 .ift .TP 15 .CR - Suppress all interactive-user feedback. This is useful when editor commands are taken from scripts. .TP .CR -l Set the .CR lisp editor option (see .IR ex (1)). Provides indents appropriate for .CR lisp code. The .CR ( , .CR ) , .CR { , .CR } , .CR [[ , and .CR ]] commands in .CR vi are modified to function with .CR lisp source code. .TP .CR -r Recover the specified .IR file s after an editor or system crash. If no .I file is specified, a list of all saved files is printed. You must be the owner of the saved file in order to recover it (superuser cannot recover files owned by other users). .TP .CR -R Set the .CR readonly editor option to prevent overwriting a file inadvertently (see .IR ex (1)). .TP .CI -t " tag" Execute the .CR tag .IR tag command to load and position a predefined file. See the .CR tag command and the .CR tags editor option in .IR ex (1). .TP .CR -v Invoke visual mode .RC ( vi ). Useful with .CR ex , it has no effect on .CR vi . .TP .CR -V Set verbose mode. Editor commands are displayed as they are executed when input from a .CR .exrc file or a source file (see the .CR source command in .IR ex (1)). .TP .CI -w size Set the value of the .CR window editor option to .IR size . If .IR size is omitted, it defaults to .CR 3 . .TP .CR -x Set encryption mode. You are prompted for a key to allow for the creation or editing of an encrypted file (see the .CR crypt command in .IR ex (1)). .ifn .TP 12 .ift .TP 15 .CI -c " command" (XPG4 only.) .ifn .TP 10 .ift .TP 15 .CI + command (Obsolescent) Begin editing by executing the specified .CR ex command-mode commands. As with the normal .CR ex command-line entries, the .CR command option-argument can consist of multiple .CR ex commands separated by vertical-line commands (|). The use of commands that enter input mode in this manner produces undefined results. .TP .I file Specify the file or files to be edited. If more than one .I file is specified, they are processed in the order given. If the .CR -r option is also specified, the files are read from the recovery area. .RE .PP (XPG4 only.) If both the .CR -t " tag " and .CR -c " command " .C "(or the obsolescent +command)" options are given, the .CR -t " tag " will be processed first, that is, the file containing the tag is selected by .CR -t and then the command is executed. .RE .PP When invoked, .CR vi is in .BR "command mode" . .BR "input mode" is initiated by several commands used to insert or change text. .PP In input mode, ESC (escape) is used to leave input mode; however, two consecutive ESC characters are required to leave input mode if the .CR doubleescape editor option is set (see .IR ex (1)). .PP In command mode, ESC is used to cancel a partial command; the terminal bell sounds if the editor is not in input mode and there is no partially entered command. .PP .B WARNING: ESC .I completes a "bottom line" command (see below). .PP The last (bottom) line of the screen is used to echo the input for search commands .RC ( / and .CR ? ), .CR ex commands .RC ( : ), and system commands .RC ( ! ). It is also used to report errors or print other messages. .PP The receipt of .CR SIGINT during text input or during the input of a command on the bottom line terminates the input (or cancels the command) and returns the editor to command mode. During command mode, .CR SIGINT causes the bell to be sounded. In general the bell indicates an error (such as an unrecognized key). .PP Lines displayed on the screen containing only a .CR ~ indicate that the last line above them is the last line of the file (the .CR ~ lines are past the end of the file). Terminals with limited local intelligence might display lines on the screen marked with an .CR @ . These indicate space on the screen not corresponding to lines in the file. (These lines can be removed by entering a .CR ^R , forcing the editor to retype the screen without these holes.) .PP If the system crashes or .CR vi aborts due to an internal error or unexpected signal, .CR vi attempts to preserve the buffer if any unwritten changes were made. Use the .CR -r command line option to retrieve the saved changes. .PP The .CR vi text editor supports the .CR SIGWINCH signal, and redraws the screen in response to window-size changes. .SS Command Summary Most commands accept a preceding number as an argument, either to give a size or position (for display or movement commands), or as a repeat count (for commands that change text). For simplicity, this optional argument is referred to as .I count when its effect is described. .PP The following operators can be followed by a movement command to specify an extent of text to be affected: .CR c , .CR d , .CR y , .CR < , .CR > , .CR ! , and .CR = . The region specified begins at the current cursor position and ends just prior to the cursor position indicated by the move. If the command operates on lines only, all the lines that fall partly or wholly within this region are affected. Otherwise the exact marked region is affected. .PP In the following description, control characters are indicated in the form .CR ^X , which represents .RC Ctrl- X . Whitespace is defined to be the characters space, tab, and alternative space. Alternative space is the first character of the .CR ALT_PUNCT item described in .IR langinfo (5) for the language specified by the .CR LANG environment variable (see .IR environ (5)). .PP Unless otherwise specified, the commands are interpreted in command mode and have no special effect in input mode. .RS .TP 12 .CR ^B Scroll backward to display the previous window of text. A preceding .I count specifies the number of windows to go back. Two lines of overlap are kept if possible. .TP .CR ^D Scroll forward a half-window of text. A preceding .I count gives the number of (logical) lines to scroll, and is remembered for future .CR ^D and .CR ^U commands. .TP .CR ^D (input mode) Backs up over the indentation provided by .CR autoindent or .CR ^T to the next multiple of .CR shiftwidth spaces. Whitespace inserted by .CR ^T at other than the beginning of a line cannot be backed over using .CR ^D . A preceding .CR ^ removes all indentation for the current and subsequent input lines of the current input mode until new indentation is established by inserting leading whitespace, either by direct input or by using .CR ^T . .TP .CR ^E Scroll forward one line, leaving the cursor where it is if possible. .TP .CR ^F Scroll forward to display the window of text following the current one. A preceding .I count specifies the number of windows to advance. Two lines of overlap are kept if possible. .IP (XPG4 only.) The current line is displayed and the cursor is moved to the first nonblank character of the current line or the first character if the line is a blank line. .TP .CR ^G Print the current file name and other information, including the number of lines and the current position (equivalent to the .CR ex command .CR f ). .TP .CR ^H Move one space to the left (stops at the left margin). A preceding .I count specifies the number of spaces to back up. (Same as .CR h ). .TP .CR ^H (input mode) Move the cursor left to the previous input character without erasing it from the screen. The character is deleted from the saved text. .TP .CR ^J Move the cursor down one line in the same column, if possible. A preceding .I count specifies the number of lines to move down. (Same as .CR ^N and .CR j ). .TP .CR ^L Clear and redraw the screen. Use when the screen is scrambled for any reason. .TP .CR ^M Move to the first nonwhitespace character in the next line. A preceding .I count specifies the number of lines to advance. .TP .CR ^N Same as .CR ^J and .CR j . .TP .CR ^P Move the cursor up one line in the same column. A preceding .I count specifies the number of lines to move up (same as .CR k ). .TP .CR ^R Redraw the current screen, eliminating the false lines marked with .C @ (which do not correspond to actual lines in the file). .TP .CR ^T Pop the tag stack. See the .CR pop command in .IR ex (1). .TP .CR ^T (input mode) Insert .CR shiftwidth whitespace. If at the beginning of the line, this inserted space can only be backed over using .CR ^D . .TP .CR ^U Scroll up a half-window of text. A preceding .I count gives the number of (logical) lines to scroll, and is remembered for future .CR ^D and .CR ^U commands. .TP .CR ^V In input mode, .CR ^V quotes the next character to permit the insertion of special characters (including ESC) into the file. .TP .CR ^W In input mode, .CR ^W backs up one word; the deleted characters remain on the display. .TP .CR ^Y Scroll backward one line, leaving the cursor where it is, if possible. .TP .CR ^[ Cancel a partially formed command; .CR ^[ sounds the bell if there is no partially formed command. .IP In input mode, .CR ^[ terminates input mode. However, two consecutive ESC characters are required to terminate input mode if the .CR doubleescape editor option is set (see .IR ex (1)). .IP When entering a command on the bottom line of the screen .RC ( ex command line or search pattern with .CR \e or .CR ? ), terminate input and execute command. .IP On many terminals, .CR ^[ can be entered by pressing the ESC or ESCAPE key. .TP .CR ^\e Exit .CR vi and enter .I ex command mode. If in input mode, terminate the input first. .TP .CR ^] Take the word at or after the cursor as a tag and execute the .CR tag MbobC editor command (see .IR ex (1)). .TP .CR ^^ Return to the previous file (equivalent to .CR ":ex #" ). .TP .I space Move one space to the right (stops at the end of the line). A preceding .I count specifies the number of spaces to go forward (same as .CR l ). .TP .I erase Erase, where .I erase is the user-designated erase character (see .IR stty (1)). Same as .CR ^H . .TP .I kill Kill, where .I kill is the user-designated kill character (see .IR stty (1)). In input mode, .I kill backs up to the beginning of the current input line without erasing the line from the screen display. .TP .I susp Suspend the editor session and return to the calling shell, where .I susp is the user-designated process-control suspend character (see .IR stty (1)). See .IR ex (1) for more information on the .CR suspend editor command. .TP .CR ! An operator that passes specified lines from the buffer as standard input to the specified system command, and replaces those lines with the standard output from the command. The .CR ! is followed by a movement command specifying the lines to be passed (lines from the current position to the end of the movement) and then the command (terminated as usual by a return). A preceding .I count is passed on to the movement command after .CR ! . .IP Doubling .CR ! and preceding it by .I count causes that many lines, starting with the current line, to be passed. .TP .C """" Use to precede a named buffer specification. There are named buffers .CR 1 through .CR 9 in which the editor places deleted text. The named buffers .CR a through .CR z are available to the user for saving deleted or yanked text; see also .CR y , below. .TP .CR $ Move to the end of the current line. A preceding .I count specifies the number of lines to advance (for example, .CR 2$ causes the cursor to advance to the end of the next line). .TP .CR % Move to the parenthesis or brace that matches the parenthesis or brace at the current cursor position. .TP .CR & Same as the .I ex command .CR & (that is, .CR & repeats the previous .CR substitute command). .TP .CR ' When followed by a .CR ' , .CR vi returns to the previous context, placing the cursor at the beginning of the line. (The previous context is set whenever a nonrelative move is made.) When followed by a letter .CR a - z , returns to the line marked with that letter (see the .CR m command), at the first nonwhitespace character in the line. .IP When used with an operator such as .CR d to specify an extent of text, the operation takes place over complete lines (see also .CR ` ). .TP .CR ` When followed by a .CR ` , .CR vi returns to the previous context, placing the cursor at the character position marked (the previous context is set whenever a nonrelative move is made). When followed by a letter .CR a .CR z , returns to the line marked with that letter (see the .CR m command), at the character position marked. .IP When used with an operator such as .CR d to specify an extent of text, the operation takes place from the exact marked place to the current position within the line (see also .CR ' ). .TP .CR [[ Back up to the previous section boundary. A section is defined by the value of the .CR sections option. Lines that start with a form feed .RC ( ^L ) or .CR { also stop .CR [[ . .IP If the option .CR lisp is set, the cursor stops at each .CR ( at the beginning of a line. .TP .C ]] Move forward to a section boundary (see .CR [[ ). .TP .CR ^ Move to the first nonwhitespace position on the current line. .TP .CR ( Move backward to the beginning of a sentence. A sentence ends at a .CR . , .CR ! , or .CR ? followed by either the end of a line or by two spaces. Any number of closing .CR ) , .CR ] , .tr ~" \"translate begin .CR ~ , \" prints as '"' and .CR ' characters can appear between the .CR . , .CR ! , or .CR ? and the spaces or end of line. If a .I count is specified, the cursor moves back the specified number of sentences. .br .tr ~~ \"translate end .IP If the .CR lisp option is set, the cursor moves to the beginning of a .CR lisp .IR s -expression. Sentences also begin at paragraph and section boundaries (see .CR { and .CR [[ ). .TP .CR ) Move forward to the beginning of a sentence. If a .I count is specified, the cursor advances the specified number of sentences (see .CR ( ). .TP .CR { Move back to the beginning of the preceding paragraph. A paragraph is defined by the value of the .CR paragraphs option. A completely empty line and a section boundary (see .CR [[ above) are also interpreted as the beginning of a paragraph. If a .I count is specified, the cursor moves backward the specified number of paragraphs. .TP .CR } Move forward to the beginning of the next paragraph. If a .I count is specified, the cursor advances the specified number of paragraphs (see .CR { ). .TP .CR | Requires a preceding .IR count ; the cursor moves to the specified column of the current line (if possible). .TP .CR + Move to the first nonwhitespace character in the next line. If a .I count is specified, the cursor advances the specified number of lines (same as .CR ^M ). .TP .CR , The comma .RC ( , ) performs the reverse action of the last .CR f , .CR F , .CR t , or .CR T command issued, by searching in the opposite direction on the current line. If a .I count is specified, the cursor repeats the search the specified number of times. .TP .CR - The hyphen character .RC ( - ) moves the cursor to the first nonwhitespace character in the previous line. If a .I count is specified, the cursor moves back the specified number of times. .TP .CR _ The underscore character .RC ( _ ) moves the cursor to the first nonwhitespace character in the current line. If a .I count is specified, the cursor advances the specified number of lines, with the current line being counted as the first line; no .I count or a .I count of 1 specifies the current line. .TP .CR . Repeat the last command that changed the buffer. If a .I count is specified, the command is repeated the specified number of times. .TP .CR / Read a string from the last line on the screen, interpret it as a regular expression, and scan forward for the next occurrence of a matching string. The search begins when the user types a carriage return to terminate the pattern; the search can be terminated by sending .CR SIGINT (or the user-designated interrupt character). .IP When used with an operator to specify an extent of text, the defined region begins with the current cursor position and ends at the beginning of the matched string. Entire lines can be specified by giving an offset from the matched line (by using a closing .CR / followed by a .CI + n or .CI - n\c ). .TP .CR 0 Move to the first character on the current line (the .CR 0 is not interpreted as a command when preceded by a nonzero digit). .TP .CR : The colon character .RC ( : ) begins an .CR ex command. The .CR : and the entered command are echoed on the bottom line; the .CR ex command is executed when the user types a carriage return. .TP .CR ; Repeat the last single character find using .CR f , .CR F , .CR t , or .CR T . If a .I count is specified, the search is repeated the specified number of times. .TP .CR < An operator that shifts lines to the left by one .CR shiftwidth . The .CR < can be followed by a move to specify lines. A preceding .I count is passed through to the move command. .IP When repeated .RC ( << ), shifts the current line (or .I count lines starting at the current one). .TP .CR > An operator that shifts lines right one .CR shiftwidth (see .CR < ). .TP .CR = If the .CR lisp option is set, .CR = reindents the specified lines, as if they were typed in with .CR lisp and .CR autoindent set. .CR = can be preceded by a .I count to indicate how many lines to process, or followed by a move command for the same purpose. .TP .CR ? Scan backwards, the reverse of .CR / (see .CR / ). .TP .CI @ buffer Execute the commands stored in the named .IR buffer . Be careful not to include a character at the end of the buffer contents unless the is part of the command stream. Commands to be executed in .I ex mode should be preceded by a colon .RC ( : ). .TP .CR ~ The tilde .RC ( ~ ) switches the case of the character under the cursor (if it is a letter), then moves one character to the right, stopping at the end of the line). A preceding .I count specifies how many characters in the current line are switched. .TP .CR A Append at the end of line (same as .CR $a ). .TP .CR B Back up one word, where a word is any nonblank sequence, placing the cursor at the beginning of the word. If a .I count is specified, the cursor moves back the specified number of words. .TP .CR C Change the rest of the text on the current line (same as .CR c$ ). .TP .CR D Delete the rest of the text on the current line (same as .CR d$ ). .TP .CR E Move forward to the end of a word, where a word is any nonblank sequence. If a .I count is specified, the cursor advances the specified number of words. .TP .CR F Must be followed by a single character; scans backwards in the current line, searching for that character and moving the cursor to it, if found. If a .I count is specified, the search is repeated the specified number of times. .TP .CR G Go to the line number given as preceding argument, or the end of the file if no preceding .I count is given. .TP .CR H Move the cursor to the top line on the screen. If a .I count is given, the cursor moves to .I count number of lines from the top of the screen. The cursor is placed on the first nonwhitespace character on the line. If used as the target of an operator, entire lines are affected. .TP .CR I Insert at the beginning of a line (same as .CR ^ followed by .CR i ). .TP .CR J Join the current line with the next one, supplying appropriate whitespace: one space between words, two spaces after a period, and no spaces at all if the first character of the next line is a closing parenthesis .RC ( ) ). A preceding .I count causes the specified number of lines to be joined, instead of just two. .TP .CR L Move the cursor to the first nonwhitespace character of the last line on the screen. If a .I count is given, the cursor moves to .I count number of lines from the bottom of the screen. When used with an operator, entire lines are affected. .TP .CR M Move the cursor to the middle line on the screen, at the first nonwhitespace position on the line. .TP .CR N Scan for the next match of the last pattern given to .CR / or .CR ? , but in the opposite direction; this is the reverse of .CR n . .TP .CR O Open a new line above the current line and enter input mode. .TP .CR P Put back (replace) the last deleted or yanked text before/above the cursor. Entire lines of text are returned above the cursor if entire lines were deleted or yanked. Otherwise, the text is inserted just before the cursor. .IP (XPG4 only.) In this case, the cursor is moved to last column position of the inserted characters. .IP If .CR P is preceded by a named buffer specification .RI ( x ), the contents of that buffer are retrieved instead. .TP .CR Q Exit .CR vi and enter .CR ex command mode. .TP .CR R Replace characters on the screen with characters entered, until the input is terminated with ESC. .TP .CR S Change entire lines (same as .CR cc ). A preceding .I count changes the specified number of lines. .TP .CR T Must be followed by a single character; scan backwards in the current line for that character, and, if found, place the cursor just after that character. A .I count is equivalent to repeating the search the specified number of times. .TP .CR U Restore the current line to its state before the cursor was last moved to it. .IP (XPG4 only.) The cursor position is set to the column position 1 or to the position indicated by the previous line if the .CR autoindent is set. .TP .CR W Move forward to the beginning of a word in the current line, where a word is a sequence of nonblank characters. If the current position is at the beginning of a word, the current position is within a bigword or the character at that position cannot be a part of a bigword, the current position shall move to the first character of the next bigword. If no subsequent bigword exists on the current line, the current position shall move to the first character of the first bigword on the first following line that contains the bigword. For this command, an empty or blank line is considered to contain exactly one bigword. The current line is set to the line containing the bigword selected and the current position is set to the first character of the bigword selected. A preceding .I count specifies the number of words to advance. .TP .CR X Delete the character before the cursor. A preceding .I count repeats the effect, but only characters on the current line are deleted. .TP .CR Y Place (yank) a copy of the current line into the unnamed buffer (same as .CR yy ). If a .I count is specified, .I count lines are copied to the buffer. If the .CR Y is preceded by a buffer name, the lines are copied to the named buffer. .TP .CR ZZ Exit the editor, writing out the buffer if it was changed since the last write (same as the .CR ex command .CR x ). Note that if the last write was to a different file and no changes have occurred since, the editor exits without writing out the buffer. .TP .CR a Enter input mode, appending the entered text after the current cursor position. A preceding .I count causes the inserted text to be replicated the specified number of times, but only if the inserted text is all on one line. .TP .CR b Back up to the previous beginning of a word in the current line. A word is a sequence of alphanumerics or a sequence of special characters. A preceding .I count repeats the effect. .TP .CR c Must be followed by a movement command. Delete the specified region of text, and enter input mode to replace deleted text with new text. If more than part of a single line is affected, the deleted text is saved in the numeric buffers. If only part of the current line is affected, the last character deleted is marked with a .CR $ . A preceding .I count passes that value through to the move command. If the command is .CR cc , the entire current line is changed. .TP .CR d Must be followed by a movement command. Delete the specified region of text. If more than part of a line is affected, the text is saved in the numeric buffers. A preceding .I count passes that value through to the move command. If the command is .CR dd , the entire current line is deleted. .TP .CR e Move forward to the end of the next word, defined as for .CR b . A preceding .I count repeats the effect. .TP .CR f Must be followed by a single character; scan the rest of the current line for that character, and moves the cursor to it if found. A preceding .I count repeats the action that many times. .TP .CR h Move the cursor one character to the left (same as .CR ^H ). A preceding .I count repeats the effect. .TP .CR i Enter input mode, inserting the entered text before the cursor (see .CR a ). .TP .CR j Move the cursor one line down in the same column (same as .CR ^J and .CR ^N ). .TP .CR k Move the cursor one line up (same as .CR ^P ). .TP .CR l Move the cursor one character to the right (same as .CR ). .TP .CI m x Mark the current position of the cursor. .CI x is a lowercase letter, .CR a \(mi z , that is used with the .CR ` and .CR ' commands to refer to the marked line or line position. .TP .CR n Repeat the last .CR / or .CR ? scanning commands. .TP .CR o Open a line below the current line and enter input mode; otherwise like .CR O . .TP .CR p Put text after/below the cursor; otherwise like .CR P . .TP .CR r Must be followed by a single character; the character under the cursor is replaced by the specified one. (The new character can be a new-line.) If .CR r is preceded by a .IR count , .I count characters are replaced by the specified character. .TP .CR s Delete the single character under the cursor and enter input mode; the entered text replaces the deleted character. A preceding .I count specifies how many characters on the current line are changed. The last character being changed is marked with a .CR $ , as for .CR c . .TP .CR t Must be followed by a single character; scan the remainder of the line for that character. The cursor moves to the column prior to the character if the character is found. A preceding .I count is equivalent to repeating the search .I count times. .TP .CR u Reverse the last change made to the current buffer. If repeated, .CR u alternates between these two states; thus is its own inverse. When used after an insertion of text on more than one line, the lines are saved in the numerically named buffers. .TP .CR w Move forward to the beginning of the next word (where word is defined as in .CR b ). A preceding .I count specifies how many words the cursor advances. .TP .CR x Delete the single character under the cursor. When .CR x is preceded by a .IR count , .CR x deletes the specified number of characters forward from the cursor position, but only on the current line. .TP .CR y Must be followed by a movement command; the specified text is copied (yanked) into the unnamed temporary buffer. If preceded by a named buffer specification, .tr ~" .CI ~ x\f1, the text is placed in that buffer also. If the command is .CR yy , the entire current line is yanked. .br .tr ~~ .TP .CR z Redraw the screen with the current line placed as specified by the following options: .CR z specifies the top of the screen, .CR z. the center of the screen, and .CR z- the bottom of the screen. The commands .CR z^ and .CR z+ are similar to .CR ^B and .CR ^F , respectively. However, .CR z^ and .CR z+ do not attempt to maintain two lines of overlap. A .I count after the .CR z and before the following character to specifies the number of lines displayed in the redrawn screen. A .I count before the .CR z gives the number of the line to use as the reference line instead of the default current line. .RE .SS Keyboard Editing Keys At initialization, the editor automatically maps some terminal keyboard editing keys to equivalent visual mode commands. These mappings are only established for keys that are listed in the following table and defined in the .IR terminfo (4) database as valid for the current terminal (as specified by the .CR TERM environment variable). .PP Both command and input mode mappings are created (see the .CR map command in .IR ex (1)). With the exception of the .CR insert char keys, which simply toggle input mode on and off, the input mode mappings exit input mode, perform the same action as the command mode mapping, and then reenter input mode. .PP On certain terminals, the character sequence sent by a keyboard editing key, which is then mapped to a visual mode command, can be the same character sequence a user might enter to perform another command or set of commands. This is most likely to happen with the input mode mappings; therefore, on these terminals, the input mode mappings are disabled by default. Users can override the disabling and enabling of both the command and input mode keyboard editing key mappings by setting the .CR keyboardedit and .CR keyboardedit! editor options as appropriate (see .IR ex (1)). The .CR timeout , .CR timeoutlen , and .CR doubleescape editor options are alternative methods of addressing this problem. .PP .TS center tab(;); lB lB lB lB lB lB lB lB lB lB lf4p+1 lf4p+1 lf4p+1 lf4p+1 l. terminfo;command;input;map entry;mode map;mode map;name;description _ .sp +.5v key_ic;i;^[;inschar;insert char key_eic;i;^[;inschar;end insert char key_up;k;^[ka;up;arrow up key_down;j;^[ja;down;arrow down key_left;h;^[ha;left;arrow left key_right;l;^[la;right;arrow right key_home;H;^[Ha;home;arrow home key_il;o^[;^[o^[a;insline;insert line key_dl;dd;^[dda;delline;delete line key_clear;^L;^[^La;clear;clear screen key_eol;d$;^[d$a;clreol;clear line key_sf;^E;^[^Ea;scrollf;scroll down key_dc;x;^[xa;delchar;delete char key_npage;^F;^[^Fa;npage;next page key_ppage;^B;^[^Ba;ppage;previous page key_sr;^Y;^[^Ya;sr;scroll up key_eos;dG;^[dGa;clreos;clear to end of screen .sp +.5v _ .TE .SH EXTERNAL INFLUENCES Support for international codes and environment variables are as follows: .SS Environment Variables .CR UNIX95 specifies using the XPG4 behaviour for this command. .PP .CR COLUMNS overrides the system-selected horizontal screen size. .PP .CR LINES overrides the system-selected vertical screen size, used as the number of lines in a screenful and the vertical screen size in visual mode. .PP .CR SHELL is a variable that shall be interpreted as the preferred command-line interpreter for use in .CR ! , .CR shell , .CR read , and other commands with an operand of the form .CR !string . For the .CR shell command the program shall be invoked with the two arguments .CR -c and .CR string . If this variable is null or not set, the .CR sh utility shall be used. .PP .CR TERM is a variable that shall be interpreted as the name of the terminal type. If this variable is unset or null, an unspecified default terminal type shall be used. .PP .CR PATH determines the search path for the shell command specified in the editor commands, .CR shell , .CR read , and .CR write . .CR EXINIT determines a list of .I ex commands that will be executed on editor startup, before reading the first file. The list can contain multiple commands by separating them using a vertical line (|) character. .PP .CR HOME determines a pathname of a directory that will be searched for an editor startup file named .CR .exrc . .PP .CR LC_ALL This variable shall determine the locale to be used to override any values for locale categories specified by the setting of .CR LANG or any environment variables beginning with .CR LC_ . .PP .CR LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .CR LC_COLLATE determines the collating sequence used in evaluating regular expressions and in processing the .I tags file. .CR LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as uppercase or lowercase letters, the shifting of letters between uppercase and lowercase, and the characters matched by character class expressions in regular expressions. .PP .CR LANG determines the language in which messages are displayed. .PP .CR LANGOPTS specifies options determining how text for right-to-left languages is stored in input and output files. See .IR environ (5). .PP If .CR LC_COLLATE or .CR LC_CTYPE is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, the editor behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .SH EXAMPLES (none needed) .SH WARNINGS See also the WARNINGS section in .IR ex (1). .SS Program Limits .CR vi places the following limits on files being edited: .TP .B Maximum Line Length .CR LINE_MAX characters (defined in .CR ), including 2-3 bytes for overhead. Thus, if the value specified for .CR LINE_MAX is 2048, a line length up to 2044 characters should cause no problem. .IP If you load a file that contain lines longer than the specified limit, the lines are truncated to the stated maximum length. Saving the file will write the truncated version over the original file, thus overwriting the original lines completely. .IP Attempting to create lines longer than the allowable maximum for the editor produces a .CR "line too long" error message. .TP .B Maximum File Size The maximum file length of 234,239 lines is silently enforced. .TP .B Other limits: .RS .TP 3 \(bu 256 characters per global command list. .TP \(bu 128 characters in a file name in .CR vi or .CR ex .CR open mode. On short-file-name HP-UX systems, the maximum file name length is 14 characters. .TP \(bu 128 characters in a previous insert/delete buffer. .TP \(bu 100 characters in a shell-escape command. .TP \(bu 63 characters in a string-valued option .RC ( :set command). .TP \(bu 30 characters in a program tag name. .TP \(bu 32 or fewer macros defined by .CR map command. .TP \(bu 512 or fewer characters total in combined .CR map macros. .RE .RE .SH AUTHOR .CR vi was developed by the University of California, Berkeley. The 16-bit extensions to .CR vi are based in part on software of the Toshiba Corporation. .SH SEE ALSO ctags(1), ed(1), ex(1), stty(1), write(1), terminfo(4), environ(5), lang(5), regexp(5). .TP .IR "The Ultimate Guide to the vi and ex Text Editors" , Benjamin/Cummings Publishing Company, Inc., ISBN 0-8053-4460-8, HP part number 97005-90015. .SH STANDARDS CONFORMANCE .CR vi ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4vedit\f1 \- beginner's screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f4vi\f1 \- extended screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f4view\f1 \- read-only screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f1editor: extended screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f1screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f1text editor, screen-oriented@@@\f3vi(1)\f1 .\" .\" toc@\f3vi(1)\f1:\0\0\f4vedit\f1, \f4vi\f1, \f4view\f1@@@extended screen-oriented text editor .\" toc@\f4vedit\f1:\0\0beginner's screen-oriented text editor@@@see \f3vi(1)\f1 .\" toc@\f4view\f1:\0\0read-only screen-oriented text editor@@@see \f3vi(1)\f1 .\" .\" links@vi.1 vedit.1 .\" links@vi.1 view.1 .\" $Header: vi.1,v 78.1 96/02/12 14:21:12 ssa Exp $ .TA v .TH vi 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vi, view, vedit \- screen-oriented (visual) text editor .SH SYNOPSIS .CR vi .RC [ - ] .RC [ -l ] .RC [ -r ] .RC [ -R ] .RC [ -t .IR tag ] .RC [ -v ] .RC [ -V ] .RC [ -w\c .IR size ] .RC [ -x ] .RC [ +\c .IR command ] .RI [ file " ...]" .PP .SS "XPG4 Synopsis" .CR vi .RC [ -rR ] .RC [ -c .IR command ] .RC [ -t .IR tag ] .RC [ -w .IR size ] .RI [ file " ...]" .PP .SS Obsolescent Options .PP .CR vi .RC [ -rR ] .RC [+\c .IR command ] .RC [ -t .IR tag ] .RC [ -w .IR size ] .RI [ file " ...]" .PP .CR view .RC [ - ] .RC [ -l ] .RC [ -r ] .RC [ -R ] .RC [ -t .IR tag ] .RC [ -v ] .RC [ -V ] .RC [ -w\c .IR size ] .RC [ -x ] .RC [ +\c .IR command ] .RI [ file " ...]" .PP .CR vedit .RC [ - ] .RC [ -r ] .RC [ -R ] .RC [ -l ] .RC [ -t .IR tag ] .RC [ -v ] .RC [ -V ] .RC [ -w\c .IR size ] .RC [ -x ] .RC [ +\c .IR command ] .RI [ file " ...]" .SS Remarks The program names .CR ex , .CR edit , .CR vi , .CR view , and .CR vedit are separate personalities of the same program. This manual entry describes the behavior of the .CR vi / view / vedit personality. .SH DESCRIPTION The .CR vi (visual) program is a display-oriented text editor that is based on the underlying .CR ex line editor (see .IR ex (1)). It is possible to switch back and forth between the two and to execute .CR ex commands from within .CR vi . The line-editor commands and the editor options are described in .IR ex (1). Only the visual mode commands are described here. .PP The .CR view program is identical to .CR vi except that the .CR readonly editor option is set (see .IR ex (1)). .PP The .CR vedit program is somewhat friendlier for beginners and casual users. The .CR report editor option is set to .CR 1 , and the .CR nomagic , .CR novice , and .CR showmode editor options are set. .PP In .CR vi , the terminal screen acts as a window into a memory copy of the file being edited. Changes made to the file copy are reflected in the screen display. The position of the cursor on the screen indicates the position within the file copy. .PP The environment variable .CR TERM must specify a terminal type that is defined in the .CR terminfo database (see .IR terminfo (4)). Otherwise, a message is displayed and the line-editor is invoked. .PP As with .CR ex , editor initialization scripts can be placed in the environment variable .CR EXINIT , or in the file .CR .exrc in the current or home directory. .SS Options and Arguments .CR vi recognizes the following command-line options and arguments: .RS .ifn .TP 10 .ift .TP 15 .CR - Suppress all interactive-user feedback. This is useful when editor commands are taken from scripts. .TP .CR -l Set the .CR lisp editor option (see .IR ex (1)). Provides indents appropriate for .CR lisp code. The .CR ( , .CR ) , .CR { , .CR } , .CR [[ , and .CR ]] commands in .CR vi are modified to function with .CR lisp source code. .TP .CR -r Recover the specified .IR file s after an editor or system crash. If no .I file is specified, a list of all saved files is printed. You must be the owner of the saved file in order to recover it (superuser cannot recover files owned by other users). .TP .CR -R Set the .CR readonly editor option to prevent overwriting a file inadvertently (see .IR ex (1)). .TP .CI -t " tag" Execute the .CR tag .IR tag command to load and position a predefined file. See the .CR tag command and the .CR tags editor option in .IR ex (1). .TP .CR -v Invoke visual mode .RC ( vi ). Useful with .CR ex , it has no effect on .CR vi . .TP .CR -V Set verbose mode. Editor commands are displayed as they are executed when input from a .CR .exrc file or a source file (see the .CR source command in .IR ex (1)). .TP .CI -w size Set the value of the .CR window editor option to .IR size . If .IR size is omitted, it defaults to .CR 3 . .TP .CR -x Set encryption mode. You are prompted for a key to allow for the creation or editing of an encrypted file (see the .CR crypt command in .IR ex (1)). .ifn .TP 12 .ift .TP 15 .CI -c " command" (XPG4 only.) .ifn .TP 10 .ift .TP 15 .CI + command (Obsolescent) Begin editing by executing the specified .CR ex command-mode commands. As with the normal .CR ex command-line entries, the .CR command option-argument can consist of multiple .CR ex commands separated by vertical-line commands (|). The use of commands that enter input mode in this manner produces undefined results. .TP .I file Specify the file or files to be edited. If more than one .I file is specified, they are processed in the order given. If the .CR -r option is also specified, the files are read from the recovery area. .RE .PP (XPG4 only.) If both the .CR -t " tag " and .CR -c " command " .C "(or the obsolescent +command)" options are given, the .CR -t " tag " will be processed first, that is, the file containing the tag is selected by .CR -t and then the command is executed. .RE .PP When invoked, .CR vi is in .BR "command mode" . .BR "input mode" is initiated by several commands used to insert or change text. .PP In input mode, ESC (escape) is used to leave input mode; however, two consecutive ESC characters are required to leave input mode if the .CR doubleescape editor option is set (see .IR ex (1)). .PP In command mode, ESC is used to cancel a partial command; the terminal bell sounds if the editor is not in input mode and there is no partially entered command. .PP .B WARNING: ESC .I completes a "bottom line" command (see below). .PP The last (bottom) line of the screen is used to echo the input for search commands .RC ( / and .CR ? ), .CR ex commands .RC ( : ), and system commands .RC ( ! ). It is also used to report errors or print other messages. .PP The receipt of .CR SIGINT during text input or during the input of a command on the bottom line terminates the input (or cancels the command) and returns the editor to command mode. During command mode, .CR SIGINT causes the bell to be sounded. In general the bell indicates an error (such as an unrecognized key). .PP Lines displayed on the screen containing only a .CR ~ indicate that the last line above them is the last line of the file (the .CR ~ lines are past the end of the file). Terminals with limited local intelligence might display lines on the screen marked with an .CR @ . These indicate space on the screen not corresponding to lines in the file. (These lines can be removed by entering a .CR ^R , forcing the editor to retype the screen without these holes.) .PP If the system crashes or .CR vi aborts due to an internal error or unexpected signal, .CR vi attempts to preserve the buffer if any unwritten changes were made. Use the .CR -r command line option to retrieve the saved changes. .PP The .CR vi text editor supports the .CR SIGWINCH signal, and redraws the screen in response to window-size changes. .SS Command Summary Most commands accept a preceding number as an argument, either to give a size or position (for display or movement commands), or as a repeat count (for commands that change text). For simplicity, this optional argument is referred to as .I count when its effect is described. .PP The following operators can be followed by a movement command to specify an extent of text to be affected: .CR c , .CR d , .CR y , .CR < , .CR > , .CR ! , and .CR = . The region specified begins at the current cursor position and ends just prior to the cursor position indicated by the move. If the command operates on lines only, all the lines that fall partly or wholly within this region are affected. Otherwise the exact marked region is affected. .PP In the following description, control characters are indicated in the form .CR ^X , which represents .RC Ctrl- X . Whitespace is defined to be the characters space, tab, and alternative space. Alternative space is the first character of the .CR ALT_PUNCT item described in .IR langinfo (5) for the language specified by the .CR LANG environment variable (see .IR environ (5)). .PP Unless otherwise specified, the commands are interpreted in command mode and have no special effect in input mode. .RS .TP 12 .CR ^B Scroll backward to display the previous window of text. A preceding .I count specifies the number of windows to go back. Two lines of overlap are kept if possible. .TP .CR ^D Scroll forward a half-window of text. A preceding .I count gives the number of (logical) lines to scroll, and is remembered for future .CR ^D and .CR ^U commands. .TP .CR ^D (input mode) Backs up over the indentation provided by .CR autoindent or .CR ^T to the next multiple of .CR shiftwidth spaces. Whitespace inserted by .CR ^T at other than the beginning of a line cannot be backed over using .CR ^D . A preceding .CR ^ removes all indentation for the current and subsequent input lines of the current input mode until new indentation is established by inserting leading whitespace, either by direct input or by using .CR ^T . .TP .CR ^E Scroll forward one line, leaving the cursor where it is if possible. .TP .CR ^F Scroll forward to display the window of text following the current one. A preceding .I count specifies the number of windows to advance. Two lines of overlap are kept if possible. .IP (XPG4 only.) The current line is displayed and the cursor is moved to the first nonblank character of the current line or the first character if the line is a blank line. .TP .CR ^G Print the current file name and other information, including the number of lines and the current position (equivalent to the .CR ex command .CR f ). .TP .CR ^H Move one space to the left (stops at the left margin). A preceding .I count specifies the number of spaces to back up. (Same as .CR h ). .TP .CR ^H (input mode) Move the cursor left to the previous input character without erasing it from the screen. The character is deleted from the saved text. .TP .CR ^J Move the cursor down one line in the same column, if possible. A preceding .I count specifies the number of lines to move down. (Same as .CR ^N and .CR j ). .TP .CR ^L Clear and redraw the screen. Use when the screen is scrambled for any reason. .TP .CR ^M Move to the first nonwhitespace character in the next line. A preceding .I count specifies the number of lines to advance. .TP .CR ^N Same as .CR ^J and .CR j . .TP .CR ^P Move the cursor up one line in the same column. A preceding .I count specifies the number of lines to move up (same as .CR k ). .TP .CR ^R Redraw the current screen, eliminating the false lines marked with .C @ (which do not correspond to actual lines in the file). .TP .CR ^T Pop the tag stack. See the .CR pop command in .IR ex (1). .TP .CR ^T (input mode) Insert .CR shiftwidth whitespace. If at the beginning of the line, this inserted space can only be backed over using .CR ^D . .TP .CR ^U Scroll up a half-window of text. A preceding .I count gives the number of (logical) lines to scroll, and is remembered for future .CR ^D and .CR ^U commands. .TP .CR ^V In input mode, .CR ^V quotes the next character to permit the insertion of special characters (including ESC) into the file. .TP .CR ^W In input mode, .CR ^W backs up one word; the deleted characters remain on the display. .TP .CR ^Y Scroll backward one line, leaving the cursor where it is, if possible. .TP .CR ^[ Cancel a partially formed command; .CR ^[ sounds the bell if there is no partially formed command. .IP In input mode, .CR ^[ terminates input mode. However, two consecutive ESC characters are required to terminate input mode if the .CR doubleescape editor option is set (see .IR ex (1)). .IP When entering a command on the bottom line of the screen .RC ( ex command line or search pattern with .CR \e or .CR ? ), terminate input and execute command. .IP On many terminals, .CR ^[ can be entered by pressing the ESC or ESCAPE key. .TP .CR ^\e Exit .CR vi and enter .I ex command mode. If in input mode, terminate the input first. .TP .CR ^] Take the word at or after the cursor as a tag and execute the .CR tag MbobC editor command (see .IR ex (1)). .TP .CR ^^ Return to the previous file (equivalent to .CR ":ex #" ). .TP .I space Move one space to the right (stops at the end of the line). A preceding .I count specifies the number of spaces to go forward (same as .CR l ). .TP .I erase Erase, where .I erase is the user-designated erase character (see .IR stty (1)). Same as .CR ^H . .TP .I kill Kill, where .I kill is the user-designated kill character (see .IR stty (1)). In input mode, .I kill backs up to the beginning of the current input line without erasing the line from the screen display. .TP .I susp Suspend the editor session and return to the calling shell, where .I susp is the user-designated process-control suspend character (see .IR stty (1)). See .IR ex (1) for more information on the .CR suspend editor command. .TP .CR ! An operator that passes specified lines from the buffer as standard input to the specified system command, and replaces those lines with the standard output from the command. The .CR ! is followed by a movement command specifying the lines to be passed (lines from the current position to the end of the movement) and then the command (terminated as usual by a return). A preceding .I count is passed on to the movement command after .CR ! . .IP Doubling .CR ! and preceding it by .I count causes that many lines, starting with the current line, to be passed. .TP .C """" Use to precede a named buffer specification. There are named buffers .CR 1 through .CR 9 in which the editor places deleted text. The named buffers .CR a through .CR z are available to the user for saving deleted or yanked text; see also .CR y , below. .TP .CR $ Move to the end of the current line. A preceding .I count specifies the number of lines to advance (for example, .CR 2$ causes the cursor to advance to the end of the next line). .TP .CR % Move to the parenthesis or brace that matches the parenthesis or brace at the current cursor position. .TP .CR & Same as the .I ex command .CR & (that is, .CR & repeats the previous .CR substitute command). .TP .CR ' When followed by a .CR ' , .CR vi returns to the previous context, placing the cursor at the beginning of the line. (The previous context is set whenever a nonrelative move is made.) When followed by a letter .CR a - z , returns to the line marked with that letter (see the .CR m command), at the first nonwhitespace character in the line. .IP When used with an operator such as .CR d to specify an extent of text, the operation takes place over complete lines (see also .CR ` ). .TP .CR ` When followed by a .CR ` , .CR vi returns to the previous context, placing the cursor at the character position marked (the previous context is set whenever a nonrelative move is made). When followed by a letter .CR a .CR z , returns to the line marked with that letter (see the .CR m command), at the character position marked. .IP When used with an operator such as .CR d to specify an extent of text, the operation takes place from the exact marked place to the current position within the line (see also .CR ' ). .TP .CR [[ Back up to the previous section boundary. A section is defined by the value of the .CR sections option. Lines that start with a form feed .RC ( ^L ) or .CR { also stop .CR [[ . .IP If the option .CR lisp is set, the cursor stops at each .CR ( at the beginning of a line. .TP .C ]] Move forward to a section boundary (see .CR [[ ). .TP .CR ^ Move to the first nonwhitespace position on the current line. .TP .CR ( Move backward to the beginning of a sentence. A sentence ends at a .CR . , .CR ! , or .CR ? followed by either the end of a line or by two spaces. Any number of closing .CR ) , .CR ] , .tr ~" \"translate begin .CR ~ , \" prints as '"' and .CR ' characters can appear between the .CR . , .CR ! , or .CR ? and the spaces or end of line. If a .I count is specified, the cursor moves back the specified number of sentences. .br .tr ~~ \"translate end .IP If the .CR lisp option is set, the cursor moves to the beginning of a .CR lisp .IR s -expression. Sentences also begin at paragraph and section boundaries (see .CR { and .CR [[ ). .TP .CR ) Move forward to the beginning of a sentence. If a .I count is specified, the cursor advances the specified number of sentences (see .CR ( ). .TP .CR { Move back to the beginning of the preceding paragraph. A paragraph is defined by the value of the .CR paragraphs option. A completely empty line and a section boundary (see .CR [[ above) are also interpreted as the beginning of a paragraph. If a .I count is specified, the cursor moves backward the specified number of paragraphs. .TP .CR } Move forward to the beginning of the next paragraph. If a .I count is specified, the cursor advances the specified number of paragraphs (see .CR { ). .TP .CR | Requires a preceding .IR count ; the cursor moves to the specified column of the current line (if possible). .TP .CR + Move to the first nonwhitespace character in the next line. If a .I count is specified, the cursor advances the specified number of lines (same as .CR ^M ). .TP .CR , The comma .RC ( , ) performs the reverse action of the last .CR f , .CR F , .CR t , or .CR T command issued, by searching in the opposite direction on the current line. If a .I count is specified, the cursor repeats the search the specified number of times. .TP .CR - The hyphen character .RC ( - ) moves the cursor to the first nonwhitespace character in the previous line. If a .I count is specified, the cursor moves back the specified number of times. .TP .CR _ The underscore character .RC ( _ ) moves the cursor to the first nonwhitespace character in the current line. If a .I count is specified, the cursor advances the specified number of lines, with the current line being counted as the first line; no .I count or a .I count of 1 specifies the current line. .TP .CR . Repeat the last command that changed the buffer. If a .I count is specified, the command is repeated the specified number of times. .TP .CR / Read a string from the last line on the screen, interpret it as a regular expression, and scan forward for the next occurrence of a matching string. The search begins when the user types a carriage return to terminate the pattern; the search can be terminated by sending .CR SIGINT (or the user-designated interrupt character). .IP When used with an operator to specify an extent of text, the defined region begins with the current cursor position and ends at the beginning of the matched string. Entire lines can be specified by giving an offset from the matched line (by using a closing .CR / followed by a .CI + n or .CI - n\c ). .TP .CR 0 Move to the first character on the current line (the .CR 0 is not interpreted as a command when preceded by a nonzero digit). .TP .CR : The colon character .RC ( : ) begins an .CR ex command. The .CR : and the entered command are echoed on the bottom line; the .CR ex command is executed when the user types a carriage return. .TP .CR ; Repeat the last single character find using .CR f , .CR F , .CR t , or .CR T . If a .I count is specified, the search is repeated the specified number of times. .TP .CR < An operator that shifts lines to the left by one .CR shiftwidth . The .CR < can be followed by a move to specify lines. A preceding .I count is passed through to the move command. .IP When repeated .RC ( << ), shifts the current line (or .I count lines starting at the current one). .TP .CR > An operator that shifts lines right one .CR shiftwidth (see .CR < ). .TP .CR = If the .CR lisp option is set, .CR = reindents the specified lines, as if they were typed in with .CR lisp and .CR autoindent set. .CR = can be preceded by a .I count to indicate how many lines to process, or followed by a move command for the same purpose. .TP .CR ? Scan backwards, the reverse of .CR / (see .CR / ). .TP .CI @ buffer Execute the commands stored in the named .IR buffer . Be careful not to include a character at the end of the buffer contents unless the is part of the command stream. Commands to be executed in .I ex mode should be preceded by a colon .RC ( : ). .TP .CR ~ The tilde .RC ( ~ ) switches the case of the character under the cursor (if it is a letter), then moves one character to the right, stopping at the end of the line). A preceding .I count specifies how many characters in the current line are switched. .TP .CR A Append at the end of line (same as .CR $a ). .TP .CR B Back up one word, where a word is any nonblank sequence, placing the cursor at the beginning of the word. If a .I count is specified, the cursor moves back the specified number of words. .TP .CR C Change the rest of the text on the current line (same as .CR c$ ). .TP .CR D Delete the rest of the text on the current line (same as .CR d$ ). .TP .CR E Move forward to the end of a word, where a word is any nonblank sequence. If a .I count is specified, the cursor advances the specified number of words. .TP .CR F Must be followed by a single character; scans backwards in the current line, searching for that character and moving the cursor to it, if found. If a .I count is specified, the search is repeated the specified number of times. .TP .CR G Go to the line number given as preceding argument, or the end of the file if no preceding .I count is given. .TP .CR H Move the cursor to the top line on the screen. If a .I count is given, the cursor moves to .I count number of lines from the top of the screen. The cursor is placed on the first nonwhitespace character on the line. If used as the target of an operator, entire lines are affected. .TP .CR I Insert at the beginning of a line (same as .CR ^ followed by .CR i ). .TP .CR J Join the current line with the next one, supplying appropriate whitespace: one space between words, two spaces after a period, and no spaces at all if the first character of the next line is a closing parenthesis .RC ( ) ). A preceding .I count causes the specified number of lines to be joined, instead of just two. .TP .CR L Move the cursor to the first nonwhitespace character of the last line on the screen. If a .I count is given, the cursor moves to .I count number of lines from the bottom of the screen. When used with an operator, entire lines are affected. .TP .CR M Move the cursor to the middle line on the screen, at the first nonwhitespace position on the line. .TP .CR N Scan for the next match of the last pattern given to .CR / or .CR ? , but in the opposite direction; this is the reverse of .CR n . .TP .CR O Open a new line above the current line and enter input mode. .TP .CR P Put back (replace) the last deleted or yanked text before/above the cursor. Entire lines of text are returned above the cursor if entire lines were deleted or yanked. Otherwise, the text is inserted just before the cursor. .IP (XPG4 only.) In this case, the cursor is moved to last column position of the inserted characters. .IP If .CR P is preceded by a named buffer specification .RI ( x ), the contents of that buffer are retrieved instead. .TP .CR Q Exit .CR vi and enter .CR ex command mode. .TP .CR R Replace characters on the screen with characters entered, until the input is terminated with ESC. .TP .CR S Change entire lines (same as .CR cc ). A preceding .I count changes the specified number of lines. .TP .CR T Must be followed by a single character; scan backwards in the current line for that character, and, if found, place the cursor just after that character. A .I count is equivalent to repeating the search the specified number of times. .TP .CR U Restore the current line to its state before the cursor was last moved to it. .IP (XPG4 only.) The cursor position is set to the column position 1 or to the position indicated by the previous line if the .CR autoindent is set. .TP .CR W Move forward to the beginning of a word in the current line, where a word is a sequence of nonblank characters. If the current position is at the beginning of a word, the current position is within a bigword or the character at that position cannot be a part of a bigword, the current position shall move to the first character of the next bigword. If no subsequent bigword exists on the current line, the current position shall move to the first character of the first bigword on the first following line that contains the bigword. For this command, an empty or blank line is considered to contain exactly one bigword. The current line is set to the line containing the bigword selected and the current position is set to the first character of the bigword selected. A preceding .I count specifies the number of words to advance. .TP .CR X Delete the character before the cursor. A preceding .I count repeats the effect, but only characters on the current line are deleted. .TP .CR Y Place (yank) a copy of the current line into the unnamed buffer (same as .CR yy ). If a .I count is specified, .I count lines are copied to the buffer. If the .CR Y is preceded by a buffer name, the lines are copied to the named buffer. .TP .CR ZZ Exit the editor, writing out the buffer if it was changed since the last write (same as the .CR ex command .CR x ). Note that if the last write was to a different file and no changes have occurred since, the editor exits without writing out the buffer. .TP .CR a Enter input mode, appending the entered text after the current cursor position. A preceding .I count causes the inserted text to be replicated the specified number of times, but only if the inserted text is all on one line. .TP .CR b Back up to the previous beginning of a word in the current line. A word is a sequence of alphanumerics or a sequence of special characters. A preceding .I count repeats the effect. .TP .CR c Must be followed by a movement command. Delete the specified region of text, and enter input mode to replace deleted text with new text. If more than part of a single line is affected, the deleted text is saved in the numeric buffers. If only part of the current line is affected, the last character deleted is marked with a .CR $ . A preceding .I count passes that value through to the move command. If the command is .CR cc , the entire current line is changed. .TP .CR d Must be followed by a movement command. Delete the specified region of text. If more than part of a line is affected, the text is saved in the numeric buffers. A preceding .I count passes that value through to the move command. If the command is .CR dd , the entire current line is deleted. .TP .CR e Move forward to the end of the next word, defined as for .CR b . A preceding .I count repeats the effect. .TP .CR f Must be followed by a single character; scan the rest of the current line for that character, and moves the cursor to it if found. A preceding .I count repeats the action that many times. .TP .CR h Move the cursor one character to the left (same as .CR ^H ). A preceding .I count repeats the effect. .TP .CR i Enter input mode, inserting the entered text before the cursor (see .CR a ). .TP .CR j Move the cursor one line down in the same column (same as .CR ^J and .CR ^N ). .TP .CR k Move the cursor one line up (same as .CR ^P ). .TP .CR l Move the cursor one character to the right (same as .CR ). .TP .CI m x Mark the current position of the cursor. .CI x is a lowercase letter, .CR a \(mi z , that is used with the .CR ` and .CR ' commands to refer to the marked line or line position. .TP .CR n Repeat the last .CR / or .CR ? scanning commands. .TP .CR o Open a line below the current line and enter input mode; otherwise like .CR O . .TP .CR p Put text after/below the cursor; otherwise like .CR P . .TP .CR r Must be followed by a single character; the character under the cursor is replaced by the specified one. (The new character can be a new-line.) If .CR r is preceded by a .IR count , .I count characters are replaced by the specified character. .TP .CR s Delete the single character under the cursor and enter input mode; the entered text replaces the deleted character. A preceding .I count specifies how many characters on the current line are changed. The last character being changed is marked with a .CR $ , as for .CR c . .TP .CR t Must be followed by a single character; scan the remainder of the line for that character. The cursor moves to the column prior to the character if the character is found. A preceding .I count is equivalent to repeating the search .I count times. .TP .CR u Reverse the last change made to the current buffer. If repeated, .CR u alternates between these two states; thus is its own inverse. When used after an insertion of text on more than one line, the lines are saved in the numerically named buffers. .TP .CR w Move forward to the beginning of the next word (where word is defined as in .CR b ). A preceding .I count specifies how many words the cursor advances. .TP .CR x Delete the single character under the cursor. When .CR x is preceded by a .IR count , .CR x deletes the specified number of characters forward from the cursor position, but only on the current line. .TP .CR y Must be followed by a movement command; the specified text is copied (yanked) into the unnamed temporary buffer. If preceded by a named buffer specification, .tr ~" .CI ~ x\f1, the text is placed in that buffer also. If the command is .CR yy , the entire current line is yanked. .br .tr ~~ .TP .CR z Redraw the screen with the current line placed as specified by the following options: .CR z specifies the top of the screen, .CR z. the center of the screen, and .CR z- the bottom of the screen. The commands .CR z^ and .CR z+ are similar to .CR ^B and .CR ^F , respectively. However, .CR z^ and .CR z+ do not attempt to maintain two lines of overlap. A .I count after the .CR z and before the following character to specifies the number of lines displayed in the redrawn screen. A .I count before the .CR z gives the number of the line to use as the reference line instead of the default current line. .RE .SS Keyboard Editing Keys At initialization, the editor automatically maps some terminal keyboard editing keys to equivalent visual mode commands. These mappings are only established for keys that are listed in the following table and defined in the .IR terminfo (4) database as valid for the current terminal (as specified by the .CR TERM environment variable). .PP Both command and input mode mappings are created (see the .CR map command in .IR ex (1)). With the exception of the .CR insert char keys, which simply toggle input mode on and off, the input mode mappings exit input mode, perform the same action as the command mode mapping, and then reenter input mode. .PP On certain terminals, the character sequence sent by a keyboard editing key, which is then mapped to a visual mode command, can be the same character sequence a user might enter to perform another command or set of commands. This is most likely to happen with the input mode mappings; therefore, on these terminals, the input mode mappings are disabled by default. Users can override the disabling and enabling of both the command and input mode keyboard editing key mappings by setting the .CR keyboardedit and .CR keyboardedit! editor options as appropriate (see .IR ex (1)). The .CR timeout , .CR timeoutlen , and .CR doubleescape editor options are alternative methods of addressing this problem. .PP .TS center tab(;); lB lB lB lB lB lB lB lB lB lB lf4p+1 lf4p+1 lf4p+1 lf4p+1 l. terminfo;command;input;map entry;mode map;mode map;name;description _ .sp +.5v key_ic;i;^[;inschar;insert char key_eic;i;^[;inschar;end insert char key_up;k;^[ka;up;arrow up key_down;j;^[ja;down;arrow down key_left;h;^[ha;left;arrow left key_right;l;^[la;right;arrow right key_home;H;^[Ha;home;arrow home key_il;o^[;^[o^[a;insline;insert line key_dl;dd;^[dda;delline;delete line key_clear;^L;^[^La;clear;clear screen key_eol;d$;^[d$a;clreol;clear line key_sf;^E;^[^Ea;scrollf;scroll down key_dc;x;^[xa;delchar;delete char key_npage;^F;^[^Fa;npage;next page key_ppage;^B;^[^Ba;ppage;previous page key_sr;^Y;^[^Ya;sr;scroll up key_eos;dG;^[dGa;clreos;clear to end of screen .sp +.5v _ .TE .SH EXTERNAL INFLUENCES Support for international codes and environment variables are as follows: .SS Environment Variables .CR UNIX95 specifies using the XPG4 behaviour for this command. .PP .CR COLUMNS overrides the system-selected horizontal screen size. .PP .CR LINES overrides the system-selected vertical screen size, used as the number of lines in a screenful and the vertical screen size in visual mode. .PP .CR SHELL is a variable that shall be interpreted as the preferred command-line interpreter for use in .CR ! , .CR shell , .CR read , and other commands with an operand of the form .CR !string . For the .CR shell command the program shall be invoked with the two arguments .CR -c and .CR string . If this variable is null or not set, the .CR sh utility shall be used. .PP .CR TERM is a variable that shall be interpreted as the name of the terminal type. If this variable is unset or null, an unspecified default terminal type shall be used. .PP .CR PATH determines the search path for the shell command specified in the editor commands, .CR shell , .CR read , and .CR write . .CR EXINIT determines a list of .I ex commands that will be executed on editor startup, before reading the first file. The list can contain multiple commands by separating them using a vertical line (|) character. .PP .CR HOME determines a pathname of a directory that will be searched for an editor startup file named .CR .exrc . .PP .CR LC_ALL This variable shall determine the locale to be used to override any values for locale categories specified by the setting of .CR LANG or any environment variables beginning with .CR LC_ . .PP .CR LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .CR LC_COLLATE determines the collating sequence used in evaluating regular expressions and in processing the .I tags file. .CR LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as uppercase or lowercase letters, the shifting of letters between uppercase and lowercase, and the characters matched by character class expressions in regular expressions. .PP .CR LANG determines the language in which messages are displayed. .PP .CR LANGOPTS specifies options determining how text for right-to-left languages is stored in input and output files. See .IR environ (5). .PP If .CR LC_COLLATE or .CR LC_CTYPE is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, the editor behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .SH EXAMPLES (none needed) .SH WARNINGS See also the WARNINGS section in .IR ex (1). .SS Program Limits .CR vi places the following limits on files being edited: .TP .B Maximum Line Length .CR LINE_MAX characters (defined in .CR ), including 2-3 bytes for overhead. Thus, if the value specified for .CR LINE_MAX is 2048, a line length up to 2044 characters should cause no problem. .IP If you load a file that contain lines longer than the specified limit, the lines are truncated to the stated maximum length. Saving the file will write the truncated version over the original file, thus overwriting the original lines completely. .IP Attempting to create lines longer than the allowable maximum for the editor produces a .CR "line too long" error message. .TP .B Maximum File Size The maximum file length of 234,239 lines is silently enforced. .TP .B Other limits: .RS .TP 3 \(bu 256 characters per global command list. .TP \(bu 128 characters in a file name in .CR vi or .CR ex .CR open mode. On short-file-name HP-UX systems, the maximum file name length is 14 characters. .TP \(bu 128 characters in a previous insert/delete buffer. .TP \(bu 100 characters in a shell-escape command. .TP \(bu 63 characters in a string-valued option .RC ( :set command). .TP \(bu 30 characters in a program tag name. .TP \(bu 32 or fewer macros defined by .CR map command. .TP \(bu 512 or fewer characters total in combined .CR map macros. .RE .RE .SH AUTHOR .CR vi was developed by the University of California, Berkeley. The 16-bit extensions to .CR vi are based in part on software of the Toshiba Corporation. .SH SEE ALSO ctags(1), ed(1), ex(1), stty(1), write(1), terminfo(4), environ(5), lang(5), regexp(5). .TP .IR "The Ultimate Guide to the vi and ex Text Editors" , Benjamin/Cummings Publishing Company, Inc., ISBN 0-8053-4460-8, HP part number 97005-90015. .SH STANDARDS CONFORMANCE .CR vi ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4vedit\f1 \- beginner's screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f4vi\f1 \- extended screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f4view\f1 \- read-only screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f1editor: extended screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f1screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f1text editor, screen-oriented@@@\f3vi(1)\f1 .\" .\" toc@\f3vi(1)\f1:\0\0\f4vedit\f1, \f4vi\f1, \f4view\f1@@@extended screen-oriented text editor .\" toc@\f4vedit\f1:\0\0beginner's screen-oriented text editor@@@see \f3vi(1)\f1 .\" toc@\f4view\f1:\0\0read-only screen-oriented text editor@@@see \f3vi(1)\f1 .\" .\" links@vi.1 vedit.1 .\" links@vi.1 view.1 .\" $Header: vi.1,v 78.1 96/02/12 14:21:12 ssa Exp $ .TA v .TH vi 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vi, view, vedit \- screen-oriented (visual) text editor .SH SYNOPSIS .CR vi .RC [ - ] .RC [ -l ] .RC [ -r ] .RC [ -R ] .RC [ -t .IR tag ] .RC [ -v ] .RC [ -V ] .RC [ -w\c .IR size ] .RC [ -x ] .RC [ +\c .IR command ] .RI [ file " ...]" .PP .SS "XPG4 Synopsis" .CR vi .RC [ -rR ] .RC [ -c .IR command ] .RC [ -t .IR tag ] .RC [ -w .IR size ] .RI [ file " ...]" .PP .SS Obsolescent Options .PP .CR vi .RC [ -rR ] .RC [+\c .IR command ] .RC [ -t .IR tag ] .RC [ -w .IR size ] .RI [ file " ...]" .PP .CR view .RC [ - ] .RC [ -l ] .RC [ -r ] .RC [ -R ] .RC [ -t .IR tag ] .RC [ -v ] .RC [ -V ] .RC [ -w\c .IR size ] .RC [ -x ] .RC [ +\c .IR command ] .RI [ file " ...]" .PP .CR vedit .RC [ - ] .RC [ -r ] .RC [ -R ] .RC [ -l ] .RC [ -t .IR tag ] .RC [ -v ] .RC [ -V ] .RC [ -w\c .IR size ] .RC [ -x ] .RC [ +\c .IR command ] .RI [ file " ...]" .SS Remarks The program names .CR ex , .CR edit , .CR vi , .CR view , and .CR vedit are separate personalities of the same program. This manual entry describes the behavior of the .CR vi / view / vedit personality. .SH DESCRIPTION The .CR vi (visual) program is a display-oriented text editor that is based on the underlying .CR ex line editor (see .IR ex (1)). It is possible to switch back and forth between the two and to execute .CR ex commands from within .CR vi . The line-editor commands and the editor options are described in .IR ex (1). Only the visual mode commands are described here. .PP The .CR view program is identical to .CR vi except that the .CR readonly editor option is set (see .IR ex (1)). .PP The .CR vedit program is somewhat friendlier for beginners and casual users. The .CR report editor option is set to .CR 1 , and the .CR nomagic , .CR novice , and .CR showmode editor options are set. .PP In .CR vi , the terminal screen acts as a window into a memory copy of the file being edited. Changes made to the file copy are reflected in the screen display. The position of the cursor on the screen indicates the position within the file copy. .PP The environment variable .CR TERM must specify a terminal type that is defined in the .CR terminfo database (see .IR terminfo (4)). Otherwise, a message is displayed and the line-editor is invoked. .PP As with .CR ex , editor initialization scripts can be placed in the environment variable .CR EXINIT , or in the file .CR .exrc in the current or home directory. .SS Options and Arguments .CR vi recognizes the following command-line options and arguments: .RS .ifn .TP 10 .ift .TP 15 .CR - Suppress all interactive-user feedback. This is useful when editor commands are taken from scripts. .TP .CR -l Set the .CR lisp editor option (see .IR ex (1)). Provides indents appropriate for .CR lisp code. The .CR ( , .CR ) , .CR { , .CR } , .CR [[ , and .CR ]] commands in .CR vi are modified to function with .CR lisp source code. .TP .CR -r Recover the specified .IR file s after an editor or system crash. If no .I file is specified, a list of all saved files is printed. You must be the owner of the saved file in order to recover it (superuser cannot recover files owned by other users). .TP .CR -R Set the .CR readonly editor option to prevent overwriting a file inadvertently (see .IR ex (1)). .TP .CI -t " tag" Execute the .CR tag .IR tag command to load and position a predefined file. See the .CR tag command and the .CR tags editor option in .IR ex (1). .TP .CR -v Invoke visual mode .RC ( vi ). Useful with .CR ex , it has no effect on .CR vi . .TP .CR -V Set verbose mode. Editor commands are displayed as they are executed when input from a .CR .exrc file or a source file (see the .CR source command in .IR ex (1)). .TP .CI -w size Set the value of the .CR window editor option to .IR size . If .IR size is omitted, it defaults to .CR 3 . .TP .CR -x Set encryption mode. You are prompted for a key to allow for the creation or editing of an encrypted file (see the .CR crypt command in .IR ex (1)). .ifn .TP 12 .ift .TP 15 .CI -c " command" (XPG4 only.) .ifn .TP 10 .ift .TP 15 .CI + command (Obsolescent) Begin editing by executing the specified .CR ex command-mode commands. As with the normal .CR ex command-line entries, the .CR command option-argument can consist of multiple .CR ex commands separated by vertical-line commands (|). The use of commands that enter input mode in this manner produces undefined results. .TP .I file Specify the file or files to be edited. If more than one .I file is specified, they are processed in the order given. If the .CR -r option is also specified, the files are read from the recovery area. .RE .PP (XPG4 only.) If both the .CR -t " tag " and .CR -c " command " .C "(or the obsolescent +command)" options are given, the .CR -t " tag " will be processed first, that is, the file containing the tag is selected by .CR -t and then the command is executed. .RE .PP When invoked, .CR vi is in .BR "command mode" . .BR "input mode" is initiated by several commands used to insert or change text. .PP In input mode, ESC (escape) is used to leave input mode; however, two consecutive ESC characters are required to leave input mode if the .CR doubleescape editor option is set (see .IR ex (1)). .PP In command mode, ESC is used to cancel a partial command; the terminal bell sounds if the editor is not in input mode and there is no partially entered command. .PP .B WARNING: ESC .I completes a "bottom line" command (see below). .PP The last (bottom) line of the screen is used to echo the input for search commands .RC ( / and .CR ? ), .CR ex commands .RC ( : ), and system commands .RC ( ! ). It is also used to report errors or print other messages. .PP The receipt of .CR SIGINT during text input or during the input of a command on the bottom line terminates the input (or cancels the command) and returns the editor to command mode. During command mode, .CR SIGINT causes the bell to be sounded. In general the bell indicates an error (such as an unrecognized key). .PP Lines displayed on the screen containing only a .CR ~ indicate that the last line above them is the last line of the file (the .CR ~ lines are past the end of the file). Terminals with limited local intelligence might display lines on the screen marked with an .CR @ . These indicate space on the screen not corresponding to lines in the file. (These lines can be removed by entering a .CR ^R , forcing the editor to retype the screen without these holes.) .PP If the system crashes or .CR vi aborts due to an internal error or unexpected signal, .CR vi attempts to preserve the buffer if any unwritten changes were made. Use the .CR -r command line option to retrieve the saved changes. .PP The .CR vi text editor supports the .CR SIGWINCH signal, and redraws the screen in response to window-size changes. .SS Command Summary Most commands accept a preceding number as an argument, either to give a size or position (for display or movement commands), or as a repeat count (for commands that change text). For simplicity, this optional argument is referred to as .I count when its effect is described. .PP The following operators can be followed by a movement command to specify an extent of text to be affected: .CR c , .CR d , .CR y , .CR < , .CR > , .CR ! , and .CR = . The region specified begins at the current cursor position and ends just prior to the cursor position indicated by the move. If the command operates on lines only, all the lines that fall partly or wholly within this region are affected. Otherwise the exact marked region is affected. .PP In the following description, control characters are indicated in the form .CR ^X , which represents .RC Ctrl- X . Whitespace is defined to be the characters space, tab, and alternative space. Alternative space is the first character of the .CR ALT_PUNCT item described in .IR langinfo (5) for the language specified by the .CR LANG environment variable (see .IR environ (5)). .PP Unless otherwise specified, the commands are interpreted in command mode and have no special effect in input mode. .RS .TP 12 .CR ^B Scroll backward to display the previous window of text. A preceding .I count specifies the number of windows to go back. Two lines of overlap are kept if possible. .TP .CR ^D Scroll forward a half-window of text. A preceding .I count gives the number of (logical) lines to scroll, and is remembered for future .CR ^D and .CR ^U commands. .TP .CR ^D (input mode) Backs up over the indentation provided by .CR autoindent or .CR ^T to the next multiple of .CR shiftwidth spaces. Whitespace inserted by .CR ^T at other than the beginning of a line cannot be backed over using .CR ^D . A preceding .CR ^ removes all indentation for the current and subsequent input lines of the current input mode until new indentation is established by inserting leading whitespace, either by direct input or by using .CR ^T . .TP .CR ^E Scroll forward one line, leaving the cursor where it is if possible. .TP .CR ^F Scroll forward to display the window of text following the current one. A preceding .I count specifies the number of windows to advance. Two lines of overlap are kept if possible. .IP (XPG4 only.) The current line is displayed and the cursor is moved to the first nonblank character of the current line or the first character if the line is a blank line. .TP .CR ^G Print the current file name and other information, including the number of lines and the current position (equivalent to the .CR ex command .CR f ). .TP .CR ^H Move one space to the left (stops at the left margin). A preceding .I count specifies the number of spaces to back up. (Same as .CR h ). .TP .CR ^H (input mode) Move the cursor left to the previous input character without erasing it from the screen. The character is deleted from the saved text. .TP .CR ^J Move the cursor down one line in the same column, if possible. A preceding .I count specifies the number of lines to move down. (Same as .CR ^N and .CR j ). .TP .CR ^L Clear and redraw the screen. Use when the screen is scrambled for any reason. .TP .CR ^M Move to the first nonwhitespace character in the next line. A preceding .I count specifies the number of lines to advance. .TP .CR ^N Same as .CR ^J and .CR j . .TP .CR ^P Move the cursor up one line in the same column. A preceding .I count specifies the number of lines to move up (same as .CR k ). .TP .CR ^R Redraw the current screen, eliminating the false lines marked with .C @ (which do not correspond to actual lines in the file). .TP .CR ^T Pop the tag stack. See the .CR pop command in .IR ex (1). .TP .CR ^T (input mode) Insert .CR shiftwidth whitespace. If at the beginning of the line, this inserted space can only be backed over using .CR ^D . .TP .CR ^U Scroll up a half-window of text. A preceding .I count gives the number of (logical) lines to scroll, and is remembered for future .CR ^D and .CR ^U commands. .TP .CR ^V In input mode, .CR ^V quotes the next character to permit the insertion of special characters (including ESC) into the file. .TP .CR ^W In input mode, .CR ^W backs up one word; the deleted characters remain on the display. .TP .CR ^Y Scroll backward one line, leaving the cursor where it is, if possible. .TP .CR ^[ Cancel a partially formed command; .CR ^[ sounds the bell if there is no partially formed command. .IP In input mode, .CR ^[ terminates input mode. However, two consecutive ESC characters are required to terminate input mode if the .CR doubleescape editor option is set (see .IR ex (1)). .IP When entering a command on the bottom line of the screen .RC ( ex command line or search pattern with .CR \e or .CR ? ), terminate input and execute command. .IP On many terminals, .CR ^[ can be entered by pressing the ESC or ESCAPE key. .TP .CR ^\e Exit .CR vi and enter .I ex command mode. If in input mode, terminate the input first. .TP .CR ^] Take the word at or after the cursor as a tag and execute the .CR tag MbobC editor command (see .IR ex (1)). .TP .CR ^^ Return to the previous file (equivalent to .CR ":ex #" ). .TP .I space Move one space to the right (stops at the end of the line). A preceding .I count specifies the number of spaces to go forward (same as .CR l ). .TP .I erase Erase, where .I erase is the user-designated erase character (see .IR stty (1)). Same as .CR ^H . .TP .I kill Kill, where .I kill is the user-designated kill character (see .IR stty (1)). In input mode, .I kill backs up to the beginning of the current input line without erasing the line from the screen display. .TP .I susp Suspend the editor session and return to the calling shell, where .I susp is the user-designated process-control suspend character (see .IR stty (1)). See .IR ex (1) for more information on the .CR suspend editor command. .TP .CR ! An operator that passes specified lines from the buffer as standard input to the specified system command, and replaces those lines with the standard output from the command. The .CR ! is followed by a movement command specifying the lines to be passed (lines from the current position to the end of the movement) and then the command (terminated as usual by a return). A preceding .I count is passed on to the movement command after .CR ! . .IP Doubling .CR ! and preceding it by .I count causes that many lines, starting with the current line, to be passed. .TP .C """" Use to precede a named buffer specification. There are named buffers .CR 1 through .CR 9 in which the editor places deleted text. The named buffers .CR a through .CR z are available to the user for saving deleted or yanked text; see also .CR y , below. .TP .CR $ Move to the end of the current line. A preceding .I count specifies the number of lines to advance (for example, .CR 2$ causes the cursor to advance to the end of the next line). .TP .CR % Move to the parenthesis or brace that matches the parenthesis or brace at the current cursor position. .TP .CR & Same as the .I ex command .CR & (that is, .CR & repeats the previous .CR substitute command). .TP .CR ' When followed by a .CR ' , .CR vi returns to the previous context, placing the cursor at the beginning of the line. (The previous context is set whenever a nonrelative move is made.) When followed by a letter .CR a - z , returns to the line marked with that letter (see the .CR m command), at the first nonwhitespace character in the line. .IP When used with an operator such as .CR d to specify an extent of text, the operation takes place over complete lines (see also .CR ` ). .TP .CR ` When followed by a .CR ` , .CR vi returns to the previous context, placing the cursor at the character position marked (the previous context is set whenever a nonrelative move is made). When followed by a letter .CR a .CR z , returns to the line marked with that letter (see the .CR m command), at the character position marked. .IP When used with an operator such as .CR d to specify an extent of text, the operation takes place from the exact marked place to the current position within the line (see also .CR ' ). .TP .CR [[ Back up to the previous section boundary. A section is defined by the value of the .CR sections option. Lines that start with a form feed .RC ( ^L ) or .CR { also stop .CR [[ . .IP If the option .CR lisp is set, the cursor stops at each .CR ( at the beginning of a line. .TP .C ]] Move forward to a section boundary (see .CR [[ ). .TP .CR ^ Move to the first nonwhitespace position on the current line. .TP .CR ( Move backward to the beginning of a sentence. A sentence ends at a .CR . , .CR ! , or .CR ? followed by either the end of a line or by two spaces. Any number of closing .CR ) , .CR ] , .tr ~" \"translate begin .CR ~ , \" prints as '"' and .CR ' characters can appear between the .CR . , .CR ! , or .CR ? and the spaces or end of line. If a .I count is specified, the cursor moves back the specified number of sentences. .br .tr ~~ \"translate end .IP If the .CR lisp option is set, the cursor moves to the beginning of a .CR lisp .IR s -expression. Sentences also begin at paragraph and section boundaries (see .CR { and .CR [[ ). .TP .CR ) Move forward to the beginning of a sentence. If a .I count is specified, the cursor advances the specified number of sentences (see .CR ( ). .TP .CR { Move back to the beginning of the preceding paragraph. A paragraph is defined by the value of the .CR paragraphs option. A completely empty line and a section boundary (see .CR [[ above) are also interpreted as the beginning of a paragraph. If a .I count is specified, the cursor moves backward the specified number of paragraphs. .TP .CR } Move forward to the beginning of the next paragraph. If a .I count is specified, the cursor advances the specified number of paragraphs (see .CR { ). .TP .CR | Requires a preceding .IR count ; the cursor moves to the specified column of the current line (if possible). .TP .CR + Move to the first nonwhitespace character in the next line. If a .I count is specified, the cursor advances the specified number of lines (same as .CR ^M ). .TP .CR , The comma .RC ( , ) performs the reverse action of the last .CR f , .CR F , .CR t , or .CR T command issued, by searching in the opposite direction on the current line. If a .I count is specified, the cursor repeats the search the specified number of times. .TP .CR - The hyphen character .RC ( - ) moves the cursor to the first nonwhitespace character in the previous line. If a .I count is specified, the cursor moves back the specified number of times. .TP .CR _ The underscore character .RC ( _ ) moves the cursor to the first nonwhitespace character in the current line. If a .I count is specified, the cursor advances the specified number of lines, with the current line being counted as the first line; no .I count or a .I count of 1 specifies the current line. .TP .CR . Repeat the last command that changed the buffer. If a .I count is specified, the command is repeated the specified number of times. .TP .CR / Read a string from the last line on the screen, interpret it as a regular expression, and scan forward for the next occurrence of a matching string. The search begins when the user types a carriage return to terminate the pattern; the search can be terminated by sending .CR SIGINT (or the user-designated interrupt character). .IP When used with an operator to specify an extent of text, the defined region begins with the current cursor position and ends at the beginning of the matched string. Entire lines can be specified by giving an offset from the matched line (by using a closing .CR / followed by a .CI + n or .CI - n\c ). .TP .CR 0 Move to the first character on the current line (the .CR 0 is not interpreted as a command when preceded by a nonzero digit). .TP .CR : The colon character .RC ( : ) begins an .CR ex command. The .CR : and the entered command are echoed on the bottom line; the .CR ex command is executed when the user types a carriage return. .TP .CR ; Repeat the last single character find using .CR f , .CR F , .CR t , or .CR T . If a .I count is specified, the search is repeated the specified number of times. .TP .CR < An operator that shifts lines to the left by one .CR shiftwidth . The .CR < can be followed by a move to specify lines. A preceding .I count is passed through to the move command. .IP When repeated .RC ( << ), shifts the current line (or .I count lines starting at the current one). .TP .CR > An operator that shifts lines right one .CR shiftwidth (see .CR < ). .TP .CR = If the .CR lisp option is set, .CR = reindents the specified lines, as if they were typed in with .CR lisp and .CR autoindent set. .CR = can be preceded by a .I count to indicate how many lines to process, or followed by a move command for the same purpose. .TP .CR ? Scan backwards, the reverse of .CR / (see .CR / ). .TP .CI @ buffer Execute the commands stored in the named .IR buffer . Be careful not to include a character at the end of the buffer contents unless the is part of the command stream. Commands to be executed in .I ex mode should be preceded by a colon .RC ( : ). .TP .CR ~ The tilde .RC ( ~ ) switches the case of the character under the cursor (if it is a letter), then moves one character to the right, stopping at the end of the line). A preceding .I count specifies how many characters in the current line are switched. .TP .CR A Append at the end of line (same as .CR $a ). .TP .CR B Back up one word, where a word is any nonblank sequence, placing the cursor at the beginning of the word. If a .I count is specified, the cursor moves back the specified number of words. .TP .CR C Change the rest of the text on the current line (same as .CR c$ ). .TP .CR D Delete the rest of the text on the current line (same as .CR d$ ). .TP .CR E Move forward to the end of a word, where a word is any nonblank sequence. If a .I count is specified, the cursor advances the specified number of words. .TP .CR F Must be followed by a single character; scans backwards in the current line, searching for that character and moving the cursor to it, if found. If a .I count is specified, the search is repeated the specified number of times. .TP .CR G Go to the line number given as preceding argument, or the end of the file if no preceding .I count is given. .TP .CR H Move the cursor to the top line on the screen. If a .I count is given, the cursor moves to .I count number of lines from the top of the screen. The cursor is placed on the first nonwhitespace character on the line. If used as the target of an operator, entire lines are affected. .TP .CR I Insert at the beginning of a line (same as .CR ^ followed by .CR i ). .TP .CR J Join the current line with the next one, supplying appropriate whitespace: one space between words, two spaces after a period, and no spaces at all if the first character of the next line is a closing parenthesis .RC ( ) ). A preceding .I count causes the specified number of lines to be joined, instead of just two. .TP .CR L Move the cursor to the first nonwhitespace character of the last line on the screen. If a .I count is given, the cursor moves to .I count number of lines from the bottom of the screen. When used with an operator, entire lines are affected. .TP .CR M Move the cursor to the middle line on the screen, at the first nonwhitespace position on the line. .TP .CR N Scan for the next match of the last pattern given to .CR / or .CR ? , but in the opposite direction; this is the reverse of .CR n . .TP .CR O Open a new line above the current line and enter input mode. .TP .CR P Put back (replace) the last deleted or yanked text before/above the cursor. Entire lines of text are returned above the cursor if entire lines were deleted or yanked. Otherwise, the text is inserted just before the cursor. .IP (XPG4 only.) In this case, the cursor is moved to last column position of the inserted characters. .IP If .CR P is preceded by a named buffer specification .RI ( x ), the contents of that buffer are retrieved instead. .TP .CR Q Exit .CR vi and enter .CR ex command mode. .TP .CR R Replace characters on the screen with characters entered, until the input is terminated with ESC. .TP .CR S Change entire lines (same as .CR cc ). A preceding .I count changes the specified number of lines. .TP .CR T Must be followed by a single character; scan backwards in the current line for that character, and, if found, place the cursor just after that character. A .I count is equivalent to repeating the search the specified number of times. .TP .CR U Restore the current line to its state before the cursor was last moved to it. .IP (XPG4 only.) The cursor position is set to the column position 1 or to the position indicated by the previous line if the .CR autoindent is set. .TP .CR W Move forward to the beginning of a word in the current line, where a word is a sequence of nonblank characters. If the current position is at the beginning of a word, the current position is within a bigword or the character at that position cannot be a part of a bigword, the current position shall move to the first character of the next bigword. If no subsequent bigword exists on the current line, the current position shall move to the first character of the first bigword on the first following line that contains the bigword. For this command, an empty or blank line is considered to contain exactly one bigword. The current line is set to the line containing the bigword selected and the current position is set to the first character of the bigword selected. A preceding .I count specifies the number of words to advance. .TP .CR X Delete the character before the cursor. A preceding .I count repeats the effect, but only characters on the current line are deleted. .TP .CR Y Place (yank) a copy of the current line into the unnamed buffer (same as .CR yy ). If a .I count is specified, .I count lines are copied to the buffer. If the .CR Y is preceded by a buffer name, the lines are copied to the named buffer. .TP .CR ZZ Exit the editor, writing out the buffer if it was changed since the last write (same as the .CR ex command .CR x ). Note that if the last write was to a different file and no changes have occurred since, the editor exits without writing out the buffer. .TP .CR a Enter input mode, appending the entered text after the current cursor position. A preceding .I count causes the inserted text to be replicated the specified number of times, but only if the inserted text is all on one line. .TP .CR b Back up to the previous beginning of a word in the current line. A word is a sequence of alphanumerics or a sequence of special characters. A preceding .I count repeats the effect. .TP .CR c Must be followed by a movement command. Delete the specified region of text, and enter input mode to replace deleted text with new text. If more than part of a single line is affected, the deleted text is saved in the numeric buffers. If only part of the current line is affected, the last character deleted is marked with a .CR $ . A preceding .I count passes that value through to the move command. If the command is .CR cc , the entire current line is changed. .TP .CR d Must be followed by a movement command. Delete the specified region of text. If more than part of a line is affected, the text is saved in the numeric buffers. A preceding .I count passes that value through to the move command. If the command is .CR dd , the entire current line is deleted. .TP .CR e Move forward to the end of the next word, defined as for .CR b . A preceding .I count repeats the effect. .TP .CR f Must be followed by a single character; scan the rest of the current line for that character, and moves the cursor to it if found. A preceding .I count repeats the action that many times. .TP .CR h Move the cursor one character to the left (same as .CR ^H ). A preceding .I count repeats the effect. .TP .CR i Enter input mode, inserting the entered text before the cursor (see .CR a ). .TP .CR j Move the cursor one line down in the same column (same as .CR ^J and .CR ^N ). .TP .CR k Move the cursor one line up (same as .CR ^P ). .TP .CR l Move the cursor one character to the right (same as .CR ). .TP .CI m x Mark the current position of the cursor. .CI x is a lowercase letter, .CR a \(mi z , that is used with the .CR ` and .CR ' commands to refer to the marked line or line position. .TP .CR n Repeat the last .CR / or .CR ? scanning commands. .TP .CR o Open a line below the current line and enter input mode; otherwise like .CR O . .TP .CR p Put text after/below the cursor; otherwise like .CR P . .TP .CR r Must be followed by a single character; the character under the cursor is replaced by the specified one. (The new character can be a new-line.) If .CR r is preceded by a .IR count , .I count characters are replaced by the specified character. .TP .CR s Delete the single character under the cursor and enter input mode; the entered text replaces the deleted character. A preceding .I count specifies how many characters on the current line are changed. The last character being changed is marked with a .CR $ , as for .CR c . .TP .CR t Must be followed by a single character; scan the remainder of the line for that character. The cursor moves to the column prior to the character if the character is found. A preceding .I count is equivalent to repeating the search .I count times. .TP .CR u Reverse the last change made to the current buffer. If repeated, .CR u alternates between these two states; thus is its own inverse. When used after an insertion of text on more than one line, the lines are saved in the numerically named buffers. .TP .CR w Move forward to the beginning of the next word (where word is defined as in .CR b ). A preceding .I count specifies how many words the cursor advances. .TP .CR x Delete the single character under the cursor. When .CR x is preceded by a .IR count , .CR x deletes the specified number of characters forward from the cursor position, but only on the current line. .TP .CR y Must be followed by a movement command; the specified text is copied (yanked) into the unnamed temporary buffer. If preceded by a named buffer specification, .tr ~" .CI ~ x\f1, the text is placed in that buffer also. If the command is .CR yy , the entire current line is yanked. .br .tr ~~ .TP .CR z Redraw the screen with the current line placed as specified by the following options: .CR z specifies the top of the screen, .CR z. the center of the screen, and .CR z- the bottom of the screen. The commands .CR z^ and .CR z+ are similar to .CR ^B and .CR ^F , respectively. However, .CR z^ and .CR z+ do not attempt to maintain two lines of overlap. A .I count after the .CR z and before the following character to specifies the number of lines displayed in the redrawn screen. A .I count before the .CR z gives the number of the line to use as the reference line instead of the default current line. .RE .SS Keyboard Editing Keys At initialization, the editor automatically maps some terminal keyboard editing keys to equivalent visual mode commands. These mappings are only established for keys that are listed in the following table and defined in the .IR terminfo (4) database as valid for the current terminal (as specified by the .CR TERM environment variable). .PP Both command and input mode mappings are created (see the .CR map command in .IR ex (1)). With the exception of the .CR insert char keys, which simply toggle input mode on and off, the input mode mappings exit input mode, perform the same action as the command mode mapping, and then reenter input mode. .PP On certain terminals, the character sequence sent by a keyboard editing key, which is then mapped to a visual mode command, can be the same character sequence a user might enter to perform another command or set of commands. This is most likely to happen with the input mode mappings; therefore, on these terminals, the input mode mappings are disabled by default. Users can override the disabling and enabling of both the command and input mode keyboard editing key mappings by setting the .CR keyboardedit and .CR keyboardedit! editor options as appropriate (see .IR ex (1)). The .CR timeout , .CR timeoutlen , and .CR doubleescape editor options are alternative methods of addressing this problem. .PP .TS center tab(;); lB lB lB lB lB lB lB lB lB lB lf4p+1 lf4p+1 lf4p+1 lf4p+1 l. terminfo;command;input;map entry;mode map;mode map;name;description _ .sp +.5v key_ic;i;^[;inschar;insert char key_eic;i;^[;inschar;end insert char key_up;k;^[ka;up;arrow up key_down;j;^[ja;down;arrow down key_left;h;^[ha;left;arrow left key_right;l;^[la;right;arrow right key_home;H;^[Ha;home;arrow home key_il;o^[;^[o^[a;insline;insert line key_dl;dd;^[dda;delline;delete line key_clear;^L;^[^La;clear;clear screen key_eol;d$;^[d$a;clreol;clear line key_sf;^E;^[^Ea;scrollf;scroll down key_dc;x;^[xa;delchar;delete char key_npage;^F;^[^Fa;npage;next page key_ppage;^B;^[^Ba;ppage;previous page key_sr;^Y;^[^Ya;sr;scroll up key_eos;dG;^[dGa;clreos;clear to end of screen .sp +.5v _ .TE .SH EXTERNAL INFLUENCES Support for international codes and environment variables are as follows: .SS Environment Variables .CR UNIX95 specifies using the XPG4 behaviour for this command. .PP .CR COLUMNS overrides the system-selected horizontal screen size. .PP .CR LINES overrides the system-selected vertical screen size, used as the number of lines in a screenful and the vertical screen size in visual mode. .PP .CR SHELL is a variable that shall be interpreted as the preferred command-line interpreter for use in .CR ! , .CR shell , .CR read , and other commands with an operand of the form .CR !string . For the .CR shell command the program shall be invoked with the two arguments .CR -c and .CR string . If this variable is null or not set, the .CR sh utility shall be used. .PP .CR TERM is a variable that shall be interpreted as the name of the terminal type. If this variable is unset or null, an unspecified default terminal type shall be used. .PP .CR PATH determines the search path for the shell command specified in the editor commands, .CR shell , .CR read , and .CR write . .CR EXINIT determines a list of .I ex commands that will be executed on editor startup, before reading the first file. The list can contain multiple commands by separating them using a vertical line (|) character. .PP .CR HOME determines a pathname of a directory that will be searched for an editor startup file named .CR .exrc . .PP .CR LC_ALL This variable shall determine the locale to be used to override any values for locale categories specified by the setting of .CR LANG or any environment variables beginning with .CR LC_ . .PP .CR LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .CR LC_COLLATE determines the collating sequence used in evaluating regular expressions and in processing the .I tags file. .CR LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as uppercase or lowercase letters, the shifting of letters between uppercase and lowercase, and the characters matched by character class expressions in regular expressions. .PP .CR LANG determines the language in which messages are displayed. .PP .CR LANGOPTS specifies options determining how text for right-to-left languages is stored in input and output files. See .IR environ (5). .PP If .CR LC_COLLATE or .CR LC_CTYPE is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, the editor behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .SH EXAMPLES (none needed) .SH WARNINGS See also the WARNINGS section in .IR ex (1). .SS Program Limits .CR vi places the following limits on files being edited: .TP .B Maximum Line Length .CR LINE_MAX characters (defined in .CR ), including 2-3 bytes for overhead. Thus, if the value specified for .CR LINE_MAX is 2048, a line length up to 2044 characters should cause no problem. .IP If you load a file that contain lines longer than the specified limit, the lines are truncated to the stated maximum length. Saving the file will write the truncated version over the original file, thus overwriting the original lines completely. .IP Attempting to create lines longer than the allowable maximum for the editor produces a .CR "line too long" error message. .TP .B Maximum File Size The maximum file length of 234,239 lines is silently enforced. .TP .B Other limits: .RS .TP 3 \(bu 256 characters per global command list. .TP \(bu 128 characters in a file name in .CR vi or .CR ex .CR open mode. On short-file-name HP-UX systems, the maximum file name length is 14 characters. .TP \(bu 128 characters in a previous insert/delete buffer. .TP \(bu 100 characters in a shell-escape command. .TP \(bu 63 characters in a string-valued option .RC ( :set command). .TP \(bu 30 characters in a program tag name. .TP \(bu 32 or fewer macros defined by .CR map command. .TP \(bu 512 or fewer characters total in combined .CR map macros. .RE .RE .SH AUTHOR .CR vi was developed by the University of California, Berkeley. The 16-bit extensions to .CR vi are based in part on software of the Toshiba Corporation. .SH SEE ALSO ctags(1), ed(1), ex(1), stty(1), write(1), terminfo(4), environ(5), lang(5), regexp(5). .TP .IR "The Ultimate Guide to the vi and ex Text Editors" , Benjamin/Cummings Publishing Company, Inc., ISBN 0-8053-4460-8, HP part number 97005-90015. .SH STANDARDS CONFORMANCE .CR vi ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4vedit\f1 \- beginner's screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f4vi\f1 \- extended screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f4view\f1 \- read-only screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f1editor: extended screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f1screen-oriented text editor@@@\f3vi(1)\f1 .\" index@\f1text editor, screen-oriented@@@\f3vi(1)\f1 .\" .\" toc@\f3vi(1)\f1:\0\0\f4vedit\f1, \f4vi\f1, \f4view\f1@@@extended screen-oriented text editor .\" toc@\f4vedit\f1:\0\0beginner's screen-oriented text editor@@@see \f3vi(1)\f1 .\" toc@\f4view\f1:\0\0read-only screen-oriented text editor@@@see \f3vi(1)\f1 .\" .\" links@vi.1 vedit.1 .\" links@vi.1 view.1 .\" $Header: vis.1,v 76.1 95/07/11 13:47:55 ssa Exp $ .TA v .TH vis 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vis, inv \- make unprintable and non-ASCII characters in a file visible or invisible .SH SYNOPSIS .C vis .RC [ -n ] .RC [ -s ] .RC [ -t ] .RC [ -u ] .RC [ -x ] .IR file \ .\|.\|. .br .C inv .RC [ -n ] .RC [ -s ] .RC [ -t ] .RC [ -u ] .RC [ -x ] .IR file \ .\|.\|. .SH DESCRIPTION .C vis reads characters from each .I file in sequence and writes them to the standard output, converting those that are not printable or not ASCII into a visible form. .I inv performs the inverse function, reading printable characters from each .IR file , returning them to non-printable or non-ASCII form, if appropriate, then writing them to standard output; .PP Non-printable ASCII characters are represented using C-like escape conventions: .RS .PD 0 .TP 8 .C \e\e backslash .TP .C \eb backspace .TP .C \ee escape .TP .C \ef form-feed .TP .C \en new-line .TP .C \er carriage return .TP .C \es space .TP .C \et horizontal tab .TP .C \ev vertical tab .TP .CI \e n the character whose .SM ASCII code is the 3-digit octal number .IR n . .TP .CI \ex n the character whose .SM ASCII code is the 2-digit hexadecimal number .IR n . .RE .PD .PP Non-ASCII single- or multi-byte characters are examined one byte at a time. For each byte, if it can be displayed as an ASCII character, it is treated as if it is an ASCII character; Otherwise, it is represented in the following conventions: .RS .PD 0 .TP 8 .CI \e n the 8-bit character whose code value is the 3-digit octal number .IR n . .TP .CI \ex n the 8-bit character whose code value is the 2-digit hexadecimal number .IR n . .RE .PD .PP Space, horizontal-tab, and new-line characters can be treated as printable (and therefore passed unaltered to the output) or non-printable depending on the options selected. Backslash, although printable, is expanded by .IR vis , to a pair of backslashes so that when they are passed back through .IR inv , they convert back to a single backslash. .PP If no input file is given, or if the argument .C - is encountered, .C vis and .I inv read from the standard input. .SS Options .C vis and .C inv recognize the following options: .RS .TP 8 .C -n Treat new-line, space, and horizontal tab as non-printable characters. .C vis expands them visibly as .CR \en , .CR \es , and .CR \et , rather than passing them directly to the output. .C inv discards these characters, expecting only the printable expansions. New-line characters are inserted by .C vis every 16 bytes so that the output will be in a form that is usable by most editors. .TP .C -s Make .C vis and .C inv silent about non-existent files, identical input and output, and write errors. Normally, no input file can be the same as the output file unless it is a special file. .TP .C -t Treat horizontal-tab and space characters as non-printable in the same manner that .C -n treats them. .TP .C -u Cause output to be unbuffered (byte-by-byte); normally, output is buffered. .TP .C -x Cause .C vis output to be in hexadecimal form rather than the default octal form. Either form is accepted to .C inv as input. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the language in which messages are displayed. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH AUTHOR .C vis was developed by HP. .SH SEE ALSO cat(1), echo(1), od(1). .SH WARNINGS Redirecting output to an input file destroys the original data. Therefore, command forms such as .IP .C vis\0file1\0file2\0>file1 .PP should be avoided unless the source file can be safely discarded. .\" .\" index@\f4vis\f1 \- make unprintable and non-ASCII characters in a file visible@@@\f3vis(1)\f1 .\" index@\f4inv\f1 \- make unprintable and non-ASCII characters in a file invisible@@@\f3vis(1)\f1 .\" index@\f1make unprintable and non-ASCII characters in a file visible or invisible@@@\f3vis(1)\f1 .\" index@\f1files: make unprintable and non-ASCII characters in a file visible or invisible@@@\f3vis(1)\f1 .\" index@\f1unprintable characters in a file, make visible or invisible@@@\f3vis(1)\f1 .\" index@\f1non-ASCII characters in a file, make visible or invisible@@@\f3vis(1)\f1 .\" index@\f1characters in a file, unprintable and non-ASCII, make visible or invisible@@@\f3vis(1)\f1 .\" .\" toc@\f3vis(1)\f1:\0\0\f4vis\f1, \f4inv\f1@@@make unprintable and non-ASCII characters in a file visible or invisible .\" toc@\f4inv\f1: make unprintable and non-ASCII characters in a file invisible@@@see \f3vis(1)\f1 .\" .\" links@vis.1 inv.1 .\" .\" $Header: vmstat.1,v 72.6 94/10/20 10:49:32 ssa Exp $ .TA v .TH vmstat 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vmstat \- report virtual memory statistics .SH SYNOPSIS .CR vmstat .RC [ \-dnS ] .RI [ interval .RI [ count ]\|] .PP .CR vmstat .CR \-f \(or .CR \-s \(or .CR \-z .SH DESCRIPTION The .CR vmstat command reports certain statistics kept about process, virtual memory, trap, and CPU activity. It also can clear the accumulators in the kernel .CR sum structure. .SS Options .CR vmstat recognizes the following options: .RS .TP 10 .CR \-d Report disk transfer information as a separate section, in the form of transfers per second. .TP .CR \-n Provide an output format that is more easily viewed on an 80-column display device. This format separates the default output into two groups: virtual memory information and CPU data. Each group is displayed as a separate line of output. On multiprocessor systems, this display format also provides CPU utilization on a per CPU basis. .TP .CR \-S Report the number of processes swapped in and out .RC ( si and .CR so ) instead of page reclaims and address translation faults .RC ( re and .CR at ). .TP .I interval Display successive lines which are summaries over the last .I interval seconds. If .I interval is zero, the output is displayed once only. If the .CR \-d option is specified, the column headers are repeated. If .CR \-d is omitted, the column headers are not repeated. .IP The command .CR "vmstat 5" prints what the system is doing every five seconds. This is a good choice of printing interval since this is how often some of the statistics are sampled in the system; others vary every second. .TP .I count Repeat the summary statistics .I count times. If .I count is omitted or zero, the output is repeated until an interrupt or quit signal is received. From the terminal, these are commonly .CR ^C and .CR ^\e , respectively (see .IR stty (1)). .TP .CR \-f Report on the number of forks and the number of pages of virtual memory involved since boot-up. .TP .CR \-s Print the total number of several kinds of paging-related events from the kernel .CR sum structure that have occurred since boot-up or since .CR vmstat was last executed with the .CR \-z option. .TP .CR \-z Clear all accumulators in the kernel .CR sum structure. This requires write file access permission on .CR /dev/kmem . This is normally restricted to users with appropriate privileges. .RE .PP If none of these options is given, .CR vmstat displays a one-line summary of the virtual memory activity since boot-up or since the .CR \-z option was last executed. .SS Column Descriptions The column headings and the meaning of each column are: .RS .TP 12 .CR procs Information about numbers of processes in various states. .RS .RS .TP 7 .CR r In run queue .TP .CR b Blocked for resources (I/O, paging, etc.) .TP .CR w Runnable or short sleeper (< 20 secs) but swapped .RE .RE .TP .CR memory Information about the usage of virtual and real memory. Virtual pages are considered active if they belong to processes that are running or have run in the last 20 seconds. .RS .RS .TP 8 .CR avm Active virtual pages .TP .CR free Size of the free list .RE .RE .TP .CR page Information about page faults and paging activity. These are averaged each five seconds, and given in units per second. .RS .RS .TP 8 .CR re Page reclaims (without .CR \-S ) .TP .CR at Address translation faults (without .CR \-S ) .TP .CR si Processes swapped in (with .CR \-S ) .TP .CR so Processes swapped out (with .CR \-S ) .TP .CR pi Pages paged in .TP .CR po Pages paged out .TP .CR fr Pages freed per second .TP .CR de Anticipated short term memory shortfall .TP .CR sr Pages scanned by clock algorithm, per second .RE .RE .TP .CR faults Trap/interrupt rate averages per second over last 5 seconds. .RS .RS .TP 8 .CR in Device interrupts per second (nonclock) .TP .CR sy System calls per second .TP .CR cs CPU context switch rate (switches/sec) .RE .RE .TP .CR cpu Breakdown of percentage usage of CPU time .RS .RS .TP 8 .CR us User time for normal and low priority processes .TP .CR sy System time .TP .CR id CPU idle .RE .RE .RE .SH EXAMPLES The following examples show the output for various command options. For formatting purposes, some leading blanks have been deleted. .\" EDITOR'S NOTE: The default (non -n) output has been physically .\" into two lines at the column after "sr". .TP .B 1. Display the default output. .PP .CR "vmstat" .nf .PP .C " procs memory page " .C " faults cpu" .C "r b w avm free re at pi po fr de sr" .C " in sy cs us sy id" .C "0 0 0 1158 511 0 0 0 0 0 0 0" .C " 111 18 7 0 0 100" .fi .TP .B 2. Add the disk tranfer information to the default output. .PP .CR "vmstat -d" .nf .PP .C " procs memory page " .C " faults cpu" .C "r b w avm free re at pi po fr de sr" .C " in sy cs us sy id" .C "0 0 0 1158 511 0 0 0 0 0 0 0" .C " 111 18 7 0 0 100" .C "\&" .C "Disk Transfers" .C " device xfer/sec" .C " c0t6d0 0" .C " c0t1d0 0" .C " c0t3d0 0" .C " c0t5d0 0" .fi .TP .B 3. Display the default output in 80-column format. .PP .CR "vmstat -n" .nf .PP .C "VM" .C " memory page faults" .C " avm free re at pi po fr de sr in sy cs" .C " 1158 430 0 0 0 0 0 0 0 111 18 7" .C "CPU" .C " cpu procs" .C " us sy id r b w" .C " 0 0 100 0 0 0" .fi .TP .B 4. Replace the page reclaims and address translation faults with process swapping in the default output. .PP .CR "vmstat -S" .nf .PP .C " procs memory page " .C " faults cpu" .C "r b w avm free si so pi po fr de sr" .C " in sy cs us sy id" .C "0 0 0 1158 430 0 0 0 0 0 0 0" .C " 111 18 7 0 0 100" .fi .TP .B 5. Display the default output twice at five-second intervals. Note that the headers are .I not repeated. .PP .CR "vmstat 5 2" .nf .PP .C " procs memory page " .C " faults cpu" .C "r b w avm free re at pi po fr de sr" .C " in sy cs us sy id" .C "0 0 0 1158 456 0 0 0 0 0 0 0" .C " 111 18 7 0 0 100" .C "0 0 0 1221 436 5 0 5 0 0 0 0" .C " 108 65 18 0 1 99" .fi .TP .B 6. Display the default output twice in 80-column format at five-second intervals. Note that the headers are .I not repeated. .PP .CR "vmstat -n 5 2" .nf .PP .C "VM" .C " memory page faults" .C " avm free re at pi po fr de sr in sy cs" .C "1221 436 0 0 0 0 0 0 0 111 18 7" .C "CPU" .C " cpu procs" .C " us sy id r b w" .C " 0 0 100 0 0 0" .C "1221 435 2 0 2 0 0 0 0 109 35 17" .C " 0 1 99 0 0 0" .fi .TP .B 7. Display the default output and disk transfers twice in 80-column format at five-second intervals. Note that the headers .I are repeated. .PP .CR "vmstat -dn 5 2" .nf .PP .C "VM" .C " memory page faults" .C " avm free re at pi po fr de sr in sy cs" .C "1221 435 0 0 0 0 0 0 0 111 18 7" .C "CPU" .C " cpu procs" .C " us sy id r b w" .C " 0 0 100 0 0 0" .C "\&" .C "Disk Transfers" .C " device xfer/sec" .C " c0t6d0 0" .C " c0t1d0 0" .C " c0t3d0 0" .C " c0t5d0 0" .C "\&" .C "VM" .C " memory page faults" .C " avm free re at pi po fr de sr in sy cs" .C "1219 425 0 0 0 0 0 0 0 111 54 15" .C "CPU" .C " cpu procs" .C " us sy id r b w" .C " 1 8 92 0 0 0" .C "\&" .C "Disk Transfers" .C " device xfer/sec" .C " c0t6d0 0" .C " c0t1d0 0" .C " c0t3d0 0" .C " c0t5d0 0" .fi .TP .B 8. Display the number of forks and pages of virtual memory since boot-up. .PP .CR "vmstat -f" .nf .PP .C "24558 forks, 1471595 pages, average= 59.92" .fi .TP .B 9. Display the counts of paging-related events. .PP .CR "vmstat -s" .nf .PP .C "0 swap ins" .C "0 swap outs" .C "0 pages swapped in" .C "0 pages swapped out" .C "1344563 total address trans. faults taken" .C "542093 page ins" .C "2185 page outs" .C "602573 pages paged in" .C "4346 pages paged out" .C "482343 reclaims from free list" .C "504621 total page reclaims" .C "124 intransit blocking page faults" .C "1460755 zero fill pages created" .C "404137 zero fill page faults" .C "366022 executable fill pages created" .C "71578 executable fill page faults" .C "0 swap text pages found in free list" .C "162043 inode text pages found in free list" .C "196 revolutions of the clock hand" .C "45732 pages scanned for page out" .C "4859 pages freed by the clock daemon" .C "36680636 cpu context switches" .C "1497746186 device interrupts" .C "1835626 traps" .C "87434493 system calls" .fi .SH WARNINGS Users of .CR vmstat must not rely on the exact field widths and spacing of its output, as these will vary depending on the system, the release of HP-UX, and the data to be displayed. .SH AUTHOR .CR vmstat was developed by the University of California, Berkeley and HP. .SH FILES .CR /dev/kmem .SH SEE ALSO iostat(1). .\" .\" index@\f4vmstat\f1 \- report virtual memory statistics@@@\f3vmstat(1)\f1 .\" index@report virtual memory statistics@@@\f3vmstat(1)\f1 .\" index@virtual memory statistics, report@@@\f3vmstat(1)\f1 .\" index@memory statistics, report virtual@@@\f3vmstat(1)\f1 .\" index@statistics, report virtual memory@@@\f3vmstat(1)\f1 .\" .\" toc@\f3vmstat(1)\f1:\0\0\f4vmstat\f1@@@report virtual memory statistics .\" $Header: vt.1,v 72.2 94/11/30 15:39:23 ssa Exp $ .TA v .TH vt 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vt \- log into another system over lan .SH SYNOPSIS .C /usr/bin/vt .I nodename .RI [ \|lan_device\| ] .br .C /usr/bin/vt \-p .RI [ \|lan_device\| ] .SH DESCRIPTION .C vt enables a user to log into another HP 9000 system .RI ( nodename ) over an HP local area network. The .C -p option causes .C vt to send a poll request over the local area network to find out what systems currently have .C vtdaemon running (see .IR vtdaemon (1M)). An asterisk .RC ( * ) following a .I nodename in the response indicates that the system is a .CR vt gateway. Plus signs .RC ( + ) following the .I nodename indicate how many .CR vt gateways must be traversed to reach that system. .PP The optional argument .I lan_device specifies a character special device name to use instead of the default device name to send and receive data to and from the local area network. The major number for this device must correspond to a .SM "CIO IEEE 802.3" local area network device. .PP Once a connection has been established, .C vt enters input mode. In this mode, text typed is sent to the remote host. To issue .CR vt commands when in input mode, precede them with the .C vt escape character (see Commands below). When in command mode, normal terminal editing conventions are available. .PP The connection should terminate automatically upon termination of the login shell on the remote machine. If the connection is not terminated upon exit, it is likely that the .C ptydaemon on the remote system has either been terminated or restarted. To terminate a vt connection, enter command mode and use the .C quit command to terminate the connection. .SS Commands .C vt recognizes the following commands. Commands can be abbreviated by typing enough of the command to uniquely identify it. .TP 30 .CI cd \0remote-directory Change the working directory on the remote machine to .I remote-directory. This command is applicable for file transfer only. .TP .CR escape \0[\f2escape-char\fP] Set the .C vt escape character. If a character is not specified .C vt prompts for one. To print or display the current .C vt escape character simply press Return in response to this prompt. .TP .CR help " or " ? Print a .C vt command summary. .PD .TP .CR lcd \0[\f2directory\fP] Change the local working directory. If no .I directory is specified, use the user's home directory. This command is applicable for file transfer and shell escapes only. .TP .CI get " remote-file local-file" .PD 0 .TP .CI receive " remote-file local-file" Copy .I remote-file to local machine and store as .IR local-file . .C vt prompts for the file names if they are not specified. The file transfer can be aborted by typing the interrupt character or pressing the break key. .PD .TP .CI put " local-file remote-file" .PD 0 .TP .CI send " local-file remote-file" Copy .I local-file to the remote machine and store as .IR remote-file . .C vt prompts for the file names if they are not specified. The file transfer can be aborted by typing the interrupt character or pressing the break key. .PD .TP .C quit Terminate the connection and exit .IR vt . .TP .CR user \f2user-name\fP[ : [\f2password\fP]] Identify yourself to the remote .C vt server. .C vt prompts for a password (after disabling local echo) if a colon .RC ( : ) is appended to .IR user-name . This command must be executed before any file transfer command can be used. .TP .CR ! \0[\f2shellcommand\fP] Shell escape. The given command is passed to a sub-shell for execution. If no command is given, a shell is started and connected to the user's terminal. .SS "Access Control Lists (ACLs)" When sending or receiving files using .CR vt , optional .SM ACL entries are removed. New files have a summary of the access modes (as returned in .C st_mode by .C stat() of the file being transferred (see .IR stat (2)). .SH DIAGNOSTICS The diagnostics produced by .C vt are intended to be self-explanatory. .SH WARNINGS .C vt uses the Hewlett-Packard .SM LLA (Link Level Access) direct interface to the .SM HP network drivers. .C vt uses the multicast address .C 0x01AABBCCBBAA. It should not be used or deleted by other applications accessing the network. .C vt uses the following .SM IEEE 802.3 .I sap (service access point) values: .CR 0x90 , .CR 0x94 , .CR 0x98 , .CR 0x9C , .CR 0xA0 , .CR 0xA4 , .CR 0xA8 , .CR 0xAC , .CR 0xB0 , .CR 0xB4 , .CR 0xB8 , .CR 0xBC , .CR 0xC0 , .CR 0xC4 , .CR 0xC8 , .CR 0xCC , .CR 0xD0 , and .CR 0xD4 . They should not be used by other applications accessing the network. .PP When using .C vt on a system with multiple .SM LAN cards installed, the optional command-line argument .I lan_device may be required if the remote system is not accessible through the default .SM LAN device. The appropriate .I lan_device is the one connected (either directly or by way of other gateways) to the remote system. .SS Desktop HP-UX If your system has been installed with the Desktop HP-UX product, neither .C ptydaemon nor .C vtdaemon will be started by default. To start these daemons, change .I PTYDAEMON_START and .I VTDAEMON_START from a .CR 0 to a .CR 1 in the .C /etc/rc.config.d/ptydaemon and .C /etc/rc.config.d/vt files, respectively. The system must be either rebooted for these changes to take effect, or you can start both daemons manually by typing the following commands: .nf .RS 4 .C /usr/sbin/ptydaemon .CI /usr/sbin/vtdaemon " /dev/lan0" .RE .fi .PP where .I /dev/lan0 is the character special device file corresponding to the IEEE 802.3 local area network device. .PP .SH FILES .TP 15 .C /dev/lan0 Default lan device name. .TP .C /etc/rc.config.d/ptydaemon .TP .C /etc/rc.config.d/vt .SH SEE ALSO vtdaemon(1M), stat(2), lan(4), acl(5). .\" .\" index@\f4vt\f1 \- log in on another system over \s-1LAN\s+1@@@\f3vt(1)\f1 .\" index@log in on another system over \s-1LAN\s+1@@@\f3vt(1)\f1 .\" index@another system over \s-1LAN\s+1, log in on@@@\f3vt(1)\f1 .\" index@system over \s-1LAN\s+1, log in on another@@@\f3vt(1)\f1 .\" index@remote system over \s-1LAN\s+1, log in on a@@@\f3vt(1)\f1 .\" index@\s-1LAN\s+1, log in on a remote system over@@@\f3vt(1)\f1 .\" .\" toc@\f3vt(1)\f1:\0\0\f4vt\f1@@@log in on another system over lan .\" $Header: uptime.1,v 78.1 95/12/20 11:21:04 ssa Exp $ .TA u .TH uptime 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uptime, w \- show how long system has been up, and/or who is logged in and what they are doing .SH SYNOPSIS .CR uptime .RC [ -hlsuw ] .RC [ user ] .PP .CR w .RC [ -hlsuw ] .RC [ user ] .SH DESCRIPTION .CR uptime prints the current time, the length of time the system has been up, the number of users logged on to the system, and the average number of jobs in the run queue over the last 1, 5, and 15 minutes. .PP .CR w is linked to .CR uptime and prints the same output as .CR "uptime -w" , displaying a summary of the current activity on the system. .SS Options .CR uptime and .CR w recognize the following options: .RS .TP .CR -h Suppress the first line and the heading line. This option should not be used with the .CR -u option. This option assumes the use of the .CR -w option to .CR uptime . .RE .RS .TP .CR -l Use long output. This option assumes the use of the .CR -w option to .CR uptime . .RE .RS .TP .CR -s Use the short form of output for displaying terminal information. The terminal name is abbreviated; the login time and CPU times are suppressed. .RE .RS .TP .CR -u Print only the first line describing the overall state of the system. This is the default for the .CR uptime command. .RE .RS .TP .CR -w Print a summary of the current activity on the system for each user. This is the default for the .CR w command. .RE .SH EXAMPLES The command: .IP .CR uptime .PP produces text resembling the following: .IP .C "2:30pm up 14days, 2:39, 33 users, load average: 1.71, 1.88, 1.80" .PP depending upon the current status of the system. .SH AUTHOR .CR uptime was developed by the University of California, Berkeley. .\" .\" toc@\f3uptime(1)\f1:\0\0\f4uptime\f1, \f4w\f1@@@show how long system has been up .\" .\" index@\f4uptime\f1 \- show how long system has been up@@@\f3uptime(1)\f1 .\" index@\f4w\f1 \- show how long system has been up@@@\f3uptime(1)\f1 .\" index@show how long system has been up@@@\f3uptime(1)\f1 .\" index@system up time, show@@@\f3uptime(1)\f1 .\" .\" links@uptime.1 w.1 .\" $Header: wait.1,v 76.1 95/08/07 10:18:22 ssa Exp $ .TA w .TH wait 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wait \- await process completion .SH SYNOPSIS .C wait .RI [ \|pid\| ] .SH DESCRIPTION If no argument is specified, .C wait waits until all processes (started with .CR & ) of the current shell have completed, and reports on abnormal terminations. If a numeric argument .I pid is given and is the process .SM ID of a background process, .C wait waits until that process has completed. Otherwise, if .I pid is not a background process, .C wait exits without waiting for any processes to complete. .PP Because the .C wait() system call must be executed in the parent process, the shell itself executes .C wait without creating a new process (see .IR wait (2)). .SS Command-Line Arguments .C wait supports the following command line arguments: .RS .TP 12 .C pid The unsigned decimal integer process .SM ID of a command, whose termination .C wait is to wait for. .SH WARNINGS Some processes in a 2-or-more-stage pipeline may not be children of the shell, and thus cannot be waited for. .SH SEE ALSO csh(1), ksh(1), sh-posix(1), sh(1), wait(2). .SH SEE ALSO sh(1), wait(2). .SH STANDARDS CONFORMANCE .CR wait ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" toc@\f3wait(1)\f1:\0\0\f4wait\f1@@@await completion of process .\" .\" index@\f4wait\f1 \- wait for background processes to complete@@@\f3wait(1)\f1 .\" index@suspend foreground until background processes are finished@@@\f3wait(1)\f1 .\" index@background processes to complete, wait for@@@\f3wait(1)\f1 .\" index@processes to complete, wait for background@@@\f3wait(1)\f1 .\" index@complete, wait for background processes to@@@\f3wait(1)\f1 .\" index@terminate, wait for background processes to@@@\f3wait(1)\f1 .\" index@finish, wait for background processes to@@@\f3wait(1)\f1 .\" .\" fileset_database@wait.1 USER-CMDS-MAN .\" $Header: wc.1,v 76.2 95/08/23 17:49:17 ssa Exp $ .TA w .TH wc 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wc \- word, line, and byte or character count .SH SYNOPSIS .C wc .RC [ -c | -m ] .RC [ -lw ]\| .RI \|[ names ] .SH DESCRIPTION The .CR wc command counts lines, words, and bytes or characters in the named files, or in the standard input if no .I names are specified. It also keeps a total count for all named files. .PP A word is a maximal string of characters delimited by spaces, tabs, or new-lines. .PP .C wc recognizes the following command-line options: .RS .TP 10 .C -c Write to the standard output the number of bytes in each input file. .TP .C -m Write to the standard output the number of characters in each input file. .TP .C -w Write to the standard output the number of words in each input file. .TP .C -l Write to the standard output the number of newline characters in each input file. .RE .PP The .CR c and .CR m options are mutually exclusive. Otherwise, the .CR l , .CR w , and .C c or .C m options can be used in any combination to specify that a subset of lines, words, and bytes or characters are to be reported. .PP When any option is specified, .C wc will report only the information requested by the specified options. If no option is specified, The default output is .CR -lwc . .PP When .I names are specified on the command line, they are printed along with the counts. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the range of graphics and space characters, and the interpretation of text as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .CR LC_CTYPE or .CR LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .CR wc behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS The .CR wc command counts the number of newlines to determine the line count. If a text file has a final line that is not terminated with a newline character, the count will be off by one. .PP .SS Standard Output (XPG4 only) By default, the standard output contains an entry for each input file of the form: .PP \f1"\f3%d %d %d %s\\n\f1", .RI < newlines >, .RI < words >, .RI < bytes >, .RI < file > .PP If the .C -m option is specified, the number of characters replaces the .RI < bytes > field in this format. .PP If any options are specified and the .C -l option is not specified, the number of .I newlines are not written. .PP If any options are specified and the .C -w option is not specified, the number of .I words are not written. .PP If any options are specified and neither .C -c nor .C -m is specified, the number of .I bytes or .I characters are not written. .PP If no input .I file operands are specified, no flie name is written and no blank characters preceding the pathname is written. .PP If more than one input .I file operand is specified, an additional line is written, of the same format as the other lines, except that the word .C total (in the POSIX Locale) is written instead of a pathname and the total of each column is written as appropriate. Such an additional line, if any, is written at the end of the input. .PP .SS Exit Status The .C wc utility shall exit with one of the following values .RS .TP 6 .C 0 Successful completion. .TP .C >0 An error occured. .SH EXAMPLES Print the number of words and characters in .CR file1 : .IP .C wc -wm file1 .PP The following is printed when the above command is executed: .IP .I n1 n2 .C \0file1 .PP where .I n1 is the number of words and .I n2 is the number of characters in .CR file1 . .SH STANDARDS CONFORMANCE .CR wc ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4wc\f1 \- count words, lines, and bytes or characters in a file@@@\f3wc(1)\f1 .\" index@\f1files: count words, lines, and bytes or characters in a file@@@\f3wc(1)\f1 .\" index@\f1count words, lines, and bytes or characters in a file@@@\f3wc(1)\f1 .\" index@\f1size of file in words, lines, and bytes or characters@@@\f3wc(1)\f1 .\" index@\f1file size in words, lines, and bytes or characters@@@\f3wc(1)\f1 .\" index@\f1words, lines, and bytes or characters in a file, count@@@\f3wc(1)\f1 .\" index@\f1lines, words, and bytes or characters in a file, count@@@\f3wc(1)\f1 .\" index@\f1bytes or characters, lines, and words in a file, count@@@\f3wc(1)\f1 .\" index@\f1characters or bytes, lines, and words in a file, count@@@\f3wc(1)\f1 .\" .\" toc@\f3wc(1)\f1:\0\0\f4wc\f1@@@word, line, and bytes or character count .\" .\" $Header: what.1,v 76.1 95/07/10 17:13:39 ssa Exp $ .TA w .TH what 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME what \- get \s-1SCCS\s+1 identification information .SH SYNOPSIS .C what .RC [ -s ] .IR file \0... .SH DESCRIPTION The .C what command searches the given files for all occurrences of the pattern that .IR get (1) substitutes for .C %Z% (currently \f3@\&(#)\f1 at this printing) and prints out what follows until the first \f3"\fP, .CR > , new-line, .CR \e , or null character. For example, if the C program in file .C f.c contains .IP .ift .ft 4 .ifn .ft 3 .ps +1 char ident[] = "@\&(#)identification information\|"; .ft .ps .PP and .C f.c is compiled to yield .C f.o and .CR a.out , the command .IP .C what f.c f.o a.out .PP prints .RS .TP 15 .C f.c: identification information .TP .C f.o: identification information .TP .C a.out: identification information .RE .PP .C what is intended to be used in conjunction with the .SM SCCS .C get command (see .IR get (1)) which automatically inserts identifying information, but it can also be used where the information is inserted manually. .SS Options .C what recognizes the following option: .RS .TP 10 .C -s Quit after finding the first occurrence of pattern in each file. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the interpretation of the pattern substituted for .C %Z% as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C what behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH DIAGNOSTICS Exit status is 0 if any matches are found, otherwise 1. Use .C help for explanations (see .IR help (1)). .SH WARNINGS The pattern \f3@\&(#)\fP may occasionally appear unintentionally in random files, but this causes no harm in nearly all cases. .SH SEE ALSO get(1), help(1). .SH STANDARDS CONFORMANCE .CR what ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4what\f1 \- get SCCS identification information from files@@@\f3what(1)\f1 .\" index@\f1SCCS: get SCCS identification information from files@@@\f3what(1)\f1 .\" index@\f1files: get SCCS identification information from files@@@\f3what(1)\f1 .\" index@\f1identification information, SCCS, get from files@@@\f3what(1)\f1 .\" index@\f1information, SCCS identification, get from files@@@\f3what(1)\f1 .\" .\" toc@\f3what(1)\f1:\0\0\f4what\f1@@@get \s-1SCCS\s+1 identification information .\" .\" $Header: whereis.1,v 72.4 93/11/11 16:58:57 ssa Exp $ .TA w .TH whereis 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME whereis \- locate source, binary, and/or manual for program .SH SYNOPSIS .C whereis .RC [ -bsm ] .RC [ -u ] .RC [ -BMS .IR dir \ ... .CR -f ] .I name ... .SH DESCRIPTION .C whereis locates source, binary, and manuals sections for specified files. The supplied names are first stripped of leading path name components and any (single) trailing extension of the form .CI . ext (such as .CR .c ). Prefixes of .C s. resulting from use of .SM SCCS are also dealt with. .C whereis then attempts to locate the desired program in a list of standard places. .SS Options .C whereis recognizes the following command-line options: .RS .TP 15 .C -b Limit search to binary files. Can be used in conjunction with .C -s or .CR -m . .TP .C -s Limit search to source-code files. Can be used in conjunction with .C -b or .CR -m . .TP .C -m Limit search to manual entry files. Can be used in conjunction with .C -b or .CR -s . .TP .C -u Search for unusual entries. A file is said to be unusual if it does not have one entry of each requested type. Thus, .C whereis -m -u * searches for those files in the current directory that have no corresponding manual entry. .TP .CR -B " \f2dir\fP [\f2dir\fP ...\|]" Limit search to binaries located in one or more specified directories. Can be used in conjunction with .C -S or .CR -M . .TP .CR -S " \f2dir\fP [\f2dir\fP ...\|]" Limit search to source files located in one or more specified directories. Can be used in conjunction with .C -B or .CR -M . .TP .CR -M " \f2dir\fP [\f2dir\fP ...\|]" Limit search to manual entry files located in one or more specified directories. Can be used in conjunction with .C -B or .CR -S . .TP .C -f Terminates the last directory list .RC ( -B , .CR -S , or .C -M options) and identifies the start of file names. .RE .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES Find all the files in .C /usr/bin that are not documented in .C /usr/share/man/man1 with source files in .CR /usr/src/cmd : .IP .C "cd /usr/bin" .br .C "whereis -u -M /usr/share/man/man1 -S /usr/src/cmd -f *" .SH WARNINGS .C whereis uses the .C chdir() system call (see .IR chdir (2)) to run faster. Therefore, path names given with the .CR -B , .CR -M , and .C -S options must be absolute path names. .SH AUTHOR .C whereis was developed by the University of California, Berkeley. .SH FILES .nf .C /usr/src/* .C /usr/sbin, /sbin, /usr/bin, /usr/lbin, /usr/ccs/bin .C /usr/share/man/* .C /usr/local/{man/*, bin, games, include, lib} .C /usr/contrib/{man/*, bin, games, include, lib} .C /usr/share/man/\s-1$LANG\s0/* .C /usr/local/man/\s-1$LANG\s0/* .C /usr/contrib/man/\s-1$LANG\s0/* .fi .\" .\" toc@\f3whereis(1)\f1:\0\0\f4whereis\f1@@@locate source, binary, and/or manual for program .\" .\" index@\f4whereis\f1 \- locate source, binary, and/or manual files for program@@@\f3whereis(1)\f1 .\" index@locate source, binary, and/or manual files for program@@@\f3whereis(1)\f1 .\" index@find location of source, binary, and/or manual files for program@@@\f3whereis(1)\f1 .\" index@manual entry files for given name, find location of@@@\f3whereis(1)\f1 .\" index@source program files for given name, find location of@@@\f3whereis(1)\f1 .\" index@binary program files for given name, find location of@@@\f3whereis(1)\f1 .\" .\" fileset_database@whereis.1 USER-CMDS-MAN .\" $Header: which.1,v 72.4 93/11/11 17:01:03 ssa Exp $ .TA w .TH which 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME which \- locate a program file including aliases and paths .SH SYNOPSIS .C which .RI [ \|name \0...\|] .SH DESCRIPTION For each .I name given, .C which searches for the file that would be executed if .I name were given as a command, and displays the absolute path of that file. Each argument is expanded if it is aliased, and searched for along the user's path. Both aliases and path are determined by sourcing (executing) the user's .C .cshrc file. .SH DIAGNOSTICS A diagnostic is given for names that are aliased to more than a single word, or if an executable file with the argument name was not found in the path. .SH EXAMPLES The command: .IP .C which sh .PP specifies where the executable program of the .IR sh (1) command is found. For example, the response might be: .IP .C /usr/bin/sh .PP if the .IR sh (1) being used is located in .CR /usr/bin . .SH WARNINGS .C which reports .C .cshrc aliases even when not invoked from .IR csh . .PP .C which cannot find .CR csh built-in commands (e.g. jobs). .PP .CR which 's information may be incorrect because it is unaware of any path or alias changes that have occurred in the current shell session. .SH AUTHOR .C which was developed by the University of California, Berkeley. .SH FILES .TP 15 .C ~/.cshrc source of aliases and path values .\" .\" toc@\f3which(1)\f1:\0\0\f4which\f1@@@locate a program file including aliases and paths .\" .\" index@\f4which\f1 \- locate a program file including aliases and paths@@@\f3which(1)\f1 .\" index@locate a program file including aliases and paths@@@\f3which(1)\f1 .\" index@aliases and paths, locate a program file including@@@\f3which(1)\f1 .\" index@paths and aliases, locate a program file including@@@\f3which(1)\f1 .\" index@program file, locate, including aliases and paths@@@\f3which(1)\f1 .\" index find program files that execute under given command name \f3which(1)\f1 .\" index@program files that execute under given command name, find@@@\f3which(1)\f1 .\" index@command name, find program files that execute under given@@@\f3which(1)\f1 .\" .\" fileset_database@which.1 USER-CMDS-MAN .\" $Header: who.1,v 76.1 95/08/23 17:50:07 ssa Exp $ .TA w .TH who 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME who \- who is on the system .SH SYNOPSIS .C who .RC [ -muTlHqpdbrtasAR ] .RI [ \|file\| ] .PP .C who am i .PP .C who am I .SH DESCRIPTION The .CR who command can list the user's name, terminal line, login time, elapsed time since input activity occurred on the line, the user's host name, and the process-\c .SM ID of the command interpreter (shell) for each current system user. It examines the .CR /etc/utmp file to obtain its information. If .I file is given, that file is examined. Usually, .I file is .CR /var/adm/wtmp , which contains a history of all of the logins since the file was last created. .PP The .CR who command with the .CR "am i" or .CR "am I" option identifies the invoking user. .PP Except for the default .CR -s option, the general format for output entries is: .IP name \|[\|state\|] \|line \|time \|activity \|pid \|[\|comment\|] \|[\|exit\|] .PP With options, .CR who can list logins, logoffs, reboots, and changes to the system clock, as well as other processes spawned by the .CR init process. .SS Options .RS .TP 15 .C -m Output only information about the current terminal. This option is equivalent to the .CR "am i" and .CR "am I" options described above. .TP .C -u Lists only those users who are currently logged in. .I name is the user's login name. .I line is the name of the line as found in the directory .CR /dev . The .I time field indicates when the user logged in. .IP .I activity is the number of hours and minutes since input activity last occurred on that particular line. A dot .RC ( \|.\| ) indicates that the terminal has seen activity in the last minute and is therefore ``current''. If more than twenty-four hours have elapsed or the line has not been used since boot time, the entry is marked .CR old . This field is useful when trying to determine whether a person is working at the terminal or not. The .I pid is the process-\c .SM ID of the user's login process. The .I comment is the comment field associated with this line as found in .CR /etc/inittab (see .IR inittab (4)). This can contain information about where the terminal is located, the telephone number of the dataset, type of terminal if hard-wired, etc. If no such information is found, then .CR who prints, as the .IR comment , the user's host name as it was stored in the .CR /etc/utmp or named .IR file . Note that the user's host name is printed instead of comments from the .CR /etc/inittab file if the .CR -u option is used in conjunction with the .CR -R option. .TP .C -T Same as the .CR -u option, except that the .I state of the terminal line is printed. .I state describes whether someone else can write to that terminal. A .CR + appears if the terminal is writable by anyone; a .CR - appears if it is not. .CR root can write to all lines having a .CR + or a .CR - in the .I state field. If a bad line is encountered, a .CR ? is printed. .IP (XPG4 only.) Only the following fields are displayed: .I name state line time .TP .C -l Lists only those lines on which the system is waiting for someone to login. The .I name field is .CR LOGIN in such cases. Other fields are the same as for user entries except that the .I state field does not exist. .TP .C -H Prints column headings above the regular output. .TP .C -q A quick .CR who , displaying only the names and the number of users currently logged in. When this option is used, all other options are ignored. .TP .C -p Lists any other process which is currently active and has been previously spawned by .IR init . The .I name field is the name of the program executed by .CR init as found in .CR /etc/inittab . The .IR state , .IR line , and .I activity fields have no meaning. The .I comment field shows the .I id field of the line from .CR /etc/inittab that spawned this process. See .IR inittab (4). .TP .C -d This option displays all processes that have expired and have not been respawned by .CR init . The .I exit field appears for dead processes and contains the termination and exit values of the dead process (as returned by .CR wait() \(em see .IR wait (2)). This can be useful in determining why a process terminated. .TP .C -b Indicates the time and date of the last reboot. .TP .C -r Indicates the current .I run-level of the .CR init process. The last three fields contain the current state of .CR init , the number of times that state has been previously entered, and the previous state. These fields are updated each time .CR init changes to a different run state. .TP .C -t Indicates the last change to the system clock (via the .CR date command) by .CR root . See .IR su (1). .TP .C -a Processes .CR /etc/utmp or the named .I file with all options turned on. .TP .C -s Default. Lists only the .IR name , .IR line , and .I time fields. .TP .C -A When the .CR /var/adm/wtmp file is specified, this option indicates when the accounting system was turned on or off using the .CR startup or .CR shutacct commands (see .IR acctsh (1M)). The .I name field is .CR . \|. The .I line field is .CR "acctg on" , .CR "acctg off" , or a reason that was given as an option to the .CR shutacct command. The .I time is the time that the on/off activity occurred. .TP .C -R Displays the user's host name. If the user is logged in on a tty, .CR who displays the string returned from .CR gethostname() (see .IR gethostname (2)). If the user is not logged in on a tty and the host name stored in the .CR /etc/utmp or named file has not been truncated when stored (meaning that the entire host name was stored with no loss of information), it is displayed as it was stored. Otherwise, the .CR gethostbyaddr() function is called with the internet address of the host (see .IR gethostent (3N)). The host name returned by .CR gethostbyaddr() is displayed unless it returns an error, in which case the truncated host name is displayed. .RE .PP (XPG4 only. The .CR -s option can not be used with .CR -d , .CR -a or .CR -T options. If .CR -u option is used with .CR -T , the idle time is added to the end of the .CR -T format.) .PP .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not set or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .CR LC_CTYPE determines the locale for interpretation of sequences of bytes of text data as characters (e.g., single- verses multibyte characters in arguments and input files). .PP .C LC_TIME determines the format and contents of date and time strings. .PP .CR LC_MESSAGES determines the language in which messages are displayed. .PP If any internationalization variable contains an invalid setting, .CR who behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES Check who is logged in on the system: .IP .C who .PP Check whether or not you can write to the terminal that another user is using: .IP .C who -T .PP and look for a plus .RC ( + ) after the user .SM ID. .SH AUTHOR .C who was developed by AT&T and HP. .SH FILES .C /etc/inittab .br .C /etc/utmp .br .C /var/adm/wtmp .SH SEE ALSO date(1), login(1), init(1), mesg(1), su(1), gethostname(2), wait(2), gethostent(3N), inittab(4), utmp(4). .SH STANDARDS CONFORMANCE .CR who ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4who\f1 \- who is using the system@@@\f3who(1)\f1 .\" index@list current system users@@@\f3who(1)\f1 .\" index@current system users, list@@@\f3who(1)\f1 .\" index@system users, list current@@@\f3who(1)\f1 .\" index@print list of current system users@@@\f3who(1)\f1 .\" index@user: print list of current system users@@@\f3who(1)\f1 .\" .\" toc@\f3who(1)\f1:\0\0\f4who\f1@@@who is currently logged in on the system .\" $Header: whoami.1,v 72.3 93/01/14 11:43:31 ssa Exp $ .TA w .TH whoami 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME whoami \- print effective current user id .SH SYNOPSIS .C whoami .SH DESCRIPTION .C whoami prints your .I current user name, even if you have used .C su to change it since your initial login (see .IR su (1)). The command .C who am i reports your initial login name because it uses .CR /etc/utmp . .SH FILES .TP 15 .C /etc/passwd name data base .SH AUTHOR .C whoami was developed by the University of California, Berkeley. .SH SEE ALSO who (1). .\" .\" toc@\f3whoami(1)\f1:\0\0\f4whoami\f1@@@print effective current user id .\" .\" index@\f4whoami\f1 \- print effective current user id@@@\f3whoami(1)\f1 .\" index@print or display effective current user id@@@\f3whoami(1)\f1 .\" index@effective current user id, print or display@@@\f3whoami(1)\f1 .\" index@current user id, print or display@@@\f3whoami(1)\f1 .\" index@user id, effective current, print or display@@@\f3whoami(1)\f1 .\" index@\s-1ID\s+1, effective current user, print or display@@@\f3whoami(1)\f1 .\" .\" fileset_database@whoami.1 USER-CMDS-MAN .\" $Header: whois.1,v 74.2 95/03/23 17:15:34 ssa Exp $ .TA w .TH whois 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME .TP 5 whois \- Internet user name directory service .SH SYNOPSIS .C whois .RC [ -h .IR hostname\| ] .RC .IR name\| .PP .SH DESCRIPTION .C whois looks up records in the Network Information Center database. .PP The operands specified to whois are concatenated together (separated by white-space) and presented to the whois server. .PP The default action, unless directed otherwise with a special name, is to do a very broad search, looking for matches to name in all types of records and most fields (name, nicknames, hostname, net address, etc.) in the database. For more information as to what name operands have special meaning, and how to guide the search, use the special name ``help''. .SS Options .C whois supports the following options: .RS .TP 5 .C -h use the specified host instead of the default (nic.ddn.mil). .C .SH EXAMPLES .PP Look up user John Doe .IP .CI whois " Doe,John " .SH DEPENDENCIES .PP The machine making the .CI whois enquiry must be able to route the request over the network to the specified host, or to the default NIC (nic.ddn.mil). .SH AUTHOR .PP .C whois was developed by the University of California, Berkeley. .PD .SH SEE ALSO RFC 854: Nicname/Whois .\" .\" toc@\f3whois(1)\f1:\0\0\f4whois\f1@@@Internet user name directory service .\" .\" index@\f4whois\f1 \- Internet user name directory service@@@\f3whois(1)\f1 .\" index@\f1Internet user name directory service@@@\f3whois(1)\f1 .\" index@\f1user name directory service, Internet@@@\f3whois(1)\f1 .\" index@\f1directory service, Internet user name@@@\f3whois(1)\f1 .\" .\" $Header: write.1,v 76.2 95/08/23 17:50:57 ssa Exp $ .TA w .TH write 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME write \- interactively write (talk) to another user .SH SYNOPSIS .CI write \0user\0\f1[\fPterminal\f1]\fP .SH DESCRIPTION The .CR write command copies lines from your terminal to that of another user. When first called, it sends the message: .IP .CI "Message from \&" yourname " (" yourterminal\c .CI ") [ \&" date " ] ..." .PP to the receiving .IR user 's terminal. When it has successfully completed the connection, it also sends two bells to your own terminal to indicate that what you are typing is being sent. .PP To set up two-way communication, the recipient of the message .RI ( user ) must execute the command: .IP .CI "write \&" "yourname\0\f1[\fPyourterminal\f1]\fP" .PP .RI ( yourterminal is only required if the originator is logged in more than once.) .PP Communication continues until an end of file is read from the terminal, an interrupt is sent, or the recipient executes .CR "mesg n" . At that point, .CR write writes .CR on the other terminal and exits. .PP To write to a user who is logged in more than once, use the .I terminal argument to indicate which line or terminal to send to (e.g., .CR tty00 ). Otherwise, the first writable instance of the user found in .CR /etc/utmp is assumed and the following message is displayed: .IP .IC user "\& is logged on more than one place." .br .tr~" .CI "You are connected to ~" terminal "~." .br .tr~~ .C "Other locations are: .br .I terminal .br \&... .PP Permission to write may be denied or granted with the .CR mesg command (see .IR mesg (1)). Writing to others is normally allowed by default. Certain commands, in particular .CR nroff and .CR pr disallow messages in order to prevent interference with their output. However, if the user has the appropriate privileges, messages can be forced onto a write-inhibited terminal. .PP If the character .CR !\&\" \& prevents two spaces after ! is found at the beginning of a line, .CR write calls the Bourne shell (see .IR sh-bourne (1)) to execute the rest of the line as a command. .PP The following protocol is suggested for using .CR write : When you first .CR write to another user, wait for the user to .CR write back before starting to send. Each person should end a message with a distinctive signal (such as "\c .CR (o)\c " for "over") so that the other person knows when to reply. Similarly, the signal "\c .CR (oo)\c " (for "over and out") can be used to indicate the end of the conversation. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the locale to use for the locale categories when both .C LC_ALL and the corresponding environment variable (beginning with .CR LC_ ) do not specify a locale. If .C LANG is not set or is set to the empty string, a default of "C" (see .IR lang (5)) is used. .PP .CR LC_TIME determines the format and contents of date and time strings. .PP .C LC_MESSAGES determines the language in which messages are displayed. .PP If any internationalization variable contains an invalid setting, .CR write behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS .TP .IC user " is not logged on." The user you are trying to write to is not logged on. .TP .CI "Can no longer write to \&" terminal Your correspondent has denied write permission .RC ( "mesg n" ) after your .CR write session started. Your .CR write session is ended. .TP .CR Your correspondent sent end-of-file, or you set your terminal to .CR "mesg n" and your correspondent tried to write to you. If you have a .CR write session established, you can continue to write to your correspondent. .TP .C "Permission denied. The user you are trying to write to has denied write permission (with .CR "mesg n" ). .TP .tr ~" .C "Warning: You have your terminal set to ~mesg -n~. No reply possible." .br .tr ~~ Your terminal is set to .CR "mesg n" and the recipient cannot respond to you. .SH EXAMPLES By issuing the command: .IP .C "write matthew .PP user .CR linda sends a message to user .CR matthew 's screen. If .CR matthew responds: .IP .C "write linda" .PP two-way communication between .CR matthew and .CR linda is established. .SH FILES .TP 20 .CR /etc/utmp To find user .PD 0 .TP .CR /usr/bin/sh To execute .CR !\&\" \& prevents two spaces after ! shell commands .PD .SH SEE ALSO elm(1), mail(1), mailx(1), mesg(1), nroff(1), pr(1), sh(1), who(1). .SH STANDARDS CONFORMANCE .CR write ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" toc@\f3write(1)\f1:\0\0\f4write\f1@@@interactively write (talk) to another user .\" .\" index@\f4write\f1 \- interactively write (talk) to another user@@@\f3write(1)\f1 .\" index@\f1interactively write (talk) to another user@@@\f3write(1)\f1 .\" index@\f1communicate interactively with another user@@@\f3write(1)\f1 .\" index@\f1user, communicate interactively with another@@@\f3write(1)\f1 .TH X11START 1 "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .SH NAME x11start - start the X11 window system .SH SYNOPSIS .B x11start [\fIoptions\fP] .SH DESCRIPTION .PP .B NOTE: Beginning with the next release of HP-UX, \fIx11start\fP and its components (\fIxinit, sys.x11start,\fP and \fIsys.Xdefaults\fP) will \fInot\fP be supported. \fIvuelogin\fP (an enhanced version of \fIxdm\fP) will perform all start-up tasks, regardless of whether or not HP-VUE is in use. See the \fIHP Visual Environment User's Guide\fP and the \fIvuelogin\fP man page for information on \fIvuelogin\fP. .PP .I x11start is a shell script that provides a standarized method for starting up the X Window System server and selected X clients when the Visual User Environment (HP-VUE) is not used. Specifically, it performs the following start-up tasks: .TP 4 .B " \(bu" PATH environment variable set-up appropriate for the X environment .PD 0 .TP 4 .B " \(bu" X server start-up .TP 4 .B " \(bu" selected client(s) start-up from a specific client file .TP 4 .B " \(bu" general user resource loading from a specific resource file .PD .SS Components .I x11start encompasses the following components: .TP 4 .B " \(bu" the \fI/usr/bin/x11start\fP script .PD 0 .TP 4 .B " \(bu" the \fI/usr/bin/X11/xinit\fP program .TP 4 .B " \(bu" the default client script, \fI/usr/lib/X11/sys.x11start\fP .TP 4 .B " \(bu" the default resouce file, \fI/usr/lib/X11/sys.Xdefaults\fP .PD .TP 4 .I The x11start script .PD 0 .TP 4 \ \(bu creates a command to load resources from the appropriate resource file using \fIxrdb\fP (see \fIxrdb(1)\fP) (This command is not executed immediately but rather is assigned to the (exported) environment variable, \fBdoxrdb\fP which is normally executed via the client script after the server has been started up.) .TP 4 \ \(bu inserts \fI/usr/bin/X11\fP ahead of \fI/usr/bin\fP in the \fBPATH\fP environment variable and appends \fI/usr/vue/bin\fP to the end .TP 4 \ \(bu execs \fIxinit\fP as follows (see \fIxinit(1)\fP): .sp xinit \fIclientscript\fP \fIoptions\fP .sp where .TP 17 .I " clientscript" is \fI$HOME/.x11start\fP or \fI/usr/lib/X11/sys.x11start\fP .TP 17 .I " options" are the \fIxinit\fP options exactly as specified on the \fIx11start\fP command line (see \fBOptions\fP below). .PD .TP 4 .I The xinit program .PD 0 .TP 4 \ \(bu starts the server with the server arguments specified in \fIoptions\fP .TP 4 \ \(bu runs the client script, passing it the client arguments specified in \fIoptions\fP .TP 4 \ \(bu waits for either the server or client script to terminate and then terminates whatever remains running .PD .TP 4 .I The default client script, /usr/lib/X11/sys.x11start .PD 0 .TP 4 \ \(bu executes the environment variable, \fB$doxrdb\fP which was setup previously by \fIx11start\fP to load the appropriate resource file to the server .TP 4 \ \(bu runs both \fImwm\fP and \fIhpterm\fP with all client arguments specified in \fIoptions\fP .TP 4 \ \(bu sleeps indefinitely so that the X Window System will not be shut down by \fIxinit\fP when all client script processes have terminated. .PD .TP 4 .I The default resource file, /usr/lib/X11/sys.Xdefaults .PD 0 .TP 4 \ \(bu sets the default \fIForeground\fP, \fIBackground\fP and \fIBorderColor\fP resources .TP 4 \ \(bu contains sample resources for a number of common clients. .PD .TP 4 .I Customized client and resource files can be created by copying the default files to \fI$HOME/.x11start\fP and \fI$HOME/.Xdefaults\fP, respectively, and then customizing them. Customized files that exist (with the appropriate permissions) will be used by the \fIx11start\fP components in place of the default files. .SS Options \fIx11start\fP \fIoptions\fP are the same as \fIxinit\fP options except that a client script cannot be specified. .PP Arguments preceeding a "--" (double dash), or all arguments if "--" is not specified, are passed on to the client script and can be accessed as positional parameters within that script. .PP Arguments following a "--" that begins with a slash (/) or a period (.) identify the server. If a server is not explicity specified, \fIxinit\fP determines the server from \fB$DISPLAY\fP if defined; otherwise from \fB$XSERVERRC\fP. If neither of these are defined, \fI$HOME/.xserverrc\fP is used if it exists and is executable; otherwise \fIX :0\fP is used. .PP Arguments following a "--" that don't begin with a slash or period are passed on to the appropriate server. .PP See \fIxinit(1)\fP for more details. .SH EXAMPLES The following examples illustrate how \fIx11start\fP can be used to control the server and/or interact with the client script. .TP 15 .B x11start This starts the default \fIxinit\fP server and executes the client script (either \fI/usr/lib/X11/sys.x11start or \fP\fI$HOME/.x11start\fP) without passing arguments to either. .TP 15 .B x11start -bg black -fn 24x36 This starts the default \fIxinit\fP server and executes the client script, passing it all of the arguments. If the default client script is used, \fI-bg black -fn 24x36\fP is be passed to both \fImwm\fP and \fIhpterm\fP since both of their default command lines contain "$@". If the default client script is used, the actual \fIxinit\fP command executed is: .sp xinit /usr/lib/X11/sys.x11start -bg black -fn 24x36 .TP 15 .B "x11start -fg white -- :1" This starts the default server on display 1 and executes the client script with the arguments, \fI-fg white\fP. If the customized client script is used, the \fIxinit\fP command line is: .sp xinit $HOME/.x11start -fg white -- :1 .TP 15 .B "x11start -- Xhp -a2 -t 5" This starts the server, \fIXhp\fP with the arguents, \fI-a2 -t 5\fP and then executes the client script without any arguments. .SH "ENVIRONMENT VARIABLES" .PP .B DISPLAY .br .B PATH .br .B XSERVERRC .br .B doxrgb .SH FILES .PP .I /usr/lib/X11/sys.Xdefaults .br .I /usr/lib/X11/sys.x11start .br .I $HOME/.Xdefaults .br .I $HOME/.x11start .br .I $HOME/.xserverrc .PP .SH ORIGIN HP .SH "SEE ALSO" .PP X(1), xinit(1), hpterm(1), mwm(1), xrdb(1) .\" $Header: xargs.1,v 76.1 95/07/11 13:48:46 ssa Exp $ .TA x .TH xargs 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xargs \- construct argument list(s) and execute command .SH SYNOPSIS .C xargs .RI [ \|options\| ] .RI [ \|command .RI [ \|initial-arguments\| ]\|] .SH DESCRIPTION .C xargs combines the fixed .I initial-arguments with arguments read from standard input to execute the specified .I command one or more times. The number of arguments read for each .I command invocation and the manner in which they are combined are determined by the options specified. .PP .IR command , which can be a shell file, is searched for, using the .C $PATH environment variable. If .I command is omitted, .C /usr/bin/echo is used. .PP Arguments read in from standard input are defined to be contiguous strings of characters delimited by one or more blanks, tabs, or new-lines; empty lines are always discarded. Spaces and tabs can be embedded as part of an argument if escaped or quoted. Characters enclosed in quotes (single or double) are taken literally, and the delimiting quotes are removed. Outside of quoted strings, a backslash .RC ( \e ) escapes the next character. .PP The amount of memory available for the execution of .I command is limited by the system parameter .CR ARG_MAX . By default, the size of the argument list is limited to .C LINE_MAX bytes. See .IR limits (5) and .IR sysconf (2) for a description of these system parameters and how their values can be determined. To increase the available argument list space, use the .C -s option. .PP Each argument list is constructed starting with the .IR initial-arguments , followed by some number of arguments read from standard input (exception: see .C -i or .C -I option). The .CR -i , .CR -I , .CR -l , .CR -L , and .C -n options determine how arguments are selected for each command invocation. When none of these options is specified, the .I initial-arguments are followed by arguments read continuously from standard input until an internal buffer is full, then .I command is executed with the accumulated args. This process is repeated until there are no more args. When there are option conflicts (such as .C -l or .C -L versus .CR -n ), the last option has precedence. .I option values are: .RS .TP 15 .CI -L \0number .I command is executed for each non-empty .I number lines of arguments from standard input. The last invocation of .I command will be with fewer lines of arguments if fewer than .I number remain. A line is considered to end with the first new-line .I unless the last character of the line is a blank or a tab; a trailing blank/tab signals continuation through the next non-empty line. The .CR -L , .CR -l , and .C -n options are mutually exclusive. The last one specified takes effect. .TP .CR -l [ \0\f2number\f1\0 ] This option is equivalent to the .C -L option. .C 1 is assumed if .I number is omitted or is given as the empty string ( \f3""\f1 ). Option .C -x is forced. .TP .CI -I \0replstr Insert mode: .I command is executed for each line from standard input, taking the entire line as a single arg, inserting it in .I initial-arguments for each occurrence of .IR replstr . A maximum of 5 arguments in .I initial-arguments can each contain one or more instances of .IR replstr . Blanks and tabs at the beginning of each line are discarded. Constructed arguments must not grow larger than 255 bytes, and option .C -x is also forced. The .C -I and .C -i options are mutually exclusive. The last one specified takes effect. .TP .CR -i [ \0\f2repstr\f1\0 ] This option is equivalent to the .C -I option. .C {\|} is assumed if .I replstr is omitted or is given as the empty string ( \f3""\f1 ). .TP .CI -n \0number Execute .I command using as many standard input arguments as possible, up to .I number arguments maximum. Fewer arguments are used if their total size is greater than .I size bytes, and for the last invocation if there are fewer than .I number arguments remaining. If option -x is also coded, each .I number arguments must fit in the .I size limitation or .C xargs terminates execution. .TP .CI -s \0size The maximum total size of each argument list is set to .I size bytes; .I size must be a positive integer less than .C LINE_MAX (see .IR limits (5), .IR sysconf (2)). If .C -s is not coded, .C LINE_MAX is taken as the default. Note that the bytes count for .I size includes one extra bytes for each argument and the count of bytes in the command name. .TP .C -t Trace mode: The .I command and each constructed argument list are echoed to standard error just prior to their execution. .TP .C -p Prompt mode: The user is asked whether to execute .I command prior to each invocation. Trace mode .RC ( -t ) is turned on to print the command instance to be executed, followed by a .C ?... prompt. An affirmative reply (by default, an affirmative reply is .C y optionally followed by anything) executes the command; anything else, including pressing Return, skips that particular invocation of .IR command . .TP .C -x Causes .I xargs to terminate if any argument list would be greater than .I size bytes. .C -x is forced by the options .CR -i , .CR -I , .CR -l , and .CR -L . When none of the options .CR -i , .CR -I , .CR -l , .CR -L , or .C -n is coded, the total length of all arguments must be within the .I size limit. .TP .CR -e [ \0\f2eofstr\f1\0 ] .I eofstr is taken as the logical end-of-file string. Underscore .RC ( _ ) is assumed for the logical .C EOF string if neither .C -e nor .C -E is used. The value .C -e with .I eofstr given as the empty string ( \f3""\f1 ) turns off the logical .C EOF string capability (underscore is taken literally). .I xargs reads standard input until either end-of-file or the logical .C EOF string is encountered. .TP .CI -E \0eofstr Specify a logical end-of-file string to replace the default underscore .RC ( _ ) character. Equivalent to the .C -e option above. .RE .PP .I xargs terminates if it receives a return code of \(mi1 from .I command or if it cannot execute .IR command . When .I command is a shell program, it should explicitly .C exit (see .IR sh (1)) with an appropriate value to avoid accidentally returning with \(mi1. .SH RETURN VALUE .C xargs exits with one of the following values: .RS .TP 5 .B \00 All invocations of .I command completed successfully. .TP .B 1-125 One or more invocations of .I command did not complete successfully. .TP .B 126 The .I command specified was found but could not be invoked. .TP .B 127 The .I command specified could not be found. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_CTYPE determines the space characters and the interpretation of text as single- and/or multi-byte characters. .PP .C LC_MESSAGES determines the language in which messages are displayed, and the local language equivalent of an affirmative reply when the .C -p prompt option is specified. .PP If .C LC_CTYPE or .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C xargs behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES Move all files from directory .C $1 to directory .CR $2 , and echo each move command just before doing it: .IP .C "ls $1 | xargs -i -t mv $1/{} $2/{}" .PP Combine the output of the parenthesized commands onto one line, then echo to the end of file .CR log : .IP .C "(logname; date; echo $0 $*) | xargs >>log" .PP Ask the user which files in the current directory are to be archived then archive them into .C arch one at a time: .IP .C "ls | xargs -p -l ar r arch" .PP or many at a time: .IP .C "ls | xargs -p -l | xargs ar r arch" .PP Execute .C diff (see .IR diff (1)) with successive pairs of arguments originally typed as shell arguments: .IP .C "echo $* | xargs -n2 diff" .SH SEE ALSO sh(1). .SH STANDARDS CONFORMANCE .CR xargs ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4xargs\f1 \- construct argument list(s) and execute command@@@\f3xargs(1)\f1 .\" index@\f1construct argument list(s) and execute command@@@\f3xargs(1)\f1 .\" index@\f1execute command with constructed large argument list(s)@@@\f3xargs(1)\f1 .\" index@\f1large argument list(s), construct, and execute command@@@\f3xargs(1)\f1 .\" index@\f1argument list(s), large, construct and execute command@@@\f3xargs(1)\f1 .\" index@\f1too many arguments (error); construct argument list(s) and execute command@@@\f3xargs(1)\f1 .\" index@\f1arguments, too many (error); construct argument list(s) and execute command@@@\f3xargs(1)\f1 .\" .\" toc@\f3xargs(1)\f1:\0\0\f4xargs\f1@@@construct argument list(s) and execute command .\" .\" $XConsortium: xauth.man,v 1.9 91/12/16 20:30:02 gildea Exp $ .TH XAUTH 1 "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .SH NAME xauth \- X authority file utility .SH SYNOPSIS .B xauth [ \fB\-f\fP \fIauthfile\fP ] [ \fB\-vqib\fP ] [ \fIcommand arg ...\fP ] .SH DESCRIPTION .PP The \fIxauth\fP program is used to edit and display the authorization information used in connecting to the X server. This program is usually used to extract authorization records from one machine and merge them in on another (as is the case when using remote logins or granting access to other users). Commands (described below) may be entered interactively, on the \fIxauth\fP command line, or in scripts. Note that this program does \fBnot\fP contact the X server. .SH OPTIONS The following options may be used with \fIxauth\fP. They may be given individually (e.g., \fI\-q \-i\|\fP) or may combined (e.g., \fI\-qi\|\fP). .TP 8 .B "\-f \fIauthfile\fP" This option specifies the name of the authority file to use. By default, \fIxauth\fP will use the file specified by the XAUTHORITY environment variable or \fI\.Xauthority\fP in the user's home directory. .TP 8 .B \-q This option indicates that \fIxauth\fP should operate quietly and not print unsolicited status messages. This is the default if an \fIxauth\fP command is is given on the command line or if the standard output is not directed to a terminal. .TP 8 .B \-v This option indicates that \fIxauth\fP should operate verbosely and print status messages indicating the results of various operations (e.g., how many records have been read in or written out). This is the default if \fIxauth\fP is reading commands from its standard input and its standard output is directed to a terminal. .TP 8 .B \-i This option indicates that \fIxauth\fP should ignore any authority file locks. Normally, \fIxauth\fP will refuse to read or edit any authority files that have been locked by other programs (usually \fIxdm\fP or another \fIxauth\fP). .TP 8 .B \-b This option indicates that \fIxauth\fP should attempt to break any authority file locks before proceeding. Use this option only to clean up stale locks. .SH COMMANDS The following commands may be used to manipulate authority files: .TP 8 .B "add \fIdisplayname protocolname hexkey" An authorization entry for the indicated display using the given protocol and key data is added to the authorization file. The data is specified as an even-lengthed string of hexadecimal digits, each pair representing one octet. The first digit of each pair gives the most significant 4 bits of the octet, and the second digit of the pair gives the least significant 4 bits. For example, a 32 character hexkey would represent a 128-bit value. A protocol name consisting of just a single period is treated as an abbreviation for \fIMIT-MAGIC-COOKIE-1\fP. .TP 8 .B "[n]extract \fIfilename displayname..." Authorization entries for each of the specified displays are written to the indicated file. If the \fInextract\fP command is used, the entries are written in a numeric format suitable for non-binary transmission (such as secure electronic mail). The extracted entries can be read back in using the \fImerge\fP and \fInmerge\fP commands. If the filename consists of just a single dash, the entries will be written to the standard output. .TP 8 .B "[n]list \fR[\fIdisplayname\fP...]" Authorization entries for each of the specified displays (or all if no displays are named) are printed on the standard output. If the \fInlist\fP command is used, entries will be shown in the numeric format used by the \fInextract\fP command; otherwise, they are shown in a textual format. Key data is always displayed in the hexadecimal format given in the description of the \fIadd\fP command. .TP 8 .B "[n]merge \fR[\fIfilename\fP...]" Authorization entries are read from the specified files and are merged into the authorization database, superceding any matching existing entries. If the \fInmerge\fP command is used, the numeric format given in the description of the \fIextract\fP command is used. If a filename consists of just a single dash, the standard input will be read if it hasn't been read before. .TP 8 .B "remove \fIdisplayname\fR..." Authorization entries matching the specified displays are removed from the authority file. .TP 8 .B "source \fIfilename" The specified file is treated as a script containing \fIxauth\fP commands to execute. Blank lines and lines beginning with a sharp sign (#) are ignored. A single dash may be used to indicate the standard input, if it hasn't already been read. .TP 8 .B "info" Information describing the authorization file, whether or not any changes have been made, and from where \fIxauth\fP commands are being read is printed on the standard output. .TP 8 .B "exit" If any modifications have been made, the authority file is written out (if allowed), and the program exits. An end of file is treated as an implicit \fIexit\fP command. .TP 8 .B "quit" The program exits, ignoring any modifications. This may also be accomplished by pressing the interrupt character. .TP 8 .B "help [\fIstring\fP]" A description of all commands that begin with the given string (or all commands if no string is given) is printed on the standard output. .TP 8 .B "?" A short list of the valid commands is printed on the standard output. .SH "DISPLAY NAMES" Display names for the \fIadd\fP, \fI[n]extract\fP, \fI[n]list\fP, \fI[n]merge\fP, and \fIremove\fP commands use the same format as the DISPLAY environment variable and the common \fI\-display\fP command line argument. Display-specific information (such as the screen number) is unnecessary and will be ignored. Same-machine connections (such as local-host sockets, shared memory, and the Internet Protocol hostname \fIlocalhost\fP) are referred to as \fIhostname\fP/unix:\fIdisplaynumber\fP so that local entries for different machines may be stored in one authority file. .SH EXAMPLE .PP The most common use for \fIxauth\fP is to extract the entry for the current display, copy it to another machine, and merge it into the user's authority file on the remote machine: .sp .nf % xauth extract \- $DISPLAY | rsh otherhost xauth merge \- .fi .SH ENVIRONMENT This \fIxauth\fP program uses the following environment variables: .TP 8 .B XAUTHORITY to get the name of the authority file to use if the \fI\-f\fP option isn't used. .TP 8 .B HOME to get the user's home directory if XAUTHORITY isn't defined. .SH FILES .TP 8 .I $HOME/.Xauthority default authority file if XAUTHORITY isn't defined. .SH BUGS .PP Users that have unsecure networks should take care to use encrypted file transfer mechanisms to copy authorization entries between machines. Similarly, the \fIMIT-MAGIC-COOKIE-1\fP protocol is not very useful in unsecure environments. Sites that are interested in additional security may need to use encrypted authorization mechanisms such as Kerberos. .PP Spaces are currently not allowed in the protocol name. Quoting could be added for the truly perverse. .SH COPYRIGHT Copyright 1989, Massachusetts Institute of Technology. .br See \fIX\fP(1) for a full statement of rights and permissions. .SH AUTHOR Jim Fulton, MIT X Consortium .de EX .ne 5 .if n .sp 1 .if t .sp .5 .nf .in +.5i .. .de EE .fi .in -.5i .if n .sp 1 .if t .sp .5 .. .TH XCAL 1 "" "" HP-UX .SH NAME xcal - display calendar in an X11 window .SH SYNOPSIS .B xcal [ .I options ] .SH DESCRIPTION The .I xcal program prints a calendar for the current month in an X11 window. The calendar highlights the current day of the month. At midnight the calendar redraws itself to display the new date. .PP The calendar displayed is the Gregorian calendar for years after 1752 and the Julian calendar for years prior to 1752. The displayed calendar is the same as "/usr/bin/cal" for compatibility. .PP The .I xcal window can display the calendar for other months of any year. When the xcal window is active, the following keyboard keys affect the calendar as follows: .in 5 .TP 15 .B The key \fBChanges the calendar to the: .TP 15 .I Left arrow Previous month. .TP .I Prev Previous month. .TP .I Right arrow Next month. .TP .I Next Next month. .TP .I Up arrow Same month of the next year. .TP .I Down arrow Same month of the previous year. .TP .I Home arrow Current month. .TP .I Clear line Current month. .TP .I Clear display Current month. .in .PP The mouse may also be used to change the calendar. Two arrows appear on the top line of the calendar. Pressing a mouse button on the left arrow changes the calendar to the previous month. The right arrow changes the calendar to the next month. Press a mouse button anywhere else on the window and the calendar reverts to the current month. .SH OPTIONS .TP .BI -display " display" Specifies the server to connect to; see X(1). .TP .BI -geometry " spec" Specify the size and location of the window in pixels. .TP .BI -fg " color" Specify the foreground (text) color. .TP .BI -bg " color" Specify the background color. .TP .BI -fn " font" Specify the font used to display the calendar. .TP .BI -vSpace " pixels" Specify the vertical padding of the calendar. .TP .BI -hSpace " pixels" Specify the horizontal padding of the calendar. .SH ENVIRONMENT .TP .B DISPLAY The default host and display number. .SH X RESOURCES .I xcal is configured from the X11 defaults files: .EX /usr/lib/X11/app-defaults/XCal $HOME/.Xdefaults or $HOME/.vue/$DISPLAY/current/vue.resources .EE The app-defaults file sets up the system-wide .I xcal configuration. The user's personal $HOME/.Xdefaults modifies the behavior of .I xcal for the user. If you are using the Visual User Environment (VUE), then see also the .B VUE CUSTOMIZATION section, below. The rest of this section describes resources that can be customized in the .I .Xdefaults file. The syntax for all .I xcal resources is .br XCal.: .br For example, .br XCal.hSpace:10 .br Specific resource options for the calendar are: .TP 20 .B Font Font used for the calendar. .br (default = fixed) .TP .B Geometry Size and/or location of the window. .br (default = based on size of font) .TP .B Foreground Foreground (text) color .br (default is `black'). .TP .B Background Background color .br (default is `white'). .TP .B hSpace Horizontal padding of the window in pixels. Ignored if geometry width is specified. .br (default is `5'). .TP .B vSpace Vertical padding of the window in pixels. Ignored if geometry height is specified. .br (default is `2'). .SH VUE CUSTOMIZATION If you are using the Visual User Environment (VUE) then you must let VUE know when you make changes to your .I .Xdefaults file. In order for your changes to take effect, run: xrdb -nocpp -merge $HOME/.Xdefaults VUE automatically saves your new defaults in the file .I $HOME/.vue/$DISPLAY/current/vue.resources. You can also edit the vue.resources file directly. If you do so, and want to store your changes for the next time you login, then run: xrdb -load $HOME/.vue.$DISPLAY.current/vue.resources .B Background Information for the X-Knowledgeable Reader The X Resource Data Base (xrdb) allows users to customize the look and behavior of their applications. The advantage of using xrdb becomes apparent in a distributed environment where a program may be running on one machine and displaying output on another machine. This allows users to specify different defaults for the different systems they use. The xrdb is kept on the server side (the display side), not on the client side (where the program is running). Therefore, at run time the program can check to see what kind of display it is displaying to. You can use any file (not just .I .Xdefaults ) to specify customizations, and then run: xrdb -nocpp -merge But this is not recommended, because some clients do not use xrdb. Any additions or changes of defaults should be made to both .I .Xdefaults and the xrdb files. .SH FILES .I /usr/lib/X11/app-defaults/XCal .br .I ${HOME}/.Xdefaults or .I $HOME/.vue/$DISPLAY/current/vue.resources .SH SEE ALSO .I cal(1) .SH WARNINGS Requires HP-UX version 6.5, and X11 version 3. .SH AUTHOR .I xcal was developed by HP to operate under the X Window System. .\" index \fIxcal\fR \- display calendar in an X11 window \s-2XCAL\s+1(1)\s+1 .\" index calendar, display in an X11 window \s-XCAL\s+1(1)\s+1 .\" toc \s-2xcal\s+1(1)\s+1:\0\0\fIxcal\fR display calendar in an X11 window .\" $XConsortium: xclock.man /main/26 1995/12/15 14:02:11 gildea $ .\" Copyright (c) 1988, 1994 X Consortium .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the .\" "Software"), to deal in the Software without restriction, including .\" without limitation the rights to use, copy, modify, merge, publish, .\" distribute, sublicense, and/or sell copies of the Software, and to .\" permit persons to whom the Software is furnished to do so, subject to .\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included .\" in all copies or substantial portions of the Software. .\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR .\" OTHER DEALINGS IN THE SOFTWARE. .\" .\" Except as contained in this notice, the name of the X Consortium shall .\" not be used in advertising or otherwise to promote the sale, use or .\" other dealings in this Software without prior written authorization .\" from the X Consortium. .TH XCLOCK 1 "Release 6.1" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 April 1996 .SH NAME xclock \- analog / digital clock for X .SH SYNOPSIS .ta 8n \fBxclock\fP [ \fB\-help\fP ] [ \fB\-analog\fP ] [ \fB\-digital\fP ] [ \fB\-chime\fP ] [ \fB\-hd\fP \fIcolor\fP ] [ \fB\-hl\fP \fIcolor\fP ] [ \fB\-update\fP \fIseconds\fP ] [ \fB\-padding\fP \fInumber\fP ] .SH DESCRIPTION The .I xclock program displays the time in analog or digital form. The time is continuously updated at a frequency which may be specified by the user. .SH OPTIONS .I Xclock accepts all of the standard X Toolkit command line options along with the additional options listed below: .TP 8 .B \-help This option indicates that a brief summary of the allowed options should be printed on the standard error. .TP 8 .B \-analog This option indicates that a conventional 12 hour clock face with tick marks and hands should be used. This is the default. .TP 8 \fB\-digital\fP or \fB\-d\fP This option indicates that a 24 hour digital clock should be used. .TP 8 .B \-chime This option indicates that the clock should chime once on the half hour and twice on the hour. .TP 8 \fB\-hands\fP \fIcolor\fP (or \fB\-hd\fP \fIcolor\fP) This option specifies the color of the hands on an analog clock. The default is \fIblack\fP. .TP 8 \fB\-highlight\fP \fIcolor\fP (or \fB\-hl\fP \fIcolor\fP) This option specifies the color of the edges of the hands on an analog clock, and is only useful on color displays. The default is \fIblack\fP. .TP 8 .B \-update \fIseconds\fP This option specifies the frequency in seconds at which \fIxclock\fP should update its display. If the clock is obscured and then exposed, it will be updated immediately. A value of 30 seconds or less will enable a second hand on an analog clock. The default is 60 seconds. .TP 8 .B \-padding \fInumber\fP This option specifies the width in pixels of the padding between the window border and clock text or picture. The default is 10 on a digital clock and 8 on an analog clock. .SH X DEFAULTS This program uses the .I Clock widget. It understands all of the core resource names and classes as well as: .PP .TP 8 .B width (\fPclass\fB Width) Specifies the width of the clock. The default for analog clocks is 164 pixels; the default for digital clocks is whatever is needed to hold the clock when displayed in the chosen font. .TP 8 .B height (\fPclass\fB Height) Specifies the height of the clock. The default for analog clocks is 164 pixels; the default for digital clocks is whatever is needed to hold the clock when displayed in the chosen font. .TP 8 .B update (\fPclass\fB Interval) Specifies the frequency in seconds at which the time should be redisplayed. .TP 8 .B foreground (\fPclass\fB Foreground) Specifies the color for the tic marks. The default is depends on whether \fIreverseVideo\fP is specified. If \fIreverseVideo\fP is specified the default is \fIlwhite\fP, otherwise the default is \fIblack\fP. .TP 8 .B hands (\fPclass\fB Foreground) Specifies the color of the insides of the clock's hands. The default is depends on whether \fIreverseVideo\fP is specified. If \fIreverseVideo\fP is specified the default is \fIlwhite\fP, otherwise the default is \fIblack\fP. .TP 8 .B highlight (\fPclass\fB Foreground) Specifies the color used to highlight the clock's hands. The default is depends on whether \fIreverseVideo\fP is specified. If \fIreverseVideo\fP is specified the default is \fIlwhite\fP, otherwise the default is \fIblack\fP. .TP 8 .B analog (\fPclass\fB Boolean) Specifies whether or not an analog clock should be used instead of a digital one. The default is True. .TP 8 .B chime (\fPclass\fB Boolean) Specifies whether or not a bell should be rung on the hour and half hour. .TP 8 .B padding (\fPclass\fB Margin) Specifies the amount of internal padding in pixels to be used. The default is 8. .TP 8 .B font (\fPclass\fB Font) Specifies the font to be used for the digital clock. Note that variable width fonts currently will not always display correctly. .SH WIDGETS In order to specify resources, it is useful to know the hierarchy of the widgets which compose \fIxclock\fR. In the notation below, indentation indicates hierarchical structure. The widget class name is given first, followed by the widget instance name. .sp .nf .TA .5i .ta .5i XClock xclock Clock clock .fi .sp .SH ENVIRONMENT .PP .TP 8 .B DISPLAY to get the default host and display number. .TP 8 .B XENVIRONMENT to get the name of a resource file that overrides the global resources stored in the RESOURCE_MANAGER property. .SH FILES /lib/X11/app-defaults/XClock - specifies required resources .SH "SEE ALSO" X(1), xrdb(1), time(3C) .SH BUGS .I Xclock believes the system clock. .PP When in digital mode, the string should be centered automatically. .SH AUTHORS Tony Della Fera (MIT-Athena, DEC) .br Dave Mankins (MIT-Athena, BBN) .br Ed Moy (UC Berkeley) .TH XCMSDB 1 "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .SH NAME xcmsdb \- Xlib Screen Color Characterization Data utility .SH SYNOPSIS .B xcmsdb [\-option ...] [\fIfilename\fP] .SH DESCRIPTION .I xcmsdb is used to load, query, or remove Screen Color Characterization Data stored in properties on the root window of the screen. Screen Color Characterization Data is an integral part of Xlib, necessary for proper conversion between device-independent and device-dependent color specifications. Xlib uses the XDCCC_LINEAR_RGB_MATRICES and XDCCC_LINEAR_RGB_CORRECTION properties to store color characterization data for color monitors. It uses XDCCC_GRAY_SCREENWWHITEPOINT and XDCCC_GRAY_CORRECTION properties for gray scale monitors. Because Xlib allows the addition of Screen Color Characterization Function Sets, added function sets may place their Screen Color Characterization Data on other properties. This utility is unaware of these other properties, therefore, you will need to use a similar utility provided with the function set, or use the .I xprop utility. .LP The ASCII readable contents of .I filename (or the standard input if no input file is given) are appropriately transformed for storage in properties, provided the .B \-query or .B \-remove options are not specified. .SH "OPTIONS" .PP .I xcmsdb program accepts the following options: .TP 8 .B \-query This option attempts to read the XDCCC properties off the screen's root window. If successful, it transforms the data into a more readable format, then sends the data to standard out. .TP 8 .B \-remove This option attempts to remove the XDCCC properties on the screen's root window. .TP 8 .B \-color This option sets the query and remove options to only check for the XDCCC_LINEAR_RGB_MATRICES and XDCCC_LINEAR_RGB_CORRECTION properties. If the \fB\-color\fP option is not set then the query and remove options check for all the properties. .TP 8 .B \-format 32 | 16 | 8 Specifies the property format (32, 16, or 8 bits per entry) for the XDCCC_LINEAR_RGB_CORRECTION property. Precision of encoded floating point values increases with the increase in bits per entry. The default is 32 bits per entry. .SH "SEE ALSO" xprop(1), Xlib documentation .SH ENVIRONMENT .TP 8 .B DISPLAY to figure out which display and screen to use. .SH BUGS .PP Unknown .SH COPYRIGHT Copyright 1990, Tektronix Inc. .SH AUTHOR Chuck Adams, Tektronix Inc. .\" $Header: od.1,v 76.1 95/08/23 17:32:12 ssa Exp $ .TA o .TH od 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME od, xd \- octal and hexadecimal dump .SH SYNOPSIS .IP .CR "od" .RC [ -v ] .RC [ -A .IR address_base \|] .RC [ -j .IR skip \|] .RC [ -N .IR count \|] .RC [ -t .IR type_string \|]\0... .RI [ \|file \0...\|] .IP .C xd .RC [ -v ] .RC [ -A .IR address_base \|] .RC [ -j .IR skip \|] .RC [ -N .IR count \|] .RC [ -t .IR type_string \|]\0... .RI [ \|file \0...\|] .PP The following pre-\c .SM POSIX usage is also supported. .IP .C od .RC [ -bcdosx ] .RI [ \|file\| ] .RC [\|[ + ]\|[ 0x ]\c .I offset\c .RC [ . ]\|[ b ]\|] .br .C xd .RC [ -bcdosx ] .RI [ \|file\| ] .RC [\|[ + ]\|[ 0x ]\c .I offset\c .RC [ . ]\|[ b ]\|] .SH DESCRIPTION .C od and .C xd concatenate one or more input .IR file s and write their contents to standard output in a user-specified format. If .I file is not specified, the standard input is used. .SS Options and Arguments .C od and .C xd recognize the following options and command-line arguments: .RS .TP 18 .CI -A \0address_base Specify the input offset base. .I address_base is a single character that defines which format the offset base is written in: .RS .RS .TP .C d Decimal format. .PD 0 .TP .C o Octal format. .TP .C x Hexadecimal format. .TP .C n Do not write the offset. .RE .RE .PD .TP .CI -j \0skip Jump over .I skip bytes from the beginning of the input. .C od seeks past the first .I skip bytes in the concatenated input files. If the combined input is not at least .I skip bytes long, .C od writes a diagnostic message to standard error and exits with a non-zero exit status. By default, .I skip is interpreted as a .I decimal number. If .I skip has a leading .C 0x or .CR 0X , it is interpreted as a .I hexadecimal number; a leading .C 0 indicates that .I skip is an .I octal number. .IP If the value of .I skip is followed by a .CR b , .CR k , or .CR m , it is interpreted as a multiple of 512, 1024, or 1048576, respectively. .TP .CI -N \0count Format no more than .I count bytes of input. .IP By default, .I count is interpreted as a .I decimal number. A leading .C 0x or .C 0X indicates that .I count is a .I hexadecimal number; a leading .C 0 identifies an .I octal value. .IP If .I count bytes of input are not available (after successfully skipping if .CI -j skip is specified), the input that is available is formatted. .TP .CI -t \0type_string .I type_string is a string defining the types to be used when writing the input data. .IP The string can contain any of the following type-specification characters: .RS .RS .TP 8 .C a named character , .PD 0 .TP .C c character , .TP .C d signed decimal , .TP .C f floating point , .TP .C o octal , .TP .C u unsigned decimal , .TP .C x hexadecimal , .RE .RE .PD .IP Type specification characters .CR d , .CR f , .CR o , .CR u , and .CR x can be followed by an optional .I unsigned decimal integer specifying the number of bytes to be transformed by each instance of the output type, or by an optional .CR C , .CR S , .CR I , or .CR L indicating that the conversion should be applied to an item of type .IR char , .IR short , .IR int , or .IR long , respectively. .IP Type specification character .C f can be followed by an optional .CR F , .CR D , or .C L indicating that the conversion should be applied to an item of type .IR float , .IR double , or .IR "long double" , respectively. .IP Multiple types can be concatenated within the same .I type_string and multiple .C -t options can be specified. Output lines are written for each type specified in the order in which the type specification characters appear. .TP .CI -v Write all input data. Without the .C -v option, any number of groups of output lines, that would be identical to the immediately preceding group of output lines (except for the byte offsets), are replaced with a line containing only an asterisk .RC ( * ). .TP .I file Pathname of one or more input files to be processed. If .I file is not specified, the standard input is used. .IP Input files can be any file type. .RE .SH DESCRIPTION OF PRE-POSIX USAGE .C od and .C xd dump .I file in one or more formats as selected by the first argument. If the first argument is missing, the default is .C -o for .CR od ; .C -x for .CR xd . An offset field is inserted at the beginning of each line. For .CR od , the offset is in octal, for .CR xd , the offset is in hexadecimal. .SS Options .C od and .C xd recognize the following format options: .RS .TP 6 .C -b Interpret bytes in octal (hexadecimal). .TP .C -c Interpret bytes in .SM ASCII. Certain non-graphic characters appear as C escapes: .RC null= \e0 , .RC backspace= \eb , .RC form-feed= \ef , .RC new-line= \en , .RC return= \er , .RC tab= \et ; others appear as 3-digit octal numbers. .TP .C -d Interpret 16-bit words in decimal. .TP .C -o Interpret 16-bit words in octal. .TP .C -s Interpret 16-bit words in signed decimal. .TP .C -x Interpret 16-bit words in hexadecimal. .RE .PP .I file specifies which file is to be dumped. If .I file is not specified, the standard input is used. .PP .I offset specifies the offset in the file where dumping is to commence, and is normally interpreted as octal bytes. Interpretation can be altered as follows: .RS .TP 3 \(bu .I offset must be preceded by .CR + if the file argument is omitted. .PD 0 .TP \(bu .I offset preceded by .B 0x is interpreted in hexadecimal. .TP \(bu .I offset followed by .C . is interpreted in decimal. .TP \(bu .I offset followed by .C b is interpreted in blocks of 512 bytes. .RS .PD .PP Dumping continues until end-of-file. .SH EXAMPLES Write hexadecimal bytes and the corresponding octal values to the standard output in blocks of 16 bytes in one line, by transforming the data from the input file .CR file1 : .IP .C od -tx1oC file1 .PP The following commands write one line each of the types .IR character , .IR "signed decimal integer" , and .IR float , in the order given, transforming 100 bytes of data starting from fifteenth byte offset in the file .CR file1 : .IP .C "od -j14 -N100 -tc -tdfF file1" .IP .C "od -j0xe -N100 -tcd4fF file1" .PP Write one line each of the types .IR "unsigned integer" , .IR "named character" , and .IR "long double" , with the offsets written in hexadecimal and forcing a write, even on lines that are identical to the immediately preceding group of output lines: .IP .C "od -v -Ax -tuafL file1" .SH WARNINGS When the output format is of floating-point type; i.e., when using the .CR "-t fD" , .CR "-t fL" , or .C -t f options: .RS .TP 3 \(bu If the input bytes cannot be transformed into a valid floating point number, a floating point exception might occur. In that case, the output is printed as a string containing some non-numeric characters and program execution continues. .TP \(bu When the number of input bytes used for transformation is set to 1 with the type specifier characters .CR d , .CR o , .CR u , or .CR x , only the least-significant seven bits of each byte are used. .TP \(bu When one or more of the .CR -A , .CR -j , .CR -N , or .C -t options is specified, an operand starting with the first character as a plus-sign .RC ( + ) or the first character as numeric is interpreted as a file name. .RE .PP (XPG4 only. Multiple types can be specified by using multiple .CR "-bcdox" options. Output lines are written for each type specified in the order in which the types are specified.) .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG provides a default value for the internationalization variables that are unset or null. If .C LANG is unset or null, the default value of "C" (see .IR lang (5)) is used. If any of the internationalization variables contains an invalid setting, .C od will behave as if all internationalization variables are set to "C". See .IR environ (5). .PP .C LC_ALL If set to a non-empty string value, overrides the values of all the other internationalization variables. .PP .C LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions. .PP .C LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output. .PP .C NLSPATH determines the location of message catalogues for the processing of .CR LC_MESSAGES . .PP .SS International Code Set Support Single- and multi-byte character code sets are supported. Multi-byte data is displayed as multi-byte values. .SH RETURN VALUE Exit values are: .TP .B \00 Successful completion. .PD 0 .TP .C >0 Error condition occurred. .PD .SH SEE ALSO adb(1). .SH STANDARDS CONFORMANCE .CR od ": SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4od\f1 \- octal file dump@@@\f3od(1)\f1 .\" index@\f4xd\f1 \- hexadecimal file dump@@@\f3od(1)\f1 .\" index@octal file dump@@@\f3od(1)\f1 .\" index@hexadecimal file dump@@@\f3od(1)\f1 .\" index@dump file in octal or hexadecimal format@@@\f3od(1)\f1 .\" index@files: dump file in octal or hexadecimal format@@@\f3od(1)\f1 .\" .\" toc@\f3od(1)\f1:\0\0\f4od\f1, \f4xd\f1@@@octal and hexadecimal dump .\" toc@\f4xd\f1: hexadecimal dump@@@see \f3od(1)\f1 .\" .\" links@od.1 xd.1 .\" .de EX .ne 5 .if n .sp 1 .if t .sp .5 .nf .in +.5i .. .de EE .fi .in -.5i .if n .sp 1 .if t .sp .5 .. .TH XDIALOG 1 "" "" HP-UX .SH NAME xdialog - display a message in an X11 Motif dialog window .SH SYNOPSIS .B xdialog [ .I options ] .SH DESCRIPTION The .I xdialog program reads a message from either the command line or from a file and displays the message in an X11 Motif dialog window. By default a single pushbutton labeled .I OK appears below the window. A message must be provided via either the command line (via the .B -m option) or from a file (via the .B -f option). .sp Command line options allow the user to specify a bitmap to be displayed left of the message, add a .I Cancel button, change the labels for the .I OK and .I Cancel buttons, and associate a command to run if/when the user selects the .I OK button. .sp The .B xdialog program can be used to query for Yes/No style responses; .B xdialog exits with a value of ``0'' when the .I OK button is selected, and a value of ``1'' with the .I Cancel button. .SH OPTIONS Several options can be used to change the behavior of .I xdialog: .TP .BI -display " display" Specifies the server to connect to; see X(1). .TP .BI -fg " color" Specify the foreground (text) color. .TP .BI -bg " color" Specify the background color. .TP .BI -m " message_string" Specify the message string to appear in the window. The string should be enclosed by quotes if it contains white space or newline characters. The .B -m and .B -f options are mutually-exclusive. .TP .BI -f " pathname" Specify the file to read The file .I pathname contains the text of the message to display. The .B -m and .B -f options are mutually-exclusive. .TP .BI -O " label_string" Specify a different label for the .I OK button. .TP .BI -C " label_string" Specify a different label for the .I Cancel button. This button also enables the .I Cancel button if is is not already enabled. .TP .BI -p " bitmap_file" Cause the bitmap specified in the file .I bitmap_file to appear to the left of the message area. .TP .BI -e " command_string" Associates the command specified by .I command_string with the .I OK button. If the user presses the .I OK button, then .B xdialog does a fork/exec of .I command_string. This option automatically turns on the .I Cancel button. .TP .BI -t " title_string" Use the specified string as the title of the window. .TP .B -c Cause the .I Cancel button to be the default button. This option causes the .I Cancel button to appear. .TP .B -o Cause the .I OK button to be the default button. This is the default behavior. This option causes the .I Cancel button to appear. .SH ENVIRONMENT .TP .B DISPLAY The default host and display number. .\" index \fIxdialog\fR \- display a message in an X11 Motif dialog window \s-2XDIALOG\s+1(1)\s+1 .\" toc \s-2xdialog\s+1(1)\s+1:\0\0\fIxdialog\fR display a message in an X11 Motif dialog window .\" Copyright (c) 1991 X Consortium .\" .\" Permission is hereby granted, free of charge, to any person obtaining a .\" copy of this software and associated documentation files (the "Software"), .\" to deal in the Software without restriction, including without limitation .\" the rights to use, copy, modify, merge, publish, distribute, sublicense, .\" and/or sell copies of the Software, and to permit persons to whom the .\" Software furnished to do so, subject to the following conditions: .\" .\" The above copyright notice and this permission notice shall be included in .\" all copies or substantial portions of the Software. .\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL .\" THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, .\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF .\" OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE .\" SOFTWARE. .\" .\" Except as contained in this notice, the name of the X Consortium shall not .\" be used in advertising or otherwise to promote the sale, use or other .\" dealing in this Software without prior written authorization from the .\" X Consortium. .\" Copyright 1991 Network Computing Devices .\" .\" Permission to use, copy, modify, distribute, and sell this software and .\" its documentation for any purpose is hereby granted without fee, provided .\" that the above copyright notice appear in all copies and that both that .\" copyright notice and this permission notice appear in supporting .\" documentation, and that the name of Network Computing Devices .\" not be used in advertising or .\" publicity pertaining to distribution of the software without specific, .\" written prior permission. Network Computing Devices make .\" no representations about the .\" suitability of this software for any purpose. It is provided "as is" .\" without express or implied warranty. .\" $XConsortium: xfs.man /main/12 1995/12/15 14:03:46 gildea $ .TH XFS 1 "Release 6.1" "X Version 11" .SH NAME xfs \- X font server .SH SYNOPSIS .B "xfs" [\-config \fIconfiguration_file\fP] [\-port \fItcp_port\fP] .SH DESCRIPTION .PP .I Xfs is the X Window System font server. It supplies fonts to X Window System display servers. .SH "STARTING THE SERVER" The server is usually run by a system administrator, and started via boot files like \fI/etc/rc.local\fR. Users may also wish to start private font servers for specific sets of fonts. .SH "OPTIONS" .TP 8 .B \-config configuration_file Specifies the configuration file the font server will use. .TP 8 .B \-ls listen-socket Specifies a file descriptor which is already set up to be used as the listen socket. This option is only intended to be used by the font server itself when automatically spawning another copy of itself to handle additional connections. .TP 8 .B \-port tcp_port Specifies the TCP port number on which the server will listen for connections. .SH "SIGNALS" .TP 8 .I SIGTERM This causes the font server to exit cleanly. .TP 8 .I SIGUSR1 This signal is used to cause the server to re-read its configuration file. .TP 8 .I SIGUSR2 This signal is used to cause the server to flush any cached data it may have. .TP 8 .I SIGHUP This signal is used to cause the server to reset, closing all active connections and re-reading the configuration file. .SH "CONFIGURATION" The configuration language is a list of keyword and value pairs. Each keyword is followed by an '=' and then the desired value. .PP Recognized keywords include: .sp .\" .IP "cache-size (cardinal)" .\" Size in bytes of the font server cache. .IP "catalogue (list of string)" Ordered list of font path element names. Use of the keyword "catalogue" is very misleading at present, the current implementation only supports a single catalogue ("all"), containing all of the specified fonts. .IP "alternate-servers (list of string)" List of alternate servers for this font server. .IP "client-limit (cardinal)" Number of clients this font server will support before refusing service. This is useful for tuning the load on each individual font server. .IP "clone-self (boolean)" Whether this font server should attempt to clone itself when it reachs the client-limit. .IP "default-point-size (cardinal)" The default pointsize (in decipoints) for fonts that don't specify. The default is 120. .IP "default-resolutions (list of resolutions)" Resolutions the server supports by default. This information may be used as a hint for pre-rendering, and substituted for scaled fonts which do not specify a resolution. A resolution is a comma-separated pair of x and y resolutions in pixels per inch. Multiple resolutions are separated by commas. .IP "error-file (string)" Filename of the error file. All warnings and errors will be logged here. .IP "port (cardinal)" TCP port on which the server will listen for connections. .IP "use-syslog (boolean)" Whether syslog(3) (on supported systems) is to be used for errors. .IP "deferglyphs (string)" Set the mode for delayed fetching and caching of glyphs. Value is "none", meaning deferred glyphs is disabled, "all", meaning it is enabled for all fonts, and "16", meaning it is enabled only for 16-bits fonts. .\" .IP "trusted-clients (list of string)" .\" Those clients the fontserver will talk to. Others .\" will be refused for the initial connection. An empty .\" list means the server will talk to any client. .SH "EXAMPLE" .nf # # sample font server configuration file # # allow a max of 10 clients to connect to this font server client-limit = 10 # when a font server reaches its limit, start up a new one clone-self = on # alternate font servers for clients to use alternate-servers = hansen:7101,hansen:7102 # where to look for fonts # the first is a set of Speedo outlines, the second is a set of # misc bitmaps and the last is a set of 100dpi bitmaps # catalogue = /usr/X11R6/lib/X11/fonts/speedo, /usr/X11R6/lib/X11/fonts/misc, /usr/X11R6/lib/X11/fonts/100dpi/ # in 12 points, decipoints default-point-size = 120 # 100 x 100 and 75 x 75 default-resolutions = 100,100,75,75 use-syslog = off .fi .sp .SH "FONT SERVER NAMES" One of the following forms can be used to name a font server that accepts TCP connections: .sp .nf tcp/\fIhostname\fP:\fIport\fP tcp/\fIhostname\fP:\fIport\fP/\fIcataloguelist\fP .fi .PP The \fIhostname\fP specifies the name (or decimal numeric address) of the machine on which the font server is running. The \fIport\fP is the decimal TCP port on which the font server is listening for connections. The \fIcataloguelist\fP specifies a list of catalogue names, with '+' as a separator. .PP Examples: \fItcp/fs.x.org:7100\fP, \fItcp/18.30.0.212:7101/all\fP. .PP One of the following forms can be used to name a font server that accepts DECnet connections: .sp .nf decnet/\fInodename\fP::font$\fIobjname\fP decnet/\fInodename\fP::font$\fIobjname\fP/\fIcataloguelist\fP .fi .PP The \fInodename\fP specifies the name (or decimal numeric address) of the machine on which the font server is running. The \fIobjname\fP is a normal, case-insensitive DECnet object name. The \fIcataloguelist\fP specifies a list of catalogue names, with '+' as a separator. .PP Examples: \fIDECnet/SRVNOD::FONT$DEFAULT\fP, \fIdecnet/44.70::font$special/symbols\fP. .SH "SEE ALSO" X(1), \fIThe X Font Service Protocol\fP, .br \fIFont server implementation overview\fP .SH BUGS Multiple catalogues should be supported. .SH AUTHORS Dave Lemke, Network Computing Devices, Inc .br Keith Packard, Massachusetts Institute of Technology .TH XHOST 1 "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .SH NAME xhost - server access control program for X .SH SYNOPSIS .B xhost [[+-]name ...] .SH DESCRIPTION The \fIxhost\fP program is used to add and delete host names or user names (in case of Secure RPC ) to the list allowed to make connections to the X server. In the case of hosts, this provides a rudimentary form of privacy control and security. It is only sufficient for a workstation (single user) environment, although it does limit the worst abuses. Environments which require more sophisticated measures should implement the user-based mechanism, or use the hooks in the protocol for passing other authentication data to the server. .PP Hostnames that are followed by two colons (::) are used in checking DECnet connections; all other hostnames are used for TCP/IP connections. .PP User names contain an at-sign (@). When Secure RPC is being used, the network independent netname (e.g., "unix.\fIuid\fP@\fIdomainname\fP") can be specified, or a local user can be specified with just the username and a trailing at-sign (e.g., "joe@"). .SH OPTIONS \fIXhost\fP accepts the following command line options described below. For security, the options that effect access control may only be run from the "controlling host". For workstations, this is the same machine as the server. For X terminals, it is the login host. .TP 8 .BI "\[\+\]" "name" The given \fIname\fP (the plus sign is optional) is added to the list allowed to connect to the X server. The name can be a host name or a user name. .TP 8 .BI \- "name" The given \fIname\fP is removed from the list of allowed to connect to the server. The name can be a host name or a user name. Existing connections are not broken, but new connection attempts will be denied. Note that the current machine is allowed to be removed; however, further connections (including attempts to add it back) will not be permitted. Resetting the server (thereby breaking all connections) is the only way to allow local connections again. .TP 8 .B \+ Access is granted to everyone, even if they aren't on the list (i.e., access control is turned off). .TP 8 .B \- Access is restricted to only those on the list (i.e., access control is turned on). .TP 8 .I nothing If no command line arguments are given, a message indicating whether or not access control is currently enabled is printed, followed by the list of those allowed to connect. This is the only option that may be used from machines other than the controlling host. .SH DIAGNOSTICS For each name added to the access control list, a line of the form "\fIname\fP being added to access contro list" is printed. For each name removed from the access control list, a line of the form "\fIname\fP being removed from access contro list" is printed. .SH FILES /etc/X*.hosts .SH "SEE ALSO" X(1), Xserver(1) .SH ENVIRONMENT .TP 8 .B DISPLAY to get the default host and display to use. .SH BUGS .PP You can't specify a display on the command line because .B \-display is a valid command line argument (indicating that you want to remove the machine named .I ``display'' from the access list). .PP This is not really a bug, but the X server stores network addresses, not host names. If somehow you change a host's network address while the server is still running, \fIxhost\fP must be used to add the new address and/or remove the old address. .SH COPYRIGHT Copyright 1988, Massachusetts Institute of Technology. .br See \fIX(1)\fP for a full statement of rights and permissions. .SH AUTHORS Bob Scheifler, MIT Laboratory for Computer Science, .br Jim Gettys, MIT Project Athena (DEC). .TH XHPCALC 1 .ad b .SH NAME xhpcalc - Hewlett-Packard type calculator emulator .SH SYNOPSIS xhpcalc .SH DESCRIPTION .I xhpcalc emulates the .B Hewlett-Packard Type of programmable scientific calculators, including the Scientific, Financial and Programming calculators. You operate the calculator by clicking the left mouse key (button 1) on the on-screen calculator buttons. Some basic calculator buttons are also accessible via the keyboard, such as the digits [0] - [9], [+], [-], [*], [Backspace], etc. All the keys on the keyboard's numeric keypad work correctly. Results appear in the calculator's display at the top. The calculator supports "continuous memory", which means that the contents of registers and program memory is saved whenever you turn off the calculator (close the window), and restored whenever you restart it. The calculator also remembers which mode (eg. SCI, FIN or PRO) it was last in, and starts in that mode by default. To change the mode of .I xhpcalc move the mouse pointer onto the HP logo in the upper right corner of the calculator and click any of the mouse keys. .SH OPTIONS .TP 15 .B -grey or gray Does not use any colors (monochrome) .TP .B -mono Same operation as .I -grey .TP .B -monochrome Same operation as .I -grey .TP .B -reverseVideo Reverses the colors (monochrome only) of .I xhpcalc .TP .B -rv Same operation as .I -reverseVideo .TP .B -reverse Same operation as .I -reverseVideo .TP .B -help Prints out the LONG version of options. Any illegal option causes a SHORT version of options to be printed. .TP .BI -display " " Sets display on which the calculator is to be displayed (see X manual page for more information). .TP .B -debug Program developers mode. Causes dump (on stderr) of .I xhpcalc internal registers when the mouse button is depressed in the .I xhpcalc display window. Left Mouse button gives normal registers, right mouse button gives storage registers. .TP .B -radix Interchanges the period "." character with a comma "," for European style numbers. .TP .B -comma Causes the display to not display the "," in any of the numbers. .TP .B -iconify Forces .I xhpcalc to come up in icon form. .TP .B -iconic Same operation as .I -iconify .TP .BI -file " " This allows starting the calculator's continuous memory from a file other that the normal "saved at last exit" continuous memory file. This is most useful to load a favorite program stored in a different file, with no danger of overwriting or destroying it. Upon exit, the continuous memory file is still saved in .I $HOME/.xhpcalc. .TP .B -startupFile " " Same as .B -file above. .TP .BI -shiftMode " " Sets the way in which the "f" and "g" keys should be used. This is an alternate way of specifying the shift mode instead of using one of the explicit modes itemized below. .I mode can be one of "noShift", "fgShift", "allShift" which are described individually below. .br (Default = -shiftMode fgShift) .TP .B -noShift Allows keystrokes to be pressed with the mouse directly. You do not need to use the "f" and "g" keys at all, and in fact using them produces no useful effect. .TP .B -fgShift Allows keystrokes to be pressed with the mouse directly. If you do use the "f" or "g" function keys then any key of the triplet produces ONLY that "f" or "g" key corresponding to the triplet. (This is the most useful mode) .br (default = -fgshift) .TP .B -allShift Causes the key triplet to ONLY generate the center key on a press of any of the triplet, and to ONLY generate the "f" or "g" key on a press of the triplet after a function key entry. (This is useful if you tend to miss with your aim a lot) .TP .BI -geometry " " Locates .I xhpcalc on the screen. Sizing parameters are used if specified, but usually do not produce a good result. For example, .br xhpcalc -geometry -0-0 .br puts the calculator window in the lower right corner. .TP .BI -iconGeometry " " Locates the icon for the window in the desired location. (This is passed as a hint to the window manager which does with it as it pleases.) The size specification is usually ignored by the window manager. .TP .BI -startAs " " This sets the initial startup of the calculator to be the type indicated. .br (Choices = SCI FIN PRO) .br (Default = SCI) .TP .BI -calcTypes " " The list of calculator types which you want access to. If you don't include the calculator type in this list it won't be available to you to use. .br (Choices = SCI FIN PRO) .br (Default = "SCI FIN PRO") .TP .B -SCI Deletes .I xhpcalc type SCI from the available list. .TP .B -FIN Deletes .I xhpcalc type FIN from the available list. .TP .B -PRO Deletes .I xhpcalc type PRO from the available list. .TP .B " " (WARNING: don't delete all .I xhpcalc types) .SH OPERATION Any mouse button can be used in .I xhpcalc to press keys. They all have the same effect. To cause .I xhpcalc to turn into an icon press the "ON" key. (If you are using the default .B mwm window manager, then you can restore the .I xhpcalc icon to its normal appearance by double-clicking on the icon. The behavior of other window managers may differ.) To turn .I xhpcalc off press CTRL-C or CTRL-D on the computer keyboard. This causes .I xhpcalc to update its continuous memory file and die. If you are using the .B mwm window manager, you can also double-click on the `Window Menu' button on the upper left corner of the window frame. .sp There are NO keys on .I xhpcalc that causes .I xhpcalc to exit. However, the window manager close action (i.e. double-click on the Window Menu button in mwm) causes .I xhpcalc to exit. .SH USING THE KEYBOARD If you wish to use the numeric keypad for numeric entry, the digit keys [0] through [9] act like numbers, [Tab] and [Return] act like [ENTER], and [,] (comma) and [Backspace] act like [<--], which is the calculator backspace key. The keys [*], [/], [+], [-] do the expected math functions. The keyboard keys are user-definable. See the Keyboard Equivalents subheading in the .B X RESOURCES section, below. By default the keys on the computer keyboard that have operational functions are: .TP 22 .B 0-9 Numeric keys .TP .B A-F a-f Numeric keys for the PRO emulator .TP .B A-F a-f Function keys for the SCI emulator .TP .B . Decimal Point .TP .B n Negate (Change Sign - CHS) .TP .B ^ EEX (Begin entering exponent) .TP .B CTRL-C, CTRL-D Quit .TP .B DEL, CTRL-H BKSP Back Space [<--] .TP .B , Back Space [<--] .TP .B CTRL-M (CR) ENTER .TP .B CTRL-J (LF) ENTER .TP .B CTRL-I (TAB) ENTER .SH PROGRAMMING .I xhpcalc shares the program between all the emulated types. For example, when you change calculator personalities from SCI to PRO, the program you entered on the SCI is now in the PRO. The display of the program is in English instead of number pairs, so that the different types of calculator functions may be mixed without confusion. You can freely mix the keystrokes from the different calculators in program memory, and all will work correctly remembering that the PRO emulator uses a TOTALLY separate set of registers for its INTEGER mode calculations, and these can not in any way be reached from the FLOAT mode calculators. .in +.5i NOTE: The integer storage registers and integer stack registers of the PRO are .I not the same as those for other models. You should not intermix operations in programs, but nothing stops you from doing so. .in -.5i The "LOGO" (change of .I xhpcalc identity) is NOT programmable. There are always 999 program steps available to the programmer, and registers 0 through .9 are always available. These do not trade off as do some real calculators. Because of the nasty effects of accidentally purging a program from memory, the "CLR-PRG" key actually clears program memory ONLY if you are in PROG mode (ie. programming). Striking the "CLR-PRG" key at any other time results in no action taken. .br If you develop a favorite program you may want to exit from .I xhpcalc (using CTRL-C, CTRL-D, or closing the window with the mwm Window Menu button) and move or copy the file $HOME/.xhpcalc to a file of another name. Whenever you want .I xhpcalc to start up with this program in memory use the .I -startupFile option which causes .I xhpcalc to restore its continuous memory from that file instead of the default file "$HOME/.xhpcalc". The only file updated with current status on exit is "$HOME/.xhpcalc" thereby preserving your developed program. You can then add comments to the saved file using an editor. An alternate way of dumping current status to the $HOME/.xhpcalc file is to use the "g"-"ON" sequence. This makes an immediate dump to the file without quitting. .SH CONTINUOUS MEMORY Continuous memory attempts to preserve itself when .I xhpcalc terminates. If the file, "$HOME/.xhpcalc" exists when .I xhpcalc is started, that file is used as continuous memory. "$HOME/.xhpcalc" is written to (by default) when the .I xhpcalc receives a CTRL-D, CTRL-C or various "kill" signals. Use "f"-"ON" to totally reset .I xhpcalc, causing the continuous memory to be ignored and resetting all registers and program memory to power-on conditions. This won't work if "-shiftMode noShift" is set. The converse is "g"-"ON" which saves continuous memory into the "$HOME/.xhpcalc" file. If you want to start up from a different continuous memory file use the .I -startupFile option on the command line. This file is read instead of the "$HOME/.xhpcalc" file. The "$HOME/.xhpcalc" file is still updated on program exit. The format of the continuous memory file is ASCII. This makes for a larger file, but permits portability, user modifications and programming. Any continuous memory file entry that starts with "#=" is treated as a comment when the file is read. Comments do NOT survive when the continuous memory file is updated at program exit, so they are useful only with the .I -startupFile option. The "?" in the line containing "PROGRAM=" may be treated as a comment and be set to whatever you desire (i.e. name the program). .SH COLOR USAGE .I xhpcalc uses many colors (8 or 9 by default) unless you specify .I -grey or .I -monochrome or have a monochrome display. .I xhpcalc shares colors with other programs whenever possible. .SH WINDOW SIZING .I xhpcalc is sized based on the sizes of the fonts requested for the keys and the display. Although you can modify the size of .I xhpcalc with window manager commands, the result will be a strange looking calculator. .SH CUT & PASTE .I xhpcalc allows you to .I cut out the contents of the calculator display and .I paste the contents into other windows which support cut and paste, such as .B hpterm(1). .sp To cut the contents of the display, press [Shift] then the center mouse key. To paste information into .I xhpcalc, press [Shift] then the right mouse key. .sp Refer to the manual entry for .B hpterm(1) for more information about using cut and paste with .I hpterm. .SH X RESOURCES This section describes the resources which can be used to customize the appearance and behavior of .I xhpcalc via the user's .I .Xdefaults file. If you are using the Visual User Environment (VUE), then see also the .B VUE CUSTOMIZATION section, below. The syntax for all .I xhpcalc resources is .br XHpcalc.: .br For example, .br XHpcalc.calcTypes:SCI .br If is left blank, "True" is assumed. For example, .br XHpcalc.comma: .br is equivalent to .br XHpcalc.comma:True .br .SS General Resources The resources below affect the overall appearance and behavior of .I xhpcalc. .TP 15 .B calcTypes: Lists calculator types which you want access to. If you don't include the calculator type in this list, it won't be available for you to use. If a is unspecified, the last "calcType" in .xhpcalc is assumed. .br (Default = "SCI FIN PRO"); .TP .B display: Sets the display on which the calculator is to be shown. .br (Default: $DISPLAY from environment, or "local:0.0") .TP .B debug: Program developers mode. Causes dump of .I xhpcalc internal registers when the mouse button is depressed in the .I xhpcalc display window. Left Mouse button gives normal registers, right mouse button gives storage registers. .br (Default: False) .TP .B geometry: Locates .I xhpcalc on the screen. Sizing parameters are used if specified, but usually do not produce a good result. .br (Default: NULL) .TP .B iconGeometry: Locates the icon for the window in the desired location. The size specification is usually ignored by the window manager. .br (Default: NULL) .TP .B iconify: Causes the calculator to come up in iconic form. .br (Default: False) .TP .B startupFile: Allows starting the calculator continuous memory from a file other than "$HOME/.xhpcalc". This is most useful to load a favorite program stored in a different file, with no danger of overwriting or destroying it. The eventual continuous memory file written is still the $HOME/.xhpcalc file. If a is unspecified, then .I xhpcalc starts with a clean memory (equivalent to keys "f"-"ON"). .br (Default = NULL). .TP .B continuousFile: This is the file to which the continuous memory is written on calculator exit. If a is unspecified, then continuous memory is thrown away. .br (Default = $HOME/.xhpcalc) .TP .B comma: Causes the display to not display the "," in any of the numbers. .br (Default: False) .TP .B radix: Interchanges the period "." character for a comma "," for European style numbers. .br (Default: False) .TP .B Delay: Sets the length of time that a calculator button should be inverse videoed (depressed). Expressed in milliseconds (1/1000 of a second). .br (Default = 50) .TP .B buttonDelay: Sets the length of time that a calculator button should be inverse videoed (depressed), but only when pressed with a mouse button. This overrides the Delay: option described above. Expressed in milliseconds (1/1000 of a second). .br (Default = set with Delay:) .TP .B keyDelay: Sets the length of time that a calculator button should be inverse videoed (depressed), but only when pressed with a keyboard key. This overrides the Delay: option described above. Expressed in milliseconds (1/1000 of a second). .br (Default = set with Delay:) .TP .B shiftMode: Sets the way in which the "f" and "g" keys should be used. This is an alternate way of specifying the shift mode instead of using one of the explicit modes itemized below. .I mode can be one of "noShift", "fgShift", "allShift", which are described below. If a is unspecified, then "noShift" is assumed. .br (Default = -shiftMode fgShift) .SS Cut and Paste These resources affect .I xhpcalc's cut and paste capability. .TP .B cutButton: Defines which mouse/keyboard keys need to be combined to cut the calculator display into the X11 cut buffer. .br Acceptable arguments are "Left" "Right" "Center" "Shift" "Meta" "Control" and may be separated either with spaces " " or pipe symbols "|". .br (Default = Left Shift) .TP .B cutBase: Defines how the base indicator (PRO calculator) is included in the cut buffer. .br .I adjacent places the "h", "d", "o" or "b" immediately against the number. .br .I separated places the "h", "d", "o" or "b" one blank away from the number. .br .I none places no indication of base in the cut buffer. .br (Default = Adjacent) .TP .B cutDigits: Defines how the digits are cut from the calculator display. .br .I all places all significant digits (held internally) in the cut buffer. .br .I showing places only what you see in the cut buffer. .br (Default = Showing) .TP .B pasteButton: Defines which mouse/keyboard keys need to be combined to paste the X11 cut buffer onto the calculator keyboard. .br NOTE: The paste buffer has the characters defined in the resource "ignorePaste" removed from it before being pasted on the keyboard. .br Acceptable arguments are "Left" "Right" "Center" "Shift" "Meta" "Control" and may be separated either with spaces " " or pipe symbols "|". .br (Default = Right Shift) .TP .B pasteIgnore: Defines which characters are removed from the X cut/paste buffer before the characters are placed on the calculator keyboard stack. This allows removing things such as "$" and "," from the input string. The resulting string is then interpreted in accordance with the .I key defaults described below. .br (Default = ", $\t") .TP .B pasteAccept: Defines which characters are accepted from the X cut/paste buffer and placed on the calculator keyboard stack. If this is not defined then all characters are accepted, except those specified in .I pasteIgnore. If a is unspecified, then nothing is accepted. .br (Default = NULL) .SS Keyboard Equivalents These resources are used to configure the mapping of keyboard keys to various .I xhpcalc buttons. .TP .B key: Defines the default generic mapping of keyboard keys to calculator function keys. The syntax is = separated with blanks or tabs. NOTE: keycodes less than space " " should be represented in octal. Because of the way X11 parses the line it is necessary to use a double backslash "\\\\" to represent a single backslash to the calculator, which causes the calculator to interpret the number following as an octal representation of the desired character. .br .I key is used to set the defaults for all calculator types. You may use .I keyALL to add to this set of defaults, or may redefine .I key to completely change the initial set of defaults. You may also set the key mapping for JUST a single calculator by setting the keycode mapping for that calculator using the defaults described below. .br (Default = XHpcalc.key: 0=0 1=1 2=2 3=3 4=4 5=5 6=6 7=7 8=8 9=9 a=Afun A=Afun b=Bfun B=Bfun c=Cfun C=Cfun d=Dfun D=Dfun e=Efun E=Efun f=Ffun F=Ffun n=CHS ^=EEX \\004=OFF \\003=OFF ,=BKSP \\177=BKSP \\010=BKSP \\015=ENTER \\012=ENTER \\011=ENTER +=+ -=- *=* /=/ .=. M=mem N=IGNORE) .TP .B keyALL : Allows adding to the set of built in key_stroke to key_code mappings that the calculator starts with by default. .br (Default = NULL) .TP .B keySCI: Specific mapping of keyboard keys to calculator function keys, and is added to the definition of "XHpcalc.key:", but only for the SCI type calculator. The same syntax and choices are available. .br (Default = NULL) .TP .B keyFIN: Specific mapping of keyboard keys to calculator function keys, and is added to the definition of "XHpcalc.key:", but only for the FIN type calculator. The same syntax and choices are available. .br (Default = NULL) .TP .B keyPRO: Specific mapping of keyboard keys to calculator function keys, and is added to the definition of "XHpcalc.key:", but only for the PRO type calculator. The same syntax and choices are available. .br (Default = XHpcalc.keyPRO: a=A A=A b=B B=B c=C C=C d=D D=D e=E E=E f=F F=F) .SS General Calculator Body The resources below affect the body and overall appearance of the calculator. .TP .B reverseVideo: Reverses the colors of a Monochrome display. Not useful when using full Color. .TP .B grey: on/off .br .TP .B fore: (Default = Black) .TP .B back: (Default = DarkSlateGrey) .TP .B bord: (Default = Black) .br .SS "Normal" keys The resources below affect the "normal" part of the calculator keys, which is in the center of the calculator button. .TP .B PKeyFore: (Default = White) .TP .B PKeyBack: (Default = Black) .TP .B PKeyBord: (Default = Black) .TP .B PFont: (Default = hp8.6x8) .br .SS The "f" and "g" Keys The resources below affect the shifted "f" and "g" portions of the calculator keys, which is the top and bottom third of each button respectively. .TP .B FKeyFore: (Default = Gold) .TP .B FKeyBack: (Default = DarkSlateGrey) .TP .B FKeyBord: (Default = DarkSlateGrey) .TP .B FFont: (Default = hp8.6x8) .TP .B GKeyFore: (Default = #0B0) .TP .B GKeyBack: (Default = DarkSlateGrey) .TP .B GKeyBord: (Default = Black) .TP .B GFont: (Default = hp8.6x8) .br .SS Calculator Display These resources affect the calculator's display window. .TP .B DispFore: (Default = Yellow) .TP .B DispBack: (Default = #777) .TP .B DispBord: (Default = Black) .TP .B DFont: (Default = hp8.12x15) .br .SH VUE CUSTOMIZATION If you are using the Visual User Environment (VUE) then you must let VUE know when you make changes to your .I .Xdefaults file. In order for your changes to take effect, run: xrdb -nocpp -merge $HOME/.Xdefaults VUE automatically saves your new defaults in the file .I $HOME/.vue/$DISPLAY/current/vue.resources. You can also edit the vue.resources file directly. If you do so, and want to store your changes for the next time you login, then run: xrdb -load $HOME/.vue.$DISPLAY.current/vue.resources .B Background Information for the X-Knowledgeable Reader The X Resource Data Base (xrdb) allows users to customize the look and behavior of their applications. The advantage of using xrdb becomes apparent in a distributed environment where a program may be running on one machine and displaying output on another machine. This allows users to specify different defaults for the different systems they use. The xrdb is kept on the server side (the display side), not on the client side (where the program is running). Therefore, at run time the program can check to see what kind of display it is displaying to. You can use any file (not just .I .Xdefaults ) to specify customizations, and then run: xrdb -nocpp -merge But this is not recommended, because some clients do not use xrdb. Any additions or changes of defaults should be made to both .I .Xdefaults and the xrdb files. .SH TIDBITS OF MISCELLANEOUS KNOWLEDGE Sending a SIGPWD (powerfail signal) to .I xhpcalc causes the emulator to display the LOW BATTERY ("*") prompt in the display. But this does not show in the display until the next time the display is redrawn. To find out the revision of .I xhpcalc you are using click any mouse button in the calculator display window. .SH "CAVEATS" .I xhpcalc results are sometimes different from actual calculators. This is usually due to more precise answers and more significant digits in .I xhpcalc. but is sometimes due to the representation of the numbers in IEEE (binary) format. The emulator does not trade register locations for program locations. Program locations are 0 through 999 Register locations are 0 through .9 from the keyboard, and 0 through 100 for indirect reference. This does not match real calculators which tend to trade registers for program locations. The PRO registers in INTEGER mode are not accessible from the PRO FLOAT mode. The INTEGER registers are solely accessible from the PRO mode and only when in INTEGER mode. .I xhpcalc is not re-sizable, but sizes itself based on the fonts used for the keys and display. .\" $XConsortium: xlsfonts.man /main/20 1995/12/15 14:04:44 gildea $ .\" Copyright (c) 1988 X Consortium .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the .\" "Software"), to deal in the Software without restriction, including .\" without limitation the rights to use, copy, modify, merge, publish, .\" distribute, sublicense, and/or sell copies of the Software, and to .\" permit persons to whom the Software is furnished to do so, subject to .\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included .\" in all copies or substantial portions of the Software. .\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR .\" OTHER DEALINGS IN THE SOFTWARE. .\" .\" Except as contained in this notice, the name of the X Consortium shall .\" not be used in advertising or otherwise to promote the sale, use or .\" other dealings in this Software without prior written authorization .\" from the X Consortium. .TH XLSFONTS 1 "Release 6.1" "X Version 11" .SH NAME xlsfonts \- server font list displayer for X .SH SYNOPSIS .B xlsfonts [\-options ...] [\-fn pattern] .SH DESCRIPTION .I Xlsfonts lists the fonts that match the given \fIpattern\fP. The wildcard character "*" may be used to match any sequence of characters (including none), and "?" to match any single character. If no pattern is given, "*" is assumed. .PP The "*" and "?" characters must be quoted to prevent them from being expanded by the shell. .SH "OPTIONS" .PP .TP 8 .B \-display \fIhost\fP:\fIdpy\fP This option specifies the X server to contact. .PP .TP 8 .B \-l Lists some attributes of the font on one line in addition to its name. .TP 8 .B \-ll Lists font properties in addition to \fB\-l\fP output. .TP 8 .B \-lll Lists character metrics in addition to \fB\-ll\fP output. .TP 8 .B \-m This option indicates that long listings should also print the minimum and maximum bounds of each font. .TP 8 .B \-C This option indicates that listings should use multiple columns. This is the same as \fB\-n 0\fP. .TP 8 .B \-1 This option indicates that listings should use a single column. This is the same as \fB\-n 1\fP. .TP 8 .B \-w \fIwidth\fP This option specifies the width in characters that should be used in figuring out how many columns to print. The default is 79. .TP 8 .B \-n \fIcolumns\fP This option specifies the number of columns to use in displaying the output. By default, it will attempt to fit as many columns of font names into the number of character specified by \fB\-w \fIwidth\fR. .TP 8 .B \-u This option indicates that the output should be left unsorted. .TP 8 .B \-o This option indicates that \fIxlsfonts\fP should do an \fBOpenFont\fP (and \fBQueryFont\fP, if appropriate) rather than a \fBListFonts\fP. This is useful if \fBListFonts\fP or \fBListFontsWithInfo\fP fail to list a known font (as is the case with some scaled font systems). .TP 8 .B \-fn \fIpattern\fP This option specifies the font name pattern to match. .PP .SH "SEE ALSO" X(1), Xserver(1), xset(1), xfd(1), .I "X Logical Font Description Conventions" .SH ENVIRONMENT .TP 8 .B DISPLAY to get the default host and display to use. .SH BUGS Doing ``xlsfonts -l'' can tie up your server for a very long time. This is really a bug with single-threaded non-preemptable servers, not with this program. .SH AUTHOR Mark Lillibridge, MIT Project Athena; Jim Fulton, MIT X Consortium; Phil Karlton, SGI ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH xmbind 1X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIxmbind\fP \- Configures virtual key bindings .SH SYNOPSIS .nf .sS \fIxmbind\fP [\fBoptions\fP] [\fBfile\fP] .sE .SH DESCRIPTION .fi \fIxmbind\fP is an X Window System client that configures the virtual key bindings for Motif applications. This action is performed by \fImwm\fP at its startup, so the \fIxmbind\fP client is only needed when \fImwm\fP is not in use, or when you want to change bindings without restarting \fImwm\fP. If a file is specified, it's contents are used as the virtual key bindings. If a file is not specified, the file \fI\&.motifbind\fP in the user's home directory is used. If this file is not found, \fIxmbind\fP loads the default virtual key bindings, as described in \fIVirtualBindings(3X)\fP. .SS Options .IP "\fI\-display\fP" This option specifies the display to use; see X(1). .SH RELATED INFORMATION .na \fIVirtualBindings(3X)\fP and \fIX(1X)\fP. .ad .de EX \"Begin example .ne 5 .if n .sp 1 .if t .sp .5 .nf .in +.5i .. .de EE .fi .in -.5i .if n .sp 1 .if t .sp .5 .. .TH XMODMAP 1 "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .SH NAME xmodmap - utility for modifying keymaps in X .SH SYNOPSIS .B xmodmap [-options ...] [filename] .SH DESCRIPTION .PP The \fIxmodmap\fP program is used to edit and display the keyboard \fImodifier map\fP and \fIkeymap table\fP that are used by client applications to convert event keycodes into keysyms. It is usually run from the user's session startup script to configure the keyboard according to personal tastes. .SH OPTIONS .PP The following options may be used with \fIxmodmap\fP: .TP 8 .B \-display \fIdisplay\fP This option specifies the host and display to use. .TP 8 .B \-help This option indicates that a brief description of the command line arguments should be printed on the standard error channel. This will be done whenever an unhandled argument is given to .I xmodmap. .TP 8 .B \-grammar This option indicates that a help message describing the expression grammar used in files and with -e expressions should be printed on the standard error. .TP 8 .B \-verbose This option indicates that .I xmodmap should print logging information as it parses its input. .TP 8 .B \-quiet This option turns off the verbose logging. This is the default. .TP 8 .B \-n This option indicates that .I xmodmap should not change the mappings, but should display what it would do, like \fImake(1)\fP does when given this option. .TP 8 .B \-e \fIexpression\fB This option specifies an expression to be executed. Any number of expressions may be specified from the command line. .TP 8 .B \-pm This option indicates that the current modifier map should be printed on the standard output. .TP 8 .B \-pk This option indicates that the current keymap table should be printed on the standard output. .TP 8 .B \-pke This option indicates that the current keymap table should be printed on the standard output in the form of expressions that can be fed back to \fIxmodmap\fP. .TP 8 .B \-pp This option indicates that the current pointer map should be printed on the standard output. .TP 8 .B \- A lone dash means that the standard input should be used as the input file. .PP The \fIfilename\fP specifies a file containing \fIxmodmap\fP expressions to be executed. This file is usually kept in the user's home directory with a name like \fI.xmodmaprc\fP. .SH EXPRESSION GRAMMAR .PP The .I xmodmap program reads a list of expressions and parses them all before attempting to execute any of them. This makes it possible to refer to keysyms that are being redefined in a natural way without having to worry as much about name conflicts. .TP 8 .B keycode \fINUMBER\fP = \fIKEYSYMNAME ...\fP The list of keysyms is assigned to the indicated keycode (which may be specified in decimal, hex or octal). The first keysym in the list is assigned to the keycode when no modifier key is used with the key, the second when the shift modifier key is used, the third when mod1 is used and the fourth when both shift and mod1 are used with the key (the standard translation makes use of only the first four keysyms in the list). .TP 8 .B keycode any = \fIKEYSYMNAME ...\fP If no existing key has the specified list of keysyms assigned to it, a spare key on the keyboard is selected and the keysyms are assigned to it. The list of keysyms may be specified in decimal, hex or octal. .TP 8 .B keysym \fIKEYSYMNAME\fP = \fIKEYSYMNAME ...\fP The \fIKEYSYMNAME\fP on the left hand side is translated into matching keycodes and used to perform the corresponding set of \fBkeycode\fP expressions. The list of keysym names may be found in the header file \fI\fP (without the \fIXK_\fP prefix) or the keysym database \fI/usr/lib/X11/XKeysymDB\fP. Note that if the same keysym is bound to multiple keys, the expression is executed for each matching keycode. .TP 8 .B clear \fIMODIFIERNAME\fP This removes all entries in the modifier map for the given modifier, where valid name are: .BR Shift , .BR Lock , .BR Control , .BR Mod1 , .BR Mod2 , .BR Mod3 , .BR Mod4 , and \fBMod5\fP (case does not matter in modifier names, although it does matter for all other names). For example, ``clear Lock'' will remove all any keys that were bound to the shift lock modifier. .TP 8 .B add \fIMODIFIERNAME\fP = \fIKEYSYMNAME ...\fP This adds all keys containing the given keysyms to the indicated modifier map. The keysym names are evaluated after all input expressions are read to make it easy to write expressions to swap keys (see the EXAMPLES section). .TP 8 .B remove \fIMODIFIERNAME\fP = \fIKEYSYMNAME ...\fP This removes all keys containing the given keysyms from the indicated modifier map. Unlike .B add, the keysym names are evaluated as the line is read in. This allows you to remove keys from a modifier without having to worry about whether or not they have been reassigned. .TP 8 .B "pointer = default" This sets the pointer map back to its default settings (button 1 generates a code of 1, button 2 generates a 2, etc.). .TP 8 .B pointer = \fINUMBER ...\fP This sets to pointer map to contain the indicated button codes. The list always starts with the first physical button. .PP Lines that begin with an exclamation point (!) are taken as comments. .PP If you want to change the binding of a modifier key, you must also remove it from the appropriate modifier map. .SH EXAMPLES .PP Many pointers are designed such that the first button is pressed using the index finger of the right hand. People who are left-handed frequently find that it is more comfortable to reverse the button codes that get generated so that the primary button is pressed using the index finger of the left hand. This could be done on a 3 button pointer as follows: .EX % xmodmap -e "pointer = 3 2 1" .EE .PP Many editor applications support the notion of Meta keys (similar to Control keys except that Meta is held down instead of Control). However, some servers do not have a Meta keysym in the default keymap table, so one needs to be added by hand. The following command will attach Meta to the Select key. It also takes advantage of the fact that applications that need a Meta key simply need to get the keycode and don't require the keysym to be in the first column of the keymap table. This means that applications that are looking for a Multi_key (including the default modifier map) won't notice any change. .EX % xmodmap -e "keysym Select = Select Meta_L" .EE .PP One of the more simple, yet convenient, uses of \fIxmodmap\fP is to set the keyboard's "rubout" key to generate an alternate keysym. This frequently involves exchanging Backspace with Delete to be more comfortable to the user. If the \fIttyModes\fP resource in \fIxterm\fP is set as well, all terminal emulator windows will use the same key for erasing characters: .EX % xmodmap -e "keysym BackSpace = Delete" % echo "XTerm*ttyModes: erase ^?" | xrdb -merge .EE .PP Some keyboards do not automatically generate less than and greater than characters when the comma and period keys are shifted. This can be remedied with \fIxmodmap\fP by resetting the bindings for the comma and period with the following scripts: .EX ! ! make shift-, be < and shift-. be > ! keysym comma = comma less keysym period = period greater .EE .PP One of the more irritating differences between keyboards is the location of the Control and Shift Lock keys. A common use of \fIxmodmap\fP is to swap these two keys as follows: .EX ! ! Swap Caps_Lock and Control_L ! remove Lock = Caps_Lock remove Control = Control_L keysym Control_L = Caps_Lock keysym Caps_Lock = Control_L add Lock = Caps_Lock add Control = Control_L .EE .PP The \fIkeycode\fP command is useful for assigning the same keysym to multiple keycodes. Although unportable, it also makes it possible to write scripts that can reset the keyboard to a known state. The following script sets the backspace key to generate Delete (as shown above), flushes all existing caps lock bindings, makes the CapsLock key be a control key, make F5 generate Escape, and makes Break/Reset be a shift lock. .EX ! ! On the HP, the following keycodes have key caps as listed: ! ! 101 Backspace ! 55 Caps ! 14 Ctrl ! 15 Break/Reset ! 86 Stop ! 89 F5 ! keycode 101 = Delete keycode 55 = Control_R clear Lock add Control = Control_R keycode 89 = Escape keycode 15 = Caps_Lock add Lock = Caps_Lock .EE .SH ENVIRONMENT .PP .TP 8 .B DISPLAY to get default host and display number. .SH SEE ALSO X(1), \fIXlib\fP documentation on key and pointer events .SH BUGS .PP Every time a \fBkeycode\fP expression is evaluated, the server generates a \fIMappingNotify\fP event on every client. This can cause some thrashing. All of the changes should be batched together and done at once. Clients that receive keyboard input and ignore \fIMappingNotify\fP events will not notice any changes made to keyboard mappings. .PP .I Xmodmap should generate "add" and "remove" expressions automatically whenever a keycode that is already bound to a modifier is changed. .PP There should be a way to have the .I remove expression accept keycodes as well as keysyms for those times when you really mess up your mappings. .SH COPYRIGHT Copyright 1988, 1989, 1990 Massachusetts Institute of Technology. .br Copyright 1987 Sun Microsystems, Inc. .br See \fIX(1)\fP for a full statement of rights and permissions. .SH AUTHOR Jim Fulton, MIT X Consortium, rewritten from an earlier version by David Rosenthal of Sun Microsystems. .TH XRDB 1 "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .SH NAME xrdb - X server resource database utility .SH SYNOPSIS .B xrdb [-option ...] [\fIfilename\fP] .SH DESCRIPTION .I Xrdb is used to get or set the contents of the RESOURCE_MANAGER property on the root window of screen 0, or the SCREEN_RESOURCES property on the root window of any or all screens, or everything combined. You would normally run this program from your X startup file. .LP Most X clients use the RESOURCE_MANAGER and SCREEN_RESOURCES properties to get user preferences about color, fonts, and so on for applications. Having this information in the server (where it is available to all clients) instead of on disk, solves the problem in previous versions of X that required you to maintain \fIdefaults\fP files on every machine that you might use. It also allows for dynamic changing of defaults without editing files. .LP The RESOURCE_MANAGER property is used for resources that apply to all screens of the display. The SCREEN_RESOURCES property on each screen specifies additional (or overriding) resources to be used for that screen. (When there is only one screen, SCREEN_RESOURCES is normally not used, all resources are just placed in the RESOURCE_MANAGER property.) .LP The file specified by .I filename (or the contents from standard input if - or no filename is given) is optionally passed through the C preprocessor with the following symbols defined, based on the capabilities of the server being used: .TP 8 .B BITS_PER_RGB=num the number of significant bits in an RGB color specification. This is the log base 2 of the number of distinct shades of each primary that the hardware can generate. Note that it usually is not related to PLANES. .TP 8 .B CLASS=visualclass one of StaticGray, GrayScale, StaticColor, PseudoColor, TrueColor, DirectColor. This is the visual class of the root window of the default screen. .TP 8 .B COLOR defined only if CLASS is one of StaticColor, PseudoColor, TrueColor, or DirectColor. .TP 8 .B HEIGHT=num the height of the default screen in pixels. .TP 8 .B SERVERHOST=hostname the hostname portion of the display to which you are connected. .TP 8 .B HOST=hostname the same as .BR SERVERHOST . .TP 8 .B CLIENTHOST=hostname the name of the host on which .I xrdb is running. .TP 8 .B PLANES=num the number of bit planes (the depth) of the root window of the default screen. .TP 8 .B RELEASE=num the vendor release number for the server. The interpretation of this number will vary depending on VENDOR. .TP 8 .B REVISION=num the X protocol minor version supported by this server (currently 0). .TP 8 .B VERSION=num the X protocol major version supported by this server (should always be 11). .TP 8 .B VENDOR=vendor a string specifying the vendor of the server. .TP 8 .B WIDTH=num the width of the default screen in pixels. .TP 8 .B X_RESOLUTION=num the x resolution of the default screen in pixels per meter. .TP 8 .B Y_RESOLUTION=num the y resolution of the default screen in pixels per meter. .LP Lines that begin with an exclamation mark (!) are ignored and may be used as comments. .LP Note that since .I xrdb can read from standard input, it can be used to the change the contents of properties directly from a terminal or from a shell script. .SH "OPTIONS" .PP .I xrdb program accepts the following options: .TP 8 .B \-help This option (or any unsupported option) will cause a brief description of the allowable options and parameters to be printed. .TP 8 .B \-display \fIdisplay\fP This option specifies the X server to be used; see \fIX(1)\fP. It also specifies the screen to use for the \fI-screen\fP option, and it specifies the screen from which preprocessor symbols are derived for the \fI-global\fP option. .TP 8 .B \-all This option indicates that operation should be performed on the screen-independent resource property (RESOURCE_MANAGER), as well as the screen-specific property (SCREEN_RESOURCES) on every screen of the display. For example, when used in conjunction with \fI-query\fP, the contents of all properties are output. For \fI-load\fP and \fI-merge\fP, the input file is processed once for each screen. The resources which occur in common in the output for every screen are collected, and these are applied as the screen-independent resources. The remaining resources are applied for each individual per-screen property. This the default mode of operation. .TP 8 .B \-global This option indicates that the operation should only be performed on the screen-independent RESOURCE_MANAGER property. .TP 8 .B \-screen This option indicates that the operation should only be performed on the SCREEN_RESOURCES property of the default screen of the display. .TP 8 .B \-screens This option indicates that the operation should be performed on the SCREEN_RESOURCES property of each screen of the display. For \fI-load\fP and \fI-merge\fP, the input file is processed for each screen. .TP 8 .B \-n This option indicates that changes to the specified properties (when used with \fI-load\fP or \fI-merge\fP) or to the resource file (when used with \fI-edit\fP) should be shown on the standard output, but should not be performed. .TP 8 .B \-quiet This option indicates that warning about duplicate entries should not be displayed. .TP 8 .B -cpp \fIfilename\fP This option specifies the pathname of the C preprocessor program to be used. Although .I xrdb was designed to use CPP, any program that acts as a filter and accepts the -D, -I, and -U options may be used. .TP 8 .B -nocpp This option indicates that .I xrdb should not run the input file through a preprocessor before loading it into properties. .TP 8 .B \-symbols This option indicates that the symbols that are defined for the preprocessor should be printed onto the standard output. .TP 8 .B \-query This option indicates that the current contents of the specified properties should be printed onto the standard output. Note that since preprocessor commands in the input resource file are part of the input file, not part of the property, they won't appear in the output from this option. The .B \-edit option can be used to merge the contents of properties back into the input resource file without damaging preprocessor commands. .TP 8 .B \-load This option indicates that the input should be loaded as the new value of the specified properties, replacing whatever was there (i.e. the old contents are removed). This is the default action. .TP 8 .B \-merge This option indicates that the input should be merged with, instead of replacing, the current contents of the specified properties. Note that this option does a lexicographic sorted merge of the two inputs, which is almost certainly not what you want, but remains for backward compatibility. .TP 8 .B \-remove This option indicates that the specified properties should be removed from the server. .TP 8 .B \-retain This option indicates that the server should be instructed not to reset if \fIxrdb\fP is the first client. This never be necessary under normal conditions, since \fIxdm\fP and \fIxinit\fP always act as the first client. .TP 8 .B \-edit \fIfilename\fP This option indicates that the contents of the specified properties should be edited into the given file, replacing any values already listed there. This allows you to put changes that you have made to your defaults back into your resource file, preserving any comments or preprocessor lines. .TP 8 .B \-backup \fIstring\fP This option specifies a suffix to be appended to the filename used with .B \-edit to generate a backup file. .TP 8 .B \-D\fIname\[=value\]\fP This option is passed through to the preprocessor and is used to define symbols for use with conditionals such as .I #ifdef. .TP 8 .B \-U\fIname\fP This option is passed through to the preprocessor and is used to remove any definitions of this symbol. .TP 8 .B \-I\fIdirectory\fP This option is passed through to the preprocessor and is used to specify a directory to search for files that are referenced with .I #include. .SH FILES Generalizes \fI~/.Xdefaults\fP files. .SH "SEE ALSO" X(1), Xlib Resource Manager documentation, Xt resource documentation .SH ENVIRONMENT .TP 8 .B DISPLAY to figure out which display to use. .SH BUGS .PP The default for no arguments should be to query, not to overwrite, so that it is consistent with other programs. .SH COPYRIGHT Copyright 1991, Digital Equipment Corporation and MIT. .SH AUTHORS Bob Scheifler, Phil Karlton, rewritten from the original by Jim Gettys .TH XSET 1 "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .SH NAME xset - user preference utility for X .SH SYNOPSIS .B xset [-display \fIdisplay\fP] [-b] [b on/off] [b [\fIvolume\fP [\fIpitch\fP [\fIduration\fP]]] [[-]bc] [-c] [c on/off] [c [\fIvolume\fP]] [[-+]fp[-+=] \fIpath\fP[,\fIpath\fP[,...]]] [fp default] [fp rehash] [[-]led [\fIinteger\fP]] [led on/off] [m[ouse] [\fIaccel_mult\fP[/\fIaccel_div\fP] [\fIthreshold\fP]]] [m[ouse] default] [p \fIpixel\fP \fIcolor\fP] [[-]r [\fIkeycode\fP]] [r on/off] [s [\fIlength\fP [\fIperiod\fP]]] [s blank/noblank] [s expose/noexpose] [s on/off] [s default] [q] .SH DESCRIPTION This program is used to set various user preference options of the display. .SH OPTIONS .PP .TP 8 .B \-display \fIdisplay\fP This option specifies the server to use; see \fIX(1)\fP. .PP .TP 8 .B b The \fBb\fP option controls bell volume, pitch and duration. This option accepts up to three numerical parameters, a preceding dash(-), or a 'on/off' flag. If no parameters are given, or the 'on' flag is used, the system defaults will be used. If the dash or 'off' are given, the bell will be turned off. If only one numerical parameter is given, the bell volume will be set to that value, as a percentage of its maximum. Likewise, the second numerical parameter specifies the bell pitch, in hertz, and the third numerical parameter specifies the duration in milliseconds. Note that not all hardware can vary the bell characteristics. The X server will set the characteristics of the bell as closely as it can to the user's specifications. .PP .TP 8 .B bc The \fBbc\fP option controls \fIbug compatibility\fP mode in the server, if possible; a preceding dash(-) disables the mode, otherwise the mode is enabled. Various pre-R4 clients pass illegal values in some protocol requests, and pre-R4 servers did not correctly generate errors in these cases. Such clients, when run against an R4 server, will terminate abnormally or otherwise fail to operate correctly. Bug compatibility mode explicitly reintroduces certain bugs into the X server, so that many such clients can still be run. This mode should be used with care; new application development should be done with this mode disabled. The server must support the MIT-SUNDRY-NONSTANDARD protocol extension in order for this option to work. .TP 8 .B c The \fBc\fP option controls key click. This option can take an optional value, a preceding dash(-), or an 'on/off' flag. If no parameter or the 'on' flag is given, the system defaults will be used. If the dash or 'off' flag is used, keyclick will be disabled. If a value from 0 to 100 is given, it is used to indicate volume, as a percentage of the maximum. The X server will set the volume to the nearest value that the hardware can support. .PP .TP 8 .B fp= \fIpath,...\fP The \fBfp=\fP sets the font path to the entries given in the path argument. The entries are interpreted by the server, not by the client. Typically they are directory names or font server names, but the interpretation is server-dependent. .TP 8 .B fp \fBdefault\fP The \fBdefault\fP argument causes the font path to be reset to the server's default. .TP 8 .B fp \fBrehash\fP The \fBrehash\fP argument resets the font path to its current value, causing the server to reread the font databases in the current font path. This is generally only used when adding new fonts to a font directory (after running \fImkfontdir\fP to recreate the font database). .PP .TP 8 .B "\-fp \fRor\fP fp\-" The \fB\-fp\fP and \fBfp\-\fP options remove elements from the current font path. They must be followed by a comma-separated list of entries. .PP .TP 8 .B "\+fp \fRor\fP fp\+" This \fB\+fp\fP and \fBfp\+\fP options prepend and append elements to the current font path, respectively. They must be followed by a comma-separated list of entries. .PP .TP 8 .B led The \fBled\fP option controls the keyboard LEDs. This controls the turning on or off of one or all of the LEDs. It accepts an optional integer, a preceding dash(-) or an 'on/off' flag. If no parameter or the 'on' flag is given, all LEDs are turned on. If a preceding dash or the flag 'off' is given, all LEDs are turned off. If a value between 1 and 32 is given, that LED will be turned on or off depending on the existence of a preceding dash. A common LED which can be controlled is the ``Caps Lock'' LED. ``xset led 3'' would turn led #3 on. ``xset -led 3'' would turn it off. The particular LED values may refer to different LEDs on different hardware. .PP .TP 8 .B m The \fBm\fP option controls the mouse parameters. The parameters for the mouse are `acceleration' and `threshold'. The acceleration can be specified as an integer, or as a simple fraction. The mouse, or whatever pointer the machine is connected to, will go `acceleration' times as fast when it travels more than `threshold' pixels in a short time. This way, the mouse can be used for precise alignment when it is moved slowly, yet it can be set to travel across the screen in a flick of the wrist when desired. One or both parameters for the .B m option can be omitted, but if only one is given, it will be interpreted as the acceleration. If no parameters or the flag 'default' is used, the system defaults will be set. .PP .TP 8 .B p The \fBp\fP option controls pixel color values. The parameters are the color map entry number in decimal, and a color specification. The root background colors may be changed on some servers by altering the entries for BlackPixel and WhitePixel. Although these are often 0 and 1, they need not be. Also, a server may choose to allocate those colors privately, in which case an error will be generated. The map entry must not be a read-only color, or an error will result. .PP .TP 8 .B r The \fBr\fP option controls the autorepeat for one or all keys. It accepts an optional keycode, a preceding dash(-) or an 'on/off' flag. If no parameter or the 'on' flag is given, autorepeat will be enabled for all keys. If a preceding dash or the flag 'off' is given, autorepeat will be disabled for all keys. If a keycode between 0 and 255 is given, autorepeat for the corresponding key will be turned on or off depending on the existence of a preceding dash. .PP .TP 8 .B s The \fBs\fP option lets you set the screen saver parameters. This option accepts up to two numerical parameters, a 'blank/noblank' flag, an 'expose/noexpose' flag, an 'on/off' flag, or the 'default' flag. If no parameters or the 'default' flag is used, the system will be set to its default screen saver characteristics. The 'on/off' flags simply turn the screen saver functions on or off. The 'blank' flag sets the preference to blank the video (if the hardware can do so) rather than display a background pattern, while 'noblank' sets the preference to display a pattern rather than blank the video. The 'expose' flag sets the preference to allow window exposures (the server can freely discard window contents), while 'noexpose' sets the preference to disable screen saver unless the server can regenerate the screens without causing exposure events. The length and period parameters for the screen saver function determines how long the server must be inactive for screen saving to activate, and the period to change the background pattern to avoid burn in. The arguments are specified in seconds. If only one numerical parameter is given, it will be used for the length. .PP .TP 8 .B q The \fBq\fP option gives you information on the current settings. .PP These settings will be reset to default values when you log out. .PP Note that not all X implementations are guaranteed to honor all of these options. .SH "SEE ALSO" X(1), Xserver(1), xmodmap(1), xrdb(1), xsetroot(1) .SH COPYRIGHT Copyright 1988, Massachusetts Institute of Technology. .br See \fIX(1)\fP for a full statement of rights and permissions. .SH AUTHOR Bob Scheifler, MIT Laboratory for Computer Science .br David Krikorian, MIT Project Athena (X11 version) .TH XSETROOT 1 "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .SH NAME xsetroot \- root window parameter setting utility for X .SH SYNOPSIS .B xsetroot [-help] [-def] [-display \fIdisplay\fP] [-cursor \fIcursorfile maskfile\fP] [-cursor_name \fIcursorname\fP] [-bitmap \fIfilename\fP] [-mod \fIx y\fP] [-gray] [-grey] [-fg \fIcolor\fP] [-bg \fIcolor\fP] [-rv] [-solid \fIcolor\fP] [-name \fIstring\fP] .SH DESCRIPTION The .I setroot program allows you to tailor the appearance of the background ("root") window on a workstation display running X. Normally, you experiment with .I xsetroot until you find a personalized look that you like, then put the .I xsetroot command that produces it into your X startup file. If no options are specified, or if .I -def is specified, the window is reset to its default state. The .I -def option can be specified along with other options and only the non-specified characteristics will be reset to the default state. .PP Only one of the background color/tiling changing options (-solid, -gray, -grey, -bitmap, and -mod) may be specified at a time. .SH OPTIONS .PP The various options are as follows: .IP \fB-help\fP Print a usage message and exit. .IP \fB-def\fP Reset unspecified attributes to the default values. (Restores the background to the familiar gray mesh and the cursor to the hollow x shape.) .IP "\fB-cursor\fP \fIcursorfile\fP \fImaskfile\fP" This lets you change the pointer cursor to whatever you want when the pointer cursor is outside of any window. Cursor and mask files are bitmaps (little pictures), and can be made with the .I bitmap(1) program. You probably want the mask file to be all black until you get used to the way masks work. .IP "\fB-cursor_name\fP \fIcursorname\fP This lets you change the pointer cursor to one of the standard cursors from the cursor font. Refer to appendix B of the X protocol for the names (except that the XC_ prefix is elided for this option). .IP "\fB-bitmap\fP \fIfilename\fP" Use the bitmap specified in the file to set the window pattern. You can make your own bitmap files (little pictures) using the .I bitmap(1) program. The entire background will be made up of repeated "tiles" of the bitmap. .IP "\fB-mod\fP \fIx\fP \fIy\fP" This is used if you want a plaid-like grid pattern on your screen. x and y are integers ranging from 1 to 16. Try the different combinations. Zero and negative numbers are taken as 1. .IP \fB-gray\fP Make the entire background gray. (Easier on the eyes.) .IP \fB-grey\fP Make the entire background grey. .IP "\fB-fg\fP \fIcolor\fP" Use ``color'' as the foreground color. Foreground and background colors are meaningful only in combination with -cursor, -bitmap, or -mod. .IP "\fB-bg\fP \fIcolor\fP" Use ``color'' as the background color. .IP \fB-rv\fP This exchanges the foreground and background colors. Normally the foreground color is black and the background color is white. .IP "\fB-solid\fP \fIcolor\fP" This sets the background of the root window to the specified color. This option is only useful on color servers. .IP "\fB-name\fP \fIstring\fP" Set the name of the root window to ``string''. There is no default value. Usually a name is assigned to a window so that the window manager can use a text representation when the window is iconified. This option is unused since you can't iconify the background. .IP "\fB-display\fP \fIdisplay\fP" Specifies the server to connect to; see \fIX(1)\fP. .SH "SEE ALSO" X(1), xset(1), xrdb(1) .SH COPYRIGHT Copyright 1988, Massachusetts Institute of Technology. .br See \fIX(1)\fP for a full statement of rights and permissions. .SH AUTHOR Mark Lillibridge, MIT Project Athena .\" $Header: xstr.1,v 72.3 93/01/14 11:43:37 ssa Exp $ .TA x .TH xstr 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xstr \- extract strings from C programs to implement shared strings .SH SYNOPSIS .C xstr .RC [ -c ] .RC [ - ] .RI [ \|file\| ] .SH DESCRIPTION .C xstr maintains a file .C strings into which strings in component parts of a large program are hashed. These strings are replaced with references to this common area. This serves to implement shared constant strings, which are most useful if they are also read-only. .PP The command: .IP .CI "xstr -c " name .PP extracts the strings from the C source in .IR name , replacing string references with expressions of the form .CI (&xstr[ number ]) for some .IR number . An appropriate declaration of .C xstr is placed at the beginning of the file. The resulting C text is placed in the file .CR x.c , for subsequent compiling. The strings from this file are placed in the .C strings database if they are not there already. Repeated strings and strings that are suffixes of existing strings do not cause changes to the data base. .PP After all components of a large program have been compiled, a file .C xs.c declaring the common .C xstr space, can be created by the command: .IP .C xstr .PP This .C xs.c file should then be compiled and loaded with the rest of the program. If possible, the array can be made read-only (shared), saving space and swap overhead. .PP .C xstr can also be used on a single file. A command: .IP .CI "xstr " name .PP creates files .C x.c and .C xs.c as before, without using or affecting any .C strings file in the same directory. .PP It may be useful to run .C xstr after the C preprocessor if any macro definitions yield strings or if there is conditional code containing strings that are not, in fact, needed. .C xstr reads from its standard input when the argument .C - is given. An appropriate command sequence for running .C xstr after the C preprocessor is: .IP .C "cc -E name.c | xstr -c -" .br .C cc -c x.c .br .C mv x.o name.o .PP .C xstr does not touch the file .C strings unless new items are added, thus .C make can avoid remaking .C xs.o unless truly necessary (see .IR make (1)). .SH AUTHOR .C xstr was developed by the University of California, Berkeley. .SH FILES .TP 15 .C strings Data base of strings .TP .C x.c Massaged C source .TP .C xs.c C source for definition of array .C xstr .TP .C /tmp/xs* Temp file when `xstr name' does not touch .C strings .SH WARNINGS If a string is a suffix of another string in the data base, but the shorter string is seen first by .CR xstr , both strings are placed in the data base, when placing only the longer one there would be sufficient. .SH SEE ALSO mkstr(1). .\" index@\f4xstr\f1 \- extract strings from C programs to implement shared strings@@@\f3xstr(1)\f1 .\" index@extract strings from C programs to implement shared strings@@@\f3xstr(1)\f1 .\" index@shared strings, extract strings from C programs to implement@@@\f3xstr(1)\f1 .\" index@C programs, extract strings from C programs to implement shared strings@@@\f3xstr(1)\f1 .\" index@strings: extract strings from C programs to implement shared strings@@@\f3xstr(1)\f1 .\" .\" toc@\f3xstr(1)\f1:\0\0\f4xstr\f1@@@extract strings from C programs to implement shared strings .\" .\" fileset_database@xstr.1 USER-CMDS-MAN .\" $XConsortium: xterm.man /main/83 1995/12/15 14:06:17 gildea $ .\" Copyright (c) 1989 X Consortium .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the .\" "Software"), to deal in the Software without restriction, including .\" without limitation the rights to use, copy, modify, merge, publish, .\" distribute, sublicense, and/or sell copies of the Software, and to .\" permit persons to whom the Software is furnished to do so, subject to .\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included .\" in all copies or substantial portions of the Software. .\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR .\" OTHER DEALINGS IN THE SOFTWARE. .\" .\" Except as contained in this notice, the name of the X Consortium shall .\" not be used in advertising or otherwise to promote the sale, use or .\" other dealings in this Software without prior written authorization .\" from the X Consortium. .TH XTERM 1 "Release 6.1" "X Version 11" .SH NAME xterm \- terminal emulator for X .SH SYNOPSIS .B xterm [\-\fItoolkitoption\fP ...] [\-option ...] .SH DESCRIPTION The \fIxterm\fP program is a terminal emulator for the X Window System. It provides DEC VT102 and Tektronix 4014 compatible terminals for programs that can't use the window system directly. If the underlying operating system supports terminal resizing capabilities (for example, the SIGWINCH signal in systems derived from 4.3bsd), \fIxterm\fP will use the facilities to notify programs running in the window whenever it is resized. .PP The VT102 and Tektronix 4014 terminals each have their own window so that you can edit text in one and look at graphics in the other at the same time. To maintain the correct aspect ratio (height/width), Tektronix graphics will be restricted to the largest box with a 4014's aspect ratio that will fit in the window. This box is located in the upper left area of the window. .PP Although both windows may be displayed at the same time, one of them is considered the ``active'' window for receiving keyboard input and terminal output. This is the window that contains the text cursor. The active window can be chosen through escape sequences, the ``VT Options'' menu in the VT102 window, and the ``Tek Options'' menu in the 4014 window. .SH EMULATIONS The VT102 emulation is fairly complete, but does not support smooth scrolling, VT52 mode, the blinking character attribute nor the double-wide and double-size character sets. .IR Termcap (5) entries that work with .I xterm include ``xterm,'' ``vt102,'' ``vt100'' and ``ansi,'' and .I xterm automatically searches the termcap file in this order for these entries and then sets the ``TERM'' and the ``TERMCAP'' environment variables. .PP Many of the special .I xterm features may be modified under program control through a set of escape sequences different from the standard VT102 escape sequences. (See the .I "Xterm Control Sequences" document.) .PP The Tektronix 4014 emulation is also fairly good. It supports 12-bit graphics addressing, scaled to the window size. Four different font sizes and five different lines types are supported. There is no write-through or defocused mode support. The Tektronix text and graphics commands are recorded internally by .I xterm and may be written to a file by sending the COPY escape sequence (or through the .B Tektronix menu; see below). The name of the file will be ``\fBCOPY\fIyy\fB\-\fIMM\fB\-\fIdd\fB.\fIhh\fB:\fImm\fB:\fIss\fR'', where .IR yy , .IR MM , .IR dd , .IR hh , .I mm and .I ss are the year, month, day, hour, minute and second when the COPY was performed (the file is created in the directory .I xterm is started in, or the home directory for a login .IR xterm ). .SH "OTHER FEATURES" .I Xterm automatically highlights the text cursor when the pointer enters the window (selected) and unhighlights it when the pointer leaves the window (unselected). If the window is the focus window, then the text cursor is highlighted no matter where the pointer is. .PP In VT102 mode, there are escape sequences to activate and deactivate an alternate screen buffer, which is the same size as the display area of the window. When activated, the current screen is saved and replaced with the alternate screen. Saving of lines scrolled off the top of the window is disabled until the normal screen is restored. The .IR termcap (5) entry for .I xterm allows the visual editor .IR vi (1) to switch to the alternate screen for editing and to restore the screen on exit. .PP In either VT102 or Tektronix mode, there are escape sequences to change the name of the windows. See \fIXterm Control Sequences\fP for details. .SH OPTIONS The \fIxterm\fP terminal emulator accepts all of the standard X Toolkit command line options as well as the following (if the option begins with a .RB ` + ' instead of a .RB ` \- ', the option is restored to its default value): .TP 8 .B \-help This causes \fIxterm\fP to print out a verbose message describing its options. .TP 8 .B \-132 Normally, the VT102 DECCOLM escape sequence that switches between 80 and 132 column mode is ignored. This option causes the DECCOLM escape sequence to be recognized, and the .I xterm window will resize appropriately. .TP 8 .B \-ah This option indicates that .I xterm should always highlight the text cursor. By default, .I xterm will display a hollow text cursor whenever the focus is lost or the pointer leaves the window. .TP 8 .B \+ah This option indicates that .I xterm should do text cursor highlighting based on focus. .TP 8 .BI \-b " number" This option specifies the size of the inner border (the distance between the outer edge of the characters and the window border) in pixels. The default is 2. .TP 8 .B "\-cb" Set the \fIvt100\fP resource \fBcutToBeginningOfLine\fP to FALSE. .TP 8 .B "\+cb" Set the \fIvt100\fP resource \fBcutToBeginningOfLine\fP to TRUE. .TP 8 .B "\-cc \fIcharacterclassrange\fP:\fIvalue\fP[,...]" This sets classes indicated by the given ranges for using in selecting by words. See the section specifying character classes. .TP 8 .B "\-cn" This option indicates that newlines should not be cut in line-mode selections. .TP 8 .B \+cn This option indicates that newlines should be cut in line-mode selections. .TP 8 .BI \-cr " color" This option specifies the color to use for text cursor. The default is to use the same foreground color that is used for text. .TP 8 .B \-cu This option indicates that \fIxterm\fP should work around a bug in the .IR more (1) program that causes it to incorrectly display lines that are exactly the width of the window and are followed by a line beginning with a tab (the leading tabs are not displayed). This option is so named because it was originally thought to be a bug in the .IR curses (3x) cursor motion package. .TP 8 .B \+cu This option indicates that \fIxterm\fP should not work around the .IR more (1) bug mentioned above. .TP 8 .BI \-e " program \fP[ \fIarguments \fP.\|.\|. ]\fI" This option specifies the program (and its command line arguments) to be run in the \fIxterm\fP window. It also sets the window title and icon name to be the basename of the program being executed if neither \fI\-T\fP nor \fI\-n\fP are given on the command line. \fBThis must be the last option on the command line.\fP .TP 8 .BI \-fb " font" This option specifies a font to be used when displaying bold text. This font must be the same height and width as the normal font. If only one of the normal or bold fonts is specified, it will be used as the normal font and the bold font will be produced by overstriking this font. The default is to do overstriking of the normal font. .TP 8 .B \-im Turn on the \fBuseInsertMode\fP resource. .TP 8 .B +im Turn off the \fBuseInsertMode\fP resource. .TP 8 .B \-j This option indicates that \fIxterm\fP should do jump scrolling. Normally, text is scrolled one line at a time; this option allows \fIxterm\fP to move multiple lines at a time so that it doesn't fall as far behind. Its use is strongly recommended since it make \fIxterm\fP much faster when scanning through large amounts of text. The VT100 escape sequences for enabling and disabling smooth scroll as well as the ``VT Options'' menu can be used to turn this feature on or off. .TP 8 .B \+j This option indicates that \fIxterm\fP should not do jump scrolling. .TP 8 .B \-ls This option indicates that the shell that is started in the \fIxterm\fP window will be a login shell (i.e., the first character of argv[0] will be a dash, indicating to the shell that it should read the user's .login or .profile). .TP 8 .B \+ls This option indicates that the shell that is started should not be a login shell (i.e. it will be a normal ``subshell''). .TP 8 .B \-mb This option indicates that \fIxterm\fP should ring a margin bell when the user types near the right end of a line. This option can be turned on and off from the ``VT Options'' menu. .TP 8 .B \+mb This option indicates that margin bell should not be rung. .TP 8 .B "\-mc milliseconds" This option specifies the maximum time between multi-click selections. .TP 8 .BI \-ms " color" This option specifies the color to be used for the pointer cursor. The default is to use the foreground color. .TP 8 .BI \-nb " number" This option specifies the number of characters from the right end of a line at which the margin bell, if enabled, will ring. The default is 10. .TP 8 .B \-rw This option indicates that reverse-wraparound should be allowed. This allows the cursor to back up from the leftmost column of one line to the rightmost column of the previous line. This is very useful for editing long shell command lines and is encouraged. This option can be turned on and off from the ``VT Options'' menu. .TP 8 .B \+rw This option indicates that reverse-wraparound should not be allowed. .TP 8 .B \-aw This option indicates that auto-wraparound should be allowed. This allows the cursor to automatically wrap to the beginning of the next line when when it is at the rightmost position of a line and text is output. .TP 8 .B \+aw This option indicates that auto-wraparound should not be allowed. .TP 8 .B \-s This option indicates that \fIxterm\fP may scroll asynchronously, meaning that the screen does not have to be kept completely up to date while scrolling. This allows \fIxterm\fP to run faster when network latencies are very high and is typically useful when running across a very large internet or many gateways. .TP 8 .B \+s This option indicates that \fIxterm\fP should scroll synchronously. .TP 8 .B \-sb This option indicates that some number of lines that are scrolled off the top of the window should be saved and that a scrollbar should be displayed so that those lines can be viewed. This option may be turned on and off from the ``VT Options'' menu. .TP 8 .B \+sb This option indicates that a scrollbar should not be displayed. .TP 8 .B \-sf This option indicates that Sun Function Key escape codes should be generated for function keys. .TP 8 .B \+sf This option indicates that the standard escape codes should be generated for function keys. .TP 8 .B \-si This option indicates that output to a window should not automatically reposition the screen to the bottom of the scrolling region. This option can be turned on and off from the ``VT Options'' menu. .TP 8 .B \+si This option indicates that output to a window should cause it to scroll to the bottom. .TP 8 .B \-sk This option indicates that pressing a key while using the scrollbar to review previous lines of text should cause the window to be repositioned automatically in the normal position at the bottom of the scroll region. .TP 8 .B \+sk This option indicates that pressing a key while using the scrollbar should not cause the window to be repositioned. .TP 8 .BI \-sl " number" This option specifies the number of lines to save that have been scrolled off the top of the screen. The default is 64. .TP 8 .B \-t This option indicates that \fIxterm\fP should start in Tektronix mode, rather than in VT102 mode. Switching between the two windows is done using the ``Options'' menus. .TP 8 .B \+t This option indicates that \fIxterm\fP should start in VT102 mode. .TP 8 .BI \-tm " string" This option specifies a series of terminal setting keywords followed by the characters that should be bound to those functions, similar to the \fIstty\fP program. Allowable keywords include: intr, quit, erase, kill, eof, eol, swtch, start, stop, brk, susp, dsusp, rprnt, flush, weras, and lnext. Control characters may be specified as ^char (e.g. ^c or ^u) and ^? may be used to indicate delete. .TP 8 .BI \-tn " name" This option specifies the name of the terminal type to be set in the TERM environment variable. This terminal type must exist in the \fItermcap(5)\fP database and should have \fIli#\fP and \fIco#\fP entries. .TP 8 .B \-ut This option indicates that \fIxterm\fP shouldn't write a record into the the system log file \fI/etc/utmp\fP. .TP 8 .B \+ut This option indicates that \fIxterm\fP should write a record into the system log file \fI/etc/utmp\fP. .TP 8 .B \-vb This option indicates that a visual bell is preferred over an audible one. Instead of ringing the terminal bell whenever a Control-G is received, the window will be flashed. .TP 8 .B \+vb This option indicates that a visual bell should not be used. .TP 8 .B \-wf This option indicates that \fIxterm\fP should wait for the window to be mapped the first time before starting the subprocess so that the initial terminal size settings and environment variables are correct. It is the application's responsibility to catch subsequent terminal size changes. .TP 8 .B \+wf This option indicates that \fIxterm\fP show not wait before starting the subprocess. .TP 8 .B \-C This option indicates that this window should receive console output. This is not supported on all systems. To obtain console output, you must be the owner of the console device, and you must have read and write permission for it. If you are running X under \fIxdm\fP on the console screen you may need to have the session startup and reset programs explicitly change the ownership of the console device in order to get this option to work. .TP 8 .B \-S\fIccn\fP This option specifies the last two letters of the name of a pseudoterminal to use in slave mode, plus the number of the inherited file descriptor. The option is parsed ``%c%c%d''. This allows \fIxterm\fP to be used as an input and output channel for an existing program and is sometimes used in specialized applications. .PP The following command line arguments are provided for compatibility with older versions. They may not be supported in the next release as the X Toolkit provides standard options that accomplish the same task. .TP 8 .B "%\fIgeom\fP" This option specifies the preferred size and position of the Tektronix window. It is shorthand for specifying the ``\fI*tekGeometry\fP'' resource. .TP 8 .B \#\fIgeom\fP This option specifies the preferred position of the icon window. It is shorthand for specifying the ``\fI*iconGeometry\fP'' resource. .TP 8 .BI \-T " string" This option specifies the title for \fIxterm\fP's windows. It is equivalent to \fB\-title\fP. .TP 8 .BI \-n " string" This option specifies the icon name for \fIxterm\fP's windows. It is shorthand for specifying the ``\fI*iconName\fP'' resource. Note that this is not the same as the toolkit option \fB\-name\fP (see below). The default icon name is the application name. .TP 8 .B \-r This option indicates that reverse video should be simulated by swapping the foreground and background colors. It is equivalent to \fB\-rv\fP. .TP 8 .BI \-w " number" This option specifies the width in pixels of the border surrounding the window. It is equivalent to \fB\-borderwidth\fP or \fB\-bw\fP. .PP The following standard X Toolkit command line arguments are commonly used with \fIxterm\fP: .TP 8 .B \-bg \fIcolor\fP This option specifies the color to use for the background of the window. The default is ``white.'' .TP 8 .B \-bd \fIcolor\fP This option specifies the color to use for the border of the window. The default is ``black.'' .TP 8 .B \-bw \fInumber\fP This option specifies the width in pixels of the border surrounding the window. .TP 8 .B \-fg \fIcolor\fP This option specifies the color to use for displaying text. The default is ``black.'' .TP 8 .B \-fn \fIfont\fP This option specifies the font to be used for displaying normal text. The default is \fIfixed\fP. .TP 8 .B \-name \fIname\fP This option specifies the application name under which resources are to be obtained, rather than the default executable file name. \fIName\fP should not contain ``.'' or ``*'' characters. .TP 8 .B \-title \fIstring\fP This option specifies the window title string, which may be displayed by window managers if the user so chooses. The default title is the command line specified after the \fB\-e\fP option, if any, otherwise the application name. .TP 8 .B \-rv This option indicates that reverse video should be simulated by swapping the foreground and background colors. .TP 8 .B \-geometry \fIgeometry\fP This option specifies the preferred size and position of the VT102 window; see \fIX(1)\fP. .TP 8 .B \-display \fIdisplay\fP This option specifies the X server to contact; see \fIX(1)\fP. .TP 8 .B \-xrm \fIresourcestring\fP This option specifies a resource string to be used. This is especially useful for setting resources that do not have separate command line options. .TP 8 .B \-iconic This option indicates that \fIxterm\fP should ask the window manager to start it as an icon rather than as the normal window. .SH RESOURCES The program understands all of the core X Toolkit resource names and classes as well as: .\".in +1in .TP 8 .B "iconGeometry (\fPclass\fB IconGeometry)" Specifies the preferred size and position of the application when iconified. It is not necessarily obeyed by all window managers. .TP 8 .B "iconName (\fPclass\fB IconName)" Specifies the icon name. The default is the application name. .TP 8 .B "termName (\fPclass\fB TermName)" Specifies the terminal type name to be set in the TERM environment variable. .TP 8 .B "title (\fPclass\fB Title)" Specifies a string that may be used by the window manager when displaying this application. .TP 8 .B "ttyModes (\fPclass\fB TtyModes)" Specifies a string containing terminal setting keywords and the characters to which they may be bound. Allowable keywords include: intr, quit, erase, kill, eof, eol, swtch, start, stop, brk, susp, dsusp, rprnt, flush, weras, and lnext. Control characters may be specified as ^char (e.g. ^c or ^u) and ^? may be used to indicate Delete. This is very useful for overriding the default terminal settings without having to do an \fIstty\fP every time an \fIxterm\fP is started. .TP 8 .B "useInsertMode (\fPclass\fB UseInsertMode) Force use of insert mode by adding appropriate entries to the TERMCAP environment variable. This is useful if the system termcap is broken. The default is ``false.'' .TP 8 .B "utmpInhibit (\fPclass\fB UtmpInhibit)" Specifies whether or not \fIxterm\fP should try to record the user's terminal in \fI/etc/utmp\fP. .TP 8 .B "sunFunctionKeys (\fPclass\fB SunFunctionKeys)" Specifies whether or not Sun Function Key escape codes should be generated for function keys instead of standard escape sequences. .\".in -1in .TP 8 .B "waitForMap (\fPclass\fB WaitForMap)" Specifies whether or not \fIxterm\fP should wait for the initial window map before starting the subprocess. The default is ``false.'' .\".in 11in .sp .PP The following resources are specified as part of the \fIvt100\fP widget (class \fIVT100\fP): .\".in +1in .TP 8 .B "allowSendEvents (\fPclass\fB AllowSendEvents)" Specifies whether or not synthetic key and button events (generated using the X protocol SendEvent request) should be interpreted or discarded. The default is ``false'' meaning they are discarded. Note that allowing such events creates a very large security hole. .sp .TP 8 .B "alwaysHighlight (\fPclass\fB AlwaysHighlight)" Specifies whether or not \fIxterm\fP should always display a highlighted text cursor. By default, a hollow text cursor is displayed whenever the pointer moves out of the window or the window loses the input focus. .TP 8 .B "appcursorDefault (\fPclass\fB AppcursorDefault)" If ``true,'' the cursor keys are initially in application mode. The default is ``false.'' .TP 8 .B "appkeypadDefault (\fPclass\fB AppkeypadDefault)" If ``true,'' the keypad keys are initially in application mode. The default is ``false.'' .TP 8 .B "autoWrap (\fPclass\fB AutoWrap)" Specifies whether or not auto-wraparound should be enabled. The default is ``true.'' .TP 8 .B "bellSuppressTime (\fPclass\fB BellSuppressTime)" Number of milliseconds after a bell command is sent during which additional bells will be suppressed. Default is 200. If set non-zero, additional bells will also be suppressed until the server reports that processing of the first bell has been completed; this feature is most useful with the visible bell. .TP 8 .B "boldFont (\fPclass\fB BoldFont)" Specifies the name of the bold font to use instead of overstriking. .TP 8 .B "c132 (\fPclass\fB C132)" Specifies whether or not the VT102 DECCOLM escape sequence should be honored. The default is ``false.'' .TP 8 .B "cutNewline (\fPclass\fB CutNewline)" If false, triple clicking to select a line does not include the Newline at the end of the line. If true, the Newline is selected. The default is ``true.'' .TP 8 .B "cutToBeginningOfLine (\fPclass\fB CutToBeginningOfLine)" If false, triple clicking to select a line selects only from the current word forward. If true, the entire line is selected. The default is ``true.'' .TP 8 .B "charClass (\fPclass\fB CharClass)" Specifies comma-separated lists of character class bindings of the form [\fIlow\fP\-]\fIhigh\fP:\fIvalue\fP. These are used in determining which sets of characters should be treated the same when doing cut and paste. See the section on specifying character classes. .TP 8 .B "curses (\fPclass\fB Curses)" Specifies whether or not the last column bug in .IR more (1) should be worked around. See the \fB\-cu\fP option for details. The default is ``false.'' .TP 8 .B "background (\fPclass\fB Background)" Specifies the color to use for the background of the window. The default is ``white.'' .TP 8 .B "foreground (\fPclass\fB Foreground)" Specifies the color to use for displaying text in the window. Setting the class name instead of the instance name is an easy way to have everything that would normally appear in the text color change color. The default is ``black.'' .TP 8 .B "cursorColor (\fPclass\fB Foreground)" Specifies the color to use for the text cursor. The default is ``black.'' .TP 8 .B "eightBitInput (\fPclass\fB EightBitInput\fP)" If true, Meta characters input from the keyboard are presented as a single character with the eighth bit turned on. If false, Meta characters are converted into a two-character sequence with the character itself preceded by ESC. The default is ``true.'' .TP 8 .B "eightBitOutput (\fPclass\fB EightBitOutput\fP)" Specifies whether or not eight-bit characters sent from the host should be accepted as is or stripped when printed. The default is ``true.'' .TP 8 .B "font (\fPclass\fB Font)" Specifies the name of the normal font. The default is ``fixed.'' .TP 8 .B "font1 (\fPclass\fB Font1)" Specifies the name of the first alternative font. .TP 8 .B "font2 (\fPclass\fB Font2)" Specifies the name of the second alternative font. .TP 8 .B "font3 (\fPclass\fB Font3)" Specifies the name of the third alternative font. .TP 8 .B "font4 (\fPclass\fB Font4)" Specifies the name of the fourth alternative font. .TP 8 .B "font5 (\fPclass\fB Font5)" Specifies the name of the fifth alternative font. .TP 8 .B "font6 (\fPclass\fB Font6)" Specifies the name of the sixth alternative font. .TP 8 .B "geometry (\fPclass\fB Geometry)" Specifies the preferred size and position of the VT102 window. .TP 8 .B "hpLowerleftBugCompat (\fPclass\fB HpLowerleftBugCompat)" Specifies whether to work around a bug in HP's \fIxdb\fP, which ignores termcap and always sends ESC F to move to the lower left corner. ``true'' causes xterm to interpret ESC F as a request to move to the lower left corner of the screen. The default is ``false.'' .TP 8 .B "internalBorder (\fPclass\fB BorderWidth)" Specifies the number of pixels between the characters and the window border. The default is 2. .TP 8 .B "jumpScroll (\fPclass\fB JumpScroll)" Specifies whether or not jump scroll should be used. The default is ``true.'' .TP 8 .B "loginShell (\fPclass\fB LoginShell)" Specifies whether or not the shell to be run in the window should be started as a login shell. The default is ``false.'' .TP 8 .B "marginBell (\fPclass\fB MarginBell)" Specifies whether or not the bell should be run when the user types near the right margin. The default is ``false.'' .TP 8 .B "multiClickTime (\fPclass\fB MultiClickTime)" Specifies the maximum time in milliseconds between multi-click select events. The default is 250 milliseconds. .TP 8 .B "multiScroll (\fPclass\fB MultiScroll)" Specifies whether or not scrolling should be done asynchronously. The default is ``false.'' .TP 8 .B "nMarginBell (\fPclass\fB Column)" Specifies the number of characters from the right margin at which the margin bell should be rung, when enabled. .TP 8 .B "pointerColor (\fPclass\fB Foreground)" Specifies the foreground color of the pointer. The default is ``XtDefaultForeground.'' .TP 8 .B "pointerColorBackground (\fPclass\fB Background)" Specifies the background color of the pointer. The default is ``XtDefaultBackground.'' .TP 8 .B "pointerShape (\fPclass\fB Cursor)" Specifies the name of the shape of the pointer. The default is ``xterm.'' .TP 8 .B "resizeGravity (\fPclass\fB ResizeGravity)" Affects the behavior when the window is resized to be taller or shorter. \fBNorthWest\fP specifies that the top line of text on the screen stay fixed. If the window is made shorter, lines are dropped from the bottom; if the window is made taller, blank lines are added at the bottom. This is compatible with the behavior in R4. \fBSouthWest\fP (the default) specifies that the bottom line of text on the screen stay fixed. If the window is made taller, additional saved lines will be scrolled down onto the screen; if the window is made shorter, lines will be scrolled off the top of the screen, and the top saved lines will be dropped. .TP 8 .B "reverseVideo (\fPclass\fB ReverseVideo)" Specifies whether or not reverse video should be simulated. The default is ``false.'' .TP 8 .B "reverseWrap (\fPclass\fB ReverseWrap)" Specifies whether or not reverse-wraparound should be enabled. The default is ``false.'' .TP 8 .B "saveLines (\fPclass\fB SaveLines)" Specifies the number of lines to save beyond the top of the screen when a scrollbar is turned on. The default is 64. .TP 8 .B "scrollBar (\fPclass\fB ScrollBar)" Specifies whether or not the scrollbar should be displayed. The default is ``false.'' .TP 8 .B "scrollTtyOutput (\fPclass\fB ScrollCond)" Specifies whether or not output to the terminal should automatically cause the scrollbar to go to the bottom of the scrolling region. The default is ``true.'' .TP 8 .B "scrollKey (\fPclass\fB ScrollCond)" Specifies whether or not pressing a key should automatically cause the scrollbar to go to the bottom of the scrolling region. The default is ``false.'' .TP 8 .B "scrollLines (\fPclass\fB ScrollLines)" Specifies the number of lines that the \fIscroll-back\fP and \fIscroll-forw\fP actions should use as a default. The default value is 1. .TP 8 .B "signalInhibit (\fPclass\fB SignalInhibit)" Specifies whether or not the entries in the ``Main Options'' menu for sending signals to \fIxterm\fP should be disallowed. The default is ``false.'' .TP 8 .B "tekGeometry (\fPclass\fB Geometry)" Specifies the preferred size and position of the Tektronix window. .TP 8 .B "tekInhibit (\fPclass\fB TekInhibit)" Specifies whether or not the escape sequence to enter Tektronix mode should be ignored. The default is ``false.'' .TP 8 .B "tekSmall (\fPclass\fB TekSmall)" Specifies whether or not the Tektronix mode window should start in its smallest size if no explicit geometry is given. This is useful when running \fIxterm\fP on displays with small screens. The default is ``false.'' .TP 8 .B "tekStartup (\fPclass\fB TekStartup)" Specifies whether or not \fIxterm\fP should start up in Tektronix mode. The default is ``false.'' .TP 8 .B "titeInhibit (\fPclass\fB TiteInhibit)" Specifies whether or not \fIxterm\fP should remove remove \fIti\fP and \fIte\fP termcap entries (used to switch between alternate screens on startup of many screen-oriented programs) from the TERMCAP string. If set, \fIxterm\fP also ignores the escape sequence to switch to the alternate screen. .TP 8 .B "translations (\fPclass\fB Translations)" Specifies the key and button bindings for menus, selections, ``programmed strings,'' etc. See \fBACTIONS\fP below. .TP 8 .B "visualBell (\fPclass\fB VisualBell)" Specifies whether or not a visible bell (i.e. flashing) should be used instead of an audible bell when Control-G is received. The default is ``false.'' .sp .PP The following resources are specified as part of the \fItek4014\fP widget (class \fITek4014\fP): .\".in +1in .TP 8 .B "width (\fPclass\fB Width)" Specifies the width of the Tektronix window in pixels. .TP 8 .B "height (\fPclass\fB Height)" Specifies the height of the Tektronix window in pixels. .TP 8 .B "fontLarge (\fPclass\fB Font)" Specifies the large font to use in the Tektronix window. .TP 8 .B "font2 (\fPclass\fB Font)" Specifies font number 2 to use in the Tektronix window. .TP 8 .B "font3 (\fPclass\fB Font)" Specifies font number 3 to use in the Tektronix window. .TP 8 .B "fontSmall (\fPclass\fB Font)" Specifies the small font to use in the Tektronix window. .TP 8 .B "initialFont (\fPclass\fB InitialFont)" Specifies which of the four Tektronix fonts to use initially. Values are the same as for the \fIset-tek-text\fP action. The default is ``large.'' .TP 8 .B "ginTerminator (\fPclass\fB GinTerminator)" Specifies what character(s) should follow a GIN report or status report. The possibilities are ``none,'' which sends no terminating characters, ``CRonly,'' which sends CR, and ``CR&EOT,'' which sends both CR and EOT. The default is ``none.'' .\".in -1in .sp .PP The resources that may be specified for the various menus are described in the documentation for the Athena \fBSimpleMenu\fP widget. The name and classes of the entries in each of the menus are listed below. .PP The \fImainMenu\fP has the following entries: .\".in +1in .TP 8 .B "securekbd (\fPclass\fB SmeBSB)" This entry invokes the \fBsecure()\fP action. .TP 8 .B "allowsends (\fPclass\fB SmeBSB)" This entry invokes the \fBallow-send-events(toggle)\fP action. .TP 8 .B "redraw (\fPclass\fB SmeBSB)" This entry invokes the \fBredraw()\fP action. .TP 8 .B "line1 (\fPclass\fB SmeLine)" This is a separator. .TP 8 .B "suspend (\fPclass\fB SmeBSB)" This entry invokes the \fBsend-signal(tstp)\fP action on systems that support job control. .TP 8 .B "continue (\fPclass\fB SmeBSB)" This entry invokes the \fBsend-signal(cont)\fP action on systems that support job control. .TP 8 .B "interrupt (\fPclass\fB SmeBSB)" This entry invokes the \fBsend-signal(int)\fP action. .TP 8 .B "hangup (\fPclass\fB SmeBSB)" This entry invokes the \fBsend-signal(hup)\fP action. .TP 8 .B "terminate (\fPclass\fB SmeBSB)" This entry invokes the \fBsend-signal(term)\fP action. .TP 8 .B "kill (\fPclass\fB SmeBSB)" This entry invokes the \fBsend-signal(kill)\fP action. .TP 8 .B "line2 (\fPclass\fB SmeLine)" This is a separator. .TP 8 .B "quit (\fPclass\fB SmeBSB)" This entry invokes the \fBquit()\fP action. .\".in -1in .sp .PP The \fIvtMenu\fP has the following entries: .\".in +1in .TP 8 .B "scrollbar (\fPclass\fB SmeBSB)" This entry invokes the \fBset-scrollbar(toggle)\fP action. .TP 8 .B "jumpscroll (\fPclass\fB SmeBSB)" This entry invokes the \fBset-jumpscroll(toggle)\fP action. .TP 8 .B "reversevideo (\fPclass\fB SmeBSB)" This entry invokes the \fBset-reverse-video(toggle)\fP action. .TP 8 .B "autowrap (\fPclass\fB SmeBSB)" This entry invokes the \fBset-autowrap(toggle)\fP action. .TP 8 .B "reversewrap (\fPclass\fB SmeBSB)" This entry invokes the \fBset-reversewrap(toggle)\fP action. .TP 8 .B "autolinefeed (\fPclass\fB SmeBSB)" This entry invokes the \fBset-autolinefeed(toggle)\fP action. .TP 8 .B "appcursor (\fPclass\fB SmeBSB)" This entry invokes the \fBset-appcursor(toggle)\fP action. .TP 8 .B "appkeypad (\fPclass\fB SmeBSB)" This entry invokes the \fBset-appkeypad(toggle)\fP action. .TP 8 .B "scrollkey (\fPclass\fB SmeBSB)" This entry invokes the \fBset-scroll-on-key(toggle)\fP action. .TP 8 .B "scrollttyoutput (\fPclass\fB SmeBSB)" This entry invokes the \fBset-scroll-on-tty-output(toggle)\fP action. .TP 8 .B "allow132 (\fPclass\fB SmeBSB)" This entry invokes the \fBset-allow132(toggle)\fP action. .TP 8 .B "cursesemul (\fPclass\fB SmeBSB)" This entry invokes the \fBset-cursesemul(toggle)\fP action. .TP 8 .B "visualbell (\fPclass\fB SmeBSB)" This entry invokes the \fBset-visualbell(toggle)\fP action. .TP 8 .B "marginbell (\fPclass\fB SmeBSB)" This entry invokes the \fBset-marginbell(toggle)\fP action. .TP 8 .B "altscreen (\fPclass\fB SmeBSB)" This entry is currently disabled. .TP 8 .B "line1 (\fPclass\fB SmeLine)" This is a separator. .TP 8 .B "softreset (\fPclass\fB SmeBSB)" This entry invokes the \fBsoft-reset()\fP action. .TP 8 .B "hardreset (\fPclass\fB SmeBSB)" This entry invokes the \fBhard-reset()\fP action. .TP 8 .B "clearsavedlines" (\fPclass\fB SmeBSB)" This entry invokes the \fBclear-saved-lines()\fP action. .TP 8 .B "line2 (\fPclass\fB SmeLine)" This is a separator. .TP 8 .B "tekshow (\fPclass\fB SmeBSB)" This entry invokes the \fBset-visibility(tek,toggle)\fP action. .TP 8 .B "tekmode (\fPclass\fB SmeBSB)" This entry invokes the \fBset-terminal-type(tek)\fP action. .TP 8 .B "vthide (\fPclass\fB SmeBSB)" This entry invokes the \fBset-visibility(vt,off)\fP action. .\".in -1in .sp .PP The \fIfontMenu\fP has the following entries: .\".in +1in .TP 8 .B "fontdefault (\fPclass\fB SmeBSB)" This entry invokes the \fBset-vt-font(d)\fP action. .TP 8 .B "font1 (\fPclass\fB SmeBSB)" This entry invokes the \fBset-vt-font(1)\fP action. .TP 8 .B "font2 (\fPclass\fB SmeBSB)" This entry invokes the \fBset-vt-font(2)\fP action. .TP 8 .B "font3 (\fPclass\fB SmeBSB)" This entry invokes the \fBset-vt-font(3)\fP action. .TP 8 .B "font4 (\fPclass\fB SmeBSB)" This entry invokes the \fBset-vt-font(4)\fP action. .TP 8 .B "font5 (\fPclass\fB SmeBSB)" This entry invokes the \fBset-vt-font(5)\fP action. .TP 8 .B "font6 (\fPclass\fB SmeBSB)" This entry invokes the \fBset-vt-font(6)\fP action. .TP 8 .B "fontescape (\fPclass\fB SmeBSB)" This entry invokes the \fBset-vt-font(e)\fP action. .TP 8 .B "fontsel (\fPclass\fB SmeBSB)" This entry invokes the \fBset-vt-font(s)\fP action. .\".in -1in .sp .PP The \fItekMenu\fP has the following entries: .\".in +1in .TP 8 .B "tektextlarge (\fPclass\fB SmeBSB)" This entry invokes the \fBset-tek-text(l)\fP action. .TP 8 .B "tektext2 (\fPclass\fB SmeBSB)" This entry invokes the \fBset-tek-text(2)\fP action. .TP 8 .B "tektext3 (\fPclass\fB SmeBSB)" This entry invokes the \fBset-tek-text(3)\fP action. .TP 8 .B "tektextsmall (\fPclass\fB SmeBSB)" This entry invokes the \fBset-tek-text(s)\fP action. .TP 8 .B "line1 (\fPclass\fB SmeLine)" This is a separator. .TP 8 .B "tekpage (\fPclass\fB SmeBSB)" This entry invokes the \fBtek-page()\fP action. .TP 8 .B "tekreset (\fPclass\fB SmeBSB)" This entry invokes the \fBtek-reset()\fP action. .TP 8 .B "tekcopy (\fPclass\fB SmeBSB)" This entry invokes the \fBtek-copy()\fP action. .TP 8 .B "line2 (\fPclass\fB SmeLine)" This is a separator. .TP 8 .B "vtshow (\fPclass\fB SmeBSB)" This entry invokes the \fBset-visibility(vt,toggle)\fP action. .TP 8 .B "vtmode (\fPclass\fB SmeBSB)" This entry invokes the \fBset-terminal-type(vt)\fP action. .TP 8 .B "tekhide (\fPclass\fB SmeBSB)" This entry invokes the \fBset-visibility(tek,toggle)\fP action. .\".in -1in .sp .PP The following resources are useful when specified for the Athena Scrollbar widget: .\".in +1in .TP 8 .B "thickness (\fPclass\fB Thickness)" Specifies the width in pixels of the scrollbar. .TP 8 .B "background (\fPclass\fB Background)" Specifies the color to use for the background of the scrollbar. .TP 8 .B "foreground (\fPclass\fB Foreground)" Specifies the color to use for the foreground of the scrollbar. The ``thumb'' of the scrollbar is a simple checkerboard pattern alternating pixels for foreground and background color. .\".in -1in .SH "POINTER USAGE" .PP Once the VT102 window is created, .I xterm allows you to select text and copy it within the same or other windows. .PP The selection functions are invoked when the pointer buttons are used with no modifiers, and when they are used with the ``shift'' key. The assignment of the functions described below to keys and buttons may be changed through the resource database; see \fBACTIONS\fP below. .PP Pointer button one (usually left) is used to save text into the cut buffer. Move the cursor to beginning of the text, and then hold the button down while moving the cursor to the end of the region and releasing the button. The selected text is highlighted and is saved in the global cut buffer and made the PRIMARY selection when the button is released. Double-clicking selects by words. Triple-clicking selects by lines. Quadruple-clicking goes back to characters, etc. Multiple-click is determined by the time from button up to button down, so you can change the selection unit in the middle of a selection. If the key/button bindings specify that an X selection is to be made, \fIxterm\fP will leave the selected text highlighted for as long as it is the selection owner. .PP Pointer button two (usually middle) `types' (pastes) the text from the PRIMARY selection, if any, otherwise from the cut buffer, inserting it as keyboard input. .PP Pointer button three (usually right) extends the current selection. (Without loss of generality, you can swap ``right'' and ``left'' everywhere in the rest of this paragraph.) If pressed while closer to the right edge of the selection than the left, it extends/contracts the right edge of the selection. If you contract the selection past the left edge of the selection, .I xterm assumes you really meant the left edge, restores the original selection, then extends/contracts the left edge of the selection. Extension starts in the selection unit mode that the last selection or extension was performed in; you can multiple-click to cycle through them. .PP By cutting and pasting pieces of text without trailing new lines, you can take text from several places in different windows and form a command to the shell, for example, or take output from a program and insert it into your favorite editor. Since the cut buffer is globally shared among different applications, you should regard it as a `file' whose contents you know. The terminal emulator and other text programs should be treating it as if it were a text file, i.e., the text is delimited by new lines. .PP The scroll region displays the position and amount of text currently showing in the window (highlighted) relative to the amount of text actually saved. As more text is saved (up to the maximum), the size of the highlighted area decreases. .PP Clicking button one with the pointer in the scroll region moves the adjacent line to the top of the display window. .PP Clicking button three moves the top line of the display window down to the pointer position. .PP Clicking button two moves the display to a position in the saved text that corresponds to the pointer's position in the scrollbar. .PP .PP Unlike the VT102 window, the Tektronix window dows not allow the copying of text. It does allow Tektronix GIN mode, and in this mode the cursor will change from an arrow to a cross. Pressing any key will send that key and the current coordinate of the cross cursor. Pressing button one, two, or three will return the letters `l', `m', and `r', respectively. If the `shift' key is pressed when a pointer button is pressed, the corresponding upper case letter is sent. To distinguish a pointer button from a key, the high bit of the character is set (but this is bit is normally stripped unless the terminal mode is RAW; see .IR tty (4) for details). .SH MENUS .PP .I Xterm has four menus, named .IR mainMenu , .IR vtMenu , .IR fontMenu , and .IR tekMenu . Each menu pops up under the correct combinations of key and button presses. Most menus are divided into two section, separated by a horizontal line. The top portion contains various modes that can be altered. A check mark appears next to a mode that is currently active. Selecting one of these modes toggles its state. The bottom portion of the menu are command entries; selecting one of these performs the indicated function. .PP The .B xterm menu pops up when the ``control'' key and pointer button one are pressed in a window. The \fImainMenu\fP contains items that apply to both the VT102 and Tektronix windows. The .B Secure Keyboard mode is be used when typing in passwords or other sensitive data in an unsecure environment; see \fBSECURITY\fP below. Notable entries in the command section of the menu are the .BR Continue , .BR Suspend , .BR Interrupt , .BR Hangup , .B Terminate and .B Kill which sends the SIGCONT, SIGTSTP, SIGINT, SIGHUP, SIGTERM and SIGKILL signals, respectively, to the process group of the process running under .I xterm (usually the shell). The .B Continue function is especially useful if the user has accidentally typed CTRL-Z, suspending the process. .PP The .I vtMenu sets various modes in the VT102 emulation, and is popped up when the ``control'' key and pointer button two are pressed in the VT102 window. In the command section of this menu, the soft reset entry will reset scroll regions. This can be convenient when some program has left the scroll regions set incorrectly (often a problem when using VMS or TOPS-20). The full reset entry will clear the screen, reset tabs to every eight columns, and reset the terminal modes (such as wrap and smooth scroll) to their initial states just after .I xterm has finished processing the command line options. .PP The \fIfontMenu\fP sets the font used in the VT102 window. In addition to the default font and a number of alternatives that are set with resources, the menu offers the font last specified by the Set Font escape sequence (see the document \fIXterm Control Sequences\fP) and the current selection as a font name (if the PRIMARY selection is owned). .PP The .I tekMenu sets various modes in the Tektronix emulation, and is popped up when the ``control'' key and pointer button two are pressed in the Tektronix window. The current font size is checked in the modes section of the menu. The .B PAGE entry in the command section clears the Tektronix window. .SH SECURITY .PP X environments differ in their security consciousness. Most servers, run under \fIxdm\fP, are capable of using a ``magic cookie'' authorization scheme that can provide a reasonable level of security for many people. If your server is only using a host-based mechanism to control access to the server (see \fIxhost(1)\fP), then if you enable access for a host and other users are also permitted to run clients on that same host, there is every possibility that someone can run an application that will use the basic services of the X protocol to snoop on your activities, potentially capturing a transcript of everything you type at the keyboard. This is of particular concern when you want to type in a password or other sensitive data. The best solution to this problem is to use a better authorization mechanism that host-based control, but a simple mechanism exists for protecting keyboard input in \fIxterm\fP. .PP The \fBxterm\fP menu (see \fBMENUS\fP above) contains a \fBSecure Keyboard\fP entry which, when enabled, ensures that all keyboard input is directed \fIonly\fP to \fIxterm\fP (using the GrabKeyboard protocol request). When an application prompts you for a password (or other sensitive data), you can enable \fBSecure Keyboard\fP using the menu, type in the data, and then disable \fBSecure Keyboard\fP using the menu again. Only one X client at a time can secure the keyboard, so when you attempt to enable \fBSecure Keyboard\fP it may fail. In this case, the bell will sound. If the \fBSecure Keyboard\fP succeeds, the foreground and background colors will be exchanged (as if you selected the \fBReverse Video\fP entry in the \fBModes\fP menu); they will be exchanged again when you exit secure mode. If the colors do \fInot\fP switch, then you should be \fIvery\fP suspicious that you are being spoofed. If the application you are running displays a prompt before asking for the password, it is safest to enter secure mode \fIbefore\fP the prompt gets displayed, and to make sure that the prompt gets displayed correctly (in the new colors), to minimize the probability of spoofing. You can also bring up the menu again and make sure that a check mark appears next to the entry. .PP \fBSecure Keyboard\fP mode will be disabled automatically if your xterm window becomes iconified (or otherwise unmapped), or if you start up a reparenting window manager (that places a title bar or other decoration around the window) while in \fBSecure Keyboard\fP mode. (This is a feature of the X protocol not easily overcome.) When this happens, the foreground and background colors will be switched back and the bell will sound in warning. .SH "CHARACTER CLASSES" Clicking the middle mouse button twice in rapid succession will cause all characters of the same class (e.g. letters, white space, punctuation) to be selected. Since different people have different preferences for what should be selected (for example, should filenames be selected as a whole or only the separate subnames), the default mapping can be overridden through the use of the \fIcharClass\fP (class \fICharClass\fP) resource. .PP This resource is a series of comma-separated of \fIrange\fP:\fIvalue\fP pairs. The \fIrange\fP is either a single number or \fIlow\fP-\fIhigh\fP in the range of 0 to 127, corresponding to the ASCII code for the character or characters to be set. The \fIvalue\fP is arbitrary, although the default table uses the character number of the first character occurring in the set. .PP The default table is .sp .in +8 .ft C \" Courier .nf static int charClass[128] = { /* NUL SOH STX ETX EOT ENQ ACK BEL */ 32, 1, 1, 1, 1, 1, 1, 1, /* BS HT NL VT NP CR SO SI */ 1, 32, 1, 1, 1, 1, 1, 1, /* DLE DC1 DC2 DC3 DC4 NAK SYN ETB */ 1, 1, 1, 1, 1, 1, 1, 1, /* CAN EM SUB ESC FS GS RS US */ 1, 1, 1, 1, 1, 1, 1, 1, /* SP ! " # $ % & ' */ 32, 33, 34, 35, 36, 37, 38, 39, /* ( ) * + , \- . / */ 40, 41, 42, 43, 44, 45, 46, 47, /* 0 1 2 3 4 5 6 7 */ 48, 48, 48, 48, 48, 48, 48, 48, /* 8 9 : ; < = > ? */ 48, 48, 58, 59, 60, 61, 62, 63, /* @ A B C D E F G */ 64, 48, 48, 48, 48, 48, 48, 48, /* H I J K L M N O */ 48, 48, 48, 48, 48, 48, 48, 48, /* P Q R S T U V W */ 48, 48, 48, 48, 48, 48, 48, 48, /* X Y Z [ \\ ] ^ _ */ 48, 48, 48, 91, 92, 93, 94, 48, /* ` a b c d e f g */ 96, 48, 48, 48, 48, 48, 48, 48, /* h i j k l m n o */ 48, 48, 48, 48, 48, 48, 48, 48, /* p q r s t u v w */ 48, 48, 48, 48, 48, 48, 48, 48, /* x y z { | } ~ DEL */ 48, 48, 48, 123, 124, 125, 126, 1}; .fi .ft P .in -8 .sp For example, the string ``33:48,37:48,45-47:48,64:48'' indicates that the exclamation mark, percent sign, dash, period, slash, and ampersand characters should be treated the same way as characters and numbers. This is useful for cutting and pasting electronic mailing addresses and filenames. .SH ACTIONS It is possible to rebind keys (or sequences of keys) to arbitrary strings for input, by changing the translations for the vt100 or tek4014 widgets. Changing the translations for events other than key and button events is not expected, and will cause unpredictable behavior. The following actions are provided for using within the \fIvt100\fP or \fItek4014\fP \fBtranslations\fP resources: .TP 8 .B "bell([\fIpercent\fP])" This action rings the keyboard bell at the specified percentage above or below the base volume. .TP 8 .B "ignore()" This action ignores the event but checks for special pointer position escape sequences. .TP 8 .B "insert()" This action inserts the character or string associated with the key that was pressed. .TP 8 .B "insert-seven-bit()" This action is a synonym for \fBinsert()\fP .TP 8 .B "insert-eight-bit()" This action inserts an eight-bit (Meta) version of the character or string associated with the key that was pressed. The exact action depends on the value of the \fBeightBitInput\fP resource. .TP 8 .B "insert-selection(\fIsourcename\fP [, ...])" This action inserts the string found in the selection or cutbuffer indicated by \fIsourcename\fP. Sources are checked in the order given (case is significant) until one is found. Commonly-used selections include: \fIPRIMARY\fP, \fISECONDARY\fP, and \fICLIPBOARD\fP. Cut buffers are typically named \fICUT_BUFFER0\fP through \fICUT_BUFFER7\fP. .TP 8 .B "keymap(\fIname\fP)" This action dynamically defines a new translation table whose resource name is \fIname\fP with the suffix \fIKeymap\fP (case is significant). The name \fINone\fP restores the original translation table. .TP 8 .B "popup-menu(\fImenuname\fP)" This action displays the specified popup menu. Valid names (case is significant) include: \fImainMenu\fP, \fIvtMenu\fP, \fIfontMenu\fP, and \fItekMenu\fP. .TP 8 .B "secure()" This action toggles the \fISecure Keyboard\fP mode described in the section named \fBSECURITY\fP, and is invoked from the \fBsecurekbd\fP entry in \fImainMenu\fP. .TP 8 .B "select-start()" This action begins text selection at the current pointer location. See the section on \fBPOINTER USAGE\fP for information on making selections. .TP 8 .B "select-extend()" This action tracks the pointer and extends the selection. It should only be bound to Motion events. .TP 8 .B "select-end(\fIdestname\fP [, ...])" This action puts the currently selected text into all of the selections or cutbuffers specified by \fIdestname\fP. .TP 8 .B "select-cursor-start()" This action is similar to \fBselect-start\fP except that it begins the selection at the current text cursor position. .TP 8 .B "select-cursor-end(\fIdestname\fP [, ...])" This action is similar to \fBselect-end\fP except that it should be used with \fBselect-cursor-start\fP. .TP 8 .B "set-vt-font(\fId/1/2/3/4/5/6/e/s\fP [,\fInormalfont\fP [, \fIboldfont\fP]])" This action sets the font or fonts currently being used in the VT102 window. The first argument is a single character that specifies the font to be used: \fId\fP or \fID\fP indicate the default font (the font initially used when \fIxterm\fP was started), \fI1\fP through \fI6\fP indicate the fonts specified by the \fIfont1\fP through \fIfont6\fP resources, \fIe\fP or \fIE\fP indicate the normal and bold fonts that have been set through escape codes (or specified as the second and third action arguments, respectively), and \fIs\fP or \fIS\fP indicate the font selection (as made by programs such as \fIxfontsel(1)\fP) indicated by the second action argument. .TP 8 .B "start-extend()" This action is similar to \fBselect-start\fP except that the selection is extended to the current pointer location. .TP 8 .B "start-cursor-extend()" This action is similar to \fBselect-extend\fP except that the selection is extended to the current text cursor position. .TP 8 .B "string(\fIstring\fP)" This action inserts the specified text string as if it had been typed. Quotation is necessary if the string contains whitespace or non-alphanumeric characters. If the string argument begins with the characters ``0x'', it is interpreted as a hex character constant. .TP 8 .B "scroll-back(\fIcount\fP [,\fIunits\fP])" This action scrolls the text window backward so that text that had previously scrolled off the top of the screen is now visible. The \fIcount\fP argument indicates the number of \fIunits\fP (which may be \fIpage\fP, \fIhalfpage\fP, \fIpixel\fP, or \fIline\fP) by which to scroll. .TP 8 .B "scroll-forw(\fIcount\fP [,\fIunits\fP])" This action scrolls is similar to \fBscroll-back\fP except that it scrolls the other direction. .TP 8 .B "allow-send-events(\fIon/off/toggle\fP)" This action set or toggles the \fBallowSendEvents\fP resource and is also invoked by the \fBallowsends\fP entry in \fImainMenu\fP. .TP 8 .B "redraw()" This action redraws the window and is also invoked by the \fIredraw\fP entry in \fImainMenu\fP. .TP 8 .B "send-signal(\fIsigname\fP)" This action sends the signal named by \fIsigname\fP to the \fIxterm\fP subprocess (the shell or program specified with the \fI\-e\fP command line option) and is also invoked by the .BR suspend , .BR continue , .BR interrupt , .BR hangup , .BR terminate , and .BR kill entries in \fImainMenu\fP. Allowable signal names are (case is not significant): \fItstp\fP (if supported by the operating system), \fIsuspend\fP (same as \fItstp\fP), \fIcont\fP (if supported by the operating system), \fIint\fP, \fIhup\fP, \fIterm\fP, \fIquit\fP, \fIalrm\fP, \fIalarm\fP (same as \fIalrm\fP) and \fIkill\fP. .TP 8 .B "quit()" This action sends a SIGHUP to the subprogram and exits. It is also invoked by the \fBquit\fP entry in \fImainMenu\fP. .TP 8 .B "set-scrollbar(\fIon/off/toggle\fP)" This action toggles the \fBscrollbar\fP resource and is also invoked by the \fBscrollbar\fP entry in \fIvtMenu\fP. .TP 8 .B "set-jumpscroll(\fIon/off/toggle\fP)" This action toggles the \fBjumpscroll\fP resource and is also invoked by the \fBjumpscroll\fP entry in \fIvtMenu\fP. .TP 8 .B "set-reverse-video(\fIon/off/toggle\fP)" This action toggles the \fIreverseVideo\fP resource and is also invoked by the \fBreversevideo\fP entry in \fIvtMenu\fP. .TP 8 .B "set-autowrap(\fIon/off/toggle\fP)" This action toggles automatic wrapping of long lines and is also invoked by the \fBautowrap\fP entry in \fIvtMenu\fP. .TP 8 .B "set-reversewrap(\fIon/off/toggle\fP)" This action toggles the \fBreverseWrap\fP resource and is also invoked by the \fBreversewrap\fP entry in \fIvtMenu\fP. .TP 8 .B "set-autolinefeed(\fIon/off/toggle\fP)" This action toggles automatic insertion of linefeeds and is also invoked by the \fBautolinefeed\fP entry in \fIvtMenu\fP. .TP 8 .B "set-appcursor(\fIon/off/toggle\fP)" This action toggles the handling Application Cursor Key mode and is also invoked by the \fBappcursor\fP entry in \fIvtMenu\fP. .TP 8 .B "set-appkeypad(\fIon/off/toggle\fP)" This action toggles the handling of Application Keypad mode and is also invoked by the \fBappkeypad\fP entry in \fIvtMenu\fP. .TP 8 .B "set-scroll-on-key(\fIon/off/toggle\fP)" This action toggles the \fBscrollKey\fP resource and is also invoked from the \fBscrollkey\fP entry in \fIvtMenu\fP. .TP 8 .B "set-scroll-on-tty-output(\fIon/off/toggle\fP)" This action toggles the \fBscrollTtyOutput\fP resource and is also invoked from the \fBscrollttyoutput\fP entry in \fIvtMenu\fP. .TP 8 .B "set-allow132(\fIon/off/toggle\fP)" This action toggles the \fBc132\fP resource and is also invoked from the \fBallow132\fP entry in \fIvtMenu\fP. .TP 8 .B "set-cursesemul(\fIon/off/toggle\fP)" This action toggles the \fBcurses\fP resource and is also invoked from the \fBcursesemul\fP entry in \fIvtMenu\fP. .TP 8 .B "set-visual-bell(\fIon/off/toggle\fP)" This action toggles the \fBvisualBell\fP resource and is also invoked by the \fBvisualbell\fP entry in \fIvtMenu\fP. .TP 8 .B "set-marginbell(\fIon/off/toggle\fP)" This action toggles the \fBmarginBell\fP resource and is also invoked from the \fBmarginbell\fP entry in \fIvtMenu\fP. .TP 8 .B "set-altscreen(\fIon/off/toggle\fP)" This action toggles between the alternate and current screens. .TP 8 .B "soft-reset()" This action resets the scrolling region and is also invoked from the \fBsoftreset\fP entry in \fIvtMenu\fP. .TP 8 .B "hard-reset()" This action resets the scrolling region, tabs, window size, and cursor keys and clears the screen. It is also invoked from the \fBhardreset\fP entry in \fIvtMenu\fP. .TP 8 .B "clear-saved-lines()" This action does \fBhard-reset()\fP (see above) and also clears the history of lines saved off the top of the screen. It is also invoked from the \fBclearsavedlines\fP entry in \fIvtMenu\fP. .TP 8 .B "set-terminal-type(\fItype\fP)" This action directs output to either the \fIvt\fP or \fItek\fP windows, according to the \fItype\fP string. It is also invoked by the \fBtekmode\fP entry in \fIvtMenu\fP and the \fBvtmode\fP entry in \fItekMenu\fP. .TP 8 .B "set-visibility(\fIvt/tek\fP,\fIon/off/toggle\fP)" This action controls whether or not the \fIvt\fP or \fItek\fP windows are visible. It is also invoked from the \fBtekshow\fP and \fBvthide\fP entries in \fIvtMenu\fP and the \fBvtshow\fP and \fBtekhide\fP entries in \fItekMenu\fP. .TP 8 .B "set-tek-text(\fIlarge/2/3/small\fP)" This action sets font used in the Tektronix window to the value of the resources \fBtektextlarge\fP, \fBtektext2\fP, \fBtektext3\fP, and \fBtektextsmall\fP according to the argument. It is also by the entries of the same names as the resources in \fItekMenu\fP. .TP 8 .B "tek-page()" This action clears the Tektronix window and is also invoked by the \fBtekpage\fP entry in \fItekMenu\fP. .TP 8 .B "tek-reset()" This action resets the Tektronix window and is also invoked by the \fItekreset\fP entry in \fItekMenu\fP. .TP 8 .B "tek-copy()" This action copies the escape codes used to generate the current window contents to a file in the current directory beginning with the name COPY. It is also invoked from the \fItekcopy\fP entry in \fItekMenu\fP. .TP 8 .B "visual-bell()" This action flashes the window quickly. .PP The Tektronix window also has the following action: .TP 8 .B "gin-press(\fIl/L/m/M/r/R\fP)" This action sends the indicated graphics input code. .PP The default bindings in the VT102 window are: .sp .in +4 .DS .TA 2.5i .ta 2.5i .nf Shift Prior: scroll-back(1,halfpage) \\n\\ Shift Next: scroll-forw(1,halfpage) \\n\\ Shift Select: select-cursor-start() \\ select-cursor-end(PRIMARY, CUT_BUFFER0) \\n\\ Shift Insert: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\ ~Meta: insert-seven-bit() \\n\\ Meta: insert-eight-bit() \\n\\ !Ctrl : popup-menu(mainMenu) \\n\\ !Lock Ctrl : popup-menu(mainMenu) \\n\\ !Lock Ctrl @Num_Lock : popup-menu(mainMenu) \\n\\ ! @Num_Lock Ctrl : popup-menu(mainMenu) \\n\\ ~Meta : select-start() \\n\\ ~Meta : select-extend() \\n\\ !Ctrl : popup-menu(vtMenu) \\n\\ !Lock Ctrl : popup-menu(vtMenu) \\n\\ !Lock Ctrl @Num_Lock : popup-menu(vtMenu) \\n\\ ! @Num_Lock Ctrl : popup-menu(vtMenu) \\n\\ ~Ctrl ~Meta : ignore() \\n\\ ~Ctrl ~Meta : insert-selection(PRIMARY, CUT_BUFFER0) \\n\\ !Ctrl : popup-menu(fontMenu) \\n\\ !Lock Ctrl : popup-menu(fontMenu) \\n\\ !Lock Ctrl @Num_Lock : popup-menu(fontMenu) \\n\\ ! @Num_Lock Ctrl : popup-menu(fontMenu) \\n\\ ~Ctrl ~Meta : start-extend() \\n\\ ~Meta : select-extend() \\n\\ : select-end(PRIMARY, CUT_BUFFER0) \\n\\ : bell(0) .fi .DE .sp .in -4 .PP The default bindings in the Tektronix window are: .sp .in +4 .DS .TA 2.5i .ta 2.5i .nf ~Meta: insert-seven-bit() \\n\\ Meta: insert-eight-bit() \\n\\ !Ctrl : popup-menu(mainMenu) \\n\\ !Lock Ctrl : popup-menu(mainMenu) \\n\\ !Lock Ctrl @Num_Lock : popup-menu(mainMenu) \\n\\ !Ctrl @Num_Lock : popup-menu(mainMenu) \\n\\ !Ctrl : popup-menu(tekMenu) \\n\\ !Lock Ctrl : popup-menu(tekMenu) \\n\\ !Lock Ctrl @Num_Lock : popup-menu(tekMenu) \\n\\ !Ctrl @Num_Lock : popup-menu(tekMenu) \\n\\ Shift ~Meta: gin-press(L) \\n\\ ~Meta: gin-press(l) \\n\\ Shift ~Meta: gin-press(M) \\n\\ ~Meta: gin-press(m) \\n\\ Shift ~Meta: gin-press(R) \\n\\ ~Meta: gin-press(r) .fi .DE .sp .in -4 .PP Below is a sample how of the \fBkeymap()\fP action is used to add special keys for entering commonly-typed works: .sp .in +4 .nf .DS .TA .5i 1.5i .ta .5i 1.5i .nf *VT100.Translations: #override F13: keymap(dbx) *VT100.dbxKeymap.translations: \\ F14: keymap(None) \\n\\ F17: string("next") string(0x0d) \\n\\ F18: string("step") string(0x0d) \\n\\ F19: string("continue") string(0x0d) \\n\\ F20: string("print ") insert-selection(PRIMARY, CUT_BUFFER0) .fi .DE .sp .in -4 .SH ENVIRONMENT .I Xterm sets the environment variables ``TERM'' and ``TERMCAP'' properly for the size window you have created. It also uses and sets the environment variable ``DISPLAY'' to specify which bit map display terminal to use. The environment variable ``WINDOWID'' is set to the X window id number of the .I xterm window. .SH "SEE ALSO" resize(1), X(1), pty(4), tty(4) .br \fIXterm Control Sequences\fP .SH BUGS .PP Large pastes do not work on some systems. This is not a bug in \fIxterm\fP; it is a bug in the pseudo terminal driver of those systems. \fIxterm\fP feeds large pastes to the pty only as fast as the pty will accept data, but some pty drivers do not return enough information to know if the write has succeeded. .PP Many of the options are not resettable after .I xterm starts. .PP Only fixed-width, character-cell fonts are supported. .PP This program still needs to be rewritten. It should be split into very modular sections, with the various emulators being completely separate widgets that don't know about each other. Ideally, you'd like to be able to pick and choose emulator widgets and stick them into a single control widget. .PP There needs to be a dialog box to allow entry of the Tek COPY file name. .SH AUTHORS Far too many people, including: .sp Loretta Guarino Reid (DEC-UEG-WSL), Joel McCormack (DEC-UEG-WSL), Terry Weissman (DEC-UEG-WSL), Edward Moy (Berkeley), Ralph R. Swick (MIT-Athena), Mark Vandevoorde (MIT-Athena), Bob McNamara (DEC-MAD), Jim Gettys (MIT-Athena), Bob Scheifler (MIT X Consortium), Doug Mink (SAO), Steve Pitschke (Stellar), Ron Newman (MIT-Athena), Jim Fulton (MIT X Consortium), Dave Serisky (HP), Jonathan Kamens (MIT-Athena) .\" $XConsortium: xwd.man /main/20 1995/12/15 14:06:31 gildea $ .\" Copyright (c) 1988, 1994 X Consortium .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the .\" "Software"), to deal in the Software without restriction, including .\" without limitation the rights to use, copy, modify, merge, publish, .\" distribute, sublicense, and/or sell copies of the Software, and to .\" permit persons to whom the Software is furnished to do so, subject to .\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included .\" in all copies or substantial portions of the Software. .\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR .\" OTHER DEALINGS IN THE SOFTWARE. .\" .\" Except as contained in this notice, the name of the X Consortium shall .\" not be used in advertising or otherwise to promote the sale, use or .\" other dealings in this Software without prior written authorization .\" from the X Consortium. .TH XWD 1 "Release 6.1" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 BLD_MONTH BLD_YEAR .SH NAME xwd - dump an image of an X window .SH SYNOPSIS .B "xwd" [-debug] [-help] [-nobdrs] [-out \fIfile\fP] [-xy] [-frame] [-add \fIvalue\fP] [-root | -id \fIid\fP | -name \fIname\fP ] [-icmap] [-screen] [-single] [-multi] [-db] [-display \fIdisplay\fP] .SH DESCRIPTION .PP .I Xwd is an X Window System window dumping utility. .I Xwd allows X users to store window images in a specially formatted dump file. This file can then be read by various other X utilities for redisplay, printing, editing, formatting, archiving, image processing, etc. The target window is selected by clicking the pointer in the desired window. The keyboard bell is rung once at the beginning of the dump and twice when the dump is completed. .SH OPTIONS .PP .TP 8 .B "-display \fIdisplay\fP" This argument allows you to specify the server to connect to; see \fIX(1)\fP. .PP .TP 8 .B "-help" Print out the `Usage:' command syntax summary. .PP .TP 8 .B "-nobdrs" This argument specifies that the window dump should not include the pixels that compose the X window border. This is useful in situations where you may wish to include the window contents in a document as an illustration. .PP .TP 8 .B "-out \fIfile\fP" This argument allows the user to explicitly specify the output file on the command line. The default is to output to standard out. .PP .TP 8 .B "-xy" This option applies to color displays only. It selects `XY' format dumping instead of the default `Z' format. .PP .TP 8 .B "-add \fIvalue\fP" This option specifies an signed value to be added to every pixel. .PP .TP 8 .B "-frame" This option indicates that the window manager frame should be included when manually selecting a window. .PP .TP 8 .B "-root" This option indicates that the root window should be selected for the window dump, without requiring the user to select a window with the pointer. .PP .TP 8 .B "-id \fIid\fP" This option indicates that the window with the specified resource id should be selected for the window dump, without requiring the user to select a window with the pointer. .PP .TP 8 .B "-name \fIname\fP" This option indicates that the window with the specified WM_NAME property should be selected for the window dump, without requiring the user to select a window with the pointer. .PP .TP 8 .B "-icmap" Normally the colormap of the chosen window is used to obtain RGB values. This option forces the first installed colormap of the screen to be used instead. .PP .TP 8 .B "-screen" This option indicates that the GetImage request used to obtain the image should be done on the root window, rather than directly on the specified window. In this way, you can obtain pieces of other windows that overlap the specified window, and more importantly, you can capture menus or other popups that are independent windows but appear over the specified window. .PP .TP 8 .B "-silent" Operate silently, i.e. don't ring any bells before and after dumping the window. .PP .TP 8 .B "-single" Only grab the primary visual for the window. Will exploit the use of BackingStore by a window, if it is overlapped by another window, and it is available. If the window's area contains multiple visuals, only the contents of the primary visual of the window will likely be returned. .PP .TP 8 .B "-multi" Grab the contents of all visuals found within the window's area. Will return the contents of the window as accurately as possible. Many combinations of mixed visuals will cause this to produce 24-bit DirectColor formatted output. It will generally produce output accurately reflecting the exact contents of the window, as they appear on the display. This is the default behavior. The use of .B "-single" negates this options. .PP .TP 8 .B "-db" If any of the windows being processed are double-buffered windows, then you may find it necessary to use this option; this will disable some of the normal optimizations used when processing overlapping windows, and will guarantee that the contents of double-buffered windows are obtained correctly. This option may cause xwd to run more slowly than normal. .SH ENVIRONMENT .PP .TP 8 .B DISPLAY To get default host and display number. .SH FILES .PP .TP 8 .B XWDFile.h X Window Dump File format definition file. .SH SEE ALSO xwud(1), xpr(1), X(1) .SH AUTHORS Tony Della Fera, Digital Equipment Corp., MIT Project Athena .br William F. Wyatt, Smithsonian Astrophysical Observatory .TH XWUD 1 "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.0 July 1994 .SH NAME xwud - image displayer for X .SH SYNOPSIS .B "xwud" [-in \fIfile\fP] [-noclick] [-geometry \fIgeom\fP] [-display \fIdisplay\fP] [-new] [-std ] [-raw] [-vis ] [-help] [-rv] [-plane \fInumber\fP] [-fg \fIcolor\fP] [-bg \fIcolor\fP] .SH DESCRIPTION .PP .I Xwud is an X Window System image undumping utility. .I Xwud allows X users to display in a window an image saved in a specially formatted dump file, such as produced by \fIxwd(1)\fP. .SH OPTIONS .PP .TP 8 .B "-bg \fIcolor\fP" If a bitmap image (or a single plane of an image) is displayed, this option can be used to specify the color to display for the "0" bits in the image. .PP .TP 8 .B "-display \fIdisplay\fP" This option allows you to specify the server to connect to; see \fIX(1)\fP. .PP .TP 8 .B "-fg \fIcolor\fP" If a bitmap image (or a single plane of an image) is displayed, this option can be used to specify the color to display for the "1" bits in the image. .PP .TP 8 .B "-geometry \fIgeom\fP" This option allows you to specify the size and position of the window. Typically you will only want to specify the position, and let the size default to the actual size of the image. .PP .TP 8 .B "-help" Print out a short description of the allowable options. .PP .TP 8 .B "-in \fIfile\fP" This option allows the user to explicitly specify the input file on the command line. If no input file is given, the standard input is assumed. .PP .TP 8 .B -new This option forces creation of a new colormap for displaying the image. If the image characteristics happen to match those of the display, this can get the image on the screen faster, but at the cost of using a new colormap (which on most displays will cause other windows to go technicolor). .PP .TP 8 .B "-noclick" Clicking any button in the window will terminate the application, unless this option is specified. Termination can always be achieved by typing 'q', 'Q', or ctrl-c. .PP .TP 8 .B "-plane \fInumber\fP" You can select a single bit plane of the image to display with this option. Planes are numbered with zero being the least significant bit. This option can be used to figure out which plane to pass to \fIxpr(1)\fP for printing. .PP .TP 8 .B -raw This option forces the image to be displayed with whatever color values happen to currently exist on the screen. This option is mostly useful when undumping an image back onto the same screen that the image originally came from, while the original windows are still on the screen, and results in getting the image on the screen faster. .PP .TP 8 .B -rv If a bitmap image (or a single plane of an image) is displayed, this option forces the foreground and background colors to be swapped. This may be needed when displaying a bitmap image which has the color sense of pixel values "0" and "1" reversed from what they are on your display. .PP .TP 8 .B "-std \fImaptype\fP" This option causes the image to be displayed using the specified Standard Colormap. The property name is obtained by converting the type to upper case, prepending "RGB_", and appending "_MAP". Typical types are "best", "default", and "gray". See \fIxstdcmap(1)\fP for one way of creating Standard Colormaps. .PP .TP 8 .B "-vis \fIvis-type-or-id\fP" This option allows you to specify a particular visual or visual class. The default is to pick the "best" one. A particular class can be specified: "StaticGray", "GrayScale", "StaticColor", "PseudoColor", "DirectColor", or "TrueColor". Or "Match" can be specified, meaning use the same class as the source image. Alternatively, an exact visual id (specific to the server) can be specified, either as a hexadecimal number (prefixed with "0x") or as a decimal number. Finally, "default" can be specified, meaning to use the same class as the colormap of the root window. Case is not significant in any of these strings. .SH ENVIRONMENT .PP .TP 8 .B DISPLAY To get default display. .SH FILES .PP .TP 8 .B XWDFile.h X Window Dump File format definition file. .SH SEE ALSO xwd(1), xpr(1), X(1) .SH COPYRIGHT Copyright 1988, Massachusetts Institute of Technology. .br See \fIX(1)\fP for a full statement of rights and permissions. .SH AUTHOR Bob Scheifler, MIT X Consortium .\" $Header: yes.1,v 72.3 93/01/14 11:40:10 ssa Exp $ .TA y .TH yes 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME yes \- be repetitively affirmative .SH SYNOPSIS .C yes .RI [ \|expletive\| ] .SH DESCRIPTION .C yes repeatedly outputs .CR y , or if .I expletive is given, the .I expletive is output repeatedly. Termination is by interrupt. .SH AUTHOR .C yes was developed by the University of California, Berkeley. .\" .\" toc@\f3yes(1)\f1:\0\0\f4yes\f1@@@be repetitively affirmative .\" .\" index@\f4yes\f1 \- repetitively affirmative responses@@@\f3yes(1)\f1 .\" index@affirmative responses, repetitively@@@\f3yes(1)\f1 .\" index@repetitively affirmative responses@@@\f3yes(1)\f1 .\" index@responses, repetitively affirmative@@@\f3yes(1)\f1 .\" .\" fileset_database@yes.1 USER-CMDS-MAN .\" $Header: ypcat.1,v 72.5 94/09/08 13:34:10 ssa Exp $ .TA y .TH ypcat 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypcat \- print all values in Network Information Service map .SH SYNOPSIS .C ypcat .RC [ -k ] .RC [ -t ] .RC [ -d .IR domain\| ] .I mname .PP .C ypcat -x .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. .SH DESCRIPTION .CR ypcat prints all values in a Network Information Service (NIS) map specified by .IR mname , which can be either a .I mapname or a map .IR nickname . A map .I nickname is a synonym by which a NIS map can be referenced. Values are listed, one per line. .SS Options .CR ypcat recognizes the following options: .RS .TP 8 .CR -k Print the associated key preceding each value. This option is useful for examining maps in which the values are null or the keys are not part of the value, such as the .I ypservers map. The maps derived from files that have an ASCII version in .CR /etc (such as .CR passwd and .CR hosts ) are not in this category. .TP .CR -t Inhibit the translation of a map's .I nickname to its corresponding .IR mapname . For example, .CR "ypcat -t passwd" fails because there is no map named .CR passwd , whereas .CR "ypcat passwd" translates to .CR "ypcat passwd.byname" . .TP .CR -d Specify a .I domain other than the one returned by .CR domainname (see .IR domainname (1)). .TP .CR -x Display the table that lists the .I nickname for each NIS map. .RE .SH AUTHOR .CR ypcat was developed by Sun Microsystems, Inc. .SH EXAMPLES Display the network-wide password database whose .I mapname is .CR passwd.byname and .I nickname is .C passwd : .IP .C ypcat passwd .SH SEE ALSO domainname(1), ypmatch(1), ypserv(1M), ypfiles(4). .\" index@\f4ypcat\f1 \- print values in Network Information Service map@@@\f3ypcat(1)\f1 .\" index@print all values in a Network Information Service map@@@\f3ypcat(1)\f1 .\" index@values in a Network Information Service map, print all@@@\f3ypcat(1)\f1 .\" index@Network Information Service map, print all values in a@@@\f3ypcat(1)\f1 .\" index@map, print all values in a Network Information Service@@@\f3ypcat(1)\f1 .\" toc@\f3ypcat(1)\f1: \f4ypcat\f1@@@print all Network Information Service map values .\" $Header: ypmatch.1,v 72.4 94/08/24 10:53:32 ssa Exp $ .TA y .TH ypmatch 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypmatch \- print values of selected keys in Network Information Service map .SH SYNOPSIS .C ypmatch .RC [ -k ] .RC [ -t ] .RC [ -d .IR domain ] .C key .RC [ key ...] .C mname .PP .C ypmatch -x .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .C ypmatch prints the values associated with one or more keys in a Network Information Service .SM (NIS) map specified by .IR mname . The .I mname can be either a .I mapname or a map .IR nickname . A map .I nickname is a synonym by which a .SM NIS map can be referenced. .PP If multiple keys are specified, the same map is searched for an occurrence of each key. A match is made only when the case and length of a key is the same as that stored in the database. No pattern matching is available. If a key is not matched, a diagnostic message is produced. .SS Options .C ypmatch recognizes the following command-line options: .RS .TP 8 .C -k Before printing the value associated with a key, print the key followed by a colon .RC ( : ). This option is useful if the keys are not part of the values (as in a .C ypservers map), or so many keys were specified that the output could be confusing. .TP .C -t Inhibit the translation of a map's .I nickname to its corresponding .IR mapname . For example, .C ypmatch -t zippy passwd fails because there is no map named .CR passwd , while .C ypmatch zippy passwd is translated to .CR "ypmatch zippy passwd.byname" . .TP .C -d Specify a .I domain other than the one returned by .C domainname (see .IR domainname (1)). .TP .C -x Display the table that lists the .I nickname for each .SM NIS map. .SH AUTHOR .C ypmatch was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), ypcat(1), ypserv(1M), ypfiles(4). .\" .\" index@\f4ypmatch\f1 \- print the values of selected keys in Network Information Service map@@@\f3ypmatch(1)\f1 .\" index@print the values of selected keys in Network Information Service map@@@\f3ypmatch(1)\f1 .\" index@values of selected keys in Network Information Service map, print the@@@\f3ypmatch(1)\f1 .\" index@selected keys in Network Information Service map, print the values of@@@\f3ypmatch(1)\f1 .\" index@keys in Network Information Service map, print the values of selected@@@\f3ypmatch(1)\f1 .\" index@Network Information Service map, print the values of selected keys in@@@\f3ypmatch(1)\f1 .\" index@map, print the values of selected keys in Network Information Service@@@\f3ypmatch(1)\f1 .\" toc@\f3ypmatch(1)\f1: \f4ypmatch\f1@@@print values of selected keys in Network Information Service map .\" $Header: yppasswd.1,v 72.6 94/11/10 13:06:59 ssa Exp $ .TA y .TH yppasswd 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME yppasswd \- change login password in Network Information System (NIS) .SH SYNOPSIS .CR yppasswd .RI [ name ] .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (YP). The functionality remains the same; only the name has changed. .SH DESCRIPTION .CR yppasswd changes or installs a password associated with the login .I name in the Network Information System (NIS). The NIS password can be different from the one on your own machine. If .I name is omitted, it defaults to the name returned by .CR getlogin() (see .IR getlogin (3C)). .PP .CR yppasswd prompts for the old NIS password (even if it does not exist), then twice for the new one. The old password must be entered correctly for the change to take effect. Checks occur to ensure that the new password meets the following construction requirements. .RS .TP 3 \(bu Only the first eight characters are significant. .TP \(bu A password can be as few as four characters long if it contains .RS 6 .TP 3 \(bu at least one special character or .TP \(bu a mixture of numeric, uppercase and lowercase letters. .RE .TP 3 \(bu A password can be as few as five characters long if it contains a mixture of .RS 6 .TP 3 \(bu uppercase and lowercase letters or .TP \(bu numeric and either uppercase or lowercase letters. .RE .TP 3 \(bu A password must contain at least six characters if it contains only monocase letters. .RE .PP All these rules except the first are relaxed if you try three times to enter an unacceptable new password. You cannot, however, enter a null password. .PP Only the owner of the .I name or the superuser can change a password. .PP The Network Information System password daemon, .IR yppasswdd (1M), must be running on the master NIS password server to change NIS passwords. .SH WARNINGS The password update protocol passes the old and new passwords to the master NIS server at once. Thus, if the old NIS password is incorrect, no notification is given until the new NIS password is successfully entered. .PP The .CR yppasswd password construction rules are different from those of the HP-UX .CR passwd command (see .IR passwd (1)). .PP User applications that call this routine must be linked with .CR /usr/include/librpcsvc.a . For example, .IP .C "cc my_source.c -lrpcsvc" .SH AUTHOR .CR yppasswd was developed by Sun Microsystems, Inc. .SH SEE ALSO id(1), passwd(1), su(1), yppasswdd(1M), getlogin(3C), yppasswd(3N), ypfiles(4). .\" index@\f4yppasswd\f1 \- change login password in Network Information System (NIS)@@@\f3yppasswd(1)\f1 .\" index@change login password in Network Information System (NIS)@@@\f3yppasswd(1)\f1 .\" index@login password in Network Information System (NIS), change@@@\f3yppasswd(1)\f1 .\" index@password in Network Information System (NIS), change login@@@\f3yppasswd(1)\f1 .\" index@Network Information System (NIS), change login password in@@@\f3yppasswd(1)\f1 .\" index@NIS (Network Information System), change login password in@@@\f3yppasswd(1)\f1 .\" toc@\f3yppasswd(1)\f1:\0\0\f4yppasswd\f1@@@change login password in Network Information System (NIS) .\" $Header: ypwhich.1,v 72.5 94/09/12 17:02:52 ssa Exp $ .TA y .TH ypwhich 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypwhich \- list which host is Network Information System server or map master .SH SYNOPSIS .C ypwhich .PP .C ypwhich .RC [ -d .IR domain\| ] .RC [ -V1 \(or .CR -V2 ] .RI [ \|hostname\| ] .PP .C ypwhich .RC [ -d .IR domain\| ] .RC [ -t ] .RC [ -m .RI [ \|mname\| ]\|] .PP .C ypwhich -x .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .CR ypwhich lists the host name of the Network Information System (NIS) server that supplies NIS services to a NIS client. It can also print the NIS server that is the master for .IR mname . The .I mname can be either a .I mapname or a map .IR nickname . A map .I nickname is a synonym by which a NIS map can be referenced. .PP If invoked without arguments, .CR ypwhich prints the host name of the NIS server serving the local machine. If .I hostname is specified, that machine is queried to determine which NIS server it is using. .SS Options .CR ypwhich recognizes the following command-line options and arguments: .RS .TP 12 .CR -d Specify a .I domain other than the one returned by .IR domainname (1). .TP .CR -V1 List the server that is serving Version 1 NIS protocol-speaking client processes. .TP .CR -V2 List the server that is serving Version 2 NIS protocol-speaking client processes. .IP If neither version is specified, .CR ypwhich locates the server supplying the Version 2 (current) services. However, if no Version 2 server is found, .CR ypwhich attempts to locate the server supplying the Version 1 services. Since NIS servers and NIS clients are both backward compatible, the user seldom needs to know which version is being used. .TP .CR -t Inhibit the translation of a map's .I nickname to its corresponding .I mapname. For example, .CR "ypwhich -t -m passwd" fails because there is no map named .CR passwd , whereas .CR "ypwhich -m passwd" translates to .CR "ypwhich -m passwd.byname" . This option is useful if a .I mapname is identical to a .I nickname (which is not true of any HP map). .TP .CR -m \0[\|\f2mname\f1\|] List the master NIS server for a map. No .I hostname can be specified with .CR -m . The .I mname can be a .I mapname or a map .IR nickname . If .I mname is omitted, a complete list of available maps and the corresponding host names of the master NIS servers is produced. .TP .CR -x Display the table that lists the .I nickname for each NIS map. .SH AUTHOR .CR ypwhich was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), ypserv(1M), ypset(1M), ypfiles(4). .\" .\" index@\f4ypwhich\f1 \- list which host is Network Information System server or map master@@@\f3ypwhich(1)\f1 .\" index@list which host is Network Information System server or map master@@@\f3ypwhich(1)\f1 .\" index@host is Network Information System server or map master, list which@@@\f3ypwhich(1)\f1 .\" index@Network Information System server or map master, list which host is@@@\f3ypwhich(1)\f1 .\" index@server or map master, list which host is Network Information System@@@\f3ypwhich(1)\f1 .\" index@map master, list which host is Network Information System server or@@@\f3ypwhich(1)\f1 .\" index@master, list which host is Network Information System server or map@@@\f3ypwhich(1)\f1 .\" $Header: compress.1,v 76.1 95/07/10 16:56:11 ssa Exp $ .TA c .TH compress 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compress, uncompress, zcat, compressdir, uncompressdir \- compress and expand data .SH SYNOPSIS .SS Compress Files .C compress .RC [ -d ] .RC [ -f|-z ] .RC [ -z ] .RC [ -v ] .RC [ -c ] .RC [ -V ] .RC [ -b .IR maxbits \|] .RI [ \|file \0...\|] .br .C uncompress .RC [ -f ] .RC [ -v ] .RC [ -c ] .RC [ -V ] .RI [ \|file \0...\|] .br .C zcat .RC [ -V ] .RI [ \|file \0...\|] .SS Compress Entire Directory Subtrees .C compressdir .RI [ \|options\| ] .RI [ \|directory \0...\|] .br .C uncompressdir .RI [ \|options\| ] .RI [ \|directory \0...\|] .SH DESCRIPTION The following commands compress and uncompress files and directory subtrees as indicated: .RS .TP 20 .C compress Reduce the size of the named .IR file s using adaptive Lempel-Ziv coding. If reduction is possible, each .I file is replaced by a new file of the same name with the suffix .CR .Z added to indicate that it is a compressed file. Original ownership, modes, access, and modification times are preserved. If no .I file is specified, or if .CR - is specified, standard input is compressed to the standard output. .TP .C uncompress Restore the compressed .IR file s to original form. Resulting files have the original filename, ownership, and permissions, and the .CR .Z filename suffix is removed. If no .I file is specified, or if .CR - is specified, standard input is uncompressed to the standard output. .TP .C zcat Restore the compressed .IR file s to original form and send the result to standard output. If no .I file is specified, or if .CR - is specified, standard input is uncompressed to the standard output. .TP .C compressdir Front-end processor. Recursively descend each specified .I directory subtree and use .CR compress to compress each file in .IR directory . Existing files are replaced by a compressed file having the same name plus the suffix .CR .Z , provided the resulting file is smaller than the original. If no directories are specified, compression is applied to all files starting with the current directory. .IP .I options may include any valid .CR compress command options (they are passed through to .CR compress ). To force compression of all files, even when the result is larger than the original file, use the .CR -f option. .TP .C uncompressdir Opposite of .CR compressdir . Restore compressed files to their original form. .I options may include any valid .CR uncompress command options (they are passed through to .CR uncompress ). .RE .PP The amount of compression obtained depends on the size of the input, the maximum number of bits .RI ( maxbits ) per code, and the distribution of common substrings. Typically, text such as source code or English is reduced by 50-60 percent. Compression is generally much better than that achieved by Huffman coding (as used in .CR pack ), or adaptive Huffman coding .RC ( compact ), and takes less time to compute. .SS Options These commands recognize the following options in the combinations shown above in .SM SYNOPSIS: .RS .TP 20 .C -d Decompress .IR file . .CR "compress -d" is equivalent to .CR uncompress . .TP .C -f Force compression of .IR file . This is useful for compressing an entire directory, even if some of the files do not actually shrink. If .CR -f is not given and .CR compress is run in the foreground, the user is prompted as to whether an existing file should be overwritten. .TP .C -z This is the same as the .C -f option except that it does not force compression when there is null compression. .TP .C -v Print a message describing the percentage of reduction for each file compressed. .TP .C -c Force .CR compress and .CR uncompress to write to the standard output; no files are changed. The nondestructive behavior of .CR zcat is identical to that of .CR "uncompress -c" . .TP .C -V Print the current version and compile options onto the standard error. .TP .CI -b \0maxbits Specify the maximum number of bits the .CR compress algorithm will use. The default is 16 and the range can be any integer between 9 and 16. .RE .PP .C compress uses the modified Lempel-Ziv algorithm popularized in .I "A Technique for High Performance Data Compression", Terry A. Welch, .I "IEEE Computer," vol. 17, no. 6 (June 1984), pages 8-19. Common substrings in the file are first replaced by 9-bit codes 257 and up. When code 512 is reached, the algorithm switches to 10-bit codes and continues to use more bits until the limit specified by the .CR -b flag is reached (default 16). .PP After the .I maxbits limit is attained, .CR compress periodically checks the compression ratio. If it is increasing, .CR compress continues to use the existing code dictionary. However, if the compression ratio is decreasing, .CR compress discards the table of substrings and rebuilds it from scratch. This allows the algorithm to adapt to the next "block" of the file. .PP Note that the .CR -b flag is omitted for .CR uncompress since the .I maxbits parameter specified during compression is encoded within the output, along with a magic number to ensure that neither decompression of random data nor recompression of compressed data is attempted. .SS "Access Control Lists" .C compress retains a file's access control list when compressing and expanding data. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .CR compress , .CR uncompress , and .C zcat behave as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE These commands return the following values upon completion: .RS .TP 5 .C 0 Completed successfully. .PD 0 .TP .C 2 Last file is larger after (attempted) compression. .TP .C 1 An error occurred. .PD .RE .SH DIAGNOSTICS .TP .C "Usage: compress [-f|-z] [-dvcV] [-b maxbits] [file ...]" Invalid options were specified on the command line. .TP .C "Missing maxbits" .I maxbits must follow .CR -b . .TP .IC file ": not in compressed format" The file specified to .CR uncompress has not been compressed. .TP .IC file ": compressed with " xx "bits, can only handle " yy "bits" .I file was compressed by a program that could deal with a higher value of .I maxbits than the compress code on this machine. Recompress the file with a lower value of .IR maxbits . .TP .IC file ": already has .Z suffix -- no change" The file is assumed to be already compressed. Rename the file and try again. .TP .IC file ": filename too long to tack on .Z" The output file name, which is the source file name with a .CR .Z extension, is too long for the file system on which the source file resides. Make the source file name shorter and try again. .TP .C "file already exists; do you wish to overwrite (y or n)?" Respond .CR y if you want the output to replace the existing file; otherwise, respond .CR n . .TP .C "uncompress: corrupt input" A .CR SIGSEGV violation was detected which usually means that the input file has been corrupted. .TP .CI "Compression: " xx . xx % Percentage of the input saved by compression. (Relevant only for .CR -v .) .TP .C "-- not a regular file: unchanged" When the input file is not a regular file (a directory for example), it is left unaltered. .TP .CI "-- has " xx "other links: unchanged" The input file has links and has been left unchanged. See .IR ln (1) for more information. .TP .C "-- file unchanged" No savings is achieved by compression. The input remains unaltered. .SH EXAMPLES Compress the file named .CR zenith and print compression information to the terminal: .RS .IP .C compress -v zenith .RE .PP The terminal display shows either a line resembling .IP .C "zenith: Compression: 23.55% -- replaced with zenith.Z" .PP indicating that the compressed file is 23.55% smaller than the original, or a line resembling .IP .C "zenith: Compression: -12.04% -- file unchanged" .PP indicating that an additional 12.04% space must be used to compress the file. .PP Undo the compression by typing either of the following commands: .RS .IP .C uncompress zenith.Z .IP .C compress -d zenith.Z .RE .PP This restores file .CR zenith.Z to its original uncompressed form and name. .PP .CR uncompress will perform on standard input if no files are specified. For example, to list a compressed tar file: .RS .IP .C "uncompress -c arch.tar.Z | tar -tvf - " .RE .SH WARNINGS Although compressed files are compatible between machines with large memory, .CR -b 12 should be used for file transfer to architectures with a small process data space (64K bytes or less). .SS \s-1NFS\s0 Access control lists of networked files are summarized (as returned in .CR st_mode by .CR stat() , but not copied to the new file (see .IR stat (2)). .SH AUTHOR .C compress was developed by Joseph M. Orost, Kenneth E. Turkowski, Spencer W. Thomas, and James A. Woods. .SH FILES .TP .C *.Z Compressed file created by .CR compress and removed by .CR uncompress . .SH SEE ALSO compact(1), pack(1), acl(5). .SH STANDARDS CONFORMANCE .CR compress ": XPG4" .\" index@\f4compress\f1, \f4uncompress\f1, \f4zcat\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4uncompress\f1, \f4compress\f1, \f4zcat\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4zcat\f1, \f4compress\f1, \f4uncompress\f1 \- compress or expand data@@@\f3compress(1)\f1 .\" index@\f4compressdir\f1, \f4uncompressdir\f1 \- compress or expand files in a directory@@@\f3compress(1)\f1 .\" index@\f4uncompressdir\f1, \f4compressdir\f1 \- compress or expand files in a directory@@@\f3compress(1)\f1 .\" index@\f1compress or expand data@@@\f3compress(1)\f1 .\" index@\f1expand or compress data@@@\f3compress(1)\f1 .\" index@\f1data, expand or compress@@@\f3compress(1)\f1 .\" index@\f1files: expand compressed files in a directory@@@\f3compress(1)\f1 .\" index@\f1files: expand compressed file@@@\f3compress(1)\f1 .\" index@\f1files: compress files in a directory@@@\f3compress(1)\f1 .\" index@\f1files: compress data in a file@@@\f3compress(1)\f1 .\" index@\f1directory: expand compressed files in a directory@@@\f3compress(1)\f1 .\" index@\f1directory: compress files in a directory@@@\f3compress(1)\f1 .\" .\" toc@\f3compress(1)\f1:\0\0\f4compress\f1, \f4compressdir\f1, \f4uncompress\f1, \f4uncompressdir\f1, \f4zcat\f1@@@compress and expand data .\" toc@\f4uncompress\f1 \- expand compressed data@@@see \f3compress(1)\f1 .\" toc@\f4uncompressdir\f1 \- expand compressed files in a directory@@@see \f3compress(1)\f1 .\" toc@\f4compressdir\f1 \- compress files in a directory@@@see \f3compress(1)\f1 .\" toc@\f4zcat\f1: expand and cat data@@@see \f3compress(1)\f1 .\" .\" links@compress.1 uncompress.1 .\" links@compress.1 zcat.1 .\" links@compress.1 compressdir.1 .\" links@compress.1 uncompressd.1 .\" .\" $Header: asecure.1m,v 76.1 95/06/20 14:30:28 ssa Exp $ .TA a .TH asecure 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME asecure \- control access to Audio on a workstation .SH SYNOPSIS .C /opt/audio/bin/asecure \f1[\f3-CdelP +h \f2host \f3-h \f2host \f3+p \f2user \f3-p \f2user \f3+u \f2user \f3-u \f2user \f3+b \f2host\f1,\f2user \f3-b \f2host\f1,\f2user\f1] .SH DESCRIPTION On Series 700 workstations, audio is secured so that only the user on the local workstation can access audio. You use the .C asecure command to modify audio security. This command does not apply to X stations; on an X station, access to audio is unrestricted. .PP To modify audio security, become root on the local workstation where you want make a change. Then, use .C asecure as follows: .sp .C /opt/audio/bin/asecure -C .sp When prompted, enter any meaningful password. Issuing .C asecure -C creates the Audio Security File (ASF). The ASF contains information that determines which hosts and users can access the Aserver, and which users (other than the superuser) can modify the ASF. .PP If needed, you can allow unrestricted access to audio on this workstation. To remove audio security, issue this command: .sp .C /opt/audio/bin/asecure -d .sp If instead, you wish to modify security, you use .C asecure to make changes to the information in the ASF. (Because the ASF is a binary file, we do not recommend using an editor on this file.) You can use .C asecure to make these types of changes: .RS .TP 3 \(bu Allow all clients from a remote host to access the server. .TP \(bu Allow specific users from all other hosts to access the server. .TP \(bu Allow a specific user from a specific host to access the server. .TP \(bu Disable access control, allowing complete unrestricted access to the server, but leaving the ASF intact. .RE .PP Every operation that creates, reinitializes, or changes the contents of the ASF is logged in the .C /var/adm/audio/asecure_log file, so that you can track any changes to the ASF. .PP .SS OPTIONS .C asecure supports the following options: .RS .TP 15 .CI +b|-b \0host,user Add/delete .IR hostname,username pair. You must be either superuser or a .C privileged user to do this. You can supply more than one .IR hostname,username pair separated by blanks. .IP To use either the .C +b or .C -b options, you MUST supply at least one .IR hostname,username pair. This option will not work without a pair. .TP .C -C Create a new ASF file, called the .C audio.sec file. Access control default is enabled with no entries in the access list. Aserver can now be accessed only by local users on the host machine. If an .C audio.sec file already exists, it is re-initialized. .IP You must be superuser to execute this option. This option is mutually-exclusive of all other options. .IP This option requires a password. This is an extra layer of protection for the contents of the ASF. It is designed to prevent surreptitious manipulation of the ASF. If you are creating a new ASF, you are prompted for a password and an encrypted copy of that password is stored in the new ASF. .IP If the ASF already exists, you are prompted for the password. If your password matches the password stored in the ASF, the ASF is then re-initialized. .TP .C -d Disable access control to the Aserver. This allows unrestricted access by all clients. .TP .C -e Enable access control to the Aserver. This restricts access to clients listed in the ASF. Enabled is the default state. .TP .CI +h|-h \0host Add/delete .IR hostnames for ALL users. You must be either superuser or a .C privileged user to do this. You can supply more than one .IR hostname separated by blanks. .TP .C -l List the contents of the ASF. This option shows a list of the hostnames and/or usernames that have access to the Aserver. .TP .C -P Change password for .C audio.sec file. You must be superuser to do this. You are prompted once for the old password, then prompted twice for the new password. .TP .CI +p|-p \0user Add/delete \f3privileged users\f1. You must be superuser to do this and must enter the password given when the ASF was created (see .C -C option). To see a list of \f3privileged users\f1, you must be superuser and use the .C -l option. .TP .CI +u|-u \0user Add/delete .IR usernames for ALL hosts. You must be either superuser or a .C privileged user to do this. You can supply more than one .IR username separated by blanks. .SH EXAMPLES List entries in access list. .IP .C /opt/audio/bin/asecure -l .PP Disable access control. This means anyone can connect to Aserver without restriction. .IP .C /opt/audio/bin/asecure -d .PP Add .IR moonbeam host for all users to access list. Remove .IR pluto host for all users from access list. .IP .C /opt/audio/bin/asecure +h .IR moonbeam .C -h .IR pluto .PP Add user .IR comet for hosts .IR saturn and .IR mercury to access list. .IP .C /opt/audio/bin/asecure +b .IR saturn,comet .IR mercury,comet .PP Add user .IR comet to access list for all hosts. Remove users .IR venus and .IR neptune from access list for all hosts. .IP .C /opt/audio/bin/asecure +u .IR comet .C -u .IR venus .IR neptune .PP Create new access list. .IP .C /opt/audio/bin/asecure -C .SH AUTHOR .C asecure was developed by .SM HP. .SH FILES .TP 38 .CR /var/opt/audio/asecure_log asecure log pathname .PD 0 .TP .CR /etc/opt/audio/audio.sec ASF pathname .PD .SH SEE ALSO .na audio(5), asecure(1m), aserver(1m), attributes(1), convert(1), send_sound(1). .PP .IR "Using the Audio Developer's Kit" .\" .\" index@\f2asecure\f1 \- Audio@@@\f3asecure(1m)\f1 .\" index@asecure@@@\f3asecure(1m)\f1 .\" index@HP-UX Audio@@@\f3Audio(1)\f1 .\" .\" toc@\f3asecure(1m)\f1:\0\0\f2asecure\f1@@@Audio .\" .\" links@asecure.1m Asecure.1m .\" .\" fileset_database@asecure.1m AUDIO-MAN .\" $Header: aserver.1m,v 76.1 95/06/20 14:30:48 ssa Exp $ .TA a .TH aserver 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME Aserver \- start the audio server .SH SYNOPSIS .C /opt/audio/bin/Aserver \0-f .SS Remarks: The .C Aserver command starts the HP-UX Audio server, which can run on a system with audio hardware. See .C Audio(5) for information about which systems have audio hardware. The .C -f option forces the starting of the Audio server; this option is only needed if the Aserver has problems starting. .SH DESCRIPTION .SS The Audio Server Before using any audio tools such as the .C Audio Editor, the system or X station must be running two audio server processes, called .C Aserver. On a Series 700, the Remote Procedure Call daemon .C (rpcd) must also be running. .PP Normally, the Aserver processes and .C rpcd start automatically when the system is booted. If problems occur on an ENTRIA or ENVIZEX X station, see the X station owner's manual. On a Series 700 Audio hardware, first check if .C rpcd is running. Type the following: .sp .C ps -e | grep rpcd .sp If it is running, you see a line similar to the following. .sp .C 604 ? 0:36 rpcd .sp If it is not running, see HP 9000/DCE documentation for information on restarting it. If .C rpcd is running, verify that the Aserver is running. Type: .sp .C ps -e | grep Aserver .sp If the Aserver is running you will see lines similar to the following, which indicate the presence of the two Aserver processes: .sp .C \0\01 ? 0:00 Aserver .br .C 224 ? 0:00 Aserver .sp If it is not running, become root and restart it as follows: .sp .C /opt/audio/bin/Aserver .sp If it fails to start, reissue the command with the .C -f option: .sp .C /opt/audio/bin/Aserver -f .sp .PP .SS "Using Audio over the Network" From a workstation, you can also use the Audio Editor and Control Panel over the network. However, the remote system is where the actual playback and recording occur. .PP The local workstation (or audio client) can be any Series 700 system. The remote system (or audio server) can be a Series 700 or an X station with audio hardware and must have the Aserver processes running. If the server is a workstation, it must also allow access from remote clients (see .C asecure(1m)) and must have .C rpcd running. .PP To make the system an audio client, set the .C AUDIO variable by modifying the .C $HOME/.vueprofile file as follows: .RS .TP 10 .C Korn, Bourne, and POSIX Shells: AUDIO=system_name; export AUDIO .TP .C C Shell:\0\0\0\0\0\0\0\0\0\0\0 setenv AUDIO system_name .RE .PP For .I system_name, identify the workstation or X Station running the Aserver. .PP If the AUDIO variable is not set, the Audio Library attempts to use to the Aserver on the system defined by the DISPLAY variable. If neither DISPLAY nor AUDIO is set, the Aserver on the local machine is used. .RE .SH DEPENDENCIES The Audio Server must run on a system that has audio hardware. Note that HP-UX for the 8MB 705 System does not include audio software. .SH AUTHOR The Audio Server was developed by .SM HP. .SH SEE ALSO .na audio(5), asecure(1m), attributes(1), convert(1), send_sound(1). .PP .IR "Using the Audio Developer's Kit" .\" .\" index@\f2aserver\f1 \- Audio@@@\f3aserver(1m)\f1 .\" index@aserver@@@\f3aserver(1m)\f1 .\" index@Audio@@@\f3Audio(1)\f1 .\" .\" toc@\f3aserver(1m)\f1:\0\0\f2aserver\f1@@@Audio .\" .\" links@aserver.1m Aserver.1m .\" .\" fileset_database@aserver.1m AUDIO-MAN .\" $Header: accept.1m,v 72.5 94/09/13 11:07:55 ssa Exp $ .TA a .TH accept 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME accept, reject \- allow/prevent LP printer queuing requests .SH SYNOPSIS .CR /usr/sbin/accept .IR destination \ ...\& .PP .CR /usr/sbin/reject .RC \|[ \-r [\f2reason\fP]\|]\| .IR destination \ ...\& .RC \|[ \-r [\f2reason\fP]\| .IR destination \ ...]\ ...\& .SH DESCRIPTION The .CR accept command permits the .CR lp command (see .IR lp (1)) to accept printing requests for each named LP printer or printer class .IR destination queue. .PP The .CR reject command causes the .CR lp command to reject subsequent printing requests for each named .IR destination queue. Requests already queued will continue to be processed for printing by the .CR lpsched scheduler (see .IR lpsched (1M)). .PP Use the .CR lpstat command (see .IR lpstat (1)) to find the status of destination queues. .PP For an overview of LP command interactions, see .IR lp (1). .SS Options The .CR reject command can have the following option. .RS .TP 15 .CR \-r "[\f2reason\fP]" Specifies a string that is used to explain why the .CR lp command is not accepting requests for a destination. .I reason applies to all queues mentioned up to the next .CR \-r option. If .I reason or .CR \-r "[\f2reason\fP]" is omitted, the default is "\c .CR "reason\ unknown\c" ". The maximum length of .I reason is 80 bytes. .IP .I reason is reported by the .CR lpstat command and by the .CR lp command when users direct requests to a rejected destination. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .PP The .CR LANG variable determines the language in which messages are displayed. If .CR LANG is not specified or is set to the empty string, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH EXAMPLES .PP These examples assume you have a system with two printers named .CR laser1 and .CR jet2 , and one class named .CR lj that includes both printers. .ne 4 .SS Example 1 To allow all destinations to accept print requests: .IP .C "accept laser1 jet2 lj" .ne 4 .SS Example 2 To reject requests to the .CR lj class destination, requiring users to choose a printer: .IP .C "reject lj .ne 5 .SS Example 3 To reject requests to the individual printer destinations, requiring all requests to go through the class destination: .IP .C "accept lj" .br .C "reject -r""use the lj destination"" laser1 jet2" .SH WARNINGS .CR accept and .CR reject operate on the local system only. .SH FILES .TP 35 .PD 0 .CR /etc/lp Directory of spooler configuration data .TP .CR /var/adm/lp Directory of spooler log files .TP .CR /var/spool/lp Directory of LP spooling files and directories .PD .SH SEE ALSO enable(1), lp(1), lpstat(1), lpadmin(1M), lpsched(1M), rcancel(1M), rlp(1M), rlpdaemon(1M), rlpstat(1M). .\" .\" index@\f4accept\f1 \- allow LP printer queuing requests@@@\f3accept(1M)\f1 .\" index@\f4reject\f1 \- prevent LP printer queuing requests@@@\f3accept(1M)\f1 .\" index@\f1LP printer, allow or prevent queuing requests@@@\f3accept(1M)\f1 .\" index@\f1printer, LP, allow or prevent queuing requests@@@\f3accept(1M)\f1 .\" .\" toc@\f3accept(1M)\f1:\0\0\f4accept\f1, \f4reject\f1@@@allow or prevent LP printer queuing requests\f1 .\" toc@\f4reject\f1:\0\0prevent LP printer queuing requests@@@see \f3accept(1M)\f1 .\" .\" links@accept.1m reject.1m .\" $Header: acct.1m,v 72.5 94/11/14 12:00:17 ssa Exp $ .TA a .TH acct 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctdisk, acctdusg, accton, acctwtmp, closewtmp, utmp2wtmp \- overview of accounting and miscellaneous accounting commands .SH SYNOPSIS .C /usr/sbin/acct/acctdisk .PP .C /usr/sbin/acct/acctdusg .RC [ -u .IR file\| ] .RC [ -p .IR file\| ] .PP .C /usr/sbin/acct/accton .RI [ \|file\| ] .PP .C /usr/sbin/acct/acctwtmp .I reason .PP .C /usr/sbin/acct/closewtmp .PP .C /usr/sbin/acct/utmp2wtmp .SH DESCRIPTION Accounting software is structured as a set of tools (consisting of both C programs and shell procedures) that can be used to build accounting systems. The shell procedures, described in .IR acctsh (1M), are built on top of the C programs. .PP Connect time accounting is handled by various programs that write records into .CR /etc/utmp , as described in .IR utmp (4). The programs described in .IR acctcon (1M) convert this file into session and charging records which are then summarized by .C acctmerg (see .IR acctmerg (1M)). .PP Process accounting is performed by the .SM HP-UX system kernel. Upon termination of a process, one record per process is written to a file (normally .CR /var/adm/pacct ). The programs in .IR acctprc (1M) summarize this data for charging purposes; .C acctcms is used to summarize command usage (see .IR acctcms (1M)). Current process data can be examined using .C acctcom (see .IR acctcom (1M)). .PP Process accounting and connect time accounting (or any accounting records in the format described in .IR acct (4)) can be merged and summarized into total accounting records by .C acctmerg (see .C tacct format in .IR acct (4)). .C prtacct is used to format any or all accounting records (see .IR acctsh (1M)). .PP .C acctdisk reads lines that contain user .SM ID, login name, and number of disk blocks, and converts them to total accounting records that can be merged with other accounting records. .PP .C acctdusg reads its standard input (usually from .CR "find -print" ) and computes disk resource consumption (including indirect blocks) by login. Only files found under login directories (as determined from the password file) are accounted for. All files under a login directory are assumed to belong to that user regardless of actual owner. If .C -u is given, records consisting of those file names for which .C acctdusg charges no one are placed in .I file (a potential source for finding users trying to avoid disk charges). If .C -p is given, .I file is the name of the password file. This option is not needed if the password file is .CR /etc/passwd . (See .IR diskusg (1M) for more details.) .PP .C accton turns process accounting off if the optional .I file argument is omitted. If .I file is given, it must be the name of an existing file, to which the kernel appends process accounting records (see .IR acct (2) and .IR acct (4)). .PP .C acctwtmp writes a .IR utmp (4) record to its standard output. The record contains the current time and a string of characters that describe the .I reason for writing the record. A record type of .SM ACCOUNTING is assigned (see .IR utmp (4)). The string argument .I reason must be 11 or fewer characters, numbers, .CR $ , or spaces. For example, the following are suggestions for use in reboot and shutdown procedures, respectively: .IP .C "acctwtmp `uname` >> /var/adm/wtmp" .IP .C "acctwtmp ""file save"" >> /var/adm/wtmp .PP .C closewtmp writes a .SM DEAD_PROCESS record, for each user currently logged in, to the file .CR /var/adm/wtmp . This program is invoked by .I runacct to close the existing .C wtmp file before creating a new one. .PP .C utmp2wtmp writes a .SM USER_PROCESS record, for each user currently logged in, to the file .CR /var/adm/wtmp . This program is invoked by .I runacct to initialize the newly created .C wtmp file. .SH FILES .TP 30 .C /usr/sbin/acct Holds all accounting commands listed in section (1M) of this manual. .TP .C /var/adm/pacct Current process accounting file. .TP .C /etc/passwd Used for converting login name to user. .SM ID .TP .C /var/adm/wtmp Login/logoff history file. .SH SEE ALSO acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), acctsh(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .PP System Accounting topics in .I HP-UX System Administrator manuals. .SH STANDARDS CONFORMANCE .CR acctdisk ": SVID2, SVID3" .PP .CR accton ": SVID2, SVID3" .PP .CR acctwtmp ": SVID2, SVID3" .\" .\" index@accounting: \f4acctdisk\f1 \- create disk usage accounting records@@@\f3acct(1M)\f1 .\" index@accounting: \f4acctdusg\f1 \- compute disk usage by login name@@@\f3acct(1M)\f1 .\" index@accounting: \f4accton\f1 \- define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@accounting: \f4acctwtmp\f1 \- write \f4utmp\f1 record and reason for writing@@@\f3acct(1M)\f1 .\" index@\f4acctdisk\f1 \- create disk usage accounting records@@@\f3acct(1M)\f1 .\" index@\f4acctdusg\f1 \- compute disk usage by login name@@@\f3acct(1M)\f1 .\" index@\f4accton\f1 \- define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@\f4acctwtmp\f1 \- write \f4utmp\f1 record and reason for writing@@@\f3acct(1M)\f1 .\" index@disk usage accounting records, create@@@\f3acct(1M)\f1 .\" index@disk usage by login name, compute@@@\f3acct(1M)\f1 .\" index@define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@disable accounting or define kernel process accounting output file@@@\f3acct(1M)\f1 .\" index@\f4utmp\f1 record, write and include reason for writing@@@\f3acct(1M)\f1 .\" .\" toc@\f3acct(1M)\f1:\0\0\f4acctdisk\f1, \f4acctdusg\f1, \f4accton\f1,\n\f4acctwtmp\f1@@@overview of accounting and miscellaneous accounting commands .\" toc@\f4acctdisk\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4acctdusg\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4accton\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4acctwtmp\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" .\" links@acct.1m acctdisk.1m .\" links@acct.1m acctdusg.1m .\" links@acct.1m accton.1m .\" links@acct.1m acctwtmp.1m .\" links@acct.1m closewtmp.1m .\" links@acct.1m utmp2wtmp.1m .\" .\" fileset_database@acct.1m SYS-ADMIN-MAN .\" $Header: acctcms.1m,v 72.5 94/11/14 12:00:55 ssa Exp $ .TA a .TH acctcms 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctcms \- command summary from per-process accounting records .SH SYNOPSIS .C /usr/sbin/acct/acctcms .RI [ \|options\| ] .I files .SH DESCRIPTION .C acctcms reads one or more .IR files , normally in the form described in .IR acct (4). It adds all records for processes that executed identically-named commands, sorts them, and writes them to the standard output, normally using an internal summary format. .SS Options .C acctcms recognizes the following options: .RS .TP 8 .C -a Print output in .SM ASCII rather than in the internal summary format. The output includes command name, number of times executed, total kcore-minutes, total .SM CPU minutes, total real minutes, mean size (in K), mean .SM CPU minutes per invocation, ``hog factor'', characters transferred, and blocks read and written, as in .IR acctcom (1M). Output is normally sorted by total kcore-minutes. .TP .C -c Sort by total .SM CPU time, rather than total kcore-minutes. .TP .C -j Combine all commands invoked only once under .CR ***other . .TP .C -n Sort by number of command invocations. .TP .C -s Any file names encountered hereafter are already in internal summary format. .TP .C -t Process all records as total accounting records. The default internal summary format splits each field into prime- and non-prime-time parts. This option combines the prime and non-prime time parts into a single field that is the total of both, and provides upward compatibility with old (i.e., .SM UNIX System V) style .C acctcms internal summary format records. .RE .PP The following options can be used only with the .C -a option. .RS .TP 8 .C -p Output a prime-time-only command summary. .TP .C -o Output a non-prime- (offshift) time only command summary. .RE .PP When .C -p and .C -o are used together, a combination prime and non-prime time report is produced. All the output summaries are total usage except number of times executed, .SM CPU minutes, and real minutes which are split into prime and non-prime. .SH EXAMPLES A typical sequence for performing daily command accounting and for maintaining a running total is: .nf .IP .CI acctcms " ile ... " >today .C cp total previoustotal .C acctcms -s today previoustotal >total .C acctcms -a -s today .fi .SH SEE ALSO acct(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), acctsh(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH WARNINGS Unpredictable output results if .C -t is used on new-style internal-summary-format files, or if it is not used with old style internal summary format files. .SH STANDARDS CONFORMANCE .CR acctcms ": SVID2, SVID3" .\" .\" index@\f4acctcms\f1 \- command summary from per-process accounting records@@@\f3acctcms(1M)\f1 .\" index@accounting: \f4acctcms\f1 \- command summary from per-process accounting records@@@\f3acctcms(1M)\f1 .\" index@command summary from per-process accounting records@@@\f3acctcms(1M)\f1 .\" index@accounting records, per-process, command summary from@@@\f3acctcms(1M)\f1 .\" .\" toc@\f3acctcms(1M)\f1:\0\0\f4acctcms\f1@@@command summary from per-process accounting records .\" .\" fileset_database@acctcms.1m SYS-ADMIN-MAN .\" $Header: acctcom.1m,v 72.6 94/12/08 12:12:22 ssa Exp $ .TA a .TH acctcom 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctcom \- search and print process accounting files .SH SYNOPSIS .CR /usr/sbin/acct/acctcom .RI [\|[ option ]...\0[ file ]\|]\0... .SH DESCRIPTION The .CR acctcom command reads .IR file , standard input, or .CR /var/adm/pacct , in the form described in .IR acct (4) and writes selected records to standard output. Each record represents the execution of one process. The output has the following column titles: .RS .TP 20 .PD 0 .CR "COMMAND NAME" .TP .CR "USER .TP .CR "TTYNAME .TP .CR "START TIME" .TP .CR "END TIME" .TP .CR "REAL (SECS)" .TP .CR "CPU (SECS)" .TP .CR "MEAN SIZE(K)" .PD .RE .PP Optionally, the following can be displayed: .RS .TP 20 .PD 0 .CR "F" .CR fork() / exec() flag: .CR 1 for .CR fork() without .CR exec() .TP .CR "STAT" System exit status .TP .CR "HOG FACTOR" .TP .CR "KCORE MIN" .TP .CR "CPU FACTOR" .TP .CR "CHARS TRNSFD" .TP .CR "BLOCKS READ" Total blocks read and written .TP .CR "PRMID" PRM process resource group ID .PD .RE .PP The command name is preceded by a .CR # if superuser privileges were .IR required to executed the command. .PP For example, if a user is logged in as .CR root , and executes the .CR date command to check the time, this does not require superuser privileges, and will be shown by .CR acctcom without the .CR # character on the line. If the user executes the command .CR "date 0731180092" to set the time, this requires superuser privileges, and so will be marked with a .CR # by .CR acctcom . .PP If a process is not associated with a known terminal, a .CR ? is printed in the .CR TTYNAME field. .PP The system exit status .CR STAT is .CR 0 if the process terminated by calling .CR exit . If it is not .CR 0 , it is the signal number that caused the process to terminate. If a core file image was produced as a result of the signal (see .IR signal (5)), the value is the signal number plus .CR 0200 . .PP If no .I files are specified, and if standard input is associated with a terminal or .CR /dev/null (as is the case when using .CR & in a shell), .CR acctcom reads .CR /var/adm/pacct . Otherwise, it reads standard input. .PP If any .I file arguments are given, they are read in their respective order. Each file is normally read forward, that is, in chronological order by process-completion time. The file .CR /var/adm/pacct is usually the current file to be examined. A busy system may need several such files of which all but the current file are found in .CI /var/adm/pacct ?\f1. .SS Options .CR acctcom recognizes the following values for the .I option argument. Listing options together has the effect of a logical AND. .RS .TP 15 .CR \-a Show some average statistics about the processes selected. Statistics are printed after the output records. .TP .CR \-b Read backwards, showing latest commands first. This option has no effect when standard input is read. .TP .CR \-f Print in octal the .CR F flag and system exit status columns in the output. .TP .CR \-h Instead of mean memory size, .CR "MEAN SIZE(K)" , show the fraction of total available CPU time consumed by the process during its execution. This .CR "HOG FACTOR" is computed as: .RS .IP .IC total-CPU-time / elapsed-time .RE .TP .CR \-i Print columns containing the I/O counts in the output. .TP .CR \-k Instead of memory size, show total kcore-minutes. .TP .CR \-m Show mean core size (the default). .TP .CR \-P Show the PRM process resource group ID .RC ( PRMID ) of each process. See DEPENDENCIES. .TP .CR \-r Show CPU factor: .RS .IP .IC user-time /( system-time + user-time ) .RE .TP .CR \-t Show separate system and user CPU times. .TP .CR \-v Exclude column headings from the output. .TP .CI \-l \0line Show only processes belonging to terminal .CI /dev/ line\f1. .TP .CI \-u \0user Show only processes belonging to .IR user , specified as: a user ID, a login name that is then converted to a user ID, a .CR # which designates only those processes executed with superuser privileges, or .CR ? which designates only those processes associated with unknown user IDs. .TP .CI \-g \0group Show only processes belonging to .IR group , specified as either the group ID or group name. .TP .CI \-s \0time Select processes existing at or after .IR time , given in the format: .RS .IP .IC hour\f1[ : minute\f1[ : second\f1]\|] .RE .TP .CI \-e \0time Select processes existing at or before .IR time ; see .CR \-s . .IP Using the same .I time for both .CR \-s and .CR \-e shows the processes that existed at .IR time ; see .CR \-s . .TP .CI \-S \0time Select processes starting at or after .IR time ; see .CR \-s . .TP .CI \-E \0time Select processes ending at or before .IR time ; see .CR \-s . .TP .CI \-n \0pattern Show only commands matching .IR pattern , where .I pattern is a regular expression as in .IR ed (1) except that .CR + means one or more occurrences. .TP .CR \-q Do not print any output records. Just print the average statistics as with the .CR \-a option. .TP .CI \-o \0ofile Copy selected process records in the input data format to .IR ofile . Suppress standard output printing. .TP .CI \-H \0factor Show only processes that exceed .IR factor , where .I factor is the "hog factor" as explained in option .CR \-h . .TP .CI \-O \0time Show only those processes with operating system CPU time exceeding .IR time ; see .CR \-s . .TP .CI \-C \0sec Show only processes with total CPU time, system plus user, exceeding .I sec seconds. .TP .CI \-I \0chars Show only processes transferring more characters than the cut-off number given by .IR chars . .TP .CI \-R \0prmgroup Show only processes belonging to process resource group .IR prmgroup , specified as either process resource group name or ID number. See DEPENDENCIES. .RE .SH WARNINGS .CR acctcom only reports on processes that have terminated. For active processes, use the .CR ps command (see .IR ps (1)). .PP If .I time exceeds the current system clock time, .I time is interpreted as occurring on the previous day. .PP The accounting flag is not cleared when one processes exec's another, but only when one process forks another. One side-effect of this is that some processes will be marked with .CR # , when users don't expect them to be. .PP For example, the .CR login command uses superuser privileges to assume the identity of the user who is logging-in, setting the ASU bit in the accounting flag (which ultimately causes the .CR # symbol in the .CR acctcom output). After assuming the user's identity, .CR login exec's the user's shell. Since the exec does not clear the ASU flag, the shell will inherit it, and be marked with a .CR # in the .CR acctcom output. .SH DEPENDENCIES .SS HP Process Resource Manager The .CR \-P and .CR \-R options require the optional HP Process Resource Manager (PRM) software to be installed and configured. See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for the definition of process resource group. .SH FILES .nf .CR /etc/group .CR /etc/passwd .CR /var/adm/pacct .fi .SH SEE ALSO ps(1), su(1), acct(1M), acctcms(1M), acctcon(1M), acctmerg(1M), acctprc(1M), acctsh(1M), fwtmp(1M), runacct(1M), acct(2), wait(2), acct(4), utmp(4), signal(5). .PP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR acctcom ": SVID2, SVID3" .\" .\" index@\f4acctcom\f1 \- search and print process accounting files@@@\f3acctcom(1M)\f1 .\" index@\f1accounting files, search and print@@@\f3acctcom(1M)\f1 .\" index@\f1files, accounting, search and print@@@\f3acctcom(1M)\f1 .\" index@\f1print process accounting files@@@\f3acctcom(1M)\f1 .\" index@\f1process accounting files, search and print@@@\f3acctcom(1M)\f1 .\" index@\f1search and print process accounting files@@@\f3acctcom(1M)\f1 .\" index@\f1PRM@@@\f2see \f1Process Resource Manager .\" index@\f1Process Resource Manager@@@\f3acctcom(1M)\f1 .\" .\" toc@\f3acctcom(1M)\f1:\0\0\f4acctcom\f1@@@search and print process accounting files .\" $Header: acctcon.1m,v 72.5 94/11/14 12:01:23 ssa Exp $ .TA a .TH acctcon 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctcon, acctcon1, acctcon2 \- connect-time accounting .SH SYNOPSIS .C /usr/sbin/acct/acctcon .RI [ \|options\| ] .PP .C /usr/sbin/acct/acctcon1 .RI [ \|options\| ] .PP .C /usr/sbin/acct/acctcon2 .SH DESCRIPTION The .CR acctcon1 command converts a sequence of login/logoff records read from its standard input to a sequence of records, one per login session. Its input should normally be redirected from .CR /var/adm/wtmp . Its output is .SM ASCII, giving device, user .SM ID, login name, prime connect time (seconds), non-prime connect time (seconds), session starting time (numeric), and starting date and time. Prime connect time is defined as the connect time within a specific prime period on a non-holiday weekday (Monday through Friday). The starting and ending time of the prime period and the year's holidays are defined in file .CR /etc/acct/holidays . .PP .CR acctcon2 expects as input a sequence of login session records, produced by .CR acctcon1 , and converts them into total accounting records (see .CR tacct format in .IR acct (4)). .PP .CR acctcon combines the functionality of .CR acctcon1 and .CR acctcon2 into one program. It takes the same input format as .CR acctcon1 and writes the same output as .CR acctcon2. .PP .CR acctcon1 recognizes the following .IR options : .RS .TP 15 .C -p Print input only, showing line name, login name, and time (in both numeric and date/time formats). .TP .C -t .C acctcon1 maintains a list of lines on which users are logged in. When it reaches the end of its input, it emits a session record for each line that still appears to be active. It normally assumes that its input is a current file, so that it uses the current time as the ending time for each session still in progress. The .CR -t flag causes it to use, instead, the last time found in its input, thus ensuring reasonable and repeatable numbers for non-current files. .RE .PP .C acctcon1 and .CR acctcon recognize the following .IR options : .RS .TP 15 .CI -l \0file .I file is created to contain a summary of line usage showing line name, number of minutes used, percentage of total elapsed time used, number of sessions charged, number of logins, and number of logoffs. This file helps track line usage, identify bad lines, and find software and hardware oddities. Hang-up, termination of .CR login (see .IR login (1)), and termination of the login shell each generate logoff records, so that the number of logoffs is often three to four times the number of sessions. See .IR init (1M) and .IR utmp (4). .TP .CI -o \0file .I file is filled with an overall record for the accounting period, giving starting time, ending time, number of reboots, and number of date changes. .RE .SH EXAMPLES These commands are typically used as shown below. The file .CR ctmp is created only for the use of commands described by the .IR acctprc (1M) manual entry: .IP .C "acctcon1 -t -l lineuse -o reboots < wtmp | sort +1n +2 > ctmp" .br .C "acctcon2 < ctmp | acctmerg > ctacct" .RE .PP or .IP .C "acctcon -t -l lineuse -o reboots < wtmp | acctmerg > ctacct" .SH FILES .C /var/adm/wtmp .br .C /etc/acct/holidays .SH WARNINGS The line usage report is confused by date changes. Use .CR wtmpfix (see .IR fwtmp (1M)) to correct this situation. .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctmerg(1M), acctprc(1M), acctsh(1M), fwtmp(1M), init(1M), login(1), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR acctcon1 ": SVID2, SVID3" .PP .CR acctcon2 ": SVID2, SVID3" .\" .\" index@\f2acctcon1\f1 \- convert login/logoff records to per-session accounting records@@@\f3acctcon(1M)\f1 .\" index@\f2acctcon2\f1 \- convert per-session records to total accounting records@@@\f3acctcon(1M)\f1 .\" index@accounting: \f2acctcon1\f1 \- convert login/logoff records to per-session accounting records@@@\f3acctcon(1M)\f1 .\" index@accounting: \f2acctcon2\f1 \- convert per-session records to total accounting records@@@\f3acctcon(1M)\f1 .\" index@convert login/logoff records to per-session accounting records@@@\f3acctcon(1M)\f1 .\" index@login/logoff records, convert to per-session accounting records@@@\f3acctcon(1M)\f1 .\" index@per-session accounting records, convert login/logoff records to@@@\f3acctcon(1M)\f1 .\" index@convert per-session records to total accounting records@@@\f3acctcon(1M)\f1 .\" index@per-session records, convert to total accounting records@@@\f3acctcon(1M)\f1 .\" index@total accounting records, convert per-session records to@@@\f3acctcon(1M)\f1 .\" .\" toc@\f3acctcon(1M)\f1:\0\0\f2acctcon1\f1, \f2acctcon2\f1@@@connect-time accounting .\" toc@\f2acctcon1\f1:\0\0connect-time accounting@@@see \f3acctcon(1M)\f1 .\" toc@\f2acctcon2\f1:\0\0connect-time accounting@@@see \f3acctcon(1M)\f1 .\" .\" links@acctcon.1m acctcon1.1m .\" links@acctcon.1m acctcon2.1m .\" .\" fileset_database@acctcon.1m SYS-ADMIN-MAN .\" $Header: acctcon.1m,v 72.5 94/11/14 12:01:23 ssa Exp $ .TA a .TH acctcon 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctcon, acctcon1, acctcon2 \- connect-time accounting .SH SYNOPSIS .C /usr/sbin/acct/acctcon .RI [ \|options\| ] .PP .C /usr/sbin/acct/acctcon1 .RI [ \|options\| ] .PP .C /usr/sbin/acct/acctcon2 .SH DESCRIPTION The .CR acctcon1 command converts a sequence of login/logoff records read from its standard input to a sequence of records, one per login session. Its input should normally be redirected from .CR /var/adm/wtmp . Its output is .SM ASCII, giving device, user .SM ID, login name, prime connect time (seconds), non-prime connect time (seconds), session starting time (numeric), and starting date and time. Prime connect time is defined as the connect time within a specific prime period on a non-holiday weekday (Monday through Friday). The starting and ending time of the prime period and the year's holidays are defined in file .CR /etc/acct/holidays . .PP .CR acctcon2 expects as input a sequence of login session records, produced by .CR acctcon1 , and converts them into total accounting records (see .CR tacct format in .IR acct (4)). .PP .CR acctcon combines the functionality of .CR acctcon1 and .CR acctcon2 into one program. It takes the same input format as .CR acctcon1 and writes the same output as .CR acctcon2. .PP .CR acctcon1 recognizes the following .IR options : .RS .TP 15 .C -p Print input only, showing line name, login name, and time (in both numeric and date/time formats). .TP .C -t .C acctcon1 maintains a list of lines on which users are logged in. When it reaches the end of its input, it emits a session record for each line that still appears to be active. It normally assumes that its input is a current file, so that it uses the current time as the ending time for each session still in progress. The .CR -t flag causes it to use, instead, the last time found in its input, thus ensuring reasonable and repeatable numbers for non-current files. .RE .PP .C acctcon1 and .CR acctcon recognize the following .IR options : .RS .TP 15 .CI -l \0file .I file is created to contain a summary of line usage showing line name, number of minutes used, percentage of total elapsed time used, number of sessions charged, number of logins, and number of logoffs. This file helps track line usage, identify bad lines, and find software and hardware oddities. Hang-up, termination of .CR login (see .IR login (1)), and termination of the login shell each generate logoff records, so that the number of logoffs is often three to four times the number of sessions. See .IR init (1M) and .IR utmp (4). .TP .CI -o \0file .I file is filled with an overall record for the accounting period, giving starting time, ending time, number of reboots, and number of date changes. .RE .SH EXAMPLES These commands are typically used as shown below. The file .CR ctmp is created only for the use of commands described by the .IR acctprc (1M) manual entry: .IP .C "acctcon1 -t -l lineuse -o reboots < wtmp | sort +1n +2 > ctmp" .br .C "acctcon2 < ctmp | acctmerg > ctacct" .RE .PP or .IP .C "acctcon -t -l lineuse -o reboots < wtmp | acctmerg > ctacct" .SH FILES .C /var/adm/wtmp .br .C /etc/acct/holidays .SH WARNINGS The line usage report is confused by date changes. Use .CR wtmpfix (see .IR fwtmp (1M)) to correct this situation. .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctmerg(1M), acctprc(1M), acctsh(1M), fwtmp(1M), init(1M), login(1), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR acctcon1 ": SVID2, SVID3" .PP .CR acctcon2 ": SVID2, SVID3" .\" .\" index@\f2acctcon1\f1 \- convert login/logoff records to per-session accounting records@@@\f3acctcon(1M)\f1 .\" index@\f2acctcon2\f1 \- convert per-session records to total accounting records@@@\f3acctcon(1M)\f1 .\" index@accounting: \f2acctcon1\f1 \- convert login/logoff records to per-session accounting records@@@\f3acctcon(1M)\f1 .\" index@accounting: \f2acctcon2\f1 \- convert per-session records to total accounting records@@@\f3acctcon(1M)\f1 .\" index@convert login/logoff records to per-session accounting records@@@\f3acctcon(1M)\f1 .\" index@login/logoff records, convert to per-session accounting records@@@\f3acctcon(1M)\f1 .\" index@per-session accounting records, convert login/logoff records to@@@\f3acctcon(1M)\f1 .\" index@convert per-session records to total accounting records@@@\f3acctcon(1M)\f1 .\" index@per-session records, convert to total accounting records@@@\f3acctcon(1M)\f1 .\" index@total accounting records, convert per-session records to@@@\f3acctcon(1M)\f1 .\" .\" toc@\f3acctcon(1M)\f1:\0\0\f2acctcon1\f1, \f2acctcon2\f1@@@connect-time accounting .\" toc@\f2acctcon1\f1:\0\0connect-time accounting@@@see \f3acctcon(1M)\f1 .\" toc@\f2acctcon2\f1:\0\0connect-time accounting@@@see \f3acctcon(1M)\f1 .\" .\" links@acctcon.1m acctcon1.1m .\" links@acctcon.1m acctcon2.1m .\" .\" fileset_database@acctcon.1m SYS-ADMIN-MAN .\" $Header: acctcon.1m,v 72.5 94/11/14 12:01:23 ssa Exp $ .TA a .TH acctcon 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctcon, acctcon1, acctcon2 \- connect-time accounting .SH SYNOPSIS .C /usr/sbin/acct/acctcon .RI [ \|options\| ] .PP .C /usr/sbin/acct/acctcon1 .RI [ \|options\| ] .PP .C /usr/sbin/acct/acctcon2 .SH DESCRIPTION The .CR acctcon1 command converts a sequence of login/logoff records read from its standard input to a sequence of records, one per login session. Its input should normally be redirected from .CR /var/adm/wtmp . Its output is .SM ASCII, giving device, user .SM ID, login name, prime connect time (seconds), non-prime connect time (seconds), session starting time (numeric), and starting date and time. Prime connect time is defined as the connect time within a specific prime period on a non-holiday weekday (Monday through Friday). The starting and ending time of the prime period and the year's holidays are defined in file .CR /etc/acct/holidays . .PP .CR acctcon2 expects as input a sequence of login session records, produced by .CR acctcon1 , and converts them into total accounting records (see .CR tacct format in .IR acct (4)). .PP .CR acctcon combines the functionality of .CR acctcon1 and .CR acctcon2 into one program. It takes the same input format as .CR acctcon1 and writes the same output as .CR acctcon2. .PP .CR acctcon1 recognizes the following .IR options : .RS .TP 15 .C -p Print input only, showing line name, login name, and time (in both numeric and date/time formats). .TP .C -t .C acctcon1 maintains a list of lines on which users are logged in. When it reaches the end of its input, it emits a session record for each line that still appears to be active. It normally assumes that its input is a current file, so that it uses the current time as the ending time for each session still in progress. The .CR -t flag causes it to use, instead, the last time found in its input, thus ensuring reasonable and repeatable numbers for non-current files. .RE .PP .C acctcon1 and .CR acctcon recognize the following .IR options : .RS .TP 15 .CI -l \0file .I file is created to contain a summary of line usage showing line name, number of minutes used, percentage of total elapsed time used, number of sessions charged, number of logins, and number of logoffs. This file helps track line usage, identify bad lines, and find software and hardware oddities. Hang-up, termination of .CR login (see .IR login (1)), and termination of the login shell each generate logoff records, so that the number of logoffs is often three to four times the number of sessions. See .IR init (1M) and .IR utmp (4). .TP .CI -o \0file .I file is filled with an overall record for the accounting period, giving starting time, ending time, number of reboots, and number of date changes. .RE .SH EXAMPLES These commands are typically used as shown below. The file .CR ctmp is created only for the use of commands described by the .IR acctprc (1M) manual entry: .IP .C "acctcon1 -t -l lineuse -o reboots < wtmp | sort +1n +2 > ctmp" .br .C "acctcon2 < ctmp | acctmerg > ctacct" .RE .PP or .IP .C "acctcon -t -l lineuse -o reboots < wtmp | acctmerg > ctacct" .SH FILES .C /var/adm/wtmp .br .C /etc/acct/holidays .SH WARNINGS The line usage report is confused by date changes. Use .CR wtmpfix (see .IR fwtmp (1M)) to correct this situation. .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctmerg(1M), acctprc(1M), acctsh(1M), fwtmp(1M), init(1M), login(1), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR acctcon1 ": SVID2, SVID3" .PP .CR acctcon2 ": SVID2, SVID3" .\" .\" index@\f2acctcon1\f1 \- convert login/logoff records to per-session accounting records@@@\f3acctcon(1M)\f1 .\" index@\f2acctcon2\f1 \- convert per-session records to total accounting records@@@\f3acctcon(1M)\f1 .\" index@accounting: \f2acctcon1\f1 \- convert login/logoff records to per-session accounting records@@@\f3acctcon(1M)\f1 .\" index@accounting: \f2acctcon2\f1 \- convert per-session records to total accounting records@@@\f3acctcon(1M)\f1 .\" index@convert login/logoff records to per-session accounting records@@@\f3acctcon(1M)\f1 .\" index@login/logoff records, convert to per-session accounting records@@@\f3acctcon(1M)\f1 .\" index@per-session accounting records, convert login/logoff records to@@@\f3acctcon(1M)\f1 .\" index@convert per-session records to total accounting records@@@\f3acctcon(1M)\f1 .\" index@per-session records, convert to total accounting records@@@\f3acctcon(1M)\f1 .\" index@total accounting records, convert per-session records to@@@\f3acctcon(1M)\f1 .\" .\" toc@\f3acctcon(1M)\f1:\0\0\f2acctcon1\f1, \f2acctcon2\f1@@@connect-time accounting .\" toc@\f2acctcon1\f1:\0\0connect-time accounting@@@see \f3acctcon(1M)\f1 .\" toc@\f2acctcon2\f1:\0\0connect-time accounting@@@see \f3acctcon(1M)\f1 .\" .\" links@acctcon.1m acctcon1.1m .\" links@acctcon.1m acctcon2.1m .\" .\" fileset_database@acctcon.1m SYS-ADMIN-MAN .\" $Header: acct.1m,v 72.5 94/11/14 12:00:17 ssa Exp $ .TA a .TH acct 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctdisk, acctdusg, accton, acctwtmp, closewtmp, utmp2wtmp \- overview of accounting and miscellaneous accounting commands .SH SYNOPSIS .C /usr/sbin/acct/acctdisk .PP .C /usr/sbin/acct/acctdusg .RC [ -u .IR file\| ] .RC [ -p .IR file\| ] .PP .C /usr/sbin/acct/accton .RI [ \|file\| ] .PP .C /usr/sbin/acct/acctwtmp .I reason .PP .C /usr/sbin/acct/closewtmp .PP .C /usr/sbin/acct/utmp2wtmp .SH DESCRIPTION Accounting software is structured as a set of tools (consisting of both C programs and shell procedures) that can be used to build accounting systems. The shell procedures, described in .IR acctsh (1M), are built on top of the C programs. .PP Connect time accounting is handled by various programs that write records into .CR /etc/utmp , as described in .IR utmp (4). The programs described in .IR acctcon (1M) convert this file into session and charging records which are then summarized by .C acctmerg (see .IR acctmerg (1M)). .PP Process accounting is performed by the .SM HP-UX system kernel. Upon termination of a process, one record per process is written to a file (normally .CR /var/adm/pacct ). The programs in .IR acctprc (1M) summarize this data for charging purposes; .C acctcms is used to summarize command usage (see .IR acctcms (1M)). Current process data can be examined using .C acctcom (see .IR acctcom (1M)). .PP Process accounting and connect time accounting (or any accounting records in the format described in .IR acct (4)) can be merged and summarized into total accounting records by .C acctmerg (see .C tacct format in .IR acct (4)). .C prtacct is used to format any or all accounting records (see .IR acctsh (1M)). .PP .C acctdisk reads lines that contain user .SM ID, login name, and number of disk blocks, and converts them to total accounting records that can be merged with other accounting records. .PP .C acctdusg reads its standard input (usually from .CR "find -print" ) and computes disk resource consumption (including indirect blocks) by login. Only files found under login directories (as determined from the password file) are accounted for. All files under a login directory are assumed to belong to that user regardless of actual owner. If .C -u is given, records consisting of those file names for which .C acctdusg charges no one are placed in .I file (a potential source for finding users trying to avoid disk charges). If .C -p is given, .I file is the name of the password file. This option is not needed if the password file is .CR /etc/passwd . (See .IR diskusg (1M) for more details.) .PP .C accton turns process accounting off if the optional .I file argument is omitted. If .I file is given, it must be the name of an existing file, to which the kernel appends process accounting records (see .IR acct (2) and .IR acct (4)). .PP .C acctwtmp writes a .IR utmp (4) record to its standard output. The record contains the current time and a string of characters that describe the .I reason for writing the record. A record type of .SM ACCOUNTING is assigned (see .IR utmp (4)). The string argument .I reason must be 11 or fewer characters, numbers, .CR $ , or spaces. For example, the following are suggestions for use in reboot and shutdown procedures, respectively: .IP .C "acctwtmp `uname` >> /var/adm/wtmp" .IP .C "acctwtmp ""file save"" >> /var/adm/wtmp .PP .C closewtmp writes a .SM DEAD_PROCESS record, for each user currently logged in, to the file .CR /var/adm/wtmp . This program is invoked by .I runacct to close the existing .C wtmp file before creating a new one. .PP .C utmp2wtmp writes a .SM USER_PROCESS record, for each user currently logged in, to the file .CR /var/adm/wtmp . This program is invoked by .I runacct to initialize the newly created .C wtmp file. .SH FILES .TP 30 .C /usr/sbin/acct Holds all accounting commands listed in section (1M) of this manual. .TP .C /var/adm/pacct Current process accounting file. .TP .C /etc/passwd Used for converting login name to user. .SM ID .TP .C /var/adm/wtmp Login/logoff history file. .SH SEE ALSO acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), acctsh(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .PP System Accounting topics in .I HP-UX System Administrator manuals. .SH STANDARDS CONFORMANCE .CR acctdisk ": SVID2, SVID3" .PP .CR accton ": SVID2, SVID3" .PP .CR acctwtmp ": SVID2, SVID3" .\" .\" index@accounting: \f4acctdisk\f1 \- create disk usage accounting records@@@\f3acct(1M)\f1 .\" index@accounting: \f4acctdusg\f1 \- compute disk usage by login name@@@\f3acct(1M)\f1 .\" index@accounting: \f4accton\f1 \- define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@accounting: \f4acctwtmp\f1 \- write \f4utmp\f1 record and reason for writing@@@\f3acct(1M)\f1 .\" index@\f4acctdisk\f1 \- create disk usage accounting records@@@\f3acct(1M)\f1 .\" index@\f4acctdusg\f1 \- compute disk usage by login name@@@\f3acct(1M)\f1 .\" index@\f4accton\f1 \- define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@\f4acctwtmp\f1 \- write \f4utmp\f1 record and reason for writing@@@\f3acct(1M)\f1 .\" index@disk usage accounting records, create@@@\f3acct(1M)\f1 .\" index@disk usage by login name, compute@@@\f3acct(1M)\f1 .\" index@define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@disable accounting or define kernel process accounting output file@@@\f3acct(1M)\f1 .\" index@\f4utmp\f1 record, write and include reason for writing@@@\f3acct(1M)\f1 .\" .\" toc@\f3acct(1M)\f1:\0\0\f4acctdisk\f1, \f4acctdusg\f1, \f4accton\f1,\n\f4acctwtmp\f1@@@overview of accounting and miscellaneous accounting commands .\" toc@\f4acctdisk\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4acctdusg\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4accton\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4acctwtmp\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" .\" links@acct.1m acctdisk.1m .\" links@acct.1m acctdusg.1m .\" links@acct.1m accton.1m .\" links@acct.1m acctwtmp.1m .\" links@acct.1m closewtmp.1m .\" links@acct.1m utmp2wtmp.1m .\" .\" fileset_database@acct.1m SYS-ADMIN-MAN .\" $Header: acct.1m,v 72.5 94/11/14 12:00:17 ssa Exp $ .TA a .TH acct 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctdisk, acctdusg, accton, acctwtmp, closewtmp, utmp2wtmp \- overview of accounting and miscellaneous accounting commands .SH SYNOPSIS .C /usr/sbin/acct/acctdisk .PP .C /usr/sbin/acct/acctdusg .RC [ -u .IR file\| ] .RC [ -p .IR file\| ] .PP .C /usr/sbin/acct/accton .RI [ \|file\| ] .PP .C /usr/sbin/acct/acctwtmp .I reason .PP .C /usr/sbin/acct/closewtmp .PP .C /usr/sbin/acct/utmp2wtmp .SH DESCRIPTION Accounting software is structured as a set of tools (consisting of both C programs and shell procedures) that can be used to build accounting systems. The shell procedures, described in .IR acctsh (1M), are built on top of the C programs. .PP Connect time accounting is handled by various programs that write records into .CR /etc/utmp , as described in .IR utmp (4). The programs described in .IR acctcon (1M) convert this file into session and charging records which are then summarized by .C acctmerg (see .IR acctmerg (1M)). .PP Process accounting is performed by the .SM HP-UX system kernel. Upon termination of a process, one record per process is written to a file (normally .CR /var/adm/pacct ). The programs in .IR acctprc (1M) summarize this data for charging purposes; .C acctcms is used to summarize command usage (see .IR acctcms (1M)). Current process data can be examined using .C acctcom (see .IR acctcom (1M)). .PP Process accounting and connect time accounting (or any accounting records in the format described in .IR acct (4)) can be merged and summarized into total accounting records by .C acctmerg (see .C tacct format in .IR acct (4)). .C prtacct is used to format any or all accounting records (see .IR acctsh (1M)). .PP .C acctdisk reads lines that contain user .SM ID, login name, and number of disk blocks, and converts them to total accounting records that can be merged with other accounting records. .PP .C acctdusg reads its standard input (usually from .CR "find -print" ) and computes disk resource consumption (including indirect blocks) by login. Only files found under login directories (as determined from the password file) are accounted for. All files under a login directory are assumed to belong to that user regardless of actual owner. If .C -u is given, records consisting of those file names for which .C acctdusg charges no one are placed in .I file (a potential source for finding users trying to avoid disk charges). If .C -p is given, .I file is the name of the password file. This option is not needed if the password file is .CR /etc/passwd . (See .IR diskusg (1M) for more details.) .PP .C accton turns process accounting off if the optional .I file argument is omitted. If .I file is given, it must be the name of an existing file, to which the kernel appends process accounting records (see .IR acct (2) and .IR acct (4)). .PP .C acctwtmp writes a .IR utmp (4) record to its standard output. The record contains the current time and a string of characters that describe the .I reason for writing the record. A record type of .SM ACCOUNTING is assigned (see .IR utmp (4)). The string argument .I reason must be 11 or fewer characters, numbers, .CR $ , or spaces. For example, the following are suggestions for use in reboot and shutdown procedures, respectively: .IP .C "acctwtmp `uname` >> /var/adm/wtmp" .IP .C "acctwtmp ""file save"" >> /var/adm/wtmp .PP .C closewtmp writes a .SM DEAD_PROCESS record, for each user currently logged in, to the file .CR /var/adm/wtmp . This program is invoked by .I runacct to close the existing .C wtmp file before creating a new one. .PP .C utmp2wtmp writes a .SM USER_PROCESS record, for each user currently logged in, to the file .CR /var/adm/wtmp . This program is invoked by .I runacct to initialize the newly created .C wtmp file. .SH FILES .TP 30 .C /usr/sbin/acct Holds all accounting commands listed in section (1M) of this manual. .TP .C /var/adm/pacct Current process accounting file. .TP .C /etc/passwd Used for converting login name to user. .SM ID .TP .C /var/adm/wtmp Login/logoff history file. .SH SEE ALSO acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), acctsh(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .PP System Accounting topics in .I HP-UX System Administrator manuals. .SH STANDARDS CONFORMANCE .CR acctdisk ": SVID2, SVID3" .PP .CR accton ": SVID2, SVID3" .PP .CR acctwtmp ": SVID2, SVID3" .\" .\" index@accounting: \f4acctdisk\f1 \- create disk usage accounting records@@@\f3acct(1M)\f1 .\" index@accounting: \f4acctdusg\f1 \- compute disk usage by login name@@@\f3acct(1M)\f1 .\" index@accounting: \f4accton\f1 \- define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@accounting: \f4acctwtmp\f1 \- write \f4utmp\f1 record and reason for writing@@@\f3acct(1M)\f1 .\" index@\f4acctdisk\f1 \- create disk usage accounting records@@@\f3acct(1M)\f1 .\" index@\f4acctdusg\f1 \- compute disk usage by login name@@@\f3acct(1M)\f1 .\" index@\f4accton\f1 \- define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@\f4acctwtmp\f1 \- write \f4utmp\f1 record and reason for writing@@@\f3acct(1M)\f1 .\" index@disk usage accounting records, create@@@\f3acct(1M)\f1 .\" index@disk usage by login name, compute@@@\f3acct(1M)\f1 .\" index@define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@disable accounting or define kernel process accounting output file@@@\f3acct(1M)\f1 .\" index@\f4utmp\f1 record, write and include reason for writing@@@\f3acct(1M)\f1 .\" .\" toc@\f3acct(1M)\f1:\0\0\f4acctdisk\f1, \f4acctdusg\f1, \f4accton\f1,\n\f4acctwtmp\f1@@@overview of accounting and miscellaneous accounting commands .\" toc@\f4acctdisk\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4acctdusg\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4accton\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4acctwtmp\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" .\" links@acct.1m acctdisk.1m .\" links@acct.1m acctdusg.1m .\" links@acct.1m accton.1m .\" links@acct.1m acctwtmp.1m .\" links@acct.1m closewtmp.1m .\" links@acct.1m utmp2wtmp.1m .\" .\" fileset_database@acct.1m SYS-ADMIN-MAN .\" $Header: acctmerg.1m,v 72.5 94/11/14 12:01:40 ssa Exp $ .TA a .TH acctmerg 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctmerg \- merge or add total accounting files .SH SYNOPSIS .C /usr/sbin/acct/acctmerg .RI [ \|options\| ] .RI [ \|file\| ]\0... .SH DESCRIPTION .C acctmerg reads its standard input and up to nine additional files, all in the .C tacct format (see .IR acct (4)) or an .SM ASCII version thereof. It merges these inputs by adding records whose keys (normally user .SM ID and name) are identical, and expects the inputs to be sorted on those keys. .SS Options .C acctmerg recognizes the following options: .RS .TP 8 .C -a Produce output in .SM ASCII version of .CR tacct . .TP .C -i Input files are in .SM ASCII version of .CR tacct . .TP .C -p Print input with no processing. .TP .C -t Produce a single record that totals all input. .TP .C -u Summarize by user .SM ID, rather than user .SM ID and name. .TP .C -v Produce output in verbose .SM ASCII format, with more precise notation for floating point numbers. .RE .SH EXAMPLES The following sequence is useful for making ``repairs'' to any file kept in this format: .IP .nf .C acctmerg -v file2 .IR "\h'.4i'edit file2 as desired " ... .C acctmerg -i file1 .fi .RE .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctprc(1M), acctsh(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR acctmerg ": SVID2, SVID3" .\" .\" index@\f4acctmerg\f1 \- merge or add total accounting files@@@\f3acctmerg(1M)\f1 .\" index@accounting: \f4acctmerg\f1 \- merge or add total accounting files@@@\f3acctmerg(1M)\f1 .\" index@merge or add total accounting files@@@\f3acctmerg(1M)\f1 .\" index@files, accounting: merge or add total accounting files@@@\f3acctmerg(1M)\f1 .\" index@total accounting files, merge or add@@@\f3acctmerg(1M)\f1 .\" index@accounting files, total, merge or add@@@\f3acctmerg(1M)\f1 .\" index@add or merge total accounting files@@@\f3acctmerg(1M)\f1 .\" .\" toc@\f3acctmerg(1M)\f1:\0\0\f4acctmerg\f1@@@merge or add total accounting files .\" .\" fileset_database@acctmerg.1m SYS-ADMIN-MAN .\" $Header: acct.1m,v 72.5 94/11/14 12:00:17 ssa Exp $ .TA a .TH acct 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctdisk, acctdusg, accton, acctwtmp, closewtmp, utmp2wtmp \- overview of accounting and miscellaneous accounting commands .SH SYNOPSIS .C /usr/sbin/acct/acctdisk .PP .C /usr/sbin/acct/acctdusg .RC [ -u .IR file\| ] .RC [ -p .IR file\| ] .PP .C /usr/sbin/acct/accton .RI [ \|file\| ] .PP .C /usr/sbin/acct/acctwtmp .I reason .PP .C /usr/sbin/acct/closewtmp .PP .C /usr/sbin/acct/utmp2wtmp .SH DESCRIPTION Accounting software is structured as a set of tools (consisting of both C programs and shell procedures) that can be used to build accounting systems. The shell procedures, described in .IR acctsh (1M), are built on top of the C programs. .PP Connect time accounting is handled by various programs that write records into .CR /etc/utmp , as described in .IR utmp (4). The programs described in .IR acctcon (1M) convert this file into session and charging records which are then summarized by .C acctmerg (see .IR acctmerg (1M)). .PP Process accounting is performed by the .SM HP-UX system kernel. Upon termination of a process, one record per process is written to a file (normally .CR /var/adm/pacct ). The programs in .IR acctprc (1M) summarize this data for charging purposes; .C acctcms is used to summarize command usage (see .IR acctcms (1M)). Current process data can be examined using .C acctcom (see .IR acctcom (1M)). .PP Process accounting and connect time accounting (or any accounting records in the format described in .IR acct (4)) can be merged and summarized into total accounting records by .C acctmerg (see .C tacct format in .IR acct (4)). .C prtacct is used to format any or all accounting records (see .IR acctsh (1M)). .PP .C acctdisk reads lines that contain user .SM ID, login name, and number of disk blocks, and converts them to total accounting records that can be merged with other accounting records. .PP .C acctdusg reads its standard input (usually from .CR "find -print" ) and computes disk resource consumption (including indirect blocks) by login. Only files found under login directories (as determined from the password file) are accounted for. All files under a login directory are assumed to belong to that user regardless of actual owner. If .C -u is given, records consisting of those file names for which .C acctdusg charges no one are placed in .I file (a potential source for finding users trying to avoid disk charges). If .C -p is given, .I file is the name of the password file. This option is not needed if the password file is .CR /etc/passwd . (See .IR diskusg (1M) for more details.) .PP .C accton turns process accounting off if the optional .I file argument is omitted. If .I file is given, it must be the name of an existing file, to which the kernel appends process accounting records (see .IR acct (2) and .IR acct (4)). .PP .C acctwtmp writes a .IR utmp (4) record to its standard output. The record contains the current time and a string of characters that describe the .I reason for writing the record. A record type of .SM ACCOUNTING is assigned (see .IR utmp (4)). The string argument .I reason must be 11 or fewer characters, numbers, .CR $ , or spaces. For example, the following are suggestions for use in reboot and shutdown procedures, respectively: .IP .C "acctwtmp `uname` >> /var/adm/wtmp" .IP .C "acctwtmp ""file save"" >> /var/adm/wtmp .PP .C closewtmp writes a .SM DEAD_PROCESS record, for each user currently logged in, to the file .CR /var/adm/wtmp . This program is invoked by .I runacct to close the existing .C wtmp file before creating a new one. .PP .C utmp2wtmp writes a .SM USER_PROCESS record, for each user currently logged in, to the file .CR /var/adm/wtmp . This program is invoked by .I runacct to initialize the newly created .C wtmp file. .SH FILES .TP 30 .C /usr/sbin/acct Holds all accounting commands listed in section (1M) of this manual. .TP .C /var/adm/pacct Current process accounting file. .TP .C /etc/passwd Used for converting login name to user. .SM ID .TP .C /var/adm/wtmp Login/logoff history file. .SH SEE ALSO acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), acctsh(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .PP System Accounting topics in .I HP-UX System Administrator manuals. .SH STANDARDS CONFORMANCE .CR acctdisk ": SVID2, SVID3" .PP .CR accton ": SVID2, SVID3" .PP .CR acctwtmp ": SVID2, SVID3" .\" .\" index@accounting: \f4acctdisk\f1 \- create disk usage accounting records@@@\f3acct(1M)\f1 .\" index@accounting: \f4acctdusg\f1 \- compute disk usage by login name@@@\f3acct(1M)\f1 .\" index@accounting: \f4accton\f1 \- define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@accounting: \f4acctwtmp\f1 \- write \f4utmp\f1 record and reason for writing@@@\f3acct(1M)\f1 .\" index@\f4acctdisk\f1 \- create disk usage accounting records@@@\f3acct(1M)\f1 .\" index@\f4acctdusg\f1 \- compute disk usage by login name@@@\f3acct(1M)\f1 .\" index@\f4accton\f1 \- define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@\f4acctwtmp\f1 \- write \f4utmp\f1 record and reason for writing@@@\f3acct(1M)\f1 .\" index@disk usage accounting records, create@@@\f3acct(1M)\f1 .\" index@disk usage by login name, compute@@@\f3acct(1M)\f1 .\" index@define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@disable accounting or define kernel process accounting output file@@@\f3acct(1M)\f1 .\" index@\f4utmp\f1 record, write and include reason for writing@@@\f3acct(1M)\f1 .\" .\" toc@\f3acct(1M)\f1:\0\0\f4acctdisk\f1, \f4acctdusg\f1, \f4accton\f1,\n\f4acctwtmp\f1@@@overview of accounting and miscellaneous accounting commands .\" toc@\f4acctdisk\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4acctdusg\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4accton\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4acctwtmp\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" .\" links@acct.1m acctdisk.1m .\" links@acct.1m acctdusg.1m .\" links@acct.1m accton.1m .\" links@acct.1m acctwtmp.1m .\" links@acct.1m closewtmp.1m .\" links@acct.1m utmp2wtmp.1m .\" .\" fileset_database@acct.1m SYS-ADMIN-MAN .\" $Header: acctprc.1m,v 72.5 94/11/14 12:01:57 ssa Exp $ .TA a .TH acctprc 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctprc, acctprc1, acctprc2 \- process accounting .SH SYNOPSIS .C /usr/sbin/acct/acctprc .PP .C /usr/sbin/acct/acctprc1 .RC [ \|ctmp\| ] .PP .C /usr/sbin/acct/acctprc2 .SH DESCRIPTION .C acctprc1 reads input in the form described by .IR acct (4), adds login names corresponding to user .SM ID\c s, then writes for each process an .SM ASCII line giving user .SM ID, login name, prime .SM CPU time (tics), non-prime .SM CPU time (tics), and mean memory size (in memory segment units). If .C ctmp is given, it is expected to contain a list of login sessions in the form described in .IR acctcon (1M), sorted by user .SM ID and login name. If this file is not supplied, it obtains login names from the password file. The information in .C ctmp helps it distinguish among different login names that share the same user .SM ID. .PP .C acctprc2 reads records in the form written by .CR acctprc1 , summarizes them by user .SM ID and name, then writes the sorted summaries to the standard output as total accounting records. .PP .C acctprc combines the functionality of .C acctprc1 and .C acctprc2 into one program. It takes the same input format as .C acctprc1 (but does not accept the ctmp argument) and writes the same output as .C acctprc2. .PP These commands are typically used as shown below: .IP .C "acctprc1 ctmp < /var/adm/pacct | acctprc2 > ptacct .sp or .IP .C "acctprc < /var/adm/pacct > ptacct" .SH EXTERNAL INFLUENCES .SS Environment Variables For the output of .CR acctprc2 , if the user .SM ID\c s are identical, .C LC_COLLATE determines the order in which the user names are sorted. .PP If .C LC_COLLATE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default. If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C acctprc2 behaves as if all internationalization variables are set to ``C'' (see .IR environ (5)). .SH FILES .C /etc/passwd .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctsh(1M), cron(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH WARNINGS Although it is possible to distinguish among login names that share user .SM ID\c s for commands run normally, it is difficult to do this for those commands run from .C cron for example (see .IR cron (1M)). More precise conversion can be done by faking login sessions on the console via the .C acctwtmp program in .IR acct (1M). .PP A memory segment of the mean memory size is a unit of measure for the number of bytes in a logical memory segment on a particular processor. .SH STANDARDS CONFORMANCE .CR acctprc1 ": SVID2, SVID3" .PP .CR acctprc2 ": SVID2, SVID3" .\" .\" index@\f4acctprc\f1 \- convert process accounting files to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\" index@\f4acctprc1\f1 \- convert process accounting files to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\" index@\f4acctprc2\f1 \- summarize process accounting files created by \f4acctprc1\f1@@@\f3acctprc(1M)\f1 .\" .\" index@\f1files, accounting: convert process accounting files to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\" index@\f1accounting: \f4acctprc1\f1 \- convert process accounting files to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\" index@\f1accounting: \f4acctprc2\f1 \- summarize process accounting files created by \f4acctprc1\f1@@@\f3acctprc(1M)\f1 .\" .\" index@\f1files, accounting: summarize process accounting files created by \f4acctprc1\f1@@@\f3acctprc(1M)\f1 .\" .\" index@\f1accounting files, process, summarize by user \s-1ID\s+1 and name@@@\f3acctprc(1M)\f1 .\" .\" index@\f1accounting files, process, convert to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\"" Main TOC entry: .\" toc@\f3acctprc(1M)\f1:\0\0\f4acctprc1\f1, \f4acctprc2\f1@@@process accounting .\" .\" toc@\f4acctprc1\f1:\0\0convert process accounting@@@\f1see \f3acctprc(1M)\f1 .\" toc@\f4acctprc2\f1:\0\0summarize process accounting@@@\f1see \f3acctprc(1M)\f1 .\" .\" links@acctprc.1m acctprc1.1m .\" links@acctprc.1m acctprc2.1m .\" .\" fileset_database@acctprc.1m SYS-ADMIN-MAN .\" $Header: acctprc.1m,v 72.5 94/11/14 12:01:57 ssa Exp $ .TA a .TH acctprc 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctprc, acctprc1, acctprc2 \- process accounting .SH SYNOPSIS .C /usr/sbin/acct/acctprc .PP .C /usr/sbin/acct/acctprc1 .RC [ \|ctmp\| ] .PP .C /usr/sbin/acct/acctprc2 .SH DESCRIPTION .C acctprc1 reads input in the form described by .IR acct (4), adds login names corresponding to user .SM ID\c s, then writes for each process an .SM ASCII line giving user .SM ID, login name, prime .SM CPU time (tics), non-prime .SM CPU time (tics), and mean memory size (in memory segment units). If .C ctmp is given, it is expected to contain a list of login sessions in the form described in .IR acctcon (1M), sorted by user .SM ID and login name. If this file is not supplied, it obtains login names from the password file. The information in .C ctmp helps it distinguish among different login names that share the same user .SM ID. .PP .C acctprc2 reads records in the form written by .CR acctprc1 , summarizes them by user .SM ID and name, then writes the sorted summaries to the standard output as total accounting records. .PP .C acctprc combines the functionality of .C acctprc1 and .C acctprc2 into one program. It takes the same input format as .C acctprc1 (but does not accept the ctmp argument) and writes the same output as .C acctprc2. .PP These commands are typically used as shown below: .IP .C "acctprc1 ctmp < /var/adm/pacct | acctprc2 > ptacct .sp or .IP .C "acctprc < /var/adm/pacct > ptacct" .SH EXTERNAL INFLUENCES .SS Environment Variables For the output of .CR acctprc2 , if the user .SM ID\c s are identical, .C LC_COLLATE determines the order in which the user names are sorted. .PP If .C LC_COLLATE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default. If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C acctprc2 behaves as if all internationalization variables are set to ``C'' (see .IR environ (5)). .SH FILES .C /etc/passwd .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctsh(1M), cron(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH WARNINGS Although it is possible to distinguish among login names that share user .SM ID\c s for commands run normally, it is difficult to do this for those commands run from .C cron for example (see .IR cron (1M)). More precise conversion can be done by faking login sessions on the console via the .C acctwtmp program in .IR acct (1M). .PP A memory segment of the mean memory size is a unit of measure for the number of bytes in a logical memory segment on a particular processor. .SH STANDARDS CONFORMANCE .CR acctprc1 ": SVID2, SVID3" .PP .CR acctprc2 ": SVID2, SVID3" .\" .\" index@\f4acctprc\f1 \- convert process accounting files to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\" index@\f4acctprc1\f1 \- convert process accounting files to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\" index@\f4acctprc2\f1 \- summarize process accounting files created by \f4acctprc1\f1@@@\f3acctprc(1M)\f1 .\" .\" index@\f1files, accounting: convert process accounting files to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\" index@\f1accounting: \f4acctprc1\f1 \- convert process accounting files to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\" index@\f1accounting: \f4acctprc2\f1 \- summarize process accounting files created by \f4acctprc1\f1@@@\f3acctprc(1M)\f1 .\" .\" index@\f1files, accounting: summarize process accounting files created by \f4acctprc1\f1@@@\f3acctprc(1M)\f1 .\" .\" index@\f1accounting files, process, summarize by user \s-1ID\s+1 and name@@@\f3acctprc(1M)\f1 .\" .\" index@\f1accounting files, process, convert to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\"" Main TOC entry: .\" toc@\f3acctprc(1M)\f1:\0\0\f4acctprc1\f1, \f4acctprc2\f1@@@process accounting .\" .\" toc@\f4acctprc1\f1:\0\0convert process accounting@@@\f1see \f3acctprc(1M)\f1 .\" toc@\f4acctprc2\f1:\0\0summarize process accounting@@@\f1see \f3acctprc(1M)\f1 .\" .\" links@acctprc.1m acctprc1.1m .\" links@acctprc.1m acctprc2.1m .\" .\" fileset_database@acctprc.1m SYS-ADMIN-MAN .\" $Header: acctprc.1m,v 72.5 94/11/14 12:01:57 ssa Exp $ .TA a .TH acctprc 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctprc, acctprc1, acctprc2 \- process accounting .SH SYNOPSIS .C /usr/sbin/acct/acctprc .PP .C /usr/sbin/acct/acctprc1 .RC [ \|ctmp\| ] .PP .C /usr/sbin/acct/acctprc2 .SH DESCRIPTION .C acctprc1 reads input in the form described by .IR acct (4), adds login names corresponding to user .SM ID\c s, then writes for each process an .SM ASCII line giving user .SM ID, login name, prime .SM CPU time (tics), non-prime .SM CPU time (tics), and mean memory size (in memory segment units). If .C ctmp is given, it is expected to contain a list of login sessions in the form described in .IR acctcon (1M), sorted by user .SM ID and login name. If this file is not supplied, it obtains login names from the password file. The information in .C ctmp helps it distinguish among different login names that share the same user .SM ID. .PP .C acctprc2 reads records in the form written by .CR acctprc1 , summarizes them by user .SM ID and name, then writes the sorted summaries to the standard output as total accounting records. .PP .C acctprc combines the functionality of .C acctprc1 and .C acctprc2 into one program. It takes the same input format as .C acctprc1 (but does not accept the ctmp argument) and writes the same output as .C acctprc2. .PP These commands are typically used as shown below: .IP .C "acctprc1 ctmp < /var/adm/pacct | acctprc2 > ptacct .sp or .IP .C "acctprc < /var/adm/pacct > ptacct" .SH EXTERNAL INFLUENCES .SS Environment Variables For the output of .CR acctprc2 , if the user .SM ID\c s are identical, .C LC_COLLATE determines the order in which the user names are sorted. .PP If .C LC_COLLATE is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default. If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C acctprc2 behaves as if all internationalization variables are set to ``C'' (see .IR environ (5)). .SH FILES .C /etc/passwd .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctsh(1M), cron(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH WARNINGS Although it is possible to distinguish among login names that share user .SM ID\c s for commands run normally, it is difficult to do this for those commands run from .C cron for example (see .IR cron (1M)). More precise conversion can be done by faking login sessions on the console via the .C acctwtmp program in .IR acct (1M). .PP A memory segment of the mean memory size is a unit of measure for the number of bytes in a logical memory segment on a particular processor. .SH STANDARDS CONFORMANCE .CR acctprc1 ": SVID2, SVID3" .PP .CR acctprc2 ": SVID2, SVID3" .\" .\" index@\f4acctprc\f1 \- convert process accounting files to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\" index@\f4acctprc1\f1 \- convert process accounting files to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\" index@\f4acctprc2\f1 \- summarize process accounting files created by \f4acctprc1\f1@@@\f3acctprc(1M)\f1 .\" .\" index@\f1files, accounting: convert process accounting files to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\" index@\f1accounting: \f4acctprc1\f1 \- convert process accounting files to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\" index@\f1accounting: \f4acctprc2\f1 \- summarize process accounting files created by \f4acctprc1\f1@@@\f3acctprc(1M)\f1 .\" .\" index@\f1files, accounting: summarize process accounting files created by \f4acctprc1\f1@@@\f3acctprc(1M)\f1 .\" .\" index@\f1accounting files, process, summarize by user \s-1ID\s+1 and name@@@\f3acctprc(1M)\f1 .\" .\" index@\f1accounting files, process, convert to \s-1ASCII\s+1 text format@@@\f3acctprc(1M)\f1 .\" .\"" Main TOC entry: .\" toc@\f3acctprc(1M)\f1:\0\0\f4acctprc1\f1, \f4acctprc2\f1@@@process accounting .\" .\" toc@\f4acctprc1\f1:\0\0convert process accounting@@@\f1see \f3acctprc(1M)\f1 .\" toc@\f4acctprc2\f1:\0\0summarize process accounting@@@\f1see \f3acctprc(1M)\f1 .\" .\" links@acctprc.1m acctprc1.1m .\" links@acctprc.1m acctprc2.1m .\" .\" fileset_database@acctprc.1m SYS-ADMIN-MAN .\" $Header: acctsh.1m,v 72.4 94/11/14 12:02:10 ssa Exp $ .TA a .TH acctsh 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chargefee, ckpacct, dodisk, lastlogin, monacct, nulladm, prctmp, prdaily, prtacct, shutacct, startup, turnacct \- shell procedures for accounting .SH SYNOPSIS .C /usr/sbin/acct/chargefee .I login-name number .PP .C /usr/sbin/acct/ckpacct .RI [ \|blocks\| ] .PP .C /usr/sbin/acct/dodisk .RC [ -o ] .RI [ \|files \0 ...\|] .PP .C /usr/sbin/acct/lastlogin .PP .C /usr/sbin/acct/monacct .I number .PP .C /usr/sbin/acct/nulladm .I file .PP .C /usr/sbin/acct/prctmp .PP .C /usr/sbin/acct/prdaily .RC [ -l ] .RC [ -c ] .RC [ \c .IR mmdd\| ] .PP .C /usr/sbin/acct/prtacct .I file .RI [ \|heading\| ] .PP .C /usr/sbin/acct/shutacct .RI [ \|reason\| ] .PP .C /usr/sbin/acct/startup .PP .C /usr/sbin/acct/turnacct .CR on \0\(or\0 off \0\(or\0 switch .SH DESCRIPTION .TP 15 .C chargefee Can be invoked to charge a .I number of units to .IR login-name . A record is written to .CR /var/adm/fee , to be merged with other accounting records during the night. .TP .C ckpacct Should be initiated via .IR cron (1M). It periodically checks the size of .CR /var/adm/pacct . If the size exceeds .IR blocks , 1000 by default, .C turnacct is invoked with argument .IR switch . If the number of free disk blocks in the .C /var file system falls below 500, .C ckpacct automatically turns off the collection of process accounting records via the .C off argument to .CR turnacct . When at least this number of blocks is restored, the accounting will be activated again. This feature is sensitive to the frequency at which .C ckpacct is executed, usually by .CR cron . .TP .C dodisk Should be invoked by .C cron to perform the disk accounting functions. By default, it will do disk accounting on the special files in .C /etc/fstab. If the .C -o flag is used, it does a slower version of disk accounting by login directory. .I files specifies the one or more filesystem names where disk accounting is to be done. If .I files is used, disk accounting will be done on these filesystems only. If the .C -o flag is used, .I files should be mount points of mounted filesystem. If omitted, they should be the special file names of mountable filesystems. .TP .C lastlogin Invoked by .C runacct to update .C /var/adm/acct/sum/loginlog which shows the last date on which each user logged in (see .IR runacct (1M)). .TP .C monacct Should be invoked once each month or each accounting period. .I number indicates which month or period it is. If .I number is not given, it defaults to the current month (01 through 12). This default is useful if .C monacct is to executed via .CR cron on the first day of each month. .C monacct creates summary files in .C /var/adm/acct/fiscal and restarts summary files in .CR /var/adm/acct/sum . .TP .C nulladm Creates .I file with mode 664 and ensures that owner and group are .CR adm . It is called by various accounting shell procedures. .TP .C prctmp Can be used to print the session record file normally .C /var/adm/acct/nite/ctmp created by .C acctcon1 (see .IR acctcon (1M)). .TP .C prdaily Invoked by .C runacct (see .IR runacct (1M)) to format a report of the previous day's accounting data. The report resides in .CI /var/adm/acct/sum/rprt mmdd where .I mmdd is the month and day of the report. The current daily accounting reports may be printed by typing .IR prdaily . Previous days' accounting reports can be printed by using the .I mmdd option and specifying the exact report date desired. The .C -l flag prints a report of exceptional usage by login id for the specifed date. Previous daily reports are cleaned up and therefore inaccessible after each invocation of .CR monacct . The .C -c flag prints a report of exceptional resource usage by command, and can be used on current day's accounting data only. .TP .C prtacct Can be used to format and print any total accounting .RC ( tacct ) file. .TP .C shutacct Should be invoked during a system shutdown to turn process accounting off and append a ``reason'' record to .CR /var/adm/wtmp . .TP .C startup Should be called by system startup scripts to turn the accounting on whenever the system is brought up. .TP .C turnacct An interface to .C accton (see .IR acct (1M)) to turn process accounting .C on or .CR off . The .C switch argument turns accounting off, moves the current .C /var/adm/pacct to the next free name in .CI /var/adm/pacct incr then turns accounting back on again. .RI ( incr is a number starting with .C 1 and incrementing by one for each additional .C pacct file.) .C turnacct is called by .CR ckpacct , and thus can be run under .C cron and used to keep .C pacct to a reasonable size. .SH FILES .TP 40 .C /usr/sbin/acct holds all accounting commands listed in section (1M) of this manual .PD 0 .TP .C /var/adm/fee accumulator for fees .TP .C /var/adm/acct/nite working directory .TP .C /var/adm/pacct current file for per-process accounting .TP .C /var/adm/pacct* used if .C pacct gets large, and during execution of daily accounting procedure .TP .C /usr/sbin/acct/ptecms.awk contains the limits for exceptional usage by command name .TP .C /usr/sbin/acct/ptelus.awk contains the limits for exceptional usage by login id .TP .C /var/adm/acct/sum summary directory, should be saved .TP .C /var/adm/wtmp login/logoff summary .PD .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), cron(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR chargefee ": SVID2, SVID3" .PP .CR ckpacct ": SVID2, SVID3" .PP .CR dodisk ": SVID2, SVID3" .PP .CR lastlogin ": SVID2, SVID3" .PP .CR monacct ": SVID2, SVID3" .PP .CR prctmp ": SVID2, SVID3" .PP .CR prdaily ": SVID2, SVID3" .PP .CR prtacct ": SVID2, SVID3" .PP .CR shutacct ": SVID2, SVID3" .PP .CR startup ": SVID2, SVID3" .PP .CR turnacct ": SVID2, SVID3" .\" .\" .\" index@\f1process accounting@@@see accounting .\" index@\f1accounting: \f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4turnacct\f1 \- turn on or turn off process accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1bill fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1user, bill fee to, based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1disk accounting, perform@@@\f3acctsh(1M)\f1 .\" index@\f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1user, show last login date for each@@@\f3acctsh(1M)\f1 .\" index@\f1last login date, show for each user@@@\f3acctsh(1M)\f1 .\" index@\f1login date, show last for each user@@@\f3acctsh(1M)\f1 .\" index@\f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1periodic accounting summary files, create@@@\f3acctsh(1M)\f1 .\" index@\f1accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1files: accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1summary files, accounting, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1create empty administration file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1empty administration file owned by \f3adm\f1 with mode 664, create@@@\f3acctsh(1M)\f1 .\" index@\f1administration file owned by \f3adm\f1 with mode 664, create empty@@@\f3acctsh(1M)\f1 .\" index@\f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f4acctcon1\f1 \- print session record file created by@@@\f3acctsh(1M)\f1 .\" index@\f1print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1files, accounting: print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1session record file created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f1record file, session, created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1total accounting (\f4tacct\f1) file, print any@@@\f3acctsh(1M)\f1 .\" index@\f1accounting (\f4tacct\f1) file, print any total@@@\f3acctsh(1M)\f1 .\" index@\f4tacct\f1 (total accounting) file, print any@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting: \f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" index@\f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting data and command usage summary, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f1command usage summary and accounting data, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1system shutdown, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f1shutdown, system, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1system startup, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f1startup, system, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f4turnacct\f1 \- turn process accounting on or off@@@\f3acctsh(1M)\f1 .\" index@\f1shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f1system accounting, shell procedures for@@@\f3acctsh(1M)\f1 .\" .\"" Main TOC entry .\" toc@\f3acctsh(1M)\f1:\0\0\f4chargefee\f1, \f4ckpacct\f1, \f4dodisk\f1, \f4lastlogin\f1, \f4monacct\f1, \f4nulladm\f1, \f4prctmp\f1, \f4prdaily\f1,\n\f4prtacct\f1, \f4shutacct\f1, \f4startup\f1, \f4turnacct\f1@@@shell procedures for accounting .\" .\" toc@\f4chargefee\f1:\0\0shell procedures for accounting, charge fee to user@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4ckpacct\f1:\0\0shell procedures for accounting, check size of accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4dodisk\f1:\0\0shell procedures for accounting, perform disk accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4lastlogin\f1:\0\0shell procedures for accounting, show last login date@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4monacct\f1:\0\0shell procedures for accounting, create accounting summary@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4nulladm\f1:\0\0shell procedures for accounting, create null file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prctmp\f1:\0\0shell procedures for accounting, print session record file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prdaily\f1:\0\0shell procedures for accounting, print daily report@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prtacct\f1:\0\0shell procedures for accounting, print accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4shutacct\f1:\0\0shell procedures for accounting, turn off accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4startup\f1:\0\0shell procedures for accounting, start up accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4turnacct\f1:\0\0shell procedures for accounting, turn on or off process accounting@@@\f1see \f3acctsh(1M)\f1 .\" .\" links@acctsh.1m chargefee.1m .\" links@acctsh.1m ckpacct.1m .\" links@acctsh.1m dodisk.1m .\" links@acctsh.1m lastlogin.1m .\" links@acctsh.1m monacct.1m .\" links@acctsh.1m nulladm.1m .\" links@acctsh.1m prctmp.1m .\" links@acctsh.1m prdaily.1m .\" links@acctsh.1m prtacct.1m .\" links@acctsh.1m shutacct.1m .\" links@acctsh.1m startup.1m .\" links@acctsh.1m turnacct.1m .\" .\" fileset_database@acctsh.1m SYS-ADMIN-MAN .\" $Header: acct.1m,v 72.5 94/11/14 12:00:17 ssa Exp $ .TA a .TH acct 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctdisk, acctdusg, accton, acctwtmp, closewtmp, utmp2wtmp \- overview of accounting and miscellaneous accounting commands .SH SYNOPSIS .C /usr/sbin/acct/acctdisk .PP .C /usr/sbin/acct/acctdusg .RC [ -u .IR file\| ] .RC [ -p .IR file\| ] .PP .C /usr/sbin/acct/accton .RI [ \|file\| ] .PP .C /usr/sbin/acct/acctwtmp .I reason .PP .C /usr/sbin/acct/closewtmp .PP .C /usr/sbin/acct/utmp2wtmp .SH DESCRIPTION Accounting software is structured as a set of tools (consisting of both C programs and shell procedures) that can be used to build accounting systems. The shell procedures, described in .IR acctsh (1M), are built on top of the C programs. .PP Connect time accounting is handled by various programs that write records into .CR /etc/utmp , as described in .IR utmp (4). The programs described in .IR acctcon (1M) convert this file into session and charging records which are then summarized by .C acctmerg (see .IR acctmerg (1M)). .PP Process accounting is performed by the .SM HP-UX system kernel. Upon termination of a process, one record per process is written to a file (normally .CR /var/adm/pacct ). The programs in .IR acctprc (1M) summarize this data for charging purposes; .C acctcms is used to summarize command usage (see .IR acctcms (1M)). Current process data can be examined using .C acctcom (see .IR acctcom (1M)). .PP Process accounting and connect time accounting (or any accounting records in the format described in .IR acct (4)) can be merged and summarized into total accounting records by .C acctmerg (see .C tacct format in .IR acct (4)). .C prtacct is used to format any or all accounting records (see .IR acctsh (1M)). .PP .C acctdisk reads lines that contain user .SM ID, login name, and number of disk blocks, and converts them to total accounting records that can be merged with other accounting records. .PP .C acctdusg reads its standard input (usually from .CR "find -print" ) and computes disk resource consumption (including indirect blocks) by login. Only files found under login directories (as determined from the password file) are accounted for. All files under a login directory are assumed to belong to that user regardless of actual owner. If .C -u is given, records consisting of those file names for which .C acctdusg charges no one are placed in .I file (a potential source for finding users trying to avoid disk charges). If .C -p is given, .I file is the name of the password file. This option is not needed if the password file is .CR /etc/passwd . (See .IR diskusg (1M) for more details.) .PP .C accton turns process accounting off if the optional .I file argument is omitted. If .I file is given, it must be the name of an existing file, to which the kernel appends process accounting records (see .IR acct (2) and .IR acct (4)). .PP .C acctwtmp writes a .IR utmp (4) record to its standard output. The record contains the current time and a string of characters that describe the .I reason for writing the record. A record type of .SM ACCOUNTING is assigned (see .IR utmp (4)). The string argument .I reason must be 11 or fewer characters, numbers, .CR $ , or spaces. For example, the following are suggestions for use in reboot and shutdown procedures, respectively: .IP .C "acctwtmp `uname` >> /var/adm/wtmp" .IP .C "acctwtmp ""file save"" >> /var/adm/wtmp .PP .C closewtmp writes a .SM DEAD_PROCESS record, for each user currently logged in, to the file .CR /var/adm/wtmp . This program is invoked by .I runacct to close the existing .C wtmp file before creating a new one. .PP .C utmp2wtmp writes a .SM USER_PROCESS record, for each user currently logged in, to the file .CR /var/adm/wtmp . This program is invoked by .I runacct to initialize the newly created .C wtmp file. .SH FILES .TP 30 .C /usr/sbin/acct Holds all accounting commands listed in section (1M) of this manual. .TP .C /var/adm/pacct Current process accounting file. .TP .C /etc/passwd Used for converting login name to user. .SM ID .TP .C /var/adm/wtmp Login/logoff history file. .SH SEE ALSO acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), acctsh(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .PP System Accounting topics in .I HP-UX System Administrator manuals. .SH STANDARDS CONFORMANCE .CR acctdisk ": SVID2, SVID3" .PP .CR accton ": SVID2, SVID3" .PP .CR acctwtmp ": SVID2, SVID3" .\" .\" index@accounting: \f4acctdisk\f1 \- create disk usage accounting records@@@\f3acct(1M)\f1 .\" index@accounting: \f4acctdusg\f1 \- compute disk usage by login name@@@\f3acct(1M)\f1 .\" index@accounting: \f4accton\f1 \- define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@accounting: \f4acctwtmp\f1 \- write \f4utmp\f1 record and reason for writing@@@\f3acct(1M)\f1 .\" index@\f4acctdisk\f1 \- create disk usage accounting records@@@\f3acct(1M)\f1 .\" index@\f4acctdusg\f1 \- compute disk usage by login name@@@\f3acct(1M)\f1 .\" index@\f4accton\f1 \- define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@\f4acctwtmp\f1 \- write \f4utmp\f1 record and reason for writing@@@\f3acct(1M)\f1 .\" index@disk usage accounting records, create@@@\f3acct(1M)\f1 .\" index@disk usage by login name, compute@@@\f3acct(1M)\f1 .\" index@define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@disable accounting or define kernel process accounting output file@@@\f3acct(1M)\f1 .\" index@\f4utmp\f1 record, write and include reason for writing@@@\f3acct(1M)\f1 .\" .\" toc@\f3acct(1M)\f1:\0\0\f4acctdisk\f1, \f4acctdusg\f1, \f4accton\f1,\n\f4acctwtmp\f1@@@overview of accounting and miscellaneous accounting commands .\" toc@\f4acctdisk\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4acctdusg\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4accton\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4acctwtmp\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" .\" links@acct.1m acctdisk.1m .\" links@acct.1m acctdusg.1m .\" links@acct.1m accton.1m .\" links@acct.1m acctwtmp.1m .\" links@acct.1m closewtmp.1m .\" links@acct.1m utmp2wtmp.1m .\" .\" fileset_database@acct.1m SYS-ADMIN-MAN ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\"Copyright Hewlett-Packard Company 1992 ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" .rm zA .rm zZ .TH acl_edit "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lacl_edit\*O command" .iX "-[" "Security Service commands" "\*Lacl_edit\*O" .iX "-[" "ACLs" "viewing" .iX "-[" "ACLs" "editing entries" .SH NAME \*Lacl_edit\*O \- Edits or lists an object's ACLs .SH "SYNOPSIS" .sS \*Lacl_edit\*O {[\*L-e\*O] \*Vpathname\*O | \*L-addr \*Vstring_binding component_name\*O} \*O[\*L-ic\*O | \*L-io\*O] \*O[\*L-n\*O | \*L-c\*O] \*O[\*Vcommand_line_subcommands\*O] \*O[\*L-ngui\*O] [\*L-v\*O] .sE .SH "OPTIONS" .VL 1i ...\" ...\" ...\" .LI "\*L-e\*O \*Vpathname\*O" ...\" For those cases in which \*Vpathname\*O resolves to both a leaf ...\" object in the Directory Service and to an object in another DCE ...\" component that supports ACLs, the \*L-e\*O option specifies that ...\" the leaf object in the Directory Service should be edited. The ...\" \*L-e\*O option can be used only with the \*Vpathname\*O argument. ...\" ...\" added 10.xii.91: Specifies that the ACL on the Directory Service entry is to be edited. You must specify the \*Vpathname\*O argument if you use the \*L\-e\*O option. .P The \*L\-e\*O option is especially useful in case of an ambiguous \*Vpathname\*O. The \*Vpathname\*O argument can be interpreted in two ways if it is the name of a leaf object in the Directory Service (that is, if it is not the name of a directory). It can be interpreted as the Directory Service entry itself, or as the object (whatever it is) referenced by that Directory Service entry. When such a \*Vpathname\*O is specified, the \*L\-e\*O option directs \*Lacl_edit\*O to the ACL on the Directory Service entry. ...\" However, the ...\" \*L-e\*O option can always be used, provided only that \*Vpathname\*O ...\" specifies a leaf object in the Directory Service. ...\" ...end of 10.xii.91 addition ...\" ...\" ...\" ...\" ...\" ...\" .LI "\*L-addr \*O\*Vstring_binding component_name\*O" The \*L\-addr\*O option lets you identify the object whose ACLs you want to edit by supplying the RPC binding handle of the ACL Manager that controls access to the object (with the \*Vstring_binding\*O argument) and the relative pathname of the object (with the \*Vcomponent_name\*O argument). Because you have identified the RPC binding handle, you can specify only the object's relative pathname for \*Vcomponent_name\*O. .sp .4vi The most common way to identify the object whose ACLs you want to manipulate is through the \*Vpathname\*O argument, described below. The \*L\-addr\*O option is used primarily by applications that do not use the Directory Service, but do use the generic ACL Manager. It can also be used if the Directory Service is unavailable. .LI "\*L-ic\*O" For container objects only, specifies that the object's Initial Container Creation ACL is to be edited. The Initial Container Creation ACL is applied by default to any containers created within the ACL'd container. If this option is specified and the object named in \*Vpathname\*O is not a container, an error is returned. .LI "\*L-io\*O" For container objects only, specifies that the object's Initial Object Creation ACL is to be edited. The Initial Object Creation ACL is applied by default to any simple objects (that is, objects that are not containers) created within the ACL'd container. If this option is specified and the object is not a container, an error is returned. .LI "\*L-n\*O" Specifies that a new mask should not be calculated. This option is useful only for objects that support the \*Lmask_obj\*O entry type and that are required to recalculate a new mask after they are modified. .P If a modify operation creates a mask that unintentionally adds permissions to an existing acl entry, the modify causing the mask recalculation will abort with an error unless you specify either the \*L-c\*O or \*L-n\*O option. .LI "\*L-c\*O" Creates or modifies the object's \*Lmask_obj\*O type entry with permissions equal to the union of all entries other than type \*Luser_obj\*O, \*Lother_obj\*O, and \*Lunauthenticated\*O. This creation or modification is done after all other modifications to the ACL are performed. The new mask is set even if it grants permissions previously masked out. It is recommended that you use this option only if not specifying it results in an error. This option is useful only for objects that support the \*Lmask_obj\*O entry type and are required to recalculate a new mask after they are modified. .P If a modify operation creates a mask that unintentionally adds permissions to an existing acl entry, the modify causing the mask recalculation will abort with an error unless you specify either the \*L-c\*O or \*L-n\*O option. .P If you specify the \*L\-c\*O option for an ACL that does not support \*Lmask_obj\*O entry type, \*Lacl_edit\*O returns an error when it attempts to save the ACL, aborting all subcommands supplied on the command line. .LI "\*L-ngui\*O" .zA "def,9636,R1.1,clarify ngui" Specifies that a Graphical User Interface (GUI) should not be used even if a GUI is available. If your version of \*Lacl_edit\*O supports a GUI and your terminal is capable of using it, invoking \*Lacl_edit\*O without this option will bring up the GUI mode. Use the \*L-ngui\*O option to bring up command-line mode. However, if a GUI is not available, or the terminal is not capable of using the GUI, \*Lacl_edit\*O comes up in command-line mode regardless of wheter you supply this option or not. .zZ "def,9636,R1.1,clarify ngui" .LI "\*L-v\*O" Run in verbose mode. .LE .SH "ARGUMENTS" .VL 1i .LI "\*Vpathname\*O" The full pathname of the object whose ACL is to be viewed or edited. If the object is in another cell,\*V pathname\*O must be fully qualified to include the cell identifier. .LI "\*Vcommand_line_subcommands\*O" The command-line subcommands, which act on the object specified by \*Vpathname\*O, are entered as part of the command string that invokes \*Lacl_edit\*O. Only one command-line subcommand can be specified per invocation. The commands follow. See the description of the equivalent interactive subcommand for a more detailed description of the command functions. .zA "defect,4752,R1.0.2,Clarify -m, -d, -s subcommand syntax" .VL .LI "\*L-m\*O [\*Vacl_entry\*O] \*Vacl_entry\*O..." Adds a new ACL entry or changes the permissions of an existing entry. You can enter multiple entries, each separated by a space. .LI "\*L-p\*O" Purges all masked permissions (before any other modifications are made). This option is useful only for ACLs that contain an entry of type \*Lmask_obj\*O. Use it to prevent unintentionally granting permissions to an existing entry when a new mask is calculated as a result of adding or modifying an ACL entry. .LI "\*L-d\*O [\*Vacl_entry\*O] \*Vacl_entry\*O..." Deletes an existing entry from the ACL associated with the specified object. You can enter multiple entries, each separated by a space. .LI "\*L-s\*O [\*Vacl_entry\*O] \*Vacl_entry\*O..." Replaces (substitutes) the ACL information associated with this object with \*Vacl_entry\*O. All existing entries are removed and replaced by the newly specified entries. If you specify the \*L\-s\*O subcommand, you cannot specify the \*L\-f\*O or \*L\-k\*O subcommand. You can enter multiple entries, each separated by a space. .LI "\*L-f\*O \*Vfile\*O" Assigns the ACL information contained in \*Vfil\*Oe to the object. All existing entries are removed and replaced by the entries in the file. If you specify the \*L\-f\*O subcommand, you cannot specify the \*L\-s\*O or \*L\-k\*O subcommand. .LI "\*L-k\*O" Removes all entries, except entries of type \*Luser_obj\*O (if they are present). If you specify the \*L\-k\*O subcommand, you cannot specify the \*L\-f\*O or \*L\-s\*O subcommand. .LI "\*L-l\*O" Lists the entries in the object's ACL. .LE .zZ "defect,4752,R1.0.2,Clarify -m, -d, -s subcommand syntax" The command-line subcommands are evaluated in the following order: .AL .LI \*L-p\*O .LI \*L-s\*O or \*L-f\*O or \*L-k\*O .LI \*L-d\*O .LI \*L-m\*O .LI \*L-l\*O .LE .LE .zA "defect, 11818, R1.1, Added caveat" .SH "NOTES" With the exception of the following subcommands, this command is replaced at Revision 1.1 by the \*Ldcecp\*O command. This command may be fully replaced by the \*Ldcecp\*O command in a future release of DCE, and may no longer be supported at that time. .P .ML .LI \*Labort\*O .LI \*Lcommit\*O .LI \*Lexit\*O .LI \*Lhelp\*O .LI \*Ltest access\*O .LE .zZ "defect, 11818, R1.1, Added caveat" .SH "DESCRIPTION" The \*Lacl_edit\*O command is a client program that, when invoked, binds to the specified object's ACL Manager (which is implemented in the object's server), and allows the user to manipulate the object's ACL through the standard DCE ACL interface. This interface is the \*Lsec_acl_...(\|)\*O interface documented in the \*VOSF DCE Application Development Reference\*O. .P The \*Lacl_edit\*O command automatically binds to the server of the object specified, and then communicates (through the standard DCE ACL interface) with that server's ACL manager in response to user input. .P Exactly what the ``object specified'' is depends partly on whether or not the \*L\-e\*O option is specified. Specifying \*L\-e\*O means that you want to operate on the Directory Service ACL \(em in other words, you want \*Lacl_edit\*O to bind to the CDS server and allow you to operate on the ACL maintained by that server on the object's directory entry. If, on the the ACL on the object to which the directory entry refers \(em then you simply omit the \*L\-e\*O option. The result will be that \*Lacl_edit\*O will bind to that object's server (the server must, of course, implement an ACL manager), giving you access to the object's ACL. .P All \*Lacl_edit\*O subcommands act on the object specified by \*Vpathname\*O when you invoked \*Lacl_edit\*O. You can invoke \*Lacl_edit\*O in either command-line or interactive mode: .ML .LI To invoke \*Lacl_edit\*O in command-line mode, enter the command, the object's pathname, options, and the command-line subcommand on the line that invokes \*Lacl_edit\*O. Only one command-line subcommand can be entered per \*Lacl_edit\*O invocation. .LI To invoke \*Lacl_edit\*O in interactive mode, enter only \*Lacl_edit\*O, the object's pathname, and options. The \*Lacl_edit\*O prompt is then displayed. In this mode, you enter interactive subcommands that let you edit and view entries in the object's ACL and view help information about the \*Lacl_edit\*O command itself. .LE .zA "def,7812,R1.0.3,clarify transaction model" Changes you make in command-line mode are saved when you enter the command. In interactive mode, you must explicitly save your changes. To do so, use the \*Lcommit\*O subcommand to save the changes without exiting \*Lacl_edit\*O or the \*Lexit\*O subcommand to save the changes and exit \*Lacl_edit\*O. Use the \*Labort\*O subcommand to exit \*Lacl_edit\*O and save none of the changes you have made. .zZ "def,7812,R1.0.3,clarify transaction model" .zA "def,8253,R1.0.3,acl_edit is non-locking" .nS note When you invoke \*Lacl_edit\*O for a specific object's ACL, that ACL is not locked. This means that it is possible for multiple users to edit the ACL simultaneously, with each change overwriting the previous changes. For this reason, the number of users assigned rights to change a particular ACL should be tightly controlled and limited to one user if possible. .nE .zZ "def,8253,R1.0.3,acl_edit is non-locking" .SH "INTERACTIVE SUBCOMMANDS" The following subcommands are available when \*Lacl_edit\*O is invoked in interactive mode. All of the commands act on the ACL associated with the object specified by \*Vpathname\*O when \*Lacl_edit\*O was invoked. .VL 1i .LI "\*L?\*O " Displays the available \*Lacl_edit\*O subcommands. .LI "\*Lab[ort]\*O" Exits \*Lacl_edit\*O without saving the changes to the object's ACL. .LI "\*Las[sign]\*O \*Vfilename\*O" Applies the ACL entries in \*Vfilename\*O to the specified object. This subcommand removes existing entries and replaces them with the entries in the file. .LI "\*Lc[ell]\*O \*Vname\*O" Sets the cell name to be associated with the ACL. This subcommand is used primarily to facilitate copying ACLs to different cells. The default cell name stays in place until you run the subcommand again to change it. .LI "\*Lco[mmit]\*O Saves all changes to the ACL without exiting. .LI "\*Ld[elete]\*O \*Vacl_entry\*O" Deletes the specified ACL entry. .LI "\*Le[xit]\*O" Exits from \*Lacl_edit\*O, saving any changes to the object's ACL. .LI "\*Lg[et_access]\*O" Displays the permissions granted in the specified object's ACL to the principal that invoked \*Lacl_edit\*O. .LI "\*Lh[elp]\*O [\*Vcommand\*O \&...]" Initiates the \*Lhelp\*O facility. If you enter only the command \*Lhelp\*O, \*Lacl_edit\*O displays a list of all commands and their functions. If you enter \*Lhelp\*O and a command (or commands separated by a space), \*Lacl_edit\*O displays help information on the specified commands. Entering \*Lhelp sec_acl_entry\*O displays information about ACL entries. .LI "\*Lk[ill_entries]\*O" Removes all ACL entries except the \*Luser_obj\*O entry if it exists. .LI "\*Ll[ist]\*O" Lists the entries in the object's ACL. .LI "\*Lm[odify]\*O \*Vacl_entry\*O [\*L-n | -c\*O]" Adds a new ACL entry or replaces an existing ACL entry. This command affects a single ACL entry. To add or replace all of an object's ACL entries, see the \*Lsu[bstitute]\*O subcommand. .P For objects that support the \*Lmask_obj\*O entry type and are required to calculate a new mask when their ACLs are modified, the \*L\-n\*O option specifies that a new mask should \*Enot\*L be calculated; the \*L\-c\*O option specifies that the object's \*Lmask_obj\*O entry should have permissions equal to the union of all entries other than \*Luser_obj\*O, \*Lother_obj\*O, and \*Lunauthenticated\*O. The mask is calculated after the ACL is modified. .P If you use the \*L\-c\*O option, the new mask is set even if it grants permissions previously masked out. It is recommended that you use the \*L\-c\*O option only if not specifying it results in an error. If the new mask unintentionally grants permissions to an existing entry, the modify operation causing the mask recalculation will abort with an error unless you specify either the \*L\-c\*O or \*L\-n\*O option. .LI "\*Lp[ermissions]\*O" Lists the available permission tokens and explanations. .LI "\*Lpu[rge\*O]" Purges all masked permissions. This option is useful only for ACLs that contain an entry of type \*Lmask_obj\*O. Use it to prevent unintentionally granting permissions to an existing entry when a new mask is calculated as a result of adding or modifying an ACL entry. .LI "\*Lsu[bstitute]\*O \*Vacl_entry\*O [\*Vacl_entry ...\*O]" Replaces all ACL entries with the one or ones specified. This subcommand removes all existing entries and adds the ones specified by \*Vacl_entry\*O. To replace only a single ACL entry, see the \*Lm[odify]\*O subcommand. .LI "\*Lt[est_access]\*0 [\*Vpermissions\*O \&...]" Tests whether or not the permissions specified in the command are granted to the principal under whose DCE identity the \*Lacl_edit\*O command was invoked. The option returns \*CGranted\*O if the permissions are granted or \*CDenied\*O if they are not. .LE .SH "ACL ENTRIES" An ACL entry has the following syntax: .sS \*Vtype\*O[\*L:\*O\*Vkey\*O]\*L:\*O\*Vpermissions\*O .sE .PP where: .VL 1i .LI "\*Vtype\*O" Identifies the role of the ACL entry. .LI "\*Vkey\*O" Identifies the specific principal or group to whom the entry applies. For an entry type of \*Lextended\*O, \*Vkey\*O contains the ACL data. .LI "\*Vpermissions\*O" The ACL permissions. .LE .PP A thorough description of each syntax component follows. .SS "Type" The \*Vtype\*O tag identifies the role of the ACL entry. Valid types are the following: .ML .LI \*Luser_obj\*O \- Permissions for the object's real or effective user. .LI \*Lgroup_obj\*O \- Permissions for the object's real or effective group. .LI \*Lother_obj\*O \- Permissions for others in the local cell who are not otherwise named by a more specific entry type. .LI \*Luser\*O \- Permissions for a specific principal user in the ACL's cell. This type of ACL entry must include a key that identifies the specific principal. .LI \*Lgroup\*O \- Permissions for a specific group in the ACL's cell. This type of ACL entry must include a key that identifies the specific group. .LI \*Lforeign_user\*O \- Permissions for a specific, authenticated user in a foreign cell. This type of ACL entry must include a key that identifies the specific principal and the principal's cell. .LI \*Lforeign_group\*O \- Permissions for a specific, authenticated group in a foreign cell. This type of ACL entry must include a key that identifies the specific group and the group's cell. .LI \*Lforeign_other\*O \- Permissions for all authenticated principals in a specific foreign cell, unless those principals are specifically named in an ACL entry of type \*Lforeign_user\*O or members in a group named in an entry of type \*Lforeign_group\*O. This type of ACL entry must include a key that identifies the specific foreign cell. .LI \*Lany_other\*O \- Permissions for all authenticated principals unless those principals match a more specific entry in the ACL. .LI \*Lmask_obj\*O \- Permissions for the object mask that is applied to all entry types except \*Luser_obj\*O, \*Lother_obj\*O, and \*Lunauthenticated\*O. .LI \*Lunauthenticated\*O \- Maximum permissions applied when the accessor does not pass authentication procedures. This entry is used for principals that have failed authentication due to bad keys, principals who are entirely outside of any authentication cell, and principals who choose not to use authenticated access. Permissions granted to an unauthenticated principal are masked with this entry, if it exists. If this entry does not exist, access to unauthenticated principals is always denied. .LI \*Lextended\*O \- A special entry that allows client applications running at earlier DCE versions to copy ACLs to and from ACL Managers running at the current DCE version without losing any data. The \*Lextended\*O entry allows the application running at the lower version to obtain a printable form of the ACL. The \*Lextended\*O ACL entry has the following form: .sp .4v \*Lextended:\*O\*Vuuid.ndr.ndr.ndr.ndr.number_of_byte.data\*O .sp .4v where: .VL 1i .LI "\*Vuuid\*O" Identifies the type extended ACL entry. (This UUID can identify one of the ACL entry types described here or an as-yet-undefined ACL entry type.) .LI "\*Vndr.ndr.ndr.ndr\*O" Up to three Network Data Representation (NDR) format labels (in hexadecimal format and separated by periods) that identify the encoding of data. .LI "\*Vnumber_of_bytes\*O A decimal number that specifies the total number of bytes in \*Vdata\*O. .LI "\*Vdata\*O" The ACL data in hexadecimal form. (Each byte of ACL data is two hexadecimal digits.) The ACL data includes all of the ACL entry specifications except the permissions (described later) that are entered separately. The data is not interpreted; it is assumed that the ACL Manager to which the data is being passed can understand that data. .LE .LE .SS "Key" The \*Vkey\*O identifier (principal or group name) specifies the principal or group to which the ACL entry applies. For entries of entry type \*Lextended\*O, \*Vkey\*O is the data passed from one ACL Manager to another. A \*Vkey\*O is required for the following types of ACL entries: .ML .LI \*Luser\*O \- Requires a principal name only. .LI \*Lgroup\*O \- Requires a group name only. .LI \*Lforeign_user\*O \- Requires a fully qualified cell name in addition to the principal name. .LI \*Lforeign_group\*O \- Requires a fully qualified cell name in addition to the group name. .LI \*Lforeign_other\*O \- Requires a fully qualified cell name. .LE .SS "Permissions" The \*Vpermissions\*O argument specifies the set of permissions that defines the access rights conferred by the entry. Since each ACL Manager defines the permission tokens and meanings appropriate for the objects it controls, the actual tokens and their meanings vary. For example, the Distributed File Service, the Directory Service, and the Security Registry Service each implement a separate ACL Manager, and each can use a different set of tokens and permissions. This means that file system objects, objects in the namespace, and registry objects could each use different permissions. Use the \*Lp[ermissions]\*O subcommand to display the currently available tokens and their meanings. See the documentation for the DCE component you are using to obtain a more detailed description of its specific permissions. .LE .SH EXAMPLES .AL .LI The following example uses the interactive interface to set permissions for the \*Lunauthenticated\*O and \*Lmask_obj\*O entry type: .iS \*Csec_acl_edit> \*Lm mask_obj:rwx\*O \*Csec_acl_edit> \*Lm unauthenticated:r\*O .iE .LI The following example uses the interactive interface to set permissions for the effective user, group, and others in the ACL's cell: .iS \*Csec_acl_edit> \*Lm user_obj:crwx\*O \*Csec_acl_edit> \*Lm group_obj:rwx\*O \*Csec_acl_edit> \*Lm other_obj:rwx\*O .iE .LI The following example uses the command-line interface to invoke \*Lacl_edit\*O and assign permissions for the file \*Lprogress_chart\*O to the authenticated user \*Lmike\*O in the local cell: .zA "def, 11666, R1.1, Changed afs to fs" .iS % acl_edit /.../dresden.com/fs/walden/progress_chart -m user:mike:crwx .iE .zZ "def, 11666, R1.1, Changed afs to fs" .P Note that because this entry will be filtered through the object mask (\*Lmask_obj\*O), which specifies only \*Lrwx\*O permissions, the actual permissions will be \*Lrwx\*O, not \*Lcrwx\*O. The \*Ll(ist)\*O subcommand will show those permissions as follows: .oS user:mike:crwx #effective -rwx--- .oE .LI The following example uses the interactive interface to set permissions for the authenticated foreign user named \*Lburati\*O in the cell named \*L/.../usc-cs.uscal.edu\*O: .iS \*Csec_acl_edit> \*Lm foreign_user:/.../usc-cs.uscal.edu/sailing/staff/burati:rwx .iE .LI The following example uses the non-interactive command-line interface to invoke \*Lacl_edit\*O and set the Initial Container Creation permissions for the directory that is named \*Lwalden\*O: .zA "def, 11666, R1.1, Changed afs to fs" .iS % acl_edit /.../dresden.com/fs/walden -ic -m /user:walden:crwxid .iE .zZ "def, 11666, R1.1, Changed afs to fs" .LE .iX "-]" "Security Service commands" "\*Lacl_edit\*O" .iX "-]" "\*Lacl_edit\*O command" .iX "-]" "ACLs" "editing entries" .iX "-]" "ACLs" "viewing" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .nr H1 1 .wH "" ...\" .rm zA .rm zZ .TH "add directory"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lcdscp\*O commands" "\*Ladd directory\*O" .iX "-[" "directories" "adding attributes (CDS)" .SH NAME .PP \*Ladd directory\*O - Adds a value to a modifiable, set-valued attribute (including application-defined attributes) of a directory .wH "" .SH "SYNOPSIS" .sS \*Lcdscp add directory \*Vdirectory-name attribute-name \*L=\*O \*Vattribute-value\*O .sE .SH "ARGUMENTS" .VL .LI "\*Vdirectory-name\*O" The full name of the directory. .LI "\*Vattribute-name\*O" The name of a particular attribute. Specify only one attribute at a time. See the \*Lcds_attributes\*O file for the list of attributes that your application uses. .LI .zA "defects,4795,6238,R1.0.2, Add description" \*Vattribute-value\*O The value of a particular attribute. The value of an application-defined attribute is dependent on the type of attribute. See the \*Lcds_attributes\*O file for the list of attributes and corresponding data types that your application uses. If you enter a byte data type, you must enter an even number of digits in length. You can only enter pairs of hexadecimal values for user-defined attributes. .zZ "defects,4795,6238,R1.0.2, Add description" .wH "" .LE .SH "DESCRIPTION" .PP The \*Ladd directory\*O command adds a value to a modifiable, set-valued attribute (including application-defined attributes) of a directory. If the attribute does not exist, this command creates it. Usually, this task is performed through the client application. See the \*VDCE Administration Guide\*O for more information about attributes. .SS "Privilege Required" .PP You must have write permission to the directory. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP To add the value \*Lontario\*O to the attribute \*Lmyname\*O of a directory named \*L/.:/sales\*O, read the \*Lcds_attributes\*O file to verify that the attribute shown in the following display exists: .iS \*C OID LABEL SYNTAX 1.3.22.1.3.91 myname char\*O .iE .PP Enter the following command to assign the value \*Lontario\*O to the attribute \*Lmyname\*O: .iS \*Ccdscp> \*Ladd directory /.:/sales myname = ontario\*O .iE .wH "" .SH "RELATED INFORMATION" Commands: \*Lremove directory(1m)\*O, \*Lshow directory(1m)\*O .PP Books: \*VOSF DCE Administration Guide\*O .iX "-]" "\*Lcdscp\*O commands" "\*Ladd directory\*O" .iX "-]" "directories" "adding attributes (CDS)" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "add object"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "objects" "adding attributes" .iX "-[" "\*Lcdscp\*O commands" "\*Ladd object\*O" .SH NAME .PP \*Ladd object\*O - Adds a value to a modifiable, set-valued attribute (including application-defined attributes) of an object entry .wH "" .SH "SYNOPSIS" .PP \*Lcdscp add object\*O \*V object-name attribute-name = attribute-value\*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vobject-name\*O" The full name of the object entry. .LI "\*Vattribute-name\*O" The name of a particular attribute. Specify only one attribute at a time. See the \*Lcds_attributes\*O file for the list of attributes and corresponding data types that your application uses. .LI "\*Vattribute-value\*O" The value of a particular attribute. The value of an application-defined attribute is dependent on the type of attribute. .LE .SH "DESCRIPTION" .PP The \*Ladd object\*O command adds a value to a modifiable, set-valued attribute (including application-defined attributes) of an object entry. If the attribute does not exist, this command creates it. Usually, this task is performed through the client application. See the \*VDCE Administration Guide\*O for more information about attributes. .SS "Privilege Required" You must have write permission to the object entry. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP To add the value \*Lps\*O to the attribute \*Lprintcap\*O of an object entry named \*L/.:/subsys/deskprinter\*O, read the \*Lcds_attributes\*O file to verify that the attribute shown in the following display exists: .iS \*C OID LABEL SYNTAX 1.3.22.1.3.70 printcap char\*O .iE .PP Enter the following command to assign the value \*Lps\*O to the attribute \*Lprintcap\*O: .iS \*Ccdscp> \*Ladd object /.:/subsys/deskprinter printcap = ps\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lcreate object(1m)\*O, \*Ldelete object(1m)\*O, \*Llist object(1m)\*O, \*Lremove object(1m)\*O, \*Lset object(1m)\*O, \*Lshow object(1m)\*O .PP Books: \*VOSF DCE Administration Guide\*O .iX "-]" "objects" "adding attributes" .iX "-]" "\*Lcdscp\*O commands" "\*Ladd object\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Oct 25, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH advertise 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "DTS servers" "advertising" .iX "\*Ldtscp\*O commands" "\*Ladvertise\*O" .SH NAME .PP \*Ladvertise\*O - Configures the system as a global server by adding the server's entry to the cell profile .SH "SYNOPSIS" .zA "defect,6211,R1.0.3,add control program name" .sS \*Ldtscp advertise\*O .sE .zZ "defect,6211,R1.0.3,add control program name" .SH "DESCRIPTION" .PP The \*Ladvertise\*O command causes DTS to forward the name and attributes of the server to CDS by binding the server's protocol tower to the CDS object and adding an entry for the server in the cell profile. Once the server's entry is in the cell profile, it is configured as a global server, and servers outside of the LAN can access it. .SS "Privilege Required" .PP You must have write permission on the ACL associated with the DTS entity in order to execute the command. ...\".SH "EXIT VALUES" ...\".PP ...\".VL 8m ...\".LI "System Error" ...\"The command failed due to an operating system ...\"error. ...\".LI "Wrong State" ...\"The command failed because the DTS ...\"entity is in the \*Loff\*O state. ...\".LE .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .PP .iS \*Cdtscp>\*O \*Ladvertise\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lunadvertise (1m)\*O .\" $Header: arp.1m,v 72.5 94/09/20 15:36:43 ssa Exp $ .TA a .TH arp 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME arp \- address resolution display and control .SH SYNOPSIS .CR arp .I hostname .PP .C arp -a .RI \|[ system ]\| .RI \|[ core ]\| .PP .C arp -d .I hostname .PP .C arp -f .I filename .PP .C arp -s .I hostname address .RC \|[ temp ]\| .RC \|[ pub ]\| .RC \|[ trail ]\| .RC \|[ rif .IR rif-address ]\| .PP .C arp \-sfc .I hostname nport_id .RC [ ipa .IR ipa_value\| ] .SH DESCRIPTION The .CR arp command displays and modifies the Internet-to-Ethernet and Internet-to-Fibre Channel address translation tables used by the Address Resolution Protocol (\s-1ARP\s0). .SS Options .CR arp has the following keyletter options: .RS .TP 10 none (first form above) Display the current .SM ARP entry for .IR hostname , which must either appear in the hostname database (see .IR hosts (4)), or be a .SM DARPA Internet address expressed in Internet standard "dot" notation. .TP .CR -a Display all current .SM ARP entries by reading the table from file .I core (default .CR /dev/kmem ) based on the kernel file .I system (default .CR /stand/vmunix ). .TP .CR -d If an .SM ARP entry exists for the host called .IR hostname , delete it. .TP .CR -f Read file .I filename and set multiple entries in the .SM ARP tables. Fibre Channel entries in the file should be of the form: .RS .IP .I .C -sfc hostname nport_id .RE .IP Other Entries in the file should be of the form: .RS .IP .I hostname address .RC [ temp ] .RC [ pub ] .RC [ trail ] .RC [ rif .IR rifAddress\| ] .RE .IP The argument meanings are the same as for the .CR -s option. .TP .CR -s Create an .SM ARP entry for the host called .I hostname with the hardware station address .IR address . The hardware station address is given as six hexadecimal bytes separated by colons. If an .SM ARP entry already exists for .IR hostname , the existing entry is updated with the new information. .IP The entry is permanent unless the word .CR temp is given in the command. .IP If the word .CR pub is specified, the entry is published, which means that this system will act as an .SM ARP server responding to requests for .I hostname even though the host address is not its own. .IP The word .CR trail indicates that trailer encapsulations can be sent to this host. .IP The word .CR rif specifies source routing information used for token ring networks. This information allows you to specify the particular bridge route which the token ring packet should be delivered. .I rif-address is given as an even number of hexadecimal bytes separated by colons, up to a maximum of 16 bytes. .TP .C \-sfc Create a permanent .SM ARP entry for the Fibre Channel host called .I hostname with the N_Port address .I nport_id. The N_Port address is given as three hexadecimal bytes separated by colons. If an .SM ARP entry already exists for .IR hostname , the existing entry is updated with the new information. The word ipa specifies the Initial Process Associator value for Fibre Channel nodes. This information allows a user to specify the particular process which the Fibre Channel packet should be delivered to within a Fibre Channel node. .CR ipa_value is given as four hexadecimal bytes separated by colons. The default value for .CR ipa_value is zero. This value is not required for HP-to-HP communications. This option is applicable and only valid on HP 9000 systems with Fibre Channel Links. .RE .PP You need superuser privilege to use the .CR -d , .CR -f , .CR -s and .CR -sfc options. .SH WARNINGS .SM HP 9000 systems can receive trailer packets but do not send them. Setting the .CR trail flag has no effect. .SH AUTHOR .CR arp was developed by the University of California, Berkeley. .SH SEE ALSO ifconfig(1M), lanconfig(1M), inet(3N), hosts(4), arp(7P). .\" .\" index@\f4arp\f1 \- address resolution display and control@@@\f3arp(1M)\f1 .\" index@address resolution display and control@@@\f3arp(1M)\f1 .\" index@display address resolution@@@\f3arp(1M)\f1 .\" index@control address resolution@@@\f3arp(1M)\f1 .\" .\" toc@\f3arp(1M)\f1:\0\0\f4arp\f1@@@address resolution display and control .\" @(#) $Header: arrayinfo.1m,v 1.2 95/12/20 13:22:08 hmgr Exp $ .TA a .TH arrayinfo 1M .SH NAME arrayinfo \- describe general characteristics of a disk array .SH SYNOPSIS .PP .C arrayinfo .RC [ -j .RC | -m .RC | -s .RC | -ar .RC | -dr ] .I device_file .br .SH DESCRIPTION .PP .C arrayinfo displays summarized information for the .SM SCSI disk array associated with the character device file .IR device_file . .PP By default .C arrayinfo returns the following information: .TP 3 .PD 0 \(bu array vendor ID .TP \(bu array product ID .TP \(bu number of attached disk mechanisms .TP \(bu vendor/product type of attached disk mechanisms. (Assumes all are the same type) .PD .PP .RE NOTE: The array vendor ID, and product ID information are constant, regardless of the type and quantity of disks attached. .PP .SS Options: .PP .C arrayinfo recognizes the following options: .PP .RS 3 .TP 4 .C -j Displays the current setting of certain jumper switches on each disk mechanism, including: .RS 4 .PP .PD 0 .PP .TP 37 \(bu Automatic Spin Up ( 0 Disable / 1 Enable ) .PP .TP 37 \(bu Parity Error Detect ( 0 Disable / 1 Enable ) .PP .TP 37 \(bu Unit Attention ( 0 Enable / 1 Disable ) .PP .TP 37 \(bu Initiate Synchronous Data Transfer ( 0 Disable / 1 Enable ) .PP \(bu SCSI target address of the mechanism .PD .PP .RE .TP 4 .C -m Displays array mapping information, including: .RS 4 .PP .PD 0 .PP .TP 3 \(bu The disk vendor, and model type of each disk in the array .TP \(bu The current status of each disk in the array, as determined by the array controller. .TP \(bu The array sub-channel, and sub-channel addresses for each disk in the array. .PD .PP .RE .TP 4 .C -s Displays serial numbers. This option displays serial number information for the disk array controller, and all attached disk mechanisms. .TP 4 .C -ar Displays array revision information. This option displays revision information for the hardware, firmware, and software of the array controller. .TP 4 .C -dr Display disk revisions. This option displays revision information for the hardware, and firmware of each disk in the array. .RE .RS 0 .SH RETURN VALUE .PP .PP .C arrayinfo returns the following values: .RS 3 .TP 3 .PD 0 .B " 0" Successful completion .TP 3 .B -1 Command failed (an error occurred). .RE .PD .PP .SH DEPENDENCIES .PP This utility is only compatible with .SM HP C2430 disk arrays. .PP .B Series 700: .RS 2 .PP .C arrayinfo must be used with a device file mapped to a unit address that is not in use by the array controller (unconfigured). By convention unit addresses 6 and 7 should not be configured. Array information should be accessible by addressing either of these unit addresses. .RE .PP .B Series 800: .RS 2 .PP Any device file (\c .SM LU\c ) that is mapped to the disk array can be used to access the array information. .RE .SH AUTHOR .PP .C arrayinfo was developed by Hewlett-Packard. .PP .SH SEE ALSO dsp(1M) .\" .\" index@\f4arrayinfo\f1 \-describe disk array characteristics@@@\f3arrayinfo(1M)\f1 .\" index@disk array, describe characteristics of@@@\f3arrayinfo(1M)\f1 .\" .\" toc@\f3arrayinfo(1M)\f1:\0\0\f4arrayinfo\f1@@@describe disk array characteristics .\" .\" fileset_database@arrayinfo.1m SYS-ADMIN-MAN .\" @(#) $Header: arrayscan.1m,v 1.11 96/04/24 11:31:55 hmgr Exp $ .TA a .TH arrayscan 1M .SH NAME arrayscan \- search system for disk arrays .SH SYNOPSIS .PP .B " arrayscan " .br .SH DESCRIPTION .PP .B arrayscan searches the system I/O buses to locate the address(es) of attached .SM HP disk array devices. The utility can also be used to determine which logical units are configured on a disk array. .PP .B arrayscan performs several functions, including: .RS 3 .TP 9 \(bu Ensuring device special files exist. .B arrayscan verifies that block and character device special files exist for all .SM LUNs configured. On Series 700 systems, device files are created for all possible .SM LUNs. .TP \(bu Ensuring disk array software was downloaded. .B arrayscan verifies that the disk array software has been downloaded for each disk array it encounters. If .B arrayscan encounters a disk array that does not have disk array software loaded, it automatically downloads the array software. .TP \(bu Updating .BR monitor , and .B pscan device lists. Two files, .BR /etc/hpC2400/hparray.devs , and .B /etc/hpC2400/hparray.luns are updated by .BR arrayscan . .B /etc/hpC2400/hparray.devs is used by the monitor daemon .RB ( /usr/lbin/hpC2400/arraymond ) to determine which devices to monitor. .B /etc/hpC2400/hparray.luns is used by the parity scan utilities .RB ( pscan ,\0 scn , .RB and\0 rpr ) to determine which .SM LUNs to monitor. .RE .PP .SH RETURN VALUE .B arrayscan returns the following values: .RS 3 .TP .B " 0" Successful completion .PD .TP .B -1 Command failed (an error occurred). .PD .PP .RE .SH DIAGNOSTICS AND ERRORS Errors can originate from problems with: .RS .TP 3 \(bu .B arrayscan .TP \(bu .SM SCSI (device level) communications .TP \(bu system calls .RE .PP .SS Error messages generated by arrayscan: .TP .B "arrayscan: Cannot access lock file. Create an empty file " Two semaphore files are used by .BR arrayscan , .BR /etc/hpC2400/pscan.lock , and .B /etc/hpC2400/monitor.lock. If these files do not exist when .B arrayscan begins, it assumes that the monitor daemon is executing. If the period of time required for the monitor daemon to execute expires, and the files still do not exist, it is assumed that they need to be created. You can create these files, if necessary, using the .B touch command (see .BR touch (1)); .TP .B "arrayscan: Unable to open Array Parity Scan list " .B arrayscan updates .BR /etc/hpC2400/hparray.luns , and .B /etc/hpC2400/hparray.devs. .B arrayscan was unable to write to this file. .TP .B "arrayscan: Error from process insf." An error occurred while executing .B insf (see .BR insf (1M)). .B insf is used by .B arrayscan on Series 800 systems to create device files for newly configured disk array devices. .TP .B "arrayscan: Error from process ioscan." An error occurred while executing .BR ioscan . .B ioscan is used by .B arrayscan to scan for all devices. Disk array devices are filtered from the ioscan output. .TP .B "arrayscan: No SCSI devices identified. Check SCSI connections." No .SM SCSI devices were identified. Check .SM SCSI cables and power connections and retry the command. .TP .PD 0 .B "arrayscan: Unable to create char device special file" .B "for path " .IP .B arrayscan will create character, and block device files for all disk array devices it encounters. .B arrayscan was unable to create the device file. .PD .TP .B "arrayscan: Insufficient dynamic memory" An attempt to allocate dynamic memory failed. .PD .PP .RE .SH DEPENDENCIES This utility is supported only on .SM HP C2425D, HP C2430D, HP C3595A and .SM HP C3596A disk array devices. .SH AUTHOR .B arrayscan was developed by HP. .SH FILES .PP .PD 0 .TP 25 .B /etc/hpC2400/hparray.luns .TP .B /etc/hpC2400/hparray.devs .TP .B /etc/hpC2400/pscan.lock .TP .B /etc/hpC2400/monitor.lock .\" .\" index@\f4arrayscan\f1 \- search system for disk arrays@@@\f3arrayscan(1M)\f1 .\" index@disk array, search system for@@@\f3arrayscan(1M)\f1 .\" index@scan the \s-1I/O\s0 system for disk arrays@@@\f3arrayscan(1M)\f1 .\" index@system, scan for disk arrays@@@\f3arrayscan(1M)\f1 .\" .\" toc@\f3arrayscan(1M)\f1:\0\0\f4arrayscan\f1@@@search system for disk arrays .\" .\" fileset_database@arrayscan.1m SYS-ADMIN-MAN .\" $Header: asecure.1m,v 76.1 95/06/20 14:30:28 ssa Exp $ .TA a .TH asecure 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME asecure \- control access to Audio on a workstation .SH SYNOPSIS .C /opt/audio/bin/asecure \f1[\f3-CdelP +h \f2host \f3-h \f2host \f3+p \f2user \f3-p \f2user \f3+u \f2user \f3-u \f2user \f3+b \f2host\f1,\f2user \f3-b \f2host\f1,\f2user\f1] .SH DESCRIPTION On Series 700 workstations, audio is secured so that only the user on the local workstation can access audio. You use the .C asecure command to modify audio security. This command does not apply to X stations; on an X station, access to audio is unrestricted. .PP To modify audio security, become root on the local workstation where you want make a change. Then, use .C asecure as follows: .sp .C /opt/audio/bin/asecure -C .sp When prompted, enter any meaningful password. Issuing .C asecure -C creates the Audio Security File (ASF). The ASF contains information that determines which hosts and users can access the Aserver, and which users (other than the superuser) can modify the ASF. .PP If needed, you can allow unrestricted access to audio on this workstation. To remove audio security, issue this command: .sp .C /opt/audio/bin/asecure -d .sp If instead, you wish to modify security, you use .C asecure to make changes to the information in the ASF. (Because the ASF is a binary file, we do not recommend using an editor on this file.) You can use .C asecure to make these types of changes: .RS .TP 3 \(bu Allow all clients from a remote host to access the server. .TP \(bu Allow specific users from all other hosts to access the server. .TP \(bu Allow a specific user from a specific host to access the server. .TP \(bu Disable access control, allowing complete unrestricted access to the server, but leaving the ASF intact. .RE .PP Every operation that creates, reinitializes, or changes the contents of the ASF is logged in the .C /var/adm/audio/asecure_log file, so that you can track any changes to the ASF. .PP .SS OPTIONS .C asecure supports the following options: .RS .TP 15 .CI +b|-b \0host,user Add/delete .IR hostname,username pair. You must be either superuser or a .C privileged user to do this. You can supply more than one .IR hostname,username pair separated by blanks. .IP To use either the .C +b or .C -b options, you MUST supply at least one .IR hostname,username pair. This option will not work without a pair. .TP .C -C Create a new ASF file, called the .C audio.sec file. Access control default is enabled with no entries in the access list. Aserver can now be accessed only by local users on the host machine. If an .C audio.sec file already exists, it is re-initialized. .IP You must be superuser to execute this option. This option is mutually-exclusive of all other options. .IP This option requires a password. This is an extra layer of protection for the contents of the ASF. It is designed to prevent surreptitious manipulation of the ASF. If you are creating a new ASF, you are prompted for a password and an encrypted copy of that password is stored in the new ASF. .IP If the ASF already exists, you are prompted for the password. If your password matches the password stored in the ASF, the ASF is then re-initialized. .TP .C -d Disable access control to the Aserver. This allows unrestricted access by all clients. .TP .C -e Enable access control to the Aserver. This restricts access to clients listed in the ASF. Enabled is the default state. .TP .CI +h|-h \0host Add/delete .IR hostnames for ALL users. You must be either superuser or a .C privileged user to do this. You can supply more than one .IR hostname separated by blanks. .TP .C -l List the contents of the ASF. This option shows a list of the hostnames and/or usernames that have access to the Aserver. .TP .C -P Change password for .C audio.sec file. You must be superuser to do this. You are prompted once for the old password, then prompted twice for the new password. .TP .CI +p|-p \0user Add/delete \f3privileged users\f1. You must be superuser to do this and must enter the password given when the ASF was created (see .C -C option). To see a list of \f3privileged users\f1, you must be superuser and use the .C -l option. .TP .CI +u|-u \0user Add/delete .IR usernames for ALL hosts. You must be either superuser or a .C privileged user to do this. You can supply more than one .IR username separated by blanks. .SH EXAMPLES List entries in access list. .IP .C /opt/audio/bin/asecure -l .PP Disable access control. This means anyone can connect to Aserver without restriction. .IP .C /opt/audio/bin/asecure -d .PP Add .IR moonbeam host for all users to access list. Remove .IR pluto host for all users from access list. .IP .C /opt/audio/bin/asecure +h .IR moonbeam .C -h .IR pluto .PP Add user .IR comet for hosts .IR saturn and .IR mercury to access list. .IP .C /opt/audio/bin/asecure +b .IR saturn,comet .IR mercury,comet .PP Add user .IR comet to access list for all hosts. Remove users .IR venus and .IR neptune from access list for all hosts. .IP .C /opt/audio/bin/asecure +u .IR comet .C -u .IR venus .IR neptune .PP Create new access list. .IP .C /opt/audio/bin/asecure -C .SH AUTHOR .C asecure was developed by .SM HP. .SH FILES .TP 38 .CR /var/opt/audio/asecure_log asecure log pathname .PD 0 .TP .CR /etc/opt/audio/audio.sec ASF pathname .PD .SH SEE ALSO .na audio(5), asecure(1m), aserver(1m), attributes(1), convert(1), send_sound(1). .PP .IR "Using the Audio Developer's Kit" .\" .\" index@\f2asecure\f1 \- Audio@@@\f3asecure(1m)\f1 .\" index@asecure@@@\f3asecure(1m)\f1 .\" index@HP-UX Audio@@@\f3Audio(1)\f1 .\" .\" toc@\f3asecure(1m)\f1:\0\0\f2asecure\f1@@@Audio .\" .\" links@asecure.1m Asecure.1m .\" .\" fileset_database@asecure.1m AUDIO-MAN .\" $Header: aserver.1m,v 76.1 95/06/20 14:30:48 ssa Exp $ .TA a .TH aserver 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME Aserver \- start the audio server .SH SYNOPSIS .C /opt/audio/bin/Aserver \0-f .SS Remarks: The .C Aserver command starts the HP-UX Audio server, which can run on a system with audio hardware. See .C Audio(5) for information about which systems have audio hardware. The .C -f option forces the starting of the Audio server; this option is only needed if the Aserver has problems starting. .SH DESCRIPTION .SS The Audio Server Before using any audio tools such as the .C Audio Editor, the system or X station must be running two audio server processes, called .C Aserver. On a Series 700, the Remote Procedure Call daemon .C (rpcd) must also be running. .PP Normally, the Aserver processes and .C rpcd start automatically when the system is booted. If problems occur on an ENTRIA or ENVIZEX X station, see the X station owner's manual. On a Series 700 Audio hardware, first check if .C rpcd is running. Type the following: .sp .C ps -e | grep rpcd .sp If it is running, you see a line similar to the following. .sp .C 604 ? 0:36 rpcd .sp If it is not running, see HP 9000/DCE documentation for information on restarting it. If .C rpcd is running, verify that the Aserver is running. Type: .sp .C ps -e | grep Aserver .sp If the Aserver is running you will see lines similar to the following, which indicate the presence of the two Aserver processes: .sp .C \0\01 ? 0:00 Aserver .br .C 224 ? 0:00 Aserver .sp If it is not running, become root and restart it as follows: .sp .C /opt/audio/bin/Aserver .sp If it fails to start, reissue the command with the .C -f option: .sp .C /opt/audio/bin/Aserver -f .sp .PP .SS "Using Audio over the Network" From a workstation, you can also use the Audio Editor and Control Panel over the network. However, the remote system is where the actual playback and recording occur. .PP The local workstation (or audio client) can be any Series 700 system. The remote system (or audio server) can be a Series 700 or an X station with audio hardware and must have the Aserver processes running. If the server is a workstation, it must also allow access from remote clients (see .C asecure(1m)) and must have .C rpcd running. .PP To make the system an audio client, set the .C AUDIO variable by modifying the .C $HOME/.vueprofile file as follows: .RS .TP 10 .C Korn, Bourne, and POSIX Shells: AUDIO=system_name; export AUDIO .TP .C C Shell:\0\0\0\0\0\0\0\0\0\0\0 setenv AUDIO system_name .RE .PP For .I system_name, identify the workstation or X Station running the Aserver. .PP If the AUDIO variable is not set, the Audio Library attempts to use to the Aserver on the system defined by the DISPLAY variable. If neither DISPLAY nor AUDIO is set, the Aserver on the local machine is used. .RE .SH DEPENDENCIES The Audio Server must run on a system that has audio hardware. Note that HP-UX for the 8MB 705 System does not include audio software. .SH AUTHOR The Audio Server was developed by .SM HP. .SH SEE ALSO .na audio(5), asecure(1m), attributes(1), convert(1), send_sound(1). .PP .IR "Using the Audio Developer's Kit" .\" .\" index@\f2aserver\f1 \- Audio@@@\f3aserver(1m)\f1 .\" index@aserver@@@\f3aserver(1m)\f1 .\" index@Audio@@@\f3Audio(1)\f1 .\" .\" toc@\f3aserver(1m)\f1:\0\0\f2aserver\f1@@@Audio .\" .\" links@aserver.1m Aserver.1m .\" .\" fileset_database@aserver.1m AUDIO-MAN .\" $Header: audevent.1m,v 72.4 94/07/03 15:47:51 ssa Exp $ .TA a .TH audevent 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME audevent \- change or display event or system call audit status .SH SYNOPSIS .C audevent .RC [ -P \(or -p ] .RC [ -F \(or -f ] .RC [ -E ] .RC [\|[ -e .IR event\| ]\0...\|] .RC [ -S ] .RC [\|[ -s .IR syscall\| ]\0...\|] .SH DESCRIPTION .C audevent changes the auditing status of the given events or system calls. The .I event is used to specify names associated with certain self-auditing commands; .I syscall is used to select related system calls. .PP If neither .CR -P , .CR -p , .CR -F , nor .C -f is specified, the current status of the selected events or system calls is displayed. If no events or system calls are specified, all events and system calls are selected. .PP If the .C -E option is supplied, it is redundant to specify events with the .C -e option; this applies similarly to the .C -S and .C -s options. .PP .C audevent takes effect immediately. However, the events and system calls specified are audited only when called by a user currently being audited (see .IR audusr (1M)). A list of valid events and associated syscalls is provided in .IR audit (5). .PP Only the super-user can change or display audit status. .SS Options .C audevent recognizes the following options and command-line arguments: .RS .TP 15 .C -P Audit successful events or system calls. .TP .C -p Do not audit successful events or system calls. .TP .C -F Audit failed events or system calls. .TP .C -f Do not audit failed events or system calls. .TP .C -E Select all events for change or display. .TP .CI -e " event" Select .I event for change or display. .TP .C -S Select all system calls for change or display. .TP .CI -s " syscall" Select .I syscall for change or display. .RE .PP The following is a list of the valid .I events and the associated .IR syscall s (if any): .RS .TP 15 .C create Object creation (\c .CR creat() , .CR mkdir() , .CR mknod() , .CR msgget() , .CR pipe() , .CR semget() , .CR shmat() , .CR shmget() ) .TP .C delete Object deletion (\c .CR msgctl() , .CR rmdir() , .CR semctl() ) .TP .C moddac Discretionary access control (DAC) modification (\c .CR chmod() , .CR chown() , .CR fchmod() , .CR fchown() , .CR fsetacl() , .CR setacl() , .CR umask() ) .TP .C modaccess Non-\c DAC modification (\c .CR chdir() , .CR chroot() , .CR link() , .CR setgid() , .CR setuid() , .CR rename() , .CR setgroups() , .CR setresgid() , .CR setresuid() , .CR shmctl() , .CR shmdt() , .CR unlink() ) .TP .C open Object opening (\c .CR open() , .CR execv() , .CR execve() , .CR ptrace() , .CR truncate() , .CR ftruncate() ) .TP .C close Object closing (\c .CR close() ) .TP .C process Process operations (\c .CR fork() , .CR exit() , .CR kill() , .CR vfork() , .CR nsp_init() ) .TP .C removable Removable media events (\c .CR mount() , .CR umount() , .CR vfsmount() ) .TP .C login Logins and logouts .TP .C admin administrative and superuser events (\c .CR audctl() , .CR audswitch() , .CR stime() , .CR reboot() , .CR setaudid() , .CR setaudproc() , .CR setdomainname() , .CR setevent() , .CR sethostid() , .CR setprivgrp() , .CR settimeofday() , .CR swapon() ) .TP .C ipccreat Interprocess Communication (IPC) object creation (\c .CR bind() and .CR socket() ) .TP .C ipcopen IPC object opening (\c .CR accept() and .CR connect() ) .TP .C ipcclose IPC object deletion (\c .CR shutdown() ) .TP .C ipcdgram IPC datagram (\c .CR sendto() and .CR recvfrom() ) .TP .C uevent1 User-defined event 1 .TP .C uevent2 User-defined event 2 .TP .C uevent3 User-defined event 3 .SH AUTHOR .C audevent was developed by HP. .SH SEE ALSO audisp(1M), audomon(1M), audsys(1M), audusr(1M), getevent(2), setevent(2), audit(4), audit(5). .\" .\" index@\f4audevent\f1 \- change or display event or system call audit status@@@\f3audevent(1M)\f1 .\" index@\f1change or display event or system call audit status@@@\f3audevent(1M)\f1 .\" index@\f1display or change event or system call audit status@@@\f3audevent(1M)\f1 .\" index@\f1event or system call audit status, change or display@@@\f3audevent(1M)\f1 .\" index@\f1system call or event audit status, change or display@@@\f3audevent(1M)\f1 .\" index@\f1status, audit, of event or system call, change or display@@@\f3audevent(1M)\f1 .\" index@\f1audit \- change or display event or system call audit status@@@\f3audevent(1M)\f1 .\" .\" toc@\f3audevent(1M)\f1:\0\0\f4audevent\f1@@@change or display event or system call audit status .\" .\" fileset_database@audevent.1m SYS-ADMIN-MAN .\" $Header: audisp.1m,v 78.1 96/04/05 11:16:03 ssa Exp $ .TA a .TH audisp 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME audisp \- display the audit information as requested by the parameters .SH SYNOPSIS .C audisp .RB [ \|\-u .IR username\| ] .RC [ \|\-e .IR eventname\| ] .RC [ \|\-c .IR syscall\| ] .RC [ \|\-p\| ] .RC [ \|\-f\| ] .RC [ \|\-l .IR ttyid\| ] .RC [ \|\-t .IR start_time\| ] .RC [ \|\-s .IR stop_time\| ] .IR audit_filename (s)\0... .SH DESCRIPTION .CR audisp analyzes and displays the audit information contained in the specified one or more audit files, .IR audit_filename (s). The audit files are merged into a single audit trail in time order. Although the entire audit trail is analyzed, .CR audisp allows you to limit the information displayed, by specifying options. This command is restricted to privileged users. .PP Any unspecified option is interpreted as an unrestricted specification. For example, a missing .CI \-u " username" option causes all users' audit information in the audit trail to be displayed as long as it satisfies all other specified options. By the same principle, citing .CI \-t " start_time" without .CI \-s " stop_time " displays all audit information beginning from .I start_time to the end of the file. .PP .CR audisp without any options displays all recorded information from the start of the audit file to the end. .PP Specifying an option without its required parameter results in error. For example, specifying .C \-e without any .I eventname returns with an error message. .SS Options .TP 15 .CI \-u " username" Specify the login name .RI ( username ) about whom to display information. If no .RI ( username ) is specified, .CR audisp displays audit information about all users in the audit file. .TP .CI \-e " eventname" Display audit information of the specified event types. The defined event types are .CR create , .CR delete , .CR moddac , .CR modaccess , .CR open , .CR close , .CR process , .CR removable , .CR login , .CR admin , .CR ipccreat , .CR ipcopen , .CR ipcclose , .CR ipcdgram , .CR uevent1 , .CR uevent2 , and .CR uevent3 (see .IR audevent (1M)). .TP .CI \-c " syscall" Display audit information about the specified system calls. .TP .C \-p Display only successful operations that were recorded in the audit trail. No user event that results in a failure is displayed, even if .I username and .I eventname are specified. .IP The .C \-p and the .C \-f options are mutually exclusive; do not specify both on the same command line. To display both successful and failed operations, omit both .C \-p and .C \-f options. .TP .C \-f Display only failed operations that are recorded in the audit trail. .TP .CI \-l " ttyid" Display all operations that occurred on the specified terminal .RI ( ttyid ) and were recorded in the audit trail. By default, operations on all terminals are displayed. .TP .CI \-t " start_time" Display all audited operations occurring since .IR start_time , specified as .IRmmddhhmm [ yy ] (month, day, hour, minute, year). If no year is given, the current year is used. No operation in the audit trail occurring before the specified time is displayed. .TP .CI \-s " stop_time" Display all audited operations occurring before .IR stop_time , specified as .IR mmddhhmm [ yy ] (month, day, hour, minute, year). If no year is given, the current year is used. No operation in the audit trail occurring after the specified time is displayed. .SH AUTHOR .CR audisp was developed by HP. .SH SEE ALSO audevent(1M), audit(4), audit(5). .\" .\" index@\f2audisp\f1 \- display audit information as requested by parameters@@@\f3audisp(1M)\f1 .\" index@display audit information as requested by parameters@@@\f3audisp(1M)\f1 .\" index@audit information, display as requested by parameters@@@\f3audisp(1M)\f1 .\" index@information, audit, display as requested by parameters@@@\f3audisp(1M)\f1 .\" .\" toc@\f3audisp(1M)\f1:\0\0\f2audisp\f1@@@display audit information as requested by parameters .\" .\" fileset_database@audisp.1m@SYS-ADMIN-MAN ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" .rm zA .rm zZ .TH auditd "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "enh,10234,R1.1,new manpage." .SH NAME \*Lauditd\*O - Starts the DCE Audit Daemon. .iX "\*Lauditd\*O command" .SH "SYNOPSIS" .zA "def,11686,R1.1,remove -i option" .zZ "def,11686,R1.1,remove -i option" .sS \*Lauditd\*O [\*L-t\*O \*Vtrail_file\*O] [\*L-a\*O] [\*L-s\*O \*Vsize\*O] [\*L-wrap\*O] [\*L-w\*O \*Vsvc_route\*O] [\*L-d \*O\*Vdebug_level\*O] .sE .SH "OPTIONS" .VL 1i .zA "def,11686,R1.1,remove -i option" .zZ "def,11686,R1.1,remove -i option" .LI "\*L-t\*O" \*Vtrail\*O" Specifies the pathname of the audit trail file used by the Audit daemon. The default path of the audit trail file is \*Vdcelocal\*O\*L/var/aud/adm/central_trail\*O. If an audit trail file name (instead of an absolute pathname) is specified, the file will be created in the \*Vdcelocal\*O\*L/var/aud/adm/\*O directory. .LI "\*L-a\*O" Audits the Audit daemon's control interface access. .LI "\*L-s\*O \*Vsize\*O" Sets a warning threshold on the size of the audit trail file. The Audit daemon displays a warning message each time an audit record is appended to the audit trail after the threshold has been reached. .LI "\*L-wrap\*O" Wraps the recording of audit events to the beginning of the audit trail file when its size limit is reached. The default action when the size limit has been reached is to stop auditing. .LI "\*L-w\*O \*Vsvc_route\*O" Specifies where each level of serviceability messages are routed. The \*Vsvc_route\*O argument is divided into three fields, separated by colons - the level, a routing identifier, and a routing parameter: .P \*Vseverity\*O:\*Vhow\*O:\*Vwhere\*O .P See svcroute(5) for possible values for these fields. .LI "\*L-d\*O \*Vdebug_level\*O Specifies debugging level of sub-components. The \*Vdebug_level\*O argument contains four fields separated by a colon: .P \*Vcomponent\*O:\*Vflags\*O:\*Vhow\*O:\*Vwhere\*O .P See svcroute(5) for possible values of these fields. .LE .P .SH "DESCRIPTION" .PP The \*Lauditd\*O command starts the Audit daemon. The Audit daemon must be run on the host before the audit clients. .P The Audit daemon can only service audit clients that are on the host where it is running. Thus, an Audit daemon must be installed and run on every host in the cell that has audit clients (audit clients include DCE servers and user-written application servers). .P The Audit daemon has two functions. It maintains the filter files which are shared by all audit clients running on the host. It also provides an audit record logging service to these clients. .iX "Audit daemon" .zA "def,11686,R1.1,Added info about machine principal" .P The Audit daemon runs under the local host's machine principal identity (\*Lhost/\*O\*Vhostname\*O/\*Lself\*O). .zZ "def,11686,R1.1,Added info about machine principal" .P .zA "def,10220,R1.1,Remove reference to rpcd and sec_clientd" A DCE Host daemon (\*Ldced\*O) must be running on the local host when \*Lauditd\*O is started. Typically, \*Ldced\*O and \*Lauditd\*O are started at boot time. The \*Lauditd\*O process places itself in the background and sends messages indicating it is ready to service requests for updating or querying filters and logging audit records. .zZ "def,10220,R1.1,Remove reference to rpcd and sec_clientd" .SS "Privileges Required" .PP .zA "enh,12210,R1.1,added info about audit-admin group" You must be logged into a privileged account (\*Lcell_admin\*O or a member of the \*Laudit-admin\*O group) to be able to run \*Lauditd\*O. .iX "\*Lauditd\*O command" "privileges required to run" .zZ "enh,12210,R1.1,added info about audit-admin group" .SH "EXAMPLES" .AL .LI The following example starts the Audit daemon using the default audit trail file (\*Vdcelocal\*O\*L/var/aud/adm/central_trail\*O): .iX "audit trail file" .oS $ \*Lauditd\*O .oE .PP .LI The following example starts the Audit daemon and specifies \*Lmy_trail_file\*O as the audit trail file. .oS $\*Lauditd -t my_trail_file \*O .oE .PP .LI The following example starts the Audit daemon and specifies where each level of serviceability messages is going to be routed. .oS $ \*Lauditd -w FATAL:FILE:/dev/console -w NOTICE:FILE:/opt/dcelocal/var/audit/adm/svc_log\*O .oE .PP .LI The following example starts the Audit daemon and specifies the debugging level. .oS $ \*Lauditd -d 1,esl.9\*O .oE .LE .PP .SH "RELATED INFORMATION" .PP \*Laud(1m)\*O, \*Laudevents(1m)\*O, \*Laudfilter(1m)\*O, \*Laudtrail(1m)\*O, \*Ldcecp(1m)\*O. .zZ "enh,10234,R1.1,new manpage." ...\" .DD "auditd(.8) \ ...\" audit daemon \ .\" $Header: audomon.1m,v 76.1 95/06/20 14:42:17 ssa Exp $ .TA a .TH audomon 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME audomon \- audit overflow monitor daemon .SH SYNOPSIS .C /usr/sbin/audomon .RC [ \|\-p .IR fss\| ] .RC [ \|\-t .IR sp_freq\| ] .RC [ \|\-w .IR warning\| ] .RC [ \|\-v\| ] .RC [ \|\-o .IR output_tty\| ] .SH DESCRIPTION .CR audomon monitors the capacity of the current audit file and the file system on which the audit file is located, and prints out warning messages when either is approaching full. It also checks the audit file and the file system against 2 switch points: .I FileSpaceSwitch .SM (FSS) and .I AuditFileSwitch .SM (AFS) and if either is reached, audit recording automatically switches to the backup audit file if it is available. .PP The .I FileSpaceSwitch .SM (FSS) is specified as a percentage of the total disk space available. When the file system reaches this percentage, .CR audomon looks for a backup audit file. If it is available, recording is switched from the audit file to the backup file. .PP The .I AuditFileSwitch .SM (AFS) is specified (using .IR audsys (1M)) by the size of the audit file. When the audit file reaches the specified size, .CR audomon looks for a backup audit file. If it is available, recording is switched from the audit file to the backup file (see .IR audsys (1M) for further information on use of this parameter). .PP If either switch point is reached but no backup file is available, .CR audomon issues a warning message. .PP .CR audomon is typically spawned by .CR /sbin/init.d/auditing (as part of the .IR init (1M) start-up process) when the system is booted up. Once invoked, .CR audomon monitors, periodically sleeping and ``waking up'' at intervals. Note that .CR audomon does not produce any messages when the audit system is disabled. .PP .CR audomon is restricted to privileged users. .SS Options .TP 15 .CI \-p " fss" Specify the .I FileSpaceSwitch by a number ranging from 0 to 100. When the audit file's file system has less than .I fss percent free space remaining, .CR audomon looks for a backup file. If available, the backup file is designated as the new audit file. If no backup file is available, .CR audomon issues a warning message. .IP The .I fss parameter should be a larger number than the .I min_free parameter of the file system to ensure that the switch takes place before .I min_free is reached. By default, .I fss is 20 percent. .TP .CI \-t " sp_freq" Specify the wake-up switch-point frequency in minutes. The wake-up frequency at any other time is calculated based on .I sp_freq and the current capacity of the audit file and the file system. The calculated wake-up frequency at any time before the switch points is larger than .IR sp_freq . As the size of the audit file or the file system's free space approaches the switch points, the wake-up frequency approaches .IR sp_freq . .I sp_freq can be any positive real number. Default .I sp_freq is 1 (minute). .TP .CI \-w " warning" Specify that warning messages be sent before the switch points. .I warning is an integer ranging from 0 through 100. The higher the .IR warning , the closer to the switch points warning messages are issued. For example, .I warning = 50 causes warning messages to be sent half-way before the switch points are reached. .I warning = 100 causes warning messages to be sent only after the designated switch points are reached and a switch is not possible due to a missing backup file. By default, .I warning is 90. .TP .C \-v Make audomon more verbose. This option causes .CR audomon to also print out the next wake-up time. .TP .CI \-o " output_tty" Specify the tty to which warning messages are directed. By default, warning messages are sent to the console. Note that this applies only to the diagnostic messages .CR audomon generates concerning the status of the audit system. Error messages caused by wrong usage of .CR audomon are sent to the standard output (where .CR audomon is invoked). .SH AUTHOR .CR audomon was developed by HP. .SH SEE ALSO audsys(1M), audit(5). .\" index@\f2audomon\f1 \- audit-overflow monitor daemon@@@\f3audomon(1M)\f1 .\" index@audit-overflow monitor daemon@@@\f3audomon(1M)\f1 .\" index@monitor daemon, audit-overflow@@@\f3audomon(1M)\f1 .\" index@overflow monitor daemon, audit-@@@\f3audomon(1M)\f1 .\" index@audit: audit-overflow monitor daemon@@@\f3audomon(1M)\f1 .\" index@daemon: audit-overflow monitor daemon@@@\f3audomon(1M)\f1 .\" toc@\f3audomon(1M)\f1:\0\0\f2audomon\f1@@@audit overflow monitor daemon .\" .\" fileset_database@audomon.1m@SYS-ADMIN-MAN .\" $Header: audsys.1m,v 76.1 95/06/20 14:42:49 ssa Exp $ .TA a .TH audsys 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME audsys \- start or halt the auditing system and set or display audit file information .SH SYNOPSIS .B audsys .RB [ \|\-nf\| ] .RB [ \|\-\|c .I file .B \|\-\|s .IR cafs\| ] .RB [ \|\-\|x .I file .B \|\-\|z .IR xafs\| ] .SH DESCRIPTION .I audsys allows the user to start or halt the auditing system, to specify the auditing system "current" and "next" audit files (and their switch sizes), or to display auditing system status information. This command is restricted to super-users. .PP The "current" audit file is the file to which the auditing system writes audit records. When the "current" file grows to either its Audit File Switch .SM (AFS) size or its File Space Switch .SM (FSS) size (see .IR audomon (1M)), the auditing system switches to write to the "next" audit file. The auditing system switches audit files by setting the "current" file designation to the "next" file and setting the new "next" file to .SM NULL. The "current" and "next" files can reside on different file systems. .PP When invoked without arguments, .I audsys displays the status of the auditing system. This status includes information describing whether auditing is on or off, the names of the "current" and "next" audit files, and a table listing their switch sizes and the sizes of file systems on which they are located, as well as the space available expressed as a percentage of the switch sizes and file system sizes. .PP .SS Options .I audsys recognizes the following options: .RS .TP 15 .B \-n Turn on the auditing system. The system uses existing "current" and "next" audit files unless others are specified with the .B \-c and .B \-x options. If no "current" audit file exists (such as when the auditing system is first installed), specify it by using the .B \-c option. .TP .B \-f Turn off the auditing system. The .B \-f\f1 and .B \-n\f1 options are mutually exclusive. Other options specified with .B \\-f\f1 are ignored. .TP .BI \-c \0file Specify a "current" file. Any existing "current" file is replaced with the .I file specified; the auditing system immediately switches to write to the new "current" file. The specified .I file must be empty or nonexistent, unless it is the "current" or "next" file already in use by the auditing system. .TP .BI \-s \0cafs Specify .IR cafs , the "current" audit file switch size (in kbytes). .TP .BI \-x \0file Specify the "next" audit file. Any existing "next" file is replaced with the .I file specified. The specified .I file must be empty or nonexistent, unless it is the "current" or "next" file already in use by the auditing system. .TP .BI \-z \0xafs Specify .IR xafs , the "next" audit file switch size (in kbytes). .RE .PP If .B \-c but not .B \-x is specified, only the "current" audit file is changed; the existing "next" audit file remains. If .B \-x but not .B \-c is specified, only the "next" audit file is changed; the existing "current" audit file remains. .PP The .B \-c option can be used to manually switch from the "current" to the "next" file by specifying the "next" file as the new "current" file. In this instance, the file specified becomes the new "current" file and the "next" file is set to .SM NULL. .PP In instances where no next file is desired, the .B \-x option can be used to set the "next" file to .SM NULL by specifying the existing "current" file as the new "next" file. .PP The user should take care to select audit files that reside on file systems large enough to accomodate the Audit File Switch .SM (AFS) desired. .I audsys returns a non-zero status and no action is performed, if any of the following situations would occur: .IP The Audit File Switch size .SM (AFS) specified for either audit file exceeds the space available on the file system where the file resides. .IP The .SM AFS size specified for either audit file is less than the file's current size. .IP Either audit file resides on a file system with no remaining user space (exceeds minfree). .SH AUTHOR .CR audsys was developed by HP. .SH FILES .TP 31 .CR /.secure/etc/audnames File maintained by .C audsys containing the "current" and "next" audit file names and their switch sizes. .SH SEE ALSO audit(5), audomon(1M), audctl(2), audwrite(2), audit(4). .\" index@\f2audsys\f1 \- start or halt the auditing system and set or display audit file information@@@\f3audsys(1M)\f1 .\" index@start or halt auditing system@@@\f3audsys(1M)\f1 .\" index@halt or start auditing system@@@\f3audsys(1M)\f1 .\" index@set or display audit file information@@@\f3audsys(1M)\f1 .\" index@display or set audit file information@@@\f3audsys(1M)\f1 .\" index@audit: start or halt auditing system@@@\f3audsys(1M)\f1 .\" index@audit: set or display audit file information@@@\f3audsys(1M)\f1 .\" index@auditing system@@@see audit .\" index@system, auditing@@@see audit .\" toc@\f3audsys(1M)\f1:\0\0\f2audsys\f1@@@start or halt the auditing system and set or display audit file information .\" .\" fileset_database@audsys.1m@SYS-ADMIN-MAN .\" $Header: audusr.1m,v 72.4 94/11/30 10:10:29 ssa Exp $ .TA a .TH audusr 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME audusr \- select users to audit .SH SYNOPSIS .C audusr .RC [\|[ -a .IR user\| ]\0...\|] .RC [\|[ -d .IR user\| ]\0...\|] .RC [ -A \(or -D ] .SH DESCRIPTION .C audusr is used to specify .IR user s to be audited or excluded from auditing. If no arguments are specified, .C audusr displays the command usage. .C audusr is restricted to super-users. .SS Options .C audusr recognizes the following options: .RS .TP 15 .CI -a \0user Audit the specified .IR user . The auditing system records audit records to the ``current'' audit file when the specified .I user executes audited events or system calls. Use .C audevent to specify events to be audited (see .IR audevent (1M)). .TP .CI -d \0user Do not audit the specified .IR user . .TP .C -A Audit all users. .TP .C -D Do not audit any users. .RE .PP The .C -A and .C -D options are mutually exclusive: that is, if .C -A is specified, .C -d cannot be specified; if .C -D is specified, .C -a cannot be specified. .PP Users specified with .C audusr are audited (or excluded from auditing) beginning with their next login session, until excluded from auditing (or specified for auditing) with a subsequent .C audusr invocation. Users already logged into the system when .C audusr is invoked are unaffected during that login session; however, any user who logs in after .C audusr is invoked is audited or excluded from auditing accordingly. .SH AUTHOR .C audusr was developed by HP. .SH FILES .TP 20 .C /tcb/files/auth/*/* File containing flags to indicate whether users are audited. .SH SEE ALSO audit(5), audevent(1M), setaudproc(2), audswitch(2), audwrite(2). .\" .\" index@\f4audusr\f1 \- select users to audit@@@\f3audusr(1M)\f1 .\" index@select users to audit@@@\f3audusr(1M)\f1 .\" index@users, select for auditing@@@\f3audusr(1M)\f1 .\" index@audit: select users to audit@@@\f3audusr(1M)\f1 .\" .\" toc@\f3audusr(1M)\f1:\0\0\f4audusr\f1@@@select users to audit .\" .\" fileset_database@audusr.1m SYS-ADMIN-MAN .\" $Header: authck.1m,v 72.2 94/08/29 16:20:05 ssa Exp $ .TA a .TH authck 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME authck \- check internal consistency of Authentication database .SH SYNOPSIS .CR authck .RC \|[ -p ]\| .RC \|[ -t ]\| .RC \|[ -a ]\| .RC \|[ -v ]\| .SH DESCRIPTION .CR authck checks both the overall structure and internal field consistency of all components of the Authentication database. It reports all problems it finds. Only users who have the .IR superuser capability can run this command. When .C pwck is used with the .CR -s option, .CR authck is run with the .CR -p option automatically. .SS Options .CR authck recognizes the following options and tests: .RS .TP 8 .C \-p Check the Protected Password database. The Protected Password database and .CR /etc/passwd are checked for completeness such that neither contains entries not in the other. The cross references between the Protected Password database and .CR /etc/passwd are checked to make sure that they agree. Fields in the Protected Password database are then checked for reasonable values. For example, all time stamps of past events are checked to make sure that they have times less than the times returned by .IR time (2). .TP .C \-t Fields in the Terminal Control database are checked for reasonable values. All time stamps of past events are checked to make sure they have times less than those returned by .IR time (2). .TP .C \-a Shorthand equivalent of using the .CR \-p and .CR \-t options together in a single command. .TP .C \-v Provide running diagnostics as the program proceeds. Produce warnings when unusual conditions are encountered that might not cause program errors in .I login, password and .I su programs. .RE .SH FILES .TP 45 .CR /etc/passwd System password file .PD 0 .TP .CR /tcb/files/auth/*/* Protected Password database .TP .CR /tcb/files/ttys Terminal Control database .TP .CR /tcb/files/auth/system/default System Defaults database .TP .CR /usr/sbin/authck .PD .SH AUTHOR SecureWare Inc. .SH SEE ALSO getprpwent(3), getprtcent(3), getprdfent(3), authcap(4). .\" .\" index@\f4authck\f1 \- check internal consistency of Authentication database@@@\f3authck(1M)\f1 .\" index@\f1check internal consistency of Authentication database@@@\f3authck(1M)\f1 .\" index@\f1internal consistency of Authentication database, check@@@\f3authck(1M)\f1 .\" index@\f1consistency of Authentication database, check internal@@@\f3authck(1M)\f1 .\" index@\f1Authentication database, check internal consistency of@@@\f3authck(1M)\f1 .\" index@\f1database, check internal consistency of Authentication@@@\f3authck(1M)\f1 .\" .\" toc@\f3authck(1M)\f1:\0\0\f4authck\f1@@@check internal consistency of Authentication database .\" .\" fileset_database@authck.1m UX-CORE-MAN .\" $Header: auto_parms.1m,v 78.2 96/02/12 13:33:38 ssa Exp $ .\" -*-Text-*- .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .\" .\" (c) Copyright 1995, Hewlett-Packard Company, all rights reserved. .\" .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .TA a .TH auto_parms 1M "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ad b .SH NAME auto_parms \- Initial system configuration/DHCP support script .SH SYNOPSIS .CR auto_parms .SH DESCRIPTION .CR auto_parms is a system initialization script whose primary responsibility lies in handling first time boot configuration and ongoing management of the DHCP lease(s). .CR auto_parms is invoked at boot time by the .CR /sbin/rc script. Initially, it will load a list of available ethernet interfaces and begin requesting a DHCP lease on each interface, stopping when a valid lease is secured or the list is exhausted. .PP As a part of checking for the availability of a lease on a particular interface, .CR auto_parms will also consult .CR /etc/rc.config.d/netconf and examine the variable DHCP_ENABLE[index]. If DHCP_ENABLE[index] is set to '0', .CR auto_parms will not attempt to request a lease on the the interface designated by 'index'. If DHCP_ENABLE[index] does not exist in .CR /etc/rc.config.d/netconf , .CR auto_parms will assume that it can attempt the DHCP request over the interface. .PP Once a lease is secured, the information supplied with the lease will be used to initialize key networking parameters (see .IR dhcpdb2conf (1M)). .PP If .CR auto_parms detects that the system is going through a "first time boot" (keyed by the hostname for the system not being set), it will invoke .CR set_parms for the purpose of verifying the DHCP supplied parameters as well as collecting any parameters not supplied by DHCP. .PP For all subsequent boots, the data supplied by a DHCP lease is assumed to be definitive and will be recognized as such by .CR auto_parms . Note that in an environment (non-mobile) where DHCP is being used for IP address management, the lease information will not change from boot to boot under normal conditions. This is accomplished by .CR auto_parms ensuring that the .CR dhcpclient is placed in "lease maintenance mode" prior to exiting. .SH FILES .CR /sbin/auto_parms .PP .CR /sbin/set_parms.util .SH EXAMPLES See .CR /sbin/rc for invocation context .SH SEE ALSO dhcpdb2conf(1M) .\" .\" index@\f4auto_parms\f1 \- Initial system configuration/DHCP support script@@@\f3auto_parms(1M)\f1 .\" index@\f1system configuration/DHCP support script@@@\f3auto_parms(1M)\f1 .\" index@\f1DHCP support script, system configuration@@@\f3auto_parms(1M)\f1 .\" .\" toc@\f3auto_parms(1M)\f1:\0\0\f4auto_parms\f1@@@ Initial system configuration/DHCP support script .\" $Header: automount.1m,v 72.6 94/09/15 16:24:45 ssa Exp $ .TA a .TH automount 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME automount \- automatically mount NFS file systems .SH SYNOPSIS .C automount .RC [ -mnTv ] .RC [ -D .IC name \0= .IR value \| ] .RC [ -f .IR master-file \|] .RC [ -M .IR mount-directory \|] .RC [ -tl .IR duration \|] .ift .br .RC [ -tm .IR interval \|] .RC [ -tw .IR interval \|] .RI [\| directory .I map .RI [\| \-mount-options \|] ] ... .SH DESCRIPTION .C automount is a daemon that automatically and transparently mounts NFS file systems as needed. It monitors attempts to access directories that are associated with an .C automount map, along with any directories or files that reside under them. When a file is to be accessed, the daemon mounts the appropriate NFS file system. Maps can be assigned to a directory by using an entry in a direct .C automount map, or by specifying an indirect map on the command line. .PP .C automount interacts with the kernel in a manner closely resembling an NFS server: .RS .TP 3 \(bu .C automount uses the map to locate an appropriate NFS file server, exported file system, and mount options. .TP \(bu It then mounts the file system in a temporary location, and replaces the file system entry for the directory or subdirectory with a symbolic link to the temporary location. .TP \(bu If the file system is not accessed within an appropriate interval (five minutes by default), the daemon unmounts the file system and removes the symbolic link. .TP \(bu If the specified directory has not already been created, the daemon creates it, and then removes it upon exiting. .RE .PP Since name-to-location binding is dynamic, updates to an .C automount map are transparent to the user. This obviates the need to mount shared file systems prior to running applications that contain internally hard-coded references to files. .PP If the dummy directory .RC ( /- ) is specified, .C automount treats the .I map argument that follows as the name of a direct map. In a direct map, each entry associates the full path name of a mount point with a remote file system to mount. .PP If the .I directory argument is a path name, the .I map argument points to an indirect map. An indirect map, contains a list of the subdirectories contained within the indicated .IR directory . With an indirect map, it is these subdirectories that are mounted automatically. .PP A map can be a file or a NIS map; if a file, the .I map argument must be a full path name. .PP The .CI - mount-options argument, when supplied, is a comma-separated list of options to the .C mount command (see .IR mount (1M)) preceded by a .CR \- . However, any conflicting mount options specified in the indicated map take precedence. .SS Options .C automount recognizes the following options: .RS .TP 15 .C -m Ignore .C auto.master NIS database. .TP .C -n Disable dynamic mounts. With this option, references through the .C automount daemon succeed only when the target filesystem has been previously mounted. This can be used to prevent NFS servers from cross-mounting each other. .TP .C -T Trace. Expand each NFS call and log it in .C /var/adm/automount.log file. .TP .C -v Verbose. Log status messages to the system log file (see .IR syslogd (1M)). .TP .CI "-D " envar " = " value Assign .I value to the indicated .C automount (environment) variable .IR envar . .TP .CI "-f " master-file Read the local .CI master_file before reading the .C auto.master NIS map. .TP .CI "-M " mount-directory Mount temporary file systems in the named directory instead of in .CR /tmp_mnt . .TP .CI "-tl " duration Specify a .I duration (in seconds) that a file system is to remain mounted when not in use. The default is 5 minutes. .TP .CI "-tm " interval Specify an .I interval (in seconds) between attempts to mount a filesystem. The default is 30 seconds. .TP .CI "-tw " interval Specify an .I interval (in seconds) between attempts to unmount filesystems that have exceeded their cached times. The default is 1 minute. .RE .SS Environment Variables Environment variables can be used within an .C automount map. For example, if .C $HOME appears within a map, .C automount expands it to the current value of the .C HOME environment variable. .PP To protect a reference from affixed characters, surround the variable name with curly braces. Environment variables cannot appear as the key entry in maps. .SH EXAMPLES .SS Map Entry Format A simple map entry (mapping) takes the form: .IP .I directory .RC [ -\c .IR mount-options \|] .IR location \ .\|.\|. .PP where .I directory is the full path name of the directory to mount, when used in a direct map, or the basename of a subdirectory in an indirect map. .I mount-options is a comma-separated list of .C mount options, and .I location specifies a remote filesystem from which the directory may be mounted. In the simple case, .I location takes the form: .IP .IC host : pathname .PP Multiple .I location fields can be specified, in which case .C automount sends multiple .C mount requests; .C automount mounts the file system from the first host that replies to the .C mount request. This request is first made to the local net or subnet. If there is no response, any connected server is allowed to respond. .PP If .I location is specified in the form: .IP .IC host : path : subdir .PP .I host is the name of the host from which to mount the file system, .I path is the path name of the directory to mount, and .IR subdir , when supplied, is the name of a subdirectory to which the symbolic link is made. This can be used to prevent duplicate mounts when multiple directories in the same remote file system might be accessed. Assume a map for .CR /home resembling: .IP .C "mike hpserver1:/home/hpserver1:mike" .br .C "dianna hpserver1:/home/hpserver1:dianna" .PP Attempting to access a file in .C /home/mike causes .C automount to mount .C hpserver1:/home/hpserver1 and creates a symbolic link called .C /home/mike to the .C mike subdirectory in the temporarily-mounted filesystem. A subsequent file access request in .C /home/dianna results in .C automount simply creating a symbolic link that points to the .C dianna subdirectory because .C /home/hpserver1 is already mounted. Given the map: .IP .C "mike hpserver1:/home/hpserver1/mike" .br .C "dianna hpserver1:/home/hpserver1/dianna" .PP .C automount would have to mount the filesystem twice. .PP A mapping can be continued across input lines by escaping the newline character with a backslash .RC ( \e ). Comments begin with a .C # and end at the subsequent newline character. .SS Directory Pattern Matching The .C & character is expanded to the value of the .I directory field for the entry in which it occurs. Given an entry of the form: .IP .C "mike hpserver1:/home/hpserver1:&" .PP the .C & expands to .CR mike . .PP The .C * character, when supplied as the .I directory field, is recognized as the catch-all entry. Such an entry resolves to any entry not previously matched. For example, if the following entry appeared in the indirect map for .CR /home : .IP .C "* &:/home/&" .PP this would allow automatic mounts in .C /home of any remote file system whose location could be specified as: .IP .IC "hostname :/home hostname" .SS Hierarchical Mappings A hierarchical mapping takes the form: .IP .I directory .RC [ /\c .RI [ subdirectory ] .RC [ -\c .IR mount-options \|] .IR location \0...]\0... .PP The initial .C / within the .CR / [\f2subdirectory\fP] is required; the optional .I subdirectory is taken as a file name relative to the .IR directory . If .I subdirectory is omitted in the first occurrence, the .C / refers to the directory itself. .PP Given the direct map entry: .nf .IP .C "/usr/local \e" .C " / -ro,intr shasta:/usr/local ranier:/usr/local \e" .C " /bin -ro,intr ranier:/usr/local/bin shasta:/usr/local/bin \e" .C " /man -ro,intr shasta:/usr/local/man ranier:/usr/local/man" .fi .RE .PP .C automount automatically mounts .CR /usr/local , .CR /usr/local/bin , and .CR /usr/local/man , as needed, from either .C shasta or .CR ranier , whichever host responded first. .SS Direct Maps A direct map contains mappings for any number of directories. Each directory listed in the map is automatically mounted as needed. The direct map as a whole is not associated with any single directory. .SS Indirect Maps An indirect map allows specifying mappings for the subdirectories to be mounted under the .I directory indicated on the command line. It also obscures local subdirectories for which no mapping is specified. In an indirect map, each .I directory field consists of the basename of a subdirectory to be mounted as needed. .SS Included Maps The contents of another map can be included within a map with an entry of the form: .IP .CI + mapname .PP .I mapname can either be a file name, or the name of an NIS map, or one of the special maps described below. .SS Special Maps Three special maps, .CR -hosts , .CR -passwd , and .CR -null , are currently available: The .C -hosts map uses the .C gethostbyname() map to locate a remote host when the hostname is specified (see .IR gethostbyname (3C). This map specifies mounts of all exported file systems from any host. For example, if the following .C automount command is already in effect: .IP .C "automount /net -hosts" .PP a reference to .C /net/hermes/usr initiates an automatic mount of all file systems from .C hermes that .C automount can mount, and any subsequent references to a directory under .C /net/hermes refer to the corresponding directory on .CR hermes . The .C -passwd map uses the .IR passwd (4) database to attempt to locate a user's home directory. For example, if the following .C automount command is already in effect: .IP .C "automount /homes -passwd" .PP if the home directory for a user has the form .CI / dir / server / username\f1, and .I server matches the host system on which that directory resides, .C automount mounts the user's home directory as: .CI / homes / username\f1. .PP For this map, the tilde character .RC ( ~ ) is recognized as a synonym for .IR username . .PP The .C -null map, when indicated on the command line, cancels a previous map for the directory indicated. It can be used to cancel a map given in .CR auto.master . .SS Configuration and the auto.master Map .C automount normally consults the .C auto.master NIS configuration map for a list of initial .C automount maps, and sets up automatic mounts for them in addition to those given on the command line. If there are duplications, the command-line arguments take precedence. This configuration database contains arguments to the .C automount command rather than mappings. Unless .C -f is in effect, .C automount does .I not look for an .C auto.master file on the local host. .PP Maps given on the command line, or those given in a local .C auto.master file specified with .C -f override those in the NIS .CR auto.master map. For example, given the command: .IP .C " automount /homes /etc/auto.homes /- /etc/auto.direct" .PP and the NIS map file .C auto.master containing: .IP .C "/homes -passwd" .PP .C automount mounts home directories using the .C /etc/auto.homes map instead of the special .C -passwd map in addition to the various directories specified in the .C /etc/auto.direct map. .SH WARNINGS Do not send the .C SIGKILL signal .RC ( "kill -9" , or .CR "kill -KILL" ) to the automount daemon. Doing so causes any processes accessing mount directories served by .C automount to hang. A system reboot may be required to recover from this state. .PP Do not start an automount daemon while another is still running. If restarting .CR automount , make sure the first daemon and all of its children are not running. .PP When .C automount receives signal .CR SIGHUP , it rereads the .C /etc/mnttab file to update its internal record of currently mounted file systems. If a file system mounted by .C automount is unmounted by a .C umount command, .C automount should be forced to reread the file by sending the .CR SIGHUP signal (see .IR kill (1)). .PP Shell file name expansion does not apply to objects not currently mounted. .PP Since .C automount is single-threaded, any request that is delayed by a slow or nonresponding NFS server delays all subsequent automatic mount requests until it completes. .PP Programs that read .C /etc/mnttab and then touch files that reside under automatic mount points introduce further entries to the file. .PP Automatically-mounted file systems are mounted with type .CR ignore ; they do not appear in the output of either .IR mount (1M), or .IR bdf (1M). .SH FILES .PD 0 .TP 20 .C /tmp_mnt directory under which filesystems are dynamically mounted .TP .C /etc/mnttab mount table .PD .SH SEE ALSO mount (1M), bdf (1M), passwd (4) .\"" .\" index@\f4automount\f1 \- automatically mount NFS file systems@@@\f3automount(1M)\f1 .\" index@\f1automatically mount NFS file systems@@@\f3automount(1M)\f1 .\" index@\f1mount NFS file systems automatically@@@\f3automount(1M)\f1 .\" index@\f1NFS file systems, automatically mount@@@\f3automount(1M)\f1 .\" index@\f1file systems, automatically mount NFS@@@\f3automount(1M)\f1 .\"" .\" toc@\f3automount(1M)\f1:\0\0\f4automount\f1@@@automatically mount NFS file systems .\" $Header: autopush.1m,v 72.2 94/08/30 14:04:01 ssa Exp $ .TA a .TH autopush 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME autopush \- manage system database of automatically pushed STREAMS modules .SH SYNOPSIS .C autopush -f .I file .PP .C autopush -g -M .I major .C -m .I minor .PP .C autopush -r -M .I major .C -m .I minor .SH DESCRIPTION .C autopush manages the system database that is used for automatic configuration of STREAMS devices. The command is used in three different ways as dictated by the .CR -f , .CR -g , and .C -r command-line options described below. .SS Options .C autopush recognizes the following command-line options and arguments: .RS .TP 15 .CI -f \0file Using the configuration information contained in .IR file , load the system database with the names of the STREAMS devices and a list of modules to use for each device. When a device is subsequently opened, the HP-UX STREAMS subsystem pushes the modules onto the stream for the device. .IP .I file must contain one or more lines of at least four fields separated by a space as shown below: .IP .I major minor lastminor module1 module2 ... .I moduleN .IP The first field .I major can be either an integer or a device name. The device name is the name for the device used in the .BR master file. The next two fields are integers. If .I minor is set to -1, then all minor devices for the specified .I major are configured and .I lastminor is ignored. If .I lastminor is 0, then only a single minor device is configured. To configure a range of minor devices for a major device, .I minor must be less then .IR lastminor . The remaining field(s) list one or more module names. Each module is pushed in the order specified. A maximum of eight modules can be pushed. Any text after a # character in .I file is treated as a comment for that line only. .IP This option is also used to restore device configuration information previously removed by .CR autopush\0-r . However, when used in such a manner, the entire database is restored, not just the information that was previously removed. .TP .CI -g\0-M \0major\0 -m \0minor Display current configuration information from the system database for the STREAMS device specified by the .I major device number (or device name for the device from the .BR master file) and .I minor number. .IP If a range of minors has been previously configured then .C autopush -g returns the configuration information for the first minor in the range, in addition to other information. .TP .CI -r\0-M \0major\0 -m \0minor Remove configuration information from the system database for the STREAMS device specified by the .I major device number (or device name for the device from the .BR master file and .I minor number. Removal is performed on the database only, not on the original configuration file. Therefore, the original configuration can be restored by using the .C -f .I file option. To permanently exclude a STREAMS device from the database, its information must be removed from the configuration file. .IP If .IR minor matches the first minor of a previously configured range then .C autopush -r removes the configuration information for the entire configured range. .RE .SH EXAMPLES If the file .CR /tmp/autopush.example contains: .IP .C 75 -1 0 modA modB .IP .C test 0 5 modC modA .PP Then .C autopush -f /tmp/autopush.example will cause .C modA and .C modB to be pushed whenever major device .C "# 75" is opened, and .C modC and .C modA to be pushed for the first six opens of device .CR test . .PP This next example lists information about the stream for major device .C 75 and its minor device .CR -2 : .IP .C "autopush -g -M 75 -m -2" .SH FILES .TP 50 .C /usr/lib/nls/msg/C/autopush.cat NLS catalog for .CR autopush . .SH SEE ALSO sad(7), streamio(7). .\" .\" index@\f4autopush\f1 \- manage system database of automatically pushed STREAMS modules@@@\f3autopush(1M)\f1 .\" index@\f1manage system database of automatically pushed STREAMS modules@@@\f3autopush(1M)\f1 .\" index@\f1system database of automatically pushed STREAMS modules, manage@@@\f3autopush(1M)\f1 .\" index@\f1pushed STREAMS modules, manage system database@@@\f3autopush(1M)\f1 .\" index@\f1STREAMS modules, manage system database of automatically pushed STREAMS modules@@@\f3autopush(1M)\f1 .\" .\" toc@\f3autopush(1M)\f1:\0\0\f4autopush\f1@@@manage system database of automatically pushed STREAMS modules .\" .\" fileset_database@autopush.1m STREAMS-MAN .\" $Header: backup.1m,v 78.1 96/04/05 11:16:32 ssa Exp $ .TA b .TH backup 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME backup \- backup or archive file system .SH SYNOPSIS .B /usr/sbin/backup .RB [ \|\-A\| ] .RI [ \|\-archive\| ] .RB [ \|\-fsck\| ] .SH DESCRIPTION The .I backup command uses .IR find (1) and .IR cpio (1) to save a .I cpio archive of all files that have been modified since the modification time of .B /var/adm/archivedate on the default tape drive .RB ( /dev/update.src ). .I backup should be invoked periodically to ensure adequate file backup. .PP The .B \-A option suppresses warning messages regarding optional access control list entries. .IR backup (1M) does not backup optional access control list entries in a file's access control list (see .IR acl (5)). Normally, a warning message is printed for each file having optional access control list entries. .PP The .B \-archive option causes .IR backup to save all files, regardless of their modification date, and then update .B /var/adm/archivedate using .IR touch (1). .PP .I backup prompts you to mount a new tape and continue if there is no more room on the current tape. Note that this prompting does not occur if you are running .IR backup from .IR cron (1M). .PP The .B \-fsck option causes .IR backup to start a file system consistency check (without correction) after the backup is complete. For correct results, it is important that the system be effectively single-user while .IR fsck is running, especially if .B \-fsck is allowed to automatically fix whatever inconsistencies it finds. .I backup does not ensure that the system is single-user. .PP You can edit .B /usr/sbin/backup to customize it for your system. For example, .IR backup uses .IR tcio (1) with .IR cpio to back up files on an .SM HP CS/80 disc drive's streaming tape. You must modify .IR backup to use .IR cpio (1) if you want to access a standard .SM HP Tape Drive. .PP Several local values are used that can be customized: .RS .TP 15 BACKUPDIRS specifies which directories to back up recursively (usually .BR / , meaning all directories); .TP BACKUPLOG file name where start and finish times, block counts, and error messages are logged; .TP ARCHIVE file name whose date is the date of the last archive; .TP REMIND file name that is checked by .B /etc/profile to remind the next person who logs in to change the backup tape; .TP FSCKLOG file name where start and finish times and .IR fsck output is logged. .RE .PP You may want to make other changes, such as whether or not .IR fsck does automatic correction (according to its arguments), where .IR cpio output is directed, other information logging, etc. .PP In all cases, the output from .IR backup is a normal .IR cpio archive file (or volume) which can be read using .IR tcio and .IR cpio with the .B c option. .SS File Recovery .I backup creates archive tapes with all files and directories specified relative to the root directory. When recovering files from an archive tape created by .IR backup , you should be in the root directory and specify the directory path names for recovered files relative to the root directory .RB ( / ). When specifying the directory path name for file recovery by .I tcio and .IR cpio , do not precede the leading directory name with a slash. If you prefer, you can also use .I cpio with a .B \-t option to determine how files and directories are named on the archive tape before attempting recovery. .SH WARNINGS Refer to .SM WARNINGS in .IR cpio (1). .PP When .IR cpio runs out of tape, it sends an error to standard error and demands a new special file name from .BR /dev/tty . .PP To continue, rewind the tape, mount the new tape, type the name of the new special file at the system console, and press .BR Return . .PP If .IR backup is being run unattended from .IR cron (1M) and the tape runs out, .I backup terminates, leaving the .IR find process still waiting. Kill this process when you return. .SH FILES .TP 30 .CR /var/adm/archivedate parameterized file names .SH SEE ALSO cpio(1), find(1), tcio(1), touch(1), cron(1M), fbackup(1M), frecover(1M), fsck(1M), acl(5). .\" index@\f2backup\f1 \- backup or archive the file system@@@\f3backup(1M)\f1 .\" index@file system: backup or archive the file system@@@\f3backup(1M)\f1 .\" index@archive the file system@@@\f3backup(1M)\f1 .\" .\" toc@\f3backup(1M)\f1:\0\0\f2backup\f1@@@backup or archive file system .\" .\" fileset_database@backup.1m@SYS-ADMIN-MAN .\" $Header: bdf.1m,v 72.6 94/11/30 14:24:04 ssa Exp $ .TA b .TH bdf 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bdf \- report number of free disk blocks (Berkeley version) .SH SYNOPSIS .C /usr/bin/bdf .RC [ -b ] .RC [ -i ] .RC [ -l ] .RC [ -t .IR type .RC \(or .RI [ filesystem \(or file ] \&... ] .SH DESCRIPTION The .CR bdf command displays the amount of free disk space available either on the specified .I filesystem .RC ( /dev/dsk/c0d0s0 , for example) or on the file system in which the specified .I file (such as .CR $HOME ), is contained. If no file system is specified, the free space on all of the normally mounted file systems is printed. The reported numbers are in kilobytes. .SS Options The .CR bdf command recognizes the following options: .RS .TP 15 .C -b Display information regarding file system swapping. .TP .C -i Report the number of used and free inodes. .TP .C -l Display information for local file systems only (for example, HFS and CDFS file systems). .TP .CI -t \0type Report on the file systems of a given .I type (for example, .CR nfs or .CR hfs ). .RE .SH RETURN VALUE The .CR bdf command returns 0 on success (able to get status on all file systems), or returns 1 on failure (unable to get status on one or more file systems). .SH WARNINGS If file system names are too long, the output for a given entry is displayed on two lines. .PP The .CR bdf command does not account for any disk space reserved for swap space, or used for the .SM HFS boot block (8 KB, 1 per file system), .SM HFS superblocks (8 KB each, 1 per disk cylinder), .SM HFS cylinder group blocks (1 KB - 8 KB each, 1 per cylinder group), and inodes (currently 128 bytes reserved for each inode). Non-\c .SM HFS file systems may have other items not accounted for by this command. .SH AUTHOR .CR bdf was developed by the University of California, Berkeley. .SH FILES .TP 20 .C /etc/fstab Static information about the file systems. .PD 0 .TP .C /etc/mnttab Mounted file system table. .TP .C /dev/dsk/* File system devices. .PD .SH SEE ALSO df(1M), fstab(4), mnttab(4). .\" .\" index@\f4bdf\f1 \- report number of free disk blocks (Berkeley version)@@@\f3bdf(1M)\f1 .\" index@\f1number of free disk blocks, report (Berkeley version)@@@\f3bdf(1M)\f1 .\" index@\f1free disk blocks, report number of (Berkeley version)@@@\f3bdf(1M)\f1 .\" index@\f1disk blocks, report number of free (Berkeley version)@@@\f3bdf(1M)\f1 .\" index@\f1blocks, report number of free disk (Berkeley version)@@@\f3bdf(1M)\f1 .\" .\" toc@\f3bdf(1M)\f1:\0\0\f4bdf\f1@@@report number of free disk blocks (Berkeley version)\f1 .\" .\" $Header: nfsd.1m,v 72.5 94/09/13 11:09:41 ssa Exp $ .TA n .TH nfsd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nfsd, biod \- NFS daemons .SH SYNOPSIS .C /usr/sbin/nfsd .RI [ nservers ] .PP .C /usr/sbin/biod .RI [ nservers ] .SH DESCRIPTION .CR nfsd starts the NFS server daemons that handle client file system requests (see .IR nfs (7)). .I nservers is the number of file system request daemons that start. This number should be determined by the load expected on the server system. To obtain the best performance in most cases, set .I nservers to four. .PP .CR biod starts .I nservers asynchronous block I/O daemons. This command is used on an NFS client to buffer cache handle read-ahead and write-behind. .I nservers is a number greater than zero. For best performance, set .I nservers to four. .SH AUTHOR .CR nfsd was developed by Sun Microsystems, Inc. .SH SEE ALSO mountd(1M), exports(4). .\" .\" index@\f4biod\f1 \- NFS block I/O daemon@@@\f3nfsd(1M)\f1 .\" index@\f4nfsd\f1 \- NFS daemon@@@\f3nfsd(1M)\f1 .\" index@\f1NFS daemons@@@\f3nfsd(1M)\f1 .\" index@\f1daemons, NFS@@@\f3nfsd(1M)\f1 .\" .\" toc@\f3nfsd(1M)\f1:\0\0\f4biod\f1, \f4nfsd\f1@@@NFS daemons\f1 .\" toc@\f4biod(1M)\f1:\0\0\NFS block I/0 daemons@@@\f1see \f3nfsd(1M)\f1 .\" .\" links@nfsd.1m biod.1m .\" $Header: boot.1m,v 72.3 93/01/14 12:15:11 ssa Exp $ .TA b .TH boot 1M "" "Series 700/800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME boot \- bootstrap process .SH DESCRIPTION The Series 700 and 800 bootstrap process involves the execution of three software components: .RS .TP 3 \(bu .C pdc (see .IR pdc (1M), .TP \(bu .C isl (see .IR isl (1M), and .TP \(bu .C hpux (see .IR hpux_800 (1M)). .RE .PP After the processor is .SM RESET, .C pdc, the .B processor-dependent code (firmware), performs a self-test and initializes the processor. It then loads and transfers control to .CR isl , the operating-system-independent .IR "initial system loader" . .CR isl , in turn, loads and transfers control to the .C hpux utility, the .SM HP-UX\s0-specific bootstrap loader. .C hpux then downloads the .SM HP-UX kernel object file from an .SM HP-UX file system and transfers control to the loaded kernel image. .SH SEE ALSO hpux(1M), hpux_800(1M), isl(1M), pdc(1M). .\" index@\f4boot\f1 \- run bootstrap process@@@\f3boot(1M)\f1 .\" index@bootstrap process, run@@@\f3boot(1M)\f1 .\" index@reboot system@@@\f3boot(1M)\f1 .\" index@load operating system@@@\f3boot(1M)\f1 .\" index@operating system, load (reboot)@@@\f3boot(1M)\f1 .\" .\" toc@\f3boot(1M)\f1:\0\0\f4boot\f1@@@bootstrap process .\" .\" fileset_database@boot.1m SYS-ADMIN-MAN .\" $Header: bootpd.1m,v 78.1 96/04/05 11:17:34 ssa Exp $ .TA b .TH bootpd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bootpd \- Internet Boot Protocol server .SH SYNOPSIS .CR /usr/lbin/bootpd .RC [ \-d .IR debuglevel ] .RC [ \-s ] .RC [ \-t .IR timeout ] .RI [ configfile .RI [ dumpfile ]\|] .SH DESCRIPTION The .CR bootpd daemon implements three functions: a Dynamic Host Configuration Protocol (DHCP) server as defined in RFC1541, an Internet Boot Protocol (BOOTP) server as defined in RFC951 and RFC1395, and a DHCP/BOOTP relay agent as defined in RFC1542. .PP .CR bootpd can be run through .CR inetd (see .IR inetd (1M)), or as a stand-alone daemon. It is run by .CR /etc/inetd when the following line (or equivalent) is included in the file .CR /etc/inetd.conf : .IP .C "bootps dgram udp wait root /usr/lbin/bootpd bootpd" .PP .CR bootpd starts when a boot request arrives. If it has not received another boot request after 15 minutes, .CR bootpd exits. The .CR \-t option can be used to specify a different timeout value in minutes (such as .CR \-t20 ). With a timeout value of zero .RC ( \-t0 ), .CR bootpd never exits. .PP To run .CR bootpd as a stand-alone daemon, invoke it with the .CR \-s option. This might be the desired mode of operation for large network installations with many DHCP/BOOTP clients. With the .CR \-s option, the .CR \-t option has no effect, since .CR bootpd never exits. .PP The .CR \-d option sets the verbosity level (1\(mi3) of the logging emitted by the daemon via .CR syslog (see .IR syslog (3C)). .PP When .CR bootpd receives a DHCP/BOOTP request, it checks whether the client information is in the /etc/bootptab database. If the client information is available, .CR bootpd sends back the reply. Otherwise, it checks whether there is any matched relay information for the client in the /etc/bootptab database. If so, .CR bootpd goes through a series of checks to see if it should relay the request. If no matched relay information was found, .CR bootpd checks whether the client information is matched by a pool or device group in the /etc/dhcptab database. If a match is found, .CR bootpd sends back a reply. The request is dropped if no matched group information is found. .PP To replay to a DCHP or BOOTP request the server puts together a BOOTREPLY message and does a number of checks to ensure the message is sent to the correct destination. .PP .CR bootpd first checks the .CR ciaddr (client IP address) field of the DHCP/BOOTP packet. If this field is nonzero, the BOOTREPLY message is sent to the IP address identified in .CR ciaddr . .PP If the .CR ciaddr field is zero, .CR bootpd checks the .CR giaddr field. If this field is not zero, .CR bootpd sends the BOOTREPLY message to the .I relay agent specified in .CR giaddr field and the .I relay agent delivers the BOOTREPLY message to the client. If the .CR giaddr field is zero, .CR bootpd sends the BOOTREPLY message to the client. In both cases, the BOOTREPLY will either be sent to the IP address specified in the .CR yiaddr (your IP address) field or as a broadcast message. On HP-UX, there are two ways to specify that the BOOTREPLY should be sent as a broadcast message. .RS 2 .TP 3 1. The client sets the broadcast flag bit in the .CR flags field (bit 0) of the DHCP/BOOTP request packet. .TP 2. Define the .CR ba tag in the .CR bootptab file (see "Tags for client entries" below) .RE .PP For the case where the .CR bootpd has matched a relay entry in /etc/bootptab, it attempts to forward the request to the configured DHCP/BOOTP server. .PP .CR bootpd first checks whether the relay function is enabled for the requesting client. The relay capability is configurable. If the relay function is disabled, then the request packet is dropped. .PP Before .CR bootpd relays the request, it also examines the .CR giaddr (gateway IP address) field. The client sets the .CR giaddr field to zero when it sends out the request. If the relay agent finds this field is zero, it fills this field with the primary IP address of the interface on which the request was received; otherwise, the relay agent does not change this field. Then .CR bootpd increments the value of the .CR hops field, and relays the request to the DHCP/BOOTP servers that have been configured for this client. .PP If the relay function is enabled for this client, .CR bootpd checks the .CR hops field of the DHCP/BOOTP request packet. The client sets the .CR hops field to 0 when it sends out the DHCP/BOOTP request. The .CR hops value is increased every time the request packet is relayed by a relay agent. The maximum hop number can be configured. The maximum possible hop number allowed is 16. The default maximum is set to 4. The request packet is dropped if the hop value exceeds the configured maximum. .PP Then .CR bootpd compares the value of the .CR secs (seconds since the client began booting) field of the DHCP/BOOTP packet to the .CR threshold value. The client sets the .CR secs field to zero when it first sends out the request. The client repeats the request if it does not receive a reply. When the client repeats the request, it sets the .CR secs value to the number of seconds since the first request was sent. .CR bootpd does not relay the request if the value of the .CR secs field is less than the .CR threshold value. The .CR threshold value can be configured. The default value is 0. .SS Configuration Upon startup, .CR bootpd reads its configuration files to build its internal database, then listens for boot request packets. The default configuration files are, .CR /etc/bootptab , and .CR /etc/dhcptab . The bootptab file can be specified in the command line. .CR bootpd rereads its configuration file when it receives a hangup signal, .CR SIGHUP , or when it receives a boot request packet and detects that the configuration file has been updated. If hosts are added, deleted, or modified, their entries in the .CR bootpd internal database are updated accordingly when the configuration files are reread. .PP If .CR bootpd receives a .CR SIGUSR1 signal, it dumps its memory-resident database to the file .CR /var/tmp/bootpd.dump or the .I dumpfile specified in the command line. .PP The configuration file can contain two types of host entries: .RS 2 .TP 3 1. The client entries, which contains the client information. .TP 2. The relay entries, which contains the configuration to relay DHCP/BOOTP requests for one or more clients. .RE .PP The configuration uses two-character, case-sensitive tag symbols to represent host parameters. These parameter declarations are separated by colons .RC ( : ). The general format is: .IP .IC hostname : tg = value\c .CR : ... :\c .IC tg = value\c .CR : ... :\c .IC tg = value\c .CR : ... .PP where .I hostname is the actual name of a DHCP/BOOTP client in the client entries, and in the case of a relay entry, it can be the actual name of a client if it is an individual relay entry, or it can be a name for a group of clients if it is a group relay entry. .I tg is a two-character tag symbol. Most tags must be followed by an equals-sign, and a value as above. Some can appear in a boolean form with no value (that is, .CI : tg :\f1). .PP Blank lines and lines beginning with .CR # are ignored in the configuration file. Host entries are separated from one another by newlines; a single host entry can be extended over multiple lines if the lines end with a backslash .RC ( \e ). It is also acceptable for lines to be longer than 80 characters. Tags can appear in any order with the following exceptions: The host name must be the very first field in an entry, and the hardware type tag, .CR ht , must precede the hardware address tag, .CR ha . and the hardware mask tag, .CR hm . .PP IP addresses are specified in standard Internet dot notation, and can use decimal, octal, or hexadecimal numbers (octal numbers begin with .CR 0 , hexadecimal numbers begin with .CR 0x or .CR 0X ). Certain tags accept a list of one or more IP addresses .RI ( ip_address_list ). When more than one IP address is listed, the addresses must be separated by whitespace. .PP The types of tags can be grouped into three categories: .RS 2 .TP 3 1. The tags that can be used for both the client and the relay entries. .TP 2. The tags that can only be used in the relay entries. .TP 3. The tags that can only be used in the client information entries. .RE .PP Tag .CR ip is used to differentiate a client entry from a relay entry. An entry with tag .CR ip defined is treated as a client entry. A relay entry can contain the relay configuration for an individual client, also a hardware address mask mechanism is provided to configure the relay entry for a group of clients. The group client relay entries are kept in a linear sorted table by .CR bootpd . When a client does not have an individual relay specification, the linear table is searched to see if there is a match for the client. If there are multiple matched entries in the sorted table, only the first one is used. Tag .CR hm is used to differentiate an individual client relay entry from a group relay entry. The linear sorted table is sorted on the value of tag .CR hm . The search and match mechanism is explained in the discussion of tag .CR hm . .PP .B "Tags for both kinds of entries" .RS .TP .CI ha= hardware-address This tag specifies the hardware address of the client. The .I hardware address must be specified in hexadecimal; optional periods and/or a leading .CR 0x can be included for readability. The .CR ha tag must be preceded by the .CR ht tag (either explicitly or implicitly; see .CR tc below). .TP .CI ht= hardware-type This tag specifies the hardware type code. .I hardware-type can be an unsigned decimal, octal, or hexadecimal integer corresponding to one of the ARP Hardware Type codes specified in RFC1010. It can also be specified by the symbolic names .CR ethernet or .CR ether for 10-Mb Ethernet; .CR ethernet3 or .CR ether3 for 3-Mb experimental Ethernet; .CR ieee802 , .CR tr , or .CR token-ring for IEEE 802 networks; .CR pronet for Proteon ProNET Token Ring; .CR chaos , and .CR arcnet , for Chaos and ARCNET, respectively. .TP .CI tc= template-host This tag indicates a table continuation. Often, many host entries share common values for certain tags (such as domain servers, etc.). Rather than repeatedly specifying these tags, a full specification can be listed for one host entry and shared by others via the .CR tc mechanism. .IP The .I template-host is a dummy host that does not actually exist and never sends boot requests. Information explicitly specified for a host always overrides information implied by a .CR tc tag symbol. The value of .I template-host can be the host name or IP address of any host entry previously listed in the configuration file. .IP Sometimes it is necessary to delete a specific tag after it has been inferred via .CR tc . This can be done using the construction \f2tag\f3@\f1 which removes the effect of .IR tag . For example, to completely undo an RFC1034 domain name server specification, use .CR :ds@: at an appropriate place in the configuration entry. After removal with .CR @ , a tag is eligible to be set again through the .CR tc mechanism. .RE .PP .B "Tags for relay entries" .RS .TP .CI bp= bootp-servers This tag specifies the BOOTP servers that DHCP/BOOTP requests will be relayed to. The value of .I bootp-servers can be one or more individual IP addresses, and/or one or more network broadcast addresses. A relay entry with this tag configured indicates that the relay function is on for the clients specified in this entry. A relay entry missing this symbol means that the relay function is off for the clients specified in this entry. .TP .CI th= threshold This tag specifies the .I threshold value in seconds for the entry. The default value is 0. .TP .CI hp= hops This tag specifies the maximum .I hops value. If the .I hops value exceeds 16, it is set to 16. The default value is 4. .TP .CI hm= hardware-address-mask This tag specifies the mask for the hardware address .CR ha . .I hardware-address-mask must be specified in hexadecimal. An optional leading .CR 0x can be included for readability. The .CR hm tag must be preceded by the .CR ht tag (either explicitly or implicitly; see .CR tc above). Each .CR 0 bit in .CR hm specifies that the corresponding bit in .CR ha is a "don't-care" bit, each .CR 1 bit in .CR hm specifies that the corresponding bit in the .CR ha value is ANDed with the .CR hm value. If the result is the same and also the hardware type matches, then a match is found. For example, .RS .nf .IP .C "if (((hm & ha)==(client_hw_addr & hm))" .C " && (ht == client_hw_type))" .C " then a match is found" .C " else continue the search" .RE .fi .RE .PP .B "Tags for client entries" .RS .TP .CR ba This tag specifies that .CR bootpd should broadcast the boot reply to the client. As a boolean tag, it causes .CR bootpd to send the boot reply on the configured broadcast address of each network interface. You can also assign the tag an IP-address value, which specifies the specific IP or broadcast address for the boot reply. .TP .CI bf= filename This tag specifies the .I filename of the bootfile that the client should download. The client's boot request, and the values of the .CR hd (see below) and .CR bf symbols, determine the contents of the bootfile field in the boot reply packet. .IP If the client specifies an absolute path name (in its boot request), and that file is accessible on the server machine (see below), .CR bootpd returns that path name in the reply packet. If the file is not accessible, the request is discarded; no reply is sent. If the client specifies a relative path name, .CR bootpd constructs a full path name by appending the relative path name to the value of the .CR hd tag, and tests to determine if the full path name is accessible. If the full path name is accessible, it is returned in the boot reply packet; if not, the request is discarded. .IP Clients that do not specify boot files in their boot requests always elicit a reply from the server. The exact reply depends on the values of the .CR hd and .CR bf tags. If the .CR bf tag specifies an absolute path name, and the file is accessible, that path name is returned in the reply packet. Otherwise, if the .CR hd and .CR bf tags together specify an accessible file, that file name is returned in the reply. If a complete file name cannot be determined, or the file is not accessible publicly, the reply contains a zeroed-out bootfile field. .IP If the .CR tftp pseudouser exists, .CR bootpd treats all path names (absolute or relative) as being relative to the home directory of .CR tftp and checks there first. If the file is not accessible under the .CR tftp home directory or the .CR tftp pseudouser does not exist, .CR bootpd checks for the file relative to .CR / . .IP For a file to be available, it must exist, and be publicly readable. .IP All file names are first tried as .IC filename . hostname and then simply as .IR filename . However, in the case when the .CR tftp pseudouser exists, but .IC filename . hostname and .I filename are not accessible under the .CR tftp home directly, only .I filename is checked relative to .CR / . .IP Note that a file considered to be accessible relative to .CR / might not actually be accessible via .CR tftp if the command line arguments to .CR tftpd disallow that path. .TP .CI bs= size This tag specifies the size of the bootfile. The parameter .I size can be either a decimal, octal, or hexadecimal integer specifying the size of the bootfile in 512-octet blocks, or the keyword .CR auto , which causes the server to automatically calculate the bootfile size at each request. Specifying the .CR bs symbol as a boolean has the same effect as specifying .CR auto as its value. .TP .CI ci= client_ID This tag specifies the client identifier of the client. The parameter .I client_ID can be either a hexadecimal integer, or a string contained in double quotes. The .I client_ID is a unique identifier that the DHCP client may use to identify itself to the server. If present, the client identifier supersedes the hardware address, so a client and an entry will only match in one of two situations: one, they both have the same client identifier, or two they both have the same hardware address and neither has a client identifier. If a request has a client identifier, then that is used to match the client up with an entry in the bootp configuration file. One common client ID used is to concatenate the hardware type (e.g. 0x01 for ethernet) with the hardware address. .TP .CI cs= ip_address_list This tag specifies the IP addresses of RFC865 Quote of the Day (cookie) servers. .TP .CI dn= domain_name This tag specifies the domain name of the client for Domain Name Server resolution (see RFC1034). .TP .CI ds= ip_address_list This tag specifies the IP addresses of RFC1034 Domain Name servers. .TP .CI ef= filename Specifies the name of an extensions file. The file, retrievable via TFTP, contains information which can be interpreted in the same way as the 64-octet vendor-extension field within the BOOTP response. The maximum length of the file is unconstrained. All references to an extensions filename within the file are ignored. .TP .CI gw= ip_address_list This tag specifies the IP addresses of gateways for the client's subnet. If one of multiple gateways is preferred, it should be listed first. .TP .CI hd= home-directory This tag specifies a directory name to which the bootfile is appended (see the .CR bf tag above). The default value of the .CR hd tag is .CR / . .TP .CR hn The presence of this tag indicates that the client's host name should be sent in the boot reply. The .CR hn tag is a boolean tag. .CR bootpd attempts to send the entire host name as it is specified in the configuration file or hosts database. The configuration file is checked first, if the host name is not found, the hosts(4) database is then checked. If the hostname cannot fit into the reply packet, an attempt is made to shorten the name to just the host field (up to the first period, if present) and then tried. In no case is an arbitrarily truncated host name sent. If nothing reasonable can fit, nothing is sent. .TP .CI im= ip_address_list This tag specifies the IP addresses of Impress network image servers. .TP .CI ip= ip-address This tag specifies the IP address of the DHCP/BOOTP client. .TP .CI lg= ip_address_list This tag specifies the IP addresses of MIT-LCS UDP log servers. .TP .CI lp= ip_address_list This tag specifies the IP addresses of Berkeley 4BSD printer servers. .TP .CI md= merit_dump_file This tag specifies the name of a file to dump the core of a client. .TP .CI na= ip_address_list This tag specifies the IP address(es) of RFC 1001/1002 NetBIOS name server(s) in order of preference. .TP .CI nb= ip_address_list This tag specifies the IP address(es) of RFC 1001/1002 NetBIOS datagram distribution server(s) in order of preference. .TP .CI nc= NetBIOS_node_type Specifies the NetBIOS node type code. Allows NetBIOS over TCP/IP clients to be configured as described in RFC1001/1002. The .I NetBIOS_node_type can be an unsigned decimal, octal, or hexadecimal integer corresponding to one of the client types as follows: .br .CR 0x1 or .CR B-node for B-node; .br .CR 0x2 or .CR P-node for P-node; .br .CR 0x4 or .CR M-node for M-node; .br .CR 0x8 or .CR H-node for H-node. .TP .CI nd= string This tag specifies the NetBIOS over TCP/IP scope parameter for the client as specified in RFC 1001/1002. .TP .CI ns= ip_address_list This tag specifies the IP addresses of IEN-116 name servers. .TP .CI nt= ip_address_list This tag specifies the IP addresses of Network Time Protocol servers. Servers should be listed in order of preference. .TP .CI rl= ip_address_list This tag specifies the IP addresses of RFC887 Resource Location Protocol servers. .TP .CI rp= root_path This tag specifies a path name to be mounted as a root disk. .TP .CI sm= subnet-mask This tag specifies the client's subnet mask. .I subnet-mask is specified as a single IP address. .TP .CI sr= "destination_ip_address gateway_ip_address ..." This tag specifies a list of static routes that the client should put in its routing cache. Each route consists of a pair of IP addresses. The first address is the destination address, and the second is the router. Use the .CR gw= option to specify the default route (0.0.0.0) as it is not a legal destination address. .TP .CI ss= ip_address This tag specifies the IP address of a swap server. .TP .CI T nnn = generic-data This is a generic tag where .I nnn is an RFC1533 option field tag number. Use this option to configure RFC1533 options not currently supported with .CR bootpd tag names. This option allows one to immediately take advantage of future extensions to RFC1533. The .I generic-data data can be represented as either a stream of hexadecimal numbers or as a quoted string of ASCII characters. The length of the generic data is automatically determined and inserted into the proper fields of the RFC1541-style boot reply. .TP .CI to= offset This tag specifies the client's time zone offset in seconds from UTC. The time .I offset can be either a signed decimal integer or the keyword .CR auto which uses the server's time zone offset. Specifying the .CR to symbol as a boolean has the same effect as specifying .CR auto as its value. .TP .CI ts= ip_address_list This tag specifies the IP addresses of RFC868 Time Protocol servers. .TP .CI yd= NIS-domain-name Specifies the name of the client's NIS domain. .TP .CI ys= ip_address_list Specifies the IP address(es) of NIS servers available to the client. Servers should be listed in order of preference. .TP .CI vm= magic-cookie This tag specifies the RFC1048 vendor information magic cookie. .I magic-cookie can be one of the following keywords: .CR auto (indicating that vendor information is determined by the client's request), .CR rfc1048 (which always forces an RFC1048-style reply), or .CR cmu (which always forces a CMU-style reply). .TP .CI V nnn = generic-data This is a generic tag for vendor specific information where .I nnn is a vendor defined option field tag number. The .I generic-data data can be represented as either a stream of hexadecimal numbers or as a quoted string of ASCII characters. The length of the generic data is automatically determined and inserted into the vendor specific field of the RFC1541-style boot reply. .TP .CI xd= ip_address_list This tag specifies the IP addresses of systems that are running the X Window System Display Manager and are available to the client. Addresses should be listed in order of preference. .TP .CI xf= ip_address_list This tag specifies the IP addresses of X window System font servers available to the client. Servers should be listed in order of preference. .SS Dhcptab Configuration .PP The configuration file .C /etc/dhcptab defines groups of IP addresses that to be leased out to clients. It also specifies certain general behaviors of the server, such as whether or not to give addresses from these groups to bootp clients or only to DHCP clients. .PP The configuration file has a format similar to the .CR /etc/bootptab configuration file, with a keyword followed by one or more tag symbols. These tag symbols are separated by colons .RC ( : ). The general format is: .IP .IC keyword : tg = value\c .CR : \|...\|:\c .IC tg = value\c .CR : \|...\| :\c .IC tg = value\c .CR : \|...\| .PP where .I keyword is one of four allowed (non-case-sensitive) symbols and .I tg is a two or more (case-sensitive) character tag symbol. Most tags must be followed by an equals-sign and a value as above. Some can also appear in a boolean form with no value (i.e. .CI : tg :\f1). .PP Blank lines and lines beginning with .C # are ignored in the configuration file. Keyword entries are separated from one another by newlines; a single host entry may be extended over multiple lines if each continued line ends with a backslash .RC ( \e ). Lines may be longer than 80 characters. Tags can appear in any order. .PP .SM IP addresses must be specified in standard Internet ``dot'' notation, and can use decimal, octal, or hexadecimal numbers (octal numbers begin with .CR 0 , hexadecimal numbers begin with .C 0x or .CR 0X ). Certain tags accept a list of one or more .SM IP addresses .RI ( ip_address_list ). When more than one .SM IP address is listed, they must be separated by white space. .PP The currently recognized keywords are: .RS .TP 6 .C dhcp_pool_group This keyword is followed by tags defining a group of IP addresses to give out to clients on the same subnet, and the characteristics of that group. In addition to the tags defined for DHCP groups, all of the two-letter tags for bootp entries may also be used (except for .CR ht , the hardware type tag, .CR ha , the hardware address tag, or .CR ci , the client ID tag. Required tags are: .CR subnet-mask , .CR addr-pool-start-address , and .CR addr-pool-last-address . .TP .CI dhcp_device_group This keyword is used to define a group of IP addresses on a subnet much like .CR dhcp_pool_group , but with one exception: all clients in a device group must have the same client class (specified with tag .CR class-id ). This allows different types of clients to receive different parameters from the server. Required tags are: .CR class-id , .CR subnet-mask , .CR addr-pool-start-address , and .CR addr-pool-last-address . .TP .CI dhcp_default_client_settings This keyword is followed by tags to be applied to all groups. These tag values can be overridden for a specific group if that tag is defined for that specific group. This keyword simply saves one from entering the same tag for every group. Thus most tags that may be used for .CR dhcp_pool_group , and .CR dhcp_device_group , may be used here. The tag descriptions specify if a tag may not be used here. .TP .CI dhcp_server_settings This keyword is followed by tags that specify a few general behaviors for the dhcp server as a whole. .RE .PP The currently supported tags for .CR dhcp_server_settings : .RS .TP 6 .CI call-on-unrequited= filename This tag specifies an executable file .I filename that will be called when the server receives a request to which it cannot send a response. Certain arguments will be passed in; the call executed will be: .PP .RS 12 .IC filename : .C client-id .C htype .C haddr .C [gateway] .PP .RE .RS 6 where .C client-id is the client ID in hex if present, or 00 if there is no client ID. .C htype is the hardware type as per the ARP section of the "Assigned Numbers" RFC. .C haddr is the hardware address in hex. .C gateway is the IP address of the bootp relay agent. If the packet was not relayed, then this field is absent. .RE .RE .PP The currently supported tags for .CR dhcp_pool_group , .CR dhcp_device_group , and .CR dhcp_default_client_settings : .RS .TP 6 .CI class-name= classname This tag specifies a name to refer to a device group by. It is only applicable to .CR dhcp_device_group . The only use that bootpd makes of this field is in logging errors found in the configuration of the group. .TP 6 .CI pool-name= poolname This tag specifies a name to refer to a pool group by. It is only applicable to .CR dhcp_pool_group . The only use that bootpd makes of this field is in logging errors found in the configuration of the group. .TP 6 .CI class-id= client-class This tag specifies the .I client-class that clients must have to be assigned to this group. This tag is required for .CR dhcp_device_group and is inappropriate for any other keyword. Some DHCP clients send out a .I client-class that identifies a class that a client belongs to. For an IP address to be assigned from a device group address pool, not only must the client be on the right subnet, it must send a request with a .I client-class that matches that defined for the .CR class-id . This may be specified in either hex or in ASCII (an ASCII string must be enclosed in double quotes). .TP 6 .CI subnet-mask= mask This tag specifies the subnet mask for the addresses in the group being defined. It is specified as an IP address. This tag is required for both .CR dhcp_device_group and .CR dhcp_pool_group , and is inappropriate for .CR dhcp_default_client_settings . .TP 6 .CI addr-pool-start-address= IP-address This tag specifies the lowest address in the pool group to be assigned. This tag is required for both .CR dhcp_device_group and .CR dhcp_pool_group , and is inappropriate for .CR dhcp_default_client_settings . .TP 6 .CI addr-pool-last-address= ip-address This tag specifies the highest address in the pool group to be assigned. This address and the .CR addr-pool-start-address define a range of addresses that can be assigned to clients. For the server, no two group address ranges may overlap. .TP 6 .CI reserved-for-other= ip-address-list This tag is followed by one address that falls in the range of the group. This address is reserved, and will not be assigned to any clients by the DHCP server. Alternatively, a range of addresses may be defined by giving 2 addresses, with the range being the addresses from the first address up to the second address, inclusively. This tag may be repeated to reserve more addresses in the same group. It is not appropriate for .CR dhcp_default_client_settings . .TP 6 .CI lease-time= seconds This tag specifies the time in seconds that a lease should be given to each client. The word "infinite" may be used to specify leases that never expire. The default is "infinite." Note that if a client asks for a shorter lease than is configured for it, it will get that shorter lease time. .TP 6 .CI lease-grace-period= percent This tag specifies the time after a lease expires during which that lease will not be assigned to a new client. .I percent is the percentage of the configured lease time that this grace period lasts. The default is 5%. .TP .CI tr= seconds This tag specifies the DHCP IP lease renewal time (T1). This is the time interval from lease assignment until when the client attempts to renew the lease. RFC1541 states that T1 defaults to half the lease duration. .TP .CI tv= seconds This tag specifies the DHCP IP lease rebind time (T2). This is the time interval from lease assignment until when the client attempts to obtain a new lease from any server. RFC1541 states that T2 defaults to 0.875 times the lease duration. .TP 6 .CI lease-policy= policy This tag specifies whether or not the assigning of new leases can be done. If .I policy is set to .CR reject-new-clients then no new clients can get a lease, and only clients with existing leases will get a response. .CR accept-new-clients is the default. .TP 6 .CI allow-bootp-clients= boolean This tag specifies whether or not bootp clients can be members of the group being defined. The default is .CR false . If .I boolean is .CR TRUE , then an IP address may be assigned to a client that doesn't have an entry in the .CR bootptab file and that is on the same subnet as the group being defined. This address is treated as an infinite lease, and a boot reply is sent to the client. This tag is is not appropriate for .CR dhcp_device_group , since bootp clients don't have a client class (and therefore a bootp client would be incapable of matching the client class of the device group). If this tag is used for .CR dhcp_default_client_settings , then it is only applicable to pool groups. .TP 6 .CI call-on-assignment= filename This tag specifies the fully qualified .I filename to be called when an IP address has been assigned to a new client. Some arguments will be passed in, the call will be made as follows: .PP .RS 12 .IC filename : .C client-id .C htype .C haddr .C ipaddr .C subnet-mask .C lease-expiration .C [hostname] .PP .RE .RS 6 where .C client-id is the client ID in hex if present, or 00 if there is no client ID. .C htype is the hardware type as per the ARP section of the "Assigned Numbers" RFC. .C haddr is the hardware address in hex. .C ipaddr is the IP address that was assigned to the client. .C subnet-mask is the subnet mask of the client represented as an IP address. .C lease-expiration is the bootpd internal representation of when the lease will expire (based on a C call to time()), a value of ffffffff represents an infinite lease. If there is a .C hostname associated with this address, then it is the final argument. .RE .TP 6 .CI call-on-decline= filename This tag specifies the fully qualified .I filename to be called when an IP address has been declined by a new client. Some arguments will be passed in, the call will be made as follows: .PP .RS 12 .IC filename : .C client-id .C htype .C haddr .C ipaddr .C subnet-mask .PP .RE .RS 6 where .C client-id is the client ID in hex if present, or 00 if there is no client ID. .C htype is the hardware type as per the ARP section of the "Assigned Numbers" RFC. .C haddr is the hardware address in hex. .C ipaddr is the IP address that was declined by the client. .C subnet-mask is the subnet mask of the client represented as an IP address. .RE .TP 6 .CI call-on-release= filename This tag specifies the fully qualified .I filename to be called when an IP address has been released by a client. Some arguments will be passed in, the call will be made as follows: .PP .RS 12 .IC filename : .C client-id .C htype .C haddr .C ipaddr .C lease-expiration .PP .RE .RS 6 where .C client-id is the client ID in hex if present, or 00 if there is no client ID. .C htype is the hardware type as per the ARP section of the "Assigned Numbers" RFC. .C haddr is the hardware address in hex. .C ipaddr is the IP address that was released by the client. .C lease-expiration is the bootpd internal representation of when the lease would have expired, a value of ffffffff represents an infinite lease. .RE .TP 6 .CI call-on-lease-extend= filename This tag specifies the fully qualified .I filename to be called when an IP address lease for a client has been extended. Some arguments will be passed in, the call will be made as follows: .PP .RS 12 .IC filename : .C client-id .C htype .C haddr .C ipaddr .C subnet-mask .C lease-expiration .PP .RE .RS 6 where .C client-id is the client ID in hex if present, or 00 if there is no client ID. .C htype is the hardware type as per the ARP section of the "Assigned Numbers" RFC. .C haddr is the hardware address in hex. .C ipaddr is the IP address that was assigned to the client. .C subnet-mask is the subnet mask of the client represented as an IP address. .C lease-expiration is the bootpd internal representation of when the lease will expire (based on a C call to time()), a value of ffffffff represents an infinite lease. .RE .SS DHCP/BOOTP Packet The DHCP/BOOTP packet has the following format: .nf .IP .C "struct dhcp { .C " unsigned char op; /* packet opcode type */" .C " unsigned char htype; /* hardware addr type */" .C " unsigned char hlen; /* hardware addr length */" .C " unsigned char hops; /* gateway hops */" .C " unsigned long xid; /* 4 bytes transaction ID */" .C " unsigned short secs; /* seconds since boot began */" .C " unsigned short flags; /* if giaddr!=0,client flags*/" .C " struct in_addr ciaddr; /* client IP address */" .C " struct in_addr yiaddr; /* 'your' IP address */" .C " struct in_addr siaddr; /* server IP address */" .C " struct in_addr giaddr; /* gateway IP address */" .C " unsigned char chaddr[16]; /* client hardware address */" .C " unsigned char sname[64]; /* server host name */" .C " unsigned char file[128]; /* boot file name */" .C " unsigned char options[312]; /* options area */" .C "}; .fi .SS DHCP Option Numbers The DHCP/BootP options discussed above correspond to the option numbers in RFC1533 as follows: .nf .IP Number Tag Description 1 sm Subnet Mask 2 to Time Offset 3 gw Gateways 4 ts Time Servers 5 ns IEN 116 Name Servers 6 ds Domain Name Servers 7 lg Log Servers 8 cs Cookie Servers 9 lp LPR Servers 10 im Impress Servers 11 rl Resource Location Servers 12 hn Send Host Name in reply 13 bs Boot File Size 14 md Merit Dump File 15 dn Domain Name 16 ss Swap Server 17 rp Root Path 18 ef Extensions Path 28 ba Broadcast Address 33 sr Static Routes 40 yd NIS Domain 41 ys NIS Servers 42 nt NTP Servers 43 V### Vendor Specific Information 44 na NetBIOS Name Servers 45 nb NetBIOS Datagram Distribution Servers 46 nc NetBIOS Node Type 47 nd NetBIOS Scope 48 xf X Font Servers 49 xd X Display Manager 51 lease-time IP Address Lease Time 58 tr Lease Renewal Time (T1) 59 tv Lease Rebinding Time (T2) 60 class-id Class Identifier 61 ci Client Identifier .fi .SH EXAMPLES This is an example of a .CR /etc/bootptab file: .nf .IP .C "# Common entry" .C "\0 .C "global.defaults:\e" .C " bf=C2300A:\e" .C " hd=/usr/lib/X11/:\e" .C " hn:\e" .C " ht=ether:\e" .C " vm=rfc1048" .C "\0 .C "# Now the actual individual entries" .C "\0 .C "xterm1:\e" .C " tc=global.defaults:\e" .C " ha=08000903212F:\e" .C " ip=190.40.101.22" .C "\0 .C "xterm2:\e" .C " tc=global.defaults:\e" .C " ha=0800090324AC:\e" .C " ip=190.40.101.35" .C "\0 .C "# Common relay entry." .C "\0 .C "relay-default:\e" .C " ht=ethernet:\e" .C " bp=15.4.3.136 15.13.6.192:\e" .C " th=2:\e" .C " hp=5:" .C "\0 .C "# Relay entry for node2" .C "\0 .C "node2:\e" .C " tc=relay-default:\e" .C " ha=08000902CA00:" .C "\0 .C "# Group relay entry" .C "\0 .C "group-machines:\e" .C " tc=relay-default:\e" .C " ha=080009000000:\e" .C " hm=080009000000:" .C "\0 .C "# Turn the relay off (block the relay) for the following machines." .C "\0 .C "blocked-machines:\e" .C " ht=ethernet:\e" .C " ha=07000A000000:\e" .C " hm=07000A000000:" .C "\0 .C "# Relay definition for all other machines." .C "\0 .C "all:\e" .C " tc=relay-default:\e" .C " ha=000000000000:\e" .C " hm=000000000000:" .fi This is an example of a .C /etc/dhcpptab file: .nf .IP .C "# The first entry is for options which define the server's operation." .C "\0 .C "DHCP_SERVER_SETTINGS:\e" .C " call-on-unrequited=""/tmp/unrequited.script"" :\e" .C "\0 .C "# The next entry is for options that will be applied to all groups." .C "# Individual options may be overridden for a specific group if the group" .C "# also configures the option." .C "\0 .C "DHCP_DEFAULT_CLIENT_SETTINGS:\e" .C " hn:\e" .C " lease-time=10080:\e" .C "\0 .C "# The next entry defines an address pool for devices with the class" .C "# id ""xterminal"" on subnet 15.14.128. Address leases will be granted" .C "# for up to 1 week. The server will use a broadcast message to " .C "# respond to all client requests." .C "\0 .C "DHCP_DEVICE_GROUP:\e" .C " ba:\e" .C " class-name=SUBNET_128_XTERMINAL_GROUP:\e" .C " class-id=""xterminal:""\e" .C " subnet-mask=255.255.255.0 :\e" .C " addr-pool-start-address= 15.14.128.1 :\e" .C " addr-pool-last-address= 15.14.128.254 :\e" .C " lease-time=604800 :\e" .C " lease-grace-period=5 :\e" .C "\0 .C "# The next entry grants IP leases to any device on subnet" .C "# 15.13.128. The script /usr/local/bin/assignment.script will be" .C "# run whenever a new lease is granted." .C "\0 .C "DHCP_POOL_GROUP:\e" .C " pool-name=RED_SUBNET_POOL:\e" .C " call-on-assignment=""/usr/local/bin/assignment.script"" :\e" .C " subnet-mask=255.255.255.0 :\e" .C " addr-pool-start-address= 15.13.128.100 :\e" .C " addr-pool-last-address= 15.13.128.254 :\e" .C " gw=15.13.128.1 :\e" .C "\0 .fi .SH WARNINGS Individual host entries must not exceed 1024 characters. .SH AUTHOR .CR bootpd was developed by Carnegie Mellon University, Stanford University, and HP. .SH FILES .CR /etc/bootptab .br .CR /etc/dhcptab .br .CR /etc/services .SH SEE ALSO bootpquery(1M), dhcptools(1M), inetd(1M), tftpd(1M), syslog(3C), hosts(4). .PP DARPA Internet Requests For Comments: RFC865, RFC868, RFC887, RFC951, RFC1010, RFC1034, RFC1048, RFC1084, RFC1395, RFC1533, RFC1534, RFC1541, RFC1542. .\" .\" index@\f4bootpd\f1 \- Internet Boot Protocol server@@@\f3bootpd(1M)\f1 .\" index@Internet Boot Protocol server@@@\f3bootpd(1M)\f1 .\" index@Boot Protocol server, Internet@@@\f3bootpd(1M)\f1 .\" index@server, Internet Boot Protocol@@@\f3bootpd(1M)\f1 .\" .\" toc@\f3bootpd(1M)\f1:\0\0\f4bootpd\f1@@@Internet Boot Protocol server .\" $Header: bootpquery.1m,v 76.1 95/06/12 14:32:31 ssa Exp $ .TA b .TH bootpquery 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bootpquery \- send BOOTREQUEST to BOOTP server .SH SYNOPSIS .C /usr/sbin/bootpquery .I haddr .RI [ \|htype\| ] .RI [ \|options\| ] .SH DESCRIPTION .CR bootpquery is a diagnostic function used to check the configuration of the Internet Bootstrap Protocol (BOOTP) server, .IR bootpd (1M). This function can only be run by the superuser, since it uses reserved ports. .PP .CR bootpquery constructs a boot request with the supplied parameters to send to the BOOTP server, and prints the contents of the BOOTP server reply (as shown in EXAMPLES, below). Note that .CR bootpquery formats and prints RFC-1048 or CMU-style vendor information included in the BOOTREPLY. .PP The BOOTREQUEST packet is broadcast on the BOOTP server port, .CR bootps . If a BOOTP server is configured to respond to the request, it returns a BOOTREPLY packet on the BOOTP client port, .CR bootpc . .CR bootpquery can only display BOOTREPLY packets when the BOOTP server broadcasts the reply on the client port or when the hardware address and IP address supplied in the BOOTREQUEST are those of the host on which .CR bootpquery is run. .PP The following options provide the information for the BOOTREQUEST: .RS .TP 8 .C haddr Hardware address of the BOOTP client; used in the BOOTREQUEST. A BOOTP server responds if it has configuration information for a host with this link-level address. .TP .C htype Type of address specified as .IR haddr ; may be .C ether or .CR ieee802 . The default address type is .CR ether . .TP .CI \-i ipaddr Specify the internet address of the BOOTP client to be used in the BOOTREQUEST. If the BOOTP client does not know its IP address, the BOOTP server supplies it in the BOOTREPLY. Otherwise, the server returns the BOOTREPLY directly to ipaddr. .TP .CI \-s server Specify the name of the BOOTP server to receive BOOTREQUEST. When the BOOTP server is known, the BOOTREQUEST is not broadcast. .TP .CI \-v vendor Specify a vendor name to include vendor information in the BOOTREPLAY. .I vendor can be specified as .C rfc1048 or .CR cmu . For any other .I vendor specification, the first four characters of the parameter are used as the vendor magic cookie. .TP .CI \-f Specify that .C bootpd should broadcast the reply back. This option is only valid for .C bootpd on the HPUX 10.0 (or later) release(s). .TP .CI \-b bootfile Specify a boot file needed by the BOOTP client. If a boot file is specified in the BOOTREQUEST, the BOOTP server responds only if the server host can make the file available. .SH EXAMPLES .RS .nf /usr/sbin/bootpquery 02608cee018e ether -s hpserver .PP Received BOOTREPLY from hpserver.hp.com (15.9.18.119) .PP Hardware Address: 02:60:8c:ee:01:8e Hardware Type: ethernet IP Address: 15.9.18.113 Boot file: /export/tftpdir/hp-gw2-confg .PP RFC 1048 Vendor Information: Subnet Mask: 255.255.248.0 Bootfile Size: 6 512 byte blocks Domain Name Server: 15.9.18.119 Host Name: hp-gw2 .fi .RE .SH AUTHOR .CR bootpquery was developed by HP. .SH SEE ALSO bootpd(1M), tftp(1), tftpd(1M) .br DARPA Internet Request For Comments RFC951, RFC1048, RFC1084, RFC1395, RFC1542 Assigned Numbers. .\" .\" index@\f4bootpquery\f1 \- send BOOTREQUEST to BOOTP server@@@\f3bootpquery(1M)\f1 .\" index@\f1send BOOTREQUEST to BOOTP server@@@\f3bootpquery(1M)\f1 .\" index@\f1BOOTREQUEST, send to BOOTP server@@@\f3bootpquery(1M)\f1 .\" index@\f1BOOTP server, send BOOTREQUEST to@@@\f3bootpquery(1M)\f1 .\" index@\f1server, send BOOTREQUEST to BOOTP@@@\f3bootpquery(1M)\f1 .\" .\" toc@\f3bootpquery(1M)\f1:\0\0\f4bootpquery\f1@@@send BOOTREQUEST to BOOTP server ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" CHANGED ...\" 12-10-91: Modified the paragraph under CAUTIONS to warn against ...\" directly editing any administrative (admin) file. ...\" END CHANGED ...\" .rm zA .rm zZ .TH "bos" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "syntax" .SH NAME .PP \*Lbos\*O \- Introduction to the \*Lbos\*O command suite .SH "OPTIONS" .PP The following options are used with many \*Lbos\*O commands. They are also listed with the commands that use them. .VL .LI "\*L\-server\*O \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the machine running the BOS Server that is to execute the command. To run a privileged \*Lbos\*O command (a \*Lbos\*O command that requires the issuer to have some level of administrative privilege) using a privileged identity, always specify the full DCE pathname of the machine (for example, \*L/.../abc.com/hosts/fs1\*O). .PP To run an unprivileged \*Lbos\*O command, you can use any of the following to specify the machine: .ML .LI The machine's DCE pathname (for example, \*L/.../abc.com/hosts/fs1\*O) .LI The machine's host name (for example, \*Lfs1.abc.com\*O or \*Lfs1\*O) .LI The machine's IP address (for example, \*L11.22.33.44\*O) .LE .nS "note" .iX "authorization checking" "unprivileged identity" If you specify the host name or IP address of the machine, the command executes using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option); unless DFS authorization checking is disabled on the specified machine, a privileged \*Lbos\*O command issued in this manner fails. If you specify the machine's host name or IP address, the command displays the following message (using the \*L\-noauth\*O option suppresses the message): .oS bos: WARNING: short form for server used; no authentication information will be sent to the bosserver .oE .nE .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zA "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs the \*Lbos\*O program to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. Generally, the \*L\-noauth\*O option is included with a command if DFS authorization checking is disabled on the server machine whose BOS Server is to execute the command or if the Security Service is unavailable. If DFS authorization checking is disabled, the BOS Server requires no administrative privilege to issue any command; any user, even the identity \*Lnobody\*O, has sufficient privilege to perform any operation. If the Security Service is unavailable, a user's security credentials cannot be obtained. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .PP DFS authorization checking is disabled with the \*Lbos setauth\*O command or by including the \*L\-noauth\*O option when the \*Lbosserver\*O process is started on a machine. DFS authorization checking is typically disabled .ML .LI During initial DFS installation .LI If the Security Service is unavailable .LI During server encryption key emergencies .LI To view the actual keys stored in a keytab file .LE .PP .zA "defect,7219,R1.0.2,Review comments" Include the \*L\-noauth\*O option with a command that requires administrative privilege only if DFS authorization checking is disabled on the necessary machine. A command that requires administrative privilege fails if the \*L\-noauth\*O option is included and DFS authorization checking is not disabled. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,7219,R1.0.2,Review comments" .zZ "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal of the machine on which the command is issued as the identity of the issuer. Each DFS server machine has a DFS server principal stored in the Registry Database. A DFS server principal is a unique, fully qualified principal name that ends with the string \*Ldfs-server\*O; for example, \*L/.../abc.com/hosts/fs1/dfs-server\*O. (Do not confuse a machine's DFS server principal with its unique \*Lself\*O identity.) .PP Use this option only if the command is issued from a DFS server machine. You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for the command. All other valid options specified with this option are ignored. For complete details about receiving help, see the \*Ldfs_intro(1m)\*O reference page. .LE .SH "DESCRIPTION" .PP .zA "enh,R1.0.2,Clarify role of BOS Server" Commands in the \*Lbos\*O command suite are used by system administrators to contact the Basic OverSeer (BOS) Server. The BOS Server runs on every DFS server machine to monitor the other DFS server processes on the machine. It restarts processes automatically if they fail. The BOS Server also provides an interface through which system administrators can start and stop processes and check on server status. .PP The files described in the following sections are used to store configuration, administrative, and security information. .zZ "enh,R1.0.2,Clarify role of BOS Server" .SS "The BosConfig File" .PP .zA "enh,R1.0.2,Clarify BOS Server files" The \*Edcelocal\*L/var/dfs/BosConfig\*O file on the local disk of each DFS server machine contains information about the processes the BOS Server is to monitor. This information includes the process type, the command parameters associated with the process, and a status flag that tells the BOS Server to start the process at initialization or restart the process if the process fails. Whenever the BOS Server starts or restarts, it reads the file to learn which processes to monitor; this information is transferred into memory and the file is not read again until the BOS Server next restarts. .zZ "enh,R1.0.2,Clarify BOS Server files" .PP The administrator can change the process status in the BOS Server's memory with specific \*Lbos\*O commands; therefore, it is possible for a process to stop running even if its status flag in the BosConfig file is set to \*LRun\*O. Similarly, an administrator can start a process without setting its status flag in the \*LBosConfig\*O file to \*LRun\*O by changing its memory state flag to \*LRun\*O. .PP .zA "defect,7219,R1.0.2,Review comments" Never edit the \*LBosConfig\*O file directly; always use the appropriate \*Lbos\*O commands. Editing the file directly can introduce changes of which the BOS Server is unaware. The BOS Server does not recognize such changes until it is restarted and again reads the file. .zZ "defect,7219,R1.0.2,Review comments" .SS "The admin.bos File" .PP .zA "defect,7219,R1.0.2,Review comments" The \*Edcelocal\*L/var/dfs/admin.bos\*O file on the local disk of each File Server machine contains the names of users who are allowed to issue \*Lbos\*O commands on that machine. All users can list the contents of the file with the \*Lbos lsadmin\*O command; only administrative users can edit the contents of the file with the \*Lbos addadmin\*O and \*Lbos rmadmin\*O commands. Because the \*Ladmin.bos\*O file is a binary file, you cannot edit it directly; you must use the appropriate \*Lbos\*O commands. .zZ "defect,7219,R1.0.2,Review comments" .SS "The Keytab File" .PP A \*L/krb5/v5srvtab\*O keytab file is stored on the local disk of each File Server machine. A keytab file contains the list of server encryption keys used by a server process on that machine to decrypt tokens presented by clients. The server process interacts only with clients possessing tokens encrypted with server encryption keys listed in the appropriate keytab file. .PP The keys in a keytab file are marked with a unique key version number. All tokens presented by clients are also marked with a key version number; a server process uses the key version number to determine which key to use to decrypt a token. .PP Only administrative users can examine, add, and remove keys in the keytab file. Never edit a keytab file directly; always use the appropriate \*Lbos\*O commands. .SS "Receiving Help" .PP There are several different ways to receive help about DFS commands. The following examples summarize the syntax for the different help options: .VL .LI "\*C$\*O \*Lman bos\*O" Displays the reference page for the command suite. .LI "\*C$\*O \*Lman bos_\*Vcommand\*O" Displays the reference page for an individual command. You must use an _ (underscore) to connect the command suite to the command name. \*EDo not use the underscore when issuing the command in DFS.\*O .LI "\*C$\*O \*Lbos help\*O" Displays a list of commands in a command suite. .LI "\*C$\*O \*Lbos help \*Vcommand\*O" Displays the syntax for a single command. .zA "misc,R1.0.2,Repair PH work mistakes" .LI "\*C$\*O \*Lbos apropos -topic \*Vstring\*O" Displays a short description of any commands that match the specified \*Vstring\*O. .zZ "misc,R1.0.2,Repair PH work mistakes" .LE .PP Consult the \*Ldfs_intro(1m)\*O reference page for complete information about the DFS help facilities. .SS "Privilege Required" .PP All \*Lbos\*O commands can be issued by users listed in the \*Ladmin.bos\*O file on the machine whose BOS Server is executing the command. Specific privilege information is listed with each command's description. In addition, if the BOS Server is running with DFS authorization checking disabled, no privilege is required to issue \*Lbos\*O commands. .SH "CAUTIONS" .PP Never directly edit a \*LBosConfig\*O file, a keytab file, an \*Ladmin.bos\*O file, or any administrative (\*Ladmin\*O) file; always use the appropriate commands from the \*Lbos\*O command suite. .SH "RELATED INFORMATION" Commands: \*Lbos addadmin(1m)\*O, \*Lbos addkey(1m)\*O, .zA "defect,5790,R1.0.2,Move bos lscell back to Admin Ref" \*Lbos apropos(1m)\*O, .zZ "defect,5790,R1.0.2,Move bos lscell back to Admin Ref" \*Lbos create(1m)\*O, \*Lbos delete(1m)\*O, .zA "defect,5801,R1.0.2,Remove bos exec command" .zZ "defect,5801,R1.0.2,Remove bos exec command" \*Lbos gckeys(8ds)\*O, \*Lbos genkey(1m)\*O, \*Lbos getdates(1m)\*O, \*Lbos getlog(1m)\*O, \*Lbos getrestart(1m)\*O, .zA "defect,5790,R1.0.2,Move bos lscell back to Admin Ref" \*Lbos help(1m)\*O, .zZ "defect,5790,R1.0.2,Move bos lscell back to Admin Ref" \*Lbos install(1m)\*O, \*Lbos lsadmin(1m)\*O, .zA "defect,5790,R1.0.2,Move bos lscell back to Admin Ref" \*Lbos lscell(1m)\*O, .zZ "defect,5790,R1.0.2,Move bos lscell back to Admin Ref" \*Lbos lskeys(1m)\*O, \*Lbos prune(1m)\*O, \*Lbos restart(1m)\*O, \*Lbos rmadmin(1m)\*O, \*Lbos rmkey(1m)\*O, \*Lbos setauth(1m)\*O, \*Lbos setrestart(1m)\*O, \*Lbos shutdown(1m)\*O, \*Lbos start(1m)\*O, \*Lbos startup(1m)\*O, \*Lbos status(1m)\*O, \*Lbos stop(1m)\*O, \*Lbos uninstall(1m)\*O, \*Ldfs_intro(1m)\*O, .zA "enh,R1.0.2,Reference security ref pages from some bos pages" .zA "defect,12535,R1.1,Incorporate dcecp commands" \*Lkeytab(1m)\*O .zZ "defect,12535,R1.1,Incorporate dcecp commands" .zA "defect,5790,R1.0.2,Move bos lscell back to Admin Ref" .zZ "defect,5790,R1.0.2,Move bos lscell back to Admin Ref" .PP .zA "enh,R1.0.2,Add list of files" Files: \*Ladmin.bak(4)\*O, \*Ladmin.bos(4)\*O, \*Ladmin.fl(4)\*O, \*Ladmin.ft(4)\*O, \*Ladmin.up(4)\*O, \*LBosConfig(4)\*O, \*Lv5srvtab(5)\*O .zZ "enh,R1.0.2,Add list of files" .zZ "enh,R1.0.2,Reference security ref pages from some bos pages" .iX "-]" "\*Lbos\*O command suite" "syntax" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos addadmin" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Laddadmin\*O" .iX "-[" "administrative lists" "adding members" .iX "-[" "principals" "on administrative lists" .iX "-[" "groups" "on administrative lists" .SH NAME .PP \*Lbos addadmin\*O \- Adds a user, group, or server to an administrative list .SH "SYNOPSIS" .sS \*Lbos addadmin -server \*Vmachine\*L -adminlist \*Vfilename\*O [\*L\-principal \*Vname\*O...] [\*L\-group \*Vname\*O...] .nL [\*L\-createlist\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine that houses the administrative list to which principals, groups, or both are to be added. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-adminlist \*Vfilename\*O" Names the administrative list to which principals, groups, or both are to be added. The complete pathname is unnecessary if the list is stored in the default configuration directory (\*Edcelocal\*O\*L/var/dfs\*O). .LI "\*L\-principal \*Vname\*O" .zA "defect,6542,R1.0.2,Improve principal/group option descriptions" Specifies the principal name of each user or server machine to be added to the administrative list. A user from the local cell can be specified by a full or abbreviated principal name (for example, \*L/.../\*Ecellname\*L/\*Eusername\*O or just \*Eusername\*O); a user from a foreign cell can be specified only by a full principal name. A server machine from the local cell can be specified by a full or abbreviated principal name (for example, \*L/.../\*Ecellname\*L/hosts/\*Ehostname\*L/self\*O or just \*Lhosts/\*Ehostname\*L/self\*O); a server machine from a foreign cell can be specified only by a full principal name. .zZ "defect,6542,R1.0.2,Improve principal/group option descriptions" .LI "\*L\-group \*Vname\*O" .zA "defect,6542,R1.0.2,Improve principal/group option descriptions" Specifies the name of each group to be added to the administrative list. A group from the local cell can be specified by a full or abbreviated group name (for example, \*L/.../\*Ecellname\*L/\*Egroup_name\*O or just \*Egroup_name\*O); a group from a foreign cell can be specified only by a full group name. .zZ "defect,6542,R1.0.2,Improve principal/group option descriptions" .LI "\*L\-createlist\*O" .zA "defect,5787,R1.0.2,-createlist creates an empty list" Specifies that the file indicated with \*L\-adminlist\*O is to be created if it is not found. Any principals or groups specified with the command are added to the new file; if no principals or groups are specified, the command creates an empty file. This option has no effect if the specified file already exists. .nS "Note" .zA "defect,7219,R1.0.2,Review comments" Because the \*Ladmin.bos\*O list must already exist to issue this command, this option is ignored if \*Ladmin.bos\*O is specified with the \*L\-adminlist\*O option. .zZ "defect,7219,R1.0.2,Review comments" .nE .zZ "defect,5787,R1.0.2,-createlist creates an empty list" .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,6542,R1.0.2,Improve principal/group option descriptions" The \*Lbos addadmin\*O command adds the specified users, groups, and servers to the administrative list specified by the \*L\-adminlist\*O option on the server machine indicated by the \*L\-server\*O option. The principal (login) names of users and the principal names of server machines to be added to the administrative list are specified with the \*L\-principal\*O option; the names of groups to be added to the list are specified with the \*L\-group\*O option. Principals added to the administrative list either directly (with the \*L\-principal\*O option) or indirectly (as members of groups indicated with the \*L\-group\*O option) can then issue administrative commands for the DFS server process associated with the list. .zZ "defect,6542,R1.0.2,Improve principal/group option descriptions" .PP The default path for administrative lists is the configuration directory (\*Edcelocal\*O\*L/var/dfs\*O). If the specified list is stored in the default directory, only the specific filename is required. If the specified list is stored elsewhere, the pathname to the file that was used when the associated server process was started is required. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .SH "EXAMPLES" .PP The following command adds the user names \*Ljones\*O and \*Lsmith\*O to the \*Ladmin.bos\*O file on \*Lfs1\*O. The administrative list is stored in the default configuration directory. .iS \*C$\*O \*Lbos adda -server /.../abc.com/hosts/fs1 -adminlist admin.bos -principal jones smith\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lbos lsadmin(1m)\*O, \*Lbos rmadmin(1m)\*O .PP Files: \*Ladmin.bak(4)\*O, \*Ladmin.bos(4)\*O, \*Ladmin.fl(4)\*O, \*Ladmin.ft(4)\*O, \*Ladmin.up(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Laddadmin\*O" .iX "-]" "administrative lists" "adding members" .iX "-]" "principals" "on administrative lists" .iX "-]" "groups" "on administrative lists" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" CHANGED ...\" 12-11-91: In DESCRIPTION, replaced the last sentence of the first ...\" paragraph with two new paragraphs. ...\" END CHANGED ...\" .rm zA .rm zZ .TH "bos addkey" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Laddkey\*O" .iX "-[" "passwords" "DFS server" .iX "-[" "DFS servers" "passwords" .SH NAME .PP \*Lbos addkey\*O \- Converts a string into a server encryption key and adds it to a keytab file .SH "SYNOPSIS" .sS .zA "defect,5786,R1.0.2,Change bos add/genkey -kvno option" \*Lbos addkey -server \*Vmachine\*L -kvno \*V+_or_version_number\*L -password \*Vstring\*O .nL [\*L\-principal \*Vname\*O] [\*L\-localonly\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .zZ "defect,5786,R1.0.2,Change bos add/genkey -kvno option" .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine whose keytab file is to have a new key added to it. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5786,R1.0.2,Change bos add/genkey -kvno option" .LI "\*L\-kvno \*V+_or_version_number\*O" Defines the key version number of the new key. The version number must be one of the following: .ML .LI An integer in the range 1 to 255. The command uses the specified integer as the version number of the new key. The integer must be unique for the principal indicated by \*L\-principal\*O in the keytab file on the server machine specified by \*L\-server\*O. .LI \*L+\*O or \*L0\*O (zero). The command chooses an integer to serve as the version number of the new key. The integer it chooses is unique for the principal indicated by \*L\-principal\*O in the Registry Database. However, it may not be unique for the indicated principal in the keytab file on the specified machine, in which case it replaces the key currently associated with the principal/version number pair in the keytab file. .LE .PP Unless the \*L\-localonly\*O option is used, the new key and its version number replace the key and version number currently stored in the Registry Database for the indicated principal. .zZ "defect,5786,R1.0.2,Change bos add/genkey -kvno option" .LI "\*L\-password \*Vstring\*O" Defines a character string to be converted into an octal string for use as the key. The string serves as a password for the indicated principal. It can include any characters; it can also include spaces if the entire string is enclosed in \*L"\|"\*O (double quotes). .LI "\*L\-principal \*Vname\*O" Provides the principal name with which the key is to be associated. The default is the DFS principal name of the machine specified by \*L\-server\*O. .LI "\*L\-localonly\*O" Specifies that the key is to be added to the keytab file on the machine indicated by \*L\-server\*O, but that the Registry Database is not to be updated. The default is to add the key to the local keytab file and update the Registry Database accordingly. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,5786,R1.0.2,Change bos add/genkey -kvno option" The \*Lbos addkey\*O command associates a new server encryption key with the principal name indicated by \*L\-principal\*O in the \*L/krb5/v5srvtab\*O keytab file on the server machine specified by \*L\-server\*O and, by default, in the Registry Database. The key is derived from the string specified by \*L\-password\*O and is given the version number specified by \*L\-kvno\*O. The issuer can either specify a version number or have the command choose one that is unique for the indicated principal in the Registry Database. If the \*L\-localonly\*O option is omitted, the server encryption key and version number for the indicated principal are automatically updated both in the keytab file on the specified server machine and in the Registry Database; if the \*L\-localonly\*O option is specified, the keytab file is updated, but the Registry Database is not. .PP .zA "defect,12535,R1.1,Incorporate dcecp commands" The \*Lbos genkey\*O command is a more secure way of adding a key to a keytab file because it generates a random key. It also always updates the Registry Database. The keytab file must already exist before the \*Lbos addkey\*O or \*Lbos genkey\*O command can be used to add a key to it. (Keytab files are created with the \*Ldcecp keytab create\*O command.) .zZ "defect,12535,R1.1,Incorporate dcecp commands" .zZ "defect,5786,R1.0.2,Change bos add/genkey -kvno option" .SS "Privilege Required" .PP You must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O, and, unless the \*L\-localonly\*O option is used, the DFS server principal of the machine specified by \*L\-server\*O must have the permissions necessary to alter entries in the Registry Database. .zA "defect,7219,R1.0.2,Review comments" .SH "OUTPUT" .PP If the packet privacy protection level is not available to you, the command displays the following message reporting that the BOS Server is using the packet integrity protection level instead: .oS \*CData encryption unsupported by RPC. Continuing without it.\*O .oE .zZ "defect,7219,R1.0.2,Review comments" .SH "EXAMPLES" .PP The following command adds a new server encryption key with key version number \*L14\*O to the keytab file on \*Lfs1\*O without updating the Registry Database. Because \*L\-principal\*O is omitted, the key is associated with the DFS principal name of \*Lfs1\*O (the machine specified with \*L\-server\*O). The password string \*Lfourteenth new key\*O is converted into an octal key before being placed in the keytab file. .iS \*C$\*O \*Lbos addk /.../abc.com/hosts/fs1 14 "fourteenth new key" -localonly\*O .iE .SH "RELATED INFORMATION" .PP .zA "enh,R1.0.2,Reference security ref pages from some bos pages" Commands: \*Lbos gckeys(1m)\*O, \*Lbos genkey(1m)\*O, \*Lbos lskeys(1m)\*O, \*Lbos rmkey(1m)\*O, .zA "defect,12535,R1.1,Incorporate dcecp commands" \*Lkeytab(1m)\*O .zZ "defect,12535,R1.1,Incorporate dcecp commands" .PP Files: \*Lv5srvtab(5)\*O .zZ "enh,R1.0.2,Reference security ref pages from some bos pages" .iX "-]" "\*Lbos\*O command suite" "\*Laddkey\*O" .iX "-]" "passwords" "DFS server" .iX "-]" "DFS servers" "passwords" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the .\" src directory for the full copyright text. ...\" ...\"Copyright (C) 1989, 1991, Transarc Corporation ...\"The Gulf Tower ...\"707 Grant Street ...\"Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "bos apropos" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lapropos\*O" .zA "def,5790,R1.0.2,Move bos lscell back to Admin Ref" .SH NAME .PP \*Lbos apropos \*O \- Shows each help entry containing a specified string .SH "SYNOPSIS" .PP .sS \*Lbos apropos -topic\*O \*Vstring\*O [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-topic \*Vstring\*O" Specifies the keyword string for which to search. If it is more than a single word, surround the string with \*L"\|"\*O (double quotes) or other delimiters. Type all strings for \*Lbos\*O commands in lowercase letters. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lbos apropos\*O command displays the first line of the help entry for any \*Lbos\*O command containing the string specified by \*L-topic\*O in its name or short description. .PP To display the syntax for a command, use the \*Lbos help\*O command. .zA "Defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "Defect,5933,R1.0.2,Include privilege required" .SH "OUTPUT" .PP The first line of an online help entry for a command lists the command and briefly describes its function. This command displays the first line for any \*Lbos\*O command where the string specified by \*L-topic\*O is part of the command name or the first line. .SH "EXAMPLES" .PP The following command lists all \*Lbos\*O commands that have the word \*Lrestart\*O in their names or short descriptions: .iS \*C$\*L bos apropos restart\*O .iE .oS getrestart: get restart times restart: restart all processes setrestart: set restart times for server processes .oE .SH "RELATED INFORMATION" .PP Commands: \*Lbos help(1m)\*O .zZ "def,5790,R1.0.2,Move bos lscell back to Admin Ref" .iX "-]" "\*Lbos\*O command suite" "\*Lapropos\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos create" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lcreate\*O" .iX "-[" "\*LBosConfig\*O file" "adding entries" .iX "-[" "DFS servers" "creating" .SH NAME .PP \*Lbos create\*O \- Creates a new process in the \*LBosConfig\*O file and starts it .SH "SYNOPSIS" .sS .PP \*Lbos create -server \*Vmachine\*L -process \*Vserver_process\*L -type \*Vprocess_type\*L -cmd \*Vcmd_line\*O... .nL [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine on which to create the new process. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-process \*Vserver_process\*O" Names the server process to be created. You can choose any name for a process, but it is recommended that you give the process the same name as its binary file (and use the same name on every machine running that process). The recommended names are .VL .LI "\*Lftserver\*O" For the Fileset Server process .LI "\*Lflserver\*O" For the Fileset Location Server process .LI "\*Lupclient\*O" For the client portion of the Update Server, which brings common configuration files and binary files from the System Control and Binary Distribution machines .LI "\*Lupserver\*O" For the server portion of the Update Server process .LI "\*Lrepserver\*O " For the Replication Server process .LI "\*Lbakserver\*O " For the Backup Server process .LE .PP .zA "defect,8633,R1.0.3,The bos create command" Each process runs under the local identity \*Lroot\*O and the DCE identity \*Lself\*O. However, the process is unauthenticated as far as DFS is concerned. .zZ "defect,8633,R1.0.3,The bos create command" .LI "\*L\-type \*Vprocess_type\*O" Specifies the process type. Legal values are \*Lsimple\*O and \*Lcron\*O. Specify \*Lsimple\*O for continuous processes and \*Lcron\*O for processes that are to run only at specified times. .LI "\*L\-cmd\*O" Specifies the commands the BOS Server runs to start the process and, if \*L\-type\*O is \*Lcron\*O, the time the BOS Server executes the command. .PP \*EFor a \*Lsimple\*E process\*O, this must be the complete pathname to the binary file for the process (for example, \*Edcelocal\*O\*L/bin/flserver\*O for the Fileset Location Server). The commands for some \*Lsimple\*O processes take options, in which case the entire argument must be surrounded with \*L"\|"\*O (double quotes). .PP \*EFor a \*Lcron\*E process\*O, provide two parameters. The first parameter is either the pathname to a binary file to be executed or the complete pathname of a command from one of the DFS suites (complete with all of the necessary arguments). Surround this parameter with \*L"\|"\*O (double quotes) if it contains spaces. .PP .zA "defect,8633,R1.0.3,The bos create command" If the specified executable file does not exist, the \*Lbos create\*O command does not create an entry in the \*LBosConfig\*O file. Instead, the command displays the following message: .oS bos: failed to create a new server instance \*Vinstance\*C of .nL type \*Vprocess_type\*C (specified executable not found) .oE .zZ "defect,8633,R1.0.3,The bos create command" .PP The second parameter for a \*Lcron\*O process specifies the time when the BOS Server is to execute the command specified by the first parameter. Use a day and time together to execute the command weekly at the specified time; use a time alone to execute the command daily at the specified time. Day and time specifications have the following format: .sS [\*Eday\*O] \*Ehh\*O:\*Emm\*O .sE .PP .zA "defect,8633,R1.0.3,The bos create command" Enter the name of the day in all lowercase letters, giving either the whole name or the first three letters as an abbreviation (for example, \*Lsunday\*O or \*Lsun\*O). Specify the time of day by separating the hours from the minutes with a \*L:\*O (colon). Use 24-hour time (for example, \*L14:30\*O), or use 1:00 to 12:00 with \*Lam\*O or \*Lpm\*O (for example, \*L"2:30 pm"\*O). The time part of the option is optional if the day is specified; if the time is excluded, it defaults to 00:00 on the specified day. As shown in the example, enclose the entire entry in \*L"\|"\*O (double quotes) if it contains a space. .zZ "defect,8633,R1.0.3,The bos create command" .PP .zA "defect,7219,R1.0.2,Review comments" .zA "defect,5801,R1.0.2,Remove bos exec command" To execute the command only once, specify \*Lnow\*O instead of a day or a day and time, or issue the command directly; the process entry is removed from the \*LBosConfig\*O file after the command is executed. To place the process entry in the \*LBosConfig\*O file without ever executing it, specify \*Lnever\*O instead of a time or a day and time. .zZ "defect,5801,R1.0.2,Remove bos exec command" .zZ "defect,7219,R1.0.2,Review comments" .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lbos create\*O command creates a new server process on the server machine specified by \*L\-server\*O by creating an entry in the \*LBosConfig\*O file on the local disk of the machine. The status of the new process entry in both the \*LBosConfig\*O file and memory is set to \*LRun\*O, and the process is started on the server machine (unless the process is a \*Lcron\*O process and the second parameter of the \*L\-cmd\*O option is \*Lnever\*O). .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .SH "EXAMPLES" .PP The following command creates the \*Lsimple\*O process \*Lflserver\*O on the machine named \*Lfs3\*O: .iS \*C$\*O \*Lbos create /.../abc.com/hosts/fs3 flserver simple \*Edcelocal\*L/bin/flserver\*O .iE .PP .zA "defect,5120,R1.0.2,Correct use of -localauth option" The following command creates the \*Lcron\*O process named \*Lbackup\*O on the machine named \*Lfs3\*O. The \*L\-localauth\*O option allows the process (which runs unauthenticated) to use the DFS server principal of \*Lfs3\*O to execute the privileged \*Lfts clonesys\*O command. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .iS \*C$\*O \*Lbos create /.../abc.com/hosts/fs3 backup cron "\*Vdcelocal\*L/bin/fts clonesys -s /.../abc.com/hosts/fs3 \\ -localauth" 5:30\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lbos delete(1m)\*O .PP Files: \*LBosConfig(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Lcreate\*O" .iX "-]" "\*LBosConfig\*O file" "adding entries" .iX "-]" "DFS servers" "creating" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos delete" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Ldelete\*O" .iX "-[" "\*LBosConfig\*O file" "deleting entries" .iX "-[" "DFS servers" "deleting" .SH NAME .PP \*Lbos delete\*O \- Deletes server processes from the \*LBosConfig\*O file .SH "SYNOPSIS" .sS \*Lbos delete -server \*Vmachine\*L -process \*Vserver_process\*O... [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine from which to delete one or more server processes. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-process \*Vserver_process\*O" Names each process to delete. Use the name assigned with the \*L\-process\*O option in the \*Lbos create\*O command; if necessary, use the \*Lbos status\*O command to list the possible process names. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lbos delete\*O command removes each indicated server process entry from the \*LBosConfig\*O file on the server machine specified by \*L\-server\*O. Before issuing this command, the issuer must use the \*Lbos stop\*O command to stop each indicated process, both \*Lsimple\*O and \*Lcron\*O, running on \*L\-server\*O. An error message results if the status flag of a process being deleted is \*LRun\*O when this command is issued. .SS "Privilege Required" .PP You must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .SH "EXAMPLES" .PP The following command removes the \*Lflserver\*O process entry from the \*LBosConfig\*O file on the machine named \*Lfs3\*O: .iS \*C$\*O \*Lbos delete /.../abc.com/hosts/fs3 flserver\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lbos create(1m)\*O .PP Files: \*LBosConfig(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Ldelete\*O" .iX "-]" "\*LBosConfig\*O file" "deleting entries" .iX "-]" "DFS servers" "deleting" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos gckeys" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lgckeys\*O" .iX "-[" "passwords" "DFS servers" .iX "-[" "DFS servers" "passwords" .SH NAME .PP \*Lbos gckeys\*O \- Removes obsolete server encryption keys from a keytab file .SH "SYNOPSIS" .sS \*Lbos gckeys -server \*Vmachine\*O [\*L\-principal \*Vname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine whose keytab file is to have obsolete keys removed from it. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-principal \*Vname\*O" Provides the principal name for which obsolete keys are to be removed from the keytab file. The default is the DFS principal name of the machine specified by \*L\-server\*O. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lbos gckeys\*O command removes obsolete server encryption keys from the \*L/krb5/v5srvtab\*O keytab file on the server machine specified by \*L\-server\*O. Obsolete keys associated only with the principal name specified by \*L\-principal\*O are removed from the keytab file; the DFS principal name of the server machine specified with \*L\-server\*O is used by default. .PP Keys are removed based on age and lack of use. The removal process, referred to as \*Lgarbage collection\*O, affects only the keytab file stored on the local disk of the machine indicated by \*L\-server\*O; it has no effect on the Registry Database. .SS "Privilege Required" .PP You must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .zA "defect,7219,R1.0.2,Review comments" .SH "OUTPUT" .PP If the packet privacy protection level is not available to you, the command displays the following message reporting that the BOS Server is using the packet integrity protection level instead: .oS \*CData encryption unsupported by RPC. Continuing without it.\*O .oE .zZ "defect,7219,R1.0.2,Review comments" .SH "EXAMPLES" .PP The following command removes obsolete keys associated with the principal \*Lhosts/fs1/dfs-server\*O from the keytab file on the server machine named \*L/.../abc.com/hosts/fs3\*O. Note that the keys being removed are associated with the principal name of a machine different from the one whose BOS Server is executing the command. .iS \*C$\*O \*Lbos gckeys /.../abc.com/hosts/fs3 hosts/fs1/dfs-server\*O .iE .SH "RELATED INFORMATION" .PP .zA "enh,R1.0.2,Reference security ref pages from some bos pages" Commands: \*Lbos addkey(1m)\*O, \*Lbos genkey(1m)\*O, \*Lbos lskeys(1m)\*O, \*Lbos rmkey(1m)\*O, .zA "defect,12535,R1.1,Incorporate dcecp commands" \*Lkeytab(1m)\*O .zZ "defect,12535,R1.1,Incorporate dcecp commands" .PP Files: \*Lv5srvtab(5)\*O .zZ "enh,R1.0.2,Reference security ref pages from some bos pages" .iX "-]" "\*Lbos\*O command suite" "\*Lgckeys\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" CHANGED ...\" 12-11-91: In DESCRIPTION, replaced the last sentence of the first ...\" paragraph with two new paragraphs. ...\" END CHANGED ...\" .rm zA .rm zZ .TH "bos genkey" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lgenkey\*O" .SH NAME .PP \*Lbos genkey\*O \- Generates a random key and adds it to a keytab file .SH "SYNOPSIS" .sS .zA "defect,5786,R1.0.2,Change bos add/genkey -kvno option" \*Lbos genkey -server \*Vmachine\*L -kvno \*V+_or_version_number\*O [\*L\-principal \*Vname\*O] .nL \*L[{-noauth | -localauth}] [-help]\*O .zZ "defect,5786,R1.0.2,Change bos add/genkey -kvno option" .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine whose keytab file is to have a new key added to it. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5786,R1.0.2,Change bos add/genkey -kvno option" .LI "\*L\-kvno \*V+_or_version_number\*O" Defines the key version number of the new key. The version number must be one of the following: .ML .LI An integer in the range 1 to 255. The command uses the specified integer as the version number of the new key. The integer must be unique for the principal indicated by \*L\-principal\*O in the keytab file on the server machine specified by \*L\-server\*O. .LI \*L+\*O or \*L0\*O (zero). The command chooses an integer to serve as the version number of the new key. The integer it chooses is unique for the principal indicated by \*L\-principal\*O in the Registry Database. However, it may not be unique for the indicated principal in the keytab file on the specified machine, in which case it replaces the key currently associated with the principal/version number pair in the keytab file. .LE .PP The new key and its version number always replace the key and version number currently stored in the Registry Database for the indicated principal. .zZ "defect,5786,R1.0.2,Change bos add/genkey -kvno option" .LI "\*L\-principal \*Vname\*O" Provides the principal name with which the key is to be associated. The default is the DFS principal name of the machine specified by \*L\-server\*O. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,5786,R1.0.2,Change bos add/genkey -kvno option" The \*Lbos genkey\*O command associates a new server encryption key with the principal name indicated by \*L\-principal\*O in the \*L/krb5/v5srvtab\*O keytab file on the server machine specified by \*L\-server\*O and in the Registry Database. The command generates a random key and assigns it the version number indicated by \*L\-kvno\*O. The issuer can either specify a version number or have the command choose one that is unique for the indicated principal in the Registry Database. The server encryption key and version number for the specified principal are automatically updated both in the keytab file on the specified server machine and in the Registry Database. .PP .zA "defect,12535,R1.1,Incorporate dcecp commands" The \*Lbos addkey\*O command can also be used to add a key to a keytab file with or without updating the Registry Database. However, it is less secure because the issuer must specify a string to be converted into the server encryption key. The keytab file must already exist before the \*Lbos genkey\*O or \*Lbos addkey\*O command can be used to add a key to it. (Keytab files are created with the \*Ldcecp keytab create\*O command.) .zZ "defect,12535,R1.1,Incorporate dcecp commands" .zZ "defect,5786,R1.0.2,Change bos add/genkey -kvno option" .SS "Privilege Required" .PP You must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O, and the DFS server principal of the machine specified by \*L\-server\*O must have the permissions necessary to alter entries in the Registry Database. .zA "defect,7219,R1.0.2,Review comments" .SH "OUTPUT" .PP If the packet privacy protection level is not available to you, the command displays the following message reporting that the BOS Server is using the packet integrity protection level instead: .oS \*CData encryption unsupported by RPC. Continuing without it.\*O .oE .zZ "defect,7219,R1.0.2,Review comments" .SH "EXAMPLES" .PP The following command generates a new server encryption key with key version number \*L14\*O and adds it to the keytab file on \*Lfs1\*O. Because \*L\-principal\*O is omitted, the key is associated with the DFS principal name of \*Lfs1\*O (the machine specified with \*L\-server\*O). The Registry Database is updated automatically. .iS \*C$\*O \*Lbos genkey /.../abc.com/hosts/fs1 14\*O .iE .SH "RELATED INFORMATION" .PP .zA "enh,R1.0.2,Reference security ref pages from some bos pages" Commands: \*Lbos addkey(1m)\*O, \*Lbos gckeys(1m)\*O, \*Lbos lskeys(1m)\*O, \*Lbos rmkey(1m)\*O, .zA "defect,12535,R1.1,Incorporate dcecp commands" \*Lkeytab(1m)\*O .zZ "defect,12535,R1.1,Incorporate dcecp commands" .PP Files: \*Lv5srvtab(5)\*O .zZ "enh,R1.0.2,Reference security ref pages from some bos pages" .iX "-]" "\*Lbos\*O command suite" "\*Lgenkey\*O" .iX "-]" "passwords" "DFS servers" .iX "-]" "DFS servers" "passwords" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos getdates" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lgetdates\*O" .iX "-[" "timestamps" "on binary files" .iX "-[" "binary files" "timestamps" .SH NAME .PP \*Lbos getdates\*O \- Lists time stamps on versions of binary files .SH "SYNOPSIS" .sS \*Lbos getdates -server \*Vmachine\*L -file \*Vbinary_file\*O... [\*L\-dir \*Valternate_dest\*O] .nL [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine that houses the binary files whose time stamps are to be displayed. The BOS Server on this machine executes the command. Specify the machine's DCE pathname, its host name, or its IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-file \*Vbinary_file\*O" .zA "defect,6021,R1.0.2,Fix -file and -dir options" Names the current version of each binary file whose time stamps are to be displayed. The time stamps on the current, \*L.BAK\*O, and \*L.OLD\*O versions of each file are displayed. All specified files must reside in the same directory (\*Edcelocal\*L/bin\*O, by default, or an alternate directory specified with the \*L\-dir\*O option\*O). Specify only filenames; if a pathname is provided for a file, the command ignores all but the final element. .zZ "defect,6021,R1.0.2,Fix -file and -dir options" .LI "\*L\-dir \*Valternate_dest\*O" .zA "defect,6021,R1.0.2,Fix -file and -dir options" Provides the pathname of the directory in which all specified files reside. Omit this option if the files reside in the default directory, \*Edcelocal\*L/bin\*O; otherwise, provide a full or relative pathname. Relative pathnames (pathnames that do not begin with a slash) are interpreted relative to the \*Edcelocal\*O directory on the machine specified by \*L\-server\*O. .zZ "defect,6021,R1.0.2,Fix -file and -dir options" .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,5782,R1.0.2,Include bos uninstall -all option and clarify" The \*Lbos getdates\*O command displays the time stamps for the current, \*L.BAK\*O, and \*L.OLD\*O versions of each binary file whose current version is specified with the \*L\-file\*O option. The time stamps record when the files were installed. The command displays a message for any version of a specified file that does not exist. Use the \*L\-server\*O option to specify the name of the server machine on which the files reside. The \*L\-dir\*O option can be used to specify the name of the directory in which the files reside if it is different from \*Edcelocal\*L/bin\*O. .PP The BOS Server automatically creates \*L.BAK\*O and \*L.OLD\*O versions when new binaries are installed with \*Lbos install\*O. Use the \*Lbos uninstall\*O command to replace the current version with its next-oldest version (\*L.BAK\*O or, if the \*L.BAK\*O version does not exist, \*L.OLD\*O) or to remove all versions of a binary file. Use the \*Lbos prune\*O command to remove \*L.BAK\*O and \*L.OLD\*O files from the \*Edcelocal\*L/bin\*O directory (the command can also be used to remove core files from the \*Edcelocal\*L/var/dfs/adm\*O directory). .zZ "defect,5782,R1.0.2,Include bos uninstall -all option and clarify" .zA "Defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "Defect,5933,R1.0.2,Include privilege required" .SH "OUTPUT" .PP .zA "defect,6021,R1.0.2,Fix -file and -dir options" For each file specified with the \*L\-file\*O option, the output reports the time stamps on the current, \*L.BAK\*O, and \*L.OLD\*O versions. The output displays a message to indicate any version that does not exist. .zZ "defect,6021,R1.0.2,Fix -file and -dir options" .SH "EXAMPLES" .PP The following command displays the time stamps on the three versions of the \*Lflserver\*O binary file stored in the default directory on the server machine named \*Lfs2\*O: .iS \*C$\*O \*Lbos getdates /.../abc.com/hosts/fs2 flserver\*O .iE .SH "RELATED INFORMATION" .PP Command: \*Lbos install(1m)\*O, \*Lbos prune(1m)\*O, \*Lbos uninstall(1m)\*O .iX "-]" "\*Lbos\*O command suite" "\*Lgetdates\*O" .iX "-]" "timestamps" "on binary files" .iX "-]" "binary files" "timestamps" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos getlog" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lgetlog\*O" .iX "-[" "log files" "examining (DFS)" .iX "-[" "DFS servers" "examining log files" .SH NAME .PP \*Lbos getlog\*O \- Examines the log file for a server process .SH "SYNOPSIS" .sS \*Lbos getlog -server \*Vmachine\*L -file \*Vlog_file\*O [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine from which to retrieve the log file. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-file \*Vlog_file\*O" .zA "defect,11180,R1.1,Incorporate DFS/NFS gateway doc" Names the log file to display. If a simple filename is provided, with no slashes, the file is assumed to reside in \*Vdcelocal\*L/var/dfs/adm\*O; the standard choices from that directory are \*LBakLog\*O, \*LBosLog\*O, \*LDfsgwLog\*O, \*LFlLog\*O, \*LFtLog\*O, \*LRepLog\*O, and \*LUpLog\*O. .zZ "defect,11180,R1.1,Incorporate DFS/NFS gateway doc" .PP Pathnames are interpreted relative to \*Edcelocal\*O\*L/var/dfs/adm\*O; absolute pathnames are also allowed. In cases where a / (slash) appears in the specified filename, the issuer's username must appear in the \*Ladmin.bos\*O file on the machine specified by the \*L\-server\*O option. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If the filename specified by \*L\-file\*O contains a / (slash), the command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lbos getlog\*O command displays the contents of the log file specified by \*L\-file\*O that resides on the machine specified by \*L\-server\*O. It can be used to view any of the following log files: .VL .LI "\*LBakLog\*O" Generated by the Backup Server process on each Backup Database machine .LI "\*LBosLog\*O" Generated by the BOS Server process on each server machine .zA "defect,11180,R1.1,Incorporate DFS/NFS gateway doc" .LI "\*LDfsgwLog\*O" Generated by the Gateway Server process on each Gateway Server machine .zZ "defect,11180,R1.1,Incorporate DFS/NFS gateway doc" .LI "\*LFlLog\*O" Generated by the Fileset Location Server process on each Fileset Database machine .LI "\*LFtLog\*O" Generated by the Fileset Server process on each File Server machine .LI "\*LRepLog\*O" Generated by the Replication Server process on each server machine .LI "\*LUpLog\*O" Generated by the \*Lupserver\*O process on each server machine running the server portion of the Update Server .LE .PP .zA "defect,7073,R1.0.2,Mention viewing of .old files" By default, the command looks in the \*L\*Edcelocal\*L/var/dfs/adm\*O directory for the log file it is to display. It is not necessary to specify the full pathname of a log file if it resides in the default directory. However, if the file resides elsewhere, the full pathname of the log file must be provided. (The command can also be used to view the \*L.old\*O version of a log file created by the associated server process.) .zZ "defect,7073,R1.0.2,Mention viewing of .old files" .SS "Privilege Required" .PP No privilege is required if the filename specified by \*L\-file\*O does not contain a / (slash). If the name contains a / (slash), the issuer must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .SH "EXAMPLES" .PP The following example displays the contents of the \*LBosLog\*O file located in the default directory (\*L\*Edcelocal\*L/var/dfs/adm\*O) on the server machine named \*Lfs1\*O: .iS \*C$\*O \*Lbos getl /.../abc.com/hosts/fs1 BosLog\*O .iE .SH "RELATED INFORMATION" .PP Files: \*LBakLog(4)\*O, \*LBosLog(4)\*O, .zA "defect,11180,R1.1,Incorporate DFS/NFS gateway doc" \*LDfsgwLog(4)\*O, .zZ "defect,11180,R1.1,Incorporate DFS/NFS gateway doc" \*LFlLog(4)\*O, \*LFtLog(4)\*O, \*LRepLog(4)\*O, \*LUpLog(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Lgetlog\*O" .iX "-]" "log files" "examining (DFS)" .iX "-]" "DFS servers" "examining log files" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos getrestart" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lgetrestart\*O" .iX "-[" "DFS servers" "viewing restart times" .SH NAME .PP \*Lbos getrestart\*O \- Lists automatic restart times for server processes .SH "SYNOPSIS" .sS \*Lbos getrestart -server \*Vmachine\*O [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine on which to check the restart times. The BOS Server on this machine executes the command. Specify the machine's DCE pathname, its host name, or its IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lbos getrestart\*O command displays the following two restart times from the \*LBosConfig\*O file on the server machine specified by the \*L\-server\*O option: .zA "defect,7219,R1.0.2,Review comments" .ML .LI The general restart time, which is the time each week when the BOS Server process automatically restarts itself and all processes that have the status flag \*LRun\*O in the \*LBosConfig\*O file .LI The new binary restart time, which is the time each day when the BOS Server automatically restarts any process executed from a binary file in the \*Edcelocal\*L/bin\*O directory whose time stamp is later than the last restart time for the process .LE .P Either of these times can be daily (consist only of a time) or weekly (consist of a day and time). By default, the general restart time is once a week, while the new binary restart time occurs once a day. Both restart times are set with the \*Lbos setrestart\*O command. .zZ "defect,7219,R1.0.2,Review comments" .zA "defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Include privilege required" .SH "OUTPUT" .PP The output consists of the following two lines: .oS \*CServer \*Vmachine\*C restarts at \*Vtime\*O .nL \*CServer \*Vmachine\*C restarts for new binaries at \*Vtime\*O .oE .PP where \*Vmachine\*O indicates the name of the server machine whose restart times are displayed, and possible values for \*Vtime\*O include .VL .LI "\*Lnever\*O" Indicates that the BOS Server never performs that type of restart .LI "A specified day and time" Indicates that the BOS Server performs that type of restart once per week .LI "A specified time" Indicates that the BOS Server performs that type of restart once per day .LE .SH "EXAMPLES" .PP The following command displays the restart times for the server machine \*Lfs2\*O: .iS \*C$\*O \*Lbos getr /.../abc.com/hosts/fs2\*O .iE .oS \*CServer fs2 restarts at sun 4:00 am\*O .nL \*CServer fs2 restarts for new binaries at 2:15 am\*O .oE .SH "RELATED INFORMATION" .PP Commands: \*Lbos setrestart(1m)\*O .PP Files: \*LBosConfig(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Lgetrestart\*O" .iX "-]" "DFS servers" "viewing restart times" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the .\" src directory for the full copyright text. ...\" ...\"Copyright (C) 1989, 1991, Transarc Corporation ...\"The Gulf Tower ...\"707 Grant Street ...\"Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "bos help" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" CHANGED ...\" 12-10-91: In EXAMPLES, changed "--- server" to "-server". ...\" END CHANGED ...\"DOCUMENTSTYLE [12pt]{book} .iX "\*Lbos\*O command suite" "\*Lhelp\*O" .zA "def,5790,R1.0.2,Move bos lscell back to Admin Ref" .SH NAME .PP \*Lbos help\*O \- Shows syntax of specified \*Lbos\*O commands or lists functional descriptions of all \*Lbos\*O commands .SH "SYNOPSIS" .PP .sS \*Lbos help\*O \*O[\*L-topic \*Vstring\*O...] [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-topic \*Vstring\*O" Specifies each command whose syntax is to be displayed. Provide only the second part of the command name (for example, \*Lstatus\*O, not \*Lbos status\*O). If this option is omitted, the output provides a short description of all \*Lbos\*O commands. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lbos help\*O command displays the first line (name and short description) of the online help entry for every \*Lbos\*O command if \*L-topic\*O is not provided. For each command name specified with \*L\-topic\*O, the output lists the entire help entry. .PP Use the \*Lbos apropos\*O command to show each help entry containing a specified string. .zA "Defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "Defect,5933,R1.0.2,Include privilege required" .SH "OUTPUT" .PP The online help entry for each \*Lbos\*O command consists of the following two lines: .ML .LI The first line names the command and briefly describes its function. .LI The second line, which begins with \*CUsage:\*O, lists the command options in the prescribed order. .LE .SH "EXAMPLES" .PP The following command displays the online help entry for the \*Lbos status\*O command: .iS \*C$\*L bos help status\*O .iE .oS bos status: show server process status Usage: bos status -server [-process ...] [-long] [{-noauth | -localauth}] [-help] .oE .SH "RELATED INFORMATION" .PP Commands: \*Lbos apropos(1m)\*O .zZ "def,5790,R1.0.2,Move bos lscell back to Admin Ref" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos install" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Linstall\*O" .iX "-[" "binary files" "installing" .iX "-[" "installation" "DFS binary files" .SH NAME .PP \*Lbos install\*O \- Installs new versions of binary files .SH "SYNOPSIS" .sS \*Lbos install -server \*Vmachine\*L -file \*Vbinary_file\*O... [\*L\-dir \*Valternate_dest\*O] .nL [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine on which the new binary files are to be installed. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-file \*Vbinary_file\*O" .zA "defect,6021,R1.0.2,Fix -file and -dir options" Specifies the pathname of each binary file to be installed on the machine specified by the \*L\-server\*O option. For each file, specify either the full pathname or a relative pathname (one that does not begin with a slash); relative pathnames are interpreted relative to the current working directory. The name of each file remains the same when it is installed on the specified machine; the command automatically preserves an existing file of the same name as a file that is installed. .zZ "defect,6021,R1.0.2,Fix -file and -dir options" .LI " \*L\-dir \*Valternate_dest\*O" .zA "defect,6021,R1.0.2,Fix -file and -dir options" Provides the pathname of the directory on the machine specified by the \*L\-server\*O option in which all specified files are to be installed. Omit this option to install the files in the default directory, \*Edcelocal\*L/bin\*O; otherwise, provide a full or relative pathname. Relative pathnames are interpreted relative to the \*Edcelocal\*O directory on the machine specified by \*L\-server\*O. .zZ "defect,6021,R1.0.2,Fix -file and -dir options" .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,6021,R1.0.2,Fix -file and -dir options" .zA "defect,4782,R1.0.2,Update Server clarified for install/uninstall" The \*Lbos install\*O command installs each binary file specified with the \*L\-file\*O option on the server machine specified with the \*L\-server\*O option. The \*L\-file\*O option provides the pathname of each file to be installed on the specified machine. By default, the command installs the files in the \*Edcelocal\*L/bin\*O directory on the specified machine; use the \*L\-dir\*O option to indicate a different installation directory on the specified machine. .PP The command does not change the names of files when it installs them. To preserve the current version of a binary file that has the same name as a file being installed, the command adds a \*L.BAK\*O extension to the name of the existing file. If there is a \*L.BAK\*O version at least 7 days old, the command adds a \*L.OLD\*O extension to its name and it replaces the current \*L.OLD\*O version (if one exists). If there is a \*L.BAK\*O version less than 7 days old, it is overwritten when the current version receives a \*L.BAK\*O extension. If there is no \*L.OLD\*O version, the current \*L.BAK\*O version becomes the \*L.OLD\*O version automatically, regardless of its age. .PP The command is typically used to install new versions of binary files on Binary Distribution machines. The machine specified with the \*L\-server\*O option should be the Binary Distribution machine for its CPU/operating system type. If it is not, newly installed binary files are overwritten the next time the \*Lupclient\*O process on the specified machine copies new (or different) versions of binary files via the \*Lupserver\*O process on the Binary Distribution machine of its CPU/OS type. (Note that the Update Server propagates binary files from Binary Distribution machines, but the BOS Server installs files when the \*Lbos install\*O command is issued; by default, it takes the Update Server 5 minutes to propagate binary files from a Binary Distribution machine.) .zZ "defect,4782,R1.0.2,Update Server clarified for install/uninstall" .PP To make the machine specified by \*L\-server\*O immediately start using new binary files for server processes controlled by the BOS Server, issue the \*Lbos restart\*O command. Otherwise, new binaries are not used until the BOS Server restarts the affected processes at the new binary restart time specified in the \*Edcelocal\*L/var/dfs/BosConfig\*O file. Use the \*Lbos getrestart\*O and \*Lbos setrestart\*O commands to inspect and set the new binary restart time. (The information in this paragraph applies \*Eonly\*O to affected processes already under the control of the BOS Server.) .zZ "defect,6021,R1.0.2,Fix -file and -dir options" .PP .zA "defect,5783,R1.0.2,Provide bos install details" The \*Lbos install\*O command installs all files with the UNIX mode bits set to \*L755\*O (\*Lrwxr\-xr\-x\*O), regardless of the mode bits associated with a version of the file that currently exists in the destination directory. These permissions are subject to the \*Lumask\*O associated with the BOS Server on the machine on which the files are installed (because the BOS Server on the specified machine actually executes the command). The mode bits associated with the current version of the file are preserved when it becomes the \*L.BAK\*O version, as are those of the \*L.BAK\*O version when it becomes the \*L.OLD\*O version. (The command does not preserve the access control list, or ACL, permissions of a file installed from a DCE LFS fileset, nor does it directly manipulate the ACL permissions of a file installed into a DCE LFS fileset.) .zZ "defect,5783,R1.0.2,Provide bos install details" .PP .zA "defect,5782,R1.0.2,Include bos uninstall -all option and clarify" Use the \*Lbos uninstall\*O command to replace the current version of a binary file with the next-oldest version of the file: the \*L.BAK\*O version, if it exists; otherwise, the \*L.OLD\*O version. If both the \*L.BAK\*O and \*L.OLD\*O versions exist, the \*L.OLD\*O version replaces the \*L.BAK\*O version when the latter becomes the current version. Use the \*L\-all\*O option with the \*Lbos uninstall\*O command to remove all versions of a file; use the \*Lbos prune\*O command to remove \*L.BAK\*O and \*L.OLD\*O files from the \*Edcelocal\*L/bin\*O directory (the command can also be used to remove core files from the \*Edcelocal\*L/var/dfs/adm\*O directory). Use the \*Lbos getdates\*O command to check the time stamps on binary files. .zZ "defect,5782,R1.0.2,Include bos uninstall -all option and clarify" .SS "Privilege Required" .PP You must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .SH "RELATED INFORMATION" .PP Commands: \*Lbos create(1m)\*O, \*Lbos getdates(1m)\*O, \*Lbos getrestart(1m)\*O, \*Lbos prune(1m)\*O, \*Lbos restart(1m)\*O, \*Lbos setrestart(1m)\*O, \*Lbos uninstall(1m)\*O, .zA "defect,4782,R1.0.2,Update Server clarified for install/uninstall" \*Lupclient(1m)\*O, \*Lupserver(1m)\*O .zZ "defect,4782,R1.0.2,Update Server clarified for install/uninstall" .PP Files: \*LBosConfig(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Linstall\*O" .iX "-]" "binary files" "installing" .iX "-]" "installation" "DFS binary files" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the .\" src directory for the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\"Copyright (C) 1989, 1991, Transarc Corporation ...\"The Gulf Tower ...\"707 Grant Street ...\"Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "bos lsadmin" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Llsadmin\*O" .iX "-[" "administrative lists" "viewing members" .SH NAME .PP \*Lbos lsadmin\*O \- Lists the users, groups, and servers from an administrative list .SH "SYNOPSIS" .sS \*Lbos lsadmin -server \*Vmachine\*L -adminlist \*Vfilename\*O [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine that houses the administrative list whose principals and groups are to be displayed. The BOS Server on this machine executes the command. Specify the machine's DCE pathname, its host name, or its IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-adminlist \*Vfilename\*O" Names the administrative list whose principals and groups are to be displayed. The complete pathname is unnecessary if the list is stored in the default configuration directory (\*Edcelocal\*O\*L/var/dfs\*O). .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,6542,R1.0.2,Improve principal/group option descriptions" The \*Lbos lsadmin\*O command lists the principal names of users and server machines and the names of groups found in the administrative list specified by the \*L\-adminlist\*O option on the server machine specified by the \*L\-server\*O option. Principals whose names are specified in the administrative list or that are members of groups specified in the list can issue administrative commands for the DFS server process associated with the list. .PP The default path for the administrative lists is the configuration directory (\*Edcelocal\*L/var/dfs\*O). If the specified list is stored in the default directory, only the specific filename is required. If the specified list is stored elsewhere, the pathname to the file that was used when the associated server process was started is required. .PP Use the \*Lbos addadmin\*O command to add principals and groups to an administrative list. Use the \*Lbos rmadmin\*O command to remove principals and groups from an administrative list. .zZ "defect,6542,R1.0.2,Improve principal/group option descriptions" .zA "Defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "Defect,5933,R1.0.2,Include privilege required" .zA "enh,R1.0.2,Clarify and add output and example" .SH "OUTPUT" .PP The command displays the output .oS Admin Users are: .oE followed by the principal name of each user and machine and the name of each group contained in the administrative list. Names from the local cell are displayed in an abbreviated form (for example, \*Eusername\*O for \*L/.../\*Ecellname\*L/\*Eusername\*O); names from foreign cells are displayed in full. Each name is preceded by one of the following strings: .VL .LI "\*Cuser:\*O" Precedes the principal name of each user or machine from the local cell .LI "\*Cforeign_user:\*O" Precedes the principal name of each user or machine from a foreign cell .LI "\*Cgroup:\*O" Precedes the name of each group from the local cell .LI "\*Cforeign_group:\*O" Precedes the name of each group from a foreign cell .LE .SH "EXAMPLES" .PP The following command lists the members of the \*Ladmin.bos\*O file on the server machine named \*Lfs1\*O. The administrative list contains two users, a server machine, and two groups, all of which are from the local cell. .iS \*C$\*O \*Lbos lsa -server /.../abc.com/hosts/fs1 -adminlist admin.bos .iE .oS Admin Users are: user: jones, user: smith, user: hosts/fs1/self, group: dfs-admin, group: fs1-admin .oE .zZ "enh,R1.0.2,Clarify and add output and example" .SH "RELATED INFORMATION" .PP Commands: \*Lbos addadmin(1m)\*O, \*Lbos rmadmin(1m)\*O .PP Files: \*Ladmin.bak(4)\*O, \*Ladmin.bos(4)\*O, \*Ladmin.fl(4)\*O, \*Ladmin.ft(4)\*O, \*Ladmin.up(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Llsadmin\*O" .iX "-]" "administrative lists" "viewing members" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright (C) 1989, 1991, Transarc Corporation ...\" The Gulf Tower ...\" 707 Grant Street ...\" Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "bos lscell" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Llscell\*O" .zA "defect,5790,R1.0.2,Move bos lscell back to Admin Ref" .SH NAME .PP \*Lbos lscell\*O \- Lists the cell in which the BOS Server is running .SH "SYNOPSIS" .PP .sS \*Lbos lscell -server \*Vmachine\*O [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O]\*O .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine on which the BOS Server whose cell is to be listed is running. Specify the machine's DCE pathname, its host name, or its IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lbos lscell\*O command reports the name of the cell in which the BOS Server on the machine specified with the \*L\-server\*O option is running. The command extracts the information from the local configuration file, \*Vdcelocal\*L/dce_cf.db\*O, on the specified machine. If the command fails after being issued from the machine specified by \*L\-server\*O (if \*L\-server\*O is the local machine), the failure may indicate that the local \*Ldce_cf.db\*O file is corrupted; use the \*Lcat\*O or \*Lmore\*O command (or a similar command appropriate to your operating system) to display the contents of the file, and ensure that it is not corrupted. .zA "Defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "Defect,5933,R1.0.2,Include privilege required" .SH "OUTPUT" .PP The \*Lbos lscell\*O command displays the following line reporting the name of the cell in which the BOS Server is running: .oS Cell name is \*Vcellname\*O .oE .SH "EXAMPLES" .PP The following command displays the name of the cell in which the BOS Server on the machine named \*Lfs1\*O is running: .iS \*C$\*L bos lscell /.../abc.com/hosts/fs1\*O .iE .oS \*CCell name is abc.com\*O .oE .zZ "defect,5790,R1.0.2,Move bos lscell back to Admin Ref" .iX "-]" "\*Lbos\*O command suite" "\*Llscell\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos lskeys" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Llskeys\*O" .iX "-[" "passwords" "viewing information" .SH NAME .PP \*Lbos lskeys\*O \- Displays server encryption key information from a keytab file .SH "SYNOPSIS" .sS \*Lbos lskeys -server \*Vmachine\*O [\*L\-principal \*Vname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine whose keytab file is to have keys listed. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-principal \*Vname\*O" Provides the principal name for which associated keys are to be listed. The default is the DFS principal name of the machine specified by \*L\-server\*O. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lbos lskeys\*O command formats and displays information about server encryption keys kept in the \*L/krb5/v5srvtab\*O keytab file on the server machine specified by \*L\-server\*O. It displays information for keys associated with the principal name indicated by \*L\-principal\*O; the DFS principal name of the server machine specified with \*L\-server\*O is used by default. .PP .zA "enh,R1.0.2,Emphasize DFS auth checking" DFS authorization checking must be disabled on the machine specified with \*L\-server\*O to display the string of octal numbers that compose the key (use the \*Lbos setauth\*O command to disable DFS authorization checking). Disabling DFS authorization checking is required for two reasons. First, it implies that only someone authorized to issue the \*Lbos setauth\*O command or someone with \*Lroot\*O access to \*L\-server\*O's local disk (presumably a system administrator) is able to see actual encryption keys. Second, it makes it clear that the system is in a compromised state of security while server encryption keys are being examined (both turning off DFS authorization checking and displaying keys on a screen are serious security risks). .PP If DFS authorization checking is enabled on \*L\-server\*O (the normal case), a \*Lchecksum\*O appears in place of the octal numbers. A checksum is a decimal number derived by encrypting a constant with each key. .SS "Privilege Required" .PP .zA "enh,R1.0.2,Clarify required privilege" If DFS authorization checking is enabled, you must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O; checksums are displayed instead of the actual keys. Because DFS authorization checking must be disabled with the \*Lbos setauth\*O command before the actual keys (rather than just checksums) can be displayed, no privilege is required to see the keys. However, you must be listed in the \*Ladmin.bos\*O file on a machine to use the \*Lbos setauth\*O command to disable DFS authorization checking on it. .zZ "enh,R1.0.2,Clarify required privilege" .SH "OUTPUT" .PP The \*Lbos lskeys\*O command displays one line for each server encryption key associated with \*L\-principal\*O in the keytab file on the machine specified by \*L\-server\*O. Each key is identified by its key version number. If DFS authorization checking is enabled on the machine, a checksum is displayed with each version number; if checking is disabled, the octal numbers that comprise the key are displayed. .zZ "enh,R1.0.2,Emphasize DFS auth checking" .PP A line specifying when the key in the Registry Database (at the Registry Server) was last changed follows the list of keys or checksums. The words \*LAll done\*O indicate the end of the output. .PP .zA "defect,7219,R1.0.2,Review comments" If the packet privacy protection level is not available to you, the command displays the following message reporting that the BOS Server is using the packet integrity protection level instead: .oS \*CData encryption unsupported by RPC. Continuing without it.\*O .oE .zZ "defect,7219,R1.0.2,Review comments" .SH "EXAMPLES" .PP The following command shows the checksums for the keys associated with the principal name of \*Lfs3\*O in the keytab file on that machine. The checksums appear instead of the actual keys because DFS authorization checking is \*Enot\*O disabled. .iS \*C$\*O \*Lbos lsk /.../abc.com/hosts/fs3\*O .iE .oS \*Ckey 1 has cksum 972037177\*O .nL \*Ckey 3 has cksum 282517022\*O .nL \*Ckey 4 has cksum 260617746\*O .nL \*CKeys last changed (at the registry server) on Thu Jun 6 11:24:46 1991.\*O .nL \*CAll done.\*O .oE .PP The following command lists the keys associated with \*Lfs3\*O after DFS authorization checking is disabled with the \*Lbos setauth\*O command: .iS \*C$\*O \*Lbos setauth /.../abc.com/hosts/fs3 off\*O .iE .iS \*C$\*O \*Lbos lsk /.../abc.com/hosts/fs3\*O .iE .oS \*Ckey 1 is `\*C\e\*C040\*C\e\*C205\*C\e\*C211\*C\e\*C241\*C\e\*C345\*C\e\*C002\*C\e\*C023\*C\e\*C211'\*O .nL \*Ckey 2 is `\*C\e\*C343\*C\e\*C315\*C\e\*C307\*C\e\*C227\*C\e\*C255\*C\e\*C320\*C\e\*C135\*C\e\*C244'\*O .nL \*Ckey 3 is `\*C\e\*C310\*C\e\*C310\*C\e\*C255\*C\e\*C253\*C\e\*C265\*C\e\*C236\*C\e\*C261\*C\e\*C211'\*O .nL \*CKeys last changed (at the registry server) on Thu Jun 6 11:24:46 1991.\*O .nL \*CAll done.\*O .oE .SH "RELATED INFORMATION" .PP .zZ "enh,R1.0.2,Reference security ref pages from some bos pages" Commands: \*Lbos addkey(1m)\*O, \*Lbos gckeys(1m)\*O, \*Lbos genkey(1m)\*O, \*Lbos rmkey(1m)\*O, \*Lbos setauth(1m)\*O, .zA "defect,12535,R1.1,Incorporate dcecp commands" \*Lkeytab(1m)\*O .zZ "defect,12535,R1.1,Incorporate dcecp commands" .PP Files: \*Lv5srvtab(5)\*O .zZ "enh,R1.0.2,Reference security ref pages from some bos pages" .iX "-]" "\*Lbos\*O command suite" "\*Llskeys\*O" .iX "-]" "passwords" "viewing information" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos prune" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lprune\*O" .iX "-[" "binary files" "deleting" .iX "-[" "core files" "deleting" .SH NAME .PP \*Lbos prune\*O \- Removes old binary and core files from \*L\*Edcelocal\*L/bin\*O and \*L\*Edcelocal\*L/var/dfs/adm\*O .SH "SYNOPSIS" .sS \*Lbos prune -server \*Vmachine\*O [\*L\-bak\*O] [\*L\-old\*O] [\*L\-core\*O] [\*L\-all\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help]\*O .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine from which to remove the indicated files. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-bak\*O" Removes all files with a \*L.BAK\*O extension from \*Edcelocal\*O\*L/bin\*O. Use this option with \*L\-old\*O, \*L\-core\*O, or both, or use \*L\-all\*O. .LI "\*L\-old\*O" Removes all files with an .\*LOLD \*Oextension from \*Edcelocal\*O\*L/bin\*O. Use this option with \*L\-bak\*O, \*L\-core\*O, or both, or use \*L\-all\*O. .LI "\*L\-core\*O" Removes all core files from \*Edcelocal\*O\*L/var/dfs/adm\*O. Use this option with \*L\-bak\*O, \*L\-old\*O, or both, or use \*L\-all\*O. .LI "\*L\-all\*O" Removes all \*L.BAK\*O and \*L.OLD\*O files from \*L\*Edcelocal\*L/bin\*O and all core files from \*L\*Edcelocal\*L/var/dfs/adm\*O. Use this option or use some combination of \*L\-bak\*O, \*L\-old\*O, and \*L\-core\*O. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lbos prune\*O command removes obsolete versions of binary and core files from the \*L\*Edcelocal\*L/bin\*O and \*L\*Edcelocal\*L/var/dfs/adm\*O directories on the server machine specified with the \*L\-server\*O option. Binary files should only need to be removed from the Binary Distribution machine for a CPU/operating system type; core files may need to be removed from any server machine. Specify the files to be removed with the command's other options as follows: .ML .LI Use the \*L\-bak\*O option to remove all \*L.BAK\*O files from \*Edcelocal\*O\*L/bin\*O. .LI Use the \*L\-old\*O option to remove all \*L.OLD\*O files from \*Edcelocal\*O\*L/bin\*O. .LI Use the \*L\-core\*O option to remove all core files from \*Edcelocal\*O\*L/var/dfs/adm\*O. .LI Use the \*L\-all\*O option to remove all three types of files. .LE .PP The \*L\-bak\*O, \*L\-old\*O, and \*L\-core\*O options can be combined to remove different types of files with the same command. The \*L\-all\*O option can also be used with any of the three options, but using the \*L\-all\*O option alone is sufficient to remove all three types of files. .PP Binary files with \*L.BAK\*O and \*L.OLD\*O extensions are created when new versions of binary files are installed with the \*Lbos install\*O command. Core files are created when a process that the BOS Server is monitoring goes down. .PP .zA "defect,5782,R1.0.2,Include bos uninstall -all option and clarify" Use the \*Lbos uninstall\*O command to replace the current version of a binary file with its next-oldest version (\*L.BAK\*O or, if the \*L.BAK\*O version does not exist, \*L.OLD\*O) or to remove all versions of a binary file. Use the \*Lbos getdates\*O command to determine the time stamps on binary files. .zZ "defect,5782,R1.0.2,Include bos uninstall -all option and clarify" .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .SH "RELATED INFORMATION" .PP Commands: \*Lbos getdates(1m)\*O, \*Lbos install(1m)\*O, \*Lbos uninstall(1m)\*O .iX "-]" "\*Lbos\*O command suite" "\*Lprune\*O" .iX "-]" "binary files" "deleting" .iX "-]" "core files" "deleting" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" CHANGED ...\" 12-09-91: Removed the italics from the word "or" in the last sentences ...\" of the descriptions of the -bosserver and -process options. ...\" END CHANGED ...\" .rm zA .rm zZ .TH "bos restart" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lrestart\*O" .iX "-[" "server machines" "restarting processes" .iX "-[" "DFS servers" "restarting" .SH NAME .PP \*Lbos restart\*O \- Restarts processes on a server machine .SH "SYNOPSIS" .sS .PP \*Lbos restart -server \*Vmachine\*O [{\*L\-bosserver\*O | \*L\-process \*Vserver_process\*O...}] .nL \*L[{-noauth | -localauth}] [-help]\*O .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine on which to stop and restart indicated processes. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-bosserver\*O" .zA "defect,6721,R1.0.2,Correct bos restart doc" Indicates that all processes, including the current BOS Server, are to stop running. A new BOS Server immediately starts; it then restarts all processes with the status flag \*LRun\*O in the \*Edcelocal\*L/var/dfs/BosConfig\*O file. .PP Provide this option or provide the \*L\-process\*O option. Omit both options to stop all processes except the BOS Server; those with the status flag \*LRun\*O in the \*LBosConfig\*O file are immediately restarted. .LI "\*L\-process \*Vserver_process\*O" Specifies each process to be stopped and immediately restarted. The BOS Server stops all specified processes that are currently running; it then restarts all of the specified processes, regardless of their status flags in the \*LBosConfig\*O file. Refer to a process by the name assigned with the \*L\-process\*O option of the \*Lbos create\*O command (this name appears in the output from the \*Lbos status\*O command). \*EDo not include \*Lbosserver\*E in the list of processes\*O; use the \*L\-bosserver\*O option instead. .PP Provide this option or provide the \*L\-bosserver\*O option. Omit both options to stop all processes except the BOS Server; those with the status flag \*LRun\*O in the \*LBosConfig\*O file are immediately restarted. .zZ "defect,6721,R1.0.2,Correct bos restart doc" .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,6721,R1.0.2,Correct bos restart doc" The \*Lbos restart\*O command instructs the BOS Server running on the server machine specified by \*L\-server\*O to stop all indicated processes on the machine. The BOS Server then immediately restarts some or all of the processes, depending on the options included with the command. The processes to be stopped and possibly restarted are specified with the following options: .ML .LI The \*L\-bosserver\*O option causes the BOS Server to stop all processes, including itself. A new BOS Server immediately starts; it then restarts all processes with the status flag \*LRun\*O in the \*LBosConfig\*O file. .LI The \*L\-process\*O option causes the BOS Server to stop and immediately restart all specified processes, regardless of their status flags in the \*LBosConfig\*O file. All restarted processes with the status flag \*LNotRun\*O in the \*LBosConfig\*O file have the status \*Ctemporarily enabled\*O in the output of the \*Lbos status\*O command. .LI The absence of both the \*L\-bosserver\*O and \*L\-process\*O options causes the BOS Server to stop all processes except itself. The BOS Server then immediately restarts all processes with the status flag \*LRun\*O in the \*LBosConfig\*O file. .LE .zZ "defect,6721,R1.0.2,Correct bos restart doc" .PP This command can be used to stop only those processes the BOS Server controls. Also, it does \*Enot\*O change the status flag for a process in the \*LBosConfig\*O file. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .SH "EXAMPLES" .PP The following command instructs the BOS Server on \*L/.../abc.com/hosts/fs3\*O to stop all processes, including itself. A new BOS Server immediately starts, after which it restarts all processes with the status flag \*LRun\*O in the \*LBosConfig\*O file. .iS \*C$\*O \*Lbos restart /.../abc.com/hosts/fs3 -bos\*O .iE .PP The following command instructs the BOS Server on \*L/.../abc.com/hosts/fs5\*O to stop all processes except itself. The BOS Server then restarts all processes with the status flag \*LRun\*O in the \*LBosConfig\*O file. .iS \*C$\*O \*Lbos res /.../abc.com/hosts/fs5\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lbos create(1m)\*O, \*Lbos status(1m)\*O .PP Files: \*LBosConfig(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Lrestart\*O" .iX "-]" "server machines" "restarting processes" .iX "-]" "DFS servers" "restarting" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos rmadmin" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lbos\*O command suite" "\*Lrmadmin\*O" .iX "-[" "administrative lists" "removing members" .iX "-[" "principals" "on administrative lists" .iX "-[" "groups" "on administrative lists" .SH NAME .PP \*Lbos rmadmin\*O \- Removes a user, group, or server from an administrative list .SH "SYNOPSIS" .sS .PP \*Lbos rmadmin -server \*Vmachine\*L -adminlist \*Vfilename\*O [\*L\-principal \*Vname\*O...] [\*L\-group \*Vname\*O...] .nL \*O[\*L-removelist\*O] [{\*L-noauth\*O | \*L-localauth\*O}] [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine that houses the administrative list from which principals, groups, or both are to be removed. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-adminlist \*Vfilename\*O" Names the administrative list from which principals, groups, or both are to be removed. The complete pathname is unnecessary if the list is stored in the default configuration directory (\*Edcelocal\*O\*L/var/dfs\*O). .LI "\*L\-principal \*Vname\*O" .zA "defect,6542,R1.0.2,Improve principal/group option descriptions" Specifies the principal name of each user or server machine to be removed from the administrative list. A user from the local cell can be specified by a full or abbreviated principal name (for example, \*L/.../\*Ecellname\*L/\*Eusername\*O or just \*Eusername\*O); a user from a foreign cell can be specified only by a full principal name. A server machine from the local cell can be specified by a full or abbreviated principal name (for example, \*L/.../\*Ecellname\*L/hosts/\*Ehostname\*L/self\*O or just \*Lhosts/\*Ehostname\*L/self\*O); a server machine from a foreign cell can be specified only by a full principal name. .zZ "defect,6542,R1.0.2,Improve principal/group option descriptions" .LI "\*L\-group \*Vname\*O" .zA "defect,6542,R1.0.2,Improve principal/group option descriptions" Specifies the name of each group to be removed from the administrative list. A group from the local cell can be specified by a full or abbreviated group name (for example, \*L/.../\*Ecellname\*L/\*Egroup_name\*O or just \*Egroup_name\*O); a group from a foreign cell can be specified only by a full group name. .zZ "defect,6542,R1.0.2,Improve principal/group option descriptions" .LI "\*L\-removelist\*O" .zA "defect,5789,R1.0.2,-removelist removes an already empty list" Specifies that the file indicated with \*L\-adminlist\*O is to be removed if it is empty either when the command is issued or after any principals or groups specified with the command are removed. This option has no effect if the specified file is not empty when the command is issued or after any indicated principals or groups are removed. .zZ "defect,5789,R1.0.2,-removelist removes an already empty list" .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,6542,R1.0.2,Improve principal/group option descriptions" The \*Lbos rmadmin\*O command removes the specified users, groups, and servers from the administrative list specified by the \*L\-adminlist\*O option on the server machine specified by the \*L\-server\*O option. The principal (login) names of users and the principal names of server machines to be removed from the administrative list are specified with the \*L\-principal\*O option; the names of groups to be removed from the list are specified with the \*L\-group\*O option. Principals removed from the administrative list either directly (with the \*L\-principal\*O option) or indirectly (as members of groups indicated with the \*L\-group\*O option) can no longer issue administrative commands for the DFS server process associated with the list. .zZ "defect,6542,R1.0.2,Improve principal/group option descriptions" .PP The default path for administrative lists is the configuration directory (\*Edcelocal\*O\*L/var/dfs\*O). If the specified list is stored in the default directory, only the specific filename is required. If the specified list is stored elsewhere, the pathname to the file that was used when the associated server process was started is required. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .SH "EXAMPLES" .PP The following command removes the former administrative users \*Lsmith\*O and \*Ljones\*O from the \*Ladmin.bos\*O file on \*Lfs1\*O: .iS \*C$\*O \*Lbos rmadmin -server /.../abc.com/hosts/fs1 -adminlist admin.bos -principal smith jones\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lbos addadmin(1m)\*O, \*Lbos lsadmin(1m)\*O .PP Files: \*Ladmin.bak(4)\*O, \*Ladmin.bos(4)\*O, \*Ladmin.fl(4)\*O, \*Ladmin.ft(4)\*O, \*Ladmin.up(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Lrmadmin\*O" .iX "-]" "administrative lists" "removing members" .iX "-]" "principals" "on administrative lists" .iX "-]" "groups" "on administrative lists" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos rmkey" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lrmkey\*O" .iX "-[" "passwords" "DFS server" .iX "-[" "DFS servers" "passwords" .SH NAME .PP \*Lbos rmkey\*O \- Removes server encryption keys from a keytab file .SH "SYNOPSIS" .sS .PP \*Lbos rmkey -server \*Vmachine\*L -kvno \*Vversion_number\*O... [\*L\-principal \*Vname\*O] .nL [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine whose keytab file is to have keys removed from it. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-kvno \*Vversion_number\*O" .zA "defect,5961,R1.0.2,Bos rmkey does not accept -kvno 0" Specifies the key version number of each key to be removed from the keytab file. The command removes each key that is associated with a specified key version number and the principal indicated by \*L\-principal\*O. Each version number must be an integer in the range 1 to 255. .zZ "defect,5961,R1.0.2,Bos rmkey does not accept -kvno 0" .LI "\*L\-principal \*Vname\*O" Provides the principal name associated with the keys to be removed from the keytab file. The default is the DFS principal name of the machine specified by \*L\-server\*O. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,7219,R1.0.2,Review comments" The \*Lbos rmkey\*O command removes server encryption keys from the \*L/krb5/v5srvtab\*O keytab file on the server machine specified by \*L\-server\*O. It removes each key associated with a key version number indicated by \*L\-kvno\*O and the principal indicated by \*L\-principal\*O. The command has no effect on the Registry Database. Once a key is removed from the keytab file, it can no longer be used to establish communication between clients and the server to which it applied. .zZ "defect,7219,R1.0.2,Review comments" .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .zA "defect,7219,R1.0.2,Review comments" .SH "OUTPUT" .PP If the packet privacy protection level is not available to you, the command displays the following message reporting that the BOS Server is using the packet integrity protection level instead: .oS \*CData encryption unsupported by RPC. Continuing without it.\*O .oE .zZ "defect,7219,R1.0.2,Review comments" .SH "EXAMPLES" .PP The following command removes two keys from the keytab file on \*Lfs1\*O: the keys with key version numbers \*L5\*O and \*L6\*O that are associated with the DFS principal name of \*Lfs1\*O. .iS \*C$\*O \*Lbos rmk /.../abc.com/hosts/fs1 -kvno 5 6\*O .iE .SH "RELATED INFORMATION" .PP .zA "enh,R1.0.2,Reference security ref pages from some bos pages" Commands: \*Lbos addkey(1m)\*O, \*Lbos gckeys(1m)\*O, \*Lbos genkey(1m)\*O, \*Lbos lskeys(1m)\*O, .zA "defect,12535,R1.1,Incorporate dcecp commands" \*Lkeytab(1m)\*O .zZ "defect,12535,R1.1,Incorporate dcecp commands" .PP Files: \*Lv5srvtab(5)\*O .zZ "enh,R1.0.2,Reference security ref pages from some bos pages" .iX "-]" "\*Lbos\*O command suite" "\*Lrmkey\*O" .iX "-]" "passwords" "DFS server" .iX "-]" "DFS servers" "passwords" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" CHANGED ...\" 12-09-91: In DESCRIPTION, completely parenthesized the parenthetical ...\" text in the third paragraph. ...\" 12-09-91: Added bosserver(1m) to RELATED INFORMATION. ...\" END CHANGED ...\" .rm zA .rm zZ .TH "bos setauth" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lsetauth\*O" .iX "-[" "authorization checking" "controlling" .SH NAME .PP \*Lbos setauth\*O \- Enables or disables DFS authorization checking for all DFS server processes on a machine .SH "SYNOPSIS" .sS .PP \*Lbos setauth -server \*Vmachine\*L -authchecking\*O {\*Lon\*O | \*Loff}\*O [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine on which the status of DFS authorization checking is to change. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-authchecking\*O" Determines whether or not server processes on the machine check for DFS authorization. A value of \*Lon\*O enables DFS authorization checking; a value of \*Loff\*O disables it. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O (the option can be used only when enabling authorization checking). If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" The \*Lbos setauth\*O command enables or disables DFS authorization checking on the server machine specified by the \*L\-server\*O option. If DFS authorization checking is enabled on a server machine, all DFS server processes running on the machine check that the issuer of a command is correctly authorized (is included in the necessary administrative lists) to execute the command. If DFS authorization checking is disabled on a server machine, the DFS server processes on the machine perform any action for any user, even the unprivileged user \*Lnobody\*O. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .PP By default, DFS authorization checking is enabled on every server machine. Disabling it on a server machine is a serious security risk. It is typically disabled for the briefest possible time and only in the following situations: .ML .LI During initial DFS installation .LI If the Security Service is unavailable .LI During server encryption key emergencies .LI To view the actual keys stored in a keytab file .LE .PP To indicate to all DFS server processes (including itself) that DFS authorization checking is disabled on a server machine, the BOS Server creates the zero-length file \*Edcelocal\*L/var/dfs/NoAuth\*O on the local disk of the machine. All DFS server processes, including the BOS Server, check for the presence of this file when they are requested to perform an operation; they do not check for the necessary administrative privilege for a requested operation when the file is present. To indicate that DFS authorization checking is enabled, the BOS Server removes the file. .zZ "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" .PP Enter this command with the \*L\-authchecking\*O option and an argument of \*Loff\*O to disable DFS authorization checking on a server machine. (DFS authorization checking can also be disabled by including the \*L\-noauth\*O option with the \*Lbosserver\*O command used to start the BOS Server.) Issue the command with the \*L\-authchecking\*O option and an argument of \*Lon\*O to enable DFS authorization checking on a server machine. It is not necessary to restart currently running server processes when you change the state of DFS authorization checking; server processes immediately obey the current state of DFS authorization checking and act accordingly. .PP .zA "defect,5791,R1.0.2,Bos status displays NoAuth message" The \*Lbos status\*O command can be used to determine whether DFS authorization checking is enabled or disabled on a server machine. The command displays the following message if DFS authorization checking is disabled on a machine (it does not display the message if DFS authorization checking is enabled): .oS \*CBosserver reports machine is not checking authorization.\*O .oE .zZ "defect,5791,R1.0.2,Bos status displays NoAuth message" .PP .zA "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" The \*L\-noauth\*O option available with many \*Lbos\*O and \*Lfts\*O commands is used when authentication information is unnecessary or unavailable. Use the \*L\-noauth\*O option if DFS authorization checking is disabled on a server machine on which administrative privilege is required or if the Security Service is unavailable. .zZ "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" .SS "Privilege Required" .PP .zA "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" The issuer must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O to disable DFS authorization checking on that machine. (No privilege is required to enable DFS authorization checking if it is currently disabled.) .zZ "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" .SH "CAUTIONS" .PP Always use the \*Lbos setauth\*O command to create the \*Edcelocal\*L/var/dfs/NoAuth\*O file. Do not create the file directly except when explicitly told to do so by instructions for dealing with emergencies (such as emergencies involving server encryption keys). Creating the file directly requires logging into the local operating system of a machine as \*Lroot\*O and using the \*Ltouch\*O command (or its equivalent). .SH "EXAMPLES" .PP The following command disables DFS authorization checking for all DFS server processes on the server machine named \*Lfs7\*O: .iS \*C$\*O \*Lbos seta /.../abc.com/hosts/fs7 off\*O .iE .SH "RELATED INFORMATION" .PP .zA "defect,5791,R1.0.2,Bos status displays NoAuth message" Commands: \*Lbos status\*O, \*Lbosserver(1m)\*O .PP Files: \*LNoAuth(4)\*O .zZ "defect,5791,R1.0.2,Bos status displays NoAuth message" .iX "-]" "\*Lbos\*O command suite" "\*Lsetauth\*O" .iX "-]" "authorization checking" "controlling" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos setrestart" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lsetrestart\*O" .iX "-[" "DFS servers" "setting restart times" .iX "-[" "BOS Server" "setting restart times" .SH NAME .PP \*Lbos setrestart\*O \- Sets the date and time at which the BOS Server restarts all processes or only those with new binaries .SH "SYNOPSIS" .sS .PP \*Lbos setrestart -server \*Vmachine\*O {\*L\-general \*Vtime\*O | \*L\-newbinary \*Vtime\*O} .nL [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .iX "processes" "restarting date and time" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Specifies the server machine for which restart times are to be set. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-general \*Vtime\*O" Sets the time at which the BOS Server restarts first itself and then each server process that has an entry in the \*LBosConfig\*O file with a status flag of \*LRun\*O. Specify a day and time to perform the restart weekly at that time; specify a time to perform the restart daily at that time. Day and time specifications have the following format: .sS [\*Eday\*O] \*Ehh\*O:\*Emm\*O .sE Enter the name of the day in all lowercase letters, giving either the whole name or the first three letters as an abbreviation (for example, \*Lsunday\*O or \*Lsun\*O). Specify the time of day by separating the hours from the minutes with a \*L:\*O (colon). Use 24-hour time (for example, \*L14:30\*O), or use 1:00 through 12:00 with \*Lam\*O or \*Lpm\*O (for example, \*L"2:30 pm"\*O). As shown in the example, enclose the entry in \*L"\|"\*O (double quotes) if it contains a space. .PP You can use either of two additional specifications instead of a time or a day and time: .VL .75i .LI "\*Lnever\*O" Directs the BOS Server never to perform the indicated type of restart .LI "\*Lnow\*O" Directs the BOS Server to use the day and time at which the command is issued (for example, Sunday at 2:00 a.m.) as the day and time for the indicated type of restart .LE .PP If this option is never used to set the general restart time, the default general restart time is Sunday at 4:00 a.m. If you change the general restart time, the recommended frequency for this type of restart is once per week. .LI "\*L\-newbinary \*Vtime\*O" Sets the time at which the BOS Server restarts any server process whose binary file was installed in \*Vdcelocal\*L/bin\*O after the current instance of the process started running. The recommended frequency for this type of restart is once per day, so it is standard to specify only a time of day. Use the conventions described for the \*L\-general\*O option to express the time of day. The remarks for the \*L\-general\*O option concerning \*Lnever\*O and \*Lnow\*O also apply to this option. .PP If this option is never used to set the binary checking time, the default binary checking time is 5:00 a.m. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lbos setrestart\*O command sets the times at which the BOS Server running on the server machine specified by the \*L\-server\*O option is to perform one of two types of restarts. The command records the time settings in the \*LBosConfig\*O file. The two types of restart times are .ML .LI The time each week when the BOS Server restarts itself and any processes marked with the status flag \*LRun\*O in the \*LBosConfig\*O file. This is equivalent to executing \*Lbos restart\*O with the \*L\-bosserver\*O option. The default setting is 4:00 a.m. each Sunday morning. .LI The time each day when the BOS Server restarts any process currently running for which the binary file in \*Edcelocal\*O\*L/bin\*O was modified since the process was last started (or restarted). The default setting is 5:00 a.m. each day. .LE .PP To change both times, you must issue the command twice. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.bos\*O file on the machine specified by the \*L\-server\*O option. .SH "CAUTIONS" .PP Restarting processes makes them unavailable for a period of time. It is advisable to set the restarts for times of typically low usage to inconvenience as few users as possible. .PP If the specified time is within one hour of the current time, the BOS Server does not restart the processes until that time on the next day. .SH "EXAMPLES" .PP The following command defines a general restart time in the \*LBosConfig\*O file on \*Lfs4\*O that causes all processes on that machine to stop and restart each Saturday morning at 3:30 a.m.: .iS \*C$\*O \*Lbos setr -s /.../abc.com/hosts/fs4 -gen "sat 3:30"\*O .iE .PP The following command defines a new binary restart time in the \*LBosConfig\*O file on \*Lfs6\*O, instructing the BOS Server on that machine to check for new binary files each evening at 11:45 p.m. and restart any processes for which it finds a new file at that time: .iS \*C$\*O \*Lbos setr -s /.../abc.com/hosts/fs6 -new 23:45\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lbos getrestart(1m)\*O, \*Lbos restart(1m)\*O .PP Files: \*LBosConfig(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Lsetrestart\*O" .iX "-]" "DFS servers" "setting restart times" .iX "-]" "BOS Server" "setting restart times" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos shutdown" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lshutdown\*O" .iX "-[" "DFS servers" "stopping" .SH NAME .PP \*Lbos shutdown\*O \- Stops processes without changing their status flags in the \*LBosConfig\*O file .SH "SYNOPSIS" .sS .PP \*Lbos shutdown -server \*Vmachine\*O [\*L\-process \*Vserver_process\*O...] [\*L\-wait\*O] .nL [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine on which the indicated processes are to be stopped. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-process \*Vserver_process\*O" Specifies each process to be stopped. If this option is omitted, the BOS Server stops all server processes other than itself on the server machine. Refer to a process by the name assigned with the \*L\-process\*O option of the \*Lbos create\*O command; this name appears in the output of the \*Lbos status\*O command. .LI "\*L\-wait\*O" Indicates that the command shell prompt is not to return until the shutdown is complete (until all processes actually stop running). If this option is omitted, the prompt returns almost immediately, even if all of the processes are not yet stopped. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lbos shutdown\*O command instructs the BOS Server running on the server machine specified by \*L\-server\*O to stop either all processes (except itself) running on the machine \*Eor\*O only the processes specified by \*L\-process\*O. The command does not change a process's status flag in the \*LBosConfig\*O file, only in the BOS Server's memory state. .PP Processes stopped with this command do not run again until they are started using the \*Lbos start\*O, \*Lbos startup\*O, or \*Lbos restart\*O commands, or until the BOS Server itself restarts. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .SH "EXAMPLES" .PP The following command instructs the BOS Server running on \*Lfs3\*O to stop running all processes except itself: .iS \*C$\*O \*Lbos shutdown -s /.../abc.com/hosts/fs3\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lbos create(1m)\*O, \*Lbos status(1m)\*O .iX "-]" "\*Lbos\*O command suite" "\*Lshutdown\*O" .iX "-]" "DFS servers" "stopping" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos start" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lstart\*O" .iX "-[" "DFS servers" "starting" .SH NAME .PP \*Lbos start\*O \- Starts processes after setting their status flags to \*LRun\*O in the \*LBosConfig\*O file and in memory .SH "SYNOPSIS" .sS \*Lbos start -server \*Vmachine\*L -process \*Vserver_process\*O... [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine whose processes are to be started. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-process \*Vserver_process\*O" Specifies each process to be started after its status flag in the \*LBosConfig\*O file and in memory is set to \*CRun\*O. Refer to a process by the name assigned with the \*L\-process\*O option of the \*Lbos create\*O command; this name appears in the output from the \*Lbos status\*O command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lbos start\*O command changes the status flag for each server process specified by \*L\-process\*O from \*LNotRun\*O to \*LRun\*O in the \*LBosConfig\*O file and in memory on the server machine specified by \*L\-server\*O. It then starts each specified process running on that machine. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .SH "CAUTIONS" .PP If an instance of a process is already running, the only effect is to guarantee that its status flag is set to \*LRun\*O in both the \*LBosConfig\*O file and memory; it does not start a new instance of the process. Issue the \*Lbos restart\*O command after this command to start a new instance. .SH "EXAMPLES" .PP The following command causes the BOS Server on \*Lfs3\*O to start the Replication Server (\*Lrepserver\*O process) on that machine by changing its status flags to \*LRun\*O in both the \*LBosConfig\*O file and memory: .iS \*C$\*O \*Lbos start /.../abc.com/hosts/fs3 repserver\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lbos create(1m)\*O, \*Lbos restart(1m)\*O, \*Lbos startup(1m)\*O, \*Lbos status(1m)\*O .PP Files: \*LBosConfig(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Lstart\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos startup" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lstartup\*O" .SH NAME .PP \*Lbos startup\*O \- Starts processes by changing their status flags to \*LRun\*O in memory without changing their status flags in the \*LBosConfig\*O file .SH "SYNOPSIS" .sS \*Lbos startup -server \*Vmachine\*O [\*L\-process \*Vserver_process\*O...] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine whose processes are to be started. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-process \*Vserver_process\*O" Specifies each process to be started after its status flag in memory is set to \*LRun\*O. Refer to a process by the name assigned with the \*L\-process\*O option of the \*Lbos create\*O command; this name appears in the output from the \*Lbos status\*O command. .PP If this option is omitted, all server processes with a status flag of \*LRun\*O in the \*LBosConfig\*O file that are not running are started after their status flags in memory are set to \*LRun\*O. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP This command instructs the BOS Server running on the server machine specified by \*L\-server\*O to start \*Eeither\*O all server processes with a status flag of \*LRun\*O in the \*LBosConfig\*O file that are not running (if \*L\-process\*O is omitted) \*Eor\*O each process specified by \*L\-process\*O, even if its status flag in the \*LBosConfig\*O file is \*LNotRun\*O. The status flags of all started processes are changed from \*LNotRun\*O to \*LRun\*O in memory. .PP Using \*L\-process\*O is useful for testing server processes without enabling them permanently. This command does \*Enot\*O change the status flag for a process in the \*LBosConfig\*O file. .SH "CAUTIONS" .PP If an instance of a process is already running, the only effect is to guarantee that its status flag is set to \*LRun\*O in memory; it does not start a new instance of the process. Issue the \*Lbos restart\*O command after this command to start a new instance. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .SH "EXAMPLES" .PP The following command causes the BOS Server on \*Lfs3\*O to start all processes on that machine marked with a status flag of \*LRun\*O in the \*LBosConfig\*O file that are not currently running. The status flags of all such processes are set to \*LRun\*O in memory; their status flags remain set to \*LRun\*O in the \*LBosConfig\*O file. .iS \*C$\*O \*Lbos startup /.../abc.com/hosts/fs3 \*O .iE The following command causes the BOS Server on \*Lfs3\*O to start the Replication Server (\*Lrepserver\*O process) on that machine by changing its status flag to \*LRun\*O in memory. The process's status flag remains unchanged in the \*LBosConfig\*O file, regardless of its current setting (\*LRun\*O or \*LNotRun\*O). .iS \*C$\*O \*Lbos startup /.../abc.com/hosts/fs3 repserver\*O .iE .SH "RELATED INFORMATION" .PP Command: \*Lbos create(1m)\*O, \*Lbos restart(1m)\*O, \*Lbos shutdown(1m)\*O, \*Lbos start(1m)\*O, \*Lbos status(1m)\*O, \*Lbos stop(1m)\*O .PP Files: \*LBosConfig(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Lstartup\*O" .iX "-]" "DFS servers" "starting" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos status" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lstatus\*O" .iX "-[" "DFS servers" "checking status" .SH NAME .PP \*Lbos status\*O \- Displays the statuses of server processes on a server machine .SH "SYNOPSIS" .sS \*Lbos status -server \*Vmachine\*O [\*L\-process \*Vserver_process\*O...] [\*L\-long\*O] .nL [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine about whose processes status information is to be displayed. The BOS Server on this machine executes the command. Specify the the machine's DCE pathname, its host name, or its IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-process \*Vserver_process\*O" Specifies each process whose status is to be displayed; refer to a process by the name assigned with the \*L\-process\*O option of the \*Lbos create\*O command. If this option is omitted, the statuses of all of the processes on the specified server are listed. .LI "\*L\-long\*O" Directs the BOS Server to provide more detailed information about the specified processes. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,7219,R1.0.2,Review comments" .zA "defect,5791,R1.0.2,Bos status displays NoAuth message" The \*Lbos status\*O command lists status information about the processes on the server machine specified by the \*L\-server\*O option. Use the \*L\-process\*O option to indicate the specific processes about which information is to be displayed, or omit the option to display information about all the processes on the server machine. The command also displays appropriate messages if DFS authorization checking is disabled on the machine or if the machine's \*Edcelocal\*O directory or a directory or file beneath it has inappropriate protections. .zZ "defect,5791,R1.0.2,Bos status displays NoAuth message" .zZ "defect,7219,R1.0.2,Review comments" .PP .zA "defect,10439,R1.1,Fix cross-references for DFS reorganization" Use the \*L\-long\*O option to display more information about each specified process. The additional information can be used to determine the role of a server machine in a domain. (See Part 1 of the \*(Ad for instructions on using this command to determine the role of a server machine.) .zZ "defect,10439,R1.1,Fix cross-references for DFS reorganization" .zA "defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Include privilege required" .SH "OUTPUT" .PP .zA "defect,5791,R1.0.2,Bos status displays NoAuth message" The command first displays the following line if DFS authorization checking is disabled on the machine (it does not display the line if DFS authorization checking is enabled): .oS \*CBosserver reports machine is not checking authorization.\*O .oE .zZ "defect,5791,R1.0.2,Bos status displays NoAuth message" .PP .zA "defect,7219,R1.0.2,Review comments" It then displays the following line if the BOS Server finds that the \*Edcelocal\*O directory or a directory or file under it on the machine has protections that the BOS Server believes are inappropriate: .oS \*CBosserver reports inappropriate access on server directories.\*O .oE .PP The message can indicate, for example, that users who should not be able to write to the \*Edcelocal\*O directory and its subdirectories have write access. The BOS Server displays the message if the UNIX mode bits on the following objects do not enforce the indicated protections. Provided the mode bits do not violate the specific restrictions cited in the list, a directory or file can grant more permissions than those shown in the list, but it should not grant fewer. .VL 2.0i .LI "\*Edcelocal\*O" At least \*L755\*O, and \*Lother\*O cannot have write access .LI "\*Edcelocal\*L/bin\*O" At least \*L755\*O, and \*Lother\*O cannot have write access .LI "\*Edcelocal\*L/var\*O" At least \*L755\*O, and \*Lother\*O cannot have write access .LI "\*Edcelocal\*L/var/dfs\*O" At least \*L701\*O, and \*Lother\*O cannot have write access .LI "\*Edcelocal\*L/var/dfs/adm\*O" At least \*L755\*O, and \*Lother\*O cannot have write access .LI "\*Edcelocal\*L/var/dfs/admin.bos\*O" At least \*L600\*O, and \*Lother\*O cannot have write or execute access .LE .PP The BOS Server also displays the message if all of these objects are not owned by \*Lroot\*O. The BOS Server displays the message only as a courtesy to the user. It does nothing to change the protections on these objects, nor does it fail if these protections are violated. .zZ "defect,7219,R1.0.2,Review comments" .PP .zA "defect,9132,R1.0.3,bosserver checks are only defaults" .nS "note" The protections just described are the default protections enforced by the BOS Server. Your vendor can modify the required owner of the indicated directories and the permissions those directories must have. Refer to your vendor's documentation to determine the protections that apply for your version of DFS. .nE .zZ "defect,9132,R1.0.3,bosserver checks are only defaults" .PP The command then displays a separate entry for each specified process. The first line of an entry shows the current status of the process. The possible statuses for any process include .VL .LI "\*Lcurrently running normally\*O" For a \*Lsimple\*O process, this means it is currently running; for a \*Lcron\*O process, this means it is scheduled to run. .LI "\*Ltemporarily enabled\*O" .zA "defect,6721,R1.0.2,Correct bos restart doc" The status flag for the process in the \*Edcelocal\*L/var/dfs/BosConfig\*O file is \*LNotRun\*O, but the process has been enabled with the \*Lbos startup\*O or \*Lbos restart\*O command. .zZ "defect,6721,R1.0.2,Correct bos restart doc" .LI "\*Ltemporarily disabled\*O" Either the \*Lbos shutdown\*O command was used to stop the process, or the BOS Server quit trying to restart the process, in which case the message \*Cstopped for too many errors\*O also appears. .LI "\*Ldisabled\*O" The status flag for the process in the \*LBosConfig\*O file is \*CNotRun\*O, and the process has not been enabled. .LI "\*Lhas core file\*O" The process failed or produced a core file at some time. This message can appear with any of the other messages. Core files are stored in \*Edcelocal\*L/var/dfs/adm\*O. The name of the core file indicates the process that failed (for example, \*Lcore.ftserver\*O). .LE .PP The output for a \*Lcron\*O process includes an auxiliary status message that reports when the command is next scheduled to execute. .PP The command displays the following additional information when the \*L\-long\*O option is used: .ML .LI The process type (\*Lsimple\*O or \*Lcron\*O). .LI How many \*Lproc starts\*O occurred (proc starts occur when the process is started or restarted by the current BOS Server). .LI The time of the last proc start. .LI The exit time and error exit time when the process last failed. This appears only if the process failed while the BOS Server was running. (Provided the BOS Server was running both when the process was started and when it failed, the BOS Server can provide this information for any process that has an entry in the \*LBosConfig\*O file.) .LI The command and its options used by the BOS Server to start the process. .LE .SH "EXAMPLES" .PP The following command displays the statuses of all server processes on the File Server machine named \*Lfs4\*O: .iS \*C$\*O \*Lbos status /.../abc.com/hosts/fs4\*O .iE .oS \*CInstance ftserver, currently running normally.\*O .nL \*CInstance repserver, currently running normally.\*O .oE .PP If the \*L\-long\*O option is included with the command, the following additional information is displayed: .oS \*CInstance ftserver, (type is simple) currently running normally.\*O .nL \*CProcess last started at Fri Nov 22 05:36:02 1991 (1 proc starts)\*O .nL \*CParameter 1 is `\*Edcelocal\*C/bin/ftserver'\*O .oE .oS \*CInstance repserver, (type is simple) currently running normally.\*O .nL \*CProcess last started at Fri Nov 22 05:36:48 1991 (1 proc starts)\*O .nL \*CParameter 1 is `\*Edcelocal\*C/bin/repserver'\*O .oE .SH "RELATED INFORMATION" .PP Commands: \*Lbos create(1m)\*O, \*Lbos restart(1m)\*O, \*Lbos shutdown(1m)\*O, \*Lbos start(1m)\*O, \*Lbos startup(1m)\*O, \*Lbos stop(1m)\*O .PP Files: \*LBosConfig(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Lstatus\*O" .iX "-]" "DFS servers" "checking status" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos stop" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Lstop\*O" .iX "-[" "DFS servers" "stopping" .SH NAME .PP \*Lbos stop\*O \- Stops processes after changing their status flags in the \*LBosConfig\*O file to \*LNotRun\*O .SH "SYNOPSIS" .sS .PP \*Lbos stop -server \*Vmachine\*L -process \*Vserver_process\*O... [\*L\-wait\*O] .nL [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine on which to stop the processes. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-process \*Vserver_process\*O" Specifies each process that the BOS Server is to stop. The BOS Server stops a process after setting its status flag in the \*LBosConfig\*O file to \*LNotRun\*O. Refer to a process by the name assigned with the \*L\-process\*O option of the \*Lbos create\*O command; this name appears in the output from the \*Lbos status\*O command. .LI "\*L\-wait\*O" Indicates that the command shell prompt is not to return until all specified processes actually stop running. If this option is omitted, the prompt returns almost immediately, even if all of the processes are not yet stopped. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lbos stop\*O command sets the status flag for each server process specified by \*L\-process\*O to \*LNotRun\*O in the \*LBosConfig\*O file on the server machine specified by \*L\-server\*O; it then stops each process. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .SH "RELATED INFORMATION" .PP Commands: \*Lbos create(1m)\*O, \*Lbos shutdown(1m)\*O, \*Lbos status(1m)\*O .PP Files: \*LBosConfig(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Lstop\*O" .iX "-]" "DFS servers" "stopping" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bos uninstall" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbos\*O command suite" "\*Luninstall\*O" .iX "-[" "binary files" "replacing" .SH NAME .PP \*Lbos uninstall\*O \- Installs the former versions of binary files .SH "SYNOPSIS" .sS .PP .zA "defect,5782,R1.0.2,Include bos uninstall -all and related information" \*Lbos uninstall -server \*Vmachine\*L -file \*Vbinary_file\*O... [\*L\-dir \*Valternate_dest\*O] [\*L\-all\*O] .nL [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-help\*O] .zZ "defect,5782,R1.0.2,Include bos uninstall -all and related information" .sE .SH "OPTIONS" .VL .zA "defect,5782,R1.0.2,Include bos uninstall -all and related information" .LI "\*L\-server \*Vmachine\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the server machine on which the former versions of specified binary files are to be used. The BOS Server on this machine executes the command. To run this command using a privileged identity, specify the full DCE pathname of the machine. To run this command using the unprivileged identity \*Lnobody\*O (the equivalent of running the command with the \*L\-noauth\*O option), specify the machine's host name or IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .LI "\*L\-file \*Vbinary_file\*O" .zA "defect,6021,R1.0.2,Fix -file and -dir options" Names each binary file to be replaced with its next-oldest version (\*L.BAK\*O, if it exists; otherwise, \*L.OLD\*O). All specified files must reside in the same directory (\*Edcelocal\*L/bin\*O, by default, or an alternate directory specified with the \*L\-dir\*O option\*O). Specify only filenames; if a pathname is provided for a file, the command ignores all but the final element. .zZ "defect,6021,R1.0.2,Fix -file and -dir options" .LI "\*L\-dir \*Valternate_dest\*O" .zA "defect,6021,R1.0.2,Fix -file and -dir options" Provides the pathname of the directory in which all specified files reside. Omit this option if the files reside in the default directory, \*Edcelocal\*L/bin\*O; otherwise, provide a full or relative pathname. Relative pathnames (pathnames that do not begin with a slash) are interpreted relative to the \*Edcelocal\*O directory on the machine specified by \*L\-server\*O. .zZ "defect,6021,R1.0.2,Fix -file and -dir options" .LI "\*L\-all\*O" Directs the BOS Server on the indicated machine to remove all versions (current, \*L.BAK\*O, and \*L.OLD\*O) of the specified files. Only versions of the files that reside in the \*Edcelocal\*L/bin\*O directory (or an alternate directory specified with the \*L\-dir\*O option) are removed. .zZ "defect,5782,R1.0.2,Include bos uninstall -all and related information" .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lbos\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. The command fails if you use this option and DFS authorization checking is not disabled on the machine specified by \*L\-server\*O. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,4782,R1.0.2,Update Server clarified for install/uninstall" .zA "defect,5782,R1.0.2,Include bos uninstall -all and related information" The \*Lbos uninstall\*O command replaces each binary file specified with the \*L\-file\*O option with its next-oldest version. Use the \*L\-server\*O option to specify the name of the server machine that houses the files to be manipulated. All specified files must reside in the same directory. By default, the command looks for the files in the \*Edcelocal\*L/bin\*O directory; use the \*L\-dir\*O option to name a different directory. Versions of the files in other directories on the specified machine are not affected. .PP The command applies the following algorithm to the removal of each binary file: .ML .LI If current, \*L.BAK\*O, and \*L.OLD\*O versions of the file exist, the command makes the \*L.BAK\*O version the current version and it makes the \*L.OLD\*O version the \*L.BAK\*O version. .LI If any version of the file does not exist, the command omits it from the algorithm. For example, if no \*L.BAK\*O version exists, the command makes the \*L.OLD\*O version the current version. .LI If the \*L\-all\*O option is included with the command, the command removes all versions (current, \*L.BAK\*O, and \*L.OLD\*O) of the file that exist. .LI The command displays the following message if no version of the file exists, or if only the current version exists and the \*L\-all\*O option is omitted: .oS \*Cbos: failed to uninstall \*Efilename\*C (there is no earlier version present .nL to reinstall)\*O .oE .PP where \*Efilename\*O is the name of the file that cannot be replaced or removed. .LE .zZ "defect,5782,R1.0.2,Include bos uninstall -all and related information" .PP The machine specified with the \*L\-server\*O option should be the Binary Distribution machine for its CPU/operating system type. If it is not, the binary files are overwritten the next time the \*Lupclient\*O process on the specified machine copies new (or different) versions of binary files via the \*Lupserver\*O process on the Binary Distribution machine of its CPU/OS type. (Note that the Update Server propagates binary files from Binary Distribution machines, but the BOS Server manipulates files when the \*Lbos uninstall\*O command is issued; by default, it takes the Update Server 5 minutes to propagate binary files from a Binary Distribution machine.) .zZ "defect,4782,R1.0.2,Update Server clarified for install/uninstall" .PP To make the machine specified by \*L\-server\*O start using the reinstalled binary files immediately, issue the \*Lbos restart\*O command. Otherwise, the binaries are not used until the BOS Server restarts the affected process at the new binary restart time specified in the \*Edcelocal\*L/var/dfs/BosConfig\*O file. Use the \*Lbos getrestart\*O and \*Lbos setrestart\*O commands to inspect and set the new binary restart time. (The information in this paragraph applies \*Eonly\*O to affected processes already under the control of the BOS Server.) .PP .zA "enh,R1.0.2,Changed for consistency" Use the \*Lbos install\*O command to install new versions of binary files on a server machine. Use the \*Lbos prune\*O command to remove \*L.BAK\*O and \*L.OLD\*O files from the \*Edcelocal\*L/bin\*O directory (the command can also be used to remove core files from the \*Edcelocal\*L/var/dfs/adm\*O directory). Use the \*Lbos getdates\*O command to check the time stamps on binary files. .zZ "enh,R1.0.2,Changed for consistency" .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.bos\*O file on the machine specified by \*L\-server\*O. .SH "RELATED INFORMATION" .PP Commands: \*Lbos getdates(1m)\*O, \*Lbos getrestart(1m)\*O, \*Lbos install(1m)\*O, \*Lbos prune(1m)\*O, \*Lbos restart(1m)\*O, \*Lbos setrestart(1m)\*O, .zA "defect,4782,R1.0.2,Update Server clarified for install/uninstall" \*Lupclient(1m)\*O, \*Lupserver(1m)\*O .zZ "defect,4782,R1.0.2,Update Server clarified for install/uninstall" .PP Files: \*LBosConfig(4)\*O .iX "-]" "\*Lbos\*O command suite" "\*Luninstall\*O" .iX "-]" "binary files" "replacing" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "bosserver" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lbosserver\*O command" .iX "-[" "BOS Server" "initializing" .SH NAME .PP \*Lbosserver\*O - Initializes the Basic OverSeer (BOS) Server process .SH "SYNOPSIS" .sS \*Lbosserver\*O [\*L-adminlist \*Vfilename\*O] [\*L-noauth\*O] [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-adminlist \*Vfilename\*O" Specifies the file that contains principals and groups authorized to execute \*Lbosserver\*O RPCs (usually using \*Lbos\*O commands). If this option is omitted, the \*Lbosserver\*O obtains the list of authorized users from the default administrative list file, \*Edcelocal\*O\*L/var/dfs/admin.bos\*O. .LI "\*L-noauth\*O" .zA "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" Invokes the \*Lbosserver\*O with DFS authorization checking turned off. In this mode, DFS processes, including the \*Lbosserver\*O process, do not check to see whether issuers have the necessary privilege to enter administrative commands. .zZ "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" .PP This option is intended for use when the BOS Server is initially installed on a server machine. Because it starts the \*Lbosserver\*O with DFS authorization checking turned off, it allows the issuer to add members to the \*Ladmin.bos\*O administrative list and to add a key to the keytab file on the server machine. .PP .zA "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" Use this mode sparingly, as it presents a security risk. Using this option forces all DFS server processes on the machine to run without DFS authorization checking. .zZ "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .PP The \*Lhelp\*O and \*Lapropos\*O commands available with all command suites are also available with the \*Lbosserver\*O command. See the \*Lbos help\*O and \*Lbos apropos\*O pages for examples of using these commands. .LE .SH "DESCRIPTION" .PP .zA "defect,7219,R1.0.2,Review comments" The Basic OverSeer Server (\*LBOS Server\*O) monitors other DFS server processes, such as the \*Lflserver\*O and \*Lftserver\*O processes, running on the machine and restarts failed processes automatically (without the intervention of a system administrator). The BOS Server, or \*Lbosserver\*O process, monitors each server process that has a process entry in the local \*LBosConfig\*O file. The \*Lbosserver\*O process must be run on all DFS server machines. The \*Lbosserver\*O command, which resides in \*Edcelocal\*L/bin/bosserver\*O, is usually added to the proper system start-up file (\*L/etc/rc\*O or its equivalent); the process places itself in the background after it starts. .zZ "defect,7219,R1.0.2,Review comments" .PP When it is started, the \*Lbosserver\*O creates the \*Edcelocal\*L/var/dfs/adm/BosLog\*O event log file if the file does not already exist. It then appends messages to the file. If the \*LBosLog\*O file exists when the \*Lbosserver\*O is started, the process moves it to the \*LBosLog.old\*O file in the same directory (overwriting the current \*LBosLog.old\*O file if it exists) before creating a new version to which to append messages. .PP The principals and groups in the \*Ladmin.bos\*O administrative list are authorized to issue BOS commands to stop, start, create, and modify server processes on that machine. For simplified administration, the same \*Ladmin.bos\*O administrative list can be used by all \*Lbosserver\*O processes in the administrative domain. .PP The first time the \*Lbosserver\*O process is initialized, it creates several directories (such as the \*Edcelocal\*L/var/dfs/adm\*O directory and any nonexistent directories along this path), sets the owners to the appropriate identities, and sets the mode bits to provide appropriate access. The \*Lbosserver\*O process also creates the \*Edcelocal\*L/var/dfs/admin.bos\*O administrative list file and the \*Edcelocal\*L/var/dfs/BosConfig\*O configuration file if either file does not already exist. On subsequent restarts, the process writes the following message to the \*LBosLog\*O file if the owners and mode bits of these objects are not set appropriately: .oS \*CBosserver reports inappropriate access on server directories.\*O .oE .PP See the reference page for the \*Lbos status\*O command for information about the protections the BOS Server wants to see enforced. .zA "defect,9132,R1.0.3,bosserver checks are only defaults" .nS "note" Your vendor can modify the owner of directories created by the BOS Server and the permissions those directories are created with. Refer to your vendor's documentation to determine the protections that apply for your version of DFS. .nE .zZ "defect,9132,R1.0.3,bosserver checks are only defaults" .PP .zA "defect,5791,R1.0.2,Bos status displays NoAuth message" When initially installing the BOS Server on a server machine, use the \*L-noauth\*O option to initialize the \*Lbosserver\*O process with DFS authorization checking disabled. This creates the \*LNoAuth\*O file in the \*Edcelocal\*L/var/dfs\*O directory on the local disk; when the file is present, DFS authorization checking is disabled on the machine. .PP With DFS authorization checking disabled, add members to the \*Ladmin.bos\*O list and add a key to the keytab file on the server machine. When these steps are complete, use the \*Lbos setauth\*O command to enable DFS authorization checking. Because running with DFS authorization checking disabled is a serious security risk, enable DFS authorization checking as soon as the previous steps are complete. The \*Lbos status\*O command can be used to determine whether DFS authorization checking is enabled or disabled on a machine; it displays the following message if DFS authorization checking is disabled on a machine (it does not display the message if DFS authorization checking is enabled): .oS \*CBosserver reports machine is not checking authorization.\*O .oE .zZ "defect,5791,R1.0.2,Bos status displays NoAuth message" .SS "Privilege Required" .PP The issuer must be logged in as \*Lroot\*O on the local machine. .SH "OUTPUT" .PP If problems are encountered during initialization, the \*Lbosserver\*O process displays error messages on standard error output. The \*Lbosserver\*O process keeps an event log in the file \*Edcelocal\*O\*L/var/dfs/adm/BosLog\*O. .SH "RELATED INFORMATION" .PP .zA "defect,5791,R1.0.2,Bos status displays NoAuth message" Commands: \*Lbos setauth(1m)\*O, \*Lbos status(1m)\*O .PP Files: \*Ladmin.bos(4)\*O, \*LBosConfig(4)\*O, \*LBosLog(4)\*O, \*LNoAuth(4)\*O .zZ "defect,5791,R1.0.2,Bos status displays NoAuth message" .iX "-]" "\*Lbosserver\*O command" .iX "-]" "BOS Server" "initializing" .\" $Header: bp_config.1m, updated 5/15/96 by rod@acm.org$ .TH bp_config 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Rel. 10.20: August, 1996 .SH NAME .C bp_config \- \s-1VME\s0 backplane networking configuration utility .SH SYNOPSES .SS "Store configuration to non-volatile memory" .C bp_config .RC [ \-bus | \-poll ] .RC [ \-f .IR cfgfile ] .RC [ \-D .IR name ] .RC [ \-U .IR name ] .SS "Perform syntax check" .C bp_config .C \-c .RC [ \-bus | \-poll ] .RC [ \-f .IR cfgfile ] .RC [ \-D .IR name ] .RC [ \-U .IR name ] .SH DESCRIPTION The .C bp_config utility creates a VME backplane networking system configuration by reading an ASCII configuration file that specifies the VME address range and space for a memory area that is shared by the CPUs in the system; the number of CPUs that use backplane networking; and other VME resources for the backplane networking driver. The configuration file format is described in .IR vme.CFG (4). .PP The .C bp_config utility uses the same configuration file as the .CR vme_config (1M) utility. VME Services provide default backplane networking parameters if .C bp_config is not executed. These defaults specify the anchor size, position, and address modifier type. .C bp_config derives the backplane networking configuration from the .C bpSharedMem memory entity declaration in the configuration file. .PP .C bp_config checks to see that .C /dev/bp0 exists, creating it if not. .PP When .C bp_config is invoked without command line parameters, it generates a configuration from the default file .C /etc/vme/vme.CFG and does not change the interrupt type .RC ( bus or .CR poll ) that was set by its previous execution. (If no interrupt type has been previously specified, .C bp_config assumes bus interrupts.) The configuration information for the current CPU is saved to the system's non-volatile memory. .PP The current CPU is identified by the CPU number stored in non-volatile memory. This value may be changed by using the .C -N .I cpu_number option of the .CR vme_config (1M) command. For more information on VME configuration and configuration file format, see the .IR "HP-UX 10.20 VME Services Guide" . .PP Storing configuration information to non-volatile memory requires that the .C vme2 and .C bp device drivers be installed in the kernel. The .C vme2 device driver is in the .SM VME_SERV fileset. .SS Options .TP 8 .C \-bus Configure backplane networking to use VME bus interrupts. One or more VME bus interrupt levels must be assigned to this CPU in the configuration file. If no interrupts are assigned, backplane networking will poll instead. .TP .C \-poll Configure backplane networking to use polling. .TP .C \-c Perform a syntax check on the configuration file. The configuration is not saved to the system's non-volatile memory. .TP .CI \-f " cfgfile" Use the specified configuration file instead of .CR /etc/vme/vme.CFG . .TP .CI \-U " name" Passed to .C cpp to remove any initial definition of name. .TP .CI \-D " name" .PD 0 .TP .CI \-D " name=def" Passed to .C cpp to define .I name as if by a .C #define directive. If no .CI = def is given, .I name is defined as 1. The .C -D option has lower precedence than the .C -U option. Thus, if the same name is used in both a .C -U option and a .C -D option, the name is undefined regardless of the order of the options. .PD .SS "Configuration Process" To configure a VME system, follow these steps. For further information, refer to .CR vme_config (1M) or the .IR "HP-UX 10.20 VME Services Guide" . .TP 3 1. Edit the configuration file .C /etc/vme/vme.CFG or another file to reflect the desired VME system. This file must include the .C bpSharedMem memory entity. .TP 2. Execute .CR vme_config (1M) on each .SM HP\-UX processor in the VME system, using the same configuration file for every processor. .TP 3. Execute .C bp_config on each .SM HP\-UX processor that will use backplane networking, using the same configuration file for every processor. .TP 4. Reboot the systems. The .SM HP\-UX kernels will initialize VME backplane networking according to the contents of the non-volatile memory as created in the previous step. .SH EXAMPLES Load non-volatile memory with the configuration specified in .CR /etc/vme/vme.CFG , and do not change the interrupt type, which is assumed to be .C bus if this is the first execution: .IP .C bp_config .PP Load non-volatile memory with the configuration specified in a different file, and set backplane networking to use VME bus interrupts: .IP .C "bp_config -bus -f hpux_bp.CFG" .PP Load non-volatile memory with the configuration specified in a different file, and set backplane networking to poll: .IP .C "bp_config -poll -f my_cfg.CFG" .SH RETURNS .C bp_config returns an exit code of .C 0 if successful. An exit code of .C 1 indicates a syntax error in the configuration file. An exit code of .C 2 indicates an internal or system error. .PP Error messages will be displayed to .SM STDOUT. .SH NOTES .C bp_config will ask for confirmation before overwriting the values stored in non\-volatile memory. .PP The stored configuration information does not take effect until the system is rebooted. .PP The .C vme2 and .C bp device drivers must be in the kernel before .C bp_config can save configuration information to non-volatile memory. The .C vme2 driver is in the fileset .CR VME\-SERV . The .C bp driver is in the fileset .CR HPUX\-BP . .SH AUTHOR .C bp_config was developed by HP. .SH FILES .PP .TP 23 .C /etc/vme/vme.CFG The default VME configuration file that .C bp_config uses. .SH SEE ALSO .IR vme_config (1M), .IR vme.CFG (4), .IR cpp (1). .\" $Header: /vob/dce.doc/src/doc/HP/misc/man8/camera.1m,v /main/2 1996/04/17 16:30 UTC millett Exp $ ...\" .rm zA .rm zZ .TH camera "8" "" "HP DCE" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .ds )H Hewlett-Packard Company .ds ]W HP DCE/9000 Version 1.2 .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml .SH NAME \*Lcamera\*O - create a shar file which contains a snapshot of the hardware and software state of a node. .SH "SYNOPSIS" \*Lcamera\*O [\*L-s \*Vsharfile_pathname\*O] [\*L-f \*Vconfig_file_pathname\*O] [\*L-d \*Vsnapshot_dir_pathname\*O] [\*L-u\*O] \*Lcamera -e \*Vsnapshot_dir_pathname \*L-s \*Vsharfile_pathname \*O[\*L-u\*O] .SH "OPTIONS" .VL 1i .LI "\*L-s \*Vsharfile_pathname\*O" Direct snapshot output to a \*Lshar\L*O file specified by \*Vsharfile_pathname\*O. A log file is also created in the same directory as the \*Lshar\*O file. .PP The file specified by \*Vsharfile_pathname\*O should not exist before you run \*Lcamera\*O. The default sharfile output pathname is \*L/opt/dcelocal/hpcamera/snapshots/snap\*Vtimestamp\*L.shar\*O. .LI "\*L-d \*Vsnapshot_dir_pathname\*O" Preserve snapshot directory and store it at the location specified by \*Vsnapshot_dir_pathname\*O. .PP The directory specified by \*Vsnapshot_dir_pathname\*O should not exist before you run \*Lcamera\*O. By default the snapshot directory is not preserved. .LI "\*L-f \*Vconfig_file_pathname\*O" Read snapshot description file specified by \*Vconfig_file_pathname\*O. .PP The default snapshot description file is \*L/opt/dcelocal/hpcamera/etc/snapshot.des\*O. .LI "\*L-u\*O" Do not validate UNIX utilities. .PP By default, \*Lcamera\*O verifies that the UNIX utilities it needs (\*Lshar\*O, \*Lfind\*O, \*Lgetopt\*O, etc.) are operational before it invokes diagnostic programs. Once \*Lcamera\*O runs successfully on a given system, you probably don't need to validate utilities again. Therefore, you can use \*L-u\*O to improve performance on subsequent runs. .LI "\*L-e \*Vsnapshot_dir_pathname\*O" Create a \*Lshar \*Ofile from an existing snapshot directory specified by \*Vsnapshot_dir_pathname\*O. .PP When \*L-e\*O is specified, no snapshot will be created and no diagnostic tools will be run. Use \*L-e\*O only if you want to create a \*Lsha\*Or file from a previously created snapshot. .PP When you use \*L-e\*O, you must also specify an output file with the \*L-s\*O option. .LE .SH "DESCRIPTION" \*Lcamera\*O is an execution and control environment for running a series of diagnostic tools on a single machine. In effect, it takes a snapshot of the hardware and software state of the machine. By default, the output goes to a temporary directory that is converted to a \*Lshar\*O file for easy mail transfer. The \*Lshar\*O file is put in \*L/opt/dcelocal/hpcamera/snapshots\*O along with a log file. After the \*Lshar\*O file is created, the temporary output directory is removed. However, you can preserve the temporary output directory by using the \*L-d \*Vsnapshot_dir_pathname\*O option. .PP \*Lcamera\*O reads a snapshot description file that specifies which tools to run, their execution order, and the location of their output. The location of the default snapshot description file is \*L/opt/dcelocal/hpcamera/etc/snapshot.des\*O. You can specify a different snapshot description file by using the \*L-f \*Vconfig_file_pathname\*O option. For more information see the manpage, snapshot.des(4). .SH "EXAMPLES" The following example creates and preserves the output directory in \*L/tmp/snapshot.dir\*O and creates a \*Lshar\*O file in \*L/tmp/snapshot.shar\*O: .oS \*Lcamera -s /tmp/snapshot.shar -d /tmp/snapshot.dir\*O .oE The following example creates a second \*Lshar\*O file, \*L/tmp/snapshot2.shar\*O, from the existing snapshot directory \*L/tmp/snapshot.dir\*O: .oS \*Lcamera -e /tmp/snapshot.dir -s /tmp/snapshot2.shar\*O .oE .SH "AUTHOR" \*Lcamera\*O was developed by HP. .SH "FILES" .VL 2.5i .LI "\*L/usr/bin/camera\*O" \*Lcamera\*O executable .LI "\*L/opt/dcelocal/hpcamera/etc/snapshot.des\*O" default snapshot description file .LI "\*L/opt/dcelocal/hpcamera/scripts/*\*O" HP-supplied diagnostic scripts .LE .SH "SEE ALSO" \*Lsnapshot.des(4), shar(1)\*O .\" $Header: captoinfo.1m,v 72.3 94/07/01 10:52:31 ssa Exp $ .TA c .TH captoinfo 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME captoinfo \- convert a termcap description into a terminfo description .SH SYNOPSIS .B captoinfo .RB [ -1v ] .RB [ -w\c .IR n ] .RI [ filenames ] .SH DESCRIPTION .CR captoinfo looks in .I filenames for .IR termcap (3X) descriptions. For each one found, an equivalent .IR terminfo (4) description is written to standard output along with any comments found. The short two letter name at the beginning of the list of names in a .CR termcap entry, a holdover from Version 6 UNIX, is removed. Any description that is expressed relative to another description (as specified in the .CR termcap .IR tc = field) is reduced to the minimum superset before output. .PP If no .I filename is given, the environment variable .CR TERMCAP is used for the filename or entry. If .CR TERMCAP is a full pathname to a file, only the terminal whose name is specified in the environment variable .CR TERM is extracted from that file. If the environment variable .CR TERMCAP is not set, the file .CR /usr/share/lib/termcap is read. .SS Options .I captoinfo recognizes the following options: .RS .TP 6 .C -1 Print one field per line. If this option is not selected, multiple fields are printed on each line up to a maximum width of 60 characters. .TP .C \-v Print (verbose) tracing information as the program runs. Additional .C -v options print more information (for example .CR "-v -v -v " or " -vvv" ). .TP .CI -w n Change the output width to .I n characters. .SH DIAGNOSTICS .TP 10 .C "tgetent failed with return code n (reason)." The termcap entry is not valid. In particular, check for an invalid 'tc=' entry. .TP .C "unknown type given for the termcap code 'cc'." The termcap description had an entry for 'cc' whose type was not boolean, numeric or string. .TP .C "wrong type given for the boolean (numeric, string) termcap code 'cc'." The boolean termcap entry 'cc' was entered as a numeric or string capability. .TP .C "the boolean (numeric, string) termcap code 'cc' is not a valid name." An unknown termcap code was specified. .TP .C "tgetent failed on TERM=term." The terminal type specified could not be found in the termcap file. .TP .C "\s-1TERM\s0=term: cap cc (info ii) is \s-1NULL\s0: \s-1REMOVED\s0" The termcap code was specified as a null string. The correct way to cancel an entry is with an '@', as in ':bs@:'. Giving a null string could cause incorrect assumptions to be made by any software that uses termcap or terminfo. .TP .C "a function key for 'cc' was specified, but it already has the value 'vv'." When parsing the 'ko' capability, the key 'cc' was specified as having the same value as the capability 'cc', but the key 'cc' already had a value assigned to it. .TP .C "the unknown termcap name 'cc' was specified in the 'ko' termcap capability." A key that could not be handled was specified in the 'ko' capability. .TP .C "the vi character 'v' (info 'ii') has the value 'xx', but 'ma' gives 'n'." The 'ma' capability specified a function key with a value different from that specified in another setting of the same key. .TP .C "the unknown vi key 'v' was specified in the 'ma' termcap capability." A vi key unknown to captoinfo was specified in the 'ma' capability. .TP .C "Warning: termcap sg (nn) and termcap ug (nn) had different values." .CR terminfo assumes that the sg (now xmc) and ug values were the same. .TP .C "Warning: the string produced for 'ii' may be inefficient." The parameterized string being created should be rewritten by hand. .TP .C "Null termname given." The terminal type was null. This occurs when .CR $TERM is null or not set. .TP .C "cannot open "%s" for reading." The specified file could not be opened. .TP .C "Warning: cannot translate \f1\fP (unsupported in terminfo)." This termcap capability is no longer supported in terminfo , and therefore cannot be translated. .SH WARNINGS Certain .CR termcap defaults are assumed to be true. For example, the bell character .RC ( terminfo .IR bel ) is assumed to be .CR "^G" . The linefeed capability .RC ( termcap .IR nl ) is assumed to be the same for both .CR cursor_down and .CR scroll_forward .RC ( terminfo .I cud1 and .IR ind , respectively). Padding information is assumed to belong at the end of the string. .PP The algorithm used to expand parameterized information for .CR termcap fields such as .CR cursor_position .RC ( termcap .IR cm , .CR terminfo .IR cup ) sometimes produces a string which, though technically correct, may not be optimal. In particular, the rarely used .CR termcap operation .CR %n produces strings that are especially long. Most occurrences of these less than optimal strings are flagged with a warning message, and may need to be recoded by hand. .PP HP supports only terminals listed on the current list of supported devices. However, the terminfo database contains both supported and nonsupported terminals. If you use nonsupported terminals, they may not work correctly. .SH AUTHOR .CR captoinfo was developed by AT&T. .SH SEE ALSO tic (1M), untic (1M), curses (3X), termcap (3X), terminfo (4). .\" index@\f2captoinfo\f1 \- convert a termcap description into a terminfo description@@@\f3captoinfo(1M)\f1 .\" index@termcap description, convert into a terminfo description@@@\f3captoinfo(1M)\f1 .\" index@terminfo description, convert from a termcap description@@@\f3captoinfo(1M)\f1 .\" .\" toc@\f3captoinfo(1M)\f1:\0\0\f2captoinfo\f1@@@convert a termcap description into a terminfo description .\" .\" fileset_database@captoinfo.1m@SYS-ADMIN-MAN .\" $Header: catman.1m,v 72.7 94/11/30 14:27:52 ssa Exp $ .TA c .TH catman 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME catman \- create the cat files for the manual .SH SYNOPSIS .CR /usr/sbin/catman .RC [ \|\-A\| .IR alt-path ] .RC [ \|\-p\| ] .RC [ \|\-m\| ] .RC [ \|\-n\| ] .RC [ \|\-w\| ] .RC [ \|\-z\| ] .RI [ \|sections\| ] .SH DESCRIPTION The .CR catman command creates the formatted versions of the online manual from .IR nroff (1)-compatible source files. Each manual entry in the .CR man\(**.Z and .CR man\(** directories is examined, and those whose formatted versions are missing or out-of-date are recreated. .CR catman formats the most recent of the entries, compresses it, and puts it into the appropriate .CR cat\(**.Z directory. .PP If any changes are made, .CR catman recreates the .CR /usr/share/lib/whatis database. By default, the .CR /usr/share/lib/whatis database is overwritten. If the .CR MANPATH environment variable is set to a non-default set of paths, the old database file is saved in .CR /usr/share/lib/whatis.old so that, if desired, the system administrator may merge them together. .PP By default, .CR catman searches the .CR man\(**.Z and .CR man\(** subdirectories under the following man directories: .PD 0 .RS .TP 3 \(bu .C /usr/share/man .TP \(bu .C /usr/contrib/man .TP \(bu .C /usr/local/man .PD .RE If .CR MANPATH is set in the environment, the directories given in .CR MANPATH are checked instead of the default. See .IR environ (5) for a description of the .CR MANPATH environment variable. .PP Before running .CR catman , remove any existing .CR cat\(** directories. If the .CR \-z option is used, .CR cat\(**.Z directories should be removed instead. If both .CR cat\(**.Z and .CR cat\(** directories exist, .IR man (1) updates both directories and more space is used. .PP Any command-line parameters not starting with .CR \- are interpreted as a list of manual sections (directories) to search. For example: .IP .C catman 123 .PP restricts updating to manual sections 1, 2, and 3 (directories .CR man1 , .CR man2 , and .CR man3 ). .SS Options .CR catman supports the following options: .RS .TP 15 .CR \-m Create a merged .CR /usr/share/lib/whatis database; i.e., information on new manual entries (added since the last time .CR catman was run) is merged into the current database rather than overwriting it. Ignored if selected with the .CR \-n option. .TP .CR \-n Prevents creation of .CR /usr/share/lib/whatis . .TP .CR \-p Prints what would be done instead of doing it. .TP .CR \-w Causes only the .CR /usr/share/lib/whatis database to be created. No manual reformatting is done. .TP .CR \-z Puts the formatted entries in the .CR cat\(** directories rather than in the .CR cat\(**.Z directories. .TP .CI \-A \0alt-path Perform actions based on the given alternate root. With this option, .I alt-path will be prepended to all directory paths, including default paths, the paths defined by .CR MANPATH , and the path to .CR /usr/share/lib/whatis . .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR MANPATH defines parent directories to be used when searching .CR man\(** and .CR man\(**.Z directories. .SH WARNINGS If unformatted manual entries (those in the .CR ../man\(** subdirectories) have been removed since the last time .CR catman was run, information in the .CR /usr/share/lib/whatis database may be lost. The .CR \-m option may be used to override this, but may result in repeated lines in the database for the same manual entry. .SH EXAMPLES Create uncompressed .CR cat\(** files for sections 1 and 1m of the manual, but don't create the .CR /usr/share/lib/whatis database: .IP .C catman -z -n 11m .PP Run .C catman from a server to create .C cat\(** entries for a diskless client under the alternate root .CR /export/shared_roots/OS_700 : .IP .C catman -A /export/shared_roots/OS_700 .PP .PD 0 This will create .C cat\(** manpages under: .IP .CR /export/shared_roots/OS_700/usr/share/man/ .br .CR /export/shared_roots/OS_700/usr/contrib/man/ .br .CR /export/shared_roots/OS_700/usr/local/man/ .PP and a .CR whatis file in: .IP .C /export/shared_roots/OS_700/usr/share/lib/whatis .PD .PP Create .C cat\(** entries for an application and merge the information with the .C /usr/share/lib/whatis database: .IP .C MANPATH=/opt/langtools/man .br .C catman -m .PP Note that you may wish to save .CR MANPATH before doing this, so as not to lose your current .CR MANPATH . .SH AUTHOR .CR catman was developed by HP and the University of California, Berkeley. .SH FILES .ift .TP 40 .ifn .TP 30 .PD 0 .C /usr/share/man/man\(**[.Z]/\(** Unformatted .RI ( nroff (1)-compatible source) manual entry files [compressed]. .TP .C /usr/share/man/cat\(**[.Z]/\(** Formatted manual pages [compressed]. .TP .C /usr/local/man/man\(**[.Z]/\(** .TP .C /usr/local/man/cat\(**[.Z]/\(** .TP .C /usr/contrib/man/man\(**[.Z]/\(** .TP .C /usr/contrib/man/cat\(**[.Z]/\(** .TP .C /usr/share/lib/whatis Database of manpage entry summaries; utilized by the .C man -k command. .TP .C /usr/lbin/mkwhatis Command to make .CR whatis database. .PD .SH SEE ALSO compress(1), fixman(1M), man(1), environ(5). .\" index@\f2catman\f1 \- create the cat files for the manual@@@\f3catman(1M)\f1 .\" index@create the cat files for the manual@@@\f3catman(1M)\f1 .\" index@files: create the cat files for the manual@@@\f3catman(1M)\f1 .\" index@manual pages, on-line, create the cat files for@@@\f3catman(1M)\f1 .\" index@cat files for on-line manual pages, create@@@\f3catman(1M)\f1 .\" .\" toc@\f3catman(1M)\f1:\0\0\f2catman\f1@@@create the cat files for the manual .\" .\" fileset_database@catman.1m@SYS-ADMIN-MAN ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Mass. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by DIGITAL * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .nr H1 1 .wH "" ...\" .rm zA .rm zZ .TH "cds_intro"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lcdscp\*O commands" "about" .SH NAME .PP \*Lcds_intro\*O - Introduction to the CDS commands .wH "" .SH "DESCRIPTION" .PP The DCE Cell Directory Service provides the following management commands: .VL 2m .LI "o" The \*Lcdsbrowser\*O command starts the CDS Browser utility. This utility is based on the OSF/Motif\(tm graphical user interface. The Browser can display an overall directory structure as well as show the contents of directories. .LI "o" The \*Lcdscp\*O command starts the CDS control program. Use this command line interface to manage the CDS components and the contents of your namespace. .LE .PP The following commands are typically started automatically by scripts that execute as part of normal system start-up procedures. See the reference pages for these commands before you try to use them. .VL 2m .LI "o" The \*Lcdsadv\*O command starts the advertisement and solicitation daemon on the local system and then starts clerks as needed by applications. Use this command only when troubleshooting because it creates and automatically starts the CDS clerk whenever the host system is rebooted. .LI "o" The \*Lcdsd\*O command restarts the CDS server. Use this command only when troubleshooting because it starts the CDS server process automatically whenever the host system is rebooted. .LI "o" The \*Lgdad\*O command starts the GDA (Global Directory Agent) daemon. The GDA enables intercell communication, serving as a connection to other cells through the global naming environment. The GDA is typically started automatically by scripts that execute as part of normal system start-up and shutdown procedures. .LE .SH "RELATED INFORMATION" .PP Book: \*VDCE Administration Guide\*O .PP Commands: .aZ "def,10220,R1.1,Remove reference to rpcd and sec_clientd" \*Lcdsadv(1m)\*O, \*Lcdsbrowser(1m)\*O, \*Lcdscp(1m)\*O, \*Lcdsd(1m)\*O, \*Lgdad(1m)\*O, \*Ldced(1m)\*O .zZ "def,10220,R1.1,Remove reference to rpcd and sec_clientd" .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed. Dec 11, 1991 Update file submission for ...\" V 1.0 final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "cdsadv"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lcdscp\*O commands" "\*Lcdsadv\*O" .iX "-[" "CDS servers" "solicitation daemon startup" .iX "-[" "CDS clerks" "solicitation daemon startup" .SH NAME .PP \*Lcdsadv\*O - Starts the CDS client daemon .wH "" .SH "SYNOPSIS" .zA "edit,10578,R1.1,Revised list of arguments" .PP \*Lcdsadv\*O [\*L-c\*O] [\*L-D\*O] [\*L-s\*O] [\*L-w \*Eroute\*O] .wH "" .SH "ARGUMENTS" .VL .LI "\*L-c\*O" Specifies cache size in kilobytes. Changing cache sizes causes previously cached information to be discarded, including information about cached servers, so use of this option may necessitate defining a new cached server. .LI "\*L-D\*O" For debugging use only. Causes the \*Lcdsadv\*O process not to fork. .LI "\*L-s\*O" Causes the \*Lcdsadv\*O not to send or receive advertisements. This argument can be used for diagnostic work involving multiple servers on the same local area network to limit access to those servers identified with the \*Ldefine cached server\*O command. .LI "\*L-w \*Eroute\*O" Routes serviceability messages. .wH "" .LE .zZ "edit,10578,R1.1,Revised list of arguments" .SH "DESCRIPTION" .PP The \*Lcdsadv\*O command starts the CDS client daemon. .SS "Privilege Required" You must log in as superuser (root). .SH "NOTES" .PP This command is ordinarily executed by a DCE configuration or startup script. You should use this command interactively only when \*Lcdsadv\*O fails to start automatically after a reboot, or if you want to restart \*Lcdsadv\*O after disabling it to perform a backup or to do diagnostic work on the host system. .SH "EXAMPLE" .PP To restart \*Lcdsadv\*O, follow these steps: .AL .LI Log in to the clerk system as superuser (root). .LI Verify that the \*Ldced\*O process is running. .LI Enter the following command to restart the \*Lcdsadv\*O process: .PP .iS \*C# \*Lcdsadv .iE .LE .wH "" .SH "RELATED INFORMATION" .PP Books: \*VOSF DCE Administration Guide\*O .iX "-]" "\*Lcdscp\*O commands" "\*Lcdsadv\*O" .iX "-]" "CDS clerks" "solicitation daemon startup" .iX "-]" "CDS servers" "solicitation daemon startup" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .nr H1 1 .wH "" ...\" .rm zA .rm zZ .TH "cdsbrowser"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lcdscp\*O commands" "\*Lcdsbrowser\*O" .iX "Browser" "startup command" .SH NAME .PP \*Lcdsbrowser\*O - Starts the CDS Browser utility on the local system .wH "" .SH "SYNOPSIS" .PP \*Lcdsbrowser\*O .wH "" .SH "DESCRIPTION" .PP The \*Lcdsbrowser\*O command starts the CDS Browser utility on the local system. This utility runs on workstations with windowing software based on the OSF/Motif\(tm graphical user interface. Using a mouse to manipulate pull-down menus, you can view the directory structure of a namespace, view child directories of a particular directory, view the object entries and soft links in a directory, and set a filter to display only object entries of a particular class. (For users who do not have windowing software, similar functions are available with the control program.) .zA "enh,4200,R1.0.2, Added confidence level" When you use the CDS Browser, it sets the confidence level of clerk calls to low. .zZ "enh,4200,R1.0.2, Added confidence level" .SS "Privilege Required" None .SH "EXAMPLE" .PP The following command starts the CDS Browser utility on the local system: .iS \*C$\*L cdsbrowser\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Books: \*VOSF DCE Administration Guide\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed. Dec 11, 1991 Update file submission for ...\" V 1.0 final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "cdsclerk"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lcdscp\*O commands" "\*Lcdsclerk\*O" .iX "-[" "CDS clerks" "managing interface to servers" .SH NAME .PP \*Lcdsclerk\*O - Manages the interface between clients and the CDS server .wH "" .SH "SYNOPSIS" .zA "edit,10578,R1.1,Revised list of arguments" .PP \*Lcdsclerk\*O [\*L-D\*O] [\*L-w \*Eroute\*O] .wH "" .SH "OPTIONS" .VL .LI "\*L-D\*O" For debugging use only. Causes the \*Lcdsadv\*O clerk process not to fork. .LI "\*L-w \*Eroute\*O" Routes serviceability messages. .wH "" .LE .zZ "edit,10578,R1.1,Revised list of arguments" .SH "DESCRIPTION" .PP The \*Lcdsclerk\*O command manages the interface between clients and the CDS server. .SS "Privilege Required" You must log in as superuser (root). .SH "NOTES" .PP This command is used by the advertiser on the system where the CDS clerk is running. You should use this command interactively only to do diagnostic work on the host system. ...\" .PP ...\" Use this command only when troubleshooting. .wH "" .SH "EXAMPLE" .PP Before you run the following process, make sure that other clerks are not running. To start the \*Lcdsclerk\*O process, follow these steps: .PP .AL .uS .LI Make sure that a CDS server is already running somewhere within the cell. .LI Log in to the system as superuser (root). .LI Log in to DCE as the machine principal of the local host. Enter the principal name in the format \*L/hosts/\*O\*Ehostname\*O\*L/self\*O as shown in the following example command for a host named \*Lorion\*O whose password is \*Lsmith\*O: .iS \*C# \*Ldce_login hosts/orion/self smith .iE .LI .zA "def,10220,R1.1,Remove reference to rpcd and sec_clientd" Enter the following command to see if the \*Ldced\*O process is already running: .iS \*C# \*Lps .iE .PP If the \*Ldced\*O process appears on the list of active processes, proceed to step 5. If the \*Ldced\*O process does not appear on the list of active processes, enter the following command to start the process: .iS \*C# \*Ldced .iE .zZ "def,10220,R1.1,Remove reference to rpcd and sec_clientd" .LI Enter the following command to start the \*Lcdsadv\*O process: .iS \*C# \*Lcdsadv .iE .LI Enter the following command with the appropriate arguments to start the \*Lcdsclerk\*O process: .iS \*C# \*Lcdsclerk\*O .iE .LE .wH "" .SH "RELATED INFORMATION" .PP Books: \*VOSF DCE Administration Guide\*O .iX "-]" "\*Lcdscp\*O commands" "\*Lcdsclerk\*O" .iX "-]" "CDS clerks" "managing interface to servers" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .nr H1 1 .wH "" ...\" .rm zA .rm zZ .TH "cdscp"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lcdscp\*O command" .iX "-[" "\*Lcdscp\*O commands" "summary" .SH NAME .PP \*Lcdscp\*O - Starts the CDS control program .wH "" .SH "SYNOPSIS" .sS \*Lcdscp \*O [\*Vcdscp-command\*O] .sE .SH "ARGUMENTS" .VL .LI "\*Vcdscp-command\*O" Optionally, specifies one of the following control commands: .VL .LI "\*Ladd directory\*O" Adds a value to a modifiable, set-valued attribute (including application-defined attributes) of a directory .LI "\*Ladd object\*O" Adds a value to a modifiable, set-valued attribute (including application-defined attributes) of an object entry .LI "\*Lclear cached server\*O" Removes knowledge of a server that you had specifically defined from the local clerk's cache .LI "\*Lclear clearinghouse\*O" Removes knowledge of the specified clearinghouse from the server's memory .LI "\*Lcreate child\*O" Creates a child pointer at the master replica of the parent directory .zA "defect 6204,R1.0.2, fixed typo" .LI "\*Lcreate clearinghouse\*O" .zZ "defect 6204,R1.0.2, fixed typo" Creates a clearinghouse on the local server system or makes an existing clearinghouse available .LI "\*Lcreate directory\*O" Creates a directory .LI "\*Lcreate link\*O" Creates a soft link and optionally specifies an expiration time and an extension time .LI "\*Lcreate object\*O" Creates a new object entry .LI "\*Lcreate replica\*O" Creates a replica of an existing directory in the specified clearinghouse .LI "\*Ldefine cached server\*O" Creates knowledge of a server in the local clerk's cache .LI "\*Ldelete child\*O" Deletes a child pointer from the namespace .LI "\*Ldelete clearinghouse\*O" Deletes the specified clearinghouse from the local server system .LI "\*Ldelete directory\*O" Deletes a directory .LI "\*Ldelete link\*O" Deletes a soft link .LI "\*Ldelete object\*O" Deletes an object entry .LI "\*Ldelete replica\*O" Deletes a read-only replica of a directory from a clearinghouse .LI "\*Ldisable clerk\*O" Stops the clerk on the local system .LI "\*Ldisable server\*O" Stops the server on the local system .LI "\*Ldump clerk cache\*O" Displays the contents of the clerk cache .LI "\*Lhelp\*O" Displays a list of the CDS control program commands .LI "\*Llist child\*O" Displays a list of all the child pointers whose names match the specified child name .LI "\*Llist clearinghouse\*O" Displays a list of all the clearinghouses whose names match the specified clearinghouse name .LI "\*Llist directory\*O" Displays a list of all the directories whose names match the specified directory name .LI "\*Llist link\*O" Displays a list of all the soft links whose names match the specified link name .LI "\*Llist object\*O" Displays a list of all the object entries (including clearinghouse object entries) whose names match the specified object entry name .LI "\*Lremove directory\*O" Removes a value from a set-valued or single-valued attribute (including application-defined attributes) of a directory .LI "\*Lremove link\*O" Removes a soft link's timeout value attribute .LI "\*Lremove object\*O" Removes a value from a set-valued or single-valued attribute (including application-defined attributes) of an object entry .LI "\*Lset cdscp confidence\*O" Sets the confidence level of clerk calls issued as a result of CDS control program commands .LI "\*Lset cdscp preferred clearinghouse\*O" Specifies a preferred clearinghouse to use for satisfying read requests that result from CDS control program commands .LI "\*Lset directory\*O" Changes the value of a modifiable, single-valued attribute of a directory .LI "\*Lset directory to new epoch\*O" Reconstructs a directory's replica set, allowing you to designate a new master replica or to exclude a replica .LI "\*Lset directory to skulk\*O" Starts the skulk of a directory immediately .LI "\*Lset link\*O" Changes the value of a modifiable, single-valued attribute of a soft link .LI "\*Lset object\*O" Changes the value of a modifiable, single-valued attribute of an object entry .LI "\*Lshow cached clearinghouse\*O" Displays current information about the specified cached clearinghouse .LI "\*Lshow cached server\*O" Displays address information of a server in the local clerk's cache .LI "\*Lshow cdscp confidence\*O" Displays the current confidence level of clerk calls resulting from CDS control program commands .LI "\*Lshow cdscp preferred clearinghouse\*O" Displays the preferred clearinghouse for satisfying read requests that result from CDS control program commands .LI "\*Lshow cell\*O" Displays the information you need to create a cell entry in either DNS or GDS .LI "\*Lshow child\*O" Displays attribute information about the specified child pointer .LI "\*Lshow clearinghouse\*O" Displays attribute information about the specified clearinghouse .LI "\*Lshow clerk\*O" Displays attribute information about the CDS clerk on the local system .LI "\*Lshow directory\*O" Displays attribute information about the specified directory .LI "\*Lshow link\*O" Displays attribute information about the specified soft link .LI "\*Lshow object\*O" Displays attribute information about the specified object entry .LI "\*Lshow replica\*O" Displays attribute information about the specified replica .LI "\*Lshow server\*O" Displays attribute information about the server running on the local system .iX "-]" "\*Lcdscp\*O commands" "summary" .LE .LE .zA "defect, 11818, R1.1, Added caveat" .SH "NOTES" With the exception of the following subcommands, this command is replaced at Revision 1.1 by the \*Ldcecp\*O command. This command may be fully replaced by the \*Ldcecp\*O command in a future release of DCE, and may no longer be supported at that time. .P .ML .LI \*Ldisable clerk\*O .LI \*Ldisable server\*O .LI \*Lhelp\*O .LI \*Lset cdscp confidence\*O .LI \*Lset directory to new epoch\*O .LI \*Lshow cdscp confidence\*O .LI \*Lshow cell\*O .LI \*Lshow clerk\*O .LI \*Lshow server\*O .LE .zZ "defect, 11818, R1.1, Added caveat" .SH "DESCRIPTION" .P The Cell Directory Service (CDS) control program is a command line interface for managing the components of the Cell Directory Service and the contents of the namespace. .P You can use the control program commands from within the control program or from the system prompt. To use the control program commands from inside the control program, start the control program by using the \*Lcdscp\*O command alone, without any argument. This enters the control program, which displays the control program prompt (\*Ccdscp>\*O): .iS \*C$ \*Lcdscp \*O \*Ccdscp>\*O .iE .P At this prompt, you can enter any control program command; for example: .iS \*Ccdscp> \*Lshow server\*O .iE .P Use the command \*Ldo\*O \*Vfilename\*O from inside the control program to read a file of commands. .P To leave the control program and return to the system prompt, use the \*Lquit\*O command. To use the control program commands from the system prompt, enter the \*Lcdscp\*O command with an internal command of the CDS control program as the first argument. The control program executes the command immediately, without displaying the control program prompt. For example, you can enter the \*Lshow server\*O command as follows: .iS \*C$ \*Lcdscp show server\*O .iE .SS "Elements of a CDS Command" .iX "-[" "\*Lcdscp\*O commands" "syntax" All CDS control program commands must include a verb, an entity name, and all required arguments. Depending on the command, you can also specify optional arguments and attributes. A space must separate more than one attribute or argument. A space must precede and follow an equal sign (=). .SS "Verbs" .PP The following is a list of the definitions of verbs used in control program commands: .VL .LI "\*Ladd\*O" Adds a value to a modifiable, set-valued attribute .LI "\*Lclear\*O" Removes knowledge of a cached clearinghouse or cached server from memory .LI "\*Lcreate\*O" Creates an entity .LI "\*Ldefine\*O" Creates knowledge of a locally cached server .LI "\*Ldelete\*O" Deletes an entity .LI "\*Ldisable\*O" Stops operation of a clerk or server .LI "\*Ldump\*O" Displays the contents of a clerk cache .LI "\*Llist\*O" Displays a list of specified entity names .LI "\*Lremove\*O" Removes a value from a set-valued or single-valued attribute .LI "\*Lset\*O" Changes the value of a modifiable, single-valued attribute .LI "\*Lshow\*O" Displays attribute information .LE .SS "Entity Names" .iX "entities" "about" .PP Any individually manageable piece of CDS is called an entity. A set of commands exists for each entity. The following is a list of the entities and a description of what each entity represents: .VL .LI "\*LCached Clearinghouse\*O" A cached clearinghouse is a clearinghouse that a clerk has discovered and cached. A clerk can learn about clearinghouses as a result of configuration information, advertisements received on a LAN, or during the process of finding a name. .LI "\*LCached Server\*O" A cached server is a server that a clerk has cached as a result of manual configuration through the control program. .LI "\*LChild\*O" A child pointer connects a parent and child directory in a hierarchical namespace. The child pointer is stored in the parent directory and has the same name as the child directory. .LI "\*LClearinghouse\*O" A clearinghouse is a database containing a collection of directory replicas at a particular server. .LI "\*LClerk\*O" The clerk is the interface between client applications and servers. .LI "\*LDirectory\*O" A directory contains child, object, and link entries that are logically stored under one name (the directory name). .LI "\*LLink\*O" A soft link is a pointer providing an alternate name for an object entry, directory, or other soft link. .LI "\*LObject\*O" An object entry represents a resource (for example, an application) that is named in the namespace. .LI "\*LReplica\*O" A replica is a copy of a directory. Each copy, including the original or master, is referred to as a replica. .LI "\*LServer\*O" A server handles lookup requests from clerks and maintains the contents of the clearinghouse or clearinghouses at its node. .LE .SS "Attributes" .PP Every CDS entity has attributes, which are pieces or sets of data associated with that entity. Attributes can reflect or affect the operational behavior of an entity, record the number of times a particular event or problem occurred since the entity was last enabled, and uniquely distinguish an entity from any other entity. Some attributes have a single value; others contain a set of values. .PP CDS attributes are identified by ISO object identifiers (OIDs). Every CDS attribute name maps to an OID and a corresponding data type. Usually, client applications define the name of an attribute and its data type. Application programmers should never need to modify (except for the purpose of foreign language translation) the existing CDS labels associated with the unique OIDs in the \*Lcds_attributes\*O file. However, programmers can obtain new OIDs from the appropriate allocation authority, create new attributes for their own object entries, and then append them to the existing list. The OID and data type of each attribute are stored in the file \*L/opt/dcelocal/etc/cds_attributes\*O. Descriptions of the CDS data types that applications can use are in the \*Lcdsclerk.h\*O file. .zA "def,CR8032,Add info re: showing multiple attrib values" .PP All entities have \*Lshow\*O commands that you can use to display the names and values of specific attributes or all attributes. When you display an attribute that has more than one value, the \*Lshow\*O command lists each value for the attribute separately. When there are multiple values for an attribute, the command first lists the attribute name on a line ending with a colon, then the parts of the value. .zZ "def,CR8032,Add info re: showing multiple attrib values" .PP For more information about CDS attributes, see the \*VDCE Directory Service\*O module in the \*VDCE Administration Guide\*O. .iX "-]" "\*Lcdscp\*O commands" "syntax" .SS "Editing the Commands" .PP You can abbreviate commands, continue a command beyond one line, or redirect output to a file within the control program. .PP To abbreviate any command name, type only the first four characters. You can abbreviate a command name to fewer than four characters as long as the abbreviated name remains unique among all command names in the control program. For example, the following commands are equivalent: .iS \*Ccdscp> \*Lshow directory /.:/sales\*O \*Ccdscp> \*Lsh dir /.:/sales\*O .iE .PP To continue a long command line onto the next line, type a space and then a \\ (backslash) at the end of the first line, for example: .iS \*Ccdscp> \*Lset link /.:/sales CDS_LinkTimeout \\ \*C> \*L(1991-12-31-12:00:00 090-00:00:00)\*O .iE .PP To add a comment, use the \*L#\*O (number sign). Everything following the \*L#\*O character on a line is ignored. .PP To redirect output to a file, most UNIX shell users can type \*L>\*O\*Vfilename\*O at the shell prompt. To redirect output of error text to a file, most UNIX shell users can type \*L>&\*Vfilename\*O at the shell prompt. .PP For example, the following command redirects the display produced by the \*Lshow directory\*O command to a new text file named \*Ldirectory_names\*O: .iS \*C$ \*Lcdscp show directory /.:/* >directory_names\*O\*O .iE .SS "Using Wildcard Characters" .PP When entering a name in \*Lshow\*O and \*Llist\*O commands, you can use wildcard characters in the rightmost simple name (the name to the right of the last slash (\*L/\*O) in the full pathname). The asterisk (*) matches 0 or more characters in a simple name. The question mark (?) matches exactly one character in a simple name. .PP When you use an asterisk or a question mark as a normal character in the rightmost simple name of a \*Lshow\*O or \*Llist\*O command, escape it with a backslash (\\* or \\?). Otherwise, the character is interpreted as a wildcard. .PP You cannot use wildcard characters in \*Lshow clerk\*O and \*Lshow server\*O commands. .SS "Privilege Required" .H 2 "DCE Permissions Supported by CDS" CDS supports the following DCE permissions: read (\*Lr\*O), write (\*Lw\*O), insert (\*Li\*O), delete (\*Ld\*O), test (\*Lt\*O), control (\*Lc\*O), and administer (\*La\*O). Each permission has a slightly different meaning, depending on the kind of CDS name with which it is associated. In general, the permissions are defined as follows: .VL .LI "\*LRead\*O" Allows a principal to look up a name and view the attribute values associated with it. .LI "\*LWrite\*O " Permission allows a principal to change the modifiable attributes associated with a name, except the name's access control list (ACL) entries. .LI "\*LInsert\*O " Permission (for use with directory entries only) allows a principal to create new names in a directory. .LI "\*LDelete\*O" Permission allows a principal to delete a name from the namespace. .LI "\*LTest\*O" Permission allows a principal to test whether an attribute of a name has a particular value without being able to actually see any of the values (that is, without having read permission to the name). .P Test permission provides application programs a more efficient way to verify a CDS attribute value. Rather than reading an entire set of values, an application can test for the presence of a particular value. ...\" ...\" .zA "defect,6779,R1.0.2,read permission needed to change ACLs" ...\" .LI "\*LControl\*O" Permission allows a principal to modify the ACL entries associated with a name. (Note that \*Lread\*O permission is also necessary for modifying a CDS entry's ACLs; otherwise, \*Lacl_edit\*O will not be able to bind to the entry.) Control permission is automatically granted to the creator of a CDS name. ...\" .zZ "defect,6779,R1.0.2,read permission needed to change ACLs" ...\" ...\" .LI "\*LAdminister\*O" Permission (for use with directory entries only) allows a principal to issue CDS control program commands that control the replication of directories. .LE .PP The creator of a name is automatically granted all permissions appropriate for the type of name created. For example, a principal creating an object entry is granted read, write, delete, test, and control permission to the object entry. A principal creating a directory is granted read, write, insert, delete, test, control, and administer permission to the directory. .SH "EXAMPLES" The following command starts the CDS control program: .iS \*C$ \*Lcdscp\*O \*Ccdscp>\*O .iE .P The following command operates from the system prompt to display the attributes of the CDS clerk on the local system: .iS \*C$ \*Lcdscp show clerk\*O .iE .SH "RELATED INFORMATION" .PP Books: \*VOSF DCE Administration Guide\*O ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed. Dec 11, 1991 Update file submission for ...\" V 1.0 final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "cdsd"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "CDS servers" "restarting" .iX "-[" "\*Lcdsd\*O command" .SH NAME .PP \*Lcdsd\*O - Starts the CDS server .wH "" .SH "SYNOPSIS" .zA "edit,10578,R1.1,Revised list of arguments" .zA "enh,11348,R1.1,Added -l option" .PP \*Lcdsd\*O [\*L-a\*O] [\*L-D\*O] [\*L-l \*Eprincipal\*O] [\*L-w \*Eroute\*O] .wH "" .SH "ARGUMENTS" .VL .LI "\*L-a\*O" Creates a new namespace if there is not an existing namespace. This flag is meaningful only when the cell is first configured (that is, the initial creation of the namespace). .LI "\*L-D\*O" For debugging use only. Causes the \*Lcdsd\*O process not to fork. .LI "\*L-l \*Eprincipal\*O" Locksmith mode. Allows the principal specified to have full access to all information stored with this server. .zZ "enh,11348,R1.1,Added -l option" .LI "\*L-w \*Eroute\*O" Routes serviceability messages. .LE .wH "" .zZ "edit,10578,R1.1,Revised list of arguments" .SH "DESCRIPTION" .PP The \*Lcdsd\*O command starts the CDS server. .SS "Privilege Required" You must log in as superuser (root). .SH "NOTES" .PP This command is ordinarily executed by a DCE configuration or startup script. You should use this command interactively only when a \*Lcdsd\*O fails to start automatically after a reboot, or if you want to restart a \*Lcdsd\*O after disabling it to perform a backup or to do diagnostic work on the host system. .SH "EXAMPLE" .PP To restart a \*Lcdsd\*O server, follow these steps: .AL .LI Log in to the server system as superuser (root). .LI Verify that the \*Ldced\*O and \*Lcdsadv\*O processes are running. .LI Enter the following command to restart the CDS server: .iS \*C# \*Lcdsd .iE .LE .PP When the server process starts, it starts all clearinghouses on the system. .wH "" .SH "RELATED INFORMATION" .PP Books: \*VOSF DCE Administration Guide\*O .wH "" .wH "" .iX "-]" "CDS servers" "restarting" .iX "-]" "\*Lcdsd\*O command" .\"========================================================= .\" (c) 1992 Hewlett-Packard Company. All Rights Reserved. .\" Author: Alex Mastin, Hewlett-Packard NSD .\"========================================================= .\" .\"@(#) $Header: cfl.1m,v 1.5 96/04/04 11:32:04 hmgr Exp $ .TA c .TH cfl 1m .SH NAME cfl \- configure a logical unit (LUN) on a SCSI disk array .SH SYNOPSIS .HP .C cfl .RC [ -L .IR LUN_address ] [\|\f4-a -c\f2list\|\f1[\f4,\f2list\|\f1] .RC [ -i ]\|] .RC [ -b .IR block_size ] [\|\f4-c\|\f2list\|\f1[\f4,\f2list\|\f1]] .RC [ -d ] .RC [ -f .IR flag_word ] .if t .br .RC [ -k .IR num_log_blocks ] .RC [ -l .IR sec_tenths ] .RC [ -n .IR num_log_blocks ] .RC [ -p .IR list ] .RC [ -r .IR RAID_level ] .if t .br .RC [ -s .IR num_log_blocks ] .if n .br .RC [ -t .CR reg | sub ] .RC [ -z .IR num_log_blocks ] .I device_file .RE .PP Where .I list is a comma-separated drive list (\c .CI c X i Y\c ,\c .CI c X i Y\c ,...) describing drives on .SM SCSI channel .IR X , and .SM SCSI ID .I Y (where .I X and .I Y are decimal numbers). Multiple .I lists are delimited by space characters. .SH DESCRIPTION .C cfl sets configuration parameters, and changes the status of a .SM LUN on the .SM HP SCSI disk array associated with .IR device_file . .PP .B NOTE: .CR newarray , a front-end program for .CR cfl , is recommended for doing array configuration (see .CR newarray (1M)). .SS Options .PP .TP 15 .CI -L " LUN_address" Specifies which .SM SCSI unit address to affect. .TP \f4-a -c \f2list \f1[\f4,\f2list \f1] [ \f4-i \f1] Add a .SM LUN to the set of .SM LUN\c s known by the controller. If this option is used, the runstring must also contain a value for the .C -c parameter, and can contain values for all other applicable parameters except .C -d (the delete .SM LUN option). If only the .C -c parameter is supplied, a default .SM RAID\c -level 0 configuration is created with the drives specified in the parameter list. The user may thus specify all the .SM LUN characteristics in one line; create a default configuration and change a few of the parameters to desired values in one line, or create a default configuration and iteratively change its parameters to the desired values. The .C -i option formats the newly added .SM LUN after configuration. If multiple .SM LUN\c s are to be added and configured, each .SM LUN must be formatted before any other LUNs can be added and configured. .TP .CI -b " block_size " Set the logical block size of the .SM LUN. .I block_size is specified in bytes. .TP \f4-c \f2list \f1[\|\f4,\f2list\f12] \f2device_file\f1 Assign to the .SM LUN a configuration table that describes which drives are associated with the .SM LUN and specifies the order each drive appears in a data stripe. One, or more tables can be assigned to each .SM LUN\c , depending on the .SM RAID level. Each table can have a maximum of five drives. .TP .CI -d Delete the .SM LUN from the set of .SM LUN\c s known by the controller. This option cannot be used simultaneously with the .C -a option. .TP .CI -f " flag_word" Assign the desired hexadecimal values, given in .IR flag_word , to the array's two .SM LUN flag bytes. The default .I flag_word is hex .CR 0072 . User-changeable bits are in Mode Page 0x2b byte 25 (the lsb): bit 4, which enables .SM AEN polling when set; bit 5, which enables parity verification when set, and bit 6, which enables writes with parity verification when set. .TP .CI -k " num_log_blocks" Set the reconstruction quantity in blocks. This represents the number of blocks reconstructed in a single reconstruction command. Reconstruction commands are issued at an adjustable interval until the .SM LUN is reconstructed (see the .C -l option). .TP .CI -l " sec_tenths" Set the reconstruction frequency, the interval between successive reconstruction commands. It is expressed in tenths of a second. .TP .CI -n " num_log_blocks" Set the number of logical blocks in the .SM LUN. .TP .CI -p " list" Create the .SM LUN's disk bit map, which describes the drives associated with the .SM LUN. Either a configuration table or a disk bit map, but not both, is required to configure a .SM LUN\c ; use of the configuration table is recommended. .TP .CI -r " raid_level" Set the .SM RAID level of the .SM LUN\c ; valid .SM RAID levels are 0, 1, 3 and 5. .TP .CI -s " num_log_blocks" Set the number of blocks in a .SM LUN segment, the part of a data stripe residing on a single disk. .TP \f4 -t reg \f1|\f4 sub\f1 Set the .SM LUN type, regular or sub-\c .SM LUN. A sub-\c .SM LUN is a .SM LUN that can share its physical drive(s) with another .SM LUN\c ; usually, its data resides on more than one drive. Configurations involving data striping or mirroring should use sub-\c .SM LUN\c s. .TP .CI -z " num_log_blocks" Set the number of blocks in the first segment of the .SM LUN. .SH RETURN VALUE .C cfl returns the following values: .RS 5 .TP .B " 0" Successful completion. .PD 0 .TP .B -1 Command failed (an error occurred). .PD .PP .RE .SH DIAGNOSTICS AND ERRORS Errors can originate from problems with: .RS .TP 3 \(bu .C cfl .TP \(bu .SM SCSI (device level) communications .TP \(bu system calls .RE All error information is printed to stderr. .PP .SS Error messages generated by cfl: .PD 0 .TP .C "usage: cfl -L -a <-c ...> [-i] add LUN" .HP .C " cfl -L -b set logical block size" .HP .C " cfl -L -c < | none> build config table(s)" .HP .C " cfl -L -d delete LUN" .HP .C " cfl -L -f set LUN flags" .HP .C " cfl -L -k set reconstruction amt in blocks" .HP .C " cfl -L -l set reconstruction frequency" .HP .C " cfl -L -n set number of blocks in LUN" .HP .C " cfl -L -p build disk bit map" .HP .C " cfl -L -r set RAID level" .HP .C " cfl -L -s set segment size in blocks" .HP .C " cfl -L -t set LUN type" .HP .C " cfl -L -z set segment 0 size in blocks" .PD .HP An error in command syntax has occurred. No valid tags were present, or an illegal tag was encountered. Re-enter the command with all required arguments. If a syntax error occurs in a runstring with a legal tag, only the template for that tag will be displayed. .TP .C "cfl: Arg incompatible with other" One of the arguments is incompatible with another, for example, when the .C \-a (add .SM LUN\c ) and .C \-d (delete .SM LUN\c ) are both on the command line. .TP .C "cfl: Arg out of range" One of the arguments is larger than its allowed maximum value (or smaller than its allowed minimum value), or is incorrect in form. Check the size, and form of each argument and make appropriate corrections. .TP .C "cfl: device busy" .tr ~" To ensure that .C cfl does not modify a disk array that is being used by another process, .C cfl attempts to obtain exclusive access to the disk array. If the disk array is already opened by another process (for example, LVM \(em the Logical Volume Manager), a .RC ~ "device busy" ~ error message is returned by the driver. To eliminate the .RC ~ "device busy" ~ condition, determine what process has the device open. In the case of LVM, it is necessary to deactivate the volume group containing the array before configuring the array (see .CR vgchange (1M)). .tr ~~ .TP .C "cfl: LUN does not exist" The addressed .SM LUN is not known to the array controller. Only the .C \-a option can operate on an unconfigured .SM LUN. The .C \-d option ignores references unconfigured .SM LUN\c s (and does nothing with them). .TP .C "cfl: LUN # too big" The .SM LUN number, which is derived from the device special file name, is out of range. .TP .C "cfl: Multiple args of same type" An argument occurs more than once on the command line. .TP .C "cfl: Not a disk array" The device being addressed did not identify itself as a .SM SCSI disk array product that is supported by .CR cfl . .TP .C "cfl: Not a raw file" .C cfl must be able to open the device file for raw access (the character device file). .TP .C "cfl: Transfer length error" The amount of data actually sent to or received from the device was not the expected amount. .SS SCSI (device level) communication errors: Sense data associated with the failed operation is printed. .SS Error messages generated by system calls: .C cfl uses the following system calls: .IP .CR malloc() , .CR free() , .CR stat() , .CR open() , .CR close() , .CR read() , .CR write() , and .CR ioctl() . .PP Documentation for these .SM HP-UX system calls contains information about the specific error conditions associated with each call. .C cfl does not alter the value of .CR errno . The interpretation of .C errno for printing purposes is performed by the system utility .CR strerror() . .SH EXAMPLES .PP To delete .SM LUN 5 associated with .CR /dev/rdsk/c2t0d0 : .IP .C "cfl -L 5 -d /dev/rdsk/c2t0d0" .PP .RE To add the .SM LUN 0 associated with .CR /dev/rdsk/c2t0d0 , which will have the following characteristics: logical block size 512 bytes, .SM RAID level of 5, auto reconstruct disabled, reconstruction amount of 64 blocks, reconstruction frequency of .2 seconds, segment size of 64 blocks, type sub-\c .SM LUN, segment zero size of 1, and drives with .SM SCSI ID 1 on channels 1 through 5, to be striped in the channel order 3, 5, 1, 2 and 4: .PD 0 .IP .C "cfl -L 0 -a -b 512 -r 5 -f 0072 -k 64 -l 2 -n 123456 -s 64" .IP .C " -t sub -z 1 -c c3i1,c5i1,c1i1,c2i1,c4i1 /dev/rdsk/c2t0d0" .PP .PD .SH WARNING Changing any configuration parameter except the reconstruction frequency and reconstruction quantity puts the affected .SM LUN in an unusable ("dead") state. You must reformat the .SM LUN before it can be used with the new configuration values. Formatting a .SM LUN destroys all of its user data. .SH DEPENDENCIES The HP C2425 and HP C2427 disk arrays are only supported on Series 700 systems running HP-UX version 9.0X. .PP The HP C2430 disk array is supported on Series 700 and 800 systems running HP-UX versions 9.0X and 10.0X. .SH AUTHOR .PP .C cfl was developed by HP. .SH SEE ALSO newarray(1M), arraytab(4), vgchange(1M) .\" .\" index@\f4cfl\f1 \- configure a \s-1SCSI\s+1 disk array \s-1LUN\s+1@@@\f3cfl(1M)\f1 .\" index@disk array, configure a logical unit (\s-1LUN\s+1)@@@\f3cfl(1M)\f1 .\" .\" toc@\f3cfl(1M)\f1:\0\0\f4cfl\f1@@@configure a \s-1SCSI\s+1 disk array \s-1LUN\s+1 .\" .\" fileset_database@cfl.1m SYS-ADMIN-MAN .\" $Header: ch_rc.1m,v 72.2 94/09/08 14:51:27 ssa Exp $ .TA c .TH ch_rc 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ch_rc \- change system configuration file .SH SYNOPSIS .C /usr/sbin/ch_rc .CR -a | -r | -l .RC [ -v ] .RC [ -A ] .RC [ -R .IR root ] .RC [ -p .RI { parameter | parameter=value }...] .RI [ \|file\| ...] .SH DESCRIPTION .CR ch_rc manages the addition, modification, removal, and retrieval of information stored in files having the format of those in the .CR /etc/rc.config.d directory. .PP Parameter names are treated as strings. Thus, .CR X[0] has no special meaning to .CR ch_rc in relation to other parameters named .CR X[1] or X \|. .SS Options .RS .TP 10 .I file Specify the file(s) to be used as the configuration database. If no file is specified, the set of files used by .CR ch_rc defaults to .CR /etc/TIMEZONE and all files in the .CR /etc/rc.config.d directory. .IP Modification and deletion of configuration parameters occurs in the file where the parameter is found. .TP .C -a Add or modify a parameter definition. For each parameter specified on the command line, if the parameter is found in the specified (or default) files, it is modified to reflect the specified value. If the parameter is not found, it is added to the specified file(s). .IP If a new parameter is being defined, one or more files must be specified on the command line; the specified files are those in which the parameter will be defined. .TP .C -r Remove a parameter definition. For each parameter name specified on the command line, remove any occurrence of that parameter from the specified file(s). .TP .C -l List configuration values. For each parameter specified on the command line, output every definition of the parameter from the specified file(s). Output consists of only the values, one per line. .TP .C -p Specify a parameter name or name/value pair. If a name and value is expected, but only a name is specified, the value will be set to the empty string. For example, specifying .C FOO or .C FOO= will result in .C "FOO" and .C "FOO=" respectively. .IP Due to shell quoting rules, if you need a quoted parameter value, you must protect the quotes from the shell. For example, .nf .RS .IP .C ch_rc -a -p VALUE="a b c" .fi .RE .IP yields: .nf .RS .IP .C "VALUE=a b c" .fi .RE .IP which is an error, whereas, .nf .RS .IP .C ch_rc -a -p VALUE='"a b c"' .fi .RE .IP yields: .nf .RS .IP .C VALUE="a b c" .fi .RE .TP .C -v Verbose. When used with the .C -l option, the .C -v option causes a verbose listing to be output. This listing includes a filename followed by the entire line containing the specified parameter for each occurrance of the parameter. .TP .C -A The .C -A option is used to list all occurances of array parameters matching the parameters specified on the command line. .IP For example, .nf .RS .IP .C ch_rc -l -A -v -p ZZZ file .fi .RE .IP may emit the following output: .nf .IP .RS .RS .C file: ZZZ[0]=zero .C file: ZZZ[5]=five .C file: ZZZ[9]=fred .fi .RE .RE .TP .CI -R \0root Normally, the files specified on the command line are used as specified. By specifying a .I root directory with the .C -R option, all files (including the default files if none are specified) will be interpreted relative to .IR root . .IP For example, if .I root is specified as .CR /foo and .CR /etc/TIMEZONE is specified on the command line, it will be interpreted as .CR /foo/etc/TIMEZONE . .RE .SH RETURN VALUE .C ch_rc exits with one of the following values: .RS .TP 5 0 add/delete/list successful .TP 1 command line syntax/usage error .TP 2 can not access one or more of the listed (or default) files .TP 3 can not open/create/write file .TP 4 memory error .TP 5 no files specified on command line for add option .RE .SH EXAMPLES Files in the .CR /etc/rc.config.d directory have the following format: .nf .IP .C "# Comments are preceded by pound signs and" .C "# are always on a line of their own." .C "# Blank lines are allowed." .IP .C "VARIABLE=value" .C "VARIABLE_2=value2" .C "VARIABLE_3[1]=value3" .C "VARIABLE_3[2]=value4" .IP .C "# All parameters are defined on a single line" .C "# Parameters must not be exported" .fi .SH WARNINGS .CR ch_rc does not interpret configuration files; it only does pattern matching. As a result, if comments appear on lines containing parameter definitions, the comments will also appear in output when using the .C -l option. .PP .C ch_rc cannot parse multiple parameter definitions which occur on the same line of a file. .SH AUTHOR .C ch_rc was developed by HP. .SH FILES .TP 20 /etc/rc.config system configuration database driver file .TP /etc/rc.config.d directory containing system configuration files .RE .SH SEE ALSO rc.config(4). .\" toc@\f3ch_rc(1M)\f1:\0\0\f4ch_rc\f1@@@change system configuration file .\" .\" index@\f4ch_rc\f1 \- change system configuration file@@@\f3ch_rc(1M)\f1 .\" index@\f1change system configuration file@@@\f3ch_rc(1M)\f1 .\" index@\f1system configuration file, change@@@\f3ch_rc(1M)\f1 .\" index@\f1configuration file, change system@@@\f3ch_rc(1M)\f1 .\" index@\f1file, change system configuration@@@\f3ch_rc(1M)\f1 ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Oct 25, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH change 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "epochs" "changing" .iX "\*Ldtscp\*O commands" "\*Lchange\*O" .SH NAME .PP \*Lchange\*O - Alters the epoch number and time on the local node .SH "SYNOPSIS" .PP .zA "defect,6211,R1.0.3,add control program name" .sS \*Ldtscp change \*Lepoch\*O \*Vinteger\*O [\*Ltime\*O \*Vabsolute-time\*O]\*O .sE .zZ "defect,6211,R1.0.3,add control program name" .SH "OPTIONS" .VL .LI "\*Lepoch\*O \*Vinteger\*O" Specifies the new epoch number .zA "defect,5716,R1.0.2, Add epoch number range '(0-255)'" (0-255). .zZ "defect,5716,R1.0.2, Add epoch number range '(0-255)'" This argument is required. .LI "\*Ltime\*O \*Vabsolute-time\*O" Specifies a clock setting for the new epoch. If you do not supply this argument and a value, the server uses the current clock time with an unspecified inaccuracy and initiates a synchronization. This argument is optional. .LE .SH "DESCRIPTION" .PP The \*Lchange\*O command sets the time and changes the epoch of the DTS server on which it is entered. Use this command to isolate a server from the rest of the servers in the network before changing the time. .SS "Permissions Required" .PP You must have write permission on the ACL associated with the DTS entity in order to execute the command. .SH "NOTES" .PP This command is valid only for servers. The new epoch number you specify must be different from the current epoch number. .zA "defect, 11818, R1.1, Added caveat" .PP This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" ...\".SH "EXIT VALUES" ...\".PP ...\".VL 8m ...\".LI "Same Epoch" ...\"The command failed because the new epoch number must ...\"be different from the current epoch number. ...\".LI "Wrong State" ...\"The command failed because the DTS ...\"entity is in the \*Loff\*O, \*Lsynchronizing\*O, or ...\"\*Lupdating\*O state. ...\".LE .SH "EXAMPLES" .AL .LI The following example shows how to change the epoch number: .iS \*Cdtscp>\*O \*Lchange epoch 1\*O .iE .LI The following example shows how to change the epoch number and time: .iS \*Cdtscp>\*O \*Lchange epoch 1 time 1990-11-30-10:58:00.000-05:00I0.000\*O .iE .LE .\" $Header: acctsh.1m,v 72.4 94/11/14 12:02:10 ssa Exp $ .TA a .TH acctsh 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chargefee, ckpacct, dodisk, lastlogin, monacct, nulladm, prctmp, prdaily, prtacct, shutacct, startup, turnacct \- shell procedures for accounting .SH SYNOPSIS .C /usr/sbin/acct/chargefee .I login-name number .PP .C /usr/sbin/acct/ckpacct .RI [ \|blocks\| ] .PP .C /usr/sbin/acct/dodisk .RC [ -o ] .RI [ \|files \0 ...\|] .PP .C /usr/sbin/acct/lastlogin .PP .C /usr/sbin/acct/monacct .I number .PP .C /usr/sbin/acct/nulladm .I file .PP .C /usr/sbin/acct/prctmp .PP .C /usr/sbin/acct/prdaily .RC [ -l ] .RC [ -c ] .RC [ \c .IR mmdd\| ] .PP .C /usr/sbin/acct/prtacct .I file .RI [ \|heading\| ] .PP .C /usr/sbin/acct/shutacct .RI [ \|reason\| ] .PP .C /usr/sbin/acct/startup .PP .C /usr/sbin/acct/turnacct .CR on \0\(or\0 off \0\(or\0 switch .SH DESCRIPTION .TP 15 .C chargefee Can be invoked to charge a .I number of units to .IR login-name . A record is written to .CR /var/adm/fee , to be merged with other accounting records during the night. .TP .C ckpacct Should be initiated via .IR cron (1M). It periodically checks the size of .CR /var/adm/pacct . If the size exceeds .IR blocks , 1000 by default, .C turnacct is invoked with argument .IR switch . If the number of free disk blocks in the .C /var file system falls below 500, .C ckpacct automatically turns off the collection of process accounting records via the .C off argument to .CR turnacct . When at least this number of blocks is restored, the accounting will be activated again. This feature is sensitive to the frequency at which .C ckpacct is executed, usually by .CR cron . .TP .C dodisk Should be invoked by .C cron to perform the disk accounting functions. By default, it will do disk accounting on the special files in .C /etc/fstab. If the .C -o flag is used, it does a slower version of disk accounting by login directory. .I files specifies the one or more filesystem names where disk accounting is to be done. If .I files is used, disk accounting will be done on these filesystems only. If the .C -o flag is used, .I files should be mount points of mounted filesystem. If omitted, they should be the special file names of mountable filesystems. .TP .C lastlogin Invoked by .C runacct to update .C /var/adm/acct/sum/loginlog which shows the last date on which each user logged in (see .IR runacct (1M)). .TP .C monacct Should be invoked once each month or each accounting period. .I number indicates which month or period it is. If .I number is not given, it defaults to the current month (01 through 12). This default is useful if .C monacct is to executed via .CR cron on the first day of each month. .C monacct creates summary files in .C /var/adm/acct/fiscal and restarts summary files in .CR /var/adm/acct/sum . .TP .C nulladm Creates .I file with mode 664 and ensures that owner and group are .CR adm . It is called by various accounting shell procedures. .TP .C prctmp Can be used to print the session record file normally .C /var/adm/acct/nite/ctmp created by .C acctcon1 (see .IR acctcon (1M)). .TP .C prdaily Invoked by .C runacct (see .IR runacct (1M)) to format a report of the previous day's accounting data. The report resides in .CI /var/adm/acct/sum/rprt mmdd where .I mmdd is the month and day of the report. The current daily accounting reports may be printed by typing .IR prdaily . Previous days' accounting reports can be printed by using the .I mmdd option and specifying the exact report date desired. The .C -l flag prints a report of exceptional usage by login id for the specifed date. Previous daily reports are cleaned up and therefore inaccessible after each invocation of .CR monacct . The .C -c flag prints a report of exceptional resource usage by command, and can be used on current day's accounting data only. .TP .C prtacct Can be used to format and print any total accounting .RC ( tacct ) file. .TP .C shutacct Should be invoked during a system shutdown to turn process accounting off and append a ``reason'' record to .CR /var/adm/wtmp . .TP .C startup Should be called by system startup scripts to turn the accounting on whenever the system is brought up. .TP .C turnacct An interface to .C accton (see .IR acct (1M)) to turn process accounting .C on or .CR off . The .C switch argument turns accounting off, moves the current .C /var/adm/pacct to the next free name in .CI /var/adm/pacct incr then turns accounting back on again. .RI ( incr is a number starting with .C 1 and incrementing by one for each additional .C pacct file.) .C turnacct is called by .CR ckpacct , and thus can be run under .C cron and used to keep .C pacct to a reasonable size. .SH FILES .TP 40 .C /usr/sbin/acct holds all accounting commands listed in section (1M) of this manual .PD 0 .TP .C /var/adm/fee accumulator for fees .TP .C /var/adm/acct/nite working directory .TP .C /var/adm/pacct current file for per-process accounting .TP .C /var/adm/pacct* used if .C pacct gets large, and during execution of daily accounting procedure .TP .C /usr/sbin/acct/ptecms.awk contains the limits for exceptional usage by command name .TP .C /usr/sbin/acct/ptelus.awk contains the limits for exceptional usage by login id .TP .C /var/adm/acct/sum summary directory, should be saved .TP .C /var/adm/wtmp login/logoff summary .PD .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), cron(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR chargefee ": SVID2, SVID3" .PP .CR ckpacct ": SVID2, SVID3" .PP .CR dodisk ": SVID2, SVID3" .PP .CR lastlogin ": SVID2, SVID3" .PP .CR monacct ": SVID2, SVID3" .PP .CR prctmp ": SVID2, SVID3" .PP .CR prdaily ": SVID2, SVID3" .PP .CR prtacct ": SVID2, SVID3" .PP .CR shutacct ": SVID2, SVID3" .PP .CR startup ": SVID2, SVID3" .PP .CR turnacct ": SVID2, SVID3" .\" .\" .\" index@\f1process accounting@@@see accounting .\" index@\f1accounting: \f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4turnacct\f1 \- turn on or turn off process accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1bill fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1user, bill fee to, based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1disk accounting, perform@@@\f3acctsh(1M)\f1 .\" index@\f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1user, show last login date for each@@@\f3acctsh(1M)\f1 .\" index@\f1last login date, show for each user@@@\f3acctsh(1M)\f1 .\" index@\f1login date, show last for each user@@@\f3acctsh(1M)\f1 .\" index@\f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1periodic accounting summary files, create@@@\f3acctsh(1M)\f1 .\" index@\f1accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1files: accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1summary files, accounting, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1create empty administration file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1empty administration file owned by \f3adm\f1 with mode 664, create@@@\f3acctsh(1M)\f1 .\" index@\f1administration file owned by \f3adm\f1 with mode 664, create empty@@@\f3acctsh(1M)\f1 .\" index@\f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f4acctcon1\f1 \- print session record file created by@@@\f3acctsh(1M)\f1 .\" index@\f1print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1files, accounting: print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1session record file created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f1record file, session, created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1total accounting (\f4tacct\f1) file, print any@@@\f3acctsh(1M)\f1 .\" index@\f1accounting (\f4tacct\f1) file, print any total@@@\f3acctsh(1M)\f1 .\" index@\f4tacct\f1 (total accounting) file, print any@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting: \f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" index@\f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting data and command usage summary, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f1command usage summary and accounting data, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1system shutdown, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f1shutdown, system, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1system startup, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f1startup, system, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f4turnacct\f1 \- turn process accounting on or off@@@\f3acctsh(1M)\f1 .\" index@\f1shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f1system accounting, shell procedures for@@@\f3acctsh(1M)\f1 .\" .\"" Main TOC entry .\" toc@\f3acctsh(1M)\f1:\0\0\f4chargefee\f1, \f4ckpacct\f1, \f4dodisk\f1, \f4lastlogin\f1, \f4monacct\f1, \f4nulladm\f1, \f4prctmp\f1, \f4prdaily\f1,\n\f4prtacct\f1, \f4shutacct\f1, \f4startup\f1, \f4turnacct\f1@@@shell procedures for accounting .\" .\" toc@\f4chargefee\f1:\0\0shell procedures for accounting, charge fee to user@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4ckpacct\f1:\0\0shell procedures for accounting, check size of accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4dodisk\f1:\0\0shell procedures for accounting, perform disk accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4lastlogin\f1:\0\0shell procedures for accounting, show last login date@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4monacct\f1:\0\0shell procedures for accounting, create accounting summary@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4nulladm\f1:\0\0shell procedures for accounting, create null file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prctmp\f1:\0\0shell procedures for accounting, print session record file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prdaily\f1:\0\0shell procedures for accounting, print daily report@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prtacct\f1:\0\0shell procedures for accounting, print accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4shutacct\f1:\0\0shell procedures for accounting, turn off accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4startup\f1:\0\0shell procedures for accounting, start up accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4turnacct\f1:\0\0shell procedures for accounting, turn on or off process accounting@@@\f1see \f3acctsh(1M)\f1 .\" .\" links@acctsh.1m chargefee.1m .\" links@acctsh.1m ckpacct.1m .\" links@acctsh.1m dodisk.1m .\" links@acctsh.1m lastlogin.1m .\" links@acctsh.1m monacct.1m .\" links@acctsh.1m nulladm.1m .\" links@acctsh.1m prctmp.1m .\" links@acctsh.1m prdaily.1m .\" links@acctsh.1m prtacct.1m .\" links@acctsh.1m shutacct.1m .\" links@acctsh.1m startup.1m .\" links@acctsh.1m turnacct.1m .\" .\" fileset_database@acctsh.1m SYS-ADMIN-MAN .\" $Header: chroot.1m,v 72.6 94/11/14 13:07:20 ssa Exp $ .TA c .TH chroot 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chroot \- change root directory for a command .SH SYNOPSIS .CR /usr/sbin/chroot .IR newroot .IR command .SH DESCRIPTION The .CR chroot command executes .IR command relative to the .IR newroot . The meaning of any initial slashes .RC ( / ) in path names is changed for .IR command and any of its children to .IR newroot . Furthermore, the initial working directory is .IR newroot . .PP Note that command suffixes that affect input or output for the .CR chroot command use the original root, not the new root. For example, the command: .IP .C "chroot newroot command > x" .PP locates file .CR x relative to the original root, not the new one. .PP The .IR command variable includes both the command name and any arguments. .PP The new root path name is always relative to the current root. Even if a .CR chroot is currently in effect, the .IR newroot argument is relative to the current root of the running process. .PP This command is restricted to users with appropriate privileges. .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multibyte character code sets are supported. .SH WARNINGS .IR command cannot be in a shell script. .PP Exercise extreme caution when referring to special files in the new root file system. .PP .CR chroot does not search the .CR PATH environment variable for the location of .IR command , so the absolute path name of .IR command must be given. .PP When using .CR chroot to establish a new environment, all absolute path name references to the file system are lost, rendering shared libraries inaccessible. If continued access to shared libraries is needed for correct operation, the shared libraries and the dynamic loader .I must be copied into the new root environment. .SH SEE ALSO chdir(2), chroot(2). .SH STANDARDS CONFORMANCE .CR chroot ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4chroot\f1 \- change root directory for a command@@@\f3chroot(1M)\f1 .\" index@change root directory for a command@@@\f3chroot(1M)\f1 .\" index@command, change root directory@@@\f3chroot(1M)\f1 .\" index@directory: change root directory for a command@@@\f3chroot(1M)\f1 .\" index@root directory, change for a command@@@\f3chroot(1M)\f1 .\" .\" toc@\f3chroot(1M)\f1:\0\0\f4chroot\f1@@@change root directory for a command .\" $Header: acctsh.1m,v 72.4 94/11/14 12:02:10 ssa Exp $ .TA a .TH acctsh 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chargefee, ckpacct, dodisk, lastlogin, monacct, nulladm, prctmp, prdaily, prtacct, shutacct, startup, turnacct \- shell procedures for accounting .SH SYNOPSIS .C /usr/sbin/acct/chargefee .I login-name number .PP .C /usr/sbin/acct/ckpacct .RI [ \|blocks\| ] .PP .C /usr/sbin/acct/dodisk .RC [ -o ] .RI [ \|files \0 ...\|] .PP .C /usr/sbin/acct/lastlogin .PP .C /usr/sbin/acct/monacct .I number .PP .C /usr/sbin/acct/nulladm .I file .PP .C /usr/sbin/acct/prctmp .PP .C /usr/sbin/acct/prdaily .RC [ -l ] .RC [ -c ] .RC [ \c .IR mmdd\| ] .PP .C /usr/sbin/acct/prtacct .I file .RI [ \|heading\| ] .PP .C /usr/sbin/acct/shutacct .RI [ \|reason\| ] .PP .C /usr/sbin/acct/startup .PP .C /usr/sbin/acct/turnacct .CR on \0\(or\0 off \0\(or\0 switch .SH DESCRIPTION .TP 15 .C chargefee Can be invoked to charge a .I number of units to .IR login-name . A record is written to .CR /var/adm/fee , to be merged with other accounting records during the night. .TP .C ckpacct Should be initiated via .IR cron (1M). It periodically checks the size of .CR /var/adm/pacct . If the size exceeds .IR blocks , 1000 by default, .C turnacct is invoked with argument .IR switch . If the number of free disk blocks in the .C /var file system falls below 500, .C ckpacct automatically turns off the collection of process accounting records via the .C off argument to .CR turnacct . When at least this number of blocks is restored, the accounting will be activated again. This feature is sensitive to the frequency at which .C ckpacct is executed, usually by .CR cron . .TP .C dodisk Should be invoked by .C cron to perform the disk accounting functions. By default, it will do disk accounting on the special files in .C /etc/fstab. If the .C -o flag is used, it does a slower version of disk accounting by login directory. .I files specifies the one or more filesystem names where disk accounting is to be done. If .I files is used, disk accounting will be done on these filesystems only. If the .C -o flag is used, .I files should be mount points of mounted filesystem. If omitted, they should be the special file names of mountable filesystems. .TP .C lastlogin Invoked by .C runacct to update .C /var/adm/acct/sum/loginlog which shows the last date on which each user logged in (see .IR runacct (1M)). .TP .C monacct Should be invoked once each month or each accounting period. .I number indicates which month or period it is. If .I number is not given, it defaults to the current month (01 through 12). This default is useful if .C monacct is to executed via .CR cron on the first day of each month. .C monacct creates summary files in .C /var/adm/acct/fiscal and restarts summary files in .CR /var/adm/acct/sum . .TP .C nulladm Creates .I file with mode 664 and ensures that owner and group are .CR adm . It is called by various accounting shell procedures. .TP .C prctmp Can be used to print the session record file normally .C /var/adm/acct/nite/ctmp created by .C acctcon1 (see .IR acctcon (1M)). .TP .C prdaily Invoked by .C runacct (see .IR runacct (1M)) to format a report of the previous day's accounting data. The report resides in .CI /var/adm/acct/sum/rprt mmdd where .I mmdd is the month and day of the report. The current daily accounting reports may be printed by typing .IR prdaily . Previous days' accounting reports can be printed by using the .I mmdd option and specifying the exact report date desired. The .C -l flag prints a report of exceptional usage by login id for the specifed date. Previous daily reports are cleaned up and therefore inaccessible after each invocation of .CR monacct . The .C -c flag prints a report of exceptional resource usage by command, and can be used on current day's accounting data only. .TP .C prtacct Can be used to format and print any total accounting .RC ( tacct ) file. .TP .C shutacct Should be invoked during a system shutdown to turn process accounting off and append a ``reason'' record to .CR /var/adm/wtmp . .TP .C startup Should be called by system startup scripts to turn the accounting on whenever the system is brought up. .TP .C turnacct An interface to .C accton (see .IR acct (1M)) to turn process accounting .C on or .CR off . The .C switch argument turns accounting off, moves the current .C /var/adm/pacct to the next free name in .CI /var/adm/pacct incr then turns accounting back on again. .RI ( incr is a number starting with .C 1 and incrementing by one for each additional .C pacct file.) .C turnacct is called by .CR ckpacct , and thus can be run under .C cron and used to keep .C pacct to a reasonable size. .SH FILES .TP 40 .C /usr/sbin/acct holds all accounting commands listed in section (1M) of this manual .PD 0 .TP .C /var/adm/fee accumulator for fees .TP .C /var/adm/acct/nite working directory .TP .C /var/adm/pacct current file for per-process accounting .TP .C /var/adm/pacct* used if .C pacct gets large, and during execution of daily accounting procedure .TP .C /usr/sbin/acct/ptecms.awk contains the limits for exceptional usage by command name .TP .C /usr/sbin/acct/ptelus.awk contains the limits for exceptional usage by login id .TP .C /var/adm/acct/sum summary directory, should be saved .TP .C /var/adm/wtmp login/logoff summary .PD .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), cron(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR chargefee ": SVID2, SVID3" .PP .CR ckpacct ": SVID2, SVID3" .PP .CR dodisk ": SVID2, SVID3" .PP .CR lastlogin ": SVID2, SVID3" .PP .CR monacct ": SVID2, SVID3" .PP .CR prctmp ": SVID2, SVID3" .PP .CR prdaily ": SVID2, SVID3" .PP .CR prtacct ": SVID2, SVID3" .PP .CR shutacct ": SVID2, SVID3" .PP .CR startup ": SVID2, SVID3" .PP .CR turnacct ": SVID2, SVID3" .\" .\" .\" index@\f1process accounting@@@see accounting .\" index@\f1accounting: \f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4turnacct\f1 \- turn on or turn off process accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1bill fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1user, bill fee to, based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1disk accounting, perform@@@\f3acctsh(1M)\f1 .\" index@\f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1user, show last login date for each@@@\f3acctsh(1M)\f1 .\" index@\f1last login date, show for each user@@@\f3acctsh(1M)\f1 .\" index@\f1login date, show last for each user@@@\f3acctsh(1M)\f1 .\" index@\f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1periodic accounting summary files, create@@@\f3acctsh(1M)\f1 .\" index@\f1accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1files: accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1summary files, accounting, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1create empty administration file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1empty administration file owned by \f3adm\f1 with mode 664, create@@@\f3acctsh(1M)\f1 .\" index@\f1administration file owned by \f3adm\f1 with mode 664, create empty@@@\f3acctsh(1M)\f1 .\" index@\f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f4acctcon1\f1 \- print session record file created by@@@\f3acctsh(1M)\f1 .\" index@\f1print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1files, accounting: print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1session record file created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f1record file, session, created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1total accounting (\f4tacct\f1) file, print any@@@\f3acctsh(1M)\f1 .\" index@\f1accounting (\f4tacct\f1) file, print any total@@@\f3acctsh(1M)\f1 .\" index@\f4tacct\f1 (total accounting) file, print any@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting: \f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" index@\f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting data and command usage summary, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f1command usage summary and accounting data, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1system shutdown, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f1shutdown, system, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1system startup, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f1startup, system, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f4turnacct\f1 \- turn process accounting on or off@@@\f3acctsh(1M)\f1 .\" index@\f1shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f1system accounting, shell procedures for@@@\f3acctsh(1M)\f1 .\" .\"" Main TOC entry .\" toc@\f3acctsh(1M)\f1:\0\0\f4chargefee\f1, \f4ckpacct\f1, \f4dodisk\f1, \f4lastlogin\f1, \f4monacct\f1, \f4nulladm\f1, \f4prctmp\f1, \f4prdaily\f1,\n\f4prtacct\f1, \f4shutacct\f1, \f4startup\f1, \f4turnacct\f1@@@shell procedures for accounting .\" .\" toc@\f4chargefee\f1:\0\0shell procedures for accounting, charge fee to user@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4ckpacct\f1:\0\0shell procedures for accounting, check size of accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4dodisk\f1:\0\0shell procedures for accounting, perform disk accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4lastlogin\f1:\0\0shell procedures for accounting, show last login date@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4monacct\f1:\0\0shell procedures for accounting, create accounting summary@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4nulladm\f1:\0\0shell procedures for accounting, create null file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prctmp\f1:\0\0shell procedures for accounting, print session record file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prdaily\f1:\0\0shell procedures for accounting, print daily report@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prtacct\f1:\0\0shell procedures for accounting, print accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4shutacct\f1:\0\0shell procedures for accounting, turn off accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4startup\f1:\0\0shell procedures for accounting, start up accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4turnacct\f1:\0\0shell procedures for accounting, turn on or off process accounting@@@\f1see \f3acctsh(1M)\f1 .\" .\" links@acctsh.1m chargefee.1m .\" links@acctsh.1m ckpacct.1m .\" links@acctsh.1m dodisk.1m .\" links@acctsh.1m lastlogin.1m .\" links@acctsh.1m monacct.1m .\" links@acctsh.1m nulladm.1m .\" links@acctsh.1m prctmp.1m .\" links@acctsh.1m prdaily.1m .\" links@acctsh.1m prtacct.1m .\" links@acctsh.1m shutacct.1m .\" links@acctsh.1m startup.1m .\" links@acctsh.1m turnacct.1m .\" .\" fileset_database@acctsh.1m SYS-ADMIN-MAN .TH cleanup 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.X 1997 2.0 10/01/97 .SH NAME cleanup \- HP-UX patch cleanup utility .SH SYNOPSIS .br .C cleanup .RC [-F]|[-t]|[-i]|[-d absolute_path_to_depot] .PP .SH DESCRIPTION The .C cleanup command provides several functions useful when dealing with HP-UX patches. It is used as an aid in managing disk space consumed by the storage of backup files during the installation of a patch. The .C cleanup command is also used to remove patch information from the SD-UX Installed Product Database (IPD) after patches have been overwritten by software updates. The .C cleanup command provides an additional option to remove patches from a software depot if they have been superseded by newer patches also available in the same depot. Another feature of .C cleanup is its ability to trim the SD log files located in /var/adm/sw/sw*.log. No file removal will occur without user confirmation. There are 5 modes of operation for .C cleanup .RS 3 .TP 3 \(bu When run in this mode, .C cleanup will remove all backups of patches that have been superseded and prompt for trimming of the log files. Removal of superseded patch save areas will still leave enough data on the system to allow patch removal back one level but would preclude removing a series of patches, each superseding the next. In this mode, some accounting information (less than 1K) will be left on the system for 1 level back of superseded patch to allow for SD-database synchronization should a superseding patch be removed from the system. .TP 3 \(bu -F (force removal of all backups) When run in this mode, .C cleanup will remove all backups of patches, not just those which have been superseded. This will recover the most disk space possible using this tool, but will eliminate the possibility of backing out any currently installed patch off of the target system. There is a confirmation step before any backup removal takes place. .TP 3 \(bu -t (trim SD log files only) When run in this mode, .C cleanup will simply trim all the SD log files located in /var/adm/sw/sw*.log. These log files will be trimmed to their most recent five entries. There is no confirmation step when trimming the log files only. .TP 3 \(bu -i (remove overwritten patches from the IPD) When run in this mode, .C cleanup determines which patches that are included in the Installed Product Database have been overwritten by software product installations or updates. These patches are removed from the IPD upon confirmation from the user so that they are no longer displayed in the output of the swlist(1M) command. .TP 3 \(bu -d absolute_path_to_depot (remove superseded patches from depot) When run in this mode, .C cleanup determines which patches in the software depot have been superseded by newer patches also available from the depot. Upon confirmation from the user, these superseded patches will be removed from the software depot. .RE .RS .PP .SH RECOMMENDATIONS The .C cleanup command should be executed when additional disk space is required on the filesystem containing the /var/adm/sw/patch directory. The .C cleanup -F command should be executed when additional disk space is required on the filesystem containing the /var/adm/sw/patch directory .C AND the user is confident that none of the patches will ever need to be removed. The .C cleanup -i command should be executed whenever software products (including the operating system) are installed, reloaded, or updated. The .C cleanup -d command should be executed whenever patches are added to a software depot. .SH AUTHOR .C cleanup was developed by .SM HP. .PP .PD .SH SEE ALSO swremove(1M) .br ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "clear cached server" 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lcdscp\*O commands" "\*Lclear cached server\*O" .iX "CDS servers" "clearing from cache" .iX "cache" "clearing servers" .SH NAME .PP \*Lclear cached server\*O - Removes knowledge of a server that you had specifically defined from the local clerk's cache .wH "" .SH "SYNOPSIS" .sS \*Lcdscp clear cached server\*V name\*O .wH "" .SH "ARGUMENTS" .VL .LI \*Vname\*O The simple name given to the cached server when it is created. .LE .wH "" .SH "DESCRIPTION" .PP The \*Lclear cached server\*O command removes knowledge of a server from the local clerk's cache. You can only clear servers that you have specifically created with the \*Ldefine cached server\*O command. .SS "Privilege Required .PP You must have write permission to the clerk. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .PP The following command removes knowledge of the server \*Lnrl\*O from the clerk cache: .iS \*Ccdscp> \*Lclear cached server nrl\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ldefine cached server(1m)\*O, \*Ldump clerk cache\*O, \*Lshow cached server(1m)\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "clear clearinghouse" 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "CDS servers" "clearing clearinghouses" .iX "\*Lcdscp\*O commands" "\*Lclear clearinghouse\*O" .SH NAME .PP \*Lclear clearinghouse\*O - Removes knowledge of the specified clearinghouse from the server's memory .wH "" .SH "SYNOPSIS" .PP \*Lcdscp clear clearinghouse \*Vclearinghouse-name\*O .wH "" .SH "ARGUMENTS" .VL .LI \*Vclearinghouse-name\*O The full name of the clearinghouse. .LE .wH "" .SH "DESCRIPTION" .PP The \*Lclear clearinghouse\*O command removes knowledge of the specified clearinghouse from the server's memory. The clearinghouse files are not deleted. This ensures that the clearinghouse is not automatically enabled on server restarts. If you issue a \*Llist clearinghouse\*O command, the clearinghouse will be listed. .PP .zA "enh,8009,V1.0.3,cannot delete cleared clearinghouse" Before you can delete a cleared clearinghouse, you must use the \*Lcreate clearinghouse\*O command to recreate it. After recreating the clearinghouse, you can use the \*Ldelete clearinghouse\*O command to remove it. .zZ "enh,8009,V1.0.3,cannot delete cleared clearinghouse" .PP This command is part of the process of relocating a clearinghouse. See the \*VOSF DCE Administration Guide\*O for more information. .SS "Privilege Required .PP You must have write permission to the server on which the clearinghouse resides. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .PP The following command clears the clearinghouse \*L/.:/Paris2_CH\*O before moving it to another server: .iS \*Ccdscp> \*Lclear clearinghouse /.:/Paris2_CH .iE .wH "" .SH "RELATED INFORMATION" .PP Books: \*VOSF DCE Administration Guide\*O .PP Commands: \*Lcreate clearinghouse(1m)\*O, \*Ldelete clearinghouse(1m)\*O, \*Llist clearinghouse(1m)\*O, \*Lset cdscp preferred clearinghouse(1m)\*O, \*Lshow cdscp preferred clearinghouse(1m)\*O, \*Lshow clearinghouse(1m)\*O .\" $Header: acct.1m,v 72.5 94/11/14 12:00:17 ssa Exp $ .TA a .TH acct 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctdisk, acctdusg, accton, acctwtmp, closewtmp, utmp2wtmp \- overview of accounting and miscellaneous accounting commands .SH SYNOPSIS .C /usr/sbin/acct/acctdisk .PP .C /usr/sbin/acct/acctdusg .RC [ -u .IR file\| ] .RC [ -p .IR file\| ] .PP .C /usr/sbin/acct/accton .RI [ \|file\| ] .PP .C /usr/sbin/acct/acctwtmp .I reason .PP .C /usr/sbin/acct/closewtmp .PP .C /usr/sbin/acct/utmp2wtmp .SH DESCRIPTION Accounting software is structured as a set of tools (consisting of both C programs and shell procedures) that can be used to build accounting systems. The shell procedures, described in .IR acctsh (1M), are built on top of the C programs. .PP Connect time accounting is handled by various programs that write records into .CR /etc/utmp , as described in .IR utmp (4). The programs described in .IR acctcon (1M) convert this file into session and charging records which are then summarized by .C acctmerg (see .IR acctmerg (1M)). .PP Process accounting is performed by the .SM HP-UX system kernel. Upon termination of a process, one record per process is written to a file (normally .CR /var/adm/pacct ). The programs in .IR acctprc (1M) summarize this data for charging purposes; .C acctcms is used to summarize command usage (see .IR acctcms (1M)). Current process data can be examined using .C acctcom (see .IR acctcom (1M)). .PP Process accounting and connect time accounting (or any accounting records in the format described in .IR acct (4)) can be merged and summarized into total accounting records by .C acctmerg (see .C tacct format in .IR acct (4)). .C prtacct is used to format any or all accounting records (see .IR acctsh (1M)). .PP .C acctdisk reads lines that contain user .SM ID, login name, and number of disk blocks, and converts them to total accounting records that can be merged with other accounting records. .PP .C acctdusg reads its standard input (usually from .CR "find -print" ) and computes disk resource consumption (including indirect blocks) by login. Only files found under login directories (as determined from the password file) are accounted for. All files under a login directory are assumed to belong to that user regardless of actual owner. If .C -u is given, records consisting of those file names for which .C acctdusg charges no one are placed in .I file (a potential source for finding users trying to avoid disk charges). If .C -p is given, .I file is the name of the password file. This option is not needed if the password file is .CR /etc/passwd . (See .IR diskusg (1M) for more details.) .PP .C accton turns process accounting off if the optional .I file argument is omitted. If .I file is given, it must be the name of an existing file, to which the kernel appends process accounting records (see .IR acct (2) and .IR acct (4)). .PP .C acctwtmp writes a .IR utmp (4) record to its standard output. The record contains the current time and a string of characters that describe the .I reason for writing the record. A record type of .SM ACCOUNTING is assigned (see .IR utmp (4)). The string argument .I reason must be 11 or fewer characters, numbers, .CR $ , or spaces. For example, the following are suggestions for use in reboot and shutdown procedures, respectively: .IP .C "acctwtmp `uname` >> /var/adm/wtmp" .IP .C "acctwtmp ""file save"" >> /var/adm/wtmp .PP .C closewtmp writes a .SM DEAD_PROCESS record, for each user currently logged in, to the file .CR /var/adm/wtmp . This program is invoked by .I runacct to close the existing .C wtmp file before creating a new one. .PP .C utmp2wtmp writes a .SM USER_PROCESS record, for each user currently logged in, to the file .CR /var/adm/wtmp . This program is invoked by .I runacct to initialize the newly created .C wtmp file. .SH FILES .TP 30 .C /usr/sbin/acct Holds all accounting commands listed in section (1M) of this manual. .TP .C /var/adm/pacct Current process accounting file. .TP .C /etc/passwd Used for converting login name to user. .SM ID .TP .C /var/adm/wtmp Login/logoff history file. .SH SEE ALSO acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), acctsh(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .PP System Accounting topics in .I HP-UX System Administrator manuals. .SH STANDARDS CONFORMANCE .CR acctdisk ": SVID2, SVID3" .PP .CR accton ": SVID2, SVID3" .PP .CR acctwtmp ": SVID2, SVID3" .\" .\" index@accounting: \f4acctdisk\f1 \- create disk usage accounting records@@@\f3acct(1M)\f1 .\" index@accounting: \f4acctdusg\f1 \- compute disk usage by login name@@@\f3acct(1M)\f1 .\" index@accounting: \f4accton\f1 \- define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@accounting: \f4acctwtmp\f1 \- write \f4utmp\f1 record and reason for writing@@@\f3acct(1M)\f1 .\" index@\f4acctdisk\f1 \- create disk usage accounting records@@@\f3acct(1M)\f1 .\" index@\f4acctdusg\f1 \- compute disk usage by login name@@@\f3acct(1M)\f1 .\" index@\f4accton\f1 \- define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@\f4acctwtmp\f1 \- write \f4utmp\f1 record and reason for writing@@@\f3acct(1M)\f1 .\" index@disk usage accounting records, create@@@\f3acct(1M)\f1 .\" index@disk usage by login name, compute@@@\f3acct(1M)\f1 .\" index@define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@disable accounting or define kernel process accounting output file@@@\f3acct(1M)\f1 .\" index@\f4utmp\f1 record, write and include reason for writing@@@\f3acct(1M)\f1 .\" .\" toc@\f3acct(1M)\f1:\0\0\f4acctdisk\f1, \f4acctdusg\f1, \f4accton\f1,\n\f4acctwtmp\f1@@@overview of accounting and miscellaneous accounting commands .\" toc@\f4acctdisk\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4acctdusg\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4accton\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4acctwtmp\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" .\" links@acct.1m acctdisk.1m .\" links@acct.1m acctdusg.1m .\" links@acct.1m accton.1m .\" links@acct.1m acctwtmp.1m .\" links@acct.1m closewtmp.1m .\" links@acct.1m utmp2wtmp.1m .\" .\" fileset_database@acct.1m SYS-ADMIN-MAN .\" $Header: clri.1m,v 72.6 94/11/29 05:52:42 ssa Exp $ .TA c .TH clri 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clri \- clear inode .SH SYNOPSIS .C /usr/sbin/clri .I special .I i-number \0... .SH DESCRIPTION The .C clri command clears the inode .I i-number by filling it with zeros. .I special must be a special file name referring to a device containing a file system. For proper results, .I special should not be mounted (see WARNINGS below). After .C clri is executed, all blocks in the affected file show up as "missing" in an .C fsck of .I special (see .IR fsck (1M)). This command should only be used in emergencies. .PP Read and write permission is required on the specified .I special device. The inode becomes allocatable. .SH WARNINGS The primary purpose of this command is to remove a file that for some reason does not appear in any directory. If it is used to clear an inode that does appear in a directory, care should be taken to locate the entry and remove it. Otherwise, when the inode is reallocated to some new file, the old entry in the directory will still point to that file. At that point, removing the old entry destroys the new file, causing the new entry to point to an unallocated inode, so the whole cycle is likely to be repeated again. .PP If the file system is mounted, .C clri is likely to be ineffective. .SH DEPENDENCIES .C clri operates only on file systems of type .C hfs. .SH SEE ALSO fsck(1M), fsdb(1M), ncheck(1M), fs(4). .SH STANDARDS CONFORMANCE .IR clri ": SVID2, SVID3" .\" .\" index@\f4clri\f1 \- clear inode@@@\f3clri(1M)\f1 .\" index@clear inode@@@\f3clri(1M)\f1 .\" index@inode, clear@@@\f3clri(1M)\f1 .\" index@remove file that is not listed in any directory@@@\f3clri(1M)\f1 .\" index@files: remove file that is not listed in any directory@@@\f3clri(1M)\f1 .\" .\" toc@\f3clri(1M)\f1:\0\0\f4clri\f1@@@clear inode .\" .\" fileset_database@clri.1m SYS-ADMIN-MAN .\" .\" links@clri.1m clri_hfs.1m .\" $Header: clri.1m,v 72.6 94/11/29 05:52:42 ssa Exp $ .TA c .TH clri 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clri \- clear inode .SH SYNOPSIS .C /usr/sbin/clri .I special .I i-number \0... .SH DESCRIPTION The .C clri command clears the inode .I i-number by filling it with zeros. .I special must be a special file name referring to a device containing a file system. For proper results, .I special should not be mounted (see WARNINGS below). After .C clri is executed, all blocks in the affected file show up as "missing" in an .C fsck of .I special (see .IR fsck (1M)). This command should only be used in emergencies. .PP Read and write permission is required on the specified .I special device. The inode becomes allocatable. .SH WARNINGS The primary purpose of this command is to remove a file that for some reason does not appear in any directory. If it is used to clear an inode that does appear in a directory, care should be taken to locate the entry and remove it. Otherwise, when the inode is reallocated to some new file, the old entry in the directory will still point to that file. At that point, removing the old entry destroys the new file, causing the new entry to point to an unallocated inode, so the whole cycle is likely to be repeated again. .PP If the file system is mounted, .C clri is likely to be ineffective. .SH DEPENDENCIES .C clri operates only on file systems of type .C hfs. .SH SEE ALSO fsck(1M), fsdb(1M), ncheck(1M), fs(4). .SH STANDARDS CONFORMANCE .IR clri ": SVID2, SVID3" .\" .\" index@\f4clri\f1 \- clear inode@@@\f3clri(1M)\f1 .\" index@clear inode@@@\f3clri(1M)\f1 .\" index@inode, clear@@@\f3clri(1M)\f1 .\" index@remove file that is not listed in any directory@@@\f3clri(1M)\f1 .\" index@files: remove file that is not listed in any directory@@@\f3clri(1M)\f1 .\" .\" toc@\f3clri(1M)\f1:\0\0\f4clri\f1@@@clear inode .\" .\" fileset_database@clri.1m SYS-ADMIN-MAN .\" .\" links@clri.1m clri_hfs.1m .\" $Header: clrsvc.1m,v 72.5 94/12/16 09:51:07 ssa Exp $ .TA c .TH clrsvc 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clrsvc \- clear x25 switched virtual circuit .SH SYNOPSIS .C clrsvc .I line pad-type .SH DESCRIPTION .C clrsvc clears any virtual circuit that might be established on the specified .IR line . .I pad-type indicates to .C clrsvc what .C opx25 script to run from .CR /usr/lbin/uucp/X25 . .SH DEPENDENCIES HP\|2334A is the only .SM PAD supported at this time, and results in an .C opx25 execution of .CR HP2334A.clr . .SH EXAMPLES A typical invocation is: .IP .C "/usr/lbin/uucp/X25/clrsvc /dev/x25.1 HP2334A" .SH AUTHOR .C clrsvc was developed by HP. .SH SEE ALSO getx25(1M), opx25(1M), getty(1M), login(1), uucp(1). .\" .\" index@\f4clrsvc\f1 \- clear \s-1X.25\s+1 switched virtual circuit@@@\f3clrsvc(1M)\f1 .\" index@clear \s-1X.25\s+1 switched virtual circuit@@@\f3clrsvc(1M)\f1 .\" index@\s-1X.25\s+1 switched virtual circuit, clear@@@\f3clrsvc(1M)\f1 .\" index@switched virtual circuit, clear \s-1X.25\s+1@@@\f3clrsvc(1M)\f1 .\" index@virtual circuit, \s-1X.25\s+1 switched, clear@@@\f3clrsvc(1M)\f1 .\" index@circuit, \s-1X.25\s+1 switched virtual, clear@@@\f3clrsvc(1M)\f1 .\" .\" toc@\f3clrsvc(1M)\f1:\0\0\f4clrsvc\f1@@@clear x25 switched virtual circuit .\" .\" fileset_database@clrsvc.1m SYS-ADMIN-MAN ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "cm" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lcm\*O command suite" "syntax" .SH NAME .PP \*Lcm\*O \- Introduction to the \*Lcm\*O command suite .SH "OPTIONS" .PP The following options are used with many \*Lcm\*O commands. They are also listed with the commands that use them. .VL .zA "misc,R1.0.2,Repair PH work oversight" .LI "\*L-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}" Names the files, directories, or both to be used with the command. .zZ "misc,R1.0.2,Repair PH work oversight" .LI "\*L-help\*O" Prints the online help for the command. All other valid options specified with this option are ignored. For complete details about receiving help, see the \*Ldfs_intro(1m)\*O reference page. .LE .SH "DESCRIPTION" .PP .zA "defect,10440,R1.1,Incorporate information from User's Guide" .zA "defect,6062,R1.0.2,Remove cm debug command" Commands in the \*Lcm\*O command suite are issued by administrative users to set cache parameters and to update cached information on local workstations. Certain commands in the \*Lcm\*O suite are available to all users to determine machine and cell information. .zZ "defect,6062,R1.0.2,Remove cm debug command" .zZ "defect,10440,R1.1,Incorporate information from User's Guide" .PP .zA "defect,6085,R1.0.2,Document cm-related files on cm.1m" The files described in the following sections are used by the Cache Manager to determine its initial configuration and to store and track cached data. Each DFS client machine stores machine-specific versions of these files on its local disk. .SS "The CacheInfo File" .PP The \*Edcelocal\*L/etc/CacheInfo\*O file specifies the Cache Manager's initial configuration. It is manually created during DFS client installation. The Cache Manager checks the file at initialization to determine certain cache configuration information. .PP The file is a one-line ASCII file that contains three fields separated by colons. The fields provide the following information: .ML .LI The local directory where the Cache Manager mounts the DCE global namespace. The default is the global namespace designation (\*L/...\*O). .LI The local directory to serve as the cache directory. The Cache Manager stores the \*LCacheItems\*O, \*LFilesetItems\*O, and V files in this directory. The default, \*Edcelocal\*L/var/adm/dfs/cache\*O, can be overridden to direct the Cache Manager to store the files in a different directory. .LI The size of the cache in 1024-byte (1-kilobyte) blocks. .LE .SS "The CacheItems File" .PP The \*Edcelocal\*L/var/adm/dfs/cache/CacheItems\*O file is a binary file created and maintained by the Cache Manager. The file records information such as the file ID number and data version number of each V file on a client machine using a disk cache. \*ENever directly modify or delete this file\*O; doing so can cause the kernel to panic. .SS "The FilesetItems File" .PP The \*Edcelocal\*L/var/adm/dfs/cache/FilesetItems\*O file is a binary file created and maintained by the Cache Manager. The file records the fileset-to-mount point mapping for each fileset accessed by the Cache Manager. The mappings allow the Cache Manager to respond correctly to commands such as \*Lpwd\*O. \*ENever directly modify or delete this file\*O; doing so can cause the kernel to panic. .SS "V Files" .PP The \*Edcelocal\*L/var/adm/dfs/cache/V\*En\*O files, or V files, hold chunks of cached data on a client machine using a disk cache. In the name of an actual V file, \*En\*O is an integer; each V file has a unique name (for example, \*LV1\*O, \*LV2\*O, and so on). The format of a V file depends on the information it contains. .PP By default, each V file holds up to 65,536 bytes (64 kilobytes) of data. The default size can be overridden with the \*Ldfsd\*O command. \*ENever directly modify or delete a V file\*O; doing so can cause the kernel to panic. .zZ "defect,6085,R1.0.2,Document cm-related files on cm.1m" .SS "Cautions" .PP Specific cautionary information is included with individual commands. .SS "Receiving Help" .PP There are several different ways to receive help about DFS commands. The following examples summarize the syntax for the different help options: .VL .zA "misc,R1.0.2,Repair PH work mistakes" .LI "\*C$\*O \*Lman cm\*O" Displays the reference page for the command suite. .LI "\*C$\*O \*Lman cm_\*Vcommand\*O" Displays the reference page for an individual command. You must use an _ (underscore) to connect the command suite to the command name. \*EDo not use the underscore when issuing the command in DFS.\*O .LI "\*C$\*O \*Lcm help\*O" Displays a list of commands in a command suite. .LI "\*C$\*O \*Lcm help \*Vcommand\*O" Displays the syntax for a single command. .LI "\*C$\*O \*Lcm apropos -topic \*Vstring\*O" Displays a short description of any commands that match the specified \*Vstring\*O. .zZ "misc,R1.0.2,Repair PH work mistakes" .LE .PP Consult the \*Ldfs_intro(1m)\*O reference page for complete information about the DFS help facilities. .SS "Privilege Required" .PP Specific privileges required by each command are listed with individual commands. .SH "RELATED INFORMATION" .PP .zA "enh,5923,R1.1,remove cross-refs to User Guide and Ref" Commands: \*Lcm apropos(1m)\*O, \*Lcm checkfilesets(1m)\*O, .zA "defect,6062,R1.0.2,Remove cm debug command" .zZ "defect,6062,R1.0.2,Remove cm debug command" \*Lcm flush(1m)\*O, \*Lcm flushfileset(1m)\*O, \*Lcm getcachesize(1m)\*O, \*Lcm getdevok(1m)\*O, \*Lcm getsetuid(1m)\*O, \*Lcm help(1m)\*O, \*Lcm lscellinfo(1m)\*O, \*Lcm lsstores(1m)\*O, \*Lcm resetstores(1m)\*O, \*Lcm setcachesize(1m)\*O, \*Lcm setdevok(1m)\*O, \*Lcm setsetuid(1m)\*O, \*Lcm statservers(1m)\*O, \*Lcm sysname(1m)\*O, \*Lcm whereis(1m)\*O, \*Ldfs_intro(1m)\*O, \*Ldfsd(1m)\*O .PP .zA "defect,6085,R1.0.2,Document cm-related files on cm.1m" Files: \*LCacheInfo(4)\*O, \*LCacheItems(4)\*O, \*LFilesetItems(4)\*O, \*LVn(4)\*O .zZ "defect,6085,R1.0.2,Document cm-related files on cm.1m" .zZ "enh,5923,R1.1,remove cross-refs to User Guide and Ref" .PP .zA "enh,5923,R1.1,remove cross-refs to User Guide and Ref" .zZ "enh,5923,R1.1,remove cross-refs to User Guide and Ref" .iX "-]" "\*Lcm\*O command suite" "syntax" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\"Copyright (C) 1989, 1991, Transarc Corporation ...\"The Gulf Tower ...\"707 Grant Street ...\"Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "cm apropos" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lcm\*O command suite" "\*Lapropos\*O" .SH NAME .PP \*Lcm apropos\*O \- Shows each help entry containing a specified string .SH "SYNOPSIS" .PP .sS \*Lcm apropos -topic \*Vstring\*O [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-topic \*Vstring\*O" Specifies the keyword string for which to search. If it is more than a single word, surround the string with \*L"\|"\*O (double quotes) or other delimiters. Type all strings for \*Lcm\*O commands in lowercase letters. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lcm apropos\*O command displays the first line of the online help entry for any \*Lcm\*O command containing the string specified by \*L-topic\*O in its name or short description. .PP To display the syntax for a command, use the \*Lcm help\*O command. .SS "Privilege Required" .PP No privileges are required. .SH "OUTPUT" .PP The first line of an online help entry for a command names the command and briefly describes its function. This command displays the first line for any \*Lcm\*O command where the string specified by \*L-topic\*O is part of the command name or the first line. .SH "EXAMPLES" .PP The following command lists all \*Lcm\*O commands that have the word \*Lcache\*O in their names or short descriptions: .iS \*C$ \*Lcm apropos cache\*O .iE .oS flush: flush file data and status information from cache getcachesize: get cache usage info setcachesize: set cache size .oE .SH "RELATED INFORMATION" .PP Commands: \*Lcm help(1m)\*O .iX "-]" "\*Lcm\*O command suite" "\*Lapropos\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "cm checkfilesets" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\'wH INPUT attable.tex ...\"DOCUMENTSTYLE [12pt]{book} ...\'wH INPUT booklat.mac .iX "-[" "\*Lcm\*O command suite" "\*Lcheckfilesets\*O" .iX "-[" "filesets" "updating mapping table" .iX "-[" "Cache Manager" "updating mapping table" .SH NAME .PP \*Lcm checkfilesets\*O \- Forces the Cache Manager to update fileset-related information .SH "SYNOPSIS" .sS .PP \*Lcm checkfilesets\*O [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-help\*O" Prints the online help for this command. .LE .SH "DESCRIPTION" .PP The \*Lcm checkfilesets\*O command forces the Cache Manager to discard its table of mappings between fileset names and fileset ID numbers. Because the Cache Manager needs the information in the table to fetch files, this command forces the Cache Manager to fetch the most recent information available about a fileset from the Fileset Location Server before the Cache Manager can fetch any more files from that fileset. (Normally, the Cache Manager flushes the table and constructs a new one every hour.) .PP This command is most useful if you know that a fileset name has changed or that there is a release of new read-only replicas. Issuing this command forces the Cache Manager to reference the fileset with the new name or the new read-only replica. .PP To force the Cache Manager to discard a cached file or directory, use the \*Lcm flush\*O command. To force the Cache Manager to discard any data cached from filesets containing specified files or directories, use the \*Lcm flushfileset\*O command. .zA "defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Include privilege required" .SH "RELATED INFORMATION" .PP Commands: \*Lcm flush(1m)\*O, \*Lcm flushfileset(1m)\*O .iX "-]" "\*Lcm\*O command suite" "\*Lcheckfilesets\*O" .iX "-]" "filesets" "updating mapping table" .iX "-]" "Cache Manager" "updating mapping table" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "cm flush" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lcm\*O command suite" "\*Lflush\*O" .iX "-[" "Cache Manager" "flushing cache" .iX "-[" "cache" "flushing" .SH NAME .PP \*Lcm flush\*O \- Forces the Cache Manager to discard data cached from specified files or directories .SH "SYNOPSIS" .sS .PP \*Lcm flush\*O [\*L-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}...] [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}" Specifies each file or directory to be flushed. A file for which a full pathname is not specified is assumed to reside in the current working directory. In the case of a directory, all the name mappings and blocks associated with the directory are flushed; data cached from files or subdirectories that reside in the directory is not flushed. If this option is omitted, the current working directory is flushed. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lcm flush\*O command forces the Cache Manager to flush data cached from each file or directory specified with the \*L-path\*O option. All data cached from these files and directories is discarded. The next time the data is requested, the Cache Manager contacts the File Exporter to obtain the current version, along with new tokens and other associated status information. .PP This command does not discard any altered data in the cache not written to the central copy maintained by the File Exporter. It also does not affect data in the buffers of application programs. .PP It is also possible to flush all cached data that resides in the same fileset as a specific file or directory with the \*Lcm flushfileset\*O command. To force the Cache Manager to update fileset-related information, use the \*Lcm checkfilesets\*O command. .zA "defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Include privilege required" .SH "EXAMPLES" .PP The following command flushes the file \*Lprojectnotes\*O, which is in the current working directory, and all data from the subdirectory \*Lplans\*O from the cache: .iS \*C$\*O \*Lcm flush projectnotes plans/*\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lcm checkfilesets(1m)\*O, \*Lcm flushfileset(1m)\*O .iX "-]" "\*Lcm\*O command suite" "\*Lflush\*O" .iX "-]" "Cache Manager" "flushing cache" .iX "-]" "cache" "flushing" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "cm flushfileset" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "\*Lcm\*O command suite" "\*Lflushfileset\*O" .iX "filesets" "flushing data" .iX "Cache Manager" "flushing data" .zZ "misc,R1.0.2,Repair mistakes from PH work" .SH NAME .PP \*Lcm flushfileset\*O \- Forces the Cache Manager to discard data cached from filesets that contain specified files or directories .SH "SYNOPSIS" .sS .PP \*Lcm flushfileset\*O [\*L-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}...] [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}" Specifies a file or directory from each fileset to be flushed. A file for which a full pathname is not specified is assumed to reside in the current working directory. If this option is omitted, the fileset containing the current working directory is flushed. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lcm flushfileset\*O command forces the Cache Manager to flush data cached from filesets that contain each file or directory specified with the \*L-path\*O option. All data cached from these filesets is discarded. The next time the data is requested, the Cache Manager contacts the File Exporter to obtain the current version, along with new tokens and other associated status information. .PP This command does not discard any altered data in the cache not written to the central copy maintained by the File Exporter. It also does not affect data in the buffers of application programs. .PP It is also possible to flush data cached from specific files or directories with the \*Lcm flush\*O command. To force the Cache Manager to update fileset-related information, use the \*Lcm checkfilesets\*O command. .zA "defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Include privilege required" .SH "EXAMPLES" .PP The following command flushes data cached from the fileset containing the current working directory and the directory \*Lreports\*O, both of which are at the same level in the file tree: .iS \*C$\*O \*Lcm flushf . ../reports\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lcm checkfilesets(1m)\*O, \*Lcm flush(1m)\*O .zZ "misc,R1.0.2,Repair mistakes from PH work" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "cm getcachesize" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lcm\*O command suite" "\*Lgetcachesize\*O" .iX "-[" "cache" "viewing size" .SH NAME .PP \*Lcm getcachesize\*O \- Shows the current size of the cache, the amount of cache in use, and the type of cache .SH "SYNOPSIS" .sS \*Lcm getcachesize\*O [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-help\*O" Prints the online help for this command. .LE .SH "DESCRIPTION" .PP .zA "misc,R1.0.2,Repair mistakes from PH work" The \*Lcm getcachesize\*O command displays the current size of the cache available to the Cache Manager and the amount in use when the command is issued. It also displays the type of cache in use on the machine. The command works both on machines using disk caching and on machines using memory caching. .zZ "misc,R1.0.2,Repair mistakes from PH work" .PP .zA "enh,R1.0.2,Editorial improvements" The information displayed by the command comes from the kernel of the workstation on which the command is issued. On machines using disk caching, the current cache size may disagree with the default setting specified in the \*LCacheInfo\*O file if the cache size was set with the \*Lcm setcachesize\*O command. Regardless of the type of caching (disk or memory) in use, the size may also disagree with the default setting if it was changed with the \*Ldfsd\*O command. .zZ "enh,R1.0.2,Editorial improvements" .zA "defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Include privilege required" .SH "OUTPUT" .PP The \*Lcm getcachesize\*O command displays the following output: .oS \*CDFS using\*O \*Vamount\*O \*Cof the cache's available\*O \*Esize\*O \*C1K byte\*O (\*Etype\*O) \*Cblocks.\*O .oE .PP In the output, \*Eamount\*O is the number of kilobyte blocks the Cache Manager is currently using, \*Esize\*O is the total number of kilobyte blocks available to the Cache Manager (the current cache size), and \*Etype\*O is the type of cache (disk or memory) in use on the machine. .SH "EXAMPLES" .PP The following command shows the output on a machine with a 25,000 kilobyte disk cache: .iS \*C$\*O \*Lcm getcachesize\*O .iE .oS \*CDFS using 22876 of the cache's available 25000 1K byte (disk) blocks.\*O .oE .SH "RELATED INFORMATION" .zA "enh,R1.0.2,Add CacheInfo file" Commands: \*Lcm setcachesize(1m)\*O, \*Ldfsd(1m)\*O .PP Files: \*LCacheInfo(4)\*O .zZ "enh,R1.0.2,Add CacheInfo file" .iX "-]" "\*Lcm\*O command suite" "\*Lgetcachesize\*O" .iX "-]" "cache" "viewing size" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "cm getdevok" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lcm\*O command suite" "\*Lgetdevok\*O" .iX "-[" "device files" "determining status" .iX "-[" "Cache Manager" "device file status" .SH NAME .PP \*Lcm getdevok\*O \- Shows whether device files from specified filesets are honored by the Cache Manager .SH "SYNOPSIS" .sS \*Lcm getdevok\*O [\*L-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}...] [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}" Names a file or directory from each fileset whose device file status information is to be displayed. If this option is omitted, status information is displayed for the fileset containing the current working directory. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lcm getdevok\*O command reports whether the Cache Manager honors device files that reside in the indicated filesets. Indicate each fileset for which you want device file status information by specifying the name of a file or directory in the fileset with the \*L-path\*O option. This information comes from the kernel of the workstation on which the command is issued. .PP .zA "defect,7219,R1.0.2,Review comments" .zA "enh,R1.0.2,Clarify device file information" System administrators set whether device files are to be honored on a per-fileset and per-Cache Manager basis with the \*Lcm setdevok\*O command. By default, the Cache Manager does not honor device files from a fileset. (The UNIX kernel always honors device files stored in the \*L/dev\*O directory.) .zZ "enh,R1.0.2,Clarify device file information" .zZ "defect,7219,R1.0.2,Review comments" .zA "defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Include privilege required" .SH "OUTPUT" .PP The \*Lcm getdevok\*O command first displays the line .oS \*CFileset\*O \*Epathname\*O \*Cstatus:\*O .oE .PP In the output, \*Epathname\*O is the name of a file or directory specified with the \*L-path\*O option. For each specified file or directory, the following output values are possible for the fileset on which it resides: .VL .LI "\*Cdevice files allowed\*O" Indicates that device files from the fileset are honored. .LI "\*Cdevice files not allowed\*O" Indicates that device files from the fileset are not honored. .LI "\*Ccm: the fileset on which `\*Epathname\*C' resides does not exist\*O" Indicates that the specified pathname is invalid. .LE .SH "EXAMPLES" .PP The following command indicates that device files from the fileset that contains the directory \*L/.../abc.com/fs/usr/jlw\*O are not honored by the Cache Manager: .iS \*C$\*O \*Lcm getdevok /.../abc.com/fs/usr/jlw\*O .iE .oS \*C/.../abc.com/fs/user/jlw status: device files not allowed\*O .oE .SH "RELATED INFORMATION" .PP Commands: \*Lcm setdevok(1m)\*O .iX "-]" "\*Lcm\*O command suite" "\*Lgetdevok\*O" .iX "-]" "device files" "determining status" .iX "-]" "Cache Manager" "device file status" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "cm getsetuid" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lcm\*O command suite" "\*Lgetsetuid\*O" .iX "-[" "\*Lsetuid\*O programs" "checking status" .iX "-[" "Cache Manager" "status of \*Lsetuid\*O programs" .iX "-[" "filesets" "\*Lsetuid\*O status" .SH NAME .PP \*Lcm getsetuid\*O \- Shows the status of \*Lsetuid\*O programs from specified filesets .SH "SYNOPSIS" .sS \*Lcm getsetuid\*O [\*L-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}...] [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}" Names a file or directory from each fileset whose \*Lsetuid\*O permission is to be displayed. If this option is omitted, permission information is displayed for the fileset containing the current working directory. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lcm getsetuid\*O command reports whether the Cache Manager allows \*Lsetuid\*O programs from the indicated filesets to run with \*Lsetuid\*O permission. Indicate each fileset whose \*Lsetuid\*O permission is desired by specifying the name of a file or directory in the fileset with the \*L-path\*O option. This information comes from the kernel of the workstation on which the command is issued. .PP .zA "defect,7219,R1.0.2,Review comments" Note that \*Lsetuid\*O programs are effective only in the local environment. A \*Lsetuid\*O program can change only the local identity under which a program runs; it cannot change the DCE identity with which a program executes because it provides no Kerberos tickets. DCE does not recognize the change to the local identity associated with a \*Lsetuid\*O program. .zZ "defect,7219,R1.0.2,Review comments" .PP .zA "enh,R1.0.2,Clarify setuid permission information" Because \*Lsetgid\*O programs on filesets are enabled or disabled along with \*Lsetuid\*O programs, this command also reports the status of \*Lsetgid\*O programs on the indicated filesets. System administrators set \*Lsetuid\*O and \*Lsetgid\*O status on a per-fileset and per-Cache Manager basis with the \*Lcm setsetuid\*O command. By default, the Cache Manager does not allow \*Lsetuid\*O programs from a fileset to execute with \*Lsetuid\*O permission. .zZ "enh,R1.0.2,Clarify setuid permission information" .zA "defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Include privilege required" .SH "OUTPUT" .PP The \*Lcm getsetuid\*O command first displays the line .oS \*CFileset\*O \*Epathname\*O \*Cstatus:\*O .oE .PP In the output, \*Epathname\*O is the name of a file or directory specified with the \*L-path\*O option. For each specified file or directory, the following output values are possible for the fileset on which it resides: .VL .LI "\*Csetuid allowed\*O" Indicates that \*Lsetuid\*O and \*Lsetgid\*O programs from the fileset are enabled. .LI "\*Cno setuid allowed\*O" Indicates that \*Lsetuid\*O and \*Lsetgid\*O programs from the fileset are disabled. .LI "\*Ccm: the fileset on which `\*Epathname\*C' resides does not exist\*O" Indicates that the specified pathname is invalid. .LE .SH "EXAMPLES" .PP The following command indicates that \*Lsetuid\*O and \*Lsetgid\*O programs from the fileset that contains the directory \*L/.../abc.com/fs/usr/jlw\*O are disabled: .iS \*C$\*O \*Lcm getsetuid /.../abc.com/fs/usr/jlw\*O .iE .oS \*CFileset /.../abc.com/fs/usr/jlw status: no setuid allowed\*O .oE .SH "RELATED INFORMATION" .PP Commands: \*Lcm setsetuid(1m)\*O .iX "-]" "\*Lcm\*O command suite" "\*Lgetsetuid\*O" .iX "-]" "\*Lsetuid\*O programs" "checking status" .iX "-]" "filesets" "\*Lsetuid\*O status" .iX "-]" "Cache Manager" "status of \*Lsetuid\*O programs" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\"Copyright (C) 1989, 1991, Transarc Corporation ...\"The Gulf Tower ...\"707 Grant Street ...\"Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "cm help" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lcm\*O command suite" "\*Lhelp\*O" .SH NAME .PP \*Lcm help\*O \- Shows syntax of specified \*Lcm\*O commands or lists functional descriptions of all \*Lcm\*O commands .SH "SYNOPSIS" .PP .sS \*Lcm help\*O \*O[\*L-topic\*O \*Vstring\*O...] \*O[\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-topic \*Vstring\*O" Specifies each command whose syntax is to be displayed. Provide only the second part of the command name (for example, \*Lflush\*O, not \*Lcm flush\*O). If this option is omitted, the output provides a short description of all \*Lcm\*O commands. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lcm help\*O command displays the first line (name and short description) of the online help entry for every \*Lcm\*O command if \*L\-topic\*O is not provided. For each command name specified with \*L\-topic\*O, the output lists the entire help entry. .PP Use the \*Lcm apropos\*O command to show each help entry containing a specified string. .SS "Privilege Required" .PP No privileges are required. .SH "OUTPUT" .PP The online help entry for each \*Lcm\*O command consists of the following two lines: .ML .LI The first line names the command and briefly describes its function. .LI The second line, which begins with \*CUsage:\*O, lists the command options in the prescribed order. .LE .SH "EXAMPLES" .PP The following command displays the online help entry for the \*Lcm\ flush\*O command: .iS \*C$ \*Lcm help flush\*O .iE .oS cm flush: flush file from cache Usage: cm flush [-path { | }...] [-help] .oE .SH "RELATED INFORMATION" .PP Commands: \*Lcm apropos(1m)\*O .iX "-]" "\*Lcm\*O command suite" "\*Lhelp\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "cm lscellinfo" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\'wH INPUT attable.tex ...\"DOCUMENTSTYLE [12pt]{book} ...\'wH INPUT booklat.mac .iX "-[" "\*Lcm\*O command suite" "\*Llscellinfo\*O" .iX "-[" "Cache Manager" "identifying known FLDB machines" .iX "-[" "Fileset Location Database" "identifying server machines" .SH NAME .PP \*Lcm lscellinfo\*O \- Shows database server machines in cells known to the Cache Manager .SH "SYNOPSIS" .sS \*Lcm lscellinfo\*O [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-help\*O" Prints the online help for this command. .LE .SH "DESCRIPTION" .PP The \*Lcm lscellinfo\*O command formats and displays the Cache Manager's kernel-resident list of Fileset Location Database (FLDB) machines in its home cell and any foreign cells the Cache Manager has accessed. This information comes from the kernel of the workstation on which the command is issued. .zA "defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Include privilege required" .SH "OUTPUT" .PP The output contains one line for the local cell and one line for each cell listed in the kernel that the Cache Manager has accessed. Each cell name is followed by a list of its database server machines (referred to as \*Lhosts\*O). .SH "EXAMPLES" .PP The following command shows output for several cells: .iS \*C$\*L cm lscellinfo\*O .iE .oS \*CCell abc.com on hosts fs2.abc.com\*O .nL \*CCell state.edu on hosts fs11.fs.state.edu\*O .oE .iX "-]" "\*Lcm\*O command suite" "\*Llscellinfo\*O" .iX "-]" "Cache Manager" "identifying known FLDB machines" .iX "-]" "Fileset Location Database" "identifying server machines" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "cm lsstores" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lcm\*O command suite" "\*Llsstores\*O" .iX "-[" "filesets" "identifying nonupdatable" .iX "-[" "Cache Manager" "nonupdatable filesets" .iX "-[" "Cache Manager" "discarding data" .SH NAME .PP \*Lcm lsstores\*O - Lists filesets that contain data the Cache Manager cannot write back to a File Server machine .SH "SYNOPSIS" .sS \*Lcm lsstores\*O [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-help\*O" Prints the online help for this command. .LE .SH "DESCRIPTION" .PP The \*Lcm lsstores\*O command lists the fileset ID numbers of filesets that contain data the Cache Manager cannot write back to a File Server machine. This information comes from the kernel of the workstation on which the command is issued. .PP .zA "defect,6557,R1.0.2,Correct how CM handles unstored data" .zA "defect,7219,R1.0.2,Review comments" On occasion, a File Server machine may be unavailable to the Cache Manager (possibly because the File Server machine is down or because a network problem prevents the Cache Manager from contacting the machine). In such cases, the Cache Manager cannot write data back to the File Server machine. The Cache Manager displays a message on the screen to notify the user that it cannot write the data to the unavailable machine. If possible, it also returns a failure code to the application program using the data. .PP The Cache Manager keeps the unstored data in the cache and continues to attempt to contact the File Server machine until it can store the data. (The frequency with which it attempts to reach a File Server machine is defined with the \*L-pollinterval\*O option of the \*Lfxd\*O command issued on that File Server machine.) In the meantime, corrective measures can be taken to alleviate the problem that prevents the data from being stored; for example, the File Server machine can be restarted. Once the problem is alleviated, the Cache Manager can reach the File Server machine and store the data. .zZ "defect,7219,R1.0.2,Review comments" .PP The Cache Manager discards unstored data only when .ML .LI It needs to make room in the cache for other data. Given an average-sized cache with average usage, the Cache Manager rarely needs to discard unstored data. .LI The \*Lcm resetstores\*O command is issued to force it to discard unstored data from the cache. .LE .PP Because unstored data discarded from the cache cannot be recovered, any problem that prevents data from being written to a File Server machine should be handled promptly. .zZ "defect,6557,R1.0.2,Correct how CM handles unstored data" .zA "defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Include privilege required" .zA "defect,7219,R1.0.2,Review comments" .SH "OUTPUT .PP If the Cache Manager cannot store data to one or more filesets, the command displays the fileset ID number of each fileset to which data cannot be stored. If the Cache Manager has been able to store all data, the command displays the following message: .oS \*CNo failed stores are being retried.\*O .oE .zZ "defect,7219,R1.0.2,Review comments" .SH "RELATED INFORMATION" .PP Commands: \*Lcm resetstores(1m)\*O, \*Lfxd(1m)\*O .iX "-]" "\*Lcm\*O command suite" "\*Llsstores\*O" .iX "-]" "filesets" "identifying nonupdatable" .iX "-]" "Cache Manager" "nonupdatable filesets" .iX "-]" "Cache Manager" "discarding data" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "cm resetstores" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lcm\*O command suite" "\*Lresetstores\*O" .iX "-[" "filesets" "canceling updates" .iX "-[" "Cache Manager" "canceling update operations" .iX "-[" "Cache Manager" "discarding data" .SH NAME .PP \*Lcm resetstores\*O - Cancels attempts by the Cache Manager to contact unavailable File Server machines and discards all data the Cache Manager cannot store to such machines .SH "SYNOPSIS" .sS \*Lcm resetstores\*O [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-help\*O" Prints the online help for this command. .LE .SH "DESCRIPTION" .PP .zA "defect,7219,R1.0.2,Review comments" The \*Lcm resetstores\*O command cancels the Cache Manager's continued attempts to contact unavailable File Server machines. \*EAll\*O data the Cache Manager cannot store to such File Server machines is discarded; there is no way to selectively discard individual files or data from specific filesets. .PP .zA "defect,6557,R1.0.2,Correct how CM handles unstored data" Occasionally, a File Server machine may be unavailable to the Cache Manager (possibly because the File Server machine is down or because a network problem prevents the Cache Manager from contacting the machine). In such cases, the Cache Manager cannot write data back to the File Server machine. The Cache Manager displays a message on the screen to notify the user that it cannot write the data to the unavailable machine. If possible, it also returns a failure code to the application program using the data. .PP The Cache Manager keeps the unstored data in the cache and continues to attempt to contact the File Server machine until it can store the data. (The frequency with which it attempts to reach a File Server machine is defined with the \*L-pollinterval\*O option of the \*Lfxd\*O command issued on that File Server machine.) In the meantime, corrective measures can be taken to alleviate the problem that prevents the data from being stored; for example, the File Server machine can be restarted. Once the problem is alleviated, the Cache Manager can reach the File Server machine and store the data. .zZ "defect,7219,R1.0.2,Review comments" .PP The Cache Manager discards unstored data only when .ML .LI It needs to make room in the cache for other data. Given an average-sized cache with average usage, the Cache Manager rarely needs to discard unstored data. .LI The \*Lcm resetstores\*O command is issued to force it to discard unstored data from the cache. .LE .PP Because unstored data discarded from the cache cannot be recovered, any problem that prevents data from being written to a File Server machine should be handled promptly. .PP Note that the \*Lcm resetstores\*O command affects only data that could not be stored to a File Server machine; it does not affect other data in the cache. Nonetheless, be cautious when issuing the \*Lcm resetstores\*O command: Issue the \*Lcm lsstores\*O command first to list the fileset ID numbers of filesets that contain data the Cache Manager cannot write to a File Server machine; examine the output of the command to be sure that you know from which filesets unstored data will be discarded (you may also be able to use this information to ensure that unstored data from the indicated filesets can safely be discarded). .zZ "defect,6557,R1.0.2,Correct how CM handles unstored data" .zA "defect,5933,R1.0.2,Include privilege required" .SS "Privilege Required" .PP .zA "defect,6557,R1.0.2,Correct how CM handles unstored data" The issuer must be logged in as \*Lroot\*O on the local machine. .zZ "defect,6557,R1.0.2,Correct how CM handles unstored data" .zZ "defect,5933,R1.0.2,Include privilege required" .SH "RELATED INFORMATION" .PP Commands: \*Lcm lsstores(1m)\*O, \*Lfxd(1m)\*O .iX "-]" "\*Lcm\*O command suite" "\*Lresetstores\*O" .iX "-]" "Cache Manager" "canceling update operations" .iX "-]" "Cache Manager" "discarding data" .iX "-]" "filesets" "canceling updates" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" CHANGED ...\" 12-10-91: Added text and an example to DESCRIPTION to document a cache ...\" size that is too small. Also added a new OUTPUT section with ...\" an additional output example. Finally, added example output ...\" to the two example commands in EXAMPLES. ...\" END CHANGED ...\" .rm zA .rm zZ .TH "cm setcachesize" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lcm\*O command suite" "\*Lsetcachesize\*O" .iX "-[" "disk cache" "setting size" .iX "-[" "cache" "disk, setting size" .iX "-[" "disk space" "setting cache size" .SH NAME .PP \*Lcm setcachesize\*O \- Sets the size of a disk cache .SH "SYNOPSIS" .sS \*Lcm setcachesize\*O {\*L-size \*Vkbytes\*O | \*L-reset\*O} [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-size \*Vkbytes\*O" Specifies the number of 1-kilobyte blocks the Cache Manager can use for the cache. The smallest allowable value is 1. Specifying a value of 0 (zero) sets the cache size to the default specified in the \*LCacheInfo\*O file. Use this option or use the \*L-reset\*O option. .LI "\*L-reset\*O" Returns the cache size to the value set when the machine was last booted. Use this option or use the \*L-size\*O option. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "enh,R1.0.2,Editorial improvements" The \*Lcm setcachesize\*O command changes the amount of local disk space the Cache Manager uses for its data cache. Specify a number of kilobyte blocks. Do not set the cache size to exceed 90% of the actual disk space available for the cache directory; the cache implementation itself requires a small amount of room on the partition. \*EDo not use this command on a machine using a memory cache.\*O .zZ "enh,R1.0.2,Editorial improvements" .PP The cache size cannot be set to a value less than twice the value of the chunk size in use by the Cache Manager. If a value smaller than twice the chunk size is specified with the \*L-size\*O option, the following message is displayed: .oS \*Epath\*O\*C: Cache size of\*O \*Esize\*O \*Cis too small; value was rounded up.\*O .oE .PP In the message, \*Epath\*O is the specified path to the \*Lcm\*O program (usually just \*Lcm\*O) and \*Esize\*O is the size, in kilobytes, specified with the command. The standard message reporting the new cache size (the size to which the cache was rounded) is then displayed; see the section on output for an example of the message. .PP .zA "enh,R1.0.2,Editorial improvements" To return the cache size to the default value specified in the \*LCacheInfo\*O file, specify 0 (zero) as the number of kilobyte blocks with the \*L-size\*O option. To return the cache size to the value set when the machine was last booted, use the \*L-reset\*O option instead of the \*L-size\*O option; the \*L-reset\*O option also sets the size to the amount specified in the \*LCacheInfo\*O file unless the \*L-blocks\*O option was used with the \*Ldfsd\*O command to override the \*LCacheInfo\*O value, in which case the value set with the \*Ldfsd\*O command is used. .PP The \*Lcm getcachesize\*O command displays the current cache size and the amount of space in use for both disk and memory caches. It also reports the type of cache (disk or memory) in use. .zZ "enh,R1.0.2,Editorial improvements" .SS "Privilege Required" .PP The issuer must be logged in as \*Lroot\*O on the local machine. .SH "OUTPUT" .PP The following message is displayed whenever this command is used to set the cache size: .oS \*Epath\*O\*C: New cache size set:\*O \*Esize\*O\*C.\*O .oE .PP In the message, \*Epath\*O is the specified path to the \*Lcm\*O program (usually just \*Lcm\*O) and \*Esize\*O is the new cache size, in kilobytes. .SH "EXAMPLES" .PP The following command sets the cache size to 25,000 kilobyte blocks: .iS \*C#\*O \*Lcm setca 25000\*O .PP \*Ccm: New cache size set: 25000.\*O .iE .PP The following command resets the cache size to the value set when the machine was last booted (50,000 kilobyte blocks, in this case): .iS \*C#\*O \*Lcm setca -r\*O .PP \*Ccm: New cache size set: 50000.\*O .iE .SH "RELATED INFORMATION" .PP .zA "enh,R1.0.2,Add CacheInfo file" Commands: \*Lcm getcachesize(1m)\*O, \*Ldfsd(1m)\*O .PP Files: \*LCacheInfo(4)\*O .zZ "enh,R1.0.2,Add CacheInfo file" .iX "-]" "\*Lcm\*O command suite" "\*Lsetcachesize\*O" .iX "-]" "disk cache" "setting size" .iX "-]" "cache" "disk, setting size" .iX "-]" "disk space" "setting cache size" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "cm setdevok" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lcm\*O command suite" "\*Lsetdevok\*O" .iX "-[" "device files" "specifying status" .iX "-[" "Cache Manager" "device file status" .SH NAME .PP \*Lcm setdevok\*O \- Specifies whether device files from specified filesets are honored by the Cache Manager .SH "SYNOPSIS" .sS \*Lcm setdevok\*O [\*L-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}...] [\*L-state\*O {\*Lon\*O | \*Loff\*O}] [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}" Names a file or directory from each fileset whose device file status is to be changed. If this option is omitted, the status is changed for the fileset containing the current working directory. .LI "\*L-state\*O" Specifies whether device files from the filesets indicated with \*L-path\*O are to be honored. Specify \*Lon\*O with this option to honor device files from the indicated filesets; specify \*Loff\*O with this option to prevent device files from the indicated filesets from being honored. If this option is omitted, device files from the filesets are honored (the command has no effect if device files were already honored). .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lcm setdevok\*O command specifies whether device files from the indicated filesets are honored by the Cache Manager. Indicate each fileset whose device files are to be honored or not honored by specifying the name of a file or directory in the fileset with the \*L-path\*O option. Device files are honored on a per-fileset and per-Cache Manager basis. This command is commonly included in a start-up file (\*L/etc/rc\*O or its equivalent) to honor device files at machine startup. .PP .zA "defect,7219,R1.0.2,Review comments" If \*Lon\*O is specified with the \*L-state\*O option, or if the \*L-state\*O option is omitted, the Cache Manager honors device files from the indicated filesets. If \*Loff\*O is specified with the \*L-state\*O option, the Cache Manager does not honor device files from the indicated filesets. By default, the Cache Manager does not honor device files from a fileset. (The UNIX kernel always honors device files stored in the \*L/dev\*O directory.) .zZ "defect,7219,R1.0.2,Review comments" .PP The \*Lcm getdevok\*O command displays whether the Cache Manager honors device files from indicated filesets. .SS "Privilege Required" .PP The issuer must be logged in as \*Lroot\*O on the local machine. .SH "EXAMPLES" .PP The following command causes device files that reside on the fileset that contains the directory \*L/.../abc.com/fs/usr/jlw\*O to be honored: .iS \*C# \*Lcm setdevok /.../abc.com/fs/usr/jlw\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lcm getdevok(1m)\*O .iX "-]" "\*Lcm\*O command suite" "\*Lsetdevok\*O" .iX "-]" "device files" "specifying status" .iX "-]" "Cache Manager" "device file status" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "cm setsetuid" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lcm\*O command suite" "\*Lsetsetuid\*O" .iX "-[" "\*Lsetuid\*O programs" "controlling" .iX "-[" "\*Lsetgid\*O programs" "controlling" .SH NAME .PP \*Lcm setsetuid\*O \- Enables or disables \*Lsetuid\*O programs from specified filesets .SH "SYNOPSIS" .sS \*Lcm setsetuid\*O [\*L-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}...] [\*L-state\*O {\*Lon\*O | \*Loff\*O}] [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}" Names a file or directory from each fileset whose \*Lsetuid\*O status is to be changed. If this option is omitted, the status is changed for the fileset containing the current working directory. .LI "\*L-state\*O" Allows or disallows \*Lsetuid\*O programs from the filesets indicated with \*L-path\*O to execute with \*Lsetuid\*O permission. Specify \*Lon\*O with this option to allow \*Lsetuid\*O programs from the indicated filesets to execute with \*Lsetuid\*O permission; specify \*Loff\*O with this option to disallow \*Lsetuid\*O programs from the indicated filesets to execute with \*Lsetuid\*O permission. If this option is omitted, \*Lsetuid\*O programs from the filesets are allowed to execute with \*Lsetuid\*O permission (the command has no effect if \*Lsetuid\*O permission was already enabled). .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lcm setsetuid\*O command enables \*Lsetuid\*O programs from the indicated filesets to execute with \*Lsetuid\*O permission or prevents them from executing with \*Lsetuid\*O permission. Indicate each fileset whose \*Lsetuid\*O permission is to be enabled or disabled by specifying the name of a file or directory in the fileset with the \*L-path\*O option. The permissions are enabled or disabled on a per-fileset and per-Cache Manager basis. This command is commonly included in a startup file (\*L/etc/rc\*O or its equivalent) to enable \*Lsetuid\*O programs at machine startup. .PP If \*Lon\*O is specified with the \*L-state\*O option, or if the \*L-state\*O option is omitted, the Cache Manager allows \*Lsetuid\*O programs from the indicated filesets to execute with \*Lsetuid\*O permission. If \*Loff\*O is specified with the \*L-state\*O option, the Cache Manager does not allow \*Lsetuid\*O programs from the indicated filesets to execute with \*Lsetuid\*O permission. By default, the Cache Manager does not allow \*Lsetuid\*O programs from a fileset to execute with \*Lsetuid\*O permission. .PP A \*Lsetuid\*O program is indicated by setting a mode bit associated with an executable file. While a \*Lsetuid\*O program executes, the person executing the program is treated as if he or she is the owner of the program. The effective user identification number (UID) of the executing program is the UID of the person who owns the program, not the UID of the person who initiated the program's execution. Thus, the person executing the program is granted the same permissions as the person who owns the program for the duration of the program's execution. .PP .zA "defect,7219,R1.0.2,Review comments" Note that \*Lsetuid\*O programs are effective only in the local environment. A \*Lsetuid\*O program can change only the local identity under which a program runs; it cannot change the DCE identity with which a program executes because it provides no Kerberos tickets. DCE does not recognize the change to the local identity associated with a \*Lsetuid\*O program. .zZ "defect,7219,R1.0.2,Review comments" .PP The \*Lcm setsetuid\*O enables or disables \*Lsetgid\*O programs from the indicated filesets at the same time that it changes the status of \*Lsetuid\*O programs. The \*Lcm getsetuid\*O command displays whether the Cache Manager allows \*Lsetuid\*O and \*Lsetgid\*O programs from indicated filesets to execute. .SS "Privilege Required" .PP The issuer must be logged in as \*Lroot\*O on the local machine. .SH "EXAMPLES" .PP The following command enables \*Lsetuid\*O and \*Lsetgid\*O programs that reside on the fileset containing the directory \*L/.../abc.com/fs/usr/jlw\*O: .iS \*C# \*Lcm setsetuid /.../abc.com/fs/usr/jlw\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lcm getsetuid(1m)\*O .iX "-]" "\*Lcm\*O command suite" "\*Lsetsetuid\*O" .iX "-]" "\*Lsetuid\*O programs" "controlling" .iX "-]" "\*Lsetgid\*O programs" "controlling" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\"Copyright (C) 1989, 1991, Transarc Corporation ...\"The Gulf Tower ...\"707 Grant Street ...\"Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "cm statservers" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lcm\*O command suite" "\*Lstatservers\*O" .iX "Cache Manager" "Checking File Server status" .iX "File Server machines" "checking status" .SH NAME .PP \*Lcm statservers\*O \- Checks the statuses of File Server machines .SH "SYNOPSIS" .PP .sS \*Lcm statservers\*O \*O[{\*L-cell\*O \*Vcellname\*O | \*L-all\*O}] \*O[\*L-fast\*O] \*O[\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-cell \*Vcellname\*O" Specifies the name of the specific cell the Cache Manager is to probe for the status of each File Server machine it has contacted or has attempted to contact from that cell. The Cache Manager probes only machines in the specified cell. Use this option or use the \*L-all\*O option; omit both options to direct the Cache Manager to probe only machines in the local cell. .LI "\*L-all\*O" Directs the Cache Manager to probe all of the machines it has contacted in all cells. Use this option or use the \*L-cell\*O option; omit both options to direct the Cache Manager to probe only machines in the local cell. .LI "\*L-fast\*O" Directs the Cache Manager to display its current list of contacted File Server machines without probing the machines. This option can be combined with the \*L\-cell\*O or \*L\-all\*O option; it can also be used if both the \*L\-cell\*O and \*L\-all\*O options are omitted. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lcm statservers\*O command lists all File Server machines in the indicated cells that meet the following two conditions: .ML .LI The Cache Manager has been in contact with the File Exporter running on the machine and needs to contact it in the future (probably because the Cache Manager is holding tokens for data on that File Server machine). .LI The File Exporter on the machine is not currently responding to the Cache Manager's probes (implying that it is not responding to the Cache Manager's requests for data either). .LE .PP The Cache Manager maintains a list of File Server machines that meet the first condition, updating the list periodically by attempting to contact the File Exporter on each machine in the list. When a machine does not respond to a probe, the Cache Manager marks it as nonfunctioning. If a machine that previously did not respond begins to respond again, the Cache Manager erases the mark. The Cache Manager maintains this information in the kernel of the local machine. .PP Without the \*L-fast\*O option, this command forces the Cache Manager to update its information immediately (rather than waiting the standard interval). The Cache Manager probes the File Exporters on the machines in the specified cells, records those that do not respond, and reports the results. If you include the \*L-fast\*O option, the Cache Manager displays the list of nonfunctioning machines that it has at the time the command is issued; it does not probe the machines again. .PP By default, the Cache Manager probes machines in the local cell only. If the \*L-all\*O option is used, the Cache Manager probes all machines (from all cells) that meet the first condition. If a \*Ecellname\*O is specified with the \*L-cell\*O option, the Cache Manager probes only the machines in that cell. .PP The execution of this command can be lengthy if a number of machines in the Cache Manager's list are unresponsive when the command is issued. The Cache Manager waits a standard time-out period before concluding that a File Exporter is not responding; this allows for the possibility of slow cross-network communication. If it is important that the command shell prompt return quickly, run this command in the background. It is harmless to interrupt the command (with \*L\*O or another interrupt signal). .PP This command does not check the statuses of all File Server machines in a cell. The Cache Manager probes only those machines that meet the first condition in the previous list. .SS "Privilege Required" .PP No privileges are required. .SH "OUTPUT" .PP .zA "defect,10440,R1.1,Incorporate information from User's Guide" If the Cache Manager gets a response from all of the machines that it probes (that is, all such machines are functioning normally), the command displays the following output: .oS All servers are running. .oE .PP This message does not imply that all File Server machines in the specified cells are running; it implies only that those machines that the Cache Manager probed are running. .PP If one or more machines fail to respond to the Cache Manager's probes within the time-out period, the command displays the following output: .oS \*CThese servers are still down: \*Vhostname\*O .oE .PP where \*Vhostname\*O is the name of each File Server machine that fails to respond. .zZ "defect,10440,R1.1,Incorporate information from User's Guide" .SH "EXAMPLES" .PP .zA "defect,10440,R1.1,Incorporate information from User's Guide" The following command uses the \*L-fast\*O option to view the Cache Manager's current list of unresponsive machines belonging to the local cell rather than waiting for the Cache Manager to probe them again. The output indicates that all machines responded to the most recent probes. .iS \*C$ \*Lcm statservers -f\*O .iE .oS All servers are running. .oE The following command checks all File Server machines from which the Cache Manager has cached data, regardless of the cell in which a machine resides. The command reports that the machines named \*Lfs1.abc.com\*O and \*Lfs3.state.edu\*O did not respond to the Cache Manager's probes. The \*L&\*O (ampersand) is used to execute the command in the background. .iS \*C$ \*Lcm statservers -all &\*O .iE .oS These servers are still down: fs1.abc.com fs3.state.edu .oE .zZ "defect,10440,R1.1,Incorporate information from User's Guide" .SH "RELATED INFORMATION" .PP Commands: \*Lcm lsstores(1m)\*O, \*Lcm whereis(1m)\*O .iX "-]" "\*Lcm\*O command suite" "\*Lstatservers\*O" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the .\" src directory for the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\"Copyright (C) 1989, 1991, Transarc Corporation ...\"The Gulf Tower ...\"707 Grant Street ...\"Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "cm sysname" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" CHANGED ...\" 12-10-91: In OUTPUT, changed the single quote at the end of the example ...\" output to an apostrophe. ...\" 12-10-91: In EXAMPLES, added the /usr element to two output lines. ...\" END CHANGED .iX "-[" "\*Lcm\*O command suite" "\*Lsysname\*O" .iX "-[" "\*L@sys\*O variable" "current setting" .SH NAME .PP \*Lcm sysname\*O \- Reports or sets the CPU/OS type .SH "SYNOPSIS" .sS \*Lcm sysname\*O [\*L-newsys \*Vsysname\*O] [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-newsys \*Vsysname\*O" Specifies the new setting of the CPU/Operating System (\*L@sys\*O) variable for the machine on which it is issued. If this option is omitted, the output shows the current setting of the variable. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lcm sysname\*O command displays the current setting of the \*L@sys\*O variable or sets the variable on a client machine. If the \*L-newsys\*O option is omitted, the command reports the current setting of the \*L@sys\*O variable. If the \*L-newsys\*O option is included, the command sets the variable to the specified CPU/OS type. The value of the variable is displayed from or set in the kernel of the client machine on which the command is issued. .PP The Cache Manager's main use of the \*L@sys\*O variable is in pathnames used in symbolic links. As the Cache Manager interprets pathnames, it substitutes the value of the indicator for any occurrence of \*L@sys\*O. (Use the \*L@sys\*O variable sparingly; it can make the effect of changing directories confusing.) .SS "Privilege Required" .PP To view the current setting of \*L@sys\*O (without the \*L-newsys\*O option), no privileges are required. To change the setting of \*L@sys\*O (with the \*L-newsys\*O option), you must be logged in as \*Lroot\*O on the local machine. .SH "OUTPUT" .PP If the \*L-newsys\*O option is not specified, the output reports the system type in the following format: .oS \*CCurrent sysname is `\*Esystem_type\*C'.\*O .oE .SH "EXAMPLES" .PP The following command shows the output produced on a machine running OSF/1: .iS \*C$ \*Lcm sys\*O .iE .oS .zA "defect,7715,R1.0.3,Correct sysname examples" \*CCurrent sysname is `pmax_osf1'.\*O .zZ "defect,7715,R1.0.3,Correct sysname examples" .oE .PP The following commands set the system type on a machine running AIX 3.2 and use it in a symbolic link from the \*L/usr/local\*O directory on the local machine to a directory in the DFS filespace: .zA "defect,7715,R1.0.3,Correct sysname examples" .zA "defect,7219,R1.0.2,Review comments" .iS \*C# \*Lcm sys -new rs_aix32\*O \*C# \*Lln -s /.../abc.com/fs/@sys/usr/local /usr/local\*O \*C# \*Lls -l /usr/local\*O .iE .oS \*Clrwxrwxrwx 1 root 34 May 31 1993 /usr/local -> \*C/.../abc.com/fs/@sys/usr/local\*O .oE .iS \*C# \*Lcd /usr/local\*O \*C# \*Lpwd\*O .iE .oS \*C/.../abc.com/fs/rs_aix32/usr/local\*O .oE .zZ "defect,7219,R1.0.2,Review comments" .zZ "defect,7715,R1.0.3,Correct sysname examples" .iX "-]" "\*Lcm\*O command suite" "\*Lsysname\*O" .iX "-]" "\*L@sys\*O variable" "current setting" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\"Copyright (C) 1989, 1991, Transarc Corporation ...\"The Gulf Tower ...\"707 Grant Street ...\"Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "cm whereis" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lcm\*O command suite" "\*Lwhereis\*O" .iX "files" "locating" .iX "directories" "locating" .SH NAME .PP \*Lcm whereis\*O \- Reports names of File Server machines that house specified files or directories .SH "SYNOPSIS" .PP .sS \*Lcm whereis \*O[\*L-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}...] [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-path \*Vfilename\*O or \*Vdirectory_name\*O" Specifies the pathname of each file or directory whose location is to be reported. Each file or directory must reside in DFS, not on a local disk. If a full pathname is not provided, the file or directory is assumed to reside in the current working directory. If this option is omitted, the current working directory is used. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lcm whereis\*O command displays information about the location of each file or directory indicated with the \*L\-path\*O option. The command reports the name of the cell in which the file or directory exists, the name of the fileset in which it resides, and the name of each File Server machine that houses a copy of the fileset. This information comes from the kernel of the workstation on which the command is issued. .SS "Privilege Required" .PP No privileges are required. .SH "OUTPUT" .PP .zA "defect,10440,R1.1,Incorporate information from User's Guide" The output includes a separate line displaying the following information about each file or directory specified with the \*L\-path\*O option: .oS File `\*Vfilename\*C' resides in the cell `\*Vcellname\*C' in fileset `\*Vfileset_name\*C' on host(s) `\*Vhostname\*C'. .oE .PP In the output .VL .LI "\*Vfilename\*O" Specifies the complete pathname of a file or directory specified with the \*L\-path\*O option. .LI "\*Vcellname\*O" Specifies the name of the cell in which the file or directory is located. .LI "\*Vfileset_name\*O" Specifies the name of the fileset in which the file or directory is located. .LI "\*Vhostname\*O" Specifies the name of the File Server machine on which the fileset is located. If the fileset is a read/write or backup fileset, only one machine name is displayed; if the fileset is a read-only fileset, multiple machine names can be displayed. .LE .zZ "defect,10440,R1.1,Incorporate information from User's Guide" .SH "EXAMPLES" .PP The following command indicates that the directory named \*L/.../abc.com/fs/bin/sysfile\*O is located in a replicated fileset on the File Server machines named \*Lfs1\*O, \*Lfs3\*O, and \*Lfs6\*O, all of which are located in the cell named \*Labc.com\*O: .iS \*C$ \*Lcm whereis /.../abc.com/fs/bin/sysfile\*O .iE .oS File `/.../abc.com/fs/bin/sysfile' resides in the cell `abc.com', in fileset `sysfile.bin', on hosts fs1.abc.com, fs3.abc.com, fs6.abc.com. .oE .SH "RELATED INFORMATION" .PP Commands: \*Lcm statservers(1m)\*O .iX "-]" "\*Lcm\*O command suite" "\*Lwhereis\*O" .\" $Header: config.1m,v 78.1 96/01/19 20:10:40 ssa Exp $ .TA c .TH config 1M "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME config \- configure and build an \s-1HP-UX\s0 system .SH SYNOPSIS .C /usr/sbin/config .RC [ -c .IR c_file ] .RC [ -l .IR m_file ] .RC [ -m .IR master_file ] .RC [ -r .IR path ] .ifn .br .ifn \0\0\0\0 .RC [ -s ] .RC [ -t ] .I system_file .br .SH DESCRIPTION .C config is used to configure the following parts of the operating system: .RS .TP 3 \(bu Device drivers .PD 0 .TP \(bu Swap and dump devices .TP \(bu Tunable system parameters .PD .RE .PP .C config reads a user-provided description of an HP-UX system .RI ( system_file ) and a master kernel configuration information table and generates two output files: .RS .TP 3 \(bu A C program source file that defines the configuration tables for various parts of the system. .TP \(bu A makefile (see .IR make (1)) to compile the C program produced and relink the newly configured system. .RE .PP Lastly .C config executes the .IR make command to compile .C conf.c and link the kernel .RC ( vmunix ) with the appropriate kernel libraries. File .C vmunix can then be booted. See the .I HP-UX System Administrator Manuals for information on how to include or remove a subsystem or file system, and how to boot the system. .PP Many header files are needed to compile .C conf.c. Also, archive library files containing the kernel objects are needed to link the kernel. These files are supplied with the system and are contained in the directories found under .CR /usr/conf . .RE .SS Command Line Arguments The .C config command recognizes the following arguments: .PP .RS .TP 15 .CI -c " c_file" Specify the name of the C program source file produced by .CR config . The default file name is .CR conf.c . .TP .CI -l " m_file" Specify the name of the makefile which is generated by .CR config . This is the makefile which will be used by .CR config to compile the C program source file and make the new kernel. The default file name is .CR config.mk . .TP .CI -m " master" Specify the name of the master kernel configuration information file or directory that config should use in creating .C conf.c and .CR config.mk . If .I master is a directory, .CR config reads all files in that directory to create its data structures. If .I master is a file, only that file is read for creating data structures for .CR config . By default, .CR config reads the files in the directory .CR/usr/conf/master.d . .C /usr/conf/master.d is supplied as part of the HP-UX operating system and should not be modified by anyone who does not fully understand its structure and purpose. .TP .CI -r " path" Search the directory .I path for the libraries and header files needed for making the kernel. By default, .CR config uses the directory .I /usr/conf . .TP .C -s Stop after creating .C conf.c and .CR config.mk . .IR make is not executed and a kernel ( .CR vmunix ) is not created. .TP .C -t Give a short table of major device numbers for the character and block devices, the card drivers, the streams drivers and modules which require link routines, the streams devices and the streams modules named in .IR system_file . These tables may be useful when creating special device files. .TP .I system_file The file containing configuration information for the user's system. The default .I system_file is .C /stand/system and when this file is used as input to config, the resulting output is placed in the directory .CR /stand/build . If a file other than .C /stand/system is used for the .IR system_file , .C config places its output files in the current directory. The .I system_file is divided into two parts: the first part (mandatory) contains driver specifications, and the second part (optional) contains system-dependent information. .SS Constructing \f4system_file\fP: First Part The first part of .I system_file is used to configure: .RS .TP 3 \(bu Device drivers .PD 0 .TP \(bu Pseudo-drivers .TP \(bu Subsystems .PD .RE .PP Each line has the following format: .IP .I devname .PP where .I devname is the driver or subsystem name as it appears in the alias tables, driver install tables or the device tables in the files in the directory .CR /usr/conf/master.d . For example, .C scsi selects the driver for SCSI disk drives, .C scsitape selects the driver for SCSI tape drives, and .C nfs selects the NFS subsystem. Together, the files in .C /usr/conf/master.d contain a complete list of configurable devices, cards, subsystems, and pseudo-drivers. .SS Constructing \f4system_file\fP: Optional Second Part The second part of .I system_file is used to: .RS .TP 3 \(bu Define the swap device. .PD 0 Define the dump device(s). .PD 0 .TP \(bu Provide a mapping of a driver to a hardware path. .TP \(bu Define status and values of selected system parameters. .PD .RE .PP Lines are constructed as indicated below for each category. .PP .B 1. Swap device specification .RS .PP No more than one swap specification is allowed. If a swap specification is not given, the system will be configured to swap on the root device at the end of the filesystem. .RS .C swap < .I hw_path > < .I offset > [< .I blocks >] .PP Configure the swap device location and its size as specified. Arguments are interpreted as follows: .RS .TP 12 .I hw_path The hardware path representing the device to configure as the swap device or the string .C default may be used to indicate using the root device. .TP .I offset The swap area location. Boundaries are located at 1K-byte intervals. A negative value specifies that a file system is expected on the device. At boot-up, the super block is read to determine the exact size of the file system, and this value is put in .IR offset . If the swap device is auto-configured, this is the mechanism used. If the super block is invalid, the entry will be skipped, so that a corrupted super block will not later cause specifies the minimum area that must be reserved. Zero means to reserve no area at the head of the device. .IR "A zero value implies that there is no file system on the device" . .TP .I blocks The number (in decimal) of 1K-byte disk blocks in the swap area. For this swap device specification, only the .I blocks parameter is optional. Zero is the default for auto-configuration. .IP If .I blocks is zero, the entire remainder of the device is automatically configured in as swap area. .IP If .I blocks is non-zero, its absolute value is treated as an upper bound for the size of the swap area. Then, if the swap area size has actually been cut back, the sign of .I blocks determines whether .I blocks remains as is, resulting in the swap area being adjacent to the reserved area, or whether .I blocks is bumped by the size of the unused area, resulting in the swap area being adjacent to the tail of the device. .RE .CR swap < .I hw_path > < .I options > .PP Configure the swap device at the location specified using the options specified. The .I hw_path argument is interpreted as it is in the previous example. The .I options argument is interpreted as follows: .RS .TP 12 .I options This field is used to specify a section. It is only offered for backwards compatibility purposes. For example, .C s3 would put the swap area on section 3. .RE .C swap lvol .PP Configure swap on a logical volume. .PP .C swap none .PP Configure the kernel with no swap device. .RE .RE .PP .B 2. Dump device(s) specification .RS .PP One or more dump specification is allowed. If a dump specification is not given, then the primary swap area will be used. .RS .C dump < .I hw_path > [< .I options > ] .PP Configure the dump device location and its size as specified. Arguments are interpreted as follows: .RS .TP 12 .I hw_path The hardware path representing the device to configure as a dump device or the string .C default may be used to indicate using the primary swap area. .TP 12 .I options This field is used to specify a section. It is only offered for backwards compatibility purposes. For example, .C s3 would put the dump area at section 3. .RE .C dump lvol .PP Configure dump on a logical volume. .PP .C dump none .PP Configure the kernel with no dump device. .RE .RE .B 3. Device driver to hardware path specification .RS .PP One or more driver to hardware path specifications is allowed. If a driver statement is provided the specified software module will be forced into the kernel I/O system at the given hardware path. This can be used to make the system recognize a device that could not be recognized automatically. .RS .C driver < .I hw_path > < .I driver_name > .PP Bind the driver into the kernel I/O system at the given hardware path. Arguments are interpreted as follows: .RS .TP 12 .I hw_path The hardware path representing the device to bind the software with. .TP 12 .I driver_name The name of the software module to bind into the kernel at the specified hardware path. .RE .RE .RE .B 4. System parameters .RS .PP These parameters should not be modified without a full understanding of the ramifications of doing so (see the .I HP-UX .I System Administrator Tasks Manual for information about each parameter). .PP Each line contains two fields. The first field can contain up to 20 characters, maximum; the second field up to 60 characters, maximum. Each line is independent, optional, and written in the following format: .RS .PP .TS lb li. parameter_name number or formula .TE .RE .PP System V interprocess communication consists of messages .RC ( mesg ), semaphores .RC ( sema ) and shared memory .RC ( shmem ) features. .PP If .CR mesg , .CR sema , and/or .C shmem are specified as .CR 0 , the kernel code for these features is not included. If they are specified as .CR 1 , the kernel code is included; this is the default. The features can be specified independent of each other. If the code is included, the parameters listed below can be modified: .PP .RS .TS lf4p+1 li. mesg \f31\f1 msgmap number or formula msgmax number or formula msgmnb number or formula msgmni number or formula msgseg number or formula msgssz number or formula msgtql number or formula .sp .5v sema \f31\f1 semaem number or formula semmap number or formula semmni number or formula semmns number or formula semmnu number or formula semume number or formula semvmx number or formula .sp .5v shmem \f31\f1 shmall number or formula smbrk number or formula shmmax number or formula shmmin number or formula shmmni number or formula shmseg number or formula .TE .RE .SH FILES .TP 40 .C /usr/conf/master.d/* default input master kernel configuration tables .PD 0 .TP .C /usr/conf/config.sys contains skeleton makefile .TP .C /stand/system default system_file .TP .C /stand/build/conf.c default output configuration table .TP .C /stand/build/config.mk default output .IR make (1) script .TP .C /stand/build/vmunix default kernel made by .C config .PD .SH SEE ALSO make(1), master(4). .\" .\" index@\f4config\f1 \- configure an \s-1HP-UX\s+1 system@@@\f3config(1M)\f1 .\" index@configure an \s-1HP-UX\s+1 system@@@\f3config(1M)\f1 .\" index@root device, configure or reconfigure@@@\f3config(1M)\f1 .\" index@swap device, configure or reconfigure@@@\f3config(1M)\f1 .\" index@\s-1I/O\s+1 device, configure or reconfigure@@@\f3config(1M)\f1 .\" index@kernel configuration, configure or reconfigure@@@\f3config(1M)\f1 .\" index@parameters, system, configure or reconfigure@@@\f3config(1M)\f1 .\" index@system parameters, configure or reconfigure@@@\f3config(1M)\f1 .\" .\" toc@\f3config(1M)\f1:\0\0\f4config\f1@@@configure an HP-UX system .\" .\" $Header: convert_awk.1m,v 1.1.113.3 97/05/23 06:00:39 sita Exp $ .TA c .TH convert_awk 1M .SH NAME /usr/newconfig/etc/mail/convert_awk \- Converts old sendmail.cf files to new format. .SH SYNOPSIS .C convert_awk .SH DESCRIPTION .C convert_awk is an .CR awk program that will convert pre-HP-UX 10.20 .CR sendmail.cf files into the format required by the HP-UX 10.20 .CR sendmail .RC ( sendmail 8.7 and up). .PP To run it, use: .IP .CI "awk -f convert_awk < " old.cf " > new.cf" .PP Note that the new sendmail.cf files offer a wealth of new options and features. You should STRONGLY consider making a new .CR sendmail.cf file from the distribution version or from the .CR m4 macros, which are provided in HP-UX 10.20 in .CR /usr/newconfig/etc/mail/cf . .PP .SH CAVEAT The configuration file generated by this .CR convert_awk script has been tested only for SMTP and Openmail delivery agents. If you find any problem while using with UUCP, please use the sendmail.cf supplied in .CR /usr/newconfig/etc/mail directory. .PP .SH SEE ALSO sendmail(1M). .\" .\" index@\f4convert_awk\f1 \- converts old sendmail.cf files to new format@@@\f3convert_awk(1M)\f1 .\" index@\f1converts old sendmail.cf files to new format@@@\f3convert_awk(1M)\f1 .\" index@\f1sendmail.cf files, convert to new format@@@\f3convert_awk(1M)\f1 .\" .\" toc@\f3convert_awk(1M)\f1:\0\0\f4convert_awk\f1@@@converts old sendmail.cf files to new format .\" $Header: convertfs.1m,v 72.6 94/11/29 05:53:00 ssa Exp $ .TA c .TH convertfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME convertfs \- convert an .SM HFS file system to allow long file names .SH SYNOPSIS .C /usr/sbin/convertfs .RC [ -q ] .RI [ \|special-file\| ] .SH DESCRIPTION The .CR convertfs command converts an existing .SM HFS file system supporting the default maximum file name length of 14 characters into one that supports file names up to 255 characters long. Once an .SM HFS file system is converted to long file names, it cannot be restored to its original state, since the longer file names require a directory representation that is incompatible with the default .SM HFS directory format. Since this is an irreversible operation, .C convertfs prompts for verification before it performs a conversion. .PP .C convertfs forces the system to reboot if the root file system is converted. When converting the root file system, the system should be in single-user mode, with all unnecessary processes terminated and all non-root file systems unmounted. Except for the root file system, .C convertfs requires that the file system to be converted be unmounted. .PP If invoked without arguments, .C convertfs interactively prompts the user with a list of the .SM HFS file systems from .CR /etc/fstab . One or more or all of the listed file systems can be selected for conversion. Typically, it is desirable to convert all of the file systems in .C /etc/fstab to avoid inconsistencies between two file systems mounted on the same system. .PP .C convertfs can also be invoked with an argument of either a block or character .I special-file of a file system to be converted. Only the block special file should be specified for a mounted root file system. .PP As part of the conversion process, .C convertfs performs an .C fsck on each file system (see .IR fsck (1M)). .SS Options .TP 10 .CR -q Do quietly. .CR convertfs will perform the conversions without querying the user. Normally .CR convertfs prompts the user before converting a file system. .SH RETURN VALUE .CR convertfs returns the following values: .RS .TP 10 .CR \00 Success. Either .CR convertfs successfully converted the file system, or the file system already allowed long file names. .TP .CR non-0 Failure. .CR convertfs was not able to convert the file system due to some failure in processing. .SH AUTHOR .CR convertfs was developed by HP. .SH FILES .TP 20 .CR /etc/fstab Default list of file systems to check. .SH SEE ALSO fsck(1M), mkfs(1M), newfs(1M), fs(4), fstab(4). .\" .\" index@\f4convertfs\f1 \- convert a file system to allow long file names@@@\f3convertfs(1M)\f1 .\" index@convert a file system to allow long file names@@@\f3convertfs(1M)\f1 .\" index@file system: convert a file system to allow long file names@@@\f3convertfs(1M)\f1 .\" index@long file names, convert a file system to allow@@@\f3convertfs(1M)\f1 .\" index@file names, long, convert a file system to allow@@@\f3convertfs(1M)\f1 .\" .\" toc@\f3convertfs(1M)\f1:\0\0\f4convertfs\f1@@@convert a file system to allow long file names .\" .\" fileset_database@convertfs.1m SYS-ADMIN-MAN .\" .\" links@convertfs.1m convertfs_hfs.1m .\" $Header: convertfs.1m,v 72.6 94/11/29 05:53:00 ssa Exp $ .TA c .TH convertfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME convertfs \- convert an .SM HFS file system to allow long file names .SH SYNOPSIS .C /usr/sbin/convertfs .RC [ -q ] .RI [ \|special-file\| ] .SH DESCRIPTION The .CR convertfs command converts an existing .SM HFS file system supporting the default maximum file name length of 14 characters into one that supports file names up to 255 characters long. Once an .SM HFS file system is converted to long file names, it cannot be restored to its original state, since the longer file names require a directory representation that is incompatible with the default .SM HFS directory format. Since this is an irreversible operation, .C convertfs prompts for verification before it performs a conversion. .PP .C convertfs forces the system to reboot if the root file system is converted. When converting the root file system, the system should be in single-user mode, with all unnecessary processes terminated and all non-root file systems unmounted. Except for the root file system, .C convertfs requires that the file system to be converted be unmounted. .PP If invoked without arguments, .C convertfs interactively prompts the user with a list of the .SM HFS file systems from .CR /etc/fstab . One or more or all of the listed file systems can be selected for conversion. Typically, it is desirable to convert all of the file systems in .C /etc/fstab to avoid inconsistencies between two file systems mounted on the same system. .PP .C convertfs can also be invoked with an argument of either a block or character .I special-file of a file system to be converted. Only the block special file should be specified for a mounted root file system. .PP As part of the conversion process, .C convertfs performs an .C fsck on each file system (see .IR fsck (1M)). .SS Options .TP 10 .CR -q Do quietly. .CR convertfs will perform the conversions without querying the user. Normally .CR convertfs prompts the user before converting a file system. .SH RETURN VALUE .CR convertfs returns the following values: .RS .TP 10 .CR \00 Success. Either .CR convertfs successfully converted the file system, or the file system already allowed long file names. .TP .CR non-0 Failure. .CR convertfs was not able to convert the file system due to some failure in processing. .SH AUTHOR .CR convertfs was developed by HP. .SH FILES .TP 20 .CR /etc/fstab Default list of file systems to check. .SH SEE ALSO fsck(1M), mkfs(1M), newfs(1M), fs(4), fstab(4). .\" .\" index@\f4convertfs\f1 \- convert a file system to allow long file names@@@\f3convertfs(1M)\f1 .\" index@convert a file system to allow long file names@@@\f3convertfs(1M)\f1 .\" index@file system: convert a file system to allow long file names@@@\f3convertfs(1M)\f1 .\" index@long file names, convert a file system to allow@@@\f3convertfs(1M)\f1 .\" index@file names, long, convert a file system to allow@@@\f3convertfs(1M)\f1 .\" .\" toc@\f3convertfs(1M)\f1:\0\0\f4convertfs\f1@@@convert a file system to allow long file names .\" .\" fileset_database@convertfs.1m SYS-ADMIN-MAN .\" .\" links@convertfs.1m convertfs_hfs.1m .\" $Header: cpset.1m,v 72.4 94/07/05 15:49:33 ssa Exp $ .TA c .TH cpset 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cpset \- install object files in binary directories .SH SYNOPSIS .CR cpset .RC [ -o ] .I object directory .RC [ -\c .I mode .RC [ -\c .I owner .RC [ -\c .IR group "]\|]\|]" .SH DESCRIPTION The .CR cpset command installs the specified .I object file in the given .IR directory . The .IR mode , .IR owner , and .IR group , of the destination file can be specified on the command line. If this data is omitted, two results are possible: .RS 2 .TP 3 \(bu If you have administrative permissions (that is, your numerical ID is less than 100), the following defaults are provided: .RS .RS .TP 10 .PD 0 .I mode .CR 0555 .TP .I owner .CR bin .TP .I group .CR bin .PD .RE .RE .TP \(bu If you do not have administrative permissions, the default .IR mode , .IR owner , and .IR group of the destination file are the same as yours. .RE .PP The .CR -o option forces .CR cpset to move .I object to .CI OLD object in the destination directory before installing the new object. .PP .CR cpset reads the .CR /etc/src/destinations file to determine the final destination of the file to be installed. The .CR destinations file contains pairs of path names separated by spaces or tabs. The first name is the "official" destination (for example: .CR /usr/bin/echo ). The second name is the new destination. If .CR echo is moved from .CR /usr/bin to .CR /usr/local/bin , the entry in .CR destinations would be: .IP .C "/usr/bin/echo /usr/local/bin/echo" .PP When the actual installation happens, .CR cpset verifies that the "old" pathname does not exist. If a file exists at that location, .CR cpset issues a warning and continues. .PP This file does not exist on a distribution tape; it is used by sites to track local command movement. The procedures used to build the source are responsible for defining the "official" locations of the source. .SS Cross Generation The environment variable .CR ROOT is used to locate the destination file (in the form .CR $ROOT/etc/src/destinations ). This is necessary in the cases where cross generation is being done on a production system. .SH EXAMPLES If you are an administrator, all of the following examples have the same effect. They copy file .CR echo into .CR /usr/bin with .IR mode , .IR owner , and .I group set to .CR 0555 , .CR bin , .CR bin , respectively: .IP .C "cpset echo /usr/bin 0555 bin bin" .IP .C "cpset echo /usr/bin" .IP .C "cpset echo /usr/bin/echo" .PP If you are not an administrator, the last two examples set .IR mode , .IR owner , and .I group to your current values. .SH SEE ALSO chacl(1), make(1), install(1M), acl(5). .\" .\" index@\f4cpset\f1 \- install object files in binary directories@@@\f3cpset(1M)\f1 .\" index@install object files in binary directories@@@\f3cpset(1M)\f1 .\" index@object files in binary directories, install@@@\f3cpset(1M)\f1 .\" index@files, object code: install in binary directories@@@\f3cpset(1M)\f1 .\" index@binary directories, install object files in@@@\f3cpset(1M)\f1 .\" index@directories, binary, install object files in@@@\f3cpset(1M)\f1 .\" .\" toc@\f3cpset(1M)\f1:\0\0\f4cpset\f1@@@install object files in binary directories ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Oct 25, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH create 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldtscp\*O commands" "\*Lcreate\*O" .iX "DTS servers" "creating" .iX "DTS clerks" "creating" .SH NAME .PP \*Lcreate\*O - Creates the DCE DTS entity on the specified node .SH "SYNOPSIS" .PP .zA "defect,6211,R1.0.3,add control program name" .sS \*Ldtscp create \*Ltype \*Vtype\*O .sE .zZ "defect,6211,R1.0.3,add control program name" .PP .SH "OPTIONS" .VL .LI "\*Ltype\*O \*Vtype\*O" Specifies the type of DCE DTS entity to be created on the specified node. Specify one of the following for \*Vtype\*O: .VL .LI "\*Lclerk\*O" The DCE DTS entity is created as a clerk. (The default setting is \*Lclerk\*O.) .LI "\*Lserver\*O" The DCE Distributed Time Service entity is created as a server. .LE .LE .SH "DESCRIPTION" .PP The \*Lcreate\*O command creates a time server or time clerk entity on the system where the command is entered. .zA "defect,7837,R1.0.3,added info on relationship between create and enable" .PP After the DTS entity is created, it is still in a non-functioning state. To put it into operation, you must invoke \*Ldtscp enable\*O, which causes an immediate synchronization to take place. For more information, see the \*Lenable\*O reference page in this chapter. .zZ "defect,7837,R1.0.3,added info on relationship between create and enable" .PP .SS "Privilege Required" .PP You must have write permission on the ACL associated with the DTS entity in order to execute the command. ...\".SH "EXIT VALUE" ...\".PP ...\".VL 8m ...\".LI "Already Exists" ...\"The command failed because the entity is already ...\"created. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .iS \*Cdtscp>\*O \*Lcreate type server\*O .iE ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "create child"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX"\*Lcdscp\*O commands" "\*Lcreate child\*O" .iX "child pointers" "creating" .iX "directories" "child pointers (CDS)" .SH NAME .PP \*Lcreate child\*O - Creates a child pointer at the master replica of the parent directory .wH "" .SH "SYNOPSIS" .PP \*Lcdscp create child\*O \*Vchild-name \*Lclearinghouse\*O \*Vclearinghouse-name\*O \*O\*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vchild-name\*O" The full name of the child pointer. .LI "\*Vclearinghouse-name\*O" The full name of a clearinghouse that contains a replica of the child directory. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lcreate child\*O command creates a child pointer at the master replica of the parent directory. When CDS looks up a name in the namespace, it uses child pointers to locate directory replicas. .zA "defect,7227,R1.0.2,Added text" Use the \*Lset cdscp preferred clearinghouse\*O command before issuing this command to ensure that the request is directed to the master replica. .zZ "defect,7227,R1.0.2,Added text" .SS "Privilege Required" .PP You must have insert permission to the parent directory. .SH "NOTES" .PP Use the \*Lcreate child\*O command only to re-create a child pointer that is accidentally deleted. This command is designed only for troubleshooting. .PP .zA "defect,7227,R1.0.2,Added text" This command will fail if the associated directory does not exist. If the associated directory exists, this command will return successfully. .zZ "defect,7227,R1.0.2,Added text" .zA "defect, 11818, R1.1, Added caveat" .PP This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .wH "" .SH "EXAMPLE" .PP The following command creates the child pointer in the parent directory \*L/.:/subsys\*O. It uses the replica located at the \*L/.:/subsys/NY_CH\*O clearinghouse to fill in its replica set. .PP .iS \*Ccdscp>\*L create child /.:/subsys clearinghouse /.:/subsys/NY_CH\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ldelete child(1m)\*O, \*Llist child(1m)\*O, \*Lshow child(1m)\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "create clearinghouse" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "clearinghouses" "creating" .iX "-[" "clearinghouses" "making available" .iX "-[" "\*Lcdscp\*O commands" "\*Lcreate clearinghouse\*O" .SH NAME .PP \*Lcreate clearinghouse\*O - Creates a clearinghouse on the local server system or makes an existing clearinghouse available .wH "" .SH "SYNOPSIS" .PP \*Lcdscp create clearinghouse\*O \*Vclearinghouse-name \*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vclearinghouse-name\*O" The full name of the clearinghouse. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lcreate clearinghouse\*O command creates a clearinghouse on the local server system or makes an existing clearinghouse available. The server start-up command usually creates a new clearinghouse when you configure a new CDS server. Occasionally, you may need to create a second clearinghouse on a particular server; for example, if you are temporarily relocating a clearinghouse on a different server. See the \*VOSF DCE Administration Guide\*O for more information about relocating a clearinghouse. .PP Clearinghouses should be named only in the root. When you enter the command, CDS creates a read-only replica of the root directory and stores it in the new clearinghouse as the initial replica. Because the process that creates the new clearinghouse initiates a skulk of the root directory, all replicas of the root should be reachable when you enter the command. .SS "Privilege Required" .PP You need write permission to the server on which you intend to create the clearinghouse and administer permission to the cell root directory. The server principal needs read, write, and administer permission to the cell root directory. .SH "NOTES" .PP This command is usually executed only by the network configuration procedure. To ensure that all replicas of the root are reachable, perform an immediate skulk of \*L/.:\*O prior to issuing this command. .zA "defect, 11818, R1.1, Added caveat" .PP This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .wH "" .SH "EXAMPLE" .PP The following command creates a clearinghouse named \*L/.:/Boston_CH\*O on the local server system: .iS \*Ccdscp>\*L create clearinghouse /.:/Boston_CH\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lclear clearinghouse(1m)\*O, \*Ldelete clearinghouse(1m)\*O, \*Llist clearinghouse(1m)\*O, \*Lset cdscp preferred clearinghouse(1m)\*O, \*Lshow cached clearinghouse(1m)\*O, \*Lshow cdscp preferred clearinghouse(1m)\*O, \*Lshow clearinghouse(1m)\*O .PP Books: \*VOSF DCE Administration Guide\*O .iX "-]" "clearinghouses" "creating" .iX "-]" "clearinghouses" "making available" .iX "-]" "\*Lcdscp\*O commands" "\*Lcreate clearinghouse\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "create directory"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "directories" "creating (CDS)" .iX "\*Lcdscp\*O commands" "\*Lcreate directory\*O" .SH NAME .PP \*Lcreate directory\*O - Creates a directory .wH "" .SH "SYNOPSIS" .PP \*Lcdscp create directory\*O \*Vdirectory-name \*L[clearinghouse\*O \*Vclearinghouse-name\*O\*L]\*O\*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vdirectory-name\*O" The full name of the directory .LI "\*Vclearinghouse-name\*O" The name of the clearinghouse in which you create the directory. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lcreate directory\*O command creates a directory with the name that you specify. If you do not specify a clearinghouse, CDS creates the master replica of the directory in the same clearinghouse as the new directory's parent directory. .SS "Privilege Required" .PP .zA "defect,6779,R1.0.2,Incorrect permissions" .zA "defect,8127,R1.0.2a,Improved wording and format" You must have the following permissions in order to create a directory: .ML .LI \*Lread\*O and \*Linsert\*O permission to the parent directory; .LI \*Lwrite\*O permission to the clearinghouse in which the master replica of the new directory is to be stored. .LE .P In addition, the server principal must have \*Lread\*O and \*Linsert\*O permission to the parent directory. .zZ "defect,8127,R1.0.2a,Improved wording and format" .zZ "defect,6779,R1.0.2,Incorrect permissions" .SH "NOTES" .PP To ensure that all replicas are consistent, perform an immediate skulk of the parent directory after issuing this command. .zA "defect, 11818, R1.1, Added caveat" .PP This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .wH "" .SH "EXAMPLE" .PP The following command creates a directory named \*L/.:/sales\*O. .iS \*Ccdscp>\*L create directory /.:/sales .iE .wH "" .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ldelete directory(1m)\*O, \*Llist directory(1m)\*O, \*Lset directory(1m)\*O, \*Lset directory to skulk(1m)\*O, \*Lshow directory(1m)\*O ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "create link"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "soft links" "creating" .iX "-[" "\*Lcdscp\*O commands" "\*Lcreate link\*O" .SH NAME .PP \*Lcreate link\*O - Creates a soft link and optionally specifies an expiration time and an extension time .wH "" .SH "SYNOPSIS" .PP \*Lcdscp create link\*O \*Vlink-name \*LCDS_LinkTarget\*O = \*Vtarget-name\*O [\*LCDS_LinkTimeout\*O = \*V (expiration-time extension-time)\*O] .wH "" .SH "ARGUMENTS" .VL .LI "\*Vlink-name\*O" The full name of the soft link. .LI "\*Vtarget-name\*O" The full name of the entry to which the soft link points. .LI "\*Vexpiration-time\*O" A date and time after which CDS checks for existence of the soft link's target and either extends or deletes the soft link. The value is specified as \*Eyyyy-mm-dd-hh:mm:ss\*O (year-month-day-hour:minute:second). .zA "defect,5001,R1.0.2, Added description" You can abbreviate this value. .zZ "defect,5001,R1.0.2, Added description" .LI "\*Vextension-time\*O" A period of time by which to extend the soft link's expiration time (if the server has validated that the target still exists). The value is specified as \*Eddd-hh:mm:ss\*O (days-hour:minute:second). .zA "defect,5001,R1.0.2, Added description" You can abbreviate ths value. .zZ "defect,5001,R1.0.2, Added description" .LE .wH "" .SH "DESCRIPTION" .PP The \*Lcreate link\*O command creates a soft link. If you specify the \*LCDS_LinkTimeout\*O attribute, you must specify an expiration time and an extension time. If you omit the \*LCDS_LinkTimeout\*O attribute, the soft link is permanent and must be explicitly deleted. .SS "Privilege Required" .PP .zA "review,R1.0.2,add text" You must have insert permission to the directory in which you intend to create the soft link. .zZ "review,R1.0.2,add text" .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP .zA "defect,7065,R1.0.2,add timeout example" The following command creates a permanent soft link named \*L/.:/sales/tokyo/price-server\*O that points to an object entry named \*L/.:/sales/east/price-server\*O. The expiration value indicates that CDS will check that the destination name \*L/.:/sales/east/price-server\*O still exists on June 25,1995, at 12:00 p.m. If the destination name still exists, the soft link remains in effect another 90 days. Thereafter, CDS will check that the destination name exists every 90 days. .iS \*Ccdscp>\*L create link /.:/sales/tokyo/price-server CDS_LinkTarget \\ \*C> \*L= /.:/sales/east/price-server CDS_LinkTimeout =(1995-06-25-12:00:00 \\ \*C> \*L= 90-00:00:00) .iE .zZ "defect,7065,R1.0.2,add timeout example" .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ldelete link(1m)\*O, \*Llist link(1m)\*O, \*Lset link(1m)\*O, \*Lshow link(1m)\*O .wH "" .wH "" .iX "-]" "soft links" "creating" .iX "-]" "\*Lcdscp\*O commands" "\*Lcreate link\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "create object"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "objects" "creating" .iX "\*Lcdscp\*O commands" "\*Lcreate object\*O" .SH NAME .PP \*Lcreate object\*O - Creates an object entry .wH "" .SH "SYNOPSIS" .zA "defect,4367,R1.0.2, "Changed syntax" .PP \*Lcdscp create object\*O \*Vobject-name\*O [\*LCDS_Class = \*O\*Vclass-name\*O \*LCDS_ClassVersion = \*O\*Vvalue\*O] .zZ "defect,4367,R1.0.2, "Changed syntax" .wH "" .SH "ARGUMENTS" .VL .LI "\*Vobject-name\*O" The full name of the object entry. .LI "\*Vclass-name\*O" The class of object entry being created. You can specify an application-defined class name. A class is specified as a simple name limited to 31 characters. .LI "\*Vvalue\*O" The version of the class assigned to the object entry. Specify the value as \*Ev.n\*O, where \*Ev\*O defines the major release number and \*En\*O specifies the minor version number. .zA "defect,4367,R1.0.2, "Changed description" Specifying a class version is useful as it allows the definition of a class to evolve as the application is revised. .zZ "defect,4367,R1.0.2, "Changed description" .LE .wH "" .SH "DESCRIPTION" .PP The \*Lcreate object\*O command creates an object entry. This task is usually done through a client application. .SS "Privilege Required" .PP You must have insert permission to the parent directory. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command creates an object entry named \*L/.:/sales/east/floor1cp\*O. The object entry describes a color printer on the first floor of a company's eastern sales office. .iS \*Ccdscp>\*L create object /.:/sales/east/floor1cp CDS_Class = printer CDS_ClassVersion = 1.0 .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ldelete object(1m)\*O, \*Llist object(1m)\*O, \*Lset object(1m)\*O, \*Lshow object(1m)\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "create replica" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "replicas" "creating" .iX "\*Lcdscp\*O commands" "\*Lcreate replicas\*O" .SH NAME .PP \*Lcreate replica\*O - Creates a replica of an existing directory in the specified clearinghouse .wH "" .SH "SYNOPSIS" .PP \*Lcdscp create replica\*O \*Vdirectory-name \*Lclearinghouse \*Vclearinghouse-name\*O \*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vdirectory-name\*O" The full name of the directory. .LI "\*Vclearinghouse-name\*O" The full name of the clearinghouse in which you want to create the replica. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lcreate replica\*O command creates a replica of an existing directory in the specified clearinghouse. .SS "Privilege Required" .PP You must have administer permission to the directory you intend to replicate and write permission to the clearinghouse that stores the new replica. The server principal needs read, write, and administer permission to the directory you intend to replicate. .SH "NOTES" .PP This command is usually executed only by the network configuration procedure. To ensure that all replicas are consistent, perform an immediate skulk of the parent directory after issuing this command. .zA "defect, 11818, R1.1, Added caveat" .PP This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command creates a replica of the \*L/.:/mfg\*O directory in the clearinghouse \*L/.:/Paris_CH\*O. .iS \*Ccdscp>\*L create replica /.:/mfg clearinghouse /.:/Paris1_CH\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ldelete replica(1m)\*O, \*Lshow replica(1m)\*O .wH "" .wH "" .\" $Header: create_sysfile.1m,v 72.3 94/11/02 17:56:36 ssa Exp $ .TA c .TH create_sysfile 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME create_sysfile \- create a kernel system file .SH SYNOPSIS .C /usr/lbin/sysadm/create_sysfile .RI [ outfile ] .SH DESCRIPTION The .CR create_sysfile command creates a kernel generation description file (system file) which can be used as input to the command .CR config . The system file is built according to the drivers required by the current system hardware. This command is intended for use during the install process when the system does not have a system file. .PP The .CR create_sysfile command first chooses a template file based on the CPU type of the machine, then it scans the system hardware and includes all drivers it can identify to run the existing hardware. If .I outfile is specified, the resulting system file is sent to .IR outfile . If .I outfile is not specified, the output is placed in the file .CR ./system . .SH RETURN VALUE The .CR create_sysfile command returns zero upon normal completion or .CR 1 if an error occurred. .SH DIAGNOSTICS Errors are sent to stderr. Most of the diagnostic messages from .CR create_sysfile are self-explanatory. Errors cause .CR create_sysfile to halt immediately. .SH AUTHOR .CR create_sysfile was developed by HP. .SH FILES .C /usr/conf/gen/templates/* .br .C /usr/conf/master.d/* .SH SEE ALSO config(1M), master(4). .\" .\" toc@\f3create_sysfile(1M)\f1:\0\0\f4create_sysfile\f1@@@create a kernel system file\f1 .\" .\" index@\f4create_sysfile\f1 \- create a kernel system file@@@\f3create_sysfile(1M)\f1 .\" index@\f1kernel system file, create@@@\f3create_sysfile(1M)\f1 .\" index@\f1system file, create a kernel@@@\f3create_sysfile(1M)\f1 .\" index@\f1file, create a kernel system@@@\f3create_sysfile(1M)\f1 .\" $Header: cron.1m,v 72.8 94/11/14 13:13:32 ssa Exp $ .TA c .TH cron 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cron \- timed-job execution daemon .SH SYNOPSIS .C /usr/sbin/cron .SH DESCRIPTION .CR cron executes commands at specified dates and times. Regularly scheduled commands can be specified according to instructions placed in crontab files. Users can submit their own crontab files with a .CR crontab command (see .IR crontab (1)). Users can submit commands that are to be executed only once with an .CR at or .CR batch command. .PP Since .CR cron never exits, it should be executed only once. This is best done by running .CR cron from the initialization process with the startup script .CR /sbin/init.d/cron (see .IR init (1M)). .PP .CR cron only establishes a schedule for crontab files and .CR at / batch command files during process initialization and when it is notified by .CR at , .CR batch , or .CR crontab that a file has been added, deleted, or modified. .PP When .CR cron executes a job, the job's user and group IDs are set to those of the user who submitted the job. .SS Spring and Autumn Time Transitions On the days of daylight savings (summer) time transition (in time zones and countries where daylight savings time applies), .CR cron schedules commands differently from normal. .PP In the following description, an .B ambiguous time refers to an hour and minute that occurs twice in the same day because of a daylight savings time transition (usually on a day during the Autumn season). A .B nonexistent time refers to an hour and minute that does not occur because of a daylight savings time transition (usually on a day during the Spring season). .B DST-shift refers to the offset that is applied to standard time to result in daylight savings time. This is normally one hour, but can be any combination of hours and minutes up to 23 hours and 59 minutes (see .IR tztab (4)). .PP When a command is specified to run at an ambiguous time, the command is executed only once at the .I first occurrence of the ambiguous time. .PP When a command is specified to run at a nonexistent time, the command is executed after the specified time by an amount of time equal to the DST-shift. When such an adjustment would conflict with another time specified to run the command, the command is run only once rather than running the command twice at the same time. .PP Commands that are scheduled to run during all hours (there is a .CR * is in the hour field of the crontab entry) are scheduled without any adjustment. .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is set to the empty string, it defaults to "C" (see .IR lang (5)). If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH DIAGNOSTICS A history of all actions taken by .CR cron is recorded in .CR /var/adm/cron/log . .SH EXAMPLES The following examples assume that the time zone is .CR MST7MDT . In this time zone, the DST transition occurs one second before 2:00 a.m.\& and the DST-shift is 1 hour. .PP Consider the following entries in a crontab file: .nf .IP .C "# Minute Hour Month Day Month Weekday Command" .C "# ----------------------------------------------------------" .C " 0 01 * * * Job_1" .C " 0 02 * * * Job_2" .C " 0 03 * * * Job_3" .C " 0 04 * * * Job_4" .C " 0 * * * * Job_hourly" .C " 0 2,3,4 * * * Multiple_1" .C " 0 2,4 * * * Multiple_2" .fi .PP .ne 18 For the period of 1:00 a.m.\& to 4:00 a.m.\& on the days of DST transition, the results will be: .PP .TS center tab(;) ; lB cB cB lf4p+1 c c . Job;Times Run in Fall;Times Run in Spring _ Job_1;01:00 MDT;01:00 MST Job_2;02:00 MDT;03:00 MDT Job_3;03:00 MST;03:00 MDT Job_4;04:00 MST;04:00 MDT Job_hourly;01:00 MDT;01:00 MST \&;02:00 MDT \&;02:00 MST \&;03:00 MST;03:00 MDT \&;04:00 MST;04:00 MDT Multiple_1;02:00 MDT \&;03:00 MST;03:00 MDT \&;04:00 MST;04:00 MDT Multiple_2;02:00 MDT;03:00 MDT \&;04:00 MST;04:00 MDT .TE .SH WARNINGS In the Spring, when there is a nonexistent hour because of daylight savings time, a command that is scheduled to run multiple times during the nonexistent hour will only be run once. For example, a command scheduled to run at 2:00 and 2:30 a.m.\& in the .CR MST7MDT time zone will only run at 3:00 a.m. The command that was scheduled at 2:30 a.m.\& will not be run at all, instead of running at 3:30 a.m. .SH DEPENDENCIES .SS HP Process Resource Manager If the optional HP Process Resource Management (PRM) software is installed and configured, jobs are launched in the initial process resource group of the user that scheduled the job. The user's initial group is determined at the time the job is started, not when the job is scheduled. If the user's initial group is not defined, the job runs in the user default group .RC ( PRMID=1 ). See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for a description of how the user's initial process resource group is determined. .SH AUTHOR .CR cron was developed by AT&T and HP. .SH FILES .if t .TP 40 .if n .TP 30 .PD 0 .CR /var/adm/cron Main .CR cron directory .TP .CR /var/spool/cron/atjobs Directory containing .CR at and .CR batch job files .TP .CR /var/spool/cron/crontabs Directory containing crontab files .TP .CR /var/adm/cron/log Accounting information .PD .SH SEE ALSO at(1), crontab(1), sh(1), init(1M), cdf(4), queuedefs(4), tztab(4). .TP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR cron ": SVID2, SVID3" .\" .\" index@clock daemon@@@\f3cron(1M)\f1 .\" index@daemon, timed-job execution@@@\f3cron(1M)\f1 .\" index@job execution daemon@@@\f3cron(1M)\f1 .\" index@PRM@@@\f1see Process Resource Manager .\" index@Process Resource Manager@@@\f3cron(1M)\f1 .\" index@timed-job execution daemon@@@\f3cron(1M)\f1 .\" .\" toc@\f3cron(1M)\f1:\0\0\f4cron\fP@@@timed-job execution daemon ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH "csrc" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "enh,9973,R1.1,add code set registry documentation" ...\" .iX "\*Lcsrc\*O command" .iX "commands" "\*Lcsrc\*O" .SH NAME .PP \*Lcsrc\*O - Builds a DCE character and code set registry on a host .SH "SYNOPSIS" .PP .sS \*Lcsrc\*O \*O[\*Vargument\*O] \&.\&.\&. .sE .br .ne 1.5i .SH "ARGUMENTS" .PP .VL 2m .LI "\*L\-i \*Vsource_filename\*O" Reads code set values from the source file you specify rather than from the default code set registry source file \*L/usr/lib/nls/csr/code_set_registry.txt\*O .LI "\*L\-m \*Vintermediate_cs_name\*O" Indicates the code set to be used as an intermediate code set .LI "\*L\-o \*Vdestination_filename\*O" Places the generated code set registry file in the location you specify rather than in the default location \*L/usr/lib/nls/csr/code_set_registry.db\*O .LE .br .ne 1.5i .SH "DESCRIPTION" .PP The Code Set Registry Compiler \*Lcsrc\*O creates a character and code set registry file from the information supplied in a character and code set registry source file. .PP A code set registry source file is composed of a series of code set records. Each record describes, in human-readable form, the mapping between an OSF-registered or (optionally) a user-defined unique code set value and the character string that a given operating system uses when referring to that code set (called the "local code set name"). .PP A code set registry file is the binary version of the source file; the DCE RPC routines for character and code set interoperability use the file to obtain a client's or a server's supported code sets and to translate between operating system-dependent names for code sets and the unique identifiers assigned to them. A code set registry file must exist on each host in an "internationalized" DCE cell (a DCE cell that supports applications that use the DCE RPC character and code set interoperability features). .SS "Creating the Source File" .PP Code set registry source files are created for input to \*Lcsrc\*O in two instances: .ML .LI By DCE licensees, when they are porting DCE to a specific operating system platform and plan for their DCE product to support internationalized DCE applications. In this instance, DCE licensees modify a template code set registry source file supplied on the DCE source tape to contain, for each code set that their platform supports, the local code set names for those supported code sets. Licensees can also add to this file any vendor-specific, non-OSF registered code set names and values that their platform supports. .LI By cell administrators, when they are configuring machines that are part of an internationalized DCE cell. In this instance, the cell administrator adds the local code set names of any additional code sets that the site supports to the licensee-generated code set registry source file for each different operating system platform that exists in the cell. The cell administrator can also add to each platform-specific source file any site-specific, non-OSF registered code set names and values. .LE .PP Each code set record specifies one code set, and has the following form: .sS \*Lstart \*O .nL \*Vfield_list\*O .nL \*Lend\*O .sE .PP where \*Vfield_list\*O consists of the following keyword-value or keyword-text pairs: .VL .LI "\*Ldescription\*O \*Vtext\*O" A comment string that briefly describes the code set. The text field can contain multiple lines; use the backslash character (\\) to continue the line. Use this field to give a detailed description of the code set and character set(s). .LI "\*Lloc_name \*Vtext\*O" A maximum 32-byte string (31 character data bytes plus a terminating NULL) that contains the operating system-specific name of a code set or the keyword \*LNONE\*O. Use this field to specify the name that your site uses to refer to this code set and the code set converters associated with it. For example, on UNIX platforms, code set converters are usually implemented under the \*Liconv\*O scheme. Check the \*Liconv\*O converter directory to determine the code set names. .LI "\*Lrgy_value \*Vvalue\*O" A 32-bit hexadecimal value that uniquely identifies this code set. A registry value can be one that OSF has assigned or one that a DCE licensee or cell administrator has assigned. Licensee or cell administrator-defined values must be in the range 0xf5000000 through 0xfffffff. .LI "\*Lchar_values \*Vvalue\*O[\*L:\*Vvalue\*O]" One or more 16-bit hexadecimal values that uniquely identify each character set that this code set encodes. A character value can be one that OSF has assigned or one that a DCE licensee or a cell administrator has assigned. Use the colon character (:) to separate multiple character set values. .LI "\*Lmax_bytes \*Vvalue\*O" A 16-bit value that specifies the maximum number of bytes this code set uses to encode one character. The count should include any single-shift control characters, if used. .LE .PP In the source file, braces({\|}) can be used as synonyms for the \*Lstart\*O and \*Lend\*O keywords. Use one or more spaces or tabs to separate field names and values. An unquoted \*L#\*O (number sign) introduces a comment; in this case, the \*Lcsrc\*O utility ignores everything between the comment character and the end of the line. .PP The OSF DCE source tape provides a partial version of a code set registry source file in the file \*L/usr/lib/nls/csr/code_set_registry.txt\*O. This source file contains records for all OSF-registered code sets, and assigns the text string \*LNONE\*O to \*Lloc_name\*O fields intended for modification to a local code set name. .PP DCE licensees who port DCE to their operating system platform and who plan to support internationalized DCE RPC applications must replace the \*LNONE\*O text string with their local name for the code set, for each code set that their operating system platform supports. If their platform does not support a given code set, they must leave the \*LNONE\*O keyword in the code set record. .PP Cell administrators of internationalized DCE cells carry out the same procedure on the licensee-supplied, platform-specific source files that exist at their site. For each platform-specific source file, they replace the \*LNONE\*O keyword with the local code set names for any site-specific supported code sets. .PP DCE licensees and cell administrators can also add vendor-specific or site-specific code set values that have not been registered with OSF. These vendor or user-defined values must be in the range 0xf5000000 through 0xfffffff. .PP Here is an excerpt from the OSF-supplied code set registry source file: .iS start description ISO 8859:1987; Latin Alphabet No. 1 loc_name NONE rgy_value 0x00010001 char_values 0x0011 max_bytes 1 end start description ISO 8859-2:1987; Latin Alphabet No. 2 loc_name NONE code_value 0x00010002 char_values 0x0012 max_bytes 1 end start description ISO 8859-3:1988; Latin Alphabet No. 3 loc_name NONE code_value 0x00010003 char_values 0x0013 max_bytes 1 end start description ISO 8859-6:1987; Latin-Arabic Alphabet loc_name NONE code_value 0x00010006 char_values 0x0016 max_bytes 1 end [...] start description ISO/IEC 10646-1:1993; UCS-2 Level 1 loc_name NONE code_value 0x00010100 char_values 0x1000 max_bytes 2 end [...] start description JIS eucJP:1993; Japanese EUC loc_name NONE code_value 0x00030010 char_values 0x0011:0x0080:0x0081:0x0082 max_bytes 3 end .iE .SS "Generating the Code Set Registry File" .PP DCE licensees use \*Lcsrc\*O to create licensee-supplied code set registry files for their internationalized DCE product. Cell administrators of internationalized DCE cells use the \*Lcsrc\*O utility to create site-specific code set registry files for each host in the cell. The cell administrator runs the \*Lcsrc\*O program on each host in the cell. .PP When invoked without options, \*Lcsrc\*O uses the default source file \*L/usr/lib/nls/csr/code_set_registry.txt\*O and creates the default output file \*L/usr/lib/nls/csr/code_set_registry.db\*O. Use the \*L-i\*O and \*L-o\*O options to redirect \*Lcsrc\*O to use a specific source file or generate a specific output file. The \*Lcsrc\*O utility also generates a log file named \*LCSRC_LOG\*O in the current directory. .SS "Adding Intermediate Code Sets" .PP Use the \*L-m\*O option to add a maximum of five intermediate code set names to the code set registry file's intermediate code set priority list. The order in which you specify intermediate code sets determines their order of precedence in the list; that is, the first intermediate code set you specify with \*L-m\*O becomes the first intermediate code set in the priority list, and thus will be the first code set used should an intermediate code set be required for client-server communication. If you do not specify intermediate code sets with \*L-m\*O, the Universal code set ISO 10646 will be used as the default intermediate code set. .SS Restrictions .PP You need write permission to the \*L/usr/lib/nls/csr\*O directory, which usually requires \*Lroot\*O privilege. .SH FILES .VL 1.5i .LI "\*L/usr/lib/nls/csr/code_set_registry.txt\*O" Default pathname for code set registry source file. .LI "\*L/usr/lib/nls/csr/code_set_registry.db\*O" Default pathname for code set registry object file .LE .PP .SH EXAMPLES .PP .oS % csrc -i /test/i18n_app/code_set_registry.txt -o code_set_registry.db -m euc -m sjis .oE .PP In the previous example, the log file \*LCSRC_LOG\*O is created in the current working directory, \*Ltest\i18n_app\*O. .PP .SH RELATED INFORMATION .ad l .PP Functions: \*Ldce_cf_get_csrgy_filename(3)\*O, \*Ldce_cs_loc_to_rgy(3), \*Ldce_cs_rgy_to_loc(3)\*O, \*Lrpc_rgy_get_codesets(3)\*O. .PP Books: \*EOSF DCE Administration Guide\*O, \*(Dk. .ad b .zZ "enh,9973,R1.1,add code set registry documentation" .\" $Header: cuegetty.1m,v 74.1 95/05/10 21:29:06 ssa Exp $ .TA c .TH cuegetty 1M "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cuegetty \- set terminal type, modes, speed, and line discipline for \f2cue\fP(1) .SH SYNOPSIS .C /usr/sbin/cuegetty .RC [ -L .IR nls_language\| ] .RC [ -T .IR terminal_type\| ] .RC [ -h ] .RC [ -t .IR timeout\| ] .I line .RI [ \|speed\| ] .\".RI [ \|type .\".RI [ \|linedesc\| ]\|]\|] .br .\".C /usr/sbin/cuegetty \-c .\"file .SH DESCRIPTION The .CR cuegetty , command, which is very similar to .IR getty (1M), is the second process in the series, .RI ( init-cuegetty-cue-work session ) that ultimately connects a user with the .SM HP-UX CUE system. It is invoked by .CR init to monitor the terminal lines configured on a system (see .IR init (1M)). Each .CR cuegetty process resets its process group using .CR setpgrp , opens a particular terminal line, and usually sleeps in the .CR open() until the machine senses a hardware connection for the terminal. When .CR open() returns, .CR cuegetty attempts to adapt the system to the terminal speed and type, and displays the contents of the .CR /etc/issue file, if it exists. Lastly, .CR cuegetty invokes .CR cue which displays the Login screen and performs user validation (see .IR cue (1)). .PP To start .CR cuegetty , an entry for .CR cuegetty should be placed in the .CR /etc/inittab file. A typical .SM CUE entry in the .CR /etc/inittab file resembles the following: .IP .CR "cue:2:respawn:/usr/sbin/cuegetty -L fr_FR.roman8 -h tty0p1" .PP See .CR /usr/newconfig/etc/cue.inittab for an example .CR /etc/inittab file. .\"If CUE is being used from a remote system or in situations where the .\".I tty .\"received by a terminal is random AND some users want to .\"use the standard .\".I login .\"mechanism, then it may be best to access the CUE system via .\".I cue .\"on the command line or as the last item in the user's .\".I .login .\"file. See .IR cue (1) for more details on the .SM CUE system. .SS Configuration Options and Arguments .CR cuegetty recognizes the following arguments: .RS .TP 12 .I line Name of a tty line in .CR /dev to which .CR cuegetty is to attach itself. .CR cuegetty uses this string as the name of a file in the .CR /dev directory to open for reading and writing. By default .CR cuegetty forces a hangup on the line by setting the speed to zero before setting the speed to the default or specified speed. However, when .CR cuegetty is run on a direct port, .CR cuegetty does not force a hangup on the line since the driver ignores changes to zero speed on ports open in direct mode (see .IR modem (7)). .TP .C -L .C nls_language is used to set the language for the .SM CUE login screens. If the message catalog, .CR cue.cat , does not exist for .CR nls_language , the default native language, C, is used. .TP .C -T .C terminal_type is used to specify the type of terminal that .CR cuegetty will be initiated on. Allowed values are .CR vt320 , .CR vt100 , .CR wy60 , and .CR hp . The default is .CR hp . .TP .C -h Tells .CR cuegetty not to force a hangup on the line before setting the speed to the default or specified speed. .TP .CI -t \ timeout .C cuegetty exits if the open on the line succeeds and nothing is typed within .I timeout seconds. .TP .I speed A label to a speed and tty definition in the file .CR /etc/gettydefs . This definition tells .CR cuegetty at what speed to initially run, what the login message should look like, what the initial tty settings are, and what speed to try next should the user indicate that the speed is inappropriate (by typing a .I break character). The default .I speed is 300 baud. .\" .\.TP .\" .\.I type .\" .\A character string describing to .\" .\.I cuegetty .\" .\what type of terminal is connected to the line in question. .\" .\.I cuegetty .\" .\understands the following types: .\" .\.RS .\" .\.IP .\" .\.TS .\" .\l l. .\" .\\f3none\f1 default .\" .\\f3vt61\f1 \s-1DEC\s+1 vt61 .\" .\\f3vt100\f1 \s-1DEC\s+1 vt100 .\" .\\f3hp45\f1 Hewlett-Packard \s-1HP\s02645 .\" .\\f3c100\f1 Concept 100 .\" .\.TE .\" .\.RE .\" .\.IP .\" .\The default terminal is .\" .\.BR none ; .\" .\i.e., any crt or normal terminal unknown to the system. .\" .\Also, for terminal type to have any meaning, the virtual .\" .\terminal handlers must be compiled into the operating system. .\" .\They are available, but not compiled in the default condition. .\" .\.\.TP .\" .\.I linedesc .\" .\A character string describing which line discipline to use .\" .\when communicating with the terminal. .\" .\Hooks for line disciplines are available in the operating system, .\" .\but there is only one presently available \(em .\" .\the default line discipline, .\" .\.SM .\" .\.BR LDISC0 . .\" .\.RE .PP When no optional arguments appear on the command line, .CR cuegetty sets the terminal interface as follows: .RS .TP 3 \(bu Interface .IR speed : 300 baud .TP \(bu Raw mode (awaken on every character) .TP \(bu Echo suppressed .TP \(bu Parity: either .TP \(bu New-line characters: convert to carriage-return, line-feed pair .TP \(bu Expand tabs on the standard output .TP \(bu Type login message then read user's name, one character at a time .ift .bp .TP \(bu If a null character (or framing error) is received, assumed it to be the result of the user pushing the ``break'' key. This causes .CR cuegetty to attempt the next .I speed in the series. The series that .CR cuegetty tries is determined by what it finds in .CR /etc/gettydefs . .RE .PP After interface set-up is complete, .CR cue is started to accept and validate the user name and password. .\".SS Check Option .\"A check option is provided. .\"When .\".I cuegetty .\"is invoked with the .\".B \-c .\"option and .\".IR file , .\"it scans .\".I file .\"as if it were scanning .\".B /etc/gettydefs .\"and prints the results on the standard output. .\"If there are any unrecognized modes or improperly constructed entries, .\"it reports these. .\"If the entries are correct, .\"it prints out the values of the various flags. .\"See .\".IR ioctl (2) .\"for an interpret of values. .\"Note that some values are added to the flags automatically. .SH WARNINGS If a supported non-HP terminal (or an HP terminal such as HP 700/60 in VT320, VT100 or WYSE60 mode) is required to run .CR cuegetty , make sure that a correct terminal type is specified using the .CR -T option. For example, if you want to run .CR cuegetty on a vt100 terminal, you should make an entry in the .CR /etc/inittab file such as the following entry: .PP .CR "tty1:23:respawn:cuegetty -T vt100 -h tty1p1 9600" .PP Absence of the .CR -T option causes .CR cuegetty to assume terminal to be a HP terminal which may then cause the terminal to behave incorrectly and may not even allow user to login. .SH DEPENDENCIES .CR cuegetty is available only on Series 800 systems, and is compatible only with the following terminals: .IP HP\|700/92\h'.3i'HP\|700/94\h'.3i'HP\|2392\h'.3i'HP\|2394\h'.3i'VT\|100\h'.3i'WYSE\|60\h .PP See .BR WARNINGS if you intend to use a non-HP terminal (or an HP terminal such as HP 700/60 in VT320, VT100, or WYSE60 mode). .\"HP\|2334 MultiMux: .\".IP .\"The modem control parameter .\".SM .\".I MRTS .\"must be present in the .\".B /etc/gettydefs .\"file when using .\".I cuegetty .\"in conjunction with an .\".SM HP\|2334 .\"or .\".SM HP\|2335 .\"MultiMux to ensure that the .\".SM RTS .\"modem control signal is asserted correctly. .\".IP .\"Example: .\".RS .\".IP .\".SM "9600# B9600 HUPCL PARENB \f3MRTS\f1 # B9600 SANE PARENB ISTRIP IXANY #login: #19200" .\".RE .\".IP .\".SM MRTS .\"is not intended for use with devices other than the .\".SM HP\|2334 .\"or .\".SM HP\|2335 .\"MultiMux. .SH FILES .ift .TP 45 .ifn .TP 25 .C /etc/gettydefs contains speed and terminal settings used by .CR cuegetty .TP .C /etc/inittab .C init reads this file to determine which processes to spawn .TP .C /etc/issue contains issue identification data .TP .C /usr/newconfig/etc/cue.inittab sample .C inittab file with .C cuegetty entry .SH SEE ALSO cue(1), env(1), nlsinfo(1), getty(1M), init(1M), ioctl(2), gettydefs(4), inittab(4), environ(5), hpnls(5), lang(5), termio(7). .\" .\" toc@\f3cuegetty(1M)\f1:\0\0\f4cuegetty\f1@@@set terminal characteristics for \f4cue\f1 .\" .\" index@\f4cuegetty\f1 \- set terminal characteristics for \f4cue\f1@@@\f3cuegetty(1M)\f1 .\" index@set terminal characteristics for \f4cue\f1@@@\f3cuegetty(1M)\f1 .\" index@terminal characteristics for \f4cue\f1, set@@@\f3cuegetty(1M)\f1 .\" index@characteristics for \f4cue\f1, set terminal@@@\f3cuegetty(1M)\f1 .\" index@\f4cue\f1, set terminal characteristics for@@@\f3cuegetty(1M)\f1 .\" .\" fileset_database@cuegetty.1m SYS-ADMIN-MAN .\" $Header: wall.1m,v 74.2 95/04/04 14:52:17 ssa Exp $ .TA w .TH wall 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wall, cwall \- write message to all users .SH SYNOPSIS .CR /usr/sbin/wall .RC [ -g\c .IR groupname ] .RI [ file ] .PP .CR /usr/sbin/cwall .RC [ -g\c .IR groupname ] .RI [ file ] .SH DESCRIPTION Without arguments, the .CR wall command reads a message from standard input until end-of-file. Then it sends this message to all currently logged-in users preceded by: .IP .CR "Broadcast Message from " ... .PP If the .CI -g groupname option is specified, .CR wall sends the message to all currently logged-in .I groupname members (as specified in .CR /etc/group ) preceded by: .IP .CR "Broadcast Message from " ... " to group" .I groupname .PP If .I file is specified, .CR wall reads .I file instead of standard input. .PP .CR wall is typically used to warn all users prior to shutting down the system. .PP In a diskless cluster, .C cwall can be used to write to all users in the cluster. .PP The sender must have appropriate privileges to override any protections the users may have invoked (see .IR mesg (1)). .PP .CR wall has timing delays, and takes at least 30 seconds to complete. .PP You must have appropriate privileges to override any protections users may have invoked (see .IR mesg (1)). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multibyte character code sets are supported. .SH DIAGNOSTICS .PP .CR "Cannot send to " ... .IP The open on a user's tty file failed. .SH AUTHOR .CR wall was developed by AT&T and HP. .SH FILES .CR /dev/tty* .SH SEE ALSO mesg(1), write(1). .SH STANDARDS CONFORMANCE .CR wall ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4wall\f1 \- write message to all users@@@\f3wall(1M)\f1 .\" index@\f4cwall\f1 \- write message to all users in a cluster@@@\f3wall(1M)\f1 .\" index@\f1broadcast message simultaneously to all users@@@\f3wall(1M)\f1 .\" index@\f1message, broadcast simultaneously to all users@@@\f3wall(1M)\f1 .\" index@\f1send a message simultaneously to all users@@@\f3wall(1M)\f1 .\" index@\f1write a message simultaneously to all users@@@\f3wall(1M)\f1 .\" index@\f1cluster, write a message simultaneously to all users@@@\f3wall(1M)\f1 .\" .\" toc@\f3wall(1M)\f1:\0\0\f4cwall\f1, \f4wall\f1@@@write message to all users .\" toc@\f4cwall\f1:\0\0write message to all users in cluster@@@\f1see \f3wall(1M)\f1 .\" .\" links@wall.1m cwall.1m .\" .\"========================================================= .\" (c) 1992 Hewlett-Packard Company. All Rights Reserved. .\" Author: Hewlett-Packard DMD .\"========================================================= .\" .\"@(#) $Header: dcc.1m,v 1.2 95/12/15 11:37:32 hmgr Exp $ .TA d .TH dcc 1M .SH NAME dcc \- control read and write caching for HP SCSI disk array drives .SH SYNOPSIS .HP .C dcc .RI [ options ] .RI [ drive_list ] .I device_file .SH DESCRIPTION .C dcc displays or changes the read-ahead caching status, and write-immediate reporting status of selected drives on the .SM HP SCSI disk array referenced by .IR device_file . .SS Options .RS .TP 19 .CI -d Display only. Displays the read-ahead caching and write immediate reporting status of all selected drives on the .SM HP SCSI disk array. For .SM HP C2430 disk array devices, the number and size of cache segments is displayed. This option cannot be used with any other option. .TP .CI -r on Read on. Enables read-ahead caching on all selected drives of the .SM HP SCSI disk array. Can be used in combination with one of the write-immediate reporting options. .TP .CI -r off Read off. Disables read-ahead caching on all selected drives of the .SM HP SCSI disk array. Can be used in combination with one of the write-immediate reporting options. .TP .CI -w on Write on. Enables write-immediate reporting on all selected drives of the .SM HP SCSI disk array. Can be used in combination with one of the read-ahead caching options. .TP .CI -w off Write off. Disables write immediate reporting on all selected drives of the .SM HP SCSI disk array. Can be used in combination with one of the read-ahead caching options. .TP .CI -s num_segments Set the number of cache segments. This option is unique to the .SM HP C2430 disk array. The disk mechanism cache can be segmented into 1, 2, 4, 8 or 16 segments. The default is 2 segments. This option cannot be used with other options. .TP .I drive_list Specify a set of drives. If this optional list is absent, the default set of affected drives is all drives attached to the controller. The list is in the form .CI c X i Y\c ,... where .I X (a decimal number) represents .SM SCSI channel number, and .I Y (a decimal number) represents the .SM SCSI ID of the drive. Multiple drives in the list are separated by commas. .SH RETURN VALUE .C dcc returns the following values: .RS 5 .TP .B " 0" Successful completion. .PD 0 .TP .B -1 Command failed (an error occurred). .PD .PP .RE .SH ERROR MESSAGES Errors can originate from problems with: .RS .TP 3 \(bu .C dcc .TP \(bu .SM SCSI (device level) communications .TP \(bu system calls .RE .PP .SS Error messages generated by dcc: .TP .C "usage: dcc options [cXiY,...] " An error in command syntax has occurred. Enter command again with the required arguments, in the order shown. .TP .C "dcc: Arg out of range" One of the arguments is larger than its allowed maximum value (or smaller than its allowed minimum value), or is incorrect in form. Check the size, and form of each argument and make appropriate corrections. .TP .C "dcc: device busy" .tr ~" To ensure that .C dcc does not modify a disk array that is being used by another process, .C dcc attempts to obtain exclusive access to the disk array. If the disk array is already opened by another process (for example, LVM \(em the Logical Volume Manager), a .RC ~ "device busy" ~ error message is returned by the driver. To eliminate the .RC ~ "device busy" ~ condition, determine what process has the device open. In the case of LVM, it is necessary to deactivate the volume group containing the array before configuring the array (see .CR vgchange (1M)). .tr ~~ .TP .C "dcc: LUN does not exist" The addressed .SM LUN is not known to the array controller. .TP .C "dcc: LUN # too big" The .SM LUN number, which is derived from the device special file name, is out of range. .TP .C "dcc: Not a raw file" Utilities must be able to open the device file for raw access. .TP .C "dcc: Not an HP SCSI disk array" The device is not an .SM HP SCSI disk array. .TP .C "dcc: Transfer length error" The amount of data actually sent to (or received from) the device was not the expected amount. .PP .SS SCSI (device level) communication errors: Sense data associated with the failed operation is printed. .PP .SS Error messages generated by system calls: .C dcc uses the following system calls: .IP .CR malloc() , .CR free() , .CR stat() , .CR open() , .CR close() , .CR read() , .CR write() , and .CR ioctl() . .PP Documentation for these .SM HP-UX system calls contains information about the specific error conditions associated with each call. .C dcc does not alter the value of .CR errno . The interpretation of .C errno for printing purposes is performed by the system utility .CR strerror() . .SH EXAMPLES .PP To display the status of read and write caching on all the drives of the disk array .C /dev/rdsk/c2t2d0 on a Series 700: .IP .C "dcc -d /dev/rdsk/c2t2d0" .PP To enable write-immediate reporting on a list of drives on the disk array .C /dev/rdsk/c2t2d0 on a Series 800: .IP .C "dcc -won c2i0,c1i0,c5i0,c4i1 /dev/rdsk/c2t2d0" .PP To disable read caching and write-immediate reporting on the drives of the disk array .C /dev/rdsk/c2t4d0 on a Series 700: .IP .C "dcc -roff -woff /dev/rdsk/c2t4d0" .PP To set the number of cache segments on the .SM HP C2430 disk array .C /dev/rdsk/c2t2d0 to 4 on a Series 800: .IP .C "dcc -s 4 /dev/rdsk/c2t2d0" .PP .SH DEPENDENCIES The HP C2425 and HP C2427 disk arrays are only supported on Series 700 systems running HP-UX version 9.0X. .PP The HP C2430 disk array is supported on Series 700 and 800 systems runing HP-UX versions 9.0X and 10.0X. .SH AUTHOR .PP .C dcc was developed by HP. .\" .\" index@\f4dcc\f1 \- control \s-1SCSI\s+1 disk array read/write caching@@@\f3dcc(1M)\f1 .\" index@disk array, control read/write caching@@@\f3dcc(1M)\f1 .\" index@caching: controlling on \s-1HP SCSI\s+1 disk arrays@@@\f3dcc(1M)\f1 .\" .\" toc@\f3dcc(1M)\f1:\0\0\f4dcc\f1@@@controlling caching on \s-1HP SCSI\s+1 disk arrays .\" .\" fileset_database@dcc.1m SYS-ADMIN-MAN ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" Copyright 1991, International Business Machines Corporation. ALL RIGHTS RESERVED. ...\" .rm zA .rm zZ .TH dce_config 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldce_config\*O command" .iX "configuring DCE" "start up command" .SH NAME .PP \*Ldce_config\*O - Configures and starts up DCE .SH "SYNOPSIS" .zA "enh,9287,add new options" .sS \*Ldce_config\*O [\*L-i\*O] [\*L-e \*Venvironment_file\*O] [\*L-c \*Vcommand_file\*O] .sE .SH "OPTIONS" .VL 1i .LI "\*L-i\*O" The \*L-i\*O option tells \*Ldce_config\*O to look in the \*L/etc\*O directory of the install area (which is generally \*L/opt/dce1.0/etc\*O) for the component scripts it needs to run. After you have invoked \*Ldce_config\*O once with the \*L-i\*O option, you do not need to use the option again. .LI "\*L-e\*O" The \*L-e\*O option causes \*Ldce_config\*O to source \*Venvironment_file\*O at startup. \*Venvironment_file\*O is a user-created file that sets the DCE and DFS variables that specify responses to the \*Ldce_config\*O user prompts. Note that if you do not specify the \*L-e\*O option, \*Ldce_config\*O looks for the \*L/etc/dce_config.conf\*O file and sources it if it exists. If the file does not exist, it uses shell variable settings if they are set. .LI "\*L-c\*O" The \*L-c\*O option causes \*Ldce_config\*O to source \*Vcommand_file\*O at startup. \*Vcommand_file\*O is a user-created shell script that initiates configuration processing. .LE .zZ "enh,9287,add new options" .SH "DESCRIPTION" .PP The \*Ldce_config\*O shell command invokes a menu-driven interface that configures and starts up DCE. The \*Ldce_config\*O command displays a hierarchy of menus and invokes individual configuration routines according to users' menu selections. .PP ...\" Installation routines store the binaries required for the server installation ...\" that is selected into \*L$DCELOCAL\*O. Binaries required for a client ...\" installation are stored on every machine. The configuration menu consists of initial cell configuration, additional server configuration, and DCE client configuration. The security server and the first CDS server constitute initial cell configuration. .PP .zA "enh,9287,add new options" If you use specify an environment file with the \*L-e\*O option and a command file with the \*L-c\*O option, you can completely automate \*Ldce_config\*O processing. .SS "The Command File" The command file consists of \*Lconfig\*O command lines that specify the component to configure and, for DFS, the type of server. .PP A sample command file, \*Lconfig.cmd\*O, is provided by with the DCE source. You can copy the file and use it as supplied or you can use it as guide to creating your own environment file. The sample file is not copied to the install tree during DCE installation. .PP ...\" The \*Linstall\*O lines are in the form: ...\" .iS ...\" install \*Vcomponent\*O [\*Vdfs_server\*O] ...\" .iE ...\" Where ...\" .VL ...\" .LI "\*Vcomponent\*O" ...\" Is one of the following values: ...\" .ML ...\" .LI ...\" \*Lsec\*O\(emMaster Security server binaries ...\" .LI ...\" \*Lcds\*O\(emInitial CDS server binaries ...\" .LI ...\" \*Lgds\*O\(emGDS server binaries ...\" .LI ...\" \*Ldts\*O\(emDTS server binaries ...\" .LI ...\" \*Lclient\*O\(emDCE client binaries ...\" .LI ...\" \*Lsec-replica\*O\(emSecurity replica binaries ...\" .LI ...\" \*Lappdev\*O\(emIDL compiler and header files for use in ...\" DCE application development ...\" .LI ...\" \*Lcdsbrowser\*O \(em CDS Browser utility ...\" .LI ...\" \*Lnidl_to_idl\*O \(em A utility to convert files written in ...\" NIDL to files written in IDL ...\" .LE ...\" .LI "\*Vdfs_server\*O" ...\" Specifies the type of DFS server to install. \*Vdfs_server\*O ...\" is one of the following values: ...\" .ML ...\" .LI ...\" \*Lclient\*O\(emDFS client ...\" .LI ...\" \*Lscm\*O\(emSystem Control Machine ...\" .LI ...\" \*Lprivatefs\*O\(emPrivate File Server ...\" .LI ...\" \*Lfs\*O\(emFile Server ...\" .LI ...\" \*Lfldb\*O\(emFile Location Database Server ...\" .LE ...\" .LE The \*Lconfig\*O lines are in the form: .iS config \*Vcomponent\*L { client | gda | sec {client | server | replica} | cds {client | server | replica} | dts {clerk | local | global | ntp-provider | null-provider} dfs {client | scm | privatefs | fs | fldb} } .iE Where .VL .LI "\*Vcomponent\*O" Is one of the following values: .ML .LI \*Lclient\*O\(emDCE client configuration .LI \*Lgda\*O\(emGDA configuration .LI \*Lsec\*O\(emSecurity configuration of any one of the following: .ML .LI \*Lclient\*O\(emSecurity client machine .LI \*Lserver\*O\(emSecurity master server machine .LI \*Lreplica\*O\(emSecurity replica machine .LE .LI \*Lcds\*O\(emCDS configuration of any one of the following: .ML .LI \*Lclient\*O\(emCDS client machine .LI \*Lserver\*O\(emCDS initial server machine .LI \*Lreplica\*O\(emAdditional CDS server machines .LE .LI \*Ldts\*O\(emDTS configuration of any one of the following: .ML .LI \*Lclerk\*O\(em DTS clerk machine .LI \*Llocal\*O\(emDTS local server machine .LI \*Lglobal\*O\(emDTS global server machine .LI \*Lntp-provider\*O\(emDTS NTP time provider machine .LI \*Lnull-provider\*O\(emDTS null time provider .LE .LI \*Ldfs\*O\(emDFS configuration of any one of the following: .ML .LI \*Lclient\*O\(emDFS client specify .LI \*Lscm\*O\(emSystem Control machine .LI \*Lprivatefs\*O\(emPrivate File Server machine .LI \*Lfs\*O\(emFile Server machine .LI \*Lfldb\*O\(emFile Location Database Server machine .LE .LE .LE .SS "The Environment File" The Environment file sets the DCE and DFS variables. The file entries are in the form: .iS \*Vvariable\*L=\*Vvalue\*O .iE To change a value, simply replace it with the new value. .PP A sample environment file, \*Lconfig.env\*O, is provided with the DCE source. You can copy the file and use it as supplied or you can use it as guide to creating your own environment file. The sample file is not copied to the install tree during DCE installation. .PP .SS "The DCE and DFS Variables" The table titled "dce_config Environment Variables" lists the DCE variables you can set for \*Ldce_config\*O processing. The table titled "dfs_config Environment Variables" lists the DFS variables you can set. In the tables, the term default refers to the original setting assigned to the variable. .P .TB "dce_config Environment Variables" .TS center,box,tab(@); lB | lB l | l. Variable@Value _ CACHE_CDS_SERVER@T{ .iX "CACHE_CDS_SERVER dce_config environment variable" The name of the CDS server to cache. It is not required that the cached server be the initial CDS Server. Used during CDS client configuration. T} _ CACHE_CDS_SERVER_IP@T{ .iX "CACHE_CDS_SERVER_IP dce_config environment variable" The IP address of the CDS server to cache. T} _ CELL_ADMIN@T{ .iX "CELL_ADMIN dce_config environment variable" The principal name of the initial privileged user of the registry database (known as the "registry creator"). Used during Security server configuration. T} _ CELL_ADMIN_PW@T{ .iX "CELL_ADMIN_PW dce_config environment variable" The default password assigned to the accounts created when the registry database is created, including the account for the registry creator. The default is .br \*L-dce-\*O. T} _ CELL_NAME@T{ .iX "CELL_NAME dce_config environment variable" The name of the cell (without the \*L.../\*O) on which the configuration is being performed. Used during Security server configuration. T} _ CHANGE_PW@T{ .iX "CHANGE_PW dce_config environment variable" Indicates whether or not \*Ldce_config\*O displays \*C'Password must be changed'\*O on exiting when the cell administrator password (CELL_ADMIN_PW) is the same as the default password. The default is \*Ln\*O. It is recommended that you do not change this value in order to help ensure that the cell administrator is not assigned a commonly known password. This variable is used in conjunction with the DEFAULT_PW variable. T} _ CHECK_TIME@T{ .iX "CHECK_TIME dce_config environment variable" Specifies whether or not to check client and server clock synchronization: \*Ly\*O indicates the time will be checked; \*Ln\*O indicates it will not. The default is \*Ly\*O. T} _ DC_DISPLAY_THRESHOLD@T{ .iX "DC_DISPLAY_THRESHOLD dce_config environment variable" Specifies the messages to write to stdout. Possible values are \*LERROR\*O, \*LWARNING\*O, \*LSUMMARY\*O, \*LDETAIL\*O, \*LVERBOSE\*O, and \*LDEBUG\*O. The default is SUMMARY. T} _ DC_LOG_THRESHOLD@T{ .iX "DC_LOG_THRESHOLD dce_config environment variable" Specifies the Minimum priority log messages to write to the log file, \*L/tmp/dce_config.log\*O. Possible values are \*LERROR\*O, \*LWARNING\*O, \*LSUMMARY\*O, \*LDETAIL\*O, \*LVERBOSE\*O, and \*LDEBUG\*O. The default is DEBUG. T} _ DEFAULT_MAX_ID@T{ .iX "DEFAULT_MAX_ID dce_config environment variable" The highest value UNIIX ID for principals. The default value is 2147483646, which means that only principals with UNIX IDs lower than 2147483646 can access the cell. It is recommended that you accept the default. Used during Security Server configuration. T} _ DEFAULT_PW@T{ .iX "DEFAULT_PW dce_config environment variable" Contains the default password used when the registry is created. This variable is used to determine if the cell administrator's password (CELL_ADMIN_PW) is the same as the default password. When the user exits \*Ldce_config\*O, the value of DEFAULT_PW and CELL_ADMIN_PW are checked. If they are the same and if the CHANGE_PW variable is set \*LY\*O, \*Ldce_config\*O issues the warning message \*CPassword must be changed\*O. The default for this variable is \*L-dce-\*O. If your site has a commonly used and known password, change the DEFAULT_PW variable to that password to help ensure that the cell administrator account is not assigned a commonly known password. T} _ DIR_REPLICATE@T{ .iX "DIR_REPLICATE dce_config environment variable" Controls the replication of CDS directories when an additional CDS server is being created at DCE configuration time. The value \*Ly\*O will cause \*Ldce_config\*O to prompt for more directories to replicate; \*Ln\*O will not. The default is \*Ln\*O. T} _ DO_CHECKS@T{ .iX "DO_CHECKS dce_config environment variable" Controls the display of three prompts. The first is whether or not the \*C Press to continue, CTRL-C to exit:\*O prompt is returned when \*Ldce_config\*O encounters a non-fatal error. This prompt forces the user to acknowledge the error and offers a way to exit \*Ldce_config\*O. The second and third prompt occur during master Security server configuration. They prompt for a UNIX ID number at which the Security server will start assigning automatically generated group UNIX IDs and principal UNIX IDs. If this prompt is turned off, the default is the default described in the \*LDEFAULT_MAX_ID\*O and \*LGID_GAP\*O variables. For the \*LDO_CHECKS\*O variable, \*Ly\*O displays the prompt; \*Ln\*O does not. The default is \*Ly\*O. T} _ EXIT_ON_ERROR@T{ .iX "EXIT_ON_ERROR dce_config environment variable" An indication of whether or not \*Ldce_config\*O will exit in the event of a fatal error: \*Ly\*O indicates that \*Ldce_config\*O exits when it encounters a fatal error; \*Ln\*O indicates it will not. The default is \*Ln\*O. Setting this variable to \*Ly\*O or \*Ln\*O can help prevent a "here" file from getting out of sync with \*Ldce_config\*O. T} _ GID_GAP@T{ .iX "GID_GAP dce_config environment variable" The increment above highest currently used GID at which the Security service will start assigning automatically generated GIDs. The value of this variable is used with the LOW_GID variable to set the starting point for UIDs automatically assigned by the Security server. Default is 100. Used in Security server configuration. T} _ HOST_NAME_IP@T{ .iX "HOST_NAME_IP dce_config environment variable" The IP address of node on which \*Ldce_config\*O is running. T} _ KEYSEED@T{ .iX "KEYSEED dce_config environment variable" A character string used to seed the random key generator in order to create the master key for the master and each slave database. Each database has its own master key and thus keyseed. Used in Security server configuration. T} _ LAN_NAME@T{ .iX "LAN_NAME dce_config environment variable" For multiple LAN configurations, the internal name of the LAN (in the LAN profile). Used in CDS server configuration. T} _ LOGFILE@T{ .iX "LOGFILE dce_config environment variable" The full pathname of the log file produced by \*Ldce_config\*O. The default is \*L/tmp/dce_config.log\*O T} _ LOW_GID@T{ .iX "LOW_GID dce_config environment variable" The value at which the Security server will start assigning automatically generated group IDs. The default is the value of the highest group ID currently used on the machine being configured, incremented by the value of GID_GAP. Although there is no restriction that the value of LOW_GID must be higher than the machine's highest group ID, if you supply a LOW_GID that is less than or equal to the highest currently used group ID, \*Ldce_config\*O issues a warning message and prompts the user to reenter LOW_GID. Used in master Security server configuration. T} _ LOW_UID@T{ .iX "LOW_UID dce_config environment variable" The value at which the Security Server will start assigning automatically generated UNIX IDs. The default is the value of the highest UNIX ID currently used on the machine being configured, incremented by the value of UID_GAP. Although there is no restriction that the value of LOW_UID must be higher than the machine's highest UNIX ID, if you supply a LOW_UID that is less than or equal to the highest currently used UNIX ID, \*Ldce_config\*O issues a warning message and prompts the user to reenter LOW_UID. Used in master Security server configuration. T} _ MULTIPLE_LAN@T{ .iX "MULTIPLE_LAN dce_config environment variable" An indication of whether or not to configure the node with multiple LAN capabilities: \*Ly\*O indicates configure with multiple LAN capabilities, \*Ln\*O indicates do not. Used in CDS configuration T} _ NTP_HOST@T{ .iX "NTP_HOST dce_config environment variable" The name of the host on which the NTP time provider server is running. Used in DTS Time Provider configuration. T} _ PWD_MGMT_SVR@T{ .iX "PWD_MGMT_SVR dce_config environment variable" The default pathname to the Password Management server, which is \*L$DCELOCAL/bin/pwd_strength\*O. Used in Password Management server configuration. T} _ PWD_MGMT_SVR_OPTIONS@T{ .iX "PWD_MGMT_SVR_OPTIONS dce_config environment variable" The default option or options for the Password Management server (\*Lpwd_strength\*O). The value of the variable is set to \*L-v\*O (verbose) at server configuration. T} _ REMOVE_PREV_CONFIG@T{ .iX "REMOVE_PREV_CONFIG dce_config environment variable" An indication of whether or not to remove all remnants of previous configurations before performing the new configuration: \*Ly\*O indicates remove all remnants; \*Ln\*O indicates do not. Be aware that if you set this variable to \L*y\*O, \*Ldce_config\*O will stop and remove all configured components each time you configure any component, and you must reconfigure them all. Used in all component configurations. T} _ REP_CLEARINGHOUSE@T{ .iX "REP_CLEARINGHOUSE dce_config environment variable" The name for new clearinghouse. Used in additional CDS server configuration. T} _ SEC_SERVER@T{ .iX "SEC_SERVER dce_config environment variable" The name of the machine on the the cell's master Security server runs. Used in security client configuration. T} _ SEC_SERVER_IP@T{ .iX "SEC_SERVER_IP dce_config environment variable" The IP address for server named in SEC_SERVER. T} _ SYNC_CLOCKS@T{ .iX "SYNC_CLOCKS dce_config environment variable" An indication of whether or not to synchronize all client clocks with the Security server clock: \*Ly\*O indicates that client and server clocks will be synchronized; \*Ln\*O indicates they will not. If this variable is set to \*Ln\*O, and clocks are out of sync by more than the value specified in the TOLERANCE_SEC variable, the user is prompted for whether or not to synchronize them. This variable is valid only if the CHECK_TIME variable is set to \*Ly\*O. For DFS machine configurations, this variable should be set to \*Ly\*O. T} _ TIME_SERVER@T{ .iX "TIME_SERVER dce_config environment variable" Specifies the host that the Security client will try to synchronize its clock against. This host must have a DTS server (\*Ldtsd\*O) running on it. The recommended choice for the host is the one running the master Security server (the name specified in the SEC_SERVER variable). T} _ TOLERANCE_SEC@T{ .iX "TOLERANCE_SEC dce_config environment variable" The number of seconds a client system clock can differ from the Security server system clock before either the user prompted to synchronize clocks or clocks are synchronized automatically. The default is 120 seconds. Both the Security service and the CDS service require that be no more than a 5-minute difference between the clocks on any two nodes in a cell. For a DFS File Location Database Server, the variable should not be set to less than 90 seconds. T} _ UID_GAP@T{ .iX "UID_GAP dce_config environment variable" The increment above highest currently used UID at which the Security service will start assigning automatically generated UIDs. The value of this variable is used with the LOW_UID variable to set the starting point for UIDs automatically assigned by the Security server. Default is 100. Used in Security server configuration. T} _ UNCONFIG_HOST_PRESET@T{ .iX "UNCONFIG_HOST_PRESET dce_config environment variable" The name of the node to be unconfigured. Used with the \*Lunconfigure\*O option. T} .TE .P .TB "dfs_config Environment Variables" .TS center,box,tab(@); lB | lB l | l. Variable@Value _ AGG_FS_TYPE@T{ .iX "AGG_FS_TYPE dce_config environment variable" The type of filesystem for the aggregate to be exported. Possible values are \*Lnative\*O meaning the native file system (e.g. UFS, JFS) or \*Lepisode\*O meaning the Episode (LFS) file system. T} _ AGG_DEV_NAME@T{ .iX "AGG_DEV_NAM dce_config environment variable" The device name of the aggregate to be exported, T} _ AGG_MOUNT_PATH@T{ .iX "AGG_MOUNT_PATH dce_config environment variable" The mount path for the aggregate (e.g. /usr/users). T} _ AGG_NAME@T{ .iX "AGG_NAME dce_config environment variable" The name to be used for the aggregate to be exported (e.g. user.jlw). T} _ AGG_ID@T{ .iX "AGG_ID dce_config environment variable" The unique numerical aggregate ID for the exported aggregate. T} _ CACHE_SIZE_RAM@T{ .iX "CACHE_SIZE_RAM dce_config environment variable" The number of bytes to use for an in-memory cache. T} _ CACHE_SIZE_DISK@T{ .iX "CACHE_SIZE_DISK dce_config environment variable" The number of bytes to use for a local disk cache. T} _ CACHE_DIR_DISK@T{ .iX "CACHE_DIR_DISK dce_config environment variable" The pathname of the directory to use for a local disk cache. T} _ CLIENT_CACHE_LOC@T{ .iX "CLIENT_CACHE_LOC dce_config environment variable" An indication of whether the cache is stored in memory or on disk. machine values are \*Lmem\*O meaning the cache is stored in memory or \*Ldisk\*O meaning the cache is stored on the local disk. T} _ CONFIG_NFS_GATEWAY@T{ .iX "CONFIG_NFS_GATEWAY dce_config environment variable" An indication of whether or not to configure the DFS client as an NFS gateway. Possible values are \*Ly\*O and \*Ln\*O; \*Ln\*O is the default. T} _ EPI_FORMAT_PART@T{ .iX "EPI_FORMAT_PAR dce_config environment variable" An indication of whether or not to format a disk partition as an Episode aggregate. Possible values are \*Ly\*O to format the partition or \*Ln\*O to not. T} _ EPI_FORCE_INIT@T{ .iX "EPI_FORCE_INIT dce_config environment variable" An indication of whether or not to force the initialization of a partition as an Episode aggregate, possibly losing data. Possible values are \*Ly\*O or the initialization or \*Ln\*O to not. T} _ INIT_LFS@T{ .iX "INIT_LFS dce_config environment variable" An indication of whether or not to initialize the LFS (using \*Lepiinit\*O). Possible values are \*Ly\*O to initialize or \*Ln\*O to not. T} _ LOAD_LFS_KEXT@T{ .iX "LOAD_LFS_KEXT dce_config environment variable" An indication of whether or not to load the LFS kernel extensions. Possible values are \*Ly\*O to load or \*Ln\*O to not. T} _ ROOT_FILESET_NM@T{ .iX "ROOT_FILESET_NM dce_config environment variable" The name of the DFS root fileset. T} _ SCM_NAME@T{ .iX "SCM_NAME dce_config environment variable" The name of the system control machine to be used during configuration. T} _ .TE .PP .SS "Component Scripts" .PP .iX "dce_config" "component scripts" The \*Ldce_config\*O script calls component scripts that reside in the \*L/opt/dcelocal/etc\*O directory (or in the \*Letc\*O directory of the install area) with symbolic links to \*L/etc\*O. In a custom configuration script, you can call the component scripts directly and supply the required input via the environment variables. The names and functions of the component scripts follows: .ML .LI .iX "dce_shutdown dce_config component script" \*Ldce_shutdown\*O\(emShuts down all DCE server processes (\*Lauditd\*O, \*Ldtsd\*O, \*Lcdsadv\*O, \*Lcdsd\*O, and \*Lsecd\*O), except for DFS processes (\*Ldfsd\*O) via the \*Ldcecp\*O or other control programs. This script must be run on the machine running the daemon processes. You must be \*Lroot\*O or another privileged user to run the script. You should always run the script before reconfiguring DCE. .P If the \*Ldce_shutdown\*O script cannot shut down a daemon gently, it sends a kill signal to all the DCE daemons. If for any reason you do not want to use a control program, you can execute the script manually. The \*Ldce_shutdown\*O script run with its \*L-f\*O option will find and kill the DCE daemons. This behavior is the same as that of the \*Ldce.clean\*O script, which was included in DCE R1.0.3 and previous releases. DCE R1.1 does not include the \*Ldce.clean\*O script, but provides the name as a symbolic link to the \*Ldce_shutdown\*O script for the user's convenience. .LI .iX "dfs.clean dce_config component script" \*Ldfs.clean\*O\(emKills DFS server processes. This script must be run on the machine running the processes. It should be run before reconfiguring DCE. (Note that some DFS daemon processes cannot be killed by \*Ldfs.clean\*O.) .LI .iX "dce.rm dce_config component script" \*Ldce.rm\*O [\*Linstall\*O]\(emRemoves all data and configuration files created by DCE servers after initial configuration except for data and files created by DFS servers. This script must be run on the machine running the processes. It should be run before reconfiguring DCE. If you invoke the script with the \*Linstall\*O parameter, the script removes the binary files added during installation. .LI .zA "def,10220,R1.1,Remove reference to rpcd and sec_clientd" .iX "dfs.rm dce_config component script" \*Ldfs.rm\*O\ [\*Linstall\*O]\(emRemoves data and configuration files created by DFS servers after initial configuration. This script must be run on the machine running the processes, and \*Ldced\*O must be running on that machine. The \*Ldfs.rm\*O script should be run before reconfiguring DCE. If you invoke the script with the \*Linstall\*O parameter, the script removes the binary files added during installation. Note that this script invokes the \*Ldce.clean\*O script. .zZ "def,10220,R1.1,Remove reference to rpcd and sec_clientd" .LI .iX "dce.unconfig dce_config component script" \*Ldce.unconfig\*O \*Vhostname\*O\(emRemoves all DCE clients on \*Vhostname\*O from the Security and Directory service databases. It should be run before reconfiguring a client machine. .LI .iX "dfs.unconfig dce_config component script" \*Ldfs.unconfig\*O \*Vhostname\*O\(emRemoves the DFS client on \*Vhostname\*O from the Security and Directory service databases. It should be run before reconfiguring a client machine. .LI .iX "dce_com_env dce_config component script \*Ldce_com_env\*O\(emSets environment variables. .LI .iX "dce_config_env dce_config component script" \*Ldce_config_env\*O\(emCalls the \*Ldce_com_env\*O script that sets the environment variables. .LI .iX "dce_com_utils dce_config component script" \*Ldce_com_utils\*O\(emContains common functions used by \*Ldce_config\*O and \*Ldfs_config\*O. .LI .iX "dce_config_utils dce_config component script" \*Ldce_config_utils\*O\(emContains internal routines used by \*Ldce_config\*O scripts. .LI .iX "dfs_config dce_config component script" \*Ldfs_config\*O\(emConfigures a machine as a DFS server or client. .LI .iX "rc.dce dce_config component script" \*Lrc.dce\*O\(emStarts DCE daemons. This script cannot be run remotely; it must be run on the machine on which the daemons are being started. .LI .iX "rc.dfs dce_config component script" \*Lrc.dfs\*O\(emStarts DCE daemons. This script cannot be run remotely; it must be run on the machine on which the daemons are being started. .LE .zZ "enh,9287,add new options" .PP .SS "Privilege Required" .PP You must have \*Lroot\*O authority to run the \*Ldce_config\*O command. ...\" .SS "Environment Variables" ...\" .zA "enh,9287,clarify variables" ...\" The following variables are set during DCE installation: ...\" .zZ "enh,9287,clarify variables" .PP ...\" \*LBIND_PE_SITE=1\*O ...\" .nL ...\" \*LDCEROOT=/opt ...\" .nL ...\" \*LDCELOCAL=$DCEROOT/dcelocal ...\" .nL ...\" \*LDCEINSTDIR=$DCEROOT/dce1.0 ...\" .nL ...\" \*LDCESHARED=$DCEROOT/dce ...\" .nL ...\" \*LSUBSYSDIR=subsys/dce ...\" .nL ...\" \*LSECURITYDIR=security ...\" .nL ...\" \*LDFSDIR=dfs ...\" .nL ...\" \*LHOSTNAME=\*Vhostname\*O ...\".zZ "enh,9287,clarify variables" .PP .SH "EXIT VALUES" .PP In case of an error, this command repeats requests for correct input. The user can exit the program from any menu. ...\" .SH "EXAMPLES" ...\" .PP ...\" .AL ...\" .LI ...\" The following example shows ...\" .iS ...\" .iE ...\" .LI ...\" The following example shows ...\" .iS ...\" .iE ...\" .LE ...\" .cE .SH "RELATED INFORMATION" .PP Books: \*VOSF DCE Administration Guide\*O ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" .rm zA .rm zZ .TH dce_intro "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .SH NAME .PP \*Ldce_intro\*O - Introduction to the general DCE administration tools .SH "DESCRIPTION" .zA "defect,CR4680,R1.0.2,new dce_intro(1) manpage" .zA "defect,10014,R1.1,dcecp doc additions" .zA "defect,9830,R1.1,dced doc additions" .PP This section describes publicly accessible DCE administration commands that are general to DCE rather than specific to a particular component. These commands are as follows: .VL .zA "enh,5923,R1.1,moving '1' ref pages to '1m' creates new intro page" .LI "\*Lcsrc\*O" The \*Lcsrc\*O utility is the code set registry compiler, which builds a DCE character and code set registry on a host from a source file supplied by a cell administrator. Administrators run the \*Lcsrc\*O utility when they are building an "internationalized" DCE cell. .LI "\*Ldce_config\*O" The \*Ldce_config\*O shell command invokes a menu-driven interface that installs, configures, and starts up DCE. The \*Ldce_config\*O command displays a hierarchy of menus and invokes individual installation and configuration routines, according to users' menu selections. .LI "\*Ldcecp\*O" The \*Ldcecp\*O control program is the primary DCE administration interface, providing remote access to routine DCE administrative functions. .LI "\*Ldced\*O" The DCE host daemon is a process that provides services for the local host, and is also the server used by remote applications to access these host services. .LI "\*Lgetcellname\*O" Returns the name of the local cell. .LI "\*Lgetip\*O" Returns the IP address for a given machine name. .LE .SH RELATED INFORMATION .PP See each command's reference page for further information. .zZ "enh,5923,R1.1,moving '1' ref pages to '1m' creates new intro page" .zZ "defect,10014,R1.1,dcecp doc additions" .zZ "defect,9830,R1.1,dced doc additions" .zZ "defect,CR4680,R1.0.2,new dce_intro(1) manpage" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\"Copyright Hewlett-Packard Company 1992 ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" .rm zA .rm zZ .TH dce_login "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldce_login\*O command" .iX "Security Service commands" "\*Ldce_login\*O" .iX "principals" "setting security for" .SH NAME \*Ldce_login\*O \- Validates a principal's identity and obtains the principal's network credentials .SH "SYNOPSIS" .PP .zA "enh,6668,R1.0.2,add -exec" .sS \*Ldce_login\*O \*O[\*Vprincipal_name\*O] \*O[\*Vpassword\*O] \*O[\*L-c\*O | \*L-k \*Vkeytable\*O] \*L[\*L-r\*O] \*O \*L[-e[xec] \*Vcmd_string\*L]\*O .zZ "enh,6668,R1.0.2,add -exec" .sE .SH "OPTIONS" .VL 1.25i .LI "\*L-c\*O" Causes the principal's identity to be certified. If you do not specify \*L\-c\*O, the principal's identity is validated only. .LI "\*L-k \*Vkeytable\*O" Retrieves the authentication key from \*Vkeytable\*O. .LI "\*L-r\*O" Refreshes and validates the current login ID. .zA "enh,6668,R1.0.2,add -exec" .LI "\*L-e[xec] \*Vcmd_string\*L\*O" Executes the command supplied as \*Vcmd_string\*L. .zZ "enh,6668,R1.0.2,add -exec" .LE .SH "ARGUMENTS" .VL 1.25i .LI "\*Vprincipal_name\*O" The name of the principal to log in as. .LI "\*Vpassword\*O" The password for \*Vprincipal_name\*O. .LE .SH "DESCRIPTION" .PP The \*Ldce_login\*O command is supplied for use in DCE configuration. It validates a principal's identity and obtains the principal's network credentials. .PP If the \*L\-c\*O option is supplied, the command also certifies the principal's identity, and, if the principal is able to be certified, creates an entry for the principal in the machine's local registry. If the principal is not able to be certified, the command attempts to log the principal in via the local registry. .PP .zA "enh,6668,R1.0.2,add -exec" The \*L-exec\*O option executes the command specified by \*Vcmd_string\*O after login. If \*Vcmd_string\*O is specified without a full pathname, the path prefix is obtained by searching the directories according to the \*LPATH\*O variable. .zZ "enh,6668,R1.0.2,add -exec" .PP If you do not supply the name of the principal to validate, either on the command line with the \*Vprincipal_name\*O argument or through the \*L-r\*O option that retrieves the principal name from the current login context, \*Ldce_login\*O prompts for the principal name. If you do not supply the principal's authentication key either on the command line with \*Vpassword\*O argument or through the \*L-k\*O option that retrieves the principal authentication key from the specified keytable, \*Ldce_login\*O prompts for the password. .PP If you supply the principal name and password on the command line, you must specify the principal name first, followed by the password. If you supply the \*Lprincipal_name\*O argument and the \*L-r\*O option, the named principla must be the principal of the current network identity. .PP The \*Ldce_login\*O command executes the shell specified in the \*LSHELL\*O environment variable. .PP .zA "def,7704,R1.0.3,effect of clock skew" Note that if the clocks on the Security server and client machines are not synchronized to within 2 or 3 minutes of each other, you may receive a password validation error and be unable to be validated. .zZ "def,7704,R1.0.3,effect of clock skew" ...\" .rm zA .rm zZ .TH dce_version 8 "" "HP DCE" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .ds )H Hewlett-Packard Company .ds ]W HP DCE/9000 Version 1.2 .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml .SH NAME \*Ldce_version\*O - print version information for HP DCE/9000 components .SH "SYNOPSIS" \*L/opt/dcelocal/etc/dce_version\*O [\*L-uvlG\*O] [\*L-g \*Vgroup_list\*O] [\*L-f \*Vversion_file\*O] [\*Vfiles\*O ... ] .SH "OPTIONS" .VL 1i .LI "\*L-u\*O" Print a usage message. .LI "\*L-v\*O" Print DCE version. This is the default behavior. .LI "\*L -l\*O" List available groups of interesting files. .LI "\*L-F\*O" Print the name of the default version information file. .LI "\*L-G\*O" Search files in all groups for \*Lwhat\*O strings. .LI "\*L-g \*Vgroup_list\*O" Search files in groups specified by \*Vgroup_list\*O for \*Lwhat\*O strings. \*Vgroup_list\*O is a comma or white-space-separated list of group names. The available group names can be listed with \*L-l\*O. .LI "\*L-f \*Vversion_file\*O" Specify an alternate version information file to use. The version information file contains the DCE version string and group/file lists. The default version information file is \*L/opt/dcelocal/etc/dce_vinfo\*O. .LE .SH "DESCRIPTION" By default, \*Ldce_version\*O prints the version of DCE that is currently installed. It can also print the \*Lwhat\*O strings for one or more groups of ``interesting'' DCE files, list the available group names and descriptions, or search any specified file for DCE \*Lwhat\*O strings. More than one action can be specified in a single invocation of \*Ldce_version\*O. .PP Filenames to be searched for DCE \*Lwhat\*O strings should be specified after any command line options. .SH "FILES" \*L/opt/dcelocal/etc/dce_vinfo\*O .SH "SEE ALSO" \*Lwhat(1)\*O ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH dcecp 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "DCE Control Program commands" "dcecp" .SH NAME \*Ldcecp\*O - Administrative interface for DCE management tasks .SH "SYNOPSIS" .PP .sS ...\" .zA "def,13377,R1.2.2, clarified syntax" ...\" .zA "1.2.1: add -local" \*Ldcecp\*O \*L[-s] [-local] [\*Vscript_name\*L | -c \*Vcommand\*O ] ...\" .zZ "1.2.1: add -local" .sE ...\" .zZ "def,13377,R1.2.2, clarified syntax" .SH "OPTIONS" .PP .VL 1i .LI "\*L-c\*O \*Vcommand\*O" A list containing one or more valid \*Ldcecp\*O commands. For a description of the \*Ldcecp\*O command format, see \*LAdministration Objects\*O. .LI "\*L-s\*O" Turns off inheritance of the login context. The default is to inherit the current login context of the principal that invokes \*Ldcecp\*O. ...\" .zA "1.2.1: add -local" .LI "\*L-local\*O The \%\*L-local\*O option specifies that the command should operate on the local \*Ldced\*O object while the \*Ldced\*O object is in a partial-service state. ...\" .zZ "1.2.1: add -local" .LE .SH "ARGUMENTS" .PP .VL 1i .LI "\*Vscript_name\*O" Filename of a user-defined script containing \*Ldcecp\*O commands. .LE .SH "DESCRIPTION" .PP The DCE control program, \*Ldcecp\*O, is the primary DCE administration interface, providing local and remote access to routine DCE administrative functions from any DCE Version 1.1 and later platform. .PP The DCE control program is built on a portable command language called the tool command language (Tcl). Tcl allows the use of variables, if statements, list processing functions, loop functions and many other features commonly found in command languages. The control program extends these features, providing a set of commands for manipulating specific DCE objects. The control program also includes task scripts to help administrators perform some routine DCE management functions. ...\" Refer to the \*(Ac for information about the basic concepts and features of \*Ldcecp\*O. Refer to the \*VOSF DCE Administration Guide Core Volume\*O for information about the basic concepts and features of \*Ldcecp\*O. All of Tcl is included in the \*Ldcecp\*O language. .SS "Invoking and Terminating dcecp" .PP The DCE control program allows you to invoke \*Ldcecp\*O commands in the following modes: .ML .LI Interactive mode .LI Command-line mode .LE .VL .LI "\*LInteractive Mode\*O" Activate interactive mode by entering the \*Ldcecp\*O command without any arguments. At the \*Ldcecp\*O prompt enter a \*Ldcecp\*O or Tcl command; \*Ldcecp\*O executes the command, displays the result, and is ready to accept another command. .oS % \*Ldcecp\*O dcecp> \*Ldirectory list /.: -directories\*C /.:/hosts /.:/subsys dcecp> .oE .PP .LI "\*LCommand-Line Mode\*O" Activate command-line mode from the system prompt by using one of the following methods: .ML .LI Enter the \*Ldcecp\*O command with a filename of a script containing \*Ldcecp\*O commands (and/or other valid Tcl commands), as follows: .PP .iS \*C% \*Ldcecp myown.Tcl .iE .LI Enter the \*Ldcecp\*O command with the \%\*L-c\*O option followed by a list containing one or more \*Ldcecp\*O commands, as follows: .iS \*C% \*Ldcecp -c directory create /.:/admin/printers .iE .PP Enter multiple \*Ldcecp\*O commands by separating them with a \*L;\*O (semicolon) and enclosing the commands in \*L""\*O (double quotes). Remember to escape shell metacharacters (for example by enclosing them in double quotes). Multiple commands must be on a single line, as follows: .iS \*C% \*Ldcecp -c "directory create /.:/admin/printers;directory show /.:/admin/printers" .iE When you use the \*L-c\*O option, operation results return to the interpreter, not to the shell. If you enter multiple operations, the output of the last operation is returned to the shell. This can be overcome by using the following ugly, but serviceable workaround: .iS % \*Ldcecp -c "puts [dir help]; puts [principal help]"\*O .iE .LE .LE .PP Terminate an interactive \*Ldcecp\*O session by using the \*Lexit\*O and \*Lquit\*O commands. Use the following command syntax: .iS exit \*Vn\*L quit \*Vn .iE Use the \*Vn\*O argument to specify the exit value returned to the shell. The following example terminates a session and returns an exit value of 56 to the shell: .iS exit 56 .iE By default, \*Ldcecp\*O returns \*L0\*O (zero) on success and \*L1\*O if a command fails. .SS "Startup Scripts" .PP When you invoke \*Ldcecp\*O, the following script files are executed in the order shown: .VL .LI "\*L[info library]/init.tcl\*O" Contains the standard Tcl initialization scripts with definitions for the \*Lunknown\*O\ command and the \*Lauto_load\*O facility. .LI "\*L$dcecp_library/init.dcecp\*O" Contains the initialization scripts implementing the \*Ldcecp\*O commands and tasks. The implementation sets the Tcl variable \*Ldcecp_library\*O to \*Vdceshared\*L/dcecp\*O by default. .LI "\*L$HOME/.dcecprc\*O" Contains user customizations. .LE .SS "Administration Objects" .PP A \*Ldcecp\*O command has the following syntax: ...\" .zA "def,13377,R1.2.2,clarify syntax" .sS \*Vobject operation \*O[\*Vargument\*O] [\*V-option\*O [\*Vopt_arg\*O]]\*V \&.\&.\&. .sE ...\" .zZ "def,13377,R1.2.2,clarify syntax" .PP where: .PP .VL .LI "\*Vobject\*O" Specifies the name of a \*Ldcecp\*O administration object. Examples of administration objects are Cell Directory Service (CDS) directories, access control lists (ACLs), Distributed Time Service (DTS) servers, server control objects, and so on. Each administration object is briefly described below. .LI "\*Voperation\*O" Specifies the name of an action such as \*Lcreate\*O, \*Lshow\*O, or \*Lremove\*O, that is to be performed on an administration object. For complete descriptions of operations supported by each \*Ldcecp\*O object, refer to individual object reference pages. Common operations are briefly described below. .LI "\*Vargument\*O" Specifies the name of one or more specific objects to operate on. Most, but not all, \*Ldcecp\*O objects take an argument. Refer to the individual reference pages for descriptions of the arguments supported by various objects. .LI "\*V-option\*O" Specifies a qualifier that controls the precise behavior of a \*Ldcecp\*O command. Most, but not all, \*Ldcecp\*O commands take options. Specify options by preceding the option name with a dash as in \*L-replica\*O. Some options take an argument, \*Vopt_arg\*O, that can be a name or a value. The following command shows a \%\*L-clearinghouse\*O option and its argument, which is the name of a CDS clearinghouse: .PP .iS directory create /.:/admin -clearinghouse /.:/boston_ch .iE .LE .PP The DCE control program supports the following \*Ldcecp\*O administration objects. For complete descriptions of the administration objects, refer to the individual object reference pages. .VL 1i .LI "\*Laccount\*O" Manages an account in the DCE Security Service registry. .LI "\*Lacl\*O" Manages any DCE ACLs. .LI "\*Lattrlist\*O" Manipulates attribute lists in scripts. .LI "\*Laud\*O" Manages the audit daemon (\*Lauditd\*O) on any DCE host. .LI "\*Laudevents\*O" Displays the audit event classes on any DCE host. .LI "\*Laudfilter\*O" Manages audit event filters on any DCE host. .LI "\*Laudtrail\*O" Displays audit trail files on the local host. .LI "\*Lcds\*O" Manages the CDS server daemon on any DCE host. .LI "\*Lcdsalias\*O" Manages cell names known to CDS. .LI "\*Lcdscache\*O" Manages the CDS clerk cache on any DCE host. .LI "\*Lcdsclient\*O" Manages the CDS client daemon on any DCE host. .LI "\*Lcell\*O" Performs cell-wide tasks. .LI "\*Lcellalias\*O" Performs cell aliasing and connection tasks. .LI "\*Lclearinghouse\*O" Manages CDS clearinghouses on the local host. .LI "\*Lclock\*O" Manages the clock on any DCE host. .LI "\*Ldirectory\*O" Manages directory entries in the CDS namespace. .LI "\*Ldts\*O" Manages DTS on any host. .LI "\*Lendpoint\*O" Displays remote endpoints, manages local endpoints. .LI "\*Lgroup\*O" Manages DCE groups in the security service. .LI "\*Lhost\*O" Performs tasks involving a host in a DCE cell. .LI "\*Lhostdata\*O" Manages host specific information on any DCE host. .LI "\*Lhostvar\*O" Manages host-specific variables on the local DCE host. .LI "\*Lkeytab\*O" Manages server key tables on any DCE host. .LI "\*Llink\*O" Manages softlinks in CDS. .LI "\*Llog\*O" Manages routing for DCE serviceability messages. .LI "\*Lname\*O" Manages CDS name translation. .LI "\*Lobject\*O" Manages object entries in CDS. .LI "\*Lorganization\*O" Manages DCE organizations in the security service. .LI "\*Lprincipal\*O" Manages DCE principals in the security service. .LI "\*Lregistry\*O" Manages any DCE security replica and registry wide info. .LI "\*Lrpcentry\*O" Manages a server entry in CDS. .LI "\*Lrpcgroup\*O" Manages a group entry in CDS. .LI "\*Lrpcprofile\*O" Manages a profile entry in CDS. .LI "\*Lsecval\*O" Manages the security validation service on any DCE host. .LI "\*Lserver\*O" Manages DCE servers on any DCE host. .LI "\*Luser\*O" Performs tasks involving individual user information. .LI "\*Lutc\*O" Manipulates Universal Time Coordinated (UTC) timestamps. .LI "\*Luuid\*O" Manipulates (generates or compares) Universal Unique Identifiers (UUIDs). .LI "\*Lxattrschema\*O" Manages schemas for extended registry attributes (ERAs). .LE ...\" .cS ...\" ******SAVING TABLE CODING******************* ...\" .ne 5i ...\" .TS ...\" tab(@); ...\" lw(.25i) lw(5.75i). ...\" \*Laccount\*O@T{ ...\" Manages an account in the DCE Security Service registry. ...\" T} ...\" \*Lacl\*O@T{ ...\" Creates, modifies, and removes access control lists. ...\" T} ...\" \*Lattrlist\*O@T{ ...\" Manipulates attribute lists. ...\" T} ...\" \*Laud\*O@T{ ...\" Manages the audit daemon (\*Lauditd\*O) on a DCE host. ...\" T} ...\" \*Laudevents\*O@T{ ...\" Manages audit event classification on a DCE host. ...\" T} ...\" \*Laudfilter\*O@T{ ...\" Manages audit event filters on a DCE host. ...\" T} ...\" \*Laudtrail\*O@T{ ...\" Controls the output format for audit events captured on a DCE host. ...\" T} ...\" \*Lcdsalias\*O@T{ ...\" Manages cell names known to CDS. ...\" T} ...\" \*Lcdscache\*O@T{ ...\" Manages the CDS clerk cache on a DCE host. ...\" T} ...\" \*Lcell\*O@T{ ...\" Manages cell configuration information. ...\" T} ...\" \*Lcellalias\*O@T{ ...\" Manages cell names across all of DCE. ...\" T} ...\" \*Lclearinghouse\*O@T{ ...\" Manages CDS clearinghouse operations in a DCE cell. ...\" T} ...\" \*Lclock\*O@T{ ...\" Manages the clock on a local DCE host. ...\" T} ...\" \*Ldirectory\*O@T{ ...\" Manages directories in the DCE Cell Directory Service. ...\" T} ...\" \*Ldts\*O@T{ ...\" Manages Distributed Time Service servers and clerks. ...\" T} ...\" \*Lendpoint\*O@T{ ...\" Manages endpoint information in a DCE host's endpoint map. ...\" T} ...\" \*Lgroup\*O@T{ ...\" Manages groups in the DCE Security Service registry. ...\" T} ...\" \*Lhost\*O@T{ ...\" Manages hosts within a cell. ...\" T} ...\" \*Lhostdata\*O@T{ ...\" Manages a DCE host's principal name and cell ...\" affiliation information on the host. ...\" T} ...\" \*Lkeytab\*O@T{ ...\" Manages server passwords on DCE hosts. ...\" T} ...\" \*Llink\*O@T{ ...\" Manages softlinks in the DCE Cell Directory Service. ...\" T} ...\" \*Llog\*O@T{ ...\" Manages routing for DCE serviceability messages. ...\" T} ...\" \*Lname\*O@T{ ...\" Manipulates names in the DCE namespace. ...\" T} ...\" \*Lobject\*O@T{ ...\" Manages object entries in the DCE Cell Directory Service. ...\" T} ...\" \*Lorganization\*O@T{ ...\" Manages organizations in the DCE Security Service registry. ...\" T} ...\" \*Lprincipal\*O@T{ ...\" Manages principals in the DCE Security Service registry. ...\" T} ...\" \*Lregistry\*O@T{ ...\" Manages the database of a DCE Security Service registry. ...\" T} ...\" \*Lrpcentry\*O@T{ ...\" Manages a server entry stored in the DCE Cell Directory Service. ...\" T} ...\" \*Lrpcgroup\*O@T{ ...\" Manages a group entry stored in the DCE Cell Directory Service. ...\" T} ...\" \*Lrpcprofile\*O@T{ ...\" Manages a profile entry stored in the DCE Cell Directory Service. ...\" T} ...\" \*Lschema\*O@T{ ...\" Manages the schema information for extended registry attributes. ...\" T} ...\" \*Lsecval\*O@T{ ...\" Manages the security validation service in \*Ldced\*O. ...\" T} ...\" \*Lserver\*O@T{ ...\" Manages servers and their configuration information on DCE hosts. ...\" T} ...\" \*Luser\*O@T{ ...\" Manages a DCE user. ...\" T} ...\" \*Lutc\*O@T{ ...\" Manipulates UTC timestamps. ...\" T} ...\" \*Luuid\*O@T{ ...\" Manipulates (generate or compare) UUID's. ...\" T} ...\" .cE .SS "Common Operations" .PP This section gives a description of operations that are common to more than one object. Some operations presented here are implemented in all objects, some in only a few, and some only for specific types of objects such as containers (for instance, CDS directories). .PP The descriptions in the sections on individual objects may override some of the information presented here. Usually this is only in the form of an operation accepting more options, but other changes are possible. .VL .LI "\*Ladd\*O" Adds an object to a container. It is implemented for all objects that represent containers. This operation returns an empty string on success. The argument is a list of names of containers. The required \%\*L-member\*O option is used to specify the name of the member to be added to the containers. It's value is a list of members to be added. If lists are specified for both the \%\*L-member\*O option and as the argument, then each member name is added to each container. For example it is used to add a member to a remote procedure call (RPC) group, and is used to add an element to an RPC profile. This operation returns an empty string on success. .LI "\*Lcatalog\*O" Returns the names of all instances of an object. It usually takes no argument. In some cases, though, an argument specifying a scope, such as a cell name, is optional. For example, the \*Lprincipal catalog\*O command returns a list of all principals in the registry. Only implemented by those objects for which this is possible. By default, full names are returned. Some objects will support a \%\*L-simplename\*O option which will return names in a shorter form (either relative or not fully qualified). The order of the returned list depends on the object. .LI "\*Lcreate\*O" Creates a new instance of an object. Takes one argument which a list of names of instances to be created. This operation returns an empty string on success. Returns an error if the object already exists. For some objects this command takes a \%\*L-attribute\*O option or a set of attribute options to create attributes on the new object. .LI "\*Ldelete\*O" Destroys an instance of the object. Takes one argument which a list of names of instances to be deleted. This operation returns an empty string on success. If the object does not exist, an error is returned. .LI "\*Lhelp\*O" Returns help information on the object as described in the \*LHelp\*O section. Takes an argument which may be an operation supported by the object or the \%\*L-verbose\*O option to return more information. .LI "\*Llist\*O" Returns a list of the names of all the members of a container. This operation returns names of members, never any other (such as, attribute) information about the members. It is implemented on all objects that represent containers. The argument is a list of names of containers to return the children of. The order of the returned list is dependent on the object. If more than one container name is given as an argument, all the member names are returned in one list. .LI "\*Lmodify\*O" This operation is used to modify attributes, policies, counters, or any other information in an object. This fact means that all attributes, policies, counters, etc. in any one object must have unique names. It will not be available to all objects. The argument is a list of names of objects to modify. All objects are modified in the same way. .PP The specific modification is described by the use of one or more of the \*L-add\*O, \*L-remove\*O, or \%\*L-change\*O options. If more than one is used, then the whole \*Lmodify\*O operation is treated atomically in that either it all will work, or none of it will. The order of the options does not matter. Each option can be used only once per command invocation. If more than one attribute is to be added, the value of that option should be an attribute list. This operation returns an empty string on success. .VL .LI "\*L-add\*O" Used to add an attribute to an object or merely to add values to an existing attribute. The value of this option is an attribute list. .LI "\*L-remove\*O" Used to remove an entire attribute or merely some values from an attribute. The value of this option is an attribute list. .LI "\*L-change\*O" Used to change one attribute value to another. The value of this option is an attribute list. .LE .LI "\*Loperations\*O" Returns a list of the operations supported by the object. It takes no arguments, and always returns a Tcl list suitable for use in a \*Lforeach\*O statement. The order of the elements is alphabetical order with the exception that \*Lhelp\*O and \*Loperations\*O are listed last. To return the elements fully sorted, use the following command: .iS lsort [\*Vobject\*L operations] .iE .LI "\*Lremove\*O" Removes an object from a container. It is implemented for all objects that represent containers. The argument is a list of names of containers. The \*Lremove\*O operation requires one option, \*L-member\*O, which is used to specify the name of the member to be removed from the container. The value is a list of names of members of the containers. If the value of this option and the argument to the command are both lists, then each listed member is removed from each specified container. If the members do not exist an error is returned. This operation returns an empty string on success. .LI "\*Lrename\*O" This operation changes the name of a specified object. The argument is a single name of an object to be renamed, that is, it cannot be a list. Takes a required \%\*L-to\*O option with a value of the new name. The value may not be a list. This operation returns an empty string on success. .LI "\*Lshow\*O" Returns information about an object instance. Objects can have various types of information such as attributes, counters, policies, etc. The \*Lshow\*O operation is used to return any of this information. Options are passed to the command to specify what information is to be returned. Most of the options used for this purpose are in the plural form such as \*L-all\*O, \*L-attributes\*O, \*L-counters\*O, and \*L-members\*O. .PP Unlike the \*Llist\*O operation which returns information about the members of a container, the \*Lshow\*O operation only looks at the named object instance. If it is a container, it does \*Lnot\*O return information about the members, only the container itself. .PP This operation takes one argument which is a list of names of instances to be shown. .LI "\*Lsynchronize\*O" Tells the instance to synchronize with any replicas of itself. In CDS terminology this will perform a skulk on a directory, in DTS it will cause a server to synchronize. It is implemented for all objects that support replication. The argument is a list of instance names to synchronize. If more than one instance name is given then each instance synchronizes, there is no relationship such as synchronize with each other, as this doesn't make sense for many objects. This operation returns an empty string on success. .LE .SS "Miscellaneous Commands" .PP The DCE control program includes a set of commands you can use for performing miscellaneous operations. .VL .LI "\*Ldcecp_initInterp\*O" Initializes a base Tcl interpreter with all the \*Ldcecp\*O commands. .LI "\*Lecho\*O" Displays the supplied string as output. .LI "\*Lerrtext\*O" Takes a DCE status code as an argument and returns the text of the associated message as found in the message catalogs. The argument can be in decimal, octal (leading \*L0\*O), or hexadecimal (leading \*L0x\*O) notation. .LI "\*Llogin\*O" Creates a new login context, which persists until the end of the \*Ldcecp\*O session or until it is destroyed by \*Llogout\*O. \*Llogin\*O also sets the \*L_c\*O convenience variable to the name of the cell logged into and the \*L_u\*O convenience variable to the name of the principal that issued the \*Llogin\*O command. Convenience variables are discussed in a separate section of this reference page. Login contexts are stacked. Takes an account name as an argument. The password is prompted for and not echoed to the screen. Also takes the \%\*L-password\*O option to enter a password. .LI "\*Llogout\*O" Logs you out of the current login context as established with a previous \*Llogin\*O command. Only contexts created with \*Ldcecp\*O's \*Llogin\*O can be logged out of. Trying to log out of an inherited context results in an error. Leaving \*Ldcecp\*O will do a \*Llogout\*O for all contexts created in the session. .LI "\*Lquit\*O" Exits from \*Ldcecp\*O. A synonym of the Tcl built-in command \*Lexit\*O. .LI "\*Lresolve\*O" Takes a partial string binding and returns a fully bound string binding. Takes a required \%\*L-interface\*O option and an optional \*L-object\*O option with an interface identifier as an argument to provide enough information for the mapping to occur. .LI "\*Lshell\*O" Spawns a command shell for the user. The value of the \*LSHELL\*O environment variable is used to obtain the name of the shell to spawn. When the command shell terminates, control is returned to \*Ldcecp\*O. If called with arguments, they are passed to the shell and executed. Control is returned upon completion. Always returns an empty string, though an error exception is generated if the shell exits abnormally. .LE .SS "Command Processing" .PP The DCE control program supports the Tcl built-in commands as well as its own commands. If a command name is unknown to \*Ldcecp\*O, it is passed to the \*Lunknown\*O procedure and \*Ldcecp\*O evaluates it using the following algorithm: .ML .LI If the command is found in a \*Ldcecp\*O script file, \*Ldcecp\*O executes the command. .LI If the command exists as an executable UNIX program, \*Ldcecp\*O executes the command. Therefore, you can invoke any UNIX command from the \*Ldcecp\*O prompt (for example, \*Lls -l\*O). Because you don't leave \*Ldcecp\*O, you don't lose any context you have established. .LI If you have invoked the command at the top level of the \*Ldcecp\*O shell and the command requests C-shell-like history substitution (such as \*L!!\*O, \*L!\*Vnumber\*O or \*L^\*Vold\*L^\*Vnew\*O), \*Ldcecp\*O emulates the C shell's history substitution. .LI If you have invoked the command at the top level of the \*Ldcecp\*O shell and the command is a unique abbreviation for another command, \*Ldcecp\*O invokes the command. .LE .SS "Abbreviations" .PP The \*Ldcecp\*O command makes use of two mechanisms to allow all object names, operation names, and options to be abbreviated to the shortest unique string in interactive commands. .PP The first mechanism relies on the \*Lunknown\*O command whose behavior is described previously in the \*LCommand Processing\*O section of this reference page. .PP The second mechanism used for abbreviations is built into the individual \*Ldcecp\*O commands themselves. This allows the operation name to be abbreviated to the shortest unique operation supported for an object, and the options to be abbreviated to the shortest unique string representing an option supported by an object and operation. .PP For example, consider the following \*Ldirectory create\*O command: .iS directory create /.:/admin/printers/ascii -replica -clearinghouse /.:/SFO_CH .iE .PP In the abbreviated form, the same command can be entered as follows: .PP .iS dir cre /.:/admin/printers/ascii -r -c /.:/SFO_CH .iE .PP Although abbreviating commands is a good way to save keystrokes in typing interactive commands, abbreviations are not recommended for use in scripts. New procedures in scripts can cause abbreviations to become ambiguous. Furthermore, abbreviations aren't always portable. When scripts move to other machines, some definitions may be left behind so scripts won't work correctly. Always spell out complete names in scripts. .SS "Syntax" .PP The \*Ldcecp\*O commands have a default word order which is \*Lobject operation\*O. This order facilitates adding new objects because new objects can simply be added along with their operations. .PP You can configure \*Ldcecp\*O to accept commands ordered as \*Loperation object\*O by loading a script called \*Lverb-object.dcecp\*O. Users who have access to the \*Voperation object\*O order continue to have access to the \*Lobject operation\*O order. You can load the script for all users on a host by including the following line in the system's \*Linit.dcecp\*O file: .iS source verb-object.dcecp .iE .PP You can configure \*Loperation object\*O for individual users by including the line in that user's \*L.dcecprc\*O file. .SS "Attribute Lists" .PP Many of the commands need to specify attributes to operate upon. For example, the \*Lmodify\*O operation allows attributes to be changed and the \*Lcreate\*O operation often allows attributes to be created along with the object. In all cases, you can use an attribute list to specify the attributes and their values. This makes passing information from one command to another very easy. For example, an ACL copy operation could be written as follows: .oS # copy acl name1 to acl name2 # no error checking proc acl_copy {name1 name2} { acl replace $name2 -acl [acl show $name1] } .oE .SS "Attribute Options" .PP While attribute lists are useful for writing scripts, they are often not user friendly. For those objects that have a fixed list of attributes (for instance, \*Lprincipal\*O and \*Ldts\*O, but not \*Lobject\*O), wherever an attribute list is allowed, options for each attribute that are named the same as the attribute are allowed followed by their values. For example, the following are equivalent: .iS principal create melman -attribute {{quota 5} {uid 123}} principal create melman -quota 5 -uid 123 .iE .SS "Lists of Lists" .PP The DCE control program interpreter relies on list structures as a way to parse command input and return command output. For instance, the \%\*L-remove\*O option in the following example uses a list to group the attribute and value parts of the option argument together. The example is a command that removes some ACLs from an object called \*L/.:/foo\*O, as follows: .iS acl modify /.:/foo -remove {user melman} .iE .P The argument to the \%\*L-remove\*O option is an ACL entry. The ACL entry happens to be a list where the first element describes the ACL type, in this case \*Luser\*O, and the second is the key for which user, in this case \*Lmelman\*O. However, the \%\*L-remove\*O option may take a list of ACL entries, so the following is valid as well: .iS acl modify /.:/foo -remove {{user melman} {user salamone}} .iE .P Lists of one value that do not contain spaces, do not need braces. The string syntax of an ACL entry allows the type and key to be separated by a \*L:\*O (colon), so the following are valid: .iS acl modify /.:/foo -remove user:melman acl modify /.:/foo -remove {user:melman user:salamone} .iE .P If there is only one ACL entry given, that is, the \%\*L-remove\*O option's value has only one element (and that element does not contain spaces), then braces are not needed to delimit the list. The following are all valid, but all are examples with unnecessary braces: .iS acl modify /.:/foo -remove {{user melman}} acl modify /.:/foo -remove {{{user melman}}} acl modify /.:/foo -remove {user:melman} acl modify /.:/foo -remove {{user:melman} {user:salamone}} .iE .SS "Convenience Variables .PP All \*Ldcecp\*O commands will set several variables on execution. The variables will contain the name of the object operated on, the return value of the last command, the cell name of the last object operated on, and so on. You can substitute the value of these variables into the next command to save typing. .PP Convenience variables behave just like other variables in \*Ldcecp\*O. Thus you can trigger variable substitution by prepending a dollar sign (\*L$\*O) before the name of the variable. Alternatively, you can trigger substitution by using \*Lset\*O. The DCE control program ensures that the convenience variables are set only by the program; it prevents users from changing these variables. .PP The following variables are defined by \*Ldcecp\*O: .VL .LI "\*L_b\*O" Holds the name of the server bound to by the last command. This is actually a Tcl array where the indexes are used to identify the service. Currently there is only one defined index: \*Lsec\*O. Refer to the variable as \*L_b(sec)\*O. .PP The value specifies the name of a server in whatever manner the service finds useful. This could be the name of an RPC server entry in the namespace, or a string binding, or the name of a cell. This variable cannot be set by the user. .LI "\*L_c\*O" Holds the cell name of the current principal. The \*Llogin\*O command sets the cell name (\*L_c\*O) and principal name (\*L_u\*O) convenience variables at login (see the \*Llogin\*O command). This variable cannot be set by the user. .LI "\*L_conf\*O" This variable alters the behavior of most commands that operate on a CDS object. It indicates the confidence you have in the local CDS daemon to fulfill requests. The legal values are \*Llow\*O, \*Lmedium\*O, and \*Lhigh\*O. .LI "\*L_e\*O" Holds the last DCE error code encountered. This variable has meaning only if \*Ldcecp\*O is able to determine what the error code is. The value \*L-l\*O (negative one) is used when an actual error code is unavailable. This variable cannot be set by the user. ...\" .zA "1.1: CR13074" .LI "\*L_h\*O" Holds the hostname the current user is operating on. This variable cannot be set by the user. ...\" .zZ "1.1: CR13074" ...\" .zA "1.2.1: add -local" .LI "\*L_local\*O" Holds a flag that indicates the mode in which the \*Ldcecp\*O session is operating. This variable is set to \*Ltrue\*O if the \*Ldcecp\*O session was started with the \%\*L-local\*O option. ...\" .zZ "1.2.1: add -local" .LI "\*L_n\*O" Holds a list of the names entered in the last command. These names are the names that the command operated on, typically entered as the third argument. Examples follow: .oS dcecp> \*Ldir list /.: -simplename\*C hosts subsys absolut_ch cell-profile fs lan-profile sec sec-v1 dcecp> dcecp> \*Lecho $_n\*C /.: dcecp> dcecp> \*Ldir create {/.:/x /.:/y}\*C dcecp> dcecp> \*Lecho $_n\*C /.:/x /.:/y dcecp> .oE .LI "\*L_o\*O" Holds the object used in the last operation. For example, if the last command was \*Ldir show /.:\*O, then \*L_o\*O is \*Ldirectory\*O. This variable cannot be set by the user. ...\" .zA "1.1: CR13058" .LI "\*L_p\*O" Holds the parent of \*L_n\*O. If \*L_n\*O is a list, then this is a list of the same length, where each element is the parent of the corresponding element in \*L_n\*O. If \*L_n\*O has no parent, then the value of \*L_p\*O is the empty string. This variable cannot be set by the user. Examples follow: .oS dcecp> \*Ldir create {/.:/gumby /.:/pokey}\*C dcecp> dcecp> \*Lecho $_p\*C /.: /.: dcecp> .oE ...\" .zZ "1.1: CR13058" .LI "\*L_r\*O" Holds the return value of the last executed command. This variable cannot be set by the user. .LI "\*L_s\*O" Holds the name of the server bound to for the last command. This is actually a Tcl array where the indexes are used to identify the service. The currently defined indexes are \*Lsec\*O, \*Lcds\*O, \*Ldts\*O, and \*Laud\*O. .PP The value specifies the name of a server in whatever manner the service finds useful. This could be the name of an RPC server entry in the namespace, or a string binding, or the name of a cell. Users can set this variable by issuing the \*Lset\*O command. This lets users select which server is used. .PP The values of this variable (array) are treated differently by each service. For example, the security service uses this variable to select the registry to bind to for the next command, and it is used as a default for the next registry operation. If bound to a read-only replica and an update is requested, \*Ldcecp\*O will try to bind to the master registry to perform the change. CDS attempts to communicate only with the CDS server named by the variable. If the named CDS server cannot satisfy a request for any reason, the request fails. The auditing service and DTS uses its variable in a similar manner to the CDS server. To contact an audit daemon or DTS server on another host, set this variable to identify that server. .PP For information about an object's use of this variable, see the object's reference page or use the object's \*Lhelp -verbose\*O operation. .LI "\*L_u\*O" Holds the current principal name. The \*Llogin\*O command sets the cell name (\*L_c\*O) and principal name (\*L_u\*O) convenience variables at login (see the \*Llogin\*O command). This variable cannot be set by the user. .LE .PP .SS "Error Handling" .PP All \*Ldcecp\*O operations return either a list of some information or an empty string on success. If an error occurs, \*Ldcecp\*O returns an error message. The DCE control program also provides a \*Lcatch\*O command to help scripts catch errors and invoke error handlers. .PP The DCE control program provides two global variables that store error information returned from commands. The \*LerrorInfo\*O variable contains the stack-trace of the error messages. When errors occur \*Ldcecp\*O commands return one line error messages by default. If the variable \*Ldcecp_verbose_errors\*O is set to \*L1\*O, then a stack trace as it would appear in \*LerrorInfo\*O is output as well. .PP When a \*Ldcecp\*O command argument is a list of objects, the command operates on multiple objects. These operations are usually performed iteratively. If an error occurs, the command aborts at the time of error, producing an exception. Some operations will have finished and others will not have. This operations are always performed in the order listed, and the error message should make it clear on which object the command failed. .SS "Help" .PP The DCE control program provides several kinds of help. All returned help strings are obtained from appropriate message catalogs. .PP To see which operations an object supports, enter an \*Vobject\*L operations\*O command. An example follows: .oS dcecp> \*Lprincipal operations\*C catalog create delete modify rename show help operations dcecp> .oE .PP This provides simple help similar to usage messages found on many systems. Users unsure of an operation name or if an operation is supported by an object can use this command to find the answer. The output is a \*Ldcecp\*O list that could be used by other \*Ldcecp\*O commands. .PP To see other information about an object, use an object's \*Lhelp\*O operation. All \*Ldcecp\*O objects have a \*Lhelp\*O operation that offers three kinds of information. .ML .LI View brief information about an object's operations by using \*Lhelp\*O without arguments or options. Operations are listed in alphabetical order, with the \*Loperations\*O and \*Lhelp\*O operations listed last because all objects support these operation. An example is as follows: .oS dcecp> \*Lprincipal help\*C catalog Returns all the names of principals in the registry. create Creates a DCE principal. delete Deletes a principal from the registry. modify Changes the information about a principal. rename Renames the specified principal. show Returns the attributes of a principal. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .LI View brief information about options supported by an operation by using \*Lhelp\*O with one argument\(emthe name of the operation. This operation returns attribute options in alphabetic order. If no options are supported, an empty string is returned. An example follows: .oS dcecp> \*Lprincipal help create\*C -alias Add principal named as an alias of specified uid. -attribute Attribute list to be assigned to the new principal. -fullname Fullname of the new principal. -quota Quota of the new principal. -uid User Identifier of the new principal. -uuid Orphaned UUID to be adopted by the specified principal. dcecp>\*O .oE .PP .LI View a short description of a \*Ldcecp\*O object by using the \*Lhelp\*O operation with the \%\*L-verbose\*O option. This operation returns text explaining what the object represents and how to use it. An example follows: .oS dcecp> \*Lprincipal help -verbose\*C This object allows manipulation of principal information stored in the DCE registry. The argument is a list of either relative or fully-qualified principal names. Specify fixed attributes using attribute options or an attribute list. Specify any extended attributes using an attribute list. Principal operations connect to a registry that can service the request. Specify a particular registry by setting the _s(sec) convenience variable to be a cell-relative or global replica name, or the binding of the host where the replica exists. The completed operation sets the _b(sec) convenience variable to the name of the registry contacted. dcecp> .oE .LE .PP ...\" .zA "Def,13377,R1.2.2,add util lib" .SS "Utility Library" .PP The file \*Lopt/dcelocal/dcecp/utility.dcp\*O contains Tcl functions useful for DCE administration. The functions, which can vary from release to release, are fully commented to document their use. ...\" .zZ "Def,13377,R1.2.2,add util lib" .PP .SS "Reference Pages" To display a reference page for a \*Ldcecp\*O administration object, use the \*Lman\*O command and preface the object name with \*Ldcecp_\*O. For example to display the \*Lregistry\*O reference page, enter: .iS man dcecp_registry .iE Users with [POSIX.2] systems can view \*Ldcecp\*O administration object reference pages without exiting \*Ldcecp\*O. ...\" HP SPECIAL ...\" PUT FOLLOWING IN FOR OSF VERSION AND TAKE FROM "REF PAGES" TO HERE OUT ...\" Users can use the \*Lman\*O command on [POSIX.2] systems to view the ...\" reference page for any \*Ldcecp\*O object without exiting \*Ldcecp\*O. ...\" This capability helps users avoid losing any context that has been ...\" established in the current \*Ldcecp\*O session. ...\" For example, the user can get detailed help on the ...\" \*Lprincipal\*O command by entering the following: ...\" .oS ...\" dcecp> \*Lman principal ...\" .oE ...\" .SS "Command-Line Editing" .PP You can edit a line before it is sent to \*Ldcecp\*O by typing certain control characters and escape sequences. To enter a control character, \*Ehold down\*O \*L\*O while pressing the appropriate character key. (Control characters are indicated in DCE documentation by the notation \*L\*O, where \*Vx\*O is the second key.) To enter an escape sequence, press \*L\*O \*Efollowed by\*O one or more character keys. (Escape sequences are indicated in DCE documentation by the notation \*L\*O, where \*Vx\*O is the second key.) Escape sequences are case-sensitive; control characters are not. .PP You can enter an editing command anywhere on a line. In addition, you can enter \*L\*O anywhere on the line. .PP You can specify a number [\*Vn\*O] as a repeat count. To enter a repeat count, press \*L\*O, a number, and the command you want to execute. .PP For example, \*L\*O deletes the next four characters on a line. .PP Use the following control characters and escape sequences for line editing: .PP .VL 1.5in .LI "\*LControl Sequence\*O" \*LAction Performed\*O .LI "\*L\*O" Move to the beginning of the line .LI "\*L\*O" Move left (backward) [\*Vn\*O] .LI "\*L\*O" Delete the next character [\*Vn\*O] .LI "\*L\*O" Move to the end of the line .LI "\*L\*O" Move right (forward) [\*Vn\*O] .LI "\*L\*O" Ring the bell .LI "\*L\*O" Delete the character before the cursor [\*Vn\*O] .LI "\*L\*O" Complete the filename (\*L\*O) .LI "\*L\*O" Done with the line (\*L\*O) .LI "\*L\*O" Kill to the end of the line (or column [\*Vn\*O] .LI "\*L\*O" Redisplay the line .LI "\*L\*O" Done with the line (alternate \*L\*O) .LI "\*L\*O" Get the next line from history [\*Vn\*O] .LI "\*L\*O" Get the previous line from history [\*Vn\*O] .LI "\*L\*O" Search backward (or forward if [\*Vn\*O]) through history for the text; start the line if the text begins with an up arrow .LI "\*L\*O" Transpose the characters .LI "\*L\*O" Insert the next character even if it is an edit command .LI "\*L\*O" Wipe to the mark .LI "\*L\*O" Exchange the current location and mark .LI "\*L\*O" Yank back the last killed test .LI "\*L\*O" Start an escape sequence (\*L\*O) .LI "\*L\*O" Move forward to the next character \*Vc\*O .LI "\*L\*O" Delete the character before the cursor [\*Vn\*O] .PP ...\" Use the escape sequences shown in the following table for line editing. .PP ...\" .TB "Escape Sequences for Line Editing" ...\" .cS ...\" .TS ...\" center,tab(@); ...\" lB lB ...\" l l. ...\" Escape Sequence@Action Performed ...\" ...\" _ ...\" .tH ...\" .cE ...\" .ne 3i ...\" .TS ...\" tab(@); ...\" lw(.25i) lw(5.75i). .LI "\*LEscape Sequence\*O" \*LAction Performed\*O .LI "\*L\*O" Delete the previous word (\*L\*O) [\*Vn\*O] .LI "\*L\*O" Delete the previous word (\*L\*O) [\*Vn\*O] .LI "\*L\*O" Set the mark (\*L\*O); refer to the \*L\*O and \*L\*O control characters in the previous table .LI "\*L\*O" Get the last (or [\*Vn\*O]th) word from the previous line .LI "\*L\*O" Show the possible completions .LI "\*L\*O" Move to the start of history .LI "\*L>\*O" Move to the end of history .LI "\*L\*O" Move backward one word [\*Vn\*O] .LI "\*L\*O" Delete the word under the cursor [\*Vn\*O] .LI "\*L\*O" Move forward one word [\*Vn\*O] .LI "\*L\*O" Make the word lowercase [\*Vn\*O] .LI "\*L\*O" Make the word uppercase [\*Vn\*O] .LI "\*L\*O" Yank back the last killed text .LI "\*L\*O" Make area up to mark yankable .LI "\*L\*O" Set repeat count to the number \*Vnn\*O .LE ...\" .cS ...\" &&&&&&&&&&&&&&&&&&&&&&&&&& ...\" taking out tbl formatting. why anyone ever used this ...\" in the first place is beyond me, especially since they didn't use any ...\" "real" table formatting features!@! ...\" .TS ...\" tab(@); ...\" lw(.25i) lw(5.75i). ...\" \*LControl Character\*O@T{ ...\" \*LAction Performed\*O ...\" T} ...\" \*L\*O@T{ ...\" Move to the beginning of the line ...\" T} ...\" _ ...\" \*L\*O@T{ ...\" Move left (backward) [\*Vn\*O] ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Delete the next character [\*Vn\*O] ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Move to the end of the line ...\" T} ...\" _ ...\" \*L\*O@T{ ...\" Move right (forward) [\*Vn\*O] ...\" T} ...\" _ ...\" \*L\*O@T{ ...\" Ring the bell ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Delete the character before the cursor [\*Vn\*O] ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Complete the filename (\*L\*O) ...\" T} ...\" ...\" _ ...\" ...\" \*L\*O@T{ ...\" Done with the line (\*L\*O) ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Kill to the end of the line (or column [\*Vn\*O] ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Redisplay the line ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Done with the line (alternate \*L\*O) ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Get the next line from history [\*Vn\*O] ...\" T} ...\" _ ...\" \*L\*O@T{ ...\" Get the previous line from history [\*Vn\*O] ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Search backward (or forward if [\*Vn\*O]) through history for the text; ...\" start the line if the text begins with an up arrow ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Transpose the characters ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Insert the next character even if it is an edit command ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Wipe to the mark ...\" T} ...\" _ ...\" \*L\*O@T{ ...\" Exchange the current location and mark ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Yank back the last killed test ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Start an escape sequence (\*L\*O) ...\" T} ...\" _ ...\" \*L\*O@T{ ...\" Move forward to the next character \*Vc\*O ...\" T} ...\" _ ...\" \*L\*O@T{ ...\" Delete the character before the cursor [\*Vn\*O] ...\" T} ...\" .TE ...\" .PP ...\" ...\" Use the escape sequences shown in the following table for line editing. ...\" .PP ...\" ...\" .TB "Escape Sequences for Line Editing" ...\" ...\" .cS ...\" ...\" .TS ...\" center,tab(@); ...\" ...\" ...\" lB lB ...\" ...\" l l. ...\" ...\" Escape Sequence@Action Performed ...\" ...\" ...\" _ ...\" ...\" .tH ...\" ...\" .cE ...\" ...\" .ne 3i ...\" .TS ...\" tab(@); ...\" lw(.25i) lw(5.75i). ...\" \*LEscape Sequence\*O@T{ ...\" \*LAction Performed\*O ...\" T} ...\" \*L\*O@T{ ...\" Delete the previous word (\*L\*O) [\*Vn\*O] ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Delete the previous word (\*L\*O) [\*Vn\*O] ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Set the mark (\*L\*O); refer to the \*L\*O and ...\" \*L\*O control ...\" characters in the previous table ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Get the last (or [\*Vn\*O]th) word from the previous line ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Show the possible completions ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Move to the start of history ...\" T} ...\" _ ...\" \*L>\*O@T{ ...\" Move to the end of history ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Move backward one word [\*Vn\*O] ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Delete the word under the cursor [\*Vn\*O] ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Move forward one word [\*Vn\*O] ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Make the word lowercase [\*Vn\*O] ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Make the word uppercase [\*Vn\*O] ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Yank back the last killed text ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Make area up to mark yankable ...\" T} ...\" ...\" _ ...\" \*L\*O@T{ ...\" Set repeat count to the number \*Vnn\*O ...\" T} ...\" .TE ...\" &&&&&&&&&&&&&&& ...\" .cE .PP The DCE control program also supports filename completion. For example, suppose the root directory has the following files in it: \*Lvmunix\*O, \*Lcore\*O, \*Lvmunix.old\*O. .PP If you type \*Lrm /v\*O and then press \*L\*O. \*Ldcecp\*O will finish off as much of the name as possible by adding \*Lmunix\*O. If the name is not unique, the terminal alarm (beep) will sound. If you enter \*L\*O, \*Ldcecp\*O will display the two possible complete filenames: \*Lvmunix\*O and \*Lvmunix.old\*O. If you respond by entering a \*L\&.\*O (period) and by entering \*L\*O, \*Ldcecp\*O completes the filename for you. .SS "Command History and Command-Line Recall" .PP The DCE control program includes a history facility that stores previously entered commands. View the stored commands using the \*Lhistory\*O command. ...\" .cS ...\" IS THIS EXAMPLE NECESSARY? ...\" .oS ...\" \*Cdcecp> \*Lhistory\*C ...\" dcecp>\*O ...\" .oE ...\" .cE .PP By default, the history facility stores the 20 most recent commands but you can use a \*Lhistory keep\*O command to change this as in the following: .oS dcecp> \*Lhistory keep 50 \*C dcecp> .oE .PP Each stored command is numbered so you can recall it by using a \*L!\*O (exclamation point) followed by the event number, as follows: .oS dcecp> \*L!7\*C \*V[execution of event 7]\*C dcecp> .oE .PP Recall a specific command using an \*L!\*O followed by the first unique characters of a previously entered command, as follows: .oS dcecp> \*L!dir\*C \*V[execution of last event beginning with \*Ldir] \*C dcecp> .oE .PP You can also recall and revise the most recent command using the \*L^\*Vold\*L^\*Vnew\*O syntax familiar to UNIX users, as follows: .oS dcecp> \*Ldirectory vreate /.:/admin/printers\*C [error message] \*C dcecp> dcecp> \*L^vreate^create\*C \*V[command output] \*C dcecp> .oE .SH "EXAMPLES" .PP ...\" .cS ...\" Examples ...\" invocations, abbrevs (maybe), foreach loop, some ...\" simple object commands ...\" .cE .SS "Invocations" .PP The following examples show some ways to issue \*Ldcecp\*O commands: .AL .LI Invoke \*Ldcecp\*O for interactive use: .oS % \*Ldcecp \*Cdcecp> .oE .LI Invoke \*Ldcecp\*O for a single command: .oS % \*Ldcecp -c clock show\*C 1994-04-21-19:12:42.203+00:00I----- % .oE .LI Invoke \*Ldcecp\*O and run a script: .oS % \*Ldcecp get_users.Tcl\*C % .oE .LE .SS "Simple Object Commands" .oS dcecp> \*Lacl show -ic /.:\*C {unauthenticated r--t---} {group subsys/dce/cds-admin rwdtcia} {group subsys/dce/cds-server rwdtcia} {any_other r--t---} dcecp> % \*Ldcecp -c directory show /.:/subsys\*C {RPC_ClassVersion {01 00}} {CDS_CTS 1995-10-11-14:06:47.884826100/08-00-09-85-b5-a6} {CDS_UTS 1995-10-23-03:06:43.209673100/08-00-09-85-b5-a6} {CDS_ObjectUUID 0c27c0ac-03d6-11cf-ad88-08000985b5a6} {CDS_Replicas {{CH_UUID 03ccab5c-03d6-11cf-ad88-08000985b5a6} {CH_Name /.../gumby1/blech_ch} {Replica_Type Master} {Tower {ncadg_ip_udp 15.22.50.213}} {Tower {ncacn_ip_tcp 15.22.50.213}}}} {CDS_AllUpTo 1995-10-23-13:06:43.560848100/08-00-09-85-b5-a6} {CDS_Convergence medium} {CDS_ParentPointer {{Parent_UUID 044a2a14-03d6-11cf-ad88-08000985b5a6} {Timeout {expiration 1994-04-19-16:39:58.049} {extension +1-00:00:00.000I0.000}} {myname /.../brain_cell.osf.org/subsys}} {CDS_DirectoryVersion 3.0} {CDS_ReplicaState on} {CDS_ReplicaType Master} {CDS_LastSkulk 1995-10-23-13:06:43.560848100/08-00-09-85-b5-a6} {CDS_LastUpdate 1995-10-23-03:06:43.209673100/08-00-09-85-b5-a6} {CDS_Epoch 0c3512fc-03d6-11cf-ad88-08000985b5a6} {CDS_ReplicaVersion 3.0} % .oE .LE .SS "The foreach Loop" .oS dcecp> \*Lforeach i [group list temps] { account modify $i temps research -expdate 6/30/95} .oE ...\" THIS EXAMPLE NEEDS TO BE CHECKED WHEN TIME ALLOWS ...\" .SS "Abbreviations" ...\" .oS ...\" dcecp> \*Lclearin sh /.../brain_cell.osf.org/pmin17_ch\*O ...\" {CDS_CTS 1994-04-14-19:25:54.051+00:00I0.000/00-00-c0-8a-df-56} ...\" {CDS_UTS 1994-04-14-19:31:46.020+00:00I0.000/00-00-c0-8a-df-56} ...\" {CDS_ObjectUUID 000ad28c-98c2-1dad-9263-0000c08adf56} ...\" {CDS_AllUpTo 1994-04-18-19:40:15.501+00:00I0.000/00-00-c0-8a-df-56} ...\" {CDS_DirectoryVersion 3.0} ...\" {CDS_CHName /.../brain_cell.osf.org/pmin17_ch} ...\" {CDS_CHLastAddress ...\" {Tower ncacn_ip_tcp:130.105.1.227[]}} ...\" {CDS_CHLastAddress ...\" {Tower ncadg_ip_udp:130.105.1.227[]}} ...\" {CDS_CHState on} ...\" {CDS_CHDirectories ...\" {dir_uuid 00972ee5-98c4-1dad-9263-0000c08adf56} ...\" {directory /.../brain_cell.osf.org}} ...\" {CDS_CHDirectories ...\" {dir_uuid 00524676-98de-1dad-9263-0000c08adf56} ...\" {directory /.../brain_cell.osf.org/subsys}} ...\" {CDS_CHDirectories ...\" {dir_uuid 0013b6b8-98e0-1dad-9263-0000c08adf56} ...\" {directory /.../brain_cell.osf.org/subsys/HP}} ...\" {CDS_CHDirectories ...\" {dir_uuid 00216e3e-98e1-1dad-9263-0000c08adf56} ...\" {directory /.../brain_cell.osf.org/subsys/HP/sample-apps}} ...\" {CDS_CHDirectories ...\" {dir_uuid 002a91da-98e2-1dad-9263-0000c08adf56} ...\" {directory /.../brain_cell.osf.org/subsys/dce}} ...\" {CDS_CHDirectories ...\" {dir_uuid 008f45f8-98e3-1dad-9263-0000c08adf56} ...\" {directory /.../brain_cell.osf.org/subsys/dce/sec}} ...\" {CDS_CHDirectories ...\" {dir_uuid 008dbc60-98e4-1dad-9263-0000c08adf56} ...\" {directory /.../brain_cell.osf.org/subsys/dce/dfs}} ...\" {CDS_CHDirectories ...\" {dir_uuid 00986692-98e5-1dad-9263-0000c08adf56} ...\" {directory /.../brain_cell.osf.org/hosts}} ...\" {CDS_CHDirectories ...\" {dir_uuid 00152a98-98e7-1dad-9263-0000c08adf56} ...\" {directory /.../brain_cell.osf.org/hosts/pmin17}} ...\" {CDS_ReplicaVersion 3.0} ...\" {CDS_NSCellname /.../brain_cell.osf.org} ...\" dcecp> ...\" .oE ...\" .cS ...\" .SH "RETURN VALUES" ...\" .PP ...\" All \*Ldcecp\*O commands return one of the following: ...\" .ML ...\" .LI ...\" A list of information requested by the user (such as the results of a ...\" search operation) ...\" .LI ...\" \*LNULL\*O (indicating successful completion of an operation) ...\" .LI ...\" An error message string ...\" .LE ...\" .PP ...\" \*Ldcecp\*O uses the Tcl native error handling facility to log ...\" additional error information. This additional information is stored ...\" in the two variables, \*EerrorInfo\*O and \*EerrorCode\*O. The ...\" \*EerrorInfo\*O variable contains a stack trace of each of the nested ...\" calls to the Tcl interpreter when the error occured. The ...\" \*EerrorCode\*O variable is a Tcl list containing two elements, ...\" \*LDCECP\*O (identifying the \*Ldcecp\*O program) and the numeric ...\" value of the error code. You can Use the Tcl \*Lcatch\*O command to ...\" determine the successful completion or failure of the various ...\" \*Ldcecp\*O commands. Refer to \*Ldcecp.h\*O header file for a ...\" description of the error codes. ...\" .PP ...\" To view the results in a structured format (for example, after a ...\" successful search operation), use the \%\*L-pretty\*O option. If you ...\" specify this option, the output of a command result is output in pages ...\" of 23 lines in length. You can scan through the output using special ...\" \*Ldcecp\*O scrolling commands: ...\" .VL ...\" .LI "\*Ln\*O" ...\" View the nth page ...\" .LI "\*L-n\*O" ...\" Skip n pages backward ...\" .LI "\*L+n\*O" ...\" Skip n pages forward ...\" .LI "\*L$\*O" ...\" View the last page ...\" .LI "\*Lq\*O" ...\" Quit ...\" .LI "\*L\*O" ...\" Advance to the next page ...\" .LI "\*L\*O" ...\" Advance one line ...\" .LE ...\" .cE .iX "-]" "DCE Control Program commands" "dcecp" ...\" .ig ++ ...\" NOTE: WHAT FOLLOWS IS THE auditcp.1m REFPAGE RICO CRUZ WROTE AND PUT ...\" INTO THE /man1m DIRECTORY. IT HAS BEEN DEFUNCTED FROM THERE, AND ...\" AFTER BETA WILL BE MERGED WITH THIS /man1m REFPAGE. ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" ...\" ...\" .TH auditcp "1m" "" "" "" ...\" ...\" .zA "enh,10234,R1.1,new reference page." ...\" .SH "NAME" ...\" \*Lauditcp\*O - Runs the Audit Control Program. ...\" .SH "SYNOPSIS" ...\" .sS ...\" \*Lauditcp\*O \*Vauditcp-subcommand\*O ...\" .sE ...\" .iX "\*Lauditcp\*O commands" ...\" .SH "ARGUMENTS" ...\" .VL 1.5i ...\" .LI "\*Vauditcp-subcommand\*O" ...\" Specifies one of the following Audit Control Program subcommands: ...\" .VL 1.3i ...\" .LI "\*Laud modify\*O" ...\" Changes the attributes of the Audit daemon. ...\" .LI "\*Laud disable\*O" ...\" Disables the audit record logging service of the Audit daemon. ...\" .LI "\*Laud enable\*O" ...\" Enables the audit record logging service of the Audit daemon. ...\" .LI "\*Laud show\*O" ...\" Shows the attributes of the Audit daemon. ...\" .LI "\*Laud stop\*O" ...\" Stops the Audit daemon. ...\" .LI "\*Laud rewind\*O" ...\" Rewinds the audit trail file. ...\" .LI "\*Laudfilter add\*O" ...\" Adds a filter directive. ...\" .LI "\*Laudfilter delete\*O" ...\" Deletes a filter. ...\" .LI "\*Laudfilter catalog\*O" ...\" Lists the names of all filters maintained by the Audit daemon. ...\" .LI "\*Laudfilter remove\*O" ...\" Removes a filter directive. ...\" .LI "\*Laudfilter show\*O" ...\" Shows the directives in a specified filter. ...\" .LI "\*Laudevents catalog\*O" ...\" Lists the names of all event classes. ...\" .LI "\*Laudevents show\*O" ...\" Lists the class number and the events of an event class. ...\" .LI "\*Laudtrail show\*O" ...\" Shows the contents of an audit trail file. ...\" .LI "\*Lhelp\*O" ...\" Displays help information on the Audit Control Program subcommands. ...\" .LI "\*Lexit\*O" ...\" Exits the Audit Control Program. ...\" .LI "\*Lquit\*O" ...\" Exits the Audit Control Program. ...\" .LE ...\" .LE ...\" .SH "DESCRIPTION" ...\" .PP ...\" The Audit Control Program ...\" provides a set of commands for managing the ...\" DCE Audit Service and examining audit trail files. ...\" .P ...\" You can only manage the Audit Service on the same host where you ...\" run the \*Lauditcp\*O command. ...\" .PP ...\" You can use Audit Control Program ...\" subcommands from within the control program or from ...\" the system prompt (represented here as a $). ...\" .ML ...\" .LI ...\" From the control program: ...\" .P ...\" To enter the Audit Control Program commands from the control program, ...\" use the \*Lauditcp\*O command without an argument. ...\" The Audit Control Program prompt is displayed, for example: ...\" .oS ...\" $ \*Lauditcp\*O ...\" auditcp> ...\" .oE ...\" You can then enter any control program subcommand, for example: ...\" .oS ...\" auditcp> \*Laud enable\*O ...\" .oE ...\" .LI ...\" From the system prompt: ...\" .P ...\" Enter the \*Lauditcp\*O command with ...\" an Audit Control Program subcommand on the system command line. ...\" For example, you can enter the ...\" \*Laudfilter show\*O command as follows: ...\" .oS ...\" $ \*Lauditcp audfilter show\*O ...\" .oE ...\" .LE ...\" To exit the control program and return to the system prompt, use the ...\" \*Lexit\*O or \*Lquit\*O subcommand. ...\" .SH "EXAMPLES" ...\" The following command at the system prompt converts the ...\" binary audit trail file, ...\" \*Lmy_trail\*O to the human-readable text file, \*Ltrail_text\*O. ...\" .oS ...\" $ \*Lauditcp audtrail show\*O ...\" Enter trail file name: \*Lcentral_trail\*O ...\" Enter text file name (enter for screen display): \*Ltrail_text\*O ...\" .oE ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH account 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Laccount\*O" .iX "account" "administering" .SH NAME .PP \*Laccount\*O - A \*Ldcecp\*O object that manages an account in the DCE Security Service .SH "SYNOPSIS" .sS \*Laccount catalog \*O[\*Vcell_name\*O] [\*L-simplename\*O] .PP \*Laccount create \*Vaccount_name_list .nL \*L-mypwd \*Vpassword .nL \*L-password \*Vpassword\*L .nL \*L-group \*Vgroup_name .nL \*L-organization \*Vorganization_name\*O .nL [\*L-attribute \*Vattribute_list\*O | .nL \*L-\*Vattribute value\*O] .PP \*Laccount delete \*Vaccount_name_list .PP ...\" .zA "1.1, CR13075" \*Laccount generate \*Vaccount_name\*O ...\" .zZ "1.1, CR13075" .PP \*Laccount help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Laccount modify \*Vaccount_name_list .nL \*O[\*L-mypwd \*Vpassword\*O] .nL {\*L-change \*Vattribute_list\*O | .nL \*L-\*Vattribute value\*O} .PP \*Laccount operations\*O .PP \*Laccount show \*Vaccount_name_list\*O [\*L-policies\*O | \*L-all\*O] .sE .SH "ARGUMENTS" ...\" .zA "def,13230,R1.2.1,HP edits" .VL .LI "\*Vaccount_name\*O and \*Vaccount_name_list\*O" The name of an account to act on. Note that accounts are identified by principal names, so when you create an account you supply a principal name for the account name. \*Vaccount_name\*O indicates the name of a single account and \*Vaccount_name_list\*O indicates a list of one or more names of accounts. .PP. Supply the names as follows: .ML .LI Fully qualified account names in the form: \*L/.../\*Vcell_name\*L/\*Vaccount_name\*O or \*L/.:/\*Vaccount_name\*O .LI Cell-relative account names in the form: \*Vaccount_name\*O. These names refer to an account in the cell identified in the \*L_s(sec)\*O convenience variable, or if the \*L_s(sec)\*O convenience variable is not set, in the local host's default cell. .LE .PP Do not mix fully-qualified names and cell-relative names in a list. In addition, do not use the names of registry database objects that contain account information; in other words, do not use account names that begin with \*L/.:/sec/account/\*O. .LI "\*Vcell_name\*O" The name of a specific cell_name (or \*L/.:\*O for the local cell) in which to catalog accounts. .LI "\*Voperation\*O" The name of the \*Laccount\*O operation for which to display help information. .LE ...\" .zZ "def,13230,R1.2.1,HP edits" .SH "DESCRIPTION" .PP The \*Laccount\*O object represents registry accounts. Although an account is associated with one principal, one group, and one organization, it is named by just the primary principal name. Alias names are differentiated for principals, so one principal can have multiple accounts under different alias names. .P ...\" .zA "dec,13230,HP edits" When this command executes, it attempts to bind to the registry server identified in the \*L_s(sec)\*O variable. If that server cannot process the request or if the \*L_s(sec)\*O variable is not set, the command binds to either an available slave server or the master registry server, depending on the operation. Upon completion the command sets the \*L_b(sec)\*O convenience variable to the name of the registry server it bound to. ...\" .zZ "dec,13230,HP edits" .SH "ATTRIBUTES" ...\" .zA "dec,13230,HP edits" .PP The \*Laccount\*O object supports the following two kinds of attributes: .ML .LI Account attributes may or may not have default values. They assume a default value or a value set by administrators. .LI Policy attributes regulate such things as account and password lifetimes for all accounts associated with a particular registry. Policy attributes have registry-wide default values. They always assume the most restrictive value whether it is the registry-wide default value or a value set for an individual account. .LE ...\" .zZ "dec,13230,HP edits" .PP .SS "Account Attributes" ...\""The account attributes are as follows: .VL .LI "\*Lacctvalid \*O{\*Lyes \*O| \*Lno\*O}" A flag set to determine account validity. Possible values are either \*Lyes\*O or \*Lno\*O. An account with an \*Lacctvalid\*O attribute set to \*Lno\*O is invalid and cannot be logged into. The default is \*Lyes\*O. .LI "\*Lclient \*O{\*Lyes \*L| no\*O}" A flag set to indicate whether or not the account is for a principal that can act as a client. Possible values are either \*Lyes\*O or \*Lno\*O. If you set this flag to \*Lyes\*O, the principal is able to log into the account and acquire tickets for authentication. The default is \*Lyes\*O. ...\" .zA "dec,13230,HP edits" .LI "\*Lcreated \*Vcreators_name ISO_timestamp\*O" A list of two items. The first is the principal name of the creator of the account, the second is an ISO timestamp showing the time of creation. This attribute is set by the system at the time of account creation and can not be specified or modified. .LI "\*Ldescription \*V\"text string\"\*O" A text string (limited to the Portable Character Set) typically used to describe the use of the account. The default is the empty string (""). .LI "\*Ldupkey \*O{\*Lyes \*O| \*Lno\*O}" A flag set to determine if tickets issued to the account's principal can have duplicate keys. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lno\*O. .PP In DCE this attribute is currently only advisory. However, Kerberos clients and servers will make use of it when they interact with a DCE Security server. .LI "\*Lexpdate \*VISO_timestamp\*O" The date on which the account expires. To renew the account, change the date in this field. To specify the time, use an ISO compliant time format such as \*VCCYY-MM-DD-hh:mm:ss\*O or the string \*Lnone\*O. The default is \*Lnone\*O. .LI "\*Lforwardabletkt \*O{\*Lyes \*O| \*Lno\*O}" A flag set to determine whether a new ticket-granting ticket with a network address that differs from the present ticket-granting ticket network address can be issued to the account's principal. The \*Lproxiabletkt\*O attribute performs the same function for service tickets. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lyes\*O. .PP In DCE this attribute is currently only advisory. However, Kerberos clients and servers will make use of it when they interact with a DCE Security server. ...\" .zA "1.1, CR13065" .LI "\*Lgoodsince \*VISO_timestamp\*O" The date and time the account was last known to be in an uncompromised state. Any tickets granted before this date are invalid. The value is an ISO timestamp. When the account is initially created, the \*Lgoodsince\*O date is set to the current date. Control over this date is especially useful if you know that an account's password was compromised. Changing the password can prevent the unauthorized principal from accessing the system again using that password, but it does not prevent the principal from accessing the system components for which tickets were obtained fraudulently before the password was changed. To eliminate the principal's access to the system, the tickets must be canceled. .PP The default is the time the account was created. ...\" ..zZ "1.1, CR13065" .LI "\*Lgroup \*Vgroup_name\*O" The name of the group associated with the account. The value is a single group name of an existing group in the registry. This attribute must be specified for the \*Laccount create\*O command; it does not have a default value. .PP If a group is deleted from the registry, all accounts associated with the group are also deleted. .LI "\*Lhome \*Vdirectory_name\*O" The file system directory in which the principal is placed at login. The default is \*L/\*O. .LI "\*Llastchange \*Vprincipal_name ISO_timestamp\*O" A list of two items. The first is the principal name of the last modifier of the account; the second is an ISO timestamp showing the time of the last modification. This attribute is set by the system whenever the account is modified; it can not be set or modified directly. The initial value consists of the principal name of the creator of the account and the time the account was created. .LI "\*Lorganization \*Vorganization_name\*O" The name of the organization associated with the account. The value is a single organization name of an existing organization in the registry. This attribute must be specified for the \*Laccount create\*O command; it does not have a default value. .PP If an organization is deleted from the registry, all accounts associated with the organization are also deleted. .LI "\*Lpassword \*Vpassword\*O" The password of the account. This attribute must be specified for the \*Laccount create\*O command; there is no default value. This attribute is not returned by an \*Laccount show\*O command. .LI "\*Lpostdatedtkt \*O{\*Lyes\*O | \*Lno\*O}" A flag set to determine if tickets with a start time some time in the future can be issued to the account's principal. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lno\*O. .PP In DCE this attribute is currently only advisory. However, Kerberos clients and servers will make use of it when they interact with a DCE Security server. .LI "\*Lproxiabletkt {yes | no}\*O" A flag set to determine whether or not a new ticket with a different network address than the present ticket can be issued to the account's principal. The \*Lforwardabletkt\*O attribute performs the same function for ticket-granting tickets. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lno\*O. .PP In DCE this attribute is currently only advisory. However, Kerberos clients and servers will make use of it when they interact with a DCE Security server. ...\" .zA "def,13230,R1.2.1,HP edits" .LI "\*Lpwdvalid \*O{\*Lyes\*O | \*Lno\*O}" A flag set to determine whether the current password is valid. If this flag is set to \*Lno\*O, the next time a principal logs in to the account, the system prompts the principal to change the password. (Note that this flag is separate from the \*Lpwdexpdate\*O policy, which sets time limits on password validity.) Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lyes\*O. .LI "\*Lrenewabletkt {yes | no}\*O" A flag set to determine if the ticket-granting ticket issued to the account's principal can be renewed. If this flag is set to \*Lyes\*O, the authentication service renews the ticket-granting ticket if its lifetime is valid. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lyes\*O. .PP In DCE this attribute is currently only advisory. However, Kerberos clients and servers will make use of it when they interact with a DCE Security server. ...\" .zZ "def,13230,R1.2.1,HP edits" .LI "\*Lserver \*O{\*Lyes \*O| \*Lno\*O}" A flag set to indicate whether or not the account is for a principal that can act as a server. If the account is for a server that engages in authenticated communications, set this flag to \*Lyes\*O. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lyes\*O. ...\" .zA "def,13230,R1.2.1,HP edits" .LI "\*Lshell \*Vpath_to_shell\*O" The path of the shell that is executed when a principal logs in. The legal value is any shell supported by the home cell. The default value is the empty string (""). ...\" .zZ "def,13230,R1.2.1,HP edits" .LI "\*Lstdtgtauth {yes | no}\*O" A flag set to determine whether or not service tickets issued to the account's principal use the standard DCE ticket-granting ticket authentication mechanism. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lyes\*O. .LE .SS "Policy Attributes" ...\" The policy attributes are as follows: .VL .LI "\*Lmaxtktlife \*Vrelative_time\*O" The maximum amount of time that a ticket can be valid. To specify the time, use the Distributed Time Service (DTS) relative time format ([\*L-\*O]\*VDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*O). When a client requests a ticket to a server, the lifetime granted to the ticket takes into account the \*Lmaxtktlife\*O set for both the server and the client. In other words, the lifetime cannot exceed the shorter of the server's or client's \*Lmaxtktlife\*O. If you do not specify a \*Lmaxtktlife\*O for an account, the \*Lmaxtktlife\*O defined as registry authorization policy is used. .LI "\*Lmaxtktrenew \*Vrelative_time\*O" The amount of time before a principal's ticket-granting ticket expires and that principal must log in again to the system to reauthenticate and obtain another ticket-granting ticket. To specify the time, use the DTS relative time format ([\*L-\*O]\*VDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*O). The lifetime of the principal's service tickets can never exceed the lifetime of the principal's ticket-granting ticket. The shorter you make this, the greater the security of the system. However, since principals must log in again to renew their ticket-granting ticket, the time needs to take into consideration user convenience and the level of security required. If you do not specify this for an account, the \*Lmaxtktrenew\*O lifetime defined as registry authorization policy is used. .LE .PP See the \*VOSF DCE Administration Guide\*O for more information about account attributes. ...\" See the \*(Ag for more information about account attributes. .SH "OPERATIONS" .SS "account catalog" .PP Returns a list of the names of all accounts in the registry. The syntax is as follows: .sS \*Laccount catalog \*O[\*Vcell_name\*O] [\*L-simplename\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-simplename\*O" Returns a list of account names in the registry without prepending the cellname. .LE .PP The \*Lcatalog\*O operation returns a list of the names of all accounts in the local registry database. Use the \*Vcell_name\*O argument to return a list of accounts in another cell's registry. By default, fully qualified names are returned in the form \*Vcell_name\*L/\*Vaccount_name\*O. Use the \%\*L-simplename\*O option to return the names without the cell name in the form \*Vaccount_name\*O. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the principal named in the account. .PP \*LExamples\*O .PP .oS dcecp> \*Laccount catalog -simplename\*C nobody root daemon uucp bin dce-ptgt dce-rgy krbtgt/goodco.com cell_admin hosts/pmin17/self hosts/pmin17/cds-server hosts/pmin17/gda ward dcecp> dcecp> \*Laccount catalog\*C /.../goodco.com/nobody /.../goodco.com/root /.../goodco.com/daemon /.../goodco.com/uucp /.../goodco.com/bin /.../goodco.com/dce-ptgt /.../goodco.com/dce-rgy /.../goodco.com/krbtgt/goodco.com /.../goodco.com/cell_admin /.../goodco.com/hosts/pmin17/self /.../goodco.com/hosts/pmin17/cds-server /.../goodco.com/hosts/pmin17/gda /.../goodco.com/ward dcecp> .oE .SS "account create" .PP Creates a new account in the registry database. The syntax is as follows: .sS \*Laccount create \*Vaccount_name_list .nL \*L-mypwd \*Vpassword .nL \*L-password \*Vpassword\*L .nL \*L-group \*Vgroup_name .nL \*L-organization \*Vorganization_name\*O .nL [\*L-attribute \*Vattribute_list\*O | .nL \*L-\*Vattribute value\*O] .sE .PP \*LOptions\*O .PP .VL ...\" .zA "def,13230,R1.2.1,HP edits" .LI "\*L-\*Vattribute value\*O" As an alternative to using the \*L-attribute\*O option with an attribute list, you can specify individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. .LI "\*L-attribute \*Vattribute_list\*O" Allows you to specify attributes by using an attribute list rather than using the \*L-\*Vattribute value\*O option. The format of an attribute list is as follows: .iS {{\*Vattribute \*Vvalue\*O}...{\*Vattribute \*Vvalue\*O}} .iE .LI "\*L-group \*Vgroup_name\*O" The name of the group to associate with the account. See \*LAccount Attributes\*O for the format of a group name. .LI "\*L-mypwd \*Vpassword\*O" Your privileged password. You must enter your privileged password to create an account. This check prevents a malicious user from using an existing privileged session to create unauthorized accounts. You must specify this option on the command line; it cannot be supplied in a script. .LI "\*L-organization \*Vorganization_name\*O" The name of the organization to associate with the account. See \*LAccount Attributes\*O for the format of an organization name. .LI "\*L-password \*Vpassword\*O" The account password. See \*LAccount Attributes\*O for the format of a password. .LE ...\" .zZ "def,13230,R1.2.1,HP edits" .PP The \*Lcreate\*O operation creates a new account. The \*Vaccount_name_list\*O argument is a list of names of principals for which the accounts are to be created. This operation returns an empty string on success. .PP You must specify the \*Lgroup\*O, \*Lorganization\*O, \*Lpassword\*O, and \*Lmypwd\*O attributes on the command line (either in an attribute list or with attribute options). The attributes specified are applied to all of the accounts created. .PP To protect the account password being entered, the \*Laccount create\*O command can be entered only from within \*Ldcecp\*O. You cannot enter this command from the operating system prompt by using \*Ldcecp\*O with the \%\*L-c\*O option. .PP Before you can create a new account, you must create a principal by using the \*Lprincipal create\*O command. Then you must add the principal to an existing group and organization using the \*Lgroup add\*O and \*Lorganization add\*O commands. .PP \*LPrivileges Required\*O .PP You must have the following permissions: .ML .LI \*Lgmau\*O (\*Lgroups\*O, \*Lmgmt_info\*O, \*Lauth_info\*O, and \*Luser_info\*O) permissions to the principal named in the account .LI \*LrtM\*O (\*Lread\*O, \*Ltest\*O, \*LMember_list\*O) permissions to the organization named in the account .LI \*LtM\*O (\*Ltest\*O, \*LMember_list\*O) permissions to the group named in the account .LI \*Lr\*O (\*Lread\*O) permission on the registry policy object. .LE .PP \*LExamples\*O .PP .oS dcecp> \*Lprincipal create John_Hunter \*C dcecp> dcecp> \*Lgroup add users -member John_Hunter \*C dcecp> dcecp> \*Lorganization add users -member John_Hunter \*C dcecp> dcecp> \*Laccount create John_Hunter -group users -organization users \\\*C > \*L-mypwd my.secret.password -password change.me \*C dcecp> .oE .SS "account delete" .PP Deletes existing accounts from the registry. The syntax is as follows: .sS \*Laccount delete \*Vaccount_name_list\*O .sE .PP The \*Ldelete\*O operation deletes existing accounts from the registry. The argument is a list of names of accounts to be deleted. If the accounts do not exist an error is generated. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lrmau\*O (\*Lread\*O, \*Lmgmt_info\*O, \*Lauth_info\*O, \*Luser_info\*O) permissions for the principal named in the account. .PP \*LExamples\*O .PP .oS dcecp> \*Laccount delete John_Hunter\*O dcecp> .oE ...\" .zA "1.1, CR13075" .SS "account generate" .PP Randomly generates a password for a named account. The syntax is as follows: .sS \*Laccount generate\*O \*Vaccount_name\*O .sE .PP To run the \*Laccount generate\*O command, the \*Lpwd_strength\*O server must be running, the principal identified by \*Vaccount_name\*O must exist, and the \*Lpwd_mgmt_binding\*O and \*Lpwd_val_type\*O Extended Registry Attributes must be attached to that principal. Otherwise, an error is generated. The command returns a randomly generated password on success. .PP ...\" See the \*(Ag for more information about the \*Lpwd_strength\*O server. See the \*VOSF DCE Administration Guide\*O for more information about the \*Lpwd_strength\*O server. .PP After the password is generated, run the \*Laccount create\*O command to establish the account. Supply the randomly generated password as the account's password (using the \%\*L-password\*O option). .PP \*LPrivileges Required\*O .PP You must have the \*Lgmau\*O (\*Lgroups\*O, \*Lmgmt_info\*O, \*Lauth_info\*O, and \*Luser_info\*O) permissions for the principal named in the account. .PP \*LExamples\*O .PP .oS dcecp> \*Laccount generate john_hunter\*C dcecp> .oE ...\" .zZ "1.1, CR13075" .PP .SS "account help" .PP Returns help information about the \*Laccount\*O object and its operations. The syntax is as follows: .sS \*Laccount help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Laccount\*O object. .LE .PP Used without an argument or option, the \*Laccount help\*O command returns brief information about each \*Laccount\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Laccount\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Laccount help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Laccount help\*C catalog Returns the names of all accounts in the registry. create Creates an account in the registry. delete Deletes an account from the registry. generate Generates a random password for an account in the registry. modify Modifies an account in the registry. show Returns the attributes of an account. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "account modify" .PP Changes attributes and policies of existing accounts. The syntax is as follows: .sS \*Laccount modify \*Vaccount_name_list .nL [\*L -mypwd \*Vpassword\*O] .nL {\*L-change \*Vattribute_list\*O | .nL \*L-\*Vattribute value\*O} .sE .PP \*LOptions\*O .VL ...\" .zA "def,13230,R1.2.1,HP edits" .LI "\*L-\*Vattribute value\*O" As an alternative to using the \*L-change\*O option with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. .LI "\*L-change\*O \*Vattribute_list\*O" Allows you to modify attributes by using an attribute list rather than using individual attribute options. The format of an attribute list is as follows: .iS \*O{{\*Vattribute value\*O}...{\*Vattribute value\*O}} .iE .PP .LI "\*L-mypwd \*Vpassword\*O" Lets you supply your privileged password when changing policy or administration data. You must enter your privileged password to change an account password; otherwise, the \*L-mypwd\*O option is optional. This check prevents a malicious user from using an existing privileged session to modify passwords of existing accounts. .LE .PP The \*Lmodify\*O operation modifies account attributes. The \*L-add\*O and \%\*L-remove\*O options are not supported because the attributes created when the account is created cannot be deleted, nor can additional attributes be added. To change an account attribute, supply the new value in an attribute list or as an individual attribute option. The operation returns an empty string on success. .PP To protect any passwords being entered, you can execute the \*Laccount modify\*O command only from within the \*Ldcecp\*O program; you cannot execute it from the operating system prompt using \*Ldcecp\*O with the \%\*L-c\*O option. .PP \*LPrivileges Required\*O .PP You must have \*Lrm\*O (\*Lread\*O, \*Lmgmt_info\*O) permissions for the principal named in the account. .PP \*LExamples\*O .PP The following example changes the account's expiration date and login shell by specifying the \*Lexpdate\*O and \*Lshell\*O attributes as individual attribute options. .oS dcecp> \*Laccount modify John_Hunter -expdate 1998 -shell /bin/csh\*C dcecp> dcecp> \*Laccount show John_Hunter \*C {acctvalid yes} {client yes} {created /.../my_cell.goodco.com/cell_admin 1994-06-15-18:31:08.000+00:00I-----} {description {}} {dupkey no} {expdate 1995-06-16-00:00:00.000+00:00I-----} {forwardabletkt yes} {goodsince 1994-06-15-18:31:05.000+00:00I-----} {group users} {home /} {lastchange /.../my_cell.goodco.com/cell_admin 1994-06-16-12:21:07.000+00:00I-----} {organization users} {postdatedtkt no} ...\" ...\" 0021 tech ComRef 1-12 man1m/account.1m ...\" ...\" The "postdatedtkt" attribute is not implemented. ...\" {proxiabletkt no} ...\" ...\" 0022 tech ComRef 1-12 man1m/account.1m ...\" ...\" The "proxiabletkt" attribute is not implemented. ...\" ...\" {pwdvalid yes} {renewabletkt yes} ...\" ...\" 0023 tech ComRef 1-12 man1m/account.1m ...\" ...\" The "renewabletkt" attribute is not implemented. ...\" {server yes} {shell /bin/csh} {stdtgtauth yes} dcecp> .oE ...\" .zA "def,13230,R1.2.1,HP edits" .SS "account operations" .PP Returns a list of the operations supported by the \*Laccount\*O object. The syntax is as follows: .sS \*Laccount operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Laccount operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Laccount operations\*C catalog create delete generate modify show help operations dcecp> .oE ...\" .zZ "def,13230,R1.2.1,HP edits" .SS "account show" .PP Returns attribute information for the specified accounts. The syntax is as follows: .sS \*Laccount show \*Vaccount_name_list\*O [\*L-policies\*O | \*L-all\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-policies\*O" Returns only account polices. .LI "\*L-all\*O" Returns account attributes followed by account policies. .LE .PP The \*Lshow\*O operation returns an attribute list describing the specified accounts. The argument is a list of names of accounts to be operated on. If more than one account is given, the attributes and policies are concatenated and a blank line inserted between accounts. The \%\*L-policies\*O option lets you return the policies of the account instead of the attributes. The \%\*L-all\*O option returns the attributes followed by the policies. .PP Attributes and policies are returned in lexical order. If the account has no policies, the operation displays the string \*Lnopolicy\*O. .P The policies that are actually in effect can be different from the account policies due to conflicts with registry-wide policies. If this is the case, the \*Lshow\*O operation will alter the attribute structure on output to include an \*Leffective\*O tag and the effective value, much in the same way \*Lorganization show\*O does. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the principal named in the account. .PP \*LExamples\*O .PP .oS dcecp> \*Laccount show John_Hunter\*C {acctvalid yes} {client yes} {created /.../my_cell.goodco.com/cell_admin 1994-06-15-18:31:08.000+00:00I-----} {description {}} {dupkey no} {expdate 1995-06-16-00:00:00.000+00:00I-----} {forwardabletkt yes} {goodsince 1994-06-15-18:31:05.000+00:00I-----} {group users} {home /} {lastchange /.../my_cell.goodco.com/cell_admin 1994-06-16-12:21:07.000+00:00I-----} {organization users} {postdatedtkt no} {proxiabletkt no} {pwdvalid yes} {renewabletkt yes} {server yes} {shell {}} {stdtgtauth yes} dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad 1 \*Ldcecp_group(1m)\*O, \*Ldcecp_principal(1m)\*O, \*Ldcecp_organization(1m)\*O, \*Ldcecp_registry(1m)\*O. .ad b ...\" Commands: ...\" .ad l ...\" \*Ldcecp(1m)\*O, ...\" \*Lgroup(1m)\*O, ...\" \*Lorganization(1m)\*O, ...\" \*Lprincipal(1m)\*O, ...\" \*Lregistry(1m)\*O. ...\" .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH acl 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lacl\*O" .iX "acl" "administering" .SH NAME .PP \*Lacl\*O - A \*Ldcecp\*O object that manages DCE access control lists .SH "SYNOPSIS" .sS ...\" .zA "Def,13377,R1.2.2,clarify syntax" \*Lacl check \*Vacl_name_list\*O [\*L-entry\*O] [\*L-type \*Vmanager_type_name\*O] .PP ...\" .zA "1.2.1: add -local" \*Lacl delete \*Vacl_name_list\*O [\*L-ic \*O| \*L-io \*O| \*L-entry\*O] [\*L-type \*Vmanager_type_name\*O] .nL [\*L-local\*O] ...\" .zZ "1.2.1: add -local" .PP \*Lacl help \*O[\*Voperation\*O | \*L-verbose\*O] .PP ...\" .zA "1.2.1: add -local" \*Lacl modify \*Vacl_name_list\*O [\*L-ic \*O| \*L-io \*O| \*L-entry\*O] [\*L-type \*Vmanager_type_name\*O] ...\" .zZ "1.2.1: add -local" .nL [\*L-cell \*Vnew_cell_name\*O] .nL {\*L-add \*Vacl_entry_list_with_permissions\*O [\*L-mask\*O {\*Lcalc\*O |\*L nocalc\*O}] | .nL \*L-change \*Vacl_entry_list_with_permissions\*O [\*L-mask {\*Lcalc\*O |\*L nocalc\*O}] | .nL \*L-remove \*Vacl_entry_list_without_permissions\*O | .nL \*L-purge\*O} .nL [\*L-local\*O] .PP \*Lacl operations\*O .PP ...\" .zA "1.2.1: add -local" \*Lacl permissions \*Vacl_name_list\*O [\*L-ic \*O| \*L-io\*O | \*L-entry\*O] [\*L-type \*Vmanager_type_name\*O] .nL [\*L-local\*O] ...\" .zZ "1.2.1: add -local" .PP ...\" .zA "1.2.1: add -local" \*Lacl replace \*Vacl_name_list\*O [\*L-ic \*O| \*L-io \*O| \*L-entry\*O] [\*L-type \*Vmanager_type_name\*O] ...\" .zZ "1.2.1: add -local" .nL \*L-acl \*Vacl_entry_list\*O [\*L-cell \*Vnew_default_cellname\*O] .nL [\*L-local\*O] .PP ...\" .zA "1.2.1: add -local" \*Lacl show \*Vacl_name_list\*O [\*L-ic \*O| \*L-io \*O| \*L-entry\*O] [\*L-type \*Vmanager_type_name\*O] ...\" .zZ "1.2.1: add -local" .nL [\*L-cell\*O | \*L-managers\*O] [\*L-local\*O] ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .sE .SH "ARGUMENTS" .VL .LI "\*Vacl_name_list\*O A list of one or more objects whose ACLs are to be acted on. You can identify objects by using the object's fully qualified names, for example, \*L/.:/hosts/gumby\*O. .PP You can also use a list of string bindings with residual names appended. The residual name indicates whether the object is a principal, group, or organization by supplying its principal, group, or organization name. There are four possible formats you can use to specify a string binding. .PP In string syntax, you can use .PP .iS {\*Vuuid\*L@\*Vprot_seq\*L:\*Vnet_addr residual_name\*L} .iE ...\" For example: ...\" .oS ...\" {006f859c-ed3d-1d57-a383-0000c0239a70@ncacn_ip_tcp:130.105.5.45 principal/aaa} ...\" .oE Another allowable string syntax is .iS {\*Vuuid\*L@\*Vprot_seq\*L:\*Vnet_addr\*L[\*Vendpoint\*L] \*Vresidual_name\*L} .iE In TCL syntax, you can use .iS {{\*Vuuid prot_seq net_addr\*L} \*Vresidual_name\*L} .iE ...\" For example: ...\" .oS ...\" {{006f859c-ed3d-1d57-a383-0000c0239a70 ncacn_ip_tcp 130.105.5.45} principal/aaa} ...\" .oE Another allowable TCL syntax is .iS {{\*Vuuid prot_seq net_addr endpoint\*L} \*Vresidual_name\*L} .iE .LI "\*Voperation\*O" The name of the \*Lacl\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Lacl\*O object represents an access control list (ACL) which may exist on any object such as a server, name service entry, container (directory), or file. .PP ACLs consist of ACL entries. ACL entries are visible only as members of ACLs. There is no object that represents ACL entries, only the \*Lacl\*O object representing an entire ACL. Most of the \*Lacl\*O operations deal directly with the ACL. See the \*LDATA STRUCTURES\*O section for a description of the syntax of ACLs and ACL entries. An ACL has one attribute, called \*Lcell\*O, that represents the default cell of the ACL. .PP In most cases, the name of an object also specifies the name of the associated ACL to manipulate. However, some objects have more than one ACL, and some names can refer to more than one object. These ambiguities are resolved by using various options on the command line. .PP An object can have more than one ACL. For example, container objects\(emsuch as Cell Directory Service (CDS) directories and directories in the registry\(emhave three ACLs: one ACL controls access to the container object itself, another ACL specifies the default ACL on new objects added to the container (the Initial Object ACL), and a third ACL specifies the default ACL on new containers added to the container (the Initial Container ACL). By default, the \*Lacl\*O commands operate on the ACL of the container object. Use the \%\*L-ic\*O option to operate on the Initial Container ACL. Use the \%\*L-io\*O option to operate on the Initial Object ACL. Simple objects (those that aren't container objects) do not have Initial Container or Initial Object ACLs. .PP Some servers that have ACLs also store their network location information in a server entry in CDS. The server entry has the same name as the server itself and may also have an attached ACL. Use the \*L-entry\*O option to operate on the server entry ACL in CDS rather than the server's ACL. ...\" .zA "1.2.1: add -local" .PP All \*Ldced\*O objects have ACLs. When the \*Ldced\*O on the local machine is in partial service mode, you must use the \%\*L-local\*O option to access \*Ldced\*O object ACLs. To access \*Ldced\*O object ACLs, specify only the residual portion of the object name to the \*Lacl\*O command. For example, use \*Lhostdata\*O, not \*L/.:/hosts/gumby/config/hostdata\*O. ...\" .zZ "1.2.1: add -local" .PP Some DCE objects have more than one purpose. For instance, a registry object can represent a principal and it can also act as a directory (a container). An example is a principal name that identifies another cell (for instance, \*L/.../comp.com\*O) with which we want to establish authenticated operation. In this case, our cell maintains a principal name \*L/.:/comp.com\*O. The registry object for this principal name is as follows: .iS /.:/sec/principal/comp.com .iE .PP Let's say our cell also has a hierarchical (subordinate) cell named \*L/.../comp.com/test_cell\*O. Our cell maintains another principal name \*L/.:/comp.com/test_cell\*O. The registry object for this principal name is as follows: .iS /.:/sec/principal/comp.com/test_cell .iE .PP Consequently, the registry object \*L/.:/sec/principal/friendly.company.com\*O also acts as a directory because it contains the hierarchical cell name \*L/.:/sec/principal/friendly.company.com/test_cell\*O. The ACL manager that operates on registry objects differs from the ACL manager that operates on registry directories. For instance, the latter ACL manager has an \*Li\*O (insert) permission bit that controls who can add new objects to the directory. Consequently, most \*Lacl\*O commands provide a \%\*L-type\*O option that lets you specify the appropriate ACL manager when operating on registry objects that are also directories. You can list the ACL managers that are available for registry objects by using the \*Lacl show -managers\*O command. .SH "DATA STRUCTURES" .PP .SS "ACL Entry Syntax" An ACL entry has the following syntax: .sS \*Vtype\*O[\*L:\*O\*Vkey\*O]\*L:\*O\*Vpermissions\*O .sE .PP where: .VL 1i .LI "\*Vtype\*O" Identifies the role of the ACL entry. .LI "\*Vkey\*O" Identifies the specific principal or group to whom the entry applies. For an entry type of \*Lextended\*O, \*Vkey\*O contains the ACL data. .LI "\*Vpermissions\*O" The ACL permissions. .LE .PP The syntax of an ACL entry is a list of two or three elements. The first element is the type, the optional second element is the key, and the last element is the set of permission bits. The permission bits are represented by a single character if the permission is granted and by \*L-\*O (dash) if it is not. An ACL is a list of ACL entries. An example of an ACL is as follows: .iS {unauthenticated -r-----} {user_obj crwx---} {user britten crwx---} {user mahler -rwx---} {foreign_user /.../C=US/O=OSF/OU=dce/pro/bach crwxidt} {group_obj -rwx---} {group dds -rwx---} {any_other -r-----}, {extended c417faf8-8340-11c9-ace3-08001e5559bb.a.b.c.a1.4.0a0b0c0d -rwx---} .iE .PP On output the above syntax is used, with one addition. If masking produces ineffective bits in an ACL entry, the entry has two additional elements. The first is the identifier \*Leffective\*O, and the second is the set of effective permissions. This is added only for those ACL entries that have ineffective bits, as seen in the following example: .iS {mask_obj -r-----} {user_obj crwx---} {user britten crwx--- effective -r-----} .iE .PP On input, do not include the identifier \*Leffective\*O or the effective permissions. You can enter permissions in any order, omitting the \*L-\*O for permissions not granted. For example, the above ACL could be entered as: .iS {mask_obj r} {user_obj crwx} {user britten wcrx} .iE .SS "Defined ACL Entry Types" .VL .LI "\*Luser_obj\*O" Permissions for the object's real or effective owner. .LI "\*Lgroup_obj\*O" Permissions for the object's real or effective owning group. .LI "\*Lother_obj\*O" Permissions for others authenticated in the local cell who are not otherwise named by a more specific entry type. .LI "\*Luser\*O" Permissions for a specific authenticated principal user in the ACL's cell. This type of ACL entry must include a key that identifies the specific principal. .LI "\*Lgroup\*O" Permissions for a specific group in the ACL's cell. This type of ACL entry must include a key that identifies the specific group. .LI "\*Lforeign_user\*O" Permissions for a specific, authenticated user in a foreign cell. This type of ACL entry must include a key that identifies the specific principal and the principal's cell. .LI "\*Lforeign_group\*O" Permissions for a specific group in a foreign cell. This type of ACL entry must include a key that identifies the specific group and the group's cell. .LI "\*Lforeign_other\*O" Permissions for all authenticated principals in a specific foreign cell, unless those principals are specifically named in an ACL entry of type \*Lforeign_user\*O or are members in a group named in an entry of type \*Lforeign_group\*O. This type of ACL entry must include a key that identifies the specific foreign cell. .LI "\*Lany_other\*O" Permissions for all authenticated principals unless those principals match a more specific entry in the ACL. .LI "\*Lmask_obj\*O" Permissions for the object mask that is applied to all entry types except \*Luser_obj\*O, \*Lother_obj\*O, and \*Lunauthenticated\*O. .LI "\*Lunauthenticated\*O" Maximum permissions applied when the accessor does not pass authentication procedures. This entry is used for principals that have failed authentication due to bad keys, principals who are entirely outside of any authentication cell, and principals who choose not to use authenticated access. Permissions granted to an unauthenticated principal are masked with this entry, if it exists. If this entry does not exist, access to unauthenticated principals is always denied. .LI "\*Lextended\*O" A special entry that allows client applications running at earlier DCE versions to copy ACLs to and from ACL Managers running at the current DCE version without losing any data. The \*Lextended\*O entry allows the application running at the lower version to obtain a printable form of the ACL. The \*Lextended\*O ACL entry has the following form: .iS extended:\*Vuuid\*L.\*Vndr\*L.\*Vndr\*L.\*Vndr\*L.\*Vndr\*L.\*Vnumber_of_byte\*L.\*Vdata\*O .iE where: .VL .LI "\*Vuuid\*O" Identifies the type extended ACL entry. (This UUID can identify one of the ACL entry types described here or an as-yet-undefined ACL entry type.) \*L.\*VLI "\*Vndr\*L.\*Vndr\*L.\*Vndr\*L.\*Vndr\*O" Up to three network data representation (NDR) format labels (in hexadecimal format and separated by periods) that identify the encoding of data. .LI "\*Vnumber_of_bytes\*O A decimal number that specifies the total number of bytes in \*Vdata\*O. .LI "\*Vdata\*O" The ACL data in hexadecimal form. (Each byte of ACL data is two hexadecimal digits.) The ACL data includes all of the ACL entry specifications except the permissions (described later) that are entered separately. The data is not interpreted; it is assumed that the ACL manager to which the data is being passed can understand that data. .LE .LI "\*Luser_obj_delegate\*O" Delegated permissions for the object's real or effective owner. .LI "\*Lgroup_obj_delegate\*O" Delegated permissions for the object's real or effective group. .LI "\*Lother_obj_delegate\*O" Delegated permissions for others in the local cell who are not otherwise named by a more specific entry type. .LI "\*Luser_delegate\*O" Delegated permissions for a specific principal user in the ACL's cell. This type of ACL entry must include a key that identifies the specific principal. .LI "\*Lgroup_delegate\*O" Delegated permissions for a specific group in the ACL's cell. This type of ACL entry must include a key that identifies the specific group. .LI "\*Lforeign_user_delegate\*O" Delegated permissions for a specific, authenticated user in a foreign cell. This type of ACL entry must include a key that identifies the specific principal and the principal's cell. .LI "\*Lforeign_group_delegate\*O" Delegated permissions for a specific, authenticated group in a foreign cell. This type of ACL entry must include a key that identifies the specific group and the group's cell. .LI "\*Lforeign_other_delegate\*O" Delegated permissions for all authenticated principals in a specific foreign cell, unless those principals are specifically named in an ACL entry of type \*Lforeign_user\*O or \*Lforeign_user_delegate\*O or members in a group named in an entry of type \*Lforeign_group\*O or \*Lforeign_group_delegate\*O. This type of ACL entry must include a key that identifies the specific foreign cell. .LI "\*Lany_other_delegate\*O" Delegated permissions for all authenticated principals unless those principals match a more specific entry in the ACL. .LE .SS "Key" The \*Vkey\*O identifier (principal, group name or cell) specifies the principal or group to which the ACL entry applies. For entries of entry type \*Lextended\*O, \*Vkey\*O is the data passed from one ACL manager to another. A \*Vkey\*O is required for the following types of ACL entries: .VL .LI "\*Luser\*O" Requires a principal name only. .LI "\*Lgroup\*O" Requires a group name only. .LI "\*Lforeign_user\*O" Requires a fully qualified cell name in addition to the principal name. .LI "\*Lforeign_group\*O" Requires a fully qualified cell name in addition to the group name. .LI "\*Lforeign_other\*O" Requires a fully qualified cell name. .LI "\*Lforeign_user_delegate\*O" Requires a fully qualified cell name, the principal name, and a key that identifies the principal and the principal's cell. .LI "\*Lforeign_group_delegate\*O" Requires a fully qualified cell name, the group name, and a key that identifies the group and the group's cell. .LE .SS "Permissions" The \*Vpermissions\*O argument specifies the set of permissions that defines the access rights conferred by the entry. Since each ACL Manager defines the permission tokens and meanings appropriate for the objects it controls, the actual tokens and their meanings vary. For example, the Distributed File Service (DFS), the directory service, and the security service each implement a separate ACL manager, and each can use a different set of tokens and permissions. This means that file system objects, objects in the namespace, and registry objects could each use different permissions. Use the \*Lpermissions\*O operation to display the currently available tokens and their meanings. See the documentation for the DCE component you are using to obtain a more detailed description of its specific permissions. .SH "ATTRIBUTES" .VL .LI "\*Lcell \*Vdefault_cellname\*O" Represents the default cell of the ACL. Manipulation of this attribute is possible only through the \*Lmodify\*O and \*Lshow\*O operations. .LE .PP ...\" See the \*(Ag for more information about ACL attributes. See the \*VOSF DCE Administration Guide\*O for more information about ACL attributes. .SH "OPERATIONS" .SS "acl check" .PP Returns the permissions granted by the ACL to the principal entering the command. The syntax is as follows: .sS ...\" .zA "Def,13377,R1.2.2,clarify syntax" \*Lacl check \*Vacl_name_list\*O [\*L-entry\*O] [\*L-type \*Vmanager_type_name\*O] ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-entry\*O" Specifies that the command is to operate on the ACL of the namespace entry of the named object. .LI "\*L-type \*Vmanager_type_name\*O" Specifies that the command uses a particular ACL manager. This option is needed only for objects that have more than one purpose, such as for principal names that also act as directories. .LE .PP The \*Lcheck\*O operation returns the permissions granted in the specified object's ACL to the principal that invoked the command. The argument is a list of names of object's whose ACLs are to be operated on. If you specify no options, the permissions from the ACL for the object named by the operation are returned. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission on the object whose ACL is to be operated on. .PP \*LExamples\*O .PP .oS dcecp> \*Lacl check {006f859c-ed3d-1d57-a383-0000c0239a70@ncacn_ip_tcp:130.105.5.45 \\\*C > \*Lprincipal/aaa}\*C rwdtcia dcecp> dcecp> \*Lacl check /.:/hosts \*C rwdtcia dcecp> .oE .SS "acl delete" .PP Deletes all ACL entries from the object, except the \*Luser_obj\*O entry, if it exists. The syntax is as follows: .sS ...\" .zA "1.2.1: add -local" ...\" .zA "Def,13377,R1.2.2,clarify syntax" \*Lacl delete \*Vacl_name_list\*O [\*L-ic \*O| \*L-io\*O | \*L-entry\*O] [\*L-type \*Vmanager_type_name\*O] .nL [\*L-local\*O] ...\" .zZ "Def,13377,R1.2.2,clarify syntax" ...\" .zZ "1.2.1: add -local" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-ic\*O" Specifies that the command is to operate on the Initial Container ACL of the named object. .LI "\*L-io\*O" Specifies that the command is to operate on the Initial Object ACL of the named object. .LI "\*L-entry\*O" Specifies that the command is to operate on the ACL of the namespace entry of the object. .LI "\*L-type \*Vmanager_type_name\*O" ...\" .zZ "Def,13377,R1.2.2,clarify syntax" Specifies that the command uses a particular ACL manager. This option is needed only for objects that have more than one purpose, such as for principal names that also act as directories. ...\" .zA "1.2.1: add -local" .LI "\*L-local\*O" Specifies that the command is to operate on the ACL of a \*Ldced\*O object while the \*Ldced\*O on the local machine is in partial service mode. ...\" .zZ "1.2.1: add -local" ...\" .zA "Def,13377,R1.2.2,clarify syntax" .LE .PP The \*Ldelete\*O operation removes all ACL entries from the object, except the \*Luser_obj\*O entry, if it exists. Note that if you use \*Ldelete\*O on an object whose ACL does not contain a \*Luser_obj\*O ACL entry (either because the object's ACL managers do not support \*Luser_obj\*O entries or because the ACL is empty), the command displays a "bad syntax" error. .PP The argument is a list of names of objects whose ACLs are to be operated on. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lc\*O (\*Lcontrol\*O) permission on the object whose ACL is to be operated on. .PP \*LExamples\*O .PP .oS dcecp> \*Lacl delete {/.:/hosts/oddball/gumby /.:/pokey}\*C dcecp> .oE .SS "acl help" .PP Returns help information about the \*Lacl\*O object and its operations. The syntax is as follows: .sS \*Lacl help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lacl\*O object. .LE .PP Used without an argument or option, the \*Lacl help\*O command returns brief information about each \*Lacl\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lacl\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lacl help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lacl help\*C check Returns ACL permissions of invoker. delete Deletes all ACL entries except 'user_obj' if it exists. modify Adds, removes, or changes ACL entries and attributes. permissions Returns permissions associated with an object. replace Replaces entire ACL with new ACL entries and attributes. show Returns ACL entries or attributes on an object. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "acl modify" .PP Changes attributes and entries of ACLs. The syntax is as follows: .sS ...\" .zA "Def,13377,R1.2.2,clarify syntax" ...\" .zA "1.2.1: add -local" \*Lacl modify \*Vacl_name_list\*O [\*L-ic \*O| \*L-io \*O| \*L-entry\*O] [\*L-type \*Vmanager_type_name\*O] ...\" .zZ "1.2.1: add -local" .nL [\*L-cell \*Vnew_cell_name\*O] .nL {\*L-add \*Vacl_entry_list_with_permissions\*O [\*L-mask\*O {\*Lcalc\*O |\*L nocalc\*O}] | .nL \*L-change \*Vacl_entry_list_with_permissions\*O [\*L-mask {\*Lcalc\*O |\*L nocalc\*O}] | .nL \*L-remove \*Vacl_entry_list_without_permissions\*O | .nL \*L-purge\*O} .nL [\*L-local\*O] ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-cell\*O \*Vnew_cell_name\*O" Changes the value of the \*Lcell\*O attribute by specifying the new default cell. It must be one value, not a list. The \*L-cell\*O option is always applied before the other options. Note that changing the default cell of an ACL that has \*Luser\*O or \*Lgroup\*O ACL entries, or their delegate counterparts, can be dangerous. The principal and groups mentioned in these ACL entries must be in the default cell. If the default cell changes, these ACL entries must change as well. ...\" .LI "\*L-add \*Vacl_entry_list_with_permissions\*O" Adds the ACL entries to the ACL. The value of this option is a list of ACL entries with permissions filled in. You can use the \*L-mask\*O option to force or prevent mask recalculation. ...\" .LI "\*L-change \*Vacl_entry_list_with_permissions\*L" Changes existing ACL entries in the ACL. The value of this option is a list of ACL entries with permissions filled in. The permissions will be the new permissions placed on the specified ACL entries. The ACL entries must exist in the ACL or an error occurs. You can use the \%\*L-mask\*O option to force or prevent mask recalculation. ...\" .LI "\*L-remove \*Vacl_entry_list_without_permissions\*L" Removes existing ACL entries from the ACL. The value of this option is a list of ACL entries with no permissions. The ACL entries must exist in the ACL or an error occurs. ...\" .LI "\*L-purge\*O" Purges all masked permissions (before any other modifications are made), in all ACL entries except \*Luser_obj\*O, \*Lother_obj\*O, \*Lmask_obj\*O, \*Luser_obj_delegate\*O, \*Lother_obj_delegate\*O, and \*Lunauthenticated\*O if they exist. This option is useful only for ACLs that contain an entry of type \*Lmask_obj\*O. ...\" .LI "\*L-mask\*O {\*Lcalc\*O |\*L nocalc\*O}" If a \*Lmodify\*O operation causes a mask recalculation that unintentionally adds permissions to an existing ACL entry, the \*Lmodify\*O operation will abort with an error unless you specify the \*L-mask\*O option with a value of either \*Lcalc\*O or \*Lnocalc\*O, or a unique abbreviation of one of these values. .PP Specifying \*Lcalc\*O creates or modifies the object's \*Lmask_obj\*O type entry with permissions equal to the union of all entries other than type \*Luser_obj\*O, \*Lother_obj\*O, \*Lmask_obj\*O and \*Lunauthenticated\*O. This creation or modification is done after all other modifications to the ACL are performed. The new mask is set even if it grants permissions previously masked out. It is recommended that you use this option only if not specifying it results in an error. If you specify the \*Lcalc\*O option for an ACL manager that does not support the \*Lmask_obj\*O entry type, an error is returned. .PP Specifying \*Lnocalc\*O means that a new mask should not be calculated. .PP The \*L-mask\*O option can be used only if the \*L-add\*O or \%\*L-change\*O option is also used and only if the object's ACL managers support the \*Lmask_obj\*O ACL type. In addition, you cannot use the \*L-mask\*O option if you specify a \*Lmask_obj\*O ACL entry in the command (by using the \*L-add\*O or \%\*L-change\*O options) ...\" .LI "\*L-ic\*O" Specifies that the operation act on the Initial Container ACL of the named object. ...\" .LI "\*L-io\*O" Specifies that the operation act on the Initial Object ACL of the named object. ...\" .LI "\*L-entry\*O" Specifies that the operation act on the ACL of the namespace entry of the named object. ...\" ...\" .zA "1.2.1: add -local" .LI "\*L-local\*O" Specifies that the operation act on the ACL of a \*Ldced\*O object while the \*Ldced\*O on the local machine is in partial service mode. ...\" .zZ "1.2.1: add -local" ...\" ...\" .zA "Def,13377,R1.2.2,clarify syntax" .LI "\*L-type \*Vmanager_type_name\*O" ...\" .zZ "Def,13377,R1.2.2,clarify syntax" Specifies that the command uses a particular ACL manager. This option is needed only for objects that have more than one purpose, such as for principal names that also act as directories. .LE .PP The \*Lmodify\*O operation changes one or more individual ACL entries. The argument is a list of names of ACLs to be modified. They are processed in the order they are entered. The specific operation to perform is described by using options. .PP Multiple actions can be specified on the command line; they will be processed in a fixed order to guarantee proper processing of the ACLs. See [POSIX.6] for a description of this processing order. Either all the changes specified in the operation are made, or none are. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lc\*O (\*Lcontrol\*O) permission on the object whose ACL is to be operated on. .PP \*LExamples\*O .PP .oS dcecp> \*Lacl modify /.:/hosts -add {user mahler rwcia}\*C dcecp> dcecp> \*Lacl modify /.:/hosts -change {user mahler rwdtcia}\*C dcecp> dcecp> \*Lacl modify /.:/hosts -add {group dce rwdtcia} -remove {user mahler} \*C dcecp> .oE .SS "acl operations" .PP Returns a list of the operations supported by the \*Lacl\*O object. The syntax is as follows: .sS \*Lacl operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lacl operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lacl operations\*C check delete modify permissions replace show help operations dcecp> .oE .SS "acl permissions" .PP Returns a list describing the permissions associated with an object. The syntax is as follows: .sS ...\" .zA "Def,13377,R1.2.2,clarify syntax" ...\" .zA "1.2.1: add -local" \*Lacl permissions \*Vacl_name_list\*O [\*L-ic\*O | \*L-io \*O| \*L-entry\*O] [\*L-type \*Vmanager_type_name\*O] .nL [\*L-local\*O] ...\" .zZ "1.2.1: add -local" ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-ic\*O" Specifies that the command is to operate on the Initial Container ACL of the named object. .LI "\*L-io\*O" Specifies that the command is to operate on the Initial Object ACL of the named object. .LI "\*L-entry\*O" Specifies that the command is to operate on the ACL of the namespace entry of the named object. .LI "\*L-type \*Vmanager_type_name\*O" Specifies that the command uses a particular ACL manager. This option is needed only for objects that have more than one purpose, such as for principal names that also act as directories. ...\" .zA "1.2.1: add -local" .LI "\*L-local\*O" Specifies that the command is to operate on the ACL of a \*Ldced\*O object while the \*Ldced\*O on the local machine is in partial service mode. ...\" .zZ "1.2.1: add -local" .LE .PP The \*Lpermissions\*O operation returns a list of the permissions associated with an object. For each permission, the operation shows the permission token and a description of the permission. The \*Vmanager_type_name\*O argument is a list of names of ACL manager types whose permissions are to be returned. If more than one name is entered the output is concatenated and a blank line inserted between each manager type. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission on the object whose ACL is to be operated on. .PP \*LExamples\*O .PP .oS dcecp> \*Lacl permissions /.:/hosts \*C{r {read entry attributes}} {w {update entry attributes}} {d {delete entry}} {t {test attribute values}} {c {change ACL}} {i {create new directory entries}} {a {administer directory replication}} dcecp> .oE .SS "acl replace" .PP Replaces the entire ACL on the object specified by the argument with the supplied value. The syntax is as follows: .sS ...\" .zA "1.2.1: add -local" ...\" .zA "Def,13377,R1.2.2,clarify syntax" \*Lacl replace \*Vacl_name_list\*O [\*L-ic\*O | \*L-io \*O| \*L-entry\*O] [\*L-type \*Vmanager_type_name\*O] .nL \*L-acl \*Vacl_entry_list\*O [\*L-cell \*Vnew_default_cellname\*O] .nL [\*L-local\*O] ...\" .zZ "Def,13377,R1.2.2,clarify syntax" ...\" .zZ "1.2.1: add -local" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-ic\*O" Specifies that the operation act on the Initial Container ACL of the named object. .LI "\*L-io\*O" Specifies that the operation act on the Initial Object ACL of the named object. .LI "\*L-entry\*O" Specifies that the operation act on the ACL of the namespace entry of the named object. .LI "\*L-type \*Vmanager_type_name\*O" Specifies that the command use a particular ACL manager. This option is needed only for objects that have more than one purpose, such as for principal names that also act as directories. .LI "\*L-acl\*O \*Vacl_entry_list\*O" Specifies ACL entries and their new values. .LI "\*L-cell\*O \*Vnew_default_cellname\*O" Specifies a new default cell for all of the ACLs named in \*Vacl_entry_list\*O. The \%\*L-cell\*O option is always applied before the other options. ...\" .zA "1.2.1: add -local" .LI "\*L-local\*O" Specifies that the operation act on the ACL of a \*Ldced\*O object while the \*Ldced\*O on the local machine is in partial service mode. ...\" .zZ "1.2.1: add -local" .LE .PP The \*Lreplace\*O operation replaces the entire ACL on the object specified by the argument, with the supplied value. The argument is a list of names of ACLs to be operated on. The syntax of the value of the \%\*L-acl\*O option is a list of ACL entries. Also takes a \%\*L-cell\*O option to specify the new default cell of the ACL. Its value is the name of one cell only (it is not a list). This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lrwd\*O (\*Lread\*O), \*Lwrite\*O, \*Ldelete\*O) permissions on the object whose ACL is being operated on. .PP \*LExamples\*O .PP .oS dcecp> \*Lacl replace /.:/hosts -acl {group dce rwdtcia}\*C dcecp> .oE .SS "acl show" .P Returns a list of the ACL entries for the specified object. The syntax is as follows: .sS ...\" .zA "Def,13377,R1.2.2,clarify syntax" ...\" .zA "1.2.1: add -local" \*Lacl show \*Vacl_name_list\*O [\*L-ic \*O| \*L-io \*L| -entry\*O] [\*L-type \*Vmanager_type_name\*O] .nL [\*L-cell\*O | \*L-managers\*O] [\*L-local\*O] ...\" .zZ "1.2.1: add -local" .PP ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-ic\*O" Specifies that the command is to operate on the Initial Container ACL of the named object. .LI "\*L-io\*O" Specifies that the command is to operate on the Initial Object ACL of the named object. .LI "\*L-entry\*O" Specifies that the command is to operate on the ACL of the namespace entry of the named object. .LI "\*L-type \*Vmanager_type_name\*O" ...\" .zZ "Def,13377,R1.2.2,clarify syntax" Specifies that the command uses a particular ACL manager. This option is needed only for objects that have more than one purpose, such as for principal names that also act as directories. .LI "\*L-cell\*O" Returns the default cell name for the ACL. .LI "\*L-managers\*O" Returns a list of ACL managers available for the named ACL. ...\" .zA "1.2.1: add -local" .LI "\*L-local\*O" Specifies that the command is to operate on the ACL of a \*Ldced\*O object while the \*Ldced\*O on the local machine is in partial service mode. ...\" .zZ "1.2.1: add -local" ...\" .zA "Def,13377,R1.2.2,clarify syntax" .LE .PP The \*Lshow\*O operation returns a list of the ACL entries for the specified object. The argument is a list of names of of objects whose ACLs are to be operated on. If more than one name is given, the output is concatenated and a blank line inserted between objects. If they exist, the \*Lmask_obj\*O and \*Lunauthenticated\*O ACL entries are displayed first. .PP Note that since UUIDs and not names are stored in ACLs, \*Ldcecp\*O may not be able to determine the name associated with an ACL entry. In this case, the UUID will be returned as the key instead of the name. This can happen if the default cell stored in the ACL is incorrect, or if the users and groups specified in the \*Luser\*O and \*Lgroup\*O entries are not registered in the default cell. .PP If a UUID replaces a name of a user and group, you can recover by adopting the orphaned UUID. To do this, create a new user or group using the UUID found in the ACL. The name of the new user or group will then be available. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission on the object whose ACL is to be operation on. .PP \*LExamples\*O .PP .oS dcecp> \*Lacl show /.:/hosts\*C {unauthenticated r--t---} {user cell_admin rwdtcia} {user hosts/absolut/cds-server rwdtcia} {user hosts/absolut/self rwdtcia} {user root rwdtcia} {group subsys/dce/cds-admin rwdtcia} {group subsys/dce/cds-server rwdtcia} {any_other r--t---} dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_account(1m)\*O, \*Ldcecp_group(1m)\*O, \*Ldcecp_organization(1m)\*O, \*Ldcecp_principal(1m)\*O, \*Ldcecp_registry(1m)\*O, \*Ldcecp_xattrschema(1m)\*O. .ad b ...\" .ad l ...\" \*Ldcecp(1m)\*O, ...\" dcecp_account(1m)\*O, ...\" dcecp_group(1m)\*O, ...\" dcecp_organization(1m)\*O, ...\" dcecp_principal(1m)\*O, ...\" dcecp_registry(1m)\*O, ...\" dcecp_xattrschema(1m)\*O. ...\ .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file attrlistd COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" .rm zA .rm zZ .TH attrlist 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lattrlist\*O" .iX "attrlist" "manipulating" .SH NAME \*Lattrlist\*O - A \*Ldcecp\*O object that manipulates attribute lists .SH "SYNOPSIS" .sS \*Lattrlist add \*Vattrlist \*L-member \*Vattrlist .PP \*Lattrlist getvalues \*Vattrlist\*L -type \*Vtypename .PP \*Lattrlist help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lattrlist list \*Vattrlist .PP ...\" .zA "Def,13377,R1.2.2,clarify syntax" \*Lattrlist modify \*Vattrlist .nL \*O{[\*L-add \*Vattribute_type attribute_values\*O] .nL [\*L-change \*Vattribute_type attribute_values\*O] .nL [\*L-remove \*Vattribute_type attribute_values\*O]} ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .PP \*Lattrlist operations\*O .PP \*Lattrlist remove \*Vattrlist\*L -member \*Vattrlist .sE .SH "ARGUMENTS" .VL .LI "\*Vattrlist\*O" A list of one or more \*Ldcecp\*O elements. An \*Vattrlist\*O can be a single character, but usually consists of at least one attribute type and its value, as shown in the following: .iS {CDS_Convergence medium} .iE .LI "\*Voperation\*O" The name of the \*Lattrlist\*O operation for which to display help information. .LE .SH "DESCRIPTION" The \*Lattrlist\*O object represents an attribute list as returned or accepted by many \*Ldcecp\*O commands. Use this object to check or manipulate attribute lists so that they can be used by other commands, most commonly in scripts. .SH "OPERATIONS" .SS "attrlist add" .PP Appends one attribute list to another. The syntax is as follows: .sS \*Lattrlist add \*Vattrlist \*L-member \*Vattrlist .sE .PP The \*Ladd\*O operation returns an attribute list with the attributes specified as the value of the required \%\*L-member\*O option appended. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lattrlist add\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lattrlist add {{a b} {c d}} -member {{e f} {g h}}\*C {a b} {c d} {e f} {g h} dcecp> .oE .SS "attrlist getvalues" .PP Returns the values of the attributes named in an attribute list. The syntax is as follows: .sS \*Lattrlist getvalues \*Vattrlist\*L -type \*Vtypename .sE .PP The \*Lgetvalues\*O operation returns the values of all attributes that are 1) named in the attribute list and 2) of the type specified by the required \%\*L-type\*O option. The value can be a single type, but if the attribute appears more than once in the attribute list, the value of each instance is returned on a separate line. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lattrlist getvalues\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lattrlist getvalues {{a w x} {c y} {a z} -type a\*C {w x} z dcecp> .oE .PP This command can be used to filter the output of \*Lshow\*O operations. For example: .oS dcecp> \*Lattrlist getvalues [dir show /.:/hosts] -type CDS_UTS\*C 1994-07-01-10:29:59.265-05:00I0.000/00-00-c0-f7-de-56 dcecp> .oE .PP With abbreviations, the above command could be entered as follows: .oS dcecp> \*Lat g [dir show /.:/hosts] -t CDS_UTS\*C 1994-07-01-10:29:59.265-05:00I0.000/00-00-c0-f7-de-56 dcecp> .oE .SS "attrlist help" .PP Returns help information about the \*Lattrlist\*O object and its operations. The syntax is as follows: .sS \*Lattrlist help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lattrlist\*O object. .LE .PP Used without an argument or option, the \*Lattrlist help\*O command returns brief information about each \*Lattrlist\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lattrlist\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lattrlist help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lattrlist help\*C add Adds attributes to a list. getvalues Returns the values of specified attributes. list Returns the attribute types present in a list. modify Modifies an attribute list. remove Removes attributes from a list. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "attrlist list" .PP Returns a list of attribute type names from an attribute list. The syntax is as follows: .sS \*Lattrlist list \*Vattrlist .sE .PP The \*Llist\*O operation returns a list of all the attribute type names in the attribute list in the order that they appear in the list. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lattrlist list\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lattrlist list {{a b} {c d}}\*C a c dcecp> .oE .SS "attrlist modify" .PP Removes and changes attributes and their values in an attribute list. The syntax is as follows: .sS ...\" .zA "Def,13377,R1.2.2,clarify syntax" \*Lattrlist modify \*Vattrlist .nL \*O{[\*L-add \*Vattribute_type attribute_values\*O] .nL [\*L-change \*Vattribute_type attribute_values\*O] .nL [\*L-remove \*Vattribute_type attribute_values\*O]} ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .sE .PP The \*Lmodify\*O operation returns an attribute list with attributes modified as specified by the \*L-add\*O, \*L-remove\*O and \%\*L-change\*O options. New attributes can be added, or new values added to existing attributes with \*L-add\*O. Entire attributes or attribute values can be removed with \*L-remove\*O. The \%\*L-change\*O option will remove all values from an existing attribute and replace them with new values specified. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lattrlist modify\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lattrlist modify {{a b} {c d}} -add {{c e}}\*C {a b} {c d e}\*C dcecp> dcecp> \*Lattrlist modify {{a b} {c d e}} -remove {{c e}} \*C {a b} {c d}\*C dcecp> dcecp> \*Lattrlist modify {{a b} {c d e}} -change {{c f}}\*C {a b} {c f}\*C dcecp> .oE .SS "attrlist operations" .PP Returns a list of the operations supported by the \*Lattrlist\*O object. The syntax is as follows: .sS \*Lattrlist operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lattrlist operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lattrlist operations\*C add getvalues list modify remove help operations dcecp> .oE .SS "attrlist remove" .PP Removes attributes and their values from an attribute list. The syntax is as follows: .sS \*Lattrlist remove \*Vattrlist\*L -member \*Vattrlist .sE .PP The \*Lremove\*O operation returns an attribute list after removing attribute types (and their values) specified as an argument to the required \%\*L-member\*O option. .PP This command removes only entire attributes; to remove specific values, use the \*Lattrlist modify\*O command. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lattrlist remove\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lattrlist remove {{a b} {c d} {e f} {g h}} -member {e g}\*C {a b} {c d} dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH aud 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "enh, CR10014, R1.1, add DCECP Object Reference Pages .iX "\*Ldcecp\*O commands" "\*Laud\*O" .iX "aud" "administering" .SH NAME .PP \*Laud\*O - A \*Ldcecp\*O object that manages the audit daemon on a DCE host. .SH "SYNOPSIS" .sS \*Laud disable\*O [\*Vremote_audit_daemon_name\*O] \*O \*Laud enable\*O [\*Vremote_audit_daemon_name\*O] \*Laud help \*O[\*Voperation\*O | \*L-verbose\*O] \*Laud modify \*O{\*L-change \*Vattribute_list\*L | \*Vattribute options\*O} .nL [\*Vremote_audit_daemon_name\*O] \*Laud operations\*O \*Laud rewind \*O[\*Vremote_audit_daemon_name\*O] \*Laud show\*O [\*Vremote_audit_daemon_name\*O] [\*L-attributes\*O] \*Laud stop\*O [\*Vremote_audit_daemon_name\*O] .sE .SH "DESCRIPTION" .PP The \*Laud\*O object represents the audit daemon (called \*Lauditd\*O in the reference implementation) on a host. The daemon creates audit trails on a single host. The administrative functions are limited to changing the state of the daemon (enabled, disabled, stopped), and changing the strategy used to deal with file system storage for the the audit trails. .PP This command operates on the audit daemon on the local host, unless the \*V_s(aud)\*O convenience variable is set. If set, the value is taken to be the name of an audit daemon's server entry, as found in the DCE namespace, or as a string binding; and that audit daemon is contacted to service the requests. An argument can also be given to these commands whose value is the same as that of the \*V_s(aud)\*O convenience variable. The argument takes precedence over the convenience variable. .SH "ARGUMENTS" .VL .LI "\*Voperation\*O" The name of one specific \*Laud\*O operation about which you want to see help information .LI "\*Vremote_audit_daemon_name\*O" By default, operations pertain to the local audit daemon. The optional argument \*Vremote_audit_daemon_name\*O specifies the name or the binding of one remote audit daemon to operate on. The name syntax is: .oS /.../\*Vcellname\*C/hosts/\*Vhostname\*C/auditd\*O .oE .PP A remote audit daemon can also be specified with a string binding for the remote host on which the audit daemon is running. Use a string binding such as .iS ncacn_ip_tcp:130.105.1.227\*O .iE Alternatively, you can specify the binding using \*Ldcecp\*O string syntax such as: .iS {ncacn_ip_tcp 130.105.1.227} .iE .LE .SH "ATTRIBUTES" .VL .LI "\*Lstostrategy {save | wrap}\*O" The audit trail storage strategy of the daemon. This attribute defines what the daemon will do if the audit trail storage is full. Its possible values are .VL .LI "\*Lsave\*O" If the specified trail size limit is reached (the default is 2 MB), \*Lauditd\*O saves the current trail file to a new file (this file has the same name as the original trail file, with the date and time appended). \*Lauditd\*O then deletes the contents of the original trail file, and continues auditing from the beginning of this file. This is the default value for \*Lstostrategy\*O. .LI "\*Lwrap\*O" The daemon will overwrite the old audit trails. .LE .LI "\*Lstate {enabled | disabled}\*O" Tells whether the audit daemon is accepting audit log requests or not. The values are \*Lenabled\*O or \*Ldisabled\*O. The default value for \*Lstate\*O is \*Lenabled\*O. .LE .PP See the \*VOSF DCE Administration Guide\*O for more information about audit attributes. .SH "OPERATIONS" .SS "aud disable" .PP Disables an audit daemon. The syntax is: .sS .nf \*Laud disable\*O [\*Vremote_audit_daemon_name\*O] .fi .sE .PP The \*Laud disable\*O operation disables the audit record logging service of an audit daemon. .PP The \*Lstate\*O attribute is changed to \*Ldisabled\*O. Returns an empty string on success. .PP \*LPrivilege Required\*O .PP You must have control (\*Lc\*O) permission on the audit daemon's ACL and be authenticated. .PP \*LExamples\*O .PP .iS \*Cdcecp> \*Laud disable \*O \*Cdcecp> .iE .SS "aud enable" .PP Enables an audit daemon. The syntax is: .sS .nf \*Laud enable\*O [\*Vremote_audit_daemon_name\*O] .fi .sE .PP The \*Laud enable\*O operation enables the audit record logging service of an audit daemon. .PP The \*Lstate\*O attribute is changed to \*Lenabled\*O. Returns an empty string on success. .PP \*LPrivilege Required\*O .PP You must have control (\*Lc\*O) permission on the audit daemon's ACL and be authenticated. .PP \*LExamples\*O .PP .iS \*Cdcecp> \*Laud enable \*O \*Cdcecp> .iE .SS "aud help" .PP Returns help information about the \*Laud\*O object and its operations. The syntax is: .sS \*Laud help [\*Voperation\*L | -verbose]\*O .sE .PP \*LOption\*O .VL .LI "\*L-verbose\*O" Displays more detailed information about the \*Laud\*O object. .LE .PP Used without an argument or option, the \*Laud help\*O command returns brief information about each \*Laud\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \*L-verbose\*O option for more detailed information about the \*Laud\*O object itself. .PP \*LPrivilege Required\*O .PP No special privileges are needed to use the \*Laud help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Laud help\*C disable Disables the audit daemon. enable Enables the audit daemon. modify Modifies the attributes of the audit daemon. rewind Rewinds the specified audit trail file to the beginning. show Returns the attributes for an audit daemon. stop Stops the audit daemon. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "aud modify" .PP Changes the values of audit attributes. The syntax is: .sS .nf \*Laud modify\*O {\*L-change \*Vattribute_list\*O | \*L-\*Vattribute_option\*O \*Vattribute_value\*O \.\.\.} .fi .sE .PP \*LOptions\*O .VL .LI "\*L-change \*Vattribute_list\*O" Allows you to specify attributes using an attribute list. See \*LExamples\*O. .iE .LI "\*L-\*Vattribute_option\*L \*Vattribute_value\*O" As an alternative to using the \*L-change\*O option with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. The \*L-change\*O option is intended for use in scripts when you can paste in lengthy attribute lists output by previous commands. The individual attribute options might be easier to use for interactive commands. .LE .PP The \*Laud modify\*O operation allows modification of the audit daemon attributes. Accepts the \*L\(hychange\*O option which takes an attribute list as a value. Also accepts the attribute options .nL \*L\(hystostrategy\*O and \*L\(hystate\*O. Returns an empty string on success. .PP \*LPrivilege Required\*O .PP You must have control (\*Lc\*O) permission on the audit daemon's ACL and be authenticated. .PP \*LExamples\*O .PP .iS \*Cdcecp> \*Laud modify -change {{stostrategy wrap} {state enabled}} \*Cdcecp> \*Cdcecp> \*Laud modify -stostrategy wrap -state enabled \*Cdcecp> .iE .SS "aud operations" .PP Returns a list of the operations supported by the \*Laud\*O object. The syntax is: .sS .nf \*Laud operations\*O .fi .sE .PP The \*Laud operations\*O operation takes no arguments, and returns a list of the available operations for the \*Laud\*O object. The order of the elements is alphabetical with the exception that \*Lhelp\*O and \*Loperations\*O are listed last. .PP \*LPrivilege Required\*O .PP No special privileges are needed to use the \*Laud operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Laud operations\*C disable enable modify rewind show stop help operations dcecp> .oE .SS "aud rewind" .P Rewinds the central audit trail file to the beginning. The syntax is: .sS \*Laud rewind\*O [\*Vremote_audit_daemon_name\*O] .sE .PP By default the central trail file is rewound to the beginning. Returns an empty string on success. .PP \*LPrivilege Required\*O .PP You must have control (\*Lc\*O) permission on the audit daemon's ACL and be authenticated. .PP \*LExamples\*O .PP .oS dcecp> \*Laud rewind\*C dcecp> .oE .SS "aud show" .P Returns the attribute list for the audit daemon. The syntax is: .sS \*Laud show\*O [\*L-attributes\*O] .sE .PP The \*Laud show\*O operation returns the attribute list for the audit daemon. The attributes are returned in lexical order. The \*L-attributes\*O option is provided for consistency with other \*Ldcecp\*O commands. It does not change the performance of the command. .PP \*LPrivilege Required\*O .PP You must have read (\*Lr\*O) permission on the audit daemon's ACL and be authenticated. .PP \*LExamples\*O .PP .oS \*Cdcecp> \*Laud show\*C {stostrategy wrap} {state enabled} \*Cdcecp> .oE .SS "aud stop" .PP Stops the audit daemon. The syntax is: .sS .nf \*Laud stop\*O [\*Vremote_audit_daemon_name\*O] .fi .sE .PP The \*Laud stop\*O operation stops the audit daemon process. Returns an empty string on success. .PP \*LPrivilege Required\*O .PP You must have control (\*Lc\*O) permission on the audit daemon's ACL and be authenticated. .PP \*LExamples\*O .PP .iS \*Cdcecp> \*Laud stop \*O \*Cdcecp> .iE .SH "RELATED INFORMATION" .PP Commands: \*L dcecp(1m), dcecp_audevents(1m), dcecp_audfilter(1m), dcecp_audtrail(1m), aud_audit_events(5), dts_audit_events(5), sec_audit_events(5), event_class(5). \*O .zZ "enh, CR10014, R1.1, add DCECP Object Reference Pages ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH audevents 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Laudevents\*O" .iX "audevents" "administering" .SH NAME .PP \*Laudevents\*O - A \*Ldcecp\*O object that lists audit events on a DCE host .SH "SYNOPSIS" .sS \*Laudevents catalog\*O .PP \*Laudevents help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Laudevents operations\*O .PP \*Laudevents show\*O \*Vevent_class_list\*O .sE .SH "ARGUMENTS" .VL .LI "\*Voperation\*O" The name of the \*Laudevents\*O operation for which to display help information. .LI "\*Vevent_class_list\*O" The name of one or more recognized event classes. Legal event classes can be viewed with the \*Lcatalog\*O operation. .LE .SH "DESCRIPTION" .PP The \*Laudevents\*O object represents the event classes that are recognized by an audit daemon on a host. Each event class is defined in an event class configuration file, and the filename is the symbolic name of the event class. .PP This command operates only on the audit daemon on the local host. .SH "OPERATIONS" .SS "audevents catalog" .PP Returns a list of the names of all event classes. The syntax is as follows: .sS \*Laudevents catalog\*O .sE .PP The \*Lcatalog\*O operation returns a list of the names of all event classes. It takes no arguments. The order returned is arbitrary. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the event class directory, \*Vdcelocal\*L/etc/audit/ec\*O. .PP \*LExamples\*O .PP .oS dcecp> \*Laudevents catalog\*C dce_audit_admin_modify dce_audit_admin_query dce_audit_filter_modify dce_audit_filter_query dce_dts_mgt_modify dce_dts_mgt_query dce_dts_synch dce_dts_time_provider dce_sec_authent dce_sec_control dce_sec_modify dce_sec_query dce_sec_server dcecp> .oE .SS "audevents help" .PP Returns help information about the \*Laudevents\*O object and its operations. The syntax is as follows: .sS \*Laudevents help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Laudevents\*O object. .LE .PP Used without an argument or option, the \*Laudevents help\*O command returns brief information about each \*Laudevent\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Laudevents\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Laudevents help\*O command. .PP \*LExamples\*O .PP .oS \*Cdcecp> \*Laudevents help\*C catalog Returns the list of event classes for an audit daemon. show Returns the contents of an event class. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "audevents operations" .PP Returns a list of the operations supported by the \*Laudevents\*O object. The syntax is as follows: .sS \*Laudevents operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Laudevents operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Laudevents operations\*C catalog show help operations dcecp> .oE .SS "audevents show" .PP Returns the contents of an event class. The syntax is as follows: .sS \*Laudevents show\*O \*Vevent_class_list\*O .sE .PP The \*Lshow\*O operation returns the contents of an event class. The argument is a list of names of event classes. For each named event class, \*Laudevents show\*O returns the event class name and the numbers of the events in the event class. (The numbers are 32 bit integers displayed in hex format.) .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the event class directory, \*Vdcelocal\*L/etc/audit/ec\*O. .PP \*LExamples\*O .PP .oS dcecp> \*Laudevents show dce_audit_filter_query\*C {dce_audit_filter_query 0x101 0x102} dcecp> dcecp> \*Laudevents show {dce_audit_filter_query dce_dts_time_provider}\*C {dce_audit_filter_query 0x101 0x102} {dce_dts_time_provider 0x211 0x212} dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad 1 \*Lauditd(1m)\*O, \*Ldcecp(1m)\*O, \*Ldcecp_aud(1m)\*O, \*Ldcecp_audfilter(1m)\*O, \*Ldcecp_audtrail(1m)\*O. .ad b ...\" .PP ...\" Commands: ...\" .ad l ...\" \*Laud(1m)\*O, ...\" \*Laudfilter(1m)\*O, ...\" \*Lauditd(1m)\*O, ...\" \*Laudtrail(1m)\*O, ...\" \*Ldcecp(1m)\*O. .PP Files: .ad 1 \*Laud_audit_events(5)\*O, \*Ldts_audit_events(5)\*O, \*Levent_class(5)\*O, \*Lsec_audit_events(5)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH audfilter 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Laudfilter\*O" .iX "audfilter" "administering" .SH NAME .PP \*Laudfilter\*O - A \*Ldcecp\*O object that manages the event filters on a DCE host .SH "SYNOPSIS" .sS \*Laudfilter catalog\*O .PP \*Laudfilter create \*Vaudit_filter_name_list\*L -attribute \*Vguide_name_list\*O .PP \*Laudfilter delete \*Vaudit_filter_name_list\*O .PP \*Laudfilter help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Laudfilter modify \*Vaudit_filter_name_list\*O .nL {[\*L-add \*Vguide_name_list\*O] .nL [\*L-remove \*Vguide_name_list\*O]} .PP \*Laudfilter operations\*O .PP \*Laudfilter show \*Vaudit_filter_name_list\*O .sE .SH "ARGUMENTS" .VL .LI "\*Vaudit_filter_name_list\*O A list of one or more names of audit event filters. A filter name consists of a filter type and possibly a key depending on the type. .PP The audit filter types are as follows: .VL 1.35i .LI "\*LType\*O" \*LKey\*O .LI "\*Lprincipal\*O" The key is a \*Vprincipal_name\*O. .LI "\*Lforeign_principal\*O" The key is a \*V/.../cellname/principal_name\*O. .LI "\*Lgroup\*O" The key is a \*Vgroup_name\*O. .LI "\*Lforeign_group\*O" The key is a \*V/.../cellname/group_name\*O. .LI "\*Lcell\*O" The key is a \*Vcell_name\*O. .LI "\*Lcell_overridable\*O" The key is a \*Vcell_name\*O. .LI "\*Lworld\*O" This type has no key. .LI "\*Lworld_overridable\*O" This type has no key. .LE .PP Examples of audit filter names are \*Lprincipal admin\*O, \*Lgroup dce\*O, and \*Lworld\*O. ...\" .zA "def,13377,def,R1.2,removed guide_name_list" ...\" .zZ " def,13377,R1.2,removed guide_name_list" .LI "\*Voperation\*O" The name of the \*Laudfilter\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Laudfilter\*O object represents audit event filters, which consists of a list of guides. Audit event filters are kept by the audit daemon and used to determine if an auditable event should be logged. An audit filter name consists of a filter type and possibly a key (dependent on the type). .PP This command operates on the audit daemon named by the \*L_s(aud)\*O convenience variable. If the variable is not set, the command operates on the audit daemon on the local host. .SH "DATA STRUCTURES" .PP Several \*Laudfilter\*O operations add and remove guide data that is stored in a filter. A guide specifies which action to take when a particular audit condition occurs. A single filter can contain multiple guides, each specifying various actions for different conditions. A guide is identified by a list of the three elements that make up the guide: audit conditions, audit actions, and event classes. Essentially, a guide specifies what (event classes) to audit, when (audit conditions), and how (audit actions). Note that event classes are definable by the administrator. .VL .LI "Audit conditions" The possible audit conditions are as follows: .VL .LI "\*Lsuccess\*O" Audit only if the event succeeded. .LI "\*Ldenial\*O" Audit only if the event failed due to access denials. .LI "\*Lfailure\*O" Audit only if the event failed due to other reasons. .LI "\*Lpending\*O" The outcome has not yet been determined. .LE .LI "Audit actions" The possible audit actions are as follows: .VL .LI "\*Lalarm\*O" Sends the audit record to the system console. ...\" .zA "1.1, CR13057" .LI "\*Lall\*O" Log the event and signal the alarm. If \*Lall\*O is set, the \*Lshow\*O operation returns the action \*Lall\*O, not \*L{log alarm all}\*O. ...\" .zZ "1.1, CR13057" .LI "\*Llog\*O" Logs the audit record either in the audit trail file of the Audit daemon or in a user-specified audit trail file. .LI "\*Lnone\*O" Takes no audit action. .LE .LE .SH "OPERATIONS" .PP ...\" .SS "audfilter catalog" .PP Returns a list of names of all filters in the audit daemon. The syntax is as follows: .sS \*Laudfilter catalog\*O .sE .PP The \*Lcatalog\*O operation returns a list of names of all filters maintained by the audit daemon. It takes no arguments. The names are a list of a type and if necessary a key. They are returned in an arbitrary order. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission on the audit daemon, and you must be authenticated. .PP \*LExamples\*O .PP .oS dcecp> \*Laudfilter catalog\*C {principal melman} {foreign_principal /.../cell_X/kevins} {group dce} world dcecp> .oE .SS "audfilter create" .PP Creates a new audit filter. The syntax is as follows: .sS \*Laudfilter create \*Vaudit_filter_name_list \*L-attribute \*Vguide_name_list\*O .sE .PP \*LOptions\*O .VL .LI "\*L-attribute \*Vguide_name_list\*O" Specifies a list of one or more guides to be added to the specified audit event filters that are created. A guide name consists of three elements: an event class, an audit condition, and an audit action. .PP See \*LDATA STRUCTURES\*O for more information about guide names. .LE .PP The \*Lcreate\*O operation creates a new audit filter. The argument is a list of names of audit filters to be created. Since a filter that has no guides will be removed by the audit daemon during a clean-up ("garbage collection") phase, this command requires an \%\*L-attribute\*O option whose value is a list of guides to be added to the specified audit filters on creation. All guides are added to all audit filters specified to be created. The operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission on the audit daemon, and you must be authenticated. .PP \*LExamples\*O .PP .oS dcecp> \*Laudfilter create {principal melman} -attribute {dce_sec_query denial log}\*C dcecp> .oE .SS "audfilter delete" .PP Deletes the filter including all filter guides. The syntax is as follows: .sS \*Laudfilter delete \*Vaudit_filter_name_list\*O .sE .PP The \*Ldelete\*O operation deletes the filter including all filter guides. The argument is a list of names of audit filters to be deleted. The operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission on the audit daemon, and you must be authenticated. .PP \*LExamples\*O .PP .oS dcecp> \*Laudfilter delete {principal jones}\*C dcecp> .oE .SS "audfilter help" .PP Returns help information about the \*Laudfilter\*O object and its operations. The syntax is as follows: .sS \*Laudfilter help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Laudfilter\*O object. .LE .PP Used without an argument or option, the \*Laudfilter help\*O command returns brief information about each \*Laudfilter\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Laudfilter\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Laudfilter help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Laudfilter help\*C catalog Returns the list of filters for an audit daemon. create Creates a new filter with specified guides. delete Deletes a filter and its associated guides. modify Adds or removes one or more guides of a filter. show Returns a list of guides in a specified filter. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "audfilter modify" .PP Adds or removes one or more guides of a filter. The syntax is as follows: .sS \*Laudfilter modify \*Vaudit_filter_name_list\*O .nL {[\*L-add \*Vguide_name_list\*O] .nL [\*L-remove \*Vguide_name_list\*O]} .sE \*LOptions\*O .VL .LI "\*L-add \*Vguide_name_list\*O" Specifies a list of one or more guides to be added to the specified audit event filters that are to be modified. A guide name consists of three elements: an audit condition, an audit action, and an event class. .PP See \*LDATA STRUCTURES\*O for more information about guide names. .LI "\*L-remove \*Vguide_name_list\*O" Specifies a list of one or more guides to be removed from the specified audit event filters that are to be modified. A guide name consists of three elements: an audit condition, an audit action, and an event class. .PP See \*LDATA STRUCTURES\*O for more information about guide names. .LE .PP The \*Lmodify\*O operation adds or removes one or more guides of a filter. The argument is a list of names of audit filters to be modified. In addition, the specific operation to perform is described with one or more of the following options: \%\*L-add\*O and \%\*L-remove\*O. The argument to both of these options is a list of guides. If more than one guide is specified, all guides are operated on, but \*Enot\*O atomically. If the last guide is removed from a filter, the filter will be deleted at some point by the audit daemon. .PP Atomicity of multiple actions is not guaranteed. .PP Similarly, the effect of adding a guide that partially exists in the specified filter is to "change" the existing guide(s). These changes guarantee that the semantics of the removal/addition are maintained. The operation returns an empty string on success .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission on the audit daemon, and you must be authenticated. .PP \*LExamples\*O .PP .oS dcecp> \*Laudfilter modify {principal jones} \e -add {dce_dts_mgt_modify failure alarm} \e -remove {dce_dts_mgt_query all log} \*C dcecp> .oE .SS "audfilter operations" .PP Returns a list of the operations supported by the \*Laudfilter\*O object. The syntax is as follows: .sS \*Laudfilter operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Laudfilter operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Laudfilter operations\*C catalog create delete modify show help operations dcecp> .oE .SS "audfilter show" .PP Returns a list of guides in a specified filter. The syntax is as follows: .sS \*Laudfilter show \*Vaudit_filter_name_list\*O .sE .PP The \*Lshow\*O operation returns a list of guides in a specified filter. The argument is a list of filter names (a filter type, and if needed, a key) to be shown. If more than one is entered, the output is concatenated and a blank line inseted between filters. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission on the audit daemon, and you must be authenticated. .PP \*LExamples\*O .PP .oS dcecp> \*Laudfilter show {principal rousseau} {dce_dts_mgt_modify failure alarm} {dce_dts_mgt_query all log} \*C dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad 1 \*Lauditd(1m)\*O, \*Ldcecp(1m)\*O, \*Ldcecp_aud(1m)\*O, \*Ldcecp_audevents(1m)\*O, \*Ldcecp_audtrail(1m)\*O. .ad b ...\" .ad l ...\" \*Laud(1m)\*O, ...\" \*Laudevents(1m)\*O, ...\" \*Lauditd(1m)\*O, ...\" \*Laudtrail(1m)\*O, ...\" \*Ldcecp(1m)\*O. .PP Files: .ad 1 \*Laud_audit_events(5)\*O, \*Ldts_audit_events(5)\*O, \*Levent_class(5)\*O, \*Lsec_audit_events(5)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH audtrail 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Laudtrail\*O" .iX "aud" "administering" .SH NAME .PP \*Laudtrail\*O - A \*Ldcecp\*O object that converts the audit trail into a readable format .SH "SYNOPSIS" .sS \*Laudtrail help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Laudtrail operations\*O .PP \*Laudtrail show \*Vaudit_trail_file_name_list\*O [\*L-to \*Vfilename\*O] .sE .SH "ARGUMENTS" .VL .LI "\*Vaudit_trail_file_name_list\*O" A list of one or more names of audit trail files. The names are not the full pathnames, but only the residual file name. .LI "\*Voperation\*O" The name of the \*Laudtrail\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Laudtrail\*O object represents an audit trail file. This command currently supports only one operation, which converts the audit trail into a human readable format. .SH "OPERATIONS" .SS "audtrail help" .PP Returns help information about the \*Laudtrail\*O object and its operations. The syntax is as follows: .sS \*Laudtrail help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Laudtrail\*O object. .LE .PP Used without an argument or option, the \*Laudtrail help\*O command returns brief information about each \*Laudtrail\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Laudtrail\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Laudtrail help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Laudtrail help\*C show Returns or files the contents of an audit trail file. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "audtrail operations" .PP Returns a list of the operations supported by the \*Laudtrail\*O object. The syntax is as follows: .sS \*Laudtrail operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Laudtrail operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Laudtrail operations\*C show help operations dcecp> .oE .SS "audtrail show" .PP Returns the audit trail in a readable format. The syntax is as follows: .sS \*Laudtrail show \*Vaudit_trail_file_name_list\*O [\*L-to \*Vfilename\*O] .sE \*LOptions\*O .VL .LI "\*L-to\*O \*Vfilename\*O" Specifies the name of the file in which to store the audit trail output. .LE .PP The \*Lshow\*O operation returns the audit trail in a readable format. This command takes as an argument a list of names of audit trail files. If more than one name is given, the output of each audit trail is concatenated and a blank line inserted between audit trails. The \%\*L-to\*O option specifies a destination filename for the trail. If this option is not present, the trail is returned from the command. If the option is present, this operation returns an empty string. .PP Because audit trail files can grow quite large, using the \*L-to\*O switch is strongly recommended to avoid reading the entire trail into memory. .PP Note that when \*Ldcecp\*O processes output, it sends the entire set of returned information to an internal buffer before it displays it. Therefore, when the output is directed to the screen, it can take a long time to appear. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission on the audit trail file on the local file system. .PP \*LExamples\*O .PP .oS dcecp> \*Laudtrail show my_trail\*C --- Start of an event record --- Event Number: 259 Client: /.../stp.gburg.ibm.com/hosts/drinkernisti/self Event Outcome: success Authorization Status: Authorized with a pac Local Time: 1993-12-19-19:02:27.037-05:00I----- --- End of an event record --- . . . --- Start of an event record --- Event Number: 256 Client: /.../stp.gburg.ibm.com/hosts/drinkernisti/self Event Outcome: success Authorization Status: Authorized with a pac Local Time: 1993-12-19-19:02:28.819-05:00I----- --- End of an event record --- dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Lauditd(1m)\*O, \*Ldcecp(1m)\*O, \*Ldcecp_aud(1m)\*O, \*Ldcecp_audevents(1m)\*O, \*Ldcecp_audfilter(1m)\*O. .ad l ...\" \*Laud(1m)\*O, ...\" \*Laudevents(1m)\*O, ...\" \*Lauditd(1m)\*O, ...\" \*Laudfilter(1m)\*O, ...\" \*Ldcecp(1m)\*O. .PP Files: \*Laud_audit_events(5)\*O, \*Ldts_audit_events(5)\*O, \*Levent_class(5)\*O, \*Lsec_audit_events(5)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" ...\" ...\" ...\" ...\" Copyright Hewlett-Packard Company 1992 ...\" ...\" .rm zA .rm zZ .TH cds "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .zA "1.2.1, new manpage" .iX "\*Ldcecp\*O commands" "\*Lcds\*O" .iX "cell directory server" "administering" .SH NAME \*Lcds\*O - A \*Ldcecp\*O object that represents a Cell Directory Service server .SH "SYNOPSIS" .sS \*Lcds disable \*Vserver_name\*O .nL \*Lcds help \*O[\*Voperation\*O |\*L -verbose\*O] .nL \*Lcds operations\*O .nL \*Lcds show \*Vserver_name\*O .sE .SH "ARGUMENTS" .VL .LI "\*Voperation\*O" The name of the \*Lcds\*O operation for which to display help information. .LI "\*Vserver_name\*O" The name of one CDS server running somewhere in the local cell. Specify the server name in one of the following formats: .iS \*L/.../\*Vcell_name\*L/hosts/\*Vhost_name\*L/cds-server\*O \*L/.:/hosts/\*Vhost_name\*L/cds-server\*O .iE .LE .SH "DESCRIPTION" .PP The \*Lcds\*O object allows some low-level control over a CDS server in the local cell. Using it you can disable a running server, which will cause it to shut down gracefully. This command will also display a limited set of the attribute and counter information currently known to the specified server. .PP .SH "ATTRIBUTES" .PP .VL .LI "\*LChild_Update_Failures\*O" The number of times the server failed to update a child replica. .LI "\*LCreation_Time\*O" The date-time stamp representing when the current server started. .LI "\*LCrucial_Replicas\*O" The number of crucial replicas known to the server. .LI "\*LFuture_Skew_Time\*O" The skew time allowed the server. .LI "\*LKnown_Clearinghouses\*O" The list of clearinghouses known to the server. .LI "\*LRead_Operations\*O" The number of read operations processed by the server since it started. .LI "\*LSecurity_Failures\*O" The number of times the CDS server had problems with the cell security service. .LI "\*LSkulks_Completed\*O" The number of skulks completed by the server since it started. .LI "\*LSkulks_Initiated\*O" The number of skulks initiated by the server since it started. .LI "\*LTimes_Lookup_Paths_Broken\*O" The number of times the lookup path was broken during a server operation. .LI "\*LWrite_Operations\*O" The number of write operations processed by the server since it started. .LE .SH "OPERATIONS" .PP .SS "cds disable" .PP Disables the specified CDS server. The syntax is as follows: .sS \*Lcds disable \*Vserver_name\*O .sE .PP The specified server must be running somewhere in the local cell, and you must have the privileges to access that machine. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Ldwc\*O (\*Ldelete\*O, \*Lwrite\*O, \*Lcreate\*O) permissions on the namespace entry of the server. .PP \*LExample\*O .PP .oS dcecp> \*Lcds disable /.:/hosts/blech/cds-server\*C dcecp> .oE .SS "cds help" .PP Returns help information about the \*Lcds\*O object and its operations. The syntax is as follows: .sS \*Lcds help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOption\*O .VL .LI "\*L-verbose\*O Displays information about the \*Lcds\*O object. .LE .PP Used without an argument or option, the \*Lcds help\*O command returns brief information about each \*Lcds\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \*L-verbose\*O option to display detailed information about the \*Lcds\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lcds help\*O command. .PP .PP \*LExamples\*O .PP .oS dcecp> \*Lcds help\*C disable Disables the specified CDS server. show Returns attribute information about the named CDS server. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .PP .SS "cds operations" .PP Returns a list of the operations supported by the \*Lcds\*O object. The syntax is as follows: .sS \*Lcds operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lcds operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lcds operations\*C disable show help operations dcecp> .SS "cds show\*O" .PP Returns attribute information about the specified CDS server. The syntax is as follows: .sS \*Lcds show \*Vserver_name\*O .sE .PP The attributes returned mostly represent counter information, which can be used to help isolate a problems with a CDS server. The order the attributes are returned is fixed within CDS. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permissions on the namespace entry of the server. .PP \*LExamples\*O .PP .oS dcecp> \*Lcds show /.:/hosts/blech/cds-server\*C {Creation_Time 1995-10-11-10:06:31.434-04:00I-----} {Future_Skew_Time 0} {Read_Operations 141384} {Write_Operations 3589} {Skulks_Initiated 278} {Skulks_Completed 278} {Times_Lookup_Paths_Broken 0} {Crucial_Replicas 0} {Child_Update_Failures 0} {Security_Failures 0} {Known_Clearinghouses /.../gumby1/blech_ch} dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad 1 \*Lcdsd(1m)\*O, \*Ldcecp(1m)\*O, \*Ldcecp_cdsclient(1m)\*O, \*Ldcecp_clearinghouse(1m)\*O, \*Ldcecp_directory(1m)\*O. .ad b ...\" .ad 1 ...\" \*Lcdsc(1m), ...\" \*Ldcecp(1m), ...\" \*Lcdsclient(1m), ...\" \*Lclearinghouse(1m), ...\" \*Ldirectory(1m).\*O ...\" .ad b ...\" .zZ "1.2.1, new manpage" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" .rm zA .rm zZ .TH cdsalias 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lcdsalias\*O" .iX "cdsalias" "administering" .SH NAME .PP \*Lcdsalias\*O - A \*Ldcecp\*O object that lets you manipulate cell names in CDS .SH "SYNOPSIS" ...\" .zA "def,13293,R1.2.1,remove set" .sS \*Lcdsalias catalog\*O .PP \*Lcdsalias connect\*O .PP \*Lcdsalias create \*Vcellalias_name\*O .PP \*Lcdsalias delete \*Vcellalias_name\*O .PP \*Lcdsalias help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lcdsalias operations\*O .PP ...\" \*Lcdsalias set \*Vcellalias_name\*O .sE ...\" .zZ "def,13293,R1.2.1,remove set" .SH "ARGUMENTS" .VL 1.25i .LI "\*Vcellalias_name\*O" A single, fully qualified alias name of the cell in the following form: .iS /.../\*Vcellalias_name\*O .iE .LI "\*Voperation\*O" The name of one specific \*Lcdsalias\*O operation about which you want to see help information. .LE .SH "DESCRIPTION" .PP The \*Lcdsalias\*O object represents cell names as known by the Cell Directory Service (CDS). This object lets you manipulate alias and preferred names of DCE cells. Each cell has one preferred name. Cells may also have alias names. Currently this object affects only the CDS component. The security server and each host must also be informed of any new cell aliases. .PP This object can also be used to define a hierarchical relation between one cell and another by connecting the first cell's root directory namespace into the the second cell's namespace. When defining a hierarchical relationship, you must use the \*Laccount\*O command to establish a trust relationship between the cells. .PP To manipulate alias and preferred names, the \*LCDS_DirectoryVersion\*O attribute must be set to 4.0 or greater. See the \*LATTRIBUTES\*O section of the \*Ldirectory\*O command for more information. ...\" .SH "ATTRIBUTES" ...\" .PP ...\" The \*Lcdsalias\*O object has no attributes. .SH "OPERATIONS" .SS "cdsalias catalog" .PP Returns a list of all defined cell aliases in CDS. The syntax is as follows: .sS \*Lcdsalias catalog\*O .sE .PP The \*Lcatalog\*O operation returns a list of all defined cell aliases in CDS. Each alias name is labeled either \*Lalias\*O or \*Lprimary\*O, depending on which name is the current preferred name. .PP \*LPrivileges Required\*O .PP Requires \*Lr\*O (\*Lread\*O) permission on the root directory of the cell. .PP \*LExamples\*O .PP .oS dcecp> \*Lcdsalias catalog\*C {CDS_CellAliases {Alias /.../green.cell.osf.org} {Primary /.../blue.cell.osf.org}} dcecp> .oE .SS "cdsalias connect" .PP Establishes a hierarchical relationship between two cells. The syntax is as follows: .sS \*Lcdsalias connect\*O .sE .PP The \*Lconnect\*O operation creates a hierarchical relationship between two cells. It takes no argument. The current preferred name of the cell is used and the last relative distinguished name (RDN) is removed to identify the parent cell. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP Requires \*La\*O (\*Lauth_info\*O) permission on the the local cell's root directory. Also, the CDS server principal on the machine containing the master replica of the local cell's root directory needs \*Li\*O (\*Linsert\*O) permission on the parent cell's root directory. .PP \*LExamples\*O .PP .oS dcecp> \*Lcdsalias connect\*C dcecp> .oE .SS "cdsalias create" .PP Creates a new alias cell name in CDS. The syntax is as follows: .sS \*Lcdsalias create \*Vcellalias_name\*O .sE .PP The \*Lcreate\*O operation creates a new alias cell name in CDS. The required argument is a single fully qualified alias name of the cell. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP Requires \*La\*O (\*Lauth_info\*O) permission on the root directory of the cell. .PP \*LExamples\*O .PP .oS dcecp> \*Lcdsalias create /.../green.cell.osf.org\*C dcecp> .oE .SS "cdsalias delete" .PP Deletes an existing alias cell name from CDS. The syntax is as follows: .sS \*Lcdsalias delete \*Vcellalias_name\*O .sE .PP The \*Ldelete\*O operation deletes an existing alias cell name from CDS. The required argument is a single fully qualified alias name of the cell. If the alias name does not exist, an error is returned. You cannot use this command to delete the preferred cell name. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP Requires \*La\*O (\*Lauth_info\*O) permission on the root directory of the cell. .PP \*LExamples\*O .PP .oS dcecp> \*Lcdsalias delete /.../green.cell.osf.org \*C dcecp> .oE .SS "cdsalias help" .PP Returns help information about the \*Lcdsalias\*O object and its operations. The syntax is as follows: .sS \*Lcdsalias help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lcdsalias\*O object. .LE .PP .ne 4 Used without an argument or option, the \*Lcdsalias help\*O command returns brief information about each \*Lcdsalias\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lcdsalias\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lcdsalias help\*O command. .PP \*LExamples\*O .PP ...\" .zA "def,13293,R1.2.1,remove set" .oS dcecp> \*Lcdsalias help\*C catalog Returns the aliases known by CDS for the named cell. connect Establishes a hierarchical relationship between two cells. create Creates the named cdsalias for the local cell. delete Deletes the existing cdsalias from the local cell. ...\" set Sets the named cdsalias as the primary for the local cell. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE ...\" .zZ "def,13293,R1.2.1,remove set" .SS "cdsalias operations" .PP Returns a list of the operations supported by the \*Lcdsalias\*O object. The syntax is as follows: .sS \*Lcdsalias operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lcdsalias operations\*O command. .PP \*LExamples\*O .PP ...\" .zA "def,13293,R1.2.1,remove set" .oS dcecp> \*Lcdsalias operations\*C catalog connect create delete help operations dcecp> .oE ...\" .SS "cdsalias set" ...\" .PP ...\" Sets the preferred name of the cell in CDS to an alias. ...\" .sS ...\" \*Lcdsalias set \*Vcellalias_name\*O ...\" .sE ...\" .PP ...\" The \*Lcdsalias set\*O command sets the preferred name of the cell ...\" to the alias named in the argument. The alias must have been previously ...\" created using the \*Lcdsalias create\*O operation. The required argument is a ...\" single fully qualified name of an existing cell alias. This ...\" command should be used only if the CDS and Security servers as ...\" well as each host in the cell know about the cell alias. ...\" .PP ...\" This operation returns an empty string on success. ...\" .PP ...\" \*LPrivileges Required\*O ...\" .PP ...\" Requires \*La\*O permission on the root directory of the ...\" cell. ...\" .PP ...\" \*LExamples\*O ...\" .PP ...\" .oS ...\" dcecp> \*Lcdsalias set /.../green.cell.osf.org\*C ...\" dcecp> ...\" .oE ...\" .zZ "def,13293,R1.2.1,remove set" .SH "RELATED INFORMATION" .PP .ad l Commands: \*Ldcecp(1m)\*O, \*Ldcecp_account(1m)\*O, \*Ldcecp_cellalias(1m)\*O, \*Ldcecp_directory(1m)\*O, \*Ldcecp_hostdata(1m)\*O. .ad b ...\" .ad l ...\" Commands: ...\" \*Ldcecp(1m)\*O, ...\" \*Laccount(1m)\*O, ...\" \*Lcellalias(1m)\*O, ...\" \*Ldirectory(1m)\*O, ...\" \*Lhostdata(1m)\*O. ...\" .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH cdscache 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lcdscache\*O" .iX "cdscache" "administering" .SH NAME .PP \*Lcdscache\*O - A \*Ldcecp\*O object that manages a local CDS cache .SH "SYNOPSIS" .PP .sS \*Lcdscache create \*Vserver_name_list\*L -binding \*Vserver_binding\*O .PP \*Lcdscache delete \*Vserver_name_list\*O .PP ...\" .zA "1.1?, add discard" \*Lcdscache discard \*Vserver_name\*O ...\" .zZ "1.1?, add discard" .PP \*Lcdscache dump \*O .PP \*Lcdscache help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lcdscache operations \*O .PP \*Lcdscache show \*Vserver_name_list\*O {\*L-server\*O | \*L-clearinghouse\*O} .sE .SH "ARGUMENTS" .VL .LI "\*Voperation\*O" The name of the \*Lcdscache\*O operation for which you want to see help information. .LI "\*Vserver_name\*O A single simple name for the cached server machine. A simple name is not a cell-relative name (such as \*L/.:/hosts/pelican/self\*O). Some examples of simple names are \*Lpelican\*O and \*Lhosts/pelican\*O. .LI "\*Vserver_name_list\*O A list of one or more simple names for the cached server machine. .LE .SH "DESCRIPTION" .PP The \*Lcdscache\*O object represents the Cell Directory Service (CDS) cache on the local node. The CDS cache contains information about servers and clearinghouses known to the local machine, and also contains user data about CDS entries that have been read. The \*Lcreate\*O and \*Ldelete\*O operations apply only to the server information. The \*Lshow\*O and \*Ldump\*O operations can display additional information. .SH "OPERATIONS" .SS "cdscache create" .PP Creates knowledge of a server in the local client's cache. The syntax is as follows: .sS \*Lcdscache create \*Vserver_name_list\*L -binding \*Vserver_binding\*O .sE .PP \*LOptions\*O .PP .VL .LI "\*L-binding\*O \*Vserver_binding\*O" The required \%\*L-binding\*O option lets you specify the binding information for a CDS server. This option takes a \*Vserver_binding\*O argument which is the protocol sequence and network address of the server node. The string format is as follows: .iS \*Vprotocol-sequence\*L:\*Vnetwork-address\*O .iE The TCL format is as follows: .iS {\*Vprotocol-sequence network-address\*L} .iE .PP A \*Vprotocol-sequence\*O is a character string identifying the network protocols used to establish a relationship between a client and server. There are two choices of protocol sequence, depending on the network address that is supplied in the binding: \*Lncacn_ip_tcp\*O or \*Lncadg_ip_udp\*O. For the \*Vnetwork-address\*O, specify an Internet address using the common Internet address notation. ...\" For more information about this format, see the \*(Dr. .LE .PP The \*Lcreate\*O operation creates knowledge of a server in the local client's cache. The \*Vserver_name_list\*O argument is a list of one or more simple names for the cached servers. (An example of a simple name would be \*Lpelican\*O, as opposed to a cell-relative name like \*L/.:/hosts/pelican/self\*O.) This command is typically used to manually provide configuration information to a client that cannot automatically configure itself. Manually providing configuration information can be required, for instance, to provide the client with addressing information about a server across a WAN. Once the client knows about one server, it can find other servers through referrals. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission to the client system. .PP \*LExamples\*O .PP The following command creates knowledge of the server \*Lpelican\*O in the local client's cache: .oS dcecp> \*Lcdscache create pelican -binding ncacn_ip_tcp:16.20.15.25\*C dcecp> .oE .SS "cdscache delete" .PP Removes knowledge of a server that you had specifically created from the local client's cache. The syntax is as follows: .sS \*Lcdscache delete \*Vserver_name_list\*O .sE .PP The \*Ldelete\*O operation removes knowledge of a server that you had specifically created from the local clients's cache. The required \*Vserver_name_list\*O argument is a list of one or more simple names given with the \*Lcdscache create\*O commmand. You can delete only servers that you have specifically created with the \*Lcdscache create\*O command. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission to the client system. .PP \*LExamples\*O .PP The following command removes knowledge of the server \*Lgumby\*O from the client cache: .oS dcecp> \*Lcdscache delete gumby\*C dcecp> .oE ...\" .zA "1.1?, add discard" .SS "cdscache discard" .PP Discards the contents of the client cache. The syntax is as follows: .sS \*Lcdscache discard [\*Vserver_name\*O] .sE .PP The \*Ldiscard\*O operation discards information cached in the client cache on the host specified by \*Vserver_name\*O. If you do not specify \*Vserver_name\*O, the operation discards the information from the client cache on the local host. Only a single server name can be specified. This operation returns an empty string on success. .PP To perform the operation, \*Lcdscache discard\*O: .AL .LI Brings down the client CDS. .LI Deletes a specific set of files. .LI Restarts the client CDS. .LE .PP During the process, all cached information is discarded. .PP \*LPrivileges Required\*O .PP You must have superuser (root) privileges on the client system. No CDS permissions are required. .PP \*LExamples\*O .PP The following command discards the contents of the client cache on the local host: .oS \*Cdcecp> \*Lcdscache discard\*C dcecp> .oE ...\" .zZ "1.1?, add discard" .SS "cdscache dump" .PP Displays the entire contents of the client cache. The syntax is as follows: .sS \*Lcdscache dump\*O .sE .PP The \*Ldump\*O operation displays the contents of the client cache on the screen. Use this command when solving CDS problems. .PP \*LPrivileges Required\*O .PP You must have superuser (root) privileges on the client system. No CDS permissions are required. .PP \*LExamples\*O .PP The following command will display the contents of the client cache on the screen (the output is not shown in the example): .oS dcecp> \*Lcdscache dump\*C dcecp> .oE .SS "cdscache help" .PP Returns help information about the \*Lcdscache\*O object and its operations. The syntax is as follows: .sS \*Lcdscache help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-verbose\*O" Displays information about the \*Lcdscache\*O object. .LE .PP Used without an argument or option, the \*Lcdscache help\*O command returns brief information about each \*Lcdscache\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lcdscache\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lcdscache help\*O command. .PP \*LExamples\*O .oS dcecp> \*Lcdscache help\*C create Adds information about named server in local cds cache. delete Removes information about named server from local cds cache. ...\" .zA "1.1?, add discard" discard Discards all cdsadv cache information on the specified host. ...\" .zZ "1.1?, add discard" dump Dumps all information from local cds cache. show Returns information stored in cds cache. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "cdscache operations" .PP Returns a list of the operations supported by the \*Lcdscache\*O object. The syntax is as follows: .sS \*Lcdscache operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lcdscache operations\*O command. .PP \*LExamples\*O .PP ...\" .zA "1.1?, add discard" .oS dcecp> \*Lcdscache operations\*C create delete discard dump show help operations dcecp> .oE ...\" .zZ "1.1?, add discard" .SS "cdscache show" .P Returns information about clearinghouses or servers stored in the cache. The syntax is as follows: .sS \*Lcdscache show \*Vserver_name_list\*O {\*L-server\*O |\*L -clearinghouse\*O} .sE .PP \*LOptions\*O .PP .VL .LI "\*L-clearinghouse\*O" This option displays all the names and values of the attributes in the specified cached clearinghouse. The following are valid attributes: .VL 1i .LI "\*LCreation Time\*O" Specifies the time at which this clearinghouse was added to the cache .LI "\*LMiscellaneous Operations\*O" Specifies the number of operations other than read and write (that is, skulks, new epochs, and so on) performed by this client on the cached clearinghouse .LI "\*LRead Operations\*O" Specifies the number of lookup operations of any sort performed by the client on the cached clearinghouse .LI "\*LTowers\*O" Specifies the protocol sequence and Internet address of the server that maintains the cached clearinghouse .LI "\*LWrite Operations\*O" Specifies the number of write operations performed by this client on the cached clearinghouse .LE .LI "\*L-server\*O" This option displays address information of a server in the local client's cache. The following attributes are valid: .VL .LI "\*LName\*O" The directory cell name .LI "\*LTowers\*O" The protocol sequence and network address of the server node .LE .LE .PP The \*Lshow\*O operation displays information about clearinghouses or servers stored in the cache. The required \*Vserver_name_list\*O argument is a list of one or more simple names of servers or CDS names of clearinghouses for which you want to display information. You must use one of the \%\*L-clearinghouse\*O or \%\*L-server\*O options to select the information you want to display. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the CDS client. .PP \*LExamples\*O .PP The following command displays all attributes of the cached clearinghouse \*L/.:/claire_ch\*O: .oS dcecp>\*L cdscache show /.:/claire_ch -clearinghouse\*C {CH_Name /.../blue.cell.osf.org/claire_ch} {Created 1994-10-07-11:41:23.131} {Others 458} {Reads 150221} {Tower {ncacn_ip_tcp 130.105.4.158}} {Tower {ncadg_ip_udp 130.105.4.158}} {Writes 162} dcecp> .oE .PP The following command displays all attributes of the cached server \*Ldrkstr\*O. .oS dcecp> \*Lcdscache show drkstr -server\*C {CH_Name /.../terrapin_cell.osf.org/drkstr_ch} {Tower {ncacn_ip_tcp 130.105.5.16}} {Tower {ncadg_ip_udp 130.105.5.16}} dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_directory(1m)\*O, \*Ldcecp_link(1m)\*O, \*Ldcecp_object(1m)\*O, \*Ldcecp_clearinghouse(1m)\*O. .ad b ...\" .ad l ...\" \*Ldcecp(1m)\*O, ...\" \*Ldirectory(1m)\*O, ...\" \*Llink(1m)\*O, ...\" \*Lobject(1m)\*O, ...\" \*Lclearinghouse(1m)\*O ...\" \*Lclear_cached_server(1m)\*O, ...\" \*Ldefine_cached_server(1m)\*O, ...\" \*Ldump_clerk_cache(1m)\*O, ...\" \*Lshow_cached_clearinghouse(1m)\*O, ...\" \*Lshow_cached_server(1m)\*O. ...\" .ad b ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\"Copyright Hewlett-Packard Company 1995 ...\" ...\" .rm zA .rm zZ .TH cdsclient "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .zA "1.2.1, new manpage" .iX "\*Ldcecp\*O commands" "\*Lcdsclient\*O" .iX "cell directory client" "administering" .SH NAME \*Lcdsclient\*O - A \*Ldcecp\*O object that represents a Cell Directory Service client .SH "SYNOPSIS" .sS \*Lcdsclient disable \*Vclient_name\*O .nL \*Lcdsclient help \*O[\*Voperation\*O | \*L-verbose\*O] .nL \*Lcdsclient operations\*O .nL \*Lcdsclient show \*Vclient_name\*O .sE .SH "DESCRIPTION" .PP The \*Lcdsclient\*O object allows some low-level control over a CDS client in the local cell. Using it you can disable a running client, which will shut down the client gracefully, and display a limited set of the attribute and counter information currently known to the client. .PP .SH "ARGUMENTS" .VL .LI "\*Vclient_name\*O" The name of one CDS client running somewhere in the local cell. Specify the client name using one of the formats: .iS \*L/.../\*Vcell_name\*L/hosts/\*Vhost_name\*L/cds-clerk\*O \*L/.:/hosts/\*Vhost_name\*L/cds-clerk\*O .iE .LI "\*V operation\*O" The name of the \*Lcdsclient\*O operation for which to display help information. .LE .SH "ATTRIBUTES" .PP .VL .LI "\*LAuthentication_Failures\*O" The number of authentication failures encountered by the client since it started. .LI "\*LCache_Bypasses\*O" The number of times the client bypassed the cache when looking for information. .LI "\*LCache_Hits\*O" The number of times the client used the cache when looking for information. .LI "\*LCreation_Time\*O" The date-time stamp representing when the current client started. .LI "\*LMiscellaneous_Operations\*O" The number of non-read, non-write operations processed by the client since it started. .LI "\*LProtocol_Errors\*O" The number of protocol errors encountered by the client since it started. .LI "\*LRead_Operations\*O" The number of read operations processed by the client since it started. .LI "\*LWrite_Operations\*O" The number of write operations processed by the client since it started. .LE .SH "OPERATIONS" .PP .SS "cdsclient disable" .PP Disables the specified CDS client. The syntax is as follows: .sS \*Lcdsclient disable \*Vclient_name\*O .sE .PP The specified client must be running somewhere in the local cell, and you must have the privileges to access that machine. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Ld\*O (\*Ldelete\*O), \*Lw\*O (\*Lwrite\*O), and \*Lc\*O (\*Lcreate\*O) permissions on the namespace entry of the clerk. .PP \*LExample\*O .PP .oS dcecp> \*Lcdsclient disable /.:/hosts/blech/cds-clerk\*C dcecp> .oE .SS "cdsclient help" .PP Returns help information about the \*Lcdsclient\*O object and its operations. The syntax is as follows: .sS \*Lcdsclient help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOption\*O .VL .LI "\*L-verbose\*O Displays information about the \*Lcdsclient\*O object. .LE .PP Used without an argument or option, \*Lcdsclient help\*O returns brief information about each \*Lcdsclient\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \*L-verbose\*O option to display detailed information about the \*Lcdsclient\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lcdsclient help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lcdsclient help\*C disable Disables the specified CDS client. show Returns attribute information about the named CDS client. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .PP .SS "cdsclient operations" .PP Returns a list of the operations supported by the \*Lcdsclient\*O object. The syntax is as follows: .sS \*Lcdsclient operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lcdsclient operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lcdsclient operations\*C disable show help operations dcecp> .SS "cdsclient show" .PP Returns attribute information about the specified CDS client. The syntax is as follows: .sS \*Lcdsclient show \*Vclient_name\*O .sE .PP The attributes returned mostly represent counter information, which can be used to help isolate a problems with a CDS client. The order the attributes are returned is fixed within CDS. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permissions on the namespace entry. .PP \*LExample\*O .PP .oS dcecp> \*Lcdsclient show /.:/hosts/blech/cds-server\*C {Creation_Time 1995-10-11-15:09:45.187-04:00I-----} {Protocol_Errors 0} {Authentication_Failures 0} {Read_Operations 78935} {Cache_Hits 55007} {Cache_Bypasses 23726} {Write_Operations 50} {Miscellaneous_Operations 53} dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad 1 \*L cdsadv(1m)\*O, \*L dcecp(1m)\*O, \*L dcecp_cds(1m)\*O, \*L dcecp_clearinghouse(1m)\*O, \*L dcecp_directory(1m)\*O. .ad b ...\" .ad 1 ...\" \*L cdsadv(1m)\*O , ...\" \*L dcecp(1m)\*O , ...\" \*L cds(1m)\*O , ...\" \*L clearinghouse(1m)\*O , ...\" \*L directory(1m)\*O . ...\" .ad b ...\" .zZ "1.2.1, new manpage" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" .rm zA .rm zZ .TH cell 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lgroup\*O" .iX "cell" "DCECP object" .SH NAME .PP \*Lcell\*O - A DCE control program task object that operates on a DCE cell .SH "SYNOPSIS" .sS \*Lcell backup \*O[\*Vcell_name\*O] .PP \*Lcell catalog\*O [\*Vcell_name\*O] .PP \*Lcell help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lcell operations\*O .PP ...\" .zA "Def,13377,R1.2.2,clarify syntax" \*Lcell ping \*O[\*Vcell_name\*O] [\*L-clients\*O] [\*L-replicas\*O] ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .PP \*Lcell show \*O[\*Vcell_name\*O] [\*L-simplename\*O] .sE .SH "ARGUMENTS" .VL .LI "\*Vcell_name\*O" The name of a single cell to operate on. The name must be a fully qualified cell name such as either of the following: .iS /.../\*Ltheir_cell.goodco.com /.:\*O .iE .LI "\*Voperation\*O" The name of the \*Lcell\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Lcell\*O task object represents a single DCE cell as a whole, including all machines, services, resources, principals, and so on. The optional \*Vcell_name\*O argument is a single cell name (not a list of cell names). If omitted the local cell (\*L/.:\*O) is the default. .SH "ATTRIBUTES" .PP .VL .LI "\*Lsecservers\*O" Each value is the name of a security server in the cell. .LI "\*Lcdsservers\*O" Each value is the name of a machine running a Cell Directory Service (CDS) server in the cell. The name is the simple name found under \*L/.:/hosts\*O. .LI "\*Ldtsservers\*O" Each value is the name of a Distributed Time Service (DTS) server in the cell. .LI "\*Lhosts\*O" Each value is the name of a host in the cell, including machines mentioned previously as servers; for example, \*Lhosts/machine1\*O. .LE .PP See the \*VOSF DCE Administration Guide\*O for more information about cell attributes. ...\" See the \*(Ag for more information about attributes. .SH "OPERATIONS" .SS "cell backup" Backs up the master security database and each clearinghouse with master replicas in the cell. The syntax is as follows: .sS \*Lcell backup \*O[\*Vcell_name\*O] .sE .PP The \*Lcell backup\*O command backs up the master security database and each clearinghouse with master replicas in the cell. It requires that \*Ldced\*O be running on each of the server hosts. It takes no arguments or options. ...\" .zA "amplify explanation" .PP Prepare a cell for regular backup operations by changing the access control lists (ACLs) on two of the \*Ldced\*O objects on the local machine and setting up an extended registry attribute (ERA) that can specify a backup destination (typically a tape archive). Then add the new attribute to the principals for the master DCE Security Service registry database and all CDS clearinghouses with master replicas that you want to back up. To do this, follow these steps: .AL .LI Put the DCE daemon into partial service mode by sending the \*Ldced\*O process the correct signal: .iS \*C#\*L kill -SIGUSR1 \*Vpid_of_dced \*C# .iE .LI Invoke \*Ldcecp\*O with the \%\*L-local\*O option: .iS \*C#\*L dcecp -local \*Cdcecp> .iE .LI Modify ACLs on the local \*Lhostdata\*O and \*Lsrvrconf\*O objects to allow the \*Lsubsys/dce/dced-admin\*O group access by using the following \*Ldcecp acl\*O operations: .oS dcecp> \*Lacl modify hostdata -add {group subsys/dce/dced-admin -riI} -local\*C dcecp> \*Lacl modify srvrconf -add {group subsys/dce/dced-admin -riI} -local\*C dcecp> \*Lacl modify srvrconf -add {group subsys/dce/dced-admin -d-rwx} -io -local\*C dcecp> .oE .LI Put the DCE daemon back into full service mode with the following command: .iS \*C# \*Lkill -SIGUSR1 \*Vpid_of_dced \*C# .iE ...\" .zZ "amplify explanation" .LI Create an ERA as a string that specifies a backup destination. Name the ERA \*L/.:/sec/xattrschema/bckp_dest\*O and the type \*Lprintstring\*O. Select the ACL manager named \*Lprincipal\*O and set its four permission bits to \*Lr\*O (read), \*Lm\*O (manage), \*Lr\*O (read), and \*LD\*O (Delete) as shown in the following command: .oS dcecp> \*Lxattrschema create /.:/sec/xattrschema/bckp_dest \\ \*C> \*L-encoding printstring -aclmgr {principal r m r D}\*C dcecp> .oE .LI Add the new ERA (\*Lbckp_dest\*O) to the principal \*Ldce-rgy\*O (the DCE Security Service registry database). Set the value to be the \*Ltar\*O filename or the device that is the backup destination, as follows: .oS dcecp> \*Lprincipal modify dce-rgy -add {bckp_dest \*Vtarfilename_or_device\*L}\*C dcecp> .oE .LI Add the new ERA (\*Lbckp_dest\*O) to the principal \*L/.:/hosts/\*Vhostname\*L/cds-server\*O (the CDS server). Set the value to be the \*Ltar\*O filename or the device that is the backup destination, as follows: .oS dcecp> \*Lprincipal modify /.:/hosts/\*Vhostname\*L/cds-server \\ \*C> \*L-add {bckp_dest \*Vtarfilename_or_device\*L} \*C dcecp> .oE .LE .PP Now, whenever you want to back up your registry database or CDS database, you can simply invoke a \*Lcell backup\*O command. .P You can back up another cell by including the cell name as an argument to the \*Lcell backup\*O command. Note that you need the necessary permissions in the remote cell. (Refer to the \*Lcell\*O object reference page for the required privileges.) This command returns an empty string on success. .PP \*LPrivileges Required\*O .PP The \*Lcell backup\*O command requires that the administrator be logged in as the local superuser (root). It also requires the user to be authenticated to the security service as the cell administrator. .PP \*LExamples\*O .oS dcecp> \*Lcell backup\*C dcecp> .oE .SS "cell catalog" .PP Lists the foreign cells that are known by the specified cell. The syntax is as follows: .sS \*Lcell catalog \*O[\*Vcell_name\*O] .sE .PP The \*Lcatalog\*O operation returns a list of the names of all cells currently registered in the specified cell. The list includes the name of the specified cell itself and of any registered foreign cells. If no \*Vcell_name\*O is provided, the operation returns cells registered in the local cell. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the \*L/.:/sec/principal\*O directory and \*Lr\*O (\*Lread\*O) permission to the specified cell principals. .PP \*LExamples\*O .PP .oS dcecp> \*Lcell catalog /.:\*C /.../gumby_cell /.../pokey_cell /.../barney_cell dcecp> .oE .nL .ne 4 .SS "cell help" .PP Returns help information about the \*Lcell\*O task object and its operations. The syntax is as follows: .sS \*Lcell help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lcell\*O task object. .LE .PP Used without an argument or option, the \*Lcell help\*O command returns brief information about each \*Lcell\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lcell\*O task object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lcell help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lcell help\*C backup Backs up master security database and master clearinghouses. catalog Returns the names of the cells known to a cell. ping Shows the current server status of the cell. show Shows attributes describing the configuration of a cell. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "cell operations" .PP Returns a list of the operations supported by the \*Lcell\*O task object. The syntax is as follows: .sS \*Lcell operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lcell operations\*O command. .PP \*LExamples\*O .PP .oS \*Cdcecp> \*Lcell operations\*C backup catalog ping show help operations dcecp> .oE .SS "cell ping" Performs quick checks to test whether a cell is running. The syntax is as follows: .sS ...\" .zA "Def,13377,R1.2.2,clarify syntax" \*Lcell ping \*O[\*Vcell_name\*O] [\*L-clients\*O] [\*L-replicas\*O] ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-clients\*O" This option causes the command to ping every machine in the cell. It does this by looping though \*L/.:/hosts\*O and doing a \*Lhost ping\*O on each host name. In case of failure, it generates an error and returns a list of hosts that could not be contacted. On success, it returns \*LDCE clients available\*O. .LI "\*L-replicas\*O" This option causes the command to ping the master security server, each security replica in the cell, all the CDS servers in the cell, and all the DTS servers in the cell. In case of failure, it generates an error and returns a list of servers that could not be contacted. On success, it returns \*LDCE servers available \*O. .LE .PP The \*Lping\*O operation performs a quick check to test whether a cell is running. .PP If called with no option it pings (using \*Lserver ping\*O) the master security server, the CDS server that currently holds the write copy of the the cell root directory (\*L/.:\*O), and all the DTS servers in the cell. In case of failure, it generates an error and returns a list of servers that could not be contacted. On success, it returns \*LDCE services available\*O. .PP The \%\*L-replicas\*O option causes the command to ping each security replica and CDS server as well as those mentioned above. In case of failure, it generates an error and returns a list of servers that could not be contacted. On success, it returns \*LDCE servers available\*O. .oE .PP The \%\*L-clients\*O option causes the command to ping every machine in the cell. It does this by looping though \*L/.:/hosts\*O and doing a \*Lhost ping\*O on the host name. In case of failure, it generates an error and returns a list of hosts that could not be contacted. On success, it returns \*LDCE clients available \*O. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to several directories in the CDS namespace. .PP \*LExamples\*O .PP The following example tests whether the core services master servers are available: .oS dcecp> \*Lcell ping /.../blue.cell.osf.org\*C DCE services available dcecp> .oE .PP The following example tests whether the core services and their replicas are available: .oS dcecp> \*Lcell ping -replicas\*C DCE servers available dcecp> .oE .PP The following example tests the presence of all DCE hosts in a cell: .oS dcecp> \*Lcell ping -clients\*C DCE clients available dcecp> .oE .SS "cell show" Returns attributes describing the configuration of the specified cell. The syntax is as follows: .sS \*Lcell show \*O[\*Vcell_name\*O] [\*L-simplename\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-simplename\*O" Returns the cell information without prepending the cell name. .LE .PP The \*Lshow\*O operation returns attributes describing the configuration of the specified cell. The returned attributes are as follows: .VL .LI "\*Lsecservers\*O" Each value is the name of a security server. .LI "\*Lcdsservers\*O" Each value is the name of a machine running a CDS server. The name is the simple name found under \*L/.:/hosts\*O. .LI "\*Ldtsservers\*O" Each value is the name of a DTS server in the cell. .LI "\*Lhosts\*O" Each value is the name of a host in the cell, including machines mentioned previously as servers; for example, \*Lhosts/machine1\*O. .LE .PP See the \*VOSF DCE Administration Guide\*O for more information about cell attributes. ...\" See the \*(Ag for more information about attributes. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to several directories in the CDS namespace. .PP \*LExamples\*O .PP .oS dcecp> \*Lcell show /.../dcecp.cell.osf.org\*C {secservers /.../dcecp.cell.osf.org/subsys/dce/sec/ice /.../dcecp.cell.osf.org/subsys/dce/sec/fire} {cdsservers /.../dcecp.cell.osf.org/hosts/frick} {dtsservers /.../dcecp.cell.osf.org/hosts/frick /.../dcecp.cell.osf.org/hosts/ice /.../dcecp.cell.osf.org/hosts/ninja} {hosts /.../dcecp.cell.osf.org/hosts/frick /.../dcecp.cell.osf.org/hosts/ice /.../dcecp.cell.osf.org/hosts/ninja} dcecp> dcecp> \*Ldcecp> cell show -simplename\*C {secservers subsys/dce/sec/ice} {cdsservers hosts/frick} {dtsservers hosts/frick hosts/ice hosts/ninja} {hosts hosts/frick hosts/ice hosts/ninja} dcecp> .oE .SH "RELATED INFORMATION" .PP .ad l Commands: \*Ldcecp(8dec)\*O, \*Ldcecp_directory(1m)\*O, \*Ldcecp_host(1m)\*O, \*Ldcecp_server(1m)\*O. .ad b ...\" .ad l ...\" Commands: ...\" \*Ldcecp(8dec0\*O, ...\" \*Ldirectory(1m)\*O, ...\" \*Lhost(1m)\*O, ...\" \*Lserver(1m)\*O. ...\" .ad b ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\"Copyright Hewlett-Packard Company 1992 ...\" ...\" ...\" .rm zA .rm zZ .TH cellalias "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .zA "1.2.1, new manpage" .iX "\*Ldcecp\*O commands" "\*Lcellalias\*O" .iX "cell alias" "administering" .SH NAME .P \*Lcellalias\*O - A \*Ldcecp\*O task object that manages cell name aliases .SH "SYNOPSIS" .sS \*Lcellalias\*O \*Lcatalog\*O .nL ...\" .zA "def,13377,R1.2.2,clarify syntax" \*Lcellalias\*O \*Lcreate\*O \*Vcell_alias_name\*O [\*L-force\*O] ...\" .zZ "def,13377,R1.2.2,clarify syntax" .nL \*Lcellalias help \*O[\*Voperation\*O | \*L-verbose\*O] .nL \*Lcellalias operations\*O ...\" .nL ...\" \*Lcellalias\*O \*Lset\*O [\*Valiasname\*O] [\*L-force\*O] .sE .SH "ARGUMENTS" .VL .LI "\*Vcell_alias_name\*O" A single fully qualified alias name for the cell alias in the form: .iS /.../\*Vcell_alias_name\*O .iE .LI "\*Voperation\*O" The name of the \*Lcellalias\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Lcellalias\*O task object allows you to create and display alternative names for cells, known as cell aliases. You can create multiple aliases for a single cell, but only one per \*Lcellalias\*O command. .PP When you create an alias, \*Lcellalias\*O: .AL .LI Creates a new principal to represent the cell alias in the registry. .LI Performs a \*Lregistry verify\*O operation to ensure that all Security replicas in the cell are up to date. .LI Creates the specified alias name in CDS using a \*Lcdsalias\*O operation. .LI Performs a \*Ldirectory synchronize\*O operation to ensure that all the CDS replicas are up to date. .LI Performs a \*Lhostdata\*O operation on each host in the cell for which you are creating the alias. .LI Updates all \*Ldced\*O objects and the \*Ldcelocal/dce_cf.db\*O and \*Ldcelocal/etc/security/pe_site\*O files to reflect the new alias name. (This action can take a long time to complete in a cell with many hosts.) .LE .PP ...\" .SH "ATTRIBUTES" ...\" .PP ...\" The \*Lcellalias\*O object has no attributes. .SH "OPERATIONS" .SS "cellalias catalog" .PP Returns a list of all cell alias names for the local cell. The syntax is: .sS \*Lcellalias catalog\*O .sE .PP In the list of cell alias names, the cell's primary name (the name that was assigned when the cell principal was created) is listed first. The alias names are listed after the primary name. .PP \*LPrivilege Required\*O .PP Requires \*Lr\*O (\*Lread\*O) permission on the root directory of the cell. .PP \*LExamples\*O .PP .oS dcecp> \*Lcellalias catalog\*C /.../gumby /.../pokey-alias\*C dcecp> .oE .SS "cellalias create" .PP Creates a new alias for the local cell. The syntax is: .sS ...\" .zA "def,13377,R1.2.2,clarify syntax" \*Lcellalias create \*Vcell_alias_name\*O [\*L-force\*O] ...\" .zZ "def,13377,R1.2.2,clarify syntax" .sE .PP \*LOption\*O .VL .LI "\*L-force\*O" Ignores errors encountered during execution. .LE .PP The required \*Vcell_alias_name\*O is a single fully qualified name. You must start \*Ldced\*O in remote-update mode with the \*L-r\*O option before you use \*Lcellalias create\*O. This operation returns an empty string on success. .PP \*LPrivilege Required\*O .PP Requires \*La\*O permission on the root directory of the cell. .PP \*LExamples\*O .PP .oS dcecp> \*Lcellalias create /.../green.cell.rainbow.com\*C dcecp> .oE .PP .SS "cellalias help" .PP Returns help information about the \*Lcellalias\*O task object and its operations. The syntax is: .sS \*Lcellalias help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOption\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lcellalias\*O task object. .LE .PP Used without an argument or option, the \*Lcellalias help\*O command returns brief information about each \*Lcell alias\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \*L-verbose\*O option to display detailed information about the \*Lcellalias\*O task object itself. .PP \*LPrivilege Required\*O .PP No special privileges are required to use the \*Lcellalias help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lcellalias help\*C catalog Returns the cell alias names currently in use. create Creates a new alias name for the local cell. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "cellalias operations" .PP Returns a list of the operations supported by the \*Lcellalias\*O task object. The syntax is as follows: .sS \*Lcellalias operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lcellalias operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lcellalias operations\*C catalog create help operations dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: ...\" .ad 1 ...\" \*Ldcecp(1m)\*O, ...\" \*Laccount(1m)\*O, ...\" \*Lcdsalias(1m)\*O, ...\" \*Ldirectory(1m)\*O, ...\" \*Lhostdata(1m)\*O, ...\" \*Lregistry(1m)\*O. ...\" .ad b .ad 1 \*Ldcecp(1m)\*O, \*Ldcecp_account(1m)\*O, \*Ldcecp_cdsalias(1m)\*O, \*Ldcecp_directory(1m)\*O, \*Ldcecp_hostdata(1m)\*O, \*Ldcecp_registry(1m)\*O. .ad b ...\" .zZ "1.2.1, new manpage" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH clearinghouse 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lclearinghouse\*O" .iX "clearinghouse" "administering" .SH NAME .PP \*Lclearinghouse\*O - A \*Ldcecp\*O object that manages a clearinghouse in CDS .SH "SYNOPSIS" .PP .sS ...\" .zA "1.1: added -simplename" \*Lclearinghouse catalog \*O[\*Vcell_name\*O] [\*L-simplename\*O] ...\" .zZ "1.1: added -simplename" .PP \*Lclearinghouse create \*Vclearinghouse_name_list\*O .PP \*Lclearinghouse delete \*Vclearinghouse_name_list\*O .PP \*Lclearinghouse disable \*Vclearinghouse_name_list\*O .PP \*Lclearinghouse help \*O[\*Voperation\*O | \*L-verbose\*O] .PP ...\" .zA "1.1, CR13079" \*Lclearinghouse initiate \*Vclearinghouse_name_list\*L -checkpoint\*O ...\" .zZ "1.1, CR13079" .PP \*Lclearinghouse operations\*O .PP ...\" .zA "1.1, CR13061" \*Lclearinghouse repair \*Vclearinghouse_name_list\*L -timestamps\*O ...\" .zZ "1.1, CR13061" .PP ...\" .zA "def,13377,R1.2.2, Clarify syntax" \*Lclearinghouse show \*Vclearinghouse_name_list .nL \*O[\*L-schema\*O | \*L-all \*O| [\*L-counters\*O] [\*L -attributes\*O]] ...\" .zZ "def,13377,R1.2.2, Clarify syntax" .PP ...\" .zA "1.1, CR13061" \*Lclearinghouse verify \*Vclearinghouse_name_list\*O ...\" .zZ "1.1, CR13061" .sE .SH "ARGUMENTS" .VL .LI "\*Vcell_name\*O" The name of a single cell. The name must be a fully qualified cell name as shown in either of the following: .iS \*L/.:\*O \*L/.../their_cell.goodco.com\*O .iE .LI "\*Vclearinghouse_name_list\*O" A list of one or more names of clearinghouses you want to operate on. A clearinghouse can be specified in either of the following forms: .iS \*L/.:/\*Vname_ch\*O \*L/.../\*Vcell_name\*L/\*Vname_ch\*O .iE .LI "\*Voperation\*O" The name of the \*Lclearinghouse\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Lclearinghouse\*O object represents Cell Directory Service (CDS) clearinghouses. Clearinghouses are databases located on CDS server machines that store data (directories, objects, and links) in CDS. On the server machines are files that contain the actual clearinghouse data. Clearinghouses are also represented in the CDS namespace by an entry that contains information about the clearinghouse. ...\" .zA "1.1, CR13079" ...\" .zA "1.1, CR13061" .PP You must run the \*Lcreate\*O operation on the host where you want to create the new clearinghouse and the \*Ldelete\*O, \*Ldisable\*O, \*Linitiate\*O, \*Lrepair\*O, and \*Lverify\*O operations on the host where the clearinghouse to be operated on resides. ...\" .zZ "1.1, CR13061" ...\" .zZ "1.1, CR13079" .PP ...\" If the \*L_s(cds)\*O convenience variable is set, it is treated as the ...\" name of a clearinghouse to contact for this operation. This is the only ...\" clearinghouse that will be contacted in an attempt to complete the ...\" operation. The \*Lclearinghouse\*O operations do not set the value of this variable ...\" after completion. .SH "ATTRIBUTES" .P The following are the CDS-defined attributes that may be present in CDS \*Lclearinghouse\*O objects: .VL .LI "\*LCDS_AllUpTo\*O" Indicates the date and time the clearinghouse object has been updated to reflect the \*LCDS_CHDirectories\*O attribute. .LI "\*LCDS_CHDirectories\*O" Specifies the full name and Universal Unique Identifier (UUID) of every directory that has a replica in this clearinghouse. .LI "\*LCDS_CHLastAddress\*O" Specifies the current reported network address of the clearinghouse. .LI "\*LCDS_CHName\*O" Specifies the full name of the clearinghouse. .LI "\*LCDS_CHState\*O" Specifies the state of the clearinghouse. The state \*Lon\*O indicates the clearinghouse is running and available. .LI "\*LCDS_CTS\*O" Specifies the creation timestamp (CTS) of the clearinghouse. .LI "\*LCDS_DirectoryVersion\*O" Specifies the current version of the directory in the clearinghouse in which the directory was created. .LI "\*LCDS_NSCellname\*O" Specifies the name of the cell in which the clearinghouse resides. .LI "\*LCDS_ObjectUUID\*O" Specifies the UUID of the clearinghouse. This read-only attribute is set by the system when the clearinghouse is created and cannot be modified by the user. .LI "\*LCDS_ReplicaVersion\*O" Specifies the current version of the replica in which the directory was created. The default is \*L3.0\*O. If an upgrade has taken place, the value will upgrade to \*L4.0\*O. .LI "\*LCDS_UpgradeTo\*O" A single-valued attribute used to control the upgrading of a clearinghouse from one version of CDS to another. By modifying this attribute, the process of upgrading a clearinghouse to a newer version of CDS may be initiated. .LI "\*LCDS_UTS\*O" Specifies the DTS-style, read-only timestamp of the most recent update to an attribute of the clearinghouse. The value is set by the system. .LE .SS "Counters" .VL .LI "\*Lcorruptions\*O" Specifies the number of times that a clearinghouse generated a \*Ldata corruption\*O event. .LI "\*Ldisables\*O" Specifies the number of times that the clearinghouse was disabled since it was last started. .LI "\*Lenables\*O" Specifies the number of times that the clearinghouse was enabled since it was last started, not including the initial startup. .LI "\*Lfailedupgrades\*O" Specifies the number of times that upgrades failed when using the \*LCDS-UpgradeTo\*O attribute. .LI "\*Lmissingentries\*O" Specifies the number of times the \*Lclearinghouse entry missing\*O event was generated. .LI "\*Lreads\*O" Specifies the number of read operations directed to this clearinghouse. .LI "\*Lreturnedrefs\*O" Specifies the number of requests directed to this clearinghouse that resulted in the return of a partial answer instead of satisfying the client's entire request. .LI "\*Lrootunreachables\*O" Specifies the number of times the \*Lroot lost\*O event was generated by the clearinghouse. .LI "\*Lskulkfailures\*O" Specifies the number of times that a skulk of a directory, initiated from this clearinghouse, failed to complete (usually because one of the replicas in the replica set was unreachable). .LI "\*Lwrites\*O" Specifies the number of write operations directed to this clearinghouse. .LE .PP See the \*VOSF DCE Administration Guide\*O for more information about clearinghouse attributes and counters. ...\" See the \*(Ag for more information about clearinghouse attributes and counters. .SH "OPERATIONS" .SS "clearinghouse catalog" ...\" .zA "1.1: added -simplename" .PP Returns a list of the names of all clearinghouses in a cell. The syntax is as follows: .sS \*Lclearinghouse catalog \*O[\*Vcell_name\*O] [\*L-simplename\*O] .sE \*LOption\*O .VL .LI \*L-simplename\*O Returns a list of clearinghouse names in a cell without prepending the cellname. .LE .PP The \*Lcatalog\*O operation returns a list of the names of all clearinghouses in a cell. If you do not specify the optional \*Vcell_name\*O argument, the cell name defaults to \*L/.:\*O. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lclearinghouse catalog\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lclearinghouse catalog\*C /.../dcecp.cell.osf.org/frick_ch dcecp> dcecp> \*Lclearinghouse catalog -simplename\*C frick_ch dcecp> .oE ...\" .zZ "1.1: added -simplename" .SS "clearinghouse create" .PP Creates a new clearinghouse on the local machine. The syntax is as follows: .sS \*Lclearinghouse create \*Vclearinghouse_name_list\*O .sE .PP The \*Lcreate\*O operation creates a new clearinghouse on the local machine. The \*Vclearinghouse_name_list\*O argument is a list of one or more names of the clearinghouses you want to create. Clearinghouses should only be named in the root directory (that is, \*L/.:\*O). This operation also stores a read-only replica of the root directory in the new clearinghouse. The process that creates the new clearinghouse initiates a skulk of the root directory, so all replicas of the root should be reachable when you enter the \*Lclearinghouse create\*O command. To ensure this, perform an immediate skulk of \*L/.:\*O prior to invoking the command, using the \*Ldirectory synchronize /.:\*O command. This operation returns an empty string on sucess. .PP \*LPrivileges Required\*O .PP You need \*Lw\*O (\*Lwrite\*O) permission to the server on which you intend to create the clearinghouse, and \*LA\*O (\*LAdmin\*O) permission to the cell root directory. The server principal needs \*Lr\*O (\*Lread\*O), \*Lw\*O (\*Lwrite\*O), and \*LA\*O (\*LAdmin\*O) permission to the cell root directory. .PP \*LExamples\*O .PP The following command creates a clearinghouse named \*L/.:/Boston_CH\*O on the local server system: .oS dcecp> \*Lclearinghouse create /.:/Boston_CH\*C dcecp> .oE .SS "clearinghouse delete" .PP Deletes the specified clearinghouse from the local machine. The syntax is as follows: .sS \*Lclearinghouse delete \*Vclearinghouse_name_list\*O .sE .PP The \*Ldelete\*O operation deletes the specified clearinghouse from the local server system. The \*Vclearinghouse_name_list\*O argument is a list of one or more names of the clearinghouses you want to delete. Clearinghouses that contain master replicas of directories are not deleted (and also return errors). This command also automatically deletes all read-only replicas from the clearinghouse; however, you should delete all read-only replicas by hand (see \*Ldirectory\*O \*Ldelete\*O \*L\%-replica\*O) before invoking this command since invoking many skulks will cause the command to execute more slowly. This operation returns an empty string on success. .PP CDS does not permit you to delete a disabled (cleared) clearinghouse. Before you can delete a disabled (cleared) clearinghouse, you must recreate it using the \*Lclearinghouse\*O \*Lcreate\*O command. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) and \*Ld\*O (\*Ldelete\*O) permission to the clearinghouse and \*LA\*O (\*LAdmin\*O) permission to all directories that store replicas in the clearinghouse. The server principal must have \*Ld\*O (\*Ldelete\*O) permission to the associated clearinghouse object entry and \*LA\*O (\*LAdmin\*O) permission to all directories that store replicas in the clearinghouse. .PP \*LExamples\*O .PP The following command deletes a clearinghouse named \*L/.:/Orion_CH\*O from the local server system: .oS dcecp> \*Lclearinghouse delete /.:/Orion_CH \*C dcecp> .oE .SS "clearinghouse disable" .PP Removes knowledge of the specified clearinghouse from the local server's memory. The syntax is as follows: .sS \*Lclearinghouse disable \*Vclearinghouse_name_list\*O .sE .PP The \*Ldisable\*O operation removes knowledge of the specified clearinghouse from the local server's memory. The \*Vclearinghouse_name_list\*O argument is a list of names of one or more clearinghouses you want to disable. Use this command when relocating a clearinghouse. This command removes the name of the prefix of the clearinghouse files from the \*L/opt/dcelocal/var/directory/cds/cds_files\*O file and notifies the local CDS server that the clearinghouse is disabled. The clearinghouse entry is not removed from the namespace, nor are the datafiles associated with the clearinghouse removed. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission to the CDS server on which the clearinghouse resides. .PP \*LExamples\*O .PP The following command disables the clearinghouse \*L/.:/Paris2_CH\*O so that it can be moved to another server: .oS dcecp> \*Lclearinghouse disable /.:/Paris2_CH \*C dcecp> .oE .SS "clearinghouse help" .PP Returns help information about the \*Lclearinghouse\*O object and its operations. The syntax is as follows: .sS \*Lclearinghouse help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-verbose\*O" Displays information about the \*Lclearinghouse\*O object. .LE .PP Used without an argument or option, the \*Lclearinghouse help\*O command returns brief information about each \*Lclearinghouse\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lclearinghouse\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lclearinghouse help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lclearinghouse help\*C catalog Returns the names of all clearinghouses in a cell. create Creates the named clearinghouse. delete Deletes the named clearinghouse. disable Disables the named clearinghouse. initiate Initiates an action on the named CDS clearinghouse. repair Repairs an aspect of the named CDS clearinghouse. show Returns the attributes of a clearinghouse. verify Verifies the consistency of the clearinghouse. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> ...\" .zA "1.1, CR13079" .SS "clearinghouse initiate" .PP Initiates a defined action on the specified clearinghouse on the local machine. The syntax is .sS \*Lclearinghouse initiate \*Vclearinghouse_name_list \*L-checkpoint\*O .sE .PP \*LOptions\*O .PP .VL .LI "\*L-checkpoint\*O" Forces the clearinghouse to checkpont to disk. .LE .PP The \*Linitiate\*O operation initiates a defined action on the specified clearinghouse. The required \*Vclearinghouse_name_list\*O argument is a list of one or more names of clearinghouses you want to initiate actions on. Currently, only a checkpoint action is available. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You need \*Lw\*O (\*Lwrite\*O) permission on the clearinghouse server and \*LA\*O (\*Ladmin\*O) permission on the cell root directory. The server principal needs \*LrwA\*L (*Lread\*O, \*Lwrite\*O, and \*Ladminister\*O) permission on the cell root directory. .PP \*LExamples\*O .PP The following command initiates a checkpoint operation on the clearinghouse named \*L/.:/oddball_ch\*O on the local system. .PP .oS dcecp> \*Lclearinghouse initiate /.:/oddball_ch -checkpoint\*C dcecp> .oE ...\" .zZ "1.1, CR13079" .SS "clearinghouse operations" .PP Returns a list of the operations supported by the \*Lclearinghouse\*O object. The syntax is as follows: .sS \*Lclearinghouse operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lclearinghouse operations\*O command. .PP \*LExamples\*O ...\" .zA "1.1, CR13079" ...\" .zA "1.1, CR13061" .PP .oS dcecp> \*Lclearinghouse operations\*C catalog create delete disable initiate repair show verify help operations dcecp> .oE ...\" .zZ "1.1, CR13061" ...\" .zZ "1.1, CR13079" ...\" .zA "1.1, CR13061" .SS "clearinghouse repair" .PP Repairs a specific problem on a specified clearinghouse on the local machine. The syntax is .sS \*Lclearinghouse repair \*Vclearinghouse_name_list \*L-timestamps\*O .sE .PP \*LOptions\*O .PP .VL .LI "\*L-timestamps\*O" Analyzes and repairs invalid timestamps found in a clearinghouse. .LE .PP Use the \*Lrepair\*O operation to fix various problems that can occur in a clearinghouse. The required \*Vclearinghouse_name_list\*O argument is a list of one or more names of clearinghouses you want to initiate repair actions on. Currently, only invalid timestamps can be repaired. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You need \*Lw\*O (\*Lwrite\*O) permission to the clearinghouse server and \*LA\*O (\*LAdmin\*O) permission to the cell root directory. The server principal needs \*Lr\*O (\*Lread\*O), \*Lw\*O (\*Lwrite\*O), and \*LA\*O (\*LAdmin\*O) permission to the cell root directory. .PP \*LExamples\*O .PP The following command repairs invalid timestamps in a clearinghouse named \*L/.:/blech_ch\*O on the local system. .PP .oS dcecp> \*Lclearinghouse repair /.:/blech_ch -timestamps\*C dcecp> .oE ...\" .zZ "1.1, CR13061" .SS "clearinghouse show" ...\" .zA "1.1: added -attributes" .P Returns attribute and counter information associated with the specified clearinghouses on local or remote machines. The syntax is as follows: .sS ...\" .zA "def,13377,R1.2.2, Clarify syntax" \*Lclearinghouse show \*Vclearinghouse_name_list .nL \*O[\*L-schema\*O | \*L-all \*O| [\*L-counters\*O] [\*L-attributes\*O]] ...\" .zZ "def,13377,R1.2.2, Clarify syntax" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-schema\*O" Indicates whether attributes are single-valued or multi-valued. .LI "\*L-all\*O" Returns the attributes and counters for the clearinghouse. .LI "\*L-attributes\*O" Returns the attributes for the clearinghouse. .LI "\*L-counters\*O" Returns the counters for the clearinghouse. .LE .PP The \*Lshow\*O operation displays attribute and counter information associated with the clearinghouses specified by \*Vclearinghouse_name_list\*O, which is a list of one or more names of the clearinghouses. If more than one clearinghouse is specified, the attributes of all the clearinghouses are concatenated into one list. The order of the returned attributes is the lexical order of the object identifiers (OIDs) of each attribute for each clearinghouse. .PP If you supply no options, \*Lclearinghouse show\*O returns the attributes associated with the specified clearinghouse. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the clearinghouse. ...\" If you specify a wildcard clearinghouse name, you also need \*Lr\*O ...\"(\*Lread\*O) permission to the cell root directory. .PP \*LExamples\*O .PP .oS dcecp> \*Lclearinghouse show /.:/drkstr_ch\*C {CDS_CTS 1994-06-18-20:16:22.150-05:00I0.000/00-00-c0-f7-de-56} {CDS_UTS 1994-06-19-17:17:43.911-05:00I0.000/00-00-c0-f7-de-56} {CDS_ObjectUUID 0066ccea-d978-1db3-8259-0000c0f7de56} {CDS_AllUpTo 1994-07-01-21:30:18.948-05:00I0.000/00-00-c0-f7-de-56} {CDS_DirectoryVersion 3.0} {CDS_CHName /.../terrapin/drkstr_ch} {CDS_CHLastAddress {Tower ncacn_ip_tcp 130.105.5.16} {Tower ncadg_ip_udp 130.105.5.16}} {CDS_CHState on} {CDS_CHDirectories {{Dir_UUID 00146037-d97b-1db3-8259-0000c0f7de56} {Dir_Name /.../terrapin}} {{Dir_UUID 0043797a-d991-1db3-8259-0000c0f7de56} {Dir_Name /.../terrapin/subsys}} {{Dir_UUID 004faa42-d992-1db3-8259-0000c0f7de56} {Dir_Name /.../terrapin/subsys/HP}} {{Dir_UUID 004fa65a-d993-1db3-8259-0000c0f7de56} {Dir_Name /.../terrapin/subsys/HP/sample-apps}} {{Dir_UUID 004b1130-d994-1db3-8259-0000c0f7de56} {Dir_Name /.../terrapin/subsys/dce}} {{Dir_UUID 00498a0e-d995-1db3-8259-0000c0f7de56} {Dir_Name /.../terrapin/subsys/dce/sec}} {{Dir_UUID 003ed80c-d996-1db3-8259-0000c0f7de56} {Dir_Name /.../terrapin/subsys/dce/dfs}} {{Dir_UUID 003d4d8e-d997-1db3-8259-0000c0f7de56} {Dir_Name /.../terrapin/hosts}} {{Dir_UUID 003bc522-d998-1db3-8259-0000c0f7de56} {Dir_Name /.../terrapin/hosts/drkstr}} {{Dir_UUID 0089ee8c-44e0-1dbe-929b-0000c0f7de56} {Dir_Name /.../terrapin/help}} {{Dir_UUID 001c6cea-00fb-1dc5-929b-0000c0f7de56} {Dir_Name /.../terrapin/test_1}} {{Dir_UUID 00440fe8-02a1-1dc5-929b-0000c0f7de56} {Dir_Name /.../terrapin/dirmod}}} {CDS_ReplicaVersion 3.0} {CDS_NSCellname /.../terrapin} dcecp> .oE .PP .oS dcecp> \*Lclearinghouse show /.:/Chicago1_CH -counters\*C {corruptions 0} {disables 0} {enables 1} {failedupgrades 0} {missingentries 0} {reads 2336} {returnedrefs 2} {rootunreachables 0} {skulkfailures 0} {writes 68} dcecp> .oE ...\" .zZ "1.1: added -attributes" ...\" .zA "1.1, CR13061" .SS "clearinghouse verify" .PP Verifies the consistency of the specified clearinghouse on the local machine. The syntax is .sS \*Lclearinghouse verify\*O \*Vclearinghouse_name_list\*O .sE .PP The \*Lverify\*O operation verifies the consistency of the specified clearinghouse by checking internal attributes. The required \*Vclearinghouse_name_list\*O argument is a list of one or more names of clearinghouses you want to verify. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You need \*Lw\*O (\*Lwrite\*O) permission to the clearinghouse server and \*LA\*O (\*LAdmin\*O) permission to the cell root directory. The server principal needs \*Lr\*O (\*Lread\*O), \*Lw\*O (\*Lwrite\*O), and \*LA\*O (\*LAdmin\*O) permission to the cell root directory. .PP \*LExamples\*O .PP The following command verifies the consistency of clearinghouses named \*L/.:/gumby_ch\*O and \*L/.:/pokey_ch\*O. .PP .oS dcecp> \*Lclearinghouse verify {\*L/.:/gumby_ch\*O \*L/.:/pokey_ch\*O}\*C dcecp> .oE ...\" .zZ "1.1, CR13061" .SH "RELATED INFORMATION" .PP Commands: .ad 1 \*Lcdsd(1m) \*Ldcecp(1m)\*O, \*Ldcecp_cdscache(1m)\*O, \*Ldcecp_directory(1m)\*O, \*Ldcecp_link(1m)\*O, \*Ldcecp_object(1m)\*O. .ad b ...\" .ad l ...\" \*Lcdsd(1m)\*O, ...\" \*Lcdscache(1m)\*O, ...\" \*Ldcecp(1m)\*O, ...\" \*Ldirectory(1m)\*O, ...\" \*Llink(1m)\*O, ...\" \*Lobject(1m)\*O. ...\" .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH clock 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lclock\*O" .iX "clock" "administering" .SH NAME .PP \*Lclock\*O - A \*Ldcecp\*O object that manages the clock on a local or remote host .SH "SYNOPSIS" .sS \*Lclock compare \*O[\*Vdts_entity\*O] [\*L-server \*Vdts_entity\*O] .PP \*Lclock help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lclock operations\*O .PP \*Lclock set \*O[\*Vdts_entity\*O] .PP ...\" .zA "def,13377,R1.2.2, Clarify syntax" ...\" .zA "1.2.1 add -bypass option" ...\" [\*L-abruptly -epoch\*O \*Vepoch_number\*L] | ...\" REPLACE ABOVE LINE WITH FOLLOWING: {\*L-to \*VDTS_timestamp\*O [\*L-abruptly -epoch \*Vepoch_number\*O] [\*L-bypass\*O] | ...\" .zZ "1.2.1 add -bypass option" ...\" .zZ "def,13377,R1.2.2, Clarify syntax" .PP ...\" -epoch \*Vepoch_number\*O} ...\" REPLACE ABOVE LINE WITH FOLLOWING: \*L-epoch \*V epoch_number\*O} .PP ...\" .zA "def,13377,R1.2.2, Clarify syntax" ...\" .zA "1.2.1 addition" \*Lclock show \*O[\*Vdts_entity\*O] [\*L-dtsd \*O | \*L-inetd\*O | \*L-dced\*O] ...\" .zZ "1.2.1 addition" ...\" .zZ "def,13377,R1.2.2, Clarify syntax" .PP ...\" \*Lclock synchronize \*O[\*Vdts_entity\*O] [\*L-abruptly\*O] ...\" REPLACE ABOVE LINE WITH FOLLOWING: ...\" .zA "def,13377,R1.2.2, Clarify syntax" ...\" .zA "1.2.1" \*Lclock synchronize \*O[\*Vdts_entity\*O] [[\*L-abruptly\*O] [\*L-dtsd\*O | \*L-inetd \*O| \*L-dced\*O] ...\" .zZ "1.2.1" ...\" .zZ "def,13377,R1.2.2, Clarify syntax" .sE .SH "ARGUMENTS" .VL .LI "\*Vdts_entity\*O" ...\" .zA "1.1, CR13084" Identifies the \*Ldtsd\*O server or clerk to act on. .PP With the \*L-server\*O option in the \*Lcompare\*O operation, \*Vdts_entity\*O can identify a DTS time provider. .PP When used without the \*L-dced\*O or \*L-initd\*O options, \*Ldts_entity\*O can be either of the following: .ML .LI The name of a \*Ldtsd\*O server, which can be on a remote host, in the format: .iS /.../\*Vcellname\*L/hosts/\*Vhostname\*L/dts-entity\*O .iE .LI As string binding for the remote host on which the \*Ldtsd\*O is running, such as: .iS {ncacn_ip_tcp 130.105.1.227} .iE .PP Alternatively you can specify the binding in \*Ldcecp\*O string format, such as: .iS ncacn_ip_tcp:130.105.1.227 .iE .LE .PP When used with the \*L-dced\*O or \%\*L-inetd\*O options, \*Vdts_entity\*O identifies the server by a simple host name in the form \*Vhostname\*O. .LI "\*Voperation\*O" The name of the \*Lclock\*O operation for which to display help information. .LE .SH "DESCRIPTION" The \*Lclock\*O object represents the clock on a system, and the time that it tells. This object has commands to display and set the time. ...\" .zA "1.2.1" The time setting functionality is provided by DTS, unless you specify either the \*L-dced\*O or \%\*L-inetd\*O option. The optional argument to the \*Lclock\*O command is the name of a DCE Version 1.1 \*Ldtsd\*O running on some ...\" .zZ "1.2.1" machine. Without an argument the \*L_s(dts)\*O convenience variable is ...\" .zA "1.1, CR13084" checked. If this variable is not set, the command operates on the clock on the local machine. ...\" .zZ "1.1, CR13084" .PP Use the \*L-epoch\*O option to change only the epoch number of the \*Ldtsd\*O. .SH "OPERATIONS" ...\" .zA "1.1: moved" .SS "clock compare" .PP Returns the difference between the clocks on the local machine and a time-provider in the cell. The syntax is as follows: .sS \*Lclock compare \*O[\*Vdts_entity\*O] [\*L-server \*Vdts_entity\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-server\*O \*Vdts_entity\*O" Optionally names a specific time-provider or a remote DTS server against which to compare the host clock. .PP See \*LARGUMENTS\*O for the format of the \*Vdts_entity\*O argument. .LE .PP The \*Lcompare\*O operation returns the difference between the clocks on the local machine and a time-provider in the cell. If a time-provider is not running and a server is not specified, the command will pick the last responding server returned by \*Ldts catalog\*O. An optional argument compares a remote host's clock against a time-provider. An optional \%\*L-server\*O option compares the clock against a specific time-provider. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission on the pertinent DTS entities to execute the command. .PP \*LExamples\*O .PP .oS dcecp> \*Lclock compare\*C {server /.:/gumby/hosts/oddball/dts_entity} {provider no} {skew -0-00:00:00.020I-----} dcecp> .oE ...\" .zZ "1.1: moved" .SS "clock help" .PP Returns help information about the \*Lclock\*O object and its operations. The syntax is as follows: .sS \*Lclock help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lclock\*O object. .LE .PP Used without an argument or option, the \*Lclock help\*O command returns brief information about each \*Lclock\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lclock\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lclock help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lclock help\*C compare Returns the difference between the local clock and a server. set Sets the system clock to the specified time. show Returns the current time as a DTS style timestamp. synchronize Synchronizes the local clock with the specified server. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "clock operations" .PP Returns a list of the operations supported by the \*Lclock\*O object. The syntax is as follows: .sS \*Lclock operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lclock operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lclock operations\*C compare set show synchronize help operations \*Cdcecp> .oE .SS "clock set" .PP Sets the clock to the specified time. The syntax is as follows: .sS ...\" .zA "def,13377,R1.2.2, Clarify syntax" \*Lclock set \*O[\*Vdts_entity\*O] .nL {\*L-to \*VDTS_timestamp\*O [\*L-abruptly -epoch\*O \*Vepoch_number\*O] [\*L-bypass\*O] | .nL ...\" .zA "1.2.1 add -bypass option" ...\[\*L-abruptly -epoch \*Vepoch_number\*L] [-bypass] | ...\" .zZ "1.2.1 add -bypass option" \*L-epoch \*Vepoch_number\*O} ...\" .zZ "def,13377,R1.2.2, Clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-to \*VDTS_timestamp\*O" This option specifies a DTS timestamp as the time to which to set the clock. You can specify the time in the ISO compliant time format, as follows: .iS \*VCCYY\*L-\*VMM\*L-\*VDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*L.\*Vfff .iE .LI "\*L-abruptly\*O" Specifies to set the clock abruptly rather than gradually adjust it to the computed time. ...\" .zA "1.1, CR13084" .LI "\*L-bypass\*O" Sets the system clock to the specified time without using DTS. ...\" .zZ "1.1, CR13084" .LI "\*L-epoch \*Vepoch_number\*O" Specifies an \*Vepoch_number\*O that matches the epochs of servers with which the local clock synchronizes. .LE ...\" .zA "1.1, CR13084" .PP The \*Lset\*O operation sets the local clock to the specified time. An optional argument specifies to set the clock on a remote host. The \%\*L-to\*O option specifies a DTS timestamp as the time to which to set the clock. If you do not specify the \%\*L-bypass\*O option, DTS adjusts the clock gradually to the specified time. The \%\*L-abruptly\*O option changes to the specified time, without gradual adjustments. If you specify the \%\*L-abruptly\*O option, you must also specify the \%\*L-epoch\*O option to indicate a new epoch. You can also use the \%\*L-epoch\*O option without specifying a time to pull the specified \*Ldts_entity\*O out of synchronization. This operation returns an empty string on success. .PP Note that setting your system clock is a dangerous operation. If your machine is not synchronized with other machines in the cell, other DCE services, especially CDS, will not operate correctly. See the \*VOSF DCE Administration Guide\*O for more information about DTS. ...\" .zZ "1.1, CR13084" .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission on the clock object in order to execute the command. .PP \*LExamples\*O .PP ...\" .zA "1.1, CR13084" .oS dcecp> \*Lclock set -to 1994-07-15-16:27:28.000-04:00 -abruptly -epoch 1\*C dcecp> dcecp> \*Lclock set -epoch 5\*C dcecp> .oE ...\" .zZ "1.1, CR13084" .SS "clock show" .P Returns a DTS-style timestamp including the time differential factor (TDF). The syntax is as follows: .sS ...\" .zA "1.2.1 addition" ...\" .zA "def,13377,R1.2.2, Clarify syntax" \*Lclock show \*O[\*Vdts_entity\*O] [\*L-dtsd\*O | \*L-inetd \*O| \*L-dced\*O] ...\" .zZ "def,13377,R1.2.2, Clarify syntax" ...\" .zZ "1.2.1: add options" .sE ...\" .zA "1.2.1: add options" .PP \*LOptions\*O .VL .LI "\*L-dced\*O" Use \*Ldced\*O services instead of DTS to report the time. .LI "\*L-inetd\*O" Use \*Linetd\*O socket connections instead of DTS to report the time .LI "\*L-dtsd\*O" Use DTS services to report the time. .LE ...\" .zZ "1.2.1: add options" .PP The \*Lshow\*O operation returns a DTS style timestamp with the TDF indicated. Use the \*Vdts_entity\*O argument to specify a remote host on which to show the clock. ...\" .zA "1.2.1: add options" .PP Two options let you specify that the time should be returned without using DTS services: .ML .LI The \%\*L-dced\*O option specifies that \*Ldced\*O services should be used instead of DTS services .LI The \*L-inetd\*O option specifies that \*Linetd\*O socket connections should be used instead of DTS .LE .PP ...\" .zZ "1.2.1: add options" .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission on the clock object in order to execute the command. .PP \*LExamples\*O ...\" .zA "1.1, CR13084" .PP .oS dcecp> \*Lclock show\*C 1994-07-15-16:28:02.229+00:00I----- dcecp> dcecp> \*Lclock show oddball -dced\*C 1994-07-16-17:29:05.321+00:00I----- dcecp> .oE ...\" .zZ "1.1, CR13084" .SS "clock synchronize" .PP Causes \*Ldtsd\*O to synchronize gradually with time-providers. The syntax is as follows: .sS ...\" \*Lclock synchronize \*O[\*Vdts_entity\*O] [\*L-abruptly\*O] ...\" REPLACE ABOVE LINE WITH FOLLOWING: ...\" .zA "1.2.1: add options" ...\" .zA"def,13377,R1.2.2, Clarify syntax" \*Lclock synchronize \*O[\*Vdts_entity\*O] [[\*L-abruptly\*O] [\*L-dtsd\*O] |\*L -inetd\*O | \*L-dtsd\*O] ...\" .zZ "def,13377,R1.2.2, Clarify syntax" ...\" .zZ "1.2.1: add options" .sE ...\" .zA "1.2.1: add options" .PP \*LOptions\*O .VL .LI "\*L-abruptly\*O" Causes the clock to be set abruptly rather than gradually adjusted to the computed time. .LI "\*L-dced\*O" Use \*Ldced\*O services instead of DTS as the time source. .LI "\*L-inetd\*O" Use \*Linetd\*O socket connections instead of DTS as the time source. .LI "\*L-dtsd\*O" Use DTS services as the time source. .LE ...\" .zZ "1.2.1: add options" .PP The \*Lsynchronize\*O operation causes the local \*Ldtsd\*O to gradually synchronize the local clock with the time from DTS time-providers. The \%\*L-abruptly\*O option changes to the specified time immediately, without gradual adjustments. ...\" .zA "1.2.1: add options" .PP By default, the time is retrieved from DTS. If the \%\*L-dced\*O option is specified, the time is retrieved from \*Ldced\*O services. If the \*L-inetd\*O option is specified, the time is retrieved from \*Linetd\*O socket connections. ...\" .zZ "1.2.1: add options" The optional \*Vdts_entry\*O argument synchronizes the clock on the named remote host.\*O This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission on the clock object in order to execute the command. .PP \*LExamples\*O .PP .oS dcecp> \*Lclock synchronize\*C dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldts(1m)\*O, \*Ldtsd(1m)\*O, \*Ldcecp_dts_intro(1m)\*O, \*Ldcecp_utc(1m)\*O. .ad b ...\" .ad l ...\" \*Ldcecp(1m)\*O, ...\" \*Ldts(1m)\*O, ...\" \*Ldtsd(1m)\*O, ...\" \*Ldts_intro(1m)\*O, ...\" \*Lutc(1m)\*O. ...\" .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH directory 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Ldirectory\*O" .iX "directory" "administering" .SH NAME .PP \*Ldirectory\*O - A \*Ldcecp\*O object that manages a name service directory .SH "SYNOPSIS" .PP .sS \*Ldirectory add \*Vdirectory_name_list\*L -member \*Vchild_pointer_list\*L .nL -clearinghouse \*Vclearinghouse_name\*L .PP ...\" .zA "DMA Clarify syntax" \*Ldirectory create \*Vdirectory_name_list\*L .nL \*O[\*L-attribute \*Vattribute_list\*O [\*L-single\*O]] .nL [[\*L-replica\*O] \*L-clearinghouse \*Vclearinghouse_name\*O]] .nL ...\" .zZ "DMA Clarify syntax" .PP \*Ldirectory delete \*Vdirectory_name_list\*O .nL ...\" [[\*L-tree\*O] | [\*L-replica -clearinghouse \*Vclearinghouse_name\*O]] ...\" REPLACE PRECEDING WITH FOLLOWING: ...\" .zA "1.2.1: add -force" ...\" .zA "DMA Clarify syntax" [[\*L-tree\*O] [\*L-force\*O] | \*L-replica -clearinghouse \*Vclearinghouse_name\*O] ...\" .zZ "DMA Clarify syntax" ...\" .zZ "1.2.1: add -force" .PP \*Ldirectory help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Ldirectory list \*Vdirectory_name_list\*O [\*L-directories\*O] [\*L-objects\*O] .nL ...\" .zA "1.1: add -fullname" [\*L-links\*O] [\*L-simplename\*O | \*L-fullname\*O] ...\" .zZ "1.1: add -fullname" .PP \*Ldirectory merge \*Vsource_directory_name .nL \*L -into \*Vdestination_directory_name\*O .nL [\*L-clearinghouse \*Vclearinghouse_name\*O] [\*L-tree\*O] [\*L-nocheck\*O] .PP ...\" .zA "DMA Clarify syntax" \*Ldirectory modify \*Vdirectory_name_list\*O .nL {\*L-add \*Vattribute_list\*O [\*L-single\*O] | .nL \*L-remove \*Vattribute_list\*O [\*L-types\*O] | .nL \*L-change \*Vattribute_list\*O | ...\" ADD FOLLOWING: .nL ...\" .zA "1.2.1: add -master and -readonly" \*L-master \*Vclearinghouse_name\*O [\*L-readonly \*Vclearinghouse_name_list\*O] ...\" .zZ "1.2.1: add -master and -readonly" .nL ...\" .zA "1.2.1: add -exclude" [\*L-exclude \*Vclearinghouse_name_list\*O]} ...\" .zZ "1.2.1: add -exclude" ...\" .zZ "DMA Clarify syntax" .PP \*Ldirectory operations\*O .PP \*Ldirectory remove \*Vdirectory_name_list\*L -member \*Vchild_pointer_list\*O .PP ...\" .zA "DMA Clarify syntax" \*Ldirectory show \*Vdirectory_name_list\*O [\*L-schema\*O] .nL [\*L-member \*Vchild_pointer_list\*O | [\*L-replica\*O] \*L-clearinghouse \*Vclearinghouse_name\*O] ...\" .zZ "DMA Clarify syntax" .PP \*Ldirectory synchronize \*Vdirectory_name_list\*O .sE .SH "ARGUMENTS" ...\" .zA "1.1: enlarge arg descriptions" .VL .LI "\*Vdirectory_name_list\*O" A list of one or more directory names to be operated on. ...\" The last simple name can contain wildcard characters. .LI "\*Voperation\*O" The name of a \*Ldirectory\*O operation for which to display help information. .LI "\*Vsource_directory_name\*O" The name of a single directory whose contents are to be copied into a destination directory using the \*Lmerge\*O operation. ...\" ...\" .LI "\*Vchild_pointer_list\*O" ...\" A list of one or more specific child pointers to be operated on. ...\" .LI "\*Vclearinghouse_name\*O" ...\" The name of a single clearinghouse to use during directory operations. ...\" .LI "\*Vclearinghouse_name_list\*O" ...\" A list of one or more clearinghouses to use during the \*Ldirectory modify\*O ...\" operations. ...\" .LI "\*Vdestination_directory_name\*O" ...\" The name of one specific directory that will contain the results ...\" .LI "\*Vattribute_list\*O" ...\" of a successful \*Ldirectory merge\*O operation. ...\" .LI "\*Vattribute_list\*O" ...\" A list of one or more legal attributes to use during \*Ldirectory\*O operations. ...\" .LE ...\" .zZ "1.1: enlarge arg descriptions" .SH "DESCRIPTION" .P The \*Ldirectory\*O object represents Cell Directory Service (CDS) directories. CDS directories are containers for other objects, links, and other directories (as well as clearinghouses). Any of these items that reside in a directory are called \*Echildren\*O of that directory. Directories also contain attributes that may be viewed or modified. .P This object also represents CDS replicas. Replicas are read-only copies of directories stored in other clearinghouses. Several of the supported operations take options to indicate that the command is to operate on a specific replica. .P If the \*L_s(cds)\*O convenience variable is set, it is treated as the name of a clearinghouse to contact for this operation. This is the only clearinghouse that will be contacted in an attempt to complete the operation. These commands do \*Enot\*O set the value of this variable after completion. If a \*L\-clearinghouse\*O option is used (as described in some commands below), then it overrides the value of \*L_s(cds)\*O, but the command will not change the setting of \*L_s(cds)\*O. .SH "ATTRIBUTES" .P ...\" .zA "def,13377,R1.2.2,enchanced descriptions of all attrs" The following are the CDS-defined attributes for CDS \*Ldirectory\*O objects: .VL .LI "\*LCDS_AllUpTo\*O" Indicates the date and time of the last successful skulk on the directory. All replicas of the directory are guaranteed to receive all updates whose timestamps are less than the value of this attribute. The value of this attribute is a read-only DTS-style timestamp that is set by the system. .LI "\*LCDS_Convergence" Specifies the degree of consistency among replicas. This attribute's value is defined as one of the following: .VL .LI "\*Llow\*O" CDS does not immediately propagate an update. The next skulk distributes all updates that occurred since the previous skulk. Skulks occur at least once every 24 hours. .LI "\*Lmedium\*O" CDS attempts to immediately propagate an update to all replicas. If the attempt fails, the next scheduled skulk makes the replicas consistent. Skulks occur at least once every 12 hours. .LI "\*Lhigh\*O" CDS attempts to immediately propagate an update to all replicas. If the attempt fails (for example, if one of the replicas is unavailable), a skulk is scheduled for within one hour. Skulks usually occur at least once every 12 hours. Use this setting temporarily and briefly, because it uses extensive system resources. .LE By default, every directory inherits the convergence setting of its parent at creation time. The default setting on the root directory is \*Lmedium\*O. .LI "\*LCDS_CTS\*O" Specifies the creation timestamp (CTS) of the directory. The value of this attribute is a read-only DTS-style timestamp that is set by the system. .LI "\*LCDS_DirectoryVersion\*O" Specifies the current version of the directory. The version is derived from the \*LCDS_DirectoryVersion\*O attribute of the clearinghouse in which the directory was created. Multiple directory versions are supported in a cell. This read-only attribute is set by the system. .LI "\*LCDS_Epoch\*O" A Universal Unique Identifier (UUID) that identifies a particular instance of the directory. This read-only attribute is set by the system. .LI "\*LCDS_GDAPointers\*O" A set-valued attribute that is only present in the root directory of a cell. This attribute contains location information about registered Global Directory Agents (GDAs) for that cell, similar to the \*LCDS_Replicas\*O attribute. It is created and only used by a GDA. .LI "\*LCDS_InCHName\*O" Indicates whether a directory or any of its descendants can store clearinghouse names. If this value is \*Ltrue\*O, the directory can store clearinghouse names. If it is \*Lfalse\*O, the directory cannot store clearinghouse names. This read-only attribute is set by the system. As of DCE Release 1.1 and later, CDS creates this attribute on the cell root directory and give it a value of true. The attribute will not appear in any other directory. .LI "\*LCDS_LastSkulk\*O" Records the timestamp of the last skulk performed on this directory. This read-only attribute is set by the system. .LI "\*LCDS_LastUpdate\*O" Records the timestamp of the most recent change to any attribute of a directory replica, or any change to an entry in the replica. This read-only attribute is set by the system. .LI "\*LCDS_ObjectUUID\*O" Specifies the unique identifier of the directory. This read-only attribute is set by the system when the directory is created. .LI "\*LCDS_ParentPointer\*O" Contains a pointer to this directory's parent in the namespace. This read-only attribute is set by the system. .LI "\*LCDS_Replicas\*O" Specifies the address, UUID, and name of every clearinghouse where a copy of this directory is located. This attribute also specifies whether the replica in a particular clearinghouse is a master or read-only replica. This read-only attribute is set by the system. .LI "\*LCDS_ReplicaState\*O" Specifies whether a directory replica can be accessed. The state \*Lon\*O indicates that the directory replica can be accessed. This read-only attribute is set by the system. .LI "\*LCDS_ReplicaType\*O" Indicates whether a directory replica is a master or read-only replica. Possible values are \*LMaster\*O and \*LReadOnly\*O. This read-only attribute is set by the system. .LI "\*LCDS_ReplicaVersion\*O" Specifies the version of a replica of the directory. The default is \*L3.0\*O. This read-only attribute is set by the system. .LI "\*LCDS_RingPointer\*O" Specifies the UUID of a clearinghouse containing another replica of this directory. The \*LCDS_RingPointer\*O attribute will appear on older directories, but not on DCE Release 1.1 and later directories. This read-only attribute is set by the system. .LI "\*LCDS_UpgradeTo\*O" A single-valued attribute used to control the upgrading of a directory from one version of CDS to another. By modifying this attribute, the process of upgrading a directory to a newer version of CDS may be initiated. After this attribute is set, the background process in CDS notices it and tries to contact each replica. If it can contact it, the \*LCDS_DirectoryVersion\*O attribute is changed to the value of this attribute. .LI "\*LCDS_UTS\*O" Specifies the timestamp of the most recent update to an attribute of the directory. The value of this attribute is a read-only DTS-style timestamp that is set by the system. .LE .PP See the \*VOSF DCE Administration Guide\*O for more information about directory attributes. ...\" See the \*(Ag for more information about directory attributes. ...\" .zZ "def,13377,R1.2.2,enchanced descriptions of all attrs" .PP .SH "OPERATIONS" ...\" .SS "directory add" .PP Creates a child pointer in the parent directory. The syntax is as follows: .sS \*Ldirectory add \*Vdirectory_name_list\*L -member \*Vchild_pointer_list .nL \*L-clearinghouse \*Vclearinghouse_name\*L .sE .PP \*LOptions\*O .PP .VL .LI "\*L-member\*O \*Vchild_pointer_list\*O" This required option names the child pointers to be added to parent directories in the clearinghouse named by the required \*L-clearinghouse\*O option. .LI "\*L-clearinghouse\*O \*Vclearinghouse_name\*O" This required option names the clearinghouse where the child pointers are to be added. .LE .PP The \*Ladd\*O operation creates a child pointer in the parent directory. The \*Vdirectory_name_list\*O argument is a list of one or more names of parent directories to have child pointers added to them. The value of the required \%\*L-member\*O option is a list of names of child pointers to be added to each of the directories listed in the argument. Each child pointer name entered should contain only the last relative distinguished name (RDN) of the name. The child object must exist or the command returns an error. The full name of a clearinghouse that holds a replica of the child directory is given as the value to the required \%\*L-clearinghouse\*O option. This option may only have one value and is used for each of the values of the \%\*L-member\*O option. This operation returns an empty string on success. If a child pointer of the same name already exists an error is returned. .P This command is needed only to recreate a child pointer that was accidentally deleted, such as in a troubleshooting situation. Normally child pointers are created internally by CDS when creating directories with the \*Ldirectory create\*O command. .PP \*LPrivileges Required\*O .PP You must have \*Li\*O (\*Linsert\*O) permission to the parent directory. .PP \*LExamples\*O .PP .oS dcecp>\*L directory add /.: -member foo -clearinghouse /.:/darkstr_ch\*C dcecp> .oE .SS "directory create" .PP Creates a new directory of the specified name. The syntax is as follows: .sS ...\" .zA "DMA Clarify syntax" \*Ldirectory create \*Vdirectory_name_list .nL \*O [\*L-attribute \*Vattribute_list\*O [\*L-single\*O]] .nL [[\*L-replica\*O] \*L-clearinghouse \*Vclearinghouse_name\*O]] ...\" .zZ "DMA Clarify syntax" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-attribute \*Vattribute_list\*O" Allows you to specify the \*LCDS_Convergence\*O attribute or the \*LCDS_UpgradeTo\*O attribute in an attribute list. The format is as follows: .iS {{\*Vattribute value\*L}... {\*Vattribute value\*L}} .iE See \*LATTRIBUTES\*O for descriptions of \*LCDS_Convergence\*O and \*LCDS_UpgradeTo\*O. .LI "\*L-single\*O" Valid only with the \%\*L-attribute\*O option, this specifies that attribute values are single-valued. Otherwise, attributes are multivalued. .LI "\*L-replica\*O" This option specifies that the directory created is a replica of an existing directory. If you use the \%\*L-replica\*O option, you must specify a clearinghouse by using the \*L\*O-clearinghouse option. .LI "\*L-clearinghouse\*O \*Vclearinghouse_name\*O" Required with the \%\*L-replica\*O option; optional when the \%\*L-replica\*O option is not present. The \%\*L-clearinghouse\*O option names the clearinghouse to which the child pointers are to be added. .LE .PP The \*Lcreate\*O operation creates a new directory of the specified name. The \*Vdirectory_name_list\*O argument is a list of names of directories to be created. .PP An optional \%\*L-attribute\*O option specifies a list of attributes to be included in each created directory. The attribute values are multivalued unless the \%\*L-single\*O option is specified, in which case all attributes are single-valued. The \%\*L-single\*O option is valid only if the \%\*L-attribute\*O option is specified. .PP The \%\*L-clearinghouse\*O option specifies one clearinghouse to create all the directories in. If this option is not specified, the new directories are created in the master clearinghouse as the parent directory. The \*Ldirectory create\*O command also takes a \%\*L-replica\*O option which indicates that a directory replica is created; when this option is used, the \%\*L-clearinghouse\*O option is required. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have the following permissions in order to create a directory: \*Lr\*O (\*Lread\*O) and \*Li\*O (\*Linsert\*O) permission to the parent directory, and \*Lw\*O (\*Lwrite\*O) permission to the clearinghouse in which the master replica of the new directory is to be stored. .PP In addition, the server principal must have \*Lr\*O (\*Lread\*O) and \*Li\*O (\*Linsert\*O) permission to the parent directory. .PP \*LExamples\*O .PP .oS dcecp>\*L directory create /.:/sales\*C dcecp> .oE .SS "directory delete" .PP Deletes a directory. The syntax is as follows: .sS \*Ldirectory delete \*Vdirectory_name_list\*O .nL ...\" .zA "1.2.1: add -force" ...\" .zA "DMA Clarify syntax" [[\*L-tree\*O] [\*L-force\*O] | \*L-replica -clearinghouse \*Vclearinghouse_name\*O] ...\" .zZ "DMA Clarify syntax" ...\" .zZ "1.2.1: add -force" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-tree\*O" Removes the directory and everything (all directories, objects, links, and clearinghouses) beneath it. .LI "\*L-replica\*O" Specifies that the directory to delete is a replica of an existing directory. The \%\*L-clearinghouse\*O option is required if you use this option. ...\" ADD FOLLOWING: ...\" .zA "1.2.1: add -force" .LI "\*L-force\*O" Allows the delete operation to proceed by deleting existing replicas. ...\" .zZ "1.2.1: add -force" .LI "\*L-clearinghouse\*V clearinghouse_name\*O" Required with the \%\*L-replica\*O option, the \%\*L-clearinghouse\*O option names one clearinghouse (not a list of clearinghouses) from which the replica is to be deleted. .LE .PP The \*Ldelete\*O operation deletes a directory from the CDS name service. The \*Vdirectory_name_list\*O argument is a list of names of directories to be deleted. If the directory is not empty, the command returns an error unless the \%\*L-tree\*O option is used. The \%\*L-tree\*O option, which takes no value, removes the directory and everything (all directories, objects, links, and clearinghouses) beneath it. ...\" ADD FOLLOWING: ...\" .zA "1.2.1: add -force" The \%\*L-force\*O option also deletes replicas. ...\" .zZ "1.2.1: add -force" .PP The \*L-replica\*O and \%\*L-clearinghouse\*O options (they must be used together) let you delete a replica instead of a directory. The \%\*L-clearinghouse\*O option specifies the clearinghouse that contains the replica; only one value can be specified, not a list. This operation returns an empty string on success. If a specified directory does not exist, an error is generated. .PP The \%\*L-replica\*O and \%\*L-clearinghouse\*O options cannot be used with the \%\*L-tree\*O option. .PP \*LPrivileges Required\*O .PP You must have \*Ld\*O (\*Ldelete\*O) permission to the directory and \*Lw\*O (\*Lwrite\*O) permission to the clearinghouse that stores the master replica of the directory. The server principal needs \*LA\*O (\*LAdmin\*O) permission to the parent directory or \*Ld\*O (\*Ldelete\*O) permission to the child pointer that points to the directory you intend to delete. .PP \*LExamples\*O .PP .oS dcecp>\*L directory delete /.:/eng \*C dcecp> .oE .PP The following command tries to delete a nonempty directory \*L/.:/depts/phrenology\*O and gets an error. The second attempt uses the \%\*L-tree\*O option to delete the directory and all the directories and objects beneath it. .oS dcecp> \*Ldir delete /.:/depts/phrenology\*C Error: Directory must be empty to be deleted dcecp> dcecp> \*Ldir delete /.:/depts/phrenology -tree\*O dcecp> .oE .SS "directory help" .PP Returns help information about the \*Ldirectory\*O object and its operations. The syntax is as follows: .sS \*Ldirectory help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Ldirectory\*O object. .LE .PP Used without an argument or option, the \*Ldirectory help\*O command returns brief information about each \*Ldirectory\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \*L-verbose\*O option to display detailed information about the \*Ldirectory\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Ldirectory help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Ldirectory help\*C add Creates a child pointer in the specified directory. create Creates the named directory. delete Deletes the named directory. list Lists the descendants of a directory. merge Merges the contents of one directory into another. modify Adds, removes or changes attributes in the named directory. remove Removes a child pointer in the specified directory. show Returns the attributes of a directory. synchronize Skulks the named directory. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "directory list" .PP Returns a list of the names of all the descendants of a directory. The syntax is as follows: ...\" .zA "1.1, add -fullname" .sS \*Ldirectory list \*Vdirectory_name_list\*O [\*L-directories\*O] [\*L-objects\*O] .nL ...\" .zA "DMA Clarify syntax" [\*L-links\*O] [\*L-simplename\*O | \*L-fullname\*O] ...\" .zZ "DMA Clarify syntax" .sE ...\" .zZ "1.1, add -fullname" .PP \*LOptions\*O .PP .VL .LI "\*L-directories\*O" This option lists the names of all descendent directories. .LI "\*L-objects\*O" This option lists the names of all descendent objects. .LI "\*L-links\*O" This option lists the names of all descendent softlinks. .LI "\*L-simplename\*O" Returns just the RDN of the name. ...\" .zA "1.1, add -fullname" .LI "\*L-fullname\*O" Returns the entire name. ...\" .zZ "1.1, add -fullname" .LE .PP The \*Llist\*O operation returns a list of the names of all the descendents of a directory. Descendents can include all directories, objects, links, and clearinghouses of the directory. The \*Vdirectory_name_list\*O argument is a list of names of directories to be operated on. This command returns only the names of descendents, so there is no way to tell the class of each name unless by convention (for instance, most clearinghouses end with \*L_ch\*O). Use the following options to specify the types of descendents to return: \%\*L-directories\*O, \%\*L-objects\*O, \%\*L-links\*O. The options take no values and can be used in combination. By default or if the \%\*L-fullname\*O option is specified, fullnames are returned. Use the \*L-simplename\*O option to return merely the last RDN of the name. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the directory named in the argument. .PP \*LExamples\*O .PP .oS dcecp> \*Ldir list /.:/depts/administration -links\*C /.../ward_cell.osf.org/depts/administration/bump_server1 dcecp> .oE .SS "directory merge" .PP Copies the contents of one directory into another directory. The syntax is as follows: .sS \*Ldirectory merge \*Vsource_directory_name .nL \*L-into \*Vdestination_directory_name\*O .nL [\*L-clearinghouse \*Vclearinghouse_name\*O] [\*L-tree\*O] [\*L-nocheck\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-tree\*O" Copies the contents of child directories (as well as the child directories themselves) into the destination directory. .LI "\*L-into\*O \*Vdestination_directory_name\*O" The argument to this required option specifies the name of the destination directory. The destination directory must exist. .LI "\*L-clearinghouse\*O \*Vclearinghouse_name\*O" Places the new objects (the resulting merged directory) in a clearinghouse other than that of the newly created destination directory. .LI "\*L-nocheck\*O" Lets the \*Lmerge\*O operation proceed without checking first for object name collisions or access control list (ACL) problems. Use this option to save time when you're sure problems don't exist. .LE .PP The \*Lmerge\*O operation copies the contents of one directory into another. The argument is the name of the source directory. This command takes a required \%\*L-into\*O option to specify the destination directory which must exist. For example, if \*L/.:/a\*O has two child objects \*L/.:/a/b\*O and \*L/.:/a/c\*O, then \*Ldirectory merge /.:/a -into /.:/x\*O would result (assuming no errors) in the creation of the following objects: \*L/.:/x/b\*O and \*L/.:/x/c\*O. .PP Normally only the immediate contents of the directory are merged. This means all objects, links, and directories, but not the contents of child directories. To merge these as well, use the \*L-tree\*O option. .PP By default, the new objects are placed in the destination directory's master clearinghouse, and all children (no matter how many levels down) are placed in the same clearinghouse. To place any newly created descendant directories in another clearinghouse, use the \%\*L-clearinghouse\*O option with a value. There can only be one clearinghouse specified for all directories involved in the merge operation. To specify more than one, either change this after the merge has happened, or use separate commands. .PP This command first checks for any collisions or ACL problems before beginning to merge any objects. If there are any problems encountered, an error is generated (not immediately; all objects are checked first), and the names of all problem objects, links or directories are returned in a list. The administrator should then address these problems and rerun the merge command. If the \%\*L-nocheck\*O option is specified the check is not performed. This way time can be saved when trying a known nonproblematic merge. This is not an atomic operation and other changes to the involved objects can cause problems. This command should be issued when others are not modifying the involved directories. Changing ACLs can be done to ensure this. If an error does occur during the actual merging process, it is generated and the operation aborts immediately. .PP The merge command actually recreates the objects with the same writable attributes of the source objects. This means that some read-only attributes will change between the source and destination. For example, the creation timestamp attribute (\*LCDS_CTS\*O) changes. .PP The resulting merged directory inherits its ACLs from the destination directory's Initial Container or Initial Object ACLs. Consequently, the ACLs of the destination objects are likely to differ from the ACLs of the source objects. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) and \*Li\*O (\*Linsert\*O) permission to the destination directory. .PP \*LExamples\*O .PP The following command merges the directories but not the contents of the \*L/.:/depts/phrenology\*O directory into the \*L/.:/depts/radiology\*O directory: .oS dcecp> \*Ldir list /.:/depts/phrenology -simple\*C applications services staff users dcecp> dcecp> \*Ldirectory merge /.:/depts/phrenology -into /.:/depts/radiology\*C dcecp> dcecp> \*Ldir list /.:/depts/radiology -simple \*C applications services staff users dcecp> .oE .SS "directory modify" .PP Adds, removes, or changes a directory's attributes and their values. The syntax is as follows: .sS ...\" .zA "DMA Clarify syntax" \*Ldirectory modify \*Vdirectory_name_list\*O .nL {\*L-add \*Vattribute_list\*O [\*L-single\*O] | .nL \*L-remove \*Vattribute_list\*O [\*L-types\*O] | .nL \*L-change \*Vattribute_list\*O | .nL \*L-master \*Vclearinghouse_name\*O [\*L-readonly \*Vclearinghouse_name_list\*O] .nL ...\" .zZ "1.2.1: add -master and -readonly" ...\" .zA "1.2.1: add -exclude" [\*L-exclude \*Vclearinghouse_name_list\*O]} ...\" .zZ "1.2.1: add -exclude" ...\" .zZ "DMA Clarify syntax" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-add\*O \*Vattribute_list\*O" This option adds a value to a modifiable, set-valued attribute (including application-defined attributes) of a directory. If you enter a byte data type, you must enter an even number of digits in length. You can only enter pairs of hexadecimal values for user-defined attributes. .LI "\*L-single\*O" Used with the \%\*L-add\*O option this specifies that the attributes to be added are to be single-valued. Normally all user defined attributes are defined to be multivalued, even if only one value is specified. This option is not legal without the \%\*L-add\*O option. .LI "\*L-remove\*O \*Vattribute_list\*O" This option removes a value from a multi-valued or single-valued attribute (including application-defined attributes) of a directory. If you do not specify a value, the command removes the entire attribute. This command can delete attributes created with the \%\*L-add\*O and \%\*L-change\*O options. .LI "\*L-types\*O" Used with the \%\*L-remove\*O option this specifies that the value of the \%\*L-remove\*O option is a list of attribute types. This means that the entire attribute should be removed, not just a value. This option is not legal without the \%\*L-remove\*O option. .LI "\*L-change\*O \*Vattribute_list\*O" This option changes the value of a modifiable, single-valued attribute of a directory. You can specify an application-defined attribute or the following attribute, which specifies the degree of consistency among replicas: .iS {CDS_Convergence\*O \*Vvalue\*L} .iE See \*LATTRIBUTES\*O for the format of \*LCDS_Convergence\*O. ...\" Specify one of the following for \*Vvalue\*O: ...\".VL ...\".LI "\*Llow\*O" ...\"CDS does not immediately propagate any updates. The next ...\"skulk distributes all updates that occurred since the previous skulk. Skulks ...\"occur at least once every 24 hours. ...\".LI "\*Lmedium\*O" ...\"CDS attempts to immediately propagate ...\"an update to all replicas. If the attempt fails, the software lets the next ...\"scheduled skulk make the replicas consistent. Skulks occur at least once ...\"every 12 hours. ...\".LI "\*Lhigh\*O" ...\"CDS attempts to immediately propagate an update to all replicas. If ...\"that attempt fails (for example, if one of the replicas is ...\"unavailable), a skulk is scheduled for within one hour. Background ...\"skulks occur at least once every 12 hours. Use this setting ...\"temporarily and briefly because it uses extensive system resources. ...\" ADD FOLLOWING: ...\" .zA "1.2.1: add -master" .LI "\*L-master \*Vclearinghouse_name\*O" When changing the epoch of a directory, use the \%\*L-master\*O option to specify a new master clearinghouse for the directory. ...\" .zZ "1.2.1: add -master" ...\" .zA "1.2.1: add -readonly" .LI "\*L-readonly \*Vclearinghouse_name_list\*O" When changing the epoch of a directory, specifies which clearinghouses will hold a replica of the directory. ...\" .zZ "1.2.1: add -readonly" ...\" .zA "1.2.1: add -exclude" .LI "\*L-exclude \*Vclearinghouse_name\_list\*O" When changing the epoch of a directory, specifies which clearinghouses will no longer be used as replicas for the directory. ...\" .zZ "1.2.1: add -exclude" .LE .LE .PP The \*Lmodify\*O operation adds, removes, or changes a directory's attributes and their values. The argument is a list of one or more names of directories to be operated on. Attribute options are not supported; use one or more of the \%\*L-add\*O, \%\*L-remove\*O, or \%\*L-change\*O options, each of which takes an attribute list as an argument. .PP Use the \%\*L-remove\*O option to remove a value from an attribute. You can use the \%\*L-types\*O option along with the \%\*L-remove\*O option to remove an entire attribute or list of attributes. .PP Some attributes in CDS are multivalued. For instance, the \*LCDS_Replicas\*O attribute can specify the locations and names of several clearinghouses that maintain copies of a directory. The \%\*L-add\*O operation needs to be instructed whether it will operate on single-valued or multivalued attributes. Multivalued attributes are the default case and are indicated by using no qualifying options. However, you can indicate the use of single-valued attributes by using the \%\*L-single\*O option. ...\" ADD FOLLOWING: ...\" .zA "1.2.1: add -exclude" ...\" .zA "1.2.1: add -master" ...\" .zA "1.2.1: add -readonly" .PP To change the epoch of a directory, you must specify each clearinghouse that has a master or replica copy of the directory as either the new master (with the \%\*L-master\*O option), a readonly copy (with the \*L-readonly\*O option), or an excluded copy (with the \%\*L-exclude\*O option). Additional extra clearinghouses can also be specified. ...\" .zZ "1.2.1: add -readonly" ...\" .zZ "1.2.1: add -master" ...\" .zZ "1.2.1: add -exclude" .PP Most attributes are usually managed by the client application. See the \*(Ag for more information about attributes. All modifications are made to each directory listed in the argument. An error in any one causes the command to immediately abort and generate an error. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission to the directory to add, remove, or change attributes. .PP \*LExamples\*O .PP The following command sets the \*LCDS_Convergence\*O attribute on the \*L/.:/depts/radiology\*O directory to a value of low: .oS dcecp> \*Ldirectory modify /.:/depts/radiology -change {CDS_Convergence low}\*C dcecp> .oE .PP To add the value \*Lontario\*O to the attribute \*Lmyname\*O of a directory named \*L/.:/sales\*O, read the \*Lcds_attributes\*O file to verify that the attribute shown in the following display exists: .oS OID LABEL SYNTAX 1.3.22.1.3.91 myname char\*O .oE .PP Enter the following command to assign the value \*Lontario\*O to the attribute \*Lmyname\*O: .oS dcecp> \*Ldirectory modify /.:/sales -add {myname ontario}\*C dcecp> .oE .PP To remove the value \*L1\*O from the user-defined, set-valued attribute \*Ldirregion\*O of a directory named \*L/.:/sales\*O, follow these steps: .AL .LI Read the \*Lcds_attributes\*O file to check that the attribute \*Ldirregion\*O is listed, as shown in the following display: .oS OID LABEL SYNTAX 1.3.22.1.3.66 dirregion small\*O .oE .LI Enter the following command to remove the value \*L1\*O from the attribute \*Ldirregion\*O: .oS dcecp> \*Ldirectory modify /.:/sales -remove {dirregion 1}\*C dcecp> .oE .LI ...\" .zA "1.2.1: add -exclude" ...\" .zA "1.2.1: add -master" ...\" .zA "1.2.1: add -readonly" To change the epoch of a directory with one master and two replicas, enter the following command: .oS dcecp>\*L directory modify /.:/oddball -master /.:/gumby_ch \\ \*C > \*L-readonly /.:/pokey_ch -exclude /.:/goober_ch \*C dcecp> .oE ...\" .zZ "1.2.1: add -readonly" ...\" .zZ "1.2.1: add -master" ...\" .zZ "1.2.1: add -exclude" .LE .SS "directory operations" .PP Returns a list of the operations supported by the \*Ldirectory\*O object. The syntax is as follows: .sS \*Ldirectory operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Ldirectory operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Ldirectory operations\*C add create delete list merge modify remove show synchronize help operations dcecp> .oE .SS "directory remove" .PP Deletes a child pointer from the directories specified. The syntax is as follows: .sS \*Ldirectory remove \*Vdirectory_name_list\*L -member \*Vchild_pointer_list\*O .sE .PP \*LOptions\*O .PP .VL .LI "\*L-member\*O \*Vchild_pointer_list\*O" This required option names the child pointers to be removed from each directory in the operation argument. .LE .PP The \*Lremove\*O operation deletes a child pointer from the directories specified. The \*Vdirectory_name_list\*O argument is a list of names of one or more directories to be operated on. The required \%\*L-member\*O option allows you to list the child pointers to be removed from each specified directory. .PP The \*Vchild_pointer_list\*O argument value of the required \%\*L-member\*O option is a list of one or more child pointers (specified as only one RDN each) to be removed from each directory in the argument. .P This command is needed only to delete a child pointer that accidentally remains after the child directory is deleted. Normally child pointers are removed internally by CDS when deleting directories with the \*Ldirectory delete\*O command. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Ld\*O (\*Ldelete\*O) permission to the child pointer or \*LA\*O (\*LAdmin\*O) permission to the parent directory. .PP \*LExamples\*O .PP The following command deletes the child pointer that accidentally remains after the \*L/.:/sales/east\*O directory is deleted: .oS dcecp>\*L directory remove /.:/sales -member east\*C dcecp> .oE .SS "directory show" .PP Returns a list of attributes for the specified directories and optionally, their specified contents. The syntax is as follows: .sS ...\" .zA "DMA Clarify syntax" \*Ldirectory show \*Vdirectory_name_list\*O [\*L-schema\*O] .nL [\*L-member \*Vchild_pointer_list\*O | [\*L-replica\*O] \*L -clearinghouse \*Vclearinghouse_name\*O] ...\" .zZ "DMA Clarify syntax" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-member\*O \*Vchild_pointer_list\*O" The optional \%\*L-member\*O option takes one required value which is the last RDN of the child pointer in the directory specified by the optional argument. The returned list describes the child pointer information for the specified member stored in the specified directories. This option cannot be combined with the \*L-replica\*O or \%\*L-clearinghouse\*O option. .LI "\*L-replica \*Vclearinghouse_name\*O" This option specifies that the directory shown is a replica of an existing directory. If you use the \%\*L-replica\*O option, you must specify a clearinghouse with the \%\*L-clearinghouse\*O option. .LI "\*L-clearinghouse\*O \*Vclearinghouse_name\*O" Required with the \%\*L-replica\*O option, the \%\*L-clearinghouse\*O option names the clearinghouse where the named replica exists. .LI "\*L-schema\*O" This option returns whether an attribute is single or multivalued. This is specific to a directory, meaning that the same attribute can be single-valued on one directory and multivalued on another directory. This option may not be used with other options. .LE .PP The \*Lshow\*O operation returns a list of attributes for the specified directories and optionally, their specified contents. The \*Vdirectory_name_list\*O argument is a list of one or more names of directories to be operated on. When used without any options, this command returns the attributes associated with the named directories. If more than one directory is specified, then all the arguments are grouped together in one list. The order of the returned arguments is the lexical order of the object identifiers (OIDs) of each attribute for each directory. .PP You can request attributes of specific replicas in specific clearinghouses by using the \*L-replica\*O and \*L-clearinghouse\*O options. Alternatively, you can request attributes of child pointers by using the \%\*L-member\*O option. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the directories named in the argument list. .PP \*LExamples\*O .PP .oS dcecp> \*Ldirectory show /.:/depts/radiology\*C {RPC_ClassVersion {01 00}} {CDS_CTS 1994-07-08-17:01:03.115+00:00I0.000/00-00-c0-8a-df-56} {CDS_UTS 1994-07-08-19:36:31.719+00:00I0.000/00-00-c0-8a-df-56} {CDS_ObjectUUID 2df03af4-9a76-11cd-8f2b-0000c08adf56} {CDS_Replicas ...\" .zA "1.1, CR13068" {{CH_UUID b32648c6-928d-11cd-b4b5-0000c08adf56} {CH_Name /.../ward_cell.osf.org/pmin17_ch} ...\" .zZ "1.1, CR13068" {Replica_Type Master} {Tower ncacn_ip_tcp:130.105.1.227[]} {Tower ncadg_ip_udp:130.105.1.227[]}}} {CDS_AllUpTo 1994-07-08-17:01:05.945+00:00I0.000/00-00-c0-8a-df-56} {CDS_Convergence medium} {CDS_ParentPointer {{Parent_UUID 8eeb369a-9a4b-11cd-8f2b-0000c08adf56} {Timeout {expiration 1994-07-09-17:13:31.959} {extension +1-00:00:00.000I0.000}} {myname /.../ward_cell.osf.org/depts/radiology}}} {CDS_DirectoryVersion 3.0} {CDS_ReplicaState on} {CDS_ReplicaType Master} {CDS_LastSkulk 1994-07-08-17:01:05.945+00:00I0.000/00-00-c0-8a-df-56} {CDS_LastUpdate 1994-07-08-19:36:31.719+00:00I0.000/00-00-c0-8a-df-56} {CDS_RingPointer b32648c6-928d-11cd-b4b5-0000c08adf56} {CDS_Epoch 2f617aa6-9a76-11cd-8f2b-0000c08adf56} {CDS_ReplicaVersion 3.0} dcecp> .oE .PP .oS dcecp> \*Ldirectory show /.:/depts/radiology -schema\*C {RPC_ClassVersion multi} {CDS_CTS single} {CDS_UTS single} {CDS_ObjectUUID single} {CDS_Replicas multi} {CDS_AllUpTo single} {CDS_Convergence single} {CDS_ParentPointer multi} {CDS_DirectoryVersion single} {CDS_ReplicaState single} {CDS_ReplicaType single} {CDS_LastSkulk single} {CDS_LastUpdate single} {CDS_RingPointer single} {CDS_Epoch single} {CDS_ReplicaVersion single} dcecp> .oE .SS "directory synchronize" .PP Initiates an immediate skulk of the directories specified. The syntax is as follows: .sS \*Ldirectory synchronize \*Vdirectory_name_list\*O .sE .PP The \*Lsynchronize\*O operation initiates an immediate skulk of the directories specified. The \*Vdirectory_name_list\*O argument is a list of names of one or more directories to be operated on. Skulks begin immediately in sequence. The command does not return until all skulks complete. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*LA\*O (\*LAdmin\*O), \*Lw\*O (\*Lwrite\*O), \*Li\*O (\*Linsert\*O), or \*Ld\*O (\*Ldelete\*O) permission to the directory. The server principal needs \*LA\*O (\*LAdmin\*O), \*Lr\*O (\*Lread\*O), and \*Lw\*O (\*Lwrite\*O) permission to the directory. .PP \*LExamples\*O .PP The following command begins a skulk on the \*L/.:/admin\*O directory: .oS dcecp>\*L directory synchronize /.:/admin\*C dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_clearinghouse(1m)\*O, \*Ldcecp_link(1m)\*O, \*Ldcecp_object(1m)\*O. .ad b ...\" .ad l ...\" \*Lclearinghouse(1m)\*O, ...\" \*Ldcecp(1m)\*O, ...\" \*Llink(1m)\*O, ...\" \*Lobject(1m)\*O. ...\" .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH dts 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Ldts\*O" .iX "dts" "administering" .SH NAME .PP \*Ldts\*O - A \*Ldcecp\*O object that manages a \*Ldtsd\*O process .SH "SYNOPSIS" .sS \*Ldts activate \*O[\*Vdts_server\*O] [\*L-abruptly\*O] .PP ...\" .zA "def,13377,R1.2.2,add -global" \*Ldts catalog \*O[\*Vcell_name\*O] [\*L-simplename\*O] [\*L-global\*O] ...\" .zZ "def,13377,R1.2.2,add -global" .PP \*Ldts configure \*O[\*Vdts_server\*O] {\*L-global \*O| \*L-notglobal\*O} .PP \*Ldts deactivate \*O[\*Vdts_server\*O] .PP \*Ldts help \*O[\*Voperation\*O | \*L-verbose\*O] .PP ...\" .zA "def,13377,R1.2.2, Clarify syntax" \*Ldts modify \*O[\*Vdts_server\*O] \*L-change \*O{\*Vattribute_list\*O | \*L-\*Vattribute value\*O} ...\" .zZ "def,13377,R1.2.2, Clarify syntax" .PP \*Ldts operations\*O .PP ...\" .zA "def,13377,R1.2.2, Clarify syntax" \*Ldts show \*O[\*Vdts_server\*O] [\*L-all\*O | [\*L-attributes\*O] [\*L-counters\*O]] ...\" .zZ "def,13377,R1.2.2, Clarify syntax" .PP \*Ldts stop \*O[\*Vdts_server\*O] .PP \*Ldts synchronize \*O[\*Vdts_server\*O] [\*L-abruptly\*O] .sE .SH "ARGUMENTS" .VL ...\" .zA "def,13377,R1.2,clarify option" .LI "\*Vcell_name\*O" The name of a single cell. This allows access to DTS servers registered in a foreign cell. The name must be a fully qualified cell name as in either of the following: .iS /.: /.../\*Vforeign_cellname\*O .iE ...\" .zZ "def,13377,R1.2,clarify option" .PP .LI "\*Vdts_server\*O" Identifies the \*Ldtsd\*O server to act on. Supply the name in one of the following forms: .ML .LI As a fully qualified name, for example: .iS /.../\*Vcellname\*L/hosts/\*Vhostname\*L/dts-entity\*O .iE .LI As a string binding for the remote host on which \*Ldtsd\*O is running in standard string-binding syntax or in \*Ldcecp\*O string syntax, for example: .iS ncacn_ip_tcp:130.105.1.227 {ncacn_ip_tcp 130.105.1.227} .iE .LE .LI "\*Voperation\*O" The name of the \*Ldts\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Ldts\*O object represents the \*Ldtsd\*O (DTS daemon) process running on a host. The DTS process does not maintain stored data as some other objects. Consequently, the \*Ldts\*O object represents the information in and about a process rather than some data stored somewhere as other objects do. ...\" .zA "1.1, CR13059" .PP These commands all affect the local \*Ldtsd\*O entity by default. Use the \*Ldts_server\*O argument to operate on a remote DCE \*Ldtsd\*O. This argument is a single server entry or string binding representing a \*Ldtsd\*O that will be contacted for the operation. If the \*L_s(dts)\*O convenience variable is set, it is treated as the name of a \*Ldtsd\*O to contact for subsequent operations. If either of these methods is used, the specified server is the only server that will be contacted in an attempt to complete the operation. The argument on the command line takes precedence over the value of the \*L_s(dts)\*O convenience variable. These commands do not set the value of this variable after completion. ...\" .zZ "1.1, CR13059" .PP There are a number of attributes associated with the \*Ldts\*O object. All of these can be viewed with the \*Lshow\*O operation, and many can be changed with the \*Lmodify\*O operation. Attribute arguments can contain a maximum of 80 characters and are recalculated to a normalized date format. For example, if the input value is \*L0-0025:10:99.99999999\*O, the result is \*L1-01:11:39.990\*O. .PP Timestamps are specified in DTS and ISO formats. They can be specified in both absolute and relative time formats. See the \*VOSF DCE Administration Guide\*O for more information. ...\" See the \*(Ag for more information. .SH "ATTRIBUTES" .PP The \*Ldts\*O object supports attributes and counters. Most attributes and counters pertain to \*Ldtsd\*O processes in general. A subset of attributes and counters pertains only to \*Ldtsd\*O processes that are enabled as DTS server entities. ...\" .zA "def,13377,R1.2 clarify attr format" The format of all attributes of type \*Vrelative_time\*O is in DTS-style ([\*L-\*O]\*VDD\*O-\*VHH\*O:\*VMM\*O:\*VSS\*O). ...\" .zZ "def,13377,R1.2 clarify attr format" .PP ...\" .SS "General Attributes" .VL .LI "\*Lautotdfchange {yes | no}\*O" Specifies whether automatic changes to the time differential factor are enabled or disabled. The value is either \*Lyes\*O or \*Lno\*O. The value is determined by the operating system (that is, it cannot be changed with the \*Lmodify\*O operation). .LI "\*Lclockadjrate\*O" Specifies the rate at which the DTS server or clerk entity adjusts the node's clock during a synchronization. This may not be set by a user, but is built into \*Ldtsd\*O. .LI "\*Lclockresolution\*O" Specifies the amount of time between system clock ticks. The value is determined by the operating system (that is, it cannot be changed with the \*Lmodify\*O operation). .LI "\*Lglobalservers \*Vrelative-time\*O" Specifies the set of global servers known by the node. The information returned for each server is as follows: the DCE name of the host followed by \*L/self\*O, the last time polled, the last observed time, the last observed skew, a binary value of whether the server was used in the last last synchronization, and the transport time. These subattributes are called respectively: \*Lname\*O, \*Ltimelastpolled\*O, \*Llastobstime\*O, \*Llastobsskew\*O, \*Linlastsync\*O, and \*Ltransport\*O. .LI "\*Lglobaltimeout \*Vrelative-time\*O" Specifies the amount of time the node waits for a response to a wide area network (WAN) synchronization request before sending another request or declaring a global server to be unavailable. The number of attempts made to reach the server is controlled by the \*Lqueryattempts\*O attribute. The default value is \*L0-00:00:15.000\*O, and the range of possible values is \*L0-00:00:00.000 - 0-00:10:00.000\*O. .LI "\*Llocalservers\*O" Specifies the set of local servers known by the node. The information returned for each server is as follows: the principal name that the server is running as, the last time polled, the last observed time, the last observed skew, a binary value indicating whether the server was used in the last synchronization, and the transport time. These subattributes are called respectively: \*Lname\*O, \*Ltimelastpolled\*O, \*Llastobstime\*O, \*Llastobsskew\*O, \*Linlastsync\*O, and \*Ltransport\*O. .LI "\*Llocaltimeout \*Vrelative-time\*O" Specifies the amount of time the node waits for a response to a synchronization request before sending another request or declaring a server to be unavailable. The number of attempts made to reach the server is controlled by the \*Lqueryattempts\*O attribute. The default is \*L0-00:00:05.000\*O, and the range of possible values is \*L0-00:00:00.000 - 0-00:01:00.000\*O. .P Note that this attribute controls only the initial contact with a time provider. During this initial contact, the time-provider itself determines the timeout value for actually reporting back times. This allows a time provider attached to a slow source like a modem to request that \*Ldtsd\*O wait for a longer interval. .LI "\*Lmaxdriftrate\*O" Specifies the worst-case drift rate of the node's clock, in nanoseconds per second, as determined by the manufacturer's specifications (that is, it cannot be changed with the \*Lmodify\*O operation). .LI "\*Lmaxinaccuracy \*Vrelative-time\*O" Specifies the inaccuracy limit for the node. When the node exceeds the maximum inaccuracy setting, it attempts to synchronize. The default is \*L0-00:00:00.100\*O, and the range of possible values is \*L0-00:00:00.0 - 10675199-02:48:05.478\*O. The maximum number of hours is \*L24\*O. A practical value is less than \*L60\*O seconds. .LI "\*Lminservers \*Vinteger\*O" Specifies the minimum number of servers required for a synchronization. Settings of \*L1\*O or \*L2\*O for a DTS server may cause unreliable computed times. The default is \*L3\*O for a DTS server and \*L1\*O for a DTS clerk. The range of possible values is \*L1-10\*O. .LI "\*Lnexttdfchange\*O" Specifies the future time at which the time differential factor is automatically changed. The value is determined by the operating system (that is, it cannot be changed with the \*Lmodify\*O operation). .LI "\*Lqueryattempts \*Vinteger\*O" Specifies the number of attempts that a node makes to contact a server before the node considers the server unavailable. The default is \*L3\*O, and the range of possible values is \*L1-10\*O. .LI "\*Lstatus\*O" Specifies the state of the DTS entity. This is a read-only attribute and its possible values are as follows: .VL 1i .LI "\*Ldisabled\*O" The DTS entity is disabled. .LI "\*Lenabled\*O" The DTS entity is enabled. .LI "\*Lsyncing\*O" The DTS entity is synchronizing. .LI "\*Lupdating\*O" The DTS entity is updating the time. .LE .LI "\*Lsyncinterval \*Vrelative-time\*O" Specifies the interval a node must wait to synchronize. Also specifies synchronization frequency when a node reaches the value specified by the \*Lmaxinaccuracy\*O attribute. For clerks the default is \*L0-00:10:00.0\*O, and the range of possible values is \*L0-00:00:30.0 - 01-00:00:00.00\*O. For servers the default is \*L0-00:02.00.0\*O, and the range of possible values \*L0-00:00:30.0 - 01-00:00:00.00\*O. .LI "\*Ltdf \*Vrelative-time\*O" Specifies the time differential factor (TDF), which is the amount of time the server varies from Greenwich mean time (GMT) or Universal Time Coordinated (UTC). The default is based on timezone information, with the range of possible values being \*L-13-00:00:00 - 13-00:00:00\*O. This may not be set by a user, but rather is obtained from various timezone information repositories (such as the \*LTZ\*O environment variable, kernel structures, and so on). .LI "\*Ltimerep\*O" Specifies the internal timestamp format used by the node. This is not related to the format that is used to display the current time to the user (see the \*Lclock show\*O command). Currently DTS only uses \*LV1.0.0\*O timestamps. This cannot be set by ...\" .zA "1.1, CR13063" a user, but is built into a \*Ldtsd\*O. .LI "\*Ltolerance \*Vrelative-time\*O" Specifies the maximum separation allowed between the local clock and the computed time before synchronizations become abrupt rather than gradual (monotonic). The default is \*L0-00:05:00.000\*O, and the range of possible values is \*L0-00:00:00.500 - 10675199-02:48:05.478\*O. ...\" .zZ "1.1, CR13063" .LI "\*Ltype\*O" Specifies whether the node is a DTS \*Lserver\*O or \*Lclerk\*O. .LI "\*Lversion\*O" Specifies the DTS software version installed on the node. This attribute cannot be changed with the \*Lmodify\*O operation. .LE .SS "DTS Server Attributes" .VL .LI "\*Lactcourierrole\*O" Specifies a server's acting interaction with the set of global servers. The values are the same as for the \*Lcourierrole\*O attribute below. The difference between \*Lactcourierrole\*O and \*Lcourierrole\*O is that even when the value of \*Lcourierrole\*O is \*Lbackup\*O there is no guarantee that the courier is acting as a courier. ...\" .zA "def,13377,R1.2 add default" The default is \*Lcourier\*O. ...\" .zZ "def,13377,R1.2 add default" .LI "\*Lcheckinterval\*O" Specifies the amount of time between checks for faulty servers. Applicable only to servers that have external time-providers. The default is \*L0-01:30:00.00\*O, and the range of the possible values is \*L0-00:00:30.000 - 10675199-02:48:05.478\*O. .LI "\*Lcourierrole\*O" Specifies a server's interaction with the set of global servers. Possible values are as follows: .VL .LI "\*Lbackup\*O" The local server becomes a courier if none are available on the local area network (LAN). This is the default. .LI "\*Lcourier\*O" The local server synchronizes with the global set of servers. .LI "\*Lnoncourier\*O" The local server does not synchronize with the global set of servers. .LE .LI "\*Lepoch\*O" Specifies the server's epoch number. The default is \*L0\*O, and the range of possible values is \*L0-255\*O. This value may not be changed via the \*Lmodify\*O command; use the \*Lclock set\*O command with the \%\*L-epoch\*O option to change its value. ...\" .zA "def,13377,R1.2 delete lastsync" ...\" .LI "\*Llastsync\*O" ...\" Specifies the computed time at the start of the last synchronization. ...\" .zZ "def,13377,R1.2 delete lastsync" .LI "\*Lprovider\*O" Specifies whether or not the entity used an external time-provider at the last successful synchronization. This attribute applies to servers only and may not be set by a user. The value is either \*Lyes\*O or \*Lno\*O. .LI "\*Lserverentry\*O" Specifies a server's access control list (ACL) entry name. The default setting is the following recommended value: \*Lhosts/\*Vhostname\*L/dts-entity\*O. .LI "\*Lservergroup\*O" Specifies the security group name for the time servers within the cell. The default is \*Lsubsys/dce/dts-servers\*O. .LI "\*Lserverprincipal\*O" Specifies a server's principal name for authentication purposes. The default setting is the following recommended value: \*Lhosts/\*Vhostname\*L/self\*O. .LI "\*Luuid \*Vuuid\*O" Specifies the entity's unique identifier, which is generated when the entity is created. .LE .SS "General Counters" .VL .LI "\*Labrupts\*O" Specifies the number of times the node clock has been set nonmonotonically (abruptly). .LI "\*Lbadlocalservers\*O" Specifies the number of times that a local server was contacted, but it was not in the dts security group. .LI "\*Lbadprotocols\*O" Specifies the number of times the local node failed to process a received message containing an incompatible protocol version. .LI "\*Lbadtimereps\*O" Specifies the number of times the local node failed to process a received message containing an incompatible timestamp format. .LI "\*Lcreationtime\*O" Specifies the time at which the DTS entity was created and the counters were initialized. .LI "\*Ldisables\*O" Specifies the number of times the DTS has been disabled. .LI "\*Lenables\*O" Specifies the number of times the DTS has been enabled. ...\" .zA "def,13377,R1.2 nointersections to nolocalintersections" .LI "\*Lnolocalintersections\*O" Specifies the number of times the node's time interval failed to intersect with the computed interval of the servers. ...\" .zZ "def,13377,R1.2 nointersections to nolocalintersections" .LI "\*Lnomemories\*O" Specifies the number of times the node has been unable to allocate virtual memory. .LI "\*Lprovidertimeouts\*O" Specifies the number of times a \*Ldtsd\*O server process initiated contact with a time-provider and did not receive the initial response within the interval specified by the \*Llocaltimeout\*O attribute. .LI "\*Lsyncs\*O" Specifies the number of times the node successfully synchronized. .LI "\*Lsyserrors\*O" Specifies the number of times a DTS process detected a system error. .LI "\*Ltoofewservers\*O" Specifies the number of times a node failed to synchronize because it could not contact the required minimum number of servers. .LE .SS "DTS Server Counters" .VL .LI "\*Lbadservers\*O" Specifies the number of times that a nonlocal server was contacted, but it was not in the dts security group. .LI "\*Ldiffepochs\*O" Specifies the number of times the node received time response messages from servers or clerks that had epoch numbers different from its own. .LI "\*Lepochchanges\*O" Specifies the number of times the server's epoch has changed. .LI "\*Lnoglobals\*O" Specifies the number of times the courier server could not contact any global servers. .LI "\*Lnoresponses\*O" Specifies the number of times the courier server could not contact a specific global server. ...\" .zA "def,13377,R1.2,faultyservers to noserverintersections" .LI "\*Lnoserverintersections\*O" Specifies the number of times a server has detected faulty servers (other than itself). ...\" .zZ "def,13377,R1.2,faultyservers to noserverintersections" .LI "\*Lproviderfailures\*O" Specifies the number of times the external time-provider signaled a failure, or the node was unable to access the time-provider. ...\" .zA "def,13377,R1.2,syncattempts to updates" .LI "\*Lupdates\*O" Specifies the number of times a server has attempted to synchronize its clock. ...\" .zZ "def,13377,R1.2,syncattempts to updates" .LE .PP See the \*VOSF DCE Administration Guide\*O for more information about DTS attributes. ...\" See the \*(Ag for more information about DTS attributes. .SH "OPERATIONS" .PP ...\" .SS "dts activate" .PP Changes a DTS entity from an inactive state to an active state. The syntax is as follows: .sS \*Ldts activate \*O[\*Vdts_server\*O] [\*L-abruptly\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-abruptly\*O" Specifies to set the clock abruptly rather than gradually adjust it to the computed time. .LE .PP The \*Lactivate\*O operation changes a DTS entity from an inactive state to an active state. The \*Lstatus\*O attribute is changed to \*Lenabled\*O. This tells the DTS entity to begin synchronizing. This operation takes an \%\*L-abruptly\*O option to determine if the first clock adjustment due to synchronization is an abrupt or gradual one, and returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission on the DTS entity in order to execute the command. .PP \*LExamples\*O .PP The following example activates a \*Ldtsd\*O on the local host: .oS dcecp> \*Ldts activate\*C dcecp> .oE .PP The following example activates a \*Ldtsd\*O on a remote host named \*Lcyclops\*O: .oS dcecp> \*Ldts activate /.:/hosts/cyclops/dts-entity\*C dcecp> .oE .SS "dts catalog" .PP Returns a list of the names of all DTS servers registered in the default LAN profile. The syntax is as follows: ...\" .zA "def,13377,R1.2.2,add -global" .sS \*Ldts catalog \*O[\*Vcell_name\*O] [\*L-simplename\*O] [\*L-global\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-simplename\*O" Returns a list of registered DTS servers without prepending the cell name. .LI "\*L-global\*O" Returns a list of registered global DTS servers. ...\" .zZ "def,13377,R1.2.2,add -global" .LE .PP The \*Lcatalog\*O operation returns a list of the names of all DTS servers registered in the default LAN profile. ...\" .zA "def,13377,R1.2.2,added additional LAN profile" Any DTS servers registered in an additional LAN profile will also be returned. The additional LAN profile must exist at the root (\*L/.:\*O) level of the CDS namespace. ...\" .zA "def,13377,R1.2.2,added additional LAN profile" The operation takes an optional \*Vcellname\*O argument that can return the names of DTS servers registered in a foreign cell. By default, fully qualified names are returned in the following form: .oS \*L/.../\*Vcellname\*L/hosts/\*Vhostname\*L/dts-entity .oE If the \%\*L-simplename\*O option is given, then the cell name is not prepended to the DTS server names. ...\" .zA "def,13377,R1.2.2,add -global" The \%\*L-global\*O option returns only DTS servers that are operating as global servers. Names are returned in lexical ...\" .zZ "def,13377,R1.2.2,add -global" order. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the cell root (\*L/.:\*O) directory. .PP \*LExamples\*O .PP ...\" .zA "1.1, added -simplename example" .oS dcecp> \*Ldts catalog\*C /.../my_cell.goodcompany.com/hosts/frick/dts-entity /.../my_cell.goodcompany.com/hosts/ice/dts-entity /.../my_cell.goodcompany.com/hosts/ninja/dts-entity dcecp> dcecp> \*Ldts catalog -simplename\*C hosts/frick/dts-entity hosts/ice/dts-entity hosts/ninja/dts-entity dcecp> .oE ...\" .zZ "1.1, added -simplename example" .SS "dts configure" .PP Configure the local \*Ldtsd\*O as a local or global server. The syntax is as follows: .sS \*Ldts configure \*O[\*Vdts_server\*O] {\*L-global\*O | \*L-notglobal\*O} .sE .PP \*LOptions\*O .PP .VL .LI "\*Lglobal\*O" Configures the system as a global server by adding the server's entry to the cell profile .LI "\*Lnotglobal\*O" Configures the system as a local server by removing the server's entry from the cell profile .LE .PP The \*Lconfigure\*O operation sets the local \*Ldtsd\*O to be a local or global server. You must specify either the \*L-global\*O or \%\*L-notglobal\*O option to indicate whether you want to configure the local \*Ldtsd\*O as a global server or not. The difference is whether they are listed in the \*L/.:/cell-profile\*O. This command returns the string \*Lglobal\*O or \*Lnotglobal\*O to indicate the current (new) state of the \*Ldtsd\*O. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission on the DTS entity in order to execute the command. .PP \*LExamples\*O .PP The following example sets the local \*Ldtsd\*O to be a global DTS server: .oS dcecp> \*Ldts configure -global\*C global dcecp> .oE .SS "dts deactivate" .PP Changes a DTS entity from an active state to an inactive state. The syntax is as follows: .sS \*Ldts deactivate \*O[\*Vdts_server\*O] .sE .PP The \*Ldeactivate\*O operation changes a DTS entity from an active state to an inactive state. The \*Lstatus\*O attribute is changed to \*Ldisabled\*O. This tells the DTS entity to stop synchronizing. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission on the DTS entity in order to execute the command. .PP \*LExamples\*O .PP .oS dcecp> \*Ldts deactivate\*C dcecp> .oE .SS "dts help" .PP Returns help information about the \*Ldts\*O object and its operations. The syntax is as follows: .sS \*Ldts help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Ldts\*O object. .LE .PP Used without an argument or option, the \*Ldts help\*O command returns brief information about each \*Ldts\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Ldts\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Ldts help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Ldts help\*C activate Activates a DTS entity. catalog Returns a list of DTS servers in the cell. configure Configures current dtsd as 'global' or 'notglobal'. deactivate Deactivates a DTS entity. modify Modifies attributes of the DTS entity. show Displays attributes or counter info of the named dtsd. stop Stops the current dtsd process. synchronize Synchronizes the local dtsd with DTS servers. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "dts modify" .PP Changes attributes of \*Ldtsd\*O processes. The syntax is as follows: .sS ...\" .zA "def,13377,R1.2.2, Clarify syntax" \*Ldts modify \*O[\*Vdts_server\*O] {\*L-change \*Vattribute_list\*O | \*L-\*Vattribute value\*O} ...\" .zZ "def,13377,R1.2.2, Clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-change\*O \*Vattribute_list\*O" Allows you to modify attributes by using an attribute list rather than using individual attribute options. The format of an attribute list is as follows: .iS \*O{{\*Vattribute value\*O}...{\*Vattribute value\*O}} .iE .LI "\*L-\*Vattribute value\*O" As an alternative to using options with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. .LE .PP The \*Lmodify\*O operation changes attributes of \*Ldtsd\*O processes. It allows attributes to be changed with the \%\*L-change\*O option. Attribute options are also supported for all modifiable attributes. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission on the DTS entity in order to execute the command. .PP \*LExamples\*O .PP The following example sets the minimum number of servers needed for DTS operation to 5 for a remote \*Ldtsd\*O: ...\" .zA "def,13377,R1.2,change number of svrs to 5" .oS dcecp> \*Ldts modify ncacn_ip_tcp:130.105.1.227 -minservers 5\*C dcecp> dcecp> \*Ldts modify ncacn_ip_tcp:130.105.1.227 -change {minservers 5} \*C dcecp> .oE ...\" .zZ "def,13377,R1.2,change number of svrs to 5" .SS "dts operations" .PP Returns a list of the operations supported by the \*Ldts\*O object. The syntax is as follows: .sS \*Laccount operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Ldts operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Ldts operations\*C activate catalog configure deactivate modify show stop synchronize help operations dcecp> .oE .SS "dts show" .P Returns attribute information for the specified \*Ldtsd\*O processes. The syntax is as follows: .sS ...\" .zA"def,13377,R1.2.2, Clarify syntax" \*Ldts show \*O[\*Vdts_server\*O] [\*L-all\*O | [\*L-attributes\*O] [\*L-counters\*O]] ...\" .zZ"def,13377,R1.2.2, Clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-attributes\*O" Returns only the attributes for the local \*Ldtsd\*O process. .LI "\*L-counters\*O" Returns only the counters for the local \*Ldtsd\*O process. .LI "\*L-all\*O" Return the attributes and counters for the local \*Ldtsd\*O process. .LE .PP The \*Lshow\*O operation shows attribute information for the specified \*Ldtsd\*O processes. When called with the \%\*L-attributes\*O option, \*Ldts show\*O returns an attribute list giving the values of the attributes listed above. If called with the \%\*L-counters\*O option then counter information is returned. If called with the \*L-all\*O or with both the \*L-attributes\*O and \%\*L-counters\*O options then both attribute and counter information is returned. The default behavior (invoked by using no options) is the same as if the \%\*L-attributes\*O option was used. Attributes and counters are listed in the order they are returned by the server. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission on the DTS entity in order to execute the command. .PP \*LExamples\*O .PP .oS dcecp> \*Ldts show\*C {checkinterval +0-01:30:00.000I-----} {epoch 0} {tolerance +0-00:10:00.000I-----} {tdf -0-05:00:00.000I-----} {maxinaccuracy +0-00:00:00.100I-----} {minservers 2} {queryattempts 3} {localtimeout +0-00:00:05.000I-----} {globaltimeout +0-00:00:15.000I-----} {syncinterval +0-00:02:00.000I-----} {type server} {courierrole backup} {actcourierrole courier} {clockadjrate 10000000 nsec/sec} {maxdriftrate 1000000 nsec/sec} {clockresolution 10000000 nsec} {version V1.0.1} {timerep V1.0.0} {provider no} {autotdfchange no} {nexttdfchange 1994-10-30-01:00:00.000-05:00I0.000} {serverprincipal hosts/medusa/self} {serverentry hosts/medusa/dts-entity} {servergroup subsys/dce/dts-servers} {status enabled} {uuid 000013ed-000b-0000-b8ef-03a4fcdf00a4} dcecp> .oE .SS "dts stop" .PP Stops the \*Ldtsd\*O process. The syntax is as follows: .sS \*Ldts stop \*O[\*Vdts_server\*O] .sE .PP The \*Lstop\*O operation stops the \*Ldtsd\*O process. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission on the DTS entity in order to execute the command. .PP \*LExamples\*O .PP The following example stops the \*Ldtsd\*O process on remote host named \*Lcyclops\*O: .oS dcecp> \*Ldts stop /.:/hosts/cyclops/dts-entity\*C dcecp> .oE .SS "dts synchronize" .PP Causes \*Ldtsd\*O to synchronize with DTS servers. The syntax is as follows: .sS \*Ldts synchronize \*O[\*Vdts_server\*O] [\*L-abruptly\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-abruptly\*O" Specifies to set the clock abruptly rather than gradually adjust it to the computed time. .LE .PP The \*Lsynchronize\*O operation causes \*Ldtsd\*O to synchronize with DTS servers. The machine's clock is adjusted accordingly. By default the clock is adjusted gradually. This command also takes the optional \%\*L-abruptly\*O option to set the clock abruptly. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission on the DTS entity in order to execute the command. .PP \*LExamples\*O .PP The following example causes the local \*Ldtsd\*O process to synchronize with other DTS servers in the cell: .oS dcecp> \*Ldts synchronize \*C dcecp> .oE .PP The following example causes the \*Ldtsd\*O process on a remote host named \*Lcyclops\*O to synchronize immediately with other DTS servers in the cell: .oS dcecp> \*Ldts synchronize /.:/hosts/cyclops/dts-entity -abruptly \*C dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_clock(1m)\*O, \*Ldcecp_utc(1m)\*O, \*Ldtsd(1m)\*O, \*Ldts_intro(1m)\*O. ...\" \*Ldcecp(1m)\*O ...\" \*Lclock(1m)\*O, ...\" \*Ldtsd(1m)\*O, ...\" \*Ldts_intro(1m)\*O, ...\" \*Lutc(1m)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH endpoint 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lendpoint\*O" .iX "endpoint" "administering" .SH NAME .PP \*Lendpoint\*O - A \*Ldcecp\*O object that manages endpoint information in local RPC endpoint maps .SH "SYNOPSIS" .sS \*Lendpoint create -interface \*Vinterface_id\*L -binding \*Vprotocol_sequence_list\*O .nL [\*L-object \*Vobject_uuid_list\*O] [\*L-annotation \*Vannotation\*O] [\*L-noreplace\*O] .PP \*Lendpoint delete -interface \*Vinterface_id\*L -binding \*Vprotocol_sequence_list\*O .nL [\*L-object \*Vobject_uuid_list\*O] .PP \*Lendpoint help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lendpoint operations .PP ...\" .zA "def,13377,R1.2.2 Clarify syntax" \*Lendpoint show \*O[\*Vhost_address\*O] [\*L-uuid\*O | .nL \*L-interface \*Vinterface_id\*O [\*L-version \*Vversions\*O] [\*L-object \*Vobject_uuid_list\*O]] ...\" .zZ "def,13377,R1.2.2 Clarify syntax" .sE .SH "ARGUMENTS" .VL .LI "\*Vhost_address\*O" A protocol sequence identifying the host whose endpoint map is to be returned. See the \*LDATA STRUCTURES\*O section for the format of \*Vhost_address\*O. .LI "\*Voperation\*O" The name of the \*Lendpoint\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Lendpoint\*O object operates on remote procedure call (RPC) endpoint mappings on the local host. Endpoints contain an interface identifier and one or more string bindings; optionally they contain object Universal Unique Identifiers (UUIDs) and an annotation. .PP Endpoint mappings are stored in the endpoint map maintained by the DCE daemon (\*Ldced\*O) for DCE Version 1.1 hosts. DCE Version 1.0 uses the RPC daemon (\*Lrpcd\*O) to maintain the endpoint map. The \*Lserver\*O object has some operations (for example, \*Ldisable\*O and \*Lenable\*O) that affect endpoints maintained by \*Ldced\*O. However, \*Lserver\*O object operations do not operate on endpoints maintained by DCE Version 1.0 hosts. The \*Lendpoint\*O object affects all endpoint maps on the local host, whether maintained by \*Lrpcd\*O or \*Ldced\*O. .PP Since endpoints have no names, the arguments to these operations is not the name of an endpoint. Earlier versions of \*Lrpcd\*O allowed remote access to endpoints, but this was a security problem. Only the \*Lendpoint show\*O command allows access to endpoint maps on remote systems. The \*Lserver\*O object allows some remote operations on \*Ldced\*O endpoint maps which are free of the security problem, depending on how \*Ldced\*O is configured. .PP Use the various \*Lendpoint\*O operations to create, delete, and show RPC endpoint information in local host endpoint maps. ...\" .SH "DATA STRUCTURES" .VL .LI "\*Vinterface_id\*O" The interface identifier of an RPC interface. The interface identifier takes the following form: .iS \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .iE The version numbers are optional, but if you omit a version number, the value defaults to 0. The UUID is a hexadecimal string and the version numbers are decimal strings. For example: .iS \&-interface ec1eeb60-5943-11c9-a309-08002b102989,3.11 .iE Leading zeros in version numbers are ignored. .PP Alternatively, you can use \*Ldcecp\*O string syntax in the following form: .iS {\*Vinterface-UUID major-version.minor-version\*O} .iE For example: .iS \&-interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0} .iE .PP .LI "\*Vprotocol_sequence_list\*O" An RPC string binding that describes a server's location. The value has the form of an RPC string binding, without an object UUID. The binding information contains an RPC protocol, a network address, and (sometimes) an endpoint within \*L[]\*O (square brackets) as follows: .iS \*Vrpc-prot-seq\*L:\*Vnetwork-addr\*L[\*Vendpoint\*L] .iE For a well-known endpoint, include the endpoint in the string binding surrounded by brackets. You may need to use the \*L\\\*O (backslash) to escape the brackets as shown in the following example. Otherwise \*Ldcecp\*O interprets the brackets as enclosing another command. .iS \&-binding ncadg_ip_udp:63.0.2.17\\[5347\\] .iE .PP For a dynamic endpoint, omit the endpoint from the string binding, for example: .iS \&-b ncacn_ip_tcp:16.20.15.25 .iE .PP Alternatively, you can use \*Ldcecp\*O string syntax. For example: .iS \&-binding {ncacn_ip_tcp 130.105.1.227 1072} .iE .LI "\*Vobject_uuid\*O" The UUID of an object. The UUID is a hexadecimal string, for example: .iS \&-object 3c6b8f60-5945-11c9-a236-08002b102989 .iE .PP Alternatively, you can use \*Ldcecp\*O string syntax. For example: .iS \&-object {3c6b8f60-5945-11c9-a236-08002b102989} .iE .LI "\*Vhost_address\*O" An RPC string binding that describes a host's location. The binding information contains an RPC protocol and the host's network address. Any specific host's network address can be obtained by using the \*Lgetip\*O command. .LI "\*Vannotation\*O" An informational text string that helps you to identify the purpose of the endpoint. Use single or double quotation marks around the annotation field of endpoints to include internal spaces in an annotation, for example: .iS \&-annotation "Bulletin Board Server, Version 1.3a" .iE .PP Alternatively, you can use \*Ldcecp\*O string syntax. For example: .iS \&-annotation {Bulletin Board Server, Version 1.3a} .iE .LI "\*Vversion\*O" Specifies which interface version numbers to be returned with a \*Lshow\*O operation. Specify versions by using one of the following values for the \%\*L-version\*O option: .VL 1i .LI "\*Lall\*O" The interface version is ignored. .LI "\*Lexact\*O" Both the major and minor versions must match the specified versions. .LI "\*Lcompatible\*O" The major version must match the specified version, and the minor version must be greater than or equal to the specified version. .LI "\*Lmajor_only\*O" The major version must match the specified version; the minor version is ignored. .LI "\*Lupto\*O" The major version must be less than or equal to that specified. If the major versions are equal, the minor version must be less than or equal to that specified. .LE .P If the \%\*L-version\*O option is absent, the command shows \*Lcompatible\*O version numbers. .LE .SH "OPERATIONS" .PP ...\" .SS "endpoint create" Creates new endpoints in the local endpoint map database. The syntax is as follows: .sS \*Lendpoint create -interface \*Vinterface_id\*L -binding \*Vprotocol_sequence_list\*O .nL [\*L-object \*Vobject_uuid_list\*O] [\*L-annotation \*Vannotation\*O] [\*L-noreplace\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-interface \*Vinterface_id\*O This required option declares the interface identifier of a single RPC interface. ...\" .zA "def,13377,R1.2.2,deletion;no multiple IDs" ...\" .zZ "def,13377,R1.2.2,deletion;no multiple IDs" .PP See \*LDATA STRUCTURES\*O for the format of the interface identifier. .LI "\*L-binding \*Vprotocol_sequence_list\*O This required option declares a list of one or more protocol sequences (RPC string bindings). .PP See \*LDATA STRUCTURES\*O for the format of a protocol sequence. .LI "\*L-object \*Vobject_uuid_list\*O Declares the UUID of an object. Each \*Lcreate\*O operation accepts a list of up to 32 object UUIDs. .PP See \*LDATA STRUCTURES\*O for the format of the object UUID. .LI "\*L-annotation \*Vannotation\*O Defines an annotation string for the endpoint. The annotation string enables you to identify the purpose of the endpoint. The annotation can be any textual information, for example, an interface name associated with the interface identifier or a description of a service or resource associated with a group. .PP Use quotation marks around the annotation field of endpoints to include internal spaces in an annotation, or use \*Ldcecp\*O syntax. .LI "\*L-noreplace\*O Use the \%\*L-noreplace\*O option when you want a host to run multiple instances of a server. Normally, when you add an interface-binding combination (a mapping) that already exists in an endpoint map, \*Ldcecp\*O replaces the existing mapping with the new one. This behavior limits the number of server instances to one. Bypass this limitation by using the \%\*L-noreplace\*O option. Using this option can cause obsolete endpoints to accumulate in the endpoint map. Remove obsolete endpoints by using the \*Lendpoint delete\*O command. .LE .PP The \*Lcreate\*O operation creates new endpoints in the endpoint map database on the local host. This command takes no arguments. It requires the \*L-interface\*O and \%\*L-binding\*O options, and accepts the \*L-object\*O and \%\*L-annotation\*O options. The value of the \*L-binding\*O and \%\*L-object\*O options can be a list, but the others must be a single value. If the mapping already exists it is replaced unless the \%\*L-noreplace\*O option is included. .PP This command creates a cross product from the \*L-interface\*O, \*L-binding\*O and \%\*L-object\*O options and adds each element in the cross product as a separate registration in the local endpoint map. If you supply no object UUIDs, the corresponding elements in the cross product contain a nil object UUID. For example, suppose that you have an interface \*Lif1\*O, three bindings, \*Lb1\*O, \*Lb2\*O, and \*Lb3\*O, and four object UUID\*Os, \*Lo1\*O, \*Lo2\*O, \*Lo3\*O and \*Lo4\*O. The resulting 12 elements in the cross product are as follows: .oS {if1,b1,o1} {if1,b1,o2} {if1,b1,o3} {if1,b1,o4} {if1,b2,o1} {if1,b2,o2} {if1,b2,o3} {if1,b2,o4} {if1,b3,o1} {if1,b3,o2} {if1,b3,o3} {if1,b3,o4} .oE .PP An annotation string is part of each of these 12 elements, but is not shown for clarity. .PP This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lendpoint create\*O command. .PP \*LExamples\*O .PP The following command adds an endpoint to the local host's endpoint map. This example uses backslashes to escape the brackets. Otherwise \*Ldcecp\*O interprets the brackets as enclosing another command. .oS dcecp> \*Lendpoint create -interface 458ffcbe-98c1-11cd-bd93-0000c08adf56 \\\*C > \*L-binding ncacn_ip_tcp:130.105.1.227\\[1067\\]\*C dcecp> .oE .PP The following example uses the \*Ldcecp\*O string syntax to create an endpoint in the local host's endpoint map. .oS dcecp> \*Lendpoint create -interface {458ffcbe-98c1-11cd-bd93-0000c08adf56,1.0} \\\*C > \*L-binding {ncacn_ip_tcp 130.105.1.227 1072} \\\*C > \*L-object {76030c42-98d5-11cd-88bc-0000c08adf56} \\\*C > \*L-annotation {Bulletin Board Server, Version 1.3a}\*C dcecp> .oE .SS "endpoint delete" Deletes the specified endpoints from the local endpoint map database. The syntax is as follows: .sS \*Lendpoint delete -interface \*Vinterface_id\*L -binding \*Vprotocol_sequence_list\*O .nL [\*L-object \*Vobject_uuid_list\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-interface \*Vinterface_id\*O This required option declares the interface identifier of a single RPC interface. ...\" .zA "def,13377,R1.2.2,deletion;no multiple IDs" ...\" .zZ "def,13377,R1.2.2,deletion;no multiple IDs" .PP See \*LDATA STRUCTURES\*O for the format of the interface identifier. .LI "\*L-binding \*Vprotocol_sequence_list\*O This required option declares a list of one or more protocol sequences (RPC string bindings). .PP See \*LDATA STRUCTURES\*O for the format of a protocol sequence. .LI "\*L-object \*Vobject_uuid_list\*O Declares the UUID of an object. Each \*Ldelete\*O operation accepts a list of up to 32 object UUIDs. The UUID is a hexadecimal string. .PP See \*LDATA STRUCTURES\*O for the format of the object UUID. .LE .PP The \*Ldelete\*O operation deletes the specified endpoints from the endpoint map database. This command takes no arguments. It requires the \*L-interface\*O and \%\*L-binding\*O options, and also accepts the \%\*L-object\*O option. The values of all but the \%\*L-interface\*O option may be lists. If the mappings do not exist an error is generated. .PP This command creates a cross product from the \*L-interface\*O, \*L-binding\*O and \%\*L-object\*O options and removes each element in the cross product from the local endpoint map. See the \*Lendpoint create\*O command above for more details. .PP This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lendpoint delete\*O command. .PP \*LExamples\*O .PP The following command removes an endpoint object from the local host's endpoint map. This example uses backslashes to escape the brackets. Otherwise \*Ldcecp\*O interprets the brackets as enclosing another command. .oS dcecp> \*Lendpoint delete -interface 458ffcbe-98c1-11cd-bd93-0000c08adf56,1.0 \\\*C > \*L-binding ncacn_ip_tcp:130.105.1.227\\[1072\\] \*C dcecp> .oE .PP The following example uses the \*Ldcecp\*O string syntax to delete an endpoint from the local host's endpoint map. .oS dcecp> \*Lendpoint delete -interface {458ffcbe-98c1-11cd-bd93-0000c08adf56,1.0} \\\*C > \*L-binding {ncacn_ip_tcp 130.105.1.227 1072} \*C dcecp> .oE .SS "endpoint help" .PP Returns help information about the \*Lendpoint\*O object and its operations. The syntax is as follows: .sS \*Lendpoint help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-verbose Displays information about the \*Lendpoint\*O object. .LE .PP Used without an argument or option, the \*Lendpoint help\*O command returns brief information about each \*Lendpoint\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lendpoint\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lendpoint help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lendpoint help\*C create Creates RPC endpoints for the specified interface. delete Deletes a set of RPC endpoints. show Returns the RPC endpoints for a specified interface. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "endpoint operations" .PP Returns a list of the operations supported by the \*Lendpoint\*O object. The syntax is as follows: .sS \*Lendpoint operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lendpoint operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lendpoint operations\*C create delete show help operations dcecp> .oE .SS "endpoint show" .PP Returns a list of information about endpoints for the local host or a remote host. The syntax is as follows: .sS ...\" .zA "def,13377,R1.2.2 Clarify syntax" \*Lendpoint show \*O[\*Vhost_address\*O] [\*L-uuid\*O | .nL \*L-interface \*Vinterface_id\*O [\*L-version \*Vversions\*O] [\*L-object \*Vobject_uuid_list\*O]] ...\" .zZ "def,13377,R1.2.2 Clarify syntax" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-uuid\*O Specifies that the UUID of the endpoint map is to be returned. It cannot be used with any other option. .LI "\*L-interface \*Vinterface_id\*O This option specifies the interface identifier of a single RPC interface for which you want to see the endpoint mapping information. ...\" .zA "def,13377,R1.2.2,deletion;no multiple IDs" ...\" .zZ "def,13377,R1.2.2,deletion;no multiple IDs" .PP See \*LDATA STRUCTURES\*O for the format of the interface identifier. .LI "\*L-version \*Vversions\*O Specifies interface version numbers to be returned with the \*Lshow\*O operation. .PP See \*LDATA STRUCTURES\*O for the exact behavior and format of the version values. .LI "\*L-object \*Vobject_uuid_list\*O Declares the UUID of an object. Each \*Lshow\*O operation accepts a list of up to 32 object UUIDs. .PP See \*LDATA STRUCTURES\*O for the format of the object UUID. ...\" .cS ...\" ...\" The following function is not implemented in DCE 1.1: ...\" .LI "\*L-host \*Vhostname_list\*O ...\" The \%\*L-host\*O option lets you specify a list of one or more hosts on ...\" which to delete or show endpoint map information. The ...\" \*Vhost_address_list\*O argument is a list of one or more string ...\" bindings that indicate where to find the target endpoint maps. When ...\" accessing the local endpoint map, you can optionally specify which ...\" protocol sequence to use. ...\" .PP ...\" See \*LDATA STRUCTURES\*O for the format of a host address. ...\" .cE .LE ...\" .zA "1.1, CR13083" .PP The \*Lshow\*O operation returns a list of information about endpoints in the endpoint map of a local or remote host. With no options, it returns all the local endpoint mappings. The \*L-interface\*O, \*L-version\*O, and \%\*L-object\*O options can be used so that only those endpoint mappings matching the supplied values are returned. The \*L-object\*O option accepts a list as a value; the others do not. The optional \*Vhost_address\*O argument is the address of the remote host whose endpoint map is to be shown. If no argument is supplied, the local host's endpoint map is used. .PP See \*LDATA STRUCTURES\*O for the format of a host address. ...\" .zZ "1.1, 13083" .PP If the \%\*L-uuid\*O option is specified, then the UUID of the specified host's endpoint map is to be returned, rather than any information about the endpoints themselves. Each endpoint map is given a UUID on creation. If you know the current UUID of an endpoint map, you can delete any other stale UUIDs that may be in the RPC entry. If you specify the \%\*L-uuid\*O option, you must not specify any other options. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lendpoint show\*O command. .PP \*LExamples\*O ...\" .zA "1.1, CR13083" .PP The following example uses \*Ldcecp\*O string syntax to specify an interface for which to return local endpoint map information: .oS dcecp> \*Lendpoint show -interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0}\*C {{object 76030c42-98d5-11cd-88bc-0000c08adf56} {interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0}} {binding {ncacn_ip_tcp 130.105.1.227 1072}} {annotation {Bulletin Board Server, Version 1.3a}}} dcecp> .oE ...\" .zZ "1.1, CR13083" .PP The following command returns the endpoint objects in the local endpoint map that contain the specified interface identifier. This interface supports two object UUIDs on two protocol sequences: .oS dcecp> \*Lendpoint show -interface 257df1c9-c6d3-11ca-8554-08002b1c8f1f,1.0\*C {{object a57104f4-dfd0-11ca-b428-08002b1c8a62} {interface {257df1c9-c6d3-11ca-8554-08002b1c8f1f 1.0}} {binding {ncacn_ip_tcp 130.105.1.227 1040}} {annotation {cdsd [910]}}} {{object a57104f4-dfd0-11ca-b428-08002b1c8a62} {interface {257df1c9-c6d3-11ca-8554-08002b1c8f1f 1.0}} {binding {ncadg_ip_udp 130.105.1.227 1163}} {annotation {cdsd [910]}}} {{object b32648c6-928d-11cd-b4b5-0000c08adf56} {interface {257df1c9-c6d3-11ca-8554-08002b1c8f1f 1.0}} {binding {ncacn_ip_tcp 130.105.1.227 1042}} {annotation cds_clerkserver}} {{object b32648c6-928d-11cd-b4b5-0000c08adf56} {interface {257df1c9-c6d3-11ca-8554-08002b1c8f1f 1.0}} {binding {ncadg_ip_udp 130.105.1.227 1168}} {annotation cds_clerkserver}} dcecp> .oE .PP The following command returns the UUID of the endpoint map on the host with the specified network address: .oS dcecp> \*Lendpoint show ncadg_ip_udp:130.105.1.227 -uuid\*C 7273c754-e51c-11cd-bc0e-0000c08de054 dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_rpcentry(1m)\*O, \*Ldcecp_rpcgroup(1m)\*O, \*Ldcecp_rpcprofile(1m)\*O, \*Ldcecp_server(1m)\*O. ...\" \*Lrpcentry(1m)\*O, ...\" \*Lrpcgroup(1m)\*O, ...\" \*Lrpcprofile(1m)\*O, ...\" \*Lserver(1m)\*O, .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH group 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lgroup\*O" .iX "group" "administering" .SH NAME .PP \*Lgroup\*O - A \*Ldcecp\*O object that manages a group in the DCE Security Service .SH "SYNOPSIS" ...\" .zA "def,13377,R1.2.2,clarify syntax" .sS \*Lgroup add \*Vgroup_name_list\*L -member \*Vmember_name_list\*O .PP ...\" .zA "1.1, add cell_name" \*Lgroup catalog \*O[\*Vcell_name\*O] [\*L-simplename\*O] ...\" .zZ "1.1, add cell_name" .PP ...\" .zA "1.1, change to extended_registry_attribute_list" \*Lgroup create \*Vgroup_name_list\*O .nL {\*L-attribute \*Vextended_rgy_attr_list\*O | .nL \*L-\*Vattribute value\*O} ...\" .zZ "1.1, change to extended_registry_attribute_list" .PP \*Lgroup delete \*Vgroup_name_list\*O .PP \*Lgroup help \*O[\*Voperation\*O | -verbose\*O] .PP \*Lgroup list \*Vgroup_name_list \*O[\*L-simplename\*O] .PP \*Lgroup modify \*Vgroup_name_list\*O .nL {\*L-add \*Vextended_rgy_attr_list\*O | .nL ...\" .zA "1.1, add -types" \*L-remove \*Vextended_rgy_attr_list\*O [\*L-types\*O] | ...\" .zZ "1.1, add -types" .nL ...\" .zA "1.1, change to extended_registry_attribute_list" \*L-change \*Vextended_rgy_attr_list\*O | .nL \*L-\*Vattribute value\*O} ...\" .zZ "1.1, change to extended_registry_attribute_list" ...\" .zZ "def,13377,R1.2.2,clarify syntax" .PP \*Lgroup operations\*O .PP \*Lgroup remove \*Vgroup_name_list\*L -member \*Vmember_name_list\*O .PP \*Lgroup rename \*Vgroup_name\*L -to \*Vnew_group_name\*L .PP ...\" .zA "def,13377,R1.2.2, Clarify syntax" \*Lgroup show \*Vgroup_name_list \*O[\*L-all \*O| \*L-xattrs\*O] ...\" .zZ "def,13377,R1.2.2, Clarify syntax" .sE .SH "ARGUMENTS" .VL ...\" .zA "1.1, add cell_name" .LI "\*Vcell_name\*O The name of a cell to contact when processing the \*Lcatalog\*O operation. The name must be a fully qualified cell name, such as \*L/.:\*O or \*L/.../\*Vcell_name\*O ...\" .zZ "1.1, add cell_name" .LI "\*Vgroup_name_list\*O" A list of one or more names of groups to act on. Supply the names as either of the following: .ML .LI Fully qualified names in the form: \*L/.../\*Vcell_name\*L/\*Vgroup_name\*O or \*L/.:/\*Vgroup_name\*O .LI Cell-relative names in the form: \*Vgroup_name\*O. These names refer to a group in the cell identified in the \*L_s(sec)\*O convenience variable, or if the \*L_s(sec)\*O convenience variable is not set, in the local host's default cell. .LE .PP Do not mix fully-qualified names and cell-relative names in a list. In addition, do not use the names of registry database objects that contain group information; in other words, do not use names that begin with \*L/.:/sec/group/\*O. .LI "\*Vgroup_name\*O" The name of a group to act on. See \*Vgroup_name_list\*O for the name format. .LI "\*Voperation\*O" The name of the \*Lgroup\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Lgroup\*O object represents registry groups. Unless otherwise noted, all of the operations of this object take the names of the groups to act on as the argument. They must be group names, not the names of the database objects that contain registry information about groups (that is, the names must not begin with \*L/.:/sec/group/\*O. .PP ...\" .zA "def,13230,HP edits" When this command executes, it attempts to bind to the registry server identified in the \*L_s(sec)\*O variable. If that server cannot process the request or if the \*L_s(sec)\*O variable is no set, the command binds to either an available slave server or the master registry server, depending on the operation. Upon completion the command sets the \*L_b(sec)\*O convenience variable to the name of the registry server to which it bound. ...\" .zZ "def,13230,HP edits" ...\" .SH "ATTRIBUTES" .VL .LI "\*Lalias \*Vvalue\*O" Used with the \*Lcreate\*O and \*Lmodify\*O operations, the value of this attribute is either \*Lyes\*O or \*Lno\*O. Although each group can have only one primary name, it can have one or more alias names. All aliases refer to the same group, and therefore, they carry the same Universal Unique Identifier (UUID) and group identifier (GID). While aliases refer to the same group they are separate entries in the registry database. Therefore the name supplied to the \*Lgroup\*O command can refer to the group's primary name or alias name. The value of this attribute determines whether the name is a primary name (\*Lalias no\*O) or an alias name (\*Lalias yes\*O). The default is \*Lno\*O. .LI "\*Lgid \*Vvalue\*O" Used with the \*Lcreate\*O operation to specify the Group Identifier. If this attribute is not present, then a identifier is assigned to the group automatically. .LI "\*Luuid \*Vhexadecimal number\*O" Used with the \*Lcreate\*O operation to "adopt" an orphaned UUID. Normally the UUID for a new group is generated by the registry. In cases where data exists tagged with the UUID of a group that has been deleted from the registry, this attribute can be used with the \*Lcreate\*O operation to specify the old UUID for a new group. The UUID specified must be an orphan; that is a UUID for which no name exists in the registry. An error occurs if you specify a name that is already defined in the registry. If this attribute is not present, a UUID is assigned to the group automatically. .LI "\*Lfullname \*Vstring\*O" Used with the \*Lcreate\*O and \*Lmodify\*O operations to specify the full name of the group to be added to the registry. The value is a string with spaces enclosed in quotes or braces. The \*Lfullname\*O attribute defaults to a null string (that is, blank). .LI "\*Linprojlist \*Vvalue\*O" Used with the \*Lcreate\*O and \*Lmodify\*O operations to include the group in the principal's project list. The value for this option is either \*Lyes\*O or \*Lno\*O. If it is \*Lno\*O, then members of this group will not acquire the access rights of this group. The default is \*Lyes\*O. .LE .PP See the \*VOSF DCE Administration Guide\*O for more information about group attributes. ...\" See the \*(Ag for more information about group attributes. .SH "OPERATIONS" .PP ...\" .SS "group add" .PP Adds members to a security group. The syntax is as follows: .sS \*Lgroup add \*Vgroup_name_list\*L -member \*Vmember_name_list\*O .sE .PP \*LOptions\*O .VL .LI "\*L-member \*Vmember_name_list\*O" A list of one or more names of principals to be added to each group in the argument. .LE .PP The \*Ladd\*O operation adds members to groups identified by \*Vgroup_name_list\*O. The required \*Vmember_name_list\*O is a list of principal names to be added. The principals must exist or the command will return an error. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) and \*LM\*O (\*LMember_list\*O) permissions on the target group and \*Lr\*O (\*Lread\*O) and \*Lg\*O (\*Lgroups\*O) permissions on the principal being added. .PP \*LExamples\*O .PP .oS dcecp> \*Lprincipal create chopin\*C dcecp> dcecp> \*Lgroup add users -member chopin \*C dcecp> .oE .SS "group catalog" .PP Returns a list of the names of all groups in the registry. The syntax is as follows: ...\" .zA "1.1, add cell_name" .sS \*Lgroup catalog \*O[\*Vcell_name\*O] [\*L-simplename\*O] .sE ...\" .zZ "1.1, add cell_name" .PP \*LOptions\*O .VL .LI "\*L-simplename\*O" Returns a list of group names in the registry without prepending the cell name. .LE .PP The \*Lcatalog\*O operation returns a list of the names of all groups in the local registry database. Use the \*Vcell_name\*O argument to return a list of groups in another cell's registry. By default, fully qualified names are returned in the form \*Vcell_name\*L/\*Vgroup_name\*O. Use the \%\*L-simplename\*O option to return the names without the cell name in the form \*Vgroup_name\*O. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the \*L/.:/sec/group\*O directory. .PP \*LExamples\*O .PP ...\" .zA "1.1, add -simplename example" .oS dcecp> \*Lgroup cat\*C /.../my_cell.goodcompany.com/nogroup /.../my_cell.goodcompany.com/system /.../my_cell.goodcompany.com/daemon /.../my_cell.goodcompany.com/uucp /.../my_cell.goodcompany.com/bin /.../my_cell.goodcompany.com/kmem /.../my_cell.goodcompany.com/mail /.../my_cell.goodcompany.com/tty /.../my_cell.goodcompany.com/none /.../my_cell.goodcompany.com/tcb /.../my_cell.goodcompany.com/acct-admin /.../my_cell.goodcompany.com/subsys/dce/sec-admin /.../my_cell.goodcompany.com/subsys/dce/cds-admin /.../my_cell.goodcompany.com/subsys/dce/dts-admin /.../my_cell.goodcompany.com/subsys/dce/cds-server /.../my_cell.goodcompany.com/subsys/dce/dts-servers /.../my_cell.goodcompany.com/users dcecp> dcecp> \*Lgroup cat -simplename\*C nogroup system daemon uucp bin kmem mail tty none tcb acct-admin subsys/dce/sec-admin subsys/dce/cds-admin subsys/dce/dts-admin subsys/dce/cds-server subsys/dce/dts-servers subsys/dce/audit-admin subsys/dce/dced-admin dcecp> .oE ...\" .zZ "1.1, add -simplename example" .SS "group create" .PP ...\" .zA "1.1, change to extended_registry_attribute_list" Creates a new group in the registry database. The syntax is as follows: .sS \*Lgroup create \*Vgroup_name_list\*O .nL ...\" .zA "def,13377,R1.2.2, Clarify syntax" {\*L-attribute \*Vextended_rgy_attr_list\*O | .nL \*L-\*Vattribute value\*O} .sE .PP \*LOptions\*O .VL .LI "\*L-\*Vattribute value\*O" As an alternative to using the \*L-attribute\*O option with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. You cannot use this option to specify ERAs; it is only for the standard attributes described in \*LATTRIBUTES\*O. .LI "\*L-attribute \*Vextended_rgy_attr_list\*O" Allows you to specify attributes, including ERAs, by using an attribute list rather than using the \*L-\*Vattribute value\*O option. The format of an attribute list is as follows: .iS {{\*Vextended_rgy_attr_list \*Vvalue\*O}...{\*Vextended_rgy_attr_list \*Vvalue\*O}} .iE .PP See the \*LOSF DCE Administration Guide\*O for more information on ERAs. ...\" See the \*(Ag for more information on ERAs. ...\" .zZ "def,13377,R1.2.2, Clarify syntax" ...\" .zZ "1.1, change to extended_registry_attribute_list" .LE .PP The \*Lcreate\*O operation creates a new group in the registry database. The argument is a list of names of groups to be created. Options are used to specify the attributes of the newly created group. All options are applied to all groups in the argument. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Li\*O (\*Linsert\*O) permission to the directory in which the group is to be created. .PP \*LExamples\*O .PP .oS dcecp> \*Lgroup create users4 -attribute {fullname "temporary users"}\*C dcecp> .oE .SS "group delete" .PP Deletes groups from the registry. The syntax is as follows: .sS \*Lgroup delete \*Vgroup_name_list\*O .sE .PP The \*Ldelete\*O operation deletes groups from the registry. When a group is deleted, any accounts associated with the group are deleted as well. The argument is a list of names of groups to be deleted. If a named group does not exist an error is generated. This operation returns an empty string on success. .PP This operation also deletes any accounts associated with groups that are deleted. To preserve accounts, add the desired principles to a different group by using the \*Lgroup add -member\*O command. Modify the principals' accounts to point to the new group by using the \*Laccount modify\*O command. Then you can delete the group by using the \*Lgroup delete\*O command. .PP \*LPrivileges Required\*O .PP You must have \*Ld\*O (\*Ldelete\*O) permission to the directory in which the target group exists. You must have \*Lr\*O (\*Lread\*O) and \*LD\*O (\*LDelete_object\*O) permission on the group to be deleted. .PP \*LExamples\*O .PP .oS dcecp> \*Lgroup delete users4\*C dcecp> .oE .SS "group help" .PP Returns help information about the \*Lgroup\*O object and its operations. The syntax is as follows: .sS \*Lgroup help \*O[\*Voperation\*O | -verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lgroup\*O object. .LE .PP Used without an argument or option, the \*Lgroup help\*O command returns brief information about each \*Lgroup\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lgroup\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lgroup help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lgroup help\*C add Adds a member to the named group. catalog Returns a list of all the names of groups in the registry. create Creates a group. delete Deletes a group. list Returns all of the members of a group. modify Changes the information about a group. remove Removes a specified member from the named group. rename Renames the specified group. show Returns the attributes of a group. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "group list" .PP Returns a list of the names of all members of a group. The syntax is as follows: .sS \*Lgroup list \*Vgroup_name_list\*O [\*L-simplename\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-simplename\*O" Returns the list of group names in the registry without prepending the cell name. .LE .PP The \*Llist\*O operation returns a list of the names of all members of a group. The argument is a list of names of groups to be operated on. If more than one group is listed, the names are concatenated together on output. By default, fully qualified names are returned in the form \*Vcellname\*L/\*Vmembername\*O. Use the \*L-simplename\*O option to return them without prepending the cell name to the member name. The members of each group are listed in lexical order. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the \*L/.:/sec/group\*O directory. .PP \*LExamples\*O .PP .oS dcecp> \*Lgroup list none\*C /.../my_cell.goodcompany.com/dce-ptgt /.../my_cell.goodcompany.com/dce-rgy /.../my_cell.goodcompany.com/krbtgt/my_cell.goodcompany.com /.../my_cell.goodcompany.com/cell_admin /.../my_cell.goodcompany.com/hosts/pmin17/self dcecp> .oE .SS "group modify" .PP Changes attributes of groups. The syntax is as follows: ...\" .zA "1.1, change to extended_registry_attribute_list" ...\" .zA "1.1, add -types" .sS \*Lgroup modify \*Vgroup_name_list\*O .nL ...\" .zA "def,13377,R1.2.2, Clarify syntax" {\*L-add \*Vextended_rgy_attr_list\*O | .nL \*L-remove \*Vextended_rgy_attr_list\*O [\*L-types\*O] | .nL \*L-change \*Vextended_rgy_attr_list\*O | .nL \*L-\*Vattribute value\*O} ...\" .zZ "def,13377,R1.2.2, Clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-\*Vattribute value\*O" As an alternative to using options with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. You cannot use this option to specify ERAs; it is only for standard group attributes described in \*LATTRIBUTES\*O. .LI "\*L-add\*O \*Vextended_rgy_attr_list\*O" Allows you to modify attributes, including ERAs, by using an attribute list rather than using individual attribute options. The format of an attribute list is as follows: .iS {{\*Vextended_rgy_attr_list \*Vvalue\*O}...{\*Vextended_rgy_attr_list \*Vvalue\*O}} .iE .PP ...\" .zA "def,13377,R1.2.2, Clarify syntax" .LI "\*L-change \*Vextended_rgy_attr_list\*O" ...\" .zZ "def,13377,R1.2.2, Clarify syntax" Allows you to modify attributes, including ERAs, by using an attribute list rather than using individual attribute options. See the \*L-add\*O option for the attribute list format. ...\" .zA "def,13377,R1.2.2, Clarify syntax" .LI "\*L-remove\*O \*Vextended_rgy_attr_list\*O" Allows you to modify attributes, including ERAs, by using an attribute list rather than using individual attribute options such as \%\*L-alias\*O, \%\*L-inprojlist\*O, and so on. See the \*L-add\*O option for the attribute list format. .PP Without the \%\*L-types\*O option, \*L-remove\*O deletes individual attribute instances attached to the group. In this case, \*Vextended_rgy_attr_list\*O is a list of attribute-value pairs. With the \%\*L-types\*O option, \*L-remove\*O deletes attribute types (and all instances of that type) attached to the group. In this case, \*Vextended_rgy_attr_list\*O is a list of attribute types. ...\" .zZ "def,13377,R1.2.2, Clarify syntax" .LI "\*L-types\*O" Used with the \%\*L-remove\*O option to remove attribute types (and all instances of that type) attached to the group. .LE See the \*VOSF DCE Administration Guide\*O for more information about ERAs. ...\" See the \*(Ag for more information about ERAs. ...\" .zZ "1.1, add -types" ...\" .zZ "1.1, change to extended_registry_attribute_list" .PP The \*Lmodify\*O operation changes attributes of groups. The argument is a list of names of groups to be operated on. All modifications are applied to all groups named in the argument. Groups are modified in the order they are listed and all modifications to an individual group are atomic. Modifications to multiple groups are not atomic. A failure for any one group in a list causes an error to be generated and the rest of the operation to be aborted. This operation returns an empty string on success. .P The \%\*L-change\*O option can be used to modify the value of any standard attribute except for \*Lgid\*O and \*Luuid\*O. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) and \*Lm\*O (\*Lmgmt_info\*O) permission to the group to be modified. .PP \*LExamples\*O .PP .oS dcecp> \*Lgroup modify users3 -change {fullname "General Nursing Staff"}\*C dcecp> dcecp> \*Lgroup show users3\*C {alias no} {gid 5212} {uuid 0000145c-9363-21cd-a601-0000c08adf56} {inprojlist no} {fullname {General Nursing Staff}} dcecp> dcecp> \*Lgroup modify users3 -add {test_era 101} \*Cdcecp> \*Lgroup show users3\*C {alias no} {gid 5212} {uuid 0000145c-9363-21cd-a601-0000c08adf56} {inprojlist no} {fullname {General Nursing Staff} {test_era 101}} dcecp> .oE .SS "group operations" .PP Returns a list of the operations supported by the \*Lgroup\*O object. The syntax is as follows: .sS \*Lgroup operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lgroup operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lgroup operations\*C add catalog create delete list modify remove rename show help operations dcecp> .oE .SS "group remove" .P Removes a member from a group. The syntax is as follows: .sS \*Lgroup remove \*Vgroup_name_list\*L -member \*Vmember_name_list\*O .sE .PP \*LOptions\*O .VL .LI "\*L-member \*Vmember_name_list\*O" A list of one or more names of principals to be removed from each group in the argument. .LE .PP The \*Lremove\*O operation removes a member from a group. The argument is a list of names of groups from which to remove members. The value of the required \%\*L-member\*O option is a list of names of principals to remove from the groups listed in the argument. When a member is removed from a group, any accounts associated with that principal and group are deleted. Remember that accounts are associated with a principal, a group, and an organization; so the statement means that any accounts where both the principal name and group name match those given to this command are removed, but accounts where only one matches are untouched. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) and \*LM\*O (\*LMember_list\*O) permissions on the target groups and \*Lr\*O (\*Lread\*O) permission on the member to be removed. .PP \*LExamples\*O .PP .oS dcecp> \*Lgroup remove users -member chopin\*C dcecp> .oE .SS "group rename" .P This operation changes the name of a specified group. The syntax is as follows: .sS \*Lgroup rename \*Vgroup_name\*L -to \*Vnew_group_name\*L .sE .PP \*LOptions\*O .VL .LI "\*L-to \*Vnew_group_name\*O" Specifies the new name of the group. .PP See \*LARGUMENTS\*O for a description of group names. .LE .PP The \*Lrename\*O operation changes the name of a specified group. The argument is a single name of a group to be renamed. The operation takes a required \%\*L-to\*O option with the value of the new name. The value may not be a list. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) and \*Lf\*O (\*Lfull name\*O) permissions to the specified groups. .PP \*LExamples\*O .PP .oS dcecp> \*Lgroup rename users4 -to users_temporary\*C dcecp> .oE .SS "group show" .P Returns registry information for the specified groups. The syntax is as follows: .sS ...\" .zA "def,13377,R1.2.2, Clarify syntax" \*Lgroup show \*Vgroup_name_list\*O [\*L-all\*O | \*L-xattrs\*O] ...\" .zZ "def,13377,R1.2.2, Clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-xattrs\*O" Returns ERAs instead of the default attributes. .LI "\*L-all\*O" Returns ERAs in addition to the default attributes. .LE .PP The \*Lshow\*O operation returns an attribute list for the specified groups. The argument is a list of names of groups to be operated on. If more than one group is given, then the attributes are concatenated together. Use the \*L-xattrs\*O option to return ERAs instead of the standard attributes. Use \*L-all\*O to return both types of attributes. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the specified groups. .PP \*LExamples\*O .PP .oS dcecp> \*Lgroup show users_temporary\*C {alias no} {gid 5211} {uuid 0000145b-9362-21cd-a601-0000c08adf56} {inprojlist no} {fullname {temporary users}} dcecp> .oE .PP .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m), \*Ldcecp_account(1m)\*O, \*Ldcecp_organization(1m)\*O, \*Ldcecp_principal(1m)\*O, \*Ldcecp_registry(1m)\*O, \*Ldcecp_xattrschema(1m). ...\" \*Ldcecp(1m), ...\" \*Ldcecp_account(1m)\*O, ...\" \*Ldcecp_organization(1m)\*O, ...\" \*Ldcecp_principal(1m)\*O, ...\" \*Ldcecp_registry(1m)\*O, ...\" \*Ldcecp_xattrshcema(1m). .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" .rm zA .rm zZ .TH host 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lgroup\*O" .iX "host" "DCECP object" .SH NAME .PP \*Lhost\*O - A \*Ldcecp\*O task object that manages host information in a DCE cell .PP \*LNote:\*O All operations of the \*Lhost\*O task object are not fully supported in this release. .SH "SYNOPSIS" .PP .sS ...\" .zA "Def,13377,R1.2.2, clarify syntax" ...\" .zA "1.1, add cell_name" \*Lhost catalog \*O[\*Vcell_name\*O] [\*L-simplename\*O] ...\" .zZ "1.1, add cell_name" ...\" .zZ "Def,13377,R1.2.2, clarify syntax" .PP ...\" ...\" .zA "1.1, add -server" \*Lhost configure \*Vhost_name .nL \*L -cell \*Vcell_name .nL \*L -secmaster \*Vmaster_security_server_name .nL \*L -cds \*Vcds_server_name .nL \*L -password \*Vpassword\*O .nL [\*L-admin \*Vadmin_principal\*O] {\*L-client\*O | \*L-server\*O} ...\" .zZ "1.1, add -server" .PP ...\*Lhost help \*O[\*Voperation\*O | \*L-verbose\*O] ...\" .PP ...\" \*Lhost catalog \*O[\*L-simplename\*O] ...\" .PP ...\" \*Lhost configure \*Vhost_name\*L -cell \*Vcell_name\*L -client ...\" .nL ...\" -secmaster \*Vmaster_security_server_name\*L -cds \*Vcds_server_name\*L ...\" .nL ...\" -password \*Vpassword\*O [\*L-admin \*Vadmin_principal\*O] .PP \*Lhost help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lhost operations\*O .PP \*Lhost ping \*Vhost_name\*O .PP \*Lhost show \*O[\*Vhost_name\*O] .PP \*Lhost start \*O[\*Vhost_name\*O] .PP \*Lhost stop \*O[\*Vhost_name\*O] [\*L-force\*O] .PP ...\" \*Lhost unconfigure \*Vhost_name\*O ...\" .zA "1.2.1: add -force" \*Lhost unconfigure \*Vhost_name\*O [\*L-force\*O] ...\" .zZ "1.2.1: add -force" .sE .SH "ARGUMENTS" .VL ...\" .zA "1.1, add cell_name" .LI "\*Vcell_name\*O" The name of a single cell to operate on. The name must be a fully qualified cell name such as either of the following: .iS /.../their_cell.goodco.com /.: .iE ...\" .zZ "1.1, add cell_name" .LI "\*Vhost_name\*O" The name of a single host to operate on. Some host commands will accept both fully qualified names (as in \*L/.../\*Vhosts\*L/\*Vhostname\*O) and cell relative names (as in \*Vhosts\*L/\*Vhostname\*O), while others will accept only fully qualified names. See individual command descriptions in the \*LOPERATIONS\*O section of this reference page for details. .LI "\*Voperation\*O" The name of the \*Lhost\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Lhost\*O task object represents DCE processes running on a machine in (or to be added to) a DCE cell. The \*Lhost\*O task object allows administrators to easily configure and start DCE on machines. .PP The \*Lhost\*O task object can configure and start the core DCE services on a client machine. This includes the DCE daemon (\*Ldced\*O), the Cell Directory Service (CDS) client (\*Lcdsadv\*O), the Distributed Time Service (DTS) daemon (\*Ldtsd\*O), and the audit daemon (\*Lauditd\*O). The argument to this command is the DCE name of a host to operate on. If an argument is omitted, the command operates on the local host, if possible. The behavior of commands operating locally may differ from the behavior of commands operating remotely, with more operations performed on the local host than may be possible remotely. See the \*LOPERATIONS\*O section of this reference page for details. .PP Currently only a client can be configured using the \*Lhost\*O command. .SH "OPERATIONS" .PP .SS "host catalog" .PP Returns a list of names of hosts in the cell. The syntax is as follows: .sS \*Lhost catalog \*O[\*Vcell_name\*O] [\*L-simplename\*O] .sE .PP The \*Lcatalog\*O operation returns a list of names of hosts in the cell. By default, the names are fully qualified. Use the \%\*L-simplename\*O option to return cell-relative names. The optional \*Vcell_name\*O argument specifies a cell to operate in. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the \*L/.:/hosts\*O directory in CDS. .PP \*LExamples\*O .PP The following example lists the full names of all the DCE hosts that have entries in the CDS \*L/.:/hosts\*O directory in the local cell: .oS dcecp> \*Lhost catalog\*C /.../my_cell.goodco.com/hosts/alpha /.../my_cell.goodco.com/hosts/beta /.../my_cell.goodco.com/hosts/gamma dcecp> .oE .PP The following example lists the simple names of all the DCE hosts that have entries in the CDS \*L/.:/hosts\*O directory in the local cell: .oS dcecp> \*Lhost catalog -simplename\*C hosts/alpha hosts/beta hosts/gamma dcecp> .oE .SS "host configure" .PP ...\" .zA "1.1: add -server" Configures a single machine named by the argument into an existing DCE cell. The syntax is as follows: .sS \*Lhost configure \*Vhost_name .nL \*L -cell \*Vcell_name .nL \*L-secmaster \*Vmaster_security_server_name .nL \*L -cds \*Vcds_server_name .nL \*L -password \*Vpassword\*O .nL [\*L-admin \*Vadmin_principal\*O] {\*L-client\*O | \*L-server\*O} .sE .PP \*LOptions\*O .PP .VL ...\" .zA "def,13377,R1.2.1,add format desc" .LI "\*L-cell \*Vcell_name\*O" Specifies the name of the cell in which the host is to be configured. The format is \*L/.../\*Vcellname\*O. ...\" .zZ "def,13377,R1.2.1,add format desc" .LI "\*L-client\*O" Configure the host as a DCE client machine. The machine will be configured to run \*Ldced\*O (including the \*Lsecval\*O service), a DTS clerk (\*Ldtsd\*O), \*Lcdsadv\*O, and \*Lauditd\*O. .LI "\*L-server\*O" Configure the host as a DCE server machine. This option is currently not supported. .LI "\*L-secmaster \*Vmaster_security_server_name\*O" Specifies the hostname of the security master server in the form \*Vhostname\*O. .LI "\*L-cds \*Vcds_server_name\*O" Specifies the hostname of any CDS server in the form \*Vhostname\*O. .LI "\*L-password \*Vpassword\*O" Specifies the password of the cell administrator principal. .LI "\*L-admin \*Vadmin_principal\*O" Optionally specifies the principal name of the cell administrator principal. It defaults to \*Lcell_admin\*O. .LE ...\" .zZ "1.1: add -server" .PP The \*Lconfigure\*O operation configures a single machine named by the \*Vhost_name\*O argument into a DCE cell. The cell must already exist and must have a security and naming service operating. The DCE software must already be installed on the machine. The \*Vhost_name\*O argument is the name of the local host machine without the cell name prepended, as in the following: .iS \*Lhosts/\*Vhostname\*O .iE .PP This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lroot\*O authority. .PP \*LExamples\*O .PP The following example configures host \*Lhydra\*O in the cell \*L/.../my_cell.goodco.com\*O: .oS dcecp> \*Lhost configure hosts/hydra -client \\\*C > \*L-cell my_cell.goodco.com -password fstzkl -secmaster scylla \\\*C > \*L-cds charybdis\*C dcecp> .oE .SS "host help" .PP Returns help information about the \*Lhost\*O task object and its operations. The syntax is as follows: .sS \*Lhost help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lhost\*O task object. .LE .PP Used without an argument or option, the \*Lhost help\*O command returns brief information about each \*Lhost\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lhost\*O task object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lhost help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lhost help\*C catalog Returns a list of configured hosts in the cell. configure Configures a host into the cell as a client or server. ping Determines if DCE is responding on the specified host. show Returns all DCE processes configured on the specified host. start Starts DCE on the specified host. stop Stops DCE on the specified host. unconfigure Removes the host from the name and security databases. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "host operations" .PP Returns a list of the operations supported by the \*Lhost\*O task object. The syntax is as follows: .sS \*Lhost operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lhost operations\*O command. .PP \*LExamples\*O .PP .oS \*Cdcecp> \*Lhost operations\*C catalog configure ping show start stop unconfigure help operations dcecp> .oE .SS "host ping" .PP Tests whether DCE processes are accessible from the network. The syntax is as follows: .sS \*Lhost ping \*Vhost_name\*O .sE .PP The \*Lping\*O operation tests if DCE processes are accessible from the network. It contacts the endpoint mapper (either \*Lrpcd\*O or \*Ldced\*O, whatever listens on port 135) on the specified host. The \*Vhost_name\*O argument is the fully qualified name of the host to ping as in the following: .iS \*L/.:/hosts\*Vhostname\*O .iE The operation returns \*L1\*O if the host responds, \*L0\*O if it does not. .PP \*LPrivileges Required\*O .PP No special privileges are required for the \*Lhost ping\*O command. .PP \*LExamples\*O .PP The following example pings host \*Lhydra\*O: .oS dcecp> \*Lhost ping /.:/hosts/hydra\*C 1 dcecp> .oE .SS "host show" .PP The \*Lshow\*O operation is not currently implemented. .PP Returns a list describing all processes that are configured to run on the specified host. The syntax is as follows: .sS \*Lhost show \*O[\*Vhost_name\*O] .sE .PP The \*Lshow\*O operation returns a list describing all processes that are configured to run on the specified host. The optional \*Vhost_name\*O argument is the fully qualified or cell-relative name of a DCE host, such as \*Lhosts/\*Vname\*O or \*L/.:/hosts/\*Vname\*O. If not given, the local host is assumed. The returned list contains the following: .ML .LI The server name as output by the \*Lserver catalog -simplename\*O command. .LI One of the tokens \*Lrunning\*O or \*Lnotrunning\*O. .LI An optional server-specific comment such as \*Lmaster\*O or \*Lreplica\*O for a security server and \*Lclerk\*O or \*Lserver\*O for a DTS server. .LE .PP If the DCE daemons on the specified host were not started by the \*Ldcecp server\*O command, the output of this command will not be as expected. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the \*Lconfig/srvrconf\*O container object on the specified host. .PP \*LExamples\*O .PP .oS dcecp> \*Lhost show hosts/hydra\*C {dced running} {cdsd running} {cdsadv running} {secd running master} {auditd notrunning} {dtsd running clerk} dcecp> .oE .SS "host start" .PP Starts all DCE processes on the specified host. The syntax is as follows: .sS \*Lhost start \*O[\*Vhost_name\*O] .sE .PP The \*Lstart\*O operation starts all DCE processes on the specified host. This command depends on \*Ldced\*O being running on the specified host; that is, it may not be used to start DCE on systems that use versions prior to Version 1.1. The processes that are started are all those listed in the server configuration data stored in the \*Ldced\*O on the specified host with the \*Lboot\*O or \*Lexplicit\*O values of the \*Lstarton\*O attribute. You can add servers to the server configuration data by using the \*Lserver create\*O command. The \*Lhost configure\*O command adds certain servers to the configuration data automatically. .PP The \*Vhost_name\*O argument is the fully qualified or cell-relative name of the host to operate on, as in the following: .iS \*L/.:/hosts/\*Vhostname\*O \*Lhosts/\*Vhostname\*O .iE .PP Without the \*Vhost_name\*O argument, \*Ldced\*O is started on the local host first, which requires the appropriate local permissions (usually \*Lroot\*O). If a host name is specified, \*Ldced\*O must be running on that host. Before starting any host, make sure that a security server and a CDS server are both running somewhere in the cell. This operation returns an empty string on success .PP \*LPrivileges Required\*O .PP You must have \*Lx\*O (\*Lexecute\*O) permission to the \*Lconfig/srvrconf\*O container object on the specified host. .PP \*LExamples\*O .PP The following example starts all DCE processes on host \*Lhydra\*O: .oS dcecp> \*Lhost start hosts/hydra\*C dcecp> .oE .SS "host stop" .PP Stops all DCE processes on the specified host. The syntax is as follows: .sS \*Lhost stop \*O[\*Vhost_name\*O] [\*L-force\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-force\*O" Optionally specifies that any servers that fail to stop normally should be stopped using a \*Lserver stop -method hard\*O command. .LE .PP The \*Lstop\*O operation stops running DCE processes on the specified host. This command depends on \*Ldced\*O being on the specified host, that is, it may not be used to stop DCE on systems that use versions prior to Version 1.1. The \*Vhost_name\*O argument is the fully qualified or cell-relative name of the host to operate on, as in .iS \*L/.:/hosts/\*Vhostname\*O. \*Lhosts/\*Vhostname\*O .iE .PP Processes are stopped as follows: .ML .LI All servers listed in the server execution data are stopped. Servers implementing DCE core services are stopped last, in the appropriate order. If servers were not started as \*Lsrvrexec\*O objects, they will not be stopped. .LI If any servers fail to stop, and the \%\*L-force\*O option was specified, those servers are stopped by the command \*Lserver stop -method hard\*O. .LE .PP This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Ls\*O (\*Lstop\*O) permission on the \*Lconfig/srvrexec\*O object for each server to be stopped. .PP \*LExamples\*O .PP The following example stops host \*Lhydra\*O: .oS dcecp> \*Lhost stop hosts/hydra\*C dcecp> .oE .SS "host unconfigure" .PP Unconfigures a specified host from a cell. The syntax is as follows: ...\" .zA "1.2.1: add -force" .sS \*Lhost unconfigure \*Vhost_name \*O[\*L-force\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-force\*O" Optionally specifies that any errors that occur during an \*Lunconfigure\*O operation are to be ignored and the \*Lunconfigure\*O operation should continue. .LE ...\" .zZ "1.2.1: add -force" .PP The \*Lunconfigure\*O operation unconfigures a specified host from a cell. To unconfigure a cell, the operation deletes: .ML .LI All objects, directories and links from \*L/.:/hosts/\*Vhostname\*O including the directory itself .LI All principal names beginning with \*Lhosts/\*Vhostname\*L\*O, but not accounts with the same names .LE .PP The \*Lunconfigure\*O operation takes the fully qualified name of a host to unconfigure as an argument, as in the following: .iS \*L/hosts/\*Vhostname\*O .iE This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have the appropriate permission to delete CDS objects and directories. You must also have the appropriate permission to delete principals from the registry. Refer to the appropriate reference page on each object for more details. .PP \*LExamples\*O .PP The following example unconfigures host \*Lhydra\*O from the cell: .oS dcecp> \*Lhost unconfigure hosts/hydra \*C dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_account(1m)\*O, \*Ldcecp_aud(1m)\*O, \*Ldcecp_directory(1m)\*O, \*Ldcecp_server(1m)\*O, \*Ldcecp_dts(1m)\*O, \*Ldcecp_registry(1m)\*O. ...\" \*Laccount(1m)\*O, ...\" \*Laud(1m)\*O, ...\" \*Ldcecp(1m)\*O, ...\" \*Ldirectory(1m)\*O, ...\" \*Ldts(1m)\*O, ...\" \*Lregistry(1m)\*O, ...\" \*Lserver(1m)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH hostdata 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lgroup\*O" .iX "hostdata" "DCECP object" .SH NAME .PP \*Lhostdata\*O - A \*Ldcecp\*O object that manages a DCE host's cell affiliation information .SH "SYNOPSIS" .sS ...\" .zA "def,13377,R1.2.2, clarify syntax" ...\" .zA "1.2.1: add -local" \*Lhostdata catalog \*O[\*Vhost_name_list\*O] [\*L-simplename] .nL [-local]\*O ...\" .zZ "1.2.1: add -local" .PP ...\" .zA "1.2.1: add -local" \*Lhostdata create \*Vhostdata_name_list .nL \*O{\*L-attribute \*Vattribute_list\*O | \*L-\*Vattribute value\*O} .nL [\*L-binary\*O] [\*L-local\*O] ...\" .zZ "1.2.1: add -local" .PP ...\" .zA "1.2.1: add -local" \*Lhostdata delete \*Vhostdata_name_list \*O[\*L-entry\*O] .nL [\*L-local\*O] ...\" .zZ "1.2.1: add -local" .PP \*Lhostdata help \*O[\*Voperation\*O | \*L-verbose\*O] .PP ...\" .zA "1.2.1: add -local" \*Lhostdata modify \*Vhostdata_name_list\*O .nL {\*L-change \*Vattribute_list\*O | \*L-\*Vattribute value\*O} .nL [\*L-binary\*O] [\*L-local\*O] ...\" .zZ "1.2.1: add -local" .PP \*Lhostdata operations\*O .PP ...\" .zA "1.2.1: add -ifname,-local" \*Lhostdata show \*Vhostdata_name_list\*O .nL [\*L-ifname \*Vresidual_object_name\*O | [\*L-entry\*O] [\*L-binary\*O]] .nL [\*L-local\*O] ...\" .zZ "def,13377,R1.2.2, clarify syntax" ...\" .zZ "1.2.1: add -ifname,-local" .sE .SH "ARGUMENTS" .VL .LI "\*Vhostdata_name_list\*O A list of one or more names of of host data items. Usually they are of the following form: .iS /.:/hosts/\*Vhostname\*L/config/hostdata/\*Vname .iE .PP For the \*Lshow\*O operation, the name can also be a single string binding representing the host with which to communicate. For example: .iS {ncacn_ip_tcp 130.105.1.227} .iE .PP A string binding is useful when the name service is not operating and cannot translate the other forms of host data item names. .LI "\*Vhost_name_list\*O" A list of one or more DCE host names specifying hosts for which to catalog servers. Host names can be in any of the following forms: .iS /.:/hosts/\*Vhostname\*L /.../\*Vcell_name\*L/hosts/\*Vhostname\*L hosts/\*Vhostname\*O .iE .PP For the \*Lcatalog\*O operation, the name can also be a single string binding representing the host with which to communicate. See \*Vhostdata_name_list\*O for more information. If you supply a single string binding, you must use the \*L-ifname\*O option to specify the host's residual name. .LI "\*Voperation\*O" The name of the \*Lhostdata\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Lhostdata\*O object represents a hostdata entry stored by \*Ldced\*O on a host that represents some data, usually a file. The data in the \*Lhostdata\*O object is represented by the \*Lhostdata/data\*O attribute of the hostdata entry. Remote manipulation of data in the \*Lhostdata\*O object is accomplished by the \*Lhostdata\*O command. The names of these \*Lhostdata\*O objects are in the DCE namespace and are controlled by \*Ldced\*O. Usually they are of the following form: .iS /.:/hosts/\*Vhostname\*L/config/hostdata/\*Vname .iE However, a shorthand notation referring to the local machine consisting of just \*Vname\*O can be used in some circumstances. ...\" .zA "1.2.1: add -local" .PP When the \*Ldced\*O on the local machine is in partial service mode, you must use the \%\*L-local\*O option to access the \*Lhostdata\*O object. To access the \*Lhostdata\*O objects when \*Ldced\*O is in partial service mode, specify only the residual portion of the object name. For example, specify \*Lhostdata\*O, not \*L/.:/hosts/gumby/config/hostdata\*O. ...\" .zZ "1.2.1: add -local" .SH "ATTRIBUTES" .VL .LI "\*Luuid \*Vhexadecimal number\*O" An internal identifier for the hostdata entry. Its value is a Universal Unique Identifier (UUID). If not specified on creation, one is generated by \*Ldcecp\*O. This attribute cannot be modified after creation. .LI "\*Lannotation \*Vstring\*O" A human readable comment field limited to Portable Character Set (PCS) data. It cannot be modified after creation. This attribute defaults to a null string (that is, blank). .LI "\*Lstorage \*Vstring\*O" A PCS string that identifies the name of the data repository. In the current release of \*Ldced\*O, it is a filename. It is required and may not be modified after creation. .LI "\*Lhostdata/data \*Vstring\*O An attribute that represents the actual data. Its syntax is a list of strings. The data can be viewed and modified in two different modes, either as a string, or as binary data. By default the string mode is used, but some of the operations below accept a \*(lBbinary\*(lE option to allow this attribute to be displayed or modified in binary form. When viewed as a string, each string in the list represents one line in the hostdata file. .LE .PP See the \*VOSF DCE Administration Guide\*O for more information about hostdata attributes. ...\" See the \*(Ag for more information about hostdata attributes. .SH "OPERATIONS" .SS "hostdata catalog" .PP Returns a list of the names of all hostdata objects on the specified host. The syntax is as follows: .sS ...\" .zA "1.2.1: add -local" ...\" .zA "def,13377,R1.2.2, clarify syntax" \*Lhostdata catalog \*O[\*Vhost_name_list\*O] [\*L-simplename\*O] .nL [\*L-local\*O] ...\" .zZ "def,13377,R1.2.2, clarify syntax" ...\" .zZ "1.2.1: add -local" .sE .PP \*LOptions\*O .VL .LI "\*L-simplename\*O" Returns a list of hostdata entries without prepending the cell name and name of the hostdata container. ...\" .zA "1.2.1: add -local" .LI "\*L-local\*O" Specifies that the command should operate on the local \*Ldced hostdata\*O object while the \*Ldced\*O object is in a partial-service state. ...\" .zZ "1.2.1: add -local" .LE .PP The \*Lcatalog\*O operation returns a list of the names of all hostdata objects on the specified host, in arbitrary order. The optional \*Vhost_name_list\*O argument is used to specify objects on a foreign host. By default, fully qualified names are returned. Use the \*L-simplename\*O option to return objects names without the prepended cellname and hostdata container names. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the hostdata container on the host (\*L/.:/hosts/\*Vhost_name\*L/config/hostdata/\*Vhostdata_container\*O). .PP \*LExamples\*O .PP .oS dcecp> \*Lhostdata catalog\*C /.../gumby1/hosts/fire/config/hostdata/dce_cf.db /.../gumby1/hosts/fire/config/hostdata/cell_name /.../gumby1/hosts/fire/config/hostdata/pe_site /.../gumby1/hosts/fire/config/hostdata/cds_attributes /.../gumby1/hosts/fire/config/hostdata/cds_globalnames /.../gumby1/hosts/fire/config/hostdata/host_name /.../gumby1/hosts/fire/config/hostdata/cell_aliases /.../gumby1/hosts/fire/config/hostdata/post_processors /.../gumby1/hosts/fire/config/hostdata/svc_routing /.../gumby1/hosts/fire/config/hostdata/krb.conf /.../gumby1/hosts/fire/config/hostdata/dfs-cache-info /.../gumby1/hosts/fire/config/hostdata/cds.conf /.../gumby1/hosts/fire/config/hostdata/passwd_override /.../gumby1/hosts/fire/config/hostdata/group_override dcecp> .oE .SS "hostdata create" .PP Creates a hostdata configuration object. The syntax is as follows: .sS ...\" .zA "1.2.1: add -local" \*Lhostdata create \*Vhostdata_name_list .nL ...\" .zA "def,13377,R1.2.2, clarify syntax" \*O{\*L-attribute \*Vattribute_list\*O | \*L-\*Vattribute value\*O} .nL [\*L-binary\*O] [\*L-local\*O] ...\" .zZ "def,13377,R1.2.2, clarify syntax" ...\" .zZ "1.2.1: add -local" .sE .PP \*LOptions\*O .VL .LI "\*L-attribute \*Vattribute_list\*O" Allows you to specify attributes by using an attribute list rather than using the \*L-\*Vattribute value\*O option. The format of an attribute list is as follows: .iS {{\*Vattribute \*Vvalue\*O}...{\*Vattribute \*Vvalue\*O}} .iE .LI "\*L-\*Vattribute value\*O" As an alternative to using the \*L-attribute\*O option with an attribute list, you can specify individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. .LI "\*L-binary\*O" Specifies that the value of the \*Ldata\*O attribute is in binary form. ...\" .zA "1.2.1: add -local" .LI "\*L-local\*O" Specifies that the command should operate on the local \*Ldced hostdata\*O object while the \*Ldced\*O object is in a partial-service state. ...\" .zZ "1.2.1: add -local" .LE .PP The \*Vhostdata_name_list\*O argument is a list of names of hostdata entries to be created. The \%\*L-attributes\*O option specifies configuration information for \*Ldced\*O. The contents of the hostdata file can be specified via the \*Vdata\*O attribute. The value of the option is applied to all elements of the argument list. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission to the hostdata container on the host. .PP \*LExamples\*O .PP .oS dcecp> \*Lhostdata create file1 -storage /tmp/file1 -data {{first line}}\*C dcecp> dcecp> \*Lhostdata show file1\*C {uuid 8484188a-eb85-11cd-91b1-080009251352} {annotation {}} {storage /tmp/file1} {hostdata/data {first line}} dcecp> dcecp> \*Lcat /tmp/file1\*C first line dcecp> .oE .SS "hostdata delete" .PP Deletes a hostdata entry and its data. The syntax is as follows: .sS ...\" .zA "def,13377,R1.2.2, clarify syntax" ...\" .zA "1.2.1: add -local" \*Lhostdata delete \*Vhostdata_name_list \*O[\*L-entry\*O] .nL [\*L-local\*O] ...\" .zZ "1.2.1: add -local" ...\" .zZ "def,13377,R1.2.2, clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-entry\*O" Only the configuration information that \*Ldced\*O keeps is deleted, not the actual hostdata. ...\" .zA "1.2.1: add -local" .LI "\*L-local\*O" Specifies that the command should operate on the local \*Ldced hostdata\*O object while the \*Ldced\*O object is in a partial-service state. ...\" .zZ "1.2.1: add -local" .LE .PP The \*Vhostdata_name_list\*O argument is a list of names of hostdata entries to be deleted in the order specified. If the \%\*L-entry\*O option is present, only the configuration information that \*Ldced\*O keeps is deleted, not the actual hostdata. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Ld\*O (\*Ldelete\*O) permission to the hostdata container on the host. .PP \*LExamples\*O .PP .oS dcecp> \*Lhostdata delete file1\*C dcecp> .oE .SS "hostdata help" .PP Returns help information about the \*Lhostdata\*O object and its operations. The syntax is as follows: .sS \*Lhostdata help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lhostdata\*O object. .LE .PP Used without an argument or option, the \*Lhostdata help\*O command returns brief information about each \*Lhostdata\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lhostdata\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lhostdata help\*O command. .PP \*LExamples\*O .PP ...\" .zA "def,13377,R1.2.2,revised help" .oS dcecp> \*Lhostdata help\*C catalog Returns the list of hostdata object names. create Creates a new hostdata configuration object. delete Deletes a hostdata object and its associated data. modify Modifies the data of a hostdata object. show Returns the attributes of a hostdata object. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE ...\" .zZ "def,13377,R1.2.2,revised help" .SS "hostdata modify" .PP This operation is used to change attributes of a hostdata entry, including the hostdata itself. The syntax is as follows: .sS ...\" .zA "1.2.1: add -local" \*Lhostdata modify \*Vhostdata_name_list\*O .nL ...\" .zA "def,13377,R1.2.2, clarify syntax" {\*L-change \*Vattribute_list\*O | \*L-\*Vattribute value\*O} .nL [\*L-binary\*O] [\*L-local\*O] ...\" .zZ "def,13377,R1.2.2, clarify syntax" ...\" .zZ "1.2.1: add -local" .sE .PP \*LOptions\*O .VL .LI "\*L-\*Vattribute value\*O" As an alternative to using options with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. .PP In the current version of DCE, only the \*Ldata\*O attribute can be modified. .LI "\*L-change\*O \*Vattribute_list\*O" Allows you to modify attributes by using an attribute list rather than using individual attribute options. The format of an attribute list is as follows: .iS \*O{{\*Vattribute value\*O}...{\*Vattribute value\*O}} .iE .PP In the current version of DCE, only the \*Ldata\*O attribute can be modified. .LI "\*L-binary\*O" Specifies that the value of the \*Ldata\*O attribute is in binary form. ...\" .zA "1.2.1: add -local" .LI "\*L-local\*O" Specifies that the command should operate on the local \*Ldced hostdata\*O object while the \*Ldced\*O object is in a partial-service state. ...\" .zZ "1.2.1: add -local" .LE .PP The argument is a list of names of hostdata entries to be modified. If more than one is specified all modifications specified are done to each hostdata entry listed. In the current DCE Version, only the \*Vdata\*O attribute is modifiable, and it can only be completely replaced. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission to the hostdata container on the host. .PP \*LExamples\*O .PP .oS dcecp> \*Lhostdata mod file1 -data {new first line}\*C dcecp> dcecp> \*Lhostdata show file1\*C {uuid cda3a184-eb85-11cd-91b1-080009251352} {annotation {}} {storage /tmp/file1} {hostdata/data {new first line}} dcecp> dcecp> \*Lcat /tmp/file1\*C new first line dcecp> .oE .SS "hostdata operations" .PP Returns a list of the operations supported by the \*Lhostdata\*O object. The syntax is as follows: .sS \*Lhostdata operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lhostdata operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lhostdata operations\*C catalog create delete modify show help operations dcecp> .oE .SS "hostdata show" Returns an attribute list of the hostdata entries specified in the argument. The syntax is as follows: .sS ...\" .zA "1.2.1: add -ifname,-local" ...\" .zA "def,13377,R1.2.2, clarify syntax" \*Lhostdata show \*Vhostdata_name_list\*O .nL [\*L-ifname \*Vresidual_object_name\*O | [\*L-entry\*O] [\*L-binary\*O]] .nL [\*L-local\*O] ...\" .zZ "def,13377,R1.2.2, clarify syntax" ...\" .zZ "1.2.1: add -ifname,-local" .sE \*LOptions\*O .VL ...\" .zA "1.2.1: add -ifname,-local" .LI "\*L-ifname\*O " Specifies the \*Ldced\*O object for which to return the value. .LI "\*L-entry\*O" Only the configuration information that \*Ldced\*O keeps is returned, not the actual hostdata. .LI "\*L-binary\*O" Specifies to return the value of the \*Ldata\*O attribute in binary form. .LI "\*L-local\*O" Specifies that the command should operate on the local \*Ldced hostdata\*O object while the \*Ldced\*O object is in a partial-service state. ...\" .zZ "1.2.1: add -ifname,-local" .LE .PP The \*Vhostdata_name_list\*O argument is a list of names of hostdata entries. If called with the \%\*L-entry\*O option, then the \*Vdata\*O attribute is not returned. The \%\*L-binary\*O option can be specified to indicate that the value of the \*Ldata\*O attribute should be returned in binary form. If the argument is a list of entries, the output is concatenated into a single list in the order specified. ...\" .zA "1.2.1: add -ifname,-local" The \*L-ifname \*O option is used to identify the specific hostdata entry to show, but only when the argument is a string binding representing a host, not the fully qualified hostdata name. ...\" .zZ "1.2.1: add -ifname,-local" .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the hostdata container on the host (\*L/.:/hosts/\*Vhost_name\*L/config/hostdata/\*Vhostdata_container\*O). .PP \*LExamples\*O .PP .oS dcecp> \*Lhostdata show /.:/hosts/mars/config/hostdata/cell_name\*C {uuid 00174f6c-6eca-1d6a-bf90-0000c09ce054} {annotation {Name of cell}} {storage cell_name} {hostdata/data /.../my_cell} \*Cdcecp> ...\" .zA "1.2.1: add -ifname,-local" \*Cdcecp> \*Lhostdata show ncacn_ip_tcp:15.122.24.148 -ifname cell_name\*C {uuid 00174f6c-6eca-1d6a-bf90-0000c09ce054} {annotation {Name of cell}} {storage cell_name} {hostdata/data /.../my_cell} \*Cdcecp>\*O ...\" .zZ "1.2.1: add -ifname,-local" .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_server(1m)\*O, \*Ldced(1m)\*O. ...\" \*Ldcecp(1m)\*O, ...\" dced(1m)\*O. ...\" \*Lserver(1m)\*O. .ad b ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\"Copyright Hewlett-Packard Company 1992 ...\" ...\" .rm zA .rm zZ .TH hostvar "8sdce" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .zA "1.2.1, new manpage" .iX "\*Ldcecp\*O commands" "\*Lhostvar\*O" .iX "host attributes" "administering" .SH NAME .P \*Lhostvar\*O - A \*Ldcecp\*O task object that manages the security binary compatibility attributes .SH "SYNOPSIS" .sS \*Lhostvar help \*O[\*Voperation\*O | \*L-verbose\*O] .nL \*Lhostvar operations\*O .nL ...\" .zA "Def,13377,R1.2.2,clarify syntax" \*Lhostvar set \*L-secbinarycompat \*O{\*Lon\*O | \*Loff\*O} .nL \*Lhostvar show\*O {\*L-all\*O | [\*L-cellname\*O] [\*L-hostname\*O] [\*L-secbinarycompat\*O]} ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .sE .PP .SH "ARGUMENTS" .PP .VL .LI "\*Voperation\*O" The name of the \*Lhostvar\*O operation for which to display help information. .LE .PP .SH "DESCRIPTION" .PP The \*Lhostvar\*O object allows you to easily set the security binary compatibility attributes for the current host and to display the local host's cell name, host name, and security binary compatibility attributes that are stored by the \*Ldecd\*O in the \*Lhostdata/dce_cf.db\*O object. .PP The cell's security server uses these compatibility attributes to determine the mode and state in which the local machine is operating. .PP .SH "ATTRIBUTES" .PP .VL .LI "\*Lcellname\*O The name of the local hosts cell. .LI "\*Lhostname\*O The name of the local host. .LI "\*Lsecbinarycompat\*O The security binary compatibility attribute that enables (\*Lon\*O) and disables (\*Loff\*O) binary compatibility for statically linked versions of DCE. .LE .PP .SH "OPERATIONS" .SS "hostvar help" .PP Returns help information about the \*Lhostvar\*O task object and its operations. The syntax is as follows: .sS \*Lhostvar help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOption\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lhostvar\*O object. .LE .PP Used without an argument or option, the \*Lhostvar help\*O command returns brief information about each \*Lhostvar\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \*L-verbose\*O option to display detailed information about the \*Lhostvar\*O task object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lhostvar\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lhostvar help\*C set Sets the value of the specified host variable. show Returns the value of the specified host variable. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "hostvar operations" .PP Returns a list of the operations supported by the \*Lhostvar\*O object. The syntax is as follows: .sS \*Lhostvar operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lhostvar operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lhostvar operations\*C set show help operations dcecp> .oE .SS "hostvar set" .PP Sets the security binary compatibility value attribute for the current host. The syntax is as follows: .sS \*Lhostvar set \*L-secbinarycompat\*O {\*Lon\*O | \*Loff\*O} .nL .sE .PP \*LOption\*O .VL .LI "\*L-secbinarycompat\*O" Sets the security binary compatibility attribute \*Lon\*O or \*Loff\*O. .LE .PP Under normal circumstances, \*Lsecbinarycompat\*O is set to \*Lon\*O when DCE is configured, which allows binary compatibility between Version 1.2 and Versions 1.0.3 and 1.1. This allows applications linked with an archived \*Llibdce\*O to share login contexts and credentials without loss of data. .PP You can disable binary compatibility on a per-host basis to achieve minor performance gains and slightly smaller credentials files by setting \*Lsecbinarycompat\*O to \*Loff\*O. ...\" HP SPECIAL If you enable binary compatibility after it has been disabled, you must start and stop all DCE daemons and if you are using integrated login, log in and out. See \*VPlanning and Configuring HP DCE1.5\*O for more information. This operation returns an empty string on success. ...\" OSF VERSION ...\" If you enable binary compatibility after it has been disabled, you must start ...\" and stop all DCE daemons. This operation returns an empty ...\" string on success. .PP \*LPrivileges Required\*O .PP No special privileges are required to use the \*Lhostvar set\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lhostvar set -secbinarycompat on\*C dcecp> .oE .PP .SS "hostvar show" .PP Returns the values of the host attributes on the local host. The syntax is as follows: .sS ...\" .zA "Def,13377,R1.2.2,clarify syntax" \*Lhostvar \*Lshow\*O {\*L-all\*O | [\*L-cellname\*O] [\*L-hostname\*O] [\*L-secbinarycompat\*O]} ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-all\*O" Returns the values of all attributes. .LI "\*L-cellname\*O" Returns the value of the \*Lcellname\*O attribute. .LI "\*L-hostname\*O" Returns the value of the \*Lhostname\*O attribute. .LI "\*L-secbinarycompat\*O" Returns the value of the \*Lsecbinarycompat\*O attribute. .LE .PP The \*Lshow\*O operation makes it easy to view the attributes stored in the \*Ldced hostdata/dce_cf.db\*O object. All the values returned by this command are from that object. Use the \*L-all\*O option to display all attributes; use individual options to display individual attributes. .PP \*LPrivileges Required\*O .PP No special privileges are required. .PP \*LExamples\*O .PP .oS dcecp> \*Lhostvar show -all\*C {cellname /.../gumby1} {hostname hosts/blech} {secbinarycompat on} dcecp> .oE .PP .SH "RELATED INFORMATION" .PP Commands: .ad 1 \*Ldcecp(1m)\*O, \*Ldcecp_hostdata(1m)\*O, \*Ldced(1m)\*O ...\" hostdata(1m) .ad b ...\" .zZ "1.2.1, new manpage" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH keytab 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lgroup\*O" .iX "keytab" "DCECP object" .SH NAME .PP \*Lkeytab\*O - A \*Ldcecp\*O object that manages server passwords on DCE hosts .SH "SYNOPSIS" .sS ...\" .zA "1.1: CR13078" ...\" .zA "1.1: CR13069" ...\" .zA "Def,13377,R1.2.2,clarify syntax,add ktname" \*Lkeytab add \*Vkeytab_name_list\*L -member \*Vprincipal_name_list\*O .nL {\*L-key \*Vplain_key \*L-version \*Vkey_version \*O[\*L-registry\*O] | .nL \*L-random -registry\*O [\*L-version \*Vkey_version\*O] } .nL [\*L-ktname\*V residual_keytab_name\*O] [\*L-noprivacy\*O] [\*L-local\*O] .PP \*Lkeytab catalog \*O[\*Vhost_name_list\*O] [\*L-simplename\*O] [\*L-noprivacy\*O] .nL [\*L-local\*O] ...\" .zA "1.1: delete -random" .PP \*Lkeytab create \*Vkeytab_name_list\*O .nL {\*L-attribute \*Vattribute_list\*O | \*L-\*Vattribute value\*O} .nL [\*L-ktname\*V residual_keytab_name\*O] [\*L-noprivacy\*O] [\*L-local\*O] ...\" .zZ "1.1: delete -random" .PP \*Lkeytab delete \*Vkeytab_name_list\*O [\*L-entry\*O] [\*L-noprivacy\*O] [\*L-local\*O] .PP \*Lkeytab help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lkeytab list \*Vkeytab_name_list\*O [\*L-noprivacy\*O] [\*L-local\*O] .PP \*Lkeytab operations\*O .PP \*Lkeytab remove \*Vkeytab_name_list\*L -member \*Vprincipal_name_list\*O .nL [\*L-version \*Vkey_version\*O] [\*L-type \*Vkey_type\*O] [\*L-noprivacy\*O] .nL [\*L-local\*O] .PP \*Lkeytab show \*Vkeytab_name_list\*O [\*L-entry\*O | \*L-members\*O] .nL [\*L-keys\*O] [\*L-ktname\*V residual_keytab_name\*O] [\*L-noprivacy\*O] [\*L-local\*O] ...\" .zZ "Def,13377,R1.2.2,clarify syntax,add ktname" ...\" .zZ "1.1: CR13069" ...\" .zZ "1.1: CR13078" .sE .SH "ARGUMENTS" .VL .LI "\*Vhost_name_list\*O" A list of one or more DCE host names specifying hosts for which to catalog key tables. Host names can be in any of the following forms: .iS \*L/.:/hosts/\*Vhostname \*L/.../\*Vcell_name\*L/hosts/\*Vhostname \*Lhosts/\*Vhostname\*O .iE ...\" .zA "Def,13377,R1.2.2,add string binding" .PP The name can also be a single string binding representing the host with which to communicate. For example: .iS {ncacn_ip_tcp 130.105.1.227} .iE .PP A string binding is useful when the name service is not operating and cannot translate the other forms of host names. If you supply a single string binding, you must use the \*L-ktname\*O option to specify the object's residual name. .LI "\*Vkeytab_name_list\*O" A list of one or more names of key tables to operate on. Key table names are similar to other \*Ldced\*O objects with the following form: .iS /.../\*Vcell\*L/hosts/\*Vhostname\*L/config/keytab/\*Vname .iE For the \*Ladd\*O, \*Lcreate\*O, and \*Lshow\*O operations, the name can also be a single string binding representing the key table to operate on. See \*Vhostdata_name_list\*O for more information on string bindings. ...\" .zZ "Def,13377,R1.2.2,add string binding" .LI "\*Voperation\*O" The name of one specific \*Lkeytab\*O operation about which you want to see help information. .LE .SH "DESCRIPTION" .PP The \*Lkeytab\*O object represents key tables (usually files) that store server keys (and key version numbers) on hosts. These key tables are manipulated remotely by using \*Ldced\*O. The keys are considered members of the key table container. The \*Lkeytab\*O names are in the form: .iS /.../\*Vcell_name\*L/hosts/\*Vhostname\*L/config/keytab/\*Vname .iE A key table has a set of keys. Each key contains a principal name, type, version, and value. The value can be created and changed, but is never shown on output. Removal of a key is based on the name, type and version number. The \*Ldcecp\*O syntax of a key is a list of \*Eprincipal name\*O, \*Etype\*O (which is either \*Lplain\*O or \*Ldes\*O), version (a nonnegative integer), and \*Evalue\*O. The value of a \*Ldes\*O key is 64 bits long and can be represented in \*Ldcecp\*O as Extended Registry Attributes (ERAs) of type \*Lbyte\*O (refer to the \*Lxattrschema\*O object attributes for details). The value is valid on input but is not displayed on output so that keys are not shown on the screen. For example: .iS melman des 1 \*Vkey1\*L melman plain 3 \*Vkey2\*O .iE .PP Multiple keys for the same principal are displayed as separate keys. See the example in the \*Lshow\*O operation below. .SH "ATTRIBUTES" .VL .LI "\*Luuid \*Vvalue\*O" A Universal Unique Identifier (UUID) that is the internal identifier for the key table's configuration information that is kept by \*Ldced\*O. If the UUID is not specified when the key table is created, one is generated automatically. This attribute cannot be modified after it is created. .LI "\*Lannotation \*Vstring\*O" A human readable comment field in Portable Character Set (PCS) format. This attribute cannot be modified after creation. It defaults to a null string (that is, blank). .LI "\*Lstorage \*Vstring\*O" The name of the key table (usually a filename). It is required and may not be modified after creation. .LI "\*Ldata \*Vkey_list\*O The contents of the key table. Represented as a list of keys. .LE .PP ...\" See the \*(Ag for more information about keytab attributes. See the \*VOSF DCE Administration Guide\*O for more information about keytab attributes. .SH "OPERATIONS" .SS "keytab add" .PP Adds members to a key table. The syntax is as follows: ...\" .zA "1.1: CR13078" ...\" .zA "1.1: CR13069" .sS ...\" .zA "Def,13377,R1.2.2,clarify syntax;add ktname" \*Lkeytab add \*Vkeytab_name_list\*L -member \*Vprincipal_name_list\*O .nL {\*L-key \*Vplain_key \*L-version \*Vkey_version\*O [\*L-registry\*O] | .nL \*L-random \*L-registry\*O [\*L-version \*Vkey_version\*O] } .nL [\*L-ktname\*V residual_keytab_name\*O] [\*L-noprivacy\*O] [\*L-local\*O] ...\" .zZ "Def,13377,R1.2.2,clarify syntax;add ktnam" .sE .PP \*LOptions\*O .VL .LI "\*L-member \*Vprincipal_name_list\*O" List of principal names to be added to each key table in the argument. .LI "\*L-registry\*O" Update the principal's key in the registry as well as on the host. Required if the \%\*L-random\*O option is used. .LI "\*L-random\*O" Generates a random \*Ldes\*O key. Cannot be used with the \*L-key\*O option. .LI "\*L-key \*Vplain_key\*O" Specifies a key explicitly. Cannot be used with the \%\*L-random\*O option. .LI "\*L-version \*Vkey_version\*O" Specifies a version number for the key. Required if the \%\*L-registry\*O option is not used. ...\" .zA "Def,13377,R1.2.2,add ktname" .LI "\*L-ktname \*Vresidual_keytab_name\*O" Specifies the \*Lkeytab\*O object to add members to. If you use this option, you must specify \*Vkeytab_name_list\*O as a string binding. See \*LARGUMENTS\*O for more information about specifying a string binding for \*Vkeytab_name_list\*O. ...\" .zZ "Def,13377,R1.2.2,add ktname" .LI "\*L-local\*O" Specifies that the \*Ladd\*O operation operates on local files only. .LI "\*L-noprivacy\*O" Specifies that keytables are sent over the network unencrypted. .LE ...\" .zZ "1.1: CR13069" ...\" .zZ "1.1: CR13078" .PP The \*Ladd\*O operation adds members to key tables. The argument is a list of names of key tables to which members should be added. The required \%\*L-member\*O option lists principal names to be added to each key table in the \*Vkeytab_name_list\*O argument. The principals named must exist or the command will return an error. The operation adds each principal name and its key to the key table. .PP Use either the \%\*L-random\*O option to have \*Ldcecp\*O generate a random \*Ldes\*O key, or the \%\*L-key\*O option to specify a plain key explicitly. The same key (whether specified or randomly generated) is used for all principals being added to all key tables. The \%\*L-registry\*O option updates the principal's key in the key table and in the registry. The \%\*L-registry\*O option is required if \%\*L-random\*O is used. The \%\*L-version\*O option specifies the version number of the key. You must specify either \%\*L-registry\*O or \%\*L-version\*O or both on any \*Lkeytab add\*O command. ...\" .zA "Def,13377,R1.2.2,add ktname" The \*L-ktname\*O option is used to identify the specific key table to operation on, but only when the argument is a string binding representing a key table, not the fully qualified key table name. ...\" .zZ "Def,13377,R1.2.2,add ktname" This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*La\*O (\*Lauth_info\*O) permission to the \*Lkeytab\*O object. .PP \*LExamples\*O .oS dcecp> \*Lkeytab add /.:/hosts/medusa/config/keytab/radiology \\\*C > \*L-member melman -random -registry \*C dcecp> dcecp> \*Lkeytab add /.:/hosts/medusa/config/keytab/radiology \\\*C > \*L-member melman -key yrrebnesor \*C dcecp> .oE .SS "keytab catalog" ...\" .zA "1.1: CR13078" ...\" .zA "1.1: CR13069" .PP Returns a list of the names of all key tables on the specified host. The syntax is as follows: .sS ...\" .zA "Def,13377,R1.2.2, clarify syntax" \*Lkeytab catalog \*O[\*Vhost_name_list\*O] [\*L-simplename\*O] [\*L-noprivacy\*O] .nL [\*L-local\*O] ...\" .zZ "Def,13377,R1.2.2, clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-simplename\*O" Returns key table names without prepending the cell name. .LI "\*L-noprivacy\*O" Specifies the key tables sent over the network are not encrypted. .LI "\*L-local\*O" Specifies that the \*Lcatalog\*O operation operates on local files only. .LE ...\" .zZ "1.1: CR13069" ...\" .zZ "1.1: CR13078" .PP The \*Lcatalog\*O operation returns a list of the names of all key tables on the host specified in the argument. The argument can be a list of one or more host names or a single string binding that identifies a host. If a host name is not specified then the current host is used. If the argument is a list, then the output is concatenated together. The return order is arbitrary. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the \*Lkeytab\*O object on the host. .PP \*LExamples\*O .PP .oS dcecp> \*Lkeytab catalog\*C /.../pokey/hosts/jimbo/config/keytab/self dcecp> .oE .SS "keytab create" ...\" .zA "1.1: CR13078" ...\" .zA "1.1: CR13069" ...\" .zA "1.1: delete -random" .PP Creates a key table. The syntax is as follows: .sS \*Lkeytab create \*Vkeytab_name_list .nL ...\" .zA "Def,13377,R1.2.2,clarify syntax;add ktname" \*O{\*L-attribute \*Vattribute_list\*O | \*L-\*Vattribute value\*O} .nL [\*L-ktname\*V residual_keytab_name\*O] [\*L-noprivacy\*O] [\*L-local\*O] ...\" .zZ "Def,13377,R1.2.2, clarify syntax;add ktname" .sE ...\" .zZ "1.1: delete -random" .PP \*LOptions\*O .VL .LI "\*L-attribute \*Vattribute_list\*O" Allows you to specify attributes by using an attribute list rather than using the \*L-\*Vattribute value\*O option. The format of an attribute list is as follows: .iS {{\*Vattribute \*Vvalue\*O}...{\*Vattribute \*Vvalue\*O}} .iE .LI "\*L-\*Vattribute value\*O" As an alternative to using the \*L-attribute\*O option with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. ...\" .zA "Def,13377,R1.2.2,add ktname" .LI "\*L-ktname \*Vresidual_keytab_name\*O" Specifies the \*Lkeytab\*O object to create. If you use this option, you must specify \*Vkeytab_name_list\*O as a string binding. See \*LARGUMENTS\*O for more information about specifying a string binding for \*Vkeytab_name_list\*O. ...\" .zZ "Def,13377,R1.2.2,add ktname" .LI "\*L-local\*O" Specifies that the \*Lcreate\*O operation operates on local files only. .LI "\*L-noprivacy\*O" Specifies that key tables are sent over the network unencrypted. .LE ...\" .zZ "1.1: CR13078" ...\" .zZ "1.1: CR13069" .PP The \*Lcreate\*O operation creates a key table. The argument is a list of names of key tables to be created. The command takes an \%\*L-attribute\*O option to specify configuration information for \*Ldced\*O. ...\" .zA "Def,13377,R1.2.2,add ktname" The \*L-ktname\*O option is used to identify the specific key table to operation on, but only when the argument is a string binding representing a key table, not the fully qualified key table name. ...\" .zZ "Def,13377,R1.2.2,add ktname" The contents of the key table can be specified via the \*Ldata\*O attribute. The value of the option is applied to all elements of the argument list. This operation returns an empty string on success. .PP The value of the \*Ldata\*O attribute, if specified, is a list of keys. Each key must have a principal name and key type. The version is optional; if it is not present, the system will generate a version of \*L1\*O. If the key type is \*Lplain\*O, a key value must be specified. If the key type is \*Ldes\*O and a key value is not specified, one will be randomly generated. .PP \*LPrivileges Required\*O .PP You must have \*Li\*O (\*Linsert\*O) permission to the \*Lkeytab\*O object on the host. .PP \*LExamples\*O .PP The following example creates two keys for user \*Lmelman\*O and one key for \*Lpwang\*O on host \*Lmedusa\*O. One of \*Lmelman\*O's keys is an automatically generated Data Encryption Standard (DES) key. Both \*Lmelman\*O's second key and \*Lpwang\*O's key are manually entered keys. .oS dcecp> \*Lkeytab create /.:/hosts/medusa/config/keytab/radiology -attribute { \\\*C > \*L{{storage /opt/dcelocal/keys/radiology} {data {{melman des} \\\*C > \*L{melman plain 3 \*Vkey2\*L} {pwang des 2 \*Vkey3\*L}}}} \*C dcecp> .oE .SS "keytab delete" ...\" .zA "1.1: CR13078" ...\" .zA "1.1: CR13069" .PP Deletes a key table entry and its data. The syntax is as follows: .sS ...\" .zA "Def,13377,R1.2.2, clarify syntax" \*Lkeytab delete \*Vkeytab_name_list\*O [\*L-entry\*O] [\*L-noprivacy\*O] [\*L-local\*O] ...\" .zZ "Def,13377,R1.2.2, clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-entry\*O" Specifies that only the configuration information that \*Ldced\*O keeps is deleted, not the actual key table. .LI "\*L-noprivacy\*O" Specifies that key tables are sent over the network unencrypted. .LI "\*L-local\*O" Specifies that the \*Ldelete\*O operation operates on local files only. .LE ...\" .zZ "1.1: CR13069" ...\" .zZ "1.1: CR13078" .PP The \*Ldelete\*O operation deletes a key table entry and its data. The argument is a list of names of key table entries to be deleted in the order specified. If the \%\*L-entry\*O option is present, only the configuration information that \*Ldced\*O keeps is deleted, not the actual key table. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Ld\*O (\*Ldelete\*O) permission to the \*Lkeytab\*O object. If you are removing the key table you must have \*LD\*O (\*LDelete_object\*O) permission to the \*Lkeytab\*O object as well. .PP \*LExamples\*O .PP .oS dcecp> \*Lkeytab delete /.:/hosts/medusa/config/keytab/radiology\*C dcecp> .oE .SS "keytab help" .PP Returns help information about the \*Lkeytab\*O object and its operations. The syntax is as follows: .sS \*Lkeytab help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lkeytab\*O object. .LE .PP Used without an argument or option, the \*Lkeytab help\*O command returns brief information about each \*Lkeytab\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lkeytab\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lkeytab help\*O command. .PP \*LExamples\*O .PP ...\" .zA "def,13377,R1.2.2,revised help" .oS dcecp> \*Lkeytab help\*C add Adds keys into a key table. catalog Returns the list of key table names. create Creates a new key table entry and its keys. delete Deletes a key table and its associated data. list Lists all principals in a specified key table. remove Removes keys from a key table. show Returns the list of keys of a key table. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE ...\" .zZ "def,13377,R1.2.2,revised help" .SS "keytab list" ...\" .zA "1.1: CR13078" ...\" .zA "1.1: CR13069" .PP Returns a list of all the principals in the specified key table. The syntax is as follows: .sS ...\" .zA "Def,13377,R1.2.2, clarify syntax" \*Lkeytab list \*Vkeytab_name_list\*O [\*L-noprivacy\*O] [\*L-local\*O] ...\" .zZ "Def,13377,R1.2.2, clarify syntax" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-noprivacy\*O" Specifies that keytables are sent over the network unencrypted. .LI "\*L-local\*O" Specifies that the \*Llist\*O operation operates on local files only. .LE ...\" .zZ "1.1: CR13069" ...\" .zZ "1.1: CR13078" .PP The \*Llist\*O operation returns a list of all the principals in the specified key table. If the argument is a list of key table names the output is concatenated and a blank line inserted between key tables. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the \*Lkeytab\*O object on the host. .PP \*LExamples\*O .PP .oS dcecp> \*Lkeytab list /.:/hosts/medusa/config/keytab/self\*C /.../mycell/hosts/medusa/self /.../mycell/hosts/medusa/cds-server /.../mycell/hosts/medusa/cds-server dcecp> .oE .SS "keytab operations" .PP Returns a list of the operations supported by the \*Lkeytab\*O object. The syntax is as follows: .sS \*Lkeytab operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lkeytab operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lkeytab operations\*C add catalog create delete list remove show help operations dcecp> .oE .SS "keytab remove" ...\" .zA "1.1: CR13078" ...\" .zA "1.1: CR13069" .PP Removes a member from a key table. The syntax is as follows: .sS \*Lkeytab remove \*Vkeytab_name_list\*L -member \*Vprincipal_name_list\*O .nL ...\" .zA "Def,13377,R1.2.2, clarify syntax" [\*L-version \*Vkey_version\*O] [\*L-type \*Vkey_type\*O] [\*L-noprivacy\*O] .nL [\*L-local\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-member \*Vprincipal_name_list\*O" Specifies a list of one or more principal names of members to be removed from the key table. .LI "\*L-version \*Vkey_version\*O" Specifies a version number for the key. ...\" Required if the \%\*L-registry\*O option is not used. .LI "\*L-type \*Vkey_type\*O" Specifies whether the key is a \*Ldes\*O (data encryption standard) key or a \*Lplain\*O key. .LI "\*L-noprivacy\*O" Specifies that key tables are sent over the network unencrypted. .LI "\*L-local\*O" Specifies that the \*Lremove\*O operation operates on local files only. .LE ...\" .zZ "Def,13377,R1.2.2, clarify syntax" ...\" .zZ "1.1: CR13069" ...\" .zZ "1.1: CR13078" .PP The \*Lremove\*O operation removes a member from a key table. The argument is a list of names of key tables from which to remove members. The value of the required \%\*L-member\*O option is a list of names of principals to be removed from the key tables listed in the argument. The two options \*L-version\*O and \*L-type\*O can be used to limit the keys removed. If either or both of these options is present, then only keys matching the values of these options are removed. The value of the \%\*L-version\*O option can be a list of version numbers. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lx\*O (\*Lexecute\*O) permission to the \*Lkeytab\*O object on the host. .PP \*LExamples\*O .PP The following example removes all \*Ldes\*O keys for principal \*LD_Britt\*O: .oS dcecp> \*Lkeytab remove /.:/hosts/jimbo/config/keytab/self -member D_Britt -type des\*C dcecp> .oE .SS "keytab show" ...\" .zA "1.1: CR13078" ...\" .zA "1.1: CR13069" .PP Returns an attribute list of the key table entries specified in the argument. The syntax is as follows: .sS ...\" .zA "Def,13377,R1.2.2,clarify syntax;add -ktname" \*Lkeytab show \*Vkeytab_name_list\*O [\*L-entry\*O | \*L-members\*O] .nL [\*L-keys\*O] [\*L-ktname\*V residual_keytab_name\*O] [\*L-noprivacy\*O] [\*L-local\*O] ...\" .zZ "Def,13377,R1.2.2,clarify syntax;add ktname" .sE \*LOptions\*O .VL .LI "\*L-entry \*V\*O" Only the configuration information that \*Ldced\*O keeps is returned not the actual key table data. .LI "\*L-members\*O" Specifies that only the \*Ldata\*O attribute of each entry be returned. .LI "\*L-keys\*V\*O" Returns the actual values of keys. .LI "\*L-noprivacy\*O" Specifies that key tables are sent over the network unencrypted. ...\" .zA "Def,13377,R1.2.2,add ktname" .LI "\*L-ktname \*Vresidual_keytab_name\*O" Specifies the \*Lkeytab\*O object for which to list entries. If you use this option, you must specify \*Vkeytab_name_list\*O as a string binding. See \*LARGUMENTS\*O for more information about specifying a string binding for \*Vkeytab_name_list\*O. ...\" .zZ "Def,13377,R1.2.2,add ktname" .LI "\*L-local\*O" Specifies that the \*Lshow\*O operation operates on local files only. .LE ...\" .zZ "1.1: CR13069" ...\" .zZ "1.1: CR13078" .PP The \*Lshow\*O operation returns an attribute list of the key tables specified in the argument. The argument is a list of names of key tables. If called with \*L-entry\*O, then the \*Ldata\*O attribute is not returned. If the optional \%\*L-members\*O option is given, only the value of the \*Ldata\*O attribute is returned (a list of keys). Keys are not normally returned unless the \%\*L-keys\*O option is used. If the argument is a list, the output is concatenated and a blank line inserted between key tables. ...\" .zA "Def,13377,R1.2.2,add ktname" The \*L-ktname\*O option is used to identify the specific key table to operation on, but only when the argument is a string binding representing a key table, not the fully qualified key table name. ...\" .zZ "Def,13377,R1.2.2,add ktname" .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the \*Lkeytab\*O object on the host. .PP \*LExamples\*O .oS dcecp> \*Lkeytab show /.:/hosts/medusa/config/keytab/radiology -members\*C {melman des 1} {melman plain 3} {pwang des 2} dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_xattrschema(1m)\*O. .ad b ...\" .ad l ...\" \*Ldcecp(1m)\*O, ...\" \*Lxattrschema(1m)\*O. ...\" .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH link 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Llink\*O" .iX "link" "administering" .SH NAME .PP \*Llink\*O - A \*Ldcecp\*O object that manages a softlink in CDS .SH "SYNOPSIS" .PP .sS \*Llink create \*Vlink_name_list\*O .nL {\*L-to \*Vtarget_name\*O [\*L-timeout \*Vexpiration_time extension_time\*O] | .nL \*L-attribute \*Vattribute_list\*O} .PP \*Llink delete \*Vlink_name_list\*O .PP \*Llink help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Llink modify \*Vlink_name_list .nL \*O{[\*L-add \*Vattribute_list\*O] .nL [\*L-remove \*Vattribute_list\*O] .nL [\*L-change \*Vattribute_list\*O]} .PP \*Llink operations\*O .PP ...\" .zA "1.1, add -schema" \*Llink show \*Vlink_name_list\*O [\*L-schema\*O] ...\" .zZ "1.1, add -schema" .sE .SH "ARGUMENTS" .VL .LI "\*Vlink_name_list\*O" A list of one or more names of CDS softlinks. .LI "\*Voperation\*O" The name of the \*Llink\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Llink\*O object represents a Cell Directory Service (CDS) softlink. A softlink in CDS contains an attribute that has a name that is the same as the name of the object the softlink points to. The softlink contains several built-in attributes, but users are free to add their own attributes. Softlinks can point to objects, directories, and other softlinks. .SH "ATTRIBUTES" .PP The following are the CDS-defined attributes that may be present in CDS \*Llink\*O objects: .VL .LI "\*LCDS_CTS\*O" Specifies the creation timestamp (CTS) of the softlink. The is a read-only DTS-style time stamp, which is set by the system. .LI "\*LCDS_LinkTarget\*O" Specifies the full name of the directory, object entry, or other softlink to which the softlink points. .LI "\*LCDS_LinkTimeout\*O" Specifies a timeout value after which the softlink is either renewed or deleted. Its value is a list of two elements enclosed in braces, as follows: .iS {\*Vexpiration_time extension_time\*O} .iE where: .VL 1i .LI "\*Vexpiration_time\*O Is a date and time after which CDS checks for the existence of the softlink's target and either extends or deletes the soft link. The value is specified in the format \*Vyyyy\*L-\*Vmm\*L-\*Vdd\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*O; portions of it can be defaulted. .LI "\*Vextension_time\*O Is a period of time by which to extend the softlink's expiration time (if the server has validated that the target still exists). The value is specified in the format \*Vddd\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*O; portions of it can be defaulted. .LE .LI "\*LCDS_UTS\*O" Specifies the timestamp of the most recent update to an attribute of the softlink. The value is a read-only DTS-style timestamp, which is set by the system. .LE .PP See the \*VOSF DCE Administration Guide\*O for more information about link attributes. ...\ See the \*(Ag for more information about link attributes. .SH "OPERATIONS" .SS "link create" .PP Creates a new softlink entry in CDS. The syntax is as follows: .sS \*Llink create \*Vlink_name_list\*O .nL {\*L-to \*Vtarget-name\*O [\*L-timeout \*Vexpiration_time extension_time\*O] | .nL \*L-attribute \*Vattribute_list\*O} .PP \*LOptions\*O .PP .VL .LI "\*L-to\*O \*Vtarget-name\*O" Specifies a single name for the links to point to. If you don't use this option, you must specify the link target with the \%\*L-attribute\*O option. .LI "\*L-timeout\*O \*Vexpiration_time extension_time\*O" Specifies the expiration time and extension period for all soft links named by the \*Vlink-name_list\*O argument. The option syntax is as follows: .iS {\*Vexpiration_time extension_time\*O} .iE See \*LATTRIBUTES\*O for more detailed information about \*Llink\*O timeouts. If you omit the \%\*L-timeout\*O option, the link is permanent and must be explicitly deleted. .LI "\*L-attribute\*O \*Vattribute_list\*O" Allows you to specify attributes by using an attribute list. See \*LATTRIBUTES\*O for more detailed information about \*Llink\*O attributes. .LE .PP The \*Lcreate\*O operation creates a new softlink entry in CDS. The required \*Vlink_name_list\*O argument is a list of one or more full CDS names of the soft links to be created. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Li\*O (\*Linsert\*O) permission to the directory in which you intend to create the soft link. .PP \*LExamples\*O .PP The following command creates a permanent soft link named \*L/.:/sales/tokyo/price-server\*O that points to an object entry named \*L/.:/sales/east/price-server\*O. The expiration value indicates that CDS will check that the destination name \*L/.:/sales/east/price-server\*O still exists on June 25,1995, at 12:00 p.m. If the destination name still exists, the soft link remains in effect another 90 days. Thereafter, CDS will check that the destination name exists every 90 days. .oS dcecp> \*Llink create /.:/sales/tokyo/price-server -to \\\*C > \*L/.:/sales/east/price-server -timeout {1995-06-25-12:00:0090-00:00:00} \*C dcecp> .oE .PP You can enter the same information as the above example by using the \%\*L-attributes\*O option, as follows: .oS dcecp> \*Llink create /.:/sales/tokyo/price-server -attribute { \*C > \*L{CDS_LinkTarget /.:/sales/east/price-server} {CDS_LinkTimeout \*C > \*L{expiration 1995-06-25-12:00:00} {extension 90-00:00:00}} }\*C dcecp> .oE .SS "link delete" .PP Removes a link entry from CDS. The syntax is as follows: .sS \*Llink delete \*Vlink_name_list\*L .sE .PP The \*Ldelete\*O operation removes a link entry from CDS. This task is usually done through a client application. The required \*Vlink_name_list\*O argument is a list of one or more full CDS names of the link entry to be removed. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Ld\*O (\*Ldelete\*O) permission to the link entry, or \*LA\*O (\*LAdmin\*O) permission to the directory that stores the link entry. .PP \*LExamples\*O .oS dcecp> \*Llink delete /.:/sales/tokyo/price-server\*C dcecp> .oE .SS "link help" .PP Returns help information about the \*Llink\*O object and its operations. The syntax is as follows: .sS \*Llink help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-verbose\*O" Displays information about the \*Llink\*O object. .LE .PP Used without an argument or option, the \*Llink help\*O command returns brief information about each \*Llink\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Llink\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Llink help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Llink help\*C create Creates the named link. delete Deletes the named link. modify Adds, removes or changes an attribute in the named link. show Returns the attributes of a link. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "link modify" .PP Changes attributes in the specified softlinks. The syntax is as follows: .sS \*Llink modify \*Vlink_name_list .nL \*O{[\*L-add \*Vattribute_list\*O] .nL [\*L-remove \*Vattribute_list\*O] .nL [\*L-change \*Vattribute_list\*O]} .sE .PP \*LOptions\*O .PP .VL .LI "\*L-add\*O \*Vattribute_list\*O" Adds one or more new attributes to a softlink, or adds values to existing attributes when values are not already present. Add an attribute type with no value by specifying an attribute type with no value. .LI "\*L-remove\*O \*Vattribute_list\*O" Removes an entire attribute, or merely some attribute values, from a softlink. If only the attribute type is specified after the option, the entire attribute is removed. If an attribute type and value are specified, only that value is removed. If an attribute or value is not present, an error is returned. .LI "\*L-change\*O \*Vattribute_list\*O" Changes one attribute value to another for a softlink. Each attribute in the list has its existing value replaced by the new value given in the attribute list. For multi-valued attributes, all existing values are replaced by all the values listed for the attribute in the attribute list. If an attribute or value is not present, an error is returned. .LE .PP The \*Lmodify\*O operation can be used to change two attributes of a softlink: \*LCDS_LinkTarget\*O and \*LCDS_LinkTimeout\*O. The argument is a list of names of softlinks to be operated on. The operation takes the \%\*L-add\*O, \%\*L-remove\*O, and \%\*L-change\*O options to specify an attribute list to describe the changes. All the changes are performed on each softlink named in the argument. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission to the \*Llink\*O object. .PP \*LExamples\*O .PP The following example sets the link expiration time to 1998 and the extension time to ten days and zero hours: .oS dcecp> \*Llink modify /.:/depts/emergency -change { \*C > \*L{CDS_LinkTimeout {expiration 1998-01-20-12:00:00:00}\ > \*L{extension +10-0:0:0}} }\*C dcecp> .oE .SS "link operations" .PP Returns a list of the operations supported by the \*Llink\*O object. The syntax is as follows: .sS \*Llink operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Llink operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Llink operations\*C create delete modify show help operations dcecp> .oE .SS "link show" .P Returns attribute information associated with specified link entries. The syntax is as follows: ...\" .zA "1.1, add -schema" .sS \*Llink show \*Vlink_name_list\*O [\*L-schema\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-schema\*O This option returns whether an attribute is single or multi-valued. This is specific to a link, meaning that the same attribute can be single-valued on one link and multi-valued on another. .LE ...\" .zZ "1.1, add -schema" .PP The \*Lshow\*O operation displays attribute information associated with specified link entries. The required \*Vlink_name_list\*O argument is a list of one or more full CDS names of the soft links you want to show. If more than one link is shown, the attributes of all the soft links are concatenated into one list. The order of the returned attributes is the lexical order of the object identifiers (OIDs) of each attribute for each object. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the link entry. If you specify a wildcard link entry name, you also need \*Lr\*O (\*Lread\*O) permission to the directory that stores the link entry. .PP \*LExamples\*O .oS dcecp> \*Llink show /.:/depts/emergency\*C {CDS_CTS 1994-07-11-17:47:59.755+00:00I0.000/00-00-c0-8a-df-56} {CDS_UTS 1994-07-11-17:52:44.698+00:00I0.000/00-00-c0-8a-df-56} {CDS_LinkTarget /.../my_cell.acme_health.org/depts/radiology} {CDS_LinkTimeout {expiration 1995-07-11-00:00:00.000} {extension +10-10:00:00.000I-----}} \*Cdcecp> dcecp> \*Llink show /.:/gumby -schema\*C {CDS-CTS single} {CDS-UTS single} {CDS-LinkTarget single}\*C dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_clearinghouse(1m)\*O, \*Ldcecp_directory(1m)\*O, \*Ldcecp_object(1m)\*O. .ad b ...\" .ad l ...\" \*Ldcecp(1m)\*O, ...\" \*Lclearinghouse(1m)\*O, ...\" \*Ldirectory(1m)\*O, ...\" \*Lobject(1m)\*O. ...\" .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" ...\" .rm zA .rm zZ .TH log 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Llog\*O" .iX "log" "serviceability" "administering" .SH NAME \*Llog\*O - Manages serviceability routing and debug routing .SH "SYNOPSIS" .sS \*Llog help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Llog list \*O{\*VRPC_server_namespace_entry\*O | \*Vstring_binding_to_server\*O} .nL [\*L-comp \*Vcomponent_name_list\*O] .PP \*Llog modify \*O{\*VRPC_server_namespace_entry\*O | \*Vstring_binding_to_server\*O} .nL \*L-change\*O {\*Vrouting_specifications\*O | \*Vdebug_routing_specifications\*O} .PP \*Llog operations\*O .PP \*Llog show \*O{\*VRPC_server_namespace_entry\*O | \*Vstring_binding_to_server\*O} .nL [\*L-debug\*O] .sE .SH "ARGUMENTS" .VL 1i .LI "\*Voperation\*O" The name of the \*Llog\*O operation for which to display help information. .LI "\*VRPC_server_namespace_entry\*O" Specifies the namespace entry of the target server. ...\" .zA "def,13377,R1.2.2,added example" For example, \*L/.:/hosts/\*Vhost_name\*L/dts-entity\*O is the name of the DTS server. ...\" .zA "def,13377,R1.2.2,added example" .LI "\*Vstring_binding_to_server\*O" A remote procedure call (RPC) string binding that describes the target server's network location. The value has the form of an RPC string binding, without an object Universal Unique Identifier (UUID). The binding information contains an RPC protocol, a network address, and an endpoint within \*L[]\*O (brackets), in one of the two following forms: .iS \*Vrpc-prot-seq\*L:\*Vnetwork-addr\*L[\*Vendpoint\*L] \*Vobject_uuid\*L@\*Vrpc-prot-seq\*L:\*Vnetwork-addr\*L[\*Vendpoint\*L] .iE .LE .SH "DESCRIPTION" .PP The \*Llog\*O object represents the current state of message routing for a given server. It supports routing for both serviceability and debug messages. Debug routing may be removed from production environment servers while still being used by application servers. .PP The \*Llog\*O commands work on both the local and remote servers. You can identify the target server by supplying either the server's entry in the namespace or a fully bound string binding. You can specify multiple target servers as a space-separated list. When specifying multiple servers, you can mix the namespace entry and string binding formats in the same list. .SH "OPERATIONS" .SS "log help" .PP Returns help information about the \*Llog\*O object and its operations. The syntax is as follows: .sS \*Llog help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-verbose\*O" Displays detailed information about the \*Llog\*O object. .LE .PP Used without an argument or option, the \*Llog help\*O command returns brief information about each \*Llog\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Llog\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Llog help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Llog help\*C list Returns serviceability components registered by a server. modify Changes serviceability routing specifications of a server. show Returns serviceability routing settings for a server. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "log list" .PP Returns a list of serviceability components registered by the target server(s). The syntax is as follows: .sS \*Llog list \*O{\*VRPC_server_namespace_entry\*O | \*Vstring_binding_to_server\*O} .nL [\*L-comp \*Vcomponent_name_list\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-comp \*Vcomponent_name_list\*O A list of one or more DCE serviceability component names for which associated subcomponents should be returned. .LE .PP If you specify more than one server, the returned lists for the second and subsequent servers are concatenated to the returned list for the first server. .PP The \*L-comp\*O option specifies a space-separated list of DCE serviceability component names. For each named component, the command returns a list of the associated subcomponents. For each subcomponent in the list, the command displays its name, its level, and its description. The order of the component names is arbitrary. If you specify more than one component name, the resulting subcomponent lists are concatenated. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Llog list\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Llog list /.:/hosts/goober/cds-server\*C {svc cds dts rpc sec} dcecp> dcecp> \*Llog list /.:/hosts/goober/cds-server -comp dts\*C {general 0 "General server administration"} {events 0 "Events received and acted upon"} {arith 0 "Math operations"} {ctlmsgs 0 "Control messages received"} {msgs 0 "Messages received"} {states 0 "Server state transitions"} {threads 0 "Thread interactions"} {config 0 "Server/cell configuration"} {sync 0 "Server sync interactions"} dcecp> .oE .SS "log modify" .PP Sets message routing specifications for one or more specified servers. The syntax is as follows: .sS \*Llog modify \*O{\*VRPC_server_namespace_entry\*O | \*Vstring_binding_to_server\*O} .nL \*L-change\*O {\*Vrouting_specifications\*O | \*Vdebug_routing_specifications\*O} .sE .PP \*LOptions\*O .PP .VL .LI "\*L-change\*O" Specifies the routing specifications (serviceability or debug) to change. .LE .PP The \%\*L-change\*O option specifies the routing specifications you want to change. There is a fixed, well-known set of routing defaults. You can change these defaults, but you cannot add new routings or remove existing routings. Routing is always set on a per-server basis and is recorded in the \*Llog\*O object for each server. This operation returns an empty string on success. .PP Serviceability and debug messages can be written to any of the normal output destinations. You can specify routing for serviceability and debug messages in any of the following ways: .ML .LI Through the \*Ldcecp log\*O object, if the server supports the remote serviceability interface .LI By the contents of the \*Vdce-local-path\*L/svc/routing\*O routing file .LI By the contents of an environment variable .LE .P For a complete discussion of the ways in which you can specify routings for serviceability and debug messages, refer to the \*Lsvcroute(5)\*O reference page. .PP \*LPrivileges Required\*O .PP The privileges are determined by what the server allows for permissions. .PP \*LExamples\*O .PP .oS dcecp> \*Llog modify /.:/tserver -change {{FATAL TEXTFILE /dev/console} \\\*C .nL \*L{ERROR TEXTFILE /tmp/timop_errors.5.100} {NOTICE BINFILE /tmp/timop_log%ld }}\*C dcecp> .oE .SS "log operations" .PP Returns a list of the operations supported by the \*Llog\*O object. The syntax is as follows: .sS \*Llog operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Llog operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Llog operations\*C list modify show help operations dcecp> .oE .SS "log show" .PP Returns a list describing the current serviceability routing settings for a server. The syntax is as follows: .sS \*Llog show \*O{\*VRPC_server_namespace_entry\*O | \*Vstring_binding_to_server\*O} [\*L-debug\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-debug\*O" Returns debug routing settings rather than serviceability routing settings. .LE .PP If you specify more than one server, the returned routings for the second and subsequent servers are concatenated to the returned routings for the first server. The order of the returned routing settings is arbitrary. .PP By default the operation returns serviceability routing settings. Use the \%\*L-debug\*O option to return debug routing settings. Debug routing settings are not available on servers for which debugging has been turned off (production servers, for example). .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Llog show\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Llog show /.../bigred/hosts/acme/cds-clerk\*C {ERROR STDERR -} {FATAL FILE /dev/console} {WARNING FILE /tmp/warnings.log} dcecp> .oE .SH "RELATED INFORMATION" ...\" ---------------------------------------------------------------------- .PP .ad l Commands: \*Ldcecp(1m)\*O .PP Files: \*Lsvcroute(5)\*O. ...\"Books: ...\"The \*(Dk. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" .rm zA .rm zZ .TH name 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lname\*O" .iX "name" "administering" .SH NAME .PP \*Lname\*O - A \*Ldcecp\*O object that compares and expands DCE names .SH "SYNOPSIS" .sS ...\ .zA "def,13377,R1.2.2,clarify syntax" \*Lname compare \*Vname name\*O ...\ .zZ "def,13377,R1.2.2,clarify syntax" .PP \*Lname expand \*Vname\*O .PP ...\ .zA "1.1, CR13062" \*Lname get \*Vstring_binding\*O ...\ .zZ "1.1, CR13062" .PP \*Lname help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lname operations\*O .PP \*Lname parse \*Vname\*O .sE .SH "ARGUMENTS" .VL .LI "\*Vname\*O" The name of an object in the DCE namespace. Examples of names include principal names, names of security groups, names of Cell Directory Service (CDS) objects like directories, softlinks, child pointers and so on, names of remote procedure call (RPC) entries and RPC groups, and Distributed File Service (DFS) filenames. .LI "\*Voperation\*O" The name of the \*Lname\*O operation for which to display help information. ...\ .zA "1.1, CR13062" .LI "\*Vstring_binding\*O" An RPC string binding (without the object UUID) that identifies the network location of the target name. It contains an RPC protocol and a network address in the form: .iS \*Vrpc_prot_seq:network_addr .iE ...\ .zZ "1.1, CR13062" .LE .SH "DESCRIPTION" .PP The \*Lname\*O object resolves, compares, and parses DCE names and string bindings. .SH "OPERATIONS" .SS "name compare" .PP Compares two names. The syntax is as follows: .sS \*Lname compare \*Vname name\*O .sE .PP The \*Lcompare\*O operation compares two names given as arguments and returns \*L1\*O if they both syntactically refer to the same name. Otherwise it returns \*L0\*O. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lname compare\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lname compare /.:/sales/east east\*C Error: Incomplete name dcecp> dcecp> \*Lname compare /.:/sales/east /.../org_cell/sales/east\*C 1 dcecp> .oE .SS "name expand" .PP Expands a simple DCE name to a global name. The syntax is as follows: .sS \*Lname expand \*Vname\*O .sE .PP The \*Lexpand\*O operation takes a single name as an argument and returns the canonical form of the name. This has the affect of converting \*L/.:\*O to \*L/.../\*Vcellname\*O. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lname expand\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lname expand /.:/sales\*C /.../org_cell/sales dcecp> .oE ...\ .zA "1.1, CR13062" .SS "name get" .PP Returns a hostname given a full or partial string binding. The syntax is as follows: .sS \*Lname get \*Vstring_binding\*O .sE .PP The \*Lget\*O operation returns host name identified by a specified string binding. The \*Vstring_binding\*O argument is a single string binding; you cannot supply multiple bindings in one operation. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lname get\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lname get ncan_ip_tcp:15.21.248.170\*C hosts/goober dcecp> .oE ...\ .zZ "1.1, CR13062" .SS "name help" .PP Returns help information about the \*Lname\*O object and its operations. The syntax is as follows: .sS \*Lname help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lname\*O object. .LE .PP Used without an argument or option, the \*Lname help\*O operation returns brief information about each \*Lname\*O operation. about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lname\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lname help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lname help\*C compare Compares two names syntactically. expand Returns the canonical form of a name. get Gets host name from a partial or full string binding. parse Parses name into cell name and residual name. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "name operations" .PP Returns a list of the operations supported by the \*Lname\*O object. The syntax is as follows: .sS \*Lname operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lname operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lname operations\*C compare expand get parse help operations dcecp> .oE .SS "name parse" .PP Divides a name into a cellname and a residual name. The syntax is as follows: .sS \*Lname parse \*Vname\*O .sE .PP The \*Lparse\*O operation parses a name into a cellname and a residual name. The argument is a single DCE name. The operation returns a list of two elements: cell name and residual name. A name not beginning with a "/" is considered to be a name in the local cell. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lname parse\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lname parse hosts/goober\*C /.../pokey hosts/goober dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH object 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lobject\*O" .iX "object" "administering" .SH NAME .PP \*Lobject\*O - A \*Ldcecp\*O object that manages an object in the DCE Cell Directory service (CDS) .SH "SYNOPSIS" .PP .sS \*Lobject create \*Vobject_name_list\*O [\*L-attribute \*Vattribute_list\*O [\*L-single\*O]] .PP \*Lobject delete \*Vobject_name_list\*L .PP \*Lobject help \*O[\*Voperation\*O | \*L-verbose\*O] .PP ...\" .zA "Def,13377,R1.2.2, clarify syntax" \*Lobject modify \*Vobject_name_list .nL \*O{\*L-add \*Vattribute_list\*O [\*L-single\*O] | .nL \*L-remove \*Vattribute_list\*O [\*L-types\*O] | .nL \*L-change \*Vattribute_list\*O} ...\" .zZ "Def,13377,R1.2.2, clarify syntax" .PP \*Lobject operations\*O .PP \*Lobject show \*Vobject_name_list\*O [\*L-schema\*O] .sE .PP .SH "ARGUMENTS" .VL .LI "\*Vobject_name_list\*O" Examples of objects are remote procedure call (RPC) server entries, group entries, profile entries, and so on. .LI "\*Voperation\*O" The name of the \*Lobject\*O operation for which you want to see help information. .LE .SH "DESCRIPTION" .P ...\" .zA "def,13252,R1.2.1,recast sentences for clarity" An \*Lobject\*O object represents an entity in CDS that has a name and attributes. ...\" .zZ "def,13252,R1.2.1,recast sentences for clarity" An object identifies a resource such as a host system, a printer, an application, or a file. Attributes consist of a type and one or more values. Every object is the child of a CDS directory. .PP .SH "ATTRIBUTES" .VL .LI "\*LCDS_Class\*O" Specifies the class to which an object belongs. .LI "\*LCDS_CTS\*O" Specifies the creation timestamp of the CDS object. The value is a read-only DTS-style timestamp, which is set by the system. .LI "\*LCDS_ClassVersion\*O" Contains the version number of the object's class. This allows applications to build in compatibility with entries created by earlier versions. .LI "\*LCDS_ObjectUUID\*O" Specifies the unique identifier of the object. The read-only identifier is set by the system at creation time. .LI "\*LCDS_UTS\*O" Specifies the timestamp of the most recent update to an attribute of the object. The value is a read-only DTS-style timestamp, which is set by the system. .LE .PP ...\ See the \*(Ag for more information about object attributes. See the \*VOSF DCE Administration Guide\*O for more information about object attributes. .SH "OPERATIONS" .SS "object create" .PP Creates a new object entry in CDS. The syntax is as follows: .sS \*Lobject create \*Vobject_name_list\*O [\*L-attribute \*Vattribute_list\*O [\*L-single\*O]] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-attribute\*O \*Vattribute_list\*O" Allows you to specify attributes by using an attribute list. See \*LATTRIBUTES\*O for more information about object attributes. .LI "\*L-single\*O" Specifies that attribute values are single-valued. Otherwise, attributes are multi-valued. Valid only with the \%\*L-attribute\*O option. .LE .PP The \*Lcreate\*O operation creates a new object entry in CDS. This task is usually done through a client application. The required \*Vobject_name_list\*O argument is a list of the full CDS names of the object entries to be created. .PP Optionally, you can use the \%\*L-attribute\*O option to associate one or more attributes (see \*LATTRIBUTES\*O) with each object being created. The attribute values are multivalued unless the \%\*L-single\*O option is specified, in which case all attributes are single-valued. The \%\*L-single\*O option is valid only if the \%\*L-attribute\*O option is specified. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Li\*O (\*Linsert\*O) permission to the parent directory. .PP \*LExamples\*O .PP The following command creates an object entry named \*L/.:/sales/east/floor1cp\*O. The object entry describes a color printer on the first floor of a company's eastern sales office. .oS dcecp> \*Lobject create /.:/sales/east/floor1cp -attribute \\\*C > \*L{{CDS_Class printer} {CDS_ClassVersion 1.0}}\*C dcecp> .oE .SS "object delete" .PP Removes an object entry from CDS. The syntax is as follows: .sS \*Lobject delete \*Vobject_name_list\*O .sE .PP The \*Ldelete\*O operation removes an object entry from CDS. The required \*Vobject_name_list\*O argument is a list of the full CDS names of the object entries to be deleted. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Ld\*O (\*Ldelete\*O) permission to the object entry, or \*LA\*O (\*LAdmin\*O) permission to the directory that stores the object entry. .PP \*LExamples\*O .PP The following command deletes the object entry \*L/.:/sales/east/floor1pr2\*O: .oS dcecp> \*Lobject delete /.:/sales/east/floor1pr2 \*C dcecp> .oE .SS "object help" .PP Returns help information about the \*Lobject\*O object and its operations. The syntax is as follows: .sS \*Lobject help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOption\*O .PP .VL .LI "\*L-verbose\*O" Displays information about the \*Lobject\*O object. .LE .PP Used without an argument or option, the \*Lobject help\*O command returns brief information about each \*Lobject\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lobject\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lobject help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lobject help\*C create Creates the named object. delete Deletes the named object. modify Adds, removes or changes an attribute in the named object. show Returns the attributes of an object. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "object modify" .PP Adds or removes attributes or changes attribute values for object entries in CDS. The syntax is as follows: .sS ...\" .zA "Def,13377,R1.2.2, clarify syntax" \*Lobject modify \*Vobject_name_list .nL \*O{\*L-add \*Vattribute_list\*O [\*L-single\*O] | .nL \*L-remove \*Vattribute_list\*O [\*L-types\*O] | .nL \*L-change \*Vattribute_list\*O} ...\" .zZ "Def,13377,R1.2.2, clarify syntax" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-add\*O \*Vattribute_list\*O" Adds one or more new attributes to an object entry. .LI "\*L-single\*O May be used with the \%\*L-add\*O option to specify that attributes to be added are single-valued. .LI "\*L-remove\*O \*Vattribute_list\*O" Eliminates one or more attribute values from an attribute type of an object entry. For instance, removing a value from an attribute with three values leaves the attribute with two values. The argument is an attribute list of the following form: .iS {{\*Vattribute value\*L}...{\*Vattribute value\*L}} .iE .PP To remove an attribute type as well as its values, use the \%\*L-types\*O option with the \%\*L-remove\*O option. .PP If an attribute is not present, an error is returned. Fixed CDS attribute types, such as the CDS creation timestamp (\*LCDS_CTS\*O), cannot be removed. .LI "\*L-types\*O" May be used with the \%\*L-remove\*O option to remove the attribute type as well as its values. Invalid without the \%\*L-remove\*O option. .LI "\*L-change\*O \*Vattribute_list\*O" Changes one attribute value to another for an object entry. Each attribute in \*Vattribute_list\*O has its existing value replaced by the new value given. For multi-valued attributes, all existing values are replaced by all the values listed for the attribute in the attribute list. If an attribute or value is not present, an error is returned. .LE .PP The \*Lmodify\*O operation adds, or removes attributes or changes attribute values for object entries in CDS. This task is usually done through a client application. The required \*Vobject_name_list\*O argument is a list of the full CDS names of the object entries to be modified. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission to the object entry. .PP \*LExamples\*O .PP To add the \*Lsales_record\*O attribute with a value of \*Lregion2\*O to an object entry named \*L/.:/Q1_records\*O, follow these steps: .AL .LI Read the \*Lcds_attributes\*O file to check that the attribute \*Lsales_record\*O is listed, as shown in the following display: .oS OID LABEL SYNTAX 1.3.22.1.3.66 sales_record char .oE .LI Enter the following command to assign the value \*Lregion2\*O to the attribute \*Lsales_record\*O of an object entry named \*L/.:/Q1_records\*O. .oS dcecp>\*L object modify /.:/Q1_records -add {sales_record region2}\*C dcecp> .oE .LE .PP To remove the \*LRPC_CLASS\*O and \*LRPC_CLASS_VERSION \*O attributes: .oS dcecp>\*L object modify /.:/foo -remove {RPC_CLASS RPC_CLASS_VERSION} -types\*C dcecp> .oE .SS "object operations" .PP Returns a list of the operations supported by the \*Lobject\*O object. The syntax is as follows: .sS \*Lobject operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lobject operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lobject operations\*C create delete modify show help operations dcecp> .oE .SS "object show" .P Returns attribute information associated with specified object entries. The syntax is as follows: .sS \*Lobject show \*Vobject_name_list\*O [\*L-schema\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-schema\*O" Indicates whether an attribute is single or multi-valued. This is specific to an object, meaning that the same attribute can be single-valued on one object and multi-valued on another object. .LE .PP The \*Lshow\*O operation displays attribute information associated with specified object entries. The required \*Vobject_name_list\*O argument is a list of the full CDS names of the object entries to be examined. If more than one object is shown, the attributes of all the objects are concatenated into one list. The order of the returned attributes is the lexical order of the object identifiers (OIDs) of each attribute for each object. .PP The \%\*L-schema\*O option indicates whether an attribute is single-valued or multi-valued. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the object entry. If you specify a wildcard object entry name, you also need \*Lr\*O (\*Lread\*O) permission to the directory that stores the object entry. .PP \*LExamples\*O .PP .oS dcecp>\*L object show /.:/obj\*C {RPC_ClassVersion {0200} {0300}} {RPC_Group 1234} {CDS_CTS 1994-07-01-22:06:54.990-05:00I0.000/00-00-c0-f7-de-56} {CDS_UTS 1994-07-01-22:07:37.248-05:00I0.000/00-00-c0-f7-de-56} {CDS_Class 0200} dcecp> .oE .PP .oS dcecp>\*L object show /.:/obj -schema\*C {RPC_ClassVersion multi} {RPC_Group multi} {CDS_CTS single} {CDS_UTS single} {CDS_Class single} dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_clearinghouse(1m)\*O, \*Ldcecp_directory(1m)\*O, \*Ldcecp_link(1m)\*O, .ad b ...\" .ad l ...\" \*Ldcecp(1m)\*O, ...\" \*Lclearinghouse(1m)\*O, ...\" \*Ldirectory(1m)\*O, ...\" \*Llink(1m)\*O, ...\" .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH organization 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lorganization\*O" .iX "organization" "administering" .SH NAME .PP \*Lorganization\*O - A \*Ldcecp\*O object that manages an organization in the DCE Security Service .SH "SYNOPSIS" ...\" .zA "def,13377,R1.2.2,clarify syntax" .sS \*Lorganization add \*Vorganization_name_list\*L -member \*Vmember_name_list\*O .PP ...\" .zA "1.1: add cell_name" \*Lorganization catalog \*O[\*Vcell_name\*O] [\*L-simplename\*O] ...\" .zZ "1.1: add cell_name" .PP ...\" .zA "1.1: change to extended_rgy_attr_list " \*Lorganization create \*Vorganization_name_list\*O .nL {\*L-attribute \*Vextended_rgy_attr_list \*O | .nL \*L-\*Vattribute\*O \*Vvalue\*O} ...\" .zZ "1.1: change to extended_rgy_attr_list " .PP \*Lorganization delete \*Vorganization_name_list\*O .PP \*Lorganization help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lorganization list \*Vorganization_name_list\*O [\*L-simplename\*O] .PP ...\" .zA "1.1: change to extended_rgy_attr_list " \*Lorganization modify \*Vorganization_name_list\*O .nL {\*L-add \*Vextended_rgy_attr_list \*O | .nL \*L-remove \*Vextended_rgy_attr_list \*O [\*L-types\*O] | .nL \*L-change\*O \*Vextended_rgy_attr_list \*O | .nL \*L-\*Vattribute\*O \*Vvalue\*O} ...\" .zZ "1.1: change to extended_rgy_attr_list " .PP \*Lorganization operations\*O .PP \*Lorganization remove \*Vorganization_name_list\*L -member \*Vmember_name_list\*O .PP \*Lorganization rename \*Vorganization_name\*L -to \*Vnew_organization_name\*L .PP \*Lorganization show \*Vorganization_name_list\*O .nL [\*L-all\*O | [\*L-policies\*O] | [\*L-xattrs\*O]] .sE ...\" .zZ "def,13377,R1.2.2,clarify syntax" .SH "ARGUMENTS" .VL ...\" .zA "1.1: add cell_name" .LI "\*Vcell_name\*O The name of a cell to contact when processing the \*Lcatalog\*O operation. The name must be a fully qualified cell name, such as \*L/.:\*O or \*L/.../\*Vcell_name\*O ...\" .zZ "1.1: add cell_name" .LI "\*Voperation\*O" The name the of \*Lorganization\*O operation for which to display help information. .LI "\*Vorganization_name_list\*O" A list of one or more names of organizations to act on. Supply the names as follows: .ML .LI Fully qualified names in the form: \*L/.../\*Vcell_name\*L/\*Vorganization_name\*O or \*L/.:/\*Vorganization_name\*O .LI Cell-relative names in the form: \*Vorganization_name\*O. These names refer to an organization in the cell identified in the \*L_s(sec)\*O convenience variable, or if the \*L_s(sec)\*O convenience variable is not set, in the local host's default cell. .LE .PP Do not mix fully-qualified names and cell-relative names in a list. In addition, do not use the names of registry database objects that contain organization information; in other words, do not use names that begin with ...\" .zA "def,13254,R1.2.1,/sec/organization to /sec/org" \*L/.:/sec/org/\*O. ...\" .zZ "def,13254,R1.2.1,/sec/organization to /sec/org" .LI "\*Vorganization_name\*O" The name of a single organization to act on. See \*Vorganization_name_list\*O for the name format. ...\" .zZ "def,13254,R1.2.1,/sec/organization to /sec/org" .LE .SH "DESCRIPTION" .PP The \*Lorganization\*O object represents registry organizations. Unless otherwise noted, all \*Lorganization\*O operations take the names of the organizations to act on as an argument. .PP When this command executes, it attempts to bind to the registry server identified in the \*L_s(sec)\*O variable. If that server cannot process the request or if the \*L_s(sec)\*O variable is not set, the command binds to either an available slave server or the master registry server, depending on the operation. Upon completion the command sets the \*L_b(sec)\*O convenience variable to the name of the registry server to which it bound. .SH "ATTRIBUTES" .PP The \*Lorganization\*O object supports two kinds of attributes: organization and policy. .ML .LI Organization attributes consist of the organization's name, Universal Unique Identifier (UUID), and organization identifier. Organization attributes may or may not have default values. They assume a default value or a value set by administrators. .LI Policy attributes regulate such things as account and password lifetimes for all accounts associated with a particular organization. If you do not set these attributes, they default to the value set for the registry as a whole with the \*Lregistry modify\*O command. Note that if a policy attribute value set for the registry as a whole is stricter than the value you set for an organization, the registrywide value is used. .LE .PP .SS "Organization Attributes" .VL .LI "\*Lorgid \*Vvalue\*O" Used with the \*Lcreate\*O operation to specify the organization identifier for the organization. If this attribute is not set when an organization is created, an organization identifier is assigned automatically. Do not specify the \%\*L-orgid\*O attribute when creating two or more organizations with the same command. If you do, the second \*Lcreate\*O operation will fail, since the organization identifier is already in use after the first is created. However, the \*Lalias\*O and \%\*Lorgid\*O attributes can be specified to create several aliases for an existing organization with one command. .PP .LI "\*Luuid \*Vhexadecimal number\*O" Used with the \*Lcreate\*O operation to specify the organization's UUID, a unique internal identifier. If this attribute is not set when an organization is created, an organization identifier is assigned automatically. Use the UUID attribute only to adopt an orphaned UUID. Normally the UUID for a new organization is generated by the registry. In cases where data exists tagged with a UUID of an organization that has been deleted from the registry, it can be entered using the \*Lcreate\*O operation to specify the old UUID for a new organization. The UUID specified \*Emust\*O be an orphan, that is, a UUID for which no name exists in the registry. An error occurs if you specify a name that is already defined in the registry. .LI "\*Lfullname \*Vstring\*O" Used with the \*Lcreate\*O and \*Lmodify\*O operations to specify the organization's full name, a name used for information purposes only. The fullname typically describes or expands a primary name to allow easy recognition by users. For example, an organization could have a primary name of \*Labc\*O and a full name of \*LAdvanced Binary Corporation\*O. The value is a string. If it contains spaces, it is displayed in quotes and, on entry, must be enclosed in quotes or braces. The \*Lfullname\*O attribute defaults to the null string (that is, blank). .LE .PP .SS "Policy Attributes" Since organization policy attributes do not exist on an organization unless explicitly defined, they attributes have no default values. The organization policy attributes are as follows: .VL .LI "\*Lacctlife {\*Vrelative_time \*L| unlimited}\*O" Defines the lifespan of accounts. Specify the time by using the Distributed Time Service (DTS) relative time format (\*V[-]dd-hh:mm:ss\*O) or the string \*Lunlimited\*O. .LI "\*Lpwdalpha {yes | no} \*O" Defines whether or not passwords can consist entirely of alphanumeric characters. Its value is either \*Lyes\*O or \*Lno\*O. .LI "\*Lpwdexpdate {\*VISO_timestamp\*L | \*Lnone\*O}" Defines a date on which a password will expire. Specify the date by using an ISO compliant time format such as \*VCC\*L-\*VMM\*L-\*VDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*O or the string \*Lnone\*O, which specifies that the password will not expire. .LI "\*Lpwdlife {\*Vrelative_time \*L| unlimited}\*O" Defines the lifespan of passwords. Specify the time by using the DTS relative time format (\*L[-]\*VDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*O) or the string \*Lunlimited\*O. .LI "\*Lpwdminlen \*Vinteger\*O" Defines the minimum number of characters in a password. Its value is a positive integer or the integer \*L0\*O, which means there is no minimum length. .LI "\*Lpwdspaces {yes | no}\*O" Defines whether or not passwords can consist entirely of spaces. Its value is either \*Lyes\*O or \*Lno\*O. .LE .PP ...\" See the \*(Ag for more information about organization and policy attributes. See the \*VOSF DCE Administration Guide\*O for more information about organization and policy attributes. .SH "OPERATIONS" .SS "organization add" .PP Adds members to a security organization. The syntax is as follows: ...\" .zA "def,13377,R1.2.2,clarify syntax" .sS \*Lorganization add \*Vorganization_name_list\*L -member \*Vmember_name_list\*O .sE ...\" .zZ "def,13377,R1.2.2,clarify syntax" .PP \*LOptions\*O .VL .LI "\*L-member \*Vmember_name_list\*O" Specifies a list of one or more names of principals to be added to each organization in the argument. .LE .PP The \*Ladd\*O operation adds members to an organization. The \*Vorganization_name_list\*O argument is a list of names of organizations to be added to. The \*Vmember_name_list\*O argument of the required \%\*L-member\*O option is a list of names of principals to be added to each organization in the argument. The principals must exist or the command will return an error. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) and \*LM\*O (\*LMember_list\*O) permissions on the target organization and \*Lr\*O (\*Lread\*O) and \*Lg\*O (\*Lgroups\*O) permissions on the principal being added. .PP \*LExamples\*O .PP .oS dcecp> \*Lorganization add managers -member W_White\*C dcecp> .oE .SS "organization catalog" .PP Returns a list of the names of all organizations in the registry. The syntax is as follows: ...\" .zA "1.1: add cell_name" .sS \*Lorganization catalog \*O[\*Vcell_name\*O] [\*L-simplename\*O] .sE ...\" .zZ "1.1: add cell_name" .PP \*LOptions\*O .VL .LI "\*L-simplename\*O" Returns a list of organization names in the registry without prepending the cell name. .LE .PP The \*Lcatalog\*O operation returns a list of the names of all organizations in the local registry in lexical order. Use the \*Vcell_name\*O argument to return a list of organizations in another cell's registry. By default, fully qualified names are returned in the form \*Vcellname\*L/\*Vorganization_name\*O. Use the \%\*L-simplename\*O option to return them in the form \*Vorganization_name\*O. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the \*L/.:/sec/organization\*O directory. .PP \*LExamples\*O .PP .oS dcecp> \*Lorganization catalog\*C /.../my_cell.goodcompany.com/none /.../my_cell.goodcompany.com/users /.../my_cell.goodcompany.com/managers dcecp> dcecp> \*Lorganization catalog -simplename\*C none users managers dcecp> .oE .SS "organization create" .PP Creates a new organization in the registry database. The syntax is as follows: ...\" .zA "def,13377,R1.2.2,clarify syntax" ...\" .zA "1.1: change to extended_rgy_attr_list " .sS \*Lorganization create \*Vorganization_name_list\*O .nL {\*L-attribute \*Vextended_rgy_attr_list \*O | .nL \*L-\*Vattribute\*O \*Vvalue\*O} ...\" .zZ "1.1: change to extended_rgy_attr_list " .sE .PP \*LOptions\*O .VL .LI "\*L-\*Vattribute value\*O" As an alternative to using the \*L-attribute\*O option with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. You cannot use this option to specify ERAs; it is only for the standard attributes described in \*LATTRIBUTES\*O. .LI "\*L-attribute \*Vextended_rgy_attr_list\*O" Allows you to specify attributes, including ERAs, by using an attribute list rather than using the \*L-\*Vattribute value\*O option. The format of an attribute list is as follows: .iS {{\*Vextended_rgy_attr_list \*Vvalue\*O}...{\*Vextended_rgy_attr_list \*Vvalue\*O}} .iE .LE .PP See the \*VOSF DCE Administration Guide\*O for more information on ERAs. .PP ...\" .zA "def,13377,R1.2.2,clarify syntax" .PP The \*Lcreate\*O operation creates a new organization. The \*Vorganization_name_list\*O argument is a list of names of organizations to be created. Options are used to specify the attributes of the newly created organization. All options are applied to all organizations in the argument list. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Li\*O (\*Linsert\*O) permission to the directory in which the organization is to be created. .PP \*LExamples\*O .PP .oS dcecp> \*Lorganization create temps -fullname "Temporary Employees"\*C dcecp> .sp .5 dcecp> \*Lorganization create temps -attribute {fullname "Temporary Employees"}\*C dcecp> .sp .5 dcecp> \*Lorg create dce -fullname {Dist Comp Env} -orgid 101\*C dcecp> .sp .5 dcecp> \*Lorg create dce -fullname {Dist Comp Env} \\ \*C> \*L-uuid c2aac790-dc6c-11cc-a6f8-080009251352\*C dcecp> .oE .SS "organization delete" .PP Deletes organizations from the registry. The syntax is as follows: .sS \*Lorganization delete \*Vorganization_name_list\*O .sE .PP The \*Ldelete\*O operation deletes organizations from the registry. The \*Vorganization_name_list\*O argument is a list of names of organizations to be deleted. If a named organization does not exist, an error is generated. This operation returns an empty string on success. .PP This operation also deletes any accounts associated with organizations that are deleted. To preserve accounts, add desired principles to a different organization by using the \*Lorganization add -member\*O command. Modify the principals' accounts to point to the new organization by using the \*Laccount modify\*O command. Then you can delete the organization by using the \*Lorganization delete\*O command. .PP \*LPrivileges Required\*O .PP You must have \*Ld\*O (\*Ldelete\*O) permission to the directory in which the target organization exists. You must have \*Lr\*O (\*Lread\*O) and \*LD\*O (\*LDelete_object\*O) permissions on the organization to be deleted. .PP \*LExamples\*O .PP .oS dcecp> \*Lorganization delete temps\*C dcecp> .oE .SS "organization help" .PP Returns help information about the \*Lorganization\*O object and its operations. The syntax is as follows: .sS \*Lorganization help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lorganization\*O object. .LE .PP Used without an argument or option, the \*Lorganization help\*O command returns brief information about each \*Lorganization\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lorganization\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lorganization help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lorganization help\*C add Adds a member to the named organization. catalog Returns a list of all the names of organizations. create Creates an organization in the registry. delete Deletes an organization from the registry. list Returns a list of all the members of an organization. modify Changes the information about an organization. remove Removes a member from the named organization. rename Renames the specified organization. show Returns the attributes of an organization. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "organization list" .PP Returns a list of the names of all members of an organization. The syntax is as follows: .sS \*Lorganization list \*Vorganization_name_list\*O [\*L-simplename\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-simplename\*O" Returns a list of member names in the organization without prepending the cell name. .LE .PP The \*Llist\*O operation returns a list of the names of all members of an organization. The \*Vorganization_name_list\*O argument is a list of names of organizations. By default, fully qualified names are returned in the form \*Vcellname/member_name\*O. If the \*L-simplename\*O option is given, the cell name is not prepended to the member names. Names are returned in lexical order. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the organization. .PP \*LExamples\*O .PP .oS dcecp> \*Lorganization list managers\*C /.../my_cell.goodcompany.com/W_Ward /.../my_cell.goodcompany.com/L_Jones /.../my_cell.goodcompany.com/S_Preska /.../my_cell.goodcompany.com/S_Rohrer /.../my_cell.goodcompany.com/J_Wanders /.../my_cell.goodcompany.com/K_Parsons dcecp> dcecp> \*Lorganization list {managers users}\*C /.../my_cell.goodcompany.com/W_Ward /.../my_cell.goodcompany.com/L_Jones /.../my_cell.goodcompany.com/S_Preska /.../my_cell.goodcompany.com/S_Rohrer /.../my_cell.goodcompany.com/J_Wanders /.../my_cell.goodcompany.com/W_Ross /.../my_cell.goodcompany.com/J_Severance /.../my_cell.goodcompany.com/J_Hunter /.../my_cell.goodcompany.com/B_Carr /.../my_cell.goodcompany.com/E_Vliet /.../my_cell.goodcompany.com/J_Egan /.../my_cell.goodcompany.com/F_Willis dcecp> .oE .SS "organization modify" .PP Changes attributes and policies of organizations. The syntax is as follows: ...\" .zA "def,13377,R1.2.2,clarify syntax" ...\" .zA "1.1: change to extended_rgy_attr_list " .sS \*Lorganization modify \*Vorganization_name_list\*O .nL {\*L-add \*Vextended_rgy_attr_list \*O | .nL \*L-remove \*Vextended_rgy_attr_list \*O [\*L-types\*O] | .nL \*L-change\*O \*Vextended_rgy_attr_list \*O | .nL \*L-\*Vattribute\*O \*Vvalue\*O} ...\" .zZ "1.1: change to extended_rgy_attr_list " .sE ...\" .zZ "1.1: change to extended_rgy_attr_list " .PP \*LOptions\*O .VL .LI "\*L-\*Vattribute value\*O" As an alternative to using options with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. You cannot use this option to specify ERAs; it is only for standard group attributes described in \*LATTRIBUTES\*O. .LI "\*L-add\*O \*Vextended_rgy_attr_list\*O" Allows you to modify attributes, including ERAs, by using an attribute list rather than using individual attribute options. The format of an attribute list is as follows: .iS {{\*Vextended_rgy_attr_list \*Vvalue\*O}...{\*Vextended_rgy_attr_list \*Vvalue\*O}} .iE .PP ...\" .zA "def,13377,R1.2.2, Clarify syntax" .LI "\*L-change \*Vextended_rgy_attr_list\*O" ...\" .zZ "def,13377,R1.2.2, Clarify syntax" Allows you to modify attributes, including ERAs, by using an attribute list rather than using individual attribute options. See the \*L-add\*O option for the attribute list format. ...\" .zA "def,13377,R1.2.2, Clarify syntax" .LI "\*L-remove\*O \*Vextended_rgy_attr_list\*O" Allows you to modify attributes, including ERAs, by using an attribute list rather than using individual attribute options such as \%\*L-fullname\*O, \%\*L-acctlife\*O, and so on. See the \*L-add\*O option for the attribute list format. .PP Without the \%\*L-types\*O option, \*L-remove\*O deletes individual attribute instances attached to the group. In this case, \*Vextended_rgy_attr_list\*O is a list of attribute-value pairs. With the \%\*L-types\*O option, \*L-remove\*O deletes attribute types (and all instances of that type) attached to the group. In this case, \*Vextended_rgy_attr_list\*O is a list of attribute types. ...\" .zZ "def,13377,R1.2.2, Clarify syntax" .LI "\*L-types\*O" Used with the \%\*L-remove\*O option to remove attribute types (and all instances of that type) attached to the group. .LE See the \*VOSF DCE Administration Guide\*O for more information about ERAs. ...\" See the \*(Ag for more information about ERAs. ...\" .zZ "1.1, add -types" ...\" .zZ "1.1, change to extended_registry_attribute_list" .PP The \*Lmodify\*O operation changes attributes and policies of organizations. (To change registry-wide policies, use the \*Lregistry\*O command.) .PP The \*Vorganization_name_list\*O argument is a list of names of organizations to be operated on. All modifications are applied to all organizations named in the argument. Organizations are modified in the order they are listed and all modifications to an individual organization are atomic. Modifications to multiple organizations are not atomic. A failure for any one organization in a list causes an error to be generated and the rest of the operation to be aborted. This operation returns an empty string on success. .PP The \%\*L-change\*O option can modify the value of any attribute except for \*Lorgid\*O and \*Luuid\*O. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) and \*Lm\*O (\*Lmgmt_info\*O) permissions on the organization to be modified. .PP \*LExamples\*O .PP .oS dcecp> \*Lorganization modify temps -acctlife 180-00:00:00 \\ \*C> \*L-pwdalpha yes -pwdlife 30-00:00:00 \\ \*C> \*L-pwdexpdate 1995-12-31-23:59:59 -pwdspaces yes\*C dcecp> dcecp> \*Lorganinzation modify temps -add {test_era 101}\*C dcecp> dcecp> \*Lorganization show temps -all\*C {fullname {}} {orgid 12} {uuid 0000000c-03d5-21cf-9802-08000985b5a6} {test_era 101} {acctlife +180-00:00:00.000I-----} {pwdalpha yes} {pwdexpdate 1995-12-31-23:59:59.000+00:00I-----} {pwdlife +30-00:00:00.000I-----} {pwdminlen 0} {pwdspaces yes} dcecp> .oE .SS "organization operations" .PP Returns a list of the operations supported by the \*Lorganization\*O object. The syntax is as follows: .sS \*Lorganization operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lorganization operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lorganization operations\*C add catalog create delete list modify remove rename show help operations dcecp> .oE .SS "organization remove" .P Removes a member from an organization. The syntax is as follows: .sS \*Lorganization remove \*Vorganization_name_list\*L -member \*Vmember_name_list\*O .sE .PP \*LOptions\*O .VL .LI "\*L-member \*Vmember_name_list\*O" Specifies a list of one or more names of principals to be removed from each organization in the argument. .LE .PP The \*Lremove\*O operation removes a member from an The argument is a list of names of organizations from which to remove members. The value of the required \*L-member\*O option is a list of names of principals to remove from the organizations listed in the argument. When a member is removed from an organization, any accounts associated with that principal and organization are deleted. Remember that accounts are associated with a principal, a group, and an organization; so the statement means that any accounts where both the principal name and account name match those given to this command are removed, but accounts where only one matches are untouched. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) and \*LM\*O (\*LMember_list\*O) permissions on the target organizations and \*Lr\*O (\*Lread\*O) permission on the member to be removed. .PP \*LExamples\*O .PP .oS dcecp> \*Lorganization remove managers -member J_Wanders\*C dcecp> dcecp> \*Lorganization add rigel -member W_White\*C dcecp> \*Laccount modify W_White -organization rigel\*C dcecp> \*Lorganization add rigel -member W_Ross\*C dcecp> \*Laccount modify W_Ross -organization rigel\*C dcecp> \*Laccount show W_Ross\*C {created /.../my_cell.goodcompany.com/cell_admin 1994-06-30-12:39:48.000+00:00I-----} {description {}} {dupkey no} {expdate none} {forwardabletkt yes} {goodsince 1994-06-30-12:39:48.000+00:00I-----} {group users} {home /} {lastchange /.../my_cell.goodcompany.com/cell_admin 1994-06-30-12:39:48.000+00:00I-----} {organization rigel} {postdatedtkt no} {proxiabletkt no} {pwdvalid yes} {renewabletkt yes} {server yes} {shell {}} {stdtgtauth yes} dcecp> dcecp> \*Lorganization remove gemini -member W_Ross\*C dcecp> .oE .SS "organization rename" .P This operation changes the name of a specified organization. The syntax is as follows: .sS \*Lorganization rename \*Vorganization_name\*L -to \*Vnew_organization_name\*O .sE .PP \*LOptions\*O .VL .LI "\*L-to \*Vnew_organization_name\*O" Specifies the new name of the organization. .PP See \*LARGUMENTS\*O for a description of organization names. .LE .PP The \*Lrename\*O operation changes the name of a specified organization. The \*Vorganization_name\*O argument is a single name of an organization to be renamed. The required \%\*L-to\*O option specifies the new name, which may not be a list. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) and \*Lf\*O (\*Lfull name\*O) permission to the specified organizations. .PP \*LExamples\*O .PP .oS dcecp> \*Lorganization list rigel\*C /.../my_cell.goodcompany.com/H_Lewis /.../my_cell.goodcompany.com/R_Mathews /.../my_cell.goodcompany.com/K_Doe /.../my_cell.goodcompany.com/W_Ross /.../my_cell.goodcompany.com/W_Williams /.../my_cell.goodcompany.com/D_White dcecp> dcecp> \*Lorganization rename rigel -to sirus\*C dcecp> dcecp> \*Lorganization list rigel\*C Error: Registry object not found dcecp> dcecp> \*Lorganization list sirus\*C /.../my_cell.goodcompany.com/H_Lewis /.../my_cell.goodcompany.com/R_Mathews /.../my_cell.goodcompany.com/K_Doe /.../my_cell.goodcompany.com/W_Ross /.../my_cell.goodcompany.com/W_Williams /.../my_cell.goodcompany.com/D_White dcecp> .oE .SS "organization show" .P Returns registry information for the specified organizations. The syntax is as follows: ...\" .zA "def,13377,R1.2.2,clarify syntax" .sS \*Lorganization show \*Vorganization_name_list\*O .nL [\*L-all\*O | [\*L-policies\*O] | [\*L-xattrs\*O]] ...\" .zZ "def,13377,R1.2.2,clarify syntax" .SE .PP \*LOptions\*O .VL .LI "\*L-policies\*O" Returns only the polices of the organization, with no other attributes. .LI "\*L-xattrs\*O" Returns only the ERAs of the organization, with no other attributes. .LI "\*L-all\*O" Return the attributes followed by the policies and ERAs. .LE .PP The \*Lshow\*O operation returns an attribute list describing the specified organizations. The \*Vorganization_name_list\*O argument is a list of names of organizations to be operated on. If more than one organization is given, the attributes are concatenated together. .PP Attributes are returned in the following order: \*Lfullname\*O, \*Lorgid\*O, \*Luuid\*O. Policies are returned in the following order: \*Lacctlife\*O, \*Lpwdalpha\*O, \*Lpwdexpdate\*O, \*Lpwdlife\*O, \*Lpwdminlen\*O, and \*Lpwdspaces\*O. If the organization does not have any policies, then \*Lnopolicy\*O is returned. .PP The policy set for an organization and the policy set for the registry as a whole may differ. If this is the case, \*Lshow\*O displays both policies and tags the registry policy with the label ``effective.'' The actual policy in effect is the stricter of the two displayed policies, regardless of the effective label. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission on the specified organizations. .PP \*LExamples\*O .PP .oS dcecp> \*Lorganization show temps\*C {fullname {Temporary Employees}} {orgid 103} {uuid 00000067-9402-21cd-a602-0000c08adf56} dcecp> dcecp> \*Lorganization show temps -policies\*C {acctlife +180-00:00:00.000I-----} {pwdalpha yes} {pwdexpdate 1995-12-31-23:59:59.000+00:00I-----} {pwdlife +30-00:00:00.000I-----} {pwdminlen 0} {pwdspaces yes} dcecp> dcecp> \*Lorganization show temps -policies\*C {acctlife 30 days} {pwdalpha no} {pwdexpdate none} {pwdlife 4 effective 5 days} {pwdminlen 6} {pwdspaces no} dcecp> dcecp> \*Lorganization show temps -all \*C {fullname {Temporary Employees}} {orgid 103} {uuid 00000067-9402-21cd-a602-0000c08adf56} {acctlife +180-00:00:00.000I-----} {pwdalpha yes} {pwdexpdate 1995-12-31-23:59:59.000+00:00I-----} {pwdlife +30-00:00:00.000I-----} {pwdminlen 0} {pwdspaces yes} dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_account(1m)\*O, \*Ldcecp_group(1m)\*O, \*Ldcecp_principal(1m)\*O, \*Ldcecp_registry(1m)\*O, \*Ldcecp_xattrschema(1m)\*O. ...\" \*Laccount(1m)\*O, ...\" \*Ldcecp(1m)\*O, ...\" \*Lgroup(1m)\*O, ...\" \*Lprincipal(1m)\*O, ...\" \*Lregistry(1m)\*O, ...\" \*Lxattrschema(1m)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH principal 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lprincipal\*O" .iX "principal" "administering" .SH NAME .PP \*Lprincipal\*O - A \*Ldcecp\*O object that manages a principal in the DCE Security Service .SH "SYNOPSIS" .PP .sS ...\" .zA "def,13377,R1.2.2,clarify syntax" ...\" .zA "1.1: add cell_name" \*Lprincipal catalog \*O[\*Vcell_name\*O] [\*L-simplename\*O] ...\" .zZ "1.1: add cell_name" .PP ...\" .zA "1.1: change to extended_attribute_list" \*Lprincipal create \*Vprincipal_name_list\*O .nL {\*L-attribute \*Vextended_rgy_attr_list\*O | .nL \*L-\*Vattribute value\*O} ...\" .zZ "1.1: change to extended_attribute_list" .PP \*Lprincipal delete \*Vprincipal_name_list\*O .PP \*Lprincipal help \*O[\*Voperation\*O | \*L-verbose\*O] .PP ...\" .zA "1.1: change to extended_attribute_list" ...\" .zA "1.1: add -types" \*Lprincipal modify \*Vprincipal_name_list\*O .nL {\*L-add \*Vextended_rgy_attr_list\*O | .nL \*L-remove \*Vextended_rgy_attr_list\*O [\*L-types\*O] | .nL \*L-change\*O \*Vextended_rgy_attr_list\*O | .nL \*L-\*Vattribute value\*O} ...\" .zZ "1.1: add -types" ...\" .zZ "1.1: change to extended_attribute_list" .PP \*Lprincipal operations\*O .PP \*Lprincipal rename \*Vprincipal_name\*L -to \*Vnew_principal_name\*O .PP \*Lprincipal show \*Vprincipal_name_list \*O[\*L-all \*O| \*L-xattrs\*O] ...\" .zZ "def,13377,R1.2.2,clarify syntax" .sE .SH "ARGUMENTS" .VL ...\" .zA "1.1: add cell_name" .LI "\*Vcell_name\*O The name of a cell to contact when processing the \*Lcatalog\*O operation. The name must be a fully qualified cell name, such as \*L/.:\*O or \*L/.../\*Vcell_name\*O ...\" .zZ "1.1: add cell_name" .LI "\*Voperation\*O" The name of the \*Lprincipal\*O operation for which to display help information. .LI "\*Vprincipal_name_list\*O" A list of one or more names of principals to act on. Supply the names as follows: .ML .LI Fully qualified principal names in the form .iS \*L/.../\*Vcell_name\*L/\*Vprincipal_name\*O or \*L/.:/\*Vprincipal_name\*O .iE .LI Cell-relative principal names in the form .iS \*Vprincipal_name\*O .iE These names refer to a principal in the cell identified in the \*L_s(sec)\*O convenience variable, or if the \*L_s(sec)\*O convenience variable is not set, in the local host's default cell. .LE .PP Do not mix fully-qualified names and cell-relative names in a list. In addition, do not use the names of registry database objects that contain principal information; in other words, do not use names that begin with \*L/.:/sec/principal\*O. .LI "\*Vprincipal_name\*O" The name of a principal to act on. See \*Vprincipal_name_list\*O for the name format. .LE .SH "DESCRIPTION" .PP The \*Lprincipal\*O object represents registry principals. Unless otherwise noted, all of the operations of this object take the names of principals to act on as an argument. They must be principal names, not the names of the database objects that contain registry information about principals (that is, the names must not begin with \*L/.:/sec/principal\*O). .P ...\" ...\" .zA "dec,13230,HP edits" When this command executes, it attempts to bind to the registry server identified in the \*L_s(sec)\*O variable. If that server cannot process the request or if the \*L_s(sec)\*O variable is not set, the command binds to either an available slave server or the master registry server, depending on the operation. Upon completion the command sets the \*L_b(sec)\*O convenience variable to the name of the registry server it bound to. ...\" ...\" .zZ "dec,13230,HP edits" .SH "ATTRIBUTES" .VL .LI "\*Lalias \*Vvalue\*O" Used with the \*Lcreate\*O and \*Lmodify\*O operations to specify whether the principal name is an alias. The value of this attribute is either \*Lyes\*O (the name is an alias) or \*Lno\*O (the name is not an alias). The default in \*Lno\*O. .PP Each principal can have only one primary name, but may have one or more alias names. All of a principal's alias names refer to the same principal, and therefore share the same UUID and uid. While aliases refer to the same principal, they are separate entries in the registry database. .LI "\*Luid \*Vvalue\*O" Used with the \*Lcreate\*O operation only for cell principals, to specify the integer to use as user identifier, known as a Unix ID, for the cell principals. No two principals can have the same uid. However, aliases can share one uid. .PP If you do not enter this option for a cell principal, the next sequential UNIX number is supplied as a default by the registry. For all principals other than cell principals, the uid is extracted from information embedded in the principal's UUID and cannot be specified here. If this attribute is not supplied when a principal is created, one is supplied automatically. .LI "\*Luuid \*Vhexadecimal number\*O" Used with the \*Lcreate\*O operation to specify the internal identifier, known as a UUID, for the principal. No two principals can have the same UUID, so do not use this option when creating more than one principal with a single \*Lcreate\*O command. .PP This option can also be used to adopt an orphaned UUID. Normally the UUID for a new principal is generated by the registry. In cases where data exists tagged with a UUID of a principal that has been deleted from the registry, this option can be used on the \*Lcreate\*O operation to specify the old UUID for a new principal. The UUID specified must be an orphan (a UUID for which no name exists in the registry). An error occurs if you specify a name or UUID that is already defined in the registry. .PP The \%\*L-alias\*O option cannot be used with this option. Both the \*L-fullname\*O and the \%\*L-quota\*O options can. .PP .LI "\*Lfullname \*Vstring\*O" Used with the \*Lcreate\*O and \*Lmodify\*O operations, to specify the full name of the principal. This name is used for information purposes only. It typically describes or expands a primary name to allow easy recognition by users. For example, a principal could have a primary name of \*Ljsbach\*O and a full name of \*LJohann S. Bach\*O. The value is a string. If the string contains spaces, you must surround them with quotes or braces for entry. This option defaults to a null string (that is, blank). .LI "\*Lquota {\*Vquota\*L | unlimited}" Used with the \*Lcreate\*O and \*Lmodify\*O operations to specify the principal's object creation quota. This is the total number of registry objects that can be created by the principal. It is either a non-negative number or the string \*Lunlimited\*O. A value of \*L0\*O prohibits the principal from creating any registry objects. Each time a principal creates a registry object, this value is decremented for that principal. .LE .PP See the \*VOSF DCE Administration Guide\*O for more information about principal attributes. ..\" See the \*(Ag for more information about principal attributes. .SH "OPERATIONS" .SS "principal catalog" .PP Returns a list of the names of all principals in the registry. The syntax is as follows: ...\" .zA "1.1: add cell_name" .sS \*Lprincipal catalog \*O[\*Vcell_name\*O] [\*L-simplename\*O] .sE ...\" .zZ "1.1: add cell_name" .PP \*LOptions\*O .VL .LI "\*L-simplename\*O" Returns a list of principal names in the registry without prepending the cell name. .LE .PP The \*Lcatalog\*O operation returns a list of the names of all principals in the local registry in lexical order. Use the \*Vcell_name\*O argument to return a list of principals in another cell's registry. By default, fully qualified names are returned in the form \*Vcellname\*L/\*Vprincipal_name\*O. Use the \%\*L-simplename\*O option to return them in the form \*Vprincipal_name\*O. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the \*L/.:/sec/principal\*O directory. .PP \*LExamples\*O .PP .oS dcecp> \*Lprincipal catalog\*C /.../small_cell.goodcompany.com/nobody /.../small_cell.goodcompany.com/root /.../small_cell.goodcompany.com/daemon /.../small_cell.goodcompany.com/sys /.../small_cell.goodcompany.com/bin /.../small_cell.goodcompany.com/uucp /.../small_cell.goodcompany.com/who /.../small_cell.goodcompany.com/mail /.../small_cell.goodcompany.com/tcb /.../small_cell.goodcompany.com/dce-ptgt /.../small_cell.goodcompany.com/dce-rgy /.../small_cell.goodcompany.com/cell_admin /.../small_cell.goodcompany.com/krbtgt/small_cell.goodcompany.com /.../small_cell.goodcompany.com/hosts/pmin17/self /.../small_cell.goodcompany.com/hosts/pmin17/cds-server /.../small_cell.goodcompany.com/hosts/pmin17/gda /.../small_cell.goodcompany.com/William_Ward /.../small_cell.goodcompany.com/John_Hunter dcecp> .oE .SS "principal create" .PP Creates a new principal in the registry database. The syntax is as follows: ...\" .zA "1.1: change to extended_attribute_list" .sS \*Lprincipal create \*Vprincipal_name_list\*O .nL ...\" .zA "def,13377,R1.2.2,clarify syntax" {\*L-attribute \*Vextended_rgy_attr_list\*O | .nL \*L-\*Vattribute value\*O} ...\" .zZ "def,13377,R1.2.2,clarify syntax" .sE .PP \*LOptions\*O .VL ...\" .zA "def,13377,R1.2.2, clarify syntax" .LI "\*L-\*Vattribute value\*O" As an alternative to using the \*L-attribute\*O option with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. You cannot use this option to specify ERAs; it is only for the standard attributes described in \*LATTRIBUTES\*O. .LI "\*L-attribute \*Vextended_rgy_attr_list\*O" Allows you to specify attributes, including ERAs, by using an attribute list rather than using the \*L-\*Vattribute value\*O option. The format of an attribute list is as follows: .iS {{\*Vextended_rgy_attr_list \*Vvalue\*O}...{\*Vextended_rgy_attr_list \*Vvalue\*O}} .iE ...\" .zZ "def,13377,R1.2.2, clarify syntax" .LE .PP The \*Lcreate\*O operation creates a new principal in the registry database. The \*Vprincipal_name_list\*O argument is a list of names of principals to be created. Options are used to specify the attributes of the newly created principal. All options are applied to all principals in the argument. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Li\*O (\*Linsert\*O) permission to the directory in which the principal is to be created. .PP \*LExamples\*O .PP The following command creates an alias \*Lpostmaster\*O for the principal with uid \*L1234\*O: .oS dcecp> \*Lprincipal create postmaster -uid 1234 -alias yes\*C dcecp> .oE .SS "principal delete" .PP Deletes principals from the registry. The syntax is as follows: .sS \*Lprincipal delete \*Vprincipal_name_list\*O .sE .PP The \*Ldelete\*O operation deletes principals from the registry. When a principal is deleted, the principal's account is deleted as well. The \*Vprincipal_name_list\*O argument is a list of names of principals to be deleted. Note that these names can be either a primary or alias names. In either case, an account associated with that name is deleted. If a named principal does not exist an error is generated. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Ld\*O (\*Ldelete\*O) permission to the directory in which the target principal exists. You must have \*Lr\*O (\*Lread\*O) and \*LD\*O (\*LDelete_object\*O) permissions on the principal to be deleted. .PP \*LExamples\*O .PP .oS dcecp> \*Lprincipal delete /.:/William_Smith\*C dcecp> .oE .SS "principal help" .PP Returns help information about the \*Lprincipal\*O object and its operations. The syntax is as follows: .sS \*Lprincipal help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lprincipal\*O object. .LE .PP Used without an argument or option, the \*Lprincipal help\*O command returns brief information about each \*Lprincipal\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lprincipal\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lprincipal help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lprincipal help\*C catalog Returns all the names of principals in the registry. create Creates a DCE principal. delete Deletes a principal from the registry. modify Changes the information about a principal. rename Renames the specified principal. show Returns the attributes of a principal. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "principal modify" .PP Changes attributes of principals. The syntax is as follows: ...\" .zA "1.1: change to extended_attribute_list" ...\" .zA "1.1: add -types" .sS ...\" .zA "def,13377,R1.2.2,clarify syntax" \*Lprincipal modify \*Vprincipal_name_list\*O .nL {\*L-add \*Vextended_rgy_attr_list\*O | .nL \*L-remove \*Vextended_rgy_attr_list\*O [\*L-types\*O] | .nL \*L-change \*Vextended_rgy_attr_list\*O | .nL \*L-\*Vattribute value\*O} ...\" .zZ "def,13377,R1.2.2,clarify syntax" .sE ...\" .zZ "1.1: add -types" ...\" .zZ "1.1: change to extended_attribute_list" .PP \*LOptions\*O .VL ...\" .zA "def,13377,R1.2.2,clarify syntax" .LI "\*L-\*Vattribute value\*O" As an alternative to using options with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. You cannot use this option to specify ERAs; it is only for standard group attributes described in \*LATTRIBUTES\*O. .LI "\*L-add\*O \*Vextended_rgy_attr_list\*O" Allows you to modify attributes, including ERAs, by using an attribute list rather than using individual attribute options. The format of an attribute list is as follows: .iS {{\*Vextended_rgy_attr_list \*Vvalue\*O}...{\*Vextended_rgy_attr_list \*Vvalue\*O}} .iE .PP .LI "\*L-change \*Vextended_rgy_attr_list\*O" Allows you to modify attributes, including ERAs, by using an attribute list rather than using individual attribute options. See the \*L-add\*O option for the attribute list format. .LI "\*L-remove\*O \*Vextended_rgy_attr_list\*O" Allows you to modify attributes, including ERAs, by using an attribute list rather than using individual attribute options such as \%\*L-alias\*O, \%\*L-fullname\*O, and so on. See the \*L-add\*O option for the attribute list format. .PP Without the \%\*L-types\*O option, \*L-remove\*O deletes individual attribute instances attached to the group. In this case, \*Vextended_rgy_attr_list\*O is a list of attribute-value pairs. With the \%\*L-types\*O option, \*L-remove\*O deletes attribute types (and all instances of that type) attached to the group. In this case, \*Vextended_rgy_attr_list\*O is a list of attribute types. .LI "\*L-types\*O" Used with the \%\*L-remove\*O option to remove attribute types (and all instances of that type) attached to the group. .LE See the \*VOSF DCE Administration Guide\*O for more information about ERAs. ...\" See the \*(Ag for more information about ERAs. ...\" .zZ "1.1, add -types" ...\" .zZ "1.1, change to extended_registry_attribute_list" ...\" .zZ "def,13377,R1.2.2,clarify syntax" .LE .PP The \*Lmodify\*O operation changes attributes of principals. The \*Vprincipal_name_list\*O argument is a list of names of principals to be operated on. All modifications are applied to all principals named in the argument. Principals are modified in the order they are listed and all modifications to an individual principal are atomic. Modifications to multiple principals are not atomic. A failure for any one principal in a list causes an error to be generated and the rest of the operation to be aborted. This operation returns an empty string on success. .PP The \%\*L-change\*O option can be used to modify the value of any of the attributes except for \*Luid\*O and \*Luuid\*O. The value of the \%\*L-change\*O option is an attribute list describing the new values .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O), \*Lf\*O (\*Lfull name\*O), \*Lm\*O (\*Lmgmt_info\*O), and \*Lu\*O (\*Luser_info\*O) permissions to the principal to be modified. .PP \*LExamples\*O .PP .oS dcecp> \*Lprincipal modify /.:/joe -fullname "Joe Long"\*C dcecp> \*Lprincipal show /.:/joe\*C {fullname {Joe Long}} {uid 30014} {uuid 0000753e-f51f-2e0e-b000-0000c08adf56} {alias no} {quota unlimited} dcecp> dcecp> \*Lprincipal modify joe -add {test_era 101}\*C dcecp> dcecp> \*Lprincipal show joe\*C {fullname {Joe Long}} {uid 30014} {uuid 0000753e-f51f-2e0e-b000-0000c08adf56} {alias no} {quota unlimited} {test_era 101} dcecp> .oE .SS "principal operations" .PP Returns a list of the operations supported by the \*Lprincipal\*O object. The syntax is as follows: .sS \*Lprincipal operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lprincipal operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lprincipal operations\*C catalog create delete modify rename show help operations dcecp> .oE .SS "principal rename" .P This operation changes the name of a specified principal. The syntax is as follows: .sS \*Lprincipal rename \*Vprincipal_name\*L -to \*Vnew_principal_name\*L .sE .PP \*LOptions\*O .VL .LI "\*L-to \*Vnew_principal_name\*O" Specifies the new name of the principal. See \*LARGUMENTS\*O for a principal's of principal names. .LE .PP The \*Lrename\*O operation changes the name of a specified principal. The argument is a single name of a principal to be renamed. The required \%\*L-to\*O option specifies the new name, which cannot be a list. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) and \*Lf\*O (\*Lfull name\*O) permission to the registry object for the specified principal. .PP \*LExamples\*O .PP .oS dcecp> \*Lacl show /.:/sec/principal/bob\*C {unauthenticated r-------g} {user_obj r---f--ug} {user cell_admin rcDnfmaug} {group acct-admin rcDnfmaug} {other_obj r-------g} {any_other r--------} dcecp> dcecp> \*Lprincipal rename K_Doe -to K_Smith\*C dcecp> dcecp> \*Lprincipal list K_Doe\*C \*CError: Registry object not found\*O dcecp> .oE .SS "principal show" .P Shows registry information for the specified principals. The syntax is as follows: .sS ...\" .zA "def,13377,R1.2.2,clarify syntax" \*Lprincipal show \*Vprincipal_name_list\*O [\*L-all\*O | \*L-xattrs\*O] ...\" .zZ "def,13377,R1.2.2,clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-xattrs\*O" Returns only the ERAs of the principal, with no other attributes. .LI "\*L-all\*O" Return the attributes followed by the ERAs. .LE .PP The \*Lshow\*O operation returns an attribute list describing the specified principals. The \*Vprincipal_name_list\*O argument is a list of names of principals to be operated on. If more than one principal is given, the attributes are concatenate and a blank line inserted between principals. There is one attribute in addition to \*Lfullname\*O, \*Luid\*O, \*Luuid\*O, \*Lalias\*O and \*Lquota\*O. It is called \*Lgroups\*O and its value is a list of the group names that the principal is a member of. Attributes are returned in the following order: \*Lfullname\*O, \*Luid\*O, \*Luuid\*O, \*Lalias\*O and \*Lquota\*O, followed by \*Lgroups\*O. .PP If called with the \%\*L-xattrs\*O option, then ERAs are returned instead of the above attributes. If called with \*L-all\*O, both are returned. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the specified principals. .PP \*LExamples\*O .PP .oS dcecp> \*Lprincipal show /.:/joe\*C {fullname {Joe Long}} {uid 30014} {uuid 0000753e-f51f-2e0e-b000-0000c08adf56} {alias no} {quota unlimited} {groups none gumby} dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad 1 \*Ldcecp(1m)\*O, \*Ldcecp_account(1m)\*O, \*Ldcecp_group(1m)\*O, \*Ldcecp_organization(1m)\*O, \*Ldcecp_registry(1m)\*O, \*Ldcecp_xattrschema(1m)\*O. .ad b ...\" .ad l ...\" \*Laccount(1m)\*O, ...\" \*Ldcecp(1m)\*O, ...\" \*Lgroup(1m)\*O, ...\" \*Lorganization(1m)\*O, ...\" \*Lxattrschema(1m)\*O, ...\" \*Lregistry(1m)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH registry 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lregistry\*O" .iX "registry" "administering" .SH NAME .PP \*Lregistry\*O - A \*Ldcecp\*O object that manages a registry in the DCE Security Service .SH "SYNOPSIS" .sS ...\" .zA "1.1: added -master" \*Lregistry catalog \*O[\*Vregistry_replica_name\*O] [\*L-master\*O] ...\" .zZ "1.1: added -master" .PP ...\" .zA "1.2.1" \*Lregistry checkpoint \*Vregistry_replica_name .nL ...\" .zA "Def,13377,R1.2.2,clarify syntax" \*O[\*L-at \*Vhh:mm\*O | \*L-cpi \*O{\*Vnum\*O | \*Vnum\*Lm\*O | \*Vnum\*Lh\*O}] [\*L-now\*O] ...\" .zZ "1.2.1" .PP ...\" .zA "1.2.1: add options" \*Lregistry connect \*Vcell_name .nL \*L-group \*Vlocal_group_name\*L -org \*Vlocal_org_name\*L -mypwd \*Vlocal_password .nL \*L-fgroup \*Vforeign_group_name\*L -forg \*Vforeign_org_name .nL \*L-facct \*Vforeign_account_name\*L -facctpwd \*Vforeign_account_password .nL \*O[\*L-expdate\*O] [\*L-acctvalid\*O] [\*L-facctvalid\*O] ...\" .zZ "1.2.1: add options" .PP ...\" .zA "1.1: delete -only option" \*Lregistry delete \*Vregistry_replica_name\*O [\*L-force\*O] ...\" .zZ "1.1: delete -only option" .nL ...\" .zA "1.1 warranty patch" \*Lregistry designate \*Vregistry_replica_name .nL \*O[\*L-slave\*O | \*L-master\*O [\*L-force\*O]] .PP \*Lregistry destroy \*Vregistry_replica_name\*L ...\" .zZ "1.1 warranty patch" .PP \*Lregistry disable \*O[\*Vregistry_replica_name\*O] .PP \*Lregistry dump\*O [\*Vregistry_replica_name\*O] .PP \*Lregistry enable \*O[\*Vregistry_replica_name\*O] .PP \*Lregistry help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lregistry modify \*O[\*Vregistry_replica_name\*O] .nL {\*L-change \*Vattribute_list\*O | \*L-\*Vattribute value\*O | \*L-key\*O} .nL .PP \*Lregistry operations\*O .PP ...\" .zA "1.2.1: add -address option" \*Lregistry replace \*Vregistry_replica_name \*L-address \*Vnew_string_binding\*O ...\" .zZ "1.2.1: add -address option" .PP \*Lregistry show \*O[\*Vregistry_replica_name\*O] .nL ...\" .zA "def,13377,R1.2.2,add verbose" [\*L-attributes\*O | \*L-policies\*O | \*L-replica\*O | \*L-master\*O | \*L-verbose\*O] ...\" .zZ "def,13377,R1.2.2,add verbose" ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .PP \*Lregistry stop \*Vregistry_replica_name\*O .PP ...\" ...\" .zA "1.1 warranty patch" \*Lregistry synchronize \*Vregistry_replica_name\*O ...\" ...\" .zZ "1.1 warranty patch" .PP \*Lregistry verify\*O [\*Vregistry_replica_name\*O \*L-verbose\*O] .sE .SH "ARGUMENTS" .VL .LI "\*Vcell_name\*O The name of a cell to contact when processing the \*Lconnect\*O operation. The name must be a fully qualified cell name, such as \*L/.:\*O or \*L/.../\*Vcell_name\*O. .LI "\*Voperation\*O" The name of the \*Lregistry\*O operation for which to display help information. .LI "\*Vregistry_replica_name\*O The name of one registry replica to act on. The replica can be a master or a slave replica. The argument, which overrides a value in the \*L_s(sec)\*O convenience variable, can be one of the following: .ML .LI A specific cell name (or \*L/.:\*O for the local cell) to bind to any replica in the named cell. .LI The global name of a replica to bind to that specific replica in that specific cell. .LI The name of a replica as it appears on the replica list to bind to that replica in the local cell. .LI A string binding to a specific replica\(emfor example, {\*Lncadg_ip_udp 15.22.144.163\*O}. This form is used primarily for debugging or if the Cell Directory Service (CDS) is not available. .LE .PP For those operations for which \*Vregistry_replica_name\*O is optional, if no argument is given, the value of \*L_s(sec)\*O is used. If the variable is not set, the default argument of \*L/.:\*O is assumed. .LE .SH "DESCRIPTION" .PP The \*Lregistry\*O object represents a DCE Security Service registry. The registry is a replicated database: each instance of a registry server, \*Lsecd\*O, maintains a working copy of the database in virtual memory and on disk. One server, called the master replica, accepts updates and handles the subsequent propagation of changes to all other replicas. All other replicas are slave replicas, which accept only queries. Each cell has one master replica and may have numerous slave replicas. .PP Note that the \*Lregistry\*O command cannot add, delete, or modify information in the registry database, such as names and accounts. Use the appropriate \*Laccount\*O, \*Lprincipal\*O, \*Lgroup\*O or \*Lorganization\*O command to modify registry database entries. .PP Two access control lists (ACLs) control access to \*Lregistry\*O operations. For operations dealing with replication, the \*Lreplist\*O object's ACL (usually \*L/.:/sec/replist\*O) controls access. For those that deal with registry attributes and policies, the \*Lpolicy\*O object's ACL (usually \*L/.:/sec/policy\*O ) controls access. .PP ...\" .zA "dec,13377,added paragraph" When this command executes, it attempts to bind to the registry server identified in the \*L_s(sec)\*O variable. If that server cannot process the request or if the \*L_s(sec)\*O variable is not set, the command binds to either an available slave server or the master registry server, depending on the operation. Upon completion the command sets the \*L_b(sec)\*O convenience variable to the name of the registry server to which it bound. ...\" .zZ "dec,13377,added paragraph" .SH "ATTRIBUTES" .PP The \*Lregistry\*O object supports the following kinds of attributes: ...\" .zA "def,13377,R1.2.1,Clarified text" .ML .LI \*LRegistry attributes\*O\(emThese modifiable attributes apply to principals, groups, organizations, and accounts. The initial values for some of these attributes must be specified when the master Security Server is configured. .LI \*LRegistrywide policy attributes\*O\(emThese modifiable attributes apply to organizations and accounts. The registrywide organization and account policy overrides the policy set for individual accounts only if the registrywide policy is more restrictive.- .LI \*LSynchronization attributes\*O\(emThese read-only attributes are maintained by each replica about itself. They cannot be directly modified. These attributes have no default value, but are computed when the replica is configured. .LI \*LReplica-specific attributes\*O\(emThese read-only attributes are kept by the master replica for each slave replica. They cannot be modified directly. These attributes have no default value, but are computed or assigned when the replica is configured. .LE ...\" .zZ "def,13377,R1.2.1,Clarified text" .PP .SS "Registry Attributes" .VL .LI "\*Ldeftktlife\*V relative_time\*O" The default lifetime for tickets issued to principals in this cell's registry. Specify the time by using the Distributed Time Service (DTS) relative time format (\*L[-]\*VDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*O). The default is: .iS \*L+0-10:00:00.000\*O .iE .LI "\*Lhidepwd {yes | no}\*O" Determines whether encrypted passwords are displayed or not. If this attribute is set to \*Lyes\*O, an asterisk is displayed in place of the encrypted password in command output and files where passwords are displayed. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lyes\*O. .LI "\*Lmaxuid\*V integer\*O" The highest number that can be supplied as a user identifier (\*Luid\*O) when principals are created. This maximum applies to both the system-generated and user-entered \*Luid\*Os. The value is an integer; the initial value depends on the configuration of your system. .LI "\*Lmingid\*V integer\*O" The starting point for group identifiers (\*Lgid\*Os) automatically generated by the security service when a group is created. You can explicitly enter a lower \*Lgid\*O than this number; it applies only to automatically generated numbers. The value is an integer; the initial value depends on the configuration of your system. .LI "\*Lminorgid\*V integer\*O" The starting point for organization identifiers (\*Lorgid\*Os) automatically generated by the security service when an organization is created. You can explicitly enter a lower \*Lorgid\*O than this number; it applies only to automatically generated numbers. The value is an integer; the initial value depends on the configuration of your system. .LI "\*Lmintktlife\*V relative_time\*O" The minimum amount of time before the principal's ticket must be renewed. The value is an integer. This renewal is performed automatically with no intervention on the part of the user. The shorter this time is, the greater the security of the system. However, extremely frequent renewal can degrade system performance. Both system performance and the level of security required by the cell should be taken into consideration when selecting the value of this attribute. This is a registrywide value only, it cannot be set for individual accounts. The default is: .iS +0-00:05:00.000 .iE .LI "\*Lminuid\*V integer\*O" The starting point for \*Luid\*Os automatically generated by the security service when a principal is created. You can explicitly enter a lower \*Luid\*O than this number; it applies only to automatically generated numbers. The value is an integer; the initial value depends on the configuration of your system. ...\" .zA "def,13377,R1.2.1,moved from synch attrs" .LI "\*Lversion\*O" The version of the security server software. The initial value depends on the configuration of your system. ...\" .zZ "def,13377,R1.2.1,moved from synch attrs" .LE .PP .SS "\*LRegistrywide Policy Attributes\*O" ...\" .zA "def,13377,R1.2.1,added defaults" .VL .LI "\*Lacctlife {\*Vrelative_time \*L| unlimited}\*O" This registrywide organization policy defines the lifespan of accounts. Specify the time by using the DTS relative time format (\*L[-]\*VDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*O) or the string \*Lunlimited\*O to define an unlimited lifespan for accounts. The default is \*Lunlimited\*O. .LI "\*Lmaxtktlife \*Vrelative_time\*O" This registrywide account policy defines the maximum amount of time that a ticket can be valid. Specify the time by using the DTS relative time format (\*L[-]\*VDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*O). When a client requests a ticket to a server, the lifetime granted to the ticket takes into account the \*Lmaxtktlife\*O set for both the server and the client. In other words, the lifetime cannot exceed the shorter of the server's or client's \*Lmaxtktlife\*O. If you do not specify a \*Lmaxtktlife\*O for an account, the \*Lmaxtktlife\*O defined as registry authorization policy is used. The default is: .iS +1-00:00:00.000 .iE .LI "\*Lmaxtktrenew \*Vrelative_time\*O" This registrywide account policy defines the amount of time before a principal's ticket-granting ticket expires and that principal must log in again to the system to reauthenticate and obtain another ticket-granting ticket. Specify the time by using the DTS relative time format (\*L[-]\*VDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*O). The lifetime of the principal's service tickets can never exceed the lifetime of the principal's ticket-granting ticket. The shorter you make this, the greater the security of the system. However, since principals must log in again to renew their ticket-granting ticket, the time needs to take into consideration user convenience and the level of security required. If you do not specify this for an account, the \*Lmaxtktrenew\*O lifetime defined as registry authorization policy is used. The default is: .iS +28-00:00:00.000\*O .iE .LI "\*Lpwdalpha {yes | no} \*O" This registrywide organization policy defines whether or not passwords can consist entirely of alphanumeric characters. Its value is either \*Lyes\*O or \*Lno\*O. The default is \*Lyes\*O. .LI "\*Lpwdexpdate \*O{\*VISO-timestamp\*O | \*Lnone\*O}" This registrywide organization policy defines a date on which a password will expire. The date is entered as an internationalized date string or the string \*Lnone\*O, in which case there is no expiration date for the password. The default is \*Lnone\*O. .LI "\*Lpwdlife {\*Vrelative_time\*L| unlimited}\*O" This registrywide organization policy defines the lifespan of passwords. Specify the time by using the DTS relative time format (\*L[-]\*VDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*O) or the string \*Lunlimited\*O. The default is \*Lunlimited\*O. .LI "\*Lpwdminlen \*Vinteger\*O" This registrywide organization policy defines the minimum number of characters in a password. Its value is a positive integer or the integer \*L0\*O which means there is no minimum length. The default is \*L0\*O. .LI "\*Lpwdspaces \*O{\*Lyes \*O| \*Lno\*O}" This registrywide organization policy defines whether or not passwords can consist entirely of spaces. Its value is either \*Lyes\*O or \*Lno\*O. The default is \*Lno\*O. .LE ...\" .zZ "def,13377,R1.2.1,added defaults" .PP .SS "Synchronization Attributes" .VL .LI "\*Lname\*O" The name of the replica. It is in the form of a fully qualified CDS name. .LI "\*Ltype\*O Indicates if the replica is a \*Lmaster\*O or a \*Lslave\*O. .LI "\*Lcell\*O The name of the cell that the replica is in. It is a fully qualified cellname. .LI "\*Luuid\*O" The Universal Unique Identifier (UUID) of the replica. .LI "\*Lstatus\*O" The state of the replica. One of the following: .VL .LI "\*Lbecomingmaster\*O" The replica is in the process of becoming a master. .LI "\*Lbecomingslave\*O" The replica is a master in the process of becoming a slave. .LI "\*Lchangingkey\*O" The replica is in the process of having its master key changed. .LI "\*Lclosed\*O" The replica is in the process of stopping. .LI "\*Lcopyingdb\*O" The replica is in the process of initializing (copying its database to) another replica. .LI "\*Ldeleted\*O" The replica is in the process of deleting itself. .LI "\*Ldisabled\*O" The replica is unavailable for updates but will accept queries. ...\" .zA "def,13377,R1.2.1,deleted sentence about sec_admin" ...\" .zZ "def,13377,R1.2.1,deleted sentence about sec_admin" .LI "\*Ldupmaster\*O" Two masters have been found in the cell, and the replica is a duplicate of the real master. .LI "\*Lenabled\*O" The replica is available for use. ...\" .zA "def,13377,R1.2.1,deleted sentence about sec_admin" ...\" .zZ "def,13377,R1.2.1,deleted sentence about sec_admin" .LI "\*Linitializing\*O" The replica is in the process of being initialized by the master replica or another up-to-date replica. .LI "\*Lsavingdb\*O" The replica is in the process of saving its database to disk. .LI "\*Lunavailable\*O" The replica cannot be reached. .LI "\*Luninitialized\*O" The database is a stub database that has not been initialized by the master replica or another up-to-date replica. .LI "\*Lunknown\*O" The replica is not known to the master. .LE .LI "\*Llastupdtime\*O" The localized date and time that the master received the last replica's last update. .LI "\*Llastupdseq\*O" The sequence number of the last update the replica received. A sequence number consists of two 32-bit integers separated by a dot (\*Vhigh.low\*O). The high integer increments when the low integer wraps. An example of this attribute is {\*Llastupdseq 0.178\*O}. .LI "\*Laddresses\*O" A list of the network addresses of the replica. There can be more than one for connectionless and connection-oriented protocols. .LI "\*Lmasteraddrs\*O" The network address of the master replica. This is what the replica believes; it is not necessarily correct. There can be more than one for connectionless and connection-oriented protocols for example. .LI "\*Lmasterseqnum\*O" The master sequence number, which is the sequence number of the event that made the replica the master. This is what the replica believes; it is not necessarily correct. A sequence number consists of two 32-bit integers separated by a dot (\*Vhigh.low\*O). The high integer increments when the low integer wraps. An example of this attribute is {\*Lmasterseqnum 0.100\*O}. .LI "\*Lmasteruuid\*O" ...\" .zA "1.1, CR13070" The UUID of the master replica. This is what the replica believes; it is not necessarily correct. The value is a UUID. ...\" .zZ "1.1, CR13070" ...\" .zA "1.1: added -supportedversions" .LI "\*Lsupportedversions\*O" DCE registry version supported by the security service. Possible values at DCE version 1.1 are \*Lsecd.dce.1.0.2\*O (for DCE version 1.0.2 and DCE version 1.0.3) and \*Lsecd.dce.1.1\*O. Both versions may be supported (that is by a DCE version 1.1 security server running in a cell with DCE version 1.0.3 replicas). ...\" .zZ "1.1: added -supportedversions" .LI "\*Lupdseqqueue\*O" A list of two update sequence numbers that are still in the propagation queue and have yet to be propagated. The first number is the base propagation sequence number (the last number known to have been received by all replicas). The second number is the sequence number of the last update made on the master. This attribute is only present in the master replica. The sequence numbers consist of two 32-bit integers separated by a dot (\*Vhigh.low\*O). The high integer increments when the low integer wraps. An example of this attribute is {\*Lupdseqqueue {0.100 0.178\*O}}. .LE .PP .SS "Replica-Specific Attributes" .VL .LI "\*Lname\*O" The name of the replica. It is in the form of a fully qualified CDS name. ...\" .zA "1.1: added" .LI "\*Luuid\*O" The UUID of the replica. ...\" .zZ "1.1: added" .LI "\*Ltype\*O" Indicates if the replica is a \*Lmaster\*O or a \*Lslave\*O. ...\" .zA "1.1: added" .LI "\*Laddresses\*O" A list of the network addresses of the replica. There can be more than one for connectionless and connection-oriented protocols. ...\" .zZ "1.1: added" .LI "\*Lpropstatus\*O" The status of the propagation. Possible values are as follows: .VL .LI "\*Ldelete\*V\*O " The replica is marked for deletion. .LI "\*Linitmarked\*V\*O " The replica is marked for initialization. .LI "\*Liniting\*V\*O " The replica is in the process of initialization, that is, getting an up-to-date copy of the registry. ...\" XXX .LI "\*Lunavailable\*O" ...\" XXX The replica cannot be reached. .LI "\*Lupdate\*V\*O " The replica is ready to receive propagation updates. .LE .LI "\*Llastupdtime\*V\*O " The localized time of the last update sent to the replica. This information is meaningful only if \*Lpropstatus\*O is \*Lupdate\*O. .LI "\*Llastupdseqsent\*V\*O " The sequence number of the last update sent to this replica. A sequence number consists of two 32-bit integers separated by a dot (\*Vhigh.low\*O). The high integer increments when the low integer wraps. An example of this attribute is: .iS {lastupdseqsent 0.175} .iE This information is meaningful only if \*Lpropstatus\*O is \*Lupdate\*O. .LI "\*Lnumupdtogo\*V\*O " The number of outstanding updates. The value is an integer. This information is meaningful only if \*Lpropstatus\*O is \*Lupdate\*O. ...\" .zA "1.1: added" .LI "\*Lcommstate\*O" The state of the last communication with the replica. ...\" .zZ "1.1: added" .LI "\*Llastcommstatus\*O" The status message of the last communication with the replica. .LE See the \*VOSF DCE Administration Guide\*O for more information about attributes, policies, and synchronizations. ...\" See the \*(Ag for more information about attributes, policies, and synchronizations. .PP .SH "OPERATIONS" .SS "registry catalog" ...\" .zA "1.1: added -master" .PP Returns a list of the names of the security servers running in the cell. The syntax is as follows: .sS \*Lregistry catalog \*O[\*Vregistry_replica_name\*O] [\*L-master\*O] .sE .PP \*LOption\*O .VL .LI "\*L-master\*O" Returns only the master security server name. .LE The \*Lcatalog\*O operation returns a list of the names of the security servers (that is, each copy of the registry) running in the cell. This is also known as the replica list. The order of elements returned is arbitrary. The optional \*Vregistry_replica_name\*O argument can specify the name of one other cell or a single string binding. If you specify the \*L-master\*O option, the operation returns only the name of the master. .PP This operation sets the \*L_b(sec)\*O variable to the name of the replica to which it binds. ...\" .zZ "1.1: added -master" .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lregistry catalog\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lregistry catalog\*C /.../dcecp.cell.osf.org/subsys/dce/sec/snow /.../dcecp.cell.osf.org/subsys/dce/sec/ice dcecp> .oE .PP ...\" ...\" ...\" .zA "1.2.1: new operation" .SS "registry checkpoint" Specifies when registry checkpoints should be performed. The syntax is as follows: .sS \*Lregistry checkpoint \*Vregistry_replica_name .nL ...\" .zA "Def,13377,R1.2.2,clarify syntax" \*O [\*L-at \*Vhh:mm\*O | \*L-cpi\*O {\*Vnum\*O | \*Vnum\*Lm\*O | \*Vnum\*Lh\*O}] [\*L-now\*O] ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-at \*Vhh:mm\*O" Specifies the specific time of the day to perform the checkpoint. \*Vhh:mm\*O specifies the hours and minutes of the day (in UTC time) to perform the checkpoint. .PP .LI "\*L-cpi {\*Vnum\*O | \*Vnum\*Lm\*O | \*Vnum\*Lh\*L}\*O" Specifies an interval at which checkpoints will be performed. .LI "\*L-now\*O Specifies an immediate checkpoint. This is the default. .LE .PP The \*Lcheckpoint\*O operation lets you set the times when the registry database should be saved to disk (checkpointed). You must supply the name of a replica for the operation to bind to. .PP If you use the \%\*L-at\*O option, the checkpoint is performed at the specified time. The time is in UTC format. For example, to specify 3:30 P.M., the entry is 15:30. The checkpoint interval then reverts to the default or to the interval specified by the \%\*L-cpi\*O option. .PP If you use the \%\*L-cpi\*O option, the checkpoint is performed at the interval you specify continuously until you specify another interval. This option takes an argument that specifies the interval time as seconds, minutes, or hours: .ML .LI To specify seconds, supply only a number. For example, \*L-cpi 101\*O specifies an interval of 101 seconds. .LI To specify minutes enter the number and \*Lm\*O. For example, \*L-cpi 101m\*O specifies an interval of 101 minutes. .LI To specify hours, enter the number and \*Lh\*O. For example, \*L-cpi 101h\*O specifies an interval of 101 hours. .LE .PP If you use the \%\*L-now\*O option, a checkpoint is performed immediately. The checkpoint interval then reverts to the default or to the interval specified by the \%\*L-cpi\*O option. This operation returns an empty string on success and sets the \*L_b(sec)\*O variable to the replica to which it binds. .LE .PP \*LPrivileges Required\*O .PP You must have \*Lad\*O (\*Lauth_info\*O, \*Ldelete\*O) permission to the \*Lreplist\*O object. .PP \*LExamples\*O .PP .oS dcecp> \*Lregistry checkpoint /.../gumby_cell/subsys/dce/sec/oddball -at 05:30\*C dcecp> .oE ...\" .zZ "1.2.1: new operation" ...\" ...\" .SS "registry connect" .PP Connects the local (that is, default) cell of the local host to the foreign cell specified by the argument. The syntax is as follows: .sS \*Lregistry connect \*Vcell_name .nL ...\" .zA "Def,13377,R1.2.2,clarify syntax" ...\" .zA "1.2.1: new options" \*L-group \*Vlocal_group_name\*L -org \*Vlocal_org_name\*L -mypwd \*Vlocal_password .nL \*L-fgroup \*Vforeign_group_name\*L -forg \*Vforeign_org_name .nL \*L-facct \*Vforeign_account_name\*L -facctpwd \*Vforeign_account_password .nL \*O[\*L-expdate\*O] [ \*L-acctvalid\*O] [\*L-facctvalid\*O] ...\" .zZ "Def,13377,R1.2.2,clarify syntax" ...\" .zZ "1.2.1: new options" .sE .PP \*LOptions\*O .VL .LI "\*L-group \*Vlocal_group_name\*O" Specifies the group for the local account. .LI "\*L-org \*Vlocal_org_name\*O" Specifies the organization for the local account. .LI "\*L-mypwd \*Vlocal_password\*O" Specifies the password for the local account. .LI "\*L-fgroup \*Vforeign_group_name\*O" Specifies the group for the foreign account. .LI "\*L-forg \*Vforeign_org_name\*O" Specifies the organization for the foreign account. .LI "\*L-facct \*Vforeign_account_name\*O" Specifies the name for the foreign account. .LI "\*L-facctpwd \*Vforeign_account_password\*O" Specifies the password for the foreign account. .LI "\*L-expdate \*Vaccount_expiration_date\*O Sets an expiration date for both local and foreign accounts. ...\" .zZ "Def,13377,R1.2.2,clarify syntax" ...\" .zA "1.2.1: new options" .LI "\*L-acctvalid\*O" Marks the local account as a valid account. A valid local account allows users from the foreign cell to login to nodes in the local cell. The default is invalid. .LI "\*L-facctvalid\*O" Marks the foreign account as a valid account. A valid foreign account allows users from the local cell to login to nodes in the foreign cell. The default is invalid. ...\" .zZ "1.2.1: new options" .LE .PP The \*Lconnect\*O operation creates an account in the local cell for the specified foreign cell and also creates an account in the foreign cell for the local cell. Both accounts have the same key. The argument must be the fully qualified name of a single cell. It cannot be a list or a string binding. .PP The \%\*L-group\*O, \%\*L-org\*O, \%\*L-mypwd\*O, and \*L-acctvalid\*O options supply the account information for the local cell. The \%\*L-fgroup\*O, \%\*L-forg\*O, \%\*L-facct\*O, \%\*L-facctpwd\*O, and \*L-facctvalid\*O options supply the account information for the foreign cell. .PP This operation creates the group and organization specified as the values of the relevant options, if necessary, and puts the relevant principal in them, if necessary. .PP If the operation fails, it removes any organization and/or group that it has created and it also removes the relevant principals. To protect the password being entered, the \*Lregistry connect\*O command can be entered only from within \*Ldcecp\*O. You cannot enter it from the operating system prompt by using \*Ldcecp\*O with the \%\*L-c\*O option. .PP ...\" ...\" .zA "1.2.1: new options" If you do not use the \*L-acctvalid\*O and \%\*L-facctvalid\*O options, you must mark the accounts as valid (using the \*Ldcecp account\*O command) before intercell access is allowed. This operation returns an empty string on success. ...\" .zZ "1.2.1: new options" ...\" .PP \*LPrivileges Required\*O .PP You must have \*La\*O (\*Lauth_info\*O) permission to the \*Lreplist\*O object. .PP \*LExamples\*O .PP .oS dcecp> \*Lgetcellname\*C /.../my_cell.com dcecp> dcecp> \*Lregistry connect /.../your_cell.com -group none -org none \\\*C > \*L-mypwd -dce- -fgroup none -forg none -facct cell_admin \\\*C > \*L-facctpwd -dce- \*C dcecp> .oE .PP ...\" .SS "registry delete" .PP Deletes a registry replica from the cell. The syntax is as follows: ...\" .zA "1.1: delete -only option" .sS ...\" .zA "Def,13377,R1.2.2,clarify syntax" \*Lregistry delete \*Vregistry_replica_name\*O [\*L-force\*O] ...\" .zZ "Def,13377,R1.2.2,clarify syntax" ...\" | [\*L-only\*O]} .sE .PP \*LOption\*O .VL .LI "\*L-force\*O" Used when the target replica is not available, the \%\*L-force\*O option removes the replica name from the master replica's replica list and propagates the deletion to other replicas that remain on the list. .LE .PP The \*Lregistry delete\*O operation, when called with no options, performs an orderly deletion of a security replica specified as the \*Vregistry_replica_name\*O argument. To do so, the operation binds binds to the master replica. The master replica then performs the following tasks: .AL .LI Marks the specified replica as deleted .LI Propagates this deletion to the other replicas on its replica list .LI Delivers the delete request to the specified replica .LI Removes the replica from its replica list .LE Note that the \*Ldcecp\*O command will return before the delete has completed because it simply tells the master to perform the delete procedure. .PP The \%\*L-force\*O option causes a more drastic deletion. It causes the master to first delete the specified replica from its replica list and then propagate the deletion to the replicas that remain on its list. Since this operation never communicates with the deleted replica, you should use \*L-force\*O only when the replica has died irrecoverably. If you use \*L-force\*O while the specified replica is still running, you should then use the \*Lregistry destroy\*O command to eliminate the deleted replica. .PP This operation returns an empty string on success and sets the \*L_b(sec)\*O variable to the master. .PP \*LPrivileges Required\*O .PP You must have \*Ld\*O (\*Ldelete\*O) permission to the \*Lreplist\*O object. .PP \*LExamples\*O .PP .oS dcecp> \*Lregistry delete /.:/subsys/dce/sec/\*Loddball\*C dcecp> .oE ...\" .zA "1.1 warranty patch" .SS "registry designate" .P Changes which replica is the master. The syntax is as follows: .sS \*Lregistry designate \*Vregistry_replica_name\*O .nL ...\" .zA "Def,13377,R1.2.2,clarify syntax" \*O[\*L-slave\*O | \*L-master \*O[\*L-force\*O]] ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-slave\*O" Makes the specified replica a slave. The \*Vregistry_replica_name\*O argument must identify the master replica. .LI "\*L-master\*O" Makes the specified replica the master. The \*Vregistry_replica_name\*O argument must identify a slave replica. .LI "\*L-force\*O" Forces \*Vregistry_replica_name\*O to become the master, even if other slave replicas are more up-to-date. Used only with the \%\*L-master\*O option. .LE .PP The preferred method of creating a new master is to use this command with no options in the form: .iS registry designate \*Vregistry_replica_name\*O .iE It changes the slave replica named in \*Vregistry_replica_name\*O to the master by performing an orderly transition. To do so, it binds to the current master and instructs the master to: .AL .LI Apply all updates to the replica named in \*Vregistry_replica_name\*O .LI Become a slave .LI Tell the replica named in \*Vregistry_replica_name\*O to become the master .LE .PP The \*L-slave\*O or \%\*L-master\*O options can also be used to change the master to a slave and a slave to a master. However, using these options is not recommended because updates can be lost. You should use them only if you must because the master replica is irrevocably damaged and is unable to perform the steps in the orderly transition. To use these options, enter the command as shown in the following list: .ML .LI To make the master a slave: .iS registry designate \*Vregistry_replica_name\*O \*L-slave\*O .iE \*Vregistry_replica_name\*O is the name of the replica to make a slave. .LI To make a slave the master: .iS registry designate \*Vregistry_replica_name\*O \*L-master\*O .iE \*Vregistry_replica_name\*O is the name of a slave to make a master. If a master exists, the command fails. Also, if there are more up-to-date slaves than the one specified by \*Vregistry_replica_name\*O, the command fails, unless you specify \*L-force\*O to override this default action. .LE .PP This operation returns the empty string on success and sets the \*L_b(sec)\*O variable as follows: .ML .LI If called with the \*L-force\*O or \%\*L-master\*O option, it sets \*L_b(sec)\*O to the replica to which it binds. .LI If called with no options, it sets \*L_b(sec)\*O to the master. .LE .PP \*LPrivileges Required\*O .PP You must have \*La\*O (\*Lauth_info\*O) permission to the \*Lreplist\*O object. .PP \*LExamples\*O .PP .oS dcecp> \*Lregistry designate /.../my_cell/subsys/dce/sec/oddball\*C dcecp> .oE .PP ...\" .SS "registry destroy" .PP Deletes a registry replica. The syntax is as follows: .sS \*Lregistry destroy \*Vregistry_replica_name\*L .sE .PP The \*Ldestroy\*O operation causes the replica named in \*Vregistry_replica_name\*O to delete its copy of the registry database and to stop running. .PP The preferred way to delete replicas is to use the \*Ldelete\*O operation. However, the \*Ldestroy\*O operation can be used if \*Ldelete\*O is unusable because the master is unreachable or the replica is not on the master's replica list. .PP This operation returns an empty string on success and sets the \*L_b(sec)\*O variable to the replica to which it binds. .PP \*LPrivileges Required\*O .PP You must have \*Ld\*O (\*Ldelete\*O) permission to the \*Lreplist\*O object. .PP \*LExamples\*O .PP .oS dcecp> \*Lregistry destroy /.:/subsys/dce/sec/oddball\*C dcecp> .oE ...\" .zZ "1.1 warranty patch" .SS "registry disable" ...\" .zA "1.1: added registry_replica_name" .PP Disables the master registry for updates. The syntax is as follows: .sS \*Lregistry disable\*O [\*Vregistry_replica_name\*O] .sE .PP The \*Ldisable \*O operation disables the master registry for updates. Generally use this mode for maintenance purposes. The \*Vregistry_replica_name\*O argument is a single name of a master registry to be disabled. If no argument is given, the operation uses the name in the \*L_s(sec)\*O convenience variable. If the \*L_s(sec)\*O variable is not set, the operation defaults to the master in the local cell. .PP This operation returns an empty string on success and sets \*L_b(sec)\*O to the name of the replica to which it binds. ...\" .zZ "1.1: added registry_replica_name" .PP \*LPrivileges Required\*O .PP You must have \*La\*O (\*Lauth_info\*O) permission to the \*Lreplist\*O object. .PP \*LExamples\*O .PP .oS dcecp> \*Lregistry disable /.../my_cell.goodcompany.com/subsys/dce/sec/snow\*C dcecp> .oE .SS "registry dump" ...\" .zA "1.1: added registry_replica_name" .PP Returns the replica information for each replica in the cell. The syntax is as follows: .sS \*Lregistry dump\*O [\*Vregistry_replica_name\*O] .sE .PP The \*Ldump\*O operation returns the replica information for each replica in the cell. Replicas are displayed with a blank line between them. .PP The \*Lregistry dump\*O command is the same as the following script: .iS foreach i [registry catalog] { lappend r [registry show $i -replica] append r } return r .iE .PP This operation sets the \*L_b(sec)\*O variable to the last replica listed in the display. .PP ...\" .zA "1.1: added registry_replica_name" .PP \*LPrivileges Required\*O .PP You must have \*La\*O (\*Lauth_info\*O) permission to the \*Lreplist\*O object. .PP \*LExamples\*O .PP .oS dcecp> \*Lregistry dump\*C {name /.../dcecp.cell.osf.org/subsys/dce/sec/snow} {type master} {cell /.../dcecp.cell.osf.org} {uuid a1248a5e-e1e6-11cd-aa0c-0800092734a4} {status enabled} {lastupdtime 1994-10-13-14:44:48.000-04:00I-----} {lastupdseq 0.271} {addresses {ncacn_ip_tcp 130.105.5.121} {ncadg_ip_udp 130.105.5.121}} {masteraddrs {ncacn_ip_tcp 130.105.5.121} {ncadg_ip_udp 130.105.5.121}} {masterseqnum 0.100} {masteruuid a1248a5e-e1e6-11cd-aa0c-0800092734a4} {version secd.dce.1.1} {updseqqueue {0.204 0.271}} {name /.../dcecp.cell.osf.org/subsys/dce/sec/ice} {type slave} {cell /.../dcecp.cell.osf.org} {uuid c772f46a-e1ec-11cd-9a16-0000c0239a70} {status enabled} {lastupdtime 1994-10-13-14:44:48.000-04:00I-----} {lastupdseq 0.271} {addresses {ncacn_ip_tcp 130.105.5.45} {ncacn_ip_tcp 130.105.5.45} {ncadg_ip_udp 130.105.5.45}} {masteraddrs {ncacn_ip_tcp 130.105.5.121} {ncadg_ip_udp 130.105.5.121}} {masterseqnum 0.100} {masteruuid a1248a5e-e1e6-11cd-aa0c-0800092734a4} {version secd.dce.1.1} dcecp> .oE .SS "registry enable" ...\" .zA "1.1: added registry_replica_name" .PP Enables the master registry for updates. The syntax is as follows: .sS \*Lregistry enable\*O [\*Vregistry_replica_name\*O] .sE .PP The \*Lenable\*O operation enables the master registry for updates. The \*Vregistry_replica_name\*O argument is a single name of a master registry to be enabled. If no argument is given, the operation uses the name in the \*L_s(sec)\*O convenience variable. If the \*L_s(sec)\*O variable is not set, the operation defaults to the master in the local cell. .PP This operation returns an empty string on success and sets the \*L_b(sec)\*O variable to the replica to which it binds. ...\" .zZ "1.1: added registry_replica_name" .PP \*LPrivileges Required\*O .PP You must have \*La\*O (\*Lauth_info\*O) permission to the \*Lreplist\*O object. .PP \*LExamples\*O .PP .oS dcecp> \*Lregistry enable /.../my_cell.goodcompany.com/subsys/dce/sec/snow \*C dcecp> .oE .SS "registry help" .PP Returns help information about the \*Lregistry\*O object and its operations. The syntax is as follows: .sS \*Lregistry help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lregistry\*O object. .LE .PP Used without an argument or option, the \*Lregistry help\*O command returns brief information about each \*Lregistry\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lregistry\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lregistry help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lregistry help\*C catalog Returns a list of all replicas running in the cell. ...\" .zA "1.2.1: new operation" checkpoint Resets registry checkpoint interval dynamically. ...\" .zZ "1.2.1: new operation" connect Creates local and foreign cross-cell authenticated accounts. delete Deletes a replica and removes from master replica list. ...\" .zA "1.1: warranty patch" designate Changes which replica is the master. destroy Destroys the specified replica and its registry database. ...\" .zZ "1.1: warranty patch" disable Disables the specified master registry for updates. dump Returns replica information for each replica in the cell. enable Enables the specified master registry for updates. modify Modifies the master registry or replica. ...\" .zA "1.1: warranty patch" replace Replaces replica information on master replica list. ...\" .zZ "1.1: warranty patch" set Changes which replica is the master. show Returns attributes of the registry and its replicas. stop Stops the specified security server process. ...\" .zA "1.1: warranty patch" synchronize Reinitializes replica with up-to-date copy of the registry. ...\" .zZ "1.1: warranty patch" verify Returns a list of replicas not up-to-date with the master. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "registry modify" ...\" .zA "1.1" added -version" .PP Changes attributes of the registry. The syntax is as follows: .sS \*Lregistry modify \*O[\*Vregistry_replica_name\*O] .nL ...\" .zA "Def,13377,R1.2.2,clarify syntax" {\*L-change \*Vattribute_list\*O | \*L-\*Vattribute value\*O | \*L-key\*O} ...\" .zZ "Def,13377,R1.2.2,clarify syntax" .sE .PP \*LOptions\*O .VL .LI "\*L-\*Vattribute value\*O" As an alternative to using options with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. .LI "\*L-change\*O \*Vattribute_list\*O" Allows you to modify attributes by using an attribute list rather than using individual attribute options. The format of an attribute list is as follows: .iS \*O{{\*Vattribute value\*O}...{\*Vattribute value\*O}} .iE .PP The \*L-change\*O option cannot be used with the \%\*L-key\*O option. ...\" .zA "def,13377,R1.2.1,deleted supportedversions" ...\" .zZ "def,13377,R1.2.1,deleted supportedversions" .LI "\*L-key\*O" Generates a new master key for the replicas listed as the argument. Cannot be used with the \%\*L-change\*O option. .LE .PP The \*Lmodify\*O operation changes attributes of the registry. The \*Vregistry_replica_name\*O is required for the \%\*L-key\*O option but optional for all other options. If an argument is not supplied and the \*L_s(sec)\*O variable is not set, the operation defaults to master in the local cell. ...\" If the \%\*L-change\*O option is used and the ...\" \*L_s(sec)\*O variable is a replica, the command operates on the ...\" master of the replica's cell. This operation returns an empty string on success. .PP Use the \%\*L-change\*O option to modify the value of any one of the attributes. .PP The operation also accepts the \%\*L-key\*O option to generate a new master key for a single replica named in the argument and to reencrypt that registry's account keys using the new master key. The new master key is randomly generated. Each replica (master and slaves) maintains its own master key which is used to access the data in its copy of the database. If you use the \%\*L-key\*O option, you must specify \*Vregistry_replica_name\*O. .PP The \%\*L-change\*O option and the \%\*L-key\*O option cannot be used together. .PP ...\" .zA "def,13377,R1.2.1,deleted supportedversions" ...\" The \%\*L-version\*O option allows you to migrate the cell ...\" security service registry from DCE version 1.0.2 or DCE version 1.0.3 to DCE ...\" version 1.1. This command updates the security service registry to ...\" support DCE version 1.1 security service functionality. ...\" For DCE version 1.1, the only available value for \*Vsupportedversions\*O ...\" is \*Lsecd.dce.1.1\*O. ...\" The \*L-version\*O operation is not reversible; backward ...\" migration is not supported. The \%\*L-version\*O option and the ...\" \%\*L-key\*O option cannot be used together. .PP ...\" .zZ "def,13377,R1.2.1,deleted supportedversions" This operation sets the \*L_b(sec)\*O variable to the replica to which it binds. .PP \*LPrivileges Required\*O .PP You must have \*La\*O (\*Lauth_info\*O) permission to the \*Lreplist\*O object. .PP \*LExamples\*O .PP .oS dcecp> \*Lregistry modify -version secd.dce.1.1\*C dcecp> dcecp> \*Lregistry modify -change {deftktlife +0-08:00:00.000I-----}\*C dcecp> .oE .SS "registry operations" .PP Returns a list of the operations supported by the \*Lregistry\*O object. The syntax is as follows: .sS \*Lregistry operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lregistry operations\*O command. .PP \*LExamples\*O .PP ...\" .zA "1.1 warranty patch" ...\" that is, designate destroy replace synchronize .PP ...\" .zA "1.2.1: new operation" .oS dcecp> \*Lregistry operations\*C catalog checkpoint connect delete designate destroy disable dump enable modify replace show stop synchronize verify help operations dcecp> .oE ...\" .zZ "1.2.1: new operation" ...\" .zZ "1.1 warranty patch" ...\" that is, designate destroy replace synchronize ...\" .zA "1.1 warranty patch: replace" .SS "registry replace" .PP Replaces the network address of a replica. The syntax is as follows: .sS \*Lregistry replace\*O \*Vregistry_replica_name \*L-address \*Vnew_string_binding\*O .sE .PP \*LOptions\*O .VL .LI "\*L-address\*O" The new address for the replica in RPC string-binding format (without the object UUID). The string binding contains an RPC protocol and a network address in the form: .iS \*Vrpc_prot_seq:network_addr .iE .LE .PP The \*Lreplace\*O operation replaces the network address of the specified replica. The new address is used by the master and other replicas to contact the replica. This operation returns an empty string on success, binds to the master, and sets the \*L_b(sec)\*O variable to the master. .to the master. .PP \*LPrivileges Required\*O .PP You must have \*Lm\*O (\*Lmgmt_info\*O) permission to the \*Lreplist\*O object. .PP \*LExamples\*O .PP .oS dcecp> \*Lregistry replace /.:/susbys/dce/sec/maria -address ncadg_ip_udp:15.22.4.93\*C dcecp> .oE ...\" .zZ "1.1 warranty patch: replace" ...\" .zA "1.1: delete set operation" ...\" .SS "registry set" ...\" .P ...\" Changes which replica is the master. The syntax is as follows: ...\" .sS ...\" \*Lregistry set \*Vregistry_replica_name\*O {[\*L-slave\*O] | [\*L-master\*O]} [\*L-force\*O] ...\" .sE ...\" .PP ...\" \*LOptions\*O ...\" .VL ...\" .LI "\*L-slave\*O" ...\" Designates the specified replica as a slave. ...\" .LI "\*L-master\*O" ...\" Designates the specified replica as the master. ...\" .LI "\*L-force\*O" ...\" Forces the command to set the specified replica as the master, even ...\" if other slaves are more up-to-date. Used only with the \*L-master\*O ...\" option. ...\" .LE ...\" .PP ...\" The \*Lregistry set\*O designates the specified replica as the master or a ...\" slave. The \*Vregistry_replica_name\*O ...\" argument is required and must be the name of a single ...\" registry replica. If no options are used, the command sets the ...\" named replica as the new master for the cell and sets ...\" the existing master as a slave. This operation returns ...\" the empty string on success. ...\" .PP ...\" Alternatively, you can use the \*L-slave\*O or \%\*L-master\*O options ...\" to explicatly set the named replica as either a slave or the master. ...\" If you use the \%\*L-master\*O option, the command checks other ...\" slaves to see if they are more up-to-date than the one specified ...\" in the argument. If any are, the command fails with an error, unless ...\" you specify the \*L-force\*O to override this default action. ...\" .PP ...\" The command sets the value of \*L_b(sec)\*O as follows: ...\" .PP ...\" .ML ...\" .LI ...\" If no options are used, \*L_b(sec)\*O is set to the old master replica. ...\" .LI ...\" If \*L-slave\*O or \*L-master\*O is used, \*L_b(sec)\*O is set to ...\" the replica specified in the argument. ...\" .LE ...\" .PP ...\" After invoking \*Lregistry set\*O, you can use the ...\" \*Lregistry dump\*O command to verify that ...\" the \*Ltype\*O attribute has changed and that the previous master is ...\" now a slave while the specified replica is now the master. ...\" .PP ...\" \*LPrivileges Required\*O ...\" .PP ...\" You must have \*La\*O (\*Lauth_info\*O) permission to the \*Lreplist\*O object. ...\" .PP ...\" \*LExamples\*O ...\" .PP ...\" .oS ...\" dcecp> \*Lregistry set /.../my_cell/subsys/dce/sec/\*Vhostname\*C ...\" dcecp> ...\" .oE ...\" .zZ "1.1: delete set operation" .SS "registry show" .P Returns information about the registry and its replicas. The syntax is as follows: .sS \*Lregistry show \*O[\*Vregistry_replica_name\*O] .nL ...\" .zA "def,13377,R1.2.2,add verbose" ...\" .zA "Def,13377,R1.2.2,clarify syntax" [\*L-attributes\*O | \*L-policies\*O | \*L-replica\*O | \*L-master\*O | \*L-verbose\*O] ...\" .zZ "Def,13377,R1.2.2,clarify syntax" ...\" .zZ "def,13377,R1.2.2,add verbose" .sE .PP \*LOptions\*O .VL .LI "\*L-attributes\*O" Returns an attribute list of the registrywide attributes. .LI "\*L-policies\*O" Returns only the registrywide polices. .LI "\*L-replica\*O" Returns the synchronization information for the specified replica. .LI "\*L-master\*O" Returns the synchronization information kept by the master keeps for each slave. .LI "\*L-verbose\*O" Returns the synchronization information kept by the replica. .LE .PP The \*Lshow\*O operation returns information about the registry and its replicas. An optional \*Vregistry_replica_name\*O argument specifies a single registry replica to contact. The operation returns a variety of different information based on the option given. .PP If called with no options or with the \%\*L-attributes\*O option, the operation returns an attribute list of all the registrywide attributes. ...\" followed by any ERAs. .PP If called with the \%\*L-policies\*O option, the operation returns an attribute list of all the registrywide polices. .PP If called with the \%\*L-replica\*O option, the operation returns the propagation information that is kept by the replica specified. ...\" .zA "1.1, CR13077" .PP ...\" .zA "def,13377,R1.2.2,add verbose" If called with the \%\*L-master\*O option, the operation returns the propagation information that is kept by the master for each slave. Use the \%\*L-verbose\*O option to return the propagation information that is kept by the replica. If you specify this option and the optional \*Vregistry_replica_name\*O, \*Vregistry_replica_name\*O must specify the name of the master or the local cell name. ...\" .zZ "def,13377,R1.2.2,add verbose" ...\" .zZ "1.1, CR13077" .PP This operation sets the \*L_b(sec)\*O variable to the replica to which it binds. .PP \*LPrivileges Required\*O .PP You must have \*La\*O (\*Lauth_info\*O) permission to the \*Lreplist\*O object. .PP \*LExamples\*O .PP .oS dcecp> \*Lregistry show -attributes\*C {mingid 31000} {minorgid 100} {minuid 30000} {maxuid 32767} {version secd.dce.1.0.2} dcecp> dcecp> \*Lregistry show -policies\*C {deftktlife +0-10:00:00.000I-----} {mintktlife +0-00:05:00.000I-----} {hidepwd yes} dcecp> dcecp> \*Lregistry show /.../absolut_cell/subsys/dce/sec/ice -replica\*C {name /.../absolut_cell/subsys/dce/sec/ice} {type slave} {cell /.../absolut_cell} {uuid 91259b6c-9415-11cd-a7b5-080009251352} {status enabled} {lastupdtime 1994-07-05-14:38:15.000-04:00I-----} {lastupdseq 0.191} {addresses {ncacn_ip_tcp 130.105.5.93} {ncadg_ip_udp 130.105.5.93}} {masteraddrs {ncacn_ip_tcp 130.105.5.93} {ncadg_ip_udp 130.105.5.93}} {masterseqnum 0.100} {masteruuid 91259b6c-9415-11cd-a7b5-080009251352} {supportedversions secd.dce.1.0.2} {updseqqueue {0.187 0.191}} dcecp> dcecp> \*Lregistry show /.../dcecp.cell.osf.org/subsys/dce/sec/snow -master\*C {name /.../dcecp.cell.osf.org/subsys/dce/sec/snow} {uuid 91259b6c-9415-11cd-a7b5-080009251352} {type master} {addresses {ncacn_ip_tcp 130.105.5.93} {ncadg_ip_udp 130.105.5.93}} {name /.../dcecp.cell.osf.org/subsys/dce/sec/ice} {uuid 91259b6c-9415-11cd-a7b5-080009251352} {type slave} {addresses {ncacn_ip_tcp 130.105.5.93} {ncadg_ip_udp 130.105.5.93}} {propstatus update} {lastupdtime 1994-10-13-14:58:28.000-04:00I-----} {lastupdseqsent 0.528} {numupdtogo 0} {commstate ok} {lastcommstatus {successful completion}} dcecp> .oE .SS "registry stop" .PP Stops the specified security server process. The syntax is as follows: .sS \*Lregistry stop \*Vregistry_replica_name\*O .sE .PP The \*Lstop\*O operation stops the security server specified in the argument. The \*Vregistry_replica_name\*O argument is required and must explicitly name one replica. (A cell name is not valid because more than one replica can operate in a cell.) This operation returns an empty string on success and sets the \*L_b(sec)\*O variable to the replica to which it binds. .PP \*LPrivileges Required\*O .PP You must have \*La\*O (\*Lauth_info\*O) permission to the \*Lreplist\*O object. .PP \*LExamples\*O .PP .oS dcecp> \*Lregistry stop /.:/subsys/dce/sec/snow \*C dcecp> .oE ...\" .zA "1.1 warranty patch: synchronize" .SS "registry synchronize" .PP Causes the specified replica to reinitialize itself with an up-to-date copy of the database. The syntax is as follows: .sS \*Lregistry synchronize \*Vregistry_replica_name\*O .sE .PP The \*Lsynchronize\*O operation reinitializes a slave replica with an up-to-date copy of the database. \*Vregistry_replica_name\*O is the name of the slave replica to operate on. .PP This operation binds to the master and tells the master to: .AL .LI Mark the specified replica named in \*Vregistry_replica_name\*O for reinitialization. .LI Send a message to the replica informing it to reinitialize itself. .LI Gives the replica a list of other replicas with up-to-date copies of the registry. .LE .PP The replica to be initialized then selects a replica from the list provided by the master and asks for a copy of the database. Note that the \*Ldcecp\*O command will return before the synchronize has completed because it simply tells the master to perform the synchronize procedure. .PP Normally, you do not need to use the \*Lregistry synchronize\*O command because registries remain synchronized automatically. This operation returns an empty string on success. .PP This operation sets the \*L_b(sec)\*O variable to the master in the local cell. .PP \*LPrivileges Required\*O .PP You must have \*La\*O (\*Lauth_info\*O) permission to the \*Lreplist\*O object. .PP \*LExamples\*O .PP .oS dcecp> \*Lregistry synchronize /.:/subsys/dce/sec/oddball\*C dcecp> .oE ...\" .zZ "1.1 warranty patch: synchronize" .SS "registry verify" .PP Checks whether all registry replicas are up-to-date. The syntax is as follows: .sS \*Lregistry verify\*O [\*Vregistry_replica_name\*O] .sE .PP .PP Checks whether all registry replicas are up-to-date. If they are, ...\" XXX it returns an empty string. If they are not, it returns a list of ...\" XXX the out-of-date and unreachable replica names (or bindings if names ...\" XXX are not available). You can use the elements of this list ...\" XXX in a \*Lforeach\*O loop around a call to \*Lregistry synchronize\*O ...\" XXX to reinitialize each replica. Note that you can set the \*V_s(sec)\*O ...\" XXX convenience variable to specify another cell or a string binding. it returns an empty string. .PP This operation sets the \*L_b(sec)\*O variable to the last replica to which it binds. .PP \*LPrivileges Required\*O .PP ...\" .zA "def,13377,R1.2.2,change perms" You must have \*La\*O (\*Lauth_info\*O) permission to the \*Lreplist\*O object. ...\" .zZ "def,13377,R1.2.2,change perms" .PP \*LExamples\*O .PP If the replicas are up-to-date, the command returns an empty string, as in the following: .oS dcecp> \*Lregistry verify \*C dcecp> .oE .PP If a replica is not up-to-date, the command returns the fully qualified replica name, as in the following: .oS dcecp> \*Lregistry verify\*C /.../cell/subsys/dce/sec/oddball\*C dcecp> .oE .PP ...\" .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_group(1m)\*O, \*Ldcecp_organization(1m)\*O, \*Ldcecp_principal(1m)\*O, \*Lsecd(1m)\*O. ...\" ...\" \*Ldcecp(1m)\*O, ...\" \*Lgroup(1m)\*O, ...\" \*Lorganization(1m)\*O, ...\" \*Lprincipal(1m)\*O, ...\" \*Lorganization(1m)\*O, ...\" \*Lsecd(1m)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH rpcentry 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lrpcentry\*O" .iX "rpcentry" "administering" .SH NAME .PP \*Lrpcentry\*O - A \*Ldcecp\*O object that manages an RPC entry in the DCE Cell Directory Service .SH "SYNOPSIS" .PP .sS \*Lrpcentry create \*Ventry_name_list\*L .PP \*Lrpcentry delete \*Ventry_name_list\*L .PP \*Lrpcentry export \*Ventry_name_list\*O .nL ...\" .zA "Def,13377,R1.2.2, clarify syntax" {[\*L-object \*Vobject_uuid_list\*O] .nL [\*L-interface \*Vinterface_id\*L -binding \*Vprotocol_sequence_list\*O]} .nL .PP \*Lrpcentry help \*O[\*Voperation\*O | \*L-verbose\*O] .PP ...\" .zA "1.1: delete -version" ...\" .zA "Def,13377,R1.2.2, clarify syntax" \*Lrpcentry import \*Ventry_name_list \*L-interface \*Vinterface_id\*O .nL [\*L-object \*Vobject_uuid\*O] [\*L-max \*Vinteger\*O] [\*L-noupdate\*O] ...\" .zZ "Def,13377,R1.2.2, clarify syntax" ...\" .zZ "1.1: delete -version" .PP \*Lrpcentry operations\*O .PP \*Lrpcentry show \*Ventry_name_list \*L-interface \*Vinterface_id_list\*O .nL [\*L-object \*Vobject_uuid_list\*O] [\*L-noupdate\*O] .PP ...\" .zA "Def,13377,R1.2.2, clarify syntax" \*Lrpcentry unexport \*Ventry_name_list\*O .nL {[\*L-object \*Vobject_uuid_list\*O] .nL [\*L-interface \*Vinterface_id\*O [\*L-version \*Vversions\*O]]} ...\" .zZ "Def,13377,R1.2.2, clarify syntax" .sE .SH "ARGUMENTS" .VL .LI "\*Ventry_name_list\*O" Specifies a list of one or more names of the target name service entry. For an entry in the local cell, you can omit the cell name and specify only cell-relative names. .LI "\*Voperation\*O" The name of the \*Lrpcentry\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Lrpcentry\*O object represents a remote procedure call (RPC) server entry in the cell name service. Use the \*Lrpcentry\*O commands to create, modify, display, and delete name service entries. .SH "DATA STRUCTURES" .VL .LI "\*Vinterface_id\*O" The interface identifier of an RPC interface. The interface identifier takes the following form: .iS \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .iE The version numbers are optional, but if you omit a version number, the value defaults to 0. The UUID is a hexadecimal string and the version numbers are decimal strings. For example: .iS \&-interface ec1eeb60-5943-11c9-a309-08002b102989,3.11 .iE Leading zeros in version numbers are ignored. .PP Alternatively, you can use \*Ldcecp\*O string syntax in the following form: .iS {\*Vinterface-UUID major-version.minor-version\*O} .iE For example: .iS \&-interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0} .iE .PP .LI "\*Vprotocol_sequence_list\*O" An RPC string binding that describes a server's location. The value has the form of an RPC string binding, without an object UUID. The binding information contains an RPC protocol, a network address, and (sometimes) an endpoint within \*L[]\*O (square brackets) as follows: .iS \*Vrpc-prot-seq\*L:\*Vnetwork-addr\*L[\*Vendpoint\*L] .iE For a well-known endpoint, include the endpoint in the string binding surrounded by brackets. You may need to use the \*L\\\*O (backslash) to escape the brackets as shown in the following example. Otherwise \*Ldcecp\*O interprets the brackets as enclosing another command. .iS \&-binding ncadg_ip_udp:63.0.2.17\\[5347\\] .iE .PP For a dynamic endpoint, omit the endpoint from the string binding, for example: .iS \&-b ncacn_ip_tcp:16.20.15.25 .iE .PP Alternatively, you can use \*Ldcecp\*O string syntax. For example: .iS \&-binding {ncacn_ip_tcp 130.105.1.227 1072} .iE .LI "\*Vobject_uuid\*O" The UUID of an object. The UUID is a hexadecimal string, for example: .iS \&-object 3c6b8f60-5945-11c9-a236-08002b102989 .iE .PP Alternatively, you can use \*Ldcecp\*O string syntax. For example: .iS \&-object {3c6b8f60-5945-11c9-a236-08002b102989} .iE .LI "\*Vversion\*O" Specifies which interface version numbers should be returned by a \*Lshow\*O operation. Specify versions by using one of the following values for the \%\*L-version\*O option: .VL 1i .LI "\*Lall\*O" The interface version is ignored. .LI "\*Lexact\*O" Both the major and minor versions must match the specified versions. .LI "\*Lcompatible\*O" The major version must match the specified version, and the minor version must be greater than or equal to the specified version. .LI "\*Lmajor_only\*O" The major version must match the specified version; the minor version is ignored. .LI "\*Lupto\*O" The major version must be less than or equal to that specified. If the major versions are equal, the minor version must be less than or equal to that specified. .LE .PP If the \%\*L-version\*O option is absent, the command shows compatible version numbers. .LE .SH "OPERATIONS" .PP .SS "rpcentry create" .PP Creates an empty entry in the name service. The syntax is as follows: .sS \*Lrpcentry create \*Ventry_name_list\*O .sE .PP The \*Lcreate\*O operation creates an empty entry in the name service. Since an empty entry is the same as an empty RPC group or RPC profile, calling \*Lrpcentry create\*O is the same as calling \*Lrpcgroup create\*O or \*Lrpcprofile create\*O. The \*Ventry_name_list\*O argument is a list of names of RPC entries to be created. If the RPC entry already exists, an error message is returned. This operation returns on empty string on success. .PP \*LPrivileges Required\*O .PP To create an \*Lrpcentry\*O, you need \*Li\*O (\*Linsert\*O) permission to the parent directory and both \*Lr\*O (\*Lread\*O) permission and \*Lw\*O (\*Lwrite\*O) permission to the Cell Directory Service (CDS) object entry (the target name service entry). .PP \*LExamples\*O .PP The following command adds an unspecialized entry to the name service database: .oS dcecp> \*Lrpcentry create /.:/LandS/anthro/Cal_host_2\*C dcecp> .oE .SS "rpcentry delete" .PP Removes the specified entry from the name service. The syntax is as follows: .sS \*Lrpcentry delete \*Ventry_name_list\*O .sE .PP The \*Ldelete\*O operation removes the specified entry from the name service. The \*Ventry_name_list\*O argument is a list of one or more names of server entries to be deleted. This operation returns an empty string on success. If the entry does not exist, an error is returned. .PP \*LPrivileges Required\*O .PP To delete an entry, you need \*Lr\*O (\*Lread\*O) permission to the CDS object entry (the target name service entry). You also need \*Ld\*O (\*Ldelete\*O) permission to the CDS object entry or to the parent directory. .PP \*LExamples\*O .PP The following command removes the entry \*L/.:/LandS/anthro/Cal_host_2\*O from the local cell of the name service database: .oS dcecp> \*Lrpcentry delete /.:/LandS/anthro/Cal_host_2 \*C dcecp> .oE .SS "rpcentry export" .PP Transfers information to the specified entry in the name service. The syntax is as follows: .sS \*Lrpcentry export \*Ventry_name_list\*O .nL {[\*L-object \*Vobject_uuid_list\*O] .nL [\*L-interface \*Vinterface_id\*L -binding \*Vprotocol_sequence_list\*O]} .nL .sE .PP \*LOptions\*O .VL .LI "\*L-object \*Vobject_uuid_list\*O" Declares the UUID of an object. Accepts a list of up to 32 object UUIDs. The UUID is a hexadecimal string. See \*LDATA STRUCTURES\*O for the format of the object UUID. ...\" May be specified by itself or with ...\" the \%\*L-interface\*O and \%\*L-binding\*O options. .LI "\*L-interface \*Vinterface_id\*O" Declares the interface identifier of one RPC interface. If you specify an interface identifier, you must specify at least one \%\*L-binding\*O option. .PP See \*LDATA STRUCTURES\*O for the format of the interface identifier. .LI "\*L-binding \*Vprotocol_sequence_list\*O" Declares a list of one or more protocol sequences (RPC bindings). To use this option, you must also use the \%\*L-interface\*O option to specify an interface identifier. .PP See \*LDATA STRUCTURES\*O for the format of a protocol sequence. .LE .PP The \*Lexport\*O operation transfers information to the specified entry in the name service. The \*Ventry_name_list\*O argument is a list of one or more names of server entries to be exported to. If an entry does not exist, it is created. Uses the \%\*L-interface\*O, \%\*L-binding\*O, and \%\*L-object\*O options to specify what to export. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP To export an entry, you need both \*Lr\*O (\*Lread\*O) permission and \*Lw\*O (\*Lwrite\*O) permission to the CDS object entry (the target name service entry). If the entry does not exist, you also need \*Li\*O (\*Linsert\*O) permission to the parent directory. .PP \*LExamples\*O .PP The following example uses the \*Ldcecp\*O string syntax to export an RPC entry to CDS: .oS dcecp> \*Lrpcentry export /.:/subsys/applications/bbs_server \\ \*C> \*L-interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0} \\ \*C> \*L-binding {ncacn_ip_tcp 130.105.1.227} \\ \*C> \*L-object {76030c42-98d5-11cd-88bc-0000c08adf56} \*C dcecp> .oE .SS "rpcentry help" .PP Returns help information about the \*Lrpcentry\*O object and its operations. The syntax is as follows: .sS \*Lrpcentry help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOption\*O .PP .VL .LI "\*L-verbose\*O" Displays information about the \*Lrpcentry\*O object. .LE .PP Used without an argument or option, the \*Lrpcentry help\*O command returns brief information about each \*Lrpcentry\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lrpcentry\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lrpcentry help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lrpcentry help\*C create Creates a list of empty RPC entries. delete Deletes a list of RPC entries. export Stores bindings in a list of RPC entries. import Returns the bindings from a list of RPC entries. show Returns the attributes of a list of RPC entries. unexport Deletes bindings from a list of RPC entries. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "rpcentry import" .PP Returns a string binding from the specified RPC entry. The syntax is as follows: ...\" .zA "1.1: delete -version" .sS \*Lrpcentry import \*Ventry_name_list \*L-interface \*Vinterface_id\*O .nL [\*L-object \*Vobject_uuid\*O] [\*L-max \*Vinteger\*O] [\*L-noupdate\*O] .sE ...\" .zZ "1.1: delete -version" .PP \*LOptions\*O .PP .VL .LI "\*L-interface \*Vinterface_id\*O" Declares the interface identifier of one RPC interface. .PP See \*LDATA STRUCTURES\*O for the format of the interface identifier. ...\" .zA "1.1: delete -version" ...\" .LI "\*L-version \*Vversions\*O" ...\" Specifies interface version numbers to be returned with an \*Lrpcentry ...\" import\*O operation. Specify versions by using one of the following values ...\" for the \%\*L-version\*O option: ...\" \*Lall\*O, ...\" \*Lexact\*O, ...\" \*Lcompatible\*O, ...\" \*Lmajor_only\*O, ...\" and ...\" \*Lupto\*O. ...\" .PP ...\" See \*LDATA STRUCTURES\*O for the exact behavior of the version values. ...\" .zZ "1.1: delete -version" .LI "\*L-object \*Vobject_uuid\*O" Declares the UUID of one object. The UUID is a hexadecimal string. .PP See \*LDATA STRUCTURES\*O for the format of the object UUID. .LI "\*L-max\*O \*Vinteger\*O" Specifies the maximum number of string bindings to return. A value greater than one returns a list containing up to the number of bindings specified by the value. .LI "\*L-noupdate\*O" Normally, name service data is cached locally on each machine in a cell. If a name service inquiry can be satisfied by data in the local CDS cache, this cached data is returned. However, locally cached copies of name service data might not include a recent CDS update. If the \%\*L-noupdate\*O option is not specified, \*Ldcecp\*O goes to a CDS server to retrieve the required data, updating the local CDS cache. Use the \%\*L-noupdate\*O option to avoid taking the time to update the local cache when you have reason to believe that the local cache is up to date. .LE .PP The \*Limport\*O operation returns a string binding from the specified RPC entry. The \*Ventry_name_list\*O argument is a list of names of RPC entries (not a list of RPC entries) to import from. The order of returned bindings is arbitrary. .PP \*LPrivileges Required\*O .PP You need \*Lr\*O (\*Lread\*O) permission to the specified CDS object entry (the starting name service entry) and to any CDS object entry in the resulting search path. .PP \*LExamples\*O .PP The following command imports an interface and object: .oS dcecp> \*L rpcentry import \*L/.:/LandS/anthro/Cal_host_3\*O \\ \*C> \*L-interface {ec1eeb60-5943-11c9-a309-08002b102989 1.1} \\ \*C> \*L-object 30dbeea0-fb6c-11c9-8eea-08002b0f4528 \*C {ncacn_ip_tcp 130.105.1.227} dcecp> .oS .SS "rpcentry operations" .PP Returns a list of the operations supported by the \*Lrpcentry\*O object. The syntax is as follows: .sS \*Lrpcentry operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lrpcentry operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lrpcentry operations\*C create delete export import show unexport help operations dcecp> .oE .SS "rpcentry show" .PP Returns a list containing the binding information in the specified RPC entries. The syntax is as follows: .sS ...\" .zA "Def,13377,R1.2.2, clarify syntax" \*Lrpcentry show \*Ventry_name_list \*L-interface \*Vinterface_id_list\*O ...\" .zZ "Def,13377,R1.2.2, clarify syntax" .nL [\*L-object \*Vobject_uuid_list\*O] [\*L-noupdate\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-interface \*Vinterface_id_list\*O" Declares a list of one or more interface identifiers of RPC interfaces. .PP See \*LDATA STRUCTURES\*O for the format of the interface identifier. .LI "\*L-object \*Vobject_uuid_list\*O" Declares the UUID of an object. Accepts a list of up to 32 object UUIDs. The UUID is a hexadecimal string. .PP See \*LDATA STRUCTURES\*O for the format of the object UUID. .LI "\*L-noupdate\*O" Normally, name service data is cached locally on each machine in a cell. If a name service inquiry can be satisfied by data in the local CDS cache, this cached data is returned. However, locally cached copies of name service data might not include a recent CDS update. If the \%\*L-noupdate\*O option is not specified, \*Ldcecp\*O goes to a CDS server to retrieve the required data, updating the local CDS cache. Use the \%\*L-noupdate\*O option to avoid taking the time to update the local cache when you have reason to believe that the local cache is up to date. .LE .PP The \*Lshow\*O operation returns a list containing the binding information in the specified RPC entry. The \*Ventry_name_list\*O argument is a list of one or more names of RPC entries to return information about. .PP The returned list consists of two lists. Each item in the first list is also a list, where the first two elements are the interface identifier (the UUID and then the version), and the rest of the elements are string bindings in Tcl syntax. The second list is a list of object UUIDs exported by the server. The order of the data returned is arbitrary. .PP \*LPrivileges Required\*O .PP You need \*Lr\*O (read) permission to the CDS object entry (the target name service entry). .PP \*LExamples\*O .PP The following command uses the \*Ldcecp\*O string syntax to show a name service entry: .oS dcecp> \*Lrpcentry show /.:/subsys/applications/bbs_server\*C {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0 {ncacn_ip_tcp 130.105.1.227}} {76030c42-98d5-11cd-88bc-0000c08adf56} dcecp> .oE .PP The following command operates from the system prompt to show a name service entry: .oS % \*Ldcecp -c rpcentry show /.:/subsys/applications/bbs_server\*C {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0 {ncacn_ip_tcp 130.105.1.227}} {76030c42-98d5-11cd-88bc-0000c08adf56} \*C% .oE .SS "rpcentry unexport" Removes binding information from an entry in the name service. The syntax is as follows: .sS \*Lrpcentry unexport \*Ventry_name_list .nL ...\" .zA "Def,13377,R1.2.2, clarify syntax" \*O{[\*L-object \*Vobject_uuid_list\*O] .nL [\*L-interface \*Vinterface_id\*O [\*L-version \*Vversions\*O]]} ...\" .zZ "Def,13377,R1.2.2, clarify syntax" .nL .sE .PP \*LOptions\*O .PP .VL .LI "\*L-object \*Vobject_uuid_list\*O" Declares the UUID of an object. Accepts a list of up to 32 object UUIDs. The UUID is a hexadecimal string. .PP See \*LDATA STRUCTURES\*O for the format of the object UUID. .LI "\*L-interface \*Vinterface_id\*O" Declares the interface identifier of an RPC interface. Only a single \*Vinterface_id\*O can be specified. .PP See \*LDATA STRUCTURES\*O for the format of the interface identifier. .LI "\*L-version \*Vversions\*O" Specifies interface version numbers to be returned with the \*Lunexport\*O operation. .PP See \*LDATA STRUCTURES\*O for the exact behavior and format of the version values. .LE .PP The \*Lunexport\*O operation removes binding information from an entry in the name service. The \*Ventry_name_list\*O argument is a list of one or more entry names from which binding information is to be removed. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You need both \*Lr\*O (\*Lread\*O) permission and \*Lw\*O (\*Lwrite\*O) permission to the CDS object entry (the target name service entry). .PP \*LExamples\*O .PP The following example uses the \*Ldcecp\*O syntax to unexport the binding information for an interface. The third command entered (\*Lrpcentry show\*O) shows the RPC entry after the unexport operation: the object UUID remains in the entry. .oS dcecp> \*Lrpcentry show /.:/subsys/applications/bbs_server \*C {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0 {ncacn_ip_tcp 130.105.1.227}} {76030c42-98d5-11cd-88bc-0000c08adf56} dcecp> dcecp> \*Lrpcentry unexport /.:/subsys/applications/bbs_server \\ \*C> \*L-interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0} \*C dcecp> dcecp> \*Lrpcentry show /.:/subsys/applications/bbs_server \*C {76030c42-98d5-11cd-88bc-0000c08adf56} dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_endpoint(1m)\*O, \*Ldcecp_rpcgroup(1m)\*O, \*Ldcecp_rpcprofile(1m)\*O. ...\" \*Ldcecp(1m)\*O, ...\" \*Lendpoint(1m)\*O, ...\" \*Lrpcgroup(1m)\*O, ...\" \*Lrpcprofile(1m)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH rpcgroup 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lrpcgroup\*O" .iX "rpcgroup" "administering" .SH NAME .PP \*Lrpcgroup\*O - A \*Ldcecp\*O object that manages an RPC group entry in CDS .SH "SYNOPSIS" .PP .sS \*Lrpcgroup add \*Vrpcgroup_name_list\*L -member \*Vmember_name_list\*O .PP \*Lrpcgroup create \*Vrpcgroup_name_list\*O .PP \*Lrpcgroup delete \*Vrpcgroup_name_list\*O .PP \*Lrpcgroup help \*O[\*Voperation\*O | \*L-verbose\*O] .PP ...\" ...\" .zA "1.1: deleted -version" ...\" ...\" .zA "Def,13377,R1.2.2, clarify syntax" \*Lrpcgroup import \*Vrpcgroup_name_list\*O \*L-interface \*Vinterface_id\*O .nL [\*L-object \*Vobject_uuid\*O] [\*L-max \*Vinteger\*O] [\*L-noupdate\*O] ...\" .zZ "Def,13377,R1.2.2, clarify syntax" ...\" .zZ "1.1: deleted -version" .PP ...\" ...\" .zA "Def,13377,R1.2.2, clarify syntax" \*Lrpcgroup list \*Vrpcgroup_name_list\*O [\*L-member \*Vmember_name_list\*O] .nL [\*L-noupdate\*O] ...\" .zZ "Def,13377,R1.2.2, clarify syntax" .PP \*Lrpcgroup operations\*O .PP \*Lrpcgroup remove \*Vrpcgroup_name_list\*L -member \*Vmember_name_list\*O .sE .SH "ARGUMENTS" .VL .LI "\*Voperation\*O" The name of the \*Lrpcgroup\*O operation for which to display help information. .LI "\*Vrpcgroup_name_list\*O" Specifies a list of one or more names of the RPC groups to be operated on. .LE .SH "DESCRIPTION" .PP The \*Lrpcgroup\*O object represents a remote procedure call (RPC) group entry in the Cell Directory Service (CDS). Each RPC group is named in the DCE namespace; ...\" ...\" .zA "def,13258,R1.2.1,minor recasting of sentence" therefore each operation takes as an argument the name of the group entry to manipulate. ...\" ...\" .zA "def,13258,R1.2.1,minor recasting of sentence" An RPC group is a container that contains only the names of RPC server entries or the names of other RPC groups; it contains no other data. .SH "DATA STRUCTURES" .VL .LI "\*Vinterface_id\*O" The interface identifier of an RPC interface. The interface identifier takes the following form: .iS \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .iE The version numbers are optional, but if you omit a version number, the value defaults to 0. The UUID is a hexadecimal string and the version numbers are decimal strings. For example: .iS \&-interface ec1eeb60-5943-11c9-a309-08002b102989,3.11 .iE Leading zeros in version numbers are ignored. .PP Alternatively, you can use \*Ldcecp\*O string syntax. For example: .iS \&-interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0} .iE .LI "\*Vobject_uuid\*O" The UUID of an object. The UUID is a hexadecimal string, for example: .iS \&-object 3c6b8f60-5945-11c9-a236-08002b102989 .iE .PP Alternatively, you can use \*Ldcecp\*O string syntax. For example: .iS \&-object {3c6b8f60-5945-11c9-a236-08002b102989} .iE .LE .SH "OPERATIONS" .SS "rpcgroup add" .PP Adds a member to the specified group entry in CDS. The syntax is as follows: .sS \*Lrpcgroup add \*Vrpcgroup_name_list\*L -member \*Vmember_name_list\*O .sE .PP \*LOptions\*O .PP .VL .LI "\*L-member \*Vmember_name_list\*O" This required option declares the name of a member to be added to the specified group entry. The \*Vmember_name_list\*O argument is a list of names of one or more members to be added to all of the specified groups. (The names need not exist when they are added.) All members are added to all groups. .LE ...\" ...\" .zA "1.1: CR13072" .PP The \*Ladd\*O operation adds a member to the specified group entry in CDS. The required \*Vrpcgroup_name_list\*O argument is a list of one or more full CDS names of the groups to which you want to add members. This operation returns an empty string on success. If \*Vmember_name_list\*O contains the names of duplicate or existing members, the duplicates are ignored and no errors are generated. ...\" .zZ "1.1: CR13072" .PP \*LPrivileges Required\*O .PP You need \*Li\*O (\*Linsert\*O) permission to the parent directory. You also need both \*Lr\*O (\*Lread\*O) permission and \*Lw\*O (\*Lwrite\*O) permission to the CDS object entry (the target group entry). .PP \*LExamples\*O .PP The following command adds the member \*L/.:/LandS/anthro/Cal_host_3\*O to the group \*L/.:/LandS/anthro/Calendar_group\*O: .oS dcecp> \*Lrpcgroup add /.:/LandS/anthro/Calendar_group\*O \\ \*C> \*L-member /.:/LandS/anthro/Cal_host_3\*C dcecp> .oE .SS "rpcgroup create" .PP Creates an empty RPC group entry in CDS. The syntax is as follows: .sS \*Lcreate \*Vrpcgroup_name_list\*O .sE .PP The \*Lcreate\*O operation creates a new (empty) RPC group entry in CDS. Since an empty group is the same as an empty RPC entry or RPC profile, calling \*Lrpcgroup create\*O is the same as calling \*Lrpcentry create\*O or \*Lrpcprofile create\*O. The \*Vrpcgroup_name_list\*O argument is a list of names of RPC groups to be created. The operation returns an empty string on success. If the RPC group already exists, an error is returned. .PP \*LPrivileges Required\*O .PP You need \*Li\*O (\*Linsert\*O) permission to the parent directory. .PP \*LExamples\*O .PP The following command creates a new group called \*L/.:/LandS/anthro/Calendar_group\*O: .oS dcecp> \*Lrpcgroup create /.:/LandS/anthro/Calendar_group\*C dcecp> .oE .SS "rpcgroup delete" .PP Removes the specified group from CDS. The syntax is as follows: .sS \*Lrpcgroup delete \*Vrpcgroup_name_list\*O .sE .PP The \*Ldelete\*O operation removes the specified group entry from CDS. The \*Vrpcgroup_name_list\*O argument is a list of names of RPC group entries to be deleted. This operation returns an empty string on sucess. If the RPC group entry does not exist, an error is generated. .PP \*LPrivileges Required\*O .PP You need \*Lw\*O (\*Lwrite\*O) permission to the CDS object entry (the target group entry). .PP \*LExamples\*O .PP The following command removes the group \*L/.:/LandS/anthro/Calendar_group\*O from CDS. .oS dcecp> \*Lrpcgroup delete /.:/LandS/anthro/Calendar_group\*C dcecp> .oE .SS "rpcgroup help" .PP Returns help information about the \*Lrpcgroup\*O object and its operations. The syntax is as follows: .sS \*Lrpcgroup help \*O[\*Voperation\*O | \*L-verbose\*O] .sE \*LOption\*O .PP .VL .LI "\*L-verbose\*O" Displays information about the \*Lrpcgroup\*O object. .LE .PP Used without an argument or option, the \*Lrpcgroup help\*O command returns brief information about each \*Lrpcgroup\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lrpcgroup\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lrpcgroup help\*O command. .PP \*LExamples\*O .oS dcecp> \*Lrpcgroup help\*C add Adds members to a list of RPC groups. create Creates a list of empty RPC groups. delete Deletes a list of RPC groups. import Returns the bindings from a list of RPC groups. list Returns the members of a list of RPC groups. remove Removes members from a list of RPC groups. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "rpcgroup import" .PP Returns a string binding from the specified RPC group. The syntax is as follows: ...\" ...\" .zA "1.1: deleted -version" .sS \*Lrpcgroup import \*Vrpcgroup_name_list\*O \*L-interface \*Vinterface_id\*O .nL [\*L-object \*Vobject_uuid\*O] [\*L-max \*Vinteger\*O] [\*L-noupdate\*O] .sE ...\" .zZ "1.1: deleted -version" .PP \*LOptions\*O .PP .VL .LI "\*L-interface \*Vinterface_id\*O" Declares the interface identifier of one RPC interface. .PP See \*LDATA STRUCTURES\*O for the format of the interface identifier. ...\" ...\" .zA "1.1: deleted -version" ...\" .LI "\*L-version \*Vversions\*O" ...\" Specifies interface version numbers to be returned with an \*Lrpcentry ...\" import\*O operation. Specify versions by using one of the following values ...\" for the \%\*L-version\*O option: ...\" \*Lall\*O, ...\" \*Lexact\*O, ...\" \*Lcompatible\*O, ...\" \*Lmajor_only\*O, ...\" and ...\" \*Lupto\*O. ...\" .PP ...\" See \*LDATA STRUCTURES\*O for the exact behavior of the version values. ...\" .zZ "1.1: deleted -version" .LI "\*L-object \*Vobject_uuid\*O" Declares the UUID of one object. The UUID is a hexadecimal string. .PP See \*LDATA STRUCTURES\*O for the format of the object UUID. .LI "\*L-max \*Vinteger\*O" Specifies the maximum number of string bindings to return. A value greater than one returns a list containing up to the number of bindings specified by the value. .LI "\*L-noupdate\*O" Normally, name service data is cached locally on each machine in a cell. If a name service inquiry can be satisfied by data in the local CDS cache, this cached data is returned. However, locally cached copies of name service data might not include a recent CDS update. If the \%\*L-noupdate\*O option is not specified, \*Ldcecp\*O goes to a CDS server(s) to retrieve the required data, updating the local CDS cache. Use the \%\*L-noupdate\*O option to avoid taking the time to update the local cache when you have reason to believe that the local cache is up to date. .LE .PP The \*Limport\*O operation returns a string binding from the specified RPC group. The \*Vrpcgroup_name_list\*O argument is a list of names of RPC groups to import from. The operation uses the \%\*L-interface\*O and \%\*L-object\*O options to specify matching bindings. The operation also accepts the \%\*L-max\*O option to specify a number of string bindings to return. The order of bindings returned is arbitrary. .PP \*LPrivileges Required\*O .PP You need \*Lr\*O (\*Lread\*O) permission to the specified CDS object entry (the starting name service entry) and to any CDS object entry in the resulting search path. .PP \*LExamples\*O .PP The following command imports an interface and object: .oS \*Cdcecp> \*Lrpcgroup import /.:/ortho_group \\ \*C> \*L-interface {ec1eeb60-5943-11c9-a309-08002b102989 1.1} \\ \*C> \*L-object 30dbeea0-fb6c-11c9-8eea-08002b0f4528\*C {ncadg_ip_udp 15.22.48.25} {ncacn_ip_tcp 15.22.48.25} dcecp> .oE .SS "rpcgroup list" .PP Returns a list of the names of all members of the specified group. The syntax is as follows: .sS ...\" ...\" .zA "Def,13377,R1.2.2, clarify syntax" \*Lrpcgroup list \*Vrpcgroup_name_list \*O[\*L-member \*Vmember_name_list\*O] .nL [\*L-noupdate\*O] ...\" .zZ "Def,13377,R1.2.2, clarify syntax" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-member \*Vmember_name_list\*O" Specifies a list of names of one or more members to be returned from all groups named in the \*Vrpcgroup_name_list\*O argument. Use this option to check for specific member names. The \*Vmember_name_list\*O argument specifies a list of names of RPC entries, RPC groups, or RPC profiles; they are only references stored in the RPC group and do not have to actually exist outside of the group. All members specified are listed from all RPC groups specified in the argument. .LI "\*L-noupdate\*O" Use \*L-noupdate\*O to avoid taking the time to update the local cache. .PP See \*Lrpcgroup import\*O for more information. .LE .PP The \*Llist\*O operation returns a list of the names of all members of the specified group. The returned names are fully qualified names and are returned in an arbitrary order. The \*Vrpcgroup_name_list\*O argument is a list of names of RPC groups whose members' names are to be returned. .PP \*LPrivileges Required\*O .PP You need \*Lr\*O (\*Lread\*O) permission to the CDS object entry (the target group entry). .PP \*LExamples\*O .PP The following example lists all the members of the group \*L/.:/subsys/applications/infobases\*O, in the order in which they were added to the group: .oS dcecp> \*Lrpcgroup list /.:/subsys/applications/infobases\*C /.../my_cell.goodcompany.com/subsys/applications/video_server /.../my_cell.goodcompany.com/subsys/applications/bbs_server /.../my_cell.goodcompany.com/subsys/applications/audio_server1 /.../my_cell.goodcompany.com/subsys/applications/audio_server2 /.../my_cell.goodcompany.com/subsys/applications/clipart_server /.../my_cell.goodcompany.com/subsys/applications/photo_server1 /.../my_cell.goodcompany.com/subsys/applications/photo_server2 dcecp> .oE .PP The following example uses the \%\*L-member\*O option to list a specific member of the group \*L/.:/subsys/applications/infobases\*O: .oS dcecp> \*Lrpcgroup list /.:/subsys/applications/infobases \\\*C > \*L-member /.:/subsys/applications/bbs_server\*C /.../my_cell.goodcompany.com/subsys/applications/bbs_server dcecp> .oE .SS "rpcgroup operations" .PP Returns a list of the operations supported by the \*Lrpcgroup\*O object. The syntax is as follows: .sS \*Lrpcgroup operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lrpcgroup operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lrpcgroup operations\*C add create delete import list remove help operations dcecp> .oE .SS "rpcgroup remove" .PP Removes one or more members from the specified group. The syntax is as follows: .sS \*Lrpcgroup remove \*Vrpcgroup_name_list\*L -member \*Vmember_name_list\*O .sE .PP \*LOptions\*O .PP .VL .LI "\*L-member \*Vmember_name_list\*O" This required option lets you specify a list of names of one or more members to be removed from all groups named in the \*Vrpcgroup_name_list\*O argument. The \*Vmember_name_list\*O argument specifies a list of names of RPC entries, RPC groups, or RPC profiles; these are only references stored in the RPC group and need not actually exist outside of the group. All members specified are removed from all RPC groups specified in the argument. .LE .PP The \*Lremove\*O operation removes one or more members from the specified group. The \*Vrpcgroup_name_list\*O argument is a list of names of RPC groups to have members removed from. The value of the required \%\*L-member\*O option is a list of names of RPC entries, RPC groups, or RPC profiles. If a specified member does not exist in an RPC group an error is returned. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You need \*Lr\*O (\*Lread\*O) permission and \*Lw\*O (\*Lwrite\*O) permission to the CDS object entry (the target group entry). .PP \*LExamples\*O .PP The following command removes the member \*L/.:subsys/applications/video_server\*O from the RPC group \*L/.:/subsys/applications/infobases\*O: .oS dcecp> \*Lrpcgroup remove /.:/subsys/applications/infobases \\\*C > \*L-member /.../my_cell.goodcompany.com/subsys/applications/video_server \*C dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad 1 \*Ldcecp(1m)\*O, \*Ldcecp_endpoint(1m)\*O, \*Ldcecp_rpcentry(1m)\*O, \*Ldcecp_rpcprofile(1m)\*O. .ad b ...\" .ad 1 ...\" \*Ldcecp(1m)\*O, ...\" endpoint(1m)\*O, ...\" rpcentry(1m)\*O, ...\" rpcprofile(1m)\*O. ...\" .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH rpcprofile 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lrpcprofile\*O" .iX "rpcprofile" "administering" .SH NAME .PP \*Lrpcprofile\*O - A \*Ldcecp\*O object that manages an RPC profile entry in CDS .SH "SYNOPSIS" .PP ...\" .zA "def,13377,R1.2.2,clarify sytnax" .sS \*Lrpcprofile add \*Vprofile_name_list\*L -member \*Vmember_name_list\*O .nL {\*L-interface \*Vinterface_id\*O [\*L-priority \*Vpriority\*O] [\*L-annotation \*Vannotation\*O] | .nL \*L-default\*O} .PP \*Lrpcprofile create \*Vprofile_name_list\*O .PP \*Lrpcprofile delete \*Vprofile_name_list\*O .PP \*Lrpcprofile help \*O[\*Voperation\*O | \*L-verbose\*O] .PP ...\" .zA "1.1: delete -version" \*Lrpcprofile import \*Vprofile_name_list\*O \*L-interface \*Vinterface_id\*O .nL [\*L-object \*Vobject_uuid\*O] [\*L-max \*Vinteger\*O] [\*L-noupdate\*O] ...\" .zZ "1.1: delete -version" .PP \*Lrpcprofile list \*Vprofile_name_list\*O [\*L-member \*Vmember_name_list\*O] [\*L-noupdate\*O] .PP \*Lrpcprofile operations\*O .PP \*Lrpcprofile remove \*Vprofile_name_list\*O .nL {\*L-default\*O | \*L-member \*Vmember_name\*O \*L-interface \*Vinterface_id\*O | .nL \*L-annotation \*Vannotation\*O | \*L-priority \*Vpriority\*O} .PP \*Lrpcprofile show \*Vprofile_name_list\*O .nL {\*L-default\*O | [\*L-member \*Vmember_name\*O] [\*L-interface \*Vinterface_id\*O] .nL [\*L-version \*Vversions\*O] [\*L-priority \*Vpriority\*O] [\*L-annotation \*Vannotation\*O] .nL [\*L-noupdate\*O]} .sE ...\" .zZ "def,13377,R1.2.2,clarify sytnax" .SH "ARGUMENTS" .VL .LI "\*Voperation\*O" The name of the \*Lrpcprofile\*O operation for which to display help information. .LI "\*Vprofile_name_list\*O" Specifies a list of one or more names of the RPC profile entries to be operated on. .LE .SH "DESCRIPTION" .PP The \*Lrpcprofile\*O object represents a remote procedure call (RPC) profile entry in the Cell Directory Service (CDS). Each operation described below, except \*Lhelp\*O and \*Loperation\*O, takes as an argument a list of one or more names of RPC profiles to be operate on. An RPC profile consists of members (also known as elements in other DCE documentation). A member can be either RPC server entries, RPC groups, or other RPC profiles; therefore each member of a profile has a name in the DCE namespace. Each profile can also have one default member (called the default profile element). .PP A profile entry contains no attributes, but it does contain information about each member that is not contained in the member itself. The information stored for each member includes up to four fields of information consisting of interface and version, a member name, a priority (0 through 7), and an annotation. For example: .iS {d46113d0-a848-11cb-b863-08001e046aa5 2.0} .nL /.../my_cell.goodcompany.com/sec 0 rs_bind} .iE .PP Various \*Lrpcprofile\*O operations have options that correspond to the fields of information contained in profile members. Specifically, the options are \%\*L-interface\*O, \%\*L-member\*O, \%\*L-priority\*O, and \%\*L-annotation\*O. .SH "DATA STRUCTURES" .VL .LI "\*Vinterface_id\*O" The interface identifier of an RPC interface. The interface identifier takes the following form: .iS \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .iE The version numbers are optional, but if you omit a version number, the value defaults to 0. The UUID is a hexadecimal string and the version numbers are decimal strings. For example: .iS \&-interface ec1eeb60-5943-11c9-a309-08002b102989,3.11 .iE Leading zeros in version numbers are ignored. .PP Alternatively, you can use \*Ldcecp\*O string syntax in the following form: .iS {\*Vinterface-UUID major-version.minor-version\*O} .iE For example: .iS \&-interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0} .iE .PP .LI "\*Vobject_uuid\*O" The UUID of an object. The UUID is a hexadecimal string, for example: .iS \&-object 3c6b8f60-5945-11c9-a236-08002b102989 .iE .PP Alternatively, you can use \*Ldcecp\*O string syntax. For example: .iS \&-object {3c6b8f60-5945-11c9-a236-08002b102989} .iE .LI "\*Vhost_address\*O" An RPC string binding that describes a host's location. The binding information contains an RPC protocol and the host's network address. Any specific host's network address can be obtained by using the \*Lgetip\*O command. .LI "\*Vannotation\*O" An informational text string that helps you to identify the purpose of the endpoint. Use single or double quotation marks around the annotation field of endpoints to include internal spaces in an annotation, for example: .iS \&-annotation "Bulletin Board Server, Version 1.3a" .iE .PP Alternatively, you can use \*Ldcecp\*O string syntax. For example: .iS \&-annotation {Bulletin Board Server, Version 1.3a} .iE .LI "\*Vversion\*O" Specifies which interface version numbers to be returned with a \*Lshow\*O operation. Specify versions by using one of the following values for the \%\*L-version\*O option: .VL 1i .LI "\*Lall\*O" The interface version is ignored. .LI "\*Lexact\*O" Both the major and minor versions must match the specified versions. .LI "\*Lcompatible\*O" The major version must match the specified version, and the minor version must be greater than or equal to the specified version. .LI "\*Lmajor_only\*O" The major version must match the specified version; the minor version is ignored. .LI "\*Lupto\*O" The major version must be less than or equal to that specified. If the major versions are equal, the minor version must be less than or equal to that specified. .LE .PP If the \%\*L-version\*O option is absent, the command shows \*Lcompatible\*O version numbers. .LE .SH "OPERATIONS" .SS "rpcprofile add" .PP Adds a member to the specified profile entry in CDS. The syntax is as follows: .sS \*Lrpcprofile add \*Vprofile_name_list\*L -member \*Vmember_name_list\*O .nL {\*L-interface \*Vinterface_id\*O [\*L-priority \*Vpriority\*O] [\*L-annotation \*Vannotation\*O] | .nL \*L-default\*O} .sE .PP \*LOptions\*O .PP .VL .LI "\*L-member \*Vmember_name_list\*O" This required option declares the name of a member to be added to the specified profile entry. The \*Vmember_name_list\*O argument is a list of names of one or more members to be added to all of the specified profiles. If you use the \%\*L-default\*O option, this option is ignored. .PP See \*LDATA STRUCTURES\*O for the format of the interface identifier. .LI "\*L-interface \*Vinterface_id\*O" Required when the \%\*L-default\*O option is not used, this declares the interface identifier of an RPC interface. The \*Ladd\*O operation operates on only one \*Vinterface_id\*O. .LI "\*L-priority \*Vpriority\*O" Defines a search priority for the new profile element. The priority value is in the range 0 to 7 with zero having the highest priority. By default, a non-default element is assigned a priority value of zero. .LI "\*L-annotation \*Vannotation\*O" Defines an annotation string for the profile element. You can include internal spaces in an annotation by enclosing the string in quotation marks. .LI "\*L-default\*O" Performs the operation on the default profile member. When you use the \%\*L-default\*O option, all of the other options except \*L-member\*O are illegal. .LE .PP The \*Ladd\*O operation adds a member to the specified profile entry in CDS. The \*Vprofile_name_list\*O argument is a list of names of RPC profiles to have members added to. The value of the required \%\*L-member\*O option is a list of names which are references to an RPC entry, RPC group, or RPC profile (that is, they do not have to actually exist). .PP The operation accepts the \%\*L-interface\*O, \%\*L-priority\*O, and \%\*L-annotation\*O options with one value (not a list) each. All members are added to each profile identified in the argument list. It also accepts a \%\*L-default\*O option to indicate that the member being added is the default profile member. (If you specify the \%\*L-default\*O option, the only other option that can be supplied is \%\*L-member\*O.). This operation returns an empty string on success. If \*Vmember_name_list\*O contains the names of duplicate or existing members, the duplicates are ignored, and no errors are generated. .PP \*LPrivileges Required\*O .PP You need \*Li\*O (\*Linsert\*O) permission to the parent directory. You also need both \*Lr\*O (\*Lread\*O) permission and \*Lw\*O (\*Lwrite\*O) permission to the CDS object entry (the target profile entry). .PP \*LExamples\*O .PP The following command adds an element to the cell profile, \*L/.:/cell-profile\*O, in the local cell: .PP .oS dcecp> \*Lrpcprofile add /.:/cell-profile \\\*C > \*L-member /.:/Calendar_profile \\ \*C > \*L-interface ec1eeb60-5943-11c9-a309-08002b102989,1.1 \\ \*C > \*L-annotation RefersToCalendarGroups \*C dcecp> .oE .PP The following commands set up a user profile associated with the cell profile as its default element and add a user-specific element for the Calenda V1.1 interface: .oS dcecp> \*Lrpcprofile add /.:/LandS/anthro/molly_o_profile -defaul /.:/cell-profile\*C dcecp> dcecp> \*Lrpcprofile add /.:/LandS/anthro/molly_o_profile \\\*C > \*L-member {/.:/LandS/anthro/Calendar_group} \\\*C > \*L-interface {ec1eeb60-5943-11c9-a309-08002b102989 1.1} \\\*C > \*L-annotation {Calendar_Version 1.1_Interface}\*C dcecp> .oE .PP The added profile element contains the global name of the member (specified by using its cell-relative name, \*L/.:/LandS/anthro/Calendar_group\*O) and the RPC interface identifier for the Calendar Version 1.1 interface. .SS "rpcprofile create" .PP Creates a new profile entry in CDS. The syntax is as follows: .sS \*Lrpcprofile create \*Vprofile_name_list\*O .sE .PP The \*Lcreate\*O operation creates a new (empty) profile entry in CDS. Since an empty profile is the same as an empty RPC entry or RPC group, calling \*Lrpcprofile create\*O is the same as calling \*Lrpcentry create\*O or \*Lrpcgroup create\*O. The \*Vprofile_name_list\*O argument is a list of names of RPC profiles to be created. This operation returns an empty string on success. If the RPC profile already exists, an error is returned. .PP \*LPrivileges Required\*O .PP You need \*Li\*O (\*Linsert\*O) permission to the parent directory. You also need both \*Lr\*O (\*Lread\*O) permission and \*Lw\*O (\*Lwrite\*O) permission to the CDS object entry (the target profile entry). .PP \*LExamples\*O .oS dcecp> \*Lrpcprofile create /.:/users/wards_profile\*C dcecp> .oE .SS "rpcprofile delete" .PP Deletes the specified profile from CDS. The syntax is as follows: .sS \*Lrpcprofile delete \*Vprofile_name_list\*O .sE .PP The \*Ldelete\*O operation deletes the specified profile from CDS. The \*Vprofile_name_list\*O argument is a list of names of RPC profiles to be deleted. This operation returns an empty string on success. If the RPC profile does not exist an error is generated. .PP \*LPrivileges Required\*O .PP You need \*Lw\*O (\*Lwrite\*O) permission to the CDS object entry (the target profile entry). .PP \*LExamples\*O .PP The following command deletes the profile named \*L/.:/LandS/anthro/molly_o_profile\*O: .PP .oS dcecp> \*Lrpcprofile delete /.:/LandS/anthro/molly_o_profile\*C dcecp> .oE .SS "rpcprofile help" .PP Returns help information about the \*Lrpcprofile\*O object and its operations. The syntax is as follows: .sS \*Lrpcprofile help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-verbose\*O Displays information about the \*Lrpcprofile\*O object. .LE .PP Used without an argument or option, the \*Lrpcprofile help\*O command returns brief information about each \*Lrpcprofile\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lrpcprofile\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lrpcprofile help\*O command. .PP \*LExamples\*O .PP .oS \*Cdcecp> \*Lrpcprofile help\*C add Adds members to a list of RPC profiles. create Creates a list of empty RPC profiles. delete Deletes a list of RPC profiles. import Returns the bindings from a list of RPC profiles. list Returns the names of members of a list of RPC profiles. remove Removes members from a list of RPC profiles. show Returns the attributes of a list of RPC profiles. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "rpcprofile import" .PP Returns a string binding from the specified RPC profile. The syntax is as follows: ...\" .zA "1.1: delete -version" .sS \*Lrpcprofile import \*Vprofile_name_list\*O \*L-interface \*Vinterface_id\*O .nL [\*L-object \*Vobject_uuid\*O] [\*L-max \*Vinteger\*O] [\*L-noupdate\*O] .sE ...\" .zZ "1.1: delete -version" .PP \*LOptions\*O .PP .VL .LI "\*L-interface \*Vinterface_id\*O" Declares the interface identifier of an RPC interface. The \*Limport\*O operation allows you to specify only one \*Vinterface_id\*O, not a list. .PP See \*LDATA STRUCTURES\*O for the format of the interface identifier. ...\" .zA "1.1: delete -version" ...\" .zZ "1.1: delete -version" .LI "\*L-object \*Vobject_uuid_list\*O" Declares the UUID of an object. Each \*Limport\*O operation accepts a list of up to 32 object UUIDs. The UUID is a hexadecimal string. .LI "\*L-max \*Vinteger\*O" Specifies the maximum number of string bindings to return. A value greater than one returns a list containing up to the number of bindings specified by the value. .LI "\*L-noupdate\*O" Normally, name service data is cached locally on each machine in a cell. If a name service inquiry can be satisfied by data in the local CDS cache, this cached data is returned. However, locally cached copies of name service data might not include a recent CDS update. If the \%\*L-noupdate\*O option is not specified, \*Ldcecp\*O goes to a CDS server to retrieve the required data, updating the local CDS cache. Use the \%\*L-noupdate\*O option to avoid taking the time to update the local cache when you have reason to believe that the local cache is up to date. .LE .PP The \*Limport\*O operation returns a string binding from the specified RPC profile. The \*Vprofile_name_list\*O argument is a list of names of RPC profiles to import from. Uses the \%\*L-interface\*O and \%\*L-object\*O options to specify matching bindings. Each of these takes only one value not a list of values. Also accepts the \%\*L-max\*O option to specify a number of string bindings to return. If the value is greater than one, then a list of as many matching bindings less than or equal to the value is returned. The order of bindings returned is arbitrary. .PP \*LPrivileges Required\*O .PP You need \*Lr\*O (\*Lread\*O) permission to the specified CDS object entry (the starting name service entry) and to any CDS object entry in the resulting search path. .PP \*LExamples\*O .PP The following example imports a binding: .oS dcecp> \*Lrpcprofile import /.:/cell-profile \\ \*C> \*L-interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0} \*C{ncadg_ip_udp 15.22.48.25} {ncadg_ip_udp 15.22.50.213} {ncacn_ip_tcp 15.22.48.25} {ncacn_ip_tcp 15.22.50.213} dcecp> .oE .SS "rpcprofile list" .PP Returns a list of the names of all members of the specified profile. The syntax is as follows: .sS \*Lrpcprofile list \*Vprofile_name_list\*O [\*L-member \*Vmember_name_list\*O] [\*L-noupdate\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-member \*Vmember_name_list\*O" Declares the names of members of the specified profile entry. The \*Vmember_name_list\*O argument is a list of names of one or more members to be listed. ...\" .zA "def,13377,R1.2.1,rewrote description" .LI "\*L-noupdate\*O" Use this option to avoid taking the time to update the local cache. See \*Lrpcprofile import\*O for more information. ...\" .zZ "def,13377,R1.2.1,rewrote description" .LE .PP The \*Llist\*O operation returns a list of the names of all members of the specified profile. The returned names are fully qualified names and are returned in an arbitrary order. The \*Vprofile_name_list\*O argument is a list of names of RPC profiles whose members' names are to be returned. The members are concatenated on output into one list. .PP \*LPrivileges Required\*O .PP You need \*Lr\*O (\*Lread\*O) permission to the CDS object entry (the target profile entry). .PP \*LExamples\*O .PP The following command lists entries in the cell profile \*L/.:/cell-profile\*O in the local cell: .oS dcecp> \*Lrpcprofile list /.:/cell-profile\*C /.../my_cell.goodcompany.com/sec /.../my_cell.goodcompany.com/sec-v1 /.../my_cell.goodcompany.com/sec /.../my_cell.goodcompany.com/sec /.../my_cell.goodcompany.com/lan-profile /.../my_cell.goodcompany.com/fs /.../my_cell.goodcompany.com/subsys/dce/dfs/bak dcecp> .oE .SS "rpcprofile operations" .PP Returns a list of the operations supported by the \*Lrpcprofile\*O object. The syntax is as follows: .sS \*Lrpcprofile operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lrpcprofile operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lrpcprofile operations\*C add create delete import list remove show help operations dcecp> .oE .SS "rpcprofile remove" .PP Removes one or more members from the specified profile. The syntax is as follows: .sS \*Lrpcprofile remove \*Vprofile_name_list\*O .nL {\*L-default\*O | \*L-member \*Vmember_name\*O \*L-interface \*Vinterface_id\*O | .nL \*L-annotation \*Vannotation\*O | \*L-priority \*Vpriority\*O} .sE .PP \*LOptions\*O .PP .VL .LI "\*L-default\*O" Performs the \*Lremove\*O operation on the default profile element. When you use the \%\*L-default\*O option, all of the other options are illegal. ...\" .zA "1.1: CR13054" .LI "\*L-member \*Vmember_name\*O" Required when the \%\*L-default\*O option is not used, this option lets you specify the name a member to be removed from all profiles named in the \*Vprofile_name_list\*O argument. The value of the \%\*L-member\*O option is a single name of an RPC entry, RPC group, or RPC profile; the name is only a reference stored in the RPC profile and need not actually exist outside of the profile. The specified member is removed from all RPC profiles specified in the argument. ...\" .zZ "1.1: CR13054" .LI "\*L-interface \*Vinterface_id\*O" Declares the interface identifier of an RPC interface. The \*Lremove\*O operation allows you to specify only one \*Vinterface_id\*O. .LI "\*L-annotation \*Vannotation\*O" Defines an annotation string for the profile element to be removed. You can include internal spaces in an annotation by enclosing the string in quotation marks (or by using other \*Ldcecp\*O quoting mechanisms). .LI "\*L-priority \*Vpriority\*O" Defines a search priority for the profile element you want to see. The priority value is in the range 0 to 7 with zero having the highest priority. By default, a non-default element is assigned a priority value of zero. .PP See \*LDATA STRUCTURES\*O for the format of the interface identifier. .LE ...\" .zA "1.1: CR13054" .PP The \*Lremove\*O operation removes one member from the specified profile(s). The \*Vprofile_name_list\*O argument is a list of names of RPC profiles from which the member is to be removed. The member to be removed must match the values given in the following options: \*L-member\*O, \*L-interface\*O, and \*L-annotation\*O. These options are all single valued; they are not lists. The matching member is removed from all RPC profiles specified in the argument. Also accepts a \%\*L-default\*O option, in which case the above options are illegal and the default profile member is removed. This operation returns an empty string on success. If the specified member does not exist in an RPC profile an error is returned. ...\" .zZ "1.1: CR13054" .PP \*LPrivileges Required\*O .PP You need \*Lr\*O (\*Lread\*O) and \*Lw\*O (\*Lwrite\*O) permission to the CDS object entry (the target profile entry). .PP \*LExamples\*O .PP The following example removes the member \*L/.:/subsys/applications/infobases\*O with interface \*L{baf8c319-998f-11cd-ac7b-0000c08adf56 1.0}\*O from the RPC profile entry \*L/.:/users/admin_profile\*O: .oS dcecp> \*Lrpcprofile remove /.:/users/admin_profile \\\*C > \*L-member /.:/subsys/applications/infobases \\ \*C > \*L-interface {baf8c319-998f-11cd-ac7b-0000c08adf56 1.0}\*C dcecp> .oE .SS "rpcprofile show" .PP Returns a list of all members of one or more profiles. The syntax is as follows: .sS \*Lrpcprofile show \*Vprofile_name_list\*O .nL {\*L-default\*O | [\*L-member \*Vmember_name\*O] [\*L-interface \*Vinterface_id\*O] .nL [\*L-version \*Vversions\*O] [\*L-priority \*Vpriority\*O] [\*L-annotation \*Vannotation\*O] .nL [\*L-noupdate\*O]} .sE .PP \*LOptions\*O .PP .VL .LI "\*L-default\*O" Performs the \*Lshow\*O operation on the default profile element. When you use the \%\*L-default\*O option, all of the other options are illegal. .LI "\*L-member \*Vmember_name\*O" Specifies one member name for which to return profile information. .PP See \*LDATA STRUCTURES\*O for the format of the interface identifier. .LI "\*L-interface \*Vinterface_id\*O" Declares the interface identifier of an RPC interface. The \*Lshow\*O operation allows you to specify only one \*Vinterface_id\*O. .LI "\*L-version \*Vversions\*O" Specifies interface version numbers to be returned. This option must be used with the \%\*L-interface\*O option. .PP See \*LDATA STRUCTURES\*O for the exact behavior of the version values. .LI "\*L-priority \*Vpriority\*O" Defines a search priority for the profile element you want to see. The priority value is in the range 0 to 7 with zero having the highest priority. By default, a non-default element is assigned a priority value of zero. .LI "\*L-annotation \*Vannotation\*O" Defines an annotation string for the profile element. You can include internal spaces in an annotation by enclosing the string in quotation marks (or by using other \*Ldcecp\*O quoting mechanisms). ...\" .zA "def,13377,R1.2.1,rewrote description" .LI "\*L-noupdate\*O" Use this option to avoid taking the time to update the local cache. See \*Lrpcprofile import\*O for more information. ...\" .zZ "def,13377,R1.2.1,rewrote description" .LE .PP The \*Lshow\*O operation returns a list of all members of one or more profiles. The \*Vprofile_name_list\*O argument is a list of names of RPC profiles to have members of returned. An attribute list is returned for each member with all of the entered information. It is always in the following order: \*Linterface\*O, \*Lmember\*O, \*Lpriority\*O, \*Lannotation\*O. If any of the items is not given, they are not included in the output, that is, no place holder is included. .P Only those members that match the values specified by the given options are returned. Each option may have only one value (that is, the value may not be a list). Also accepts a \%\*L-default\*O option, in which case the above options are ignored and the default profile member is returned. .PP \*LPrivileges Required\*O .PP You need \*Lr\*O (\*Lread\*O) permission to the CDS object entry (the target profile entry). .PP \*LExamples\*O .PP The following example uses no options to show all the members of a profile: .oS ...\" .S -3 dcecp> \*Lrpcprofile show /.:/users/temp_profile\*C {{458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0} /.../cell.co.com/subsys/appls/infobases 0} {{00000000-0000-0000-0000-000000000000 0.0} /.../cell.co.com/cell-profile 0} {{baf8c319-998f-11cd-ac7b-0000c08adf56 1.0} /.../cell.co.com/subsys/appls/infobases 0} dcecp> ...\" .S +3 .oE .PP The following example uses the \%\*L-interface\*O option to show a single member of a profile. .oS ...\" .S -3 dcecp> \*Lrpcprofile show /.:/users/temp_profile \\ \*C > \*L-interface {baf8c319-998f-11cd-ac7b-0000c08adf56 1.0}\*C {{baf8c319-998f-11cd-ac7b-0000c08adf56 1.0} /.../cell.co.com/subsys/appls/infobases 0} ...\" .S +3 .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_endpoint(1m)\*O, \*Ldcecp_rpcentry(1m)\*O, \*Ldcecp_rpcgroup(1m)\*O. ...\" \*Ldcecp(1m)\*O, ...\" \*Lendpoint(1m)\*O, ...\" \*Lrpcentry(1m)\*O, ...\" *Lrpcgroup(1m)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH secval 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lsecval\*O" .iX "secval" "administering" .SH NAME .PP \*Lsecval\*O - A \*Ldcecp\*O object that manages the security validation service on a host .SH "SYNOPSIS" .sS \*Lsecval activate \*O[\*Vhost_name_list\*O] .PP \*Lsecval deactivate \*O[\*Vhost_name_list\*O] .PP \*Lsecval help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lsecval operations\*O .PP \*Lsecval ping \*O[\*Vhost_name_list\*O] .PP \*Lsecval status \*O[\*Vhost_name_list\*O] .PP ...\" .zA "1.2.1: update -pesite" \*Lsecval update \*O[\*Vhost_name_list\*O] [\*L-pesite \*Vtime_in_seconds\*O] ...\" .zZ "1.2.1: update -pesite" .sE .SH "ARGUMENTS" .VL .LI "\*Vhost_name_list\*O" A list of one or more names of host systems whose security validation systems you want to act on. If you do not specify this argument, the local host is assumed. The argument is optional and takes either of the following forms: .iS /.:/hosts/\*Vhost_name /.../\*Vcell_name\*L/hosts/\*Vhost_name .iE .LI "\*Voperation\*O" The name of the \*Lsecval\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Lsecval\*O object represents the security validation service running on a host, as part of the \*Ldced\*O server. This service is responsible for maintaining the security credentials of the host machine. .PP Access to the commands is based on the access control list (ACL) of the security validation object for a host. This takes the form of \*L/.../\*Vcell_name\*L/hosts/\*Vhost_name\*L/config/secval\*O. .SH "OPERATIONS" .SS "secval activate" .PP Activates a security validation service. The syntax is as follows: .sS \*Lsecval activate \*O[\*Vhost_name_list\*O] .sE .PP The \*Lactivate\*O operation activates a security validation service. If it is already activated, an error is returned. The optional \*Vhost_name_list\*O argument is a list of one or more names of host systems whose security validation systems you want to activate. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lx\*O (\*Lexecute\*O) permission to the security validation service object. .PP \*LExamples\*O .PP .oS dcecp> \*Lsecval activate\*C dcecp> .oE .SS "secval deactivate" .PP Deactivates a security validation service. The syntax is as follows: .sS \*Lsecval deactivate \*O[\*Vhost_name_list\*O] .sE .PP The \*Ldeactivate\*O operation deactivates a security validation service. If it is already deactivated, an error is returned. The optional \*Vhost_name_list\*O argument is a list of one or more names of host systems whose security validation systems you want to deactivate. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Ls\*O (\*Lstop\*O) permission to the security validation service object. .PP \*LExamples\*O .PP .oS dcecp> \*Lsecval deactivate\*C dcecp> .oE .SS "secval help" .PP Returns help information about the \*Lsecval\*O object and its operations. The syntax is as follows: .sS \*Lsecval help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lsecval\*O object. .LE .PP Used without an argument or option, the \*Lsecval help\*O command returns brief information about each \*Lsecval\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lsecval\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lsecval help\*O command. .PP \*LExamples\*O .oS dcecp> \*Lsecval help\*C activate Enables the secval service. deactivate Disables the secval service. ping Contacts the dced secval to validate the security service. status Returns 1 if secval is enabled, 0 if not. ...\" .zA "1.2.1: update -pesite" update Updates a component of the secval. ...\" .zZ "1.2.1: update -pesite" help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "secval operations" .PP Returns a list of the operations supported by the \*Lsecval\*O object. The syntax is as follows: .sS \*Lsecval operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lsecval operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lsecval operations\*C ...\" .zA "1.2.1: update -pesite" activate deactivate ping status update help operations dcecp> ...\" .zZ "1.2.1: update -pesite" .oE .SS "secval ping" .PP Validates the credentials returned by a DCE security service. The syntax is as follows: .sS \*Lsecval ping \*O[\*Vhost_name_list\*O] .sE .PP The \*Lping\*O operation validates the credentials returned by a security service. This is expected to be a rarely invoked routine, but it could be used to verify that \*Lsecd\*O is trusted. The operation returns \*L1\*O if the credentials are valid, \*L0\*O if they are not. The optional \*Vhost_name_list\*O argument is a list of one or more names of host systems whose security validation systems you want to validate. If the argument is a list of host names, a list is returned with a \*L1\*O or a \*L0\*O for each server. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lsecval ping\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lsecval ping\*C 1 dcecp> .oE .SS "secval status" .PP Checks for an active secval. The syntax is as follows: .sS \*Lsecval status \*O[\*Vhost_name_list\*O] .sE .PP The \*Lstatus\*O operation returns \*L1\*O if the security validation service is activated, \*L0\*O if it is not. If the argument is a list, a list is returned, with a \*L0\*O or \*L1\*O for each server. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lsecval status\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lsecval status\*C 1 dcecp> .oE ...\" .zA "1.2.1: update -pesite" .SS "secval update" .PP Updates a component of the secval service. The syntax is as follows: .sS \*Lsecval update \*O[\*Vhost_name_list\*O] [\*L-pesite \*Vtime_in_seconds\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-pesite\*O" Sets the amount of time to wait between each pe_site Thread Maintenance update. .LE .PP The \*Lupdate\*O operation updates a component of the security validation service. Currently only updates to the pe_site Maintainer Thread are supported. Use the \%\*L-pesite\*O option to set the amount of time in seconds between each update. The update is performed after the time specified in \*Vtime_in_seconds\*O passes, if the \%\*L-pesite\*O option is not supplied, the update is performed immediately. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lx\*O permission to the security validation service object. .PP \*LExamples\*O .PP .oS dcecp> \*Lsecval update -pesite 300\*C dcecp> .oE ...\" .zZ "1.2.1: update -pesite" ...\" ...\" .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldced(1m)\*O ...\" \*Ldcecp(1m)\*O, ...\" \*Ldced(1m)\*O. .ad b ..\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH server 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lserver\*O" .iX "server" "administering" .SH NAME .PP \*Lserver\*O - A \*Ldcecp\*O object that manages DCE application servers .SH "SYNOPSIS" .sS ...\" \*Lserver catalog\*O [\*Vhost_name_list\*O] [\*L-executing\*O] [\*L-simplename\*O] ...\" .zA "1.2.1: added -local" \*Lserver catalog\*O [\*Vhost_name_list\*O] [\*L-executing\*O] [\*L-simplename\*O] .nL [\*L-local\*O] ...\" .zZ "1.2.1: added -local" .PP ...\" \*Lserver create\*O \*Vserver_name_list\*O {\*L-attribute \*Vattribute_list\*O | \*Vattribute_options\*O} ...\" .zA "1.2.1: added -local" \*Lserver create\*O \*Vserver_name_list .nL ...\" .zA "def,13377,R1.2.2, clarify syntax" \*O{\*L-attribute \*Vattribute_list\*O | \*L-\*Vattribute value\*O} .nL [\*L-local\*O] ...\" .zZ "1.2.1: added -local" .PP ...\" \*Lserver delete \*Vserver_name_list\*O ...\" .zA "1.2.1: added -local" \*Lserver delete \*Vserver_name_list\*O [\*L-local\*O] ...\" .zZ "1.2.1: added -local" .PP \*Lserver disable \*Vserver_name_list\*O [\*L-interface \*Vinterface_id_list\*O] .PP \*Lserver enable \*Vserver_name_list\*O [\*L-interface \*Vinterface_id_list\*O] .PP \*Lserver help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lserver modify \*Vserver_name_list\*O .nL {\*L-add \*Vextended_rgy_attr_list\*O | .nL \*L-remove \*Vextended_rgy_attr_list \*O[\*L-types\*O] | .nL \*L-change \*Vattribute_list\*O} .nL [\*L-local\*O] .PP \*Lserver operations\*O .PP ...\" .zA "1.1: added -timeout" \*Lserver ping \*Vserver_name_list\*O [\*L-timeout \*Vtimeout_method\*O] ...\" .zZ"def,13377,R1.2.2, clarify syntax" ...\" .zZ "1.1: added -timeout" .PP ...\" \*Lserver show\*O \*Vserver_name_list\*O [\*L-executing\*O] ...\" .zA "1.2.1: added -local" \*Lserver show\*O \*Vserver_name_list\*O [\*L-executing\*O] [\*L-local\*O] ...\" .zZ "1.2.1: added -local" .PP \*Lserver start \*Vserver_name_list\*O [\*L-uuid \*Vuuid_list\*O] .PP \*Lserver stop \*Vserver_name_list\*O [\*L-method \*Vmethod\*O] .sE .SH "ARGUMENTS" .VL .LI "\*Vhost_name_list\*O" A list of one or more DCE host names specifying hosts for which to catalog servers. Host names can be in any of the following forms: .iS \*L/.:/hosts/\*Vhostname \*L/.../\*Vcell_name\*L/hosts/\*Vhostname \*Lhosts/\*Vhostname\*O .iE .LI "\*Vserver_name_list\*O" A list of one or more names of servers to act on. Server names have the following form: .iS /.../\*Vcell_name\*L/hosts/\*Vhost_name\*L/config/\*Vservice\*L/\*Vname .iE where \*Vservice\*L\*O is one of the following: \*Lsrvrconf\*O, \*Lsrvrexec\*O, or \*Lserver\*O. The first two replacements for \*Vservice\*O uniquely identify the correct service as either the configuration service or the execution service. The third is a simpler but ambiguous term; however, the ambiguity can usually be resolved by context. For example, the \*Lstop\*O operation only applies to a \*Lsrvrexec\*O object. In cases where it is still ambiguous, a \*Lsrvrconf\*O object is assumed unless the \%\*L-executing\*O option is present. .PP Examples of server names are shown in the \*LOPERATIONS\*O sections of this reference page. .LI "\*Voperation\*O" The name of the \*Lserver\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Lserver\*O object refers to servers residing on a host. This one object can affect both the running daemons and the configuration information used by \*Ldced\*O to start that daemon. The distinction is usually obvious by the definition of the operation or by the name given as an argument. When this is not the case, the ambiguity is resolved by a required option. .PP Almost all of these commands contact the \*Ldced\*O on the target host to perform their operations. Exceptions to this are noted below. .PP Some commands operate on a single server while other commands operate on more than one server. See the \*LARGUMENTS\*O section of this reference page for a description of how to specify server names. .PP Server configuration objects may contain application-specific extended registry attributes (ERAs). Only the ERAs can be modified after creation, other attributes cannot. .PP When the \*Ldced\*O on the local machine is in partial service mode, you must use the \%\*L-local\*O option to access the \*Lserver\*O object. To access the \*Lserver\*O object when \*Ldced\*O is in this mode, specify only the residual portion of the object name. For example, specify \*Lserver/\*Vserver_name\*O, not \*L/.:/hosts/\*Vhost_name\*L/config/server/\*Vserver_name\*O. .SH "DATA STRUCTURES" .VL .LI "\*Vinterface_id\*O" The interface identifier of an RPC interface. The interface identifier takes the following form: .iS \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .iE The version numbers are optional, but if you omit a version number, the value defaults to 0. The UUID is a hexadecimal string and the version numbers are decimal strings. For example: .iS \&-interface ec1eeb60-5943-11c9-a309-08002b102989,3.11 .iE Leading zeros in version numbers are ignored. .PP Alternatively, you can use \*Ldcecp\*O string syntax in the following form: .iS {\*Vinterface-UUID major-version.minor-version\*O} .iE For example: .iS \&-interface {458ffcbe-98c1-11cd-bd93-0000c08adf56 1.0} .iE .PP .LE .SH "ATTRIBUTES" .PP .VL .LI "\*Larguments \*Vstring_list\*O" The command-line arguments passed to the program on startup. Its value is a list of strings. May not be modified after creation. .LI "\*Ldirectory \*Vdirectory_name\*O" The working directory that the server is started with. May not be modified after creation. .LI "\*Lgid \*Vgroup_id\*O" The POSIX group identifier (\*Lgid\*O) that the server is started with. May not be modified after creation. .LI "\*Lkeytabs \*Vkeytab_list\*O" A list of UUIDs of related keytab objects where the server stores its keys. May not be modified after creation. .LI "\*Lprogram \*Vprogram_name\*O" The name of the server program to be run. Its' value is a string. May not be modified after creation. .LI "\*Lprerequesites \*Vuuid_list\*O" A list of UUIDs of other server configuration objects that represents servers that must be running before this one is started. In DCE Version 1.1, this information is not used to start the other servers; it is merely a note to the administrator. Future versions of \*Ldced\*O will probably take action based on this attribute. May not be modified after creation. .LI "\*Lprincipals \*Vprincipal_name_list\*O" A list of principal names that the server runs as. For example, \*Lsecd\*O runs as three different principals. A fully qualified name is always returned on output. On input a relative principal name represents a principal in the default cell of the \*Ldced\*O. May not be modified after creation. .LI "\*Lservices \*Vattribute_list\*O" A list where each element is an attribute list of the following attributes: .VL .LI "\*Lannotation \*Vstring\*O" A human readable Portable Character Set (PCS) string describing the service. (This is not an internationalized string, for compatibility with DCE Version 1.0 endpoint map annotation strings.) .LI "\*Lbindings \*Vprotocol_sequence_list\*O" A list of string bindings identifying the service. ...\" This is only specified for well-known endpoints. .LI "\*Lflags \*Vflag_name_list\*O" The value is a list of key words to identify flags for the server. Currently only the following is supported: .VL 1i .LI "\*Ldisabled\*O" The mapping has been marked as disabled in the endpoint map. .LE .LI "\*Lifname \*Vinterface_name\*O" The name of the interface of the service limited to PCS characters. .LI "\*Linterface \*Vinterface_id\*O" The interface identifier (UUID and version) of the service. .LI "\*Lentryname \*Vservice_name\*O" The name of the service (limited to PCS characters). .LI "\*Lobjects \*Vobject_uuid_list\*O" A list of object UUIDs supported by the service. .LE .LI "\*Lexecuting\*O{ \*Vuuid pid\*O}" A list of two elements, the UUID of the server instance and the pid (process ID) of the running server. This attribute is only present if the server is running. This attribute is multi-valued, one value for each instance of the server. .LI "\*Lstarton \*Vstarting_condition_list\*O" This attribute identifies when a server should be started. The value is a list of one or more of the following, none of which can be modified after creation. .VL 1i .LI "\*Lauto\*O" Start if a remote call that would be serviced by this server is received by \*Ldced\*O. Ignored for those servers that are repositories. .LI "\*Lboot\*O" Start at system startup. .LI "\*Lexplicit\*O" Start if \*Ldced\*O receives a command to start the server (such as the \*Lserver start\*O command in \*Ldcecp\*O). .LI "\*Lfailure\*O" Start if \*Ldced\*O detects that the server exited with a nonsuccessful error code. .LE .PP Specifying a null value to this attribute means the server will not be started. An example of a possible value is as follows: .iS {starton {boot explicit failure}} .iE .PP .LI "\*Luid \*Vuser_id\*O" The POSIX user identifier (\*Luid\*O) that the server is started with. May not be modified after creation. .LI "\*Luuid \*Vuuid\*O" The internal identifier of the object. It can be specified on creation, or automatically generated, but once created it may not be modified. .LE .PP Server configuration objects may also have ERAs attached to them. ERAs may be manipulated by the \*Lmodify\*O operation. .PP ...\" See the \*(Ag for more information about server attributes. See the \*VOSF DCE Administration Guide\*O for more information about server attributes. .SH "OPERATIONS" .PP .SS "server catalog" .PP Returns a list of the names of all server configuration objects on a specified host. The syntax is as follows: .sS ...\" \*Lserver catalog\*O [\*Vhost_name_list\*O] [\*L-executing\*O] [\*L-simplename\*O] ...\" .zA "1.2.1: added -local" \*Lserver catalog\*O [\*Vhost_name_list\*O] [\*L-executing\*O] [\*L-simplename\*O] .nL [\*L-local\*O] ...\" .zZ "1.2.1: added -local" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-executing\*O" Returns the name of all servers known by \*Ldced\*O that are currently running on the specified host. .LI "\*L-simplename\*O" Returns names but removes the \*L/.../\*Vcellname\*L/hosts/\*Vhostname\*L/config/\*Vservice\*L/\*O portion of the name. ...\" .zA "1.2.1: added -local" .LI "\*L-local\*O" Specifies that the command is to operate on the local \*Ldced\*O object while the \*Ldced\*O on the local machine is in partial service mode. ...\" .zZ "1.2.1: added -local" .LE .PP The \*Lcatalog\*O operation returns a list of the names of all server configuration objects on a specified host. If called with the \%\*L-executing\*O option, it returns the name of all server execution objects (running servers) known by \*Ldced\*O that are currently executing on the specified host. If called with no arguments, it returns information about the servers on the local host. The optional \*Vhost_name_list\*O argument is a list of host names. If more than one is specified then the information returned is concatenated together. The order of information returned is arbitrary. Fully qualified names are returned by default; use the \%\*L-simplename\*O option to return the names without prepending the cellname and the name of the server container. .PP \*LPrivileges Required\*O .PP You must have \*Li\*O (\*Linsert\*O) permission to the applicable container (configuration or execution) object. .PP \*LExamples\*O .PP .oS dcecp> \*Lserver catalog /.:/hosts/foster/config\*C /.:/hosts/gumby/config/srvconf/try_tserver dcecp> .oE .SS "server create" .PP Creates a server configuration object. The syntax is as follows: .sS ...\" .zA "1.2.1: added -local" ...\" .zA "def,13377,R1.2.2, clarify syntax" \*Lserver create\*O \*Vserver_name_list\*O {\*L-attribute \*Vattribute_list\*O | \*L-\*Vattribute value\*O} .nL [\*L-local\*O] ...\" .zZ "def,13377,R1.2.2, clarify syntax" ...\" .zZ "1.2.1: added -local" .sE .PP \*LOptions\*O .PP .VL .LI "\*L-attribute \*Vattribute_list\*O" Allows you to specify attributes by using an attribute list rather than using the \*L-\*Vattribute value\*O option. The format of an attribute list is as follows: .iS {{\*Vattribute \*Vvalue\*O}...{\*Vattribute \*Vvalue\*O}} .iE .LI "\*L-\*Vattribute value\*O" As an alternative to using the \*L-attribute\*O option with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. .PP See \*LATTRIBUTES\*O for descriptions of attributes. ...\" .zA "1.2.1: added -local" .LI "\*L-local\*O" Specifies that the command is to operate on the local \*Ldced\*O object while the \*Ldced\*O on the local machine is in partial service mode. ...\" .zZ "1.2.1: added -local" .LE .PP ...\" .zA "def,13377,R1.2.2, clarify syntax" The \*Lcreate\*O operation creates a server configuration object. The \*Vserver_name_list\*O argument is a list of names of server configuration objects to be created. An \%\*L-attribute\*O option with an argument list as a value is required to define attributes for the server to be created; the operation also accepts individual \*L-\*Vattribute value\*O. It returns an empty string on success. ...\" .zZ "def,13377,R1.2.2, clarify syntax" .PP \*LPrivileges Required\*O .PP You must have \*Li\*O (\*Linsert\*O) permission to the configuration container object. .PP \*LExamples\*O .PP .oS dcecp> \*Lserver create /.:/hosts/foster/config/srvrconf/try_tserver \e\*C > \*L-arguments /.:/hosts/foster/test_server \e\*C > \*L-program tserver \e\*C > \*L-entryname /.:/hosts/foster/test_server \e\*C > \*L-services {{ifname {test server}} \*C > \*L {annotation {dcecp server test program}}\*C > \*L {interface {008bebed-c7c1-1ddc-9cb3-0000c0ba4944 1.0}}\*C > \*L {bindings {ncadg_ip_udp 130.105.5.50}}\*C > \*L {objects 0073f23a-2e1a-1ddd-b73a-0000c0ba4944}\*C > \*L {flags {}}\*C > \*L {entryname /.:/hosts/foster/test_server}}}\*C > \*L-principals tserver \e\*C > \*L-starton boot auto explicit failure \e\*C > \*L-directory {/opt/tserver}\*C dcecp> .oE .SS "server delete" .PP Deletes a server configuration object. The syntax is as follows: .sS ...\" \*Lserver delete \*Vserver_name_list\*O ...\" .zA "1.2.1: added -local" \*Lserver delete \*Vserver_name_list\*O [\*L-local\*O] ...\" .zZ "1.2.1: added -local" .sE .PP The \*Ldelete\*O operation deletes a server configuration object. The \*Vserver_name_list\*O argument is a list of names of server configuration objects to be deleted. This operation returns an empty string on success. An error is returned if any of the objects do not exist. .PP ...\" ...\" .zA "1.2.1: added -local" \*LOptions\*O .PP .VL .LI "\*L-local\*O" Specifies that the command is to operate on the local \*Ldced\*O object while the \*Ldced\*O on the local machine is in partial service mode. .LE ...\" .zZ "1.2.1: added -local" \*LPrivileges Required\*O .PP You must have \*Ld\*O (\*Ldelete\*O) permission to the server configuration object. .PP \*LExamples\*O .PP .oS dcecp> \*Lserver delete /.:/hosts/foster/config/srvrconf/try_tserver\*C dcecp> .oE .SS "server disable" .PP Disables the specified server. The syntax is as follows: .sS \*Lserver disable \*Vserver_name_list\*O [\*L-interface \*Vinterface_id_list\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-interface \*Vinterface_id_list\*L\*O Optionally specifies a list of one or more RPC interfaces to be disabled. The interface identifier can be in string syntax or \*Ldcecp\*O syntax. .PP See \*LDATA STRUCTURES\*O for a description of string and \*Ldcecp\*O syntaxes. .LE .PP The \*Ldisable\*O operation disables the specified server. It communicates with \*Ldced\*O and removes the endpoints for all interfaces registered by the server (except the \*Lrpc_mgmt\*O interface) from the endpoint map. The \*Vserver_name_list\*O argument is a list of names of server execution objects. The operation accepts an optional \%\*L-interface\*O option to specify a list of interfaces to be disabled. It returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission to the server configuration object. .PP \*LExamples\*O .PP .oS dcecp> \*Lserver disable /.:/hosts/foster/config/srvrexec/try_tserver \*C dcecp> .oE .SS "server enable" .PP Enables the specified server. The syntax is as follows: .sS \*Lserver enable \*Vserver_name_list\*O [\*L-interface \*Vinterface_id_list\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-interface \*Vinterface_id_list\*L\*O Optionally specifies a list of one or more RPC interfaces to be disabled. The interface identifier can be in string syntax or \*Ldcecp\*O syntax. .PP See \*LDATA STRUCTURES\*O for a description of string and \*Ldcecp\*O syntax. .LE .PP The \*Lenable\*O operation enables the specified server. It communicates with \*Ldced\*O and enables any previously disabled endpoint mapping for all interfaces registered by the server in the endpoint map. The argument \*Vserver_name\*O is a list of names of server execution objects. This operation accepts an optional \%\*L-interface\*O option to specify a list of interfaces to be enabled and returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission to the server execution object. .PP \*LExamples\*O .PP .oS dcecp> \*Lserver enable /.:/hosts/foster/config/srvrexec/try_tserver \*C dcecp> .oE .SS "server help" .PP Returns help information about the \*Lserver\*O object and its operations. The syntax is as follows: .sS \*Lserver help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lserver\*O object. .LE .PP Used without an argument or option, the \*Lserver help\*O command returns brief information about each \*Lserver\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lserver\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lserver help\*O command. .PP \*LExamples\*O .oS dcecp> \*Lserver help\*C catalog Returns the list of srvrconf or srvrexec object names. create Creates a new server configuration (srvrconf) object. delete Deletes a server configuration (srvrconf) object. disable Disables interfaces of server execution (srvrexec) object. enable Enables interfaces of server execution (srvrexec) object. modify Modifies the srvrconf object's variable attributes. ping Pings a server to see if it is receiving requests. show Returns the attributes of a srvrconf or srvrexec object. start Starts the specified server. stop Stops the specified running server. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "server modify" .PP Used to add or remove fixed attributes or ERAs and their values from the server configuration object. The syntax is as follows: .sS ...\" .zA "def,13377,R1.2.2, clarify syntax" \*Lserver modify \*Vserver_name_list\*O .nL {\*L-add \*Vextended_rgy_attr_list\*O | .nL ...\" [\*L-remove \*Vextended_registry_attribute_list\*O [\*L-types\*O]] ...\" .zA "1.2.1: added -local" .nL \*L-remove \*Vextended_rgy_attr_list\*O [\*L-types\*O] | ...\" .zZ "1.2.1: added -local" .nL \*L-change \*Vattribute_list\*O} .nL \*O[\*L-local\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-add\*O \*Vextended_rgy_attr_list\*O" Allows you to add ERAs that may be defined for your environment. You can specify the attributes to be added as a list. ...\" See the \*(Ag for more information about ERAs. See the \*VOSF DCE Administration Guide\*O for more information about ERAs. .LI "\*L-remove\*O \*Vextended_rgy_attr_list\*O" ...\" .zZ "def,13377,R1.2.2, clarify syntax" Allows you to remove ERAs that may be defined for your environment. You can specify the attributes to be removed as a list. ...\" See the \*(Ag for more information about ERAs. See the \*VOSF DCE Administration Guide\*O and for more information about ERAs. .LI "\*L-types\*O" Specifies that a list of attribute names instead of names and values was given as the value of the \%\*L-remove\*O option, indicating that the entire attribute should be removed and not just specified values. .LI "\*L-change\*O \*Vattribute_list\*O" Allows you to specify attributes by using an attribute list in the following format: .iS {{\*Vattribute \*Vvalue\*O}...{\*Vattribute \*Vvalue\*O}} .iE .PP See \*LATTRIBUTES\*O for more information about server attributes. ...\" .zA "1.2.1: added -local" .LI "\*L-local\*O" Specifies that the command is to operate on the local \*Ldced\*O object while the \*Ldced\*O on the local machine is in partial service mode. ...\" .zZ "1.2.1: added -local" .LE .PP The \*Lmodify\*O operation changes fixed attributes or adds or removes ERAs and their values from the server object. The \*Vserver_name_list\*O argument is a list of names of server objects to be modified. The operation accepts the \%\*L-change\*O option which must have an attribute list as its value. Attribute options are not supported for this command. The name is always for a server configuration object; you may not modify a server execution object. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lw\*O (\*Lwrite\*O) permission to the server configuration object. .PP \*LExamples\*O .PP .oS \*Cdcecp> \*Lserver modify /.:/hosts/foster/config/srvrconf/try_tserver \e\*C > \*L-add {data {second server list}}\*C dcecp> .oE .SS "server operations" .PP Returns a list of the operations supported by the \*Lserver\*O object. The syntax is as follows: .sS \*Lserver operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lserver operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lserver operations\*C catalog create delete disable enable modify ping show start stop help operations dcecp> .oE .SS "server ping" .PP Checks whether a server is receiving client requests. The syntax is as follows: ...\" .zA "1.1: added -timeout" .sS \*Lserver ping \*Vserver_name_list\*O [\*L-timeout\*O \*Vtimeout_method\*O] .sE .PP \*LOptions\*O .VL ...\" .zA "def,13377,R1.2.2, clarify syntax" .LI "\*L-timeout\*O \*Vtimeout_method\*O" ...\" .zZ "def,13377,R1.2.2, clarify syntax" Specifies the timeout method to use during communication with the server. Legal values are: \*Lmin\*O (the default), \*Lmax\*O or \*Ldefault\*O. .LE .PP The \*Lping\*O operation queries a server to see if it is receiving requests. This operation communicates directly with the server. The \*Vserver_name_list\*O argument is a list identifying the servers to ping. .PP The \%\*L-timeout\*O option controls the communication timeout used in contacting the server being pinged. Use \*Lmin\*O for speed, \*Lmax\*O for accuracy, and \*Ldefault\*O for a compromise between speed and accuracy. ...\" .zZ "1.1: added -timeout" .PP This operation returns a list of values, one for each server specified in the argument, in the same order. The values are \*L1\*O if the server is listening for RPC requests, \*L0\*O if it is not. .PP Each argument can be in one of the following formats: .ML .LI The name of a server entry in the namespace to be imported from. For example: .iS /.../brain_cell/hosts/wallis/srvrexec/event_server .iE .LI A string binding with an object UUID specified. For example: .iS {00337ea9-d979-1dd8-923f-0000c08adf56 ncacn_ip_tcp 15.121.12.72} .iE .LI A string binding with an endpoint specified. For example: .iS {ncacn_ip_tcp 15.121.12.72 1075} .iE .LI An interface ID followed by a hostname, separated by commas. For example: .iS {4885772c-c6d3-11ca-84c6-08002bic8fif,oddball} .iE .LI An interface ID followed by an object UUID and a hostname, separated by commas. For example: .iS {4885772c-c6d3-11ca-84c6-08002bic8fif, 019ee420-682d-1109-a607-08002bodea7a, oddball} .iE .LE .PP \*LPrivileges Required\*O .PP Often no special privileges are required, but this can vary depending on the individual server. .PP \*LExamples\*O .PP .oS dcecp> \*Lserver ping /.../brain_cell/hosts/wallis/srvrexec/event_server\*C 1 dcecp> .oE .SS "server show" .PP Returns information about servers. The syntax is as follows: .sS ...\" .zA "1.2.1: added -local" \*Lserver show\*O \*Vserver_name_list\*O [\*L-executing\*O] [\*L-local\*O] ...\" .zZ "1.2.1: added -local" .sE .PP \*LOptions\*O .VL .LI "\*L-executing\*O" Returns an attribute list for a running server rather than its associated configuration object. ...\" .zA "1.2.1: added -local" .LI "\*L-local\*O" Specifies that the command is to operate on the local \*Ldced\*O object while the \*Ldced\*O on the local machine is in partial service mode. ...\" .zZ "1.2.1: added -local" .LE .PP The \*Lshow\*O operation returns a list of both the fixed attributes and ERAs for the server entries specified in the argument. The argument \*Vserver_name_list\*O is a list of names of server object entries. If the names are ambiguous, server configuration objects are assumed unless the \%\*L-executing\*O option is present. If the argument is a list the output is concatenated into a single list in the order specified. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the specified (configuration or execution) object. .PP \*LExamples\*O .PP .oS dcecp> \*Lserver show /.:/hosts/foster/config/srvrconf/try_tserver\*C {uuid 003b24d2-a196-1df3-915f-0000c0ba4944} {program tserver} {arguments /.:/hosts/foster/test_server} {prerequisites {}} {keytabs {}} {entryname /.:/hosts/foster/test_server} {services {{ifname {test server}} {annotation {dcecp server test program}} {interface {008bebed-c7c1-1ddc-9cb3-0000c0ba4944 1.0}} {bindings {ncadg_ip_udp 130.105.5.50}} {objects 0073f23a-2e1a-1ddd-b73a-0000c0ba4944} {flags {}} {entryname /.:/hosts/foster/test_server}}} {principals /.../foster_cell/tserver} {starton boot auto explicit failure} {uid 0} {gid 0} {dir /opt/tserver} dcecp> .oE .SS "server start" .PP Contacts a \*Ldced\*O process to start a server based on a server configuration object. The syntax is as follows: .sS \*Lserver start \*Vserver_name_list\*O [\*L-uuid \*Vuuid_list\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-uuid \*Vuuid_list\*L\*O" A list of one or more UUIDs that identify the server to be started. .LE The \*Lstart\*O operation contacts a \*Ldced\*O to start a server based on a server configuration object. The \*Vserver_name_list\*O argument is a list of names of server configuration objects. This operation returns the UUID of the started server on success. This is the UUID found in the \*Lserverexec\*O object for the server. .PP \*LPrivileges Required\*O .PP You must have \*Lx\*O (\*Lexecute\*O) permission to the configuration object. .PP \*LExamples\*O .PP .oS dcecp> \*Lserver start /.:/hosts/foster/config/srvrconf/try_tserver\*C d90a0374-eb99-11cd-91b1-080009251352 dcecp> .oE .SS "server stop" .PP Stops the specified running server processes. The syntax is as follows: .sS \*Lserver stop \*Vserver_name_list\*O [\*L-method \*Vmethod\*O] .sE .PP \*LOptions\*O .PP .VL .LI "\*L-method \*Vmethod\*L\*O" Optionally specifies how \*Ldced\*O should stop the server. The \*Vmethod\*O must be one of the following: .VL 1i .LI "\*Lrpc\*O" Use \*Lrpc_mgmt_server_stop_listening\*O. This is the default. .LI "\*Lsoft\*O" Use a soft local mechanism, such as \*LSIGTERM\*O. .LI "\*Lhard\*O" Use a hard local mechanism, such as \*LSIGKILL\*O. .LI "\*Lerror\*O" Use a state-preserving mechanism, such as \*LSIGABRT\*O. .LE .LE .PP The \*Lstop\*O operation stops the specified running server processes. The \*Vserver_name_list\*O argument is a list of names of servers. This operation returns an empty string on success. It takes an optional \%\*L-method\*O option to specify how \*Ldced\*O should stop the server. .PP The RPC runtime identifies servers not by name, but by interface, object UUID and endpoints. You should be aware that if you use the \*Lrpc\*O method, the command will be unable to distinguish between two or more server instances binding \*Vwithout\*O endpoints to the same interface and using the same object UUID. In this case, the command will stop a randomly selected server, not necessarily the one named in \*Vserver_name_list\*O. .PP \*LPrivileges Required\*O .PP You must have \*Ls\*O (\*Lstop\*O) permission on the execution object. .PP \*LExamples\*O .PP .oS dcecp> \*Lserver stop /.:/hosts/foster/config/srvrexec/try_tserver \*C dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_account(1m)\*O, \*Ldcecp_acl(1m)\*O, \*Ldcecp_keytab(1m)\*O, \*Ldced(1m)\*O. ...\" \*Ldcecp(1m)\*O, ...\" \*Ldced(1m)\*O, ...\" \*Laccount(1m)\*O, ...\" \*Lacl(1m)\*O, ...\" \*Lkeytab(1m)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" .rm zA .rm zZ .TH user 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lgroup\*O" .iX "user" "DCECP object" .SH NAME .PP \*Luser\*O - A \*Ldcecp\*O task object that manipulates user information in a DCE cell .SH "SYNOPSIS" .sS ...\" .zA "1.1: CR13064" \*Luser create \*Vuser_name_list\*L -mypwd \*Vpassword\*L -password \*Vpassword\*L .nL -group \*Vgroup_name\*L -organization \*Vorganization_name\*O .nL ...\" .zA "def,13377,R1.2.2, clarify syntax" [\*L-force\*O] .nL {\*L-attribute \*Vattribute_list\*O .nL \*L-\*Vattribute value\*O} ...\" .zZ "def,13377,R1.2.2, clarify syntax" ...\" .zZ "1.1: CR13064" .PP ...\" .zA "1.1: CR13064" \*Luser delete \*Vuser_name_list\*O ...\" .zZ "1.1: CR13064" .PP \*Luser help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Luser operations\*O .PP ...\" .zA "1.1: CR13064" \*Luser show \*Vuser_name_list\*O ...\" .zZ "1.1: CR13064" .sE .SH "ARGUMENTS" .VL ...\" .zA "1.1: CR13064" .LI "\*Vuser_name_list\*O" A list of one or more names of principals to act on. Supply the names as follows: .ML .LI Fully qualified principal names in the form: .iS \*L/.../\*Vcell_name\*L/\*Vprincipal_name\*O or \*L/.:/\*Vprincipal_name\*O .iE .LI Cell-relative principal names in the form .iS \*Vprincipal_name\*O .iE These names refer to a principal in the cell identified in the \*L_s(sec)\*O convenience variable, or if the \*L_s(sec)\*O convenience variable is not set, in the local host's default cell. .LE .PP Do not mix fully-qualified names and cell-relative names in a list. In addition, do not use the names of registry database objects that contain principal information; in other words, do not use names that begin with \*L/.:/sec/principal/\*O. .LI "\*Voperation\*O" The name of the \*Luser\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Luser\*O task object represents all of the data associated with a DCE user. This consists of registry information and a Cell Directory Service (CDS) directory in the default implementation. The \*Luser\*O task object allows administrators to easily create, delete and view user information. .PP The \*Luser\*O task object comprises a principal and account in the registry; adds the principal to a group and an organization, creating them if necessary; and a CDS directory named after the principal with the appropriate access control list (ACL). Only the principal and account attributes are considered attributes of the \*Luser\*O task object, and are the only ones displayed by the \*Lshow\*O operation. .PP A principal name is used as the name of user objects. The naming conventions for principal names apply; if no cell name is given it is assumed to be in the current cell. If one is specified, the other cell is contacted. .PP This object is implemented as a script to allow it to be manipulated and extended on a per-site basis. For example, administrators might want to add Global Directory Service (GDS) and Distributed File Service (DFS) information to the object. Other possible modifications include the following: .ML .LI Changing the location of the CDS directory created for users, or remove it completely. .LI Changing the default ACLs placed on the various objects. .LI Setting certain attributes or policies on all newly created principals and accounts to match the site's policies. .LI Setting up site specific defaults for passwords (to be changed by the user later), groups, organizations, principal directories, etc. .LI Supporting a \*Lmodify\*O operation. .LE .SH "ATTRIBUTES" .VL .LI "\*Lalias \*Vvalue\*O" Used with the \*Lcreate\*O operation, the value of this attribute is either \*Lyes\*O or \*Lno\*O. Each principal can have only one name, but may have one or more alias names. All these names refer to the same principal, and therefore the same Universal Unique Identifier (UUID) and user identifier (\*Luid\*O). While aliases refer to the same principal, they are separate entries in the registry database. Therefore the name supplied to a \*Luser\*O command can refer to either the primary name or an alias name of a principal. The value of this attribute determines whether the name is a primary name (\*Lalias no\*O) or an alias name (\*Lalias yes\*O). The default is \*Lno\*O. .LI "\*Lclient \*O{\*Lyes\*O | \*Lno\*O}" A flag set to indicate whether or not the account is for a principal that can act as a client. Possible values are either \*Lyes\*O or \*Lno\*O. If you set this flag to \*Lyes\*O, the principal is able to log into the account and acquire tickets for authentication. The default is \*Lyes\*O. .LI "\*Ldescription \"\*Vtext string\*L\"" A text string (limited to the Portable Character Set or PCS) typically used to describe the use of the account. The default is the empty string (""). .LI "\*Ldupkey \*O{\*Lyes \*O| \*Lno\*O}" A flag set to determine if tickets issued to the account's principal can have duplicate keys. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lno\*O. ...\" .zA "def,13377,R1.2.1,add that attr is advisory" .PP In DCE this attribute is currently only advisory. However, Kerberos clients and servers will make use of it when they interact with a DCE Security server. ...\" .zZ "def,13377,R1.2.1,attr that is advisory" .LI "\*Lexpdate \*VISO_timestamp\*O" The date on which the account expires. To renew the account, change the date in this field. Specify the time by using an ISO compliant time format such as \*VCCYY\*L-\*VMM\*L-\*VDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*O or the string \*Lnone\*O. The default is \*Lnone\*O. .LI "\*Lforwardabletkt \*O{\*Lyes\*O |\*L no\*O}" A flag set to determine whether a new ticket-granting ticket with a network address that differs from the present ticket-granting ticket network address can be issued to the account's principal. The \*Lproxiabletkt\*O attribute performs the same function for service tickets. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lyes\*O. ...\" .zA "def,13377,R1.2.1,add that attr is advisory" .PP In DCE this attribute is currently only advisory. However, Kerberos clients and servers will make use of it when they interact with a DCE Security server. ...\" .zZ "def,13377,R1.2.1,attr that is advisory" .LI "\*Lfullname \*Vstring\*O" Used with the \*Lcreate\*O operation, this specifies the full name of the principal, it is for information purposes only. It typically describes or expands a primary name to allow easy recognition by users. For example, a principal could have a primary name of \*Ljsbach\*O and a full name of \*LJohann S. Bach\*O. The value is a string. If it contains spaces, it is displayed in quotes, and on entry must be in quotes or braces (as per Tcl quoting rules). If not entered, the full name defaults to the null string (that is, blank). .LI "\*Lforce\*O" Force creation of the specified group or organization if they do not exist. .LI "\*Lgroup \*Vgroup_name\*O" The name of the group associated with the account. The value is a single group name of an existing group in the registry. This attribute must be specified for the \*Luser create\*O command; it does not have a default value. .PP If a group is deleted from the registry, all accounts associated with the group are also deleted. .LI "\*Lhome \*Vdirectory_name\*O" The file system directory in which the principal is placed in at login. The default is \*L/\*O. .LI "\*Lorganization \*Vorganization_name\*O" The name of the organization associated with the account. The value is a single organization name of an existing organization in the registry. This attribute must be specified for the \*Laccount create\*O command; it does not have a default value. .PP If an organization is deleted from the registry, all accounts associated with the organization are also deleted. .LI "\*Lmaxtktlife \*Vrelative_time\*O" The maximum amount of time that a ticket can be valid. Specify the time by using the Distributed Time Service (DTS) relative time format (\*L[-]\*VDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*O). When a client requests a ticket to a server, the lifetime granted to the ticket takes into account the \*Lmaxtktlife\*O set for both the server and the client. In other words, the lifetime cannot exceed the shorter of the server's or client's \*Lmaxtktlife\*O. If you do not specify a \*Lmaxtktlife\*O for an account, the \*Lmaxtktlife\*O defined as registry authorization policy is used. .LI "\*Lmaxtktrenew \*Vrelative_time\*O" The amount of time before a principal's ticket-granting ticket expires and that principal must log in again to the system to reauthenticate and obtain another ticket-granting ticket. Specify the time by using the DTS relative time format (\*L[-]\*VDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*O). The lifetime of the principal's service tickets can never exceed the lifetime of the principal's ticket-granting ticket. The shorter you make this, the greater the security of the system. However, since principals must log in again to renew their ticket-granting ticket, the time needs to take into consideration user convenience and the level of security required. If you do not specify this for an account, the \*Lmaxtktrenew\*O lifetime defined as registry authorization policy is used. .LI "\*Lmypwd \*Vpassword\*O" Lets you enter your password. You must enter your password to create an account. This check prevents a malicious user from using an existing privileged session to create unauthorized accounts. .LI "\*Lpassword \*Vpassword\*O" The password of the account. This attribute must be specified for the \*Luser create\*O command; there is no default value. This attribute is not returned by a \*Luser show\*O command. .LI "\*Lpostdatedtkt \*O{\*Lyes\*O | \*Lno\*O}" A flag set to determine if tickets with a start time some time in the future can be issued to the account's principal. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lno\*O. .PP ...\" .zA "def,13377,R1.2.1,added that attr is advisory" In DCE this attribute is currently only advisory. However, Kerberos clients and servers will make use of it when they interact with a DCE Security server. ...\" .zZ "def,13377,R1.2.1,added that attr is advisory" .LI "\*Lproxiabletkt \*O{\*Lyes \*O|\*L no\*O}" A flag set to determine whether or not a new ticket with a different network address than the present ticket can be issued to the account's principal. The \*Lforwardabletkt\*O attribute performs the same function for ticket-granting tickets. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lno\*O. .PP ...\" .zA "def,13377,R1.2.1,added that attr is advisory" In DCE this attribute is currently only advisory. However, Kerberos clients and servers will make use of it when they interact with a DCE Security server. ...\" .zZ "def,13377,R1.2.1,added that attr is advisory" .LI "\*Lpwdvalid \*O{\*Lyes \*O| \*Lno\*O}" A flag set to determine whether the current password is valid. If this flag is set to \*Lno\*O, the next time a principal logs in to the account, the system prompts the principal to change the password. (Note that this flag is separate from the \*Lpwdexpdate\*O policy, which sets time limits on password validity.) Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lyes\*O. .LI "\*Lrenewabletkt \*O{\*Lyes\*O | \*Lno\*O}" A flag set to determine if the ticket-granting ticket issued to the account's principal can be renewed. If this flag is set to \*Lyes\*O, the authentication service renews the ticket-granting ticket if its lifetime is valid. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lyes\*O. .PP ...\" .zA "def,13377,R1.2.1,added that attr is advisory" In DCE this attribute is currently only advisory. However, Kerberos clients and servers will make use of it when they interact with a DCE Security server. ...\" .zZ "def,13377,R1.2.1,added that attr is advisory" .LI "\*Lserver \*O{\*Lyes\*O | \*Lno\*O}" A flag set to indicate whether or not the account is for a principal that can act as a server. If the account is for a server that engages in authenticated communications, set this flag to \*Lyes\*O. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lyes\*O. .LI "\*Lshell \*Vpath_to_shell\*O" The path of the shell that is executed when a principal logs in. The legal value is any shell supported by the home cell. The default value is the empty string (""). .LI "\*Lstdtgtauth \*O{\*Lyes \*O| \*Lno\*O}" A flag set to determine whether or not service tickets issued to the account's principal use the standard DCE ticket-granting ticket authentication mechanism. Possible values are either \*Lyes\*O or \*Lno\*O. The default is \*Lyes\*O. .LI "\*Luid \*Vvalue\*O" Used with the \*Lcreate\*O operation, this specifies the user identifier (\*Luid\*O) for the principal. No two principals can have the same \*Luid\*O. However, aliases can share one \*Luid\*O. It is often called the Unix ID and is an integer. If this attribute is not supplied, a UID is assigned to principal automatically. .LE .PP ...\" See the \*(Ag for more information about principal and account attributes. See the \*VOSF DCE Administration Guide\*O for more information about principal and account attributes. .SH "OPERATIONS" .SS "user create" .PP Creates a principal name, an account, and a directory in CDS for one or more DCE users. The syntax is as follows: ...\" .zA "1.1: CR13064" .sS \*Luser create \*Vuser_name_list\*L -mypwd \*Vpassword\*L -password \*Vpassword\*L .nL -group \*Vgroup_name\*L -organization \*Vorganization_name\*O .nL ...\" .zA "def,13377,R1.2.2, clarify syntax" [\*L-force\*O] .nL {\*L-attribute \*Vattribute_list\*O | .nL \*L-\*Vattribute value\*O} ...\" .zZ "def,13377,R1.2.2, clarify syntax" .sE ...\" .zZ "1.1: CR13064" .PP \*LOptions\*O .VL .LI "\*L-\*Vattribute value\*O" As an alternative to using the \*L-attribute\*O option with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. .LI "\*L-attribute \*Vattribute_list\*O" Allows you to specify attributes, including ERAs, by using an attribute list rather than using the \*L-\*Vattribute value\*O option. The format of an attribute list is as follows: .iS {{\*Vattribute \*Vvalue\*O}...{\*Vattribute \*Vvalue\*O}} .iE .LI "\*L-force\*O" Forces creation of the specified group or organization if they do not exist. .LI "\*L-group \*Vgroup_name\*O" The name of the group to associate with the account. See \*LATTRIBUTES\*O for the format of a group name. .LI "\*L-mypwd \*Vpassword\*O" Your privileged password. You must enter your privileged password to create an account. This check prevents a malicious user from using an existing privileged session to create unauthorized accounts. You must specify this option on the command line; it cannot be supplied in a script. .LI "\*L-organization \*Vorganization_name\*O" The name of the organization to associate with the account. See \*LATTRIBUTES\*O for the format of an organization name. .LI "\*L-password \*Vpassword\*O" The account password. See \*LATTRIBUTES\*O for the format of a password. .LE .PP The \*Lcreate\*O operation creates a principal name, account, and a directory in CDS for one or more DCE users. The \*Vuser_name_list\*O argument is the name of one or more principals to be added to the registry. This operation returns an empty string on success. If the operation encounters an error, it attempts to undo any interim operations that have completed. .PP This command creates one or more principals and accounts for them. If a principal or account already exists, an error is generated. Each principal is then added to the specified group and organization (since the principal has just been created, it can't already have been a member of any group or organization). If the group or organization does not exist, an error is generated unless the \%\*L-force\*O option is used. The operation creates a CDS directory called \*L/.:/users/\*Vprincipalname\*O and adds an ACL entry to the default ACL so that the user has \*Lrwtci\*O permissions on the directory. This allows all access except for deleting the directory and administering replication on the directory. .PP Attributes and policies for the newly created principal and account may be specified with the \%\*L-attributes\*O option and specifying an attribute list as the value, or with attribute options. This command will attempt to add any unknown attributes as ERAs on the created principal object. Policies of the organization may not be specified as these would probably affect more than just the created user. The required group and organization names may be specified either as attributes in the \%\*L-attributes\*O option, or via the \*L-group\*O and \*L-organization\*O options. The required \*Lpassword\*O attribute may be provided as in the \*Laccount create\*O command, and the \%\*L-mypwd\*O option is also required. .PP \*LPrivileges Required\*O .PP Because the \*Luser create\*O command performs several operations you need the permissions associated with each operation, as follows: .ML .LI To create the principal name, you must have \*Li\*O (\*Linsert\*O) permission to the directory in which the principal is to be created. .LI If the specified groups or organizations do not already exist and you use the \%\*L-force\*O option, you must have \*Li\*O (\*Linsert\*O) permission to the directories in which the groups and organizations are to be created. .LI To create the account, you must have \*Lm\*O (\*Lmgmt_info\*O), \*La\*O (\*Lauth_info\*O), and \*Lu\*O (\*Luser_info\*O) permission to the principal named in the account, \*Lr\*O (\*Lread\*O) permission to the organization named in the account, \*Lr\*O (\*Lread\*O) permission to the group named in the account, and \*Lr\*O (\*Lread\*O) permission on the registry policy object. .LI To create the directory in CDS you must have the following permissions: .ML .LI \*Lr\*O (\*Lread\*O) and \*Li\*O (\*Linsert\*O) permission to the parent directory .LI \*Lw\*O (\*Lwrite\*O) permission to the clearinghouse in which the master replica of the new directory is to be stored. .LE .LE .PP \*LExamples\*O .PP The following example creates a principal named \*LK_Parsons\*O and adds him to a group named \*Lusers\*O and an organization named \*Lusers\*O: .oS dcecp> \*Luser create K_Parsons -mypwd 3kl_JL2 -password change.me \\\*C > \*L-group users -organization users \*C dcecp> \*Lgroup list users\*C /.../my_cell.goodco.com/W_Ross /.../my_cell.goodco.com/J_Severance /.../my_cell.goodco.com/J_Hunter /.../my_cell.goodco.com/B_Carr /.../my_cell.goodco.com/E_Vliet /.../my_cell.goodco.com/J_Egan /.../my_cell.goodco.com/F_Willis /.../my_cell.goodco.com/K_Parsons dcecp> dcecp> \*Laccount show K_Parsons\*C {acctvalid yes} {client yes} {created /.../my_cell.goodco.com/cell_admin 1994-07-27-13:02:51.000+00:00I-----} {description {}} {dupkey no} {expdate none} {forwardabletkt yes} {goodsince 1994-07-27-13:02:51.000+00:00I-----} {group users} {home /} {lastchange /.../my_cell.goodco.com/cell_admin 1994-07-27-13:02:51.000+00:00I-----} {organization users} {postdatedtkt no} {proxiabletkt no} {pwdvalid yes} {renewabletkt yes} {server yes} {shell {}} {stdtgtauth yes} dcecp> .oE .SS "user delete" .PP ...\" .zA "1.1: CR13064" Deletes DCE users. The syntax is as follows: .sS \*Luser delete \*Vuser_name_list\*O .sE ...\" .zZ "1.1: CR13064" .PP The \*Ldelete\*O operation deletes the DCE users named in \*Vuser_name_list\*O. To delete a user, the operation: .ML .LI Deletes the principal from the registry, which also deletes the account and removes the principal from any groups and organizations. .LI Deletes the \*L/.:/users/\*Vprincipalname\*O directory and any contents. .LE This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP Because the \*Luser delete\*O command performs several operations, you need the permissions associated with each operation, as follows: .ML .LI You must have \*Ld\*O (\*Ldelete\*O) permission to the directory in which the target principal exists. You must have \*Lr\*O (\*Lread\*O) and \*LD\*O (\*LDelete_object\*O) permission on the principal to be deleted. .LI You must have \*Lr\*O (\*Lread\*O) and \*LM\*O (\*LMember_list\*O) permission on the target groups and organizations and \*Lr\*O (\*Lread\*O) permission on the member to be removed. .LI To delete the account, you must have \*Lr\*O (\*Lread\*O) , \*Lm\*O (\*Lmgmt_info\*O), \*La\*O (\*Lauth_info\*O), and \*Lu\*O (\*Luser_info\*O) permissions for the principal named in the account. .LI To delete the directory in CDS you must have \*Ld\*O (\*Ldelete\*O) permission to the directory and \*Lw\*O (\*Lwrite\*O) permission to the clearinghouse that stores the master replica of the directory. The server principal needs \*La\*O (\*Lauth_info\*O) permission to the parent directory or \*Ld\*O (\*Ldelete\*O) permission to the child pointer that points to the directory you intend to delete. .LE .PP \*LExamples\*O .PP The following example deletes user \*LK_Parsons\*O from the cell: .oS dcecp> \*Luser delete K_Parsons\*C dcecp> .oE .SS "user help" .PP Returns help information about the \*Luser\*O task object and its operations. The syntax is as follows: .sS \*Luser help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Luser\*O task object. .LE .PP Used without an argument or option, the \*Luser help\*O command returns brief information about each \*Luser\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Luser\*O task object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Luser help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Luser help\*C create Creates a DCE user. delete Deletes a DCE user. show Shows the attributes of a DCE user. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "user operations" .PP Returns a list of the operations supported by the \*Luser\*O task object. The syntax is as follows: .sS \*Luser operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Luser operations\*O command. .PP \*LExamples\*O .PP .oS \*Cdcecp> \*Luser operations\*C create delete show help operations dcecp> .oE .SS "user show" Returns the attributes of a single DCE user. The syntax is as follows: ...\" .zA "1.1: CR13064" .sS \*Luser show \*Vuser_name_list\*O .sE ...\" .zZ "1.1: CR13064" .PP The \*Lshow\*O operation returns the attributes of the users named in \*Vuser_name_list\*O. The information returned includes principal attributes, account attributes, and policies. The information is returned as if the following commands were run in the following order: .oS principal show account show -all .oE .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the principal named in the account. .PP \*LExamples\*O .PP .oS dcecp> \*Luser show K_Parsons \*C {fullname {}} {uid 5129} {uuid 00001409-a943-21cd-be00-0000c08adf56} {alias no} {quota unlimited} {groups users} {acctvalid yes} {client yes} {created /.../my_cell.goodco.com/cell_admin 1994-07-27-13:02:51.000+00:00I-----} {description {}} {dupkey no} {expdate none} {forwardabletkt yes} {goodsince 1994-07-27-13:02:51.000+00:00I-----} {group users} {home /} {lastchange /.../my_cell.goodco.com/cell_admin 1994-07-27-13:02:51.000+00:00I-----} {organization users} {postdatedtkt no} {proxiabletkt no} {pwdvalid yes} {renewabletkt yes} {server yes} {shell {}} {stdtgtauth yes} nopolicy dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_account(1m)\*O, \*Ldcecp_directory(1m)\*O, \*Ldcecp_group(1m)\*O, \*Ldcecp_organization(1m)\*O, \*Ldcecp_principal(1m)\*O, \*Ldcecp_xattrschema(1m)\*O. ...\" \*Laccount(1m)\*O, ...\" \*Ldcecp(1m)\*O, ...\" \*Ldirectory(1m)\*O, ...\" \*Lgroup(1m)\*O, ...\" \*Lorganization(1m)\*O, ...\" \*Lprincipal(1m)\*O, ...\" \*Lxattrschema(1m)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" .rm zA .rm zZ .TH utc 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lutc\*O" .iX "utc" "administering" .SH NAME .PP \*Lutc\*O - A \*Ldcecp\*O object that manipulates UTC timestamps .SH "SYNOPSIS" .sS \*Lutc add \*Vtimestamp \*Vrelative_timestamp\*O .PP \*Lutc compare \*Vabsolute_timestamp absolute_timestamp\*O [\*L-noinaccuracy\*O] .PP \*Lutc convert \*Vabsolute_timestamp\*O [\*L-gmt\*O] .PP \*Lutc help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lutc multiply \*Vrelative_timestamp \*O{\*Vinteger\*O | \*Vfloating_point_factor\*O} .PP \*Lutc operations\*O .PP \*Lutc subtract \*Vtimestamp timestamp\*O .sE .SH "ARGUMENTS" .VL .LI "\*Vabsolute_timestamp\*O" An International Organization for Standardization (ISO) compliant time format of the following form: .iS \*VCCYY\*L-\*VMMDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*L.\*Vfff\*O[\*L+\*O|\*L-\*O]\*Vhh\*L:\*VmmIsss\*L.\*Vfff .iE The Time Differential Factor (TDF) component [\*L+\*O|\*L-\*O]\*Vhh\*L.\*Vmm\*O, if present, indicates the offset from Universal Time Coordinated (UTC) time and implies local system time. The inaccuracy component \*VIss\*L.\*Vfff\*O, if present, specifies the duration of the time interval that contains the absolute time. .LI "\*Vfloating_point_factor\*O" A floating point number such as 53.234. .LI "\*Vinteger\*O" A whole number such as 79. .LI "\*Voperation\*O" The name of the \*Lutc\*O operation for which to display help information. .LI "\*Vrelative_timestamp\*O" A Distributed Time Service (DTS) timestamp of the following form: .iS [-]\*VDD\*L-\*Vhh\*L:\*Vmm\*L:\*Vss\*L.\*VfffIss\*L.\*Vfff .iE Relative times often omit fractions of seconds (the leftmost \*V.fff\*O sequence) and generally lack an inaccuracy component (\*VIss.fff\*O). For example, a relative time of 21 days, 8 hours, and 15 minutes is expressed as 21-08:15:00. .LI "\*Vtimestamp\*O" A \*Lutc\*O timestamp that can be a relative or absolute time. See the \*Vrelative_timestamp\*O and \*Vabsolute_timestamp\*O argument descriptions for the format of these timestamps. .LE .SH "DESCRIPTION" .PP The \*Lutc\*O object lets you add, compare, and convert timestamps in DTS and ISO formats. .SH "OPERATIONS" .SS "utc add" .PP Adds two timestamps. The syntax is as follows: .sS \*Lutc add \*Vtimestamp\*O \*Vrelative_timestamp\*O .sE .PP The \*Ladd\*O operation returns the sum of two timestamps. The timestamps can be two relative times or an absolute time and a relative time. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lutc add\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lutc add 1994-10-18-13:21:50.419-04:00I----- +0-00:02:00.000I----- \*C 1994-10-18-13:23:50.419-04:00I----- dcecp> .oE .SS "utc compare" .PP Compares two absolute timestamps indicating the temporal order. The syntax is as follows: .sS \*Lutc compare \*Vabsolute_timestamp absolute_timestamp\*O [\*L-noinaccuracy\*O] .sE .PP The \*Lcompare\*O operation compares two timestamps and returns \*L-1\*O if the first is earlier, \*L1\*O if the second is earlier, and \*L0\*O if the difference is indeterminate. Specify the \%\*L-noinaccuracy\*O option to ignore inaccuracies in comparisons; in this case a return of \*L0\*O indicates the times are the same. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lutc compare\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lutc compare 1994-10-18-13:22:32.816-04:00I----- \\ \*C> \*L1994-10-18-13:21:50.419-04:00I----- -noinaccuracy\*C 1 dcecp> .oE .SS "utc convert" .PP Converts a timestamp from UTC to local time. The syntax is as follows: .sS \*Lutc convert \*Vabsolute_timestamp\*O [\*L-gmt\*O] .sE .PP The \*Lconvert\*O operation accepts a timestamp and returns another timestamp that expresses the same time in the local timezone. If called with the \*L-gmt\*O option it returns a Greenwich mean time (GMT) formatted timestamp. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lutc convert\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lutc convert 1994-10-18-13:22:32.816-00:00I-----\*C 1994-10-18-09:22:32.816-04:00I----- dcecp> .oE .SS "utc help" .PP Returns help information about the \*Lutc\*O object and its operations. The syntax is as follows: .sS \*Lutc help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lutc\*O object. .LE .PP Used without an argument or option, the \*Lutc help\*O command returns brief information about each \*Lutc\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lutc\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lutc help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lutc help\*C add Adds a relative and absolute, or two relative, timestamps. compare Compares two timestamps to determine which is earlier. convert Converts a timestamp into the local timezone or GMT. multiply Multiplies a relative timestamp by a number. subtract Returns the difference between two timestamps. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "utc multiply" .PP Multiplies a relative time (a length of time) by an integer or floating point factor. The syntax is as follows: .sS \*Lutc multiply \*Vrelative_timestamp\*O {\*Vinteger\*O | \*Vfloating_point_factor\*O} .sE .PP The \*Lmultiply\*O operation accepts two arguments: a relative timestamp and an integer or floating point factor. It multiplies the length of time (specified by the relative timestamp) by the integer or floating point factor, returning the product as a relative timestamp. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lutc multiply\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lutc multiply +0-00:00:05.000I----- 3\*C +0-00:00:15.000I----- dcecp> .oE .SS "utc operations" .PP Returns a list of the operations supported by the \*Lutc\*O object. The syntax is as follows: .sS \*Lutc operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lutc operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lutc operations\*C add compare convert multiply subtract help operations dcecp> .oE .SS "utc subtract" .PP Subtracts one timestamp from another, returning the difference as a relative timestamp. The syntax is as follows: .sS \*Lutc subtract \*Vtimestamp timestamp\*O .sE .PP The \*Lsubtract\*O operation returns the difference between two timestamps that express either an absolute time and a relative time, two relative times, or two absolute times. The return value is a relative timestamp. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lutc subtract\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lutc subtract 1994-10-18-13:22:32.816-00:00I----- +0-00:00:15.000I-----\*C 1994-10-18-13:22:17.816+00:00I----- dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, \*Ldcecp_clock(1m)\*O, \*Ldcecp_dts(1m)\*O, \*Ldts_intro(1m)\*O, \*Ldtsd(1m)\*O. ...\" \*Lclock(1m)\*O, ...\" \*Ldcecp(1m)\*O, ...\" \*Ldts(1m)\*O, ...\" \*Ldts_intro(1m)\*O, ...\" \*Ldtsd(1m)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" .rm zA .rm zZ .TH uuid 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp(\\)(\.)\*O commands" "\*Luuid\*O" .iX "uuid" "administering" .SH NAME .PP \*Luuid\*O - A \*Ldcecp\*O object that generates and compares UUIDs .SH "SYNOPSIS" .sS \*Luuid compare \*Vuuid uuid\*O .PP \*Luuid create\*O .PP \*Luuid help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Luuid operations\*O .sE .SH "ARGUMENTS" .VL .LI "\*Vuuid\*O" A UUID in the following form: .oS C069d9fb6-943e-11cd-a35c-0000c08adf56 .oE .LI "\*Voperation\*O" The name of the \*Luuid\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Luuid\*O object generates and compares Universal Unique Identifiers (UUIDs). UUIDs uniquely identify DCE entities such as principals, RPC entries, Cell Directory Service (CDS) replicas, and so on. .SH "OPERATIONS" .SS "uuid compare" .PP Compares two UUIDs. The syntax is as follows: .sS \*Luuid compare \*Vuuid uuid\*O .sE .PP The \*Lcompare\*O operation compares two UUIDs, returning \*L1\*O if they are equal or \*L0\*O if they are not. ...\" .zA "def,13377,R1.2.2,clarify wording" Because the \*Luuid compare\*O command handles the comparison of UUIDs in current and previous DCE formats, you should use it rather than \*Lstring compare\*O. ...\" .zZ "def,13377,R1.2.2,clarify wording" .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Luuid compare\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Luuid compare 03bb2688-943e-11cd-8bfd-0000c08adf56 \\ > \*L069d9fb6-943e-11cd-a35c-0000c08adf56\*C 0 dcecp> .oE .SS "uuid create" .PP Returns a newly generated UUID. The syntax is as follows: .sS \*Luuid create\*O .sE .PP The \*Lcreate\*O operation returns a newly generated UUID. It takes no arguments. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Luuid create\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Luuid create\*C 03bb2688-943e-11cd-8bfd-0000c08adf56 dcecp> .oE .SS "uuid help" .PP Returns help information about the \*Luuid\*O object and its operations. The syntax is as follows: .sS \*Luuid help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Luuid\*O object. .LE .PP Used without an argument or option, the \*Luuid help\*O command returns brief information about each \*Luuid\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Luuid\*O object itself. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Luuid help\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Luuid help\*C compare Compares two UUID's for equality. create Returns a newly generated UUID. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "uuid operations" .PP Returns a list of the operations supported by the \*Luuid\*O object. The syntax is as follows: .sS \*Luuid operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Luuid operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Luuid operations\*C compare create help operations dcecp> .oE .SH "RELATED INFORMATION" .PP Commands: .ad l \*Ldcecp(1m)\*O, ...\" \*Lendpoint(1m)\*O. \*Ldcecp_endpoint(1m)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH xattrschema 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldcecp\*O commands" "\*Lxattrschema\*O" .iX "xattrschema" "administering" .iX "schema" "administering" .SH NAME .PP \*Lxattrschema\*O - A DCE control program object that manages schema information for ERAs .SH "SYNOPSIS" .sS \*Lxattrschema catalog \*Vschema_name\*L\*O [\*L-simplename\*O] .PP \*Lxattrschema create \*Vschema_entry_name_list\*O .nL {\*L-attribute \*Vattribute_list\*O | .nL \*L-\*Vattribute \*Vvalue\*O} .PP \*Lxattrschema delete \*Vschema_entry_name_list\*O .PP \*Lxattrschema help \*O[\*Voperation\*O | \*L-verbose\*O] .PP \*Lxattrschema modify \*Vschema_entry_name_list\*O .nL {\*L-change \*Vattribute_list\*O | .nL \*L-\*Vattribute \*Vvalue\*O} .PP \*Lxattrschema operations\*O .PP \*Lxattrschema rename \*Vschema_entry_name\*L -to \*Vnew_schema_entry_name\*L .PP \*Lxattrschema show \*Vschema_entry_name_list\*O .sE .SH "ARGUMENTS" .VL .LI "\*Vschema_name\*O The name of the schema that defines the schema entry types named in \*Vschema_entry_name_list\*O. The two following schemas are currently supported: .iS /.../\*Vcell_name\*O/sec/xattrschema\*O .iE .iS /.../\*Vcell_name\*O/hosts/\*Vhost_name\*O/config/xattrschema\*O .iE .LI "\*Vschema_entry_name\*O" The name of a schema entry type to be renamed. .LI "\*Vschema_entry_name_list\*O A list of one or more schema entry types to act on. .LI "\*Voperation\*O" The name of the \*Lxattrschema\*O operation for which to display help information. .LE .SH "DESCRIPTION" .PP The \*Lxattrschema\*O object represents the schema information for an extended registry attribute (ERA). This command manipulates the schema type that defines ERAs. Schema types are identified by name. Other \*Ldcecp\*O commands manipulate individual instances of ERAs. ERA instances are an attribute of a given schema type that has been attached to an object and assigned a value. .PP You can attach ERAs to principal, group, and organizations objects and to server configuration and server execution objects supported by \*Ldced\*O. .PP ERA entry types for principal, group, and organizations objects have the following default name: .iS /.:/sec/xattrschema/\*Vschema_entry_name .iE .PP ERA types for \*Ldced\*O server objects have the following name: .iS /.:/hosts/\*Vhostname\*L/config/xattrschema/\*Vschema_entry_name .iE .PP ERA types are defined to be attached to only those objects supported by specified access control list (ACL) managers. .nL .ne 6 .SH "ATTRIBUTES" .VL .5i .LI "\*Laclmgr \*Vdescription\*O" A set that lists the ACL managers that support the object types on which ERAs of this type can be created. For each ACL manager type, the permissions required for attribute operations are also specified. Each ACL manager is described with a list, in the following format: .iS {\*Vuuid queryset updateset testset deleteset\*L} .iE .P where the first element is the Universal Unique Identifier (UUID) of the ACL manager, and the rest are the sets of permissions (concatenated permission strings as found in an ACL) required to perform each type of operation. The value of this attribute is actually a list of these lists. For example: .oS {8680f026-2642-11cd-9a43-080009251352 r w t D} {18dbdad2-23df-11cd-82d4-080009251352 r w t mD} .oE .P This attribute is modifiable after creation, but only in a limited way. New ACL managers can be added, but existing ones cannot be removed or changed. This attribute must be specified on creation. .LI "\*Lannotation \*Vstring\*O" This is a comment field used to store information about the schema entry. It is a Portable Character Set (PCS) string. ...\" .zA "def,13377,R1.2.1,add default" The default is an empty string (that is, blank). ...\" .zZ "def,13377,R1.2.1,add default" .LI "\*Lapplydefs \*O{\*Lyes\*O | \*Lno\*O}" Indicates that if this ERA doesn't exist for a given object on an attribute query, the system-defined default value (if any) for this attribute will be returned. If set to \*Lno\*O, an attribute query will return an attribute instance only if it exists on the object named in the query. The possible values are either \*Lyes\*O or \*Lno\*O. This attribute is only advisory in DCE Version 1.1. Future versions of DCE will support this functionality. ...\" .zA "def,13377,R1.2.1,add default" The default is \*Lno\*O. ...\" .zZ "def,13377,R1.2.1,add default" .LI "\*Lencoding \*Vtype\*O" The type of the ERA. This attribute is not modifiable after creation, and must be specified on creation. Legal values are one of the following: .VL .LI "\*Lany\*O" The value of the ERA can take on any encoding. This encoding type is only legal for the definition of an ERA in a schema entry. All instances of an ERA must have an encoding of some other value. .LI "\*Lattrset\*O" The value of the ERA is a list of attribute type UUIDs used to retrieve multiple related attributes by specifying a single attribute type on a query. .LI "\*Lbinding\*O" The value of the ERA contains authentication, authorization and binding information suitable for communicating with a DCE server. The syntax is a list of two elements. .PP The first element is a list of security information where the first element is the authentication type, either \*Lnone\*O or \*Ldce\*O, followed by information specific for each type. The type \*Lnone\*O has no further info. The type \*Ldce\*O is followed by a principal name, a protection level (one of \*Ldefault\*O, \*Lnone\*O, \*Lconnect\*O, \*Lcall\*O, \*Lpkt\*O, \*Lpktinteg\*O, or \*Lpktprivacy\*O), an authentication service (one of \*Ldefault\*O, \*Lnone\*O, or \*Lsecret\*O), and an authorization service (one of \*Lnone\*O, \*Lname\*O, or \*Ldce\*O). Examples of three security information lists are as follows: .ne 6 .oS {none} {dce /.:/melman default default dce} {dce /.:/melman pktprivacy secret dce} .oE .P The second element is a list of binding information, where binding information can be string bindings or server entry names. Two examples of binding information are as follows: .oS {/.:/hosts/\*Vhostname\*C/dce-entity /.:/subsys/dce/sec/master} {ncadg_ip_udp:130.105.96.3 ncadg_ip_udp:130.105.96.6} .oE .LI "\*Lbyte\*O" The value of the ERA is a string of bytes. The byte string is assumed to be \*Lpickle\*O or is otherwise a self-describing type. .PP It is unlikely that attributes of this type will be entered manually. The format of output is hex bytes separated by spaces with 20 bytes per line. For example, the input attribute name \*Lbindata\*O might produce the following output: .oS {bindata {00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 10 11 12 13 22 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f 12 11 12 13}} .oE The braces indicate that \*Lbindata\*O has one value. On input all whitespace is compressed so that users can enter the data as bytes or words or any combination, whichever is more convenient. Therefore a user could enter the following: .iS {bindata {00010203 0405 06070809 0a0b 0c0d0e0f 10111213 22212223 2425 26272829 2a2b 2c2d2e2f 12111213}} .iE ...\" .cS ...\" .LI "\*Lconfidential\*O" ...\" The value of the ERA is a string of bytes encrypted under the key of the ...\" principal to which this attribute is attached. Like a plaintext byte ...\" string this is assumed to be a self describing type. This encoding type is ...\" only useful for an attribute instance attached to a principal object where ...\" it will be decrypted and reencrypted every time the password associated ...\" with the node is changed. ...\" .PP ...\" Although it is unlikely that administrators will enter attributes of ...\" this type manually, the DCE control program does support entering ...\" binary data via the following notations: \*V\\ddd\*O where \*Vddd\*O ...\" can be one, two, or three octal digits, and \\x\*Vhh\*O where \*Vhh\*O ...\" can be any number of hex digits. ...\" .cE .LI "\*Li18ndata\*O" The value of the ERA is a string of bytes with a tag identifying the (OSF registered) codeset used to encode the data. .PP Although it is unlikely that administrators will enter attributes of this type manually, the DCE control program does support entering binary data via the following notations: \*V\\ddd\*O where \*Vddd\*O can be one, two, or three octal digits, and \\x\*Vhh\*O where \*Vhh\*O can be any number of hex digits. .LI "\*Linteger\*O" The value of the ERA is a signed 32 bit integer. .LI "\*Lprintstring\*O" The value of the ERA is a printable Interface Definition Language (IDL) character string using PCS. .LI "\*Lstringarray\*O" An array of PCS strings; represented as a Tcl list of strings. .LI "\*Luuid\*O" The value of the ERA is a UUID. .LI "\*Lvoid\*O" The ERA has no value. It is simply a marker that is either present or absent. .LE .LI "\*Lintercell \*Vvalue\*O" Specifies the action that should be taken by the privilege server when reading ERAs from a foreign cell. Possible values are as follows: .VL .LI "\*Laccept\*O" Accepts ERAs from foreign cells. The only check applied is uniqueness if indicated by the \*Lunique\*O attribute. .LI "\*Lreject\*O" Discards ERAs from foreign cells. .LI "\*Levaluate\*O" Invokes a trigger function to a server that would decide whether the ERA should be kept, discarded or mapped to another value. .LE ...\" .zA "def,13377,R1.2.1,add default" The default is \*Lreject\*O. ...\" .zZ "def,13377,R1.2.1,add default" .PP This attribute is only advisory in DCE Version 1.1. Future versions of DCE will support this functionality. .LI "\*Lmultivalued \*O{\*Lyes\*O | \*Lno\*O}" Indicates that ERAs of this type may be multivalued (that is, multiple instances of the same attribute type may be attached to a single registry object). The possible values are either \*Lyes\*O or \*Lno\*O. This attribute is not modifiable after creation. ...\" .zA "def,13377,R1.2.1,add default" The default is \*Lno\*O. ...\" .zZ "def,13377,R1.2.1,add default" .LI "\*Lreserved \*O{\*Lyes \*O|\*L no\*O}" If set then this schema entry may not be deleted through any interface by any user. The possible values are either \*Lyes\*O or \*Lno\*O. ...\" .zA "def,13377,R1.2.1,add default" The default is \*Lno\*O. ...\" .zZ "def,13377,R1.2.1,add default" ...\" .zA "def,13293,R1.2.1,amplify explanation" .LI "\*Lscope \*Vstring\*O" Indicates the name of a security directory or object in the registry. If it is an object, then only that object may have instances of this ERA attached to them. If it is a directory, then only descendants of this directory may have instances of this ERA attached to them. The default is an empty string which does not limit which objects ERAs may be attached to. For example, if this attribute is set to \*Lprincipal/org/dce\*O only principals with a prefix of \*Lorg/dce\*O in the name may have this type of ERA. You cannot modify this attribute after it is created. ...\" .zA "def,13377,R1.2.1,add default" The default is the empty string (that is, blank). ...\" .zZ "def,13377,R1.2.1,add default" .PP This attribute is only advisory in DCE Version 1.1. Future versions of DCE will support this functionality. ...\" .zZ "def,13293,R1.2.1,amplify explanation" .LI "\*Ltrigtype \*Vtype\*O" Identifies if there is a trigger and if so what type it is. The possible values are one of: \*Lnone\*O, \*Lquery\*O, or \*Lupdate\*O. If this attribute is anything other than \*Lnone\*O, then \*Ltrigbind\*O must be set. This attribute is not modifiable after creation. ...\" .zA "def,13377,R1.2.1,add default" The default is \*Lnone\*O. ...\" .zZ "def,13377,R1.2.1,add default" .LI "\*Ltrigbind \*Vbinding\*O" Contains binding information for the server that will support the trigger operations. This field must be set if \*Ltrigtype\*O is not \*Lnone\*O or if \*Lintercell\*O is set to \*Levaluate\*O. The value of this attribute is of the format described by the \*Lbinding\*O encoding type. ...\" .zA "def,13377,R1.2.1,add default" The default is the empty string (that is, blank). ...\" .zZ "def,13377,R1.2.1,add default" .LI "\*Lunique \*O{\*Lyes \*O| \*Lno\*O}" Indicates that each instance of the ERA must have a unique value within the cell for a particular object type (for instance, principal). The possible values are either \*Lyes\*O or \*Lno\*O. This attribute is not modifiable after creation. ...\" .zA "def,13377,R1.2.1,add default" The default is \*Lno\*O. ...\" .zZ "def,13377,R1.2.1,add default" .PP This attribute is only advisory in DCE Version 1.1. Future versions of DCE will support this functionality. .LI "\*Luuid \*Vuuid\*O" The internal identifier of the ERA. The value is a UUID. This attribute is not modifiable after creation. If not specified on the \*Lcreate\*O operation, a value is generated by the system. .LE .PP See the \*VOSF DCE Administration Guide\*O for more information about \*Lxattrschema\*O attributes. ...\" See the \*(Ag for more information about \*Lxattrschema\*O attributes. .SH "OPERATIONS" .SS "xattrschema catalog" .PP Returns a list of all the schema entry types defined in the specified schema. The syntax is as follows: .sS \*Lxattrschema catalog \*Vschema_name\*O [\*L-simplename\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-simplename\*O" Returns only the residual part of the schema name. .LE .PP The \*Lcatalog\*O operation returns a list of the names of all the schema entry types defined in the named schema. Use the \%\*L-simplename\*O option to return only the residual part of the names, instead of the fully qualified names. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the schema container object (\*L/.:/sec/xattrschema\*O or \*L/.:/hosts/\*Vhostname\*L/config/xattrschema\*O). .PP \*LExamples\*O .PP .oS dcecp> \*Lxattrschema catalog /.:/sec/xattrschema\*C /.../my_cell/sec/xattrschema/pre_auth_req /.../my_cell/sec/xattrschema/pwd_val_type /.../my_cell/sec/xattrschema/pwd_mgmt_binding /.../my_cell/sec/xattrschema/X500_DN /.../my_cell/sec/xattrschema/X500_DSA_Admin /.../my_cell/sec/xattrschema/disable_time_interval /.../my_cell/sec/xattrschema/max_invalid_attempts /.../my_cell/sec/xattrschema/passwd_override /.../my_cell/sec/xattrschema/test_any /.../my_cell/sec/xattrschema/test_void /.../my_cell/sec/xattrschema/test_printstring /.../my_cell/sec/xattrschema/test_printstring_array /.../my_cell/sec/xattrschema/test_integer /.../my_cell/sec/xattrschema/test_bytes /.../my_cell/sec/xattrschema/test_i18n_data /.../my_cell/sec/xattrschema/test_uuid /.../my_cell/sec/xattrschema/test_attr_set /.../my_cell/sec/xattrschema/test_binding dcecp> .oE .SS "xattrschema create" .PP Creates a new schema entry type. The syntax is as follows: .sS \*Lxattrschema create \*Vschema_entry_name_list\*O .nL {\*L-attribute \*Vattribute_list\*O | \*L-\*Vattribute value\*O} .sE .PP \*LOptions\*O .PP .VL .LI "\*L-\*Vattribute value\*O" As an alternative to using the \*L-attribute\*O option with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. .LI "\*L-attribute \*Vattribute_list\*O" Allows you to specify attributes by using an attribute list rather than using the \*L-\*Vattribute value\*O option. The format of an attribute list is as follows: .iS {{\*Vattribute \*Vvalue\*O}...{\*Vattribute \*Vvalue\*O}} .iE .LE .PP The \*Lcreate\*O operation creates a new schema entry for an ERA. The argument is a list of one or more names of schema entry types to be created. Attributes for the created schema entry types can be specified via attribute lists or attribute options. If the command argument contains more than one schema name, you cannot specify a UUID attribute. All attributes are applied to all entry types to be created. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Li\*O (\*Linsert\*O) permission to the container object (\*L/.:/sec/xattrschema\*O or \*L/.:/hosts/\*Vhostname\*L/config/xattrschema\*O). .PP \*LExamples\*O .PP .oS dcecp> \*Lxattrschema create /.:/sec/xattrschema/test_integer \e\*C > \*L-encoding integer -aclmgr {group r r r r} \*C dcecp> .oE .SS "xattrschema delete" .PP Deletes a schema entry type. The syntax is as follows: .sS \*Lxattrschema delete \*Vschema_entry_name_list\*O .sE .PP The \*Ldelete\*O operation deletes a schema entry. The argument is a list of names of schema entry types to be deleted. This command also deletes all ERA instances of the schema entry. If the entry types do not exist an error is generated. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Ld\*O (\*Ldelete\*O) permission to the container object (\*L/.:/sec/xattrschema\*O or \*L/.:/hosts/\*Vhostname\*L/config/xattrschema\*O). .PP \*LExamples\*O .PP .oS dcecp> \*Lxattrschema delete /.:/sec/xattrschema/test_integer \*C dcecp> .oE .SS "xattrschema help" .PP Returns help information about the \*Lxattrschema\*O object and its operations. The syntax is as follows: .sS \*Lxattrschema help \*O[\*Voperation\*O | \*L-verbose\*O] .sE .PP \*LOptions\*O .VL .LI "\*L-verbose\*O" Displays information about the \*Lxattrschema\*O object. .LE .PP Used without an argument or option, the \*Lxattrschema help\*O command returns brief information about each \*Lxattrschema\*O operation. The optional \*Voperation\*O argument is the name of an operation about which you want detailed information. Alternatively, you can use the \%\*L-verbose\*O option for more detailed information about the \*Lxattrschema\*O object itself. .PP .ne 4 \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lxattrschema help\*O command. .PP \*LExamples\*O .oS dcecp> \*Lxattrschema help\*C catalog Returns a list of all entries in a schema. create Creates a schema entry. delete Deletes a schema entry. modify Modifies an existing schema entry. rename Renames an existing schema entry. show Returns the attributes of a schema entry. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> .oE .SS "xattrschema modify" .PP This operation changes the attributes of a schema entry type. The syntax is as follows: .sS \*Lxattrschema modify \*Vschema_entry_name_list\*O .nL {\*L-change \*Vattribute_list\*O | .nL \*L-\*Vattribute value\*O} .sE .PP \*LOptions\*O .PP .VL .LI "\*L-\*Vattribute value\*O" As an alternative to using options with an attribute list, you can change individual attribute options by prepending a hyphen (\*L-\*O) to any attributes listed in the \*LATTRIBUTES\*O section of this reference page. .LI "\*L-change\*O \*Vattribute_list\*O" Allows you to modify attributes by using an attribute list rather than using individual attribute options. The format of an attribute list is as follows: .iS \*O{{\*Vattribute value\*O}...{\*Vattribute value\*O}} .iE .PP See \*LATTRIBUTES\*O for descriptions of the attributes. .LE .PP The \*Lmodify\*O operation changes attributes of schema entry types in the security service only. The argument is a list of names of schema entry types to be operated on. All modifications are applied to all schema entry types named in the argument. Schema entry types are modified in the order they are listed and all modifications to an individual schema entry are atomic. Modifications to multiple schema entry types are not atomic. A failure for any one schema entry in a list causes an error to be generated and the rest of the operation to be aborted. This operation returns an empty string on success. .P The \%\*L-change\*O option modifies attributes. Its value is an attribute list describing the new values for the specified attributes. The command supports attribute options as well. .PP \*LPrivileges Required\*O .PP You must have \*Lm\*O (\*Lmgmt_info\*O) permission to the container object \*L/.:/sec/xattrschema\*O. .PP .ne 4 \*LExamples\*O .PP .oS dcecp> \*Lxattrschema modify /.:/sec/xattrschema/test_integer \e\*C > \*L-aclmgr {organization r r r r} \*C dcecp> .oE .SS "xattrschema operations" .PP Returns a list of the operations supported by the \*Lxattrschema\*O object. The syntax is as follows: .sS \*Lxattrschema operations\*O .sE .PP The list of available operations is in alphabetical order except for \*Lhelp\*O and \*Loperations\*O, which are listed last. .PP \*LPrivileges Required\*O .PP No special privileges are needed to use the \*Lxattrschema operations\*O command. .PP \*LExamples\*O .PP .oS dcecp> \*Lxattrschema operations\*C catalog create delete modify rename show help operations dcecp> .oE .SS "xattrschema rename" .P Changes the name of a specified schema entry type. The syntax is as follows: .sS \*Lxattrschema rename \*Vschema_entry_name\*L -to \*Vnew_schema_entry_name\*O .sE .PP \*LOptions\*O .VL .LI "\*L-to \*Vnew_schema_entry_name\*O" Specifies the new name. Specify the name in simple format, without the container-object portion (that is, without \*L/.:/sec/xattrschema\*O). .LE .PP The \*Lrename\*O operation changes the name of a specified ERA in the security service only. The argument is a single name of an ERA to be renamed. The \*Vnew_schema_entry_name\*O argument to the required \%\*L-to\*O option specifies the new name; this argument may not be a list. This operation returns an empty string on success. .PP \*LPrivileges Required\*O .PP You must have \*Lm\*O (\*Lmgmt_info\*O) permission to the container object \*L/.:/sec/xattrschema\*O. .PP \*LExamples\*O .PP .oS dcecp> \*Lxattrschema rename /.:/sec/xattrschema/test_integer -to test_int \*C dcecp> .oE .SS "xattrschema show" .P Returns an attribute list describing the specified schema entry type. The syntax is as follows: .sS \*Lxattrschema show \*Vschema_entry_name_list\*L\*O .sE .PP The \*Lshow\*O operation returns an attribute list describing the specified schema entry types. The argument is a list of names of schema entry types to be operated on. If more than one schema entry is given, then the attributes are concatenated together. Attributes are returned in arbitrary order. .PP \*LPrivileges Required\*O .PP You must have \*Lr\*O (\*Lread\*O) permission to the container object (\*L/.:/sec/xattrschema\*O or \*L/.:/hosts/\*Vhostname\*L/config/xattrschema\*O). .PP .ne 14 \*LExamples\*O .PP .oS dcecp> \*Lxattrschema show /.:/sec/xattrschema/test_integer\*C {aclmgr {principal {{query r} {update r} {test r} {delete r}}}} {annotation {test_integer: encoding type integer}} {applydefs yes} {encoding integer} {intercell reject} {multivalued yes} {reserved no} {scope {}} {trigbind {none {}}} {trigtype none} {unique no} {uuid 5f439154-2af1-11cd-8ec3-080009353559} dcecp> .oE .SH "RELATED INFORMATION" .PP .ad l Commands: \*Ldcecp(1m)\*O, \*Ldcecp_account(1m)\*O, \*Ldcecp_group(1m)\*O, \*Ldcecp_organization(1m)\*O, \*Ldcecp_principal(1m)\*O. ...\" \*Laccount(1m)\*O, ...\" \*Ldcecp(1m)\*O, ...\" \*Lgroup(1m)\*O, ...\" \*Lorganization(1m)\*O, ...\" \*Lprincipal(1m)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH dced "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "defect,9830,R1.1, New dced daemon" .iX "-[" "DCE Host daemon" "about" .SH NAME \*Ldced\*O - DCE Host daemon .SH "SYNOPSIS" .sS \*Ldced\*O [\*L-ifhr\*O] [\*L-w \*Vroute\*O] [\*L-b\*O|\*L-p\*O|\*L-s\*O] [\*L-e\*O|\*Vprot_seq...\*O] \*Lrpcd\*O [\*L-f\*O] [\*Vprot_seq...\*O] ...\" ...\"\*Ldced\*O [\*L-h\*O] [\*L-w\*O \*Vrouting\*O] ...\" ...\"\*Ldced\*O [\*L-i\*O] [\*L-w\*O \*Vrouting\*O] ...\" ...\"\*Ldced\*O [\*L-bcf\*O[\*L-p\*O|\*L-s\*O]] [\*Vprotseq\*O...] [-e] [\*L-w\*O \*Vrouting\*O] ...\" ...\" debug mode ...\"\*Ldced\*O [\*L-d\*O] ...\" .sE .SH "OPTIONS" .VL .LI \*L-h\*O Prints the \*Ldced\*O usage and exits. .LI \*L-i\*O Initializes the \*Ldced\*O databases and ACLs and exits. If the databases exist, this option displays an error. See the list of databases in the FILES section. .LI \*L-b\*O Starts \*Ldced\*O in bootstrap mode with the endpoint mapper service and ACLs. This mode means it may need to wait for other daemons such as \*Lsecd\*O and \*Lcdsd\*O before it can perform its own initialization. .LI \*L-c\*O Starts \*Ldced\*O so it does not require DCE privacy encryption for remote key table management. The default is to use DCE privacy encryption. DCE Privacy encryption is supported only by the Domestic (United States and Canada) versions of the DCE library and \*Ldced\*O. If the Export version of \*Ldced\*O is run without \*L-c\*O, then remote key table management is in effect disabled; if the Export \*Ldced\*O is run with \*L-c\*O, then remote key table management is enabled. However, running either version of \*Ldced\*O with \*L-c\*O is insecure and not recommended, because remote key table management without privacy encryption allows an eavesdropper to learn the long-term key of a service principal and thus to compromise the security of services running as that principal. .LI \*L-e\*O Starts \*Ldced\*O without the endpoint mapper service. No protocol sequences are valid for this option. .LI \*L-f\*O Starts the \*Ldced\*O or \*Lrpcd\*O process in the foreground. The default is to run in the background. .LI \*L-p\*O Purges the existing machine context and removes the bindings file before starting. .LI "\*L-r\*O" Starts \*Ldced\*O in remote-update mode. This mode allows DCE cell administration tasks to be performed by an administrator on a remote machine. By default, \*Ldced\*O prevents any remote administration to help prevent attacks by a malicious administrators. .LI \*L-s\*O Starts \*Ldced\*O without the security validation service. .LI \*L-w\*O Sets the routing for serviceability. ...\" debug mode ...\".LI \*L-d\*O ...\"Starts the DCE Host daemon in debug mode. ...\"In this mode, \*Ldced\*O runs as a forground process. .LE .SH "ARGUMENTS" .VL .LI \*Vroute\*O Establishes the serviceability routing for \*Ldced\*O's messages. .LI \*Vprot_seq\*O Specifies the RPC protocol sequences that \*Ldced\*O or \*Lrpcd\*O will use. Possible values include \*Lncadg_ip_udp\*O (for a datagram protocol) and \*Lncacn_ip_tcp\*O (for a connection-based protocol). A complete list of the protocol sequences recognized can be found in \*Ldce/ep.idl\*O. .LE .SH "DESCRIPTION" The DCE Host daemon is a process that provides services for the local host, and is also the server used by remote applications to access these host services. .PP The daemon can be invoked either as \*Ldced\*O or as \*Lrpcd\*O. When invoked as \*Ldced\*O, it provides by default all of the services described below, and it requires that the local host be configured into a DCE cell. When invoked as \*Lrpcd\*O, it provides only the Endpoint Mapper and Local Location Broker services that were provided by \*Lrpcd\*O in earlier versions of DCE; The \*Lrpcd\*O mode does not require that the host be configured into a DCE cell, so this is a simple alternative for hosts that run Networking Computing System (NCS) applications or DCE RPC-only applications. .PP The DCE Host daemon services include the following: .VL .LI "Endpoint Mapper" .nL The endpoint mapper service maintains a database called the \*Vlocal endpoint map\*O which allows DCE clients to find servers, individual services provided by servers, and objects managed by services on the host. The endpoint mapper service maps interfaces, object UUIDs, and protocol sequence registrations to server ports (endpoints). Servers register their bindings with the local endpoint mapper, and the endpoint mapper service on each host uses the local endpoint map to locate a compatible server for clients that do not already know the endpoint of a compatible server. .LI "Local Location Broker" .nL The local location broker service maintains a database called the LLB database, which allows NCS clients to find NCS servers on the host. This service was provided by \*Lrpcd\*O in earlier versions of DCE and by \*Lllbd\*O in NCS. .LI "Host Data Management" .nL The host data management service maintains local files of host data that include (among others) the \*Lhost_name, cell_name, cell_aliases,\*O and a \*Lpost_processors\*O file. The \*Lpost_processors\*O file contains program names matched with the other host data items (UUIDs). The \*Ldced\*O runs the program if the corresponding host data item is changed. There may also be host-specific data files. .LI "Server Management" .nL The server management service maintains data that describes the startup configuration (\*Lsrvrconf\*O) and execution state (\*Lsrvrexec\*O) for each server. It also has the functionality to start or stop particular servers, and enable or disable specific services of servers. .LI "Security Validation" .nL The security validation service acts as the client side of the security server by assuring applications that the DCE Security daemon (\*Lsecd\*O) that the host is using is legitimate. In addition, this service performs a DCE login for the local machine principal when \*Ldced\*O is invoked, and it automatically updates the local machine principal's keys. .LI "Key Table Management" .nL The key table management service allows for remote maintenance of server's key tables (\*Lkeytab\*O files). .LE .PP The DCE Host daemon must be running before any other DCE-based servers are started. Each DCE host must run only a single \*Ldced\*O, and it must run with root privileges since it typically listens on privileged or reserved network ports. Typically, \*Ldced\*O starts each time a host boots. (A file called \*L/etc/rc.dce\*O is responsible for configuration issues such as deleting the endpoint map database and starting \*Ldced\*O.) .PP By default, the DCE Host daemon listens on one well-known port for each RPC protocol sequence (that is, each combination of an RPC protocol and a transport protocol) supported by the host on which it is running. A \*Vprot_seq\*O argument lets you limit the protocol sequences on which \*Ldced\*O listens. .PP .SH "FILES" .PP .TS tab(@); lB lB. \*Vdcelocal\*L/var/dced/Ep.db @\*Vdcelocal\*L/dce_cf.db \*Vdcelocal\*L/var/dced/Llb.db @\*Vdcelocal\*L/var/dced/cell_aliases \*Vdcelocal\*L/var/dced/Hostdata.db@\*Vdcelocal\*L/var/dced/cell_name \*Vdcelocal\*L/var/dced/Srvrconf.db@\*Vdcelocal\*L/var/dced/host_name \*Vdcelocal\*L/var/dced/Srvrexec.db@\*Vdcelocal\*L/var/dced/post_processes \*Vdcelocal\*L/var/dced/Keytab.db @\*Vdcelocal\*L/bin/dcecf_postproc \*Vdcelocal\*L/var/dced/Acl.db @/krb5/v5srvtab \*Vdcelocal\*L/var/dced/Xattrschema.db@ .TE .SH "RELATED INFORMATION" Commands: \*Lhostdata(1m), endpoint(1m), server(1m), secval(1m), keytab(1m), attribute(1m)\*O .PP Library calls: \*Ldce_server*(3), dced_*(3), rpc_mgmt_ep*(3)\*O .PP Books: ...\"App. Dev. Guide \*(Dg. .iX "-]" "DCE Host daemon" "about" .zZ "defect,9830,R1.1, New dced daemon"  .\" $Header: /vob/dce.doc/src/doc/HP/misc/man8/dceping.1m,v /main/2 1996/04/17 16:30 UTC millett Exp $ ...\" .rm zA .rm zZ .TH dceping "8" "" "HP DCE" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .ds )H Hewlett-Packard Company .ds ]W HP DCE/9000 Version 1.2 .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml .SH NAME \*Ldceping\*O - test the ability to contact DCE services from a local DCE client. .SH "SYNOPSIS" \*Ldceping\*O [\*L-n \*Vnumber\*O] [\*L-s \*Vtime\*O] [\*L-v\*O] [\*L-C\*O] [\*Vservice_name\*O ...] required to specify the literal strings, \*LNAMESPACE\*O or \*LSTRING_BINDING\*O (see nondcesvc(4)). .SH "OPTIONS" .VL 1i .LI "\*L-n \*Vnumber\*O" Specify the number of pinging cycles. Each service is tested once per cycle. The default is one pinging cycle. Specifying \*L-n 0\*O makes pinging continuous. .LI "\*L-s \*Vtime\*O" Specify time, in seconds, to wait between pinging cycles. You must specify more than one pinging cycle with the \*L-n\*O option in order to use \*L-s\*O. .LI "\*L-v\*O" Run in verbose mode. .LI "\*L-C\*O" Ping only core DCE services. This option is ineffective if a \*Vservice_name\*O is specified on the command line. .LE .SH "DESCRIPTION" \*Ldceping\*O verifies that a local DCE client can communicate with DCE and other services. It uses the RPC management interface to determine if the DCE service is listening. The core DCE services that \*Ldceping\*O checks include \*Lsecd\*O, \*Lcdsd\*O, \*Lgdad\*O, \*Lrpcd\*O, \*Lcdsadv\*O, \*Ldtsd\*O, and \*Lsec_clientd\*O. .PP You can ping other DCE and non-DCE services by naming them in the file, \*L/opt/dcelocal/hpadmin/etc/nondcesvc\*O. If you want to determine at run time what services you want \*Ldceping\*O to ping, you may do so using the same file. See the manpage, nondcesvc(4), for more information. .PP You may specify the services to ping on the command line separated by blanks. In this case, \*Ldceping\*O does not ping any DCE core services or the services listed in \*L/opt/dcelocal/hpadmin/etc/nondcesvc\*O. The \*Vservice_name\*O specified could be either a name in the DCE Cell Directory Service Namespace or an RPC string binding. It is not .SH "AUTHOR" \*Ldceping\*O was developed by HP. .SH "FILES" \*L/opt/dcelocal/hpadmin/etc/nondcesvc .nL /opt/dcelocal/hpadmin/etc/wellknownif\*O .SH "SEE ALSO" \*Lnondcesvc(4), wellknownif(4)\*O .\" $Header: /vob/dce.doc/src/doc/HP/misc/man8/dceval.1m,v /main/2 1996/04/17 16:30 UTC millett Exp $ ...\" .rm zA .rm zZ .TH dceval "8" "" "HP DCE" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .ds )H Hewlett-Packard Company .ds ]W HP DCE/9000 Version 1.2 .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml .SH NAME \*Ldceval\*O - test if a DCE client can function in its cell. .SH "SYNOPSIS" \*Ldceval\*O [\*L-p \*Vpreserve_directory\*O] [\*L-v\*O] .SH "OPTIONS" .VL 1i .LI "\*L-p \*Vpreserve_directory\*O Specify a directory to preserve intermediate validation data for debugging purposes. By default, intermediate data is not displayed and is not saved. .LI "\*L-v\*O Run in verbose mode. .LE .SH "DESCRIPTION " \*Ldceval\*O runs a series of tests that verify whether or not a local DCE client is able to participate in its cell. .PP When you invoke \*Ldceval\*O from a command line, it prompts for the cell administrator's principal name and for a password. If you use the defaults, you can enter at the prompts. .PP \*Ldceval\*O performs the following validation tests: .ML 1.5i .LI Contact core services using \*Ldceping\*O. .LI Check RPC endpoint map. .LI Verify DCE security service installation and configuration. .LI Verify DCE namespace service installation and configuration. .LI Verify DCE time service installation and configuration. .LI Optionally, validate ENCINA-related security and namespace objects. .LE .SH "AUTHOR" \*Ldceval\*O was developed by HP. .SH "SEE ALSO" \*Ldceping(8)\*O .\" $Header: dcnodes.1m,v 74.1 95/03/02 11:38:43 ssa Exp $ .TA d .TH dcnodes 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" =========== .SH NAME dcnodes \- display information about specified diskless cluster nodes .\" =========== .SH SYNOPSIS .C dcnodes .RC [ -lLsSarmxbhHq ] .RC [ -t .IR timeout ] .RI [ \|name \0...\|] .\" =========== .SH DESCRIPTION .C dcnodes displays static (configuration) and dynamic (status) information about diskless cluster nodes (server, and clients). By default, when run on any node in a cluster .C dcnodes displays the names of all nodes in the cluster (both active, and inactive). The cluster server's name is displayed as the first in the list, with the remaining names sorted alphabetically. ``Cluster server'' also refers to a standalone system on which .C dcnodes is invoked. .\" .\" The old version, cnodes(1), had -C and -1 options and sometimes printed .\" the names in columns, using curses(3X). We decided this wasn't worth .\" keeping. .PP When at least one .I name is specified, information about each named cluster node is displayed, subject to modification by options (see below), in the same order as they would appear in the full list. .\" .\" The old version displayed active nodes only by default, but that's .\" expensive to know with NFS diskless, so the new version will list all or .\" the specified dcnodes regardless of their status. The -a (all clients) .\" option will be replaced by a -a (active clients) option with inverse .\" meaning, to limit output to active dcnodes only. The old -A (all .\" clients, no asterisks for down clients) option is obsolete. .PP When .C dcnodes is executed on a cluster (remote-root) client, it contacts the cluster (root) server for the information to display, except as noted below. .\" .\" dcnodes can be invoked in "raw" mode by rcmd() from a remote call of .\" dcnodes() or dcnodes_status() using an undocumented option. See .\" the code for details. .\" ----------- .SS Options .C dcnodes recognizes the following options: .RS .TP 6 .C -l (ell) List cluster nodes in long format. If the cluster server has multiple .SM LAN cards, there is one line of output for each, sorted by card name. If standard output is a terminal, a two-line header containing field labels is also displayed. The information for each node includes the fields described in .RB `` "Data Fields" '' below. .TP .C -L Like .C -l but also append a column for .SM OS shared root values. .TP .C -s Display a node status column after the node name column. Status determination can take time since the cluster server must poll each client for its status. Status field values are described in .RB `` "Data Fields" '' below. .\" .\" The previous -s option was renamed to -q (quiet) to allow -s to stand .\" for "status" in the new version. .TP .C -S Same as .CR -s , but give more detailed status information for inactive clients. .TP .C -a List only active systems, that is, those that are up as remote-root clients of the cluster server on which .C dcnodes is invoked, or of the cluster (root) server for the remote-root client on which .C dcnodes is invoked. This can take time since the cluster server must poll each client for its status. If .IR name s are specified on the command line, only those systems are polled, and only those that are running as clients of the local cluster are listed. .TP .C -r Display information about the cluster (root) server system only. Any .I name arguments are ignored. If invoked on a remote-root client with .C -r or .C -rs only, .C dcnodes does not contact the cluster server, but constructs the output quickly from local information. .TP .C -m (myself) List information about the local cluster node only. Any .I name arguments are ignored. Invoked on a remote-root client with .C -m or .C -ms only, .C dcnodes does not contact the cluster server, but constructs the output quickly from local information. .TP .C -x (except myself) Do not list information about the local cluster node (based on its .C hostname value, see .IR hostname (1)), even if it is explicitly named on the command line. .TP .C -b Display hostnames as basenames only, with domain parts (if any) removed. This is useful for stripping unnecessary information from the output if all cluster nodes are in the same domain. .TP .C -h Print an output header (field labels) even if standard output is not a terminal. Note that no header appears when printing only hostnames, that is, when none of the .C -lLs options are specified. .TP .C -H Do not print an output header even if standard output is a terminal. .TP .C -q Quiet mode; suppress all output. This option is useful for testing .CR dcnode 's return value to distinguish between standalone systems, cluster servers, and cluster clients. With this option, .C dcnodes on a cluster client does not contact the cluster server. .TP .CI -t \0timeout Cluster clients periodically send ``keepalive'' messages to the server. When the server receives one of these messages, it updates a timestamp for the client from which the message was received. The timeout value specified with the .C -t option is the lifespan of a timestamp. For example, if you want to know how many clients checked in with the server in the last 5 seconds, use a timeout of 5. The default timeout value is 10 seconds. .PP Contradictory option combinations such as .C -r with .C -x are not permitted. .\" .\" The -n option existed to list dcnode IDs; it is obsolete. .\" ----------- .SS Data Fields Each output column (field) is automatically sized to the widest value that appears in that column, including field labels if header lines are printed. A script that parses the output must look for whitespace-separated fields rather than fixed-width data, except that the optional last column (\s-1OS SHARED ROOT\s0) might contain whitespace. .PP This field always appears: .TP 20 .B NODENAME For a cluster server or standalone system: .RS .TP 3 \(bu When the .C -l or .C -L option is used, .C NODENAME is reported as the name corresponding to the .SM IP address of each of a system's .SM LAN cards. .TP \(bu When the .C -l or .C -L option is used, and the name corresponding to the .SM IP address is unknown, .C NODENAME is reported as .RC `` ? ''. .TP \(bu if the system has no .SM LAN cards, or when .CR -l , and .C -L options are not used, .C NODENAME is reported as the server's .C hostname value expanded through the hosts database to include domain information, if any. When the .C -b option is used, domain information is not reported. .RE .IP For a cluster client: .RS .TP 3 \(bu With the .C -r or .C -rs options only, .C NODENAME is reported as the name corresponding to the server's internet address by which the client mounts its root directory. .TP \(bu When the .C -r or .C -rs options are used, and the name corresponding to the server's internet address is unknown, .C NODENAME is reported as the server's internet address. .TP \(bu When the .C -r or .C -rs options are used, and the server's internet address is unknown, .C NODENAME is reported as .RC `` ? ''. .TP \(bu With the .C -m or .C -ms options only, .C NODENAME is reported as the client's .C hostname expanded through the hosts database to include domain information, if any. .TP \(bu Otherwise, .C NODENAME is reported as the name that appears in the server's list of configured client nodes (see .SM FILES below). .RE .\" ----------- .PP When the .C -l or .C -L option is used, the following data fields appear. If a cluster server system has multiple .SM LAN interface cards, one line of output appears for each card with the appropriate values for that card. If a field's value cannot be determined, the field contains .RC `` ? ''. .TP 20 .B IP ADDRESS Dot-form internet address value for each of the server's .SM LAN cards, or for the .SM LAN card through which each client contacts the server .RC ( lan0 ). .TP .B HW ADDRESS 12-digit hex form hardware address value for each of the server's .SM LAN cards, or for the .SM LAN card through which each client contacts the server. .TP .B NETMASK Dot-form net/subnet mask value for each of the server's .SM LAN cards, or for the .SM LAN card through which each client contacts the server (based on boot-up configuration). .TP .B DEF ROUTE First default route value configured for the server, if any, or in the boot-up configuration for each client, if it has a gateway field. .TP .B OS SHARED ROOT A description if available, otherwise a path. For the server, always .RC `` / ''; for each client, the appropriate value. Only appears when the .C -L option is used. .PP The following data field appears with the .C -s or .C -S option: .TP .B STATUS The value is one of the following: .RS .TP 12 .C ? Cannot be determined. .TP .C standalone System on which .C dcnodes is invoked has a local root volume and no remote-root clients configured. .TP .C server Cluster (root) server, a local-root system with one or more remote-root clients configured. .TP .C active Node is running as a remote-root client of the local cluster. It allows .C rcmd() from the cluster (root) server (see .IR rcmd (3N)) and identifies the server as its root server. Note that all nodes in a cluster are normally configured to allow .C rcmd() access between the cluster server and clients (at least to privileged users); and .C dcnodes is normally set to run setuid-root (see .IR setuid (2)). .TP .C inactive Node does not respond to or does not allow .C rcmd() from the cluster (root) server, is running as a standalone (local-root) system, or identifies as its root server a system other than the local cluster's root server. A node is marked inactive if anything goes wrong, including timeout, while .C dcnodes tries to check that it is active. .RE .PP With the .C -S option, any of the following can appear instead of .CR inactive : .RS .TP 12 .C no_IP_addr Client's .SM IP address is unknown, and its name is unknown to the hosts database (cannot be converted to an .SM IP address). .TP .C no_data Data for this system was not available from the cluster status daemon. .RE .\" =========== .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG specifies the language used to display messages. .PP If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C dcnodes behaves as if all internationalization variables are set to ``C''. See .IR environ (5). .\" =========== .SH RETURN VALUE .C dcnodes returns the following values: .RS .TP 5 .C 0 Successful completion on a standalone system, that is, on a local-root system with no remote-root clients configured. .PD 0 .TP .C 1 Successful completion on a cluster server, that is, on a local-root system with one or more remote-root clients configured. .TP .C 2 Successful completion on a cluster (remote-root) client. .TP .C 3 Failure due to incorrect invocation of the command; a specific message is written to standard error. .TP .C 4 Failure of a call to .C dcnodes() or .CR dcnodes_status() ; a specific message is written to standard error. .TP .C 5 Failure to allocate memory needed internally. .PD .RE .\" =========== .SH DIAGNOSTICS .C dcnodes writes warnings or error messages to standard error as appropriate. It issues a warning if a system named on the command line is not the local system and is not listed (configured) as a member of the local cluster, regardless of its status. It issues an error if invoked on a remote-root client and it cannot contact the cluster (root) server for information when this is required. .\" =========== .SH EXAMPLES List all cluster nodes and related information except .SM OS shared root paths: .IP .C dcnodes -ls .PP List all active cluster nodes and their status, except the local system: .IP .C dcnodes -asx .PP List full information for the cluster server: .IP .C dcnodes -rLs .PP List status and other information for selected nodes, but only if they are active: .IP .C dcnodes -lsa sys1 sys2 ... .\" =========== .SH WARNINGS Using .C dcnodes it is possible to distinguish between standalone, server, and client systems, and behave differently depending on the system type. However, it is desirable that applications not make this distinction, and it is usually found to be unnecessary upon closer analysis. .PP When the .C -l or .C -L options are used with the .C -m or .C -x option, or .IR name s are specified on the command line, cluster server .SM LAN cards with names that are unknown, or with names that don't match the cluster server's expanded .C hostname value, might be included, or excluded, from the output unexpectedly. .PP Because the .C -l and .C -L options retrieve each client's internet address from the bootptab file, running dcnodes with the .CR -s , .CR -S , or .C -a option might run faster when the .C -l or .C -L option is also used. Without .C -l or .CR -L , each internet address for each client must be found in the hosts database, a process that might take longer than searching bootptab. However, when bootptab is used, only a single internet address is tried for each cluster client. .\" =========== .SH AUTHOR .C dcnodes was developed by .SM HP. .\" =========== .SH FILES .TP 25 .C /etc/clients.dc list of configured cluster client nodes that receive root service from a system .TP .C /etc/bootptab control file for .C bootpd (see .IR bootpd (1M)) that contains most of the client information returned by .C dcnodes .\" =========== .SH SEE ALSO hostname(1), bootpd(1M), dcnodes(1M), dcnodesd(1M), errno(2), setuid(2), dcnodes(3X), rcmd(3N), environ(5), lang(5). .\" .\" toc@\f3dcnodes(1M)\f1:\0\0\f4dcnodes\f1@@@diskless cluster node information display .\" .\" index@\f4dcnodes\f1 \- diskless cluster node information@@@\f3dcnodes(1M)\f1 .\" index@\f1display diskless cluster node information@@@\f3dcnodes(1M)\f1 .\" index@\f1diskless cluster nodes, display information about@@@\f3dcnodes(1M)\f1 .\" .\" $Header: dcnodesd.1m,v 72.2 95/03/02 12:13:05 ssa Exp $ .TA d .TH dcnodesd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" =========== .SH NAME dcnodesd \- maintain cluster client status information .\" =========== .SH SYNOPSIS .C dcnodesd .RC [ -r .IR retransmit_interval ] .\" =========== .SH DESCRIPTION .C dcnodesd provides information on the state of cluster clients. .C dcnodesd executes on all nodes of a cluster. On clients, it periodically sends ``keepalive'' packets to the .C dcnodesd running on the cluster server. .C dcnodesd gathers this information from clients and provides it to the .C dcnodes_status() function (see .IR dcnodes_status (3X)). .PP .C dcnodesd is started on cluster servers and clients by entries in .IR /etc/inittab . .PP When started on a cluster server, .C dcnodesd collects packets from cluster clients and resets timestamps. When started on a cluster client, .C dcnodesd periodically send keepalive packets to the cluster server. .SS Options .C dcnodesd recognizes the following options: .RS .TP 6 .CI -r \0retransmit_interval The .C dcnodesd running on a cluster clients periodically sends messages to the server. When the server receives one of these messages, it updates a timestamp for the client from which the message was received. When the .C dcnodesd on the server provides information to .CR dcnodes_status() , it provides both the client timestamps and a current timestamp. The difference between these two values is used to determine if a client is active or not. By using the .C -r option, the retransmission interval can be specified for the .C dcnodesd running on a client. It defaults to once every 5 seconds. .IP Client timestamps have a lifespan which defaults to 10 seconds. A client with a timestamp older than 10 seconds is considered inactive. The retransmission interval should not require adjustment, but on a heavily loaded client and/or network, it can be shortened to increase the likelihood of updating the client timestamp regularly. .\" ----------- .SH DIAGNOSTICS .C dcnodesd writes warnings or error messages to standard error as appropriate. .C dcnodesd uses syslog() for error and warning messages once it has initiated its network connections. .\" =========== .SH AUTHOR .C dcnodesd was developed by .SM HP. .\" =========== .SH FILES .TP 25 .C /etc/clients.dc list of configured cluster client nodes that receive root service from a system .TP .C /etc/bootptab control file for .C bootpd (see .IR bootpd (1M)) that contains most of the client information returned by .C dcnodes .\" =========== .SH SEE ALSO bootpd(1M), dcnodes(1M), dcnodes(3X). .\" .\" toc@\f3dcnodesd(1M)\f1:\0\0\f4dcnodesd\f1@@@maintain cluster client status information .\" .\" index@\f4dcnodesd\f1 \- maintain cluster client status information@@@\f3dcnodesd(1M)\f1 .\" index@\f4dcnodesd\f1 \- cluster client status information@@@\f3dcnodesd(1M)\f1 .\" index@\f1maintain cluster client status information information@@@\f3dcnodesd(1M)\f1 .\" index@\f1diskless cluster nodes, maintain status information about@@@\f3dcnodesd(1M)\f1 .\" index@\f1cluster nodes, maintain status information about diskless@@@\f3dcnodesd(1M)\f1 .\" .\" $Header: dcopy.1m,v 72.5 94/09/08 16:43:47 ssa Exp $ .TA d .TH dcopy 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dcopy \- copy HFS file system with compaction. .SH SYNOPSIS .CR /usr/sbin/dcopy .RC [ -d ] .RC [ -f\c .IR fsize [\c .CI : isize\c .RC ]\|] .RC [ -F .CR hfs ] .RC [\c .CI -s cyl : skip\c .RC ] .RC [ -v ] .RC [ -V ] .ifn .br .ifn \0\0\0\0 .I source_fs .I destination_fs .SH DESCRIPTION The .CR dcopy command copies an existing HFS file system .RI ( source_fs ) to a new HFS file system .RI ( destination_fs ), appropriately sized to hold the reorganized results. For best results, the source file system should be a raw device, and the destination file system should be a block device. Always run .CR dcopy on unmounted file systems. (In the case of the root file system, copy it to a new minidisk.) .PP If no options are specified, .CR dcopy copies files from .IR source_fs , compressing directories by removing vacant entries and spacing consecutive blocks in a file by the optimal rotational gap. If options such as .CR -f or .CR -s are specified, the destination file system structure will be different from that of the source file system. .PP .CR dcopy makes the destination file system identical to the source file system and preserves the pack and volume labels. Thus, to compress a file system without moving it, use .CR dcopy to copy the files to another file system and the .CR dd command to copy the file back (see .IR dd (1)). .PP Directory compression is accomplished by running .CR dcopy on the primary copy of the file system and allowing the modified directories to propagate to the other copies of the file system in the normal manner. .SS Options .CR dcopy recognizes the following options: .RS .TP 15 .CI -d Move subdirectories to the beginning of directories. .TP .CI -f fsize\f1[ : isize\f1] Specify the file system size .RI ( fsize ) and inode-list size .RI ( isize ) in blocks. If this option is not specified, the source file-system value is used. .TP .C "-F hfs" Specify the HFS file system type. The type of a file system can be determined with the .CR fstyp command (see .IR fstyp (1M)). See DEPENDENCIES. .TP .CI -s cyl : skip Supply device information for creating the best organization of blocks in a file. .I cyl is the number of block per cylinder; .I skip is the number of blocks to skip. .TP .CR -v Report size of source and destination file system. .TP .CR -V Echo the completed command line, but performs no other actions. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows you to verify the command line. .RE .SH EXAMPLES .CR dcopy can be executed with or without options. If no options are specified as in this example, the source and destination file systems are identical. Any differences between the two file systems lie only in the available disk space. .IP .C "dcopy /dev/rdsk/c2d0s4 /dev/dsk/c2d0s5" .PP If options are specified, expect a major difference between the source and destination file system structure: .IP .C "dcopy -F hfs -f40960:260 -s45:5 -d /dev/rdsk/c2d0s4" .ifn .C "\e" .ifn .br .ifn \0\0\0\0 .C "/dev/dsk/c2d0s5" .SH WARNINGS .CR dcopy produces invalid results if run on a mounted file system. .PP The figures specified in option arguments cannot be smaller than corresponding figures in the source file system. .SH DEPENDENCIES .CR dcopy only operates on HFS file systems. .SH AUTHOR .CR dcopy was developed by HP. .SH SEE ALSO dd(1M), fstyp(1M). .SH STANDARDS CONFORMANCE .CR dcopy ": SVID3" .\" .\" index@\f4dcopy\f1 \- copy HFS file system with compaction@@@\f3dcopy(1M)\f1 .\" index@copy HFS file system with compaction@@@\f3dcopy(1M)\f1 .\" index@HFS file system, copy with compaction@@@\f3dcopy(1M)\f1 .\" index@file system, copy HFS with compaction@@@\f3dcopy(1M)\f1 .\" index@compaction, copy HFS file system with@@@\f3dcopy(1M)\f1 .\" .\" toc@\f3dcopy(1M)\f1:\0\0\f4dcopy\f1@@@copy HFS file system with compaction .\" .\" links@dcopy.1m dcopy_hfs.1m .\" $Header: dcopy.1m,v 72.5 94/09/08 16:43:47 ssa Exp $ .TA d .TH dcopy 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dcopy \- copy HFS file system with compaction. .SH SYNOPSIS .CR /usr/sbin/dcopy .RC [ -d ] .RC [ -f\c .IR fsize [\c .CI : isize\c .RC ]\|] .RC [ -F .CR hfs ] .RC [\c .CI -s cyl : skip\c .RC ] .RC [ -v ] .RC [ -V ] .ifn .br .ifn \0\0\0\0 .I source_fs .I destination_fs .SH DESCRIPTION The .CR dcopy command copies an existing HFS file system .RI ( source_fs ) to a new HFS file system .RI ( destination_fs ), appropriately sized to hold the reorganized results. For best results, the source file system should be a raw device, and the destination file system should be a block device. Always run .CR dcopy on unmounted file systems. (In the case of the root file system, copy it to a new minidisk.) .PP If no options are specified, .CR dcopy copies files from .IR source_fs , compressing directories by removing vacant entries and spacing consecutive blocks in a file by the optimal rotational gap. If options such as .CR -f or .CR -s are specified, the destination file system structure will be different from that of the source file system. .PP .CR dcopy makes the destination file system identical to the source file system and preserves the pack and volume labels. Thus, to compress a file system without moving it, use .CR dcopy to copy the files to another file system and the .CR dd command to copy the file back (see .IR dd (1)). .PP Directory compression is accomplished by running .CR dcopy on the primary copy of the file system and allowing the modified directories to propagate to the other copies of the file system in the normal manner. .SS Options .CR dcopy recognizes the following options: .RS .TP 15 .CI -d Move subdirectories to the beginning of directories. .TP .CI -f fsize\f1[ : isize\f1] Specify the file system size .RI ( fsize ) and inode-list size .RI ( isize ) in blocks. If this option is not specified, the source file-system value is used. .TP .C "-F hfs" Specify the HFS file system type. The type of a file system can be determined with the .CR fstyp command (see .IR fstyp (1M)). See DEPENDENCIES. .TP .CI -s cyl : skip Supply device information for creating the best organization of blocks in a file. .I cyl is the number of block per cylinder; .I skip is the number of blocks to skip. .TP .CR -v Report size of source and destination file system. .TP .CR -V Echo the completed command line, but performs no other actions. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows you to verify the command line. .RE .SH EXAMPLES .CR dcopy can be executed with or without options. If no options are specified as in this example, the source and destination file systems are identical. Any differences between the two file systems lie only in the available disk space. .IP .C "dcopy /dev/rdsk/c2d0s4 /dev/dsk/c2d0s5" .PP If options are specified, expect a major difference between the source and destination file system structure: .IP .C "dcopy -F hfs -f40960:260 -s45:5 -d /dev/rdsk/c2d0s4" .ifn .C "\e" .ifn .br .ifn \0\0\0\0 .C "/dev/dsk/c2d0s5" .SH WARNINGS .CR dcopy produces invalid results if run on a mounted file system. .PP The figures specified in option arguments cannot be smaller than corresponding figures in the source file system. .SH DEPENDENCIES .CR dcopy only operates on HFS file systems. .SH AUTHOR .CR dcopy was developed by HP. .SH SEE ALSO dd(1M), fstyp(1M). .SH STANDARDS CONFORMANCE .CR dcopy ": SVID3" .\" .\" index@\f4dcopy\f1 \- copy HFS file system with compaction@@@\f3dcopy(1M)\f1 .\" index@copy HFS file system with compaction@@@\f3dcopy(1M)\f1 .\" index@HFS file system, copy with compaction@@@\f3dcopy(1M)\f1 .\" index@file system, copy HFS with compaction@@@\f3dcopy(1M)\f1 .\" index@compaction, copy HFS file system with@@@\f3dcopy(1M)\f1 .\" .\" toc@\f3dcopy(1M)\f1:\0\0\f4dcopy\f1@@@copy HFS file system with compaction .\" .\" links@dcopy.1m dcopy_hfs.1m ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" .wH ""(2) .wH "" ...\" .rm zA .rm zZ .TH "define cached server" 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .wH "" .wH "" .wH "" .iX "-[" "CDS servers" "defining in local cache" .iX "-[" "cache" "defining servers" .iX "-[" "\*Lcdscp\*O commands" "\*Ldefine cached server\*O" .SH NAME .PP \*Ldefine cached server\*O - Creates knowledge of a server in the local clerk's cache .wH "" .SH "SYNOPSIS" .sS \*Lcdscp define cached server\*V name \*Ltower \*Vvalue\*O .sE .wH "" .SH "ARGUMENTS" .VL .LI "\*Vname\*O" A simple name for the cached server. .LI "\*Vvalue\*O" The protocol sequence and network address of the server node. The format is \*Vprotocol-sequence:network-address\*O. A \*Vprotocol-sequence\*O is a character string identifying the network protocols used to establish a relationship between a client and server. There are two choices of protocol sequence, depending on the network address that is supplied in the binding: \*Lncacn_ip_tcp\*O or \*Lncadg_ip_udp\*O. For the \*Enetwork-address\*O, specify an Internet address using the common Internet address notation. For more information about this format, see the RPC introduction in the \*EDCE Application Development Reference\*O. .wH "" .LE .SH "DESCRIPTION" .PP .wH "" The \*Ldefine cached server\*O command creates knowledge of a server in the local clerk's cache. This command is typically used to manually provide configuration information to a clerk that cannot automatically configure itself. This is required, for instance, to give the clerk addressing information about a server across a WAN. Once the clerk knows about one server, it can find other servers through referrals. .nE .SS "Privilege Required" .PP You must have write permission to the clerk. .wH "" .wH "" .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .PP The following command creates knowledge of the server \*Lnrl\*O in the local clerk's cache: .iS \*Ccdscp> \*Ldefine cached server nrl tower ncacn_ip_tcp:16.20.15.25 .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lclear cached server(1m)\*O, \*Ldump clerk cache(1m)\*O, \*Lshow cached server(1m)\*O .PP Books: \*EOSF DCE Application Development Reference\*O .iX "-]" "CDS servers" "defining in local cache" .iX "-]" "cache" "defining servers" .iX "-]" "\*Lcdscp\*O commands" "\*Ldefine cached server\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Oct 25, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH delete 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldtscp\*O commands" "\*Ldelete\*O" .iX "DTS clerks" "deleting" .iX "DTS servers" "deleting" .SH NAME .PP \*Ldelete\*O - Deletes the DCE DTS entity .SH "SYNOPSIS" .PP .zA "defect,6211,R1.0.3,add control program name" .sS \*Ldtscp delete\*O .sE .zZ "defect,6211,R1.0.3,add control program name" .SH "DESCRIPTION" .PP The \*Ldelete\*O command deletes the DCE DTS entity from the system where the command is entered. When \*Ldelete\*O is executed, the DTS daemon process completes execution. To restart the DTS daemon, use the \*Ldce_config\*O shell command. .SS "Privilege Required" .PP You must have write permission on the ACL associated with the DTS entity in order to execute the command. .SH "NOTES" .PP The DCE DTS entity cannot be deleted until you enter the \*Ldisable\*O command, which causes the status attribute \*Lstate\*O to be set to \*Loff\*O. .zA "defect, 11818, R1.1, Added caveat" .PP This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" ...\".SH "EXIT VALUE" ...\".PP ...\".VL 8m ...\".LI "Wrong State" ...\"The command failed because the DTS ...\"entity is not in the \*Loff\*O state. ...\".LE .SH "EXAMPLE" .iS \*Cdtscp>\*O \*Ldelete\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Ldisable (1m)\*O ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "delete child"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "child pointers" "deleting" .iX "\*Lcdscp\*O commands" "\*Ldelete child\*O" .iX "directories" "child pointers (CDS)" .SH NAME .PP \*Ldelete child\*O - Deletes a child pointer from the namespace .wH "" .SH "SYNOPSIS" .PP \*Lcdscp delete child\*O \*Vchild-name\*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vchild-name\*O" The full name of the child pointer. .wH "" .LE .SH "DESCRIPTION" .PP The \*Ldelete child\*O command deletes a child pointer from the namespace. .SS "Privilege Required" .PP You must have delete permission to the child pointer or administer permission to the parent directory. .SH "NOTES" .PP Use the \*Ldelete child\*O command only when the directory to which the child pointer refers is deleted and the child pointer accidentally remains. .zA "defect, 11818, R1.1, Added caveat" .PP This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .wH "" .SH "EXAMPLE" .PP The following command deletes the child pointer that accidentally remains after the \*L/.:/sales/east\*O directory is deleted: .iS \*Ccdscp>\*L delete child /.:/sales/east\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lcreate child(1m)\*O, \*Llist child(1m)\*O, \*Lshow child(1m)\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "delete clearinghouse" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "clearinghouses" "deleting" .iX "-[" "\*Lcdscp\*O commands" "\*Ldelete clearinghouse\*O" .SH NAME .PP \*Ldelete clearinghouse\*O - Deletes the specified clearinghouse from the local server system .wH "" .SH "SYNOPSIS" .PP \*Lcdscp delete clearinghouse\*O \*Vclearinghouse-name\*O .wH "" .SH "ARGUMENT" .VL .LI "\*Vclearinghouse-name\*O" The full name of the clearinghouse. .wH "" .LE .SH "DESCRIPTION" .PP .zA "enh,8009,V1.0.3,cannot delete cleared clearinghouse" The \*Ldelete clearinghouse\*O command deletes a clearinghouse from the local server system. CDS does not permit you to delete a cleared clearinghouse. Before you can delete a cleared clearinghouse, you must recreate it using the \*Lcreate clearinghouse\*O command. .zZ "enh,8009,V1.0.3,cannot delete cleared clearinghouse" .PP The \*Ldelete clearinghouse\*O command automatically deletes all read-only replicas from a clearinghouse. CDS does not permit you to delete a clearinghouse that contains a master replica. See the \*VDCE Directory Service\*O module of the \*VDCE Administration Guide\*O for more information about handling master replicas when deleting a clearinghouse. .SS "Permissions Required" .PP You must have write and delete permission to the clearinghouse and administer permission to all directories that store replicas in the clearinghouse. The server principal needs delete permission to the associated clearinghouse object entry and administer permission to all directories that store replicas in the clearinghouse. .SH "NOTES" .PP It is recommended that you delete all replicas except the root before issuing this command. .zA "defect, 11818, R1.1, Added caveat" .PP This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .wH "" .SH "EXAMPLE" .PP The following command deletes a clearinghouse named \*L/.:/sales/Orion_CH\*O from the local server system: .iS \*Ccdscp>\*L delete clearinghouse \*L/.:/sales/Orion_CH .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lclear clearinghouse(1m)\*O, \*Lcreate clearinghouse(1m)\*O, \*Llist clearinghouse(1m)\*O, \*Lset cdscp preferred clearinghouse(1m)\*O, \*Lshow clearinghouse(1m)\*O, \*Lshow cdscp preferred clearinghouse(1m)\*O .PP Books: \*VDCE Administration Guide\*O .iX "-]" "clearinghouses" "deleting" .iX "-]" "\*Lcdscp\*O commands" "\*Ldelete clearinghouse\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "delete directory"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "directories" "deleting (CDS)" .iX "\*Lcdscp\*O commands" "\*Ldelete directory\*O" .iX "replicas" "deleting" .SH NAME .PP \*Ldelete directory\*O - Deletes a directory .wH "" .SH "SYNOPSIS" .PP \*Lcdscp delete directory\*O \*Vdirectory-name\*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vdirectory-name\*O" The full name of the directory. .wH "" .LE .SH "DESCRIPTION" .PP The \*Ldelete directory\*O command deletes a directory. The directory cannot contain any object entries, soft links, or child pointers. The master replica must be the only remaining replica in the cell. Use the \*Ldelete replica\*O command if you need to remove read-only replicas. .SS "Privilege Required" .PP You must have delete permission to the directory and write permission to the clearinghouse that stores the master replica of the directory. The server principal needs administer permission to the parent directory or delete permission to the child pointer that points to the directory you intend to delete. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command deletes the directory \*L/.:/eng\*O from the namespace: .iS \*Ccdscp>\*L delete directory /.:/eng\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lcreate directory(1m)\*O, \*Ldelete replica(1m)\*O, \*Llist directory(1m)\*O, \*Lset directory(1m)\*O, \*Lset directory to skulk(1m)\*O, \*Lshow directory(1m)\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "delete link"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "soft links" "deleting" .iX "\*Lcdscp\*O commands" "\*Ldelete link\*O" .SH NAME .PP \*Ldelete link\*O - Deletes a soft link .wH "" .SH "SYNOPSIS" .PP \*Lcdscp delete link\*O \*Vlink-name\*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vlink-name\*O" The full name of the soft link. .wH "" .LE .SH "DESCRIPTION" .PP The \*Ldelete link\*O command deletes a soft link. .SS "Privilege Required" .PP You must have delete permission to the soft link, or administer permission to the directory that stores the soft link. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command deletes the soft link \*L/.:/sales/asia\*O. .iS \*Ccdscp>\*L delete link /.:/sales/asia\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lcreate link(1m)\*O, \*Llist link(1m)\*O, \*Lset link(1m)\*O, \*Lshow link(1m)\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "delete object"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "objects" "deleting" .iX "\*Lcdscp\*O commands" "\*Ldelete object\*O" .SH NAME .PP \*Ldelete object\*O - Deletes an object entry .wH "" .SH "SYNOPSIS" .PP \*Lcdscp delete object\*O \*Vobject-name\*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vobject-name\*O" The full name of the object entry. .wH "" .LE .SH "DESCRIPTION" .PP The \*Ldelete object\*O command deletes an object entry. This task is usually done through the client application, except under certain circumstances (for example, if the application is obsolete or no longer has access to the namespace). .SS "Privilege Required" .PP .zA "defect,4524,R1.0.2, Changed permission" You must have delete permission to the object entry, or administer permission to the directory that stores the object entry. .zZ "defect,4524,R1.0.2, Changed permission" .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command deletes the object entry \*L/.:/sales/east/floor1pr2\*O. .iS \*Ccdscp>\*L delete object /.:/sales/east/floor1pr2\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lcreate object(1m)\*O, \*Llist object(1m)\*O, \*Lset object(1m)\*O, \*Lshow object(1m)\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "delete replica" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "replicas" "deleting (CDS)" .iX "\*Lcdscp\*O commands" "\*Ldelete replica\*O" .SH NAME .PP \*Ldelete replica\*O - Deletes a read-only replica of a directory from a clearinghouse .wH "" .SH "SYNOPSIS" .PP \*Lcdscp delete replica\*O \*Vdirectory-name \*Lclearinghouse\*O \*Vclearinghouse-name\*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vdirectory-name\*O" The full name of the directory .LI "\*Vclearinghouse-name\*O" The full name of the clearinghouse .wH "" .LE .SH "DESCRIPTION" .PP The \*Ldelete replica\*O command deletes a read-only replica of a directory from a clearinghouse. Use the \*Ldelete directory\*O command to delete the master replica of the directory. .SS "Privilege Required" .PP You must have administer permission to the directory whose replica you want to delete and write permission to the clearinghouse from which you are deleting the replica. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command deletes a read-only replica of the \*L/.:/mfg\*O directory from the \*L/.:/Paris1_CH\*O clearinghouse: .iS \*Ccdscp>\*L delete replica /.:/mfg clearinghouse /.:/Paris1_CH .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lcreate replica(1m)\*O, \*Ldelete directory(1m)\*O, \*Lshow replica(1m)\*O .wH "" .wH "" .\" $Header: devnm.1m,v 72.7 94/11/28 08:38:38 ssa Exp $ .TA d .TH devnm 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME devnm \- device name .SH SYNOPSIS .C /usr/sbin/devnm .RI [\| name \|... ] .SH DESCRIPTION For each .I name specified, the .C devnm command identifies the special file associated with the mounted file system where the named file or directory resides. .SH EXAMPLES The command: .RS .C /usr/sbin/devnm /usr .RE produces: .RS .C /dev/dsk/c1d0s9 /usr .RE if .C /usr is mounted on .CR /dev/dsk/c1d0s9 . .SH FILES .TP 20 .PD 0 .CR /dev/dsk/* .TP .CR /etc/mnttab Mounted file system table. .PD .SH SEE ALSO brc(1M). .SH STANDARDS COMPLIANCE .CR devnm ": SVID2, SVID3" .\" .\" index@\f4devnm\f1 \- device name@@@\f3devnm(1M)\f1 .\" index@device name@@@\f3devnm(1M)\f1 .\" index@name of device@@@\f3devnm(1M)\f1 .\" .\" toc@\f3devnm(1M)\f1:\0\0\f4devnm\f1@@@device name .\" .\" fileset_database@devnm.1m SYS-ADMIN-MAN .\" $Header: df.1m,v 78.1 95/12/20 10:43:04 ssa Exp $ .TA d .TH df 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME df (generic) \- report number of free file system disk blocks .SH SYNOPSIS .CR /usr/bin/df .RC [ \-F .IR FStype ] .RC [ \-befgiklnv ] .RC [ \-t|-P ] .RC [ \-o .IR specific_options ] .RC [ \-V ] .ifn .br .ifn \0\0\0\0 .RI [ special \(or directory ]...\& .SH DESCRIPTION The .CR df command displays the number of free 512-byte blocks and free inodes available for file systems by examining the counts kept in the superblock or superblocks. If a .I special or a .I directory is not specified, the free space on all mounted file systems is displayed. If the arguments to .CR df are path names, .CR df reports on the file systems containing the named files. If the argument to .CR df is a .I special of an unmounted file system, the free space in the unmounted file system is displayed. .SS Options .CR df recognizes the following options: .RS .TP 15 .CR \-b Report only the number of kilobytes (KB) free. .TP .CR \-e Report the number of files free. .TP .CR \-f Report only the actual count of the blocks in the free list (free inodes are not reported). .TP .CI \-F \0FStype Report only on the .IR FStype file system type (see .IR fstyp (1M)). .TP .CR \-g Report the entire structure described in .IR statvfs (2). .TP .CR \-i Report the total number of inodes, the number of free inodes, number of used inodes, and the percentage of inodes in use. .TP .CR \-k Report the allocation in kilobytes (KB). .TP .CR \-l Report on local file systems only. .TP .CR \-n Report the file system name. If used with no other options, display a list of mounted file system types. .TP .CI \-o \0specific_options Specify options specific to each file system type. .I specific_options is a comma-separated list of suboptions intended for a specific .IR FStype module of the command. See the file-system-specific manual entries for further details. .TP .CR \-P Report the name of the file system, the size of the file system, the number of blocks used, the number of blocks free, the percentage of blocks used and the directory below which the file system hierarchy appears. .TP .CR \-t Report the total allocated block figures and the number of free blocks. .TP .CR \-v Report the percentage of blocks used, the number of blocks used, and the number of blocks free. This option cannot be used with other options. .TP .CR \-V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C df behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH EXAMPLES Report the number of free disk blocks for all mounted file systems: .IP .C "df" .PP Report the number of free disk blocks for all mounted HFS file systems: .IP .C "df \-F hfs" .PP Report the number of free files for all mounted NFS file systems: .IP .C "df \-F nfs \-e" .PP Report the total allocated block figures and the number of free blocks, for all mounted file systems: .IP .C "df \-t" .PP Report the total allocated block figures and the number of free blocks, for the file system mounted as .CR /usr : .IP .C "df \-t /usr" .RE .SH FILES .TP 20 .CR /dev/dsk/* File system devices .PD 0 .TP .CR /etc/fstab Static information about the file systems .PD 0 .TP .CR /etc/mnttab Mounted file system table .PD .SH SEE ALSO du(1), .RI df_ FStype (1M), fsck(1M), fstab(4), fstyp(1M), statvfs(2), mnttab(4). .SH STANDARDS CONFORMANCE .CR df ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f1disk blocks (generic), report number of free file system@@@\f3df(1M)\f1 .\" index@\f1file system disk blocks (generic), report number of free@@@\f3df(1M)\f1 .\" index@\f1report number of free file system disk blocks (generic)@@@\f3df(1M)\f1 .\" index@\f4df\f1 \- report number of free file system disk blocks (generic)@@@\f3df(1M)\f1 .\" .\" toc@\f3df(1M)\f1:\0\0\f4df\f1@@@report number of free file system disk blocks (generic) .\" $Header: df_hfs.1m,v 72.3 94/11/30 14:24:49 ssa Exp $ .TA d .TH df_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME df \- report number of free CDFS, HFS, or NFS file system disk blocks .SH SYNOPSIS .CR /usr/bin/df .RC [ \-F .IR FStype ] .RC [ \-befgiklntv ] .RC [ \-B ] .RC [ \-o .IR specific_options ] .RC [ \-V ] .ifn .br .ifn \0\0\0\0 .RI [ special \(or directory ]...\& .SH DESCRIPTION The .CR df command displays the number of free 512-byte blocks and free inodes available for file systems by examining the counts kept in the superblock or superblocks. If a .I special or a .I directory is not specified, the free space on all mounted file systems is displayed. If the arguments to .CR df are path names, .CR df reports on the file systems containing the named files. If the argument to .CR df is a .I special of an unmounted file system, the free space in the unmounted file system is displayed. .SS Options .CR df recognizes the following options: .RS .TP 15 .CR \-b Report only the number of kilobytes (KB) free. .TP .CR \-B Report the total number of blocks allocated for swapping to the file system as well as the number of blocks free for swapping to the file system. This option is supported on HFS file systems only. .TP .CR \-e Report the number of files free. .TP .CR \-f Report only the actual count of the blocks in the free list (free inodes are not reported). When this option is specified, .CR df reports on raw devices. .TP .CI \-F \0FStype Report only on the .IR FStype file system type (see .IR fstyp (1M)). For the purposes of this manual entry, .IR FStype can be one of .CR cdfs , .CR hfs , and .CR nfs , for the CDFS, HFS, and NFS file systems, respectively. .TP .CR \-g Report the entire structure described in .IR statvfs (2). .TP .CR \-i Report the total number of inodes, the number of free inodes, number of used inodes, and the percentage of inodes in use. .TP .CR \-k Report the allocation in kilobytes (KB). .TP .CR \-l Report on local file systems only. .TP .CR \-n Report the file system name. If used with no other options, display a list of mounted file system types. .TP .CI \-o \0specific_options Specify options specific to the HFS file system type. .I specific_options is a comma-separated list of suboptions. .IP The available suboption is: .RS .RS .TP .CR i Report the number of used and free inodes. .RE .RE .TP .CR \-t Report the total allocated block figures and the number of free blocks. .TP .CR \-v Report the percentage of blocks used, the number of blocks used, and the number of blocks free. This option cannot be used with other options. .TP .CR \-V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .PP When .CR df is used on an HFS file system, the file space reported is the space available to the ordinary user, and does not include the reserved file space specified by .CR fs_minfree . .PP Unreported reserved blocks are available only to users who have appropriate privileges. See .IR fs (4) for information about .CR fs_minfree . .PP When .CR df is used on NFS file systems, the number of inodes is displayed as \(mi1 . This is due to superuser access restrictions over NFS. .SH EXAMPLES Report the number of free disk blocks for all mounted file systems: .IP .C "df" .PP Report the number of free disk blocks for all mounted HFS file systems: .IP .C "df \-F hfs" .PP Report the number of free files for all mounted NFS file systems: .IP .C "df \-F nfs \-e" .PP Report the total allocated block figures and the number of free blocks, for all mounted file systems: .IP .C "df \-t" .PP Report the total allocated block figures and the number of free blocks, for the file system mounted as /usr: .IP .C "df \-t /usr" .SH WARNINGS .CR df does not account for: .RS .TP 3 .PD 0 \(bu Disk space reserved for swap space, .TP \(bu Space used for the HFS boot block (8K bytes, 1 per file system), .TP \(bu HFS superblocks (8K bytes each, 1 per disk cylinder), .TP \(bu HFS cylinder group blocks (1K-8K bytes each, 1 per cylinder group), .TP \(bu Inodes (currently 128 bytes reserved for each inode). .PD .RE .PP Non-HFS file systems may have other items that this command does not account for. .PP The .CR \-b option, from prior releases, has been replaced by the .CR \-B option. .SH FILES .TP 20 .C /dev/dsk/* File system devices. .PD 0 .TP .C /etc/fstab Static information about the file systems .PD 0 .TP .C /etc/mnttab Mounted file system table .PD .SH SEE ALSO du(1), df(1M), fsck(1M), fstab(4), fstyp(1M), statvfs(2), fs(4), mnttab(4). .SH STANDARDS CONFORMANCE .CR df ": SVID2, XPG2, XPG3" .\" .\" index@\f1CDFS file system disk blocks, report number of free@@@\f3df_hfs(1M)\f1 .\" index@\f1HFS file system disk blocks, report number of free@@@\f3df_hfs(1M)\f1 .\" index@\f1NFS file system disk blocks, report number of free@@@\f3df_hfs(1M)\f1 .\" index@\f1disk blocks, report number of free, CDFS, HFS, or NFS file system@@@\f3df_hfs(1M)\f1 .\" index@\f1file system disk blocks, report number of free CDFS, HFS, or NFS@@@\f3df_hfs(1M)\f1 .\" index@\f1report number of free CDFS, HFS, or NFS file system disk blocks@@@\f3df_hfs(1M)\f1 .\" index@\f4df\f1 \- report number of free CDFS, HFS, or NFS file system disk blocks@@@\f3df_hfs(1M)\f1 .\" .\" toc@\f3df_hfs(1M)\f1:\0\0\f4df\f1@@@report number of free CDFS, HFS, or NFS file system disk blocks .\" .\" links@df_hfs.1m df_cdfs.1m .\" links@df_hfs.1m df_nfs.1m .\" $Header: df_hfs.1m,v 72.3 94/11/30 14:24:49 ssa Exp $ .TA d .TH df_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME df \- report number of free CDFS, HFS, or NFS file system disk blocks .SH SYNOPSIS .CR /usr/bin/df .RC [ \-F .IR FStype ] .RC [ \-befgiklntv ] .RC [ \-B ] .RC [ \-o .IR specific_options ] .RC [ \-V ] .ifn .br .ifn \0\0\0\0 .RI [ special \(or directory ]...\& .SH DESCRIPTION The .CR df command displays the number of free 512-byte blocks and free inodes available for file systems by examining the counts kept in the superblock or superblocks. If a .I special or a .I directory is not specified, the free space on all mounted file systems is displayed. If the arguments to .CR df are path names, .CR df reports on the file systems containing the named files. If the argument to .CR df is a .I special of an unmounted file system, the free space in the unmounted file system is displayed. .SS Options .CR df recognizes the following options: .RS .TP 15 .CR \-b Report only the number of kilobytes (KB) free. .TP .CR \-B Report the total number of blocks allocated for swapping to the file system as well as the number of blocks free for swapping to the file system. This option is supported on HFS file systems only. .TP .CR \-e Report the number of files free. .TP .CR \-f Report only the actual count of the blocks in the free list (free inodes are not reported). When this option is specified, .CR df reports on raw devices. .TP .CI \-F \0FStype Report only on the .IR FStype file system type (see .IR fstyp (1M)). For the purposes of this manual entry, .IR FStype can be one of .CR cdfs , .CR hfs , and .CR nfs , for the CDFS, HFS, and NFS file systems, respectively. .TP .CR \-g Report the entire structure described in .IR statvfs (2). .TP .CR \-i Report the total number of inodes, the number of free inodes, number of used inodes, and the percentage of inodes in use. .TP .CR \-k Report the allocation in kilobytes (KB). .TP .CR \-l Report on local file systems only. .TP .CR \-n Report the file system name. If used with no other options, display a list of mounted file system types. .TP .CI \-o \0specific_options Specify options specific to the HFS file system type. .I specific_options is a comma-separated list of suboptions. .IP The available suboption is: .RS .RS .TP .CR i Report the number of used and free inodes. .RE .RE .TP .CR \-t Report the total allocated block figures and the number of free blocks. .TP .CR \-v Report the percentage of blocks used, the number of blocks used, and the number of blocks free. This option cannot be used with other options. .TP .CR \-V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .PP When .CR df is used on an HFS file system, the file space reported is the space available to the ordinary user, and does not include the reserved file space specified by .CR fs_minfree . .PP Unreported reserved blocks are available only to users who have appropriate privileges. See .IR fs (4) for information about .CR fs_minfree . .PP When .CR df is used on NFS file systems, the number of inodes is displayed as \(mi1 . This is due to superuser access restrictions over NFS. .SH EXAMPLES Report the number of free disk blocks for all mounted file systems: .IP .C "df" .PP Report the number of free disk blocks for all mounted HFS file systems: .IP .C "df \-F hfs" .PP Report the number of free files for all mounted NFS file systems: .IP .C "df \-F nfs \-e" .PP Report the total allocated block figures and the number of free blocks, for all mounted file systems: .IP .C "df \-t" .PP Report the total allocated block figures and the number of free blocks, for the file system mounted as /usr: .IP .C "df \-t /usr" .SH WARNINGS .CR df does not account for: .RS .TP 3 .PD 0 \(bu Disk space reserved for swap space, .TP \(bu Space used for the HFS boot block (8K bytes, 1 per file system), .TP \(bu HFS superblocks (8K bytes each, 1 per disk cylinder), .TP \(bu HFS cylinder group blocks (1K-8K bytes each, 1 per cylinder group), .TP \(bu Inodes (currently 128 bytes reserved for each inode). .PD .RE .PP Non-HFS file systems may have other items that this command does not account for. .PP The .CR \-b option, from prior releases, has been replaced by the .CR \-B option. .SH FILES .TP 20 .C /dev/dsk/* File system devices. .PD 0 .TP .C /etc/fstab Static information about the file systems .PD 0 .TP .C /etc/mnttab Mounted file system table .PD .SH SEE ALSO du(1), df(1M), fsck(1M), fstab(4), fstyp(1M), statvfs(2), fs(4), mnttab(4). .SH STANDARDS CONFORMANCE .CR df ": SVID2, XPG2, XPG3" .\" .\" index@\f1CDFS file system disk blocks, report number of free@@@\f3df_hfs(1M)\f1 .\" index@\f1HFS file system disk blocks, report number of free@@@\f3df_hfs(1M)\f1 .\" index@\f1NFS file system disk blocks, report number of free@@@\f3df_hfs(1M)\f1 .\" index@\f1disk blocks, report number of free, CDFS, HFS, or NFS file system@@@\f3df_hfs(1M)\f1 .\" index@\f1file system disk blocks, report number of free CDFS, HFS, or NFS@@@\f3df_hfs(1M)\f1 .\" index@\f1report number of free CDFS, HFS, or NFS file system disk blocks@@@\f3df_hfs(1M)\f1 .\" index@\f4df\f1 \- report number of free CDFS, HFS, or NFS file system disk blocks@@@\f3df_hfs(1M)\f1 .\" .\" toc@\f3df_hfs(1M)\f1:\0\0\f4df\f1@@@report number of free CDFS, HFS, or NFS file system disk blocks .\" .\" links@df_hfs.1m df_cdfs.1m .\" links@df_hfs.1m df_nfs.1m .\" $Header: df_hfs.1m,v 72.3 94/11/30 14:24:49 ssa Exp $ .TA d .TH df_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME df \- report number of free CDFS, HFS, or NFS file system disk blocks .SH SYNOPSIS .CR /usr/bin/df .RC [ \-F .IR FStype ] .RC [ \-befgiklntv ] .RC [ \-B ] .RC [ \-o .IR specific_options ] .RC [ \-V ] .ifn .br .ifn \0\0\0\0 .RI [ special \(or directory ]...\& .SH DESCRIPTION The .CR df command displays the number of free 512-byte blocks and free inodes available for file systems by examining the counts kept in the superblock or superblocks. If a .I special or a .I directory is not specified, the free space on all mounted file systems is displayed. If the arguments to .CR df are path names, .CR df reports on the file systems containing the named files. If the argument to .CR df is a .I special of an unmounted file system, the free space in the unmounted file system is displayed. .SS Options .CR df recognizes the following options: .RS .TP 15 .CR \-b Report only the number of kilobytes (KB) free. .TP .CR \-B Report the total number of blocks allocated for swapping to the file system as well as the number of blocks free for swapping to the file system. This option is supported on HFS file systems only. .TP .CR \-e Report the number of files free. .TP .CR \-f Report only the actual count of the blocks in the free list (free inodes are not reported). When this option is specified, .CR df reports on raw devices. .TP .CI \-F \0FStype Report only on the .IR FStype file system type (see .IR fstyp (1M)). For the purposes of this manual entry, .IR FStype can be one of .CR cdfs , .CR hfs , and .CR nfs , for the CDFS, HFS, and NFS file systems, respectively. .TP .CR \-g Report the entire structure described in .IR statvfs (2). .TP .CR \-i Report the total number of inodes, the number of free inodes, number of used inodes, and the percentage of inodes in use. .TP .CR \-k Report the allocation in kilobytes (KB). .TP .CR \-l Report on local file systems only. .TP .CR \-n Report the file system name. If used with no other options, display a list of mounted file system types. .TP .CI \-o \0specific_options Specify options specific to the HFS file system type. .I specific_options is a comma-separated list of suboptions. .IP The available suboption is: .RS .RS .TP .CR i Report the number of used and free inodes. .RE .RE .TP .CR \-t Report the total allocated block figures and the number of free blocks. .TP .CR \-v Report the percentage of blocks used, the number of blocks used, and the number of blocks free. This option cannot be used with other options. .TP .CR \-V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .PP When .CR df is used on an HFS file system, the file space reported is the space available to the ordinary user, and does not include the reserved file space specified by .CR fs_minfree . .PP Unreported reserved blocks are available only to users who have appropriate privileges. See .IR fs (4) for information about .CR fs_minfree . .PP When .CR df is used on NFS file systems, the number of inodes is displayed as \(mi1 . This is due to superuser access restrictions over NFS. .SH EXAMPLES Report the number of free disk blocks for all mounted file systems: .IP .C "df" .PP Report the number of free disk blocks for all mounted HFS file systems: .IP .C "df \-F hfs" .PP Report the number of free files for all mounted NFS file systems: .IP .C "df \-F nfs \-e" .PP Report the total allocated block figures and the number of free blocks, for all mounted file systems: .IP .C "df \-t" .PP Report the total allocated block figures and the number of free blocks, for the file system mounted as /usr: .IP .C "df \-t /usr" .SH WARNINGS .CR df does not account for: .RS .TP 3 .PD 0 \(bu Disk space reserved for swap space, .TP \(bu Space used for the HFS boot block (8K bytes, 1 per file system), .TP \(bu HFS superblocks (8K bytes each, 1 per disk cylinder), .TP \(bu HFS cylinder group blocks (1K-8K bytes each, 1 per cylinder group), .TP \(bu Inodes (currently 128 bytes reserved for each inode). .PD .RE .PP Non-HFS file systems may have other items that this command does not account for. .PP The .CR \-b option, from prior releases, has been replaced by the .CR \-B option. .SH FILES .TP 20 .C /dev/dsk/* File system devices. .PD 0 .TP .C /etc/fstab Static information about the file systems .PD 0 .TP .C /etc/mnttab Mounted file system table .PD .SH SEE ALSO du(1), df(1M), fsck(1M), fstab(4), fstyp(1M), statvfs(2), fs(4), mnttab(4). .SH STANDARDS CONFORMANCE .CR df ": SVID2, XPG2, XPG3" .\" .\" index@\f1CDFS file system disk blocks, report number of free@@@\f3df_hfs(1M)\f1 .\" index@\f1HFS file system disk blocks, report number of free@@@\f3df_hfs(1M)\f1 .\" index@\f1NFS file system disk blocks, report number of free@@@\f3df_hfs(1M)\f1 .\" index@\f1disk blocks, report number of free, CDFS, HFS, or NFS file system@@@\f3df_hfs(1M)\f1 .\" index@\f1file system disk blocks, report number of free CDFS, HFS, or NFS@@@\f3df_hfs(1M)\f1 .\" index@\f1report number of free CDFS, HFS, or NFS file system disk blocks@@@\f3df_hfs(1M)\f1 .\" index@\f4df\f1 \- report number of free CDFS, HFS, or NFS file system disk blocks@@@\f3df_hfs(1M)\f1 .\" .\" toc@\f3df_hfs(1M)\f1:\0\0\f4df\f1@@@report number of free CDFS, HFS, or NFS file system disk blocks .\" .\" links@df_hfs.1m df_cdfs.1m .\" links@df_hfs.1m df_nfs.1m .\" $Header: df_vxfs.1m,v 78.1 96/02/13 10:24:40 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA d .TH df_vxfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME df (vxfs) \- report number of free disk blocks on a VxFS file system .SH SYNOPSIS .na .nh .C /usr/bin/df .RC [ \|-F\| .CR vxfs\| ] .if \n(hP \{\ .RC [ \|-V\| ] \} .RC [ \-egiklnvtfb ] .RC [ \-o .IR specific_options ] .if n .br .if n \0\0\0\0\0\0\0\0 .if t .br .if t \0\0\0\0\0\0\0\0 .RI [ special | .I directory .IR ...\| ] .ad .hy .SH DESCRIPTION The .CI df command prints the number of free 512-byte blocks and free inodes available for file systems by examining the counts kept in the superblock or superblocks. If a .I special or a .I directory is not specified, the free space on all of the mounted file systems is printed. If the arguments to .C df are pathnames, .C df produces a report on the file system containing the named file. If the argument to .C df is a .IR special , the file system can be an unmounted or mounted file system. .PP On a Version 1 or 2 disk, layout extents smaller than 8 Kbytes may not be usable for all types of allocation, so .C df does not count free blocks in extents below 8 Kbytes when reporting the total number of free blocks. .PP On a Version 2 or 3 disk layout, VxFS dynamically allocates inodes from the pool of free blocks, so the number of free inodes and blocks reported by .C df is an estimate based on the number of free extents and the current ratio of allocated inodes to allocated blocks. Allocating additional blocks may therefore decrease the count of free inodes, and vice versa. .SS Options .C df recognizes the following options: .RS .TP 15 .C \-b Report only the number of kilobytes free. .TP .C \-e Report the number of files free. .TP .C \-f Report only an actual count of the blocks in the free list (free inodes are not reported). When this option is specified, .C df reports on raw devices. .TP .C "\-F vxfs" Specifies the file system type .RI ( vxfs ). .TP .C \-g Report the entire statvfs(2) structure. .TP .C \-i Report the total number of inodes, the number of free inodes, number of used inodes and the percentage of inodes in use. .TP .C \-k Report the allocation in Kbytes. .TP .C \-l Report on local file systems only. .TP .C \-n Report the file system name. If invoked with no other options this option prints a list of mounted file system types. .TP .CI \-o " specific_options" Specifies options specific to the vxfs file system type. .I specific_options is a list of suboptions and/or keyword/attribute pairs intended for the vxfs-specific module of the command. .IP The available option is .RS .TP .C s Print the number of free extents of each size. Free extents are always an integral power of 2 in length, ranging from a minimum of 1 block to the maximum extent size supported by the file system. .RE .TP 15 .C \-t Report the total allocated block figures and the number of free blocks. .TP .C \-v Report the percentage of blocks used, the number of blocks used and the number of blocks free. This option cannot be used with other options. .if \n(hP \{\ .TP .C \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR "/etc/fstab" . This option allows the user to verify the command line. \} .PP There are a number of options that specify output formats, some combinations of which are incompatible. If an incompatible combination is specified, one of the options will override the other(s). .SH EXAMPLES Report the number of free disk blocks for all mounted file systems: .IP .C df .PP Report the number of free extents of each size, for all mounted VxFS file systems: .IP .C df \-F vxfs \-o s .PP Report the number of free files for all mounted VxFS file systems: .IP .C df \-F vxfs \-e .PP Report the total allocated block figures and the number of free blocks, for all mounted file systems: .IP .C df \-t .PP Report the total allocated block figures and the number of free blocks, for the file system mounted as .CR /usr : .IP .C df \-t /usr .RE .SH FILES .TP 20 .C /dev/vg00/\(** File-system devices. .PD 0 .TP .C /dev/dsk/\(** File-system devices. .PD .TP .C /etc/fstab Static information about the file systems. .PD 0 .TP .C /etc/mnttab mounted-file-system table. .PD .SH SEE ALSO du(1), fsck(1M), fs(4), mnttab(4), statvfs(2), df(1M). .SH STANDARDS CONFORMANCE .C df : SVID2, XPG2, XPG3 .\" .\" toc@\f3df_vxfs(1M)\f1:\0\0\f(CWdf\f1@@@report number of free disk blocks on VxFS file system .\" .\" index@\f(CWdf_vxfs\f1 \- report number of free disk blocks on a VxFS file system@@@\f3df_vxfs(1M)\f1 .\" index@\f(CWdf\f1 \- report number of free disk blocks on a VxFS file system@@@\f3df_vxfs(1M)\f1 .\" index@\f1report number of free disk blocks on a VxFS file system@@@\f3df_vxfs(1M)\f1 .\" index@\f1free disk blocks on a VxFS file system@@@\f3df_vxfs(1M)\f1 .\" index@\f1disk blocks on a VxFS file system@@@\f3df_vxfs(1M)\f1 .\" index@\f1VxFS file system, report free disk blocks@@@\f3df_vxfs(1M)\f1 .\" index@\f1file system, report free disk blocks on VxFS@@@\f3df_vxfs(1M)\f1 .\" .\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "dfs_intro" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "Distributed File Service (DFS)" "command syntax" .SH NAME \*Ldfs_intro\*O \- Introduction to the DFS commands .SH "DESCRIPTION" .PP Most DFS commands are divided into the following categories, or command suites: .VL .LI "\*Lbak\*O" Operates the DFS Backup System .LI "\*Lbos\*O" .zA "defect,5790,R1.0.2,Move bos lscell back to Admin Ref" Operates the Basic OverSeer (BOS) Server .zZ "defect,5790,R1.0.2,Move bos lscell back to Admin Ref" .LI "\*Lcm\*O" Configures the Cache Manager .LI "\*Ldfstrace\*)" Provides DFS kernel and server process logging information .LI "\*Lfts\*O" Manipulates filesets .LE .PP .zA "enh,5923,R1.1,remove references to user-level commands" .zA "defect,11180,R1.1,Incorporate DFS/NFS gateway doc" In addition, DFS provides a number of miscellaneous commands (for example, \*Lsalvage\*O and \*Lscout\*O) not associated with a specific command suite. DFS also provides an additional command suite, \*Ldfsgw\*O, that is used with the DFS/NFS Secure Gateway. .PP System administrators use the majority of DFS commands. However, DCE users can use the following commands: .zZ "defect,11180,R1.1,Incorporate DFS/NFS gateway doc" .ML .LI The \*Lcm\*O commands \*Lcm_statservers\*O and \*Lcm_whereis\*O to determine machine, file, and directory information .LI The \*Lfts\*O command \*Lfts_lsquota\*O to check quota information .LE .zZ "enh,5923,R1.1,remove reference to user-level commands" .PP .zA "enh,5923,R1.1,remove references to user-level commands" .zZ "enh,5923,R1.1,remove reference to user-level commands" .SS "DFS Command Types" .PP DFS commands follow these general naming rules. Commands that begin with .ML .LI \*Ladd\*O or \*Lrm\*O (remove) affect lists or groups of DFS objects. For example, \*Lbos addadmin\*O adds an administrative user to an administrative list. .LI \*Lcr\*O (create) or \*Ldel\*O (delete) affect DFS objects. For example, \*Lfts crserverentry\*O creates a DFS object, a server entry. .LI \*Lls\*O (list) are used to display objects and groups of objects. .LI \*Lset\*O are used to assign values to parameters; for example, \*Lfts setrepinfo\*O assigns replication parameters. Analogously, commands beginning with \*Lget\*O are used to display parameters; for example, \*Lcm getcachesize\*O displays parameters used by the Cache Manager. .LE .SS "Rules For Using DFS Commands" .PP When supplying an argument to a command, the option associated with the argument can be omitted if .ML .LI All arguments supplied with the command are entered in the order in which they appear in the command's synopsis. .LI Arguments are supplied for all options that precede the option to be omitted. .LI All options that precede the option to be omitted accept only a single argument. .LI No options, either those that accept an argument or those that do not, are supplied before the option to be omitted. .LE .PP In the case where two options are presented in { | } (braces separated by a vertical bar), the option associated with the first argument can be omitted if that argument is provided; however, the option associated with the second argument is required if that argument is provided. .PP If it must be specified, an option can be abbreviated to the shortest possible form that distinguishes it from other options of the command. For example, the \*L-server\*O option found in many DFS commands can typically be omitted or abbreviated to be simply \*L-s\*O. .PP It is also valid to abbreviate a command name to the shortest form that still distinguishes it from the other command names in the suite. For example, it is acceptable to shorten the \*Lbos install\*O command to \*Lbos i\*O because no other command names in the \*Lbos\*O command suite begin with the letter "i." However, there are three \*Lbos\*O commands that begin with the letter "g": \*Lbos getdates\*O, \*Lbos getlog\*O, and \*Lbos getrestart\*O. To remain unambiguous, they can be abbreviated to \*Lbos getd\*O, \*Lbos getl\*O, and \*Lbos getr\*O. .PP The following examples illustrate three acceptable ways to enter the same \*Lbos getlog\*O command. .PP Complete command: .iS \*C$\*O \*Lbos getlog\*O \*L-server /.../abc.com/hosts/fs1\*O \*L-file BosLog\*O .iE .PP Abbreviated command name and abbreviated options: .iS \*C$\*O \*Lbos getl\*O \*L-s /.../abc.com/hosts/fs1\*O \*L-f BosLog\*O .iE .PP Abbreviated command name and omitted options: .iS \*C$\*O \*Lbos getl\*O \*L/.../abc.com/hosts/fs1\*O \*LBosLog\*O .iE .zA "defect,11180,R1.1,Incorporate DFS/NFS gateway doc" .nS "note" The \*Ldfs_login\*O and \*Ldfs_logout\*O commands provided with the DFS/NFS Secure Gateway do not provide the shortcuts and help available with other DFS commands. See the reference pages for these two commands for information about using them. .nE .zZ "defect,11180,R1.1,Incorporate DFS/NFS gateway doc" .SS "Aliases" .PP An alias is an alternative way of entering an existing command. Each alias is either shorter than the original command, or it is unique within the command's suite (because only the number of characters sufficient to uniquely identify a command need to be entered to execute the command, unique aliases require less typing). .PP The \*Lbak\*O suite is the only command suite with aliases. Refer to the \*Lbak(1m)\*O reference page for a list of the \*Lbak\*O commands that have aliases. .SS "Receiving Help" .PP There are several different ways to receive help about DFS commands. The following list summarizes the syntax for the different help options: .VL .LI "\*LReference pages for a command suite\*O" To view the introductory page for a command suite, enter \*Lman\*O followed by the command suite: .iS \*C$\*O \*Lman bak\*O .iE .LI "\*LReference page for an individual command\*O" To view the reference page for a command in a suite, enter \*Lman\*O followed by the command suite and the command name. Use an _ (underscore) to connect the command suite to the command name. \*EDo not use the underscore when issuing the command in DFS.\*O .iS \*C$\*O \*Lman bak_\*Ecommand\*O .iE .LI "\*LList of commands in a command suite\*O" To view a list of all commands in a command suite, enter the command suite name followed by \*Lhelp\*O: .iS \*C$\*O \*Lbak help\*O .iE .LI "\*LThe command syntax for a single command\*O" To view the syntax of a specific command, enter the suite name, \*Lhelp\*O, and the command name, in that order: .iS \*C$\*O \*Lbak help \*Ecommand\*O .iE .LE .PP In addition, all DFS commands include a \*L-help\*O option you can use to display the syntax of the command. .PP The \*Lapropos\*O command displays the first line of the online help entry for any command that has a specified string in its name or short description; this is useful if you cannot remember the exact name of a command. If the string is more than a single word, surround it with \*L"\|"\*O (double quotes) or other delimiters; enter all strings in lowercase letters. For example, the following command produces a list of all \*Lbos\*O commands with the word \*Lcreate\*O in their names or short descriptions: .iS \*C$\*O \*Lbos apropos -topic create\*O .iE .SS "Privileges Required" .PP The majority of DFS commands, because they are administrative in nature, require that the issuer be included in an \*Ladmin\*O file (for example, \*Ladmin.bos\*O). Some commands require that the issuer have specific permissions to access files (for example, the delete permission on a directory) or be logged in as \*Lroot\*O on the machine on which the command is issued. The exact privilege needed to execute each command is detailed with the command. .SH "CAUTIONS" .PP Specific cautionary information is included with individual commands. .SH "RELATED INFORMATION" .PP For more information about the commands in a specific suite and a list of the commands in the suite, see the introductory page for that suite. .PP \*Lbak(1m)\*O .PP \*Lbos(1m)\*O .PP \*Lcm(1m)\*O .PP \*Ldfstrace(1m)\*O .PP \*Lfts(1m)\*O .iX "-]" "Distributed File Service (DFS)" "command syntax" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "dfsbind" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Ldfsbind\*O command" .iX "-[" "\*Ldfsbind\*O process" .SH NAME .PP .zA "defect,6326,R1.0.2,Update Ubik and related information" \*Ldfsbind\*O \- Provides user-space information to the Cache Manager and File Exporter .zZ "defect,6326,R1.0.2,Update Ubik and related information" .SH "SYNOPSIS" .sS .zA "defect,6594,R1.0.2,Include dfsbind changes" \*Ldfsbind\*O [\*L-expressprocs \*Vnumber_of_express_daemons\*O] .nL [\*L-regularprocs \*Vnumber_of_regular_daemons\*O] [\*L-junctionlife \*Vseconds_to_live\*O] .nL [\*L-prefixlife \*Vseconds_to_live\*O] [\*L-notfoundlife \*Vseconds_to_live\*O] [\*L-debug]\*O [\*L-help\*O] .zZ "defect,6594,R1.0.2,Include dfsbind changes" .sE .SH "OPTIONS" .VL .zA "defect,6594,R1.0.2,Include dfsbind changes" .LI "\*L-expressprocs \*Vnumber_of_express_daemons\*O" Specifies the number of express processes (user-space threads) allocated to handling requests for security information that do not require a substantial amount of time. By default, \*Ldfsbind\*O uses one express process. Use this option to increase the number of express processes if the local machine encounters a large number of time-out errors. Specify an integer greater than 0 (zero) to indicate the number of express processes. .LI "\*L-regularprocs \*Vnumber_of_regular_daemons\*O" Specifies the number of regular processes (user-space threads) allocated to handling requests for CDS pathname resolution and requests for security information that may require significant time. By default, \*Ldfsbind\*O uses one regular process. Use this option to increase the number of regular processes if the local machine experiences a large number of time-out errors. Specify an integer greater than 0 (zero) to indicate the number of regular processes. .LI "\*L-junctionlife \*Vseconds_to_live\*O" Specifies the length of time for which information cached about Fileset Database machines for a cell remains valid. When \*Ldfsbind\*O retrieves this information from the DFS junction of a cell, it sends the information, along with a "time to live" (TTL), to the Cache Manager. The TTL specifies the length of time for which the Cache Manager is to consider the information valid. The Cache Manager caches the information and the TTL. It continues to recognize the information as valid until the TTL expires, after which it asks \*Ldfsbind\*O to refresh the information the next time it needs it. .PP By default, \*Ldfsbind\*O assigns a TTL of 24 hours to information about Fileset Database machines. This option can be used to change the TTL that \*Ldfsbind\*O assigns to such information. Specify an integer greater than or equal to 30 to indicate the new TTL in seconds. \*EThis option has an effect only on DFS client machines, where it is useful primarily for debugging purposes.\*O .LI "\*L-prefixlife \*Vseconds_to_live\*O" Specifies the length of time for which information cached about a pathname that is a valid DFS junction name prefix remains valid. When \*Ldfsbind\*O successfully traverses a given path but the path is not a DFS junction name, it sends the Cache Manager the valid pathname along with a TTL. The Cache Manager caches the information and the TTL, continuing to recognize the information as valid until the TTL expires; it then contacts \*Ldfsbind\*O to refresh the information the next time it needs it. .PP By default, \*Ldfsbind\*O assigns a TTL of 24 hours to information about pathnames that are valid DFS junction name prefixes. This option can be used to change the TTL that \*Ldfsbind\*O assigns to such information. Specify an integer greater than or equal to 30 to indicate the new TTL in seconds. \*EThis option has an effect only on DFS client machines, where it is useful primarily for debugging purposes.\*O .LI "\*L-notfoundlife \*Vseconds_to_live\*O" Specifies the length of time for which information cached about an invalid pathname remains valid. When \*Ldfsbind\*O cannot traverse a given path, it sends the Cache Manager the invalid pathname along with a TTL. The Cache Manager caches the information and the TTL, considering the information valid until the TTL expires; it then contacts \*Ldfsbind\*O to refresh the information the next time it needs it. .PP By default, \*Ldfsbind\*O assigns a TTL of 1 hour to information about invalid pathnames. This option can be used to change the TTL that \*Ldfsbind\*O assigns to such information. Specify an integer greater than or equal to 30 to indicate the new TTL in seconds. \*EThis option has an effect only on DFS client machines, where it is useful primarily for debugging purposes.\*O .zZ "defect,6594,R1.0.2,Include dfsbind changes" .LI "\*L-debug\*O" .zA "defect,6326,R1.0.2,Update Ubik and related information" Provides debugging information about the execution of the command. The primary usage of the information is to ensure that the process is executing properly. If this option is specified, the process does not automatically place itself in the background once it starts. .zZ "defect,6326,R1.0.2,Update Ubik and related information" .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .PP The \*Lhelp\*O and \*Lapropos\*O commands available with all command suites are also available with \*Ldfsbind\*O. See the \*Lbos help\*O and \*Lbos apropos\*O reference pages for examples using these commands. .LE .SH "DESCRIPTION" .PP .zA "defect,6326,R1.0.2,Update Ubik and related information" The \*Ldfsbind\*O command starts the \*Ldfsbind\*O process, which provides user-space services to the Cache Manager on a DFS client machine or the File Exporter on a DFS File Server machine. (The Cache Manager and the File Exporter reside in the kernels of their respective machines.) The binary file for the \*Ldfsbind\*O command resides in \*Edcelocal\*L/bin/dfsbind\*O. By default, the process automatically places itself in the background after it starts. .PP The \*Ldfsbind\*O process must be run on all client machines and File Server machines. A machine that runs the Cache Manager (which is initialized by the \*Ldfsd\*O command) and the \*Ldfsbind\*O process is considered a DFS client machine. A machine that runs the Fileset Server (\*Lftserver\*O process), the File Exporter (which is initialized by the \*Lfxd\*O command), and the \*Ldfsbind\*O process is considered a DFS File Server machine. .PP On either type of machine, the \*Ldfsbind\*O command is usually added to the proper start-up file (\*L/etc/rc\*O or its equivalent) rather than entered at the command shell prompt. On a client machine, the \*Ldfsbind\*O process must be run before the \*Ldfsd\*O process in a start-up file; on a File Server machine, it must be run before the \*Lfxd\*O process in a start-up file. .PP \*EOn a client machine\*O, the \*Ldfsbind\*O process performs the following services: .ML .LI It contacts CDS to resolve DCE pathnames (both local and foreign) that it receives from the Cache Manager. When a user on a client machine requests data that the Cache Manager has not cached, the Cache Manager employs \*Ldfsbind\*O to resolve the pathname of the data. It sends \*Ldfsbind\*O each element of the pathname in succession, appending each new element to the preceding elements when it sends it (for example, it first sends \*L/.../\*Eelement_one\*O, then \*L/.../\*Eelement_one\*L/\*Eelement_two\*O, and so on). In turn, \*Ldfsbind\*O determines whether each successive pathname is valid. .PP If the pathname of the data is valid, it eventually contains a DFS junction from which \*Ldfsbind\*O can access information about the Fileset Database machines for the cell in which the data resides. If it encounters a junction for the DFS filespace, \*Ldfsbind\*O returns information about the names and network addresses of the Fileset Database machines for the cell to the Cache Manager. (It actually decomposes binding handles to learn this information.) The Cache Manager uses the information from \*Ldfsbind\*O to create an RPC binding that it employs to communicate with a Fileset Location (FL) Server on an appropriate Fileset Database machine. The FL Server examines the FLDB and tells the Cache Manager which File Server machine houses the fileset that contains the data requested by the user. .PP For each successive pathname that it attempts to resolve for the Cache Manager, the \*Ldfsbind\*O process returns one of the following error codes to the Cache Manager to indicate the result of the resolution operation: .VL .LI "\*C0\*O" Indicates that the pathname corresponds to a DFS junction that contains information about the Fileset Database machines in the cell. The process sends information about the Fileset Database machines to the Cache Manager. .LI "\*CEISDIR\*O" Indicates that the pathname is a valid DFS junction name prefix but is not itself a DFS junction. The process returns the valid pathname to the Cache Manager. .LI "\*CENOENT\*O" Indicates that the given path could not be traversed. The process returns the invalid pathname to the Cache Manager. .LI "\*CETIMEDOUT\*O" Indicates that unexpected errors occurred. The process returns only the error code to the Cache Manager. .LE .PP .zA "defect,6594,R1.0.2,Include dfsbind changes" DCE pathname and DFS junction information that the Cache Manager receives from \*Ldfsbind\*O is valid for a limited amount of time. The \*Ldfsbind\*O process associates a "time to live" (TTL) with all information it sends to the Cache Manager. The TTL defines the amount of time for which the Cache Manager is to consider the information valid. The Cache Manager caches the TTL with the information. Once its TTL has elapsed, the information becomes stale; the Cache Manager contacts \*Ldfsbind\*O to refresh the information the next time it needs it. .PP The \*Ldfsbind\*O process associates the following TTLs with the information it passes to the Cache Manager: .ML .LI Information about Fileset Database machines (error code \*C0\*O) receives a TTL of 24 hours by default. (The TTL of such information can be modified with the \*Ldfsbind\*O command's \*L-junctionlife\*O option.) .LI Information about valid DFS junction name prefixes (error code \*CEISDIR\*O) has a TTL of 24 hours by default. (The TTL of this type of information can be changed with the command's \*L-prefixlife\*O option.) .LI Information about invalid pathnames (error code \*CENOENT\*O) has a TTL of 1 hour by default. (The TTL of this type of information can be altered with the command's \*L-notfoundlife\*O option.) .LE .PP For example, when the Cache Manager first needs to access data from a fileset in the local cell, it passes each successive element of the DCE pathname of the data to \*Ldfsbind\*O. If the path contains a DFS junction name, \*Ldfsbind\*O eventually returns information about the local cell's Fileset Database machines, and a TTL that it assigns to the information, to the Cache Manager. The Cache Manager caches the information and the TTL, using the information to contact a Fileset Database machine in the cell. If the Cache Manager needs to access data from a fileset in the local cell before the TTL has elapsed, it uses the cached information to contact a Fileset Database machine in the cell. However, if it needs to access data from a fileset in the local cell after the TTL has elapsed, it again contacts \*Ldfsbind\*O to refresh its knowledge of local Fileset Database machines. .zZ "defect,6594,R1.0.2,Include dfsbind changes" .LI It obtains user authentication information for the kernel RPC Runtime. It communicates with the Security Service of the appropriate cell to obtain authentication information about users of the client machine. .PP The Cache Manager communicates with the kernel RPC Runtime when it needs to create an RPC binding to a File Server machine on behalf of a user. The kernel RPC Runtime then communicates with \*Ldfsbind\*O to obtain authentication information about the user for use in the binding. The \*Ldfsbind\*O process obtains the authentication information from the Security Server and sends it back to the kernel RPC Runtime, which packages the information along with the other information from the Cache Manager into the RPC binding and sends it to the appropriate File Server machine. .LE .PP \*EOn a File Server machine\*O, the \*Ldfsbind\*O process simply maintains user authentication information required by the File Exporter on the machine. The File Exporter uses this information to ensure that only authenticated users access data from the machine. .PP .zA "defect,6594,R1.0.2,Include dfsbind changes" The command's \*L-expressprocs\*O and \*L-regularprocs\*O options can be used to change the default number of processes \*Ldfsbind\*O runs on a machine as follows: .ML .LI The \*L-expressprocs\*O option specifies the number of express processes that \*Ldfsbind\*O allocates for the handling of requests that require little time to complete. For example, express processes service requests for information from the local Security Service. The \*Ldfsbind\*O process can typically handle these types of requests more quickly than it can those assigned to regular processes. .LI The \*L-regularprocs\*O option specifies the number of regular processes that \*Ldfsbind\*O allocates for the handling of requests that may require a substantial amount of time to complete. For example, regular processes service requests for the resolution of DCE pathnames and for information from the Security Service of a foreign cell. The \*Ldfsbind\*O process typically requires more time to handle these types of requests than it does to handle requests assigned to express processes. .LE .PP Employing two types of processes allows \*Ldfsbind\*O to function more efficiently. Requests are assigned to processes according to the amount of time they require to complete. Thus, requests with short turnaround times are not queued behind requests with long turnaround times. Increase the number of express and regular daemons on a machine that experiences a large number of time-out (\*CETIMEDOUT\*O) errors. (Note that both express and regular processes run as threads rather than processes, so neither type of process shows up in the output of the \*Lps\*O command or its equivalent.) .zZ "defect,6594,R1.0.2,Include dfsbind changes" .PP If the \*L-debug\*O option is included with the \*Ldfsbind\*O command, the process provides debugging information as it executes. The debugging output is in the form of brief messages reporting the action currently being performed. The messages are useful primarily to ensure that the process is executing properly. If the \*L-debug\*O option is included with the command, the process does not automatically place itself in the background after it starts. .zZ "defect,6326,R1.0.2,Update Ubik and related information" .SS "Privilege Required" .PP The issuer must be logged in as \*Lroot\*O on the local machine. .SH "EXAMPLES" .PP .zA "defect,6594,R1.0.2,Include dfsbind changes" The following line, entered in the appropriate initialization file (\*L/etc/rc\*O or its equivalent) on a client or File Server machine, starts the \*Ldfsbind\*O process on the local machine. This line must be included before the line that starts the \*Ldfsd\*O or \*Lfxd\*O process on a client or File Server machine. The \*Ldfsbind\*O process in the example uses one express process and one regular process (the defaults). .zZ "defect,6594,R1.0.2,Include dfsbind changes" .iS dfsbind .iE .SH "RELATED INFORMATION" .PP Commands: \*Ldfsd(1m)\*O, \*Lfxd(1m)\*O .iX "-]" "\*Ldfsbind\*O command" .iX "-]" "\*Ldfsbind\*O process" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "dfsd" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Ldfsd\*O command" .iX "-[" "Cache Manager" "initializing" .SH NAME .PP \*Ldfsd\*O \- Initializes the DFS Cache Manager and starts related daemons .SH "SYNOPSIS" .sS .zA "defect,9333,R1.0.3,Correct dfsd changes" .zA "defect,9241,R1.0.3,Document namecachesize option" \*Ldfsd\*O [\*L-blocks \*Vnumber_of_cache_blocks\*O] [\*L-files \*Vnumber_of_cache_files\*O] .nL [\*L-stat \*Vnumber_of_status_cache_entries\*O] [\*L-rootfileset \*Vroot_fileset\*O] .nL [\*L-cachedir \*Vcache_directory\*O] [\*L-mountdir \*EDFS_mount_directory\*O] .nL [\*L-rootcell \*Vroot_cell\*O] [\*L-settime\*O] .nL [\*L-mainprocs \*Vnumber_of_background_daemons\*O] .nL [\*L-tokenprocs \*Vnumber_of_token_daemons\*O] .nL [\*L-ioprocs \*Vnumber_of_I/O_background_daemons\*O] .nL [\*L-memcache\*O] [\*L-dcache \*Vnumber_of_entries\*O] .nL [\*L-chunksize \*Vchunk_exponent\*O] .nL [\*L-namecachesize \*Vnumber_of_name_cache_entries\*O] .nL [\*L-verbose\*O] [\*L-debug\*O] [\*L-help\*O] .zZ "defect,9241,R1.0.3,Document namecachesize option" .zZ "defect,9333,R1.0.3,Correct dfsd changes" .sE .SH "OPTIONS" .VL .LI "\*L-blocks \*Vnumber_of_cache_blocks\*O" Specifies the number of kilobytes to be made available for caching in the machine's cache directory (for a disk cache) or memory (for a memory cache). This value overrides the default, which must be specified in the third field of the \*Edcelocal\*L/etc/CacheInfo\*O file. The unit of measurement for block size is always kilobytes. .PP .zA "enh,R1.0.2,Add details" A disk cache should not exceed 90% of the disk space available on the cache partition; a memory cache should not exceed 20 to 25% of the machine's available memory. These limits are necessary because the implementation of the cache requires a small amount of disk space or machine memory, and because a memory cache must leave enough memory for processes and applications to run. .zZ "enh,R1.0.2,Add details" .PP For a memory cache, do not combine this option with the \*L-dcache\*O option. .zA "defect,8320,R1.0.3,Document minimum cache size" .nS "note" The minimum cache size you can specify with the \*L-blocks\*O option is 17 kilobytes. If you specify a cache size smaller than 17 kilobytes, the Cache Manager creates a cache of 17 kilobytes. .nE .zZ "defect,8320,R1.0.3,Document minimum cache size" .LI "\*L-files \*Vnumber_of_cache_files\*O" .zA "defect,7219,R1.0.2,Review comments" Specifies the number of V files (chunks) to be created in the cache directory for a disk cache. This value overrides the default, which is the number of cache blocks divided by 8. .zZ "defect,7219,R1.0.2,Review comments" .PP Each V file can accommodate a chunk of data. By default, each chunk can accommodate 64 kilobytes of data. To operate most efficiently, at least 90 percent of the cache must be in use. Use the \*L-files\*O option to increase the number of V files if this is not the case. Do not specify a value greater than 32,000. .PP Do not combine this option with the \*L-memcache\*O option, which is used for memory caching. .zA "defect,8320,R1.0.3,Document minimum cache size" .nS "note" The minimum number of V files you can specify with the \*L-files\*O option is 2. If you specify a value smaller than 2, the Cache Manager creates a cache with two V files. .nE .zZ "defect,8320,R1.0.3,Document minimum cache size" .LI "\*L-stat \*Vnumber_of_status_cache_entries\*O" Specifies the number of entries in the machine's memory for recording status information about DFS files in the cache. The default is 300. .LI "\*L-rootfileset \*Vroot_fileset\*O" Names the read/write fileset corresponding to the top-level (\*Lroot\*O) directory. This option is generally used for testing purposes only. .LI "\*L-cachedir \*Vcache_directory\*O" .zA "defect,5125,R1.0.2,Clarify cache dir and memory cache" .zA "defect,6062,R1.0.2,Remove cm debug command" Names the local disk directory to be used as the cache for disk caching. This value overrides the default, which must be specified in the second field of the \*LCacheInfo\*O file. The default is \*Edcelocal\*L/var/adm/dfs/cache\*O. .PP Do not combine this option with the \*L-memcache\*O option, which is used for memory caching. With memory caching, the \*L-cachedir\*O option, like the second field of the \*LCacheInfo\*O file, is ignored. .zZ "defect,6062,R1.0.2,Remove cm debug command" .zZ "defect,5125,R1.0.2,Clarify cache dir and memory cache" .LI "\*L-mountdir \*VDFS_mount_directory\*O" Names the local disk directory where the DCE global namespace is to be mounted. This value overrides the default, which must be specified in the first field of the \*LCacheInfo\*O file. The default for a machine with a disk is the global namespace designation (\*L/...\*O); if \*L/...\*O is not used, symbolic links to the global namespace will not work. .zA "enh, 10306, R1.1, remove diskless documentation" .LI "\*L-rootcell \*Vroot_cell\*O" Names the cell that contains the root fileset. This option is generally used for testing purposes only. .cS Use this option only with a DCE diskless machine. .cE .zZ "enh, 10306, R1.1, remove diskless documentation" .LI "\*L-settime\*O" Causes the local machine to select a random server machine in the local cell to use as the source of the correct time. If this option is specified, the local machine selects a server machine and checks the time on that machine every 10 minutes. If the time on the local machine differs by more than 2 seconds from the time on the selected server machine, the local machine adjusts its time to match that of the server machine. .PP .zA "defect,7219,R1.0.2,Review comments" For machines running the DCE Distributed Time Service (DTS) or the Network Time Protocol (NTP), it is recommended that the \*L-settime\*O option be omitted to prevent the machine from selecting and using two different time standards at once. .zZ "defect,7219,R1.0.2,Review comments" .LI "\*L-mainprocs \*Vnumber_of_background_daemons\*O" Specifies the number of background daemons to run on the machine. These daemons improve efficiency by performing prefetching and background writing of saved data. The default is two. .PP Increase the number of background daemons if the machine serves more than five users. .LI "\*L-tokenprocs \*Vnumber_of_token_daemons\*O" .zA "defect,6888,R1.0.2,Correct -tokenprocs descriptions" Specifies the number of background daemons dedicated to servicing token revocation RPC requests from File Exporters. The default is two. (Token daemons run in addition to the background daemons associated with the \*L-mainprocs\*O option.) .PP Increase the number of token daemons if users on this machine interact with many File Server machines. .zZ "defect,6888,R1.0.2,Correct -tokenprocs descriptions" .LI "\*L-ioprocs \*Vnumber_of_I/O_background_daemons\*O" .zA "defect,6811,R1.0.2,-ioprocs works only on AIX" \*EOn a machine running the AIX operating system\*O, specifies the number of background I/O daemons performing I/O operations. I/O daemons move data from disk to memory, and vice versa. The default is five. .PP On a machine running AIX, increase the number of I/O daemons if many users use the machine. \*EUse this option only on a machine running AIX.\*O Because no I/O daemons are used on a machine not running AIX, the option is ignored if it is used on a non-AIX machine. .zZ "defect,6811,R1.0.2,-ioprocs works only on AIX" .LI "\*L-memcache\*O" .zA "defect,5125,R1.0.2,Clarify cache dir and memory cache" Causes \*Ldfsd\*O to initialize a memory cache rather than a disk cache. If this option is provided, space in memory is allocated for the cache; no disk space is used, even if it is available. .PP Do not combine this option with the \*L-files\*O option (which is used for machines that use disk caching). Also, do not combine this option with the \*L-cachedir\*O option; with memory caching, the \*L-cachedir\*O option, like the second field of the \*LCacheInfo\*O file, is ignored. .zZ "defect,5125,R1.0.2,Clarify cache dir and memory cache" .LI "\*L-dcache \*Vnumber_of_entries\*O" Sets the number of dcache entries in memory; dcache entries store information about cache chunks. .PP For a disk cache, the \*Edcelocal\*L/var/adm/dfs/cache/CacheItems\*O file contains one entry for each V file. By default, 100 entries from the \*LCacheItems\*O file are duplicated in machine memory; the \*L-dcache\*O option overrides the default. .PP For a memory cache, there is no \*LCacheItems\*O file; one dcache entry exists for each cache chunk. The Cache Manager determines the number of dcache entries (cache chunks) by dividing the cache size by the chunk size; the \*L-dcache\*O option sets the number of cache chunks. Do not combine this option with the \*L-blocks\*O option. .PP Use of this option with a disk cache is not necessary because it increases performance only marginally. It is not recommended with a memory cache because it requires the issuer to perform additional calculations. .LI "\*L-chunksize \*Vchunk_exponent\*O" .zA "defect,7219,R1.0.2,Review comments" Sets the size of each cache chunk. Provide an integer between 13 and 18 to be used as an exponent of 2. This value overrides the default chunk size, which is 64 kilobytes (2\u\s-4\&16\s0\d) for a disk cache and 8 kilobytes (2\u\s-4\&13\s0\d) for a memory cache. A value less than 13 or greater than 18 sets the chunk size to the appropriate default for the type of cache in use. The unit of measure for chunk size is always bytes. .zZ "defect,7219,R1.0.2,Review comments" .PP It is not recommended that you use this option with the \*L-dcache\*O option for a memory cache. .zA "defect,9333,R1.0.3,Correct dfsd changes" .zA "defect,9241,R1.0.3,Document namecachesize option" .LI "\*L-namecachesize \*Vnumber_of_name_cache_entries\*O" Sets the number of entries allocated for the Cache Manager's name lookup cache. Provide an integer greater than 0 (zero); the default number of name cache entries is 256. .PP The name lookup cache stores the results obtained from remote directory lookup requests to DFS servers, which allows subsequent lookup requests for the same file or directory to be satisfied on the local DFS client rather than on the remote DFS server. Because name cache entries are recycled when the name lookup cache limit is reached, the ability to satisfy the request locally depends upon the size of the name lookup cache. .zZ "defect,9241,R1.0.3,Document namecachesize option" .zZ "defect,9333,R1.0.3,Correct dfsd changes" .LI "\*L-verbose\*O" .zA "enh,R1.0.2,Clarify small detail" Directs \*Ldfsd\*O to produce a more detailed trace of its activities than it does by default. The trace is displayed on standard output (\*Lstdout\*O) unless it is directed elsewhere. .zZ "enh,R1.0.2,Clarify small detail" .LI "\*L-debug\*O" .zA "enh,R1.0.2,Clarify small detail" Causes \*Ldfsd\*O to produce a highly detailed trace of its activities, which can be useful for debugging purposes. The trace is displayed on standard output (\*Lstdout\*O) unless it is directed elsewhere. .zZ "enh,R1.0.2,Clarify small detail" .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .PP The \*Lhelp\*O and \*Lapropos\*O commands available with all command suites are also available with \*Ldfsd\*O. See the \*Lbos help\*O and \*Lbos apropos\*O reference pages for examples using these commands. .LE .SH "DESCRIPTION" .iX "-[" "\*Ldfsd\*O process" "functions" .zA "enh,R1.0.2,Correct daemons index references" ...\" These index entries removed because they are not in the master index. .zZ "enh,R1.0.2,Correct daemons index references" .PP .zA "enh,R1.0.2,Editorial changes" The \*Ldfsd\*O process initializes the DFS Cache Manager on a client machine according to the information specified with the options described previously. It must be run on all DFS client machines. It is usually added to the proper start-up file (\*L/etc/rc\*O or its equivalent) rather than typed at the command shell prompt. (The \*Ldfsbind\*O process must be run before the \*Ldfsd\*O process in a start-up file.) The binary file for the \*Ldfsd\*O process resides in \*Edcelocal\*L/bin/dfsd\*O. .PP Specifically, the \*Ldfsd\*O process .zZ "enh,R1.0.2,Editorial changes" .ML .LI .zA "defect,6326,R1.0.2,Update Ubik and related information" Transfers information about cell membership to kernel memory. This information can be changed only by rebooting and running \*Ldfsd\*O. .zZ "defect,6326,R1.0.2,Update Ubik and related information" .LI .zA "defect,5125,R1.0.2,Clarify cache dir and memory cache" Determines if the cache is on the local disk or in machine memory. A disk cache is used unless the \*L-memcache\*O option is provided. If the \*L-memcache\*O option is used, no disk space is used, even if it is available; the Cache Manager maintains all cached data and cache-related information in memory. .zZ "defect,5125,R1.0.2,Clarify cache dir and memory cache" .LI Defines the name of the local disk directory devoted to a disk cache. The second field in the \*LCacheInfo\*O file specifies the default directory. If necessary, \*Ldfsd\*O creates the directory, provided its parent directory exists. Any directory that formerly served as the disk cache is left on the disk. .LI Sets the size of the cache. The third field in the \*LCacheInfo\*O file specifies the default cache size in kilobytes. .PP For a disk cache, the value in the \*LCacheInfo\*O file is an upper limit that can be increased only with the \*L-blocks\*O option; it cannot be increased with the other options available with the \*Ldfsd\*O process. For a memory cache, the \*L\-dcache\*O option alone or in combination with the \*L-chunksize\*O option overrides the cache size specified in the \*LCacheInfo\*O file; these combinations are not recommended. .PP .zA "enh,R1.0.2,Add details" After initialization, use the \*Lcm setcachesize\*O command to change the size of a disk cache without rebooting. The value set with the \*Lcm setcachesize\*O command is overridden the next time the machine is rebooted and \*Ldfsd\*O is run. The \*Lcm setcachesize\*O command does not work for memory caches; the machine must be rebooted. (The \*Lcm getcachesize\*O command can be used to display the current size of the cache, the amount in use, and the type of cache \(em disk or memory.) .zZ "enh,R1.0.2,Add details" .LI Sets the size of each chunk of data in the cache and, by implication, the amount of data the Cache Manager requests at one time from the File Exporter. For a memory cache, if the total cache size divided by the chunk size leaves a remainder, \*Ldfsd\*O rounds the number down, resulting in a slightly smaller cache. .LI .zA "enh,R1.0.2,Add details" Sets the number of dcache entries allocated in machine memory for storing information about the cache chunks in a disk cache. .zZ "enh,R1.0.2,Add details" .LI Sets the number of empty V files created in the cache directory for a disk cache. (A memory cache cannot use V files because it does not use disk storage; the number of chunks is instead equal to the number of dcache entries.) .LI Sets the number of stat entries in machine memory for caching status information about cached DFS files. .zA "defect,9241,R1.0.3,Document namecachesize option" .LI Sets the number of entries in the name lookup cache for storing the results of remote directory lookups. .zZ "defect,9241,R1.0.3,Document namecachesize option" .LI Specifies the directory on the machine's local disk where DFS is mounted. The first field in the \*LCacheInfo\*O file specifies the default directory. .zA "enh, 10306, R1.1, remove diskless documentation" .cS .LI Specifies the read/write fileset that corresponds to the root of the DFS file tree for a diskless machine. For a diskless machine, use the \*L-rootfileset\*O option to specify the fileset that serves as the top-level directory. This overrides the default specified in the first field of the \*LCacheInfo\*O file. .LI Specifies the name of the cell containing the root fileset. For a DCE diskless machine, use the \*L-rootcell\*O option to specify the name of the cell that contains the root fileset. .cE .zZ "enh, 10306, R1.1, remove diskless documentation" .LI Selects a random server machine in the local cell as the source of the correct time if the \*L\-settime\*O option is provided. .zA "defect,6062,R1.0.2,Remove cm debug command" .zZ "defect,6062,R1.0.2,Remove cm debug command" .LE .PP In addition to setting cache configuration parameters, \*Ldfsd\*O also starts the following types of daemons. On most system types, these daemons appear as nameless entries in the output of the \*Lps\*O command. .ML .LI .zA "defect,7219,R1.0.2,Review comments" One or more maintenance daemons, which perform routine periodic maintenance tasks such as .zZ "defect,7219,R1.0.2,Review comments" .ML .LI Performing garbage collection .LI Synchronizing files .LI Probing processes on File Server machines every few minutes .LI Refreshing information about filesets referenced by the Cache Manager once per hour .LI .zA "enh,R1.0.2,Clarify small detail" Keeping the machine's clock synchronized with that of the chosen server machine (if the \*L-settime\*O option is included with the \*Ldfsd\*O command) .zZ "enh,R1.0.2,Clarify small detail" .LE .LI One or more background daemons, which improve performance by performing delayed writing of updated data. The default number of background daemons is two, which is usually sufficient to handle up to five simultaneous users of a machine. Use the \*L\-mainprocs\*O option to increase the number of background daemons if the machine serves more than five users. .LI .zA "defect,6888,R1.0.2,Correct -tokenprocs descriptions" One or more token daemons, which handle token revocation RPC requests from the File Exporters on File Server machines (for example, by writing modified data back to the File Server machines). The default number of token daemons is two. Use the \*L\-tokenprocs\*O option to increase this number if the machine interacts with many File Server machines from different cells. .zZ "defect,6888,R1.0.2,Correct -tokenprocs descriptions" .LI .zA "defect,6811,R1.0.2,-ioprocs works only on AIX" \*EOn a machine running the AIX operating system\*O, one or more I/O daemons, which move data from disk to memory and from memory to disk. The default number of I/O daemons is five. Use the \*L\-ioprocs\*O option to increase the number of I/O daemons performing I/O requests if the number of users working on the machine increases and the machine begins to experience performance problems. .PP \*EUse the \*L-ioprocs\*E option only on a machine running AIX.\*O No I/O daemons are used on a machine not running AIX; the option is ignored if it is used on such a machine. .zZ "defect,6811,R1.0.2,-ioprocs works only on AIX" .LE .PP .zA "defect,7219,R1.0.2,Review comments" The default number of daemons is ten (one maintenance daemon, two background daemons, two token daemons, and five I/O daemons). You can alter only the number of background daemons, token daemons, and I/O daemons; \*Ldfsd\*O initializes additional maintenance daemons as necessary. .iX "-]" "\*Ldfsd\*O process" "functions" .zZ "defect,7219,R1.0.2,Review comments" .zA "enh,R1.0.2,Editorial changes" .zZ "enh,R1.0.2,Editorial changes" .SS "Privilege Required" .PP The issuer must be logged in as \*Lroot\*O on the local machine. .SH "EXAMPLES" .PP It is recommended that the \*Ldfsd\*O process be included in the proper initialization file (\*L/etc/rc\*O or its equivalent) rather than typed at the command shell prompt. The \*Ldfsbind\*O process must be run before the \*Ldfsd\*O process in a start-up file. For most disk caches, the following form is appropriate in the initialization file: .iS \*Edcelocal\*O/bin/dfsd\*O .iE .PP The following line in an initialization file is appropriate when enabling a machine to serve more than five users: .iS \*Edcelocal\*O/bin/dfsd -mainprocs 4\*O .iE .PP The following line in an initialization file initializes a memory cache and sets the chunk size to 16 kilobytes (2\u\s-4\&14\s0\d): .iS \*Edcelocal\*O/bin/dfsd -memcache -chunksize 14\*O .iE .SH "RELATED INFORMATION" .PP .zA "enh,R1.0.2,Add other cache-related files" .zA "defect,6062,R1.0.2,Remove cm debug command" Commands: \*Lcm getcachesize(1m)\*O, \*Lcm setcachesize(1m)\*O, \*Ldfsbind(1m)\*O .PP Files: \*LCacheInfo(4)\*O, \*LCacheItems(4)\*O, \*LFilesetItems(4)\*O, \*LVn(4)\*O .zZ "defect,6062,R1.0.2,Remove cm debug command" .zZ "enh,R1.0.2,Add other cache-related files" .iX "-]" "\*Ldfsd\*O command" .iX "-]" "Cache Manager" "initializing" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for .\" the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright (C) 1989, 1991, Transarc Corporation ...\" The Gulf Tower ...\" 707 Grant Street ...\" Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "dfstrace" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "defect,6222,R1.0.3,Document the DFS trace facility" .iX "-[" "\*Ldfstrace\*O command suite" "syntax" .SH NAME .PP \*Ldfstrace\*O \- Introduction to the \*Ldfstrace\*O command suite .SH "OPTIONS" .PP The following options are used with many \*Ldfstrace\*O commands. They are also listed with the commands that use them. .VL .LI "\*L\-set\*O \*Vset_name\*O" Specifies the name of an event set to be utilized by the command. An event set is a module designed to track specific events within the DFS kernel or within one or more server processes. Each event set generates trace messages relative to the type of events that it tracks and writes information on each event to from one to eight trace logs. Tracing by event set allows users of the \*Ldfstrace\*O commands to more quickly isolate and diagnose a problem. .PP Following are some of the DFS kernel event sets that you can see: .ML .LI cm \- Cache Manager package .LI fshost \- File exporter host package .LI fx \- File exporter package .LI episode/anode \- LFS anode package .LI episode/logbuf \- LFS buffer/logging package .LI episode/vnops \- LFS vnode package .LI tkc \- Token cache package .LI tkm \- Token manager package .LI tpq \- Thread pool queue package .LI xops \- Vnode-to-fileset synchronization package .LE .PP Following are some of the server process event sets that you can see: .ML .LI bosserver \- \*Lbosserver\*O package .LI dacl \- DFS ACL package .LI dfsauth \- DFS security package .LI flserver \- \*Lflserver\*O package .LI ftserver \- \*Lftserver\*O package .LI ftutil \- Fileset utility package .LI ubikdisk \- Disk I/O subset of Ubik package .LI ubikvote \- Sync site election subset of Ubik package .LE .LI "\*L\-log\*O \*Vlog_name\*O" Specifies the name of a server process or kernel trace log to be utilized by the command. All logs are stored in kernel or server process memory that is allocated on the initialization of the kernel or server process. The default size of a log, which is measured in 4-kilobyte units (kwords), is predefined; however, this size can be changed by a system administrator. Any number of event sets can write to a single log. .LI "\*L\-cdsentry\*O \*Vserver_entry_in_CDS\*O" Specifies the name of a server process to which to connect. This option is required when performing operations on server process logs and event sets; it must be omitted when performing operations on kernel logs and event sets. The full DCE pathname of a server process must be specified with this option (\*L/.:/hosts/\*Vmachine\*L/\*Vprocess_name\*O). .LI "\*L\-help\*O" Prints the online help for the command. All other valid options specified with this option are ignored. For complete details about receiving help, see the \*Ldfs_intro(1m)\*O reference page. .LE .SH "DESCRIPTION" .PP Command in the \*Ldfstrace\*O command suite are used by system administrators to diagnose problems within the DFS kernel or within the server processes that interface with the \*Ldfstrace\*O command suite. This diagnosis is performed by reading the output of trace logs containing diagnostic messages written by event sets that track specific actions performed by the DFS kernel or a server process. .PP The commands in the \*Ldfstrace\*O command suite allow you to perform the following functions: .ML .LI List information about event sets (using the \*Ldfstrace lsset\*O command) .LI Set an event set's state (using the \*Ldfstrace setset\*O command) .LI List information about trace logs (using the \*Ldfstrace lslog\*O command) .LI Change the size of trace logs (using the \*Ldfstrace setlog\*O command) .LI Dump the contents of trace logs (using the \*Ldfstrace dump\*O command) .LI Clear trace logs (using the \*Ldfstrace clear\*O command) .LE .SS "Receiving Help" .PP There are several different ways to receive help about DFS commands. The following examples summarize the syntax for the different help options: .VL .LI "\*C$\*O \*Lman dfstrace\*O" Displays the reference page for the command suite. .LI "\*C$\*O \*Lman dfstrace_\*Vcommand\*O" Displays the reference page for an individual command. You must use an _ (underscore) to connect the command suite to the command name. \*EDo not use the underscore when issuing the command in DFS.\*O .LI "\*C$\*O \*Ldfstrace help\*O" Displays a list of commands in a command suite. .LI "\*C$\*O \*Ldfstrace help \*Vcommand\*O" Displays the syntax for a single command. .LI "\*C$\*O \*Ldfstrace apropos -topic \*Vstring\*O" Displays a short description of any commands that match the specified \*Vstring\*O. .LE .PP Consult the \*Ldfs_intro(1m)\*O reference page for complete information about the DFS help facilities. .SS "Privilege Required" .PP Except for the \*Ldfstrace help\*O and \*Ldfstrace apropos\*O commands, which require no privilege, executing the \*Ldfstrace\*O commands require one of the following two types of privilege, depending on the operation being performed: .ML .LI If the \*Ldfstrace\*O command is executed on a kernel log or event set, the issuer must be logged in as \*Lroot\*O on the local machine. .LI If the \*Ldfstrace\*O command is executed on a server process log or event set, the issuer must be listed in the admin list associated with that process on the machine specified with the \*L\-cdsentry\*O option (for example, \*Ladmin.fl\*O for the \*Lflserver\*O process and \*Ladmin.ft\*O for the \*Lftserver\*O process). .LE Specific privilege information is listed with each command's description. In addition, if the BOS Server, on the same machine as a server process, is running with DFS authorization checking disabled, no privilege is required to issue \*Ldfstrace\*O commands on the event sets and logs associated with that server process. .SH "RELATED INFORMATION" Commands: \*Ldfs_intro(1m)\*O, \*Ldfstrace apropos(1m)\*O, \*Ldfstrace clear(1m)\*O, \*Ldfstrace dump(1m)\*O, \*Ldfstrace help(1m)\*O, \*Ldfstrace lslog(1m)\*O, \*Ldfstrace lsset(1m)\*O, \*Ldfstrace setlog(1m)\*O, \*Ldfstrace setset(1m)\*O .iX "-]" "\*Ldfstrace\*O command suite" "syntax" .zZ "defect,6222,R1.0.3,Document the DFS trace facility" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for .\" the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright (C) 1989, 1991, Transarc Corporation ...\" The Gulf Tower ...\" 707 Grant Street ...\" Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "dfstrace apropos" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "defect,6222,R1.0.3,Document the DFS trace facility" .iX "-[" "\*Ldfstrace\*O command suite" "\*Lapropos\*O" .SH NAME .PP \*Ldfstrace apropos \*O \- Shows each help entry containing a specified string .SH "SYNOPSIS" .PP .sS \*Ldfstrace apropos -topic\*O \*Vstring\*O [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-topic \*Vstring\*O" Specifies the keyword string for which to search. If it is more than a single word, surround the string with \*L"\|"\*O (double quotes) or other delimiters. Type all strings for \*Ldfstrace\*O commands in lowercase letters. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Ldfstrace apropos\*O command displays the first line of the help entry for any \*Ldfstrace\*O command containing the string specified by \*L-topic\*O in its name or short description. .PP To display the syntax for a command, use the \*Ldfstrace help\*O command. .SS "Privilege Required" .PP No privileges are required. .SH "OUTPUT" .PP The first line of an online help entry for a command lists the command and briefly describes its function. This command displays the first line for any \*Ldfstrace\*O command where the string specified by \*L-topic\*O is part of the command name or the first line. .SH "EXAMPLES" .PP The following command lists all \*Ldfstrace\*O commands that have the word \*Llist\*O in their names or short descriptions: .iS \*C$\*L dfstrace apropos list\*O .iE .oS lslog: list available logs lsset: list available event sets .oE .SH "RELATED INFORMATION" .PP Commands: \*Ldfstrace help(1m)\*O .iX "-]" "\*Ldfstrace\*O command suite" "\*Lapropos\*O" .zZ "defect,6222,R1.0.3,Document the DFS trace facility" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for .\" the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright (C) 1989, 1991, Transarc Corporation ...\" The Gulf Tower ...\" 707 Grant Street ...\" Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "dfstrace clear" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "defect,6222,R1.0.3,Document the DFS trace facility" .iX "-[" "\*Ldfstrace\*O command suite" "\*Lclear\*O" .SH NAME .PP \*Ldfstrace clear\*O \- Clears server process or kernel trace logs .SH "SYNOPSIS" .sS .PP \*Ldfstrace clear\*O [{\*L\-set \*Vset_name\*O... | \*L\-log \*Vlog_name\*O...}] [\*L\-cdsentry \*Vserver_entry_in_CDS\*O] .nL [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-set \*Vset_name\*O" Specifies the name of each event set whose logs you want to clear. Specify this option or the \*L\-log\*O option; omit both to clear all non-\*Cpersistent\*O kernel logs on the local machine or all non-\*Cpersistent\*O server process logs for the server process specified with the \*L\-cdsentry\*O option. .LI "\*L\-log \*Vlog_name\*O" Specifies the name of each log that you want to clear. Specify this option or the \*L\-set\*O option; omit both to clear all non-\*Cpersistent\*O kernel logs on the local machine or all non-\*Cpersistent\*O server process logs for the server process specified with the \*L\-cdsentry\*O option. .LI "\*L\-cdsentry \*Vserver_entry_in_CDS\*O" Specifies the full DCE pathname (\*L/.:/hosts/\*Vmachine\*L/\*Vprocess_name\*O) of a server process whose logs you want to clear. Use the \*L\-set\*O or \*L\-log\*O option with this option to specify a distinct group of server process logs to clear; use this option alone to clear all non-\*Cpersistent\*O logs associated with the server process. Omit this option to clear kernel logs. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Ldfstrace clear\*O command clears the specified server process or kernel logs. If you want to clear a kernel log, it must reside on the local machine. If you want to clear a server process log, it can reside on any machine; however, you must use the \*L\-cdsentry\*O option to specify the appropriate server process. .PP To clear a specific log, identify the log with the \*L\-set\*O or \*L\-log\*O option. Use the \*L\-cdsentry\*O option to clear a specific server process log, omit that option to clear a specific kernel log. .PP To clear all kernel logs on a machine, run the \*Ldfstrace clear\*O command without any options. To clear all server process logs associated with a particular server, run the command with the \*L\-cdsentry\*O option only. Note that you cannot clear \*Cpersistent\*O logs in this global manner. The \*Cpersistent\*O attribute prevents accidental clearing of important logs. The attribute is assigned to a log when the kernel or server process is compiled and cannot be changed. .SS "Privilege Required" .PP To clear a kernel log, the issuer must be logged in as \*Lroot\*O on the local machine. To clear a server process log, the issuer must be listed in the admin list associated with that process on the machine specified with the \*L\-cdsentry\*O option (for example, \*Ladmin.fl\*O for the \*Lflserver\*O process and \*Ladmin.ft\*O for the \*Lftserver\*O process). .SH "EXAMPLES" .PP The following command clears all logs used by the \*Lfx\*O kernel event set on the local machine: .iS \*C#\*O \*Ldfstrace clear fx\*O .iE The following command clears all logs used by the \*Lftserver\*O process on the machine dewitt: .iS \*C$\*O \*Ldfstrace clear -cdsentry /.:/hosts/dewitt/ftserver\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Ldfstrace lslog(1m)\*O, \*Ldfstrace lsset(1m)\*O .iX "-]" "\*Ldfstrace\*O command suite" "\*Lclear\*O" .zZ "defect,6222,R1.0.3,Document the DFS trace facility" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for .\" the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright (C) 1989, 1991, Transarc Corporation ...\" The Gulf Tower ...\" 707 Grant Street ...\" Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "dfstrace dump" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "defect,6222,R1.0.3,Document the DFS trace facility" .iX "-[" "\*Ldfstrace\*O command suite" "\*Ldump\*O" .SH NAME .PP \*Ldfstrace dump\*O \- Dumps server process or kernel trace logs .SH "SYNOPSIS" .sS .PP \*Ldfstrace dump\*O [{\*L\-set \*Vset_name\*O... | \*L\-follow \*Vlog_name\*O}] [\*L\-file \*Voutput_filename\*O] .nL [\*L\-sleep \*Vseconds_between_reads\*O] [\*L\-cdsentry \*Vserver_entry_in_CDS\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-set \*Vset_name\*O" Specifies the name of each event set whose corresponding logs you want to dump. Specify this option or the \*L\-follow\*O option; omit both to dump all kernel logs on the local machine or all server process logs for the server process specified with the \*L\-cdsentry\*O option. If you specify multiple event sets that point to the same log, that log is dumped multiple times. .LI "\*L\-follow \*Vlog_name\*O" Specifies the name of a kernel log to continuously dump. Process server logs cannot be continuously dumped. When a log is continuously dumped, it is also cleared. Specify this option or the \*L\-set\*O option; omit both to dump all kernel logs on the local machine or all server process logs for the server process specified with the \*L\-cdsentry\*O option. .LI "\*L\-file \*Voutput_filename\*O" Indicates the name of a file to which to write the output of the command. If the log being dumped is a server process log, the \*Voutput_filename\*O cannot contain slashes (/); the file is automatically placed in the directory \*Vdcelocal\*L/var/dfs/adm\*O. Furthermore, if an \*Voutput_filename\*O is not provided, the output is placed in the file \*Licl.\*Vserver_process_name\*O. Server process logs cannot be directly dumped to standard output. (If the output file for a server process log already exists, the older version is moved to the file \*Voutput_filename\*L.old\*O.) If the log being dumped is a kernel log, the \*Voutput_filename\*O must specify the full or relative pathname of the output file. .LI "\*L\-sleep \*Vseconds_between_reads\*O" Defines the number of seconds that the command pauses between dumps when dumping a kernel log in continuous mode. This option can only be used with the \*L\-follow\*O option. The default value is 10 seconds. .LI "\*L\-cdsentry \*Vserver_entry_in_CDS\*O" Specifies the full DCE pathname (\*L/.:/hosts/\*Vmachine\*L/\*Vprocess_name\*O) of a server process whose logs you want to dump. Use the \*L\-set\*O option with this option to specify a distinct group of server process logs to dump; use this option alone to dump all logs associated with the specified server process. Omit this option to dump kernel logs. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Ldfstrace dump\*O command dumps the specified kernel logs to standard output or the specified server process logs to the \*Voutput_filename\*O specified with the \*L\-file\*O option. Server process logs cannot be directly dumped to standard output. If an \*Voutput_filename\*O is not provided for a server process log dump, the output is place in the file \*Licl.\*Vserver_entry_in_CDS\*O. The contents of a kernel log dump can be directed into a file, rather than to standard output, by using the \*L\-file\*O option. .PP If you want to dump a kernel log, it must reside on the local machine. If you want to dump a server process log, it can reside on any machine; however, you must use the \*L\-cdsentry\*O option to specify the appropriate server process. .PP To dump specific logs, identify the logs with the \*L\-set\*O option. Use the \*L\-cdsentry\*O option to dump specific server process logs, omit that option to dump specific kernel logs. .PP To continuously dump a single kernel log, issue the command with the \*L\-follow\*O option. Server process logs cannot be continuously dumped. .PP To dump all kernel logs on a machine, run the \*Ldfstrace dump\*O command without the \*L\-set\*O or \*L\-follow\*O option. To dump all server process logs associated with a particular server, run the command with the \*L\-cdsentry\*O option, but without the \*L\-set\*O option. .PP .SS "Privilege Required" .PP To dump a kernel log, the issuer must be logged in as \*Lroot\*O on the local machine. To dump a server process log, the issuer must be listed in the admin list associated with that process on the machine specified by the \*L\-cdsentry\*O option (for example, \*Ladmin.fl\*O for the \*Lflserver\*O process and \*Ladmin.ft\*O for the \*Lftserver\*O process). .SH "OUTPUT" .PP At the beginning of the output of each dump is the date and time at which the dump began. Unless the \*L\-follow\*O option is specified, the number of logs being dumped is displayed. The content of each log is preceded by a message identifying the log. .PP Each log message contains the following three components: .ML .LI The timestamp associated with the message .LI The process ID or thread ID associated with the message .LI The message itself .LE .PP Every 1024 seconds, a current time message is written to each log. This message has the following format: .oS time \*Vtimestamp\*C, pid 0: Current time: \*Vunix_time\*O .oE Use the current time message to determine the actual time associated with each log message as follows: .AL .LI Locate the log message whose actual time you want to determine. .LI Search backward through the dump record until you come to a current time message. .LI If the current time message's timestamp is smaller than the log message's timestamp, subtract the former from the latter. If the current time message's timestamp is larger than the log message's timestamp, add 1024 to the latter and subtract the former from the result. .LI Add the resulting number to the current time message's \*Vunix_time\*O to determine the log message's actual time. .LE .PP Since log data is stored in a finite, circular buffer, some of the data can be overwritten before being read. If this happens, the following message appears at the appropriate place in the dump: .oS Log wrapped; data missing. .oE .nS "Note" If this message appears in the middle of a dump, which can happen under load, it indicates that not all of the log data is being written to the log. Increasing the size of the log with the \*Ldfstrace setlog\*O command may alleviate this problem. .nE .SH "EXAMPLES" .PP The following command dumps the log used by the \*Lcm\*O kernel event set on the local machine: .iS \*C#\*O \*Ldfstrace dump cm\*O .iE .oS DFS Trace Dump - .nL Date: Fri Oct 8 10:18:02 1993 .nL Found 1 logs. .nL Contents of log cmfx: Log wrapped; data missing. time 520.211319, pid 25135: found a princ 62b4144 ref 3 time 520.211355, pid 25135: find a princ (fast path) 62b4144, ref 3 time 520.211387, pid 25135: fshs_GetPrincipal END 62b4144, ref 3 time 520.211411, pid 25135: fshs_PutPrincipal 62b4144 ref 3 time 520.219153, pid 25135: Lookup 8005a4d.81c6c35.0.3fe/param.h, flags 0x1 time 520.219440, pid 25135: fshs_GetPrincipal START time 520.219483, pid 25135: fshs_GetHost, cookie 667de00 time 520.219511, pid 25135: fshs_FindHost, cookie 667de00 time 520.219559, pid 25135: find a prime host 62a2068 time 520.219590, pid 25135: find a host in fast path 62a2068 time 520.219625, pid 25135: fshs_FindPrincipal .. time 715.203951, pid 0: Current time: Mon Sep 20 13:05:15 1993 time 717.969835, pid 24621: fshs_GetPrincipal START time 717.969881, pid 24621: fshs_GetHost, cookie 66eed80 time 718.969910, pid 24621: fshs_FindHost, cookie 66eed80 time 718.969959, pid 24621: find a prime host 62a2068 .oE .SH "RELATED INFORMATION" .PP Commands: \*Ldfstrace lslog(1m)\*O, \*Ldfstrace lsset(1m)\*O, \*Ldfstrace setlog(1m)\*O .iX "-]" "\*Ldfstrace\*O command suite" "\*Ldump\*O" .zZ "defect,6222,R1.0.3,Document the DFS trace facility" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for .\" the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright (C) 1989, 1991, Transarc Corporation ...\" The Gulf Tower ...\" 707 Grant Street ...\" Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "dfstrace help" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "defect,6222,R1.0.3,Document the DFS trace facility" .iX "-[" "\*Ldfstrace\*O command suite" "\*Lhelp\*O" .SH NAME .PP \*Ldfstrace help\*O \- Shows syntax of specified \*Ldfstrace\*O commands or lists functional descriptions of all \*Ldfstrace\*O commands .SH "SYNOPSIS" .PP .sS \*Ldfstrace help\*O \*O[\*L-topic \*Vstring\*O...] [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-topic \*Vstring\*O" Specifies each command whose syntax is to be displayed. Provide only the second part of the command name (for example, \*Lsetset\*O, not \*Ldfstrace setset\*O). If this option is omitted, the output provides a short description of all \*Ldfstrace\*O commands. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Ldfstrace help\*O command displays the first line (name and short description) of the online help entry for every \*Ldfstrace\*O command if \*L-topic\*O is not provided. For each command name specified with \*L-topic\*O, the output lists the entire help entry. .PP Use the \*Ldfstrace apropos\*O command to show each help entry containing a specified string. .SS "Privilege Required" .PP No privileges are required. .SH "OUTPUT" .PP The online help entry for each \*Ldfstrace\*O command consists of the following two lines: .ML .LI The first line names the command and briefly describes its function. .LI The second line, which begins with \*CUsage:\*O, lists the command options in the prescribed order. .LE .SH "EXAMPLES" .PP The following command displays the online help entry for the \*Ldfstrace setset\*O command: .iS \*C$\*L dfstrace help setset\*O .iE .oS /bin/dfstrace setset: set state of event sets Usage: /bin/dfstrace setset [-set ...] [{-active | -inactive | -dormant}] [-cdsentry ] [-help] .oE .SH "RELATED INFORMATION" .PP Commands: \*Ldfstrace apropos(1m)\*O .iX "-]" "\*Ldfstrace\*O command suite" "\*Lhelp\*O" .zZ "defect,6222,R1.0.3,Document the DFS trace facility" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for .\" the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright (C) 1989, 1991, Transarc Corporation ...\" The Gulf Tower ...\" 707 Grant Street ...\" Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "dfstrace lslog" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "defect,6222,R1.0.3,Document the DFS trace facility" .iX "-[" "\*Ldfstrace\*O command suite" "\*Llslog\*O" .SH NAME .PP \*Ldfstrace lslog\*O \- Lists information on server process or kernel trace logs .SH "SYNOPSIS" .sS .PP \*Ldfstrace lslog\*O [{\*L\-set \*Vset_name\*O... | \*L\-log \*Vlog_name\*O...}] [\*L\-long\*O] .nL [\*L\-cdsentry \*Vserver_entry_in_CDS\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-set \*Vset_name\*O" Specifies the name of each event set whose corresponding logs you want to list. Specify this option or the \*L\-log\*O option; omit both to list all kernel logs on the local machine or all server process logs for the server process specified with the \*L\-cdsentry\*O option. .LI "\*L\-log \*Vlog_name\*O" Specifies the name of each log that you want to list. Specify this option or the \*L\-set\*O option; omit both to list all kernel logs on the local machine or all server process logs for the server process specified with the \*L\-cdsentry\*O option. .LI "\*L\-long\*O" Directs the \*Ldfstrace lslog\*O command to also provide information on the size of each log in 4-kilobyte units (kwords) and whether the log is physically allocated in the kernel. .LI "\*L\-cdsentry \*Vserver_entry_in_CDS\*O" Specifies the full DCE pathname (\*L/.:/hosts/\*Vmachine\*L/\*Vprocess_name\*O) of a server process whose logs you want to list. Use the \*L\-set\*O or \*L\-log\*O option with this option to list specific server process logs; use this option without the \*L\-set\*O or \*L\-log\*O option to list all logs associated with the server process. Omit this option to list kernel logs. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Ldfstrace lslog\*O command lists the specified server process or kernel trace logs. To display size and allocation information for the logs, run the command with the \*L\-long\*O option. If you want to list a kernel log, it must reside on the local machine. If you want to list a server process log, it can reside on any machine; however, you must use the \*L\-cdsentry\*O option to specify the appropriate server process. .PP To list a specific log, identify the log with the \*L\-set\*O or \*L\-log\*O option. Use the \*L\-cdsentry\*O option to list a specific server process log, omit that option to list a specific kernel log. .PP To list all kernel logs on a machine, run the \*Ldfstrace lslog\*O command without the \*L\-set\*O or \*L\-log\*O option. To list all server process logs associated with a particular server process, run the command with the \*L\-cdsentry\*O option, but without the \*L\-set\*O or \*L\-log\*O option. .SS "Privilege Required" .PP To list a kernel log, the issuer must be logged in as \*Lroot\*O on the local machine. To list a server process log, the issuer must be listed in the admin list associated with that process on the machine specified by the \*L\-cdsentry\*O option (for example, \*Ladmin.fl\*O for the \*Lflserver\*O process and \*Ladmin.ft\*O for the \*Lftserver\*O process). .SH "OUTPUT" When run without the \*L\-long\*O option, the \*Ldfstrace lslog\*O command lists the logs only. When run with the \*L\-long\*O option, the command lists the logs, the size of each log in kwords, and the allocation state of each log. There are two allocation states: .ML .LI \*Callocated\*O \- Space is allocated for the log in the kernel or server process memory. This indicates that one or more of the event sets that write to this log are either \*Cactive\*O or \*Cinactive\*O. .LI \*Cunallocated\*O \- Space is \*Vnot\*O allocated for the the log in the kernel or server process memory. This indicates that all of the event sets that write to this log are \*Cdormant\*O. .LE .PP A log can also be \*Cpersistent\*O; however, the persistence of a log cannot currently be determined using \*Ldfstrace\*O commands. If a log is \*Cpersistent\*O, it cannot be cleared during a global log clearing (executed by issuing \*Ldfstrace clear\*O without the \*L\-set\*O or \*L\-log\*O option). Of course, the log can still be cleared if it is otherwise named with the \*Ldfstrace clear\*O command. The \*Cpersistent\*O attribute prevents accidental clearing of important logs. The attribute is assigned to a log when the kernel or server process is compiled and cannot be changed. .SH "EXAMPLES" .PP The following command lists all kernel logs on the local machine: .iS \*C#\*O \*Ldfstrace lsl\*O .iE .oS Available logs: cmfx DFS syslog .oE .PP The following command lists all server process logs used by the \*Lflserver\*O process on the machine dewitt; it also provides the size and the allocation status of each log: .iS \*C$\*O \*Ldfstrace lsl -long -cdsentry /.:/hosts/dewitt/flserver\*O .iE .oS Available logs: ubikvote : 30 kwords (allocated) common : 30 kwords (allocated) .oE .SH "RELATED INFORMATION" .PP Commands: \*Ldfstrace lsset(1m)\*O, \*Ldfstrace setlog(1m)\*O .iX "-]" "\*Ldfstrace\*O command suite" "\*Llslog\*O" .zZ "defect,6222,R1.0.3,Document the DFS trace facility" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for .\" the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright (C) 1989, 1991, Transarc Corporation ...\" The Gulf Tower ...\" 707 Grant Street ...\" Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "dfstrace lsset" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "defect,6222,R1.0.3,Document the DFS trace facility" .iX "-[" "\*Ldfstrace\*O command suite" "\*Llsset\*O" .SH NAME .PP \*Ldfstrace lsset\*O \- Lists server process or kernel event sets and their states .SH "SYNOPSIS" .sS .PP \*Ldfstrace lsset\*O [\*L\-set \*Vset_name\*O...] [\*L\-cdsentry \*Vserver_entry_in_CDS\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-set \*Vset_name\*O" Specifies the name of each event set you want to list. Omit this option to list all kernel event sets on the local machine or all server process event sets for the server process specified with the \*L\-cdsentry\*O option. .LI "\*L\-cdsentry \*Vserver_entry_in_CDS\*O" Specifies the full DCE pathname (\*L/.:/hosts/\*Vmachine\*L/\*Vprocess_name\*O) of a server process whose event sets you want to list. Use this option with the \*L\-set\*O option to list a distinct group of server process event sets; use this option alone to list all event sets associated with the server process. Omit this option to list kernel event sets. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Ldfstrace lsset\*O command lists the specified server process or kernel event sets and their states. If you want to list a kernel event set, it must reside on the local machine. If you want to list a server process event set, it can reside on any machine; however, you must use the \*L\-cdsentry\*O option to specify the appropriate server process. .PP To list a specific event set, identify the event set with the \*L\-set\*O option. Use the \*L\-cdsentry\*O option to list a specific server process event set, omit that option to list a specific kernel event set. .PP To list all kernel event sets on a machine, run the \*Ldfstrace lsset\*O command without any options. To list all server process event sets associated with a particular server process, run the command with the \*L\-cdsentry\*O option only. .SS "Privilege Required" .PP To list a kernel event set, the issuer must be logged in as \*Lroot\*O on the local machine. To list a server process event set, the issuer must be listed in the admin list associated with that process on the machine specified with the \*L\-cdsentry\*O option (for example, \*Ladmin.fl\*O for the \*Lflserver\*O process and \*Ladmin.ft\*O for the \*Lftserver\*O process). .SH "OUTPUT" The command lists each event set and its state. There are three event set states: .ML .LI \*Cactive\*O \- Tracing is enabled for the event set. .LI \*Cinactive\*O \- Tracing is temporarily disabled for the event set; however, the event set continues to claim space occupied by the logs to which it sends data. .LI \*Cdormant\*O \- Tracing is disabled for the event set; furthermore, the event set releases its claim to space occupied by the logs to which it sends data. When all of the event sets that send data to a particular log are in this state, the space allocated for that log is freed. .LE .PP An event set can also be \*Cpersistent\*O. If an event set is \*Cpersistent\*O, its state cannot be set during a global state setting (executed by issuing \*Ldfstrace setset\*O command with the \*L\-set\*O option). Of course, the event set's state can still be set if the event set is otherwise specified with the \*Ldfstrace setset\*O command. The \*Cpersistent\*O attribute prevents accidental resetting of an event set's state. The attribute is assigned to an event set when the kernel or server process is compiled and cannot be changed. .SH "EXAMPLES" .PP The following command lists all kernel event sets and their states on the local machine: .iS \*C#\*O \*Ldfstrace lss\*O .iE .oS Available sets: cm: active fx: active fshost: active xops: active episode/anode: dormant episode/logbuf: dormant episode/vnops: dormant tkc: inactive tpq: active tkm: active .oE .PP The following command lists state information on the event set \*Lubikvote\*O for the \*Lflserver\*O process on the machine dewitt: .iS \*C$\*O \*Ldfstrace lss -set ubikvote -cdsentry /.:/hosts/dewitt/flserver\*O .iE .oS ubikvote: active .oE .SH "RELATED INFORMATION" .PP Commands: \*Ldfstrace clear(1m)\*O, \*Ldfstrace setset(1m)\*O .iX "-]" "\*Ldfstrace\*O command suite" "\*Llsset\*O" .zZ "defect,6222,R1.0.3,Document the DFS trace facility" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for .\" the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright (C) 1989, 1991, Transarc Corporation ...\" The Gulf Tower ...\" 707 Grant Street ...\" Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "dfstrace setlog" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "defect,6222,R1.0.3,Document the DFS trace facility" .iX "-[" "\*Ldfstrace\*O command suite" "\*Lsetlog\*O" .SH NAME .PP \*Ldfstrace setlog\*O \- Sets the size of the indicated log .SH "SYNOPSIS" .sS .PP \*Ldfstrace setlog -log \*Vlog_name\*L -buffersize \*V4-kilobyte_units\*O [\*L\-cdsentry \*Vserver_entry_in_CDS\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-log \*Vlog_name\*O" Specifies the name of the kernel or server process log whose size you want to set. .LI "\*L\-buffersize \*V4_kilobyte_units\*O" Defines the size of the log in 4-kilobyte units (kwords). .LI "\*L\-cdsentry \*Vserver_entry_in_CDS\*O" Specifies the full DCE pathname (\*L/.:/hosts/\*Vmachine\*L/\*Vprocess_name\*O) of a server process whose log size you want to set. Omit this option to set the size of a kernel log. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Ldfstrace setlog\*O command sets the size of a server process or kernel log. The size of the log is set in kwords. To set the size of a server process log, specify the server process with the \*L\-cdsentry\*O option; to set the size of a kernel log, omit the \*L\-cdsentry\*O option. .PP If a specified log is already allocated, it is cleared and freed when this command is run, and a new log of the desired size is created. Otherwise, a log of the desired size is created when the log is allocated. .PP To display the current size and allocated status of a log, issue the \*Ldfstrace lslog\*O command. .PP .SS "Privilege Required" .PP To set the size of a kernel log, the issuer must be logged in as \*Lroot\*O on the local machine. To set the size of a server process log, the issuer must be listed in the admin list associated with that process on the machine specified by the \*L\-cdsentry\*O option (for example, \*Ladmin.fl\*O for the \*Lflserver\*O process and \*Ladmin.ft\*O for the \*Lftserver\*O process). .SH "EXAMPLES" .PP The following command sets the size of the \*Lcmfx\*O kernel log to 64 kilobytes (16 kwords): .iS \*C#\*O \*Ldfstrace setl cmfx 16\*O .iE .PP The following command sets the size of the \*Lubikvote\*O server process log on the machine dewitt to 120 kilobytes (30 kwords): .iS \*C$\*O \*Ldfstrace setl ubikvote 30 -cdsentry /.:/hosts/dewitt/flserver\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Ldfstrace lslog(1m)\*O .iX "-]" "\*Ldfstrace\*O command suite" "\*Lsetlog\*O" .zZ "defect,6222,R1.0.3,Document the DFS trace facility" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for .\" the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright (C) 1989, 1991, Transarc Corporation ...\" The Gulf Tower ...\" 707 Grant Street ...\" Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "dfstrace setset" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "defect,6222,R1.0.3,Document the DFS trace facility" .iX "-[" "\*Ldfstrace\*O command suite" "\*Lsetset\*O" .SH NAME .PP \*Ldfstrace setset\*O \- Sets the state of server process or kernel event sets .SH "SYNOPSIS" .sS .PP \*Ldfstrace setset\*O [\*L\-set \*Vset_name\*O...] [{\*L\-active\*O | \*L\-inactive\*O | \*L\-dormant\*O}] .nL [\*L\-cdsentry \*Vserver_entry_in_CDS\*O] [\*L\-help\*L] .sE .SH "OPTIONS" .VL .LI "\*L\-set \*Vset_name\*O" Specifies the name of each event set whose state you want to set. Omit this option to set the state for all non-\*Cpersistent\*O kernel event sets on the local machine or all non-\*Cpersistent\*O server process event sets for the server process specified with the \*L\-cdsentry\*O option. .LI "\*L\-active\*O" Sets the state of each specified event set to \*Cactive\*O. Use this option or the \*L\-inactive\*O or \*L\-dormant\*O option. .LI "\*L\-inactive\*O" Sets the state of each specified event set to \*Cinactive\*O. Use this option or the \*L\-active\*O or \*L\-dormant\*O option. .LI "\*L\-dormant\*O" Sets the state of each specified event set to \*Cdormant\*O. Use this option or the \*L\-active\*O or \*L\-inactive\*O option. .LI "\*L\-cdsentry \*Vserver_entry_in_CDS\*O" Specifies the full DCE pathname (\*L/.:/hosts/\*Vmachine\*L/\*Vprocess_name\*O) of a server process whose event set states you want to set. If this option is used with the \*L\-set\*O option, only the states of the specified event sets are set; if this option is used without the \*L\-set\*O option, the state of all non-\*Cpersistent\*O event sets associated with the specified server process are set. Omit this option to set the state of kernel event sets. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Ldfstrace setset\*O command sets the state of the server process or kernel event sets. To set the state of a kernel event set, you must run this command on the machine that contains that event set. To set the state of a server process event set, you can run the command from any machine; however, you must identify the corresponding server process by specifying the process with the \*L\-cdsentry\*O option. .PP To set the state of a specific event set, identify the event set with the \*L\-set\*O option. Use the \*L\-cdsentry\*O option to set the state of a specific server process event set, omit that option to set the state of a specific kernel event set. .PP To set the state of each kernel event set on a machine, run the \*Ldfstrace setset\*O command without the \*L\-set\*O option. To set the state of each event set associated with a particular server process, run the command with the \*L\-cdsentry\*O option, but without the \*L\-set\*O option. Note that you cannot set the state of \*Cpersistent\*O event sets in this global manner. The \*Cpersistent\*O attribute prevents accidental resetting of an event set's state. The attribute is assigned to an event set when the kernel or server process is compiled and cannot be changed. .PP The state of each event set is defined by using the \*L\-active\*O, \*L\-inactive\*O, or \*L\-dormant\*O option. These options correspond to the following event set states: .ML .LI \*Cactive\*O \- Tracing is enabled for the event set. .LI \*Cinactive\*O \- Tracing is temporarily disabled for the event set; however, the event set continues to claim space occupied by the logs to which it sends data. .LI \*Cdormant\*O \- Tracing is disabled for the event set; furthermore, the event set releases its claim to space occupied by the logs to which it sends data. When all of the event sets that send data to a particular log are in this state, the space for that log is deallocated. .LE .SS "Privilege Required" .PP To set the state of a kernel event set, the issuer must be logged in as \*Lroot\*O on the local machine. To set the state of a server process event set, the issuer must be listed in the admin list associated with that process on the machine specified by the \*L\-cdsentry\*O option (for example, \*Ladmin.fl\*O for the \*Lflserver\*O process and \*Ladmin.ft\*O for the \*Lftserver\*O process). .SH "EXAMPLES" .PP The following command sets the event state of all kernel event sets on the local machine to \*Cinactive\*O: .iS \*C#\*O \*Ldfstrace sets -inactive\*O .iE .PP The following command sets the event state of the event set \*Lubikvote\*O to \*Cactive\* for the \*Lflserver\*O process on the machine dewitt: .iS \*C$\*O \*Ldfstrace sets -set ubikvote -active -cdsentry /.:/hosts/dewitt/flserver\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Ldfstrace lsset(1m)\*O, \*Ldfstrace setlog(1m)\*O .iX "-]" "\*Ldfstrace\*O command suite" "\*Lsetset\*O" .zZ "defect,6222,R1.0.3,Document the DFS trace facility" .\" $Header: dhcpdb2conf.1m,v 78.3 96/02/12 17:03:48 ssa Exp $ .\" -*-Text-*- .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .\" .\" (c) Copyright 1996, Hewlett-Packard Company, all rights reserved. .\" .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .TA d .TH dhcpdb2conf 1M "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ad b .SH NAME dhcpdb2conf \- DHCP client database converter .SH SYNOPSIS .CR dhcpdb2conf .RI [ dhcpdb2conf_options ] .RI [ lan_interfaces ] .SH DESCRIPTION .CR dhcpdb2conf provides a means of translating a client DHCP database into a set of standard configuration file variables. A DHCP client database can contain settings for such items as, IP address, hostname, and default gateway. Using .CR dhcpdb2conf , you can simply list the contents of the database to the screen, create a set of configuration staging files, or execute direct edits on existing configuration files using the values contained in the client database. .SS Options .CR dhcpdb2conf allows you to specify a list of interfaces on the command line (e.g. lan0 lan1 ...). If no lan interface is specified, .CR dhcpdb2conf will process all entries referenced in the client database. The entries themselves are defined as a unique lan interface and a list of attributes which correspond to that interface. The attributes can be selected for processing by specifying one or more filter flags on the command line. Each filter flag may be combined with any other filter flag(s). If no filter flag is specified, all the attributes for a lan interface will be processed. The following options are supported: .TP 15 .B -a Using the results of the specified filter, directly apply the variable defintions to the existing configuration files (for example, .CR /etc/rc.config.d/netconf ). .TP 15 .B -c Create a set of staging files using the results of the selected filter(s). Each variable processed will be applied to its corresponding configuration file. Specifically, .CR dhcpdb2conf will generate a copy of the existing configuration file. As an example, .CR /etc/rc.config.d/netconf will be copied to .CR /etc/rc.config.d/netconf.dhcp . Once this staging file has been created, the variable that is being processed will be applied to the newly created file. .IP .B WARNING: Using the .CR -c option will override any existing values which are currently set in the system's configuration files. .TP 15 .CR -d Process the DNS variable set: [domain, nameserver] .TP 15 .CR -h Process HOSTNAME .TP 15 .CR -i Process the INTERFACE variable set: [IP_ADDRESS, SUBNET_MASK, BROADCAST_MASK, LANCONFIG_ARGS] .TP 15 .CR -n Process the NIS variable set: [NISDOMAIN, YPSET_ADDR] .TP 15 .CR -p Print results to the screen (stdout), this is the default action if neither .CR -c or .CR -a are specified .TP 15 .CR -r Process the ROUTE variable set: [ROUTE_DESTINATION, ROUTE_GATEWAY, ROUTE_COUNT] .TP 15 .CI -s " set index" Specify the variable set index .TP 15 .CR -t Process NTPDATE_SERVER .SS Configuration Files and Variable Names The files and variables which can be processed are the following: .TP 15 .CR /etc/rc.config.d/netconf .nf HOSTNAME INTERFACE_NAME[index] IP_ADDRESS[index] SUBNET_MASK[index] BROADCAST_MASK[index] LANCONFIG_ARGS[index] ROUTE_DESTINATION[index] ROUTE_GATEWAY[index] ROUTE_COUNT[index] .fi .TP 15 .CR /etc/rc.config.d/namesvrs .nf NISDOMAIN YPSET_ADDR .fi .TP 15 .CR /etc/rc.config.d/netdaemons .nf NTPDATE_SERVER .fi .TP 15 .CR /etc/resolv.conf .nf domain nameserver .fi .PP .SH EXAMPLES To list the entire contents of the DHCP client database type: .IP .CR dhcpdb2conf .PP To list only the INTERFACE variable set for lan0 type: .IP .CR "dhcpdb2conf -i lan0" .PP To list the INTERFACE and ROUTE variable sets for lan0 and lan1 type: .IP .CR "dhcpdb2conf -ir lan0 lan1" .PP To apply the INTERFACE and ROUTE variable sets for lan0 to the existing configuration files type: .IP .CR "dhcpdb2conf -ira lan0" .PP To apply all variable sets to the existing configuration files using lan0 and set index = 1 type: .IP .CR "dhcpdb2conf -a -s 1 lan0" .PP .SH WARNINGS Using the .CR -c option will override any existing values which are currently set in the system's configuration files. .SH FILES .CR /usr/lbin/dhcpdb2conf .PP .CR /etc/dhcpclient.data .SH SEE ALSO auto_parms(1M) .\" .\" index@\f4dhcpdb2conf\f1 \- DHCP client database converter@@@\f3dhcpdb2conf(1M)\f1 .\" index@\f1DHCP client database converter@@@\f3dhcpdb2conf(1M)\f1 .\" index@\f1database converter, DHCP client@@@\f3dhcpdb2conf(1M)\f1 .\" index@\f1Dynamic Host Configuration Protocol (DHCP)@@@\f3dhcpdb2conf(1M)\f1 .\" .\" toc@\f3dhcpdb2conf(1M)\f1:\0\0\f4dhcpdb2conf\f1@@@DHCP client database converter .\" .\" .\" $Header $ .\" $Revision: 74.2 $ .TA d .TH dhcptools 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" ============= .SH NAME dhcptools \- command line tool for DHCP elements of bootpd .\" ============= .SH SYNOPSIS .ift .ad l .PP .C dhcptools .RC -d .PP .C dhcptools .RC -h fip=\c .IR first_IP_address no=\c .IR number_of_entries_to_generate sm=\c .IR subnet_mask hn=\c .IR hostname_template [dn=\c .IR domain_name ] .PP .C dhcptools .RC -p ht=\c .IR hardware_type ha=\c .IR hardware_address sn=\c .IR subnet_identifier [lt=\c .IR lease_time ] [rip=\c .IR requested_IP_address ] .PP .C dhcptools .RC -P ci=\c .IR client_identifier sn=\c .IR subnet_identifier [lt=\c .IR lease_time ] [rip=\c .IR requested_IP_address ] .PP .C dhcptools .RC -r ip=\c .IR IP_address ht=\c .IR hardware_type ha=\c .IR hardware_address .PP .C dhcptools .RC -R ip=\c .IR IP_address ci=\c .IR client_identifier .PP .C dhcptools .RC -t [ct=\c .IR count ] .PP .C dhcptools .RC -v [bt=\c .IR bootptabfile ] [dt=\c .IR dhcptabfile ] .SH DESCRIPTION .PP .CR dhcptools is a command line tool that provides access to DHCP-related options for the bootpd server. The options provide control for dumping internal data structures, generating a hosts file, previewing client address assignment, reclaiming unused addresses, tracing packets, and validating configuration files. .\" ============= .SS Options .CR dhcptools supports the following options: .RS .TP 10 .C -d Dump internal bootpd data to output files. The dump output files are .CR /tmp/dhcp.dump.bootptab , .CR /tmp/dhcp.dump.dhcptab , and .CR /tmp/dhcp.dump.other . The first file reports fixed address clients known to the currently active .CR bootpd server. The second file reports .CR bootpd global and group configuration. The third file reports miscellaneous .CR bootpd internal data. .TP .C -h Generate a hosts file in .CR /etc/hosts format; see .IR hosts (4). The output file is .CR /tmp/dhcphosts . The file can be incorporated into a name database in advance of .CR bootpd server activation so that the server can automatically allocate a host name along with an IP address to a DHCP client. For IP address allocation to DHCP clients, the .CR bootpd server uses .IR gethostbyaddr (3N) to find the host name associated with a particular IP address. Each host entry in .CR dhcphosts contains an IP address followed by a hostname. The IP address of the first entry is first_IP_address. The hostname of the first entry is derived from the hostname_template. Each subsequent host entry contains a unique IP address and hostname derived from the first_IP_address, subnet_mask, and hostname_template. The wildcards permitted in the hostname_template are .CR *#? . A .CR * means to use a character selected sequentially from the range .RI [ a-z , 0-9 ]. A .CR # means to use a digit selected sequentially from the range .RI [ 0-9 ]. A .CR ? means to use a letter selected sequentially from the range .RI [ a-z ]. A maximum of 3 wildcards can be specified. If a domain_name is specified, it will be appended to the hostname. The maximum number_of_entries_to_generate is 1000. .TP .C -p Preview a client's address assignment based on current conditions for the .CR bootpd server. The output is written to stdout. The subnet-identifier tells .CR bootpd the subnet for which the client is requesting an IP address. Optionally, the user may request a specific IP address and lease duration using the parameters lease-time and requested-IP-address. Use Internet address dot notation (see .IR inet (3N) for the IP address and an integer number of seconds for the lease-time. .TP .C -P Preview a client's address assignment based on current conditions for the .CR bootpd server. This option is the same as .C -p except that the client is identified by a unique client-identifer. See .IR bootpd (1M). .TP .C -r Reclaim a client's IP address for re-use by the .CR bootpd server. This option is intended for limited use by the .CR bootpd administrator to return an allocated but unused IP address to a DHCP allocation pool. The option may be useful to clear the bootpd database of old entries (e.g. for clients retired from service while holding an unexpired IP address lease). Do not reclaim an address that belongs to an active client. See .IR bootpd (1M). The IP_address, hardware_address, and hardware_type can be obtained from the bootpd database file. .TP .C -R Reclaim a client's IP address for re-use by the .CR bootpd server. This option is the same as .CR -r except that the client is identified by its unique client_identifier. See .IR bootpd (1M). The IP_address and matching client_identifier can be obtained from the bootpd database file. .TP .CR -t Establish packet tracing for .CR bootpd . This will trace the inbound and outbound BOOTP/DHCP packets for the local .CR bootpd server. The output file is .CR /tmp/dhcptrace . The packet trace count can be a value from 0 to 100. To query the current count, use .CR "dhcptools -t" . To turn off packet tracing use .CR "dhcptools -t ct=0" . .TP .C -v Validate .CR bootpd configuration files. The default configuration files that will be validated are .CR /etc/bootptab and .CR /etc/dhcptab . When a bootptabfile or dhpctabfile is specified, the full pathname is required. The output file for validate is .CR /tmp/dhcpvalidate . .PP Only one of the .CR -d , .CR -h , .CR -t , .CR -p , .CR -P , .CR -r , .CR -R , or .CR -v options is allowed per .CR dhcptools command. .RE .\" ============= .SH RETURN VALUE .CR dhcptools returns zero upon successful completion or non-zero if the command failed, in which case an explanation is written to standard error. .\" ============= .SH EXAMPLES .PP Dump the active .CR bootpd server's internal data to the dump output files: .PP .nf .C dhcptools -d .fi .PP Generate a .CR /tmp/dhcphosts file with 10 entries: .PP .nf .C dhcptools -h fip=192.11.22.0 no=10 sm=255.255.255.0 hn=workstation#? .fi .PP Query the active .CR bootpd daemon for the the current packet trace count: .PP .nf .C dhcptools -t .fi .PP Set the count to 10 packets: .PP .nf .C dhcptools -t ct=10 .fi .PP Preview two clients' address assignments by hardware address: .PP .nf .C dhcptools -p ht=1 ha=080009000001 sn=192.11.22.0 lt=infinite .C dhcptools -p ht=1 ha=080009000002 sn=192.11.22.0 lt=600 rip=192.11.22.105 .fi .PP To preview a client's address assignment by client identifier, a unique client identifier value is needed. This information can be obtained for actual DHCP clients (provided they support a client identifier) from the manufacturer's documentation. See .IR bootpd (1M) for more information about the client identifier. Assuming that .CR serial_number_12345678 is a valid client identifier, the preview command is: .PP .nf .C dhcptools -P ci="serial_number_12345678" sn=192.11.22.0 .fi .PP To reclaim an IP address by hardware address: .PP .C dhcptools -r ip=192.11.22.149 ht=1 ha=080009000006 .PP .nf The parameter values were obtained from this sample entry in the dhcpdb file: C 192.11.22.0: 192.11.22.149 00 1 080009000006 FFFFFFFF 00 .fi .PP To reclaim an IP address by client identifier (see earlier example of preview by client identifier): .PP .C dhcptools -R ip=192.11.22.110 ci="serial_number_12345678" .PP To validate a bootptab and dhcptab file: .PP .C dhcptools -v bt=/home/mydir/bootptab dt=/home/mydir/dhcptab .\" ============= .SH WARNINGS The .CR dhcptools operations of dump, packet trace, preview, and reclaim depend on communication with the local .CR bootpd server. If the server is not running, you may encounter an error. .\" ============= .SH AUTHOR .CR dhcptools was developed by HP. .\" ============= .SH FILES .PD 0 .TP 33 .C /tmp/dhcphosts hostgen output file in /etc/hosts format .TP .C /tmp/dhcptrace packet trace output file .TP .C /tmp/dhcpvalidate validate output file .TP .C /tmp/libdhcp.sl library file .TP .C /tmp/dhcp.dump.bootptab dump output file .TP .C /tmp/dhcp.dump.dhcptab dump output file .TP .C /tmp/dhcp.dump.other dump output file .TP .C /etc/bootptab default bootptab file for validate .TP .C /etc/dhcptab default dhcptab file for validate .TP .C /tmp/dhcpfifo.root FIFO file for dhpctools to bootpd(1M) communication .TP .C /tmp/dhcpfifo.any FIFO file for dhcptools to bootpd(1M) communication .TP .C /tmp/dhcpfifo FIFO file for bootpd(1M) to dhcptools communication .PD .\" ============= .SH "SEE ALSO" bootpd(1M), bootpquery(1M); .SM DARPA Internet Request For Comments .SM RFC1541, RFC1542, RFC1533, RFC1534, Assigned Numbers .\" .\" index@\f4dhcptools\f1 \- command line tool for DHCP elements of bootpd@@@\f3dhcptools(1M)\f1 .\" index@\f1command line tool for DHCP elements of bootpd@@@\f3dhcptools(1M)\f1 .\" index@\f1bootpd, command line tools for DHCP elements of@@@\f3dhcptools(1M)\f1 .\" index@\f1DHCP elements of bootpd, command line tool@@@\f3dhcptools(1M)\f1 .\" .\" toc@\f3dhcptools(1M)\f1:\0\0\f4dhcptools\f1@@@comand line tools for DHCP elements of bootpd .\" .\" fileset_database@dhcptools.1m INET-ENG-A-MAN ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Oct 25, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH disable 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldtscp\*O commands" "\*Ldisable\*O" .iX "DTS servers" "stopping" .iX "DTS clerks" "stopping" .SH NAME .PP .zA "defect,7684,R1.0.3,change specified node to local node" \*Ldisable\*O - Stops the DCE DTS entity on the local node .zZ "defect,7684,R1.0.3,change specified node to local node" .SH "SYNOPSIS" .PP .zA "defect,6211,R1.0.3,add control program name" .sS \*Ldtscp disable\*O .sE .zZ "defect,6211,R1.0.3,add control program name" .SH "DESCRIPTION" .PP The \*Ldisable\*O command turns off the DCE DTS entity on the system where the command is entered. When the command is executed, the status attribute \*Lstate\*O is set to \*Loff\*O. .SS "Privilege Required" .PP You must have write permission on the ACL associated with the DTS entity in order to execute the command. .SH "NOTES" .PP The DCE DTS entity cannot be disabled until it is enabled with the \*Lenable\*O command. You must enter the \*Ldisable\*O command before you can delete the entity. .zA "defect, 11818, R1.1, Added caveat" .PP This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" ...\".SH "EXIT VALUE" ...\".PP ...\".VL 8m ...\".LI "Wrong State" ...\"The command failed because the DTS ...\"entity is in the \*Loff\*O state or because the \*Lcreate\*O ...\"command was not entered (that is, the software entity was not created). .SH "EXAMPLES" .iS \*Cdtscp>\*O \*Ldisable\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lenable (1m)\*O, \*Ldelete (1m)\*O, \*Lcreate (1m)\*O ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "disable clerk" 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "CDS clerks" "stopping" .iX "\*Lcdscp\*O commands" "\*Ldisable clerk\*O" .SH NAME .PP \*Ldisable clerk\*O - Stops the clerk on the local system .SH "SYNOPSIS" .sS \*Lcdscp disable clerk\*O .sE .SH "DESCRIPTION" .PP The \*Ldisable clerk\*O command stops the clerk on the local system, causing all active communication with any server to be aborted and all client calls in progress to fail. The clerk cache is copied to disk. .SS "Privilege Required" .PP You must have write permission to the clerk. .SH "NOTES" .PP If you are disabling a clerk on a system where a server is running, make sure you disable the server first. .zA "defect, 11818, R1.1, Added caveat" .PP This command may be replaced in future releases by the \*Ldcecp\*O command, and may no longer be supported at that time. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .PP The following command stops the clerk on the local server system: .iS \*Ccdscp> \*Ldisable clerk\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Command: \*Lshow clerk(1m)\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "disable server" 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lcdscp\*O commands" "\*Ldisable server\*O" .iX "CDS servers" "stopping" .SH NAME .PP \*Ldisable server\*O - Stops the server on the local system .SH "SYNOPSIS" .sS \*Lcdscp disable server\*O .sE .SH "DESCRIPTION" .PP The \*Ldisable server\*O command stops the server on the local system. The server is disabled after all transactions in progress are completed. .SS "Privilege Required" .PP You must have write permission to the server. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command may be replaced in future releases by the \*Ldcecp\*O command, and may no longer be supported at that time. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command stops the server on the local system: .iS \*Ccdscp> \*Ldisable server\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Command: \*Lshow server(1m)\*O .wH "" .wH "" .\" $Header: diskinfo.1m,v 72.5 94/05/06 16:38:00 ssa Exp $ .TA d .TH diskinfo 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME diskinfo \- describe characteristics of a disk device .SH SYNOPSIS .C /usr/sbin/diskinfo .RC [ -b \(or -v ] .I character_devicefile .SH DESCRIPTION The .CR diskinfo command determines whether the character special file named by .I character_devicefile is associated with a .SM SCSI, CS\c /80, or Subset/80 disk drive. If so, .CR diskinfo summarizes the disk's characteristics. .PP The .CR diskinfo command displays information about the following characteristics of disk drives: .RS .TP 15 Vendor name Manufacturer of the drive (\c .SM SCSI only) .PD 0 .TP Product \s-1ID\s0 Product identification number or .SM ASCII name .TP Type .SM CS\c /80 or .SM SCSI classification for the device .TP Disk Size of disk specified in bytes .TP Sector Specified as bytes per sector .PD .RE .PP Both the size of disk and bytes per sector represent formatted media. .SS Options The .CR diskinfo command recognizes the following options: .RS .TP 15 .C -b Return the size of the disk in 1024-byte sectors. .TP .C -v Display a verbose summary of all of the information available from the device. (Since the information returned by .SM CS\c /80 drives and .SM SCSI drives differs, the associated descriptions also differ.) .RS .RS .TP 3 \(bu .SM CS\c /80 devices return the following: .PD 0 .RS .nf .IP Device name Number of bytes/sector Geometry information Interleave Type of device Timing information .fi .RE .PD .TP \(bu .SM SCSI disk devices return the following: .PD 0 .RS .nf .IP Vendor and product \c .SM ID Device type Size (in bytes and in logical blocks) Bytes per sector Revision level .SM SCSI\0\c conformance level data .fi .PD .RE .RE .SH DEPENDENCIES .SS General The .CR diskinfo command supports only .SM CS\c /80, subset/80, and .SM HP SCSI disk devices. .SS SCSI Devices The .SM SCSI specification provides for a wide variety of device-dependent formats. For non-\c .SM HP devices, .CR diskinfo may be unable to interpret all of the data returned by the device. Refer to the drive operating manual accompanying the unit for more information. .SH AUTHOR .C diskinfo was developed by .SM HP. .SH SEE ALSO lsdev(1M), disktab(4), disk(7). .\" .\" index@\f4diskinfo\f1 \- describe characteristics of a disk device@@@\f3diskinfo(1M)\f1 .\" index@describe characteristics of a disk device@@@\f3diskinfo(1M)\f1 .\" index@device, describe characteristics of a disk@@@\f3diskinfo(1M)\f1 .\" index@characteristics of a disk device, describe@@@\f3diskinfo(1M)\f1 .\" index@disk device, describe characteristics of a@@@\f3diskinfo(1M)\f1 .\" .\" toc@\f3diskinfo(1M)\f1:\0\0\f4diskinfo\f1@@@describe characteristics of a disk device .\" .\" fileset_database@diskinfo.1m SYS-ADMIN-MAN .\" $Header: disksecn.1m,v 74.1 95/03/23 17:59:33 ssa Exp $ .TA d .TH disksecn 1M "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not implemented on 700 .SH NAME disksecn \- calculate default disk section sizes .SH SYNOPSIS .B disksecn .RB [ \|\-p\| \(or \|\-d\| ] .RB [ \|\-b .IR block_size\| ] .RB [ \|\-n .IR disk_name\| ] .SH DESCRIPTION .I disksecn is used to calculate the disk section sizes based on the Berkeley disk partitioning method. .PP .I disksecn recognizes the following options: .RS .TP 15 .B \-p Produce tables suitable for inclusion in the device driver. .TP .B \-d Produce tables suitable for generating the disk description file .BR /etc/disktab . .TP .BI \-b \ block_size When generating the above tables, use a sector size of .I block_size bytes, where .I block_size can be .BR 256 , .BR 512 , .BR 1024 , or .BR 2048 . Defaults to .SM DEV_BSIZE (defined in .RB < sys/param.h >) if not specified. .TP .BI \-n \ disk_name Specifies the disk name to be used in calculating sector sizes; for example, .B hp7912 or .BR hp7945 . If an unknown disk name is specified, .I disksecn prompts the user for the necessary disk information. .RE .PP If neither .C \-p nor .C \-d table selection switches are specified a default table of the section sizes and range of cylinders used is output. .PP Disk section sizes are based on the total amount of space on the disk as given in the table below (all values are supplied in units of 256-byte sectors). If the disk is smaller than approximately 44 Mbytes, .I disksecn aborts and returns the message .BR "disk too small, calculate by hand" . .IP .TS c c c c c n r r r r. Section 44-56MB 57-106MB 107-332MB 333+MB 0 97120 97120 97120 97120 1 39064 39064 143808 194240 3 39064 39064 78128 117192 4 unused 48560 110096 429704 6 7992 7992 7992 7992 10 unused unused unused 516096 .TE .PP .SM NOTE: .br It is important to note the difference between the block size passed into .I disksecn via the .B \-b switch argument and the sector size the user is asked to input when an unknown disk name is passed to .I disksecn via the .B \-n switch argument. .PP The block size is the sector size that .I disksecn assumes the disk to have when it prints the requested tables. All information printed in the tables is adjusted to reflect this assumed sector size (block size) passed in by the user. The sector size requested by .I disksecn when an unknown disk name is passed does not necessarily have to be the same as the assumed sector size (block size) passed in by the .B \-b switch argument. .PP For example, a user wants to see the device driver tables for the disk named .B hp7945 with an assumed sector size (block size) of 256 bytes. The user has the following information about the .B hp7945 disk: .IP Disk type = winchester .PD 0 .IP Sector size = 512 .IP Number of sectors per track (512 byte sectors) = 16 .IP Number of tracks = 7 .IP Number of cylinders = 968 .IP Revolutions per minute = 3600 .PD .PP The user invokes .I disksecn by typing the following command: .IP .B disksecn \-p \-b 256 \-n hp7945 .PP Assuming that .B hp7945 is an unknown disk name, .I disksecn prompts the user for the necessary disk information. The user should input the information as shown above, reflecting a sector size of 512 bytes. All the information will be adjusted within .I disksecn to reflect the assumed sector size (block size) of 256 bytes, passed as the argument of the .B \-b switch, before the requested device driver table is output. .PP This adjustment also takes place when the disk name is known and an assumed sector size (block size) is passed in as the argument of the .B \-b switch which is not .SM DEV_BSIZE bytes, the assumed sector size (block size) used to create the .B etc/disktab file. .SH RETURN VALUE .I disksecn returns the following values: .RS .TP 5 .B 0 Successful completion. .PD 0 .TP .B 1 Usage error. .TP .B 2 User did not input parameters for an unknown disk. .TP .B 3 Disk too small or an invalid block size. .PD .RE .PP .I disksecn aborts and prints an error message under the following conditions: .RS .TP 3 \(bu .I disksecn was invoked without specifying a disk name. .PD 0 .TP \(bu Requested both .B \-p and .B \-d switch. .TP \(bu Illegal block size requested. .TP \(bu Unknown disk name was specified and user did not supply disk information. .TP \(bu Disk's maximum storage space is less than approximately 44 MB. .PD .SH WARNINGS Alternate names are not included in the output when the .B \-d switch is used. .PP Blanks are required in the command line between each of the switches when invoking .IR disksecn . .PP A blank is required between the .B \-n switch and the disk name argument to that switch. For example: .IP .B disksecn \-p \-b 1024 \-n hp9712 .PP .I disksecn does not save the block size used to generate the .B /etc/disktab disk description file. The system assumes that the block size used was .SM DEV_BSIZE when it reads the information stored in the .B etc/disktab file. .SH AUTHOR .I disksecn was developed by the University of California, Berkeley. .SH FILES /etc/disktab .SH SEE ALSO disktab(4). .\" index@\f2disksecn\f1 \- calculate default disk section sizes@@@\f3disksecn(1M)\f1 .\" index@calculate default disk section sizes@@@\f3disksecn(1M)\f1 .\" index@default disk section sizes, calculate@@@\f3disksecn(1M)\f1 .\" index@disk section sizes, calculate default@@@\f3disksecn(1M)\f1 .\" index@section sizes, disk, calculate default@@@\f3disksecn(1M)\f1 .\" .\" toc@\f3disksecn(1M)\f1:\0\0\f2disksecn\f1@@@calculate default disk section sizes .\" .\" fileset_database@disksecn.1m@SYS-ADMIN-MAN .\" $Header: diskusg.1m,v 74.1 95/03/30 16:49:29 ssa Exp $ .TA d .TH diskusg 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME diskusg \- generate disk accounting data by user ID .SH SYNOPSIS .C /usr/sbin/acct/diskusg .RI [ \|options\| ] .RI [ \|files\| ] .SH DESCRIPTION .C diskusg generates intermediate disk accounting information from data in .IR files , or the standard input if omitted. .C diskusg outputs lines on the standard output, one per user, in the following format: .IP .I "uid login #blocks" .PP where: .RS .TP 10 .I uid User's numerical user .SM ID, .TP .I login User's login name, and .TP .I #blocks Total number of disk blocks allocated to this user. .RE .PP .C diskusg normally reads only the inodes of file systems for disk accounting. In this case, .I files are the special filenames of these devices. .SS Options .C diskusg recognizes the following options: .RS .TP 15 .C -s Input data is already in .C diskusg output format. .C diskusg combines all lines for a single user into a single line. .TP .C -v verbose. Print a list on standard error of all files that are charged to no one. .TP .CI -i \0fnmlist Ignore the data on those file systems whose file system name is in .IR fnmlist . .I fnmlist is a list of file system names, separated by commas or enclosed within quotes. .C diskusg compares each name in this list with the file system name stored in the volume .SM ID if it exists. .TP .CI -p \0file Use .I file as the name of the password file to generate login names. .C /etc/passwd is used by default. .TP .CI -u \0file Write records to .I file of files that are charged to no one. Records consist of the special file name, the inode number, and the user .SM ID. .RE .PP The output of .C diskusg is normally the input to .C acctdisk (see .IR acct (1M)) which generates total accounting records that can be merged with other accounting records. .C diskusg is normally run in .C dodisk (see .IR acctsh (1M)). .SH EXAMPLES The following generates daily disk accounting information: .nf .IP .C "for i in /dev/rp00 /dev/rp01 /dev/rp10 /dev/rp11; do" .C " diskusg $i > dtmp.`basename $i` &" .C done .C wait .C "diskusg -s dtmp.* | sort +0n +1 | acctdisk > disktacct" .fi .SH FILES .TP 20 .C /etc/passwd used for user-\c .SM ID\c -to-login-name conversions .SH SEE ALSO acct(1M), acctsh(1M), volcopy(1M), acct(4), vxdiskusg(1M). .SH STANDARDS CONFORMANCE .CR diskusg ": SVID2, SVID3" .\" .\" index@\f4diskusg\f1 \- generate disk accounting data by user \s-1ID\s+1@@@\f3diskusg(1M)\f1 .\" index@\f1disk usage, generate disk accounting data by user \s-1ID\s+1@@@\f3diskusg(1M)\f1 .\" index@\f1disk accounting data, disk usage by user \s-1ID\s+1@@@\f3diskusg(1M)\f1 .\" index@\f1accounting data, disk usage by user \s-1ID\s+1@@@\f3diskusg(1M)\f1 .\" .\" toc@\f3diskusg(1M)\f1:\0\0\f4diskusg\f1@@@generate disk accounting data by user ID .\" .\"========================================================= .\" (c) 1992 Hewlett-Packard Company. All Rights Reserved. .\" Author: Hewlett-Packard DMD .\"========================================================= .\" .\"@(#) $Header: dlf.1m,v 1.2 95/12/15 11:37:59 hmgr Exp $ .TA d .TH dlf 1M .SH NAME dlf \- download firmware to an .SM HP SCSI disk array .SH SYNOPSIS .HP .C dlf -f .I firmware_file device_file .SH DESCRIPTION .C dlf downloads a new set of controller firmware to the .SM HP SCSI disk array associated with device file .I device_file. The .I firmware_file must be a binary file with a special format. .SH RETURN VALUE .C dlf returns the following values: .RS 5 .TP 0 Successful completion. .PD 0 .TP \-1 Command failed (an error occurred). .PD .PP .RE .SH ERROR MESSAGES Errors can originate from problems with: .RS .TP 3 \(bu .C dlf .TP \(bu .SM SCSI (device level) communications .TP \(bu system calls .RE .PP .SS Error messages generated by dlf: .TP .C "usage: dlf -f " An error in command syntax has occurred. Enter command again with all required arguments, in the order shown. .TP .C "dlf: Binary file has bad format" The binary file could not be read in properly by the utility. .TP .C "dlf: device busy" .tr ~" To ensure that .C dlf does not modify a disk array that is being used by another process, .C dlf attempts to obtain exclusive access to the disk array. If the disk array is already opened by another process (for example, LVM \(em the Logical Volume Manager), a .RC ~ "device busy" ~ error message is returned by the driver. To eliminate the .RC ~ "device busy" ~ condition, determine what process has the device open. In the case of LVM, it is necessary to deactivate the volume group containing the array before configuring the array (see .CR vgchange (1M)). .tr ~~ .TP .C "dlf: LUN # too big" The .SM LUN number, which is derived from the device file name, is out of range. .TP .C "dlf: Not a raw file" Utilities must be able to open the device file for raw access. .TP .C "dlf: Not an HP SCSI disk array" The device being addressed is not an .TP .C "dlf: Transfer length error" The amount of data actually sent to or received from the device was not the expected amount. .SM HP SCSI disk array. .PP .SS SCSI (device level) communication errors: Sense data associated with the failed operation is printed. .PP .SS Error messages generated by system calls: .C dlf uses the following system calls: .IP .CR malloc() , .CR free() , .CR stat() , .CR open() , .CR close() , .CR fopen() , .CR fclose() , .CR read() , .CR write() , and .CR ioctl() . .PP Documentation for these .SM HP-UX system calls contains information about the specific error conditions associated with each call. .C dlf does not alter the value of .CR errno . The interpretation of .C errno for printing purposes is performed by the system utility .CR strerror() . .SH EXAMPLES .PP To download the special-format binary file .C new_firmware to the .SM HP SCSI disk array .C /dev/rdsk/c2t0d0 on a series 800: .IP .C "dlf -f new_firmware /dev/rdsk/c2t0d0" .SH DEPENDENCIES The HP C2425 and HP C2427 disk arrays are only supported on Series 700 systems running HP-UX version 9.0X. .PP The HP C2430 disk array is supported on Series 700 and 800 systems runing HP-UX versions 9.0X and 10.0X. .SH AUTHOR .PP .C dlf was developed by .SM HP. .\" .\" index@\f4dlf\f1 \- download firmware to an \s-1HP SCSI\s+1 disk array@@@\f3dlf(1M)\f1 .\" index@disk array, download firmware to@@@\f3dlf(1M)\f1 .\" .\" toc@\f3dlf(1M)\f1:\0\0\f4dlf\f1@@@download firmware to an \s-1HP SCSI\s+1 disk array .\" .\" fileset_database@dlf.1m SYS-ADMIN-MAN .\" $Header: dmesg.1m,v 78.1 95/12/20 10:44:21 ssa Exp $ .TA d .TH dmesg 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dmesg \- collect system diagnostic messages to form error log .SH SYNOPSIS .C /usr/sbin/dmesg .RC [ - ] .RC [ core ] .RC [ system ] .SH DESCRIPTION .C dmesg looks in a system buffer for recently printed diagnostic messages and prints them on the standard output. The messages are those printed by the system when unusual events occur (such as when system tables overflow or the system crashes). If the .C - argument is specified, .C dmesg computes (incrementally) the new messages since the last time it was run and places these on the standard output. This is typically used with .C cron (see .IR cron (1)) to produce the error log .C /var/adm/messages by running the command: .IP .C "/usr/sbin/dmesg - >> /var/adm/messages" .PP every 10 minutes. .PP The arguments .C core and .C system allow substitution for the defaults .C /dev/kmem and .C /stand/vmunix\f1 respectively, where .C core should be a file containing the image of the kernel virtual memory saved by the .C savecore(1M) command and .C system should be the corresponding kernel. If the system is booted with a kernel other than /stand/vmunix say /stand/vmunix_new, .C dmesg must be passed this name, the command must be, .IP .C "/usr/sbin/dmesg [-] /dev/kmem /stand/vmunix_new" .SH WARNINGS The system error message buffer is of small, finite size. .C dmesg is run only every few minutes, so there is no guarantee that all error messages will be logged. .SH AUTHOR .C dmesg was developed by the University of California, Berkeley. .SH FILES .TP 25 .C /var/adm/messages error log (conventional location) .PD 0 .TP 25 .C /var/adm/msgbuf memory scratch file for .CR - option .TP 25 .C /dev/kmem special file containing the image of kernel virtual memory .TP 25 .C /stand/vmunix the kernel, system name list .PD .SH SEE ALSO savecore(1M). .\" .\" index@\f4dmesg\f1 \- collect system diagnostic messages to form error log@@@\f3dmesg(1M)\f1 .\" index@collect system diagnostic messages to form error log@@@\f3dmesg(1M)\f1 .\" index@system diagnostic messages, collect to form error log@@@\f3dmesg(1M)\f1 .\" index@diagnostic messages, collect to form system error log@@@\f3dmesg(1M)\f1 .\" index@messages, diagnostic, collect to form system error log@@@\f3dmesg(1M)\f1 .\" index@error log, collect system diagnostic messages to form@@@\f3dmesg(1M)\f1 .\" index@log, error, collect system diagnostic messages to form@@@\f3dmesg(1M)\f1 .\" .\" toc@\f3dmesg(1M)\f1:\0\0\f4dmesg\f1@@@collect system diagnostic messages to form error log .\" .\" fileset_database@dmesg.1m SYS-ADMIN-MAN .\" $Header: acctsh.1m,v 72.4 94/11/14 12:02:10 ssa Exp $ .TA a .TH acctsh 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chargefee, ckpacct, dodisk, lastlogin, monacct, nulladm, prctmp, prdaily, prtacct, shutacct, startup, turnacct \- shell procedures for accounting .SH SYNOPSIS .C /usr/sbin/acct/chargefee .I login-name number .PP .C /usr/sbin/acct/ckpacct .RI [ \|blocks\| ] .PP .C /usr/sbin/acct/dodisk .RC [ -o ] .RI [ \|files \0 ...\|] .PP .C /usr/sbin/acct/lastlogin .PP .C /usr/sbin/acct/monacct .I number .PP .C /usr/sbin/acct/nulladm .I file .PP .C /usr/sbin/acct/prctmp .PP .C /usr/sbin/acct/prdaily .RC [ -l ] .RC [ -c ] .RC [ \c .IR mmdd\| ] .PP .C /usr/sbin/acct/prtacct .I file .RI [ \|heading\| ] .PP .C /usr/sbin/acct/shutacct .RI [ \|reason\| ] .PP .C /usr/sbin/acct/startup .PP .C /usr/sbin/acct/turnacct .CR on \0\(or\0 off \0\(or\0 switch .SH DESCRIPTION .TP 15 .C chargefee Can be invoked to charge a .I number of units to .IR login-name . A record is written to .CR /var/adm/fee , to be merged with other accounting records during the night. .TP .C ckpacct Should be initiated via .IR cron (1M). It periodically checks the size of .CR /var/adm/pacct . If the size exceeds .IR blocks , 1000 by default, .C turnacct is invoked with argument .IR switch . If the number of free disk blocks in the .C /var file system falls below 500, .C ckpacct automatically turns off the collection of process accounting records via the .C off argument to .CR turnacct . When at least this number of blocks is restored, the accounting will be activated again. This feature is sensitive to the frequency at which .C ckpacct is executed, usually by .CR cron . .TP .C dodisk Should be invoked by .C cron to perform the disk accounting functions. By default, it will do disk accounting on the special files in .C /etc/fstab. If the .C -o flag is used, it does a slower version of disk accounting by login directory. .I files specifies the one or more filesystem names where disk accounting is to be done. If .I files is used, disk accounting will be done on these filesystems only. If the .C -o flag is used, .I files should be mount points of mounted filesystem. If omitted, they should be the special file names of mountable filesystems. .TP .C lastlogin Invoked by .C runacct to update .C /var/adm/acct/sum/loginlog which shows the last date on which each user logged in (see .IR runacct (1M)). .TP .C monacct Should be invoked once each month or each accounting period. .I number indicates which month or period it is. If .I number is not given, it defaults to the current month (01 through 12). This default is useful if .C monacct is to executed via .CR cron on the first day of each month. .C monacct creates summary files in .C /var/adm/acct/fiscal and restarts summary files in .CR /var/adm/acct/sum . .TP .C nulladm Creates .I file with mode 664 and ensures that owner and group are .CR adm . It is called by various accounting shell procedures. .TP .C prctmp Can be used to print the session record file normally .C /var/adm/acct/nite/ctmp created by .C acctcon1 (see .IR acctcon (1M)). .TP .C prdaily Invoked by .C runacct (see .IR runacct (1M)) to format a report of the previous day's accounting data. The report resides in .CI /var/adm/acct/sum/rprt mmdd where .I mmdd is the month and day of the report. The current daily accounting reports may be printed by typing .IR prdaily . Previous days' accounting reports can be printed by using the .I mmdd option and specifying the exact report date desired. The .C -l flag prints a report of exceptional usage by login id for the specifed date. Previous daily reports are cleaned up and therefore inaccessible after each invocation of .CR monacct . The .C -c flag prints a report of exceptional resource usage by command, and can be used on current day's accounting data only. .TP .C prtacct Can be used to format and print any total accounting .RC ( tacct ) file. .TP .C shutacct Should be invoked during a system shutdown to turn process accounting off and append a ``reason'' record to .CR /var/adm/wtmp . .TP .C startup Should be called by system startup scripts to turn the accounting on whenever the system is brought up. .TP .C turnacct An interface to .C accton (see .IR acct (1M)) to turn process accounting .C on or .CR off . The .C switch argument turns accounting off, moves the current .C /var/adm/pacct to the next free name in .CI /var/adm/pacct incr then turns accounting back on again. .RI ( incr is a number starting with .C 1 and incrementing by one for each additional .C pacct file.) .C turnacct is called by .CR ckpacct , and thus can be run under .C cron and used to keep .C pacct to a reasonable size. .SH FILES .TP 40 .C /usr/sbin/acct holds all accounting commands listed in section (1M) of this manual .PD 0 .TP .C /var/adm/fee accumulator for fees .TP .C /var/adm/acct/nite working directory .TP .C /var/adm/pacct current file for per-process accounting .TP .C /var/adm/pacct* used if .C pacct gets large, and during execution of daily accounting procedure .TP .C /usr/sbin/acct/ptecms.awk contains the limits for exceptional usage by command name .TP .C /usr/sbin/acct/ptelus.awk contains the limits for exceptional usage by login id .TP .C /var/adm/acct/sum summary directory, should be saved .TP .C /var/adm/wtmp login/logoff summary .PD .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), cron(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR chargefee ": SVID2, SVID3" .PP .CR ckpacct ": SVID2, SVID3" .PP .CR dodisk ": SVID2, SVID3" .PP .CR lastlogin ": SVID2, SVID3" .PP .CR monacct ": SVID2, SVID3" .PP .CR prctmp ": SVID2, SVID3" .PP .CR prdaily ": SVID2, SVID3" .PP .CR prtacct ": SVID2, SVID3" .PP .CR shutacct ": SVID2, SVID3" .PP .CR startup ": SVID2, SVID3" .PP .CR turnacct ": SVID2, SVID3" .\" .\" .\" index@\f1process accounting@@@see accounting .\" index@\f1accounting: \f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4turnacct\f1 \- turn on or turn off process accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1bill fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1user, bill fee to, based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1disk accounting, perform@@@\f3acctsh(1M)\f1 .\" index@\f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1user, show last login date for each@@@\f3acctsh(1M)\f1 .\" index@\f1last login date, show for each user@@@\f3acctsh(1M)\f1 .\" index@\f1login date, show last for each user@@@\f3acctsh(1M)\f1 .\" index@\f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1periodic accounting summary files, create@@@\f3acctsh(1M)\f1 .\" index@\f1accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1files: accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1summary files, accounting, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1create empty administration file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1empty administration file owned by \f3adm\f1 with mode 664, create@@@\f3acctsh(1M)\f1 .\" index@\f1administration file owned by \f3adm\f1 with mode 664, create empty@@@\f3acctsh(1M)\f1 .\" index@\f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f4acctcon1\f1 \- print session record file created by@@@\f3acctsh(1M)\f1 .\" index@\f1print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1files, accounting: print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1session record file created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f1record file, session, created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1total accounting (\f4tacct\f1) file, print any@@@\f3acctsh(1M)\f1 .\" index@\f1accounting (\f4tacct\f1) file, print any total@@@\f3acctsh(1M)\f1 .\" index@\f4tacct\f1 (total accounting) file, print any@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting: \f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" index@\f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting data and command usage summary, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f1command usage summary and accounting data, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1system shutdown, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f1shutdown, system, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1system startup, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f1startup, system, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f4turnacct\f1 \- turn process accounting on or off@@@\f3acctsh(1M)\f1 .\" index@\f1shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f1system accounting, shell procedures for@@@\f3acctsh(1M)\f1 .\" .\"" Main TOC entry .\" toc@\f3acctsh(1M)\f1:\0\0\f4chargefee\f1, \f4ckpacct\f1, \f4dodisk\f1, \f4lastlogin\f1, \f4monacct\f1, \f4nulladm\f1, \f4prctmp\f1, \f4prdaily\f1,\n\f4prtacct\f1, \f4shutacct\f1, \f4startup\f1, \f4turnacct\f1@@@shell procedures for accounting .\" .\" toc@\f4chargefee\f1:\0\0shell procedures for accounting, charge fee to user@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4ckpacct\f1:\0\0shell procedures for accounting, check size of accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4dodisk\f1:\0\0shell procedures for accounting, perform disk accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4lastlogin\f1:\0\0shell procedures for accounting, show last login date@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4monacct\f1:\0\0shell procedures for accounting, create accounting summary@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4nulladm\f1:\0\0shell procedures for accounting, create null file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prctmp\f1:\0\0shell procedures for accounting, print session record file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prdaily\f1:\0\0shell procedures for accounting, print daily report@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prtacct\f1:\0\0shell procedures for accounting, print accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4shutacct\f1:\0\0shell procedures for accounting, turn off accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4startup\f1:\0\0shell procedures for accounting, start up accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4turnacct\f1:\0\0shell procedures for accounting, turn on or off process accounting@@@\f1see \f3acctsh(1M)\f1 .\" .\" links@acctsh.1m chargefee.1m .\" links@acctsh.1m ckpacct.1m .\" links@acctsh.1m dodisk.1m .\" links@acctsh.1m lastlogin.1m .\" links@acctsh.1m monacct.1m .\" links@acctsh.1m nulladm.1m .\" links@acctsh.1m prctmp.1m .\" links@acctsh.1m prdaily.1m .\" links@acctsh.1m prtacct.1m .\" links@acctsh.1m shutacct.1m .\" links@acctsh.1m startup.1m .\" links@acctsh.1m turnacct.1m .\" .\" fileset_database@acctsh.1m SYS-ADMIN-MAN .\" $Header: dpp.1m,v 74.1 95/01/25 15:52:52 ssa Exp $ .TA d .TH dpp 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dpp \- dedicated ports parser used by DDFA software .SH SYNOPSIS .CR dpp .I dp_file .RC [ \-c ] .RC [ \-k ] .RC [ \-l .IR log_file ] .RC [ \-p .IR ocd_program ] .SH DESCRIPTION The Dedicated Ports Parser command .RC ( dpp ) is part of the Data Communications and Terminal Controller (DTC) Device File Access (DDFA) software. It parses the Dedicated Ports file .RC ( dp ) and spawns an Outbound Connection Daemon .RC ( ocd ) for each valid entry in the .CR dp file. .PP .CR dpp can be run from the shell or it can be included in a system initialization script to automatically run the DDFA software each time the system is booted. .PP See .IR ddfa (7) for more information on how to configure the DDFA software and for an explanation of how it works. .SS Options and Arguments .CR dpp recognizes the following options and arguments: .RS .TP 18 .I dp_file It must be the first argument. The .CR dp file .RI ( dp_file ) defines the link between a terminal server port and the device file used by applications to access the port. Its contents must meet the specifications given in .IR dp (4). If it is modified, .CR dpp must be run again to activate the changes. .TP .CR \-c Specify that the .CR dp file should be parsed and that all incorrect entries should be logged without invoking any .CR ocd processes. This option is useful for debugging the .CR dp file before running it properly. The .CR \-p option is ignored if the .CR \-c option is used. .TP .CR \-k Specify that the device file corresponding to each valid entry in the .CR dp file should be removed before launching .CR ocd for each valid entry. .IP .CR ocd normally creates and removes devices files. However, if the process is killed incorrectly, such as with .CR "kill \-9" , the device file may remain. If the system is rebooted, the .CR \-k option can be specified to restart all .CR dp file entries correctly. Deleting the device file eventually causes an .CR ocd process (if any is running) to exit. .IP If a corresponding .CR ocd no longer exists, the device file is removed by any following invocation of .CR ocd that requires the same device file. .TP .CI \-l log_file Specify where to log error messages. If this option is omitted, all error messages are logged to standard output. .IP If the specified file does not already exist, it is created. The file must be nonexecutable and readable by .CR dpp . .TP .CI \-p ocd_program Specify the path for an outbound connection daemon. The default path for is .CR /usr/sbin/ocd . The daemon must be executable. .RE .SH DIAGNOSTICS Error messages are logged for bad arguments, bad file entries, and .CR ocd creation errors. By default, they are logged to standard output. If the .CI \-l option is used, they are appended to the specified log file. .PP .C "(0) ERROR: dp file is mandatory .PP .C "(1) ERROR: dp file must be the first argument .PP .CI "(2) ERROR: Cannot read dp file (" filename ) .IP The .CR dp file either does not exist or cannot be accessed with the current access privileges. .PP .C "(3) ERROR: No log file defined (-l option) .PP .CI "(4) ERROR: Cannot create log file (-l " filename ) .IP The log file cannot be created, either because of an invalid path or because of insufficient access privileges. .PP .CI "(5) ERROR: Cannot access log file (-l " filename ) .IP The log file cannot be accessed, either because of an invalid path or because of insufficient access privileges. The log file must be readable by everyone. .PP .C "(6) ERROR: No ocd file defined in program option .PP .CI "(7) ERROR: Cannot execute ocd program (-p " pathname ) .IP The .CR ocd program specified in the .CR \-p option either does not exist or is not an executable file with the current access privileges. .PP .CI "(8) ERROR: Cannot purge device file (/dev/" filename ) .IP The .CR \-k option has been specified and the device file exists, but it cannot be purged because of insufficient access privileges. .PP .C "(9) ERROR: Cannot execute default program (/usr/sbin/ocd) .IP The default .CR ocd cannot be executed, either because of insufficient access privileges or because it has not been correctly installed. .PP .C "(10) ERROR: Entry ignored (Bad IP address) .IP The .CR dp file entry specified does not have a valid IP address. .PP .C "(11) ERROR: Entry ignored (no port/board info) .PP .C "(12) ERROR: Entry ignored (Bad port number) .IP The port specified is either not a decimal value or a string composed of .CR x or .CR X characters. .PP .C "(13) ERROR: Entry ignored (Bad board number) .IP The board specified is either not a decimal value or a string composed of .CR x or .CR X characters. .PP .C "(14) ERROR: No more processes available on system .IP The .CR ocd program specified cannot be started because there are no processes available on the system. .PP .C "(15) ERROR: Entry ignored (no device_name) .PP .C "(16) ERROR: Entry ignored (Bad device_name) .IP The device file specified cannot be created, either because of an invalid path or because of insufficient access privileges. .PP .C "(17) ERROR: Entry ignored (Bad config name) .IP The specified configuration file cannot be read, either because of an invalid path or because of insufficient access privileges. .PP .C "(18) ERROR: Entry ignored (Invalid log level) .IP The specified logging level is not in the range 0 to 3. .PP .C "(19) ERROR: Entry ignored (Bad node name) .IP The specified node name does not exist or does not have an entry in a name database. .\"X EDITOR'S NOTE: .\"X The following diagnostics appear in the dpp program text but were not .\"X described in the submitted manpage. -- allanp .\"X .C "(30) ERROR: Too many login entries (limited to %s) .\"X Port identification feature for '%s' device file name is disable. .\"X .C "(31) ERROR: Cannot access dpp login file (%s) .\"X Port identification feature is disable (Bad installation). .\"X .C "(50) WARNING: Device file not specified in /dev/telnet .\"X Many commands (such as ps) may not display the correct device file name in their output .\"X >>>>> %s <<<<< .\"X .C "(99) ERROR: Unknown error (%d) .SH WARNINGS To ensure that commands (such as .IR ps ) display the correct device file name (that is, the .IR pseudonym ), all pseudonyms should be placed into the directory .CR /dev/telnet . If pseudonyms are not specified for placement in this directory, the correct display of device file names with many commands is not guaranteed. .PP Also, in order to reliably handle timing mark negotiations (and ensure that files printing on a printer attached to a terminal server have been completely flushed to that printer), the following line must be added near the end of each printer interface script for printers attached to a terminal server: .IP .C "stty exta <&1 2>/dev/null" .PP The printer interface scripts reside in the directory .CR /etc/lp/interface . The line must be added just prior to the final 'exit' command in each printer interface script. .PP If this line is not added as specified, the printing reliability of printers attached to a terminal server is not guaranteed. .PP Finally, .CR ocd should be killed using .CR "kill \-15" . Do not use .CR "kill \-9" for this purpose as it does not remove the device file. .CR ocd verifies the validity of an existing pseudonym before trying to use it. .CR dpp and .CR ocd use data stored in the file .CR /var/adm/utmp.dfa to verify whether a process still owns a pseudonym before taking it over. If .CR ocd finds an unowned pseudonym, it uses it. .SH FILES .nf .CR /usr/examples/ddfa/dp .CR /usr/examples/ddfa/pcf .CR /usr/sbin/dpp .CR /usr/sbin/ocd .CR /usr/sbin/ocdebug .CR /var/adm/dpp_login.bin .CR /var/adm/utmp.dfa .fi .SH SEE ALSO ocd(1M), ocdebug(1M), dp(4), pcf(4), ddfa(7). .\" .\" toc@\f3dpp(1M)\f1:\0\0\f4dpp\f1@@@dedicated ports parser used by DDFA software .\" .\" index@\f4dpp\f1 \- dedicated ports parser used by DDFA software@@@\f3dpp(1M)\f1 .\" index@dedicated ports parser used by DDFA software@@@\f3dpp(1M)\f1 .\" index@ports parser used by DDFA software, dedicated@@@\f3dpp(1M)\f1 .\" index@parser used by DDFA software, dedicated ports@@@\f3dpp(1M)\f1 .\" index@DDFA software, dedicated ports parser used by@@@\f3dpp(1M)\f1 .\" $Header: drm_admin.1m,v 74.1 95/01/25 16:18:55 ssa Exp $ .TA d .TH drm_admin 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drm_admin \- Data Replication Manager administrative tool .SH SYNOPSIS .B /usr/sbin/ncs/drm_admin .RB [ \|\-\f2version\fP\| ] .SH DESCRIPTION .I drm_admin administers servers based on the Data Replication Manager .SM (DRM) such as .IR glbd , the replicated version of the Global Location Broker .SM (GLB). .PP .I drm_admin is used to inspect or modify replica lists, merge databases to force convergence among replicas, stop servers, and delete replicas. .PP The role of .I drm_admin is to administer the replication of databases, not to change the data they contain. For example, use .I drm_admin to merge two replicas of the .SM GLB database; use .I lb_admin to add a new entry to the database. Also, although .I drm_admin can stop or delete a GLB replica, you must invoke .B glbd directly if you want to start or create a replica. .PP Once invoked, .I drm_admin enters an interactive mode, in which it accepts the commands described below. .SH OPTIONS .TP \f3\-version Display the version of NCK that this .I drm_admin belongs to, but do not start the tool. .SH COMMANDS Most .I drm_admin commands operate on a default object (\f2default_obj\f1) at a default host (\f2default_host\f1). Together, .I default_obj and .I default_host specify a default replica. Defaults are established by the .B set command and are remembered until changed by another .BR set . .PP Currently, the only known object is .BR glb . .PP Some .I drm_admin commands operate on a host other than the default. We identify this host as .I other_host . .PP The host name you supply as a .I default_host or an .I other_host takes the form .IB family : host\f1, where the host can be specified either by its name or by its network address. For example, .BR ip:bertie , .BR ip:#192.5.5.5 , .BR dds://jeeves , and .B dds:#101a.57f95 are acceptable host names. (All .SM HP-UX hosts have .B ip as the .IR family .) .TP .BI addrep \ other_host Add .I other_host to the replica list at .IR default_host . The replica at .I default_host will propagate .I other_host to all other replica lists for .IR default_obj . .TP \f3chrep\f1 \f3\-from\f1 \f2other_host\f1 \f3\-to\f1 \f2new_other_host\f1 Change the network address for .I other_host in the replica list at .I default_host to .IR new_other_host . The replica at .I default_host will propagate this change to all other replica lists for .IR default_obj . The .B chrep command fails if a replica of .I default_obj is running at .I other_host or if .I other_host is not on the replica list at .IR default_host . .TP .BI delrep \ other_host Delete the replica of .I default_obj at .IR other_host . The .B delrep command tells the replica at .I other_host .RS .RS .TP 5 1. To propagate all of the entries in its propagation queue. .TP 2. To propagate a delete request to all other replicas, causing .I other_host to be deleted from all other replica lists for .IR default_obj . .TP 3. To delete its copy of .I default_obj . .TP 4. To stop running. .RE .RE .IP The .B delrep command returns you immediately to the .I drm_admin prompt, but the actual deletion of the replica can take a long time in configurations that are not stable and intact. To check whether the daemon for the deleted replica has stopped, list the processes running on its host. .TP .B info Get status information about the replica for .I default_obj at .IR default_host . .TP \f3lrep\f1 [ \f3\-d\f1 ] [ \f3\-clocks\f1 ] [ \f3\-na\f1 ] List replicas for .I default_obj as stored in the replica list at .IR default_host . .IP The .B \-d option lists deleted as well as existing replicas. .IP The .B \-clocks option shows the current time on each host and indicates clock skew among the replicas. .IP The .B \-na option lists the network address of each host. .TP \f3merge\f1 { \f3\-from\f1 | \f3\-to\f1 } \f2other_host\f1 The .B merge command copies entries in the .I default_obj database and replica list from one replica to another. It copies an entry if no corresponding entry exists in the destination database or if the corresponding entry in the destination database bears an earlier timestamp. .IP A merge does not cause entries to be propagated. The database and replica list at the origination are not changed. .IP The .B \-from option copies entries from the .I default_obj database and replica list at .I other_host to the .I default_obj database and replica list at .IR default_host . .IP The .B \-to option copies entries from the database and replica list at .I default_host to the database and replica list at .IR other_host . .IP A .B merge \-from followed by a .B merge \-to causes the replicas at the two hosts to converge. .TP .B merge_all The .B merge_all command uses .I default_host as the hub for a global merge of all replicas for .IR default_obj . For each host on the replica list at .IR default_host , a .B merge_all first does a .BR merge\0\-from , then does a .BR merge\0\-to . All replicas of .I default_obj are thereby forced into a consistent state. The .B merge_all operation does not cause any entries to be propagated. .IP Perform a .B merge_all when: .RS .TP 3 \(bu A replica is purged, .TP \(bu A replica is reset, .TP \(bu A replica has been incommunicado for two weeks or more, .TP \(bu A replica dies (for example, its database is destroyed by a disk failure). .RE .TP \f3monitor\f1 [ \f3\-r\f1 \f2n\f1 ] This command causes .I drm_admin to read the clock of each replica of .I default_obj every .I n minutes and report any clock skews or non-answering replicas. If .B \-r is not specified, the period is 15 minutes. .TP .BI purgerep \ other_host The .B purgerep command purges .I other_host from the replica list at .IR default_host . The replica at .I default_host then propagates a delete request to the replicas at the hosts remaining on its list, thereby removing .I other_host from all other replica lists for .IR default_obj . The delete request is not sent to .IR other_host . .IP A .B purgerep can cause data to be lost and should only be used when a replica has died. A .B merge_all operation after the .B purgerep is strongly recommended to prevent the remaining replicas of the .I default_obj database from becoming inconsistent. If the purged replica is still running, it should be .BR reset . .IP Recommendation: Use .B chrep (rather than .B addrep and .BR purgerep ) to change entries on the replica list. .TP .B quit Quit the .I drm_admin session. .TP .BI reset \ other_host Reset the replica of .I default_obj at .IR other_host . .IP The .B reset command tells the replica at .I other_host to delete its copy of .I default_obj and stop running. It does not cause .I other_host to be deleted from any other replica lists. This command can cause data to be lost unless a successful .B merge_all is done first. .TP \f3set\f1 [ \f3\-o\f1 \f2obj_name\f1 ] \f3\-h\f1 \f2host_name\f1 Set the default object and host. All subsequent commands operate on .IR obj_name . Subsequent commands that do not specify a host are sent to .IR host_name . If you do not specify the .B \-o option, .I drm_admin keeps the current .IR default_obj . .IP If you use .B set with the .B \-o option, .I drm_admin checks the clocks at all hosts with replicas of the specified object. .TP .B stop Stop the server for .I default_obj that is running at .IR default_host . .SH EXAMPLES Start .IR drm_admin , set the default object to .BR glb , and set the default host to .BR mars : .ta .5i, 3i .IP .nf .RB $ \ /usr/sbin/ncs/drm_admin .RB drm_admin: " set \-o glb \-h ip:mars" .B " Default object: glb default host: ip:mars state: in service" .B " Checking clocks of glb replicas" .B " ip:mars 1987/04/09.17:09" .B " ip:pluto 1987/04/09.17:09" .B " ip:mercury 1987/04/09.17:07" .fi .DT .SH SEE ALSO glbd(1M), lb_admin(1M). .\" .\" index@Network Computing System@@@see \s-1NCS\s0 .\" index@\s-1NCS\s0: Data Replication Manager administrative tool@@@ \f3drm_admin(1M)\f1 .\" index@\f2drm_admin\f1 \- Data Replication Manager administrative tool@@@ \f3drm_admin(1M)\f1 .\" index@Data Replication Manager administrative tool@@@ \f3drm_admin(1M)\f1 .\" index@administrative tool, Data Replication Manager@@@ \f3drm_admin(1M)\f1 .\" index@replicating Global Location Brokers@@@ \f3drm_admin(1M)\f1 .\" index@administering Global Location Brokers@@@ \f3drm_admin(1M)\f1 .\" index@Global Location Brokers, administering@@@ \f3drm_admin(1M)\f1 .\" index@Location Brokers, replicating@@@ \f3drm_admin(1M)\f1 .\" index@Location Brokers, administering@@@ \f3drm_admin(1M)\f1 .\" index@Global Location Brokers, replicating@@@ \f3drm_admin(1M)\f1 .\" .\" toc@\f3drm_admin(1M)\f1:\0\0\f2drm_admin\f1@@@Data Replication Manager Administrative Tool .\" .\" fileset_database@drm_admin.1m@SYS-ADMIN-MAN .\"========================================================= .\" (c) 1992 Hewlett-Packard Company. All Rights Reserved. .\" Author: Hewlett-Packard DMD .\"========================================================= .\" .\"@(#) $Header: dsp.1m,v 1.2 95/12/15 11:38:25 hmgr Exp $ .TA d .TH dsp 1M .SH NAME dsp \- display status of an .SM HP SCSI disk array .SH SYNOPSIS .HP .C dsp -p .RC [ -h | -d ] .I device_file .PP .C dsp -l .RC [ -h | -d ] .I device_file .SH DESCRIPTION .C dsp displays the status of the .SM LUN (in an .SM HP SCSI disk array) that is associated with the device file .IR device_file . .C dsp displays the status of physical drives in an array (when the .C -p option is specified), or the status of .SM LUN\c s in an array (when the .C -l option is specified). This information can be displayed in interpreted form, or in raw hexadecimal or raw decimal format. .SS Options .RS .TP 15 .C -p Display physical drive status. The .C -p option displays the status of a .SM LUN's physical drives, regardless of their .SM LUN ownership. This information is retrieved the array physical page (Mode Page 2A), and inquiry data. .TP .C -l Display .SM LUN status. The .C -l option displays information about the state of the .SM LUN including it's .SM RAID level, block and segment sizes, reconstruction information, and so on. This information is retrieved from the array logical page (Mode Page 2B), and inquiry data. .PP By default, data is displayed in interpreted form; if raw data is desired, one of the following options can be used: .TP 15 .C -h Raw hex format. Displays the data in raw hex format in rows, each of which contains the .SM ASCII representation of 16 hexadecimal data bytes, separated by spaces. .TP .C -d Raw decimal format. Displays the data in raw decimal format in rows, each of which contains the .SM ASCII representation of 16 decimal data bytes, separated by spaces. .SH RETURN VALUE .C dsp returns the following values: .RS 5 .TP .B " 0" Successful completion. .PD 0 .TP .B -1 Command failed (an error occurred). .PD .PP .RE .SH DIAGNOSTICS AND ERRORS Errors can originate from problems with: .RS .TP 3 \(bu .C dsp .TP \(bu .SM SCSI (device level) communications .TP \(bu system calls .RE .PP .SS Error messages generated by dsp: .TP .C "usage: dsp <-p | -l> [-h | -d] " An error in command syntax has occurred. Enter the command again with all required arguments. .TP .C "dsp: Arg out of range" One of the arguments is larger than its allowed maximum value (or smaller than its allowed minimum value), or is incorrect in form. Check the size and form of each argument and make appropriate corrections. .TP .C "dsp: LUN # too big" The .SM LUN number, which is derived from the device special file name, is out of range. .TP .C "dsp: Not a raw file" Utilities must be able to open the device file for raw access. .TP .C "dsp: Transfer length error" The amount of data actually sent to or received from the device was not the expected amount. .TP .C "dsp: LUN does not exist" The requested .SM LUN is not among those known to the controller. .TP .C "dsp: Not an HP SCSI disk array" The device being addressed is not an .SM HP SCSI disk array. .PP .SS SCSI (device level) communication errors: Sense data associated with the failed operation is printed. .PP .SS Error messages generated by system calls: .C dsp uses the following system calls: .IP .CR stat() , .CR open() , .CR close() , .CR read() , .CR write() , and .CR ioctl() . .PP Documentation for these .SM HP-UX system calls contains information about the specific error conditions associated with each call. .C dsp does not alter the value of .CR errno . The interpretation of .C errno for printing purposes is performed by the system utility .CR strerror() . .SH EXAMPLES .PP To display the status of the drives on the .SM HP SCSI disk array .C /dev/rdsk/c2t4d0 on a Series 700: .IP .C "dsp -p /dev/rdsk/c2t4d0" .PP To display the status of the .SM LUN associated with the .SM HP SCSI disk array .C /dev/rdsk/c2t0d0 on a Series 800 in raw hex format: .IP .C "dsp -l -h /dev/rdsk/c2t0d0" .PP To display the status of the drives on the .SM HP SCSI disk array .C /dev/rdsk/c2t5d0 in raw decimal format on a Series 700: .IP .C "dsp -p -d /dev/rdsk/c2t5d0" .SH DEPENDENCIES The HP C2425 and HP C2427 disk arrays are only supported on Series 700 systems running HP-UX version 9.0X. .PP The HP C2430 disk array is supported on Series 700 and 800 systems runing HP-UX versions 9.0X and 10.0X. .SH AUTHOR .PP .C dsp was developed by .SM HP. .\" .\" index@\f4dsp\f1 \- display status of an \s-1HP SCSI\s+1 disk array@@@\f3dsp(1M)\f1 .\" index@disk array, display status of@@@\f3dsp(1M)\f1 .\" .\" toc@\f3dsp(1M)\f1:\0\0\f4dsp\f1@@@display status of an \s-1HP SCSI\s+1 disk array .\" .\" fileset_database@dsp.1m SYS-ADMIN-MAN ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Oct 25, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .nr H1 1 ...\" .rm zA .rm zZ .TH "dts_intro" 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldtscp\*O commands" "summary" .SH NAME \*Ldts_intro\*O - Introduction to the DCE DTS commands .SH "DESCRIPTION" .zA "defect,7991,R1.0.3,added information" .PP The DCE Distributed Time Service (DTS) provides the following facilities: .ML .zA "defect,7837,R1.0.3,added info on relationship between dtsd and dtscp" .LI The \*Ldtsd\*O daemon .LI The DTS control program (\*Ldtscp\*O) .zA "enh 11127,R1.1,added info on dtsdate command" .LI The DTS local clock setting program (\*Ldtsdate\*O) .zZ "enh 11127,R1.1,added info on dtsdate command" .LE .PP The DTS is implemented in the \*Ldtsd\*O process. Both clerks and servers use the same daemon. The behavior of the \*Ldtsd\*O daemon is determined by the \*Ldtscp\*O command. .zZ "defect,7837,R1.0.3,added info on relationship between dtsd and dtscp" .PP The \*Ldtscp\*O control program allows you to synchronize, adjust, and maintain the system clocks in a distributed network. The DTS control program commands are listed below: .ML .LI The \*Ladvertise\*O command, which configures the DTS server as a global server .LI The \*Lchange\*O command, which modifies the epoch and sets the local time to a new time .LI The \*Lcreate\*O command, which establishes a DTS entity (a clerk or server) .LI The \*Ldelete\*O command, which causes DTS to exit on the local node .LI The \*Ldisable\*O command, which suspends a DTS entity .LI The \*Lenable\*O command, which starts a DTS entity .LI The \*Lexit\*O command, which ends the \*Ldtscp\*O management session and returns you to the system prompt .LI The \*Lhelp\*O command which invokes the \*Ldtscp\*O help service. .LI The \*Lquit\*O command, which ends the \*Ldtscp\*O management session and returns you to the system prompt .LI The \*Lset\*O command, which modifies characteristics of a DTS entity .LI The \*Lshow\*O command, which displays characteristics of a DTS entity .LI The \*Lsynchronize\*O command, which synchronizes the system clock with the time obtained from DTS servers in the network .LI The \*Lunadvertise\*O command, which removes the global server entry .LI The \*Lupdate\*O command, which gradually adjusts the system clock to a new time .LE .PP For more information on any of the above \*Ldtscp\*O commands, see the appropriate reference page in this chapter. .zZ "defect,7991,R1.0.3,added information" .PP The \*Ldtsd\*O command restarts the DTS daemon (clerk or server process). When the host system is rebooted, this command is automatically executed as part of the overall DCE configuration procedure. For more information, see the \*Ldtsd\*O reference page in this chapter. .zA "defect,7837,R1.0.3,added info on relationship between dtsd and dtscp" .PP Invocation of \*Ldtsd\*O leaves it in an idle state. In order for it to assume an identity, it must be ``created'' with the \*Ldtscp create\*O command. .PP After the DTS entity is created, it is still in a non-functioning state. To put it into operation, you must invoke \*Ldtscp enable\*O, which causes an immediate synchronization to take place. For more information, see the \*Lenable\*O reference page in this chapter. .PP To bring down a DTS entity, you must first stop it with \*Ldtscp disable\*O and then delete it with \*Ldtscp delete\*O. For more information, see the \*Ldisable\*O and \*Ldelete\*O reference pages in this chapter. .zZ "defect,7837,R1.0.3,added info on relationship between dtsd and dtscp" .PP .zA "enh 11127,R1.1,added info on dtsdate command" The \*Ldtsdate\*O command sets the local clock of a system to be the same as the host \*Vremote_host\*O, running a \*Ldtsd\*O server. For more information see the \*dtsdate\*O reference page in this chapter. .PP .SH "RELATED INFORMATION" .PP Command: \*Ldtscp(1m)\*O \*Ldtsdate(1m)\*O .zZ "enh 11127,R1.1,added info on dtsdate command" .PP Books: \*VDCE Administration Guide\*O, \*VDCE Administration Reference\*O ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Oct 25, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH update 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "clocks" "adjusting" .iX "\*Ldtscp\*O commands" "\*Lupdate\*O" .SH NAME .PP .zA "defect,7838,R1.0.3, change specified server to local node" \*Lupdate\*O - Gradually adjusts the clock on the local node to the specified time .zZ "defect,7838,R1.0.3, change specified server to local node" .SH "SYNOPSIS" .PP .zA "defect,6211,R1.0.3,add control program name" .zA "defect,10890,R1.1,add missing 'time' identifier" .sS \*Ldtscp update time\*O \*Vabsolute-time\*O .sE .zZ "defect,10890,R1.1,add missing 'time' identifier" .zZ "defect,6211,R1.0.3,add control program name" .SH "ARGUMENTS" .VL .LI "\*Ltime\*O \*Vabsolute-time\*O" Specifies the absolute time to which the clock is adjusted. This argument is required. .LE .SH "DESCRIPTION" .PP The \*Lupdate\*O command gradually adjusts the system clock to a new time, beginning at the time specified in the argument. The difference between the current clock value and the absolute time specified in the argument is used to adjust the clock. .SS "Privilege Required" .PP You must have write permission on the ACL associated with the DTS entity in order to execute the command. .SH "NOTES" .PP The \*Lupdate\*O command is valid only for servers. The combined time and inaccuracy value you specify must be contained within the interval formed by the current time and inaccuracy. That is, the new setting must be more accurate than the current time. .zA "defect, 11818, R1.1, Added caveat" .PP This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" ...\".SH "EXIT VALUES" ...\".VL 8m ...\".LI "Invalid Time" ...\"The command failed due to an out-of-range interval ...\"formed by the specified time and inaccuracy. The specified (new) interval ...\"must be contained in the current interval. ...\".LI "Wrong State" ...\"The command failed because the DTS ...\"entity is in the \*Loff\*O or \*Lsynchronizing\*O state. ...\".LE .SH "EXAMPLES" .PP The following example shows how to update the time for a server; the clock is gradually adjusted to the specified time: .iS \*Cdtscp>\*O \*Lupdate time 1993-12-30-11:24:00.000-05:00I0.000\*O .iE ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Oct 25, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "dtscp" 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Ldtscp\*O commands" "syntax" .iX "-[" "DTS control program" "invoking" .SH NAME .PP \*Ldtscp\*O - DTS control program .SH "SYNOPSIS" .PP .zA "defect,6211,R1.0.3,remove full pathname" .sS \*Ldtscp\*O .sE .zZ "defect,6211,R1.0.3,remove full pathname" .zA "defect, 11818, R1.1, Added caveat" .SH "NOTES" With the exception of the following subcommands, this command is replaced at Revision 1.1 by the \*Ldcecp\*O command. This command may be fully replaced by the \*Ldcecp\*O command in a future release of DCE, and may no longer be supported at that time. .P .ML .LI \*Lexit\*O .LI \*Lhelp\*O .LI \*Lquit\*O .LE .zZ "defect, 11818, R1.1, Added caveat" .SH "DESCRIPTION" .zA "defect,7991,R1.0.3,added information" .PP This section describes the commands for the DCE Distributed Time Service (DTS) control program (\*Ldtscp\*O). The DTS control program is a command-line interface that enables you to synchronize, adjust, and maintain the system clocks in a distributed network. For a detailed explanation of system clock synchronization and management, see the \*EOSF DCE Administration Guide\*O. .PP The DTS control program commands are .ML .LI The \*Ladvertise\*O command, which configures the DTS server as a global server .LI The \*Lchange\*O command, which modifies the epoch and sets the local time to a new time .LI The \*Lcreate\*O command, which establishes a DTS entity (a clerk or server) .LI The \*Ldelete\*O command, which causes DTS to exit on the local node .LI The \*Ldisable\*O command, which suspends a DTS entity .LI The \*Lenable\*O command, which starts a DTS entity .LI The \*Lexit\*O command, which ends the \*Ldtscp\*O management session and returns you to the system prompt .LI The \*Lhelp\*O command which invokes the \*Ldtscp\*O help service. .LI The \*Lquit\*O command, which ends the \*Ldtscp\*O management session and returns you to the system prompt .LI The \*Lset\*O command, which modifies characteristics of a DTS entity .LI The \*Lshow\*O command, which displays characteristics of a DTS entity .LI The \*Lsynchronize\*O command, which synchronizes the system clock with the time obtained from DTS servers in the network .LI The \*Lunadvertise\*O command, which removes the global server entry .LI The \*Lupdate\*O command, which gradually adjusts the system clock to a new time .LE .PP For more information on any of the above \*Ldtscp\*O commands, see the appropriate reference page in this chapter. .PP You can use control program commands from within the control program or from the system prompt. To enter DTS commands from within the control program, first start the control program by entering the \*Ldtscp\*O command. For example: .iS \*C$ \*Ldtscp \*O \*Cdtscp> \*O .iE At this prompt you can enter any control program command; for example: .iS \*Cdtscp> \*Lshow current time\*O .iE .P To leave the control program and return to the system prompt, enter the \*Lexit\*O command. .PP To enter DTS commands from the system prompt (interactively or in a command procedure) enter the \*Ldtscp\*O command with an internal command of the control program as the first argument. The control program executes the command without displaying the control program prompt. For example, you can enter the \*Lsynchronize\*O command as follows: .iS \*C$ \*Ldtscp synchronize\*O .iE .PP Some \*Ldtscp\*O commands have optional arguments or attributes; there may also be optional variables for the arguments and attributes. .PP See the following sample command: .iS \*Cdtscp>\*O \*Lupdate time 1990-08-03-05:45:28.000+01:00I00.500\*O / / / Command [Argument] Variable -------- [Attribute] .iE .SS "Abbreviations" .PP You can enter as few as three characters for each DTS command or argument; DTS commands and arguments are unique for three characters or more. For example, rather than entering the command \*Lenable set clock true\*O, you can enter the following abbreviated command: .iS \*Cdtscp>\*O \*Lena set clo tru\*O .iE .SS "Attributes" .PP The \*Ldtscp\*O \*Lset\*O and \*Lshow\*O commands have several attributes\(empieces or sets of data associated with them. The attribute groups are categorized as follows: .PP .VL .LI "\*LCharacteristics\*O" Set or show the entity's operation. .LI "\*LCounters\*O" Show the number of occurrences of an event since the entity was enabled. .LI "\*LStatus\*O" Show the current state of the entity. (The DTS entity has four status attributes.) .LI "\*LGlobal Servers\*O" Show the global servers known by this DTS entity. .LI "\*LLocal Servers\*O" Show the local servers known by this DTS entity. .LE .PP Individual attributes within each of the previously listed groups are described in the reference pages for the \*Lset\*O and \*Lshow\*O commands. The \*Lshow\*O command also allows you to specify attribute groups. .SS Time Stamps .iX "-[" "timestamps" "format" .PP All responses to commands contain a timestamp. The following example shows a typical DTS time display: .oS 1993-03-16-14:29:47.52000-05:00I000.003 .oE .PP The timestamp uses the DTS format that is explained in ...\" the chapter on DTS concepts. Chapter 15 of the \*EOSF DCE Administration Guide\(emCore Components\*O. In this example, the year is 1993, the day is March 16, and the time is 14 hours, 29 minutes, and 47.52 seconds. A negative Time Differential Factor (TDF) of 5 hours and an inaccuracy of 3 milliseconds are included in the timestamp. .nS note An inaccuracy value of \*CI-----\*O indicates an infinite inaccuracy. This value appears in time displays before a node's initial synchronization or after you enter the \*Lchange\*O command without specifying an inaccuracy value. .nE .iX "-]" "timestamps" "format" .SH "RELATED INFORMATION" Commands: \*Ladvertise\*O, \*Lchange\*O, \*Lcreate\*O, \*Ldelete\*O, \*Ldisable\*O, \*Lenable\*O, \*Lexit\*O, \*Lhelp\*O, \*Lset\*O, \*Lshow\*O, \*Lsynchronize\*O, \*Lquit\*O, \*Lunadvertise\*O, \*Lupdate\*O .PP Books: \*EOSF DCE Administration Guide\*O .iX "-]" "\*Ldtscp\*O commands" "syntax" .iX "-]" "DTS control program" "invoking" .zZ "defect,7991,R1.0.3,added information" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" ...\"********************************************************************* ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" ...\" .nr H1 1 .wH "" ...\" .rm zA .rm zZ .TH "dtsd"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Ldtsd\*O process" "restarting" .iX "-[" "\*Ldtsd\*O command" .SH NAME .PP \*Ldtsd\*O - Restarts the DTS daemon .wH "" .zA "enhancement,11382,R1.1,command arguments" .SH "SYNOPSIS" .PP .sS \*Ldtsd\*O [\*Loptions\*O] [\*L-d\*O] [\*L-w \*Vserviceability\*O] \*Ldtsd\*O [\*L-s\*O [\*L-k courier\*O|\*Lnoncourier\*O] [\*L-g\*O] [\*L-o\*O]] \*Ldtsd -c\*O .sE .wH "" .SH "ARGUMENTS" .VL .LI "\*L-d\*O" Debug mode. The command will run in the foreground. .LI "\*L-w \*Vserviceability\*O" See \*Lsvcroute(5)\*O for the full description of the appropriate format for this entry. Only the three-field format, \*Vseverity\*L:\*Vhow\*L:\*Vwhere\*O, is used. An example is: .iS FATAL:TEXTFILE:/dev/console .iE .LI "\*L-s\*O" Run as a server. Default is backup, courier, local server .LI "\*L-g\*O" Run \*Ldtsd\*O as a global server. .LI "\*L-k courier\*O" Run \*Ldtsd\*O as a courier. .LI "\*L-k noncourier\*O" Run \*Ldtsd\*O as a noncourier. .LI "\*L-o\*O" When enabling as a server, set the clock immediately. Equivalent to the command \*Lenable set clock true\*O in \*Ldtscp\*O or to the command \*Ldcecp dts activate -abruptly\*O. .LI "\*L-c\*O" Run \*Ldtsd\*O as a clerk. .LE .SH "DESCRIPTION" .PP .zA "defect,11382,R1.1,other engineering suggestions" The \*Ldtsd\*O command invokes the DTS daemon (clerk or server process). This command is usually executed as part of the overall DCE startup script, \*Lrc.dce\*O. .PP .zA "defect,7991,R1.0.3,improved wording/formatting" You can enter the command manually under the following conditions: .ML .LI If a DTS daemon fails to start automatically upon reboot .LI If you want to restart a daemon that you shut down to perform a backup or do diagnostic work .LE .zZ "defect,7991,R1.0.3,improved wording/formatting" .PP In normal rebooting, the \*Lrc.dce\*O script automatically provides arguments appropriate to the choice of configuration options. .PP The command line arguments shown here can also be provided to \*Ldced\*O as part of the fixed configuration strings, if \*Ldced\*O is configured to automatically start the \*Ldtsd\*O. .PP If \*Ldtsd\*O is started with no arguments (other than \*L-d\*O and \*L-w\*O), then the server must be started with \*Ldcecp\*O. The following example configures a local server: .iS \*Cdcecp> \*Ldts configure -notglobal \*Cdcecp> \*Ldts activate .iE .zZ "enhancement,11382,R1.1,command arguments" .SS "Privilege Required" .PP DTS runs as the host machine principal, which is usually \*Lroot\*O. See the Security reference pages for information about principals. .SH "NOTES" .PP Use \*Ldtsd\*O interactively only when troubleshooting; use the \*Lrc.dce\*O script to start the DTS daemon. On some systsems the superuser is associated with the machine principal. .wH "" .SH "EXAMPLES" .PP To restart the daemon, follow these steps: .AL .LI Log in to the system as superuser (\*Lroot\*O). .LI .zA "def,10220,R1.1,Remove reference to rpcd and sec_clientd" Use the \*Lps\*O command to make sure that \*Ldced\*O and \*Lcdsadv\*O are running. (The DCE daemon provides the endpoint mapping and security services, and \*Lcdsadv\*O provides CDS.) .zZ "def,10220,R1.1,Remove reference to rpcd and sec_clientd" ...\".LI ...\"Enter the following command to see if the \*Ldtsadv\*O process is already ...\"running: ...\".PP ...\".iS ...\"\*C$ \*Lps ...\".iE ...\".PP ...\"If the \*Ldtsadv\*O process appears on the list of active processes, ...\"proceed to step 5. ...\"If the \*Ldtsadv\*O process does not appear on the list of active processes, ...\"enter the following command to start the process: ...\".PP ...\".iS ...\"\*C$ \*Ldtsadv ...\".iE .LI Enter the following command to restart the \*Ldts\*O daemon as a clerk: .iS \*C$ \*Ldtsd -c .iE .zZ "enhancement,11382,R1.1,command arguments" .LE .PP To restart the \*Ldts\*O daemon as a server, use .iS dtsd -s .iE and to restart it as a global server, setting the clock on startup, use .iS dtsd -s -g -o .iE .zZ "defect,11382,R1.1,other engineering suggestions" ...\".PP ...\"When the server process starts, it starts all ...\"clearinghouses on the system. ...\".wH "" .SH "RELATED INFORMATION" Commands: \*Ldtscp (1m)\*O, \*Ldtsdate (1m)\*O, \*Ldcecp (1m)\*O. .PP Books: \*VOSF DCE Administration Guide\*O .wH "" .wH "" .iX "-]" "\*Ldtsd\*O process" "restarting" .iX "-]" "\*Ldtsd\*O command" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH dtsdate 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldtsdate\*O command" .SH NAME .PP \*Ldtsdate\*O - Sets local clock from a remote dtsd server host .SH "SYNOPSIS" .PP .sS \*Ldtsdate\*O [\*L-q\*O] [\*L-s\*O] [\*L-u\*O] \*Vremote_host\*O [\*Vnsecs\*O] .sE .SH "ARGUMENTS" .PP .VL .LI "\*L-q\*O" Queries the difference in time between the local host and the remote host, but does not change the local clock. The returned result (2 if the time would have been reset, 1 if there was an error, and 0 otherwise) can be used by a script to determine what action to take. .LI "\*L-s\*O" Causes \*Ldtsdate\*O to work silently, without showing the time. .LI "\*L-u\*O" Shows the time in UTC, rather than in the current time zone. .LI \*Vremote_host\*O The name or the IP address of a remote host that has a \*Ldtsd\*O server. .LI \*Vnsecs\*O An integer giving the number of seconds by which the remote and local host times can differ, without the local host's clock being reset. If \*Vnsecs\*O is 0, or if it is not specified, it is treated as if it were extremely large, and no resetting occurs. .LE .SH "DESCRIPTION" .PP The \*Ldtsdate\*O command sets the local clock of a system to be the same as the host \*Vremote_host\*O, running a \*Ldtsd\*O server. The purpose of \*Ldtsdate\*O is to ensure that clock skew is minimized at initial cell configuration or at host instantiation, because it is difficult to start DCE and its components if the skew is too great. .PP Clocks among all DCE components must be within five minutes of each other, to prevent failure of CDS and of security. Some DCE components have even more stringent requirements. For instance, a DFS file server cannot start if its local host differs from other DFS hosts by more than ten seconds. .PP The \*Ldtsdate\*O command can be used for adjusting a clock backwards, before DCE is running on a host. Adjusting a clock backwards while DCE is running can cause many difficulties, because security and file system software generally require system time to increase monotonically. .SH "NOTES" .PP The remote host must be running as a DTS server. This means that the \*Ldtsd\*O on that system must have registered the DTS management interface, because \*Ldtsdate\*O uses the management call to get the current time from that host. .PP For \*Ldtsdate\*O to be able to set the clock, it must run as a privileged user (\*Lroot\*O). .SH "EXIT VALUE" .PP If the \*L-q\*O argument is given, \*Ldtsdate\*O returns 2 if the remote time and local time differ by more than \*Vnsecs\*O, 1 if there was an error, and 0 otherwise. .PP If the \*L-q\*O argument is not given, \*Ldtsdate\*O returns 1 if there was an error, and 0 otherwise. .SH "EXAMPLES" .PP With only the host argument: .iS dtsdate remotehost .iE .PP \*Ldtsdate\*O prints out the time on the remote host. .PP In this example: .iS dtsdate -s -q remotehost 10 .iE .PP \*Ldtsdate\*O does not print out the remote host's time. If the times differ by more than 10 seconds, it returns the value of 1, otherwise 0. .PP In the next example: .iS dtsdate -s remotehost 10 .iE \*Ldtsdate\*O sets the clock if it differed from the remote clock by more than 10 seconds. It does this work silently, because of the \*L-s\*O option. .PP The following example shows a shell script that uses the return value of \*Ldtsdate\*O: .oS dtsdate -s -q remhost 10 result = $? if [ $result -eq 0 ] ; then echo "Time is within tolerence." elif [ $result -eq 1 ] ; then echo "Could not contact remote host." >&2 else # result = 2 if dtsdate remhost 10; then # it failed! echo "Could not set the clock." >&2 fi fi .oE .SH "RELATED INFORMATION" .PP Commands: \*Ldtsd (1m)\*O .\" $Header: dump.1m,v 78.1 96/01/22 22:20:48 ssa Exp $ .TA d .TH dump 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dump, rdump \- incremental file system dump, local or across network .SH SYNOPSIS .C /usr/sbin/dump .RI [ \|option \ [ \|argument \ ...] .IR filesystem ] .PP .C /usr/sbin/rdump .RI [ \|option \ [ \|argument \ ...] .IR filesystem ] .SH DESCRIPTION The .CR dump and .CR rdump commands copy to magnetic tape all files in the .I filesystem that have been changed after a certain date. This information is derived from the files .CR /var/adm/dumpdates and .CR /etc/fstab . .I option specifies the date and other options about the dump. .I option consists of characters from the set .CR 0123456789bdfnsuWw . The .CR dump and .CR rdump commands work only on file systems of type .CR hfs . If the given file system is not of type .CR hfs , .CR dump and .CR rdump will abort after printing an error message. .SS Options .RS .TP 10 .CR 0 - 9 This number is the "dump level". All files modified since the last date stored in file .CR /var/adm/dumpdates for the same file system at lesser levels will be dumped. If no date is determined by the level, the beginning of time is assumed. Thus, the option .CR 0 causes the entire file system to be dumped. .TP .C b The blocking factor is taken from the next argument (default is 10 if not specified). Block size is defined as the logical record size times the blocking factor. .CR dump writes logical records of 1024 bytes. When dumping to tapes with densities of 6250 BPI or greater without using the .CR b option, the default blocking factor is 32. .TP .C d The density of the tape (expressed in BPIs) is taken from the next .IR argument . This is used in calculating the amount of tape used per reel. The default value of 1600 assumes a reel tape. .TP .C f Place the dump on the next .I argument file instead of the tape. If the name of the file is .CR - , .CR dump writes to the standard output. When using .CR rdump , this option should be specified, and the next argument supplied should be of the form .IC machine : device\f1. .TP .C n Whenever .CR dump and .CR rdump require operator attention, notify all users in group .CR operator by means similar to that described by .IR wall (1). .TP .C s The size of the dump tape is specified in feet. The number of feet is taken from the next .IR argument . When the specified size is reached, .CR dump and .CR rdump wait for reels to be changed. The default tape size value of 2300 feet assumes a reel tape. .TP .C u If the dump completes successfully, write on file .CR /var/adm/dumpdates the date when the dump started. This file records a separate date for each file system and each dump level. The format of .CR /var/adm/dumpdates is user-readable and consists of one free-format record per line: file system name, increment level, and dump date in .IR ctime (3C) format. The file .CR /var/adm/dumpdates can be edited to change any of the fields if necessary. .TP .C W For each file system in .CR /var/adm/dumpdates , print the most recent dump date and level, indicating which file systems should be dumped. If the .CR W option is set, all other options are ignored and .CR dump exits immediately. .TP .C w Operates like .CR W , but prints only file systems that need to be dumped. .RE .PP If no arguments are given, .I option is assumed to be .C 9u and a default file system is dumped to the default tape. .PP Sizes are based on 1600-BPI blocked tape; the raw magnetic tape device must be used to approach these densities. Up to 32 read errors on the file system are ignored. Each reel requires a new process; thus parent processes for reels already written remain until the entire tape is written. .PP The .CR rdump command creates a server, .CR /usr/sbin/rmt or .CR /etc/rmt , on the remote machine to access the tape device. .ift .bp .PP .CR dump and .CR rdump require operator intervention for any of the following conditions: .RS .TP 3 \(bu end of tape, .PD 0 .TP \(bu end of dump, .TP \(bu tape-write error, .TP \(bu tape-open error, or .TP \(bu disk-read error (if errors exceed threshold of 32). .RE .PD .PP In addition to alerting all operators implied by the .CR n option, .CR dump and .CR rdump interact with the control terminal operator by posing questions requiring .CR yes or .CR no answers when it can no longer proceed or if something is grossly wrong. .PP Since making a full dump involves considerable time and effort, .CR dump and .CR rdump each establish a checkpoint at the start of each tape volume. If, for any reason, writing that volume fails, .CR dump and .CR rdump will, with operator permission, restart from the checkpoint after the old tape has been rewound and removed and a new tape has been mounted. .PP .CR dump and .CR rdump periodically report information to the operator, including typically low estimates of the number of blocks to write, the number of tapes it will require, the time needed for completion, and the time remaining until tape change. The output is verbose to inform other users that the terminal controlling .CR dump and .CR rdump is busy and will be for some time. .SS Access Control Lists (ACLs) The optional entries of a file's access control list (ACL) are not backed up with .CR dump and .CR rdump . Instead, the file's permission bits are backed up and any information contained in its optional ACL entries is lost (see .IR acl (5)). .SH EXAMPLES In the following example, assume that the file system .CR /mnt is to be attached to the file tree at the root directory, .RC ( / ). This example causes the entire file system .RC ( /mnt ) to be dumped on .\" .CR /dev/rmt/0h .CR /dev/rmt/c0t0d0BEST and specifies that the density of the tape is 6250 BPI. .IP .\" .C /usr/sbin/dump 0df 6250 /dev/rmt/0h /mnt .C /usr/sbin/dump 0df 6250 /dev/rmt/c0t0d0BEST /mnt .\" .SH DIAGNOSTICS .\" Many, and verbose. .SH WARNINGS .CR dump will not backup a file system containing large files. .PP Tapes created from file systems containing files with UID/GIDs greater than 60,000 will have a new magic number in the header to prevent older versions of .IR restore (1M) from incorrectly restoring ownerships for these files. .SH AUTHOR .CR dump and .CR rdump were developed by the University of California, Berkeley. .SH FILES .PD 0 .TP 32 .C /dev/rdsk/c0d0s0 Default file system to dump from. .TP .C /dev/rmt/0m Default tape unit to dump to. .TP .C /var/adm/dumpdates New format-dump-date record. .TP .C /etc/fstab Dump table: file systems and frequency. .TP .C /etc/group Used to find group .CR operator . .PD .SH SEE ALSO restore(1M), rmt(1M), fstab(4), acl(5). .\" .\" index@\f4dump\f1 \- incremental file system dump (for backups)@@@\f3dump(1M)\f1 .\" index@\f4rdump\f1 \- incremental file system dump (for backups)@@@\f3dump(1M)\f1 .\" index@\f1incremental file system dump (for backups)@@@\f3dump(1M)\f1 .\" index@\f1backup, incremental file system dump@@@\f3dump(1M)\f1 .\" index@\f1backup, incremental file system dump over network@@@\f3dump(1M)\f1 .\" index@\f1remote incremental file system dump (for backups)@@@\f3dump(1M)\f1 .\" index@\f1remote backup over network@@@\f3dump(1M)\f1 .\" index@\f1network, remote backup over@@@\f3dump(1M)\f1 .\" index@\f1file system, incremental dump (for backups)@@@\f3dump(1M)\f1 .\" .\" toc@\f3dump(1M)\f1:\0\0\f4dump\f1, \f4rdump\f1@@@incremental file system dump\f1 .\" toc@\f4rdump\f1:\0\0incremental file system dump across network@@@\f1see \f3dump(1M)\f1 .\" .\" links@dump.1m rdump.1m ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "dump clerk cache" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lcdscp\*O commands" "\*Ldump clerk cache\*O" .iX "CDS clerks" "viewing cache contents" .iX "cache" "viewing contents" .SH NAME .PP \*Ldump clerk cache\*O - Displays the contents of the clerk cache .wH "" .SH "SYNOPSIS" .PP \*Lcdscp dump clerk cache\*O .wH "" .SH "DESCRIPTION" .PP The \*Ldump clerk cache\*O command displays the contents of the clerk cache on the screen. Use this command when solving CDS problems. .SS "Privilege Required" You must have superuser (root) privileges on the clerk system. No CDS permissions are required. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command displays the contents of the clerk cache on the screen: .zA "defect,6203,R1.0.2, fixed example" .iS \*Ccdscp> \*Ldump clerk cache\*O .iE .zZ "defect,6203,R1.0.2, fixed example" .wH "" .wH "" .SH "RELATED INFORMATION" .PP Command: \*Lshow clerk\*O .wH "" .wH "" .\" $Header: dumpfs.1m,v 72.4 94/11/28 08:38:55 ssa Exp $ .TA d .TH dumpfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dumpfs \- dump file system information .SH SYNOPSIS .CI "/usr/sbin/dumpfs " rootdir \| | \| special .SH DESCRIPTION The .C dumpfs command prints the super block and cylinder group information for an HFS file system to the standard output. The file system may be specified by its root directory or the name of the device special file on which it resides. The information is very long and detailed. This command can be used to find file system information such as the file system block size or the minimum free space percentage. .SH DEPENDENCIES The .C dumpfs command can only be used on HFS file systems. .SH AUTHOR .C dumpfs was developed by the University of California, Berkeley. .SH SEE ALSO fsck(1M), mkfs(1M), newfs(1M), tunefs(1M), disktab(4), fs(4). .\" .\" index@\f4dumpfs\f1 \- dump file system information@@@\f3dumpfs(1M)\f1 .\" index@dump file system information@@@\f3dumpfs(1M)\f1 .\" index@file system information, dump@@@\f3dumpfs(1M)\f1 .\" index@free space percentage, dump file system@@@\f3dumpfs(1M)\f1 .\" index@block size, dump file system@@@\f3dumpfs(1M)\f1 .\" .\" toc@\f3dumpfs(1M)\f1:\0\0\f4dumpfs\f1@@@dump file system information .\" .\" fileset_database@dumpfs.1m SYS-ADMIN-MAN .\" .\" links@dumpfs.1m dumpfs_hfs.1m .\" $Header: dumpfs.1m,v 72.4 94/11/28 08:38:55 ssa Exp $ .TA d .TH dumpfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dumpfs \- dump file system information .SH SYNOPSIS .CI "/usr/sbin/dumpfs " rootdir \| | \| special .SH DESCRIPTION The .C dumpfs command prints the super block and cylinder group information for an HFS file system to the standard output. The file system may be specified by its root directory or the name of the device special file on which it resides. The information is very long and detailed. This command can be used to find file system information such as the file system block size or the minimum free space percentage. .SH DEPENDENCIES The .C dumpfs command can only be used on HFS file systems. .SH AUTHOR .C dumpfs was developed by the University of California, Berkeley. .SH SEE ALSO fsck(1M), mkfs(1M), newfs(1M), tunefs(1M), disktab(4), fs(4). .\" .\" index@\f4dumpfs\f1 \- dump file system information@@@\f3dumpfs(1M)\f1 .\" index@dump file system information@@@\f3dumpfs(1M)\f1 .\" index@file system information, dump@@@\f3dumpfs(1M)\f1 .\" index@free space percentage, dump file system@@@\f3dumpfs(1M)\f1 .\" index@block size, dump file system@@@\f3dumpfs(1M)\f1 .\" .\" toc@\f3dumpfs(1M)\f1:\0\0\f4dumpfs\f1@@@dump file system information .\" .\" fileset_database@dumpfs.1m SYS-ADMIN-MAN .\" .\" links@dumpfs.1m dumpfs_hfs.1m .\" $Header: edquota.1m,v 78.1 96/02/12 13:41:11 ssa Exp $ .TA e .TH edquota 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME edquota \- edit user disk quotas .SH SYNOPSIS .CR /usr/sbin/edquota .RC \|[ -p .IR proto-user ]\| .IR username \|...\& .PP .C /usr/sbin/edquota -t .SH DESCRIPTION The .CR edquota command is the quota editor. One or more user names can be specified on the command line. For each .IR username , a temporary file is created with a textual representation of the current disk quotas for that user, and an editor is invoked on the file. The quotas can then be modified, new quotas added, etc. Upon leaving the editor, .CR edquota reads the temporary file and modifies the binary quota files to reflect the changes made. .PP The editor invoked is specified by the .CR EDITOR environment variable. It defaults to .CR vi (see .IR vi (1)). .PP In order for quotas to be established on a file system, the root directory of the file system must contain a file named .CR quotas . See .IR quota (5) for details. .PP Quotas can be established only for users whose user ID is less than 67,000,000. Attempts to establish quotas for other users will result in an error message. This restriction will be removed in a future version of .SM HP-UX. .PP Only users who have appropriate privileges can edit quotas. .SS Options .TP 15 .CI -p \0proto_user Duplicate the quotas of the user name .I proto_user for each .IR username . This is the normal mechanism used to initialize quotas for groups of users. .TP .CR -t Edit the time limits for each file system. Time limits are set for file systems, not users. When a user exceeds the .IR soft limit for blocks or inodes on a file system, a countdown timer is started and the user has an amount of time equal to the time limit in which to reduce usage to below the soft limit (the required action is given by the .CR quota command). If the time limit expires before corrective action is taken, the quota system enforces policy as if the .IR hard limit had been exceeded. The default time limit of 0 is interpreted to mean the value in .CR , or one week (7 days). Time units of sec(onds), min(utes), hour(s), day(s), week(s), and month(s) are understood. Time limits are printed in the greatest possible time unit such that the value is greater than or equal to one. .SS Temporary File Formats Here is an example of the temporary file created for editing user block and inode quotas: .nf .IP .SM .C "fs /mnt blocks (soft = 100, hard = 120) inodes (soft = 0, hard = 0)" .SM .C "fs / blocks (soft = 1000, hard = 1200) inodes (soft = 200, hard = 200)" .fi .PP Here is the format for editing quota time limits: .nf .IP .SM .C "fs /mnt blocks time limit = 10.00 days, files time limit = 20.00 days" .SM .C "fs / blocks time limit = 0 (default), files time limit = 0 (default)" .fi .PP When editing .CR (default) values, it is not necessary to remove the .CR (default) string. For example, to change the .CR "blocks time limit" for .CR / , changing the .CR 0 to .CR "4 days" is sufficient. .SH WARNINGS When establishing quotas for a user who has had none before, (for either blocks or inodes), the quota statistics for that user do not include any currently occupied file system resources. Therefore, it is necessary to run .CR quotacheck (see .IR quotacheck (1M)) to collect statistics for that user's current usage of that file system. See .IR quota (5) for a detailed discussion of this topic. .PP .CR edquota will only edit quotas on local file systems. .SH AUTHOR .CR edquota was developed by the University of California, Berkeley, and by Sun Microsystems, Inc. .SH FILES .PD 0 .TP 25 .CR /etc/fstab Static information about the file systems. .TP .CR /etc/mnttab Mounted file system table .TP .IC directory /quotas Quota statistics static storage for a file system, where .I directory is the root of the file system as specified to the .CR mount command (see .IR mount (1M)). .PD .SH SEE ALSO vi(1), quota(1), quotacheck(1M), quotacheck_hfs(1M), quota(5). .\" .\" index@\f4edquota\f1 \- edit user quotas@@@\f3edquota(1M)\f1 .\" index@edit user quotas@@@\f3edquota(1M)\f1 .\" index@user quotas, edit@@@\f3edquota(1M)\f1 .\" index@quotas, edit user@@@\f3edquota(1M)\f1 .\" .\" toc@\f3edquota(1M)\f1:\0\0\f4edquota\f1@@@edit user quotas .\" .\" $Header: eisa_config.1m,v 72.5 94/03/16 18:50:54 ssa Exp $ .TA e .TH eisa_config 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME eisa_config \- \s-1EISA\s0 configuration tool .SH SYNOPSIS .C eisa_config .PP .C eisa_config .RC [ -a ] .PP .C eisa_config .RC [ -c .IR cfgfile\| ] .PP .C eisa_config .RC [ -n .IR scifile\| ] .SH DESCRIPTION .C eisa_config is a specialized program for configuring .SM EISA and .SM ISA (referred to collectively as E/ISA) .SM I/O boards on .SM HP-UX workstations equipped with .SM EISA backplanes. It is used each time the .SM E/ISA configuration is to be changed in any way; i.e., whenever an .SM EISA or .SM ISA board is added to the system, removed from the system, or moved to a different location in the system. .C eisa_config should be run before any physical board configuration or installation changes are made. (This is not necessary in some cases -- see automatic mode below.) .PP .C eisa_config interprets information stored in configuration files and uses it to configure system resources needed to properly interact with .SM E/ISA boards. Even though they may be physically present in the computer, .SM E/ISA boards cannot be used by the .SM HP-UX operating system until configuration by .C eisa_config is complete. .PP The .C eisa_config command takes one of four forms: .RS .ift .TP 30 .ifn .TP 10 .C eisa_config Use interactive commands to examine or modify configuration. .C eisa_config prompts for a command, executes it, reports the results of command execution, then prompts for the next command. .TP .C eisa_config -a Attempt to automatically add new .SM EISA boards to the configuration. This option is used by .C /sbin/bcheckrc but should not be used elsewhere. .SM ISA boards cannot be added with this option. .TP .CI "eisa_config -c " cfgfile Check configuration .SM (CFG) file (discussed below). This option is used mostly by .SM E/ISA board developers. It simply checks the specified .SM CFG file to verify that it follows correct grammar and can be used by .CR eisa_config . This option does not affect current configuration in any way. .TP .CI "eisa_config -n " scifile Non-target mode. This option uses the contents of .I scifile instead of non-volatile memory .SM (NVM) to set up .SM E/ISA configuration, and is most commonly used for creating identical configurations on multiple workstations. .RE .SS Assigning Resources Depending on their design, internal capabilities, and their role in system operation, .SM E/ISA boards use various combinations of one or more system resources such as .SM DMA channels, interrupt lines, memory, etc. Also, given boards do not always use a full set of system resources; for example, .SM EISA provides 11 interrupt lines, but a given board might be able to use only lines 3, 5, and 6. Thus a means for the board to determine what resources are to be used must be provided. .PP .SM ISA boards use physical switches or jumpers on the board to specify what resources are to be used. The person installing the board sets the switches or jumpers as specified by the board's manufacturer and based on system needs. There are thousands of different kinds of .SM ISA boards, but unfortunately there are no standard conventions for switch and jumper usage. This results in much confusion and numerous configuration problems. For example, it is easy to inadvertently assign a given resource to two different boards, but often very difficult to diagnose the problem. .PP .SM EISA boards usually have no switches or jumpers for resource assignment. Instead, each .SM EISA board has a corresponding configuration .SM (CFG) file that tells the system how the board can be used and what resources it needs. .C eisa_config is the .SM HP-UX system program that interprets the various .SM CFG files for all boards in the system, then builds a conflict-free configuration. .SS Configuration Files All .SM EISA boards have a corresponding .SM CFG file. .SM ISA boards, when used in .SM HP-UX systems, must also have a corresponding .SM CFG file. Although .C eisa_config cannot automatically configure an .SM ISA board, it can use the contents of the .SM CFG file to determine what switch or jumper settings on an .SM ISA board can be used to prevent resource conflicts. .PP .C eisa_config expects to find a .SM CFG file for each .SM E/ISA board connected to the workstation. The administrator is responsible for making sure that these .SM CFG files are present in directory .CR /sbin/lib/eisa . .SM CFG files corresponding to boards being used should always be kept in this directory. Do not remove them after .C eisa_config is run the first time, because they will be needed every time the configuration is changed, such as when a new board is added or one is removed. Do not change the file names of the .SM CFG files. The file name has a specific format which is used by .C eisa_config to automatically match a board with its .SM CFG file. .PP .SM CFG files are normally supplied by the .SM E/ISA board manufacturer. Two scenarios apply: .RS .TP 3 \(bu If the .SM E/ISA board is supplied by HP, the .SM CFG file corresponding to the board is loaded into .C /sbin/lib/eisa as part of normal operating system installation. It should never be removed. .TP \(bu If the .SM E/ISA board is not supplied by HP, install both the .SM CFG file and the software driver for the board from .SM HP-UX\c -readable media supplied by the board manufacturer. Copy the .SM CFG file to directory .C /sbin/lib/eisa where it must remain as long as the card is present in the system. .RE .PP All .SM CFG files must follow a grammar specified in the .SM EISA bus specification. The most basic building block in the .SM CFG grammar is the .IR board . Each board has several attributes including board .SM ID (to match with a board's ID register), manufacturer, .SM ASCII text describing what the board does, what kinds of slots the board can go in, whether the board has a readable .SM ID register, and various other capability attributes. .PP Each file can also contain lists of board-wide resources (such as .SM I/O registers, switches, and jumpers) and how they should be initialized. .PP A board can be treated as a set of one or more .I functions where a given board contains a single function or multiple functions. An example of a two-function board is one having both a serial port and a parallel printer port. Each function has a separate block in that board's .SM CFG file. Each function has a name, a type, and a set of configuration .IR choices . .PP Each .I choice block has a name and a set of attributes. These attributes include what resources the choice requires and whether the function is enabled or disabled by that choice. Initialization is also usually specified within a choice. A given choice might require that certain registers be initialized to a specified value and that switches be set in a certain way. .SS Configuration Processing .SM E/ISA configuration is handled as follows: .RS .TP 3 \(bu .C eisa_config builds a conflict-free configuration, then saves the configuration in .SM EISA non-volatile memory .SM (NVM). .TP \(bu Appropriate drivers and device files must be installed before rebooting the system. .TP \(bu Next time the operating system is rebooted, the .SM HP-UX kernel initializes the specified .SM E/ISA boards according to the contents of .SM NVM. .RE .PP If a board is currently present in the system, but has no corresponding configuration data in .SM NVM, the .SM EISA board cannot be used until the .C eisa_config program is run again and the new board is accounted for in .SM NVM. A newly installed or existing .SM E/ISA board is not usable until .C eisa_config has added it and the system has been rebooted with the necessary drivers and device special files installed. See .SM EXAMPLES for an illustration of how to add a new board to the system. .PP It is possible to add .SM EISA boards that do not have switches or jumpers to the configuration without running .C eisa_config interactively. The .C /sbin/bcheckrc script invokes .C eisa_config with automatic mode during each system initialization. If a board has been added since the last time .C eisa_config was executed, .C eisa_config attempts to add the new board to the configuration. If the new board is successfully added, the system may need to be rebooted .RC ( /sbin/bcheckrc does this automatically). If the new board could not be added to the configuration, a warning is written to the system console and .CR /etc/eisa/config.err . .PP In addition to writing to .SM NVM, .C eisa_config also automatically saves the current configuration to an .SM SCI file called .CR /etc/eisa/system.sci . .SM SCI files can also be created by the interactive .C save command (see below). The .SM E/ISA subsystem can also be initialized from an .SM SCI file, rather than from .SM NVM by using the .C eisa_config -n command form discussed earlier. .SM SCI files are quite useful when a site has several identically-configured workstations. Run .C eisa_config on one system and save the configuration in an .SM SCI file. Copy this file to other systems, then use it to initialize those systems. Remember that the configuration must be saved to .SM NVM and the system rebooted before the .SM E/ISA boards can be used. .SS Drivers and Device Files Running .C eisa_config is not the only task necessary when adding an .SM E/ISA board to a system. Corresponding .SM I/O drivers must be added to the kernel and appropriate device files must be created. These steps are the same as is required for any .SM I/O card, and can be performed either before or after running .CR eisa_config . The important thing to remember is that the .SM E/ISA board cannot be used until .I all necessary tasks are complete. .SS Interactive Commands If the command form .C eisa_config is used, .C eisa_config runs in interactive mode. Interactive mode conducts configuration changes by using a series of keyboard commands. .C eisa_config prompts for a command, executes it, displays the results of executing the command, then prompts for the next command. Interactive commands are broadly grouped into five categories: .RS .TP 12 .I action Alter the configuration in some way. .TP .I display Show current configuration. .TP .I cfg Manage .SM CFG files. .TP .I comments Display help and comments information found in .SM CFG files. .TP .I help Help for using .C eisa_config interactive commands .RE .PP The .I action commands are: .RS .TP 20 .CI add " cfgfile slotnum" Adds a board to the current configuration. .I cfgfile specifies which .SM CFG file corresponds to the board and .I slotnum identifies the slot where the board resides. .TP .CI remove \0slotnum Remove a board from the current configuration. .I slotnum identifies the slot where the board currently resides. .TP .CI move " curslotnum newslotnum" Move a board that is currently configured in one slot to a different slot. .I curslotnum and .I newslotnum specify the current and new slot numbers, respectively. .TP .CI change " slotnum functionnum choicenum" Change the choice used for a given function. All three arguments, .IR slotnum , .IR functionnum , and .I choicenum are required. The function number .RI ( functionnum ) and choice number .RI ( choicenum ) can be obtained by using the .C show board command on the slot in question. Function numbers are of the format .CI F num and choice numbers are of the format .CI CH num\f1. Note that a board must already be part of the configuration before the change command can be used. .IP When .C eisa_config adds a board, it selects a choice for each function. Generally, the first choice for each function is selected (the default). However, in order to resolve conflicts, .C eisa_config may select a different choice for a given function. When specifying a choice for a particular function by use of the .C change command, .C eisa_config always uses that choice; it does not select a different one, even when a conflict needs to be resolved. .TP .CR save \0[\|\f2filename\fP\|] Save the current configuration. If the current configuration is not conflict-free, a warning is produced and the save is not done. If you specify a file name, the save is done to that file; otherwise, the save is done to .SM NVM (and the .C /etc/eisa/system.sci file). Note that the .C quit command also (optionally) saves the configuration to .SM NVM (and file .CR /etc/eisa/system.sci ). .IP When the configuration is saved to .SM NVM, a log file is created that provides a brief desription of the new configuration. The log file is named .CR /etc/eisa/config.log , and contains information generated by a .C show command, followed by a .C show board command, followed by a .C show switch command. .TP .CR init \0[\|\f2filename\fP\|] Initialize the configuration. The initial configuration is retrieved from a file if one has been specified. Otherwise, it is retrieved from .SM NVM. Note that an implicit .C init is done when .C eisa_config is first started. This command should only be used when the current configuration .C eisa_config is dealing with is incorrect. For example, if you make some changes that you decide you do not want, you can use this command to start over. .TP .C quit Leave .CR eisa_config . If the configuration is conflict-free and has been changed, you are asked if you want to save the configuration (to .SM NVM\s0). If any switches or jumpers have to be changed as a result of this new configuration, you are notified of these changes prior to saving the configuration. Be sure that all switches and jumpers match what .C eisa_config has specified before booting the system. .IP When the configuration is saved to .SM NVM, a log file is created that provides a brief desription of the new configuration. The log file is named .CR /etc/eisa/config.log , and contains information generated by a .C show command, followed by a .C show board command, followed by a .C show switch command. .RE .PP The .I show (display) commands are: .RS .TP 20 .C show List all slots and their current status; i.e., whether occupied by a particular board, or empty. .TP .CI "show slots " cfgfile List all of the slots that could accept the board corresponding to the .SM CFG file .IR cfgfile . .TP .CR "show board" \0[\|\f2cfgfile\fP\|\(or\|\f2slotnum\fP\|] List the basic attributes for the selected board or boards. Includes a list of all the functions on the board and a list of all available choices for each function. If the board is currently part of the configuration, the currently selected choice is marked. The default choice is the first choice listed for each function. If a board is not specified (either by .SM CFG file name or slot number), information is displayed for each of board installed and configured in the system. .TP .C "show switch " [ \|changed\| ]\0[\|\f2slotnum\fP\|] List the switch and jumper settings (both default and required) for the boards in the configuration. If the keyword .C changed is used, only those switches and jumpers that were changed from the previous configuration are displayed. If a slot number is specified, only switches and jumpers on the board in that slot are displayed. Note that .C show switch supports all combinations of .C changed and .IR slotnum . .RE .PP There are two kinds of .I cfg commands: .RS .TP 20 .C cfgtypes List the types of boards that have .SM CFG files in directory .C /sbin/lib/eisa and how many .SM CFG files in .C /sbin/lib/eisa are of each type. .TP .CR cfgfiles \0[\|\f2type\fP\|] List all .SM CFG files that are currently available for use in the .C /sbin/lib/eisa directory. If a specific board .I type is specified, only .SM CFG files of that type are displayed. .RE .PP .I comment commands extract the help and comments text provided in the specified .SM CFG file or files. Both help and comments are displayed if they are available. Each command form accepts as an argument either a .SM CFG file or a slot number identifying which board you want help for. .RS .TP 20 .CR "comment board" \0[\|\f2cfgfile\fP\|\(or\|\f2slotnum\fP\|] Display board-level help and comments. .TP .CR "comment function" \0[\|\f2cfgfile\fP\|\(or\|\f2slotnum\fP\|] Display function-level help and comments. .TP .CR "comment choice" \0[\|\f2cfgfile\fP\|\(or\|\f2slotnum\fP\|] Display choice-level help. .TP .CR "comment switch" \0[\|\f2cfgfile\fP\(or\|\f2slotnum\fP\|] Display help and comments for switches and/or jumpers as appropriate. .RE .IP Note that all arguments (except the type of comments requested) are optional. If no optional argument is specified, all available comments for the specified file or board are extracted. For example: .RS .TP 20 .C comment board 1 Display help and comments available for the board currently configured in slot 1. .TP .C comment board Display help and comments available for .I all currently configured boards. .RE .PP The .I help commands explain how to use the .C eisa_config interactive commands. If no other arguments are given, help is displayed for all of the interactive commands. Alternatively, any valid command can be used as a argument to the help command. Help is then given for the specified command only. .RS .TP 20 .C help Display a brief explanation of all valid .C eisa_config interactive commands. .TP .CR help \0[\|\f2cmdname\fP\|] Display an explanation of the command specified. .RE .SH EXAMPLES Add a new .SM E/ISA board to the system: .RS .TP 3 1. Load the .SM CFG file (from media provided by the manufacturer) into directory .C /sbin/lib/eisa if the file is not already present. .TP 2. Run .CR eisa_config . .C eisa_config reads the contents of .SM NVM to obtain current system configuration. .TP 3. Use the interactive .C add command to add the new board. .C eisa_config reads the corresponding .SM CFG file to obtain needed configuration information. .TP 4. Exit .CR eisa_config , noting any required switch or jumper settings. .C eisa_config generates a new configuration and writes it to .SM NVM. The required switch and jumper settings are also saved in the log file .CR /etc/eisa/config.log . .TP 5. Add the correct software drivers for the board (and board devices) to the kernel, and use .IR mknod (1M) to create any needed device special files. .TP 6. Shut down and disconnect power to the system. .TP 7. Install the .SM E/ISA board after changing any switch or jumper settings required by .CR eisa_config . .TP 8. Reboot the system. When the system is running again, the contents of .SM NVM will match the .SM E/ISA boards present in the system, and the newly added board can be used immediately. .RE .PP This procedure can also be used to add multiple new boards at the same time. Simply use the .C add command once for each board and alter the other steps as appropriate. .PP If the board to be added is an .SM EISA board that does not have switches or jumpers, the board can be added via automatic mode; that is, steps 2-4 above can be skipped. .SH AUTHOR .C eisa_config was developed by HP and Compaq. .SH FILES .TP 40 .C /sbin/lib/eisa/!XXX0000.CFG .SM CFG files .TP .C /etc/eisa/config.err errors encountered in automatic mode .TP .C /etc/eisa/config.log log file containing current .SM E/ISA configuration .TP .C /etc/eisa/system.sci mirror image of configuration saved to .SM NVM .SH SEE ALSO config(1M), mknod(1M). .\" .\" index@\f4eisa_config\f1 \- \s-1EISA\s0 configuration tool@@@\f3eisa_config(1M)\f1 .\" index@\s-1EISA\s0 configuration tool@@@\f3eisa_config(1M)\f1 .\" index@\s-1ISA\s0 configuration tool@@@\f3eisa_config(1M)\f1 .\" index@configuration tool, \s-1EISA\s0@@@\f3eisa_config(1M)\f1 .\" index@tool, \s-1EISA\s0 configuration@@@\f3eisa_config(1M)\f1 .\" .\" toc@\f3eisa_config(1M)\f1:\0\0\f4eisa_config\f1@@@\s-1EISA\s0 configuration tool .\" .\" fileset_database@eisa_config.1m SYS-ADMIN-MAN ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Oct 25, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH enable 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Ldtscp\*O commands" "\*Lenable\*O" .iX "-[" "DTS servers" "starting" .iX "-[" "DTS clerks" "starting" .SH NAME .PP .zA "defect,7684,R1.0.3,change specified node to local node" \*Lenable\*O - Starts the DTS entity on the local node. .zZ "defect,7684,R1.0.3,change specified node to local node" .SH "SYNOPSIS" .PP .zA "defect,6211,R1.0.3,add control program name" .sS \*Ldtscp enable\*O [\*Lset clock\*O \*Vboolean\*O]\*O .sE .zZ "defect,6211,R1.0.3,add control program name" .SH "ARGUMENTS" .PP .VL .LI "\*Lset clock\*O \*Vboolean\*O" Specifies whether the clock is abruptly set or gradually adjusted to the computed time. This argument is optional. Valid values for boolean are .VL .LI "\*Lfalse\*O" The clock is gradually adjusted. This is the default condition. .LI "\*Ltrue\*O" The clock is abruptly set. .LE .LE .SH "DESCRIPTION" .PP .zA "defect,7837,R1.0.3,added info on relationship between create and enable" .PP After the DTS entity is created with the \*Ldtscp create\*O command, it is still in a non-functioning state. To put it into operation, you must invoke \*Ldtscp enable\*O, which causes an immediate synchronization to take place. When the command is executed, the status attribute \*Lstate\*O is set to \*Lon\*O. .PP In addition, you may use the \*Lenable\*O command to activate a DTS entity that has previously been deactivated with the \*Ldisable\*O command. See the \*Ldisable\*O reference page in this chapter for more information. .zZ "defect,7837,R1.0.3,added info on relationship between create and enable" .SS "Privilege Required" .PP You must have write permission on the ACL associated with the DTS entity in order to execute the command. .SH "NOTES" .PP The DTS entity cannot be enabled until it is created with the \*Lcreate\*O command; the DTS entity must be in the \*Loff\*O state. .zA "defect, 11818, R1.1, Added caveat" .PP This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" ...\".SH "EXIT VALUE" ...\".PP ...\".VL 8m ...\".LI "Wrong State" ...\"The command failed because the DTS ...\"entity is not in the \*Loff\*O state. ...\".LE .SH "EXAMPLES" .PP .AL .LI The following example shows how to enable the entity and adjust the clock gradually to the computed time following the first synchronization: .iS \*Cdtscp>\*O \*Lenable\*O .iE .LI The following example shows how to enable the entity and abruptly set the clock to the computed time following the first synchronization: .iS \*Cdtscp>\*O \*Lenable set clock true\*O .iE .LE .SH "RELATED INFORMATION" .PP Commands: \*Lcreate (1m)\*O, \*Ldisable (1m)\*O .iX "-]" "\*Ldtscp\*O commands" "\*Lenable\*O" .iX "-]" "DTS servers" "starting" .iX "-]" "DTS clerks" "starting" .\" $Header: envd.1m,v 72.4 94/05/18 19:03:06 ssa Exp $ .TA e .TH envd 1M "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME envd \- system physical environment daemon .SH SYNOPSIS .C /usr/sbin/envd .RC [ -f .IR configfile\| ] .SH DESCRIPTION The .C envd daemon provides a means for the system to respond to environmental conditions detected by hardware. Such responses are typically designed to maintain file system integrity and prevent data loss. The environmental condition currently recognized by .C envd is over-temperature. .PP .C envd logs messages and then executes actions when a supported environmental event is detected. Whether to do message logging and what actions to perform for a given environmental event are determined by .I configfile (default is .CR /etc/envd.conf ). If no .C -f option was specified and the default configfile .C /etc/envd.conf does not exist, .C envd fails. A recommended default .I configfile is available in .CR /usr/newconfig/etc/envd.conf . The .I configfile (or .CR /etc/envd.conf ) is only examined when the daemon is started or when it receives a .C SIGHUP signal to restart and re-initialize the daemon itself. .PP .C envd uses the .C syslog message logging facility to log warning messages. If .I configfile specifies messages to be logged, the destination of the warning messages is determined by the configuration of the .C LOG_DAEMON facility of the .C syslogd daemon (see .IR syslogd (1M) and .IR syslog (3C) for details) and various .C syslog priorities defined below for the corresponding environmental events. Warning messages are written to the console if .C envd is unable to send to .CR syslogd . .PP The .I configfile is composed of event lines, each of which followed by zero or more action lines. Comment lines can be interspersed at any point. No more than one event line can be specified for a given event. .RS .TP 15 Event Event lines consist of an event keyword and a message indicator, separated by a colon .RC ( : ). Valid event keywords are .C OVERTEMP_CRIT and .CR OVERTEMP_EMERG . Valid message indicators are .C y and .CR n . An example is .CR OVERTEMP_EMERG:y , indicating that warning messages are to be sent for the .SM OVERTEMP_EMERG event. .IP Event keywords must start in the first column, and only one event and one message indicator are allowed on a given line. .TP Action Action lines can consist of a sequence of any valid .C /usr/bin/sh commands or pipelines. Lines from one event line to the next event line, or to the end of the file, are part of the action lines for the preceding event, and are passed intact to the shell to execute upon detecting the event. The action for an event can span across several lines, but the syntax of every line must be understood by .CR /usr/bin/sh . There are no default actions for any events if no action lines are specified. .IP No parsing or syntax checking is performed on the action lines; system administrators are responsible for verifying the correctness of the action syntax. .TP Comments Lines beginning with the .C # character in the first column are comment lines, and all characters up to the subsequent new-line character are ignored. .IP Blank lines are ignored as comment lines. .RE .PP Here is an example .C /etc/envd.conf file: .nf .IP .C "# The example below configures envd to log the warning message and" .C "# to rcp critical applications to a remote machine at OVERTEMP_CRIT." .C "# It configures envd to log emergency messages and to perform" .C "# system shutdown at OVERTEMP_EMERG, in order to preserve" .C "# the data integrity." .IP .C OVERTEMP_CRIT:y .C " /usr/bin/rcp critical_appl_files \e" .C " remote_machine:/backup" .IP .C OVERTEMP_EMERG:y .C " /usr/sbin/reboot -qh" .fi .RE .PP Only users with appropriate privileges can invoke .CR envd . .SS Over-temperature Handling Over-temperature handling is supported only on systems equipped with over-temperature sensing hardware. Over-temperature limits may vary, depending on the hardware. Each system processor defines its own safest threshold for supported equipment combinations. The table below shows four levels of temperature states. For the temperature range specific to your system configuration, refer to any of the following documents for your system: .IR "Site Planning and Preparation Guide" , .IR "Installation and Configuration Guide" , or .IR "Operator Handbook" . .PP .TS center box; lB | lBw(3i) lf4 | l. State State Description _ NORMAL Within normal operating temperature range .ift .sp .5v .ifn .sp 1v OVERTEMP_CRIT T{ Temperature has exceed the normal operating range of the system, but it is still within the operating limit of the hardware media. T} .ift .sp .5v .ifn .sp 1v OVERTEMP_EMERG T{ Temperature has exceeded the maximum specified operating limit of hardware media; power loss is imminent. A minimum of about 60 seconds is guaranteed between the \s-1OVERTEMP_MID\s0 state and the \s-1OVERTEMP_POWERLOSS\s0 (power loss) state. T} .ift .sp .5v .ifn .sp 1v OVERTEMP_POWERLOSS T{ Hardware will disconnect all power from all cards in the system chassis. T} .ifn .sp 1v .TE .PP The .C syslog priorities mapped to two over-temperature events are: .C LOG\_EMERG (for .CR OVERTEMP_EMERG ) and .C LOG_CRIT (for .CR OVERTEMP_CRIT ). .PP Any non-shutdown activities (e.g. file transfer) should be performed at .CR OVERTEMP_CRIT . It is important to configure only critical activities for .C OVERTEMP_CRIT because the over-temperature might rise dramatically fast to .CR OVERTEMP_EMERG . It is recommended to perform a quick shutdown using .C /usr/sbin/reboot -qh at .C OVERTEMP_EMERG to preserve file system data integrity. If the hardware enters the .C OVERTEMP_POWERLOSS state and the system has not been shut down, the sudden loss of power could result in data loss. Note that power-fail recovery functionality is not available in this case. When the hardware powers down, no warning messages are produced, and no action is taken by the system. .PP Whenever the temperature rises from one level to another (such as from .C NORMAL to .C OVERTEMP_CRIT or from .C OVERTEMP_CRIT to .CR OVERTEMP_EMERG , the warning message, if specified, and the corresponding specified over-temperature action is executed once, and only once, per state change. .SH AUTHOR .C envd was developed by HP. .SH FILES .TP 35 .C /usr/sbin/envd .C envd executable file .PD 0 .TP .C /etc/envd.conf default .C envd configuration file .TP .C /etc/syslog.conf default .C syslog configuration file .TP .C /var/tmp/envd.action[123] .C envd work files .PD .SH SEE ALSO reboot(1M), shutdown(1M), syslogd(1M), syslog(3C). .PP .SM HP-UX System Administration manuals. .\" .\" index@\f4envd\f1 \- system physical environment daemon@@@\f3envd(1M)\f1 .\" index@system physical environment daemon@@@\f3envd(1M)\f1 .\" index@over-temperature environment, handle@@@\f3envd(1M)\f1 .\" index@temperature environment, handle over-@@@\f3envd(1M)\f1 .\" index@physical environment daemon, system@@@\f3envd(1M)\f1 .\" index@environment daemon, system physical@@@\f3envd(1M)\f1 .\" index@daemon, system physical environment@@@\f3envd(1M)\f1 .\" .\" toc@\f3envd(1M)\f1:\0\0\f4envd\f1@@@system physical environment daemon .\" .\" fileset_database@envd.1m SYS-ADMIN-MAN ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH exit 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "DTS control program" "exiting" .iX "\*Ldtscp\*O commands" "\*Lexit\*O" .SH NAME .PP \*Lexit\*O - Causes \*Ldtscp\*O to complete execution. .SH "SYNOPSIS" .PP .zA "defect,6211,R1.0.3,add control program name" .sS \*Ldtscp exit\*O .sE .zZ "defect,6211,R1.0.3,add control program name" .SH "DESCRIPTION" .PP The \*Lexit\*O command causes the DTS control program (\*Ldtscp\*O) to complete execution and returns operation to the parent process. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command may be replaced in future releases by the \*Ldcecp\*O command, and may no longer be supported at that time. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .PP The following command shows how to leave \*Ldtscp\*O and return to the parent process: .iS \*Cdtscp>\*O \*Lexit\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lquit(1m)\*O .\" $Header: exportfs.1m,v 1.1.111.1 95/01/17 18:20:32 kcs Exp $ .TA e .TH exportfs 1M .SH NAME exportfs \- export and unexport directories to NFS clients .SH SYNOPSIS .CR /usr/sbin/exportfs .RC [ \-auv ] .PP .CR /usr/sbin/exportfs .RC [ \-uv ] .RI [ dir \ ...] .PP .CR /usr/sbin/exportfs .CR \-i .RC [ \-o .IR options ] .RC [ \-v ] .RI [ dir \ ...] .SH DESCRIPTION The .CR exportfs command makes a local directory or file available to NFS clients for mounting over the network. Directories and files cannot be NFS-mounted unless they are first exported by .CR exportfs . .PP .CR exportfs is normally invoked at boot time by the .CR /sbin/init.d/nfs.server script, and uses information contained in the .CR /etc/exports file to export the file or file system named by each .IR dir , which must be specified as a full path name. .PP If no options or arguments are specified in the command line, .CR exportfs displays a list of the currently exported directories and files on standard output. #ifdef B1 .SS Security Restrictions Users who have the .CR backup subsystem authorization can run #else .PP A superuser can run #endif .CR exportfs at any time to alter the list or characteristics of exported directories and files. .SS Options .CR exportfs recognizes the following options: .RS .TP 15 .CR \-a Export all directories listed in .CR /etc/exports . If .CR \-u is also specified, unexport all of the currently exported directories. .TP .CR \-i Ignore the options in .CR /etc/exports . Normally, .CR exportfs consults .CR /etc/exports for the options associated with the exported directory. .TP .CR \-u Unexport the indicated directories. .TP .CR \-v Verbose. Print each directory or file name as it is exported or unexported. .TP .CI \-o \0options Specify a comma-separated list of optional characteristics for the directory being exported. The list of .I options can include any of the following: .RS .TP 15 .CR async All mounts will be asynchronous. Refer to .IR exports (4) for warnings when using this option. .TP .CR ro Export the directory read-only. If not specified, the directory is exported read-write. .TP .CI rw= hostname\f1[ : hostname\f1]... Export the directory "read-mostly". Read-mostly means exported read-only to most machines, but read-write to those specified. If not specified, the directory is exported read-write to all. Up to 256 .IR hostname s can be specified. .TP .CI anon= uid If a request comes from an unknown user, use .I uid as the effective user ID. .IP Root users (user ID 0) are always treated as user .CR unknown by the NFS server unless they are included in the .CR root option below. .IP If the client is a UNIX system, only root users are considered .CR unknown . All other users are recognized even if they are not in .CR /etc/passwd . .IP The default value for .I uid is the user ID of user .CR nobody . If user .CR nobody does not exist, the value -2 is used. Setting the value of .CR anon to -1 disables anonymous access. #ifdef B1 .IP This option applies only to an unlabeled host. If the client is a BLS system, an .CR unknown user will be mapped to .CR m6nobody as defined in the remote host database. #endif .TP .CI root= hostname\f1[ : hostname\f1]... Give root access only to the root users from a specified .IR hostname . The default is for no hosts to be granted root access. Up to 256 .IR hostname s can be specified. #ifdef B1 .IP This option applies only to an unlabeled host. If the client is a BLS system, all user IDs (including user ID 0) are mapped. #endif .TP .CI access= client\f1[\f1 : client\f1]... Give mount access to each .I client listed. A .I client can either be a host name, or a netgroup (see .IR netgroup (4)). .CR exportfs checks for each .I client in the list first in file .CR /etc/hosts , then in .CR /etc/netgroup . The default value allows any machine to mount the given directory. .RE .RE .SH DIAGNOSTICS If an NFS-mounted directory is unexported by .CR exportfs , any access by the client to the directory causes an .CR "NFS stale file handle" error. However, if .CR exportfs is used to remove a client from the access list of an exported directory, an .CR "NFS stale file handle" error does not result from any access by the client to the directory. .SH EXAMPLES The following invocation of .CR exportfs lists currently exported directories and files: .IP .C "exportfs" .PP Export entries in .CR /etc/exports " .IP .C "exportfs \-a" .PP Unexport all exported files and directories: .IP .C "exportfs \-ua" .PP Unexport all exported files and directories and print each directory or file name as it is unexported: .IP .C "exportfs \-uav" .PP Export .CR /usr to the world, ignoring options in .CR /etc/exports : .IP .C "exportfs \-i /usr" .PP Export .CR /usr/bin and .CR /var/adm read-only to the world: .IP .C "exportfs \-i \-o ro /usr/bin /var/adm" .PP Export .CR /usr/bin read-write only to systems .CR polk and .CR vanness : .IP .C "exportfs \-i \-o rw=polk:vanness /usr/bin" .PP Export root access on .CR /var/adm only to the system named .CR pine , and mount access to both .CR pine and .CR geary : .IP .C "exportfs \-i \-o root=pine, access=pine:geary /var/adm" .SH WARNINGS You cannot export a directory that resides within the same file system and is either a parent or sub-directory of a directory that is currently exported. For example, .CR /usr and .CR /usr/local cannot both be exported if they reside in the same disk partition. .PP If you unexport a directory, remove a client from the access list, then export again, the client still has access to the directory until the client unmounts the directory. Removing a client from the .CR root or .CR rw list takes effect immediately. .PP .CR /etc/xtab is a system file that contains a list of currently exported directories and files. This file is maintained by .CR exportfs . To ensure that this file is always synchronous with current system data structures, do not attempt to edit .CR /etc/xtab by hand. .SH FILES .TP .CR /etc/exports Static export information .TP .CR /etc/netgroup List of network groups .TP .CR /etc/xtab Current state of exported directories .SH SEE ALSO showmount(1M), exports(4), netgroup(4). .\" .\" toc@\f3exportfs(1M):\0\0\f4exportfs\f1@@@ export and unexport directories to NFS clients .\" .\" index@\f4exportfs\f1 \- export and unexport directories to NFS clients@@@\f3exportfs(1M)\f1 .\" index@\f1export directories to NFS clients@@@\f3exportfs(1M)\f1 .\" index@\f1unexport directories to NFS clients@@@\f3exportfs(1M)\f1 .\" index@\f1directories to NFS clients, export and unexport@@@\f3exportfs(1M)\f1 .\" index@\f1NFS clients, export and unexport directories to@@@\f3exportfs(1M)\f1 .\" index@\f1clients, export and unexport directories to NFS@@@\f3exportfs(1M)\f1 .\" $Header: extendfs.1m,v 76.2 95/08/01 09:50:55 ssa Exp $ .TA e .TH extendfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME extendfs (generic) \- extend a file system size .SH SYNOPSIS .C /usr/sbin/extendfs .RC [ -F .CR FStype ] .RC [ -q ] .RC [ -v ] .RC [ -s .IR size\| ] .I special .SH DESCRIPTION If the original file system image created on .I special does not make use of all of the available space, .C extendfs can be used to increase the capacity of a file system by updating the file system structure to include the extra space. .PP The command-line parameter .I special specifies the device special file of either a logical volume or a disk partition. The .I special must be un-mounted before .C extendfs can be run (see .IR mount (1M)). .SS Options .C extendfs recognizes the following options: .RS .TP 10 .CI -F\0FStype Specify the file system type on which to operate (see .IR fstyp (1M) and .IR fs_wrapper (5)). If this option is not included on the command line, then the file system type is determined from the file .CR /etc/default/fs . .TP .C -q Query the size of .IR special . No file system extension will be done. .TP .C -v Verbose flag. .TP .CI -s \0size Specifies the number of .C DEV_BSIZE blocks to be added to the file system. If .CI .IR size is not specified, the maximum possible size is used. .SH EXAMPLES To increase the capacity of a file system created on a logical volume, enter: .IP .C umount /dev/vg00/lvol1 .IP .CI "lvextend -L" " larger_size" .C /dev/vg00/lvol1 .IP .C extendfs -F hfs /dev/vg00/rlvol1 .IP .CI "mount /dev/vg00/lvol1" " mount_directory" .SH SEE ALSO fstyp(1M), lvextend(1M), mkfs(1M), mount(1M), umount(1M), fs(4), fs_wrapper(5). .\" .\" toc@\f3extendfs(1M)\f1:\0\0\f4extendfs\f1@@@extend file system size .\" .\" index@\f4extendfs\f1 \- extend file system size@@@\f3extendfs(1M)\f1 .\" index@\f1extend file system size@@@\f3extendfs(1M)\f1 .\" index@\f1file system size, extend@@@\f3extendfs(1M)\f1 .\" index@\f1size, extend file system@@@\f3extendfs(1M)\f1 .\" .\" $Header: extendfs_hfs.1m,v 76.2 95/08/01 15:16:48 ssa Exp $ .TA e .TH extendfs_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME extendfs (hfs) \- extend an HFS file system size .SH SYNOPSIS .C /usr/sbin/extendfs .RC [ -F .CR hfs ] .RC [ -q ] .RC [ -v ] .RC [ -s .IR size\| ] .I special .SH DESCRIPTION If the original HFS file system image created on .I special does not make use of all of the available space, the .C extendfs command can be used to increase the capacity of an HFS file system by updating the file system structure to include the extra space. .PP The command-line parameter .I special specifies the character device special file of either a logical volume or a disk partition. The .I special must be unmounted before the .C extendfs command can be run (see .IR mount (1M)). .SS Options .C extendfs recognizes the following options: .RS .TP 10 .CI -F\0hfs Specify the HFS file system type. .TP .C -q Query the size of .IR special . No file system extension will be done. .TP .C -v Verbose flag. .TP .CI -s \0size Specifies the number of .C DEV_BSIZE blocks to be added to the file system. If the number of blocks is not specified, the maximum possible size is used. .RE .SH EXAMPLES To increase the capacity of a file system created on a logical volume, enter: .IP .C umount /dev/vg00/lvol1 .PD 0 .IP .CI "lvextend -L" " larger_size" .C /dev/vg00/lvol1 .IP .C extendfs -F hfs /dev/vg00/rlvol1 .IP .CI "mount /dev/vg00/lvol1" " mount_directory" .PD .SH WARNINGS The root file system cannot be extended using the .C extendfs command because the root file system is always mounted, and the .C extendfs command only works on unmounted file systems. .PP .C extendfs will fail if used on a file system, on a logical volume, where the logical block size of the logical volume is greater than the file system's fragment size. The logical block size, of a logical volume changes, when additional disks with larger sector size are added. .SH RETURN VALUE .C extendfs returns the following values: .RS .TP 10 .PD 0 .B \00 No errors were detected and file system was successfully extended. .TP .B \01 Command aborted. .PD .RE .SH SEE ALSO extendfs(1M), lvextend(1M), mkfs(1M), mount(1M), umount(1M), fs(4). .\" .\" toc@\f3extendfs_hfs(1M)\f1:\0\0\f4extendfs\f1@@@extend HFS file system size .\" .\" index@\f4extendfs_hfs\f1 \- extend HFS file system size@@@\f3extendfs_hfs(1M)\f1 .\" index@\f1extend HFS file system size@@@\f3extendfs_hfs(1M)\f1 .\" index@\f1file system size, extend HFS@@@\f3extendfs_hfs(1M)\f1 .\" index@\f1size, extend HFS file system@@@\f3extendfs_hfs(1M)\f1 .\" .\" $Header: extendfs_vxfs.1m,v 78.1 96/02/13 10:32:29 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA e .TH extendfs_vxfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME extendfs (vxfs) \- extend a VxFS file system size .SH SYNOPSIS .C /usr/sbin/extendfs .RC [ \-F .CR vxfs ] .RC [ \-q ] .RC [ \-v ] .RC [ \-s .IR size ] .I special .SH DESCRIPTION If the original VxFS file system image created on .I special does not make use of all of the available space, .C extendfs can be used to increase the capacity of a VxFS file system by updating the file system structure to include the extra space. .PP The command-line parameter .I special specifies the device special file of either a logical volume or a disk partition. If .I special refers to a mounted file system, .I special must be unmounted before .C extendfs can be run (see .IR mount (1M)). .SS Options .C extendfs recognizes the following options: .RS .TP 10 .C \-F vxfs Specify the VxFS file system type. .TP .C \-q Query the size of .IR special . No file system extension will be done. .TP .C \-v Verbose flag. .TP .CI "\-s" " size Specifies the number of .C DEV_BSIZE blocks to be added to the file system. If .IR size is not specified, the maximum possible size is used. .SH EXAMPLES To increase the capacity of a file system created on a logical volume, enter: .IP .C umount /dev/vg00/lvol1 .IP .CI "lvextend \-L" " larger_size" .C /dev/vg00/lvol1 .IP .C extendfs \-F vxfs /dev/vg00/rlvol1 .IP .CI "mount /dev/vg00/lvol1" " mount_directory" .SH SEE ALSO extendfs(1M), lvextend(1M), mkfs(1M), mount(1M), umount(1M), fs(4). .\" .\" toc@\f3extendfs_vxfs(1M)\f1:\0\0\f(CWextendfs\f1@@@extend VxFS file system size .\" .\" index@\f(CWextendfs_vxfs\f1 \- extend VxFS file system size@@@\f3extendfs_vxfs(1M)\f1 .\" index@\f1extend VxFS file system size@@@\f3extendfs_vxfs(1M)\f1 .\" index@\f1file system size, extend VxFS@@@\f3extendfs_vxfs(1M)\f1 .\" index@\f1size, extend VxFS file system@@@\f3extendfs_vxfs(1M)\f1 .\" .\" $Header: fbackup.1m,v 78.3 96/05/09 11:12:39 ssa Exp $ .TA f .TH fbackup 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fbackup \- selectively back up files .SH SYNOPSIS .C /usr/sbin/fbackup -f .I device .RC [ -f .IR device\| ]\0... .RC [ -0 - 9 ] .RC [ -nsuvyAEl ] .RC [ -i .IR path\| ] .RC [ -e .IR path\| ] .RC [ -g .IR graph\| ] .RC [ -d .IR path\| ] .RC [ -I .IR path\| ] .RC [ -V .IR path\| ] .RC [ -c .IR config\| ] .PP .C /usr/sbin/fbackup -f .I device .RC [ -f .IR device\| ]\0... .RC [ -R .IR restart\| ] .RC [ -nsuvyAEl ] .RC [ -d .IR path\| ] .RC [ -I .IR path\| ] .RC [ -V .IR path\| ] .RC [ -c .IR config\| ] .SH DESCRIPTION .CR fbackup combines features of .CR dump and .CR ftio to provide a flexible, high-speed file system backup mechanism (see .IR dump (1M) and .IR ftio (1)). .CR fbackup selectively transfers files to an output device. For each file transferred, the file's contents and all the relevant information necessary to restore it to an equivalent state are copied to the output device. The output device can be a raw magnetic tape drive, the standard output, a DDS\c -format tape, a rewritable magneto-optical disk or a file. .PP The selection of files to backup is done by explicitly specifying trees of files to be included or excluded from an .CR fbackup session. The user can construct an arbitrary graph of files by using the .CR -i or .CR -e options on the command line, or by using the .CR -g option with a graph file. For backups being done on a regular basis, the .CR -g option provides an easier interface for controlling the backup graph. .CR fbackup selects files in this graph, and attempts to transfer them to the output device. The selectivity depends on the mode in which .CR fbackup is being used; i.e., full or incremental backup. .PP When doing full backups, all files in the graph are selected. When doing incremental backups, only files in the graph that have been modified since a previous backup of that graph are selected. If an incremental backup is being done at level 4 and the .CR -g option is used, the database file is searched for the most recent previous backup at levels 0-3. If a file's modification time is before the time when the last appropriate session began and the i-node change time is before the time that same session ended, the file is not backed up. Beginning at HP-UX Release 8.0, all directories lying on the path to a file that qualifies for the incremental backup will also be on the backup media, even if the directories do not qualify on their own status. .PP If .CR fbackup is used for incremental backups, a database of past backups must be kept. .CR fbackup maintains this data in the text file .CR /var/adm/fbackupfiles/dates , by default. Note that the directory .CR /var/adm/fbackupfiles must be created prior to the first time .CR fbackup is used for incremental backups. The .CR -d option can be used to specify an alternate database file. The user can specify to update this file when an .CR fbackup session completes successfully. Entries for each session are recorded on separate pairs of lines. The following four items appear on the first line of each pair: the graph file name, backup level, starting time, and ending time (both in .IR time (2) format). The second line of each pair contains the same two times, but in .IR strftime (3C) format. These lines contain the local equivalent of .CR STARTED: , the start time, the local equivalent of .CR ENDED: , and the ending time. These second lines serve only to make the dates file more readable; .CR fbackup does not use them. All fields are separated by white space. Graph file names are compared character-by-character when checking the previous-backup database file to ascertain when a previous session was run for that graph. Caution must be exercised to ensure that, for example, .CR graph and .CR ./graph are not used to specify the same graph file because .CR fbackup treats them as two different graph files. .PP The general structure of a .CR fbackup volume is the same, no matter what type of device is used. There are some small specific differences due to differing capabilities of devices. The general structure is as follows: .RS .TP 3 \(bu Reserved space for ASCII tape label (1024 bytes) .PD 0 .TP \(bu .CR fbackup specific volume label (2048 bytes) .TP \(bu session index (size in field of volume label) .TP \(bu data .PD .RE .PP Each file entry in the index contains the volume number and the pathname of the file. At the beginning of every volume, .CR fbackup assumes that all files not already backed up will fit on that volume; an erroneous assumption for all but the last volume. Indices are accurate only for the previous volumes in the same set. Hence, the index on the last volume may indicate that a file resides on that volume, but it may not have actually been backed up (for example, if it was removed after the index was created, but before .CR fbackup attempted to back it up). The only index guaranteed to be correct in all cases is the on-line index .RC ( -I option), which is produced after the last volume has been written. Specific minor differences are listed below: .RS .TP 3 \(bu When using 9-track tape drives or DDS-format tape drives several small differences exist. The main blocks of information are separated by EOF. .CR fbackup checkpoints the media periodically to enhance error recovery. If a write error is detected, the user normally has two options: First, a new volume can be mounted and that volume rewritten from the beginning. Second, if the volume is not too severely damaged, the good data before the error can be saved, and the write error is treated as a normal end-of-media condition. The blocks of data with their checkpoint records are also separated by EOF. In addition if the DDS-format drive supports .I Fast Search Marks these will be used to enhance recovery speed by placing them between blocks of files. .TP \(bu For a magneto-optical device, a disk, a file, or standard output, there are no special marks separating the information pieces. Using standard output results in only one volume. .PD .RE .PP .CR fbackup provides the ability to use UCB-mode tape drives. This makes it possible to overlap the tape rewind times if two or more tape drives are connected to the system. .SS Set-up There are several things the user will want to consider when setting .CR fbackup up for regular use. These include type of device and media, full versus incremental frequency, amount of logging information to keep on-line, structure of the graph file, and on-line versus off-line backup. .PP The type of device used for backups can affect such things as media expenses, ability to do unattended backup and speed of the backup. Using 9-track tapes will probably result in the highest performance, but require user intervention for changing tapes. A magneto-optical autochanger can provide an unattended backup for a large system and long life media, however the media cost is high. The lowest cost will probably be achieved through DDS-format devices, but at the lowest performance. .PP It is also important to consider how often full backups should be made, and how many incremental backups to make between full backups. Time periods can be used, such as a full backup every Friday and incrementals on all other days. Media capacities can be used if incremental backups need to run unattended. The availability of personnel to change media can also be an important factor as well as the length of time needed for the backup. Other factors may affect the need for full and incremental backup combinations such as contractual or legal requirements. .PP If backup information is kept online; i.e., output from the .CR -V or .CR -I options, the required storage space must also be considered. Index file sizes are hard to predict in advance because they depend on system configuration. Each volume header file takes less than 1536 bytes. Of course the more information that is kept on-line, the faster locating a backup media for a recovery will be. .PP There are several ways to structure the graph file or files used in a system backup. The first decision involves whether to use one or more than one graph files for the backup. Using one file is simpler, but less flexible. Using two or more graph files simplifies splitting backups into logical sets. For example, one graph file can be used for system disks where changes tend to be less frequent, and another graph file for the users area. Thus two different policies can be implemented for full and incremental backups. .PP .CR fbackup was designed to allow backups while the system is in use by providing the capability to retry an active file. When absolute consistency on a full backup is important, the system should probably be in single-user mode. However, incremental backups can be made while the system is in normal use, thus improving system up-time. .SS Options .TP 15 .CI -c \0config .I config is the name of the configuration file, and can contain values for the following parameters: .RS 18 .TP 3 \(bu Number of 1024-byte blocks per record, .PD 0 .TP \(bu Number of records of shared memory to allocate, .TP \(bu Number of records between checkpoints, .TP \(bu Number of file-reader processes, .TP \(bu Maximum number of times .CR fbackup is to retry an active file, .TP \(bu Maximum number of bytes of media to use while retrying the backup of an active file, .TP \(bu Maximum number of times a magnetic tape volume can be used, .TP \(bu Name of a file to be executed when a volume change occurs. This file must exist and be executable. .TP \(bu Name of a file to be executed when a fatal error occurs. This file must exist and be executable. .TP \(bu The number of files between the .I Fast Search Marks on DDS-format tapes. The cost of these marks are negligible in terms of space on the DDS-format tape. Not all DDS-format devices support fast search marks. .PD .RE .IP Each entry in the configuration file consists of one line of text in the following format: identifier, white space, argument. In the following sample configuration file, the number of blocks per record is set to 16, the number of records is set to 32, the checkpoint frequency is set to 32, the number of file reader processes is set to 2, the maximum number of retries is set to 5, the maximum retry space for active files is set to 5,000,000 bytes, the maximum number of times a magnetic tape volume can be used is set to 100, the file to be executed at volume change time is .CR /var/adm/fbackupfiles/chgvol , the file to be executed when a fatal error occurs is .CR /var/adm/fbackupfiles/error , and the number of files between fast search marks is set to 200. .RS .RS .TP 25 .PD 0 .CR blocksperrecord 16 .TP .C records 32 .TP .C checkpointfreq 32 .TP .C readerprocesses 2 (maximum of 6) .TP .C maxretries 5 .TP .C retrylimit 5000000 .TP .C maxvoluses 100 .TP .C chgvol .C /var/adm/fbackupfiles/chgvol .TP .C error .C /var/adm/fbackupfiles/error .TP .C filesperfsm 200 .PD .RE .RE .IP Each value listed is also the default value, except .CR chgvol and .CR error , which default to null values. .TP .CI -d \0path This specifies a path to a database for use with incremental backups. It overrides the default database file .CR /var/adm/fbackupfiles/dates . .TP .CI -e \0path .I path specifies a tree to be excluded from the backup graph. This tree must be a subtree of part of the backup graph. Otherwise, specifying it will not exclude any files from the graph. There is no limit on how many times the .CR -e option can be specified. .TP .CI -f \0device .I device specifies the name of an output file. If the name of the file is .CR - , .CR fbackup writes to the standard output. There is no default output file; at least one must be specified. If more than one output file is specified, .CR fbackup uses each one successively and then repeats in a cyclical pattern. Patterns can be used in the device name in a manner resembling file name expansion as done by the shell (see .IR sh-bourne (1) and other shell manual entries. The patterns must be protected from expansion by the shell by quoting them. The expansion of the pattern results in all matching names being in the list of devices used. .IP There is slightly different behavior if remote devices are used. A device on the remote machine can be specified in the form .IC machine : device\f1. .CR fbackup creates a server process from .CR /usr/sbin/rmt on the remote machine to access the tape device. If .CR /usr/sbin/rmt does not exist on the remote system, .CR fbackup creates a server process from .CR /etc/rmt on the remote machine to access the tape device. Only half-inch 9-track magnetic tapes or DDS-format tapes can be remote devices. The fast search and save set marks capabilities are not used when remote DDS-format devices are used. .TP .CI -g \0graph .I graph defines the graph file. The graph file is a text file containing the list of file names of trees to be included or excluded from the backup graph. These trees are interpreted in the same manner as when they are specified with the .CR -i and .CR -e options. Graph file entries consist of a line beginning with either .CR i or .CR e , followed by white space, and then the path name of a tree. Lines not beginning with .CR i or .CR e are treated as an error. There is no default graph file. For example, to backup all of .CR /usr except for the subtree .CR /usr/lib , a file could be created with the following two records: .RS .IP .C i /usr .br .C e /usr/lib .RE .TP .CI -i \0path .I path specifies a tree to be included in the backup graph. There is no limit on how many times the .CR -i option can be specified. .TP .C -n Cross NFS mount points. By default .CR fbackup does not cross NFS mount points, regardless of paths specified by the .CR -i or .CR -g options. .TP .C -l Includes LOFS files specified by the backup graph. By default, .CR fbackup does not cross LOFS mount points. If .CR -l is specified, and the backup graph includes files which are also in a LOFS that is in the backup graph, then those files will backed up twice. .TP .C -s Backup the object that a symbolic link refers to. The default behavior is to backup the symbolic link. .TP .C -u Update the database of past backups so that it contains the backup level, the time of the beginning and end of the session, and the graph file used for this .CR fbackup session. For this update to take place, the following conditions must exist: Neither the .CR -i nor the .CR -e option can be used; the .CR -g option must be specified exactly once (see below); the .CR fbackup must complete successfully. .TP .C -v Run in verbose mode. Generates status messages that are otherwise not seen. .TP .C -y Automatically answer .CR yes to any inquiries. .TP .C -A Do not back up optional entries of access control lists (ACLs) for files. Normally, all mode information is backed up including the optional ACL entries. With the .CR -A option, the summary mode information (as returned by .CR stat() ) is backed up. Use this option when backing up files from a system that contains ACL to be recovered on a system that does not understand ACL (see .IR acl (5)). .TP .C -E Do not back up extent attributes. Normally, all extent attributes that have been set are included with the file. This option only applies to file systems which support extent attributes. .TP .CI -I \0path .I path specifies the name of the on-line index file to be generated. It consists of one line for each file backed up during the session. Each line contains the volume number on which that file resides and the file name. If the .CR -I option is omitted, no index file is generated. .TP .CI -V \0path The volume header information is written to .I path at the end of a successful .CR fbackup session. The following fields from the header are written in the format .IC label : value with one pair per line. .RS .RS .TP 23 .PD 0 .C Magic Field On a valid .CR fbackup media it contains the value .CR "FBACKUP_LABEL" (HP-UX release 10.20 and beyond). Before HP-UX release 10.20, it contained the value .CR "FBACKUP LABEL" . .TP .C Machine Identification This field contains the result of .CR "uname -m" . .TP .C System Identification This field contains the result of .CR "uname -s" . .TP .C Release Identification This field contains the result of .CR "uname -r" . .TP .C Node Identification This field contains the result of .CR "uname -n" . .TP .C User Identification This field contains the result of .CR cuserid() (see .IR cuserid (3S)). .TP .C Record Size This field contains the maximum length in bytes of a data record. .TP .C Time This field contains the clock time when .CR fbackup was started. .TP .C Media Use This field contains the number of times the media has been used for backup. Since the information is actually on the media, this field will always contain the value 0. .TP .C Volume Number This field contains a .CR # character followed by 3 digits, and identifies the number of volumes in the backup. .TP .C Checkpoint Frequency This field contains the frequency of backup-data-record checkpointing. .TP .C Index Size This field contains the size of the index. .TP .C Backup Identification Tag This field is composed of two items: the process ID (pid) and the start time of that process. .TP .C Language This field contains the language used to make the backup. .PD .RE .RE .TP .CI -R \0restart Restart an .CR fbackup session from where it was previously interrupted. The .I restart file contains all the information necessary to restart the interrupted session. None of the .CR - [ ieg0 - 9 ] options can be used together with the restart option. .TP .CR -0 - 9 This single-digit number is the backup level. Level .CR 0 indicates a full backup. Higher levels are generally used to perform incremental backups. When doing an incremental backup of a particular graph at a particular level, the database of past backups is searched to find the date of the most recent backup of the same graph that was done at a lower level. If no such entry is found, the beginning of time is assumed. All files in the graph that have been modified since this date are backed up. .SS "Access Control Lists (\s-1ACL\s+1s) .PP If a file has optional ACL entries, the .CR -A option is required to enable its recovery on a system whose access control lists capability is not present. .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LC_COLLATE determines the order in which files are stored in the backup device and the order output by the .CR -I option. .PP .CR LC_TIME determines the format and contents of date and time strings. .PP .CR LC_MESSAGES determines the language in which messages are displayed. .PP If .CR LC_COLLATE and .CR LC_TIME and .CR LC_MESSAGES are not all specified in the environment or if either is set to the empty string, the value of .CR LANG is used as a default for each unspecified or empty variable. If .CR LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR fbackup behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .CR fbackup returns 0 upon normal completion, 1 if it is interrupted but allowed to save its state for possible restart, and 2 if any error conditions prevent the session from completing. .SH EXAMPLES In the following two examples, assume the graph of interest specifies all of .CR /usr except .CR /usr/lib (as described in the .CR g key section above). .PP The first example is a simple case where a full backup is done but the database file is not updated. This can be invoked as follows: .IP .C "/usr/sbin/fbackup -0i /usr -e /usr/lib -f /dev/rmt/c0t0d0BEST" .PP The second example is more complicated, and assumes the user wants to maintain a database of past .CR fbackup sessions so that incremental backups are possible. .PP If sufficient on-line storage is available, it may be desirable to keep several of the most recent index files on disk. This eliminates the need to recover the index from the backup media to determine if the files to be recovered are on that set. One method of maintaining on-line index files is outlined below. The system administrator must do the following once before .CR fbackup is run for the first time (creating intermediate level directories where necessary): .RS .TP 3 \(bu Create a suitable configuration file called .CR config in the directory .CR /var/adm/fbackupfiles .TP \(bu Create a graph file called .CR usr-usrlib in the directory .CR /var/adm/fbackupfiles/graphs .TP \(bu Create a directory called .CR usr-usrlib in the directory .CR /var/adm/fbackupfiles/indices .RE .PP A shell script that performs the following tasks could be run for each .CR fbackup session: .PP .RS .TP 3 \(bu Build an index file path name based on both the graph file used (passed as a parameter to the script) and the start time of the session (obtained from the system). For example: .RS .IP .CR /var/adm/fbackupfiles/indices/usr-usrlib/871128.15:17 .br (for Nov 28, 1987 at 3:17 PM) .RE .TP \(bu Invoke .CR fbackup with this path name as its index file name. For example: .RS .IP .CR "cd /var/adm/fbackupfiles" .br .C "/usr/sbin/fbackup -0uc config -g graphs/usr-usrlib\e" .br .C \h'.3i'-I indices/usr-usrlib/871128.15:17\e .br .C "\h'.6i'-f /dev/rmt/c0t0d0BEST" .RE .RE .PP When the session completes successfully, the index is automatically placed in the proper location. .PP Note that .CR fbackup should be piped to .CR tcio when backing up to a CS/80 cartridge tape device see .IR tcio (1)). The following example copies the entire contents of directory .CR /usr to a cartridge tape: .IP .C "/usr/sbin/fbackup i /usr -f - | tcio -oe /dev/rct/c0d1s2" .SH WARNINGS With release 10.20, HP-UX supports large files (greater than 2GB) and increased UID/GIDs (greater than 60,000). Archives containing files with these attributes would cause severe problems on systems that do not support the increased sizes. For this reason, .CR fbackup creates tapes with a new magic number ("FBACKUP_LABEL"). This prevents .CR fbackup tape archives from being restored on pre-10.20 HP-UX systems. .CR frecover still reads both tape formats so that .CR fbackup tape archives created on pre-10.20 HP-UX systems can be restored. .PP Starting with HP-UX Release 8.0, .CR fbackup does not back up network special files because RFA networking is obsolete. A warning message is issued if a network special file is encountered in the backup graph and the file is skipped. .PP The use of .CR fbackup for backing up NFS mounted file systems is not guaranteed to work as expected if the backup is done as a privileged user. This is due to the manner in which NFS handles privileged-user access by mapping user .CR root and uid .CR 0 to user .CR nobody , usually uid .CR -2 , thus disallowing root privileges on the remote system to a root user on the local system. .PP The utility set comprised of .CR fbackup and .CR frecover was originally designed for use on systems equipped with not more than one gigabyte of total file system storage. Although the utilities have no programming limitations that restrict users to this size, complete backups and recoveries of substantially larger systems can cause a large amount system activity due to the amount of virtual memory (swap space) used to store the indices. Users who want to use these utilities, but are noticing poor system-wide performance due to the size of the backup, are encouraged to backup their systems in multiple smaller sessions, rather than attempting to backup the entire system at one time. .PP Due to present file-system limitations, files whose inode data, but not their contents, are modified while a backup is in progress might be omitted from the next incremental backup of the same graph. Also, .CR fbackup does not reset the inode change times of files to their original value. .PP .CR fbackup allocates resources that are not returned to the system if it is killed in an ungraceful manner. If it is necessary to kill .CR fbackup , send it a .CR SIGTERM ; not a .CR SIGKILL . .PP For security reasons, configuration files and the .CR chgvol and .CR error executable files should only be writable by their owners. .PP If sparse files are backed up without using data compression, a very large amount of media can be consumed. .PP .CR fbackup does not require special privileges. However, if the user does not have access to a given file, the file is not backed up. .PP .CR fbackup consists of multiple executable objects, all of which are expected to reside in directory .CR /usr/sbin . .PP .CR fbackup creates volumes with a format that makes duplication of volumes by .CR dd impossible (see .IR dd (1)). Copying an .CR fbackup volume created on one media type to another media type does not produce a valid .CR fbackup volume on the new media because the formats of volumes on 9-track tape, backup to a file, rewritable optical disks and DDS-format tapes are not identical. .PP When configuring the parameter .CR blocksperrecord (see .CR -c option), the record size is limited by the maximum allowed for the tape drive. Common maximum record sizes include 16 1-Kbyte blocks for tape drive models HP\|7974 and HP\|7978A, 32 blocks for the HP\|7978B, 60 blocks for the HP\|7980, and 64 blocks for DDS tape drives. Note also that the .I blocksize used in earlier releases (7.0 and before) was 512 bytes, whereas it is now 1024 bytes. This means that the same value specified in .I blocksperrecord in an earlier release creates blocks twice their earlier size in the current release (i.e., a .I blocksperrecord parameter of 32 would create 16-Kbyte blocks at Release 7.0, but now creates 32-Kbyte blocks). If .I blocksperrecord exceeds the byte count allowed by the tape drive, the tape drive rejects the write, causing an error to be communicated to .CR fbackup which .CR fbackup interprets as a bad tape. The resulting write error message resembles the following: .IP .C "fbackup (3013): Write error while writing backup at tape block 0." .br .C "Diagnostic error from tape 11...... SW_PROBLEM" .RI \0\0( "printed by driver on console" ) .br .C "fbackup (3102): Attempting to make this volume salvageable." .br etc. .SH DEPENDENCIES .SS NFS Access control lists of networked files are summarized (as returned in .CR st_mode by .CR stat() ), but not copied to the new file (see .IR stat (2)). .SS Series 800 On NIO-bus machines there can be problems when a CS/80 cartridge tape device is on the same interface card as hard disk devices. If writes longer than 16K bytes are made to the tape device, it is possible to have disk access time-out errors. This happens because the tape device has exclusive access to the bus during write operations. Depending on the system activity, this problem may not be seen. The default write size of .CR fbackup is 16 Kbytes. .SS Series 700/800 .CR fbackup does not support QIC-120, and QIC-150 formats on QIC devices. If .CR fbackup is attempted for these formats, .CR fbackup fails and the following message is displayed : .IP .C "mt lu X: Write must be a multiple of 512 bytes in QIC 120 or QIC 150" .SH AUTHOR .CR fbackup was developed by HP. .SH FILES .TP 45 .C /var/adm/fbackupfiles/dates database of past backups .SH SEE ALSO cpio(1), ftio(1), tcio(1), dump(1M), frecover(1M), ftio(1M), restore(1M), rmt(1M), stat(2), acl(5), mt(7). .\" .\" index@\f4fbackup\f1 \- back up selected files or groups of files@@@\f3fbackup(1M)\f1 .\" index@files: back up selected files or groups of files@@@\f3fbackup(1M)\f1 .\" .\" toc@\f3fbackup(1M)\f1:\0\0\f4fbackup\f1@@@selectively back up files .\" .\" $Header: fdetach.1m,v 72.2 94/10/13 16:02:26 ssa Exp $ .TA f .TH fdetach 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH "NAME" fdetach \- detach a STREAMS-based file descriptor from a filename .SH "SYNOPSIS" .CR fdetach .I path .SH "DESCRIPTION" The .CR fdetach command detaches or disassociates a file descriptor for an open STREAMS device or pipe from its filename in the file system. The .I path argument is the .I path that was previously associated with the file descriptor by the .CR fattach() function. .PP Operations on .I path will subsequently affect the file system node, not the STREAMS device or pipe. The permissions and status of the node are returned to the state that they were in before the STREAMS device or pipe was attached. Any other paths that the STREAMS device or pipe may be attached to are not affected. .PP To successfully issue the .CR fdetach command, the user must be superuser or must be the owner of the file and have write permission. .SH "RETURN VALUE" .CR fdetach returns 0 (zero) on success. If .CR fdetach fails, it returns 1 and prints a message to .CR stderr . .SH "EXAMPLES" To detach the file descriptor for the STREAMS file .CR /tmp/streamfile from its associated file system node, enter: .PP .CR "fdetach /tmp/streamfile" .SH "FILES" .TP 40 .CR /usr/lib/nls/C/fdetach.cat NLS catalog for .CR fdetach . .SH "SEE ALSO" fattach(3c), fdetach(3c), streamio(7). .\" .\" index@\f4fdetach\f1 \- detach a STREAMS-based file descriptor@@@\f3fdetach(1M)\f1 .\" index@\f1detach a STREAMS-based file descriptor@@@\f3fdetach(1M)\f1 .\" index@\f1filename: detach a STREAMS-based file descriptor@@@\f3fdetach(1M)\f1 .\" index@\f1file descriptor: detach a STREAMS-based file descriptor@@@\f3fdetach(1M)\f1 .\" index@\f1STREAMS-based file descriptor@@@\f3fdetach(1M)\f1 .\" index@\f1STREAMS: detach a STREAMS-based file descriptor@@@\f3fdetach(1M)\f1 .\" .\" toc@\f3fdetach(1M)\f1:\0\0\f4fdetach\f1@@@detach a STREAMS-based file descriptor from a filename .\" .\" fileset_database@fdetach.1m STREAMS-MAN .\" $Header: ff.1m,v 72.7 94/12/08 12:18:10 ssa Exp $ .TA f .TH ff 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ff(generic) \- list file names and statistics for a file system .SH SYNOPSIS .CR /usr/sbin/ff .RC [ \-F .IR FStype ] .RC [ \-o .IR specific_options ] .RC [ \-V ] .IR special \0... .SH DESCRIPTION The .CR ff command reads the i-list and directories of each .I special file, assuming it to be a file system, saving i-node data for files that match the selection criteria. Output consists of the path name for each saved i-node, plus any other file information requested with the .CR \-o option. Output fields are positional. The output is produced in i-node order; fields are separated by tabs. The default line produced by .CR ff includes the path name and i-number fields. .SS Options and Arguments .CR ff recognizes the following options and arguments: .RS .TP 15 .CI \-F \0FStype Specify the file system type on which to operate (see .IR fstyp (1M) and .IR fs_wrapper (5)). If this option is not included on the command line, then the file system type is determined from the file .CR /etc/fstab by matching each .I special with an entry in that file. If there is no entry in .CR /etc/fstab , then the file system type is determined from the file .CR /etc/default/fs . .TP .CI \-o \0specific_options Specify options specific to each file system type. .I specific_options is a list of suboptions and/or keyword/attribute pairs intended for a specific .IR FStype -specific module of the command. See the file-system-specific man pages for a description of the .I specific_options supported, if any. .TP .CR \-V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SH EXAMPLES List the path names and i-numbers of all files in the file system .CR /dev/dsk/c1d2s0 : .IP .C "ff /dev/dsk/c1d2s0" .PP Execute the .CR ff command on HFS file system .CR /dev/dsk/c1d2s0 : .IP .C "ff \-F hfs /dev/dsk/c1d2s0" .PP Display a completed command line without executing the command: .IP .C "ff \-V /dev/dsk/c1d2s0" .SH FILES .TP 25 .CR /etc/default/fs File that specifies the default system type. .PD 0 .TP .CR /etc/fstab Static information about the file systems. .PD .SH SEE ALSO find(1), .RI ff_ FStype (1M), fstyp(1M), ncheck(1M), fstab(4), fs_wrapper(5). .\" .\" toc@\f3ff(1M)\f1:\0\0\f4ff\f1@@@list file names and statistics for file system (generic) .\" .\" index@\f4ff\f1 \- list file names and statistics for file system (generic)@@@\f3ff(1M)\f1 .\" index@\f1list file names and statistics for file system (generic)@@@\f3ff(1M)\f1 .\" index@\f1file names for file system, list (generic)@@@\f3ff(1M)\f1 .\" index@\f1statistics for file system, list (generic)@@@\f3ff(1M)\f1 .\" index@\f1file system, list file names and statistics for (generic)@@@\f3ff(1M)\f1 .\" index@\f1file system, list file names and statistics (generic)@@@\f3ff(1M)\f1 .\" $Header: ff_hfs.1m,v 72.3 94/11/30 14:25:41 ssa Exp $ .TA f .TH ff_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ff(hfs) \- list file names and statistics for HFS file system .SH SYNOPSIS .CR /usr/sbin/ff .RC [ \-F .CR hfs ] .RC [ \-a .IR num ] .RC [ \-c .IR num ] .RC [ \-i .IR inode-list ] .RC [ \-I ] .RC [ \-l ] .ifn .br .ifn \0\0\0\0 .RC [ \-m .IR num ] .RC [ \-n .IR file ] .ift .br .ift \0\0\0\0 .RC [ \-p .IR prefix ] .RC [ \-s ] .RC [ \-u ] .RC [ \-V ] .IR special \0... .SH DESCRIPTION The .CR ff command reads the i-list and directories of each special file .IR special , assuming it to be an HFS file system, saving i-node data for files that match the selection criteria. Output consists of the path name for each saved i-node, plus any other file information requested using the print options below. Output fields are positional. The output is produced in i-node order; fields are separated by tabs. The default line produced by .CR ff contains the path name and i-number fields. With all options specified, the output fields include path name, i-number, size, and user ID. .PP The .I num parameter in the options descriptions is a decimal number, where .CI + num means more than .IR num , .CI \- num means less than .IR num , and .I num means exactly .IR num . A day is defined as a 24-hour period. .PP .CR ff lists only a single path name out of many possible ones for an i-node with more than one link, unless you specify the .CR \-l option. With .CR \-l , .CR ff applies no selection criteria to the names listed. All possible names for every linked file on the file system are included in the output. On very large file systems, memory may run out before .CR ff completes execution. .SS Options and Arguments .CR ff recognizes the following options and arguments: .RS .TP 15 .CI \-a \0num Select a file if the i-node has been accessed in .I num days. .TP .CI \-c \0num Select a file if the i-node has been changed in .I num days. .TP .CR \-F\0hfs Specify the HFS file system type. .TP .CI \-i \0inode-list Generate names for any i-node specified in the .IR inode-list . .TP .CR \-I Do not display the i-node number after each path name. .TP .CR \-l Generate a list of all path names for files with more than one link. .TP .CI \-m \0num Select a file associated with an i-node if it has been modified in .I num days. .TP .CI \-n \0file Select a file associated with an i-node if it has been modified more recently than the specified .IR file . .TP .CI \-p \0prefix Add the specified .I prefix to each path name. The default prefix is .CR . (dot). .TP .CR \-s Write the file size, in bytes, after each path name. .TP .CR \-u Write the owner's login name after each path name. .TP 15 .CR \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .SH EXAMPLES List the path names and i-numbers of all files in the file system .CR /dev/dsk/c1d2s0 : .IP .C "ff /dev/dsk/c1d2s0" .PP Same as above, but suppress the printing of i-numbers: .IP .C "ff \-I /dev/dsk/c1d2s0" .PP List files on the same file system that have been modified recently, displaying the path name, i-number, and owner's user name (the .CR \-u option). List only files that have been modified within the last two days (the .CR "\-m\ \-2" option): .IP .C "ff \-m \-2 \-u /dev/dsk/c1d2s0" .PP List all files on the same file system, including the path name and i-number of each file, that was last accessed more than 30 days ago .RC ( "\-a\ +30" ): .IP .C "ff \-a +30 /dev/dsk/c1d2s0" .PP Find all path names associated with i-nodes .CR 451 and .CR 76 (the .CR \-l option): .IP .C "ff \-l \-i 451,76 /dev/dsk/c1d2s0" .PP Execute the .CR ff command on an HFS file system .CR /dev/dsk/c1d2s0 : .IP .C "ff \-F hfs /dev/dsk/c1d2s0" .SH FILES .TP 20 .CR /etc/fstab Static information about the file systems. .SH SEE ALSO find(1), ff(1M), ncheck(1M), fstab(4). .\" .\" toc@\f3ff_hfs(1M)\f1:\0\0\f4ff\f1@@@list file names and statistics for HFS file system .\" .\" index@\f4ff\f1 \- list file names and statistics for HFS file system@@@\f3ff_hfs(1M)\f1 .\" index@\f1list file names and statistics for HFS file system@@@\f3ff_hfs(1M)\f1 .\" index@\f1file names and statistics for HFS file system, list@@@\f3ff_hfs(1M)\f1 .\" index@\f1names and statistics for HFS file system, list file@@@\f3ff_hfs(1M)\f1 .\" index@\f1statistics for HFS file system, list file names and@@@\f3ff_hfs(1M)\f1 .\" index@\f1file system, list file names and statistics for HFS@@@\f3ff_hfs(1M)\f1 .\" index@\f1HFS file system, list file names and statistics@@@\f3ff_hfs(1M)\f1 .\" index@\f1i-number, list path name corresponding to@@@\f3ff_hfs(1M)\f1 .\" index@\f1list path name corresponding to i-number@@@\f3ff_hfs(1M)\f1 .\" index@\f1path name corresponding to i-number, list@@@\f3ff_hfs(1M)\f1 .\" $Header: ff_vxfs.1m,v 78.2 96/05/09 10:49:33 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA f .TH ff_vxfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ff (vxfs) \- fast find: list file names and statistics for a VxFS file system .SH SYNOPSIS .C /usr/sbin/ff .RC [ \-F .CR vxfs ] .RC [ \-VIlsu ] .RC [ \-p .IR prefix ] .RC [ \-a .IR num ] .RC [ \-m .IR num ] .RC [ \-c .IR num ] .RC [ \-n .IR file ] .RC [ \-i .IR inode-list ] .RC [ \-o .IR specific_options ] .I special ... .SH DESCRIPTION The .C ff command reads the i-list and directories of the special file .I special, assuming it to be a VxFS file system, printing i-node data for files that match the selection criteria. Output consists of the pathname for each saved i-node, plus any other file information requested using the print options below. Output fields are positional. The output is produced in i-node order; fields are separated by tabs. The default line produced by the .C ff command includes the path name and i-number fields. With all options specified, the output fields include path name, i-number, size, and user ID. .PP The .I num parameter in the options descriptions is a decimal number, where .CI + num means more than .IR num days, .CI \- num means less than .IR num days, and .I num means exactly .IR num days. A day is defined as a 24 hour period. .SS Options .C ff recognizes the following options: .RS .TP 15 .CI \-a \0num Select a file if the i-node has been accessed in .I num days. .TP .CI \-c \0num Select a file if the i-node has been changed in .I num days. .TP 15 .CR \-F\0vxfs Specify the VxFS file system type. .TP .CI \-i \0inode-list Generate names for any i-nodes specified in the .IR inode-list . .TP .C \-I Does not display the i-node number after each path name. .TP .C \-l Generates a list of all path names for files with more than one link. .TP .CI \-m \0num Select a file associated with the i-node if it has been modified in .I num days. .TP .CI \-n \0file Select a file associated with an i-node if it has been modified more recently than the specified .IR file . .TP .CI \-p \0prefix Adds the specified .I prefix to each path name. The default prefix is .C . (dot). .TP .CI \-o \0specific_options Specify options specific to the VxFS file system type. .I specific_options is a list of suboptions and/or keyword/attribute pairs intended for the VxFS specific module of the command. .IP The available option is: .RS .TP .C s Display only special files and files with set-user-ID mode. .RE .TP .C \-s Writes the file size, in bytes, after each path name. .TP .C \-u Writes the owner's login name after each path name. .TP 15 .C \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SH EXAMPLES List the path names and i-numbers of all files in the file system .CR /dev/vg01/rlvol1 : .IP .C ff /dev/vg01/rlvol1 .PP Same as above, but suppress the printing of i-numbers: .IP .C ff \-I /dev/vg01/rlvol1 .PP List files on the same file system that have been modified recently, displaying the path name, i-number, and owner's user name .RC ( "\-u" option). List only files that have been modified within the last two days .RC ( "\-m \-2" option): .IP .C " ff \-m \-2 \-u /dev/vg01/rlvol1 .PP List all files on the same file system, including the path name and i-number of each file, that was last accessed more than 30 days ago .RC ( "\-a\ +30" ): .IP .C "ff \-a +30 /dev/vg01/rlvol1 .PP Find all path names associated with i-nodes .CR 451 and .CR 76 .CR (\-l option): .IP .C "ff \-l \-i 451,76 /dev/vg01/rlvol1 .PP Execute the .C ff command on a VxFS file system .CR /dev/vg01/rlvol1 : .IP .C ff \-F vxfs /dev/vg01/rlvol1 .SH FILES .TP 20 .CR /etc/fstab Static information about the file systems. .SH SEE ALSO ff(1M), find(1), fstab(4), ncheck(1M). .\" .\" toc@\f3ff_vxfs(1M)\f1:\0\0\f(CWff\f1@@@fast find: list file names and statistics for VxFS file system .\" .\" index@\f(CWff_vxfs\f1 \- fast find: list file names and statistics for VxFS file system@@@\f3ff_vxfs(1M)\f1 .\" index@\f(CWff\f1 \- fast find: list file names and statistics for VxFS file system@@@\f3ff_vxfs(1M)\f1 .\" index@\f1fast find: list file names and statistics for VxFS file system@@@\f3ff_vxfs(1M)\f1 .\" index@\f1list file names and statistics for VxFS file system@@@\f3ff_vxfs(1M)\f1 .\" index@\f1file names and statistics for VxFS file system@@@\f3ff_vxfs(1M)\f1 .\" index@\f1statistics for VxFS file system@@@\f3ff_vxfs(1M)\f1 .\" index@\f1VxFS file system, list file names and statistics@@@\f3ff_vxfs(1M)\f1 .\" index@\f1file system, list file names and statistics for VxFS@@@\f3ff_vxfs(1M)\f1 .\" .\" .\" $Header: fingerd.1m,v 72.5 94/12/09 14:54:58 ssa Exp $ .TA f .TH fingerd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fingerd \- remote user information server .SH SYNOPSIS .C /usr/lbin/fingerd .RC [ -r ] .SH DESCRIPTION .C fingerd is the server for the RFC 742 Name/Finger protocol. It provides a network interface to .CR finger , which gives a status report of users currently logged in on the system or a detailed report about a specific user (see .IR finger (1)). The Internet daemon executes .C fingerd when it receives a service request at the port listed in the services data base for ``finger'' using ``tcp'' protocol; see .IR inetd (1M) and .IR services (4). .PP To start .C fingerd from .CR inetd , the configuration file .C /etc/inetd.conf must contain an entry as follows: .IP .C "finger stream tcp nowait bin /usr/lbin/fingerd fingerd" .PP Once a remote host is connected, .C fingerd reads a single ``command line'' terminated by a carriage-return and line-feed. It uses this command line as the arguments to an invocation of .CR finger . .C fingerd sends the output of .C finger to the remote host and closes the connection. .PP If the command line is null (contains only a carriage-return and line-feed pair), .C finger returns a report that lists all users logged in on the system at that moment. .PP If a user name is specified on the command line (for example, .IR user ), the response lists more extended information for only that particular user, whether logged in or not. See .IR finger (1) for the details of this extended information. .PP If .C fingerd is run with the .C -r option, it allows remote user names on the command line (for example, .IR user @ host ). Otherwise, if the command line contains a remote user name, .C fingerd prints the error message .C Remote finger not allowed and closes the connection. .SH AUTHOR .C fingerd was developed by the University of California, Berkeley and HP. .SH SEE ALSO finger(1), inetd(1m), services(4), .PD 0 .PP RFC 742 for the Name/Finger protocol. .PD .\" .\" index@\f4fingerd\f1 \- remote user information server@@@\f3fingerd(1M)\f1 .\" index@remote user information server@@@\f3fingerd(1M)\f1 .\" index@user information server, remote@@@\f3fingerd(1M)\f1 .\" index@information server, remote user@@@\f3fingerd(1M)\f1 .\" index@server, remote user information@@@\f3fingerd(1M)\f1 .\" .\" toc@\f3fingerd(1M)\f1:\0\0\f4fingerd\f1@@@remote user information server .\" .\" fileset_database@fingerd.1m INETSVCS-MAN .\" $Header: fixman.1m,v 72.4 94/11/30 15:03:24 ssa Exp $ .TA f .TH fixman 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fixman \- fix manual pages for faster viewing with man(1) .SH SYNOPSIS .C /usr/sbin/fixman .RC [ \|\-A\| .IR alt-path ] .SH DESCRIPTION The .C fixman command is a shell script that processes man pages in the .C cat* directories to unexpand spaces to tabs where possible, and to remove all character-backspace pairs (which usually exist to cause overstriking or underscoring for printer output). Removal of unnecessary character sequences improves the speed of .IR man (1), and reduces disk space consumption. The .C fixman command should be run after using .C catman to create formatted, .CR cat -able manual entries from unformatted, .IR nroff (1)-compatible source files (see .IR catman (1M)). .PP By default, .C fixman searches for .C cat* subdirectories in the following parent directories in the order indicated: .PD 0 .RS .TP 3 \(bu .C /usr/share/man .TP \(bu .C /usr/contrib/man .TP \(bu .C /usr/local/man .PD .RE If the .C MANPATH environment variable is set, the directory paths specified by .C MANPATH are searched instead of the default. See .IR environ (5) for a description of the .C MANPATH environment variable. .PP The .C fixman command does not remove duplicate blank lines. Thus, all files remain a multiple of one page (66 lines) long and can still be passed directly to .C lp (see .IR lp (1)). (Note that .IR man (1) normally uses .C more -s to accomplish this removal.) .PP To ensure success, .C fixman should be run by a user who has appropriate privileges. It will take awhile to complete depending on system speed, load, memory size, etc. As a side-effect, file ownerships and permissions may be changed. .SS Options .TP .CI \-A \0alt-path Perform actions based on the given alternate root. With this option, .I alt-path will be prepended to all directory paths, including default paths or the paths defined by .CR MANPATH . .SH EXTERNAL INFLUENCES .SS Environment Variables .CR MANPATH , if set, defines the directories to be searched for .CR cat -able manual entries. .SH WARNING If the value of .C MANPATH is not the same while .CR fixman is running as it was when .C catman was run or when manpage files were installed, some files may be missed and not processed (see .IR catman (1M)). .SH EXAMPLES Run fixman from a server to fix the manual pages on a diskless under the alternate root .CR /export/shared_roots/OS_700 : .IP .C fixman -A /export/shared_roots/OS_700 .PP .PD 0 This will fix manpages in .C cat* directories under: .IP .CR /export/shared_roots/OS_700/usr/share/man/ .br .CR /export/shared_roots/OS_700/usr/contrib/man/ .br .CR /export/shared_roots/OS_700/usr/local/man/ .PD .SH FILES .TP 33 .PD 0 .C /usr/share/man/cat\(**[.Z] Directories containing [compressed] .IR nroff (1)-formatted versions of manual entries .TP .C /usr/local/man/cat\(**[.Z] .TP .C /usr/contrib/man/cat\(**[.Z] .PD .SH AUTHOR .C fixman was developed by HP. .SH SEE ALSO catman(1M), chmod(1), expand(1), lp(1), man(1), mv(1), sed(1), environ(5). .\" .\" index@\f4fixman\f1 \- fix manual pages for faster viewing with \f4man\f1(1)@@@\f3fixman(1M)\f1 .\" index@\f4man\f1(1), fix manual pages for faster viewing with@@@\f3fixman(1M)\f1 .\" index@on-line manuals, fix pages for faster viewing with \f4man\f1(1)@@@\f3fixman(1M)\f1 .\" .\" toc@\f3fixman(1M)\f1:\0\0\f4fixman\f1@@@fix manual pages for faster viewing with man(1) .\" .\" fileset_database@fixman.1m USER-CMDS-MAN .\"========================================================= .\" (c) 1992 Hewlett-Packard Company. All Rights Reserved. .\" Author: Hewlett-Packard DMD .\"========================================================= .\" .\"@(#) $Header: fmt.1m,v 1.2 95/12/15 11:37:03 hmgr Exp $ .TA f .TH fmt 1M .SH NAME fmt \- format an .SM HP SCSI disk array .SM LUN .SH SYNOPSIS .C fmt .I device_file .SH DESCRIPTION .C fmt formats one .SM LUN of the .SM HP SCSI disk array associated with device file .IR device_file . The format will usually be a soft or zeroing format, in which the controller writes zeroes to the data area and parity area, if any, of the .SM LUN. .HP .B NOTE: The above should always be true of a sub-\c .SM LUN\c , but the controller might decide, based on certain conditions, to do a full format of a regular .SM LUN\c , which consists of sending a mode select and a media initialization command to the physical drive(s) in question, followed by zeroing the data and parity area, if any. The conditions which will cause a full format to be done are as follows: .IP 1. The controller received a Mode Select command which requires a drive sector size change. .IP 2. The controller received a Mode Select command which changed a parameter in the Format Device Page (0x03). .IP 3. The .SM LUN contains one or more failed drives. In this case only a certain subset of the drives containing the failed drives will be formatted. .IP 4. Either the FmtData or the CmpLst bit in the Format Unit .SM CDB is set. .SH RETURN VALUE .C fmt returns the following values: .RS 5 .TP .B " 0" Successful completion. .PD 0 .TP .B -1 Command failed. .PD .PP .RE .SH DIAGNOSTICS AND ERRORS Errors can originate from problems with: .RS .TP 3 \(bu .C fmt .TP \(bu .SM SCSI (device level) communications .TP \(bu system calls .RE .PP .SS Error messages generated by fmt: .TP .C "usage: fmt " An error in command syntax has occurred. Enter command again with all required arguments, in the order shown. .TP .C "fmt: device busy" .tr ~" To ensure that .C fmt does not modify a disk array that is being used by another process, .C fmt attempts to obtain exclusive access to the disk array. If the disk array is already opened by another process (for example, LVM \(em the Logical Volume Manager), a .RC ~ "device busy" ~ error message is returned by the driver. To eliminate the .RC ~ "device busy" ~ condition, determine what process has the device open. In the case of LVM, it is necessary to deactivate the volume group containing the array before formatting array .SM LUN\c s (see .CR vgchange (1M)). .tr ~~ .TP .C "fmt: LUN # too big" The .SM LUN number, which is derived from the device file name, is out of range. .TP .C "fmt: LUN does not exist" The addressed .SM LUN is not configured, and thus is not known to the array controller. .TP .C "fmt: Not a raw file" Utilities must be able to open the device file for raw access. .TP .C "fmt: Not an HP SCSI disk array" The device being addressed is not an HP SCSI disk array. .PP .SS SCSI (device level) communication errors: Sense data associated with the failed operation is printed. .PP .SS Error messages generated by system calls: .C fmt uses the following system calls: .IP .CR malloc() , .CR free() , .CR stat() , .CR open() , .CR close() , .CR read() , .CR write() , and .CR ioctl() . .PP Documentation for these .SM HP-UX system calls contains information about the specific error conditions associated with each call. .C fmt does not alter the value of .CR errno . The interpretation of .C errno for printing purposes is performed by the system utility .CR strerror() . .SH EXAMPLES .PP To format the .SM HP SCSI disk array .SM LUN .C /dev/rdsk/c2t0d0 on a Series 800: .IP .C "fmt /dev/rdsk/c2t0d0" .SH WARNING The .C fmt command will destroy all user data on the addressed .SM LUN. .SH DEPENDENCIES The HP C2425 and HP C2427 disk arrays are only supported on Series 700 systems running HP-UX version 9.0X. .PP The HP C2430 disk array is supported on Series 700 and 800 systems running HP-UX versions 9.0X and 10.0X. .SH AUTHOR .PP .C fmt was developed by .SM HP. .\" .\" index@\f4fmt\f1 \- format an \s-1HP SCSI\s+1 disk array \s-1LUN\s+1@@@\f3fmt(1M)\f1 .\" index@disk array, formatting a \s-1LUN\s+1 for@@@\f3fmt(1M)\f1 .\" .\" toc@\f3fmt(1M)\f1:\0\0\f4fmt\f1@@@format an \s-1HP SCSI\s+1 disk array \s-1LUN\s+1 .\" .\" fileset_database@fmt.1m SYS-ADMIN-MAN .\" $Header: fpkg2swpkg.1m,v 76.1 95/08/07 11:36:35 ssa Exp $ .\" -*-Nroff-*- .\" $Header: fpkg2swpkg.1m,v 76.1 95/08/07 11:36:35 ssa Exp $ .TA f .TH fpkg2swpkg 1M " " "Hewlett-Packard Company" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME .PP fpkg2swpkg \- Translate .C fpkg network media or Product Specification Files (PSFs) to SD .C swpackage PSFs. .PP .SH SYNOPSIS .C fpkg2swpkg .RC [ -m .IR media_type\| ] .RC [ -d .IR destination\| ] .IR fpkg_pathname .PP .SH DESCRIPTION The .C fpkg2swpkg command provides a way to translate existing .C fpkg Product Specification Files (PSFs) and .C fpkg -format network media into skeleton SD .C swpackage PSFs. .C fpkg keywords are converted to .C swpackage counterparts when available. .C swpackage keywords with no .C fpkg counterpart are included but commented out in the .C swpackage PSF. Manual edits and use of the .IR swpackage(1M) command complete the process of generating a .C swpackage -format depot from the .C fpkg information. .PP .SS Options .C fpkg2swpkg supports the following options: .RS .TP 15 .CI "-m media_type" Defines which .C fpkg media type to convert. Default .I media_type is .I psf. The supported media types are: .RS .TP 15 .CI psf Translate from an .C fpkg PSF. .TP .CI network Translate from an .C fpkg - format network media (netdist server). .RE .PP Note: the .C -m option requires the presence of the .C fpkg command which is only supported on HP-UX systems prior to 10.0. .RE .PP .RS .TP 15 .CI "-d destination" Defines the pathname of the new .C swpackage PSF. The default destination is .IR "./swpackage.psf." .RE .PP .SS Operands .PP The .C fpkg2swpkg command supports the following syntaxes for .I fpkg_pathname: .PP .IR "[relative_or_absolute_directory_path/]fpkg_PSF_filename" .PP Example: .C ./my_psf .PP .IR "/absolute_directory_path/fpkg_netdist_directory_name " .PP Example: .C /netdist/700 .PP The .C fpkg source type (file or directory) specified for .IR fpkg_pathname overrides the .IR media_type option. When the .C fpkg source is a file, .C fpkg2swpkg performs as described for PSF translation. When the .C fpkg source is a directory, .C fpkg2swpkg performs as described for network media translation. .PP .SH EXTERNAL INFLUENCES .PP .SS Environment Variables .PP None .PP .SS Signals .PP The .C fpkg2swpkg command catches the signals SIGQUIT and SIGINIT during initialization and parsing. If these signals are received, .C fpkg2swpkg prints a WARNING message and exits. All signals are ignored while the .C swpackage PSF is being built to ensure the integrity of the new PSF. .PP .SH OPERATION .PP .SS PSF translation .PP When the .C fpkg source is a PSF, .C fpkg2swpkg performs a line-by-line translation of the .C fpkg PSF. .PP .SS Network media translation .PP When the .C fpkg source is a directory, .C fpkg2swpkg first calls .C "fpkg -r" to create an .C fpkg PSF from the indicated .C fpkg -format network media. The command then performs a line-by-line translation of the newly generated .C fpkg PSF. .PP .SS Keyword Mappings .PP The following table summarizes .C fpkg keywords and their .C swpackage counterparts. Comments regarding keyword translation are included where necessary. .PP .ift \{ \0 .TS tab(@) box; cB| cB| cB| cB lI| l| l| l. fpkg Keyword @ Description @ swpackage Keyword @ Level = pn, partition_name @T{ name given to a logical grouping of filesets T}@ tag @ subproduct _ pd, partition_description @T{ partition/subproduct description T}@ title @ subproduct _ fn, fileset_name @ fileset name @ tag @ fileset _ fd, fileset_description @ fileset description @ title @ fileset _ fv, fileset_version @ fileset revision level @ revision @ fileset _ ff, fileset_flags: @ @ @ _ B @ kernel fileset @ is_kernel, is_reboot @ fileset _ C @T{ fileset is not locatable T}@T{ is_locatable (set to TRUE when no fileset in the partition has a "C" flag) T}@ fileset _ Y @T{ run rmfn before loading a fileset with the same name T}@ not avail. in SD@ _ D @T{ run the fileset's customize script after all filesets are loaded T}@ not available in SD@ _ H @T{ fileset is compatible only with HPPA-RISC architecture machines T}@T{ assumed - no swpackage keyword T}@ _ M @T{ fileset is compatible only with MC-680x0 [Series300/400] machines T}@T{ not applicable - SD runs on Series 700/800 machines only T}@ _ dep, fileset_dependency @T{ fileset(s) on which this fileset has a run-time dependency T}@T{ corequisite (includes the product name) T}@ fileset _ copyright @T{ path to fileset copyright file stored at the swpackage product level T}@ copyright@ product _ customize @T{ path to fileset configuration script T}@T{ configure (not guaranteed to work) T}@ fileset _ T{ decustomize with the check option T}@T{ path to fileset unconfiguration script, prevent removal option T}@T{ checkremove (not guaranteed to work) T}@ fileset _ decustomize @T{ path to fileset unconfiguration script T}@T{ unconfigure (not guaranteed to work) T}@ fileset _ T{ ffperm, fileset_file_permission T}@T{ permissions for all files in the fileset T}@ file_permissions @ fileset _ pr, pseudo_root @T{ directory where source files are located T}@ directory @ fileset _ F, Files @T{ file name(s): recursive (*) or individual T}@ file [* or ] @ fileset .TE .fi \} .ifn \{ .nf .C "fpkg Keyword Description swpackage Keyword Level" .PP pn, partition_name name given to a tag subproduct logical grouping of filesets .PP pd, partition/sub- title subproduct partition_description product description .PP fn, fileset_name fileset name tag fileset .PP fd, fileset description title fileset fileset_description .PP fv, fileset_version fileset revision revision fileset level .PP ff, fileset_flags: .PP B kernel fileset is_kernel, fileset is_reboot .PP C fileset is not is_locatable (set fileset locatable to TRUE when no fileset in the partition has a "C" flag .PP Y run rmfn before not available loading a fileset in SD with the same name .PP D run the fileset's not available customize script in SD after all filesets are loaded .PP H fileset is compa- assumed - no tible only with swpackage HPPA-RISC machines keyword .PP M fileset is compa- not applicable - tible only with SD runs on MC-680x0 [S300/ S700/800 400] machines machines only .PP dep, fileset(s) on corequisite fileset fileset_dependency which this file- (includes the set has a runtime product name) dependency .PP copyright path to fileset copyright product copyright file stored at the swpackage product level .PP customize path to fileset configure fileset configuration (not guar- script anteed to work) .PP decustomize with path to fileset checkremove fileset the check option unconfiguration (not guar- script, prevent anteed to removal option work) .PP decustomize path to fileset unconfigure fileset unconfiguration (not guar- script anteed to work) .PP ffperm, permissions for file_permissions fileset fileset_file_per- all files in mission fileset .PP pr, pseudo_root directory where directory fileset source files are located .PP F, Files file name(s): file [* or fileset recursive (*) or ] individual .PP .fi \} .PP The following .C fpkg keywords do not have .C swpackage counterparts. The .C fpkg2swpkg command issues a warning to indicate that the .C fpkg keyword is ignored. .PP .ift \{ \0 .TS tab(@) box; cB| cB lI| l. fpkg Keyword @ Description = sys, system_architecture_type@ system architecture type _ is, instruction_set @ instruction set _ fdperm, fileset_directory_permission @ fileset directory permission _ CDFinfo @ control_file for CDF clusters _ systemfile @ control_file to locate system files _ media_format @ media format version _ media_order order @ filesets are written to tape .TE .fi \} .ifn \{ .nf .C "fpkg Keyword Description " .PP sys, system_architecture_type system architecture type .PP is, instruction_set instruction set .PP fdperm, fileset_directory_permission fileset directory permission .PP CDFinfo control_file for CDF clusters .PP systemfile control_file for locating system files .PP media_format media format version .PP media_order order filesets are written to tape .fi \} .PP The following .C swpackage keywords have default settings. These defaults cannot be changed within .C fpkg2swpkg but can be edited manually in the new PSF. .PP .ift \{ \0 .TS tab(@) box; cB| cB| cB lI| l| l. SD Level.Keyword@ Default Setting @ Description = vendor.tag @ HP @ short vendor identifier _ vendor.title @ "Hewlett-Packard Company" @ full vendor name _ product.tag @ HP-UX10 @ short product identifier _ product.title @ "HP-UX update(1M) translated fileset" @ full product name _ product.architecture @ HP-UX_B.10.00_700/800 @T{ supported hardware and operating systems T} _ product.machine_type @ 9000/[678]?? @T{ supported machine types (uname -m) T} _ product.os_name @ HP-UX @T{ supported operating systems (uname -s) T} _ product.os_release @ ?.10.* @T{ supported operating system releases (uname -r) T} .TE .fi \} .ifn \{ .nf .C "SD Level.Keyword Default Setting Description " .PP vendor.tag HP short vendor identifier .PP vendor.title "Hewlett-Packard full vendor name Company" .PP product.tag HP-UX10 short product identifier _ product.title "HP-UX update(1M) full product name translated fileset" .PP product.architecture HP-UX_B.10.00_700/800 supported hardware and operating systems .PP product.machine_type 9000/[678]?? supported machine types (uname -m) .PP product.os_name HP-UX supported operating systems (uname -s) .PP product.os_release ?.10.* supported operating system releases (uname -r) .fi \} .PP .SS Fileset Dependencies .PP All .IR update(1M) dependencies translate to Software Distributor (SD) corequisites. The .C swpackage corequisite keyword contains the fully-qualified software specification including the product revision number. The fileset revision number, which was used in .C update, is not included. The revision number can be changed manually if necessary. .SS update Script Handling The .C fpkg2swpackage command writes SD control scripts which are wrappers calling the .C update customize and decustomize scripts. This method of script conversion is not preferred and is not guaranteed to work. Nothing but the most trivial scripts will execute correctly in SD environments without manual conversion. .PP The pathname to the .C update script, used by the SD control script, varies with the type of the fpkg source specified and is one of the following: .RS .TP 3 .C "[directory_path/]customize" This is the pathname given in the .C fpkg PSF. It is used when the .C fpkg source is a PSF. .TP .C "fpkg_pathname + /product/system//(de)customize" This is the pathname created while parsing the network media. It is used when the .C fpkg source is a directory. .RE .PP The following table summarizes the wrappers written by the .C fpkg2swpkg command. .PP .ift \{ \0 .TS tab(@) box; cB| cB| cB lI| l| l. update script name @ SD script name @ SD script contents = customize @ configure @T{ "customize"_pathname HP-PA exit $? T} _ T{ decustomize with the check option T}@ checkremove @T{ "decustomize"_pathname HP-PA check exit $? T} _ decustomize @unconfigure @T{ "decustomize"_pathname HP-PA exit $? T} .TE .fi \} .ifn \{ .nf .C "update script name SD script name SD script contents" .PP customize configure "customize"_pathname HP-PA exit $? .PP decustomize with checkremove "decustomize"_pathname the check option HP-PA check exit $? .PP decustomize unconfigure "decustomize"_pathname HP-PA exit $? .fi \} .PP .SH HARDWARE REQUIREMENTS .PP Supported on HP-UX 9.X and 10.0, Series 700 and Series 800. .PP .SH SOFTWARE REQUIREMENTS .PP Supported on HP-UX 9.X and 10.0, Series 700 and Series 800. .PP The .C fpkg command must be on the system to run the .C fpkg2swpkg command when the .C fpkg source is a directory. .PP .SH PROCEDURES .PP .SS Initial Translation .PP Execute the .C fpkg2swpkg command as shown in "EXAMPLES" below. .PP .SS Product Script Conversion .PP Edit/create scripts for compatibility in SD environments. .PP .SS swpackage PSF Completion .PP Manually edit the generated swpackage PSF to change default settings and supply information not provided by the .C fpkg PSF. .PP .SS SD Depot Creation .PP Execute the .C swpackage(1M) command to build an SD depot. If the default .C swpackage PSF destination was used when .C fpkg2swpkg was invoked, type: .PP .C "swpackage -s ./swpackage.psf" .PP .SH RETURN VALUES The .C fpkg2swpkg command returns: .PP 0 Success .PP 1 Failure .PP 2 Warning (interrupt warning) .PP .SH LIMITATIONS .PP .SS Subproducts .PP Subproduct definitions are specific to the command instance. Separate invocations of .C fpkg2swpkg may place the same filesets in subproducts with different names. To avoid this problem, run the tool on an entire partition, not just on a fileset. To fix this problem after running .C fpkg2swpkg, alter the subproduct contents line of the .C swpackage PSF to show all filesets which SHOULD be in the subproduct even though they didn't show up in this instance. .PP .SS CDFinfo Keyword .PP SD does not support CDFs. .C fpkg2swpkg ignores the existence of CDFs. Any actions in customize and decustomize scripts that use or create CDFs must be manually removed. .PP .SS Systemfile Keyword .PP Files identified by the systemfile keyword are not automatically included in the .C swpackage PSF and must be manually added with the .C swpackage file keyword if they are needed by a wrapped customize or decustomize script. If the calling script is not updated for SD, the systemfile may be delivered under .CR /system// as is the case for .C update. If the calling script is rewritten for SD environments, the systemfile should also be rewritten and delivered via the .C swpackage .I control_file keyword. .PP .SS Scripts .PP .C fpkg2swpkg does not translate the functionality of .C update customize and decustomize scripts. Scripts must be tested for 10.0 compatibility by the developer. In particular, scripts which contain DUX-specific commands and paths will not work. .PP .SS Dependency Revision .PP .C swpackage dependencies are based on product revision numbers, not fileset revision numbers as was the case with .CR fpkg . .PP .SH EXAMPLES .PP .SS Command Line .PP Write a .C swpackage PSF named .I ./swpackage.psf from an .C fpkg PSF for the Pascal product: .IP .CI "fpkg2swpkg /build/prog_lang/pascal.psf" .PP Write a .C swpackage PSF named .C /sw_build/pascal.sw_psf from an .C fpkg PSF for the Pascal product: .IP .CI "fpkg2swpkg -d /sw_build/pascal.sw_psf /build/prog_lang/ pascal.psf" .PP Write a .C swpackage PSF named .CR ./swpackage.psf from an .C fpkg network media named .I prog_lang: .IP .CI "fpkg2swpkg -m network /build/prog_lang" .PP Write a .C swpackage PSF named .CR /sw_build/prog_lang.sw_psf from an .C fpkg network media named .CR prog_lang : .IP .CI "fpkg2swpkg -m network -d sw_build/prog_lang.sw_psf / build/prog_lang" .PP .SS PSF .PP The first file listing below is an .C fpkg PSF. The second file shown is its .C swpackage counterpart after being translated by with the .C fpkg2swpkg command. Note that the .C swpackage PSF would benefit from manual editing before being packaged for SD environments. .PP .SH Sample fpkg PSF .PP .RS .ifn .ft3 .ift .ft4 .nf #fpkg PSF file for an update 9.0 set of filesets with one partition #Partition specification pn Manager pd Manager Subset of SD #Fileset specifications fn Controllers fd SD Executable Commands fv A.B10.01.0A ff B is PA_RISC_1_0 sys S600,S700,S800 dep Controllrs-man A.B.10.01.0A copyright /build/s700/mfg/data/sdu.copyright customize /build/s700/mfg/scripts/customize decustomize /build/s700/mfg/scripts/decustomize ffperm bin bin 0555 pr /build/s700/mfg=/opt/sw Files bin/swinstall bin/swcopy data/install.defs newconfig/defaults/swinstall data/install.defs /var/adm/sw/defaults/swinstall fn Controllers-man fd SD Executables Manual Pages fv A.B10.01.0A pr /build/s700/mfg/man=/opt/sw/man Files * .PP .SH Sample swpackage PSF .PP .ifn .ft3 .ift .ft4 .nf # Purpose: swpackage PSF file translated from your fpkg PSF file # Description: This file is a functional PSF translated from your fpkg # PSF. All possible keywords are given. The keywords # that did not have a counterpart in your fpkg PSF are # commented (with minor exceptions). For the following # exceptions, the keywords are filled in with defaults: # vendor.tag, vendor.title, product.tag, product.title, # product.architecture, product.machine_type, # product.os_name, product.os_release. # In general: # * a PSF can define 0 or more attributes for the # target depot. # * a PSF can define 1 or more products. # * a product can contain 0 or more subproducts. # * a product can contain 1 or more filesets. # * a fileset can contain 0 or more files. # Depot definition: # All depot attributes are OPTIONAL, except for the products which # must be contained within it. The other attributes are intended # for depots being distributed on CD-ROM or tape. depot # tag depot_ID # An identifier for the depot # title "short description" # A name for the depot # number "depot_partnumber" # The part number for the depot # description "the in-line description of the depot" # A multi-line desc. of the depot # copyright &1 | tee " "filename" .PP Find filesets that have not been used in the past 90 days: .IP .CR "/usr/sbin/freedisk -a 90" .SH WARNINGS .PP Removing the kernel build filesets in phase two can result in unresolved fileset dependencies. This means that .CR swverify (see .IR swverify (1M)) will indicate errors, unless the appropriate options are used to ignore missing dependencies. .PP Be careful when using the .CI -a \0n option. Small values of .I n might cause infrequently used filesets to be discovered as unused. .SH AUTHOR .CR freedisk was developed by HP. .SH FILES .TP 28 /var/adm/sw/krn_rmvd.log log of removed kernel-build filesets .PD 0 .TP /var/adm/sw/swremove.log log of .C swremove actions .TP /var/adm/sw/swagent.log log of .CR swagent actions .PD .SH SEE ALSO find(1), swinstall(1M), swmodify(1M), swremove(1M), swverify(1M), and the manual .IR "Managing HP-UX Software with SD-UX" (HP Part No. B2355-90054). .\" toc@\f3freedisk(1M)\f1:\0\0\f4freedisk\f1@@@recover disk space .\" index@\f4freedisk\f1 \- recover disk space@@@\f3freedisk(1M)\f1 .\" index@\f1recover disk space@@@\f3freedisk(1M)\f1 .\" index@\f1disk space, recover@@@\f3freedisk(1M)\f1 .\" index@\f1space, recover disk@@@\f3freedisk(1M)\f1 .\" $Header: fsadm.1m,v 78.1 96/01/04 15:06:47 ssa Exp $ .TA f .TH fsadm 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fsadm (generic) - a file system administration command .SH SYNOPSIS .C /usr/sbin/fsadm .RC [ -F .IR FStype ] .RC [ -V ] .RC [ -o .IR specific_options ] .IR special .SH DESCRIPTION The .CR fsadm command is designed to perform selected administration tasks on file systems. These tasks may differ between file system types. .IR special is a device file containing an unmounted file system. However, if the file system is of the type that provides online administration capabilities the .IR special could be a .IR directory. .IR directory must be the root of a mounted file system. .PP Only a superuser can invoke .CR fsadm . .PP .SS Options .TP 15 .CI \-F \0FStype Specify the file system type on which to operate (see .IR fstyp (1M) and .IR fs_wrapper (5)). If this option is not included on the command line, then the file system type is determined from the file .CR /etc/fstab by matching each .I special with an entry in that file. If there is no entry in .CR /etc/fstab , then the file system type is determined from the file .CR /etc/default/fs . .TP .CI -o \0specific_options Specify options specific to each file system type. .I specific_options is a list of comma separated suboptions and/or keyword/attribute pairs intended for a specific .IR FStype -specific module of the command. See the file system specific manual entries for a description of the .I specific_options supported, if any. .TP .CR -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SH EXAMPLES Convert a .CR HFS file system from a .CR nolargefiles file system to a .CR largefiles file system: .IP .C "fsadm -F hfs -o largefiles /dev/vg02/lvol1" .PP Display .CR HFS relevant file system statistics: .IP .C "fsadm -F hfs /dev/vg02/lvol1" .SH FILES .TP 25 .PD 0 .CR /etc/fstab Static information about the systems .PD .SH SEE ALSO .RI fsadm_ FStype (1M), fsck(1M), fstab(4), fs_wrapper(5). .\" .\" index@\f4fsadm\f1 \- file system administration command@@@\f3fsadm(1M)\f1 .\" index@\f1file system administration command@@@\f3fsadm(1M)\f1 .\" index@\f1administration command for file system@@@\f3fsadm(1M)\f1 .\" .\" toc@\f3fsadm(1M)\f1:\0\0\f4fsadm\f1@@@file system administration command .\" $Header: fsadm_hfs.1m,v 78.2 96/01/04 15:08:30 ssa Exp $ .TA f .TH fsadm_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fsadm (hfs) - an HFS file system administration command .SH SYNOPSIS .C /usr/sbin/fsadm .RC [ -F .CR hfs ] .RC [ -V ] .RC [ -o .IR specific_options ] .IR special .SH DESCRIPTION The .CR fsadm command is designed to perform selected administration tasks on a HFS file systems. .IR special is a device file containing an unmounted file system. .PP Only a superuser can invoke .CR fsadm . .PP .SS Options .TP 15 .CI \-F \0hfs Specify the HFS file system type. .TP .CI \-o \0specific_options Specify a list of comma separated suboptions and/or keyword/attribute pairs from the list below. The following .IR specific_options are valid on HFS file systems. .RS .RS .TP 15 .CR largefiles Converts a .CR nolargefiles file system to a .CR largefiles file system. The file system should be unmounted and must be in a clean state (see .IR fsck (1M)). A .CR largefiles file system supports file sizes greater than 2 gigabytes. .TP 15 .CR nolargefiles Converts a .CR largefiles file system to a .CR nolargefiles file system. The file system should be umounted and must be in a clean state (see .IR fsck (1M)). All .CR largefiles should be purged from the file system for the conversion to succeed. .RE .RE .TP .CR -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SH DIAGNOSTICS Error and warning messages may originate from .CR fsadm and .CR fsck . See .IR fsadm (1M) or .IR fsck (1M) to interpret the error and warning messages. .SH EXAMPLES Convert a .CR nolargefiles HFS file system to a .CR largefiles HFS file system: .IP .C "fsadm -F hfs -o largefiles /dev/vg02/lvol1" .PP Convert a .CR largefiles HFS file system to a .CR nolargefiles file system: .IP .C "fsadm -F hfs -o nolargefiles /dev/vg02/lvol1" .PP Display relevant HFS file system statistics: .IP .C "fsadm -F hfs /dev/vg02/lvol1" .SH WARNINGS .PP The size of a file system will impact the performance of the .CR fsadm command. .PP During conversion from largefiles file system to a nolargefiles file system .CR fsadm scans the entire file system for a large file. This functionality degrades the performance of the .CR fsadm command. .SH FILES .TP 25 .PD 0 .CR /etc/fstab Static information about the systems .PD .SH SEE ALSO fsadm(1M), fsck(1M), fstab(4), fs_wrapper(5). .\" .\" index@\f4fsadm_hfs\f1 \- HFS file system administration command@@@\f3fsadm_hfs(1M)\f1 .\" index@\f1file system administration command@@@\f3fsadm_hfs(1M)\f1 .\" index@\f1administration command for HFS file system@@@\f3fsadm_hfs(1M)\f1 .\" index@\f1HFS file system administration command@@@\f3fsadm_hfs(1M)\f1 .\" .\" toc@\f3fsadm_hfs(1M)\f1:\0\0\f4fsadm_hfs\f1@@@HFS file system administration command .\" $Header: fsck.1m,v 72.6 94/11/29 05:53:59 ssa Exp $ .TA f .TH fsck 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fsck (generic) \- file system consistency check and interactive repair .SH SYNOPSIS .CR /usr/sbin/fsck .RC [ -F .IR FSType ] .RC [ -m ] .RC [ -V ] .RI [ special ] .PP .CR /usr/sbin/fsck .RC [ -F .IR FSType ] .RC [ -o .IR FSspecific-options ] .RC [ -V ] .RI [ special \0...] .PP .SH DESCRIPTION The .CR fsck command audits and interactively repairs inconsistent conditions for HP-UX file systems on mass storage device files identified by .IR special . If the file system is consistent, the number of files on that file system and the number of used and free blocks are reported. If the file system is inconsistent, .CR fsck provides a mechanism to fix these inconsistencies, depending on which form of the .CR fsck command is used. .PP .I special represents a special device (e.g., .CR /dev/rdsk/c1d0s8 ). .SS Options .CR fsck recognizes the following options: .RS .TP 15 .CI -F \0FStype Specify the file system type on which to operate (see .IR fstyp (1M) and .IR fs_wrapper (5)). If this option is not included on the command line, then the file system type is determined from the file .CR /etc/fstab by matching .I special with an entry in that file. If there is no entry in .CR /etc/fstab , then the file system type is determined from the file .CR /etc/default/fs . .TP .CR -m Perform a sanity check only. .CR fsck will return 0 if the file system is suitable for mounting. If the file system needs additional checking, the return code is 32. If the file system is mounted, the return code is 33. Error codes larger than 33 indicate that the file system is badly damaged. .TP .CI -o \0FSspecific-options Specify options specific to each file system type. .I FSspecific-options is a list of suboptions and/or keyword/attribute pairs intended for a file-system-specific version of the command. See the file-system-specific manual entries for a description of the .I specific_options supported, if any. .TP .CR -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SH RETURN VALUES The following values are returned by the .CR -m option to .CR fsck : .RS .TP .CR \00 Either no errors were detected or all errors were corrected. .TP .CR 32 The file system needs additional checking. .TP .CR 33 The file system is mounted. .RE .PP Return values greater that .CR 33 indicate that file system is badly corrupted. File system specific versions of .CR fsck will have their own additional return values (see .RI fsck _FSType (1M)). .SH WARNINGS This command may not be supported for all file system types. .SH FILES .TP 25 .CR /etc/default/fs Specifies the default file system type .PD 0 .TP .CR /etc/fstab Default list of file systems to check .PD .SH STANDARDS CONFORMANCE .CR fsck ": SVID3" .SH SEE ALSO .RI fsck_ FSType (1M), mkfs(1M), newfs(1M), fstab(4), fs_wrapper(5). .\" .\" index@\f4fsck\f1 \- file system consistency check and interactive repair (generic)@@@\f3fsck(1M)\f1 .\" index@\f1file system consistency check and interactive repair (generic)@@@\f3fsck(1M)\f1 .\" index@\f1repair file system interactively and check consistency (generic)@@@\f3fsck(1M)\f1 .\" index@\f1check file system consistency and interactively repair (generic)@@@\f3fsck(1M)\f1 .\" .\" toc@\f3fsck(1M)\f1:\0\0\f4fsck\f1@@@file system consistency check and interactive repair (generic) .\" $Header: fsck_hfs.1m,v 76.1 95/07/24 15:26:34 ssa Exp $ .TA f .TH fsck_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fsck (hfs) \- .SM HFS file system consistency check and interactive repair .SH SYNOPSIS .CR /usr/sbin/fsck .RC [ -F .CR hfs ] .RC [ -m ] .RC [ -V ] .RI [ special ] .PP .CR /usr/sbin/fsck .RC [ -F .CR hfs ] .RC [ -c .IR size ] .RC [ -f ] .RC [ -p \(or -P ] .RC [ -V ] .RI [ special \0...] .PP .CR /usr/sbin/fsck .RC [ -F .CR hfs ] .RC [ -b .IR blocknum ] .RC [ -c .IR size ] .RC [ -f ] .RC [ -n \(or -N \(or\c .CR -y \(or -Y ] .br .ifn \0\0\0\0\0\0\0\0\0\0\0\0\0\0 .ift \0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0 .RC [ -q ] .RC [ -V ] .RI [ special \0...] .SH DESCRIPTION The .CR fsck command audits and repairs inconsistent conditions for .SM HFS file systems on mass storage device files identified by .IR special . If the file system is consistent, the number of files on that file system and the number of used and free blocks are reported. If the file system is inconsistent, .CR fsck provides a mechanism to fix these inconsistencies, depending on which form of the .CR fsck command is used. .PP .I special represents a special device (e.g., .CR /dev/rdsk/c1d0s8 ). .PP If the target device is a swap device, .CR fsck does not continue to process. .CR fsck also checks the target device to ensure a mounted file system is not being checked. If a mounted device is specified but the .CR -f option is omitted, .CR fsck prompts the user for a response. .PP If the .CR -p \(or -P option is used and .I special is not specified, .CR fsck reads the pass numbers in .CR /etc/fstab to determine which groups of disks to inspect in parallel, taking maximum advantage of I/O overlap to process the file systems as quickly as possible. The .CR -p \(or -P option is normally used in the script .CR /sbin/bcheckrc during automatic reboot. .PP Normally, the root file system is checked on pass 1, and other "root" (section 0) file systems on pass 2. Other small file systems are checked on separate passes (such as the section 4 file systems on pass 3 and the section 7 file systems on pass 4), and finally the large user file systems are checked on the last pass (for example, pass 5). A pass number of 0 or a type which is neither .CR rw nor .CR ro in .CR /etc/fstab causes a file system not to be checked. If the optional fields are not present on a line in .CR /etc/fstab , .CR fsck processes the file system on such lines sequentially after all eligible file systems with positive pass numbers have been processed. .PP The inconsistencies that .CR fsck with the .CR -p \(or -P option corrects are shown below. These are inconsistencies that are correctable without data loss. If it encounters other inconsistencies, it exits with an abnormal return status. For each corrected inconsistency, one or more lines are printed identifying the file system on which the correction will take place and the nature of the correction. Correctable inconsistencies are limited to the following: .RS .TP 3 \(bu Unreferenced inodes .PD 0 .TP \(bu Unreferenced continuation inodes (see .IR inode (4)) .TP \(bu Unreferenced pipes and FIFOs .TP \(bu Link counts in inodes too large .TP \(bu Missing blocks in the free list .TP \(bu Blocks in the free list also in files .TP \(bu Counts in the superblock wrong. .PD .RE .PP The .CR -P option operates in the same manner as the .CR -p option except that cleanly unmounted file systems are not checked (see .IR fsclean (1M)). This can greatly decrease the amount of time required to reboot a system that was brought down cleanly. .PP If the .CR -p \(or -P option is not specified, the pass numbers are ignored and the file systems are checked interactively in the order they are listed in .CR /etc/fstab . .PP Without the .CR -p \(or -P option, .CR fsck prompts for concurrence before each correction is attempted when the file system is inconsistent. It should be noted that some corrective actions result in a loss of data. The amount and severity of data loss can be determined from the diagnostic output. The default action for each consistency correction is to wait for the operator to respond .CR yes or .CR no . If the operator does not have write permission, .CR fsck defaults to a .CR -n action. .SS Options .CR fsck recognizes the following options: .RS .TP 10 .CR "-F hfs" Specify the .SM HFS file system. .TP .CI -c " size" Set the size of the buffer cache which .CR fsck uses to cache disk blocks. .IR size is the number of cache blocks, and is between 0 and 100 inclusive. The most common use of this option is .CR "-c 0" to disable all caches, thus reducing memory usage. .TP .CI -b " blocknum" Use the specified .IR blocknum as the superblock for the file system. An alternate superblock can usually be found at block .CR ((SBSIZE+BBSIZE)/DEV_BSIZE) , typically block 16. .CR DEV_BSIZE is defined in .CR . You can also find a list of alternate superblocks in .CR /var/adm/sbtab (see .IR mkfs (1M)). .TP .CR -f Force .CR fsck to check a mounted file system. .TP .CR -m Perform a sanity check only. Verify whether .IR special is mounted, or needs additional checking. Refer to the RETURN VALUE section for more information. .TP .CR -n \(or -N Assume a .CR no response to all questions asked by .CR fsck about repairing a file system. Do not open the file system for writing. .TP .CR -p "Preen" the file system. Proceed to process and repair file systems without user interaction, as described above. Exit immediately if there is a problem requiring intervention. .TP .CR -P Same as .CR -p except that cleanly unmounted file systems are not checked. .TP .CR -q Quiet. Do not print size-check messages in Phase 1. Unreferenced fifos are silently removed. If .CR fsck requires it, counts in the superblock and cylinder groups are automatically fixed. .TP .CR -V Echo the completed command line, but perform no other actions. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .TP .CR -y \(or -Y Assume a .CR yes response to all questions asked by .CR fsck about repairing a file system. This should be used with great caution, because this is a free license to continue after essentially unlimited trouble has been encountered. .RE .PP .ne 10 In all cases, .CR fsck checks the following inconsistencies: .RS .TP 3 .PD 0 \(bu Blocks claimed by more than one inode or the free list. .TP \(bu Blocks claimed by an inode or the free list outside the range of the file system. .TP \(bu Incorrect link counts. .TP \(bu Size checks: .RS .RS .TP 3 \(mi Directory size not of proper format. .RE .RE .TP \(bu Bad inode format. .TP \(bu Blocks not accounted for anywhere. .TP \(bu Directory checks: .RS .RS .TP 3 \(mi File pointing to unallocated inode. .TP \(mi Inode number out of range. .RE .RE .TP \(bu Superblock checks: .RS .RS .TP 3 \(mi More blocks for inodes than there are in the file system. .RE .RE .TP \(bu Bad free block list format. .TP \(bu Total free block and/or free inode count incorrect. .TP \(bu Invalid continuation inode number in a primary inode. .RE .PD .PP Orphaned files and directories (allocated but unreferenced) are, with the operator's concurrence, reconnected by placing them in the .CR lost+found directory. The name assigned is the inode number. The only restriction is that the directory .CR lost+found must already exist in the root of the file system being checked, and must have empty slots in which entries can be made. This is accomplished by making .CR lost+found , copying a number of files to the directory, then removing them before .CR fsck is executed. .PP Unreferenced continuation inodes are removed with the .CR -p option, since they do not refer back to the primary inode. When a primary inode contains an invalid continuation inode number, the continuation inode number should be cleared (that is, set to 0). This is not done automatically (with the .CR -p option), because access control list information may have been lost and should be corrected. .PP After .CR fsck has checked and fixed the file system, it stores the correct .CR fs_clean flag in the superblock if it is not already there. For a nonroot file system, .CR FS_CLEAN is stored there. For the root file system, which is mounted at the time of the .CR fsck , no changes are required to the superblock if no problems were found and .CR FS_OK was already set. .PP Checking the raw device is almost always faster. .SH RETURN VALUE .CR fsck returns the following values: .RS .TP .CR \00 Either no errors were detected or all errors were corrected. .TP .CR \04 Root file system errors were corrected. The system must be rebooted. .TP .CR \08 Some uncorrected errors exist on one or more of the file systems checked, there was a syntax error, or some other operational error occurred. .TP .CR 12 A signal was caught during processing. .TP .CR 32 The file system is unmounted and needs additional checking. .TP .CR 33 The file system is mounted. .TP .CR 34 The file system is damaged. .RE .SH WARNINGS .CR fsck should not be run on mounted file systems or on the root device. If you do run on mounted file systems, be sure the system is in single-user state (see .IR shutdown (1M)). .PP The special case of the .CR -c option, .CR "-c 0", will disable all internal caches, which will reduce memory usage but may impact performance. .PP The .CR -F option, from prior releases, has been replaced by the .CR -f option. .SH AUTHOR .CR fsck was developed by HP, AT&T, the University of California, Berkeley. .SH FILES .TP 22 .CR /etc/fstab Default list of file systems to check. .TP .CR /var/adm/sbtab List of locations of the superblocks for file systems. The .CR mkfs command appends entries to this file. .SH STANDARDS CONFORMANCE .CR fsck ": SVID3" .SH SEE ALSO fsck(1M), dumpfs(1M), fsclean(1M), mkfs(1M), newfs(1M), shutdown(1M), fstab(4), fs(4), inode(4), fs_wrapper(5), acl(5). .\" .\" index@\f4fsck\f1 \- file system consistency check and interactive repair@@@\f3fsck(1M)\f1 .\" index@\f1file system consistency check and interactive repair@@@\f3fsck(1M)\f1 .\" index@\f1repair file system interactively and check consistency@@@\f3fsck(1M)\f1 .\" index@\f1check file system consistency and interactively repair@@@\f3fsck(1M)\f1 .\" .\" toc@\f3fsck(1M)\f1:\0\0\f4fsck\f1@@@file system consistency check and interactive repair .\" .\" $Header: fsck_vxfs.1m,v 78.2 96/02/13 11:46:38 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .so /usr/share/lib/macros/vxfs.an .TA f .TH fsck_vxfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fsck (vxfs) \- check and repair a VxFS file system .SH SYNOPSIS .C /usr/sbin/fsck .RC [ \-F .CR vxfs ] .RC [ \-V ] .RC [ \-pPmnNyY ] .RC [ \-o .CR full,nolog ] .RI [ special ...\0] .SH DESCRIPTION The .C fsck utility checks VxFS file systems for consistency. Since VxFS records pending file system updates in an intent log, .C fsck typically runs an intent log replay, rather than a full structural file system check on a VxFS file system. .PP If .I special is not specified, .C fsck reads the table in .CR /etc/fstab , using the first field to determine which file system to check. .SS Options .TP 15 .CR \-F\0vxfs Specify the VxFS file system type. .TP .C \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .TP 15 .CR \-y | Y Assume a "yes" response to all questions asked by .CR fsck . Additionally, if the file system requires a full file system check after the log replay, or if the .C nolog suboption causes the log replay to be skipped and the file system is not clean, then a full file system check is performed. .TP 15 .CR \-n | N Assume a "no" response to all questions asked by .CR fsck ; do not open the file system for writing. Log replay is not performed. A full file system check is performed. .TP .C \-p Cause .C fsck to produce messages that identify the device being checked. .TP .C \-P With VxFS, .C \-P is used by .C fsck by default; it does not provide any functionality. With other file system types, .CR \-P may be used for optional functionality. .TP .C \-o Specify VxFS file system specific options. These options can be a combination of the following in a comma-separated list: .RS .TP .C full Perform a full file system check. The default is to perform an intent log replay only. Since the VxFS file system maintains an intent log, a complete check is generally not required. If the file system detects damage or the log replay operation detects damage, an indication that a complete check is required is placed in the super-block, and a full check is performed. .TP .C nolog Do not perform log replay. This option may be used if the log area was physically damaged. .RE .PP .ne 15 When a full check is performed, the following inconsistencies are checked: .sp .RS .PD 0 .TP 6 -- Blocks claimed by more than one inode or the free list. .TP 6 -- Blocks claimed by an inode outside the range of the file system. .TP 6 -- Incorrect link counts. .TP 6 -- Size checks: .IP "" 12 Incorrect number of blocks. .br Directory entry format. .TP 6 -- Bad inode format. .TP 6 -- Blocks not accounted for anywhere. .TP 6 -- Directory checks: .IP "" 12 File pointing to unallocated inode. .br Inode number out of range. .br Linkage to parent directory. .br Hash chain linkage. .br Free space count. .TP 6 -- Super-block checks: .IP "" 12 Checksum mismatch. .br More blocks for inodes than there are in the file system. .TP 6 -- Structural Files: .br .IP "" 12 Fileset headers. .br Object Location Table (OLT). .br Inode list files. .br Inode allocation summary files. .br Attribute files (including Access Control Lists). .br Attribute link counts. .TP 6 -- Bad free block list format. .TP 6 -- Total free block and/or free inode count incorrect. .RE .PD .PP Orphaned files and directories (allocated but unreferenced) are, with the user's concurrence, reconnected by placing them in the .C lost+found directory. The name assigned is the inode number. The only restriction is that the directory .C lost+found must already exist in the root of the file system being checked. .PP .SH "OUTPUT" Structural errors discovered during a full check are displayed on standard output. Responses required during a full check are read from standard input. .PP The following return codes are used for the .C \-m (generic) option for all devices other than the one used by the root file system: .RS .TP 0 The file system is unmounted and clean. .TP 32 The file system is unmounted and needs checking. .TP 33 The file system is mounted. .TP 34 The stat of the device failed. .TP Other The state could not be determined because of an error. .RE .PP The following return codes are used for the .C \-m (generic) option for the device used by the root file system: .RS .TP 0 The root file system is mounted read-only and is clean, or the root file system is mounted read/write and therefore doesn't need checking. .TP 32 The root file system is mounted read-only and needs checking. .TP 34 The stat of the device failed. .TP Other The state could not be determined because of an error. .RE .SH "ERROR/DIAGNOSTICS" All error messages that relate to the contents of a file system produced during a log replay are displayed on standard output. All I/O failures and exit messages are displayed on standard error output. .SH "NOTES" Checking the raw device is almost always faster. .PP A full file-system check will always perform any pending extended-inode operations, generating various messages, without operator interaction. If a structural flaw is detected, the .C VX_FULLFSCK flag will be set on the file system, without operator interaction. If .C fsck was not invoked with the .C \-y option, it must be reinvoked with the .C \-y or .C \-o full option to perform a full .CR fsck . .PP If the .C \-o full flag is used on a clean file system, .C fsck will perform a log replay first, and since the .C VX_FULLFSCK flag is set, it will not update the inode and extent maps before performing the full .CR fsck , so it will report inconsistencies. Use the .C \-n option to verify file-system inconsistency. .SH FILES .TP 20 .CR /etc/fstab Default list of file systems to check. .SH "SEE ALSO" fsck(1M), mkfs(1M), ncheck(1M). .\" .\" toc@\f3fsck_vxfs(1M)\f1:\0\0\f(CWfsck\f1@@@check and repair VxFS file systems .\" .\" index@\f(CWfsck_vxfs\f1 \- check and repair VxFS file system@@@\f3fsck_vxfs(1M)\f1 .\" index@\f(CWfsck\f1 \- check and repair VxFS file system@@@\f3fsck_vxfs(1M)\f1 .\" .\" index@\f1check and repair VxFS file system@@@\f3fsck_vxfs(1M)\f1 .\" index@\f1repair VxFS file system@@@\f3fsck_vxfs(1M)\f1 .\" index@\f1VxFS file system, check and repair@@@\f3fsck_vxfs(1M)\f1 .\" index@\f1VxFS file system, repair@@@\f3fsck_vxfs(1M)\f1 .\" index@\f1file system, check and repair VxFS@@@\f3fsck_vxfs(1M)\f1 .\" index@\f1file system, repair VxFS@@@\f3fsck_vxfs(1M)\f1 .\" .\" $Header: fsclean.1m,v 72.6 94/11/29 05:54:43 ssa Exp $ .TA f .TH fsclean 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fsclean \- determine the shutdown status of HFS file systems .SH SYNOPSIS .C /sbin/fsclean .RC [ -q\| ] .RC [ -v\| ] .RI [ \|special \ ...\|] .SH DESCRIPTION The .C fsclean command determines the shutdown status of the HFS file system specified by .I special or, in the absence of .IR special , the file systems listed in .C /etc/fstab of type .C hfs with the .CR rw , .CR default , or .C ro options set. All optional fields in .C /etc/fstab must be present for .C fsclean to be able to check each file system. .PP .C fsclean reads the superblock to determine whether the file system's last shutdown was done correctly, and returns one of the following values: .RS .TP 5 .B 0 All of the checked file systems were shut down correctly. .TP .B 1 One or more checked file systems were not shutdown correctly, implying that .C fsck should be run (see .IR fsck (1M)). .TP .B 2 Other error (such as .CR "cannot open the specified device file" ). .RE .PP The .C fsclean command is usually silent. .SS Options: .TP 10 .C -q Check quotas. Instead of checking the file system shutdown status, .C fsclean checks the validity of disk quota statistics. This option is useful for determining whether .C quotacheck should be run (see .IR quotacheck (1M)). If .I special is not provided, then all file systems in .C /etc/fstab of type .C hfs with the .C rw (or .CR default ) and .C quota options are checked. .TP .C -v Be verbose. Prints the status of each file system checked. .SH DEPENDENCIES .C fsclean only operates on HFS file systems. .SH AUTHOR .C fsclean was developed by HP. .SH FILES .TP 25 .CR /etc/fstab Default list of file systems to check .SH SEE ALSO dumpfs(1M), fsck(1M), fsck_hfs(1M), mount(1M), quotacheck(1M), quotacheck_hfs(1M), reboot(1M), fstab(4). .\" .\" index@\f4fsclean\f1 \- determine shutdown status of specified file system@@@\f3fsclean(1M)\f1 .\" index@shutdown status of specified file system, determine@@@\f3fsclean(1M)\f1 .\" index@clean file system at last system shutdown, test for@@@\f3fsclean(1M)\f1 .\" index@file system clean at last system shutdown, test for@@@\f3fsclean(1M)\f1 .\" index@shutdown, test for file system clean at last@@@\f3fsclean(1M)\f1 .\" index@quota status of specified file system, determine disk@@@\f3fsclean(1M)\f1 .\" index@disk quota status of specified file system, determine@@@\f3fsclean(1M)\f1 .\" .\" toc@\f3fsclean(1M)\f1:\0\0\f4fsclean\f1@@@determine shutdown status of specified file system .\" .\" fileset_database@fsclean.1m SYS-ADMIN-MAN .\" .\" links@fsclean.1m fsclean_hfs.1m .\" $Header: fsclean.1m,v 72.6 94/11/29 05:54:43 ssa Exp $ .TA f .TH fsclean 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fsclean \- determine the shutdown status of HFS file systems .SH SYNOPSIS .C /sbin/fsclean .RC [ -q\| ] .RC [ -v\| ] .RI [ \|special \ ...\|] .SH DESCRIPTION The .C fsclean command determines the shutdown status of the HFS file system specified by .I special or, in the absence of .IR special , the file systems listed in .C /etc/fstab of type .C hfs with the .CR rw , .CR default , or .C ro options set. All optional fields in .C /etc/fstab must be present for .C fsclean to be able to check each file system. .PP .C fsclean reads the superblock to determine whether the file system's last shutdown was done correctly, and returns one of the following values: .RS .TP 5 .B 0 All of the checked file systems were shut down correctly. .TP .B 1 One or more checked file systems were not shutdown correctly, implying that .C fsck should be run (see .IR fsck (1M)). .TP .B 2 Other error (such as .CR "cannot open the specified device file" ). .RE .PP The .C fsclean command is usually silent. .SS Options: .TP 10 .C -q Check quotas. Instead of checking the file system shutdown status, .C fsclean checks the validity of disk quota statistics. This option is useful for determining whether .C quotacheck should be run (see .IR quotacheck (1M)). If .I special is not provided, then all file systems in .C /etc/fstab of type .C hfs with the .C rw (or .CR default ) and .C quota options are checked. .TP .C -v Be verbose. Prints the status of each file system checked. .SH DEPENDENCIES .C fsclean only operates on HFS file systems. .SH AUTHOR .C fsclean was developed by HP. .SH FILES .TP 25 .CR /etc/fstab Default list of file systems to check .SH SEE ALSO dumpfs(1M), fsck(1M), fsck_hfs(1M), mount(1M), quotacheck(1M), quotacheck_hfs(1M), reboot(1M), fstab(4). .\" .\" index@\f4fsclean\f1 \- determine shutdown status of specified file system@@@\f3fsclean(1M)\f1 .\" index@shutdown status of specified file system, determine@@@\f3fsclean(1M)\f1 .\" index@clean file system at last system shutdown, test for@@@\f3fsclean(1M)\f1 .\" index@file system clean at last system shutdown, test for@@@\f3fsclean(1M)\f1 .\" index@shutdown, test for file system clean at last@@@\f3fsclean(1M)\f1 .\" index@quota status of specified file system, determine disk@@@\f3fsclean(1M)\f1 .\" index@disk quota status of specified file system, determine@@@\f3fsclean(1M)\f1 .\" .\" toc@\f3fsclean(1M)\f1:\0\0\f4fsclean\f1@@@determine shutdown status of specified file system .\" .\" fileset_database@fsclean.1m SYS-ADMIN-MAN .\" .\" links@fsclean.1m fsclean_hfs.1m .\" $Header: fsdb.1m,v 72.4 94/11/29 05:55:06 ssa Exp $ .TA f .TH fsdb 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fsdb \- file system debugger (generic) .SH SYNOPSIS .CR /usr/sbin/fsdb .RC [ \-F .IR FStype ] .RC [ \-o .IR specific_options ] .RC [ \-V ] .I special .SS Remarks Always execute the .CR fsck command (see .IR fsck (1M)) after running .CR fsdb . .SH DESCRIPTION The .CR fsdb command can be used to patch up a damaged file system after a crash. It is intended for experienced users only. The file system type to be debugged is specified as .IR FStype . Each file system type has a unique structure requiring different debugging capabilities. The manual entries for the file-system-specific .CR fsdb should be consulted before attempting any debugging or modifications. .SS Options and Arguments .CR fsdb recognizes the following options and arguments: .RS .TP 15 .I special The file name of the special file containing the file system. .TP .CI -F \0FStype Specify the file system type on which to operate (see .IR fstyp (1M) and .IR fs_wrapper (5)). If this option is not included on the command line, then the file system type is determined from the file .CR /etc/fstab by matching .I special with an entry in that file. If there is no entry in .CR /etc/fstab , then the file system type is determined from the file .CR /etc/default/fs . .TP .CI \-o \0specific_options Specify suboptions specific to each file system type. .I specific_options is a comma-separated list of suboptions and/or keyword/attribute pairs supported by the specific .IR FStype . .TP .CR \-V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from the .CR /etc/fstab file. This option allows the user to verify the command line. .SH EXAMPLES Invoke the file system debugger on HFS file system .CR /dev/dsk/c1d2s0 : .IP .C "fsdb \-F hfs /dev/dsk/c1d2s0" .PP Display a completed command line without executing the debugger: .IP .C "fsdb \-V /dev/dsk/c1d2s0" .PP The previous command might display: .IP .C "fsdb \-F hfs /dev/dsk/c1d2s0" .SH WARNINGS Only experienced users should use .CR fsdb . The failure to fully understand the usage of .CR fsdb and the file system's internal organization can lead to complete destruction of the file system and total loss of data. .SH AUTHORS .CR fsdb was developed by HP and AT&T. .SH FILES .TP 25 .CR /etc/default/fs Specifies the default file system type .TP .CR /etc/fstab Static information about the file systems .SH SEE ALSO fsck(1M), .RI fsdb_ FStype (1M), fstyp(1M), stat(2), fs_wrapper(5). .SH STANDARDS CONFORMANCE .PP .CR fsdb ": SVID3" .\" .\" index@\f4fsdb\f1 \- file system debugger (generic)@@@\f3fsdb(1M)\f1 .\" index@\f1damaged file system, patch up (generic)@@@\f3fsdb(1M)\f1 .\" index@\f1debug file system (generic)@@@\f3fsdb(1M)\f1 .\" index@\f1file system debugger (generic)@@@\f3fsdb(1M)\f1 .\" index@\f1generic file system debugger@@@\f3fsdb(1M)\f1 .\" index@\f1file system, damaged, patch up (generic)@@@\f3fsdb(1M)\f1 .\" index@\f1fix damaged file system (generic)@@@\f3fsdb(1M)\f1 .\" index@\f1patch up damaged file system (generic)@@@\f3fsdb(1M)\f1 .\" index@\f1crash, patch up damaged file system (generic)@@@\f3fsdb(1M)\f1 .\" index@\f1repair damaged file system (generic)@@@\f3fsdb(1M)\f1 .\" .\" toc@\f3fsdb(1M)\f1:\0\0\f4fsdb\f1@@@file system debugger (generic) .\" $Header: fsdb_hfs.1m,v 72.3 94/11/29 05:55:24 ssa Exp $ .TA f .TH fsdb_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fsdb \- HFS file system debugger .SH SYNOPSIS .CR /usr/sbin/fsdb .RC [ \-F .CR hfs ] .RC [ \-V ] .I special .RC [ \-b .IR blocknum ] .RC [ \- ] .SS Remarks Always execute the .CR fsck command (see .IR fsck (1M)) after running .CR fsdb . .SH DESCRIPTION The .C fsdb command can be used to patch up a damaged file system after a crash. .SS Options and Arguments .CR fsdb recognizes the following options and arguments. .RS .TP 15 .I special The file name of the special file containing the file system. .TP .CR \- Initially disable the error-checking routines that are used to verify the inode and fragment addresses. See the .CR O symbol. If used, this option must follow .I special on the command line. .TP .CI \-b \0blocknum Use .I blocknum as the superblock for the file system. If used, this option must follow .I special on the command line. .TP .CR \-F \0hfs Specify the HFS file system type. .TP .CR \-V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from the .CR /etc/fstab file. This option allows the user to verify the command line. .RE .SS Operation .CR fsdb normally uses the first superblock for the file system, located at the beginning of the disk section, as the effective superblock. An alternate superblock can always be found at block .CR "((SBSIZE+BBSIZE)/DEV_BSIZE)" , typically block 16. The .CR \-b option can be used to specify the superblock location. .PP .CR fsdb deals with the file system in terms of block fragments, which are the unit of addressing in the file system and the minimum unit of space allocation. To avoid possible confusion, .I fragment is used to mean that, and .I block is reserved for the larger true block. .CR fsdb has conversions to translate fragment numbers and i-numbers into their corresponding disk addresses. Also included are mnemonic offsets to access different parts of an inode. These greatly simplify the process of correcting control block entries or descending the file system tree. .PP .CR fsdb contains several error-checking routines to verify inode and fragment addresses. These can be disabled if necessary by invoking .CR fsdb with the optional .CR \- argument, or by using the .CR O symbol. .PP Numbers are considered decimal by default. Octal numbers must be prefixed with a zero. Hexadecimal numbers must be prefixed with .CR 0x . During any assignment operation, numbers are checked for a possible truncation error due to a size mismatch between source and destination. .PP .CR fsdb reads a fragment at a time. A buffer management routine is used to retain commonly used fragments of data in order to reduce the number of read system calls. All assignment operations result in an immediate write-through of the corresponding fragment. .SS Symbols The following symbols are recognized by .CR fsdb : .RS .TP 10 .PD 0 .CR ! Escape to shell .TP .CR # Absolute address .TP .CR + Address arithmetic .TP .CR \- Address arithmetic .TP .CR < Restore an address .TP .CR > Save an address .TP .CR = Numerical assignment .TP .CR =+ Incremental assignment .TP .CR =\- Decremental assignment .TP .C "=""" Character string assignment .TP .CR b Convert from fragment number to disk address (historically "block") .TP .CR d Directory slot offset .TP .CR f File print facility .TP .CR i Convert from i-number to inode address; for continuation inodes as well as primary inodes (see .IR inode (4)) .TP .CR p General print facility .TP .CR q Quit .TP .CR B Byte mode .TP .CR D Double-word mode .TP .CR O Error checking flip-flop .TP .CR W Word mode .TP .CR X Hexadecimal flip-flop .PD .RE .PP Dots, tabs, and spaces can be used as function delimiters, but are not necessary. A line with just a newline character increments the current address by the size of the data type last printed. That is, the address is set to the next byte, word, double word, directory entry, or inode, allowing the user to step through a region of a file system. .PP Information is printed in a format appropriate to the data type. If the .CR X toggle is off, bytes, words, and double words are printed in the form: .IP .IC octal-address \0\0:\0 octal-value \0\0( decimal-value ) .PP If the .CR X toggle is on, bytes, words, and double words are printed in the form: .IP .IC hex-address \0\0:\0 hex-value .PP If the .CR B (byte) or .CR D (double-word) mode is in effect, the colon .RC ( : ) shown above is preceded by .CR \&.B or .CR \&.D , respectively. .PP Directories are printed as a directory slot offset followed by the decimal i-number and the character representation of the entry name. .PP Inodes are printed with labeled fields describing each element. .SS Print Facilities The print facilities generate a formatted output in various styles. Octal numbers are prefixed with a zero. Hexadecimal numbers are prefixed with .CR 0x . The current address is normalized to an appropriate boundary before printing begins. It advances with the printing and is left at the address of the last item printed. The output can be terminated at any time by typing the interrupt character. If a number follows the .CR p symbol, that many entries are printed. A check is made to detect fragment boundary overflows since logically sequential blocks are generally not physically sequential. If a count of zero is used, all entries to the end of the current fragment are printed. The print options available are: .RS .TP 10 .PD 0 .CR b Print as octal bytes .TP .CR c Print as characters .TP .CR d Print as directories .TP .CR e Print as decimal words .TP .CR i Print as inodes (primary or continuation) .TP .CR o Print as octal words .TP .CR x Print as hexadecimal words .PD .RE .PP The .CR f symbol prints data fragments associated with the current inode. If followed by a number, that fragment of the file is printed. (Fragments are numbered from zero). The desired print option letter follows the fragment number, if present, or the .CR f symbol. This print facility works for small as well as large files except for special files such as FIFOs, and device special files. .SS Inode and Directory Mnemonics The following mnemonics are used for inode examination and refer to the current working inode: .RS .TP 10 .PD 0 .CI a num Data block numbers .RI ( num is in the range 0 \(mi 14) .TP .CR at Time last accessed .TP .CR ci Continuation inode number .TP .CR ct Last time inode changed .TP .CR gid Group ID number .TP .CR ln Link count .TP .CR maj Major device number .TP .CR md Mode .TP .CR min Minor device number .TP .CR mt Time last modified .TP .CR sz File size in byte unit .TP .CR uid User ID number .PD .RE .PP The following mnemonics are used for directory examination: .RS .TP 10 .PD 0 .CR di I-number of the associated directory entry .TP .CR nm Name of the associated directory entry .PD .RE .SH EXAMPLES .TP 15 .C "386i" Print i-number 386 in an inode format. This now becomes the current working inode. .TP .C "ln=4" Change the link count for the working inode to 4. .TP .C "ln=+1" Increment the link count by 1. .TP .C "fc" Print in ASCII fragment zero of the file associated with the working inode. .TP .C "2i.fd" Print the first fragment-size piece of directory entries for the root inode of this file system. .TP .C "d5i.fc" Change the current inode to that associated with the fifth directory entry (numbered from zero) found from the above command. The first fragment's worth of bytes of the file are then printed in ASCII. .TP .C "1b.px" Print the first fragment of the superblock of this file system in hexadecimal. .TP .C "2i.a0b.d7=3" Change the i-number for the seventh directory slot in the root directory to 3. This example also shows how several operations can be combined on one command line. .TP .C "d7.nm=""newname""" Change the name field in the directory slot to the given string. Quotes are optional if the first character of the name field is alphabetic. .TP .C "a2b.p0d" Print the third fragment of the current inode as directory entries. .SH WARNINGS Only experienced users should use .CR fsdb . The failure to fully understand the usage of .CR fsdb and the file system's internal organization can lead to complete destruction of the file system and total loss of data. .SH FILES .TP 15 .CR /etc/fstab Static information about the file systems .SH AUTHOR .CR fsdb was developed by HP and AT&T. .SH SEE ALSO dumpfs(1M), fsck(1M), fsdb(1M), stat(2), dir(4), fs(4). .SH STANDARDS CONFORMANCE .PP .CR fsdb ": SVID3" .\" .\" index@\f4fsdb\f1 \- HFS file system debugger@@@\f3fsdb_hfs(1M)\f1 .\" index@\f1damaged HFS file system, patch up@@@\f3fsdb_hfs(1M)\f1 .\" index@\f1debug HFS file system@@@\f3fsdb_hfs(1M)\f1 .\" index@\f1file system debugger (HFS)@@@\f3fsdb_hfs(1M)\f1 .\" index@\f1HFS file system debugger@@@\f3fsdb_hfs(1M)\f1 .\" index@\f1file system, damaged, patch up (HFS)@@@\f3fsdb_hfs(1M)\f1 .\" index@\f1fix damaged HFS file system@@@\f3fsdb_hfs(1M)\f1 .\" index@\f1patch up damaged HFS file system@@@\f3fsdb_hfs(1M)\f1 .\" index@\f1crash, patch up damaged HFS file system@@@\f3fsdb_hfs(1M)\f1 .\" index@\f1repair damaged HFS file system@@@\f3fsdb_hfs(1M)\f1 .\" toc@\f3fsdb_hfs(1M)\f1:\0\0\f4fsdb\f1@@@HFS file system debugger .\" $Header: fsdb_vxfs.1m,v 78.1 96/02/13 11:47:01 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA f .TH fsdb_vxfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fsdb (vxfs) \- VxFS file system debugger .SH SYNOPSIS .C /usr/sbin/fsdb .RC [ \-F .CR vxfs ] .RC [ \-V ] .RC [ \-z .IR inumber ] .I special .SH DESCRIPTION .PP The .C fsdb command can be used to patch up a damaged VxFS file system after a crash. A special device .I special is used to indicate the file system to be debugged. The .C fsdb command is intended for experienced users only. .PP The .C fsdb command has conversions to translate block and inumbers into their corresponding disk addresses. Also included are mnemonic offsets to access different parts of an inode. These greatly simplify the process of correcting control block entries or descending the file system tree. .PP By default, numbers are considered decimal. Octal numbers must be prefixed with .CR 0. Hedecimal numbers must be prefixed with .CR 0x . When using hexadecimal numbers, it is preferable to follow the number with a space, since a number of commands are letters that are also hexadecimal digits. In this document a pound sign .RC ( # ) is used to indicate that a number is to be specified. .PP The .C fsdb command reads a block at a time and works with raw and block I/O. All I/O is unbuffered, so changes made to the file system are immediate and changes made by other processes or by the kernel are immediately seen by the .CR fsdb command. .PP .SS Options .RS .TP 15 .CR "\-F vxfs" Specifies the VxFS file-system type. .TP .C \-V Echoes the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR "/etc/fstab" . This option allows the user to verify the command line. .TP .CI \-z " inumber" Clear the inode identified by .I inumber (non-interactive). Multiple .C \-z options accumulate. .RE .PP The following symbols are recognized by the .C fsdb command: .RS .PD 0 .TP 15 h [mod|print] Print summary of commands that display [modify|format] the file system. .TP 15 ? [mod|print] Print summary of commands that display [modify|format] the file system. .TP 15 help [mod|print] Print summary of commands that display [modify|format] the file system. .TP 15 ! Escape to shell. .TP | Pipe output of fsdb command to a shell command. .TP 15 q Quit. .TP 15 "string" A character string. Inside a character string, a NULL character may be specified with ``\e0''; a double quote may be specified with ``\e"''; and a backslash may be specified with ``\e\e ''. .TP 15 + - \(** / % Add, subtract, multiply, divide, and modulus. .TP 15 = Assignment .TP 15 i An inode in the primary inode list. .TP 15 ai An inode in the attribute inode list. .TP 15 au An allocation unit. .TP 15 b A block. .TP 15 im The immediate data area of an inode. Small directories and symbolic link files (96 bytes or less) are stored directly in the inode itself, in the area normally occupied by data block numbers and extent sizes. .TP 15 attr An attribute inode. .TP 15 cdb Current directory block. .TP 15 d A directory entry. .TP 15 a An inode address entry. .TP 15 B A byte. .TP 15 H A half-word (2 bytes) .TP 15 W A word (4 bytes) .TP 15 D A double-word (8 bytes) .TP 15 p General print facility .TP 15 calc Simple calculator and base converter .TP 15 find Find a matching pattern in the file system .TP 15 fset A fileset. .TP 15 iau An inode allocation unit in the primary inode list. .TP 15 aiau An inode allocation unit in the attribute inode list. .TP 15 cut The current usage table. .TP 15 olt The object location table. .TP mapi Map logical file offset to an inode extent. .TP reset Reset device. .PD .RE .PP The print facility recognizes the following print formats: .RS .PD 0 .TP 15 S Print as a super-block. .TP 15 A Print as an allocation-unit header. .TP 15 AS Print as an auxilliary super-block. .TP 15 L Print as intent-log records. .TP 15 I Print as inodes. .TP 15 T Print as typed extent descriptors. .TP 15 dent Print as directory entries. .TP 15 db Print as a directory block. .TP 15 dh Print as a directory header. .TP 15 o Print as octal words. .TP 15 oB oH oW oD Print as octal bytes, half-words, words, or double-words. .TP 15 x Print as hexadecimal words. .TP 15 xB xH xW xD Print as hexadecimal bytes, half-words, words, or double-words. .TP 15 e Print as decimal words. .TP 15 eB eH eW eD Print as decimal bytes, half-words, words, or double-words. .TP 15 c Print as characters. .TP 15 F Print as fileset headers. .TP 15 C Print as current usage table entries. .TP 15 IA Print as an inode allocation unit header. .TP 15 oltext Print as an object location table extent. .TP Q Print as a BSD quota record. .TP DV Print as a device record. .PD .RE .PP Changes to inode fields may be made symbolically. The following symbols represent inode fields: .RS .PD 0 .TP 15 md Inode mode field .TP 15 ln Inode link count field .TP 15 uid Inode user .SM ID Number field .TP 15 gid Inode group .SM ID Number field .TP 15 szlo Low-order word of inode file size field .TP 15 szhi High-order word of inode file size field .TP 15 sz Inode file size field .TP 15 de# Inode direct extent data block numbers (0 \- 9) .TP 15 des# Inode direct extent sizes (0 \- 9) .TP 15 ie# Inode indirect extent data block numbers (0 \- 1) .TP 15 ies Inode indirect extent size .TP 15 at Inode access time field (seconds) .TP 15 ats Inode access time field (microseconds). .TP 15 ct Inode change time field (seconds). .TP 15 cts Inode change time field (microseconds). .TP 15 mt Inode modification time field (seconds). .TP 15 mts Inode modification time field (microseconds). .TP 15 af Inode allocation flags field. .TP 15 gen Inode generation count field. .TP 15 org Inode mapping type field. .TP 15 fe Inode fixed extent size field. .TP 15 bl Inode blocks held field. .TP 15 eopflg Inode extended operation flag field. .TP 15 eopdat Inode extended operation data field. .TP 15 rdev If device, inode device number. .TP 15 maj If device, inode major number. .TP 15 min If device, inode minor number. .TP 15 pd If directory, inode parent directory. .TP 15 res If regular file, inode reservation. .TP 15 verhi Inode high-order word of serial number. .TP 15 verlo Inode low-order word of serial number. .TP 15 fsindex Referencing fileset ID. .TP 15 matching Inode number of matching inode. .TP 15 iano Indirect attribute inode. .PD .RE .PP Changes to directory block fields may be made symbolically. The following symbols represent directory block fields: .RS .PD 0 .TP 15 tfree Total free space (only if in a data block). .TP 15 hash# Hash chain start (0 through 31, only if in a data block). .TP 15 d# Directory entry (variable number of entries). .TP 15 nhash Number of hash chains. .PD .RE .PP Changes to directory entry fields may be made symbolically. The following symbols represent directory entry fields: .RS .PD 0 .TP 15 ino Inode number .TP 15 nm Entry name .TP 15 nmlen Name length .TP 15 reclen Record length (only if in a data block) .TP 15 hnext Name hash next (only if in a data block) .PD .RE .PP It is preferable to separate each token on a command line with a space. Although the command parser does not insist on space separation, there is no ambiguity in the command language if each token is separated with a space. For example, the command 0x23b b sets the current position to block 0x23b hexadecimal. The command 0x23bb is invalid, since the command is parsed as simply a hexadecimal number. The command 23b positions to block 23 decimal, since the command is not ambiguous. .PP Commands are separated by new lines, or multiple commands may be placed on one line, separated by a period (.) or a semicolon (;). When multiple commands are placed on one line, generally only the last command displays results. This allows positioning commands to be followed by printing commands or change commands without intermediate printing. .PP The .C fsdb command maintains several positions in the file system: the .I current position, the .I current primary-inode position (i), the .I current attribute-inode position (ai), the .I current inode type (i or ai), the .I current fileset-header position (fset), the .I current allocation-unit position (au), the .I current primary-inode allocation-unit (iau) position. the .I current inode allocation-unit type (iau or aiau). the .I current attribute-inode allocation-unit (aiau) position. These are used by various .C fsdb commands. (The au positions are supported through Version 3, but not beyond.) .PP The following commands are supported: .RS .PD 0 .TP 15 # B|H|W|D Set current position in the file system to the specified offset in bytes, half-words, words, or double-words. If the last command on a line, print the byte, half-word, word, or double-words in hexadecimal. .TP 15 +|- # B|H|W|D Set current position to specified relative offset in bytes, half-words, words, or double-words. If the last command on a line, print the byte, half-word, word, or double-words in hexadecimal. .TP 15 # au Set current position in the file system to the specified allocation unit (au) position. Set current allocation unit position to the resulting offset. If the last command on a line, print the allocation unit header. .TP 15 +|- # au Set current position in the file system to the specified position relative to the current allocation unit (au) position. Set current allocation unit position to the resulting offset. If the last command on a line, print the allocation unit header. .TP 15 au Set current position in the file system to the current allocation unit position. If the last command on a line, print the allocation unit header. .TP 15 # b Set current position in the file system to the specified offset in blocks. Set current block position to the resulting offset. The block size is the block size of the file system. If the last command on a line, print the first word in the block in hexadecimal. .TP 15 +|- # b Set current position to specified relative offset in blocks. Set current block position to the resulting offset. If the last command on a line, print the first word in the block in hexadecimal. .TP 15 b Set current position to current block position (the block specified by the last [+|-] # b operation). If the last command on a line, print the first word in the block in hexadecimal. .TP 15 cut Set current position to the current usage table (cut). If the last command on a line, print the first current usage table entry. .TP 15 dev Set current position to the primary device's configuration record. If the last command on a line, print the device-configuration record. .TP 15 # fset Set current position in the file system to the fileset header entry for the specified fileset index. Set current fileset position to the resulting offset. If the last command on a line, print the specified fileset header. .TP 15 +|- # fset Set current position in the file system to the fileset header entry for the specified position relative to the current fileset position. Set current fileset position to resulting offset. If the last command on a line, print the specified fileset header. .TP 15 fset Set current position in the file system to the current fileset position. If the last command on a line, print the fileset header for the current fileset. .TP 15 # aiau Set current position in the file system to the specified attribute inode allocation unit (aiau) in a fileset. Set the current attribute inode allocation unit position to the resulting offset. If the last command on a line, print the attribute inode allocation unit header. .TP 15 +|- # aiau Set the current position in the file system to the specified position relative to the current attribute inode allocation unit (aiau) position. Set the current attribute inode allocation unit position to the resulting offset. If the last command on a line, print the attribute inode allocation unit header. .TP 15 aiau Set the current position in the file system to the current attribute inode allocation unit (aiau) position. If the last command on a line, print the attribute inode allocation unit header. .TP 15 # iau Set current position in the file system to the specified inode allocation unit (iau) in a fileset. Set the current inode allocation unit position to the resulting offset. If the last command on a line, print the inode allocation unit header. .TP 15 +|- # iau Set the current position in the file system to the specified position relative to the current inode allocation unit (iau) position. Set the current inode allocation unit position to the resulting offset. If the last command on a line, print the inode allocation unit header. .TP 15 iau Set the current position in the file system to the current inode allocation unit (iau) position. If the last command on a line, print the inode allocation unit header. .TP 15 # ai Set current position in the current fileset to the ilist entry for the specified attribute inode. Set current attribute inode position to the resulting offset. If the last command on a line, print the ilist entry for the inode. .TP 15 +|- # ai Set current position in the current fileset to the ilist entry for the specified relative attribute inode. Set current attribute inode position to the resulting offset. If the last command on a line, print the ilist entry for the inode. .TP 15 ai Set current position in the current fileset to the current attribute inode position. If the last command on a line, print the ilist entry for the inode. .TP 15 # i Set current position in the current fileset to the ilist entry for the specified inode. Set current inode position to the resulting offset. If the last command on a line, print the ilist entry for the inode. .TP 15 +|- # i Set current position in the current fileset to the ilist entry for the specified relative inode. Set current inode position to the resulting offset. If the last command on a line, print the ilist entry for the inode. .TP 15 i Set current position in the current fileset to the current inode position. If the last command on a line, print the ilist entry for the inode. .TP 15 a# Set current position to specified offset in blocks specified by the inode address #. Addresses 0 through 9 are for direct extents ( de ). Addresses 10-11 are for indirect extents ( ie ). The addresses are displayed when printing an ilist entry. Set current block position to the resulting offset. If the last command on a line, print the first word in the block in hexadecimal. .TP 15 im Set current position to immediate data area of the current inode. Set current block position to the resulting offset. If the last command on a line, print the first word of the area in hexadecimal. .TP 15 attr Set current position to attribute data area of the current inode. Set current block position to the resulting offset. If the last command on a line, print the first word in the block in hexadecimal. .TP 15 # B|H|W|D =# [#] Set the current position and change the number at the specified offset to the given number. If a double-word offset is specified, then two numbers separated by a space are required. The resulting value is printed in hexadecimal. .TP 15 +|-# B|H|W|D =# [#] Set the current position and change the number at the specified relative offset to the given number. If a double-word offset is specified, then two numbers separated by a space are required. The resulting value is printed in hexadecimal. .TP 15 # B|H|W|D = "\f2string\fP" Set the current position and change the characters at the specified offset to the given string. The resulting value is printed as a character string. .TP 15 +|- # B|H|W|D = "\f2string\fP" Set the current position and change the characters at the specified relative offset to the given string. The resulting value is printed as a character string. .TP 15 olt Set the current position to the object location table (olt). If the last command on a line, print the object location table. .TP 15 p [#] format Print the contents of the file system at the current offset as the specified number of entries of a given format. The allowable print formats are specified above. If a number of entries to print is not specified, one entry is printed. .TP 15 \f2inode_field\fP = # Set the contents of the given inode field to the specified number. The current inode specifies the inode list entry to be modified. The symbols representing inode fields are previously listed. .TP 15 \f2directory_block_field\fP = # Set the contents of the given directory block field to the specified number. The current block is treated as a directory block and the offset in that block which is represented by the given field is changed. The symbols representing directory block fields are listed above. .TP 15 d# Set the current directory entry to the specified number. The current block is treated as a directory block. If the current block is an immediate data area for an inode, then the block is treated as containing immediate directory entries. If the last command on a line, the directory entry at the resulting offset is printed. .TP 15 \f2directory_entry_field\fP = # Set the contents of the given directory field to the specified number. The current directory entry specifies where the directory entry is located. The resulting value is printed in hexadecimal. .TP 15 nm = "\f2string\fP" Set the directory name field of the current directory entry to the specified string. The resulting value is printed as a character string. .TP 15 calc # [+|-|\(**|/ #] Take a number or the sum, difference, product or dividend of two numbers and print in decimal, octal, hexadecimal and character format. .TP 15 find # B|H|W|D [#] Search for the given numeric pattern in the file system. The size of the object to match is specified. If a double-word is specified, then two numbers must be given. The search is performed forward from the current offset. A maximum number of blocks to search may be specified. If found, the location and value are printed in hexadecimal. .TP 15 find "\f2string\fP" [#] Search for the given character string in the file system. The search is performed forward from the current offset. A maximum number of blocks to search may be specified. If found the location and string are printed. .TP 15 fmtlog Format all intent log entries. A completely formatted intent log can be quite lengthy. It is a good idea use the .C fsdb command as a filter and redirect the output to a file or pager to look at a complete log format. .TP 15 listfset List all filesets by their indexes and names. .TP mapi # Treat the number as a logical offset in the file described by the current inode, and print the extent that it maps to. .TP reset Does the equivalent of exiting .C fsdb and restarting on same device. .RE .PP The following help commands are supported: .RS .PD 0 .TP 15 h|help Display primary help screen. .TP 15 h mod Display modification-commands help screen. .TP 15 h print Display print-commands help screen. .RE .PD .SH EXAMPLES .TP 15 386i Prints inumber 386 in an inode format. This now becomes the current working inode. .TP 15 ln=4 Changes the link count for the working inode to 4. .TP 15 .\".ie \(nHp \{ .\"8192.p S .\"\} .\".TP 15 .\".el \{ 1024.p S \} Prints the super-block of this file system symbolically. .TP 15 2i.a0b.d7.ino = 3 Changes the inumber for the seventh directory slot in the root directory to 3. This example also shows how several operations can be combined on one command line. .br .ne 3 .TP 15 d7.nm = "\f2foo\fP" Changes the name field in the directory slot to "\f2foo\fP". .TP 15 23i.im.pdb Prints the immediate area of inode 23 as a directory block. .TP 15 23i.im.d5 Prints the sixth directory entry in the immediate area of inode 23. .PP .SH WARNINGS Always execute .C fsck (1M) after using the .C fsdb command to modify a file system (use .CR "fsck \-o full,nolog" ). .SH SEE ALSO fsck(1M), fsdb(1M). .\" .\" toc@\f3fsdb_vxfs(1M)\f1:\0\0\f(CWfsdb\f1@@@VxFS file system debugger .\" .\" index@\f(CWfsdb_vxfs\f1 \- VxFS file system debugger@@@\f3fsdb_vxfs(1M)\f1 .\" index@\f(CWfsdb\f1 \- VxFS file system debugger@@@\f3fsdb_vxfs(1M)\f1 .\" .\" index@\f1VxFS file system debugger@@@\f3fsdb_vxfs(1M)\f1 .\" index@\f1file system debugger, VxFS@@@\f3fsdb_vxfs(1M)\f1 .\" index@\f1debugger, VxFS file system@@@\f3fsdb_vxfs(1M)\f1 .\" .\" $Header: fsirand.1m,v 72.4 94/06/30 15:20:35 ssa Exp $ .TA f .TH fsirand 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fsirand \- install random inode generation numbers .SH SYNOPSIS .C /usr/sbin/fsirand .RC [ -p ] .I special .SH DESCRIPTION .CR fsirand installs random inode generation numbers on all the inodes on device .I special, and also installs a filesystem ID in the superblock. This process increases the security of filesystems exported by NFS. .PP Use .CR fsirand only on an unmounted filesystem that was checked with .CR fsck (see .IR fsck (1M)). The only exception is that it can be used on the root filesystem in single-user mode if the system is immediately re-booted afterwards using .CR "reboot -n" . .PP The .CR -p option prints the generation numbers for all inodes. .SH WARNINGS .CR fsirand should not be run on mounted filesystems. If executing .CR fsirand on the root filesystem, the system should be in single-user mode and should be re-booted immediately afterwards using .CR "reboot -n" . .SH AUTHOR .CR fsirand was developed by Sun Microsystems, Inc. .SH SEE ALSO statfs(2). .\" .\" index@\f4fsirand\f1: install random inode generation numbers@@@\f3fsirand(1M)\f1 .\" index@install random inode generation numbers@@@\f3fsirand(1M)\f1 .\" index@random inode generation numbers, install@@@\f3fsirand(1M)\f1 .\" index@inode generation numbers, install random@@@\f3fsirand(1M)\f1 .\" index@numbers, inode generation, install random@@@\f3fsirand(1M)\f1 .\" .\" toc@\f3fsirand(1M)\f1: \f4fsirand\f1@@@install random inode generation numbers .\" $Header: fstyp.1m,v 78.1 95/12/20 10:51:12 ssa Exp $ .TA f .TH fstyp 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fstyp \- determine file system type .SH SYNOPSIS .C /usr/sbin/fstyp .RC [ -v ] .IR special .SH DESCRIPTION The .CR fstyp command allows the user to determine the file system type of a mounted or unmounted file system. .I special represents a device special file (for example: .CR /dev/dsk/c1t6d0 ). .PP The file system type is determined by reading the superblock of the supplied .I special file. If the superblock is read successfully, the command prints the file system type identifier on the standard output and exits with an exit status of .CR 0 . If the type of the file system cannot be identified, the error message .C unknown_fstyp (no matches) is printed and the exit status is .CR 1 . Exit status .CR 2 is not currently returned, but is reserved for the situation where the file system matches more than one file system type. Any other error will cause exit status .CR 3 to be returned. .PP The file system type is determined by reading the superblock of the supplied .IR special file. .SS Options .RS .TP 10 .C -v Produce verbose output. The output contains information about the file system's superblock. .SH RETURN VALUE .CR fstyp returns the following values: .RS .TP 10 .PD 0 .CR 0 Successful completion. .TP .CR 1 Unknown file system type. .TP .CR 2 File system matches more than one type. .TP .CR 3 Usage error or access problem. .PD .SH EXAMPLES Find the type of the file system on a disk, .CR /dev/dsk/c1t6d0 : .IP .C fstyp /dev/dsk/c1t6d0 .PP Find the type of the file system on a logical volume, .CR /dev/vg00/lvol6 : .IP .C fstyp /dev/vg00/lvol6 .PP Find the file system type for a particular device file and also information about its super block: .IP .C fstyp -v /dev/dsk/c1t6d0 .SH SEE ALSO stat(2), statvfsdev(2). .\" .\" toc@\f3fstyp(1M)\f1:\0\0\f4fstyp\f1@@@determine file system type\f1 .\" .\" index@\f4fstyp\f1 \- determine file system type@@@\f3fstyp(1M)\f1 .\" index@\f1file system type, determine@@@\f3fstyp(1M)\f1 .\" index@\f1type, determine file system@@@\f3fstyp(1M)\f1 .\" $Header: ftpd.1m,v 1.1.113.4 96/12/13 16:36:58 sandya Exp $ .TA f .TH ftpd 1M .SH NAME ftpd \- DARPA Internet File Transfer Protocol server .SH SYNOPSIS .C /usr/lbin/ftpd .RC [ -l ] .RC [ -p ] .RC [ -v ] .RC [ -t .IR timeout\| ] .RC [ -T .IR maxtimeout\| ] .RC [ -u .IR umask\| ] .RC [ -B .IR size ] .SH DESCRIPTION .C ftpd is the DARPA Internet File Transfer Protocol server. It expects to be run by the Internet daemon (see .IR inetd (1M) and .IR inetd.conf (4)). .C inetd runs .C ftpd when a service request is received at the port indicated in the .C ftp service specification in .C /etc/services (see .IR services (4)). .C ftpd recognizes the following options and command-line arguments. .RS .TP 15 .CR -l Causes each FTP session to be logged in the syslog file. For anonymous FTP sessions, other information is also logged in the syslog file. This information includes what files are stored and retrieved and what directories are created. .TP .CR -p The default action of ftpd does not allow usage of reserved ports as the originating port on the client's system i.e., the PORT command cannot specify a reserved port. This option allows the client to specify a reserved port. Note, allowing usage of reserved ports can result in the misuse of ftpd. The security ramifications should be understood before the option is turned on. .TP .CR -v Logs other information in the syslog file. This information is what is normally logged for anonymous FTP sessions. This information includes what files are stored and retrieved and what directories are created. .TP .CI -t \0timeout Causes .C ftpd to timeout inactive sessions after .I timeout seconds. By default, .C ftpd terminates an inactive session after 15 minutes. .TP .CI -T \0maxtimeout A client can also request a different timeout period. The .CR -T option sets to .IR maxtimeout the maximum timeout that client can request, in seconds. By default, the maximum timeout is 2 hours. .TP .CI -u \0umask Change default .C ftpd umask from 027 to .IR umask . .TP .CI -B \0size Sets the buffer size of the data socket to .I size blocks of 1024 bytes. The valid range for .I size is from 1 to 64 (default is 56). .BR NOTE: A large buffer size will improve the performance of .C ftpd on fast links (e.g. FDDI), but may cause long connection times on slow links (e.g. X.25). .RE .PP .C ftpd currently supports the following commands (uppercase and lowercase are interpreted as equivalent): .RS .TP 15 .C Command .C Description .PD 0 .TP .C ABOR Abort previous command .TP .C ACCT Specify account (ignored) .TP .C ALLO Allocate storage (vacuously) .TP .C APPE Append to a file .TP .C CDUP Change to parent of current working directory .TP .C CWD Change working directory .TP .C DELE Delete a file .TP .C HELP Give help information .TP .C LIST Give list files in a directory .RC ( "ls -l" ) .TP .C MKD Make a directory .TP .C MDTM Show last modification time of file .TP .C MODE Specify data transfer .I mode .TP .C NLST Give name list of files in directory .TP .C NOOP Do nothing .TP .C PASS Specify password .TP .C PASV Prepare for server-to-server transfer .TP .C PORT Specify data connection port .TP .C PWD Print the current working directory .TP .C QUIT Terminate session .TP .C REST Restart incomplete transfer .TP .C RETR Retrieve a file .TP .C RMD Remove a directory .TP .C RNFR Specify rename-from file name .TP .C RNTO Specify rename-to file name .TP .C SITE Non-standard commands (see next section) .TP .C SIZE Return size of file .TP .C STAT Return status of server .TP .C STOR Store a file .TP .C STOU Store a file with a unique name .TP .C STRU Specify data transfer .I structure .TP .C SYST Show operating system type of server system .TP .C TYPE Specify data transfer .I type .TP .C USER Specify user name .TP .C XCUP Change to parent of current working directory .TP .C XCWD Change working directory .TP .C XMKD Make a directory .TP .C XPWD Print the current working directory .TP .C XRMD Remove a directory .RE .PD .PP The following non-standard or HP-UX specific commands are supported by the .C SITE command: .PP .RS .TP 15 .C Command .C Description .PD 0 .TP .C UMASK Change umask. (e.g., .CR "SITE UMASK 002" ) .TP .C IDLE Set idle-timer. (e.g., .C "SITE IDLE" 60) .TP .C CHMOD Change mode of a file. (e.g., .C "SITE CHMOD 755" filename) .TP .C HELP Give help information. (e.g., .CR "SITE HELP" ) .RE .PD .PP The remaining FTP requests specified in Internet RFC 959 are recognized, but not implemented. .C MDTM and .C SIZE are not specified in RFC 959, but are expected in the next updated .CR "FTP RFC" . .PP The FTP server aborts an active file transfer only when the .C ABOR command is preceded by a Telnet "Interrupt Process" (IP) signal and a Telnet ``Synch'' signal in the command Telnet stream, as described in Internet RFC 959. If .C ftpd receives a .C STAT command during a data transfer, preceded by a Telnet IP and Synch, it returns the status of the transfer. .PP .C ftpd interprets file names according to the ``globbing'' conventions used by .IR csh (1). This allows users to utilize the metacharacters .CR * , .CR . , .CR [ , .CR ] , .CR { , .CR } , .CR ~ , and .CR ? . .PP .C ftpd authenticates users according to three rules: .RS .TP 3 \(bu The user name must be in the password data base, .CR /etc/passwd , and not have a null password. The client must provide the correct password for the user before any file operations can be performed. .TP \(bu The user name must not appear in the file .C /etc/ftpusers (see .IR ftpusers (4)). .TP \(bu The user must have a standard shell returned by .CR getusershell() . .RE .PP Optionally, a system administrator can permit public access or ``anonymous FTP.'' If this has been set up, users can access the anonymous FTP account with the user name .C anonymous or .C ftp and any non-null password (by convention, the client host's name). .C ftpd does a .C chroot() to the home directory of user .CR ftp , thus limiting anonymous FTP users' access to the system. If the user name is .C anonymous or .CR ftp , an anonymous FTP account must be present in the password file (user .CR ftp ). In this case the user is allowed to log in by specifying any password (by convention this is given as the user's e-mail address). .PP In order to permit anonymous FTP, there must be an entry in the .IR passwd (4) database for an account named .CR ftp . The password field should be .CR * , the group membership should be .CR guest , and the login shell should be .CR /usr/bin/false . For example (assuming the .C guest group ID is .CR 10 ): .RS .nf .P .C "ftp:*:500:10:anonymous ftp:/home/ftp:/usr/bin/false" .fi .RE .PP The anonymous FTP directory should be set up as follows: .RS 0 .TP 8 .C ~ftp The home directory of the FTP account should be owned by user .C root and mode 555 (not writable). Since .C ftpd does a .C chroot() to this directory, it must have the following subdirectories and files: .RS .TP 10 .C ~ftp/usr/bin This directory must be owned by root and mode 555 (not writable). It should contain a copy of .CR /usr/bin/ls . This is needed to support directory listing by .CR ftpd . The command should be mode 111 (executable only). If the FTP account is on the same file system as .CR /usr/bin , .C ~ftp/usr/bin/ls can be hard link, but it may not be a symbolic link, because of the .CR chroot() . The command must be replaced when the system is updated. .TP .C ~ftp/etc This directory must be owned by root and mode 555 (not writable). It should contain versions of the files .IR passwd , .IR group , and .IR logingroup . See .IR passwd (4) and .IR group (4). These files must be owned by root and mode 444 (readable only). These are needed to map user and group ids in the .C LIST command, and to support (optional) sub-logins of anonymous FTP. Sub-logins can sometimes be used to allow access to particular files by only specific remote users (who know the sub-login password) without giving those remote users logins on the system. A sub-login user would access the system via anonymous FTP, then use .C USER and .C PASS to change to the sub-login user. .TP .C ~ftp/etc/passwd This file should contain entries for the .C ftp user and any other users who own files under the anonymous .C ftp directory. Such entries should have .C * for passwords. .C ~ftp/etc/passwd should also contain entries for any desired anonymous FTP sub-logins. The sub-logins must have passwords, which must be encrypted as in .IR passwd (4). Group IDs must be listed in the anonymous FTP group file, .CR ~ftp/etc/group . The path names of home directories in .C ~ftp/etc/passwd must be with respect to the anonymous FTP home directory. A sub-login home directory should be owned by the sub-login user ID. The shell field is ignored, and can be empty. .IP For example, the anonymous FTP sub-login name .C subftp would have an entry in the FTP .C passwd file that resembles: .RS 15 .nf .P .C "subftp:bAg6vI82aq5Yt:501:10:ftp sub-login:/subftp:" .fi .RE .IP FTP sub-login IDs do not need to be present in the system .C /etc/passwd file. Assuming the anonymous FTP directory is .CR /home/ftp , the sub-login home directory in the example would be created by user .C root as follows: .RS 15 .nf .P .C "cd /home/ftp" .C "mkdir subftp" .C "chmod 700 subftp" .C "chown 501 subftp" .C "chgrp guest subftp" .fi .RE .IP File .C ~ftp/etc/group should contain the group names associated with any group IDs in file .C ~ftp/etc/passwd and any group IDs of files in the anonymous FTP subdirectories. In the above example, .C ~ftp/etc/group would require an entry for .CR guest , and the associated group ID would have to be the same as in the system's .C /etc/group file. .TP .C ~ftp/etc/logingroup Permits anonymous ftp sub-logins to be members of multiple groups. Can be a hard link to FTP .CR ~ftp/etc/group . .TP .CR ~ftp/pub\0 (optional) This directory is used by anonymous FTP users to deposit files on the system. It should be owned by user .C ftp and should be mode 777 (readable and writable by all). .TP .CR ~ftp/dist\0 (optional) Directories used to make files available to anonymous ftp users should be mode 555 (not writable), and any files to be distributed should be owned by root and mode 444 (readable only) so that they cannot be modified or removed by anonymous FTP users. .RE .RE .PP .C ftpd has the capability of using the HP-UX Integrated Login Library if configured. For a complete description of using and administering HP-UX Integrated Login, see .IR auth (5) and .IR auth.adm (1M). .PP HP-UX Integrated Login typically uses the Distributed Computing Environment (DCE) for its user registry. For a complete description of the DCE user registry and its relationship with HP-UX Integrated Login, see .IR auth.dce (5). .SH DIAGNOSTICS .C ftpd replies to FTP commands to ensure synchronization of requests and actions during file transfers, and to indicate the status of .CR ftpd . Every command produces at least one reply, although there may be more than one. A reply consists of a three-digit number, a space, some text, and an end of line. The number is useful for programs; the text is useful for users. The number must conform to this standard, but the text can vary. .PP The first digit of the message indicates whether the reply is good, bad, or incomplete. Five values exist for the first digit. The values and the interpretations of the values are: .RS .TP 8 1 The requested action is being initiated; expect another reply before proceeding with a new command. .TP 2 The requested action is complete. The server is ready for a new request. .TP 3 The command has been accepted, but the requested action requires more information. .TP 4 The command was not accepted, the requested action failed, but the error condition is temporary and the action can be requested again. .TP 5 The command was not accepted, the requested action failed, and the error condition would most likely occur again if the same command sequence is repeated. .RE .PP The second digit indicates the functional area that the message addresses. The values of the second digit and the interpretations of these values are: .RS .TP 8 0 Syntax. A message with a 0 for the second digit indicates that a syntax error occurred. .TP 1 Information. A message with a 1 as the second digit indicates that the message is in reply to a request for information. .TP 2 Connections. A message with a 2 as the second digit indicates that the message is a reply to a request for control and data connection information. .TP 3 Authentication and accounting. A message with a 3 as the second digit indicates that the message is a reply to a login or accounting procedure. .TP 4 Not currently specified. .TP 5 File system. A message with a 5 as the second digit indicates that the text following the number contains information concerning the status of the server file system. .RE .PP The third digit provides a further clarification of the information supplied by the second digit. Following are several examples of messages. Note that .CR ftpd 's replies match the number but not the text. .RS .TP 8 110 Restart marker reply. MARK .IC yyyy = mmmm where .I yyyy is a user process data stream marker, and .I mmmm is .CR ftpd 's equivalent marker .PD 0 .TP 120 Service ready in .I nnn minutes .TP 200 Command okay .TP 211 System status, or system help reply .TP 212 Directory status .TP 230 User logged in, proceed .TP 250 Requested file action okay, completed .TP 331 User name okay, need password .TP 350 Requested file action pending further information .TP 425 Cannot open data connection .TP 451 Requested action aborted: local error in processing .TP 500 Syntax error, command unrecognized or command line too long .TP 530 Not logged in .TP 550 Requested action not taken; file unavailable, not found, no access .PD .RE .SH WARNINGS The password is sent unencrypted through the socket connection. .PP Anonymous FTP is inherently dangerous to system security. .SH AUTHOR .C ftpd was developed by the University of California, Berkeley. .SH SEE ALSO auth(5), auth.adm(1M), auth.dce(5), ftp(1), inetd(1M), chroot(2), getusershel(3C), inetd.conf(4), ftpusers(4), passwd(4), group(4). .\" .\" index@\f4ftpd\f1 \- file transfer protocol server@@@\f3ftpd(1M)\f1 .\" index@\f1file transfer protocol server@@@\f3ftpd(1M)\f1 .\" index@\f1protocol server, file transfer@@@\f3ftpd(1M)\f1 .\" index@\f1transfer protocol server, file@@@\f3ftpd(1M)\f1 .\" index@\f1server, file transfer protocol@@@\f3ftpd(1M)\f1 .\" .\" toc@\f3ftpd(1M)\f1:\0\0\f4ftpd\f1@@@file transfer protocol server ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "summary and syntax" .SH NAME .PP \*Lfts\*O \- Introduction to the \*Lfts\*O command suite .SH "OPTIONS" .PP The following options are used with many \*Lfts\*O commands. They are also listed with the commands that use them. .VL 10 .zA "enh,R1.0.2,Reorganized list and added arguments" .LI "\*L\-fileset\*O {\*Vname\*O | \*VID\*O}" Specifies the fileset to use with the command. You can specify either a fileset name or a fileset ID. .LI "\*L\-server\*O \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Specifies the File Server machine to use with the command. This option is typically used to provide the name of the File Server machine on which the fileset or filesets to use with the command reside. You can use any of the following to specify the File Server machine: .ML .LI The machine's DCE pathname (for example, \*L/.../abc.com/hosts/fs1\*O) .LI The machine's host name (for example, \*Lfs1.abc.com\*O or \*Lfs1\*O) .LI The machine's IP address (for example, \*L11.22.33.44\*O) .LE .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-aggregate\*O \*Vname\*O" Specifies the device name, aggregate name, or aggregate ID of the aggregate or partition to use with the command. These identifiers are specified in the first, second, and fourth fields of the entry for the aggregate or partition in the \*Edcelocal\*L/var/dfs/dfstab\*O file. .LI "\*L\-cell\*O \*Vcellname\*O" Specifies that the command is to be run with respect to the cell named by the \*Ecellname\*O argument. By default, commands are executed in the local cell of the issuer of the command. .zZ "enh,R1.0.2,Reorganized list and added arguments" .zA "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs the \*Lfts\*O program to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. Generally, the \*L\-noauth\*O option is included with a command if DFS authorization checking is disabled on a server machine on which administrative privilege is required or if the Security Service is unavailable. If DFS authorization checking is disabled, DFS processes require no administrative privilege to issue any command; any user, even the identity \*Lnobody\*O, has sufficient privilege to perform any operation. If the Security Service is unavailable, a user's security credentials cannot be obtained. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .PP DFS authorization checking is disabled with the \*Lbos setauth\*O command or by including the \*L\-noauth\*O option when the \*Lbosserver\*O process is started on a machine. DFS authorization checking is typically disabled .ML .LI During initial DFS installation .LI If the Security Service is unavailable .LI During server encryption key emergencies .LI To view the actual keys stored in a keytab file .LE .PP .zA "defect,7219,R1.0.2,Review comments" Include the \*L\-noauth\*O option with a command that requires administrative privilege only if DFS authorization checking is disabled on the necessary machines. A command that requires administrative privilege fails if the \*L\-noauth\*O option is included and DFS authorization checking is not disabled. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,7219,R1.0.2,Review comments" .zZ "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal of the machine on which the command is issued as the identity of the issuer. Each DFS server machine has a DFS server principal stored in the Registry Database. A DFS server principal is a unique, fully qualified principal name that ends with the string \*Ldfs-server\*O; for example, \*L/.../abc.com/hosts/fs1/dfs-server\*O. (Do not confuse a machine's DFS server principal with its unique \*Lself\*O identity.) .PP Use this option only if the command is issued from a DFS server machine. You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs the \*Lfts\*O program to provide detailed information about its actions as it executes the command. This is useful mainly for debugging or trace purposes. The amount of additional information displayed when the \*L\-verbose\*O option is specified varies for different commands. .LI "\*L\-help\*O" Prints the online help for the command. All other valid options specified with this option are ignored. For complete details about receiving help, see the \*Ldfs_intro(1m)\*O reference page. .LE .SH "DESCRIPTION" .PP .zA "defect,10440,R1.1,Incorporate information from User's Guide" Most commands in the \*Lfts\*O command suite are administrative-level commands used only by system administrators to contact the Fileset Server and the Fileset Location Server (FL Server). (The primary exception is the \*Lfts lsquota\*O command, which is also issued by users to determine the quota of filesets with which they work.) Commands in the \*Lfts\*O suite are used to instruct the Fileset Server to create and delete filesets, as well as to move, replicate, and back up filesets. The FL Server automatically records in the Fileset Location Database (FLDB) any changes in fileset status and fileset location resulting from \*Lfts\*O commands. .zZ "defect,10440,R1.1,Incorporate information from User's Guide" .PP If the execution of an \*Lfts\*O command is interrupted by a server or a process failure, subsequent execution of the command continues at the interruption point rather than at the beginning of the operation. Therefore, before executing a command, the Fileset Server and the FL Server verify that running the command has an effect. If the desired end-state already exists, the command is not executed; if the end-state does not yet exist, the command continues as necessary to achieve it. .PP If the issuer explicitly interrupts a fileset operation with an interrupt signal, the fileset is locked. The issuer must unlock it with the \*Lfts unlock\*O command before proceeding. .SS "DCE Local File System" .PP The DCE Local File System (DCE LFS) is a high-performance, log-based file system. It supports the use of DCE LFS \*Laggregates\*O, which are physically equivalent to standard UNIX disk partitions but also contain a specialized log of \*Lmetadata\*O about the structure and location of information they house. .PP .zA "enh,R1.0.2,Add fileset definition" DCE LFS aggregates, in turn, support the use of DCE LFS filesets. DCE LFS filesets are hierarchical groupings of files managed as a single unit. They can vary in size but are almost always smaller than a disk partition. As a result, multiple DCE LFS filesets can be stored on a single aggregate. Non-LFS filesets occupy the entire partition on which they reside. .zZ "enh,R1.0.2,Add fileset definition" .PP Because of the differences between DCE LFS and non-LFS filesets, the following \*Lfts\*O commands function only with DCE LFS filesets. Refer to the appropriate command reference pages for more information about the functionality provided by these commands. .ML .LI \*Lfts addsite(1m)\*O .LI \*Lfts clone(1m)\*O .LI \*Lfts clonesys(1m)\*O .LI \*Lfts create(1m)\*O .LI \*Lfts delete(1m)\*O .LI \*Lfts lsreplicas(1m)\*O .LI \*Lfts move(1m)\*O .LI \*Lfts release(1m)\*O .LI \*Lfts rmsite(1m)\*O .LI \*Lfts setquota(1m)\*O .LI \*Lfts setrepinfo(1m)\*O .LI \*Lfts statrepserver(1m)\*O .LI \*Lfts update(1m)\*O .LI \*Lfts zap(1m)\*O .LE .SS "Fileset Location Database Information" .PP The Fileset Location Database (FLDB) is maintained by the Fileset Location Server (FL Server). A master copy of the FLDB is stored on one Fileset Database machine, with copies synchronized on other Fileset Database machines via the Ubik library of facilities. It is essential that the information in the FLDB correspond to the status of the filesets on the File Server machines. Therefore, any \*Lfts\*O command that affects fileset status also changes the corresponding FLDB entry automatically. If an \*Lfts\*O operation is interrupted before completion, information in the FLDB can differ from information on a File Server machine. In these cases, the \*Lfts syncfldb\*O and \*Lfts syncserv\*O commands must be used to align the information. .PP .zA "defect,10439,R1.1,Fix cross-references for DFS reorganization" There is an entry in the FLDB for each read/write DCE LFS and non-LFS fileset. Each entry for a DCE LFS fileset also records information about the read-only and backup versions of the fileset, because these versions do not have their own entries. The information in an FLDB entry includes the fileset's name and fileset ID number, the ID numbers of its read-only and backup versions (if it is a DCE LFS fileset), site definitions, site counts, and status flags. Complete details about the FLDB are included in Part 1 of the \*(Ad. .zZ "defect,10439,R1.1,Fix cross-references for DFS reorganization" .SS "Fileset Header Information" .PP .iX "fileset headers" "about" A separate fileset header is stored at the site of each copy of a DCE LFS fileset, regardless of its type (read/write, read-only, or backup). The data structure of the fileset header records the physical memory addresses of the files in the fileset on the partition on which the fileset is stored. The fileset header binds all the files into a logical unit without requiring that they be stored in contiguous memory blocks. .PP The header of a DCE LFS fileset includes the following information: the fileset's name; its fileset ID number; its type (read/write, read-only, or backup); its size; the ID numbers of its parent, clone, and backup versions; its creation date; and the date of its last modification. .SS "Cautions" .PP Specific cautionary information is included with individual commands. .SS "Receiving Help" .PP There are several different ways to receive help about DFS commands. The following examples summarize the syntax for the different help options: .VL .LI "\*C$\*O \*Lman fts\*O" Displays the reference page for the command suite. .LI "\*C$\*O \*Lman fts_\*Vcommand\*O" Displays the reference page for an individual command. You must use an _ (underscore) to connect the command suite to the command name. \*EDo not use the underscore when issuing the command in DFS.\*O .LI "\*C$\*O \*Lfts help\*O" Displays a list of commands in a command suite. .LI "\*C$\*O \*Lfts help \*Vcommand\*O" Displays the syntax for a single command. .LI "\*C$\*O \*Lfts apropos -topic \*Vstring\*O" Displays a short description of any commands that match the specified \*Vstring\*O. .LE .PP Consult the \*Ldfs_intro(1m)\*O reference page for complete information about the DFS help facilities. .SS "Privilege Required" .PP Most \*Lfts\*O commands can be issued by users included in either the \*Ladmin.ft\*O file or the \*Ladmin.fl\*O file. Some commands require that the issuer be included on both lists; some commands also require that the user have certain permissions for a file or directory. Specific privilege information is listed with each command's description. .SH "RELATED INFORMATION" .PP .zA "enh,5923,R1.1,remove cross-refs to User Guide and Ref" Commands: \*Ldfs_intro(1m)\*O, \*Lfts addsite(1m)\*O, \*Lfts aggrinfo(1m)\*O, \*Lfts apropos(1m)\*O, \*Lfts clone(1m)\*O, \*Lfts clonesys(1m)\*O, \*Lfts create(1m)\*O, \*Lfts crfldbentry(1m)\*O, \*Lfts crmount(1m)\*O, \*Lfts crserverentry(1m)\*O, \*Lfts delete(1m)\*O, \*Lfts delfldbentry(1m)\*O, \*Lfts delmount(1m)\*O, \*Lfts delserverentry(1m)\*O, \*Lfts dump(1m)\*O, \*Lfts edserverentry(1m)\*O, \*Lfts help(1m)\*O, \*Lfts lock(1m)\*O, \*Lfts lsaggr(1m)\*O, \*Lfts lsfldb(1m)\*O, \*Lfts lsft(1m)\*O, \*Lfts lsheader(1m)\*O, \*Lfts lsmount(1m)\*O, \*Lfts lsquota(1m)\*O, \*Lfts lsreplicas(1m)\*O, \*Lfts lsserverentry(1m)\*O, \*Lfts move(1m)\*O, \*Lfts release(1m)\*O, \*Lfts rename(1m)\*O, \*Lfts restore(1m)\*O, \*Lfts rmsite(1m)\*O, \*Lfts setquota(1m)\*O, \*Lfts setrepinfo(1m)\*O, \*Lfts statftserver(1m)\*O, \*Lfts statrepserver(1m)\*O, \*Lfts syncfldb(1m)\*O, \*Lfts syncserv(1m)\*O, \*Lfts unlock(1m)\*O, \*Lfts unlockfldb(1m)\*O, \*Lfts update(1m)\*O, \*Lfts zap(1m)\*O .PP .zA "enh,R1.0.2,Add list of files" Files: \*Ladmin.fl(4)\*O, \*Ladmin.ft(4)\*O, \*Ldfstab(4) .zZ "enh,R1.0.2,Add list of files" .PP .zA "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" .zZ "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" .zZ "enh,5923,R1.1,remove cross-refs to User Guide and Ref" .iX "-]" "\*Lfts\*O command suite" "summary and syntax" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" CHANGED ...\" 12-11-91: Added a sentence to the end of the second paragraph in the ...\" DESCRIPTION section. ...\" END CHANGED ...\" .rm zA .rm zZ .TH "fts addsite" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Laddsite\*O" .iX "-[" "replication" "defining sites" .SH NAME .PP \*Lfts addsite\*O \- Adds a replication site for a read/write DCE LFS fileset .SH "SYNOPSIS" .sS \*Lfts addsite -fileset\*O {\*Vname\*O | \*VID\*O} \*L\-server \*Vmachine\*L -aggregate \*Vname\*O [\*L\-maxsiteage \*Vinterval\*O] .nL [\*L\-cell \*Vcellname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-verbose\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-fileset\*O {\*Vname\*O | \*VID\*O}" Specifies the complete name or fileset ID number of the read/write source fileset for which the replication site is to be added. .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the File Server machine on which the replica is to be stored. Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-aggregate \*Vname\*O" Specifies the device name, aggregate name, or aggregate ID of the aggregate on which the replica is to be stored. These identifiers are specified in the first, second, and fourth fields of the entry for the aggregate in the \*Edcelocal\*L/var/dfs/dfstab\*O file. .LI "\*L\-maxsiteage \*Vinterval\*O" Specifies the maximum amount of time that the replica to be stored at the site can be out of date (MaxSiteAge). The Replication Server attempts to keep the replica current within this amount of time. If this option is omitted, the DefaultSiteAge for the read/write site is used as the value for the MaxSiteAge. This option must be specified if the DefaultSiteAge was not defined for the read/write fileset (if the \*L\-defaultsiteage\*O option was omitted when the \*Lfts setrepinfo\*O was used to set the replication parameters for the read/write fileset). .PP \*EUse this option only with Scheduled Replication.\*O The MaxSiteAge of a replication site is ignored if Release Replication is used. .LI "\*L\-cell \*Vcellname\*O" Specifies the cell where the command is to be run. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts addsite\*O command defines a replication site for the read/write DCE LFS fileset specified with the \*L\-fileset\*O option. A replication site is a File Server machine and aggregate where a read-only replica of a read/write fileset is to be stored. The command also increments the number of fileset entries recorded as residing on the File Server machine specified with the \*L\-server\*O option in the Fileset Location Database (FLDB) entry for the server. .PP A fileset's replication sites are recorded in the FLDB entry for the fileset. If this is the first replication site defined for the fileset, the status flag for the read-only version of the fileset is changed to \*Cvalid\*O in anticipation of the creation of a read-only fileset at the site. .PP Enter this command once for each replication site to be defined for a read/write fileset. Before this command is issued, the \*Lfts setrepinfo\*O command must be used to set the replication parameters for the read/write fileset and a server entry must exist in the FLDB for the File Server machine specified with the \*L\-server\*O option. .PP If Release Replication is used with the fileset, the first site defined with this command must be on the same File Server machine as the read/write, source fileset. If it is on the same aggregate as the source fileset, it is created as a clone of the source. Because it is created as a clone fileset, which has the same structure as a backup fileset, it shares data with the read/write fileset; therefore, it requires potentially much less space than a full read-only fileset created on a different aggregate. .PP .zA "defect,10752,R1.1,Minor technical clarification" A File Server machine can house only a single read-only version of a given read/write fileset. The command fails if an attempt is made to define a second replication site for a given fileset on the same File Server machine. Also, the File Server machine that houses a replication site must reside in the same cell as the read/write fileset for which the replication site is defined. The FLDB entry for a read/write fileset records the locations of the fileset's replication sites; the server machine on which a site is defined must have a server entry in the FLDB that records the entry for the read/write fileset. .zZ "defect,10752,R1.1,Minor technical clarification" .PP .zA "defect,9119,R1.0.3,Document max number of read-only sites" The FLDB can record a maximum of 16 sites for all versions of a fileset combined, a site being a specific File Server machine and aggregate. The read/write version and backup version (if it exists) of a fileset share a single site definition. If you define a replication site for a fileset at the same site as its read/write and backup versions, you can then define 15 more replication sites for the fileset; this approach allows you to define up to 16 replication sites. If you do not place a replica of a fileset at the same site as its read/write and backup versions, you can define a maximum of 15 replication sites for the fileset. .zZ "defect,9119,R1.0.3,Document max number of read-only sites" .PP The \*L\-maxsiteage\*O option is used to define the MaxSiteAge for the site, which is the maximum amount of time the replica at the site can be out of date. The Replication Server always attempts to copy the latest version of the fileset to the site before the MaxSiteAge expires. Use the \*L\-maxsiteage\*O option only if Scheduled Replication is used with the source fileset; the MaxSiteAge is ignored if Release Replication is used. .PP The DefaultSiteAge associated with the read/write fileset is used by default if the \*L\-maxsiteage\*O option is omitted. The \*L\-maxsiteage\*O option is required with the \*Lfts addsite\*O command if the \*L\-defaultsiteage\*O option was omitted when the \*Lfts setrepinfo\*O command was used to define the replication parameters for the read/write fileset. .PP If Release Replication is used, the \*Lfts release\*O command must be used to place a read-only replica at the replication site defined on the same File Server machine as the source fileset. The Replication Servers at the fileset's other replication sites then copy the replica to the sites on their respective machines. If Scheduled Replication is used, the Replication Servers at the replication sites automatically copy the source fileset to their sites. Immediate updates to sites using either type of replication can be forced with the \*Lfts update\*O command. .PP .zA "enh,R1.0.2,Clarify small details" Use the \*Lfts aggrinfo\*O command to check the available space on an aggregate before adding it as a replication site. (Use the \*Lfts lsft\*O command to check the size of the read/write fileset.) Use the \*Lfts rmsite\*O command to remove a replication site and to instruct the Replication Server to remove the replica stored at the site. Use the \*Lfts lsreplicas\*O command to determine the status of the read-only replica at a site. .zZ "enh,R1.0.2,Clarify small details" .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.fl\*O files on all Fileset Database machines or must own the server entry for each machine on which a version of the source fileset specified with the \*L\-fileset\*O option resides. .SH "EXAMPLES" .PP .zA "defect,7715,R1.0.3,Correct sysname examples" The following command defines a read-only site for the fileset \*Lrs_aix32.bin\*O. The site is defined as the aggregate whose device name is \*L/dev/lv01\*O on the File Server machine named \*Lfs3\*O. .iS \*C$\*O \*Lfts addsite rs_aix32.bin /.../abc.com/hosts/fs3 /dev/lv01\*O .iE .zZ "defect,7715,R1.0.3,Correct sysname examples" .SH "RELATED INFORMATION" .PP Commands: \*Lfts lsreplicas(1m)\*O, \*Lfts release(1m)\*O, \*Lfts rmsite(1m)\*O, \*Lfts setrepinfo(1m)\*O, \*Lfts update(1m)\*O .PP Files: \*Ldfstab(4)\*O .iX "-]" "\*Lfts\*O command suite" "\*Laddsite\*O" .iX "-]" "replication" "defining sites" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts aggrinfo" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .SH NAME .iX "-[" "\*Lfts\*O command suite" "\*Laggrinfo\*O" .iX "-[" "aggregates" "disk space information" .iX "-[" "disk space" "aggregates and partitions" .PP \*Lfts aggrinfo\*O \- Displays disk space information about aggregates and partitions exported from a File Server machine .SH "SYNOPSIS" .sS \*Lfts aggrinfo -server \*Vmachine\*O [\*L\-aggregate \*Vname\*O] [\*L\-cell \*Vcellname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] .nL [\*L\-verbose\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the File Server machine about whose aggregates and partitions information is to be displayed. Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-aggregate \*Vname\*O" Specifies the device name, aggregate name, or aggregate ID of an exported aggregate or partition about which information is to be displayed. These identifiers are specified in the first, second, and fourth fields of the entry for the aggregate or partition in the \*Edcelocal\*L/var/dfs/dfstab\*O file. If this option is omitted, information is provided about all of the exported aggregates and partitions on the specified machine. .LI "\*L\-cell \*Vcellname\*O" Specifies the cell where the command is to be run. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,6223,R1.0.2,df works on LFS aggregates" The \*Lfts aggrinfo\*O command lists information about the total amount of disk space and the amount of disk space currently available on exported aggregates and partitions. The \*L\-server\*O option is used to specify the File Server machine on which the aggregates and partitions reside. The \*L\-aggregate\*O option can be used to specify a single aggregate or partition about which information is to be displayed. If this option is omitted, information about all aggregates and partitions exported from the specified server is displayed. (Much of the information displayed by the \*Lfts aggrinfo\*O command is specified in the \*Edcelocal\*L/var/dfs/dfstab\*O file.) .PP The \*Lfts aggrinfo\*O command displays roughly the same information as the \*Ldf\*O command available in the UNIX operating system. The \*Ldf\*O command can also be used to display information about exported DCE LFS aggregates and locally mounted DCE LFS filesets. .zZ "defect,6223,R1.0.2,df works on LFS aggregates" .PP The \*Lfts lsaggr\*O command can also be used to list all of the aggregates and partitions exported from a File Server machine. .zA "defect,5933,R1.0.2,Reinstate priv. required sections" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Reinstate priv. required sections" .SH "OUTPUT" .PP The \*Lfts aggrinfo\*O command displays a separate line for each aggregate or partition. Each line displays the following information: .ML .zA "defect,8118,R1.1,Work release notes into documentation" .LI The file system type (\*CLFS\*O for a DCE LFS aggregate, or \*CNon-LFS\*O for a non-LFS partition). .LI The aggregate name. .LI The device name. .LI The number of kilobytes of disk space currently available for use on the aggregate or partition. .LI The total number of kilobytes on the aggregate or partition (not including any reserved disk space). .LI The number of kilobytes, if any, of reserved disk space on the aggregate or partition. DCE LFS reserves a variable amount of disk space on each aggregate for internal purposes (for example, to accommodate additional space required for fileset move and clone operations). Some non-LFS implementations also reserve some amount of overdraw disk space for administrative purposes. .zZ "defect,8118,R1.1,Work release notes into documentation" .LE .PP .zA "defect,6223,R1.0.2,df works on LFS aggregates" The \*Lfts aggrinfo\*O and UNIX \*Ldf\*O commands produce essentially the same information. .zZ "defect,6223,R1.0.2,df works on LFS aggregates" .SH "EXAMPLES" .PP The following example displays information about the disk space available on all aggregates and partitions exported from the File Server machine named \*L/.../abc.com/hosts/fs1\*O: .iS \*C$ \*Lfts aggrinfo /.../abc.com/hosts/fs1\*O .iE .zA "defect,8118,R1.1,Work release notes into documentation" .oS \*CNon-LFS aggregate /usr (/dev/lv02): 24048 K free out of total 98304 \ \ \ \ \ (10923 reserved) Non-LFS aggregate /tmp (/dev/lv03): 11668 K free out of total 12288 \ \ \ \ \ (1365 reserved) LFS aggregate lfs1 (/dev/lfs1): 100537 K free out of total 101340 \ \ \ \ \ (2048 reserved) LFS aggregate lfs2 (/dev/lfs2): 71957 K free out of total 73728 \ \ \ \ \ (2048 reserved)\*O .oE .zZ "defect,8118,R1.1,Work release notes into documentation" .SH "RELATED INFORMATION" .PP Commands: \*Lfts lsaggr(1m)\*O .PP Files: \*Ldfstab(4)\*O .iX "-]" "\*Lfts\*O command suite" "\*Laggrinfo\*O" .iX "-]" "aggregates" "disk space information" .iX "-]" "disk space" "aggregates and partitions" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\"Copyright (C) 1989, 1991, Transarc Corporation ...\"The Gulf Tower ...\"707 Grant Street ...\"Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "fts apropos" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lfts\*O command suite" "\*Lapropos\*O" .SH NAME .PP \*Lfts apropos\*O \- Shows each help entry containing a specified string .SH "SYNOPSIS" .PP .sS \*Lfts apropos -topic\*O \*Vstring\*O \*O[\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-topic \*Vstring\*O" Specifies the keyword string for which to search. If it is more than a single word, surround the string with \*L"\|"\*O (double quotes) or other delimiters. Type all strings for \*Lfts\*O commands in all lowercase letters. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts apropos\*O command displays the first line of the online help entry for any \*Lfts\*O command containing the string specified by \*L-topic\*O in its name or short description. .PP To display the syntax for a command, use the \*Lfts help\*O command. .SS "Privilege Required" .PP No privileges are required. .SH "OUTPUT" .PP The first line of an online help entry for a command lists the command and briefly describes its function. This command displays the first line for any \*Lfts\*O command where the string specified by \*L-topic\*O is part of the command name or the first line. .SH "EXAMPLES" .PP The following command lists all \*Lfts\*O commands that have the word \*Lmount\*O in their names or short descriptions: .iS \*C$ \*Lfts apropos mount\*O .iE .oS crmount: make mount point delmount: remove mount point lsmount: list mount point .oE .SH "RELATED INFORMATION" .PP Commands: \*Lfts help(1m)\*O .iX "-]" "\*Lfts\*O command suite" "\*Lapropos\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts clone" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Lclone\*O" .iX "-[" "filesets" "creating backup" .SH NAME \*Lfts clone\*O \- Creates a backup version of a read/write DCE LFS fileset .SH "SYNOPSIS" .sS \*Lfts clone -fileset\*O {\*Vname\*O | \*VID\*O} [\*L\-cell \*Vcellname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-verbose\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-fileset\*O {\*Vname\*O | \*VID\*O}" Specifies the complete name or fileset ID number of the read/write source fileset. .LI "\*L\-cell \*Vcellname\*O" Specifies the cell where the command is to be run. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,8607,R1.0.3,Backing up non-LFS filesets" This command creates a backup version, or clone, of the indicated read/write DCE LFS fileset. It names the new backup version by adding a \*L.backup\*O extension to the name of the read/write source fileset. It places the backup version at the same site (File Server machine and aggregate) as the read/write version. The \*Lfts clone\*O command \*Ecannot\*O backup non-LFS filesets. .zZ "defect,8607,R1.0.3,Backing up non-LFS filesets" .PP If no backup version exists, the command changes the status flag for the backup version in the fileset's entry in the Fileset Location Database (FLDB) to \*Lvalid\*O. It also increments the number of fileset entries recorded as residing on the File Server machine in the FLDB entry for the server. .PP If a backup version already exists, the new clone replaces it. The status flag for the backup version remains \*Lvalid\*O, and the number of fileset entries recorded in the File Server machine's FLDB entry remains unchanged. .zA "defect,5623,R1.0.2,Remove local mounting restriction" .zZ "defect,5623,R1.0.2,Remove local mounting restriction" .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.ft\*O file on the machine on which the read/write copy of the fileset is stored. The issuer must also be listed in the \*Ladmin.fl\*O files on all Fileset Database machines or own the server entry for each machine on which a version of the fileset resides. .SH "EXAMPLES" .PP The following command creates a backup version of the fileset \*Luser.smith\*O: .iS \*C$\*O \*Lfts clone user.smith\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lfts clonesys(1m)\*O .iX "-]" "\*Lfts\*O command suite" "\*Lclone\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts clonesys" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Lclonesys\*O" .SH NAME .PP \*Lfts clonesys\*O \- Creates backup versions of all indicated read/write DCE LFS filesets .SH "SYNOPSIS" .sS \*Lfts clonesys\*O [\*L\-prefix \*Vstring\*O] [\*L\-server \*Vmachine\*O] [\*L\-aggregate \*Vname\*O] [\*L\-cell \*Vcellname\*O] .nL [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-verbose\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-prefix \*Vstring\*O" Specifies a character string of any length. Every fileset with a name matching this string is cloned. Include field separators (such as periods) if appropriate. This option can be combined with \*L\-server\*O, \*L\-aggregate\*O, or both. Omit all three options to back up all filesets in the local cell. .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Specifies the File Server machine where the read/write source filesets are stored. Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. This option can be combined with \*L\-prefix\*O, \*L\-aggregate\*O, or both. Omit all three options to back up all filesets in the local cell. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-aggregate \*Vname\*O" Specifies the device name, aggregate name, or aggregate ID of the aggregate on \*L\-server\*O where the read/write source filesets are stored. These identifiers are specified in the first, second, and fourth fields of the entry for the aggregate in the \*Edcelocal\*L/var/dfs/dfstab\*O file. This option can be combined with \*L\-server\*O, \*L\-prefix\*O, or both. Omit all three options to back up all filesets in the local cell. The \*L\-server\*O option must be specified if this option is used. .LI "\*L\-cell \*Vcellname\*O" Specifies the cell where the command is to be run. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,8607,R1.0.3,Backing up non-LFS filesets" The \*Lfts clonesys\*O command creates a backup version, or clone, of each indicated read/write DCE LFS fileset. It names each backup version by adding a \*L.backup\*O extension to the name of its read/write source fileset. It places each backup version at the same site (File Server machine and aggregate) as its read/write version. The \*Lfts clonesys\*O command \*Ecannot\*O backup non-LFS filesets. .zZ "defect,8607,R1.0.3,Backing up non-LFS filesets" .PP If no backup version of a fileset exists, the command changes the status flag for the backup version in the fileset's entry in the Fileset Location Database (FLDB) to \*Lvalid\*O. It also increments the number of fileset entries recorded as residing on the File Server machine in the FLDB entry for the server. .PP If a backup version of a fileset already exists, the new clone replaces it. The status flag for the backup version remains \*Lvalid\*O, and the number of fileset entries recorded in the File Server machine's FLDB entry remains unchanged. .PP .zA "defect,8607,R1.0.3,Backing up non-LFS filesets" The \*Lfts clonesys\*O command returns a \*L0\*O if all DCE LFS filesets were successfully backed up, regardless of whether back ups of any non-LFS filesets were attempted. The command returns a \*L1\*O if one or more DCE LFS filesets could not be backed up or if only backups of non-LFS filesets were attempted. .zZ "defect,8607,R1.0.3,Backing up non-LFS filesets" .PP By combining the \*L\-prefix\*O, \*L\-server\*O, and \*L\-aggregate\*O options, you can create backup copies of different subsets of read/write filesets. To back up .ML .LI All filesets in the local cell, specify no options .LI All filesets in the local cell with a name beginning with the same character string (for example, \*Lsys.\*O or \*Luser.\*O), specify the string with the \*L\-prefix\*O option .LI All filesets on a File Server machine, specify the machine's name with the \*L\-server\*O option .LI Filesets on a specific aggregate on a File Server machine, specify both the \*L\-server\*O and \*L\-aggregate\*O options .LI Filesets with a certain prefix on a specific File Server machine, specify both the \*L\-prefix\*O and \*L\-server\*O options .LI Filesets with a certain prefix on a specific aggregate on a File Server machine, specify the \*L\-prefix\*O, \*L\-server\*O, and \*L\-aggregate\*O options .LE .PP Use the \*Lfts clone\*O command to back up a single read/write DCE LFS fileset. .zA "defect,5623,R1.0.2,Remove local mounting restriction" .zZ "defect,5623,R1.0.2,Remove local mounting restriction" .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.ft\*O files on all machines on which read/write versions of the filesets are stored. The issuer must also be listed in the \*Ladmin.fl\*O files on all Fileset Database machines or own the server entry for each machine on which a version of any fileset to be backed up resides. .zA "defect,8607,R1.0.3,Backing up non-LFS filesets" .SH "OUTPUT" .PP If the \*Lfts clonesys\*O command fails to back up either one or more DCE LFS filesets or one or more non-LFS filesets, the command displays the following output: .oS Total FLDB entries that were successfully backed up: .nL x (y failed; z wrong aggr type) .oE .PP The variable \*Cx\*O indicates the number of DCE LFS filesets that were successfully backed up. The variable \*Cy\*O indicates the number of DCE LFS filesets that could not be backed up. The variable \*Cz\*O indicates the number of non-LFS filesets that the command attempted to back up, but could not because of the command's inability to back up non-LFS filesets. .zZ "defect,8607,R1.0.3,Backing up non-LFS filesets" .SH "EXAMPLES" .PP The following example creates a backup version of each fileset in the local cell whose name begins with the prefix \*Luser.\*O: .iS \*C$\*O \*Lfts clonesys -prefix user.\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lfts clone(1m)\*O .PP Files: \*Ldfstab(4)\*O .iX "-]" "\*Lfts\*O command suite" "\*Lclonesys\*O" .iX "-]" "filesets" "creating backup" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts create" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Lcreate\*O" .iX "-[" "filesets" "creating" .SH NAME .PP \*Lfts create\*O \- Creates a read/write DCE LFS fileset and associated FLDB entry .SH "SYNOPSIS" .sS \*Lfts create -ftname \*Vname\*L -server \*Vmachine\*L -aggregate \*Vname\*O [\*L\-cell \*Vcellname\*O] .nL [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-verbose\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-ftname \*Vname\*O" Specifies a name for the read/write fileset. The name must be unique within the local cell, and it should be indicative of the fileset's contents. The following characters can be included in the name of a fileset: .ML .LI All uppercase and lowercase alphabetic characters (a to z, and A to Z) .LI All numerals (0 to 9) .LI The . (period) .LI The - (dash) .LI The _ (underscore) .LE .PP .zA "defect,10752,R1.1,Minor technical clarification" The name must contain at least one alphabetic character or an _ (underscore) to differentiate it from an ID number. It can be no longer than 102 characters. This length does not include the \*L.readonly\*O or \*L.backup\*O extension, which is added automatically when a read-only or backup version of the fileset is created. Note that the \*L.readonly\*O and \*L.backup\*O extensions are reserved for use with read-only and backup filesets, so you cannot specify a fileset name that ends with either of these extensions. .zZ "defect,10752,R1.1,Minor technical clarification" .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the File Server machine on which to create the new read/write fileset. A server entry for the machine must already exist. Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-aggregate \*Vname\*O" Specifies the device name, aggregate name, or aggregate ID of the aggregate where the read/write fileset is to be stored. These identifiers are specified in the first, second, and fourth fields of the entry for the aggregate in the \*Edcelocal\*L/var/dfs/dfstab\*O file. .LI "\*L\-cell \*Vcellname\*O" Specifies the cell where the command is to be run. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts create\*O command creates a read/write DCE LFS fileset, names it as specified by \*L\-ftname\*O, and places it at the site specified by \*L\-server\*O and \*L\-aggregate\*O. The FL Server creates an entry for the fileset in the Fileset Location Database (FLDB) and allocates the fileset a unique ID number, which is recorded in both the fileset's FLDB entry and its fileset header. It also sets the status flag recorded for the read/write site in the fileset's FLDB entry to \*Lvalid\*O and increments the number of fileset entries recorded as residing on the specified File Server machine in the FLDB entry for the server. A server entry must exist in the FLDB for the File Server machine before this command is issued. .PP The FL Server also allocates and stores in the entry for the fileset in the FLDB the fileset ID numbers for the read-only and backup versions of the fileset that can be created later. It does not create these types of filesets or place anything at a read-only or backup site, so the status flags for the read-only and backup versions are set to \*Linvalid\*O. .PP If this command succeeds, the fileset is available for use. It must be mounted in the file system with the \*Lfts crmount\*O command for its contents to be visible in the global namespace. The command creates an empty root directory in the fileset, which becomes visible when the fileset is mounted. It records null ACLs as the default for use by the directory. (Although, due to the interaction between ACLs and UNIX mode bits, the directory has a set of implicit initial ACLs granting permissions to different users and groups.) .PP .zA "defect,10439,R1.1,Fix cross-references for DFS reorganization" When a cell is initially configured, the \*Lfts create\*O command is used to create the cell's main read/write fileset, \*Lroot.dfs\*O. Although \*Lroot.dfs\*O can be a non-LFS fileset, it must be a DCE LFS fileset if functionality such as replication is to be available in the cell. Part 1 of the \*(Ad provides information about configuring the root fileset to support replication. .zZ "defect,10439,R1.1,Fix cross-references for DFS reorganization" .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.ft\*O file on the machine specified by \*L\-server\*O. The issuer must also be listed in the \*Ladmin.fl\*O files on all Fileset Database machines or own the server entry for the machine specified by \*L\-server\*O. .SH "EXAMPLES" .PP The following command creates the read/write fileset \*Luser.pat\*O. The fileset is created on the aggregate \*L/dev/lv01\*O on the File Server machine \*Lfs4\*O. .iS \*C$\*O \*Lfts create user.pat /.../abc.com/hosts/fs4 /dev/lv01\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lfts crfldbentry(1m)\*O, \*Lfts crmount(1m)\*O .PP Files: \*Ldfstab(4)\*O .iX "-]" "\*Lfts\*O command suite" "\*Lcreate\*O" .iX "-]" "filesets" "creating" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts crfldbentry" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Lcrfldbentry\*O" .iX "-[" "Fileset Location Database" "registering filesets" .iX "-[" "filesets" "registering" .SH NAME .PP \*Lfts crfldbentry \*O \- Creates a fileset entry in the FLDB .SH "SYNOPSIS" .sS .PP \*Lfts crfldbentry -ftname \*Vname\*L -server \*Vmachine\*L -aggrid \*VID\*O [\*L\-cell \*Vcellname\*O] .nL [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-verbose\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-ftname \*Vname\*O" Specifies a name for the fileset. The name must be unique within the local cell, and it should be indicative of the fileset's contents. The following characters can be included in the name of a fileset: .ML .LI All uppercase and lowercase alphabetic characters (a to z, and A to Z) .LI All numerals (0 to 9) .LI The . (period) .LI The - (dash) .LI The _ (underscore) .LE .PP .zA "defect,10752,R1.1,Minor technical clarification" The name must contain at least one alphabetic character or an _ (underscore) to differentiate it from an ID number. It can be no longer than 102 characters. (Fileset names are restricted to this limit to accommodate the \*L.readonly\*O and \*L.backup\*O extensions that DCE LFS filesets of those types receive. Note that the \*L.readonly\*O and \*L.backup\*O extensions are reserved for use with read-only and backup DCE LFS filesets, so you cannot specify a fileset name that ends with either of these extensions.) .zZ "defect,10752,R1.1,Minor technical clarification" .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the File Server machine on which the fileset resides. Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-aggrid \*VID\*O" Specifies the aggregate ID number to be assigned to the aggregate or partition in the Fileset Location Database (FLDB). The number specified with this option must also be used as the aggregate ID in the fourth field of the entry for the aggregate or partition in the \*Edcelocal\*L/var/dfs/dfstab\*O file on the machine where the aggregate or partition resides. The ID number must be a positive integer. If the command is being used to create an FLDB entry for a non-LFS fileset (its typical use), the specified number must not already be in use in the \*Ldfstab\*O file on the specified \*L\-server\*O. .LI "\*L\-cell \*Vcellname\*O" Specifies the cell where the command is to be run. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts crfldbentry\*O command is used to register a fileset in the FLDB. After the fileset is registered, its location can be tracked by the FL Server. The command is typically used to create FLDB entries for non-LFS filesets. .PP Use the \*L\-ftname\*O option to specify a name for the fileset according to the guidelines presented with the description of the \*L\-ftname\*O option. Use the \*L\-server\*O option to indicate the File Server machine that houses the aggregate or partition on which the fileset resides. Use the \*L\-aggrid\*O option to specify an aggregate ID number to be associated with the aggregate or partition in the FLDB. This same number must be used in the entry for the aggregate or partition in the \*Ldfstab\*O file on \*L\-server\*O; choose a number that is not already in use in the machine's \*Ldfstab\*O file. .PP The FL Server allocates a unique fileset ID number for the fileset. This number, along with ID numbers allocated for read-only and backup filesets, is returned by the command. When creating an entry for a non-LFS fileset, the ID number allocated for the read-write fileset must be specified in the fifth field of the entry in the \*Ldfstab\*O file for the partition on which the fileset resides. .PP The FL Server also sets the status flag for the read-write version in the fileset's entry to \*Lvalid\*O. In addition, it increments the number of fileset entries recorded as residing on the specified File Server machine in the FLDB entry for the server. A server entry must exist in the FLDB for the File Server machine before this command is issued. .PP After issuing this command to register a non-LFS fileset, create an entry for the partition on which the fileset resides in the local \*Ldfstab\*O file, export the partition with the \*Ldfsexport\*O command, and mount the fileset with the \*Lfts crmount\*O command to make the fileset accessible in the DCE namespace. The \*Lfts crserverentry\*O command must be used before this command to create a server entry in the FLDB for the machine on which the fileset resides. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.fl\*O files on all Fileset Database machines or own the server entry for the machine specified by \*L\-server\*O. .SH "EXAMPLES" .PP The following example creates an entry in the FLDB for a non-LFS fileset named \*Luser.jlw\*O. The fileset is located on the File Server machine named \*Lfs3\*O. The aggregate ID of the partition the fileset resides on is \*L7\*O. .iS \*C$\*O \*Lfts crfldbentry user.jlw /.../abc.com/hosts/fs3 7\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Ldfsexport(1m)\*O, \*Lfts create(1m)\*O, \*Lfts crserverentry(1m)\*O, \*Lfts crmount(1m)\*O .PP Files: \*Ldfstab(4)\*O .iX "-]" "\*Lfts\*O command suite" "\*Lcrfldbentry\*O" .iX "-]" "Fileset Location Database" "registering filesets" .iX "-]" "filesets" "registering" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts crmount" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Lcrmount\*O" .iX "-[" "mount points" "creating" .iX "-[" "filesets" "mounting" .SH NAME .PP \*Lfts crmount\*O \- Creates a mount point for a fileset .SH "SYNOPSIS" .sS .zA "defect,8462,R1.0.3,Remove fts crmount -cell option" \*Lfts crmount -dir \*Vdirectory_name\*O {\*L-fileset\*O {\*Vname \*O|\*V ID\*O} | \*L-global\*O} [\*L-rw\*O] .nL [\*L-fast\*O] [\*L-help\*O] .zZ "defect,8462,R1.0.3,Remove fts crmount -cell option" .sE .SH "OPTIONS" .VL .LI "\*L-dir \*Vdirectory_name\*O" Names the location in the file tree at which the root directory of the fileset is to be mounted. The specified location becomes the fileset's mount point. The specified mount point must not already exist, but the parent directory of the mount point must exist in the DFS filespace. .LI "\*L-fileset\*O {\*Vname\*O | \*VID\*O}" Specifies the complete name or fileset ID number of the fileset to be mounted. The mount point for the fileset is created at the location specified with the \*L-dir\*O option. The read/write, read-only, or backup version of the fileset can be named. Use this option or use the \*L-global\*O option. .zA "enh, 10306, R1.1, remove diskless documentation" .LI "\*L-global\*O" Specifies that the mount point named with the \*L-dir\*O option is for the root of the DCE global namespace (a global root mount point). Use this option or use the \*L\-fileset\*O option. Do not use the \*L\-global\*O option under normal circumstances; it is maintained to provide backward compatibility with other file systems (for example, AFS). .cS .zA "defect,7219,R1.0.2,Review comments" Specifies that the mount point is for the root of the DCE global namespace (a global root mount point). When preparing a fileset for use as the top-level fileset for diskless machines, use this option to create a mount point for the root of the DCE global namespace under the top-level diskless directory. The mount point for the root of the DCE namespace is specified with \*L-dir\*O. Use this option only when preparing a fileset for use as the top-level diskless fileset. .zZ "defect,7219,R1.0.2,Review comments" .cE .zZ "enh, 10306, R1.1, remove diskless documentation" .zA "defect,8462,R1.0.3,Remove fts crmount -cell option" .zZ "defect,8462,R1.0.3,Remove fts crmount -cell option" .LI "\*L-rw\*O" .zA "defect,9568,R1.1,Clarify pathname traversal" Specifies the type of the mount point as read/write. By default, a mount point is regular. If this option is used, the \*L-fileset\*O option must specify the read/write version of the fileset. .PP An important function of the \*L-rw\*O option is to mount a cell's main read/write fileset, \*Lroot.dfs\*O, below the top-level of the cell's DFS filespace. The option must be used in this capacity at installation if replication is to be available in the cell. See the description section for more information about the different types of mount points and about using the \*L-rw\*O option to create a read/write mount point for the fileset \*Lroot.dfs\*O. .zZ "defect,9568,R1.1,Clarify pathname traversal" .LI "\*L-fast\*O" .zA "defect,8462,R1.0.3,Remove fts crmount -cell option" .zA "defect,5042,R1.0.2,Provide text for additional -fast functionality" Directs \*Lfts\*O not to verify the existence of the fileset indicated with the \*L-fileset\*O option. Use this option to create a mount point for a fileset that does not yet exist. .PP By default, \*Lfts\*O contacts the Fileset Location (FL) Server for the cell that houses the parent directory of the name supplied with the \*L\-dir\*O option to verify that the FLDB contains an entry for the fileset to be mounted. If no FLDB entry exists for the specified fileset, the command displays a warning. The specified mount point is always created, regardless of whether the \*L-fast\*O option is provided; the option simply suppresses the check and any possible warnings. .zZ "defect,5042,R1.0.2,Provide text for additional -fast functionality" .zZ "defect,8462,R1.0.3,Remove fts crmount -cell option" .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,9568,R1.1,Clarify pathname traversal" The \*Lfts crmount\*O command creates a mount point for the fileset specified with the \*L-fileset\*O option at the location in the file tree specified with the \*L-dir\*O option. The mount point makes the contents of the specified fileset visible and accessible to users. Once this command is used to mount a fileset, no further actions need to be taken to mount the fileset and the fileset never needs to be mounted again. .PP A mount point is actually a special symbolic link that acts as an association between a directory location and a fileset. Mount points look and function like standard directories. When the Cache Manager encounters a mount point in a pathname traversal, it determines which fileset is associated with the mount point. When it finds that fileset, it can access files or directories contained in the fileset's root directory. It traverses any paths leading through directories or other mount points in the fileset until it finds the directory or file indicated by the pathname. .PP .zA "defect,8462,R1.0.3,Remove fts crmount -cell option" To a large extent, the type of a mount point determines the version of a fileset through which the Cache Manager searches for a requested directory or file. By default, every mount point created by the \*Lfts crmount\*O command is a regular mount point, which is the most common type of mount point. However, if you include the \*L\-rw\*O option with the command, the command creates a read/write mount point. .zZ "defect,8462,R1.0.3,Remove fts crmount -cell option" .PP When the Cache Manager encounters a regular mount point, it checks the version of the fileset that the mount point indicates. If the mount point indicates the read-only or backup version of the fileset, the Cache Manager accesses that version. If the mount point indicates the read/write version of the fileset, the Cache Manager considers the fileset in which the mount point resides and acts accordingly, as follows: .ML .LI If a regular mount point that names a read/write fileset resides in a read-only fileset, the Cache Manager first determines whether the fileset is replicated. If the fileset is not replicated, the Cache Manager attempts to access the read/write version of the fileset; if the read/write version does not exist or is inaccessible, the Cache Manager cannot access the fileset. If the fileset is replicated, the Cache Manager attempts to access a read-only version of the fileset; if all of the read-only copies are unavailable, the Cache Manager cannot access the fileset (it does not attempt to access the read/write version of the fileset). .LI If a regular mount point that names a read/write fileset resides in a read/write fileset, the Cache Manager attempts to access only the read/write version of the fileset. If the read/write version does not exist or is inaccessible, the Cache Manager cannot access the fileset. .LE .PP When the Cache Manager encounters a read/write mount point, it attempts to access only the read/write version of the fileset, regardless of the type of fileset in which the mount point resides. If the read/write version of the fileset does not exist or is inaccessible, the Cache Manager cannot access the fileset. .PP Regular mount points promote greater fileset availability than read/write mount points because they allow the Cache Manager to access read-only filesets as often as possible. Because multiple copies of read-only filesets typically exist, regular mount points generally increase fileset availability. Conversely, because only a single version of a read/write fileset can exist, read/write mount points generally reduce fileset availability. .PP You typically mount filesets with regular mount points. A regular mount point is explicitly not a "read-only" mount point. Although the Cache Manager attempts to access a read-only version of a fileset when it encounters a regular mount point, it accesses the read/write version of the fileset if no read-only versions of the fileset exist or if it is traversing a read/write path (that is, if it accessed the mount point in a read/write fileset). .zZ "defect,9568,R1.1,Clarify pathname traversal" .PP During a cell's configuration, an important function of the \*Lfts crmount\*O command is to create a mount point for the cell's main read/write fileset, \*Lroot.dfs\*O. The command must be used with the \*L-rw\*O option to create an explicit read/write mount point for the fileset below the top-level of the cell's DFS filespace. The mount point for the fileset must be created at \*L/.../\*Ecellname\*L/fs/.rw\*O. .PP The \*Lroot.dfs\*O fileset is the first fileset mounted in a cell. The Cache Manager automatically mounts it at the top-level of the cell's DFS filespace (\*L/.../\*Ecellname\*L/fs\*O by default, but it can be defined as something else). It must be created as a DCE LFS fileset with the \*Lfts create\*O command if functionality such as replication is to be available in the cell. .PP .zA "defect,10439,R1.1,Fix cross-references for DFS reorganization" Once the \*Lroot.dfs\*O fileset is mounted with a read/write mount point, it can be replicated. Replication is then available for DCE LFS filesets in the cell. If \*Lroot.dfs\*O is replicated before its read/write mount point is created with the \*Lfts crmount\*O command, the read/write version of \*Lroot.dfs\*O cannot be accessed in the cell. Part 1 of the \*(Ad provides information about configuring \*Lroot.dfs\*O to support replication. .zZ "defect,10439,R1.1,Fix cross-references for DFS reorganization" .SS "Privilege Required" .PP .zA "defect,7219,R1.0.2,Review comments" If the parent directory of the mount point (the directory in which the mount point is to be created) is in a DCE LFS fileset, the issuer must have write, execute, control, and insert permissions on the directory. If the parent directory is in a non-LFS fileset, the issuer must have write and execute permissions on the directory. .zZ "defect,7219,R1.0.2,Review comments" .SH "CAUTIONS" .PP .iX "mount points" "multiple" Do not mount a fileset at more than one location in the file system. Creating multiple mount points can distort the hierarchical nature of the file system. Because the Cache Manager stores only a single pointer to the parent directory of the mount point for each fileset, it can become confused about which pathname to follow when searching for a file in a fileset with multiple mount points. This is true even if the full pathname of a file is specified. .PP Create multiple mount points for a fileset sparingly, only in a very limited number of troubleshooting and testing situations. Remove the extraneous mount points as soon as they are no longer necessary. .PP .zA "defect,9568,R1.1,Clarify pathname traversal" Do not create a symbolic link that begins with a \*L#\*O (number sign) or a \*L%\*O (percent sign) character. Because a mount point is a special type of symbolic link that uses these characters internally to identify its type, the Cache Manager becomes confused if it encounters a normal symbolic link that begins with one of these characters. .zZ "defect,9568,R1.1,Clarify pathname traversal" .SH "EXAMPLES" .PP The following command creates a regular mount point (the default type of mount point) for the read/write fileset named \*Luser.jlw\*O at the directory named \*L/.../abc.com/fs/usr/jlw\*O: .iS \*C$\*O \*Lfts crmount /.../abc.com/fs/usr/jlw user.jlw\*O .iE .zA "defect,8462,R1.0.3,Remove fts crmount -cell option" .zZ "defect,8462,R1.0.3,Remove fts crmount -cell option" .zA "enh, 10306, R1.1, remove diskless documentation" .cS .PP .zA "defect,7219,R1.0.2,Review comments" The next two commands create mount points for the read/write fileset \*Ldiskless.root\*O and the root of the DCE global namespace under the top-level directory of the fileset. These steps are necessary if the fileset is to serve as the top-level diskless fileset (to be used as the root directory by diskless machines). The first command creates a mount point for the top-level diskless fileset at \*L/.../abc.com/fs/diskless.root\*O. The second command creates a mount point for the root of the DCE namespace (/...) beneath the top-level directory of the diskless fileset. .zZ "defect,7219,R1.0.2,Review comments" .iS \*C$\*O \*Lfts crmount /.../abc.com/fs/diskless.root diskless.root\*O .iE .iS \*C$\*O \*Lfts crmount /.../abc.com/fs/diskless.root/... -global\*O .iE .cE .zZ "enh, 10306, R1.1, remove diskless documentation" .PP The following command creates a read/write mount point for the fileset named \*Lroot.dfs\*O in the cell \*Labc.com\*O. The fileset is mounted at \*L.rw\*O, immediately below the top-level of the cell's DFS filespace. .iS \*C$\*O \*Lfts crmount /.../abc.com/fs/.rw root.dfs -rw\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Ldfsd(1m)\*O, \*Lfts create(1m)\*O, \*Lfts delmount(1m)\*O, \*Lfts lsmount(1m)\*O .iX "-]" "\*Lfts\*O command suite" "\*Lcrmount\*O" .iX "-]" "mount points" "creating" .iX "-]" "filesets" "mounting" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" CHANGED ...\" 12-09-91: Modified the description of the -quota option. ...\" END CHANGED ...\" .rm zA .rm zZ .TH "fts crserverentry" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Lcrserverentry\*O" .iX "-[" "Fileset Location Database" "creating server entries" .iX "-[" "server machines" "FLDB entries" .SH NAME .PP \*Lfts crserverentry\*O \- Creates a server entry in the FLDB .SH "SYNOPSIS" .sS .zA "defect,5778,R1.0.3,Use of short forms of machine names" .zA "defect,5313,R1.0.2,Remove -fxdid option" \*Lfts crserverentry -server\*O \*Vmachine\*O \*L\-principal \*Vname\*O [\*L\-quota \*Ventries\*O] .nL [\*L\-owner \*Vgroup\*O] [\*L\-cell \*Vcellname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-verbose\*O] [\*L\-help\*O] .zZ "defect,5313,R1.0.2,Remove -fxdid option" .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Specifies the server machine for which an entry is to be created in the Fileset Location Database (FLDB). Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-principal \*Vname\*O" .zA "defect,8084,R1.0.3,Correct description of -principal option" Specifies the abbreviation for the DFS server principal to be registered in the FLDB for the machine (for example, \*Lhosts/\*Vhostname\*O). The machine's principal name in the Registry Database must match this name. .zZ "defect,8084,R1.0.3,Correct description of -principal option" .LI "\*L\-quota \*Ventries\*O" Sets a limit on the number of fileset entries (read-write, read-only, and backup) in the FLDB that can be associated with the specified \*L\-server\*O. If this option is omitted, a value of 0 (zero) is used, meaning an unlimited number of fileset entries can be associated with the specified File Server machine. .LI "\*L\-owner \*Vgroup\*O" .zA "defect,8616,R1.0.3,Foreign groups cannot own server entries" .zA "defect,6542,R1.0.2,Improve principal/group option descriptions" .zA "defect,7219,R1.0.2,Review comments" \*L\-owner\*O \*Egroup\*O specifies the name of the group that is the owner of the server entry. A group can be specified by a full or abbreviated group name (for example, \*L/.../\*Ecellname\*L/\*Egroup_name\*O or just \*Egroup_name\*O). Foreign groups cannot own a local server entry. If this option is omitted, no group owns the server entry (the value \*L\*O is reported as the owner). .zZ "defect,7219,R1.0.2,Review comments" .zZ "defect,6542,R1.0.2,Improve principal/group option descriptions" .zZ "defect,8616,R1.0.3,Foreign groups cannot own server entries" .zA "defect,5313,R1.0.2,Remove -fxdid option" .zZ "defect,5313,R1.0.2,Remove -fxdid option" .LI "\*L\-cell \*Vcellname\*O" Specifies the cell in whose FLDB the server entry is to be created. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts crserverentry\*O command creates a server entry in the FLDB for the server machine specified with \*L\-server\*O. You must issue this command for a server machine before issuing any other \*Lfts\*O commands involving that machine (for example, before creating filesets on the machine with the \*Lfts create\*O command, before adding the machine as a replication site with the \*Lfts addsite\*O command, before moving filesets to the machine with the \*Lfts move\*O command, and so on). .PP The \*L\-quota\*O option is used to limit the number of filesets (read-write, read-only, and backup) that can reside on the specified File Server machine. When a fileset entry in the FLDB is defined to reference the File Server machine as the site of a fileset version, the FL Server increments the number of fileset entries recorded as residing on the server in its server entry. The FL Server creates no more than the specified \*L\-quota\*O of fileset entries on the server machine. .PP The following commands update the number of fileset entries recorded for a File Server machine in its server entry: The \*Lfts create\*O, \*Lfts crfldbentry\*O, \*Lfts addsite\*O, \*Lfts restore\*O, \*Lfts clone\*O, and \*Lfts clonesys\*O commands increment the number of fileset entries recorded for the server; the \*Lfts delete\*O, \*Lfts delfldbentry\*O, and \*Lfts rmsite\*O commands decrement the number of fileset entries recorded; the \*Lfts move\*O command decrements and increments the number of fileset entries recorded on the source and destination machines, respectively; and the \*Lfts syncfldb\*O and \*Lfts syncserv\*O commands can update the number of fileset entries recorded, as necessary. .PP The \*L\-owner\*O option is used to specify a group of administrators who can administer entries in the FLDB for all of the filesets on the specified File Server machine. The same group can be given ownership of all server entries for the File Server machines in the domain where the specified machine resides. Members of the group can then manipulate the FLDB entries for all of the filesets in the domain where the File Server machine resides. This way, the administrators in the group need not be included on the \*Ladmin.fl\*O list for the entire cell, which would allow them to modify all of the fileset entries in the FLDB in that cell. .PP Use the \*Lfts lsserverentry\*O command to display the current values from the FLDB for a server entry. Use the \*Lfts edserverentry\*O command to change the current values in the FLDB for a server entry. Use the \*Lfts delserverentry\*O command to remove a server entry from the FLDB. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.fl\*O files on all Fileset Database machines. .SH "EXAMPLES" .PP .zA "defect,8084,R1.0.3,Correct description of -principal option" .zA "defect,7219,R1.0.2,Review comments" The following example adds a server entry to the FLDB for a server machine named \*Lfs1\*O. The abbreviated DFS server principal of the machine is specified with the \*L\-principal\*O option as \*Lhosts/fs1\*O. Because they are omitted, the \*L\-quota\*O and \*L\-owner\*O options receive the default values of 0 (zero) and the empty group ID (displayed as \*L\*O), respectively. .zZ "defect,7219,R1.0.2,Review comments" .zZ "defect,8084,R1.0.3,Correct description of -principal option" .iS \*C$\*O \*Lfts crserverentry /.../abc.com/hosts/fs1 hosts/fs1\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lfts delserverentry(1m)\*O, \*Lfts edserverentry(1m)\*O, \*Lfts lsserverentry(1m)\*O .iX "-]" "\*Lfts\*O command suite" "\*Lcrserverentry\*O" .iX "-]" "Fileset Location Database" "creating server entries" .iX "-]" "server machines" "FLDB entries" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts delete" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Ldelete\*O" .iX "-[" "filesets" "deleting" .iX "-[" "Fileset Location Database" "deleted filesets" .SH NAME .PP \*Lfts delete\*O \- Removes a specified read/write or backup version of a DCE LFS fileset .SH "SYNOPSIS" .sS \*Lfts delete -fileset\*O {\*Vname\*O |\*VID\*O} \*L\-server \*Vmachine\*L -aggregate \*Vname\*O .nL [\*L\-cell \*Vcellname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-verbose\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-fileset\*O {\*Vname\*O | \*VID\*O}\*O" Specifies the complete name or fileset ID number of the read/write or backup fileset to be removed. Include the \*L.backup\*O extension if specifying the name of a backup fileset. .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the File Server machine from which to remove the fileset. Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-aggregate \*Vname\*O" Specifies the device name, aggregate name, or aggregate ID of the aggregate from which to remove the fileset. These identifiers are specified in the first, second, and fourth fields of the entry for the aggregate in the \*Edcelocal\*L/var/dfs/dfstab\*O file. .LI "\*L\-cell \*Vcellname\*O" Specifies the cell where the command is to be run. The default is the local cell of the issuer of the command. .LI " \*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts delete\*O command removes the read/write or backup DCE LFS fileset indicated by the \*L\-fileset\*O option from the site specified by the \*L\-server\*O and \*L\-aggregate\*O options. Versions of the fileset are removed and the Fileset Location Database (FLDB) entry for the fileset updated to record the removals as follows: .ML .LI Removing a read/write fileset automatically removes its associated backup version (if the backup version exists). If read-only versions of the fileset exist, site information for the read/write and backup versions of the fileset is removed from the fileset's FLDB entry and the status flags for both versions are set to \*Linvalid\*O (their fileset ID numbers are still recorded), but the read-only versions of the fileset are not affected. If no read-only versions of the fileset exist, the entire entry for the fileset is removed from the FLDB. .LI Removing a backup fileset removes site information for the backup version from the fileset's FLDB entry and marks the backup version as \*Linvalid\*O but does not erase its fileset ID number. Read/write and read-only versions of the fileset are not affected. .LE .PP .zA "defect,5879,R1.0.2,Remove more local-mounting restrictions" The number of fileset entries recorded in the server entry in the FLDB for the File Server machine from which a read/write or backup version of a fileset is removed is decremented once for each deleted version of the fileset. (Note that, if the indicated version of a fileset does not exist at the specified site but is referenced in the fileset's FLDB entry, the command removes site information about that version of the fileset from the fileset's entry and generally performs all other operations as indicated.) .PP .zA "enh,R1.0.2,Clarify small details" Before you remove the read/write (and backup) version of a fileset, use the \*Lfts rmsite\*O command to remove the fileset's replication sites and to instruct the Replication Server to remove the replicas stored at the sites. If Release Replication was used for the fileset, use the \*Lfts rmsite\*O command to remove the replication site and replica stored at the read/write fileset's site as well. .PP .zA "defect,7063,R1.0.2,Update local-mounting restrictions" .zA "defect,7219,R1.0.2,Review comments" After removing a fileset, use the \*Lfts delmount\*O command to remove its mount point. Note that it might be better in some cases to remove a fileset's mount point before deleting the fileset; removing the mount point first ensures that no users are accessing the fileset when it is deleted. .PP If the DCE LFS fileset to be removed is also mounted locally (as a file system on its File Server machine), you must remove its local mount point before you delete it; the \*Lfts delete\*O command cannot be used to delete a fileset that is mounted locally. In addition, because the backup version of a fileset is removed when its read/write version is removed, you cannot remove the read/write version of a fileset if its backup version is mounted locally. You must remove the backup version's local mount point before deleting the read/write version. .zZ "defect,7219,R1.0.2,Review comments" .zZ "defect,7063,R1.0.2,Update local-mounting restrictions" .zZ "enh,R1.0.2,Clarify small details" .zZ "defect,5879,R1.0.2,Remove more local-mounting restrictions" .PP The \*Lfts delfldbentry\*O command can be used to remove an FLDB entry for a fileset. Use the command only when you are certain that a fileset deletion was not recorded in the FLDB. The \*Lfts zap\*O command can be used to remove a fileset when it is urgent that the fileset be removed but the FLDB is inaccessible. When the FLDB is again accessible, use the \*Lfts delfldbentry\*O command to remove the fileset's FLDB entry or use the \*Lfts syncfldb\*O and \*Lfts syncserv\*O commands to synchronize the FLDB with the state of the filesets. .PP The \*Lfts delfldbentry\*O command is also used to remove the FLDB entry for a non-LFS fileset. The \*Lfts delmount\*O command is then used to remove its mount point, and the \*Ldfsexport\*O command is used to detach the partition it resides on from the global namespace. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.ft\*O file on the machine specified by \*L\-server\*O. The issuer must also be listed in the \*Ladmin.fl\*O files on all Fileset Database machines or own the server entry for each machine on which a version of the fileset to be deleted resides. .SH "EXAMPLES" .PP The following command deletes the read/write fileset named \*Luser.terry\*O and its backup version (if it exists) from the aggregate named \*L/dev/lv01\*O on the File Server machine named \*Lfs3\*O: .iS \*C$\*O \*Lfts delete user.terry /.../abc.com/hosts/fs3 /dev/lv01\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Ldfsexport(1m)\*O, \*Lfts delfldbentry(1m)\*O, \*Lfts delmount(1m)\*O, \*Lfts rmsite(1m)\*O, \*Lfts syncfldb(1m)\*O, \*Lfts syncserv(1m)\*O, \*Lfts zap(1m)\*O .PP Files: \*Ldfstab(4)\*O .iX "-]" "\*Lfts\*O command suite" "\*Ldelete\*O" .iX "-]" "filesets" "deleting" .iX "-]" "Fileset Location Database" "deleted filesets" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts delfldbentry" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Ldelfldbentry\*O" .iX "-[" "Fileset Location Database" "deleting fileset entries" .SH NAME .PP \*Lfts delfldbentry\*O \- Removes a specified entry from the FLDB .SH "SYNOPSIS" .sS \*Lfts delfldbentry\*O {\*L\-fileset\*O {\*Vname\*O | \*VID\*O} | \*L\-prefix \*Vstring\*O} [\*L\-server \*Vmachine\*O] .nL [\*L\-aggregate \*Vname\*O] [\*L\-cell \*Vcellname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-verbose\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-fileset\*O {\*Lname\*O | \*LID\*O}" Specifies the complete name or fileset ID number of a fileset. The entire entry for the fileset is removed from the Fileset Location Database (FLDB), regardless of whether the read-write, read-only, or backup version of the fileset is specified. Provide this option or use the \*L\-prefix\*O option. .LI "\*L\-prefix \*Vstring\*O" Specifies a character string of any length. Every FLDB entry that lists a fileset whose name begins with this exact string is removed (unless more-restrictive constraints are specified with the \*L\-server\*O and optionally \*L\-aggregate\*O options). Include field separators such as periods if appropriate. Provide this option (optionally with \*L\-server\*O and \*L\-aggregate\*O) or use the \*L\-fileset\*O option. .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names a File Server machine. If a fileset's name matches the specified \*L\-prefix\*O and it is listed as residing on the specified File Server machine, its entry is removed from the FLDB. Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. If this option is used, \*L\-prefix\*O must be used; \*L\-aggregate\*O can also be used. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" \*L\-aggregate\*O can also be used. .LI "\*L\-aggregate \*Vname\*O" Specifies the device name, aggregate name, or aggregate ID of an aggregate or partition on \*L\-server\*O. These identifiers are specified in the first, second, and fourth fields of the entry for the aggregate or partition in the \*Edcelocal\*L/var/dfs/dfstab\*O file. If a fileset's name matches the specified \*L\-prefix\*O and it resides on the specified aggregate on \*L\-server\*O, its entry is removed from the FLDB. If this option is used, \*L\-prefix\*O and \*L\-server\*O must be used. .LI "\*L\-cell \*Vcellname\*O" Specifies the cell where the command is to be run. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .iX "filesets" "removing varying numbers" .PP The \*Lfts delfldbentry\*O command removes the entries for all indicated filesets from the FLDB. Regardless of the version of a fileset (read-write, read-only, or backup) specified with the command, the fileset's entire entry is removed. The command has no effect on actual filesets on File Server machines, only on their FLDB entries. .PP The command also decrements the number of fileset entries recorded in server entries, as appropriate. For each version of a fileset whose entry is removed from the FLDB, the number of fileset entries recorded in the server entry for the File Server machine it resides on is reduced by one. .PP By using the \*L\-fileset\*O option alone or combining the \*L\-prefix\*O, \*L\-server\*O, and \*L\-aggregate\*O options in increasingly specific ways, FLDB entries can be removed for varying numbers of filesets. To remove the FLDB entry for .ML .LI A single fileset, specify \*L\-fileset\*O .LI Every fileset whose name begins with a certain character string (for example, \*Lsys.\*O or \*Luser.\*O), regardless of site, specify \*L\-prefix\*O .LI Every fileset whose name begins with a certain character string and that is stored on a specific File Server machine, specify \*L\-prefix\*O and \*L\-server\*O .LI Every fileset whose name begins with a certain character string and that is stored on a specific aggregate of a specific File Server machine, specify \*L\-prefix\*O, \*L\-server\*O, and \*L\-aggregate\*O .LE .PP This command can be used if the issuer is certain that a fileset removal is not recorded in the FLDB and does not want to take the time to synchronize an entire File Server machine. It can also be used to remove the FLDB entry for a non-LFS fileset to be removed from the global namespace. (Use the \*Lfts rmsite\*O command to remove an incorrect entry for a read-only site from the FLDB.) .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.fl\*O files on all Fileset Database machines or own the server entry for each machine that houses a version of any fileset whose FLDB entry is to be removed. .SH "CAUTIONS" .PP Do not use this command as the standard way to remove a fileset entry from the FLDB. It can make the FLDB inconsistent with the filesets on server machines. Use the \*Lfts delete\*O command to remove the fileset entry from the FLDB at the same time that the fileset is deleted. Also, because it can be used to remove multiple FLDB entries simultaneously, use this command carefully. .SH "EXAMPLES" .PP The following command removes the FLDB entry for the fileset \*Luser.temp\*O: .iS \*C$\*O \*Lfts delfldbentry user.temp\*O .iE .PP The following command removes all FLDB entries for filesets whose names begin with \*Ltest\*O and that are stored on the File Server machine named \*Lfs3\*O: .iS \*C$\*O \*Lfts delfldbentry -prefix test -server /.../abc.com/hosts/fs3\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lfts clone(1m)\*O, \*Lfts delete(1m)\*O, \*Lfts rmsite(1m)\*O, \*Lfts syncfldb(1m)\*O, \*Lfts syncserv(1m)\*O, \*Lfts zap(1m)\*O .PP Files: \*Ldfstab(4)\*O .iX "-]" "\*Lfts\*O command suite" "\*Ldelfldbentry\*O" .iX "-]" "Fileset Location Database" "deleting fileset entries" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts delmount" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "\*Lfts\*O command suite" "\*Ldelmount\*O" .iX "mount points" "deleting" .SH NAME .PP \*Lfts delmount\*O \- Removes a mount point .SH "SYNOPSIS" .sS \*Lfts delmount -dir \*Vdirectory_name\*O... [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-dir \*Vdirectory_name\*O" Names the mount point to be deleted. Provide a complete pathname. The last element in the pathname must be an actual name, not . (dot) or .. (dot dot). .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts delmount\*O command removes the mount point specified by \*L-dir\*O. The associated fileset is not affected, but it is inaccessible if no other mount points exist for it. When the mount point for a fileset is removed, any fileset mounted only as a subdirectory of the fileset's root directory becomes inaccessible. .SS "Privilege Required" .PP If \*L-dir\*O resides in a directory in a DCE LFS fileset, the issuer must have write, execute, and delete permissions on the directory in which it resides. If \*L-dir\*O resides in a directory in a non-LFS fileset, the issuer must have write and execute permissions on the directory in which it resides. .SH "EXAMPLES" .PP The following command removes the mount point for the fileset \*Luser.vijay\*O, which is mounted at \*L/.../abc.com/fs/usr/vijay\*O: .iS \*C$\*O \*Lfts delm /.../abc.com/fs/usr/vijay\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lfts crmount(1m)\*O, \*Lfts lsmount(1m)\*O .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the .\" src directory for the full copyright text. .\" ...\" ...\" .rm zA .rm zZ .TH "fts delserverentry" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Ldelserverentry\*O" .iX "-[" "Fileset Location Database" "deleting server entries" .SH NAME .PP \*Lfts delserverentry\*O \- Deletes a server entry from the FLDB .SH "SYNOPSIS" .sS .zA "defect,5778,R1.0.3,Use of short forms of machine names" \*Lfts delserverentry -server\*O \*Vmachine\*O [\*L\-cell \*Vcellname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] .nL [\*L\-verbose\*O] [\*L\-help\*O] .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .sE .SH "OPTIONS" .VL .zA "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-server\*O \*Vmachine\*O" Specifies the server machine whose entry is to be removed from the Fileset Location Database (FLDB). Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-cell \*Vcellname\*O" Specifies the cell from whose FLDB the server entry is to be removed. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts delserverentry\*O command removes the existing server entry from the FLDB for the server machine specified with \*L\-server\*O. When the command is issued, no fileset entries in the FLDB can reference the server entry to be removed as the site of a fileset. If a fileset entry in the FLDB references the server entry to be removed, the command fails. .PP Use the \*Lfts crserverentry\*O command to create a server entry in the FLDB. Use the \*Lfts lsserverentry\*O command to display the current values from the FLDB for a server entry. Use the \*Lfts edserverentry\*O command to change the current values in the FLDB for a server entry. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.fl\*O files on all Fileset Database machines. .SH "EXAMPLES" .PP The following example deletes the server entry from the FLDB for the server machine named \*Lfs1\*O. No filesets can reside on the machine when the command is issued. .iS \*C$\*O \*Lfts delserverentry /.../abc.com/hosts/fs1\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lfts crserverentry(1m)\*O, \*Lfts edserverentry(1m)\*O, \*Lfts lsserverentry(1m)\*O .iX "-]" "\*Lfts\*O command suite" "\*Ldelserverentry\*O" .iX "-]" "Fileset Location Database" "deleting server entries" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts dump" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Ldump\*O" .iX "-[" "filesets" "dumping to disk" .iX "-[" "dump files" "creating" .SH NAME .PP \*Lfts dump\*O \- Converts a fileset to a bytestream format and places it in a file .SH "SYNOPSIS" .sS .zA "defect,6447,R1.0.2,Add -server option to fts dump" \*Lfts dump -fileset\*O {\*Vname\*O | \*VID\*O} {\*L\-time\*O {\*Vdate\*O | \*V0\*O} | \*L\-version \*Vnumber\*O} [\*L\-server \*Vmachine\*O] .nL [\*L\-file \*Vfilename\*O] [\*L\-cell \*Vcellname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-verbose\*O] [\*L\-help\*O] .zZ "defect,6447,R1.0.2,Add -server option to fts dump" .sE .SH "OPTIONS" .iX "filesets" "dumping, time format" .VL .LI "\*L\-fileset\*O {\*Vname\*O | \*VID\*O}" .zA "enh,R1.0.2,Add descriptive text" Specifies the complete name or fileset ID number of the fileset to be dumped. The read-write, read-only, or backup version of the fileset can be dumped. Append the \*L.readonly\*O or \*L.backup\*O extension to the name of the fileset to dump the read-only or backup version instead of the read/write version. .zZ "enh,R1.0.2,Add descriptive text" .zA "misc,R1.0.2,Repair mistakes from PH work" .LI "\*L\-time\*O {\*Vdate\*O | \*V0\*O}" Specifies a full or incremental dump. Three values are legal: .VL .LI "\*L0\*O (zero)" A \*L0\*O (zero) value causes a full dump of the current version of the fileset. .LI "\*Emm\*O/\*Edd\*O/\*Eyy\*O" A month/day/year value causes an incremental dump from 12:00 a.m. (00:00) on the indicated date (for example, \*L1/23/90\*O or \*L10/16/92\*O). Only files with modification time stamps equal to or later than the specified date and time are dumped. .LI "\*Emm\*O/\*Edd\*O/\*Eyy hh\*O:\*Emm\*O" An exact date and time value causes an incremental dump from the specified time on the indicated date. Only files with modification time stamps equal to or later than the specified date and time are dumped. The time must be in 24-hour format (for example, \*L20:30\*O for 8:30 p.m.). The date format is the same as for a date alone. Surround the entire argument with \*L"\|"\*O (double quotes) because it contains a space (for example, \*L"1/23/90 22:30"\*O or \*L"10/16/92 3:45"\*O). .LE .zZ "misc,R1.0.2,Repair mistakes from PH work" .PP Use this option to perform a full dump or to perform an incremental dump of only those files in the fileset modified since a specific date or date and time. Use this option or use \*L\-version\*O. .LI "\*L\-version \*Vnumber\*O" Specifies an incremental dump based on the indicated fileset version number. Each DCE LFS fileset has a version number. Each file in the fileset records the version number that was current when the file was last modified. If this option is specified, only those files with version numbers equal to or greater than the specified version number are dumped. (A DCE LFS fileset's version number is recorded in its fileset header; it has the same format as a fileset ID number. Use the \*Lfts lsheader\*O or \*Lfts lsft\*O command to display a fileset's current version number.) .PP Use this option or use \*L\-time\*O. Use this option only with DCE LFS filesets. .zA "defect,6447,R1.0.2,Add -server option to fts dump" .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the File Server machine that houses the version of the fileset to be dumped. Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .PP This option is useful for dumping a particular read-only replica of a DCE LFS fileset for which multiple replicas exist. If you include the \*L.readonly\*O extension with the name of a fileset specified with the \*L\-fileset\*O option, or if you specify the ID number of the read-only version of a fileset with the \*L\-fileset\*O option, you can use the \*L\-server\*O option to indicate the machine that houses the specific replica to be dumped. If you omit the \*L\-server\*O option in these cases, the command dumps the replica that resides at the fileset's oldest read-only site (the replica at the site that has been defined for the longest time). .PP This option is always unnecessary if the read/write or backup version of a fileset is to be dumped. .zZ "defect,6447,R1.0.2,Add -server option to fts dump" .LI "\*L\-file \*Vfilename\*O" Specifies the complete pathname of the file to which the dump is to be written. If a complete pathname is not specified, the file is written to the current working directory. If this option is omitted, the data is sent to standard output (\*Lstdout\*O). .LI "\*L\-cell \*Vcellname\*O" Specifies the cell where the command is to be run. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts dump\*O command converts the contents of the indicated fileset to a bytestream format. It puts the converted contents into the file specified with the \*L\-file\*O option. If this option is omitted, the dumped data is sent to \*Lstdout\*O. Both non-LFS and read-write, read-only, and backup DCE LFS filesets can be dumped. .PP The command's options can be used to perform the following types of dumps: .ML .LI A value of 0 (zero) specified with the \*L\-time\*O option causes a full dump of the fileset. .LI A date specified with the \*L\-time\*O option causes an incremental dump of all files modified since 12:00 a.m. (00:00) on that date. .LI A date and time specified with the \*L\-time\*O option cause an incremental dump of all files modified since that date and time. .LI A version number specified with \*L\-version\*O causes an incremental dump of all files in the fileset with version numbers equal to or greater than the specified version number. .LE .PP .zA "enh,R1.0.2,Remove subtly misleading statement" Dumping a fileset does not affect its status in the Fileset Location Database (FLDB) or at the site from which it is dumped. However, it does make the fileset inaccessible for the duration of the dump operation. For this reason, it is customary to dump the backup version of a fileset to prevent the read-write version from being inaccessible for an extended time. .zZ "enh,R1.0.2,Remove subtly misleading statement" .PP .zA "defect,6447,R1.0.2,Add -server option to fts dump" If a read-only replica of a DCE LFS fileset is to be dumped and multiple replicas of the fileset exist, the \*L\-server\*O option can be used to name the File Server machine that houses the specific replica to be dumped. Indicating a specific replica can be useful if network or hardware problems caused only some of a fileset's replicas to be updated. It can be especially useful for restoring the read/write version of a fileset that was lost before all of its replicas were updated: You can dump and restore a specific replica that was updated before the read/write version was lost. (By default, all replicas of the same fileset are always identical; to determine whether all replicas of a fileset are the same, use the \*Lfts lsft\*O command to display information about specific replicas.) .zZ "defect,6447,R1.0.2,Add -server option to fts dump" .PP .zA "defect,7156,R1.0.2,Correct dump/restore restrictions" The \*Lfts restore\*O command can be used to restore a fileset dumped with the \*Lfts dump\*O command. You can use the \*Lfts restore\*O command to restore a dump file to any type of fileset (DCE LFS or non-LFS), regardless of the type of fileset from which it was created. Thus, you can dump and restore data between DCE LFS and non-LFS filesets, as well as between different types of non-LFS filesets. (See the documentation for the \*Lfts restore\*O command for more information about dumping and restoring filesets between different types of file systems.) .zZ "defect,7156,R1.0.2,Correct dump/restore restrictions" .PP .zA "defect,7526,R1.0.3,Moving filesets between cells" You cannot restore a fileset dumped in one cell to a site in another cell. .zZ "defect,7526,R1.0.3,Moving filesets between cells" .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.ft\*O file on the machine on which the fileset is stored. In addition, the issuer must have the write, execute, and insert permissions on the directory in which the dump file is to reside. .SH "EXAMPLES" .PP The following command executes a full dump of the fileset \*Luser.terry\*O into the file named \*L/tmp/terry.dump\*O: .iS \*C$\*O \*Lfts dump user.terry -time 0 /tmp/terry.dump\*O .iE .PP The following command executes an incremental dump of the fileset \*Luser.smith\*O into the file named \*L/tmp/smith.013191.dump\*O. Only those files in the fileset with modification time stamps equal to or later than 6:00 p.m. on 31 January 1991 are included in the dump. .iS \*C$\*O \*Lfts dump user.smith -time "1/31/91 18:00" /tmp/smith.013191.dump\*O .iE .SH "RELATED INFORMATION" .PP .zA "defect,6447,R1.0.2,Add -server option to fts dump" Commands: \*Lfts lsft(1m)\*O, \*Lfts restore(1m)\*O .zZ "defect,6447,R1.0.2,Add -server option to fts dump" .iX "-]" "\*Lfts\*O command suite" "\*Ldump\*O" .iX "-]" "dump files" "creating" .iX "-]" "filesets" "dumping to disk" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" CHANGED ...\" 12-09-91: Modified the description of the -quota option. ...\" END CHANGED ...\" .rm zA .rm zZ .TH "fts edserverentry" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Ledserverentry\*O" .iX "-[" "Fileset Location Database" "editing server entries" .SH NAME \*Lfts edserverentry\*O \- Edits a server entry in the FLDB .SH "SYNOPSIS" .sS .zA "defect,5778,R1.0.3,Use of short forms of machine names" .zA "defect,6378,R1.0.2,Add -noowner option" .zA "defect,5313,R1.0.2,Remove -fxdid option" \*Lfts edserverentry -server\*O \*Vmachine\*O .nL [{\*L\-rmaddr\*O | \*L\-addaddr \*Vaddress\*O | \*L\-changeaddr \*Vaddress\*O}] [\*L\-principal \*Vname\*O] .nL [\*L\-quota \*Ventries\*O] [{\*L\-owner \*Vgroup\*O | \*L\-noowner\*O}] [\*L\-cell \*Vcellname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] .nL [\*L\-verbose\*O] [\*L\-help\*O] .zZ "defect,5313,R1.0.2,Remove -fxdid option" .zZ "defect,6378,R1.0.2,Add -noowner option" .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .sE .SH "OPTIONS" .VL .zA "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-server\*O \*Vmachine\*O" Specifies the server machine whose entry in the Fileset Location Database (FLDB) is to be edited. Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. If the \*L\-rmaddr\*O, \*L\-addaddr\*O, or \*L\-changeaddr\*O option is used with the command, specify the network address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-rmaddr\*O" Removes the address specified with \*L\-server\*O from the server entry identified by \*L\-server\*O in the FLDB. If the name of the machine rather than one of its addresses is specified with \*L\-server\*O, the command can choose one of the machine's addresses at random to be removed from the FLDB. Because this can have unpredictable results, always specify an address with \*L\-server\*O when using the \*L\-rmaddr\*O option. In addition, the command fails if the address to be removed is the only address present for the machine in the FLDB. .PP If this option is specified, do not specify the \*L\-addaddr\*O or \*L\-changeaddr\*O option. .LI "\*L\-addaddr \*Vaddress\*O" Adds the additional address specified with this option to the server entry specified by \*L\-server\*O in the FLDB. A machine can have from one to four addresses associated with it in the FLDB. The command fails if you attempt to add a fifth address for the machine to the FLDB. .PP If the name of the machine rather than one of its addresses is specified with \*L\-server\*O, the command can choose one of the machine's addresses in the FLDB at random to have the address added to it. Because this can have unpredictable results, always specify an address with \*L\-server\*O when using the \*L\-addaddr\*O option. .PP If this option is specified, do not specify the \*L\-rmaddr\*O or \*L\-changeaddr\*O option. .LI "\*L\-changeaddr \*Vaddress\*O" Substitutes the address specified with this option for the address specified by \*L\-server\*O in the FLDB. If the name of the machine rather than one of its addresses is specified with \*L\-server\*O, the command can choose one of the machine's addresses at random to be replaced with the address specified with this option. Because this can produce unpredictable results, always specify an address with \*L\-server\*O when using the \*L\-changeaddr\*O option. .PP If this option is specified, do not specify the \*L\-rmaddr\*O or \*L\-addaddr\*O option. .LI "\*L\-principal \*Vname\*O" .zA "defect,8084,R1.0.3,Correct description of -principal option" Changes the abbreviation for the DFS server principal that is registered for the machine in the FLDB (for example, \*Lhosts/\*Vhostname\*O). The machine's principal name in the Registry Database must match this name. If this option is omitted, the abbreviated DFS server principal currently associated with the server entry remains unchanged. .zZ "defect,8084,R1.0.3,Correct description of -principal option" .LI "\*L\-quota \*Ventries\*O" Changes the limit on the number of fileset entries (read-write, read-only, and backup) in the FLDB that can be associated with the specified \*L\-server\*O. A value of 0 (zero) allows an unlimited number of fileset entries to be associated with the server. If this option is omitted, the number of fileset entries currently allowed for the specified File Server machine remains unchanged. .LI "\*L\-owner \*Vgroup\*O" .zA "defect,8616,R1.0.3,Foreign groups cannot own server entries" .zA "defect,6378,R1.0.2,Add -noowner option" .zA "defect,6542,R1.0.2,Improve principal/group option descriptions" \*L\-owner\*O \*Egroup\*O changes the group that is the owner of the server entry. In the entry, the specified group replaces the current owning group, if any. A group can be specified by a full or abbreviated group name (for example, \*L/.../\*Ecellname\*L/\*Egroup_name\*O or just \*Egroup_name\*O). Foreign groups cannot own a local server entry. If this option is omitted, no group owns the server entry (the value \*L\*O is reported as the owner). Use this option or use the \*L\-noowner\*O option; omit both options to leave the current owning group unchanged. .zZ "defect,6542,R1.0.2,Improve principal/group option descriptions" .zZ "defect,8616,R1.0.3,Foreign groups cannot own server entries" .LI "\*L\-noowner\*O" .zA "defect,7219,R1.0.2,Review comments" Specifies that no group is to own the server entry. In the entry, the empty group ID, displayed as \*L\*O, replaces the group that currently owns the server entry; the entry is unchanged in this regard if no group presently owns the server entry. Use this option or use the \*L\-owner\*O option; omit both options to leave the current owning group unchanged. .zZ "defect,7219,R1.0.2,Review comments" .zZ "defect,6378,R1.0.2,Add -noowner option" .zA "defect,5313,R1.0.2,Remove -fxdid option" .zZ "defect,5313,R1.0.2,Remove -fxdid option" .LI "\*L\-cell \*Vcellname\*O" Specifies the cell in whose FLDB the server entry is to be modified. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts edserverentry\*O command alters a server entry in the FLDB for the server machine specified with the \*L\-server\*O option. Use the \*L\-rmaddr\*O option to remove an address associated with a server from the FLDB. Use the \*L\-addaddr\*O option to add a new address for a server to the FLDB, or use the \*L\-changeaddr\*O option to change an address for a server in the FLDB. .PP .zA "defect,6378,R1.0.2,Add -noowner option" The \*L\-principal\*O option can be used to change the abbreviated DFS server principal associated with the server entry. The \*L\-quota\*O option can be used to alter the number of fileset entries that can be associated with the File Server machine in the FLDB, and the \*L\-owner\*O option can be used to assign a new group as the owner of the server entry (or the \*L\-noowner\*O option can be used to indicate that no group owns the server entry). .zZ "defect,6378,R1.0.2,Add -noowner option" .PP Unless a value associated with a server entry is explicitly modified with this command, its current value in the FLDB remains unchanged. The values associated with a server entry are initially specified when the server entry is created with the \*Lfts crserverentry\*O command. The values can then be modified at any time with the \*Lfts edserverentry\*O command. Use the \*Lfts lsserverentry\*O command to display the current values from the FLDB for a server entry. Use the \*Lfts delserverentry\*O command to remove a server entry from the FLDB. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.fl\*O files on all Fileset Database machines. .SH "EXAMPLES" .PP The following command modifies the server entry in the FLDB for a server machine. The command changes the machine's network address from \*L191.54.206.36\*O, as specified with the \*L\-server\*O option, to \*L191.54.206.46\*O, as indicated with the \*L\-changeaddr\*O option. The command also allows the server to accommodate an unlimited number of fileset entries by providing a value of \*L0\*O (zero) with the \*L\-quota\*O option. .iS \*C$\*O \*Lfts edserverentry 191.54.206.36 -changeaddr 191.54.206.46 -quota 0\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lfts crserverentry(1m)\*O, \*Lfts delserverentry(1m)\*O, \*Lfts lsserverentry(1m)\*O .iX "-]" "\*Lfts\*O command suite" "\*Ledserverentry\*O" .iX "-]" "Fileset Location Database" "editing server entries" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\"Copyright (C) 1989, 1991, Transarc Corporation ...\"The Gulf Tower ...\"707 Grant Street ...\"Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "fts help" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" CHANGED ...\" 12-10-91: In EXAMPLES, changed "--- dir" to "-dir". ...\" END CHANGED .iX "-[" "\*Lfts\*O command suite" "\*Lhelp\*O" .SH NAME .PP \*Lfts help\*O \- Shows syntax of specified \*Lfts\*O commands or lists functional descriptions of all \*Lfts\*O commands .SH "SYNOPSIS" .PP .sS \*Lfts help\*O [\*L-topic\*O \*Vstring\*O...] [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-topic \*Vstring\*O" Specifies each command whose syntax is to be displayed. Provide only the second part of the command name (for example, \*Llsft\*O, not \*Lfts lsft\*O). If this option is omitted, the output provides a short description of all \*Lfts\*O commands. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts help\*O command displays the first line (name and short description) of the online help entry for every \*Lfts\*O command if \*L-topic\*O is not provided. For each command name specified with \*L-topic\*O, the output lists the entire help entry. .PP Use the \*Lfts apropos\*O command to show each help entry containing a specified string. .SS "Privilege Required" .PP No privileges are required. .SH "OUTPUT" .PP The online help entry for each \*Lfts\*O command consists of the following two lines: .ML .LI The first line names the command and briefly describes its function. .LI The second line, which begins with \*CUsage:\*O, lists the command options in the prescribed order. .LE .SH "EXAMPLES" .PP The following command displays the online help entry for the \*Lfts delmount\*O command: .iS \*C$ \*Lfts help delmount\*O .iE .oS fts delmount: remove mount point Usage: fts delmount -dir ... [-help] .oE .SH "RELATED INFORMATION" .PP Commands: \*Lfts apropos(1m)\*O .iX "-]" "\*Lfts\*O command suite" "\*Lhelp\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts lock" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Llock\*O" .iX "-[" "Fileset Location Database" "locking fileset entries" .iX "-[" "filesets" "blocking operations" .SH NAME .PP \*Lfts lock\*O \- Locks a fileset entry in the FLDB .SH "SYNOPSIS" .sS \*Lfts lock -fileset\*O {\*Vname\*O | \*VID\*O} [\*L\-cell \*Vcellname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-verbose\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-fileset\*O {\*Vname\*O | \*VID\*O}" Specifies the complete name or fileset ID number of the fileset whose entry in the Fileset Location Database (FLDB) is to be locked. All versions of the fileset referenced in the entry are affected by the lock, regardless of whether the read-write, read-only, or backup version of the fileset is specified. .LI "\*L\-cell \*Vcellname\*O" Specifies the cell where the command is to be run. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts lock\*O command locks the entry in the FLDB for the fileset indicated with the \*L\-fileset\*O option. Locking a fileset's FLDB entry blocks operations on all versions of the fileset, regardless of whether the read-write, read-only, or backup version of the fileset is indicated with the \*L\-fileset\*O option. Locking a fileset's entry prevents all versions of the fileset from being modified with \*Lfts\*O commands. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.fl\*O files on all Fileset Database machines or own the server entry for each machine on which a version of the fileset to be locked resides. .SH "CAUTIONS" .PP Do not use this command in normal circumstances. It is useful only if the system administrator wants to guarantee that no one else manipulates the fileset until the lock is released and if there is reason to believe that locking will not happen automatically. Locking a fileset entry inhibits only operations such as deleting and cloning of the fileset; it does not prevent the reading of data from the fileset. .SH "EXAMPLES" .PP The following command locks the FLDB entry for \*Luser.terry\*O: .iS \*C$\*O \*Lfts lock user.terry\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lfts unlock(1m)\*O, \*Lfts unlockfldb(1m)\*O .iX "-]" "\*Lfts\*O command suite" "\*Llock\*O" .iX "-]" "Fileset Location Database" "locking fileset entries" .iX "-]" "filesets" "blocking operations" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" CHANGED ...\" 12-09-91: In OUTPUT, removed the period from the end of the fourth ...\" item in the bulleted list. ...\" END CHANGED ...\" .rm zA .rm zZ .TH "fts lsaggr" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .SH NAME .iX "-[" "\*Lfts\*O command suite" "\*Llsaggr\*O" .iX "-[" "aggregates" "identifying exported" .PP \*Lfts lsaggr\*O \- Lists all exported aggregates and partitions on a File Server machine .SH "SYNOPSIS" .sS \*Lfts lsaggr -server \*Vmachine\*O [\*L\-cell \*Vcellname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-verbose\*O] .nL [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the File Server machine whose exported aggregates and partitions are to be listed. Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-cell \*Vcellname\*O" Specifies the cell where the command is to be run. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "misc,R1.0.2,Repair mistakes from PH work" The \*Lfts lsaggr\*O command displays information about all exported aggregates and partitions on the File Server machine specified by the \*L\-server\*O option. The information about each aggregate and partition is specified in the \*Edcelocal\*L/var/dfs/dfstab\*O file on the machine. .zZ "misc,R1.0.2,Repair mistakes from PH work" .PP .zA "defect,8439,R1.0.3,Remove dfsatab file" You can also issue the \*Ldfsexport\*O command with no options to list all aggregates and partitions currently exported from the local disk to the DCE namespace. You can use the \*Lfts aggrinfo\*O command to display information about the amount of disk space available on a specific aggregate or partition or on all aggregates and partitions on a File Server machine. .zZ "defect,8439,R1.0.3,Remove dfsatab file" .zA "defect,5933,R1.0.2,Reinstate priv. required sections" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Reinstate priv. required sections" .SH "OUTPUT" .PP This command displays a separate line for each aggregate or partition. Each line displays the following information: .zA "misc,R1.0.2,Repair mistakes from PH work" .ML .LI The aggregate name, specified in the second field of the \*Ldfstab\*O file .LI The device name, specified in the first field of the \*Ldfstab\*O file .LI The aggregate ID, specified in the fourth field of the \*Ldfstab\*O file .LI The file system type, specified in the third field of the \*Ldfstab\*O file .LE .zZ "misc,R1.0.2,Repair mistakes from PH work" .SH "EXAMPLES" .PP The following example shows that two non-LFS partitions and two DCE LFS aggregates are exported from the File Server machine named \*L/.../abc.com/hosts/fs1\*O: .iS \*C$\*O \*Lfts lsaggr /.../abc.com/hosts/fs1\*O .iE .iS \*CThere are 4 aggregates on the server /.../abc.com/hosts/fs1 (fs1.abc.com):\*O .nL \*C\ \ \ \ \ \ \ \ \ \ \ \ \ \ /usr (/dev/lv02):\ id=3\ \ \ \ \ (non-LFS)\*O .nL \*C\ \ \ \ \ \ \ \ \ \ \ \ \ \ /tmp (/dev/lv03):\ id=4\ \ \ \ \ (non-LFS)\*O .nL \*C\ \ \ \ \ \ \ \ \ \ \ \ \ \ lfs1 (/dev/lfs1):\ id=10\ \ \ \ \ (LFS)\*O .nL \*C\ \ \ \ \ \ \ \ \ \ \ \ \ \ lfs2 (/dev/lfs2):\ id=11\ \ \ \ \ (LFS)\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Ldfsexport(1m)\*O, \*Lfts aggrinfo(1m)\*O .PP .zA "defect,8439,R1.0.3,Remove dfsatab file" Files: \*Ldfstab(4)\*O .zZ "defect,8439,R1.0.3,Remove dfsatab file" .iX "-]" "\*Lfts\*O command suite" "\*Llsaggr\*O" .iX "-]" "aggregates" "identifying exported" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts lsfldb" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Llsfldb\*O" .iX "-[" "Fileset Location Database" "viewing fileset entries" .iX "-[" "filesets" "viewing FLDB information" .SH NAME .PP \*Lfts lsfldb\*O \- Shows information from fileset entries in the FLDB .SH "SYNOPSIS" .sS \*Lfts lsfldb\*O [\*L\-fileset\*O {\*Vname\*O | \*VID\*O}] [\*L\-server \*Vmachine\*O] [\*L\-aggregate \*Vname\*O] [\*L\-locked\*O] .nL [\*L\-cell \*Vcellname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-verbose\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-fileset\*O {\*Vname\*O | \*VID\*O}" Specifies the complete name or fileset ID number of a fileset about which information from the Fileset Location Database (FLDB) is to be displayed. Use this option or use -\*Lserver\*O (and optionally \*L\-aggregate\*O), \*L\-locked\*O, or both. Omit this option and the \*L\-server\*O, \*L\-aggregate\*O, and \*L\-locked\*O options to display information about all fileset entries in the FLDB. .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names a File Server machine about whose filesets information from the FLDB is to be displayed. Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. This option can be combined with \*L\-aggregate\*O to display information about the filesets on a single aggregate on \*L\-server\*O, or it can be combined with \*L\-locked\*O to display information about the filesets with locked FLDB entries on the server machine. Use this option alone or with \*L\-aggregate\*O, \*L\-locked\*O, or both, or use \*L\-fileset\*O. Omit this option and the \*L\-fileset\*O, \*L\-aggregate\*O, and \*L\-locked\*O options to display information about all fileset entries in the FLDB. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-aggregate \*Vname\*O" Specifies the device name, aggregate name, or aggregate ID of the aggregate or partition on \*L\-server\*O about whose filesets information from the FLDB is to be displayed. These identifiers are specified in the first, second, and fourth fields of the entry for the aggregate or partition in the \*Edcelocal\*L/var/dfs/dfstab\*O file. The \*L\-server\*O option must be provided with this option. The \*L\-locked\*O option can be supplied with this option to display information about the filesets with locked FLDB entries on the aggregate. .LI "\*L\-locked\*O" Specifies that the output show information only for filesets with locked FLDB entries. Use this option alone to see information for all filesets with locked FLDB entries. Use this option with \*L\-server\*O (and optionally \*L\-aggregate\*O) to see all filesets on a specific server machine (and optionally aggregate) with locked FLDB entries. Use this option alone or with \*L\-server\*O (and optionally \*L\-aggregate\*O) or use \*L\-fileset\*O. Omit this option and the \*L\-fileset\*O, \*L\-server\*O, and \*L\-aggregate\*O options to display information about all fileset entries in the FLDB. .LI "\*L\-cell \*Vcellname\*O" Specifies the cell where the command is to be run. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts lsfldb\*O command formats and displays information about fileset entries from the FLDB. Its options can be combined to display information about a variety of different filesets. To display FLDB information for .ML .LI Every fileset entry, specify no options .LI Every fileset entry that mentions a specific File Server machine as the site of any version of a fileset, specify the name of the machine with \*L\-server\*O .LI Every fileset entry that mentions a specific aggregate on a specific File Server machine as the site of any version of a fileset, specify both \*L\-server\*O and \*L\-aggregate\*O .LI The FLDB entries for filesets with locked entries, specify the \*L\-locked\*O option alone or with \*L\-server\*O (and optionally \*L\-aggregate\*O) .LI The fileset entry for a single fileset, specify the fileset name or ID number with \*L\-fileset\*O .LE .PP Use the \*Lfts lsheader\*O command to display information from fileset headers. To display more information about a single fileset, use the \*Lfts lsft\*O command to display all of the information displayed by the \*Lfts lsheader\*O command when the \*L\-long\*O option is used and all of the information displayed by this command. .zA "defect,5933,R1.0.2,Reinstate priv. required sections" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Reinstate priv. required sections" .SH "OUTPUT" .PP The \*Lfts lsfldb\*O command displays the following information from the FLDB for each DCE LFS fileset specified with \*L\-fileset\*O or \*L\-server\*O (and optionally \*L\-aggregate\*O). Because functionality such as replication is not supported for non-LFS filesets, this command displays less information for non-LFS filesets. .ML .LI .zA "defect,7219,R1.0.2,Review comments" The fileset's name. .zZ "defect,7219,R1.0.2,Review comments" .LI The fileset IDs of the read/write, read-only, and backup versions of the fileset. .LI For each version, a status flag of \*Lvalid\*O indicates the version actually exists at a site; a status flag of \*Linvalid\*O indicates the version does not exist at any site. (For the read-only version, the status flag indicates whether a replication site is defined.) .LI The number of sites a version of the fileset exists at. .LI An indicator if the FLDB entry is locked (the indicator is omitted if the entry is not locked). .LI The replication parameters associated with the fileset. .LI Information identifying the File Server machines and aggregates (sites) where read/write (RW), read-only (RO), or backup (BK) versions of the fileset reside. .LI For a read-only version, the MaxSiteAge replication parameter defined for that site; for a read/write version, \*C0:00:00\*O. .LI .zA "defect,7219,R1.0.2,Review comments" The abbreviated DCE principal name of each File Server machine on which a version of the fileset resides, and the name of the group that owns the server entry for the machine (or \*C\*O if no group owns the server entry). .zZ "defect,7219,R1.0.2,Review comments" .LE .PP If the output includes more than one FLDB entry, information about the filesets is displayed in alphabetical order by fileset name. The last line of the output displays the total number of entries successfully reported and the total number of entries not reported (the number of entries that \*Cfailed\*O). .SH "EXAMPLES" .PP The following command shows an example of the output from the \*Lfts lsfldb\*O command for a fileset named \*Luser.terry\*O: .iS \*C$\*O \*Lfts lsfldb user.terry\*O .iE .iS \*Cuser.terry\*O .nL \*C\ \ \ \ \ \ \ \ readWriteID\ \ 0,,196953\ \ valid\*O .nL \*C\ \ \ \ \ \ \ \ readOnlyID\ \ \ 0,,196594\ \ invalid\*O .nL \*C\ \ \ \ \ \ \ \ backupID\ \ \ \ \ 0,,196595\ \ valid\*O .nL \*Cnumber of sites:\ 1\*O .nL \*C\ \ Sched\ repl:\ maxAge=2:00:00;\ failAge=1d0:00:00;\*O .nL \*C\ \ reclaimWait=18:00:00;\ minRepDelay=0:05:00;\ defaultSiteAge=0:30:00\*O .nL \*C\ \ \ server\ \ \ \ \ \ \ \ flags\ \ \ aggr\ \ \ siteAge\ principal\ \ owner\*O .nL \*Cfs3.abc.com\ \ \ \ \ \ RW,BK\ \ \ lfs1\ \ \ 0:00:00\ hosts/fs3\ \ \*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Lfts lock(1m)\*O, \*Lfts lsfldb(1m)\*O, \*Lfts lsft(1m)\*O, \*Lfts unlock(1m)\*O, \*Lfts unlockfldb(1m)\*O .PP Files: \*Ldfstab(4)\*O .iX "-]" "\*Lfts\*O command suite" "\*Llsfldb\*O" .iX "-]" "filesets" "viewing FLDB information" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts lsft" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Llsft\*O" .iX "-[" "fileset headers" "viewing FLDB information" .SH NAME .PP \*Lfts lsft\*O \- Lists fileset information from both the fileset header and the FLDB entry .SH "SYNOPSIS" .sS .PP .zA "defect,6446,R1.0.2,Add -server option to fts lsft" \*Lfts lsft\*O [{\*L\-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O} | \*L\-fileset\*O {\*Vname\*O | \*EID\*O}}] [\*L\-server\*O \*Vmachine\*O] .nL [\*L\-cell \*Vcellname\*O] [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-verbose\*O] [\*L\-help\*O] .zZ "defect,6446,R1.0.2,Add -server option to fts lsft" .sE .SH "OPTIONS" .VL .LI "\*L\-path\*O {\*Vfilename\*O | \*Vdirectory_name\*O}" Names a file or directory on the fileset whose fileset header and FLDB information is to be displayed. Use this option or use \*L\-fileset\*O; omit both options to display information about the fileset that contains the current working directory. .LI "\*L\-fileset\*O {\*Vname\*O | \*VID\*O}" .zA "enh,R1.0.2,Clarify description" Specifies the complete name or fileset ID number of the fileset to be examined. The read/write, read-only, or backup version of the fileset can be specified. Append the \*L.backup\*O or \*L.readonly\*O extension to the name of the fileset to list information about the backup or read-only version instead of the read/write version; if the read/write version no longer exists, the command fails if the \*L.backup\*O or \*L.readonly\*O extension is not used with the name of the fileset. .zZ "enh,R1.0.2,Clarify description" .PP Use this option or use \*L\-path\*O; omit both options to display information about the fileset that contains the current working directory. .zA "defect,6446,R1.0.2,Add -server option to fts lsft" .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names the File Server machine that houses the fileset about which information is to be displayed. Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .PP This option is useful for displaying information about a particular read-only replica of a DCE LFS fileset for which multiple replicas exist. If you include the \*L.readonly\*O extension with the name of a fileset specified with the \*L\-fileset\*O option, specify the ID number of the read-only version of a fileset with the \*L\-fileset\*O option, or specify the path to a file or directory in a read-only fileset with the \*L\-path\*O option, you can use the \*L\-server\*O option to indicate the machine that houses the specific replica about which information is to be displayed. If you omit the \*L\-server\*O option in these cases, the command displays information about the replica at the fileset's oldest read-only site (the replica at the site that has been defined for the longest time). .PP This option is always unnecessary if information is to be displayed about the read/write or backup version of a fileset. .zZ "defect,6446,R1.0.2,Add -server option to fts lsft" .LI "\*L\-cell \*Vcellname\*O" Specifies the cell where the command is to be run. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts lsft\*O command displays information from both the fileset header and the Fileset Location Database (FLDB) entry for the specified fileset. It displays the same output as the \*Lfts lsheader\*O command with the \*L\-long\*O option and the \*Lfts lsfldb\*O command for a single fileset. It can be used to learn the fileset ID number of a fileset or to examine locked FLDB entries. .PP The fileset whose information is to be displayed can be specified by indicating the name of a file or directory on the fileset with the \*L\-path\*O option, or it can be specified by indicating its name or ID number with the \*L\-fileset\*O option. Omit both the \*L\-path\*O and \*L\-fileset\*O options to display information about the fileset that contains the current working directory. If the name of the fileset is specified with the \*L\-fileset\*O option, the \*L.backup\*O or \*L.readonly\*O extension can be appended to the name to display information about one of those fileset versions rather than the read/write version. .PP .zA "defect,6446,R1.0.2,Add -server option to fts lsft" If information about a read-only replica of a DCE LFS fileset is to be displayed and multiple replicas of the fileset exist, the \*L\-server\*O option can be used to name the File Server machine that houses the specific replica about which information is to be displayed. Indicating a specific replica can be useful if network or hardware problems caused only some of a fileset's replicas to be updated. (By default, all replicas of the same fileset should always contain the same information.) .zZ "defect,6446,R1.0.2,Add -server option to fts lsft" .PP Use the \*Lfts lsheader\*O command to display information from fileset headers. Use the \*Lfts lsfldb\*O command to display information from fileset entries in the FLDB. .zA "defect,5933,R1.0.2,Reinstate priv. required sections" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Reinstate priv. required sections" .SH "OUTPUT" .PP The \*Lfts lsft\*O command displays the following information from the fileset header and the FLDB entry for a specified DCE LFS fileset. Because non-LFS filesets do not have DCE LFS fileset headers, and because functionality such as replication is not supported for non-LFS filesets, this command displays less information for a non-LFS fileset. .PP The command displays the following information from the fileset's header: .ML .LI The fileset's name (with a \*L.readonly\*O or \*L.backup\*O extension, if appropriate) .LI Its fileset ID number .LI Its type (\*LRW\*O for read/write, \*LRO\*O for read-only, or \*LBK\*O for backup) .LI Its type (\*LLFS\*O or \*Lnon-LFS\*O) .zA "defect,6358,R1.0.3,Fileset quota change" .zZ "defect,6358,R1.0.3,Fileset quota change" .LI .zA "defect,6358,R1.0.3,Fileset quota change" Information about the state of the fileset .zZ "defect,6358,R1.0.3,Fileset quota change" .LI Its status (\*LOn-line\*O, \*LOff-line\*O, or an error indicator) .LI The File Server machine, aggregate name, and aggregate ID number on which it resides .LI The ID numbers of the parent, clone, and backup filesets related to the fileset .LI The ID numbers of the low-level backing and low-level forward filesets related to the fileset .LI Its version number .LI .zA "defect,6358,R1.0.3,Fileset quota change" Its allocation and allocation usage, in kilobytes .LI Its quota and quota usage, in kilobytes .zZ "defect,6358,R1.0.3,Fileset quota change" .LI The day, date, and time when the fileset was created (replicated or backed up for a read-only or backup fileset) .LI The day, date, and time when the contents of the fileset were last updated (same as the creation time for a read-only or backup fileset) .LE .PP It then displays the following information from the fileset's entry in the FLDB: .ML .LI .zA "defect,7219,R1.0.2,Review comments" The fileset's name. .zZ "defect,7219,R1.0.2,Review comments" .LI The fileset IDs of the read/write, read-only, and backup versions of the fileset. .LI For each version, a status flag of \*Lvalid\*O indicates the version actually exists at a site; a status flag of \*Linvalid\*O indicates the version does not exist at any site. (For the read-only version, the status flag indicates whether a replication site is defined.) .LI The number of sites at which a version of the fileset exists. .LI An indicator if the FLDB entry is locked. (The indicator is omitted if the entry is not locked.) .LI The replication parameters associated with the fileset. .LI Information identifying the File Server machines and aggregates (sites) on which read/write (RW), read-only (RO), or backup (BK) versions of the fileset reside. .LI For a read-only version, the MaxSiteAge replication parameter defined for that site; for a read/write version, \*C0:00:00\*O. .LI .zA "defect,7219,R1.0.2,Review comments" The abbreviated DCE principal name of each File Server machine on which a version of the fileset resides, and the name of the group that owns the server entry for the machine (or \*C\*O if no group owns the server entry). .zZ "defect,7219,R1.0.2,Review comments" .LE .SH "EXAMPLES" .PP The following example displays information from the fileset header and FLDB entry for a DCE LFS fileset named \*Luser.terry\*O: .iS \*C$\*O \*Lfts lsft -fileset user.terry\*O .iE .iS .zA "defect,6358,R1.0.3,Fileset quota change" \*C_______________________________________________________________\*O .nL \*Cuser.terry\ 0,,196953\ RW\ LFS\ \ \ \ \ states 0x10010005\ On-line\*O .nL \*C\ \ \ \ fs3.abc.com,\ aggregate lfs1\ (ID\ 10)\*O .nL \*C\ \ \ \ Parent\ 0,,196953\ \ \ Clone\ 0,,0\ \ \ Backup\ 0,,196955\*O .nL \*C\ \ \ \ llBack\ 0,,0\ \ \ \ \ \ \ \ llFwd\ 0,,0\ \ \ Version\ 0,,25963\*O .nL \*C\ \ \ \ 429496729 K alloc limit; \ \ \ \ \ \1252 K alloc usage\ \*O .nL \*C\ \ \ \ \ \ \ \ \15000 K quota limit; \ \ \ \ \ \9340 K quota usage\ \*O .nL \*C\ \ \ \ Creation\ Fri\ Oct\ 15\ 16:45:16\ 1993\*O .nL \*C\ \ \ \ Last\ Update\ Mon\ Nov\ 22\ 11:36:00\ 1993\*O .iE .iS \*Cuser.terry\*O .nL \*C\ \ \ \ \ \ \ \ readWriteID\ \ 0,,196953\ \ valid\*O .nL \*C\ \ \ \ \ \ \ \ readOnlyID\ \ \ 0,,196594\ \ invalid\*O .nL \*C\ \ \ \ \ \ \ \ backupID\ \ \ \ \ 0,,196595\ \ valid\*O .nL \*Cnumber of sites:\ 2\*O .nL \*C\ \ Sched\ repl:\ maxAge=2:00:00;\ failAge=1d0:00:00;\*O .nL \*C\ \ reclaimWait=18:00:00;\ minRepDelay=0:05:00;\*O .nL \*CdefaultSiteAge=0:30:00\*O .nL \*C\ \ \ server\ \ \ \ \ \ \ \ flags\ \ \ aggr\ \ \ siteAge\ principal\ \ owner\*O .nL \*Cfs3.abc.com\ \ \ \ \ \ RW,BK\ \ \ lfs1\ \ \ 0:00:00\ hosts/fs3\ \ \*O .nL \*C_______________________________________________________________\*O .zZ "defect,6358,R1.0.3,Fileset quota change" .iE .SH "RELATED INFORMATION" .PP Commands: \*Lfts lsfldb(1m)\*O, \*Lfts lsheader(1m)\*O .iX "-]" "\*Lfts\*O command suite" "\*Llsft\*O" .iX "-]" "fileset headers" "viewing FLDB information" .iX "-]" "Fileset Location Database" "viewing fileset entries" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts lsheader" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Llsheader\*O" .iX "-[" "fileset headers" "viewing" .SH NAME .PP \*Lfts lsheader\*O \- Shows information from fileset headers .SH "SYNOPSIS" .sS \*Lfts lsheader -server \*Vmachine\*O [\*L\-aggregate \*Vname\*O] [{\*L\-fast\*O | \*L\-long\*O}] [\*L\-cell \*Vcellname\*O] .nL [{\*L\-noauth\*O | \*L\-localauth\*O}] [\*L\-verbose\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-server \*Vmachine\*O" .zA "defect,5778,R1.0.3,Use of short forms of machine names" Names a File Server machine about whose filesets header information is to be displayed. Specify the File Server machine using the machine's DCE pathname, the machine's host name, or the machine's IP address. This option can be combined with the \*L\-aggregate\*O option to name a specific aggregate on \*L\-server\*O. .zZ "defect,5778,R1.0.3,Use of short forms of machine names" .LI "\*L\-aggregate \*Vname\*O" Specifies the device name, aggregate name, or aggregate ID of the aggregate or partition on \*L\-server\*O from whose filesets header information is to be displayed. These identifiers are specified in the first, second, and fourth fields of the entry for the aggregate or partition in the \*Edcelocal\*L/var/dfs/dfstab\*O file. The \*L\-server\*O option must be provided with this option. .LI "\*L\-fast\*O" Directs the output to display only the fileset ID numbers of all filesets on the indicated server (and optionally the aggregate). If you use this option, do not use the \*L\-long\*O option. .LI "\*L\-long\*O" Directs the output to display more detailed information about all filesets on the indicated server (and optionally the aggregate). If you use this option, do not use the \*L\-fast\*O option. .LI "\*L\-cell \*Vcellname\*O" Specifies the cell where the command is to be run. The default is the local cell of the issuer of the command. .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lfts\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions as it executes the command. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts lsheader\*O command formats and displays information from the fileset headers of filesets on the specified server (and optionally the aggregate or partition). To display information from the headers of all filesets on a specific File Server machine, specify the name of the server machine with the \*L\-server\*O option. To specify information from the headers of all filesets on a specific aggregate on a File Server machine, specify the name of the server machine with the \*L\-server\*O option and the name of the aggregate or partition with the \*L\-aggregate\*O option. .PP Include the \*L\-fast\*O option with the command to display only the ID numbers of the filesets at the specified location. Include the \*L\-long\*O option with the command to display more detailed information from the headers of the filesets at the specified location. .PP Use the \*Lfts lsfldb\*O command to display information from fileset entries in the Fileset Location Database (FLDB). To display more information about a single fileset, use the \*Lfts lsft\*O command to display all of the information displayed by this command when the \*L\-long\*O option is used and all of the information displayed by the \*Lfts lsfldb\*O command. .SS "Privilege Required" .PP The issuer must be listed in the \*Ladmin.ft\*O file on the machine specified by \*L\-server\*O. .SH "OUTPUT" .PP The \*Lfts lsheader\*O command displays different output about the filesets at the specified location depending on whether the \*L\-fast\*O or \*L\-long\*O option is included. Information about the filesets is displayed in numeric order by fileset ID number if the \*L\-fast\*O option is used; otherwise, it is displayed in alphabetical order by fileset name. .PP The information described in this section is displayed for DCE LFS filesets. Because non-LFS filesets do not have DCE LFS fileset headers, the \*Lfts lsheader\*O command displays much less information for non-LFS filesets, and the \*L\-fast\*O and \*L\-long\*O options have less of an impact on the amount of output displayed. .PP If the \*L\-fast\*O option is used, the command lists the ID number of each fileset. If the \*L-aggregate\*O option is omitted, the command also displays the total number of filesets on the specified server. .PP If both the \*L\-fast\*O and \*L\-long\*O options are omitted, the command displays the following information: .ML .LI The File Server machine, aggregate name, and aggregate ID number where the filesets reside. .LI The total number of filesets on the aggregate. .LI Each fileset's name (with a \*L.readonly\*O or \*L.backup\*O extension, if appropriate). .LI Each fileset's fileset ID number. .LI Each fileset's type (\*LRW\*O for read/write, \*LRO\*O for read-only, or \*LBK\*O for backup). .LI .zA "defect,6358,R1.0.3,Fileset quota change" Each fileset's allocation usage and quota usage, in kilobytes. .zZ "defect,6358,R1.0.3,Fileset quota change" .LI Each fileset's status (\*LOn-line\*O, \*LOff-line\*O, or an error indicator). .LI The total number of filesets online, the total number of filesets offline, and the total number of filesets busy. A busy fileset is one upon which a fileset-related operation is currently in progress (for example, the fileset is being moved or cloned, or the Replication Server is currently forwarding changes from the fileset to read-only replicas). .LE .PP If the \*L\-long\*O option is used, the command displays the following additional information for each fileset: .ML .LI Whether it is a DCE LFS (\*LLFS\*O) or \*Lnon-LFS\*O fileset .LI .zA "defect,6358,R1.0.3,Fileset quota change" Information about the state of the fileset .zZ "defect,6358,R1.0.3,Fileset quota change" .LI The ID numbers of the parent, clone, and backup filesets related to the fileset .LI The ID numbers of the low-level backing and low-level forward filesets related to the fileset .LI The version number of the fileset .LI .zA "defect,6358,R1.0.3,Fileset quota change" The allocation and allocation usage, in kilobytes, of the fileset .LI The quota and quota usage, in kilobytes, of the fileset .zZ "defect,6358,R1.0.3,Fileset quota change" .LI The day, date, and time when the fileset was created (replicated or backed up for a read-only or backup fileset) .LI The day, date, and time when the contents of the fileset were last updated (same as the creation time for a read-only or backup fileset) .LE .SH "EXAMPLES" .PP The following examples show output from the \*Lfts lsheader\*O command when it is executed with the \*L\-fast\*O option, with neither the \*L\-fast\*O option nor the \*L\-long\*O option, and with the \*L\-long\*O option. All three examples display output primarily for the same fileset, \*Luser.terry\*O (ID number \*L0,,196953\*O). .iS \*C$\*O \*Lfts lsheader /.../abc.com/hosts/fs3 /dev/lfs1 -fast\*O .iE .oS \*C0,,196953\*O .nL \*C0,,196956\*O .nL \*C\ \ \ \ .\*O .nL \*C\ \ \ \ .\*O .nL \*C0,,199845\*O .nL \*C0,,199846\*O .oE .iS \*C$\*O \*Lfts lsheader /.../abc.com/hosts/fs3 /dev/lfs1\*O .iE .oS \*CTotal filesets\ on\ server fs3 aggregate\ lfs1\ (ID 10): 16\*O .nL .zA "defect,6358,R1.0.3,Fileset quota change" \*Cuser.terry\ \ \ \ \ \ \ \ \ \ \ \ \ 0,,196953\ RW\ \ \ \5071 K alloc \ \8421 K quota \On-line\*O .nL \*Cuser.wvh\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0,,196956\ RW\ \ \ \4955 K alloc \ \9371 K quota \On-line\*O .nL \*C\ \ \ \ .\*O .nL \*C\ \ \ \ .\*O .nL \*CTotal\ filesets\ on-line\ 15;\ total\ off-line\ 1; \*Ctotal\ busy\ 0\*O .zZ "defect,6358,R1.0.3,Fileset quota change" .oE .iS \*C$\*O \*Lfts lsheader /.../abc.com/hosts/fs3 /dev/lfs1 -long\*O .iE .oS \*CTotal filesets\ on\ server fs3 aggregate\ lfs1\ (ID 10): 16\*O .nL .zA "defect,6358,R1.0.3,Fileset quota change" \*Cuser.terry\ 0,,196953\ RW\ LFS\ \ \ \ \ states 0x10010005\ \ \ On-line\*O .nL \*C\ \ \ \ fs3.abc.com,\ aggregate lfs1\ (ID\ 10)\*O .nL \*C\ \ \ \ Parent\ 0,,196953\ \ \ Clone\ 0,,0\ \ \ Backup\ 0,,196955\*O .nL \*C\ \ \ \ llBack\ 0,,0\ \ \ \ \ \ \ \ llFwd\ 0,,0\ \ \ Version\ 0,,25963\*O .nL \*C\ \ \ \ 429496729 K alloc limit; \ \ \ \ \ \1252 K alloc usage\ \*O .nL \*C\ \ \ \ \ \ \ \ \15000 K quota limit; \ \ \ \ \ \9340 K quota usage\ \*O .nL \*C\ \ \ \ Creation\ Tue\ Oct\ 15\ 16:45:16\ 1991\*O .nL \*C\ \ \ \ Last\ Update\ Fri\ Nov\ 22\ 11:36:00\ 1991\*O .nL \ \ .nL \*Cuser.wvh\ 0,,196956\ RW\ LFS\ \ \ \ \ states\ 0x10010005\ \ On-line\*O .nL \*C\ \ \ \ .\*O .nL \*C\ \ \ \ .\*O .nL \*CTotal\ filesets\ on-line\ 15;\ total\ off-line\ 1; \*Ctotal\ busy\ 0\*O .oE .zZ "defect,6358,R1.0.3,Fileset quota change" .SH "RELATED INFORMATION" .PP Commands: \*Lfts lsfldb(1m)\*O, \*Lfts lsft(1m)\*O .PP Files: \*Ldfstab(4)\*O .iX "-]" "\*Lfts\*O command suite" "\*Llsheader\*O" .iX "-]" "fileset headers" "viewing" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "fts lsmount" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Llsmount\*O" .iX "-[" "filesets" "identifying mount points" .iX "-[" "mount points" "identifying associated filesets" .SH NAME .PP \*Lfts lsmount\*O \- Lists the filesets associated with mount points .SH "SYNOPSIS" .sS \*Lfts lsmount -dir \*Vdirectory_name\*O... [\*L-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L-dir \*Vdirectory_name\*O" Names each directory that serves as a mount point for a fileset. The last element in the specified pathname must be an actual name, not . (dot) or .. (dot dot). .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Lfts lsmount\*O command displays the name of the fileset for which each directory specified with the \*L\-dir\*O option is the mount point. The association between a mount point and a fileset is created with the \*Lfts crmount\*O command; it is removed with the \*Lfts delmount\*O command. .SS "Privilege Required" .PP The issuer must have read permission on each directory indicated with the \*L-dir\*O option, regardless of whether each indicated directory resides in a directory in a DCE LFS or non-LFS fileset. .SH "OUTPUT" .PP The \*Lfts lsmount\*O command displays the following message for each directory that is a mount point: .oS \*C`\*Edirectory_name\*O\*C' is a mount point for fileset `\*Efileset_name\*O\*C'\*O .oE .PP In the output, \*Edirectory_name\*O is the name of a directory specified with the \*L-dir\*O option; \*Efileset_name\*O is the name of the fileset for which \*Edirectory_name\*O serves as a mount point. The command also provides the following information about the directory and fileset: .zA "misc,R1.0.2,Repair mistakes from PH work" .VL .LI "\*L#\*O (number sign)" Precedes \*Efileset_name\*O if \*Edirectory_name\*O is a regular mount point .LI "\*L%\*O (percent sign)" Precedes \*Efileset_name\*O if \*Edirectory_name\*O is a read/write mount point .zA "defect,8462,R1.0.3,Remove fts crmount -cell option" .zZ "defect,8462,R1.0.3,Remove fts crmount -cell option" .LI "\*L!\*O (exclamation point)" .zA "defect,7219,R1.0.2,Review comments" Replaces \*Efileset_name\*O if the directory is a global root mount point (a mount point for the root of the DCE global namespace) .zZ "defect,7219,R1.0.2,Review comments" .LE .zZ "misc,R1.0.2,Repair mistakes from PH work" .PP The \*Lfts lsmount\*O command displays the following message for each directory that is not a mount point: .oS \*C`\*Edirectory_name\*O\*C' is not a mount point.\*O .oE .SH "EXAMPLES" .PP The following example lists the mount point \*Lvijay\*O, which is a regular mount point for the fileset named \*Luser.vijay\*O: .iS \*C$ \*Lfts lsmount vijay\*O .iE .oS \*C`vijay' is a mount point for fileset `#user.vijay'\*O .oE .SH "RELATED INFORMATION" .PP Commands: \*Lfts crmount(1m)\*O, \*Lfts delmount(1m)\*O .iX "-]" "\*Lfts\*O command suite" "\*Llsmount\*O" .iX "-]" "filesets" "identifying mount points" .iX "-]" "mount points" "identifying associated filesets" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\"Copyright (C) 1989, 1991, Transarc Corporation ...\"The Gulf Tower ...\"707 Grant Street ...\"Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "fts lsquota" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lfts\*O command suite" "\*Llsquota\*O" .iX "-[" "filesets" "quotas, viewing" .iX "-[" "quotas" "viewing fileset" .SH NAME .PP .zA "defect,6358,R1.0.3,Fileset quota change" \*Lfts lsquota\*O \- Shows quota and quota usage information for filesets and disk size and usage information for aggregates or partitions .zZ "defect,6358,R1.0.3,Fileset quota change" .SH "SYNOPSIS" .PP .sS \*Lfts lsquota\*O \*O[{\*L\-path\*O \*O{\*Vfilename\*O | \*Vdirectory_name\*O}... | \*L\-fileset\*O \*O{\*Vname\*O | \*VID\*O}...}] .nL \*O[\*L\-cell \*Vcellname\*O] \*O[{\*L\-noauth\*O | \*L\-localauth\*O}] \*O[\*L\-verbose\*O] \*O[\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-path \*Vfilename\*O or \*Vdirectory_name\*O" .zA "defect,6358,R1.0.3,Fileset quota change" Names a file or directory from each fileset about which quota, size, and usage information is to be displayed. Include filenames or directory names from different filesets if desired. It is not necessary to name more than one file or directory from the same fileset. Use this option or use \*L\-fileset\*O; omit both options to display information about the fileset containing the current working directory. .LI "\*L\-fileset \*Vname\*O or \*VID\*O" Specifies the complete name or fileset ID number of each fileset about which quota, size, and usage information is to be displayed. Use this option or use \*L\-path\*O; omit both options to display information about the fileset that contains the current working directory. .zZ "defect,6358,R1.0.3,Fileset quota change" .LI "\*L\-cell \*Vcellname\*O" Specifies the cell with respect to which the command is to be run. The default is the local cell of the issuer of the command. .zA "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" .LI "\*L\-noauth\*O" .zA "defect,8634,R1.0.3,Change anonymous to nobody" Directs \*Lfts\*O to use the unprivileged identity \*Lnobody\*O as the identity of the issuer of the command. Generally, the \*L\-noauth\*O option is included if DFS authorization checking is disabled on a server machine on which administrative privilege is required or if the Security Service is unavailable. If you use this option, do not use the \*L\-localauth\*O option. .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .zZ "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" .zA "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-localauth\*O" Directs \*Lbos\*O to use the DFS server principal name of the machine on which the command is issued as the identity of the issuer. Use this option only if the command is issued from a DFS server machine (a machine that has a DFS server principal in the local Registry Database). You must be logged into the server machine as \*Lroot\*O for this option to work. If you use this option, do not use the \*L\-noauth\*O option. .zZ "defect,5120,R1.0.2,Correct use of -localauth option" .LI "\*L\-verbose\*O" Directs \*Lfts\*O to provide detailed information about its actions during command execution. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP .zA "defect,6358,R1.0.3,Fileset quota change" The \*Lfts lsquota\*O command displays quota and quota usage information about filesets and disk size and usage information about the partitions or aggregates on which the filesets reside. Use the \*L\-path\*O option to specify a file or directory on a fileset to see information about that fileset; use the \*L\-fileset\*O option to specify the name or ID number of a fileset to see information about that fileset; omit both options to see information about the fileset that contains the current working directory. .PP For DCE LFS filesets, the \*Lfts lsquota\*O command displays the quota and quota use (in kilobytes) and the percentage of the quota in use. For both DCE LFS and non-LFS filesets, this command displays the name of the fileset, information about the number of available kilobytes on the aggregate or partition on which the fileset resides, the number of kilobytes in use on the aggregate or partition, and the percentage of the aggregate or partition in use. It also reports whether the device is a DCE LFS aggregate or a non-LFS partition. .PP .zA "defect,6223,R1.0.2,df works on LFS aggregates" The size of a non-LFS fileset is equal to the size of the partition on which it resides. Therefore, the size and usage information displayed for the partition (non-LFS aggregate) in the output of the \*Lfts lsquota\*O command equals the quota and quota usage information of the fileset on the partition. Using this command with a non-LFS fileset is analogous to using the UNIX \*Ldf\*O command with the partition on which the fileset resides. (Note that the \*Ldf\*O command can be used to display the size of exported DCE LFS aggregates and locally mounted DCE LFS filesets, but it cannot be used to display the size of a DCE LFS fileset that is not mounted locally.) .zZ "defect,6223,R1.0.2,df works on LFS aggregates" .zZ "defect,6358,R1.0.3,Fileset quota change" .PP The \*Lfts lsheader\*O and \*Lfts lsft\*O commands can be used to display the quota of a DCE LFS fileset. The \*Lfts aggrinfo\*O command can be used to display the total disk space on an aggregate and the amount currently available. .PP By default, every newly created DCE LFS fileset has a quota of 5000 kilobytes. The \*Lfts setquota\*O command can be used to increase or decrease the quota of a DCE LFS fileset. Because the quota of a DCE LFS fileset does not represent the amount of physical data stored on the fileset, it can be larger than the size of the aggregate on which the fileset resides. Similarly, the combined quotas of all filesets on an aggregate can be larger than the size of the aggregate. .PP .zA "defect,7219,R1.0.2,Review comments" The quota of a non-LFS fileset cannot be changed via DFS. (The \*Lfts setquota\*O command works only with DCE LFS filesets.) .zZ "defect,7219,R1.0.2,Review comments" .SS "Privilege Required" .PP No privileges are required. .SH "OUTPUT" .PP This command displays the following information about each specified fileset: .ML .LI The name of the fileset .LI The quota, in kilobytes, of the fileset (DCE LFS only) .LI The number of kilobytes of the quota currently in use on the fileset (DCE LFS only) .LI The percentage of the quota currently in use on the fileset (DCE LFS only) .LI .zA "defect,6358,R1.0.3,Fileset quota change" The percentage of available disk space currently in use on the aggregate or partition on which the fileset resides .LI The number of kilobytes of disk space in use and available on the aggregate or partition on which the fileset resides .zZ "defect,6358,R1.0.3,Fileset quota change" .LI The file system type of the aggregate (\*CLFS\*O or \*Cnon-LFS\*O) .LE .PP .zA "defect,6358,R1.0.3,Fileset quota change" If the fileset quota usage rises above 90% or the aggregate or partition usage rises above 97%, the appropriate percentage is indicated with \*C<<\*O and the message \*C< structure. The second record specifies the new date, and is denoted by the string .B "new time" placed in the line field and the flag .SM .B NEW_TIME placed in the type field. .I wtmpfix uses these records to synchronize all time stamps in the file. .I wtmpfix nullifies date change records when writing to the standard output by setting the time field of the .RB < utmp.h > structure in the old date change record equal to the time field in the new date change record. This prevents .I wtmpfix and .I acctcon1 from factoring in a date change record pair more than once. .PP In addition to correcting time/date stamps, .I wtmpfix checks the validity of the name field to ensure that it consists solely of alphanumeric characters or spaces. If it encounters a name that is considered invalid, it changes the login name to .SM .B INVALID and write a diagnostic to the standard error. This minimizes the risk that .I acctcon1 will fail when processing connect accounting records. .SH DIAGNOSTICS .I wtmpfix generates the following diagnostics messages: .IP Cannot make temporary: xxx failed to make temp file .br Input truncated at offset: xxx missing half of date pair .br New date expected at offset: xxx missing half of date pair .br Cannot read from temp: xxx some error reading .br Bad file at offset: xxx ut_line entry not digit, alpha, nor \(bv or .B { (first character only checked) .br Out of core: .I malloc fails. (Saves table of date changes) .br No dtab: software error (rarely seen, if ever) .SH FILES /usr/include/utmp.h .br /var/adm/wtmp .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), acctsh(1M), ed(1), runacct(1M), acct(2), acct(4), utmp(4). .SH BUGS .I fwtmp generates no errors, even on garbage input. .SH STANDARDS CONFORMANCE .CR fwtmp ": SVID2, SVID3" .PP .CR wtmpfix ": SVID2, SVID3" .\" .\" index@\f4fwtmp\f1 \- manipulate connect accounting records@@@\f3fwtmp(1M)\f1 .\" index@\f4wtmpfix\f1 \- manipulate connect accounting records@@@\f3fwtmp(1M)\f1 .\" index@\f1manipulate connect accounting records@@@\f3fwtmp(1M)\f1 .\" index@\f1connect accounting records, manipulate@@@\f3fwtmp(1M)\f1 .\" index@\f1accounting records, manipulate@@@\f3fwtmp(1M)\f1 .\" .\" toc@\f3fwtmp(1M)\f1:\0\0\f4fwtmp\f1, \f4wtmpfix\f1@@@manipulate connect accounting records .\" toc@\f4wtmpfix\f1:\0\0manipulate connect accounting records@@@\f1see \f3fwtmp(1M)\f1 .\" .\" links@fwtmp.1m wtmpfix.1m .\" .\" fileset_database@fwtmp.1m SYS-ADMIN-MAN .\" $Header: gated.1m,v 80.5 96/11/22 14:09:19 ssa Exp $ .TA g .TH gated 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Formatted: March 1998 .SH NAME gated \- gateway routing daemon .SH SYNOPSIS .C gated .RC [ -c ] .RC [ -C ] .RC [ -n ] .RC [ -N ] .RC [ -t\c .IR trace_options\| ] .RC [ -f .IR config_file\| ] .RI [ trace_file\| ] .SH DESCRIPTION .C gated is a routing daemon that handles multiple routing protocols and replaces routed, egpup, and any routing daemon that speaks the HELLO routing protocol. .C gated currently handles the RIP, BGP, EGP, HELLO, and OSPF routing protocols. The .C gated process can be configured to perform all routing protocols or any subset of them (see .CT WARNINGS below). .SS Options The command-line options are: .RS .TP 12 .C -c Specifies that the configuration file will be parsed for syntax errors and then .C gated will exit. .C gated will leave a dump file in .CR /var/tmp/gated_dump if there were no errors. .C gated does not need to be run as the superuser to use the .C -c option but it may not be possible to read the kernel forwarding table and interface configuration if not run as superuser. The .C -c option implies .CR -tgeneral . All .I trace_option clauses in the configuration file will be ignored. .TP .C -C Specifies that the configuration file will just be parsed for syntax errors. .C gated will exit with a status 1 if there were any errors and 0 (zero) if there were not. .C gated does not need to be run as the superuser to use the .C -C option but it may not be possible to read the kernel forwarding table and interface configuration if not run as the superuser. .TP .C -n Specifies that .C gated will not modify the kernel forwarding table. This is used for testing .C gated configurations with actual routing data. .TP .C -N Specifies that .C gated will not daemonize. Normally, if tracing to stderr is not specified .C gated will daemonize if the parent process ID is not 1. This allows the use of an .CR /etc/inittab -like method of invoking .C gated that does not have a PID of 1. .TP .CI -t trace_options Specifies a comma separated list of trace options to be enabled on startup. If no flags are specified, .C general is assumed. No space is allowed between this option and it's arguments. .IP This option must be used to trace events that take place before the configuration file is parsed, such as determining the interface configuration and reading routes from the kernel. .IP See the .CT "GateD Configuration Guide" for valid trace options and a more detailed explanation of tracing. .TP .CI -f \0config_file Use an alternate config file. By default, .C gated uses .CR /etc/gated.conf . .TP .I trace_file Trace file in which to place trace information. .IP If a trace file is specified on the command line, or no trace flags are specified on the command line, .C gated detaches from the terminal and runs in the background. If trace flags are specified without specifying a trace file, .C gated assumes that tracing is desired to stderr and remains in the foreground. .RE .SS "Signal Processing" .PP The following signals may be used to control .CR gated : .RS .TP 12 .C SIGHUP Re-read configuration. A .C SIGHUP causes .C gated to reread the configuration file. .C gated first performs a clean-up of all allocated policy structures. All BGP and EGP peers are flagged for deletion and the configuration file is re-parsed. .IP If the re-parse is successful, any BGP and EGP peers that are no longer in the configuration are shut down, and new peers are started. .C gated attempts to determine if changes to existing peers require a shutdown and restart. OSPF is not capable of reconfiguring; it is shutdown and restarted during a reconfiguration. This may have an adverse impact on the routing system. .IP It should also be possible to enable/disable any protocol without restarting .CR gated . .TP .C SIGINT Snap-shot of current state. .IP The current state of all .C gated tasks, timers, protocols and tables are written to .CR /var/tmp/gated_dump . .IP On systems supporting .CR fork() , this is done by forking a subprocess to dump the table information so as not to impact .CR gated 's routing functions. On systems where memory management does not support copy-on-write, this will cause the .C gated address space to be duplicated; this may cause a noticeable impact on the system. On system not supporting .CR fork() , the main process immediately processes the dump, which may impact .CR gated 's routing functions. .TP .C SIGTERM Graceful shutdown. .IP On receipt of a .CR SIGTERM , .C gated attempts a graceful shutdown. All tasks and protocols are asked to shutdown. Most will terminate immediately, the exception being EGP peers which wait for confirmation. It may be necessary to repeat the .C SIGTERM once or twice if it this process takes too long. .IP All protocol routes are removed from the kernel's routing table on receipt of a .CR SIGTERM . Interface routes, routes with RTF_STATIC set (from the route command where supported) and static routes specifying .C retain will remain. To terminate .C gated with the exterior routes intact, use .CR SIGKILL . .TP .C SIGUSR1 Toggle tracing. .IP On receipt of a .CR SIGUSR1 , .C gated will close the trace file. A subsequent .C SIGUSR1 will cause it to be reopened. This will allow the file to be moved regularly. .IP It is not possible to use .C SIGUSR1 if a trace file has not been specified, or tracing is being performed to stderr. .TP .C SIGUSR2 Check for interface changes. .IP On receipt of a .CR SIGUSR2 , .C gated will rescan the kernel interface list looking for changes. .RE .PP .SH WARNINGS .C gated contains provisions for BGP protocol, but it is not officially supported by HP at the present time. Some RIP version 2 features (RFC1388) are not currently supported: MIB and route tag. The optional OSPF version 2 (RFC1247) feature of TOS (type of service) based routing is not supported. The route aggregation, generating a more general route from compressing the specific routes through the explicit configuration, is not supported in this release. .SH AUTHORS .C gated was primarily developed by Cornell University which includes code from the Regents of the University of California and the University of Maryland. .PP This software and associated documentation is Copyright 1990, 1991, 1992 by Cornell University. .SH SEE ALSO gated.conf(4), arp(1M), fork(2), gdc(1M), ifconfig(1M), netstat(1), ospf_monitor(1M), ripquery(1M), .CT "GateD Documentation" , .CT "GateD Configuration Guide" . .PP .PD 0 .RS 0 .TP 15 RFC\ 891 DCN Local-Network Protocols (HELLO) .TP RFC\ 904 Exterior Gateway Protocol Formal Specification .TP RFC\ 1058 Routing Information Protocol .TP RFC\ 1163 A Border Gateway Protocol (BGP) .TP RFC\ 1164 Application of the Border Gateway Protocol in the Internet .TP RFC\ 1247 OSPF Specification, Version 2. .RE .PD .\" index@\f4gated\f1 \- gateway routing daemon@@@\f3gated(1M)\f1 .\" index@\f1gateway routing daemon@@@\f3gated(1M)\f1 .\" index@\f1routing daemon, gateway@@@\f3gated(1M)\f1 .\" index@\f1daemon, gateway routing@@@\f3gated(1M)\f1 .\" .\" toc@\f3gated(1M)\f1:\0\0\f4gated\f1@@@gateway routing daemon ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .nr H1 1 .wH "" ...\" .rm zA .rm zZ .TH "gdad"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lgdad\*O command" .iX "-[" "Global Directory Agent (GDA)" "starting daemon" .iX "-[" "\*Lgdad\*O process" .SH NAME .PP \*Lgdad\*O - Starts the GDA daemon .wH "" .SH "SYNOPSIS" .zA "edit,10578,R1.1,Revised list of options" .PP \*Lgdad\*O [\*L-D\*O] [\*L-w \*Vroute\*O] [\*L-b | -x\*O] .wH "" .SH "OPTIONS" .VL .LI "\*L-D\*O" For debugging use only. Causes the \*Lgdad\*O process not to fork. .LI "\*L-w \*Eroute\*O" Routes serviceability messages. .LI "\*L-b\*O" Disables BIND name resolution. .LI "\*L-x\*O" Disables X.500 name resolution. .wH "" .LE .zZ "edit,10578,R1.1,Revised list of options" .SH "DESCRIPTION" .PP The \*Lgdad\*O command starts the GDA daemon. The Global Directory Agent (GDA) serves as a connection to the global naming environment. .SS "Privilege Required" You must log in as superuser (root). .SH "NOTES" .PP This command is ordinarily executed by a DCE configuration or startup script. You should use this command interactively only when a \*Lgdad\*O fails to start automatically after a reboot, or if you want to restart \*Lgdad\*O after disabling it to perform a backup or do diagnostic work on the host system. .wH "" .SH "EXAMPLE" .PP To restart \*Lgdad\*O, follow these steps: .AL ...\".uS .LI Log in to the system as superuser (root). .LI Verify that the \*Ldced\*O and \*Lcdsadv\*O processes are running. .LI Enter the following command to restart the \*Lgdad\*O process: .iS \*C# \*Lgdad\*O .iE ...\".uE .LE .PP To stop the GDA, enter the following command: .sS \*C#\*L kill \*Vpid\*O .sE where \*Vpid\*O is the process identifier of the \*Lgdad\*O process. .wH "" .SH "RELATED INFORMATION" .PP Books: \*VOSF DCE Administration Guide\*O .wH "" .wH "" .iX "-]" "\*Lgdad\*O command" .iX "-]" "Global Directory Agent (GDA)" "starting daemon" .iX "-]" "\*Lgdad\*O process" .\" $Header: gdc.1m,v 72.3 94/12/09 14:56:37 ssa Exp $ .TA g .TH gdc 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gdc \- operational user interface for \f2gated\fP(1M) .SH SYNOPSIS .C gdc [ .C \-q ] [ .CI \-t seconds ] .I command .SH DESCRIPTION .C gdc provides a user\-oriented interface for the operation of the .IR gated (1M) routing daemon. It provides support for starting and stopping the daemon, for the delivery of signals to manipulate the daemon when it is operating, for the maintenance and syntax checking of configuration files, and for the production and removal of state dumps and core dumps. .CR gdc can reliably determine .CR gated 's running state and produces a reliable exit status when errors occur, making it advantageous for use in shell scripts which manipulate .CR gated . Commands executed using .CR gdc and, optionally, error messages produced by the execution of those commands, are logged via the same .IR syslogd (1M) facility which .CR gated itself uses, providing an audit trail of operations performed on the daemon. .PP If installed as a setuid root program .CR gdc will allow non-root users who are members of a trusted group (by default the .CR gdmaint group) to manipulate the routing daemon while denying access to others. The name of the user is logged along via .IR syslogd (1M) along with an indication of each command executed, for audit purposes. .PP The command-line options are: .TP 5 .CR -q Run quietly. With this option informational messages which are normally printed to the standard output are suppressed and error messages are logged via .IR syslogd (1M) instead of being printed to the standard error output. This is often convenient when running .CR gdc from a shell script. .TP .CR -t Specifies the time in seconds which .CR gdc will spend waiting for .CR gated to complete certain operations, in particular at termination and startup. By default this value is set to 10 seconds. .PP The following commands cause signals to be delivered to .CR gated for various purpose: .TP 17 .CR COREDUMP Sends an abort signal to .CR gated , causing it to terminate with a core dump. .TP .CR dump Signal .CR gated to dump its current state into the file .CR /var/tmp/gated_dump . .TP .CR interface Signal .CR gated to recheck the interface configuration. .CR gated normally does this periodically in any event, but the facility can be used to force the daemon to check interface status immediately when changes are known to have occurred. .TP .CR KILL Cause .CR gated to terminate ungracefully. Normally useful when the daemon has hung. .TP .CR reconfig Signal .CR gated to reread its configuration file, reconfiguring its current state as appropriate. .TP .CR term Signal .CR gated to terminate after shutting down all operating routing protocols gracefully. Executing this command a second time should cause .CR gated to terminate even if some protocols have not yet fully shut down. .TP .CR toggletrace If .CR gated is currently tracing to a file, cause tracing to be suspended and the trace file to be closed. If .CR gated tracing is current suspended, cause the trace file to be reopened and tracing initiated. This is useful for moving trace files. .PP By default .CR gated obtains its configuration from a file normally named .CR /etc/gated.conf . The .CR gdc program also maintains several other versions of the configuration file, in particular named: .TP 25 .CR /etc/gated.conf+ The .IR new configuration file. When .CR gdc is requested to install a new configuration file, this file is renamed .CR /etc/gated.conf . .TP .CR /etc/gated.conf\- The .IR old configuration file. When .CR gdc is requested to install a new configuration file, the previous .CR /etc/gated.conf is renamed to this name. .TP .CR /etc/gated.conf\-\- The .I really old configuration file. .CR gdc retains the previous .IR old configuration file under this name. .PP The following commands perform operations related to configuration files: .TP 17 .CR checkconf Check .CR /etc/gated.conf for syntax errors. This is usefully done after changes to the configuration file but before sending a .CR reconfig signal to the currently running .CR gated , to ensure that there are no errors in the configuration which would cause the running .CR gated to terminate on reconfiguration. When this command is used, .CR gdc issues an informational message indicating whether there were parse errors or not, and if so saves the error output in a file for inspection. .TP .CR checknew Like .CR checkconf except that the .IR new configuration file, .CR /etc/gated.conf+ , is checked instead. .TP .CR newconf Move the .CR /etc/gated.conf+ file into place as .CR /etc/gated.conf , retaining the older versions of the file as described above. .CR gdc will decline to do anything when given this command if the .IR new configuration file doesn't exist or otherwise looks suspect. .TP .CR backout Rotate the configuration files in the .IR newer direction, in effect moving the .IR old configuration file to .CR /etc/gated.conf . The command will decline to perform the operation if .CR /etc/gated.conf\- doesn't exist or is zero length, or if the operation would delete an existing, non-zero length .CR /etc/gated.conf+ file. .TP .CR BACKOUT Perform a .CR backout operation even if .CR /etc/gated.conf+ exists and is of non-zero length. .TP .CR modeconf Set all configuration files to mode 664, owner root, group gdmaint. This allows a trusted non-root user to modify the configuration files. .TP .CR createconf If .CR /etc/gated.conf+ does not exist, create a zero length file with the file mode set to 664, owner root, group gdmaint. This allows a trusted non-root user to install a new configuration file. .PP The following commands provide support for starting and stopping .CR gated , and for determining its running state: .TP 14 .CR running Determine if .CR gated is currently running. This is done by checking to see if .CR gated has a lock on the file containing its pid, if the pid in the file is sensible and if there is a running process with that pid. Exits with zero status if .CR gated is running, non-zero otherwise. .TP .CR start Start .CR gated . The command returns an error if .CR gated is already running. Otherwise it executes the .CR gated binary and waits for up to the delay interval (10 seconds by default, as set with the .CR -t option otherwise) until the newly started process obtains a lock on the pid file. A non-zero exit status is returned if an error is detected while executing the binary, or if a lock is not obtained on the pid file within the specified wait time. .TP .CR stop Stop .CR gated , gracefully if possible, ungracefully if not. The command returns an error (with non-zero exit status) if .CR gated is not currently running. Otherwise it sends a terminate signal to .CR gated and waits for up to the delay interval (10 seconds by default, as specified with the .CR -t option otherwise) for the process to exit. Should .CR gated fail to exit within the delay interval it is then signaled again with a second terminate signal. Should it fail to exit by the end of the second delay interval it is signalled for a third time with a kill signal. This should force immediate termination unless something is very broken. The command terminates with zero exit status when it detects that .CR gated has terminated, non-zero otherwise. .TP .CR restart If .CR gated is running it is terminated via the same procedure as is used for the .CR stop command above. When the previous .CR gated terminates, or if it was not running prior to command execution, a new .CR gated process is executed using the procedures described for the .CR start command above. A non-zero exit status is returned if any step in this procedure appears to have failed. .PP The following commands allow the removal of files created by the execution of some of the commands above: .TP 17 .CR rmcore Removes any existing .CR gated core dump file. .TP .CR rmdump Removes any existing .CR gated state dump file. .TP .CR rmparse Removes the parse error file generated when a .CR checkconf or .CR checknew command is executed and syntax errors are encountered in the configuration file being checked. .PD .SH FILES .PD 0 .TP 30 .CR /usr/sbin/gated The .CR gated binary .TP .CR /etc/gated.conf Current .CR gated configuration file .TP .CR /etc/gated.conf+ Newer configuration file .TP .CR /etc/gated.conf\- Older configuration file .TP .CR /etc/gated.conf\-\- Much older configuration file .TP .CR /var/run/gated.pid Where .CR gated stores its pid .TP .CR /var/tmp/gated_dump .CR gated 's state dump file .TP .CR /var/tmp/gated_parse Where config file parse errors go .TP .CR /var/tmp Where .CR gated drops its core file .PD .SH AUTHOR .CR gdc was developed by Dennis Ferguson and Cornell University. .SH SEE ALSO gated(1m), gated.config(4), ripquery(1m), syslog(1m). .SH BUGS Many commands only work when .CR gated is installed in the system directory it was configured with. .PP There is not yet any way to tell .CR gdc about systems which name their core dump other than .CR core .RC ( core.gated is a less common possibility). .PP .PD .\" ------------------------------------------------------------------------ .\" .\" GateD, Release 3 .\" .\" Copyright (c) 1990,1991,1992,1993 by Cornell University. .\" .\" THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT .\" LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY .\" AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" Royalty-free licenses to redistribute GateD Release .\" 3 in whole or in part may be obtained by writing to: .\" .\" GateDaemon Project .\" Information Technologies/Network Resources .\" 200 CCC, Garden Avenue .\" Cornell University .\" Ithaca, NY 14853-2601 USA .\" .\" GateD is based on Kirton's EGP, UC Berkeley's routing .\" daemon (routed), and DCN's HELLO routing Protocol. .\" Development of GateD has been supported in part by the .\" National Science Foundation. .\" .\" Please forward bug fixes, enhancements and questions to the .\" gated mailing list: gated-people@gated.cornell.edu. .\" .\" Authors: .\" .\" Jeffrey C Honig .\" Scott W Brim .\" .\" ------------------------------------------------------------------------ .\" .\" Portions of this software may fall under the following .\" copyrights: .\" .\" Copyright (c) 1988 Regents of the University of California. .\" .\" Redistribution and use in source and binary forms are .\" permitted provided that the above copyright notice and .\" this paragraph are duplicated in all such forms and that .\" any documentation, advertising materials, and other .\" materials related to such distribution and use .\" acknowledge that the software was developed by the .\" University of California, Berkeley. The name of the .\" University may not be used to endorse or promote .\" products derived from this software without specific .\" prior written permission. THIS SOFTWARE IS PROVIDED .\" ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, .\" INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" index@\f4gdc\f1 \- operational user interface for dated@@@\f3gdc(1M)\f1 .\" index@\f4gdc\f1 \- user interface for dated@@@\f3gdc(1M)\f1 .\" index@\f1gated's operational user interface@@@\f3gdc(1M)\f1 .\" index@\f1routing daemon, usr interface@@@\f3gdc(1M)\f1 .\" .\" toc@\f3gdc(1M)\f1:\0\0\f4gdc\f1@@@operations user interface for gated .\" .\" fileset_database@gdc.1m INETSVCS-MAN .\" $Header: get_bootp_info.1m,v 74.2 95/03/02 14:49:44 ssa Exp $ .TA g .TH get_bootp_info 1M "" "Series 700 Only" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME get_bootp_info \- get bootp record data on a diskless client .SH SYNOPSIS .C get_bootp_info .RC [ -y .IR \| ] .RC [ -s .IR \| ] .RC [ -G .IR \| ] .RC [ -g .IR \| ] .RC [ -h .IR \| ] .RC [ -m .IR \| ] .RC [ -A .IR \| ] .RC [ -? .IR \| ] .PP .SS Remarks: The output and format of the command may change at any time. HP does not guarantee backward compatibility. .PP .SS Options .C get_bootp_info recognizes the following options: .RS .TP 15 .C -y Reports the yiaddr field, client IP address. (Standard IP address form: ddd.ddd.ddd.ddd) .TP .C -s Reports the siaddr field, client IP address. (Standard IP address form.) .TP .C -G Reports the giaddr field, bootpd gateway IP address. (Standard IP address form.) .TP .C -g Reports the gw= field, client routing gateway IP address. (Standard IP address form.) .TP .C -f Reports the bf= field, bootfile for tftp to download. (Server filename for uxbootlf file.) .TP .C -h Reports the client nodename. (Client hostname.) .TP .C -m Reports the sm= field, network subnet mask. (Standard IP address form.) .TP .C -? Reports usage information. .TP .C -A Reports all the bootp information: .nf .\" NOTE: lines below can be max 78 chars (. to ") to print properly in nroff .PP .C "boot data " .C " op=2 /* packet opcode type */" .C " htype=1 /* hardware addr type*/" .C " hlen=6 /* hardware addr length */" .C " hops=0 /* gateway hops */" .C " xid=10414 /* transaction ID */" .C " secs=0 /* seconds since boot began */" .C " ciaddr=0.0.0.0 /* client IP address */" .C " yiaddr=ddd.ddd.ddd.ddd /* 'your' IP address */" .C " siaddr=ddd.ddd.ddd.ddd /* server IP address */" .C " giaddr=ddd.ddd.ddd.ddd /* gateway IP address */" .C " chaddr=0x xx:xx:xx:xx:xx:xx /* client hardware address */" .C " sname= /* server host name */" .C " file=/export/tftpboot/client/stand/uxbootlf /* boot file name */" .C " vend is RFC 1084 /* vendor-specific area */" .C " subnet mask ddd.ddd.ddd.ddd .C " gateway IP ddd.ddd.ddd.ddd .C " hostname " .PP .SH AUTHOR get_bootp_info() was developed by Hewlett-Packard. .SH FILES .CR /usr/conf/ramroot/get_bootp_info .\" .\" toc@\f3get_bootp_info(1M)\f1:\0\0\f4get_bootp_info\f1@@@get bootp record data on a diskless client .\" .\" index@\f4get_bootp_info\f1 \- get bootp record data on a diskless client@@@\f3get_bootp_info(1M)\f1 .\" index@\f4get_bootp_info\f1 \- bootp record data on a diskless client@@@\f3get_bootp_info(1M)\f1 .\" index@\f4get_bootp_info\f1 \- diskless client, get bootp record@@@\f3get_bootp_info(1M)\f1 .\" index@\f1bootp record on diskless client@@@\f3get_bootp_info(1M)\f1 .\" index@\f1diskless client, get bootp record@@@\f3get_bootp_info(1M)\f1 .\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH getcellname "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lgetcellname\*O command" .SH NAME \*Lgetcellname\*O \- Gets the primary name of the cell .SH "SYNOPSIS" .sS \*Lgetcellname\*O \*L[\*Vhost\*L]\*O .sE .PP \*LArgument\*O .PP .VL .LI "\*Vhost\*O" The name of the host for which to return the cell names, supplied in the form of a host name or an IP adddress. .LE .SH "DESCRIPTION" .PP The \*Lgetcellname\*O command prints the primary name of a cell to standard output. By default, this command returns the name of the local cell. Use the \*Vhost\*O argument to return the name of a cell on a remote host. If the command fails, it prints an error message to standard error. .SH "EXAMPLES" .oS % \*Lgetcellname santan\*C /.../dc.cell.ch.company.com % % \*Lgetcellname 15.22.49.22\*C /.../dc.cell.ch.company.com % .oE .SH "FILES" .PP \*Vdcelocal/\*Ldce_cf.db\*O .P The local DCE configuration database. .SH "RELATED INFORMATION" .PP Functions: \*Ldce_cf_get_cell_name(3)\*O .\" $Header: getext.1m,v 78.1 96/02/13 12:19:44 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA g .TH getext 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getext (vxfs) \- get extent attributes .SH SYNOPSIS .CR /usr/sbin/getext .RC [ \-F .CR vxfs ] .RC [ \-V ] .RC [ \-f ] .RC [ \-s ] .I file... .SH DESCRIPTION The .C getext command displays extent attribute information associated with a set of files. .SS Options .RS .TP 15 .CR \-F\0vxfs Specifies the VxFS file system type. .TP .C \-V Echoes the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options. This option allows the user to verify the command line. .TP .C \-f Do not print the filenames for which extent attributes are displayed. .TP .C \-s Do not print output for files that do not have fixed extent sizes or reservations. .SH "OUTPUT" file1: Bsize 1024 Reserve 36 Extent Size 3 align noextend .PP The above line indicates a file with 36 blocks of reservation, a fixed extent size of 3 blocks, all extents aligned to 3 block boundaries, and the file cannot be extended once the current reservation is exhausted. In this case, the file system block size is 1024 bytes. Reservation and fixed extent sizes are allocated in units of the file system block size. .SH "NOTES" Only the .C align and .C noextend allocation flags (set through .C setext(1M) or the VX_SETEXT ioctl) are persistent attributes of the file and therefore visible via .C getext or the VX_GETEXT ioctl. .C trim is also visible, although it is cleared and the reservation is reduced on the final close of the file. .SH "SEE ALSO" setext(1M), vxfsio(7). .\" .\" toc@\f3getext(1M)\f1:\0\0\f(CWgetext\f1@@@get extent attributes (VxFS) .\" .\" index@\f(CWgetext\f1 \- get extent attributes (VxFS)@@@\f3getext(1M)\f1 .\" .\" index@\f1get extent attributes (VxFS)@@@\f3getext(1M)\f1 .\" index@\f1VxFS Advanced, get extent attributes@@@\f3getext(1M)\f1 .\" index@\f1extent attributes (VxFS), get@@@\f3getext(1M)\f1 .\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH getip "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lgetip\*O command" .SH NAME \*Lgetip\*O \- Gets a host's IP address .SH "SYNOPSIS" .sS \*Lgetip\*O \*Vhost\*O .sE .SH "ARGUMENTS" .VL 1i .LI "\*Vhost\*O" The \*Vhost\*O argument indicates the name of the machine whose IP address you want to obtain. .LE .SH "DESCRIPTION" .zA "defect,CR4680,R1.0.2,new getip manpage" .PP The \*Lgetip\*O command prints the IP address of the machine indicated in the \*Vhost\*O argument. A machine may have more than one IP address associated with it; if so, \*Lgetip\*O prints one of the addresses. If the command fails, it returns a status of 1. .SH "RELATED INFORMATION" .PP Functions: \*Lgethostbyname(3)\*O .zZ "defect,CR4680,R1.0.2,new getip manpage" .\" $Header: getty.1m,v 72.2 93/11/17 23:13:11 ssa Exp $ .TA g .TH getty 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getty \- set terminal type, modes, speed, and line discipline .SH SYNOPSIS .B /usr/sbin/getty .RB [ \|\-h\| ] .RB [ \| \-t .IR timeout\| ] .I line .RI [ \|speed .RI [ \|type .RI [ \|linedesc\| ]\|]\|] .br .B /usr/sbin/getty \-c .I file .SH DESCRIPTION .I getty is a program that is invoked by .IR init (1M). It is the second process in the series, .RI ( init-getty-login-shell ) that ultimately connects a user with the .SM HP-UX system. Initially, if .B /etc/issue exists, .I getty prints its contents to the user's terminal, followed by the login message field for the entry it is using from .BR /etc/gettydefs . .I getty reads the user's login name and invokes the .IR login (1) command with the user's name as argument. While reading the name, .I getty attempts to adapt the system to the speed and type of terminal being used. .SS Configuration Options and Arguments .I getty recognizes the following arguments: .RS .TP 12 .I line Name of a tty line in .B /dev to which .I getty is to attach itself. .I getty uses this string as the name of a file in the .B /dev directory to open for reading and writing. By default .I getty forces a hangup on the line by setting the speed to zero before setting the speed to the default or specified speed. However, when .I getty is run on a direct port, .I getty does not force a hangup on the line since the driver ignores changes to zero speed on ports open in direct mode (see .IR modem (7)). .TP .B \-h Tells .I getty not to force a hangup on the line before setting the speed to the default or specified speed. .TP .BI \-t \ timeout .I getty exits if the open on the line succeeds and no one types anything within .I timeout seconds. .TP .I speed A label to a speed and tty definition in the file .BR /etc/gettydefs . This definition tells .I getty at what speed to initially run, what the login message should look like, what the initial tty settings are, and what speed to try next should the user indicate that the speed is inappropriate (by typing a .I break character). The default .I speed is 300 baud. .TP .I type A character string describing to .I getty what type of terminal is connected to the line in question. .I getty understands the following types: .RS .IP .TS l l. \f3none\f1 default \f3vt61\f1 \s-1DEC\s+1 vt61 \f3vt100\f1 \s-1DEC\s+1 vt100 \f3hp45\f1 Hewlett-Packard \s-1HP\s02645 \f3c100\f1 Concept 100 .TE .RE .IP The default terminal is .BR none ; i.e., any crt or normal terminal unknown to the system. Also, for terminal type to have any meaning, the virtual terminal handlers must be compiled into the operating system. They are available, but not compiled in the default condition. .TP .I linedesc A character string describing which line discipline to use when communicating with the terminal. Hooks for line disciplines are available in the operating system, but there is only one presently available \(em the default line discipline, .SM .BR LDISC0 . .RE .PP When given no optional arguments, .I getty sets the .I speed of the interface to 300 baud, specifies that raw mode is to be used (awaken on every character), that echo is to be suppressed, either parity allowed, new-line characters will be converted to carriage return-line feed, and tab expansion performed on the standard output. It types the login message before reading the user's name a character at a time. If a null character (or framing error) is received, it is assumed to be the result of the user pushing the ``break'' key. This causes .I getty to attempt the next .I speed in the series. The series that .I getty tries is determined by what it finds in .BR /etc/gettydefs . .PP The user's name is terminated by a new-line or carriage-return character. The latter results in the system being set to treat carriage returns appropriately (see .IR ioctl (2)). .PP The user's name is scanned to see if it contains any lowercase alphabetic characters; if not, and if the name is non-empty, the system is told to map any future uppercase characters into the corresponding lowercase characters. .PP .I getty also understands the ``standard'' \s-1ESS\s02 protocols for erasing, killing and aborting a line, and terminating a line. If .I getty sees the .SM ESS erase character, .BR _ , or kill character, .BR $ , or abort character, .BR & , or the .SM ESS line terminators, .B / or .BR ! , it arranges for this set of characters to be used for these functions. .PP Finally, .I login is called with the user's name as an argument. Additional arguments can be typed after the login name. These are passed to .IR login , which places them in the environment (see .IR login (1)). .SS Check Option A check option is provided. When .I getty is invoked with the .B \-c option and .IR file , it scans .I file as if scanning .B /etc/gettydefs and prints the results on the standard output. If there are any unrecognized modes or improperly constructed entries, .I getty reports these. If the entries are correct, .I getty prints out the values of the various flags. See .IR ioctl (2) for an interpretation of values. Note that some values are added to the flags automatically. .SH DEPENDENCIES HP\|2334 MultiMux: .IP The modem control parameter .SM .I MRTS must be present in the .B /etc/gettydefs file when using .I getty in conjunction with an .SM HP\|2334 or .SM HP\|2335 MultiMux to ensure that the .SM RTS modem control signal is asserted correctly. .IP Example: .RS .IP .SM "9600# B9600 HUPCL PARENB \f3MRTS\f1 # B9600 SANE PARENB ISTRIP IXANY #login: #19200" .RE .IP .SM MRTS is not intended for use with devices other than the .SM HP\|2334 or .SM HP\|2335 MultiMux. .SH FILES /etc/gettydefs .br /etc/issue .SH SEE ALSO ct(1), login(1), init(1M), ioctl(2), gettydefs(4), inittab(4), modem(7), termio(7). .SH BUGS While .I getty does understand simple single character quoting conventions, it is not possible to quote the special control characters that .I getty uses to determine when the end of the line has been reached, which protocol is being used, and what the erase character is. Therefore it is not possible to log in by means of .I getty and type a .BR # , \f3@\f1, .BR / , .BR ! , .BR _ , backspace, .BR ^U , .BR ^D , or .B & as part of your login name or arguments. They will always be interpreted as having their special meaning as described above. .\" index@\f2getty\f1 \- set terminal type, modes, speed, and line discipline@@@\f3getty(1M)\f1 .\" index@set terminal type, modes, speed, and line discipline@@@\f3getty(1M)\f1 .\" index@terminal type, modes, speed, and line discipline, set@@@\f3getty(1M)\f1 .\" .\" toc@\f3getty(1M)\f1:\0\0\f2getty \f1@@@set terminal type, modes, speed, and line discipline .\" .\" fileset_database@getty.1m@SYS-ADMIN-MAN .\" $Header: getx25.1m,v 72.7 94/12/16 09:54:10 ssa Exp $ .TA g .TH getx25 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getx25 \- get x25 line .SH SYNOPSIS .C /usr/sbin/getx25 .I line\0\0speed\0pad-type .SH DESCRIPTION .CR getx25 is functionally very similar to .CR getty (see .IR getty (1M)) but is used only for incoming lines that are connected to an X.25 PAD. It performs special functions such as setting up an initial PAD configuration. It also logs the number of the caller in .CR /var/uucp/.Log/LOGX25 . The third parameter is the name of the PAD being used. HP 2334A is the only one supported at this time. A typical invocation would be: .IP .C "/usr/sbin/getx25 x25.1 2 HP2334A" .SH AUTHOR .CR getx25 was developed by HP. .SH SEE ALSO login(1), uucp(1), getty(1M). .PP .\" .\" index@\f4getx25\f1 \- get \s-1X.25\s+1 line@@@\f3getx25(1M)\f1 .\" index@get \s-1X.25\s+1 line@@@\f3getx25(1M)\f1 .\" index@\s-1X.25\s+1 line, get@@@\f3getx25(1M)\f1 .\" index@line, get \s-1X.25\s+1@@@\f3getx25(1M)\f1 .\" .\" toc@\f3getx25(1M)\f1:\0\0\f4getx25\f1@@@get x25 line .\" .\" fileset_database@getx25.1m SYS-ADMIN-MAN .\" $Header: glbd.1m,v 72.2 94/10/27 14:36:45 ssa Exp $ .TA g .TH glbd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME glbd \- Global Location Broker Daemon .SH SYNOPSIS .B /usr/sbin/ncs/glbd .RB [ \|\-create .RB { \|\-first .RB [ \|\-family .IR family_name\| ]\ | .B \-from .IR host_name\| \|] .RB [ \|\-change_family .IR family_name\| ] .RB [ \|\-listen .IR family_list\| ] .RB [ \|\-version\| ] .SH DESCRIPTION The Global Location Broker .SM (GLB), part of the Network Computing System .SM (NCS), helps clients locate servers on a network or internet. The .SM GLB database stores the locations (that is, the network addresses and port numbers) where server processes are running. A daemon maintains this database and provides access to it. .PP The .SM GLB database can be replicated to increase its availability. Copies of the database can exist on several hosts, with a .I glbd running on each of those hosts to maintain the consistency of the database replicas. (In an internet, at least one .I glbd must run in each network.) Each replica of the .SM GLB keeps a list of all the other .SM GLB replicas. .IR drm_admin (1M) administers the replication of the .SM GLB database and the replica list. .PP Currently, .I glbd supports both the .SM DARPA IP and Domain .SM DDS network protocols. A .SM GLB replica can allow access to its database from both .SM IP and .SM DDS clients. However, when communicating with each other to maintain replication of the .SM GLB database, .SM GLB replicas should use only one protocol family. You choose which family the GLBs will use. In an internet, all routing nodes must support this family. .PP If a set of .SM GLB replicas includes any HP-UX, SunOS, or ULTRIX systems, all replicas must use IP protocols to communicate with each other. A replica running on a Domain/OS system can communicate with other replicas via IP protocols but still provide lookup and update services to its clients via both IP and DDS protocols. .SS "Running glbd on HP-UX Systems" On HP-UX systems, the .SM GLB communicates only via IP protocols. A Remote Procedure Call daemon .RI ( rpcd ) must be running on the local host when .I glbd is started. .PP Typically, the .I rpcd and .I glbd processes are started in background at boot time. If the .SM .B START_GLBD variable in .B /etc/rc.config.d/ncs is set to 1, a .I glbd will be started. To start the .I rpcd and .I glbd daemons by hand, you must be root. .SH OPTIONS .TP 12 .B \-create Create a replica of the GLB. This option creates a .SM GLB database in addition to starting a broker process. It must be used with either .B \-first or .BR \-from . .TP .B \-first This option can be used only with the .B \-create option. Use it to create the first replica (that is, the very first instance) of the .SM GLB on your network or internet. .TP .BI \-family \ family_name This option can be used only in conjunction with the .B \-first option. It specifies the address family that the first .SM GLB replica will use to identify itself on the replica list. Any subsequently created replicas must use this family to communicate with this replica. Currently, .I family_name can be either .B ip or .BR dds . If this option is not used, the replica will be identified on the replica list by its .SM IP address. .TP .BI \-from \ host_name This option can be used only with the .B \-create option. Use it to create additional replicas of the .SM GLB. A replica of the .SM GLB must exist at .IR host_name . The database and replica list for the new replica are initialized from those at .IR host_name . The replica at .I host_name adds an entry for the new replica to its replica list and propagates the entry to the other .SM GLB replicas. .IP A .I host_name takes the form .IB family : host\f1, where the host can be specified either by its name or by its network address. For example, .BR ip:bertie , .BR ip:#192.5.5.5 , .BR dds://jeeves , and .BR dds:#959a.940f are acceptable host names. .IP The new replica will use the same address family as .I host_name in identifying itself on the replica list. For example, if .I host_name is an .SM IP address, the new replica will be listed by its IP address on the replica list. .TP .BI \-change_family \ family_name Use this option only if network reconfigurations require that you change the address family of every .SM GLB replica; see the discussion in the .SM DESCRIPTION section. Currently, .I family_name can be either .B ip or .BR dds . (If a .SM GLB replica runs on an .SM HP-UX host, its address family must be IP.) .IP For a procedure to change all of your .SM GLB replicas from one address family to another, see .IR "Managing NCS Software" . .TP .BI \-listen \ family_list This option restricts the address families on which a .SM GLB listens. Use it only if you are creating a special configuration where access to a .SM GLB is restricted to a subset of hosts in the network or internet. .IP The .I family_list is a list of the address families on which the .SM GLB will listen. Names in this list are separated by spaces. Possible family names include .B ip and .BR dds . .IP The .SM GLB will always listen for requests from the family by which it is listed on the replica list, even if that family is not specified in .IR family_list . .IP If .I glbd is started without the .B \-listen option, the .SM GLB will listen on all address families that are supported both by .SM NCS and by the local host. On Domain/OS systems, this set of families always includes .B dds and may also include .BR ip . On most other systems, including .SM HP-UX systems, .B ip is currently the only family. .TP .B \-version Display the version of .SM NCK that this .I glbd belongs to, but do not start the daemon. .SH EXAMPLES Create and start for the first time the first replica of the .SM GLB on this network or internet: .IP \f1$ \f3 /usr/sbin/ncs/glbd \-create \-first &\f1 .PP Start for the first time a subsequent replica of the .SM GLB, initializing its database from host .BR jeeves : .IP \f1$ \f3/usr/sbin/ncs/glbd \-create \-from ip:jeeves &\f1 .PP Restart an existing replica of the .SM GLB: .IP \f1$ \f3/usr/sbin/ncs/glbd &\f1 .SH FILES On HP-UX systems, .I glbd writes diagnostic output to the file .BR /var/ncs/glb_log . .SH SEE ALSO drm_admin(1M), lb_admin(1M), rpcd(1M), glb_obj.txt(4), glb_site.txt(4). .PP .IR "Managing NCS Software" . .\" .\" index@\f2glbd\f1 \- Global Location Broker daemon@@@\f3glbd(1M)\f1 .\" index@Global Location Broker daemon@@@\f3glbd(1M)\f1 .\" index@replicating Global Location Brokers@@@\f3glbd(1M)\f1 .\" index@Location Broker daemon, Global@@@\f3glbd(1M)\f1 .\" index@Broker daemon, Global Location@@@\f3glbd(1M)\f1 .\" index@daemon, Global Location Broker@@@\f3glbd(1M)\f1 .\" .\" toc@\f3glbd(1M)\f1:\0\0\f2glbd\f1@@@Global Location Broker daemon .\" .\" fileset_database@glbd.1m@SYS-ADMIN-MAN .TH GRMD 1M "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.0 .ad b .SH NAME grmd \- graphics resource manager daemon .SH SYNOPSIS .B grmd .SH DESCRIPTION The .I grmd program manages shared resources among cooperating X Window System servers and Starbase processes. The grmd receives requests from these client programs, processes the requests, and returns results to the clients. The resources managed by the grmd include allocation of objects from a shared memory segment and from display frame buffer offscreen memory. .PP .I Grmd is invoked automatically by the X Window System and Starbase processes. When invoked the .I grmd creates a shared memory segment and a semaphore during its initialization. The .I grmd is installed to run as user .I daemon so that it may reliably remove the semaphore. .PP The .I grmd communicates with its clients via a UNIX domain socket. The grmd creates the socket in the directory .I /var/spool/sockets. .SH FILES .PD 0 .TP 25 .B /usr/lbin/grmd grmd executable .TP 25 .B /var/spool/sockets directory created to contain the grmd and other UNIX domain sockets .PD .SH AUTHOR HP .\" $Header: groupadd.1m,v 78.1 96/05/09 10:51:12 ssa Exp $ .TA g .TH groupadd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME groupadd \- add a new group to the system .SH SYNOPSIS .CR groupadd .RC [ -g .I gid .RC [ -o ]\| .RI ]\| " group" .SH DESCRIPTION The .CR groupadd command creates a new group on the system by adding the appropriate entry to the .CR /etc/group file. The .CR groupadd command expects the .I group argument, which is the name of the new group. The name consists of a string of printable characters that may not include a colon (:) or newline (\\n). .SS Options The .CR groupadd command may be used with the following options: .RS .TP 10 .CI -g " gid" Specifies the group .SM ID for the new group. .I gid must be a non-negative decimal integer less than .SM MAXUID as defined in the .RC < param.h > header file. By default the next available unique group .SM ID in the valid range is allocated. Group .SM ID\c s in the range 0-99 are reserved. .TP .C -o Allow the .I gid to be non-unique (i.e., a duplicate). .SH NETWORKING FEATURES The .CR groupadd command is aware of .SM NIS user entries. Only local groups may be added with this command. Attempts to add an .SM NIS group will result in an error. .SM NIS groups must be administered from the .SM NIS server. If .CR groupadd is used on a system where .SM NIS is installed, it may fail with the error .IP .CI "group " x .CR "is not unique" .PP (return value 9) if the group specified is not present in the local .CR /etc/group file, but is an .SM NIS group (see .IR group (4)). .SM NIS groups are also checked when verifying uniqueness of the new .IR gid , which may result in the error .IP .C GID # is not unique .PP (return value 4). .SH RETURN VALUE The .CR groupadd command exits with one of the following values: .RS .TP 5 .C 0 No error. .PD 0 .TP .C 2 Invalid command syntax. .TP .C 3 Invalid argument supplied to an option. .TP .C 4 .I gid is not unique (when .CR -o is not used). .TP .C 9 .I group is not unique. .TP .C 10 Cannot modify the .CR /etc/group file. .TP .C 11 .CR /etc/passwd file or .CR /etc/ptmp file busy. Another command may be modifying the .CR /etc/passwd file. .TP .C 12 Unable to open .CR /etc/ptmp file or .CR /etc/passwd file is non-existent. .PD .RE .SH EXAMPLES Add the group .CR project1 to the .CR /etc/group file. .IP .C groupadd project1 .PP Add the group .CR project12 to the .CR /etc/group file with the group .SM ID .CR 111 as long as no group currently exists with a group .SM ID of .CR 111 . .IP .C groupadd -g 111 project12 .SH WARNINGS As many users may try to write the .CR /etc/passwd file simultaneously, a passwd locking mechanism was deviced. If this locking fails after subsequent retrying, .CR groupadd terminates. .SH FILES .C /etc/group .br .C /etc/ptmp .SH SEE ALSO users(1), groupdel(1M), groupmod(1M), logins(1M), useradd(1M), userdel(1M), usermod(1M), group(4). .SH STANDARDS CONFORMANCE .CR groupadd ": SVID3" .\" toc@\f3groupadd(1M)\f1:\0\0\f4groupadd\f1@@@add a new group to the system\f1 .\" index@\f4groupadd\f1 \- add a new group to the system@@@\f3groupadd(1M)\f1 .\" index@\f1add a new group to the system@@@\f3groupadd(1M)\f1 .\" index@\f1group, add a new@@@\f3groupadd(1M)\f1 .\" $Header: groupdel.1m,v 78.1 96/05/09 10:51:46 ssa Exp $ .TA g .TH groupdel 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME groupdel \- delete a group from the system .SH SYNOPSIS .CI groupdel " group" .SH DESCRIPTION The .CR groupdel command deletes a group from the system by removing the appropriate entry from the .CR /etc/group file. .PP The .CR groupdel command must be used with the .I group argument. .I group is the name of the group to be deleted, consisting of a string of printable characters. .SH NETWORKING FEATURES This command is aware of .SM NIS user entries. Only local groups may be deleted with .CR groupdel . Attempts to delete an .SM NIS group will result in an error. .SM NIS groups must be administered from the .SM NIS server. If .CR groupdel is used on a system where .SM NIS is installed, it may fail with the error .IP .CI "group " x " does not exist" .PP (return value 6), if the group specified is an .SM NIS group (see .IR group (4)). .SH RETURN VALUE .CR groupdel exits with one of the following values: .RS .TP 5 .C 0 No error. .PD 0 .TP .C 2 Invalid command syntax. .TP .C 3 Invalid argument supplied to an option. .TP .C 6 .I group does not exist. .TP .C 10 Cannot modify the .CR /etc/group file. .TP .C 11 .CR /etc/passwd file or .CR /etc/ptmp file busy. Another command may be modifying the .CR /etc/passwd file. .TP .C 12 Unable to open .CR /etc/ptmp or .CR /etc/passwd file is non-existent. .PD .RE .SH EXAMPLES Delete the group .CR project1 from the .CR /etc/group file if it exists: .IP .C groupdel project1 .SH WARNINGS As many users may try to write the .CR /etc/passwd file simultaneously, a passwd locking mechanism was deviced. If this locking fails after subsequent retrying, .CR groupdel terminates. .SH FILES .C /etc/group .br .C /etc/ptmp .SH SEE ALSO users(1), groupadd(1M), groupmod(1M), logins(1M), useradd(1M), userdel(1M), usermod(1M), group(4). .SH STANDARDS CONFORMANCE .CR groupdel ": SVID3" .\" .\" toc@\f3groupdel(1M)\f1:\0\0\f4groupdel\f1@@@delete a group from the system\f1 .\" index@\f4groupdel\f1 \- delete a group from the system@@@\f3groupdel(1M)\f1 .\" index@\f1delete a group from the system@@@\f3groupdel(1M)\f1 .\" index@\f1group, delete from the system@@@\f3groupdel(1M)\f1 .\" $Header: groupmod.1m,v 78.1 96/05/09 10:52:24 ssa Exp $ .TA g .TH groupmod 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME groupmod \- modify a group on the system .SH SYNOPSIS .C groupmod .RC [ -g .I gid .RC [ -o ] .RC \|] .RC [ -n .IR name ] .I " group" .SH DESCRIPTION The .CR groupmod command modifies a group on the system by altering the appropriate entry in the .CR /etc/group file. .PP The .CR groupmod command must be used with the .I group argument, which is the name of the group to be modified. .SS Options .PP The .CR groupmod command may be used with the following options: .RS .TP 10 .CI -g " gid" Change the value of the group .SM ID to .IR gid . .I gid must be a non-negative decimal integer less than .SM MAXUID as defined in the .RC < param.h > header file. .TP .C -o Allow the .I gid to be non-unique (i.e., a duplicate). .TP .CI -n " name" Change the name of the group to .IR name . .I name consists of a string of printable characters that may not include a colon (:) or newline (\\n). .RE .SH NETWORKING FEATURES This command is aware of .SM NIS user entries. Only local groups may be modified with .CR groupmod . Attempts to modify an .SM NIS group will result in an error. .SM NIS groups must be administered from the .SM NIS server. If .CR groupmod is used on a system where .SM NIS is installed, it may fail with the error .IP .CI "group " x " does not exist" .PP (return value 6) if the group specified is an .SM NIS group (see .IR group (4)). However, .SM NIS groups are checked when verifying uniqueness of the new .I gid or new group name, which may result in the above error, or the error .IP .C GID # is not unique .PP (return value 4). .SH RETURN VALUES .CR groupmod exits with one of the following values: .RS .TP 5 .C 0 No error. .PD 0 .TP .C 2 Invalid command syntax. .TP .C 3 Invalid argument supplied to an option. .TP .C 4 .I gid is not unique (when .CR -o is not used). .TP .C 6 .I group does not exist. .TP .C 9 .I group is not unique. .TP .C 10 Cannot modify the .CR /etc/group file. .TP .C 11 .CR /etc/passwd file or .CR /etc/ptmp file busy. Another command may be modifying the .CR /etc/passwd file. .TP .C 12 Unable to open .CR /etc/ptmp file or the .CR /etc/passwd file is non-existent. .PD .RE .SH EXAMPLES Change the group .SM ID of the group .CR project2 to .CR 111 in the file .CR /etc/group if the group .CR project2 exists. This is done even if the group .SM ID .CR 111 is already in use. .IP .C groupmod -g 111 -o project2 .PP Change the name of .CR project2 to .CR project22 in the file .CR /etc/group if the group .CR project22 does not already exist. .IP .C groupmod -n project22 project2 .SH WARNINGS As many users may try to write the .CR /etc/passwd file simultaneously, a passwd locking mechanism was deviced. If this locking fails after subsequent retrying, .CR groupmod terminates. .SH FILES .C /etc/group .br .C /etc/ptmp .SH SEE ALSO users(1), groupadd(1M), groupdel(1M), logins(1M), useradd(1M), userdel(1M), usermod(1M), group(4). .SH STANDARDS CONFORMANCE .CR groupmod ": SVID3" .\" toc@\f3groupmod(1M)\f1:\0\0\f4groupmod\f1@@@modify a group on the system\f1 .\" index@\f4groupmod\f1 \- modify a group on the system@@@\f3groupmod(1M)\f1 .\" index@\f1modify a group on the system@@@\f3groupmod(1M)\f1 .\" index@\f1group, modify a@@@\f3groupmod(1M)\f1 .\" $Header: pwck.1m,v 72.4 94/11/14 15:23:23 ssa Exp $ .TA p .TH pwck 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pwck, grpck \- password/group file checkers .SH SYNOPSIS .C /usr/sbin/pwck .RI [ \|file\| ] .br .C /usr/sbin/grpck .RI [ \|file\| ] .SH DESCRIPTION .C pwck scans the default password file or .I file and reports any inconsistencies to standard error. The checks include validation of the number of fields, login name, user .SM ID, group .SM ID, and whether the login directory and optional program name exist. The criteria for determining a valid login name are described in the .I HP-UX System Administrator manuals for your system. The default password file is .CR /etc/passwd . .PP .C grpck verifies all entries in the group file and reports any inconsistencies to standard error. This verification includes a check of the number of fields, group name, group .SM ID, and whether all login names appear in the password file. The default group file is .CR /etc/group . .SH DIAGNOSTICS Group entries in .CR /etc/group with no login names are flagged. .SH AUTHOR .C pwck was developed by AT&T and HP. .SH DEPENDENCIES .SS \s-1NFS\s0: .C pwck and .C grpck check only the local password and group files. The Network Information Service database for password and group files is not checked. .SH FILES .C /etc/group .br .C /etc/passwd .SH SEE ALSO group(4), passwd(4). .SH STANDARDS CONFORMANCE .CR pwck ": SVID2, SVID3" .PP .CR grpck ": SVID2, SVID3" .\" .\" index@\f4pwck\f1 \- password file checker@@@\f3pwck(1M)\f1 .\" index@\f4grpck\f1 \- group file checker@@@\f3pwck(1M)\f1 .\" index@check password or group file@@@\f3pwck(1M)\f1 .\" index@password file, check@@@\f3pwck(1M)\f1 .\" index@group file, check@@@\f3pwck(1M)\f1 .\" .\" toc@\f3pwck(1M)\f1:\0\0\f4pwck\f1, \f4grpck\f1@@@password/group file checkers .\" toc@\f4grpck\f1:\0\0group file checker@@@see \f3pwck(1M)\f1 .\" .\" links@pwck.1m grpck.1m .\" .\" fileset_database@pwck.1m SYS-ADMIN-MAN ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH help 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldtscp\*O commands" "\*Lhelp\*O" .SH NAME .PP \*Lhelp\*O - Displays help information about \*Ldtscp\*O commands. .SH "SYNOPSIS" .PP .zA "defect,6211,R1.0.3,add control program name" .sS \*Ldtscp help\*O [\*Vhelp-topic\*O] .sE .zZ "defect,6211,R1.0.3,add control program name" .SH "ARGUMENTS" .VL .LI "\*Vhelp-topic\*O" Specifies the help topic for which help information is to be displayed. The following are valid help topics: .PP .ML .LI \*Ladvertise\*O .LI \*Lchange\*O .LI \*Lcreate\*O .LI \*Ldelete\*O .LI \*Ldisable\*O .LI \*Lenable\*O .LI \*Lset\*O .LI \*Lshow\*O .LI \*Lsynchronize\*O .LI \*Lunadvertise\*O .LI \*Lupdate\*O .LE .LE .SH "DESCRIPTION" The \*Lhelp\*O command displays information about \*Ldtscp\*O commands. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command may be replaced in future releases by the \*Ldcecp\*O command, and may no longer be supported at that time. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" The following command shows how to get help about the help subtopic \*Lunadvertise\*O. .iS \*Cdtscp>\*O \*Lhelp unadvertise\*O .iE .\" $Header: hosts_to_na.1m,v 76.1 95/05/26 16:59:55 ssa Exp $ .TA h .TH hosts_to_named 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hosts_to_named \- Translate host table to name server file format .SH SYNOPSIS .C hosts_to_named .C \-d .I domain .C \-n .I network-number .RI [ \|options\| ] .SH DESCRIPTION .CR hosts_to_named translates the host table, .CR /etc/hosts , into files that are usable by the name server .IR named (1M). The format of these files is defined in RFC1035. The files are created in the current directory. Once the host table is translated, the name server files can be maintained directly, or the translation can be repeated after each change to the host table. .PP If a line in the host table contains no domain names, all names on the line are assumed to be in the default domain. The first .I domain listed is the "default domain". If data is being created for more than 1 domain or if certain options are used, there must be domain names in the host table to determine which names belong in which domain. .PP The name server data is referred to as "resource records". .PP Options are: .RS .TP 15 .CI \-a " network-number" Add the information about hosts in the local domain from network .IR network-number. This is the same as the .CR \-n option except that no pointer (PTR) data is created. This is useful when there are multiple domains on a network and a different server is handling the address-to-name mapping for .IR network-number. .TP .CI \-b " bootfile" Name the boot file .IR bootfile . The default is .C named.boot in the current directory. .TP .CI \-c " subdomain" Create alias (CNAME) records for hosts in .I subdomain of the default domain. When a subdomain is delegated, it is useful to create aliases for the old names in the default domain that point to the new names in the .IR subdomain . After creating the alias (CNAME) records, ignore lines in the host table that contain names in the .IR subdomain . This option can be used more than once on the command line. This option requires domain names in the host table. When the old names in this .I domain are no longer used, they can be ignored with the .CR \-e option. If the .I subdomain name does not have dots, the default domain is appended to .IR subdomain . .TP .CI \-d " domain" Create data for .IR domain. This option can be used more than once on the command line if data is being created for more than 1 domain. The first .I domain listed is the "default domain". This option requires domain names in the host table for all hosts in domains except the default domain. .TP .CI \-e " subdomain" Eliminate lines from the host table that contain names in the .I subdomain before translating. If the .I subdomain name does not have dots, the default domain is appended. This option may be used more than once on the command line. This option requires domain names in the host table. .TP .CI \-f " file" Read command line options from .IR file . The .CR \-f option is not allowed within a file. .TP .CI \-h " host" Declare .I host to be the host in the start of authority (SOA) record that the name server data was created on. Also use .I host for the electronic mail address of the responsible user in the SOA record. The default is the host this command is run on. .TP .CI \-m " weight:mailhub" For each canonical hostname from the host table, create mail exchanger (MX) records with the specified weight and mail hub. The weight is a positive integer. The mail hub is a hostname. If the mail hub name has no dots, the default domain is appended. This option can be used more than once on the command line. .TP .CI \-n " network-number\f1[:\fPmask\f1]\fP" Create data for .IR network-number. See below for description of .IR network-number. If only one .I domain is listed with .CR \-d , all data for .I network-number is assumed to be in .IR domain . The optional subnet mask .I mask can be used instead of supplying each .I network-number for a subnet using multiple .CR \-n options. .I mask must be in dot notation. .TP .CI \-o " refresh:retry:expire:min" Set the values in the start-of-authority (SOA) record to those specified. See below for description of the start-of-authority (SOA) record. .TP .CI \-p " domain" Create only pointer (PTR) data for hosts in .IR domain . This is useful when there are multiple domains on a network and a different server is responsible for .IR domain , but this server is responsible for the address-to-name mapping. This option can be used more than once on the command line. This option requires domain names in the host table. .TP .C \-q Run quietly. No messages are printed. .TP .C \-r Create name server data indicating that the name server is authoritative for .C . (the root of the domain tree). The file created is .CR db.root . Use this only when your network is isolated from the Internet. If other root servers exist for the isolated network, they must be added manually. .TP .CI \-s " server" Create name server (NS) records that declare .I server is an authoritative name server for all of the domains created. If more than 1 server is authoritative, each needs to be declared. If the server name does not have any dots in it, the default domain is appended. The default server is the host this script is run on. This option can be used more than once on the command line. .TP .C \-t Create text (TXT) records from the comments that appear with host data. The comments will all be in lower case because the host table is translated to lower case. If .C [no smtp] appears in a comment, it is omitted. The .C [no smtp] is used to control mail exchanger (MX) data. .TP .CI \-u " user" Declare .I user to be the electronic mail address of the person responsible for this domain. This is used in the start of authority (SOA) record. The format required in the name server data is .IR user\c .IR .host (host must be a domain name). If given as .IR user , the host on which this script is run is appended. If given as .I user\c .RC @\c .IR host , the .RC @ is replaced with a dot .RC ( . ). The default user is .CR root . .TP .C \-w Create well known services (WKS) data declaring that the host provides the SMTP service. This is done only when mail exchanger (MX) data is also being created and only for hosts without .C [no smtp] in a comment. .TP .CI \-z " internet-address" Create a secondary boot file, .CR boot.sec.save , from the primary boot file listing .I internet-address as the server to load the data from. The boot file has the server back up the data on disk. The .I internet-address defaults to the value used with .CR \-Z . This option can be used more than once. .TP .C \-A Do not create name server data for aliases in the host table. .TP .CI \-C " file" Create resource records from strings in the comment field of the host table. Each string in the comment field (except .C [no smtp] ) is searched for in .IR file . The format of .I file is a string, a colon, and a resource record. If the string in the comment field matches the string before the colon in .IR file , a resource record is added consisting of the name of the host followed by everything after the colon from the matching line in .IR file . For example, host information (HINFO) records can be created by adding .C 360:IN HINFO hp9000s360 hp-ux to .I file and adding 360 to comments in the host table. .TP .C \-D Do not create name server data for domain names in the host table. .TP .C \-F By default, the serial number is incremented for a domain only if the data has changed (pointer (PTR) data only). This option forces the serial number to be incremented, even if the data has not changed. .TP .CI \-H " host-file" Use .I host-file instead of .CR /etc/hosts . .TP .C \-M Do not create mail exchanger (MX) records for hosts in the host table. .TP .CI \-N " mask" Apply the default subnet mask .I mask to each .I network-number specified with .C \-n except for ones with their subnet masks already provided. .I mask must be in dot notation. This is the same as supplying each .I network-number for a subnet using multiple .C \-n options. .TP .CI \-S " server" This option is the same as the .CR \-s option, but it only applies to the last .I domain specified with .CR \-d or the last .I network-number specified with .CR \-n . This option is for when .I server is backing up some, but not all, of the domains. .TP .CI \-Z " internet-address" Create a secondary boot file, .CR boot.sec , from the primary boot file listing .I internet-address as the server to load the data from. The boot file does not have the server back up the data on disk. The .I internet-address defaults to value used with .CR \-z . This option can be used more than once. .TP .C \-1 This option is obsolete. .RE .PP .CR hosts_to_named translates the host table to lower case to help eliminate duplicate data. Since the name server treats uppercase and lowercase as equivalent, names that differ only in case are considered the same. .PP Alias (CNAME) records are created for .I subdomains delegated with .CR \-c . Lines from the host table that contain names in .I subdomains from .CR \-c and .CR \-e are removed from the lowercase copy of the host table. .PP The host table is then used to create the name server data for each .I network-number declared on the command line. Do not include the trailing 0's in the network number. No distinction is made between class A, B, or C addresses nor is there any understanding of subnets unless a subnet mask is supplied. Example network numbers are: 10 (for all addresses of the form 10.\(**.\(**.\(**), 10.1 (for addresses of the form 10.1.\(**.\(**), or 10.2.2 (for addresses of the form 10.2.2.*). .PP Address (A) records are created for mapping hostnames to IP addresses. Alias (CNAME) records are created for aliases of hosts that are not multi-homed. The data are placed in a file named .C db.\c .I DOMAIN where .I DOMAIN is the first part of the domain from the command line. For the domain .CR div.inc.com , the file is named .CR db.div . All other name server data goes in this file except the pointer (PTR) records described below. .PP Pointer (PTR) records are created for mapping IP addresses to host names. PTR records are placed in a file named .C db.\c .I NET where .I NET is the network number from the command line. Network 10 data is placed in .CR db.10 . Network 10.1 data are placed in "db.10.1". .PP Mail exchanger (MX) records are created unless the .CR \-M option is used. The default MX record has a weight of 10 with the host itself as its mail exchanger. No default MX record is created for a host if .CR [no .CR smtp] is in the comment section of that line in the host table. MX records for each mail hub declared with the .CR \-m option are added for each host even if .CR [no .CR smtp] is in the comment section. .PP Well known services (WKS) records are created for each host that handles SMTP mail (does not have .CR [no .CR smtp] ) if .CR \-w is used. The only service listed is SMTP. .PP Text (TXT) records are created for comments associated with hosts in the host table if .CR \-t is used. The comments do not include .CR [no .CR smtp] . .PP For each domain, a start of authority (SOA) record is created. The SOA record requires 2 domain names: the host that the data is created on and the electronic mail address of the person responsible. The .CR \-h and .CR \-u options influence the names. In addition, the SOA record requires 5 values: a serial number, a refresh time, a retry time, an expire time, and a minimum ttl (time to live). The first time the data is created, the serial number is set to 1, the refresh time is set to 3 hours, the retry time is set to 1 hour, the expire time is set to 1 week, and the minimum ttl is set to 1 day. The .CR \-o option changes these values except for the serial number. Each subsequent time .CR hosts_to_named is run, the serial number is incremented. If any of the other fields in the SOA record are modified, the changed values are retained. .PP If there are files named .C spcl.\c .I DOMAIN or .C spcl.\c .I NET in the current directory, .CR $INCLUDE directives are added to the corresponding .C db.\c .I DOMAIN or .C db.\c .I NET file for the .CR spcl file. In this way, special data can be added to the data generated by .IR hosts_to_named . .PP The first time .CR hosts_to_named is run, it creates a default boot file for a primary name server. Each subsequent time .CR hosts_to_named is run, the boot file is updated if necessary. New entries are made in the boot file for any additional networks or domains not already in the boot file. No entries are deleted from the boot file. .PP The boot file for a caching-only server, .CR boot.cacheonly , is created if it does not exist. The boot files for secondary servers, .CR boot.sec.save and .CR boot.sec , are created if the .CR \-z or .CR \-Z options are used. The boot files for secondary servers are created new each time from the primary server boot file so that they are equivalent. .SH EXAMPLES Create name server data for networks 15.19.8 and 15.19.9 in .C div.inc.com. .IP .C "hosts_to_named \-d div.inc.com \-n 15.19.8 \-n 15.19.9" .PP Create name server data for networks 15.19.8 and 15.19.9 in .C div.inc.com. Ignore aliases in the host table and include 2 mail hubs \- .C aaa.div.inc.com and .CR bbb.mkt.inc.comk . Put all of the options in a file. .IP .C hosts_to_named \-f option_file .PP .C Option_file contains the following lines: .IP .nf .C "\-d div.inc.com" .C "\-n 15.19.8 \-n 15.19.9" .C "\-m 20:aaa" .C "\-m 30:bbb.mkt.inc.com" .C "\-A" .fi .PP Network 15.19.15 has hosts in the .CR xx.inc.com domain and the .CR div.inc.com domain. Create name server data for .CR xx.inc.com . Create only pointer (PTR) data for hosts in .CR div.inc.com on network 15.19.15 (this requires the hosts in .CR div.inc.com to have the canonical name or an alias of the form .CR x.div.inc.com ). .IP .C "hosts_to_named \-d xx.inc.com \-n 15.19.15 \-p div.inc.com" .PP Create name server data for network 15.19.8 in .CR div.inc.com . Include .C div.inc.com data from network 15.19.15 but do not create pointer (PTR) data for 15.19.15 since that is being handled by the .C xx.inc.com server. .IP .C "hosts_to_named \-d div.inc.com \-n 15.19.8 \-a 15.19.15" .SH AUTHOR .CR hosts_to_named was developed by HP. .SH FILES .PD 0 .TP 30 .CR /etc/hosts The host table .TP .CR named.boot Primary server boot file .TP .CR boot.cacheonly Caching only server boot file .TP .CR boot.sec.save Secondary server boot file .TP .CR boot.sec Secondary server boot file .TP .CR db.127.0.0 Pointer information for 127.0.0.1 .TP .CR db.cache Stub cache file for root server addresses .TP .CR db.root Data for servers for the root domain .TP .CR db.DOMAIN Address and other data for a domain .TP .CR db.DOMAIN.in\-addr Pointer data for all network-numbers .TP .CR db.NET Pointer data for a network-number .PD .SH "SEE ALSO" named(1M), RFC1034, RFC1035 .\" .\" index@\f4hosts_to_named\f1 \- translate host table to name server file format@@@\f3hosts_to_named(1M)\f1 .\" index@\f1translate host table to name server file format@@@\f3hosts_to_named(1M)\f1 .\" index@\f1host table, translate to name server file format@@@\f3hosts_to_named(1M)\f1 .\" index@\f1table, translate host-to-name-server file format@@@\f3hosts_to_named(1M)\f1 .\" index@\f1name server file format, translate host table to@@@\f3hosts_to_named(1M)\f1 .\" index@\f1file format, translate host table to name server@@@\f3hosts_to_named(1M)\f1 .\" index@\f1format, translate host table file to name server@@@\f3hosts_to_named(1M)\f1 .\" .\" toc@\f3hosts_to_named(1M)\f1:\0\0\f4hosts_to_named\f1@@@translate host table to name server file format .\" .\" fileset_database@hosts_to_na.1m INETSVCS-MAN .\" $Header: hpux.1m,v 78.1 95/12/20 10:55:02 ssa Exp $ .\" To print: tbl -TX hpux_800.1m | neqn | nroff -h -man | col -x | lp -dljn9 -onroff .TA h .TH hpux 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hpux \- HP-UX bootstrap .SH SYNOPSIS .C hpux .RC [ -F ] .RC [ -lm ] .RC [ -a [ C \(or R\c .RC \(or S \(or D ] .IR devicefile\| ] .RC [ -f\c .IR number\| ] .RC [ -i\c .IR string\| ] .RC [ \|boot\| ] .RI [ \|devicefile\| ] .br .C hpux ll .RI [ \|devicefile\| ] (same as .C hpux ls .CR -aFln ) .br .C hpux ls .RC [ -aFiln ] .RI [ \|devicefile\| ] .br .C hpux set autofile .I devicefile string .br .C hpux show autofile .RI [ \|devicefile\| ] .br .C hpux -v .br .CI "hpux restore " devicefile (Series 700 only; see DEPENDENCIES.) .SH DESCRIPTION .CR hpux is the HP-UX specific secondary system loader (SSL) utility for bootstrap (see .IR isl (1M) for the initial system loader). It supports the operations summarized below, as shown in the SYNOPSIS and detailed later in this DESCRIPTION. .RS .TP 22 .CR boot Loads an object file from an HP-UX file system or raw device and transfers control to the loaded image. (Note, the .CR boot operation is position dependent). .TP .CR ll Lists the contents of HP-UX directories in a format similar to .CR "ls -aFln" . (See .IR ls (1); .CR ls only works on a local disk with a HFS file system). .TP .CR ls Lists the contents of HP-UX directories. (See .IR ls (1); .CR ls only works on a local disk with a HFS file system). .TP .C show autofile Displays the contents of the .CR autoexecute file. .TP .C set autofile Changes the contents of the .CR autoexecute file to that specified by .IR string . .TP .C -v Displays the release and version numbers of the .CR hpux utility. .TP .C restore Recovers the system from a properly formatted bootable tape. (Series 700 specific; see DEPENDENCIES.) .RE .PP .CR hpux commands can be given interactively from the keyboard, or provided in an .I isl .CR autoexecute file. .PP .CR hpux is limited to operations on the interface initialized by .IR pdc (1M). In most cases, operations are limited to the boot device interface. .SS Notation .CR hpux accepts numbers (numeric constants) in many of its options. Numbers follow the C language notation for decimal, octal, and hexadecimal constants. A leading 0 (zero) implies octal and a leading 0x or 0X implies hexadecimal. For example, 037, 0x1F, 0X1f, and 31 all represent the same number, decimal 31. .PP .CR hpux .CR boot , .CR ll , .CR ls , .CR "set autofile" , .CR "show autofile" , and .CR restore operations accept .I devicefile specifications, which have the following format: .IP .IC manager ( w / x .\c .IC y . z ; n )\c .I filename .PP The .I devicefiles specification is comprised of a device name and a file name. The device name (\|\c .IC manager ( w / x .\c .IC y . z ; n )\c \|), consists of a generic name of an I/O system .I manager (device or interface driver) such as .CR disc , a hardware path to the device, and minor number. The .I manager name can be omitted entirely if the default is used. .IC w / x . y .\c .I z is the physical hardware path to the device, identifying bus converters, slot numbers, and hardware addresses. For Series 700 machines, there are a set of mnemonics that can be used instead of the hardware paths. The .I n is the minor number that controls .IR manager -dependent functionality. The file name part, .IR filename , is a standard HP-UX path name. Some .CR hpux operations have defaults for particular components. A .I devicefile specification containing a device part only specifies a raw device. A .I devicefile specification containing a file name implies that the device contains an HP-UX file system, and that the .I filename resides in that file system. .PP A typical boot .I devicefile specification is .IP .C disc(2/4.0.0;0)/stand/vmunix .PP The .I manager is .CR disc , the hardware path to the disk device is .CR 2/4.0.0 , the minor number shown as .CR 0 by default, and the .CR /stand/vmunix is the .I filename for the boot device. .PP .CR hpux now supports a consolidated list of managers: .CR disc , .CR tape , and .CR lan . The manager .CR disc manages all CS/80 disks connected via HP-IB (formerly .CR disc0 ); CS/80 disks connected via the HP\|27111 interface (formerly .CR disc2 ); CS/80 disks connected via NIO HP-IB (formerly .CR disc1 ); all disks connected via SCSI, (formerly .CR disc3 ), and all .I autochanger disk devices (formerly .CR disc30 ). The manager .CR lan manages remote boot through the HP\|28652A NIO based LAN interface (formerly .CR lan1 ). Remote boot is currently supported on this card only and not on any CIO-based LAN card. The manager .CR tape manages the HP\|7974, HP\|7978, and HP\|7980 tape drives via HP-IB (formerly .CR tape1 ) and tape drives via SCSI (formerly .CR tape2 ). .PP The hardware path in a .I devicefile specification is a string of numbers, each suffixed by slash, .RC ( / ), followed by a string of numbers separated by dots .RC ( . ), each number identifying a hardware component notated sequentially from the bus address to the device address. A hardware component suffixed by a slash indicates a bus converter and may not be necessary on your machine. For example, in .IC w / x . y .\c .I z .I w is the address of the bus converter, .I x is the address of the MID-BUS module, .I y is the CIO slot number, and .I z is the HP-IB address or HP\|27111 bus address. .PP The minor number, .IR n , in a .I devicefile specification controls driver-dependent functionality. (See the manual, .I "Configuring HP-UX for Peripherals," for minor-number bit assignments of specific drivers). .PP File names are standard HP-UX path names. No preceding slash .RC ( / ) is necessary and specifying one will not cause problems. .SS Defaults Default values chosen by .CR hpux to complete a command are obtained through a sequence of steps. First, any components of the command specified explicitly are used. If the command is not complete, .CR hpux attempts to construct defaults from information maintained by .CR pdc (see .IR pdc (1M)). If sufficient information to complete the command is unavailable, the .CR autoexecute file is searched. If the search fails, any remaining unresolved components of the command are satisfied by hard-coded defaults. .PP There is no hard-coded default choice for a .IR manager ; if none can be chosen, .CR hpux reports an error. .PP When the hardware path to the boot device is not specified, .CR hpux defaults to information maintained by .IR pdc . The hardware path element has no hard-coded default. .PP If the minor number element is not supplied, .CR hpux takes its default from the .CR autoexecute file. Failing that, the hard-coded default of 0 is used. .PP For the .CR boot command, a .I devicefile specification without a file name indicates that the boot device does not contain an HP-UX file system. .CR hpux interprets this as a NULL (instead of missing) file name and does not search for a default. If the entire .I devicefile specification is missing, .CR hpux searches for a default; either the .CR autoexecute file contents or the hard-coded default is chosen. .PP There are two possible hard-coded default .I devicefile specifications. One hard-coded default .I devicefile specification is .CR /vmunix . The other hard-coded default .I devicefile specification is .CR /stand/vmunix . .PP If you have a LVM system where the boot volume and the root volume are on different logical volumes, the kernel would be .CR /vmunix . This is because the boot volume will be mounted under /stand when the system is up. .PP For all other configurations, the kernel would be .CR /stand/vmunix . .PP The search order for the hard-coded defaults is .CR /stand/vmunix and then .CR /vmunix. .SS \s+1boot\s0 Operation The .CR boot operation loads an object file from an HP-UX file system or raw device as specified by the optional .IR devicefile . It then transfers control to the loaded image. .PP Any missing components in a specified .I devicefile are supplied with a default. For example, a .I devicefile of .CR vmunix.new would actually yield: .IP .C disc(8.0.0;0)vmunix.new .PP and a .I devicefile of .CR (8.0.1)/stand/vmunix , for booting from the disk at HP-IB address 1, would yield .IP .C disc(8.0.1;0)/stand/vmunix .PP Regardless of how incomplete the specified .I devicefile may be, .CR boot announces the complete .I devicefile specification used to find the object file. Along with this information, .CR boot gives the sizes of the .CR TEXT , .CR DATA , and .CR BSS , segments and the entry offset of the loaded image, before transferring control to it. .ift .br .ift .ne 10 .PP The .CR boot operation accepts several options. Note that .CR boot options .I must be specified positionally as shown in the syntax statement in the SYNOPSIS. Options for the .CR boot operations are as follows: .RS .TP 26 .CI "-a[C\(orR\(orS\(orD]" \0devicefile Accept a new location (as specified by .I devicefile) and pass it to the loaded image. If that image is an HP-UX kernel, the kernel will erase its predefined I/O configuration, and configure in the specified .IR devicefile . If the .CR C , .CR R , .CR S , or .CR D option is specified, the kernel configures the .I devicefile as the .CR console , .CR root , .CR swap , or .CR dump device, respectively. Note that .CR -a can be repeated multiple times. .TP .CI -f number Use the number and pass it as the flags word to the loaded image. .TP .CI -i string Set the initial .I run-level for .CR init (see .IR init (1M)) when booting the system. The .I run-level specified will override any .I run-level specified in an .I initdefault entry in .CR /etc/inittab (see .IR inittab (4)). .TP .C -lm Boot the system in LVM maintenance mode, configure only the root volume, and then initiate single user mode. .TP .C -F Use with SwitchOver/UX software. Ignore any locks on the boot disk. The .CR -F option should be used only when it is known that the processor holding the lock is no longer running. (If this option is not specified and a disk is locked by another processor, the kernel will not boot from it, to avoid the corruption that would result if the other processor were still using the disk). .RE .PP .CR boot places some restrictions on object files it can load. It accepts only the HP-UX magic numbers .CR EXECMAGIC (0407), .CR SHAREMAGIC (0410), and .CR DEMANDMAGIC (0413). See .IR magic (4). The object file must contain an Auxiliary Header of the .CR HPUX_AUX_ID type and it must be the first Auxiliary Header (see .IR a.out (4)). .SS \s+1ll\s0 and \s+1ls\s0 Operations The .CR ll and .CR ls operations list the contents of the HP-UX directory specified by the optional .IR devicefile . The output is similar to that of .CR "ls -aFl" command, except the date information is not printed. .PP The default .I devicefile is generated just as for .CR boot , defaulting to the current directory. .SS \s+1set autofile\s0 Operation The .CR "set autofile" operation overwrites the contents of the .CR autoexecute file, .IR autofile , with the string specified (see .CR autoexecute in the EXAMPLES section). .SS \s+1show autofile\s0 Operation The .CR "show autofile" operation displays the contents of the .CR autoexecute file, .IR autofile (see .CR autoexecute in the EXAMPLES section). .SH DIAGNOSTICS If an error is encountered, .CR hpux prints diagnostic messages to indicate the cause of the error. These messages fall into the General, Boot, Copy, Configuration, and System Call categories. System Call error messages are described in .IR errno (2). The remaining messages are listed below. .SS General .TP 5 .C "bad minor number in devicefile spec" The minor number in the .I devicefile specification is not recognized. .TP .C "bad path in devicefile spec" The hardware path in the .I devicefile specification is not recognized. .TP .C "command too complex for parsing" The command line contains too many arguments. .TP .C "no path in devicefile spec" The .I devicefile specification requires (but does not contain) a hardware path component. .TP .CI "panic (in hpuxboot): (display==" number ", flags==" number ") " string A severe internal .CR hpux error has occurred. Report to your nearest HP Field Representative. .SS Boot .TP 5 .C "bad magic" The specified object file does not have a recognizable magic number. .TP .C "bad number in flags spec" The flags specification in the .CR -f option is not recognized. .TP .C "Exec failed: Cannot find /stand/vmunix or /vmunix." Neither /stand/vmunix or /vmunix could be found. .TP .C "booting from raw character device" In booting from a raw device, the .I manager specified only has a character interface, which might cause problems if the block size is incorrect. .TP .C "isl not present, please hit system RESET button to continue" An unsuccessful .CR boot operation has overlaid .CR isl in memory. It is impossible to return control to .CR isl . .TP .C "short read" The specified object file is internally inconsistent; it is not long enough. .TP .C "would overlay" Loading the specified object file would overlay .CR hpux . .SS "Configuration" .TP 5 .CI "cannot add path, error " number An unknown error has occurred in adding the hardware path to the I/O tree. The internal error number is given. Contact your HP Field Representative. .TP .C "driver does not exist" The manager specified is not configured into .CR hpux . .TP .C "driver is not a logical device manager" The .I manager named is not that of a logical device manager and cannot be used for direct I/O operations. .TP .C error rewinding device" An error was encountered attempting to rewind a device. .TP .C "error skipping file" An error was encountered attempting to forward-space a tape device. .TP .C "negative skip count" The skip count, if specified, must be greater than or equal to zero. .TP .C "no major number" The specified .I manager has no entry in the block or character device switch tables. .TP .C "path incompatible with another path" Multiple incompatible hardware paths have been specified. .TP .C "path long" The hardware path specified contains too many components for the specified .IR manager . .TP .C "path short" The hardware path specified contains too few components for the specified .IR manager . .TP .C "table full" Too many devices have been specified to .CR hpux . .ift .br .ift .ne 15 .SH EXAMPLES As a preface to the examples which follow, here is a brief overview of HP-UX system boot-up sequences. .SS Automatic Boot Automatic boot processes on various HP-UX systems follow similar general sequences. When power is applied to the HP-UX system processor, or the system .B Reset button is pressed, processor-dependent code (firmware) is executed to verify hardware and general system integrity (see .IR pdc (1M)). After checking the hardware, .CR pdc gives the user the option to override the .CR autoboot sequence by pressing the .B Esc key. At that point, a message resembling the following usually appears on the console. .nf .IP .C "(c) Copyright. Hewlett-Packard Company. 1994." .C "All rights reserved." .IP .C "PDC ROM rev. 130.0" .C "32 MB of memory configured and tested." .IP .C "Selecting a system to boot." .C "To stop selection process, press and hold the ESCAPE key..." .fi .PP If no keyboard activity is detected, .CR pdc commences the .CR autoboot sequence by loading .CR isl (see .IR isl (1M)) and transferring control to it. Since an .CR autoboot sequence is occurring, .CR isl finds and executes the .CR autoexecute file which, on an HP-UX system, requests that .CR hpux be run with appropriate arguments. Messages similar to the following are displayed by .CR isl on the console: .nf .IP .C "Booting from: scsi.6 HP 2213A" .C "Hard booted." .C "ISL Revision A.00.09 March 27, 1990" .C "ISL booting hpux boot disk(;0)/stand/vmunix" .fi .PP .CR hpux , the secondary system loader, then announces the operation it is performing, in this case .CR boot , the .I devicefile from which the load image comes, and the .CR TEXT size, .CR DATA size, .CR BSS size, and start address of the load image, as shown below, before control is passed to the image. .nf .IP .C "Booting disk(scsi.6;0)/stand/vmunix" .C "966616+397312+409688 start 0x6c50" .fi .PP The loaded image then displays numerous configuration and status messages. .SS Interactive Boot To use .CR hpux interactively, .CR isl must be brought up in interactive mode by pressing the .B Esc key during the interval allowed by .CR pdc . .CR pdc then searches for and displays all bootable devices and presents a set of boot options. If the appropriate option is chosen, .CR pdc loads .CR isl and .CR isl interactively prompts for commands. Information similar to the following is displayed: .nf .IP .C "Selection process stopped." .IP .C "Searching for Potential Boot Devices." .C "To terminate search, press and hold the ESCAPE key." .IP .C "Device Selection Device Path Device Type" .C "-------------------------------------------------------------" .C "P0 scsi.6.0 QUANTUM PD210S" .C "P1 scsi.1.0 HP 2213A" .C "p2 lan.ffffff-ffffff.f.f hpfoobar" .C "" .IP .C "b) Boot from specified device" .C "s) Search for bootable devices" .C "a) Enter Boot Administration mode" .C "x) Exit and continue boot sequence" .IP .C "Select from menu: b p0 isl" .IP .C "Trying scsi.6.0" .C "Boot path initialized." .C "Attempting to load IPL." .IP .C "Hard booted." .C "ISL Revision A.00.2G Mar 27, 1994" .C ISL> .fi .PP Although all of the operations and options of .CR hpux can be used from .CR isl interactively, they can also be executed from an .CR autoexecute file. In the examples below, user input is the remainder of the line after each .CR ISL> prompt shown. The remainder of each example is text displayed by the system. Before going over specific examples of the various options and operations of .CR hpux , here is an outline of the steps taken in the automatic boot process. Although the hardware configuration and boot paths shown are for a single Series 800 machine, the user interfaces are consistent across all models. When the system .B Reset button is depressed, .CR pdc executes self-test, and assuming the hardware tests pass, .CR pdc announces itself, sends a BELL character to the controlling terminal, and gives the user 10 seconds to override the .CR autoboot sequence by entering any character. Text resembling the following is displayed on the console: .nf .IP .C "Processor Dependent Code (PDC) revision 1.2" .C "Duplex Console IO Dependent Code (IODC) revision 3" .IP .C "Console path = 56.0.0.0.0.0.0 (dec)" .C " 38.0.0.0.0.0.0 (hex)" .IP .C "Primary boot path = 44.3.0.0.0.0.0 (dec)" .C " 2c.00000003.0.0.0.0.0 (hex)" .IP .C "Alternate boot path = 52.0.0.0.0.0.0 (dec)" .C " 34.0.0.0.0.0.0 (hex)" .IP .C "32 MB of memory configured and tested." .IP .C "Autosearch for boot path enabled" .IP .C "To override, press any key within 10 seconds." .fi .PP If no keyboard character is pressed within 10 seconds, .CR pdc commences the .CR autoboot sequence by loading .CR isl and transferring control to it. Because an .CR autoboot sequence is occurring, .CR isl merely announces itself, finds and executes the .CR autoexecute file which, on an HP-UX system, requests that .CR hpux be run with appropriate arguments. The following is displayed on the console. .nf .IP .C "10 seconds expired." .C "Proceeding with autoboot." .IP .C "Trying Primary Boot Path" .C "------------------------" .C "Booting..." .C "Boot IO Dependent Code (IODC) revision 2" .IP .C "HARD Booted." .IP .C "ISL Revision A.00.2G Mar 20, 1994" .IP .C "ISL booting hpux" .fi .PP .CR hpux then announces the operation it is performing, in this case .CR boot , the .I devicefile from which the load image comes, and the .CR TEXT size, .CR DATA size, .CR BSS size, and start address of the load image. The following is displayed before control is passed to the image. .nf .IP .C "Boot" .C ": disc3(44.3.0;0)/stand/vmunix" .C "3288076 + 323584 + 405312 start 0x11f3e8" .fi .PP Finally, the loaded image displays numerous configuration and status messages, then proceeds to .CR init .I run-level 2 for multiuser mode of operation. .ift .br .ift .ne 20 .PP .CR isl must be brought up in interactive mode to use the operations and options of .CR hpux . To do this, simply enter a character during the 10 second interval allowed by .CR pdc . .CR pdc then asks if the primary boot path is acceptable. Answering yes .RC ( Y ) is usually appropriate. .CR pdc then loads .CR isl and .CR isl interactively prompts for commands. The following lines show the boot prompt, the .CR Y response, subsequent boot messages, and finally the Initial System Loader (ISL) prompt that are sent to the display terminal: .nf .IP .C "Boot from primary boot path (Y or N)?> y" .C "Interact with IPL (Y or N)?> y" .IP .C "Booting..." .C "Boot IO Dependent Code (IODC) revision 2" .IP .C "HARD Booted." .IP .C "ISL Revision A.00.2G Mar 20, 1994" .IP .C "ISL>" .fi .PP Although all of the operations and options of .CR hpux can be used from .CR isl interactively, they can also be executed from an .CR autoexecute file. In the examples below, all user input follows the .CR ISL> prompt on the same line. Subsequent text is resultant messages from the ISL. .SS Default Boot Entering .CR hpux initiates the default boot sequence. The boot path read from .CR pdc is .CR 8.0.0 , the manager associated with the device at that path is .CR disc , the minor number, in this case derived from the .CR autoexecute file, is .CR 4 specifying section 4 of the disk, and the object file name is .CR /stand/vmunix . .nf .IP .C "ISL> hpux" .IP .C "Boot" .C ": disc3(44.3.0;0)/stand/vmunix" .C "3288076 + 323584 + 405312 start 0x11f3e8" .fi .SS Booting Another Kernel In this example, .CR hpux initiates a .CR boot operation where the name of the object file is .CR vmunix.new . .nf .IP .C "ISL> hpux vmunix.new" .IP .C "Boot .C ": disc3(44.3.0;0)/stand/vmunix.new" .C "3288076 + 323584 + 405312 start 0x11f3e8" .fi .SS Booting From Another Section In this example (shown for backward compatibility), a kernel is booted from another section of the root disk. For example, suppose kernel development takes place under .CR /mnt/azure/root.port which happens to reside in its own section, section 3 of the root disk. By specifying a minor number of .CR 3 in the above example, the object file .CR sys.azure/S800/vmunix is loaded from .CR /mnt/azure/root.port . .nf .IP .C "ISL> hpux (;3)sys.azure/S800/vmunix" .IP .C "Boot" .C ": disc(8.0.0;0x3)sys.azure/S800/vmunix" .C "966616+397312+409688 start 0x6c50" .fi .SS "Booting From Another Disk" Only the hardware path and file name are specified in this example. All other values are boot defaults. The object file comes from the file system on another disk. .nf .IP .C "ISL> hpux (52.5.0.0)/stand/vmunix" .IP .C "Boot" .C ": disc(52.5.0.0)/stand/vmunix" .C "966616+397312+409688 start 0x6c50" .fi .SS "Booting From LAN" This example shows how to boot a cluster client from the LAN. Though this example specifies a .IR devicefile , you can also use default boot, as shown in a previous example. For a boot operation other than default boot, the file name must be specified and can be no longer than 11 characters. Booting to .CR isl from a local disk then requesting an image to be loaded from the LAN is .I not supported. .nf .IP .C "ISL> hpux lan(32)/stand/vmunix" .IP .C "Boot" .C ": lan(32;0x0)/stand/vmunix" .C "966616+397312+409688 start 0x6c50" .fi .SS "Booting To Single User Mode" In this example, the .CR -i option is used to make the system come up in .I run-level .CR s , for single user mode of operation. .nf .IP .C "ISL> hpux -is" .IP .C Boot .C ": disc(8.0.0;0x0)/stand/vmunix" .C "966616+397312+409688 start 0x6c50" .IP .I "\h'.3i'Kernel Startup Messages Omitted" .IP .C "INIT: Overriding default level with level 's'" .IP .C "INIT: SINGLE USER MODE" .C "WARNING: YOU ARE SUPERUSER !!" .C # .fi .SS "Booting With A Modified I/O Configuration" Here, a tape driver is configured in at CIO slot 2, HP-IB address 0. Regardless of what was present in the kernel's original I/O configuration, the driver .CR tape is now configured at that hardware path. Similarly, .CR mux0 is configured in at CIO slot 1 which is to be the console. The only other devices configured are the console and root device, which .CR boot derived from .CR pdc . .nf .IP .C "ISL> hpux -aC mux0(8.1) -a tape(8.2.0)" .IP .C Boot .C ": disc(8.0.0;0x0)/stand/vmunix" .C ": Adding mux0(8.1;0x0)..." .C ": Adding tape(8.2.0;0x0)..." .C "966616+397312+409688 start 0x6c50" .C "Beginning I/O System Configuration." .C "cio_ca0 address = 8" .C " hpib0 address = 0" .C " disc0 lu = 0 address = 0" .C " mux0 lu = 0 address = 1" .C " hpib0 address = 2" .C " tape1 lu = 0 address = 0" .C "I/O System Configuration complete." .IP .I "\h'.3i'Additional Kernel Startup Messages Omitted" .fi .SS "Booting From A Raw Device" This example shows booting from a raw device (that is, a device containing no file system). Note that no file name is specified in the .IR devicefile . The device is an HP\|7974 tape drive, and therefore .CR tape is the .I manager used. The tape drive is at CIO slot 2, HP-IB address 3. The first file on the tape will be skipped. The minor number specifies a tape density of 1600 BPI with no rewind on close. Depending on the minor number, .CR tape requires the tape be written with 512 or 1024 byte blocks. .nf .IP .C "ISL> hpux tape(8.2.3;0xa0000)" .IP .C "Boot" .C ": tape(8.2.3;0xa0000)" .C "966616+397312+409688 start 0x6c50" .fi .\" DHB .SS "Booting From Cartridge Tape" .\" DHB The default boot device in this example is an .\" DHB HP\|7914 disk with a cartridge tape at unit 1. .\" DHB The minor number has the cartridge tape flag set .\" DHB and specifies unit 1, section 0 of the device. .\" DHB Although the minor number was entered in decimal format, .\" DHB the hexadecimal form would be accepted. .\" DHB Since a file name is specified, .\" DHB it is assumed that section 0 contains a file system. .\" DHB .nf .\" DHB .IP .\" DHB .C "ISL> hpux (;4194336)/stand/vmunix" .\" DHB .IP .\" DHB .C "Boot" .\" DHB .C ": disc(8.0.0;0x400020)/stand/vmunix" .\" DHB .C "966616+397312+409688 start 0x6c50" .\" DHB .fi .SS "Displaying The Autoexecute File" In this example, .CR "show autofile" is used to print the contents of the .CR autoexecute file residing in the boot LIF, on the device from which .CR hpux was booted. Optionally, a .I devicefile can be specified in order to read the .CR autoexecute file from the boot LIF of another boot device. .nf .IP .C "ISL> hpux show autofile" .C "Show autofile" .C ": AUTO file contains (hpux)" .fi .SS "Changing The Autoexecute File" This example shows how to change the contents of the .CR autoexecute file. Once done, the system can be reset, and the new command will be used during any unattended boot. .nf .IP .C "ISL> hpux set autofile ""hpux /stand/vmunix.std""" .C "Set autofile" .C ": disk(2/0/1.3.0.0.0.0.0;0)" .C ": AUTO file now contains ""(hpux /stand/vmunix.std)""" .fi .SS "Listing Directory Contents" The contents of the directory .RC ( /stand ) on the root disk are listed. The format shows the file protections, number of links, user id, group id, and size in bytes for each file in the directory. There are three available kernels to boot: .CR vmunix , .CR vmunix.test , and .CR vmunix.prev . Listing the files over the LAN is not supported. .nf .IP .C "ISL> hpux ll /stand" .C "Ls" .C ": disk(2/0/1.3.0.0.0.0.0;0)/stand" .C "dr-xr-xr-x 3 2 2 1024 ./" .C "drwxr-xr-x 17 0 0 1024 ../" .C "-rw-r--r-- 1 0 3 191 bootconf" .C "drwxr-xr-x 2 0 0 1024 build/" .C "-rw-r--r-- 1 0 0 632 ioconfig" .C "-rw-r--r-- 1 0 3 82 kernrel" .C "-r--r--r-- 1 0 3 426 system" .C "-rw-r--r-- 1 0 3 437 system.prev" .C "-rwxr-xr-x 1 0 3 7771408 vmunix*" .C "-rwxr-xr-x 1 0 3 7771408 vmunix.prev* .fi .ift .br .ift .ne 9 .SS "Getting The Version" The .CR -v option is used to get the version numbers of .CR hpux . .nf .IP .C "ISL> hpux -v" .IP .C "Release: 10.00" .C "Release Version:" .C "@(#) X10.20.B HP-UX() #1: Dec 4 1995 16:55:08" .fi .SH DEPENDENCIES .SS Series 700 Only The .CR restore operation is provided as a recovery mechanism in the event that a disk becomes totally corrupted. It copies data from a properly formatted bootable tape to disk. When this tape contains a backup image of the disk, the entire disk is restored. To create a properly formatted tape (DDS ONLY), the following commands should be executed: .IP .C "dd if=/usr/lib/uxbootlf of=/dev/rmt/0mn bs=2k" .br .C "dd if=/dev/rdsk/1ss of=/dev/rmt/0m bs=64k" .PP The first .CR dd puts a boot area on the tape, making it a bootable image (see .IR dd (1)). Once the boot image is on tape, the tape is .I not rewound. The next .CR dd appends an image of the disk to the tape. The entire process takes about one hour for a 660 MB HP\|2213 disk. To avoid later problems with .CR fsck after the disk is restored, bring the system to single user mode and type .CR sync a few times before doing the second .CR dd (see .IR fsck (1M)). Once created, the tape can be used to completely restore the disk: .RS .TP 3 1. Insert the tape into the tape drive. .TP 2. Instruct the machine to boot to ISL from the tape. This is usually done by specifying .CR scsi.3 as the boot path. .TP 3. Enter the following in response to the ISL prompt: .RS .IP .C "ISL> hpux restore disk(scsi.1;0)" .RE .RE .PP This restores the disk image from the tape to the actual disk at .CR scsi.1 . .BR "Any existing data on the disk will be lost" . This command destroys the contents of the device specified by .IR devicefile. The restoration process takes about one hour for a 660 MB drive. .PP .B NOTE: There is a 2 GB limit on the amount of data that can be restored. The tape and disk must be on the boot device interface. .PP Also, this command may be replaced in the future by superior installation and recovery mechanisms. At that time, this command will be removed. .SH SEE ALSO boot(1M), fsck(1M), init(1M), isl(1M), pdc(1M), errno(2), a.out(4), inittab(4), magic(4). .\" .\" index@\f4hpux\f1 \- HP-UX bootstrap and installation utility@@@\f3hpux(1M)\f1 .\" index@\f1HP-UX bootstrap and installation utility@@@\f3hpux(1M)\f1 .\" index@\f1bootstrap and installation utility, HP-UX@@@\f3hpux(1M)\f1 .\" index@\f1installation and bootstrap utility, HP-UX@@@\f3hpux(1M)\f1 .\" .\" toc@\f3hpux(1M)\f1:\0\0\f4hpux\f1@@@HP-UX bootstrap and installation utility\f1 .\" $Header: i4admin.1m,v 78.1 96/02/12 13:50:19 ssa Exp $ .TA i .TH i4admin 1M "" "iFOR/LS Version 3" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME i4admin \- administer iFOR/LS licensing .SH SYNOPSIS .HP \f3\f4i4admin \f1[\f3\f4-\f2Standard-X-Arguments\f1] .HP \f3\f4i4admin \-a \f1[\f3\f4\-n \f2server-name\f1] \f1[\f3\f4\-f \f2filename\f1] .if n .br \f1[\f3\f4\-v "'\f2vendor-name\f3\f4' \f1[\f3\f4vendor-id vendor-password\f1]\f3\f4" .if n .br .if t .br \f3\f4\-p "'\f2product-name\f3\f4' '\f2product_version\f3\f4' \f2license_password .if n .br \f1[\f3\f4'\f2license_annotation\f3\f4'\f1]\f3\f4"\f1] .HP \f3\f4i4admin \-d \f1[\f3\f4\-n \f2server-name\f1] \f3\f4\-v \f2vendor-name\f1 \f3\f4\-p \f2product-name\f1 .if n .br \f3\f4\-t \f2timestamp\f1 .HP \f3\f4i4admin \-l s\f1|\f3\f4v\f1|\f3\f4p \f1[\f3\f4-i\f1] \f1[\f3\f4\-n "\f2server-name\f1...\f3\f4"\f1] .if n .br \f1[\f3\f4\-v "'\f2vendor-name\f3\f4'\f1...\f3\f4"\f1] \f1[\f3\f4\-p "'\f2product-name\f3\f4'\f1...\f3\f4"\f1] .if n .br .if t .br \f1[\f3\f4\-u "\f2user-name\f1...\f3\f4"\f1] .HP \f3\f4i4admin \-s \f1[\f3\f4\-n "\f2server-name\f1...\f3\f4"\f1] .if n .br \f1[\f3\f4\-v "'\f2vendor-name\f3\f4'\f1...\f3\f4"\f1] \f1[\f3\f4\-p "'\f2product-name\f3\f4'\f1...\f3\f4"\f1] .if n .br \f1[\f3\f4\-u "\f2user-name\f1...\f3\f4"\f1] .HP \f3\f4i4admin \-r 1\f1|\f3\f42\f1|\f3\f43\f1|\f3\f44\f1|\f3\f45 \f1[\f3\f4\-e 1\f1|\f3\f4234567\f1] .if n .br \f1[\f3\f4\-b \f2start-date\f1] \f1[\f3\f4\-g \f2end-date\f1] .if n .br \f1[\f3\f4\-n "\f2server-name\f1...\f3\f4"\f1] .if t .br \f1[\f3\f4\-v "'\f2vendor-name\f3\f4'\f1...\f3\f4"\f1] .if n .br \f1[\f3\f4\-p "'\f2product-name\f3\f4'\f1...\f3\f4"\f1] \f1[\f3\f4\-u "\f2user-name\f1...\f3\f4"\f1] .HP \f3\f4i4admin \-x \f2before-date \f3\f4\-n "\f2server-name\f1...\f3\f4P" .HP \f3\f4i4admin \-h\f1 .SH DESCRIPTION The iFOR/LS Administration tool, \f3\f4i4admin\f1, completely manages the iFOR/LS licensing system. The tool can perform the following tasks: .TP \(bu Perform basic license administration (e.g., adding and deleting licenses). .TP \(bu Construct a single logical view of the license system from which current summary license usage and current detailed license usage reports can be generated. .TP \(bu Generate detailed license event and license usage reports from logged server data. .PP The \f3\f4i4admin\f1 tool has a Graphical User Interface (GUI) and a Command Line Interface (CLI). If \f3\f4i4admin\f1 is invoked with non-X arguments, the CLI version is started, otherwise the GUI version is started. .SS CLI Actions The CLI is invoked with one of the following actions, and one or more action modifiers. .TP \f3\f4\-a Add a product license to a specified license server. There are two ways to add a license to a license server. .IP If the license information has been provided in the form of a license certificate (a flat file describing the license), the license certificate can be added by specifying the .I server-name and the license certificate .I filename. If the server name is omitted, the license is added to the license server running on the local machine. .IP If the license information has not been provided in a license certificate, the parameters must be entered individually. All three vendor parameters are not always required. If the vendor for the product is already installed on the server, only the .I vendor-name must be specified, otherwise the .I "vendor-name, vendor-id and .I vendor-password must be specified. .TP \f3\f4\-d\f1 Delete a product license. To delete a compound password, or a use-once license, the license must have expired. If the server name is omitted, the license is deleted from the license server running on the local machine. The license .I timestamp must be specified to differentiate between licenses for the same product (same Vendor ID, Product ID, and Product version), which are installed on the same server. The license .I timestamp can be found using the list product details command: .RS .IP \f3\f4i4admin \-lp \-i \-p \f2product-name\f1 .RE .TP \f3\f4\-l\f1 List installed license information. The command is qualified by the list type flag, \f3\f4s\f1|\f3\f4v\f1|\f3\f4p\f1, to list servers, vendors, or products respectively. .IP The vendor list can be limited to specific servers by entering one or more .I server-names. If more than one \f2server-name\fP is entered, the list must be enclosed in double quotes. .IP By default the product list contains a summary of product information. Detailed product information can be queried by specifying the \f3\f4\-i\f1 parameter. The product list can be filtered by server, vendor, and user. If more than one .I vendor-name is entered, the list of .I vendor-names must be enclosed in double quotes. Any .I vendor-name which contains white space must also be enclosed in single quotes. .IP Specify one or more .I user-names to limit the product list to products currently in use by the those users. .TP \f3\f4\-s\f1 Generate a status report containing detailed current license usage. For each product, the report includes the number of licenses in use, the user of the product and when license was acquired. By default the status report is generated based on all active license servers in the cell. The scope of the report can be limited by specifying .I server-names, vendor-names, product-names, or .I user-names. .TP \f3\f4\-r\f1 Generates reports which are based on license events logged by the license server. The command will generate one of five reports specified by the report-type flag (\f3\f41\f1|\f3\f42\f1|\f3\f43\f1|\f3\f44\f1|\f3\f45\f1). .RS .TP \f3\f41\f1 Reports server log events. This command is further qualified by the event-flag which is described below. .TP \f3\f42\f1 For each product lists the number of requests for licenses, the number of licenses granted, and the percent of rejected requests. .TP \f3\f43\f1 Lists the same information as \f3\f42\f1 but breaks out a separate entry for each user. .TP \f3\f44\f1 For each product, lists the maximum concurrent nodes, maximum concurrent users, and average time in use. .TP \f3\f45\f1 For each product, lists the number of times each user invoked the product and the average time the product was in use. .RE .TP \f3\f4\-x\f2\0before-date Delete all log entries on the servers specified by .I server-names which are timestamped on or before .I before-date .TP \f3\f4\-h\f1 Display a synopsis of command-line options .SS CLI Action Modifiers .TP \f3\f4\-b\f2\0start-date\f1 Specify the start date for generating log reports. By default the start date is Jan. 1 1970. .TP \f3\f4\-e\f2\0event-type\f1 Specify an event filter for the standard event report (\f3\f4\-r1\f1). By default all events are listed. .RS .TP \f3\f41\f1 All events (default) .TP \f3\f42\f1 License related events (license request, license release, etc.) .TP \f3\f43\f1 Vendor messages .TP \f3\f44\f1 License database modifications (license added, license deleted, etc.) .TP \f3\f45\f1 Error events (license request failed, vendor not found, etc.) .TP \f3\f46\f1 Server start/stop .TP \f3\f47\f1 Fatal error events (server out of memory, server file IO error, etc). .PP Error events 2-7 can be combined, e.g., \f3\f4-e357\f1 to list vendor messages, error events, and fatal error events. .RE .TP \f3\f4\-f\f2\0filename\f1 Specifies filename for adding a license certificate. .TP \f3\f4\-g\f2\0end-date\f1 Specify the end date for generating log reports. By default the end date is current day. .TP \f3\f4\-i\f1 Include license details (start date, end-date, multi-use rules, timestamp, etc.) when listing products. .TP \f3\f4\-p "'\f2product-name\f3\f4' '\f2product_version\f3\f4' \f2license_password\f1 [\f3\f4'\f2license_annotation\f3\f4'\f1]\f3\f4"\f1 .br Specify a product when adding a license (\f3\f4\-a\f1) which is not defined in a license certificate. The entire argument must be enclosed in double quotes. If the \f2product-name\f1, \f2product-version\f1, or \f2license-annotation\f1 contains white space the argument must be enclosed in single quotes. .TP \f3\f4\-p "'\f2product-name\f3\f4'\f1...\f3\f4"\f1 Specify a product, or products to limit the scope of a product listing (\f3\f4-lp\f1), a status report (\f3\f4-s\f1), or a event report (\f3\f4-r\f1). If multiple \f2product-name\f1s are specified, the entire argument must be enclosed in double quotes. If any \f2product-name\f1 contains white space it must be enclosed in single quotes to differentiate the argument from multiple single-word product names. .TP \f3\f4\-s "\f2server-name\f1...\f3\f4"\f1 Specify a server when performing administrative actions (adding a license, deleting a license, cleaning the log file), or limit the scope of a listing, status report or event report to a particular server, or servers. If more than one \f2server-name\f1 is specified to limit the scope of a listing or report, the entire argument must be enclosed in double quotes. .TP \f3\f4\-u \f3\f4"\f2user-name\f1...\f3\f4"\f1 Limit the scope of a status report, or event report to a specific user, or users. If more than one user is specified, the entire argument must be enclosed in double quotes. .TP \f3\f4\-v "'\f2vendor-name\f3\f4'\f1 [\f2vendor-id vendor-password\f1]\f3\f4"\f1 Specify a vendor when adding a product license manually. If another product for this vendor has been installed on an active license server in this cell, only the \f2vendor-name\f1 must be specified. If a product for this vendor has not been previously installed on an active server in this cell, the \f2vendor-id\f1 and the \f2vendor-password\f1 must also be specified. .SS GUI Description .PP The \f3\f4i4admin\f1 GUI provides an intuitive dialog based interface to manage all aspects of the iFOR/LS licensing system. The main window is divided into four functional areas: .TP \(bu The menu bar contains pulldown menus which provide the interface to all administrative commands. .TP \(bu The toolbar provides direct access to frequently used commands. .TP \(bu All reports are displayed in the scrolling display area. .TP \(bu When performing a task, the tool displays its progress in the status line at the bottom of the main window. .PP The GUI tool can perform the following tasks which will be described in detail in succeeding sections. .TP \(bu Basic license administration which includes adding and deleting licenses. .TP \(bu Extensive report generation based on current license usage and logged license events. .SS GUI Administrative Tasks .PP The Administrative tasks are adding licenses, deleting licenses, and cleaning up stale licenses. There are two ways to add a license. If the license information has been provided in the form of a license certificate (a flat file describing the license), follow the first procedure. If the license information has been provided in any other form, follow the second procedure. .PP \f3Adding a license from a license certificate\f1 .TP 1. Open the \f3Add\f1 pulldown menu and select the \f3License...\&\f1 menu item. .TP 2. Select the server to add the license to from the \f3Server\f1 drop-down listbox. .TP 3. Select the \f3Read certificate...\&\f1 button. .TP 4. Enter the name of the license certificate in the \f3Selection\f1 entry field. The \f3Filter\f1 entry field and the \f3Filter\f1 button can be used to limit the selection to a specific file or range of files. .TP 5. Select \f3OK\f1 to accept the file selection and close the dialog. Verify that the Vendor name, Product name, and Product version appear correctly on the \f3Add License\f1 panel. .TP 6. Select \f3OK\f1 to add the license to the selected server and close the \f3Add license\f1 dialog. .PP \f3Adding a license manually\f1 .TP 1. Open the \f3Add\f1 pulldown menu and select the \f3License...\&\f1 menu item. .TP 2. Select the server to add the license to from the \f3Server\f1 drop-down listbox. .TP 3. Select the \f3Enter manually...\&\f1 button. .TP 4. Select the product's vendor from the drop down list of vendors which are displayed. If the product's vendor is not displayed, select the \f3New vendor\f1 button to specify the vendor information. .TP 5. Enter the Product name, Product version, License password, and optional License annotation (if provided) in the fields. .TP 6. Select \f3OK\f1 to accept the information and close the dialog. Verify that the Vendor name, Product name, and Product version appear correctly on the \f3Add license\f1 dialog. .PP \f3Deleting a license\f1 .TP 1. Change to the \f3Product details\f1 view. To change views select the desired view from the \f3View\f1 pulldown menu. .TP 2. Select a license to delete. Note that selected items which can be acted on are distinguished from plain text by the highlight color of the selection. .TP 3. Select \f3Delete license\f1 button from the \f3Selected\f1 pulldown menu. The tool will ask for confirmation before deleting the license. Note that compound passwords, and use-once licenses cannot be deleted before their expiration date. .PP \f3Cleaning up stale licenses\f1 .PP When a client application acquires a license from the license server, it also periodically checks back with the server to tell the server the application is still running. The interval between checks is referred to as the check-in period. The server does not automatically release licenses for applications which have missed their check-in period. However, if a client application attempts to acquire a license and none are available, the server will check all the outstanding licenses to make sure the respective clients have checked in. If a client has missed its check-in period, that client's license will be granted. The clean stale license command forces the server to iterate through the outstanding licenses, releasing the licenses which have not been checked. .PP To clean up stale licenses for a product or products: .TP 1. Select one or more products from the \f3Product summary\f1 view or the \f3Product status\f1 view. Multiple entries can be selected by holding the Shift or Control key down while selecting. .TP 2. Open the \f3Selected\f1 menu and choose the \f3Clean stale licenses\f1 menu item. .SS GUI Usage and Installed License Reporting .PP This set of reports are generated based on installed license details, and current usage information. The reports are generated based on a snapshot of the license system at a particular instant in time. Since the license system may be constantly changing, the information contained in these reports is only as current as the last snapshot. .PP These reports contain information which is summed across the license system. The \f3\f4i4admin\f1 tool constructs a single logical view of the license system from which these reports are generated. This logical view is referred to as a snapshot of the license system. There are three reports based on the snapshot. The reports are accessed via the \f3View\f1 pulldown menu. .TP \(bu The product summary is a terse view of a product's installed licenses and current license usage. From this view the administrator can quickly identify problem areas, i.e., a product has 10 licenses installed, and 10 are in use. .TP \(bu The product details view reports detailed installed product information, including the number of license installed, the start and expiration date of the licenses, and the server that the license is installed on. From this view, the administrator can select delete a license. .TP \(bu The product status view generates a detailed current usage report which includes; the number of licenses installed, the number of licenses currently checked out, who is using the license from what node, and how long the user has had the license. .PP By default these reports are based on all the installed products and licenses on all the servers contained in the current snapshot. The scope of any of these reports can be limited by applying one or more View Filters. The View filter allows the report to be scoped by server, vendor, product, or user. To change the View filter: .TP 1. Select \f3Filter...\&\f1 from the \f3View\f1 pulldown menu. .TP 2. From the \f3View filter\f1 dialog select the type of filter to apply. .TP 3. Select \f3OK\f1 to close the individual filter selection dialog. Select \f3OK\f1 to close the \f3View filter\f1 dialog. The view will be immediately updated based on the new view when the \f3View filter\f1 dialog is closed. .PP It is important to remember that these reports are only as current as the last snapshot. The snapshot can be updated manually or automatically. .PP To update the snapshot manually, select \f3Refresh now\f1 from the \f3Snapshot\f1 pulldown menu. The snapshot will be immediately updated, .PP To update the snapshot automatically, open the \f3Automatic refresh\f1 dialog from the \f3Snapshot\f1 pulldown menu. Select the \f3Automatic refresh\f1 radio button, and enter a refresh interval in minutes. .SS GUI License Event Reporting .PP These reports are generated by querying information directly from a server or servers. Since the amount of logged event information may be extensive it is impractical to create a local snapshot of all the log information to generate reports from. .PP The reports can be filtered using the same View Filter as previously discussed. A log report can be scoped by server, vendor, product, or user. By default, the View filter dialogs allow the administrator to select from the servers, vendors, products, and users which are contained in the current snapshot. If the desired filter item is not contained in the current snapshot, the administrator can manually specify the name in an entry field on the filter dialog. .PP There are five log reports which are summarized below. .TP \(bu License event log reports which reports logged server events without deriving additional information. There are seven categories of events which can be included in this reports. .RS .TP 1. All events .TP 2. (default) License related events (license request, license release, etc.) .TP 3. Vendor messages .TP 4. License database modifications. .TP 5. Error events (license request failed, vendor not found, etc.) .TP 6. Server start/stop .TP 7. Fatal error events (server out of memory, server file IO error, etc.) .PP Note that error events 2-7 can be combined. .RE .TP \(bu License requests by product. For each product lists the number of requests for licenses, the number of licenses granted, and the percent of rejected requests. .TP \(bu License requests by user. Lists the same information and the previous reports, but breaks out a separate entry for each user. .TP \(bu License use by product. For each product lists the maximum concurrent nodes, maximum concurrent users, and average time in use. .TP \(bu License use by user. For each product, lists the number of times each user invoked the product and the average time the product was in use. .SH AUTHOR \f3i4admin\f1 was developed by HP and Gradient Technologies, Inc. .SH FILES .TP 35 \f3\f4opt/ifor/ls/conf/i4rpt.fmt\f1 Report templates .TP \f3\f4opt/ifor/ls/res/*.bmp\f1 Icon bitmaps .TP \f3\f4opt/ifor/ls/res/i4admin.pdl\f1 Panel definitions .SH SEE ALSO i4ally(1M), i4lbfind(1M), i4lmd(1M), i4start(1M), i4stop(1M), i4target(1M), i4tv(1M). .\" toc@\f3i4admin(1M)\f1:\0\0\f4i4admin\f1@@@administer iFOR/LS licensing .\" index@\f4i4admin\f1 \- administer iFOR/LS licensing@@@\f3i4admin(1M)\f1: .\" index@\f1administer iFOR/LS licensing@@@\f3i4admin(1M)\f1: .\" index@\f1iFOR/LS licensing@@@\f3i4admin(1M)\f1: .\" index@\f1licensing, iFOR/LS@@@\f3i4admin(1M)\f1: .\" $Header: i4ally.1m,v 76.1 95/08/23 17:18:26 ssa Exp $ .TA i .TH i4ally 1M "" "iFOR/LS Version 3" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME i4ally \- Communicate with iFOR/LS on behalf of iFOR/LS 16-bit Windows clients. .SH SYNOPSIS \f3i4ally\f1 [ \f3-v\f1 ] .SH DESCRIPTION The \f3i4ally\f1 is a process that enables iFOR/LS 16-bit Windows client applications to use iFOR/LS server-based licenses. The ally is not required for iFOR/LS 16-bit Windows client applications that are using nodelocked licenses only. .PP This process can reside on any iFOR/LS V3 system (other than 16-bit Windows) or on an iFOR/LS for OS/2 system. It is suggested that it reside on a license server system (instead of a license client system), but this is not required. .PP The ally currently supports one address family, IP. The ally listens on a port defined in the iFOR/LS configuration file (\f4i4ls.ini\f1) on the system running the ally. In the \f4i4ls.ini\f1 file, this port definition can be found in the \f4[iFOR/LS NCS-Server]\f1 section as the \f2allyport\f1 entry. The \f4i4ls.ini\f1 file is usually found in the \f4/opt/ifor/ls/conf\f1 directory. .SH OPTIONS .TP \f3-v\f1 Verbose mode. This causes the iFOR/LS ally to display debugging information to stdout. This information could be useful if a call to Gradient support is required. .SH ERRORS .TP iFOR/LS Ally encountered error searching for network transports. The ally that is used for 16-bit Windows clients was not able to find a valid network transport. Check the configuration of the networking software on the ally machine. .TP iFOR/LS Ally encountered error finding the ally machine. The ally was not able to determine it's own machine name. Check the configuration of the networking software on the ally machine. .TP iFOR/LS Ally encountered error registering with namespace. The ally did not find a port number in the i4ls.ini configuration file. Specify a port number for \f2allyport\f1 in i4ls.ini. .TP iFOR/LS Ally encountered error listening for client requests. A network communications error occurred between the ally and the license server. Check that the license server(s) specified in i4ls.ini on the ally's machine are actually running. .TP iFOR/LS Ally encountered error unregistering with the namespace. The ally was not able to remove itself from the NCS namespace. Use lb_admin to clean the namespace. .\" .\" The following text should not be displayed, because it contains future .\" information from Gradient: .\" In the future i4ally will need to support IP, NetBIOS, and IPX. .\" These families .\" and the port numbers that are used with them will need to be configurable. .\" We will probably do this through a combination of arguments and a .\" configuration file. .\" .fi .SH AUTHOR \f3i4ally\f1 was developed by Gradient Technologies, Inc. .\" .\" index@\f4i4ally\f1 \- request license from Network License Servers@@@\f3i4ally(1M)\f1 .\" index@\f1request license from Network License Servers@@@\f3i4ally(1M)\f1 .\" index@\f1license from Network License Servers@@@\f3i4ally(1M)\f1 .\" index@\f1Network License Servers@@@\f3i4ally(1M)\f1 .\" .\" toc@\f3i4ally(1M)\f1:\0\0\f4i4ally\f1@@@request license from Network License Servers .\" .\" $Header: i4findsv.1m,v 76.1 95/08/23 17:21:37 ssa Exp $ .TA i .TH i4findsv 1M "" "iFOR/LS Version 3" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME i4findsv \- Verify a Network License Server is running or not .SH SYNOPSIS .B i4findsv .SH DESCRIPTION The \f3i4findsv\f1 tool uses the iFOR/LS \f3i4tv\f1 program to verifiy if the <\f3server_name\f1> is running a \f3i4lmd\f1 or not. .PP Exit status is 0 if \f3server_name\f1 is running. Otherwise exit status is 255. .SH AUTHOR \f3i4findsv\f1 was developed by Gradient Technologies, Inc. .\" .\" index@\f4ifindsv\f1 \- verify Network License Servers@@@\f3i4findsv(1M)\f1 .\" index@\f1verify Network License Servers@@@\f3i4findsv(1M)\f1 .\" index@\f1Network License Servers, verify@@@\f3i4findsv(1M)\f1 .\" .\" toc@\f3i4findsv(1M)\f1:\0\0\f4i4findsv\f1@@@verify Network License Servers .\" .\" $Header: i4lbfind.1m,v 78.1 96/02/12 16:31:01 ssa Exp $ .TA i .TH i4lbfind 1M "NCS Administration" "iFOR/LS Version 3" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME i4lbfind \- get a list of GLB server daemons and their attributes .SH SYNOPSIS .CR i4lbfind .RC [ \-dl ] .RC [ \-q ] .RC [ \-v ] .SH DESCRIPTION .CR i4lbfind sends out inquiries to the NCS Location Broker daemons and gathers the responses. The results are analyzed to determine whether the Global Location Broker is replicatable or not, and which cell each daemon serves. After ten seconds, the results are summarized, showing the GLB broker type, the server host's network address, a cell name of either \f2default\f1 or \f2alternate_N\f1, and the cell's UUID. .SS Options .TP .CR \-dl Turn on RPC debugging while searching for GLB servers. .TP .CR \-q Query for a GLB server, using the standard RPC mechanism. At most one GLB server will be printed, and only servers in the current machine's cell will be searched. The program will exit with a status of zero if a GLB server was found, otherwise the status will be non-zero. .TP .CR \-v Print out the NCS version string. .SH EXAMPLES A network contains one .CR glbd in each of two NCS cells, and one .CR nrglbd in a third cell. .nf .PP .ft 3 .ft 4 .ps +1 .ifn .in -2 $ /etc/ncs/i4lbfind sent to broadcast address 192.92.110.255 waiting for replies received response from glb daemon at ip:stimpy(192.92.110.43) port 1072. received response from glb daemon at ip:oscar(192.92.110.16) port 1168. received response from glb daemon at ip:vmess(192.92.110.21) port 1114. \&..... replicatable ip:stimpy default 333b91c50000.0d.00.00.87.84.00.00.00 replicatable ip:oscar alternate_1 54bdad9a4000.0d.00.01.83.0f.00.00.00 non-replicatable ip:vmess alternate_2 5c0e4acb8fa7.02.c0.5c.6e.15.00.00.00 $ .ft 1 .ifn .in .ps .fi .SH AUTHOR .CR i4lbfind was developed by Gradient Technologies, Inc. .SH SEE ALSO glbd(1M), i4admin(1M), i4ally(1M), i4lbfind(1M), i4lmd(1M), i4start(1M), i4stop(1M), i4target(1M), i4tv(1M), lb_admin(1M) llbd(1M), nrglbd(1M). .\" .\" toc@\f3i4lbfind(1M)\f1:\0\0\f4i4lbfind\f1@@@get list of GLB server daemons and their attributes .\" .\" index@\f4i4lbfind\f1 \- get list of GLB server daemons and their attributes@@@\f3i4lbfind(1M)\f1 .\" index@\f1GLB server daemons and their attributes@@@\f3i4lbfind(1M)\f1 .\" index@\f1server daemons (GLB) and their attributes@@@\f3i4lbfind(1M)\f1 .\" index@\f1daemons (GLB) and their attributes@@@\f3i4lbfind(1M)\f1 .\" $Header: i4lmd.1m,v 78.1 96/02/29 01:13:39 ssa Exp $ .\" /gradient/repository/ifor/man/man1/i4lmd.man,v 1.3 1995/08/15 20:35:09 ddj Exp $ .TA i .TH i4lmd 1M "" "iFOR/LS Version 3" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME i4lmd \- Starts the license server on a local node. .SH SYNOPSIS \f3i4lmd\f1 [[ \f3-no \f2event_list\f3 | -o | -v | -s | -z | -l \f2log_name\f1 ]] .SH DESCRIPTION The \f3i4lmd\f1 command starts a license server on the local node. There is no graphic interface for this command. .PP \f3NOTE:\f1 Please refer to the release notes for information on how to automate the start-up of \f3i4lmd\f1 on your specific platform. .SH OPTIONS .TP \f3-no\f1 Turns off logging of the events specified in event_list. Any combination of events is valid, but items in the list of events must not be separated by spaces or other characters. Following are the event types that you may specify: .RS .TP \f3l\f1 License-grant and license-release events. .TP \f3c\f1 License checkin events. (Licensed products usually check in with the license server at regular intervals while a user is using the product). .TP \f3w\f1 Waiting events: these include wait events (a user was waiting for a license), waitgrant events (a user was waiting for and then was granted a license), and waitremove events (a user was waiting for a license and then asked to be removed from the queues before a license was granted). .TP \f3v\f1 Vendor events: a vendor was added, renamed or deleted. .TP \f3p\f1 Product events: a product was added, renamed, or deleted. .TP \f3e\f1 Error events. .TP \f3t\f1 License timeout events. (When a licensed product fails to check in with the license server, it may stop running after it "times out." The vendor of the product sets the timeout interval, which is how long a product may run after it has lost contact with the license server). .TP \f3m\f1 Message events. .TP \f3s\f1 License server start/stop events. .RE .TP \f3-l\f1 \f2log_name\f1 Redirects license server log entries to a file and location other than the default (\f3/opt/ifor/ls/conf/log_file\f1). The alternate log file specification (\f2log_name\f1) must be fully qualified starting from the root directory (/). .TP \f3-o\f1 Overrides the in-use flag at a license server database. While a license server is running, its database is flagged as being in use to prevent more than one server from running on the same node. When a license server stops running, the flag is reset. However, if a license server exits abnormally, the flag may not be reset, which prevents the server from restarting. The \f3-o \f1 option overrides an in-use flag, allowing the server to be restarted. Do not use \f3-o \f1 unless you are sure the license server isn't running. .TP \f3-v\f1 iFOR/LS library verbose mode. .TP \f3-s\f1 Secure mode. An iFOR/LS license server running in secure mode will only permit modifications to its database from tools run locally (on the same node). Tools running on remote node are not permitted to modify the database. .TP \f3-z\f1 Debugging flag. (Prints RPC debugging information). .SH EXAMPLES Start a license server; do not log checkin, vendor, product, timeout, or message events: .PP .nf \f3i4lmd -no cvptm .fi \f1 Start a license server, overriding the in-use flag: .PP .nf \f3i4lmd -o .fi \f1 Start a license server, overriding the default log file: .PP .nf \f3i4lmd -l\f2/logs/license_server_log .fi \f1 .SH AUTHOR \f4i4lmd\f1 was developed by HP and Gradient Technologies, Inc. .\" .\" index@\f4i4lmd\f1 \- starts the license server@@@\f3i4lmd(1M)\f1 .\" index@\f1start license server@@@\f3i4lmd(1M)\f1 .\" index@\f1license server, start@@@\f3i4lmd(1M)\f1 .\" .\" toc@\f3i4lmd(1M)\f1:\0\0\f4i4lmd\f1@@@start license server .\" .\" $Header: i4report.1m,v 76.1 95/08/23 17:24:32 ssa Exp $ .TA i .TH i4report 1M "" "iFOR/LS Version 3" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME i4report - Report on license server events .SH SYNOPSIS .nf \f3i4report\f1 [[\f3 -n\f1 \f2node_name\f1 ][ \f3-c\f1 ][ \f3-z\f1 ] [ \f2event_type_list\f1 ][ \f2information_filter_list\f1 ] | [ \f3-h\f1 |\f3 -usage\f1 | \f3-version\f1 ]] .fi .SH DESCRIPTION The \f3i4report \f1command generates reports on license server events. There is no graphic interface for this command. .SH OPTIONS AND ARGUMENTS .PP Default options are indicated by (D). .TP \f3-n\f1 Specifies the server node about which the report is to be generated. If you do not specify a node, \f3i4report \f1 reports on the current server node. .TP \f3-c\f1 Lists data in 80-column format. .TP \f3-z\f1 Debugging flag. (Prints RPC debugging information). .TP \f3-h\f1 Displays command usage information. (Same as \f3-usage\f1). .TP \f3-usage\f1 Displays command usage information. (Same as \f3-h\f1). .TP \f3-version\f1 Displays command version information. .PP \f2event_type_list\f1 .PP You may specify any combination of the following event types. Specify \f3-a\f1 to specify all event types. .TP \f3-a\f1 Lists all log messages. .TP \f3-l\f1 (D) Lists license-related events (product received license, product released license to server, user entered license queue, user exited queue). .TP \f3-e\f1 Lists error events. .TP \f3-s\f1 Lists server start/stop events. .TP \f3-m\f1 Lists messages that were logged by software product or license server. .TP \f3-f\f1 Lists fatal error events. .TP \f3-d\f1 Lists license database modification messages. .PP \f2information_filter_list\f1 .PP You may choose any combination of the following information filters. If no filters are specified the default is all dates, all vendors, all products, all users. .TP \f3-b\f2mm/dd/yy\f1 or \f3-b\f2N\f1 Lists events that occurred beginning at the specified date. The date is either absolute, \f2mm/dd/yy\f1, or \f2N\f1 24 hour periods relative to now in the past. .TP \f3-t\f2mm/dd/yy\f1 or \f3-t\f2N\f1 Lists events that occurred up to the specified date. The date is either absolute, \f2mm/dd/yy\f1, or \f2N\f1 24 hour periods relative to now in the past. .TP \f3-v\f1 \f2vendor_name\f1 Lists events related to the specified vendor(s). .TP \f3-p\f2 product_name\f1 Lists events related to the specified product(s). .TP \f3-u \f2user_name\f1 List events related to the specified user(s). .TP \f3-r \f21\f1 Lists for the specified product the number of requests for licenses, the number of licenses granted, and the percent of rejected requests. .TP \f3-r \f22\f1 Lists the same information as \f3-r 1\f1, but also includes user names and number of licenses installed. .TP \f3-x\f2mm/dd/yy\f1 or \f3-x\f2N\f1 Deletes log file entries written on and before the specified date. The date is either absolute, \f2mm/dd/yy\f1, or \f2N\f1 24 hour periods relative to now in the past. .SH EXAMPLES List license events on the local server node: .nf \f3i4report\f1 .fi List errors and fatal errors occurring between August 31 and September 30 1990 on the server node \f2pluto\f1: .nf \f3i4report -n \f2pluto\f3 -e -f -b \f287/08/31\f3 -t \f287/09/30\f1 .fi List all messages logged at \f2mars\f1 by the vendor \f2xyz\f1: .nf \f3i4report -n \f2mars \f3-m -v \f2xyz\f1 .fi Delete all messages logged at \f2neptune\f1 that are 15 days or more old. Note that here that it actually means 15 days ago at the current time as well. .nf \f3i4report -n \f2neptune \f3-x\f215\f1 .fi .SH AUTHOR \f4i4report\f1 was developed by HP and Gradient Technologies, Inc. .\" .\" index@\f4i4report\f1 \- report license server events@@@\f3i4report(1M)\f1 .\" index@\f1report license server events@@@\f3i4report(1M)\f1 .\" index@\f1license server events, report@@@\f3i4report(1M)\f1 .\" .\" toc@\f3i4report(1M)\f1:\0\0\f4i4report\f1@@@report license server events .\" .\" $Header: i4start.1m,v 78.2 96/02/13 16:45:50 ssa Exp $ .\" /gradient/repository/ifor/man/man1/i4start.man,v 1.3 1995/08/15 20:35:13 ddj Exp $ .TA i .TH i4start 1M "" "iFOR/LS Version 3" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \f3i4start\f1 \- iFOR/LS server start tool .SH SYNOPSIS \f3i4start\f1 .SH DESCRIPTION The \f3i4start\f1 tool can be used to manually re-start an iFOR/LS license server that has been stopped (for instance, with the \f3i4stop\f1 tool). It will also start location brokers, if they are needed on the system. The tool is located in \f3/opt/ifor/ls/bin\f1. .\" .\" toc@\f3i4start(1M)\f1:\0\0\f4i4start\f1@@@iFOR/LS server start tool .\" .\" index@\f4i4start\f1 \- iFOR/LS server start tool@@@\f3i4start(1M)\f1 .\" index@\f1iFOR/LS server start tool@@@\f3i4start(1M)\f1 .\" .\" $Header: i4stat.1m,v 76.1 95/08/23 17:25:22 ssa Exp $ .TA i .TH i4stat 1M "" "iFOR/LS Version 3" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME i4stat \- Display the status of the license server system .SH SYNOPSIS .PP \f3i4stat\f1 .PP \f3i4stat --\f1 [ \f3standard X arguments\f1 ] .PP \f3i4stat\f1 { \f3-t\f1 | \f3-i\f1 | \f3-a\f1 | \f3-u\f1 \f2user_name\f1 } [[ \f3-n\f1 \f2server\f1 ][ \f3-v\f1 \f2vendor\f1 ][ \f3-p\f1 \f2product\f1 ] [ \f3-r\f1 \f2version\f1 | \f3-z\f1 ]] | [ \f3-h\f1 | \f3-usage\f1 | \f3-version\f1 ] .SH DESCRIPTION The \f3i4stat\f1 command displays, in the transcript pad below the \f3i4stat\f1 window, status information on licenses. Note that end users as well as system administrators may find \f3i4stat\f1 useful for finding out the status of licenses in an iFOR/LS system. .PP \f3i4stat\f1 features both a command-line and graphic interface. If all options are omitted, or the X argument delimiter \f3--\f1 is found on the command line, \f3i4stat\f1 invokes a graphic interface. Both interfaces are described here. .PP In graphic interface mode, you can get help by placing the cursor on any button and pressing SHIFT/HELP. .SH GRAPHIC INTERFACE MENUS AND BUTTONS .TP \f3Exit Button\f1 Select this button to exit from \f3i4stat\f1. .TP \f3License Information Menu \f1 This menu contains three buttons: \f3Users\f1, \f3Installed\f1, and \f3Usage\f1 (see below). After you have selected a server and product from the Server and Product lists, select these buttons to display information about users, installed licenses, and usage of the selected server and product. .TP \f3Users Button\f1 Displays information, listed by vendor, product and server, about current users of licensed products, including user ID, node name, group, number of licenses held, and start time. .TP \f3Installed Button\f1 Displays information, listed by vendor, product and server, about product licenses installed at selected servers, including number of active licenses, their start and end dates, their type, the number of licenses currently in use, and the length of the queue of users waiting for licenses. .TP \f3Usage Button\f1 Displays information, listed by vendor, product and server, about the usage of products, including number of licenses in use, total number of licenses, and number of licenses available. .TP \f3Server List Box\f1 This list box, directly to the right of the License Information menu, displays the server list. At the top of this box is the All Servers (Update) button (see below). At the left of the box is a scroll bar that you can use to scroll the list. .TP \f3All Servers (Update) Button\f1 Select this button to poll the network and update the server list. When you select this button, a check mark appears in the box at its left. A check mark in this box indicates that: .in +.5i .sp All existing servers are displayed in the Server List Box. .sp The vendors and products listed in the Product List box are the vendors and products existing at the server currently selected in the Server List box.. .in -.5i .sp After updating the server list, select a server to display (in the Product List box) the products it administers. Next select a product (or All) from the list of products; then select \f3Users\f1, \f3Installed\f1, or \f3Usage\f1. .TP \f3Product List Box\f1 This list box, directly to the right of the Server List box, displays the server list. At the top of this box is the All Products (Update) button (see below). At the left of the box is a scroll bar that you can use to scroll the list. .TP \f3All Products (Update) Button\f1 Select this button to poll the network and update the product list. When you select this button, a check mark appears in the box at its left. A check mark in this box indicates that: .in +.5i .sp All existing vendors and products are displayed in the Product List Box. .sp The servers listed in the Server List box are the servers that hold licenses for the product currently selected in the Product List box. .in -.5i .sp After updating the product list, select a product to display (in the Server List box) the servers holding licenses for the product. Select a server (or All) from the list of servers; then select \f3Users\f1, \f3Installed\f1, or \f3Usage\f1. .TP \f3Status Message Field \f1 This field, across the bottom of the window, describes the information currently displayed in the Server List box and the Product List box. .SH COMMAND-LINE INTERFACE OPTIONS AND ARGUMENTS .TP \f3-t\f1 Displays a table of total license usage compared to installed licenses; all servers and all products are listed by default. .TP \f3-i\f1 Displays installed licenses; all servers and all products are listed by default. .TP \f3-a\f1 Displays information about all license users; all servers and all products are listed by default. .TP \f3-u user_name\f1 Displays licenses being used by the specified user. .PP \f3Note:\f1 One of the options listed above must be included in all \f3i4stat\f1 command lines. .TP \f3-n server\f1 Displays licenses located at the specified server. .TP \f3-v vendor\f1 Displays licenses of the specified vendor; if the vendor string contains spaces, it must be delimited by single or double quotes. .TP \f3-p product\f1 Displays licenses for the specified product; if the product string contains spaces, it must be delimited by single or double quotes. .TP \f3-r version\f1 Displays licenses for the specified revision of a product specified by \f3-p\f1; if the version string contains spaces, it must be delimited by single or double quotes. .TP \f3-z\f1 Debugging flag. (Prints RPC debugging information). .TP \f3-h\f1 Displays command usage information. (Same as \f3-usage\f1). .TP \f3-usage\f1 Displays command usage information. (Same as \f3-h\f1). .TP \f3-version\f1 Displays command version information. .SH EXAMPLES Display all licenses installed for all products on all servers: .nf \f3i4stat -i\f1 .fi Display licenses in use from the server park: .nf \f3i4stat -a -n park\f1 .fi Display licenses installed and currently in use for the product KwikDraw, revision V2.1: .nf \f3i4stat -a -i -p Kwik-Draw -r V2.1\f1 .fi Display licenses installed on park for the vendor Apollo. .nf \f3i4stat -i -v Apollo -n park\f1 .fi .SH AUTHOR \f4i4stat\f1 was developed by HP and Gradient Technologies, Inc. .\" .\" index@\f4i4stat\f1 \- display status of license server system@@@\f3i4stat(1M)\f1 .\" index@\f1display status of license server system@@@\f3i4stat(1M)\f1 .\" index@\f1status of license server system@@@\f3i4stat(1M)\f1 .\" index@\f1license server system, display status@@@\f3i4stat(1M)\f1 .\" .\" toc@\f3i4stat(1M)\f1:\0\0\f4i4stat\f1@@@display status of license server system .\" .\" $Header: i4stop.1m,v 78.2 96/02/13 16:49:29 ssa Exp $ .\" /gradient/repository/ifor/man/man1/i4stop.man,v 1.2 1995/08/15 20:35:15 ddj Exp $ .TH i4stop 1M "" "iFOR/LS Version 3" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \f3i4stop\f1 \- iFOR/LS server stop tool .SH SYNOPSIS \f3i4stop\f1 .SH DESCRIPTION The \f3i4stop\f1 tool can be used to manually stop an iFOR/LS license server (and location brokers, if they are running on the system. Use this tool \f3on\f1 the system that contains the active iFOR/LS license server that you want to stop. The tool is located in \f3/opt/ifor/ls/bin\f1. .\" .\" toc@\f3i4stop(1M)\f1:\0\0\f4i4stop\f1@@@iFOR/LS server stop tool .\" .\" index@\f4i4stop\f1 \- iFOR/LS server stop tool@@@\f3i4stop(1M)\f1 .\" index@\f1iFOR/LS server stop tool@@@\f3i4stop(1M)\f1 .\" .\" $Header: i4target.1m,v 78.2 96/05/09 12:27:31 ssa Exp $ .\" /gradient/repository/ifor/man/man1/i4target.man,v 1.5 1995/08/15 20:35:16 ddj Exp $ .TA i .TH i4target 1M "" "iFOR/LS Version 3" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME i4target \- Returns the local iFOR/LS target id. .SH SYNOPSIS \f3i4target\f1 .PP \f3i4target\f1 [ \f3\-c\f1 ] [ \f3\-C\f1 ] [ \f3\-h\f1 ] [ \f3\-H\f1 ] [ \f3\-o\f1 ] [ \f3\-O\f1 ] [ \f3\-q\f1 ] [ \f3\-Q\f1 ] [ \f3\-v\f1 ] [ \f3\-V\f1 ] .SH "DESCRIPTION" .B i4target is used to find the target ID that can be used by iFOR/LS for locking licenses to a particular system. .PP To create iFOR/LS licenses for an application, an application supplier will need the target ID of the machine where the iFOR/LS licenses will be installed. The target ID tool (\f3i4target\f1) should be run on the machine where you want to identify an iFOR/LS target ID. For server-based licensing, this will be the machine that is executing the license server (\f3i4lmd\f1) where you plan to install this application supplier's licenses. For nodelocked licensing, this will be the system where the application will be executing. .PP The algorithm that is used to identify an iFOR/LS target ID may vary depending on operating system platform. .PP For example: On an HP-UX machine licenses managed by the i4lmd (concurrent and use once licenses), the iFOR/LS target ID is derived from the link level address of the LAN card accessed by the device file \f4/dev/i4target\f1 on the machine that is running the i4lmd. If \f4/dev/i4target\f1 does not exist and the super-user is executing .BR i4target , .B i4target will create \f4/dev/i4target\f1. On an HP 9000 Series 700 or 800, the device file will be for the lan0 LAN card. This is the same method used by the i4lmd for determining the iFOR/LS ID of the machine on which it is executing. .PP On HP-UX, for iFOR/LS nodelocked licenses, the iFOR/LS ID is derived from: .RS .TP 3 \(bu The LAN card accessed by /dev/i4target, or .TP \(bu The built in SPU ID number, or .TP \(bu An HIL ID Module. .RE .SS "Options" .TP 15 .B \-c -C Change the permanent target ID value. .TP .B \-h -H Help. Display a list of options. .TP .B \-o -O Display operating system name. .TP .B \-q -Q Display target ID in quiet mode (without headers). .TP .B \-v -V Display a verbose list of the iFOR/LS target IDs from each possible source. The list consist of the link level address of the installed LAN cards. A super-user can then use the address to change to an alternate LAN card. This lets you change the IO slot where a LAN card is installed without losing the use of iFOR/LS licenses locked to that LAN card. .PP .SH "RETURN VALUE" .B i4target always returns 0. .SH DIAGNOSTICS Messages displayed during execution are self-explanatory. .SH EXAMPLES To find the current local iFOR/LS target ID(s): .PP .nf .B i4target .PP Examples for each of the options are shown below: .PP .B i4target -c \c or \c .B i4target -C .PP .CR "Current Permanent Target ID: 3e53d0" .PP .CR "1. Target ID value: 3e53d0" .CR " LAN card at logical unit 0" .PP .CR "There is only one choice for the new Permanent Target ID." .CR "Enter '1' to select it; enter any other character to abort: 1" .PP .CR "New Permanent Target ID: 3e53d0" .PP .CR "NOTE: i4lmd must be restarted for the new" .CR " Permanent Target ID to take effect." .PP .B i4target -h \c or \c .B i4target -H .PP .CR "Usage:" .CR " i4target [options]" .CR " options are: .CR " -[vV] : verbose mode; detailed output" .CR " -[qQ] : quiet mode; no headers in output" .CR " -[cC] : change Permanent Target ID;" .CR " -[hH] : displays this message" .CR " -[oO] : displays os name" .PP .B i4target -o \c or \c .B i4target -O .PP .CR "HP-UX" .PP .B i4target -q \c or \c .B i4target -Q .PP .CR "3e53d0" .PP .B i4target -v \c or \c .B i4target -V .PP .CR "Permanent Target ID: 3e53d0" .PP .CR "SPU Target ID: 70328251" .PP .CR "The Permanent Target ID is derived from a permanent hardware source" .CR "on the system from which the i4target program is executed." .CR "This target ID may be used for all license types." .PP .CR "The SPU ID is derived from a hardware identification number on the" .CR "SPU. It is used as the Permanent Target ID when no higher-priority" .CR "sources for Permanent Target ID (i.e., LAN cards) are present." .PP .fi .PP .SH AUTHOR \f4i4target\f1 was developed by .SM HP and further enhanced for other platforms by .SM Gradient. .SH "SEE ALSO" .I iFOR EZ-LoK Programmer's Guide and Reference .\" .\" index@\f4i4target\f1 \- print information about local IFOR/LS target id@@@\f3i4target(1M)\f1 .\" index@\f1print information about local IFOR/LS target id@@@\f3i4target(1M)\f1 .\" index@\f1local IFOR/LS target id, print information@@@\f3i4target(1M)\f1 .\" .\" toc@\f3i4target(1M)\f1:\0\0\f4i4target\f1@@@print information about local IFOR/LS target id .\" .\" $Header: i4tv.1m,v 78.1 96/02/29 01:14:58 ssa Exp $ .\" /gradient/repository/ifor/man/man1/i4tv.man,v 1.5 1995/08/15 20:35:16 ddj Exp $ .TA i .TH i4tv 1M "" "iFOR/LS Version 3" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \f3i4tv\f1 \- Verify that iFOR/LS License Servers are working .SH SYNOPSIS \f3i4tv\f1 [ \f3-n\f1 \f2hostname\f1 | \f3-z\f1 | \f3-v\f1 ] [ \f3-h\f1 | \f3-usage\f1 | \f3-version\f1 ] .SH DESCRIPTION The \f3i4tv\f1 tool can be used after the license servers have been started to verify that that they are running properly. The \f3i4tv\f1 program resides in the \f4/opt/ifor/ls/bin\f1 directory. A message describing a completed license transaction and a list of all license servers will be displayed. Once a license server has been configured using \f3i4config\f1, the \f3i4tv\f1 tool is used to quickly verify the status of the license server \f3i4lmd\f1. .SS Options .TP \f3-n\f1 \f2hostname\f1 The \f3-n\f1 option is used to check that the specified machine is running a license server. It returns \f30\f1 if the hostname is running \f3i4lmd\f1 and it returns \f31\f1 if the hostname is not running \f3i4lmd\f1. .TP \f3-z\f1 The \f3-z\f1 option turns on RPC tracing messages, which can be used to diagnose problems. .TP \f3-v\f1 Displays progress messages during the license request operation. .TP \f3-h\f1 Displays command usage information (same as -usage) .TP \f3-usage\f1 Displays command usage information (same as -h) .TP \f3-version\f1 Displays command version information. .PP If you can run \f3i4tv\f1 successfully but are still having a problem with a licensed product, the problem is probably with the licenses, or possibly with the product itself: in this case, talk to the vendor of the licensed software product. .PP If you can not run \f3i4tv\f1 successfully or it takes more than 10 seconds to retrieve a license, verify that \f3llbd\f1, \f3glbd\f1 and \f3i4lmd\f1 are all running. Use the utilities \f3lb_admin\f1 to clean the database. Answer YES to all database entries that do not respond. If you receive one of the error messages listed below, use the explanation of the error to fix the problem. Then try running \f3i4tv\f1 again. .PP If you can not run \f3i4tv\f1 successfully and receive an error that's not listed below, it means there is a problem with the software on which iFOR/LS ARK is layered (for example, TCP or NCS), or a hardware problem. .SH ERROR MESSAGES .TP netls_no_svrs_found No license servers are running or someone has deleted the iFOR/LS Test Vendor from the license servers. .TP netls_license_not_found Someone has deleted the Test Vendor licenses that each server automatically installs the first time that it starts. This prohibits anyone from using the test and verification tool (\f3i4tv\f1). .TP netls_not_authorized Someone has edited the user file to restrict the use of \f3i4tv\f1. .TP netls_bad_timestamp System clocks have not been synchronized to within 12 hours. .SH EXAMPLES .sp .PP Run the \f3i4tv\f1 test and verification tool: .sp .nf .B "i4tv" i4TV Version 3.0 -- iFOR/LS Test and Verification Tool (c) Copyright 1991, 1992, 1993, Hewlett-Packard Company, All Rights Reserved (c) Copyright 1991-1995, Gradient Technologies Inc., All Rights Reserved Completed license transaction on node 3541b8 running iFOR/LS 3.0 Active iFOR/LS Servers: hp_snake.gradient.com (HP-UX) running iFOR/LS Version 3.0.0 .PP Check for the presence of the license server hp1020: .sp .nf .B "i4tv -n hp1020" (c) Copyright 1991, 1992, 1993, Hewlett-Packard Company, All Rights Reserved (c) Copyright 1991-1996, Gradient Technologies Inc., All Rights Reserved hp1020 running .fi .SH AUTHOR \f3i4tv \f1 was developed by HP and Gradient Technologies, Inc. .\" .\" index@\f4i4tv\f1 \- verify Network License Servers are working@@@\f3i4tv(1M)\f1 .\" index@\f1verify Network License Servers are working@@@\f3i4tv(1M)\f1 .\" index@\f1Network License Servers, verify working@@@\f3i4tv(1M)\f1 .\" .\" toc@\f3i4tv(1M)\f1:\0\0\f4i4tv\f1@@@verify Network License Servers are working .\" .\" $Header: identd.1m,v 1.1.113.2 96/01/04 16:29:08 indnetwk Exp $ .\" Copyright (c) 1992 Peter Eriksson, Lysator, Linkoping University. .\" This software has been released into the public domain. .\" .TA i .TH identd 1M .SH NAME identd \- TCP/IP IDENT protocol server .SH SYNOPSIS .C /usr/lbin/identd .RC [ \-i | .CR \-w | \-b ] .RC [ \-t\c .IR seconds ] .RC [ \-u\c .IR uid ] .RC [ \-g\c .IR gid ] .RC [ \-p\c .IR port ] .RC [ \-a\c .IR address ] .RC [ \-c\c .IR charset ] .RC [ \-n ] .RC [ \-o ] .RC [ \-e ] .RC [ \-l ] .RC [ \-V ] .RC [ \-m ] .RC [ \-N ] .RC [ \-d ] .RC [ kernelfile .RI [ kmemfile ]] .SH DESCRIPTION .CR identd is a server which implements the TCP/IP proposed standard IDENT user identification protocol as specified in the RFC 1413 document. .PP .CR identd operates by looking up specific TCP/IP connections and returning the user name of the process owning the connection. .SS Arguments .TP 10 .C -i The .CR -i flag, which is the default mode, should be used when starting the daemon from .CR inetd with the "nowait" option in the .CR /etc/inetd.conf file. Use of this mode will make .CR inetd start one .CR identd daemon for each connection request. .TP .C -w The .CR -w flag should be used when starting the daemon from .CR inetd with the "wait" option in the .CR /etc/inetd.conf file. This is the preferred mode of operation since that will start a copy of .CR identd at the first connection request and then .CR identd will handle subsequent requests without having to do the nlist lookup in the kernel file for every request as in the .CR -i mode above. The .CR identd daemon will run either forever, until a timeout, as specified by the .CR -t flag, occurs. .TP .C -b The .CR -b flag can be used to make the daemon run in standalone mode without the assistance from .CR inetd. This mode is the least preferred mode, and not supported by HP, since a bug or any other fatal condition in the server will make it terminate and it will then have to be restarted manually. Other than that is has the same advantage as the .CR -w mode in that it parses the nlist only once. .TP .CI -t seconds The .CI -t seconds option is used to specify the timeout limit. This is the number of seconds a server started with the .CR -w flag will wait for new connections before terminating. The server is automatically restarted by .CR inetd whenever a new connection is requested if it has terminated. A suitable value for this is 120 (2 minutes), if used. It defaults to no timeout (ie, will wait forever, or until a fatal condition occurs in the server). .TP .CI -u uid The .CI -u uid option is used to specify a user id number which the .CR ident server should switch to after binding itself to the TCP/IP port if using the .CR -b mode of operation. .TP .CI -g gid The .CI -g gid option is used to specify a group id number which the .CR ident server should switch to after binding itself to the TCP/IP port if using the .CR -b mode of operation. .TP .CI -p port The .CI -p port option is used to specify an alternative port number to bind to if using the .CR -b mode of operation. It can be specified by name or by number. Defaults to the IDENT port (113). .TP .CI -a address The .CI -a address option is used to specify the local address to bind the socket to if using the .CR -b mode of operation. Can only be specified by IP address and not by domain name. Defaults to the INADDR_ANY address which normally means all local addresses. .TP .C -V The .CR -V flag makes .CR identd display the version number and the exit. .TP .C -l The .CR -l flag tells .CR identd to use the System logging daemon .CR syslogd for logging purposes. .TP .C -o The .CR -o flag tells .CR identd to not reveal the operating system type it is run on and to instead always return "OTHER". .TP .C -e The .CR -e flag tells .CR identd to always return "UNKNOWN-ERROR" instead of the "NO-USER" or "INVALID-PORT" errors. .TP .CI -c charset The .CI -c charset flags tells .CR identd to add the optional (according to the IDENT protocol) character set designator to the reply generated. should be a valid character set as described in the MIME RFC in upper case characters. .TP .C -n The .CR -n flags tells .CR identd to always return user numbers instead of user names if you wish to keep the user names a secret. .TP .C -N The .CR -N flag makes .CR identd check for a file .CR .noident in each homedirectory for a user which the daemon is about to return the user name for. It that file exists then the daemon will give the error HIDDEN-USER instead of the normal USERID response. .TP .C -m The .CR -m flag makes .CR identd use a mode of operation that will allow multiple requests to be processed per session. Each request is specified one per line and the responses will be returned one per line. The connection will not be closed until the connecting part closes it's end of the line. \f3Please note that this mode violates the protocol specification as it currently stands\f1. .TP .C -d The .CR -d flag enables some debugging code that normally should NOT be enabled since that breaks the protocol and may reveal information that should not be available to outsiders. .TP .C kernelfile .CR kernelfile defaults to the normally running kernel file. .TP .C kmemfile .CR kmemfile defaults to the memory space of the normally running kernel. .SH INSTALLATION .CR identd is invoked either by the internet server (see .IR inetd (1M)) for requests to connect to the IDENT port as indicated by the .CR /etc/services file (see .IR services (5)) when using the .CR -w or .CR -i modes of operation or started manually by using the .CR -b mode of operation. .SH EXAMPLES Since the server is located in .CR /usr/lbin/identd one can put either: .IP .C "ident stream tcp wait bin /usr/lbin/identd identd -w -t120" .PP or: .IP .C "ident stream tcp nowait bin /usr/lbin/identd identd -i" .PP into the .CR /etc/inetd.conf file. .PP To start it using the unsupported .CR -b mode of operation one can put a line like this into the .CR /sbin/init.d/sendmail file under the 'start' section: .IP .C "/usr/lbin/identd -b -u2 -g2" .PP This will cause .CR identd to be started as daemon whenever .CR sendmail is running. It will run in the background as user 2, group 2 (user 'bin', group 'bin'). .SH SEE ALSO inetd.conf (4). .\" .\" index@\f4identd\f1 \- TCP/IP IDENT protocol server@@@\f3identd(1M)\f1 .\" index@\f1TCP/IP IDENT protocol server@@@\f3identd(1M)\f1 .\" index@\f1IDENT protocol server, TCP/IP@@@\f3identd(1M)\f1 .\" index@\f1protocol server, for TCP/IP IDENT@@@\f3identd(1M)\f1 .\" .\" toc@\f3identd(1M)\f1:\0\0\f4identd\f1@@@TCP/IP IDENT protocol server .\" $Header: ifconfig.1m,v 78.1 96/01/12 17:56:17 ssa Exp $ .TA i .TH ifconfig 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ifconfig \- configure network interface parameters .SH SYNOPSIS .CR ifconfig .I interface .I address_family .RI [ address .RI [ dest_address ]\|] .RI [ parameters ] .PP .CR ifconfig .I interface .RI [ address_family ] .SH DESCRIPTION The first form of the .CR ifconfig command assigns an address to a network interface and/or configures network interface parameters. .CR ifconfig must be used at boot time to define the network address of each interface present on a machine. It can also be used at other times to redefine an interface's address or other operating parameters. .PP The second form of the command, without .IR address_family , displays the current configuration for .IR interface . If .I address_family is also specified, .CR ifconfig reports only the details specific to that address family. .PP Only a user with appropriate privileges can modify the configuration of a network interface. All users can run the second form of the command. .SS Arguments .CR ifconfig recognizes the following arguments: .RS .TP 16 .I address Either a host name present in the host name database (see .IR hosts (4)), or a DARPA Internet address expressed in Internet standard dot notation (see .IR inet (3N)). The host number can be omitted on 10MB/second Ethernet interfaces (which use the hardware physical address), and on interfaces other than the first. .TP .I address_family Name of protocol on which naming scheme is based. An interface can receive transmissions in differing protocols, each of which may require separate naming schemes. Therefore, it is necessary to specify the .IR address_family , which may affect interpretation of the remaining parameters on the command line. The only address family currently supported is .CR inet (DARPA-Internet family). .TP .I dest_address Address of destination system. Consists of either a host name present in the host name database (see .IR hosts (4)), or a DARPA Internet address expressed in Internet standard dot notation (see .IR inet (3N)). .TP .I interface A string of the form .IR "name\|unit" , such as .CR lan0 . (See the LAN Card Numbering subsection.) .TP .I parameters One or more of the following operating parameters: .RS .TP 15 .CR up Mark an interface "up". Enables interface after an .CR "ifconfig down" . Occurs automatically when setting the address on an interface. Setting this flag has no effect if the hardware is "down". .TP .CR down Mark an interface "down". When an interface is marked "down", the system will not attempt to transmit messages through that interface. If possible, the interface will be reset to disable reception as well. This action does not automatically disable routes using the interface. .TP .CR broadcast (Inet only) Specify the address that represents broadcasts to the network. The default broadcast address is the address with a host part of all 1's. .TP .CR debug Enable driver-dependent debugging code. This usually turns on extra console error logging. .TP .CR -debug Disable driver-dependent debugging code. .TP .CR ipdst (NS only) This is used to specify an Internet host that is willing to receive IP packets encapsulating NS packets bound for a remote network. In this case, an apparent point-to-point link is constructed, and the address specified is taken as the NS address and network of the destination. .TP .CI metric \0n Set the routing metric of the interface to .IR n . The default is 0. The routing metric is used by the routing protocol (see .IR gated (1m)). Higher metrics have the effect of making a route less favorable; metrics are counted as additional hops to the destination network or host. .TP .CI netmask \0mask (Inet only) Specify how much of the address to reserve for subdividing networks into sub-networks or aggregating networks into supernets. .I mask can be specified as a single hexadecimal number with a leading .CR 0x , with a dot-notation Internet address, or with a pseudo-network name listed in the network table (see .IR networks (4)). For subdividing networks into sub-networks, .I mask must include the network part of the local address, and the subnet part which is taken from the host field of the address. .I mask must contain 1's in the bit positions in the 32-bit address that are to be used for the network and subnet parts, and 0's in the host part. The 1's in the .I mask must be contiguous starting from the leftmost bit position in the 32-bit field. .I mask must contain at least the standard network portion, and the subnet field must be contiguous with the network portion. The subnet field must contain at least 2 bits. The subnet part after performing a bit-wise AND operation between the .I address and the .I mask must not contain all 0's or all 1's. For aggregating networks into supernets, .I mask must only include a portion of the network part. .I mask must contain contiguous 1's in the bit positions starting from the leftmost bit of the 32-bit field. .TP .CR trailers Request the use of a "trailer" link-level encapsulation when sending. If a network interface supports .CR trailers , the system will, when possible, encapsulate outgoing messages in a manner that minimizes the number of memory-to-memory copy operations performed by the receiver. On networks that support the Address Resolution Protocol, this flag indicates that the system should request that other systems use trailers when sending to this host. Similarly, trailer encapsulations will be sent to other hosts that have made such requests. Currently used by Internet protocols only. See WARNINGS section. .TP .CR -trailers Disable the use of a "trailer" link-level encapsulation (default). .RE .RE .SS LAN Card Numbering The .IR name of an interface associated with a LAN card is .CR lan , and its .IR unit number is determined as follows. The LAN card installed first in the system is given interface unit number .CR 0 ; the next LAN card installed is given interface unit number .CR 1 ; and so on. When there are two or more LAN cards installed at the same time, interface unit numbers are assigned according to card positions in the backplane: the LAN card that appears "first" in the backplane is given the interface unit number N; the next LAN card in the backplane is given the number N+1. .PP The .CR lanscan command can be used to display the name and unit number of each interface that is associated with a LAN card (see .IR lanscan (1M)). .SS Supernets A supernet is a collection of smaller networks. Supernetting is a technique of using the netmask to aggregate a collection of smaller networks into a supernet. This technique is particularly useful for class C networks. A Class C network can only have 254 hosts. This can be too restrictive for some companies. For these companies, a netmask that only contains a portion of the network part can be applied to the hosts in these class C networks to form a supernet. This supernet netmask should be applied to those interfaces that connect to the supernet using the .I ifconfig command. For example, a host can configure its interface to connect to a class C supernet, 192.6, by configuring an IP address of 192.6.1.1 and a netmask of 255.255.0.0 to its interface. .SH DIAGNOSTICS Messages indicate if the specified interface does not exist, the requested address is unknown, or the user is not privileged and tried to alter an interface's configuration. .SH WARNINGS Currently, all HP 9000 systems can receive trailer packets but do not send them. Setting the .CR trailers flag has no effect. .SH SEE ALSO netstat(1), lanconfig(1m), lanscan(1m) hosts(4), routing(7). .\" .\" index@\f4ifconfig\f1 \- configure network interface parameters@@@\f3ifconfig(1M)\f1 .\" index@configure network interface parameters@@@\f3ifconfig(1M)\f1 .\" index@network interface parameters, configure@@@\f3ifconfig(1M)\f1 .\" index@interface parameters, configure network@@@\f3ifconfig(1M)\f1 .\" index@parameters, configure network interface@@@\f3ifconfig(1M)\f1 .\" .\" toc@\f3ifconfig(1M)\f1:\0\0\f4ifconfig\f1@@@configure network interface parameters .\" $Header: inetd.1m,v 74.1 95/05/10 21:49:13 ssa Exp $ .TA i .TH inetd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inetd \- Internet services daemon .SH SYNOPSIS .CR /usr\/sbin/inetd .RC [ \-c ] .PP .CR /usr\/sbin/inetd .RC [ \-k ] .PP .CR /usr\/sbin/inetd .RC [ \-l ] .SH DESCRIPTION The .CR inetd daemon is the Internet superserver, which invokes Internet server processes as needed. It must be running before other hosts can connect to the local host through .CR ftp , .CR rcp , .CR remsh , .CR rlogin , and .CR telnet . The .CR inetd daemon also supports services based on the Remote Procedure Call (RPC) protocol (NFS), such as .CR rwalld and .CR rusersd . If RPC servers are started by .CR inetd , the .CR portmap server (see .IR portmap (1M)) must be started before .CR inetd . .PP The .CR inetd daemon is designed to invoke all the Internet servers as needed, thus reducing load on the system. It is normally started at system boot time. Only one .CR inetd can run at any given time. .PP The .CR inetd daemon starts servers for both stream and datagram type services. For stream services, .CR inetd listens for connection requests on Internet stream sockets. When a connection is requested for one of its sockets, .CR inetd decides which service the socket will support, forks a process, invokes an appropriate server for the connection, and passes the connected socket to the server as .CR stdin and .CR stdout . Then .CR inetd returns to listening for connection requests. .PP For datagram services, .CR inetd waits for activity on Internet datagram sockets. When an incoming datagram is detected, .CR inetd forks a process, invokes an appropriate server, and passes the socket to the server as .CR stdin and .CR stdout . Then .CR inetd waits, ignoring activity on that datagram socket, until the server exits. .PP The .CR inetd daemon is normally started by the .CR /sbin/init.d/inetd script, which is invoked during the boot-time initialization. Otherwise, .CR inetd can be started only by the superuser. .PP The Internet daemon and the servers it starts inherit the .CR LANG and .CR TZ environment variables and the .CR umask of the process that started .CR inetd . If .CR inetd is started by the superuser, it inherits the superuser's umask, and passes that umask to the servers it starts. .PP When invoked, .CR inetd reads .CR /etc/inetd.conf and configures itself to support whatever services are included in that file (see .IR inetd.conf (4)). The .CR inetd daemon also performs a security check if the file .CR /var/adm/inetd.sec exists (see .IR inetd.sec (4)). If the Internet daemon refuses a connection for security reasons, the connection is shut down. Most RPC-based services, if their first connection is refused, attempt to connect four more times at 5-second intervals before timing out. In such cases, .CR inetd refuses the connection from the same service invocation five times. This is visible in the system log if .CR inetd connection logging and .CR syslogd logging for the .B daemon facility are both enabled (see .IR syslogd (1M)). .PP The .CR inetd daemon provides several "trivial" services internally by use of routines within itself. The services are .CR echo , .CR discard , .CR chargen (character generator), .CR daytime (human readable time), and .CR time (machine readable time in the form of the number of seconds since midnight, January 1, 1900). The .CR inetd daemon provides both TCP- and UDP-based servers for each of these services. See .IR inetd.conf (4) for instructions on configuring internal servers. .SS Options .CR inetd recognizes the following options. These options can be used only by a superuser. .RS .TP .CR \-c Reconfigure the Internet daemon; in other words, force the current .CR inetd to reread .CR /etc/inetd.conf . This option sends the signal .CR SIGHUP to the Internet daemon that is currently running. Any configuration errors that occur during the reconfiguration are logged to the .CR syslogd daemon facility. .TP .CR \-k Kill the current .CR inetd . This option sends the signal .CR SIGTERM to the Internet daemon that is currently running, causing it to exit gracefully. This option is the preferred method of killing .CR inetd . .TP .CR \-l By default, .CR inetd starts with connection logging disabled. If no .CR inetd is running, the .CR \-l option causes the .CR inetd to start with connection logging enabled. Otherwise the .CR \-l option causes .CR inetd to send the signal .CR SIGQUIT to the .CR inetd that is already running, which causes it to toggle the state of connection logging. .IP When connection logging is enabled, the Internet daemon logs attempted connections to services. It also logs connection attempts which fail the security check. This information can be useful when trying to determine if someone is repeatedly trying to access your system from a particular remote system (in other words, trying to break into your system). Successful connection attempts are logged to the .CR syslogd daemon facility at the .B info log level. Connection attempts failing the security check are logged at the .B notice log level. .CR inetd also logs whether the connection logging has been enabled or disabled at the .I info log level. .RE .SH DIAGNOSTICS The following diagnostics are returned by the Internet daemon before it disconnects from the terminal. .RS .PP .C "An inetd is already running" .IP An attempt was made to start an Internet daemon when one was already running. It is incorrect to call the Internet daemon a second time without the .CR \-c , .CR \-k , or .CR \-l option. .PP .C "There is no inetd running" .IP An attempt was made to reconfigure an Internet daemon when none was running. .PP .C "Inetd not found" .IP This message occurs if .CR inetd is called with .CR \-c and another Internet daemon is running but cannot be reconfigured. This occurs if the original Internet daemon died without removing its semaphore. .IP .IR "Next step" : Use the .CR "inetd \-k" command to remove the semaphore left by the previous Internet daemon; then restart the daemon. .RE .PP The following diagnostics are logged to the .CR syslogd daemon facility. Unless otherwise indicated, messages are logged at the .B error log level. .RS .PP .C "/etc/inetd.conf: Unusable configuration file" .IP The Internet daemon is unable to access the configuration file .CR /etc/inetd.conf . The error message preceding this one specifies the reason for the failure. .PP .CI "/etc/inetd.conf: line \&" number ": \&" error .IP There is an error on the specified line in .CR /etc/inetd.conf . The line in the configuration file is skipped. This error does not stop the Internet daemon from reading the rest of the file and configuring itself accordingly. .IP .IR "Next step" : Fix the line with the error and reconfigure the Internet daemon by executing the .CR "inetd \-c" command. .PP .IC system_call : \0message .IP .I "system_call" failed. See the corresponding manual entry for a description of .IR system_call . The reason for the failure is explained in .IR message . .PP .C "Cannot configure inetd" .IP None of the services/servers listed in the configuration file could be set up properly, due to configuration file errors. .PP .CI "Too many services (max \&" n ) .IP The number of active services listed in the configuration file exceeds the "hard" limit that can be supported by the system (see .IR setrlimit (2)). .IP .IR "Next step" : Reduce the number of services listed in the configuration file, then reconfigure the Internet daemon by running the command .CR "inetd \-c" . .PP .IC file ": \e found before end of line \&" line .IP .I file can be either .C inetd.conf or .CR inetd.sec . If a backslash is not immediately followed by an end of line, it is ignored and the information up to the end of line is accepted. In this case, the next line of the file is not appended to the end of the current line. Unless all the information required is present on a single line, configuration file error messages are also output. This message is logged at the .B warning log level. .PP .IC service/protocol ": Unknown service" .IP The call to the library routine .CR getservbyname (see .IR getservent (3N)) failed. The service is not listed in .CR /etc/services . .IP .IR "Next step" : Include that service in .CR /etc/services or eliminate the entry for the service in .CR /etc/inetd.conf . .PP .IC service/protocol ": Server failing (looping), service terminated." .IP When .CR inetd tries to start 40 servers within 60 seconds for a datagram service, other than .CR bootp , .CR rpc , or .CR tftp , it assumes that the server is failing to handle the connection. To avoid entering a potentially infinite loop, .CR inetd issues this message, discards the packet requesting the socket connection, and refuses further connections for this service. After 10 minutes, .CR inetd tries to reinstate the service, and once again accepts connections for the service. .PP .IC service/protocol ": socket: \&" message .br .IC service/protocol ": listen: \&" message .br .IC service/protocol ": getsockname: \&" message .IP Any one of the three errors above makes the service unusable. For another host to communicate with the server host through this service, the Internet daemon needs to be reconfigured after any of these error messages. .PP .IC service/protocol ": bind: \&" message .IP If this error occurs, the service is temporarily unusable. After 10 minutes, .CR inetd tries again to make the service usable by binding to the Internet socket for the service. .PP .IC service/protocol ": Access denied to \&" remote_host " (" address ) .IP The remote host failed to pass the security test for the indicated service. This information can be useful when trying to determine if someone is repeatedly trying to access your system from a particular remote system (in other words, trying to break into your system). This message is logged at the .B warning log level. .PP .IC service/protocol ": Connection from \&" remote_host " (" address ) .IP When connection logging is enabled, this message indicates a successful connection attempt to the specified service. This message is logged at the .B notice log level. .PP .IC service/protocol ": Added service, server \&" executable .IP Keeps track of the services added when reconfiguring the Internet daemon. This message is logged at the .B info log level. .PP .IC service/protocol ": New \&" list .IP Lists the new user IDs, servers or executables used for the service when reconfiguring the Internet daemon. This message is logged at the .B info log level. .PP .IC service/protocol ": Deleted service" .IP Keeps track of the services deleted when reconfiguring the Internet daemon. This message is logged at the .B info log level. .RE .SS Security File (inetd.sec) Errors The following errors, prefixed by .CR /var/adm/inetd.sec: , are related to the security file .CR inetd.sec : .RS .PP .CI "Field contains other characters in addition to * for \&" service .IP For example, field 2 of the Internet address .CR 10.5*.8.7 is incorrect. .PP .CI "Missing low value in range for \&" service .IP For example, field 2 of the Internet address .CR 10.\-5.8.7 is incorrect. .PP .CI "Missing high value in range for \&" service .IP For example, field 2 of the Internet address .CR 10.5\-.8.7 is incorrect. .PP .CI "High value in range is lower than low value for \&" service .IP For example, field 2 of the Internet address .CR 10.5\-3.8.7 is incorrect. .PP .CI "allow/deny field does not have a valid entry for \&" service .IP The entry in the allow/deny field is not one of the keywords .CR allow or .CR deny . No security for this service is implemented by .CR inetd since the line in the security file is ignored. This message is logged at the .B warning log level. .RE .SS RPC Related Errors for NFS Users These errors are specific to RPC-based servers: .RS .PP .CI "/etc/inetd.conf: line \&" number ": Missing program number" .br .CI "/etc/inetd.conf: line \&" number ": Missing version number" .IP Error on the specified line of .CR /etc/inetd.conf . The program or version number for an RPC service is missing. This error does not stop the Internet daemon from reading the rest of the file and configuring itself accordingly. However, the service corresponding to the error message will not be configured correctly. .IP .I Next step: Fix the line with the error, then reconfigure the Internet daemon by executing the .CR "inetd \-c command. .PP .CI "/etc/inetd.conf: line \&" number ": Invalid program number" .IP Error on the specified line of .CR /etc/inetd.conf . The program number for an RPC service is not a number. This error does not stop the Internet daemon from reading the rest of the file and configuring itself accordingly. However, the service corresponding to the error message will not be correctly configured. .IP .I Next step: Fix the line with the error, then reconfigure the Internet daemon by executing the .CR "inetd \-c" command. .RE .SH AUTHOR .CR inetd was developed by HP and the University of California, Berkeley. .PP NFS was developed by Sun Microsystems, Inc. .SH FILES .PD 0 .TP 30 .CR /etc/inetd.conf List of Internet server processes. .TP .CR /var/adm/inetd.sec Optional security file. .PD .SH SEE ALSO umask(1), portmap(1M), syslogd(1M), getservent(3N), inetd.conf(4), inetd.sec(4), protocols(4), services(4), environ(5). .\" .\" index@\f4inetd\f1 \- Internet services daemon@@@\f3inetd(1M)\f1 .\" index@Internet services daemon@@@\f3inetd(1M)\f1 .\" index@services daemon, Internet@@@\f3inetd(1M)\f1 .\" index@daemon, Internet services@@@\f3inetd(1M)\f1 .\" .\" toc@\f3inetd(1M)\f1:\0\0\f4inetd\f1@@@Internet services daemon .\" $Header: init.1m,v 72.7 94/11/14 15:22:45 ssa Exp $ .TA i .TH init 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME init \- process control initialization .SH SYNOPSIS .CR /sbin/init .RC [ 0 \(or 1 \(or 2\c .RC \(or 3 \(or 4 \(or 5\c .RC \(or 6 \(or S \(or s\c .RC \(or Q \(or q \(or a\c .RC \(or b \(or c ] .SH DESCRIPTION The .CR init daemon and command is a general process spawner. Its primary role is to create processes from a script stored in the file .CR /etc/inittab (see .IR inittab (4)). This file usually has .CR init spawn a .CR getty on each line where users can log in. It also controls autonomous processes required by any particular system. .PP At boot time, .CR init is started as a system daemon. .PP While the system is running, a user-spawned .CR init directs the actions of the boot .CR init . It accepts a one-character argument and signals the boot .CR init with the .CR kill() system call to perform the appropriate action. .PP The arguments have the following effect: .RS .TP 10 .CR 0 \(mi 6 Place the system in one of the run levels .CR 0 through .CR 6 . .TP .CR a \(or b \(or c Process the .CR inittab entries that have the special "run level" .CR a , .CR b , or .CR c , without changing the numeric run level. .TP .CR Q \(or q Re-examine the .CR inittab entries without changing the run level. .TP .CR S \(or s Enter the single-user environment. When this level change occurs, the logical system console .CR /dev/syscon is changed to the terminal from which the command was executed. .RE .PP Boot .CR init considers the system to be in a .B run level at any given time. A run level can be viewed as a software configuration of the system, where each configuration allows only a selected group of processes to exist. The processes spawned by boot .CR init for each of these run levels are defined in the .CR inittab file. Boot .CR init can be in one of eight run levels, .CR 0 \(mi 6 , and .CR S or .CR s . The run level is changed by having a privileged user run the .CR init command. This user-spawned .CR init sends appropriate signals to the boot .CR init . .PP Boot .CR init is invoked inside the HP-UX system as the last step in the boot procedure. Boot .CR init first performs any required machine-dependent initialization, such as setting the system context (see .IR context (5)). Next, boot .CR init looks for the .CR inittab file to see if there is an entry of the type .CR initdefault (see .IR inittab (4)). If an .CR initdefault entry is found, boot .CR init uses the run level specified in that entry as the initial run level to enter. If this entry is not in .CR inittab , or .CR inittab is not found, boot .CR init requests that the user enter a run level from the logical system console, .CR /dev/syscon . If .CR S or .CR s is entered, boot .CR init goes into the .B single-user level. This is the only run level that does not require the existence of a properly formatted .CR inittab file. If .CR inittab does not exist, then by default the only legal run level that boot .CR init can enter is the single-user level. .PP In the single-user level, the logical system console terminal .CR /dev/syscon is opened for reading and writing, and the command .CR /usr/bin/su , .CR /usr/bin/sh , or .CR /sbin/sh is invoked immediately. To exit from the single-user run level, one of two options can be selected: .RS 3 .TP 3 \(bu If the shell is terminated with an end-of-file, boot .CR init reprompts for a new run level. .TP \(bu User .CR init can signal boot .CR init and force it to change the current system run level. .RE .PP When attempting to boot the system, some processes spawned by boot .CR init may send display messages to the system console (depending on the contents of .CR inittab ). If messages are expected but do not appear during booting, it may be caused by the logical system console .RC ( /dev/syscon ) being linked to a device that is not the physical system console .RC ( /dev/systty ). If this occurs, you can force boot .CR init to relink .CR /dev/syscon to .CR /dev/systty by pressing the DEL (delete) key (ASCII 127) on the physical system console. .PP When boot .CR init prompts for the new run level, you can only enter one of the digits .CR 0 through .CR 6 or the letter .CR S or .CR s . If you enter .CR S , boot .CR init operates as previously described in single-user mode with the additional result that .CR /dev/syscon is linked to the user's terminal line, thus making it the logical system console. A message is generated on the physical system console, .CR /dev/systty , identifying the new logical system console. .PP When boot .CR init comes up initially, and whenever it switches out of single-user state to normal run states, it sets the states (see .IR ioctl (2)) of the logical system console, .CR /dev/syscon , to those modes saved in the file .CR /etc/ioctl.syscon . This file is written by boot .CR init whenever single-user mode is entered. If this file does not exist when boot .CR init wants to read it, a warning is printed and default settings are assumed. .PP If .CR 0 through .CR 6 is entered, boot .CR init enters the corresponding run level. Any other input is rejected and a new prompt is issued. If this is the first time boot .CR init has entered a run level other than single-user, boot .CR init first scans .CR inittab for special entries of the type .CR boot and .CR bootwait . These entries are performed \(em provided that the run level entered matches that of the entry \(em before any normal processing of .CR inittab takes place. In this way, any special initialization of the operating system, such as mounting file systems, can take place before users are allowed onto the system. The .CR inittab file is scanned to find all entries that are to be processed for that run level. .PP Run level 2 is usually defined as the "normal" run level, containing all of the terminal processes and daemons that are spawned in the multiuser environment. .PP In a multiuser environment, the .CR inittab file is usually set up so that boot .CR init creates a process for each terminal on the system. .PP For terminal processes, ultimately the shell terminates because of an end-of-file either typed explicitly or generated as the result of hanging up. When boot .CR init receives a child death signal telling it that a process it spawned has died, it records the fact and the reason it died in .CR /etc/utmp and .CR /var/adm/wtmp , if they exist (see .IR who (1)). A history of the processes spawned is kept in .CR /var/adm/wtmp , if it exists. .PP To spawn each process in the .CR inittab file, boot .CR init reads each entry and, for each entry that should be respawned, it forks a child process. After it has spawned all of the processes specified by the .CR inittab file, boot .CR init waits for one of its descendant processes to die, a powerfail signal, or until it is signaled by a user .CR init to change the system's run level. When one of the above three conditions occurs, boot .CR init re-examines the .CR inittab file. New entries can be added to the .CR inittab file at any time. However, boot .CR init still waits for one of the above three conditions to occur. For an instantaneous response, use the .CR "init Q" (or .CR "init q" ) command to wake up boot .CR init to re-examine the .CR inittab file without changing the run level. .PP If boot .CR init receives a powerfail signal .RC ( SIGPWR ) and is not in single-user mode, it scans .CR inittab for special .CR powerfail entries. These entries are invoked (if the run levels permit) before any other processing takes place by boot .CR init . In this way, boot .CR init can perform various cleanup and recording functions whenever the operating system experiences a power failure. Note, however, that although boot .CR init receives .CR SIGPWR immediately after a power failure, boot .CR init cannot handle the signal until it resumes execution. Since execution order is based on scheduling priority, any eligible process with a higher priority executes before boot .CR init can scan .CR inittab and perform the specified functions. .PP When boot .CR init is requested to change run levels via a user .CR init , it sends the warning signal .CR SIGTERM to all processes that are undefined in the target run level. Boot .CR init waits 20 seconds before forcibly terminating these processes with the kill signal .CR SIGKILL . Note that boot .CR init assumes that all these processes (and their descendants) remain in the same process group that boot .CR init originally created for them. If any process changes its process group affiliation with either .CR setpgrp() or .CR setpgrp2() (see .IR setsid (2) and .IR setpgid (2)), it will not receive these signals. (Common examples of such processes are the shells .CR csh and .CR ksh (see .IR csh (1) and .IR ksh (1).) Such processes need to be terminated separately. .PP A user .CR init can be invoked only by users with appropriate privileges. .SH DIAGNOSTICS If boot .CR init finds that it is continuously respawning an entry from .CR inittab more than 10 times in 2 minutes, it will assume that there is an error in the command string, generate an error message on the system console, and refuse to respawn this entry until either 5 minutes have elapsed or it receives a signal from a user .CR init . This prevents boot .CR init from eating up system resources if there is a typographical error in the .CR inittab file or a program is removed that is referenced in .CR inittab. .SH WARNINGS Boot .CR init assumes that processes and descendants of processes spawned by boot .CR init remain in the same process group that boot .CR init originally created for them. When changing init states, special care should be taken with processes that change their process group affiliation, such as .CR csh and .CR ksh . .PP One particular scenario that often causes confusing behavior can occur when a child .CR csh or .CR ksh is started by a login shell. When boot .CR init is asked to change to a run level that would cause the original login shell to be killed, the shell's descendant .CR csh or .CR ksh process does not receive a hangup signal since it has changed its process group affiliation and is no longer affiliated with the process group of the original shell. Boot .CR init cannot kill this .CR csh or .CR ksh process (or any of its children). .PP If a .CR getty process is later started on the same tty as this previous shell, the result may be two processes (the .CR getty and the job control shell) competing for input on the tty. .PP To avoid problems such as this, always be sure to manually kill any job control shells that should not be running after changing init states. Also, always be sure that user .CR init is invoked from the lowest level (login) shell when changing to an init state that may cause your login shell to be killed. .SH FILES .nf .CR /dev/syscon .CR /dev/systty .CR /etc/inittab \" STD .CR /etc/ioctl.syscon .CR /etc/utmp .CR /var/adm/wtmp .fi .SH SEE ALSO csh(1), ksh(1), login(1), sh(1), who(1), getty(1M), ioctl(2), kill(2), setpgid(2), setsid(2), clusterconf(4), inittab(4), utmp(4), context(5). .SH STANDARDS CONFORMANCE .CR init ": SVID2, SVID3" .\" .\" index@\f4init\f1 \- process control initialization@@@\f3init(1M)\f1 .\" index@spawn processes@@@\f3init(1M)\f1 .\" index@processes, spawn@@@\f3init(1M)\f1 .\" index@run level@@@\f3init(1M)\f1 .\" index@single-user mode@@@\f3init(1M)\f1 .\" .\" toc@\f3init(1M)\f1:\0\0\f4init\f1@@@process control initialization .\" $Header: insf.1m,v 78.1 96/04/05 11:21:04 ssa Exp $ .TA i .TH insf 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insf \- install special (device) files .SH SYNOPSIS .CR /sbin/insf .PP .CR /sbin/insf .RC [ \-C .IR class .RI \(or .CR \-d .IR driver ] .RC [ \-D .IR directory ] .RC [ \-e ] .RC [ \-H .IR hw\-path ] .ifn .br .ifn \0\0\0\0 .RC [ \-I .IR instance ] .ift .br .ift \0\0\0\0 .RC [ \-n .IR npty ] .RC [ \-q \(or \-v ] .RC [ \-s .IR nstrpty ] .ifn .br .ifn \0\0\0\0 .RC [ \-p .IC first\-optical\-disk : last\-optical\-disk\f1] .SH DESCRIPTION The .CR insf command installs special files in the devices directory, normally .CR /dev . If required, .CR insf creates any subdirectories that are defined for the resulting special file. .PP If no options are specified, special files are created for all new devices in the system. New devices are those devices for which no special files have been previously created. A subset of the new devices can be selected with the .CR \-C , .CR \-d , and .CR \-H options. .PP With the .CR \-e option, .CR insf reinstalls the special files for pseudo-drivers and existing devices. This is useful for restoring special files when one or more have been removed. .PP Normally, .CR insf displays a message as the special files are installed for each driver. The .CR \-q (quiet) option suppresses the installation message. The .CR \-v (verbose) option displays the installation message and the name of each special file as it is created. .SS Options .CR insf recognizes the following options. .RS .TP 15 .CI \-C \0class Match devices that belong to a given device class, .IR class . Device classes can be listed with the .CR lsdev command (see .IR lsdev (1M)). They are defined in the files in the directory .CR /usr/conf/master.d . The special class .CR pseudo includes all pseudo-drivers. This option cannot be used with .CR \-d . .TP .CI \-d \0driver Match devices that are controlled by the specified device driver, .IR driver . Device drivers can be listed with the .CR lsdev command (see .IR lsdev (1M)). They are defined in the files in the directory .CR /usr/conf/master.d . This option cannot be used with .CR \-C . .TP .CI \-D \0directory Override the default device installation directory .CR /dev and install the special files in .I directory instead. .I directory must exist; otherwise, .CR insf displays an error message and exits. See WARNINGS. .TP .CR \-e Reinstall the special files for pseudo-drivers and existing devices. This is useful for restoring special files if one or more have been removed. .TP .CI \-H \0hw\-path Match devices at a given hardware path, .IR hw\-path . Hardware paths can be listed with the .CR ioscan command (see .IR ioscan (1M)). A hardware path specifies the addresses of the hardware components leading to a device. It consists of a string of numbers separated by periods .RC ( . ), such as .CR 52 (a card), .CR 52.3 (a target address), and .CR 52.3.0 (a device). If a hardware component is a bus converter, the following period, if any, is replaced by a slash .RC ( / ) as in .CR 2 , .CR 2/3 , and .CR 2/3.0 . .IP If the specified path contains fewer numbers than are necessary to reach a device, special files are made for all devices at addresses that extend the given path. If the specified path is .CR 56 , then special files are made for the devices at addresses .CR 56.0 , .CR 56.1 , .CR 56.2 , etc. .TP .CI \-I \0instance Match a device with the specified .I instance number. Instances can be listed with the .CR \-f option of the .CR ioscan command (see .IR ioscan (1M)). .IP This option is effective only if the .CR \-e option is specified or if an appropriate device class or driver is specified with a .CR \-C or .CR \-d option. .TP .CI \-n \0npty Install .I npty special files for each specified .CR ptym and .CR ptys driver. The .CR pty driver specifies both the .CR ptym and .CR ptys drivers. .I npty is a decimal number. .IP This option is effective only if the .CR \-e option is specified or if an appropriate device class or driver is specified with a .CR \-C or .CR \-d option. .IP If this option is omitted, .I npty defaults to 60 for the .CR ptym and .CR ptys drivers. .TP .CI \-p \0first\-optical\-disk : last\-optical\-disk Install the special files for those optical disks located in slots in the range .I first\-optical\-disk to .IR last\-optical\-disk . The two variables can have values from the set .CR 1a , .CR 1b , \&..., .CR 32a , .CR 32b . This option only applies to the .CR autox0 and .CR schgr drivers. If it is omitted, the 64 special files for both sides of 32 optical disks .RC ( 1a through .CR 32b ) will be installed. .TP .CR \-q Quiet option. Normally, .CR insf displays a message as each driver is processed. This option suppresses the driver message, but not error messages. See the .CR \-v option. .TP .CI \-s \0nstrpty Install .I nstrpty slave-side stream special files for the .CR pts driver. .I nstrpty is a decimal number. This option only applies to the .CR pts special file installation. .IP This option is effective only if the .CR \-e option is specified or if an appropriate device class or driver is specified with a .CR \-C or .CR \-d option. .IP If this option is omitted, .IR nstrpty defaults to 60. .TP .CR \-v Verbose option. In addition to the normal processing message, display the name of each special file as it is created. See the .CR \-q option. .RE .SS Naming Conventions Many special files are named using the .CI c card t target d device naming convention. These variables have the following meaning wherever they are used. .RS .TP 10 .I card The unique interface card identification number from .CR ioscan (see .IR ioscan (1M)). It is represented as a decimal number with a typical range of 0 to 255. .TP .I target The device target number, for example the address on a HP-FL or SCSI bus. It is represented as a decimal number with a typical range of 0 to 15. .TP .I device A address unit within a device, for example, the unit in a HP-FL device or the LUN in a SCSI device. It is represented as a decimal number with a typical range of 0 to 15. .SS Special Files This subsection shows which special files are created and the permissions for each device driver. .PP The special file names are relative to the installation directory, normally .CR /dev . This directory may be overridden with the .CR \-D option. .PP .CR insf sets the file permissions and the owner and group IDs. They are shown here in a format similar to that of the .CR ll command: .RS 16 .TP 20 .I special\-file .I permissions .I owner .I group .RE .PP For example: .RS 16 .TP 20 .CR tty .CR "rw\-rw\-rw\-\ bin\ bin" .RE .sp .ne 7 .TP 16 .B Device Driver .B Special Files and Description .TP .CR asio0 For each card instance, the following special files are installed: .RS .TP 20 .CI tty card p0 .CR "rw\-\-w\-\-w\-\ bin\ bin" .br Direct connect .RE .TP .CR asyncdsk The following special file is installed: .RS .TP 20 .CR asyncdsk .CR "rw\-rw\-rw\-\ bin\ bin" .RE .TP .CR audio The following special files are installed. Note the underscore .RC ( _ ) before .I card in each special file name. .IP For .IR card 0, the device files are linked to files without the trailing .CR _0 in their names. .RS .TP 20 .CI audio_ card .CR rw\-rw\-rw\-\ bin\ bin .br Default audio device .TP .CI audioCtl_ card .CR rw\-rw\-rw\-\ bin\ bin .br Audio control device .TP .CI audioBA_ card .CR rw\-rw\-rw\-\ bin\ bin .br All outputs, A-law format .TP .CI audioBL_ card .CR rw\-rw\-rw\-\ bin\ bin .br All outputs, 16-bit linear format .TP .CI audioBU_ card .CR rw\-rw\-rw\-\ bin\ bin .br All outputs, Mu-law format .TP .CI audioEA_ card .CR rw\-rw\-rw\-\ bin\ bin .br External output, A-law format .TP .CI audioEL_ card .CR rw\-rw\-rw\-\ bin\ bin .br External output, 16-bit linear format .TP .CI audioEU_ card .CR rw\-rw\-rw\-\ bin\ bin .br External output, Mu-law format .TP .CI audioIA_ card .CR rw\-rw\-rw\-\ bin\ bin .br Internal speaker output, A-law format .TP .CI audioIL_ card .CR rw\-rw\-rw\-\ bin\ bin .br Internal speaker output, 16-bit linear format .TP .CI audioIU_ card .CR rw\-rw\-rw\-\ bin\ bin .br Internal speaker output, Mu-law format .TP .CI audioLA_ card .CR rw\-rw\-rw\-\ bin\ bin .br Line output, A-law format .TP .CI audioLL_ card .CR rw\-rw\-rw\-\ bin\ bin .br Line output, 16 bit linear format .TP .CI audioLU_ card .CR rw\-rw\-rw\-\ bin\ bin .br Line output, Mu-law format .TP .CI audioNA_ card .CR rw\-rw\-rw\-\ bin\ bin .br No output, A-law format .TP .CI audioNL_ card .CR rw\-rw\-rw\-\ bin\ bin .br No output, 16 bit linear format .TP .CI audioNU_ card .CR rw\-rw\-rw\-\ bin\ bin .br No output, Mu-law format .RE .TP .C "autox0 schgr" Special file names for .CR autox0 and .CR schgr use the format: .IP .CI c card t target d device\fP\s+1_\s0\f2surface .IP .IR surface : .CR 1a through .CR 32b , unless modified by the .CR \-p option. Note the underscore .RC ( _ ) between .I device and .IR surface . .IP For each autochanger device, the following special files are installed: .RS .TP 35 .CI ac/c card t target d device\fP\s+1_\s0\f2surface .CR rw\-r\-\-\-\-\-\ bin\ sys .br Block entry .TP .CI rac/c card t target d device\fP\s+1_\s0\f2surface .CR rw\-r\-\-\-\-\-\ bin\ sys .br Character entry .TP .CI rac/c card t target d device .CR rw\-\-\-\-\-\-\-\ bin\ sys .br Character entry .RE .TP .CR beep The following special file is installed: .RS .TP 20 .CR beep .CR rw\-rw\-rw\-\ bin\ bin .RE .TP .CR CentIf For each card instance, the following special file is installed. .RS .TP 30 .CI c card t target d device\fP\s+1_lp\s0 .CR rw\-rw\-rw\-\ lp\ bin .br Handshake mode 2, character entry .RE .TP .CR cn The following special files are installed: .RS .TP 20 .CR syscon .CR rw\-\-w\-\-w\-\ bin\ bin .TP .CR systty .CR rw\-\-w\-\-w\-\ bin\ bin .TP .CR console .CR rw\-\-w\-\-w\-\ root\ sys .TP .CR ttyconf .CR rw\-\-\-\-\-\-\-\ root\ sys .RE .TP .C "cs80 disc1 disc2 disc3 disc4 sdisk" For each disk device, the following special files are installed: .RS .TP 35 .CI dsk/c card t target d device .CR rw\-r\-\-\-\-\-\ bin\ sys .br Block entry .TP .CI rdsk/c card t target d device .CR rw\-r\-\-\-\-\-\ bin\ sys .br Character entry .PP For .CR disc1 and .CR disc2 instances, the following additional special file is installed: .TP 35 .CI diag/rdsk/c card t target d device .CR rw\-\-\-\-\-\-\-\ bin\ bin .br Character entry .PP For .CR cs80 and .CR disc1 instances, the following additional special files are installed: .TP 35 .CI ct/c card t target d device .CR rw\-r\-\-\-\-\-\ bin\ sys .br Block entry .TP .CI rct/c card t target d device .CR rw\-r\-\-\-\-\-\ bin\ sys .br Character entry .PP For .CR disc1 instances, the following additional special file is installed: .TP 35 .CI diag/rct/c card t target d device .CR rw\-\-\-\-\-\-\-\ bin\ bin .br Character entry .PP For .CR disc3 instances, the following additional special files are installed: .TP 35 .CI floppy/c card t target d device .CR rw\-r\-\-\-\-\-\ bin\ sys .br Block entry .TP .CI rfloppy/c card t target d device .CR rw\-r\-\-\-\-\-\ bin\ sys .br Character entry .RE .TP .CR devconfig The following special file is installed: .RS .TP 20 .CR config .CR rw\-r\-\-\-\-\-\ root\ sys .RE .TP .CR diag0 The following special file is installed: .RS .TP 20 .CR diag/diag0 .CR rw\-\-\-\-\-\-\-\ bin\ bin .RE .TP .CR diag1 The following special file is installed: .RS .TP 20 .CR diag/diag1 .CR rw\-\-\-\-\-\-\-\ bin\ bin .RE .TP .CR diag2 The following special files are installed: .RS .TP 20 .CR diag2 .CR rw\-\-\-\-\-\-\-\ bin\ bin .TP .CR diag/diag2 .CR rw\-\-\-\-\-\-\-\ bin\ bin .RE .TP .CR diaghpib1 For each device, the following special files are installed: .RS .TP 35 .CI diag/hpib/hp28650A/ instance .CR rw\-\-\-\-\-\-\-\ bin\ bin .RE .TP .C "disc1 disc2 disc3 disc4" See .CR cs80 . .TP .CR dlpi The following special files are installed: .RS .TP 20 .CR dlpi .CR rw\-rw\-rw\-\ root\ sys .TP .CR dlpi0 .CR rw\-rw\-rw\-\ root\ sys .TP .CR dlpi1 .CR rw\-rw\-rw\-\ root\ sys .TP .CR dlpi2 .CR rw\-rw\-rw\-\ root\ sys .TP .CR dlpi3 .CR rw\-rw\-rw\-\ root\ sys .TP .CR dlpi4 .CR rw\-rw\-rw\-\ root\ sys .RE .TP .CR dmem The following special file is installed: .RS .TP 20 .CR dmem .CR rw\-\-\-\-\-\-\-\ bin\ bin .RE .TP .CR echo The following special file is installed: .RS .TP 20 .CR echo .CR rw\-rw\-rw\-\ root\ sys .RE .TP .CR eisa_mux0 For each instance of an eisa_mux card, the following special files are installed: .RS .TP 20 .CI tty card letter port .CR rw\-\-w\-\-w\-\ bin\ bin .br .br .IR letter : .CR a to .CR p, module index .br .IR port : .CR 1 to .CR 16 , direct connect .TP .CI mux card .CR rw\-\-\-\-\-\-\-\ bin\ bin .TP .CI diag/mux card .CR rw\-\-\-\-\-\-\-\ bin\ bin .TP .CI diag/mux card _1 .CR rw\-\-\-\-\-\-\-\ bin\ bin .TP .CI diag/mux card _2 .CR rw\-\-\-\-\-\-\-\ bin\ bin .RE .TP .CR fddi The following special file is installed: .RS .TP 20 .CI lan card .CR rw\-rw\-rw\-\ bin\ bin .RE .TP .CR framebuf For each graphics device, the following special files are installed. .RS .TP 20 .CI crt device_number .CR rw\-rw\-rw\-\ bin\ bin .TP .CI ocrt device_number .CR rw\-rw\-rw\-\ bin\ bin .RE .IP .I device_number is 0 indexed and is assigned in the order in which the devices appear in .IR ioscan(1m) output. .IP If the console device is a graphics device, the files .CR crt and .CR ocrt are created as the console device. If the console is not a graphics device, .CR crt and .CR ocrt are identical to .CR crt0 and .CR ocrt0. .TP .CR hil For each device, the following special files are installed. Note the underscore .RC ( _ ) before .I card in each special file name. .IP For .IR card 0, the device files are linked to files named .CI hil addr for the link addresses 1 to 7; .CR hilkbd for the cooked keyboard device; and .CR rhil for the .CR hil controller device. .RS .TP 20 .CI hil_ card . addr .CR rw\-rw\-rw\-\ bin\ bin .br .IR addr : link addresses .CR 1 to .CR 7 .TP .CI hilkbd_ card .CR rw\-rw\-rw\-\ bin\ bin .TP .CI rhil_ card .CR rw\-rw\-rw\-\ bin\ bin .RE .TP .CR inet_clts The following special file is installed: .RS .TP 20 .CR inet_clts .CR rw\-rw\-rw\-\ root\ sys .RE .TP .CR inet_cots The following special file is installed: .RS .TP 20 .CR inet_cots .CR rw\-rw\-rw\-\ root\ sys .RE .TP .CR instr0 For each card instance, the following special files are installed: .RS .TP 30 .CI hpib/c card .CR rw\-rw\-rw\-\ bin\ bin .TP .CI hpib/c card t addr d0 .CR rw\-rw\-rw\-\ bin\ bin .br .IR addr : .CR 0 to .CR 30 .TP .CI diag/hpib/c card .CR rw\-\-\-\-\-\-\-\ bin\ bin .RE .TP .CR kepd The following special file is installed: .RS .TP 20 .CR kepd .CR rw\-r\-\-r\-\-\ root\ other .RE .TP .CR klog The following special file is installed: .RS .TP 20 .CR klog .CR rw\-\-\-\-\-\-\-\ bin\ bin .RE .TP .C "lan0 lan1 lan2 lan3" For each card instance, the following special files are installed: .RS .TP 20 .CI lan card .CR rw\-rw\-rw\-\ bin\ bin .TP .CI ether card .CR rw\-rw\-rw\-\ bin\ bin .TP .CI diag/lan card .CR rw\-\-\-\-\-\-\-\ bin\ bin .RE .TP .CR lantty0 For each card instance, the following special files are installed: .RS .TP 30 .CI lantty card .CR rw\-rw\-rw\-\ bin\ bin .br Normal access .TP .CI diag/lantty card .CR rw\-rw\-rw\-\ bin\ bin .br Exclusive access .RE .TP .C "lpr0 lpr1 lpr2 lpr3" For each card instance, the following special files are installed: .RS .TP 35 .CI c card t target d device\fP\s+1_lp\s0 .CR rw\-\-\-\-\-\-\-\ lp\ bin .PP .TP 35 .CI diag/c card t target d device\fP\s+1_lp\s0 .CR rw\-\-\-\-\-\-\-\ bin\ bin .RE .TP .CR mm The following special files are installed: .RS .TP 20 .CR mem .CR rw\-r\-\-\-\-\-\ bin\ sys .br Minor .CR 0 .TP .CR kmem .CR rw\-r\-\-\-\-\-\ bin\ sys .br Minor .CR 1 .TP .CR null .CR rw\-rw\-rw\-\ bin\ bin .br Minor .CR 2 .RE .TP .CR mux0 For each instance of a 6-channel card, the following special files are installed: .RS .TP 20 .CI tty card p port .CR rw\-\-w\-\-w\-\ bin\ bin .br .IR port : .CR 0 to .CR 5 , direct connect .TP .CI mux card .CR rw\-\-\-\-\-\-\-\ bin\ bin .TP .CI diag/mux card .CR rw\-\-\-\-\-\-\-\ bin\ bin .PP For each instance of a 16-channel card, the following special files are installed: .TP 20 .CI tty card p port .CR rw\-\-w\-\-w\-\ bin\ bin .br .IR port : .CR 0 to .CR 15 , direct connect .TP .CI mux card .CR rw\-\-\-\-\-\-\-\ bin\ bin .TP .CI diag/mux card .CR rw\-\-\-\-\-\-\-\ bin\ bin .RE .TP .CR mux2 For each instance of an 16-channel card, the following special files are installed: .RS .TP 20 .CI tty card p port .CR rw\-\-w\-\-w\-\ bin\ bin .br .IR port : .CR 0 to .CR 15 , direct connect .TP .CI mux card .CR rw\-\-\-\-\-\-\-\ bin\ bin .TP .CI diag/mux card .CR rw\-\-\-\-\-\-\-\ bin\ bin .PP For each card instance of an 8-channel card, the following special files are installed: .TP 20 .CI tty card p port .CR rw\-\-w\-\-w\-\ bin\ bin .br .IR port : .CR 0 to .CR 7 , direct connect .TP .CI mux card .CR rw\-\-\-\-\-\-\-\ bin\ bin .TP .CI diag/mux card .CR rw\-\-\-\-\-\-\-\ bin\ bin .PP For each card instance of an 3-channel card, the following special files are installed: .TP 20 .CI tty card p port .CR rw\-\-w\-\-w\-\ bin\ bin .br .IR port : .CR 0 , .CR 1 , and .CR 7 , direct connect .TP .CI mux card .CR rw\-\-\-\-\-\-\-\ bin\ bin .TP .CI diag/mux card .CR rw\-\-\-\-\-\-\-\ bin\ bin .RE .TP .CR mux4 For each card instance, the following special files are installed: .RS .TP 20 .CI tty card p port .CR rw\-\-w\-\-w\-\ bin\ bin .br .IR port : .CR 0 and .CR 1 , direct connect .RE .TP .C "pflop sflop" For each card instance, the following special files are installed: .RS .TP 35 .CI floppy/c card t target d device .CR rw\-r\-\-\-\-\-\ bin\ sys .br Block entry .TP .CI rfloppy/c card t target d device .CR rw\-r\-\-\-\-\-\ bin\ sys .br Character entry .RE .TP .CR ps2 The following special files are installed: .RS .TP 20 .CR ps2kbd .CR rw\-rw\-rw\-\ bin\ bin .br Autosearch for first ps2 keyboard .TP .CR ps2mouse .CR rw\-rw\-rw\-\ bin\ bin .br Autosearch for first ps2 mouse .TP .CR ps2_0 .CR rw\-rw\-rw\-\ bin\ bin .br ps2 port 0 .TP .CR ps2_1 .CR rw\-rw\-rw\-\ bin\ bin .br ps2 port 1 .RE .TP .CR ptm The following special file is installed: .RS .TP 20 .CR ptmx .CR rw\-rw\-rw\-\ root\ sys .RE .TP .CR pts The following special files are installed: .RS .TP 20 .CI pts/ number .CR rw\-rw\-rw\-\ root\ sys .br .IR number : .CR 0 to .CR 59 .RE .TP .CR pty Specifying this driver tells .CR insf to install the special files for both the master and slave pty drivers, .CR ptym and .CR ptys . The command .CR "insf -d pty" is equivalent to the two commands .CR "insf -d ptym; insf -d ptys" . .TP .CR ptym The following special files are installed: .RS .TP 30 .CR ptym/clone .CR rw\-r\-\-r\-\-\ root\ other .TP .CI ptym/pty index\|number .CR rw\-rw\-rw\-\ bin\ bin .br .IR index : .CR p to .CR z , .CR a to .CR c , .CR e to .CR o ; .IR number : .CR 0 to .CR f (hexadecimal) .IP The first 48 special files .CR ptym/pty* are linked to .CR pty* . .TP .CI ptym/pty index\|number .CR rw\-rw\-rw\-\ bin\ bin .br .IR index : .CR p to .CR z , .CR a to .CR c , .CR e to .CR o ; .IR number : .CR 00 to .CR 99 .TP .CI ptym/pty index\|number .CR rw\-rw\-rw\-\ bin\ bin .br .IR index : .CR p to .CR z , .CR a to .CR c , .CR e to .CR o ; .IR number : .CR 000 to .CR 999 .RE .TP .CR ptys The following special files are installed: .RS .TP 30 .CI pty/tty index\|number .CR rw\-rw\-rw\-\ bin\ bin .br .IR index : .CR p to .CR z , .CR a to .CR c , .CR e to .CR o ; .IR number : .CR 0 to .CR f (hexadecimal) .IP The first 48 special files .CR pty/tty* are linked to .CR tty* . .TP .CI pty/tty index\|number .CR rw\-rw\-rw\-\ bin\ bin .br .IR index : .CR p to .CR z , .CR a to .CR c , .CR e to .CR o ; .IR number : .CR 00 to .CR 99 .TP .CI pty/tty index\|number .CR rw\-rw\-rw\-\ bin\ bin .br .IR index : .CR p to .CR z , .CR a to .CR c , .CR e to .CR o ; .IR number : .CR 000 to .CR 999 .RE .TP .CR root The following special files are installed: .RS .TP 20 .CR root .CR rw\-r\-\-\-\-\-\ bin\ sys .TP .CR rroot .CR rw\-r\-\-\-\-\-\ bin\ sys .RE .TP .CR sad The following special file is installed: .RS .TP 20 .CR sad .CR rw\-rw\-rw\-\ root\ sys .RE .TP .CR schgr See .CR autox0 . .TP .CR sdisk See .CR cs80 . .TP .CR sflop See .CR pflop . .TP .C "stape tape1 tape2" For each driver instance, different special files are installed depending on the number of characters allowed in the target directory. There are two lists below, one for long file name directories and one for short file name directories (14 characters maximum). Short file names are used for files installed on an NFS file system. .IP Note that the first four special files in each list for tape driver instances 0-9 are also linked to .CI rmt/ instance m \f1, .CI rmt/ instance mb \f1, .CI rmt/ instance mn \f1, and .CI rmt/ instance mnb \f1, respectively. .RS .PP For installation in a long file name directory: .TP 35 .CI rmt/c card t target d device\fP\s+1BEST\s0 .CR rw\-rw\-rw\-\ bin\ bin .br AT&T-style, best available density, character entry .TP .CI rmt/c card t target d device\fP\s+1BESTb\s0 .CR rw\-rw\-rw\-\ bin\ bin .br Berkeley-style, best available density, character entry .TP .CI rmt/c card t target d device\fP\s+1BESTn\s0 .CR rw\-rw\-rw\-\ bin\ bin .br AT&T-style, no rewind, best available density, character entry .TP .CI rmt/c card t target d device\fP\s+1BESTnb\s0 .CR rw\-rw\-rw\-\ bin\ bin .br Berkeley-style, no rewind, best available density, character entry .PP For installation in a short file name directory: .TP 35 .CI rmt/c card t target d device\fP\s+1f0\s0 .CR rw\-rw\-rw\-\ bin\ bin .br AT&T-style, best available density, character entry .TP .CI rmt/c card t target d device\fP\s+1f0b\s0 .CR rw\-rw\-rw\-\ bin\ bin .br Berkeley-style, best available density, character entry .TP .CI rmt/c card t target d device\fP\s+1f0n\s0 .CR rw\-rw\-rw\-\ bin\ bin .br AT&T-style, no rewind, best available density, character entry .TP .CI rmt/c card t target d device\fP\s+1f0nb\s0 .CR rw\-rw\-rw\-\ bin\ bin .br Berkeley-style, no rewind, best available density, character entry .PP For both long and short file name directories, the following additional files are created. .TP 35 .CI rmt/ driver_name _config .CR rw\-r\-\-r\-\-\ bin\ bin .br Tape configuration, character entry .TP .CI diag/rmt/c card t target d device .CR rw\-\-\-\-\-\-\-\ bin\ bin .br For .CR tape1 and .CR tape2 only, diagnostic access, character entry .RE .TP .CR strlog The following special file is installed: .RS .TP 20 .CR strlog .CR rw\-rw\-rw\-\ root\ sys .RE .TP .CR sy The following special file is installed: .RS .TP 20 .CR tty .CR rw\-rw\-rw\-\ bin\ bin .RE .TP .CR "tape1 tape2" See .CR stape . .TP .CR token2 The following special file is installed: .RS .TP 20 .CI lan card .CR rw\-rw\-rw\-\ bin\ bin .RE .TP .CR unix_clts The following special file is installed: .RS .TP 20 .CR unix_clts .CR rw\-rw\-rw\-\ root\ sys .RE .TP .CR unix_cots The following special file is installed: .RS .TP 20 .CR unix_cots .CR rw\-rw\-rw\-\ root\ sys .RE .RE .SH RETURN VALUE .CR insf exits with one of the following values: .RS .TP .PD 0 .CR 0 Successful completion, including warning diagnostics. .TP .CR 1 Failure. .PD .RE .SH DIAGNOSTICS Most diagnostic messages from .CR insf are self-explanatory. Listed below are some messages deserving further clarification. .SS Warnings .PP .CI "Device driver \&" name " is not in the kernel" .br .CI "Device class \&" name " is not in the kernel" .IP The indicated device driver or device class is not present in the kernel. A device driver and/or device class can be added to the kernel using .IR config (1M). .PP .CI "No instance number available for device class \&" name .IP All of the instance numbers available for the device class are already assigned. Use the .CR rmsf command to remove any unneeded devices from the system (see .IR rmsf (1M)). .PP .CI "Don't know how to handle driver \&" name " \- no special files created for \&" path .IP .CR insf does not know how to create special files for the specified device driver. Use .CR mknod to create special files for the device (see .IR mknod (1M)). .SH EXAMPLES Install special files for all new devices belonging to the .CR tty device class: .IP .C "insf \-C tty" .PP Install special files to the new device added at hardware path .CR 2/4.0.0 : .IP .C "insf \-H 2/4.0.0" .SH WARNINGS .CR insf should only be run in single-user mode. It can change the mode, owner, or group of an existing special file, or unlink and recreate one; special files that are currently open may be left in an indeterminate state. .PP Many commands and subsystems assume their device files are in .CR /dev , therefore the use of the .CR \-D option is discouraged. .SH AUTHOR .CR insf was developed by HP. .SH FILES .TP 30 .CR /dev/config I/O system special file .TP .CR /etc/ioconfig I/O system configuration database .SH SEE ALSO config(1M), ioscan(1M), lsdev(1M), lssf(1M), mknod(1M), mksf(1M), rmsf(1M). .\" .\" index@\f4insf\f1 \- install special (device) files@@@\f3insf(1M)\f1 .\" index@\f1install special (device) files@@@\f3insf(1M)\f1 .\" index@\f1special (device) files, install@@@\f3insf(1M)\f1 .\" index@\f1files, install special (device)@@@\f3insf(1M)\f1 .\" index@\f1device (special) files, install@@@\f3insf(1M)\f1 .\" .\" toc@\f3insf(1M)\f1:\0\0\f4insf\f1@@@install special (device) files .\" $Header: install.1m,v 72.2 93/11/12 13:08:43 ssa Exp $ .TA i .TH install 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME install \- install commands .SH SYNOPSIS .B /usr/sbin/install .RB [ \|\-c .IR dira\| ] .RB [ \|\-f .IR dirb\| ] .RB [ \|\-i\| ] .RB [ \|\-n .IR dirc\| ] .RB [ \|\-o\| ] .RB [ \|\-g .IR group\| ] .RB [ \|\-s\| ] .RB [ \|\-u .IR user\| ] .I file .RI [ \|dirx \ ...\|] .SH DESCRIPTION .I install is a command most commonly used in ``makefiles'' (see .IR make (1)) to install a .I file (updated target file) in a specific place within a file system. Each .I file is installed by copying it into the appropriate directory, thereby retaining the mode and owner of the original command. The program prints messages telling the user exactly what files it is replacing or creating and where they are going. .PP .I install is useful for installing new commands, or new versions of existing commands, in the standard directories (i.e. .BR /usr/bin , .BR /usr/sbin , etc.). .PP If no options or directories .RI ( dirx .\|.\|.) are given, .I install searches a set of default directories .RB ( /usr/bin , .BR /usr/sbin , .BR /sbin , and .BR /usr/lbin , in that order) for a file with the same name as .IR file . When the first occurrence is found, .I install issues a message saying that it is overwriting that file with .I file (the new version), and proceeds to do so. If the file is not found, the program states this and exits without further action. .PP If one or more directories .RI ( dirx \&.\|.\|.) are specified after .IR file , those directories are searched before the directories specified in the default list. .SS Options Options are interpreted as follows: .RS .TP 15 .BI \-c \ dira Installs a new command .RI ( file ) in the directory specified by .IR dira , only if it is not found. If it is found, .I install issues a message saying that the file already exists, and exits without overwriting it. Can be used alone or with the .B \-s option. .TP .BI \-f \ dirb Forces .I file to be installed in given directory, whether or not one already exists. If the file being installed does not already exist, the mode and owner of the new file will be set to .B 755 and .BR bin , respectively. If the file already exists, the mode and owner will be that of the already existing file. Can be used alone or with the .B \-o or .B \-s options. .TP .B \-i Ignores default directory list, searching only through the given directories .RI ( dirx \&.\|.\|.). Can be used alone or with any other options other than .B \-c and .BR \-f . .TP 15 .BI \-n \ dirc If .I file is not found in any of the searched directories, it is put in the directory specified in .IR dirc . The mode and owner of the new file will be set to .B 755 and .BR bin , respectively. Can be used alone or with any other options other than .B \-c and .BR \-f . .TP .B \-o If .I file is found, this option saves the ``found'' file by copying it to .BI \s-1OLD\s0 file in the directory in which it was found. This option is useful when installing a normally busy text file such as .B /usr/bin/sh or .BR /usr/sbin/getty , where the existing file cannot be removed. Can be used alone or with any other options other than .BR \-c . .TP .BI \-g \ group Causes .I file to be owned by group .IR group . This option is available only to users who have appropriate privileges. Can be used alone or with any other option. .TP .BI \-u \ user Causes .I file to be owned by user .IR user . This option is available only to users who have appropriate privileges. Can be used alone or with any other option. .TP .B \-s Suppresses printing of messages other than error messages. Can be used alone or with any other options. .RE .PP When no directories are specified .RI ( dirx \&.\|.\|.), or when .I file cannot be placed in one of the directories specified, .I install checks for the existence of the file .BR /etc/syslist . If .B /etc/syslist exists, it is used to determine the final destination of .IR file . If .B /etc/syslist does not exist, the default directory list is further scanned to determine where .I file is to be located. .PP The file .B /etc/syslist contains a list of absolute pathnames, one per line. The pathname is the "official" destination (for example .BR /usr/bin/echo ) of the file as it appears on a file system. The file .B /etc/syslist serves as a master list for system command destinations. If there is no entry for .I file in the file .B /etc/syslist the default directory list is further scanned to determine where .I file is to be located. .SS Cross Generation The environment variable .SM .B ROOT is used to locate the locations file (in the form .SM .BR $ROOT\s0/etc/syslist ). This is necessary in cases where cross generation is being done on a production system. Furthermore, each pathname in .SM .B $ROOT\s0/etc/syslist is appended to .SM .B $ROOT (for example, .SM .BR $ROOT\s0/usr/bin/echo ), and used as the destination for .IR file . Also, the default directories are also appended to .SM .B $ROOT so that the default directories are actually .SM .BR $ROOT\s0/usr/bin , .SM .BR $ROOT\s0/usr/sbin , .SM .BR $ROOT\s0/sbin , and .SM .BR $ROOT\s0/usr/lbin . .PP The file .B /etc/syslist .RB ( \s-1$ROOT\s0/etc/syslist ) does not exist on a distribution tape; it is created and used by local sites. .SH WARNINGS .I install cannot create alias links for a command (for example, .IR vi (1) is an alias link for .IR ex (1)). .SH SEE ALSO make(1), cpset(1M). .\" .\" index@\f2install\f1 \- install new commands@@@\f3install(1M)\f1 .\" index@add new commands to system@@@\f3install(1M)\f1 .\" index@commands, install new@@@\f3install(1M)\f1 .\" index@new commands, install@@@\f3install(1M)\f1 .\" .\" toc@\f3install(1M)\f1:\0\0\f2install\f1@@@install commands .\" .\" fileset_database@install.1m@SYS-ADMIN-MAN .\" $Header: instl_adm.1m,v 76.1 95/07/05 17:32:08 ssa Exp $ .TA i .TH instl_adm 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME instl_adm \- maintain network install configuration and default parameters .SH SYNOPSIS .C instl_adm .RC [ \|-d\| ] .RC [ \|-F .IR filesystem | LIF-vol\| ] .RC [ \|-h .IR hostname\| ] .RC [ \|-s .IR SD-server [: depot-dir ]] .RC [ \|-g .IR gateway\| ] .RC [ \|-m .IR netmask\| ] .RC [ \|-t .IR install-tftp-server\| ] .RC [ \|-a .IR msg-file | -\| ] .PP .C instl_adm .RC [ \|-d\| ] .RC [ \|-c\| ] .RC [ \|-f .IR config-file\| ] .RC [ \|-F .IR filesystem | LIF-vol\| ] .PP .C instl_adm .C -T .RC [ \|-f .IR config-file\| ] .PP .C instl_adm .RC [ \|-b\| ] .RC [ \|-F .IR filesystem | LIF-vol\| ] .SH DESCRIPTION .C instl_adm is used on a network install boot server to set, modify, or display the default parameters used when a client connects to the server to install the .SM HP-UX operating system. .C instl_adm can be used to specify the network parameters using the .C -h -s -g -m -t options. An informative message can be given to install users by using the .C -a option. More complex configuration parameters can be stored in a .I config-file and applied or tested by using the .C -f and .C -T options. (See .IR instl_adm (4) for details on the syntax of .IR config-file ). .SS Options .C instl_adm recognizes the following options: .RS .TP 15 .C \-d Display the current configuration. The format of this information is described in the .IR instl_adm (4) man page. .IP The standard-output resulting from the .C -d option can be stored in a file, edited, and re-applied using the .C -f option. .TP .CI \-F \0filesystem \f1| \f2LIF-vol\f1 Specifies that .C instl_adm should modify/display the configuration as stored in .I filesystem or .I LIF-vol. See .SM FILES below for the default file system file that .C instl_adm operates on. If .I filesystem or .I LIF-vol is a file system image, .C instl_adm will save the configuration in the first 8KB of that image. If the file is a LIF volume (like a bootable tape image), and the .C -c option is not given, then .C instl_adm will operate on the first 8KB of the LIF file named .CR INSTALLFS . If the file is a LIF file and the .I -c option is given, then the LIF file named .C CONFIG will be operated on in totality. .TP .CI \-h \0hostname Specifies the default hostname to be supplied to the install user for his or her system during a network install. The IP address of the .I hostname given is determined and stored along with the hostname. If .I hostname is given as an IP address, then the hostname is looked up and stored as the default. Use this option only if a specific hostname and Internet address is reserved for install purposes. This should be a temporary Internet address used only during installs. Once the install client has its system installed, it must be assigned its own unique Internet address. .IP Supplying this default is not recommended if multiple installs are to be done simultaneously because only one active host can occupy a given Internet address at any given time. .TP .CI \-s \0SD-server\f1[:\f2depot-dir\f1]\f1 Specifies the default Software Distributor server and depot directory that is to be used during the install as the source for the .IR swinstall (1M) command. The .I SD-server must have the HP-UX operating system loaded into .I depot-dir using the .IR swcopy (1M) command prior to attempting an installation. .IP If either the .I SD-server or .I depot-dir element of the source is omitted, then the previously set element (if any) will be retained. .TP .CI \-g \0gateway Specifies the default Internet address for the gateway system through which the client system can reach the .I install-tftp-server and the .I SD-server system (see .IR route (1M)). .IP If no default .I gateway is given, then the default will be the same as the client host's IP address, in which case wild-card routing will be performed (on networks that support it). .TP .CI \-m \0netmask Specifies the default netmask for the client system to use in reaching the install and SD server systems. This is necessary if your network uses sub-networks. The netmask is the same as that supplied to the .C ifconfig command (see .IR ifconfig (1M)). .I netmask can be supplied either in dot-notation (for example, .CR 255.255.248.0 ) or as a hexadecimal number with a leading 0x (such as, .CR 0xfffff80 ). .TP .CI \-t \0install-tftp-server Specifies the default system to be used as the install server. The .I install-tftp-server is normally the same as system that is being used as the boot-server (which is normally the same as the system on which .I instl_adm is run). .I install-tftp-server is a system that has the HPUX-Install.FILE-SERV-HPPA fileset loaded and that is configured with .IR tftp (1) access to the files listed under .SM FILES . .TP .CI \-a \0msg-file \f1| - .C instl_adm stores the contents of .I msg-file for use as the opening message displayed to users doing an install. If this option is omitted, the current message (if any) is kept. To remove the message completely, simply use an empty file such as .C /dev/null as the .IR msg-file . If the .C \- character is given for .IR msg-file , then .I instl_adm will prompt the user to enter the message on the command line. Once the message is entered, Ctrl-D (end-of-file) should be typed to end the message. .IP If the message given contains any double-quote characters (") then they must be preceded by the back-slash (\\) character. (i.e. \\"hello\\"). A message with non-escaped double-quote characters will cause syntax errors. .TP .C \-c Causes .I instl_adm to operate on the LIF file named .C CONFIG instead of the first 8KB of the file named .CR INSTALLFS . This option is only valid when the .C -F option is used to instruct .I instl_adm to operate on an install tape image. The install tape image is a logical interchange format file (See .IR lif (4)). .IP The .C CONFIG file is where the standard configuration as shipped by Hewlett-Packard is kept. This file defines the default file system and software configuration that is selectable during an install. See .SM FILES below for the location of this file on a network install server. .IP Hewlett-Packard does not support modifications of the standard configuration file. .TP .C \-T Test for proper syntax of standard configuration files, or of the configuration file given with the .C -f option. See .SM FILES below for the location of the standard configuration files. .TP .C \-b Blanks (or clears) any previous configuration values set. .RE .SH EXAMPLES Display the current message and defaults: .IP .C instl_adm -d .PP Change the message to the contents of file .C new-message while leaving the current network defaults in place: .IP .C instl_adm -a new-message .PP Install new default parameters for the SD server and depot directory as well as a default gateway and netmask. The .C \-d option will cause the information to be displayed after installation: .IP .C "instl_adm -d -s jupiter:/depot -g 15.1.48.1 -m255.255.248.0" .PP Extract the current default configuration, edit it, and then reinstall the new configuration: .IP .C instl_adm -d > /tmp/cfg .br .C vi /tmp/cfg .br .C instl_adm -f /tmp/cfg .PP Make a customized cold-install tape that gives a message to the user. This uses .C dd to extract the tape data, .C instl_adm to modify it, and then .C dd to write a new tape. .IP .C mt -t /dev/rmt/0m rew .br .C dd if=/dev/rmt/0m of=/tmp/tape.image bs=2k .br .C instl_adm -F /tmp/tape.image -a msg-file .br .C mt -t /dev/rmt/0m rew .br .C dd if=/tmp/tape.image of=/dev/rmt/0m bs=2k .C .SH FILES .TP 15 .C /usr/lib/sw/hpux.install/700INSTALLFS File system used by Series 700 install clients. Configuration information available at client boot-time is stored in the first 8KB of this file. This is the default file .C instl_adm modifies. .TP .C /usr/lib/sw/hpux.install/700INSTALL The kernel booted by Series 700 install clients. .TP .C /usr/lib/sw/hpux.install/config.local Holds the configuration that resulted from the installation of the server itself. This configuration is provided to clients as a way of matching that of the server. The information in this file will become out of date with respect to the server as software is added/deleted and as new file systems are created. This file may be customized to provide an easy way to pick a system configuration for your specific application. (see .IR instl_adm (4)). .TP .C /usr/lib/sw/hpux.install/config Holds the default configuration information provided by Hewlett-Packard. Modification of this file is not recommended or supported. Any modifications will be lost if the HPUX-Install product is re-loaded. Customizations should be restricted to the .C config.local file. .SH SEE ALSO instl_adm(4), instl_bootd(1M), swinstall(1M), swcopy(1M), ifconfig(1M), route(1M), hosts(4). .\" .\" toc@\f3instl_adm(1M)\f1:\0\0\f4instl_adm\f1@@@maintain network install configuration and default parameters .\" .\" index@\f4instl_adm\f1 \- maintain network install configuration and default parameters@@@\f3instl_adm(1M)\f1 .\" index@\f1maintain network install configuration and default parameters@@@\f3instl_adm(1M)\f1 .\" index@\f1network install configuration and default parameters, maintain@@@\f3instl_adm(1M)\f1 .\" index@\f1install configuration and default parameters, maintain network@@@\f3instl_adm(1M)\f1 .\" index@\f1configuration and default parameters, maintain network install@@@\f3instl_adm(1M)\f1 .\" index@\f1default parameters, maintain network install configuration and@@@\f3instl_adm(1M)\f1 .\" index@\f1parameters, maintain network install configuration and default@@@\f3instl_adm(1M)\f1 .\" .\" fileset_database@instl_adm.1m SYS-ADMIN-MAN .\" $Header: instl_bootd.1m,v 76.1 95/07/05 17:32:59 ssa Exp $ .TA i .TH instl_bootd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME instl_bootd \- boot protocol server for cold-install clients .SH SYNOPSIS .C instl_bootd .RC [ -s ] .RC [ -r .IR reuse-time\| ] .RC [ -t .IR timeout\| ] .RC [ -d .IR debug-level\| ] .RC [ -c .IR command\| ] .RC [ -C .IR command\| ] .RC [ -P .IR port\| ] .RC [ -b .IR boot-file\| ] .RI [ \|instl_boottab\| ] .PP .SH DESCRIPTION .C instl_bootd is a boot protocol daemon that responds to boot requests from clients wishing to install an operating system, using the Internet Boot Protocol (BOOTP) as defined in RFC951 and RFC1048. .C instl_bootd can respond to clients without the server's prior knowledge of the client (unlike .C bootpd which requires a client to be registered with the server prior to a boot request). .PP When .C instl_bootd receives a boot request, it allocates an Internet Protocol (IP) address from a list of available addresses held in the file .IR instl_boottab . .C instl_bootd then responds to the client by returning the IP address and the .IR boot-file . .SS Options .C instl_bootd recognizes the following options and arguments: .RS .TP 15 .CR -s \0 Allow .C instl_bootd to run as a stand-alone daemon. This option is used when starting the daemon manually or via a system startup script, but not when starting via .C inetd (see .CR inetd (1M)). Without this option, .C instl_bootd expects an open socket associated with the server port as its standard input. With this option, .C instl_bootd opens the socket itself. Using .C inetd is the preferred startup method. .TP 15 .CI -r \0reuse-time Specify the minimum amount of time (in minutes) that must elapse before an IP address can be reused. The default value for .I reuse-time is 3 minutes. .I reuse-time should correspond to the amount of time a client requires to perform the initial phase of bootup (that is, transferring the kernel into memory). Once .C instl_bootd allocates an IP address to a client, it will not reallocate the same address to a different client for .I reuse-time minutes. This prevents IP address collision during the client's boot phase. .C instl_bootd does not respond to clients (and clients cannot boot) if it cannot successfully allocate an IP address old enough to satisfy the .I reuse-time requirement. In this case, a diagnostic message is logged to .C syslogd (see .CR syslogd (1M)). If this condition occurs frequently, adding more IP addresses to .I instl_boottab might be necessary. .TP 15 .CI -t \0timeout Specify how long (in minutes) .C instl_bootd remains running after responding to a boot request. A .I timeout value of zero means that .C instl_bootd will never exit. The default .I timeout value is 15 minutes. Increasing .IR timeout , (or setting to it zero) prevents .C instl_bootd from being started and stopped excessively during heavy use. Decreasing .I timeout is useful if .C instl_bootd is rarely used, and its resources need to be reclaimed sooner. The .C -t option has no meaning when used with the .C -s option. .TP 15 .CI -d \0debug-level Specify the detail of messages logged to .C syslogd (see .CR syslogd (1M)). The default value of zero means that only errors and warnings are logged. Values of 1, 2, or 3 cause increasingly more verbose message logging. .TP 15 .CI -c \0command Specify a .I command to be executed using .C system (see .CR system (3S)) when .C instl_bootd responds to a new client's boot request. Two arguments are passed to .IR command , the LAN card station address, and the IP address allocated to the client. .TP 15 .CI -C \0command Like the .C -c option. Client systems often send multiple boot requests during the boot process. The .C -c option causes .C instl_bootd to execute .I command only the first time it responds to a boot request from a client. The .C -C option causes .C instl_bootd to execute .I command every time it responds to a boot request. .TP 15 .CI -P \0port Override the default User Datagram Protocol (UDP) port numbers defined by .CR services (4) for .I instl_boots and .IR instl_bootc . Default values are 1067 and 1068 respectively. This causes .C instl_bootd to listen and respond to boot requests on .I port and .IR port +1. .I port becomes the server port .RI ( instl_boots ) and .IR port +1 becomes the client port .RI ( instl_bootc ). This option is useful if more than one daemon is in use, or if the default ports conflict with another service. Some clients can only specify a limited set of port numbers. When using a non-default .IR port , ensure it is set to a value that can be matched by the client hardware. .TP 15 .CI -b \0boot-file Change the boot file path from the default .br .C /usr/lib/sw/hpux.install/uxinstlf.hppa to .IR boot-file . .I boot-file is a Logical Interchange Format (LIF) volume that the client uses to access other boot utilities (see .CR lif (4), .CR hpux (1M) and .CR isl (1M)). .I boot-file must be accessible using the .C tftp service (see .CR tftp (1)). .TP 15 .I instl_boottab Use the file .I instl_boottab instead of the default file .C /etc/instl_boottab as the source of available IP addresses to allocate to clients. See below for a description of this file. .RE .SS instl_boottab description The .I instl_boottab file contains the list of temporary Internet Protocol (IP) addresses used by clients during the initial phase of their boot process. A permanent IP address for the client is prompted for and used when the boot process is complete, at which time the temporary IP address may be reused to service other boot requests. The .I instl_boottab file can contain one or more IP addresses. If it contains no addresses, the server will not accept boot requests. .PP The following is a sample .C instl_boottab file: .RS .IP .C # This is a comment line .br .C 1.23.45.67 # A single entry. .br .C 1.23.45.68:::reserve # Reserve when allocated. .br .C 1.23.45.69:080009123456:930225100240:reserve # Reserved .br .C 1.23.45.70:080009123457:930225111433 .RE .PP Comments are denoted by the .C # character and can be used anywhere except between fields. Blank lines are also allowed. A template .I instl_boottab is provided in .C /etc/instl_boottab and contains a header comment explaining the syntax, and sample entries, which are commented out. .PP Each non-comment line of the .I instl_boottab file contains one IP address entry, with the IP address specified in "dot" notation (for example, 12.34.567.89). In addition to the IP address, each entry can contain three additional fields, each separated by the .C : (colon) character. The additional fields may be empty or absent. All four fields are defined as follows: .RS .TP 10 Field 1 Defines the IP address of the entry in "dot" notation. This field cannot be empty and it must begin in the first column of the line. .TP Field 2 Indicates the LAN card station address of the last client to use the entry. It is added automatically by .IR instl_bootd , but can be added manually and is useful when field 4 is set to .CR reserve . .TP Field 3 Indicates the date and time (in YYMMDDhhmmss format) when the entry was last allocated. This field is updated by .IR instl_bootd . .TP Field 4 Can be set manually to the keyword .CR reserve , to indicate that the entry may be allocated only to the client with a station address matching field 2. If field 2 is empty, the entry can be allocated to any host, but after allocation, field 2 is updated to indicate the client to which it is allocated. Once field 2 is set, the entry cannot be allocated to any other client. .RE .PP When .C instl_bootd receives a boot request, it searches .I instl_boottab for an IP address issued to the client during a prior boot request. If the search is unsuccessful, .C instl_bootd searches for the IP address with the oldest time-stamp. .PP An IP address can be marked with a .C reserve keyword, which causes .C instl_bootd to allocate the address to the client specified in field 2. Once a .C reserve address is allocated to a client, it cannot be allocated to a different client unless .I instl_boottab is manually edited to change the reserved status. .PP Once an IP address is allocated to a client, .C instl_bootd updates fields 2 and 3 of .IR instl_boottab . Field 2 identifies the client by its LAN card station address; field 3 indicates the date and time the allocation occurred. .PP Since .I instl_boottab is modified after each boot request and response, the system administrator should move the file to a temporary location while editing it, and then return it to its permanent location when done. All boot requests are denied when the file is in its temporary location. The .I instl_boottab file is automatically reread after modification. .PP Multiple .C instl_bootd processes can share a single .I instl_boottab file. Appropriate file locking and retry mechanisms are implemented to ensure that this is possible. Even so, each process must have a unique network port number (see .C -P option). .SH WARNINGS If several clients attempt to boot simultaneously, and not enough IP addresses are listed in .IR instl_boottab , some clients may be denied boot services. From the client perspective, it will appear that the .C instl_bootd services are not working. If this happens, check the .CR syslogd (1M) logfile on the server to verify this condition. Adding more IP addresses to .I instl_boottab can help avoid this situation. .SH DEPENDENCIES HP 9000 systems not supporting BOOTP use .CR rbootd (1M) to provide booting services. .CR rbootd (1M) serves older HP 9000 systems by translating boot packets into BOOTP and forwarding them to the .C instl_bootd server. .PP In addition to the services provided by .CR instl_bootd , the .C tftp service must also be configured on the server system, and .I boot-file must be accessible through the .C tftp service (see .CR tftp (1) and .CR tftpd (1M)). .SH FILES .TP 30 .C /etc/instl_boottab default IP address database .TP .C /usr/lib/sw/hpux.install/uxinstlf.hppa default boot-file (LIF volume) .TP .C /etc/inetd.conf contains the command line used by .CR inetd (1M) to start instl_bootd. .TP .C /etc/services network services port number database .TP .C /var/adm/syslog/syslog.log default location of the .C syslogd logfile (see .CR syslogd (1M)). .SH AUTHOR .PP .C bootpd was developed by Carnegie Mellon University and Stanford University. .br .C instl_bootd was derived from .C bootpd by Hewlett-Packard. .SH SEE ALSO .PP inetd(1M), services(4), instl_adm(1M), tftp(1), tftpd(1M), syslogd(1M), bootpd(1M). .br .IR "Installing and Updating HP-UX" manual. .br DARPA Internet Request For Comments RFC951, RFC1048. .\" .\" index@\f4instl_bootd\f1 \- boot protocol server for cold-install clients@@@\f3instl_bootd(1M)\f1 .\" index@\f1boot protocol server for cold-install clients@@@\f3instl_bootd(1M)\f1 .\" index@\f1protocol server, for booting cold-install clients@@@\f3instl_bootd(1M)\f1 .\" index@\f1server, for booting cold-install clients@@@\f3instl_bootd(1M)\f1 .\" index@\f1cold-install clients@@@\f3instl_bootd(1M)\f1 .\" .\" toc@\f3instl_bootd(1M)\f1:\0\0\f4instl_bootd\f1@@@boot protocol server for cold-install clients .\" .\" fileset_database@instl_bootd.1m SYS-ADMIN-MAN .\" $Header: intro.1m,v 72.3 93/01/14 12:13:21 ssa Exp $ .TA a .TH intro 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME intro \- introduction to system maintenance commands and application programs .SH DESCRIPTION This section describes commands that are used chiefly for system maintenance and administration purposes. The commands in this section should be used in conjunction with other sections of this manual, as well as the .SM HP-UX System Administration manuals for your system. .SS Command Syntax Unless otherwise noted, commands described in this section accept options and other arguments according to the following syntax: .IP .I name .RI [ \|option\| ( \|s\| )\|] .RI [ \|cmd_arg\| ( \|s\| )\|] .PP where the elements are defined as follows: .RS .TP 10 .I name Name of an executable file. .TP .I option One or more .IR option s can appear on a command line. Each takes one of the following forms: .RS .ift .RS .TP .CI - no_arg_letter A single letter representing an option without an argument. .TP .CI - no_arg_letters Two or more single-letter options combined into a single command-line argument. .TP .CI - arg_letter\f1<>\fPopt_arg A single-letter option followed by a required argument where: .RS .ift .RS .PD 0 .TP .I arg_letter is the single letter representing an option that requires an argument, .TP .I opt_arg is an argument (character string) satisfying the preceding .IR arg_letter , .TP <> represents optional white space. .RE .RE .ift .RE .ift .RE .PD .TP .I cmd_arg Path name (or other command argument) .I not beginning with .CR - , or .C - by itself indicating the standard input. If two or more .IR cmd_arg s appear, they must be separated by white space. .RE .SH RETURN STATUS Upon termination, each command returns two bytes of status, one supplied by the system giving the cause for termination, and (in the case of ``normal'' termination) one supplied by the program (for descriptions, see .IR wait (2) and .IR exit (2)). The system-supplied byte is 0 for normal termination. The byte provided by the program is customarily 0 for successful execution and non-zero to indicate errors or failure such as incorrect parameters in the command line, or bad or inaccessible data. Values returned are usually called variously ``exit code'', ``exit status'', or ``return code'', and are described only where special conventions are involved. .SH WARNINGS Some commands produce unexpected results when processing files containing null characters. These commands often treat text input lines as strings and therefore become confused upon encountering a null character (the string terminator) within a line. .SH SEE ALSO getopt(1), exit(2), wait(2), getopt(3C), hier(5). .PP The introduction to this manual. .\" .\" index@\f4intro\f1 \- introduction to system maintenance commands and application programs@@@\f3intro(1M)\f1 .\" index@system maintenance commands and application programs, introduction to@@@\f3intro(1M)\f1 .\" .\" toc@\f3intro(1M)\f1:\0\0\f4intro\f1@@@introduction to system maintenance commands and application programs .\" .\" fileset_database@intro.1m SYS-ADMIN-MAN .\" $Header: ioinit.1m,v 72.4 94/09/08 13:53:58 ssa Exp $ .TH ioinit 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .TA i .SH NAME .C ioinit \- test and maintain consistency between the kernel I/O data structures and .C /etc/ioconfig .SH SYNOPSIS .C /sbin/ioinit .CI -i .RC [ -r ] .br .C /sbin/ioinit .CI -c .br .C /sbin/ioinit .CI \-f \ infile .RC [ -r ] .br .SH DESCRIPTION .C ioinit is invoked by the .C init process when the system is booted, based on the .br .C ioin entry in .BR /etc/inittab: .RS .TP 6 .C ioin::sysinit:/sbin/ioinitrc > /dev/console 2>&1 .RE .PP where .CR ioinitrc is a script to invoke .CR ioinit with the .CR -i and .CR -r options. Given the .CR -i option, .CR ioinit checks consistency between the kernel I/O data structures (initialized with .CR /stand/ioconfig , which is accessible for NFS diskless support when the system boots up) and information read from .CR /etc/ioconfig . If these are consistent, .C ioinit invokes .C insf to install special files for all new devices. If the kernel is inconsistent with .CR /etc/ioconfig , .C ioinit updates .CR /stand/ioconfig from .CR /etc/ioconfig , and if the .C -r option is given, reboots the system. .PP If .C /etc/ioconfig is corrupted or missing when the system reboots, .CR ioinitrc brings the system up in single-user mode. The user should then restore .C /etc/ioconfig from backup or invoke the .C ioinit with the .C -c option to recreate .C /etc/ioconfig from the kernel. .PP If the .C -f option is given, .C ioinit reassigns instance numbers to existing devices within a given class based on .IR infile . Reassignment takes effect when the system reboots. If .C ioinit finds no errors associated with the reassignment, and the .C -r option is given, the system is rebooted. (See Warnings section.) .PP If the .C -c option is given, .C ioinit recreates .C /etc/ioconfig from the existing kernel I/O data structures. .SS Options .C ioinit recognizes the following options: .RS .TP 12 .C -i Invoke .C insf to install special files for new devices after checking consistency between the kernel and .CR /etc/ioconfig . .TP .CI \-f \ infile Use the file .I infile to reassign instance numbers to devices within a specified class. .I infile may have multiple entries, each to appear on a separate line, each field in the entry separated by 1 or more blanks. Entries should conform to the following format: .C .nf h/w_path class_name instance_# .fi .C ioinit preprocesses the contents of .I infile looking for invalid entries and prints out explanatory messages. An entry is considered to be invalid if the specified hardware path or class name does not already exist in the system, or if the specified instance number already exists for the given class. .TP .C -r Reboot the system when it is required to correct the inconsistent state between the kernel and .CR /etc/ioconfig , as used with the .C -i option. When used with the .C -f option, if there are no errors associated with the instance reassignment, .C -r reboots the system. .TP .C -c Recreate .C /etc/ioconfig , if the file is corrupted or missing and cannot be restored from backup. If .C -c is invoked, any previous binding of hardware path to device class and instance number is lost. .RE .BR .SH RETURN VALUE .RS .TP 12 .C 0 No errors occurred, although warnings might be issued. .TP .C 1 .C ioinit encountered an error. .RE .BR .SH DIAGNOSTICS Most of the diagnostic messages from .C ioinit are self-explanatory. Listed below are some messages deserving further clarification. Errors cause .C ioinit to halt immediately. .SS Errors .TP .C "/etc/ioconfig is missing." .TP .C "/etc/ioconfig is corrupted." Restore .C /etc/ioconfig from backup and then reboot; or recreate .C /etc/ioconfig using .CR "ioinit -c" . .TP .C "Permission to access /etc/ioconfig is denied." Change permissions to .C /etc/ioconfig to allow access by .CR ioinit . .TP .C "exec of insf failed." .C ioinit completed successfully, but .C insf failed. .TP .C "Instance number is already in kernel." Instance number already exists for a given class. Use .C rmsf to remove the existing instance number, then retry. .TP .C "Hardware path is not in the kernel." Given hardware path is not in the kernel. Use .C ioscan -k to get the correct hardware path, then retry. .TP .C "Device class name is not in the kernel." The given class name is not in the kernel. Use .C ioscan -k to get the correct class name, then retry. .RE .BR .SH EXAMPLES To reassign an instance number to a device and class (specified in .IR infile ) and reboot the system: .RS .nf .C "/sbin/ioinit -f infile -r" .fi .RE where .C infile consists of the following: .RS .nf .C 56.52 scsi 2 .fi .RE .C 56.52 is the .IR h/w_path , .C scsi is the .IR class_name , and .C 2 is the .IR instance_# . .BR .PP .SH WARNINGS .PP Running .C rmsf or .C insf overwrites the effect of reassignment by .CR ioinit before the system is rebooted. .SH AUTHOR .C ioinit was developed by HP. .BR .SH FILES .C /stand/ioconfig .br .C /etc/ioconfig .BR .SH SEE ALSO init(1M), insf(1M), ioscan(1M), rmsf(1M), ioconfig(4), inittab(4) .\" .\" toc@\f3ioinit(1M)\f1:\0\0\f2ioinit\f1@@@initialize \s-1I/O\s0 system .\" .\" index@\f2ioinit\f1 \- initialize \s-1I/O\s0 system@@@\f3ioinit(1M)\f1 .\" index@\f2ioinit\f1 \- maintain consistency between data structures and /etc/ioconfig@@@\f3ioinit(1M)\f1 .\" index@kernel data structures and /etc/ioconfig consistency@@@\f3ioinit(1M)\f1 .\" index@consistency, maintain between kernel and /etc/ioconfig@@@\f3ioinit(1M)\f1 .\" index@/etc/ioconfig, maintain consistency with kernel data structures@@@\f3ioinit(1M)\f1 .\" $Header: ioscan.1m,v 72.6 94/08/24 14:20:34 ssa Exp $ .TA i .TH ioscan 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ioscan \- scan \s-1I/O\s0 system .SH SYNOPSIS .C /usr/sbin/ioscan .RC [ -k \(or -u ] .RC [ -d .IR driver \(or\c .C -C .IR class\| ] .RC [ -I .IR instance\| ] .RC [ -H .IR hw_path\| ] .RC [ -f [ -n\c ]\(or\c .CR -F [ -n ]\|] .RI [ \|devfile\| ] .PP .C /usr/sbin/ioscan .CI \-M \ driver .CI \-H \ hw_path .RC [ -I .IR instance\| ] .SH DESCRIPTION .CR ioscan scans system hardware, usable .SM I/O system devices, or kernel .SM I/O system data structures as appropriate, and lists the results. For each hardware module on the system, .CR ioscan displays by default the hardware path to the hardware module, the class of the hardware module, and a brief description. .PP By default, .CR ioscan scans the system and lists all reportable hardware found. The types of hardware reported include processors, memory, interface cards and .SM I/O devices. Scanning the hardware may cause drivers to be unbound and others bound in their place in order to match actual system hardware. Entities that cannot be scanned are not listed. .PP In the second form shown, .CR ioscan forces the specified software driver into the kernel I/O system at the given hardware path and forces software driver to be bound. This can be used to make the system recognize a device that cannot be recognized automatically; for example, because it has not yet been connected to the system, does not support autoconfiguration, or because diagnostics need to be run on a faulty device. .SS Options .CR ioscan recognizes the following options: .RS .TP 18 .CI -C " class" Restrict the output listing to those devices belonging to the specified .IR class . Cannot be used with .CR -d . .TP .CI -d \ driver Restrict the output listing to those devices controlled by the specified .IR driver . Cannot be used with .CR -C . .TP .CR -f Generate a full listing, displaying the module's class, instance number, hardware path, driver, software state, hardware type, and a brief description. .TP .CR -F Produce a compact listing of fields (described below), separated by colons. This option overrides the .CR -f option. .TP .CI -H \ hw_path Restrict the scan and output listing to those devices connected at the specified hardware path. When used with .CR -M, this option specifies the full hardware path at which to bind the software modules. .TP .CI -I \ instance Restrict the scan and output listing to the specified instance, when used with either .CR -d or .CR -C . When used with .CR -M , specifies the desired instance number for binding. .TP .CR -k Scan kernel .SM I/O system data structures instead of the actual hardware and list the results. No binding or unbinding of drivers is performed. The .CR -d , .CR -C , .CR -I , and .CR -H options can be used to restrict listings. Cannot be used with .CR -u . .TP .CI -M \ driver Specifies the software driver to bind at the hardware path given by the .C -H option. Must be used with the .CR -H option. .TP .CR -n List device file names in the output. Only special files in the .CR /dev directory and its subdirectories are listed. .TP .CR -u Scan and list usable .SM I/O system devices instead of the actual hardware. Usable .SM I/O devices are those having a driver in the kernel and an assigned instance number. The .CR -d , .CR -C , .CR -I , and .CR -H options can be used to restrict listings. The .CR -u option cannot be used with .CR -k . .RE .PP The .CR -d and .CR -C options can be used to obtain listings of subsets of the .SM I/O system, although the entire system is still scanned. Specifying .CR -d or .CR -C along with .CR -I , or specifying .CR -H or a .I devfile causes .CR ioscan to restrict both the scan and the listing to the hardware subset indicated. .RE .SS Fields .PP The .CR -F option can be used to generate a compact listing of fields separated by colons (:), useful for producing custom listings with .CR awk . Fields include the module's bus type, cdio, is_block, is_char, is_pseudo, block major number, character major number, minor number, class, driver, hardware path, identify bytes, instance number, module path, module name, software state, hardware type, a brief description, and card instance. If a field does not exist, consecutive colons hold the field's position. Fields are defined as follows: .RS .TP 15 .I class A device category, defined in the files located in the directory .CR /usr/conf/master.d and consistent with the listings output by .CR lsdev (see .IR lsdev (1M)). Examples are .CR disk , .CR printer , and .CR tape . .TP .I instance The instance number associated with the device or card. It is a unique number assigned to a card or device within a class. If no driver is available for the hardware component or an error occurs binding the driver, the kernel will not assign an instance number and a .RC ( -1 ), is listed. .TP .I hw path A numerical string of hardware components, notated sequentially from the bus address to the device address. Typically, the initial number is appended by slash .RC ( / ), to represent a bus converter (if required by your machine), and subsequent numbers are separated by periods .RC ( . ). Each number represents the location of a hardware component on the path to the device. .TP .I driver The name of the driver that controls the hardware component. If no driver is available to control the hardware component, a question mark .RC ( ? ) is displayed in the output. .TP .I software state The result of software binding. .RS .TP 15 .CI CLAIMED software bound successfully .TP .C UNCLAIMED no associated software found .TP .C DIFF_HW software found does not match the associated software .TP .C NO_HW the hardware at this address is no longer responding .TP .CR ERROR the hardware at this address is responding but is in an error state .TP .CR SCAN node locked, try again later .RE .TP .I hardware type Entity identifier for the hardware component. It is one of the following strings: .RS .TP 15 .CI UNKNOWN There is no hardware associated or the type of hardware is unknown .TP .CR PROCESSOR Hardware component is a processor .TP .CR MEMORY Hardware component is memory .TP .CR BUS_NEXUS Hardware component is bus converter or bus adapter .TP .CR INTERFACE Hardware component is an interface card .TP .CR DEVICE Hardware component is a device .RE .TP .I bus type Bus type associated with the node. .TP .I cdio The name associated with the Context-Dependent I/O module. .TP .I is_block A boolean value indicating whether a device block major number exists. A .CR T or .CR F is generated in this field. .TP .I is_char A boolean value indicating whether a device character major number exists. A .CR T or .CR F is generated in this field. .TP .I is_pseudo A boolean value indicating a pseudo driver. A .CR T or .CR F is generated in this field. .TP .I block major The device block major number. A .CR -1 indicates that a device block major number does not exist. .TP .I character major The device character major number. A .CR -1 indicates that a device character major number does not exist. .TP .I minor The device minor number. .TP .I identify bytes The identify bytes returned from a module or device. .TP .I module path The software components separated by periods (.). .TP .I module name The module name of the software component controlling the node. .TP .I description A description of the device. .TP .I card instance The instance number of the hardware interface card. .SH RETURN VALUE .CR ioscan returns .B 0 upon normal completion and .B 1 if an error occurred. .SH EXAMPLES Scan the system hardware and list all the devices belonging to the disk device class. .IP .C ioscan -C disk .PP Forcibly bind driver .CR tape1 at the hardware path .CR 8.4.1 . .IP .C "ioscan -M tape1 -H 8.4.1" .SH AUTHOR .CR ioscan was developed by HP. .SH FILES .CR /dev/config .br .CR /dev/* .SH SEE ALSO config(1M), lsdev(1M), ioconfig(4). .\" .\" index@\f4ioscan\f1 \- scan the \s-1I/O\s0 system@@@\f3ioscan(1M)\f1 .\" index@scan the \s-1I/O\s0 system@@@\f3ioscan(1M)\f1 .\" index@\s-1I/O\s0 system, scan the@@@\f3ioscan(1M)\f1 .\" index@system, scan the \s-1I/O\s0@@@\f3ioscan(1M)\f1 .\" .\" toc@\f3ioscan(1M)\f1:\0\0\f4ioscan\f1@@@scan the \s-1I/O\s0 system .\" $Header: isl.1m,v 72.1 93/01/15 10:54:59 ssa Exp $ .TA i .TH isl 1M "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isl \- initial system loader .SH DESCRIPTION .I isl implements the operating system independent portion of the bootstrap process. It is loaded and executed after self-test and initialization have completed successfully. .PP The processor contains special purpose memory for maintaining critical configuration related parameters (e.g. Primary Boot, Alternate Boot, and Console Paths). Two forms of memory are supported: Stable Storage and Non-Volatile Memory (NVM). .PP Typically, when control is transferred to .I isl, an .I autoboot sequence takes place. An .I autoboot sequence allows a complete bootstrap operation to occur with no intervention from an operator. .I isl executes commands from the .I autoexecute file in a script-like fashion. .I autoboot is enabled by a flag in Stable Storage. .PP .I autosearch is a mechanism that automatically locates the boot and console devices. For further information, see .IR pdc (1M). .PP During an .I autoboot sequence, .I isl displays its revision and the name of any utility it executes. However, if .I autoboot is disabled, after .I isl displays its revision, it then prompts for input from the console device. Acceptable input is any .I isl command name or the name of any utility available on the system. If a non-fatal error occurs or the executed utility returns, .I isl again prompts for input. .SS "Commands" There are several commands available in .I isl. The following is a list with a short description. Parameters may be entered on the command line following the command name. They must be separated by spaces. .I isl prompts for any necessary parameters that are not entered on the command line. .RS .TP 15 .B ? .PD 0 .TP .B help Help \- List commands and available utilities .PD .TP .B listf .PD 0 .TP .B ls List available utilities .PD .TP .B autoboot Enable or disable the .I autoboot sequence .br Parameter \- on or off .TP .B autosearch Enable or disable the .I autosearch sequence .br Parameter \- on or off .TP .B primpath Modify the Primary Boot Path .br Parameter \- Primary Boot Path in decimal .TP .B altpath Modify the Alternate Boot Path .br Parameter \- Alternate Boot Path in decimal .TP .B conspath Modify the Console Path .br Parameter \- Console Path in decimal .TP .B lsautofl .PD 0 .TP .B listautofl List contents of the .I autoexecute file .PD .TP .B display Display the Primary Boot, Alternate Boot, and Console Paths .PD .TP .B readnvm Display the contents of one word of NVM in hexadecimal .br Parameter \- NVM address in decimal or standard hexadecimal notation .TP .B readss Display the contents of one word of Stable Storage in hexadecimal .br Parameter \- Stable Storage address in decimal or standard hexadecimal notation .RE .SH "DIAGNOSTICS" .I isl displays diagnostic information through error messages written on the console and display codes on the .SM LED display. .PP For the display codes, .SM .BI CE0\s0 x are informative only. .SM .BI CE1\s0 x and .SM .BI CE2\s0 x indicate errors, some of which are fatal and cause the system to halt. Other errors merely cause .I isl to display a message. .PP Non-fatal errors during an .I autoboot sequence cause the .I autoboot sequence to be aborted and .I isl to prompt for input. After non-fatal errors during an interactive .I isl session, .I isl merely prompts for input. .PP Fatal errors cause the system to halt. The problem must be corrected and the system .SM .B RESET to recover. .ift .RS .PP .TS lB p-1 l. CE00 \f2isl\fP is executing. CE01 \f2isl\fP is \f2autoboot\fPing from the \f2autoexecute\fP file. CE02 Cannot find an \f2autoexecute\fP file. \f2autoboot\fP aborted. CE03 No console found, \f2isl\fP can only \f2autoboot\fP. CE05 Directory of utilities is too big, \f2isl\fP reads only 2K bytes. CE06 \f2autoexecute\fP file is inconsistent. \f2autoboot\fP aborted. CE07 Utility file header inconsistent: SOM values invalid. CE08 \f2autoexecute\fP file input string exceeds 2048 characters. \f2autoboot\fP aborted. CE09 \f2isl\fP command or utility name exceeds 10 characters. CE0F \f2isl\fP has transferred control to the utility. CE10 Internal inconsistency: Volume label - \f3FATAL\fP. CE11 Internal inconsistency: Directory - \f3FATAL\fP. CE12 Error reading \f2autoexecute\fP file. CE13 Error reading from console - \f3FATAL\fP. CE14 Error writing to console - \f3FATAL\fP. CE15 Not an \f2isl\fP command or utility. CE16 Utility file header inconsistent: Invalid System ID. CE17 Error reading utility file header. CE18 Utility file header inconsistent: Bad magic number. CE19 Utility would overlay \f2isl\fP in memory. CE1A Utility requires more memory than is configured. CE1B Error reading utility into memory. CE1C Incorrect checksum: Reading utility into memory. CE1D Console needed - \f3FATAL\fP. CE1E Internal inconsistency: Boot device class - \f3FATAL\fP. CE21 Destination memory address of utility is invalid. CE22 Utility file header inconsistent: \f2pdc_cache\fP entry. CE23 Internal inconsistency: \f2iodc_entry_init\fP - \f3FATAL\fP. CE24 Internal inconsistency: \f2iodc_entry_init\fP - console - \f3FATAL\fP. CE25 Internal inconsistency: \f2iodc_entry_init\fP - boot device - \f3FATAL\fP. CE26 Utility file header inconsistent: Bad aux_id. CE27 Bad utility file type. .TE .RE .SH SEE ALSO boot(1M), hpux_800(1M), pdc(1M). .\" index@\f2isl\f1 \- initial system loader@@@\f3isl(1M)\f1 .\" index@initial system loader@@@\f3isl(1M)\f1 .\" index@system loader, initial@@@\f3isl(1M)\f1 .\" index@loader, initial system@@@\f3isl(1M)\f1 .\" .\" toc@\f3isl(1M)\f1:\0\0\f2isl\f1@@@initial system loader .\" .\" fileset_database@isl.1m@SYS-ADMIN-MAN .\" $Header: itemap.1m,v 72.2 94/11/03 11:38:56 ssa Exp $ .TA i .TH itemap 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME itemap \- load an ITE (Internal Terminal Emulator) keyboard mapping. .SH SYNOPSIS .C itemap .RC [ options ] .SH DESCRIPTION The .CR itemap command loads a keyboard mapping into the ITE (the graphics console driver), or displays ITE keyboard mappings. .CR itemap is run by .CR /etc/bcheckrc automatically. It is not usually explicitly invoked by the user. .SH Options .RS .TP 15 .CR -d\ \f2name\ \f1or\ \f2keyboard_ID\f1 Dump a keymap to standard output in hexadecimal notation. .TP .C -h Load the specified keymap into the kernel mapping table used for .CR HP-HIL keyboards. .TP .C -i Interactively prompt for a .CR "PS2 DIN" keyboard mapping. .CR itemap scans the keymap database file for all mapping names beginning with a .CR "PS2_DIN" prefix. Each of these names is displayed, and one must be selected. .TP .CR -k\ \f2database_file_name The name of the keymap database file to be used for input. The default is .CR /etc/X11/XHPKeymaps . .TP .C -L Load the appropriate keymap. .CR itemap scans the hardware for a keyboard, determines the language of that keyboard, and loads the keymap corresponding to that keyboard. .IP Because .CR itemap cannot determine the language of .CR "PS2 DIN" keyboards, use the .CR -i option when using .CR -L with .CR "PS2 DIN" keyboards. .TP .CR -l\ \f2name\ \f1or\ \f2keyboard_ID Load a specified keyboard map. Once loaded, ITE uses the specified mapping. .IP When loading a keyboard mapping with the .CR -l option, .CR itemap matches the suffix of the name of the specified keyboard mapping with those found in .CR /etc/X11/XHPKeymaps to determine the keyboard language. This information is used by the ITE to perform ISO 7-to-8 bit conversion. Keymap names added by users, via .RS .IP .C /usr/contrib/bin/X11/keymap_ed .RE .IP should use the same suffixes as those already used in .CR /etc/X11/XHPKeymaps. For example, a French keyboard mapping can be named .CR New_French , for consistency with existing .CR ITF_French and .CR PS2_French mappings. A mapping called .CR New_Stuff would not match any suffix patterns found by itemap, and would result in incorrect ISO 7-to-8 bit conversion. .TP .C -p Load the specified keymap into the kernel mapping table used for .CR "PS2 DIN" keyboards. .TP .C -v Perform actions verbosely. .TP .CR -w\ \f2file_name If a keymap for a .CR "PS2 DIN" keyboard is loaded, write its name to .IR file_name . .RE .SH EXAMPLES To automatically install the correct mapping for an .CR HP-HIL keyboard: .IP .C itemap -L .PP To explicitly load the .CR ITF_French mapping for an .CR HP-HIL keyboard: .IP .C itemap -h -l ITF_French .PP To explicitly load the .CR PS2_DIN_French mapping for a .CR "PS2 DIN" keyboard: .IP .C itemap -p -l PS2_DIN_French .ift .br .ift .ne 6 .PP To interactively choose a .CR "PS2 DIN" keyboard mapping: .IP .C itemap -Li .PP To generate a list of the available keyboard mappings: .IP .C /usr/contrib/bin/X11/keymap_ed -l .SH FILES .TP 40 /usr/contrib/bin/X11/keymap_ed Keymap database editor .PD 0 .TP /etc/X11/XHPKeymaps System keymap database .TP /etc/kbdlang Contains mapping name configured for .CR "PS2 DIN" keyboards .PD .SH SEE ALSO ps2(7), termio(7), keymap_ed(1X111). .\" .\" index@\f4itemap\f1 \- load a keyboard mapping into the Internal Terminal Emulator@@@\f3itemap(1M)\f1 .\" index@\f1keyboard mapping, loading into the Internal Terminal Emulator@@@\f3itemap(1M)\f1 .\" index@\f1Internal Terminal Emulator (ITE), load keyboard mapping@@@\f3itemap(1M)\f1 .\" index@\f1terminal emulator, keyboard mapping@@@\f3itemap(1M)\f1 .\" .\" toc@\f3itemap(1M)\f1:\0\0\f4itemap\f1@@@load a keymap into the Internal Terminal Emulator (ITE)\f1 ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" ...\"Copyright Hewlett-Packard Company 1991 ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" .rm zA .rm zZ .TH kdestroy "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lkdestroy\*O command" .iX "Security Service commands" "\*Lkdestroy\*O" .iX "principals" "destroying login context" .SH NAME \*Lkdestroy\*O \- Destroys a principal's login context and associated credentials .SH "SYNOPSIS" .sS \*Lkdestroy\*O \*O[\*L-c \*Vcache_name\*O] [\*L-e \*Vexp_period\*O] .sE .SH "OPTIONS" .VL 1.25i .LI "\*L-c \*Vcache_name\*O" Specifies that the login context and associated credentials for \*Vcache_name\*O should be destroyed instead of the default cache. .LI "\*L-e \*Vexp_period\*O" Removes credentials that have been expired for a period of time longer than the period of time specified by \*Vexp_period\*O. .LE .SH "DESCRIPTION" .PP The \*Lkdestroy\*O command destroys a principal's login context and the principal's credentials. Until the credentials are reestablished by either executing the \*Ldce_login\*O command or the \*Lkinit\*O command, the principal and any processes created by the principal will be limited to unauthenticated access. .PP Specify the expiration period in the following format: .sS {\*Vnum\*O{\*Vinterval\*O}}... .sE .PP where: .VL 1i .LI "\*Vnum\*O" A number that specifies the number of \*Vinterval\*O .LI "\*Vinterval\*O" A designator of the time period for \*Vnum\*O. \*Vinterval\*O can be any of the following: .ML .LI \*Lw\*O \- weeks .LI \*Ld\*O \- days .LI \*Lh\*O \- hours (default) .LI \*Lm\*O \- minutes .LI \*Ls\*O \- seconds .LE .LE .PP For example, to destroy credentials that have been expired more than 5 days and 10 hours, the entry would be 5d10h. .SH "FILES" .VL 2i .LI "\*L/tmp/krb5cc_\*O[\*Vunix_id\*O] If the \*LKRB5CCNAME\*O environment variable is set, the default credentials cache. ([\*Vunix_id\*O] is the decimal UNIX ID of the user.) .LE .SH "RELATED INFORMATION" .PP Commands: \*Lklist(1m)\*O, \*Lkinit(1m)\*O. .\" $Header: keyenvoy.1m,v 72.2 94/08/25 12:30:15 ssa Exp $ .TA k .TH keyenvoy 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME keyenvoy \- talk to keyserver .SH SYNOPSIS .C keyenvoy .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .CR keyenvoy is a setuid root process that is used by some RPC programs to intermediate between a user process and the keyserv process, .IR keyserv (1M), which will not talk to anything but a root process. .PP This program cannot be run interactively. .SH AUTHOR .CR keyenvoy was developed by Sun Microsystems, Inc. .SH SEE ALSO keyserv(1M). .\" .\" index@\f4keyenvoy(1M)\f1 \- talk to the keyserv process@@@\f3keyenvoy(1M)\f1 .\" index@\f1talk to the keyserv process@@@\f3keyenvoy(1M)\f1 .\" index@\f1keyserv process, talk to the@@@\f3keyenvoy(1M)\f1 .\" .\" toc@\f3keyenvoy(1M)\f1:\0\0\f4keyenvoy\f1@@@talk to the keyserv process .\"$Header: keyserv.1m,v 72.4 94/10/31 13:43:21 ssa Exp $ .TA k .TH keyserv 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME /usr/sbin/keyserv \- store public and private keys .SH SYNOPSIS .C keyserv .RC [ -dkn\| ] .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .CR keyserv is a daemon that stores the private encryption keys of all users logged into the system. These private encryption keys are used to access secure network services such as secure NFS. .PP When a user logs into the system, the .CR login program uses the login password to decrypt the key that is stored in the Network Information Service (NIS) map, .CR publickey.byname . The decrypted key is then stored in the .CR keyserv daemon. .PP When the .CR keyserv daemon is started, it normally reads the encryption key for root from the file .CR /etc/.rootkey . This is done to ensure that the secure network services may be started at any time (even when the owner of root is not around to type in the root password), and that these services operate normally. .SS Options .CR keyserv supports the following options: .RS .TP 15 .C -d Prohibit the use of the default key, .I nobody. If this option is used, every machine and user within a domain must have a public/private key pair in the NIS map, .CR publickey.byname. Also, new publickeys cannot be created from this host with .CR chkey , but existing keys can be modified (see .IR chkey (1) for more details). .TP .C -k Remember key logins across machine reboots. This is only needed if .CR at (1) is used to schedule jobs that require secure RPC. Use of this option is not recommended. .TP .C -n Do not read root's key from .CR /etc/.rootkey . Instead, prompt the user for the password to decrypt root's key, stored in the .SM NIS service and then store the decrypted key in .C /etc/.rootkey for future use. This option is useful if the .C /etc/.rootkey file ever becomes outdated or corrupted. .SH EXAMPLES .C /usr/sbin/keyserv .PP .C /usr/sbin/keyserv -n .PP .C root password: xxxx .SH AUTHOR .CR keyserv was developed by Sun Microsystems, Inc. .SH FILES .TP 25 .C /etc/.rootkey .PD 0 .TP .C /etc/keystore .PD .SH SEE ALSO .PP chkey(1), login(1), keylogin(1), keylogout(1), keyenvoy(1M), publickey(4). .\" .\" index@\f4keyserv\f1 \- server for storing public and private keys@@@\f3keyserv(1)\f1 .\" index@\f1server for storing public and private keys@@@\f3keyserv(1)\f1 .\" index@\f1key server, storing public and private keys@@@\f3keyserv(1)\f1 .\" index@\f1public and private key storage, server for@@@\f3keyserv(1)\f1 .\" .\" toc@\f3keyserv(1)\f1:\0\0\f4keyserv\f1@@@server for storing public and private keys .\" $Header: killall.1m,v 72.5 94/11/14 15:22:50 ssa Exp $ .TA k .TH killall 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME killall \- kill all active processes .SH SYNOPSIS .C /usr/sbin/killall .RI [ \|signal\| ] .SH DESCRIPTION .C killall is a procedure used by .C /usr/sbin/shutdown to kill all active processes not directly related to the shutdown procedure. .PP .C killall is chiefly used to terminate all processes with open files so that the mounted file systems are no longer busy and can be unmounted. .C killall sends the specified .I signal to all user processes in the system, with the following exceptions: .IP the .C init process; .IP all processes (including background processes) associated with the terminal from which .C killall was invoked; .IP any .C ps\0-ef process, if owned by .CR root ; .IP any .C sed\0-e process, if owned by .CR root ; .IP any .C shutdown process; .IP any .C killall process; .IP any .C /sbin/rc process. .PP .C killall obtains its process information from .CR ps , and therefore may not be able to perfectly identify which processes to signal (see .IR ps (1)). .PP If no .I signal is specified, a default of .C 9 (kill) is used. .PP .C killall is invoked automatically by .C shutdown The use of .C shutdown is recommended over using .C killall by itself (see .IR shutdown (1M)). .SH FILES .C /usr/sbin/shutdown .SH SEE ALSO fuser(1M), kill(1), ps(1), shutdown(1M), signal(5). .SH STANDARDS CONFORMANCE .CR killall ": SVID2, SVID3" .\" .\" index@\f4killall\f1 \- kill all active processes@@@\f3killall(1M)\f1 .\" index@terminate all active processes@@@\f3killall(1M)\f1 .\" index@active processes, kill (terminate) all@@@\f3killall(1M)\f1 .\" index@processes, kill all active@@@\f3killall(1M)\f1 .\" .\" toc@\f3killall(1M)\f1:\0\0\f4killall\f1@@@kill all active processes .\" .\" fileset_database@killall.1m SYS-ADMIN-MAN .\" $Header: killsm.1m,v 1.1.113.3 96/04/04 14:08:06 bkelley Exp $ .TA k .TH killsm 1M .SH NAME /usr/sbin/killsm \- kills the sendmail daemon .SH SYNOPSIS .C killsm .SH DESCRIPTION .C killsm reads the .CR /etc/mail/sendmail.pid file to find the pid number of the currently running sendmail daemon, and then kills that daemon. The .CR "/sbin/init.d/sendmail stop" command does the same thing. .PP HP recommends that system administrators use "/sbin/init.d/sendmail start" and "/sbin/init.s/sendmail stop" to start and stop sendmail; these startup scripts are used when the system is booting to start sendmail. Advanced system administrators can put /usr/sbin into their search path and just reference "sendmail -bd -q30m" to start sendmail, and "killsm" to stop it. .PP The previous .CR "sendmail -bk" option of former releases is no longer supported. .PP .SH SEE ALSO sendmail(1M). .\" .\" index@\f4killsm\f1 \- kills the sendmail daemon@@@\f3killsm(1M)\f1 .\" index@\f1kills the sendmail daemon@@@\f3killsm(1M)\f1 .\" index@\f1sendmail daemon, killing it@@@\f3killsm(1M)\f1 .\" index@\f1daemon, kills the sendmail daemon@@@\f3killsm(1M)\f1 .\" .\" toc@\f3killsm(1M)\f1:\0\0\f4killsm\f1@@@kills the sendmail daemon ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\"Copyright Hewlett-Packard Company 1991 ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" $Source: /vob/dce.doc/src/doc/dce_books/command_ref/man1m/kinit.1m $ ...\" $Author: arh $ ...\" $Id: kinit.1m,v /main/1 1995/03/08 02:13 UTC arh Exp $ ...\" Copyright 1990 by the Massachusetts Institute of Technology. ...\" For copying and distribution information, please see the file ...\" . ...\".TH KINIT 1 "Kerberos Version 5.0" "MIT Project Athena" ...\" .rm zA .rm zZ .TH kinit "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lkinit\*O command" .iX "Security Service commands" "\*Lkinit\*O" .iX "-[" "ticket granting tickets" "obtaining and caching" .SH NAME \*Lkinit\*O \- Obtains and caches ticket-granting ticket .SH "SYNOPSIS" .sS \*Lkinit\*O \*O[\*L-c \*Vcachename\*O] \*O[\*L-f\*O] \*O[\*L-l \*Vlifetime\*O] \*O[\*L-p\*O] \*O[\*L-r \*Vlifetime\*O] \*O[\*L-v\*O] \*O[\*Vprincipal\*O] .sE .SH "OPTIONS" .VL 1i .LI "\*L-c \*Vcachename\*O" Specifies an alternative credentials cache, \*Vcachename\*O, to be used in place of the default credentials cache. The \*Lkinit\*O command overwrites the contents of the alternative cache with the current credentials. .PP The name of the default credentials cache may vary between systems. However, if the \*LKRB5CCNAME\*O environment variable is set, its value is used to name the default cache. .LI "\*L-f\*O" Requests the FORWARDABLE option. This option allows a ticket-granting ticket with a different network address than the present ticket-granting ticket to be issued to the principal. For forwardable tickets to be granted, the principal's account in the registry must specify that the principal can be granted forwardable tickets. .LI "\*L-l\*O \*Vlifetime\*O" Specifies the lifetime of the ticket-granting ticket in hours. If this option is not specified, the default ticket lifetime (set by each site using the \*Lrgy_edit(1m)\*O command) is used. .LI "\*L-p\*O" Requests the PROXIABLE option. This option allows a ticket with a different network address than the present ticket to be issued to the principal. For proxiable tickets to be granted, the principal's account in the registry must specify that the principal can be granted proxiable tickets. .LI "\*L-r \*Vlifetime\*O" Requests the RENEWABLE option. This option allows the tickets issued to the principal to be renewed. For renewable tickets to be granted, the principal's account in the registry must specify that the principal can be granted renewable tickets. The lifetime of the ticket-granting ticket is specified in hours by \*Vlifetime\*O. .LI "\*L-v\*O" Specifies that the command should run in verbose mode. .LE .SH "ARGUMENTS" .VL 1i .LI "\*Vprincipal\*O" The \*Vprincipal\*O argument specifies the name of the principal for whom the ticket-granting ticket should be obtained. If \*Vprincipal\*O is omitted, the principal name from the existing cache is reused. .LE .SH "DESCRIPTION" .PP The \*Lkinit\*O command can be used to refresh a DCE credentials cache. When you invoke \*Lkinit\*O, it prompts for your password. .PP The ticket lifetime and renewable lifetime are set in the following format: .sS {\*Vnum\*O {\*Vinterval\*O}}... .sE .PP where: .VL 1i .LI "\*Vnum\*O" A number that specifies the number of the interval; \*Vinterval\*O can be specified by the following: .ML .LI \*Lw\*O \- weeks .LI \*Ld\*O \- days .LI \*Lh\*O \- hours .LI \*Lm\*O \- minutes .LI \*Ls\*O \- seconds .LE .LE .PP For example, to set the lifetime to 3 weeks, 5 days, and 10 hours, the entry would be the following: .iS 3w5d10h .iE .iX "-]" "ticket granting tickets" "obtaining and caching" .SH "FILES" .VL 2i .LI "\*L/tmp/krb5cc_\*O[\*Vunix_id\*O] If the \*LKRB5CCNAME\*O environment variable is not set, the name of the file is in the form shown where [\*Vunix_id\*O] is the decimal UNIX ID of the user. If the \*LKRB5CCNAME\*O environment variable is set, its setting determines the name of the file. .LE .SH "RELATED INFORMATION" .PP Commands: \*Lklist(1m)\*O, \*Lkdestroy(1m)\*O. ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" $EndLog$ ...\" ...\"Copyright Hewlett-Packard Company 1991 ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" $Source: /vob/dce.doc/src/doc/dce_books/command_ref/man1m/klist.1m $ ...\" $Author: arh $ ...\" $Id: klist.1m,v /main/1 1995/03/08 02:13 UTC arh Exp $ ...\" Copyright 1990 by the Massachusetts Institute of Technology. ...\" ...\" For copying and distribution information, please see the file ...\" . ...\".TH KLIST 1 "Kerberos Version 5.0" "MIT Project Athena" ...\" .rm zA .rm zZ .TH klist "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lklist\*O command" .iX "Security Service commands" "\*Lklist\*O" .iX "tickets" "viewing cached" .SH NAME \*Lklist\*O \- Lists cached tickets .SH "SYNOPSIS" .sS \*Lklist\*O \*O[\*L-c \*Vcachename\*O] \*O[\*L-e\*O] \*O[\*L-f\*O] .sE .SH "OPTIONS" .VL 1i .LI "\*L-c \*Vcachename\*O" Specifies that the contents of the cache identified by \*Vcachename\*O should be displayed instead of the contents of the default cache. .LI "\*L-e\*O" Includes expired tickets in the display. Without this option, only current tickets are displayed. .LI "\*L-f\*O" Displays option settings on the tickets. The options are .ML .LI \*LD\*O (postdatable) .LI \*Ld\*O (postdated) \*LF\*O (forwardable) .LI \*Lf\*O (forwarded) .LI \*LI\*O (initial) .LI \*Li\*O (invalid) .LI \*LP\*O (proxiable) .LI \*Lp\*O (proxy) .LI \*LR\*O (renewable) .LE .LE .SH "DESCRIPTION" The \*Lklist\*O command lists the primary principal and tickets held in the default credentials cache, or in the cache identified by \*Vcachename\*O if the \*L\-c\*O option is used. .PP The name of the default credentials cache can vary between systems. However, if the \*LKRB5CCNAME\*O environment variable is set, its value is used to name the default cache. If it is not set, the form of the name is \*L/tmp/krb5cc_\*O[\*Vunix_id\*O], where [\*Vunix_id\*O] is the decimal UNIX ID of the user. .LE .SH "RELATED INFORMATION" .PP Commands: \*Lkinit(1m)\*O, \*Lkdestroy(1m)\*O, \*Lkrb5(3)\*O. ...\".SH BUGS ...\"Does not display srvtabs yet. ...\"Does not list ticket options or lifetimes. .\" $Header: volcopy.1m,v 72.6 94/11/29 13:27:56 ssa Exp $ .TA v .TH volcopy 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME volcopy, labelit (generic) \- copy a file system with label checking .SH SYNOPSIS .CR /usr/sbin/volcopy .RI [ options ]\& .I fsname .I special1 .I volname1 .I special2 .ifn .br .ifn \0\0\0\0 .I volname2 .PP .CR /usr/sbin/labelit .RI [ options ]\& .I special .RI [ fsname .I volume .RC [ \-n ]\|] .SH DESCRIPTION The .CR volcopy command makes a literal copy of the file system using a block size matched to the device. .SS Options .CR volcopy recognizes the following options: .RS .TP 15 .CI \-F \0FStype Specify the file system type on which to operate (see .IR fstyp (1M) and .IR fs_wrapper (5)). If this option is not included on the command line, then the file system type is determined from the file .CR /etc/fstab by matching .I special with an entry in that file. If there is no entry in .CR /etc/fstab , then the file system type is determined from the file .CR /etc/default/fs . .TP .CR \-a Invoke a verification sequence requiring a positive operator response instead of the standard delay before the copy is made. .TP .CI \-o \0specific_options Specify options specific to the file system type. .I specific_options is a list of suboptions and/or keyword/attribute pairs intended for an .IR FStype -specific module of the command. See the file system specific manual entries for a description of the .I specific_options that are supported, if any. .TP .CR \-s (default) Invoke the DEL-if-wrong verification sequence. .TP .CR \-V Echo the completed command line, but perform no other actions. The command line is generated by incorporating the user-specified options and arguments with other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .PP Other options are used with 9-track magnetic tapes: .RS .TP 15 .CI \-bpi \0density Bits per inch. .TP .CI \-feet \0size Size of reel in feet. .TP .CI \-reel \0num Beginning reel number for a restarted copy. .TP .CR \-buf Use double buffered I/O. .RE .PP The .CR volcopy command requests length and density information if they are not given on the command line and they are not recorded on an input tape label. If the file system is too large to fit on one reel, the .CR volcopy command prompts for additional reels. Labels of all reels are checked. Tapes can be mounted alternately on two or more drives. If the .CR volcopy command is interrupted, it asks if the user wants to quit or wants to escape to the command interpreter. In the latter case, other operations (such as executing the .CR labelit command) can be performed before returning to the .CR volcopy command by exiting the command interpreter. .TP 10 .I fsname The file system name on the device (e.g., .CR root ) being copied. .TP .I special The physical disk section or tape (e.g., .CR /dev/rdsk/1s3 or .CR /dev/rmt/c0t0d0BEST ). .TP .I volname The physical volume name; it should match the external sticker. Such label names are limited to six or fewer characters. The argument .I volname can be .CR - to use the existing volume name. .TP .I special1 The device from which the copy of the file system is being extracted. .TP .I volname1 The volume from which the copy of the file system is being extracted. .TP .I special2 The target device. .TP .I volname2 The target volume. .PP The .CR labelit command can be used to provide initial labels for unmounted disk or tape file systems. With the optional arguments omitted, the .CR labelit command prints current label values. The .CR \-n option provides for initial labeling of new tapes only (this destroys previous contents). The .CR \-F , .CR \-V , and .CR \-o options can be specified for the .CR labelit command. The behavior of the .CR \-F , .CR \-V , and .CR \-o options is similar to their behavior in the .CR volcopy command. .SH FILES .TP 20 .PD 0 .CR /etc/default/fs File that specifies the default file system type. .TP .CR /etc/fstab Static information about the file systems. .PD .SH SEE ALSO .RI volcopy_ FStype (1M), fs_wrapper(5). .\" .\" toc@\f3volcopy(1M)\f1:\0\0\f4volcopy\f1, \f4labelit\f1@@@copy file systems with label checking .\" toc@\f4labelit\f1 \- copy file systems with label checking@@@see \f3volcopy(1M)\f1 .\" .\" index@\f4volcopy\f1 \- copy file systems with label checking@@@\f3volcopy(1M)\f1 .\" index@\f4labelit\f1 \- copy file systems with label checking@@@\f3volcopy(1M)\f1 .\" index@copy file systems with label checking@@@\f3volcopy(1M)\f1 .\" index@file systems with label checking, copy@@@\f3volcopy(1M)\f1 .\" index@systems with label checking, copy file@@@\f3volcopy(1M)\f1 .\" index@label checking, copy file systems with@@@\f3volcopy(1M)\f1 .\" index@checking, copy file systems with label@@@\f3volcopy(1M)\f1 .\" .\" links@volcopy.1m labelit.1m .\" $Header: volcopy_hfs.1m,v 72.3 94/11/29 13:28:18 ssa Exp $ .TA v .TH volcopy_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME volcopy, labelit (hfs) \- copy an HFS file system with label checking .SH SYNOPSIS .CR /usr/sbin/volcopy .RI [ options ]\& .I fsname .I special1 .I volname1 .I special2 .ifn .br .ifn \0\0\0\0 .I volname2 .PP .CR /usr/sbin/labelit .RI [ options ]\& .I special .RI [ fsname .I volume .RC [ \-n ]\|] .SH DESCRIPTION The .CR volcopy command makes a literal copy of an HFS file system using a block size matched to the device. .SS Options .CR volcopy recognizes the following options: .RS .TP 15 .CR \-F\0hfs Specifies the HFS file system type. .TP .CR \-a Invoke a verification sequence requiring a positive operator response instead of the standard delay before the copy is made. .TP .CR \-s (default) Invoke the DEL-if-wrong verification sequence. .TP .CR \-V Echo the completed command line, but perform no other actions. The command line is generated by incorporating the user-specified options and arguments with other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .PP Other options are used with 9-track magnetic tapes: .RS .TP 15 .CI \-bpi \0density Bits per inch. .TP .CI \-feet \0size Size of reel in feet. .TP .CI \-reel \0num Beginning reel number for a restarted copy. .TP .CR \-buf Use double buffered I/O. .RE .PP The .CR volcopy command requests length and density information if they are not given on the command line and they are not recorded on an input tape label. If the file system is too large to fit on one reel, the .CR volcopy command prompts for additional reels. Labels of all reels are checked. Tapes can be mounted alternately on two or more drives. If the .CR volcopy command is interrupted, it asks if the user wants to quit or wants to escape to the command interpreter. In the latter case, other operations (such as executing the .CR labelit command) can be performed before returning to the .CR volcopy command by exiting the command interpreter. .TP 10 .I fsname The file system name on the device (e.g., .CR root ) being copied. .TP .I special The physical disk section or tape (e.g., .CR /dev/rdsk/1s3 or .CR /dev/rmt/c0t0d0BEST ). .TP .I volname The physical volume name; it should match the external sticker. Such label names are limited to six or fewer characters. The argument .I volname can be .CR - to use the existing volume name. .TP .I special1 The device from which the copy of the file system is being extracted. .TP .I volname1 The volume from which the copy of the file system is being extracted. .TP .I special2 The target device. .TP .I volname2 The target volume. .PP The .CR labelit command can be used to provide initial labels for unmounted disk or tape file systems. With the optional arguments omitted, the .CR labelit command prints current label values. The .CR \-n option provides for initial labeling of new tapes only (this destroys previous contents). The .CR \-F and .CR \-V options can be specified for the .CR labelit command. The behavior of the .CR \-F and .CR \-V options is similar to their behavior in the .CR volcopy command. .SH SEE ALSO fstyp(1M), volcopy(1M), fs_wrapper(5). .\" .\" toc@\f3volcopy_hfs(1M)\f1:\0\0\f4volcopy\f1, \f4labelit\f1@@@copy file systems with label checking .\" toc@\f4labelit\f1 \- copy file systems with label checking@@@see \f3volcopy_hfs(1M)\f1 .\" .\" index@\f4volcopy\f1 \- copy file systems with label checking@@@\f3volcopy_hfs(1M)\f1 .\" index@\f4labelit\f1 \- copy file systems with label checking@@@\f3volcopy_hfs(1M)\f1 .\" index@copy file systems with label checking@@@\f3volcopy_hfs(1M)\f1 .\" index@file systems with label checking, copy@@@\f3volcopy_hfs(1M)\f1 .\" index@systems with label checking, copy file@@@\f3volcopy_hfs(1M)\f1 .\" index@label checking, copy file systems with@@@\f3volcopy_hfs(1M)\f1 .\" index@checking, copy file systems with label@@@\f3volcopy_hfs(1M)\f1 .\" .\" links@volcopy_hfs.1m labelit_hfs.1m .\" $Header: volcopy_vxfs.1m,v 78.1 96/02/13 14:02:39 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA v .TH volcopy_vxfs 1M "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME volcopy, labelit (vxfs) \- copy a VxFS file system with label checking .SH SYNOPSIS .CR /usr/sbin/volcopy .RC [ "\-F vxfs" ] .RC [ \-V ] .RC [ \-a ] .RC [ \-s ] .br \0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0 .I fsname\0special1\0volname1\0special2\0volname2 .PP .C /usr/sbin/labelit .RC [ "\-F vxfs" ] .RC [ \-V ] .RC [ \-n ] .I special .RI [ "fsname volume" ] .SH DESCRIPTION The .C volcopy command makes a literal copy of a VxFS file system using a block size matched to the device. .SS Options .C volcopy recognizes the following options and command-line arguments: .RS .TP 15 .C \-F vxfs Specify the file-system type .RC ( vxfs ). .TP .C \-V Validate the command line options, however, the command is not executed. If the options specified are valid, the complete command line is echoed. If the options specified are not valid, an error message is printed. .TP .C \-a Normally, before copying the file system, .C volcopy delays so that the user can interrupt the copying if needed. This option invokes a verification sequence requiring a positive operator response instead of the standard delay. .TP .C \-s (default) Before copying the file system, prints a message and allows the user to interrupt the copy if needed. .RE .PP Other options are used with 9-track magnetic tapes: .RS .TP 15 .CI \-bpi \0density Bits per inch. .TP .CI \-feet \0size Size of reel in feet. .TP .CI \-reel \0num Beginning reel number for a restarted copy. .TP .C \-buf Use double buffered I/O. .RE .PP The .C volcopy command requests length and density information it is not given on the command line or if it is not recorded on an input tape label. If the file system is too large to fit on one reel, .C volcopy prompts for additional reels. Labels of all reels are checked. Tapes can be mounted alternately on two or more drives. If .C volcopy is interrupted, it asks if the user wants to quit or to escape to the command interpreter. In the later case, other operations (such as .CR labelit ) can be performed before returning to .C volcopy by exiting the command interpreter. .PP The .I fsname argument represents the file system name on the device (e.g., .CR root ) being copied. .PP .I special should be the physical disk section or tape (e.g., .C /dev/rdsk/c0t4d0s0 or .CR /dev/rmt/0mb ). .PP .I volname is the physical volume name; it should match the external sticker. Such label names are limited to six or fewer characters. The argument .I volname can be .C \- to use the existing volume name. .PP The arguments .I special1 and .I volname1 are the device and volume, respectively, from which the copy of the file system is being extracted. The arguments .I special2 and .I volname2 are the target device and volume, respectively. .PP The .C labelit command can be used to provide initial labels for unmounted disk or tape file systems. With the optional arguments omitted, .C labelit prints current label values. .C \-F and .C \-V options can be specified for .CR labelit . The behavior of .C \-F and .C \-V options are similar to the behavior of .CR volcopy . The option .C \-n of .C labelit provides for initial labeling of new tapes (this destroys previous contents). .SH SEE ALSO volcopy(1M), labelit(1M). .\" .\" toc@\f3volcopy_vxfs(1M)\f1:\0\0\f(CWvolcopy\f1, \f(CWlabelit\f1@@@copy VxFS file system with label checking .\" toc@\f(CWlabelit\f1:\0\0label for VxFS file system@@@see \f3volcopy_vxfs(1M)\f1 .\" .\" index@\f(CWvolcopy_vxfs\f1 \- copy VxFS file system with label checking@@@\f3volcopy_vxfs(1M)\f1 .\" index@\f(CWvolcopy\f1 \- copy VxFS file system with label checking@@@\f3volcopy_vxfs(1M)\f1 .\" .\" index@\f(CWlabelit\f1 \- label for VxFS file system@@@\f3volcopy_vxfs(1M)\f1 .\" index@\f1copy VxFS file system with label checking@@@\f3volcopy_vxfs(1M)\f1 .\" index@\f1VxFS file system with label checking@@@\f3volcopy_vxfs(1M)\f1 .\" index@\f1label checking, VxFS file system@@@\f3volcopy_vxfs(1M)\f1 .\" index@\f1checking VxFS file system with label@@@\f3volcopy_vxfs(1M)\f1 .\" .\" links@volcopy_vxfs.1m labelit_vxfs.1m .\" $Header: lanadmin.1m,v 1.2.113.4 98/05/08 14:23:47 prakashr Exp $ .TA l .TH lanadmin 1M .SH NAME lanadmin \- local area network administration program .SH SYNOPSIS .CR /usr/sbin/lanadmin .RC [ \-e ] .RC [ \-t ] .PP .CR /usr/sbin/lanadmin .RC [ \-a ] .RC [ \-A .IR station_addr ] .RC [ \-m ] .RC [ \-M .IR mtu_size ] .RC [ \-R ] .ifn .br .ifn \0\0\0\0 .RC [ \-s ] .RC [ \-S .IR speed ] .RC [ \-x .IR options ] .RC [ \-X .IR options ] .ift .br .ift \0\0\0\0 .I NetMgmtID .SH DESCRIPTION The .CR lanadmin program administers and tests the Local Area Network (LAN). For each interface card, it allows you to: .RS 2 .TP 3 .PD 0 \(bu Display and change the station address. .TP \(bu Display and change the maximum transmission unit (MTU). .TP \(bu Display and change the speed setting. .TP \(bu Clear the network statistics registers to zero. .TP \(bu Display the interface statistics. .TP \(bu Reset the interface card, thus executing its self-test. .PD .RE .PP For operations other than display, you must have superuser privileges. .PP .CR lanadmin reads commands from standard input, writes prompts and error messages to standard error, and writes status information to standard output. When the program is run from a terminal, the interrupt key (usually .CR ^C ) interrupts a currently executing command; the eof key (usually .CR ^D ) terminates the program. .PP .CR lanadmin operates in two modes: Menu Mode (see the first SYNOPSIS line) and Immediate Mode (see the second SYNOPSIS line). If at least one .CR -aAmMRsS option is supplied, .CR lanadmin executes in Immediate Mode. Otherwise, it executes in Menu Mode. .SS Options and Arguments .CR lanadmin recognizes the following Immediate Mode options and arguments. At least one .CR -aAmMRsS option and the .I NetMgmtID argument must be supplied. .RS .TP 20 .I NetMgmtID The Network Management ID number of the LAN interface. This argument is ignored if none of the .CR -aAmMRsS options is used (Menu Mode). Any options specified after .I NetMgmtID are ignored. Appropriate values can be displayed with the .CR lanscan command (see .IR lanscan (1M)). .TP .CR \-a Display the current station address of the interface corresponding to .IR NetMgmtID . .TP .CI \-A \0station_addr Set the new station address of the interface corresponding to .IR NetMgmtID . The .I station_addr must be entered in hex format with a '0x' prefix. You must have superuser privileges. When .IR station_addr is DEFAULT the factory default physical address will be restored. .TP .CR \-m Display the current MTU size of the interface corresponding to .IR NetMgmtID . .TP .CI \-M \0mtu_size Set the new MTU size of the interface corresponding to .IR NetMgmtID . The .I mtu_size value must be within the link specific range. You must have superuser privileges. .TP .CR \-R Reset the MTU size of the interface corresponding to .IR NetMgmtID to the default for that link type. You must have superuser privileges. .TP .CR \-s Display the current speed setting of the interface corresponding to .IR NetMgmtID . .TP .CI \-S \0speed Set the new speed setting of the interface corresponding to .IR NetMgmtID . You must have superuser privileges. .TP .CI \-x \0options Get and display driver specific .IR options of the interface corresponding to .IR NetMgmtID . .TP .CI \-X \0options Set driver specific .IR options of the interface corresponding to .IR NetMgmtID . You must have superuser privileges. .RE .PP .CR lanadmin recognizes the following Menu Mode options. They are ignored if they are given with an Immediate Mode option. .RS .TP 20 .CR \-e Echo the input commands on the output device. .TP .CR \-t Suppress the display of the command menu before each command prompt. This is equivalent to the Test Selection Mode .CR terse command. The default is .CR verbose . .RE .SS Immediate Mode In Immediate Mode, you can display the station address, MTU size, and link speed of LAN interface .IR NetMgmtID . For certain interfaces, if you have superuser privileges you can also modify the station address, MTU size, and link speed. See "Options and Arguments" above. .SS Menu Mode In Menu Mode, you can select an interface card, display statistics for the selected card, reset the card, and clear the statistics registers. .PP Menu Mode accepts either complete command words or unique abbreviations, and no distinction is made between uppercase and lowercase letters in commands. Multiple commands can be entered on one line if they are separated by spaces, tabs, or commas. .PP .B "Test Selection Mode Menu" .PP This menu is entered when Menu Mode is first selected. The available Test Selection Mode commands are: .RS .TP 15 .CR lan Select the LAN Interface Test Mode menu. .TP .CR menu Display the Test Selection Mode command menu. .TP .CR quit Terminate the .CR lanadmin program. .TP .CR terse Suppress the display of command menus. .TP .CR verbose Restore the display of command menus. .RE .PP .B "LAN Interface Test Mode Menu" .PP The following commands are available: .RS .TP 16 .CR clear Clear the LAN interface network statistics registers to zero. You must have superuser privileges. .TP .CR display Display the RFC 1213 MIB II statistics. Depending on the link, the type-specific MIB statistics may also be displayed. For instance, for Ethernet links, the RFC 1398 Ethernet-like statistics are displayed. .TP .CR end Return .CR lanadmin to Test Selection Mode. .TP .CR menu Display the LAN Interface Test Mode command menu. .TP .CR nmid Prompt for a Network Management ID that corresponds to a LAN interface card. It defaults to the first LAN interface encountered in an internal list. Appropriate values can be displayed with the .CR lanscan command (see .IR lanscan (1M)). .TP .CR quit Terminate the .CR lanadmin program. .TP .CR reset Reset the local LAN interface card, causing it to execute its self-test. Local access to the network is interrupted during execution of .CR reset . You must have superuser privileges. .RE .SH AUTHOR .CR lanadmin was developed by HP. .SH SEE ALSO netstat(1), lanscan(1M), linkloop(1M), ping(1M), lan(7). .PP DARPA Requests for Comments: RFC 1213, RFC 1398. .\" .\" index@\f4lanadmin\f1 \- local area network administration@@@\f3lanadmin(1M)\f1 .\" index@local area network administration@@@\f3lanadmin(1M)\f1 .\" index@administration, local area network@@@\f3lanadmin(1M)\f1 .\" index@diagnostics, local area network@@@\f3lanadmin(1M)\f1 .\" index@LAN administration@@@\f3lanadmin(1M)\f1 .\" .\" toc@\f3lanadmin(1M)\f1:\0\0\f4lanadmin\f1@@@local area network administration .\" .\" links@lanadmin.1m landiag.1m .\" $Header: lanconfig.1m,v 74.1 95/03/16 16:31:28 ssa Exp $ .TA l .TH lanconfig 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lanconfig \- configure network interface parameters .SH SYNOPSIS .CR lanconfig .I interface .RC [ ether \(or -ether ] .RC [ ieee \(or -ieee ] .RC [ snap8023 \(or -snap8023 ] .RC [ rif \(or -rif ] .SH DESCRIPTION The .CR lanconfig command displays or configures the network interface protocol. It must be used at boot time to configure each interface present on a machine. It can also be used at a later time to redefine an interface protocol configuration. .PP .I interface is the name of an interface in the form .IR "name\|unit" , such as .CR lan0 . .SS Options .CR lanconfig recognizes the following options: .RS .TP 10 (none) Display the current configuration for .IR interface . .TP .CR ieee Enable the IEEE 802.3 protocol over the network interface. .TP .CR \-ieee Disable the IEEE 802.3 protocol over the network interface. .TP .CR ether Enable the Ethernet protocol and ARP over the network interface. .TP .CR \-ether Disable the Ethernet protocol and ARP over the network interface. .TP .CR snap8023 Enable SNAP encapsulation and ARP within the 802.3 protocol for the network interface. .TP .CR \-snap8023 Disable SNAP encapsulation and ARP within the 802.3 protocol for the network interface. .TP .CR rif Enable the Source Routing protocol over an 802.5 network interface. This is the default. .TP .CR \-rif Disable the Source Routing protocol over an 802.5 network interface. .RE .PP You must have appropriate privileges to modify the configuration of a network interface. .SH DIAGNOSTICS Messages indicate the specified interface does not exist, the requested parameter value is unknown, or the user is not privileged and tried to alter an interface's configuration. .SH WARNINGS If no protocol encapsulation method is enabled, the lan driver cannot send packets over that interface and any subsequent .CR send() fails, returning the error [ENETUNREACH]. .SH SEE ALSO netstat(1), ifconfig(1m), hosts(4), routing(7). .\" .\" index@\f4lanconfig\f1 \- configure network interface parameters@@@\f3lanconfig(1M)\f1 .\" index@\f1configure network interface parameters@@@\f3lanconfig(1M)\f1 .\" index@\f1network interface parameters, configure@@@\f3lanconfig(1M)\f1 .\" index@\f1interface parameters, configure network@@@\f3lanconfig(1M)\f1 .\" index@\f1parameters, configure network interface@@@\f3lanconfig(1M)\f1 .\" .\" toc@\f3lanconfig(1M)\f1:\0\0\f4lanconfig\f1@@@configure network interface parameters .\" $Header: lanadmin.1m,v 74.1 95/03/14 11:01:05 ssa Exp $ .TA l .TH lanadmin 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lanadmin \- local area network administration program .SH SYNOPSIS .CR /usr/sbin/lanadmin .RC [ \-e ] .RC [ \-t ] .PP .CR /usr/sbin/lanadmin .RC [ \-a ] .RC [ \-A .IR station_addr ] .RC [ \-m ] .RC [ \-M .IR mtu_size ] .RC [ \-R ] .ifn .br .ifn \0\0\0\0 .RC [ \-s ] .RC [ \-S .IR speed ] .ift .br .ift \0\0\0\0 .I NetMgmtID .SH DESCRIPTION The .CR lanadmin program administers and tests the Local Area Network (LAN). For each interface card, it allows you to: .RS 2 .TP 3 .PD 0 \(bu Display and change the station address. .TP \(bu Display and change the maximum transmission unit (MTU). .TP \(bu Display and change the speed setting. .TP \(bu Clear the network statistics registers to zero. .TP \(bu Display the interface statistics. .TP \(bu Reset the interface card, thus executing its self-test. .PD .RE .PP For operations other than display, you must have superuser privileges. .PP .CR lanadmin reads commands from standard input, writes prompts and error messages to standard error, and writes status information to standard output. When the program is run from a terminal, the interrupt key (usually .CR ^C ) interrupts a currently executing command; the eof key (usually .CR ^D ) terminates the program. .PP .CR lanadmin operates in two modes: Menu Mode (see the first SYNOPSIS line) and Immediate Mode (see the second SYNOPSIS line). If at least one .CR -aAmMRsS option is supplied, .CR lanadmin executes in Immediate Mode. Otherwise, it executes in Menu Mode. .SS Options and Arguments .CR lanadmin recognizes the following Immediate Mode options and arguments. At least one .CR -aAmMRsS option and the .I NetMgmtID argument must be supplied. .RS .TP 20 .I NetMgmtID The Network Management ID number of the LAN interface. This argument is ignored if none of the .CR -aAmMRsS options is used (Menu Mode). Any options specified after .I NetMgmtID are ignored. Appropriate values can be displayed with the .CR lanscan command (see .IR lanscan (1M)). .TP .CR \-a Display the current station address of the interface corresponding to .IR NetMgmtID . .TP .CI \-A \0station_addr Set the new station address of the interface corresponding to .IR NetMgmtID . The .I station_addr must be entered in hex format with a '0x' prefix. You must have superuser privileges. .TP .CR \-m Display the current MTU size of the interface corresponding to .IR NetMgmtID . .TP .CI \-M \0mtu_size Set the new MTU size of the interface corresponding to .IR NetMgmtID . The .I mtu_size value must be within the link specific range. You must have superuser privileges. .TP .CR \-R Reset the MTU size of the interface corresponding to .IR NetMgmtID to the default for that link type. You must have superuser privileges. .TP .CR \-s Display the current speed setting of the interface corresponding to .IR NetMgmtID . .TP .CI \-S \0speed Set the new speed setting of the interface corresponding to .IR NetMgmtID . You must have superuser privileges. .RE .PP .CR lanadmin recognizes the following Menu Mode options. They are ignored if they are given with an Immediate Mode option. .RS .TP 20 .CR \-e Echo the input commands on the output device. .TP .CR \-t Suppress the display of the command menu before each command prompt. This is equivalent to the Test Selection Mode .CR terse command. The default is .CR verbose . .RE .SS Immediate Mode In Immediate Mode, you can display the station address, MTU size, and link speed of LAN interface .IR NetMgmtID . For certain interfaces, if you have superuser privileges you can also modify the station address, MTU size, and link speed. See "Options and Arguments" above. .SS Menu Mode In Menu Mode, you can select an interface card, display statistics for the selected card, reset the card, and clear the statistics registers. .PP Menu Mode accepts either complete command words or unique abbreviations, and no distinction is made between uppercase and lowercase letters in commands. Multiple commands can be entered on one line if they are separated by spaces, tabs, or commas. .PP .B "Test Selection Mode Menu" .PP This menu is entered when Menu Mode is first selected. The available Test Selection Mode commands are: .RS .TP 15 .CR lan Select the LAN Interface Test Mode menu. .TP .CR menu Display the Test Selection Mode command menu. .TP .CR quit Terminate the .CR lanadmin program. .TP .CR terse Suppress the display of command menus. .TP .CR verbose Restore the display of command menus. .RE .PP .B "LAN Interface Test Mode Menu" .PP The following commands are available: .RS .TP 16 .CR clear Clear the LAN interface network statistics registers to zero. You must have superuser privileges. .TP .CR display Display the RFC 1213 MIB II statistics. Depending on the link, the type-specific MIB statistics may also be displayed. For instance, for Ethernet links, the RFC 1398 Ethernet-like statistics are displayed. .TP .CR end Return .CR lanadmin to Test Selection Mode. .TP .CR menu Display the LAN Interface Test Mode command menu. .TP .CR nmid Prompt for a Network Management ID that corresponds to a LAN interface card. It defaults to the first LAN interface encountered in an internal list. Appropriate values can be displayed with the .CR lanscan command (see .IR lanscan (1M)). .TP .CR quit Terminate the .CR lanadmin program. .TP .CR reset Reset the local LAN interface card, causing it to execute its self-test. Local access to the network is interrupted during execution of .CR reset . You must have superuser privileges. .RE .SH AUTHOR .CR lanadmin was developed by HP. .SH SEE ALSO netstat(1), lanscan(1M), linkloop(1M), ping(1M), lan(7). .PP DARPA Requests for Comments: RFC 1213, RFC 1398. .\" .\" index@\f4lanadmin\f1 \- local area network administration@@@\f3lanadmin(1M)\f1 .\" index@local area network administration@@@\f3lanadmin(1M)\f1 .\" index@administration, local area network@@@\f3lanadmin(1M)\f1 .\" index@diagnostics, local area network@@@\f3lanadmin(1M)\f1 .\" index@LAN administration@@@\f3lanadmin(1M)\f1 .\" .\" toc@\f3lanadmin(1M)\f1:\0\0\f4lanadmin\f1@@@local area network administration .\" .\" links@lanadmin.1m landiag.1m .\" $Header: lanscan.1m,v 74.1 95/05/10 21:52:43 ssa Exp $ .TA l .TH lanscan 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lanscan \- display \s-1LAN\s0 device configuration and status .SH SYNOPSIS .C lanscan .RC [ -ainv ] .RI [ \|system .RI [ \|core\| ]\|] .SH DESCRIPTION .C lanscan displays the following information about each .SM LAN device that has software support on the system: .RS .TP 3 \(bu Hardware Path. .TP \(bu Active Station Address (also known as Physical Address). .TP \(bu Card Instance Number .TP \(bu Hardware State. .TP \(bu Network Interface ``Name Unit'' and State. .TP \(bu Network Management .SM ID. .TP \(bu MAC Type. .TP \(bu HP DLPI Supported. Indicates whether or not the lan device driver will work with HP's Data Link Provider Interface. .TP \(bu Major Number associated with the driver for the lan interface. A .C -- implies that a major number does not apply to this .SM LAN device. .TP \(bu Extended Station Address for those interfaces which require more than 48 bits. This is displayed only when the .C -v option is selected. .TP \(bu Encapsulation Methods that the Network Interface supports. This is displayed only when the .C -v option is selected. .PP The arguments .I system and .I core allow substitution for the default values .C /stand/vmunix and .CR /dev/kmem . .SS Options .C lanscan recognizes the following command-line options: .RS .TP 8 .C -a Display station addresses only. No headings. .TP .C -i Display interface names only. No headings. .TP .C -n Display Network Management IDs only. No headings. .TP .C -v Verbose output. Two lines per interface. Includes displaying of extended station address and supported encapsulation methods. .SH WARNINGS .C lanscan does not display information about .SM LAN devices that do not have software support such as .SM LAN interface cards that fail to bind properly at boot-up time. .SH AUTHOR .C lanscan was developed by HP. .SH SEE ALSO ifconfig(1M), lanconfig(1M), ioscan(1M), lanadmin(1M). .\" .\" index@\f4lanscan\f1 \- display \s-1LAN\s0 device configuration and status@@@\f3lanscan(1M)\f1 .\" index@display \s-1LAN\s0 device configuration and status@@@\f3lanscan(1M)\f1 .\" index@\s-1LAN\s0 device configuration and status, display@@@\f3lanscan(1M)\f1 .\" index@device configuration and status, display \s-1LAN\s0@@@\f3lanscan(1M)\f1 .\" index@configuration and status, display \s-1LAN\s0 device@@@\f3lanscan(1M)\f1 .\" index@status, display \s-1LAN\s0 device configuration and@@@\f3lanscan(1M)\f1 .\" toc@\f3lanscan(1M)\f1:\0\0\f4lanscan\f1@@@display \s-1LAN\s0 device configuration and status .\" $Header: acctsh.1m,v 72.4 94/11/14 12:02:10 ssa Exp $ .TA a .TH acctsh 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chargefee, ckpacct, dodisk, lastlogin, monacct, nulladm, prctmp, prdaily, prtacct, shutacct, startup, turnacct \- shell procedures for accounting .SH SYNOPSIS .C /usr/sbin/acct/chargefee .I login-name number .PP .C /usr/sbin/acct/ckpacct .RI [ \|blocks\| ] .PP .C /usr/sbin/acct/dodisk .RC [ -o ] .RI [ \|files \0 ...\|] .PP .C /usr/sbin/acct/lastlogin .PP .C /usr/sbin/acct/monacct .I number .PP .C /usr/sbin/acct/nulladm .I file .PP .C /usr/sbin/acct/prctmp .PP .C /usr/sbin/acct/prdaily .RC [ -l ] .RC [ -c ] .RC [ \c .IR mmdd\| ] .PP .C /usr/sbin/acct/prtacct .I file .RI [ \|heading\| ] .PP .C /usr/sbin/acct/shutacct .RI [ \|reason\| ] .PP .C /usr/sbin/acct/startup .PP .C /usr/sbin/acct/turnacct .CR on \0\(or\0 off \0\(or\0 switch .SH DESCRIPTION .TP 15 .C chargefee Can be invoked to charge a .I number of units to .IR login-name . A record is written to .CR /var/adm/fee , to be merged with other accounting records during the night. .TP .C ckpacct Should be initiated via .IR cron (1M). It periodically checks the size of .CR /var/adm/pacct . If the size exceeds .IR blocks , 1000 by default, .C turnacct is invoked with argument .IR switch . If the number of free disk blocks in the .C /var file system falls below 500, .C ckpacct automatically turns off the collection of process accounting records via the .C off argument to .CR turnacct . When at least this number of blocks is restored, the accounting will be activated again. This feature is sensitive to the frequency at which .C ckpacct is executed, usually by .CR cron . .TP .C dodisk Should be invoked by .C cron to perform the disk accounting functions. By default, it will do disk accounting on the special files in .C /etc/fstab. If the .C -o flag is used, it does a slower version of disk accounting by login directory. .I files specifies the one or more filesystem names where disk accounting is to be done. If .I files is used, disk accounting will be done on these filesystems only. If the .C -o flag is used, .I files should be mount points of mounted filesystem. If omitted, they should be the special file names of mountable filesystems. .TP .C lastlogin Invoked by .C runacct to update .C /var/adm/acct/sum/loginlog which shows the last date on which each user logged in (see .IR runacct (1M)). .TP .C monacct Should be invoked once each month or each accounting period. .I number indicates which month or period it is. If .I number is not given, it defaults to the current month (01 through 12). This default is useful if .C monacct is to executed via .CR cron on the first day of each month. .C monacct creates summary files in .C /var/adm/acct/fiscal and restarts summary files in .CR /var/adm/acct/sum . .TP .C nulladm Creates .I file with mode 664 and ensures that owner and group are .CR adm . It is called by various accounting shell procedures. .TP .C prctmp Can be used to print the session record file normally .C /var/adm/acct/nite/ctmp created by .C acctcon1 (see .IR acctcon (1M)). .TP .C prdaily Invoked by .C runacct (see .IR runacct (1M)) to format a report of the previous day's accounting data. The report resides in .CI /var/adm/acct/sum/rprt mmdd where .I mmdd is the month and day of the report. The current daily accounting reports may be printed by typing .IR prdaily . Previous days' accounting reports can be printed by using the .I mmdd option and specifying the exact report date desired. The .C -l flag prints a report of exceptional usage by login id for the specifed date. Previous daily reports are cleaned up and therefore inaccessible after each invocation of .CR monacct . The .C -c flag prints a report of exceptional resource usage by command, and can be used on current day's accounting data only. .TP .C prtacct Can be used to format and print any total accounting .RC ( tacct ) file. .TP .C shutacct Should be invoked during a system shutdown to turn process accounting off and append a ``reason'' record to .CR /var/adm/wtmp . .TP .C startup Should be called by system startup scripts to turn the accounting on whenever the system is brought up. .TP .C turnacct An interface to .C accton (see .IR acct (1M)) to turn process accounting .C on or .CR off . The .C switch argument turns accounting off, moves the current .C /var/adm/pacct to the next free name in .CI /var/adm/pacct incr then turns accounting back on again. .RI ( incr is a number starting with .C 1 and incrementing by one for each additional .C pacct file.) .C turnacct is called by .CR ckpacct , and thus can be run under .C cron and used to keep .C pacct to a reasonable size. .SH FILES .TP 40 .C /usr/sbin/acct holds all accounting commands listed in section (1M) of this manual .PD 0 .TP .C /var/adm/fee accumulator for fees .TP .C /var/adm/acct/nite working directory .TP .C /var/adm/pacct current file for per-process accounting .TP .C /var/adm/pacct* used if .C pacct gets large, and during execution of daily accounting procedure .TP .C /usr/sbin/acct/ptecms.awk contains the limits for exceptional usage by command name .TP .C /usr/sbin/acct/ptelus.awk contains the limits for exceptional usage by login id .TP .C /var/adm/acct/sum summary directory, should be saved .TP .C /var/adm/wtmp login/logoff summary .PD .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), cron(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR chargefee ": SVID2, SVID3" .PP .CR ckpacct ": SVID2, SVID3" .PP .CR dodisk ": SVID2, SVID3" .PP .CR lastlogin ": SVID2, SVID3" .PP .CR monacct ": SVID2, SVID3" .PP .CR prctmp ": SVID2, SVID3" .PP .CR prdaily ": SVID2, SVID3" .PP .CR prtacct ": SVID2, SVID3" .PP .CR shutacct ": SVID2, SVID3" .PP .CR startup ": SVID2, SVID3" .PP .CR turnacct ": SVID2, SVID3" .\" .\" .\" index@\f1process accounting@@@see accounting .\" index@\f1accounting: \f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4turnacct\f1 \- turn on or turn off process accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1bill fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1user, bill fee to, based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1disk accounting, perform@@@\f3acctsh(1M)\f1 .\" index@\f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1user, show last login date for each@@@\f3acctsh(1M)\f1 .\" index@\f1last login date, show for each user@@@\f3acctsh(1M)\f1 .\" index@\f1login date, show last for each user@@@\f3acctsh(1M)\f1 .\" index@\f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1periodic accounting summary files, create@@@\f3acctsh(1M)\f1 .\" index@\f1accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1files: accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1summary files, accounting, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1create empty administration file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1empty administration file owned by \f3adm\f1 with mode 664, create@@@\f3acctsh(1M)\f1 .\" index@\f1administration file owned by \f3adm\f1 with mode 664, create empty@@@\f3acctsh(1M)\f1 .\" index@\f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f4acctcon1\f1 \- print session record file created by@@@\f3acctsh(1M)\f1 .\" index@\f1print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1files, accounting: print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1session record file created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f1record file, session, created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1total accounting (\f4tacct\f1) file, print any@@@\f3acctsh(1M)\f1 .\" index@\f1accounting (\f4tacct\f1) file, print any total@@@\f3acctsh(1M)\f1 .\" index@\f4tacct\f1 (total accounting) file, print any@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting: \f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" index@\f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting data and command usage summary, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f1command usage summary and accounting data, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1system shutdown, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f1shutdown, system, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1system startup, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f1startup, system, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f4turnacct\f1 \- turn process accounting on or off@@@\f3acctsh(1M)\f1 .\" index@\f1shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f1system accounting, shell procedures for@@@\f3acctsh(1M)\f1 .\" .\"" Main TOC entry .\" toc@\f3acctsh(1M)\f1:\0\0\f4chargefee\f1, \f4ckpacct\f1, \f4dodisk\f1, \f4lastlogin\f1, \f4monacct\f1, \f4nulladm\f1, \f4prctmp\f1, \f4prdaily\f1,\n\f4prtacct\f1, \f4shutacct\f1, \f4startup\f1, \f4turnacct\f1@@@shell procedures for accounting .\" .\" toc@\f4chargefee\f1:\0\0shell procedures for accounting, charge fee to user@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4ckpacct\f1:\0\0shell procedures for accounting, check size of accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4dodisk\f1:\0\0shell procedures for accounting, perform disk accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4lastlogin\f1:\0\0shell procedures for accounting, show last login date@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4monacct\f1:\0\0shell procedures for accounting, create accounting summary@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4nulladm\f1:\0\0shell procedures for accounting, create null file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prctmp\f1:\0\0shell procedures for accounting, print session record file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prdaily\f1:\0\0shell procedures for accounting, print daily report@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prtacct\f1:\0\0shell procedures for accounting, print accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4shutacct\f1:\0\0shell procedures for accounting, turn off accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4startup\f1:\0\0shell procedures for accounting, start up accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4turnacct\f1:\0\0shell procedures for accounting, turn on or off process accounting@@@\f1see \f3acctsh(1M)\f1 .\" .\" links@acctsh.1m chargefee.1m .\" links@acctsh.1m ckpacct.1m .\" links@acctsh.1m dodisk.1m .\" links@acctsh.1m lastlogin.1m .\" links@acctsh.1m monacct.1m .\" links@acctsh.1m nulladm.1m .\" links@acctsh.1m prctmp.1m .\" links@acctsh.1m prdaily.1m .\" links@acctsh.1m prtacct.1m .\" links@acctsh.1m shutacct.1m .\" links@acctsh.1m startup.1m .\" links@acctsh.1m turnacct.1m .\" .\" fileset_database@acctsh.1m SYS-ADMIN-MAN .\" $Header: lb_admin.1m,v 72.4 94/10/27 14:39:12 ssa Exp $ .TA l .TH lb_admin 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lb_admin \- Location Broker administrative tool .SH SYNOPSIS .C /usr/sbin/ncs/lb_admin .RC [ -nq ] .RC [ -\c .IR version\| ] .SH DESCRIPTION .C lb_admin administers the registrations of .SM NCS\c -based servers in Global Location Broker .SM (GLB) or Local Location Broker .SM (LLB) databases. A server registers Universal Unique Identifiers .SM (UUIDs) specifying an object, a type, and an interface, along with a socket address specifying its location. A client can locate servers by issuing lookup requests to .SM GLB\s0s and .SM LLB\s0s. .C lb_admin can be used to look up information, add new entries, and delete existing entries in a specified database. .PP .C lb_admin is useful for inspecting the contents of Location Broker databases and for correcting database errors. For example, if a server terminates abnormally without unregistering itself, use .C lb_admin to manually remove its entry from the .SM GLB database. .PP In accepting input or displaying output, .C lb_admin uses either character strings or descriptive textual names to identify objects, types, and interfaces. A character string directly represents the data in a .SM UUID in the format .IC xxxxxxxxxxxx .\c .IC xx .\c .IC xx .\c .IC xx .\c .IC xx .\c .IC xx .\c .IC xx .\c .IC xx .\c .IR xx , where each .I x is a hexadecimal digit. Descriptive textual names are associated with .SM UUID\c s in the .C uuidname.txt file. .PP .C lb_admin examines or modifies only one database at a time, refered to as the ``current database''. The .C use_broker command selects the type of Location Broker database, .SM GLB or .SM LLB. The .C set_broker command selects the host whose .SM GLB or .SM LLB database is to be accessed. Of course, if you modify one replica of a replicated .SM GLB database, the modification is propagated to the other replicas of that database. .PP On HP-UX 10.x systems, though the DCE .C rpcd daemon provides both NCS .SM LLB service and DCE .SM RPC Endpoint Map service, .C lb_admin administers only the .SM LLB database, not the Endpoint Map. .SS Options .C lb_admin recognizes the following options: .RS .TP 10 .C -nq Do not query for verification of wildcard expansions in .C unregister operations. .TP .CI - version Display the version of .SM NCK that this .C lb_admin belongs to, but do not start the tool. .RE .SS Commands In .CR lookup , .CR register , and .C unregister commands, the .IR object , .IR type , and .I interface arguments can be either character strings representing .SM UUID\c s or textual names corresponding to .SM UUID\c s, as described earlier. .RS .TP 12 .CR a [ dd ] Synonym for .CR register . .TP .CR c [ lean ] Find and delete obsolete entries in the current database. .IP With this command, .C lb_admin attempts to contact each server registered in the database. If the server responds, the entry for its registration is left intact in the database. If the server does not respond, .C lb_admin tries to look up its registration in the .SM LLB database at the host where the server is located, displays the result of this lookup, and asks whether to delete the entry. If a server responds, but its .SM UUID\c s do not match the entry in the database, .C lb_admin displays this result and asks whether to delete the entry. .IP There are two situations in which it is likely that a database entry should be deleted: .RS .RS .TP 3 \(bu The server does not respond, .C lb_admin succeeds in contacting the .SM LLB at the host where the server is located, and the server is not registered with that .SM LLB. The server is probably no longer running. .TP \(bu A server responds, but its .SM UUID\s0s do not match the entry in the database. The server that responded is not the one that registered the entry. .RE .RE .IP Entries that meet either of these conditions are probably safe to delete and are considered eligible for "automatic deletion" (described in the next paragraph). In other situations, it is best not to delete the entry unless you can verify directly that the server is not running (for example, by listing the processes running on its host). .IP When .C lb_admin asks whether you want to delete an entry, you have four ways to respond. .CR y [ es ] deletes the entry. .CR n [ o ] leaves the entry intact in the database. After a .C yes or a .CR no , .C lb_admin proceeds to check the next entry in the current database. .C g [ o ] invokes automatic deletion in which all eligible entries are deleted and all ineligible entries are left intact without your being queried, until all entries have been checked. .CR q [ uit ] terminates the .C clean operation. .TP .CR d [ elete ] Synonym for .CR unregister . .TP .ift \f4\s+1h\f1\s0[\f4\s+1elp\f1\s0] [\f2command\f1] or \f4\s+1?\f1\s0 [\f2command\f1] .ifn \f3h\f1[\f3elp\f1] [\f2command\f1] or \f3?\f1 [\f2command\f1] Display a description of the specified .I command or, if none is specified, list all of the .C lb_admin commands. .TP .CR l [ ookup "] \f2object type interface\f1" Look up and display all entries with matching .IR object , .IR type , and .I interface fields in the current database. You can use asterisks as wildcards for any of the arguments. If all the arguments are wildcards, .C lookup displays the entire database. .TP .CR q [ uit ] Exit the .I lb_admin session. .TP .ift \f4\s+1r\f1\s0[\f4\s+1egister\f1\s0] \f2object type interface location annotation \f1[\f2flag\f1] .ifn \f3r\f1[\f3egister\f1] \f2object type interface location annotation \f1[\f2flag\f1] Add the specified entry to the current database. Use an asterisk to represent a nil .SM UUID in the .IR object , .IR type , and .I interface fields. .IP The .I location is a string in the format .IC family : host [ port ]\f1, where .I family is an address family, .I host is a host name, and .I port is a port number. Possible values for .I family include .C ip and .CR dds . Use a leading .C # to indicate that a host name is in the standard numeric form. For example, .CR ip:vienna[1756] , .CR ip:#192.5.5.5[1791] , .CR dds://salzburg[515] , and .C dds:#575d.542e[452] are all acceptable .I location specifiers. (All .SM HP-UX hosts have .C ip as the .IR family .) .IP The .I annotation is a string of up to 64 characters annotating the entry. Use double quotation marks to delimit a string that contains a space or contains no characters. To embed a double quotation mark in the string, precede it with a backslash. .IP The .I flag is either .C local (the default) or .CR global , indicating whether the entry should be marked for local registration only or for registration in both the .SM LLB and .SM GLB databases. The .I flag is a field that is stored with the entry; it does not affect where the entry is registered. The .C set_broker and .C use_broker commands select the particular .SM LLB or .SM GLB database for registration. .TP .ift \f4\s+1s\f1\s0[\f4\s+1et_broker\f1\s0] [\f2broker_switch\f1] \f2host\f1 .ifn \f3s\f1[\f3et_broker\f1] [\f2broker_switch\f1] \f2host\f1 Set the host for the current .SM LLB or .SM GLB. If you specify .C global as the .IR broker_switch , .C set_broker sets the current .SM GLB; otherwise, it sets the current .SM LLB. The .I host is a string in the format .IC family : host\f1, where .I family is an address family and .I host is a host name. Possible values for .I family include .C ip and .CR dds . Use a leading .C # to indicate that a host name is in the standard numeric form. For example, .CR ip:prague , .CR ip:#192.5.5.5 , .CR dds://linz , and .C dds:#499d.590f are all acceptable .I host specifiers. (All .SM HP-UX hosts have .C ip as the .IR family .) .IP Issue .CR use_broker , not this command, to determine whether subsequent operations will access the .SM LLB or the .SM GLB. .TP .ift \f4\s+1set_t\f1\s0[\f4\s+1imeout\f1\s0] [\f4\s+1short\f1\s0 \(or \f4\s+1long\f1\s0] .ifn \f3set_t\f1[\f3imeout\f1] [\f3short\f1 \(or \f3long\f1] Set the timeout period used by .C lb_admin for all of its operations. With an argument of .C short or .CR long , .C set_timeout sets the timeout accordingly. With no argument, it displays the current timeout value. .TP .CR u [ nregister "] \f2object type interface location\f1" Delete the specified entry from the current database. .IP .I location is a string in the format .IC family : host\c .CI [ \|port\| ]\c , where .I family is an address family, .I host is a host name, and .I port is a port number. Possible values for .I family include .C ip and .CR dds . Use a leading .C # to indicate that a host name is in the standard numeric form. For example, .CR ip:vienna[1756] , .CR ip:#192.5.5.5[1791] , .CR dds://salzburg[515] , and .C dds:#575d.542e[452] are all acceptable .I location specifiers. (All .SM HP-UX hosts have .C ip as the .IR family .) .IP Use an asterisk as a wildcard in the .IR object , .IR type , and .IR interface fields to match any value for the field. Unless .C lb_admin -nq was used to suppress queries, .C unregister asks whether to delete each matching entry. .CR y [ es ] deletes the entry. .CR n [ o ] leaves the entry in the database. .CR g [ o ] deletes all remaining database entries that match, without further interaction. .CR q [ uit ] terminates the .C unregister operation without deleting any more entries. .TP .CR us [ e_broker "] [\f2broker_switch\fP]" Select the type of database that subsequent operations will access, .SM GLB or .SM LLB. The .I broker_switch is either .C global or .CR local . If .I broker_switch is not specified, .C use_broker tells whether the current database is global or local. .IP Use .C set_broker to select the host whose .SM GLB or .SM LLB is to be accessed. .SH SEE ALSO drm_admin(1M), glbd(1M), rpcd(1M), uuidname.txt(4). .\" .\" index@\f4lb_admin\f1 \- Location Broker administrative tool@@@\f3lb_admin(1M)\f1 .\" index@Location Broker administrative tool@@@\f3lb_admin(1M)\f1 .\" index@administrative tool, Location Broker@@@\f3lb_admin(1M)\f1 .\" .\" toc@\f3lb_admin(1M)\f1:\0\0\f4lb_admin\f1@@@Location Broker administrative tool .\" .\" fileset_database@lb_admin.1m SYS-ADMIN-MAN .\" $Header: lb_test.1m,v 72.4 94/10/27 14:39:44 ssa Exp $ .TA l .TH lb_test 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lb_test \- test the Location Broker .SH SYNOPSIS .C /usr/sbin/ncs/lb_test .RC [ -unreg ] .RC [ -num .IR entries\| ] .RC [ -time .IR seconds\| ] .SH DESCRIPTION .I lb_test tests the functionality of the Global Location Broker .SM (GLB) and Local Location Broker .SM (LLB), parts of the Network Computing System .SM (NCS). .PP .C lb_test repeatedly registers and looks up entries with the .SM GLB and with the local .SM LLB. It fails if a .SM GLB or .SM LLB does not exist, is an incorrect version, is inaccessible, or is functioning improperly. The host that runs .C lb_test must also run the Remote Procedure Call daemon .RC ( rpcd ) and must be able to reach a Global Location Broker daemon .RC ( glbd ). .PP A Location Broker entry contains Universal Unique Identifiers .SM (UUIDs) for an object, the type of the object, and an interface to the object, together with the location of a server exporting the interface. To avoid flooding the .SM GLB and .SM LLB databases, .C lb_test always uses the same three .SM UUID\s0s for all registrations. .PP .C lb_test loops, making 256 passes. Each iteration of the loop attempts to register a set of entries and look them up. .C lb_test attempts to unregister the entries when it exits. .PP Command-line options specify the number of entries that .C lb_test registers at each iteration and the amount of time that it waits between iterations. If options are not specified, .C lb_test uses default values. .PP If .C lb_test fails, try running .C lb_admin to access a Global Location Broker; if .C lb_admin also fails, there is probably a problem in the .SM GLB configuration. .SS Options .TP .CI -num \0entries Register the specified number of entries. The default for .I entries is 5. .TP .CI -time \0seconds Sleep for the specified number of seconds between iterations. The default is no waiting. .TP .C -unreg Unregister all entries of .C lb_test type .SM UUID. After unregistering the entries, .C lb_test terminates. .SS Sample Output This section shows the output that .C lb_test produces if the Location Broker is operating correctly. Most of the output has been omitted as indicated by the ellipses .RC ( ... ). .PP If the hosts and/or the network used in the test are heavily loaded, additional informational messages may be printed. These message are printed when the Remote Procedure Call .SM (RPC) runtime library is recovering from slow transmissions or lost packets. .nf .IP .RC $ \0lb_test .C "Handling 5 registrations with no time delay" .C "Starting test loop..." .C " Pass 0 .C " Pass 1 .C " Pass 2 .C " Pass 3 \h'.6i'. \h'.6i'. \h'.6i'. .C " Pass 252 .C " Pass 253 .C " Pass 254 .C " Pass 255 .C Unregistering... $ .fi .SH SEE ALSO glbd(1M), perf(1M), rpcd(1M). .\" .\" index@\f4lb_test\f1 \- test the Location Broker@@@\f3lb_test(1M)\f1 .\" index@test the Location Broker@@@\f3lb_test(1M)\f1 .\" index@Location Broker, test the@@@\f3lb_test(1M)\f1 .\" .\" toc@\f3lb_test(1M)\f1:\0\0\f4lb_test\f1@@@test the Location Broker .\" .\" fileset_database@lb_test.1m SYS-ADMIN-MAN .\" $Header: link.1m,v 76.1 95/07/10 17:05:32 ssa Exp $ .TA l .TH link 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME link, unlink \- execute .CR link() and .CR unlink() system calls without error checking .SH SYNOPSIS .CR /usr/sbin/link .I file1 .I file2 .PP .CR /usr/sbin/unlink .I file .SH DESCRIPTION The .CR link and .CR unlink commands perform their respective system calls .RC ( link() \ or\ unlink() ) on their arguments, abandoning most error checking. .PP These commands can be executed only by users who have appropriate privileges. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C link behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .CR link and .CR unlink return the following values: .RS .TP .PD 0 .CR 0 Operation successful. .TP .CR 1 Input syntax error. .TP .CR 2 The .CR link() or .CR unlink() call failed. .PD .RE .SH WARNINGS If a directory that contains files other than .CR . and .CR .. is unlinked, the files become orphans, unless they are also linked by some other directory. .PP Not all file systems permit linking to directories. .SH SEE ALSO ln(1), rm(1), link(2), unlink(2). .SH STANDARDS CONFORMANCE .CR link ": SVID2, SVID3" .PP .CR unlink ": SVID2, SVID3" .\" .\" index@\f4link\f1 \- execute \f4link()\f1 system call without error checks@@@\f3link(1M)\f1 .\" index@\f4unlink\f1 \- execute \f4unlink()\f1 system call without error checks@@@\f3link(1M)\f1 .\" index@\f4link()\f1 system call, execute without error checks@@@\f3link(1M)\f1 .\" index@\f4unlink()\f1 system call, execute without error checks@@@\f3link(1M)\f1 .\" .\" toc@\f3link(1M)\f1:\0\0\f4link\f1, \f4unlink\f1@@@execute \f4link()\f1 and \f4unlink()\f1 system calls without error checking .\" toc@\f4unlink\f1:\0\0execute \f4unlink()\f1 system call without error checking@@@see \f3link(1M)\f1 .\" .\" links@link.1m unlink.1m .\" $Header: linkloop.1m,v 76.1 95/08/23 17:28:05 ssa Exp $ .TA l .TH linkloop 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME linkloop \- verify LAN connectivity with link-level loopback .SH SYNOPSIS .CR linkloop .RC [ \-i .IR NetMgmtID ] .RC [ \-n .IR count ] .RC [ \-r .IR rif ] .RC [ \-s .IR size ] .RC [ \-t .IR timeout ] .ifn .br .ifn \0\0\0\0 .RC [ \-v ] .IR linkaddr \0...\& .SH DESCRIPTION The .CR linkloop command uses IEEE 802.2 link-level test frames to check connectivity within a local area network (LAN). .PP .IR linkaddr is the hardware station address of a remote node. Several addresses can be specified at one time. .PP .CR linkloop tests the connectivity of the local node and the remote node specified by each hardware station address. The hardware station address of a remote node can be found by executing .CR lanscan on the remote node. This hardware station address is usually represented as a hexadecimal string prefixed with .CR 0x . It can also be represented as a octal string prefixed with .CR 0 or as a decimal string. The hardware station address must not be a multicast or broadcast address. .SS Options .CR linkloop recognizes the following options: .RS .TP 20 .CI \-i \0NetMgmtID Specify the Network Management ID to use. If this option is omitted, .CR linkloop uses the first .I NetMgmtID it encounters in an internal data structure. .TP .CI \-n \0count Set the number of frames to transmit. If .I count is .CR 0 , .CR linkloop transfers frames indefinitely until an interrupt signal (defined by the user shell) is received. The default value for .I count is .CR 1 . .TP .CI \-r \0rif Specify the particular bridge route over which token ring packets should be delivered. .I rif is the .I routing information field used for token-ring networks. Its value is given as an even number of hexadecimal bytes separated by colons, up to a maximum of 16 bytes. .TP .CI \-s \0size Set the size in bytes of the data message to send. The maximum data size is dependent on the type of LAN link being used. The default value is the maximum data byte count that can be used for the particular link. .TP .CI \-t \0timeout Set the amount of time in seconds to wait for a reply from the remote node before aborting. If .I timeout is .CR 0 , .CR linkloop waits indefinitely for a reply. The default value for is 2 seconds. .TP .CR \-v Set the verbose option. In addition to the regular summary of test results, this option displays more extensive error information. If there are header or length errors, appropriate messages are displayed. All verbose output is preceded by the number of replies accepted before an error occurred. .RE .SS Connectivity Test Results .CR linkloop aborts upon receipt of an interrupt signal. If aborted, the current results are printed. .PP .CR linkloop prints the result of the link-level connectivity test. If the test fails, it prints a summary of the test and indicates the type of error. The possible messages are: .PP .C "address has bad format" .IP Incorrect hardware station address was entered on the command line. .PP .C "address is not individual" .IP Station address entered on the command line is either a multicast or broadcast address. .PP .C "frames sent" .IP Total number of frames sent. .PP .C "frames received correctly" .IP Total number of frames received without errors. .PP .C "frames with length error" .IP Received frame length does not match transmitted frame length. If the verbose option is set, the length received is printed. .PP .C "frames with data error" .IP Received frame does not match transmitted frame. .PP .C "frames with header error" .IP Number of frames received containing unexpected frame header information. Either the source address does not match the remote address, the destination address does not match the local address, or the control field is not the TEST .BR "frame control field" . These frames are ignored. .CR linkloop continues to try to receive the reply frame until the .CR read operation times out. .PP .C "reads that timed out" .IP Count of how many .CR read operations timed out before the reply was received. .RE .SH DIAGNOSTICS .PP .C "illegal count parameter" .IP The .I count specified in the .CR \-n option is not a nonnegative integer, or the number specified is too large for the local computer. .PP .C "illegal timeout parameter" .IP The .I timeout specified in the .CR \-t option is not a nonnegative integer, or the value specified multiplied by 1000 is too large for the local computer. .PP .C "illegal size parameter" .IP The .I size specified in the .CR \-s option is not in the range from 0 to the maximum link data size. Remember that the maximum link data size can vary in value for different LAN connection types. .PP .C "No valid interface associated with Net Mgmt ID" .IP The .I NetMgmtID specified in the .CR \-i option is not a valid network management ID. .PP .C "Unable to open device file /dev/dlpi" .IP Device file .CR /dev/dlpi does not exist. .PP .C "invalid rif parameter " .IP The .I rif value in the .CR \-r option is invalid. .PP .C "rif parameter too long" .IP The number of bytes in .I rif in the .CR \-r option exceeded the maximum allowed (16). .PP .C "rif parameter length must be even" .IP The number of bytes in .I rif in the .CR \-r option is odd. The number of bytes must be even. .SH AUTHOR .CR linkloop was developed by HP. .SH SEE ALSO lanadmin(1M), lanscan(1M), lan(7). .\" .\" index@\f4linkloop\f1 \- verify LAN connectivity with link-level loopback@@@\f3linkloop(1M)\f1 .\" index@\f1verify LAN connectivity with link-level loopback@@@\f3linkloop(1M)\f1 .\" index@\f1LAN connectivity, verify with link-level loopback@@@\f3linkloop(1M)\f1 .\" index@\f1connectivity, verify LAN with link-level loopback@@@\f3linkloop(1M)\f1 .\" index@\f1link-level loopback to verify LAN connectivity@@@\f3linkloop(1M)\f1 .\" index@\f1loopback, link-level, to verify LAN connectivity@@@\f3linkloop(1M)\f1 .\" .\" toc@\f3linkloop(1M)\f1:\0\0\f4linkloop\f1@@@verify LAN connectivity with link-level loopback ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "list child"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lcdscp\*O commands" "\*Llist child\*O" .iX "-[" "child pointers" "viewing" .SH NAME .PP \*Llist child\*O - Displays a list of all the child pointers whose names match the specified child name .wH "" .SH "SYNOPSIS" .PP \*Lcdscp list child\*O \*Vchild-name\*O \*L[with\*O \*Vattribute-name = attribute-value\*O\*L]\*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vchild-name\*O" The full name of a specific child pointer. The last simple name can contain wildcard characters. .LI "\*Vattribute-name\*O" The name of a particular attribute. .LI "\*Vattribute-value\*O" The value of a particular attribute. .wH "" .LE .SH "DESCRIPTION" .PP The \*Llist child\*O command displays a list of all the child pointers whose names match the specified child name. The last simple name can contain wildcard characters. You can use a \*Lwith\*O \*Vattribute-name = attribute-value\*O clause to limit output only to child pointers whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). .SS "Privilege Required" .PP You must have read permission to the directory that stores the child pointer. If you use a \*Lwith\*O \*Vattribute-name = attribute-value\*O clause in the command, you also need read or test permission to the selected child pointers. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command displays a list of all the child pointers named in the \*L/.:/sales\*O directory: .PP .iS \*Ccdscp>\*L list child /.:/sales/*\*O \*C LIST CHILD /.../abc.com/sales AT 1991-10-15-15:56:00 Q1 Q2 Q3 Q4\*O .PP .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lcreate child(1m)\*O, \*Ldelete child(1m)\*O, \*Lshow child(1m)\*O .wH "" .wH "" .iX "-]" "\*Lcdscp\*O commands" "\*Llist child\*O" .iX "-]" "child pointers" "viewing" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "list clearinghouse"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lcdscp\*O commands" "\*Llist clearinghouse\*O" .iX "-[" "clearinghouses" "viewing" .SH NAME .PP \*Llist clearinghouse\*O - Displays a list of all the clearinghouses whose names match the specified clearinghouse name .wH "" .SH "SYNOPSIS" .PP \*Lcdscp list clearinghouse\*O \*Vclearinghouse-name\*O \*L[with\*0 \*Vattribute-name = attribute-value\*0\*L]\*0 .wH "" .SH "ARGUMENTS" .VL .LI "\*Vclearinghouse-name\*O" The full name of a specific clearinghouse. The last simple name can contain wildcard characters. .LI "\*Vattribute-name\*O" The name of a particular attribute. .LI "\*Vattribute-value\*O" The value of a particular attribute. .wH "" .LE .SH "DESCRIPTION" .PP The \*Llist clearinghouse\*O command displays a list of all the clearinghouses whose names match the specified name. The last simple name can contain wildcards. You can use a \*Lwith\*O \*Vattribute-name = attribute-value\*O clause to limit output only to clearinghouses whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). .SS "Privilege Required" .PP You must have read permission to the directory that stores the associated clearinghouse object entry. If you use a \*Lwith\*O \*Vattribute-name = attribute-value\*O clause in the command, you also need read or test permission to the selected clearinghouses. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command displays a list of all the clearinghouses named in the root directory: .iS \*Ccdscp>\*L list clearinghouse /.:/*\*O \*C LIST CLEARINGHOUSE /.../abc.com/* AT 1991-10-15-15:56:00 /.../abc.com/Munich_CH /.../abc.com/Paris_CH\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lclear clearinghouse(1m)\*O, \*Lcreate clearinghouse(1m)\*O, \*Ldelete clearinghouse(1m)\*O, .zA "defect,7613,R1.0.3,removed set clearinghouse" .zZ "defect,7613,R1.0.3,removed set clearinghouse" \*Lset cdscp preferred clearinghouse(1m)\*O, \*Lshow cdscp preferred clearinghouse(1m)\*O, \*Lshow clearinghouse(1m)\*O .wH "" .wH "" .iX "-]" "\*Lcdscp\*O commands" "\*Llist clearinghouse\*O" .iX "-]" "clearinghouses" "viewing" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "list directory"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "directories" "viewing (CDS)" .iX "-[" "\*Lcdscp\*O commands" "\*Llist directory\*O" .SH NAME .PP \*Llist directory\*O - Displays a list of all the directories whose names match the specified directory name .wH "" .SH "SYNOPSIS" .PP \*Lcdscp list directory\*O \*Vdirectory-name\*O \*L[with\*0 \*Vattribute-name = attribute-value\*0\*L]\*0 .wH "" .SH "ARGUMENTS" .VL .LI "\*Vdirectory-name\*O" The full name of a specific directory. The last simple name can contain wildcard characters. .LI "\*Vattribute-name\*O" The name of a particular attribute. .LI "\*Vattribute-value\*O" The value of a particular attribute. .wH "" .LE .SH "DESCRIPTION" .PP The \*Llist directory\*O command displays a list of all the directories whose names match the specified directory name. The last simple name can contain wildcards. You can use a \*Lwith\*O \*Vattribute-name = attribute-value\*O clause to limit output only to directories whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). .SS "Privilege Required" .PP You must have read permission to the parent directory. If you use a \*Lwith\*O \*Vattribute-name = attribute-value\*O clause in the command, you also need read or test permission to the selected directories. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command displays the names of all the directories in the \*L/.:/sales\*O directory: .iS \*Ccdscp>\*L list directory /.:/sales/* \*C LIST DIRECTORY /.../abc.com/sales AT 1991-10-15-15:43:58 atlanta austin boston chicago ontario ny seattle\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ladd directory(1m)\*O, \*Lcreate directory(1m)\*O, \*Ldelete directory(1m)\*O, \*Lremove directory(1m)\*O, \*Lset directory(1m)\*O, \*Lset directory to skulk(1m)\*O, \*Lshow directory(1m)\*O .wH "" .wH "" .iX "-]" "directories" "viewing (CDS)" .iX "-]" "\*Lcdscp\*O commands" "\*Llist directory\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "list link"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lcdscp\*O commands" "\*Llist link\*O" .iX "-[" "soft links" "viewing" .SH NAME .PP \*Llist link\*O - Displays a list of all the soft links whose names match the link name that you specify .wH "" .SH "SYNOPSIS" .PP \*Lcdscp list link\*O \*Vlink-name\*O \*L[with\*0 \*Vattribute-name = attribute-value\*0\*L]\*0 .wH "" .SH "ARGUMENTS" .VL .LI "\*Vlink-name\*O" The full name of a specific soft link. The last simple name can contain wildcard characters. .LI "\*Vattribute-name\*O" The name of a particular attribute. .LI "\*Vattribute-value\*O" The value of a particular attribute. .wH "" .LE .SH "DESCRIPTION" .PP .zA "defect,6281,R1.0.2,Added description" The \*Llist link\*O command displays a list of all the soft links whose names match the link name that you specify. The last simple name can contain wildcard characters. You can use a \*Lwith\*O \*Vattribute-name = attribute-value\*O clause to limit output only to soft links whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). This command does not list the name of the directory, object entry, or other soft link to which the soft link points. .zZ "defect,6281,R1.0.2,Added description" .SS "Privilege Required" .PP You must have read permission to the directory that stores the soft link. If you use a \*Lwith\*O \*V attribute-name = attribute-value\*O clause in the command, you also need read or test permission to the selected soft links. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command displays a list of all the soft links whose names begin with the letter \*Ll\*O in the directory \*L/.:/admin\*O. .iS \*Ccdscp>\*L list link /.:/admin/l* \*C LIST SOFTLINK /.../abc.com/admin AT 1991-10-15-15:54:38 lnk01 lnk02 lnk03 lnk04 lnk05 lnk06\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lcreate link(1m)\*O, \*Ldelete link(1m)\*O, \*Lremove link(1m)\*O, \*Lset link(1m)\*O, \*Lshow link(1m)\*O .wH "" .wH "" .iX "-]" "soft links" "viewing" .iX "-]" "\*Lcdscp\*O commands" "\*Llist link\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "list object"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "objects" "viewing entries" .iX "-[" "\*Lcdscp\*O commands" "\*Llist object\*O" .SH NAME .PP \*Llist object\*O - Lists the specifies object entries (including clearinghouse object entries) .wH "" .SH "SYNOPSIS" .PP \*Lcdscp list object\*O \*Vobject-name\*O \*L[with\*0 \*Vattribute-name = attribute-value\*0\*L]\*0 .wH "" .SH "ARGUMENTS" .VL .LI "\*Vobject-name\*O" The full name of a specific object entry. The last simple name can contain wildcard characters. .LI "\*Vattribute-name\*O" The name of a particular attribute. .LI "\*Vattribute-value\*O" The value of a particular attribute. .wH "" .LE .SH "DESCRIPTION" .PP The \*Llist object\*O command displays a list of all the object entries (including clearinghouse object entries) whose names match the object entry name that you specify. The last simple name can contain wildcard characters. You can use a \*Lwith\*O \*Vattribute-name = attribute-value\*O clause to limit output only to object entries whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). .SS "Privilege Required" .PP You must have read permission to the directory that stores the object entry. If you use a \*Lwith\*O \*Vattribute-name = attribute-value\*O clause in the command, you also need read or test permission to the selected object entries. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command displays a list of all the object entries named in the directory \*L/.:/eng\*O. .iS \*Ccdscp>\*L list object /.:/eng/* \*C LIST OBJECT /.../abc.com/eng AT 1991-10-15-15:53:06 juno test_stats work_disk1 work_disk2\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ladd object(1m)\*O, \*Lcreate object(1m)\*O, \*Ldelete object(1m)\*O, \*Lremove object(1m)\*O, \*Lset object(1m)\*O, \*Lshow object(1m)\*O .wH "" .wH "" .iX "-]" "objects" "viewing entries" .iX "-]" "\*Lcdscp\*O commands" "\*Llist object\*O" .\" $Header: localedef.1m,v 76.1 95/08/03 18:08:35 ssa Exp $ .TA l .TH localedef 1 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME localedef \- generate a locale environment .SH SYNOPSIS .C localedef .RC [ -cnvw ] .RC [ -C .IR compiler_options\| ] .RC [ -L .IR loader_options\| ] .RC [ -m .IR method_file\| ] .RC [ -f .IR charmap_file\| ] .RC [ -i .IR locale_definition\| ] .RI \|locale_name\| .SH DESCRIPTION .C localedef sets up the language environment for the named locale. .C localedef reads a .B locale definition file (see .IR localedef (4) for a detailed description) from standard input (default) or from .IR locale_definition file, creates a locale file with the same name as specified for the .IR locale_name parameter, and optionally installs this locale in the appropriate directory. Installation of public locales (those accessible to all users) requires appropriate privileges. Creation of locales (both private and public) requires access to the ANSI C compiler. .SS Options .C localedef recognizes the following options: .ift .RS .TP 15 .C -c Create permanent output even if warning messages have been generated. .TP .C -n (noinstall) Create the locale file in the current directory. .TP .C -v (verbose) Generate as many diagnostic messages as possible. .TP .C -w Generate additional warning messages for duplicate definitions and ellipses use in the .C LC_COLLATE category. .TP .CI -f \0charmap_file If .B locale definition file contains symbolic names (of the form .CI < name >\c ) use .I charmap_file. See .I charmap(4) for a description of the format of a .IR charmap_file . .TP .CI -i \0locale_definition Use .I locale_definition file as input, instead of standard input (default). .TP .CI -m \0method_file Use the specified .I method_file to overwrite use of default methods in processing the .B locale definition . .TP .CI -C \0compiler_options Specify additional compiler options to be applied in compiling the locale. See .I cc(1) for a complete list of options. .TP .CI -L \0loader_options Specify additional loader options to be applied in linking the locale. See .I ld(1) for a complete list of options. .TP .I locale_name This argument is required, and identifies the name of the language following the naming convention of the .C LANG environment variable (see .IR environ (5)): .RS .IP .IR language\| [ \|_territory\| ]\|[ \|.codeset\| ] .RE .ift .RE .PP The following is a brief description of the components that make up a locale. For a complete description of the form and syntax of a .B locale defintion file, see .IR localedef (4). For a complete description of the form and effects of a charmap file, see .IR charmap (4). .PP Six categories of data in the .C locale_name file are recognized by .IR setlocale (3C), and make up a language definition: .RS .TP 20 .C LC_COLLATE Information in this category affects behavior of regular-expressions and .SM NLS string-collation functions. .TP .C LC_CTYPE Information in this category affects behavior of character classification and conversion functions. .TP .C LC_MONETARY Information in this category affects behavior of functions that handle monetary values. .TP .C LC_NUMERIC Information in this category affects handling of the radix character in formatted-input/output and string-conversion functions. .TP .C LC_TIME Information in this category affects behavior of time-conversion functions. .TP .C LC_MESSAGES This category contains information affecting interpretation of yes/no responses. .RE .PP A .B locale definition file also consists of six categories. The beginning of each category is identified by a .B category tag having the form .CI LC_ category where .I category is one of the following: .CR CTYPE , .CR COLLATE , .CR MONETARY , .CR NUMERIC , .CR TIME , or .CR MESSAGES . The end of each category is identified by a tag consisting of the word .C END followed by a space and the category identifier; for example, .CR "END LC_COLLATE" . Categories can appear in any order in the .B locale definition file. At least one category specifications is required. If a category is not specified, .C setlocale() sets up the default ``C'' locale for that category (see .IR setlocale (3C) and .IR lang (5)). .PP Each category is composed of one or more statements. Each statement begins with a keyword followed by one or more expressions. An expression is a set of well-formed metacharacters, strings, and constants. .C localedef also recognizes comments and separators. .PP More than one definition specified for each category constitutes a hard error (causes .C localedef to exit without generating a locale). Any category can be specified by the keyword .C copy followed by the name of a valid locale. This causes the information for the category to be identical to that in the named locale. Note that the .C copy keyword, if used for a category, must be the first and only keyword following the category tag. .PP A methods file is used to creat locales for user-specific character encoding schemes. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the locale to use when neither .C LC_ALL or the other category variables specify a locale. .PP .C LC_ALL determines locale to be used. It overrides any values specified by .C LANG or any other .C LC_* variables. .PP .C LC_COLLATE and .C LC_CTYPE have no effect on the processing of localedef, which behaves as if these two variables were set to the C locale. .PP .C LC_MESSAGES determines the language in which messages are displayed. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .C localedef returns the following values: .RS .TP 6 .B \00 No errors occurred and the locale was successfully created. .PD 0 .TP .B \01 Warnings occurred and the locale was successfully created. .TP .B \02 The locale specification exceeded implementation limits or the coded character set used is not supported. .TP .B >3 Warnings or errors occurred, and no output was generated. .PD .SH AUTHOR .C localedef was developed by OSF and HP. .SH FILES .C /usr/lib/nls/config .br .C /usr/lib/nls/loc/src .br .C /usr/lib/nls/loc/charmaps .br .C /usr/lib/nls/loc/methods .br .CI /usr/lib/nls/loc/locales/ language\c .RC [ _\c .IR territory\| ]\c .RC [ .\c .IR codeset\| ]\c .SH SEE ALSO locale(1), localedef(4), charmap(4), setlocale(3C), environ(5). .SH STANDARDS CONFORMANCE .CR localedef ": XPG4, POSIX.2" .\" .\" index@\f4localedef\f1 \- generate a locale environment@@@\f3localedef(1M)\f1 .\" index@\f1generate a locale environment@@@\f3localedef(1M)\f1 .\" index@\f1locale environment, generate@@@\f3localedef(1M)\f1 .\" .\" toc@\f3localedef(1M)\f1:\0\0\f4localedef\f1@@@generate a locale environment\f1 file .\" .\" fileset_database@localedef.1m SYS-ADMIN-MAN .\" $Header: lockd.1m,v 78.1 96/01/03 15:16:35 ssa Exp $ .TA l .TH lockd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lockd \- network lock daemon .SH SYNOPSIS .C /usr/sbin/rpc.lockd .RC [ -l .IR log_file ] .RC [ -t .IR timeout ] .RC [ -g .IR graceperiod ] .SH DESCRIPTION .CR lockd is an RPC server that processes NFS file locking requests from the local kernel or from another remote lock daemon. .CR lockd forwards lock requests for remote data to the server site's lock daemon through the RPC/XDR package (see .IR rpc (3C)). .CR lockd then requests the status monitor daemon, .CR statd for monitor service (see .IR statd (1M)). The reply to the lock request is not sent to the kernel until the status daemon and the server site's lock daemon have replied. .PP If either the status monitor or server site's lock daemon is unavailable, the reply to a lock request for remote data is delayed until all daemons become available. .PP When a server recovers, it waits for a grace period for all NFS client-site .CR lockd s to submit reclaim requests. Client-site .IR lockd s are notified by the .CR statd of the server recovery, and promptly resubmit previously granted lock requests. If a .CR lockd fails to secure a previously granted lock at the server site, the .CR lockd sends a .CR SIGLOST to the process holding that lock. .SS Options .CR lockd recognizes the following options and command-line arguments: .RS .TP 20 .CI -l \0log_file Log any errors to the named log file .IR log_file . Errors are not logged if the .CR -l option is not specified. .IP Information logged to the file includes date and time of the error, host name, process ID and name of the function generating the error, and the error message. .TP .CI -t \0timeout .CR lockd uses .I timeout (seconds) as the interval instead of the default value (10 seconds) to retransmit a lock request to the remote server. Note that changing this value also changes the value for grace period duration. .TP .CI -g \0graceperiod .CR lockd uses .RI [\|1\|+\|( \|graceperiod\| / \|timeout\| )]\|\(mu\| timeout (seconds) as the grace period duration instead of the default value .RI (\|5\(mu\| timeout seconds). If both .CR -t and .CR -g are specified, the .CR -t should appear first since the grace period duration is dependent on the value of timeout. .SH AUTHOR .CR lockd was developed by Sun Microsystems, Inc., and HP. .SH SEE ALSO fcntl(2), lockf(2), signal(2), statd(1M). .\" .\" index@\f4lockd\f1 \- network lock daemon@@@\f3lockd(1M)\f1 .\" index@network lock daemon@@@\f3lockd(1M)\f1 .\" index@lock daemon, network@@@\f3lockd(1M)\f1 .\" index@daemon, network lock@@@\f3lockd(1M)\f1 .\" .\" toc@\f3lockd(1M)\f1:\0\0\f4lockd\f1@@@network lock daemon .\" .\" links@lockd.1m rpc.lockd.1m .\" $Header: logins.1m,v 78.1 95/12/20 10:58:26 ssa Exp $ .TA l .TH logins 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME logins \- display system and user login data .SH SYNOPSIS .C logins .RC [ -admopstux ] .RC [ -g .IR groups ] .RC [ -l .IR logins ] .SH DESCRIPTION .C logins displays data concerning system and user logins. The format and content of the output is controlled by command options and may include: system or user login, user ID number, .C /etc/passwd comment field value (e.g., user name, etc...), primary group name, primary group ID, supplementary group names, supplementary group IDs, home directory, login shell, user security level, user audit events, and password aging parameters. The default data is: login, user ID, primary group name, primary group ID, and .C /etc/passwd comment field value. Output is sort by user ID, with user logins following system logins. The default output consists of login, user ID, primary group, primary group ID and comment field formatted into columns. .PP The following options are available to this command: .TP 5 .C -a Displays two account expiration fields. The fields show how long the account can be unused (in days) before it becomes inactive and the date the account will expire. .TP .C -d Display logins with duplicate UIDs. .TP .C -m Show multiple group membership data. .TP .C -o Display with alternate format of one line of colon separated fields. .TP .C -p Display logins with no passwords .TP .C -s Display all system logins .TP .C -t Sort output by login rather than UID. .TP .C -u Display all user logins. .TP .C -x Display extended information about selected users. This extended information includes home directory, login shell and password aging data, each on its own line. Password information consists of password status (PS for valid password, LK for locked and NP for no password) and, if a password is present, date of last change, required number of days between changes, and number of days allowed between changes. In the case of non-trusted systems, the date of last change will be the latest Thursday since the change. .TP .CI "-g " groups Display all users belonging to .IR groups , sorted by login. A comma separated list specifies multiple groups. .TP .CI "-l " logins Display the requested .IR logins . A comma separated list specifies multiple logins. .PP Multiple options may be used. Any login matching any of the criteria will be displayed. A login will be displayed only once, even if it meets multiple criteria. .SH EXAMPLES .RS 5 .TP 5 .C logins list all logins in default format. .TP .C logins -p -d list all logins that have no password or have a duplicate UID in default format. .TP .C logins -s -o list all system logins in the alternate format. .RE .SH FILES .TP 30 .PD 0 .C /etc/passwd HP-UX password file. .TP .C /etc/group HP-UX group file. .PD .SH SEE ALSO listusers(1), passwd(1), group(4), passwd(4). .SH STANDARDS COMPLIANCE .CR logins ": SVID3" .\" index@\f4logins\f1 \- display login data@@@\f3logins(1m)\f1 .\" index@display system and user login data@@@\f3logins(1m)\f1 .\" index@login data, display@@@\f3logins(1m)\f1 .\" index@system login data, display@@@\f3logins(1m)\f1 .\" index@user login data, display@@@\f3logins(1m)\f1 .\" .\" toc@\f3logins(1m)\f1:\0\0\f4logins\f1@@@display system and user login data .\" .\" fileset_database@logins.1m .\" $Header: lpadmin.1m,v 72.2 94/09/13 15:12:47 ssa Exp $ .TA l .TH lpadmin 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lpadmin \- configure the \s-1LP\s+1 spooling system .SH SYNOPSIS .B /usr/sbin/lpadmin .BI \-p printer .RI [\| options \|] .br .B /usr/sbin/lpadmin .BI \-x dest .br .B /usr/sbin/lpadmin .BR \-d [\|\f2dest\fP\|] .SH DESCRIPTION .I lpadmin configures .SM LP spooling systems to describe printers, classes and devices. It is used to add and remove destinations, change membership in classes, change devices for printers, change printer interface programs, and to change the system default destination. .I lpadmin cannot be used when the .SM LP scheduler, .IR lpsched (1M), is running, except where noted below. .PP Exactly one of the .BR \-p , .B \-x or .B \-d options must be present for every legal invocation of .IR lpadmin . .RS .TP 15 .BI \-p printer Names a .I printer to which all of the .I options below refer. If .I printer does not exist, it will be created. .TP .BI \-x dest Removes destination .I dest from the .SM LP system. If .I dest is a printer and is the only member of a class, the class is deleted, too. No other .I options are allowed with .BR \-x . .TP .BR \-d [\|\f2dest\fP\|] Makes existing destination .I dest the new system default destination. If .I dest is not supplied, there is no system default destination. This option can be used when .IR lpsched (1M) is running. No other .I options are allowed with .BR \-d . .RE .PP The following .I options are only useful with .B \-p and can appear in any order. For ease of discussion, the printer is referred to below as printer .IR P . .RS .TP 15 .BI \-c class Inserts printer .I P into the specified .IR class . .I class is created if it does not already exist. .TP .BI \-e printer Copies an existing .IR printer 's interface program to be the new interface program for printer .IR P . .TP .BI \-g priority Sets the default priority for printer .I P associated with .IR lp (1). If omitted, the default priority is set to 0. .TP .B \-h Indicates that the device associated with printer .I P is hardwired. This .I option is assumed when creating a new printer unless the .B \-l option is specified. .TP .BI \-i interface Establishes a new interface program for printer .IR P . .I interface is the pathname of the new program. .TP .B \-l Indicates that the device associated with printer .I P is a login terminal. The .SM LP scheduler (see .IR lpsched (1M)) disables all login terminals automatically each time it is started. Before re-enabling printer .IR P , its current .I device should be established using .IR lpadmin . .TP .BI \-m model Selects a model interface program for printer .IR P . .I model is one of the model interface names supplied with the .SM LP software (see Models below). .TP .BI \-r class Removes printer .I P from the specified .IR class . If printer .I P is the last member of the .IR class , the .I class is removed. .TP .BI \-v device Associates a new .I device with printer .IR P . .I device is the pathname of a file that is writable by the .SM LP administrator .IR lp . Note that there is nothing to stop an administrator from associating the same .I device with more than one .IR printer . If only the .B \-p and .B \-v .I options are supplied, .I lpadmin can be used while the scheduler is running. .RE .PP The following .I options are only useful with .B \-p and can appear in any order. They are provided with systems that provide remote spooling. .RS .TP 15 .BI \-ob3 Uses three-digit request numbers associated with the printer directory. This is for contact with .SM BSD systems. The default is to not use three-digit request numbers. .TP .BI \-oci remcancel Specifies that the local command .I remcancel is used to cancel requests to remote printers. To ensure that the correct command is used, specify the full path name. .TP .BI \-ocm remcancel Specifies that the local model .I remcancel is used to cancel requests to remote printers. .TP .BI \-orm machine The name of the remote machine is .IR machine . .TP .BI \-orp printer The name of the printer to use on the remote machine is .IR printer . .TP .B \-orc Restricts users to canceling only their own requests. Default is to not restrict the cancel command. .TP .BI \-osi remstatus Specifies that the command .I remstatus is used to obtain the status of requests to remote printers. To ensure that the correct command is used, specify the full path name. .TP .BI \-osm remstatus Specifies that the model .I remstatus is used to obtain the status of requests to remote printers. .RE .SS Restrictions When creating a new printer, the .B \-v option and one of the .BR \-e , .B \-i , or .B \-m options must be specified. Only one of the .BR \-e , .B \-i or .B \-m options can be specified. The .B \-h and .B \-l key letters are mutually exclusive. Printer and class names must not exceed 14 characters and must consist entirely of the characters .BR A - Z , .BR a - z , .BR 0 - 9 and .B _ (underscore). .SS Models Model interface programs are supplied with the .SM LP software. They are shell procedures, C programs, or other executable programs that interface between .IR lpsched (1M) and devices. All printer models reside in directory .B /usr/lib/lp/model and can be used without modification with .BR "lpadmin \-m" . All cancel models reside in directory .B /usr/lib/lp/cmodel and can be used without modification with .BR "lpadmin \-ocm" . All status models reside in directory .B /usr/lib/lp/smodel and can be used without modification with .BR "lpadmin \-osm" . Models should have 644 permission if owned by .B lp and .BR bin , or 664 permission if owned by .B bin and .BR bin . Model file names must not exceed 14 characters. Alternatively, .SM LP administrators can modify copies of models then use .B lpadmin \-m to associate them with printers. See .IR mklp (1M) for details of the printer models provided with your .SM HP-UX system. .PP The .SM LP model interface program does the actual printing on the device that is currently associated with the printer. The .SM LP spooler sets standard input to .B /dev/null and standard output and standard error output to the device specified in the .B \-v option of .IR lpadmin . The interface program is then invoked for printer .I P from the directory .B /etc/lp as follows: .IP .BI interface/ "P id user title copies options file "\f1.\|.\|. .PP where arguments are as follows: .RS .TP 15 .I id request id returned by .IR lp (1). .TP .I user login name of the user who made the request. .TP .I title optional title specified with the .B \-t option of .IR lp (1). .TP .I copies number of copies to be printed. .TP .I options blank-separated list of class-dependent or printer-dependent options specified with the .B \-o option of .IR lp (1). Options from a .SM BSD system have the character sequence .SM .B BSD attached to the beginning of the option (for example, .SM .BR BSDl \s0). .TP .I file full pathname of the file to be printed. .RE .PP Given the command line arguments and the output directed to the device, interface programs can format their output in any way they choose. .PP When printing is completed, it is the responsibility of the interface program to exit with a code indicative of the success of the print job. Only return values of .B 0 indicating that the job completed successfully, or values of positive .B 1 through .B 127 indicating that some error was encountered that does not affect future print jobs should be used. Negative values and positive values greater than 127 are reserved for system use and should not be used by interface programs. .IR lpsched (1M) notifies users by mail when there is an error in printing the request. If problems are detected that are likely to affect future print jobs, the interface program should disable the printer so that other pending print requests are not lost. .PP The cancel and status model interface programs perform the actual communication with the remote system to cancel requests or get the status of requests. See .IR rcancel (1M) and .IR rlpstat (1M) for command line arguments. .SH EXTERNAL INFLUENCES .SS Environment Variables .PP .SM LANG determines the language in which messages are displayed. .PP If .SM LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .SM LANG. .PP If any internationalization variable contains an invalid setting, .I lpadmin behaves as if all internationalization variables are set to "C" (see .IR environ (5)). .SH EXAMPLES .PP Assuming an existing Hewlett-Packard HP\|2934A line printer named .BR lp1 , it will use the .B hp2934a model interface through .B /dev/lp after the command: .IP .B "/usr/sbin/lpadmin\ \-plp1\ \-mhp2934a \-v/dev/lp" .PP Assuming a printer .B lp on a remote system .BR system2 , the command: .IP .B "/usr/sbin/lpadmin \-plp3 \-v/dev/null \-mrmodel \-ocmrcmodel" .B "\-osmrsmodel \-ob3 \-ormsystem2 \-orplp \-v/dev/null .PP causes the spool system to use the local line printer .B lp3 and the model .BR rmodel . The spool system also uses the model .B rcmodel to cancel remote requests and .B rsmodel to get status from .BR system2 . In addition, the three-digit sequence numbers, the remote system name .B system2 and the remote printer .B lp are used. .SH WARNINGS When installing remote printers, use the option .B \-ocmrcmodel instead of .B \-oci/usr/sbin/rcancel to specify the method used to cancel remote requests. The option .B \-osmrsmodel should be used instead of .B \-osi/usr/sbin/rlpstat to specify the method used for displaying remote status. .PP .IR class es must not include .I remote printers. .SM HP-UX systems do not have the ability to distribute print jobs in this way. Printing to a class of printers on a remote system .RB ( systemB for example) must be accomplished by creating the class on the remote system, then identifying that class by using a command resembling the following (though you might have to change some of the specific values shown in the example): .IP .C "lpadmin -plocal_name -ormsystemB -orpsystemB_class_name" .ifn .br .C "-v /dev/null -mrmodel -ocmrcmodel -osmrsmodel" .SH FILES .nf .C /var/spool/lp/* .C /var/adm/lp/* .C /etc/lp/* .C /usr/lib/lp/* .fi .SH SEE ALSO enable(1), lp(1), lpstat(1), nroff(1), accept(1M), lpana(1M), lpsched(1M), mklp(1M), rcancel(1M), rlp(1M), rlpdaemon(1M), rlpstat(1M). .\" .\" index@\f2lpadmin\f1 \- configure the \s-1LP\s+1 spooling system@@@\f3lpadmin(1M)\f1 .\" index@configure the \s-1LP\s+1 spooling system@@@\f3lpadmin(1M)\f1 .\" index@\s-1LP\s+1 spooling system, configure the@@@\f3lpadmin(1M)\f1 .\" index@spooling system, configure the \s-1LP\s+1@@@\f3lpadmin(1M)\f1 .\" index@line printer spooling system@@@see \s-1LP\s+1 .\" index@printer spooling system@@@see \s-1LP\s+1 .\" index@spooling system, line printer@@@see \s-1LP\s+1 .\" .\" toc@\f3lpadmin(1M)\f1:\0\0\f2lpadmin\f1@@@configure the \s-1LP\s+1 spooling system .\" $Header: lpana.1m,v 72.5 94/07/05 17:15:48 ssa Exp $ .TA l .TH lpana 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lpana \- print LP spooler performance analysis information .SH SYNOPSIS .C lpana .RC [ -d .IR dest\| ] .SH DESCRIPTION .C lpana prints LP spooler performance information, which system administrators can use to optimize the configuration of the entire spooler system. .SS Options .C lpana recognizes one option: .RS .TP 15 .CI -d \0dest Choose .I dest as the printer or the class of printers. If .I dest is a printer, the performance analysis information is printed on that specific printer. If .I dest is a class of printers, the performance analysis information is printed on the printers that are members of the class. By default, .C lpana prints the performance analysis information for all printers and/or classes. .RE .PP .C lpana examines .C /var/adm/lp/lpana.log for the following items: .RS .TP 15 .C Wait AV Average waiting time from when job is spooled until start of printing. .TP .C Wait SD Standard Deviation for waiting time. .TP .C Print AV Average printing time from start to end of job. .TP .C Print SD Standard Deviation for printing time. .TP .C Bytes AV Average of number of bytes printed per request. .TP .C Bytes SD Standard Deviation for number of bytes. .TP .C Sum KB Sum of bytes printed for all requests (in kilobytes). .TP .C Num of Requests Total number of requests since logging started. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG determines the language in which messages are displayed. .SH WARNINGS .C lpana performs its operation on the local system only. .SH AUTHOR .C lpana was developed by HP. .SH FILES .C /var/adm/lp/lpana.log .SH SEE ALSO lp(1), lpstat(1), lpadmin(1M), lpsched(1M). .\" .\" index@\f4lpana\f1 \- print LP spooler performance analysis information@@@\f3lpana(1M)\f1 .\" index@\f1print LP spooler performance analysis information@@@\f3lpana(1M)\f1 .\" index@\f1LP spooler performance analysis information, print@@@\f3lpana(1M)\f1 .\" index@\f1spooler performance analysis information, print LP@@@\f3lpana(1M)\f1 .\" index@\f1performance analysis information, print LP spooler@@@\f3lpana(1M)\f1 .\" index@\f1analysis information, print LP spooler performance@@@\f3lpana(1M)\f1 .\" .\" toc@\f3lpana(1M)\f1:\0\0\f4lpana\f1@@@print LP spooler performance analysis information .\" $Header: lpsched.1m,v 72.2 94/09/13 15:13:13 ssa Exp $ .TA l .TH lpsched 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lpsched, lpshut, lpmove, lpfence \- start/stop the \s-1LP\s0 request scheduler, move requests, and define the minimum priority for printing .SH SYNOPSIS .B /usr/sbin/lpsched .RB [ \|\-v\| ] .RB [ \|\-a\| ] .br .B /usr/sbin/lpshut .br .B /usr/sbin/lpmove .I requests .I dest .br .B /usr/sbin/lpmove .I dest1 .I dest2 .br .B /usr/sbin/lpfence .I printer .I fence .SH DESCRIPTION .TP 10 .I lpsched Schedules requests taken by .IR lp (1) for printing on line printers. .IR lpsched (1M) is typically invoked in .BR /sbin/rc . This creates a process which runs in the background until .I lpshut is executed. The activity of the process is recorded in .BR /var/adm/lp/log . .IP .I lpsched recognizes the following options: .RS .RS .TP 6 .B \-v Write a verbose record of the .I lpsched process on .BR /var/adm/lp/log . .TP .B \-a Write .IR lpana(1M) logging data on .BR /var/adm/lp/lpana.log . .RE .RE .TP .I lpshut Shuts down the line printer scheduler. All printers that are printing at the time .I lpshut is invoked stop printing. Requests that were printing at the time a printer was shut down are reprinted in their entirety after .I lpsched is started again. All .SM LP commands perform their functions even when .I lpsched is not running. .TP .I lpmove Moves requests that were queued by .IR lp (1) between .SM LP destinations. This command can be used only when .I lpsched is not running. .IP The first form of the command moves the named .I requests to the .SM LP destination, .IR dest . .I requests are request ids as returned by .IR lp (1) . The second form moves all requests for destination .I dest1 to destination .IR dest2 . As a side effect, .IR lp (1) rejects requests for .IR dest1 . .IP Note that .I lpmove never checks the acceptance status (see .IR accept (1M)) for the new destination when moving requests. .TP .I lpfence Defines the minimum required .I priority for the spooled file to be printed. .I fence must be in between 0 (lowest fence) and 7 (highest fence). Each .I printer has its own .IR fence , which is initialized to 0 when it is configured by the .IR lpadmin (1M) command. .I lpfence is used only when .I lpsched is not running. .SH EXTERNAL INFLUENCES Environment Variables .IP .SM LC_TIME determines the format and contents of date and time strings. .IP .SM LANG determines the language in which messages are displayed. .IP If .SM LC_TIME is not specified in the environment or is set to the empty string, the value of .SM LANG is used as a default for each unspecified or empty variable. If .SM LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .SM LANG. If any internationalization variable contains an invalid setting, .IR lpsched , .IR lpmove , and .I lpshut behave as if all internationalization variables are set to "C". See .IR environ (5). .SH FILES .nf .C /var/spool/lp/* .C /var/adm/lp/* .C /etc/lp/* .C /usr/lib/lp/* .fi .SH WARNINGS Moving requests associated with remote printers can cause unpredictable results. .PP .IR lpsched , .IR lpshut , .IR lpmove , and .I lpfence perform their operation on the local system only. .SH SEE ALSO accept(1M), cancel(1), enable(1), lp(1), lpadmin(1M), lpana(1M), lpstat(1), rcancel(1M), rlp(1M), rlpdaemon(1M), rlpstat(1M). .\" .\" index@\f4lpsched\f1 \- start the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@\f4lpshut\f1 \- stop the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@\f4lpmove\f1 \- move \s-1LP\s+1 spooling requests to specified destination@@@\f3lpsched(1M)\f1 .\" index@\f4lpfence\f1 \- set \s-1LP\s+1 spooling request priority fence@@@\f3lpsched(1M)\f1 .\" index@start/stop the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@stop/start the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@move \s-1LP\s+1 spooling requests to a specified destination@@@\f3lpsched(1M)\f1 .\" index@\s-1LP\s+1 spooling requests, move to a specified destination@@@\f3lpsched(1M)\f1 .\" index@requests, \s-1LP\s+1 spooling, move to a specified destination@@@\f3lpsched(1M)\f1 .\" index@\s-1LP\s+1 spooling scheduler, start or stop@@@\f3lpsched(1M)\f1 .\" index@scheduler, \s-1LP\s+1, start or stop@@@\f3lpsched(1M)\f1 .\" index@line printer spooling system@@@see \s-1LP\s+1 .\" index@printer spooling system@@@see \s-1LP\s+1 .\" index@spooling system, line printer@@@see \s-1LP\s+1 .\" .\" toc@\f3lpsched(1M)\f1:\0\0 \f4lpshut\f1, \f4lpfence\f1, \f4lpmove\f1\f4lpsched\f1@@@start/stop the \s-1LP\s+1 request scheduler and move requests .\" toc@\f4lpshut\f1:\0\0stop \s-1LP\s+1 scheduler requests@@@see \f3lpsched(1M)\f1 .\" toc@\f4lpmove\f1:\0\0move \s-1LP\s+1 scheduler requests@@@see \f3lpsched(1M)\f1 .\" toc@\f4lpfence\f1:\0\0set \s-1LP\s+1 scheduler priority fence@@@see \f3lpsched(1M)\f1 .\" .\" links@lpsched.1m lpshut.1m .\" links@lpsched.1m lpmove.1m .\" links@lpsched.1m lpfence.1m .\" $Header: lpsched.1m,v 72.2 94/09/13 15:13:13 ssa Exp $ .TA l .TH lpsched 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lpsched, lpshut, lpmove, lpfence \- start/stop the \s-1LP\s0 request scheduler, move requests, and define the minimum priority for printing .SH SYNOPSIS .B /usr/sbin/lpsched .RB [ \|\-v\| ] .RB [ \|\-a\| ] .br .B /usr/sbin/lpshut .br .B /usr/sbin/lpmove .I requests .I dest .br .B /usr/sbin/lpmove .I dest1 .I dest2 .br .B /usr/sbin/lpfence .I printer .I fence .SH DESCRIPTION .TP 10 .I lpsched Schedules requests taken by .IR lp (1) for printing on line printers. .IR lpsched (1M) is typically invoked in .BR /sbin/rc . This creates a process which runs in the background until .I lpshut is executed. The activity of the process is recorded in .BR /var/adm/lp/log . .IP .I lpsched recognizes the following options: .RS .RS .TP 6 .B \-v Write a verbose record of the .I lpsched process on .BR /var/adm/lp/log . .TP .B \-a Write .IR lpana(1M) logging data on .BR /var/adm/lp/lpana.log . .RE .RE .TP .I lpshut Shuts down the line printer scheduler. All printers that are printing at the time .I lpshut is invoked stop printing. Requests that were printing at the time a printer was shut down are reprinted in their entirety after .I lpsched is started again. All .SM LP commands perform their functions even when .I lpsched is not running. .TP .I lpmove Moves requests that were queued by .IR lp (1) between .SM LP destinations. This command can be used only when .I lpsched is not running. .IP The first form of the command moves the named .I requests to the .SM LP destination, .IR dest . .I requests are request ids as returned by .IR lp (1) . The second form moves all requests for destination .I dest1 to destination .IR dest2 . As a side effect, .IR lp (1) rejects requests for .IR dest1 . .IP Note that .I lpmove never checks the acceptance status (see .IR accept (1M)) for the new destination when moving requests. .TP .I lpfence Defines the minimum required .I priority for the spooled file to be printed. .I fence must be in between 0 (lowest fence) and 7 (highest fence). Each .I printer has its own .IR fence , which is initialized to 0 when it is configured by the .IR lpadmin (1M) command. .I lpfence is used only when .I lpsched is not running. .SH EXTERNAL INFLUENCES Environment Variables .IP .SM LC_TIME determines the format and contents of date and time strings. .IP .SM LANG determines the language in which messages are displayed. .IP If .SM LC_TIME is not specified in the environment or is set to the empty string, the value of .SM LANG is used as a default for each unspecified or empty variable. If .SM LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .SM LANG. If any internationalization variable contains an invalid setting, .IR lpsched , .IR lpmove , and .I lpshut behave as if all internationalization variables are set to "C". See .IR environ (5). .SH FILES .nf .C /var/spool/lp/* .C /var/adm/lp/* .C /etc/lp/* .C /usr/lib/lp/* .fi .SH WARNINGS Moving requests associated with remote printers can cause unpredictable results. .PP .IR lpsched , .IR lpshut , .IR lpmove , and .I lpfence perform their operation on the local system only. .SH SEE ALSO accept(1M), cancel(1), enable(1), lp(1), lpadmin(1M), lpana(1M), lpstat(1), rcancel(1M), rlp(1M), rlpdaemon(1M), rlpstat(1M). .\" .\" index@\f4lpsched\f1 \- start the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@\f4lpshut\f1 \- stop the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@\f4lpmove\f1 \- move \s-1LP\s+1 spooling requests to specified destination@@@\f3lpsched(1M)\f1 .\" index@\f4lpfence\f1 \- set \s-1LP\s+1 spooling request priority fence@@@\f3lpsched(1M)\f1 .\" index@start/stop the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@stop/start the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@move \s-1LP\s+1 spooling requests to a specified destination@@@\f3lpsched(1M)\f1 .\" index@\s-1LP\s+1 spooling requests, move to a specified destination@@@\f3lpsched(1M)\f1 .\" index@requests, \s-1LP\s+1 spooling, move to a specified destination@@@\f3lpsched(1M)\f1 .\" index@\s-1LP\s+1 spooling scheduler, start or stop@@@\f3lpsched(1M)\f1 .\" index@scheduler, \s-1LP\s+1, start or stop@@@\f3lpsched(1M)\f1 .\" index@line printer spooling system@@@see \s-1LP\s+1 .\" index@printer spooling system@@@see \s-1LP\s+1 .\" index@spooling system, line printer@@@see \s-1LP\s+1 .\" .\" toc@\f3lpsched(1M)\f1:\0\0 \f4lpshut\f1, \f4lpfence\f1, \f4lpmove\f1\f4lpsched\f1@@@start/stop the \s-1LP\s+1 request scheduler and move requests .\" toc@\f4lpshut\f1:\0\0stop \s-1LP\s+1 scheduler requests@@@see \f3lpsched(1M)\f1 .\" toc@\f4lpmove\f1:\0\0move \s-1LP\s+1 scheduler requests@@@see \f3lpsched(1M)\f1 .\" toc@\f4lpfence\f1:\0\0set \s-1LP\s+1 scheduler priority fence@@@see \f3lpsched(1M)\f1 .\" .\" links@lpsched.1m lpshut.1m .\" links@lpsched.1m lpmove.1m .\" links@lpsched.1m lpfence.1m .\" $Header: lpsched.1m,v 72.2 94/09/13 15:13:13 ssa Exp $ .TA l .TH lpsched 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lpsched, lpshut, lpmove, lpfence \- start/stop the \s-1LP\s0 request scheduler, move requests, and define the minimum priority for printing .SH SYNOPSIS .B /usr/sbin/lpsched .RB [ \|\-v\| ] .RB [ \|\-a\| ] .br .B /usr/sbin/lpshut .br .B /usr/sbin/lpmove .I requests .I dest .br .B /usr/sbin/lpmove .I dest1 .I dest2 .br .B /usr/sbin/lpfence .I printer .I fence .SH DESCRIPTION .TP 10 .I lpsched Schedules requests taken by .IR lp (1) for printing on line printers. .IR lpsched (1M) is typically invoked in .BR /sbin/rc . This creates a process which runs in the background until .I lpshut is executed. The activity of the process is recorded in .BR /var/adm/lp/log . .IP .I lpsched recognizes the following options: .RS .RS .TP 6 .B \-v Write a verbose record of the .I lpsched process on .BR /var/adm/lp/log . .TP .B \-a Write .IR lpana(1M) logging data on .BR /var/adm/lp/lpana.log . .RE .RE .TP .I lpshut Shuts down the line printer scheduler. All printers that are printing at the time .I lpshut is invoked stop printing. Requests that were printing at the time a printer was shut down are reprinted in their entirety after .I lpsched is started again. All .SM LP commands perform their functions even when .I lpsched is not running. .TP .I lpmove Moves requests that were queued by .IR lp (1) between .SM LP destinations. This command can be used only when .I lpsched is not running. .IP The first form of the command moves the named .I requests to the .SM LP destination, .IR dest . .I requests are request ids as returned by .IR lp (1) . The second form moves all requests for destination .I dest1 to destination .IR dest2 . As a side effect, .IR lp (1) rejects requests for .IR dest1 . .IP Note that .I lpmove never checks the acceptance status (see .IR accept (1M)) for the new destination when moving requests. .TP .I lpfence Defines the minimum required .I priority for the spooled file to be printed. .I fence must be in between 0 (lowest fence) and 7 (highest fence). Each .I printer has its own .IR fence , which is initialized to 0 when it is configured by the .IR lpadmin (1M) command. .I lpfence is used only when .I lpsched is not running. .SH EXTERNAL INFLUENCES Environment Variables .IP .SM LC_TIME determines the format and contents of date and time strings. .IP .SM LANG determines the language in which messages are displayed. .IP If .SM LC_TIME is not specified in the environment or is set to the empty string, the value of .SM LANG is used as a default for each unspecified or empty variable. If .SM LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .SM LANG. If any internationalization variable contains an invalid setting, .IR lpsched , .IR lpmove , and .I lpshut behave as if all internationalization variables are set to "C". See .IR environ (5). .SH FILES .nf .C /var/spool/lp/* .C /var/adm/lp/* .C /etc/lp/* .C /usr/lib/lp/* .fi .SH WARNINGS Moving requests associated with remote printers can cause unpredictable results. .PP .IR lpsched , .IR lpshut , .IR lpmove , and .I lpfence perform their operation on the local system only. .SH SEE ALSO accept(1M), cancel(1), enable(1), lp(1), lpadmin(1M), lpana(1M), lpstat(1), rcancel(1M), rlp(1M), rlpdaemon(1M), rlpstat(1M). .\" .\" index@\f4lpsched\f1 \- start the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@\f4lpshut\f1 \- stop the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@\f4lpmove\f1 \- move \s-1LP\s+1 spooling requests to specified destination@@@\f3lpsched(1M)\f1 .\" index@\f4lpfence\f1 \- set \s-1LP\s+1 spooling request priority fence@@@\f3lpsched(1M)\f1 .\" index@start/stop the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@stop/start the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@move \s-1LP\s+1 spooling requests to a specified destination@@@\f3lpsched(1M)\f1 .\" index@\s-1LP\s+1 spooling requests, move to a specified destination@@@\f3lpsched(1M)\f1 .\" index@requests, \s-1LP\s+1 spooling, move to a specified destination@@@\f3lpsched(1M)\f1 .\" index@\s-1LP\s+1 spooling scheduler, start or stop@@@\f3lpsched(1M)\f1 .\" index@scheduler, \s-1LP\s+1, start or stop@@@\f3lpsched(1M)\f1 .\" index@line printer spooling system@@@see \s-1LP\s+1 .\" index@printer spooling system@@@see \s-1LP\s+1 .\" index@spooling system, line printer@@@see \s-1LP\s+1 .\" .\" toc@\f3lpsched(1M)\f1:\0\0 \f4lpshut\f1, \f4lpfence\f1, \f4lpmove\f1\f4lpsched\f1@@@start/stop the \s-1LP\s+1 request scheduler and move requests .\" toc@\f4lpshut\f1:\0\0stop \s-1LP\s+1 scheduler requests@@@see \f3lpsched(1M)\f1 .\" toc@\f4lpmove\f1:\0\0move \s-1LP\s+1 scheduler requests@@@see \f3lpsched(1M)\f1 .\" toc@\f4lpfence\f1:\0\0set \s-1LP\s+1 scheduler priority fence@@@see \f3lpsched(1M)\f1 .\" .\" links@lpsched.1m lpshut.1m .\" links@lpsched.1m lpmove.1m .\" links@lpsched.1m lpfence.1m .\" $Header: lpsched.1m,v 72.2 94/09/13 15:13:13 ssa Exp $ .TA l .TH lpsched 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lpsched, lpshut, lpmove, lpfence \- start/stop the \s-1LP\s0 request scheduler, move requests, and define the minimum priority for printing .SH SYNOPSIS .B /usr/sbin/lpsched .RB [ \|\-v\| ] .RB [ \|\-a\| ] .br .B /usr/sbin/lpshut .br .B /usr/sbin/lpmove .I requests .I dest .br .B /usr/sbin/lpmove .I dest1 .I dest2 .br .B /usr/sbin/lpfence .I printer .I fence .SH DESCRIPTION .TP 10 .I lpsched Schedules requests taken by .IR lp (1) for printing on line printers. .IR lpsched (1M) is typically invoked in .BR /sbin/rc . This creates a process which runs in the background until .I lpshut is executed. The activity of the process is recorded in .BR /var/adm/lp/log . .IP .I lpsched recognizes the following options: .RS .RS .TP 6 .B \-v Write a verbose record of the .I lpsched process on .BR /var/adm/lp/log . .TP .B \-a Write .IR lpana(1M) logging data on .BR /var/adm/lp/lpana.log . .RE .RE .TP .I lpshut Shuts down the line printer scheduler. All printers that are printing at the time .I lpshut is invoked stop printing. Requests that were printing at the time a printer was shut down are reprinted in their entirety after .I lpsched is started again. All .SM LP commands perform their functions even when .I lpsched is not running. .TP .I lpmove Moves requests that were queued by .IR lp (1) between .SM LP destinations. This command can be used only when .I lpsched is not running. .IP The first form of the command moves the named .I requests to the .SM LP destination, .IR dest . .I requests are request ids as returned by .IR lp (1) . The second form moves all requests for destination .I dest1 to destination .IR dest2 . As a side effect, .IR lp (1) rejects requests for .IR dest1 . .IP Note that .I lpmove never checks the acceptance status (see .IR accept (1M)) for the new destination when moving requests. .TP .I lpfence Defines the minimum required .I priority for the spooled file to be printed. .I fence must be in between 0 (lowest fence) and 7 (highest fence). Each .I printer has its own .IR fence , which is initialized to 0 when it is configured by the .IR lpadmin (1M) command. .I lpfence is used only when .I lpsched is not running. .SH EXTERNAL INFLUENCES Environment Variables .IP .SM LC_TIME determines the format and contents of date and time strings. .IP .SM LANG determines the language in which messages are displayed. .IP If .SM LC_TIME is not specified in the environment or is set to the empty string, the value of .SM LANG is used as a default for each unspecified or empty variable. If .SM LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .SM LANG. If any internationalization variable contains an invalid setting, .IR lpsched , .IR lpmove , and .I lpshut behave as if all internationalization variables are set to "C". See .IR environ (5). .SH FILES .nf .C /var/spool/lp/* .C /var/adm/lp/* .C /etc/lp/* .C /usr/lib/lp/* .fi .SH WARNINGS Moving requests associated with remote printers can cause unpredictable results. .PP .IR lpsched , .IR lpshut , .IR lpmove , and .I lpfence perform their operation on the local system only. .SH SEE ALSO accept(1M), cancel(1), enable(1), lp(1), lpadmin(1M), lpana(1M), lpstat(1), rcancel(1M), rlp(1M), rlpdaemon(1M), rlpstat(1M). .\" .\" index@\f4lpsched\f1 \- start the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@\f4lpshut\f1 \- stop the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@\f4lpmove\f1 \- move \s-1LP\s+1 spooling requests to specified destination@@@\f3lpsched(1M)\f1 .\" index@\f4lpfence\f1 \- set \s-1LP\s+1 spooling request priority fence@@@\f3lpsched(1M)\f1 .\" index@start/stop the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@stop/start the \s-1LP\s+1 spooling request scheduler@@@\f3lpsched(1M)\f1 .\" index@move \s-1LP\s+1 spooling requests to a specified destination@@@\f3lpsched(1M)\f1 .\" index@\s-1LP\s+1 spooling requests, move to a specified destination@@@\f3lpsched(1M)\f1 .\" index@requests, \s-1LP\s+1 spooling, move to a specified destination@@@\f3lpsched(1M)\f1 .\" index@\s-1LP\s+1 spooling scheduler, start or stop@@@\f3lpsched(1M)\f1 .\" index@scheduler, \s-1LP\s+1, start or stop@@@\f3lpsched(1M)\f1 .\" index@line printer spooling system@@@see \s-1LP\s+1 .\" index@printer spooling system@@@see \s-1LP\s+1 .\" index@spooling system, line printer@@@see \s-1LP\s+1 .\" .\" toc@\f3lpsched(1M)\f1:\0\0 \f4lpshut\f1, \f4lpfence\f1, \f4lpmove\f1\f4lpsched\f1@@@start/stop the \s-1LP\s+1 request scheduler and move requests .\" toc@\f4lpshut\f1:\0\0stop \s-1LP\s+1 scheduler requests@@@see \f3lpsched(1M)\f1 .\" toc@\f4lpmove\f1:\0\0move \s-1LP\s+1 scheduler requests@@@see \f3lpsched(1M)\f1 .\" toc@\f4lpfence\f1:\0\0set \s-1LP\s+1 scheduler priority fence@@@see \f3lpsched(1M)\f1 .\" .\" links@lpsched.1m lpshut.1m .\" links@lpsched.1m lpmove.1m .\" links@lpsched.1m lpfence.1m .\" $Header: lsdev.1m,v 78.1 96/01/03 15:34:32 ssa Exp $ .TA l .TH lsdev 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lsdev \- list device drivers in the system .SH SYNOPSIS .C /usr/sbin/lsdev .RC [ -h ] .RC [ -d .IR driver\0 \(or .C -C .IR class ] .RC [ -b .IR block_major ] .ifn .br .ifn \0\0\0\0 .RC [ -c .IR char_major ] .RC [ -e .IR major ] .ift .br .ift \0\0\0\0 .RI [ major \0...\|] .SH DESCRIPTION The .CR lsdev command lists, one pair per line, the major device numbers and driver names of device drivers configured into the system and available for invocation via special files. A .CR \(mi1 in either the block or character column means that a major number does not exist for that type. .PP If no arguments are specified, .CR lsdev lists all drivers configured into the system. .PP If the .CR -h option is specified, .CR lsdev will not print a heading. This option may be useful when the output of .CR lsdev will be used by another program. .PP The .CR -d , .CR -C , .CR -b , .CR -c , and .CR -e options are used to select specific device drivers for output. If more than one option is specified, all drivers that match the criteria specified by those options will be listed. These search options are divided into two types: name search keys (the .CR -d and .CR -C options) and major number search keys (the .CR -b , .CR -c , and .CR -e options). If both types of options are present, only entries that match both types are printed. The same type of option may appear more than once on the command line with each occurrence providing an ORing effect of that search type. The .CR -d and .CR -C options may not be specified at the same time. .PP The ability to process .I major arguments is provided for compatibility and functions like the .CR -e option. .SS Options .RS .TP 20 .CI -C " class" List device drivers that match .IR class . .TP .CI -d " driver" List device drivers with the name .IR driver . .TP .CI -b " block_major" List device drivers with a block major number of .IR block_major . .TP .CI -c " char_major" List device drivers with a character major number of .IR char_major . .TP .CI -e " major" List device drivers with either a character major number or block major equal to .IR major . .RE .SH DIAGNOSTICS .TP .C Invalid combination of options The .CR -d and .CR -C options may not be specified at the same time. .TP .C Invalid major number A major number is malformed or out of range. .SH EXAMPLES To output entries for all drivers in the .CR pseudo class: .IP .C lsdev -C pseudo .PP To output entries that are in the class .CR disk that have either a block or character major number of .CR 0 : .IP .C lsdev -C disk -e 0 .PP To get the character major number of .CR my_driver into a shell environment variable: .IP .C "C_MAJOR=$(lsdev -h -d my_driver | awk '{print $1}')" .SH WARNINGS Some device drivers available from the system may be intended for use by other drivers. Attempting to use them directly from a special file may produce unexpected results. .PP A driver may be listed even when the hardware requiring the driver is not present. Attempts to access a driver without the corresponding hardware will fail. .PP .CR lsdev only lists drivers that are configured into the currently executing kernel. For a complete list of available drivers, please run .CR sam (see .IR sam (1M). .SH DEPENDENCIES Since .CR lsdev relies on the device driver information provided in a .IC driver _install routine, .CR lsdev may not list drivers installed by other means. .SH AUTHOR .CR lsdev was developed by HP. .SH SEE ALSO sam(1M). .PP Section 7 entries related to specific device drivers. .PP .I "HP-UX System Administration Tasks" .\" .\" index@\f4lsdev\f1 \- list device drivers in the system@@@\f3lsdev(1M)\f1 .\" index@\f1list device drivers in the system@@@\f3lsdev(1M)\f1 .\" index@\f1device drivers in the system, list@@@\f3lsdev(1M)\f1 .\" index@\f1drivers in the system, list device@@@\f3lsdev(1M)\f1 .\" index@\f1special files; list all device drivers available in the system@@@\f3lsdev(1M)\f1 .\" .\" toc@\f3lsdev(1M)\f1:\0\0\f4lsdev\f1@@@list device drivers in the system .\" $Header: lssf.1m,v 72.5 94/08/09 11:16:20 ssa Exp $ .TA l .TH lssf 1M "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lssf \- list a special file .SH SYNOPSIS .C /sbin/lssf .IR special_file \0... .SH DESCRIPTION .C lssf lists information about a special file. For each .I special_file name, .C lssf determines the major number of the special file and whether it is block or character (using .IR stat(2) ). It then scans the system for the device that is associated with the special file. When the device is found, the minor number of the special file is decoded. A mnemonic description of the minor number is printed on standard output along with the hardware path (i.e., address) of the device. Mnemonics used to describe the fields are closely related to the options used with .C mksf (see .IR mksf (1M)). .SH DIAGNOSTICS Most diagnostic messages from .C lssf are self explanatory. Listed below are some messages deserving further clarification. Warnings allow .C lssf to continue. .SS Warnings .TP 10 .C "No such device in the system" There is no information about the device in the kernel. The special file is not usable. Use .C rmsf to remove the special file (see .IR rmsf (1M)). .TP .CI "Character major <" major "> is not in the kernel" .PD 0 .TP .CI "Block major <" major "> is not in the kernel" The major number associated with the special file is not in the kernel. Use .C config to add the appropriate driver to the kernel (see .IR config (1M)). .PD .TP .CI "Device driver <" name "> is not in the kernel" .PD 0 .TP .CI "Device class <" name "> is not in the kernel" The indicated device driver or device class is not present in the kernel. An .C open() of a special file pointing to an unusable device fails. To make the device usable, the appropriate device driver and/or device class must be added to the .C config input file and a new kernel generated (see .IR config (1M)). If the device is no longer needed, .C rmsf should be used to remove the special files and update .CR /etc/ioconfig . .TP .CI < special_file "> is not a special file" The file is not associated with an I/O device. .SH EXAMPLES Suppose a special file is created with the command .CR "mksf -d tape1 -H 8.6.1 -b 1600 -a rmt/c2t6d0m" . The command .C lssf rmt/c2t6d0m then produces: .IP .C "tape1 instance 2 bpi 1600 att address 8.6.1 rmt/c2t6d0m" .SH AUTHOR .C lssf was developed by HP. .SH FILES .TP 20 .C /dev/config I/O system special file .TP .C /etc/ioconfig I/O system configuration database .SH SEE ALSO config(1M), insf(1M), mksf(1M), rmsf(1M). .\" .\" index@\f4lssf\f1 \- list a special (I/O device) file@@@\f3lssf(1M)\f1 .\" index@\f1list a special (I/O device) file@@@\f3lssf(1M)\f1 .\" index@\f1device (special) file, list an I/O@@@\f3lssf(1M)\f1 .\" index@\f1I/O device file, list a@@@\f3lssf(1M)\f1 .\" index@\f1special (I/O device) file, list a@@@\f3lssf(1M)\f1 .\" index@\f1I/O device file, list a@@@\f3lssf(1M)\f1 .\" .\" toc@\f3lssf(1M)\f1:\0\0\f4lssf\f1@@@list a special file .\" $Header: lvchange.1m,v 78.1 96/02/13 13:11:09 ssa Exp $ .TA l .TH lvchange 1M .SH NAME lvchange \- change LVM logical volume characteristics .SH SYNOPSIS .CR /sbin/lvchange .RC [ -a .IR availability ] .RC [ -A .IR autobackup ] .ifn .br .ifn \0\0\0\0 .RC [ -c .IR mirror_consistency ] .ift .br .ift \0\0\0\0 .RC [ -C .IR contiguous ] .ifn .br .ifn \0\0\0\0 .RC [ -d .IR schedule ] .RC [ -D .IR distributed ] .RC [ -M .IR mirror_write_cache ] .ifn .br .ifn \0\0\0\0 .RC [ -p .IR permission ] .RC [ -r .IR relocate ] .RC [ -s .IR strict ] .I lv_path .SS Remarks Mirror disk operations require the installation of the optional HP MirrorDisk/UX software, which is not included in the standard HP-UX operating system. .sp .CR lvchange cannot be performed if the volume group is activated in shared mode. .SH DESCRIPTION The .CR lvchange command changes certain characteristics of a logical volume. Other characteristics can be changed with the .CR lvextend and .CR lvreduce commands (see .IR lvextend (1M) and .IR lvreduce (1M)). .PP The command-line options specify the type and extent of change. Each current characteristic for a logical volume remains in effect until explicitly changed by the corresponding option. All options take effect immediately, except .CR -s , which takes effect only when new extents are allocated by the .CR lvextend command. .PP If a logical volume is striped, its scheduling policy is always parallel and its allocation policy is always strict and noncontiguous; these attributes cannot be changed with .CR lvchange . .SS Options and Arguments .PP The .CR -c , .CR -d , .CR -M , and .CR -s options are meaningful only if the optional HP MirrorDisk/UX software has been installed on the system. .PP .CR lvchange recognizes the following options and arguments: .RS .TP 25 .I lv_path The block device path name of a logical volume. .TP .CI -a \0availability Set logical volume availability. .I availability can have one of the following values: .RS .RS .TP .CR y Make a logical volume available. An open of the logical volume will succeed. .TP .CR n Make a logical volume temporarily unavailable. An open of the logical volume will fail. However, all current processes that have the logical volume open remain open. .RE .RE .TP .CI -A \0autobackup Set automatic backup for this invocation of this command. .I autobackup can have one of the following values: .RS .RS .TP .CR y Automatically back up configuration changes made to the logical volume. This is the default. .IP After this command executes, the .CR vgcfgbackup command (see .IR vgcfgbackup (1M)) is executed for the volume group to which the logical volume belongs. .TP .CR n Do not back up configuration changes this time. .RE .RE .TP .CI -c \0mirror_consistency Set mirror consistency recovery. This option is effective only when .CR "-M n" is specified or previously set. .I mirror_consistency can have one of the following values: .RS .RS .TP .CR y Set mirror consistency recovery on. LVM achieves mirror consistency during volume group activation by going through all logical extents and copying data from a nonstale copy to the other mirror copies. .TP .CR n Set mirror consistency recovery off. LVM does not perform mirror consistency recovery on this logical volume when the volume group is activated. .RE .RE .TP .CI -C \0contiguous Set the contiguous allocation policy. .I contiguous can have one of the following values: .RS .RS .TP .CR y Set a contiguous allocation policy. Physical extents are allocated in ascending order without any gap between adjacent extents and all extents are contained in a single physical volume. .TP .CR n Do not set a contiguous allocation policy. .RE .RE .IP A nonempty logical volume that has a noncontiguous allocation policy cannot be changed to a contiguous allocation policy unless it happens to meet all the requirements of the contiguous allocation policy. See .IR lvcreate (1m) for more information about the contiguous allocation policy. .TP .CI -d \0schedule Set the scheduling policy when a logical extent with more than one mirror is written. (The scheduling policy of a striped logical volume is striped and cannot be changed.) .I schedule can have one of the following values: .RS .RS .TP .CR p Establish a parallel scheduling policy. .TP .CR s Establish a sequential scheduling policy. Use this value with care, because it leads to performance loss in most cases. .RE .RE .TP .CI -D \0distributed Change the distributed allocation policy. .I distributed can have one of the following values: .RS .RS .TP .CR y Turn on distributed allocation. .TP .CR n Turn off distributed allocation. .TP .CR f Force distributed allocation to be on. .RE .RE .IP When the distributed allocation policy is turned on, only one free extent is allocated from the first available physical volume. The next free extent is allocated from the next available physical volume. Allocation of free extents proceeds in round-robin order on the list of available physical volumes. .IP When the distributed allocation policy is turned off, all available free extents are allocated from each available physical volume before proceeding to the next available physical volume. .IP The distributed allocation policy REQUIRES the PVG-strict allocation policy ( .CR "-s g" ) to ensure that mirrors of distributed extents do not overlap (for maximum availability). .IP The distributed allocation policy is incompatible with the striped scheduling policy ( .CI -i \0stripes ) and the contiguous allocation policy ( .CR "-C y" ). .IP See .IR lvcreate (1M) for more information on the distributed allocation policy. .IP The .CR "-D y" option will fail if the existing logical volume has any two consecutive logical extents on the same physical volume. To override this failure, use the .CR "-D f" option. .IP If a logical volume with the distributed allocation policy has at least two consecutive logical extents on the same physical volume, then .IR lvdisplay (1M) will display the allocation as .CR partially-distributed (vs. .CR distributed ). .IP See .IR lvdisplay (1M) for display values. .TP .CI -M \0mirror_write_cache Set the Mirror Write Cache flag. This option is allowed only when the logical volume is not opened. .I mirror_write_cache can have one of the following values: .RS .RS .TP .CR y Set Mirror Write Cache on. Every write to a mirror copy is recorded in the Mirror Write Cache and written into the Mirror Consistency Record on the disk if a cache-miss occurs. This allows LVM to determine whether all mirror copies are identical, even across system crashes. When the volume group is activated, the Mirror Consistency Record is used to perform mirror consistency recovery. .TP .CR n Set Mirror Write Cache off. Mirror write does not incur an additional write to the Mirror Consistency Record on the disk. .RE .RE .TP .CI -p \0permission Set the access permission. .I permission can have one of the following values: .RS .RS .TP .CR w Set the access permission to read-write. .TP .CR r Set the access permission to read-only. .RE .RE .TP .CI -r \0relocate Set the bad block relocation policy. .I relocate can have one of the following values: .RS .RS .TP .CR y Allow bad block relocation. Upon an EMEDIA failure, LVM will mark the failed block in the Bad Block Directory, and attempt to relocate the block to a new location on the disk. .TP .CR n Prevent bad block relocation. Upon an EMEDIA failure, LVM will mark the failed block as bad in the Bad Block Directory, but will not attempt to relocate the bad block to a new location. .TP .CR N Prevent bad block relocation and the Bad Block Directory. Upon an EMEDIA failure, LVM will not attempt to relocate the failed block, nor will it even mark the block as bad in the Bad Block Directory. .RE .RE .TP .CI -s \0strict Set the strict allocation policy. Mirror copies of a logical extent can be allocated to share or not share the same physical volume or physical volume group. This option only makes sense when the physical volumes of the volume group that owns the specified logical volume reside on different physical disks. .I strict can have one of the following values: .RS .RS .TP .CR y Set a strict allocation policy. Mirrors of a logical extent cannot share the same physical volume. .TP .CR g Set a PVG-strict allocation policy. Mirrors of a logical extent cannot share the same physical volume group. .TP .CR n Do not set a strict or a PVG-strict allocation policy. Mirrors of a logical extent can share the same physical volume. .RE .RE .IP When a logical volume is mirrored, the following changes are not allowed: .RS .RS .TP .PD 0 \(bu From nonstrict to strict .TP \(bu From nonstrict to PVG-strict .TP \(bu From strict to PVG-strict .PD .RE .RE .RE #ifdef B1 .SS Security Restrictions .PP You must have the .CR lvm secondary subsystem authorization to use this command. #endif .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES .PP Change the permission of a logical volume to read-only: .IP .C "lvchange -p r /dev/vg01/lvol3" .PP Change the allocation policy of a logical volume to nonstrict: .IP .C "lvchange -s n /dev/vg01/lvol7" .PP Turn the mirror write cache off on a logical volume: .IP .C "lvchange -M n /dev/vg01/lvol1" .SH DEPENDENCIES The .CR -r option is not available on HP-IB devices. .SH WARNINGS For root, swap or dump logical volumes, its allocation policy is always contiguous. This attribute cannot be changed with .CR lvchange . .SH SEE ALSO lvcreate(1M), lvdisplay(1M), lvextend(1M). .\" .\" toc@\f3lvchange(1M)\f1:\0\0\f4lvchange\f1@@@change LVM logical volume characteristics .\" .\" index@\f4lvchange\f1 \- change LVM logical volume characteristics@@@\f3lvchange(1M)\f1 .\" index@change LVM logical volume characteristics@@@\f3lvchange(1M)\f1 .\" index@LVM logical volume characteristics, change@@@\f3lvchange(1M)\f1 .\" index@logical volume characteristics (LVM), change@@@\f3lvchange(1M)\f1 .\" index@characteristics, change LVM logical volume@@@\f3lvchange(1M)\f1 .\" $Header: lvcreate.1m,v 78.1.1.1 98/02/05 11:29:31 ssa Exp $ .TA l .TH lvcreate 1M .SH NAME lvcreate \- create logical volume in LVM volume group .SH SYNOPSIS .CR /sbin/lvcreate .RC [ -A .IR autobackup ] .RC [ -c .IR mirror_consistency ] .RC [ -C .IR contiguous ] .ifn .br .ifn \0\0\0\0 .RC [ -d .IR schedule ] .ift .br .ift \0\0\0\0 .RC [ -D .IR distributed ] .ifn .br .ifn \0\0\0\0 .RC [ -i .IR stripes .CR -I .IR stripe_size ] .RC [ -l .IR le_number \(or .CR -L .IR lv_size ] .ift .br .ift \0\0\0\0 .ifn .br .ifn \0\0\0\0 .RC [ -m .IR mirror_copies ] .RC [ -M .IR mirror_write_cache ] .RC [ -n .IR lv_name ] .ifn .br .ifn \0\0\0\0 .RC [ -p .IR permission ] .RC [ -r .IR relocate ] .RC [ -s .IR strict ] .IR vg_name .SS Remarks .ss 12 Mirror disk operations require the installation of the optional HP MirrorDisk/UX software, which is not included in the standard HP-UX operating system. .sp .CR lvcreate cannot be performed if the volume group is activated in shared mode. .sp Logical volumes that were created using the striped option are not supported in shared mode. .SH DESCRIPTION The .CR lvcreate command creates a new logical volume within the volume group specified by .IR vg_name . Up to 255 logical volumes can be created in one volume group. .PP If you specify the .CI -n \ lv_name option, a new logical volume is created with that name. Otherwise, a system-generated name of the form .CI lvol N is created, where .IR N is the decimal equivalent of the two least significant bytes of the minor number of the new logical volume, in the range .CR 1 to .CR 255 (see .IR lvm (7)). Two device files are created in .IR vg_name : a block device file named .IR lv_name or .CI lvol N\f1, and a character (raw) device file named .CI r lv_name or .CI rlvol N\f1. .PP If you omit the .CR -l and .CR -L options, the logical volume is created with zero length. This permits you to choose its physical volume location when you allocate logical extents with the .CR lvextend command (see .IR lvextend (1M)). If you specify .CR -l or .CR -L , the location is determined automatically. .PP The default settings provide the most commonly used characteristics. Use the options to tailor the logical volume to the requirements of the system. Once a logical volume is created, some of its characteristics can be changed with the .CR lvchange , .CR lvextend , and .CR lvreduce commands (see .IR lvchange (1M), .IR lvextend (1M), and .IR lvreduce (1M)). .SS Options and Arguments The .CR -c , .CR -d , .CR -m , .CR -M , and .CR -s options are only meaningful if the optional HP MirrorDisk/UX software has been installed on the system. .PP .CR lvcreate recognizes the following options and arguments: .RS .TP 25 .I vg_name The path name of a volume group. .TP .CI -A \0autobackup Set automatic backup for this invocation of this command. .I autobackup can have one of the following values: .RS .RS .TP .CR y Automatically back up configuration changes made to the logical volume. This is the default. .IP After this command executes, the .CR vgcfgbackup command (see .IR vgcfgbackup (1M)) is executed for the volume group to which the logical volume belongs. .TP .CR n Do not back up configuration changes this time. .RE .RE .TP .CI -c \0mirror_consistency Set mirror consistency recovery. This option is effective only when .CR "-M n" is specified. It is ignored for .CR "-M y" . .I mirror_consistency can have one of the following values: .RS .RS .TP .CR y Set mirror consistency recovery on. This is the default. .IP LVM achieves mirror consistency during volume group activation by going through all logical extents and copying data from a nonstale copy to the other mirror copies. .TP .CR n Set mirror consistency recovery off. LVM does not perform mirror consistency recovery on this logical volume when the volume group is activated. .RE .RE .TP .CI -C \0contiguous Set the contiguous allocation policy. A contiguous logical volume has three characteristics: .RS .RS .TP .PD 0 \(bu Physical extents are allocated in ascending order, .TP \(bu No gap is allowed between physical extents within a mirror copy, .TP \(bu Physical extents of any mirror copy all reside on a single physical volume. .PD .RE .RE .IP Use the strict .RC ( -s ) and contiguous .RC ( -C ) options together to form various combined allocation policies on a logical volume. For example, .CR "-s y -C y" defines a logical volume such that each mirror copy is contiguous, yet mirror copies of a logical extent cannot share the same physical volume. .IP .IR contiguous can have one of the following values: .RS .RS .TP .CR y Set a contiguous allocation policy. .TP .CR n Do not set a contiguous allocation policy. This is the default. .RE .RE .TP .CI -d \0schedule Set the scheduling policy when a logical extent with more than one mirror is written. (The scheduling policy of a striped logical volume is striped and cannot be changed.) .I schedule can have one of the following values: .RS .RS .TP .CR p Establish a parallel scheduling policy. This is the default. .TP .CR s Establish a sequential scheduling policy. Use this value with care, because it leads to performance loss in most cases. .RE .RE .TP .CI -D \0distributed Set the distributed allocation policy. .I distributed can have one of the following values: .RS .RS .TP .CR y Turn on distributed allocation. .TP .CR n Turn off distributed allocation. This is the default. .RE .RE .IP When the distributed allocation policy is turned on, only one free extent is allocated from the first available physical volume. The next free extent is allocated from the next available physical volume. Allocation of free extents proceeds in round-robin order on the list of available physical volumes. .IP When the distributed allocation policy is turned off, all available free extents are allocated from each available physical volume before proceeding to the next available physical volume. This is the default. .IP The distributed allocation policy REQUIRES the PVG-strict allocation policy ( .CR "-s g" ) to ensure that mirrors of distributed extents do not overlap (for maximum availability). .IP .IR lvcreate (1M) will obtain the list of available physical volumes from /etc/lvmpvg. See .IR vgextend (1M) for more information on physical volume groups and /etc/lvmpvg. .IP When a logical volume with distributed extents is mirrored, the resulting layout is commonly referred to as EXTENT-BASED MIRRORED STRIPES. .IP Note that EXTENT-BASED MIRRORED STRIPES can be created without the distributed allocation policy by adding one extent at a time to the desired physical volumes through .IR lvextend (1M). .IP The distributed allocation policy is incompatible with the striped scheduling policy ( .CI -i \0stripes ) and the contiguous allocation policy ( .CR "-C y" ). .IP The .IR lvchange (1M) command can be used to assign the distributed allocation policy to an existing logical volume. .IP See .IR lvdisplay (1M) for display values. .IP See EXAMPLES. .TP .CI -i \0stripes Set the number of disks to stripe across. .IR stripes must be in the range .CR 2 to the number of disks in the current volume group. .CR -i and .CR -I must be specified together. .TP .CI -I \0stripe_size Set the size in kilobytes of the stripe. .IR stripe_size can have the value .CR 4 , .CR 8 , .CR 16 , .CR 32 , or .CR 64 . .CR -i and .CR -I must be specified together. .TP .CI -l \0le_number Allocate space to the logical volume, specified in logical extents. .I le_number is a decimal value in the range .CR 1 to .CR 65535 (the implementation limit). The default is described above. .IP Either .CR -l or .CR -L can be specified, but not both. .TP .CI -L \0lv_size Allocate space to the logical volume, specified in megabytes. .I lv_size is a decimal value in the range .CR 1 to .CR 16777216 (the implementation limit). .I lv_size is rounded up to the nearest multiple of the logical extent size, equivalent to the physical extent size defined for the volume group by the .CR vgcreate command (see .IR vgcreate (1M)). The default is described above. .IP Either the .CR -l or the .CR -L option can be specified, but not both. .TP .CI -m \0mirror_copies Set the number of mirror copies allocated for each logical extent. A mirror copy contains the same data as the original. .I mirror_copies can have the value .CR 1 or .CR 2 . The default value is .CR 0 (no mirror copies). .TP .CI -M \0mirror_write_cache Set the Mirror Write Cache flag. .I mirror_write_cache can have one of the following values: .RS .RS .TP .CR y Set Mirror Write Cache on. This is the default. .IP Every write to a mirror copy is recorded in the Mirror Write Cache. The Mirror Consistency Record in the Volume Group Reserved Area on the disk is updated whenever there is a write to a logical track group that is not already recorded in the cache. This allows LVM to determine whether all the mirror copies are identical, even across system crashes. When the volume group is activated, the Mirror Consistency Record is used to perform mirror consistency recovery. .TP .CR n Set Mirror Write Cache to off. Mirror write does not incur an additional write to the Mirror Consistency Record. .RE .RE .TP .CI -n \0lv_name Set the name of the new logical volume to .IR lv_name , where .IR lv_name is a simple file name, not a path name. The default is described above. .TP .CI -p \0permission Set the access permission. .I permission can have one of the following values: .RS .RS .TP .CR w Set the access permission to read-write. This is the default. .TP .CR r Set the access permission to read-only. .RE .RE .TP .CI -r \0relocate Set the bad block relocation policy. .I relocate can have one of the following values: .RS .RS .TP .CR y Allow bad block relocation. Upon an EMEDIA failure, LVM will mark the failed block in the Bad Block Directory, and attempt to relocate the block to a new location on the disk. This is the default. .TP .CR n Prevent bad block relocation. Upon an EMEDIA failure, LVM will mark the failed block as bad in the Bad Block Directory, but will not attempt to relocate the bad block to a new location. .TP .CR N Prevent bad block relocation and the Bad Block Directory. Upon an EMEDIA failure, LVM will not attempt to relocate the failed block, nor will it even mark the block as bad in the Bad Block Directory. .RE .RE .TP .CI -s \0strict Set the strict allocation policy. Mirror copies of a logical extent can be allocated to share or not share the same physical volume or physical volume group. .I strict can have one of the following values: .RS .RS .TP .CR y Set a strict allocation policy. Mirrors of a logical extent cannot share the same physical volume. This is the default. .TP .CR g Set a PVG-strict allocation policy. Mirrors of a logical extent cannot share the same physical volume group. A PVG-strict allocation policy cannot be set on a logical volume in a volume group that does not have a physical volume group defined. .TP .CR n Do not set a strict or PVG-strict allocation policy. Mirrors of a logical extent can share the same physical volume. .RE .RE .RE #ifdef B1 .SS Security Restrictions .PP You must have the .CR lvm secondary subsystem authorization to use this command. #endif .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES .PP Create a logical volume in volume group .CR /dev/vg02 : .IP .C "lvcreate /dev/vg02" .PP Create a logical volume in volume group .CR /dev/vg03 with nonstrict allocation policy: .IP .C "lvcreate -s n /dev/vg03" .PP Create a logical volume of size 100 MB in volume group .CR /dev/vg03 : .IP .C "lvcreate -L 100 /dev/vg03" .PP Create a logical volume of size 90 MB striped across 3 disks with a stripe size of 64 KB: .IP .C "lvcreate -L 90 -i 3 -I 64 /dev/vg03" .PP DISTRIBUTED ALLOCATION POLICY .PP This example shows how the -D y option can be used to create EXTENT-BASED MIRRORED STRIPES. .PP Assume that volume group /dev/vgtest has two physical volume groups: "pvg1", "pvg2". .PP Assume that each physical volume group has 2 physical volumes. .PP Assume that the first physical volume in each pvg has 3 extents free and the second physical volume in each pvg has 2 extents free. .PP The following command creates a logical volume in vgtest with EXTENT-BASED MIRRORED STRIPES: .IP .C "lvcreate -D y -s g -m 1 -l 5 /dev/vgtest" .PP The distributed allocation proceeds as follows: .RS .RS .PD 0 .TP \(bu A free extent is allocated from the 1st pvol in pvg1. .TP \(bu A free extent is allocated from the 2nd pvol in pvg1. .TP \(bu A free extent is allocated from the 1st pvol in pvg1. .TP \(bu A free extent is allocated from the 2nd pvol in pvg1. .TP \(bu A free extent is allocated from the 1st pvol in pvg1. .TP \(bu Mirrors for the five extents are then allocated from the free extents in pvg2 in a similar manner. .PD .RE .RE .SH WARNINGS The .CR -m and .CR -r options cannot be used with HP-IB devices. .PP The root, swap, and dump logical volumes (see .IR lvlnboot (1m)) must be created with contiguous allocation policy. .SH SEE ALSO lvchange(1M), lvdisplay(1M), lvextend(1M), lvreduce(1M), pvchange(1M), vgextend(1M). .\" .\" toc@\f3lvcreate(1M)\f1:\0\0\f4lvcreate\f1@@@create logical volume in LVM volume group .\" .\" index@\f4lvcreate\f1 \- create logical volume in LVM volume group@@@\f3lvcreate(1M)\f1 .\" index@create logical volume in LVM volume group@@@\f3lvcreate(1M)\f1 .\" index@logical volume in LVM volume group, create@@@\f3lvcreate(1M)\f1 .\" index@volume in LVM volume group, create logical@@@\f3lvcreate(1M)\f1 .\" index@LVM volume group, create logical volume in@@@\f3lvcreate(1M)\f1 .\" index@volume group (LVM), create logical volume in@@@\f3lvcreate(1M)\f1 .\" $Header: lvdisplay.1m,v 78.1.1.1 98/02/05 11:23:22 ssa Exp $ .TA l .TH lvdisplay 1M .SH NAME lvdisplay \- display information about LVM logical volumes .SH SYNOPSIS .CR /sbin/lvdisplay .RC [ -k ] .RC [ -v ] .I lv_path \ ... .SS Remarks Mirror disk information requires the installation of the optional HP MirrorDisk/UX software, which is not included in the standard HP-UX operating system. .SH DESCRIPTION The .CR lvdisplay command displays the characteristics and status of each logical volume specified by .IR lv_path . .SS Options and Arguments .CR lvdisplay recognizes the following options and arguments: .RS .TP 10 .I lv_path The block device path name of a logical volume, for example, .CR /dev/vg00/lvol1 . .TP .CR -v For each logical volume, display the physical volume distribution, and the mapping of the logical extents onto the physical extents of the physical volumes. .TP .CR -k This option displays the same information as the .CR -v option, except in the column where .CR "PV Name" is displayed, the .CR pvkey (Physical Volume Number in VG) will be displayed instead. .IP Use this option with the .CR -v option. .RE .SS Display Without \(miv Option If you omit the .CR -v option, .CR lvdisplay displays the following information for each logical volume: .TP .CR "--- Logical volumes ---" .RS .TP 20 .CR "LV Name" The block device path name of the logical volume. .TP .CR "VG Name" The path name of the volume group. .TP .CR "LV Permission" Access permission: .CR read-only or .CR read/write . .TP .CR "LV Status" State of the logical volume: .RS .TP 25 .CR available/stale Available but contains physical extents that are not current. .TP .CR available/syncd Available and synchronized. .TP .CR available Available but the stale or synchronized state cannot be confidently determined because both Mirror Write Cache and Mirror Consistency Recovery are turned off. .TP .CR unavailable Not available for use. .RE .TP .CR "Mirror copies" Number of physical extents beyond the original allocated for each logical extent; i.e., the number of mirrors: 0, 1, or 2. .TP .CR "Consistency Recovery" Mode of mirror consistency recovery which determines how LVM performs mirror consistency recovery during volume group activation: .RS .TP 10 .CR MWC Recover mirror consistency by using the Mirror Write Cache and Mirror Consistency Record. Implies that Mirror Write Cache is on. .TP .CR NOMWC Recover mirror consistency by going through all logical extents and copying data from a non-stale copy to the other mirror copies. Implies that Mirror Write Cache is off. .TP .CR NONE No mirror consistency recovery during volume group activation on this logical volume. Implies that Mirror Write Cache is off. .RE .TP .CR "Schedule" Striped, sequential or parallel scheduling policy. Striped policy is by default parallel scheduling for mirrored I/O. .TP .CR "LV Size (Mbytes)" Size of the logical volume in megabytes (MB). .TP .CR "Current LE" Number of logical extents currently in the logical volume. .TP .CR "Allocated PE" Number of physical extents allocated to the logical volume. .TP .CR Stripes The number of stripes. If this field is 0, then the logical volume is not striped. .TP .CR "Stripe Size (Kbytes)" The size of each stripe in kilobytes (KB). .TP .CR "Bad block" Bad block relocation policy. .br .ne 8 .TP .CR "Allocation" Current allocation state, displayed as one of: .RS .RS .ifn .TP 15 .ift .TP 25 .PD 0 .CR non-strict .CR non-strict/contiguous .TP .CR strict .CR strict/contiguous .TP .CR PVG-strict .CR PVG-strict/contiguous .TP .CR .CR PVG-strict/distributed .TP .CR .CR PVG-strict/partially-distributed .PD .RE .TP 15 .CR contiguous Physical extents are allocated in an ascending order without any gap between adjacent extents. All physical extents of a given mirror are contained in a single physical volume. .TP .CR distributed Distributed allocation is turned on and any two consecutive logical extents are guaranteed to be located on different physical volumes. See .IR lvcreate (1M) for more information. .TP .CR partially-distributed Distributed allocation is turned on but any two consecutive logical extents are NOT guaranteed to be located on different physical volumes. See .IR lvchange (1M) for more information. .TP .CR non-strict Physical extents that belong to the same logical extent can be allocated on the same physical volume or physical volume group. .TP .CR PVG-strict Mirror copies for a logical extent are not allocated on the same physical volume group. .TP .CR strict Mirror copies for a logical extent are not allocated on the same physical volume. .RE .RE .SS Display With \(miv Option If you specify the .CR -v option, .CR lvdisplay also lists the distribution of each logical volume across the physical volumes of the volume group and the mapping of each logical extent of the logical volume on the physical extents of the physical volume. .TP .CR "--- Distribution of logical volume ---" .IP The distribution of logical volume .I lv_path across the physical volumes of the volume group, displayed in the following columns: .RS .TP 20 .CR "PV Name" The block device path name of the physical volume where the logical extents are allocated. .TP .CR "PVNUM" The Physical Volume Number in VG (if .CR -k option is specified). .TP .CR "LE on PV" Number of logical extents allocated on the physical volume. .TP .CR "PE on PV" Number of physical extents allocated on the physical volume. .RE .TP .CR "--- Logical extents ---" .IP The mapping of logical extents onto physical extents, displayed in the following columns: .RS .TP 20 .CR LE Logical extent number. .TP .CR PV1 The block device path name of the physical volume that corresponds to the location of the first physical extent of the logical extent. .TP .CR PE1 First physical extent number allocated to the logical extent. .TP .CR "Status 1" Status of the first physical extent: .CR stale or .CR current . .HP The following columns are displayed for one or two mirror copies: .TP .CR PV2 The block device path name of the physical volume that corresponds to the location of the second physical extent (first copy) of the logical extent. .TP .CR PE2 Second physical extent number allocated to the logical extent. .TP .CR "Status 2" Status of the second physical extent: .CR stale or .CR current . .HP The following columns are displayed for two mirror copies: .TP .CR PV3 The block device path name of the physical volume that corresponds to the location of the third physical extent (second copy) of the logical extent. .TP .CR PE3 Third physical extent number allocated to the logical extent. .TP .CR "Status 3" Status of the third physical extent: .CR stale or .CR current . .RE #ifdef B1 .SS Security Restrictions .PP You must have the .CR lvm secondary subsystem authorization to use this command. #endif .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Display information about a logical volume: .IP .C "lvdisplay /dev/vg01/lvol3" .PP Display all the available information about a logical volume, including the characteristics, status and distribution map: .IP .C "lvdisplay -v /dev/vg01/lvol3" .PP Display all the available information about a logical volume, but display .CR pvkey instead of .CR "PV Name" in the status and distribution map. .IP .C "lvdisplay -v -k /dev/vg01/lvol3" .SH SEE ALSO lvchange(1M), lvcreate(1M), lvextend(1M), lvreduce(1M), pvdisplay(1M), vgdisplay(1M). .\" .\" toc@\f3lvdisplay(1M)\f1:\0\0\f4lvdisplay\f1@@@display information about LVM logical volumes .\" .\" index@\f4lvdisplay\f1 \- display information about LVM logical volumes@@@\f3lvdisplay(1M)\f1 .\" index@display information about LVM logical volumes@@@\f3lvdisplay(1M)\f1 .\" index@information about LVM logical volumes, display@@@\f3lvdisplay(1M)\f1 .\" index@LVM logical volumes, display information about@@@\f3lvdisplay(1M)\f1 .\" index@logical volumes (LVM), display information about@@@\f3lvdisplay(1M)\f1 .\" $Header: lvextend.1m,v 78.1 96/02/13 13:14:48 ssa Exp $ .TA l .TH lvextend 1M .SH NAME lvextend \- increase space, increase mirrors for LVM logical volume .SH SYNOPSIS .CR /sbin/lvextend .RC [ -A .IR autobackup ] .br \0\0\0\0 .RC { -l .I le_number \(or .CR -L .I lv_size \(or .CR -m .IR mirror_copies } .ifn .br .ifn \0\0\0\0 .I lv_path .RI [ pv_path \ ...\& \(or .IR pvg_name \ ...] .SS Remarks .ss 12 Mirror disk operations require the installation of the optional HP MirrorDisk/UX software, which is not included in the standard HP-UX operating system. .sp .CR lvextend cannot be performed if the volume group is activated in shared mode. .sp Existing logical volumes that were created using the striped option are not supported in shared mode. .SH DESCRIPTION The .CR lvextend command can increase a logical volume's allocated space, or increase its number of mirrored copies. .PP Other logical volume characteristics can be modified with the .CR lvchange and .CR lvreduce commands (see .IR lvchange (1M) and .IR lvreduce (1M)). .PP To limit the allocation to specific physical volumes, specify the physical volume names as .I pv_path arguments or specify the physical volume group names as .I pvg_name arguments. Otherwise, all of the physical volumes in a volume group are available for allocating new physical extents. LVM always ensures that physical extent allocation can satisfy the current allocation policy or policies. If a physical volume is not suitable for use with a certain allocation policy, it is not used during physical extent allocation, even it is specified in a .I pv_path argument or indirectly in a .I pvg_name argument. .PP The .I pvg_name argument is allowed only if one of the allocation policies of the logical volume is PVG-strict. .SS Options and Arguments The .CR -m option is only meaningful if the optional HP MirrorDisk/UX software has been installed on the system. .PP .CR lvextend recognizes the following options and arguments: .RS .TP 25 .I lv_path The block device path name of a logical volume. .TP .I pv_path The block device path name of a physical volume. .TP .I pvg_name The name of a physical volume group (see .IR lvmpvg (1M)). .TP .CI -A \0autobackup Set automatic backup for this invocation of this command. .I autobackup can have one of the following values: .RS .RS .TP .CR y Automatically back up configuration changes made to the logical volume. This is the default. .IP After this command executes, the .CR vgcfgbackup command (see .IR vgcfgbackup (1M)) is executed for the volume group to which the logical volume belongs. .TP .CR n Do not back up configuration changes this time. .RE .RE .TP .CI -l \0le_number Increase the space allocated to the logical volume, specified in logical extents. .I le_number is a decimal value greater than the current number of logical extents, in the range .CR 1 to .CR 65535 (the implementation limit). .IP One, and only one, .CR -l , .CR -L , or .CR -m option must be supplied. .TP .CI -L \0lv_size Increase the space allocated to the logical volume, specified in megabytes. .I lv_size is a decimal value greater than the current logical volume size, in the range .CR 1 to .CR 16777216 (the implementation limit). .I lv_size is rounded up to the nearest multiple of the logical extent size, equivalent to the physical extent size defined for the volume group by the .CR vgcreate command (see .IR vgcreate (1M)). .IP One, and only one, .CR -l , .CR -L , or .CR -m option must be specified. .TP .CI -m \0mirror_copies Set the number of mirror copies allocated for each logical extent. A mirror copy contains the same data as the original. .I mirror_copies can have the value .CR 1 or .CR 2 . It must be greater than the current value. .IP Data in the new copies is synchronized. The synchronization process can be time consuming, depending on hardware characteristics and the amount of data. .IP One, and only one, .CR -l , .CR -L , or .CR -m option must be specified. .RE #ifdef B1 .SS Security Restrictions .PP You must have the .CR lvm secondary subsystem authorization to use this command. #endif .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Increase the number of the logical extents of a logical volume to 100: .IP .C "lvextend -l 100 /dev/vg01/lvol3" .PP Increase the logical volume size to 400 MB: .IP .C "lvextend -L 400 /dev/vg01/lvol4" .PP Allocate two mirrors (that is, two copies of the original) for each logical extent of a logical volume: .IP .C "lvextend -m 2 /dev/vg01/lvol5" .PP Mirror a logical volume onto a particular physical volume. .IP .C "lvextend -m 1 /dev/vg00/lvol3 /dev/dsk/c0t3d0" .PP Increase the size of a file system existing on a logical volume. .RS .PP First, increase the size of the logical volume. .IP .C "lvextend -L 400 /dev/vg06/lvol3" .PP Unmount the file system. .IP .C "umount /dev/vg06/lvol3" .PP Extend the file system to occupy the entire (larger) logical volume. .IP .C "extendfs /dev/vg06/rlvol3" .PP Remount the file system. .IP .C "mount /dev/vg06/lvol3 /mnt" .RE .SH WARNINGS The .CR -m option cannot be used on HP-IB devices. .SH SEE ALSO lvchange(1M), lvcreate(1M), lvdisplay(1M), lvreduce(1M), pvchange(1M), pvdisplay(1M). .\" .\" toc@\f3lvextend(1M)\f1:\0\0\f4lvextend\f1@@@stripe, increase space, increase mirrors for LVM logical volume .\" .\" index@\f1LVM logical volume, stripe, increase space, increase mirrors@@@\f3lvextend(1M)\f1 .\" index@\f1increase mirrors for LVM logical volume@@@\f3lvextend(1M)\f1 .\" index@\f1increase space for LVM logical volume@@@\f3lvextend(1M)\f1 .\" index@\f1logical volume (LVM), stripe, increase space, increase mirrors@@@\f3lvextend(1M)\f1 .\" index@\f1mirrors for LVM logical volume, increase@@@\f3lvextend(1M)\f1 .\" index@\f1space for LVM logical volume, increase@@@\f3lvextend(1M)\f1 .\" index@\f1stripe LVM logical volume@@@\f3lvextend(1M)\f1 .\" index@\f4lvextend\f1 \- stripe, increase space, increase mirrors for LVM logical volume@@@\f3lvextend(1M)\f1 .\" $Header: lvlnboot.1m,v 78.1.1.1 98/02/05 11:05:38 ssa Exp $ .TA l .TH lvlnboot 1M .SH NAME lvlnboot \- prepare LVM logical volume to be root, boot, primary swap, or dump volume .SH SYNOPSIS .HP .CR /usr/sbin/lvlnboot .RC [\|[ -A .IR autobackup ] .ifn .br { .CR -b .IR boot_lv \(or .CR -d .IR dump_lv \(or .CR -r .IR root_lv \(or .ift .br .CR -R \(or .CR -s .IR swap_lv }\|] .RC [ -v ] .RI [ vg_name ] .PP .CR /usr/sbin/lvlnboot .RC [ -c ] .SS Remarks .CR lvlnboot cannot be performed if the volume group is activated in shared mode. .SH DESCRIPTION The .CR lvlnboot command updates all physical volumes in the volume group so that the logical volume becomes the root, boot, primary swap, or a dump volume when the system is next booted on the volume group. If a nonexistent logical volume is specified, this command fails. If a different logical volume is already linked to the root or primary swap, the command fails. .PP This command should be run in recovery mode .RC ( -R ) whenever the configuration of the root volume group is affected by one of the following commands: .CR lvextend , .CR lvmerge , .CR lvreduce , .CR lvsplit , .CR pvmove , .CR lvremove , .CR vgextend , or .CR vgreduce (see .IR lvextend (1M), .IR lvmerge (1M), .IR lvreduce (1M), .IR lvsplit (1M), .IR pvmove (1M), .IR lvremove (1M), .IR vgextend (1M), and .IR vgreduce (1M)). Starting with HP-UX Release 10.0, this is done automatically. .SS Options and Arguments .CR lvlnboot recognizes the following options and arguments: .RS .TP 20 .I vg_name The path name of a volume group. .TP .CI -A \0autobackup Set automatic backup for this invocation of this command. .I autobackup can have one of the following values: .RS .TP .CR y Automatically back up configuration changes made to the logical volume. This is the default. .IP After this command executes, the .CR vgcfgbackup command (see .IR vgcfgbackup (1M)) is executed for the volume group to which the logical volume belongs. .TP .CR n Do not back up configuration changes this time. .RE .TP .CI -b \0boot_lv Define .I boot_lv to be the boot volume the next time the system is booted on the volume group. .I boot_lv must be the first logical volume on the physical volume. .I boot_lv must be contiguous, and must not allow bad block relocation. .IP .I boot_lv is used to locate the boot file system during the boot process. The boot file system has the kernel which is read by the boot loader .IR hpux (1M). .TP .CI -d \0dump_lv Define .I dump_lv to be one of the dump volumes the next time the system is booted on the volume group. .I dump_lv must be a contiguous logical volume and cannot have Bad Block Relocation enabled. .IP The command updates the Boot Data Reserved Area of each bootable physical volume in the volume group (see .IR pvcreate (1M)). .IP The combined size of all the dump volumes should be at least 2048 bytes larger than the total memory of the system. The additional 2 KB is used to safeguard against a dump to the bottom of the disk. .IP Multiple dump devices can be configured, but each .I dump_lv must be entered with a separate .CR lvlnboot command line. .TP .CI -r \0root_lv Define .I root_lv to be the root volume the next time the system is booted on this volume group. .I root_lv must be a contiguous logical volume and cannot have bad block relocation enabled. .IP If .I root_lv is the first logical volume on the physical volume, then it is configured as the combined root-boot volume. Otherwise, .I root_lv is configured as the separate root volume in which case a separate boot volume needs to be configured using the .CR "lvlnboot\ -b" option. .IP Either the separate root or the separate boot volume can be configured first. .IP The command updates the Boot Data Reserved Area of each bootable physical volume (see .IR pvcreate (1M)) to enable the volume group to be used to locate the root file system. .I root_lv is also used as the root volume during a maintenance-mode boot (see .IR hpux (1M)). .IP The physical volumes containing .I root_lv must have been created using the .CR "pvcreate\ -B" option (see .IR pvcreate (1M)), indicating that that physical volume is to be used as a bootable physical volume. Also, the .CR mkboot command (see .IR mkboot (1M)) must have been run on the physical volume to create the LIF area at the top of the physical volume (see .IR lif (4)). .TP .CI -R Recover any missing links to all of the logical volumes specified in the Boot Data Reserved Area and update the Boot Data Reserved Area of each bootable physical volume in the volume group (see .IR pvcreate (1M)). .TP .CI -s \0swap_lv Define .I swap_lv to be the primary swap volume the next time the system is booted on the volume group. .I swap_lv must be a contiguous logical volume, and a root logical volume must have been previously defined with this command. .IP The command updates the Boot Data Reserved Area of each bootable physical volume in the volume group (see .IR pvcreate (1M)). Any existing swap area previously defined must be removed via .IR lvrmboot (1M). .TP .CR -c During normal boots (vs. maintenance-mode boots, see .IR hpux (1M)), this command is automatically executed by .CR /sbin/ioinitrc (see .IR inittab (4)). .IP Since this command is performed during boot, it does not need to be performed manually unless .CR /stand/rootconf is missing in a separate root/boot configuration (or alternatively, performing a normal reboot will recreate this file). .IP This command updates the .CR /stand/rootconf file with the location of the root volume in the currently booted volume group. .IP The .CR /stand/rootconf file is used during maintenance-mode boots to locate the root volume for volume groups with separate boot and root volumes. .IP During maintenance-mode boots, since the root volume group is not activated, .CR "lvlnboot\ -c" does not update .CR /stand/rootconf . For separate root/boot configurations, maintenance-mode boot will fail if .CR /stand/rootconf does not already exist with the correct location of the root volume. See .CT WARNINGS . .IP When a new volume group with separate boot and root volumes is created, the first boot must be a normal boot (versus. a maintenance-mode boot), so that .CR /stand/rootconf gets created. .IP This option does not allow updating .CR /stand/rootconf for any volume group other than the one that is booted. .TP .CR -v Print verbose messages. With no other arguments present, print information on root, boot, swap, and dump logical volumes. If a combined root-boot volume is configured, no information for the boot volume is displayed. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES .PP The following examples show configuration of a combined root-boot volume. .IP Create a root volume group, .CR vglvmroot , containing root, swap, and dump logical volumes. Assume that an appropriate directory called .CR /dev/vglvmroot and a corresponding .CR group file already exist (see .IR lvm (7)). .IP First, initialize the disk, say .CR /dev/dsk/c0t0d0 , so that it can be used as an LVM boot disk. .RS .nf .IP .C "pvcreate -B /dev/rdsk/c0t0d0" .fi .RE .IP Place the LIF information on the disk using the .CR mkboot command. .RS .nf .IP .C "mkboot /dev/rdsk/c0t0d0" .fi .RE .IP Create the volume group .CR vglvmroot . .RS .nf .IP .C "vgcreate /dev/vglvmroot /dev/dsk/c0t0d0" .fi .RE .IP Create a logical volume that is suitable for use as the root volume. This logical volume has to be the first in the volume group and should be a contiguous volume with bad block relocation turned off. .RS .nf .IP .C "lvcreate -n root -L 120 -C y -r n /dev/vglvmroot" .fi .RE .IP Create a logical volume that will be used as primary swap. This volume should be contiguous. .RS .nf .IP .C "lvcreate -n swap -L 64 -C y /dev/vglvmroot" .fi .RE .IP Create a logical volume that will be used as the dump volume. This volume should be contiguous. .RS .nf .IP .C "lvcreate -n dump -L 64 -C y /dev/vglvmroot" .fi .RE .IP Specify that the logical volume, .CR root , will be used as the root volume. .RS .nf .IP .C "lvlnboot -r /dev/vglvmroot/root" .fi .RE .IP Specify that the logical volume, .CR swap , will be used as the primary swap. .RS .nf .IP .C "lvlnboot -s /dev/vglvmroot/swap" .fi .RE .IP Specify that the logical volume, .CR dump , will be used as the dump volume. .RS .nf .IP .C "lvlnboot -d /dev/vglvmroot/dump" .fi .RE .IP Display the results of the previous operations. .RS .nf .IP .C "lvlnboot -v /dev/vglvmroot" .fi .RE .PP The following examples show configuration of separate root and boot volumes. .IP Create a root volume group, .CR vglvmroot , containing root, boot, swap, and dump logical volumes. Assume that an appropriate directory called .CR /dev/vglvmroot and a corresponding .CR group file already exist (see .IR lvm (7)). .IP First, initialize the disk, say .CR /dev/dsk/c0t0d0 , so that it can be used as an LVM boot disk. .RS .nf .IP .C "pvcreate -B /dev/rdsk/c0t0d0" .fi .RE .IP Place the LIF information on the disk using the .CR mkboot command. .RS .nf .IP .C "mkboot /dev/rdsk/c0t0d0" .fi .RE .IP Create the volume group .CR vglvmroot . .RS .nf .IP .C "vgcreate /dev/vglvmroot /dev/dsk/c0t0d0" .fi .RE .IP Create a logical volume that is suitable for use as the boot volume. This logical volume has to be the first in the volume group and should be a contiguous volume with bad block relocation turned off. .RS .nf .IP .C "lvcreate -n boot -L 24 -C y -r n /dev/vglvmroot" .fi .RE .IP Create a logical volume that is suitable for use as the root volume. This logical volume should be a contiguous volume with bad block relocation turned off. .RS .nf .IP .C "lvcreate -n root -L 64 -C y -r n /dev/vglvmroot" .fi .RE .IP Create a logical volume that will be used as primary swap. This volume should be contiguous. .RS .nf .IP .C "lvcreate -n swap -L 64 -C y /dev/vglvmroot" .fi .RE .IP Create a logical volume that will be used as the dump volume. This volume should be contiguous. .RS .nf .IP .C "lvcreate -n dump -L 64 -C y /dev/vglvmroot" .fi .RE .IP Specify that the logical volume, .CR root , will be used as the root volume. .RS .nf .IP .C "lvlnboot -r /dev/vglvmroot/root" .fi .RE .IP Specify that the logical volume, .CR boot , will be used as the boot volume. .RS .nf .IP .C "lvlnboot -b /dev/vglvmroot/boot" .fi .RE .IP Specify that the logical volume, .CR swap , will be used as the primary swap. .RS .nf .IP .C "lvlnboot -s /dev/vglvmroot/swap" .fi .RE .IP Specify that the logical volume, .CR dump , will be used as the dump volume. .RS .nf .IP .C "lvlnboot -d /dev/vglvmroot/dump" .fi .RE .IP Display the results of the previous operations. .RS .nf .IP .C "lvlnboot -v /dev/vglvmroot" .fi .RE .PP The following example shows configuration of multiple dump volumes. .PP Specify that logical volumes .CR /dev/vg00/swap1 , .CR /dev/vg00/dump2 , and .CR /dev/vg00/dump3 should be used as the dump logical volumes and that .CR /dev/vg00/swap1 should also be used as primary swap. Assume that the volume group and the logical volumes have been created and the logical volumes are contiguous. .P .RS .nf .C "lvlnboot -s /dev/vg00/swap1" .C "lvlnboot -d /dev/vg00/swap1" .C "lvlnboot -d /dev/vg00/dump2" .C "lvlnboot -d /dev/vg00/dump3" .fi .RE .SH WARNINGS .SS Dump Volume Warnings A dump logical volume, or a swap logical volume used as a dump volume, must lie within the first 2 GB (< 2 GB) of the physical volume. The .CR lvlnboot command will not allow a dump logical volume to be configured that crosses the 2 GB boundary, but it will allow such a swap logical volume to be configured. .PP For a system with high-density memory boards installed, .CR lvlnboot will be able to support dump logical volumes up to 4 GB of the physical volume. .PP If the swap device is used as a dump volume by specifying the .CR dump default in the system file (see .IR config (1M)), care should be taken to ensure that the swap logical volume does not exceed the 2 GB boundary (or 4 GB for the system as mentioned above). .SS Separate Root/Boot Warnings Whenever .IR mkboot (1M) is used to restore the LIF area of a damaged root physical volume, the .CR -b .IR boot_lv option of .CR lvlnboot must be performed afterwards to record the boot volume information inside the new LIF (see .IR lif (4)). Subsequent .CR lvlnboot commands such as .CR "lvlnboot\ -R" are dependent on the .IR boot_lv information inside the LIF. .PP If the .CR -v option does not locate the boot volume .IR boot_lv, and the .CR -r .IR root_lv has not yet been performed, then performing the .CR -r .IR root_lv option will enable the boot volume to be located. The .CR lvlnboot command derives the location of boot volume from the location of the root volume. .SS Separate Root/Boot Maintenance-Mode Warnings .PP When creating additional root volumes with separate root/boot, a normal boot must be performed on each new root volume so that .IR /stand/rootconf, which is required for maintenance-mode boots (see .IR hpux (1M)), gets created for each new root volume. .PP Mirrored .IR root_lv volumes should start at the same offset on each physical volume so that the location stored in .IR /stand/rootconf works for maintenance-mode boots off of any mirror. .SH FILES .RS 0 .TP 25 .CR /stand/rootconf Contains the location of the root volume. Used during maintenance-mode boots (see .IR hpux (1M)) to locate the root volume for volume groups with separate boot and root volumes. .RE .SH "SEE ALSO" lvcreate(1M), lvrmboot(1M), mkboot(1M), pvcreate(1M), vgcreate(1M), inittab(4), lif(4), lvm(7). .\" .\" toc@\f3lvlnboot(1M)\f1:\0\0\f4lvlnboot\f1@@@prepare LVM logical volume to be root, swap, or dump volume .\" .\" index@\f4lvlnboot\f1 \- prepare LVM logical volume to be root, swap, or dump volume@@@\f3lvlnboot(1M)\f1 .\" index@\f1prepare LVM logical volume to be root, swap, or dump volume@@@\f3lvlnboot(1M)\f1 .\" index@\f1LVM logical volume, prepare to be root, swap, or dump volume@@@\f3lvlnboot(1M)\f1 .\" index@\f1logical volume (LVM), prepare to be root, swap, or dump volume@@@\f3lvlnboot(1M)\f1 .\" index@\f1root volume, prepare LVM logical volume to be@@@\f3lvlnboot(1M)\f1 .\" index@\f1primary swap volume, prepare LVM logical volume to be@@@\f3lvlnboot(1M)\f1 .\" index@\f1swap volume, prepare LVM logical volume to be@@@\f3lvlnboot(1M)\f1 .\" index@\f1dump volume, prepare LVM logical volume to be@@@\f3lvlnboot(1M)\f1 .\" $Header: lvmerge.1m,v 76.1 95/07/31 17:21:22 ssa Exp $ .TA l .TH lvmerge 1M "Requires Optional HP MirrorDisk/UX Software" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lvmerge \- merge two LVM logical volumes into one logical volume .SH SYNOPSIS .CR /sbin/lvmerge .RC [ -A .IR autobackup ] .I dest_lv_path .I src_lv_path .SS Remarks This command requires the installation of the optional HP MirrorDisk/UX software, which is not included in the standard HP-UX operating system. .sp .CR lvmerge cannot be performed if the volume group is activated in shared mode. .SH DESCRIPTION The .CR lvmerge command merges two logical volumes of the same size. The number of mirrored copies of the .I dest_lv_path is increased by the number of copies in the .IR src_lv_path. .PP Data previously contained in the .I dest_lv_path is resynchronized using the data in the .IR src_lv_path . All new data on the .I dest_lv_path is destroyed. .PP Whenever a mirrored logical volume is split into two logical volumes, a bit map is stored that keeps track of all writes to either logical volume in the split pair. When the two logical volumes are subsequently merged using .CR lvmerge , the bit map is used to decide which areas of the logical volumes need to be resynchronized. This bit map continues to exist until the merge is completed, or one of the logical volumes is extended or reduced, or the system is rebooted. .PP If there is no bit map available, the entire logical volume is resynchronized. .PP The normal usage for this command is to merge previously mirrored logical volumes that have been split using the .CR lvsplit command (see .IR lvsplit (1M). However, the two logical volumes are not required to have been the result of a previous .CR lvsplit operation. .SS Options and Arguments .CR lvmerge recognizes the following options and arguments: .RS .TP 20 .IR dest_lv_path The block device path name of a logical volume. .TP .IR src_lv_path The block device path name of a logical volume. .TP .CI -A \0autobackup Set automatic backup for this invocation of this command. .I autobackup can have one of the following values: .RS .RS .TP .CR y Automatically back up configuration changes made to the logical volume. This is the default. .IP After this command executes, the .CR vgcfgbackup command (see .IR vgcfgbackup (1M)) is executed for the volume group to which the logical volume belongs. .TP .CR n Do not back up configuration changes this time. .RE .RE .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Merge .CR /dev/vg00/lvol1b with .CR /dev/vg00/lvol1 : Data in /dev/vg00/lvol1b will be overridden by /dev/vg00/lvol1. .IP .C "lvmerge /dev/vg00/lvol1b /dev/vg00/lvol1" .SH WARNINGS If no bit map is found, all data on .I dest_lv_path is lost after the merge. .PP .CR lvmerge does not check to guarantee that the allocation policy of .I src_lv_path is preserved after the merge. .SH SEE ALSO lvcreate(1M), lvextend(1M), lvsplit(1M). .\" .\" toc@\f3lvmerge(1M)\f1:\0\0\f4lvmerge\f1@@@merge two LVM logical volumes into one logical volume .\" .\" index@\f4lvmerge\f1 \- merge two LVM logical volumes into one logical volume@@@\f3lvmerge(1M)\f1 .\" index@\f1merge two LVM logical volumes into one logical volume@@@\f3lvmerge(1M)\f1 .\" index@\f1combine two LVM logical volumes into one logical volume@@@\f3lvmerge(1M)\f1 .\" index@\f1LVM logical volumes, merge two into one logical volume@@@\f3lvmerge(1M)\f1 .\" index@\f1logical volumes (LVM), merge two into one logical volume@@@\f3lvmerge(1M)\f1 .\" $Header: lvmmigrate.1m,v 78.1 96/02/13 13:15:42 ssa Exp $ .TA l .TH lvmmigrate 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lvmmigrate \- prepare root file system for migration from partitions to LVM logical volumes .SH SYNOPSIS .CR /usr/sbin/lvmmigrate .RC [ -d .IR disk_special_file ] .RC [ -e .IR file_system \0...\&] .RC [ -f ] .ifn .br .ifn \0\0\0\0 .RC [ -i .IR file_system \0...\&] .RC [ -n ] .RC [ -v ] .SH DESCRIPTION The .CR lvmmigrate command records the configuration information of the current system in the LIF volume of the boot section for use with a subsequent cold-install process. If there is no LIF volume on the disk, .CR lvmmigrate creates it using .IR lifinit (1), then records the information in a LIF file named .CR CUSTOM . A copy of the LIF file is saved as .CR /tmp/LVMMIGRATE.CFG . The information is also written to file .CR /tmp/LVMMIGRATE for reviewing. The install process looks for the LIF file .CR CUSTOM , and if it exists, uses the information found as the configuration defaults for the root volume group and the root file systems. After the install process has completed, a copy of the .CR CUSTOM final configuration can be found on the newly created system in the file .CR /usr/lib/sw/hpux.install/config.local . .PP All file system entries in the .CR /etc/mnttab and .CR /etc/fstab files are read. .CR lvmmigrate also searches for unmounted file systems and possible character data sections in unused disk areas. The file systems appropriate for the root volume group are marked for migration. The default file systems are: .CR / , .CR /home , .CR /opt , .CR /tmp , .CR /usr , .CR /var , and any file system with a mount path beginning with: .CR /home/ , .CR /opt/ , .CR /tmp/ , .CR /usr/ , .CR /var/ . .PP .CR lvmmigrate displays the following information on the standard output: disks and file system names that are marked for migration, disk areas and file systems to be backed up by the user, and instructions for reinstallation. .PP After executing .CR lvmmigrate , the user .B must back up the file systems and any raw device section having useful data to tape. The system is then reinstalled on logical volumes using the configuration information recorded by .CR lvmmigrate . .SS Options .CR lvmmigrate recognizes the following options: .RS .TP 25 .CI -d \0disk_special_file Use the specified root disk for reinstallation. Without this option, the current root disk (where root file system .CR / is currently located) is assumed and the configuration is recorded in the boot section. .TP .CI -e \0file_system\0...\& Exclude each specified default file system from the root volume group. Note that the .CR / file system cannot be excluded. .TP .CR -f Force the recording of configuration information. Information is recorded in a LIF file named .CR CUSTOM in the boot section. Without this option, if there is a file system or LVM record in the boot section, no write is done and a warning message is displayed. .TP .CI -i \0file_system\0...\& Include each specified file system in the root volume group, along with the default file systems. .TP .CR -n Perform a "no write" operation for preview purposes. Migration information is displayed on the terminal screen, but is not recorded in the boot section of the disk. The .CR CUSTOM LIF file is not written, but the files .CR /tmp/LVMMIGRATE and .CR /tmp/LVMMIGRATE.CFG are still created. .TP .CR -v Display all disks, file systems, and possible raw sections present in the system. .RE .SH EXAMPLES Prepare a system for migration to root logical volumes. Create a file in the LIF area that the cold-install can use to read default configuration information. Specify verbose mode. Create files .CR /tmp/LVMMIGRATE and .CR /tmp/LVMMIGRATE.CFG : .IP .C "lvmmigrate -v" .PP Display a detailed list of the disks, file systems, and possible raw data sections present in the current system. .IP .C "lvmmigrate -v -n" .PP Include file system .CR /mnt in the root volume group for migration and exclude file system .CR /usr/source . Write configuration information in the boot section of disk .CR /dev/dsk/c1t0d0 : .IP .C "lvmmigrate -d /dev/dsk/c1t0d0 -i /mnt -e /usr/source" .SH WARNINGS Use of the .CR -f option results in overwriting the contents of the boot section. Before using the .CR -f option be sure to back up all data on the boot section of the disk specified with the .CR -d option. .PP If there is no LIF volume, .CR lvmmigrate uses .CR lifinit to create it (see .IR lifinit (1) ). If file .CR CUSTOM already exists in the LIF volume, .CR lvmmigrate rewrites it. .PP .B Caution: All data on disks being used for reinstallation must be backed up to a .B "separate device" because the install process overwrites data on all disks used in the new root volume group. .SH "SEE ALSO" lifinit(1). .\" .\" toc@\f3lvmmigrate(1M)\f1:\0\0\f4lvmmigrate\f1@@@prepare root file system for migration from partitions to LVM logical volumes .\" .\" index@\f4lvmmigrate\f1 \- prepare root file system for migration from partitions to LVM logical volumes@@@\f3lvmmigrate(1M)\f1 .\" index@\f1prepare root file system for migration from partitions to LVM logical volumes@@@\f3lvmmigrate(1M)\f1 .\" index@\f1root file system, prepare for migration from partitions to LVM logical volumes@@@\f3lvmmigrate(1M)\f1 .\" index@\f1migration from partitions to LVM logical volumes, prepare root file system for@@@\f3lvmmigrate(1M)\f1 .\" index@\f1partitions to LVM logical volumes, prepare root file system for migration from@@@\f3lvmmigrate(1M)\f1 .\" index@\f1LVM logical volumes, prepare root file system for migration from partitions to@@@\f3lvmmigrate(1M)\f1 .\" index@\f1logical volumes (LVM), prepare root file system for migration from partitions to@@@\f3lvmmigrate(1M)\f1 .\" $Header: lvreduce.1m,v 78.1 96/03/14 22:28:58 ssa Exp $ .TA l .TH lvreduce 1M .SH NAME lvreduce \- decrease number of physical extents allocated to LVM logical volume .SH SYNOPSIS .CR /sbin/lvreduce .RC [ -A .IR autobackup ] .RC [ -f ] .CR -l .IR le_number .IR lv_path .PP .CR /sbin/lvreduce .RC [ -A .IR autobackup ] .RC [ -f ] .CR -L .IR lv_size .IR lv_path .PP .CR /sbin/lvreduce .RC [ -A .IR autobackup ] .CR -m .IR mirror_copies .IR lv_path .RI [ pv_path \0...] .PP .CR /sbin/lvreduce .RC [ -A .IR autobackup ] .CR -k .CR -m .IR mirror_copies .IR lv_path .RI pv_key \0... .SS Remarks Mirror disk operations require the installation of the optional HP MirrorDisk/UX software, which is not included in the standard HP-UX operating system. .sp .CR lvreduce cannot be performed if the volume group is activated in shared mode. .SH DESCRIPTION The .CR lvreduce command reduces the number of logical extents allocated to a logical volume specified by .IR lv_path . The excess physical extents in the original copy and any mirror copies are deallocated. .PP Alternatively, it reduces the number of mirror copies in the logical volume. The physical extents that comprise the deleted mirror copies are deallocated. If .IR pv_path \ ... is specified, the mirror or mirrors to be removed are sought on those physical volumes. .PP .CR lvreduce asks for confirmation before reducing logical extents if the .CR -f option is omitted. .SS Options and Arguments .PP The .CR -m option and .I pv_path, pv_key arguments are only meaningful if the optional HP MirrorDisk/UX software has been installed on the system. .PP .CR lvreduce recognizes the following options and arguments: .RS .TP 20 .I lv_path The block device path name of a logical volume. .TP .I pv_path The block device path name of a physical volume. .TP .CI -A \0autobackup Set automatic backup for this invocation of this command. .I autobackup can have one of the following values: .RS .RS .TP .CR y Automatically back up configuration changes made to the logical volume. This is the default. .IP After this command executes, the .CR vgcfgbackup command (see .IR vgcfgbackup (1M)) is executed for the volume group to which the logical volume belongs. .TP .CR n Do not back up configuration changes this time. .RE .RE .TP .CR -f Force reduction of the number of logical extents without first requesting confirmation. .IP This option can be dangerous when there is a file system on the .I lv_path that is larger than the size that the logical volume is being reduced to. If the file system is unmounted, the .CR -f option forces the reduction of the logical volume without reducing the file system. The file system becomes corrupt and is not mountable. If the file system is mounted, .CR lvreduce fails, preventing a mounted file system from becoming corrupted. .TP .CI -l \0le_number Decrease the space allocated to the logical volume, specified in logical extents. .I le_number is a decimal value smaller than the current number of logical extents, in the range .CR 1 to .CR 65535 (the implementation limit). .IP One, and only one, .CR -l , .CR -L , or .CR -m option must be supplied. .TP .CI -L \0lv_size Decrease the space allocated to the logical volume, specified in megabytes. .I lv_size is a decimal value smaller than the current logical volume size, in the range .CR 1 to .CR 16777216 (the implementation limit). .I lv_size is rounded up to the nearest multiple of the logical extent size, equivalent to the physical extent size defined for the volume group by the .CR vgcreate command (see .IR vgcreate (1M)). .IP One, and only one, .CR -l , .CR -L , or .CR -m option must be specified. .TP .CI -m \0mirror_copies Reduce the number of mirror copies allocated for each logical extent. A mirror copy contains the same data as the original. .I mirror_copies can have the value .CR 0 or .CR 1 . It must be smaller than the current value. .IP If optional .I pv_path arguments are specified, the mirror copies are deallocated from the specified physical volumes. .IP One, and only one, .CR -l , .CR -L , or .CR -m option must be specified. .TP .CI -k This option should be used only on special cases -- to reduce a mirrored logical volume on a physical volume that is missing or has failed. This option will remove a mirrored logical volume from the given .I pv_key list (the Physical Volume Number in VG). In order to obtain the .I pv_key, use the .CR "-k" option in the .CR lvdisplay command. See .IR lvdisplay (1M) for details. .IP Use this option with the .CR "-m" option. .RE #ifdef B1 .SS Security Restrictions .PP You must have the .CR lvm secondary subsystem authorization to use this command. #endif .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Decrease the number of the logical extents of a logical volume to one hundred: .IP .C "lvreduce -l 100 /dev/vg01/lvol3" .PP Reduce to one mirror (that is, two copies) for each logical extent of a logical volume: .IP .C "lvreduce -m 1 /dev/vg01/lvol5" .PP Remove mirror copies of logical extents of a logical volume from the physical volume .CR /dev/dsk/c1t0d0 : .IP .C "lvreduce -m 0 /dev/vg01/lvol4 /dev/dsk/c1t0d0" .PP Remove a logical volume from a one way mirrored set on the second and third physical volumes in a volume group. .IP .C "lvreduce -m 0 -k /dev/vg01/lvol1 2 3 .SH WARNINGS LVM does not store any information about which physical extents contain useful data; therefore, using the .CR -l option could lead to the loss of useful data. The .CR lvreduce command on a logical volume containing a file system of greater length than the size being reduced to will cause data corruption. .PP To reduce a logical volume being used for swap, that swap area must not be currently in use. .SH SEE ALSO lvcreate(1M), lvdisplay(1M), lvextend(1M), pvchange(1M), pvdisplay(1M). .\" .\" toc@\f3lvreduce(1M)\f1:\0\0\f4lvreduce\f1@@@decrease physical extents allocated to LVM logical volume .\" .\" index@\f4lvreduce\f1 \- decrease physical extents allocated to LVM logical volume@@@\f3lvreduce(1M)\f1 .\" index@decrease physical extents allocated to LVM logical volume@@@\f3lvreduce(1M)\f1 .\" index@physical extents allocated to LVM logical volume, decrease@@@\f3lvreduce(1M)\f1 .\" index@LVM logical volume, decrease physical extents allocated to@@@\f3lvreduce(1M)\f1 .\" index@logical volume (LVM), decrease physical extents allocated to@@@\f3lvreduce(1M)\f1 .\" $Header: lvremove.1m,v 76.1 95/08/01 15:20:37 ssa Exp $ .TA l .TH lvremove 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lvremove \- remove one or more logical volumes from LVM volume group .SH SYNOPSIS .CR /sbin/lvremove .RC [ -A .IR autobackup ] .RC [ -f ] .IR lv_path \ ... .SS Remarks .CR lvremove cannot be performed if the volume group is activated in shared mode. .SH DESCRIPTION The .CR lvremove command removes each logical volume specified by .IR lv_path \ .... .PP Logical volumes must be closed before they can be removed. For example, if the logical volume contains a file system, unmount the file system before removing it. .SS Options and Arguments .CR lvremove recognizes the following options and arguments: .RS .TP 20 .I lv_path The block device path name of a logical volume. .TP .CI -A \0autobackup Set automatic backup for this invocation of this command. .I autobackup can have one of the following values: .RS .RS .TP .CR y Automatically back up configuration changes made to the logical volume. This is the default. .IP After this command executes, the .CR vgcfgbackup command (see .IR vgcfgbackup (1M)) is executed for the volume group to which the logical volume belongs. .TP .CR n Do not back up configuration changes this time. .RE .RE .TP .CR -f Specify that no user confirmation is required. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Remove a logical volume without requiring user confirmation: .IP .C "lvremove \-f /dev/vg01/lvol5" .SH WARNINGS This command destroys all data in the specified logical volumes. .SH SEE ALSO lvchange(1M), umount(1M). .\" .\" toc@\f3lvremove(1M)\f1:\0\0\f4lvremove\f1@@@remove logical volumes from LVM volume group .\" .\" index@\f4lvremove\f1 \- remove logical volumes from LVM volume group@@@\f3lvremove(1M)\f1 .\" index@remove logical volumes from LVM volume group@@@\f3lvremove(1M)\f1 .\" index@logical volumes from LVM volume group, remove@@@\f3lvremove(1M)\f1 .\" index@volumes from LVM volume group, remove logical@@@\f3lvremove(1M)\f1 .\" index@LVM volume group, remove logical volumes from@@@\f3lvremove(1M)\f1 .\" index@volume group (LVM), remove logical volumes from@@@\f3lvremove(1M)\f1 .\" $Header: lvrmboot.1m,v 78.1 96/02/13 13:16:02 ssa Exp $ .TA l .TH lvrmboot 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lvrmboot \- remove LVM logical volume link to root, primary swap, or dump volume .SH SYNOPSIS .CR /sbin/lvrmboot .RC [ -A .IR autobackup ] .RC [ -d .IR dump_lv ] .RC [ -r ] .RC [ -s ] .RC [ -v ] .IR vg_name .SS Remarks .CR lvrmboot cannot be performed if the volume group is activated in shared mode. .SH DESCRIPTION The .CR lvrmboot command updates all physical volumes contained in the volume group .IR vg_name such that the logical volume is removed as a root, primary swap, or dump volume when the system is next booted on the volume group. .SS Options and Arguments .CR lvrmboot recognizes the following options and arguments: .RS .TP 20 .I vg_name The path name of the volume group. .TP .CI -A \0autobackup Set automatic backup for this invocation of this command. .I autobackup can have one of the following values: .RS .RS .TP .CR y Automatically back up configuration changes made to the logical volume. This is the default. .IP After this command executes, the .CR vgcfgbackup command (see .IR vgcfgbackup (1M)) is executed for the volume group to which the logical volume belongs. .TP .CR n Do not back up configuration changes this time. .RE .RE .TP .CI -d \0dump_lv Remove the definition of .I dump_lv as one of the dump volumes. Update the Boot Data Reserved Area. .TP .CR -r Remove the definitions of all of the root, primary swap, and all dump volumes from the given volume group. Update the Boot Data Reserved Area. .TP .CR -s Remove the definition of the primary swap volume from the given volume group. Update the Boot Data Reserved Area. .TP .CR -v Print verbose messages. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Specify that the logical volume .CR /dev/vg00/lvol3 should be removed as one of the dump logical volumes: .IP .C "lvrmboot -v -d lvol3 /dev/vg00" .PP Specify that volume group .CR /dev/vg00 should no longer be a root volume group. Primary swap and dump are also removed. .IP .C "lvrmboot -r /dev/vg00" .SH SEE ALSO lvlnboot(1M). .\" .\" toc@\f3lvrmboot(1M)\f1:\0\0\f4lvrmboot\f1@@@remove LVM logical volume link to root, primary swap, or dump volume .\" .\" index@\f4lvrmboot\f1 \- remove LVM logical volume link to root, primary swap, or dump volume@@@\f3lvrmboot(1M)\f1 .\" index@remove LVM logical volume link to root, primary swap, or dump volume@@@\f3lvrmboot(1M)\f1 .\" index@LVM logical volume link to root, primary swap, or dump volume, remove@@@\f3lvrmboot(1M)\f1 .\" index@link to root, primary swap, or dump volume, remove LVM logical volume@@@\f3lvrmboot(1M)\f1 .\" index@root volume, remove LVM logical volume link@@@\f3lvrmboot(1M)\f1 .\" index@primary swap volume, remove LVM logical volume link@@@\f3lvrmboot(1M)\f1 .\" index@swap volume, remove LVM logical volume link@@@\f3lvrmboot(1M)\f1 .\" index@dump volume, remove LVM logical volume link@@@\f3lvrmboot(1M)\f1 .\" $Header: lvsplit.1m,v 76.1 95/07/31 17:18:12 ssa Exp $ .TA l .TH lvsplit 1M "Requires Optional HP MirrorDisk/UX Software" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lvsplit \- split mirrored LVM logical volume into two logical volumes .SH SYNOPSIS .CR /sbin/lvsplit .RC [ -A .IR autobackup ] .RC [ -s .IR suffix ] .IR lv_path \ ... .SS Remarks This command requires the installation of the optional HP MirrorDisk/UX software (not included in the standard HP-UX operating system) before it can be used. .sp .CR lvsplit cannot be performed if the volume group is activated in shared mode. .SH DESCRIPTION The .CR lvsplit command splits a single- or double-mirrored logical volume .I lv_path into two logical volumes. A new logical volume is created containing one copy of the data. The original logical volume is appropriately reset as unmirrored or single-mirrored. .PP If the .CR -s option is specified, the new logical volume name has the form .IR lv_path\|suffix . If .CR -s is not specified, .I suffix defaults to .CR b , as in .IC lv_path b \f1. .PP If more than one .I lv_path is specified on the command line, .CR lvsplit ensures that all logical volumes are brought offline together in one system call, ensuring predictable results among the logical volumes. Up to 127 logical volumes can be specified on the command line. All logical volumes must belong to the same volume group, and there must be enough unused logical volumes remaining in the volume group to hold the newly split logical volumes. A volume group can contain up to 255 logical volumes. .PP Whenever a mirrored logical volume is split into two logical volumes, a bit map is stored that keeps track of all writes to either logical volume in the split pair. When the two logical volumes are subsequently merged using .CR lvmerge , the bit map is used to decide which areas of the logical volumes need to be resynchronized (see .IR lvmerge (1M)). This bit map remains in existence until the merge is completed, until one of the logical volumes is extended, reduced, or split again, or until the system is rebooted. .PP The new logical volume must be checked with the .CR fsck command before it is mounted (see .IR fsck (1M)). .CR lvsplit flushes the file system to a consistent state except for pipes and unlinked but open files. .PP To rejoin two split copies of a logical volume, use the .CR lvmerge command (see .IR lvmerge (1M)). .SS Options and Arguments .CR lvsplit recognizes the following options and arguments: .RS .TP 20 .IR lv_path The block device path name of a logical volume. Up to 127 logical volumes in the same volume group can be specified at one time. .TP .CI -A \0autobackup Set automatic backup for this invocation of this command. .I autobackup can have one of the following values: .RS .RS .TP .CR y Automatically back up configuration changes made to the logical volume. This is the default. .IP After this command executes, the .CR vgcfgbackup command (see .IR vgcfgbackup (1M)) is executed for the volume group to which the logical volume belongs. .TP .CR n Do not back up configuration changes this time. .RE .RE .TP .CI -s \0suffix Specify the suffix to use to identify the new logical volume. The new logical volume name has the form .IR lv_path\|suffix . If .CR -s is omitted, .I suffix defaults to .CR b , as in .IC lv_path b \f1. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Split the mirrored logical volume .CR /dev/vg00/lvol1 into two copies. Call the new logical volume .CR /dev/vg00/lvol1backup : .IP .C "lvsplit -s backup /dev/vg00/lvol1" .PP Split an online logical volume which is currently mounted on .CR /usr so that a backup can take place: .IP .C "lvsplit /dev/vg00/lvol1" .br .C "fsck /dev/vg00/lvol1b" .br .C "mount /dev/vg00/lvol1b /usr.backup" .IP Perform a backup operation, then: .IP .C "umount /usr.backup" .br .C "lvmerge /dev/vg00/lvol1b /dev/vg00/lvol1" .PP Split two logical volumes at the same time: .IP .C "lvsplit /dev/vg00/database1 /dev/vg00/database2" .IP Perform operation on split logical volumes, then rejoin them: .IP .C "lvmerge /dev/vg00/database1b /dev/vg00/database1" .br .C "lvmerge /dev/vg00/database2b /dev/vg00/database1" .SH WARNINGS After a two way mirrored logical volume has been split once, it cannot be split again without merging the logical volumes using the .CR lvmerge command (see .IR lvmerge (1M)). .SH SEE ALSO lvcreate(1M), lvextend(1M), lvmerge(1M). .\" .\" toc@\f3lvsplit(1M)\f1:\0\0\f4lvsplit\f1@@@split mirrored LVM logical volume into two logical volumes .\" .\" index@\f4lvsplit\f1 \- split mirrored LVM logical volume into two logical volumes@@@\f3lvsplit(1M)\f1 .\" index@split mirrored LVM logical volume into two logical volumes@@@\f3lvsplit(1M)\f1 .\" index@divide mirrored LVM logical volume into two logical volumes@@@\f3lvsplit(1M)\f1 .\" index@separate mirrored LVM logical volume into two logical volumes@@@\f3lvsplit(1M)\f1 .\" index@mirrored LVM logical volume, split into two logical volumes@@@\f3lvsplit(1M)\f1 .\" index@LVM, split mirrored logical volume into two logical volumes@@@\f3lvsplit(1M)\f1 .\" index@logical volumes, split mirrored LVM logical volume into two@@@\f3lvsplit(1M)\f1 .\" $Header: lvsync.1m,v 72.4 94/08/26 16:35:28 ssa Exp $ .TA l .TH lvsync 1M "Requires Optional HP MirrorDisk/UX Software" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lvsync \- synchronize stale mirrors in LVM logical volumes .SH SYNOPSIS .CR /sbin/lvsync .IR lv_path \ ... .SS Remarks This command requires the installation of the optional HP MirrorDisk/UX software (not included in the standard HP-UX operating system) before it can be used. .SH DESCRIPTION The .CR lvsync command synchronizes the physical extents of each logical volume specified by .IR lv_path . Synchronization occurs only on physical extents that are stale mirrors of the original logical extent. The synchronization process can be time consuming, depending on the hardware characteristics and the amount of data. .SS Arguments .CR lvsync recognizes the following argument: .RS .TP 20 lv_path The block device path name of a mirrored logical volume. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES .PP Synchronize the mirrors on a logical volume: .IP .C "lvsync /dev/vg01/lvol5" .SH SEE ALSO lvdisplay(1M), vgsync(1M). .\" .\" toc@\f3lvsync(1M)\f1 :\0\0\f4lvsync\f1@@@synchronize stale mirrors in LVM logical volumes .\" .\" index@\f4lvsync\f1 \- synchronize stale mirrors in LVM logical volumes@@@\f3lvsync(1M)\f1 .\" index@synchronize stale mirrors in LVM logical volumes@@@\f3lvsync(1M)\f1 .\" index@stale mirrors in LVM logical volumes, synchronize@@@\f3lvsync(1M)\f1 .\" index@mirrors in LVM logical volumes, synchronize stale@@@\f3lvsync(1M)\f1 .\" index@LVM logical volumes, synchronize stale mirrors in@@@\f3lvsync(1M)\f1 .\" index@logical volumes (LVM), synchronize stale mirrors in@@@\f3lvsync(1M)\f1 .\" $Header: makedbm.1m,v 72.7 94/11/29 11:27:20 ssa Exp $ .TA m .TH makedbm 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME makedbm \- make a Network Information System database .SH SYNOPSIS .C /usr/sbin/makedbm .RC [ -b ] .RC [ -l ] .RC [ -s ] .RC [ -i .IR nis_input_file ] .ifn .br .ifn \0\0\0\0 .RC [ -o .IR nis_output_name ] .RC [ -d .IR nis_domain_name ] .ifn .br .ifn \0\0\0\0 .RC [ -m .IR nis_master_name ] .I infile outfile .PP .C /usr/sbin/makedbm \-u .I database_name .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .C makedbm generates databases (maps) for the Network Information System (NIS) from .IR infile . A database created by .C makedbm consists of two files: .IC outfile . pag and .IC outfile . dir. A .C makedbm database contains records called .B dbm records composed of key-value pairs. .PP Each line of .I infile is converted to a single dbm record; all characters up to the first tab or space form the key, and the remainder of the line is the value. If a value read from .I infile ends with .CR \e , the value for that record is continued onto the next line. The NIS clients must interpret the .C # character (which means that .C makedbm does not treat the .C # as if it precedes a comment). If .I infile is a hyphen .RC ( - ), .C makedbm reads standard input. .PP .C makedbm always generates a special dbm record with the key .CR YP_LAST_MODIFIED , whose value is the time of last modification of .I infile (or the current time, if .I infile is .CR - ). This value is also known as the order number of a map, and .C yppoll prints it for a specified NIS map (see .IR yppoll (1M)). .PP Another special dbm record created by .C makedbm has the key .CR YP_MASTER_NAME . Its value is usually the host name retrieved by .CR gethostname() ; however, the .C -m option can be used to specify a different value (see .IR gethostname (2)). .PP If the .C -b option is used, another special dbm record with the .CR YP_INTERDOMAIN key is created. When this key exists in the NIS .I host.by* maps and the NIS host name resolution fails, the ypserv process will query the Internet domain name server, .IR named (1M), to provide the host name resolution. Before using the .C -b option, it is recommended that the name services switch, .IR switch (4), be set to allow NIS host name resolution first. (Note that, since the ypserv process only checks .I hosts.byname and .I hosts.byaddr for the existence of the .CR YP_INTERDOMAIN key, using the .C -b option on any other NIS map will have no effect. Also, the .C -b option should be used on both the .I hosts.byname and .I hosts.byaddr maps, not one exclusively.) .PP If the .C -s option is used, another special dbm record created is the .CR YP_SECURE key. If this key exists in an NIS map, ypserv will only allow privileged processes (applications that can create reserved ports) to access the data within the map. .SS Options .C makedbm recognizes the following options and command-line arguments. .TP .C -b Create a special dbm record with the key .CR YP_INTERDOMAIN . This key, which is in the .I hosts.byname and .I hosts.byaddr maps, allows the ypserv process to query the Internet domain name server, (see .IR named (1M)). .TP .C -l Convert the keys of the given map to lowercase. This command option allows host name matches to work independent of character-case distinctions. .TP .C -s Accept connections from secure NIS networks only. .TP .C -i Create a special dbm record with the key .C YP_INPUT_FILE and the value .CR nis_input_file . If the -s option is used, another special dbm record created is the .CR YP_SECURE key. If this key exists in an NIS map, ypserv will only allow privileged processes to access the data within the map. (i.e. applications that can create reserved ports.) .TP .C -o Create a special dbm record with the key .C YP_OUTPUT_NAME and the value .IR nis_output_name . .TP .C -d Create a special dbm record with the key .C YP_DOMAIN_NAME and the value .IR nis_domain_name . .TP .C -m Replace the value of the special dbm record whose key is .C YP_MASTER_NAME with .IR nis_master_name . .TP .C -u Undo the .I database_name (i.e., write the contents of .I database_name to the standard output), one dbm record per line. A single space separates each key from its value. .RE .SH EXAMPLES Shell scripts can be written to convert ASCII files such as .C /etc/netgroup to the key-value form used by .CR makedbm . For example, .IP .nf .C #!/usr/bin/sh .ift .ft 4 .ifn .ft 3 .ps +1 /usr/bin/awk 'BEGIN { FS = ":" } { print $1, $0 }' \\ /etc/netgroup | \\ makedbm - netgroup .ft .ps .fi .PP converts the file .C /etc/netgroup to a form that is read by .C makedbm to make the NIS map .CR netgroup . The keys in the database are .IR netgroup (4) names, and the values are the remainders of the lines in the .C /etc/netgroup file. .SH AUTHOR .C makedbm was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), ypinit(1M), ypmake(1M), yppoll(1M), gethostname(2), netgroup(4), ypfiles(4). .\" .\" index@\f4makedbm\f1 \- make a Network Information System database@@@\f3makedbm(1M)\f1 .\" index@\f1make a Network Information System database@@@\f3makedbm(1M)\f1 .\" index@\f1Network Information System database, make a@@@\f3makedbm(1M)\f1 .\" index@\f1database, make a Network Information System@@@\f3makedbm(1M)\f1 .\" .\" toc@\f3makedbm(1M)\f1:\0\0\f4makedbm\f1@@@make a Network Information System database .\" Copyright (c) 1988, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)makemap.1m 8.3 (Berkeley) 7/24/94 .\" .TH makemap 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: August 1997 .SH NAME .B makemap \- create database maps for sendmail .SH SYNOPSIS .B makemap .RC [ -N ] .RC [ -n ] .RC [ -d ] .RC [ -f ] .RC [ -o ] .RC [ -r ] .RC [ -v ] .I maptype .I mapname .SH DESCRIPTION .B makemap creates the database maps used by the keyed map lookups in sendmail(1M). It reads input from the standard input and outputs them to the indicated .I mapname. .PP Depending on how it is compiled, .B makemap handles up to three different database formats, selected using the .I maptype parameter. They may be .TP 8 .C dbm DBM format maps. This requires the ndbm(3X) library. .TP .C btree B-Tree format maps. This requires the new Berkeley db library. .TP .C hash Hash format maps. This also requires the db library. .PP In all cases, .B makemap reads lines from the standard input consisting of two words separated by white space. The first is the database key, the second is the value. The value may contain ``%n'' strings to indicated parameter substitution. Literal parentheses should be doubled (``%%''). Blank lines and lines beginning with ``#'' are ignored. .SS Flags .TP 8 .C -N Include the null byte that terminates strings in the map. This must match the \-N flag in the sendmail.cf ``K'' line. .TP .C -n Create NIS compatible alias database. .TP .C -d Allow duplicate keys in the map. This is only allowed on B-Tree format maps. If two identical keys are read, they will both be inserted into the map. .TP .C -f Normally all upper case letters in the key are folded to lower case. This flag disables that behaviour. This is intended to mesh with the \-f flag in the .B K line in sendmail.cf. The value is never case folded. .TP .C -o Append to an old file. This allows you to augment an existing file. .TP .C -r Allow replacement of existing keys. Normally .B makemap complains if you repeat a key, and does not do the insert. .TP .C -v Verbosely print what it is doing. .SH SEE ALSO sendmail(1M). .SH HISTORY The .B makemap command appeared in 4.4BSD. .\" $Header: map-mbone.1m,v 74.2 95/06/09 10:01:58 ssa Exp $ .TA m .TH map-mbone 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME map-mbone - Multicast Router Connection Mapper .SH SYNOPSIS .C /usr/sbin/map-mbone .RC [ \-d .IR debuglevel ] .RC [ -f ] .RC [ -g ] .RC [ -n ] .RC [ \-r .IR retries ] .RC [ \-t .IR timeout ] [ .I multicast-router ] .SH DESCRIPTION .CR map-mbone requests the multicast router connection information from the .I multicast-router, and prints the information to the standard out. .CR map-mbone sends out the .I ASK_NEIGHBORS igmp message to the multicast-router. When the multicast-router receives the request, it sends back its configuration information. .I multicast-router can be either an ip address or a system name. .PP If the .I multicast-router is not specified, .I flood mode is on by default and the igmp request message is sent to all the multicast router on the local network. With .I flood mode on, when .CR map-mbone finds new neighbor routers from the replies, it will send the same igmp request to the new neighbor routers. This activity continues until no new neighbor routers are reported in the replies. .PP The command line options are: .TP 14 .CI -d debuglevel Sets the level for printing out the debug message. The default is 0, which prints only error and warning messages. Debug level three prints most the messages. .TP .CI -r retries Sets the retry times to poll the routing daemon for information. The default is 1. .TP .CI -t timeout It specifies the timeout value in seconds for waiting the reply. The default value is 2 seconds. .TP .C -f Sets the .I flood mode on. It is the default value when no .I multicast-router is given on the command line input. .TP .C -g Generates output in GRaphEd format. .TP .C -n Disable DNS lookup for the multicast router names. .PP The output contains the interface configuration information of the requested router(s). The format for each interface output is: .PP .nf .C interface_addr -> neighbor_addr (neighbor_name) [metrics/thresh/flags] .fi .PP If there are multiple neighbor routers on one interface, they will all be reported. The .I neighbor_name will not be printed if the .C -n option is specified on the command line. .PP The possible values for .C flags are: .TP 14 .C tunnel Neighbors are reached via tunnel. .TP .C srcrt The tunnel uses IP source routing. .TP .C down The interface is down. .TP .C disabled The interface is administratively disabled for multicast routing. .TP .C querier The local router is the querier of the subnet. .PP The format of the GRaphEd output is: .PP .nf .C interface_addr_in_integer {$ NP low_byte_addr high_byte_addr} "node_name" .in 8 .C [ neighbor_addr_in_integer "metrics/threshold/flags" ] .in -8 .fi .PP If there is no neighbor router on an interface, then a .C "*" will be put next to the node_name. If there are multiple neighbor routers on one interface, all of them will be reported. The possible values for .C "flags" are: .TP 10 .C E The neighbor is reached via tunnel. .TP 10 .C P The neighbor is on the same network/subnet. .TP 10 .C D The interface is down. .PP Please see .IR mrouted (1M) for .C metrics and .C thresh .SH EXAMPLES .RS Querying camden.cup.hp.com for the multicast router connection information. .nf .PP map-mbone hpntclt.cup.hp.com .PP 127.0.0.1 (localhost) [version 3.3]: 15.13.106.144 -> 15.13.106.145 (hpntcbs.cup.hp.com) [10/1/querier] 193.2.1.39 -> 0.0.0.0 (all-zeros-broadcast) [1/1/disabled] 15.13.106.144 -> 15.255.176.33 (matmos.hpl.hp.com) [10/1/tunnel] 15.13.106.144 -> 15.17.20.7 (hpspddc.vid.hp.com) [10/1/tunnel/down] .PP .fi Querying hpntcbs.cup.hp.com for multicast router connectivity with .I -g option: .nf .PP map-mbone -g hpntcbs.cup.hp.com GRAPH "Multicast Router Connectivity: Wed Feb 1 17:34:59 1995"=UNDIRECTED 252537488 {$ NP 1440 1060 $} "hpntc1t.cup.hp.com*" ; 252538974 {$ NP 940 1120 $} "hpntcbs.cup.hp.com" 252537488 "10/1E" 252539807 "1/1P" ; 252539807 {$ NP 1590 1150 $} "hpntc1h.cup.hp.com*" ; .fi .RE .PP .SH NOTE .CR map-mbone must be run as root .PP .SH AUTHOR .PP .CR map-mbone was developed by Pavel Curtis. .PD .SH SEE ALSO .PP mrouted (1M), mrinfo(1M). .\" .\" index@\f4map-mbone\f1 \- multicast router connection mapper@@@\f3map-mbone(1M)\f1 .\" index@\f1multicast router connection mapper@@@\f3map-mbone(1M)\f1 .\" index@\f1router connection mapper, multicast@@@\f3map-mbone(1M)\f1 .\" index@\f1connection mapper, multicast router@@@\f3map-mbone(1M)\f1 .\" index@\f1mapper, multicast router connection@@@\f3map-mbone(1M)\f1 .\" .\" toc@\f3map-mbone(1M)\f1:\0\0\f4map-mbone\f1,@@@multicast router connection mapper .\" .\" fileset_database@map-mbone.1m INET-ENG-A-MAN .\" $Header: 97/04/07 15:06:57 PDT ajasper $ .\" April 1997: patch to add mc command and manpage on 10.01 .TA m .TH mc 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: April 1997 .SH NAME mc - media changer manipulation utility .SH SYNOPSIS .CR "mc" .RC [ -p .IR device ] .RC [ -a .IR num ] .RC [ -q ] .RC [ -c .IR ] .PP .CR "mc" .RC [ -p .IR device ] .RC [ -l .CR 0 | .CR 1 ] .RC [ -e .IR element_type ] .RC [ -r .IR element_type ] .PP .CR "mc" .RC [ -p .IR device ] .CI -s\0 .CI -d\0 .PP .CR "mc" .RC [ -h .RC | "-?" ] .SH DESCRIPTION The .CR mc utility provides users with a command-line interface to send media manipulation commands to an autoloader or media changer device. It takes "element types" as arguments to most of the options. The valid element types .RI ( element_types ) are: .RS .TP 5 .CR D Specifies a Data Transfer (DT) element. .TP .CR I Specifies an Import/Export (IE) element. .TP .CR M Specifies a Medium Transport (MT) element. .TP .CR S Specifies a Storage (ST) element. .RE .PP An example of a Data Transfer element is the embedded tape drive of the autoloader. An example of an Import/Export element is the slot(s) by which an item of the media maybe inserted or removed from the autoloader. An example of a Medium Transport element is the robotic picker portion of the autoloader. An example of a Storage element is the magazine slot of the autoloader. .PP Please see examples below for usage. .SS Options .CR mc recognizes the following options and arguments: .PP .TP 15 .CI -a \0num Prints the SCSI bus address of the drive slot specified by .IR num . .TP .CI -c\0 Determines whether a move from source to destination is valid. Uses device capabilities mode page and will return TRUE or FALSE. There should be no spaces in the the source and destination element type values. .\" add extra \0 for spacing for nroff output For example, .CR "-c DS" specifies a Data Transfer element as the source and a Storage element as the destination. .TP .CI -e\0 element_type Prints out the number of elements of element type. See element types above. Multiple types can be specified. For example, .CR "-e IDSM" specifies all the valid element types. .TP .CR -h | -? Prints out usage description. .TP .CR "-l\0 0"| "1" Allow .RC ( 0 ) or prevent .RC ( 1 ) media removal. .TP .CI -p\0 device Specifies the pass-through device file to the library device. .TP .CR -q Prints out Vendor ID, Product ID and Product Rev standard inquiry information. .TP .CI -r\0 element_type Prints out the status (FULL/EMPTY/NONE) of element slots of element type(s). See element types above. Multiple types can be specified. For example, .CR "-r IDSM" specifies all the valid element types. .TP .CI -s\0 "" Specifies the element type and slot number .RI ( ) for the move medium source. There should be no space between the element type and the slot number. For example, .CR -sS1 specifies a Storage element in slot number 1. This option cannot be specified more than twice per invocation. .TP .CI -d\0 "" Specifies the element type and slot number for the move medium destination. There should be no space between the element type and the slot number. .\" add extra \0 for spacing for nroff output For example,\0\0 .CR "-dD3" specifies a Data Transfer element in slot number 3. This option cannot be specified more than twice per invocation. .SH RETURN VALUE .PP .CR mc returns 0 upon successful completion and -1 otherwise. .SH DIAGNOSTICS .PP .C "ERROR: 0x5 Illegal Request: 0x3b0d Medium Destination element full" .IP The above error message could be a result of the following command .C "mc -s S2 -d D1" that was used to move a media to an embedded drive that is already full. .PP .C "ERROR: /dev/scsi/3: No such file or directory" .IP If the default SCSI pass-through device file does not exist and no other device file is specified, then the above error message will be printed. .SH EXAMPLES .PP Using a DDS-2 autoloader with a six cartridges magazine as an example: .PP To see the status of the autoloader's Data Transfer and Storage element types. .IP .C "mc -r DS" .PP The following shows an example output from the above command. The output indicates that there is an item of media in slot 2 (ST_slot_2), an item of media in the embedded drive (DT_slot_1), and all the other slots are empty. .IP .C "DT_slot_1 FULL" .IP .C "ST_slot_1 EMPTY" .IP .C "ST_slot_2 FULL" .IP .C "ST_slot_3 EMPTY" .IP .C "ST_slot_4 EMPTY" .IP .C "ST_slot_5 EMPTY" .IP .C "ST_slot_6 EMPTY" .PP To move media from an embedded drive to slot 5 and then move media from slot 2 to an embedded drive. .IP .C "mc -s D1 -d S5 -s S2 -d D1" .PP To check if a move from a Data Transfer element to a Storage element is possible. .IP .C "mc -c DS" .PP The following example output indicates that moves from Data Transfer element types to Storage element types are valid. .IP .C "DT->ST: TRUE" .SH WARNINGS Note for all DDS autoloaders. After the .CR mc command has been used for the first time, the autoloader will enter into random mode. Once in random mode, all front panel button features are disabled except for the Eject Button. To go back to stacker mode, the magazine must be ejected and then reinserted. .SH DEPENDENCIES The .CR mc command supports the following autoloaders and libraries: .RS .TP 15 .CR C1553A HP DDS-2 Autoloader .TP .CR C1557A HP DDS-3 Autoloader .TP .CR C1194 HP DLT Library .TP .CR "STK 9710" StorageTek DLT/4890 Library .TP .CR "ATL 4/52" ATL DLT Library .RE .PP A SCSI pass-through driver must be configured and the device file created before this command can be used to manipulate the autoloader. .SS Series 700 The .BR ctl pass-through driver must be configured. See .IR scsi_ctl (7). .SS Series 800 The .BR spt pass-through driver must be configured. See .IR scsi_pt (7). .SH AUTHOR .CR mc was developed by Hewlett-Packard. .SH FILES .TP 20 .PD 0 .CR /dev/scsi/3 Default pass-through device file. .PD .SH SEE ALSO .PP scsi(7), scsi_ctl(7), scsi_pt(7). .\" $Header: mk_fnt_clnt.1m,v 10.1 95/10/24 20:51:50 hmgr Exp $ .ds RL Release 10.0 .ds ]W HP-UX Release 10.0 .TH mk_fnt_clnt 1M .SH NAME mk_fnt_clnt - configure a font client .SH SYNOPSIS .C mk_fnt_clnt .RC [ -k\| ] .I host .SH DESCRIPTION The command .C mk_fnt_clnt configures a system as a font client so the HP VUE product accesses X11 fonts from a network font server. Once a system is a font client, .C mk_fnt_clnt can be run again to switch from one font server to another. .PP The system specified by the .I host argument should already be configured as a font server, and must be accessible when .C mk_fnt_clnt is executed. .I host can be a hostname or an Internet address. .PP First time configuration of a font client results in the removal of some filesets containing X11 fonts. Only filesets that contain an SD control file with the name .C font_client_rm are removed. No filesets are removed on subsequent calls to switch font servers. .PP When appropriate, a font client can also be configured as part of first time system setup or by running the interactive command .C /sbin/set_parms with the argument .I font_c-s. .SS Options .C mk_fnt_clnt supports the following option and parameter: .RS .TP 15 .C -k Keep the font filesets. By default, .C mk_fnt_clnt uses .C swremove (see .IR swremove (1M)) to remove any font filesets that have a control file named .C font_client_rm. This option is only useful if access to a network font server is desired but removal of local fonts is not desired. Keeping local fonts means the font client has no RAM or disk space savings. .IP Note that font filesets are only removed during first time configuration. No fileset removals occur during subsequent calls to .C mk_fnt_clnt even if the .C -k option is not specified. .TP .I host The font server host specified by the .I host parameter can be a hostname or an Internet address. The host acting as the font server should always be configured before configuring any font clients. .PP To change a system so that it ceases being a font client, reload the font filesets and remove or comment out the line from .C /etc/vue/config/vuerc that begins with ``FONT_PATH_TAIL=''. After that, exit any active VUE sessions and restart them. .SH NETWORKING FEATURES This command should only be used on systems that are connected to a network. Networking must be configured and enabled before using this command. .SH EXTERNAL INFLUENCES If the DISPLAY environment variable is set and refers to the same host as the one on which .C mk_fnt_clnt executes, which is the normal case, the current font path of the X server for that display is updated. When changing font servers, the new font server is added to the path ahead of any other remote font servers. If present, the previous font server is removed from the font path. .PP If the host has multiple displays, only the X server referred to by the DISPLAY environment variable will be updated immediately. Other X server processes will get the new path when a new VUE session is started for that display. .PP If the DISPLAY environment variable is set and refers to a host different from the one on which .C mk_fnt_clnt executes, no changes are made to the font path of the X server referred to by the DISPLAY environment variable. .SH RETURN VALUE Exit values are: .PP .RS .TP 5 .C " 0" Successful configuration of the host as a font client. .PD 0 .TP .C " 1" One or more errors occurred. .PD .RE .SH DIAGNOSTICS Error messages are self-explanatory. .SH WARNINGS Being a network font client makes your VUE interface somewhat dependent on the network and the font server host. If your font server system becomes unreachable, your font client system has a very restricted set of fonts. .PP X11 applications that are currently executing usually continue to function, but encounter problems if they request a new font while the font server is unavailable. At that point they may exhibit errors, display a very small fixed size font, or hang. .PP Most new X11 applications you try to start after a server becomes unreachable probably hang until the server comes back. .PP Because of these conditions, you might want to use font clients only on systems that are connected by reliable networks to reliable font server systems. .PP The following are circumstances in which you should not configure a host as a font client: .TP 2 \(bu Diskless cluster servers should never be configured as font clients. Before configuring an existing font client to be a diskless cluster server, you should restore the X11 font filesets and cease being a font client, as described earlier. .TP \(bu In general, any server system providing X11 or VUE resources to other clients, such as a system serving X terminals or an MPower server, should not be a font client. A system already acting as a font server can not become a font client without first ceasing to be a font server. .TP \(bu If your system uses something other than VUE 3.0 for its X11 interface or does not have a local X11 interface, you should not make the system a font client. .SH AUTHOR .C mk_fnt_clnt was developed by HP. .SH FILES .TP 25 /etc/vue/config/vuerc configuration file for holding the font path. .PD 0 .TP /usr/lbin/font_c-s.utils functions used by the .C mk_fnt_clnt script .PD .SH SEE ALSO fs(1), mk_fnt_srvr(1M), swremove(1M). .PP .IR "HP Visual User Environment 3.0 User's Guide" .\" $Header: mk_fnt_srvr.1m,v 10.1 95/10/24 20:51:19 hmgr Exp $ .ds RL Release 10.0 .ds ]W HP-UX Release 10.0 .TH mk_fnt_srvr 1M .SH NAME mk_fnt_srvr - configure a host as a font server .SH SYNOPSIS .C mk_fnt_srvr .SH DESCRIPTION The command .C mk_fnt_srvr configures a host to run the X11 R5 font server daemon. .PP If the host on which .C mk_fnt_srvr is invoked is not already configured as a font client or a font server, the script modifies a control variable in a configuration file so a font server process is started after each reboot. If the configuration file is successfully modified, .C mk_fnt_srvr starts a font server daemon. .PP When appropriate, this configuration step can also be performed as part of first time system setup or by running the interactive command .C /sbin/set_parms with the argument .I font_c-s. .PP To change a system so that it is no longer acting as a font server, switch all existing font clients to another server. Then, disable this font server by setting the ``RUN_X_FONT_SERVER'' variable in the file .C /etc/rc.config.d/xfs equal to ``0''. .PP Finally, as superuser, run the command .C /sbin/init.d/xfs with the argument .I stop. .SH NETWORKING FEATURES This command should only be used on systems that are connected to a network. Networking must be configured and enabled before using this command. .SH RETURN VALUE Exit values are: .PP .RS .TP 5 .C " 0" Successful configuration of the host as a font server. .PD 0 .TP .C " 1" One or more errors occurred. .PD .RE .SH DIAGNOSTICS Error messages are self-explanatory. .SH AUTHOR .C mk_fnt_srvr was developed by HP. .SH FILES .TP 25 /etc/rc.config.d/xfs configuration file for controling the start up of the font server .PD 0 .TP /usr/lbin/font_c-s.utils functions used by the .C mk_fnt_srvr script .PD .SH SEE ALSO fs(1), mk_fnt_clnt(1M). .PP .IR "HP Visual User Environment 3.0 User's Guide" .\" $Header: mk_kernel.1m,v 74.1 95/03/23 17:31:42 ssa Exp $ .\" The '@' hoses eroff, so use a display and don't .\" put the display inside of a font macro, e.g. .CR, .RI, etc. Instead split .\" the word containing the @ using the \c (continuation) and \0 (space) .\" appropriately. .TA m .TH mk_kernel 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .SH NAME mk_kernel \- build a boot-able HP-UX kernel. .PP .SH SYNOPSIS .C /usr/sbin/mk_kernel .RC [ -v ] .RC [ -o .IR file ] .RC [ -s .IR file ] .PP .SH DESCRIPTION .C mk_kernel builds an executable file which can be used as a boot-able kernel. If the build succeeds, the newly built binary will be a file named .IR vmunix_test located in the build directory, as defined below. .PP The build directory is a directory where .C mk_kernel places files created by its processes. Other files that are created by the invocation of .C mk_kernel, such as .IR conf.c and .IR conf.o are left in the build directory. The build directory is .IR /stand/build if the system file used is .IR /stand/system, either by default or by designation. If another path is used to designate the system file, the build directory will be the present working directory. Libraries for the kernel are expected to be found in .IR /usr/conf/lib. The master file used is the composite of files found under .IR /usr/conf/master.d. .C mk_kernel exits with no action if the environment variable SW_INITIAL_INSTALL has the value of 1. SW_INITIAL_INSTALL is exported by SD with that value only when the system is undergoing its initial software system installation. .SS Options .C mk_kernel recognizes the following options. .RS .TP 15 .C -v Verbose mode. More verbose messages are sent to stdout if errors are encountered. .TP .CI -o \0file Specify the target file path. The resultant kernel file will be moved from .IR vmunix_test in the build directory to the path specified by the option argument. If the path is .IR /stand/vmunix, and if a file already exists at that location, it will be moved to .IR /stand/vmunix.prev. An error encountered in moving the file will result in the newly built kernel being left in the build directory. .TP .CI -s \0file Specify the kernel template file. If this option is not specified, the system file .IR /stand/system, is used. .RE .PP .SH RETURN VALUES .PP .C mk_kernel returns 0 upon normal completion, and 1 if an error occurred. .PP .SH EXAMPLES .IP .C "mk_kernel -o /stand/vmunix" .PP Uses the file .IR /stand/system to build a new kernel which will be placed in .IR /stand/vmunix upon success. .PP .IP .C "mk_kernel -s /mnt/altsys/stand/system.new" .PP Uses the file .IR /mnt/altsys/stand/system.new to build a new kernel which will remain in file .IR vmunix_test in the present working directory. .PP .IP .C "mk_kernel -s /stand/system -o /tmp/new_kernel" .PP Uses the file .IR /stand/system to build a new kernel which will be placed in .IR /tmp/new_kernel upon success. .PP .SH DIAGNOSTICS .PP Messages and warnings are sent to stdout. Diagnostic messages from .C mk_kernel are self explanatory. Messages from .C config and other commands are not suppressed. Errors cause .C mk_kernel to halt immediately; warnings allow the program to continue. .PP .SH SEE ALSO .PP config(1M) .\" index@\f4mk_kernel(1M)\f1 \- build a bootable HP-UX kernel@@@\f3mk_kernel(1M)\f1 .\" index@\f1build a bootable HP-UX kernel@@@\f3mk_kernel(1M)\f1 .\" index@\f1bootable HP-UX kernel, build@@@\f3mk_kernel(1M)\f1 .\" index@\f1HP-UX kernel, build a bootable@@@\f3mk_kernel(1M)\f1 .\" index@\f1kernel, build a bootable HP-UX@@@\f3mk_kernel(1M)\f1 .\" toc@\f3mk_kernel(1M)\f1:\0\0\f4mk_kernel\f1@@@build a bootable HP-UX kernel .\" $Header: mkboot.1m,v 74.1 95/05/10 21:53:34 ssa Exp $ .TA m .TH mkboot 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mkboot, rmboot \- install, update or remove boot programs from disk .SH SYNOPSIS .C /usr/sbin/mkboot .RC \0[ -b .IR boot_file_path ] .RC \0\0[ -c .RC [ -u ] .RC | \0-f .RC | \0-h .RC | \0-u ] .ifn .br .RC \0\0[ -i .IR included_lif_file ] .ift .br .RC \0[ -p .IR preserved_lif_file ] .RC \0\0[ -l \0| .CR -H \0| .CR -W ] .RC [ -v ] .ifn .br .I \0\0device .PP .C /usr/sbin/mkboot .RC [ -a .IR auto_file_string\| ] .RC [ -v\| ] .I device .PP .C /usr/sbin/rmboot .I device .SH DESCRIPTION .CR mkboot is used to install or update boot programs on the specified device file. .PP The position on .I device at which boot programs are installed depends on the disk layout of the device. .CR mkboot examines .I device to discover the current layout and uses this as the default. If the disk is uninitialized, the default is LVM layout. The default can be overriden by the .CR -l, .CR -H or .CR -W options. .PP Boot programs are stored in the boot area in Logical Interchange Format (LIF), which is similar to a file system. For a device to be bootable, the LIF volume on that device must contain at least the .CR ISL (the initial system loader) and .CR HPUX (the HP-UX bootstrap utility) LIF files. If, in addition, the device is an LVM physical volume, the .CR LABEL file must be present (see .IR lvlnboot (1M) ). .SH Options .CR mkboot recognizes the following options: .RS .TP 24 .CI -a \0auto_file_string If the .CR -a option is specified, mkboot creates an autoexecute file .CR AUTO on .I device, if none exists. .CR mkboot deposits .I auto_file_string in that file. If this string contains spaces, it must be quoted so that it is a single parameter. .TP .CI -b \0boot_file_path If this option is given, boot programs in the pathname specified by .I boot_file_path are installed on the given device. .TP .C -c If this option is specified, .CR mkboot checks if the available space on .I device is sufficient for the boot programs. If the .CR -i option is also specified, .CR mkboot checks if each .I included_lif_file is present in the boot programs. If the .CR -p option is specified, it checks if each .I preserved_lif_file is present on the .I device. If all these checks succeed, .CR mkboot exits with a status code of 0. If any of these checks fail, .CR mkboot exits with a status code of 1. If the verbose option is also selected, a message is also displayed on the standard output. .TP .C -f This option forces the information contained in the boot programs to be placed on the specified .I device without regard to the current swapping status. Its intended use is to allow the boot area to grow without having to boot the system twice (see .CR -h option). .IP This option should only be used when the system is in the single user state. .IP This could be a dangerous operation because swap space that is already allocated and possibly in use will be overwritten by the new boot program information. A message is also displayed to the standard output stating that the operator should immediately reboot the system to avoid system corruption and to reflect new information on the running system. .IP A safer method for reapportioning space is to use the .CR -h option. .IP This option is valid only if .I device has the Whole Disk layout. .TP .C -h Specifying this option shrinks the available space allocated to swap in the LIF header by the amount required to allow the installation of the new boot programs specified by .I boot_file_path. .IP After the LIF header has been modified, reboot the system to reflect the new swap space on the running system. At this point, the new boot programs can be installed and the system rebooted again to reflect the new boot programs on the running system. This is the safe method for accomplishing the capability of the .CR -f option. .IP This option is valid only if .I device has the Whole Disk layout. .TP .C -H If this option is specified, .CR mkboot treats .I device to be a Hard Partition layout disk. This option cannot be used along with the .CR -l and .CR -W options. .TP .CI -i \0included_lif_file If the .CR -i option is specified one or more times, .CR mkboot copies each .I included_lif_file and ignores any other LIF files in the boot programs. The sole exceptions to this rule are the files .CR ISL and .CR HPUX , which are copied without regard to the .CR -i options. If .I included_lif_file is also specified with the .CR -p option, the .CR -i option is ignored. If the .CR -i option is used with .CR LABEL as its argument and the file .CR LABEL does not exist in the boot programs, and .I device is an LVM layout disk or the .CR -l option is used, .CR mkboot creates a minimal .CR LABEL file on .I device which will permit the system to boot on .I device, possibly without swap or dump. .TP .C -l If this option is used, .CR mkboot treats .I device as an LVM layout disk, regardless of whether or not it is currently set up as one. This option cannot be used along with the .CR -H and .CR -W options. .TP .CI -p \0preserved_lif_file If the .CR -p option is specified one or more times, .CR mkboot keeps each specified .I preserved_lif_file intact on .I device. If .IR preserved_lif_file also appears as an argument to the .CR -i option, that .CR -i option is ignored. This option is typically used with the autoexecute file .CR AUTO and with the LVM and SwitchOver/UX file .CR LABEL. .IP If .CR LABEL is specified as an argument to the .CR -p option and .CR LABEL does not exist on the .I device, and if the layout is LVM, .CR mkboot creates a minimal .CR LABEL file. In general, if .I preserved_lif_file is not on the .I device, .CR mkboot fails. An exception to this condition is if the .I preserved_lif_file is .CR LABEL and the layout is not LVM, in which case the .CR LABEL file is ignored. .TP .C -u If .CR -u is specified, .CR mkboot uses the information contained in the LIF header to identify the location of the swap area, boot area, and raw I/O so that installation of the boot programs does not violate any user data. .IP Normally, the LIF header information is overwritten on each invocation of mkboot. This option is typically used with the .CR -W option, to modify boot programs on a disk that is actively supporting swap and/or raw I/O. .TP .C -v If this option is specified, .CR mkboot displays its actions, including the amount of swap space available on the specified device. .TP .C -W If this option is specified, .CR mkboot treats .I device as a disk having the Whole Disk layout. This option cannot be used along with the .CR -l and .CR -H options. .TP .I device Install the boot programs on the given device special file. The specified .I device can identify either a character-special or block-special device. However, .CR mkboot requires that both the block and character device special files be present. .CR mkboot attempts to determine whether .I device is character or block special by examining the specified path name. For this reason, the complete path name must be supplied. If .CR mkboot is unable to determine the corresponding device file, a message is written to the display, and .CR mkboot exits. .RE .PP .CR rmboot removes the boot programs from the boot area. .SH EXAMPLES Install default boot programs on the specified disk, treating it as an LVM disk: .PP .C " mkboot -l /dev/dsk/c0t5d0" .PP Use the existing layout, and install only SYSLIB and ODE files and preserve the EST file on the disk: .PP .C " mkboot -i SYSLIB -i ODE -p EST /dev/rdsk/c0t5d0" .PP Install only the SYSLIB file and retain the ODE file on the disk. Use the Whole Disk layout. Use the file .CR /tmp/bootlf to get the boot programs rather than the default. (The .CR -i .CR ODE option will be ignored): .PP .C " mkboot -b /tmp/bootlf -i SYSLIB -i ODE -p ODE -W /dev/rdsk/c0t5d0" .SH WARNINGS If .I device has a Whole Disk layout, a file system must reside on the device being modified. .PP When executing from a recovery system, the .CR mkboot command (if used) must be invoked with the .CR -f option; otherwise it will not be able to replace the boot area on your disk. .PP If .I device is, or is intended to become an LVM physical volume, .I device must specify the whole disk. .PP If .I device is, or is intended to become a Hard Partitioned disk, .I device must specify section 6. .SH DEPENDENCIES .CR mkboot and .CR rmboot fail if file system type on .I device is not HFS. .SS "LVM and Hard Partition Layouts" The .CR -f , .CR -h and .CR -u options are not supported. .SH AUTHOR .CR mkboot and .CR rmboot were developed by HP. .SH FILES .TP 30 .C /usr/lib/uxbootlf file containing default boot programs .PD 0 .TP .C ISL initial system loader .PD 0 .TP .C HPUX HP-UX bootstrap and installation utility .PD 0 .TP .C AUTO defines default/automatic boot behavior (see .IR hpux(1M)) .PD 0 .TP .C LABEL used by SwitchOver/UX and LVM .PD 0 .TP .C RDB diagnostics tool .PD 0 .TP .C IOMAP diagnostics tool .PD .SH SEE ALSO boot(1M), hpux(1M), isl(1M), lif(4), lvlnboot(1M), mkfs(1M), newfs(1M). .\" .\" index@\f4mkboot\f1 \- install, or update boot programs from a disk device@@@\f3mkboot(1M)\f1 .\" index@\f4rmboot\f1 \- remove boot programs from a disk device@@@\f3mkboot(1M)\f1 .\" index@\f1install, update, or remove boot programs from a disk device@@@\f3mkboot(1M)\f1 .\" index@\f1update, install, or remove boot programs from a disk device@@@\f3mkboot(1M)\f1 .\" index@\f1remove boot programs from a disk device, install, update, or@@@\f3mkboot(1M)\f1 .\" index@\f1boot programs; install, update, or remove from a disk device@@@\f3mkboot(1M)\f1 .\" index@\f1programs from a disk device; update, install, or remove boot@@@\f3mkboot(1M)\f1 .\" index@\f1disk device; update, install, or remove boot programs from a@@@\f3mkboot(1M)\f1 .\" index@\f1device; update, install, or remove boot programs from a disk@@@\f3mkboot(1M)\f1 .\" .\" toc@\f3mkboot(1M)\f1:\0\0\f4mkboot\f1, \f4rmboot\f1@@@install, update, or remove boot programs from a disk device .\" toc@\f4rmboot\f1 \- install, update, or remove boot programs from a disk device@@@see \f3mkboot(1M)\f1 .\" .\" links@mkboot.1m rmboot.1m .\" .\" fileset_database@mkboot.1m SYS-ADMIN-MAN .\" $Header: mkfs.1m,v 78.1 96/02/26 13:45:27 ssa Exp $ .TA m .TH mkfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mkfs (generic) \- construct a file system .SH SYNOPSIS .CR /usr/sbin/mkfs .RC [ \-F .IR FStype ] .RC [ \-o .IR specific_options ] .RC [ \-V ] .I special .ifn .br .ifn \0\0\0\0 .RI [ operands ] .PP .CR /usr/sbin/mkfs .RC [ \-F .IR FStype ] .RC [ \-m ] .RC [ \-V ] .I special .SH DESCRIPTION The .CR mkfs command creates a file system by writing on the special file .IR special . .SS Options .CR mkfs recognizes the following options: .RS .TP 15 .CI \-F \0FStype Specify the file system type on which to operate (see .IR fstyp (1M) and .IR fs_wrapper (5)). If this option is not included on the command line, then the file system type is determined from the file .CR /etc/fstab by matching .I special with an entry in that file. If there is no entry in .CR /etc/fstab , then the file system type is determined from the file .CR /etc/default/fs . .TP .CR \-m Display the command line that was used to create the file system. The file system must already exist. This option provides a means of determining the parameters used to construct the file system. .TP .CI \-o \0specific_options Specify options specific to the file system type. .I specific_options is a list of suboptions and/or keyword/attribute pairs intended for an .IR FStype -specific module of the command. See the file system specific manual entries for a description of the .I specific_options that are supported, if any. .TP .CR \-V Echo the completed command line, but perform no other action. The command line is generated by incorporating the specified options and arguments with other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .SH EXAMPLES Execute the .CR mkfs command to create an HFS file system on .CR /dev/dsk/c1d2s0 : .IP .C "mkfs \-F hfs /dev/dsk/c1d2s0 1024" .PP Execute the .CR mkfs command on an HFS file system, .CR /dev/dsk/c1d2s0 , to recreate the command that was used to create the file system on .CR /dev/dsk/c1d2s0 : .IP .C "mkfs \-F hfs \-m /dev/dsk/c1d2s0" .SH AUTHOR .CR mkfs was developed by HP and the University of California, Berkeley. .SH FILES .TP 23 .PD 0 .CR /etc/default/fs Specifies the default file system type. .TP 23 .CR /etc/fstab Static information about the file systems. .PD .SH SEE ALSO chmod(1), bdf(1M), df(1M), fsck(1M), fstyp(1M), mkfs_hfs(1M), mkfs_vxfs(1M), newfs(1M), fstab(4), group(4), passwd(4), fs_wrapper(5). .SH STANDARDS COMPLIANCE .CR mkfs ": SVID3" .\" index@\f4mkfs\f1 \- construct a file system (generic)@@@\f3mkfs(1M)\f1 .\" index@\f1construct a file system (generic)@@@\f3mkfs(1M)\f1 .\" index@\f1make a file system (generic)@@@\f3mkfs(1M)\f1 .\" index@\f1file system (generic), construct@@@\f3mkfs(1M)\f1 .\" index@\f1generic file system, construct@@@\f3mkfs(1M)\f1 .\" .\" toc@\f3mkfs(1M)\f1:\0\0\f4mkfs\f1@@@construct a file system (generic) .\" $Header: mkfs_hfs.1m,v 78.1 96/02/13 13:16:32 ssa Exp $ .TA m .TH mkfs_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mkfs (hfs) \- construct an HFS file system .SH SYNOPSIS .CR /usr/sbin/mkfs .RC [ \-F .CR hfs ] .RC [ \-d ] .RC [ \-L \(or \-S ] .RC [ \-V ] .RC [ \-o .IR specific_options ] .I special .br \0\0\0\0 .RI [ size .RI [ "nsect ntrack blksize fragsize ncpg minfree rps nbpi" ]\|] .PP .CR /usr/sbin/mkfs .RC [ \-d ] .RC [ \-F .CR hfs ] .RC [ \-L \(or \-S ] .RC [ \-V ] .RC [ \-o .IR specific_options ] .IR special .br \0\0\0\0 .RI [ proto .RI [ "nsect ntrack blksize fragsize ncpg minfree rps nbpi" ]\|] .PP .CR /usr/sbin/mkfs .RC [ \-F .CR hfs ] .RC [ \-m ] .RC [ \-V ] .IR special .SS Remarks HFS file systems are normally created with the .CR newfs command (see .IR newfs_hfs (1M)). .SH DESCRIPTION The .CR mkfs command constructs an HFS file system by writing on the special file .IR special . The .CR mkfs command builds the file system with a root directory and a .CR lost+found directory (see .IR fsck_hfs (1M)). The .CR FS_CLEAN magic number for the file system is stored in the superblock. .PP The .CR mkfs command creates the file system with a rotational delay value of zero (see .IR tunefs (1M)). .PP .SS Options .CR mkfs recognizes the following options: .RS .TP 15 .CR \-F\0hfs Specify the HFS file system type. .TP .CR \-d This option allows the .CR mkfs command to make the new file system in an ordinary file. In this case, .IR special is the name of an existing file in which to create the file system. When this option is used, the size of the new file system cannot be defaulted. It must either be specified on the command line following .IR special , or if a prototype file is being used, it must be the second token in the prototype file as usual. .TP .CR \-L \(or \-S There are two types of HFS file systems, distinguished mainly by directory formats that place different limits on the length of file names. .IP If .CR \-L is specified, build a long-file-name file system that allows directory entries (file names) to be up to .CR MAXNAMLEN (255) bytes long. .IP If .CR \-S is specified, build a short-file-name file system that allows directory entries (file names) to be up to .CR DIRSIZ (14) bytes long. .IP If neither .CR \-L nor .CR \-S is specified, build a file system of the same type as the root file system. .TP .CR \-m Display the command line that was used to create the file system. The file system must already exist. This option provides a means to determine the parameters used to construct the file system. .TP .CR \-V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .TP .CR \-o \0specific_options Specify a list of comma separated suboptions and/or keyword/attribute pairs from the list below. .RS .TP .CI largefiles|nolargefiles Controls the .I largefile featurebit for the file system. The default is nolargefiles. This means the bit is not set, and files created on the file system will be limited to less than 2 gigabytes in size. If .C largefiles is specified, the bit is set and the maximum size for files created on the file system is not limited to 2 gigabytes. .RE .SS Arguments .CR mkfs recognizes the following arguments: .RS .TP 15 .I special The file name of a special file. .RE .PP One of the following arguments can be included after .IR special : .RS .TP 15 .I size The number of .CR DEV_BSIZE blocks in the file system. .CR DEV_BSIZE is defined in .CR . The default value is the size of the entire disk or disk section minus any swap or boot space requested. .IP The size of HFS file systems are limited by .CR UFS_MAXDEVBLK (defined in .CR ) to 256GB-1 or 268,435,455 blocks. .TP .I proto The name of a file that can be opened. The .CR mkfs command assumes it is a prototype file and takes its directions from that file. See "Prototype File Structure" below. .RE .PP The following optional arguments allow fine-tune control over file system parameters: .RS .TP 15 .I nsect The number of sectors per track on the disk. The default value is 32 sectors per track. .TP .I ntrack The number of tracks per cylinder on the disk. The default value is 16 tracks per cylinder. .TP .I blksize The primary block size for files on the file system. Valid values are: 4096, 8192, 16384, 32768, and 65536. The default value is 8192 bytes. .TP .I fragsize The fragment size for files on the file system. .I fragsize represents the smallest amount of disk space to be allocated to a file. It must be a power of two no smaller than .CR DEV_BSIZE and no smaller than one-eighth of the file system block size. The default value is 1024 bytes. .TP .I ncpg The number of disk cylinders per cylinder group. This number must be in the range 1 to 32. The default value is 16 cylinders per group. .TP .I minfree The minimum percentage of free disk space allowed. The default value is 10 percent. .IP Once the file system capacity reaches this threshold, only users with appropriate privileges can allocate disk blocks. .TP .I rps The number of disk revolutions per second. The default value is 60 revolutions per second. .TP .I nbpi The density of inodes in the file system specified as the number of bytes per inode. The default value is 6144 bytes per inode. .IP This number should reflect the expected average size of files in the file system. If fewer inodes are desired, a larger number should be used; if more inodes are desired, a smaller number should be used. .IP .B Note: The number of inodes that will be created in each cylinder group of a file system is approximately the size of the cylinder group divided by the number of bytes per inode, up to a limit of 2048 inodes per cylinder group. If the size of the cylinder group is large enough to reach this limit, the default number of bytes per inode will be increased. .RE .SS Prototype File Structure A prototype file describes the initial file structure of a new file system. The file contains tokens separated by spaces or newline characters. It cannot contain comments. .PP The first token is the name of a file to be copied onto block zero as the bootstrap program (usually .CR /etc/BOOT ). If the file name is \f3\f4\s+1""\f1\s-1, \" EDITOR: \f4 and \s.. are ignored by nroff it is ignored. The second token is a number specifying the number of .CR DEV_BSIZE blocks in the file system. .PP The next three tokens specify the mode, user ID, and group ID of the root directory of the new file system, followed by the initial contents of the root directory in the format described for a directory file below, and terminated with a .CR $ token. .PP A file specification consists of four tokens giving the name, mode, user ID, and group ID, and an initial contents field. The syntax of the initial contents field depends on the mode. .PP A name token is a file name that is valid for the file system. The root directory does not have a name token. .PP A mode token is a 6-character string. The first character specifies the type of the file. It can be one of the following characters: .RS .TP .PD 0 .CR \- Regular file .TP .CR b Block special file .TP .CR c Character special file .TP .CR d Directory .TP .CR l Symbolic link .TP .CR L Hard link .PD .RE .PP The second character of a mode token is either .CR u or .CR \- to specify set-user-ID mode or not. The third character of a mode token is either .CR g or .CR \- to specify the set-group-ID mode or not. The rest of a mode token is a three-digit octal number giving the .IR owner , .IR group , and .I other read, write, and execute permissions (see .IR chmod (1)). .PP The user-ID and group-ID tokens define the owner of the file. These values can be specified numerically or with symbolic names that appear in the current password and group databases. .PP .B "Regular file." The initial contents field is the path name of an existing file in the current file system whose contents and size are copied to the new file. .PP .B "Block or character special file." The initial contents field is two numeric tokens that specify the major and minor device numbers. .PP .B "Directory file." The initial contents field is a list of file specifications for the entries in the directory. The list is terminated with a .CR $ token. Directories can be nested. For each directory, the .CR mkfs command automatically makes the .CR \.\& and .CR \.\\.\& entries. .PP .B "Symbolic link." The initial contents field is a path name that is used as the path to which the symbolic link should point. .PP .B "Hard link." The initial contents field is a path name that is used as the name of a file within the new file system to which the entry should be linked. The mode, user-ID and group-ID tokens of this entry are ignored; they are taken from the target of the link. The target of the link must be listed before the entry specifying the link. Hard links to directories are not permitted. .PP With the exception of the permissions field of the mode token (which is always an octal number), all numeric fields can be specified in hexadecimal (using a leading .CR 0x ), octal (using a leading .CR 0 ), or decimal. .PP Here is a sample prototype specification. The indentation clarifies the directory recursion. .nf .IP .C "/etc/BOOT" .C "12288" .C "d--555 bin bin" .C "sbin d--755 bin bin" .C " init ---555 bin bin /sbin/init" .C " savecore ---555 bin bin /sbin/savecore" .C " $" .C "dev d--555 bin bin" .C " b0 b--640 root sys 0 0x0e0000" .C " c0 c--640 root sys 4 0x0e0000" .C " $" .C "etc d--755 bin bin" .C " init l--777 bin bin /sbin/init" .C " passwd ---444 bin bin /etc/passwd" .C " group ---444 bin bin /etc/group" .C " $" .C "usr d--755 bin bin" .C " bin d--755 bin bin" .C " sh ---555 bin bin /usr/bin/sh" .C " rsh L--555 bin bin /usr/bin/sh" .C " su -u-555 root bin /usr/bin/su" .C " mailq l--777 bin bin /usr/sbin/sendmail" .C " $" .C " sbin d--755 bin bin" .C " sendmail -ug555 root mail /usr/sbin/sendmail" .C " $" .C " $" .C "$" .fi .SS Access Control Lists Every file with one or more optional ACL entries consumes an extra (continuation) inode. If you anticipate significant use of ACLs on a new file system, you can allocate more inodes by reducing the value of .I nbpi appropriately. The small default value typically causes allocation of many more inodes than are actually necessary, even with ACLs. To evaluate your need for extra inodes, run the .CR "bdf\ \-i" command on existing file systems. For more information on access control lists, see .IR acl (5). .SH EXAMPLES Execute the .CR mkfs command to create a 32MB HFS file system on .CR /dev/dsk/c1d2s0 : .IP .C "mkfs \-F hfs /dev/dsk/c1d2s0 32768" .PP Execute the .CR mkfs command to display the command that was used to construct the file system on .CR /dev/dsk/c1d2s0 : .IP .C "mkfs \-F hfs \-m /dev/dsk/c1d2s0" .SH WARNINGS The old .CR \-F option, from prior releases of .IR mkfs (1M), is no longer supported. .PP .IR mkfs_hfs (1M) cannot be executed on a device that belonged to a logical volume group, unless the device is initialized by .IR mediainit (1). .PP The .C \-o largefile option should be used with care, since older applications will not react correctly when confronted with large files. .SH AUTHOR .CR mkfs was developed by HP and the University of California, Berkeley. .SH FILES .TP 25 .CR /var/adm/sbtab List of locations of the superblocks for the created file system. The .CR mkfs command appends entries to this file. .SH SEE ALSO chmod(1), bdf(1M), df(1M), fsck(1M), fsck_hfs(1M), fsclean(1M), mkfs(1M), newfs(1M), newfs_hfs(1M), dir(4), fs(4), fstab(4), group(4), passwd(4), symlink(4), acl(5).\"STD .SH STANDARDS CONFORMANCE .CR mkfs ": SVID3" .\" .\" index@\f4mkfs\f1 \- construct an HFS file system@@@\f3mkfs_hfs(1M)\f1 .\" index@\f1construct an HFS file system@@@\f3mkfs_hfs(1M)\f1 .\" index@\f1make an HFS file system@@@\f3mkfs_hfs(1M)\f1 .\" index@\f1file system (HFS), construct@@@\f3mkfs_hfs(1M)\f1 .\" index@\f1HFS file system, construct@@@\f3mkfs_hfs(1M)\f1 .\" .\" toc@\f3mkfs_hfs(1M)\f1:\0\0\f4mkfs\f1@@@construct an HFS file system .\" $Header: mkfs_vxfs.1m,v 78.1 96/02/13 13:17:08 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA m .TH mkfs_vxfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mkfs (vxfs) \- construct a VxFS file system .SH SYNOPSIS .HP .C /usr/sbin/mkfs .RC [ \-F .CR vxfs ] .RC [ \-V ] .C \-m .I special .HP .C /usr/sbin/mkfs .RC [ \-F .CR vxfs ] .RC [ \-V ] .br .RC [ \-o .RC [ N ] .RC [ X ] .RC [ ninode=\c .IR n ] .RC [ nau=\c .IR n ] .RC [ bsize=\c .IR n ] .RC [ logsize=\c .IR n ] .RC [ ausize=\c .IR n ] .RC [ aufirst=\c .IR n ] .RC [ aupad=\c .IR n ] .RC [ version=\c .IR n ] .RC [ inosize=\c .IR n ] .RC [ largefiles | nolargefiles ] .RC ] .I special size .SH DESCRIPTION The .C mkfs command creates a VxFS file system by writing on the .I special device file. .I special must be the first argument after the options are given. The file system is created based on the .I options and .I size specified on the command line. The .I size specifies the number of sectors in the file system. By default, size is specified in units of DEV_BSIZE sectors. However, the letter .CR k , .CR m , or .CR g can be appended to the number to indicate that the value is in kilobytes, megabytes, or gigabytes, respectively. The .C mkfs command builds a file system with a root directory and a .C lost+found directory. .SS Options .C mkfs recognizes the following options: .RS .TP 15 .CI \-F\0vxfs Specify the VxFS file system type. .TP 15 .C \-m Display the command line which was used to create the file system. The file system must already exist. This option provides a means of determining the command used in constructing the file system. .TP 15 .CI \-o " specific_options" Specify options specific to the VxFS file system type. .I specific_options is a comma separated list of suboptions and/or keyword/attribute pairs intended for the VxFS-specific module of the command. .IP The following .I specific_options are valid on a VxFS file system: .RS .TP .C N Do not write the file system to the .I special file. This option gives all the information needed to create a file system but does not create it. .TP .C X Create a file system in a file. This is used for debugging purposes only. .TP .CI version= n .I n is the VxFS disk layout version number. .I n can be 2 or 3 to indicate the Version 2 or Version 3 disk layout. Version 2 supports dynamic inode allocation. Version 3 adds support for large files and large .IR UID s. The default is the Version 3. .TP .CI inosize= n .I n is the on-disk inode structure size for files on the file system. The only allowed value is 256 bytes. .TP .CI bsize= n .I n is the block size for files on the file system and represents the smallest amount of disk space that will be allocated to a file. .I n must be a power of 2 selected from the range 1024 to 8192. The default is 1024. .TP .CI ninode= n .I n is the maximum number of inodes in the file system. The actual maximum number of inodes is .I n rounded up to an appropriate boundary. For a Version 2 or 3 disk layout this is the maximum number of inodes, The number 0 and the string .RC `` unlimited '' are interpreted to mean that the number of inodes is unlimited. The default is .ig the total number of blocks in allocation units divided by 4 for a Version 1 disk layout, and .. ``unlimited'' for a Version 2 or 3 disk layout. .TP .CI nau= n .I n is the number of allocation units on the file system. If .I nau is specified, then .I ausize is determined by evenly dividing the sectors among the allocation units. By default, the number of allocation units will be set based on the value of .I ausize. This option is ignored for a Version 3 disk layout. .TP .CI ausize= n .I n is the size, in blocks of size .I bsize, of an allocation unit. This is an alternate way of specifying the number of allocation units. This option may not be used in conjunction with the .I nau option. With this option, the last allocation unit on the file system may be shorter than the others. If the last allocation unit on the file system is not long enough to contain an entire allocation unit header, the resulting size of the file system will be to the end of the last complete allocation unit. This parameter may not exceed 262144 blocks. .IP The algorithm used to choose the default value is rather complicated, but is intended to balance the number of allocation units (4 to 16 is a good range), the size of the allocation units (at least 32768 blocks), and other factors. For a Version 3 disk layout the allocation unit size is fixed at 32768 blocks, and this option is ignored. .TP .CI aufirst= n .I n is the starting block number, in blocks of size .I bsize, of the first allocation unit. This option allows the allocation units to be aligned to a particular boundary, such as a cylinder boundary. For a Version 3 file system, .C aufirst is always 0, and this option is ignored. .TP .CI aupad= n .I n is the size, in blocks of size .I bsize, to leave between the end of the inode list and the first data block in each allocation unit. This option allows the data blocks of an allocation unit to be aligned to a particular boundary, such as a cylinder boundary. For a Version 3 file system, .C aupad is always 0, and this option is ignored. .TP .CI logsize= n .I n is the number of blocks to allocate for an activity logging area. .I n must be in the range 32 blocks to 16384 Kbytes. Although .I logsize is specified in blocks, the maximum value is 16384 Kbytes. This means that for a .I bsize of 1024, 2048, 4096, or 8192 bytes the maximum value of .I logsize is 16384, 8192, 4096, or 2048 blocks, respectively. To avoid wasting space, the default .I logsize is 1024 blocks for a file system 8 megabytes or larger, 128 blocks for a file system 2 megabytes or larger but less than 8 megabytes, and 32 blocks for a file system less than 2 megabytes. .TP .CI largefiles|nolargefiles Controls the .I largefile compatibility bit for the file system. By default the bit is not set, and files created on the file system will be limited to less than 2 gigabytes in size. If .C largefiles is specified, the bit is set and the maximum file size for files created on the file system is not limited to 2 gigabytes (see .IR mount_vxfs (1M) and .IR fsadm_vxfs (1M)). This option is only valid for a Version 3 disk layout. The default is .IR nolargefiles , although the default may change in the future. .RE .TP 15 .C \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR "/etc/fstab" . This option allows the user to verify the command line. .SH EXAMPLES Execute the .C mkfs command to create a VxFS file system on .CR /dev/rdsk/c0t6d0 : .IP .C mkfs \-F vxfs /dev/rdsk/c0t6d0 1024 .PP Execute the .C mkfs command on a VxFS file system, .CR /dev/rdsk/c0t6d0 , to determine the command that was used to create the file system on .CR /dev/rdsk/c0t6d0 : .IP .C mkfs \-F vxfs \-m /dev/rdsk/c0t6d0 .SH WARNINGS .if \n(hP \{\ .IR mkfs_vxfs (1M) cannot be executed on a device that belonged to a logical volume group, unless the device is initialized by .IR mediainit (1). \} .PP The .C \-o largefiles option should be used with care, since older applications will not react correctly when confronted with large files. .SH RETURN VALUE Upon successful completion, the .C mkfs command returns a value of 0. The return value is 1 if a syntax error occurs. Other errors return a value of 32. .SH FILES .TP 20 .CR /etc/fstab Default list of file systems to check. .SH SEE ALSO chmod(1), df(1M), bdf(1M), fsadm_vxfs(1M), fsck(1M), mount_vxfs(1M), newfs(1M), chown(2), group(4), passwd(4), mkfs(1M). .SH STANDARDS CONFORMANCE .C mkfs : SVID3 .\" .\" toc@\f3mkfs_vxfs(1M)\f1:\0\0\f(CWmkfs\f1@@@construct VxFS file system .\" .\" index@\f(CWmkfs_vxfs\f1 \- construct VxFS file system@@@\f3mkfs_vxfs(1M)\f1 .\" index@\f(CWmkfs\f1 \- construct VxFS file system@@@\f3mkfs_vxfs(1M)\f1 .\" index@\f1construct VxFS file system@@@\f3mkfs_vxfs(1M)\f1 .\" index@\f1VxFS file system, construct@@@\f3mkfs_vxfs(1M)\f1 .\" index@\f1file system, construct VxFS@@@\f3mkfs_vxfs(1M)\f1 .\" $Header: mklost+foun.1m,v 72.4 94/11/28 08:40:24 ssa Exp $ .TA m .TH mklost+found 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mklost+found \- make a lost+found directory for \f2fsck\f1(1M) .SH SYNOPSIS .C /usr/sbin/mklost+found .SH DESCRIPTION The .C mklost+found command creates a directory named .C lost+found in the current directory. It also creates several empty files which are then removed to provide empty slots for the .C fsck command (see .IR fsck (1M)). .PP For an .SM HFS file system, the .C mklost+found command is not normally needed since the .C mkfs command automatically creates the .C lost+found directory when a new file system is created (see .IR mkfs (1M)). .SH AUTHOR .C mklost+found was developed by the University of California, Berkeley. .SH SEE ALSO fsck(1M), mkfs(1M). .\" .\" index@\f4mklost+found\f1 \- make a \f4lost+found\f1 directory for \f4fsck\f1(1M)@@@\f3mklost+found(1M)\f1 .\" index@make a \f4lost+found\f1 directory for \f4fsck\f1(1M)@@@\f3mklost+found(1M)\f1 .\" index@\f4lost+found\f1 directory for \f4fsck\f1(1M), make a@@@\f3mklost+found(1M)\f1 .\" index@\f4fsck\f1(1M), make a \f4lost+found\f1 directory for@@@\f3mklost+found(1M)\f1 .\" .\" toc@\f3mklost+found(1M)\f1:\0\0\f4mklost+found\f1@@@make a lost+found directory for \f4fsck\f1(1M) .\" .\" fileset_database@mklost+foun.1m SYS-ADMIN-MAN .\" $Header: mknod.1m,v 78.1 96/04/05 11:32:04 ssa Exp $ .TA m .TH mknod 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mknod \- create special files .SH SYNOPSIS .CR /sbin/mknod .I name .CR c .I major .I minor .PP .CR /sbin/mknod .I name .CR b .I major .I minor .PP .CR /sbin/mknod .I name .CR p .SH DESCRIPTION The .CR mknod command creates the following types of files: .RS .TP 3 .PD 0 \(bu Character device special file (first SYNOPSIS form), .TP \(bu Block device special file (second SYNOPSIS form), .TP \(bu FIFO file, sometimes called a named pipe (third SYNOPSIS form). .RE .PD .PP .I name is the path name of the file to be created. The newly created file has a default mode that is readable and writable by all users (0666), but the mode is modified by the current setting of the user's file mode creation mask (see .IR umask (1)). .SS Character and Block Special Files Character device special files are used for devices that can transfer single bytes at a time, such as nine-track magnetic tape drives, printers, plotters, disk drives operating in "raw" mode, and terminals. To create a character special file, use the .CR c argument. .PP Block device special files are used for devices that usually transfer a block of data at a time, such as disk drives. To create a block device special file, use the .CR b argument. .PP The remaining arguments specify the device that will be accessible through the new special file: .RS .TP 15 .I major The major number specifies the major device type (for example, the device driver number). .TP .I minor The minor number specifies the device location, which is typically, but not always, the unit, drive, HP-IB bus address and/or line number. .RE .PP The .I major and .I minor values can each be specified in hexadecimal, octal, or decimal, using C language conventions (decimal: no leading zero; octal: leading zero; hexadecimal: leading .CR 0x ). .PP The assignment of major and minor device numbers is specific to each HP-UX system. Refer to the System Administrator manuals supplied with your system for details. .PP Only users who have appropriate privileges can use .CR mknod to create a character or block device special file. .SS FIFO files To create a FIFO (named pipe or buffer) file, use the .CR p argument. You can also use the .CR mkfifo command for this purpose (see .IR mkfifo (1)). All users can use .CR mknod to create FIFO files. .SH WARNINGS .SS Access Control Lists Optional ACL entries can be added to special files and FIFOs with the .CR chacl command (see .IR chacl (1)). However, system programs are likely to silently change or eliminate the optional ACL entries for these files. .SH SEE ALSO chacl(1),\"STD mkdir(1), mkfifo(1), umask(1), lsdev(1M), sam(1M),\"STD mknod(2), acl(5),\"STD mknod(5). .PP HP-UX System Administrator manuals. .SH STANDARDS CONFORMANCE .IR mknod ": SVID2, SVID3, XPG2" .\" .\" index@\f4mknod\f1 \- create special and FIFO files@@@\f3mknod(1M)\f1 .\" index@\f1file, create special and FIFO@@@\f3mknod(1M)\f1 .\" index@\f1create special and FIFO files@@@\f3mknod(1M)\f1 .\" index@\f1special and FIFO files, create@@@\f3mknod(1M)\f1 .\" index@\f1device and FIFO files, create@@@\f3mknod(1M)\f1 .\" index@\f1FIFO files, create@@@\f3mknod(1M)\f1 .\" index@\f1pipes, create named@@@\f3mknod(1M)\f1 .\" index@\f1named pipes, create@@@\f3mknod(1M)\f1 .\" .\" toc@\f3mknod(1M)\f1:\0\0\f4mknod\f1@@@create special and FIFO files .\" $Header: mkpdf.1m,v 78.1 96/01/09 13:55:14 ssa Exp $ .TA m .TH mkpdf 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mkpdf \- create a Product Description File from a prototype PDF .SH SYNOPSIS .HP .C mkpdf .RC [ \-c .IR comment_string ] .RC [ \-n ] .RC [ \-r .IR alternate_root ] .I prototype_PDF .I new_PDF .SH DESCRIPTION The .CR mkpdf program reads a prototype PDF and generates a new PDF (see .IR pdf (4)) that reflects the current status of the file system files defined by path names in the prototype file. .PP If .I pathname is a directory, the .IR size , .IR version , .IR checksum , and .I linked_to target fields are forced to be empty. If the file is a device, the .IR version , .IR checksum , and .I linked_to fields are forced to be empty and the .I size field contains the major and minor device numbers. .PP If a path name in .I prototype_PDF is prefaced with a question mark .RC ( ? ), the file is assumed to be an optional file. This file is processed in the same manner as all other files except that, if the file does not exist, values provided in the prototype are reproduced, and the .CR ? , is passed through to .IR new_PDF . If a path name is not preceded with .CR ? , and the file does not exist on the file system, an error is reported and no entry is added to .IR new_PDF . .PP If a dash .RC ( \- ) is used for .I prototype_PDF or .IR new_PDF , .CR mkpdf assumes that standard input and/or standard output, respectively, is being used for the appropriate value. .PP Comments in .I prototype_PDF are supported as follows: Lines beginning with the percent character .RC ( % ) are generally passed through, in order, to .IR new_PDF , except that any "\c .CR "% Product Description File\c" " and "\c .CR "% total size is ...\c" " lines are removed to prevent duplication of these automatically generated lines in .IR new_PDF when .I prototype_PDF is a PDF. Lines beginning with a pound character .RC ( # ), and lines containing only the newline character .RC ( \en ) are not passed through to .IR new_PDF . Note that blank space preceding these special characters is not allowed and will generally result in error messages about files not found. .PP A size summary is produced as a comment at the end of the PDF. .SS Options .TP 20 .CI \-c " comment_string" Insert a string that contains a comment about the product for which this PDF is being generated. This is used as a second comment line of the PDF. See .IR pdf (4) for a description of the first comment line. If this option is not specified, no second comment line is produced. .TP .C \-n Record numerical representation of user ID from .CR /etc/passwd and group ID from .CR /etc/group for each file instead of the usual text representation. .TP .CI \-r " alternate_root" Prefix the string .I alternate_root to each path name in the prototype (after removing the optional .CR ? ) to form a modified path name to be used to gather attributes for the entry. Default is an empty string. .SH EXAMPLES Given a file .CR Proto with contents: .nf .IP .C /usr/bin/basename .C /usr/bin/cat .C /usr/bin/ccat .C /usr/bin/dirname .C /usr/bin/grep .C /usr/bin/ls .C /usr/bin/ll::::::::/usr/bin/ls .C /usr/bin/su .fi .PP the command: .IP .C "mkpdf \-c ""fileset TEST, Release 1.0"" Proto \-" .PP produces the PDF shown in the EXAMPLE section of .IR pdf (4). .PP The following example creates a totally new PDF for the fileset .CR ALBA_CORE . The .I pathname and .I linked_to are taken from the prototype PDF. All other fields are generated from the file system. .IP .C "mkpdf /tmp/ALBA_CORE /system/ALBA_CORE/new.pdf" .PP The next example shows how to create a completely new PDF from just a list of files. The PDF for the files under the .CR /PRODUCT directory is created by executing the .CR find command (see .IR find (1)) on all the files in the directory structure under .CR /PRODUCT . A .CR / is edited onto the beginning of each path name to make it absolute. The path names are then piped to .CR mkpdf . The .CR \-r option specifies that a root of .CR /PRODUCT should be prefixed to each path name while the directory is being searched. A .CR \- in the .I prototype_PDF position specifies that .CR stdin is being used for the prototype PDF file. The resulting PDF does not contain the .CR /PRODUCT prefix. Note that, with only a list of path names, the .I linked_to field of linked files will not conform to the convention explained in .IR pdf (4). .nf .IP .C "cd /PRODUCT .C "find * \-print | sed \-e 's:^:/:' | .C "mkpdf \-r /PRODUCT \- PDF .fi .SH RETURN VALUE Upon completion, .CR mkpdf returns one of the following values: .RS .TP .C 0 Successful completion. .TP .C 1 Nonoptional files in the prototype file were not found. .TP .C 2 .CR mkpdf encountered other problems. .RE .SH DIAGNOSTICS .PP .IC filename ": no such file or directory" .IP A nonoptional file was not found on the file system and will not appear in the new PDF. .SH WARNINGS Sizes reported do not reflect blocks allocated to directories. .PP Use of PDFs is discouraged since this functionality is obsolete and is being replaced with Software Distributor (see .IR sd (4)). .SH AUTHOR .CR mkpdf was developed by HP. .SH SEE ALSO pdfck(1M), pdfdiff(1M), pdf(4). .\" .\" index@\f4mkpdf\f1 \- create Product Description File from an input@@@\f3mkpdf(1M)\f1 .\" index@\f1create Product Description File from an input@@@\f3mkpdf(1M)\f1 .\" index@\f1Product Description File, create from an input@@@\f3mkpdf(1M)\f1 .\" index@\f1PDF, create from an input@@@\f3mkpdf(1M)\f1 .\" .\" toc@\f3mkpdf(1M)\f1:\0\0\f4mkpdf\f1@@@create Product Description File from an input .\" $Header: mksf.1m,v 76.2 95/10/06 10:35:01 ssa Exp $ .\" AUTHOR'S NOTE: In the tables, the construct "\f3\f4" provides .\" computer font for troff and bold font for nroff/man -allanp .\" Patch PHCO_13699 supports pci_mux0; related to software Patch PHCO_13336. .\" Patch PHCO_13859 supports DLT4000 devices. Stape must be updated. .TA m .TH mksf 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: January 1998 .SH NAME mksf \- make a special (device) file .SH SYNOPSIS .CR /sbin/mksf .RC [ \-C .IR class .RI \(or .CR \-d .IR driver ] .RC [ \-D .IR directory ] .RC [ \-H .IR hw\-path ] .ifn .br .ifn \0\0\0\0 .RC [ \-I .IR instance ] .RC [ \-q \(or \-v ] .ift .br .ift \0\0\0\0 .RI [ driver\-options ] .RI [ special\-file ] .PP .CR /sbin/mksf .RC [ \-C .IR class .RI \(or .CR \-d .IR driver ] .RC [ \-D .IR directory ] .RC [ \-H .IR hw\-path ] .ifn .br .ifn \0\0\0\0 .CR \-m .I minor .RC [ \-q \(or \-v ] .RC [ \-r ] .ift .br .ift \0\0\0\0 .I special\-file .SH DESCRIPTION The .CR mksf command makes a special file in the devices directory, normally .CR /dev , for an existing device, a device that has already been assigned an instance number by the system. The device is specified by supplying some combination of the .CR \-C , .CR \-d , .CR \-H , and .CR \-I options. If the options specified match a unique device in the system, .CR mksf creates a special file for that device; otherwise, .CR mksf prints an error message and exits. If required, .CR mksf creates any subdirectories relative to the device installation directory that are defined for the resulting special file. .PP For most drivers, .CR mksf has a set of built-in driver options, .IR driver\-options , and special-file naming conventions. By supplying some subset of the driver options, as in the first form above, the user can create a special file with a particular set of characteristics. If a .I special\-file name is specified, .CR mksf creates the special file with that special file name; otherwise, the default naming convention for the driver is used. .PP In the second form, the .I minor number and .I special\-file name are explicitly specified. This form is used to make a special file for a driver without using the built-in driver options in .CR mksf . The .CR \-r option specifies that .CR mksf should make a character (raw) device file instead of the default block device file for drivers that support both. .PP .SS Options .CR mksf recognizes the following options: .RS .TP 15 .CI \-C \0class Match a device that belongs to a given device class, .IR class . Device classes can be listed with the .CR lsdev command (see .IR lsdev (1M)). They are defined in the files in the directory .CR /usr/conf/master.d . This option is not valid for pseudo devices. This option cannot be used with .CR \-d . .TP .CI \-d \0driver Match a device that is controlled by the specified device driver, .IR driver . Device drivers can be listed with the .CR lsdev command (see .IR lsdev (1M)). They are defined in the files in the directory .CR /usr/conf/master.d . This option cannot be used with .CR \-C . .TP .CI \-D \0directory Override the default device installation directory .CR /dev and install the special files in .I directory instead. .I directory must exist; otherwise, .CR mksf displays an error message and exits. See WARNINGS. .TP .CI \-H \0hw\-path Match a device at a given hardware path, .IR hw\-path . Hardware paths can be listed with the .CR ioscan command (see .IR ioscan (1M)). A hardware path specifies the addresses of the hardware components leading to a device. It consists of a string of numbers separated by periods .RC ( . ), such as .CR 52 (a card), .CR 52.3 (a target address), and .CR 52.3.0 (a device). If a hardware component is a bus converter, the following period, if any, is replaced by a slash .RC ( / ) as in .CR 2 , .CR 2/3 , and .CR 2/3.0 . This option is not valid for pseudo devices. .TP .CI \-I \0instance Match a device with the specified .I instance number. Instances can be listed with the .CR \-f option of the .CR ioscan command (see .IR ioscan (1M)). This option is not valid for pseudo devices. .TP .CI \-m \0minor Create the special file with the specified minor number .IR minor . The format of .I minor is the same as that given in .IR mknod (1M) and .IR mknod (5). .TP .CR \-q Quiet option. Normally, .CR mksf displays a message as each driver is processed. This option suppresses the driver message, but not error messages. See the .CR \-v option. .TP .CR \-r Create a character (raw) special file instead of a block special file. .TP .CR \-v Verbose option. In addition to the normal processing message, display the name of each special file as it is created. See the .CR \-q option. .RE .SS Naming Conventions Many special files are named using the .CI c card t target d device naming convention. These variables have the following meaning wherever they are used. .RS .TP 10 .I card The unique interface card identification number from .CR ioscan (see .IR ioscan (1M)). It is represented as a decimal number with a typical range of 0 to 255. .TP .I target The device target number, for example the address on a HP\-FL or SCSI bus. It is represented as a decimal number with a typical range of 0 to 15. .TP .I device A address unit within a device, for example, the unit in a HP-FL device or the LUN in a SCSI device. It is represented as a decimal number with a typical range of 0 to 15. .SS Special Files .PP The driver-specific options .RI ( driver\-options ) and default special file names .RI ( special\-file ) are listed below. .PP .CR asio0 .RS .TP 15 .CI \-a \0access\-mode Port access mode (0-2). The default access mode is 0 (Direct connect). The .I access\-mode meanings are: .sp .5v .ne 7 .TS box tab(;); cf2 | cf3 c | l. access\-mode;Port Operation _ \f3\f40\f1;Direct connect \f3\f41\f1;Dial out modem \f3\f42\f1;Dial in modem .TE .TP .CR \-c CCITT. .TP .CR \-f Hardware flow control (RTS/CTS). .TP .CR \-i Modem dialer. Cannot be used with .CR \-l. .TP .CR \-l Line printer. Cannot be used with .CR \-i. .TP .CI \-r \0fifo-trigger .I fifo-trigger should have a value between 0 and 3. The following table shows the corresponding FIFO trigger level for a given .I fifo-trigger value. .sp .5v .ne 8 .TS box tab(;); cf2 | cf3 c | c. fifo-trigger;Receive FIFO Trigger Level _ \f3\f40\f1;1 \f3\f41\f1;4 \f3\f42\f1;8 \f3\f43\f1;14 .TE .TP .CR \-t Transparent mode (normally used by diagnostics). .TP .CI \-x \0xmit-limit .I xmit-limit should have a value between 0 and 3. The following table shows the corresponding transmit limit for a given .I xmit-limit value. .sp .5v .ne 8 .TS box tab(;); cf2 | cf3 c | c. xmit-limit;Transmit Limit _ \f3\f40\f1;1 \f3\f41\f1;4 \f3\f42\f1;8 \f3\f43\f1;12 .TE .TP .I special\-file The default special file name depends on the .I access\-mode and whether the .CR \-i and .CR \-l options are used. .sp .5v .ne 9 .TS box tab(;); cf2 | c | c | cB c | c | c | l. access\-mode;\f3\f4-i\f1;\f3\f4-l\f1;Special File Name _ \(em;no;yes;\f3\f4c\f2card\f3\f4p0_lp\f1 \f3\f42\f1;no;no;\f3\f4ttyd\f2card\f3\f4p0\f1 \f3\f41\f1;no;no;\f3\f4cul\f2card\f3\f4p0\f1 \f3\f40\f1;yes;no;\f3\f4cua\f2card\f3\f4p0\f1 \f3\f40\f1;no;no;\f3\f4tty\f2card\f3\f4p0\f1 .TE .RE .PP .CR audio .RS .TP 15 .CI \-f \0format Audio format (0-3). The .I format meanings are: .ifn .in -10n \" move left to fit in nroff .sp .5v .ne 9 .TS box tab(;); c | c | cf3 cf2 | cf3 | cf2 c | l | c . ;;File Name Modifier format;Audio Format;format-mod _ \f3\f40\f1;No change in audio format; \f3\f41\f1;8-bit Mu-law;\f3\f4U\f1 \f3\f42\f1;8-bit A-law;\f3\f4A\f1 \f3\f43\f1;16-bit linear;\f3\f4L\f1 .TE .TP .CI \-o \0output-dest Output destination (0-4). The .I output-dest should have a value between 0 and 4. The following table shows the corresponding output destinations for a given .I output-dest value. .ifn .in -10n \" move left to fit in nroff .sp .5v .ne 10 .TS box tab(;); c | c | cf3 cf2 | cf3 | cf2 c | l | c . ;;File Name Modifier output-dest;Output Destinations;output-mod _ \f3\f40\f1;All outputs;\f3\f4B\f1 \f3\f41\f1;Headphone;\f3\f4E\f1 \f3\f42\f1;Internal Speaker;\f3\f4I\f1 \f3\f43\f1;No output;\f3\f4N\f1 \f3\f44\f1;Line output;\f3\f4L\f1 .TE .TP .CR \-r Raw, control access. This option cannot be used with either the .CR \-f or .CR \-o options. .TP .I special\-file The default special file name depends on the options specified. .sp .5v .ne 7 .TS box tab(;); cf3 | cf3 c | l. Options;Special File Name _ \f3\f4\-r\f1;\f3\f4audioCtl_\f2card\f1 \f3\f4\-f\ 0\f1;\f3\f4audio_\f2card\f1 all others;\f3\f4audio\f2output-mod\^format-mod\f3\f4_\f2card\f1 .TE .IP The optional .IR output-mod and .IR format-mod values are given in the tables above. Note the underscore .RC ( _ ) before .I card in each special file name. Also note that for .I card .CR 0 , each file will be linked to a simpler name without the trailing .CI _ card\f1. .RE .PP .C "autox0 schgr" .RS .PP Note that .CR \-i cannot be used with either .CR \-r or .CR \-p . .TP 15 .CR \-i Ioctl; create picker control special file. .TP .CI \-p \0optical-disk\f1[ : last-optical-disk\f1] The optical disk number (starts with 1). If the optional .CI : last-optical-disk is given then special files for the range of disks specified will be created. .TP .CR \-r Raw; create character, not block, special file. .TP .I special\-file A special file cannot be given if a range of optical disks is given with the .CR \-p option. If one is given for the single disk case, the name will have an .CR a appended to the end for the A-side device and a .CR b appended to the end for the B-side device. The default special file name depends on whether the .CR \-r option is used. .sp .5v .ne 9 .TS box tab(;); c | cB c | l. \f3\f4-r\f1;Special File Name _ yes;\f3\f4rac/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f3\f4_\f2optical-disk\f3\f4a\f1 \& ;\f3\f4rac/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f3\f4_\f2optical-disk\f3\f4b\f1 _ no;\f3\f4ac/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f3\f4_\f2optical-disk\f3\f4a\f1 \&;\f3\f4ac/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f3\f4_\f2optical-disk\f3\f4b\f1 .TE .IP Note the underscore .RC ( _ ) between .I device and .IR optical-disk . .RE .PP .CR CentIf .RS .TP 15 .CI \-h \0handshake-mode Handshake mode. Valid values range from 1 to 6: .ifn .in -12n \" move left to fit in nroff .sp .5v .ne 12 .TS box tab(;); cf2 | cf3 c | l. handshake-mode;Handshake operation _ \f3\f41\f1;Automatic NACK/BUSY handshaking \f3\f42\f1;Automatic BUSY only handshaking \f3\f43\f1;Bidirectional read/write \f3\f44\f1;Stream mode (NSTROBE only, no handshaking) \f3\f45\f1;Automatic NACK/BUSY with pulsed NSTROBE \f3\f46\f1;Automatic BUSY with pulsed NSTROBE .TE .TP .I special\-file The default special file name is .CI c card t0d0_lp for .I handshake-mode .CR 2 and .CI c card t0d0h handshake-mode _lp for all others. .RE .PP .CR disc1 .RS .TP 15 .CR \-c This option must be present if the unit is a cartridge tape. .TP .CR \-r Raw; create character, not block, special file. .TP .CI \-s \0section The section number. .TP .CR \-t Transparent mode (normally used by diagnostics). .TP .CI \-u \0unit The CS/80 unit number (for example, unit 0 for disk, unit 1 for tape). .TP .I special\-file The default special file name depends on whether the .CR \-c , .CR \-r , and .CR \-s options are used: .ifn .in -10n \" move left to fit in nroff .sp .5v .ne 10 .TS box tab(;); c | c | c | cf3 c | c | c | l. \f3\f4-c\f1;\f3\f4-r\f1;\f3\f4-s\f1;Special File Name _ yes;yes;invalid;\f3\f4rct/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f1 no;yes;no;\f3\f4rdsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f1 no;yes;yes;\f3\f4rdsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f3\f4s\f2section\f1 yes;no;invalid;\f3\f4ct/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f1 no;no;no;\f3\f4dsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f1 no;no;yes;\f3\f4dsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f3\f4s\f2section\f1 .TE .RE .PP .CR disc2 .RS .TP 15 .CR \-r Raw; create character, not block, special file. .TP .CI \-s \0section The section number. .TP .CR \-t Transparent mode (normally used by diagnostics). .TP .CI \-u \0unit The cs80 unit number (typically 0). .TP .I special\-file The default special file name depends on whether the .CR \-r and .CR \-s options are used: .sp .5v .ne 8 .TS box tab(;); c | c | cf3 c | c | l. \f3\f4-r\f1;\f3\f4-s\f1;Special File Name _ yes;no;\f3\f4rdsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f1 yes;yes;\f3\f4rdsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f3\f4s\f2section\f1 no;no;\f3\f4dsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f1 no;yes;\f3\f4dsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f3\f4s\f2section\f1 .TE .RE .PP .CR disc3 .RS .TP 15 .CR \-f Floppy. .TP .CR \-r Raw; create character, not block, special file. .TP .CI \-s \0section The section number. .TP .I special\-file The default special file name depends on whether the .CR \-r and .CR \-s options are used: .sp .5v .ne 10 .TS box tab(;); c | c | cf3 c | c | l. \f3\f4-r\f1;\f3\f4-s\f1;Special File Name _ yes;no;\f3\f4rdsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f1 and \& ;;\f3\f4rfloppy/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f1 yes;yes;\f3\f4rdsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f3\f4s\f2section\f1 no;no;\f3\f4dsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f1 and \& ;;\f3\f4floppy/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f1 no;yes;\f3\f4dsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f3\f4s\f2section\f1 .TE .RE .PP .C "disc4 sdisc" .RS .TP 15 .CR \-r Raw; create character, not block, special file. .TP .CI \-s \0section The section number. .TP .I special\-file The default special file name depends on whether the .CR \-r and .CR \-s options are used: .sp .5v .ne 8 .TS box tab(;); c | c | cf3 c | c | l. \f3\f4-r\f1;\f3\f4-s\f1;Special File Name _ yes;no;\f3\f4rdsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f1 yes;yes;\f3\f4rdsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f3\f4s\f2section\f1 no;no;\f3\f4dsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f1 no;yes;\f3\f4dsk/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f3\f4s\f2section\f1 .TE .RE .PP .CR instr0 .RS .TP 15 .CI \-a \0address The HP-IB instrument address (0-30). Cannot be used with the .CR \-t option. .TP .CR \-t Transparent mode (normally used by diagnostics). Cannot be used with the .CR \-a option. .TP .I special\-file The default special file name depends on the arguments .CR \-a and .CR \-t : .sp .5v .ne 7 .TS box tab(;); c | c | cf3 c | c | l. \f3\f4-a\f1;\f3\f4-t\f1;Special File Name _ no;no;\f3\f4hpib/c\f2card\f1 no;yes;\f3\f4diag/hpib/c\f2card\f1 yes;no;\f3\f4hpib/c\f2card\f3\f4t\f2target\f3\f4d\f2address\f1 .TE .RE .PP .CR hil .RS .PP Note that only one of .CR \-a , .CR \-k , or .CR \-r is allowed. .TP 15 .CI \-a \0address The link address (1-7). .TP .CR \-k Cooked keyboard. .TP .CR \-n The hil controller device. .TP .I special\-file The default special file name depends on the .CR \-a , .CR \-k , and .CR \-r options: .sp .5v .ne 7 .TS box tab(;); cf3 | cf3 c | l. Option;Special File Name _ \f3\f4-a\f1;\f3\f4hil_\f2card\f3\f4.\f2address\f1 \f3\f4-k\f1;\f3\f4hilkbd_\f2card\f1 \f3\f4-r\f1;\f3\f4rhil_\f2card\f1 .TE .IP Note the underscore .RC ( _ ) before .IR card . Also note that for .I card .CR 0 , each file will be linked to a simpler name without .CI _ card\f1, either .CI hil address\f1, .CR hilkbd , or .CR rhil . .RE .PP .C "lan0 lan1 lan2 lan3" .RS .PP Note that only one of .CR \-e or .CR \-i is allowed. .TP 15 .CI \-e Ethernet protocol. .TP .CR \-i IEEE 802.3 protocol. .TP .CR \-t Transparent mode (normally used by diagnostics). .TP .I special\-file The default special file name depends on the .CR \-e , .CR \-i , and .CR \-t options: .sp .5v .ne 8 .TS box tab(;); cf3 | c | cf3 c | c | l. Option;\f3\f4-t\f1;Special File Name _ \f3\f4-e\f1;no;\f3\f4ether\f2card\f1 \f3\f4-e\f1;yes;\f3\f4diag/ether\f2card\f1 \f3\f4-i\f1;no;\f3\f4lan\f2card\f1 \f3\f4-i\f1;yes;\f3\f4diag/lan\f2card\f1 .TE .RE .PP .CR lantty0 .RS .TP 15 .CR \-e Exclusive access. .TP .I special\-file The default special file name depends on whether the .CR \-e option is used: .sp .5v .ne 6 .TS box tab(;); c | cf3 c | l. \f3\f4-e\f1;Special File Name _ no;\f3\f4lantty\f2card\f1 yes;\f3\f4diag/lantty\f2card\f1 .TE .RE .PP .C "lpr0 lpr1 lpr2 lpr3" .RS .TP 15 .CR \-c Capital letters. Convert all output to uppercase. .TP .CR \-e Eject page after paper-out recovery. .TP .CR \-n No form-feed. .TP .CR \-o Old paper-out behavior (abort job). .TP .CR \-r Raw. .TP .CR \-t Transparent mode (normally used by diagnostics). .TP .CR \-w No wait. Don't retry errors on open. .TP .I special\-file The default special file name depends on whether the .CR \-r option is used: .sp .5v .ne 6 .TS box tab(;); c | cf3 c | l. \f3\f4-r\f1;Special File Name _ no;\f3\f4c\f2card\f3\f4t\f2target\f3\f4d\f2device\f3\f4_lp\f1 yes;\f3\f4c\f2card\f3\f4t\f2target\f3\f4d\f2device\f3\f4_rlp\f1 .TE .RE .PP .C "mux0 mux2 mux4 eisa_mux0 pci_mux0" .RS .TP 15 .CI \-a \0access\-mode Port access mode (0-2). The default access mode is 0 (Direct connect). The .I access\-mode meanings are: .sp .5v .ne 7 .TS box tab(;); cf2 | cf3 c | l. access\-mode;Port Operation _ \f3\f40\f1;Direct connect \f3\f41\f1;Dial out modem \f3\f42\f1;Dial in modem .TE .TP .CR \-c CCITT. .TP .CR \-f Hardware flow control (RTS/CTS). .TP .CR \-i Modem dialer. Cannot be used with .CR \-l. .TP .CR \-l Line printer. Cannot be used with .CR \-i. .TP .CI \-p \0port Multiplexer port number (0\(mi15 for .CR mux0 and .CR mux2 ; 0\(mi1 for .CR mux4 ; a1 - a16, b1 - b16, c1 - c16 & etc for the .CR eisa_mux0 or .CR pci_mux0 ). Some MUX cards controlled by a particular driver have fewer than the maximum supported ports. .TP .CR \-t Transparent mode (normally used by diagnostics). .TP .I special\-file The default special file name depends on the .I access\-mode and whether the .CR \-i and .CR \-l options are used. .sp .5v .ne 9 .TS box tab(;); cf2 | c | c | cf3 c | c | c | l. access\-mode;\f3\f4-i\f1;\f3\f4-l\f1;Special File Name _ \(em;no;yes;\f3\f4c\f2card\f3\f4p\f2port\f3\f4_lp\f1 \f3\f42\f1;no;no;\f3\f4ttyd\f2card\f3\f4p\f2port\f1 \f3\f41\f1;no;no;\f3\f4cul\f2card\f3\f4p\f2port\f1 \f3\f40\f1;yes;no;\f3\f4cua\f2card\f3\f4p\f2port\f1 \f3\f40\f1;no;no;\f3\f4tty\f2card\f3\f4p\f2port\f1 .TE .RE .PP .C "pflop sflop" .RS .TP 15 .CR \-r Raw; create character, not block, special file. .TP .I special\-file The default special file name depends on whether the .CR \-r option is used: .sp .5v .ne 6 .TS box tab(;); c | cf3 c | l. \f3\f4-r\f1;Special File Name _ no;\f3\f4floppy/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f1 yes;\f3\f4rfloppy/c\f2card\f3\f4t\f2target\f3\f4d\f2device\f1 .TE .RE .PP .CR ps2 .RS .PP Note that only one of .CR \-a , or .CR \-p is allowed. .TP 15 .CI \-a \0auto_device Autosearch device. An .I auto_device value of 0 means first mouse; a value of 1 means first keyboard. .TP .CI \-p \0port PS2 port number. .TP .I special\-file The default special file name depends on the .CR \-a , and .CR \-p options: .sp .5v .ne 7 .TS box tab(;); cf3 | cB c | l. Option;Special File Name _ \f3\f4-a 0\f1;\f3\f4ps2mouse\f1 \f3\f4-a 1\f1;\f3\f4ps2kbd\f1 \f3\f4-p\f1;\f3\f4ps2_\f2port\f1 .TE .IP Note the underscore .RC ( _ ) before .IR port . .RE .PP .CR scc1 .RS .TP 15 .CI \-a \0access\-mode Port access mode (0\(mi2). The default access mode is 0. The .I access\-mode meanings are: .sp .5v .ne 7 .TS box tab(;); cf2 | cf3 c | l. access\-mode;Port Operation _ \f3\f40\f1;Direct connect \f3\f41\f1;Dial out modem \f3\f42\f1;Dial in modem .TE .TP .CR \-b Port B. .TP .CR \-c CCITT. .TP .CR \-i Modem dialer. Cannot be used with .CR \-l. .TP .CR \-l Line printer. Cannot be used with .CR \-i . .TP .I special\-file The default special file name depends on the .I access\-mode and whether the .CR \-i and .CR \-l options are used. .sp .5v .ne 9 .TS box tab(;); cf2 | c | c | cf3 c | c | c | l. access\-mode;\f3\f4-i\f1;\f3\f4-l\f1;Special File Name _ \(em;no;yes;\f3\f4c\f2card\f3\f4p\f2port\f3\f4_lp\f1 \f3\f42\f1;no;no;\f3\f4ttyd\f2card\f3\f4p\f2port\f1 \f3\f41\f1;no;no;\f3\f4cul\f2card\f3\f4p\f2port\f1 \f3\f40\f1;yes;no;\f3\f4cua\f2card\f3\f4p\f2port\f1 \f3\f40\f1;no;no;\f3\f4tty\f2card\f3\f4p\f2port\f1 .TE .RE .PP .CR schgr \0\0\0\0See .CR autox0 . .PP .CR sdisk \0\0\0\0See .CR disc4 . .PP .CR sflop \0\0\0\0See .CR pflop . .PP .CR stape .RS .TP 15 .CR \-a AT&T-style rewind/close. .TP .CI \-b \0bpi Bits per inch or tape density. The recognized values for .I bpi are: .br .CR BEST , .CR D1600 , .CR D3480 , .CR D3480C , .CR D6250 , .CR D6250C , .CR D800 , .CR D8MM_8200 , .CR D8MM_8200C , .CR D8MM_8500 , .CR D8MM_8500C , .CR DDS1 , .CR DDS1C , .CR DDS2 , .CR DDS2C , .CR NOMOD , .CR QIC_1000 , .CR QIC_11 , .CR QIC_120 , .CR QIC_1350 , .CR QIC_150 , .CR QIC_2100 , .CR QIC_24 , .CR QIC_2GB , .CR QIC_525 , .CR QIC_5GB , .CR DLT_42500_24 , .CR DLT_42500_56 , .CR DLT_62500_64 , .CR DLT_81633_64 , .CR DLT_62500_64C , .CR DLT_81633_64C , .br or a decimal number density code. .TP .CR -c \0[\f2code\f1] Compression with optional compression code. The optional decimal code is used to select a particular compression algorithm on drives that support more than one compression algorithm. This option must be specified at the end of an option string. See .IR mt (7) for more details. .TP .CR \-e Exhaustive mode. This option allows the driver to experiment with multiple configuration values in an attempt to access the media. The default behavior is to use only the configuration specified. .TP .CR \-n No rewind on close. .TP .CR \-p Partition one. .TP .CR -s \0[\f2block-size\f1] Fixed block size mode. If a numeric .I block-size is given, it is used for a fixed block size. If the .CR \-s option is used alone, a device-specific default fixed block size is used. This option must be specified at the end of an option string. .TP .CR \-u UC Berkeley-style rewind/close. .TP .CR \-w Wait (disable immediate reporting). .TP .CI \-x \0index Use the .I index value to access the tape device driver property table entry. Recognized values for .I index are decimal values in the range 0 to 30. .TP .I special\-file Put all tape special files in the .CR /dev/rmt directory. This is required for proper maintenance of the Tape Property Table (see .IR mt (7)). Device files located outside the .CR /dev/rmt directory may not provide consistent behavior across system reboots. The default special file names are dependent on the tape drive being accessed and the options specified. All default special files begin with .CI rmt/c card t target d device\f1. See .IR mt (7) for a complete description of the default special file naming scheme for tapes. .RE .PP .C "tape1 tape2" .RS .TP 15 .CR \-a AT&T-style rewind/close. .TP .CI \-b \0bpi Bits per inch or tape density. The recognized values for .I bpi are: .br .CR BEST , .CR D1600 , .CR D3480 , .CR D3480C , .CR D6250 , .CR D6250C , .CR D800 , .CR D8MM_8200 , .CR D8MM_8200C , .CR D8MM_8500 , .CR D8MM_8500C , .CR DDS1 , .CR DDS1C , .CR DDS2 , .CR DDS2C , .CR NOMOD , .CR QIC_1000 , .CR QIC_11 , .CR QIC_120 , .CR QIC_1350 , .CR QIC_150 , .CR QIC_2100 , .CR QIC_24 , .CR QIC_2GB , .CR QIC_525 , .CR QIC_5GB , .CR DLT_42500_24 , .CR DLT_42500_56 , .CR DLT_62500_64 , .CR DLT_81633_64 , .CR DLT_62500_64C , .CR DLT_81633_64C , .br or a decimal number density code. .fi .TP .CI -c \0[\f2code\f1] Compression with optional compression code. The optional decimal code is used to select a particular compression algorithm on drives that support more than one compression algorithm. This option must be specified at the end of an option string. See .IR mt (7) for more details. .TP .CR \-n No rewind on close. .TP .CR \-o Console messages disabled. .TP .CR \-t Transparent mode, normally used by diagnostics. .TP .CR \-u UC Berkeley-style rewind/close. .TP .CR \-w Wait (disable immediate reporting). .TP .CI \-x \0index Use the index value to access the tape device driver property table entry. The recognized values for .I index are decimal values in the range 0 to 30. .TP .CI \-z RTE compatible close. .TP .I special\-file Put all tape special files in the .CR /dev/rmt directory. This is required for proper maintenance of the Tape Property Table (see .IR mt (7)). Device files located outside the .CR /dev/rmt directory may not provide consistent behavior across system reboots. The default special file names are dependent on the tape drive being accessed and the options specified. All default special files begin with .CI rmt/c card t target d device\f1. See .IR mt (7) for a complete description of the default special file naming scheme for tapes. .RE .RE .SH RETURN VALUE .CR mksf exits with one of the following values: .RS .TP .PD 0 .CR 0 Successful completion. .TP .CR 1 Failure. An error occurred. .PD .RE .SH DIAGNOSTICS Most of the diagnostic messages from .CR mksf are self-explanatory. Listed below are some messages deserving further clarification. Errors cause .CR mksf to abort immediately. .SS Errors .PP .C "Ambiguous device specification" .IP Matched more than one device in the system. Use some combination of the .CR \-d , .CR \-C , .CR \-H , and .CR \-I options to specify a unique device. .PP .C "No such device in the system" .IP No device in the system matched the options specified. Use .CR ioscan to list the devices in the system (see .IR ioscan (1M)). .PP .CI "Device driver \&" name " is not in the kernel" .br .CI "Device class \&" name " is not in the kernel" .IP The indicated device driver or device class is not present in the kernel. Add the appropriate device driver and/or device class to the .CR config input file and generate a new kernel (see .IR config (1M)). .PD .PP .C "Device has no instance number" .IP The specified device has not been assigned an instance number. Use .CR ioscan to assign an .I instance to the device. .PP .CI "Directory \&" directory " doesn't exist" .IP The .I directory argument of the .CR \-D option doesn't exist. Use .CR mkdir to create the directory (see .IR mkdir (1)). .SH EXAMPLES Make a special file named .CR /dev/printer for the line printer device associated with instance number 2. .IP .C "mksf \-C printer \-I 2 /dev/printer" .PP Make a special file, using the default naming convention, for the tape device at hardware path 8.4.1. The driver-specific options specify 1600 bits per inch and no rewind on close. .IP .C "mksf \-C tape \-H 8.4.1 \-b D1600 \-n" .SH WARNINGS Many commands and subsystems assume their device files are in .CR /dev ; therefore, the use of the .CR \-D option is discouraged. .SH AUTHOR .CR mksf was developed by HP. .SH FILES .TP 20 .CR /dev/config I/O system special file .TP .CR /etc/mtconfig Tape driver property table database .SH SEE ALSO mkdir(1), config(1M), insf(1M), ioscan(1M), lsdev(1M), mknod(1M), rmsf(1M), mknod(2), ioconfig(4), mknod(5), mt(7). .\" .\" index@\f4mksf\f1 \- make a special (device) file@@@\f3mksf(1M)\f1 .\" index@\f1file, create special (device)@@@\f3mksf(1M)\f1 .\" index@\f1make a special (device) file@@@\f3mksf(1M)\f1 .\" index@\f1create a special (device) file@@@\f3mksf(1M)\f1 .\" index@\f1special (device) file, make@@@\f3mksf(1M)\f1 .\" index@\f1device (special) file, make@@@\f3mksf(1M)\f1 .\" .\" toc@\f3mksf(1M)\f1:\0\0\f4mksf\f1@@@make a special (device) file .\" $Header: acctsh.1m,v 72.4 94/11/14 12:02:10 ssa Exp $ .TA a .TH acctsh 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chargefee, ckpacct, dodisk, lastlogin, monacct, nulladm, prctmp, prdaily, prtacct, shutacct, startup, turnacct \- shell procedures for accounting .SH SYNOPSIS .C /usr/sbin/acct/chargefee .I login-name number .PP .C /usr/sbin/acct/ckpacct .RI [ \|blocks\| ] .PP .C /usr/sbin/acct/dodisk .RC [ -o ] .RI [ \|files \0 ...\|] .PP .C /usr/sbin/acct/lastlogin .PP .C /usr/sbin/acct/monacct .I number .PP .C /usr/sbin/acct/nulladm .I file .PP .C /usr/sbin/acct/prctmp .PP .C /usr/sbin/acct/prdaily .RC [ -l ] .RC [ -c ] .RC [ \c .IR mmdd\| ] .PP .C /usr/sbin/acct/prtacct .I file .RI [ \|heading\| ] .PP .C /usr/sbin/acct/shutacct .RI [ \|reason\| ] .PP .C /usr/sbin/acct/startup .PP .C /usr/sbin/acct/turnacct .CR on \0\(or\0 off \0\(or\0 switch .SH DESCRIPTION .TP 15 .C chargefee Can be invoked to charge a .I number of units to .IR login-name . A record is written to .CR /var/adm/fee , to be merged with other accounting records during the night. .TP .C ckpacct Should be initiated via .IR cron (1M). It periodically checks the size of .CR /var/adm/pacct . If the size exceeds .IR blocks , 1000 by default, .C turnacct is invoked with argument .IR switch . If the number of free disk blocks in the .C /var file system falls below 500, .C ckpacct automatically turns off the collection of process accounting records via the .C off argument to .CR turnacct . When at least this number of blocks is restored, the accounting will be activated again. This feature is sensitive to the frequency at which .C ckpacct is executed, usually by .CR cron . .TP .C dodisk Should be invoked by .C cron to perform the disk accounting functions. By default, it will do disk accounting on the special files in .C /etc/fstab. If the .C -o flag is used, it does a slower version of disk accounting by login directory. .I files specifies the one or more filesystem names where disk accounting is to be done. If .I files is used, disk accounting will be done on these filesystems only. If the .C -o flag is used, .I files should be mount points of mounted filesystem. If omitted, they should be the special file names of mountable filesystems. .TP .C lastlogin Invoked by .C runacct to update .C /var/adm/acct/sum/loginlog which shows the last date on which each user logged in (see .IR runacct (1M)). .TP .C monacct Should be invoked once each month or each accounting period. .I number indicates which month or period it is. If .I number is not given, it defaults to the current month (01 through 12). This default is useful if .C monacct is to executed via .CR cron on the first day of each month. .C monacct creates summary files in .C /var/adm/acct/fiscal and restarts summary files in .CR /var/adm/acct/sum . .TP .C nulladm Creates .I file with mode 664 and ensures that owner and group are .CR adm . It is called by various accounting shell procedures. .TP .C prctmp Can be used to print the session record file normally .C /var/adm/acct/nite/ctmp created by .C acctcon1 (see .IR acctcon (1M)). .TP .C prdaily Invoked by .C runacct (see .IR runacct (1M)) to format a report of the previous day's accounting data. The report resides in .CI /var/adm/acct/sum/rprt mmdd where .I mmdd is the month and day of the report. The current daily accounting reports may be printed by typing .IR prdaily . Previous days' accounting reports can be printed by using the .I mmdd option and specifying the exact report date desired. The .C -l flag prints a report of exceptional usage by login id for the specifed date. Previous daily reports are cleaned up and therefore inaccessible after each invocation of .CR monacct . The .C -c flag prints a report of exceptional resource usage by command, and can be used on current day's accounting data only. .TP .C prtacct Can be used to format and print any total accounting .RC ( tacct ) file. .TP .C shutacct Should be invoked during a system shutdown to turn process accounting off and append a ``reason'' record to .CR /var/adm/wtmp . .TP .C startup Should be called by system startup scripts to turn the accounting on whenever the system is brought up. .TP .C turnacct An interface to .C accton (see .IR acct (1M)) to turn process accounting .C on or .CR off . The .C switch argument turns accounting off, moves the current .C /var/adm/pacct to the next free name in .CI /var/adm/pacct incr then turns accounting back on again. .RI ( incr is a number starting with .C 1 and incrementing by one for each additional .C pacct file.) .C turnacct is called by .CR ckpacct , and thus can be run under .C cron and used to keep .C pacct to a reasonable size. .SH FILES .TP 40 .C /usr/sbin/acct holds all accounting commands listed in section (1M) of this manual .PD 0 .TP .C /var/adm/fee accumulator for fees .TP .C /var/adm/acct/nite working directory .TP .C /var/adm/pacct current file for per-process accounting .TP .C /var/adm/pacct* used if .C pacct gets large, and during execution of daily accounting procedure .TP .C /usr/sbin/acct/ptecms.awk contains the limits for exceptional usage by command name .TP .C /usr/sbin/acct/ptelus.awk contains the limits for exceptional usage by login id .TP .C /var/adm/acct/sum summary directory, should be saved .TP .C /var/adm/wtmp login/logoff summary .PD .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), cron(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR chargefee ": SVID2, SVID3" .PP .CR ckpacct ": SVID2, SVID3" .PP .CR dodisk ": SVID2, SVID3" .PP .CR lastlogin ": SVID2, SVID3" .PP .CR monacct ": SVID2, SVID3" .PP .CR prctmp ": SVID2, SVID3" .PP .CR prdaily ": SVID2, SVID3" .PP .CR prtacct ": SVID2, SVID3" .PP .CR shutacct ": SVID2, SVID3" .PP .CR startup ": SVID2, SVID3" .PP .CR turnacct ": SVID2, SVID3" .\" .\" .\" index@\f1process accounting@@@see accounting .\" index@\f1accounting: \f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4turnacct\f1 \- turn on or turn off process accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1bill fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1user, bill fee to, based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1disk accounting, perform@@@\f3acctsh(1M)\f1 .\" index@\f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1user, show last login date for each@@@\f3acctsh(1M)\f1 .\" index@\f1last login date, show for each user@@@\f3acctsh(1M)\f1 .\" index@\f1login date, show last for each user@@@\f3acctsh(1M)\f1 .\" index@\f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1periodic accounting summary files, create@@@\f3acctsh(1M)\f1 .\" index@\f1accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1files: accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1summary files, accounting, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1create empty administration file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1empty administration file owned by \f3adm\f1 with mode 664, create@@@\f3acctsh(1M)\f1 .\" index@\f1administration file owned by \f3adm\f1 with mode 664, create empty@@@\f3acctsh(1M)\f1 .\" index@\f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f4acctcon1\f1 \- print session record file created by@@@\f3acctsh(1M)\f1 .\" index@\f1print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1files, accounting: print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1session record file created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f1record file, session, created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1total accounting (\f4tacct\f1) file, print any@@@\f3acctsh(1M)\f1 .\" index@\f1accounting (\f4tacct\f1) file, print any total@@@\f3acctsh(1M)\f1 .\" index@\f4tacct\f1 (total accounting) file, print any@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting: \f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" index@\f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting data and command usage summary, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f1command usage summary and accounting data, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1system shutdown, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f1shutdown, system, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1system startup, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f1startup, system, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f4turnacct\f1 \- turn process accounting on or off@@@\f3acctsh(1M)\f1 .\" index@\f1shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f1system accounting, shell procedures for@@@\f3acctsh(1M)\f1 .\" .\"" Main TOC entry .\" toc@\f3acctsh(1M)\f1:\0\0\f4chargefee\f1, \f4ckpacct\f1, \f4dodisk\f1, \f4lastlogin\f1, \f4monacct\f1, \f4nulladm\f1, \f4prctmp\f1, \f4prdaily\f1,\n\f4prtacct\f1, \f4shutacct\f1, \f4startup\f1, \f4turnacct\f1@@@shell procedures for accounting .\" .\" toc@\f4chargefee\f1:\0\0shell procedures for accounting, charge fee to user@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4ckpacct\f1:\0\0shell procedures for accounting, check size of accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4dodisk\f1:\0\0shell procedures for accounting, perform disk accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4lastlogin\f1:\0\0shell procedures for accounting, show last login date@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4monacct\f1:\0\0shell procedures for accounting, create accounting summary@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4nulladm\f1:\0\0shell procedures for accounting, create null file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prctmp\f1:\0\0shell procedures for accounting, print session record file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prdaily\f1:\0\0shell procedures for accounting, print daily report@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prtacct\f1:\0\0shell procedures for accounting, print accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4shutacct\f1:\0\0shell procedures for accounting, turn off accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4startup\f1:\0\0shell procedures for accounting, start up accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4turnacct\f1:\0\0shell procedures for accounting, turn on or off process accounting@@@\f1see \f3acctsh(1M)\f1 .\" .\" links@acctsh.1m chargefee.1m .\" links@acctsh.1m ckpacct.1m .\" links@acctsh.1m dodisk.1m .\" links@acctsh.1m lastlogin.1m .\" links@acctsh.1m monacct.1m .\" links@acctsh.1m nulladm.1m .\" links@acctsh.1m prctmp.1m .\" links@acctsh.1m prdaily.1m .\" links@acctsh.1m prtacct.1m .\" links@acctsh.1m shutacct.1m .\" links@acctsh.1m startup.1m .\" links@acctsh.1m turnacct.1m .\" .\" fileset_database@acctsh.1m SYS-ADMIN-MAN .\" $Header: mount.1m,v 78.1 96/01/22 22:34:31 ssa Exp $ .TA m .TH mount 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mount (generic), umount (generic) \- mount and unmount file systems .SH SYNOPSIS .C /usr/sbin/mount .RC [ -l ] .RC [ -p \(or -v ] .PP .C /usr/sbin/mount .C -a .RC [ -F .IR FStype ] .RC [ -eQ ] .PP .C /usr/sbin/mount .RC [ -F .IR FStype ] .RC [ -eQrV ] .RC [ -o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .RI { special \(or directory } .PP .C /usr/sbin/mount .RC [ -F .IR FStype ] .RC [ -eQrV ] .RC [ -o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .I special .I directory .ift .sp .5v \" add extra space to separate the two command groups .PP .C /usr/sbin/umount .RC [ -v ] .RC [ -V ] .RI { special \(or directory } .PP .C /usr/sbin/umount .C -a .RC [ -F .IR FStype ] .RC [ -v ] .SH DESCRIPTION The .CR mount command mounts file systems. Only a superuser can mount file systems. Other users can use .CR mount to list mounted file systems. .PP The .CR mount command attaches .IR special , a removable file system, to .IR directory , a directory on the file tree. .IR directory , which must already exist, will become the name of the root of the newly mounted file system. .IR special and .IR directory must be given as absolute path names. If either .IR special or .IR directory is omitted, .CR mount attempts to determine the missing value from an entry in the .CR /etc/fstab file. .CR mount can be invoked on any removable file system, except .CR / . .PP If .CR mount is invoked without any arguments, it lists all of the mounted file systems from the file system mount table, .CR /etc/mnttab . .PP The .CR umount command unmounts mounted file systems. Only a superuser can unmount file systems. .SS Options (mount) The .CR mount command recognizes the following options: .RS .TP 15 .CR -a Attempt to mount all file systems described in .CR /etc/fstab . All optional fields in .CR /etc/fstab must be included and supported. If the .CR -F option is specified, all file systems in .CR /etc/fstab with that .I FStype are mounted. File systems are not necessarily mounted in the order listed in .CR /etc/fstab . .TP .CR -e Verbose mode. Write a message to the standard output indicating which file system is being mounted. .TP .CI -F \0FStype Specify .IR FStype , the file system type on which to operate. See .IR fstyp (1M). If this option is not included on the command line, then it is determined from either .CR /etc/fstab , by matching .I special with an entry in that file, or from file system statistics of .IR special , obtained by .CR statfsdev() (see .IR statfsdev (3C)). .TP .CR -l Limit actions to local file systems only. .TP .CI -o \0specific_options Specify options specific to each file system type. .I specific_options is a list of comma separated suboptions and/or keyword/attribute pairs intended for a .IR FStype -specific version of the command. See the .IR FStype -specific manual entries for a description of the .I specific_options supported, if any. .TP .CR -p Report the list of mounted file systems in the .CR /etc/fstab format. .TP .CR -Q Prevent the display of error messages that result from an attempt to mount already mounted file systems. .TP .CR -r Mount the specified file system as read-only. Physically write-protected file systems must be mounted in this way or errors occur when access times are updated, whether or not any explicit write is attempted. .TP .CR -v Report the regular output with file system type and flags; however, the .IR directory and .IR special fields are reversed. .TP .CR -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .SS Options (umount) The .CR umount command recognizes the following options: .RS .TP 15 .CR -a Attempt to unmount all file systems described in .CR /etc/mnttab . All optional fields in .CR /etc/mnttab must be included and supported. If .I FStype is specified, all file systems in .CR /etc/mnttab with that .I FStype are unmounted. File systems are not necessarily unmounted in the order listed in .CR /etc/mnttab . .TP .CI -F \0FStype Specify .IR FStype , the file system type on which to operate. If this option is not included on the command line, then it is determined from .CR /etc/mnttab by matching .I special with an entry in that file. If no match is found, the command fails. .TP .CR -v Verbose mode. Write a message to standard output indicating which file system is being unmounted. .TP .CR -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR "/etc/fstab" . This option allows the user to verify the command line. .RE .SH EXAMPLES List the file systems currently mounted: .IP .CR mount .PP Mount the HFS file system .CR /dev/dsk/c1d2s0 at directory .CR /home : .IP .C "mount -F hfs /dev/dsk/c1d2s0 /home" .PP Unmount the same file system: .IP .C "umount /dev/dsk/c1d2s0" .SH AUTHOR .CR mount was developed by HP, AT&T, the University of California, Berkeley, and Sun Microsystems. .SH FILES .TP 25 .PD 0 .CR /etc/fstab Static information about the systems .TP .CR /etc/mnttab Mounted file system table .PD .SH SEE ALSO .RI mount_ FStype (1M), mount(2), fstab(4), mnttab(4), fs_wrapper(5), quota(5). .SH STANDARDS COMPLIANCE .CR mount ": SVID3" .PP .CR umount ": SVID3" .\" .\" index@\f4mount\f1 \- mount a file system (generic)@@@\f3mount(1M)\f1 .\" index@\f4umount\f1 \- unmount a file system (generic)@@@\f3mount(1M)\f1 .\" index@\f1unmount a file system (generic)@@@\f3mount(1M)\f1 .\" index@\f1dismount (unmount) a file system (generic)@@@\f3mount(1M)\f1 .\" index@\f1file system, mount or unmount (generic)@@@\f3mount(1M)\f1 .\" index@\f1generic file system, mount or unmount@@@\f3mount(1M)\f1 .\" .\" index@\f4default_disk_ir\f1 tunable parameter@@@\f3mount(1M)\f1 .\" index@\f1tunable parameter, \f4default_disk_ir\f1@@@\f3mount(1M)\f1 .\" .\" toc@\f3mount(1M)\f1:\0\0\f4mount\f1, \f4umount\f1@@@mount and unmount a file system (generic)\f1 .\" toc@\f4umount\f1:\0\0unmount a file system (generic)@@@\f1see \f3mount(1M)\f1 .\" .\" links@mount.1m umount.1m .\" $Header: mount_cdfs.1m,v 78.2 96/01/22 22:37:04 ssa Exp $ .TA m .TH mount_cdfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mount(cdfs), umount(cdfs) \- mount and unmount an CDFS file systems .SH SYNOPSIS .CR /usr/sbin/mount .RC [ \-l ] .RC [ \-p | \-v ] .PP .CR /usr/sbin/mount .CR \-a .RC [ \-F .CR cdfs ] .RC [ \-eQ ] .PP .CR /usr/sbin/mount .RC [ \-F .CR cdfs ] .RC [ \-eQrV ] .RC [ \-o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .RI { special \(or directory } .PP .CR /usr/sbin/mount .RC [ \-F .CR cdfs ] .RC [ \-eQrV ] .RC [ \-o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .I special .I directory .sp .PP .CR /usr/sbin/umount .CR \-a .RC [ \-F .CR cdfs ] .RC [ \-v ] .PP .CR /usr/sbin/umount .RC [ \-v ] .RC [ \-V ] .RI { special \(or directory } .SH DESCRIPTION The .CR mount command mounts file systems. Only a superuser can mount file systems. Other users can use .CR mount to list mounted file systems. .PP The .CR mount command attaches .IR special , a removable file system, to .IR directory , a directory on the file tree. .IR directory , which must already exist, will become the name of the root of the newly mounted file system. .IR special and .IR directory must be given as absolute path names. If either .IR special or .IR directory is omitted, .CR mount attempts to determine the missing value from an entry in the .CR /etc/fstab file. .CR mount can be invoked on any removable file system, except .CR / . .PP If .CR mount is invoked without any arguments, it lists all of the mounted file systems from the file system mount table, .CR /etc/mnttab . .PP The .CR umount command unmounts mounted file systems. Only a superuser can unmount file systems. .SS Options (mount) .CR mount recognizes the following options: .RS .TP 15 .CR \-a Attempt to mount all file systems described in .CR /etc/fstab . All optional fields in .CR /etc/fstab must be included and supported. If .CR \-F .CR cdfs is specified, all CDFS file systems in .CR /etc/fstab are mounted. File systems are not necessarily mounted in the order listed in .CR /etc/fstab . .TP .CR \-e Verbose mode. Write a message to standard output indicating which file system is being mounted. .TP .CR \-F\0cdfs Specify the CDFS file system type (see .IR fstyp (1m)). .TP .CR \-l Limit actions to local file systems only. .\" AAA .TP .CI \-o \0specific_options Specify options specific to the CDFS file system type. .I specific_options is a list of comma separated suboptions and/or keyword/attribute pairs intended for the CDFS specific module of the command. .IP The following .IR specific_options are valid on CDFS file systems. .RS .RS .TP 15 .CR cdcase Suppress the display of version numbers. Show and match file names as lower case. .TP .CR defaults Use all default options. When given, this must be the only option specified. .TP .CR ro Mount read-only (default). .TP .CR suid Allow set-user-ID execution (default). .TP .CR nosuid Do not allow set-user-ID execution. .RE .RE .TP .CR \-p Report the list of mounted file systems in the .CR /etc/fstab format. .TP .CR \-Q Prevent the display of error messages resulting from an attempt to mount already mounted file systems. .TP .CR \-r Mount the specified file system as read-only. This option is equivalent to the .CR "\-o\ ro" .IR specific_option . For CDFS file systems this is a default option. .TP .CR \-v Report the regular output with file system type and flags; however, .IR directory and .IR special fields are reversed. .TP .CR \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SS Options (umount) .CR umount recognizes the following options: .RS .TP 15 .CR \-a Attempt to unmount all file systems described in .CR /etc/mnttab . All optional fields in .CR /etc/mnttab must be included and supported. If .CR \-F .CR cdfs is specified, all CDFS file systems in .CR /etc/mnttab are unmounted. File systems are not necessarily unmounted in the order listed in .CR /etc/mnttab . .TP .CR \-F\0cdfs Specify the CDFS file system type (see .IR fstyp (1m)). .TP .CR \-v Verbose mode. Write a message to standard output indicating which file system is being unmounted. .TP .CR \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SH DIAGNOSTICS .PP .CR umount complains if the special file is not mounted or if it is busy. The file system is busy if it contains an open file or some logged-in user's working directory. .SH EXAMPLES Mount a local CDFS disk: .IP .C "mount -F cdfs /dev/dsk/c0d0s4 /cdrom" .PP Unmount a local CDFS disk: .IP .C "umount /dev/dsk/c0d0s4" .SH WARNINGS .PP Some degree of validation is done on the file system, however, it is generally unwise to mount file systems that are defective, corrupt, or of unknown origin. .SH AUTHOR .CR mount was developed by HP, AT&T, the University of California, Berkeley, and Sun Microsystems. .SH FILES .TP 20 .PD 0 .CR /etc/fstab Static information about the file systems .TP .CR /etc/mnttab Mounted file system table .PD .SH SEE ALSO fsclean(1M), mount(1M), quotaon(1M), mount(2), fstab(4), mnttab(4), fs_wrapper(5), quota(5). .SH STANDARDS COMPLIANCE .CR mount ": SVID3" .br .CR umount ": SVID3" .\" .\" index@\f4mount\f1 \- mount CDFS file systems@@@\f3mount_cdfs(1M)\f1 .\" index@\f4umount\f1 \- unmount CDFS file systems@@@\f3mount_cdfs(1M)\f1 .\" index@\f1unmount CDFS file systems@@@\f3mount_cdfs(1M)\f1 .\" index@\f1CDFS file systems, mount and unmount@@@\f3mount_cdfs(1M)\f1 .\" index@\f1dismount (unmount) CDFS file systems@@@\f3mount_cdfs(1M)\f1 .\" index@\f1file systems, mount and unmount CDFS@@@\f3mount_cdfs(1M)\f1 .\" .\" toc@\f3mount_cdfs(1M)\f1:\0\0\f4mount\f1, \f4umount\f1@@@mount and unmount CDFS file systems .\" toc@\f4umount\f1:\0\0mount and unmount CDFS file systems@@@see \f3mount_cdfs(1M)\f1 .\" .\" links@mount_cdfs.1m umount_cdfs.1m .\" $Header: mount_hfs.1m,v 78.1 96/01/22 22:40:15 ssa Exp $ .TA m .TH mount_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mount(hfs), umount(hfs) \- mount and unmount an HFS file systems .SH SYNOPSIS .CR /usr/sbin/mount .RC [ \-l ] .RC [ \-p | \-v ] .PP .CR /usr/sbin/mount .CR \-a .RC [ \-F .CR hfs ] .RC [ \-eQ ] .RC [ \-f ] .PP .CR /usr/sbin/mount .RC [ \-F .CR hfs ] .RC [ \-eQrV ] .RC [ \-f ] .RC [ \-o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .RI { special \(or directory } .PP .CR /usr/sbin/mount .RC [ \-F .CR hfs ] .RC [ \-eQrV ] .RC [ \-f ] .RC [ \-o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .I special .I directory .sp .PP .CR /usr/sbin/umount .CR \-a .RC [ \-F .CR hfs ] .RC [ \-v ] .PP .CR /usr/sbin/umount .RC [ \-v ] .RC [ \-V ] .RI { special \(or directory } .SH DESCRIPTION The .CR mount command mounts file systems. Only a superuser can mount file systems. Other users can use .CR mount to list mounted file systems. .PP The .CR mount command attaches .IR special , a removable file system, to .IR directory , a directory on the file tree. .IR directory , which must already exist, will become the name of the root of the newly mounted file system. .IR special and .IR directory must be given as absolute path names. If either .IR special or .IR directory is omitted, .CR mount attempts to determine the missing value from an entry in the .CR /etc/fstab file. .CR mount can be invoked on any removable file system, except .CR / . .PP If .CR mount is invoked without any arguments, it lists all of the mounted file systems from the file system mount table, .CR /etc/mnttab . .PP The .CR umount command unmounts mounted file systems. Only a superuser can unmount file systems. .SS Options (mount) .CR mount recognizes the following options: .RS .TP 15 .CR \-a Attempt to mount all file systems described in .CR /etc/fstab . All optional fields in .CR /etc/fstab must be included and supported. If .CR \-F .CR hfs is specified, all HFS file systems in .CR /etc/fstab are mounted. File systems are not necessarily mounted in the order listed in .CR /etc/fstab . .TP .CR \-e Verbose mode. Write a message to standard output indicating which file system is being mounted. .TP .CR \-f Force the file system to be mounted, even if the file system clean flag indicates that the file system should have .CR fsck run on it before mounting (see .IR fsck (1M)). This option is valid only on HFS file systems. .TP .CR \-F\0hfs Specify the HFS file system type (see .IR fstyp (1M)). .TP .CR \-l Limit actions to local file systems only. .\" AAA .TP .CI \-o \0specific_options Specify options specific to the HFS file system type. .I specific_options is a list of comma separated suboptions and/or keyword/attribute pairs intended for the HFS specific module of the command. .IP The following .IR specific_options are valid on HFS file systems. .RS .RS .TP 15 .CR defaults Use all default options. When given, this must be the only option specified. .TP .CR rw Mount read-write (default). .TP .CR ro Mount read-only. .TP .CR suid Allow set-user-ID execution (default). .TP .CR nosuid Do not allow set-user-ID execution. .RE .RE .RS .RS .TP 15 .CR behind Enable, where possible, asynchronous writes to disk. This is the default on 700 systems. .TP 15 .CR delayed Enable delayed or buffered writes to disk. This is the default on 800 systems. .TP 15 .CR fs_async Enable relaxed posting of file system metadata. .TP 15 .CR no_fs_async Enable rigorous posting of file system metadata. This is the default. .TP 15 .CR largefiles Attempt to enable the creation of files greater than 2 gigabytes in size. File systems have to be created or configured to enable large files (see .IR mkfs_hfs(1M) and .IR fsadm_hfs(1M)). .TP 15 .CR nolargefiles Attempt to disable the creation of files greater than 2 gigabytes in size. File systems have to be created or configured to disable large files. (see .IR mkfs_hfs(1M) and .IR fsadm_hfs(1M)). .TP 15 .CR quota Enable disk quotas (valid only for .CR rw file systems). .TP .CR noquota Disable disk quotas (default). .PP Mounting with the .CR quota option also enables quotas for the file system, unlike some other systems, which require the additional invocation of the .CR quotaon command after the file system has been mounted (see .IR quotaon (1M)). Running .CR quotaon does no harm, but it is not necessary. .RE .RE .TP .CR \-p Report the list of mounted file systems in the .CR /etc/fstab format. .TP .CR \-Q Prevent the display of error messages resulting from an attempt to mount already mounted file systems. .TP .CR \-r Mount the specified file system as read-only. This option is equivalent to the .CR "\-o\ ro" .IR specific_option . Physically write-protected file systems must be mounted in this way or errors occur when access times are updated, whether or not any explicit write is attempted. .TP .CR \-v Report the regular output with file system type and flags; however, .IR directory and .IR special fields are reversed. .TP .CR \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SS Options (umount) .CR umount recognizes the following options: .RS .TP 15 .CR \-a Attempt to unmount all file systems described in .CR /etc/mnttab . All optional fields in .CR /etc/mnttab must be included and supported. If .CR \-F .CR hfs is specified, all HFS file systems in .CR /etc/mnttab are unmounted. File systems are not necessarily unmounted in the order listed in .CR /etc/mnttab . .TP .CR \-F\0hfs Specify the HFS file system type (see .IR fstyp (1M)). .TP .CR \-v Verbose mode. Write a message to standard output indicating which file system is being unmounted. .TP .CR \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SH DIAGNOSTICS .PP .CR umount complains if the special file is not mounted or if it is busy. The file system is busy if it contains an open file or some logged-in user's working directory. .SH EXAMPLES Mount a local HFS disk: .IP .C "mount -F hfs /dev/dsk/c0d0s4 /usr" .PP Unmount a local HFS disk: .IP .C "umount /dev/dsk/c0d0s4" .SH WARNINGS .PP Some degree of validation is done on the file system, however, it is generally unwise to mount file systems that are defective, corrupt, or of unknown origin. .SH AUTHOR .CR mount was developed by HP, AT&T, the University of California, Berkeley, and Sun Microsystems. .SH FILES .TP 20 .PD 0 .CR /etc/fstab Static information about the file systems .TP .CR /etc/mnttab Mounted file system table .PD .SH SEE ALSO fsclean(1M), mount(1M), mkfs_hfs(1M), fsadm_hfs(1M), quotaon(1M), mount(2), fstab(4), mnttab(4), fs_wrapper(5), quota(5). .SH STANDARDS COMPLIANCE .CR mount ": SVID3" .br .CR umount ": SVID3" .\" .\" index@\f4mount\f1 \- mount HFS file systems@@@\f3mount_hfs(1M)\f1 .\" index@\f4umount\f1 \- unmount HFS file systems@@@\f3mount_hfs(1M)\f1 .\" index@\f1unmount HFS file systems@@@\f3mount_hfs(1M)\f1 .\" index@\f1HFS file systems, mount and unmount@@@\f3mount_hfs(1M)\f1 .\" index@\f1dismount (unmount) HFS file systems@@@\f3mount_hfs(1M)\f1 .\" index@\f1file systems, mount and unmount HFS@@@\f3mount_hfs(1M)\f1 .\" .\" toc@\f3mount_hfs(1M)\f1:\0\0\f4mount\f1, \f4umount\f1@@@mount and unmount HFS file systems .\" toc@\f4umount\f1:\0\0mount and unmount HFS file systems@@@see \f3mount_hfs(1M)\f1 .\" .\" links@mount_hfs.1m umount_hfs.1m .\" $Header: mount_lofs.1m,v 78.1 96/01/22 22:41:08 ssa Exp $ .TA m .TH mount_lofs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mount(lofs), umount(lofs) \- mount and unmount an LOFS file system .SH SYNOPSIS .CR /usr/sbin/mount .RC [ -p | -v ] .PP .CR /usr/sbin/mount .CR -a .RC [ -F .CR lofs ] .RC [ -eQ ] .PP .CR /usr/sbin/mount .RC [ -F .CR lofs ] .RC [ -eQrV ] .RC [ -o .IR specific_options ] .br \0\0\0\0 .RI { special_directory \(or directory } .PP .CR /usr/sbin/mount .RC [ -F .CR lofs ] .RC [ -eQrV ] .RC [ -o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .I special_directory .I directory .sp .PP .C /usr/sbin/umount .RC [ -v ] .RC [ -V ] .RI { special_directory \(or directory } .PP .C /usr/sbin/umount .C -a .RC [ -F .CR lofs ] .RC [ -v ] .SH DESCRIPTION The .CR mount command mounts LOFS file systems. Only superuser can mount LOFS file systems. Other users can use .CR mount to list mounted file systems. .PP .CR mount , attaches .IR special_directory , a directory from one of the mounted file systems, to .IR directory , an another directory in one of the mounted file systems. This enables new file systems to be created, which provide access to existing directories or file systems using alternate path names. Both .IR special_directory and .IR directory should already exist. .I directory will become the root of the newly mounted LOFS file system, containing the file system hierarchy under .IR special_directory . .IR special_directory and .IR directory must be specified as absolute path names. If either .IR special_directory or .IR directory is omitted, .CR mount attempts to determine the missing value from an entry in the .CR /etc/fstab file. .CR mount can be invoked on any removable file system, except .CR / . .PP If .CR mount is invoked without any arguments, it lists all the mounted file systems from the file system mount table, .CR /etc/mnttab . .PP The .CR umount command unmounts mounted file systems. Only a superuser can unmount file systems. .SS Options (mount) .CR mount recognizes the following options: .RS .TP 15 .CR -a Attempt to mount all file systems described in .CR /etc/fstab . All optional fields in .CR /etc/fstab must be included and supported. If .CR "-F lofs" is specified, all LOFS file systems in .CR /etc/fstab are mounted. File systems are not necessarily mounted in the order listed in .CR /etc/fstab . .TP .CR -e Verbose mode. Write a message to standard output indicating which file system is being mounted. .TP .CR -F\0lofs Specify the LOFS file system type (see .IR fstyp (1M)). .TP .CR -l Limit actions to local file systems only. LOFS is a local file system. .TP .CI \-o \0specific_options Specify options specific to the LOFS file system type. .I specific_options is a list of comma separated suboptions and/or keyword/attribute pairs intended for the LOFS specific module of the command. .IP The following .I specific_options are valid on an LOFS file system: .RS .RS .TP 15 .CR defaults Use all default options. When used, this must be the only option specified. .TP .CR ro Read-only. .RE .RE .TP .CR -p Report the list of mounted file systems in the .CR /etc/fstab format. .TP .CR -Q Prevent display of error messages resulting from an attempt to mount already mounted file systems. .TP .CR -r Mount the specified file system as read-only. .TP .CR -v Report the output in a new style. The new style has the file system type and flags displayed in addition to the old output. The .IR directory and .IR special_directory fields are reversed. .TP .CR -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .SS Options (umount) The .CR umount command recognizes the following options: .RS .TP 15 .CR -a Attempt to unmount all file systems described in .CR /etc/mnttab . All optional fields in .CR /etc/mnttab must be included and supported. If .CR "-F lofs" file system type is specified, all the LOFS file systems in .CR /etc/mnttab are unmounted. File systems are not necessarily unmounted in the order listed in .CR /etc/mnttab . .TP .CR -F\0lofs Specify the LOFS file system type (see .IR fstyp (1M)). .TP .CR -v Verbose mode. Write a message to standard output indicating which file system is being unmounted. .TP .CR -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR "/etc/fstab" . This option allows the user to verify the command line. .SH EXAMPLES Mount an LOFS file system: .IP .C "mount /usr /tmp/usr" .PP Mount another LOFS file system: .IP .C "mount -F lofs /usr/sbin /tmp/sbin" .SH WARNINGS LOFS file systems provide the user with numerous applications; however, they may be potentially confusing. LOFS file systems should generally be created by an experienced user. .SH AUTHOR .CR mount was developed by HP, AT&T, the University of California, Berkeley, and Sun Microsystems. .SH FILES .TP 25 .CR /etc/fstab Static information about the file systems .PD 0 .TP .CR /etc/mnttab Mounted file system table .PD .SH SEE ALSO mount(1M), mount(2), fstab(4), mnttab(4). .SH STANDARDS CONFORMANCE .PP .CR mount ": SVID3" .\" .\" index@\f4mount\f1 \- mount an LOFS file system@@@\f3mount_lofs(1M)\f1 .\" index@file system, mount an LOFS@@@\f3mount_lofs(1M)\f1 .\" index@LOFS file system, mount@@@\f3mount_lofs(1M)\f1 .\" .\" toc@\f3mount_lofs(1M)\f1:\0\0\f4mount\f1@@@mount an LOFS file system .\" .\" links@mount_lofs.1m umount_lofs.1m .\" $Header: mount_nfs.1m,v 78.2 96/01/22 22:42:46 ssa Exp $ .TA m .TH mount_nfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mount(nfs), umount(nfs) \- mount and unmount an NFS file systems .SH SYNOPSIS .CR /usr/sbin/mount .RC [ \-l ] .RC [ \-p | \-v ] .PP .CR /usr/sbin/mount .CR \-a .RC [ \-F .CR nfs ] .RC [ \-eQ ] .PP .CR /usr/sbin/mount .RC [ \-F .CR nfs ] .RC [ \-eQrV ] .RC [ \-o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .RI { host:path \(or directory } .PP .CR /usr/sbin/mount .RC [ \-F .CR nfs ] .RC [ \-eQrV ] .RC [ \-o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .I host:path .I directory .sp .PP .CR /usr/sbin/umount .CR \-a .RC [ \-F .CR nfs ] .RC [ \-h .IR host ] .RC [ \-v ] .PP .CR /usr/sbin/umount .RC [ \-v ] .RC [ \-V ] .RI { host:path \(or directory } .SH DESCRIPTION The .CR mount command mounts file systems. Only a superuser can mount file systems. Other users can use .CR mount to list mounted file systems. .PP The .CR mount command attaches .IR host:path to .IR directory. .IR host is a remote system, .IR path is a directory on this remote system and .IR directory is a directory on the local file tree. .IR directory must already exist, be given as an absolute path name and will become the name of the root of the newly mounted file system. If either .IR host:path or .IR directory is omitted, .CR mount attempts to determine the missing value from an entry in the .CR /etc/fstab file. .CR mount can be invoked on any removable file system, except .CR / . .PP If .CR mount is invoked without any arguments, it lists all of the mounted file systems from the file system mount table, .CR /etc/mnttab . .PP The .CR umount command unmounts mounted file systems. Only a superuser can unmount file systems. .SS Options (mount) .CR mount recognizes the following options: .RS .TP 15 .CR \-a Attempt to mount all file systems described in .CR /etc/fstab . All optional fields in .CR /etc/fstab must be included and supported. If .CR \-F .CR nfs is specified, all NFS file systems in .CR /etc/fstab are mounted. File systems are not necessarily mounted in the order listed in .CR /etc/fstab . .TP .CR \-e Verbose mode. Write a message to standard output indicating which file system is being mounted. .TP .CR \-F\0nfs Specify the NFS file system type (see .IR fstyp (1M)). .TP .CR \-l Limit actions to local file systems only. .\" AAA .TP .CI \-o \0specific_options Specify options specific to the NFS file system type. .I specific_options is a list of comma separated suboptions and/or keyword/attribute pairs intended for the NFS specific module of the command. .IP The following .IR specific_options are valid on NFS file systems. .RS .RS .TP 15 .CR defaults Use all default options. When given, this must be the only option specified. .TP .CR rw Mount read-write (default). .TP .CR ro Mount read-only. .TP .CR suid Allow set-user-ID execution (default). .TP .CR nosuid Do not allow set-user-ID execution. .PP Additional .IR specific_options for the NFS file systems are listed under NETWORKING FEATURES below. .RE .RE .TP .CR \-p Report the list of mounted file systems in the .CR /etc/fstab format. .TP .CR \-Q Prevent the display of error messages resulting from an attempt to mount already mounted file systems. .TP .CR \-r Mount the specified file system as read-only. This option is equivalent to the .CR "\-o\ ro" .IR specific_option . Physically write-protected file systems must be mounted in this way or errors occur when access times are updated, whether or not any explicit write is attempted. .SS Options (umount) .CR umount recognizes the following options: .RS .TP 15 .CR \-a Attempt to unmount all file systems described in .CR /etc/mnttab . All optional fields in .CR /etc/mnttab must be included and supported. If .CR \-F .CR nfs option is specified, all NFS file systems in .CR /etc/mnttab are unmounted. File systems are not necessarily unmounted in the order listed in .CR /etc/mnttab . .TP .CR \-F\0nfs Specify the NFS file system type (see .IR fstyp (1M)). .TP .CI \-h \0host Unmount only those file systems listed in .CR /etc/mnttab that are remote-mounted from .IR host . .TP .CR \-v Verbose mode. Write a message to standard output indicating which file system is being unmounted. .TP .CR \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SH NETWORKING FEATURES .SS NFS The following .I specific_options are applicable to NFS file systems: .RS .TP 15 .CI acdirmax= n Hold cached attributes for no more than .IR n seconds after directory update. .TP .CI acdirmin= n Hold cached attributes for at least .IR n seconds after directory update. .TP .CI acregmax= n Hold cached attributes for no more than .IR n seconds after file modification. .TP .CI acregmin= n Hold cached attributes for at least .IR n seconds after file modification. .TP .CI actimeo= n Set minimum and maximum times for regular files and directories to .IR n seconds. .TP .CR bg If the first .CR mount attempt fails, retry in the background. .\" not supported in B1-NFS; will be supported in 10.0x .TP .CR devs Allow access to local devices (default). .TP .CR fg Retry in foreground (default). .TP .CR hard Once the file system is mounted, retry subsequent NFS requests until server responds (default). .TP .CR intr Permit interrupts for hard mounts (default). .TP .CR noac Suppress attribute and name (lookup) caching. .TP .CR nocto Suppress fresh attributes when opening a file. .\" not supported in B1-NFS; will be supported in 10.0x .TP .CR nodevs Deny access to local devices. .TP .CR nointr Ignore interrupts for hard mounts. .TP .CI port= n Set server UDP port number to .IR n (the default is the port customarily used for NFS servers). .TP .CI retrans= n Set number of NFS retransmissions to .IR n (the default = 4). .TP .CI retry= n Set number of .CR mount failure retries to .IR n (the default = 1). .TP .CI rsize= n Set read buffer size to .IR n bytes (the default is set by kernel). .TP .CR soft Once the file system is mounted, return error if server does not respond. .TP .CI timeo= n Set NFS timeout to .IR n tenths of a second (the default = 7). .TP .CI wsize= n Set write buffer size to .IR n bytes (the default is set by kernel). .RE .PP The regular defaults are: .IP .CR acregmin=3\0\0acregmax=60\0\0acdirmin=30\0\0acdirmax=60 .PP .CR actimeo has no default; it sets .CR acregmin , .CR acregmax , .CR acdirmin , and .CR acdirmax to the value specified. .PP .CR bg causes .CR mount to run in the background if the server's mount daemon does not respond. .PP .CR mount attempts each request .CI retry= n times before giving up. .PP Once the file system is mounted, each NFS request made in the kernel waits .CI timeo= n tenths of a second for a response. If no response arrives, the timeout is multiplied by 2 and the request is retransmitted. When .CI retrans= n retransmissions have been sent with no reply, a .CR soft mounted file system returns an error on the request and a .CR hard mounted file system retries the request. .PP By default, the .CR retry requests for a .CR hard mounted file system can be interrupted. If the .CR nointr option is specified, .CR retry requests for a .CR hard mounted file system are not interruptable which means that .CR retry requests continue until successful. File systems that are mounted .CR rw (read-write) should use the .CR hard option. .PP The number of bytes in a read or write request can be set with the .CR rsize and .CR wsize options. .PP The .CR devs option allows access to devices attached to the NFS client via device files located on the mounted NFS file system. The .CR nodevs option denies access to devices attached to the NFS client by causing attempts to read or write to NFS device files to return an error. .SS File Attributes The attribute cache retains file attributes for the client. Attributes for a file are assigned a time to be flushed. If the file is modified before the flush time, the flush time is extended by the time since the last modification (under the assumption that files that have changed recently are likely to change again soon). There is a minimum and maximum flush time extension for regular files and for directories. Setting .CI actimeo= n extends flush time by .IR n seconds for both regular files and directories. .SH DIAGNOSTICS .CR umount complains if the host:path is not mounted or if it is busy. The file system is busy if it contains an open file or some logged-in user's working directory. .PP Cascaded distributed mounts (mounts whose mount point resides on another client node's locally mounted disk) are not supported. .SH EXAMPLES Mount a remote file system: .IP .C "mount \-F nfs serv:/usr/src /usr/src" .PP Same as above: .IP .C "mount serv:/usr/src /usr/src" .PP Same as above but with a soft mount; the file system is mounted read-only: .IP .C "mount \-o soft,ro serv:/usr/src /usr/src" .SH WARNINGS A directory or file must be exported by the .CR exportfs command before it is NFS-mounted (see .IR exportfs (1M)). .PP Some degree of validation is done on the file system. However, it is generally unwise to mount file systems that are defective, corrupt, or of unknown origin. .SH AUTHOR .CR mount was developed by HP, AT&T, the University of California, Berkeley, and Sun Microsystems. .SH FILES .TP 20 .PD 0 .CR /etc/fstab Static information about the file systems .TP .CR /etc/mnttab Mounted file system table .PD .SH SEE ALSO fsclean(1M), mount(1M), quotaon(1M), mount(2), fstab(4), mnttab(4), fs_wrapper(5), quota(5). .SH STANDARDS COMPLIANCE .CR mount ": SVID3" .br .CR umount ": SVID3" .\" .\" index@\f4mount\f1 \- mount NFS file systems@@@\f3mount_nfs(1M)\f1 .\" index@\f4umount\f1 \- unmount NFS file systems@@@\f3mount_nfs(1M)\f1 .\" index@\f1unmount NFS CDFS file systems@@@\f3mount_nfs(1M)\f1 .\" index@\f1NFS file systems, mount and unmount@@@\f3mount_nfs(1M)\f1 .\" index@\f1dismount (unmount) NFS file systems@@@\f3mount_nfs(1M)\f1 .\" index@\f1file systems, mount and unmount NFS@@@\f3mount_nfs(1M)\f1 .\" .\" toc@\f3mount_nfs(1M)\f1:\0\0\f4mount\f1, \f4umount\f1@@@mount and unmount NFS file systems .\" toc@\f4umount\f1:\0\0mount and unmount NFS file systems@@@see \f3mount_nfs(1M)\f1 .\" .\" links@mount_nfs.1m umount_nfs.1m .\" $Header: mount_vxfs.1m,v 78.2 96/02/13 13:23:44 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA m .TH mount_vxfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mount, umount (vxfs) \- mount and unmount a VxFS file system .SH SYNOPSIS .C /usr/sbin/mount .RC [ \-l ] .RC [ \-v | \-p ] .br .C /usr/sbin/mount .RC [ \-F .CR vxfs\| ] .RC [ \-eQ ] .C \-a .br .\" Use .na and .nh to turn off line adjustment and hyphenation, so .\" that troff/nroff can determine the best way to print the options. .na .nh .C /usr/sbin/mount .RC [ \-F .CR vxfs\| ] .RC [ \-eQrV ] .RS .RC [ \-o .IR specific_options ] .RI { special | mount_point } .RE .br .\" Use .na and .nh to turn off line adjustment and hyphenation, so .\" that troff/nroff can determine the best way to print the options. .na .nh .C /usr/sbin/mount .RC [ \-F .CR vxfs\| ] .RC [ \-eQrV ] .RS .RC [ \-o .IR specific_options ] .I special mount_point .RE .br .\" Use .na and .nh to turn off line adjustment and hyphenation, so .\" that troff/nroff can determine the best way to print the options. .na .nh .C /usr/sbin/umount .RC [ \-V ] .RC [ \-v ] .RI { \|special " |" " directory\|" } .br .C /usr/sbin/umount .RC [ \-F .CR vxfs\| ] .RC [ \-v ] .C \-a .\" Turn adjustment and hyphenation back on. .ad .hy .SH DESCRIPTION The .C mount command attaches .IR special , a removable file system, to .IR directory , a directory on the file tree. .IR directory , which must already exist, will become the name of the root of the newly mounted file system. .C mount can be invoked on any removable file system, except .IR / . If .C mount is invoked with no arguments it lists all the mounted file systems from the mounted file system table, .CR /etc/mnttab . .IR special \0and \0directory must be given as absolute path names. .PP The .C umount command unmounts mounted file systems. .PP Only the superuser can .CR mount " and" " umount" file systems. Other users can use .CR mount to list mounted file systems. .SS Options .CR mount recognizes the following options: .RS .TP 15 .C \-a Attempt to mount all file systems described in .C /etc/fstab. All optional fields in .C /etc/fstab must be included and supported. If .C "\-F vxfs " is specified, all VxFS file systems in .C /etc/fstab are mounted. File systems are not necessarily mounted in the order listed in .CR /etc/fstab . .TP 15 .C \-e Verbose mode. Write a message to the standard output indicating which file system is being mounted. .TP 15 .C "\-F vxfs" Specifies the file system type .RC ( vxfs ). .TP .C \-l Limit actions to local file systems only. .TP .CI \-o " specific_options" Specifies options specific to the VxFS file system type. .I specific_options is a list of comma separated suboptions and/or keyword/attribute pairs intended for the VxFS-specific module of the command. .IP The following .I specific_options are valid on a VxFS file system: .RS .TP 15 .C rw Read-write (default). .TP .C ro Read-only. .TP .C suid Set-user-\c .SM ID execution allowed (default). .TP .C nosuid Set-user-\c .SM ID execution not allowed. .TP 15 .C quota Disk quotas enabled (valid only for .C rw type file systems). VxFS maintains quota information in a private area of the file system. If the file system is mounted with quotas enabled, and the file system was previously mounted with quotas disabled and was modified, then the quota information is rebuilt. This may take awhile. .TP .C remount Changes the mount options for a mounted file system, such as logging and caching policies or whether the file system can be written to. .TP .C log|delaylog|tmplog|nolog Controls intent logging. File system integrity across system failure requires that logging be enabled. The default is .CR log . In .C log mode, file system structural changes are logged to disk before the system call returns to the application. If the system crashes, .IR fsck_vxfs (1M) will complete logged operations that have not completed. .IP In .C delaylog mode, some system calls return before the intent log is written. This improves the performance of the system, but some changes are not guaranteed until a short time later when the intent log is written. This mode approximates traditional UNIX system guarantees for correctness in case of system failures. .IP In .C tmplog mode, the intent log is almost always delayed. This improves performance, but recent changes may disappear if the system crashes. This mode is only recommended for temporary file systems. .IP In .C nolog mode, the intent log is disabled. The other three logging modes provide fast file system recovery; .C nolog does not provide fast file system recovery. With .C nolog mode, a full structural check must be performed after a crash; this may result in loss of substantial portions of the file system, depending upon activity at the time of the crash. Usually, a .C nolog file system should be rebuilt with .IR mkfs_vxfs (1m) after a crash. The .C nolog mode should only be used for memory resident or very temporary file systems. .TP .C blkclear Ensure that all data extents are cleared before being allocated to a file (requires synchronous zeroing, on disk, of certain newly allocated extents). This prevents uninitialized data from appearing in a file being written at the time of a system crash. .TP .CI snapof= filesystem Mount the file system as a snapshot of .IR filesystem , where .I filesystem is either the directory on which a VxFS file system is mounted, or is the block special file containing a mounted VxFS file system. An explicit .CI "\-F vxfs" option is required to mount a snapshot file system. .TP .CI snapsize= blocks Used in conjunction with .CR snapof . .I blocks is the size in sectors of the snapshot file system being mounted. This option is required only when the device driver is incapable of determining the size of .IR special , and will default to the entire device if not specified. .TP .C mincache=direct|dsync|closesync|tmpcache This option is used to alter the caching behavior of the file system. .IP The .C direct value causes any writes without the O_SYNC flag and all reads to be handled as if the VX_DIRECT caching advisory was set instead. .IP The .C dsync value causes any writes without either the O_SYNC flag or the VX_DIRECT caching advisory to be handled as if the VX_DSYNC caching advisory has been set. .IP The .CR closesync , .C dsync and .C direct values all cause the equivalent of an .IR fsync (2) to be run when the file is closed. See .IR vxfsio (7) for an explanation of VX_DIRECT and VX_DSYNC. .IP The .C tmpcache value disables delayed extending writes, trading off integrity for performance. When this option is chosen, VxFS does not zero out new extents allocated as files are sequentially written. Uninitialized data may appear in files being written at the time of a system crash. .TP .C convosync=direct|dsync|closesync|delay This option is used to alter the caching behavior of the file system for O_SYNC I/O operations. .IP The .C direct value causes any reads or writes with the O_SYNC flag to be handled as if the VX_DIRECT caching advisory was set instead. .IP The .C dsync value causes any writes with the O_SYNC flag to be handled as if the VX_DSYNC caching advisory was set instead. .IP The .C closesync value causes O_SYNC writes to be delayed rather than to take effect immediately. The .CR closesync , .CR dsync , and .C direct values all cause the equivalent of an .IR fsync (2) to be run when any file is accessed with the O_SYNC flag is closed. .IP The .C delay value causes O_SYNC writes to be delayed rather than to take effect immediately. Choosing this option causes VxFS to change all O_SYNC writes into delayed writes. No special action is performed when closing a file. This option effectively cancels any data integrity guarantees normally provided by opening a file with O_SYNC. .TP .C datainlog|nodatainlog Normally, the VxFS file system performs small O_SYNC write requests and NFS write requests by logging both the data and the time change to the inode .RC ( datainlog ). If the .C nodatainlog option is used, the logging of synchronous write data is disabled; such writes will write the data into the file and update the inode synchronously before returning to the user. .TP .C largefiles|nolargefiles If one of these options is specified, the file system mount will fail if the .I largefile compatibility bit for the file system does not match the option specified. If .C nolargefiles is specified and the mount succeeds, then the file system does not contain any files whose size is 2 gigabytes or larger, and such files cannot be created. If .C largefiles is specified and the mount succeeds, then the file system may contain files whose size is 2 gigabytes or larger, and large files can be created. The default is to mount the file system according to the .IR "largefile compatibility bit" (see .IR fsadm_vxfs (1M) and .IR mkfs_vxfs (1M).) .RE .TP .C \-p Report the list of mounted file systems in the .CR /etc/fstab format. .TP .C \-Q Prevent display of error messages, resulting from an attempt to mount already mounted file systems. .TP .C \-r Mount the specified file system as read-only. Physically write-protected file systems must be mounted in this way or errors occur when access times are updated, whether or not any explicit write is attempted. .TP .C \-v Reports the regular output with file system type and flags, however, .IR directory " and" " special" fields are reversed. .TP .C \-V Echoes the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR "/etc/fstab" . This option allows the user to verify the command line. .SS .CR umount recognizes the following options: .RS .TP 15 .C \-a Attempt to unmount all file systems described in .CR /etc/mnttab . All optional fields in .C /etc/mnttab must be included and supported. If .C "\-F vxfs" is specified, all VxFS file systems in .C /etc/mnttab are unmounted. File systems are not necessarily unmounted in the order listed in .CR /etc/mnttab . .TP 15 .C "\-F vxfs" Specifies the file system type .RC ( vxfs ). .TP 15 .C \-v Verbose mode. Write a message to the standard output indicating which file system is being unmounted. .TP .C \-V Echoes the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR "/etc/fstab" . This option allows the user to verify the command line. .SH EXAMPLES List the file systems currently mounted: .IP .C mount .PP Mount a VxFS file system .C /dev/dsk/c1d2s0 at directory .C /home .IP .C mount \-F vxfs /dev/dsk/c1d2s0 /home .PP Unmount the same file system: .IP .C umount /dev/dsk/c1d2s0 .SH FILES .TP 20 .PD 0 .C /etc/fstab Static information about the file systems .TP .C /etc/mnttab Mounted file system table .PD .SH SEE ALSO fsadm_vxfs(1M), fsck_vxfs(1M), mkfs_vxfs(1M), mount(1M), mount(2), fsync(2), fstab(4), mnttab(4), quota(5), vxfsio(7). .SH STANDARDS CONFORMANCE .PP .C mount: SVID3 .br .C umount: SVID3 .\" .\" toc@\f3mount_vxfs(1M)\f1:\0\0\f(CWmount\f1, \f(CWunmount\f1@@@mount and unmount VxFS file system .\" toc@\f(CWunmount\f1:\0\0unmount VxFS file system@@@\f1see \f3mount_vxfs(1M)\f1 .\" .\" index@\f(CWmount_vxfs\f1 \- mount and unmount VxFS file system@@@\f3mount_vxfs(1M)\f1 .\" index@\f(CWmount\f1 \- mount VxFS file system@@@\f3mount_vxfs(1M)\f1 .\" index@\f(CWumount\f1 \- unmount VxFS file system@@@\f3mount_vxfs(1M)\f1 .\" .\" index@\f1mount and unmount VxFS file system@@@\f3mount_vxfs(1M)\f1 .\" index@\f1unmount VxFS file system@@@\f3mount_vxfs(1M)\f1 .\" index@\f1VxFS file system, mount and unmount@@@\f3mount_vxfs(1M)\f1 .\" index@\f1file system, mount and unmount VxFS@@@\f3mount_vxfs(1M)\f1 .\" .\" links@mount_vxfs.1m umount_vxfs.1m .\" $Header: mountall.1m,v 76.1 95/07/06 15:04:16 ssa Exp $ .TA m .TH mountall 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mountall, umountall \- mount and unmount multiple file systems .SH SYNOPSIS .C /sbin/mountall .RC [ -F .IR FStype ] .RC [ -l | -r ] .RI [ file_system_table | .CR - ] .br .C /sbin/mountall .RC [ -l | -r ] .RC [ -m ] .br .C /sbin/mountall .RC [ -n ] .br .C /sbin/umountall .RC [ -F .IR FStype ] .RC [ -k ] .RC [ -l | -r ] .SH DESCRIPTION .C mountall is used to mount file systems according to .I file_system_table. By default, .C /etc/fstab is the .IR file_system_table . If a dash .RC ( - ) is specified, .CR mountall reads .I file_system_table from the standard input; the standard input must be in the same format as the .CR /etc/fstab . .PP Before each file system is mounted, a check is done using .CR fsck (see .IR fsck (1M)) to ensure that the file system is mountable. If the file system is not mountable, it is repaired by .CR fsck before the mount is attempted. .PP .C umountall causes all mounted file systems except the non-removable file systems such as .CR root to be unmounted. .SS Options .C mountall and .C umountall recognize the following options: .RS .TP 15 .CI -F " FStype" Specify the file system type .RI ( FStype ) to be mounted or unmounted. .TP 15 .C -l Specify action on local file systems only. .TP 15 .C -r Specify action on remote file systems only. .TP 15 .C -k Send a .C SIGKILL signal to processes that have files opened. .TP 15 .C -m Attempt to mount all the unmounted file systems. This option will not perform the file system consistency check and repair. .TP 15 .C -n Perform the file system consistency check and repair on all unmounted file system. This option will not mount the file systems. .SH DIAGNOSTICS Error and warning messages may originate from .CR fsck , .CR mount , .CR fuser , or .CR umount . See .IR fsck (1M), .IR mount (1M), or .IR fuser (1M) to interpret the error and warning messages. .SH EXAMPLES .PP Mount all unmounted file systems listed in .CR /etc/fstab : .IP .C mountall .PP Mount all local file systems listed in .CR /etc/fstab : .IP .C mountall -l .PP Mount all remote file systems listed in .CR /etc/fstab : .IP .C mountall -r .PP Mount all local hfs file systems: .IP .C mountall -F hfs -l .PP Unmount all NFS file systems and kill any processes that have files opened in the file system: .IP .C umountall -F nfs -k .SH WARNINGS .PP .CR umountall , especially with the .CR -k option, should be used with extreme caution, because it can cause severe damage. .PP The .C -n option may not be available in future releases. .PP .C mountall may not be effective with some cases of LOFS file systems. .SH FILES .TP 20 .C /etc/fstab Static information about the file systems .PD 0 .TP .C /etc/mnttab Mounted file system table .PD .SH SEE ALSO fsck(1M), mount(1M), fuser(1M), mnttab(4), fstab(4), signal(2) .\" .\" toc@\f3mountall(1M)\f1:\0\0\f4mountall\f1, \f4umountall\f1@@@mount and unmount multiple file systems .\" index@\f4mountall\f1 \- mount multiple file systems@@@\f3mountall(1M)\f1 .\" index@\f4umountall\f1 \- unmount multiple file systems@@@\f3mountall(1M)\f1 .\" index@\f1 unmount multiple file systems@@@\f3mountall(1M)\f1 .\" index@\f1 mount multiple file systems@@@\f3mountall(1M)\f1 .\" index@\f1 multiple file systems, mount and unmount@@@\f3mountall(1M)\f1 .\" index@\f1 file systems, mount and unmount multiple@@@\f3mountall(1M)\f1 .\" .\" links@mountall.1m umountall.1m .\" .\" $Header: mountd.1m,v 78.2 96/05/09 12:29:18 ssa Exp $ .\" mountd.1m,v 1.1.113.2 96/01/04 16:29:13 indnetwk Exp $ .TA m .TH mountd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mountd \- \s-1NFS\s0 mount request server .SH SYNOPSIS .C /usr/sbin/rpc.mountd .RC [ -l .IR log_file\| ] .RC [ -t .IR n\| ] .RC [ -p \(or -e \(or -n\ ] .SH DESCRIPTION .C mountd is an .SM RPC server that answers file system mount requests. It reads file .C /etc/xtab (described in .IR exports (4)) to determine which directories are available to which machines. It also provides information on what file systems are mounted by which clients. This information can be printed using the .C showmount command (see .IR showmount (1M)). .PP .C rpc.mountd can be started at boot time by setting the variable .C NFS_SERVER to 1 in the file .C /etc/rc.config.d/nfsconf. It can also be started through .C /etc/inetd.conf (see .IR inetd (1M)), provided that the .C START_MOUNTD variable is set to 0 in .C /etc/rc.config.d/nfsconf. .SS Options .C mountd recognizes the following options: .RS .TP 12 .CI -l \0log_file Log any errors to the named log file, .IR log_file . Errors are not logged if the .C -l option is not specified. .IP The information logged to the file includes the date and time of the error, the host name, process .SM ID and name of the function generating the error, and the error message. Note that different services can share a single log file since enough information is included to uniquely identify each error. .TP .C -p Run from unreserved ports. This option restores the old default behavior on HP-UX. The default has been changed for the mount daemon to run from reserved ports unless this option is set. .TP .C -e Exit after serving each .SM RPC request. When this option is used, the .C inetd security file .C /var/adm/inetd.sec can control access to .SM RPC services. This option only supports .SM UDP requests. .TP .C -n Exit only if: .RS .RS .TP 3 \(bu .C portmap dies (see .IR portmap (1M)), .PD 0 .TP \(bu another .C rpc.mountd registers with .CR portmap , or .TP \(bu .C rpc.mountd becomes unregistered with .CR portmap . .RE .RE .PD .IP This option is more efficient because a new process is not launched for each .SM RPC request. This option is the default. .TP .CI -t n Specify tracing level .I n , where .I n can have one of the following values: .RS .RS .TP .C 1 Errors only (default) .PD 0 .TP .C 2 Errors, mount requests and mount failures .RE .RE .RE .PD .SH WARNINGS The default behavior of the mount daemon is to run from reserved ports. If the daemon needs to be run from unreserved ports, use the -p option. .PP If a client crashes, executing .C showmount on the server will show that the client still has a file system mounted; i.e., the client's entry is not removed from .C /etc/rmtab until the client reboots and executes .C umount -a (see .IR showmount (1M)). .PP Also, if a client mounts the same remote directory twice, only one entry appears in .CR /etc/rmtab . Doing a .C umount of one of these directories removes the single entry and .C showmount no longer indicates that the remote directory is mounted. .SH AUTHOR .C mountd was developed by Sun Microsystems, Inc. .SH FILES .TP 20 .C /etc/rmtab List of all hosts having file systems mounted from this machine .SH SEE ALSO inetd(1M), mount(1M), portmap(1M), showmount(1M), exports(4), inetd.conf(4), inetd.sec(4), rmtab(4), services(4). .\" .\" index@\f4mountd\f1: \s-1NFS\s+1 mount request server@@@\f3mountd(1M)\f1 .\" index@\s-1NFS\s+1 mount request server@@@\f3mountd(1M)\f1 .\" index@mount request server, \s-1NFS\s+1@@@\f3mountd(1M)\f1 .\" index@server, \s-1NFS\s+1 mount request@@@\f3mountd(1M)\f1 .\" .\" toc@\f3mountd(1M)\f1: \f4mountd\f1@@@NFS mount request server .\" .\" links@mountd.1m rpc.mountd.1m .\" $Header: mrinfo.1m,v 76.2 95/06/12 14:24:39 ssa Exp $ .TA m .TH mrinfo 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mrinfo - Multicast Routing Configuration Information Tool .SH SYNOPSIS .CR /usr/sbin/mrinfo .RC [ \-d .IR debuglevel ] .RC [ \-r .IR retries ] .RC [ \-t .IR timeout ] [ .I multicast-router ] .SH DESCRIPTION .CR mrinfo requests the configuration information from the .IR multicast-ourter , and prints the information to the standard out. .I multicast-router can be either an IP address or a system name. .CR mrinfo sends out the .I ASK_NEIGHBORS igmp message to the specified .IR multicast-router , when the router receives the request, it sends back its configuration information. If the .I multicast-router is not specified, the request is sent the local router. .PP The the configuration information for each interface is printed in the following format: .PP .nf .C interface_addr -> neighbor_addr (neighbor_name) [metrics/thresh/flags] .fi .PP If there are multiple neighbor routers on one interface, they will all be reported on the output. The possible values for .I flag are: .TP 14 .C tunnel Neighbors are reached via tunnel. .TP .C srcrt The tunnel uses IP source routing. .TP .C down The interface is down. .TP .C disabled The interface is administratively disabled for multicast routing. .TP .C querier The local router is the querier of the subnet. .PP Please see .IR mrouted (1M) for .CR metrics and .CR thresh . .PP The command line options are: .TP 14 .CI -d debuglevel Sets the level for printing out the debug message. The default is 0, only error and warning messages will be printed. Debug level three prints most the messages. .TP .CI -r retries Sets the retry times to pull the routing daemon for information. The default is 3. .TP .CI -t timeout Specifies the timeout value in seconds for waiting the reply. The default value is 4. .RE .SH EXAMPLE The following is an example of quering the multicasting configuration from the local routing daemon. .PP .RS .nf mrinfo .PP 127.0.0.1 (localhost) [version 3.3]: 15.13.106.144 -> 15.13.106.145 (hpntcbs.cup.hp.com) [10/1/querier] 193.2.1.39 -> 0.0.0.0 (all-zeros-broadcast) [1/1/disabled] 15.13.106.144 -> 15.255.176.33 (matmos.hpl.hp.com) [10/1/tunnel] 15.13.106.144 -> 15.17.20.7 (hpspddc.vid.hp.com) [10/1/tunnel/down] .PP .fi .RE .PP .SH NOTE .PP .CR mrinfo must be run as root. .PP .SH AUTHOR .PP .CR mrinfo was developed by Van Jacobson. .PD .SH SEE ALSO .PP mrouted(1M), map-mbone(1M). .\" .\" index@\f4mrinfo\f1 \- multicast routing configuration information tool@@@\f3mrinfo(1)\f1 .\" index@\f1multicast routing configuration information tool@@@\f3mrinfo(1M)\f1 .\" index@\f1configuration information tool, multicast routing@@@\f3mrinfo(1M)\f1 .\" index@\f1routing, multicast, configuration information tool@@@\f3mrinfo(1M)\f1 .\" .\" toc@\f3mrinfo(1M)\f1:\0\0\f4mrinfo\f1,@@@multicast routing configuration information tool .\" .\" fileset_database@mrinfo.1m INET-ENG-A-MAN .\" $Header $ .TA m .TH mrouted 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .UC 5 .SH NAME mrouted \- IP multicast routing daemon .SH SYNOPSIS .C /usr/sbin/mrouted [ .C \-p ] [ .C \-c .I config_file ] [ .C \-d [ .I debug_level ]] .SH DESCRIPTION .CR mrouted is an implementation of the Distance-Vector Multicast Routing Protocol (DVMRP), an earlier version of which is specified in RFC-1075. It maintains topological knowledge via a distance-vector routing protocol (like RIP, described in RFC-1058), upon which it implements a multicast datagram forwarding algorithm called Reverse Path Multicasting. .PP .CR mrouted forwards a multicast datagram along a shortest (reverse) path tree rooted at the subnet on which the datagram originates. The multicast delivery tree may be thought of as a broadcast delivery tree that has been pruned back so that it does not extend beyond those subnetworks that have members of the destination group. Hence, datagrams are not forwarded along those branches which have no listeners of the multicast group. The IP time-to-live of a multicast datagram can be used to limit the range of multicast datagrams. .PP In order to support multicasting among subnets that are separated by (unicast) routers that do not support IP multicasting, .CR mrouted includes support for "tunnels", which are virtual point-to-point links between pairs of .IR mrouted s located anywhere in an internet. IP multicast packets are encapsulated for transmission through tunnels, so that they look like normal unicast datagrams to intervening routers and subnets. The encapsulation is added on entry to a tunnel, and stripped off on exit from a tunnel. By default, the packets are encapsulated using the IP-in-IP protocol (IP protocol number 4). Older versions of .CR mrouted tunnel using IP source routing, which puts a heavy load on some types of routers. This version supports IP source route tunneling only for backwards compatibility. .PP The tunneling mechanism allows .CR mrouted to establish a virtual internet, for the purpose of multicasting only, which is independent of the physical internet, and which may span multiple Autonomous Systems. This capability is intended for experimental support of internet multicasting only, pending widespread support for multicast routing by the regular (unicast) routers. .CR mrouted suffers from the well-known scaling problems of any distance-vector routing protocol, and does not (yet) support hierarchical multicast routing. .PP .CR mrouted handles multicast routing only; there may or may not be unicast routing software running on the same machine as .CR mrouted . With the use of tunnels, it is not necessary for .CR mrouted to have access to more than one physical subnet in order to perform multicast forwarding. .br .ne 5 .SH INVOCATION .PP If no .CR \-d option is given, or if the debug level is specified as 0, .CR mrouted detaches from the invoking terminal. Otherwise, it remains attached to the invoking terminal and responsive to signals from that terminal. If .CR \-d is given with no argument, the debug level defaults to 2. Regardless of the debug level, .CR mrouted always writes warning and error messages to the system log demon. Non-zero debug levels have the following effects: .TP 10 level 1 all syslog'ed messages are also printed to stderr. .TP level 2 all level 1 messages plus notifications of "significant" events are printed to stderr. .TP level 3 all level 2 messages plus notifications of all packet arrivals and departures are printed to stderr. .SH CONFIGURATION .PP .CR mrouted automatically configures itself to forward on all multicast-capable interfaces, i.e., interfaces that have the IFF_MULTICAST flag set (excluding the loopback "interface"), and it finds other .CR mrouted s directly reachable via those interfaces. To override the default configuration, or to add tunnel links to other .CR mrouted s, configuration commands may be placed in .CR /etc/mrouted.conf (or an alternative file, specified by the .CR \-c option). There are four types of configuration commands: .nf phyint [disable] [metric ] [threshold ] [rate_limit ] [boundary /] tunnel [metric ] [threshold ] [srcrt] [rate_limit ] [boundary /] cache_lifetime pruning .fi .PP One note about the configuration commands - all the phyint and tunnel command options must be on a single line except for the boundary option which may begin on a separate line. .PP The phyint command can be used to disable multicast routing on the physical interface identified by local IP address , or to associate a non-default metric or threshold with the specified physical interface. The local IP address may be alternatively replaced by the interface name e.g le0. Phyint commands must precede tunnel commands. .PP The tunnel command can be used to establish a tunnel link between local IP address and remote IP address , and to associate a non-default metric or threshold with that tunnel. The tunnel must be set up in the mrouted.conf files of both routers before it can be used. For backwards compatibility with older .CR mrouted s, the srcrt keyword specifies encapsulation using IP source routing. .PP The cache_lifetime is a value that determines the amount of time that a cached multicast route stays in kernel before timing out. The value of this entry should lie between 300 (5 min) and 86400 (1 day). It defaults to 300. .PP The pruning option is provided for .CR mrouted to act as a non-pruning router. It is also possible to start .CR mrouted in a non-pruning mode using the .CR \-p option on the command line. It is expected that a router would be configured in this manner for test purposes only. The default mode is pruning enabled. .PP The metric is the "cost" associated with sending a datagram on the given interface or tunnel; it may be used to influence the choice of routes. The metric defaults to 1. Metrics should be kept as small as possible, because .CR mrouted cannot route along paths with a sum of metrics greater than 31. .PP The threshold is the minimum IP time-to-live required for a multicast datagram to be forwarded to the given interface or tunnel. It is used to control the scope of multicast datagrams. (The TTL of forwarded packets is only compared to the threshold, it is not decremented by the threshold. Every multicast router decrements the TTL by 1.) The default threshold is 1. .PP In general, all .CR mrouted s connected to a particular subnet or tunnel should use the same metric and threshold for that subnet or tunnel. .PP The rate_limit option allows the network administrator to specify a certain bandwidth in Kbits/second which would be allocated to multicast traffic. .PP The boundary option allows an interface to be configured as an administrative boundary for the specified scoped address. Packets belonging to this address will not be forwarded on a scoped interface. .PP .CR mrouted will not initiate execution if it has fewer than two enabled vifs, where a vif (virtual interface) is either a physical multicast-capable interface or a tunnel. It will log a warning if all of its vifs are tunnels; such an .I mrouted configuration would be better replaced by more direct tunnels (i.e., eliminate the middle man). .SH SIGNALS .PP .CR mrouted responds to the following signals: .TP 10 HUP restarts .CR mrouted . The configuration file is reread every time this signal is evoked. .TP INT terminates execution gracefully (i.e., by sending good-bye messages to all neighboring routers). .TP TERM same as INT .TP USR1 dumps the internal routing tables to .CR /var/tmp/mrouted.dump . .TP USR2 dumps the internal cache tables to .CR /var/tmp/mrouted.cache . .TP QUIT dumps the internal routing tables to stderr (only if .CR mrouted was invoked with a non-zero debug level). .ift .bp .SH EXAMPLE .PP The routing tables look like this: .nf \f4 Virtual Interface Table Vif Local-Address Metric Thresh Flags 0 36.2.0.8 subnet: 36.2 1 1 querier groups: 224.0.2.1 224.0.0.4 pkts in : 3456 pkts out: 2322323 1 36.11.0.1 subnet: 36.11 1 1 querier groups: 224.0.2.1 224.0.1.0 224.0.0.4 pkts in : 345 pkts out: 3456 2 36.2.0.8 tunnel: 36.8.0.77 3 1 peers : 36.8.0.77 (2.2) acls : 239.0.1 : 239.1.2 pkts in : 34545433 pkts out: 234342 3 36.2.0.8 tunnel: 36.6.8.23 3 16 Multicast Routing Table (1136 entries) Origin-Subnet From-Gateway Metric In-Vif Out-Vifs 36.2 1 0 1* 2 3* 36.8 36.8.0.77 4 2 0* 1* 3* 36.11 1 1 0* 2 3* \f1 .fi In this example, there are four vifs connecting to two subnets and two tunnels. The vif 3 tunnel is not in use (no peer address). The vif 0 and vif 1 subnets have some groups present; tunnels never have any groups. This instance of .CR mrouted is the one responsible for sending periodic group membership queries on the vif 0 and vif 1 subnets, as indicated by the "querier" flags. The list of acls indicate the scoped addresses on that interface. A count of the no. of incoming and outgoing packets is also shown at each interface. .PP Associated with each subnet from which a multicast datagram can originate is the address of the previous hop router (unless the subnet is directly- connected), the metric of the path back to the origin, the incoming vif for multicasts from that origin, and a list of outgoing vifs. "*" means that the outgoing vif is connected to a leaf of the broadcast tree rooted at the origin, and a multicast datagram from that origin will be forwarded on that outgoing vif only if there are members of the destination group on that leaf. .PP .CR mrouted also maintains a copy of the kernel forwarding cache table. Entries are created and deleted by .CR mrouted . .PP The cache tables look like this: .nf \f4 Multicast Routing Cache Table (325 entries) Origin-Subnet Mcast-group CTmr IVif Prcv# Psnt Forwvifs 134.207.7 224.2.140.239 300 1 0 0 2 138.15.103 224.2.203.214 295 1 2 P 0p 2p 128.237.0 224.2.253.119 290 1 1 0 2p 129.215.200 224.2.207.48 40 1 1 0p 2 36.77.14 239.0.1.234 345 2b \f1 .fi Each entry is characterized by the origin subnet number and the destination multicast group. The 'CTmr' field indicates the lifetime (in seconds) of the entry. The entry is deleted from the cache table when the timer decrements to zero. The Ivif field indicates the incoming vif for multicast packets from that origin. Each router also maintains a record of the number of prunes received from neighboring routers for a particular source and group. If there are no members of a multicast group on any downward link of the multicast tree for a subnet, a prune message is sent to the upstream router. They are indicated by a "P" in the Psnt field. The Forwvifs field shows the interfaces along which datagrams belonging to the source-group are forwarded. A "p" indicates that no datagrams are being forwarded along that interface. An unlisted interface is a leaf subnet with are no members of the particular group on that subnet. A "b" on an interface indicates that it is a boundary interface, i.e. traffic will not be forwarded on the scoped address on that interface. .SH FILES .CR /etc/mrouted.conf .SH AUTHORS Steve Deering & Ajit Thyagarajan .SH SEE ALSO RFC-1075, map-mbone(1M), mrinfo(1M). .\" .\" index@\f4mrouted\f1 \- IP multicast routing daemon@@@\f3mrouted(1M)\f1 .\" index@\f1IP multicast routing daemon@@@\f3mrouted(1M)\f1 .\" index@\f1routing daemon, IP multicast@@@\f3mrouted(1M)\f1 .\" index@\f1daemon, IP multicast routing@@@\f3mrouted(1M)\f1 .\" index@\f1multicast routing daemon, IP@@@\f3mrouted(1M)\f1 .\" .\" toc@\f3mrouted(1M)\f1:\0\0\f4mrouted\f1@@@IP multicast routing daemon .\" .\" fileset_database@mrouted.1m INET-ENG-A-MAN .\" $Header: mtail.1m,v 1.1.113.2 96/01/04 16:29:14 indnetwk Exp $ .TA m .TH mtail 1M .SH NAME /usr/sbin/mtail \- Tails the mail log file. .SH SYNOPSIS .C mtail .RI [ n ] .SH DESCRIPTION .C mtail displays the last part of the mail log, typically .CR /var/adm/syslog/mail.log . By default, it displays the last 20 lines of this log. .SS Options .TP .I n Display last .IR n lines of .CR /var/adm/syslog/mail.log instead of just 20. .PP .SH SEE ALSO sendmail(1M). .\" .\" index@\f4mtail\f1 \- displays the last part of the mail log@@@\f3mtail(1M)\f1 .\" index@\f1displays the last part of the mail log@@@\f3mtail(1M)\f1 .\" index@\f1tails the mail log@@@\f3mtail(1M)\f1 .\" index@\f1mail log, displays the last part of@@@\f3mtail(1M)\f1 .\" index@\f1log, mail, displays the last part of@@@\f3mtail(1M)\f1 .\" .\" toc@\f3mtail(1M)\f1:\0\0\f4mtail\f1@@@displays the last part of the mail log .\" $Header: mvdir.1m,v 74.1 95/03/23 18:04:49 ssa Exp $ .TA m .TH mvdir 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mvdir \- move a directory .SH SYNOPSIS .C /usr/sbin/mvdir .I dir newdir .SH DESCRIPTION .C mvdir moves one directory tree into another existing directory (within the same file system), or renames a directory without moving it. .PP .I dir must be an existing directory. .PP If .I newdir does not exist but the directory that would contain it does, .I dir is moved and/or renamed to .IR newdir . Otherwise, .I newdir must be an existing directory not already containing an entry with the same name as the last pathname component of .IR dir . In this case, .I dir is moved and becomes a subdirectory of .IR newdir . The last pathname component of .I dir is used as the name for the moved directory. .PP .C mvdir refuses to move .I dir if the path specified by .I newdir would be a descendent directory of the path specified by .IR dir . Such cases are not allowed because cyclic sub-trees would be created as in the case, for example, of .C mvdir x/y x/y/z/t which is prohibited. .PP .C mvdir does not allow directory .C . to be moved. .PP Only users who have appropriate privileges can use .CR mvdir . .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH AUTHOR .CR mvdir was developed by OSF and HP. .SH SEE ALSO cp(1), mkdir(1), mv(1). .SH STANDARDS CONFORMANCE .CR mvdir ": SVID2, SVID3" .\" .\" index@\f4mvdir\f1 \- move a directory (requires super-user)@@@\f3mvdir(1M)\f1 .\" index@\f1move a directory (requires super-user)@@@\f3mvdir(1M)\f1 .\" index@\f1directory: move a directory (requires super-user)@@@\f3mvdir(1M)\f1 .\" .\" toc@\f3mvdir(1M)\f1:\0\0\f4mvdir\f1@@@move a directory .\" $Header: named-xfer.1m,v 80.3 96/11/12 17:39:48 ssa Exp $ .TA n .TH named-xfer 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 11.00: October 1997 .SH NAME named-xfer \- ancillary agent for inbound zone transfers .SH SYNOPSIS .C named-xfer \-z .IR zone_to_transfer .CR \-f .IR db_file .CR \-s .IR serial_no .RC [ \|\-d .IR debuglevel\| ] .RC [ \|\-l .IR debug_log_file\| ] .br .RC [ \|\-t .IR trace_file\| ] .RC [ \|\-p .IR port# \|] .RC [ \|\-S\| ] .IR nameserver ... .SH DESCRIPTION .C named-xfer is an ancillary program executed by .IR named (1M) to perform an inbound zone transfer. It is rarely executed directly, and then generally by system administrators trying to debug a zone transfer problem. See RFC's 1033, 1034, and 1035 for more information on the Internet name-domain system. .PP Options are: .TP .C \-z specifies the name of the zone to be transferred. .TP .C \-f specifies the name of the file into which the zone should be dumped when it is received from the primary server. .TP .C \-s specifies the serial number of the current copy of the zone selected for transfer. If the SOA resource record received from the specified remote nameserver(s) does not have a serial number higher than one specified with this option, the transfer will be aborted. .TP .C \-d Print debugging information. A number after the .CR d determines the level of messages printed. .TP .C \-l Specifies a log file for debugging messages. The default file uses the prefix .C xfer.ddt. and is located in the .C /var/tmp directory. Note this option only applies if .CR \-d is also specified. .TP .C \-t Specifies a trace file which will contain a protocol trace of the zone transfer. This is probably only of interest when debugging the name server itself. .TP .C \-p Use a different port number. The default is the standard port number as returned by .IR getservbyname (3) for service ``domain''. .TP .C \-S Perform a restricted transfer of only the SOA, NS and glue A records for the zone. The SOA will not be loaded by .CR named , but will be used to determine when to verify the NS records. See the .CR stubs directive in .IR named (1M) for more information. .PP Additional arguments are taken as name server addresses in so-called ``dotted-quad'' syntax only; no host name are allowed here. At least one address must be specified. Any additional addresses will be tried in order if the first one fails to transfer to us successfully. .SH RETURN VALUE .TP .C 0 Indicates that the zone was up-to-date and no transfer was needed. .TP .C 1 Indicates a successful transfer. .TP .C 2 Indicates that the host(s) .C named-xfer queried cannot be reached or that an error occurred and .C named-xfer did not log a corresponding error message. .TP .C 3 Indicates that an error occurred and .C named-xfer logged an error message. .SH AUTHOR .CR named-xfer was developed by the University of California, Berkeley. .SH "SEE ALSO" named(1M), resolver(3N), resolver(4), hostname(5). .P RFC 882, RFC 883, RFC 973, RFC 974, RFC 1033, RFC 1034, RFC 1035, RFC 1123. .\" .\" index@\f4named-xfer\f1 \- ancillary agent for inbound zone transfers@@@\f3named-xfer(1M)\f1 .\" index@\f1inbound zone transfer, ancillary agent@@@\f3named-xfer(1M)\f1 .\" index@\f1ancillary agent for inbound zone transfer@@@\f3named-xfer(1M)\f1 .\" .\" toc@\f3named-xfer(1M)\f1:\0\0\f4named-xfer\f1@@@ancillary agent for inbound zone transfers .\" .\" $Header: named.1m,v 80.3 96/11/12 17:39:56 ssa Exp $ .TA n .TH named 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 11.00: June 1998 .SH NAME named \- Internet domain name server .SH SYNOPSIS .C named .RC [ \|\-d .IR debuglevel\| ] .RC [ \|\-p .IR port_number\| ] .RC [\|[ \|\-b\| ] .IR bootfile\| ] .RC [ \|\-q\| ] .RC [ \|\-r\| ] .SH DESCRIPTION .CR named is the Internet domain name server. See RFC1034 and RFC1035 for more information on the Domain Name System. Without any arguments, .CR named reads the default boot file .CR /etc/named.boot , reads any initial data, and listens for queries. .PP Options are: .RS .TP .C \-d Print debugging information. A number after the .C d determines the level of messages printed. .TP .C \-p Use a different port number. .TP .C \-b Use a boot file other than .CR /etc/named.boot . .TP .C \-q Trace all incoming queries. The boot file directive .CR "options query\-log" can also be used to enable this functionality. .TP .C \-r Turns recursion off in the server. Answers can only come from local (primary or secondary) zones. This can be used on root servers. The boot file directive .CR "options no\-recursion" can also be used to enable this functionality. .RE .PP Any additional argument is taken as the name of the boot file. The boot file contains information about where the name server gets its initial data. If multiple boot files are specified, only the last is used. Lines in the boot file cannot be continued on subsequent lines. The following is a small example: .RS .nf .PP .ft 4 ; ; boot file for name server ; directory /usr/local/domain .ifn .sp .ift .sp 0.4v ; type domain host/file backup file .ifn .sp .ift .sp 0.4v cache . db.cache primary berkeley.edu db.berkeley primary 32.128.in\-addr.arpa db.128.32 secondary cc.berkeley.edu 128.32.137.8 db.cc secondary 6.32.128.in\-addr.arpa 128.32.137.8 db.128.32.6 primary 0.0.127.in\-addr.arpa db.127.0.0 forwarders 10.0.0.78 10.2.0.78 noforward test.com c.b.a.in-add.arpa limit max\-xfers 10 limit files 256 options no\-recursion sortlist 10.0.0.0 26.0.0.0 check-names primary fail check-names secondary warn check-names response ignore .ft 1 .fi .RE .PP Comments in the boot file start with a .C ; and end at the end of the line. Comments can start anywhere on the line. .PP The .CR directory line causes the server to change its working directory to the directory specified. This can be important for the correct processing of $INCLUDE files (described later) in primary servers' master files. There can be more than one .CR directory line in the boot file if master files are in separate directories. .PP Files referenced in the boot file contain data in the master file format described in RFC1035. .PP A server can access information from servers in other domains given a list of root name servers and their addresses. The .CR cache line specifies that data in .CR db.cache is to be placed in the backup cache. Its use is to prime the server with the locations of root domain servers. This information is used to find the current root servers and their addresses. The current root server information is placed in the operating cache. Data for the root nameservers in the backup cache are never discarded. There can be more than one .CR cache file specified. .PP The first .CR primary line states that the master file .CR db.berkeley contains authoritative data for the .CR berkeley.edu zone. A server authoritative for a zone has the most accurate information for the zone. All domain names are relative to the origin, in this case, .CR berkeley.edu (see below for a more detailed description). The second .CR primary line states that the file .CR db.128.32 contains authoritative data for the domain .CR 32.128.in\-addr.arpa . This domain is used to translate addresses in network .CR 128.32 to hostnames. The third .CR primary line states that the file .CR db.127.0.0 contains authoritative data for the domain .CR 0.0.127.in\-addr.arpa . The domain is used to translate .CR 127.0.0.1 to the name used by the loopback interface. Each master file should begin with an SOA record for the zone (see below). .PP The first .CR secondary line specifies that all authoritative data in the .CR cc.berkeley.edu zone is to be transferred from the name server at Internet address 128.32.137.8 and will be saved in the backup file .CR db.cc . Up to 10 addresses can be listed on this line. If a transfer fails, it will try the next address in the list. The secondary copy is also authoritative for the specified domain. The first non-Internet address on this line will be taken as a filename in which to backup the transferred zone. The name server will load the zone from this backup file (if it exists) when it boots, providing a complete copy, even if the master servers are unreachable. Whenever a new copy of the domain is received by automatic zone transfer from one of the master servers, this file is updated. If no file name is given, a temporary file will be used and will be deleted after each successful zone transfer. This is not recommended because it causes a needless waste of bandwidth. .PP A .CR stub line (not shown) is similar to a .CR secondary . Stub zones are intended to ensure that a primary for a zone always has the correct NS records for children of that zone. If the primary is not a secondary for a child zone, it should be configured with stub zones for all its children. Stub zones provide a mechanism to allow NS records for a zone to be specified in only one place. .PP This feature is experimental as of release 4.9.6 of BIND. .RS .nf .PP .ft 4 primary csiro.au db.csiro stub dms.csiro.au 130.155.16.1 db.dms-stub stub dap.csiro.au 130.155.98.1 db.dap-stub .ft 1 .fi .RE .PP The .CR forwarders line specifies the addresses of sitewide servers that will accept recursive queries from other servers. If the boot file specifies one or more forwarders, then the server will send all queries for data not in the cache or in its authoritative data to the forwarders first. Each forwarder will be asked in turn until an answer is returned or the list is exhausted. If no answer is forthcoming from a forwarder, the server will continue as it would have without the forwarders line unless it is in .CR forward\-only (slave) mode. The forwarding facility is useful to cause a large sitewide cache to be generated on a master, and to reduce traffic over links to outside servers. .PP The .CR noforward line specifies that the DNS server will not forward any request for something in or below the listed domains, even if the forwarders directive exists. .PP The .CR sortlist line can be used to indicate networks that are preferred over other, unlisted networks. Address sorting only happens when the query is from a host on the same network as the server. The best address is placed first in the response. The address preference is local network addresses, then addresses on the sort list, then other addresses. .PP The .CR xfrnets directive (not shown) can be used to implement primitive access control. If this directive is given, then your name server will only answer zone transfer requests from hosts which are on networks listed in your .CR xfrnets directives. .PP The .CR include directive (not shown) can be used to process the contents of some other file as though they appeared in place of the .CR include directive. This may be useful if you have many zones or have logical groupings of zones maintained by different people. The directive takes one argument, that being the name of the file whose contents are to be included. No quotation marks are necessary around the file name. .PP The .CR bogusns directive (not shown) tells the server that no queries are to be sent to the specified name server addresses (specified as dotted quads, not as domain names). This may be useful if you know that a popular server has bad data in a zone or cache and you wish to avoid contamination while the problem is being fixed. .PP The .CR limit directive can be used to change the servers' internal limits. .PP The .CR transfers\-in argument is the number of .CR named-xfer subprocesses which the server will spawn at any one time. The .CR transfers\-per\-ns argument is the maximum number of zone transfers to be simultaneously initiated to any given remote name server. The .CR files argument sets the number of filedescriptors available to the process. .PP The .CR options directive introduces a boolean specifier that changes the server behaviour. More than one option can be specified in a single directive. The options are as follows: .RS .TP 15 .C no-recursion which will cause the server to answer with a referral rather than actual data whenever it receives a query for a name it is not authoritative for. This must not be enabled on a server that is listed in any host's .CR resolv.conf file. .TP .C query-log which causes all queries to be logged to the .CR syslog file. This produces a lot of data, so some consideration should be given before enabling this for any period of time. .TP .C forward-only which causes the server to query only its forwarders. This option is normally used on a machine that wishes to run a server but for physical or administrative reasons cannot be given access to the Internet. Enabling this option is equivalent to the use of the "slave" line used in previous versions of .CR named . .TP .C fake-iquery which tells the server to send back a useless and bogus reply to inverse queries rather than responding with an error. .TP .C no-round-robin which disables the default round\-robin cycling of returned IP addresses for multi-homed hosts. .RE .PP The .CR max\-fetch directive (not shown) is allowed for backward compatibility; its meaning is identical to .CR "limit transfers\-in" . .PP The .CR slave directive (not shown) is allowed for backward compatibility; its meaning is identical to .CR "options forward\-only" . .PP The .CR check\-names directive tells BIND to check names in either .CR primary or .CR secondary zone files, or in .CR response received during recursive name resolution. For each type of name, BIND can be told to .CR fail such that a zone would not be loaded or a response would not be cached or forwarded, or merely .CR warn which would cause a message to be emitted in the system operation logs, or to .CR ignore the badness of a name and process it in the traditional fashion. Names are considered good if they confirm to RFC 952 for hostnames or if they consist only of printable ASCII characters, for names which are not hostnames. .PP The master file consists of control information and a list of resource records for objects in the zone of the forms: .RS .nf .P .CI $INCLUDE\0 "filename\0\0opt_domain" .CI $ORIGIN\0 " domain .I domain\0 opt_ttl\0 opt_class\0 type\0 resource_record_data .fi .RE .PP where .I domain is .CR . for root domain, .CR @ for the current origin (where current origin is the domain from the boot file or the origin from an .C $ORIGIN line), or a standard domain name. If .I domain is a standard domain name that does not end with .CR . , the current origin is appended to the domain. Domain names ending with .CR . are unmodified. The .I opt_domain field is used to define an origin for the data in an included file. It is equivalent to placing a .C $ORIGIN statement before the first line of the included file. The field is optional. Neither the .I opt_domain field nor .C $ORIGIN statements in the included file modify the current origin for this file. The .I opt_ttl field is an optional integer number for the time-to-live field. It defaults to zero, meaning the minimum value specified in the SOA record for the zone. The .I opt_class field is the object address type; currently only two types are supported: .CR IN and, to a limited extent, .CR HS . .CR IN is for objects connected to the DARPA Internet and .CR HS is for objects in the Hesiod class. The .I type field contains one of the following tokens; the data expected in the .I resource_record_data field is in parentheses: .RS .TP 12 .C A A host address (dotted quad) .TP .C AFSDB DCE or AFS server information .TP .C CNAME Canonical name for an alias (domain) .TP .C HINFO host information .RI ( cpu_type .IR OS_type ) .TP .C MX a mail exchanger (domain) .TP .C NS an authoritative name server (domain) .TP .C PTR a domain name pointer (domain) .TP .C PX Pointer to X.400/RFC822 mapping information .TP .C SOA marks the start of a zone of authority (domain of originating host, domain address of maintainer, a serial number and the following parameters in seconds: refresh, retry, expire and minimum TTL) .TP .C TXT text data (string) .TP .C WKS a well known service description (\c IP address followed by a list of services) .RE .PP Not all of the data types are used during normal operation. The following data types are for experimental use and are subject to change: AFSDB, PX. .PP Resource records normally end at the end of a line, but can be continued across lines between opening and closing parentheses. Comments are introduced by semicolons and continue to the end of the line. .br .ne 1i .PP Each master zone file should begin with an SOA record for the zone. An example SOA record is as follows: .PP .RS .nf .ft 4 @ IN SOA ucbvax.berkeley.edu. root.ucbvax.berkeley.edu. ( 89 ; Serial 10800 ; Refresh every 3 hours 3600 ; Retry every hour 604800 ; Expire after a week 86400 ) ; Minimum ttl of 1 day .ft 1 .fi .RE .PP The SOA lists a serial number, which should be increased each time the master file is changed. Secondary servers check the serial number at intervals specified by the refresh time in seconds; if the serial number increases, a zone transfer is done to load the new data. If a master server cannot be contacted when a refresh is due, the retry time specifies the interval at which refreshes should be attempted until successful. If a master server cannot be contacted within the interval given by the expire time, all data from the zone is discarded by secondary servers. The minimum value is the time-to-live used by records in the file with no explicit time-to-live value. .SH NOTES The boot file directives .CR domain and .CR suffixes have been obsoleted by a more useful resolver-based implementation of suffixing for partially qualified domain names. .PP The following signals have the specified effect when sent to the server process using the .IR kill (1) command: .RS .TP 15 .C SIGHUP Causes server to read the boot file and reload database. .TP .C SIGINT Dumps current data base and cache to .CR /var/tmp/named_dump.db . .TP .C SIGIOT Dumps statistics data into .CR /var/tmp/named.stats . Statistics data is appended to the file. .TP .C SIGUSR1 Turns on debugging; each .C SIGUSR1 increments debug level. .TP .C SIGUSR2 Turns off debugging completely. .TP .C SIGWINCH Toggles the logging of all incoming queries via .C syslog() .RE .PP .IR sig_named (1M) can also be used for sending signals to the server process. .SH DIAGNOSTICS Any errors encountered by .C named in the boot file, master files, or in normal operation are logged with syslog and in the debug file, .CR /var/tmp/named.run , if debugging is on. .SH AUTHOR .CR named was developed by the University of California, Berkeley. .SH FILES .TP 33 .CR /etc/named.boot name server configuration boot file .PD 0 .TP .CR /var/run/named.pid process ID .TP .CR /var/tmp/named.run debug output .TP .CR /var/tmp/named_dump.db dump of the name server database .TP .CR /var/tmp/named.stats nameserver statistics data .PD .SH "SEE ALSO" kill(1), hosts_to_named(1M), named-xfer(1M), sig_named(1M), signal(2), gethostent(3N), resolver(3N), resolver(4), hostname(5), .PP RFC 882, RFC 883, RFC 973, RFC 974, RFC 1032, RFC 1033, RFC 1034, RFC 1035, RFC 1123. .\" .\" index@\f4named\f1 \- Internet domain name server@@@\f3named(1M)\f3 .\" index@\f1Internet domain name server@@@\f3named(1M)\f1 .\" index@\f1domain name server, Internet@@@\f3named(1M)\f1 .\" index@\f1name server, Internet domain@@@\f3named(1M)\f1 .\" index@\f1server, Internet domain name@@@\f3named(1M)\f1 .\" .\" toc@\f3named(1M)\f1:\0\0\f4named\f1@@@Internet domain name server .\" .\" $Header: ncheck.1m,v 72.6 94/11/30 10:14:49 ssa Exp $ .TA n .TH ncheck 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ncheck (generic) \- generate a list of path names from inode numbers .SH SYNOPSIS .C /usr/sbin/ncheck .RC [ -F .IR FStype\| ] .RC [ -V ] .RC [ -o .IR specific_options\| ] .RI [ \|special\0...\| ] .SH DESCRIPTION .CR ncheck , when invoked without arguments, generates a list of path names corresponding to the inode numbers of all files contained on the file systems listed in .CR /etc/fstab. If .IR special is specified, ncheck reports on the .IR special \0only. Path names generated by .C ncheck are relative to the given .IR special. .SS Options .RS .TP 15 .CI \-F \0FStype Specify the file system type on which to operate (see .IR fstyp (1M) and .IR fs_wrapper (5)). If this option is not included on the command line, then the file system type is determined from the file .CR /etc/fstab by matching each .I special with an entry in that file. If there is no entry in .CR /etc/fstab , then the file system type is determined from the file .CR /etc/default/fs . .TP .CI \-o \0specific_options Specify options specific to each file system type. .I specific_options is a list of suboptions and/or keyword/attribute pairs intended for a specific .IR FStype -specific module of the command. See the file-system-specific manual pages for a description of the .I specific_options supported, if any. .TP .CR \-V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SH EXAMPLES Execute the .CR ncheck command on all .IR special \0in .CR /etc/fstab: .IP .C "ncheck" .PP Execute the .CR ncheck command on HFS file system .CR /dev/dsk/c1d2s0: .IP .C "ncheck \-F hfs /dev/dsk/c1d2s0" .PP Display a completed command line without executing the command: .IP .C "ncheck \-V /dev/dsk/c1d2s0" .SH FILES .TP 25 .CR /etc/default/fs Specifies the default system type. .PD 0 .TP .CR /etc/fstab Static information about the file systems. .PD .SH AUTHOR .C ncheck was developed by AT&T and HP. .SH SEE ALSO fstab(4), fstyp(1M), fs_wrapper(5), .RI ncheck_ FStype (1M). .SH STANDARDS CONFORMANCE .CR ncheck ": SVID2, SVID3" .\" index@\f4ncheck\f1 \- generate path names from i-numbers@@@\f3ncheck(1M)\f1 .\" index@generate path names from i-numbers@@@\f3ncheck(1M)\f1 .\" index@path names from i-numbers, generate@@@\f3ncheck(1M)\f1 .\" index@names from i-numbers, generate path@@@\f3ncheck(1M)\f1 .\" index@i-numbers, generate path names from@@@\f3ncheck(1M)\f1 .\" .\" toc@\f3ncheck(1M)\f1:\0\0\f4ncheck\f1@@@generate path names from inode numbers .\" .\" $Header: ncheck_hfs.1m,v 78.1 96/02/13 13:24:12 ssa Exp $ .TA n .TH ncheck_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ncheck (hfs) \- generate a list of path names from inode numbers for a HFS file system .SH SYNOPSIS .C /usr/sbin/ncheck .RC [ -F .CR hfs ] .RC [ -V ] .RC [ -S .CR sector_ranges ] .RC [ -i .IR inode-numbers\| ] .ift .br .ift \0\0\0\0 .RC [ -a ] .RC [ -s ] .RI [ \|special\0...\| ] .SH DESCRIPTION .CR ncheck , when invoked without arguments, generates a list of path names corresponding to the inode numbers of all files contained on the HFS file systems listed in .CR /etc/fstab. If .IR special is specified, ncheck reports on the .IR special \0only. Path names generated by .C ncheck are relative to the given .IR special. Names of directory files are followed by .CR / . .PP .SS Options .RS .TP 15 .C -a Allow printing of the names .C . and .CR .. , which are ordinarily suppressed. .TP .C -F hfs Specify the HFS file system type. .TP .CI -i \0inode-numbers Report only on files whose inode numbers are specified on the command line, in .I inode-numbers. .I inode-numbers is a comma separated list of inode numbers. .TP .C -s Report only on special files and regular files with set-user-\c .SM ID mode. The .C -s option is intended to discover concealed violations of security policy. .TP .CR \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .TP .CI -S \0sector_ranges Report only on files using sector numbers specified on the command line in .I sector_ranges. .I sector_ranges is a comma separated list of sector ranges. A sector range is a starting sector number and an ending sector number separated by a dash, or just a sector number. The sector numbers should be in DEV_BSIZE units. If no pathname contains the sector number it will be reported as free or containing file system structure. Sectors beyond the end of the file system will be reported as illegal. .PP .SS Access Control Lists Continuation inodes (that is, inodes containing additional access control list information) are quietly skipped since they do not correspond to any path name. .SH EXAMPLES Execute the .CR ncheck command on all .IR special \0in .CR /etc/fstab: .IP .C "ncheck" .PP Execute the .CR ncheck command on HFS file system .CR /dev/dsk/c1d2s0: .IP .C "ncheck \-F hfs /dev/dsk/c1d2s0" .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS When the file system structure is improper, .C ?? denotes the ``parent'' of a parentless file and a path-name beginning with .C ... denotes a loop. .SH AUTHOR .C ncheck was developed by AT&T and HP. .SH FILES .TP 25 .CR /etc/default/fs Specifies the default file system type. .PD 0 .TP .CR /etc/fstab Static information about the file systems. .PD .SH SEE ALSO acl(5), fsck(1M), fstab(4), fs_wrapper(5), ncheck(1M), sort(1). .SH STANDARDS CONFORMANCE .CR ncheck ": SVID2, SVID3" .\" index@\f4ncheck\f1 \- generate path names from i-numbers@@@\f3ncheck(1M)\f1 .\" index@generate path names from i-numbers@@@\f3ncheck(1M)\f1 .\" index@path names from i-numbers, generate@@@\f3ncheck(1M)\f1 .\" index@names from i-numbers, generate path@@@\f3ncheck(1M)\f1 .\" index@i-numbers, generate path names from@@@\f3ncheck(1M)\f1 .\" .\" toc@\f3ncheck(1M)\f1:\0\0\f4ncheck\f1@@@generate path names from inode numbers .\" .\" fileset_database@ncheck.1m SYS-ADMIN-MAN .\" $Header: ncheck_vxfs.1m,v 78.1 96/02/13 13:24:44 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL ** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE ** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA n .TH ncheck_vxfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ncheck (vxfs) \- generate pathnames from inode numbers for a VxFS file system .SH SYNOPSIS .\" Use .na and .nh to turn off line adjustment and hyphenation, so .\" that troff/nroff can determine the best way to print the options. .na .nh .CR /usr/sbin/ncheck .RC [ \-F .CR vxfs ] .RC [ -V\| ] .RC [ \-i .IR ilist ] .RC [ \-a ] .RC [ \-s ] .ifn .br .ifn \0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0 .RC [ \-S .IR sector_list ] .ift .br .ift \0\0\0\0\0\0\0\0\0\0\0\0\0\0\0 .RC [ \-o .IR specific_options ] .I special\0... .\" Turn adjustment and hyphenation back on. .ad .hy .SH DESCRIPTION The .CR ncheck program generates a pathname-\f2vs\f1-inode-number list of files for the specified VxFS file system. .PP Some options accept a .I range as a value. A range consists of a single number, or two numbers separated by a .RC `` - '', indicating an inclusive range of values. If .RC `` - '' is specified and the first number is omitted, 0 is assumed. If the second number is omitted, the end of the file system is assumed. .PP Names of directory files are followed by .RC `` /. ''. .SS Options .RS .TP 15 .CI "\-F vxfs" Specifies the file-system type .RC ( vxfs ). .TP .C \-V Echoes the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR "/etc/fstab" . This option allows the user to verify the command line. .TP 15 .CI "\-i " ilist Limits the report to the files on the ilist that follows. The .I ilist must be separated by commas without spaces. .TP .C \-a Allow printing of the names .RC `` . '' and .RC `` .. '' (dot and dotdot), which are ordinarily suppressed. .TP 15 .C \-s Report only on special files and regular files with set-user-ID mode. This option may be used to detect violations of security policy. .TP 15 .CI "-S " sector_list Report on files containing or referencing the specified sector(s). Output consists of the fileset name, fileset index, inode number, and pathname of file or file type if a structural inode or attribute inode. Sectors not allocated to any file or file system structure are reported as .CR . Sectors not part of the file system are reported as .CR . Unused or irrelevant fields are printed as .RC `` - ''. .RS .PP .I sector_list consists of one or more .I ranges of sector numbers, separated by commas without intervening spaces. Multiple .C -S options accumulate. .RE .TP .CI \-o " specific_options" Specifies options specific to the VxFS file-system type. .I specific_options is a list of suboptions and/or keyword/attribute pairs intended for the VxFS-specific module of the command. .IP The available options are .RS .TP .C m Print mode information (used in conjunction with .CR \-i option). .TP .CI b= block Print pathname containing file system block number .IR block . .TP .CI sector= sector_range Report on all inodes containing or referencing the sector(s) in .IR sector_range . The output includes the inode number, fileset index of the inode, sector(s) contained and the pathname or inode type. Inodes searched include structural inodes and attribute inodes, so a pathname is only generated when the sector is contained by a file. If the sector is not contained in any file, the inode type is printed as .RC `` ''. Multiple .C -o sector= options accumulate. .ne 4 .TP .CI block= block_range Print information on all inodes containing or referencing block numbers in the range specified. The output format is the same as that for .CR -o .CR sector= , but the units used are file-system blocks rather than sectors. .TP .CR surface [ = \f2sector_range\fP] Perform a surface analysis. If a .I sector_range is specified perform a surface analysis only for that range. All the sector are read and if the read of a sector fails, its sector number is printed. If any bad sectors are found, .C ncheck treats the list of bad sector as input to the .C -o .CI sector= # option and produces a list of containing or referencing inodes. .PP .SH EXAMPLES Report on all inodes or file system structures containing or referencing sector 20 through 35 (inclusive) in the file system .CR /dev/vg01/rlvol1 : .IP .C ncheck -F vxfs -S 20-35 /dev/vg01/rlvol1 .PP Same as above but report on all inodes or file system structures referencing any sector in the file system .CR /dev/vg01/rlvol1 : .IP .C ncheck -F vxfs -S - /dev/vg01/rlvol1 .PP .SH DIAGNOSTICS When the file-system structure is improper, .RC `` ??? '' denotes the ``parent'' of a parentless file, a pathname beginning with .RC `` ... '' denotes a loop, and a pathname beginning with .RC `` *** '' denotes a directory entry whose .RC `` .. '' (dotdot) entry is not in accord with the directory in which it was found. .SH FILES .TP 25 .CR /etc/fstab Static information about the file systems. .PD .SH SEE ALSO sort(1), fsck(1M), fsck_vxfs(1M), ncheck(1M). .\" .\" toc@\f3ncheck_vxfs(1M)\f1:\0\0\f(CWncheck\f1@@@generate pathnames from inode numbers for VxFS file system .\" .\" index@\f(CWncheck_vxfs\f1 \- generate pathnames from inode numbers for VxFS file system@@@\f3ncheck_vxfs(1M)\f1 .\" index@\f(CWncheck\f1 \- generate pathnames from inode numbers for VxFS file system@@@\f3ncheck_vxfs(1M)\f1 .\" .\" index@\f1generate pathnames from inode numbers for VxFS file system@@@\f3ncheck_vxfs(1M)\f1 .\" index@\f1pathnames from inode numbers for VxFS file system, generate@@@\f3ncheck_vxfs(1M)\f1 .\" index@\f1inode numbers for VxFS file system, generate pathnames from@@@\f3ncheck_vxfs(1M)\f1 .\" index@\f1VxFS file system, generate pathnames from inode numbers@@@\f3ncheck_vxfs(1M)\f1 .\" index@\f1file system, generate pathnames from inode numbers for VxFS@@@\f3ncheck_vxfs(1M)\f1 .\" .\" $Header: netfmt.1m,v 76.1 95/05/30 15:31:28 ssa Exp $ .TA n .TH netfmt 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME netfmt \- format tracing and logging binary files .SH SYNOPSIS .C /usr/sbin/netfmt -s .RC [ \|\-t .IR records\| ] .RC [[ \|\-f\| ] .IR file_name\| ] .PP .C /usr/sbin/netfmt -p .RC [ \|\-c .IR config_file\| ] .PP .C /usr/sbin/netfmt .RC [ \|\-c .IR config_file\| ] .RC [ \|\-F\| ] .RC [ \|\-t .IR records\| ] .RC [ \|\-v\| ] .RC [ \|\-l\| ] .RC [ \|\-n\| ] .sp 0 .RC [ \|\-N\| \(or .RC [ \|\-1 .RC [ \|\-L\| ] .RC [ \|\-T\| ]]] .RC [[ \|\-f\| ] .IR file_name\| ] .SH DESCRIPTION .C netfmt is used to format binary trace and log data gathered from the network tracing and logging facility (see .IR nettl (1M)). The binary trace and log information can be read from a file or from standard input (if standard input is a tty device, an informative message is given and .CR netfmt quits). Formatted data is written to standard output. .PP Formatting options are specified in an optional filter configuration file. Message inclusion and format can be controlled by the filter configuration file. If no configuration commands are specified, all messages are fully formatted. A description of the filter configuration file follows the option descriptions. .SS Options .C netfmt recognizes the following command-line options and arguments: .RS .TP 15 .C \|\-s Display a summary of the input file. The summary includes the total number of messages, the starting and ending timestamps, the types of messages, and information about the system that the data was collected on. The contents of the input file are not formatted; only a summary is reported. .TP .CI \|\-t " records" Specifies the number of records from the tail end of the input file to format. This allows the user to bypass extraneous information at the beginning of the file, and get to the most recent information quickly. The maximum number of .I records that can be specified is 1000. If omitted, all records are formatted. The .C -t option is not allowed when the input file is a FIFO (pipe). .TP .CI \|\-f " file_name" Specifies the input file containing the binary log or trace data. .I file_name may not be the name of a tty device. Other options may impose additional restrictions on the type of the input file allowed. If omitted, data is read from standard input. .TP .C \|\-p Parse input: this switch allows the user to perform a syntax check on the .I config_file specified by the .C -c parameter. All other parameters are ignored. If the syntax is correct, .C netfmt terminates with no output or warnings. .TP .CI \|\-c " config_file" Specifies the file containing formatter filter configuration commands. Syntax for the commands is given below. When .C -c is omitted the file .SM .C $HOME/.netfmtrc is read for both logging and tracing filter configuration commands if it exists. .TP .C -F Follow the input file. Instead of closing the input file when end of file is encountered, .C netfmt keeps it open and continues to read from it as new data arrives. This is especially useful for watching events occur in real time while troubleshooting a problem. Another use would be for recording events to a console or hard-copy device for auditing. (Note that console logging is controlled by the configuration files .C /etc/nettlgen.conf and .CR /var/adm/conslog.opts ; see .IR nettlgen.conf (4).) The .C -F option is not allowed when the input file is redirected. .RE .PP The following options are not supported by all subsystems. If a subsystem does not support an option, that option is ignored during formatting of data from that subsystem. Consult the product documentation of the subsystem for information regarding the support of these options. .RS .TP 15 .C -v Enables output of verbose information. This includes additional cause and action text with formatted output. This information describes the possible cause of the message and any actions that may be required by the subsystem. After the contents of the input file have been formatted a summary of the file is displayed. When this option is used with the .C -t option, only a summary of the last .I records is reported. No summary is produced when this option is used in conjunction with the .C -F option or if formatting is interrupted. .TP .C -l .RI ( ell ) Turn off inverse video highlighting of certain traced fields. Use this flag when sending formatted trace data to a line printer. By default, certain fields in the trace file are highlighted in inverse video when viewing the formatted trace format at a terminal that supports highlighting. .TP .C -n Shows port numbers and network addresses(such as IP and x121) as numbers (normally, .C netfmt interprets numbers and attempts to display them symbolically). .TP .C -N Enables ``nice'' formatting where Ethernet/\s-1IEEE802.3\s0, .SM SLIP, IP, ICMP, IGMP, TCP, UDP, ARP, Probe, and .SM RPC packets are displayed symbolically. All remaining user data is formatted in hexadecimal and .SM ASCII. .TP .C -1 .I (one) Attempts to tersely format each traced packet on a single line. If .C -L and/or .C -T options are used, the output lines will be more than 80 characters long. .TP .C -T Places a time stamp on terse tracing output. Used with the .C -1 .RI ( "minus one" ) option. .TP .C -L Prefixes local link address information to terse tracing output. Used with the .C -1 .RI ( "minus one" ) option. .SS Filter Configuration File .B Note: Filter configuration file syntax converges the syntax used with the obsolete .C nettrfmt network trace formatter and .C netlogfmt network log formatter commands with new .C netfmt syntax for controlling formatter options. The first section below describes the general use and syntax of the filter configuration file. Specific options for subsystem Naming and Filtering are listed in the .I Subsystem Filtering section below. .PP The filter configuration file allows specification of two types of information: .RS .TP 3 \(bu Specify options in order to control how the input data is to be formatted. These options determine what the output looks like and allow a user to select the best format to suit their needs. .TP \(bu Specify filters in order to precisely tailor what input data is to be discarded and what is to be formatted. .B Global filters control all subsystems; .B subsystem filters pertain only to specific subsystems. .RE .PP A filter is compared against values in the input data. If the data matches a filter, the data is formatted; otherwise, the input data is discarded. A filter can also specify .SM .I NOT by using .C ! before the filter value in the configuration file. If the input data matches a .SM .I NOT filter, it is discarded. A filter can also be a ``wild-card'' (matching any value) by specifying an asterisk .C * before the filter value in the configuration file. ``Wild card'' filters pass all values of the input data. Specifying .C !* as the filter means .SM .IR "NOT ALL" . .SS Filter Configuration File Syntax .TP 3 \(bu The formatter ignores white space, such as spaces or tabs. However, newlines (end of line characters) are important, as they terminate comments and filter specifications. .TP \(bu The formatter is not case sensitive. For example .C error and .C ERROR are treated as equivalent. .TP \(bu To place comments in the file, begin each comment line with a .C # character. The formatter ignores all remaining characters on that line. There are no inline comments allowed. .TP \(bu An exclamation point .RC ( ! ) in front of an argument indicates .SM .IR NOT . This operator is not supported for timestamp, log instance, and .SM ID filtering. .TP \(bu The asterisk .RC ( * ), when used as an argument, indicates .SM .IR ALL . Since the default for all formatting options is .SM .IR ALL , it is unnecessary to use the asterisk alone. It can be used along with the exclamation point, .RC ( !* ) to indicate .SM .IR "NOT ALL" . This operator is not available for timestamp, log instance, and .SM ID filtering. .PP .B Global Filtering: .br Global filtering commands start with the word .CR formatter , followed by the keywords .CR verbosity , .CR mode , .CR option , or .CR filter . .RS .TP 3 \(bu .C formatter verbosity .IR value , .I value should be either of .RS .TP 7 .C high Enables output of netfmt internal debugging information to standard error. Same as the .C -v option. .TP .C low No internal debugging information is to be displayed. .RE .TP 3 \(bu .C formatter mode .IR value , .I value should be one of .RS .TP 7 .C raw Dumps out the messages in hex format. .TP 7 .C nice Enables "nice" formatting. Same as .C -N option. .TP 7 .C terse Attempts to tersely format each traced packet on a single line. Same as .C -1 .RI ( "minus one" ) option. .TP 7 .C normal Normal formatting. .RE .TP 3 \(bu .C formatter option .RC [ ! ] .IR value , .I value should be .RS .TP .C suppress Normally repeated lines in hex output are condensed into a single line and a message stating that redundant lines have been skipped is displayed. Specifying .C !suppress will print all redundant data. This is useful when the formatted output is used as input into other commands. .RE .RS .TP .C highlight Normally the formatter will highlight certain fields in its trace output in inverse video. Specifying .C !highlight will turn this feature off. Same as the .C -l \s .RI ( "minus ell" ) option. .RE .TP \(bu .C formatter filter .I type .RC [ \|!\| ] .IR value\|\ \(or .C * .RS .TP Six .I types of filtering are provided: .RS .TP 20 .C class log classes .PD 0 .TP .C kind trace kinds .TP .C id connection, process, path, and user .TP .C log instance specific thread of events .TP .C subsystem subsystem names .TP .C time specify ranges of time(s) .TP The following combinations are recognized: .TP 5 .CR "formatter filter class" " \f2value\fP [\f2subsystem\fP]" .I value indicates the log class. This option allows the user to select one or more classes to be formatted. Initially all log classes are formatted. Only one class is allowed per line. Classes in multiple lines are logically ``OR''ed. The optional .I subsystem name sets the class filter only for the specified subsystem. The log classes are: .RS .TP 18 .C INFORMATIVE Describes routine operations and current system values. .TP .C WARNING Indicates abnormal events possibly caused by subsystem problems. .TP .C ERROR Signals an event or condition which was .I not affecting the overall subsystem or network operation, but may have caused an application program to fail. .TP .C DISASTER Signals an event or condition which .I did affect the overall subsystem or network operation, caused several programs to fail or the entire node to shut down. .RE .TP .CI "formatter filter Connection_ID"\|\ value .PD 0 .TP .CI "formatter filter Device_ID"\|\ value .TP .CI "formatter filter Path_ID"\|\ value .TP .CI "formatter filter Process_ID"\|\ value .TP .CI "formatter filter User_ID"\|\ value .I value specifies the .SM ID number of the messages to format. Last-entered value has precedence over any previous ones. See the record header in the formatted output to determine which ID numbers to filter on. The .C ! operator is .I not allowed in .PD .IR value . .TP .CR "formatter filter kind" " \f2value\fP [\f2subsystem\fP]" .I value can either be an established trace kind or a mask. A mask is a hexadecimal representation of a (set of) trace kind(s). Masks in multiple lines are logically ``OR''ed. The optional .I subsystem name sets the kind filter only for the specified subsystem. Trace kinds and their corresponding masks are: .TS center tab(;); lB cB cw(.4i) lB cB lf4p+1 c c lf4p+1 c. Name;Mask;\&;Name;Mask _ hdrin;0x80000000;\&;state;0x04000000; hdrout;0x40000000;\&;error;0x02000000; pduin;0x20000000;\&;logging;0x01000000; pduout;0x10000000;\&;loopback;0x00800000 proc;0x08000000;\&; .TE .RS .TP 12 .C hdrin Inbound Protocol Header. .TP .C hdrout Outbound Protocol Header. .TP .C pduin Inbound Protocol Data Unit (including header and data). .TP .C pduout Outbound Protocol Data Unit (including header and data). .TP .C proc Procedure entry and exit. .TP .C state Protocol or connection states. .TP .C error Invalid events or condition. .TP .C logging Special kind of trace that contains a log message. .TP .C loopback Packets whose source and destination system is the same. .RE .TP .CI "formatter filter log_instance"\|\ value .I value specifies the log instance number of the messages to filter. Selecting a log instance allows the user to see the messages from a single thread of network events. Only one log instance is allowed per filter configuration file. The log instance can not be negated with the .C ! operator. .TP .CI "formatter filter subsystem"\|\ value .I value specifies the subsystem name. Available subsystem names can be listed by using the command: .RS .IP .C nettlconf -status .RE .IP Only one subsystem name is allowed per line; multiple lines ``OR'' the request. To eliminate a given subsystem name, use the .C ! operator, which formats all subsystems except those excluded by the list of negated subsystems. To include all subsystems (the default), use the .C * operator. To eliminate all subsystems, use the .C !* operator. .TP .CI "formatter filter time_from"\|\ value .PD 0 .TP .CI "formatter filter time_through"\|\ value .C time_from indicates the inclusive starting time. .C time_through indicates the inclusive ending time. .I value consists of .I time_of_day and optionally .IR day_of_year , (usually separated by one or more blanks for readability). .PD .IP .I time_of_day specifies the time on the 24-hour clock in hours, minutes, seconds and decimal parts of a second (resolution is to the nearest microsecond). Hours, minutes and seconds are required; fractional seconds are optional. .I time_of_day format is .IC hh : mm : ss .\c .IR dddddd . .IP .I day_of_year specifies the day of the year in the form month/day/year in the format: .IC mm / dd / yy\f1. Specify month and day numerically, using one or two digits. For example, January can be specified as .C 1 or .CR 01 ; the third day of the month as .C 3 or .CR 03 . Specify the year by its last two digits. For example, specify 1993 as .CR 93 . .I day_of_year is an optional field; the current date is used as a default. .IP The .C time_from specification includes .I only those records starting from the resolution of time given. For example, if the .I time_of_day for .C time_from is specified as 10:08:00, all times before that, from 10:07:59.999999 and earlier, are excluded from the formatted output. Records with times of 10:08:00.000000 and later are included in the formatted output. Similarly, the .C time_through specification includes .I only up to the resolution of time given. For example, if the .I time_of_day for .C time_through is specified as 10:08:00, all records with times after that, from 10:08:00.000001 onward, are excluded from the formatted output. .RE .RE .SS Subsystem Filtering .B Note: Global filtering described above takes precedence over individual subsystem tracing and logging filtering described below. .PP Subsystem filters are provided to allow filtering of data for individual subsystems or groups of subsystems. Their behavior varies among individual subsystems. Subsystem filters are valid only when the corresponding subsystems have been installed and configured on the system. See the subsystem documentation for a description of supported subsystem filters and their behavior. .PP Subsystem filtering commands start with the name of the subsystem followed by the subsystem filter keywords. However, to provide convenience and backwards compatibility, several other filter keywords are provided for the group of LAN subsystems: .CR "NAME " and " FILTER" . Currently, four types of subsystem filters are provided: .SM LAN, .SM X25, .SM STREAMS, and .SM OTS. The collection of .SM LAN subsystems use the subsystem filters identified by the .C FILTER and .C NAME keywords and the collection of .SM OTS subsystems use the subsystem filters with the .C OTS keyword. The collection of .SM X25 subsystems start their filter commands with the X25 subsystem names. .RE .SS LAN Naming and Filtering LAN naming can be used to symbolically represent numbers with more recognizable labels. .RS .TP 5 .CI "name " "nodename value" .I nodename is a character string to be displayed in place of all occurrences of .IR value . .I value is a (IEEE802.3/Ethernet) hardware address consisting of 6 bytes specified in hexadecimal (without leading "0x"), optionally separated by .CR - . .C netfmt substitutes all occurrences of .I value with .I nodename in the formatted output. The mapping is disabled when the .C -n option is used. This option applies to tracing output only. .RE .PP LAN filtering is used to selectively format packets from the input file. There are numerous filter types, each associated with a particular protocol layer: .RS .PP .TS tab(;); cB cB cB l lf4p+1 l. Filter Layer;Filter Type;Description _ Layer 1;dest;hardware destination address \&;source;hardware source address \&;interface;software network interface _ Layer 2;ssap;IEEE802.2 source sap \&;dsap;IEEE802.2 destination sap \&;type;Ethernet type _ Layer 3;ip_saddr;\s-1IP\s0 source address \&;ip_daddr;\s-1IP\s0 destination address \&;ip_proto;\s-1IP\s0 protocol number _ Layer 4;tcp_sport;\s-1TCP\s0 source port \&;tcp_dport;\s-1TCP\s0 destination port \&;udp_sport;\s-1UDP\s0 source port \&;udp_dport;\s-1UDP\s0 destination port \&;connection;a level 4 \s-1(TCP, UDP)\s0 connection _ Layer 5;rpcprogram;\s-1RPC\s0 program \&;rpcprocedure;\s-1RPC\s0 procedure \&;rpcdirection;\s-1RPC\s0 call or reply .TE .RE .PP Filtering occurs at each of the five layers. If a packet matches any filter within a layer, it is passed up to the next layer. The packet must pass every layer to pass through the entire filter. Filtering starts with Layer 1 and ends with Layer 5. If no filter is specified for a particular layer, that layer is ``open'' and all packets pass through. For a packet to make it through a filter layer which has a filter specified, it must match the filter. Filters at each layer are logically ``OR''ed. Filters between layers are logically ``AND''ed. .PP LAN trace and log filters use the following format: .RS .TP 5 .CR "filter " "\f2type\fP [" ! "] \f2value\fP \(or " * .C filter is the keyword identifying the filter as a .SM LAN subsystem filter. .RE .PP The following filters are available for LAN tracing. .RS .TP 5 .CI "filter connection"\|\ value .I value takes the form: .RS .IP .IC local_addr : "port remote_addr" : port .RE .IP where .I local_addr and .I remote_addr can be a hostname or a 4-byte Internet address specified in decimal dot notation (see .IR inet (3N) for more information on Internet addresses and decimal dot notations). .I port can be a service name or an .IR integer . .I integer represents a port and can be designated by a hexadecimal integer .RC ( 0x \f2digits\fP), an octal integer .RC ( 0 \f2digits\fP), or base-10 integers (0 through 65\|535). .TP .CI "filter dest"\|\ value .PD 0 .TP .CI "filter source"\|\ value .I value is a hardware address consisting of 6 bytes specified in hexadecimal (without leading .CR 0x ), optionally separated by .CR - . .PD .TP .CI "filter dsap"\|\ value .PD 0 .TP .CI "filter ssap"\|\ value .I value is a hexadecimal integer of the form: .CR 0x \f2digit\fP; an octal integer of the form: .CR 0 \f2digits\fP; or a base-ten integer, 0 through 255. .PD .TP .CI "filter interface"\|\ value .I value identifies a network interface and takes the form: .CI lan n for .SM LAN interface, or .CI lo n for loopback interface, where .I n is the logical unit number, as in .CR lan0 . .TP .CI "filter ip_daddr"\|\ value .PD 0 .TP .CI "filter ip_saddr"\|\ value .I value is a hostname or a 4-byte Internet address specified in decimal dot notation (see .IR inet (3N) for more information on Internet addresses and decimal dot notations). .PD .TP .CI "filter ip_proto"\|\ value .I value is a hexadecimal integer of the form: .CR 0x \f2digit\fP; an octal integer of the form: .CR 0 \f2digits\fP; or a base-ten integer, 0 through 255 (see .IR protocols (4) for more information on protocol numbers). .PD .TP .CI "filter tcp_dport"\|\ value .PD 0 .TP .CI "filter tcp_sport"\|\ value .TP .CI "filter udp_dport"\|\ value .TP .CI "filter udp_sport"\|\ value .I value is a port number designated as a 2-byte integer value or a service name. The integer value can be designated by a hexadecimal integer .RC ( 0x \f2digits\fP), an octal integer .RC ( 0 \f2digits\fP), or a base-10 integer (0 through 65\|535). .PD .TP .CI "filter rpcprogram"\|\ value .I value is a RPC program name or an integer RPC program number (see .IR rpc (4) for more information on RPC program names). The integer value can be designated by a hexadecimal integer .RC ( 0x \f2digits\fP), an octal integer .RC ( 0 \f2digits\fP), or a base-10 integer (0 through 65\|535). .PD .TP .CI "filter rpcprocedure"\|\ value .I value is an integer RPC procedure number. The integer value can be designated by a hexadecimal integer .RC ( 0x \f2digits\fP), an octal integer .RC ( 0 \f2digits\fP), or a base-10 integer (0 through 65\|535). .PD .TP .CI "filter rpcdirection"\|\ value .I value can be either .CR call\|\ or .CR reply . .PD .TP .CI "filter type"\|\ value .I value is a hexadecimal integer of the form: .CR 0x \f2digits\fP; an octal integer of the form: .CR 0 \f2digits\fP; or a base-ten integer (0 through 65\|535). .PD .RE .PP LAN log filtering command has the following form: .RS .TP .CI "filter subsystem"\|\ value .I value takes the form: .RS .IP .IC "subsys_name " event " event_list" .RE .IP where .I subsys_name is a subsystem name obtained using the .C nettlconf -status command or one of the following abbreviations: .nf .IP .C " axin bufs caselib caserouter" .C " ip ipc lan loopback" .C " netisr nfs nft ni" .C " nsdiag nse probe pxp" .C " rlbdaemon sockregd strlog tcp" .C " timod tirdwr udp " .fi .IP .I event_list takes the form: .RS .IP .I event_spec .RC [ \|,\c .IR event_spec .\|.\|.\|]" .RE .IP where .I event_spec takes one of the three forms: .RS .IP .RC [ ! ]\c .I integer \h'1i' .RC [ ! ]\c .I range \h'1i' .RC [ ! ]\c .C * .RE .IP .I integer is an integer in hexadecimal (leading .CR 0x ), octal (leading .CR 0 ), or decimal, which specifies a log event for the subsystem indicated. .IP .I range takes the form .IC integer - integer\c , and indicates an inclusive set of events. .RE .SS X25 Naming and Filtering The X25 product provides capabilities to assign symbolic names to important numbers and to filter log events and trace messages. See .IR x25log (1M) and .IR x25trace (1M) for more information about X25 naming and filtering. .SS OTS Filtering The .SM OTS subsystem filter allows filtering of the message .SM ID numbers that are typically found in the data portion of an .SM OTS subsystem's log or trace record. The .SM OTS subsystem filter is effective for any subsystem that is a member of the .SM OTS subsystem group. .PP .SM OTS trace filtering configuration commands have the following form in .IR config_file : .IP .C OTS .RI [ \|subsystem\| ] .C msgid .RC [ ! ] .I message_ID \(or .C * .PP Keywords and arguments are interpreted as follows: .RS .TP 15 .C OTS Identifies the filter as an .SM OTS subsystem filter. .TP .I subsystem One of the following group of .SM OTS subsystems: .nf .IP .C " OTS ACSE_PRES NETWORK" .C " TRANSPORT SESSION" .fi .IP .B Note: The absence of .I subsystem implies that the filter applies to all .SM OTS subsystems. .TP .I message_ID is the value of the message .SM ID to filter. A message .SM ID is used by .SM OTS subsystems to identify similar types of information. It can be recognized as a 4 digit number contained in brackets .RC ( [ .CR ] ) at the beginning of an .SM OTS subsystem's trace or log record. Initially all .IR message_ID s are enabled for formatting. To format records with specific .IR message_ID s, turn off all message .SM ID\c s using the .C !* operator, then selectively enable the desired message .SM ID\c s. Only one .I message_ID is allowed on each line. Multiple lines are ``OR''ed together. .RE .sp .SS STREAMS Filtering The STREAMS subsystem filter allows filtering on some fields of the messages logged by STREAMS modules and drivers. See .IR strlog (7) for more information. .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported in data. Single-byte character codesets are supported in filenames. .SH DEPENDENCIES .C netfmt only recognizes subsystems and filters from products which have been installed and configured. .SH WARNINGS The syntax that was used for the obsolete .SM LAN trace and log options has been mixed with the syntax for the .C netfmt command such that any old options files can be used without any changes. The combination of syntax introduces some redundancy and possible confusion. The global filtering options have the string .C formatter filter as the first two fields, while the .SM LAN filtering options merely have the string .C filter as the first field. It is expected that the older .SM LAN filtering options may change to become more congruent with the global filtering syntax in future releases. .PP The .C nettl and .C netfmt commands read the .C /etc/nettlgen.conf file each time they are executed. These commands will not operate if the file becomes corrupted (see .IR nettl (1M) and .IR netfmt (1M)). .SH DIAGNOSTICS Messages describe illegal use of .C netfmt command and unexpected .SM EOF encountered. .SH EXAMPLES The first group of examples show how to use command line options. .RS .TP 4 1. Format the last 50 records in file .C /var/adm/nettl.LOG00 (the default log file): .RS .IP .C "netfmt -t 50 -f /var/adm/nettl.LOG00" .RE .TP 2. Use the follow option to send .I all log messages to the console (normally, only .C DISASTER\c -class log messages are sent to the console in console form): .RS .IP .C "netfmt -f /var/adm/nettl.LOG00 -F > /dev/console" .RE .TP 3. Monitor all log messages in a .C hpterm window: .RS .IP .C "hpterm -e /usr/sbin/netfmt -F -f /var/adm/nettl.LOG00" .RE .TP 4. Read file .C /var/adm/trace.TRC1 for binary data and use .C conf.file as the filter configuration file: .RS .IP .C "netfmt -c conf.file -f /var/adm/trace.TRC1" .RE .RE .PP The remaining examples show how to specify entries in the filter configuration file used with the .C -c option. .RS .TP 4 1. Tell .C netfmt to format only .C INFORMATIVE\c -class log messages coming from the .C NS_LS_IP subsystem between 10:31:53 and 10:41:00 on 23 November 1993. .RS .nf .IP .C "formatter filter time_from 10:31:53 11/23/93" .C "formatter filter time_through 10:41:00 11/23/93" .C "formatter filter class !*" .C "formatter filter class INFORMATIVE" .C "formatter filter subsystem !*" .C "formatter filter subsystem NS_LS_IP" .fi .RE .TP 2. Map hardware address to name(LAN): .RS .nf .IP .C "name node1 08-00-09-00-0e-ca" .C "name node3 02-60-8c-01-33-58" .fi .RE .TP 3. Format only packets from either of the above hardware addresses: .RS .nf .IP .C "filter source 08-00-09-00-0e-ca" .C "filter source 02-60-8c-01-33-58" .fi .RE .TP 4. Format all packets transmitted from the local node, .CR local , to the remote node, .CR 192.6.1.3 , which reference local .SM TCP service ports .C login or .CR shell , or remote .SM UDP port .CR 777 : .RS .nf .IP .C "filter ip_saddr local" .C "filter ip_daddr 192.6.1.3" .C "filter tcp_sport login" .C "filter tcp_sport shell" .C "filter udp_dport 777" .fi .RE .TP 5. Format a .SM TCP connection from local node .C node2 to .C 192.6.1.3 which uses .C node2 service port .C ftp and remote port .CR 1198 . .RS .nf .IP .C "filter connection node2:ftp 192.6.1.3:1198" .fi .RE .TP 6. Format all packets except those that use interface .CR lan0 : .RS .nf .IP .C "filter interface ! lan0" .fi .RE .TP 7. Format all logged events for subsystem .CR ip . No other events are formatted. (By default, all events are formatted): .RS .nf .IP .C "filter subsystem ip event *" .fi .RE .TP 8. Format only event .C 5003 for subsystem .CR ip . Format all events except .C 3000 for subsystem .CR tcp . No other events are formatted. .RS .nf .IP .C "filter subsystem ip event 5003" .C "filter subsystem tcp event *,!3000" .fi .RE .TP 9. Format only events .CR 5003 , .CR 5004 , .CR 5005 , and .C 5006 for subsystem .CR ip . Format all events except events .CR 3000 , .CR 3002 , and .C 3003 for subsystem .CR tcp . No other events are formatted: .RS .nf .IP .C "filter subsystem ip event 5003-5006" .C "filter subsystem tcp event *,!3000,!3002-3003" .fi .RE .TP 10. Format only those records containing message .SM ID\c s .C 9973 and .C 9974 for subsystem .C session and those not containing message .SM ID .C 9974 for subsystem .CR transport . All records from other subsystems are formatted: .RS .nf .IP .C "ots session msgid !*" .C "ots session msgid 9973" .C "ots session msgid 9974" .C "ots transport msgid !9974" .fi .RE .TP 11. Combine .SM LAN and general filtering options into one configuration file. Format 15 minutes of pduin and pduout data starting at 3:00 PM on 2 April 1990 for data from .C lan0 interface. .RS .nf .IP .C "formatter filter kind 0x30000000" .C "formatter filter time_from 15:00:00 04/02/90" .C "formatter filter time_through 15:15:00 04/02/90" .C "filter interface !*" .C "filter interface lan0" .fi .RE .SH FILES .TP 20 .C /etc/nettlgen.conf default subsystem configuration file .TP .C /var/adm/conslog.opts default console logging options filter file .TP .C $HOME/.netfmtrc default filter configuration file if the .CI \|\-c\|\ config_file option is not used on the command line. .SH SEE ALSO nettl(1M), nettlconf(1M), nettlgen.conf(4), strlog(7). .SH AUTHOR .C netfmt was developed by HP. .\" .\" index@\f4netfmt\f1 \- format tracing and logging binary files@@@\f3netfmt(1M)\f1 .\" index@\f1format tracing and logging binary files@@@\f3netfmt(1M)\f1 .\" index@\f1tracing and logging binary files, format@@@\f3netfmt(1M)\f1 .\" index@\f1logging and tracing binary files, format@@@\f3netfmt(1M)\f1 .\" index@\f1binary files, format tracing and logging@@@\f3netfmt(1M)\f1 .\" index@\f1files: format tracing and logging binary files@@@\f3netfmt(1M)\f1 .\" .\" toc@\f3netfmt(1M)\f1:\0\0\f4netfmt\f1@@@format tracing and logging binary files .\" .\" $Header: nettl.1m,v 72.4 94/10/17 11:32:15 ssa Exp $ .TA n .TH nettl 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nettl \- control network tracing and logging .SH SYNOPSIS .CR /usr/sbin/nettl .CR \-start .PP .CR /usr/sbin/nettl .CR \-stop .PP .CR /usr/sbin/nettl .CR \-firmlog .CR 0 \(or 1 \(or 2 .CR \-card .IR dev_name .RI ...\& .PP .CR /usr/sbin/nettl .CR \-log .IR class .RI ...\& .CI \-entity .IR subsystem .RI ...\& .PP .CR /usr/sbin/nettl .CR \-status .RC [ log .RC \(or trace .RC \(or all ] .PP .CR /usr/sbin/nettl .CR \-traceon .IR kind .RI ...\& .CR \-entity .IR subsystem .RI ...\& .ifn .br .ifn \0\0\0\0 .RC [ \-card .IR dev_name .RI ...\&] .ift .br .ift \0\0\0\0 .RC [ \-file .IR tracename ] .RC [ \-m .IR bytes ] .RC [ \-size .IR portsize ] .ifn .br .ifn \0\0\0\0 .RC [ \-tracemax .IR maxsize ] .PP .CR /usr/sbin/nettl .CR \-traceoff .CR \-entity .I subsystem .RI ...\& .SH DESCRIPTION The .CR nettl command is a tool used to capture network events or packets. Logging is a means of capturing network activities such as state changes, errors, and connection establishment. Tracing is used to capture or take a snapshot of inbound and outbound packets going through the network, as well as loopback or header information. A subsystem is a particular network module that can be acted upon, such as .CR ns_ls_driver , or .CR X25L2 . .CR nettl is used to control the network tracing and logging facility. .PP Except for the .CR \-status option, .CR nettl can be used only by users who have an effective user ID of 0. .SS Options .CR nettl recognizes the following options, which can be used only in the combinations indicated in SYNOPSIS. Some option and argument keywords can be abbreviated as described below. All keywords are case-insensitive. .TP 15 .CR \-start .RC (Abbr.: \0\-st ) .br Used alone without other options. .IP Initialize the tracing and logging facility, start up default logging, and optionally start up console logging. Logging is enabled for .I all subsystems as determined by the .CR /etc/nettlgen.conf file. Log messages are sent to a log file whose name is determined by adding the suffix .CR .LOG00 to the log file name specified in the .CR /etc/nettlgen.conf configuration file. Console logging is started if console logging has been configured in the .CR /etc/nettlgen.conf file. See .IR nettlconf (1M) and .IR nettlgen.conf (4) for an explanation of the configuration file. If the log file (with suffix) already exists, it is opened in .I append mode; that is, new data is added to the file. The default name is .CR /var/adm/nettl (thus logging starts to file .CR /var/adm/nettl.LOG00 ). See "Data File Management" below for more information on how the log file is handled. .IP A .CR "nettl\ \-start" command is performed during system startup if the .CR NETTL variable in the .CR /etc/rc.config.d/nettl file has a value of .CR 1 . .IP .B Note: It is strongly recommended that the tracing and logging facility be turned on before any networking is started and remain on as long as networking is being used. Otherwise, information about disasters will be lost. To minimize the impact on the system, all subsystems can be set with the .CR \-log option to capture only .CR disaster -class log messages. .TP .CR \-stop .RC (Abbr.: \0\-sp ) .br Used alone without other options. .IP Terminate the trace/log facility. Once this command is issued, the trace/log facility is no longer able to accept the corresponding trace/log calls from the network subsystems. .IP .B Note: See note for the .CR \-start option. .TP .CI \-card \0dev_name\f1\0...\& .RC (Abbr.: \0\-c ) .\"This option applies to .\"X.25 .\"subsystems only, for setting up tracing. .\"For other subsystems, this option is .\"ignored and a warning message is issued. .\"Only one .\"X.25 .\"card can be traced at a time. .br This option is required by the X.25 subsystems; it is optional for other subsystems. Some subsystems do not support this option. .IP Limit the trace information gathered to only the data that comes from the specified network interface card. More than one .I dev_name can be specified at a time in order to trace multiple network interfaces. .IP .I dev_name specifies a device which corresponds to a network interface card that has been installed and configured. It can be either an integer representing the network interface, or the device file name of the network interface. Some subsystems do not support both types of .IR dev_name . For example, the X25 subsystems require that .I dev_name be a device file name. The product documentation for the subsystems should explain if the .CR \-card option is applicable and how to choose an appropriate .IR dev_name . .IP If .I dev_name is not an integer it is assumed to be a device file name. The path prefix .CR /dev/ will be attached in front of .I dev_name if it is not an absolute path name to form the device file name, .CI /dev/ dev_name. .I dev_name must refer to a valid network device file. .TP .PD 0 .CR \-entity\ all .TP .CI \-entity \0subsystem\f1\0...\& .PD .RC (Abbr.: \0\-e ) .IP Limit the action of .CR \-log , .CR \-traceoff , or .CR \-traceon to the specified protocol layers or software modules specified by .IR subsystem . .IP The number and names of .IR subsystem s on each system are dependent on the products that have been installed. Use the command .CR nettlconf\ \-status to obtain a full listing of supported subsystems and the products that own them. .IP Examples of OSI subsystems: .RS .nf .IP .C "acse_pres ftam_init mms" .C "asn1 ftam_resp network" .C "cm ftam_vfs ots" .C "em ftp_ftam_gw transport" .C "ftam_ftp_gw hps ula_utils" .fi .RE .IP Examples of LAN subsystems: .RS .nf .IP .C "ns_ls_driver ns_ls_loopback ns_ls_ni" .C "ns_ls_icmp ns_ls_netisr ns_ls_tcp" .C "ns_ls_igmp ns_ls_nfs ns_ls_udp" .C "ns_ls_ip ns_ls_nft ns_ls_x25" .fi .RE .IP Two X.25-specific subsystems are used for tracing only: .RS .IP .C "X25L2 X25L3" .RE .TP .CI \-file \0tracename .RC (Abbr.: \0\-f ) .br Used with the first .CR \-traceon option only. .IP The first time the .CR \-traceon keyword is used, it initializes tracing, creating a file .IC tracename .TRC0 which receives the binary tracing data. If a trace file of the name .IC tracename .TRC0 already exists the binary trace data is appended to the end of the file. .IP To start a fresh trace file, first turn off tracing then turn it back on again using a different .IR tracename . See "Data File Management" below for more information on file naming. .IP If .CR \-file is omitted, .I binary trace output goes to standard output. If standard output is a terminal device, an error message is issued and no tracing is generated. .TP .CR \-firmlog\00 \(or 1 \(or 2 .RC (Abbr.: \0\-fm ) .\" This does not apply to Series 700 systems .br Requires the .CR \-card option. .br Series 800 and X.25 only. .IP Set the X.25/800 interface card logging mask to level 0, 1, or 2. The default level is 0. The X.25/800 interface logs a standard set of messages. A level of 1 specifies cautionary messages as well as the default messages. A level of 2 specifies information messages in addition to the cautionary and default messages. This option is recognized only by the .CR ns_ls_x25 subsystem. .TP .CI \-log \0class\f1\0...\& .RC (Abbr.: \0\-l ) .br Requires the .CR \-entity option. .IP Control the class of log messages that are enabled for the subsystems specified by the .CR \-entity option. .IP .I class specifies the logging class. Available classes are: .RS .IP .ift .sp -1v .TS tab(;); cB cB cB lf4p+1 cf4p+1 c . Full;Abbr.;Mask _ informative;i;1 warning;w;2 error;e;4 disaster;d;8 .TE .RS .TP 20 .CR informative Describes routine operations and current system values. .TP .CR warning Indicates abnormal events possibly caused by subsystem problems. .TP .CR error Signals an event or condition which was .I not affecting the overall subsystem or network operation, but may have caused an application program to fail. .TP .CR disaster Signals an event or condition which .I did affect the overall subsystem or network operation, caused several programs to fail or the entire node to shut down. .RE .RE .IP Classes can be specified as keywords or as a single numeric mask depicting which classes to log. The mask is formed by adding the individual masks of the log classes. If you choose to indicate several classes at once, be sure to separate each log class with a space. .IP .CR disaster logging is always on. The default logging classes for each subsystem is configured into the configuration file, .CR /etc/nettlgen.conf . When the tracing/logging facility is started, the information in the configuration file is read and subsystems are enabled for logging with the specified classes. To change the log class, use the "\c .CI "nettl\ \-log\ " class "\ \-entity\ " subsystem\c " command with a new log class value. If desired, the command can be run for different log classes and different entities. .TP .CI \-m \0bytes Specify the number of bytes .RI ( bytes ) of each trace record to trace. This option allows the user to specify the number of bytes to be captured in the trace packet. The user may prefer not to capture an entire PDU trace, such as when the user is only interested in the header. .IP The maximum value for .I bytes is 2000. By default, the entire packet is traced. A value of 0 will also cause the entire packet to be traced. This option currently applies only to kernel subsystems. .TP .CI \-size \0portsize .RC (Abbr.: \0\-s ) .br Used with first .C \-traceon option only. .IP Set the size in kilobytes (KB) of the trace buffer used to hold trace messages until they are written to the file. The default size for this buffer is 68 KB. The possible range for .I portsize is 1 to 1024. Setting this value too low increases the possibility of dropped trace messages from fast subsystems. .TP .PD 0 .CR \-status\0log .TP .CR \-status\0trace .TP .CR \-status \0[ all ] .PD .RC (Abbr.: \0\-ss ) .br Used alone without other options. .IP Report the tracing and logging facility status. The facility must be operational, that is, .CR nettl\ \-start has been completed. The additional options define the type of trace or log information that is to be displayed. The default value is .CR all . .RS .RS .TP 10 .CR log Log status information .TP .CR trace Trace status information .TP .CR all Trace and log status information .RE .RE .TP .CI \-tracemax \0maxsize .RC (Abbr.: \0\-tm ) .br Used with first .CR \-traceon option only. .IP Tracing uses a circular file method such that when one file fills up, a second is used. Two trace files can exist on a system at any given time. See "Data File Management" below for more information on file behavior. .IP .I maxsize specifies the maximum size in kilobytes (KB) of both trace files combined. The default value for the combined file sizes is 1000 KB. The possible range for .I maxsize is 100 to 99999. .TP .CI \-traceoff .RC (Abbr.: \0\-tf ) .br Requires the .CR \-entity option. .IP Disable tracing of .IR subsystem s specified by the .CR \-entity option. If .CR all is specified as an argument to the .CR \-entity option, all tracing is disabled. The trace file remains, and can be formatted by using the .CR netfmt command to view the trace messages it contains (see .IR netfmt (1M)). .TP .PD 0 .CR \-traceon\0all .TP .CI \-traceon \0kind\f1\0...\& .PD .RC (Abbr.: \0\-tn ) .br Requires the .C \-entity option. The .C \-card option is required for X.25 subsystems. Other options are not required. .IP Start tracing on the specified subsystems. The tracing and logging facility must have been initialized by .CR nettl\ \-start for this command to have any effect. The default trace file is standard output; it can be overridden by the .CR \-file option. If standard output is a terminal device, then an informative message is displayed and no trace data is produced. .IP When tracing is enabled, every operation through the subsystems is recorded if the .I kind mask is matched. .IP .I kind defines the trace masks used by the tracing facility before recording a message. If .CR \-traceon\ all is specified, all trace masks are enabled. .I kind can be entered as one or several of the following keywords or masks: .RS .ift .sp -1v .IP .TS tab(;); cB cB cw(.4i) cB cB lf4p+1 lf4p+1 c lf4p+1 lf4p+1. keyword;mask;\&;keyword;mask _;_;\&;_;_ hdrin;0x80000000;\&;state;0x04000000 hdrout;0x40000000;\&;error;0x02000000 pduin;0x20000000;\&;logging;0x01000000 pduout;0x10000000;\&;loopback;0x00800000 proc;0x08000000;\&; .TE .RS .TP 15 .CR hdrin Inbound Protocol Header. .TP .CR hdrout Outbound Protocol Header. .TP .CR pduin Inbound Protocol Data Unit (including header and data). .TP .CR pduout Outbound Protocol Data Unit (including header and data). .TP .CR proc Procedure entry and exit. .TP .CR state Protocol or connection states. .TP .CR error Invalid events or condition. .TP .CR logging Special kind of trace that contains a log message. .TP .CR loopback Packets whose source and destination system is the same. .RE .RE .IP For multiple .IR kind s, the masks can be specified separately or combined into a single number. For example, to enable both .CR pduin and .CR pduout (to trace all packets coming into and out of the node) use either .CR pduin\ pduout or .CR 0x10000000\ 0x20000000 or the combination .CR 0x30000000 . .IP Not all subsystems support all trace .IR kind s. .I No error is returned if a given subsystem does not support a particular trace .IR kind . .IP If a .CR \-traceon is issued on a subsystem that is already being traced, the tracing mask and optional values are changed to those specified by the new command, but the new .CR \-file , .CR \-size , and .CR \-tracemax options are ignored and a message is issued. .IP If .CR \-entity\ all is specified, all recognized subsystems are traced except X.25-specific subsystems. To turn on tracing for X.25, use the command .RS .IP .CR nettl .CR \-traceon .IR kind .C \-e .IR x.25_subsys .CI \-card .IR dev_name .RE .IP where the value of .IR x.25_subsys is .CR X25L2 or .CR X25L3 . .SS Data File Management Data files created by the tracing and logging facility require special handling by the facility that the user must be aware of. When files are created, they have the suffix .CR .LOG00 or .CR .TRC0 appended to them, depending on whether they are log or trace files, respectively. This scheme is used to keep the files distinct for cases where the user specifies the same name in both places. Also, the files implement a type of circular buffer, with new data always going into the file appended with .CR .LOG00 or .CR .TRC0 . When a file is full, it is renamed to the next higher number in its sequence; that is, .IC logname .LOG01 or .IC tracename .TRC1 and a new file named .IC logname .LOG00 or .IC tracename .TRC0 is created. Currently, only two generations of files are possible; thus, only two log files and two trace files can appear on the system simultaneously: .IC logname .LOG00 \f1, .IC logname .LOG01 \f1, .IC tracename .TRC0 \f1, and .IC tracename .TRC1 \f1. .IP .B Note: The file name prefix .RI ( logname or .IR tracename ) specified by the user must not exceed eight characters so that the file name plus suffix does not exceed fourteen characters. Longer names are truncated. To see the actual name of the trace or log file, use the .CR nettl\ \-status\ all command. .SS Console Logging Console logging is used to display significant log events on the system console. The values in the .CR /etc/nettlgen.conf file determine if console logging is to be started and the entries in the .CR /var/adm/conslog.opts file determine what log messages will be reported to the console. The .CR nettlconf command can be used to configure and maintain the information in the .CR /etc/nettlgen.conf file (see .IR nettlconf (1M)). If changes are made to these files, .CR nettl must be stopped and restarted for the new information to take effect. .PP All log messages written to the console as a result of this configuration information are in a special short form. If more information is desired on the console, the .CR netfmt formatter can be used to direct output to the console device. This may be most useful in an X windows environment. .PP Console logging may be disabled if conservation of system resources is valued more than notification of log events. .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multibyte character code sets are supported in data; single-byte character code sets are supported in file names. .SH EXAMPLES .TP 1. Initialize the tracing/logging facility: .RS .IP .C "nettl \-start" .IP (See note for the .CR \-start option.) .RE .TP 2. Display the status of the tracing/logging facility. .RS .IP .C "nettl \-status all" .RE .TP 3. Change log class to .CR error and .CR warning for all the subsystems. .CR disaster logging is always on for all subsystems. .RS .IP .C "nettl \-log e w \-e all" .RE .TP 4. Turn on inbound and outbound PDU tracing for the .CR transport and .CR session (OTS/9000) subsystems and send binary trace messages to file .CR /var/adm/trace.TRC0 . .RS .IP .C "nettl \-traceon pduin pduout \-entity transport session \e" .br .C " -file /var/adm/trace" .RE .TP 5. Turn on outbound PDU tracing for X.25 level two, and subsystem .CR ns_ls_ip . Trace messages go to the trace file set up in the previous example. This example also uses the abbreviated options. Tracing for X.25 requires a .CR \-card option to indicate which X.25 card to trace. .RS .IP .C "nettl \-tn pduout \-e X25L2 ns_ls_ip \-c x25_0" .RE .TP 6. Determine status of tracing from the previous two examples. .RS .IP .C "nettl \-status trace" .RE .IP The output should resemble the following: .RS .nf .IP .C "Tracing Information:" .C "Trace Filename: /var/adm/trace.TRC*" .C "Trace file size(Kbytes): 1000 .C "User's ID: 0 Buffer Size: 32768" .C "Messages Dropped: 0 Messages Queued: 0" .ift .sp .5v .ifn .sp 1v .C "Subsystem Name: Trace Mask: Card:" .C "TRANSPORT 0x30000000" .C "SESSION 0x30000000" .C "NS_LS_IP 0x10000000" .C "X25L2 0x10000000 x25_0" .fi .RE .TP 7. Stop tracing for all subsystems. .PD .RS .IP .C "nettl \-traceoff \-e all" .RE .TP 8. Enable .CR pduin and .CR pduout tracing for .CR ns_ls_driver (LAN driver) subsystem. Binary trace data goes to file .CR /var/adm/LAN.TRC0 . .IP The .CR \-file option of this command is only valid the first time tracing is called. The trace file is not automatically reset with the .CR \-file option. To change the trace output file, stop tracing and start up again. This example assumes that the .CR \-traceon option is being used for the first time. .RS .IP .C "nettl \-tn pduin pduout \-e ns_ls_driver \-file /var/adm/LAN" .RE .TP 9. Terminate the tracing and logging facility. .PD .RS .IP .C "nettl \-stop" .IP (See note for the .CR \-start option.) .RE .SH WARNINGS Although the .CR nettl command allows the specification of all log classes and all trace kinds for all subsystems, many subsystems do not support all log classes and all trace kinds. No error or warning will be issued if a subsystem does not support a log class or trace kind. Refer to the product documentation of the subsystem for information on supported log classes and trace kinds. .PP Tracing to a file that resides on a NFS file system can impact system performance and result in loss of trace data. It is recommended that NFS file systems not be used to contain tracing output files. .PP Tracing to a file may not be able to keep up with a busy system, especially when extensive tracing information is being gathered. If some data loss is encountered, the trace buffer size can be increased. Be selective about the number of subsystems being traced, as well as the kinds of trace data being captured. .PP The .CR nettl and .CR netfmt commands read the .CR /etc/nettlgen.conf file each time they are run (see .IR nettl (1M) and .IR netfmt (1M)). If the file becomes corrupted, these commands will no longer be operational. .SH FILES .TP 40 .CR /dev/netlog Kernel log pseudo-device file. .TP .CR /dev/nettrace Kernel trace pseudo-device file. .TP .CR /etc/nettlgen.conf Tracing and logging subsystem configuration file. .TP .CR /etc/rc.config.d/nettl Contains variables which control the behavior of .CR nettl during system startup. .TP .CR /var/adm/conslog.opts Default console logging options filter file as specified in .CR /etc/nettlgen.conf . .TP .CR /var/adm/nettl.LOG00 Default log file as specified in .CR /etc/nettlgen.conf . .SH AUTHOR .CR nettl was developed by HP. .SH SEE ALSO netfmt(1M), nettlconf(1M), nettlgen.conf(4). .\" .\" index@\f4nettl\f1 \- control network tracing and logging@@@\f3nettl(1M)\f1 .\" index@\f1control network tracing and logging@@@\f3nettl(1M)\f1 .\" index@\f1network tracing and logging, control@@@\f3nettl(1M)\f1 .\" index@\f1tracing, control network@@@\f3nettl(1M)\f1 .\" index@\f1logging, control network@@@\f3nettl(1M)\f1 .\" .\" toc@\f3nettl(1M)\f1:\0\0\f4nettl\f1@@@control network tracing and logging .\" $Header: nettladm.1m,v 72.2 95/02/17 14:39:16 ssa Exp $ .TA n .TH nettladm 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nettladm \- network tracing and logging administration manager .SH SYNOPSIS .CR /opt/nettladm/bin/nettladm .RC [ \-t \(or \-l ] .RC [ -c .IR filter_file ] .SH DESCRIPTION The .CR nettladm command is a tool used to administer network tracing and logging. It provides an interactive user interface to the nettl, netfmt, and nettlconf commands. The interface runs in either text terminal mode or in a Motif graphical environment. To run .CR nettladm using Motif windows set the .C DISPLAY environment variable to match the system name (e.g., .CI DISPLAY= system :0.0\c ) prior to using the command. .PP The .CR nettladm command starts a menu-driven program that makes it easy to perform network tracing and logging tasks with only limited specialized knowledge of HP-UX. .CR nettladm is a self-guided tool, and context-sensitive help is available at any point by pressing the f1 function key. .PP .\" ...add description of tasks and capabilities here... .SS Options .CR nettladm recognizes the following options: .TP 15 .CR \-l Shortcut to enter the ``Logging Subsystems'' (logging) area. This is the default. .TP .CR \-t Shortcut to enter the ``Tracing Subsystems'' (tracing) area. .TP .CI \-c \0filter_file Use the contents of .IR filter_file as the default set of subsystem formatting criteria when creating reports within the ``Create Report'' area. The defaults can be overridden through the interface screens. Global filters (those beginning with the word .CR FORMATTER ) and comments are ignored. See .IR netfmt (1M) for the description and syntax of .IR filter_file . .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multibyte character code sets are supported in data; single-byte character code sets are supported in file names. .SH WARNINGS Changes to logging and tracing levels and states are not preserved across system reboots or stops and restarts from outside of the .CR nettladm command. Permanent changes must be made to the .CR /etc/nettlgen.conf file using the .CR nettlconf command. Note that changes to console logging and all logging startup parameters are preserved. .PP Although the .CR nettladm command allows the specification of all log classes and all trace kinds for all subsystems, many subsystems do not support all log classes and all trace kinds. No error or warning will be issued if a subsystem does not support a log class or trace kind. Refer to the product documentation of the subsystem for information on supported log classes and trace kinds. .PP The .CR nettladm command reads the .CR /etc/nettlgen.conf and .CR /var/adm/conslog.opts files each time it is run (see .IR nettlgen.conf (4)). If the files become corrupted, this command will no longer be operational. .SH DEPENDENCIES .CR nettladm runs in an X Windows environment as well as on the following kinds of terminals or terminal emulators: .RS .TP 3 \(bu HP-compatible terminal with programmable function keys and on-screen display of function key labels. .TP \(bu .SM VT\c -100 .RE .PP .SH FILES .TP 40 .CR /etc/nettlgen.conf Tracing and logging subsystem configuration file. .TP .CR /var/adm/conslog.opts Default console logging options filter file as specified in .CR /etc/nettlgen.conf . .TP .CR /var/adm/nettl.LOG00 Default log file as specified in .CR /etc/nettlgen.conf . .TP .CR /var/adm/nettl.TRC0 Default trace file. .TP .CR /opt/nettladm/lib/X11/app-defaults/Nettladm X11 application defaults file. .SH AUTHOR .CR nettladm was developed by HP. .SH SEE ALSO nettl(1M), netfmt(1M), nettlconf(1M), nettlgen.conf(4). .\" .\" index@\f4nettl\f1 \- control network tracing and logging@@@\f3nettl(1M)\f1 .\" index@\f1control network tracing and logging@@@\f3nettl(1M)\f1 .\" index@\f1network tracing and logging, control@@@\f3nettl(1M)\f1 .\" index@\f1tracing, control network@@@\f3nettl(1M)\f1 .\" index@\f1logging, control network@@@\f3nettl(1M)\f1 .\" .\" toc@\f3nettl(1M)\f1:\0\0\f4nettl\f1@@@control network tracing and logging .\" $Header: nettlconf.1m,v 72.4 94/09/19 10:16:50 ssa Exp $ .TA n .TH nettlconf 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nettlconf \- configure network tracing and logging command subsystem database .SH SYNOPSIS .C /usr/sbin/nettlconf -status .PP .C /usr/sbin/nettlconf -L .RC [ \|\-console .IR conlog\| ] .RC [ \|\-portsize .IR logportsize\| ] .RC [ \|\-space .IR maxlogspace\| ] .RC [ \|\-filename .IR logfilename\| ] .RC [ \|\-option .IR logoptfile\| ] .PP .C /usr/sbin/nettlconf .RC [ \|-S\| ] .CI \|\-id \|\ ssid .CI \|\-name \|\ ssname .RC [ \|\-class .IR logclass\| ] .RC [ \|\-kernel\| ] .CI \|\-lib \|\ sslib .CI \|\-msg \|\ ssmsgcat .RC [ \|\-fmtfn .IR fmtfunc\| ] .RC [ \|\-optfn .IR optfunc\| ] .CI \|\-group \|\ ssgrpname .PP .C /usr/sbin/nettlconf -delete .I ssid .SH DESCRIPTION .C nettlconf maintains the database file .C /etc/nettlgen.conf which contains information required by the .C nettl and .C netfmt commands (see .IR nettl (1M) and .IR netfmt (1M)). This database contains system logging information along with a description of each subsystem that uses the network tracing and logging facilities. .PP .C nettlconf can be used to update the system logging parameters or to add, update, and delete subsystem descriptions. If a subsystem already exists with the same .IR ssid , the values given are substituted for those in the database; otherwise a new entry is created. .PP System administrators may use the .C nettlconf command to customize the system logging parameters stored in the database such as console logging behavior, the system log file name, the maximum system log file size, and the amount of memory required by the tracing and logging facilities. .PP .C nettlconf is also called during system startup to change the database to reflect the values of any relevant environment variables in the .C /etc/rc.config.d/nettl file. .PP Products use the .C nettlconf command during product installation to configure subsystems into the tracing and logging facility. The installation will execute the .C nettlconf command for each subsystem it installs in order to provide the information necessary for the subsystem to use the tracing and logging facilities. .PP Only users with appropriate privileges can invoke .C nettlconf to modify the configuration file. .SS Options The following option can be used to view the system logging parameters and all subsystem descriptions from the .C nettlgen.conf database. .TP 20 .C \|\-status (abbrev: .CR \|\-s ) display the contents of the database. .TP 0 The following options can be used to update the system logging parameters. .TP 20 .C \|\-L This indicates that subsequent options apply to updating logging information. Changes to logging information will not take effect until .C nettl has been stopped and restarted. This is a required field. .TP .CI \|\-console \ conlog (abbrev: .CR \|\-c ) .I conlog is set to 1 if console logging is to be enabled when .C nettl is started, 0 if not. (Console logging is used to report interesting events on the system console.) This is an optional field. NOTE: during system startup .I conlog will be changed to match the value of the .I NETTL_CONSOLE variable in the .C /etc/rc.config.d/nettl file. .TP .CI \|\-portsize \ logportsize (abbrev: .CR \|\-p ) .I logportsize determines the number of outstanding messages possible in the log queue. The value is in multiples of 1024 bytes. Valid range is 1 through 64. The default is 8. This is an optional field. .TP .CI \|\-space \ maxlogspace (abbrev: .CR \|\-s ) .I maxlogspace is the maximum logging file space to be allowed. This is the combined size of the 2 ping-ponged log files. Specify the size in multiples of 1024 bytes. Valid range is 1 through 10240. Default is 1000. This is an optional field. .TP .CI \|\-filename \ logfilename (abbrev: .CR \|\-f ) .I logfilename is the path and file name to be used as the system log file, without the ping-pong extension (.LOGx). The default system log file is .CR /var/adm/nettl . This is an optional field. .TP .CI \|\-option \ logoptfile (abbrev: .CR \|\-o ) .I logoptfile is the path and file name to be used as the console log options file. The information in this file will be used to select logged events that will be reported to the system console. The default console logging options file is .CR /var/adm/conslog.opts . This is an optional field. .TP 0 The following options are used to add or update a subsystem description to the database. .TP 20 .CI \|\-S Indicates that subsequent options apply to adding or updating a subsystem entry. This is an optional field. .TP .CI \|\-id \ ssid (abbrev: .CR \|\-i ) .I ssid (subsystem ID number) is used as the key field in the .C nettlgen.conf database. It uniquely identifies a subsystem to the tracing and logging facility. This is a required field. .TP .CI \|\-name \ ssname (abbrev: .CR \|\-n ) .I ssname is the subsystem-name mnemonic. This string is used to identify the subsystem on the .C nettl command line and also in the subsystem header displayed by the formatter (see .IR nettl (1M) and .IR netfmt (1M)). This is a required field. .TP .CI \|\-class \ logclass (abbrev: .CR \|\-c ) .I logclass is the default log class mask assigned to the subsystem at start-up of the tracing/logging facility. For multiple classes, the masks must be combined into a single decimal number. For example, to initially log .C DISASTER and .C ERROR events use .C 12 as the .IR logclass . Default is an empty field in .CR nettlgen.conf . .C nettl substitutes .C 12 (disaster and error) for an empty class field. This is an optional field. .RS .ift .sp -1v .IP .TS tab(;); cB cB af4p+1 c . Class;Abbreviation _ informative;1 warning;2 error;4 disaster;8 .TE .RE .TP .C \|\-kernel (abbrev: .CR \|\-k ) flags the given subsystem as a kernel subsystem. .C nettl uses this information to control certain tracing and logging properties of the subsystem. A subsystem is defaulted to non-kernel unless this option is used. This is an optional field. .TP .CI \|\-lib \ sslib (abbrev: .CR \|\-l ) .I sslib is the name of the shared library where the subsystem formatter resides. This should be an absolute path name unless the library resides in .CR /usr/lib . Multiple subsystems can reference the same library. This is a required field. .TP .CI \|\-msg \ ssmsgcat (abbrev: .CR \|\-m ) .I ssmsgcat is the name of the subsystem formatter message catalog. If the pathname and .C .cat filename extension are excluded, .I /usr/lib/nls/%L/%N.cat is used to locate .IR ssmsgcat . Otherwise, .I ssmsgcat must be formatted similarly to the .C NLSPATH environment variable (see .IR environ (5)). Multiple subsystems can refer to the same message catalog. This is a required field. .TP .CI \|\-fmtfn \ fmtfunc (abbrev: .CR \|\-f ) .I fmtfunc specifies the function to call when formatting data from the given subsystem. Multiple subsystems can reference the same formatting function. Default is to form the function name from the subsystem ID as follows: .RS .IP .CI subsys_ N _format .RE .IP where .I N is the subsystem .I ID number. If a null function is needed for this subsystem, specify .RS .IP .C \|\-f .SM .C NULL .RE .IP This is an optional field. .TP .CI \|\-optfn \ optfunc (abbrev: .CR \|\-o ) .I optfunc specifies the function used to process options in the .C netfmt filter configuration file (see .IR netfmt (1M)). Multiple subsystems can reference the same options processing function. The default is an empty field in .CR nettlgen.conf . .C netfmt assumes a .I NULL function for an empty .I optfunc field. This is an optional field. .TP .CI \|\-group \ ssgrpname (abbrev: .CR \|\-g ) .I ssgrpname is a group name associated with the subsystem. It is typically the product name of the subsystem. Several subsystems can be grouped together so that a common banner is printed in the formatted header. This is a required field. .TP 0 The following option is used to remove a subsystem description from the database. .TP 20 .CI \|\-delete \ ssid (abbrev: .CR \|\-d ) Deletes all information associated with the .I ssid (subsystem ID) from the database. .SH WARNINGS The .C nettlconf utility is intended primarily for use by .SM HP subsystems to configure themselves into the tracing and logging facility at installation time. System administrators may wish to use this command to alter the default logging class each subsystem starts up with, but no other information about the subsystem should be changed. .PP The .C nettl and .C netfmt commands read the .C /etc/nettlgen.conf file each time they are executed. If the file becomes corrupted these commands cannot function. .PP Some changes to the .C /etc/nettlgen.conf file do not take effect until .C nettl and .C netfmt are stopped and restarted. .SH AUTHOR .C nettlconf was developed by HP. .SH FILES .TP 38 .C /etc/nettlgen.conf subsystem configuration file maintained by .C nettlconf .TP .C /etc/rc.config.d/nettl configuration file controlling .C nettl during system startup .SH SEE ALSO netfmt(1M), nettl(1M), nettlgen.conf(4), environ(5). .\" .\" index@\f4nettlconf\f1 \- configure tracing and logging commands@@@\f3nettlconf(1M)\f1 .\" index@files: configure tracing and logging@@@\f3nettlconf(1M)\f1 .\" index@files: configure trace and log command: nettl(1M)@@@\f3nettlconf(1M)\f1 .\" index@files: configure trace and log command: netfmt(1M)@@@\f3nettlconf(1M)\f1 .\" .\" toc@\f3nettlconf(1M)\f1:\0\0\f4nettlconf\f1@@@configure tracing and logging commands .\" .\" fileset_database@nettlconf.1m SYS-ADMIN-MAN .\" Copyright (c) 1983, 1997 Eric P. Allman .\" Copyright (c) 1985, 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)newaliases.1m 8.5 (Berkeley) 2/1/97 .\" .TH newaliases 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: August 1997 .SH NAME .B newaliases \- rebuild the data base for the mail aliases file .SH SYNOPSIS .B newaliases .SH DESCRIPTION .B Newaliases rebuilds the random access data base for the mail aliases file .I /etc/mail/aliases. It must be run each time this file is changed in order for the change to take effect. .PP .B Newaliases is identical to ``sendmail -bi''. .SH RETURN VALUE The .B newaliases utility exits 0 on success, and >0 if an error occurs. .SH FILES .TP 25 /etc/mail/aliases The mail aliases file .SH SEE ALSO aliases(5), sendmail(1M). .SH HISTORY The .B newaliases command appeared in 4.0BSD. .\" $Header: newarray.1m,v 1.4 96/03/06 13:51:37 hmgr Exp $ .\" $VERSION 1.0 $ .TA n .TH newarray 1M .SH NAME newarray \- configure a disk array .SH SYNOPSIS .HP .C newarray .RC [ -N\c .IR Config_Name\ |\| .RC -r\c .IR RAID_Level ] .RC [ Options ] .I device_file .br .SH DESCRIPTION .CR newarray , a front-end program for the utility .C cfl (see .CR cfl (1M)), facilitates the configuration of Hewlett-Packard SCSI disk arrays. It is the recommended utility for all array configuration. Array configuration maps a set of one or more physical disk mechanisms in an array to a set of one or more logical disks, addressable by .SM HP-UX. Logical disks are addressed through device files. Each logical disk in an array (also known as a LUN, for Logical UNit), has its own device file. A logical disk can consist of a single physical disk, a portion of a single physical disk, multiple physical disks, or portions of multiple physical disks. For additional information about possible array configurations, see the array configuration table contained in the file .CR /etc/hpC2400/arraytab , and .CR arraytab (4). .PP Supported configurations for the array device are pre-defined in the array configuration table, located in file .CR /etc/hpC2400/arraytab . .PP .C newarray can configure a complete set of logical partitions for an array in one operation. Due to the inter-dependency of logical partitions, this is the recommended method for configuration. A single logical partition can be added to an array configuration using an entry from the array configuration table by using the .C -L option. .PP .C device_file is a character device file that specifies the I/O address, and driver to use when configuring the disk array. The way that this file is used by .C newarray is system dependent. See dependencies below. Logical partitions in an array are independently addressable by using the appropriate device file to address the logical unit assigned to a partition. .PP Prior to configuring the array (except with the .C -L option ), all currently configured logical partitions are removed from the configuration. .PP To simplify array configuration .C newarray obtains much of the necessary information directly from the array device, and its attached disk mechanisms. The array model number, and the number of available physical disks available, is determined by querying the device. This information is used to locate the appropriate configuration entry in the array configuration table. Optional parameters can be used to override the default, and inquiry values. .PP The preferred configuration method is to use the .C -N option to specify a configuration by name. The name determines which configuration .C newarray uses from the array configuration table. Configuration parameters are obtained from the named configuration entry. Parameters of the chosen configuration can be overridden using options to .CR newarray , or by creating and using a custom configuration entry in the array configuration table. See the WARNINGS section of this manpage. .PP Because the array controller type, and disk mechanism types are used in addition to the configuration name to select an entry from the array configuration table the configuration name does not have to be unique within the array configuration table. However, the combination of configuration name, array controller type, and disk mechanism types must be unique within the array configuration table. During configuration, the array controller type, and disk mechanism types are obtained by querying the devices. .PP The .C -r option specifies an operating mode, rather than specifying a configuration by name. The .C -d option, which specifies the size of a disk group, is often used with the .C -r option. If .C -d is not used, .C newarray selects the configuration in the array configuration table that most closely matches the disks in the array. .PP When the configuration parameters have been determined, .C newarray calls .C cfl. .PP If the .C -V option is used, .C newarray prints its actions, and the parameters it passes to .C cfl to configure the array (see .CR cfl (1M)). .PP .SS Array Configuration .PP .C newarray obtains its configuration values from the array configuration table. If not specified there, default values are provided by .C cfl (see .CR cfl (1M)). Configuration values can be overridden by .C newarray options. .SS Options .TP 15 .CI -L " unit addr" Configures a single .SM LUN from the specified configuration. The .C -L option is useful for adding disks to an array without changing the existing configuration. Because the order in which .SM LUN's are configured determines the physical mapping on the disks within the array, be very careful when using the .C -L option. .TP .CI -N " config_name" The name of the configuration to be used, as specified in the configuration file .CR /etc/hpC2400/arraytab . See .CR arraytab(4) . .TP .C -V Display the parameters of array configuration, and the utility commands issued as part of the configuration process. .TP .CI -b " block_size" The size in bytes of the .SM LUN block. Must be an integral number of the physical disk mechanism sector size. Currently supported values are 512, 1024, 2048, and 4096. .TP .CI -c " capacity" The size in blocks of the .SM LUN. A value of 0 defaults to the largest capacity available. If the .SM LUN type is set to sub-\c .SM LUN, the capacity is the available capacity of the composite drive group or 2 GByte if the 2 GByte flag is set, which ever is smaller. See .C -f option. .TP .CI -d " group_size" Physical drive group will contain this number of disks in the logical partition configuration. .TP .CI -f " flags" Configuration flags. There are 16 flags, represented by a 16 bit hexadecimal number. Currently only four of the flags are defined. The flag definitions and their default value are: .RS 15 .PP .TP 16 .BI "Bit 0 " " off" Not used. .TP .BI "Bit 1 " " on" Disable auto reconstruction. When set (on), disables the automatic detection, and initiation of failed disk data reconstruction. .TP .BI "Bit 2 " " off" Not used. .TP .BI "Bit 3 " " off" Not used. .TP .BI "Bit 4 " " on" When set (on), enables AEN (automatic event notification) polling. .TP .BI "Bit 5 " " on" When set (on), enables read parity verification. .TP .BI "Bit 6 " " on" When set (on), enables write with parity verification. .TP .BI "Bit 7 " " off" Not used. .TP .BI "Bit 8 " " off" Mode Sense default pages. Bit 8 and Bit 9 concurrently set is reserved. .TP .BI "Bit 9 " " off" Mode Sense current pages. Bit 8 and Bit 9 concurrently set is reserved. .TP .BI "Bit 10-15 " "off" Not used. .RE .TP 15 .CI -g " group_name" Use physical drive group configuration with label GroupName (in array configuration table) for this .SM LUN configuration. .TP .CI -i " seg0_size" The size in bytes of the first segment .SM LUN. This allows this area to be set to a size different than the remainder of the disk, an area typically used as the boot block for some systems. This must be a integral number of the block-size. If there are no special requirements, this parameter should be set to 0. .TP .CI -k " recon_size" Reconstruction size. The .C -k option specifies (in .SM LUN blocks) the amount of data to be reconstructed in a single operation during reconstruction of a redundant drive configuration. Larger values provide more efficient (faster) reconstruction, but hold off the servicing of I/O requests. Smaller values allow quicker servicing of I/O requests, but with less efficient (slower) reconstruction. .TP .CI -l " recon_freq" Reconstruction frequency. The .C -l option specifies (in tenths of a second) the time period between reconstruction of disk segments in a redundant drive configuration. Small time periods cause the array to consume most of its time reconstructing data, but allow the reconstruction to complete more quickly. Large time periods allocate more time to I/O processing, but require longer reconstruction times. .TP .CI -r " raid_level" The .SM RAID (redundancy level) to apply to the disks in the array. Valid entries for .I raid_level are .SM RAID\c _0, .SM RAID\c _1, .SM RAID\c _3, and .SM RAID\c _5. Some .SM RAID levels require specific physical drive configurations. See also the .C -g option. .TP .CI -s " seg_size" The number of bytes of a contiguous segment of the logical address space residing on a single physical disk. This affects how many physical disks are involved in a single I/O request. If I/O requests are mostly random, single-block requests, set this value to the integral number of the .SM LUN block size that minimizes the number of disks necessary to service most I/O requests. A larger size will allocate more time to I/O processing. .TP .CI \-t " LUN_type" .SM LUNs can be configured as regular .SM LUNs .RC ( reg ), or sub-\c .SM LUNs .RC ( sub ). A regular .SM LUN utilizes all the available capacity of a disk group, or limits the .SM LUN configuration to 2 GBytes if the 2 GByte limiter is set. If a regular .SM LUN configuration is used, the .C -c option is ignored. A sub-\c .SM LUN allows logical partitioning of the disk group capacity into a maximum of eight .SM LUNs. Valid values for .I LUN_type are "\c .C reg\c " and "\c .C sub\c ". .RE .PP .SS Custom Configurations .PP You can create array configurations that might be better suited to a particular application by using .CR newarray 's command line parameters to override default values, or by creating special entries in the array configuration table in the file .CR /etc/hpC2400/arraytab . Before you do, see cautionary notes in the WARNINGS section of this manpage. .SH RETURN VALUES .C newarray will return the following values: .PP .RS 2 .PD 0 .TP 3 .B " 0" Successful completion. .TP 3 .B \-1 Command failed (an error occurred). .RE .PD .SH ERRORS .RS 4 .C "newarray: device busy" .RE .PP .tr ~" To ensure that .C newarray does not modify a disk array that is being used by another process, .C newarray attempts to obtain exclusive access to the disk array. If the disk array is already opened by another process (for example, LVM \(em the Logical Volume Manager), a .RC ~ "device busy" ~ error message is returned by the driver. To eliminate the .RC ~ "device busy" ~ condition, determine what process has the device open. In the case of LVM, it is necessary to deactivate the volume group containing the array before configuring the array (see .CR vgchange (1M)). .tr ~~ .SH EXAMPLES: The following examples use configurations contained in .CR /etc/hpC2400/arraytab . .PP .SS Raid Level Specification .PP To configure an .SM HP C2425D with 5 internal disks to a five drive .SM RAID level 0 configuration (on Series 700 computer): .PP .RS 4 .C "newarray -rRAID_0 /dev/rdsk/c2t3d0" .RE .PP To configure an .SM HP C2425D with 5 internal disks to a one drive .SM RAID level 0 configuration (on Series 700): .PP .RS 4 .C "newarray -rRAID_0 -d1 /dev/rdsk/c2t3d0" .RE .PP .SS Name Specification .PP To configure an .SM HP C2430D with five disks connected on .SM SCSI channel 3 (on a Series 800) using the configuration "Raid_3_5d" in .CR /etc/hpC2400/arraytab : .PP .RS 4 .C "newarray \-NRaid_3_5d /dev/rdsk/c2t3d0" .RE .PP .SH WARNINGS We strongly recommend that you use the array configurations that are specified, and delivered by Hewlett-Packard, in the file .C /etc/hpC2400/arraytab. These configurations have been tested and certified for proper use on Hewlett-Packard computer systems. Custom configurations cannot be warranted for proper operation. .PP Configuring a disk array causes the loss of user data on the array. .PP When using the .C -L option, physical media is assigned to the logical unit in the order in which the logical units are configured. Existing logical unit configurations are NOT removed prior to configuration with this option. The use of this option is not recommended at this time. .SH DEPENDENCIES .PP .SS File System Considerations .RS 2 .PP The disk array maps the address space of one or more physical disk mechanisms onto logical "disk" partitions. The parameters defined in the configuration, together with the data access patterns of the user's application, determine the operating characteristics of the logical disk. Some configurations create multiple logical partitions, that share a set of physical disks. I/O traffic to each of the logical partitions affects performance, due to the common physical disk resources. The file system or application using the "logical" disk may require or assume certain characteristics. For optimal system performance it is necessary that the file system configuration and application be compatible with the array configuration. .PP Your choice of segment size directly affects the performance of the disk array. Choose this parameter in concert with the choice of the parameters used when building the file system on the device. In general, the segment size determines how much data from a single I/O will be stored on a single disk within the array. A smaller value will involve more of the disks with the I/O, whereas a larger value will involve fewer disks. If input/output operations tend to be very long, the involvement of multiple disks may hasten the completion of each I/O. In this case the access time is the same as a single disk, but the disk data transfer time is shared across the set of disks. If input/output operations are short, the access time will dominate relative to the disk data transfer time, and more input/output operations may be processed in parallel by involving fewer disks in each I/O. In all cases the relative locality of data and the access pattern will affect the performance. For highly sequential data, it may be advantageous to locate the data for a single I/O on a single disk, to take advantage of read-ahead caching within each disk. .PP Configurations for the .SM HP C2430 disk array should enable the automatic data reconstruction .SM LUN flag as part of the configuration specification. .RE .PP .SS SUPPORTED ARRAY PRODUCTS: .RS 2 .PP The HP C2425 and HP C2427 disk arrays are only supported on Series 700 systems running HP-UX version 9.0X. .PP The HP C2430 disk array is supported on Series 700 and 800 systems running HP-UX versions 9.0X and 10.0X. .SH AUTHOR .PP .C newarray was developed by .SM HP. .SH SEE ALSO arraytab(4), cfl(1m), buildfs(1m), fs(4), mkfs(1m), sss(1m), and dcc(1m) .\" .\" index@\f4newarray\f1 \- configure a disk array@@@\f3newarray(1M)\f1 .\" index@disk array, configuring@@@\f3newarray(1M)\f1 .\" index@configuring a disk array@@@\f3newarray(1M)\f1 .\" .\" toc@\f3newarray(1M)\f1:\0\0\f4newarray\f1@@@make a special file .\" .\" fileset_database@newarray.1m SYS-ADMIN-MAN .\" $Header: newfs.1m,v 72.7 94/11/28 08:40:36 ssa Exp $ .TA n .TH newfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME newfs (generic) \- construct a new file system .SH SYNOPSIS .CR /usr/sbin/newfs .RC [ \-F .IR FStype ] .RC [ \-o .IR specific_options ] .RC [ \-V ] .I special .SH DESCRIPTION The .CR newfs command is a "friendly" front-end to the .CR mkfs command (see .IR mkfs (1M)). The .CR newfs command calculates the appropriate parameters and then builds the file system by invoking the .CR mkfs command. .PP .I special represents a character (raw) special device. .SS Options .CR newfs recognizes the following options: .RS .TP 15 .CI \-F \0FStype Specify the file system type on which to operate (see .IR fstyp (1M) and .IR fs_wrapper (5)). If this option is not included on the command line, then the file system type is determined from the file .CR /etc/fstab by matching .I special with an entry in that file. If there is no entry in .CR /etc/fstab , then the file system type is determined from the file .CR /etc/default/fs . .TP .CI \-o \0specific_options Specify options specific to the file system type. .I specific_options is a list of suboptions and/or keyword/attribute pairs intended for an .IR FStype -specific module of the command. See the file system specific manual entries for a description of the .I specific_options that are supported, if any. .TP .CR \-V Echo the completed command line, but perform no other actions. The command line is generated by incorporating the specified options and arguments and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .SH EXAMPLES Execute the .CR newfs command to create an HFS file system on .CR /dev/rdsk/c1d0s2 .IP .C "newfs \-F hfs /dev/rdsk/c1d0s2" .SH AUTHOR .CR newfs was developed by HP and the University of California, Berkeley. .SH FILES .TP 25 .PD 0 .CR /etc/default/fs File that specifies the default file system type. .TP .CR /etc/fstab Static information about the file systems. .PD .SH SEE ALSO fsck(1M), fstyp(1M), mkfs(1M), .RI newfs_ FStype (1M), fstab(4), fs_wrapper(5). .\" .\" index@\f4newfs\f1 \- construct a new file system (generic)@@@\f3newfs(1M)\f1 .\" index@\f1construct a new file system (generic)@@@\f3newfs(1M)\f1 .\" index@\f1make a new file system (generic)@@@\f3newfs(1M)\f1 .\" index@\f1new file system (generic), construct@@@\f3newfs(1M)\f1 .\" index@\f1file system (generic), construct new@@@\f3newfs(1M)\f1 .\" index@\f1generic new file system, construct@@@\f3newfs(1M)\f1 .\" .\" toc@\f3newfs(1M)\f1:\0\0\f4newfs\f1@@@construct a new file system (generic) .\" $Header: newfs_hfs.1m,v 78.2 96/02/13 13:26:13 ssa Exp $ .TA n .TH newfs_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME newfs (hfs) \- construct a new HFS file system .SH SYNOPSIS .CR /usr/sbin/newfs .RC [ \-F .CR hfs ] .RC [ \-B ] .RC [ \-d ] .RC [ \-L \(or \-S ] .RC [ \-O .IR disk_type ] .RC [ \-R .IR swap ] .ifn .br .ifn \0\0\0\0 .RC [ \-v ] .RC [ \-V ] .ift .br .ift \0\0\0\0 .RI [ mkfs-options ] .I special .SH DESCRIPTION The .CR newfs command builds a file system by invoking the .CR mkfs command. .PP The .CR newfs command creates the file system with a rotational delay value of zero (see .IR tunefs (1M)). .PP .I special represents a character (raw) special device. .PP .SS Options .CR newfs recognizes the following options: .RS .TP 15 .CR \-F\0hfs Specify the HFS file system type. .TP .CR \-B Reserve space for boot programs past the end of the file system. If file .CR /usr/lib/uxbootlf is present on the system then sufficient space to accommodate that file is reserved, otherwise 691 KB sectors are reserved. This option decreases the size of the file system to be created. This option cannot be used if the .CR \-s option is given; see "mkfs Options" below. .TP .CR \-d This option allows the .CR newfs command to make the new file system in an ordinary file. In this case, .IR special is the name of an existing file in which to create the file system. The .CR \-s option (see "mkfs Options") must be provided with this option. .TP .CR \-L \(or \-S There are two types of HFS file systems, distinguished mainly by directory formats that place different limits on the length of file names. .IP If .CR \-L is specified, build a long-file-name file system that allows directory entries (file names) to be up to .CR MAXNAMLEN (255) bytes long. .IP If .CR \-S is specified, build a short-file-name file system that allows directory entries (file names) to be up to .CR DIRSIZ (14) bytes long. .IP If neither .CR \-L nor .CR \-S is specified, build a file system of the same type as the root file system. .TP .CI \-O \0disk_type Use disk parameters from the entry for the named disk type in .CR /etc/disktab . This option is provided for backward compatibility with previous HP-UX releases. Any parameters specified in the command line will override the corresponding values in .CR /etc/disktab . Any values not given in the command line or in .CR /etc/disktab will be defaulted. .TP .CI \-R \0swap Reserve .I swap megabytes (MB) of swap space past the end of the file system. This option decreases the size of the file system to be created by the given amount. This option cannot be used if the .CR \-s option is given; see "mkfs Options" below. .TP .CR \-v Verbose; the .CR newfs command prints out its actions, including the parameters passed to the .CR mkfs command. .TP .CR \-V Echo the completed command line, but perform no other actions. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .PP Both the .CR \-R and .CR \-B options can be given in the same command line. In this case, both the requested swap space and the space needed for boot programs are reserved. These options are for use when the file system size defaults to the size of the entire disk. .SS mkfs Options The .I mkfs-options argument can be zero or more of the following options that can be used to override default values passed to the .CR mkfs command: .RS .TP 15 .CI \-b \0blksize The primary block size for files on the file system. Valid values are: 4096, 8192, 16384, 32768, and 65536. The default value is 8192 bytes. .TP .CI \-c \0cylinders_per_group The number of disk cylinders per cylinder group. This number must be in the range 1 to 32. The default value is 16 cylinders per group. .TP .CI \-f \0fragsize The fragment size for files on the file system. .I fragsize represents the smallest amount of disk space to be allocated to a file. It must be a power of two no smaller than .CR DEV_BSIZE and no smaller than one-eighth of the file system block size. The default value is 1024 bytes. .TP .CI \-i \0number_of_bytes_per_inode The density of inodes in the file system specified as the number of bytes per inode. The default is 6144 bytes per inode. .IP This number should reflect the expected average size of files in the file system. If fewer inodes are desired, a larger number should be used; if more inodes are desired, a smaller number should be used. .IP .B Note: The number of inodes that will be created in each cylinder group of a file system is approximately the size of the cylinder group divided by the number of bytes per inode, up to a limit of 2048 inodes per cylinder group. If the size of the cylinder group is large enough to reach this limit, the default number of bytes per inode will be increased. .TP .CI \-m \0free_space_percent The minimum percentage of free disk space allowed. The default value is 10 percent. .IP Once the file system capacity reaches this threshold, only users with appropriate privileges can allocate disk blocks. .TP .CI \-r \0revolutions_per_minute The disk speed in revolutions per minute (rpm). The default value is 3600 revolutions per minute. .TP .CI \-s \0size The number of .CR DEV_BSIZE blocks in the file system. .CR DEV_BSIZE is defined in .CR . The default value is the size of the entire disk or disk section minus any swap or boot space requested. See .IR mkfs_hfs (1M) for limits on the size of HFS file systems. .TP .CI \-t \0tracks_per_cylinder The number of tracks per cylinder. The default value depends on the size of the file system. For file systems of less than 500 MB, the default is 7; for file systems between 500 MB and 1 GB, the default is 12; for file systems larger than 1 GB the default is 16. .TP .CI \-o \0specific_options Specify a list of comma separated suboptions and/or keyword/attribute pairs from the list below. .RS .TP .CI largefiles|nolargefiles Controls the .I largefile featurebit for the file system. The default is nolargefiles. This means the bit is not set, and files created on the file system will be limited to less than 2 gigabytes in size. If .C largefiles is specified, the bit is set and the maximum size for files created on the file system is not limited to 2 gigabytes. .RE .SS Access Control Lists Every file with one or more optional ACL entries consumes an extra (continuation) inode. If you anticipate significant use of ACLs on a new file system, you can allocate more inodes by reducing the value of the argument to the .CR \-i option appropriately. The small default value typically causes allocation of many more inodes than are actually necessary, even with ACLs. To evaluate the need for extra inodes, run the .CR "bdf\ \-i" command on existing file systems. For more information on access control lists, see .IR acl (5). .SH EXAMPLES Execute the .CR newfs command to create an HFS file system on .CR /dev/rdsk/c1d0s2 and reserve 40 megabytes of swap space. .IP .C "newfs \-F hfs \-R40 /dev/rdsk/c1d0s2" .SH WARNINGS The old .CR \-F option, from prior releases of .IR newfs (1M), is no longer supported. .SH AUTHOR .CR newfs was developed by HP and the University of California, Berkeley. .SH FILES .TP 20 .PD 0 .CR /etc/disktab .TP .CR /etc/fstab Static information about the file systems. .PD .SH SEE ALSO bdf(1M), mkboot(1M), mkfs(1M), mkfs_hfs(1M), newfs(1M), tunefs(1M), disktab(4), fs(4), acl(5). .\" .\" index@\f4newfs\f1 \- construct a new HFS file system@@@\f3newfs_hfs(1M)\f1 .\" index@construct a new HFS file system@@@\f3newfs_hfs(1M)\f1 .\" index@make a new HFS file system@@@\f3newfs_hfs(1M)\f1 .\" index@new HFS file system, construct a@@@\f3newfs_hfs(1M)\f1 .\" index@HFS file system, construct a new@@@\f3newfs_hfs(1M)\f1 .\" index@file system (HFS), construct a new@@@\f3newfs_hfs(1M)\f1 .\" .\" toc@\f3newfs_hfs(1M)\f1:\0\0\f4newfs\f1@@@construct a new HFS file system .\" $Header: newfs_vxfs.1m,v 78.1 96/02/13 13:26:50 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" (c) Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA n .TH newfs_vxfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME newfs (vxfs) \- construct a new VxFS file system .SH SYNOPSIS .CR "/usr/sbin/newfs \-F vxfs" .RC [ \-V ] .RC [ \-v ] .RC [ \-R .IR swap ] .RC [ \-l ] .RC [ \-B ] .RC [ \-O .IR disk_type ] .br \0\0\0\0\0\0\0\0\0\0\0\0\0\0\0 .RI [ mkfs_vxfs_options ] .I special .SH DESCRIPTION The .C newfs \-F vxfs command builds a VxFS file system by invoking .CR mkfs . In addition to file system type specification, .CR newfs takes a variety of options, listed below. A character (raw) file, .IR special , (for example, .CR /dev/rdsk/c0t6d0 ) must also be specified. .PP .SS Options .C newfs recognizes the following options: .RS .TP 15 .C \-F " vxfs" Specify the file-system type .CR vxfs , required for a VxFS file system. .TP .C \-V Echo the completed command line, but perform no other actions. The command line is generated by incorporating the user-specified options and other information derived from .C /etc/fstab. This option allows the user to verify the command line. .TP .C \-v Verbose. .C newfs prints out its actions, including the parameters passed to .CR mkfs . .TP 15 .CI \-l Set the .I largefile compatibility bit for the file system, allowing files larger than 2 Gbytes to be created. (See the .C \-o largefiles option in the .CR mkfs_vxfs (1m) manual page.) .TP 15 .CI \-R " swap" Reserve .I swap Mbytes of swap space past the end of the file system. This option decreases the size of the file system to be created by the given number of Mbytes. This option cannot be used if the file-system size is also specified using .CR \-s (see .CR mkfs_vxfs options below). .TP 15 .C \-B Reserve space for boot programs past the end of the file system. If file .CR /usr/lib/uxbootlf is present on the system, sufficient space to accommodate that file is reserved; otherwise 691 Kbytes are reserved. This option decreases the size of the file system being created. This option cannot be used if the file-system size is also specified using .CR \-s (see .CR mkfs_vxfs options below). .TP 15 .CI \-O " disk_type" Use disk parameters from the entry for the named .I disk_type in .CR /etc/disktab . This option is provided for backward compatibility with previous HP-UX releases. Any parameters specified on the command line will override the corresponding values in .CR /etc/disktab . Any values not specified in the command line and not shown in .CR /etc/disktab will be defaulted. .RE .PP Both .CR \-R and .CR \-B options may be given in the same command line. In this case, both the requested swap space and the space needed for boot programs are reserved. These options are used when the file system size is defaulted to the size of the entire disk. .SS mkfs_vxfs Options The following additional command-line options can be used to override default parameters passed to .CR mkfs_vxfs: .RS .TP 15 .CI \-s " size" File system size in .C DEV_BSIZE blocks (defined in .CR ). The default value used is the size of the entire disk or disk section, minus any swap or boot space requested. The .I size specifies the number of sectors in the file system. By default, size is specified in units of DEV_BSIZE sectors. However, the letter .CR k , .CR m , or .CR g can be appended to the number to indicate that the value is in kilobytes, megabytes, or gigabytes, respectively. .TP 15 .CI \-b " block_size" File system block size in bytes. The default value used is 1024 bytes. .TP 15 .CI \-o " largefiles | nolargefiles" Controls the .I largefile compatibility bit for the file system. By default the bit is not set, and files created on the file system will be limited to less than 2 gigabytes in size. If .C largefiles is specified, the bit is set and the maximum file size for files created on the file system is not limited to 2 gigabytes (see .IR mkfs_vxfs (1M) , .IR mount_vxfs (1M) and .IR fsadm_vxfs (1M)) . This option is only valid for a Version 3 disk layout. The default is .IR nolargefiles , although the default may change in the future. .RE .PP .SH EXAMPLES Execute .C newfs to create a VxFS file system on .CR /dev/rdsk/c1t5d0 and reserve 40 Mbytes of swap space. .IP .C newfs \-F vxfs \-R40 /dev/rdsk/c1t5d0 .SH FILES .TP 25 .PD 0 .CR /etc/disktab Disk description file. .TP .CR /etc/fstab Static information about the file systems. .PD .SH SEE ALSO mkfs(1M), mkfs_vxfs(1M), newfs(1M), disktab(4). .\" .\" index@\f(CWnewfs_vxfs\f1 \- construct new VxFS file system@@@\f3newfs_vxfs(1M)\f1 .\" index@\f(CWnewfs\f1 \- construct new VxFS file system@@@\f3newfs_vxfs(1M)\f1 .\" .\" index@\f1construct new VxFS file system@@@\f3newfs_vxfs(1M)\f1 .\" index@\f1new VxFS file system, construct a@@@\f3newfs_vxfs(1M)\f1 .\" index@\f1VxFS file system: construct new file system@@@\f3newfs_vxfs(1M)\f1 .\" index@\f1file system: construct new VxFS file system@@@\f3newfs_vxfs(1M)\f1 .\" .\" toc@\f3newfs_vxfs(1M)\f1:\0\0\f(CWnewfs_vxfs\f1@@@construct new VxFS file system .\" .\" $Header: newkey.1m,v 72.3 94/09/21 13:50:32 ssa Exp $ .TA n .TH newkey 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME newkey \- create a new key in the publickey database file .SH SYNOPSIS .C newkey .RC -h .IR hostname\| .PP .C newkey .RC -u .IR username\| .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .CR newkey is run by the network administrator on the Network Information Service (NIS) master server to create the public/secret key pair for users and superusers on the network. These keys are required to use secure RPC or secure NFS. .PP .CR newkey prompts the user for the login password of the user specified in .I \|username\|, or the root password of the host given in .I \|hostname\|, and then creates a new public/secret key pair, which is encrypted with the specified password in the .CR publickey database file, .CR /etc/publickey . .CR newkey invokes .CR udpublickey to update .C /etc/publickey on its behalf. (See .IR udpublickey (1M)). .PP If the .I nobody entry in the publickey database file, .CR /etc/publickey , has been commented out, only .CR newkey can be used to create a public/secret key pair. Otherwise, .CR chkey may be used to create the public/secret key pair. .SS Options .CR newkey supports the following options: .RS .TP 15 .CI -h \0hostname Create a new public/secret key pair for the superuser at the specified hostname. Prompts for the root password for the specified machine. .TP .CI -u \0username Create a new public/secret key pair for the username specified by username. Prompts for the NIS password of the specified username .SH EXAMPLES .C /usr/sbin/newkey .PP .CR /usr/sbin/keyserv .C -h \f2hostname\fP .PP .C "Adding new key for" .CR \0unix.\f2hostname\fP\f4@domain\fP .PP .C New password: xxxxx .PP .C Retype password: xxxxx .PP .C "Please wait for the database to get updated..." .PP .C "Your new key has been successfully stored away." .SH AUTHOR .CR newkey was developed by Sun Microsystems, Inc. .SH FILES .TP 25 .C /etc/publickey .SH SEE ALSO chkey(1), keylogin(1), keylogout(1), keyserv(1M), udpublickey(1M), updaters(1M), publickey(4) .\" .\" index@\f4newkey\f1 \- create a new key in the \f4publickey\f1 database file@@@\f3newkey v(1M)\f1 .\" index@create a new key in the \f4publickey\f1 database file@@@\f3newkey(1M)\f1 .\" index@\f4publickey\f1 database file, creating new key in@@@\f3newkey(1M)\f1 .\" index@new key, creating in \f4publickey\f1 database file@@@\f3newkey(1M)\f1 .\" .\" toc@\f3newkey(1M)\f1:\0\0\f4newkey\f1@@@create a new key in \f4publickey\f1 database file .\" $Header: nfsd.1m,v 72.5 94/09/13 11:09:41 ssa Exp $ .TA n .TH nfsd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nfsd, biod \- NFS daemons .SH SYNOPSIS .C /usr/sbin/nfsd .RI [ nservers ] .PP .C /usr/sbin/biod .RI [ nservers ] .SH DESCRIPTION .CR nfsd starts the NFS server daemons that handle client file system requests (see .IR nfs (7)). .I nservers is the number of file system request daemons that start. This number should be determined by the load expected on the server system. To obtain the best performance in most cases, set .I nservers to four. .PP .CR biod starts .I nservers asynchronous block I/O daemons. This command is used on an NFS client to buffer cache handle read-ahead and write-behind. .I nservers is a number greater than zero. For best performance, set .I nservers to four. .SH AUTHOR .CR nfsd was developed by Sun Microsystems, Inc. .SH SEE ALSO mountd(1M), exports(4). .\" .\" index@\f4biod\f1 \- NFS block I/O daemon@@@\f3nfsd(1M)\f1 .\" index@\f4nfsd\f1 \- NFS daemon@@@\f3nfsd(1M)\f1 .\" index@\f1NFS daemons@@@\f3nfsd(1M)\f1 .\" index@\f1daemons, NFS@@@\f3nfsd(1M)\f1 .\" .\" toc@\f3nfsd(1M)\f1:\0\0\f4biod\f1, \f4nfsd\f1@@@NFS daemons\f1 .\" toc@\f4biod(1M)\f1:\0\0\NFS block I/0 daemons@@@\f1see \f3nfsd(1M)\f1 .\" .\" links@nfsd.1m biod.1m .\" @(#)nfsstat.1m 1.35 92/05/21 SMI; .TH nfsstat 1M "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nfsstat \- Network File System statistics .SH SYNOPSIS .B nfsstat [ .B \-cmnrsz ] /stand\/vmunix .SH AVAILABILITY This program is available with the .I Networking software installation option. Refer to .TZ INSTALL for information on how to install optional software. .SH DESCRIPTION .IX "nfsstat command" "" "\fLnfsstat\fP \(em display NFS statistics" .IX "NFS" "display statistics" "" "display statistics \(em \fLnfsstat\fP" .IX "statistics" "NFS, display" "" "NFS, display \(em \fLnfsstat\fP" .B nfsstat displays statistical information about the .SM NFS (Network File System) and .SM RPC (Remote Procedure Call), interfaces to the kernel. It can also be used to reinitialize this information. If no options are given the default is .IP .B nfsstat \-cnrs /stand/vmunix .LP That is, display everything, but reinitialize nothing. .SH OPTIONS .TP .B \-c Display client information. Only the client side .SM NFS and .SM RPC information will be printed. Can be combined with the .B \-n and .B \-r options to print client .SM NFS or client .SM RPC information only. .TP .B \-m Display statistics for each .SM NFS mounted file system. This includes the server name and address, mount flags, current read and write sizes, the retransmission count, and the timers used for dynamic retransmission. The .B srtt value contains the smoothed round trip time, the .B dev value contains the estimated deviation, and the .B cur value is the current backed-off retransmission value. .TP .B \-n Display .SM NFS information. .SM NFS information for both the client and server side will be printed. Can be combined with the .B \-c and .B \-s options to print client or server .SM NFS information only. .TP .B \-r Display .SM RPC information. .TP .B \-s Display server information. .TP .B \-z Zero (reinitialize) statistics. This option is for use by the super-user only, and can be combined with any of the above options to zero particular sets of statistics after printing them. .SH DISPLAYS .LP The server .SM RPC display includes the following fields: .RS .TP 10 .B calls .PD 0 The total number of .SM RPC calls received. .PD .TP .B badcalls The total number of calls rejected by the .SM RPC layer (the sum of .B badlen and .B xdrcall as defined below). .TP .B nullrecv The number of times an .SM RPC call was not available when it was thought to be received. .TP .B badlen The number of .SM RPC calls with a length shorter than a minimum-sized .SM RPC call. .TP .B xdrcall The number of .SM RPC calls whose header could not be .SM XDR decoded. .RE .LP The server .SM NFS display shows the number of .SM NFS calls received .RB ( calls ) and rejected .RB ( badcalls ), and the counts and percentages for the various calls that were made. .LP The client .SM RPC display includes the following fields: .RS .TP 10 .B calls .PD 0 The total number of .SM RPC calls made. .TP .B badcalls The total number of calls rejected by the .SM RPC layer. .TP .B retrans The number of times a call had to be retransmitted due to a timeout while waiting for a reply from the server. .TP .B badxid The number of times a reply from a server was received which did not correspond to any outstanding call. .TP .B timeout The number of times a call timed out while waiting for a reply from the server. .TP .B wait The number of times a call had to wait because no client handle was available. .TP .B newcred The number of times authentication information had to be refreshed. .TP .B timers The number of times the calculated time-out value was greater than or equal to the minimum specified time-out value for a call. .PD .RE .LP The client .SM NFS display shows the number of calls sent and rejected, as well as the number of times a .SB CLIENT handle was received .RB ( nclget ), the number of times a call had to sleep while awaiting a handle .RB ( nclsleep ), as well as a count of the various calls and their respective percentages. .RE .SH AUTHOR .C nfsstat was developed by Sun Microsystems, Inc. .\" $Header: ntpdate.1m,v 72.3 94/12/09 14:57:41 ssa Exp $ .TA n .TH ntpdate 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ntpdate - set the date and time via NTP .SH SYNOPSIS .B ntpdate [ .B -bdos ] [ .B -a .I key# ] [ .B -e .I authdelay ] [ .B -k .I keyfile ] [ .B -p .I samples ] [ .B -t .I timeout ] server ... .SH DESCRIPTION .C ntpdate sets the local date and time by polling the Network Time Protocol server(s) on the host(s) given as arguments to determine the correct time. It must be run as root on the local host. A number of samples are obtained from each of the servers specified and the standard NTP clock filter and selection algorithms are applied to select the best of these. Typically, .C ntpdate can be inserted in the startup script to set the time of day at boot time and/or can be run from time\-to\-time via .IR cron (1M). Note that .CR ntpdate 's reliability and precision will improve dramatically with greater numbers of servers. While a single server may be used, better performance and greater resistance to insanity on the part of any one server will be obtained by providing at least three or four servers, if not more. .PP Time adjustments are made by .C ntpdate in one of two ways. If .C ntpdate determines your clock is off by more than 0.5 seconds it will simply step the time by calling .IR settimeofday (2). If the error is less than 0.5 seconds, however, it will by default slew the clock's time via a call to .IR adjtime (2) with the offset. The latter technique is less disruptive and more accurate when the offset is small, and works quite well when .C ntpdate is run by .IR cron (1M) every hour or two. The adjustment made in the latter case is actually 50% larger than the measured offset since this will tend to keep a badly drifting clock more accurate (at some expense to stability, though this tradeoff is usually advantageous). At boot time, however, it is usually better to always step the time. This can be forced in all cases by specifying the .B -b switch on the command line. The .B -s switch tells .C ntpdate to log its actions via the .IR syslog (3C) facility rather than to the standard output, a useful option when running the program from .IR cron (1M). .PP The .B -d flag may be used to determine what .C ntpdate will do without it actually doing it. Information useful for general debugging will also be printed. By default .C ntpdate claims to be an NTP version 3 implementation in its outgoing packets. As some older software will decline to respond to version 3 queries, the .B -o switch can be used to force the program to poll as a version 2 implementation instead. .PP The number of samples .C ntpdate acquires from each server can be set to between 1 and 8 inclusive using the .B -p switch. The default is 4. The time it will spend waiting for a response can be set using the .B -t switch, and will be rounded to a multiple of 0.2 seconds. The default is 1 second, a value suitable for polling across a LAN. .PP .C ntpdate will authenticate its transactions if need be. The .B -a switch specifies that all packets should be authenticated using the key number indicated. The .B -k switch allows the name of the file from which the keys may be read to be modified from the default of .CR /etc/ntp.keys . This file should be in the format described in .IR xntpd (1M). The .B -e option allows the specification of an authentication processing delay, in seconds (see .IR xntpd (1M) for details). This number is usually small enough to be negligible for .CR ntpdate 's purposes, though specifying a value may improve timekeeping on very slow CPU's. .PP .C ntpdate will decline to set the date if an NTP server daemon (e.g. .IR xntpd (1M)) is running on the same host. When running .C ntpdate on a regular basis from .IR cron (1M) as an alternative to running a daemon, doing so once every hour or two will result in precise enough timekeeping to avoid stepping the clock. .SH FILES .TP 30 .CR /etc/ntp.keys Contains the encription keys used by .CR ntpdate . .SH SEE ALSO xntpd(1M), syslog(3C), .br .SM DARPA Internet Request For Comments .SM RFC1035 Assigned Numbers. .SH AUTHOR .C ntpdate was developed by Dennis Ferguson at the University of Toronto .\" .\" index@\f4ntpdate\f1 \- set time and date via NTP@@@\f3ntpdate(1M)\f1 .\" index@\f1time and date, set via NTP@@@\f3ntpdate(1M)\f1 .\" index@\f1date and time, set via NTP@@@\f3ntpdate(1M)\f1 .\" index@\f1Network Time Protocol (NTP), set time and date@@@\f3ntpdate(1M)\f1 .\" index@\f1NTP (Network Time Protocol), set time and date@@@\f3ntpdate(1M)\f1 .\" .\" toc@\f3ntpdate(1M)\f1:\0\0\f4ntpdate\f1@@@set time and date via NTP .\" .\" fileset_database@ntpdate.1m INETSVCS-MAN .\" $Header: ntpq.1m,v 72.2 94/07/05 13:05:31 ssa Exp $ .TA n .TH ntpq 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ntpq - standard Network Time Protocol query program .SH SYNOPSIS .B ntpq [ .B -inp ] [ .B -c .I command ] [ .I host ] [ .I ... ] .SH DESCRIPTION .C ntpq is used to query .SM NTP servers about current state and to request changes in that state. The program may be run either in interactive mode or controlled using command line arguments. Requests to read and write arbitrary variables can be assembled, with raw and pretty\-printed output options being available. .C ntpq can also obtain and print a list of peers in a common format by sending multiple queries to the server. .PP If one or more request options is included on the command line when .C ntpq is executed, each of the requests will be sent to the NTP servers running on each of the hosts given as command line arguments, or on .I localhost by default. .C ntpq will run in the interactive mode if no request options are given. It will attempt to read interactive format commands from the standard input and execute these commands on the .SM NTP server running on the first host given on the command line, again defaulting to .I localhost when no other host is specified. .C ntpq will prompt for commands if the standard input is a terminal device. .PP .C ntpq uses NTP mode 6 packets to communicate with the NTP server, and hence can be used to query any compatible server on the network which permits it. Note that since NTP is a UDP protocol this communication will be somewhat unreliable, especially over large distances in terms of network topology. .C ntpq makes one attempt to retransmit requests, and will time requests out if the remote host is not heard from within a suitable timeout time. .PP Command line options are described following. .TP 6 .C -c The following .I command argument is interpreted as an interactive format command and is added to the list of commands to be sent to and executed on the specified host(s). Multiple .C -c options may be given. .TP .C -i Force .C ntpq to operate in interactive mode. Prompts will be written to the standard output and commands read from the standard input. .TP .C -n Output all host addresses in dotted\-quad numeric format rather than converting to the canonical host names. .TP .C -p Print a list of the peers known to the server as well as a summary of their state. This is equivalent to the .C peers interactive command. .PP .SH INTERACTIVE INTERNAL COMMANDS .PP Interactive format commands consist of a keyword followed by zero to four arguments. Only enough characters of the full keyword to uniquely identify the command need be typed. The output of a command is normally sent to the standard output, but optionally the output of individual commands may be sent to a file by appending a .C > followed by a file name, to the command line. .PP A number of interactive format commands are executed entirely within the .C ntpq program itself and do not result in NTP mode 6 requests being sent to a server. These are described following. .PP .C ? [ .I command_keyword ] .PP A .C ? by itself will print a list of all the command keywords known to this incarnation of .CR ntpq . A .C ? followed by a command keyword will print function and usage information about the command. .PP .C timeout .I millseconds .PP Specify a timeout period for responses to server queries. The default is about 5000 milliseconds. Note that since .C ntpq retries each query once after a timeout, the total waiting time for a timeout will be twice the timeout value set. .PP .C host .I hostname .PP Set the host to which future queries will be sent. .I Hostname may be either a host name or a numeric address. .PP .C keyid .I # .PP This command allows the specification of a key number to be used to authenticate configuration requests. This must correspond to a key number the server has been configured to use for this purpose. .PP .C passwd .PP This command prompts you to type in a password (which will not be echoed) which will be used to authenticate configuration requests. The password must correspond to the key configured for use by the NTP server for this purpose if such requests are to be successful. .PP .C "hostnames yes|no" .PP If .I yes is specified, host names are printed in information displays. If .I no is given, numeric addresses are printed instead. The default is .I yes unless modified using the command line .C -n switch. .PP .C raw .PP Causes all output from query commands to be printed as received from the remote server. The only formating/interpretation done on the data is to transform nonascii data into a printable (but barely understandable) form. .PP .C cooked .PP Causes output from query commands to be .C cooked. Variables which are recognized by the server will have their values reformatted for human consumption. .PP .C ntpversion .C 1|2|3 .PP Sets the NTP version number which .C ntpq claims in packets. Defaults to .CR 3 . Note that mode 6 control messages (and modes, for that matter) didn't exist in NTP version 1. There appear to be no servers left which demand version 1. .PP .C version .PP Display the version of .CR ntpq . .PP .C keytype .C m|d .PP set the authentication type to md5 [ .C m ] or des [ .C d ]. .PP .C authenticate .C yes|no .PP Normally .C ntpq does not authenticate requests unless they are write requests. The command .C authenticate yes causes .C ntpq to send authentication with all requests it makes. .PP .C debug .C more|less|no .PP Turns internal query program debugging on and off. .PP .C quit .PP Exit .CR ntpq . .SH CONTROL MESSAGE COMMANDS .PP Each peer known to an NTP server has a 16 bit integer .I association identifier assigned to it. NTP control messages which carry peer variables must identify the peer to which the values correspond by including its association ID. An association ID of 0 is special, and indicates the variables are system variables, whose names are drawn from a separate name space. .PP Control message commands result in one or more NTP mode 6 messages being sent to the server, and cause the data returned to be printed in some format. Most commands currently implemented send a single message and expect a single response. The current exceptions are the .C peers command, which will send a preprogrammed series of messages to obtain the data it needs, and the .C mreadlist and .C mreadvar commands, which will iterate over a range of associations. .PP .C associations .PP Obtains and prints a list of association identifiers and peer statuses for in\-spec peers of the server being queried. The list is printed in columns. The first of these is an index numbering the associations from 1 for internal use; the second is the actual association identifier returned by the server; and the third is the status word for the peer. This is followed by a number of columns containing data decoded from the status word. Note that the data returned by the .C associations command is cached internally in .CR ntpq . The index can be use when dealing with servers that use association identifiers which are hard for humans to type. The form .I &index may be used for any subsequent commands that require an association identifier as an argument. .PP .C lassocations .PP Obtains and prints a list of association identifiers and peer statuses for all associations for which the server is maintaining state. This command differs from the .C associations command only for servers which retain state for out\-of\-spec client associations (i.e. fuzzballs). Such associations are normally omitted from the display when the .C associations command is used, but are included in the output of .C lassociations .PP .C passociations .PP Prints association data concerning in\-spec peers from the internally cached list of associations. This command performs identically to the .C associations except that it displays the internally stored data rather than making a new query. .PP .C lpassociations .PP Print data for all associations, including out\-of\-spec client associations, from the internally cached list of associations. This command differs from .C passociations only when dealing with fuzzballs. .PP .C pstatus .I assocID .PP Sends a read status request to the server for the given association. The status value, the names, and values of the peer variables returned will be printed. .PP .C readvar [ .I assocID ] [ .IR [,...] ] .PP Requests that the values of the specified variables be returned by the server by sending a read variables request. If the association ID is omitted or is .C 0 the variables are system variables; otherwise they are peer variables and the values returned will be those of the corresponding peer. Omitting the variable list will send a request with no data which should induce the server to return a default display. .PP .C rv [ .I assocID ] [ .IR [,...] ] .PP An easy\-to\-type short form for the .C readvar command. .PP .C writevar .I assocID .IR = [,...] .PP Like the .C readvar request, except the specified variables are written instead of read. .PP .C readlist [ .I assocID ] .PP Requests that the values of the variables in the internal variable list be returned by the server. If the association ID is omitted or is 0, the variables are assumed to be system variables; otherwise they are treated as peer variables. If the internal variable list is empty a request is sent without data, which should induce the remote server to return a default display. .PP .C rl [ .I assocID ] .PP An easy\-to\-type short form of the .C readlist command. .PP .C mreadvar .I assocID .I assocID [ .IR [,...] ] .PP Like the .C readvar command except the query is done for each of a range of (nonzero) association IDs. This range is determined from the association list cached by the most recent .C associations command. .PP .C mrv .I assocID .I assocID [ .IR [,...] ] .PP An easy\-to\-type short form of the .C mreadvar command. .PP .C mreadlist .I assocID .I assocID .PP Like the .C readlist command except the query is done for each of a range of (nonzero) association IDs. This range is determined from the association list cached by the most recent .C associations command. .PP .C mrl .I assocID .I assocID .PP An easy\-to\-type short form of the .C mreadlist command. .PP .C clocklist [ .I assocID ] .PP Requests for the server's clock variables to be sent. Servers which have a radio clock or other external synchronization will respond positively to this. If the association identifier is omitted or is .CR 0 , the request is for the variables of the .C system clock and will generally get a positive response from all servers with a clock. If the server treats clocks as pseudo\-peers, and hence can possibly have more than one clock connected at once, referencing the appropriate peer association ID will show the variables of a particular clock. .PP .C clockvar [ .I assocID ] [ .IR [,...] ] .PP Requests that a list of the server's clock variables be sent. Servers which have a radio clock or other external synchronization will respond positively to this. If the association identifier is omitted or is .CR 0 , the request is for the variables of the .C system clock and will generally get a positive response from all servers with a clock. If the server treats clocks as pseudo\-peers, and hence can possibly have more than one clock connected at once, referencing the appropriate peer association ID will show the variables of a particular clock. Omitting the variable list will cause the server to return a default variable display. .PP .C cv [ .I assocID ] [ .IR [,...] ] .PP An easy\-to\-type short form of the .C clockvar command. .PP .C peers .PP Obtains a list of in\-spec peers of the server, along with a summary of each peer's state. Summary information includes the address of the remote peer, the reference ID (0.0.0.0 if the reference ID is unknown), the stratum of the remote peer, the polling interval, in seconds, the reachability register, in octal, and the current estimated delay, offset and dispersion of the peer, all in seconds. In addition, the character in the left margin indicates the fate of this peer in the clock selection algorithm. Characters only appear beside peers which were included in the final stage of the clock selection algorithm. A .C . indicates that this peer was cast off in the falseticker detection, while a .C + indicates that the peer made it through. A .C * denotes the peer with which the server is currently synchronizing. Note that since the .C peers command depends on the ability to parse the values in the responses it gets, it may fail to work from time to time with servers that poorly control the data formats. .PP The contents of the host field may be one of four forms. It may be a host name, an IP address, a reference clock implementation name with its parameter, or .CR REFCLK ( .RI < "implementation number" >, .RI < parameter >). On .C hostnames no, only IP\-addresses will be displayed. .PP .C lpeers .PP Like .C peers, except a summary is printed of all associations for which the server is maintaining state. This can produce a much longer list of peers from fuzzball servers. .PP .C opeers .PP An old form of the .C peers command with the reference ID replaced by the local interface address. .PP .C lopeers .PP An old form of the .C lpeers command with the reference ID replaced by the local interface address. .PP .SH FILES .TP 30 .C /etc/ntp.keys Contains the encription keys used for authentication. .SH AUTHOR .C ntpq was developed by Dennis Ferguson at the University of Toronto. .SH SEE ALSO ntpdate(1M), xntpd(1M), .br .SM DARPA Internet Request For Comments .SM RFC1035 Assigned Numbers. .\" .\" index@\f4ntpq\f1 \- Network Time Protocol query program@@@\f3ntpq(1M)\f1 .\" index@\f1query program, Network Time Protocol@@@\f3ntpq(1M)\f1 .\" index@\f1NTP, query program@@@\f3ntpq(1M)\f1 .\" index@\f1Network Time Protocol (NTP), query program@@@\f3ntpq(1M)\f1 .\" .\" toc@\f3ntpq(1M)\f1:\0\0\f4ntpq\f1@@@Network Time Protocol query program .\" .\" fileset_database@ntpq.1m INETSVCS-MAN .\" $Header: acctsh.1m,v 72.4 94/11/14 12:02:10 ssa Exp $ .TA a .TH acctsh 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chargefee, ckpacct, dodisk, lastlogin, monacct, nulladm, prctmp, prdaily, prtacct, shutacct, startup, turnacct \- shell procedures for accounting .SH SYNOPSIS .C /usr/sbin/acct/chargefee .I login-name number .PP .C /usr/sbin/acct/ckpacct .RI [ \|blocks\| ] .PP .C /usr/sbin/acct/dodisk .RC [ -o ] .RI [ \|files \0 ...\|] .PP .C /usr/sbin/acct/lastlogin .PP .C /usr/sbin/acct/monacct .I number .PP .C /usr/sbin/acct/nulladm .I file .PP .C /usr/sbin/acct/prctmp .PP .C /usr/sbin/acct/prdaily .RC [ -l ] .RC [ -c ] .RC [ \c .IR mmdd\| ] .PP .C /usr/sbin/acct/prtacct .I file .RI [ \|heading\| ] .PP .C /usr/sbin/acct/shutacct .RI [ \|reason\| ] .PP .C /usr/sbin/acct/startup .PP .C /usr/sbin/acct/turnacct .CR on \0\(or\0 off \0\(or\0 switch .SH DESCRIPTION .TP 15 .C chargefee Can be invoked to charge a .I number of units to .IR login-name . A record is written to .CR /var/adm/fee , to be merged with other accounting records during the night. .TP .C ckpacct Should be initiated via .IR cron (1M). It periodically checks the size of .CR /var/adm/pacct . If the size exceeds .IR blocks , 1000 by default, .C turnacct is invoked with argument .IR switch . If the number of free disk blocks in the .C /var file system falls below 500, .C ckpacct automatically turns off the collection of process accounting records via the .C off argument to .CR turnacct . When at least this number of blocks is restored, the accounting will be activated again. This feature is sensitive to the frequency at which .C ckpacct is executed, usually by .CR cron . .TP .C dodisk Should be invoked by .C cron to perform the disk accounting functions. By default, it will do disk accounting on the special files in .C /etc/fstab. If the .C -o flag is used, it does a slower version of disk accounting by login directory. .I files specifies the one or more filesystem names where disk accounting is to be done. If .I files is used, disk accounting will be done on these filesystems only. If the .C -o flag is used, .I files should be mount points of mounted filesystem. If omitted, they should be the special file names of mountable filesystems. .TP .C lastlogin Invoked by .C runacct to update .C /var/adm/acct/sum/loginlog which shows the last date on which each user logged in (see .IR runacct (1M)). .TP .C monacct Should be invoked once each month or each accounting period. .I number indicates which month or period it is. If .I number is not given, it defaults to the current month (01 through 12). This default is useful if .C monacct is to executed via .CR cron on the first day of each month. .C monacct creates summary files in .C /var/adm/acct/fiscal and restarts summary files in .CR /var/adm/acct/sum . .TP .C nulladm Creates .I file with mode 664 and ensures that owner and group are .CR adm . It is called by various accounting shell procedures. .TP .C prctmp Can be used to print the session record file normally .C /var/adm/acct/nite/ctmp created by .C acctcon1 (see .IR acctcon (1M)). .TP .C prdaily Invoked by .C runacct (see .IR runacct (1M)) to format a report of the previous day's accounting data. The report resides in .CI /var/adm/acct/sum/rprt mmdd where .I mmdd is the month and day of the report. The current daily accounting reports may be printed by typing .IR prdaily . Previous days' accounting reports can be printed by using the .I mmdd option and specifying the exact report date desired. The .C -l flag prints a report of exceptional usage by login id for the specifed date. Previous daily reports are cleaned up and therefore inaccessible after each invocation of .CR monacct . The .C -c flag prints a report of exceptional resource usage by command, and can be used on current day's accounting data only. .TP .C prtacct Can be used to format and print any total accounting .RC ( tacct ) file. .TP .C shutacct Should be invoked during a system shutdown to turn process accounting off and append a ``reason'' record to .CR /var/adm/wtmp . .TP .C startup Should be called by system startup scripts to turn the accounting on whenever the system is brought up. .TP .C turnacct An interface to .C accton (see .IR acct (1M)) to turn process accounting .C on or .CR off . The .C switch argument turns accounting off, moves the current .C /var/adm/pacct to the next free name in .CI /var/adm/pacct incr then turns accounting back on again. .RI ( incr is a number starting with .C 1 and incrementing by one for each additional .C pacct file.) .C turnacct is called by .CR ckpacct , and thus can be run under .C cron and used to keep .C pacct to a reasonable size. .SH FILES .TP 40 .C /usr/sbin/acct holds all accounting commands listed in section (1M) of this manual .PD 0 .TP .C /var/adm/fee accumulator for fees .TP .C /var/adm/acct/nite working directory .TP .C /var/adm/pacct current file for per-process accounting .TP .C /var/adm/pacct* used if .C pacct gets large, and during execution of daily accounting procedure .TP .C /usr/sbin/acct/ptecms.awk contains the limits for exceptional usage by command name .TP .C /usr/sbin/acct/ptelus.awk contains the limits for exceptional usage by login id .TP .C /var/adm/acct/sum summary directory, should be saved .TP .C /var/adm/wtmp login/logoff summary .PD .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), cron(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR chargefee ": SVID2, SVID3" .PP .CR ckpacct ": SVID2, SVID3" .PP .CR dodisk ": SVID2, SVID3" .PP .CR lastlogin ": SVID2, SVID3" .PP .CR monacct ": SVID2, SVID3" .PP .CR prctmp ": SVID2, SVID3" .PP .CR prdaily ": SVID2, SVID3" .PP .CR prtacct ": SVID2, SVID3" .PP .CR shutacct ": SVID2, SVID3" .PP .CR startup ": SVID2, SVID3" .PP .CR turnacct ": SVID2, SVID3" .\" .\" .\" index@\f1process accounting@@@see accounting .\" index@\f1accounting: \f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4turnacct\f1 \- turn on or turn off process accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1bill fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1user, bill fee to, based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1disk accounting, perform@@@\f3acctsh(1M)\f1 .\" index@\f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1user, show last login date for each@@@\f3acctsh(1M)\f1 .\" index@\f1last login date, show for each user@@@\f3acctsh(1M)\f1 .\" index@\f1login date, show last for each user@@@\f3acctsh(1M)\f1 .\" index@\f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1periodic accounting summary files, create@@@\f3acctsh(1M)\f1 .\" index@\f1accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1files: accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1summary files, accounting, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1create empty administration file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1empty administration file owned by \f3adm\f1 with mode 664, create@@@\f3acctsh(1M)\f1 .\" index@\f1administration file owned by \f3adm\f1 with mode 664, create empty@@@\f3acctsh(1M)\f1 .\" index@\f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f4acctcon1\f1 \- print session record file created by@@@\f3acctsh(1M)\f1 .\" index@\f1print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1files, accounting: print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1session record file created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f1record file, session, created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1total accounting (\f4tacct\f1) file, print any@@@\f3acctsh(1M)\f1 .\" index@\f1accounting (\f4tacct\f1) file, print any total@@@\f3acctsh(1M)\f1 .\" index@\f4tacct\f1 (total accounting) file, print any@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting: \f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" index@\f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting data and command usage summary, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f1command usage summary and accounting data, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1system shutdown, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f1shutdown, system, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1system startup, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f1startup, system, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f4turnacct\f1 \- turn process accounting on or off@@@\f3acctsh(1M)\f1 .\" index@\f1shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f1system accounting, shell procedures for@@@\f3acctsh(1M)\f1 .\" .\"" Main TOC entry .\" toc@\f3acctsh(1M)\f1:\0\0\f4chargefee\f1, \f4ckpacct\f1, \f4dodisk\f1, \f4lastlogin\f1, \f4monacct\f1, \f4nulladm\f1, \f4prctmp\f1, \f4prdaily\f1,\n\f4prtacct\f1, \f4shutacct\f1, \f4startup\f1, \f4turnacct\f1@@@shell procedures for accounting .\" .\" toc@\f4chargefee\f1:\0\0shell procedures for accounting, charge fee to user@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4ckpacct\f1:\0\0shell procedures for accounting, check size of accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4dodisk\f1:\0\0shell procedures for accounting, perform disk accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4lastlogin\f1:\0\0shell procedures for accounting, show last login date@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4monacct\f1:\0\0shell procedures for accounting, create accounting summary@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4nulladm\f1:\0\0shell procedures for accounting, create null file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prctmp\f1:\0\0shell procedures for accounting, print session record file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prdaily\f1:\0\0shell procedures for accounting, print daily report@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prtacct\f1:\0\0shell procedures for accounting, print accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4shutacct\f1:\0\0shell procedures for accounting, turn off accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4startup\f1:\0\0shell procedures for accounting, start up accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4turnacct\f1:\0\0shell procedures for accounting, turn on or off process accounting@@@\f1see \f3acctsh(1M)\f1 .\" .\" links@acctsh.1m chargefee.1m .\" links@acctsh.1m ckpacct.1m .\" links@acctsh.1m dodisk.1m .\" links@acctsh.1m lastlogin.1m .\" links@acctsh.1m monacct.1m .\" links@acctsh.1m nulladm.1m .\" links@acctsh.1m prctmp.1m .\" links@acctsh.1m prdaily.1m .\" links@acctsh.1m prtacct.1m .\" links@acctsh.1m shutacct.1m .\" links@acctsh.1m startup.1m .\" links@acctsh.1m turnacct.1m .\" .\" fileset_database@acctsh.1m SYS-ADMIN-MAN .\" $Header: ocd.1m,v 74.1 95/01/25 15:53:58 ssa Exp $ .TA o .TH ocd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ocd \- outbound connection daemon used by DDFA software .SH SYNOPSIS .CR ocd .CI \-f pseudonym .CI \-n node_name .RC [ \-b\c .IR board_no ] .RC [ \-c\c .IR config_file ] .RC [ \-l\c .IR log_level ] .ifn .br .ifn \0\0\0\0 .RC [ \-p\c .IR port_no ] .SH DESCRIPTION The Outbound Connection Daemon .RC ( ocd ) is part of the Data Communications and Terminal Controller (DTC) Device File Access (DDFA) software. It manages the connection and data transfer to the remote terminal server port. It can be spawned from the Dedicated Port Parser .RC ( dpp ) or run directly from the shell. .PP For performance reasons, .CR ocd does not have a debug mode. However, a version called .CR ocdebug with debug facilities is available. .PP See .IR ddfa (7) for more information on how to configure the DDFA software and for an explanation of how it works. .PP .CR ocd logs important messages and error conditions to .CR /var/adm/syslog . .SS Options .CR ocd recognizes the following options: .RS .TP 18 .CI \-b board_no The board number of a DTC. If it is omitted, the port number option must contain the full TCP service port address. The .CR \-b and .CR \-p options must not be used if the IP address given in the .CR \-n option is the IP address of a port. .IP If the .CR \-n option explicitly names a terminal server port, the .CR \-b option is not needed. .TP .CI \-c config_file Specify the name (including the absolute path) of the configuration file used to profile the terminal server port. If this option is omitted, the default values specified in the default .CR pcf file .RC ( /usr/examples/ddfa/pcf ) are used. If the file specified does not exist, an error message is logged and the following values are used (note that the values for .CR open_tries and .CR open_timer are different from the default values): .nf .RS .IP .C "telnet_mode: enable" .C "timing_mark: enable" .C "telnet_timer: 120" .C "binary_mode: disable" .C "open_tries: 0" .C "open_timer: 0" .C "close_timer: 0" .C "status_request: disable" .C "status_timer: 30" .C "eight_bit: disable" .C "tcp_nodelay: enable" .fi .RE .TP .CI \-f pseudonym The absolute or relative path to the device file that is linked by the software to the reserved .CR pty . Applications use .IR pseudonym and not the dynamically allocated .CR pty slave. .TP .CI \-l log_level Specify the logging level. It determines the severity of messages sent to .CR /var/adm/syslog . The logging levels (and how they relate to system logging levels) are as follows: .RS .RS .TP .CR 0 Log only LOG_CRIT messages. .PD 0 .TP .CR 1 Log only LOG_CRIT and LOG_ERR messages. .TP .CR 2 Log only LOG_CRIT, LOG_ERR, and LOG_WARNING messages. .TP .CR 3 Log all messages. .PD .RE .RE .IP If this option is omitted, the logging level is set to 1. .TP .CI \-n node_name The IP address of the terminal server or the port. .TP .CI \-p port_no A DTC port number or, if the .CR \-b option is omitted, the TCP port service address that will be used by the software to access the port. If the value is omitted, the value .CR 23 (Telnet) is used by default. .RE .SH WARNINGS In order to ensure that commands (such as .CR ps ) display the correct device file name (that is, the .IR pseudonym ), all pseudonyms should be placed into the directory .CR /dev/telnet . If pseudonyms are not specified for placement in this directory, the correct display of device file names with many commands is not guaranteed. .PP Also, in order to reliably handle timing mark negotiations (and ensure that files printing on a printer attached to a terminal server have been completely flushed to that printer), the following line must be added near the end of each printer interface script for printers attached to a terminal server: .IP .C "stty exta <&1 2>/dev/null" .PP The printer interface scripts reside in the directory .CR /etc/lp/interface . The line must be added just prior to the final .CR exit command in each printer interface script. .PP If this line is not added as specified, the printing reliability of printers attached to a terminal server is not guaranteed. .SH FILES .nf .CR /usr/examples/ddfa/dp .CR /usr/examples/ddfa/pcf .CR /usr/sbin/dpp .CR /usr/sbin/ocd .CR /usr/sbin/ocdebug .CR /var/adm/dpp_login.bin .CR /var/adm/utmp.dfa .fi .SH SEE ALSO dpp(1M), ocdebug(1M), syslog(3C), dp(4), pcf(4), ddfa(7). .\" .\" toc@\f3ocd(1M)\f1:\0\0\f4ocd\f1@@@outbound connection daemon used by DDFA software .\" .\" index@\f4ocd\f1 \- outbound connection daemon used by DDFA software@@@\f3ocd(1M)\f1 .\" index@outbound connection daemon used by DDFA software@@@\f3ocd(1M)\f1 .\" index@connection daemon used by DDFA software, outbound@@@\f3ocd(1M)\f1 .\" index@daemon used by DDFA software, outbound connection@@@\f3ocd(1M)\f1 .\" index@DDFA software, outbound connection daemon used by@@@\f3ocd(1M)\f1 .\" $Header: ocdebug.1m,v 74.1 95/01/25 15:54:31 ssa Exp $ .TA o .TH ocdebug 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ocdebug \- outbound connection daemon debug utility used by DDFA software .SH SYNOPSIS .CR ocdebug .CI \-f pseudonym .CI \-n node_name .RC [ \-b\c .IR board_no\| ] .RC [ \-c\c .IR config_file\| ] .ifn .br .ifn \0\0\0\0 .RC [ \-d\c .IR debug_level\| ] .RC [ \-l\c .IR log_level\| ] .ift .br .ift \0\0\0\0 .RC [ \-p\c .IR port_no\| ] .SH DESCRIPTION The .CR ocdebug daemon is the debugging version of the Outbound Connection Daemon .RC ( ocd ). .CR ocd is part of the Data Communications and Terminal Controller (DTC) Device File Access (DDFA) software. It manages the connection and data transfer to the remote terminal server port. .PP See .IR ddfa (7) for more information on how to configure the DDFA software and for an explanation of how it works. .PP Debugging may be toggled interactively by sending the .CR SIGUSR1 signal to the process using: .IP .CI "kill \-16 \&" pid\f1. .PP .CR ocdebug logs important messages and error conditions to .CR /var/adm/syslog . Debug messages are logged to the file .CI /var/adm/ocd pid and the file name is displayed at the start of debugging. .SS Options .CR ocdebug recognizes the following options. Apart from the .CR \-d option they are the same as the .CR ocd options. .RS .TP 15 .CI \-b board_no Specify the board number of a DTC. If it is omitted, the port number option must contain the full TCP service port address. The .CR \-b and .CR \-p options must not be used if the IP address given in the .CR \-n option is the IP address of a port. .IP If the .CR \-n option explicitly names a terminal server port, the .CR \-b option is not needed. .TP .CI \-c config_file Specify the name (including the absolute path) of the configuration file used to profile the terminal server port. If this value is omitted, the values specified in the default .CR pcf file .RC ( /usr/examples/ddfa/pcf ) are used. If the file specified does not exist, an error message is logged and the following values are used (note that the values for .I open_tries and .I open_timer are different from the default values): .RS .nf .IP .C "telnet_mode: enable" .C "timing_mark: enable" .C "telnet_timer: 120" .C "binary_mode: disable" .C "open_tries: 0" .C "open_timer: 0" .C "close_timer: 0" .C "status_request: disable" .C "status_timer: 30" .C "eight_bit: disable" .C "tcp_nodelay: enable" .fi .RE .TP .CI \-d debug_level Specify the level of debugging. Levels can be added together to accumulate debugging functions. For example, .CR \-d7 enables all levels and .CR \-d3 enables only the first two levels. The levels are: .RS .RS .TP .CR 0 No debug messages. .PD 0 .TP .CR 1 Trace procedure entry/exit logged. .TP .CR 2 Additional tracking messages logged. .TP .CR 4 Data structures dumped. .PD .RE .RE .TP .CI \-f pseudonym Specify the absolute or relative path to the device file, which is linked by the software to the reserved .CR pty . Applications use the pseudonym and not the dynamically allocated .CR pty slave. .TP .CI \-l log_level Specify the logging level. It determines the severity of messages sent to .CR /var/adm/syslog . The logging levels (and how they relate to system logging levels) are as follows: .RS .RS .TP .PD 0 .CR 0 Log only LOG_CRIT messages. .TP .CR 1 Log only LOG_CRIT and LOG_ERR messages. .TP .CR 2 Log only LOG_CRIT, LOG_ERR, and LOG_WARNING messages. .TP .CR 3 Log all messages. .TP If it is omitted, the logging level is set to 1. .PD .RE .RE .TP .CI \-n node_name Specify the IP address of the terminal server or the port. .TP .CI \-p port_no Specify a DTC port number or, if the .CR \-b option is omitted, the TCP port service address that will be used by the software to access the port. If the value is omitted, the value .CR 23 (Telnet) is used by default. .RE .SH WARNINGS In order to ensure that commands (such as .IR ps ) display the correct device file name (that is, the .IR pseudonym ), all pseudonyms should be placed into the directory .CR /dev/telnet . If pseudonyms are not specified for placement in this directory, the correct display of device file names with many commands is not guaranteed. .PP Also, in order to reliably handle timing mark negotiations (and ensure that files printing on a printer attached to a terminal server have been completely flushed to that printer), the following line must be added near the end of each printer interface script for printers attached to a terminal server: .IP .C "stty exta <&1 2>/dev/null" .PP The printer interface scripts reside in the directory .CR /etc/lp/interface . The line must be added just prior to the final 'exit' command in each printer interface script. .PP If this line is not added as specified, the printing reliability of printers attached to a terminal server is not guaranteed. .SH FILES .nf .CR /usr/examples/ddfa/dp .CR /usr/examples/ddfa/pcf .CR /usr/sbin/dpp .CR /usr/sbin/ocd .CR /usr/sbin/ocdebug .CR /var/adm/dpp_login.bin .CI /var/adm/ocd pid .CR /var/adm/syslog .CR /var/adm/utmp.dfa .fi .SH SEE ALSO dpp(1M), ocd(1M), syslog(3C), dp(4), pcf(4), ddfa(7). .\" .\" toc@\f3ocdebug(1M)\f1:\0\0\f4ocdebug\f1@@@outbound connection daemon debug utility used by DDFA software .\" .\" index@\f4ocdebug\f1 \- outbound connection daemon debug utility used by DDFA software@@@\f3ocdebug(1M)\f1 .\" index@outbound connection daemon debug utility used by DDFA software@@@\f3ocdebug(1M)\f1 .\" index@connection daemon debug utility used by DDFA software, outbound@@@\f3ocdebug(1M)\f1 .\" index@daemon debug utility used by DDFA software, outbound connection@@@\f3ocdebug(1M)\f1 .\" index@debug utility used by DDFA software, outbound connection daemon@@@\f3ocdebug(1M)\f1 .\" index@software, outbound connection daemon debug utility used by DDFA@@@\f3ocdebug(1M)\f1 .\" $Header: opx25.1m,v 72.5 94/12/16 09:54:54 ssa Exp $ .TA o .TH opx25 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME opx25 \- execute \s-1HALGOL\s0 programs .SH SYNOPSIS .C /usr/lbin/uucp/\s-1X25\s0/opx25 .RC [ -f .IR scriptname \|] .RC [ -c .IR char \|] .RC [ -o\c .IR file-descriptor \|] .RC [ -i\c .IR file-descriptor \|] .RC [ -n\c .IR string \|] .RC [ -d \|] .RC [ -v \|] .br .SH DESCRIPTION HALGOL is a simple language for communicating with devices such as modems and X.25 PADs. It has simple statements similar to .CI send \0xxx and .CI expect \0yyy that are described below. .SS Options: .CR opx25 recognizes the following options: .RS .TP 15 .CI -f \0script Causes .CR opx25 to read script as the input program. If .CR -f is not specified, .CR opx25 reads the standard input as a script. .TP .CI -c \0char Causes .CR opx25 to use .IR char as the first character in the input stream instead of actually reading it from the input descriptor. This is useful sometimes when the program that calls .CR opx25 is forced to read a character but then cannot ``unread'' it. .TP .CI -o \0number Causes .CR opx25 to use .IR number for the output file descriptor (i.e., the device to use for .CR send ). The default is 1. .TP .CI -i \0number Causes .CR opx25 to use 'number' for the input file descriptor (ie, the device to use for 'expect'). The default is 0. .TP .CI -n \0string Causes .CR opx25 to save this string for use when .CR \e# is encountered in a .CR send command. .TP .C -d Causes .CR opx25 to turn on debugging mode. .TP .C -v Causes .CR opx25 to turn on verbose mode. .RE .PP An .CR opx25 script file contains lines of the following types: .RS .TP 15 (empty) Empty lines are ignored. .TP .C / Lines beginning with a slash .RC ( / ) are ignored (comments) .TP .I ID .I ID denotes a label, and is limited to alphanumerics or .CR _ . .TP .CI send \0string .I string must be surrounded by double quotes. The text is sent to the device specified by the .CR -o option. Non-printable characters are represented as in C; i.e., as \eDDD, where DDD is the octal ascii character code. .CR \e# in a send string is the string that followed the .CR -n option. .TP .C break Send a break "character" to the device. .TP .CI expect " number string" Here .IR number is how many seconds to wait before giving up. 0 means wait forever, but this is not advised. Whenever .IR string appears in the input within the time allotted, the command succeeds. Thus, it is not necessary to specify the entire string. For example, if you know that the PAD will send several lines followed by an .CR @ prompt, you could just use .CR @ as the string. .TP .CI run " program args" The program .RC ( sleep , .CR date , etc.) is run with the args specified. Do not use quotes here. Also, the program is invoked directly (using .CR execp ), so wild cards, redirection, etc. are not possible. .TP .CI error \0ID If the most recent expect or run encountered an error, go to the label .IR ID . .TP .CI exec " program args" Similar to .CR run , but does not fork. .TP .CI echo " string" Similar to .CR send , but goes to standard error instead of to the device. .TP .C set debug Sets the program in debug mode. It echoes each line to .CR /tmp/opx25.log , as well as giving the result of each expect and run. This can be useful for writing new scripts. The command .CR set .CR nodebug disables this feature. .TP .C set log Sends subsequent incoming characters to .CR /var/uucp/.Log/LOGX25 . This can be used in the .CR *.in file as a security measure, because part of the incoming data stream contains the number of the caller. There is a similar feature in .CR getx25 ; it writes the time and the login name into the same logfile. The command .CR set .CR nolog disables this feature. .TP .C set numlog Similar to .CR "set log" , but better in some cases because it sends only digits to the log file, and not other characters. The command .CR set .CR nonumlog disables this feature. .TP .CI timeout \0number Sets a global timeout value. Each expect uses time in the timeout reservoir; when this time is gone, the program gives up (exit 1). If this command is not used, there is no global timeout. Also, the global timeout can be reset any time, and a value of 0 turns it off. .TP .CI exit \0number Exits with this value. 0 is success; anything else is failure. .RE .PP To perform a rudimentary test of configuration files, run .CR opx25 by hand, using the .CR -f option followed by the name of the script file. .CR opx25 then sends to standard output and expects from standard input; thus you can type the input, observe the output, and use the .CR echo command to see messages. See the file .CR /usr/lbin/uucp/X25/ventel.out for a good example of HALGOL programming. .SH AUTHOR .CR opx25 was developed by HP. .SH SEE ALSO getx25(1), uucp(1). .\" .\" index@\f4opx25\f1 \- execute HALGOL programs@@@\f3opx25(1M)\f1 .\" index@\f1execute HALGOL programs@@@\f3opx25(1M)\f1 .\" index@\f1HALGOL programs, execute@@@\f3opx25(1M)\f1 .\" index@\f1programs, HALGOL, execute@@@\f3opx25(1M)\f1 .\" .\" toc@\f3opx25(1M)\f1:\0\0\f4opx25\f1@@@execute HALGOL programs .\" .\" fileset_database@opx25.1m SYS-ADMIN-MAN .\" $Header: ospf_monito.1m,v 72.2 94/12/09 15:02:19 ssa Exp $ .\" .\" Gated Release 3.5 .\" Copyright (c) 1990,1991,1992,1993,1994 by Cornell University. All rights .\" reserved. Refer to Particulars and other Copyright notices at the end of this .\" file. .\" .TA o .TH ospf_monitor 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH "NAME" ospf_monitor \- monitor OSPF gateways .SH "SYNOPSIS" .C ospf_monitor .IR mon_db_file .SH "DESCRIPTION" Use the .CR ospf_monitor command to query OSPF routers. The .CR ospf_monitor command operates in interactive mode. It allows the user to query the various OSPF routers to provide detailed information on IO statistics, error logs, link-state data bases, AS external data bases, the OSPF routing table, configured OSPF interfaces, and OSPF neighbors. .PP .I mon_db_file is the complete pathname of a database composed of records configuring destinations for .CR ospf_monitor remote commands. Each destination record is a single-line entry which lists the destination IP address, the destination hostname, and an OSPF authentication key (if authentication is activated by the destination). Since authentication keys may be present in the destination records, it is recommended that general access to this database be restricted. .PP Refer to RFC-1583 (OSPF Specification, version 2) for details about OSPF database and packet formats. .SS COMMANDS Upon entering interactive mode, .CR ospf_monitor presents this prompt: .RS .C "[ # ] dest command params >" .RE From this prompt, you can enter any of the .CR ospf_monitor interactive commands. Interactive commands can be interrupted at any time via a keyboard interrupt. Note that the command line length must be less than 200 characters. .SS "Local Commands" .TP 10 .CR "?" Display all local commands and their functions. .TP .CR "?R" Display all remote commands and their functions. .TP .CR "d" Display all configured destinations. This command displays .IR dest_index , the IP address, and the hostname of all potential .CR ospf_monitor command destinations configured in .IR mon_db_file . .TP .CR "h" Display the command history buffer showing the last 30 interactive commands. .TP .CR "x" Exit the .CR ospf_monitor program. .TP 35 .CI @ remote_command Send .IR remote_command to the same (previous) destination. .TP 35 .CI @ "dest_index remote_command" Send .IR remote_command to configured destination .IR dest_index . .TP 15 .CI F filename Send all .CR ospf_monitor output to .IR filename. .TP 10 .CR S Send all .CR ospf_monitor output to stdout. .PP .SS "Remote Commands" .TP 10 .CI a " area_id type ls_id adv_rtr" .PP Display link state advertisement. .IR area_id is the OSPF area for which the query is directed. .IR adv_rtr is the router-id of the router which originated this link state advertisement. .IR type specifies the type of advertisement to request and should be specified as follows: .RS .IP "1" Request the router links advertisements. They describe the collected states of the router's interfaces. For this type of request, the .IR ls_id field should be set to the originating router's Router ID. .IP "2" Request the network links advertisements. They describe the set of routers attached to the network. For this type of request, the .IR ls_id field should be set to the IP interface address of the network's Designated Router. .IP "3" Request the summary link advertisements describing routes to networks. They describe inter-area routes, and enable the condensing of routing information at area borders. For this type of request, the .IR ls_id field should be set to the destination network's IP address. .IP "4" Request the summary link advertisements describing routes to AS boundary routers. They describe inter-area routes, and enable the condensing of routing information at area borders. For this type of request, the .IR ls_id field should be set to the Router ID of the described AS boundary router. .IP "5" Request the AS external link advertisements. They describe routes to destinations external to the Autonomous System. For this type of request, the .IR ls_id field should be set to the destination network's IP address. .RE .TP .CR "c" Display cumulative log. This log includes input/output statistics for monitor request, hello, data base description, link-state request, link-state update, and link-state ack packets. Area statistics are provided which describe the total number of routing neighbors and number of active OSPF interfaces. Routing table statistics are summarized and reported as the number of intra-area routes, inter-area routes, and AS external data base entries. .TP .CR "e" Display cumulative errors. This log reports the various error conditions which can occur between OSPF routing neighbors and shows the number of occurrences for each. .TP .CI l " retrans" Display the link-state database (except for ASE's). This table describes the routers and networks making up the AS. If .IR retrans is non-zero, the retransmit list of neighbors held by this lsdb structure will be printed. .TP .CI A " retrans" Display the AS external data base entries. This table reports the advertising router, forwarding address, age, length, sequence number, type, and metric for each AS external route. If .IR retrans is non-zero, the retransmit list of neighbors held by this lsdb structure will be printed. .TP .CR "o" Display the OSPF routing table. This table reports the AS border routes, area border routes, summary AS border routes, and networks currently managed via OSPF. .TP .CR "I" Display all interfaces. This report shows all interfaces configured for OSPF. Information reported includes the area, interface IP address, interface type, interface state, cost, priority, and the IP address of the DR and BDR for the network. .TP .CR "N" Display all OSPF routing neighbors. Information reported includes the area, local interface address, router ID, neighbor IP address, state, and mode. .PP .SH "AUTHOR" Rob Coltun of University of Maryland .br Jeffrey C. Honig of Cornell University .SH "SEE ALSO" gated (1M), gdc (1M), ripquery (1M), gated.conf(4). .br GateD Documentation .br GateD Configuration Guide .\" .\" COPYRIGHT INFORMATION .\" .\" This package and associated documentation is Copyright (c) .\" 1990,1991,1992,1993,1994 Cornell University. .\" .\" This software contains code that is Copyright (c) 1988 Regents of the .\" University of California. .\" .\" This package contains code that is Copyright (c) 1989, 1990, 1991 .\" The University of Maryland, College Park, Maryland., all rights .\" reserved. .\" .\" ------------------------------------------------------------------------ .\" .\" GateD, Release 3.5 .\" .\" Copyright (c) 1990,1991,1992,1993,1994 by Cornell University .\" .\" THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT .\" LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY .\" AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" Royalty-free licenses to redistribute GateD Release .\" 3 in whole or in part may be obtained by writing to: .\" .\" GateDaemon Project .\" Information Technologies/Network Resources .\" 200 CCC .\" Cornell University .\" Ithaca, NY 14853-2601 USA .\" .\" GateD is based on Kirton's EGP, UC Berkeley's routing .\" daemon (routed), and DCN's HELLO routing Protocol. .\" Development of GateD has been supported in part by the .\" National Science Foundation. .\" .\" Please forward bug fixes, enhancements and questions to the .\" gated mailing list: gated-people@gated.cornell.edu. .\" .\" ------------------------------------------------------------------------ .\" .\" Portions of this software may fall under the following .\" copyrights: .\" .\" Copyright (c) 1988 Regents of the University of California. .\" .\" Redistribution and use in source and binary forms are .\" permitted provided that the above copyright notice and .\" this paragraph are duplicated in all such forms and that .\" any documentation, advertising materials, and other .\" materials related to such distribution and use .\" acknowledge that the software was developed by the .\" University of California, Berkeley. The name of the .\" University may not be used to endorse or promote .\" products derived from this software without specific .\" prior written permission. THIS SOFTWARE IS PROVIDED .\" ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, .\" INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" .\" .\" index@\f4ospf_monitor\f1: monitor OSPF gateways@@@\f3ospf_monitor(1M)\f1 .\" index@\f4ospf_monitor\f1: OSPF gateways, monitor@@@\f3ospf_monitor(1M)\f1 .\" index@\f4ospf_monitor\f1: gateways, monitor OSPF@@@\f3ospf_monitor(1M)\f1 .\" .\" toc@\f3ospf_monitor(1M)\f1:\0\0\f4ospf_monitor\f1@@@monitor OSPF gateways .\" .\" $Header: owners.1m,v 1.1.113.3 96/02/27 12:55:32 indnetwk Exp $ .TA o .TH owners 1M .SH NAME /usr/sbin/owners \- Lists owners of outgoing network connections .SH SYNOPSIS .C owners .SH DESCRIPTION .CR owners displays a list of established network connections which originate on this system, and indicates the owners of each connection using the .CR identd running on this system. .SH SEE ALSO sendmail(1M). .\" .\" index@\f4owners\f1 \- lists owners of outgoing network connections@@@\f3owners(1M)\f1 .\" index@\f1lists owners of outgoing network connections@@@\f3owners(1M)\f1 .\" index@\f1outgoing network connections, list owners of@@@\f3owners(1M)\f1 .\" index@\f1network connections, outgoing, list owners of@@@\f3owners(1M)\f1 .\" .\" toc@\f3owners(1M)\f1:\0\0\f4owners\f1@@@lists owners of outgoing network connections ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\"Copyright Hewlett-Packard Company 1991 ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" .rm zA .rm zZ .TH passwd_export "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "Security Service commands" "\*Lpasswd_export\*O" .iX "-[" "passwords" "backing up files" .SH NAME \fBpasswd_export\*O \- Creates local password and group files .SH "SYNOPSIS" .zA "defect,6211,R1.0.3,remove full path in SYNOPSIS" .sS \*Lpasswd_export\*O [\*L-d \*Vdir_name\*O] [\*L-m \*Vmax_entries\*O] [\*L-h[elp]\*O] [\*L-n\*O] [\*L-s\*O] [\*L-v\*O] [\*L-x\*O] .sE .zZ "defect,6211,R1.0.3,remove full path in SYNOPSIS" .SH "OPTIONS" .VL 1i .LI "[\*L-d \*Vdir_name\*O]" The name of the directory to store the password, group, and organization files created by \*Lpasswd_export\*O. If you do not enter a directory name, the files are stored in the \*L/etc\*O directory. .LI "\*L-h[elp]\*O" Display help information. .zA "feature,10415,R1.1,Add Security group override" .LI "\*L-n\*O" Ignore \*Lpasswd_override\*O and \*Lgroup_override\*O file entries. Without this option, \*Lpasswd_export\*O applies the override entries from both files to the local password and group files it creates. .zZ "feature,10415,R1.1,Add Security group override" .LI "[\*L-m \*Vmax_entries\*O]" The maximum number of entries that can be stored in the local files. .LI "\*L-s\*O" Sort the local password and group file entries by UNIX number. If you do not specify this option, the entries are in order as they are retrieved from the registry. .LI "\*L-v\*O" Run in verbose mode. .zA "feature,10415,R1.1,Add Security group override" .LI "\*L-x\*O" Do not create entries for users with \*LOMIT\*O as their encrypted password in the \*Lpasswd_override\*O and \*Lgroup_override\*O files. See the \*Lpasswd_override\*O and \*Lgroup_override\*O reference pages for further details about omitting users. .zZ "feature,10415,R1.1,Add Security group override" .LE .SH "DESCRIPTION" .PP The \*Vdceshared\*L/bin/passwd_export\*O command creates local password and group files from registry data. These files are used when the network registry is unavailable and by programs that use the original UNIX passwd and group interfaces instead of the DCE interfaces. Use \*Lpasswd_export\*O to keep these local files consistent with the registry database. .PP When \*Lpasswd_export\*O runs, it makes backup copies of the current password and group files, if they exist. The files are named, respectively, \*Lpasswd.bak\*O and \*Lgroup.bak\*O. .PP By default, the backups are stored and the new files created in the \*L/etc\*O directory. You can override the default by supplying a directory name with the \*L-d\*O option. .SS "Running passwd_export" .PP The \*Lpasswd_export\*O command is commonly run with an entry in \*L/usr/lib/crontab\*O. For example, to update the files every hour, the entry is .oS 0 * * * * \*Vdceshared\*C/bin/passwd_export .oE In large network environments, it is a good idea to stagger the times \*Lpasswd_export\*O is run. .SH "RELATED INFORMATION" .zA "def,4466,R1.0.2,Additions to Related Information" .PP Commands: \*Lrgy_edit(1m)\*O .PP Files: \*Lgroup(5), passwd(5), passwd_override(5), group_override(5)\*O .zZ "def,4466,R1.0.2,Additions to Related Information" .iX "-]" "Security Service commands" "\*Lpasswd_export\*O" .iX "-]" "passwords" "backing up files" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright (c) 1987 Apollo Computer, Inc. ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" .rm zA .rm zZ .TH passwd_import "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "Security Service commands" "\*Lpasswd_import\*O" .iX "-[" "accounts" "importing" .SH NAME \*Lpasswd_import\*O \- Creates registry database entries based on information in UNIX group and password files .SH SYNOPSIS .zA "def,7274,R1.0.2,add -h option" .zA "defect,6211,R1.0.3,remove full path in SYNOPSIS" .sS \*Lpasswd_import\*O [\*L-c\*O] \*L-d\*O \*Vpathname\*O [\*L-i\*O] [\*L-o\*O \*Vorg\*O] [\*L-p \*Vpassword\*O] .br [\*L-u \*Vusername\*O] [\*L-h\*O] [\*L-v\*O] .sE .zZ "defect,6211,R1.0.3,remove full path in SYNOPSIS" .zZ "def,7274,R1.0.2,add -h option" .SH "OPTIONS" .VL .LI "\*L-c\*O" Run in check mode: process the command, showing all conflicts, but make no requests for resolution. .LI "\*L-d \*Vpathname\*O" The path to the directory containing the foreign password and group files to be imported. .LI "\*L-i\*O" Ignore name confilcts. Names in the registry and the group and password files represent the same identity. .LI "\*L-o \*Vorg\*O" The name of an organization to be assigned to all imported entries. .zA "def,9992,R1.1,delete that org will be created" .zZ "def,9992,R1.1,delete that org will be created" The default organization is \*Lnone\*O. .zZ "def,9992,R1.1,delete that org will be created" .LI "\*L-p\*O \*Vpassword\*O" The password for the account with whose privileges \*Lpasswd_import\*O will run. .LI "\*L-u\*O \*Vusername\*O" The principal name of the account with whose privileges \*Lpasswd_import\*O will run. This account must have the privileges to access the registry and add principals, groups, accounts, and organizations, and to add members to groups and organizations. The principal name and password are used to obtain network authentication. If you do not supply them, \*Lpasswd_import\*O prompts for them, even if you have already performed a network login. .zA "def,7274,R1.0.2,add -h option" .LI "\*L-h\*O" Display help information. .zZ "def,7274,R1.0.2,add -h option" .LI "\*L-v\*O" Run in verbose mode: generate a verbose transcript of \*Lpasswd_import\*O activity. .LE .SH DESCRIPTION The \*Lpasswd_import\*O command is a mechanism for creating registry database entries that are consistent with foreign password and group file entries. Use \*Lpasswd_import\*O to ensure consistency between DCE and foreign protection mechanisms when you do the following: .ML .LI Attach DCE node(s) to an existing UNIX network .LI Attach UNIX node(s) to a DCE network .LI Connect DCE and UNIX networks .LE .PP If the password and group file entries do not exist in the DCE registry, \*Lpasswd_import\*O creates them. If there are duplicate entries, \*Lpasswd_import\*O follows your directions on how to handle them. .SS "The Process" .PP The DCE registry database must exist and be running before you can use \*Lpasswd_import\*O. If you are simply adding a few DCE nodes to a foreign network, you can create a new, but empty, registry to meet this requirement. .PP As \*Lpasswd_import\*O processes, it performs the following steps: .zA "def,4466,R1.0.2, Clarified steps" .AL .LI It opens the group and password files and establishes a connection to the registry. .LI It compares the group file entries to groups in the registry. If there are no conflicts, it creates groups in the registry corresponding to the groups in the group file. .LI It compares the entries in the password file to principals in the registry. Again, if there are no conflicts, it .AL .LI Creates principals in the registry corresponding to the entries in the password file. .LI Adds the newly created principals to the appropriate groups. .LI Creates accounts for the newly created principals. .LE .LI It re-examines the group file and adds the principals as members of any addtional groups it finds there. .LE .P The changes to the registry are made individually as each step is processed. .zA "def,9992,R1.1,delete that org will be created" .zZ "def,9992,R1.1,delete that org will be created" If you do not specify the organization, the principals are added to the organization \*Lnone\*O. .LE .zZ "def,4466,R1.0.2, Clarified steps" .SS "Conflicts" .PP During this process, \*Lpasswd_import\*O can find conflicts in name strings (for example, in the password file, \*Ljoe\*O \*L102\*O; in the registry database, \*Ljoe\*O \*L555\*O) and in UNIX IDs (for example, in the password file, \*Ljoe 102\*O; in the DCE, \*Lcarmelita\*O 102). When \*Lpasswd_import\*O finds a conflict, it prompts for changes to make to the \*L/etc/passwd\*O and \*L/etc/group\*O entries. No changes are made to the registry entries. In other words, all conflicts are resolved in favor of the registry entry. .PP The \*L-i \*O option specifies that duplicate names are not in conflict but, in fact, represent the same identity. Therefore, when duplicate names arise, no action is necessary. If you do not use the \*L-i\*O option, \*Lpasswd_import\*O prompts for how to handle the name conflicts. .SS "Resolving Conflicts" .PP The \*Lpasswd_import\*O command prompts for instructions to resolve the conflicts it finds. You have the following choices: .ML .LI You can create an alias to resolve a UNIX ID conflict. This action creates an alias for the registry object in conflict. The \*Lpasswd_import\*O command assigns this alias the same name as the conflicting entry in the \*L/etc/group\*O or \*L/etc/passwd\*O file. For example, if the entry \*Ljoe 555\*O exists in the registry and the entry \*Ltim 555\*O exists in the \*L/etc/passwd\*O file, choosing this option creates the alias \*Ltim\*O for \*Ljoe 555\*O. .LI You can generate a new UNIX ID automatically or enter a new one explicitly to resolve a UNIX ID conflict. For example, if there is a conflict between the entry \*Ljoe 555\*O in the registry and \*Ltim 555\*O in the \*L/etc/passwd\*O file, you can generate a new UNIX ID for \*Ltim\*O. .LI You can enter a new name to resolve a name conflict. For example if there is a conflict between the entry \*Ljoe 555\*O in the registry and \*Ljoe 383\*O in the \*L/etc/passwd\*O file, you can generate a new name for \*Ljoe 383\*O. This new name will then be added to the registry. .LE .P In addition, you are given the option of ignoring the conflict and skipping this entry. .P Generally, you should run \*Lpasswd_import\*O with the \*L-c\*O option. Using the results of this run, you can determine how to handle the conflicts. If there are many conflicts, it may be more efficient to manually edit either the registry or the group and password files to resolve some of them before you run \*Limport_passwd\*O. .SS "Registry Database Entries" .PP New registry entries created by \*Lpasswd_import\*O are assigned the following values: .VL .LI "\*LFor Principal and Group Entries:\*O" .VL .LI "\*Lalias/primary\*O " If the \*L/etc/passwd\*O file contains two entries with the same UNIX number, \*Lpasswd_import\*O creates a primary name entry for the first occurrence of the UNIX number and alises entries for each subsequent occurrence. .LI "\*Lfullname\*O " A blank string; no fullname is added for the entry. .LI "\*Lmembership list\*O " For new groups only, all principals listed in the group file, and all principals with accounts in the password file with that group. .LI "\*Lprojlist_ok\*O " Yes (for groups only). .LE .LI "\*LFor Account Entries:\*O" .VL .LI "\*LAccount expiration date\*O " None. .LI "\*LAccount_valid\*O " False. .LI "\*LClient flag\*O" True. .LI "\*LDuplicate certificate flag\*O " False. .LI "\*LForwardable certificate flag\*O " True. .LI "\*LGecos\*O " Same as password file. .LI "\*LGood since date\*O " Time of account creation. .LI "\*LHomedir\*O" Same as password file. .LI "\*LMaximum certificate lifetime\*O " Default to registry authentication policy. .LI "\*LMaximum certificate renewable\*O " Default to registry authentication policy. .LI "\*LPasswd\*O " Randomly generated. Note that you must modify or reset randomly generated passwords before user authentication is possible. .LI "\*LPasswd_dtm\*O " Date and time \*Lpasswd_import\*O was run. .LI "\*LPasswd_valid\*O " False. .LI "\*LPostdated certificate flag\*O " False. .LI "\*LProxiable certificate flag\*O " False. .LI "\*LRenewable certificate flag\*O " True. .LI "\*LServer flag\*O " True. .LI \"*LShell\*O " Same as password file. .LI "\*LTGT authentication flag\*O " True. .LE .LE .SH "RELATED INFORMATION" Commands: \*Lrgy_edit(1m)\*O, \*Lsec_admin(1m)\*O, \*Lsecd(1m)\*O .iX "-]" "Security Service commands" "\*Lpasswd_import\*O" .iX "-]" "accounts" "importing" .\" $Header: pcnfsd.1m,v 1.1.113.2 97/07/16 18:13:21 mbhootha Exp $ .TA p .TH pcnfsd 1M .SH NAME pcnfsd \- PC-NFS authentication and print request server .SH SYNOPSIS .CR /usr/sbin/rpc.pcnfsd .SH DESCRIPTION .CR pcnfsd is an RPC server that supports ONC clients on PC (DOS, OS/2, Macintosh, and other) systems. This describes version two of the .CR pcnfsd server. .PP .CR pcnfsd can be started from the .CR /sbin/init.d/nfs.server startup script by setting the .CR PCNFS_SERVER variable to 1 in .CR /etc/rc.config.d/nfsconf , or from the .CR inetd daemon (see .IR inetd (1M)). It reads the configuration file .CR /etc/pcnfsd.conf , if present, and services RPC requests directed to program number 150001. The .CR pcnfsd daemon now supports version 1 and version 2 of the PCNFSD protocol. .PP The requests serviced by .CR pcnfsd fall into three categories: authentication, printing, and other. Only the authentication and printing categories have administrative significance. .SS Authentication When .CR pcnfsd receives a .CR PCNFSD_AUTH or .CR PCNFSD2_AUTH request, it will "log in" the user by validating the user name and password, returning the corresponding user ID, group IDs, home directory, and umask. It will also append a record to the .CR wtmp data base (see .IR wtmp (4)). If you do not want PC "logins" recorded in this way, add a line to the .CR /etc/pcnfsd.conf file in the form: .IP .C "wtmp off" .PP By default, .CR pcnfsd will only allow authentication or print requests for users with user IDs in the range 101 to 60002 (this corresponds, in SVR4, to the range for nonsystem accounts). To override this, add a line to the .CR /etc/pcnfsd.conf file in the form: .IP .CR uidrange .IR range [\c .CI , range\f1]... .PP where each .IR range is a user ID number in the form .IP .I uid .PP or an inclusive range of user ID numbers in the form .IP .IC uid - uid .SS Printing .CR pcnfsd supports a printing model that uses NFS to transfer print data from the client to the server. The client system issues a .CR PCNFSD_PR_INIT or .CR PCNFSD2_PR_INIT request, and the server returns the path to a spool directory that is exported by NFS for use by the client. .CR pcnfsd creates a subdirectory for each client. By default, the parent directory is .CR /var/spool/pcnfs , and the name of each subdirectory is the same as its client's host name. To use a different parent directory, add a line to the .CR /etc/pcnfsd.conf file in the form: .IP .CR spooldir .I path .PP Once a client has mounted the spool directory using NFS, and transferred print data to a file in that directory, it will issue a .CR PCNFSD_PR_START or .CR PCNFSD2_PR_START request. .CR pcnfsd handles most print-related requests by constructing a command based on the printing services of the server's operating system, and executing that command using the identity of the PC user. Because this involves set-user-ID privileges, .CR pcnfsd must be run as .CR root . .PP Every print request from a client includes the name of the printer to be used. This name corresponds to a printer that has been configured into the line printer spooling system using the .CR lpadmin command. .PP By default, The lpstat -v command executed by pcnfsd will time out in 10 seconds. To change this default add a line to /etc/pcnfsd.conf. .CR .IP lpstat_timer .PP To process print data in a special way (for example, to print it in landscape mode, or to print it in duplex mode), define a new printer and arrange for the client to print to that printer. There are two ways to define the new printer: .RS .TP 3 \(bu You can add a new printer to the line printer spooling system that uses a different printer model script, and arrange for the client to use the new printer. Do this using the .CR lpadmin command (see .IR lpadmin (1m)). .TP \(bu .CR pcnfsd includes a mechanism to define virtual printers known only to .CR pcnfsd clients. Each of these printers is defined by an entry in the file .CR /etc/pcnfsd.conf using the following format: .RS .IP .CR printer .IR name .IR alias-for .IR command .RE .IP with the following values: .RS .TP 15 .I name The name of the printer, as it will be referred to in print requests from clients. .TP .I alias-for The corresponding name for the printer, as it is defined in the line printer spooling system. For example, a request to display the queue for .I name will be translated into the corresponding request for the printer .IR alias-for . If you have defined a printer within .CR pcnfsd that has no corresponding printer defined in the line printer spooling system, use a single hyphen .RC ( - ) for this field. For an example, see the definition of the printer .CR test in the examples section, below. .TP .I command A command that will be executed whenever a file is printed on .IR name . This command is executed by the POSIX shell, .CR /usr/bin/sh using the .CR -c option. For complex operations, construct an executable shell program and execute that in .IR command . .IP Within .I command the following tokens will be replaced: .RS .TP 10 .B Token .B Substitution .TP .CR $FILE Replaced by the full path name of the print data file. When the command has been executed, the file will be unlinked. .TP .CR $USER Replaced by the user name of the user logged in to the client system. .TP .CR $HOST Replaced by the host name of the client system. .RE .RE .RE .SS Reconfiguration By checking the modification time (and contents) of the file .CR /var/spool/lp/pstatus , .CR pcnfsd will detect when printers have been added or deleted, and will rebuild its list of valid printers. However, .CR pcnfsd does not monitor the file .CR /etc/pcnfsd.conf for updates; if you change this file, you must kill and restart .CR pcnfsd for the changes to take effect. .SH EXAMPLES Given the following entries for the file .CR /etc/pcnfsd.conf: .IP .C "printer abc lj lp -dlj -oraw" .br .C "printer test - /usr/bin/cp $FILE /usr/tmp/$HOST-$USER" .PP If a user on a client system prints a job on printer .CR abc , the request will be sent to destination .CR lj in raw mode. .PP If the client requests a list of the print queue for printer .CR abc , the .CR pcnfsd daemon will translate this into a request for a listing for printer .CR lj . .PP Printer .CR test is used only for testing. Any file sent to this printer will be copied into the directory .CR /usr/tmp . Any request to list the queue, check the status, etc., of printer .CR test will be rejected because .I alias-for has been specified as a hyphen .RC ( - ). .SH FILES .PD 0 .nf .CR /etc/pcnfsd.conf .CR /etc/rc.config.d/nfsconf .CR /var/spool/lp/pstatus .CR /var/spool/pcnfs .fi .PD .SH SEE ALSO lp(1), lpstat(1), inetd(1M), lpadmin(1M), wtmp(4). .\" .\" index@\f4pcnfsd\f1 \- PC-NFS authentication and print request server@@@\f3pcnfsd(1M)\f1 .\" index@\f4rpc.pcnfsd\f1 \- PC-NFS authentication and print request server@@@\f3pcnfsd(1M)\f1 .\" index@PC-NFS authentication and print request server@@@\f3pcnfsd(1M)\f1 .\" index@authentication and print request server, PC-NFS@@@\f3pcnfsd(1M)\f1 .\" index@print request server, PC-NFS@@@\f3pcnfsd(1M)\f1 .\" .\" links@pcnfsd.1m rpc.pcnfsd.1m .\" .\" toc@\f3pcnfsd(1M)\f1:\0\0\f4rpc.pcnfsd\f1@@@PC-NFS authentication and print request server .\" toc@\f4rpc.pcnfsd\f1:\0\0PC-NFS authentication and print request server@@@see \f3pcnfsd(1M)\f1 .\" $Header: pcserver.1m,v 72.4 94/12/08 12:21:43 ssa Exp $ .TA p .TH pcserver 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pcserver \- Basic Serial and HP AdvanceLink server .SH SYNOPSIS .C pcserver .RC [ -n ] .RC [ -l .RI [ \|log_file\| ]\|] .RC [ -v ] .SH DESCRIPTION .C pcserver is the hostside server program for Basic Serial and AdvanceLink, and is started and terminated by an application program running on a PC. .PP .C pcserver supports both the Basic Serial and the AdvanceLink protocols. .PP Basic Serial offers a library of routines that support a variety of services between a PC and a serially connected host computer, including file transfers and remote interprocess communications. .PP AdvanceLink is a terminal emulation program that also supports file transfers between a PC and host system over various physical connections. .SS Options The following options are recognized by .IR pcserver : .RS .TP 12 .CR -l " [\f2logfile\fP]" This option is now obsolete, but is retained for compatibility with earlier versions of software. Logging is now controlled by the presence or absence of the server.pro file as described in NOTES, below. Enables packet logging and records .C pcserver messages to a specified log file (for debugging). If .I logfile is not specified, the file .C s-log is used in the default logging directory, as defined in the .CR server.pro file. .C pcserver looks for a local version of server.pro in the user's home directory. If none is found, it will look for a system-wide version as .CR /var/adm/server.pro or .CR /usr/adm/server.pro . If the .C logfile exists, logging is appended to it. If the file does not exist, logging is disabled. .TP .C -n Informs .C pcserver that a "netmode" for data encryption should be used during special operations (for example, a netmode is needed to mask device control characters when a PAD is being used). The details of the netmode are then negotiated between the .C pcserver and the PC application. For a more comprehensive discussion on netmode, see .IR "Using Basic Serial Connection Files" . .TP .C -v Causes .C pcserver to print its version number to standard output and quit. .RE .PP .C pcserver is designed to be invoked by a PC application program rather than from the command line. In order for the connection to be correctly established, the PC and host port must be properly configured. .PP If you are using .C pcserver to manage a session between a PC and a hostside application (via Basic Serial), you may need to use a Basic Serial connection file to actually log in to your account. Establishing connections using Basic Serial connection files is a sensitive operation. Before attempting to use them, you should read the manual .IR "Using Basic Serial Connection Files" . .PP If you are using .C pcserver to transfer files between a PC and a host machine via Advancelink, use the following AdvanceLink commands: .IP .C "&HOSTCOPY ""pcserver""" .br .C "&TERMINATOR ""$""" .PP If your prompt does not end with .CR $ , replace the .C $ in the terminator command with the last character in your normal prompt. .PP To permanently configure AdvanceLink for the HP-UX version of .CR pcserver , refer to the .I "Using AdvanceLink" manual for more information. .SH NOTES Packet logging is controlled by the presence or absence of the file .CR server.pro .PP .CR pcserver looks for a local version of .CR server.pro in the user's home directory. If none is found, it will look for a system-wide version as .CR /var/adm/server.pro or .CR /usr/adm/server.pro . .PP If no logging file is found in these directories, logging is not performed. A commented example of a .CR server.pro may be found in .CR /usr/newconfig/var/adm/server.pro.ex or .CR /usr/adm/server.pro.ex . To make use of this file, copy it to the active file name, .CR server.pro , in one of the previously mentioned directory locations. If your screen displays a .C "Command not found" message when you choose START TRANSFER from AdvLink, either .C pcserver has not yet been installed on your HP-UX system, or it has been installed in a directory that is not part of your current path. .PP HP-UX treats files containing binary or ASCII data identically. Therefore it is up to the user to specify the desired file type when using .C pcserver to transfer files with Advancelink. The difference between the two is that during ASCII transfers, .C pcserver maps HP-UX line-feed characters to the MS-DOS carriage-return/line-feed pair. This produces incorrect results when transferring a binary file as an ASCII file. .PP Also, older versions of AdvanceLink show totally inaccurate estimates for file transfer times. This does not interfere with the actual transfer. .PP If the PC is reset while a transfer is taking place, it may temporarily appear to be a "dead" terminal port. This is no cause for alarm; left to its own devices, .C pcserver will restore the port in a short time. In the worst case, it could take six timeout periods (6\|\(mu\|20 = 120 seconds). For faster response, press the Break key a few times to terminate .C pcserver immediately. .SH FILES .TP 35 .C /usr/bin/pcserver the executable program .PD 0 .TP .C /var/adm/server.pro system-wide logging profile .TP .C /usr/adm/server.pro system-wide logging profile .TP .C $HOME/server.pro local logging profile .TP 55 .C /usr/newconfig/var/adm/server.pro.ex commented inactive example of server.pro .TP 35 .C /usr/adm/server.pro.ex commented inactive example of server.pro .PD .SH SEE ALSO .TP 35 .I Using AdvanceLink Describes protocol and how to use AdvanceLink. .TP .I Using Basic Serial Connection Files Describes Basic Serial and how connection files should be used. .\" .\" index@\f4pcserver\f1 \- Basic Serial and HP AdvanceLink server@@@\f3pcserver(1M)\f1 .\" index@Basic Serial and HP AdvanceLink server@@@\f3pcserver(1M)\f1 .\" index@Serial and HP AdvanceLink server, Basic@@@\f3pcserver(1M)\f1 .\" index@HP AdvanceLink and Basic Serial server@@@\f3pcserver(1M)\f1 .\" index@AdvanceLink server, Basic Serial and HP@@@\f3pcserver(1M)\f1 .\" index@server, Basic Serial and HP AdvanceLink@@@\f3pcserver(1M)\f1 .\" .\" toc@\f3pcserver(1M)\f1:\0\0\f4pcserver\f1@@@Basic Serial and HP AdvanceLink server .\" $Header: pdc.1m,v 72.1 93/01/15 10:54:18 ssa Exp $ .TA p .TH pdc 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pdc \- processor-dependent code (firmware) .SH DESCRIPTION .I pdc is the firmware that implements all processor-dependent functionality, including initialization and self-test of the processor. Upon completion, it loads and transfers control to the initial system loader .RI ( isl (1M)). Firmware behavior varies somewhat, depending on the hardware series as described below. .SS Series 800 Behavior To load .I isl from an external medium, .I pdc must know the particular device on which .I isl resides. Typically the device is identified by the Primary Boot Path that is maintained by .I pdc in Stable Storage. A .I path specification is a series of decimal numbers each suffixed by '/', indicating bus converters, followed by a series of decimal numbers separated by '.', indicating the various card and slot numbers and addresses. The first number, not specifying a bus converter, is the .SM MID-BUS module number (that is, slot number times four) and followed by the .SM CIO slot number. If the .SM CIO slot contains an .SM HP-IB card, the next number is the .SM HP-IB address, followed by the unit number of the device if the device supports units. If the .SM CIO slot contains a terminal card, the next number is the port number, which must be zero for the console. .PP When the processor is reset after initialization and self-test complete, .I pdc reads the Console Path from Stable Storage, and attempts to initialize the console device. If the initialization fails, .I pdc attempts to find and initialize a console device. Algorithms used to find a console device are model-dependent. .I pdc then announces the Primary Boot, Alternate Boot, and Console Paths. .PP If .I autoboot (see .IR isl (1M)) is enabled, .I pdc provides a 10-second delay, during which time the operator can override the .I autoboot sequence by typing any character on the console. If the operator does not interrupt this process, .I pdc initializes and reads .I isl from the Primary Boot Path. On models that support autosearch, if this path is not valid and .I autosearch (see .IR isl (1M)) is enabled, .I pdc then searches through the .SM MID-BUS modules and .SM CIO slots to find a bootable medium. Currently, autosearch is only implemented on the model 825. .PP If the .I autoboot sequence is unsuccessful, overridden by the operator, or not enabled in the first place, .I pdc interactively prompts the operator for the Boot Path to use. Any required path components that are not supplied default to zero. .PP The Primary Boot, Alternate Boot, and Console Paths as well as .I autoboot and .I autosearch enable can be modified via .I isl. .SS Series 700 Behavior To load .I isl from an external medium, .I pdc must know the particular device on which .I isl resides. Typically the device is identified by the Primary Boot Path that is maintained by .I pdc in Stable Storage. A .I path specification is an .SM I/O subsystem mnemonic that varies according to hardware model. .PP When the processor is reset after initialization and self-test complete, .I pdc reads the Console Path from Stable Storage, and attempts to initialize the console device. If the initialization fails, .I pdc attempts to find and initialize a console device. Algorithms used to find a console device vary according to hardware model. .PP If .I autoboot and .I autosearch (see .IR isl (1M)) are enabled, .I pdc waits for approximately 10 seconds during which time the operator can override the .I autoboot sequence pressing and holding the .SM ESC (escape) key on the console. .PP The system then begins a search for potentially bootable devices. If allowed to complete, a list of potentially bootable devices is displayed, labeled with abbreviated path identifiers (P0, P1, etc). A simple menu is then displayed where the user can: .RS .TP 3 \(bu Boot a specific device, using the abbreviated path identifier, or the full mnenomic. .TP \(bu Start a device search where the contents are searched for .SM IPL images (note the first search only identified devices and did not check the contents). .TP \(bu Enter the boot administration level. .TP \(bu Exit the menu and return to autobooting .TP \(bu Get help on choices .RE .PP The search of potentially bootable devices can be aborted by pressing and holding the escape key. The search for device contents can also be aborted by pressing and holding the escape key. .PP If the operator does not interrupt the search process, .I pdc initializes and reads .I isl from the Primary Boot Path. .PP If the .I autoboot sequence is unsuccessful, overridden by the operator, or not enabled in the first place, .I pdc executes the device search and enters the menu described above. .PP The Primary Boot, Alternate Boot, and Console Paths as well as .I autoboot and .I autosearch enable can be modified via .I isl or at the pdc boot administration level. .SH SEE ALSO boot(1M), hpuxboot(1M), isl(1M). .\" index@\f2pdc\f1 \- processor-dependent code (firmware)@@@\f3pdc(1M)\f1 .\" index@code, processor-dependent (firmware)@@@\f3pdc(1M)\f1 .\" index@processor-dependent code (firmware)@@@\f3pdc(1M)\f1 .\" index@firmware (processor-dependent code)@@@\f3pdc(1M)\f1 .\" index@console, search for during boot process@@@\f3pdc(1M)\f1 .\" index@processor self test@@@\f3pdc(1M)\f1 .\" index@processor initialization@@@\f3pdc(1M)\f1 .\" index@\f2autoboot\f1 sequence@@@\f3pdc(1M)\f1 .\" .\" toc@\f3pdc(1M)\f1:\0\0\f2pdc\f1@@@processor-dependent code (firmware) .\" .\" fileset_database@pdc.1m@SYS-ADMIN-MAN .\" $Header: pdfck.1m,v 72.6 94/12/08 12:21:57 ssa Exp $ .TA p .TH pdfck 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pdfck \- compare Product Description File to File System .SH SYNOPSIS .C pdfck .RC [ \|-n\| ] .RC [ \|-r\| .IR alternate_root\| ] .SM .I PDF .SH DESCRIPTION .C pdfck is a program that compares the file descriptions in a .SM PDF (Product Description File) to the actual files on the file system. It is intended as a tool to audit the file system and detect corruption and/or tampering. Differences found are reported in the format described in the .IR pdfdiff (1M) manual entry. (Size growth .RC ( -p option) is not reported.) For a detailed explanation of the .SM PDF fields see .IR pdf (4). The command .IP .C "pdfck -r /pseudoroot /system/AL_CORE/pdf" .PP is roughly equivalent to .IP .nf .C "mkpdf -r /pseudoroot /system/\s-1AL_CORE\s+1/pdf \- | \e" .C "pdfdiff /system/\s-1AL_CORE\s+1/pdf \-" .fi .SS Options .C pdfck recognizes the following options: .RS .TP 20 .C -n Compare numerical representation of user id .I uid and group id .I gid of each file, instead of the usual text representation. If owner or group is recorded in the .SM PDF as a name, look the name up in the .C /etc/passwd or .C /etc/group file, respectively, to find the id number. .TP .CI -r \0alternate_root .I alternate_root is a string that is prefixed to each pathname in the prototype when the filesystem is being searched for that file. Default is .SM NULL. .RE .SH EXAMPLES The following output indicates tampering with .CR /usr/bin/cat : .IP .nf /usr/bin/cat: mode(-r-xr-xr-x -> -r-sr-xr-x)(became suid), size(27724 -> 10345), checksum(1665 -> 398) .fi .SH WARNING Use of PDFs is discouraged since this functionality is obsolete and is being replaced with Software Distributor (see .IR sd (4)). .SH FILES .TP 33 .CI /system/ fileset_name /pdf Product Description File of fileset called .IR fileset_name . .SH SEE ALSO mkpdf(1M), pdfdiff(1M), pdf(4). .\" .\" index@compare Product Description File and file system@@@\f3pdfck(1M)\f1 .\" index@file system, compare with Product Description File@@@\f3pdfck(1M)\f1 .\" index@Product Description File, check against file system@@@\f3pdfck(1M)\f1 .\" index@check Product Description File against file system@@@\f3pdfck(1M)\f1 .\" .\" toc@\f3pdfck(1M)\f1:\0\0\f4pdfck\f1@@@compare Product Description File and file system .\" .\" fileset_database@pdfck.1m SYS-ADMIN-MAN .\" $Header: pdfdiff.1m,v 72.5 94/12/08 12:22:14 ssa Exp $ .TA p .TH pdfdiff 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pdfdiff \- compare two Product Description Files .SH SYNOPSIS .C pdfdiff .RC [ -n ] .RC [ -p .IR percent\| ] .I pdf1\0pdf2 .SH DESCRIPTION .C pdfdiff is a program that compares two .SM PDF\s0s (Product Description Files). The .SM PDF\s0s can be generated using the .C mkpdf command (see .IR mkpdf (1M)). Individual fields in the .SM PDF\s0s are compared, and differences found in these fields are reported. For a detailed explanation of the .SM PDF fields see .IR pdf (4). .PP The report format is: .IP \f2pathname\f1: \f2diff_\|field\f1[(\f2details\f1) ][ ,...] .PP .I diff_\|field is one of the field names specified in .IR pdf (4). The format of .I details is .RI `` oldvalue " \(mi> " newvalue '' and may include an additional .RI ``( "added description" )''. .PP A summary of total product growth in bytes, .C DEV_BSIZE disk blocks, and the percentage change in disk blocks is reported. This summary includes growth of all files, including those for which growth did .I not exceed the threshhold .IR percent . Format of the growth summary is: .IP \h'.4i'Growth: \f2x\f1 bytes, \f2y\f1 blocks (\f2z\f1%) .SS Options .C pdfdiff recognizes the following options: .RS .TP 15 .C -n Compare numerical representation of user .SM ID .I uid and group .SM ID .I gid of each file, instead of the usual text representation. If owner or group is recorded in the .SM PDF as a name, look the name up in the .C /etc/passwd or .C /etc/group file, respectively, to find the .SM ID number. .TP .CI -p \0percent specifies a threshhold percentage for file growth. Files having a net size change greater than or equal to this percentage are reported. A decrease in size is reported as a negative number. If .C -p is not specified, a default value of zero percent is used. .RE .SH EXAMPLES The following output results when the .C /usr/bin/cat entry in the example from .I pdf(4) is different in the compared .SM PDF: .nf \f4/usr/bin/cat: mode(-r-xr-xr-x -> -r-sr-xr-x)(became suid), size(27724 -> 10345),\fP \f4 checksum(1665 -> 398)\fP \f4Growth: -17379 bytes, -17 blocks (-4%)\fP .fi .SH WARNING Use of PDFs is discouraged since this functionality is obsolete and is being replaced with Software Distributor (see .IR sd (4)). .SH FILES .CI /system/ fileset_name /pdf .SH SEE ALSO mkpdf(1M), pdfck(1M), pdf(4). .\" .\" index@\f4pdfdiff\f1: compare two Product Description Files@@@\f3pdfdiff(1M)\f1 .\" index@\f4pdfdiff\f1: Product Description Files, compare two@@@\f3pdfdiff(1M)\f1 .\" index@\f4pdfdiff\f1: differences between two Product Description Files@@@\f3pdfdiff(1M)\f1 .\" .\" toc@\f3pdfdiff(1M)\f1:\0\0\f4pdfdiff\f1@@@compare two Product Description Files .\" .\" fileset_database@pdfdiff.1m SYS-ADMIN-MAN .\" $Header: perf.1m,v 72.2 94/10/27 14:40:31 ssa Exp $ .TA p .TH perf 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME perf \- test the NCS RPC runtime library .SH SYNOPSIS .B /usr/sbin/ncs/perf/server .RB [ \|\-d\| ] .I max_calls family .PP .B /usr/sbin/ncs/perf/run_client .I family hostname .PP .B /usr/sbin/ncs/perf/client .I test_number test_args .SH DESCRIPTION The .I perf exerciser tests the functionality and measures the performance of the Remote Procedure Call .SM (RPC) runtime library, part of the Network Computing System .SM (NCS). .PP .I perf consists of client and server programs called .B client and .B server and a shell script called .BR run_client . These executables reside in the directory .BR /usr/sbin/ncs/perf . .PP The .I perf client and server programs run as separate processes, either on one host or on two different hosts. Any host that runs either the client or the server must have the Network Computing Kernel .SM (NCK), the runtime portion of .SM NCS, installed. .PP .I perf makes only minimal use of the Location Broker. .PP To use .IR perf , first start the server, then run the client to conduct various .SM NCK tests against that server, as described in the following sections. .SS "Starting the perf Server" Any host that runs the .I perf server must also run \f3rpcd\f1, the Remote Procedure Call daemon. Ensure that an \f3rpcd\f1 is running. .PP The .I perf server has the following syntax: .IP .B /usr/sbin/ncs/perf/server .RB [ \|\-d\| ] .I max_calls family .PP The .B \-d option instructs the server to display debug messages. .PP The .I max_calls argument specifies the maximum number of calls that the server can execute in parallel. On HP-UX systems, specify the value .BR 1 . .PP The .I family argument specifies one or more address families for which the server should create sockets to listen on. On .SM HP-UX systems, specify .BR ip . .PP For testing .SM NCK functionality, a typical invocation of the .I perf server is .IP .RB $ \ "server 1 ip" .PP which creates a .I perf server that handles one call at a time, listens for .I perf client tests on an internet socket, and does not run in debug mode. .SS "Running the run_client Script" The .I perf client consists of 11 tests, each of which exercises a particular feature of .SM NCK. .PP To test .SM NCK functionality, invoke the .B run_client script, which runs all 11 of the .I perf tests. (Several of the tests are run twice, once with the .B idempotent operation attribute and once without.) .PP The syntax for .B run_client is .IP .RB $ " run_client \f2family hostname\fP" .PP The .I family and .I hostname arguments specify the host that is running the .I perf server. .SS "Running Individual perf Client Tests" You can run the .I perf tests individually by directly invoking the .B client program. .PP Following are the individual .I perf client tests. .nf .IP .ta 1.75i \&\f3Test Syntax\f1 .if t .sp 0.5v .if t \{\c Null call \f3client 0\f2 host passes calls/pass verify? idempotent?\f1 Variable length \f3client 1\f2 host passes calls/pass verify? idempotent? nbytes\f1 input argument Variable length \f3client 2\f2 host passes calls/pass verify? idempotent? nbytes\f1 output argument Broadcast \f3client 3\f2 family\f1 Maybe \f3client 4\f2 host\f1 Broadcast/maybe \f3client 5\f2 family\f1 Floating point \f3client 6\f2 host passes calls/pass verify? idempotent?\f1 Unregistered \f3client 7\f2 host\f1 interface Forwarding \f3client 8\f2 host global?\f1 Exception \f3client 9\f2 host\f1 Slow call \f3client 10\f2 host passes calls/pass verify? idempotent? seconds\f1 Shutdown \f3client 11\f2 host\f1 \} .if n \{\c Null call \f3client 0\f2 host passes calls/pass verify? idempotent?\f1 Variable length \f3client 1\f2 host passes calls/pass verify? idempotent?\f1 input argument \f3nbytes\f1 Variable length \f3client 2\f2 host passes calls/pass verify? idempotent?\f1 output argument \f3nbytes\f1 Broadcast \f3client 3\f2 family\f1 Maybe \f3client 4\f2 host\f1 Broadcast/maybe \f3client 5\f2 family\f1 Floating point \f3client 6\f2 host passes calls/pass verify? idempotent?\f1 Unregistered \f3client 7\f2 host\f1 interface Forwarding \f3client 8\f2 host global?\f1 Exception \f3client 9\f2 host\f1 Slow call \f3client 10\f2 host passes calls/pass verify? idempotent?\f1 \& \f3seconds\f1 Shutdown \f3client 11\f2 host\f1 \} .fi .PP .DT Test 0 makes the simplest possible remote procedure call, one with no parameters. .PP Tests 1 and 2 pass open arrays as input and output parameters, respectively. .PP Tests 3, 4, and 5 use the .B broadcast and .B maybe operation attributes. (Tests 3 and 5 will not work if the server and the client are running on hosts in different networks.) .PP Test 6 passes floating-point parameters. .PP Test 7 requests an operation in an interface that is not registered with the .SM RPC runtime library at the server. .PP Test 8 sends a call to the Location Broker forwarding port at the server, testing the forwarding facility provided by .IR rpcd . (Test 8 requires an .I rpcd to be running at the server. The others specify well-known ports.) .PP Test 9 makes a call that raises an exception at the server. .PP Test 10 makes a call from which the server will return after the specified period of time. .PP Test 11 remotely shuts down the server. .PP Following are descriptions of the arguments that appear in the syntax table. .TP .I host The host on which the .I perf server is running, specified in the form .IB family : name (for example, .BR ip:toscanini ). .TP .I passes The number of times to run the test. The .I perf client displays a message after each pass. .TP .I calls/pass The number of remote calls to make during one pass. .TP .I verify? Yes/no .RB ( y or .BR n ) input. A "yes" input directs .I perf to run the test for correct operation. A "no" input directs .I perf to run the test to obtain performance statistics. .TP .I idempotent? Yes/no .RB ( y or .BR n ) input. A "yes" input directs the .I perf client to call an idempotent operation at the .I perf server. A "no" input directs the .I perf client to call a non-idempotent operation. .TP .I nbytes The number of bytes the input and output parameters should have. .TP .I family An address family (for example, .B ip or .BR dds ). .TP .I global? Yes/no .RB ( y or .BR n ) input. At this release, specify .BR n . .TP .I seconds The number of seconds the server should wait before returning. .SS "Using perf to Troubleshoot NCK" If .I perf is not running successfully, check that the networking software and hardware used by .SM NCK is functioning correctly. On networks that support .SM IP protocols, for example, try running .IR telnet , .IR ftp , and other IP-based applications between the hosts that ran .IR perf . Network services must be available and working correctly before you start Location Brokers and other .SM NCS\s0-based programs. .PP If the .I perf tests appear to be running successfully but .SM NCK appears to be functioning incorrectly, try reversing the roles of the .I perf hosts. It is possible that the .I perf tests will work correctly with the client running on host A and the server running on host B but will fail with the client running on host B and the server running on host A. .PP If any of the .I perf tests fail, try running the tests locally, with both the client and the server running on the same host. Failure in this case could be due to incorrect mapping of names to addresses (in a host table, for instance), absence of required daemons or servers, or mismatch of versions between the .I perf client and server. .SH SEE ALSO lb_test(1M), rpcd(1M). .\" .\" index@\f2perf\f1 \- test the \s-1NCS RPC\s0 runtime library@@@\f3perf(1M)\f1 .\" index@test the \s-1NCS RPC\s0 runtime library@@@\f3perf(1M)\f1 .\" index@\s-1NCS RPC\s0 runtime library, test the@@@\f3perf(1M)\f1 .\" index@\s-1RPC\s0 runtime library, test the \s-1NCS\s0@@@\f3perf(1M)\f1 .\" index@runtime library, test the \s-1NCS RPC\s0@@@\f3perf(1M)\f1 .\" index@library, test the \s-1NCS RPC\s0 runtime@@@\f3perf(1M)\f1 .\" .\" toc@\f3perf(1M)\f1:\0\0\f2perf\f1@@@test the \s-1NCS RPC\s0 runtime library .\" .\" fileset_database@perf.1m@SYS-ADMIN-MAN .\" $Header $ .\" SCCS Keywords @(#)pfs_exportfs.8 1.3 12/1/91 .TA p .TH pfs_exportfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfs_exportfs \- export and unexport directories to PFS clients .SH SYNOPSIS .C /usr/sbin/pfs_exportfs [ .C \-a \-u \-v ] [ .I pathname ] .SH DESCRIPTION .CR pfs_exportfs makes a local directory or filename available for mounting over the network by PFS clients. It is recommended that a command to invoke .CR pfs_exportfs at boot time be added to .IR rc (1M). .CR pfs_exportfs uses information contained in the .CR /etc/pfs_exports file to export .I pathname (which must be specified as a full pathname). The superuser can run .CR pfs_exportfs at any time to alter the list or characteristics of exported directories and filenames. Directories and files that are currently exported are listed in the file .CR /etc/pfs_xtab . .PP With no options or arguments, .CR pfs_exportfs prints out the list of directories and filenames currently exported. .SS Options .TP .C \-a All. Export all pathnames listed in .CR /etc/pfs_exports , or if .CR \-u is specified, unexport all of the currently exported pathnames. .TP .C \-u Unexport the indicated pathnames. .TP .C \-v Verbose. Print each directory or filename as it is exported or unexported. .RE .SH AUTHOR .CR psf_exportfs was developed by Young Minds, Inc. .SH FILES .PD 0 .TP 25 .C /etc/pfs_exports static export information .TP .C /etc/pfs_xtab current state of exported pathnames .PD .SH "SEE ALSO" pfs_exports (5). .\" .\" index@\f4pfs_exportfs\f1 \- export and unexport directories to PFS clients@@@\f3pfs_exportfs(1M)\f1 .\" index@\f1export and unexport directories to PFS clients@@@\f3pfs_exportfs(1M)\f1 .\" index@\f1unexport and export directories to PFS clients@@@\f3pfs_exportfs(1M)\f1 .\" index@\f1PFS clients, export and unexport directories to@@@\f3pfs_exportfs(1M)\f1 .\" index@\f1clients, PFS, export and unexport directories to@@@\f3pfs_exportfs(1M)\f1 .\" index@\f1directories, export or unexport to PFS clients@@@\f3pfs_exportfs(1M)\f1 .\" .\" toc@\f3pfs_exportfs(1M)\f1:\0\0\f4pfs_exportfs\f1@@@export and unexport directories to PFS clients .\" .\" fileset_database@pfs_exportfs.1m CORE-ENG-A-MAN .\" $Header: pfs_mount.1m,v 84.1 98/05/05 15:38:18 ssa Exp $ .\" SCCS Keywords @(#)pfs_mount.8 1.8 1/30/92 .\" Document pfs_umount -c option, and recommend using character device .TA p .TH pfs_mount 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: May 1998 .SH NAME pfs_mount, pfs_umount \- mount and unmount CD-ROM file systems .SH SYNOPSIS .C pfs_mount .RC [ \-v .CR \-a ] .HP .C pfs_mount .RC [ \-v .C \-a .C \-f .CR \-n ] [ .C \-t .I type ] [ .CI \-x " xlat" ] [ .CI \-o " options" ] .I filesystem .I directory .HP .C pfs_mount .RC [ \-v .C \-a .C \-f .CR \-n ] [ .CI \-x " xlat" ] [ .CI \-o " options" ] .IR filesystem " | " directory .HP .C pfs_umount [ .C \-v .C \-a .C \-c ] .IR filesystem " | " directory .SH DESCRIPTION .CR pfs_mount attaches a named .I filesystem to the file system hierarchy at the pathname location .IR directory , which must already exist. If .I directory has any contents prior to the .CR pfs_mount operation, these remain hidden until the .I filesystem is once again unmounted. If .I filesystem is of the form .IC host : pathname\c , it is assumed to be a remote file system. .PP In the case of a local mount, .CR pfs_mount probes the specified .C "character device" to determine the file system type. It then contacts the local .C pfs_mountd.rpc program to register the specified .IR directory as a valid mounted file system. .CR pfs_mountd.rpc will reply with the address of the .CR pfsd.rpc who will be handling all requests for files on that .IR directory . .PP Remote mounts are very similar, except that both the local and remote mount daemons will be contacted. The remote mount daemon will supply the PFS server address, and the local mount daemon will be contacted to register the mount. .PP .CR pfs_umount unmounts a currently mounted PFS file system, which can be specified as either a .IR directory or a .IR filesystem . .PP .CR pfs_umount contacts the local mount daemon to determine what actions should be taken to perform the unmount. If the file system was originally remotely mounted, the remote mount daemon is informed of the unmount, and the file system is unmounted. Otherwise, it is simply unmounted. .PP .CR pfs_mount and .CR pfs_umount maintain a table of mounted file systems in .CR /etc/pfs_mtab , described in .IR pfs_fstab (5). If invoked without an argument, .C pfs_mount displays the contents of this table. If invoked with either a .IR filesystem or a .IR directory only, .C pfs_mount searches the file .C /etc/pfs_fstab for a matching entry, and mounts the file system indicated in that entry on the indicated directory. .PP If a user unmounts a PFS file system with the .C umount program, or interrupts the .C pfs_umount program before it has completed processing, the PFS daemons may leave the mount device open after the file system is no longer accessible. To clear these problems, use the .C \-c flag for .CR pfs_umount . .PP PFS expects a .C "character device" to be used for mounts, not a block device. Use of a block device with PFS is not supported. .SS "pfs_mount Options" .RS 0 .TP 13 .C \-v Verbose. Display a message indicating each file system being mounted. .TP .C \-a All. Mount all file systems described in the .C /etc/pfs_fstab file. .TP .C \-f Fake an .C /etc/mnttab entry, but do not actually mount any file systems. Note: This option has no effect on HP-UX 10.30 or later. .TP .C \-n Mount the file system without making an entry in .CR /etc/mnttab . Note: This option has no effect on HP-UX 10.30 or later. .TP .CI \-x " xlat" Filename translation options. Any combination can be specified, although some combinations do not make sense (i.e. .C dot_version and .CR no_version ). .RS .TP 17 .C no_version will suppress the printing of the version number (and semicolon) at the end of ISO 9660 and High Sierra filenames. .TP .C dot_version replaces the version number (and semicolon) with a period followed by the version number. .TP .C lower_case Converts upper to lower case on all file (and directory) names. .TP .C unix Shorthand for .C no_version and .CR lower_case . .RE .TP .CI \-t " type" Force the CD-ROM to be mounted as the specified type, if possible. Accepted types are: .RS .TP 14 .C iso9660 will cause the mount program to attempt to mount the CD-ROM image using the ISO 9660 specifications. If the CD image is not ISO 9660 compatible, the mount fails. Note that if the CD image is also Rock Ridge compliant, and the .C "-t iso9660" option is not specified, the CD-ROM image will be mounted with Rock Ridge extensions enabled. .TP .C hsfs will cause the mount program to attempt to mount the CD-ROM image using the High Sierra specifications. If the CD image is not .C hsfs compatible, the mount fails. .TP .C rrip will cause the mount program to attempt to mount the CD-ROM image using the Rock Ridge Interchange specifications. If the CD image is not RRIP compatible, the mount fails. Note, that if the CD-ROM image supports the Rock Ridge Interchange Protocol, and the CD-ROM image is mounted with .CR rrip , the translation options are suppressed. .RE .IP Note that these get entered into the .CR /etc/pfs_mtab and .CR /etc/pfs_fstab with a .CI "pfs-" preceding the type. .TP .CI \-o " options" Specify file system .IR "options " as a list of comma-separated words from the list below. .IP .I options valid on .EM all file systems: .RS .PD 0 .TP 18 .CR ro Even if not specified, the read-only option is implied. .TP .CR suid \||\| nosuid SetUID execution allowed or disallowed. .TP .CR bg \||\| fg If the first attempt fails, retry in the background, or, in the foreground. .TP .CI retry= n The number of times to retry the mount operation. .TP .CI rsize= n Set the read buffer size to .I n bytes. .TP .CI timeo= n Set the PFS timeout to .I n tenths of a second. .TP .CI retrans= n The number of PFS retransmissions. .TP .CR soft \||\| hard Return an error if the server does not respond, or continue the retry request until the server responds. .TP .C intr Allow keyboard interrupts on hard mounts. .RE .PD .IP The defaults are: .RS 18 .nf .P .C suid,fg,retry=10000,timeo=7,rsize=2048,retrans=3,hard .fi .RE .IP .I options specific to .CR iso9660 and .CR hsfs file systems: .RS .TP 20 .CR xlat=xlat_flags .I xlat_flags is a colon (:) separated list of translation options. Currently supported are .CR no_version , .CR dot_version , .CR lower_case , and .CR unix . They allow you to perform the same translations options the .I -x flag does. The .I -x flag remains for backward compatibility. It is suggested that you use the .I xlat= option flag as they can be placed in the .CR /etc/pfs_fstab file. .RE .RE .SS "pfs_umount Options" .TP .CI \-v Verbose. Display a message indicating each file system as it is unmounted. .TP .C \-a All. Unmount all PFS mounted file systems. .TP .C \-c Close. Instruct the PFS daemons to close the given file system, but do not attempt to umount the file system. This is useful when the file system has already been unmounted, but the PFS daemons still have the source .B "character device" open. .PP .SH "pfs_mount CONFIGURATIONS" .SS Background vs. Foreground Filesystems mounted with the .CR bg option indicate that .CR pfs_mount is to retry in the background if the server's mount daemon (see .IR pfs_mountd (1M)) does not respond. .CR pfs_mount retries the request up to the count specified in the .CI retry= n option. Once the file system is mounted, each PFS request made in the kernel waits .CI timeo= n tenths of a second for a response. If no response arrives, the time-out is multiplied by .CR 2 and the request is retransmitted. When the number of retransmissions has reached the number specified in the .CI retrans= n option, a file system mounted with the .CR soft option returns an error on the request; one mounted with the .CR hard option prints a warning message and continues to retry the request. .PP .SS "Interrupting Processes With Pending PFS Requests" The .CR intr option allows keyboard interrupts to kill a process that is hung while waiting for a response on a hard-mounted file system. .SS "Attributes Cache" The server's attribute cache retains file attribute information on requests that have been made. This provides faster access to entries which have previously been decoded. .SS "Lookup Cache" The .CR "Lookup Cache" holds information about the sequential nature of the directory entries. This cache stores the location of the next directory entry. When a request comes in for a directory entry, if the preceding directory entry had been accessed earlier, this location is examined first to see if the directory entry being requested matches the directory entry at that location. .SS "Block Cache" This cache holds raw 8k blocks of recently accessed data. .SH EXAMPLES To mount a CD-ROM disk: .IP .C pfs_mount /dev/rdsk/c0t6d0 /cd-rom .P To mount a remote file system: .IP .C pfs_mount serv:/cd-rom /cd-rom .P To fake an entry for iso9660 on /cd-rom: .IP .C pfs_mount \-f -t iso9660 /dev/rdsk/c0t6d0 /cd-rom .P To hard mount a remote file system: .IP .C pfs_mount \-o hard serv:/cd-rom /cd-rom .SH AUTHOR .CR pfs_mount was developed by Young Minds, Inc. .SH FILES .PD 0 .TP 22 .C /etc/mnttab table of mounted file systems .TP .C /etc/pfs_fstab table of PFS file systems .TP .C /etc/pfs_mtab table of mounted PFS file systems .PD .SH "SEE ALSO" pfs_fstab(5), pfs_mountd(1M), pfsd(1M). .SH BUGS If the directory on which a file system is to be mounted is a symbolic link, the file system is mounted on .EM "the directory to which the symbolic link refers" , rather than being mounted on top of the symbolic link itself. .PP On Pioneer six disc changers (and perhaps other drives) if you mount the file system using the block device driver, the Pioneer returns information to the driver indicating there is no data, causing the mount to fail. Either mount the file system again (which will should succeed), or use the raw device driver. .\" .\" index@\f4pfs_mount\f1 \- mount and unmount CD-ROM file systems@@@\f3pfs_mount(1M)\f1 .\" index@\f1mount and unmount CD-ROM file systems@@@\f3pfs_mount(1M)\f1 .\" index@\f1unmount and mount CD-ROM file systems@@@\f3pfs_mount(1M)\f1 .\" index@\f1CD-ROM file systems, mount and unmount@@@\f3pfs_mount(1M)\f1 .\" index@\f1file systems, CD-ROM, mount and unmount@@@\f3pfs_mount(1M)\f1 .\" .\" toc@\f3pfs_mount(1M)\f1:\0\0\f4pfs_mount\f1@@@mount and unmount CD-ROM file systems .\" toc@\f4pfs_umount\f1:\0\0unmount CD-ROM file systems@@@\f1see \f3pfs_mount(1M)\f1 .\" .\" links@pfs_mount.1m pfs_umount.1m .\" .\" $Header $ .\" SCCS Keywords @(#)pfs_mountd.8 1.4 12/1/91 .TA p .TH pfs_mountd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfs_mountd, pfs_mountd.rpc \- PFS mount request server .SH SYNOPSIS .C /usr/etc/pfs_mountd .SH DESCRIPTION This program is available with the .I Portable File System Package (PFS). .CR pfs_mountd is an RPC server that answers file system mount requests. In the case of remote mount requests, it reads the file .CR /etc/pfs_xtab , described in .IR pfs_exports (5), to determine which file systems are available for mounting by which machines. .PP It is recommended that the .CR pfs_mountd daemon be invoked by .IR rc (1M). It must be invoked in the background. .PP The .CR pfs mount daemon is composed of two programs: .CR pfs_mountd and .CR pfs_mountd.rpc . The .CR pfs_mountd.rpc program should .BR not be run directly. It is invoked by the .CR pfs_mountd program. .PP The mount daemon assigns servers to mounted file systems in a round\-robin fashion. For example, if there are four pfs daemons, and four .CR pfs_mount 's are performed, each daemon will be serving a different mount. .PP .SS Options .TP .C \-v Verbose. Show version number, etc. .SH AUTHOR .CR pfs_mountd was developed by Young Minds, Inc. .SH FILES .PD 0 .TP 20 .C /etc/pfs_xtab .PD .SH "SEE ALSO" pfs_exports (5), rc (1M). .\" .\" index@\f4pfs_mountd\f1 \- PFS mount request server@@@\f3pfs_mountd(1M)\f1 .\" index@\f1PFS mount request server@@@\f3pfs_mountd(1M)\f1 .\" index@\f1mount request server, PFS@@@\f3pfs_mountd(1M)\f1 .\" index@\f1request server, PFS mount@@@\f3pfs_mountd(1M)\f1 .\" index@\f1server, PFS mount request@@@\f3pfs_mountd(1M)\f1 .\" .\" toc@\f3pfs_mountd(1M)\f1:\0\0\f4pfs_mountd\f1@@@PFS mount request server .\" toc@\f4pfs_mountd.rpc\f1:\0\0PFS mount request server@@@\f1see \f3pfs_mountd(1M)\f1 .\" .\" links@pfs_mountd.1m pfs_mountd.rpc.1m .\" .\" fileset_database@pfs_mountd.1m CORE-ENG-A-MAN .\" $Header $ .\" SCCS Keywords @(#)pfs_mountd.8 1.4 12/1/91 .TA p .TH pfs_mountd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfs_mountd, pfs_mountd.rpc \- PFS mount request server .SH SYNOPSIS .C /usr/etc/pfs_mountd .SH DESCRIPTION This program is available with the .I Portable File System Package (PFS). .CR pfs_mountd is an RPC server that answers file system mount requests. In the case of remote mount requests, it reads the file .CR /etc/pfs_xtab , described in .IR pfs_exports (5), to determine which file systems are available for mounting by which machines. .PP It is recommended that the .CR pfs_mountd daemon be invoked by .IR rc (1M). It must be invoked in the background. .PP The .CR pfs mount daemon is composed of two programs: .CR pfs_mountd and .CR pfs_mountd.rpc . The .CR pfs_mountd.rpc program should .BR not be run directly. It is invoked by the .CR pfs_mountd program. .PP The mount daemon assigns servers to mounted file systems in a round\-robin fashion. For example, if there are four pfs daemons, and four .CR pfs_mount 's are performed, each daemon will be serving a different mount. .PP .SS Options .TP .C \-v Verbose. Show version number, etc. .SH AUTHOR .CR pfs_mountd was developed by Young Minds, Inc. .SH FILES .PD 0 .TP 20 .C /etc/pfs_xtab .PD .SH "SEE ALSO" pfs_exports (5), rc (1M). .\" .\" index@\f4pfs_mountd\f1 \- PFS mount request server@@@\f3pfs_mountd(1M)\f1 .\" index@\f1PFS mount request server@@@\f3pfs_mountd(1M)\f1 .\" index@\f1mount request server, PFS@@@\f3pfs_mountd(1M)\f1 .\" index@\f1request server, PFS mount@@@\f3pfs_mountd(1M)\f1 .\" index@\f1server, PFS mount request@@@\f3pfs_mountd(1M)\f1 .\" .\" toc@\f3pfs_mountd(1M)\f1:\0\0\f4pfs_mountd\f1@@@PFS mount request server .\" toc@\f4pfs_mountd.rpc\f1:\0\0PFS mount request server@@@\f1see \f3pfs_mountd(1M)\f1 .\" .\" links@pfs_mountd.1m pfs_mountd.rpc.1m .\" .\" fileset_database@pfs_mountd.1m CORE-ENG-A-MAN .\" $Header: pfs_mount.1m,v 84.1 98/05/05 15:38:18 ssa Exp $ .\" SCCS Keywords @(#)pfs_mount.8 1.8 1/30/92 .\" Document pfs_umount -c option, and recommend using character device .TA p .TH pfs_mount 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: May 1998 .SH NAME pfs_mount, pfs_umount \- mount and unmount CD-ROM file systems .SH SYNOPSIS .C pfs_mount .RC [ \-v .CR \-a ] .HP .C pfs_mount .RC [ \-v .C \-a .C \-f .CR \-n ] [ .C \-t .I type ] [ .CI \-x " xlat" ] [ .CI \-o " options" ] .I filesystem .I directory .HP .C pfs_mount .RC [ \-v .C \-a .C \-f .CR \-n ] [ .CI \-x " xlat" ] [ .CI \-o " options" ] .IR filesystem " | " directory .HP .C pfs_umount [ .C \-v .C \-a .C \-c ] .IR filesystem " | " directory .SH DESCRIPTION .CR pfs_mount attaches a named .I filesystem to the file system hierarchy at the pathname location .IR directory , which must already exist. If .I directory has any contents prior to the .CR pfs_mount operation, these remain hidden until the .I filesystem is once again unmounted. If .I filesystem is of the form .IC host : pathname\c , it is assumed to be a remote file system. .PP In the case of a local mount, .CR pfs_mount probes the specified .C "character device" to determine the file system type. It then contacts the local .C pfs_mountd.rpc program to register the specified .IR directory as a valid mounted file system. .CR pfs_mountd.rpc will reply with the address of the .CR pfsd.rpc who will be handling all requests for files on that .IR directory . .PP Remote mounts are very similar, except that both the local and remote mount daemons will be contacted. The remote mount daemon will supply the PFS server address, and the local mount daemon will be contacted to register the mount. .PP .CR pfs_umount unmounts a currently mounted PFS file system, which can be specified as either a .IR directory or a .IR filesystem . .PP .CR pfs_umount contacts the local mount daemon to determine what actions should be taken to perform the unmount. If the file system was originally remotely mounted, the remote mount daemon is informed of the unmount, and the file system is unmounted. Otherwise, it is simply unmounted. .PP .CR pfs_mount and .CR pfs_umount maintain a table of mounted file systems in .CR /etc/pfs_mtab , described in .IR pfs_fstab (5). If invoked without an argument, .C pfs_mount displays the contents of this table. If invoked with either a .IR filesystem or a .IR directory only, .C pfs_mount searches the file .C /etc/pfs_fstab for a matching entry, and mounts the file system indicated in that entry on the indicated directory. .PP If a user unmounts a PFS file system with the .C umount program, or interrupts the .C pfs_umount program before it has completed processing, the PFS daemons may leave the mount device open after the file system is no longer accessible. To clear these problems, use the .C \-c flag for .CR pfs_umount . .PP PFS expects a .C "character device" to be used for mounts, not a block device. Use of a block device with PFS is not supported. .SS "pfs_mount Options" .RS 0 .TP 13 .C \-v Verbose. Display a message indicating each file system being mounted. .TP .C \-a All. Mount all file systems described in the .C /etc/pfs_fstab file. .TP .C \-f Fake an .C /etc/mnttab entry, but do not actually mount any file systems. Note: This option has no effect on HP-UX 10.30 or later. .TP .C \-n Mount the file system without making an entry in .CR /etc/mnttab . Note: This option has no effect on HP-UX 10.30 or later. .TP .CI \-x " xlat" Filename translation options. Any combination can be specified, although some combinations do not make sense (i.e. .C dot_version and .CR no_version ). .RS .TP 17 .C no_version will suppress the printing of the version number (and semicolon) at the end of ISO 9660 and High Sierra filenames. .TP .C dot_version replaces the version number (and semicolon) with a period followed by the version number. .TP .C lower_case Converts upper to lower case on all file (and directory) names. .TP .C unix Shorthand for .C no_version and .CR lower_case . .RE .TP .CI \-t " type" Force the CD-ROM to be mounted as the specified type, if possible. Accepted types are: .RS .TP 14 .C iso9660 will cause the mount program to attempt to mount the CD-ROM image using the ISO 9660 specifications. If the CD image is not ISO 9660 compatible, the mount fails. Note that if the CD image is also Rock Ridge compliant, and the .C "-t iso9660" option is not specified, the CD-ROM image will be mounted with Rock Ridge extensions enabled. .TP .C hsfs will cause the mount program to attempt to mount the CD-ROM image using the High Sierra specifications. If the CD image is not .C hsfs compatible, the mount fails. .TP .C rrip will cause the mount program to attempt to mount the CD-ROM image using the Rock Ridge Interchange specifications. If the CD image is not RRIP compatible, the mount fails. Note, that if the CD-ROM image supports the Rock Ridge Interchange Protocol, and the CD-ROM image is mounted with .CR rrip , the translation options are suppressed. .RE .IP Note that these get entered into the .CR /etc/pfs_mtab and .CR /etc/pfs_fstab with a .CI "pfs-" preceding the type. .TP .CI \-o " options" Specify file system .IR "options " as a list of comma-separated words from the list below. .IP .I options valid on .EM all file systems: .RS .PD 0 .TP 18 .CR ro Even if not specified, the read-only option is implied. .TP .CR suid \||\| nosuid SetUID execution allowed or disallowed. .TP .CR bg \||\| fg If the first attempt fails, retry in the background, or, in the foreground. .TP .CI retry= n The number of times to retry the mount operation. .TP .CI rsize= n Set the read buffer size to .I n bytes. .TP .CI timeo= n Set the PFS timeout to .I n tenths of a second. .TP .CI retrans= n The number of PFS retransmissions. .TP .CR soft \||\| hard Return an error if the server does not respond, or continue the retry request until the server responds. .TP .C intr Allow keyboard interrupts on hard mounts. .RE .PD .IP The defaults are: .RS 18 .nf .P .C suid,fg,retry=10000,timeo=7,rsize=2048,retrans=3,hard .fi .RE .IP .I options specific to .CR iso9660 and .CR hsfs file systems: .RS .TP 20 .CR xlat=xlat_flags .I xlat_flags is a colon (:) separated list of translation options. Currently supported are .CR no_version , .CR dot_version , .CR lower_case , and .CR unix . They allow you to perform the same translations options the .I -x flag does. The .I -x flag remains for backward compatibility. It is suggested that you use the .I xlat= option flag as they can be placed in the .CR /etc/pfs_fstab file. .RE .RE .SS "pfs_umount Options" .TP .CI \-v Verbose. Display a message indicating each file system as it is unmounted. .TP .C \-a All. Unmount all PFS mounted file systems. .TP .C \-c Close. Instruct the PFS daemons to close the given file system, but do not attempt to umount the file system. This is useful when the file system has already been unmounted, but the PFS daemons still have the source .B "character device" open. .PP .SH "pfs_mount CONFIGURATIONS" .SS Background vs. Foreground Filesystems mounted with the .CR bg option indicate that .CR pfs_mount is to retry in the background if the server's mount daemon (see .IR pfs_mountd (1M)) does not respond. .CR pfs_mount retries the request up to the count specified in the .CI retry= n option. Once the file system is mounted, each PFS request made in the kernel waits .CI timeo= n tenths of a second for a response. If no response arrives, the time-out is multiplied by .CR 2 and the request is retransmitted. When the number of retransmissions has reached the number specified in the .CI retrans= n option, a file system mounted with the .CR soft option returns an error on the request; one mounted with the .CR hard option prints a warning message and continues to retry the request. .PP .SS "Interrupting Processes With Pending PFS Requests" The .CR intr option allows keyboard interrupts to kill a process that is hung while waiting for a response on a hard-mounted file system. .SS "Attributes Cache" The server's attribute cache retains file attribute information on requests that have been made. This provides faster access to entries which have previously been decoded. .SS "Lookup Cache" The .CR "Lookup Cache" holds information about the sequential nature of the directory entries. This cache stores the location of the next directory entry. When a request comes in for a directory entry, if the preceding directory entry had been accessed earlier, this location is examined first to see if the directory entry being requested matches the directory entry at that location. .SS "Block Cache" This cache holds raw 8k blocks of recently accessed data. .SH EXAMPLES To mount a CD-ROM disk: .IP .C pfs_mount /dev/rdsk/c0t6d0 /cd-rom .P To mount a remote file system: .IP .C pfs_mount serv:/cd-rom /cd-rom .P To fake an entry for iso9660 on /cd-rom: .IP .C pfs_mount \-f -t iso9660 /dev/rdsk/c0t6d0 /cd-rom .P To hard mount a remote file system: .IP .C pfs_mount \-o hard serv:/cd-rom /cd-rom .SH AUTHOR .CR pfs_mount was developed by Young Minds, Inc. .SH FILES .PD 0 .TP 22 .C /etc/mnttab table of mounted file systems .TP .C /etc/pfs_fstab table of PFS file systems .TP .C /etc/pfs_mtab table of mounted PFS file systems .PD .SH "SEE ALSO" pfs_fstab(5), pfs_mountd(1M), pfsd(1M). .SH BUGS If the directory on which a file system is to be mounted is a symbolic link, the file system is mounted on .EM "the directory to which the symbolic link refers" , rather than being mounted on top of the symbolic link itself. .PP On Pioneer six disc changers (and perhaps other drives) if you mount the file system using the block device driver, the Pioneer returns information to the driver indicating there is no data, causing the mount to fail. Either mount the file system again (which will should succeed), or use the raw device driver. .\" .\" index@\f4pfs_mount\f1 \- mount and unmount CD-ROM file systems@@@\f3pfs_mount(1M)\f1 .\" index@\f1mount and unmount CD-ROM file systems@@@\f3pfs_mount(1M)\f1 .\" index@\f1unmount and mount CD-ROM file systems@@@\f3pfs_mount(1M)\f1 .\" index@\f1CD-ROM file systems, mount and unmount@@@\f3pfs_mount(1M)\f1 .\" index@\f1file systems, CD-ROM, mount and unmount@@@\f3pfs_mount(1M)\f1 .\" .\" toc@\f3pfs_mount(1M)\f1:\0\0\f4pfs_mount\f1@@@mount and unmount CD-ROM file systems .\" toc@\f4pfs_umount\f1:\0\0unmount CD-ROM file systems@@@\f1see \f3pfs_mount(1M)\f1 .\" .\" links@pfs_mount.1m pfs_umount.1m .\" .\" $Header $ .\" SCCS Keywords @(#)pfsd.8 1.7 12/2/91 .TA p .TH pfsd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfsd, pfsd.rpc \- PFS daemon .SH SYNOPSIS .C pfsd .CI [ nservers ] [ .CI \-v ] [ .CI \-o " options" ] .SH DESCRIPTION .CR pfsd starts the daemons that handle client filesystem requests. .I nservers is the number of file system server daemons to start. This number should be based on the load expected on this server. The load is defined by the number of mounted file systems. .PP Mounts are distributed in a round-robin fashion to the .CR pfsd daemons. .PP It is recommended that the .CR pfsd daemon be invoked by .IR rc (1M). It must be invoked in the background. .PP The .CR PFS daemon is composed of two programs: .CR pfsd and .CR pfsd.rpc . The .CR pfsd.rpc program should .BR not be run directly. It is invoked by the .CR pfsd program. .SS Options .TP 14 .C \-v Verbose. Show version number, etc. .TP .CI \-o " options" Specify filesystem .IR "options " "\(em\c a" list of comma-separated words from the list below. .RS .IR options valid: .TP 16 .CI acsize= n The number of entries to keep in the attribute cache (1390 bytes per entry). .TP .CI bcsize= n The number of entries to keep in the block cache (8244 bytes per entry). .TP .CI lcsize= n The number of entries to keep in the lookup cache (56 bytes per entry). .TP 19 The defaults are: .C acsize=200,bcsize=25,lcsize=100 .SS "Attributes Cache" The server's attribute cache retains file attribute information on requests that have been made. This provides faster access to entries which have previously been decoded. .SS "Lookup Cache" The .C Lookup Cache holds information about the sequential nature of the directory entries. This cache stores the location of the next directory entry. When a request comes in for a directory entry, if the preceding directory entry had been accessed earlier, this location is examined first to see if the directory entry being requested matches the directory entry at that location. .SS "Block Cache" This cache holds raw 8k blocks of recently accessed data. .SH EXAMPLES .RS .PD 0 .TP To start a pfs daemon with a 400 entry attribute cache: .C pfsd -o acsize=400 & .TP To start a 4 pfs daemons with the default cache sizes: .C pfsd 4 & .br .ne 2 .RE .PD .SH AUTHOR .CR pfsd was developed by Young Minds, Inc. .SH "SEE ALSO" pfs_mountd (1M). .SH WARNINGS It is not a good idea to have the cache sizes of the .CR pfsd exceed the amount of physical memory (or actually a small portion thereof). If the .CR pfsd spends excessive amounts of time swapping to and from disk, the benefits of the caching are diminished. .PP Specifying cache which consume more virtual memory than available will cause the daemon to die with a vitual memory error. .\" .\" index@\f4pfsd\f1 \- PFS daemon@@@\f3pfsd(1M)\f1 .\" index@\f1PFS daemon@@@\f3pfsd(1M)\f1 .\" index@\f1daemon, PFS@@@\f3pfsd(1M)\f1 .\" .\" toc@\f3pfsd(1M)\f1:\0\0\f4pfs\f1@@@PFS daemon .\" toc@\f4pfsd.rpc\f1:\0\0PFS daemon@@@\f1see \f3pfsd(1M)\f1 .\" .\" links@pfsd.1m pfsd.rpc.1m .\" .\" fileset_database@pfsd.1m CORE-ENG-A-MAN .\" $Header $ .\" SCCS Keywords @(#)pfsd.8 1.7 12/2/91 .TA p .TH pfsd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfsd, pfsd.rpc \- PFS daemon .SH SYNOPSIS .C pfsd .CI [ nservers ] [ .CI \-v ] [ .CI \-o " options" ] .SH DESCRIPTION .CR pfsd starts the daemons that handle client filesystem requests. .I nservers is the number of file system server daemons to start. This number should be based on the load expected on this server. The load is defined by the number of mounted file systems. .PP Mounts are distributed in a round-robin fashion to the .CR pfsd daemons. .PP It is recommended that the .CR pfsd daemon be invoked by .IR rc (1M). It must be invoked in the background. .PP The .CR PFS daemon is composed of two programs: .CR pfsd and .CR pfsd.rpc . The .CR pfsd.rpc program should .BR not be run directly. It is invoked by the .CR pfsd program. .SS Options .TP 14 .C \-v Verbose. Show version number, etc. .TP .CI \-o " options" Specify filesystem .IR "options " "\(em\c a" list of comma-separated words from the list below. .RS .IR options valid: .TP 16 .CI acsize= n The number of entries to keep in the attribute cache (1390 bytes per entry). .TP .CI bcsize= n The number of entries to keep in the block cache (8244 bytes per entry). .TP .CI lcsize= n The number of entries to keep in the lookup cache (56 bytes per entry). .TP 19 The defaults are: .C acsize=200,bcsize=25,lcsize=100 .SS "Attributes Cache" The server's attribute cache retains file attribute information on requests that have been made. This provides faster access to entries which have previously been decoded. .SS "Lookup Cache" The .C Lookup Cache holds information about the sequential nature of the directory entries. This cache stores the location of the next directory entry. When a request comes in for a directory entry, if the preceding directory entry had been accessed earlier, this location is examined first to see if the directory entry being requested matches the directory entry at that location. .SS "Block Cache" This cache holds raw 8k blocks of recently accessed data. .SH EXAMPLES .RS .PD 0 .TP To start a pfs daemon with a 400 entry attribute cache: .C pfsd -o acsize=400 & .TP To start a 4 pfs daemons with the default cache sizes: .C pfsd 4 & .br .ne 2 .RE .PD .SH AUTHOR .CR pfsd was developed by Young Minds, Inc. .SH "SEE ALSO" pfs_mountd (1M). .SH WARNINGS It is not a good idea to have the cache sizes of the .CR pfsd exceed the amount of physical memory (or actually a small portion thereof). If the .CR pfsd spends excessive amounts of time swapping to and from disk, the benefits of the caching are diminished. .PP Specifying cache which consume more virtual memory than available will cause the daemon to die with a vitual memory error. .\" .\" index@\f4pfsd\f1 \- PFS daemon@@@\f3pfsd(1M)\f1 .\" index@\f1PFS daemon@@@\f3pfsd(1M)\f1 .\" index@\f1daemon, PFS@@@\f3pfsd(1M)\f1 .\" .\" toc@\f3pfsd(1M)\f1:\0\0\f4pfs\f1@@@PFS daemon .\" toc@\f4pfsd.rpc\f1:\0\0PFS daemon@@@\f1see \f3pfsd(1M)\f1 .\" .\" links@pfsd.1m pfsd.rpc.1m .\" .\" fileset_database@pfsd.1m CORE-ENG-A-MAN .\" $Header: ping.1m,v 72.5 94/09/21 13:53:26 ssa Exp $ .TA p .TH ping 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ping \- send ICMP Echo Request packets to network host .SH SYNOPSIS .C ping .RC [ -oprv ] .RC [ -i .IR address ] .RC [ -t .IR ttl ] .I host .RC [ -n .IR count ] .br .C ping .RC [ -oprv ] .RC [ -i .IR address ] .RC [ -t .IR ttl ] .I host .I packet-size .RC [\0[ -n ] .IR count ] .SH DESCRIPTION The .CR ping command sends ICMP Echo Request (ECHO_REQUEST) packets to .I host once per second. Each packet that is echoed back via an ICMP Echo Response packet is written to the standard output, including round-trip time. .PP ICMP Echo Request datagrams ("pings") have an IP and ICMP header, followed by a .C "struct timeval" (see .IR gettimeofday (2)) and an arbitrary number of "pad" bytes used to fill out the packet. The default datagram length is 64 bytes, but this can be changed by using the .I packet-size option. .SS Options The following options and parameters are recognizaed by .CR ping : .RS .TP 12 .CI -i \0address If .I host is a multicast address, send multicast datagrams from the interface with the local IP address specified by .IR address in ``dot'' notation (see .IR inet_addr (3N)). If the .CR -i option is not specified, multicast datagrams are sent from the default interface, which is determined by the route configuration. .TP .C -o Insert an IP Record Route option in outgoing packets, summarizing routes taken when the command terminates. .IP It may not be possible to get the round-trip path if some hosts on the route taken do not implement the IP Record Route option. A maximum of 9 Internet addresses can be recorded due to the maximum length of the IP option area. .TP .CR -p The new Path MTU information is displayed when a ICMP "Datagram Too Big" message is received from a gateway. The .CR -p option must be used in conjunction with a large .I packetsize and with the .CR -v option. .TP .C -r Bypass the normal routing tables and send directly to a host on an attached network. If the host is not on a directly-connected network, an error is returned. This option can be used to ping the local system through an interface that has no route through it, such as after the interface was dropped by .CR gated (see .IR gated (1M)). .TP .CI -t \0ttl If .I host is a multicast address, set the time-to-live field in the multicast datagram to .IR ttl . This controls the scope of the multicast datagrams by specifying the maximum number of external systems through which the datagram can be forwarded. .IP If .I ttl is zero, the datagram is restricted to the local system. If .I ttl is one, the datagram is restricted to systems that have an interface on the network directly connected to the interface specified by the .C -i option. If .I ttl is two, the datagram can forwarded through at most one multicast router; and so forth. .C Range: zero to 255. The default value is 1. .TP .C -v Verbose output. Show ICMP packets other than Echo Responses that are received. .TP .I host Destination to which the ICMP Echo Requests are sent. .I host can be a hostname or an Internet address. All symbolic names specified for .I host are looked up by using .C gethostbyname() (see .IR gethostbyname (3N)). If .I host is an Internet address, it must be in "dot" notation (see .IR inet_addr (3N)). .IP If a system does not respond as expected, the route might be configured incorrectly on the local or remote system or on an intermediate gateway, or there might be some other network failure. Normally, .I host is the address assigned to a local or remote network interface. .IP If .I host is a broadcast address, all systems that receive the broadcast should respond. Normally, these are only systems that have a network interface on the same network as the local interface sending the ICMP Echo Request. .IP If .I host is a multicast address, only systems that have joined the multicast group should respond. These may be distant systems if the .C -t option is specified, and there is a multicast router on the network directly connected to the interface specified by the .C -i option. .TP .I packet-size The size of the transmitted packet, in bytes. By default (when .I packet-size is not specified), the size of transmitted packets is 64 bytes. The minimum value allowed for .I packet-size is 8 bytes, and the maximum is 4095 bytes. If .I packet-size is smaller than 16 bytes, there is not enough room for timing information. In that case, the round-trip times are not displayed. .TP .I count The number of packets .C ping will transmit before terminating. .B Range: zero to 2147483647. The default is zero, in which case .C ping sends packets until interrupted. .RE .PP When using .CR ping for fault isolation, first specify a local address for .I host to verify that the local network interface is working correctly. Then specify host and gateway addresses further and further away to determine the point of failure. .CR ping sends one datagram per second, and it normally writes one line of output for every ICMP Echo Response that is received. No output is produced if there are no responses. If an optional .I count is given, only the specified number of requests is sent. Round-trip times and packet loss statistics are computed. When all responses have been received or the command times out (if the .I count option is specified), or if the command is terminated with a .CR SIGINT , a brief summary is displayed. .PP This command is intended for use in testing, managing and measuring network performance. It should be used primarily to isolate network failures. Because of the load it could impose on the network, it is considered discourteous to use .CR ping unnecessarily during normal operations or from automated scripts. .SH AUTHOR .CR ping was developed in the Public Domain. .SH FILES .CR /etc/hosts .SH SEE ALSO gethostbyname(3N), inet(3N). .\" .\" index@echo packets@@@\f3ping(1M)\f1 .\" index@ECHO_REQUEST packets@@@\f3ping(1M)\f1 .\" index@host test packets, send@@@\f3ping(1M)\f1 .\" index@network test packets, send@@@\f3ping(1M)\f1 .\" index@packets, echo@@@\f3ping(1M)\f1 .\" index@packets, ECHO_REQUEST@@@\f3ping(1M)\f1 .\" index@send test packets@@@\f3ping(1M)\f1 .\" index@test packets, send@@@\f3ping(1M)\f1 .\" index@\f4ping\f1 \- send echo packets to a network host@@@\f3ping(1M)\f1 .\" .\" toc@\f3ping(1M)\f1:\0\0\f4ping\f1@@@send echo request packets to a network host; test host availability .\" .\" fileset_database@ping.1m .\" $Header: portmap.1m,v 72.4 94/11/29 11:28:35 ssa Exp $ .TA p .TH portmap 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME portmap \- \s-1DARPA\s0 port to \s-1RPC\s0 program number mapper .SH SYNOPSIS .C /usr/sbin/portmap .SH DESCRIPTION The .C portmap server converts .SM RPC program numbers into .SM DARPA protocol port numbers. It must be running to make .SM RPC calls. .PP When an .SM RPC server starts, it registers itself with .CR portmap , telling .C portmap what port number it is listening to and what .SM RPC program numbers it is prepared to serve. When a client wants to make an .SM RPC call to a given program number, it first contacts .C portmap on the server machine to determine the port number where .SM RPC packets should be sent. .PP The .C portmap server must be started before .C inetd because standard .SM RPC servers are started by .C inetd (see .IR inetd (1M)). .SH WARNINGS If .C portmap crashes, all .SM RPC servers must be restarted. .SH AUTHOR .C portmap was developed by Sun Microsystems, Inc. .SH SEE ALSO inetd(1M), rpcinfo(1M), inetd.conf(4). .SH INTERNATIONAL SUPPORT 8-bit data, 16-bit data, messages .\" .\" index@\f4portmap\f1: \s-1DARPA\s+1 port to \s-1RPC\s+1 program number mapper@@@\f3portmap(1M)\f1 .\" index@\s-1DARPA\s+1 port to \s-1RPC\s+1 program number mapper@@@\f3portmap(1M)\f1 .\" index@\s-1RPC\s+1 program number mapper, \s-1DARPA\s+1 port to@@@\f3portmap(1M)\f1 .\" index@program number mapper, \s-1DARPA\s+1 port to \s-1RPC\s+1@@@\f3portmap(1M)\f1 .\" index@number mapper, \s-1DARPA\s+1 port to \s-1RPC\s+1 program@@@\f3portmap(1M)\f1 .\" index@mapper, \s-1DARPA\s+1 port to \s-1RPC\s+1 program number@@@\f3portmap(1M)\f1 .\" .\" toc@\f3portmap(1M)\f1: \f4portmap\f1@@@DARPA-port-to-RPC-program-number mapper .\" .\" fileset_database@portmap.1m SYS-ADMIN-MAN .\" $Header: power_onoff.1m,v 72.1 94/08/24 14:55:34 ssa Exp $ .TA p .TH power_onoff 1M " " "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME power_onoff \- timed, automatic system power on, and power off .SH SYNOPSIS .C /usr/sbin/power_onoff -n .br .C /usr/sbin/power_onoff\| .I time \| .RI [ \|date\| ] \| .RC [\|[ \|next \0\(or .CR + \f2increment\fP\|] \| .IR time_designation\| ] .SH DESCRIPTION .C power_onoff instructs the UPS monitor .RC ( ups_mond ) to shut down the system, and optionally informs the monitor when to power on the system again. The UPS monitor in turn instructs the uninterruptible power source (UPS) when to turn the power off and on. The UPS monitor then proceeds to shut down the system. The time to restart the system (power on) is specified with .C power_onoff command-line arguments. .PP Some UPS units limit the time that can elapse between the time the power is turned off and the time it is turned back on. Please see your UPS documentation for information about limitations. .PP .C power_onoff requires a UPS that is supported by the UPS monitor (see .IR ups_mond (1M)). .RE .SS Command Line Arguments The .C power_onoff command has two forms, and recognizes the following arguments: .TP 12 .C -n No power on. Causes the system to be shutdown and not be powered back on. .RE .TP 12 .I time Can be specified as one, two, or four digits. One- and two-digit numbers represent hours; four digits represent hours and minutes. .I time can also be specified as two numbers separated by a colon .RC ( \|:\| ), single quote .RC ( \|'\| ), the letter "h" .RC ( \|h\| ), a period .RC ( \|.\| ), or comma .RC ( \|,\| ). .\" If defined in locale (see EXTERNAL INFLUENCES) .\" special time unit characters can be used. A suffix .C am or .C pm can be appended. Otherwise a 24-hour clock time is understood. For example, .CR 0815 , .CR 8:15 , .CR 8'15 , .CR 8h15 , .CR 8.15 , and .CR 8,15 are read as 15 minutes after 8 in the morning. The suffixes .C zulu and .C utc can be used to indicate Coordinated Universal Time. The special names .CR noon , .CR midnight , .CR now , and .CR next are also recognized. .TP .I date Can be specified as either a day of the week (fully spelled out or abbreviated) or a date consisting of a day, a month, and optionally a year. The day and year fields must be numeric, and the month can be fully spelled out, abbreviated, or numeric. These three fields can be in any order, and be separated by punctuation marks such as .CR / , .CR - , .CR . , or .CR , . .\" If defined in locale (see EXTERNAL INFLUENCES) .\" special date unit characters can be present. Two special ``days'', .C today and .CR tomorrow , are also recognized. If no .I date is given, .C today is assumed if the given time is greater than the current time; .C tomorrow is assumed if it is less. If the given month is less than the current month (and no year is given), next year is assumed. .\" If a given date is ambiguous (such as 2/5), the D_T_FMT string .\" if defined in locale (see EXTERNAL INFLUENCES) .\" is used to resolve the ambiguity. .TP .C next .PD 0 .TP or .TP .CI + increment .sp -3v If followed by a .I time_designation of .CR minutes , .CR hours , .CR days , .CR weeks , .CR months , or .CR years , lets the user startup the system when the specified .I time_designation has elapsed. A numerical operator, .CI + increment, enables the user to schedule the startup several hours, days, weeks, months, or years in advance (see .SM EXAMPLES\s0). Using the argument .C next is equivalent to using an .I increment of .CR +1 . Both plural and singular forms of .I time_designation are accepted. .RE .PD .\" .PP .\" The words .\" .CR today , .\" .CR tomorrow , .\" .CR noon , .\" .CR midnight , .\" .CR now , .\" .CR minutes , .\" .CR hours , .\" .CR days , .\" .CR weeks , .\" .CR months , .\" .C years .\" and their singular forms are replaced .\" by the local language equivalent (see .\" .SM EXTERNAL INFLUENCES .\" below). .\" .SH EXTERNAL INFLUENCES .\" .SS Environment Variables .\" .C LC_TIME .\" determines the format and contents of date and time strings. .\" .PP .\" .C LANG .\" determines the translation of the words .\" .CR today , .\" .CR tomorrow , .\" .CR noon , .\" .CR midnight , .\" .CR now , .\" .CR minutes , .\" .CR hours , .\" .CR days , .\" .CR weeks , .\" .CR months , .\" .CR years , .\" .CR next , .\" and their singular forms. .\" .C LANG .\".\" also determines the language in which messages are displayed. .\" .PP .\" If .\" .C LC_TIME .\" is not specified in the environment .\" or is set to the empty string, the value of .\" .C LANG .\" is used as a default for each unspecified or empty variable. .\" If .\" .C LANG .\" is not specified or is set to the empty string, .\" a default of "C" (see .\" .IR lang (5)) .\" is used instead of .\" .CR LANG . .\" If any internationalization variable contains an invalid setting, .\" .C power_onoff .\" behaves as if all internationalization variables are set to "C". .\" See .\" .IR environ(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE Exit code 0 is returned upon successful completion, otherwise non 0 is returned. .SH DIAGNOSTICS .C power_onoff issues diagnostic messages when it encounters syntax errors and out-of-range times. .SH EXAMPLES .PP To startup the system at 5:00 am next Tuesday, use .IP .C "power_onoff 5am Tuesday next week" .PP To startup the system at 5:30 am tomorrow, use .IP .C "power_onoff 5:30 tomorrow" .PP To make your system startup each weekday at 7:30am and shutdown at 5:30pm each week day, use .C crontab to execute the first entry on Monday through Thursday and the second entry on Friday (see .IR crontab (1)). .IP .C "power_onoff 7:30 tomorrow" .IP .C "power_onoff 7:30 Monday" .PP To startup the system at 8:15 on January 24, use .IP .C "power_onoff 0815 Jan 24" .PP To startup the system at 5:15 on January 24, use .IP .C "power_onoff 8:15 Jan 24" .PP To startup the system at 9:30 tomorrow, use .IP .C "power_onoff 9:30am tomorrow" .PP To startup the system 24 hours from now, use .IP .C "power_onoff now + 1 day" .PP To shutdown the system and not start it up, use .IP .C "power_onoff -n" .SH WARNINGS .PP Some UPS units limit the time that can elapse between the time the power is turned off and the time it is turned back on. Please see your UPS documentation for information about limitations. .PP If the .I date argument begins with a number and the .I time argument is also numeric (and without suffix), the .I time argument should be a four-digit number that can be correctly interpreted as hours and minutes. .PP Do not use both .C next and .CI + " increment" within a single .C power_onoff command; only the first operator is accepted and the trailing operator is ignored. No warning or error is produced. .PP The power cord must be disconnected before servicing the unit. .SH AUTHOR .C power_onoff was developed by .SM HP. .SH FILES .TP 35 .C /var/tmp/timed_off fifo for communicating with ups_mond. .SH SEE ALSO at(1), cron(1M), crontab(1), queuedefs(4), proto(4), kill(1), .\" hpnls(5), sam(1M), ups_mond(1M). .\" .\" index@\f4power_onoff\f1 \- timed, automatic system power on, and power off@@@\f3power_onoff(1M)\f1 .\" index@timed, automatic system power on, and power off@@@\f3power_onoff(1M)\f1 .\" index@system startup and shutdown, timed@@@\f3power_onoff(1M)\f1 .\" .\" toc@\f3power_onoff(1M)\f1:\0\0\f4power_onoff\f1@@@timed, system power on/off .\" $Header: acctsh.1m,v 72.4 94/11/14 12:02:10 ssa Exp $ .TA a .TH acctsh 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chargefee, ckpacct, dodisk, lastlogin, monacct, nulladm, prctmp, prdaily, prtacct, shutacct, startup, turnacct \- shell procedures for accounting .SH SYNOPSIS .C /usr/sbin/acct/chargefee .I login-name number .PP .C /usr/sbin/acct/ckpacct .RI [ \|blocks\| ] .PP .C /usr/sbin/acct/dodisk .RC [ -o ] .RI [ \|files \0 ...\|] .PP .C /usr/sbin/acct/lastlogin .PP .C /usr/sbin/acct/monacct .I number .PP .C /usr/sbin/acct/nulladm .I file .PP .C /usr/sbin/acct/prctmp .PP .C /usr/sbin/acct/prdaily .RC [ -l ] .RC [ -c ] .RC [ \c .IR mmdd\| ] .PP .C /usr/sbin/acct/prtacct .I file .RI [ \|heading\| ] .PP .C /usr/sbin/acct/shutacct .RI [ \|reason\| ] .PP .C /usr/sbin/acct/startup .PP .C /usr/sbin/acct/turnacct .CR on \0\(or\0 off \0\(or\0 switch .SH DESCRIPTION .TP 15 .C chargefee Can be invoked to charge a .I number of units to .IR login-name . A record is written to .CR /var/adm/fee , to be merged with other accounting records during the night. .TP .C ckpacct Should be initiated via .IR cron (1M). It periodically checks the size of .CR /var/adm/pacct . If the size exceeds .IR blocks , 1000 by default, .C turnacct is invoked with argument .IR switch . If the number of free disk blocks in the .C /var file system falls below 500, .C ckpacct automatically turns off the collection of process accounting records via the .C off argument to .CR turnacct . When at least this number of blocks is restored, the accounting will be activated again. This feature is sensitive to the frequency at which .C ckpacct is executed, usually by .CR cron . .TP .C dodisk Should be invoked by .C cron to perform the disk accounting functions. By default, it will do disk accounting on the special files in .C /etc/fstab. If the .C -o flag is used, it does a slower version of disk accounting by login directory. .I files specifies the one or more filesystem names where disk accounting is to be done. If .I files is used, disk accounting will be done on these filesystems only. If the .C -o flag is used, .I files should be mount points of mounted filesystem. If omitted, they should be the special file names of mountable filesystems. .TP .C lastlogin Invoked by .C runacct to update .C /var/adm/acct/sum/loginlog which shows the last date on which each user logged in (see .IR runacct (1M)). .TP .C monacct Should be invoked once each month or each accounting period. .I number indicates which month or period it is. If .I number is not given, it defaults to the current month (01 through 12). This default is useful if .C monacct is to executed via .CR cron on the first day of each month. .C monacct creates summary files in .C /var/adm/acct/fiscal and restarts summary files in .CR /var/adm/acct/sum . .TP .C nulladm Creates .I file with mode 664 and ensures that owner and group are .CR adm . It is called by various accounting shell procedures. .TP .C prctmp Can be used to print the session record file normally .C /var/adm/acct/nite/ctmp created by .C acctcon1 (see .IR acctcon (1M)). .TP .C prdaily Invoked by .C runacct (see .IR runacct (1M)) to format a report of the previous day's accounting data. The report resides in .CI /var/adm/acct/sum/rprt mmdd where .I mmdd is the month and day of the report. The current daily accounting reports may be printed by typing .IR prdaily . Previous days' accounting reports can be printed by using the .I mmdd option and specifying the exact report date desired. The .C -l flag prints a report of exceptional usage by login id for the specifed date. Previous daily reports are cleaned up and therefore inaccessible after each invocation of .CR monacct . The .C -c flag prints a report of exceptional resource usage by command, and can be used on current day's accounting data only. .TP .C prtacct Can be used to format and print any total accounting .RC ( tacct ) file. .TP .C shutacct Should be invoked during a system shutdown to turn process accounting off and append a ``reason'' record to .CR /var/adm/wtmp . .TP .C startup Should be called by system startup scripts to turn the accounting on whenever the system is brought up. .TP .C turnacct An interface to .C accton (see .IR acct (1M)) to turn process accounting .C on or .CR off . The .C switch argument turns accounting off, moves the current .C /var/adm/pacct to the next free name in .CI /var/adm/pacct incr then turns accounting back on again. .RI ( incr is a number starting with .C 1 and incrementing by one for each additional .C pacct file.) .C turnacct is called by .CR ckpacct , and thus can be run under .C cron and used to keep .C pacct to a reasonable size. .SH FILES .TP 40 .C /usr/sbin/acct holds all accounting commands listed in section (1M) of this manual .PD 0 .TP .C /var/adm/fee accumulator for fees .TP .C /var/adm/acct/nite working directory .TP .C /var/adm/pacct current file for per-process accounting .TP .C /var/adm/pacct* used if .C pacct gets large, and during execution of daily accounting procedure .TP .C /usr/sbin/acct/ptecms.awk contains the limits for exceptional usage by command name .TP .C /usr/sbin/acct/ptelus.awk contains the limits for exceptional usage by login id .TP .C /var/adm/acct/sum summary directory, should be saved .TP .C /var/adm/wtmp login/logoff summary .PD .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), cron(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR chargefee ": SVID2, SVID3" .PP .CR ckpacct ": SVID2, SVID3" .PP .CR dodisk ": SVID2, SVID3" .PP .CR lastlogin ": SVID2, SVID3" .PP .CR monacct ": SVID2, SVID3" .PP .CR prctmp ": SVID2, SVID3" .PP .CR prdaily ": SVID2, SVID3" .PP .CR prtacct ": SVID2, SVID3" .PP .CR shutacct ": SVID2, SVID3" .PP .CR startup ": SVID2, SVID3" .PP .CR turnacct ": SVID2, SVID3" .\" .\" .\" index@\f1process accounting@@@see accounting .\" index@\f1accounting: \f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4turnacct\f1 \- turn on or turn off process accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1bill fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1user, bill fee to, based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1disk accounting, perform@@@\f3acctsh(1M)\f1 .\" index@\f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1user, show last login date for each@@@\f3acctsh(1M)\f1 .\" index@\f1last login date, show for each user@@@\f3acctsh(1M)\f1 .\" index@\f1login date, show last for each user@@@\f3acctsh(1M)\f1 .\" index@\f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1periodic accounting summary files, create@@@\f3acctsh(1M)\f1 .\" index@\f1accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1files: accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1summary files, accounting, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1create empty administration file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1empty administration file owned by \f3adm\f1 with mode 664, create@@@\f3acctsh(1M)\f1 .\" index@\f1administration file owned by \f3adm\f1 with mode 664, create empty@@@\f3acctsh(1M)\f1 .\" index@\f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f4acctcon1\f1 \- print session record file created by@@@\f3acctsh(1M)\f1 .\" index@\f1print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1files, accounting: print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1session record file created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f1record file, session, created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1total accounting (\f4tacct\f1) file, print any@@@\f3acctsh(1M)\f1 .\" index@\f1accounting (\f4tacct\f1) file, print any total@@@\f3acctsh(1M)\f1 .\" index@\f4tacct\f1 (total accounting) file, print any@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting: \f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" index@\f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting data and command usage summary, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f1command usage summary and accounting data, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1system shutdown, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f1shutdown, system, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1system startup, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f1startup, system, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f4turnacct\f1 \- turn process accounting on or off@@@\f3acctsh(1M)\f1 .\" index@\f1shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f1system accounting, shell procedures for@@@\f3acctsh(1M)\f1 .\" .\"" Main TOC entry .\" toc@\f3acctsh(1M)\f1:\0\0\f4chargefee\f1, \f4ckpacct\f1, \f4dodisk\f1, \f4lastlogin\f1, \f4monacct\f1, \f4nulladm\f1, \f4prctmp\f1, \f4prdaily\f1,\n\f4prtacct\f1, \f4shutacct\f1, \f4startup\f1, \f4turnacct\f1@@@shell procedures for accounting .\" .\" toc@\f4chargefee\f1:\0\0shell procedures for accounting, charge fee to user@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4ckpacct\f1:\0\0shell procedures for accounting, check size of accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4dodisk\f1:\0\0shell procedures for accounting, perform disk accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4lastlogin\f1:\0\0shell procedures for accounting, show last login date@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4monacct\f1:\0\0shell procedures for accounting, create accounting summary@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4nulladm\f1:\0\0shell procedures for accounting, create null file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prctmp\f1:\0\0shell procedures for accounting, print session record file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prdaily\f1:\0\0shell procedures for accounting, print daily report@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prtacct\f1:\0\0shell procedures for accounting, print accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4shutacct\f1:\0\0shell procedures for accounting, turn off accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4startup\f1:\0\0shell procedures for accounting, start up accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4turnacct\f1:\0\0shell procedures for accounting, turn on or off process accounting@@@\f1see \f3acctsh(1M)\f1 .\" .\" links@acctsh.1m chargefee.1m .\" links@acctsh.1m ckpacct.1m .\" links@acctsh.1m dodisk.1m .\" links@acctsh.1m lastlogin.1m .\" links@acctsh.1m monacct.1m .\" links@acctsh.1m nulladm.1m .\" links@acctsh.1m prctmp.1m .\" links@acctsh.1m prdaily.1m .\" links@acctsh.1m prtacct.1m .\" links@acctsh.1m shutacct.1m .\" links@acctsh.1m startup.1m .\" links@acctsh.1m turnacct.1m .\" .\" fileset_database@acctsh.1m SYS-ADMIN-MAN .\" $Header: acctsh.1m,v 72.4 94/11/14 12:02:10 ssa Exp $ .TA a .TH acctsh 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chargefee, ckpacct, dodisk, lastlogin, monacct, nulladm, prctmp, prdaily, prtacct, shutacct, startup, turnacct \- shell procedures for accounting .SH SYNOPSIS .C /usr/sbin/acct/chargefee .I login-name number .PP .C /usr/sbin/acct/ckpacct .RI [ \|blocks\| ] .PP .C /usr/sbin/acct/dodisk .RC [ -o ] .RI [ \|files \0 ...\|] .PP .C /usr/sbin/acct/lastlogin .PP .C /usr/sbin/acct/monacct .I number .PP .C /usr/sbin/acct/nulladm .I file .PP .C /usr/sbin/acct/prctmp .PP .C /usr/sbin/acct/prdaily .RC [ -l ] .RC [ -c ] .RC [ \c .IR mmdd\| ] .PP .C /usr/sbin/acct/prtacct .I file .RI [ \|heading\| ] .PP .C /usr/sbin/acct/shutacct .RI [ \|reason\| ] .PP .C /usr/sbin/acct/startup .PP .C /usr/sbin/acct/turnacct .CR on \0\(or\0 off \0\(or\0 switch .SH DESCRIPTION .TP 15 .C chargefee Can be invoked to charge a .I number of units to .IR login-name . A record is written to .CR /var/adm/fee , to be merged with other accounting records during the night. .TP .C ckpacct Should be initiated via .IR cron (1M). It periodically checks the size of .CR /var/adm/pacct . If the size exceeds .IR blocks , 1000 by default, .C turnacct is invoked with argument .IR switch . If the number of free disk blocks in the .C /var file system falls below 500, .C ckpacct automatically turns off the collection of process accounting records via the .C off argument to .CR turnacct . When at least this number of blocks is restored, the accounting will be activated again. This feature is sensitive to the frequency at which .C ckpacct is executed, usually by .CR cron . .TP .C dodisk Should be invoked by .C cron to perform the disk accounting functions. By default, it will do disk accounting on the special files in .C /etc/fstab. If the .C -o flag is used, it does a slower version of disk accounting by login directory. .I files specifies the one or more filesystem names where disk accounting is to be done. If .I files is used, disk accounting will be done on these filesystems only. If the .C -o flag is used, .I files should be mount points of mounted filesystem. If omitted, they should be the special file names of mountable filesystems. .TP .C lastlogin Invoked by .C runacct to update .C /var/adm/acct/sum/loginlog which shows the last date on which each user logged in (see .IR runacct (1M)). .TP .C monacct Should be invoked once each month or each accounting period. .I number indicates which month or period it is. If .I number is not given, it defaults to the current month (01 through 12). This default is useful if .C monacct is to executed via .CR cron on the first day of each month. .C monacct creates summary files in .C /var/adm/acct/fiscal and restarts summary files in .CR /var/adm/acct/sum . .TP .C nulladm Creates .I file with mode 664 and ensures that owner and group are .CR adm . It is called by various accounting shell procedures. .TP .C prctmp Can be used to print the session record file normally .C /var/adm/acct/nite/ctmp created by .C acctcon1 (see .IR acctcon (1M)). .TP .C prdaily Invoked by .C runacct (see .IR runacct (1M)) to format a report of the previous day's accounting data. The report resides in .CI /var/adm/acct/sum/rprt mmdd where .I mmdd is the month and day of the report. The current daily accounting reports may be printed by typing .IR prdaily . Previous days' accounting reports can be printed by using the .I mmdd option and specifying the exact report date desired. The .C -l flag prints a report of exceptional usage by login id for the specifed date. Previous daily reports are cleaned up and therefore inaccessible after each invocation of .CR monacct . The .C -c flag prints a report of exceptional resource usage by command, and can be used on current day's accounting data only. .TP .C prtacct Can be used to format and print any total accounting .RC ( tacct ) file. .TP .C shutacct Should be invoked during a system shutdown to turn process accounting off and append a ``reason'' record to .CR /var/adm/wtmp . .TP .C startup Should be called by system startup scripts to turn the accounting on whenever the system is brought up. .TP .C turnacct An interface to .C accton (see .IR acct (1M)) to turn process accounting .C on or .CR off . The .C switch argument turns accounting off, moves the current .C /var/adm/pacct to the next free name in .CI /var/adm/pacct incr then turns accounting back on again. .RI ( incr is a number starting with .C 1 and incrementing by one for each additional .C pacct file.) .C turnacct is called by .CR ckpacct , and thus can be run under .C cron and used to keep .C pacct to a reasonable size. .SH FILES .TP 40 .C /usr/sbin/acct holds all accounting commands listed in section (1M) of this manual .PD 0 .TP .C /var/adm/fee accumulator for fees .TP .C /var/adm/acct/nite working directory .TP .C /var/adm/pacct current file for per-process accounting .TP .C /var/adm/pacct* used if .C pacct gets large, and during execution of daily accounting procedure .TP .C /usr/sbin/acct/ptecms.awk contains the limits for exceptional usage by command name .TP .C /usr/sbin/acct/ptelus.awk contains the limits for exceptional usage by login id .TP .C /var/adm/acct/sum summary directory, should be saved .TP .C /var/adm/wtmp login/logoff summary .PD .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), cron(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR chargefee ": SVID2, SVID3" .PP .CR ckpacct ": SVID2, SVID3" .PP .CR dodisk ": SVID2, SVID3" .PP .CR lastlogin ": SVID2, SVID3" .PP .CR monacct ": SVID2, SVID3" .PP .CR prctmp ": SVID2, SVID3" .PP .CR prdaily ": SVID2, SVID3" .PP .CR prtacct ": SVID2, SVID3" .PP .CR shutacct ": SVID2, SVID3" .PP .CR startup ": SVID2, SVID3" .PP .CR turnacct ": SVID2, SVID3" .\" .\" .\" index@\f1process accounting@@@see accounting .\" index@\f1accounting: \f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4turnacct\f1 \- turn on or turn off process accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1bill fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1user, bill fee to, based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1disk accounting, perform@@@\f3acctsh(1M)\f1 .\" index@\f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1user, show last login date for each@@@\f3acctsh(1M)\f1 .\" index@\f1last login date, show for each user@@@\f3acctsh(1M)\f1 .\" index@\f1login date, show last for each user@@@\f3acctsh(1M)\f1 .\" index@\f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1periodic accounting summary files, create@@@\f3acctsh(1M)\f1 .\" index@\f1accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1files: accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1summary files, accounting, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1create empty administration file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1empty administration file owned by \f3adm\f1 with mode 664, create@@@\f3acctsh(1M)\f1 .\" index@\f1administration file owned by \f3adm\f1 with mode 664, create empty@@@\f3acctsh(1M)\f1 .\" index@\f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f4acctcon1\f1 \- print session record file created by@@@\f3acctsh(1M)\f1 .\" index@\f1print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1files, accounting: print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1session record file created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f1record file, session, created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1total accounting (\f4tacct\f1) file, print any@@@\f3acctsh(1M)\f1 .\" index@\f1accounting (\f4tacct\f1) file, print any total@@@\f3acctsh(1M)\f1 .\" index@\f4tacct\f1 (total accounting) file, print any@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting: \f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" index@\f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting data and command usage summary, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f1command usage summary and accounting data, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1system shutdown, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f1shutdown, system, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1system startup, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f1startup, system, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f4turnacct\f1 \- turn process accounting on or off@@@\f3acctsh(1M)\f1 .\" index@\f1shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f1system accounting, shell procedures for@@@\f3acctsh(1M)\f1 .\" .\"" Main TOC entry .\" toc@\f3acctsh(1M)\f1:\0\0\f4chargefee\f1, \f4ckpacct\f1, \f4dodisk\f1, \f4lastlogin\f1, \f4monacct\f1, \f4nulladm\f1, \f4prctmp\f1, \f4prdaily\f1,\n\f4prtacct\f1, \f4shutacct\f1, \f4startup\f1, \f4turnacct\f1@@@shell procedures for accounting .\" .\" toc@\f4chargefee\f1:\0\0shell procedures for accounting, charge fee to user@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4ckpacct\f1:\0\0shell procedures for accounting, check size of accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4dodisk\f1:\0\0shell procedures for accounting, perform disk accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4lastlogin\f1:\0\0shell procedures for accounting, show last login date@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4monacct\f1:\0\0shell procedures for accounting, create accounting summary@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4nulladm\f1:\0\0shell procedures for accounting, create null file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prctmp\f1:\0\0shell procedures for accounting, print session record file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prdaily\f1:\0\0shell procedures for accounting, print daily report@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prtacct\f1:\0\0shell procedures for accounting, print accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4shutacct\f1:\0\0shell procedures for accounting, turn off accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4startup\f1:\0\0shell procedures for accounting, start up accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4turnacct\f1:\0\0shell procedures for accounting, turn on or off process accounting@@@\f1see \f3acctsh(1M)\f1 .\" .\" links@acctsh.1m chargefee.1m .\" links@acctsh.1m ckpacct.1m .\" links@acctsh.1m dodisk.1m .\" links@acctsh.1m lastlogin.1m .\" links@acctsh.1m monacct.1m .\" links@acctsh.1m nulladm.1m .\" links@acctsh.1m prctmp.1m .\" links@acctsh.1m prdaily.1m .\" links@acctsh.1m prtacct.1m .\" links@acctsh.1m shutacct.1m .\" links@acctsh.1m startup.1m .\" links@acctsh.1m turnacct.1m .\" .\" fileset_database@acctsh.1m SYS-ADMIN-MAN .\" $Header: proxy.1m,v 72.1 93/01/15 10:55:52 ssa Exp $ .TA p .TH proxy 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME proxy \- manipulates the \s-1NS\s+1 Probe proxy table .SH SYNOPSIS .B proxy on .PP .B proxy off .PP .B proxy add .I nodename domain ip_address medium .PP .B proxy append .I nodename domain ip_address medium .PP .B proxy delete .I nodename .PP .B proxy show .I nodename .PP .B proxy flush .PP .B proxy list .SH DESCRIPTION .I proxy enables or disables Probe proxy server capability on a node on a .SM LAN or .SM WAN. .B proxy also adds entries to the Probe proxy table or deletes entries from the Probe proxy table on a node. A probe proxy server enables .SM NS through a \s-1LAN\s0-to-\s-1LAN\s0, \s-1LAN\s0-to-\s-1WAN\s0, \s-1WAN\s0-to-\s-1WAN\s0 gateway when used with the .IR route (1M) command. .SM NS uses the probe protocol for name-to-\s-1IP\s0-Address-resolution. By itself, the probe protocol can only obtain information about nodes on the same network or subnetwork. The probe proxy server provides .SM IP address information about nodes on remote connected networks. The Probe proxy server can be a gateway node or any other node on the .SM LAN. Note: The Probe protocol is not supported over .SM X.25 links. In order to initiate .SM NS over a connection path whose first hop is an .SM X.25 link, the initiating node must be a Probe proxy server, and must include an entry for the target node in its Probe proxy table. .SS Options .TP 20 .B on Enables Probe proxy on a node. This option must be used before invoking any other proxy option. Requires super-user capability. .TP .B off Disables the Probe proxy server. The Probe proxy table is not flushed. Requires super-user capability. .TP .B add Adds a new entry to the Probe proxy table. Requires super-user capability. The following parameters are required: .RS 23 .TP 12 .I nodename A fully-qualified .SM NS node name, including domain and organization. See .IR nodename (1) for details. .TP .I domain Internet domain. The only supported domain is .SM HPDSN. .TP .I ip_address An .SM IP address of the remote node being mapped to by .IR nodename . The .SM IP address must be in internet ``dot'' format. See .IR inet (3N) for details on internet dot format. .TP .I medium The physical link medium, either .BR ieee , .BR ether , or .BR x.25 . .RE .TP 20 .B append Appends an additional path report to an existing Probe proxy table entry. Use this option if a remote node supports more than one among .SM IEEE 802.3 .RB ( ieee ), Ethernet .RB ( ether ), and X.25 .RB ( x.25 ) links, or if a remote node contains more than one network interface. .B append requires the same parameters as the .B add option described above. Requires super-user capability. .TP .BI delete \ nodename Deletes .I nodename and all path reports associated with .I nodename from the Probe proxy table. Requires super-user capability. .TP .B flush Clears the Probe proxy table, deleting all entries. Requires super-user capability. .TP .BI show \ nodename Sends path report information for .I nodename to standard output. For each path report associated with .IR nodename , the following information is returned: node name, .SM IP address or addresseses, medium, services, and transports. The services and transports field will always contain the value .SM FFFF, meaning that all services and transports are enabled. .TP .B list Returns information for all entries in the Probe proxy table. .B proxy list is equivalent to issuing a .B proxy show command for all node names in the Probe proxy table. .SH DIAGNOSTICS .PP .B "proxy server not yet enabled \-" .br .B "must do so before issuing any other proxy commands" .RS 15 Other \f3proxy\f1 options attempted before .B proxy on issued. .RE .TP 15 .B "proxy on: proxy server was already enabled" .B proxy on issued after proxy server already enabled. .TP 15 .B "proxy off: proxy server was already disabled" Super-user tried to turn off an already disabled proxy server. .TP 15 .B "proxy add: entry already exists" Super-user tried to add to the proxy table an entry which already exists. .TP 15 .B "proxy: out of memory for path reports" Probe proxy memory account is depleted. .TP 15 .B "proxy add: no space left in hash table buckets" Super-user tried to add too many entries that hash to the same bucket in the proxy table. .TP 15 .B "proxy append: entry does not exist" Super-user tried to append to a proxy table entry which had not been added. .TP 15 .B "proxy delete: entry does not exist" Super-user tried to delete an entry in the proxy table which had never been added. .TP 15 .B "proxy show: no entry for \f2nodename\f1" Requested .I nodename had no entry in proxy table. .SH WARNINGS Reciprocal .I route commands must be executed on the local proxy requestor, the destination host, and all intermediate hosts before .SM NS routing can succeed. See .IR route (1M) and .IR routing (7) for details. .PP Proxy entries are hashed for storage. Each hash bucket contains room for only five entries. There are 19 hash buckets for a potential total of 95 entries. .SH AUTHOR .I proxy was developed by HP .SH "SEE ALSO" nodename(1), route(1M), inet(3N), routing(7). .\" .\" index@\f2proxy\f1 \- manipulate \s-1NS\s+1 Probe proxy table@@@\f3proxy(1M)\f1 .\" index@manipulate \s-1NS\s+1 Probe proxy table@@@\f3proxy(1M)\f1 .\" index@\s-1NS\s+1 Probe proxy table, manipulate@@@\f3proxy(1M)\f1 .\" index@Probe proxy table, manipulate \s-1NS\s+1@@@\f3proxy(1M)\f1 .\" index@proxy table, manipulate \s-1NS\s+1 Probe@@@\f3proxy(1M)\f1 .\" index@table, manipulate \s-1NS\s+1 Probe proxy@@@\f3proxy(1M)\f1 .\" .\" toc@\f3proxy(1M)\f1:\0\0\f2proxy\f1@@@manipulate \s-1NS\s+1 Probe proxy table .\" .\" fileset_database@proxy.1m@SYS-ADMIN-MAN .\" $Header: acctsh.1m,v 72.4 94/11/14 12:02:10 ssa Exp $ .TA a .TH acctsh 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chargefee, ckpacct, dodisk, lastlogin, monacct, nulladm, prctmp, prdaily, prtacct, shutacct, startup, turnacct \- shell procedures for accounting .SH SYNOPSIS .C /usr/sbin/acct/chargefee .I login-name number .PP .C /usr/sbin/acct/ckpacct .RI [ \|blocks\| ] .PP .C /usr/sbin/acct/dodisk .RC [ -o ] .RI [ \|files \0 ...\|] .PP .C /usr/sbin/acct/lastlogin .PP .C /usr/sbin/acct/monacct .I number .PP .C /usr/sbin/acct/nulladm .I file .PP .C /usr/sbin/acct/prctmp .PP .C /usr/sbin/acct/prdaily .RC [ -l ] .RC [ -c ] .RC [ \c .IR mmdd\| ] .PP .C /usr/sbin/acct/prtacct .I file .RI [ \|heading\| ] .PP .C /usr/sbin/acct/shutacct .RI [ \|reason\| ] .PP .C /usr/sbin/acct/startup .PP .C /usr/sbin/acct/turnacct .CR on \0\(or\0 off \0\(or\0 switch .SH DESCRIPTION .TP 15 .C chargefee Can be invoked to charge a .I number of units to .IR login-name . A record is written to .CR /var/adm/fee , to be merged with other accounting records during the night. .TP .C ckpacct Should be initiated via .IR cron (1M). It periodically checks the size of .CR /var/adm/pacct . If the size exceeds .IR blocks , 1000 by default, .C turnacct is invoked with argument .IR switch . If the number of free disk blocks in the .C /var file system falls below 500, .C ckpacct automatically turns off the collection of process accounting records via the .C off argument to .CR turnacct . When at least this number of blocks is restored, the accounting will be activated again. This feature is sensitive to the frequency at which .C ckpacct is executed, usually by .CR cron . .TP .C dodisk Should be invoked by .C cron to perform the disk accounting functions. By default, it will do disk accounting on the special files in .C /etc/fstab. If the .C -o flag is used, it does a slower version of disk accounting by login directory. .I files specifies the one or more filesystem names where disk accounting is to be done. If .I files is used, disk accounting will be done on these filesystems only. If the .C -o flag is used, .I files should be mount points of mounted filesystem. If omitted, they should be the special file names of mountable filesystems. .TP .C lastlogin Invoked by .C runacct to update .C /var/adm/acct/sum/loginlog which shows the last date on which each user logged in (see .IR runacct (1M)). .TP .C monacct Should be invoked once each month or each accounting period. .I number indicates which month or period it is. If .I number is not given, it defaults to the current month (01 through 12). This default is useful if .C monacct is to executed via .CR cron on the first day of each month. .C monacct creates summary files in .C /var/adm/acct/fiscal and restarts summary files in .CR /var/adm/acct/sum . .TP .C nulladm Creates .I file with mode 664 and ensures that owner and group are .CR adm . It is called by various accounting shell procedures. .TP .C prctmp Can be used to print the session record file normally .C /var/adm/acct/nite/ctmp created by .C acctcon1 (see .IR acctcon (1M)). .TP .C prdaily Invoked by .C runacct (see .IR runacct (1M)) to format a report of the previous day's accounting data. The report resides in .CI /var/adm/acct/sum/rprt mmdd where .I mmdd is the month and day of the report. The current daily accounting reports may be printed by typing .IR prdaily . Previous days' accounting reports can be printed by using the .I mmdd option and specifying the exact report date desired. The .C -l flag prints a report of exceptional usage by login id for the specifed date. Previous daily reports are cleaned up and therefore inaccessible after each invocation of .CR monacct . The .C -c flag prints a report of exceptional resource usage by command, and can be used on current day's accounting data only. .TP .C prtacct Can be used to format and print any total accounting .RC ( tacct ) file. .TP .C shutacct Should be invoked during a system shutdown to turn process accounting off and append a ``reason'' record to .CR /var/adm/wtmp . .TP .C startup Should be called by system startup scripts to turn the accounting on whenever the system is brought up. .TP .C turnacct An interface to .C accton (see .IR acct (1M)) to turn process accounting .C on or .CR off . The .C switch argument turns accounting off, moves the current .C /var/adm/pacct to the next free name in .CI /var/adm/pacct incr then turns accounting back on again. .RI ( incr is a number starting with .C 1 and incrementing by one for each additional .C pacct file.) .C turnacct is called by .CR ckpacct , and thus can be run under .C cron and used to keep .C pacct to a reasonable size. .SH FILES .TP 40 .C /usr/sbin/acct holds all accounting commands listed in section (1M) of this manual .PD 0 .TP .C /var/adm/fee accumulator for fees .TP .C /var/adm/acct/nite working directory .TP .C /var/adm/pacct current file for per-process accounting .TP .C /var/adm/pacct* used if .C pacct gets large, and during execution of daily accounting procedure .TP .C /usr/sbin/acct/ptecms.awk contains the limits for exceptional usage by command name .TP .C /usr/sbin/acct/ptelus.awk contains the limits for exceptional usage by login id .TP .C /var/adm/acct/sum summary directory, should be saved .TP .C /var/adm/wtmp login/logoff summary .PD .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), cron(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR chargefee ": SVID2, SVID3" .PP .CR ckpacct ": SVID2, SVID3" .PP .CR dodisk ": SVID2, SVID3" .PP .CR lastlogin ": SVID2, SVID3" .PP .CR monacct ": SVID2, SVID3" .PP .CR prctmp ": SVID2, SVID3" .PP .CR prdaily ": SVID2, SVID3" .PP .CR prtacct ": SVID2, SVID3" .PP .CR shutacct ": SVID2, SVID3" .PP .CR startup ": SVID2, SVID3" .PP .CR turnacct ": SVID2, SVID3" .\" .\" .\" index@\f1process accounting@@@see accounting .\" index@\f1accounting: \f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4turnacct\f1 \- turn on or turn off process accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1bill fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1user, bill fee to, based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1disk accounting, perform@@@\f3acctsh(1M)\f1 .\" index@\f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1user, show last login date for each@@@\f3acctsh(1M)\f1 .\" index@\f1last login date, show for each user@@@\f3acctsh(1M)\f1 .\" index@\f1login date, show last for each user@@@\f3acctsh(1M)\f1 .\" index@\f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1periodic accounting summary files, create@@@\f3acctsh(1M)\f1 .\" index@\f1accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1files: accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1summary files, accounting, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1create empty administration file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1empty administration file owned by \f3adm\f1 with mode 664, create@@@\f3acctsh(1M)\f1 .\" index@\f1administration file owned by \f3adm\f1 with mode 664, create empty@@@\f3acctsh(1M)\f1 .\" index@\f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f4acctcon1\f1 \- print session record file created by@@@\f3acctsh(1M)\f1 .\" index@\f1print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1files, accounting: print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1session record file created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f1record file, session, created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1total accounting (\f4tacct\f1) file, print any@@@\f3acctsh(1M)\f1 .\" index@\f1accounting (\f4tacct\f1) file, print any total@@@\f3acctsh(1M)\f1 .\" index@\f4tacct\f1 (total accounting) file, print any@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting: \f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" index@\f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting data and command usage summary, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f1command usage summary and accounting data, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1system shutdown, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f1shutdown, system, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1system startup, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f1startup, system, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f4turnacct\f1 \- turn process accounting on or off@@@\f3acctsh(1M)\f1 .\" index@\f1shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f1system accounting, shell procedures for@@@\f3acctsh(1M)\f1 .\" .\"" Main TOC entry .\" toc@\f3acctsh(1M)\f1:\0\0\f4chargefee\f1, \f4ckpacct\f1, \f4dodisk\f1, \f4lastlogin\f1, \f4monacct\f1, \f4nulladm\f1, \f4prctmp\f1, \f4prdaily\f1,\n\f4prtacct\f1, \f4shutacct\f1, \f4startup\f1, \f4turnacct\f1@@@shell procedures for accounting .\" .\" toc@\f4chargefee\f1:\0\0shell procedures for accounting, charge fee to user@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4ckpacct\f1:\0\0shell procedures for accounting, check size of accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4dodisk\f1:\0\0shell procedures for accounting, perform disk accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4lastlogin\f1:\0\0shell procedures for accounting, show last login date@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4monacct\f1:\0\0shell procedures for accounting, create accounting summary@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4nulladm\f1:\0\0shell procedures for accounting, create null file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prctmp\f1:\0\0shell procedures for accounting, print session record file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prdaily\f1:\0\0shell procedures for accounting, print daily report@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prtacct\f1:\0\0shell procedures for accounting, print accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4shutacct\f1:\0\0shell procedures for accounting, turn off accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4startup\f1:\0\0shell procedures for accounting, start up accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4turnacct\f1:\0\0shell procedures for accounting, turn on or off process accounting@@@\f1see \f3acctsh(1M)\f1 .\" .\" links@acctsh.1m chargefee.1m .\" links@acctsh.1m ckpacct.1m .\" links@acctsh.1m dodisk.1m .\" links@acctsh.1m lastlogin.1m .\" links@acctsh.1m monacct.1m .\" links@acctsh.1m nulladm.1m .\" links@acctsh.1m prctmp.1m .\" links@acctsh.1m prdaily.1m .\" links@acctsh.1m prtacct.1m .\" links@acctsh.1m shutacct.1m .\" links@acctsh.1m startup.1m .\" links@acctsh.1m turnacct.1m .\" .\" fileset_database@acctsh.1m SYS-ADMIN-MAN .\"@(#) $Header: pscan.1m,v 1.2 95/12/15 11:38:52 hmgr Exp $ .\"========================================================= .\" (c) 1992, 1993 Hewlett-Packard Company. All Rights Reserved. .\" Author: Hewlett-Packard DMD .\"========================================================= .\" .TA p .TH pscan 1M .SH NAME pscan \- scan an .SM HP SCSI disk array .SM LUN for parity consistency .SH SYNOPSIS .PP .C pscan -s .I system_state .I device_file .SH DESCRIPTION .C pscan is a front end script to .C scn designed to be called during system bootup and shutdown. It stores information on the disk array used to indicate improper system shutdown. If the system was not properly shutdown, a parity scan is initiated when the system boots. The values of 0 (operating system booting), and 1 (operating system shutdown) are expected for .IR system_state . .I device_file refers to the device file associated with the selected disk array. If multiple hosts (initiators) are connected to the disk array, the file /etc/hpC2400/pscan.initiators needs to be created. This file will contain an integer value from 1 to 8. If the file is not created, pscan will assume that only one host (initiator) is connected to the disk array. .SH RETURN VALUE .C pscan returns the following values: .RS 5 .TP .B " 0" Successful completion. .PD 0 .TP .B -1 Command failed (an error occurred). .PD .PP .RE .SH DIAGNOSTICS AND ERRORS Errors can originate from problems with: .RS .TP 3 \(bu .C pscan .TP \(bu .SM SCSI (device level) communications .TP \(bu system calls .RE .PP .SS Error messages generated by pscan: .TP .C "usage: pscan -s " An error in command syntax has occurred. Enter command again with all required arguments, in the order shown. .TP .C "pscan: LUN # too big" The .SM LUN number, which is derived from the device file name, is out of range. .TP .C "pscan: Not a raw file" Utilities must be able to open the device file for raw access. .TP .C "pscan: LUN does not exist" The addressed .SM LUN is not configured, and thus is not known to the array controller. .TP .C "pscan: Not an HP SCSI disk array" The device being addressed is not an .SM HP SCSI disk array. .PP .SS SCSI (device level) communication errors: Sense data associated with the failed operation is printed. .PP .SS Error messages generated by system calls: .C pscan uses the following system calls: .IP .CR malloc() , .CR free() , .CR stat() , .CR open() , .CR close() , .CR fopen() , .CR fclose() , .CR read() , .CR write() , and .CR ioctl() . .PP Documentation for these .SM HP-UX system calls contains information about the specific error conditions associated with each call. .C pscan does not alter the value of .CR errno . The interpretation of .C errno for printing purposes is performed by the system utility .CR strerror() . .SH EXAMPLES .PP To call pscan on the .SM LUN .C /dev/rdsk/c2t0d2 prior to a system shutdown on a series 800: .IP .C "pscan -s 1 /dev/rdsk/c2t0d2" .PP To call pscan on the .SM LUN .C /dev/rdsk/c2t0d2 during a system bootup on a series 700: .IP .C "pscan -s 0 /dev/rdsk/c2t0d2" .SH DEPENDENCIES The HP C2425 and HP C2427 disk arrays are only supported on Series 700 systems running HP-UX version 9.0X. .PP The HP C2430 disk array is supported on Series 700 and 800 systems running HP-UX versions 9.0X and 10.0X. .SH AUTHOR .PP .C pscan was developed by .SM HP. .\" .\" index@\f4pscan\f1 \- scan \s-1HP SCSI\s+1 disk array \s-1LUN\s+1s for parity consistency@@@\f3pscan(1M)\f1 .\" index@disk array, scan \s-1LUN\s+1s for parity consistency@@@\f3pscan(1M)\f1 .\" index@parity consistency of \s-1HP SCSI\s+1 disk array \s-1LUN\s+1s@@@\f3pscan(1M)\f1 .\" .\" toc@\f3pscan(1M)\f1:\0\0\f4pscan\f1@@@scan \s-1HP SCSI\s+1 disk array \s-1LUN\s+1s for parity consistency .\" .\" fileset_database@pscan.1m SYS-ADMIN-MAN .\" $Header: pushAgent.1m,v 5.4 96/05/29 15:15:30 hmgr Exp $ .\" -*-Nroff-*- .\" $Header: pushAgent.1m,v 5.4 96/05/29 15:15:30 hmgr Exp $ .\" .ds RZ \&HP CONFIDENTIAL .\" .ds RL Release B.10.0x .\" .ds MT Software Distributor B.10.0x .\" The '@' hoses eroff, so use a display and don't .\" put the display inside of a font macro, e.g. .CR, .RI, etc. Instead split .\" the word containing the @ using the \c (continuation) and \0 (space) appropriately. .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .\" .ds PN Release B.10.0x .TA p .TH pushAgent 1M " " "Hewlett-Packard Company" .\" .ds )H Software Distributor .\" .ds ]W Release B.10.0x .SH NAME .PP pushAgent \- Install the Software Distributor agent on remote systems .SH SYNOPSIS .C /usr/sbin/pushAgent .RC [ -t .IR target_file|\| .RC -m .IR machine_name\| ] .RC [ -a .IR additional_diskspace\| ] .br .RC [ -x .IR prompt_rootname=[true|false\| ] .PP .SS Remarks: .B "This command applies only to the HP OpenView Software Distributor" .B "product (HP Prod. No. B1996AA). It is not part of the SD-UX command" .B "set shipped with the HP-UX operating system." .PP .SH DESCRIPTION .PP The .C pushAgent command provides the HP OpenView Software Distributor (SD) user with a way to install the SD agent onto remote systems for the first time or to replace SD-UX. The tool is especially useful when configuring a large number of remote systems as SD agents. .P The SD supports two separate configurations: .RS .TP 2 \(bu SD controller systems .TP 2 \(bu SD agent systems .RE .P SD controller systems are created by installing the full SD product from the installation media. SD agent systems are created by using .C pushAgent to install the SD agent on remote systems. Once the SD agent has been installed on a remote system using this tool, the remote system becomes a valid target for software distribution tasks. .P The .C pushAgent command has two different basic modes of operation: interactive and command line. Command line mode is entered when either .C -m or .C -t is specified on the command line. If neither of these options is specified, interactive mode is used. .P In interactive mode, the program will present a number of alternatives to the user via a terminal-based user interface. On-line help is available from within this tool. Use interactive mode when you only need to install the SD agent onto a few systems. When you select this method, you will be prompted for the name of the remote system. Once the system name has been entered, .C pushAgent will install and configure the SD agent on that remote system. While the installation progresses, the current status of the installation will be displayed. Finally, the success or failure of the installation is shown. If the installation failed, the tool will report why, and may suggest a way for the user to remedy the problem so that the installation can be re-tried later. .P In command line mode, all machines which need the SD agent are listed via the command line (on the command line itself with the .C -m option or in a batch file with the .C -t option). Install the SD agent via .C -m when you have to install the SD agent on just a few systems, but do not want to use the interactive mode. .P Install the SD agent from a batch file when you need to install the SD agent on many systems. When you select this method, you must provide an input file which contains a list of remote systems. The .C pushAgent command reads the file, and serially installs the SD agent on each system listed in the file. While the installation progresses, .C pushAgent displays the current status of the installation. When the installation process has completed to all of the remote systems listed in the input file, a summary screen is displayed which lists the names of the systems whose installation failed. .P An example input file for the batch installation method is displayed below: .P .RS 10 .PD 0 .C "# Accounting Department" .PP .C "hpbob # Bob's machine" .PP .C "hpfrank # Frank's machine" .sp .PP .C "# R+D Department" .PP .C "grpserver.co.here.com # Our server system" .PP .C "15.1.2.3 # IP address of their test machine" .PD .RE .P For both modes, verbose logging information is written to the log file .C /tmp/pushAgent.log (see the DIAGNOSTICS section below). .P For both modes, access to the remote machines is first attempted via .CR remsh(1) . If remsh access fails, .C rexec(1) access is attempted. If rexec access is not already set up for the remote machine, .C pushAgent prompts for the remote machine's root password. .PP If you are using .C pushAgent on an HP-UX 10.x system, you will be prompted for the name of a source depot which contains the SD commands. This depot will most likely be your SD media (on which the SD product was delivered). You will only be asked for the name of the source depot once per invocation of .CR pushAgent . .PP .C pushAgent expects SD for different architectures to be already loaded on the system. The location is .CR /tmp/sd . If you do not have enough space on your .CR /tmp file system, you can create a soft link to a file system with enough space. .PP If the SD product for the target system's architecture is not loaded on the target system, .C pushAgent prompts you for the source depot that contains SD. .C pushAgent then loads SD into .C /tmp/sd on the target system. .PP .C pushAgent does not remove .C /tmp/sd so that SD will be available on the system for subsequent pushes. If you need the disk space, you can remove .C /tmp/sd manually. .PP .SS Options .C pushAgent supports the following options: .RS .TP 15 .C -t Specifies a file containing a list of machines to install the SD agent on (a batch file). .TP .C -m Specifies a single machine to install the SD agent on. Multiple .C -m options are allowed on a single invocation of .C pushAgent. .TP .C -a Specifies how much additional disk space must be present on each of the target machines in the file system containing /usr. This is space above and beyond what SD itself will require. The number is specified in Kbytes. The default is 0. This option is useful when you have other software which will be installed after the SD agent, and you want to make sure both it and the SD agent will fit on your remote system. .TP .C -x prompt_rootname= This option is useful when your remote system's root user is something other than .C root. Valid option values are either .C true or .C false (default is .C false). If set to .C true, pushAgent will prompt for both the remote root name and the remote root password if access to the remote machine via remsh fails. If set to .C false, only the root password will be prompted for (the user .C root is assumed). .RE .SH EXTERNAL INFLUENCES .PP .SS Signals The .C pushAgent command catches the signals SIGHUP, SIGINT, SIGQUIT, and SIGTERM. If any of these signals are received, the .C pushAgent command confirms whether the user wishes to exit. Note that sending a signal to the .C pushAgent command while it is installing the SD agent on a remote system may leave that remote system in an inconsistent state, and is therefore not recommended. .SH SECURITY .PP When the installation of the SD agent on remote systems has completed, .C pushAgent performs some basic configuration of the security Access Control Lists (ACLs) on the remote system. Specifically, an entry is added to the remote system which will enable full software distribution access by the super-user on the system which is running the .C pushAgent program. This super-user will be able to perform software distribution tasks to the remote system without having to further configure its ACLs. .SH DIAGNOSTICS .PP The .C pushAgent tool supports three log files: .RS .TP 2 \(bu .C /tmp/pushAgent.log .TP 2 \(bu .C /tmp/pushAgent.old .TP 2 \(bu .C /tmp/pushAgent.older .RE .P Every time this command is started, a new log file .C /tmp/pushAgent.log is created. The .C pushAgent command records in this log file the names of the remote systems which had the SD agent installed on, the success or failure of that installation, together with a detailed message on the type of failure if the installation failed. In addition, log files for the two previous .C pushAgent sessions are maintained. The log information from these two sessions is saved in the files .C /tmp/pushAgent.old and .C /tmp/pushAgent.older. .\".SS WARNINGS .\".PP .\".SS DEPENDENCIES .\".PP .SH RETURN VALUES .PP The .C pushAgent command returns 1 if an invalid command line option is used or if a batch file is incorrect. The .C pushAgent command returns 2 if the user prematurely exits from the program. In all other circumstances, the .C pushAgent command returns 0. .SH LIMITATIONS .PP .\" .C SunOS .br .RS 4 .C pushAgent is not supported on SunOS. Refer to .IR "Using HP OpenView Software Distributor on Sun Platforms" for more information on how to distribute the SD agent to remote workstations running SunOS. .PP .C pushAgent is not supported for installing to PC controllers. .\" .SH AUTHOR .PP .C pushAgent was developed by the Hewlett-Packard Company. .PP .SH SEE ALSO .PP swacl(1M), swagent(1M), swconfig(1M), swcopy(1M), swinstall(1M), swjob(1M), swlist(1M), swmodify(1M), swpackage(1M), swreg(1M), swremove(1M), swverify(1M), swpackage(4), sd(4), sd(5), and the .IR "HP OpenView Software Distributor Administrator's Guide". .\" .\" toc@\f3pushAgent(1M)\f1:\0\0\f4pushAgent\f1@@@install Software Distributor agent on remote systems .\" .\" index@\f4pushAgent\f1 \- install Software Distributor agent on remote systems@@@\f3pushAgent(1M)\f1 .\" index@\f1install Software Distributor agent on remote systems@@@\f3pushAgent(1M)\f1 .\" index@\f1Software Distributor agent on remote systems@@@\f3pushAgent(1M)\f1 .\" .\" $Header: pvchange.1m,v 76.1 95/07/31 17:22:13 ssa Exp $ .TA p .TH pvchange 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pvchange \- change characteristics and access path of physical volume in LVM volume group .SH SYNOPSIS .CR /sbin/pvchange .RC [ \-A .IR autobackup ] .CR \-s .IR pv_path .PP .CR /sbin/pvchange .RC [ \-A .IR autobackup ] .CR \-S .IR autoswitch .IR pv_path .PP .CR /sbin/pvchange .RC [ \-A .IR autobackup ] .CR \-x .IR extensibility .IR pv_path .PP .CR /sbin/pvchange .RC [ \-A .IR autobackup ] .CR \-t .IR IO_timeout .IR pv_path .SS Remarks .CR pvchange cannot be performed if the the volume group is activated in shared mode. .SH DESCRIPTION The .CR pvchange command changes the characteristics and access path of a physical volume .RI ( pv_path ) in a volume group. .PP On dual controller devices, .CR pvchange sets the permission that controls whether or not the system will automatically switch from the current controller to the original controller after the original controller has recovered from a failure. It also permits you to switch manually to a controller on the device other than the current controller. .PP .CR pvchange sets the allocation permission to add physical extents to the physical volume. .SS Options and Arguments .CR pvchange recognizes the following options and arguments. .RS .TP 20 .I pv_path The block device path name of a physical volume. .TP .CI \-A \0autobackup Set automatic backup for this invocation of this command. .I autobackup can have one of the following values: .RS .RS .TP .CR y Automatically back up configuration changes made to the logical volume. This is the default. .IP After this command executes, the .CR vgcfgbackup command (see .IR vgcfgbackup (1M)) is executed for the volume group to which the logical volume belongs. .TP .CR n Do not back up configuration changes this time. .RE .RE .TP .CR \-s Manually switch access to the device to the path named by .IR pv_path , specifying it as the primary path. .TP .CI \-S \0autoswitch Set the autoswitch operation for the physical volume .IR pv_path . .I autoswitch can have one of the following values: .RS .RS .TP .CR y Automatically switch back to the original primary path after a recovery from a failure. This is the default. .TP .CR n Do not switch back. Stay on the current controller. .RE .RE .TP .CI \-x \0extensibility Set the allocation permission to add physical extents to the physical volume .IR pv_path . .IR extensibility can have the following values: .RS .RS .TP .CR y Allow allocation of additional physical extents on the physical volume. .TP .CR n Prohibit allocation of additional physical extents on the physical volume. However, logical volumes residing on the physical volume are accessible. .RE .RE .TP .CI \-t \0IO_timeout Set the .IR IO_timeout for the physical volume to the number of seconds indicated. An .IR IO_timeout value of zero (0) causes the system to use the default value supplied by the device driver associated with the physical device. The .IR IO_timeout is used by the device driver to determine how long to wait for disk transactions to complete before concluding that an IO request can not be completed (and the device is offline or unavailable). .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to .CR C (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to .CR C (see .IR environ (5)). .SH EXAMPLES Prohibit the allocation of additional physical extents to a physical volume: .IP .C "pvchange \-x n /dev/dsk/c0t0d0" .PP Allow the allocation of additional physical extents to a physical volume: .IP .C "pvchange \-x y /dev/dsk/c0t0d0" .PP Prohibit a switch back to the original primary controller after it has recovered from a failure: .IP .C "pvchange -S n /dev/dsk/c0t0d0" .PP Allow a switch back to the original primary controller after it has recovered from a failure: .IP .C "pvchange -S y /dev/dsk/c0t0d0" .PP Manually switch a physical volume to use another controller path: .IP .C "pvchange -s /dev/dsk/c2d0s2" .PP Set the .IR IO_timeout for a physical volume to 60 seconds: .IP .C "pvchange -t 60 /dev/dsk/c2d0s2" .PP Set the .IR IO_timeout for a physical volume to zero (0) to use the driver default: .IP .C "pvchange -t 0 /dev/dsk/c2d0s2" .SH SEE ALSO pvdisplay(1M). .\" .\" index@\f1LVM volume group, change characteristics and access path of physical volume in@@@\f3pvchange(1M)\f1 .\" index@\f1access path of physical volume in LVM volume group, change@@@\f3pvchange(1M)\f1 .\" index@\f1change characteristics of physical volume in LVM volume group@@@\f3pvchange(1M)\f1 .\" index@\f1characteristics of physical volume in LVM volume group, change@@@\f3pvchange(1M)\f1 .\" index@\f1physical volume in LVM volume group, change characteristics and access path@@@\f3pvchange(1M)\f1 .\" index@\f1volume group (LVM), change characteristics and access path of physical volume in@@@\f3pvchange(1M)\f1 .\" index@\f4pvchange\f1 \- change characteristics and access path of physical volume in LVM volume group@@@\f3pvchange(1M)\f1 .\" .\" toc@\f3pvchange(1M)\f1:\0\0\f4pvchange\f1@@@change characteristics and access path of physical volume in LVM volume group .\" $Header: pvcreate.1m,v 78.1 96/04/05 11:33:25 ssa Exp $ .TA p .TH pvcreate 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pvcreate \- create physical volume for use in LVM volume group .SH SYNOPSIS .CR /sbin/pvcreate .RC \|[ -b ]\| .RC \|[ -B ]\| .RC \|[ -d .IR soft_defects ]\| .RC \|[ -s .IR disk_size ]\| .RC \|[ -f ]\| .ifn .br .ifn \0\0\0\0 .RC \|[ -t .IR disk_type ]\| .IR \|pv_path .SH DESCRIPTION The .CR pvcreate command initializes a direct access storage device (a raw disk device) for use as a physical volume in a volume group. .PP If .IR pv_path contains a file system and the .CR -f option is not specified, .CR pvcreate asks for confirmation. The request for confirmation avoids accidentally deleting a file system. .PP The operation is denied if .IR pv_path belongs to another volume group. Only physical volumes not belonging to other volume groups can be created. .PP After using .CR pvcreate to create a physical volume, use .CR vgcreate to add it to a new volume group or .CR vgextend to add it to an existing volume group (see .IR vgcreate (1M) and .IR vgextend (1M)). .PP Disks cannot be added to a volume group until they are properly initialized by .CR pvcreate . .PP .IR pv_path can be made into a bootable disk by specifying the .CR -B option, which reserves space on the physical volume for boot-related data. This is a prerequisite for creating root volumes on logical volumes. Refer to .IR mkboot (1M) and .IR lif (4) for more information. .SS Options and Arguments .CR pvcreate recognizes the following options and arguments: .RS .TP 20 .IR pv_path The character (raw) device path name of a physical volume. .TP .CR -b Read from standard input the numbers that correspond to the indexes of all known bad blocks on the physical volume, .IR pv_path , that is being created. Specify the indexes using decimal, octal, or hexadecimal numbers in standard C-language notation, with numbers separated by newline, tab, or formfeed characters. If this option is not used, .CR pvcreate assumes that the physical volume contains no bad blocks. .TP .CR -B Make a bootable physical volume (i.e., a system disk). .TP .CI -d \0soft_defects Specify the minimum number of bad blocks that LVM should reserve in order to perform software bad block relocation. This number can be no larger than 7039. If not specified, one block is reserved for each 8K of data blocks. .IP This option is not supported on HP-IB devices; .IR soft_defects is set to 0 when .CR pvcreate is executed for an HP-IB device. .TP .CI -s \0disk_size Effective size of the physical volume to be created, specified in number of physical sectors. .TP .CR -f Force the creation of a physical volume (thus deleting any file system present) without first requesting confirmation. .TP .CI -t \0disk_type Retrieve configuration information about the physical volume from the file .CR /etc/disktab . .IR disk_type specifies the device (for example, hp7959S). .IP The .IR disk_type only needs to be specified when .CR pvcreate fails to get the size from the underlying disk driver. If the driver successfully returns the size of the device, .IR disk_type is ignored. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Create a physical volume on raw device .CR /dev/rdsk/c1t0d0 , and force the creation without confirmation: .IP .C "pvcreate -f /dev/rdsk/c1t0d0" .PP Create a physical volume on raw device .CR /dev/rdsk/c1t0d0 , specifying that a bad blocks list (7, 13, 95, and 133) must be read from standard input: .IP .C "echo 7 13 95 133 | pvcreate -b /dev/rdsk/c1t0d0" .SH FILES .TP 20 .CR /etc/disktab Disk geometry and disk partition characteristics for all disk devices on the system .SH WARNINGS Check the manufacturer's listing or run diagnostics testing for bad blocks on the device prior to creating a physical volume. If bad blocks are present, use the .CR -b option when creating the physical volume. .SH SEE ALSO mkboot(1M), vgcreate(1M), vgextend(1M), lif(4). .\" .\" toc@\f3pvcreate(1M)\f1:\0\0\f4pvcreate\f1@@@create physical volume for use in LVM volume group .\" .\" index@\f4pvcreate\f1 \- create physical volume for use in LVM volume group@@@\f3pvcreate(1M)\f1 .\" index@create physical volume for use in LVM volume group@@@\f3pvcreate(1M)\f1 .\" index@physical volume for use in LVM volume group, create@@@\f3pvcreate(1M)\f1 .\" index@LVM volume group, create physical volume for use in@@@\f3pvcreate(1M)\f1 .\" index@volume group (LVM), create physical volume for use in@@@\f3pvcreate(1M)\f1 .\" $Header: pvdisplay.1m,v 78.1 96/02/13 13:39:32 ssa Exp $ .TA p .TH pvdisplay 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pvdisplay \- display information about physical volumes within LVM volume group .SH SYNOPSIS .CR /sbin/pvdisplay .RC [ -v ] .RC [ -b .IR BlockList ] .IR pv_path \ ... .SH DESCRIPTION The .CR pvdisplay command displays information about each physical volume specified by a .I pv_path parameter. .SS Options .CR pvdisplay recognizes the following options: .RS .TP 10 .I pv_path The block device path name of a physical volume. .TP .CR -v For each physical volume, display the logical volumes that have extents allocated on the physical volume and the usage of all the physical extents. .TP .CI -b \0BlockList For each block in .IR BlockList display information about the block. .IR BlockList is a comma separated list of blocks in DEV_BSIZE units. .RE .SS Display Without \(miv Option If you omit the .CR -v option, .CR pvdisplay displays the characteristics of each physical volume specified by .IR pv_path : .TP .CR "--- Physical volumes ---" .RS .TP 20 .CR "PV Name" The block device path name of the physical volume .TP .CR "VG Name" The path name of the volume group .TP .CR "PV Status" State of the physical volume: .CR available or .CR unavailable .TP .CR Allocatable Allocation permission for the physical volume .TP .CR VGDA Number of volume group descriptors on the physical volume .TP .CR "Cur LV" Number of logical volumes using the physical volume .TP .CR "PE Size (Mbytes)" Size of physical extents on the volume, in megabytes (MB) .TP .CR "Total PE" Total number of physical extents on the physical volume .TP .CR "Free PE" Number of free physical extents on the physical volume .TP .CR "Allocated PE" Number of physical extents on the physical volume that are allocated to logical volumes .TP .CR "Stale PE" Number of physical extents on the physical volume that are not current .TP .CR "IO Timeout" The IO timeout used by the disk driver when accessing the physical volume. A value of .CR default, indicates that the driver default IO timeout is being used. .RE .SS Display With \(miv Option If the .CR -v is specified, .CR pvdisplay lists additional information for each logical volume and for each physical extent on the physical volume: .TP .CR "--- Distribution of physical volume ---" .IP The logical volumes that have extents allocated on .IR pv_path , displayed in column format: .RS .TP 20 .CR "LV Name" The block device path name of the logical volume which has extents allocated on .IR pv_path . .TP .CR "LE of LV" Number of logical extents within the logical volume that are contained on this physical volume .TP .CR "PE for LV" Number of physical extents within the logical volume that are contained on this physical volume .RE .TP .CR "--- Physical extents ---" .IP The following information for each physical extent, displayed in column format: .RS .TP 20 .CR PE Physical extent number .TP .CR Status Current state of the physical extent: .CR free , .CR used , or .CR stale .TP .CR LV The block device path name of the logical volume to which the extent is allocated .TP .CR LE Index of the logical extent to which the physical extent is allocated .RE .SS Display With \(mib Option If the .CR -b is specified, .CR pvdisplay lists additional information for each block specified in .IR BlockList . .TP .CR "--- Block Mapping ---" .IP The use of blocks on .IR pv_path , displayed in column format: .RS .TP 20 .CR "Block" The block number relative to the physical volume. .TP .CR "Status" The current status of the block: .CR free , .CR used , .CR structure , .CR spared , or .CR unknown .TP .CR "Offset" The offset of the block relative to the logical volume. .TP .CR "LV Name" The block device path name of the logical volume to which the block is allocated. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Display the status and characteristics of a physical volume: .IP .C "pvdisplay /dev/dsk/c1t0d0" .PP Display the status, characteristics, and allocation map of a physical volume: .IP .C "pvdisplay -v /dev/dsk/c2t0d0" .SH SEE ALSO lvdisplay(1M), pvchange(1M), vgdisplay(1M). .\" .\" toc@\f3pvdisplay(1M)\f1:\0\0\f4pvdisplay\f1@@@display information about physical volumes in LVM volume group .\" .\" index@\f4pvdisplay\f1 \- display information about physical volumes in LVM volume group@@@\f3pvdisplay(1M)\f1 .\" index@display information about physical volumes in LVM volume group@@@\f3pvdisplay(1M)\f1 .\" index@information about physical volumes in LVM volume group, display@@@\f3pvdisplay(1M)\f1 .\" index@physical volumes in LVM volume group, display information about@@@\f3pvdisplay(1M)\f1 .\" index@LVM volume group, display information about physical volumes in@@@\f3pvdisplay(1M)\f1 .\" index@volume group (LVM), display information about physical volumes in@@@\f3pvdisplay(1M)\f1 .\" $Header: pvmove.1m,v 76.1 95/07/31 17:22:34 ssa Exp $ .TA p .TH pvmove 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pvmove \- move allocated physical extents from one LVM physical volume to other physical volumes .SH SYNOPSIS .CR /sbin/pvmove .RC [ -A .IR autobackup ] .RC [ -n .IR lv_path ] .I source_pv_path .br \0\0\0\0 .RI [ dest_pv_path \ ...\& \(or .IR dest_pvg_name \ ...] .SS Remarks .CR pvmove cannot be performed if the volume group is activated in shared mode. .SH DESCRIPTION The .CR pvmove command moves allocated physical extents and the data they contain from a source physical volume, .IR source_pv_path , to one or more other physical volumes in the same volume group. .PP If a destination physical volume or physical volume group is not specified, all physical volumes in the volume group are available as destination volumes for the transfer. .CR pvmove selects the proper physical volumes to be used in order to preserve the allocation policies of the logical volume involved. .PP To limit the transfer to specific physical volumes, specify the name of each physical volume directly with a .I dest_pv_path argument. Optionally, if physical volume groups are defined for the volume group, specify the physical volumes indirectly with one or more .I dest_pvg_name arguments .PP .I source_pv_path must not appear as a .IR dest_pv_path . .PP If .I source_pv_path is a member of a .IR dest_pv_path , it is automatically excluded from being a destination physical volume. .PP .CR pvmove succeeds only if there is enough space on the destination physical volumes to hold all the allocated extents of the source physical volume. .SS Options .CR pvmove recognizes the following options: .RS .TP 20 .I dest_pv_path The block device path name of a physical volume. It cannot be the source physical volume. It must be in the same volume group as .IR source_pv_path . .TP .I dest_pvg_name The name of a physical volume group. It must be in the same volume group as .IR source_pv_path . .TP .I source_pv_path The block device path name of a physical volume. .TP .CI -A \0autobackup Set automatic backup for this invocation of this command. .I autobackup can have one of the following values: .RS .RS .TP .CR y Automatically back up configuration changes made to the physical volume. This is the default. .IP After this command executes, the .CR vgcfgbackup command (see .IR vgcfgbackup (1M)) is executed for the volume group to which the physical volume belongs. .TP .CR n Do not back up configuration changes this time. .RE .RE .TP .CI -n \ lv_path Move only the physical extents allocated to the logical volume specified by .IR lv_path that are located on the source physical volume specified by .IR source_pv_path . .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Move physical extents from .CR /dev/dsk/c1t0d0 to .CR /dev/dsk/c2t0d0 and .CR /dev/dsk/c3t0d0 : .IP .C "pvmove /dev/dsk/c1t0d0 /dev/dsk/c2t0d0 /dev/dsk/c3t0d0" .PP If only .CR /dev/dsk/c2t0d0 and .CR /dev/dsk/c3t0d0 belong to physical volume group .CR PVG0 , the same result can be achieved with the following command: .IP .C "pvmove /dev/dsk/c1t0d0 PVG0" .PP Move only the physical extents in logical volume .CR /dev/vg01/lvol2 that are on .CR /dev/dsk/c1t0d0 to .CR /dev/dsk/c2t0d0 : .IP .C "pvmove -n /dev/vg01/lvol2 /dev/dsk/c1t0d0 /dev/dsk/c2t0d0" .SH SEE ALSO pvdisplay(1M), vgcfgbackup(1M). .\" .\" toc@\f3pvmove(1M)\f1:\0\0\f4pvmove\f1@@@move physical extents from one LVM physical volume to other physical volumes .\" .\" index@\f4pvmove\f1 \- move allocated physical extents from one LVM physical volume to other physical volumes@@@\f3pvmove(1M)\f1 .\" index@\f1move allocated physical extents from one LVM physical volume to other physical volumes@@@\f3pvmove(1M)\f1 .\" index@\f1allocated physical extents, move from one LVM physical volume to other physical volumes@@@\f3pvmove(1M)\f1 .\" index@\f1physical extents, move from one LVM physical volume to other physical volumes@@@\f3pvmove(1M)\f1 .\" index@\f1LVM physical volume to other physical volumes, move allocated physical extents from@@@\f3pvmove(1M)\f1 .\" index@\f1physical volume (LVM) to other physical volumes, move allocated physical extents from@@@\f3pvmove(1M)\f1 .\" $Header: pwck.1m,v 72.4 94/11/14 15:23:23 ssa Exp $ .TA p .TH pwck 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pwck, grpck \- password/group file checkers .SH SYNOPSIS .C /usr/sbin/pwck .RI [ \|file\| ] .br .C /usr/sbin/grpck .RI [ \|file\| ] .SH DESCRIPTION .C pwck scans the default password file or .I file and reports any inconsistencies to standard error. The checks include validation of the number of fields, login name, user .SM ID, group .SM ID, and whether the login directory and optional program name exist. The criteria for determining a valid login name are described in the .I HP-UX System Administrator manuals for your system. The default password file is .CR /etc/passwd . .PP .C grpck verifies all entries in the group file and reports any inconsistencies to standard error. This verification includes a check of the number of fields, group name, group .SM ID, and whether all login names appear in the password file. The default group file is .CR /etc/group . .SH DIAGNOSTICS Group entries in .CR /etc/group with no login names are flagged. .SH AUTHOR .C pwck was developed by AT&T and HP. .SH DEPENDENCIES .SS \s-1NFS\s0: .C pwck and .C grpck check only the local password and group files. The Network Information Service database for password and group files is not checked. .SH FILES .C /etc/group .br .C /etc/passwd .SH SEE ALSO group(4), passwd(4). .SH STANDARDS CONFORMANCE .CR pwck ": SVID2, SVID3" .PP .CR grpck ": SVID2, SVID3" .\" .\" index@\f4pwck\f1 \- password file checker@@@\f3pwck(1M)\f1 .\" index@\f4grpck\f1 \- group file checker@@@\f3pwck(1M)\f1 .\" index@check password or group file@@@\f3pwck(1M)\f1 .\" index@password file, check@@@\f3pwck(1M)\f1 .\" index@group file, check@@@\f3pwck(1M)\f1 .\" .\" toc@\f3pwck(1M)\f1:\0\0\f4pwck\f1, \f4grpck\f1@@@password/group file checkers .\" toc@\f4grpck\f1:\0\0group file checker@@@see \f3pwck(1M)\f1 .\" .\" links@pwck.1m grpck.1m .\" .\" fileset_database@pwck.1m SYS-ADMIN-MAN .\" $Header: pwconv.1m,v 72.2 94/07/01 17:36:03 ssa Exp $ .TA p .TH pwconv 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pwconv \- install and update secured password facility .SH SYNOPSIS .C pwconv .SH DESCRIPTION The .CR pwconv command creates the directories and files needed for the secured password facility if it is not already installed. If the secured password facility is already installed, .CR pwconv updates the facility to reflect any changes made in the .CR /etc/passwd file. .SH FILES .C /etc/passwd .SH SEE ALSO tsconvert(1M). .\" .SH STANDARDS COMPLIANCE .\" .CR pwconv ": SVR4" .\" toc@\pwconv(1M)\f1:\0\0f4pwconv\f1@@@install and update secured password facility\f1 .\" index@\f4pwconv\f1 \- install and update secured password facility@@@\f3pwconv(1M)\f1 .\" index@\f1install and update secured password facility@@@\f3pwconv(1M)\f1 .\" index@\f1secured password facility, install and update@@@\f3pwconv(1M)\f1 ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright (c) 1987 Apollo Computer, Inc. ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" .rm zA .rm zZ .TH pwd_strengthd "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "enh,11658,R1.1,new manpage" .iX "-[" "Security Service commands" "\*Lpwd_strengthd\*O" .iX "-[" "accounts" "importing" .SH NAME \*Lpwd_strengthd\*O \- The sample Password Management Server .SH SYNOPSIS .sS \*Lpwd_strengthd\*O [\*L+/-all\*O[\*L_spaces\*O]] [\*L+/-alp\*O[\*Lha_num\*O]] .br [\*L-c\*O[\*Lache_size\*O]] \*Vsize\*O [\*L-d[\*Lebug\*O]] .br [\*L-m\*O[\*Lin_len\*O]] \*Vpwd_min_len\*O [\*L-t\*O[\*Limeout\*O]] \*Vminutes\*O .br [\*L-v\*O[\*Lerbose\*O]] .sE .SH "OPTIONS" .VL .LI "\*L+all_spaces\*O" Allow passwords to be all spaces. If this option is not set, the effective registry policy is used. .LI "\*L-all_spaces\*O" Disallow passwords to be all spaces. If this option is not set, the effective registry policy is used. .LI "\*L+alpha_num\*O" Allow passwords to consist only of alphanumeric characters. If this option is not set, the effective registry policy is used. .LI "\*L-alpha_num\*O" Disallow passwords to consist only of alphanumeric characters. If this option is not set, the effective registry policy is used. .LI "\*L-cache_size\*O \*Vsize\*O" Specify the number of hash buckets in the password cache. The password cache is used to store generated passwords which are retrieved when the password is strength checked. The password cache is a hash table with a linked list for collisions. The size should be set to a reasonable value based on how large the cache will be on average. The default value if not specified is 100. .LI "\*L-debug\*O" Run in the foreground. Log messages are written to standard output. .LI "\*L-min_len\*O \*Vpwd_min_len\*O" Specify the minimum length of a password. If this option is not set, the effective registry policy is used. .LI "\*L-timeout\*O \*Vminutes\*O" Specify the time, in minutes, that generated passwords remain in the cache before they are deleted from memory. If this option is not specified, the default time is 30 minutes. .LI "\*L-verbose\*O" Runs in verbose mode. More detailed messages are sent to the logfile \*L$DCELOCAL/var/security/pwd_strengthd.log\*O. (Use of this option is recommended.) .LE .SH DESCRIPTION DESCRIPTION .PP \*Lpwd_strengthd\*O is a sample Password Management Server. It exports the \*Lrsec_pwd_mgmt\*O application programming interface. .PP \*Lpwd_strengthd\*O generates passwords and strength-checks them. It enforces the security registry policy for password strength-checking. Administrators can override the security registry policy via the command-line options (\*Lalpha_num\*O, \*Lall_spaces\*O, \*Lmin_len\*O.) .PP Administrators can subject principals to password-strength and -generation policies by attaching the following ERAs: .VL 7m .LI "\*Lpwd_val_type\*O" Specifies the password management policy the user must conform to when selecting passwords. .LI "\*Lpwd_mgmt_binding\*O" Specifies information required in order to connect to the password management server. .LE .PP See the \*VOSF DCE Administrator's Guide -- Core Services\*O for more information and examples. .nS "NOTE" You may want to enhance \*Lpwd_strengthd\*O to support your site's policies for password strength and generation. .nE .iX "-]" "Security Service commands" "\*Lpwd_strengthd\*O" .iX "-]" "accounts" "importing" .zZ "enh,11658,R1.1,new manpage" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH quit 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "DTS control program" "exiting" .iX "\*Ldtscp\*O commands" "\*Lquit\*O" .SH NAME .PP \*Lquit\*O - Causes \*Ldtscp\*O to complete execution .SH "SYNOPSIS" .PP .zA "defect,6211,R1.0.3,add control program name" .sS \*Ldtscp quit\*O .sE .zZ "defect,6211,R1.0.3,add control program name" .SH "DESCRIPTION" .PP The \*Lquit\*O command causes \*Ldtscp\*O to complete execution and returns operation to the parent process. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command may be replaced in future releases by the \*Ldcecp\*O command, and may no longer be supported at that time. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .PP The following command shows how to leave \*Ldtscp\*O and return to the parent process: .iS \*Cdtscp>\*O \*Lquit\*O .iE .SH "RELATED INFORMATION" .PP Command: \*Lexit(1m)\*O .\" $Header: quot.1m,v 72.7 94/11/29 05:55:53 ssa Exp $ .TA q .TH quot 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME quot \- summarize file system ownership .SH SYNOPSIS .C /usr/sbin/quot .RC [ -F .IR FStype ] .RC [ -V ] .RC [ -cfhnv ] .ifn .br .ifn \0\0\0\0\0\0\0\0\0\0\0\0\0\0 .RC [ -o .IR FSspecific-options ] .IR filesystem \0... .br .C /usr/sbin/quot .RC [ -F .IR FStype ] .RC [ -V ] .RC [ -cfhnv ] .C -a .SH DESCRIPTION The .C quot command displays the number of 1024-byte blocks in the named .I filesystem that are currently owned by each user. .I filesystem is either the name of the directory on which the file system is mounted or the name of the device containing the file system. .SS Options .CR quot recognizes the following options: .RS .TP 15 .CI -F \0FStype Specify the file system type on which to operate (see .IR fstyp (1M) and .IR fs_wrapper (5)). If this option is not included on the command line, the file system type is determined from the file .CR /etc/fstab by matching .I filesystem with an entry in that file. If there is no entry in .CR /etc/fstab , then the file system type is determined from the file .CR /etc/default/fs . .TP .C -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .TP .CI -o \0FSspecific-options Specify any options specific to the file system. .TP .C -a Generate a report for all mounted file systems. .TP .C -c Report size rather than user statistics. Generates histogram statistics in 3-column format: .RS .RS .TP 12 Column 1: File size in blocks. Sizes are listed in ascending order up to 499 blocks per file. Files occupying 499 or more blocks are counted together on a single line as 499-block files (but column 3 is based on actual number of blocks occupied). .TP Column 2: Number of files of size indicated in column 1. .TP Column 3: Cumulative total blocks occupied by files counted in current plus all preceding lines. .RE .RE .IP Use of this option overrides the .C -f and .C -v options. .TP .C -f Display number of files and space occupied by each user. .TP .C -h Calculate the number of blocks in the file based on file size rather than actual blocks allocated. This option does not account for sparse files (files with holes in them). .TP .C -n Accept data from the .CR ncheck command (see .IR ncheck (1M)) as input. Run the pipeline: .RS .IP .CI "ncheck " device " | sort +0n | quot -n " filesystem .RE .IP to produce a list of all files and their owners. .TP .C -v Display three columns containing the number of blocks not accessed in the last 30, 60, and 90 days. .SH AUTHOR .CR quot was developed by the University of California, Berkeley, Sun Microsystems, Inc., and HP. .SH FILES .PD 0 .TP 25 .CR /etc/default/fs Specifies the default file system type .TP .C /etc/fstab Static information about the file systems .TP .C /etc/mnttab Mounted file system table .TP .C /etc/passwd Password file (contains user names) .PD .SH SEE ALSO .RI quot_ FStype (1M), du(1), find(1), ls(1), fstyp(1M), mount(1M), ncheck(1M), repquota(1M), fs_wrapper(5), quota(5). .\" .\" index@\f4quot\f1 \- summarize file system ownership@@@\f3quot(1M)\f1 .\" index@ownership, summarize file system@@@\f3quot(1M)\f1 .\" index@summarize file system ownership@@@\f3quot(1M)\f1 .\" .\" toc@\f3quot(1M)\f1:\0\0\f4quot\f1@@@summarize file system ownership .\" $Header: quot_hfs.1m,v 72.2 94/11/29 11:50:26 ssa Exp $ .TA q .TH quot_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME quot (hfs) \- summarize ownership on an HFS file system .SH SYNOPSIS .C /usr/sbin/quot .RC [ -F .CR hfs ] .RC [ -V ] .RC [ -cfhnv ] .IR filesystem \0... .br .C /usr/sbin/quot .RC [ -F .CR hfs ] .RC [ -V ] .RC [ -cfhnv ] .C -a .SH DESCRIPTION The .CR quot command displays the number of 1024-byte blocks in the named HFS .I filesystem that are currently owned by each user. .I filesystem is either the name of the directory on which the file system is mounted or the name of the device containing the file system. .SS Options .C quot recognizes the following options: .RS .TP 10 .CR "-F hfs" Specify the file system type .CR hfs . .TP .C -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab. This option allows the user to verify the command line. If the options specified are valid, the completed command line is echoed. If the options specified are not valid, an error message is printed. .TP .C -a Generate a report for all mounted HFS file systems. .TP .C -c Report size rather than user statistics. Generates histogram statistics in 3-column format: .RS .RS .TP 12 Column 1: File size in blocks. Sizes are listed in ascending order up to 499 blocks per file. Files occupying 499 or more blocks are counted together on a single line as 499-block files (but column 3 is based on actual number of blocks occupied). .TP Column 2: Number of files of size indicated in column 1. .TP Column 3: Cumulative total blocks occupied by files counted in current plus all preceding lines. .RE .RE .IP Use of this option overrides the .C -f and .C -v options. .TP .C -f Display number of files and space occupied by each user. .TP .C -h Calculate the number of blocks in the file based on file size rather than actual blocks allocated. This option does not account for sparse files (files with holes in them). .TP .C -n Accept data from the .CR ncheck command (see .IR ncheck (1M)) as input. Run the pipeline: .RS .IP .CI "ncheck " device " | sort +0n | quot -n " filesystem .RE .IP to produce a list of all files and their owners. .TP .C -v Display three columns containing the number of blocks not accessed in the last 30, 60, and 90 days. .SH AUTHOR .CR quot , a disk quota command, was developed by the University of California, Berkeley, Sun Microsystems, Inc., and HP. .SH FILES .TP 25 .CR /etc/fstab Static information about the file systems .PD 0 .TP .CR /etc/mnttab Mounted file system table .TP .CR /etc/passwd Password file (contains user names). .PD .SH SEE ALSO quot(1M), du(1), find(1), ls(1), fstyp(1M), mount(1M), ncheck(1M), repquota(1M), quota(5). .\" .\" index@\f4quot\f1 \- summarize file system ownership@@@\f3quot(1M)\f1 .\" index@ownership, summarize file system@@@\f3quot(1M)\f1 .\" index@summarize file system ownership@@@\f3quot(1M)\f1 .\" .\" toc@\f3quot(1M)\f1:\0\0\f4quot\f1@@@summarize file system ownership .\" $Header: quot_vxfs.1m,v 78.1 96/02/13 13:43:05 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA q .TH quot_vxfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME quot(vxfs) \- summarize ownership on a VxFS file system .SH SYNOPSIS .CR /usr/sbin/quot .RC [ "\-F vxfs" ] .RC [ \-V ] .RC [ \-cfhnv ] .I filesystem ... .br .C /usr/sbin/quot .RC [ "\-F vxfs" ] .RC [ \-V ] .RC [ \-cfhnv ] .C \-a .SH DESCRIPTION The .C quot command displays the number of 1024-byte blocks in the named VxFS .I filesystem that are currently owned by each user. .I filesystem is either the name of the directory on which the file system is mounted or the name of the device containing the file system. .SS Options .C quot recognizes the following options: .RS .TP 10 .C "\-F vxfs" Specifies file system type .C vxfs .TP .C \-V Validate the command line options, but perform no other action. If the options specified are valid, the complete command line is echoed. If the options specified are not valid, an error message is printed. .TP .C \-a Generate a report for all mounted file systems. .TP .C \-c Report size rather than user statistics. Generates histogram statistics in 3-column format: .RS .RS .TP 12 Column 1: File size in blocks. Sizes are listed in ascending order up to 499 blocks per file. Files occupying 499 or more blocks are counted together on a single line as 499-block files (but column 3 is based on actual number of blocks occupied). .TP Column 2: Number of files of size indicated in column 1. .TP Column 3: Cumulative total blocks occupied by files counted in current plus all preceding lines. .RE .RE .IP Use of this option overrides the .C \-f and .C \-v options. .TP .C \-f Display number of files and space occupied by each user. .TP .C \-h Calculate the number of blocks in the file based on file size rather than actual blocks allocated. This option does not account for sparse files (files with holes in them). .TP .C \-n Accept .IR ncheck (1M) data as input. Run the pipeline .RS .IP .CI "ncheck " device " | sort +0n | quot \-n " filesystem .RE .IP to produce a list of all files and their owners. .TP .C \-v Display three columns containing the number of blocks not accessed in the last 30, 60, and 90 days. .SH AUTHOR Disk Quotas were developed by the University of California, Berkeley, Sun Microsystems, Inc., and HP. .SH FILES .PD 0 .TP 25 .C /etc/mnttab Mounted file system table .PD 0 .TP .C /etc/passwd Password file (contains user names). .PD .SH SEE ALSO quot(1M), du(1), find(1), fstyp(1M), ls(1), mount(1M), ncheck(1M), repquota(1M), quota(5). .\" .\" index@\f(CWquot_vxfs\f1 \- summarize file system ownership@@@\f3quot_vxfs(1M)\f1 .\" index@ownership, summarize file system@@@\f3quot_vxfs(1M)\f1 .\" index@summarize file system ownership@@@\f3quot_vxfs(1M)\f1 .\" .\" toc@\f3quot_vxfs(1M)\f1:\0\0\f(CWquot_vxfs\f1@@@summarize file system ownership .\" $Header: quotacheck.1m,v 76.1 95/07/10 17:09:44 ssa Exp $ .TA q .TH quotacheck 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME quotacheck (generic) \- file system quota consistency checker .SH SYNOPSIS .C /usr/sbin/quotacheck .RC [ -F .IR FStype ] .RC [ -V ] .ifn .br .ifn \0\0\0\0 .RC [ -o .IR specific-options ] .IR filesystem \0... .br .C /usr/sbin/quotacheck .RC [ -F .IR FStype ] .RC [ -V ] .ifn .br .ifn \0\0\0\0 .RC [ -o .IR specific-options ] .CR -a .SH DESCRIPTION The .CR quotacheck command examines each file system, builds a table of current disk usage, and compares this table against that stored in the disk quota file for the file system. If any inconsistencies are detected, both the quota file and the current system copy of the incorrect quotas are updated. .PP .CR quotacheck expects each file system to be checked to have a file named .CR quotas in the root directory. If none is present, .CR quotacheck reports an error and ignores the file system. .CR quotacheck is normally run at mount time from start-up scripts. .PP .I filesystem represents a mount point or block special device such as .CR /dev/dsk/c1d0s2 . .SS Options .CR quotacheck recognizes the following options: .RS .TP 15 .CI -F " Fstype" Specify the file system type on which to operate (see .IR fstyp (1M) and .IR fs_wrapper (5)). If this option is not included on the command line, then the file system type is determined from the file .CR /etc/fstab by matching .I filesystem with an entry in that file. If there is no entry in .CR /etc/fstab , then the file system type is determined from the file .CR /etc/default/fs . .TP 15 .CR -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .TP 15 .CI -o " specific-options" Specify options specific to each file system type. .I specific-options is a list of suboptions and/or keyword/attribute pairs intended for a .IR FStype -specific module of the command. See the file system specific man pages for a description of the .I specific-options supported, if any. .TP 15 .CR -a Obtain list of file systems to check from .CR /etc/fstab . Only mounted .CR rw (or .CR default ) type file systems with the .CR quota option are checked. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C quotacheck behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH AUTHOR .CR quotacheck was developed by HP and the University of California, Berkeley. .SH FILES .TP 25 .CR /etc/default/fs Specifies the default file system type .PD 0 .TP 25 .CR /etc/fstab Default list of file systems to check .PD 0 .TP 25 .CR /etc/mnttab Mounted file system table .PD 0 .TP 25 .IC directory /quotas Quota statistics static storage for file system where .I directory is the file system root as specified to the .CR mount command (see .IR mount (1M)). .PD .SH SEE ALSO fs_wrapper(5), mount(1M), quota(5), .RI quotacheck_ FSType (1M). .\" .\" index@\f4quotacheck\f1 \- generic file system quota consistency checker@@@\f3quotacheck(1M)\f1 .\" index@\f1generic file system quota consistency checker@@@\f3quotacheck(1M)\f1 .\" index@\f1file system quota consistency checker, generic@@@\f3quotacheck(1M)\f1 .\" index@\f1quota consistency checker, generic file system@@@\f3quotacheck(1M)\f1 .\" index@\f1consistency checker, generic file system quota@@@\f3quotacheck(1M)\f1 .\" index@\f1checker, generic file system quota consistency@@@\f3quotacheck(1M)\f1 .\" index@\f1verifier, generic file system quota consistency@@@\f3quotacheck(1M)\f1 .\" .\" toc@\f3quotacheck(1M)\f1:\0\0\f4quotacheck\f1@@@generic file system quota consistency checker .\" $Header: quotacheck_hfs.1m,v 72.4 94/11/29 05:57:44 ssa Exp $ .TA q .TH quotacheck_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME quotacheck (hfs) \- quota consistency checker for HFS file systems .SH SYNOPSIS .C /usr/sbin/quotacheck .RC [ -F .CR hfs ] .RC [ -V ] .RC [ -pPv ] .IR filesystem \0... .br .C /usr/sbin/quotacheck .RC [ -F .CR hfs ] .RC [ -V ] .RC [ -pPv ] .CR -a .SH DESCRIPTION The .CR quotacheck command examines each HFS file system, builds a table of current disk usage, and compares this table against that stored in the disk quota file for the file system. If any inconsistencies are detected, both the quota file and the current system copy of the incorrect quotas are updated. .PP .CR quotacheck expects each file system to be checked to have a file named .CR quotas in the root directory. If none is present, .CR quotacheck reports an error and ignores the file system. .CR quotacheck is normally run at mount time from start up scripts. .PP .I filesystem represents a mount point or block special device (e.g., .CR /dev/dsk/c1d0s2 ). .SS Options .CR quotacheck recognizes the following options: .RS .TP 15 .CR "-F hfs" Specify the file system type .CR hfs . .TP 15 .CR -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab. This option allows the user to verify the command line. .TP 15 .CR -a Obtain list of file systems to check from .CR /etc/fstab . Only mounted file systems of type .CR hfs and .CR rw (or .CR default ) with the .CR quota option are checked. .TP 15 .CR -v Indicate the calculated disk quotas for each user on a particular file system. .CR quotacheck normally reports only those quotas that are modified. .TP 15 .CR -p Check file systems in parallel as allowed by equal values in the .I pass number field in .CR /etc/fstab . .TP 15 .CR -P Preen file systems, checking only those with invalid quota statistics .RC ( quotaoff and .CR edquota commands can invalidate quota statistics as discussed in .IR quota (5) \(em see .IR quotaoff (1M) and .IR edquota (1M)). Also checks in parallel as in .CR -p above. .RE .SH AUTHOR .CR quotacheck was developed by HP and the University of California, Berkeley. .SH FILES .TP 20 .CR /etc/fstab Static information about the file systems .PD 0 .TP .CR /etc/mnttab Mounted file system table .TP .IC directory /quotas Quota statistics static storage for filesystem where .I directory is the file system root as specified to the .CR mount command (see .IR mount (1M)). .PD .SH SEE ALSO mount(1M), quota(5), quotacheck(1M), quotaon(1M), quotaoff(1M). .\" .\" index@\f4quotacheck_nfs\f1 \- hfs file system quota consistency checker@@@\f3quotacheck_nfs(1M)\f1 .\" index@hfs file system quota consistency checker@@@\f3quotacheck_nfs(1M)\f1 .\" index@quota consistency checker, hfs file system@@@\f3quotacheck_nfs(1M)\f1 .\" index@consistency checker, hfs file system quota@@@\f3quotacheck_nfs(1M)\f1 .\" index@checker, hfs file system quota consistency@@@\f3quotacheck_nfs(1M)\f1 .\" index@verifier, hfs file system quota consistency@@@\f3quotacheck_nfs(1M)\f1 .\" .\" toc@\f3quotacheck_nfs(1M)\f1:\0\0\f4quotacheck_nfs\f1@@@hfs file system quota consistency checker .\" $Header: quotacheck_vxfs.1m,v 78.1 96/02/13 13:43:24 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" (c) Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA q .TH quotacheck_vxfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME quotacheck \- VxFS file system quota consistency checker .SH SYNOPSIS .CR /usr/sbin/quotacheck .RC [ \-F .CR vxfs ] .RC [ \-V ] .RC [ \-pPv ] .I filesystem... .br .C /usr/sbin/quotacheck .RC [ \-F .CR vxfs ] .RC [ \-V ] .RC [ \-pPv ] .RC \-a .SH DESCRIPTION Since VxFS maintains quota information in the kernel, .CR quotacheck for VxFS syncs quotas from the current system copy to the disk quota file for the VxFS file system. .PP .CR quotacheck expects each file system to be checked to have a file named .CR quotas in the root directory. .CR quotacheck is normally run at mount time from start-up scripts. .PP .I filesystem represents a mount point or block special device (e.g., .CR /dev/dsk/c0t0d0) . .SS Options .CR quotacheck recognizes the following options: .RS .TP 15 .CR \-F " vxfs" Specify the file-system type .CR vxfs . .TP 15 .CR \-V Echo the completed command line, but perform no other actions. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .TP 15 .CR \-a Obtain list of file systems to check from .CR /etc/fstab . Only mounted .CR rw type file systems with the .CR quota option are checked. .TP 15 .CR \-v Reports the file system name before syncing quotas from current system copy to the disk quota file. .TP 15 .CR \-p This option does nothing, but exists for standards compatibility. .TP 15 .CR \-P This option does nothing, but exists for standards compatibility. .SH AUTHOR .CR quotacheck was developed by HP and the University of California, Berkeley. .SH FILES .TP 20 .CR /etc/fstab default file systems .PD 0 .TP 20 .IC directory /quotas quota statistics static storage for filesystem where .I directory is the file system root as specified to .CR mount (see .IR mount (1M)). .PD .SH SEE ALSO quota(5), quotacheck(1M), quotacheck_hfs(1M). .\" .\" index@\f(CWquotacheck_vxfs\f1 \- VxFS file system quota consistency checker@@@\f3quotacheck_vxfs(1M)\f1 .\" index@VxFS file system quota consistency checker@@@\f3quotacheck_vxfs(1M)\f1 .\" index@file system quota consistency checker, VxFS@@@\f3quotacheck_vxfs(1M)\f1 .\" index@quota consistency checker, VxFS file system@@@\f3quotacheck_vxfs(1M)\f1 .\" index@consistency checker, VxFS file system quota@@@\f3quotacheck_vxfs(1M)\f1 .\" index@checker, VxFS file system quota consistency@@@\f3quotacheck_vxfs(1M)\f1 .\" index@verifier, VxFS file system quota consistency@@@\f3quotacheck_vxfs(1M)\f1 .\" .\" toc@\f3quotacheck_vxfs(1M)\f1:\0\0\f(CWquotacheck_vxfs\f1@@@VxFS file system quota consistency checker .\" $Header: quotaon.1m,v 76.1 95/07/10 17:10:08 ssa Exp $ .TA q .TH quotaon 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME quotaon, quotaoff \- turn HFS file system quotas on and off .SH SYNOPSIS .CR /usr/sbin/quotaon .RC [ -v ] .IR filesystem \0... .PP .CR /usr/sbin/quotaon .RC [ -v ] .CR -a .PP .CR /usr/sbin/quotaoff .RC [ -v ] .IR filesystem \0... .PP .CR /usr/sbin/quotaoff .RC [ -v ] .CR -a .SS Remarks These commands are provided for compatibility only. Their use is neither required nor recommended because .CR mount and .CR umount enable and disable quotas cleanly (see .IR mount (1M)). See WARNINGS below for more information. .SH DESCRIPTION The .CR quotaon command enables quotas on one or more HFS file systems. .PP The .CR quotaoff command disables quotas on one or more HFS file systems. .PP .IR filesystem is either the name of the mount point of the file system, or the name of the block device containing the file system. The file systems specified must be currently mounted in order to turn quotas on or off. Also, the file system quota file, .CR quotas , must be present in the root directory of each specified file system. .PP These commands will update the appropriate entries in .CR /etc/mnttab to indicate that quotas are on or off for each file system. .PP When enabling quotas interactively after boot time, the .CR quotacheck command should be immediately afterward (see WARNINGS below). .PP Use .CR mount (see .IR mount (1M)) to determine whether quotas are enabled on mounted file systems. .SS Options The following options affect the behavior described above. .RS .TP .CR -a Obtain the .IR filesystem list from .CR /etc/fstab , using entries of type .CR hfs and .CR rw (or .CR default ) with the .CR quota option (see .IR fstab (4)). .TP .CR -v Generate a message for each file system affected. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C quotaon behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS Using .CR quotaoff to disable quotas on a file system causes the system to discontinue tracking quotas for that file system, and marks the .CR "quota clean" flag in the superblock .CR NOT_OK (see .IR fsclean (1M)). This in turn, forces a .CR quotacheck the next time the system is booted. Since quotas are enabled and disabled cleanly by .CR mount and .CR umount anyway, the use of .CR quotaon and .CR quotaoff is generally discouraged. .SH AUTHOR Disk quotas were developed by the University of California, Berkeley, Sun Microsystems, Inc., and HP. .SH FILES .TP 25 .PD 0 .CR /etc/fstab Static information about the file systems .TP .CR /etc/mnttab Mount file system table .TP .IC directory /quotas Quota statistics storage for the file system, where .IR directory is the root of the file system as specified to the .CR mount command (see .IR mount (1M)). .PD .SH SEE ALSO fsclean(1M), quotacheck(1M), quotacheck_hfs(1M), mount(1M), quota(5). .\" .\" index@\f4quotaon\f1 \- turn file system quotas on@@@\f3quotaon(1M)\f1 .\" index@\f4quotaoff\f1 \- turn file system quotas off@@@\f3quotaon(1M)\f1 .\" index@\f1file system quotas, turn on and off@@@\f3quotaon(1M)\f1 .\" index@\f1quotas, file system, turn on and off@@@\f3quotaon(1M)\f1 .\" .\" toc@\f3quotaon(1M)\f1:\0\0\f4quotaoff\f1, \f4quotaon\f1@@@turn file system quotas on and off\f1 .\" toc@\f4quotaoff\f1:\0\0turn file system quotas off@@@see \f3quotaon(1M)\f1 .\" .\" links@quotaon.1m quotaoff.1m .\" $Header: quotaon.1m,v 76.1 95/07/10 17:10:08 ssa Exp $ .TA q .TH quotaon 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME quotaon, quotaoff \- turn HFS file system quotas on and off .SH SYNOPSIS .CR /usr/sbin/quotaon .RC [ -v ] .IR filesystem \0... .PP .CR /usr/sbin/quotaon .RC [ -v ] .CR -a .PP .CR /usr/sbin/quotaoff .RC [ -v ] .IR filesystem \0... .PP .CR /usr/sbin/quotaoff .RC [ -v ] .CR -a .SS Remarks These commands are provided for compatibility only. Their use is neither required nor recommended because .CR mount and .CR umount enable and disable quotas cleanly (see .IR mount (1M)). See WARNINGS below for more information. .SH DESCRIPTION The .CR quotaon command enables quotas on one or more HFS file systems. .PP The .CR quotaoff command disables quotas on one or more HFS file systems. .PP .IR filesystem is either the name of the mount point of the file system, or the name of the block device containing the file system. The file systems specified must be currently mounted in order to turn quotas on or off. Also, the file system quota file, .CR quotas , must be present in the root directory of each specified file system. .PP These commands will update the appropriate entries in .CR /etc/mnttab to indicate that quotas are on or off for each file system. .PP When enabling quotas interactively after boot time, the .CR quotacheck command should be immediately afterward (see WARNINGS below). .PP Use .CR mount (see .IR mount (1M)) to determine whether quotas are enabled on mounted file systems. .SS Options The following options affect the behavior described above. .RS .TP .CR -a Obtain the .IR filesystem list from .CR /etc/fstab , using entries of type .CR hfs and .CR rw (or .CR default ) with the .CR quota option (see .IR fstab (4)). .TP .CR -v Generate a message for each file system affected. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C quotaon behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS Using .CR quotaoff to disable quotas on a file system causes the system to discontinue tracking quotas for that file system, and marks the .CR "quota clean" flag in the superblock .CR NOT_OK (see .IR fsclean (1M)). This in turn, forces a .CR quotacheck the next time the system is booted. Since quotas are enabled and disabled cleanly by .CR mount and .CR umount anyway, the use of .CR quotaon and .CR quotaoff is generally discouraged. .SH AUTHOR Disk quotas were developed by the University of California, Berkeley, Sun Microsystems, Inc., and HP. .SH FILES .TP 25 .PD 0 .CR /etc/fstab Static information about the file systems .TP .CR /etc/mnttab Mount file system table .TP .IC directory /quotas Quota statistics storage for the file system, where .IR directory is the root of the file system as specified to the .CR mount command (see .IR mount (1M)). .PD .SH SEE ALSO fsclean(1M), quotacheck(1M), quotacheck_hfs(1M), mount(1M), quota(5). .\" .\" index@\f4quotaon\f1 \- turn file system quotas on@@@\f3quotaon(1M)\f1 .\" index@\f4quotaoff\f1 \- turn file system quotas off@@@\f3quotaon(1M)\f1 .\" index@\f1file system quotas, turn on and off@@@\f3quotaon(1M)\f1 .\" index@\f1quotas, file system, turn on and off@@@\f3quotaon(1M)\f1 .\" .\" toc@\f3quotaon(1M)\f1:\0\0\f4quotaoff\f1, \f4quotaon\f1@@@turn file system quotas on and off\f1 .\" toc@\f4quotaoff\f1:\0\0turn file system quotas off@@@see \f3quotaon(1M)\f1 .\" .\" links@quotaon.1m quotaoff.1m .\" $Header: rarpc.1m,v 78.2 96/01/04 13:29:29 ssa Exp $ .TA r .TH rarpc 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rarpc - Reverse Address Resolution Protocol client .SH SYNOPSIS .C rarpc .RC [ -d ] .RC [ -e | -s ] .RC [ -n .IR count ] .IR interface_name .SH DESCRIPTION .PP .CR rarpc , the Reverse Address Resolution Protocol client, implements the client portion of the Reverse Address Resolution Protocol [1]. It sends RARP requests for the specified interface's hardware address and waits for the response from the RARP server. Rarpc can be used during boot-time initialization to find the IP address of an interface. To do so, set the .CR IP_ADDRESS [\c .IR i ] variable of interface .IR i with .CR IP_ADDRESS[0]=RARP in .CR /etc/rc.config.d/netconf . .PP Options are: .RS .TP 12 .C -d Print debugging information. .TP .C -e Use ethernet encapsulation only. .TP .C -s Use SNAP encapsulation only. .TP .CI -n \0count Transmits count requests and waits for each one to time out before giving up. .TP .I interface_name Identifies the interface to request information about. .PP .RE If a response is received, it prints the IP address to its standard output. This information can be used to configure the interface as seen in .CR /sbin/init.d/net . .PP If a response is not received, the client will retransmit after 2 seconds, and then after 4 seconds. After that, retransmissions occur every 8 seconds. .RE .SH RETURN VALUE Exit status is 1 if the command fails or no RARP response is received. Exit status is 0 and the IP address is printed to standard output if a response is received. .SH LIMITATIONS .TP 3 1) The rarpc client cannot be run at the same time a rarpd daemon is running on the same interface. .TP 2) The rarpc client supports only ethernet, 100VG and FDDI network interfaces. .SH AUTHOR .CR rarpc was developed by HP. .SH SEE ALSO rarpd(1M), .PP R. Finlayson, T. Mann, J.C. Mogul, M. Theimer, "Reverse Address Resolution Protocol", RFC 903. .\" .\" index@\f4rarpc\f1 \- Reverse Address Resolution Protocol client@@@\f3rarpc(1M)\f1 .\" index@\f1Reverse Address Resolution Protocol client@@@\f3rarpc(1M)\f1 .\" .\" toc@\f3rarpc(1M)\f1:\0\0\f4rarpc\f1@@@Reverse Address Resolution Protocol client .\" $Header: rarpd.1m,v 78.2 96/01/04 13:31:48 ssa Exp $ .TA r .TH rarpd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rarpd - Reverse Address Resolution Protocol daemon .SH SYNOPSIS .CR rarpd .RC [ -d ] .RC [ -f .IR config_file ] .RI [ interface_name ] .SH DESCRIPTION .PP rarpd, the Reverse Address Resolution Protocol daemon, implements the server portion of the Reverse Address Resolution Protocol [1]. It responds to RARP requests providing the requested client IP address. Rarpd can be started during boot-time initialization. To do so, set the RARPD variable with .CR RARPD=1 in .CR /etc/rc.config.d/netconf . .PP Options are: .RS .TP 15 .C -d Print debugging information. .TP .CI -f \0config_file Use the specified config_file database instead of .CR /etc/rarpd.conf . .TP .I interface_name Respond to requests over just this interface. .PP .RE The configuration file database contains hardware address to IP address mappings. Other than comment lines (which begin with a '#') and blank lines, all lines are considered client entries. A client entry is of the form: .PP .RS .nf .IR hardware_address \0WHITE_SPACE \0ip_address .fi .RE .PP where .IR hardware_address consists of (\c .CR : ) colon-separated hexadecimal bytes, and .IR ip_address consists of (\c .CR . ) dot-seperated decimal bytes. For example: .PP .RS .nf # # hardware addr IP addr # # ethernet clients 08:00:09:26:ec:19 15.13.136.68 08:00:09:17:0a:93 15.13.136.74 # # 100VG clients 08:00:09:63:5d:f5 190.20.30.103 # # FDDI clients 08:00:09:09:53:4c 192.20.30.98 .fi .RE .PP There must be exactly 6 hardware address bytes. There must be exactly 4 protocol address bytes. .PP The following signals have the specified effect when sent to the rarpd process using the .IR kill (1) command: .RS .TP 10 SIGHUP Causes server to read the config file and reload database. .TP SIGINT Dumps current data base and cache to .CR /var/tmp/rarpd.db . .RE .RE .SH RETURN VALUE Exit status is 1 if the command fails, and error messages are written to stderr and/or syslog. Typically, the daemon will continue answering requests until externally interrupted. .SH LIMITATIONS .TP 3 1) The rarpd daemon supports only ethernet, 100VG and FDDI network interfaces. .TP 2) The rarpd daemon supports only 4 byte Internet Protocol addresses. .TP 3) The rarpd and rarpc programs cannot be run on the same interface at the same time. .SH AUTHOR .CR rarpd was developed by HP. .SH SEE ALSO rarpc(1M), .PP [1] R. Finlayson, T. Mann, J.C. Mogul, M. Theimer, "Reverse Address Resolution Protocol", RFC 903. .\" .\" index@\f4rarpd\f1 \- Reverse Address Resolution Protocol daemon@@@\f3rarpd(1M)\f1 .\" index@\f1Reverse Address Resolution Protocol daemon@@@\f3rarpd(1M)\f1 .\" .\" toc@\f3rarpd(1M)\f1:\0\0\f4rarpd\f1@@@Reverse Address Resolution Protocol daemon .\" $Header: rbootd.1m,v 74.1 95/05/10 21:55:57 ssa Exp $ .TA r .TH rbootd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rbootd \- remote boot server for RMP clients .SH SYNOPSIS .C /usr/sbin/rbootd .RC [ -a ] .RC [ -l .IR loglevel\| ] .RC [ -L .IR logfile\| ] .RC [ -t .IR minutes\| ] .RI [ \|landevs\| ] .SH DESCRIPTION .CR rbootd services initial boot-up requests from RMP clients over a local area network. Early s700 workstations and all Datacommunications and Terminal Controllers (DTC/9000) use this RMP protocol and can only communicate with .CR rbootd during boot-up. Later s700 workstations (starting with the s712) use the industry standard BOOTP protocol and communicate with .IR bootpd (1M). Future s700 workstations will use the BOOTP protocol. See the listings below. .PP .CR rbootd now acts as a forwarding agent for s700 RMP clients, receiving their RMP boot requests and reformulating them into BOOTP boot requests that are sent to the local .CR bootpd daemon. If .CR bootpd replies to this boot request, .CR rbootd receives the BOOTP reply and produces an RMP reply which is sent to the client. .CR rbootd continues to act as the intermediary in this transaction until the client is successfully booted. .PP .CR rbootd only responds to DTC clients if they are listed in the .CR map802 file. The .CR map802 file (a binary file) is created when a DTC is configured by .IR dtcconfig (1M) on the host machine. .PP In order to boot a s700 RMP client run .CR rbootd and .CR bootpd on the server machine, on the same subnet as the client. If the local .CR bootpd daemon is acting as a relay agent, there must also be a remote NFS Diskless server with the necessary boot files and NFS or .CR tftp access to those files. .PP .SS Options .CR rbootd supports the following options: .RS .TP 14 .C -a Append to the .CR rbootd log file. By default, starting up .CR rbootd truncates the log file. .TP .CI \-l " loglevel" Set the amount of information that will be logged in the log file. .CR rbootd supports the following logging levels: .RS .RS .TP 5 .PD 0 .C 0 Log only .CR rbootd startup and termination messages. .TP .C 1 Log all errors. This is the default logging level. .TP .C 2 Log rejected boot requests from machines not found in .CR /etc/bootptab or .CR /usr/dtcmgr/map802 . .TP .C 3 Log all boot requests. .RE .RE .PD .TP .CI \-L " logfile" Specify an alternate file that .CR rbootd should use to log status and error messages. .TP .CI \-t " minutes" Grace period before removing inactive temporary files. Meaningful only in the .CR tftp\c -remote configuration. Default is 10 minutes. .TP .I landevs Specify the .IR only devices that .CR rbootd should use to listen for boot requests. The default is all LAN devices. The device names must be of the form .CR /dev/lan* .RE .SS New Functionality .PP Beginning with HP-UX 10.0 .CR rbootd has the following behavior: .PP .TP 3 \(bu .C bootpd/bootptab Dependency: .IP .CR rbootd now relies on .IR bootpd (1M) to verify the identity of cluster clients and locate the bootable images (from .CR /etc/bootptab ). RMP clients are thus administered in exactly the same way as new BOOTP clients. The old methods for administering RMP clients (\c .CR /etc/clusterconf , context-dependent files, .CR /usr/boot/* ) are obsolete and no longer work. .IP See .IR bootpd (1M) and .IR sam (1M) for details on configuring cluster clients. .IP It is necessary to have the .CR bootpd daemon running on the same machine as the .CR rbootd daemon. .TP \(bu .CR Auto-Discovery: .IP To aid the system administrator, .CR rbootd now discovers working ethernet interfaces at startup time and monitors them for boot requests. Alternatively, the system administrator may put a list of up to ten ethernet devices on the command line. Putting device names on the command line means "monitor these devices ONLY". If device names are included on the command line, they must be ethernet interfaces (not X.25, token-ring, etc) and they must be up and running at the time .CR rbootd is started. See .IR lanscan (1M) and .IR ifconfig (1M) to determine the state of system devices. Attempting to have .CR rbootd monitor non-ethernet devices will not succeed. The device names must always be of the form .CR /dev/lan* . .TP \(bu .C Multiple LAN Coverage: .IP .CR rbootd can monitor up to 10 lan devices (depending on hardware) and can boot clients from all of them. Clients are still restricted to booting from their own builtin lan devices. .TP \(bu .C Gateway Booting: .IP RMP clients can now be booted from servers that are not on the same subnet as the client. The RMP boot requests and replies cannot cross gateways, but the repackaged BOOTP requests and replies can. The BOOTP requests and replies are relayed across gateways by .CR bootpd . This is known as the remote configuration. .IP .CR rbootd uses the NFS or .CR tftp mechanism to transfer the necessary files from the remote server to the .CR rbootd machine, and then transfers the bootable images to the client in a succession of RMP packets. Thus the remote server must make the necessary files accessible by NFS or .CR tftp . .IP In the remote-\c .CR tftp case, the boot files are temporarily stored in .CR /var/rbootd/C0809* , and are removed after a period of inactivity, controlled by the .CR -t option. The default is 10 minutes. .TP \(bu .C S800 Servers: .IP S800 machines can now be used as cluster servers, booting s700 clients and DTCs. S800 machines are not supported as cluster clients. .TP \(bu C Network Install: .IP .CR rbootd now forwards install requests to .IR instl_bootd (1M). If there is no appropriate response, .CR rbootd will deny the request. .TP \(bu .C S300/400 Not Supported: .IP S300/400 machines are not supported in clusters. .TP \(bu .C Performance Recommendations: .IP Boot from a local server for the fastest boot times. Run the .CR rbootd daemon and the .CR bootpd server daemon on the same machine, and avoid transferring the boot files by NFS or .CR tftp . This is strongly recommended. .IP If booting from remote .CR bootpd servers (across gateways), use NFS mounts to make the boot files available to the .CR rbootd server. See .IR mount (1M) for more information. The system administrator can configure local and remote diskless clients in any mix, but it is strongly recommended that the number of remote diskless clients be minimized. .IP If booting from remote servers using the .CR tftp method, there must also be temporary file space available on the .CR rbootd server machine. Generally 6-8 MBytes per diskless client must be available under .CR /var , but this number could be larger when booting customized kernels. These temporary files are removed automatically after some period of inactivity, controlled by the .CR -t option. The default is 10 minutes. .TP \(bu .C RMP/BOOTP: .IP The RMP clients are the older s700 workstations and all DTCs: workstations: 705, 710, 715, 720, 725, 730, 735, 750, 755 .IP The BOOTP clients are the s712 and future workstations. .PP .SH WARNINGS It is necessary to stop .CR rbootd before running .CR bootpquery because they use the same reserved port (67/udp). .PP .SH AUTHOR .CR rbootd was developed by HP. .PP .SH FILES .PD 0 .TP 33 .C /var/adm/rbootd.log Default rbootd log file. .TP .C /etc/boottab Bootstrap configuration file. .TP .C /etc/opt/dtcmgr/map802 DTC/9000 configuration file. .TP .C /opt/dtcmgr/map802 DTC/9000 configuration file. .TP .C /var/rbootd/C0809* Temporary boot files. .PD .SS Obsoleted Files .C /etc/clusterconf .br .C /usr/boot/* .PP .SH SEE ALSO bootpd(1M), instl_bootd(1M), tftpd(1M), mount(1M), sam(1M), dcnodes(1), dtcconfig(1M), dtcnmd(1M), dtcnmp(1M). .\" .\" index@\f4rbootd\f1 \- remote (diskless) boot server@@@\f3rbootd(1M)\f1 .\" index@remote (diskless) boot server@@@\f3rbootd(1M)\f1 .\" index@diskless (remote) boot server@@@\f3rbootd(1M)\f1 .\" index@boot server, remote (diskless)@@@\f3rbootd(1M)\f1 .\" .\" toc@\f3rbootd(1M)\f1:\0\0\f4rbootd\f1@@@remote boot server .\" .\" fileset_database@rbootd.1m SYS-ADMIN-MAN .\" $Header: rc.1m,v 72.3 94/11/02 01:25:38 ssa Exp $ .TA r .TH rc 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rc \- general purpose sequencer invoked upon entering new run level .SH SYNOPSIS .C /sbin/rc .SH DESCRIPTION The .CR rc shell script is the general sequencer invoked upon entering a new run level via the .CI "init " N command (where .I N equals 0\-6). The script .CR /sbin/rc is typically invoked by the corresponding entry in the file .CR /etc/inittab as follows: .IP .C "sqnc:123456:wait:/sbin/rc /dev/console 2>&1" .PP .CR /sbin/rc is the startup and shutdown sequencer script. There is only one sequencer script and it handles all of the sequencer directories. This script sequences the scripts in the appropriate sequencer directories in alphabetical order as defined by the shell and invokes them as either startup or kill scripts. .PP If a transition from a lower to a higher run level (i.e., .I init state) occurs, the start scripts for the new run level and all intermediate levels between the old and new level are executed. If a transition from a higher to a lower run level occurs, the kill scripts for the new run level and all intermediate levels between the old and new level are executed. .PP If a start script link (e.g., .CI /sbin/rc N .d/S123test\f1) in sequencer .I N has a stop action, the corresponding kill script should be placed in sequencer .IC N -1 (e.g., .CI /sbin/rc N -1.d/K200test\f1). Actions started in level .I N should be stopped in level .IC N -1\f1. This way, a system shutdown (e.g., transition from level 3 directly to level 0) will result in all subsystems being stopped. .SS Start and Kill Scripts In many cases, a startup script will have both a start and a kill action. For example, the .I inetd script starts the Internet daemon in the start case, and kills that process in the stop case. Instead of two separate scripts, only one exists, which accepts both the .CR start and .CR stop arguments and executes the correct code. In some cases, only a start action will be applicable. If this is the case, and if the .CR stop action is specified, the script should produce a usage message and exit with an error. In general, scripts should look at their arguments and produce error messages if bad arguments are present. When a script executes properly, it must exit with a return value of zero. If an error condition exists, the return value must be nonzero. .SS Naming Conventions The startup and shutdown scripts (referred to as startup scripts hereafter) exist in the .CR /sbin/init.d directory, named after the subsystem they control. For example, the .CR /sbin/init.d/cron script controls starting up the .CR cron daemon. The contents of sequencer directories consist of symbolic links to startup scripts in .CR /sbin/init.d . These symbolic links must follow a strict naming convention, as noted in the various fields of this example: .IP .C /sbin/rc2.d/S060cron .PP where the fields are defined as follows: .RS .TP 15 .C rc2.d The sequencer directory is numbered to reflect the run level for which its contents will be executed. In this case, start scripts in this directory will be executed upon entering run level 2 from run level 1, and kill scripts will be executed upon entering run level 2 from run level 3. .TP .C S The first character of a sequencer link name determines whether the script is executed as a start script (if the character is .CR S ), or as a kill script (if the character is .CR K ). .TP .C 060 A three digit number is used for sequencing scripts within the sequencer directory. Scripts are executed by type (start or kill) in alphabetical order as defined by the shell. Although it is not recommended, two scripts may share the same sequence number. .TP .C cron The name of the startup script follows the sequence number. The startup script name must be the same name as the script to which this sequencer entry is linked. In this example, the link points to .CR /sbin/init.d/cron . .IP Note that short file name systems require file names of 14 or less characters. This means that the fourth field is limited to 10 or fewer characters. .IP Scripts are executed in alphabetical order. The entire file name of the script is used for alphabetical ordering purposes. .IP When ordering start and kill script links, note that subsystems started in any given order should be stopped in the reverse order to eliminate any dependencies between subsystems. This means that kill scripts will generally not have the same numbers as their start script counterparts. For example, if two subsystems must be started in a given order due to dependencies (e.g., .CR S111house followed by .CR S222uses_house ), the kill counterparts to these scripts must be numbered so that the subsystems are stopped in the opposite order in which they were started (e.g., .CR K555uses_house followed by .CR K777house ). .IP Also keep in mind that kill scripts for a start script in directory .CI /sbin/rc N .d will reside in .CI /sbin/rc( N -1).d\f1. For example, .CR /sbin/rc3.d/S123homer and .CR /sbin/rc2.d/K654homer might be start/kill counterparts. .RE .SS Arguments The startup/shutdown scripts should be able to recognize the following four arguments (where applicable): .RS .TP 15 .C start The .CR start argument is passed to scripts whose names start with .CR S . Upon receiving the .CR start argument, the script should perform its start actions. .TP .C stop The .CR stop argument is passed to scripts whose names start with .CR K . Upon receiving the .CR stop argument, the script should perform its stop actions. .TP .C start_msg The .CR start_msg argument is passed to scripts whose names start with .CR S so that the script can report back a short message indicating what the start action will do. For instance, when the .CR lp spooler script is invoked with a .CR start_msg argument, it echoes .RS .IP .C Starting the LP subsystem .RE .IP This string is used by the startup routines. Scripts given just the .CR start_msg argument will only print a message and not perform any actions. .TP .C stop_msg The .CR stop_msg argument is passed to scripts whose names start with .CR K so that the script can report back a short message indicating what the stop action will do. For instance, when the .CR lp spooler script is invoked with a .CR stop_msg argument, it echoes .RS .IP .C Stopping the LP subsystem .RE .IP This string is used by the shutdown checklist. Scripts given just the .CR stop_msg argument will only print a message and not perform any actions. .RE .SS Script Output To ensure proper reporting of startup events, startup scripts are required to comply with the following guidelines for script output. .RS .TP 3 \(bu Status messages, such as .RS .IP .C starting house daemon .RE .IP must be directed to stdout. All error messages must be directed to stderr. .TP \(bu Script output, both stdout and stderr, is redirected to log file .CR /etc/rc.log , unless the startup checklist mode is set to the raw mode. In this case, all output goes to the console. All error messages should be echoed to stdout or stderr. .TP \(bu Startup scripts are not allowed to send messages directly to the console, or to start any daemons that immediately write to the console. This restriction exists because these scripts are now started by the .CR /sbin/rc checklist wrapper. All script output should go to either stdout or stderr, and thus be captured in a log file. Any console output will be garbled. .SH RETURN VALUE The return values for startup scripts are as follows: .RS .TP 5 .C 0 Script exited without error. .PD 0 .TP .C 1 Script encountered errors. .TP .C 2 Script was skipped due to overriding control variables from .CR /etc/rc.config.d files, or for other reasons, and did not actually do anything. .PD .RE .SH SEE ALSO init(1M), shutdown(1M), inittab(4), rc.config(4). .\" .\" index@\f4rc\f1 \- general purpose sequencer invoked upon entering new run level@@@\f3rc(1M)\f1 .\" index@\f4rc\f1sequencer, invoked upon entering new run level@@@\f3rc(1M)\f1 .\" toc@\f3rc(1M)\f1:\0\0\f4rc\f1@@@general purpose sequencer invoked upon entering new run level\f1 .\" $Header: rcancel.1m,v 72.4 94/09/12 13:35:27 ssa Exp $ .TA r .TH rcancel 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rcancel \- remove requests from a remote line printer spooling queue .SH SYNOPSIS .C /usr/sbin/rcancel .RI [ id \0...\|] .RI [ printer ] .RC [ -a ] .RC [ -e ] .RC [ -u .IR user ] .SH DESCRIPTION The .CR rcancel command removes a request, or requests, from the spool queue of a remote printer. .CR rcancel is invoked by the .CR cancel command (see .IR cancel (1)). .PP At least one .I id or the name of a .I printer must be specified. .PP This command is intended to be used only by the spool system in response to the .CR cancel command (see .IR lp (1)), and should not be invoked directly. .SS Options The .CR rcancel command recognizes the following options: .RS .TP 12 .I id Specifying a request ID (as returned by .CR lp (see .IR lp (1)) cancels the associated request (if the request is owned by the user), even if it is currently printing. .TP .I printer Name of the printer (for a complete list, use .CR lpstat (see .IR lpstat (1)). Specifying a .I printer cancels the request which is currently printing on that printer, if the request is owned by the user. If the .CR -a , .CR -e , or the .CR -u option is specified, this option only specifies the printer on which to perform the cancel operation. .TP .C -a Remove all requests owned by the user on the specified printer (see .IR printer ). The owner is determined by the user's login name and host name on the machine where the .CR lp command was invoked. .TP .C -e Empty the spool queue of all requests for the specified .IR printer . This form of invoking .CR rcancel is useful only to users with appropriate privileges. .TP .CI -u \0user Remove any requests queued belonging to that user (or users). This form of invoking .CR rcancel is available only to users with appropriate privileges. .RE .SH AUTHOR .CR rcancel was developed by the University of California, Berkeley, and HP. .SH FILES .nf .C /var/spool/lp/* .C /var/adm/lp/* .C /etc/lp/* .C /usr/lib/lp/* .fi .SH SEE ALSO enable(1), lp(1), lpstat(1), accept(1M), lpadmin(1M), lpsched(1M), rlp(1M), rlpdaemon(1M), rlpstat(1M). .\" .\" index@\f4rcancel\f1 \- remove requests from line printer spooling queue on remote system@@@\f3rcancel(1M)\f1 .\" index@\f1cancel LP requests from spooling queue on remote system@@@\f3rcancel(1M)\f1 .\" index@\f1remote systems, cancel LP spooling requests sent to@@@\f3rcancel(1M)\f1 .\" index@\f1LP requests, cancel from spooling queue on remote system@@@\f3rcancel(1M)\f1 .\" .\" toc@\f3rcancel(1M)\f1:\0\0\f4rcancel\f1@@@remove requests from a remote line printer spooling queue\f1 .\" $Header: rdpd.1m,v 76.1 95/05/26 17:03:19 ssa Exp $ .TA r .TH rdpd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rdpd - router discovery protocol daemon .SH SYNOPSIS .C rdpd [-r|t|v] .SH DESCRIPTION .PP rdpd, the router discover protocol daemon, implements the host portion of the router discovery protocol [1]. More specifically it: .PP Solicits router advertisements when it is first started so as to populate the kernel table as soon as possible. .PP Listens on all ethernet interfaces (that are up) for ICMP router advertisement datagrams. .PP Adds a default router to the kernel table based on whether the router is a neighbor and has the highest preference among all advertisements received. .PP Ages the default router entry applied to the kernel table based on the lifetime value found in the advertisement message. .PP rdpd can be started during boot-time initialization. To do so, see .C /etc/rc.config.d/netconf . .SS Options .C rdpd supports the following options: .RS .TP 5 .C -r Display the version of rdpd. .TP .CI -t Enable tracing of the following events: .RS .RS .TP 3 - setting of expiration timer for advertised entry. .PD 0 .TP - expiration of a router advertisement entry (only the active entry has a timer running). .TP - add/update of an advertised router to the kernel. .TP - removal from kernel table of an advertised router. .TP - reception of a router advertisement from the link. .TP - transmission of a router solicitation message. .TP - failure while attempting to transmit a solicitation. .RE .RE .PD .TP .C -v Enable verbose tracing, in addition to the above, trace: .RS .RS .TP 3 - contents of the router advertisement message received. .PD 0 .TP - contents of rdpd internal statics which includes: .RS .TP 4 1) total number of icmp messages received, .TP 2) total number advertisements received, .TP 3) total number of advertisements with invalid number of addresses field, .TP 4) total number of advertisements with invalid address size field, .TP 5) total number of advertisements with invalid message lengths, .TP 6) total number of advertisements with invalid lifetime fields, .TP 7) total number of icmp message with number of bytes received <> header length field. .PD .RE .RE .RE .SH LIMITATIONS .TP 3 1) The maximum number of default routes retained is 10. Only one of which is applied to the kernel routing tables (the one with the highest preference). In the event that the advertised router with the highest preference expires the retained advertised router list will be searched for the highest preference, still current entry and that entry will be applied to the kernel table. This allows for quick recovery from aged advertisements. .TP 2) rdpd only becomes aware of link state changes when either a new Router Advertisement message is received or a timer pops to age a currently active default router added by rdpd. This may cause a delay between an interface state change (e.g., ifconfig down) and any necessary change to the kernel routing table. .TP 3) The "all hosts on subnet" broadcast address is used for sending solicitations instead of either the all-routers multicast or limited-broadcast IP addresses. .TP 4) The limited-broadcast address for inbound Advertisements is assumed. .TP 5) Default routers added via the route command can be altered due to Router Advertisements for the same router. .TP 6) Adding default routes via the route command can cause unpredictable results and should be avoided. .SH REFERENCES .TP [1] Deering, S., "ICMP Router Discovery Messages", RFC 1256 .SH AUTHOR rdpd was developed by HP. .\" .\" index@\f2rdpd\f1 \- router discovery protocol daemon@@@\f3rdpd(1)\f1 .\" .\" toc@\f3rdpd(1m)\f1:\0\0\f2rdpd\f1@@@router discovery protocol daemon .\" .\" fileset_database@rdpd.1m NETWORK-MAN .\" $Header: dump.1m,v 78.1 96/01/22 22:20:48 ssa Exp $ .TA d .TH dump 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dump, rdump \- incremental file system dump, local or across network .SH SYNOPSIS .C /usr/sbin/dump .RI [ \|option \ [ \|argument \ ...] .IR filesystem ] .PP .C /usr/sbin/rdump .RI [ \|option \ [ \|argument \ ...] .IR filesystem ] .SH DESCRIPTION The .CR dump and .CR rdump commands copy to magnetic tape all files in the .I filesystem that have been changed after a certain date. This information is derived from the files .CR /var/adm/dumpdates and .CR /etc/fstab . .I option specifies the date and other options about the dump. .I option consists of characters from the set .CR 0123456789bdfnsuWw . The .CR dump and .CR rdump commands work only on file systems of type .CR hfs . If the given file system is not of type .CR hfs , .CR dump and .CR rdump will abort after printing an error message. .SS Options .RS .TP 10 .CR 0 - 9 This number is the "dump level". All files modified since the last date stored in file .CR /var/adm/dumpdates for the same file system at lesser levels will be dumped. If no date is determined by the level, the beginning of time is assumed. Thus, the option .CR 0 causes the entire file system to be dumped. .TP .C b The blocking factor is taken from the next argument (default is 10 if not specified). Block size is defined as the logical record size times the blocking factor. .CR dump writes logical records of 1024 bytes. When dumping to tapes with densities of 6250 BPI or greater without using the .CR b option, the default blocking factor is 32. .TP .C d The density of the tape (expressed in BPIs) is taken from the next .IR argument . This is used in calculating the amount of tape used per reel. The default value of 1600 assumes a reel tape. .TP .C f Place the dump on the next .I argument file instead of the tape. If the name of the file is .CR - , .CR dump writes to the standard output. When using .CR rdump , this option should be specified, and the next argument supplied should be of the form .IC machine : device\f1. .TP .C n Whenever .CR dump and .CR rdump require operator attention, notify all users in group .CR operator by means similar to that described by .IR wall (1). .TP .C s The size of the dump tape is specified in feet. The number of feet is taken from the next .IR argument . When the specified size is reached, .CR dump and .CR rdump wait for reels to be changed. The default tape size value of 2300 feet assumes a reel tape. .TP .C u If the dump completes successfully, write on file .CR /var/adm/dumpdates the date when the dump started. This file records a separate date for each file system and each dump level. The format of .CR /var/adm/dumpdates is user-readable and consists of one free-format record per line: file system name, increment level, and dump date in .IR ctime (3C) format. The file .CR /var/adm/dumpdates can be edited to change any of the fields if necessary. .TP .C W For each file system in .CR /var/adm/dumpdates , print the most recent dump date and level, indicating which file systems should be dumped. If the .CR W option is set, all other options are ignored and .CR dump exits immediately. .TP .C w Operates like .CR W , but prints only file systems that need to be dumped. .RE .PP If no arguments are given, .I option is assumed to be .C 9u and a default file system is dumped to the default tape. .PP Sizes are based on 1600-BPI blocked tape; the raw magnetic tape device must be used to approach these densities. Up to 32 read errors on the file system are ignored. Each reel requires a new process; thus parent processes for reels already written remain until the entire tape is written. .PP The .CR rdump command creates a server, .CR /usr/sbin/rmt or .CR /etc/rmt , on the remote machine to access the tape device. .ift .bp .PP .CR dump and .CR rdump require operator intervention for any of the following conditions: .RS .TP 3 \(bu end of tape, .PD 0 .TP \(bu end of dump, .TP \(bu tape-write error, .TP \(bu tape-open error, or .TP \(bu disk-read error (if errors exceed threshold of 32). .RE .PD .PP In addition to alerting all operators implied by the .CR n option, .CR dump and .CR rdump interact with the control terminal operator by posing questions requiring .CR yes or .CR no answers when it can no longer proceed or if something is grossly wrong. .PP Since making a full dump involves considerable time and effort, .CR dump and .CR rdump each establish a checkpoint at the start of each tape volume. If, for any reason, writing that volume fails, .CR dump and .CR rdump will, with operator permission, restart from the checkpoint after the old tape has been rewound and removed and a new tape has been mounted. .PP .CR dump and .CR rdump periodically report information to the operator, including typically low estimates of the number of blocks to write, the number of tapes it will require, the time needed for completion, and the time remaining until tape change. The output is verbose to inform other users that the terminal controlling .CR dump and .CR rdump is busy and will be for some time. .SS Access Control Lists (ACLs) The optional entries of a file's access control list (ACL) are not backed up with .CR dump and .CR rdump . Instead, the file's permission bits are backed up and any information contained in its optional ACL entries is lost (see .IR acl (5)). .SH EXAMPLES In the following example, assume that the file system .CR /mnt is to be attached to the file tree at the root directory, .RC ( / ). This example causes the entire file system .RC ( /mnt ) to be dumped on .\" .CR /dev/rmt/0h .CR /dev/rmt/c0t0d0BEST and specifies that the density of the tape is 6250 BPI. .IP .\" .C /usr/sbin/dump 0df 6250 /dev/rmt/0h /mnt .C /usr/sbin/dump 0df 6250 /dev/rmt/c0t0d0BEST /mnt .\" .SH DIAGNOSTICS .\" Many, and verbose. .SH WARNINGS .CR dump will not backup a file system containing large files. .PP Tapes created from file systems containing files with UID/GIDs greater than 60,000 will have a new magic number in the header to prevent older versions of .IR restore (1M) from incorrectly restoring ownerships for these files. .SH AUTHOR .CR dump and .CR rdump were developed by the University of California, Berkeley. .SH FILES .PD 0 .TP 32 .C /dev/rdsk/c0d0s0 Default file system to dump from. .TP .C /dev/rmt/0m Default tape unit to dump to. .TP .C /var/adm/dumpdates New format-dump-date record. .TP .C /etc/fstab Dump table: file systems and frequency. .TP .C /etc/group Used to find group .CR operator . .PD .SH SEE ALSO restore(1M), rmt(1M), fstab(4), acl(5). .\" .\" index@\f4dump\f1 \- incremental file system dump (for backups)@@@\f3dump(1M)\f1 .\" index@\f4rdump\f1 \- incremental file system dump (for backups)@@@\f3dump(1M)\f1 .\" index@\f1incremental file system dump (for backups)@@@\f3dump(1M)\f1 .\" index@\f1backup, incremental file system dump@@@\f3dump(1M)\f1 .\" index@\f1backup, incremental file system dump over network@@@\f3dump(1M)\f1 .\" index@\f1remote incremental file system dump (for backups)@@@\f3dump(1M)\f1 .\" index@\f1remote backup over network@@@\f3dump(1M)\f1 .\" index@\f1network, remote backup over@@@\f3dump(1M)\f1 .\" index@\f1file system, incremental dump (for backups)@@@\f3dump(1M)\f1 .\" .\" toc@\f3dump(1M)\f1:\0\0\f4dump\f1, \f4rdump\f1@@@incremental file system dump\f1 .\" toc@\f4rdump\f1:\0\0incremental file system dump across network@@@\f1see \f3dump(1M)\f1 .\" .\" links@dump.1m rdump.1m .\" $Header: reboot.1m,v 72.7 94/07/28 10:31:51 ssa Exp $ .TA r .TH reboot 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME reboot \- reboot the system .SH SYNOPSIS .C /usr/sbin/reboot .RC [ -h \(or -r ] .RC [ -n \(or -s ] .RC [ -q ] .RC [ -t .IR time ] .RC [ -m .IR message ] .SH DESCRIPTION The .CR reboot command terminates all currently executing processes except those essential to the system, then halts or reboots the system. When invoked without arguments, .CR reboot syncs all disks before rebooting the system. .SS Options The .CR reboot command recognizes the following options: .RS .TP 15 .CI -h Shut down the system and halt. .TP .CI -r Shut down the system and reboot automatically (default). .TP .C -n Do not sync the file systems before shutdown. .TP .C -s Sync the file systems before shutdown; for file systems that were cleanly mounted, modify the .CR fs_clean flag from .CR FS_OK to .CR FS_CLEAN (default). .TP .C -q Quick and quiet. Suppress broadcast of warning messages, terminate processes by brute force (with .CR SIGKILL ) and immediately call .CR reboot with arguments as indicated by the other options (see .IR reboot (2)). No logging is performed. The .CR -t and .CR -m options are ignored with this option. .TP .CI -t " time" Specify what time .CR reboot will bring the system down. .I time can be the word .CR now (indicating immediate shutdown) or a future time in one of two formats: .CI + number and .IC hour : min\f1. The first form brings the system down in .I number minutes; the second brings the system down at the time of day indicated (based on a 24-hour clock). .TP .CI -m " message" Display .I message at the terminals of all users on the system at decreasing intervals as reboot .I time approaches. The .I message must not contain any embedded double quotes. options cannot be used together. .RE .ifn .bp .PP At shutdown time a message is written in the file .IP .C /etc/shutdownlog .PP (if it exists), containing the time of shutdown, who ran .CR reboot , and the reason. .PP Only users with appropriate privileges can execute the .CR shutdown command. .SH AUTHOR .CR reboot was developed by HP and the University of California, Berkeley. .SH FILES .PD 0 .TP 30 .C /etc/shutdownlog Shutdown log .PD .SH SEE ALSO reboot(2). .\" .\" index@\f4reboot\f1 \- reboot the system@@@\f3reboot(1M)\f1 .\" index@\f1shut down and reboot the system@@@\f3reboot(1M)\f1 .\" index@\f1halt then reboot the system@@@\f3reboot(1M)\f1 .\" index@\f1stop then reboot the system@@@\f3reboot(1M)\f1 .\" .\" toc@\f3reboot(1M)\f1:\0\0\f4reboot\f1@@@reboot the system\f1 .\" $Header: reconcile.1m,v 74.2 95/03/02 14:55:21 ssa Exp $ .TA r .TH reconcile 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME reconcile \- configure, modify, or unconfigure cluster-wide resources .SH SYNOPSIS .C /usr/sam/bin/reconcile .SH DESCRIPTION .C reconcile enables NFS Diskless cluster clients to configure, modify or unconfigure cluster-wide resources, such as printers or file systems. Normally such tasks are accomplished during a .SM SAM session through the use of cluster-wide tasks, tasks that are executed on every cluster member. However, if a diskless client is inaccessible (down or not communicating with the .SM LAN\c ) when the cluster-wide task is executed during the .SM SAM session, the task is deferred for later execution. .PP .C reconcile executes deferred tasks. It is invoked automatically during client boot by the .SM SAM single point administration startup script. It can also be invoked explicitly on the client system to update the client's cluster-wide resources without rebooting. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG specifies the language used to display messages. .PP If .C LANG is not specified or is set to the empty string, a default of .C C (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .C reconcile behaves as if all internationalization variables are set to .CR C . See .IR environ (5). .\" ======================================================================= .SH RETURN VALUE .C reconcile returns the following values: .RS .TP 8 .C \0\00 Successful completion. All deferred tasks completed successfully. .TP .C \0\01 Successful completion. All deferred tasks completed successfully, but some completed with exceptions or conditions. .TP .C 255 A task or command failure occurred. A task failure results when at least one deferred task failed during execution or was prevented from executing. A command failure generally prevents all tasks from executing and can be caused, for example, by missing or corrupt configuration files. .SH DIAGNOSTICS .C reconcile issues a summary of deferred tasks' results on standard output, and logs all messages received on standard output and standard error in the .SM SAM log file. If .C reconcile fails (returns a value of 255), the summary is mailed to the root user of the cluster server. .SH EXAMPLES Update the local client's cluster-wide resources: .IP .C /usr/sam/bin/reconcile .\" ======================================================================= .SH WARNINGS .C reconcile cannot be used to update cluster-wide resources on the cluster server because tasks are never deferred for the server. .PP The cluster resource database directory must be mounted from the server or results will be undefined. .SH AUTHOR .C reconcile was developed by .SM HP. .SH FILES .TP 35 .C /etc/sam/domain/spa/* Cluster resource database .PD 0 .TP .C /var/sam/log/samlog .SM SAM log file .PD .\" .\" toc@\f3reconcile(1M)\f1:\0\0\f4reconcile\f1@@@configure, modify, or unconfigure cluster-wide resources .\" .\" index@\f4reconcile\f1 \- configure, modify, or unconfigure cluster-wide resources@@@\f3reconcile(1M)\f1 .\" index@\f4reconcile\f1 \- modify cluster-wide resources@@@\f3reconcile(1M)\f1 .\" index@\f4reconcile\f1 \- unconfigure cluster-wide resources@@@\f3reconcile(1M)\f1 .\" index@\f4reconcile\f1 \- cluster-wide resources@@@\f3reconcile(1M)\f1 .\" index@\f1configure, modify, or unconfigure cluster-wide resources@@@\f3reconcile(1M)\f1 .\" index@\f1modify, or unconfigure cluster-wide resources@@@\f3reconcile(1M)\f1 .\" index@\f1unconfigure cluster-wide resources@@@\f3reconcile(1M)\f1 .\" index@\f1cluster-wide resources, configure, modify, or unconfigure@@@\f3reconcile(1M)\f1 .\" .\" $Header: recserv.man.src,v 1.2 94/03/28 09:35:09 jerrie Exp $ .TH recserv 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.0 July 1994 .SH NAME recserv \- HP SharedX Receiver Service .SH SYNOPSIS .B /usr/lbin/recserv .SH DESCRIPTION .I HP SharedX Receiver Service provides a method for a receiver to allow the sharing of windows without explicitly performing any xhost commands. The Internet daemon .RI ( inetd (1M)) executes .B recserv when it receives a service request at the port listed in the services data base for .B recserv (see .IR inetd (1m) and .IR services (4)). .PP When .B recserv is executed via inetd, a dialog box appears informing the receiver of the share request by the sender. The receiver can allow or disallow the share request by selecting the YES or NO button. .PP .B recserv allows sharing by xhosting the sender just long enough for it to make a connection to the receiver. Once the connection is established .B recserv removes the sender from the access control list, unless the sender was entered in the list prior to the execution of .B recserv. Since no permanent change is made to the access control list, security is maintained at its highest level. .PP To start .BR recserv from the Internet daemon, the configuration file .B /etc/inetd.conf must include the single line entry, .PP .B "recserv stream tcp nowait bin /usr/lbin/recserv recserv -display :0" .PP and the services file .B /etc/services must include the line, .PP .B "recserv 7815/tcp # SharedX Receiver Service" .sp .PP .I Receiver Service options, set by selecting the .I Options button, dictate the behavior of .B recserv. The behavior can also be set by running .B recserv manually. In either case, an X server resource is set dictating the behavior for subsequent invocations of .B recserv. .SH OPTIONS The following options allow different behavior according to user preferences. .RS .TP .B "AlwaysAsk" The dialog will pop up each time sharing is requested, regardless of the security on your X server. .TP .B "AlwaysAllow" The dialog box never appears, but sharing will always be allowed. .TP .B "AskUnhosted" The dialog will pop up only if the sender's machine is not hosted on your machine. If the sender's machine is already hosted, sharing will occur without a dialog appearing. .TP .B "NeverAsk" The dialog will never appear. Windows are shared only if the sender's machine is already hosted by your server. .RE To set resources (system behavior, label strings, etc) globally for a system, edit the file .B /usr/lib/X11/app-defaults/RecServ. .SH AUTHOR .I HP SharedX Receiver Service was developed by Hewlett Packard. .SH SEE ALSO SharedX(1), inetd(1M), xhost(1), hosts(4), inetd.conf(4), inetd.sec(4), services(4). .br .\" .\" index \fItelnetd\fR: \s-1TELNET\s+1 protocol server \fBtelnetd(1M) \fR .\" index \s-1TELNET\s+1 protocol server \fBtelnetd(1M)\fR .\" index protocol server, \s-1TELNET\s+1 \fBtelnetd(1M)\fR .\" index server, \s-1TELNET\s+1 protocol \fBtelnetd(1M)\fR .\" .\" toc \fBtelnetd(1M)\fR:\0\0\fItelnetd\fR \s-1TELNET\s+1 protocol server .\" .\" fileset_database telnetd.1m ARPA-MAN .\" $Header: accept.1m,v 72.5 94/09/13 11:07:55 ssa Exp $ .TA a .TH accept 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME accept, reject \- allow/prevent LP printer queuing requests .SH SYNOPSIS .CR /usr/sbin/accept .IR destination \ ...\& .PP .CR /usr/sbin/reject .RC \|[ \-r [\f2reason\fP]\|]\| .IR destination \ ...\& .RC \|[ \-r [\f2reason\fP]\| .IR destination \ ...]\ ...\& .SH DESCRIPTION The .CR accept command permits the .CR lp command (see .IR lp (1)) to accept printing requests for each named LP printer or printer class .IR destination queue. .PP The .CR reject command causes the .CR lp command to reject subsequent printing requests for each named .IR destination queue. Requests already queued will continue to be processed for printing by the .CR lpsched scheduler (see .IR lpsched (1M)). .PP Use the .CR lpstat command (see .IR lpstat (1)) to find the status of destination queues. .PP For an overview of LP command interactions, see .IR lp (1). .SS Options The .CR reject command can have the following option. .RS .TP 15 .CR \-r "[\f2reason\fP]" Specifies a string that is used to explain why the .CR lp command is not accepting requests for a destination. .I reason applies to all queues mentioned up to the next .CR \-r option. If .I reason or .CR \-r "[\f2reason\fP]" is omitted, the default is "\c .CR "reason\ unknown\c" ". The maximum length of .I reason is 80 bytes. .IP .I reason is reported by the .CR lpstat command and by the .CR lp command when users direct requests to a rejected destination. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .PP The .CR LANG variable determines the language in which messages are displayed. If .CR LANG is not specified or is set to the empty string, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SS International Code Set Support Single- and multibyte character code sets are supported. .SH EXAMPLES .PP These examples assume you have a system with two printers named .CR laser1 and .CR jet2 , and one class named .CR lj that includes both printers. .ne 4 .SS Example 1 To allow all destinations to accept print requests: .IP .C "accept laser1 jet2 lj" .ne 4 .SS Example 2 To reject requests to the .CR lj class destination, requiring users to choose a printer: .IP .C "reject lj .ne 5 .SS Example 3 To reject requests to the individual printer destinations, requiring all requests to go through the class destination: .IP .C "accept lj" .br .C "reject -r""use the lj destination"" laser1 jet2" .SH WARNINGS .CR accept and .CR reject operate on the local system only. .SH FILES .TP 35 .PD 0 .CR /etc/lp Directory of spooler configuration data .TP .CR /var/adm/lp Directory of spooler log files .TP .CR /var/spool/lp Directory of LP spooling files and directories .PD .SH SEE ALSO enable(1), lp(1), lpstat(1), lpadmin(1M), lpsched(1M), rcancel(1M), rlp(1M), rlpdaemon(1M), rlpstat(1M). .\" .\" index@\f4accept\f1 \- allow LP printer queuing requests@@@\f3accept(1M)\f1 .\" index@\f4reject\f1 \- prevent LP printer queuing requests@@@\f3accept(1M)\f1 .\" index@\f1LP printer, allow or prevent queuing requests@@@\f3accept(1M)\f1 .\" index@\f1printer, LP, allow or prevent queuing requests@@@\f3accept(1M)\f1 .\" .\" toc@\f3accept(1M)\f1:\0\0\f4accept\f1, \f4reject\f1@@@allow or prevent LP printer queuing requests\f1 .\" toc@\f4reject\f1:\0\0prevent LP printer queuing requests@@@see \f3accept(1M)\f1 .\" .\" links@accept.1m reject.1m ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "remove directory" 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "directories" "removing attribute values (CDS)" .iX "-[" "\*Lcdscp\*O commands" "\*Lremove directory\*O" .SH NAME .PP \*Lremove directory\*O - Removes a value from a set-valued or single-valued attribute (including application-defined attributes) of a directory .wH "" .SH "SYNOPSIS" .sS \*Lcdscp remove directory \*Vdirectory-name attribute-name \*O[= \*Vattribute-value\*O] .sE .SH "ARGUMENTS" .VL .LI "\*Vdirectory-name\*O" The full name of the directory. .LI "\*Vattribute-name\*O" The name of a particular attribute. Specify only one attribute at a time. See the \*Lcds_attributes\*O file for the list of attributes and corresponding data types that your application uses. .LI "\*Vattribute-value\*O" The value of a particular attribute. The value of an application-defined attribute is dependent on the type of attribute. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lremove directory\*O command removes a value from a set-valued or single-valued attribute (including application-defined attributes) of a directory. If you do not specify a value, the command removes the entire attribute. This command can delete attributes created by the \*Ladd directory\*O and \*Lset directory\*O commands. Usually this task is performed through the client application. See the \*VOSF DCE Administration Guide\*O for more information about attributes. .SS "Privilege Required" .PP You must have write permission to the directory. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP To remove the value \*L1\*O from the user-defined, set-valued attribute \*Ldirregion\*O of a directory named \*L/.:/sales\*O, follow these steps: .AL .LI Read the \*Lcds_attributes\*O file to check that the attribute \*Ldirregion\*O is listed, as shown in the following display: .iS \*C OID LABEL SYNTAX 1.3.22.1.3.66 dirregion small\*O .iE .LI Enter the following command to remove the value \*L1\*O from the attribute \*Ldirregion\*O. .iS \*Ccdscp> \*Lremove directory /.:/sales dirregion = 1 .iE .LE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ladd directory(1m)\*O, \*Llist directory(1m)\*O, \*Lset directory(1m)\*O, \*Lset directory to skulk(1m)\*O, \*Lshow directory(1m)\*O .PP Books: \*VOSF DCE Administration Guide\*O .wH "" .wH "" .iX "-]" "directories" "removing attribute values (CDS)" .iX "-]" "\*Lcdscp\*O commands" "\*Lremove directory\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "remove link" 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "soft links" "removing timeout value attribute" .iX "\*Lcdscp\*O commands" "\*Lremove link\*O" .SH NAME \*Lremove link\*O - Removes a soft link's timeout value attribute .wH "" .SH "SYNOPSIS" .sS \*Lcdscp remove link \*Vlink-name\*O \*LCDS_LinkTimeout\*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vlink-name\*O" The full name of the soft link. .wH "" .LE .SH "DESCRIPTION" The \*Lremove link\*O command removes a soft link's timeout value attribute, \*LCDS_LinkTimeout\*O, causing the soft link to become permanent. .SS "Privilege Required" .PP You must have write permission to the soft link. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" The following command removes the timeout value attribute of a soft link named \*L/.:/eng/link01\*O. .iS \*Ccdscp> \*Lremove link /.:/eng/link01 CDS_LinkTimeout\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lcreate link(1m)\*O, \*Ldelete link(1m)\*O, \*Llist link(1m)\*O, \*Lset link(1m)\*O, \*Lshow link(1m)\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "remove object"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "objects" "removing attribute values" .iX "-[" "\*Lcdscp\*O commands" "\*Lremove object\*O" .SH NAME .PP \*Lremove object\*O - Removes a value from a set-valued or single-valued attribute (including application-defined attributes) of an object entry .wH "" .SH "SYNOPSIS" .PP \*Lcdscp remove object\*O \*Vobject-name attribute-name\*O [\*V= attribute-value\*O] .wH "" .SH "ARGUMENTS" .VL .LI "\*Vobject name\*O" The full name of the object entry. .LI "\*Vattribute-name\*O" The name of a particular attribute. Specify only one attribute at a time. See the \*Lcds_attributes\*O file for the list of attributes and corresponding data types that your application uses. .LI "\*Vattribute-value\*O" The value of a particular attribute. The value of an application-defined attribute is dependent on the type of attribute. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lremove object\*O command removes a value from a set-valued or single-valued attribute (including application-defined attributes) of an object entry. If you do not specify a value, the command removes the entire attribute. This command can delete attributes created by the \*Ladd object\*O and \*Lset object\*O commands. Usually, this task is performed through the client application. See the \*VOSF DCE Administration Guide\*O for more information about attributes. .SS "Privilege Required" .PP You must have write permission to the object entry. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP .PP To remove the value \*Lps\*O from the attribute \*Lprintcap\*O of an object entry named \*L/.:/mlh/deskprinter\*O, follow these steps: .AL .LI Read the \*Lcds_attributes\*O file to check that the attribute \*Lprintcap\*O is listed, as shown in the following display: .iS \*C OID LABEL SYNTAX 1.3.22.1.3.50 printcap char\*O .iE .LI Enter the following command to remove the value \*Lps\*O from the attribute \*Lprintcap\*O. .iS \*Ccdscp> \*Lremove object /.:/mlh/deskprinter printcap = ps .iE .LE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ladd object(1m)\*O, \*Llist object(1m)\*O, \*Lset object(1m)\*O, \*Lshow object(1m)\*O .PP Books: \*VOSF DCE Administration Guide\*O .wH "" .wH "" .iX "-]" "objects" "removing attribute values" .iX "-]" "\*Lcdscp\*O commands" "\*Lremove object\*O" .\" $Header: remshd.1m,v 72.5 94/12/09 15:05:56 ssa Exp $ .TA r .TH remshd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME remshd \- remote shell server .SH SYNOPSIS .CR /usr/lbin/remshd .RC [ \-ln ] .SH DESCRIPTION The .CR remshd command is the server for the .CR rcp , .CR rdist and .CR remsh commands, and the .CR rcmd() function (see .IR rcp (1), .IR rdist (1), .IR remsh (1), and .IR rcmd (3N)). The server provides remote execution facilities with authentication based on privileged port numbers. .PP The .CR inetd daemon calls .CR remshd when a service request is received at the port indicated for the .CR shell (or .CR cmd ) service specified in .CR /etc/services (see .IR inetd (1M) and .IR services (4)). When called, .CR inetd creates a connection to the service on the client's host. To run .CR remshd , the following line should be present in the .CR /etc/inetd.conf file: .IP .C "shell stream tcp nowait root /usr/lbin/remshd remshd" .PP See .IR inetd.conf (4) for more information. .SS Options .CR remshd recognizes the following options. .RS .TP .CR \-l Disallow authentication based on the user's .CR .rhosts file unless the user is a superuser. .TP .CR \-n Disable transport-level keep-alive messages. Otherwise, the messages are enabled. The keep-alive messages allow sessions to be timed out if the client crashes or becomes unreachable. .RE .SS Operation When .CR remshd receives a service request, it responds with the following protocol: .RS .TP 1. The server checks the client's source port. If the port is not in the range 512 through 1023, the server aborts the connection. .TP 2. The server reads characters from the connection up to a null .RC ( \e0 ) byte. It interprets the resulting string as an ASCII number, base 10. .TP 3. If the number is non-zero, it is interpreted as the port number of a secondary stream to be used for standard error. A second connection is then created to the specified port on the client's host. (The source port of this second connection must be also in the range 512 through 1023.) If the first character sent is a null .RC ( \e0 ), no secondary connection is made, and the standard error from the command is sent to the primary stream. If the secondary connection has been made, .CR remshd interprets bytes it receives on that socket as signal numbers and passes them to the command as signals. See .IR signal (2). .TP 4. The server checks the client's source address and requests the corresponding host name (see .IR named (1M), .IR gethostbyaddr (3N), and .IR hosts (4)). If it cannot determine the hostname, it uses the dot-notation representation of the host address. .TP 5. The server reads the client's host account name from the first connection. This is a null-terminated sequence not exceeding 16 characters. .TP 6. The server reads the server's host account name from the first connection. This is a null-terminated sequence not exceeding 16 characters. .TP 7. The server reads a command to be passed to the shell from the first connection. The command length is limited by the maximum size of the system's argument list. .TP 8. .CR remshd then validates the user as follows (all actions take place on the host .CR remshd runs on): .RS .TP a. It looks up the user account name (retrieved in step 6) in the password file. If it finds it, it performs a .CR chdir() to either the user's home directory, if there is one, or to "/." .TP b. If either the lookup or .CR chdir() fails, the connection is terminated (see .IR chdir (2)). .TP c. The connection is also terminated if .RS .TP \(bu the account accessed is administratively locked; .TP \(bu the account accessed is protected by a password and, either the password expired or the account on the client's host is not equivalent to the account accessed; .TP \(bu .C remshd runs on a secure system and the account accessed is not protected by a password. .PP For more information on equivalent accounts, see .IR hosts.equiv (4). .RE .RE .TP 9. A null byte is returned on the primary connection and the command line is passed to the normal login shell of the user with that shell's .CR \-c option. The shell inherits the network connections established by .CR remshd and assumes the normal user and group permissions of the user. .IP .CR remshd uses the following path when executing the specified command: .RS .IP .C "/usr/bin:/usr/ccs/bin:/usr/bin/X11:" .RE .TP 10. If a secondary socket has been set up, .CR remshd normally exits when command standard error and secondary socket standard error have both been closed. If no secondary socket was set up, .CR remshd has called an .IR exec (2) function, launched the command process, and is no longer present. .RE .SH DIAGNOSTICS All diagnostic messages are returned on the connection associated with standard error after which any network connections are closed. An error is indicated by a leading byte with a value of 1 (0 is returned in step 9 above upon successful completion of all the steps before the command execution). .TP .C "Malformed from address" .IP The first socket connection does not use a reserved port or the client's host address is not an Internet address. .TP .C "Can't get stderr port" .IP Unable to complete the connection of the secondary socket used for error communication. .TP .C "Second port not reserved" .IP The secondary socket connection does not use a reserved port. .TP .C "Locuser too long" .IP The name of the user account on the client's host is longer than 16 characters. .TP .C "Remuser too long" .IP The name of the user on the server's host is longer than 16 characters. .TP .C "Command too long" .IP The command line passed exceeds the size of the argument list (as configured into the system). .TP .C "Login incorrect" .IP No password file entry existed for the user name on the server's host, or the authentication procedure described above in step 8 failed. .TP .C "No remote directory" .IP The .CR chdir command to the home directory or "/" on the server's host failed. .TP .C "Can't make pipe" .IP The pipe needed for the standard error output wasn't created. .TP .C "No more processes" .IP The server was unable to fork a process to handle the incoming connection. .IP .IR "Next step" : Wait a period of time and try again. If this message persists, the server's host may have runaway processes that are using all the entries in the process table. .TP .IC "system call" ": " message .IP Error in executing the named system call. The message specifies the cause of the failure. .TP .IC shellname ": " \f1... .IP The user's login shell could not be started. This message is returned on the connection associated with the standard error, and is not preceded by a leading byte with a value of 1. Other messages can be returned by the remote command when it executes. .SH WARNINGS The "privileged port" authentication procedure used here assumes the integrity of each host and the connecting medium. This is insecure, but is useful in an "open" environment. .PP .CR remshd ignores .CR SIGHUP , .CR SIGINT , .CR SIGQUIT , and .CR SIGTERM , so these signal numbers can safely be sent to remote commands via the secondary socket provided by .CR remshd . Other signal numbers may cause .CR remshd to kill itself. .SH AUTHOR .CR remshd was developed by the University of California, Berkeley. .SH FILES .TP 30 .PD 0 .CR $HOME/.rhosts User's private equivalence list .TP .CR /etc/hosts.equiv List of equivalent hosts .PD .SH SEE ALSO remsh(1), inetd(1M), named(1M),\" STD rcmd(3N), hosts(4), hosts.equiv(4), inetd.conf(4), inetd.sec(4), services(4). .\" .\" index@\f4remshd\f1 \- remote shell server@@@\f3remshd(1M)\f1 .\" index@\f1remote shell server@@@\f3remshd(1M)\f1 .\" index@\f1server, remote shell@@@\f3remshd(1M)\f1 .\" index@\f1shell server, remote@@@\f3remshd(1M)\f1 .\" .\" toc@\f3remshd(1M)\f1:\0\0\f4remshd\f1@@@remote shell server .\" $Header: renice.1m,v 78.1 96/02/13 16:03:27 ssa Exp $ .\" Copyright: Hewlett-Packard Company .TA r .TH renice 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME renice \- alter priority of running processes .SH SYNOPSIS .CR renice .RC \|[ -n .IR newoffset ]\| .RC \|[ -g \(or -p \(or\c .CR -u ]\| .IR id \0... .SH DESCRIPTION The .CR renice command alters the system nice value (used in the system scheduling priority) of one or more running processes specified by .IR id \0.... The new system nice value is set to 20 + .IR newoffset , and is limited to the range 0 to 39. However if the .CR UNIX95 environment variable is set, the new system nice value is set to current nice value + .IR newoffset. Processes with lower system nice values run at higher system priorities than processes with higher system nice values. The .CR -l option of the .CR ps command shows the current priority .RC ( PRI ) and nice value .RC ( NI ) for processes. See also .CR nice (1). .PP To reduce the system nice value of a process, or to set it to a value less than 20 (with a negative .IR newoffset ), a user must have appropriate privileges. Otherwise, users cannot decrease the system nice value of a process and can only increase it within the range 20 to 39, to prevent overriding any current administrative restrictions. .PP To alter the system nice value of another user's process, a user must have appropriate privileges. Otherwise, users can only affect processes that they own. .SS Options .CR renice recognizes the following options. If no .CR -g , .CR -p , or .CR -u option is specified, the default is .CR -p . .RS .TP 15 .CI -g \0id\0\f1... Interpret each .IR id as a process group .SM ID\s0. All processes in each process group have their system nice value altered. Only users with appropriate privileges can use this option. .TP .CI -n \0newoffset Change the system nice value of each affected process to 20 + .IR newoffset . If the .CR UNIX95 environment variable is set, the system nice value of each affected process is changed to current nice value + .IR newoffset. .IP If .IR newoffset is negative, the system nice value is set to 20 minus the absolute value of .IR newoffset . If the .CR UNIX95 environment variable is set and the .IR newoffset is negative, the system nice value is set to current nice value minus the absolute value of .IR newoffset. Only users with appropriate privileges can reduce the system nice value or set it to less than 20. If this option is omitted, .IR newoffset defaults to 10. .TP .CI -p \0id\0\f1... Interpret each .IR id as a process .SM ID\s0. This is the default. .IP .B Note: .IR id is a process .SM ID as reported by the .CR ps command, not a job number (e.g., .CR %1 ), as used by some shells. .TP .CI -u \0id\0\f1... Interpret each .IR id as a user name or user .SM ID number. All processes owned by each specified user have their system nice values altered. Only users with appropriate privileges can use this option for user names and .SM ID\s0s other than their own. .RE .SH RETURN VALUES .CR renice returns a 0 when successful, and a non-zero value when unsuccessful. .SH EXTERNAL INFLUENCES Single-byte character code sets are supported. .SH DIAGNOSTICS .CR renice reports the old and new .IR newoffset values (system nice value \(mi 20) of the affected processes if the operation requested completes successfully. Otherwise, an error message is displayed to indicate the reason for failure. .PP However, if the .CR UNIX95 envionment variable is set, no reporting is done unless the command fails. .SH EXAMPLES Use .CR renice default values to decrease the priority of process .CR 923 . The .IR id type defaults to .CR -p , and .IR newoffset defaults to .CR 10 , setting the process to a system nice value of 30. .IP .C "renice 923" .PP Change the system nice value for all processes owned by user .CR john and user .CR 123 to 33 .RI ( newoffset =13). (Affecting other users processes requires appropriate privileges.) .IP .C "renice -n 13 -u john 123" .PP Change the system nice value of all processes in process group 20 to .CR 10 . (Lowering the system nice value of a process group requires appropriate privileges.) .IP .C "renice -n -10 -g 20" .SH WARNINGS Users who do not have appropriate privileges cannot reduce the system nice values of their own processes, even if they increased them in the first place. .SH FILES .TP 20 .CR /etc/passwd Maps user names to user .SM ID\s0's .SH SEE ALSO nice(1), ps(1), getpriority(2), nice(2). .SH STANDARDS CONFORMANCE .CR renice ": XPG4" .\" .\" toc@\f3renice(1)\f1:\0\0\f4renice\fP@@@alter priority of running processes .\" .\" index@\f1alter priority of running processes@@@\f3renice(1)\f1 .\" index@\f1change priority of running processes@@@\f3renice(1)\f1 .\" index@\f1nice value@@@\f3renice(1)\f1 .\" index@\f1priority of running processes, alter@@@\f3renice(1)\f1 .\" index@\f1priority@@@\f3renice(1)\f1 .\" index@\f1processes, alter priority of running@@@\f3renice(1)\f1 .\" index@\f1running processes, alter priority of@@@\f3renice(1)\f1 .\" index@\f1scheduling priority@@@\f3renice(1)\f1 .\" index@\f1system nice value@@@\f3renice(1)\f1 .\" index@\f1system scheduling priority@@@\f3renice(1)\f1 .\" index@\f4renice\fP \- alter priority of running processes@@@\f3renice(1)\f1 .\" .\" fileset_database@renice.1 CMDS-MIN-MAN .\" $Header: repquota.1m,v 76.1 95/07/10 17:10:24 ssa Exp $ .TA r .TH repquota 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME repquota \- summarize file system quotas .SH SYNOPSIS .CR /usr/sbin/repquota .RC \|[ -v ]\| .IR filesystem \0... .PP .CR /usr/sbin/repquota .RC \|[ -v ]\| .CR -a .SH DESCRIPTION The .CR repquota command prints a summary of disk usage and quotas for each specified .IR filesystem . .PP .IR filesystem is either the name of the directory on which the file system is mounted or the name of the device containing the file system. .PP For each user, the current number of files and amount of space (in Kbytes) is printed, along with any quotas created with .CR edquota (see .IR edquota (1M)). .SS Options .CR repquota recognizes the following options: .RS .TP .CR -a Report on all appropriate file systems in .CR /etc/fstab . .TP .CR -v Report all quotas, even if there is no usage. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C repquota behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH AUTHOR Disk Quotas were developed by the University of California, Berkeley, Sun Microsystems, and HP. .SH FILES .TP 25 .PD 0 .CR /etc/fstab Static information about the file systems .TP .CR /etc/mnttab Mounted file system table .TP .IC directory /quotas Quota statistics static storage for the file system, where .IR directory is the root of the file system as interpreted by .CR mount (see .IR mount (1M)). .PD .SH SEE ALSO edquota(1M), mount(1M), quota(5). .\" .\" index@\f4repquota\f1 \- summarize file system quotas@@@\f3repquota(1M)\f1 .\" index@\f1summarize file system quotas@@@\f3repquota(1M)\f1 .\" index@\f1file system: summarize quotas@@@\f3repquota(1M)\f1 .\" index@\f1quotas, summarize for a file system@@@\f3repquota(1M)\f1 .\" index@\f1disk quotas, summarize for a file system@@@\f3repquota(1M)\f1 .\" .\" toc@\f3repquota(1M)\f1:\0\0\f4repquota\f1@@@summarize file system quotas .\" .\" $Header: restore.1m,v 72.4 94/08/12 11:18:53 ssa Exp $ .TA r .TH restore 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME restore, rrestore \- restore file system incrementally, local or across network .SH SYNOPSIS .C /usr/sbin/restore .I key .RI [ \|name \0...\|] .PP .C /usr/sbin/rrestore .I key .RI [ \|name \0...\|] .SH DESCRIPTION The .CR restore and .CR rrestore commands read tapes previously dumped by the .CR dump or .CR rdump command (see .IR dump (1M) and .IR rdump (1M)). Actions taken are controlled by the .I key argument where .I key is a string of characters containing not more than one function letter and possibly one or more function modifiers. One or more .I name arguments, if present, are file or directory names specifying the files that are to be restored. Unless the .CR h modifier is specified (see below), the appearance of a directory name refers to the files and (recursively) subdirectories of that directory. .SS Function Portion of \f2key\fP The function portion of the key is specified by one of the following letters: .RS .TP 6 .C r Read the tape and load into the current directory. .CR r should be used only after careful consideration, and only to restore a complete dump tape onto a clear file system, or to restore an incremental dump tape after a full level zero restore. Thus, .RS .IP .nf .C /usr/sbin/newfs -F hfs /dev/rdsk/c0t0d0 .C /usr/sbin/mount /dev/dsk/c0t0d0 /mnt .C cd /mnt .C restore r .fi .RE .IP is a typical sequence to restore a complete dump. Another .CR restore or .CR rrestore can then be performed to restore an incremental dump on top of this. Note that .CR restore and .CR rrestore leave a file .CR restoresymtab in the root directory of the file system to pass information between incremental restore passes. This file should be removed when the last incremental tape has been restored. A .CR dump or .CR rdump followed by a .CR newfs and a .CR restore or .CR rrestore is used to change the size of a file system (see .IR newfs (1M)). .TP .C R .CR restore and .CR rrestore request a particular tape of a multivolume set on which to restart a full restore (see .CR r above). This provides a means for interrupting and restarting .CR restore and .CR rrestore . .TP .C x Extract the named files from the tape. If the named file matches a directory whose contents had been written onto the tape, and the .CR h modifier is not specified, the directory is recursively extracted. The owner, modification time, and mode are restored (if possible). If no file argument is given, the root directory is extracted, which results in the entire contents of the tape being extracted, unless .CR h has been specified. .TP .C t Names of the specified files are listed if they occur on the tape. If no file argument is given, the root directory is listed, which results in the entire content of the tape being listed, unless .CR h has been specified. .TP .C s The next argument to .CR restore is used as the dump file number to recover. This is useful if there is more than one dump file on a tape. .TP .C i This mode allows interactive restoration of files from a dump tape. After reading in the directory information from the tape, .CR restore and .CR rrestore provide a shell-like interface that allows the user to move around the directory tree selecting files to be extracted. The available commands are given below; for those commands that require an argument, the default is the current directory. .RS .RS .TP 15 .CR add \0[\f2arg\fP] The current directory or specified argument is added to the list of files to be extracted. If a directory is specified, it and all its descendents are added to the extraction list (unless the .CR h key is specified on the command line). File names on the extraction list are displayed with a leading .CR * when listed by .CR ls . .TP .CR cd \0[\f2arg\fP] Change the current working directory to the specified argument. .TP .CR delete \0[\f2arg\fP] The current directory or specified argument is deleted from the list of files to be extracted. If a directory is specified, it and all its descendents are deleted from the extraction list (unless .CR h is specified on the command line). The most expedient way to extract files from a directory is to add the directory to the extraction list, then delete unnecessary files. .TP .C extract All files named on the extraction list are extracted from the dump tape. .CR restore and .CR rrestore ask which volume the user wants to mount. The fastest way to extract a few files is to start with the last volume, then work toward the first volume. .TP .C help List a summary of the available commands. .TP .CR ls \0[\f2arg\fP] List the current or specified directory. Entries that are directories are displayed with a trailing .CR / . Entries marked for extraction are displayed with a leading .CR * . If the verbose key is set, the inode number of each entry is also listed. .TP .C pwd Print the full path name of the current working directory. .TP .C quit .CR restore and .CR rrestore immediately exit, even if the extraction list is not empty. .TP .C set-modes Set the owner, modes, and times of all directories that are added to the extraction list. Nothing is extracted from the tape. This setting is useful for cleaning up after a restore aborts prematurely. .TP .C verbose The sense of the .CR v modifier is toggled. When set, the verbose key causes the .C ls command to list the inode numbers of all entries. It also causes .CR restore and .CR rrestore to print out information about each file as it is extracted. .RE .RE .RE .SS Function Modifiers The following function modifier characters can be used in addition to the letter that selects the function desired: .RS .TP 6 .C b Specify the block size of the tape in kilobytes. If the .CR -b option is not specified, .CR restore and .CR rrestore try to determine the tape block size dynamically. .TP .C f Specify the name of the archive instead of .CR /dev/rmt/0m . If the name of the file is .CR - , .CR restore reads from standard input. Thus, .CR dump and .CR restore can be used in a pipeline to dump and restore a file system with the command .RS .IP .C "dump 0f - /usr | (cd /mnt; restore xf -) .RE .IP When using .CR rrestore , this key should be specified, and the next argument supplied should be of the form .IC machine : device\f1. .TP .C h Extract the actual directory, rather than the files to which it refers. This prevents hierarchical restoration of complete subtrees from the tape, rather than the files to which it refers. .TP .C m Extract by inode numbers rather than by file name. This is useful if only a few files are being extracted and one wants to avoid regenerating the complete path name to the file. .TP .C v Type the name of each file .CR restore and .CR rrestore treat, preceded by its file type. Normally .CR restore and .CR rrestore do their work silently; the .CR v modifier specifies verbose output. .TP .C y Do not ask whether to abort the operation if .CR restore and .CR rrestore encounters a tape error. .CR restore and .CR rrestore attempt to skip over the bad tape block(s) and continue. .PP .CR rrestore creates a server, either .CR /usr/sbin/rmt or .CR /etc/rmt, on the remote machine to access the tape device. .RE .SH DIAGNOSTICS .CR restore and .CR rrestore complain about bad key characters. .PP .CR restore and .CR rrestore complain if a read error is encountered. If the .CR y modifier has been specified, or the user responds .CR y , .CR restore and .CR rrestore attempt to continue the restore. .PP If the dump extends over more than one tape, .CR restore and .CR rrestore ask the user to change tapes. If the .CR x or .CR i function has been specified, .CR restore and .CR rrestore also ask which volume the user wants to mount. The fastest way to extract a few files is to start with the last volume and work towards the first volume. .PP There are numerous consistency checks that can be listed by .CR restore and .CR rrestore . Most checks are self-explanatory or can ``never happen''. Here are some common errors: .RS .TP .IC filename ": not found on tape" The specified file name was listed in the tape directory but not found on the tape. This is caused by tape read errors while looking for the file, and from using a dump tape created on an active file system. .TP .CI "expected next file " inumber ", got " inumber A file not listed in the directory showed up. This can occur when using a dump tape created on an active file system. .TP .C "Incremental tape too low" When doing an incremental restore, a tape that was written before the previous incremental tape, or that has too low an incremental level has been loaded. .TP .C "Incremental tape too high" When doing an incremental restore, a tape that does not begin its coverage where the previous incremental tape left off, or that has too high an incremental level has been loaded. .TP .CI "Tape read error while restoring " filename" .PD 0 .TP .CI "Tape read error while skipping over inode " inumber" .TP .C "Tape read error while trying to resynchronize" A tape read error has occurred. If a file name is specified, the contents of the restored files are probably partially wrong. If restore is skipping an inode or is trying to resynchronize the tape, no extracted files are corrupted, although files may not be found on the tape. .PD .TP .CI "Resync restore, skipped " num" blocks" After a tape read error, .CR restore and .CR rrestore may have to resynchronize themselves. This message indicates the number of blocks skipped over. .SH WARNINGS .CR restore and .CR rrestore can get confused when doing incremental restores from dump tapes that were made on active file systems. .PP A level zero dump (see .IR dump (1M)) must be done after a full restore. Since restore runs in user code, it has no control over inode allocation; thus a full dump must be done to get a new set of directories reflecting the new inode numbering, even though the contents of the files are unchanged. .SH AUTHOR .CR restore and .CR rrestore were developed by the University of California, Berkeley. .SH FILES .TP 25 .C /dev/rmt/0m Default tape drive. .TP .C /tmp/rstdr* File containing directories on the tape. .TP .C /tmp/rstmd* Owner, mode, and time stamps for directories. .TP .C ./restoresymtab Information passed between incremental restores. .SH SEE ALSO dump(1M), mkfs(1M), mount(1M), newfs(1M), rmt(1M). .\" .\" index@\f4restore\f1 \- incrementally restore file system@@@\f3restore(1M)\f1 .\" index@\f4rrestore\f1 \- incrementally restore file system across network@@@\f3restore(1M)\f1 .\" index@\f1incrementally restore file system@@@\f3restore(1M)\f1 .\" index@\f1restore file system incrementally@@@\f3restore(1M)\f1 .\" index@\f1remote incremental file system restore@@@\f3restore(1M)\f1 .\" index@\f1network, restore file system incrementally across@@@\f3restore(1M)\f1 .\" index@\f1file system, restore incrementally, local or across network@@@\f3restore(1M)\f1 .\" .\" toc@\f3restore(1M)\f1:\0\0\f4restore\f1, \f4rrestore\f1@@@restore file system incrementally, local or over a network\f1 .\" toc@\f4rrestore\f1: restore file system incrementally over a network@@@see \f3restore(1M)\f1 .\" .\" links@restore.1m rrestore.1m .\" $Header: revck.1m,v 72.6 94/11/02 01:31:46 ssa Exp $ .TA r .TH revck 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME revck \- check internal revision numbers of HP-UX files .SH SYNOPSIS .C /usr/old/usr/bin/revck .I ref_files .SH DESCRIPTION .C revck checks the internal revision numbers of lists of files against reference lists. Each .I ref_file must contain a list of absolute path names (each beginning with .CR / ) and .I whatstrings (revision information strings from .C what \(em see .IR what (1)). Path names begin in column 1 of a line, and have a colon appended to them. Each path name is followed by zero or more lines of .IR whatstrings , one per line, each indented by at least one tab (this is the same format in which .C what outputs its results). .PP For each path name, .C revck checks that the file exists, and that executing .C what on the current path name produces results identical to the .I whatstrings in the reference file. Only the first 1024 bytes of .I whatstrings are checked. .PP .I ref_files are usually the absolute path names of the .I revlist files shipped with .SM HP-UX. Each .SM HP-UX software product includes a file named .CI /system/ product/ revlist (for example, .CR /system/97070A/revlist ). The .I revlist file for each product is a reference list for the ordinary files shipped with the product, plus any empty directories on which the product depends. .SH FILES .TP 30 .CI /system/ product /revlist lists of .SM HP-UX files and revision numbers .SH SEE ALSO what(1). .SH DIAGNOSTICS .C revck is silent except for reporting missing files or mismatches. .SH WARNINGS .C revck produces unpredictable results if a .I ref_file is not in the right format. .\" .\" index@\f4revck\f1 \- check internal revision numbers of \s-1HP-UX\s+1 files@@@\f3revck(1M)\f1 .\" index@check internal revision numbers of \s-1HP-UX\s+1 files@@@\f3revck(1M)\f1 .\" index@verify internal revision numbers of \s-1HP-UX\s+1 files@@@\f3revck(1M)\f1 .\" index@internal revision numbers of \s-1HP-UX\s+1 files, verify@@@\f3revck(1M)\f1 .\" index@revision numbers of \s-1HP-UX\s+1 files, verify internal@@@\f3revck(1M)\f1 .\" index@\s-1HP-UX\s+1 files, verify internal revision numbers of@@@\f3revck(1M)\f1 .\" index@files: verify internal revision numbers of \s-1HP-UX\s+1 files@@@\f3revck(1M)\f1 .\" .\" toc@\f3revck(1M)\f1:\0\0\f4revck\f1@@@check internal revision numbers of HP-UX files .\" .\" fileset_database@revck.1m SYS-ADMIN-MAN .\" $Header: rexd.1m,v 72.6 94/11/29 11:51:33 ssa Exp $ .TA r .TH rexd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rexd \- RPC-based remote execution server .SH SYNOPSIS .C /usr/sbin/rpc.rexd .RC [ -l .IR log_file ] .RC [ -m .IR mountdir ] .RC [ -r ] .SH DESCRIPTION .CR rexd is the RPC server for remote command execution. A .CR rexd is started by .CR inetd when a remote execution request is received (see .IR inetd (1M)). .CR rexd exits when command execution has completed. .PP If the user ID (uid) in the remote execution request is assigned to a user on the server, .CR rexd executes the command as that user. If no user on the server is assigned to the uid, .CR rexd does not execute the command. The .CR -r option and .CR inetd.sec security file allow for better access control (see .IR inetd.sec (4)). .PP For noninteractive commands, standard output and error file descriptors are connected to sockets. Interactive commands use pseudo terminals for standard input, output, and error (see .IR pty (7)). .PP If the file system specified in the remote execution request is not already mounted on the server, .CR rexd uses NFS to mount the file system for the duration of the command execution (see .IR nfs (7)). .CR rexd mounts file systems with the .CR nosuid and .CR soft options. For more details on mount options see .IR mount (1M). If the server cannot mount the file system, an error message is returned to the client. By default, any mount points required by .CR rexd are created below .CR /var/spool/rexd . To change the default location, use the .CR -m option. .SS Options .CR rexd recognizes the following options and command-line arguments: .RS .TP 20 .CI -l \0log_file Log any diagnostic, warning, and error messages to .IR log_file . If .I log_file exists, .CR rexd appends messages to the file. If .I log_file does not exist, .CR rexd creates it. Messages are not logged if the .CR -l option is not specified. .IP Information logged to the file includes date and time of the error, host name, process ID and name of the function generating the error, and the error message. Note that different RPC services can share a single log file because enough information is included to uniquely identify each error. .TP .CI -m \0mountdir Create temporary mount points below directory .IR mountdir . By default, .CR rexd creates temporary mount points below .CR /var/spool/rexd . The directory .I mountdir should have read and execute permission for all users (mode 555). Otherwise, .CR rexd denies execution for users that do not have read and execute permission. .TP .CR -r Use increased security checking. When started with the .CR -r option, .CR rexd denies execution access to a client unless one of the following conditions is met: .RS .RS .TP 3 \(bu The name of the client host is in .CR /etc/hosts.equiv file on the server. .TP \(bu The user on the server that is associated with the uid sent by the client has an entry in .CR $HOME/.rhosts specifying the client name on a line or the client name followed by at least one blank and the user's name. .IP For example, assume a user whose login name is .CR mjk is assigned to uid 7 on .CR NODE1 and executes the following .CR on command: .IP .C on NODE2 pwd .IP User .CR mjk on .CR NODE2 must have one of the following entries in .CR $HOME/.rhosts : .RS .IP .CR NODE1 .br .C NODE1 mjk .RE .RE .RE .ift .br .ift .ne 6 .SH DIAGNOSTICS The following is a subset of the messages that could appear in the log file if the .CR -l option is used. Some of these messages are also returned to the client. .RS .TP 12 .CI "rexd: could not umount: " dir .CR rexd was unable to .CR umount() the user's current working file system. See WARNINGS for more details. .TP .CI "rexd: mountdir (" mountdir ") is not a directory" The path name .IR mountdir , under which temporary mount points are created, is not a directory or does not exist. .TP .CI "rexd: " command ": Command not found" .CR rexd could not find .IR command . .TP .CI "rexd: " command ": Permission denied" .CR rexd was denied permission to execute .IR command . .TP .CI "rexd: " command ": Text file busy" The executable file is currently open for writing. .TP .CI "rexd: " command ": Can't execute" .CR rexd was unable to execute .IR command . .TP .CR "rexd: root execution not allowed" .CR rexd does not allow execution as user .CR root . .TP .CI "rexd: User id " uid " not valid" The uid .I uid is not assigned to a user on the server. .TP .CI "rexd: User id " uid " denied access" .CR rexd was started with the .CR -r option and the remote execution request did not meet either of the conditions required by the .CR -r option. .TP .CI "rexd: " host " is not running a mount daemon" The host .I host on which the user's current working directory is located is not running .CR mountd . Therefore, .CR rexd is unable to mount the required file system (see .IR mountd (1M)). .TP .CI "rexd: not in export list for\0" file_system The host on which the client's current working directory is located does not have the server on the export list for file system .I file_system containing the client's current working directory. Therefore, .CR rexd is unable to mount the required file system. .SH WARNINGS The client's environment is simulated by .CR rexd , but not completely recreated. The simulation of the client's environment consists of mounting the file system containing the client's current working directory (if it is not already mounted) and setting the user's environment variables on the server to be the same as the user's environment variables on the client. Therefore a command run by .CR rexd does not always have the same effect as a command run locally on the client. .PP The .CR rex protocol only identifies the client user by sending the uid of the client process and the host name of the client. Therefore, it is very difficult for .CR rexd to perform user authentication. If a user on the server is assigned to the uid sent by the client, .CR rexd executes the requested command as that user. If no user on the client is assigned to the uid sent by the client, .CR rexd returns an error. .PP The .CR -r option has been added to provide increased user authentication. However, the authentication provided is not foolproof, and is limited by the information passed by the .CR rex protocol. .PP In order to simulate the client's environment, .CR rexd mounts the file system containing the client's current working directory (if it is not already mounted). This mount is intended to be temporary for the duration of the command. .PP If .CR rexd mounts a file system, it attempts to .CR umount() the file system after the command has completed executing. However, if .CR rexd receives a .CR SIGKILL signal (see .IR signal (2)), the file system is not unmounted. The file system remains mounted until the superuser executes the appropriate .CR umount command or the server is rebooted. .PP .CR rexd 's attempt to umount the file system can also fail if the file system is busy. The file system is busy if it contains an open file or a user's current working directory. The file system remains mounted until the superuser executes the appropriate .CR umount command or the server is rebooted. .PP For more information on .CR rexd security issues, see .IR "Using and Administering NFS Services" . Security issues and their consequences should be considered before configuring .CR rexd to run on a system. .SH FILES .TP 40 .CR /dev/pty [ pqr ] * Master pseudo terminals. .PD 0 .TP .CR /dev/tty [ pqr ] * Slave pseudo terminals. .TP .CR /dev/ptym/pty [ pqr ] * Master pseudo terminals. .TP .CR /dev/pty/tty [ pqr ] * Slave pseudo terminals. .TP .CR /etc/inetd.conf Configuration file for .IR inetd (1M). .TP .CR /etc/hosts.equiv List of equivalent hosts. .TP .CR $HOME/.rhosts User's private equivalence list. .TP .CI /var/spool/rexd/rexd xxxxx Temporary mount points for remote file systems where .I xxxxx is a string of alpha numeric characters. .PD .SH AUTHOR .CR rexd was developed by Sun Microsystems, Inc. .SH SEE ALSO on(1), inetd(1M), mount(1M), exports(4), inetd.conf(4), inetd.sec(4). .PP .I "Using and Administering NFS Services" .\" .\" index@\f4rexd\f1 \- RPC-based remote execution server@@@\f3rexd(1M)\f1 .\" index@\f1RPC-based remote execution server@@@\f3rexd(1M)\f1 .\" index@\f1remote execution server, RPC-based@@@\f3rexd(1M)\f1 .\" index@\f1execution server, RPC-based remote@@@\f3rexd(1M)\f1 .\" index@\f1server, RPC-based remote execution@@@\f3rexd(1M)\f1 .\" .\" toc@\f3rexd(1M)\f1:\0\0\f4rexd\f1@@@RPC-based remote execution server\f1 .\" $Header: rexecd.1m,v 72.3 94/12/09 15:06:23 ssa Exp $ .TA r .TH rexecd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rexecd \- remote execution server .SH SYNOPSIS .C /usr/lbin/rexecd .RC [ \|\-n\| ] .SH DESCRIPTION .CR rexecd is the server for the .IR rexec (3N) routine; it expects to be started by the internet daemon (see .IR inetd (1M)). .CR rexecd provides remote execution facilities with authentication based on user account names and unencrypted passwords. .PP .IR inetd (1M) calls .CR rexecd when a service request is received at the port indicated for the ``exec'' service specification in .CR /etc/services ; see .IR services (4). To run .CR rexecd , the following line should be present in .CR /etc/inetd.conf : .IP .C "exec stream tcp nowait root /usr/lbin/rexecd rexecd" .PP When a service request is received, the following protocol is initiated: .RS .TP 4 1. The server reads characters from the socket up to a null .RC ( \e0 ) byte. The resultant string is interpreted as an ASCII number, base 10. .TP 2. If the number received in step 1 is non-zero, it is interpreted as the port number of a secondary stream to be used for the .CR stderr . A second connection is then created to the specified port on the client's host. If the first character sent is a null .RC ( \e0 ), no secondary connection is made and the .CR stderr of the command is sent to the primary stream. If the secondary connection has been made, .CR rexecd interprets bytes it receives on that socket as signal numbers and passes them to the command as signals (see .IR signal (2)). .TP 3. A null-terminated user name of not more than 16 characters is retrieved on the initial socket. .TP 4. A null-terminated, unencrypted, password of not more than 16 characters is retrieved on the initial socket. .TP 5. A null-terminated command to be passed to a shell is retrieved on the initial socket. The length of the command is limited by the upper bound on the size of the system's argument list. .TP 6. .CR rexecd then validates the user as is done by .IR login (1). If the authentication succeeds, .CR rexecd changes to the user's home directory and establishes the user and group protections of the user. If any of these steps fail, .CR rexecd returns a diagnostic message through the connection, then closes the connection. .TP 7. A null byte is returned on the connection associated with .CR stderr and the command line is passed to the normal login shell of the user with that shell's .CR \-c option. The shell inherits the network connections established by .CR rexecd . .RE .PP .CR rexecd uses the following path when executing the specified command: .IP .C "/usr/bin:/usr/ccs/bin:/usr/bin/X11:" .PP Transport-level keepalive messages are enabled unless the .CR \-n option is present. The use of keepalive messages allows sessions to be timed out if the client crashes or becomes unreachable. .SH DIAGNOSTICS All diagnostic messages are returned on the connection associated with the .CR stderr , after which any network connections are closed. An error is indicated by a leading byte with a value of 1 (0 is returned in step 7 above upon successful completion of all the steps prior to the command execution). .RS .TP .C "Username too long" The user name is longer than 16 characters. .TP .C "Password too long" The password is longer than 16 characters. .TP .C "Command too long" The command line passed exceeds the size of the argument list (as configured into the system). .TP .C "Login incorrect" No password file entry for the user name existed or the wrong password was supplied. .TP .C "No remote directory" The .CR chdir command to the home directory failed. .TP .C "No more processes" The server was unable to fork a process to handle the incoming connection. .IP .IR "Next step" : Wait a period of time and try again. If the message persists, then the server's host may have a runaway process that is using all the entries in the process table. .TP .IC shellname ": ..." The user's login shell could not be started via .IR exec (2) for the given reason. .RE .SH WARNINGS The password is sent unencrypted through the socket connection. .SH AUTHOR .CR rexecd was developed by the University of California, Berkeley. .SH SEE ALSO remsh(1), inetd(1M), rexec(3N), inetd.conf(4), inetd.sec(4), services(4). .\" index@\f4rexecd\f1 \- remote execution server@@@\f3rexecd(1M)\f1 .\" index@\f1remote execution server@@@\f3rexecd(1M)\f1 .\" index@\f1execution server, remote@@@\f3rexecd(1M)\f1 .\" index@\f1server, remote execution@@@\f3rexecd(1M)\f1 .\" .\" toc@\f3rexecd(1M)\f1:\0\0\f4rexecd\f1@@@remote execution server .\" .\" fileset_database@rexecd.1m INETSVCS-MAN ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright (c) 1987 Apollo Computer, Inc. ..\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" .rm zA .rm zZ .TH rgy_edit "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .SH NAME \*Lrgy_edit\*O - Edits the registry database .SH "SYNOPSIS" .zA "def,8134,R1.0.2A,-update abbreviated as -up;add bracket" .zA "def,4718,R1.0.2,update syntax and options" .zA "defect,6211,R1.0.3,remove full path in SYNOPSIS" .sS \*Lrgy_edit\*O [[[\*L-a\*O | \*L-p\*O | \*L-g\*O | \*L-o\*O] [\*L-s\*V name\*O] [\*L-up[date\*O]] .br [\*L-v\*O [\*L-f\*O] [\*Vname\*O | \*L-un\*O[\*Vix__number\*O]] [\*L-nq\*O]] | \*L-l\*O] .sE .zZ "defect,6211,R1.0.3,remove full path in SYNOPSIS" .zZ "def,8134,R1.0.2A,-update abbreviated as -up;add bracket" .SH "OPTIONS" The following options are supplied when \*Lrgy_edit \*O is invoked. You can specify only one of the options \*L-a\*O, \*L-p\*O, \*L-g\*O, and \*L-o\*O. If you specify the \*L-l\*O option, you can specify no other options. .VL 1i .LI "\*L-a\*O (default)" Edits or views accounts. .LI "\*L-p\*O" Edits or views principals. .LI "\*L-g\*O" Edits or views groups. .LI "\*L-o\*O" Edits or views organizations. .LI "\*L-s\*O" Binds to the registry site specified by \*Vname\*O. The \*Vname\*O variable is either the fully qualified name of the cell that contains the registry to which you want access, or the fully qualified name of a specific registry server. .zA "def,8134,R1.0.2A,-update abbreviated as -u" .LI "\*L-up[date]\*O" Binds to a read-write registry site in the cell specified by the \*L-s\*O option. .zZ "def,8134,R1.0.2A,-update abbreviated as -u" .LI "\*L-v\*O" Views the registry entry specified by \*Vname\*O or \*Vunix_number\*O. If no entry is specified, all entries are viewed. .LI "\*L-f\*O" Displays in full the entry (or entries) selected by the \*L-v\*O option. The full entry includes all fields except the membership list and organization policy. .LI "\*L-nq\*O" Specifies that delete operations will not be queried. The default is to prompt the user for verification when a delete operation is requested. .LI "\*L-l\*O" Edits or views entries in local registry. .LE .zZ "def,4718,R1.0.2,update syntax and options" .zA "defect, 11818, R1.1, Added caveat" .SH "NOTES" With the exception of the following subcommands, this command is replaced at Revision 1.1 by the \*Ldcecp\*O command. This command may be fully replaced by the \*Ldcecp\*O command in a future release of DCE, and may no longer be supported at that time. .P .sS "Miscellaneous Subcommands" .P .ML .LI \*Ldefaults\*O .LI \*Ldomain\*O .LI \*Lscope\*O .LI \*Lhelp\*O .LI \*Lquit\*O .LI \*Lexit\*O .LE .P .sS "Local Registry Subcommands" .P .ML .LI \*Ldelete\*O .LI \*Lpurge\*O .LI \*Lview\*O .LE .zZ "defect, 11818, R1.1, Added caveat" .SH "DESCRIPTION" .PP The \*Lrgy_edit\*O tool views and edits information in the registry database. You can invoke \*Lrgy_edit\*O from any node. .PP You can edit and view principals, groups, organization, accounts, and policies in the network registry (the default) or perform a subset of those functions on the local registry (using the \*L-l\*O option). Changes made by \*Lrgy_edit\*O apply only to the registry. They do not apply to the local override file or the local password and group files, both of which can be edited manually. You can view and change only those registry objects to which you are granted the appropriate permissions. .PP .SS "Invoking rgy_edit" .PP When you invoke \*Lrgy_edit\*O, it displays the following prompt: .oS rgy_edit=> .oE At this prompt, you can enter any of the \*Lrgy_edit\*O subcommands, and \*Lrgy_edit\*O will prompt you for the required information. Alternatively, you can enter the subcommand followed by all the options required to perform a specific operation. The \*Lrgy_edit\*O command may prompt you for any required information you do not enter. .SH "SUBCOMMANDS" ...\" .zA "def,9113,document use of slash" .zA "def,4718,R1.0.2,null entries clarified" .PP In the \*Lrgy_edit\*O subcommands that follow, use two double quotation marks with nothing in between to indicate a null \*Vfullname\*O, \*Vpassword\*O, \*Vmisc\*O, \*Vhomedir\*O, or \*Vshell\*O. Use double quotation marks to embed spaces, or hyphens in \*Vfullname\*O, \*Vmisc\*O, and \*Vhomedir\*O if you specify the argument on the command line. .zZ "def,4718,R1.0.2,null entries clarified" ...\" To use a literal double quotation mark in \*Vfullname\*O or ...\" \*Vmisc\*O, precede each double quotation mark with a backslash (\\). ...\" .nS note ...\" In interactive mode, hyphens can be entered without the use of double quotation ...\" marks. The double quotation marks are required to enter hyphens in text in command-line mode. ...\" .nE ...\" .zZ "def,9113,document use of slash" .SS "Principal, Group, and Organization Subcommands" .P .zA "def,4718,R1.0.2,add -u" .sS \*Lv\*O[\*Liew\*O] [\*Vname\*O | \*L-u \*Vunix_number\*O] [\*L-f\*O] [\*L-m\*O] [\*L-po\*O] .sE .zZ "def,4718,R1.0.2,add -u" .iX "\*Lrgy_edit\*O subcommands" "\*Lview\*O" .iX "principals" "viewing registry information" .iX "organizations" "viewing registry information" .iX "groups" "viewing registry information" Views registry entries. Whether \*Vname\*O applies to a principal, group, or organization depends on the domain in which you run \*Lrgy_edit\*O. Use the \*Ldo[main]\*O subcommand (described in \*LMiscellaneous Commands\*O, later in this reference page) to change domains. .PP .zA "def,4718,R1.0.2,add -u" If you specify the \*L-u \*Vunix_number\*O option, \*Lrgy_edit\*O displays all matching entries, including any aliases. .zZ "def,4718,R1.0.2,add -u" .PP The \*L-f\*O option displays entries in full (all fields except the membership list and organization policy). .PP If you are viewing groups or organizations, \*L-m\*O displays the membership list. For principals, \*L-m\*O lists all groups of which the principal is a member, including groups that cannot appear in a project list. .PP If you are viewing organizations, \*L-po\*O displays policy information. If you do not enter the \*L-po\*O option, \*Lrgy_edit\*O shows only the organization's name and the UNIX number. .P .zA "def,4718,R1.0.2,add -f to syntax" .zA "def,4718,R1.0.2,unix_number optional" .zA "def,6220,R1.0.2,group aliases added" .sS \*La\*O[\*Ldd\*O] [\*Vprincipal_name\*O [\*Vunix_number\*O] [\*L-f \*Vfullname\*O] [\*L-al\*O] [\*L-q\*O \*Vquota\*O]] .br \*La\*O[\*Ldd\*O] [\*Vgroup_name\*O [\*Vunix_number\*O] [\*L-f \*Vfullname\*O [\*L-nl\*O]]] [\*L-al\*O] ls .br \*La\*O[\*Ldd\*O] [\*Vorganization_name\*O [\*Vunix_number\*O] [\*L-f \*Vfullname\*O]] .zZ "def,6220,R1.0.2,group aliases added" .zZ "def,4718,R1.0.2,unix_number optional" .zZ "def,4718,R1.0.2,add -f to syntax" .sE .VL 1i .iX "\*Lrgy_edit\*O subcommands" "\*Ladd\*O" .iX "principals" "adding to registry" .iX "organizations" "adding to registry" .iX "groups" "adding to registry" Create a new name entry. .PP If you do not specify \*Vprincipal_name\*O, \*Vgroup_name\*O, or \*Vorganization-name\*O, the \*Ladd\*O subcommand prompts you for each field in the entry. If you are adding organizations, the command prompts you for policy information as well. If you specify only \*Vprincipal_name\*O, \*Vgroup_name\*O, or \*Vorganization_name\*O and no other arguments, the object's fullname defaults to "" (that is, blank), the object's UNIX number is assigned automatically, and the object's creation quota defaults to unlimited. .zA "def,6220,R1.0.2,group aliases added" .zA "def,4718,R1.0.2,clarify -al option" .PP Use the \*L-al\*O option to create an alias for an existing principal or group. No two principals or groups can have the same UNIX number, but a principal or group and all its aliases share the same UNIX number. The \*L-al\*O option creates an alias name for a principal or group and assigns the alias name the same UNIX number as the principal or group. .zZ "def,6220,R1.0.2,group aliases added" .zZ "def,4718,R1.0.2,clarify -al option" .PP The \*L-q\*O option specifies the principal's object creation quota, the total number of registry objects that can be created by the principal. If you do not specify this option, the object creation quota defaults to unlimited. .PP For groups, the \*L-nl\*O option indicates that the group is not to be included on project lists; omitting this option allows the group to appear on project lists. .PP .zA "def,6220,R1.0.2,group aliases added" .sS \*Lc\*O[\*Lhange\*O] [\*Vprincipal_name\*O [\*L-n\*O \*Vname\*O] [\*L-f\*O \*Vfullname\*O] [\*L-al\*O | \*L-pr\*O] [\*L-q\*O \*Vquota\*O]] .br \*Lc\*O[\*Lhange\*O] [\*Vgroup_name\*O [\*L-n\*O \*Vname\*O] [\*L-f\*O \*Vfullname\*O] [\*L-nl\*O | \*L-l\*O] ] [\*L-al\*O | \*L-pr\*O] .br \*Lc\*O[\*Lhange\*O] [\*Vorganization_name\*O [\*L-n\*O \*Vname\*O] [\*L-f\*O \*Vfullname\*O]] .sE .zZ "def,6220,R1.0.2,group aliases added" .PP .iX "\*Lrgy_edit\*O subcommands" "\*Lchange\*O" .iX "organizations" "changing registry information" .iX "groups" "changing registry information" Changes a principal, group, or organization. .PP Specify the entry to change with \*Vprincipal_name\*O, \*Vgroup_name\*O, or \*Vorganization_name\*O. If you do not specify a \*Vprincipal_name\*O, \*Vgroup_name\*O, or \*Vorganization_name\*O, the \*Lchange\*O subcommand prompts you for a name. If you do not specify any fields, the subcommand prompts you for each field in succession. To leave a field unchanged, press \*L\*O at the prompt. If you are changing organization entries in the interactive mode, the subcommand prompts you for policy information as well. .PP Use \*L-n\*O \*Vname\*O and \*L-f\*O \*Vfullname\*O, to specify a new primary name or fullname, respectively. .PP .zA "def,6220,R1.0.2,group aliases added" For principals and groups, the \*L-al\*O option changes a primary name into an alias, and the \*L-pr\*O option changes an alias into a primary name. This change can be made only from the command line, not in the interactive mode. .zZ "def,6220,R1.0.2,group aliases added" .PP The \*L-q\*O option specifies the total number of registry objects that can be created by the principal. .PP For group entries, the \*L-nl\*O option disallows the group from appearing in project lists, while the \*L-l\*O option allows the group to appear in project lists. .PP For organization entries, you can change policy information only in the interactive mode. .PP Changes to a principal name are reflected in membership lists that contain the principal name. For example, if the principal \*Lludwig\*O is a member of the group \*Lcomposers\*O and the principal name is changed to \*Llouis\*O, the membership list for \*Lcomposers\*O is automatically changed to include \*Llouis\*O but not \*Lludwig\*O. .PP .zA "def,4718,R1.0.2,reserved group statement deleted" For reserved names, you can change only \*Vfullname\*O. .zZ "def,4718,R1.0.2,reserved group statement deleted" .P .sS \*Lm\*O[\*Lember\*O] [\*Vgroup_name\*O | \*Vorganization_name\*O [\*L-a\*O \*Vmember_list\*O] [\*L-r\*O \*Vmember_list\*O] ] .sE .P Edits the membership list for a group or organization. .iX "\*Lrgy_edit\*O subcommands" "\*Lmember\*O" .iX "organizations" "adding members" .iX "groups" "adding members" .PP If you do not specify a group or organization, the \*Lmember\*O subcommand prompts you for names to add or remove. .PP To add names or aliases to a membership list, use the \*L-a\*O option followed by the names separated by commas. To delete names from a membership list, use the \*L-r\*O option followed by the names separated by commas. If you do not include either the \*L-a\*O or \*L-r\*O option on the command line, \*Lrgy_edit\*O prompts you for names to add or remove. .PP Removing names from the membership list for a group or organization has the side effect of deleting the login account for removed member (and, of course, eliminating any permissions granted as a result of the membership the next time the member's ticket-granting ticket is renewed). .zA "def,4718,R1.0.2,-p,-g,-o flags not used" .P .sS \*Ldel\*O[\*Lete\*O] \*Vname\*O .sE .zZ "def,4718,R1.0.2,-p,-g,-o flags not used" .P .iX "\*Lrgy_edit\*O subcommands" "\*Ldelete\*O" .iX "principals" "deleting" .iX "groups" "deleting" .iX "organizations" "deleting" Deletes a registry entry. .PP If you delete a principal, \*Lrgy_edit\*O deletes the principal's account. If you delete a group or organization, \*Lrgy_edit\*O deletes any accounts associated with the group or organization. You cannot delete reserved principals. .P .zA "def,6387,R1.0.2,clarify uuid and -u" .sS \*Ladopt\*O \*Vuuid\*L \*Vprincipal_name\*O [\*L-u \*Vunix_number\*O] [\*L -f \*Vfullname\*O] [\*L-q \*Vquota\*O] .br \*Ladopt\*O \*Vuuid\*L \*Vgroup_name\*O ...\" [\*L-u \*Vunix_number\*O] [\*L-f\*O \*Vfullname\*O] [\*L-nl\*O] .br \*Ladopt\*O \*Vuuid\*L \*Vorganization_name\*O ...\" [\*L-u \*Vunix_number\*O] [\*L-f \*Vfullname\*O] .sE .zA "def,4718,R1.0.2,option descriptions expanded" .zA "def,8675,R1.0.3,clarify adopt subcommand" .P .iX "\*Lrgy_edit\*O subcommands" "\*Ladopt\*O" .iX "orphans" "adopting" .iX "registry objects" "adopting" Creates a principal, group, or organization for the specified UUID. .PP The principal, group, or organization is created to adopt an orphan object. Orphans are registry objects that cannot be accessed because 1) they are owned by UUIDs that are not associated with a principal or group and 2) no other principal, group, or organization has access rights to the orphaned object. UUIDs are associated with all registry objects when the object is created. When the registry object is deleted, the association between the object and the UUID is also deleted. .PP The \*Vprincipal_name\*O, \*Vgroup_name\*O, or \*Vorganization_name\*O you specify must be unique in the registry as it must be when you create a principal, group, or organization using the \*Ladd\*O subcommand. Except for the manner in which it is created, the principal, group, or organization created by the \*Ladopt\*O subcommand is no different from any other principal, group, or organization. .PP .zA "def,9649,R1.1,correct uuid format" The \*Vuuid\*O option specifies the UUID number to be assigned to the principal, group, or organization. The UUID supplied must be the one that owns the orphaned object. Specify the \*Vuuid\*O in RPC print string format as 8 hexadecimal digits, a hyphen; 4 hexadecimal digits, a hyphen; 4 hexadecimal digits, a hyphen; 4 hexadecimal digits, a hyphen; and 12 hexadecimal digits. The format follows: .P \*Ennnnnnnn\*O\*L-\*O\*Ennnn\*O\*L-\*O\*Ennnn\*O\*L-\*O\*Ennnn\*O\*L-\*O\*Ennnnnnnnnnnn\*O .PP .zZ "def,9649,R1.1,correct uuid format" For cell principals only, the \*L-u\*O option specifies the UNIX number to be associated with the cell name. If you do not enter this option, the next sequential UNIX number is supplied as a default. For all principals other than cells, the UNIX number is extracted from information embedded in the principal's UUID and cannot be specified here. .zZ "def,8675,R1.0.3,clarify adopt subcommand" .zZ "def,6387,R1.0.2,clarify uuid and -u" .PP For principals, the \*L-q\*O option specifies the principal's object creation quota. If you do not enter the option, the object creation quota is set to ''unlimited.'' .PP For groups, the \*L-nl\*O option turns off the project list inclusion property so that groups are not included in project lists. If you do not enter this option, the group is included in project lists. .PP For principals, groups, and organizations, the \*L-f\*O option supplies the object's fullname. If you do not enter the \*L-f\*O option, fullname defaults to blank. .PP An error occurs if you specify a name or UNIX number that is already defined within the same domain of the database. .LE .PP .zA "def,8675,R1.0.3,clarify adopt subcommand" Note that in the current implementation of the DCE, UNIX numbers are embedded in UUID numbers. If you try to create a group or organization to adopt an orphaned object and fail, it could be because the embedded UNIX number is invalid because it does not fall within the range of valid UNIX numbers set for the cell as a registry property. If this is the case, you must reset the range of valid UNIX numbers to include the UNIX number embedded in the UUID and then try again to adopt the object. .zZ "def,8675,R1.0.3,clarify adopt subcommand" .PP .zZ "def,4718,R1.0.2,option descriptions expanded" .SS "Account Subcommands" .P .zA "def,4718,R1.0.2,syntax clarified" .sS \*Lv\*O[\*Liew\*O] [\*Vpname\*O [\*Vgname\*O [\*Voname\*O]]] [\*L-f\*O] .sE .zZ "def,4718,R1.0.2,syntax clarified" .P .iX "-[" "accounts" "viewing registry information" .iX "-[" "\*Lrgy_edit\*O subcommands" "\*Lview\*O" Displays login accounts. .PP Without the \*L-f\*O option, \*Lview\*O displays only the user fields in each account entry. These fields include each account's .ML .LI Principal, group, and organization name .LI Encrypted password .LI Miscellaneous information .LI Home directory .LI Login shell .LE .PP With \*L-f\*O, \*Lview\*O displays the full entry, including the administrative fields as well as the user fields. Administrative information includes: .ML .LI Who created the account .LI When the account was created .LI Who last changed the account .LI When the account was last changed .LI When the account expires .LI Whether the account is valid .LI Whether the account principal's password is valid .LI When the account principal's password was last changed .LE .P .zA "def,4718,R1.0.2,syntax clarified" .sS \*La[dd] [\*Vpname\*O [\*L-g \*Vgname \*L-o \*Voname\*O \*L-mp\*O \*Vpassword\*O {\*L-rp | -pw\*O \*Vpassword\*O} .br [\*L-m\*O \*Vmisc\*O] [\*L-h\*O \*Vhomedir\*O] [\*L-s\*O \*Vshell\*O] .br [\*L-pnv | -pv\*O] [\*L-x\*O \*Vaccount_exp\*O | \*Lnone\*O] [\*L-anv | -av\*O] .br [ [\*L-ena[ble] \*Voption\*O | \*L-dis[able] \*Voption\*O]...] .br [\*L-gs\*O \*Vdate_and_time\*O] [\*L-mcr\*O \*Vlifespan\*O] [\*L-mcl\*O \*Vlifespan\*O]]] .sE .zZ "def,4718,R1.0.2,syntax clarified" .P Creates a login account. .PP If you enter the subcommand only or the subcommand and the optional \*Vpname\*O argument (principal name), \*Lrgy_edit\*O prompts you for all information. If you enter the subcommand, the \*Vpname\*O argument, and the \*Vgname\*O (group name) argument or the the \*Vpname\*O, \*Vgname\*O and \*Voname\*O (organization name) arguments, you must also enter the \*L-mp\*O, and \*L-pw\*O or \*L-rp\*O options. All other options are optional. .PP The \*Vpname\*O argument specifies the principal for whom the account should be created. The \*L-g\*O and \*L-o\*O options specify the account's group and organization. If the principal specified in \*Vpname\*O is not already a member of the specified group and organization, \*Lrgy_edit\*O automatically attempts to add the principal to the membership lists. If you do not have the appropriate permissions for the group and organization, the attempt will fail and the account will not be created. .PP The \*L-rp\*O option generates a random password for the account. The primary use of this option is to create passwords for accounts that will not be logged into (since the random password can never be supplied.) The \*L-pw\*O option is used to supply a password for the account on the command line. .PP If you use the \*L-rp\*O option or the \*L-pw\*O option, you must also use the \*L-mp\*O option to supply your password so your identity can be validated. .PP If you do not specify the \*L-rp\*O option or the \*L-pw\*O option, \*Lrgy_edit\*O prompts for the account's password twice to ensure you did not make a typing mistake. Then it prompts for your password to verify your identity. .zA "enh,11658,R1.1,add generated password info for extended login" .PP If the user's password management policy allows the selection of generated passwords, specifying "*" as the argument to the \*L-pw\*O option or at the account's password prompt automatically generates a plaintext password. .PP If the user's password management policy \*Vrequires\*O the selection of generated passwords, specifying the \*L-pw\*O option is an error. \*Lrgy_edit\*O displays a generated password and then prompts for the password for confirmation. .zZ "enh,11658,R1.1, add generated password info for extended login" .zA "def,6125,R1.0.2,delete encrypted password entry" .zZ "def,6125,R1.0.2,delete encrypted password entry" The format of \*Vpassword\*O must adhere to the policy of the associated organization or the policy of the registry as a whole, whichever is more restrictive. .PP The information supplied with the \*L-m\*O option is used to create the GECOS field for the account in the \*L/etc/passwd\*O file. If you run the \*Lpasswd_export\*O command, this entry contains the concatenation of the principal's full name and the information specified with the \*L-m\*O option. .PP The \*L-h\*O option specifies the pathname of the principal's home directory. The default \*Vhomedir\*O is \*L/\*O. The \*L-s\*O option specifies the pathname of the principal's login shell. The default \*Vshell\*O is a null string. .PP The \*L-pnv\*O (password not valid) option specifies that the password has expired. .zA "def,7829,R1.0.3,expire policy is implementation dependent" Generally, users must change their passwords when the passwords expire. However, the policy to handle expired passwords and the mechanism by which users change their passwords are defined for each platform, usually through the login facility. The \*L-pv\*O option indicates the password is not expired (the default). .zZ "def,7829,R1.0.3,expire policy is implementation dependent" .PP The \*L-x\*O option sets an expiration date for the account in yy/mm/dd/hh/mm/ss format. The default is "none," meaning that the password will never expire. .PP .PP The \*L-anv\*O (account not valid) option specifies that the account is not currently valid for login. The \*L-av\*O option indicates the account is currently valid (the default). .PP The \*L-enable\*O and \*L-disable\*O options set or clear the following options: .ML .LI The \*Lc[lient]\*O option, if enabled, allows the principal to act as as a client and log in, acquire tickets, and be authenticated. If you disable \*Lclient\*O, the principal cannot act as a client. The default is enabled. .LI The \*Ls[erver]\*O option, if enabled, allows the principal to act as a server and engage in authenticated communication. If you disable \*Lserver\*O, the principal cannot act as a server that engages in authenticated communication. The default is enabled. .LI The \*Lpo[stdated]\*O option, if enabled, allows tickets with a start time some time in the future to be issued to the account's principal. The default is disabled. .LI The \*Lf[orwardable]\*O option, if enabled, allows a new ticket-granting ticket with a network address that differs from the present ticket-granting ticket address to be issued to the account's principal. The default is enabled. .zA "def,4718,R1.0.2,default is disabled" .LI The \*Lpr[oxiable]\*O option, if enabled, allows a new ticket with a different network address than the present ticket to be issued to the account's principal. The default is disabled. .zZ "def,4718,R1.0.2,default is disabled" .zA "def,8134,R1.0.2A,description corrected" .LI The \*LT[GT_authentication]\*O option, if enabled, specifies that tickets issued to the account's principal can use the ticket-granting-ticket authentication mechanism. The default is enabled. .zZ "def,8134,R1.0.2A,description corrected" .LI The \*Lr[enewable]\*O option .zA "def,8334,renewable tickets not available" turns on the Kerberos V5 renewable ticket feature. This feature is not currently used by the DCE; any use of this option is unsupported at the present time. .zZ "def,8334,renewable tickets not available" ...\" , if enabled, allows tickets issued to the ...\" principal's ticket-granting ticket to be renewed. If this option is enabled, the DCE Security Service ...\" allows the principal's ticket-granting ticket to be renewed for as long as its ...\" lifetime is valid. The default is enabled. .LI The \*Ldup[_session_key]\*O option allows tickets issued to the account's principal to have duplicate keys. The default is disabled. .LE .PP The \*L-gs\*O (good since date) is the date and time the account was last known to be valid. When accounts are created, this date is set to the account creation time. If you change the good since date, any tickets issued before the changed date are invalid. Enter the date in yy/mm/dd.hh:mm format. .PP The \*L-mcr\*O (maximum certificate renewable) option is the number of hours before a session with the principal's identity expires and the principal must log in again to reauthenticate. The default is 4 weeks. .PP The \*L-mcl\*O (maximum certificate lifetime) option is the number of hours before the Authentication Service must renew a principal's service certificates. This is handled automatically and requires no action on the part of the principal. The default is 1 day. .P .zA "def,4718,R1.0.2,syntax clarified" .sS \*Lc\*O[\*Lhange\*O] [\*L-p\*O \*Vpname\*O] [\*L-g\*O \*Vgname\*O] [\*L-o\*O \*Voname\*O] .br [\*L-np\*O \*Vpname\*O] [\*L-ng\*O \*Vgname\*O] [\*L-no\*O \*Voname\*O] .br [{\*L-rp | -pw\*O \*Vpassword\*O} \*L-mp\*O \*Vpassword\*O] .br [\*L-m\*O \*Vmisc\*O] [\*L-h\*O \*Vhomedir\*O] [\*L-s\*O \*Vshell\*O] .br [\*L-pnv | -pv\*O] [\*L-x\*O \*Vaccount_exp\*O | \*Lnone\*O] [\*L-anv | -av\*O] .br [[\*L-ena[ble] \*Voption\*O | \*L-dis[able] \*Voption\*O]...] .br [\*L-gs\*O \*Vdate_and_time\*O] [\*L-mcr\*O \*Vlifespan\*O] [\*L-mcl\*O \*Vlifespan\*O] .sE .zZ "def,4718,R1.0.2,syntax clarified" .P Changes an account. .PP The \*L-p\*O, \*L-g\*O, and \*L-o\*O options identify the account to change. The \*L-np\*O, \*L-ng\*O, and \*L-no\*O options change the account's, principal, group, and organization, respectively. .zA "def,4718,R1.0.2,wildcarding added" .PP If you do not specify all three \*L-p\*O, \*L-g\*O, and \*L-o\*O options, wildcard updates can occur. For example, if you specify only the \*L-g\*O option, the changes affect all accounts that are associated with the named group. Note that you cannot use wildcarding to change passwords. .zZ "def,4718,R1.0.2,wildcarding added" .zA "def,6133,R1.0.2,must enter -p,-g,-o" To change a password, you must enter the \*L-p\*O, \*L-g\*O, and \*L-o\*O options. .zZ "def,6133,R1.0.2,must enter -p,-g,-o" .PP All other options have the same meaning as described in the \*Ladd\*O command for accounts. Note that the \*L-rp\*O option can be used to change the random passwords of the reserved accounts created by \*Lsec_create_db\*O when the registry database is created. .P .sS \*Ldel\*O[\*Lete\*O]\*O \*L-p\*O \*Vpname\*O [\*L-g\*O \*Vgname\*O] [\*L-o\*O \*Voname\*O] .sE .P Deletes the specified account. .PP Enter the \*L-p\*O option to delete the specified principal's account. Enter the \*L-g\*O or \*L-o\*O option to delete accounts associated with the specified group or organization. If you enter the \*L-g\*O or \*L-o\*O option, \*Lrgy_edit\*O prompts individually for whether to delete each account associated with the group or organization. .P .zA "def,6474,R1.0.2,delete -m option" .zA "def,4718,R1.0.2,-q option added" .sS \*Lce[ll] \*Vcellname\*O [\*L-ul\*O \*Vunix_num\*O] [\*L-uf\*O \*Vunix_num\*O] [\*L-gl\*O \*Vgname\*O] [-\*Lol\*O \*Voname\*O] .br [-\*Lgf\*O \*Vgname\*O] [\*L-of\*O \*Voname\*O] [\*L-mp\*O \*Vpasswd\*O] .br [\*L-fa\*O \*Vname\*O] \*L[-fp\*O \*Vpasswd\*O] .br [\*L-q\*V quota\*O] [\*L-x\*O \*Vaccount_expiration_date\*O | \*Lnone\*O] .sE .zZ "def,6474,R1.0.2,delete -m option" .zZ "def,4718,R1.0.2,-q option added" .P Creates a cross-cell authentication account in the local and foreign cells. .P This account allows local principals to access objects in the foreign cell as authenticated users and vice versa. The administrator in the foreign cell must have also set up a standard account, whose ID and password the administrator of the foreign cell must supply to you. .PP .zA "def,4718,R1.0.2,cellname description enhanced" The \*Vcellname\*O variable specifies the full pathname of the foreign cell with which you will establish the cross-cell authentication account. This name is stripped of the path qualifier and prefixed with "krbtgt." The resulting name is used as the primary name for the cross-cell authentication account. For example, if you enter /.../dresden.com, the principal name is krbtgt/dresden.com. .zZ "def,4718,R1.0.2,cellname description enhanced" .PP The \*L-ul\*O option specifies the UNIX number for the local cell's principal. The \*L-uf\*O option specifies the UNIX number for the foreign cell's principal. If you do not specify these UNIX numbers, they are generated automatically. .PP The \*L-gl\*O and \*L-ol\*O options specify the local account's group and organization. The \*L-gf\*O and \*L-of\*O options specify the foreign account's group and organization. .PP The \*L-mp\*O option specifies the password of the person who invoked \*Lrgy_edit\*O. .PP The \*L-fa\*O option specifies the name identifying the account in the foreign cell, and the \*L-fp\*O option specifies the account's password. .PP .zA "def,6474,R1.0.2,delete -m option" .zZ "def,6474,R1.0.2,delete -m option" .zA "def,4718,R1.0.2,-q option added" .PP The \*L-q\*O option specifies the total number of objects that can be created in your cell's registry by all foreign users who use the cross-cell authentication account to access your cell. The object creation quota defaults to 0 (zero), meaning that principals in the foreign cell cannot create objects in the local cell. The object creation quota set for your cell's account in the foreign cell places the same restriction on the number of objects that your cell's principals can create in the foreign cell's registry. .zZ "def,4718,R1.0.2,-q option added" .PP The \*L-x\*O option specifies the account expiration date for both the local and foreign accounts. The default for this option is "none." .PP Note that the object creation quota for the local account defaults to 0 (zero), meaning that principals in the foreign cell cannot create objects in the local cell. You can change this with the \*Lrgy_edit change\*O subcommand. .iX "-]" "accounts" "viewing registry information" .iX "-]" "\*Lrgy_edit\*O subcommands" "\*Lview\*O" .LE .SS "Key Management Subcommands" .PP .iX "-[" "passwords" "managing server" The key management subcommands must be run in command-line mode. .PP .sS \*Lkta[dd] \*L-p\*o \*Vprincipal_name\*O [\*L-pw\*O \*Vpassword\*O] [\*L-a[uto]] [-r[egistry]] [-f\*O \*Vkeyfile\*O] .sE .iX "-[" "\*Lrgy_edit\*O subcommands" "\*Lktadd\*O" Creates a password for a server or machine in the keytab file on the local node. .PP The \*L-p\*O option specifies the name of the server or machine principal for which you are creating a password. .PP The \*L-pw\*O option lets you supply the password on the command line. If you do not enter this option or the \*L-auto\*O option, \*Lktadd\*O prompts for the password. .PP .zA "def,6643,R1.0.2,clarify -r option" The \*L-a\*O option generates the password randomly. If you use this option, you must also use the \*L\-r\*O option. If you do not specify the \*L-auto\*O or the \*L-pw\*O option, you are prompted for a password. .PP The \*L-r\*O option updates the principal's password in the registry to match the string you enter (or automatically generate) for the password in the keytab file. Use it to ensure that the principal's password in the registry and the keytab file are in synch when you change a principal's password in the keytab file. To use this option, a password for the principal must exist in the default keytab file or the keytab file named by the \*L-f\*O option. .zZ "def,6643,R1.0.2,clarify -r option" .PP The \*L-f\*O option specifies the name of the server keytab file on the local node to which you are adding the password. If you do not specify a keytab file name, \*L/krb5/v5srvtab\*O is used. Note that you must be root to add entries in the default keytab file. .iX "-]" "\*Lrgy_edit\*O subcommands" "\*Lktadd\*O" .P .sS \*Lktl[ist] [\*L-p\*O \*Vprincipal_name\*O] [\*L-f\*O \*Vkeyfile\*O] .sE .P .iX "\*Lrgy_edit\*O subcommands" "\*Lktlist\*O" Displays principal names and password version numbers in the local keytab file. .PP The \*L-p\*O option specifies the name of the server or machine principal for which you are displaying passwords. .PP The \*L-f\*O option specifies the name of the server keytab file on the local node for which you want to display entries. If you do not specify a keytab file name, \*L/krb5/v5srvtab\*O is used. .P .sS \*Lktd[elete] \*L-p\*o \*Vprincipal_name\*O \*L-v\*O \*Vversion_number\*O [\*L-f\*O \*Vkeyfile\*O] .sE .P .iX "\*Lrgy_edit\*O subcommands" "\*Lktdelete\*O" Deletes a sever or machine principal's password entry from a keytab file. .PP The \*L-p\*O option specifies the name of the server or machine principal for whom you are deleting a password entry. .PP The \*L-v\*O option specifies the version number of the password you want to delete. Version numbers are assigned to a principal's password whenever the principal's password is changed. This allows any servers or machines still using tickets granted under the old password to run without interruption until the ticket expires naturally. .PP The \*L-f\*O option specifies the name of the server keytab file on the local node from which you want to delete passwords. If you do not specify a keytab file name, \*L/krb5/v5srvtab\*O is used. Note that you must be root to delete entries in the default keytab file. You must have the appropriate access rights to delete entries in other keytab files. .iX "-]" "passwords" "managing server" .SS "Miscellaneous Commands" .P .sS \*Ldo\*O[\*Lmain\*O] [\*Lp\*O | \*Lg\*O | \*Lo\*O | \*La\*O] .sE .P .iX "\*Lrgy_edit\*O subcommands" "\*Ldomain\*O" Changes or displays the type of registry information being viewed or edited. .PP You can specify \*Lp\*O for principals, \*Lg\*O for groups, \*Lo\*O for organizations, or \*La\*O for accounts. If you supply no argument, \*Lrgy_edit\*O displays the current domain. .P .zA "def,4718,R1.0.2,-q option removed" .zA "def,6125,R1.0.2,abbreviation is si" .sS \*Lsi\*O[\*Lte\*O] [[\*Vname\*O]] [\*L-u\*O[\*Lpdate\*O]] .sE .zZ "def,6125,R1.0.2,abbreviation is si" .P .iX "\*Lrgy_edit\*O subcommands" "\*Lsite\*O" Changes or displays the registry site being viewed or edited. .PP The \*Vname\*O variable is the fully qualified name of the cell that contains the registry to which you want access. If you supply no argument, \*Lrgy_edit\*O displays the current site. .PP The \*L-update\*O option indicates you want to talk to an update site in the specified cell. .zZ "def,4718,R1.0.2,-q option removed" .sS \*Lprop\*O[\*Lerties\*O] .sE .iX "\*Lrgy_edit\*O subcommands" "\*Lproperties\*O" Changes or displays registry properties. .PP This command prompts you for changes. Press \*L\*O to leave information unchanged. .P .zA "def,4718,R1.0.2,add command-line options" .sS \*Lpo\*O[\*Llicy\*O] [\*Vorganization_name\*O] [\*L-al \*Vlifespan\*O | \*Lforever\*O] [\*L-pl \*Vpasswd_lifespan\*O | \*Lforever\*O] .br [\*L-px \*Vpasswd_exp_date\*O | none\*O] [\*L-pm \*Vpasswd_min_length\*O] [\*L-pa \*O| \*L-pna\*O] [\*L-ps \*O| \*L-pns\*O] .sE .PP .iX "\*Lrgy_edit\*O subcommands" "\*Lpolicy\*O" Changes or displays registry standard policy or the policy for an organization. .PP Enter \*Vorganization_name\*O to display or change policy for that specific organization. If you do not enter \*Vorganization_name\*O the subcommand affects standard policy for the entire registry. .PP The \*L-al\*O option determines the account's lifespan, the period during which accounts are valid. After this period of time passes, the accounts become invalid and must be recreated. An account's lifespan is also controlled by the \*Ladd\*O and \*Lchange\*O subcommands \*L-x\*O option. If the two lifespans conflict, the shorter one is used. Enter the \*Vlifespan\*O in the following in the following format: .sp .4v \*Vweeks\*Lw\*Vdays\*Ld\*Vhours\*Lh\*Vminutes\*Lm\*O .sp .4v .PP For example, 4 weeks and 5 days is entered as \*C4w5d\*O. .PP If you enter only a number and no weeks, days, or hours designation, the designation defaults to hours. If you end the lifepan with an number and no weeks, days, or hours designation, the number with no designation defaults to seconds. For example, 12w30 is assumed to be 12 weeks thirty seconds. .PP The \*L-pl\*O option determines the password lifespan, the period of time before account's password expires. .zA "def,7829,R1.0.3,expire policy is implementation dependent" Generally, users must change their passwords when the passwords expire. However, the policy to handle expired passwords and the mechanism by which users change their passwords are defined for each platform, usually through the login facility. .PP Enter \*Vpasswd_lifespan\*O as a number indicating the number of days. If you define a password lifespan as \*Lforever\*O, the password has an unlimited lifespan. .PP The \*L-px\*O option specifies the password expiration date in yy/mm/dd/hh.mm:ss format. Generally, users must change their passwords when the passwords expire. However, the policy to handle expired passwords and the mechanism by which users change their passwords are defined for each platform, usually through the login facility. .zZ "def,7829,R1.0.3,expire policy is implementation dependent" .PP .zA "def,10450,R1.1,forever to none" If you define a password expiration date as \*Lnone\*O, the password has an unlimited lifespan. .zZ "def,10450,R1.1,forever to n .PP The \*L-pm\*O, \*L-ps\*O, \*L-pns\*O, \*L-pa\*O, and \*L-pna\*O options all control the format of passwords as follows: .ML .LI \*L-pm\*O \(em Specifies the minimum length of passwords in characters. If you enter 0, no password minimum length is in effect. .LI \*L-ps\*O and \*L-pns\*O \(em Specify whether passwords can contain all spaces (\*L-ps\*O) or can not be all spaces (\*L-pns\*O). .LI \*L-pa\*O and \*L-pna\*O \(em Specify whether passwords can consist of all alphanumeric characters (\*L-pn\*O) or must include some non-alphanumeric characters (\*L-pna\*O). .LE .zZ "def,4718,R1.0.2,add command-line options" .P .zA "def,8649,R1.0.3,del extra policy cmd descrip" .zZ "def,8649,R1.0.3,del extra policy cmd descrip" .P .sS \*Lau\*O[\*Lth_policy\*O] .sE .P .iX "\*Lrgy_edit\*O subcommands" "\*Lauthpolicy\*O" Changes and/or displays registry authentication policies. .PP This command prompts you for changes. Press \*L\*O to leave information unchanged. .P .sS \*Ldef\*O[\*Laults\*O] .sE .P .iX "\*Lrgy_edit\*O subcommands" "\*Ldefaults\*O" Changes or displays the home directory, login shell, password valid option, account expiration date, and account valid option default values that \*Lrgy_edit\*O uses. .P This command first displays the current defaults. It then prompts you for whether or not you want to make changes. If you make changes, \*Ldefaults\*O immediately changes the defaults for the current session, and it saves the new defaults in \*L~/.rgy_editrc\*O. The newly saved defaults are used until you change them. .P .sS \*Lh\*O[\*Lelp\*O] [\*Vcommand\*O .sE .P .iX "\*Lrgy_edit\*O subcommands" "\*Lhelp\*O" Displays usage information for \*Lrgy_edit\*O. .PP If you do not specify a particular command, \*Lrgy_edit\*O lists the available commands. .P .sS \*Lq\*O[\*Luit\*O] .sE .P .iX "\*Lrgy_edit\*O subcommands" "\*Lquit\*O" Exit \*Lrgy_edit\*O. .P .sS \*Le\*O[\*Lxit\*O] .sE .P .iX "\*Lrgy_edit\*O subcommands" "\*Lexit\*O" Exit \*Lrgy_edit\*O. .P .sS \*Ll[ogin]\*O .sE .zA "def,4718,R1.0.2,description changed" .P .iX "\*Lrgy_edit\*O subcommands" "\*Llogin\*O" Lets you establish a new network identity for use during the \*Lrgy_edit\*O session. .zZ "def,4718,R1.0.2,description changed" .P The \*Lrgy_edit\*O login command prompts for a principal name and password. .P .sS \*Lsc[ope]\*O [\*Vname\*O] .sE .P .iX "\*Lrgy_edit\*O subcommands" "\*Lscope\*O" Limits the scope of the information displayed by the \*Lview\*O subcommand to the directory (specified by \*Vname\*O) in the registry database. .P .SS Commands for the Local Registry .PP .iX "-[" "registry" "maintaining local" To edit or view the local registry, invoke \*Lrgy_edit\*O with the \*L-l\*O option while you are logged into the machine whose local registry you want to maintain. This section lists the commands that are valid for editing or viewing the local registry. When you invoke \*Lrgy_edit\*O with the \*L-l\*O option, only the subcommands and options listed here can be used. .P .sS \*Lv\*O[\*Liew\*O] .sE .P .iX "\*Lrgy_edit\*O subcommands" "\*Lview\*O" Displays local registry entries. .P .sS \*Ldel\*O[\*Lete\*O]\*O \*Vprincipal_name\*O .sE .P .iX "\*Lrgy_edit\*O subcommands" "\*Ldelete\*O" Deletes the account and credential information for \*Vprincipal_name\*O from the local registry. .P .zA "def,4718,R1.0.2,expanded purge description" .sS \*Lpu[rge]\*O .sE .P .iX "\*Lrgy_edit\*O subcommands" "\*Lpurge\*O" Purges expired local registry entries. .P .zA "def,9125,R1.0.3,not options typo" This command has no options or arguments. .zZ "def,9125,R1.0.3,not options typo" .P The time limit, or lifespan, for which an entry in the local registry is valid is set as a property of the local registry with the \*Lproperties\*O subcommand. When the \*Lpurge\*O subcommand is run, it deletes all expired entries. The lifespan begins when an entry for the principal is added to the local registry (that is, the beginning of the lifespan is the last time the principal logged in to the local machine.) The lifespan ends after the time limit set as a local registry property. .P .zZ "def,4718,R1.0.2,expanded purge description" .zA "def,4718,R1.0.2,expanded properties description" .sS \*Lpr[operties\*O] .sE .P .iX "\*Lrgy_edit\*O subcommands" "\*Lproperties\*O" Changes and/or displays local registry properties and policies. .P This command displays the current properties and then prompts for whether you want to make changes to them. You can change the local registry's: .ML .LI Capacity \(em A number representing the total number of entries the local registry can contain at any one time. When the capacity is reached, subsequent new entries overwrite the oldest entries. .LI Account lifespan \(em The time in which an account in the local registry is valid in the following format: .sp .4v \*Vweeks\*Lw\*Vdays\*Ld\*Vhours\*Lh\*Vminutes\*Lm\*O .sp .4v .PP For example, 4 weeks and 5 days is entered as \*C4w5d\*O. .PP If you enter only a number and no weeks, days, or hours designation, the designation defaults to hours. If you end the lifepan with an number and no weeks, days, or hours designation, the number with no designation defaults to seconds. For example, 12w30 is assumed to be 12 weeks thirty seconds. .LE ...\" .P .zZ "def,4718,R1.0.2,expanded properties description" .iX "-]" "registry" "maintaining local" .\" $Header: ripquery.1m,v 72.5 94/12/09 15:06:37 ssa Exp $ .TA r .TH ripquery 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ripquery \- query RIP gateways .SH SYNOPSIS .C ripquery .RC [ "\-1 " ] .RC [ " \-2 " ] .RC [ " \-a" .IR "authkey" ] .RC [ " \-n " ] .RC [ " \-p " ] .RC [ " \-r " ] .RC [ " \-v " ] .RC [ " \-w" .IR "time " ] .I gateway \&.\|.\|. .SH DESCRIPTION .CR ripquery is used to request all routes known by a RIP gateway by sending a RIP request or POLL command. The routing information in any routing packets returned is displayed numerically and symbolically. .CR ripquery is intended to be used as a tool for debugging gateways, not for network management. SNMP is the preferred protocol for network management. .PP .CR ripquery by default uses the RIP POLL command, which is an undocumented extension to the RIP specification supported by .CR routed on SunOS 3.x and later and by .CR gated 1.4 and later. The RIP POLL command is preferred over the RIP REQUEST command because it is not subject to Split Horizon and/or Poisoned Reverse. See the RIP RFC for more information. .SH OPTIONS .TP 8 .C -1 Send the query as a version 1 packet. .TP .C -2 Send the query as a version 2 packet (default). .TP .C -a Specifies the authentication password to use for queries. If specified, an authentication type of SIMPLE will be used, otherwise the default is an authentication type of NONE. Authentication fields in incoming packets will be displayed, but not validated. .TP .C -n Prevents the address of the responding host from being looked up to determine the symbolic name. .TP .C -p Uses the RIP POLL command to request information from the routing table. This is the default, but is an undocumented extension supported only by some versions of SunOS 3.x and later versions of .CR gated . If there is no response to the RIP POLL command, the RIP REQUEST command is tried. .CR gated responds to a POLL command with all the routes learned via RIP. .TP .C -r Used the RIP REQUEST command to request information from the gateway's routing table. Unlike the RIP POLL command, all gateways should support the RIP REQUEST. If there is no response to the RIP REQUEST command, the RIP POLL command is tried. .CR gated responds to a REQUEST command with all the routes he announces out the specified interface. Due to limitations in the UDP interface, on systems based on BSD 4.3 Reno or earlier, REQUESTs respond about the interface used to route packets back to the sender. This can be avoided by running .CR ripquery on the host being queried. .TP .C -v Version information about .CR ripquery is displayed before querying the gateways. .TP .C -w Specifies the time in seconds to wait for the initial response from a gateway. The default value is 5 seconds. .SH AUTHOR .CR ripquery and associated documentation is Copyright 1990, 1991, 1992, 1993 by Cornell University. .SH "SEE ALSO" gated(1m), gated.config(4), gdc(1m). .br .nf RFC1058 - Routing Information Protocol .fi .SH BUGS Some versions of UNIX do not allow looking up the symbolic name of a subnet. .\" ------------------------------------------------------------------------ .\" .\" GateD, Release 3 .\" .\" Copyright (c) 1990,1991,1992,1993 by Cornell University. .\" .\" THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT .\" LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY .\" AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" Royalty-free licenses to redistribute GateD Release .\" 3 in whole or in part may be obtained by writing to: .\" .\" GateDaemon Project .\" Information Technologies/Network Resources .\" 200 CCC, Garden Avenue .\" Cornell University .\" Ithaca, NY 14853-2601 USA .\" .\" GateD is based on Kirton's EGP, UC Berkeley's routing .\" daemon (routed), and DCN's HELLO routing Protocol. .\" Development of GateD has been supported in part by the .\" National Science Foundation. .\" .\" Please forward bug fixes, enhancements and questions to the .\" gated mailing list: gated-people@gated.cornell.edu. .\" .\" Authors: .\" .\" Jeffrey C Honig .\" Scott W Brim .\" .\" ------------------------------------------------------------------------ .\" .\" Portions of this software may fall under the following .\" copyrights: .\" .\" Copyright (c) 1988 Regents of the University of California. .\" .\" Redistribution and use in source and binary forms are .\" permitted provided that the above copyright notice and .\" this paragraph are duplicated in all such forms and that .\" any documentation, advertising materials, and other .\" materials related to such distribution and use .\" acknowledge that the software was developed by the .\" University of California, Berkeley. The name of the .\" University may not be used to endorse or promote .\" products derived from this software without specific .\" prior written permission. THIS SOFTWARE IS PROVIDED .\" ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, .\" INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" index@\f4ripquery\f1 \- query RIP gateways@@@\f3ripquery(1M)\f1 .\" index@\f1query \s-1RIP\s+1 gateways@@@\f3ripquery(1M)\f1 .\" index@\f1RIP gateways, query@@@\f3ripquery(1M)\f1 .\" index@\f1gateways, query RIP@@@\f3ripquery(1M)\f1 .\" .\" toc@\f3ripquery(1M)\f1:\0\0\f4ripquery\f1@@@query RIP gateways .\" .\" fileset_database@ripquery.1m INETSVCS-MAN .\" $Header: rlogind.1m,v 78.3 96/04/06 17:51:17 ssa Exp $ .TA r .TH rlogind 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rlogind \- remote login server .SH SYNOPSIS .C /usr/lbin/rlogind .RC [ \|\-ln\| ] .RC [ -B .IR bannerfile\| ] .SH DESCRIPTION .CR rlogind is the server for the .IR rlogin (1) program. It provides a remote login facility with authentication based on privileged port numbers. .CR rlogind expects to be executed by the Internet daemon .RI ( inetd (1M)) when it receives a service request at the port indicated in the services database for .CR login using the .CR tcp protocol (see .IR services (4)). .PP When a service request is received, the following protocol is initiated by .CR rlogind : .RS .TP 4 1. .CR rlogind checks the client's source port. If the port is not in the range 512 through 1023 (a ``privileged port''), the server aborts the connection. .TP 2. .CR rlogind checks the client's source address and requests the corresponding host name (see .IR gethostent (3N), .IR hosts (4), and .IR named (1M)). If it cannot determine the hostname, it uses the Internet dot-notation representation of the host address. .RE .PP Once the source port and address have been checked, .CR rlogind proceeds with the authentication process described in .IR hosts.equiv (4). .CR rlogind then allocates a STREAMS based pseudo-terminal (see .IR ptm (7), .IR pts (7)), and manipulates file descriptors so that the slave half of the pseudo-terminal becomes .CR stdin , .CR stdout , and .CR stderr for a login process. The login process is an instance of .IR login (1) invoked with the .CR \-f option if authentication has succeeded. If automatic authentication fails, .IR login (1) prompts the user with the normal login sequence. The .CR \-l option to .CR rlogind prevents any authentication based on the user's .CR .rhosts file unless the user is logging in as super-user. The .B \-B option to .I rlogind causes the file to be displayed to incoming rlogin requests. .PP The .CR rlogind process manipulates the master side of the pseudo-terminal, operating as an intermediary between the login process and the client instance of the .CR rlogin program. The protocol described in .IR ptm (7) and .IR pts (7) is used to enable and disable flow control via Ctrl-S/Ctrl-Q under the direction of the program running on the slave side of the pseudo-terminal, and to flush terminal output in response to interrupt signals. The login process sets the baud rate and .CR TERM environment variable to correspond to the client's baud rate and terminal type (see .IR environ (5)). .PP Transport-level keepalive messages are enabled unless the .CR \-n option is present. The use of keepalive messages allows sessions to be timed out if the client crashes or becomes unreachable. .PP To start .CR rlogind from the Internet daemon, the configuration file .CR /etc/inetd.conf must contain an entry as follows: .IP .C "login stream tcp nowait root /usr/lbin/rlogind rlogind" .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multibyte character code sets are supported. .SH DIAGNOSTICS Errors in establishing a connection cause an error message to be returned with a leading byte of 1 through the socket connection, after which the network connection is closed. Any errors generated by the login process or its descendents are passed through by the server as normal communication. .RS .TP .C "fork: No more processes" The server was unable to fork a process to handle the incoming connection. .IP .IR "Next step" : Wait a period of time and try again. If this message persists, the server's host may have runaway processes that are using all the entries in the process table. .TP .C "Cannot allocate pty on remote host" The server was unable to obtain a pseudo-terminal for use with the login process. Either all pseudo-terminals were in use, or the pty driver has not been properly set up. Note, the number of slave devices that can be allocated depends on NSTRPTY, a kernel tunable parameter. This can be changed via SAM (see .IR ptm (7), .IR pts (7)). .IP .IR "Next step" : Check the pty configuration of the host where .CR rlogind executes. .TP .C "Permission denied" The server denied access because the client was not using a reserved port. This should only happen to interlopers trying to break into the system. .PP .TP .C "/usr/bin/login: ..." The login program could not be started via .IR exec (2) for the reason indicated. .IP .IR "Next step" : Try to correct the condition causing the problem. If this message persists, contact your system administrator. .RE .SH WARNINGS The ``privileged port'' authentication procedure used here assumes the integrity of each host and the connecting medium. This is insecure, but is useful in an ``open'' environment. Note that any passwords are sent unencrypted through the socket connection. .SH AUTHOR .CR rlogind was developed by the University of California, Berkeley. .SH FILES .PD 0 .TP 33 .CR /etc/hosts.equiv List of equivalent hosts .TP .CR $HOME\s0/.rhosts User's private equivalence list .PD .SH SEE ALSO login(1), rlogin(1), inetd(1M), named(1M), gethostent(3N), ruserok(3N), hosts(4), hosts.equiv(4), inetd.conf(4), services(4), environ(5), pty(7). .\" index@\f4rlogind\f1 \- remote login server@@@\f3rlogind(1M)\f1 .\" index@\f1remote login server@@@\f3rlogind(1M)\f1 .\" index@\f1login server, remote@@@\f3rlogind(1M)\f1 .\" index@\f1server, remote login@@@\f3rlogind(1M)\f1 .\" .\" toc@\f3rlogind(1M)\f1:\0\0\f4rlogind\f1@@@remote login server .\" .\" fileset_database@rlogind.1m INETSVCS-MAN .\" $Header: rlp.1m,v 72.4 94/11/02 11:31:17 ssa Exp $ .TA r .TH rlp 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rlp \- send LP line printer request to a remote system .SH SYNOPSIS .C /usr/sbin/rlp .CI -I id .RC [ -C .IR class\| ] .RC [ -J .IR job\| ] .RC [ -T .IR title\| ] .RC [ -i\c .RI [ \|numcols\| ]\|] .RI [ -k\|font\| ] .RC [ -w .IR num\| ] .RC [ -cdfghlnptv ] .I file .SH DESCRIPTION .CR rlp transfers a spooling request to a remote system to be printed. .CR rlp communicates with a spooling daemon on a remote system to transfer the spooling request. Options can be set only on the original system. Transfers of a remote request use only the .CR -I option and the file. .PP This command is intended to be used only by the spool system in response to the .CR lp command and should not be invoked directly (see .IR lp (1)). .SS Options .CR rlp recognizes the following options and command-line arguments: .RS .TP 15 .CI -I id The argument .I id is the request ID. .TP .CI -C " class" Take the .I class argument as a job classification for use on the banner page. .TP .CI -J " job" Take the .I job argument as the job name to print on the banner page. Normally, the first file's name is used. .TP .CI -T " title" Use the .I title argument as the title used by .CR pr instead of the file name (see .IR pr (1)). .CR -T is ignored unless the .CR -p option is specified. .TP .C -h Suppress the printing of the banner page. .TP .CR -i [\f2numcols\fP] Cause the output to be indented. If the next argument is numeric, it is used as the number of blanks to be printed before each line; otherwise, 8 characters are printed. .TP .CI - kfont Specify a .I font to be mounted on font position .IR k , where .I k is from .CR 1 through .CR 4 . .TP .CI -w num Use the .I num argument number as the page width for .CR pr . .RE .PP The following single-letter options are used to notify the line printer spooler that the files are not standard text files. The spooling system uses the appropriate filters (if the option is supported) to print the data accordingly. These options are mutually exclusive. .RS .TP 12 .C -c The files are assumed to contain data produced by .IR cifplot . .TP .C -d The files are assumed to contain data from .I tex (DVI format). .TP .C -f Use a filter that interprets the first character of each line as a standard FORTRAN carriage control character. .TP .C -g The files are assumed to contain standard plot data as produced by the .CR plot routines. .TP .C -l Use a filter that suppresses page breaks. .TP .C -n The files are assumed to contain data from .CR ditroff (device-independent .CR troff ). .TP .C -p Use .CR pr to format the files. .TP .C -t The files are assumed to contain data from .CR troff (cat phototypesetter commands). .TP .C -v The files are assumed to contain a raster image for devices such as the Benson Varian. .RE .SH WARNINGS Some remote line printer models may not support all of these options. Options not supported are silently ignored. .PP When .CR rlp is transferring a request that originated on another system, only the .CR -I option and the file is used. This saves .CR rlp from having to set the various options multiple times. Specifying unused options does not produce an error. .SH AUTHOR .CR rlp was developed by the University of California, Berkeley and HP. .SH FILES .nf .C /etc/passwd .C /usr/sbin/rlpdaemon .C /var/spool/lp/* .C /var/adm/lp/* .C /etc/lp/* .C /usr/lib/lp/* .fi .SH SEE ALSO accept(1M), enable(1), lp(1), lpadmin(1M), lpsched(1M), lpstat(1), rcancel(1M), rlpdaemon(1M), rlpstat(1M). .\" .\" index@\f4rlp\f1 \- send LP line printer request to a remote system@@@\f3rlp(1M)\f1 .\" index@\f1send LP line printer request to a remote system@@@\f3rlp(1M)\f1 .\" index@\f1LP requests: send LP request to a remote system@@@\f3rlp(1M)\f1 .\" index@\f1remote system, send LP request to@@@\f3rlp(1M)\f1 .\" index@\f1system, send LP request to remote@@@\f3rlp(1M)\f1 .\" .\" toc@\f3rlp(1M)\f1:\0\0\f4rlp\f1@@@send LP line printer request to a remote system .\" .\" fileset_database@rlp.1m SYS-ADMIN-MAN .\" $Header: rlpdaemon.1m,v 72.2 94/09/21 16:14:50 ssa Exp $ .TA r .TH rlpdaemon 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rlpdaemon \- remote spooling line printer daemon, message write daemon .SH SYNOPSIS .C /usr/sbin/rlpdaemon .RC [ \|\-i\| ] .RC [ \|\-l\| ] .RC [ \|\-L .IR logfile\| ] .SH DESCRIPTION .CR rlpdaemon is a line printer daemon (spool area handler) for remote spool requests. .CR rlpdaemon is normally invoked at boot time from the .CR /sbin/rc file or started by .IR inetd (1M), when necessary. .CR rlpdaemon runs on a system that receives requests to be printed. .CR rlpdaemon transfers files to the spooling area, displays the queue, or removes jobs from the queue. .PP .CR rlpdaemon is also used as a server process to write a message on the user's terminal, upon receiving a request from a remote system. .SS Options .TP 12 .C \-i Prevent .CR rlpdaemon from remaining after a request is processed. This is required if .CR rlpdaemon is started from .IR inetd (1M). .TP .C \-l Cause .CR rlpdaemon to log error messages and valid requests received from the network to the file .CR /var/adm/lp/lpd.log . This can be useful for debugging. .TP .CI \-L " logfile" Change the file used for writing error conditions from the file .CR /var/adm/lp/lpd.log to .IR logfile . .PP When .CR rlpdaemon is started by .IR inetd (1M), access control is provided via the file .CR /var/adm/inetd.sec to allow or prevent a host from making requests. When .CR rlpdaemon is not started by .IR inetd (1M), all requests must come from one of the machines listed in the file .CR /etc/hosts.equiv or .CR /var/spool/lp/.rhosts . When .C /var/spool/lp/.rhosts is used for access, the user name should be .CR lp . .PP The following entry should exist in .CR /etc/services for remote spooling: .IP printer 515/tcp spooler .SH EXAMPLES .PP To start .CR rlpdaemon from .CR /sbin/rc , invoke the command: .IP .C /usr/sbin/rlpdaemon .PP To start .CR rlpdaemon from .CR inetd , the following line should be included in the file .CR /etc/inetd.conf : .IP .C "printer stream tcp nowait root /usr/sbin/rlpdaemon rlpdaemon -i" .SH WARNINGS If the remote system is the same as the local system and .CR rlpdaemon was not started by .IR inetd (1M), the local system name .I must be included in file .CR /etc/hosts.equiv . .SH AUTHOR .CR rlpdaemon was developed by the University of California, Berkeley and HP. .SH FILES .nf .C /etc/hosts.equiv .C /etc/services .C /var/spool/lp/* .C /var/adm/lp/* .C /etc/lp/* .C /usr/lib/lp/* .C /var/adm/inetd.sec .fi .SH SEE ALSO accept(1M), enable(1), lp(1), inetd(1M), lpadmin(1M), lpsched(1M), lpstat(1), rcancel(1M), rlp(1M), rlpdaemon(1M), rlpstat(1M). hosts.equiv(4), inetd.conf(4), inetd.sec(4), services(4). .br .I HP-UX System Administrator manuals .\" .\" index@\f4rlpdaemon\f1 \- line printer daemon for LP requests from remote systems@@@\f3rlpdaemon(1M)\f1 .\" index@\f1line printer daemon for LP requests from remote systems@@@\f3rlpdaemon(1M)\f1 .\" index@\f1printer daemon for LP requests from remote systems@@@\f3rlpdaemon(1M)\f1 .\" index@\f1daemon, line printer daemon for LP requests from remote systems@@@\f3rlpdaemon(1M)\f1 .\" index@\f1LP requests: daemon for LP requests from remote systems@@@\f3rlpdaemon(1M)\f1 .\" index@\f1remote systems, daemon for LP requests from@@@\f3rlpdaemon(1M)\f1 .\" .\" toc@\f3rlpdaemon(1M)\f1:\0\0\f4rlpdaemon\f1@@@line printer daemon for LP requests from remote systems .\" .\" fileset_database@rlpdaemon.1m SYS-ADMIN-MAN .\" $Header: rlpstat.1m,v 72.4 94/09/21 16:15:07 ssa Exp $ .TA r .TH rlpstat 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rlpstat \- print status of LP spooler requests on a remote system .SH SYNOPSIS .C /usr/sbin/rlpstat .RC [ -d .IR printer\| ] .RC [ -u .IR user\| ] .RI [ \|id \0...\|] .SH DESCRIPTION .CR rlpstat reports the status of the specified jobs or all requests associated with a user. If no arguments are specified, .CR rlpstat reports on any requests currently in the queue. .PP For each request submitted (i.e., each invocation of .CR lp \(em see .IR lp (1)) .CR rlpstat reports the request ID, user's name, total size of the request, date of the request, and, if it is being transferred, the device. .PP This command is intended to be used only by the spool system in response to the .CR lpstat command and should not be invoked directly (see .IR lpstat (1M)). .SS Options .CR rlpstat recognizes the following options and command-line arguments: .RS .TP 15 .CI -d \0printer Specify a particular printer. Otherwise, the default line printer is used (or the value of the .CR LPDEST environment variable). .TP .CI -u \0user Status is requested on all requests for the user who executed the .CR rlpstat command on the specified printer (see the .CR -d option). .TP .I id Status is requested on the specified request IDs (as returned by .CR lp ). All the request IDs must be for the same printer. .RE .SH AUTHOR .CR rlpstat was developed by the University of California, Berkeley, and HP. .SH FILES .nf .C /var/spool/lp/* .C /var/adm/lp/* .C /etc/lp/* .C /usr/lib/lp/* .fi .SH SEE ALSO enable(1), lp(1), lpadmin(1M), lpsched(1M), lpstat(1), rcancel(1M), rlp(1M), rlpdaemon(1M). .\" .\" index@\f4rlpstat\f1 \- print status of LP requests sent to remote system@@@\f3rlpstat(1M)\f1 .\" index@\f1LP requests: print status of requests sent to remote system for printing@@@\f3rlpstat(1M)\f1 .\" index@\f1requests, LP@@@see LP requests .\" index@\f1status: LP requests sent to remote system for printing@@@\f3rlpstat(1M)\f1 .\" .\" toc@\f3rlpstat(1M)\f1:\0\0\f4rlpstat\f1@@@print status of LP spooler requests on a remote system .\" .\" fileset_database@rlpstat.1m SYS-ADMIN-MAN .\" $Header: mkboot.1m,v 74.1 95/05/10 21:53:34 ssa Exp $ .TA m .TH mkboot 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mkboot, rmboot \- install, update or remove boot programs from disk .SH SYNOPSIS .C /usr/sbin/mkboot .RC \0[ -b .IR boot_file_path ] .RC \0\0[ -c .RC [ -u ] .RC | \0-f .RC | \0-h .RC | \0-u ] .ifn .br .RC \0\0[ -i .IR included_lif_file ] .ift .br .RC \0[ -p .IR preserved_lif_file ] .RC \0\0[ -l \0| .CR -H \0| .CR -W ] .RC [ -v ] .ifn .br .I \0\0device .PP .C /usr/sbin/mkboot .RC [ -a .IR auto_file_string\| ] .RC [ -v\| ] .I device .PP .C /usr/sbin/rmboot .I device .SH DESCRIPTION .CR mkboot is used to install or update boot programs on the specified device file. .PP The position on .I device at which boot programs are installed depends on the disk layout of the device. .CR mkboot examines .I device to discover the current layout and uses this as the default. If the disk is uninitialized, the default is LVM layout. The default can be overriden by the .CR -l, .CR -H or .CR -W options. .PP Boot programs are stored in the boot area in Logical Interchange Format (LIF), which is similar to a file system. For a device to be bootable, the LIF volume on that device must contain at least the .CR ISL (the initial system loader) and .CR HPUX (the HP-UX bootstrap utility) LIF files. If, in addition, the device is an LVM physical volume, the .CR LABEL file must be present (see .IR lvlnboot (1M) ). .SH Options .CR mkboot recognizes the following options: .RS .TP 24 .CI -a \0auto_file_string If the .CR -a option is specified, mkboot creates an autoexecute file .CR AUTO on .I device, if none exists. .CR mkboot deposits .I auto_file_string in that file. If this string contains spaces, it must be quoted so that it is a single parameter. .TP .CI -b \0boot_file_path If this option is given, boot programs in the pathname specified by .I boot_file_path are installed on the given device. .TP .C -c If this option is specified, .CR mkboot checks if the available space on .I device is sufficient for the boot programs. If the .CR -i option is also specified, .CR mkboot checks if each .I included_lif_file is present in the boot programs. If the .CR -p option is specified, it checks if each .I preserved_lif_file is present on the .I device. If all these checks succeed, .CR mkboot exits with a status code of 0. If any of these checks fail, .CR mkboot exits with a status code of 1. If the verbose option is also selected, a message is also displayed on the standard output. .TP .C -f This option forces the information contained in the boot programs to be placed on the specified .I device without regard to the current swapping status. Its intended use is to allow the boot area to grow without having to boot the system twice (see .CR -h option). .IP This option should only be used when the system is in the single user state. .IP This could be a dangerous operation because swap space that is already allocated and possibly in use will be overwritten by the new boot program information. A message is also displayed to the standard output stating that the operator should immediately reboot the system to avoid system corruption and to reflect new information on the running system. .IP A safer method for reapportioning space is to use the .CR -h option. .IP This option is valid only if .I device has the Whole Disk layout. .TP .C -h Specifying this option shrinks the available space allocated to swap in the LIF header by the amount required to allow the installation of the new boot programs specified by .I boot_file_path. .IP After the LIF header has been modified, reboot the system to reflect the new swap space on the running system. At this point, the new boot programs can be installed and the system rebooted again to reflect the new boot programs on the running system. This is the safe method for accomplishing the capability of the .CR -f option. .IP This option is valid only if .I device has the Whole Disk layout. .TP .C -H If this option is specified, .CR mkboot treats .I device to be a Hard Partition layout disk. This option cannot be used along with the .CR -l and .CR -W options. .TP .CI -i \0included_lif_file If the .CR -i option is specified one or more times, .CR mkboot copies each .I included_lif_file and ignores any other LIF files in the boot programs. The sole exceptions to this rule are the files .CR ISL and .CR HPUX , which are copied without regard to the .CR -i options. If .I included_lif_file is also specified with the .CR -p option, the .CR -i option is ignored. If the .CR -i option is used with .CR LABEL as its argument and the file .CR LABEL does not exist in the boot programs, and .I device is an LVM layout disk or the .CR -l option is used, .CR mkboot creates a minimal .CR LABEL file on .I device which will permit the system to boot on .I device, possibly without swap or dump. .TP .C -l If this option is used, .CR mkboot treats .I device as an LVM layout disk, regardless of whether or not it is currently set up as one. This option cannot be used along with the .CR -H and .CR -W options. .TP .CI -p \0preserved_lif_file If the .CR -p option is specified one or more times, .CR mkboot keeps each specified .I preserved_lif_file intact on .I device. If .IR preserved_lif_file also appears as an argument to the .CR -i option, that .CR -i option is ignored. This option is typically used with the autoexecute file .CR AUTO and with the LVM and SwitchOver/UX file .CR LABEL. .IP If .CR LABEL is specified as an argument to the .CR -p option and .CR LABEL does not exist on the .I device, and if the layout is LVM, .CR mkboot creates a minimal .CR LABEL file. In general, if .I preserved_lif_file is not on the .I device, .CR mkboot fails. An exception to this condition is if the .I preserved_lif_file is .CR LABEL and the layout is not LVM, in which case the .CR LABEL file is ignored. .TP .C -u If .CR -u is specified, .CR mkboot uses the information contained in the LIF header to identify the location of the swap area, boot area, and raw I/O so that installation of the boot programs does not violate any user data. .IP Normally, the LIF header information is overwritten on each invocation of mkboot. This option is typically used with the .CR -W option, to modify boot programs on a disk that is actively supporting swap and/or raw I/O. .TP .C -v If this option is specified, .CR mkboot displays its actions, including the amount of swap space available on the specified device. .TP .C -W If this option is specified, .CR mkboot treats .I device as a disk having the Whole Disk layout. This option cannot be used along with the .CR -l and .CR -H options. .TP .I device Install the boot programs on the given device special file. The specified .I device can identify either a character-special or block-special device. However, .CR mkboot requires that both the block and character device special files be present. .CR mkboot attempts to determine whether .I device is character or block special by examining the specified path name. For this reason, the complete path name must be supplied. If .CR mkboot is unable to determine the corresponding device file, a message is written to the display, and .CR mkboot exits. .RE .PP .CR rmboot removes the boot programs from the boot area. .SH EXAMPLES Install default boot programs on the specified disk, treating it as an LVM disk: .PP .C " mkboot -l /dev/dsk/c0t5d0" .PP Use the existing layout, and install only SYSLIB and ODE files and preserve the EST file on the disk: .PP .C " mkboot -i SYSLIB -i ODE -p EST /dev/rdsk/c0t5d0" .PP Install only the SYSLIB file and retain the ODE file on the disk. Use the Whole Disk layout. Use the file .CR /tmp/bootlf to get the boot programs rather than the default. (The .CR -i .CR ODE option will be ignored): .PP .C " mkboot -b /tmp/bootlf -i SYSLIB -i ODE -p ODE -W /dev/rdsk/c0t5d0" .SH WARNINGS If .I device has a Whole Disk layout, a file system must reside on the device being modified. .PP When executing from a recovery system, the .CR mkboot command (if used) must be invoked with the .CR -f option; otherwise it will not be able to replace the boot area on your disk. .PP If .I device is, or is intended to become an LVM physical volume, .I device must specify the whole disk. .PP If .I device is, or is intended to become a Hard Partitioned disk, .I device must specify section 6. .SH DEPENDENCIES .CR mkboot and .CR rmboot fail if file system type on .I device is not HFS. .SS "LVM and Hard Partition Layouts" The .CR -f , .CR -h and .CR -u options are not supported. .SH AUTHOR .CR mkboot and .CR rmboot were developed by HP. .SH FILES .TP 30 .C /usr/lib/uxbootlf file containing default boot programs .PD 0 .TP .C ISL initial system loader .PD 0 .TP .C HPUX HP-UX bootstrap and installation utility .PD 0 .TP .C AUTO defines default/automatic boot behavior (see .IR hpux(1M)) .PD 0 .TP .C LABEL used by SwitchOver/UX and LVM .PD 0 .TP .C RDB diagnostics tool .PD 0 .TP .C IOMAP diagnostics tool .PD .SH SEE ALSO boot(1M), hpux(1M), isl(1M), lif(4), lvlnboot(1M), mkfs(1M), newfs(1M). .\" .\" index@\f4mkboot\f1 \- install, or update boot programs from a disk device@@@\f3mkboot(1M)\f1 .\" index@\f4rmboot\f1 \- remove boot programs from a disk device@@@\f3mkboot(1M)\f1 .\" index@\f1install, update, or remove boot programs from a disk device@@@\f3mkboot(1M)\f1 .\" index@\f1update, install, or remove boot programs from a disk device@@@\f3mkboot(1M)\f1 .\" index@\f1remove boot programs from a disk device, install, update, or@@@\f3mkboot(1M)\f1 .\" index@\f1boot programs; install, update, or remove from a disk device@@@\f3mkboot(1M)\f1 .\" index@\f1programs from a disk device; update, install, or remove boot@@@\f3mkboot(1M)\f1 .\" index@\f1disk device; update, install, or remove boot programs from a@@@\f3mkboot(1M)\f1 .\" index@\f1device; update, install, or remove boot programs from a disk@@@\f3mkboot(1M)\f1 .\" .\" toc@\f3mkboot(1M)\f1:\0\0\f4mkboot\f1, \f4rmboot\f1@@@install, update, or remove boot programs from a disk device .\" toc@\f4rmboot\f1 \- install, update, or remove boot programs from a disk device@@@see \f3mkboot(1M)\f1 .\" .\" links@mkboot.1m rmboot.1m .\" .\" fileset_database@mkboot.1m SYS-ADMIN-MAN .\" $Header: rmsf.1m,v 72.6 94/11/02 01:36:41 ssa Exp $ .TA r .TH rmsf 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rmsf \- remove a special (device) file .SH SYNOPSIS .CR /sbin/rmsf .RC [ \-a \(or \-k ] .RC [ \-D .IR directory ] .RC [ \-q \(or \-v ] .IR special_file .RI ... .PP .CR /sbin/rmsf .RC [ \-C .IR class \(or .CR \-d .IR driver ] .RC [ \-D .IR directory ] .CR \-H .I hw_path .RC [ \-k ] .RC [ \-q \(or \-v ] .SH DESCRIPTION The .CR rmsf command removes one or more special files from the current directory, and potentially removes information about the associated device or devices from the system. .PP If no options are specified, .CR rmsf removes only the .I special_files specified on the command line. The .CR \-k option causes .CR rmsf to remove the definition of the device from the system without removing any special files. The .CR \-a option causes .CR rmsf to remove the device definition, and all special files that map to it from the .CR /dev directory (or the directory specified with the .CR \-D option). By default, .CR rmsf only removes .I special_file as given on the command line, however, when the .CR \-a option is used and .I special_file is an absolute path name .I special_file will be removed even if it does not reside in the .CR /dev directory (or the directory specified with the .CR \-D option). .PP If a .CI -H \ hw_path is specified alone, all special files mapping to devices at that hardware path and the system definition of those devices are removed. The .CR \-C and .CR \-d options remove only those special files that are associated with the given device driver or that belong to the given device class, respectively. This is useful when there is more than one type of special file mapped to a single hardware path. If the .CR \-k option is specified, the definition of all devices at that hardware path are removed from the system, again without removing any special files. .PP Normally, .CR rmsf displays a message as the special files are deleted for each driver. The .CR \-q (quiet) option suppresses the deletion message. The .CR \-v (verbose) option displays the deletion message and the name of each special file as it is deleted. .PP Note that most drivers do not support the ability to be removed from the system. .PP If the device being removed from the system uses a dynamically assigned major number, that number will be freed up for future allocation. .SS Options .CR rmsf recognizes the following options: .RS .TP 15 .CR \-a Remove the definition of the device from the system along with all special files that refer to the device. This option cannot be used with .CR \-k . .TP .CI \-C \0class Match devices that belong to a given device class, .IR class . Device classes can be listed with the .CR lsdev command (see .IR lsdev (1M)). They are defined in files in the directory .CR /usr/conf/master.d . This option cannot be used with .CR \-d . .TP .CI \-d \0driver Match devices that are controlled by the specified device driver, .IR driver . Device drivers can be listed with the .CR lsdev command (see .IR lsdev (1M)). They are defined in files in the directory .CR /usr/conf/master.d . This option cannot be used with .CR \-C . .TP .CI \-D \0directory Override the default device installation directory .CR /dev and remove the special files from .I directory instead. .I directory must exist; otherwise, .CR rmsf displays an error message and exits. See WARNINGS. .TP .CI \-H \0hw_path Match devices at a given hardware path, .IR hw\-path . Hardware paths can be listed with the .CR ioscan command (see .IR ioscan (1M)). A hardware path specifies the addresses of the hardware components leading to a device. It consists of a string of numbers separated by periods .RC ( . ), such as .CR 52 (a card), .CR 52.3 (a target address), and .CR 52.3.0 (a device). If a hardware component is a bus converter, the following period, if any, is replaced by a slash .RC ( / ) as in .CR 2 , .CR 2/3 , and .CR 2/3.0 . .IP If the specified path contains fewer numbers than are necessary to reach a device, special files are made for all devices at addresses that extend the given path. If the specified path is .CR 56 , then special files are made for the devices at addresses .CR 56.0 , .CR 56.1 , .CR 56.2 , etc. .TP .CR \-k Remove the definition of the device from the system, but not any special files. This option cannot be used with .CR \-a . .TP .CR \-q Quiet option. Normally, .CR rmsf displays a message as each driver is removed. This option suppresses the driver message, but not error messages. See the .CR \-v option. .TP .CR \-v Verbose option. In addition to the normal processing message, display the name of each sepecial file as it is removed. See the .CR \-q option. Print the names of the files as .CR rmsf is removing them. .RE .SH RETURN VALUE .CR rmsf exits with one of the following values: .RS .TP .PD 0 .CR 0 Successful completion, including warning diagnostics. .TP .CR 1 Failure. An error occurred. .PD .RE .SH DIAGNOSTICS Most of the diagnostic messages from .CR rmsf are self-explanatory. Listed below are some messages deserving further clarification. Errors cause .CR rmsf to halt immediately. Warnings allow the program to continue. .SS Errors .PP .C "No such device in the system" .IP No device in the system matched the options specified. Use .CR ioscan to list the devices in the system (see .IR ioscan (1M)). .PP .IC special_file "\0is not a special file" .IP The file is not associated with an I/O device. .SS Warnings .PP .CI "Cannot remove\0" driver "\0at\0" hw_path .IP The definition of the device located at .I hw_path and controlled by .I driver cannot be removed from the kernel. That is .I driver does not support the .CR unbind function. .PP .CI "No device associated with\0" special_file .IP The special file does not map to a device in the system; the file is removed unless the .CR \-k option was specified. .SH EXAMPLES Remove the special file .CR mux0 from the current directory: .IP .C "rmsf ./mux0" .PP Remove the system definition of the device associated with .CR /dev/lp0 along with all special files that refer to the device: .IP .C "rmsf \-a /dev/lp0" .PP Remove the system definitions for all devices associated with hardware path 52.6.0: .IP .C "rmsf \-k \-H 52.6.0" .SH WARNINGS Most commands and subsystems assume their device files are in .CR /dev , therefore the use of the .CR \-D option is discouraged. .PP Most device drivers do not support the .I unbind operation necessary to remove the device from the system. .SH AUTHOR .CR rmsf was developed by HP. .SH FILES .CR /dev/config .br .CR /etc/ioconfig .br .CR /usr/conf/master.d/* .SH SEE ALSO rm(1), insf(1M), ioscan(1M), lsdev(1M), lssf(1M), mksf(1M), ioconfig(4). .\" .\" index@\f4rmsf\f1 \- remove a special (device) file@@@\f3rmsf(1M)\f1 .\" index@\f1remove a special (device) file@@@\f3rmsf(1M)\f1 .\" index@\f1special (device) file, remove a@@@\f3rmsf(1M)\f1 .\" index@\f1device (special) file, remove a@@@\f3rmsf(1M)\f1 .\" index@\f1file, remove a special (device)@@@\f3rmsf(1M)\f1 .\" .\" toc@\f3rmsf(1M)\f1:\0\0\f4rmsf\f1@@@remove a special (device) file .\" $Header: rmt.1m,v 72.4 93/11/12 13:47:16 ssa Exp $ .TA r .TH rmt 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rmt \- remote magnetic-tape protocol module .SH SYNOPSIS .C /usr/sbin/rmt .SH DESCRIPTION .C rmt is a program used by the remote dump and restore programs for manipulating a magnetic tape drive through an interprocess communication .SM (IPC) connection. The .C fbackup and .C frecover commands also use .C rmt to achieve remote backup capability (see .IR fbackup (1M) and .IR frecover (1M)). .C rmt is normally started up with an .C rexec() or .C rcmd() call (see .IR rexec (3C) and .IR rcmd (3C)). .PP .C rmt accepts requests specific to the manipulation of magnetic tapes, performs the commands, then responds with a status indication. .SM DDS devices that emulate magnetic tapes are also supported. All responses are in .SM ASCII and in one of two forms. Successful commands have responses of .IP .CI A number \en .PP where .I number is an .SM ASCII representation of a decimal number. Unsuccessful commands are responded to with .IP .CI E error-number \en error-message \en .PP where .I error-number is one of the possible error numbers described in .IR errno (2) and .I error-message is the corresponding error string as printed from a call to .C perror() (see .IR perror (3C)). The protocol is comprised of the following commands (a space is present between each token): .RS .TP 18 .CI O " device mode" Open the specified .I device using the indicated .IR mode . .I device is a full pathname and .I mode is an .SM ASCII representation of a decimal number suitable for passing to .C open() (see .IR open (2)). If a device is already open, it is closed before a new open is performed. .TP .CI o " device mode" Open the specified .I device using the indicated .IR mode . .I device is a full pathname and .I mode is an .SM ASCII representation of an octal number suitable for passing to .CR open() . If a device is already open, it is closed before a new open is performed. .TP .CI C " device" Close the currently open device. The .I device specified is ignored. .TP .CI L " whence offset" Perform an .C lseek() operation using the specified parameters (see .IR lseek (2)). The response value is that returned from by .CR lseek() . .TP .CI W \0count Write data onto the open device. .C rmt reads .I count bytes from the connection, aborting if a premature end-of-file is encountered. The response value is that returned from by .C write() (see .IR write (2)). .TP .CI R " count" Read .I count bytes of data from the open device. If .I count exceeds the size of the data buffer (10 Kbytes), it is truncated to the data buffer size. .C rmt then performs the requested .C read() and responds with .CI A count-read \en if the read was successful. Otherwise an error is returned in the standard format. If the read was successful, the data read is then sent. .TP .CI I " operation count" Perform a .C MTIOCOP .C ioctl() command using the specified parameters. Parameters are interpreted as .SM ASCII representations of the decimal values to be placed in the .C mt_op and .C mt_count fields of the structure used in the .C ioctl() call. The return value is the .I count parameter when the operation is successful. .TP .C S Return the status of the open device, as obtained with a .C MTIOCGET .C ioctl() call. If the operation was successful, an .SM ACK is sent with the size of the status buffer, then the status buffer is sent (in binary). .TP .C s Return the status of the open device, as obtained with a .C fstat() call. If the operation was successful, an .SM ACK is sent with the size of the status buffer, then the status buffer is sent (in binary). .C f Return the status of the open device, as obtained with a .C fstat() call. If the operation was successful, an .SM ACK is sent with the size of the status buffer, then the status buffer is sent in the following .SM ASCII format: .RS .IP .IR machine value .br .IR stat_struct_member_name value .RE .IP The end of the data is indicated by an .SM ASCII NULL character. See .C /usr/include/sys/stat.h for the .C struct stat definition. In addition to the struct stat information, there is an entry in the buffer describing the machine type as returned from a .C uname() call (see .IR uname (2)). In the above format ``machine'' is a key word. All fields except .C st_spare4 of the .C struct stat are returned. .TP .C m Return the status of the open device, as obtained with a .C MTIOCGET .C ioctl() call. If the operation was successful, an .SM ack is sent with the size of the status buffer, then the status buffer is sent in the following .SM ASCII format: .RS .IP .IR machine value .br .IR mtget_struct_member_name value .RE .IP The end of the data is indicated by an .SM ASCII NULL character. See .C /usr/include/sys/mtio.h for the .C struct mtget definition. In addition to the struct mtget information there is an entry in the buffer describing the machine type as returned from a .C uname() call. In the above format ``machine'' is a keyword. .RE .PP Any other command causes .C rmt to exit. .SH RETURN VALUE Device status is returned in the field .CR mt_gstat . .C /usr/include/sys/mtio.h contains defined macros for checking the status bits. .SH DIAGNOSTICS All responses are of the form described above. .SH AUTHOR .C rmt was developed by the University of California, Berkeley. .SH SEE ALSO ftio(1), fbackup(1M), frecover(1M), dump(1M), restore(1M), rcmd(3C), rexec(3C). .SH WARNINGS Use of this command for remote file access protocol is discouraged. .\" .\" index@\f2rmt\f1 \- remote magnetic tape protocol module@@@\f3rmt(1M)\f1 .\" index@remote magnetic tape dump and restore protocol module@@@\f3rmt(1M)\f1 .\" index@magnetic tape dump and restore protocol module, remote@@@\f3rmt(1M)\f1 .\" index@tape dump and restore protocol module, remote magnetic@@@\f3rmt(1M)\f1 .\" index@dump and restore protocol module, remote magnetic tape@@@\f3rmt(1M)\f1 .\" index@protocol module, remote magnetic tape dump and restore@@@\f3rmt(1M)\f1 .\" index@module, remote magnetic tape dump and restore protocol@@@\f3rmt(1M)\f1 .\" .\" toc@\f3rmt(1M)\f1:\0\0\f2rmt\f1@@@remote magnetic-tape protocol module .\" .\" fileset_database@rmt.1m SYS-ADMIN-MAN .\" $Header: route.1m,v 74.1 95/03/16 16:33:29 ssa Exp $ .TA r .TH route 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME route \- manually manipulate the routing tables .SH SYNOPSIS .CR /usr/sbin/route .RC [ -f ] .RC [ -n ] .RC [ -p .IR pmtu ] .CR add .RC [ net \(or host ] .IR destination .ifn .br .ifn \0\0\0\0 .RC [ netmask .IR mask ] .IR gateway .RI [ count ] .PP .CR /usr/sbin/route .RC [ -f ] .RC [ -n ] .CR delete .RC [ net \(or host ] .IR destination .ifn .br .ifn \0\0\0\0 .RC [ netmask .IR mask ] .IR gateway .RI [ count ] .PP .CR /usr/sbin/route .CR -f .RC [ -n ] .SH DESCRIPTION The .CR route command manipulates the network routing tables manually. You must have appropriate privileges. .SS Subcommands The following subcommands are supported. .RS .TP 15 .CR add Add the specified host or network route to the network routing table. If the route already exists, a message is printed and nothing changes. .TP .CR delete Delete the specified host or network route from the network routing table. .RE .SS Options and Arguments .CR route recognizes the following options and arguments. .RS .TP 15 .CR -f Delete all route table entries that specify a remote host for a gateway. If this is used with one of the subcommands, the entries are deleted before the subcommand is processed. .TP .CR -n Print any host and network addresses in Internet dot notation, except for the default network address, which is printed as .CR default . .TP .CI -p \0pmtu Specifies a path maximum transmission unit (MTU) value for a static host route. The minimum value allowed is 68 bytes; the maximum is the MTU of the outgoing interface for this route. This option only applies to adding a host route. In all other cases, this option is ignored and has no effect on a system. .IP You can also disable the Path MTU Discovery for a host route by specifying .I pmtu as zero. .TP .CR net .PD 0 .TP \0or .TP .CR host .sp -3v The type of .I destination address. If this argument is omitted, routes to a particular host are distinguished from those to a network by interpreting the Internet address associated with .IR destination . If the .I destination has a local address part of .CR INADDR_ANY(0) , the route is assumed to be to a network; otherwise, it is treated as a route to a host. .PD .TP .I destination The destination host system where the packets will be routed. .I destination can be one of the following: .RS .RS 2 .TP 3 .PD 0 \(bu A host name (the official name or an alias, see .IR gethostbyname (3N)). .TP \(bu A network name (the official name or an alias, see .IR getnetbyname (3N)). .TP \(bu An Internet address in dot notation (see .IR inet (3N)). .TP \(bu The keyword .CR default , which signifies the wildcard gateway route (see .IR routing (7)). .PD .RE .RE .PD .TP .CR netmask .PD 0 .TP .IR mask The mask that will be bit-wise ANDed with .I destination to yield a net address where the packets will be routed. .I mask can be specified as a single hexadecimal number with a leading .CR 0x , with a dot-notation Internet address, or with a pseudo-network name listed in the network table (see .IR networks (4)). The length of the .I mask, which is the number of contiguous 1's starting from the leftmost bit position of the 32-bit field, can be shorter than the default network mask for the .I destination address. (see .I routing (7)). If the .CR netmask option is not given, .I mask for the route will be derived from the .I netmasks associated with the local interfaces. (see .I ifconfig (1)). .I mask will be defaulted to the longest .I netmask of those local interfaces that have the same network address. If there is not any local interface that has the same network address, then .I mask will be defaulted to the default network mask of .I destination. .PD .TP .I gateway The gateway through which the destination is reached. .I gateway can be one of the following: .RS .RS 2 .TP 3 .PD 0 \(bu A host name (the official name or an alias, see .IR gethostbyname (3N)). .TP \(bu An Internet address in dot notation (see .IR inet (3N)). .PD .RE .RE .TP .I count An integer that indicates whether the gateway is a remote host or the local host. If the route leads to a destination through a remote gateway, .I count should be a number greater than 0. If the route leads to .I destination and the gateway is the local host, .I count should be 0. The default for .I count is zero. The result is not defined if .I count is negative. .RE .SS Operation All symbolic names specified for a .I destination or .I gateway are looked up first as a host name using .CR gethostbyname() ; if the host name is not found, the .I destination is searched for as a network name using .CR getnetbyname() . .I destination and .I gateway can be in dot notation (see .IR inet (3N)). .PP If the .CR -n option is not specified, any host and network addresses are displayed symbolically according to the name returned by .CR gethostbyaddr() and .CR getnetbyaddr() , respectively, except for the default network address (printed as .CR default ) and addresses that have unknown names. Addresses with unknown names are printed in Internet dot notation (see .IR inet (3N)). .PP If the .CR -n option is specified, any host and network addresses are printed in Internet dot notation except for the default network address which is printed as .CR default . .PP If the .CR -f option is specified, .CR route deletes all route table entries that specify a remote host for a gateway. If it is used with one of the subcommands described above, the entries are deleted before the subcommand is processed. .PP Path MTU Discovery is a technique for discovering the maximum size of an IP datagram that can be sent on an internet path without causing datagram fragmentation in the intermediate routers. In essence, a source host that utilizes this technique initially sends out datagrams up to the the size of the outgoing interface. The Don't Fragment (DF) bit in the IP datagram header is set. As an intermediate router that supports Path MTU Discovery receives a datagram that is too large to be forwarded in one piece to the next-hop router and the DF bit is set, the router will discard the datagram and send an ICMP Destination Unreachable message with a code meaning "fragmentation needed and DF set". The ICMP message will also contain the MTU of the next-hop router. When the source host receives the ICMP message, it reduces the path MTU of the route to the MTU in the ICMP message. With this technique, the host route in the source host for this path will contain the proper MTU. .PP By default, Path MTU Discovery is enabled for TCP sockets and disabled for UDP sockets. .PP If the .CR -p .I pmtu option is specified for a host route, the .I pmtu value is considered permanent for the host route. Even if the Path MTU Discovery process discovers a smaller .I pmtu for this route at a later time, the .I pmtu field in the host route will not be updated. A warning message will be logged with the new .I pmtu value. .PP The .CR -p .I pmtu option is useful only if you knows the network environment well enough to enter an appropriate .I pmtu for a host route. IP will fragment a datagram to the .I pmtu specified for the route on the local host before sending the datagram out to the remote. It will avoid fragmentation by routers along the path, if the .I pmtu specified in the .CR route command is correct. .PP .CR ping can be used to find the .I pmtu information for the route to a remote host. The .I pmtu information in the routing table can be displayed with the .CR "netstat\ -r" command (see .IR netstat (1)). .SS Output .PP .CI add \0destination :\0gateway \0gateway .IP The specified route is being added to the tables. .PP .CI delete \0destination :\0gateway \0gateway .IP The specified route is being deleted from the tables. .SS Flags The values of the .I count and .I destination type fields in the .CR route command determine the presence of the .CR G and .CR H flags in the .CR "netstat\ -r" display and thus the route type, as shown in the following table. .PP .ne 16 .RS .vs +2 .TS tab(*); cB cB cB cBw(3i) c c lf4p+1 l. Count*Destination Type*Flags*Route Type _ \&=0*network*\0U*T{ Route to a network directly from the local host T} \&>0*network*\0UG*T{ Route to a network through a remote host gateway T} \&=0*host*\0UH*T{ Route to a remote host directly from the local host T} \&>0*host*\0UGH*T{ Route to a remote host through a remote host gateway T} \&=0*\f4default\f1*\0U*T{ Wildcard route directly from the local host T} \&>0*\f4default\f1*\0UG*T{ Wildcard route through a remote host gateway T} _ .TE .vs .RE .SH DIAGNOSTICS The following error diagnostics can be displayed. .PP .C "add a route that already exists" .IP The specified entry is already in the routing table. .PP .C "add too many routes" .IP The routing table is full. .PP .C "delete a route that does not exist" .IP The specified route was not in the routing table. .SH WARNINGS Reciprocal .CR route commands must be executed on the local host, the destination host, and all intermediate hosts if routing is to succeed in the cases of virtual circuit connections or bidirectional datagram transfers. .PP The .SM HP-UX implementation of .CR route does not presently support a .CR change subcommand. .SH AUTHOR .CR route was developed by the University of California, Berkeley. .SH FILES .CR /etc/networks .br .CR /etc/hosts .SH SEE ALSO netstat(1), ifconfig(1M), ping(1M), getsockopt(2), recv(2), send(2), gethostbyaddr(3N), gethostbyname(3N), getnetbyaddr(3N), getnetbyname(3N), inet(3N), routing(7). .\" .\" index@\f4route\f1 \- manipulate routing tables manually@@@\f3route(1M)\f1 .\" index@manipulate routing tables manually@@@\f3route(1M)\f1 .\" index@routing tables manually, manipulate@@@\f3route(1M)\f1 .\" index@tables manually, manipulate routing@@@\f3route(1M)\f1 .\" index@manually manipulate routing tables@@@\f3route(1M)\f1 .\" .\" toc@\f3route(1M)\f1:\0\0\f4route\f1@@@manually manipulate routing tables .\" .\" fileset_database@route.1m SYS-ADMIN-MAN .\" $Header: lockd.1m,v 78.1 96/01/03 15:16:35 ssa Exp $ .TA l .TH lockd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lockd \- network lock daemon .SH SYNOPSIS .C /usr/sbin/rpc.lockd .RC [ -l .IR log_file ] .RC [ -t .IR timeout ] .RC [ -g .IR graceperiod ] .SH DESCRIPTION .CR lockd is an RPC server that processes NFS file locking requests from the local kernel or from another remote lock daemon. .CR lockd forwards lock requests for remote data to the server site's lock daemon through the RPC/XDR package (see .IR rpc (3C)). .CR lockd then requests the status monitor daemon, .CR statd for monitor service (see .IR statd (1M)). The reply to the lock request is not sent to the kernel until the status daemon and the server site's lock daemon have replied. .PP If either the status monitor or server site's lock daemon is unavailable, the reply to a lock request for remote data is delayed until all daemons become available. .PP When a server recovers, it waits for a grace period for all NFS client-site .CR lockd s to submit reclaim requests. Client-site .IR lockd s are notified by the .CR statd of the server recovery, and promptly resubmit previously granted lock requests. If a .CR lockd fails to secure a previously granted lock at the server site, the .CR lockd sends a .CR SIGLOST to the process holding that lock. .SS Options .CR lockd recognizes the following options and command-line arguments: .RS .TP 20 .CI -l \0log_file Log any errors to the named log file .IR log_file . Errors are not logged if the .CR -l option is not specified. .IP Information logged to the file includes date and time of the error, host name, process ID and name of the function generating the error, and the error message. .TP .CI -t \0timeout .CR lockd uses .I timeout (seconds) as the interval instead of the default value (10 seconds) to retransmit a lock request to the remote server. Note that changing this value also changes the value for grace period duration. .TP .CI -g \0graceperiod .CR lockd uses .RI [\|1\|+\|( \|graceperiod\| / \|timeout\| )]\|\(mu\| timeout (seconds) as the grace period duration instead of the default value .RI (\|5\(mu\| timeout seconds). If both .CR -t and .CR -g are specified, the .CR -t should appear first since the grace period duration is dependent on the value of timeout. .SH AUTHOR .CR lockd was developed by Sun Microsystems, Inc., and HP. .SH SEE ALSO fcntl(2), lockf(2), signal(2), statd(1M). .\" .\" index@\f4lockd\f1 \- network lock daemon@@@\f3lockd(1M)\f1 .\" index@network lock daemon@@@\f3lockd(1M)\f1 .\" index@lock daemon, network@@@\f3lockd(1M)\f1 .\" index@daemon, network lock@@@\f3lockd(1M)\f1 .\" .\" toc@\f3lockd(1M)\f1:\0\0\f4lockd\f1@@@network lock daemon .\" .\" links@lockd.1m rpc.lockd.1m .\" $Header: mountd.1m,v 78.2 96/05/09 12:29:18 ssa Exp $ .\" mountd.1m,v 1.1.113.2 96/01/04 16:29:13 indnetwk Exp $ .TA m .TH mountd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mountd \- \s-1NFS\s0 mount request server .SH SYNOPSIS .C /usr/sbin/rpc.mountd .RC [ -l .IR log_file\| ] .RC [ -t .IR n\| ] .RC [ -p \(or -e \(or -n\ ] .SH DESCRIPTION .C mountd is an .SM RPC server that answers file system mount requests. It reads file .C /etc/xtab (described in .IR exports (4)) to determine which directories are available to which machines. It also provides information on what file systems are mounted by which clients. This information can be printed using the .C showmount command (see .IR showmount (1M)). .PP .C rpc.mountd can be started at boot time by setting the variable .C NFS_SERVER to 1 in the file .C /etc/rc.config.d/nfsconf. It can also be started through .C /etc/inetd.conf (see .IR inetd (1M)), provided that the .C START_MOUNTD variable is set to 0 in .C /etc/rc.config.d/nfsconf. .SS Options .C mountd recognizes the following options: .RS .TP 12 .CI -l \0log_file Log any errors to the named log file, .IR log_file . Errors are not logged if the .C -l option is not specified. .IP The information logged to the file includes the date and time of the error, the host name, process .SM ID and name of the function generating the error, and the error message. Note that different services can share a single log file since enough information is included to uniquely identify each error. .TP .C -p Run from unreserved ports. This option restores the old default behavior on HP-UX. The default has been changed for the mount daemon to run from reserved ports unless this option is set. .TP .C -e Exit after serving each .SM RPC request. When this option is used, the .C inetd security file .C /var/adm/inetd.sec can control access to .SM RPC services. This option only supports .SM UDP requests. .TP .C -n Exit only if: .RS .RS .TP 3 \(bu .C portmap dies (see .IR portmap (1M)), .PD 0 .TP \(bu another .C rpc.mountd registers with .CR portmap , or .TP \(bu .C rpc.mountd becomes unregistered with .CR portmap . .RE .RE .PD .IP This option is more efficient because a new process is not launched for each .SM RPC request. This option is the default. .TP .CI -t n Specify tracing level .I n , where .I n can have one of the following values: .RS .RS .TP .C 1 Errors only (default) .PD 0 .TP .C 2 Errors, mount requests and mount failures .RE .RE .RE .PD .SH WARNINGS The default behavior of the mount daemon is to run from reserved ports. If the daemon needs to be run from unreserved ports, use the -p option. .PP If a client crashes, executing .C showmount on the server will show that the client still has a file system mounted; i.e., the client's entry is not removed from .C /etc/rmtab until the client reboots and executes .C umount -a (see .IR showmount (1M)). .PP Also, if a client mounts the same remote directory twice, only one entry appears in .CR /etc/rmtab . Doing a .C umount of one of these directories removes the single entry and .C showmount no longer indicates that the remote directory is mounted. .SH AUTHOR .C mountd was developed by Sun Microsystems, Inc. .SH FILES .TP 20 .C /etc/rmtab List of all hosts having file systems mounted from this machine .SH SEE ALSO inetd(1M), mount(1M), portmap(1M), showmount(1M), exports(4), inetd.conf(4), inetd.sec(4), rmtab(4), services(4). .\" .\" index@\f4mountd\f1: \s-1NFS\s+1 mount request server@@@\f3mountd(1M)\f1 .\" index@\s-1NFS\s+1 mount request server@@@\f3mountd(1M)\f1 .\" index@mount request server, \s-1NFS\s+1@@@\f3mountd(1M)\f1 .\" index@server, \s-1NFS\s+1 mount request@@@\f3mountd(1M)\f1 .\" .\" toc@\f3mountd(1M)\f1: \f4mountd\f1@@@NFS mount request server .\" .\" links@mountd.1m rpc.mountd.1m .\" $Header: pcnfsd.1m,v 72.5 94/11/29 11:28:17 ssa Exp $ .TA p .TH pcnfsd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pcnfsd \- PC-NFS authentication and print request server .SH SYNOPSIS .CR /usr/sbin/rpc.pcnfsd .SH DESCRIPTION .CR pcnfsd is an RPC server that supports ONC clients on PC (DOS, OS/2, Macintosh, and other) systems. This describes version two of the .CR pcnfsd server. .PP .CR pcnfsd can be started from the .CR /sbin/init.d/nfs.server startup script by setting the .CR PCNFS_SERVER variable to 1 in .CR /etc/rc.config.d/nfsconf , or from the .CR inetd daemon (see .IR inetd (1M)). It reads the configuration file .CR /etc/pcnfsd.conf , if present, and services RPC requests directed to program number 150001. The .CR pcnfsd daemon now supports version 1 and version 2 of the PCNFSD protocol. .PP The requests serviced by .CR pcnfsd fall into three categories: authentication, printing, and other. Only the authentication and printing categories have administrative significance. .SS Authentication When .CR pcnfsd receives a .CR PCNFSD_AUTH or .CR PCNFSD2_AUTH request, it will "log in" the user by validating the user name and password, returning the corresponding user ID, group IDs, home directory, and umask. It will also append a record to the .CR wtmp data base (see .IR wtmp (4)). If you do not want PC "logins" recorded in this way, add a line to the .CR /etc/pcnfsd.conf file in the form: .IP .C "wtmp off" .PP By default, .CR pcnfsd will only allow authentication or print requests for users with user IDs in the range 101 to 60002 (this corresponds, in SVR4, to the range for nonsystem accounts). To override this, add a line to the .CR /etc/pcnfsd.conf file in the form: .IP .CR uidrange .IR range [\c .CI , range\f1]... .PP where each .IR range is a user ID number in the form .IP .I uid .PP or an inclusive range of user ID numbers in the form .IP .IC uid - uid .SS Printing .CR pcnfsd supports a printing model that uses NFS to transfer print data from the client to the server. The client system issues a .CR PCNFSD_PR_INIT or .CR PCNFSD2_PR_INIT request, and the server returns the path to a spool directory that is exported by NFS for use by the client. .CR pcnfsd creates a subdirectory for each client. By default, the parent directory is .CR /var/spool/pcnfs , and the name of each subdirectory is the same as its client's host name. To use a different parent directory, add a line to the .CR /etc/pcnfsd.conf file in the form: .IP .CR spooldir .I path .PP Once a client has mounted the spool directory using NFS, and transferred print data to a file in that directory, it will issue a .CR PCNFSD_PR_START or .CR PCNFSD2_PR_START request. .CR pcnfsd handles most print-related requests by constructing a command based on the printing services of the server's operating system, and executing that command using the identity of the PC user. Because this involves set-user-ID privileges, .CR pcnfsd must be run as .CR root . .PP Every print request from a client includes the name of the printer to be used. This name corresponds to a printer that has been configured into the line printer spooling system using the .CR lpadmin command. .PP To process print data in a special way (for example, to print it in landscape mode, or to print it in duplex mode), define a new printer and arrange for the client to print to that printer. There are two ways to define the new printer: .RS .TP 3 \(bu You can add a new printer to the line printer spooling system that uses a different printer model script, and arrange for the client to use the new printer. Do this using the .CR lpadmin command (see .IR lpadmin (1m)). .TP \(bu .CR pcnfsd includes a mechanism to define virtual printers known only to .CR pcnfsd clients. Each of these printers is defined by an entry in the file .CR /etc/pcnfsd.conf using the following format: .RS .IP .CR printer .IR name .IR alias-for .IR command .RE .IP with the following values: .RS .TP 15 .I name The name of the printer, as it will be referred to in print requests from clients. .TP .I alias-for The corresponding name for the printer, as it is defined in the line printer spooling system. For example, a request to display the queue for .I name will be translated into the corresponding request for the printer .IR alias-for . If you have defined a printer within .CR pcnfsd that has no corresponding printer defined in the line printer spooling system, use a single hyphen .RC ( - ) for this field. For an example, see the definition of the printer .CR test in the examples section, below. .TP .I command A command that will be executed whenever a file is printed on .IR name . This command is executed by the POSIX shell, .CR /usr/bin/sh using the .CR -c option. For complex operations, construct an executable shell program and execute that in .IR command . .IP Within .I command the following tokens will be replaced: .RS .TP 10 .B Token .B Substitution .TP .CR $FILE Replaced by the full path name of the print data file. When the command has been executed, the file will be unlinked. .TP .CR $USER Replaced by the user name of the user logged in to the client system. .TP .CR $HOST Replaced by the host name of the client system. .RE .RE .RE .SS Reconfiguration By checking the modification time (and contents) of the file .CR /var/spool/lp/pstatus , .CR pcnfsd will detect when printers have been added or deleted, and will rebuild its list of valid printers. However, .CR pcnfsd does not monitor the file .CR /etc/pcnfsd.conf for updates; if you change this file, you must kill and restart .CR pcnfsd for the changes to take effect. .SH EXAMPLES Given the following entries for the file .CR /etc/pcnfsd.conf: .IP .C "printer abc lj lp -dlj -oraw" .br .C "printer test - /usr/bin/cp $FILE /usr/tmp/$HOST-$USER" .PP If a user on a client system prints a job on printer .CR abc , the request will be sent to destination .CR lj in raw mode. .PP If the client requests a list of the print queue for printer .CR abc , the .CR pcnfsd daemon will translate this into a request for a listing for printer .CR lj . .PP Printer .CR test is used only for testing. Any file sent to this printer will be copied into the directory .CR /usr/tmp . Any request to list the queue, check the status, etc., of printer .CR test will be rejected because .I alias-for has been specified as a hyphen .RC ( - ). .SH FILES .PD 0 .nf .CR /etc/pcnfsd.conf .CR /etc/rc.config.d/nfsconf .CR /var/spool/lp/pstatus .CR /var/spool/pcnfs .fi .PD .SH SEE ALSO lp(1), lpstat(1), inetd(1M), lpadmin(1M), wtmp(4). .\" .\" index@\f4pcnfsd\f1 \- PC-NFS authentication and print request server@@@\f3pcnfsd(1M)\f1 .\" index@\f4rpc.pcnfsd\f1 \- PC-NFS authentication and print request server@@@\f3pcnfsd(1M)\f1 .\" index@PC-NFS authentication and print request server@@@\f3pcnfsd(1M)\f1 .\" index@authentication and print request server, PC-NFS@@@\f3pcnfsd(1M)\f1 .\" index@print request server, PC-NFS@@@\f3pcnfsd(1M)\f1 .\" .\" links@pcnfsd.1m rpc.pcnfsd.1m .\" .\" toc@\f3pcnfsd(1M)\f1:\0\0\f4rpc.pcnfsd\f1@@@PC-NFS authentication and print request server .\" toc@\f4rpc.pcnfsd\f1:\0\0PC-NFS authentication and print request server@@@see \f3pcnfsd(1M)\f1 .\" $Header: statd.1m,v 78.1 96/01/03 15:27:52 ssa Exp $ .TA s .TH statd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME statd \- network status monitor .SH SYNOPSIS .C /usr/sbin/rpc.statd .RC [ -l .IR log_file ] .SH DESCRIPTION .CR statd is an RPC server. It interacts with .CR lockd to provide crash and recovery functions for the locking services on NFS (see .IR lockd (1M)). .SS Options .CR statd recognizes the following options and command-line arguments: .TP 15 .CI -l \0log_file Log any errors to the named log file, .IR log_file . Errors are not logged if the .CR -l option is not specified. .IP Information logged to the file includes date and time of the error, host name, process id and name of the function generating the error, and the error message. .SH FILES .CR /var/statmon/sm/* .br .CR /var/statmon/sm.bak/* .br .CR /var/statmon/state .SH WARNINGS Changes in status of a site are detected only upon startup of a new status monitor and lock daemon. .SH AUTHOR .CR statd was developed by Sun Microsystems, Inc. .SH SEE ALSO fcntl(2), lockf(2), signal(2), lockd(1M), sm(4). .\" .\" index@\f4statd\f1 \- network status monitor@@@\f3statd(1M)\f1 .\" index@\f1network status monitor@@@\f3statd(1M)\f1 .\" index@\f1status monitor, network@@@\f3statd(1M)\f1 .\" index@\f1monitor, network status@@@\f3statd(1M)\f1 .\" .\" toc@\f3statd(1M)\f1:\0\0\f4statd\f1@@@network status monitor .\" .\" links@statd.1m rpc.statd.1m .\" $Header: ypupdated.1m,v 76.1 95/07/10 17:17:31 ssa Exp $ .TA y .TH ypupdated 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypupdated, rpc.ypupdated \- server for changing NIS information .SH SYNOPSIS .C /usr/lib/netsvc/yp/rpc.ypupdated [-is] .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .CR ypupdated is a daemon that updates information in the .CR "Network Information Service (NIS)" databases. It is activated at system startup when the .C NIS_MASTER_SERVER variable is set to 1 in .CR /etc/rc.config.d/namesvrs file on the NIS master server. .CR ypupdated consults the file .CR updaters in the directory .CR /var/yp to determine which NIS maps should be updated and how to change them. .PP By default, the daemon requires the most secure method of authentication available to it, either DES (secure) or UNIX (without augmented security). .SS Options .CR ypupdated supports the following options: .RS .TP .C -i Accept RPC calls with the insecure AUTH_UNIX credentials. This allows programmatic updating of the NIS maps in all networks. .TP .C -s Accept only calls authenticated using the secure RPC mechanism (AUTH_DES authentication). This disables programmatic updating of the NIS maps unless the network supports these calls. .SH AUTHOR .CR ypupdated was developed by Sun Microsystems, Inc. .SH FILES .TP 25 .CR /var/yp/updaters .SH SEE ALSO keyserv(1M), updaters(1M). .\" .\" toc@\f3ypupdated(1M)\f1:\0\0\f4ypupdated\f1, \f4rpc.ypupdated\f1@@@server for changing NIS information .\" .\" toc@\f4rpc.ypupdated\f1:\0\0hex encryption and utility routines@@@see \f3ypupdated(1M)\f1 .\" .\" index@\f4ypupdated\f1, \f4rpc.ypupdated\f1 \- server for changing NIS information@@@\f3ypupdated(1M)\f1 .\" .\" index@\f4rpc.ypupdated\f1, \f4ypupdated\f1, \- server for changing NIS information@@@\f3ypupdated(1M)\f1 .\" .\" index@server for changing NIS information@@@\f3ypupdated(1M)\f1 .\" index@changing NIS information, server for@@@\f3ypupdated(1M)\f1 .\" index@NIS information, server for changing@@@\f3ypupdated(1M)\f1 .\" .\" links@ypupdated.1m rpc.ypupdated.1m ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "rpc_intro" 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .SH NAME \*Lrpc_intro\*O - Introduction to DCE RPC daemon and RPC control program commands .SH "DESCRIPTION" .iX "RPC daemon" "about" .iX "Endpoint Map Service" .iX "endpoints" "about" .iX "endpoint maps" "about" .PP DCE RPC provides two administrative facilities, the RPC daemon and the RPC control program. .zA "def,10220,R1.1,Remove reference to rpcd and sec_clientd" .nS note These facilities are superceded by the DCE Host daemon (\*Ldced\*O) and the DCE control program (\*Ldcecp\*O) for OSF DCE version 1.1. .nE .zZ "def,10220,R1.1,Remove reference to rpcd and sec_clientd" .ML .LI The ...\" .gL "RPC daemon" \*LRPC daemon\*O is ...\" WRITER'S NOTE: The remainder of this paragraph is identical to ...\" the end of the first paragraph of "The RPC Daemon" section of ...\" the rpc_components chapter in the RPC Part A of the Appl. Devel. Gde. ...\" a process that provides the ...\" .gL "Endpoint Map service" \*LEndpoint Map Service\*O, which maintains the local endpoint map for local RPC servers and looks up endpoints for RPC clients. ...\" .gL "endpoint" An \*Lendpoint\*O is the address of a specific instance of a server executing in a particular address space on a given system ...\" .gL "server instance" (a \*Lserver instance\*O). Each endpoint can be used on a system by only one server at a time. .P ...\" .gL "endpoint map" An \*Lendpoint map\*O is a database where servers register their binding information, including endpoints, for each of their RPC interfaces and the associated RPC objects. Each combination of binding information, interface identifier, and object UUID uses a distinct element in the local endoint map. .PP The \*Lrpcd\*O command starts the RPC daemon. ...\" .LI "o" .LI The control program provides a set of commands for accessing the operations of the RPC \*Lname service interface\*O (\*LNSI\*O). .iX "Name Service Interface (NSI)" "accessing" For managing endpoint maps, the control program supports showing endpoint map elements and removing any set of map elements from the local endpoint map or from any remote endpoint map. .PP The \*Lrpccp\*O command starts the RPC control program (RPCCP). .LE .SH "EXIT VALUES" .PP The RPC control program reports DCE error messages on the command line. If the command executes successfully, the internal value returned is 0 (zero); otherwise, the value is -1 (negative one). .SH "RELATED INFORMATION" .PP Commands: \*Ldced\*O, \*Ldcecp\*O, \*Lrpcd(1m)\*O, \*Lrpccp(1m)\*O .PP Books: \*(Ag, \*(Dk, \*(Dr ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" "~/rpc/RPCCP/rpccp_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "rpccp"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "RPC control program" "initializing" .SH NAME .PP \*Lrpccp\*O - Starts the RPC control program .SH "SYNOPSIS" .sS \*Lrpccp \*O [\*Vrpccp-command\*O] .sE .SH "ARGUMENTS" .iX "-[" "\*Lrpccp\*O commands" "summary" .VL .LI "\*Vrpccp-command\*O" Specifies one of the following control program commands: .VL .LI "\*Ladd element\*O" Adds an element to a profile in a name service entry; if the specified entry does not exist, creates the entry. .LI "\*Ladd entry\*O" Adds an entry to the name service database. .zA "defect,7587,R1.0.2a,added add mapping" .LI "\*Ladd mapping\*O" Adds or replaces server address information in the local endpoint map. .zZ "defect,7587,R1.0.2a,added add mapping" .LI "\*Ladd member\*O" Adds a member to a group in a name service entry; if the specified entry does not exist, creates the entry. .LI "\*Lexit\*O" Leaves the RPC control program. .LI "\*Lexport\*O" Exports binding information for an interface identifier, object UUIDs, or both to a server entry; if the specified entry does not exist, creates the entry. .LI "\*Lhelp \*O" Displays a list of commands or the possible options of a specified command. .LI "\*Limport\*O" Imports binding information and an object UUID from a server entry. .LI "\*Lquit\*O" Leaves the RPC control program. .LI "\*Lremove element\*O" Removes selected elements from a profile. .LI "\*Lremove entry\*O" Removes an entry from the name service database. .LI "\*Lremove group\*O" Removes all group members and the group from the specified entry. .LI "\*Lremove mapping\*O" Removes specified elements from the local endpoint map or from the endpoint map of a specified remote host. .LI "\*Lremove member\*O" Removes a selected member from a group. .LI "\*Lremove profile\*O" Removes all profile elements and the profile from the specified entry. .LI "\*Lshow entry\*O" Shows the NSI attributes of an entry. .LI "\*Lshow group\*O" Shows the members of a group. .LI "\*Lshow mapping\*O" Shows the elements of the local endpoint map. .LI "\*Lshow profile\*O" Shows the elements of a profile. .LI "\*Lshow server\*O" Shows the binding information, interface identifier, and object UUIDs in a server entry. .LI "\*Lunexport\*O" Removes binding information, interface identifiers, and object UUIDs from a server entry. .iX "-]" "\*Lrpccp\*O commands" "summary" .LE .LE .SH NOTES .zA "def,10220,R1.1,Remove reference to rpcd and sec_clientd" This facility is superceded by the DCE control program (\*Ldcecp\*O) for OSF DCE version 1.1. .zZ "def,10220,R1.1,Remove reference to rpcd and sec_clientd" .P A \*Lserver entry\*O equates to an NSI binding attribute and, optionally, an object attribute; a \*Lgroup\*O equates to an NSI group attribute; and a \*Lprofile\*O equates to an NSI profile attribute. Typically, each server's entries, groups, and profiles reside in distinct name service entries. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTES" With the exception of the \*Lrpccp_help\*O subcommand, this command is replaced at Revision 1.1 by the \*Ldcecp\*O command. This command may be fully replaced by the \*Ldcecp\*O command in a future release of DCE, and may no longer be supported at that time. .zZ "defect, 11818, R1.1, Added caveat" .SH "DESCRIPTION" .PP .iX "Name Service Interface (NSI)" "managing for RPC applications" .iX "endpoint maps" "managing" The RPC control program (RPCCP) provides a set of commands for managing name service use for RPC applications and for managing the endpoint map. .P You can use control program commands from within the control program or from the system prompt (represented here as a $). .P To use the control program commands from inside the control program, Start and enter the control program using the \*Lrpccp\*O command alone, without any argument. The control program then displays the control program prompt (\*Crpccp>\*O), as follows: .iS \*C$ \*Lrpccp \*O \*Crpccp> \*O .iE You can then enter any control program command, for example: .zA "defect,5989,R1.0.2, Correct entry name syntax" .iS \*Crpccp> \*Lshow entry /.:/LandS/anthro/pr_server_node3\*O .iE .zZ "defect,5989,R1.0.2, Correct entry name syntax" You leave the control program and return to the system prompt using the \*Lexit\*O or \*Lquit\*O command. .P If you enter invalid input, the control program displays the valid commands. .P To use the control program commands from the system prompt, enter the \*Lrpccp\*O command with an internal command of the control program as the first argument. You can do this either interactively or in a command procedure. For example, you can enter the \*Lshow entry\*O command as follows: .zA "defect,5989,R1.0.2, Correct entry name syntax" .iS \*C$ \*Lrpccp show entry /.:/LandS/anthro/pr_server_node3\*O .iE .zZ "defect,5989,R1.0.2, Correct entry name syntax" .SS "Arguments and Options" Except for the \*Lexit\*O and \*Lquit\*O commands, \*Lrpccp\*O commands have one or more options. Each option is identified by a - (dash) followed by a letter; for example, \*L-s\*O. Some options require arguments. .P Commands that access NSI operations also require the name of a name service entry as an argument. The order of arguments and the entry-name option is arbitrary; for example, the following placements of arguments and options are equivalent: .zA "defect,7517,R1.0.3, used add element so example makes sense" .zA "defect,5240,R1.0.2, The add_entry routine does not support the -i option" .zA "defect,5989,R1.0.2, Correct entry name syntax" .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS \*Crpccp> \*Ladd element /.:/LandS/anthro/mis_node_2 \\ \*C> \*L-i ec1eeb60-5943-11c9-a309-08002b102989,1.0\*O .sp \*Crpccp> \*Ladd element -i ec1eeb60-5943-11c9-a309-08002b102989,1.0\*O \\ \*C> \*L/.:/LandS/anthro/mis_node_2\*O .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .zZ "defect,5989,R1.0.2, Correct entry name syntax" .zZ "defect,5240,R1.0.2, The add_entry routine does not support the -i option" .zZ "defect,7517,R1.0.3, used add element so example makes sense" ...\" When an option without an argument precedes another option, separate ...\" them with a hyphen (-). .SS "Environmental Influences on Command Syntax" There are variations in the action of the control program, depending on whether commands are entered from the system prompt or from within the control program. For example, entering the annotation field of profile elements from the system prompt allows you to include internal spaces in an annotation. .P .zA "defect,7518,R1.0.3,Changed footnote to note" .TS center, box, tab(%); lb |lb |lb l |l |l. Function%At System Prompt%Inside Control Program _ T{ Strings within quotation marks T}%Supported%Not required .sp 4p T{ Wildcard substitution T}%Supported%Unsupported _ .TE .PP .nS note Some UNIX systems require that you place an escape symbol (\*L\e\*O) before string binding delimiters such as brackets (\*L[ ]\*O) or that you place the delimiters within quotation marks (\*L' '\*O or \*L'' ''\*O) at the system prompt. .nE .zZ "defect,7518,R1.0.3,Changed footnote to note" .PP The following table describes the scope of the RPC control program commands. .iX "-[" "\*Lrpccp\*O commands" "scope" .P .zA "defect,7587,R1.0.2a,added add mapping" .TS box, center, tab(%); lB |lB l |lB. Scope%Command _ % All entries%add entry %remove entry %show entry % Server entry%export %import %show server %unexport % Group%add member %remove group %remove member %show group % Profile%add element %remove element %remove profile %show profile % Endpoint map%add mapping %remove mapping %show mapping _ .TE .iX "-]" "\*Lrpccp\*O commands" "scope" .zZ "defect,7587,R1.0.2a,added add mapping" ...\" the ~/rpc/concepts/*.gpsml include files are shared with the ...\" NSI usage chapter of RPC Part A of the Appl. Devel. Gde. .SS "Environment Variables" .iX "-[" "RPC control program" "enviornment variables" .iX "-[" "variables" "in \*Lrpccp\*O" The control program supports environment variables. Using environment variables facilitates interactive use of the control program. .P To distinguish environment variables, \*Lrpccp*(1m)\*O reference pages follow the convention of using all uppercase letters for examples of environment variables. Note that UNIX environment variables are case sensitive. .VL .5i .LI "\*LUser-defined environment variables\*O" You can set an environment variable to represent values to \*Lrpccp\*O. Using an environment variable is helpful for specifying a long string such as the following: .ML .LI A string representation of binding information (\*Lbinding string\*O) .LI A string representation of an object or interface UUID (\*Lstring UUID\*O) .LI An \*Linterface identifier\*O (the interface UUID and version numbers) .LI The name of a name service entry .zA "defect,5989,R1.0.2, Correct entry name syntax" .zA "defect,7519,R1.0.3, Change to sh/ksh example" .P For example, in the following example, the environment variable \*LJANE_CAL\*O represents an object UUID; the target name service entry, \*L/.:/LandS/anthro/Cal_host_2\*O, is in the local cell: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS \*C$ \*LJANE_CAL=47f40d10-e2e0-11c9-bb29-08002b0f4528 \*C$ \*Lexport JANE_CAL .sp \*C$ \*Lrpccp \*Crpccp> \*Lexport -o JANE_CAL /.:/LandS/anthro/Cal_host_2\*O .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .zZ "defect,5989,R1.0.2, Correct entry name syntax" .zZ "defect,7519,R1.0.3, Change to sh/ksh example" .LE .LI "\*LDCE RPC environment variables\*O" .VL .LI "\*LNLSPATH\*O" The environment variable \*LNLSPATH\*O must point to the location of \*Ldcerpc.cat\*O and \*Ldcedcs.cat\*O. Otherwise, any run-time status codes returned by the control program will be hexadecimal, rather than textual. form. The value of this variable must include both the pathname of the directory where the \*L.cat\*O files reside and the string \*L%N\*O. .LI \*LRPC_DEFAULT_ENTRY_SYNTAX\*O .iX "local names" "overriding CDS syntax" .iX "Name Service Interface (NSI)" The \*Ldce\*O name syntax is the only syntax currently supported by the DCE Cell Directory Service (CDS). However, the Name Service Interface (NSI) is independent of any specific name service and, in the future, may support name services that use other name syntaxes. When alternative name syntaxes are supported, you can override the standard default with a process-specific default by setting the \*LRPC_DEFAULT_ENTRY_SYNTAX\*O environment variable. When this variable is set for a process, the control program uses it to find out the default syntax for the process. You can override this default in any NSI command of the control program by using the \*L-s\*O option to specify an alternative entry syntax. .p Setting \*LRPC_DEFAULT_ENTRY_SYNTAX\*O requires specifying the integer 3 to indicate the \*Ldce\*O syntax. .zA "defect,7519,R1.0.3, Change to sh/ksh example" To set \*LRPC_DEFAULT_ENTRY_SYNTAX\*O, use the \*Vname\*L=\*Vvalue\*O command to define an environment variable. The following command specifies \*Ldce\*O as the default name syntax in a login command file: .iS # .login command file # setting dce as default name syntax, RPC_DEFAULT_ENTRY_SYNTAX=3 .iE .zZ "defect,7519,R1.0.3, Change to sh/ksh example" .LI "\*LRPC_DEFAULT_ENTRY\*O" For the \*Limport\*O command, you can use this environment variable to indicate the entry where the search operation starts. Usually, the starting entry is a profile. .iX "-]" "RPC control program" "enviornment variables" .iX "-]" "variables" "in \*Lrpccp\*O" .LE .LE .SS "The Name Service Interface" .PP .iX "-[" "Name Service Interface (NSI)" "command syntax" The remainder of this description contains information to help you use commands that call the name service interface to access name service entries (\*LNSI commands\*O). .P The DCE RPC name service interface (NSI) is independent of any particular name service. CDS, however, is the only name service available for DCE RPC Version 1.0 applications. For more details on the name service interface, see the \*(Dk. For a description of the DCE Cell Directory Service, see the \*(Ac. .SS "Name Service Entries" ...\" "Name Service Entries Defined by the RPC Name Service Interface" ...\ ~/rpc/concepts/ns-entries-of-NSI.gpsml To store information about RPC servers, interfaces, and objects, the NSI defines the following name service entries: .VL ...\" .gL "server entry" .LI "\*Lserver entry\*O " Stores binding information, interface identifiers, and object UUIDs for an RPC server ...\" .LI "o" ...\" .gL "group" .LI "\*Lgroup\*O " Corresponds to one or more RPC servers that offer a common RPC interface, type of RPC object, or both ...\" .LI "o" ...\" .gL "profile" .LI "\*Lprofile\*O " Defines search paths for looking in a name service database for a server that offers a particular RPC interface and object .LE .P Note that when the NSI is used with the Cell Directory Service, the name service entries are CDS object entries .SS "Structure of Entry Names" Each entry in a name service database is identified by a unique \*Lglobal name\*O made up of a cell name and a cell-relative name. .P A \*Lcell\*O is a group of users, systems, and resources that share common DCE services. A cell configuration includes at least one cell directory server, one security server, and one time server. A cell's size can range from one system to thousands of systems. For information on cells, see the CDS portion of this book. .P The following is an example of a global name: .iX "-[" "global names" "conventions" .iS /.../C=US/O=uw/OU=MadCity/LandS/anthro/Stats_host_2\*O .iE The parts of a global name are as follows: .VL .iX "cell names" "conventions" .iX "local names" "conventions" .LI "\*LCell name\*O (using X.500 name syntax)" For example: .oS /.../C=US/O=uw/OU=MadCity\*O .oE The symbol \*L/...\*O begins a cell name. The letters before the equal signs (=) are abbreviations for country (C), organization (O), and organization unit (OU). .P For entries in the local cell, the cell name can be represented by a \*L/.:\*O prefix, in place of the actual cell name; for example, .iS /.:/LandS/anthro/Stats_host_2 .iE For NSI operations on entries in the local cell you can omit the cell name. .LI "\*LCell-relative name\*O" ...\" .gL "cell-relative name" .PP .iX "directory pathnames" "conventions" Each name service entry requires a cell-relative name, which contains a directory pathname and a leaf name. .VL .LI "\*Ldirectory pathname\*O " Follows the cell name and ...\" .gL "directory pathname" indicates the hierarchical relationship of the entry to the cell root. .P The directory pathname is the middle portion of the global name. The cell name is to the left of the directory pathname, and the leaf name is to the right, as follows: .P \*Vcell-name\*O \*L+\*O \*Vdirectory-pathname\*O \*L+\*O \*Vleaf-name\*O .P The directory pathname contains the names of any subdirectories in the path; each subdirectory name begins with a slash (/), as follows: .P /\*Vsub-dir-a-name\*O/\*Vsub-dir-b-name\*O/\*Vsub-dir-c-name\*O .P Directory paths are created by name service administrators. If an appropriate directory path does not exist, ask your name service administrator to extend an existing path or create a new path. In a directory path, the name of a subdirectory should reflect its relationship to its \*Lparent directory\*O (the directory that contains the subdirectory). ...\" .gL "leaf name" .iX "-[" "leaf names" "conventions" .LI "\*Lleaf name\*O" Identifies the specific entry. The leaf name is the right-hand part of global name beginning with the rightmost slash. .LE .P In the following example, \*L /.../C=US/O=uw/OU=MadCity\*O is the cell name, \*L/LandS/anthro\*O is the directory pathname, and \*L/Cal_host_4\*O is the leaf name. .iS /.../C=US/O=uw/OU=MadCity/LandS/anthro/Cal_host_4, .iE .P .zA "defect,8217,R1.0.3,changed cell_profile" If a name service entry is located at the cell root, the leaf name directly follows the cell name; for example, \*L/.:/cell-profile\*O. .zZ "defect,8217,R1.0.3,changed cell_profile" .LE .P Note that when the NSI is used with CDS, the cell-relative name is a CDS name. .iX "-]" "leaf names" "conventions" .iX "-]" "global names" "conventions" .LE .SS "Guidelines for Constructing Names of Name Service Entries" .P .iX "-[" "Name Service Interface (NSI)" "naming guidelines" A global name includes both a cell name and a cell-relative name composed of a directory pathname and a leaf name. The cell name is assigned to a cell root at its creation. When you specify only a cell-relative name to an NSI command, the NSI automatically expands the name into a global name by inserting the local cell name. When returning the name of a name service entry, a group member, or member in a profile element, NSI operations return global names. .sp The directory pathname and leaf name uniquely identify a name service entry. The leaf name should somehow describe the entry; for example, by identifying its owner or its contents. The remainder of this section contains guidelines for choosing leaf names. Note that directory pathnames and leaf names are case sensitive. .VL .LI "\*LNaming a Server Entry\*O" .sp .iX "servers" "naming" For a server entry that advertises an RPC interface or service offered by a server, the leaf name must distinguish the entry from the equivalent entries of other servers. When a single server instance runs on a host, you can ensure a unique name by combining the name of the service, interface (from the interface definition), or the system name for the server's host system. .P For example, consider two servers, one offering a calendar service on host JULES and one, on host VERNE. .P The server on JULES uses the following leaf name: .iS calendar_JULES\*O .iE The server on VERNE uses the following leaf name: .iS calendar_VERNE\*O .iE For servers that perform tasks on or for a specific system, an alternative approach is to create server entries in a system-specific host directory within the name service database. Each host directory takes the name of the host to which it corresponds. Because the directory name identifies the system, the leaf name of the server entry name need not include the host name, for example: .sp .iS /.:/LandS/host_1/Process_control\*O .iE .P To construct names for the server entries used by distinctive server instances on a single host, you can construct unique server entry names by combining the following information: the name of the server's service, interface, or object; the system name of the server's host system, and a reusable instance identifier, such as an integer. .P For example, the following leaf names distinguish two instances of a calendar service on the JULES system: .iS calendar_JULES_01 .sp calendar_JULES_02 \*O .iE .P Avoid automatically generating entry names for the server entries of server instances, for example, by using unique data such as a time stamp (\*Lcalendar_verne_15OCT91_21:25:32\*O) or a process identifier (\*Lcalendar_jules_208004D6\*O). When a server incorporates such unique data into its server entry names, each server instance creates a separate server entry, causing many server entries. When a server instance stops running, it leaves an obsolete server entry that is not reused. The creation of a new entry whenever a server instance starts may impair performance. .PP A server can use multiple server entries to advertise different combinations of interfaces and objects. For example, a server can create a separate server entry for a specific object (and the associated interfaces). The name of such a server entry should correspond to a well-known name for the object. For example, consider a server that offers a horticulture bulletin board known to users as \*Lhorticulture_bb\*O. The server exports the \*Lhorticulture_bb\*O object, binding information, and the associated bulletin-board interface to a server entry whose leaf name identifies the object, as follows: .iS horticulture_bb\*O .iE Note that an RPC server that uses RPC authentication can choose identical names for its principal name and its server entry. Use of identical names permits a client that calls the \*Lrpc_binding_set_auth_info\*O routine to automatically determine a server's principal name (the client will assume the principal name to be the same as the server's entry name). If a server uses different principal and server entry names, users must explicitly supply the principal name. For an explanation of principal names, see the DCE Security Service part of the \*EDCE Application Development Guide\*O. .LI "\*LNaming a Group\*O" .P .iX "groups" "naming" The leaf name of a group should indicate the interface, service, or object that determines membership in the group. For example, for a group whose members are selected because they advertise an interface named \*LStatistics\*O, the following is an effective leaf name: .iS Statistics\*O .iE For a group whose members advertise laser-printer print queues as objects, the following is an effective leaf name: .iS laser-printer\*O .iE .LI "\*LNaming a Profile\*O" .P .iX "profiles" "naming" The leaf name of a profile should indicate the profile users; for example, for a profile that serves the members of an accounting department, the following is an effective leaf name: .iS accounting_profile .iX "-]" "Name Service Interface (NSI)" "naming guidelines" .iE .LE .SS "Privilege Required" To use the NSI commands to access entries in a CDS database, you need \*Laccess control list\*O (\*LACL\*O) permissions. Depending on the NSI operation, you need ACL permissions to the parent directory or the CDS object entry (the name service entry) or both. The ACL permissions are as follows: .ML .LI To create an entry, you need insert permission to the parent directory. .LI To read an entry, you need read permission to the CDS object entry. .LI To write to an entry, you need write permission to the CDS object entry. .LI To delete an entry, you need delete permission either to the CDS object entry or to the parent directory. .LE .PP Note that write permission does not imply read permission. .PP ACL permissions for the NSI commands of the control program are described in the reference pages. .SH "EXAMPLES" .ft R The following command starts the RPC control program: .zA "defect,5989,R1.0.2, Correct entry name syntax" .iS \*C$ \*Lrpccp\*O \*Crpccp>\*O .iE The following command at the system prompt removes the entry \*L/.:/LandS/anthro/Cal_host_2\*O: .iS \*C$ \*Lrpccp remove entry \\ \*C> \*L/.:/LandS/anthro/Cal_host_2\*O .iE .zZ "defect,5989,R1.0.2, Correct entry name syntax" .SH "RELATED INFORMATION" .zA "defect,7587,R1.0.2a,added add mapping" .zA "def,10220,R1.1,Remove reference to rpcd and sec_clientd, added dcecp" Commands: \*Ldcecp\*O, \*Ladd element(1m)\*O, \*Ladd entry(1m)\*O, \*Ladd mapping(1m)\*O, \*Ladd member(1m)\*O, \*Lexport(1m)\*O, \*Limport(1m)\*O, \*Lremove element(1m)\*O, \*Lremove entry(1m)\*O, \*Lremove group(1m)\*O, \*Lremove mapping(1m)\*O, \*Lremove member(1m)\*O, \*Lremove profile(1m)\*O, \*Lshow entry(1m)\*O, \*Lshow group(1m)\*O, \*Lshow mapping(1m)\*O, \*Lshow profile(1m)\*O, \*Lshow server(1m)\*O, \*Lunexport(1m)\*O .zZ "defect,7587,R1.0.2a,added add mapping" .zZ "def,10220,R1.1,Remove reference to rpcd and sec_clientd, added dcecp" .iX "-]" "Name Service Interface (NSI)" "command syntax" .iX "-]" "RPC control program" "initializing" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_add_element_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "add element"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Ladd element\*O" .iX "-[" "profiles" "adding elements" .SH NAME \*Ladd element\*O - Adds an element to a profile in a name service entry; if the specified entry does not exist, creates the entry. .SH "SYNOPSIS" .sS \*Lrpccp add element\*O \*V profile-entry-name\*O \*L-m\*O \*Vmember\*O {\*L-d\*O | \*L-i\*O \*Vif-id\*O [\*L-p\*O \*V priority\*O]} .nL [\*L-a\*O \*Vannotation\*O] [\*L-s\*O \*V syntax \*O] .sE .SH "OPTIONS" .VL .LI "\*L-m\*O" Defines a member name for the profile element to be added (required). .LI "\*L-d\*O" Performs the \*Ladd element\*O operation on the default profile element. With the \*L-d\*O option, the \*L-i\*O and \*L-p\*O options are ignored. .LI "\*L-i\*O" Defines an interface identifier for the profile element to be added. Only one interface can be added in a single operation. An interface identifier is required, unless the default profile element is being added. With the \*L-d\*O option, the \*L-i\*O option is ignored. .P The value has the following form: .iS \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .iE The UUID is a hexadecimal string and the version numbers are a decimal string, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .oS -i ec1eeb60-5943-11c9-a309-08002b102989,3.11 .oE .zZ "defect,6742,R1.0.2,lowercase UUIDs" Leading zeros in version numbers are ignored. .LI "\*L-p\*O" Defines a search priority for the new profile element. The priority value is in the range 0 to 7, with zero having the highest priority. When a default element is added (with the \*L-d\*O option), the \*L-p\*O option is ignored. By default, a nondefault element is assigned a priority value of zero. .LI "\*L-a\*O" Defines an annotation string for the profile element. .P Note that the shell supports quotation marks around the annotation field of profile elements, which allows you to include internal spaces in an annotation; the control program does not. To specify or refer to annotations from within the control program, limit each annotation to an unbroken alphanumeric string; for example, \*LCalendarGroup\*O. To refer to annotations from the system prompt, do not incorporate quotation marks into any annotation. .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .LE .SH "ARGUMENTS" .VL .LI "\*Vprofile-entry-name\*O" .nL Specifies the entry name of the target profile. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" The \*Ladd element\*O command adds an element to a profile in a name service entry. The name of the entry containing the profile and the entry name of the profile member in the new element are required. The entry of a profile may have been created previously (by either the \*Ladd entry\*O or \*Ladd element\*O command). But, if the specified entry does not exist, the \*Ladd element\*O command tries to create the entry. .P A profile element is a database record containing the following fields: .VL .LI "\*LInterface identifier\*O" .nL This is the primary search key. The ...\" .gL "interface identifier" interface identifier consists of the interface UUID and the interface version numbers. .LI "\*LMember name\*O" .nL The entry name of one of the following kinds of name service entries: .ML .LI A server entry for a server offering the requested RPC interface and object .LI A group corresponding to the requested RPC interface .LI A profile .LE .LI "\*LPriority value\*O" .nL The priority value (0 (zero) is the highest priority; 7 is the lowest) is designated by the creator of a profile element to help determine the order for using the element. NSI search operations select among like priority elements at random. For the \*Lrpccp add element\*O command, the default is 0. .LI "\*LAnnotation string\*O" .nL The annotation string enables you to identify the purpose of the profile element. The annotation can be any textual information, for example, an interface name associated with the interface identifier or a description of a service or resource associated with a group. The annotation string is not a search key for the import or lookup operations. .LE .SS "Privilege Required" ...\"add element You need both read permission and write permission to the CDS object entry (the target profile entry). If the entry does not exist, you also need insert permission to the parent directory. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .zA "defect,8217,R1.0.3,changed cell_profile" The following command adds an element to the cell profile, \*L/cell-profile\*O, in the local cell: .zA "defect,5989,R1.0.2, Correct entry name syntax" .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS \*C$ \*Lrpccp \*Crpccp> \*Ladd element \\ \*C> \*L-i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \\ \*C> \*L-m /.:/Calendar_profile \\ \*C> \*L-a RefersToCalendarGroups \\ \*C> \*L/.:/cell-profile\*O .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .zZ "defect,5989,R1.0.2, Correct entry name syntax" The following control program commands start the control program, set up a user profile associated with the cell profile as its default element, and add a user-specific element for the Calendar V1.1 interface, as follows: .zA "defect,5989,R1.0.2, Correct entry name syntax" .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS \*C$ \*Lrpccp \*Crpccp> \*L add element /.:/LandS/anthro/molly_o_profile \\ \*C> \*L-d -m /.:/cell-profile \*Crpccp> \*Crpccp> \*L add element /.:/LandS/anthro/molly_o_profile \\ \*C> \*L-m /.:/LandS/anthro/Calendar_group \\ \*C> \*L-i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \\ \*C> \*L-a Calendar_Version 1.1_Interface \*Crpccp> .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .zZ "defect,8217,R1.0.3,changed cell_profile" .P The added profile element contains the global name of the member (specified using its cell-relative name, \*L/.:/LandS/anthro/Calendar_group)\*O and the RPC interface identifier for the Calendar Version 1.1 interface. .zZ "defect,5989,R1.0.2, Correct entry name syntax" .SH "RELATED INFORMATION" Commands: \*Lremove element(1m)\*O, \*Lremove profile(1m)\*O, \*Lshow profile(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Ladd element\*O" .iX "-]" "profiles" "adding elements" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_add_entry_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "add entry"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Ladd entry\*O" .iX "-[" "RPC control program" "adding entries to namespace" .SH NAME \*Ladd entry\*O - Adds a name service entry to the name service database .SH "SYNOPSIS" .sS \*Lrpccp add entry\*O \*V entry-name\*O [\*L-s\*O \*Vsyntax\*O] .sE .SH "OPTIONS" .VL .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .LE .SH "ARGUMENTS" .VL .LI "\*Ventry-name\*O" Specifies the name of the target name service entry. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" The \*Ladd entry\*O command adds an unspecialized entry to the name service database. The name of the entry is required. .P The new entry initially contains no NSI attributes. This command creates a general name service entry for an application or user. The application or user can later use the \*Lexport\*O, \*Ladd element\*O, and \*Ladd member\*O commands to make the generic entry into a server entry, a group, or a profile (or a combination), as follows: .ML .LI For a server entry, specify the new entry as the target entry for the \*Lrpccp export\*O command. .LI For a group, specify the new entry as the target group for the \*Lrpccp add member\*O command. .LI For a profile, specify the new entry as the target profile for the \*Lrpccp add element\*O command. .LE .P The add entry command enables administrators to add entries for users who lack the required permissions. If you have the permissions required by the \*Ladd entry\*O command, you can also add an entry using an \*Lexport\*O, \*Ladd member\*O, or \*Ladd element\*O command; if the entry you specify does not exist, the command creates the entry. .SS "Privilege Required" .PP ...\"add entry To add an entry, you need insert permission to the parent directory and both read permission and write permission to the CDS object entry (the target name service entry). .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" The following commands start RPCCP and add an unspecialized entry to the name service database: .zA "defect,5533,R1.0.2, Correct entry name syntax" .iS \*C$ \*Lrpccp \*Crpccp> \*Ladd entry \\ \*C> \*L/.:/LandS/anthro/Cal_host_2\*O .iE The following command operates from the system prompt to add an unspecialized entry to the name service database: .iS \*C$ \*Lrpccp add entry \\ \*C> \*L/.:/LandS/anthro/Cal_host_3\*O .iE .zZ "defect,5533,R1.0.2, Correct entry name syntax" .SH "RELATED INFORMATION" Commands: \*Lremove entry(1m)\*O, \*Lshow entry(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Ladd entry\*O" .iX "-]" "RPC control program" "adding entries to namespace" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH "add mapping"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Ladd mapping\*O" .iX "-[" "endpoint maps" "add or replace server address information" .zA "defect,8126,7587,R1.0.2a,new reference page" .SH NAME \*Ladd mapping\*O - Adds or replaces server address information in the local endpoint map .SH "SYNOPSIS" .sS \*Lrpccp add mapping\*O \*L-b \*Vstring-binding\*O \*L-i \*Vinterface-identifier\*O [\*L-a \*Vannotation-string\*O] .nL [\*L-o \*Vobject-uuid\*O] [\*L-N\*O] .sE ...\" ...\" ---------------------------------------------------------------------- .SH "OPTIONS" .VL .LI "\*L-b\*O" Specifies a string representation of a binding over which the server can receive remote procedure calls. At least one binding is required. .P The value has the form of an RPC string binding, without an object UUID, for example: .iS -b ncadg_ip_udp:63.0.2.17[5347] .iE .P Note that depending on your system, string binding delimiters such as brackets (\*L[ ]\*O) may need to be preceded by an escape symbol (\\) or placed within quotation marks (\*L' '\*O or \*L`` ''\*O). Requirements vary from system to system, and you must conform to the usage rules of a system. .LI "\*L-i\*O" Specifies an interface identifier to register with the local endpoint map. An interface identifier is required. Only one interface can be added (i.e., registered) in a single operation. The interface identifier has the following form: .iS \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .iE .P The UUID is a hexadecimal string and the version numbers are decimal strings, for example: ...\" .iS -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 .iE ...\" .P Leading zeros in version numbers are ignored. ...\" ...\" .LI "\*L-a\*O" Specifies a character string comment to be applied to each cross product element that is added to the local endpoint map. The string can be up to 64 characters long, including the \*LNULL\*O terminating character. .P The string is used by applications for informational purposes only. The RPC runtime does not use this string to determine which server instance a client communicates with, or for enumerating endpoint map elements. .LI "\*L-o\*O" Defines an object UUID that further determines the endpoint map elements that are removed (optional). Each \*Ladd mapping\*O command accepts up to 32 \*L-o\*O options. .P The UUID is a hexadecimal string, for example: .iS -o 3c6b8f60-5945-11c9-a236-08002b102989 .iE .LI "\*L-N\*O" Specifies that existing elements in the local host's endpoint map should \*Vnot\*O be replaced when the new information is added. .LE .SH "DESCRIPTION" The \*Ladd mapping\*O command adds to, replaces, or adds server address information to the local endpoint map. .P Each element in the local endpoint map logically contains the following: .ML .LI Interface ID, consisting of an interface UUID and versions (major and minor) .LI Binding information .LI Object UUID (optional) .LI Annotation (optional) .LE .P This command should be used without the \*L-N\*O option when only a single instance of the server in question runs on the server's host. Do not use the \*L-N\*O option if no more than one server instance on the host ever offers the same interface UUID, object UUID, and protocol sequence. .P When local endpoint map elements are not replaced, obsolete elements accumulate each time a server instance stops running without explicitly unregistering its endpoint map information. ...\" ...by calling \*Lrpc_ep_unregister(\|)\*O. Periodically, the RPC Daemon (RPCD) will identify these obsolete elements and remove them. However, during the interval between these removals, the presence of the obsolete elements increases the chance that clients will receive endpoints to nonexistent servers. The clients will then waste time trying to communicate with these servers before giving up and obtaining another endpoint. .P Allowing RPCD to replace any existing local endpoint map elements (by not specifying \*L-N\*O) reduces the chance of this happening. ...\" ...\" .P For example, suppose an existing element in the local endpoint map matches the interface UUID, binding information exclusive of the endpoint, and object UUID of an element this routine provides. The routine changes the endpoint map according to the elements' interface major and minor version numbers. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .PP The following command operates from the system prompt to add a map element to the local endpoint map. The command adds the map element that contains the specified interface identifier, server address (specified as a string binding), and object UUIDs. .iS \*C$\*O \*Lrpccp add mapping -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 -b ncadg_ip_udp:63.0.2.17[5347] \e -o 005077d8-8022-1acb-9375-10005a4f533a -o 001bc29a-8041-1acb-b377-10005a4f533a \e -a 'Calendar version 1.1' \*C$\*O .iE .P The previous command adds the following elements: .VL .LI "interface ID" ec1eeb60-5943-1169-a309-08002b102989,1.1 .LI "string binding" ncadg_ip_udp:63.0.2.17[5347] .LI "objects" 005077d8-8022-1acb-9375-10005a4f533a .nL 001bc29a-8041-1acb-b377-10005a4f533a .LI "annotation" Calendar version 1.1 .LE .SH "RELATED INFORMATION" .PP Commands: \*Lexport(1m)\*O, \*Lremove mapping(1m)\*O, \*Lshow mapping(1m)\*O, \*Lshow server(1m)\*O .PP Subroutines: \*Lrpc_ep_register\*O, \*Lrpc_ep_register_no_replace\*O .zZ "defect,8126,7587,R1.0.2a,new reference page" .iX "-]" "\*Lrpccp\*O commands" "\*Ladd mapping\*O" .iX "-]" "endpoint maps" "add or replace server address information" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_add_member_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "add member"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Ladd member\*O" .iX "-[" "groups" "adding members to name service entries" .SH NAME \*Ladd member\*O - Adds a member to a group in a name service entry; if the specified entry does not exist, creates the entry .SH "SYNOPSIS" .sS \*Lrpccp add member\*O \*V group-entry-name\*O \*L-m\*O \*Vmember\*O [\*L-s\*O \*Vsyntax\*O] .sE .SH "OPTIONS" .VL .LI "\*L-m\*O" Declares the name of a member to be added to the specified group entry (required). .P You can add only one member at a time. .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .LE .SH "ARGUMENTS" .VL .LI "\*Vgroup-entry-name\*O" Specifies the name of the target group. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" The \*Ladd member\*O command adds a member to a group in a name service entry. The name of the entry containing the group and the name of the new group member are required. The entry of a group may have been created previously (by either the \*Ladd entry\*O or \*Ladd member\*O command). If the specified entry does not exist, the \*Ladd member\*O command tries to create the entry. .SS "Privilege Required" .PP ...\"add member You need both read permission and write permission to the CDS object entry (the target group entry). If the entry does not exist, you also need insert permission to the parent directory. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .zA "defect,5989,R1.0.2, Correct entry name syntax" The following commands run RPCCP and add the member \*L/.:/LandS/anthro/Cal_host_3\*O to the group \*L/.:/LandS/anthro/Calendar_group\*O: .iS \*C$ \*Lrpccp \*Crpccp> \*Ladd member \\ \*C> \*L-m /.:/LandS/anthro/Cal_host_3 \\ \*C> \*L /.:/LandS/anthro/Calendar_group\*O .iE .zZ "defect,5989,R1.0.2, Correct entry name syntax" .SH "RELATED INFORMATION" Commands: \*Lremove group(1m)\*O, \*Lremove member(1m)\*O, \*Lshow group(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Ladd member\*O" .iX "-]" "groups" "adding members to name service entries" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_export_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "export"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Lexport\*O" .iX "-[" "binding information (RPC)" "exporting to server entries" .SH NAME \*Lexport\*O - Exports binding information for an interface identifier or object UUIDs or both to a server entry; if the specified entry does not exist, creates the entry .SH "SYNOPSIS" .sS \*Lrpccp export\*O \*V entry-name\*O .nL {\*L-i \*Vif-id \*L-b \*Vstring-binding\*O [\*L-b \*Vstring-binding\*O...] \*L-o\*O \*Vobject-uuid\*O [\*L-o \*Vobject-uuid\*O...] | .nL \*L-i \*Vif-id \*L-b \*Vstring-binding\*O [\*L-b\*O...] | \*L-o\*O \*Vobject-uuid\*O [\*L-o \*Vobject-uuid\*O...] \*L }\*O .nL [\*L-s\*O \*V syntax \*O] .sE .SH "OPTIONS" .VL .LI "\*L-i\*O" Declares the interface identifier of an RPC interface. The \*Lexport\*O command operates on only one \*L-i\*O option; if you enter more than one, the command ignores all but the last interface identifier. If you specify an interface identifier, you must specify at least one \*L-b\*O option. The \*L-i\*O and \*L-o\*O options can occur together or separately, but one of them is necessary. .P The interface identifier takes the following form: .iS \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .iE The version numbers are optional, but if you omit a version number, the value defaults to 0. The UUID is a hexadecimal string and the version numbers are decimal strings, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -i ec1eeb60-5943-11c9-a309-08002b102989,3.11 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" Leading zeros in version numbers are ignored. .LI "\*L-b\*O" Declares a string binding (optional). To use this option, you must also specify an interface identifier (using the \*L-i\*O option). Each command accepts up to 32 \*L-b\*O options. .P The value has the form of an RPC string binding, without an object UUID. The binding information contains an RPC protocol sequence, a network address, and sometimes an endpoint within brackets (\*Vrpc-prot-seq\*O:\*Vnetwork-addr\*O[\*Vendpoint\*O]). For a well-known endpoint, include the endpoint in the string binding, for example: .iS -b ncadg_ip_udp:63.0.2.17[5347] .iE .P For a dynamic endpoint, omit the endpoint from the string binding, for example: .iS -b ncacn_ip_tcp:16.20.15.25 .iE .P Note that depending on your system, string binding delimiters such as brackets (\*L[ ]\*O) may need to be preceded by an escape symbol (\\) or placed within quotation marks (\*L' '\*O or \*L`` ''\*O). Requirements vary from system to system, and you must conform to the usage rules of a system. .LI "\*L-o\*O" Declares the UUID of an object. Each \*Lexport\*O command accepts up to 32 \*L-o\*O options. The \*L-i\*O and \*L-o\*O options can occur together or separately, but one of them is necessary. .P The UUID is a hexadecimal string, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -o 3c6b8f60-5945-11c9-a236-08002b102989 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .LE .SH "ARGUMENTS" .VL .LI "\*Ventry-name\*O" Specifies the name of the target name service entry. Usually, the target is a server entry. However, objects also can be exported (without an interface identifier or any binding information) to a group or a profile. .P For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" The \*Lexport\*O command places binding information and an interface identifier, object UUIDs, or both into a server entry, or the command object UUIDs into a group's entry. The \*Lexport\*O command searches the name service database for the entry with the specified entry name. If the entry exists, the command uses it; otherwise, the command tries to create a new name service entry using the specified entry name. .P Minimally, the command requires the name of the entry and either an identifier and binding string or an object. .P If the specified entry does not exist, the \*Lexport\*O command tries to create the entry. .SS "Privilege Required" ...\"export You need both read permission and write permission to the CDS object entry (the target name service entry). If the entry does not exist, you also need insert permission to the parent directory. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .zA "defect,5534,R1.0.2, Correct entry name syntax" This example shows a control program \*Lexport\*O command that is stored in a file for later execution from the system prompt. The command exports two objects and an interface with two string bindings to the server entry \*L/.:/LandS/anthro/Cal_host_3\*O in the local cell: .zA "defect,6742,R1.0.2,lowercase UUIDs" .oS \*L# file to export Calendar 1.1 at installation time rpccp export \\ -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \\ -b ncacn_ip_tcp:16.20.15.25 \\ -b ncadg_ip_udp:63.0.2.17 \\ -o 30dbeea0-fb6c-11c9-8eea-08002b0f4528 \\ -o 16977538-e257-11c9-8dc0-08002b0f4528 \\ /.:/LandS/anthro/Cal_host_3 \*O .oE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .zZ "defect,5534,R1.0.2, Correct entry name syntax" .P The following example shows the use of a user-defined environment variable as an interface identifier, to facilitate entering an export command interactively (in this case, from inside the control program). .LE .zA "defect,7519,R1.0.3, Change to sh/ksh example" .zA "defect,5534,R1.0.2, Correct entry name syntax" The initial two shell commands set up an environment variable \*LCalendar_1_1\*O, which represents the interface identifier of an RPC interface. The \*Lrpccp\*O command then starts the control program, and the \*Lexport\*O command exports the Calendar interface and two string bindings to the server entry \*L/.:/LandS/anthro/Cal_host_2\*O in the local cell, as follows: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS \*C$ \*LCalendar_1_1=ec1eeb60-5943-11c9-a309-08002b102989,1.1 \*C$ \*Lexport Calendar_1_1 \*C$ \*Lrpccp \*Crpccp> \*Lexport -i Calendar_1_1 \\ \*C> \*L-b ncacn_ip_tcp:16.20.15.25 \\ \*C> \*L-b ncadg_ip_udp:63.0.2.17 \\ \*C> \*L/.:/LandS/anthro/Cal_host_2 \*O .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .zZ "defect,5534,R1.0.2, Correct entry name syntax" .zZ "defect,7519,R1.0.3, Change to sh/ksh example" .P The following example shows the use of user-defined environment variables for object UUIDs to facilitate entering an export command interactively (in this case, from inside the control program). .P .zA "defect,7519,R1.0.3, Change to sh/ksh example" .zA "defect,5534,R1.0.2, Correct entry name syntax" The initial shell commands set up the environment variables \*LLUKE_CAL\*O and \*LJOSH_CAL\*O, which represent personal calendars that are accessible as objects to an RPC server. The \*Lrpccp\*O command then starts the control program, and the \*Lexport\*O command exports the two objects to the server's entry \*L/.:/LandS/anthro/Cal_host_2\*O in the local cell: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS \*C$ \*LLUKE_CAL=30dbeea0-fb6c-11c9-8eea-08002b0f4528 \*C$ \*Lexport LUKE_CAL \*C$ \*LJOSH_CAL=16977538-e257-11c9-8dc0-08002b0f4528 \*C$ \*Lexport JOSH_CAL \*C$ \*Lrpccp \*Crpccp> \*Lexport -o LUKE_CAL -o JOSH_CAL \\ \*C> \*L/.:/LandS/anthro/Cal_host_2 \*O .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .zZ "defect,5534,R1.0.2, Correct entry name syntax" .zZ "defect,7519,R1.0.3, Change to sh/ksh example" .SH "RELATED INFORMATION" Commands: \*Limport(1m)\*O, \*Lshow server(1m)\*O, \*Lunexport(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Lexport\*O" .iX "-]" "binding information (RPC)" "exporting to server entries" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" "~/rpc/RPCCP/rpccp_help_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "help"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Lhelp\*O" .SH NAME .PP \*Lhelp\*O - Displays a list of commands or the options of a specified command .SH "SYNOPSIS" .sS \*Lrpccp help\*O [\*Vrpccp-command\*O] .sE .SH "ARGUMENTS" .VL .LI "\*Vrpccp-command\*O" Specifies one of the following control commands: .VL .LI "\*Ladd element\*O" ...\" Adds an element to a profile in a name service entry; if ...\" the specified entry does not exist, creates the entry. .LI "\*Ladd entry\*O" ...\" Adds an entry to the name service database .LI "\*Ladd member\*O" ...\" Adds a member to a group in a name service entry; if ...\" the specified entry does not exist, creates the entry. .LI "\*Lexit\*O" ...\" Leaves the RPC control program. .LI "\*Lexport\*O" ...\" Exports binding information, interface identifiers, and object UUIDs to a server entry .LI "\*Limport\*O" ...\" Imports binding information and an object UUID from a server entry .LI "\*Lquit\*O" ...\" Leaves the RPC control program .LI "\*Lremove element\*O" ...\" Removes selected elements from a profile .LI "\*Lremove entry\*O" ...\" Removes an entry from the name service database .LI "\*Lremove group\*O" ...\" Removes all group members and the group from the specified entry .LI "\*Lremove mapping\*O" ...\" Removes specified elements from the local endpoint map or from the endpoint map of a specified remote host .LI "\*Lremove member\*O" ...\" Removes a selected member from a group .LI "\*Lremove profile\*O" ...\" Removes all profile elements and the profile from the specified entry .LI "\*Lshow entry\*O" ...\" Shows the NSI attributes of an entry .LI "\*Lshow group\*O" ...\" Shows the members of a group .LI "\*Lshow mapping\*O" ...\" Shows the elements of the local endpoint map .LI "\*Lshow profile\*O" ...\" Shows the elements of a profile .LI "\*Lshow server\*O" ...\" Shows the binding information, interface identifiers, and object UUIDs in a server entry .LI "\*Lunexport\*O" ...\" Removes binding information, interface identifiers, and object UUIDs from a server entry .LE .LE .SH "DESCRIPTION" .PP The \*Lhelp\*O command displays information about the RPCCP command set or the options and argument associated with a specific command. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command may be replaced in future releases by the \*Ldcecp\*O command, and may no longer be supported at that time. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" The following command operates from the system prompt to display the internal commands of the control program: .iS \*C$ \*Lrpccp help \*O .iE The following commands start the control program and display the syntax of the \*Lremove entry\*O command: .iS \*C$ \*Lrpccp\*O \*Crpccp> \*Lhelp remove entry\*O .iE .SH "RELATED INFORMATION" Commands: \*Ladd element(1m)\*O, \*Ladd entry(1m)\*O, \*Ladd member(1m)\*O, \*Lexport(1m)\*O, \*Limport(1m)\*O, \*Lremove element(1m)\*O, \*Lremove entry(1m)\*O, \*Lremove group(1m)\*O, \*Lremove mapping(1m)\*O, \*Lremove member(1m)\*O, \*Lremove profile(1m)\*O, \*Lrpccp(1m)\*O, \*Lshow entry(1m)\*O, \*Lshow group(1m)\*O, \*Lshow mapping(1m)\*O, \*Lshow profile(1m)\*O, \*Lshow server(1m)\*O, \*Lunexport(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Lhelp\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_import_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "import"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Limport\*O" .iX "-[" "Name Service Interface (NSI)" "importing binding information" .SH NAME \*Limport\*O - Imports binding information and an object UUID from a server entry .SH "SYNOPSIS" .sS \*Lrpccp\*O \*Limport\*O \*V starting-entry-name\*O \*L-i\*O \*Vif-id\*O [\*L-v\*O \*Vversions\*O] [\*L-e\*O] [\*L-n\*O [\*V integer\*O]] .nL [\*L-o\*O \*Vobject-uuid\*O] [\*L-s\*O \*V syntax\*O] [\*L-u\*O] .sE .SH "OPTIONS" .VL .LI "\*L-i\*O" Defines an interface identifier to be imported (required). You can import only one interface at a time. .P The value has the following form: .sS \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .sE The UUID is a hexadecimal string and the version numbers are decimal strings, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" Leading zeros in version numbers are ignored. .LI "\*L-v\*O" Indicates how a specified interface version is used (optional). If it is used without the \*L-i\*O option, the \*L-v\*O option is ignored. The possible combinations of versions for the \*L-v\*O option and their actions are as follows: .zA "defect,8152,R1.0.3,change upto description" .sp .TS center, box, tab(%); lB| lB lB| lw(3.5i). Versions%Action _ all%T{ The interface version is ignored. T} exact%T{ Both the major and minor versions must match the specified versions. T} compatible%T{ The major version must match the specified version, and the minor version must be greater than or equal to the specified version. T} major_only%T{ The major version must match the specified version; the minor version is ignored. T} upto%T{ The major version must be less than or equal to that specified. If the major versions are equal, the minor version must be less than or equal to that specified. T} _ .TE .zZ "defect,8152,R1.0.3,change upto description" .P If the \*L-v\*O option is absent, the command shows compatible version numbers. .LI "\*L-e\*O" Shows the name of the entry where the binding is found (optional). .LI "\*L-n\*O" Declares that the import operation is to continue until no more potential bindings are found (optional). Providing a numeric value to this option restricts the number of imported bindings. If you omit the number, only one binding is imported. If repeated, this operation may return the same binding. .P For example, \*L-n\*O imports all available bindings, and \*L-n 5\*O imports up to five bindings. Note that the imported bindings are displayed as string bindings. .LI "\*L-o\*O" Declares the UUID of an object to be imported (optional). Only one UUID can occur in a single operation. .P If an object is specified, the import operation limits its search to server entries that contain both the specified interface identifier and object UUID when searching for a potential binding. Without the \*L-o\*O option, the import operation ignores object UUIDs. .P The UUID is a hexadecimal string, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -o 3c6b8f60-5945-11c9-a236-08002b102989 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .sp .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .LI "\*L-u\*O" .zA "defect,7561,R1.0.3,improve -u description" Updates the local CDS cache copy of name service data (optional). .PP Name service data is cached locally on each machine in a cell. If an \*Lrpccp\*O inquiry can be satisfied by data in the local CDS cache, this cached data is returned. Locally cached copies of name service data might not include a recent CDS update, however. If the required data is not available in the local CDS cache, \*Lrpccp\*O goes to a CDS server(s) to retrieve the required data. \*Lrpccp\*O then updates the local CDS cache. .PP Using the \*L-u\*O option bypasses the local cache, allowing \*Lrpccp\*O to go directly to a CDS server for the inquiry. \*Lrpccp\*O then updates the local CDS cache. .zZ "defect,7561,R1.0.3,improve -u description" .LE .SH "ARGUMENTS" .VL .LI "\*Vstarting-entry-name\*O" Indicates the name of the server entry where the import operation starts. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" .sp The \*Limport\*O command imports binding information and an RPC object UUID for a specific RPC interface from a server entry. The name of the entry and the interface identifier are required. The entry name can refer to a server entry, a group, or a profile. .SS "Privilege Required" .PP ...\"import You need read permission to the specified CDS object entry (the starting name service entry) and to any CDS object entry in the resulting search path. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" The following commands run RPCCP and import an interface and object: .zA "defect,5535,R1.0.2, Correct entry name syntax" .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS \*C$ \*Lrpccp \*Crpccp> \*L import -i ec1eeb60-5943-11c9-a309-08002b102989,1.1\\ \*C> \*L-o 30dbeea0-fb6c-11c9-8eea-08002b0f4528 \\ \*C> \*L/.:/LandS/anthro/Cal_host_3\*O .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .zZ "defect,5535,R1.0.2, Correct entry name syntax" .SH "RELATED INFORMATION" Commands: \*Lexport(1m)\*O, \*Lshow server(1m)\*O, \*Lunexport(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Limport\*O" .iX "-]" "Name Service Interface (NSI)" "importing binding information" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_remove_element_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "remove element"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Lremove element\*O" .iX "-[" "profiles" "removing elements" .SH NAME \*Lremove element\*O - Removes selected elements from a profile .SH "SYNOPSIS" .sS \*Lrpccp remove element\*O \*Vprofile-entry-name\*O {\*L-d\*O | \*L-i \*Vif-id \*L-m \*V member\*O | \*L-a \*Vannotation\*O} [\*L-s \*Vsyntax\*O] .sE .SH "OPTIONS" .VL .LI "\*L-d\*O" Removes the default profile element. With the \*L-d\*O option, the \*L-a\*O, \*L-i\*O, and \*L-m\*O options are ignored. .LI "\*L-i\*O" Defines an interface identifier for the profile element to be removed for a member specified with the \*L-m\*O option. Only one interface and member pair can be removed in a single operation. If you supply multiple instances of the \*L-i\*O option, the command uses the final instance. .P The \*L-i\*O and \*L-m\*O options take precedence over the \*L-a\*O option. However, if the default profile element is specified (by the \*L-d\*O option), the \*L-i\*O and \*L-m\*O options are ignored. .P The interface identifier value has the following form: .P \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .P The UUID is a hexadecimal string and the version numbers are decimal strings, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" Leading zeros in version numbers are ignored. .LI "\*L-m\*O" Defines a member name for the profile element to be removed. This option is required if the interface identifier is specified. Only one interface and member can be removed in a single operation. If you supply multiple instances of the \*L-m\*O option, the command uses the final instance. .LI "\*L-a\*O" Removes all elements whose annotation fields match the specified annotation; in the presence of \*L-d\*O option or \*L-i\*O and \*L-m\*O options, the \*L-a\*O option is ignored. .P Note that the shell supports quotation marks around the annotation field of profile elements, which allows you to include internal spaces in an annotation; the control program does not. To specify or refer to annotations from within the control program, limit each annotation to an unbroken alphanumeric string; for example, \*LCalendarGroup\*O. To refer to annotations from the system prompt, do not incorporate quotation marks into any annotation. .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .LE .SH "ARGUMENTS" .VL .LI "\*Vprofile-entry-name\*O" Indicates the name of the target profile. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" The \*Lremove element\*O command removes an element from a profile in the name service database. For a description of the fields in a profile element, see \*Ladd entry(1m)\*O. .P The \*Lremove element\*O command requires the entry name of the profile. The command also requires one of the following options: .VL .LI "\*L-d\*O" The default profile option takes precedence over the other two options. .LI "\*L-i\*O" \*Vinterface-id\*O \*L-m\*O \*Vmember-name\*O An interface and member pair takes precedence over the \*L-a\*O option. .LI "\*L-a\*O \*Vannotation-string\*O" The annotation option takes effect only if neither the \*L-d\*O or \*L-i\*O option is specified. .LE .SS "Privilege Required" ...\"remove element You need read permission and write permission to the CDS object entry (the target profile entry). .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .PP .zA "defect,7519,R1.0.3, Change to sh/ksh example" The initial shell commands set up an environment variable \*LCalendar_1_1\*O, which represents the interface identifier of an RPC interface. The control program commands set up an environment variable for the interface identifier of the Calendar Version 1.1 RPC interface, run RPCCP, and remove an element from a profile, as follows: .zA "defect,5989,R1.0.2, Correct entry name syntax" .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS \*C$ \*LCalendar_1_1=ec1eeb60-5943-11c9-a309-08002b102989,1.1 \*C$ \*Lexport Calendar_1_1 \*C$ \*Lrpccp \*Crpccp> \*Lremove element -i Calendar_1_1 \\ \*C> \*L-m /.:/LandS/anthro/Calendar_group \\ \*C> \*L/.:/LandS/anthro/molly_o_profile\*O .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .zZ "defect,5989,R1.0.2, Correct entry name syntax" .zZ "defect,7519,R1.0.3, Change to sh/ksh example" .SH "RELATED INFORMATION" Commands: \*Ladd element(1m)\*O, \*Lremove profile(1m)\*O, \*Lshow profile(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Lremove element\*O" .iX "-]" "profiles" "removing elements" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_remove_entry_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "remove entry"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lrpccp\*O commands" "\*Lremove entry\*O" .iX "RPC control program" "removing entries" .SH NAME \*Lremove entry\*O - Removes a name service entry from the name service database .SH "SYNOPSIS" .sS \*Lrpccp remove entry\*O \*V entry-name\*O [\*L-s\*O \*Vsyntax\*O] .sE .SH "OPTIONS" .VL .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .LE .SH "ARGUMENTS" .VL .LI "\*Ventry-name\*O" Indicates the name of the target name service entry. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" The \*Lremove entry\*O command removes an entry from the name service database. The name of the entry is required. .SS "Privilege Required" .PP ...\"remove entry You need read permission to the CDS object entry (the target name service entry). You also need delete permission to the CDS object entry or to the parent directory. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .zA "defect,5536,R1.0.2, Correct entry name syntax" The following commands run RPCCP and remove the entry \*L/.:/LandS/anthro/Cal_host_2\*O from the local cell of the name service database: .iS \*C$ \*Lrpccp \*Crpccp> \*Lremove entry /.:/LandS/anthro/Cal_host_2\*O .iE .zZ "defect,5536,R1.0.2, Correct entry name syntax" .SH "RELATED INFORMATION" Commands: \*Ladd entry(1m)\*O, \*Lshow entry(1m)\*O ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_remove_group_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "remove group"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lrpccp\*O commands" "\*Lremove group\*O" .iX "groups" "removing from NSI entry" .SH NAME \*Lremove group\*O - Removes all group members and the group from the specified name service entry .SH "SYNOPSIS" .sS \*Lrpccp remove group\*O \*V group-entry-name\*O .nL [\*L-s\*O \*Vsyntax\*O] .sE .SH "OPTIONS" .VL .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .LE .SH "ARGUMENTS" .VL .LI "\*Vgroup-entry-name\*O" Indicates the name of the target group. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" The \*Lremove group\*O command removes a group from the name service database. The group need not be empty. The entry name of the group is required. .SS "Privilege Required" .PP ...\"remove group You need write permission to the CDS object entry (the target group entry). .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .zA "defect,5539,R1.0.2, Correct entry name syntax" The following commands run RPCCP and remove the group from the name service entry \*L/.:/LandS/anthro/Calendar_group\*O: .iS \*C$ \*Lrpccp \*Crpccp> \*Lremove group /.:/LandS/anthro/Calendar_group \*O .iE .zZ "defect,5539,R1.0.2, Correct entry name syntax" .SH "RELATED INFORMATION" .PP Commands: \*Ladd member(1m)\*O, \*Lremove member(1m)\*O, \*Lshow group(1m)\*O ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_remove_mapping_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "remove mapping"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Lremove mapping\*O" .iX "-[" "endpoint maps" "removing elements" .SH NAME .zA "defect,8672,R1.0.3,remove refs to remote endpoint functionality" \*Lremove mapping\*O - Removes specified elements from the local endpoint map .SH "SYNOPSIS" .sS .zA "defect,8169,R1.0.3,remove -v" \*Lrpccp remove mapping\*O \*L-b \*Vstring-binding \*L-i \*Vinterface-identifier\*O [\*L-o\*O \*Vobject-uuid\*O] .zZ "defect,8169,R1.0.3,remove -v" .sE .zZ "defect,8672,R1.0.3,remove refs to remote endpoint functionality" .SH "OPTIONS" .zA "defect,8672,R1.0.3,remove refs to remote endpoint functionality" .VL .LI "\*L-b\*O" Specifies a string representation of a binding over which the server can receive remote procedure calls. At least one binding is required. .P The value has the form of an RPC string binding, without an object UUID, for example: .iS -b ncadg_ip_udp:63.0.2.17[5347] .iE Note that depending on your system, string binding delimiters such as brackets (\*L[ ]\*O) may need to be preceded by an escape symbol (\\) or placed within quotation marks (\*L' '\*O or \*L`` ''\*O). Requirements vary from system to system, and you must conform to the usage rules of a system. .LI "\*L-i\*O" Specifies an interface identifier to remove from the local endpoint map. An interface identifier is required. Only one interface can be removed in a single operation. The interface identifier has the following form: .sS \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .sE The UUID is a hexadecimal string and the version numbers are decimal strings, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" Leading zeros in version numbers are ignored. .zA "defect,8169,R1.0.3,remove -v" .zA "defect,8152,R1.0.3,change upto description" .zZ "defect,8152,R1.0.3,change upto description" .zZ "defect,8169,R1.0.3,remove -v" .LI "\*L-o\*O" Defines an object UUID that further determines the endpoint map elements that are removed (optional). Each \*Lremove mapping\*O command accepts up to 32 \*L-o\*O options. .P The UUID is a hexadecimal string, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -o 3c6b8f60-5945-11c9-a236-08002b102989 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .LE .zZ "defect,8672,R1.0.3,remove refs to remote endpoint functionality" .SH "DESCRIPTION" .zA "defect,8672,R1.0.3,remove refs to remote endpoint functionality" The \*Lremove mapping\*O command removes server address information from the local endpoint map. Each element in the local endpoint map logically contains the following: .ML .LI Interface ID, consisting of an interface UUID and versions (major and minor) .LI Binding information .LI Object UUID (optional) .LI Annotation (optional) .LE .P This command requires one interface identifier (the \*L-i\*O option); at least one string binding (the \*L-b\*O option); and optionally, one or more object UUIDs (the \*L-o\*O option). Each instance of the command accepts from 1 to 32 \*L-b\*O options and from 0 to 32 \*L-o\*O options. The options work together to delimit the elements to be removed from the target endpoint map. The command removes any map element that contains the specified interface identifier, a specified string binding, and a specified object UUID (if any). .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" The following command operates from the system prompt to remove a map element from the local endpoint map. The command removes only the map element that contains the specified interface identifier, server address (specified as a string binding), and object UUID. .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS \*C$ \*Lrpccp remove mapping \\ \*C> \*L-i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \\ \*C> \*L-b ncadg_ip_udp:16.20.16.64[3424] \\ \*C> \*L-o 30dbeea0-fb6c-11c9-8eea-08002b0f4528 \*O \*C$ \*O .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .zZ "defect,8672,R1.0.3,remove refs to remote endpoint functionality" .SH "RELATED INFORMATION" Commands: \*Ladd mapping(1m)\*O, \*Lshow mapping(1m)\*O, \*Lshow server(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Lremove mapping\*O" .iX "-]" "endpoint maps" "removing elements" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_remove_member_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "remove member"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Lremove member\*O" .iX "-[" "groups" "removing members" .SH NAME \*Lremove member\*O - Removes a specified member from a group .SH "SYNOPSIS" .sS \*Lrpccp remove member\*O \*V group-entry-name\*O .nL \*L-m\*O \*Vmember\*O .nL [\*L-s \*Vsyntax\*O] .sE .SH "OPTIONS" .VL .LI "\*L-m\*O" Declares the entry name of the group member to be removed (required). .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .LE .SH "ARGUMENTS" .VL .LI "\*Vgroup-entry-name\*O" Indicates the name of the target group. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" The \*Lremove member\*O command removes a specified member from a specified group. .SS "Privilege Required" ...\"remove member You need read permission and write permission to the CDS object entry (the target group entry). .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .zA "defect,5989,R1.0.2, Correct entry name syntax" The following commands run RPCCP and remove the member \*L/.:/LandS/anthro/Cal_host_2\*O from the group \*L/.:/LandS/dept/Calendar_group\*O: .iS \*C$ \*Lrpccp \*Crpccp> \*Lremove member \\ \*C> \*L-m /.:/LandS/anthro/Cal_host_2 \\ \*C> \*L/.:/LandS/anthro/Calendar_group \*O .iE The following command removes the member \*L/.:/LandS/anthro/Cal_host_3\*O from the group \*L/.:/LandS/anthro/Calendar_group\*O: .iS \*C$ \*Lrpccp remove member \\ \*C> \*L-m /.:/LandS/anthro/Cal_host_3 \\ \*C> \*L/.:/LandS/anthro/Calendar_group \*O .iE .zZ "defect,5989,R1.0.2, Correct entry name syntax" .SH "RELATED INFORMATION" Commands: \*Ladd member(1m)\*O, \*Lremove group(1m)\*O, \*Lshow group(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Lremove member\*O" .iX "-]" "groups" "removing members" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_remove_profile_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "remove profile"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Lrpccp\*O commands" "\*Lremove profile\*O" .iX "profiles" "removing from namespace" .SH NAME \*Lremove profile\*O - Removes all profile elements and the profile from the specified name service entry .SH "SYNOPSIS" .sS \*Lrpccp remove profile\*O \*V profile-entry-name\*O .nL [\*L-s\*O \*Vsyntax\*O] .sE .SH "OPTIONS" .VL .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .LE .SH "ARGUMENTS" .VL .LI "\*Vprofile-entry-name\*O" Indicates the name of the target profile. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" The \*Lremove profile\*O command removes a profile (and all of its elements) from the name service database. The entry name of the profile is required. .SS "Privilege Required" ...\"remove profile You need write permission to the CDS object entry (the target profile entry). .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .zA "defect,5989,R1.0.2, Correct entry name syntax" The following commands run RPCCP and remove the profile named \*L/.:/LandS/anthro/molly_o_profile\*O: .iS \*C$ \*Lrpccp \*Crpccp> \*Lremove profile /.:/LandS/anthro/molly_o_profile\*O .iE .zZ "defect,5989,R1.0.2, Correct entry name syntax" .SH "RELATED INFORMATION" Commands: \*Ladd element(1m)\*O, \*Lremove element(1m)\*O, \*Lshow profile(1m)\*O ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_show_entry_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "show entry"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Lshow entry\*O" .iX "-[" "Name Service Interface (NSI)" "viewing NSI attributes" .iX "-[" "attributes" "NSI, viewing" .SH NAME \*Lshow entry\*O - Shows the NSI attributes of a name service entry .SH "SYNOPSIS" .sS \*Lrpccp show entry\*O \*V entry-name\*O .nL [\*L-i\*O \*Vif-id\*O] \*V \*O [\*L-s\*O \*Vsyntax\*O] \*V \*O [\*L-u\*O] .sE .SH "OPTIONS" .VL .LI "\*L-i\*O" Selects a specified interface identifier (optional). Only elements containing that identifier are shown. .P The interface identifier value has the following form: .P \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .P The UUID is a hexadecimal string and the version numbers are decimal strings, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" Leading zeros in version numbers are ignored. .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .LI "\*L-u\*O" .zA "defect,7561,R1.0.3,improve -u description" Updates the local CDS cache copy of name service data (optional). .PP Name service data is cached locally on each machine in a cell. If an \*Lrpccp\*O inquiry can be satisfied by data in the local CDS cache, this cached data is returned. Locally cached copies of name service data might not include a recent CDS update, however. If the required data is not available in the local CDS cache, \*Lrpccp\*O goes to a CDS server(s) to retrieve the required data. \*Lrpccp\*O then updates the local CDS cache. .PP Using the \*L-u\*O option bypasses the local cache, allowing \*Lrpccp\*O to go directly to a CDS server for the inquiry. \*Lrpccp\*O then updates the local CDS cache. .zZ "defect,7561,R1.0.3,improve -u description" .LE .SH "ARGUMENTS" .VL .LI "\*Ventry-name\*O" Indicates the name of the target name service entry. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" The \*Lshow entry\*O command shows the NSI attributes of a name service entry. The name of the entry is required. .P Note that this operation shows all of the compatible bindings for a given interface. .P The \*Lshow entry\*O command shows the same list of string bindings as the import operation returns for the specified entry. This list includes all string bindings that refer to a major version that matches the specified version and a minor version that is equal to or greater than the specified version. The list may include string bindings exported for other versions of the interface that are upwardly compatible, rather than for this particular version of the interface. .SS "Privilege Required" ...\"show entry You need read permission to the CDS object entry (the target name service entry). .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .zA "defect,5528,R1.0.2, Correct entry name syntax" The following command operates from the system prompt to show the name service entry \*L/.:/LandS/anthro/calendar_mgr_node_3\*O. .iS \*C$ \*Lrpccp show entry /.:/LandS/anthro/Cal_host_3\*O .iE The following commands run the control program and show the name service entry \*L/.:/LandS/anthro/Calendar_group\*O: .iS \*C$ \*Lrpccp \*Crpccp> \*Lshow entry \\ \*C> \*L/.:/LandS/anthro/Calendar_group \*O .iE .zZ "defect,5528,R1.0.2, Correct entry name syntax" .SH "RELATED INFORMATION" Commands: \*Ladd entry(1m)\*O, \*Lremove entry(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Lshow entry\*O" .iX "-]" "Name Service Interface (NSI)" "viewing NSI attributes" .iX "-]" "attributes" "NSI, viewing" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_show_group_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "show group"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Lshow group\*O" .iX "-[" "groups" "viewing members" .SH NAME \*Lshow group\*O - Shows the members of a group .SH "SYNOPSIS" .sS \*Lrpccp show group\*O \*V group-entry-name\*O .nL [\*L-m\*O \*Vmember\*O] \*V \*O [\*L-r\*O [ \*V integer\*O]] .nL [\*L-s\*O \*Vsyntax\*O] \*V \*O [\*L-u\*O] .sE .SH "OPTIONS" .VL .LI "\*L-m\*O" Declares the name of a single group member. .LI "\*L-r\*O" Indicates that the \*Lshow group\*O operation recurses. If any members of a group are also groups, their entries are shown. By default, the \*L-r\*O option causes the \*Lshow group\*O operation to recurse until all nested groups are expanded; for example, \*L-r\*O shows the members of the specified group and all nested groups. .P You can limit recursion to one or more levels by specifying a decimal integer as part of the \*L-r\*O option. For example, \*L-r 1\*O shows the members of the specified group and, for members that are groups, the command also shows their members; then recursion stops. .sp Without the \*L-r\*O option, only the members of the specified group are shown. .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .LI "\*L-u\*O" .zA "defect,7561,R1.0.3,improve -u description" Updates the local CDS cache copy of name service data (optional). .PP Name service data is cached locally on each machine in a cell. If an \*Lrpccp\*O inquiry can be satisfied by data in the local CDS cache, this cached data is returned. Locally cached copies of name service data might not include a recent CDS update, however. If the required data is not available in the local CDS cache, \*Lrpccp\*O goes to a CDS server(s) to retrieve the required data. \*Lrpccp\*O then updates the local CDS cache. .PP Using the \*L-u\*O option bypasses the local cache, allowing \*Lrpccp\*O to go directly to a CDS server for the inquiry. \*Lrpccp\*O then updates the local CDS cache. .zZ "defect,7561,R1.0.3,improve -u description" .LE .SH "ARGUMENTS" .VL .LI "\*Vgroup-entry-name\*O" Indicates the name of the target group. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" The \*Lshow group\*O command shows the members of a group in the name service database. The entry name of the group is required. Unless it is limited to a specific member (by the \*L-m\*O option), the \*Lshow group\*O command shows all members. The command shows only the members in the specified group; the \*L-r\*O option enables you to show members of nested groups. .SS "Privilege Required" .PP ...\"show group You need read permission to the CDS object entry (the target group entry). If you use the \*L-r\*O option, you also need read permission to any nested groups. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .zA "defect,5538,R1.0.2, Correct entry name syntax" The following example shows all the members of the group \*L/.:/LandS/anthro/Calendar_group\*O, in the order in which they were added to the group: .iS \*C$ \*Lrpccp \*Crpccp> \*Lshow group /.:/LandS/anthro/Calendar_group\*O .iE The following command operates from the system prompt to show a specific member of the group \*L/.:/LandS/dept/Calendar_group\*O: .iS \*C$ \*Lrpccp show group \\ \*C> \*L-m /.:/LandS/anthro/Cal_host_2 \\ \*C> \*L/.:/LandS/anthro/Calendar_group\*O .iE .zZ "defect,5538,R1.0.2, Correct entry name syntax" .SH "RELATED INFORMATION" Commands: \*Ladd member(1m)\*O, \*Lremove group(1m)\*O, \*Lremove member(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Lshow group\*O" .iX "-]" "groups" "viewing members" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_show_mapping_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "show mapping"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Lshow mapping\*O" .iX "-[" "endpoint maps" "viewing elements" .SH NAME \*Lshow mapping\*O - Shows the elements of the either the local or a remote endpoint map .SH "SYNOPSIS" .sS \*Lrpccp show mapping\*O \*V \*O [\*Vhost-address\*O] .nL [\*L-i\*O \*Vif-id\*O \*V \*O [\*L-v\*O \*Vversions\*O]] .nL [\*L-o\*O \*Vobject-uuid\*O [ \*L-o\*O \*Vobject-uuid\*O...]] .sE .SH "OPTIONS" .VL .LI "\*L-i\*O" Defines an interface identifier to be shown (optional). Only one interface can be shown in a single operation. If specified, only elements containing this interface identifier are shown. The \*L-i\*O option can be qualified by the \*L-v\*O option. The value has the following form: .P \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .P The UUID is a hexadecimal string and the version numbers are decimal strings, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" Leading zeros in version numbers are ignored. .LI "\*L-v\*O" Indicates how a specified interface version is used (optional). If it is used without the \*L-i\*O option, the \*L-v\*O option is ignored. The possible combinations of versions for the \*L-v\*O option and their actions are described in the following table. .zA "defect,8152,R1.0.3,change upto description" .PP .ne 20 .TS center, box, tab(%); lB |lB lB |lw(3.5i). _ Versions%Action _ all%T{ The interface version is ignored. T} exact%T{ Both the major and minor versions must match the specified versions. T} compatible%T{ The major version must match the specified version, and the minor version must be greater than or equal to the specified version. T} major_only%T{ The major version must match the specified version; the minor version is ignored. T} upto%T{ The major version must be less than or equal to that specified. If the major versions are equal, the minor version must be less than or equal to that specified. T} _ .TE .zZ "defect,8152,R1.0.3,change upto description" .P If the \*L-v\*O option is absent, the command shows compatible version numbers. .LI "\*L-o\*O" Defines an object to be shown (optional). Each \*Lshow mapping\*O command accepts up to 32 \*L-o\*O options. .P The UUID is a hexadecimal string, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -o 3c6b8f60-5945-11c9-a236-08002b102989 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .LE .SH "ARGUMENTS" .VL .LI "\*Vhost-address\*O" The \*Lhost-address\*O argument is a string binding that indicates where to find the target endpoint map. When accessing the local endpoint map, you can specify which protocol sequence to use (optional); for example, .iS ncadg_ip_udp: .iE When accessing a remote endpoint map, you must specify both a protocol sequence and a network address for the remote system (required); for example, .iS ncadg_ip_udp:16.20.16.44 .iE An endpoint is unnecessary in local or remote host addresses, and the \*Lremove mapping\*O command ignores any endpoint specified as part of a host address. .LE .SH "DESCRIPTION" The \*Lshow mapping\*O command shows elements of an endpoint map. Each element corresponds to an object UUID, interface identifier, annotation, and binding information. The binding information contains an RPC protocol sequence, a network address, and an endpoint within square brackets (\*Vrpc- prot-seq\*O:\*Vnetwork-addr\*O[\*Vendpoint\*O]). .P The endpoint map can be either the local endpoint map or the endpoint map of a specified remote host. If entered without a remote host address, the command accesses the local endpoint map. For the local endpoint map, a \*Lshow mapping\*O command without any options displays all the map elements. For a remote endpoint map, map elements are accessible only for protocol sequences that are supported on both your system and the remote system. .P The options list a selected subset of map elements. The \*L- i\*O option selects a specific interface, and the \*L-v\*O option qualifies the \*L-i\*O option. The \*L-o\*O object selects a specific object. You can use from 0 to 32 \*L-o\*O options per command. The options work together to specify the subset of elements for the target protocol sequence(s). .SH "NOTES" Note that to ensure that you can remotely display all map elements from every remote endpoint map, run the RPC control program on a system that supports all of the protocol sequences available in your network environment. .zA "defect, 11818, R1.1, Added caveat" .P This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" The following commands start the control program and show the map elements in the local endpoint map that contain the specified interface identifier: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS \*C$ \*Lrpccp \*Crpccp> \*Lshow mapping -i ec1eeb60-5943-11c9-a309-08002b102989,1.1\*O .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .P The following \*Lrpccp show mapping\*O command operates from the system prompt. The command accesses the endpoint map of the remote host specified by the host address (ncadg_ip_udp:16.20.16.44) and displays the one map element that contains both the specified interface identifier and the specified object UUID: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS \*C$ \*Lrpccp show mapping \\ \*C> \*L-i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \\ \*C> \*L-o 30dbeea0-fb6c-11c9-8eea-08002b0f4528 \\ \*C> \*Lncadg_ip_udp:16.20.16.44\*O .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .SH "RELATED INFORMATION" Commands: \*Lremove mapping(1m)\*O, \*Lshow server(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Lshow mapping\*O" .iX "-]" "endpoint maps" "viewing elements" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_show_profile_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "show profile"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Lshow profile\*O" .iX "-[" "profiles" "viewing elements" .SH NAME \*Lshow profile\*O - Shows the elements of a profile .SH "SYNOPSIS" .sS \*Lrpccp show profile\*O \*V profile-entry-name\*O .nL {\*L-d\*O \*V \*O | \*V \*O \*L-a\*O \*Vannotation\*O \*V \*O | \*V \*O \*L-i\*O \*Vif-id\*O \*V \*O [\*L-v\*O \*Vversions\*O] \*V \*O \*L-m\*O \*Vmember\*O} .nL [\*L-r\*O [\*Vinteger\*O]] \*V \*O [\*L-s\*O \*Vsyntax\*O] \*V \*O [\*L-u\*O] .sE .SH "OPTIONS" .VL .LI "\*L-d\*O" Selects the default profile element. With the \*L-d\*O option, the \*L-a\*O, \*L-i\*O, and \*L-m\*O options are ignored. .P Note that the \*L-a\*O option works with the \*L-d\*O option, but do not use them together. .LI "\*L-a\*O" Declares a single annotation field (optional). The \*L-a\*O option selects only elements containing the specified annotation. The option is case sensitive. .P The \*L-a\*O option works alone or in combination with the \*L-i\*O or \*L-m\*O options or both; only elements containing all the specified values are displayed. .P Note that the shell supports quotation marks around the annotation field of profile elements, allowing you to include internal spaces in an annotation; the control program does not. To specify or refer to annotations from within the control program, limit each annotation to an unbroken alphanumeric string; for example, CalendarGroup. To refer to annotations from the system prompt, do not incorporate quotation marks into any annotation. .LI "\*L-i\*O" Selects a specified interface identifier (optional). Only elements containing that interface identifier are shown. .P The interface identifier value has the following form: .P \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .P The UUID is a hexadecimal string and the version numbers are decimal strings, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" Leading zeros in version numbers are ignored. .P The \*L-i\*O option works alone or in combination with the \*L-a\*O or \*L-m\*O options or both; only elements containing all the specified values are displayed. When the \*L-d\*O option is specified, the \*L-i\*O option is ignored. .LI "\*L-m\*O" Declares a single member name (optional). Only elements containing that member name are shown. .P The \*L-m\*O option works alone or in combination with the \*L-a\*O or \*L-i\*O options or both; only elements containing all the specified values are displayed. When the \*L-d\*O option is specified, the \*L-m\*O option is ignored. .LI "\*L-r\*O" Indicates that the \*Lshow profile\*O operation recurses. If the member of any element of a profile is also a profile, its elements are shown. By default, the \*L-r\*O option causes the show profile operation to recurse until all nested profiles are expanded; for example, \*L-r\*O shows the elements of the specified profile and of all nested profiles. .P You can limit recursion to one or more levels by specifying a decimal integer as part of the \*L-r\*O option. For example, \*L-r 1\*O shows the elements of the specified profile and, for element members that are profiles, the command also shows their elements; then recursion stops. .P Without the \*L-r\*O option, only the profile elements in the specified entry are shown. .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .zA "CR5268 -- Add description of -u option .LI "\*L-u\*O" .zA "defect,7561,R1.0.3,improve -u description" Updates the local CDS cache copy of name service data (optional). .PP Name service data is cached locally on each machine in a cell. If an \*Lrpccp\*O inquiry can be satisfied by data in the local CDS cache, this cached data is returned. Locally cached copies of name service data might not include a recent CDS update, however. If the required data is not available in the local CDS cache, \*Lrpccp\*O goes to a CDS server(s) to retrieve the required data. \*Lrpccp\*O then updates the local CDS cache. .PP Using the \*L-u\*O option bypasses the local cache, allowing \*Lrpccp\*O to go directly to a CDS server for the inquiry. \*Lrpccp\*O then updates the local CDS cache. .zZ "defect,7561,R1.0.3,improve -u description" .zZ "CR5268 -- Add description of -u option .LI "\*L-v\*O" Indicates how a specified interface version is used (optional). If it is used without the \*L-i\*O option, the \*L-v\*O option is ignored. The possible combinations of versions for the \*L-v\*O option and their actions are described in the following table. .zA "defect,8152,R1.0.3,change upto description" .sp .ne 20 .TS center, box, tab(%); lB| lB lB| lw(3.5i). _ Versions%Action _ all%T{ The interface version is ignored. T} exact%T{ Both the major and minor versions must match the specified versions. T} compatible%T{ The major version must match the specified version, and the minor version must be greater than or equal to the specified version. T} major_only%T{ The major version must match the specified version; the minor version is ignored. T} upto%T{ The major version must be less than or equal to that specified. If the major versions are equal, the minor version must be less than or equal to that specified. T} _ .TE .zZ "defect,8152,R1.0.3,change upto description" .P If the \*L-v\*O option is absent, the command shows compatible version numbers. .LE .SH "ARGUMENTS" .VL .LI "\*Vprofile-entry-name\*O" Indicates the name of the target profile. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" The \*Lshow profile\*O command shows the elements of a profile in the name service database. The entry name of the profile is required. .P By default, all elements in the profile are shown. You can select a subset of the elements by specifying the \*L-a\*O, \*L-i\*O, or \*L-m\*O options. The \*L-r\*O option enables you to show nested profiles. .SS "Privilege Required" .PP ...\"show profile You need read permission to the CDS object entry (the target profile entry). If you use the \*L-r\*O option, you also need read permission to any nested profiles. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .zA "CR5989 -- Correct entry name syntax .zA "defect,8217,R1.0.3,changed cell_profile" The following command operates from the system prompt to show the cell \*Lprofile /.:/cell-profile\*O in the local cell: .iS \*C$ \*Lrpccp show profile /.:/cell-profile\*O .iE .zZ "defect,8217,R1.0.3,changed cell_profile" .zA "defect,7519,R1.0.3, Change to sh/ksh example" .PP The initial shell commands set up an environment variable \*LMOLLY_O_PROFILE\*O, which represents the user profile \*L/.:/LandS/anthro/molly_o_profile\*O. The control program commands start the control program and show the user profile associated with the \*LMOLLY_O_PROFILE\*O environment variable, as follows: .iS \*C$ \*LMOLLY_O_PROFILE=/.:/LandS/anthro/molly_o_profile \*C$ \*Lexport MOLLY_O_PROFILE \*C$ \*Lrpccp \*Crpccp> \*Lshow profile MOLLY_O_PROFILE\*O .iE .zZ "CR5989 -- Correct entry name syntax .zZ "defect,7519,R1.0.3, Change to sh/ksh example" .SH "RELATED INFORMATION" Commands: \*Ladd element(1m)\*O, \*Lremove element(1m)\*O, \*Lremove profile(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Lshow profile\*O" .iX "-]" "profiles" "viewing elements" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_show_server_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "show server"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Lshow server\*O" .iX "-[" "binding information (RPC)" "viewing server entries" .SH NAME \*Lshow server\*O - Shows the binding information, interface identifiers, and object UUIDs in a server entry .SH "SYNOPSIS" .sS \*Lrpccp show server\*O \*V server-entry-name\*O .nL [\*L-i\*O [\*Vif-id\*O]] .nL [\*L-o\*O [\*Vobject-uuid\*O]] .nL [\*L-s\*O \*Vsyntax\*O] [\*L-u\*O] .sE .SH "OPTIONS" .VL .LI "\*L-i\*O" Shows interface identifiers from binding information found in the entry (optional). Without the \*L-i\*O option, the command displays all interface identifiers. .P To display a specific interface, supply its identifier as the value. The value has the following form: .sS \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .sE The UUID is a hexadecimal string and the version numbers are decimal strings, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" Leading zeros in version numbers are ignored. .LI "\*L-o\*O" Shows object UUIDs found in the entry (optional). Without the \*L-o\*O option, the command displays all object UUIDs. To display a specific object UUID, supply its string representation as the value, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -o 3c6b8f60-5945-11c9-a236-08002b102989 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .LI "\*L-u\*O" .zA "defect,7561,R1.0.3,improve -u description" Updates the local CDS cache copy of name service data (optional). .PP Name service data is cached locally on each machine in a cell. If an \*Lrpccp\*O inquiry can be satisfied by data in the local CDS cache, this cached data is returned. Locally cached copies of name service data might not include a recent CDS update, however. If the required data is not available in the local CDS cache, \*Lrpccp\*O goes to a CDS server(s) to retrieve the required data. \*Lrpccp\*O then updates the local CDS cache. .PP Using the \*L-u\*O option bypasses the local cache, allowing \*Lrpccp\*O to go directly to a CDS server for the inquiry. \*Lrpccp\*O then updates the local CDS cache. .zZ "defect,7561,R1.0.3,improve -u description" .LE .SH "ARGUMENTS" .VL .LI "\*Vserver-entry-name\*O" Indicates the name of the target server. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" The \*Lshow server\*O command shows the RPC binding information, interface identifiers, and object UUIDs in a server entry. The entry name of the server entry is required. .P This operation shows all of the potential bindings for an interface. By default, this command displays bindings for the specified version of the interface and for upwardly compatible versions of the interface. The \*L-v\*O option controls which versions are targeted by this command. .SS "Privilege Required" ...\"show server You need read permission to the CDS object entry (the target server entry). .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .zA "defect,5537,R1.0.2, Correct entry name syntax" The following commands start the control program and show the server entry \*L/.:/LandS/anthro/Cal_host_2\*O in the local cell: .iS \*C$ \*Lrpccp \*Crpccp> \*Lshow server /.:/LandS/anthro/Cal_host_2\*O .iE The following command operates from the system prompt to display a specific object and interface from the server entry \*L/.:/LandS/anthro/Cal_host_2\*O in the local cell: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS \*C$ \*Lrpccp show server \\ \*C> \*L/.:/LandS/anthro/Cal_host_2 \\ \*C> \*L-o 16977538-e257-11c9-8dc0-08002b0f4528 \\ \*C> \*L-i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \*O .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .zZ "defect,5537,R1.0.2, Correct entry name syntax" .SH "RELATED INFORMATION" Commands: \*Lexport(1m)\*O, \*Limport(1m)\*O, \*Lunexport(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Lshow server\*O" .iX "-]" "binding information (RPC)" "viewing server entries" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Nov 8, 1991 Initial file submission to HP ...\" for final integration at IBM. ...\" ...\" ...\" ...\" " ~/rpc/RPCCP/rpccp_unexport_1m.rsml" ...\" HP/DIGITAL -- DCE RPC Version 1.0 , final draft ...\" ******************************************************************** ...\" * ...\" Copyright (c) 1991 Hewlett-Packard Co. and Digital Equipment Corp. ...\" All rights reserved. ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH "unexport"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lrpccp\*O commands" "\*Lunexport\*O" .iX "-[" "binding information (RPC)" "removing information" .SH NAME \*Lunexport\*O - Removes binding information, interface identifiers, and object UUIDs from a server entry .SH "SYNOPSIS" .zA "defect,8563,R1.0.3,-u option not valid for unexport" .zA "defect,7750,R1.0.3,add missing -u option to SYNOPSIS" .sS \*Lrpccp unexport\*O \*V entry-name\*O .nL {[\*L-i\*O \*Vif-id\*O [\*L-v\*O \*Vversions\*O]] \*V \*O | \*V \*O [\*L-o\*O \*Vobject-uuid\*O]} .nL [\*L-s\*O \*V syntax\*O] .sE .zZ "defect,7750,R1.0.3,add missing -u option to SYNOPSIS" .zZ "defect,8563,R1.0.3,-u option not valid for unexport" .SH "OPTIONS" .VL .LI "\*L-i\*O" Defines an interface identifier to be unexported (optional). Only one interface can be unexported in a single operation. If specified, binding information for this interface is removed from the entry. The \*L-i\*O option can be qualified by the \*L-v\*O option. The value has the following form: .sS \*Vinterface-uuid\*O\*L,\*O\*Vmajor-version\*O\*L.\*O\*Vminor-version\*O .sE The UUID is a hexadecimal string and the version numbers are decimal strings, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" Leading zeros in version numbers are ignored. .LI "\*L-v\*O" Indicates how a specified interface version is used (optional). If it is used without the \*L-i\*O option, the \*L-v\*O option is ignored. The possible combinations of versions for the \*L-v\*O option and their actions are described in the following table. .zA "defect,8152,R1.0.3,change upto description" .PP .ne 20 .TS center, box, tab(%); lB |lB lB |lw(3.5i). Versions%Action _ all%T{ The interface version is ignored. T} exact%T{ Both the major and minor versions must match the specified versions. T} compatible%T{ The major version must match the specified version, and the minor version must be greater than or equal to the specified version. T} major_only%T{ The major version must match the specified version; the minor version is ignored. T} upto%T{ The major version must be less than or equal to that specified. If the major versions are equal, the minor version must be less than or equal to that specified. T} _ .TE .zZ "defect,8152,R1.0.3,change upto description" .P If the \*L-v\*O option is absent, the command shows compatible version numbers. .LI "\*L-o\*O" Defines an object to be unexported (optional). Each \*Lunexport\*O command accepts up to 32 \*L-o\*O options. .P The UUID is a hexadecimal string, for example: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS -o 3c6b8f60-5945-11c9-a236-08002b102989 .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .LI "\*L-s\*O" Indicates the name syntax of the entry name (optional). The only value for this option is the \*Ldce\*O name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the \*L-s\*O option is unnecessary. .zA "defect,8563,R1.0.3,-u option not valid for unexport" .zA "defect,7561,R1.0.3,improve -u description" .zZ "defect,7561,R1.0.3,improve -u description" .zZ "defect,8563,R1.0.3,-u option not valid for unexport" .LE .SH "ARGUMENTS" .VL .LI "\*Ventry-name\*O" Indicates the name of the target name service entry. Usually, the target is a server entry. However, objects also can be exported (without an interface identifier or binding information) to a group or a profile. .P For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. .LE .SH "DESCRIPTION" The \*Lunexport\*O command removes binding information and an interface identifier, object UUIDs, or both from a server entry, or it removes object UUIDs from a group's entry. The command requires the entry name and either the interface identifier or one or more object UUIDs. .P By default, the \*Lunexport\*O operation removes \*Lcompatible\*O interface versions. .SS "Privilege Required" ...\"unexport You need both read permission and write permission to the CDS object entry (the target name service entry). .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .zA "defect,7519,R1.0.3, Change to sh/ksh example" .zA "defect,5989,R1.0.2, Correct entry name syntax" The initial shell commands set up an environment variable \*LCalendar_1_1\*O, which represents the interface identifier of an RPC interface. The control program commands start the control program and remove (unexport) the Calendar Version 1.1 interface from the server entry \*L/.:/LandS/anthro/Cal_host_2\*O in the local cell, as follows: .zA "defect,6742,R1.0.2,lowercase UUIDs" .iS \*C$ \*LCalendar_1_1=ec1eeb60-5943-11c9-a309-08002b102989,1.1 \*C$ \*Lexport Calendar_1_1 .sp \*C$ \*Lrpccp \*Crpccp> \*Lunexport \\ \*C> \*L-i Calendar_1_1 \\ \*C> \*L/.:/LandS/anthro/Cal_host_2\*O \*Crpccp>\*O .iE .zZ "defect,6742,R1.0.2,lowercase UUIDs" .zZ "defect,5989,R1.0.2, Correct entry name syntax" .zZ "defect,7519,R1.0.3, Change to sh/ksh example" .SH "RELATED INFORMATION" Commands: \*Lexport(1m)\*O, \*Limport(1m)\*O, \*Lshow server(1m)\*O .iX "-]" "\*Lrpccp\*O commands" "\*Lunexport\*O" .iX "-]" "binding information (RPC)" "removing information" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH dced "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "defect,9830,R1.1, New dced daemon" .iX "-[" "DCE Host daemon" "about" .SH NAME \*Ldced\*O - DCE Host daemon .SH "SYNOPSIS" .sS \*Ldced\*O [\*L-ifhr\*O] [\*L-w \*Vroute\*O] [\*L-b\*O|\*L-p\*O|\*L-s\*O] [\*L-e\*O|\*Vprot_seq...\*O] \*Lrpcd\*O [\*L-f\*O] [\*Vprot_seq...\*O] ...\" ...\"\*Ldced\*O [\*L-h\*O] [\*L-w\*O \*Vrouting\*O] ...\" ...\"\*Ldced\*O [\*L-i\*O] [\*L-w\*O \*Vrouting\*O] ...\" ...\"\*Ldced\*O [\*L-bcf\*O[\*L-p\*O|\*L-s\*O]] [\*Vprotseq\*O...] [-e] [\*L-w\*O \*Vrouting\*O] ...\" ...\" debug mode ...\"\*Ldced\*O [\*L-d\*O] ...\" .sE .SH "OPTIONS" .VL .LI \*L-h\*O Prints the \*Ldced\*O usage and exits. .LI \*L-i\*O Initializes the \*Ldced\*O databases and ACLs and exits. If the databases exist, this option displays an error. See the list of databases in the FILES section. .LI \*L-b\*O Starts \*Ldced\*O in bootstrap mode with the endpoint mapper service and ACLs. This mode means it may need to wait for other daemons such as \*Lsecd\*O and \*Lcdsd\*O before it can perform its own initialization. .LI \*L-c\*O Starts \*Ldced\*O so it does not require DCE privacy encryption for remote key table management. The default is to use DCE privacy encryption. DCE Privacy encryption is supported only by the Domestic (United States and Canada) versions of the DCE library and \*Ldced\*O. If the Export version of \*Ldced\*O is run without \*L-c\*O, then remote key table management is in effect disabled; if the Export \*Ldced\*O is run with \*L-c\*O, then remote key table management is enabled. However, running either version of \*Ldced\*O with \*L-c\*O is insecure and not recommended, because remote key table management without privacy encryption allows an eavesdropper to learn the long-term key of a service principal and thus to compromise the security of services running as that principal. .LI \*L-e\*O Starts \*Ldced\*O without the endpoint mapper service. No protocol sequences are valid for this option. .LI \*L-f\*O Starts the \*Ldced\*O or \*Lrpcd\*O process in the foreground. The default is to run in the background. .LI \*L-p\*O Purges the existing machine context and removes the bindings file before starting. .LI "\*L-r\*O" Starts \*Ldced\*O in remote-update mode. This mode allows DCE cell administration tasks to be performed by an administrator on a remote machine. By default, \*Ldced\*O prevents any remote administration to help prevent attacks by a malicious administrators. .LI \*L-s\*O Starts \*Ldced\*O without the security validation service. .LI \*L-w\*O Sets the routing for serviceability. ...\" debug mode ...\".LI \*L-d\*O ...\"Starts the DCE Host daemon in debug mode. ...\"In this mode, \*Ldced\*O runs as a forground process. .LE .SH "ARGUMENTS" .VL .LI \*Vroute\*O Establishes the serviceability routing for \*Ldced\*O's messages. .LI \*Vprot_seq\*O Specifies the RPC protocol sequences that \*Ldced\*O or \*Lrpcd\*O will use. Possible values include \*Lncadg_ip_udp\*O (for a datagram protocol) and \*Lncacn_ip_tcp\*O (for a connection-based protocol). A complete list of the protocol sequences recognized can be found in \*Ldce/ep.idl\*O. .LE .SH "DESCRIPTION" The DCE Host daemon is a process that provides services for the local host, and is also the server used by remote applications to access these host services. .PP The daemon can be invoked either as \*Ldced\*O or as \*Lrpcd\*O. When invoked as \*Ldced\*O, it provides by default all of the services described below, and it requires that the local host be configured into a DCE cell. When invoked as \*Lrpcd\*O, it provides only the Endpoint Mapper and Local Location Broker services that were provided by \*Lrpcd\*O in earlier versions of DCE; The \*Lrpcd\*O mode does not require that the host be configured into a DCE cell, so this is a simple alternative for hosts that run Networking Computing System (NCS) applications or DCE RPC-only applications. .PP The DCE Host daemon services include the following: .VL .LI "Endpoint Mapper" .nL The endpoint mapper service maintains a database called the \*Vlocal endpoint map\*O which allows DCE clients to find servers, individual services provided by servers, and objects managed by services on the host. The endpoint mapper service maps interfaces, object UUIDs, and protocol sequence registrations to server ports (endpoints). Servers register their bindings with the local endpoint mapper, and the endpoint mapper service on each host uses the local endpoint map to locate a compatible server for clients that do not already know the endpoint of a compatible server. .LI "Local Location Broker" .nL The local location broker service maintains a database called the LLB database, which allows NCS clients to find NCS servers on the host. This service was provided by \*Lrpcd\*O in earlier versions of DCE and by \*Lllbd\*O in NCS. .LI "Host Data Management" .nL The host data management service maintains local files of host data that include (among others) the \*Lhost_name, cell_name, cell_aliases,\*O and a \*Lpost_processors\*O file. The \*Lpost_processors\*O file contains program names matched with the other host data items (UUIDs). The \*Ldced\*O runs the program if the corresponding host data item is changed. There may also be host-specific data files. .LI "Server Management" .nL The server management service maintains data that describes the startup configuration (\*Lsrvrconf\*O) and execution state (\*Lsrvrexec\*O) for each server. It also has the functionality to start or stop particular servers, and enable or disable specific services of servers. .LI "Security Validation" .nL The security validation service acts as the client side of the security server by assuring applications that the DCE Security daemon (\*Lsecd\*O) that the host is using is legitimate. In addition, this service performs a DCE login for the local machine principal when \*Ldced\*O is invoked, and it automatically updates the local machine principal's keys. .LI "Key Table Management" .nL The key table management service allows for remote maintenance of server's key tables (\*Lkeytab\*O files). .LE .PP The DCE Host daemon must be running before any other DCE-based servers are started. Each DCE host must run only a single \*Ldced\*O, and it must run with root privileges since it typically listens on privileged or reserved network ports. Typically, \*Ldced\*O starts each time a host boots. (A file called \*L/etc/rc.dce\*O is responsible for configuration issues such as deleting the endpoint map database and starting \*Ldced\*O.) .PP By default, the DCE Host daemon listens on one well-known port for each RPC protocol sequence (that is, each combination of an RPC protocol and a transport protocol) supported by the host on which it is running. A \*Vprot_seq\*O argument lets you limit the protocol sequences on which \*Ldced\*O listens. .PP .SH "FILES" .PP .TS tab(@); lB lB. \*Vdcelocal\*L/var/dced/Ep.db @\*Vdcelocal\*L/dce_cf.db \*Vdcelocal\*L/var/dced/Llb.db @\*Vdcelocal\*L/var/dced/cell_aliases \*Vdcelocal\*L/var/dced/Hostdata.db@\*Vdcelocal\*L/var/dced/cell_name \*Vdcelocal\*L/var/dced/Srvrconf.db@\*Vdcelocal\*L/var/dced/host_name \*Vdcelocal\*L/var/dced/Srvrexec.db@\*Vdcelocal\*L/var/dced/post_processes \*Vdcelocal\*L/var/dced/Keytab.db @\*Vdcelocal\*L/bin/dcecf_postproc \*Vdcelocal\*L/var/dced/Acl.db @/krb5/v5srvtab \*Vdcelocal\*L/var/dced/Xattrschema.db@ .TE .SH "RELATED INFORMATION" Commands: \*Lhostdata(1m), endpoint(1m), server(1m), secval(1m), keytab(1m), attribute(1m)\*O .PP Library calls: \*Ldce_server*(3), dced_*(3), rpc_mgmt_ep*(3)\*O .PP Books: ...\"App. Dev. Guide \*(Dg. .iX "-]" "DCE Host daemon" "about" .zZ "defect,9830,R1.1, New dced daemon"  .\" $Header: rpcinfo.1m,v 72.5 94/10/31 13:43:38 ssa Exp $ .TA r .TH rpcinfo 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rpcinfo \- report RPC information .SH SYNOPSIS .C "/usr/sbin/rpcinfo -p" .RI [ \|host\| ] .br .C /usr/sbin/rpcinfo .RC [ -n .IR portnum\| ] .CI -u \0host\0program .RI [ \|version\| ] .br .C /usr/sbin/rpcinfo .RC [ -n .IR portnum\| ] .CI -t \0host\0program .RI [ \|version\| ] .br .CI "/usr/sbin/rpcinfo -b" \0program\0version .br .CI "/usr/sbin/rpcinfo -d" \0program\0version .SH DESCRIPTION .CR rpcinfo makes an RPC call to an RPC server and reports what it finds. .SS Options .CR rpcinfo recognizes the following command-line options and arguments: .RS .TP 15 .CI -p \0host Probe the portmapper on .I host and print a list of all registered RPC programs. If .I host is not specified, it defaults to the value returned by .CR hostname (see .IR hostname (1)). .TP .CI -n \0portnum Use .I portnum as the port number for the .CR -t and .CR -u options instead of the port number given by the portmapper. .TP .C -u Make an RPC call to procedure 0 of .I program on the specified .I host using UDP and report whether a response was received. .TP .C -t Make an RPC call to procedure 0 of .I program on the specified .I host using TCP and report whether a response was received. .TP .C -b Make an RPC broadcast to procedure 0 of the specified .I program and .I version using UDP and report all hosts that respond. .TP .C -d Delete registration for the RPC service of the specified .I program and .IR version . Only users with appropriate privileges can use this option. .TP .I program Can be either a name or a number. .TP .I version If specified, .CR rpcinfo attempts to call that version of the specified .IR program . Otherwise, .CR rpcinfo attempts to find all the registered version numbers for the specified program by calling version 0, then attempts to call each registered version. (Version 0 is presumed to not exist, but if version 0 does exist, .CR rpcinfo attempts to obtain the version number information by calling an extremely high version number instead.) Note that .I version must be specified when the .CR -b and .CR -d options are used. .RE .SH EXAMPLES Show all of the RPC services registered on the local machine: .IP .C "rpcinfo -p" .PP Show all of the RPC services registered on the machine named .CR klaxon : .IP .C "rpcinfo -p klaxon" .PP Show all machines on the local net that are running the Network Information Service (\c NIS\c ): .IP .C "rpcinfo -b ypserv 1 | sort | uniq" .PP where .CR 1 is the current NIS .I version obtained from the results of the .CR -p option in the previous example. .PP Delete the registration for version 1 of the .CR walld service: .IP .C "rpcinfo -d walld 1" .PP [Note that .CR walld is the RPC program name for .CR rwalld (see .IR rwalld (1m))]. .SH WARNINGS In releases prior to Sun UNIX 3.0, the Network File System (NFS) did not register itself with the portmapper; .I rpcinfo cannot be used to make RPC calls to the NFS server on hosts running such releases. Note that this does not apply to any HP releases of NFS. .SH AUTHOR .CR rpcinfo was developed by Sun Microsystems, Inc. .SH FILES .TP 22 .CR /etc/rpc names for RPC program numbers .SH SEE ALSO .PP rpc(4), portmap(1M), .br .I Programming and Protocols for NFS .IR Services . .\" index@\f4rpcinfo\f1 \- report RPC information@@@\f3rpcinfo(1M)\f1 .\" index@\f1report RPC information@@@\f3rpcinfo(1M)\f1 .\" toc@\f3rpcinfo(1M)\f1:\0\0\f4rpcinfo\f1@@@report RPC information .\" .\" fileset_database@rpcinfo.1m SYS-ADMIN-MAN .\"========================================================= .\" (c) 1992,1993 Hewlett-Packard Company. All Rights Reserved. .\" Author: Hewlett-Packard DMD .\"========================================================= .\" .\"@(#) $Header: rpr.1m,v 1.2 95/12/15 11:35:50 hmgr Exp $ .TA r .TH rpr 1M .SH NAME rpr \- repair parity information in an .SM HP SCSI disk array .SM LUN .SH SYNOPSIS .HP .C rpr -b .I block device_file .SH DESCRIPTION .C rpr repairs the data parity information on a .SM LUN in an .SM HP SCSI disk array when the .SM LUN is configured in a data redundant .SM RAID\c -level (\c .SM RAID\c _1, .SM RAID\c _3, or .SM RAID\c _5). .I block is the logical address of the data block corresponding to the parity block needing repair. .I block is specified using the .C -b parameter. .I device_file is the name of the device file for the .SM LUN. .PP Use .C scn (see .CR scn (1M)) to identify data blocks that do not have correct parity blocks. .SH RETURN VALUE .PP .C rpr returns the following values: .RS 5 .TP .B " 0" Successful completion. .PD 0 .TP .B -1 Command failed (an error occurred). .PD .PP .RE .SH DIAGNOSTICS AND ERRORS Errors can originate from problems with: .RS .TP 3 \(bu .C rpr .TP \(bu .SM SCSI (device level) communications .TP \(bu system calls .RE .PP .SS Error messages generated by rpr: .TP .C "usage: rpr -b block> " .C rpr encountered an error in command syntax. Re-enter the command with all required arguments, in the order shown. .TP .C "rpr: LUN does not exist" The addressed LUN is not configured, and is not known to the array controller. .TP .C "rpr: LUN # too big" The LUN number, derived from the device file name, is out of range. .TP .C "rpr: Not a raw file" .C rpr must be able to open the device file for raw access. .TP .C "rpr: Transfer length error" The amount of data actually sent to or received from the device was not the expected amount. .TP .C "rpr: Not an HP SCSI disk array" The device being addressed is not an HP SCSI disk array. .PP .SS SCSI (device level) communication errors: Sense data associated with the failed operation is printed. .PP .SS Error messages generated by system calls: .C rpr uses the following system calls: .IP .CR malloc() , .CR free() , .CR stat() , .CR open() , .CR close() , .CR fopen() , .CR fclose() , .CR read() , .CR write() , .CR unlink() , and .CR ioctl() . .PP Documentation for these .SM HP-UX system calls contains information about the specific error conditions associated with each call. .C rpr does not alter the value of .CR errno . The interpretation of .C errno for printing purposes is performed by the system utility .CR strerror() . .SH EXAMPLES .PP To repair block 12345 of the .SM LUN .C /dev/rdsk/c2t6d0 on a series 800: .IP .C "rpr -b 12345 /dev/rdsk/c2t6d0" .SH DEPENDENCIES The HP C2425 and HP C2427 disk arrays are only supported on Series 700 systems running HP-UX version 9.0X. .PP The HP C2430 disk array is supported on Series 700 and 800 systems running HP-UX versions 9.0X and 10.0X. .SH AUTHOR .PP .C rpr was developed by HP. .SH SEE ALSO scn(1m) .\" .\" index@\f4rpr\f1 \- repair parity information on an \s-1HP SCSI\s+1 disk array \s-1LUN\s+1@@@\f3rpr(1M)\f1 .\" index@disk array, repair \s-1LUN\s+1 parity information@@@\f3rpr(1M)\f1 .\" index@parity information, repair disk array \s-1LUN\s+1@@@\f3rpr(1M)\f1 .\" .\" toc@\f3rpr(1M)\f1:\0\0\f4rpr\f1@@@repair parity information on an \s-1HP SCSI\s+1 disk array \s-1LUN\s+1 .\" .\" fileset_database@rpr.1m SYS-ADMIN-MAN .\" $Header: rquotad.1m,v 72.5 94/11/29 05:58:32 ssa Exp $ .TA r .TH rquotad 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rquotad \- remote quota server .SH SYNOPSIS .C /usr/sbin/rpc.rquotad .SH DESCRIPTION .C rquotad is an .SM RPC server that returns quotas for a user of a local file system currently mounted by a remote machine by means of .SM NFS (see .IR rpc (3C)). The results are used by .C quota to display user quotas for remote file systems (see .IR quota (1)). .C rquotad is normally invoked by .C inetd (see .IR inetd (1M)). .SH AUTHOR Disk Quotas were developed by the University of California, Berkeley, Sun Microsystems, Inc., and HP. .SH FILES .TP 25 .IC directory /quotas Quota statistics static storage for a file system, where .I directory is the root of the file system. .SH SEE ALSO inetd(1M), rpc(3C), services(4), quota(5), nfs(7). .\" .\" index@\f4rquotad\f1 \- remote quota server@@@\f3rquotad(1M)\f1 .\" index@remote quota server@@@\f3rquotad(1M)\f1 .\" index@quota server, remote@@@\f3rquotad(1M)\f1 .\" index@server, remote quota@@@\f3rquotad(1M)\f1 .\" .\" toc@\f3rquotad(1M)\f1:\0\0\f4rquotad\f1@@@remote quota server .\" .\" fileset_database@rquotad.1m SYS-ADMIN-MAN .\" $Header: restore.1m,v 72.4 94/08/12 11:18:53 ssa Exp $ .TA r .TH restore 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME restore, rrestore \- restore file system incrementally, local or across network .SH SYNOPSIS .C /usr/sbin/restore .I key .RI [ \|name \0...\|] .PP .C /usr/sbin/rrestore .I key .RI [ \|name \0...\|] .SH DESCRIPTION The .CR restore and .CR rrestore commands read tapes previously dumped by the .CR dump or .CR rdump command (see .IR dump (1M) and .IR rdump (1M)). Actions taken are controlled by the .I key argument where .I key is a string of characters containing not more than one function letter and possibly one or more function modifiers. One or more .I name arguments, if present, are file or directory names specifying the files that are to be restored. Unless the .CR h modifier is specified (see below), the appearance of a directory name refers to the files and (recursively) subdirectories of that directory. .SS Function Portion of \f2key\fP The function portion of the key is specified by one of the following letters: .RS .TP 6 .C r Read the tape and load into the current directory. .CR r should be used only after careful consideration, and only to restore a complete dump tape onto a clear file system, or to restore an incremental dump tape after a full level zero restore. Thus, .RS .IP .nf .C /usr/sbin/newfs -F hfs /dev/rdsk/c0t0d0 .C /usr/sbin/mount /dev/dsk/c0t0d0 /mnt .C cd /mnt .C restore r .fi .RE .IP is a typical sequence to restore a complete dump. Another .CR restore or .CR rrestore can then be performed to restore an incremental dump on top of this. Note that .CR restore and .CR rrestore leave a file .CR restoresymtab in the root directory of the file system to pass information between incremental restore passes. This file should be removed when the last incremental tape has been restored. A .CR dump or .CR rdump followed by a .CR newfs and a .CR restore or .CR rrestore is used to change the size of a file system (see .IR newfs (1M)). .TP .C R .CR restore and .CR rrestore request a particular tape of a multivolume set on which to restart a full restore (see .CR r above). This provides a means for interrupting and restarting .CR restore and .CR rrestore . .TP .C x Extract the named files from the tape. If the named file matches a directory whose contents had been written onto the tape, and the .CR h modifier is not specified, the directory is recursively extracted. The owner, modification time, and mode are restored (if possible). If no file argument is given, the root directory is extracted, which results in the entire contents of the tape being extracted, unless .CR h has been specified. .TP .C t Names of the specified files are listed if they occur on the tape. If no file argument is given, the root directory is listed, which results in the entire content of the tape being listed, unless .CR h has been specified. .TP .C s The next argument to .CR restore is used as the dump file number to recover. This is useful if there is more than one dump file on a tape. .TP .C i This mode allows interactive restoration of files from a dump tape. After reading in the directory information from the tape, .CR restore and .CR rrestore provide a shell-like interface that allows the user to move around the directory tree selecting files to be extracted. The available commands are given below; for those commands that require an argument, the default is the current directory. .RS .RS .TP 15 .CR add \0[\f2arg\fP] The current directory or specified argument is added to the list of files to be extracted. If a directory is specified, it and all its descendents are added to the extraction list (unless the .CR h key is specified on the command line). File names on the extraction list are displayed with a leading .CR * when listed by .CR ls . .TP .CR cd \0[\f2arg\fP] Change the current working directory to the specified argument. .TP .CR delete \0[\f2arg\fP] The current directory or specified argument is deleted from the list of files to be extracted. If a directory is specified, it and all its descendents are deleted from the extraction list (unless .CR h is specified on the command line). The most expedient way to extract files from a directory is to add the directory to the extraction list, then delete unnecessary files. .TP .C extract All files named on the extraction list are extracted from the dump tape. .CR restore and .CR rrestore ask which volume the user wants to mount. The fastest way to extract a few files is to start with the last volume, then work toward the first volume. .TP .C help List a summary of the available commands. .TP .CR ls \0[\f2arg\fP] List the current or specified directory. Entries that are directories are displayed with a trailing .CR / . Entries marked for extraction are displayed with a leading .CR * . If the verbose key is set, the inode number of each entry is also listed. .TP .C pwd Print the full path name of the current working directory. .TP .C quit .CR restore and .CR rrestore immediately exit, even if the extraction list is not empty. .TP .C set-modes Set the owner, modes, and times of all directories that are added to the extraction list. Nothing is extracted from the tape. This setting is useful for cleaning up after a restore aborts prematurely. .TP .C verbose The sense of the .CR v modifier is toggled. When set, the verbose key causes the .C ls command to list the inode numbers of all entries. It also causes .CR restore and .CR rrestore to print out information about each file as it is extracted. .RE .RE .RE .SS Function Modifiers The following function modifier characters can be used in addition to the letter that selects the function desired: .RS .TP 6 .C b Specify the block size of the tape in kilobytes. If the .CR -b option is not specified, .CR restore and .CR rrestore try to determine the tape block size dynamically. .TP .C f Specify the name of the archive instead of .CR /dev/rmt/0m . If the name of the file is .CR - , .CR restore reads from standard input. Thus, .CR dump and .CR restore can be used in a pipeline to dump and restore a file system with the command .RS .IP .C "dump 0f - /usr | (cd /mnt; restore xf -) .RE .IP When using .CR rrestore , this key should be specified, and the next argument supplied should be of the form .IC machine : device\f1. .TP .C h Extract the actual directory, rather than the files to which it refers. This prevents hierarchical restoration of complete subtrees from the tape, rather than the files to which it refers. .TP .C m Extract by inode numbers rather than by file name. This is useful if only a few files are being extracted and one wants to avoid regenerating the complete path name to the file. .TP .C v Type the name of each file .CR restore and .CR rrestore treat, preceded by its file type. Normally .CR restore and .CR rrestore do their work silently; the .CR v modifier specifies verbose output. .TP .C y Do not ask whether to abort the operation if .CR restore and .CR rrestore encounters a tape error. .CR restore and .CR rrestore attempt to skip over the bad tape block(s) and continue. .PP .CR rrestore creates a server, either .CR /usr/sbin/rmt or .CR /etc/rmt, on the remote machine to access the tape device. .RE .SH DIAGNOSTICS .CR restore and .CR rrestore complain about bad key characters. .PP .CR restore and .CR rrestore complain if a read error is encountered. If the .CR y modifier has been specified, or the user responds .CR y , .CR restore and .CR rrestore attempt to continue the restore. .PP If the dump extends over more than one tape, .CR restore and .CR rrestore ask the user to change tapes. If the .CR x or .CR i function has been specified, .CR restore and .CR rrestore also ask which volume the user wants to mount. The fastest way to extract a few files is to start with the last volume and work towards the first volume. .PP There are numerous consistency checks that can be listed by .CR restore and .CR rrestore . Most checks are self-explanatory or can ``never happen''. Here are some common errors: .RS .TP .IC filename ": not found on tape" The specified file name was listed in the tape directory but not found on the tape. This is caused by tape read errors while looking for the file, and from using a dump tape created on an active file system. .TP .CI "expected next file " inumber ", got " inumber A file not listed in the directory showed up. This can occur when using a dump tape created on an active file system. .TP .C "Incremental tape too low" When doing an incremental restore, a tape that was written before the previous incremental tape, or that has too low an incremental level has been loaded. .TP .C "Incremental tape too high" When doing an incremental restore, a tape that does not begin its coverage where the previous incremental tape left off, or that has too high an incremental level has been loaded. .TP .CI "Tape read error while restoring " filename" .PD 0 .TP .CI "Tape read error while skipping over inode " inumber" .TP .C "Tape read error while trying to resynchronize" A tape read error has occurred. If a file name is specified, the contents of the restored files are probably partially wrong. If restore is skipping an inode or is trying to resynchronize the tape, no extracted files are corrupted, although files may not be found on the tape. .PD .TP .CI "Resync restore, skipped " num" blocks" After a tape read error, .CR restore and .CR rrestore may have to resynchronize themselves. This message indicates the number of blocks skipped over. .SH WARNINGS .CR restore and .CR rrestore can get confused when doing incremental restores from dump tapes that were made on active file systems. .PP A level zero dump (see .IR dump (1M)) must be done after a full restore. Since restore runs in user code, it has no control over inode allocation; thus a full dump must be done to get a new set of directories reflecting the new inode numbering, even though the contents of the files are unchanged. .SH AUTHOR .CR restore and .CR rrestore were developed by the University of California, Berkeley. .SH FILES .TP 25 .C /dev/rmt/0m Default tape drive. .TP .C /tmp/rstdr* File containing directories on the tape. .TP .C /tmp/rstmd* Owner, mode, and time stamps for directories. .TP .C ./restoresymtab Information passed between incremental restores. .SH SEE ALSO dump(1M), mkfs(1M), mount(1M), newfs(1M), rmt(1M). .\" .\" index@\f4restore\f1 \- incrementally restore file system@@@\f3restore(1M)\f1 .\" index@\f4rrestore\f1 \- incrementally restore file system across network@@@\f3restore(1M)\f1 .\" index@\f1incrementally restore file system@@@\f3restore(1M)\f1 .\" index@\f1restore file system incrementally@@@\f3restore(1M)\f1 .\" index@\f1remote incremental file system restore@@@\f3restore(1M)\f1 .\" index@\f1network, restore file system incrementally across@@@\f3restore(1M)\f1 .\" index@\f1file system, restore incrementally, local or across network@@@\f3restore(1M)\f1 .\" .\" toc@\f3restore(1M)\f1:\0\0\f4restore\f1, \f4rrestore\f1@@@restore file system incrementally, local or over a network\f1 .\" toc@\f4rrestore\f1: restore file system incrementally over a network@@@see \f3restore(1M)\f1 .\" .\" links@restore.1m rrestore.1m .\" $Header: rstatd.1m,v 72.4 94/06/30 15:44:53 ssa Exp $ .TA r .TH rstatd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rstatd \- kernel statistics server .SH SYNOPSIS .C /usr/lib/netsvc/rstat/rpc.rstatd .RC [ -l .IR log_file ] .RC [ -e \(or -n ] .SH DESCRIPTION .C rstatd is an RPC server that returns performance statistics obtained from the kernel. The .C rup utility prints this information (see .IR rup (1)). .PP .C inetd invokes .C rstatd through .C /etc/inetd.conf (see .IR inetd (1M)). .SS Options .C rstatd recognizes the following options and command-line arguments: .RS .TP 15 .CI -l \0log_file Log any errors to the named log file, .IR log_file . Errors are not logged if the .C -l option is not specified. .IP Information logged to the file includes date and time of the error, the host name, process ID and name of the function generating the error, and the error message. Note that different services can share a single log file because enough information is included to uniquely identify each error. .TP .C -e Exit after serving each RPC request. Using the .C -e option, the .C inetd security file .C /var/adm/inetd.sec can control access to RPC services. .TP .C -n Exit only if .RS .RS .TP 3 \(bu .C portmap dies (see .IR portmap (1M)), .TP \(bu another .C rpc.rstatd registers with .CR portmap , or .TP \(bu .C rpc.rstatd becomes unregistered with .IR portmap . .RE .RE .IP The .C -n option is more efficient since a new process is not launched for each RPC request. Note, this option is the default. .RE .SH AUTHOR .C rstatd was developed by Sun Microsystems, Inc. .SH SEE ALSO rup(1), inetd(1M), portmap(1M), inetd.conf(4), inetd.sec(4), services(4). .\" .\" index@\f4rstatd\f1: kernel statistics server@@@\f3rstatd(1M)\f1 .\" index@kernel statistics server@@@\f3rstatd(1M)\f1 .\" index@statistics server, kernel@@@\f3rstatd(1M)\f1 .\" index@server, kernel statistics@@@\f3rstatd(1M)\f1 .\" .\" toc@\f3rstatd(1M)\f1: \f4rstatd\f1@@@kernel statistics server .\" $Header: runacct.1m,v 72.3 94/11/14 15:23:28 ssa Exp $ .TA r .TH runacct 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME runacct \- run daily accounting .SH SYNOPSIS .B /usr/sbin/acct/runacct .RI [ \|mmdd\| [ \|state\| ]\|] .SH DESCRIPTION .I runacct is the main daily accounting shell procedure. It is normally initiated via .IR cron (1M). .I runacct processes connect, fee, disk, and process accounting files. It also prepares summary files for .I prdaily or billing purposes. .PP .I runacct takes care not to damage active accounting files or summary files in the event of errors. It records its progress by writing descriptive diagnostic messages into .BR active . When an error is detected, a message is written to .BR /dev/console , mail (see .IR mail (1), .IR mailx (1), or .IR elm (1)) is sent to .B root and .BR adm , and .I runacct terminates. .I runacct uses a series of lock files to protect against re-invocation. The files .B lock and .B lock1 are used to prevent simultaneous invocation, and .B lastdate is used to prevent more than one invocation per day. .PP .I runacct breaks its processing into separate, restartable .I states using .B statefile to remember the last .I state completed. It accomplishes this by writing the .I state name into .BR statefile . .I runacct then looks in .B statefile to see what it has done and to determine what to process next. .I states are executed in the following order: .RS .TP 15 .SM .B SETUP Move active accounting files into working files. .TP .SM .B WTMPFIX Verify integrity of .B wtmp file, correcting date changes if necessary. .TP .SM .B CONNECT Produce connect session records in .B tacct.h format. .TP .SM .B PROCESS Convert process accounting records into .B tacct.h format. .TP .SM .B MERGE Merge the connect and process accounting records. .TP .SM .B FEES Convert output of .I chargefee into .B tacct.h format and merge with connect and process accounting records. .TP .SM .B DISK Merge disk accounting records with connect, process, and fee accounting records. .TP .SM .B MERGETACCT Merge the daily total accounting records in .B daytacct with the summary total accounting records in .BR /var/adm/acct/sum/tacct . .TP .SM .B CMS Produce command summaries. .TP .SM .B USEREXIT Any installation-dependent accounting programs can be included here. .TP .SM .B CLEANUP Cleanup temporary files and exit. .RE .PP To restart .I runacct after a failure, first check the .B active file for diagnostics, then fix up any corrupted data files such as .B pacct or .BR wtmp . The .B lock files and .B lastdate file must be removed before .I runacct can be restarted. The argument .I mmdd is necessary if .I runacct is being restarted, and specifies the month and day for which .I runacct will rerun the accounting. Entry point for processing is based on the contents of .BR statefile ; to override this, include the desired .I state on the command line to designate where processing should begin. .SH EXAMPLES To start .IR runacct . .IP .B "nohup runacct 2> /var/adm/acct/nite/fd2log &" .PP To restart .IR runacct . .IP .B "nohup runacct 0601 2>> /var/adm/acct/nite/fd2log &" .PP To restart .I runacct at a specific .IR state . .IP .B "nohup runacct 0601 \s-1MERGE\s0 2>> /var/adm/acct/nite/fd2log &" .SH WARNINGS Normally it is not a good idea to restart .I runacct in its .SM .B SETUP .IR state . Run .SM .B SETUP manually, then restart via: .IP .B runacct .I mmdd .SM .B WTMPFIX .PP If .I runacct failed in its .SM .B PROCESS .IR state , remove the last .B ptacct file because it will not be complete. .SH FILES .nf /var/adm/acct/nite/active /var/adm/acct/nite/daytacct /var/adm/acct/nite/lastdate /var/adm/acct/nite/lock /var/adm/acct/nite/lock1 /var/adm/pacct\f2\(**\fP /var/adm/acct/nite/ptacct\(**.\f2mmdd\fP /var/adm/acct/nite/statefile /var/adm/wtmp .fi .SH SEE ALSO mail(1), acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), acctsh(1M), cron(1M), fwtmp(1M), acct(2), acct(4), utmp(4) .PP .SH STANDARDS CONFORMANCE .CR runacct ": SVID2, SVID3" .\" .\" index@\f4runacct\f1 \- run daily accounting@@@\f3runacct(1M)\f1 .\" .\" index@\f1run daily accounting@@@\f3runacct(1M)\f1 .\" index@\f1daily accounting shell procedure@@@\f3runacct(1M)\f1 .\" index@\f1accounting: daily accounting shell procedure@@@\f3runacct(1M)\f1 .\" index@\f1process accounting, daily accounting shell procedure@@@\f3runacct(1M)\f1 .\" index@\f1user accounting, daily accounting shell procedure@@@\f3runacct(1M)\f1 .\" .\" toc@\f3runacct(1M)\f1:\0\0\f4runacct\f1@@@run daily accounting .\" .\" fileset_database@runacct.1m SYS-ADMIN-MAN .\" $Header: rusersd.1m,v 72.4 94/06/30 15:50:09 ssa Exp $ .TA r .TH rusersd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rusersd \- network username server .SH SYNOPSIS .C /usr/lib/netsvc/rusers/rpc.rusersd .RC [ -l .IR log_file ] .RC [ -e \(or -n ] .SH DESCRIPTION .CR rusersd is an RPC server that returns a list of users on the network. The .CR rusers command prints this information (see .IR rusers (1)). .PP .CR inetd invokes .CR rusersd through .CR /etc/inetd.conf (see .IR inetd (1M)). .SS Options .CR rusersd recognizes the following options and command-line arguments: .RS .TP 15 .CI -l \0log_file Log any errors to the named log file, .IR log_file . Errors are not logged if the .CR -l option is not specified. .IP Information logged to the file includes date and time of the error, the host name, process ID and name of the function generating the error, and the error message. Note that different services can share a single log file since enough information is included to uniquely identify each error. .TP .CR -e Exit after serving each RPC request. Using the .CR -e option, the .CR inetd security file .CR /var/adm/inetd.sec can control access to RPC services. .TP .CR -n Exit only if .RS .RS .TP 3 \(bu .CR portmap dies (see .IR portmap (1M)), .TP \(bu another .CR rpc.rusersd registers with .CR portmap , or .TP \(bu .CR rpc.rusersd becomes unregistered with .CR portmap . .RE .RE .IP The .CR -n option is more efficient because a new process is not launched for each RPC request. This option is the default. .RE .SH AUTHOR .CR rusersd was developed by Sun Microsystems, Inc. .SH SEE ALSO rusers(1), inetd(1M), portmap(1M), inetd.conf(4), inetd.sec(4), services(4). .\" .\" index@\f4rusersd\f1: network username server@@@\f3rusersd(1M)\f1 .\" index@network username server@@@\f3rusersd(1M)\f1 .\" index@username server, network@@@\f3rusersd(1M)\f1 .\" index@server, network username@@@\f3rusersd(1M)\f1 .\" .\" toc@\f3rusersd(1M)\f1: \f4rusersd\f1@@@network username server .\" $Header: vxdump.1m,v 78.1 96/02/13 14:07:01 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1996 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .\" Copyright (c) 1980, 1991, 1993 .\" Regents of the University of California. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .so /usr/share/lib/macros/vxfs.an .TA v .TH vxdump 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vxdump, rvxdump (vxfs) \- incremental file system dump, local or across network .SH SYNOPSIS .CR /usr/sbin/vxdump .RC [ \-nuwW ] .RC [ \-0123456789 ] .RC [ \-f .IR file_name ] .RS .RC [ \-d .IR density ] .RC [ \-s .IR size ] .RC [ \-T .IR time ] .RC [ \-b .IR block_size ] .RE .RS .RC [ \-B .IR records ] .I filesystem .RE .PP .C /usr/sbin/rvxdump .RC [ \-nuwW ] .RC [ \-0123456789 ] .RC [ \-f .IR file_name ] .RS .RC [ \-d .IR density ] .RC [ \-s .IR size ] .RC [ \-T .IR time ] .RC [ \-b .IR block_size ] .RE .RS .RC [ \-B .IR records ] .I filesystem .RE .PP .C /usr/sbin/vxdump .RI [ option .RI [ argument " ...]" .IR filesystem ] .PP .C /usr/sbin/rvxdump .RI [ option .RI [ argument " ...]" .IR filesystem ] .SH DESCRIPTION .CR vxdump and .CR rvxdump copy to magnetic tape all files in the .CR vxfs .I filesystem that have been changed after a certain date. This information is derived from the files .CR /var/adm/dumpdates and .CR /etc/fstab . .PP .CR vxdump and .CR rvxdump support both .IR getopt (3C) and traditional .CR dump command line invocations as shown above. The original .CR dump command line style is supported for compatibility with previous versions of .CR vxdump and for synonymy with the existing .CR dump program used for hfs file systems. For the traditional command line style, .I option consists of characters from the set .CR 0123456789bBdfnsTuWw without any intervening white space. .PP On most devices .C vxdump can detect end-of-media and prompt for the media to be changed, so it is not necessary to specify the size of the device. However, if the dump will require multiple tapes and the tapes are to be read using an older version of .CR vxrestore , or if the tape device handles end-of-media in a way that .C vxdump doesn't understand, then the size of the device must be specified using either the .CR \-B option or a combination of the .CR \-d " and " \-s options. .SS Options .RS .TP 10 .CI \- number Where .I number is in the range [0\-9]. This number is the dump level. All files modified since the last date stored in the file .CR /var/adm/dumpdates for the same file system at a lesser dump level will be dumped. Thus, the option .CR \-0 causes the entire file system to be dumped. If no date is determined by the level, the beginning of time is assumed. .TP .CI \-B " records" The number of logical records per volume. The .CR vxdump logical record size is 1024 bytes. .I records can also be specified with a suffix to indicate a unit of measure other than 1024 bytes. A .CR k , .CR m , or .CR g can be appended to the number to indicate that the value is in kilobytes, megabytes, or gigabytes, respectively. This option overrides the calculation of tape size based on length and density. .TP .CI \-b " block_size" The blocking factor is taken from the .I block_size option argument. (default is 63 if .C \-b is not specified). Block size is defined as the logical record size times the blocking factor. .CR vxdump writes logical records of 1024 bytes. Older versions of .C vxdump used a blocking factor of 10 for tapes with densities less than 6250 BPI, and 32 for tapes with densities of 6250 BPI or greater. .CR vxrestore will dynamically determine the blocking factor. .TP .CI \-d " density" The density of the tape (expressed in BPI). This is used in calculating the amount of tape used per tape reel. If the .C \-s option is specified, a default density value of 1600 is assumed a for a reel tape. .TP .CI \-f " file_name" Place the dump on the file .I file_name instead of the tape. If the name of the file is .CR \- , .CR vxdump writes to the standard output. This option can be of the form .IC machine : device to specify a tape device on a remote machine. .TP .C \-n Whenever .CR vxdump requires operator attention, notify all users in group .CR operator by means similar to that described by .IR wall (1). .TP .CI \-s " size" .I size is the size of the dump tape, specified in feet. When the specified size is reached, .CR vxdump waits for reels to be changed. If the .C \-d option is specified, a default size value of 2300 is assumed a for a reel tape. .TP .C \-u If the dump completes successfully, write on file .CR /var/adm/dumpdates the date when the dump started. This file records a separate date for each file system and each dump level. The format of .CR /var/adm/dumpdates is user-readable and consists of one free-format record per line: file system name, increment level and dump date in .IR ctime (3C) format. The file .CR /var/adm/dumpdates can be edited to change any of the fields if necessary. .TP .CI \-T " date" Use the specified date as the starting time for the dump instead of the time determined from looking in .CR /var/adm/dumpdates . The format of .I date is the same as that of .IR ctime (3C) This option is useful for automated dump scripts that wish to dump over a specific period of time. The .C \-T option is mutually exclusive with the .C \-u option. .TP .C \-W For each file system in .CR /var/adm/dumpdates , print the most recent dump date and level, indicating which file systems should be dumped. If the .CR \-W option is set, all other options are ignored and .CR vxdump exits immediately. .TP .C \-w Operates like .CR W , but prints only file systems that need to be dumped. .RE .PP If no arguments are given, the options are assumed to be .CR \-9u and a default file system is dumped to the default tape. .SS Operator Interaction .PP .CR vxdump requires operator intervention for any of the following conditions: .RS .TP 3 \(bu end of tape, .PD 0 .TP \(bu end of dump, .TP \(bu tape-write error, .TP \(bu tape-open error, or .TP \(bu disk-read error (if errors exceed threshold of 32). .RE .PD .PP In addition to alerting all operators implied by the .C \-n option, .CR vxdump interacts with the control terminal operator by posing questions requiring .CR yes or .CR no answers when it can no longer proceed or if something is grossly wrong. .PP Since making a full dump involves considerable time and effort, .CR vxdump establishes a checkpoint at the start of each tape volume. If, for any reason, writing that volume fails, .CR vxdump will, with operator permission, restart from the checkpoint after the old tape has been rewound and removed and a new tape has been mounted. .PP .CR vxdump periodically reports information to the operator, including estimates (typically low) of the number of blocks to write, the number of tapes it will require, time needed for completion, and the time remaining until tape change. The output is verbose to inform other users that the terminal controlling .CR vxdump is busy and will be for some time. .SS Compatibility The dump tape format is independent of the VxFS disk layout. A dump of a file system with the Version 3 disk layout can be restored on a file system using the Version 2 disk layout or even a file system of another file system type, with the following exceptions: .TP 3 \(bu Files larger than 2 Gbyte cannot be restored by earlier versions of .CR vxrestore . If a file larger than 2 Gbyte is encountered, .C vxrestore will skip the file and produce the diagnostic: .RS 1i .CI "Resync restore, skipped " num " blocks" .RE .TP \(bu Files larger than 2 Gbyte cannot be restored on a file system that does not support large files (see .CR mount_vxfs(1m) ). .TP \(bu A file with a large .I uid (user ID of the file owner) or large .I gid (group ID of the file owner) cannot be restored correctly on a file system that does not support large IDs. Instead, the owner and/or group of the file will be that of the user invoking .CR vxrestore . (A large ID is a value grater than 65535. The VxFS Version 2 disk layout does not support lage IDs). .TP \(bu Files with VxFS extent attributes (see setext(1m)) cannot be restored on a file system of a type that does not support extent attributes. .PP If you use .CR vxdump to produce a dump intended for an earlier version of .CR vxrestore, and if the dump requires multiple tapes, you should use the .CR -s , .CR -d , or .CR -B option. .PP Dumps produced by older versions of .CR vxdump can be read by the current version of .CR vxrestore. .ig Tapes produced by .CR vxdump on other platforms can also be read by .CR vxrestore , provided they are not from a version of .CR vxdump more recent the version of .CR vxrestore in use. .. .SH NOTES Dumps should be performed with the file system unmounted or the system in single-user environment (see .CR init (1M)) to insure a consistent dump. If the VxFS Advanced package is installed, the dump can be performed in the multi-user environment using a snapshot file system with the online backup facility (see the .CI snapof=file option of .CR mount_vxfs (1M)). .PP Up to 32 read errors on the file system are ignored. .PP Each reel requires a new process; thus parent processes for reels already written remain until the entire tape is written. .PP .CR vxdump creates a server, .CR /usr/sbin/rmt , on the remote machine to access the tape device. .PP .ig The .CR vxdump and .CR vxrestore commands are fully interoperable with the .CR dump and .CR restore commands: tapes created by .CR vxdump can be restored by .CR restore ; and tapes created by .CR dump can be restored by .CR vxrestore . .. .SH EXAMPLES In the following example, assume that the file system .CR /mnt is normally attached to the file tree at the root directory, .RC ( / ). .PP This example causes the entire file system .RC ( /mnt ) to be dumped on .CR /dev/rmt/0m and specifies that the the size of the tape is 2 gigabytes. .IP .C vxdump -0 -B 2g -f /dev/rmt/0m /mnt .PP Or, using the traditional command line syntax and specifying the tape size in logical records: .IP .C vxdump 0Bf 2097152 /dev/rmt/0m /mnt .PP where the option argument ``2097152'' goes with the option letter .C B as it is the first option letter that requires an option argument, and where the option argument ``/dev/rmt/0m'' goes with the option letter .C f as it is the second option letter that requires an option argument. .SH AUTHOR .C vxdump and .C rvxdump are based on the .CR dump and .CR rdump programs from the 4.4 Berkeley Software Distribution, developed by the the University of California, Berkeley, and its contributors. .SH FILES .PD 0 .TP 30 .C /dev/rdsk/c0t0d0 Default file system to dump from. .TP .C /dev/rmt/0m Default tape unit to dump to. .TP .C /var/adm/dumpdates New format-dump-date record. .TP .C /etc/fstab Dump table: file systems and frequency. .TP .C /etc/mnttab Mounted file system table. .TP .C /etc/group Used to find group .CR operator . .PD .SH SEE ALSO rmt(1M), vxrestore(1M), fstab(4). .\" .\" toc@\f3vxdump(1M)\f1:\0\0\f(CWrvxdump\f1, \f(CWvxdump\f1@@@incremental file system dump, local or across network\f1 .\" toc@\f(CWrvxdump\f1:\0\0incremental file system dump across network@@@\f1see \f3vxdump(1M)\f1 .\" .\" index@\f(CWvxdump\f1 \- local incremental file system dump@@@\f3vxdump(1M)\f1 .\" index@\f(CWrvxdump\f1 \- incremental file system dump across network@@@\f3vxdump(1M)\f1 .\" index@\f1dump, incremental file system, local@@@\f3vxdump(1M)\f1 .\" index@\f1dump, incremental file system, across network@@@\f3vxdump(1M)\f1 .\" index@\f1file system, dump across network@@@\f3vxdump(1M)\f1 .\" index@\f1file system, local dump@@@\f3vxdump(1M)\f1 .\" index@\f1local, dump of file system@@@\f3vxdump(1M)\f1 .\" index@\f1network, dump of file system across@@@\f3vxdump(1M)\f1 .\" .\" links@vxdump.1m rvxdump.1m .\" $Header: vxrestore.1m,v 78.1 96/02/13 14:07:35 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" (c) Copyright 1996 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .\" Copyright (c) 1980, 1991, 1993 .\" Regents of the University of California. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .so /usr/share/lib/macros/vxfs.an .TA v .TH vxrestore 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vxrestore, rvxrestore (vxfs) \- restore file system incrementally, local or across network .SH SYNOPSIS .CR /usr/sbin/vxrestore .RC [ \-rRtxihmvy ] .RC [ \-s .IR number ] .RS .RC [ \-b .IR block_size ] .RC [ \-e .IR opt ] .RC [ \-f .IR file ] .RI [ \|file_name \0...\|] .RE .PP .C /usr/sbin/rvxrestore .RC [ \-rRtxihmvy ] .RC [ \-s .IR number ] .RS .RC [ \-b .IR block_size ] .RC [ \-e .IR opt ] .RC [ \-f .IR file ] .RI [ \|file_name \0...\|] .RE .PP .C /usr/sbin/vxrestore .I key .RI [ \|file_name \0...\|] .PP .C /usr/sbin/rvxrestore .I key .RI [ \|file_name \0...\|] .SH DESCRIPTION .C rvxrestore is another name for .CR vxrestore . .C vxrestore reads tapes previously dumped by the .C vxdump or .C rvxdump command (see .IR vxdump (1M) ). .PP .CR vxrestore and .CR rvxrestore support both .IR getopt (3C) and traditional .CR restore command line invocations as shown above. The original .CR restore command line style is supported for compatibility with previous versions of .CR vxrestore and for synonymy with the existing .CR restore program used for hfs file systems. .PP For the original .CR restore command line style, actions taken are controlled by the .I key argument where .I key is a string of characters containing exactly one function letter from the group .CR rRxtsi , and zero or more function modifiers from the group .CR befhmvy . One or more .I file_name arguments, if present, are file or directory names specifying the files that are to be restored. Unless the .C h modifier is specified (see below), the appearance of a directory name refers to the files and (recursively) subdirectories of that directory. .SS Options .RS .TP 6 .CR \-r Read the tape and load into the current directory. .C \-r should be used only after careful consideration, and only to restore a complete dump tape onto a clear file system or to restore an incremental dump tape after a full-level zero restore. Thus, .RS .IP .nf .C /usr/sbin/newfs -F vxfs /dev/rdsk/c0t0d0 .C /usr/sbin/mount -F vxfs /dev/dsk/c0t0d0 /mnt .C cd /mnt .C vxrestore -r .fi .RE .IP is a typical sequence to restore a complete dump. Another .C vxrestore can then be performed to restore an incremental dump on top of this. Note that .C vxrestore leaves a file .C restoresymtab in the root directory of the file system to pass information between incremental .C vxrestore passes. This file should be removed when the last incremental tape has been restored. .TP .C \-R Resume a full restore. .C vxrestore restarts from a checkpoint it created during a full restore (see .C \-r above). It requests a particular tape of a multi-volume set on which to restart a full restore. This provides a means for interrupting and restarting a multi-volume .CR vxrestore . .TP .C \-x Extract named files from the tape. If the named file matches a directory whose contents had been written onto the tape, and the .C \-h option is not specified, the directory is recursively extracted. The owner, modification time, and mode are restored (if possible). If no .I file_name argument is given, the root directory is extracted, which results in the entire contents of the tape being extracted, unless .C \-h has been specified. .TP .C \-t Names of .I file_names, as specified on the command line, are listed if they occur on the tape. If no .I file_name is given, the root directory is listed, which results in the entire content of the tape being listed, unless .C \-h has been specified. .TP .CI \-s number .I number is used as the dump file number to recover. This is useful if there is more than one dump file on a tape. .TP .C \-i This option allows interactive restoration of files from a dump tape. After reading in the directory information from the tape, .C vxrestore provides a shell-like interface that allows the user to move around the directory tree selecting files to be extracted. The available commands are given below; for those commands that require an argument, the default is the current directory. .RS .RS .TP 15 .CR add \0[\f2arg\fP] The current directory or specified argument is added to the list of files to be extracted. If a directory is specified, it and all its descendents are added to the extraction list (unless the .C h key is specified on the command line). File names on the extraction list are displayed with a leading .C \(** when listed by .CR ls . .TP .CR cd \0[\f2arg\fP] Change the current working directory to the specified argument. .TP .CR delete \0[\f2arg\fP] The current directory or specified argument is deleted from the list of files to be extracted. If a directory is specified, it and all its descendents are deleted from the extraction list (unless .C h is specified on the command line). The most expedient way to extract most files from a directory is to add the directory to the extraction list, then delete unnecessary files. .TP .C extract All files named on the extraction list are extracted from the dump tape. .C vxrestore asks which volume the user wants to mount. The fastest way to extract a few files is to start with the last volume, then work toward the first volume. .TP .C help List a summary of the available commands. .TP .CR ls \0[\f2arg\fP] List the current or specified directory. Entries that are directories are displayed with a trailing .CR / . Entries marked for extraction are displayed with a leading .CR \(** . If the verbose key is set, the inode number of each entry is also listed. .TP .C pwd Print the full pathname of the current working directory. .TP .C quit .C vxrestore immediately exits, even if the extraction list is not empty. .TP .C set-modes Set the owner, modes, and times of all directories that are added to the extraction list. Nothing is extracted from the tape. This setting is useful for cleaning up after a restore aborts prematurely. .TP .C verbose The sense of the .C v modifier is toggled. When set, the verbose key causes the .C ls command to list the inode numbers of all entries. It also causes .C vxrestore to print out information about each file as it is extracted. .RE .RE .RE The following options can be used in addition to the letter that selects the primary function desired: .RS .TP 6 .CI \-b " block_size" Specify the block size of the tape in Kbytes. If the .C \-b option is not specified, .C vxrestore will determine the tape block size dynamically. [This option is exists to preserve backwards compatibility with previous versions of .CR vxrestore .] .TP .CI \-e " opt" Specify how to handle a .I vxfs file that has extent attribute information. Extent attributes include reserved space, a fixed extent size, and extent alignment. It may not be possible to preserve the information if the destination file system does not support extent attributes, has a different block size than the source file system, or lack free extents appropriate to satisfy the extent attribute requirements. Valid values for .I opt are: .RS .TP 10 .C warn Issue a warning message if extent attribute information cannot be kept (the default). .TP .C force Fail to restore the file if extent attribute information cannot be kept. .TP .C ignore Ignore extent attribute information entirely. .RE .TP .CI \-f " file" Specify the name of the archive instead of .CR /dev/rmt/0m . If the name of the file is .CR \- , .C vxrestore reads from standard input. Thus, .C vxdump and .C vxrestore can be used in a pipeline to vxdump and vxrestore a file system with the command .RS .IP .C "vxdump 0f \- /usr | (cd /mnt; vxrestore xf \-) .RE .IP An archive name of the form .IC machine : device can be used to specify a tape device on a remote machine. .TP .C \-h Extract the actual directory, rather than the files to which it refers. This prevents hierarchical restoration of complete subtrees. .TP .C \-m Extract by inode numbers rather than by file name. This is useful if only a few files are being extracted and one wants to avoid regenerating the complete pathname to the file. .TP .C \-v Type the name of each file restored, preceded by its file type. Normally .C vxrestore does its work silently; the .C \-v option specifies verbose output. .TP .C \-y Do not ask whether to abort the operation if .C vxrestore encounters a tape error. Normally .C vxrestore asks whether to continue after encountering a read error. With this option, .C vxrestore continues without asking, attempting to skip over the bad tape block(s) and continue as best it can. .RE .PP .C vxrestore creates a server, .CR /usr/sbin/rmt , on the remote machine to access the tape device. .SH DIAGNOSTICS .PP .C vxrestore complains if a read error is encountered. If the .C \-y option has been specified, or the user responds .CR y , .C vxrestore attempts to continue the restore. .PP If the dump extends over more than one tape, .C vxrestore asks the user to change tapes. If the .C \-x or .C \-i option has been specified, .C vxrestore also asks which volume the user wants to mount. The fastest way to extract a few files is to start with the last volume and work towards the first volume. .PP There are numerous consistency checks that can be listed by .CR vxrestore . Most checks are self-explanatory or can ``never happen''. Here are some common errors: .RS .TP .IC filename ": not found on tape" The specified file name was listed in the tape directory but not found on the tape. This is caused by tape read errors while looking for the file, and from using a dump tape created on an active file system. .TP .CI "expected next file " inumber ", got " inumber A file not listed in the directory showed up. This can occur when using a dump tape created on an active file system. Dumps should be performed with the file system unmounted or the system in single-user environment (see .CR init (1M)) to insure a consistent dump. If the VxFS Advanced package is installed, the dump can be performed in the multi-user environment using a snapshot file system with the online backup facility (see the .CI snapof=file option of .CR mount_vxfs (1M)). .TP .C "Incremental tape too low" When doing an incremental restore, a tape that was written before the previous incremental tape, or that has too low an incremental level has been loaded. .TP .C "Incremental tape too high" When doing an incremental restore, a tape that does not begin its coverage where the previous incremental tape left off, or that has too high an incremental level has been loaded. .TP .CI "Tape read error while restoring " filename" .PD 0 .TP .CI "Tape read error while skipping over inode " inumber" .TP .C "Tape read error while trying to resynchronize" A tape-read error has occurred. If a file name is specified, the contents of the restored files are probably partially wrong. If .C vxrestore is skipping an inode or is trying to resynchronize the tape, no extracted files are corrupted, although files may not be found on the tape. .PD .TP .CI "Resync restore, skipped " num " blocks" After a tape-read error, .C vxrestore may have to resynchronize itself. This message indicates the number of blocks skipped over. This message will also be generated by older versions of .C vxrestore while skipping over files larger than 2 Gbyte dumped by a more recent version of .CR vxdump . .SH NOTES If the dump tape contains files larger than 2 Gbyte, and if the file system being restored to does not support files larger than 2 Gbyte, the file will not be restored correctly. Instead it will be truncated to 2 Gbyte. .PP A file with a large .I uid (user ID of the file owner) or large .I gid (group ID of the file owner) cannot be restored correctly on a file system that does not support large IDs. Instead, the owner and/or group of the file will be that of the user invoking .CR vxrestore . (A large ID is a value grater than 65535. The VxFS Version 2 disk layout does not support lage IDs). .PP Dumps produced by older versions of .CR vxdump can be read by the current version of .CR vxrestore . .ig Dumps produced by .CR vxdump on other platforms can also be read by .CR vxrestore , provided they are not from a version of .CR vxdump more recent the version of .CR vxrestore in use. .. .PP .C vxrestore can restore files to a file system of a type other than VxFS. If the file system type does not support extent attributes, than the extent attributes will not be restored (see the .C -e option). .PP .SH WARNINGS .C vxrestore can get confused when doing incremental restores from dump tapes that were made on active file systems. .PP A level-zero dump (see the .CR vxdump (1M) manual page) must be done after a full restore. Since .C vxrestore runs in user code, it has no control over inode allocation; thus a full dump must be done to get a new set of directories reflecting the new inode numbering, even though the contents of the files are unchanged. .SH AUTHOR .CR vxrestore and .CR rvxrestore are based on the .CR restore program distributed in the 4.4 Berkeley Software Distribution, developed by the the University of California, Berkeley, and its contributors. .SH FILES .TP 20 .C /dev/rmt/0m default tape drive .TP .C /tmp/rstdr\(** file containing directories on the tape .TP .C /tmp/rstmd\(** owner, mode, and time stamps for directories .TP .C ./restoresymtab information passed between incremental restores .SH SEE ALSO .CR vxdump (1M), .CR extendfs_vxfs (1M), .CR fsadm_vxfs (1M), .CR mkfs (1M), .CR mount (1M), .CR newfs (1M), .CR rmt (1M). .\" toc@\f3vxrestore(1M)\f1:\0\0\f(CWvxrestore\f1, \f(CWrvxrestore\f1@@@restore file system incrementally, local or across network\f1 .\" toc@\f(CWrvxrestore\f1:\0\0 restore file system incrementally across network\f1@@@see \f3vxrestore(1M)\f1 .\" index@\f(CWvxrestore\f1 \- restore file system incrementally, local or across network@@@\f3vxrestore(1M)\f1 .\" index@\f(CWrvxrestore\f1 \- restore file system incrementally across network@@@\f3vxrestore(1M)\f1 .\" index@restore file system incrementally, local or across network@@@\f3vxrestore(1M)\f1 .\" index@file system, restore incrementally, local or across network @@@\f3vxrestore(1M)\f1 .\" index@local file system, restore incrementally@@@\f3vxrestore(1M)\f1 .\" index@remote file system, restore incrementally@@@\f3rvxrestore(1M)\f1 .\" links@vxrestore.1m rvxrestore.1m .\" $Header: rwall.1m,v 74.2 95/04/17 12:00:22 ssa Exp $ .TA r .TH rwall 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rwall \- write to all users over a network .SH SYNOPSIS .C /usr/sbin/rwall .IR hostname \0... .br .C /usr/sbin/rwall -n .IR netgroup \0... .br .C /usr/sbin/rwall -h .I host .C -n .I netgroup .SH DESCRIPTION .CR rwall reads a message from standard input until EOF, then sends the message, preceded by the line .CR "Broadcast Message " ...\|, to all users logged in on the specified host machines. With the .CR -n option, .CR rwall sends the message to the specified network hosts defined in .CR /etc/netgroup (see .IR netgroup (4)). .PP A machine can only receive such a message if it is running .CR rwalld , which is normally started from .CR /etc/inetd.conf by the .CR inetd daemon (see .IR inetd (1M)). .SH WARNINGS The timeout is kept fairly short so that the message can be sent to a large group of machines (some of which may be down) in a reasonable amount of time. Thus, the message may not get through to a heavily loaded machine. .SH AUTHOR .CR rwall was developed by Sun Microsystems, Inc. .SH FILES .CR /etc/inetd.conf .SH SEE ALSO rwalld(1M), shutdown(1M), wall(1M), netgroup(4). .\" .\" index@\f4rwall\f1 \- write to all users over a network@@@\f3rwall(1M)\f1 .\" index@\f1write to all users over a network@@@\f3rwall(1M)\f1 .\" index@\f1all users over a network, write to@@@\f3rwall(1M)\f1 .\" index@\f1users over a network, write to all@@@\f3rwall(1M)\f1 .\" index@\f1network, write to all users over a@@@\f3rwall(1M)\f1 .\" .\" toc@\f3rwall(1M)\f1: \0\0\f4rwall\f1@@@write to all users over a network .\" $Header: rwalld.1m,v 72.4 94/06/30 14:58:41 ssa Exp $ .TA r .TH rwalld 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rwalld \- network rwall server .SH SYNOPSIS .C /usr/lib/netsvc/rwall/rpc.rwalld .RC [ -l .IR log_file ] .RC [ -e \(or -n ] .SH DESCRIPTION .CR rwalld is an RPC server that handles .CR rwall requests (see .IR rwall (1)). .CR rwalld calls .CR wall to send a message to all users logged into the host on which .CR rwalld is running (see .IR wall (1)). .PP .CR inetd invokes .CR rwalld through .CR /etc/inetd.conf (see .IR inetd (1M)). .SS Options .CR rwalld recognizes the following options and command-line options: .RS .TP 15 .CI -l \0log_file Log any errors to .IR log_file . Errors are not logged if the .CR -l option is not specified. .IP Information logged to the log file includes date and time of the error, the host name, process ID and name of the function generating the error, and the error message. Note that different services can share a single log file because enough information is included to uniquely identify each error. .TP .CR -e Exit after serving each RPC request. Using the .CR -e option, the .CR inetd security file .CR /var/adm/inetd.sec can control access to RPC services. .TP .CR -n Exit only if: .RS .RS .TP 3 \(bu .CR portmap dies (see .IR portmap (1M)), .TP \(bu another .CR rpc.rwalld registers with .CR portmap , or .TP \(bu .CR rpc.rwalld becomes unregistered with .CR portmap . .RE .RE .RE .PP The .CR -n option is more efficient because a new process is not launched for each RPC request. Note, this option is the default. .SH AUTHOR .CR rwalld was developed by Sun Microsystems, Inc. .SH SEE ALSO inetd(1M), portmap(1M), rwall(1M), wall(1M), inetd.conf(4), inetd.sec(4), services(4). .\" .\" index@\f4rwalld\f1: network \f4rwall\f1 server@@@\f3rwalld(1M)\f1 .\" index@network \f4rwall\f1 server@@@\f3rwalld(1M)\f1 .\" index@rwall server, network@@@\f3rwalld(1M)\f1 .\" index@server, network \f4rwall\f1@@@\f3rwalld(1M)\f1 .\" .\" toc@\f3rwalld(1M)\f1: \f4rwalld\f1@@@network rwall server .\" $Header: rwhod.1m,v 72.5 94/12/09 15:07:07 ssa Exp $ .TA r .TH rwhod 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rwhod \- system status server .SH SYNOPSIS .C /usr/lbin/rwhod .RC [ -s ] .RC [ -r ] .SH DESCRIPTION .C rwhod is the server that maintains the database used by .C rwho and .C ruptime (see .IR rwho (1) and .IR ruptime (1)). .C rwhod sends status information to and receives status information from other nodes on the local network that are running .CR rwhod . .PP .C rwhod is started at system boot time if the RWHOD variable is set to 1 in the file .CR /etc/rc.config.d/netdaemons . .PP As an information sender, it periodically queries the state of the system and constructs status messages that are broadcast on a network. .PP As an information receiver, it listens for other .C rwhod servers' status messages, validates them, then records them in a collection of files located in the .C /var/spool/rwho directory. .PP By default, .C rwhod both sends and receives information. .C rwhod also supports the following options: .RS .TP 8 .C -s Configures server to be an information sender only. .TP .C -r Configures server to be an information receiver only. .RE .PP Status messages are generated approximately once every three minutes. .C rwhod transmits and receives messages at the port indicated in the .C who service specification (see .IR services (4)). The messages sent and received, are of the form: .nf .IP .C "struct outmp {" .C " char out_line[8]; /* tty name */" .C " char out_name[8]; /* user id */" .C " long out_time; /* time on */" .C "}; .IP .C "struct whod {" .C " char wd_vers;" .C " char wd_type;" .C " char wd_fill[2];" .C " int wd_sendtime;" .C " int wd_recvtime;" .C " char wd_hostname[32];" .C " int wd_loadav[3];" .C " int wd_boottime;" .C " struct whoent {" .C " struct outmp we_utmp;" .C " int we_idle;" .C " } wd_we[1024 / sizeof (struct whoent)];" .C }; .fi .PP All fields are converted to network byte order before transmission. System load averages are calculated from the number of jobs in the run queue over the last 1-, 5- and 15-minute intervals. The host name included is the one returned by the .C gethostname() system call (see .IR gethostname (2)). The array at the end of the message contains information about the users logged in on the sending machine. This information includes the contents of the .C utmp entry for each non-idle terminal line and a value indicating the time since a character was last received on the terminal line (see .IR utmp (4)). .PP .C rwhod discards received messages if they did .C not originate at a .C rwho server's port, or if the host's name, as specified in the message, contains any unprintable .SM ASCII characters. .PP Valid messages received by .C rwhod are placed in files named .CI whod. hostname in the .C /var/spool/rwho directory. These files contain only the most recent message in the format described above. .SH WARNINGS .C rwhod does not relay status information between networks. Users often incorrectly interpret the server dying as a machine going down. .SH AUTHOR .C rwhod was developed by the University of California, Berkeley. .SH FILES .TP 33 .C /var/spool/rwho/whod.* Information about other machines. .SH SEE ALSO rwho(1), ruptime(1). .\" .\" index@\f4rwhod\f1 \- system status server@@@\f3rwhod(1M)\f1 .\" index@system status server@@@\f3rwhod(1M)\f1 .\" index@status server, system@@@\f3rwhod(1M)\f1 .\" index@server, system status@@@\f3rwhod(1M)\f1 .\" .\" toc@\f3rwhod(1M)\f1:\0\0\f4rwhod\f1@@@system status server .\" .\" fileset_database@rwhod.1m INETSVCS-MAN .\" $Header: sa1.1m,v 72.6 94/11/29 13:25:20 ssa Exp $ .TA s .TH sa1 1M "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not implemented on 700 .SH NAME sa1, sa2, sadc \- system activity report package .SH SYNOPSIS .C /usr/lbin/sa/sa1 .RI [ "\|t n\|" ] .PP .C /usr/lbin/sa/sa2 .RC [ -ubdycwaqvmA\| ] .RC [ -s .IR time\| ] .RC [ -e .IR time\| ] .RC [ -i .IR sec\| ] .PP .C /usr/lbin/sa/sadc .RI [ "\|t n\|" ] .RI [ \|ofile\| ] .SH DESCRIPTION System activity data can be accessed at the special request of a user (see .IR sar (1)) and automatically on a routine basis as described here. The operating system contains a number of counters that are incremented as various system actions occur. These include .SM CPU utilization counters, buffer usage counters, disk and tape .SM I/O activity counters, tty device activity counters, switching and system-call counters, file-access counters, queue activity counters, and counters for inter-process communications. .PP .C sadc and shell procedures .C sa1 and .C sa2 are used to sample, save, and process this data. .PP .CR sadc , the data collector, samples system data .I n times every .I t seconds and writes in binary format to .I ofile or to standard output. If .I t and .I n are omitted, a special record is written. This facility is used at system boot time to mark the time at which the counters restart from zero. Executing the following command in a system startup script: .IP .C /usr/lbin/sa/sadc /var/adm/sa/sa`date +%d` .PP writes the special record to the daily data file to mark the system restart. Instructions for creating system startup scripts may be found in the 10.0 File System Layout White Paper, which is online in file .CR /usr/share/doc/filesys.ps . .PP The shell script .CR sa1 , a variant of .CR sadc , is used to collect and store data in binary file .CI /var/adm/sa/sa dd where .I dd is the current day. The arguments .I t and .I n cause records to be written .I n times at an interval of .I t seconds, or once if omitted. The following entries, if placed in .CR crontab , produce records every 20 minutes during working hours and hourly otherwise (see .IR cron (1M)): .nf .IP .C "0 * * * 0,6 /usr/lbin/sa/sa1" .C "0 8-17 * * 1-5 /usr/lbin/sa/sa1 1200 3" .C "0 18-7 * * 1-5 /usr/lbin/sa/sa1" .fi .PP The shell script .CR sa2 , a variant of .CR sar , writes a daily report in file .CI /var/adm/sa/sar dd\f1. The options are explained in .IR sar (1). The following .C crontab entry reports important activities hourly during the working day: .IP .C "5 18 * * 1-5 /usr/lbin/sa/sa2 -s 8:00 -e 18:01 -i 3600 -A" .PP The structure of the binary daily data file is: .nf .IP .ift .ft 4 .ps +1 struct sa { struct sysinfo si; /* see /usr/include/sys/sysinfo.h */ int sztext; /* current entries of text table */ int szinode; /* current entries of inode table */ int szfile; /* current entries of file table */ int szproc; /* current entries of proc table */ int msztext; /* size of text table */ int mszinode; /* size of inode table */ int mszfile; /* size of file table */ int mszproc; /* size of proc table */ long textovf; /* cumul. overflows of text table */ long inodeovf; /* cumul. overflows of inode table */ long fileovf; /* cumul. overflows of file table */ long procovf; /* cumul. overflows of proc table */ time_t ts; /* time stamp, seconds */ long devio[NDEVS][4]; /* device info for up to NDEVS units */ #define IO_OPS 0 /* cumul. I/O requests */ #define IO_BCNT 1 /* cumul. blocks transferred */ #define IO_ACT 2 /* cumul. drive busy time in ticks */ #define IO_RESP 3 /* cumul. I/O resp time in ticks */ }; .ift .ft 1 .ps .fi .SH FILES .TP 35 .CI /tmp/sa. adrfl address file .PD 0 .TP .CI /var/adm/sa/sa dd daily data file .TP .CI /var/adm/sa/sar dd daily report file .PD .SH SEE ALSO cron(1M), sar(1), timex(1). .SH STANDARDS CONFORMANCE .CR sa1 ": SVID2, SVID3" .PP .CR sa2 ": SVID2, SVID3" .PP .CR sadc ": SVID2, SVID3" .\" .\" index@\f4sa1\f1, \f4sa2\f1, \f4sadc\f1 \- system activity report package@@@\f3sa1(1M)\f1 .\" index@\f4sadc\f1 \- collect and output or store system activity data@@@\f3sa1(1M)\f1 .\" index@\f4sa1\f1 \- collect and output or store system activity data in binary file@@@\f3sa1(1M)\f1 .\" index@\f4sa2\f1 \- write daily system activity report in binary file@@@\f3sa1(1M)\f1 .\" index@daily system activity report package@@@\f3sa1(1M)\f1 .\" index@report daily system activity@@@\f3sa1(1M)\f1 .\" index@system activity daily report package@@@\f3sa1(1M)\f1 .\" index@activity, system, daily report package@@@\f3sa1(1M)\f1 .\" .\" toc@\f3sa1(1M)\f1:\0\0\f4sa1\f1, \f4sa2\f1, \f4sadc\f1@@@system activity report package .\" toc@\f4sa2\f1:\0\0system activity report package@@@see \f3sa1(1M)\f1 .\" toc@\f4sadc\f1:\0\0system activity report package@@@see \f3sa1(1M)\f1 .\" .\" links@sa1.1m sa2.1m .\" links@sa1.1m sadc.1m .\" .\" fileset_database@sa1.1m SYS-ADMIN-MAN .\" $Header: sa1.1m,v 72.6 94/11/29 13:25:20 ssa Exp $ .TA s .TH sa1 1M "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not implemented on 700 .SH NAME sa1, sa2, sadc \- system activity report package .SH SYNOPSIS .C /usr/lbin/sa/sa1 .RI [ "\|t n\|" ] .PP .C /usr/lbin/sa/sa2 .RC [ -ubdycwaqvmA\| ] .RC [ -s .IR time\| ] .RC [ -e .IR time\| ] .RC [ -i .IR sec\| ] .PP .C /usr/lbin/sa/sadc .RI [ "\|t n\|" ] .RI [ \|ofile\| ] .SH DESCRIPTION System activity data can be accessed at the special request of a user (see .IR sar (1)) and automatically on a routine basis as described here. The operating system contains a number of counters that are incremented as various system actions occur. These include .SM CPU utilization counters, buffer usage counters, disk and tape .SM I/O activity counters, tty device activity counters, switching and system-call counters, file-access counters, queue activity counters, and counters for inter-process communications. .PP .C sadc and shell procedures .C sa1 and .C sa2 are used to sample, save, and process this data. .PP .CR sadc , the data collector, samples system data .I n times every .I t seconds and writes in binary format to .I ofile or to standard output. If .I t and .I n are omitted, a special record is written. This facility is used at system boot time to mark the time at which the counters restart from zero. Executing the following command in a system startup script: .IP .C /usr/lbin/sa/sadc /var/adm/sa/sa`date +%d` .PP writes the special record to the daily data file to mark the system restart. Instructions for creating system startup scripts may be found in the 10.0 File System Layout White Paper, which is online in file .CR /usr/share/doc/filesys.ps . .PP The shell script .CR sa1 , a variant of .CR sadc , is used to collect and store data in binary file .CI /var/adm/sa/sa dd where .I dd is the current day. The arguments .I t and .I n cause records to be written .I n times at an interval of .I t seconds, or once if omitted. The following entries, if placed in .CR crontab , produce records every 20 minutes during working hours and hourly otherwise (see .IR cron (1M)): .nf .IP .C "0 * * * 0,6 /usr/lbin/sa/sa1" .C "0 8-17 * * 1-5 /usr/lbin/sa/sa1 1200 3" .C "0 18-7 * * 1-5 /usr/lbin/sa/sa1" .fi .PP The shell script .CR sa2 , a variant of .CR sar , writes a daily report in file .CI /var/adm/sa/sar dd\f1. The options are explained in .IR sar (1). The following .C crontab entry reports important activities hourly during the working day: .IP .C "5 18 * * 1-5 /usr/lbin/sa/sa2 -s 8:00 -e 18:01 -i 3600 -A" .PP The structure of the binary daily data file is: .nf .IP .ift .ft 4 .ps +1 struct sa { struct sysinfo si; /* see /usr/include/sys/sysinfo.h */ int sztext; /* current entries of text table */ int szinode; /* current entries of inode table */ int szfile; /* current entries of file table */ int szproc; /* current entries of proc table */ int msztext; /* size of text table */ int mszinode; /* size of inode table */ int mszfile; /* size of file table */ int mszproc; /* size of proc table */ long textovf; /* cumul. overflows of text table */ long inodeovf; /* cumul. overflows of inode table */ long fileovf; /* cumul. overflows of file table */ long procovf; /* cumul. overflows of proc table */ time_t ts; /* time stamp, seconds */ long devio[NDEVS][4]; /* device info for up to NDEVS units */ #define IO_OPS 0 /* cumul. I/O requests */ #define IO_BCNT 1 /* cumul. blocks transferred */ #define IO_ACT 2 /* cumul. drive busy time in ticks */ #define IO_RESP 3 /* cumul. I/O resp time in ticks */ }; .ift .ft 1 .ps .fi .SH FILES .TP 35 .CI /tmp/sa. adrfl address file .PD 0 .TP .CI /var/adm/sa/sa dd daily data file .TP .CI /var/adm/sa/sar dd daily report file .PD .SH SEE ALSO cron(1M), sar(1), timex(1). .SH STANDARDS CONFORMANCE .CR sa1 ": SVID2, SVID3" .PP .CR sa2 ": SVID2, SVID3" .PP .CR sadc ": SVID2, SVID3" .\" .\" index@\f4sa1\f1, \f4sa2\f1, \f4sadc\f1 \- system activity report package@@@\f3sa1(1M)\f1 .\" index@\f4sadc\f1 \- collect and output or store system activity data@@@\f3sa1(1M)\f1 .\" index@\f4sa1\f1 \- collect and output or store system activity data in binary file@@@\f3sa1(1M)\f1 .\" index@\f4sa2\f1 \- write daily system activity report in binary file@@@\f3sa1(1M)\f1 .\" index@daily system activity report package@@@\f3sa1(1M)\f1 .\" index@report daily system activity@@@\f3sa1(1M)\f1 .\" index@system activity daily report package@@@\f3sa1(1M)\f1 .\" index@activity, system, daily report package@@@\f3sa1(1M)\f1 .\" .\" toc@\f3sa1(1M)\f1:\0\0\f4sa1\f1, \f4sa2\f1, \f4sadc\f1@@@system activity report package .\" toc@\f4sa2\f1:\0\0system activity report package@@@see \f3sa1(1M)\f1 .\" toc@\f4sadc\f1:\0\0system activity report package@@@see \f3sa1(1M)\f1 .\" .\" links@sa1.1m sa2.1m .\" links@sa1.1m sadc.1m .\" .\" fileset_database@sa1.1m SYS-ADMIN-MAN .\" $Header: sa1.1m,v 72.6 94/11/29 13:25:20 ssa Exp $ .TA s .TH sa1 1M "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not implemented on 700 .SH NAME sa1, sa2, sadc \- system activity report package .SH SYNOPSIS .C /usr/lbin/sa/sa1 .RI [ "\|t n\|" ] .PP .C /usr/lbin/sa/sa2 .RC [ -ubdycwaqvmA\| ] .RC [ -s .IR time\| ] .RC [ -e .IR time\| ] .RC [ -i .IR sec\| ] .PP .C /usr/lbin/sa/sadc .RI [ "\|t n\|" ] .RI [ \|ofile\| ] .SH DESCRIPTION System activity data can be accessed at the special request of a user (see .IR sar (1)) and automatically on a routine basis as described here. The operating system contains a number of counters that are incremented as various system actions occur. These include .SM CPU utilization counters, buffer usage counters, disk and tape .SM I/O activity counters, tty device activity counters, switching and system-call counters, file-access counters, queue activity counters, and counters for inter-process communications. .PP .C sadc and shell procedures .C sa1 and .C sa2 are used to sample, save, and process this data. .PP .CR sadc , the data collector, samples system data .I n times every .I t seconds and writes in binary format to .I ofile or to standard output. If .I t and .I n are omitted, a special record is written. This facility is used at system boot time to mark the time at which the counters restart from zero. Executing the following command in a system startup script: .IP .C /usr/lbin/sa/sadc /var/adm/sa/sa`date +%d` .PP writes the special record to the daily data file to mark the system restart. Instructions for creating system startup scripts may be found in the 10.0 File System Layout White Paper, which is online in file .CR /usr/share/doc/filesys.ps . .PP The shell script .CR sa1 , a variant of .CR sadc , is used to collect and store data in binary file .CI /var/adm/sa/sa dd where .I dd is the current day. The arguments .I t and .I n cause records to be written .I n times at an interval of .I t seconds, or once if omitted. The following entries, if placed in .CR crontab , produce records every 20 minutes during working hours and hourly otherwise (see .IR cron (1M)): .nf .IP .C "0 * * * 0,6 /usr/lbin/sa/sa1" .C "0 8-17 * * 1-5 /usr/lbin/sa/sa1 1200 3" .C "0 18-7 * * 1-5 /usr/lbin/sa/sa1" .fi .PP The shell script .CR sa2 , a variant of .CR sar , writes a daily report in file .CI /var/adm/sa/sar dd\f1. The options are explained in .IR sar (1). The following .C crontab entry reports important activities hourly during the working day: .IP .C "5 18 * * 1-5 /usr/lbin/sa/sa2 -s 8:00 -e 18:01 -i 3600 -A" .PP The structure of the binary daily data file is: .nf .IP .ift .ft 4 .ps +1 struct sa { struct sysinfo si; /* see /usr/include/sys/sysinfo.h */ int sztext; /* current entries of text table */ int szinode; /* current entries of inode table */ int szfile; /* current entries of file table */ int szproc; /* current entries of proc table */ int msztext; /* size of text table */ int mszinode; /* size of inode table */ int mszfile; /* size of file table */ int mszproc; /* size of proc table */ long textovf; /* cumul. overflows of text table */ long inodeovf; /* cumul. overflows of inode table */ long fileovf; /* cumul. overflows of file table */ long procovf; /* cumul. overflows of proc table */ time_t ts; /* time stamp, seconds */ long devio[NDEVS][4]; /* device info for up to NDEVS units */ #define IO_OPS 0 /* cumul. I/O requests */ #define IO_BCNT 1 /* cumul. blocks transferred */ #define IO_ACT 2 /* cumul. drive busy time in ticks */ #define IO_RESP 3 /* cumul. I/O resp time in ticks */ }; .ift .ft 1 .ps .fi .SH FILES .TP 35 .CI /tmp/sa. adrfl address file .PD 0 .TP .CI /var/adm/sa/sa dd daily data file .TP .CI /var/adm/sa/sar dd daily report file .PD .SH SEE ALSO cron(1M), sar(1), timex(1). .SH STANDARDS CONFORMANCE .CR sa1 ": SVID2, SVID3" .PP .CR sa2 ": SVID2, SVID3" .PP .CR sadc ": SVID2, SVID3" .\" .\" index@\f4sa1\f1, \f4sa2\f1, \f4sadc\f1 \- system activity report package@@@\f3sa1(1M)\f1 .\" index@\f4sadc\f1 \- collect and output or store system activity data@@@\f3sa1(1M)\f1 .\" index@\f4sa1\f1 \- collect and output or store system activity data in binary file@@@\f3sa1(1M)\f1 .\" index@\f4sa2\f1 \- write daily system activity report in binary file@@@\f3sa1(1M)\f1 .\" index@daily system activity report package@@@\f3sa1(1M)\f1 .\" index@report daily system activity@@@\f3sa1(1M)\f1 .\" index@system activity daily report package@@@\f3sa1(1M)\f1 .\" index@activity, system, daily report package@@@\f3sa1(1M)\f1 .\" .\" toc@\f3sa1(1M)\f1:\0\0\f4sa1\f1, \f4sa2\f1, \f4sadc\f1@@@system activity report package .\" toc@\f4sa2\f1:\0\0system activity report package@@@see \f3sa1(1M)\f1 .\" toc@\f4sadc\f1:\0\0system activity report package@@@see \f3sa1(1M)\f1 .\" .\" links@sa1.1m sa2.1m .\" links@sa1.1m sadc.1m .\" .\" fileset_database@sa1.1m SYS-ADMIN-MAN .\" $Header: sadp.1m,v 72.7 94/11/29 13:25:41 ssa Exp $ .TA s .TH sadp 1M "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sadp \- disk access profiler .SH SYNOPSIS .CR /usr/sbin/sadp .RC \|[ -th ]\| .RC \|[ -d .IR device [ -drive ]\|]\| .IR interval .RI \|[ count ]\| .SH DESCRIPTION .CR sadp reports disk access location and seek distance, in tabular or histogram form, or both. It samples disk activity once every second during an interval of .IR interval seconds. This is done .IR count times if .IR count is specified. Cylinder usage and disk distance are recorded in units of 8 cylinders. .SS Options .CR sadp recognizes the following options and command-line arguments: .RS .TP 15 .C -t (default) Report data in tabular form. .TP 15 .C -h Produce a histogram of the data. .TP .CI -d \0device Profile a specified device. The following are valid values for .IR device are: .RS .RS .TP 10 .CR disc1 .SM HP-IB disks (CS/80). .TP .CR disc2 Fiber Link (\s-1FL\s0) disk. .TP .CR disc3 Small Computer Systems Interface (\s-1SCSI\s0) disk. .TP .C sdisk .SM SCSI disks. .RE .RE .IP .CR sadp can profile only one device type per invocation. The .CR -d option can be omitted if the system has only one device type. .TP .I -drive Specify the disk drive. .IR drive can be one of the following: .RS .RS 3 .TP 3 \(bu The instance number of the interface card to which .IR device is configured, as reported by the .C ioscan command (see .IR ioscan (1M)). .TP \(bu Two .SM instance numbers separated by a minus (indicating an inclusive range). .TP \(bu A list of .SM instance numbers separated by commas. .RE .RE .IP If .I -drive is specified, it must follow .I device without a space (see EXAMPLES). If .IR -drive is not specified, .CR sadp profiles all the disk drives configured for .IR device . The .SM instance number can be in the range 0 to 255 for .CR disc1 , .CR disc2 , .CR disc3 , and .CR sdisk device drivers. .RE .SH EXAMPLES Generate four tabular reports, each describing cylinder usage and seek distance of .CR disc1 , the device driver for disk drive at instance 0, during a fifteen-minute interval: .IP .C "sadp -d disc1-0 900 4" .SH SEE ALSO ioscan(1M), kmem(7), mem(7). .SH STANDARDS CONFORMANCE .CR sadp ": SVID2" .\" .\" toc@\f3sadp(1M):\f1\0\0\f4sadp\f1@@@disk access profiler .\" .\" index@\f4sadp\f1 \- disk access profiler@@@\f3sadp(1M)\f1 .\" index@\f1disk access profiler@@@\f3sadp(1M)\f1 .\" index@\f1access profiler, disk@@@\f3sadp(1M)\f1 .\" index@\f1profiler, disk access@@@\f3sadp(1M)\f1 .\" $Header: sam.1m,v 78.1 96/02/12 16:31:41 ssa Exp $ .TA s .TH sam 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sam \- system administration manager .SH SYNOPSIS .CR /usr/sbin/sam .RC [ \-display .IR display ] .RC [ \-f .IR login ] .RC [ \-r ] .SH DESCRIPTION The .CR sam command starts a menu-driven System Administration Manager program (SAM) that makes it easy to perform system administration tasks with only limited, specialized knowledge of the HP-UX operating system. SAM discovers most aspects of a system's configuration through automated inquiries and tests. Help menus describe how to use SAM and perform the various management tasks. Context-sensitive help on the currently highlighted field is always available by pressing the .BR F1 function key. Status messages and a log file monitor keep the user informed of what SAM is doing. .SS "Running SAM" SAM has been tuned to run in the Motif environment, but it can be run on text terminals as well. To run SAM in the Motif environment, be sure that Motif has been installed on your system, and that the .BR DISPLAY environment variable is set to the system name on which the SAM screens should be displayed (or use the .CR \-display command line option). .PP Generally, SAM requires superuser (user .CR root ) privileges to execute successfully. However, SAM can be configured (through the use of "Restricted SAM"; see below) to allow subsets of its capabilities to be used by .RC non- root users. When Restricted SAM is used, .RC non- root users are promoted to .CR root when necessary to enable them to execute successfully. .SS "Options" .CR sam recognizes the following options. .RS .TP 20 .CI \-display \0display Set the .CR DISPLAY value for the duration of the SAM session. .TP .CI \-f \0login Execute SAM with the privileges associated with the specified .IR login . When used in conjunction with .CR \-r , the Restricted SAM Builder is invoked and initialized with the privileges associated with the specified .IR login . You must be a superuser to use this option. See "Restricted SAM" below for more information. .TP .CR \-r Invoke the Restricted SAM Builder. This enables the system administrator to provide limited nonsuperuser access to SAM functionality. You must be a superuser to use this option. See "Restricted SAM" below for more information. .RE .SS "SAM Functional Areas" SAM performs system administration tasks in the following areas: .PP .B "Auditing and Security (Trusted Systems)" .RS .TP 3 \(bu Set global system security policies .RS .RS 2 .TP 3 \(bu Maximum account inactivity period .PD 0 .TP \(bu Password generation policies .TP \(bu Null password usage and use of password restriction rules .TP \(bu Password aging .TP \(bu Maximum unsuccessful login attempts .TP \(bu Single-user boot authorization .TP \(bu Terminal security policies .PD .RE .RE .TP \(bu Turn the Auditing system on or off .TP \(bu Set the parameters for the Audit Logs and Size Monitor .TP \(bu View all or selected parts of the audit logs .TP \(bu Modify (or view) which users, events, and/or system calls get audited .TP \(bu Convert your system to a Trusted System .TP \(bu Convert your system to a non-Trusted System .RE .ift .ne 20 .PP .B "Backup and Recovery" .RS .TP 3 \(bu Interactively back up files to a valid backup device (cartridge tape, cartridge tape autochanger, magnetic tape, DAT, magneto-optical disk, or magneto-optical disk autochanger). The SAM interface is suspended so that you can read and/or respond to the interactive messages produced by .CR fbackup (see .IR fbackup (1M)). .TP \(bu Recover files online from a valid backup device. The SAM interface is suspended so that you can read/respond to the interactive messages produced by .CR frecover (see .IR frecover (1M)). .TP \(bu Add to, delete from, or view the automated backup schedule. .TP \(bu Obtain a list of files from a backup tape. .TP \(bu View various backup and recovery log files. .RE .PP .B "Disk and File Systems Management" .RS .TP 3 \(bu Add, configure, or unconfigure disk devices. This includes hard drives, floppy drives, CD-ROMs, magneto-optical devices, and disk arrays. .TP \(bu Add, modify, or remove local file systems, or convert them to long file names. .TP \(bu Configure HFS or VxFS file systems. .TP \(bu Remote (NFS) file systems configuration, including: .RS .RS 2 .TP 3 \(bu Add, modify, or remove remote (NFS) file systems. .TP \(bu Allow or disallow access by remote systems to local file systems. .TP \(bu Modify RPC (Remote Procedure Call) services' security. .RE .RE .TP \(bu Add, remove, or modify device or file system swap. .TP \(bu Change the primary swap device. .TP \(bu Add, modify, or remove dump devices. .TP \(bu Examine, create, extend, or reduce a volume-group pool of disks. .TP \(bu Create, extend or change number of mirrored copies of a logical volume and associated file system. .TP \(bu Remove a logical volume or increase its size. .TP \(bu Split or merge mirrored copies of a logical volume. .TP \(bu Share or unshare volume groups (only on ServiceGuard clusters running MC/LockManager distributed lock-manager software). .RE .PP .B "Diskless Cluster Configuration" .RS .TP 3 \(bu Add or remove cluster clients. You can customize the tasks of adding and removing cluster clients by specifying steps to be performed before and/or after SAM does its processing for the task. The .CR "Task Customization" action leads you through this capability. See "Customizing SAM Tasks" below for more information. .RE .PP .B "Kernel and Device Configuration" .RS .TP 3 \(bu Change the configuration for I/O device and pseudo drivers. .TP \(bu Modify operating system parameters. .TP \(bu Modify dump device configuration in the kernel. .TP \(bu Minimize kernel and system configuration to reduce memory usage (Series 700 only). .TP \(bu Add or remove optional subsystems such as NFS, LAN, NS, CD-ROM, etc. .TP \(bu Generate a new kernel. .RE .PP .B "Networks/Communications" .RS .TP 3 \(bu Configure one or more LAN cards. .TP \(bu Configure ARPA services. .TP \(bu Configure the Network File System (NFS). .TP \(bu Configure X.25 card or cards and PAD (Packet Assembler/Disassembler) services (if X.25 has been purchased). .RE .PP .B "Peripheral Devices Management" .RS .TP 3 \(bu Administer the LP spooler or Distributed Print Services and associated printers and plotters (see "Printer and Plotter Management" below). .TP \(bu Add, modify, or remove the configuration of disk devices. .TP \(bu Add or remove terminals and modems. .TP \(bu Configure terminal security policies (Trusted Systems only). .TP \(bu Lock and unlock terminals (Trusted Systems only). .TP \(bu Add or remove tape drives. .TP \(bu Add or remove hardware interface cards and HP-IB instruments. .TP \(bu View current configuration of peripherals and disk space information. .RE .PP .B "Printer and Plotter Management" .br SAM supports two methods for managing printers and plotters: .PP .RS .B "LP Spooler" .RS .TP 3 \(bu Add and remove local, remote, and networked printers and plotters to/from the LP spooler. .TP \(bu Enable and disable printers and plotters from printing requests accepted by the LP spooler. .TP \(bu Accept and reject requests for printers, plotters, and print classes. .TP \(bu Modify the fence priority of printers and plotters. .TP \(bu Set the system default print destination. .TP \(bu Start and stop the LP scheduler. .RE .PP .B "HP Distributed Print Service (HPDPS)" .RS .TP 3 \(bu Add and remove physical printers (parallel, serial, or network interface and remote printers), logical printers, print queues, spoolers, and supervisors. .TP \(bu Enable and disable logical printers, print queues, and physical printers to accept print jobs. .TP \(bu Pause and resume print queues, physical printers, and print jobs. .TP \(bu Start and stop spoolers and supervisors .TP \(bu Modify attributes of physical printers, logical printers, print queues, spoolers, and supervisors. .TP \(bu Remove a single print job or all print jobs assigned to a physical printer, logical printer, print queue, spooler or supervisor. .RE .RE .PP .B "Process Management" .RS .TP 3 \(bu Kill, stop or continue processes. .TP \(bu Change the nice priority of processes. .TP \(bu View the current status of processes. .TP \(bu Schedule periodic tasks via cron. .TP \(bu View current periodic (cron) tasks. .TP \(bu Run performance monitors. .TP \(bu Display system properties such as: machine model and ID; number of installed processors, their version and speed; operating-system release version; swap statistics, real, physical, and virtual memory statistics; network connection information. .RE .ne 3 .PP .B "Remote Administration" .RS .TP 3 \(bu Configure remote systems for remote administration. .TP \(bu Execute SAM on systems configured for remote administration. .RE .PP .B "Routine Tasks" .RS .TP 3 \(bu Shut down the system. .TP \(bu View and remove large files. Specify size and time-since-accessed of large files to display or remove. .TP \(bu View and remove unowned files. Specify size and time-since-accessed of unowned files to display or remove. .TP \(bu View and remove core files. .TP \(bu View and trim ASCII or non-ASCII log files. Add or remove files from the list of files to monitor. Set recommended size for trimming. .RE .PP .B "User and Group Account Management" .RS .TP 3 \(bu Add, remove, view, and modify user accounts. .TP \(bu Remove or reassign ownership of files belonging to removed or modified user accounts. .TP \(bu Modify a user account's group membership. .TP \(bu Set up password aging for a user account. .TP \(bu Add, remove, view, and modify groups. .TP \(bu Customize adding and removing users by specifying steps to be performed before and/or after SAM does its processing for the task. The .CR "Task Customization" action items in SAM Users and Groups leads you through this capability. See "Customizing SAM Tasks" below for more information. .TP \(bu Deactivate and reactivate user accounts. .TP \(bu Manage trusted system security policies on a per-user basis. The policies that can be managed include: .RS .RS 2 .TP 3 \(bu Account lifetime .PD 0 .TP \(bu Maximum account inactivity period .TP \(bu Password generation policies .TP \(bu Null password usage and use of password restriction rules .TP \(bu Maximum password length .TP \(bu Password aging .TP \(bu Maximum unsuccessful login attempts .TP \(bu Generation of admin numbers for new or reactivated accounts .TP \(bu Single-user boot authorization .TP \(bu Authorized login times .PD .RE .RE .RE .SS Adding New Functionality to SAM You can easily add stand-alone commands, programs, and scripts to SAM. SAM is suspended while the executable program is running. When it finishes, the SAM interface is restored. You can also write your own help screen for each menu item you create. To add functionality to SAM, select the "Add Custom Menu Item" or "Add Custom Menu Group" action items from the SAM Areas menu. (Note that the new item is added to the hierarchy that is currently displayed, so you need to navigate to the desired hierarchy before adding the item.) .SS "Single-Point Administration of NFS Diskless Clusters" SAM provides some special capabilities for managing an NFS diskless cluster as a single entity. .PP For printers and file systems, you can use a feature of the "add" tasks to add a resource to all members of a cluster, making the printer or file system a "cluster-wide" resource. Not only can the resource be added to all systems in the cluster in a single task, but when a cluster-wide resource is selected and a task requested, that task can be performed automatically on all members of the cluster. .PP For users/groups and electronic mail, SAM provides the choice between shared data and private data when the first client is configured. Choosing shared data results in clients being configured in such a way that they and the cluster server share such things as .CR /etc/passwd , .CR /etc/group , and user mailboxes, and such that sendmail is configured on clients so that all email passes through the server. .PP Finally, for backups, all publicly-available file systems that belong to systems in the cluster can be backed up from the cluster server. .PP Online help in the various SAM areas contains more details about single-point administration of NFS diskless clusters (for example, the online help in the Printers/Plotters area provides more information about managing printers as cluster-wide resources and what it means to perform a task on a cluster-wide resource). .SS File System Protection When Removing Users When removing users or files from a system, there is always the unfortunate possibility that the wrong user may be removed or that files belonging to a user who is removed are deleted inadvertently during the removal process. For example, user .CR bin is the owner of (from the operating system's perspective) the majority of the executable commands on the system. Removing this user would obviously be disastrous. On the other hand, suppose user .CR joe owns all of the files comprising the test suite for a project. It may be appropriate to remove .CR joe , but the test suite should be left intact and assigned to a new owner. SAM provides two features to help protect against inadvertent removal of users or files when removing users: .RS .TP 3 \(bu When prompting for the name of a user to remove from the system, SAM checks the name given against a list of names specified in the file .CR /etc/sam/rmuser.excl . If the name matches one within the file, SAM does not remove the user. .TP \(bu When SAM removes a user, all files (or a subset thereof) for that user are also removed, unless the ownership is given to another user. Before removing a file belonging to the user, SAM checks to see if the file resides in a path that has been excluded from removal. SAM uses the file .CR /etc/sam/rmfiles.excl to determine which paths have been excluded from removal. So, for example, if the path .CR /users/joe/test is named in the file, SAM will not remove any files residing beneath that directory. SAM logs a list of all files it removes in the file .CR /var/tmp/sam_remove.log . .TP \(bu SAM does not remove or reassign any files if the user being removed has the same user ID as another user on the system. .RE .PP Files .CR /etc/sam/rmuser.excl and .CR /etc/sam/rmfiles.excl can be edited to contain users and directories that you want to exclude from removal by SAM. .SS Customizing SAM Tasks You can customize the following SAM tasks: .RS .TP 3 \(bu Add a New User Account to the System .TP \(bu Remove a User Account from the System .TP \(bu Add a Cluster Client .TP \(bu Remove a Cluster Client .RE .PP For each of these tasks, you can specify steps you want performed before and/or after SAM does its processing for the task. Before SAM performs one of the tasks, it checks to see if a pretask step (executable file) was defined. If so, SAM invokes the executable, passes it a set of parameters (see below), and waits for its completion. You can halt SAM's processing of a task by exiting from your executable with a nonzero value (for example if an error occurs during execution of your executable). .PP After SAM has finished processing, it checks for a posttask step, performing the same type of actions as for the pretask step. .PP The executable file must have these characteristics: .RS .TP 3 \(bu Must be owned by root. .TP \(bu Must be executable only by root, and if writable, only by root. .TP \(bu Must reside in a directory path where all the directories are writable only by owner. .TP \(bu The full path name of the executable file must be given in the SAM data entry form. .RE .PP The same parameters are passed from SAM to your program for both the pretask and posttask steps. Here are the parameters passed for each task: .RS .TP 3 \(bu .B "Add a New User Account to the System" .RS 5 .nf .PP .CI \-l \0login_name .CI \-v \0user_id .CI \-h \0home_directory .CI \-g \0group .CI \-s \0shell .CI \-p \0password .CI \-R \0real_name .CI \-L \0office_location .CI \-H \0home_phone .CI \-O \0office_phone .fi .RE .IP The file .CR /usr/sam/lib/ct_adduser.ex contains an example of how to process these parameters. .TP \(bu .B "Remove a User Account From the System" .IP There can be one of three possible parameters, depending on the option selected in the SAM data entry form. The parameter can be .I one of these three: .RS 5 .TP 30 .CI \-f \0user_name Option supplied when all of .IR user_name 's files are being removed. .TP .CI \-h \0user_name Option supplied when .IR user_name 's home directory and files below it are being removed. .TP .CI \-n \0new_owner\0user_name Option supplied when all of .IR user_name 's files are being assigned to .IR new_owner . .RE .IP The file .CR /usr/sam/lib/ct_rmuser.ex contains an example of how to process these parameters. .TP \(bu .B "Add a Cluster Client" .IP When adding multiple clients, the customized task is invoked once for each client. If any pretask command fails (returns nonzero), the corresponding client is not added. .IP The parameters are: .RS 5 .TP 30 .CI \-n \0client_nodename Name of the cluster client being added. .TP .CI \-i \0internet_address Unique network address for the cluster client, in the form .IC ddd . ddd . ddd .\c .IR ddd . .TP .CI \-s \0server Name of the server. .TP .CI \-h \0link_level_address 12-character hardware address associated with the LAN card in the cluster client. .RE .IP The file .CR /usr/sam/lib/ct_addnode.ex contains an example of how to process these parameters. The task customize command is run with standard output and standard error sent to the SAM log file. .TP \(bu .B "Remove a Cluster Client" .IP When removing multiple clients, the customized task is invoked once for each client. If any pretask command fails (returns nonzero), the corresponding client is not removed. The format of the parameter string for this task is: .RS 5 .TP 30 .CI \-n \0client_nodename Name of the cluster client being removed. .RE .IP File .CR /usr/sam/lib/ct_rmnode.ex contains an example of how to process these parameters. The task customize command is run with standard output and standard error sent to the SAM log file. .RE .SS "Restricted SAM" SAM can be configured to provide a subset of its functionality to certain users or groups of users. It can also be used to build a template file for assigning SAM access restrictions on multiple systems. This is done through the Restricted SAM Builder. System administrators access the Restricted SAM Builder by invoking SAM with the .CR \-r option (see "Options" above). In the Builder, system administrators may assign subsets of SAM functionality on a per-user or per-group basis. Once set up, the .CR \-f option (see "Options" above) can then be used by system administrators to verify that the appropriate SAM functional areas, and only those areas, are available to the specified user. .PP A nonroot user that has been given Restricted SAM privileges simply executes .CR /usr/sbin/sam and sees only those areas the user is privileged to access. For security reasons, the "List" and "Shell Escape" choices are not provided. (Note that some SAM functional areas require the user to be promoted to root in order to execute successfully. SAM does this automatically as needed.) .PP SAM provides a default set of SAM functional areas that the system administrator can assign to other users. Of course, system administrators are able to assign custom lists of SAM functional areas to users as necessary. .SS "SAM Logging" All actions taken by SAM are logged into the SAM log file .CR /var/sam/log/samlog . The log entries in this file can be viewed via the SAM utility .CR samlog_viewer (see .IR samlog_viewer (1M)). .CR samlog_viewer can filter the log file by user name, by time of log entry creation, and by level of detail. .PP The "Options" menu in the SAM Areas Menu enables you to start a log file viewer and to control certain logging options. These options include whether or not SAM should automatically start a log file viewer whenever SAM is executed, whether or not SAM should trim the log file automatically, and what maximum log file size should be enforced if automatic log file trimming is selected. .SS VT320 Terminal Support Because the VT320 terminal has predefined local functions for keys labeled as .BR F1 , .BR F2 , .BR F3 and .BR F4 , users should use following mapping when they desire to use function keys: .PP .RS .TP 20 .B "HP or Wyse60" .B "VT320 or HP 700/60 in VT320 mode" .TP .PD 0 .B F1 .B PF2 .IR (1) .TP .B F2 .B PF1 .IR (1) .TP .B F3 .B spacebar .TP .B F4 .B PF3 .IR (1) .TP .B F5 .BR F10 ", [EXIT], " F5 .IR (2) .TP .B F6 none .TP .B F7 .BR F18 , first unlabeled key to right of .B Pause/Break .IR (2) .TP .B F8 .BR F19 , second unlabeled key to right of .B Pause/Break .IR (2) .PD .RS 5 .TP .IR (1) See the "Configuration: HP 700/60 in DEC mode, or DEC terminals with PC-AT-type keyboard" subsection below. .TP .IR (2) When using PC-AT keyboard with HP 700/60 in VT320 mode. .RE .RE .PP Since DEC terminals do not support the softkey menu, that menu is not displayed on those terminals. .PP Many applications use .BR TAB for forward navigation (moving from one field to another) and .BR shift-TAB for backward navigation. Users having DEC terminals or using terminals in DEC emulation modes such as VT100 or VT320 may note that these terminals/emulators may produce the same character for .BR TAB and .BR shift-TAB . As such, it is impossible for an application to distinguish between the two and both of them are treated as if the .BR TAB key was pressed. This presents an inconvenience to users if they want to go backward. In most cases, they should complete rest of the input fields and get back to the desired field later. .SS VT100 Terminal Support VT100 does not allow the .BR F1 \(mi F8 function keys to be configured. Therefore, the following keyboard mappings apply to VT100 terminals: .RS .TP 20 .B "HP or Wyse60" .B "VT100 or HP 700/60 in VT100 mode" .TP .PD 0 .B F1 .B PF2 .IR (1) .TP .B F2 .B PF1 .IR (1) .TP .B F3 .B spacebar .TP .B F4 .BR PF3 ", " spacebar or .BR PF3 ", " = .IR (1) .TP .B F5 .B Return .TP .B F6 none .TP .B F7 none .TP .B F8 none .PD .RS 5 .TP .IR (1) See the "Configuration: HP 700/60 in DEC mode, or DEC terminals with PC-AT-type keyboard" subsection below. .RE .RE .PP See the comments on softkeys and .BR TAB keys in the "VT320 Terminal Support" subsection above. .SS "Configuration: HP 700/60 Terminal in DEC Mode, or DEC Terminal with PC-AT-Type Keyboard" .PP Customers using the following configuration may want to be aware of the following keyboard difference. .PP It may be possible for a user with the "HP 700/60 terminal in DEC mode, or DEC terminal with PC-AT-type keyboard" configuration to be told to press function key .B F1 through .B F4 to achieve some desired result. For an HP 700/60 terminal in DEC mode or DEC terminals, these functions keys may be mapped onto .BR PF1 \(mi PF4 keys. However, the PC-AT-type keyboard does not provide .BR PF1 \(mi PF4 keys, as does the DEC/ANSI keyboard. .PP .RS .TP 20 .B "Key" .B "Maps to .TP .B "Num Lock" .B "PF1" .TP .B "/" .B "PF2" .TP .B "*" .B "PF3" .TP .B "\(mi" .B "PF4" .RE The .BR "Num Lock" , .BR "/" , .BR "*" , and .BR "\(mi" keys are located on the keyboard, in a row above the number pad on the right side of the keyboard. Please note that although this keyboard is called a PC-AT-type keyboard, it is supplied by HP. A PC-AT-type keyboard can be recognized by location of ESC key at the left-top of the keyboard. .SS "Wyse60 Terminal Support" .PP On Wyse60, use the .B DEL key (located next to .BR Backspace ) to backspace. On an HP 700/60 with a PC-AT-type keyboard in Wyse60 mode, the .B DEL key is located in the bottom row on the number pad. .PP Wyse60 terminals provide a single line to display softkey labels unlike HP terminals which provide two lines. Sometimes this may result in truncated softkey labels. For example, the .CR "Help on Context" label for .B F1 may appear as .CR "Help on C" . Some standard labels for screen-oriented applications, such as SAM and .CR swinstall are as follows: .RS .TP 25 .B "The SAM label: .B "May appear on the Wyse60 as:" .TP .C "Help On Context" .C "Help On C" .TP .C "Select/Deselect" .C "Select/D" .TP .C "Menubar on/off" .C "Menubar" .RE .SH DEPENDENCIES SAM runs in an X Window environment as well as on the following kinds of terminals or terminal emulators: .RS .TP 3 \(bu HP-compatible terminal with programmable function keys and on-screen display of function key labels. .TP \(bu VT-100 and VT-320 .TP \(bu WY30 and WY60 .RE .PP Depending on what other applications are running concurrently with SAM, more swap space may be required. SAM requires the following amounts of internal memory: .RS .TP 10 .PD 0 8 MB If using terminal based version of SAM. .TP 16 MB If using Motif X Window version of SAM. .PD .RE .PP For more detailed information about how to use SAM on a terminal, see the .I "System Administration Tasks" manual. .SH AUTHOR .CR sam was developed by HP. .SH FILES .ifn .TP 25 .ift .TP 35 .CR /etc/sam/custom Directory where SAM stores user privileges. .TP .CR /etc/sam/rmfiles.excl File containing a list of files and directories that are excluded from removal by SAM. .TP .CR /etc/sam/rmuser.excl File containing a list of users that are excluded from removal by SAM. .TP .CR /usr/sam/bin Directory containing executable files, which can be used outside of any SAM session. .TP .CR /usr/sam/help/$LANG Directory containing SAM language specific online help files. .TP .CR /usr/sam/lbin Directory containing SAM executables, which are intended only for use by SAM and are not supported in any other context. .TP .CR /usr/sam/lib Directory for internal configuration files. .TP .CR /var/sam Directory for working space, including lock files (if a SAM session dies, it may leave behind a spurious lock file), preferences, logging, and temporary files. .TP .CR /var/sam/log/samlog File containing unformatted SAM logging messages. This file should not be modified by users. Use .CR samlog_viewer to view the contents of this file (see .IR samlog_viewer (1M)). .TP .CR /var/sam/log/samlog.old Previous SAM log file. This file is created by SAM when .CR /var/sam/log/samlog is larger than the user specified limit. Use .CR samlog_viewer with its .CR \-f option to view the contents of this file (see .IR samlog_viewer (1M)). .PD .SH SEE ALSO samlog_viewer(1M). .PP .I "System Administration Tasks" .br .I "Installing and Administering ARPA Services" .br .I "Installing and Administering LAN/9000" .br .I "Installing and Administering NFS Services" .br .I "Installing and Administering Network Services" .br .I "Installing and Administering X.25/9000" .br .I "How HP-UX Works: Concepts for the System Administrator" .\" .\" index@\f4sam\f1 \- system administration manager@@@\f3sam(1M)\f1 .\" index@\f1system administration manager@@@\f3sam(1M)\f1 .\" index@\f1menu-driven system administration manager@@@\f3sam(1M)\f1 .\" index@\f1administration manager, system, menu-driven@@@\f3sam(1M)\f1 .\" index@\f1manager, menu-driven system administration@@@\f3sam(1M)\f1 .\" .\" index@\f1terminals, VT320, VT100, Wyse60@@@\f3sam(1m)\f1 .\" index@\f1VT320 terminal@@@\f3sam(1m)\f1 .\" index@\f1VT100 terminal@@@\f3sam(1m)\f1 .\" index@\f1Wyse60 terminal@@@\f3sam(1m)\f1 .\" .\" toc@\f3sam(1M)\f1:\0\0\f4sam\f1@@@system administration manager .\" $Header: sar.1m,v 74.1 95/03/23 18:07:16 ssa Exp $ .TA s .TH sar 1M "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sar \- system activity reporter .SH SYNOPSIS .C sar .RC [ -ubdycwaqvmAMS ] .RC [ -o .IR file\| ] .I t .RI [ \|n\| ] .PP .C sar .RC [ -ubdycwaqvmAMS ] .RC [ -s .IR time\| ] .RC [ -e .IR time\| ] .RC [ -i .IR sec\| ] .RC [ -f .IR file\| ] .SH DESCRIPTION In the first form above, .C sar samples cumulative activity counters in the operating system at .I n intervals of .I t seconds. If the .C -o option is specified, it saves the samples in .I file in binary format. The default value of .I n is 1. In the second form, with no sampling interval specified, .C sar extracts data from a previously recorded .IR file , either the one specified by .C -f option or, by default, the standard system activity daily data file .CI /var/adm/sa/sa dd for the current day .IR dd . The starting and ending times of the report can be bounded via the .C -s and .C -e .I time arguments of the form .IR hh \|[\|: mm \|[\|: ss\| ]\|]. The .C -i option selects records at .IR sec -second intervals. Otherwise, all intervals found in the data file are reported. .PP In either case, subsets of data to be printed are specified by option: .RS .TP 6 .C -u Report .SM CPU utilization (the default); portion of time running in one of several modes. On a multi-processor system, if the .C -M option is used together with the .C -u option, per-\c .SM CPU utilization as well as the average .SM CPU utilization of all the processors are reported. If the .C -M option is not used, only the average .SM CPU utilization of all the processors is reported: .RS .RS .TP 15 .C cpu cpu number (only on a multi-processor system with the .C -M option); .TP .C %usr user mode; .TP .C %sys system mode; .TP .C %wio idle with some process waiting for .SM I/O (only block .SM I/O, raw .SM I/O, or .SM VM pageins/swapins indicated); .TP .C %idle otherwise idle. .RE .RE .TP .C -b Report buffer activity: .RS .RS .TP 15 .C bread/s Number of physical reads per second from the disk (or other block devices) to the buffer cache; .TP .C bwrit/s Number of physical writes per second from the buffer cache to the disk (or other block device); .TP .C lread/s Number of reads per second from buffer cache; .TP .C lwrit/s Number of writes per second to buffer cache; .TP .C %rcache Buffer cache hit ratio for read requests e.g., 1 \(mi bread/lread; .TP .C %wcache Buffer cache hit ratio for write requests e.g., 1 \(mi bwrit/lwrit; .TP .C pread/s Number of reads per second from character device using the .C physio() (raw .SM I/O\c ) mechanism; .TP .C pwrit/s Number of writes per second to character device using the .C physio() (i.e., raw .SM I/O\c ) mechanism; mechanism. .RE .RE .TP .C -d Report activity for each block device, e.g., disk or tape drive. One line is printed for each device that had activity during the last interval. If no devices were active, a blank line is printed. Each line contains the following data: .RS .RS .TP 15 .C device Logical name of the device and its corresponding instance. Devices are categorized into the following four device types: .RS .IP disk1 \(mi .SM HP-IB disks .SM (CS/80) .br disk2 \(mi .SM CIO HP-FL disks .SM (CS/80) .br disk3 \(mi .SM SCSI and .SM NIO FL disks .br sdisk \(mi .SM SCSI disks; .RE .TP .C %busy Portion of time device was busy servicing a request; .TP .C avque Average number of requests outstanding for the device; .TP .C r+w/s Number of data transfers per second (read and writes) from and to the device; .TP .C blks/s Number of bytes transferred (in 512-byte units) from and to the device; .TP .C avwait Average time (in milliseconds) that transfer requests waited idly on queue for the device; .TP .C avserv Average time (in milliseconds) to service each transfer request (includes seek, rotational latency, and data transfer times) for the device. .RE .RE .TP .C -y Report tty device activity: .RS .RS .TP 15 .C rawch/s Raw input characters per second; .TP .C canch/s Input characters per second processed by .CR canon() ; .TP .C outch/s Output characters per second; .TP .C rcvin/s Receive incoming character interrupts per second; .TP .C xmtin/s Transmit outgoing character interrupts per second; .TP .C mdmin/s Modem interrupt rate (not supported; always 0). .RE .RE .TP .C -c Report system calls: .RS .RS .TP 15 .C scall/s Number of system calls of all types per second; .TP .C sread/s Number of .C read() and/or .C readv() system calls per second; .TP .C swrit/s Number of .C write() and/or .C writev() system calls per second; .TP .C fork/s Number of .C fork() and/or .C vfork() system calls per second; .TP .C exec/s Number of .C exec() system calls per second; .TP .C rchar/s Number of characters transferred by read system calls block devices only) per second; .TP .C wchar/s Number of characters transferred by write system calls (block devices only) per second. .RE .RE .TP .C -w Report system swapping and switching activity: .RS .RS .TP 15 .C swpin/s Number of process swapins per second; .TP .C swpot/s Number of process swapouts per second; .TP .C bswin/s Number of 512-byte units transferred for swapins per second; .TP .C bswot/s Number of 512-byte units transferred for swapouts per second; .TP .C pswch/s Number of process context switches per second. .RE .RE .TP .C -a Report use of file access system routines: .RS .RS .TP 15 .C iget/s Number of file system .C iget() calls per second; .TP .C namei/s Number of file system .C lookuppn() (pathname translation) calls per second; .TP .C dirblk/s Number of file system blocks read per second doing directory lookup. .RE .RE .TP .C -q Report average queue length while occupied, and percent of time occupied. On a multi-processor machine, if the .C -M option is used together with the .C -q option, the per-\c .SM CPU run queue as well as the average run queue of all the processors are reported. If the .C -M option is not used, only the average run queue information of all the processors is reported: .RS .RS .TP 15 .C cpu cpu number (only on a multi-processor system and used with the .C -M option) .TP .C runq-sz Average length of the run queue(s) of processes (in memory and runnable); .TP .C %runocc The percentage of time the run queue(s) were occupied by processes (in memory and runnable); .TP .C swpq-sz Average length of the swap queue of runnable processes (processes swapped out but ready to run); .TP .C %swpocc The percentage of time the swap queue of runnable processes (processes swapped out but ready to run) was occupied. .RE .RE .TP .C -v Report status of text, process, inode and file tables: .RS .RS .TP 15 .C text-sz (Not Applicable); .TP .C proc-sz The current-size and maximum-size of the process table; .TP .C inod-sz The current-size and maximum-size of the inode table (inode cache); .TP .C file-sz The current-size and maximum-size of the system file table; .TP .C text-ov (Not Applicable); .TP .C proc-ov The number of times the process table overflowed (number of times the kernel could not find any available process table entries) between sample points; .TP .C inod-ov The number of times the inode table (inode cache) overflowed (number of times the kernel could not find any available inode table entries) between sample points; .TP .C file-ov The number of times the system file table overflowed (number of times the kernel could not find any available file table entries) between sample points. .RE .RE .TP .C -m Report message and semaphore activities: .RS .RS .TP 15 .C msg/s Number of System V .C msgrcv() calls per second; .TP .C sema/s Number of System V .C semop() calls per second; .TP .C select/s Number of System V .C select() calls per second. This value will only be reported if the "-S" option is also explicitly specified. .RE .RE .TP .C -A Report all data. Equivalent to .CR -udqbwcayvm . .TP .C -M Report the per-processor data on a multi-processor system when used with .C -q and/or .C -u options. If the .C -M option is not used on a multi-processor system, the output format of the .C -u and .C -q options is the same as the uni-processor output format and the data reported is the average value of all the processors. .RE .SH EXAMPLES Watch .SM CPU activity evolve for 5 seconds: .IP .C sar 1 5 .PP Watch .SM CPU activity evolve for 10 minutes and save data: .IP .C "sar -o temp 60 10" .PP Review disk and tape activity from that period later: .IP .C "sar -d -f temp" .PP Review cpu utilization on a multi-processor system later: .IP .C "sar -u -M -f temp" .SH WARNINGS Users of .C sar must not rely on the exact field widths and spacing of its output, as these will vary depending on the system, the release of HP-UX, and the data to be displayed. .SH FILES .TP 25 .CI /var/adm/sa/sa dd daily data file, where .I dd is two digits representing the day of the month. .SH SEE ALSO sa1(1M). .SH STANDARDS CONFORMANCE .CR sar ": SVID2, SVID3" .\" .\" index@\f4sar\f1 \- system activity reporter@@@\f3sar(1M)\f1 .\" index@system activity reporter@@@\f3sar(1M)\f1 .\" index@activity reporter, system@@@\f3sar(1M)\f1 .\" index@reporter, system activity@@@\f3sar(1M)\f1 .\" .\" toc@\f3sar(1M)\f1:\0\0\f4sar\f1@@@system activity reporter .\" $Header: savecore.1m,v 78.1 96/02/12 14:13:03 ssa Exp $ .TA s .TH savecore 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME savecore \- save a core dump of the operating system .SH SYNOPSIS .C /sbin/savecore .RC [ -cflrvxzZ ] .RC [ -D .IR dumpdevice ] .RC [ -O .IR offset ] .RC [ -m .IR minfree ] .RC [ -s .IR chunksize ] .RC [ -t .IR tapedevice ] .RC [ "-w 0"\(or\c .CR 1\c .RC \(or 2 ] .RI [ dirname ] .SS Obsolescent Options: .C savecore .RC [ -n ] .RC [ -d .IR dumpsystem ] .PP The .CR -i , .CR -u , .CR -k , .CR -F , .CR -s , and .CR -p options are obsolescent and will be ignored. .SH DESCRIPTION .C savecore saves a core dump of the system (assuming one was made when the system crashed) and writes a reboot message in the shutdown log file. .PP .I dirname is the name of the existing directory in which to store the core dump; the default is .CR /var/adm/crash . .PP .C savecore saves the core image and related files in the directory .IC dirname /core. n\f1. (The format of this directory is described in .IR savecore (4)). The trailing .I n in the directory name is a number that increases by one every time .C savecore is run with the same .IR dirname . This number is kept in the file .IC dirname /bounds\f1, which is created if it does not already exist. .PP By default, .C /stand/vmunix is used as the name of the kernel module saved by .CR savecore . If .C /stand/vmunix was not the running kernel at the time of the crash, the .C -d option should be used to specify the kernel. .PP When .C savecore writes out a core dump directory, it checks the space available on the file system containing .IR dirname . .C savecore will not use that portion of the file system space which is reserved for the superuser. Additional space on the file system can be reserved for other uses with .CR -m , or with the .IC dirname /minfree file (obsolescent). This option is useful for ensuring enough file system space for normal system activities after a panic. Note that the .C -m option is by default in kBytes, whereas the .IC dirname /minfree file value is assumed to be in 512-byte blocks. .PP If there is insufficient space in the file system for the entire core dump, .C savecore will save as much of the dump as will fit in the available space. (Priority is given to the index file, then to the kernel module files, starting with the earliest loaded, and then to the physical memory image starting at the lowest addresses and working up.) The dump will be considered saved, and .C savecore will not attempt to save it again, unless there was insufficient space for even a single chunk. (See the description of option .CR -r .) .PP .C savecore also writes a reboot message in the shutdown log file ( .CR /etc/shutdownlog ), if one exists. (If a shutdown log file does not exist, .C savecore does not create one.) If the system crashes as a result of a panic, .C savecore also records the panic string in the shutdown log. .PP By default, when the primary paging device is not used as one of the dump devices or when the core image on the primary paging device is saved, .C savecore runs in the background. This reduces system boot-up time by allowing the system to be run with only the primary paging device. .PP It is possible for dump devices to be used also as paging devices. If .C savecore determines that a dump device is already enabled for paging, and that paging activity has already taken place on that device, a warning message will indicate that the dump may be invalid. If a dump device has not already been enabled for paging, .C savecore prevents paging from being enabled to the device by creating the file .CR /etc/savecore.LCK . .C swapon does not enable the device for paging if the device is locked in .C /etc/savecore.LCK (see .IR swapon (1M) for more details). As .C savecore finishes saving the image from each dump device, it updates the .C /etc/savecore.LCK file and optionally executes .C swapon to enable paging on the device. .SS Options .TP 18 .C -c Mark the dump in the dump device as saved, without performing any other action. The .C -c option is useful for manually inhibiting dump actions called by .CR /sbin/init.d/savecore . .TP .C -f Run .C savecore in the foreground only. By default, .C savecore runs in the background when the primary paging device does not contain an unsaved portion of the core image. Turning this option on increases system boot-up time. .TP .C -l Logs the panic information to .C /etc/shutdownlog as described above, but does not actually save the dump. The dump is marked as saved so that future invocations of .C savecore do not create duplicate log entries. .TP .C -r Resaves a dump that a previous invocation of .C savecore has marked as already saved. This is useful if the first invocation saved only a partial dump, and enough space has been freed to try to save a complete dump. .TP .C -v Enables additional progress messages and diagnostics. .TP .C -x This option is used to extract a core dump and system from a specified tape device, from a tape written by a previous invocation of .C savecore (perhaps on a different system). A tape device must be specified with .C -t to use this option. .TP .C -z .C savecore will compress all physical memory image files and kernel module files in the dump directory. .TP .C -Z .C savecore will not compress any files in the dump directory. .IP If neither .C -z nor .C -Z is specified, .C savecore will determine whether or not to compress files based on the file sizes involved and the amount of available file system space. Compression may take place in the background after the image has been saved or in the foreground while saving the image, depending on available disk space. .TP .C -n (Obsolescent) Copies of the kernel module files are omitted from the dump directory. Only the physical memory image is saved. .TP .CI -D " dumpdevice" .I dumpdevice is the name of the device containing the header of the raw core image. The console messages from the time of the panic will identify the major and minor numbers of this device. This option, in combination with .CR -O , can be used to tell .C savecore where to find the dump in the rare instances that .C savecore doesn't know where to look. (See "Problems and Remedies," below.) .TP .CI -O " offset" .I offset is the offset in kBytes, relative to the beginning of the device specified with .C -D above, of the header of the raw core image. The console messages from the time of the panic will identify this offset. This option, in combination with .CR -D , can be used to tell .C savecore where to find the dump in the rare instances that .C savecore doesn't know where to look. (See "Problems and Remedies," below.) .TP .CI -m " minfree" .I minfree is the amount of free space (in kBytes) that must remain free for ordinary user files after .C savecore completes, in addition to space reserved for the superuser. If necessary, only part of the dump will be saved to achieve this requirement. .I minfree may be specified in bytes (b), kilobytes (k), megabytes (m), or gigabytes (g). The default .I minfree value is zero, and the default unit is kilobytes. This option will override the value in the .IC dirname /minfree file, if it exists. .TP .CI -s " chunksize" .I chunksize is the size (default kBytes) of a single physical memory image file before compression (see .IR savecore (4)). The kByte value must be a multiple of page size (divisible by 4) and between 64 and 1048576. .I chunksize may be specified in units of bytes (b), kilobytes (k), megabytes (m), or gigabytes (g). Larger numbers increase compression efficiency at the expense of both .C savecore time and debugging time. If .C -s is not specified, a default is chosen based on the physical memory size and the amount of available file system space. .TP .CI -t " tapedevice" This option is used to identify a tape device. If .C -t is specified without .CR -x , the core dump will be written to .I tapedevice . If this option is specified with .CR -x , the core dump will be read from the .I tapedevice and written to .I dirname. .TP .CI -w " n" Defines the interaction between .C savecore and .CR swapon . .I n can be one of the following values: .RS .RS .TP .C 0 Do not run .C swapon from .CR savecore . .TP .C 1 (default) Call .C swapon each time savecore finishes saving the image from each dump device. This option provides the most efficient use of paging space. .TP .C 2 Only call .C swapon when .C savecore finishes saving the image file from .I all dump devices. If this option is used, no additional paging space other than the primary paging space is available until the complete core dump image is saved. This option provides a second chance to retrieve the core image if .C savecore fails on first attempt. .RE .RE .TP .CI -d " dumpsystem" (Obsolescent) .I dumpsystem is the name of a file containing the image of the system that produced the core dump (that is, the system running when the crash occurred). If this option is not specified, .C savecore assumes the image is .C /stand/vmunix. This option may also be used when the system being booted to save the core dump differs from the system that crashed. .SH RETURN VALUE Upon exit, .C savecore returns the following values: .RS .TP 5 .PD 0 .B 0 A core dump was found and saved. .TP .B 1 A core dump could not be saved due to an error. .TP .B 2 No core dump was found to save. .TP .B 3 A partial core dump was saved, but there was insufficient space to save the complete dump. .PD .RE .SH PROBLEMS AND REMEDIES .SS No Dump Was Saved .TP 15 .B Cause: The system may have shut down successfully. .TP .B Remedy: No dump is expected. Core dumps are only created for abnormal shutdowns. .TP .B Cause: .C savecore may not have been run. .TP .B Remedy: .C savecore must be enabled in the .C /sbin/rc.config.d/savecore configuration script, or run manually. .TP .B Cause: There may not be enough space to save a dump. .TP .B Remedies: See below under "Parts of the Dump Are Missing." .TP .B Cause: The system may not have dumped successfully. .TP .B Remedy: Examine the console messages from the time when the system went down. Error messages there should point to the problem. .TP .B Cause: .C savecore may not know where to look for the dump. (If not, it will say so.) .TP .B Remedy: Examine the console messages from the time when the system went down to determine where the dump header is stored. Rerun .C savecore using the .C -D and .C -O options to tell it where the dump header is located. .TP .B Cause: System paging activity may have overwritten the dump. (A warning will be displayed indicating that paging activities have modified the dump device.) .TP .B Remedy: The dump cannot be saved. To avoid repetition of the problem, use a device other than your primary paging partition for dumps, and/or run .C savecore early in the system boot process (as is done by the .C /sbin/init.d/savecore startup script) to save the dump before much paging activity can occur. .TP .B Cause: The device numbers encoded in the dump header may not identify the same devices as they did when the system dumped. This can happen if the system was booted from a different boot device in order to run .CR savecore . Error messages stating that no device file could be found corresponding to a particular device number are a likely symptom of this problem. .TP .B Remedy: .C savecore must be run from a boot device that uses the same I/O configuration as the system that dumped. .SS Parts of the Dump Are Missing .TP 15 .B Cause: Insufficient space to save a complete core dump. .TP .B Remedies: Try one or more of the following steps to relieve the space constraints. Remember to use .C -r to override the fact that the dump has already been saved. .IP Free up space on the file system. .IP Reduce the .I minfree value specified with .C -m or the .IC dirname /minfree file, if applicable. .IP Use a different file system. .IP Enable compression. .IP Increase the chunk size, to improve compression efficiency. .IP Save the core dump to tape, and restore it on a system with more disk space. .SS Saving a Dump Takes Too Long .TP 15 .B Cause: Time is being taken to compress files while saving core. .TP .B Remedies: Disable compression, or free up disk space so that compression can occur in the background after the dump has been saved. .TP .B Cause: .C savecore is running in the foreground to avoid contention for paging space. .TP .B Remedies: Do not specify .CR -f . Use different devices for paging and dumps. .TP .B Cause: Slow disk accesses. .TP .B Remedy: Use a dump device that is fast and tuned for very large data transfers. .SH WARNINGS .C savecore relies on the expectation that device numbers have the same meaning (point to the same devices) at the time the system dumps and at the time the dump is saved. If, after a crash, the system was booted from a different boot device in order to run .CR savecore , it is possible that this expectation will not be met. If so, .C savecore may save an incomplete or incorrect dump or may fail to save a dump at all. Such cases cannot be reliably detected, so there may be no warning or error message. .SH AUTHOR .C savecore was developed by HP and the University of California, Berkeley. .SH FILES .PD 0 .TP 40 .C /etc/shutdownlog shutdown log .TP .C /etc/rc.config.d/savecore savecore startup configuration file .TP .C /sbin/init.d/savecore savecore startup file .TP .IC dirname /bounds crash dump number .TP .IC dirname /minfree (Obsolescent) minimum free space required after .CR savecore finishes .TP .C /stand/vmunix default kernel image saved by savecore .PD .SH SEE ALSO adb(1), savecore(4), swapon(1M). .\" .\" index@\f4savecore\f1 \- preserve core dump from system crash if it exists@@@\f3savecore(1M)\f1 .\" index@\f1crash, preserve core dump from if it exists@@@\f3savecore(1M)\f1 .\" index@\f1system crash, preserve core dump from if it exists@@@\f3savecore(1M)\f1 .\" index@\f1core dump from system crash, preserve if it exists@@@\f3savecore(1M)\f1 .\" index@\f1dump, core from system crash, preserve if it exists@@@\f3savecore(1M)\f1 .\" index@\f1save core dump of operating system if it exists following system crash@@@\f3savecore(1M)\f1 .\" .\" toc@\f3savecore(1M)\f1:\0\0\f4savecore\f1@@@save a core dump of the operating system .\" .\"@(#) $Header: scn.1m,v 1.2 95/12/15 11:35:24 hmgr Exp $ .\"========================================================= .\" (c) 1992, 1993 Hewlett-Packard Company. All Rights Reserved. .\" Author: Hewlett-Packard DMD .\"========================================================= .\" .TA s .TH scn 1M .SH NAME scn \- scan an .SM HP SCSI disk array .SM LUN for parity consistency .SH SYNOPSIS .HP .C scn .C -i .I number_of_initiators .I device_file .SH DESCRIPTION .C scn scans the disks of the .SM LUN in an .SM HP SCSI disk array identified by the character device file .IR device_file . The parity information for any block reporting inconsistent parity is corrected by an immediate call to .CR rpr . .SH RETURN VALUE .C scn returns the following values: .RS 5 .TP .B " 0" Successful completion. .PD 0 .TP .B -1 Command failed (an error occurred). .PD .PP .RE .SH DIAGNOSTICS AND ERRORS Errors can originate from problems with: .RS .TP 3 \(bu .C scn .TP \(bu .SM SCSI (device level) communications .TP \(bu system calls .RE .PP .SS Error messages generated by scn: .TP .C "usage: scn -i " .C scn encountered an error in command syntax. Enter the command again with all required arguments, in the order shown. .TP .C "scn: LUN # too big" The .SM LUN number, derived from the device file name, is out of range. .TP .C "scn: Not a raw file" Utilities must be able to open the device file for raw access. That is, you must specify a character device file rather than a block device file. .TP .C "scn: LUN does not exist" The addressed .SM LUN is not configured, and is not known to the array controller. .TP .C "scn: Not an HP SCSI disk array" The device being addressed is not an .SM HP SCSI disk array. .PP .SS SCSI (device level) communication errors: Sense data associated with the failed operation is printed. .PP .SS Error messages generated by system calls: .C scn uses the following system calls: .IP .CR malloc() , .CR free() , .CR stat() , .CR open() , .CR close() , .CR fopen() , .CR fclose() , .CR read() , .CR write() , and .CR ioctl() . .PP Documentation for these .SM HP-UX system calls contains information about the specific error conditions associated with each call. .C scn does not alter the value of .CR errno . The interpretation of .C errno for printing purposes is performed by the system utility .CR strerror() . .SH EXAMPLES .PP To scan the .SM LUN at .C /dev/rdsk/c2t0d0 on a Series 800 computer with two hosts (initiators) attached: .IP .C "scn -i 2 /dev/rdsk/c2t0d0" .SH DEPENDENCIES The HP C2425 and HP C2427 disk arrays are only supported on Series 700 systems running HP-UX version 9.0X. .PP The HP C2430 disk array is supported on Series 700 and 800 systems running HP-UX versions 9.0X and 10.0X. .SH AUTHOR .PP .C scn was developed by .SM HP. .\" .\" index@\f4scn\f1 \- scan \s-1HP SCSI\s+1 disk array \s-1LUN\s+1s for parity consistency@@@\f3scn(1M)\f1 .\" index@disk array, scan \s-1LUN\s+1s for parity consistency@@@\f3scn(1M)\f1 .\" index@parity information, scan for consistency@@@\f3scn(1M)\f1 .\" .\" toc@\f3scn(1M)\f1:\0\0\f4scn\f1@@@scan \s-1HP SCSI\s+1 disk array \s-1LUN\s+1s for parity consistency .\" .\" fileset_database@scn.1m SYS-ADMIN-MAN ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "scout" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Lscout\*O command" .iX "-[" "\*Lscout\*O command" "initializing" .SH NAME .PP \*Lscout\*O \- Initializes the \*Lscout\*O program .SH "SYNOPSIS" .sS .PP \*Lscout -server \*Vmachine\*O... [\*L-basename \*Vcommon_prefix\*O] [\*L-host\*O] [\*L-frequency \*Vseconds\*O] .nL [\*L-attention \*Vstat/threshold_pair\*O...] [\*L-debug \*Vfilename\*O] [\*L-help\*O] .sE .SH "OPTIONS" .VL .zA "defect,12569,R1.1,Correct -server option of scout command" .LI "\*L-server \*Vmachine\*O" Specifies each File Server machine whose File Exporter is to be monitored. Use one of the following to indicate each File Server machine: .ML .LI The machine's DCE pathname (for example, \*L/.../abc.com/hosts/fs1\*O). If you use the \*L\-basename\*O option to specify a pathname prefix common to all machines to be monitored, you need to provide only the unique suffix of each machine name; you can omit the common DCE pathname prefix. .LI The machine's hostname (for example, \*Lfs1.abc.com\*O or \*Lfs1\*O). .LI The machine's IP address (for example, \*L11.22.33.44\*O). .LE .LI "\*L-basename \*Vcommon_prefix\*O" Specifies the DCE pathname prefix (for example, \*L/.../abc.com/hosts\*O) common to all File Server machines specified with the \*L\-server\*O option. Do not include the \*L/\*O (slash) that separates the prefix from the unique part of each machine name; it is included automatically with the \*L\-basename\*O option. The basename, if specified, is displayed in the banner line. .P Use this option only if you are specifying the DCE pathname of each File Server machine to be monitored. Omit this option if you are specifying the hostnames or IP addresses of one or more machines. .zZ "defect,12569,R1.1,Correct -server option of scout command" .LI "\*L-host\*O" Displays the name of the machine running the \*Lscout\*O program in the banner line. This is useful if you are logged into the machine remotely. By default, \*Lscout\*O does not display this name. .LI "\*L-frequency \*Vseconds\*O" Indicates how often the \*Lscout\*O program is to probe the File Exporters. Specify a positive integer as a value in seconds; the default is 60 seconds. .LI "\*L-attention \*Vstat/threshold_pair\*O" Specifies a list of attention settings (statistic and threshold value pairs). The \*Lscout\*O program highlights any value for a statistic that exceeds its specified threshold; the highlighting is removed when the value goes below the threshold. The pairs can appear in any order. Legal statistic/threshold pairs are .VL .zA "defect,10825,R1.1,Correct scout information" .LI "\*Lconn\*O \*Vconnections\*O" The maximum number of connections that principals can have open to the File Exporter before the value is highlighted. Enter a threshold for this statistic in the form of a positive integer. .LI "\*Lfetch\*O \*Vnumber_of_fetches\*O" The maximum number of fetches (requests to send data) the File Exporter can service before the value is highlighted. Enter a threshold for this statistic in the form of a positive integer. The highlighting is removed when the File Exporter is restarted, at which time the value returns to 0 (zero). .LI "\*Lstore\*O \*Vnumber_of_stores\*O" The maximum number of stores (requests to store data) the File Exporter can accept before the value is highlighted. Enter a threshold for this statistic in the form of a positive integer. The highlighting is removed when the File Exporter is restarted, at which time the value returns to 0 (zero). .zZ "defect,10825,R1.1,Correct scout information" .LI "\*Lws\*O \*Vactive_client_machines\*O" The maximum number of active client machines the File Exporter can serve before the value is highlighted. \*EActive\*O indicates those machines that communicated with the File Exporter in the past 15 minutes. Enter a threshold for this statistic in the form of a positive integer. .LI "\*Ldisk\*O \*Vpercent_full\*L%\*O" The maximum percentage of an aggregate that can contain data before the value is highlighted. This threshold is applied to all exported aggregates and partitions on a File Server machine being monitored. Legal thresholds are the integers between 0 (zero) and 99; the default is 95%. \*EYou must enter the % (percent sign) with this threshold.\*O If the % (percent sign) is absent, \*Lscout\*O interprets the number as a number of kilobyte blocks.\*O Use this threshold or use \*Ldisk\*O \*Vminimum_blocks_free\*O. .LI "\*Ldisk\*O \*Vminimum_blocks_free\*O" The minimum number of kilobyte blocks that must be available on an aggregate before the value is highlighted. This threshold is applied to all exported aggregates and partitions on a File Server machine being monitored. Enter a threshold for this statistic in the form of a positive integer. Use this threshold or use \*Ldisk \*Vpercent_full\*L%\*O. .LE .LI "\*L-debug \*Vfilename\*O" Enables debugging output and directs it to the specified \*Vfilename\*O. Provide a complete pathname for \*Vfilename\*O; the current working directory is used by default. If this option is omitted, no debugging output is written. .LI "\*L-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .PP The \*Lhelp\*O and \*Lapropos\*O commands available with all command suites are also available with the \*Lscout\*O command. See the \*Lbos help\*O and \*Lbos apropos\*O reference pages for examples of these commands. .LE .SH "DESCRIPTION" .iX "\*Lscout\*O command" "display environment" .PP The \*Lscout\*O command displays statistics gathered from the File Exporter running in the kernel on each File Server machine specified with the \*L\-server\*O option. Usage statistics are also displayed about exported aggregates and partitions on the File Server machine being monitored. The \*Lscout\*O program can be run on any DFS client or server machine. The binary file for the program resides in \*Vdceshared\*L/bin/scout\*O. .PP To change attention settings (statistic and threshold pairs), you must stop and restart the \*Lscout\*O program. In addition, \*Lscout\*O does not store the settings from previous executions; you must specify the desired settings each time you start the program. .PP Both terminals and windowing systems that emulate terminals can display \*Lscout\*O statistics. The \*Lscout\*O display uses reverse video and cursor addressing; therefore, the display environment must support these features. The issuer must set the \*LTERM\*O environment variable to the correct terminal type or to one with similar characteristics. .PP To stop the \*Lscout\*O program, enter the interrupt command (\*L\*O or its equivalent) for your operating system in the \*Lscout\*O window. .PP .iX "\*Lscout\*O command" "monitoring screen" The \*Lscout\*O program can display statistics in either a dedicated window or on a plain screen if a windowing environment is unavailable. The \*Lscout\*O screen has three main parts: the Banner Line, the Statistics Display Region, and the Message/Probe Line. .PP The Banner Line at the top of the window or screen displays the word \*CScout\*O, indicating the program is running. The name of the machine executing \*Lscout\*O is displayed if the \*L\-host\*O option is specified, and the basename of the File Server machines being monitored is displayed if the \*L\-basename\*O option is specified. .PP The Statistics Display Region displays the statistics \*Lscout\*O has gathered for each File Exporter. The region is divided into six columns, one column for each of the five statistic and threshold pairs used with the \*L-attention\*O option, and one column for the name of each File Server machine being monitored. In addition to highlighting any value that exceeds its specified attention threshold, \*Lscout\*O highlights the name of any File Server machine whose File Exporter fails to respond to \*Lscout\*O's probes. The name remains highlighted until the machine resumes responding to \*Lscout\*O's probes. .PP The Message/Probe Line at the bottom of the window or screen indicates how many times \*Lscout\*O has probed the File Exporters for statistics. Use the \*L-frequency\*O option to specify how frequently \*Lscout\*O is to probe the File Exporters. .zA "defect,5933,R1.0.2,Reinstate priv. required sections" .SS "Privilege Required" .PP No privileges are required. .zZ "defect,5933,R1.0.2,Reinstate priv. required sections" .SH "EXAMPLES" .PP The following \*Lscout\*O command causes the program to monitor the File Exporters on File Server machines \*Lfs1\*O and \*Lfs2\*O in the cell \*Labc.com\*O. The \*Lscout\*O program probes the File Exporters every 30 seconds and writes debugging information to the file named \*Lscout.one\*O in the current working directory. .iS \*C$\*O \*Lscout -server fs1 fs2 -basename /.../abc.com/hosts -frequency 30 -debug scout.one\*O .iE .PP The following command causes \*Lscout\*O to monitor the same two machines. The \*Lscout\*O program highlights an entry in the \*CFetch\*O column if the File Exporter services 20,000 or more fetches, and it highlights an entry in the \*CStore\*O column if the File Exporter accepts 10,000 or more stores. .iS \*C$\*O \*Lscout -server fs1 fs2 -b /.../abc.com/hosts -attention fetch 16 store 8\*O .iE .iX "-]" "\*Lscout\*O command" .iX "-]" "\*Lscout\*O command" "initializing" .\" $Header: scsi_log.1m,v 74.1 95/05/10 21:57:51 ssa Exp $ .TA s .TH scsi_log 1M "" "Series 700 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scsi_log \- control and dump SCSI event log for sdisk, schgr, sflop, stape device drivers .SH SYNOPSIS .C scsi_log .RC [ -V ] .br .C scsi_log .RC [ -h .IR hpux_file ] .RC [ -c .IR core_file ] .RC [ -f .IR command_file ] \0... .RI [ command ] \0... .br .C scsi_log .RC [ -s .IR save_file ] .RC [ -f .IR command_file ] \0... .RI [ command ] \0... .br .C scsi_log .RC [ -h .IR hpux_file ] .RC [ -i ] .RC [ -f .IR command_file ] \0... .RI [ command ] \0... .SH DESCRIPTION .C scsi_log is the interface for control and decoding of the system's SCSI event log. Information is logged at specific predetermined points throughout the SCSI I/O subsystem. SCSI event log information is most useful to the person who creates the log points; however, the information may also be useful for analysis of device-related issues. .PP .CR scsi_log can be used to analyze the state of the SCSI I/O subsystem after a system crashes, using the ``core'' file created by use of .IR savecore(1M) . Specify the resulting .C /stand/vmunix and .C vm-core files using the .C -h and .C -c flag arguments. .PP .CR scsi_log can be used on a running system to gain access to the current state of the SCSI I/O subsystem. When used in this way, .C scsi_log provides a logic-analyzer-like interface useful for limiting the events to be logged and stopping event logging when some trigger condition is met. .C scsi_log operates in this manner by default. .PP .C Scsi_log can be used on a kernel executable file to examine or modify the initial operation of event logging in the SCSI I/O subsystem. This type of operation is most useful for analysis of system reboot via the SCSI I/O subsystem. .SS Options and Arguments .TP 15 .C -V Cause the .C scsi_log version to be printed. Because .C scsi_log works very closely with the system kernel and contains very detailed information about the SCSI I/O subsystem, the .CR scsi_log version and system version (as shown by .IR uname (1)) must match. Suspect mismatched system and .C scsi_log versions whenever .C scsi_log operates incorrectly or fails to decode log information. .TP .C -c Specify the .CR core file to be analyzed. By default, .C scsi_log accesses the SCSI log of the currently running system using .CR /dev/kmem . When accessing the SCSI event log contained in a .CR core file, only status and log decoding commands may be used. .TP .CI -h hpux_file Specify the appropriate HP-UX kernel file. By default, .C scsi_log obtains indexing (symbol table) information from the .CR /stand/vmunix file. .TP .CI -s save_file Specify that log data should be taken from a .I save_file instead of a .C core file. The .I save_file should be the result of a .C save or .C running_save command executed with the same .C scsi_log version. .TP .C -i Examine or modify the initial operating parameters in the .C /stand/vmunix file. Changes to .CR /stand/vmunix take effect when the system is next rebooted. This application of .C scsi_log is considerably slower than others; however, because .CR /stand/vmunix file modifications require a system reboot to take effect, the additional time is insignificant. .TP .CI -f command_file Specify a .I scsi_log command file. This is useful for complex command sequences, which might require unmanageable .I scsi_log argument lines. Multiple .C -f options can be used to execute a series of command files. .SS Commands .PP The following commands may be used to with .C -f to control the operation of .CR scsi_log : .TP 15 .C # Begin a comment, which is terminated by the end of the source line. Because end-of-line is somewhat ambiguous in the context of command-line arguments, comments are only permitted in command files. .TP .C status Decode and print the current event log status. The printed information includes a variety of information including the log state, and current limit and trigger conditions. .TP .C dump Decode and print the current contents of the SCSI event log. The dump format controls which log fields are printed and their order, and can be specified using the .C format command. .TP .C running_dump Continuously decode and print the contents of the SCSI event log by reading and rereading system memory. If the event log rate exceeds the event dump rate, events might be lost, a fact that will be noted in the dump. A .I running_dump operation continues until logging stops. This happens when a log run is completed (that is, the trigger condition has been met and sufficient events have been post-stored). If the trigger condition is not met or triggering is not enabled, this command will never terminate. .TP .CI "format =" format_value Print SCSI event log lines using the fields in the field indicated by .IR format_value . A default .CR dump format is used if an explicit .CR dump format is not provided. The default .CR dump format can be set using the .CR SCSI_LOG_FORMAT environment variable. A .I format_value is made up of the following letters: .RS .RS .TP 5 .PD 0 .C A Absolute event time based on the trigger event or the first dumped event in an easily readable form. .TP .C C Comment associated with the log point. Log point comments are optional and many log points do not have comments associated with them. .TP .C D Device number in hexadecimal. .TP .C E Absolute event number based on the first logged event. .TP .C F The name of the source file containing the log point. .TP .C L The line number in the source file of the log point. .TP .C M Decoded meaning of parameter data value. .TP .C N Relative event number based on the trigger event or the first dumped event. .TP .C P Parameter name. .TP .C Q Relative event time in a consistent, high-precision, numeric form. .TP .C R The name of the subroutine containing the log point. .TP .C T Relative event time in an easily readable form. .TP .C V Parameter value in decimal form. .TP .C X Parameter value in hexadecimal form. .TP .C Y Absolute event time based on the trigger event or the first dumped event in a consistent, high-precision, numeric form. .TP .C Z The character .C @ to mark the trigger event (otherwise blank). .PD .RE .RE .TP .CI "dump_limit =" condition Cause only events meeting the indicated .I condition to be printed by a .C dump or .C running_dump command. The .I condition must be specified as .CR NONE , .CR ANY , or as an .I event_specification indicated later in this manpage. .TP .C dump_unlimit Disable the current dump limit condition. This causes all logged events to be printed by a .C dump or .C running_dump command. .TP .CI "save =" save_file Record the current contents of the SCSI event log in .IR save_file . The contents of this file may be latter decoded using the .C scsi_log .C -s option. .TP .C running_save Continuously record the contents of the SCSI event log in .IR file_name by reading and rereading system memory. If the event log rate exceeds the event dump rate, events may be lost. If events are lost, that fact will be noted in the .IR save_file . A .C running_save command continues until logging is stopped. This happens when a log run is completed (that is, when the trigger condition has been met and sufficient events have been post-stored). If the trigger condition is not met or triggering is not enabled, this command will never terminate. Note that a .I running_save command can generate substantial quantities of data (the .I save_file can grow very quickly). .TP .C run Clear the event log and enable event logging. This command starts or restarts logging using the current limit and trigger conditions. .TP .C stop Disable event logging. This command does not clear the current limit or trigger conditions. .TP .C reset Restore SCSI event log to standard system boot operation. Use this command when .C scsi_log will not be used for an extended period. It will cause both the .C core file and the .CR /stand/vmunix file to be changed. .TP .C on Clear the event log and enable SCSI event logging. This command starts or restarts logging with no limit or trigger conditions. .TP .C off Disable SCSI event logging. Use this command to shutdown SCSI event logging. .TP .CI "limit =" condition Log only events meeting the indicated .IR condition . The .I condition must be specified as .CR NONE , .CR ANY , or as an .I event_specification indicated later in this manpage. .TP .C unlimit Disable the current limit condition. This causes all events to be logged. .TP .C limit_points Print the SCSI log points whose log events might meet the current limit condition. .TP .CI "trigger =" condition Disable SCSI event logging when the indicated .I condition is met and all of the post-store events have been logged. The .I condition must be specified as .CR NONE , .CR ANY , or as an .I event_specification indicated later in this manpage. .TP .C untrigger Disable the current trigger condition. This command does not clear the current trigger condition. .TP .C trigger_points Print the SCSI log points whose log events might meet the current trigger condition. .TP .C wait_for_trigger Wait until logging is stopped. This happens when a log run is completed (that is, the trigger condition has been met and sufficient events have been post-stored). If the trigger condition is not met or triggering is not enabled this command will never terminate. .TP .C center_store Stop logging events after the trigger condition is met (post-store) such that the trigger event ends up in the center of the SCSI event log. .TP .CI "pre_store [ =" number_of_events ] Stop logging events after the trigger condition is met and the indicated .I number_of_events from before the trigger event (pre-store events) remain in the SCSI event log. If the number of events to pre-store is not specified, event logging will stop as soon as the trigger condition is met. This causes the entire log to be used to hold events which occurred before the trigger event. .TP .CI "post_store [ =" number_of_events ] Stop logging events after the trigger condition is met and the indicated .I number_of_events after the trigger event (pre-store events) have been logged. Note that .I number_of_events may be larger than the total size of the SCSI event log. Such a .I number_of_events will cause the trigger event to be pushed out of the log. If the number of events to post-store is not specified, event logging will stop when the entire log is filled with events which occurred after the trigger event. .TP .CI "clock =" clock_mode Clock SCSI events to be logged as specified by .IR clock_mode . A high-precision clock is best used for events that occur over short intervals. A high-accuracy clock is best used for events that occur over long intervals. .I Clock_mode must be one of the following values: .RS .RS .TP 12 .PD 0 .C normal Select between clocks to achieve a balance of precision and accuracy. .TP .C precise Favor the high precision clock when possible. This .I clock_mode should be used to obtain maximally precise timing between successive events. .TP .C accurate Favor the high accuracy clock when possible. This .I clock_mode should be used to obtain maximally accurate timing between events which are widely separated in time and event number. .PD .RE .RE .TP .CI "log_size =" number_of_events Change the SCSI event log size to the indicated .IR number_of_events . This command changes the length of the SCSI log, as specified in the .CR /stand/vmunix file. A system reboot is required to cause the this change to take effect. .TP .C trace Decode and print the current SCSI command trace condition. SCSI command tracing causes data to be stored in the kernel .CR /usr/sbin/dmesg buffer. The .IR dmesg (1M) command can be used to print this stored data. Note that SCSI command tracing is independent from SCSI event logging. .TP .CI "trace_on =" trace_specification Trace SCSI commands and command information meeting the specified .IR trace_specification . Trace information may be accessed via .IR dmesg (1M). The .I trace_specification must be a list of relational expressions surrounded by parenthesis and separated by the logical operator .C && (AND). The following relational terms may appear in an .IR event_specification : .RS .RS .TP 12 .PD 0 .CI "device [ &" dev_mask "] ==" dev_value The device associated with the SCSI command must equal .I dev_value after being bitwise ANDed with .IC dev_mask . If no .I dev_mask is specified, the device associated with the SCSI command must exactly match .IC dev_value . .TP .CI "major ==" dev_value The device associated with the SCSI command must have the major number indicated by .IR dev_value . .TP .CI "dev ==" dev_value The device associated with the SCSI command must have the minor number indicated by .IR dev_value . .TP .CI "lun ==" dev_value The device associated with the SCSI command must have the SCSI bus, target and LUN indicated by .IR dev_value . .TP .CI "tgt ==" dev_value The device associated with the SCSI command must have the SCSI bus and target indicated by .IR dev_value . .TP .CI "bus ==" dev_value The device associated with the SCSI command must have the SCSI bus indicated by .IR dev_value . .TP .CI "dmesg_lines ==" dmesg_lines_value The trace information contained in the .IR dmesg (1M) buffer lines indicated by .I dmesg_lines_value should be recorded. .PD .RE .RE .TP .C trace_off Discontinue tracing additional SCSI commands. Normally the SCSI I/O subsystem records only information associated with commands which unexpectedly fail. The .C trace_off command restores this system default operation. .RE .SS Event Specifications .PP An .I event_specification consists of a list of relational expressions surrounded by parenthesis and separated by the logical operators .C && (AND) and .C || (OR). Since the SCSI tracing uses a fixed AND-OR (SUM of products) .I event_specification evaluation scheme, there is no need (nor support) for additional parenthesis imbeded within an .IR event_specification . The following relational terms may appear in an .IR event_specification : .TP 15 .CI "device [ &" dev_mask "] ==" dev_value The device associated with the event must equal .I dev_value after being bitwise ANDed with .IC dev_mask . If no .I dev_mask is specified, the device associated with the event must exactly match .IC dev_value . .TP .CI "major ==" dev_value The device associated with the event must have the major number indicated by .IR dev_value . .TP .CI "dev ==" dev_value The device associated with the event must have the minor number indicated by .IR dev_value . .TP .CI "lun ==" dev_value The device associated with the event must have the SCSI bus, target and LUN indicated by .IR dev_value . .TP .CI "tgt ==" dev_value The device associated with the event must have the SCSI bus and target indicated by .IR dev_value . .TP .CI "bus ==" dev_value The device associated with the event must have the SCSI bus indicated by .IR dev_value . .TP .CI "file ==" file_name The log point generating the event must be in the SCSI I/O subsystem source file indicated by .IC file_name . This term also establishes the context for use of symbolic literals in successive terms separated by .C && operators. .TP .CI "routine ==" routine_name The log point generating the event must be in the SCSI I/O subsystem source subroutine indicated by .IC routine_name . This term also establishes the context for use of symbolic literals in successive terms separated by .C && operators. .TP .CI "function ==" function_value The log point generating the event must be associated with the functional portion of the SCSI I/O subsystem indicated by .IR function_name . .TP .CI "line ==" number "[ ..." number ] The log point generating the event must be at the indicated line number or in the indicated range of line numbers. .TP .CI "parameter ==" parameter_name The log point generating the event must reference the parameter name indicated by .IR parameter_name . .TP .IC parameter_name "[ &" value_mask ] "relational_operator value" The log point generating the event must reference the parameter name indicated by .IR parameter_name and the parameter value being logged must satisfy the indicated relational expression. Specifically, the result of bitwise ANDing the parameter value with .I value_mask must compare in the manner indicated by .I relational_operator with the value indicated by .IR value . The .I relational_operator must be one of the following relation operators: .C == (equal), .C != (not equal), .C < (less than), .C > (greater than), .C <= (less than or equal to), or .C >= (greater than or equal to). .PP Value and value masks in relational terms may be specified using multiple numeric and symbolic literals in a bitwise logical OR expression using .C | operators. Device values and device masks may also include device file names. .SH EXAMPLES The following .C scsi_log command line causes accesses by any device driver to the indicated SCSI target addresses to be logged: .RS .PP .nf .ift .ft 4 .C "scsi_log 'limit = ( tgt == /dev/rdsk/0s0 || tgt == /dev/rdsk/6s0 )'" .fi .RE .PP The following .C scsi_log command line causes all SCSI tape-driver open and close operations to be logged: .RS .PP .nf .ift .ft 4 .C "scsi_log 'limit = ( file == scsi_tape.c && function == OPEN_CLOSE )'" .fi .RE .PP The following .C scsi_log command line causes all SCSI events associated with the indicated device file to be logged, but stops logging when an .SM ENXIO error occurs: .RS .PP .nf .ift .ft 4 .C "scsi_log 'limit = ( dev == /dev/rmt/0m )' 'trigger = ( error == ENXIO )'" .fi .RE .PP The following .C scsi_log command line causes all SCSI commands associated with the indicated device file to be traced in the kernel .C /usr/sbin/dmesg buffer: .RS .PP .nf .ift .ft 4 .C "scsi_log 'trace_on = ( dev == /dev/rmt/0m )'" .fi .RE .SH AUTHOR .C scsi_log was developed by HP. .SH SEE ALSO scsi(7), analyze(1M), savecore(1M), dmesg(1M) .\" .\" toc@\f3scsi_log(1M)\f1:\0\0\f4scsi_log\f1@@@control and dump SCSI event log for sdisk, schgr, sflop, stape device drivers .\" .\" index@\f4scsi_log\f1 \- control and dump SCSI event log for sdisk, schgr, sflop, stape device drivers@@@\f3scsi_log(1M)\f1 .\" index@\f1control and dump SCSI event log for sdisk, schgr, sflop, stape device drivers@@@\f3scsi_log(1M)\f1 .\" index@\f1dump SCSI event log for sdisk, schgr, sflop, stape device drivers@@@\f3scsi_log(1M)\f1 .\" index@\f1sdisk, schgr, sflop, stape device drivers, control and dump SCSI event log@@@\f3scsi_log(1M)\f1 .\" index@\f1schgr, sflop, stape, sdisk device drivers, control and dump SCSI event log@@@\f3scsi_log(1M)\f1 .\" index@\f1sflop, stape, sdisk, schgr device drivers, control and dump SCSI event log@@@\f3scsi_log(1M)\f1 .\" index@\f1stape, sdisk, schgr, sflop device drivers, control and dump SCSI event log@@@\f3scsi_log(1M)\f1 .\" .\" $Header: scsictl.1m,v 72.3 94/10/07 10:41:17 ssa Exp $ .TA s .TH scsictl 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scsictl \- control a SCSI device .SH SYNOPSIS .CR scsictl .RC [ -akq ] .RC [ -c .IR command ]...\& .RC [ -m .IR mode [\c .CR =\c .IR value ]\|]...\& .I device .SH DESCRIPTION The .CR scsictl command provides a mechanism for controlling a SCSI device. It can be used to query mode parameters, set configurable mode parameters, and perform SCSI commands. The operations are performed in the same order as they appear on the command line. .PP .I device specifies the character special file to use. .SS Options .CR scsictl recognizes the following options. .RS .TP 10 .CR -a Display the status of all mode parameters available, separated by semicolon-blank .RC ( ";\0" ) or newline. .TP .CI -c \0command Cause the device to perform the specified command. .IR command can be one of the following: .RS .TP 10 .CR erase For magneto-optical devices that support write without erase, this command can be used to pre-erase the whole surface to increase data throughput on subsequent write operations. This command maintains exclusive access to the surface during the pre-erasure. .TP .CR sync_cache For devices that have an internal write cache, this command causes the device to flush its cache to the physical medium. .RE .TP .CR -k Continue processing arguments even after an error is detected. The default behavior is to exit immediately when an error is detected. .IP Command line syntax is always verified for correctness, regardless of the .CR -k option. Improper command line syntax causes .CR scsictl to exit without performing any operations on the device. .TP .CI -m \0mode Display the status of the specified .I mode parameter. .I mode can be one of the following: .RS .TP 10 .CR immediate_report For devices that support immediate reporting, this mode controls how the device responds to write requests. If immediate report is enabled .RC ( 1 ), write requests can be acknowledged before the data is physically transferred to the media. If immediate report is disabled .RC ( 0 ), the device is forced to await the completion of any write request before reporting its status. .TP .CR ir Equivalent to .CR immediate_report . .TP .CR queue_depth For devices that support a queue depth greater than the system default, this mode controls how many I/Os the driver will attempt to queue to the device at any one time. Valid values are .RC ( 1 \(mi 255 ). Some disk devices will not support the maximum queue depth settable by this command. Setting the queue depth in software to a value larger than the disk can handle will result in I/Os being held off once a QUEUE FULL condition exists on the disk. .RE .TP .CI -m \0mode = value Set the mode parameter .I mode to .IR value . The available mode parameters and values are listed above. .IP Mode parameters that take only a binary value .RC ( 1 or .CR 0 ) can also be specified as either .CR on or .CR off , respectively. .TP .CR -q Suppress the labels that are normally printed when mode parameters are displayed. Mode parameter values are printed in the same order as they appear on the command line, separated by semicolon-blank .RC ( ";\0" ) or newline. .RE .PP Mode parameters and commands need only be specified up to a unique prefix. When abbreviating a mode parameter or command, at least the first three characters must be supplied. .SH DIAGNOSTICS Diagnostic messages are generally self-explanatory. .SH EXAMPLES To display all the mode parameters, turn .CR immediate_report on, and redisplay the value of .CR immediate_report : .IP .C "scsictl -a -m ir=1 -m ir /dev/rdsk/c0t6d0" .PP producing the following output: .IP .C "immediate_report = 0; queue_depth = 8; immediate_report = 1" .PP The same operation with labels suppressed: .IP .C "scsictl -aq -m ir=1 -m ir /dev/rdsk/c0t6d0" .PP produces the following output: .IP .C "0; 8; 1" .SH WARNINGS Not all devices support all mode parameters and commands listed above. Changing a mode parameter may have no effect on such a device. .PP Issuing a command that is not supported by a device can cause an error message to be generated. .PP .CR scsictl is not supported on sequential-access devices using the tape driver. .PP The .CR immediate_report mode applies to the entire device; the section number of the .I device argument is ignored. .PP To aid recovery, immediate reporting is not used for writes of file system data structures that are maintained by the operating system, writes to a hard disk (but not a magneto-optical device) through the character-device interface, or writes to regular files that the user has made synchronous with .CR O_SYNC or .CR O_DSYNC (see .IR open (2) and .IR fcntl (2)). .SH DEPENDENCIES .SS disc3 When the system is rebooted, the .CR disc3 driver always resets the value of the .CR immediate_report mode parameter to .CR off . If .CR ioctl() or .CR scsictl is used to change the setting of immediate reporting on a SCSI device, the new value becomes the default setting upon subsequent configuration (e.g., opens) of this device and retains its value across system or device powerfail recovery. However, on the next system reboot, the .CR immediate-report mode parameter is again reset to the value of the tunable system parameter, .CR default_disk_ir . This is set in the .I system_file used to create the HP-UX system by the .CR config command (see .IR config(1M)). .SS sdisk If .CR ioctl() or .CR scsictl is used to change the setting of immediate reporting on a SCSI device, the new value becomes the default setting upon subsequent configuration (e.g., opens) of this device until the "last close" of the device, that is, when neither the system nor any application has the device open (for example, unmounting a file system via .CR umount and then mounting it again via .CR mount (see .IR mount (1M)). On the next "first open", the .CR immediate-report mode parameter is again reset to the value of the tunable system parameter, .CR default_disk_ir . This is set in the .I system_file used to create the HP-UX system by the .CR config command (see .IR config(1M)). .SH SEE ALSO config(1M), diskinfo(1M), fcntl(2, open(2). .\" .\" index@\f4scsictl\f1 \- control a SCSI device@@@\f3scsictl(1m)\f1 .\" index@control a SCSI device@@@\f3scsictl(1m)\f1 .\" index@SCSI device, control a@@@\f3scsictl(1m)\f1 .\" index@device, control a SCSI@@@\f3scsictl(1m)\f1 .\" .\" toc@\f3scsictl(1M)\f1:\0\0\f4scsictl\f1@@@control a SCSI device .\" $Header: swjob.1m,v 78.2 96/05/09 12:33:56 ssa Exp $ .\" -*-Nroff-*- .\" $Header: swjob.1m,v 78.2 96/05/09 12:33:56 ssa Exp $ .\" .ds RZ \&HP CONFIDENTIAL .\" .ds RL Release B.10.0x .\" .ds MT Software Distributor B.10.0x .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro, e.g. .CR, .RI, .\" etc. A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .\" .ds PN Release B.10.0x .TA s .TH swjob 1M " " "Hewlett-Packard Company" sd(1M) .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ds )H Software Distributor .\" .ds ]W Release B.10.0x .SH NAME swjob \- Display job information and remove jobs. .PP sd \- Interactive interface for creating and monitoring jobs. .PP For a description of the HP OpenView Software Distributor objects, attributes and data formats, see the .C sd(4) manual page by typing: .PD 0 .IP .C "man 4 sd" .PD .PP For an overview of all HP OpenView Software Distributor commands, see the .C sd(5) manual page by typing: .PD 0 .IP .C "man 5 sd" .PD .PP .SH SYNOPSIS .C swjob .RC [ -i ] .RC [ -u ] .RC [ -v ] .RC [ -R ] .RC [ -a\| .IR attribute\| ] .RC [ -x\| .IR option=value\| ] .RC [ -X\| .IR option_file\| ] .RC [ -f\| .IR jobid_file\| ] .br .RC [ -t\| .IR target_file\| ] .RC [ -C\| .IR session_file\| ] .RC [ -S\| .IR session_file\| ] .RI \c .RI \0[ jobid(s) ] .RI [\c \*(at .IR \0target_selections\| ] .PP .C sd .RC [ -x\| .IR option=value\| ] .RC [ -X\| .IR option_file\| ] .PP .SS Remarks: .B "This command applies only to the HP OpenView Software Distributor" .B "product (HP Prod. No. B1996AA). It is not part of the SD-UX command" .B "set shipped with the HP-UX operating system." .PP .SH DESCRIPTION .PP The .C swjob command displays job information and removes jobs. It supports these features: .RS .TP 2 \(bu Display the current install jobs, copy jobs, and other SD jobs initiated by the SD commands. .TP \(bu Specify a specific job to list or remove. .TP \(bu Display the command logfile for a specific job. .TP \(bu Display the target logfile for a specific target. .RE .PP The .C sd command is used to invoke the interactive interface to create, monitor and remove job status and logs. It provides an interactive interface to the same functionality that .C swjob provides; in addition, it can be used to initiate new install, copy, and remove jobs. .PP .SS Options When no options or operands are specified, .C swjob lists the jobs that exist on the local host. These jobs may be pending, active, in the background or completed. The .C swjob command supports the following options: .RS .TP 15 .C -i Runs the command in interactive mode (invokes the Graphical User Interface). This invocation, "swjob -i", is an alias for the command "sd". [Note: The Graphical User Interface is not supported on SunOS]. .TP .C -u Causes .C swjob to remove the specified job(s). .TP .C -v Causes .C swjob to list all available attributes, one per line. The option applies only to the default list. .TP .C -R Applies to target lists as a shorthand for .CR "@*::*" . .TP .CI -a \0attribute Each job has its own set of attributes. These attributes include such things as job title, schedule date, or results. The .C -a option selects a specific attribute to display. You can specify multiple .C -a options to display multiple attributes. See also .C sd(4) for details on these attributes. This option applies only to the default list. The logfiles summarizing a job or detailing target actions can be displayed using .CR "-a log" , if .C -a log is specified and no other attribute is specified (i.e. no other attribute may be specified). .TP .CI -x \0option=value Set the session .I option to .I value and override the default value (or a value in an alternate .IR option_file specified with the .C -X option). Multiple .C -x options can be specified. .TP .CI -X \0option_file Read the session options and behaviors from .IR option_file . .TP .CI -f \0jobid_file Read the list of .I jobids from .I jobid_file instead of (or in addition to) the command line. .TP .CI -t \0target_file Read the list of .I target_selections from .I target_file instead of (or in addition to) the command line. .TP .CI -C \0session_file Save the current options and operands to .IR session_file . You can enter a relative or absolute path with the file name. The default directory for session files is .CR /.sw/sessions/ . You can recall a session file with the .C -S option. .TP .CI -S \0session_file Execute .C swjob based on the options and operands saved from a previous session, as defined in .IR session_file . You can save session information to a file with the .C -C option. .RE .PP .SS Operands .PP The .C swjob command supports the following syntax for each .IR jobid : .IP .C "jobid" .P The .C swjob command supports the following syntax for each .IR target_selection : .IP .C "[target]" .PP Additionally, the .C swjob command supports the syntax: .IP .C "[pc_controller][::][pc_target]" .PP This syntax only applies to PCs. The PC controller is a fanout server. The PC target may be a PC machine, user, or group name. Valid targets for a PC controller can be listed using .CR "swlist -l machine|user|group" . PC targets can be further qualified for whether they refer to a PC machine, user, or group type with the following syntax: .IP .CI name[,t= type ][,k= address ] .PP The .I type only needs to be specified if a name applies to both (more than one) of a .CR machine , .CR user , or .CR group . (The .I address is used internally for machines and is generally not needed on the command line.) The keyword .C * can be substituted for .CR pc_targets , specifying an operation to all target machines: .IP .C "@ pc_controller::*" .P The .C * cannot be used when retrieving logfiles using .CR "-a log" . .PP .SH EXTERNAL INFLUENCES .PP .SS Defaults File .PP In addition to the standard options, several .C swjob behaviors and policy options can be changed by editing the default values found in: .IP .C /var/adm/sw/defaults - the system-wide default values, .IP .C $HOME/.sw/defaults - the user-specific default values. .P Values must be specified in the defaults file using this syntax: .PP .IP .CI swjob. option = value .PP The default values can be overridden by specifying an options file with the .C -X option, or by specifying .CI -x\0 option = value on the command line. The policy options that apply to .C swjob are: .PP .RS .TP 10 .C agent_timeout_minutes=1440 Causes a target agent to exit if it has been inactive for the specified time. The default of 1440 (24 hours) applies only when the interactive UI is used. Usually, the command line controller resets this to 10 minutes. If you change this value to anything other than 1440, that value will be used even if the controller is using an interactive UI. When using command line invocation of HP OpenView Software Distributor with multiple targets and you have not changed this value from 1440, the value will be reset to 9 minutes plus the number of targets. .\" .bp .\" .TP .C force_job_removal=false By default, the master job is removed from the controller only after a removal of the job information stored on each of its targets succeeds. If the job should be removed regardless of the success of the removal of job information from its targets, set this option to .CR true . .TP .C one_liner={jobid operation state progress results title} Defines the attributes which will be listed for each job when no .C -a option is specified. Each attribute included in the .C one_liner definition is separated by or . Any attributes, except .C log may be included in the .C one_liner definition. If a particular attribute does not exist for an object, then that attribute is silently ignored. .TP .C poll_now=false The status information displayed for a job is as recent as the last time the daemon polled remote targets for information (the .C swinstall option .CR job_polling_interval ). If the most recent status is wanted set this option to .CR true . .TP .C remove_fanout_depot=true When a job is removed the depot software associated with that job is automatically removed. If the software that is part of this job is the same software being used by another job, then be sure to not delete the software as part of the job removal. If the depot software should be retained, set this option to .CR false . .TP .C rpc_binding_info=ncadg_ip_udp:[2121] Defines the protocol sequence and endpoint which will be used to contact .CR swagentd . This value should be consistent among all hosts that work together. See sd(5) for details on specifying this option. .TP .C rpc_timeout=5 Relative length of the communications timeout. This is a value in the range from 0 to 9 and is interpreted by the DCE RPC. Higher values mean longer times; you may need a higher value for a slow or busy network. Lower values will give faster recognition on attempts to contact hosts that are not up, or are not running the .CR swagentd . Each value is approximately twice as long as the preceding value. A value of 5 is about 30 seconds for .CR ncadg_ip_udp . .TP .C targets= Defines the default .IR target_selections . There is no supplied default. If there is more than one target selection, they must be separated by spaces. .TP .C verbose=0 Controls how attribute values are displayed. A value of .C 0 displays only the attribute value. A value of .C 1 displays both the attribute keyword and value. (See the .C -v option above.) .RE .PP .SS Session File .PP Each invocation of the .C swjob command defines a job display session. The invocation options, source information, software selections, and target hosts are saved before the installation or copy task actually commences. This lets you re-execute the command even if the session ends before proper completion. .PP Each session is automatically saved to the file .I $HOME/.sw/sessions/swinstall{swcopy}.last. This file is overwritten by each invocation of .CR swjob . .PP You can also save session information to a specific file by executing .C swjob with the .C -C .I session__file option. .PP A session file uses the same syntax as the defaults files. You can specify an absolute path for the session file. If you do not specify a directory, the default location for a session file is .IR "/.sw/sessions/" . .PP To re-execute a session file, specify the session file as the argument for the .C -S .I session__file option of .CR swjob . .PP Note that when you re-execute a session file, the values in the session file take precedence over values in the system defaults file. Likewise, any command line options or parameters that you specify when you invoke .CR swjob take precedence over the values in the session file. .PP .SS Environment Variables .PP The .C swjob command does not use environment variables. .PP .C LANG .IP Determines the language in which messages are displayed. If LANG is not specified or is set to the empty string, a default value of .C C is used. See .C lang(5) for more information. .IP NOTE: The language in which the SD agent and daemon log messages are displayed is set by the system configuration variable script, .CR /etc/rc.config.d/LANG . For example, .CR /etc/rc.config.d/LANG , must be set to .CR LANG=ja_JP.SJIS or .CR LANG=ja_JP.eucJP to make the agent and daemon log messages display in Japanese. .PP .SS Signals .PP The .C swjob command catches the signals SIGQUIT and SIGINT. If these signals are received, .C swjob prints a message, sends a Remote Procedure Call (RPC) to the daemons to wrap up, and then exits. .PP Each agent will complete the list task before it wraps up. .PP .SH OPERATION .PP Different views of the job information are available. The types of listings that can be selected are given below. .RS .TP 2 \(bu Default Listing .TP \(bu Target Listing .TP \(bu Logfile Listing .RE .PP .SS "Default Listing" .PP If .C swjob is invoked with no options or operands, it lists all jobs that are on the local host. This listing contains one line for each job. The line includes the job tag attribute and all other attributes selected via the .C one_liner option. .PP Listing jobs on a remote controller is not supported. If a .IR jobid is given, information for only that job is displayed. .PP .SS "Status Listing" .PP If a .IR -R or .I @ target_specification is given, the targets for that job and their status are displayed. By default the status information includes Type, State, Progress and Results. .PP .SS "Logfile Listing" .PP One of the attributes "log" encompasses a variety of logfile types. The type of logfile returned when the -a log attribute is given depends on the operands given. The types of logfiles: .PP .RS .TP 27 .C "No target_selections" Show the controller logfile (default). .TP .C "@ target" Show the agent or PC controller logfile. .TP .C "@ pc_controller::pc_target" Show the PC target logfile. .RE .RE .PP .SH RETURN VALUES .PP The .C swjob command returns: .RS .TP 4 .C 0 The job information was successfully listed or the job was successfully removed. .PD 0 .TP .C 1 The list /remove operation failed for all .IR jobids . .PD 0 .TP .C 2 The list /remove operation failed for some .IR jobids . .PD .RE .PP .SH DIAGNOSTICS .PP The .C swjob command writes to stdout, stderr, and to the agent logfile. .PP .SS Standard Output .PP All listings are printed to stdout. .PP .SS Standard Error .PP The .C swjob command writes messages for all WARNING and ERROR conditions to stderr. .\" .\" .\" .bp .\" .PP .SS Logging .PP The .C swjob command does not log summary events. It logs events about each read task to the .CR swagent logfile associated with each .IR target_selection . .PP .SH EXAMPLES .PP To list all of the jobs that exist on the local host: .IP .C "swjob" .P To show the scheduled date for job hostA-0001: .IP .C "swjob -a schedule hostA-0001" .P For job hostA-0001 list the targets and their status: .IP .C "swjob -R hostA-0001" or .C "swjob hostA-0001 @ *" .P For job hostA-0001 give the status for pc_controller1 and all its PC targets .IP .C "swjob hostA-0001 \*(at .C " pc_controller1"::*" .P For job hostA-0001 list the controller log: .IP .C "swjob -a log hostA-0001" .P For job hostA-0001 list the log for pc_controller1: .IP .C "swjob -a log hostA-0001" \*(at .C " pc_controller1" .P For job hostA-0001 list the log for PC target pc1 on pc_controller1: .IP .C "swjob -a log hostA-0001" \*(at .C " pc_controller1::pc1" .SH LIMITATIONS The .C swjob command only runs on HP-UX. Any .C PC controller target selections apply only to PCs. .PP .SH FILES .PP .\" .C /var/adm/sw/ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. This directory is also the default location of logfiles. .RE .\" .C /var/adm/sw/queue/ .br .RS 8 The directory which contains the information about all active and complete install jobs, copy jobs, and other jobs initiated by the SD commands. .RE .\" .C /usr/lib/sw/sys.defaults .br .RS 8 Contains the master list of current SD options (with their default values). .RE .\" .C /var/adm/sw/defaults .br .RS 8 Contains the active system-wide default values for some or all SD options. .RE .\" .C $HOME/.sw/defaults .br .RS 8 Contains the user-specific default values for some or all SD options. .RE .PP .SH PC FILES .PP .\" .C ...\\\\SD\\\\DATA\\\\ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. .RE .\" .C ...\\\\SD\\\\DATA\\\\QUEUE\\\\ .br .RS 8 The directory which contains the information about all active and complete install, remove, and other jobs at the PC Controller. .RE .PP .SH AUTHOR .PP .C swjob was developed by the Hewlett-Packard Company. .PP .SH SEE ALSO .PP sd(4), sd(5), swacl(1M), swagentd(1M), swcluster(1M), swconfig(1M), swcopy(1M), swgettools(1M), swinstall(1M), swlist(1M), swmodify(1M), swpackage(1M), swpackage(4), swreg(1M), swremove(1M), swverify(1M), update(1M), and the .IR "HP OpenView Software Distributor Administrator's Guide". .\" .\" toc@\f3swjob(1M)\f1:\0\0\f4swjob\f1, \f4sd\f1@@@display job information, remove jobs, create and monitor jobs .\" .\" toc@\f4sd\f1:\0\0create and monitor jobs@@@\f1see \f3swjob(1M)\f1 .\" .\" index@\f4swjob\f1 \- display job information and remove jobs@@@\f3swjob(1M)\f1 .\" index@\f4sd\f1 \- create and monitor jobs@@@\f3swjob(1M)\f1 .\" .\" index@\f1display job information and remove jobs@@@\f3swjob(1M)\f1 .\" index@\f1create and monitor jobs@@@\f3swjob(1M)\f1 .\" .\" links@swjob.1m sd.1m ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright Hewlett-Packard Company 1991 ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws ...\" ...\" .rm zA .rm zZ .TH sec_admin "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "Security Servers" "administering" .iX "master keys" "creating" .iX "registry database" "updating" .iX "-[" "Security Service commands" "\*Lsec_admin\*O" .SH NAME \*Lsec_admin\*O - Registry replica administration tool .zA "enh,6450,R1.0.2,update for replication" .SH "SYNOPSIS" .zA "def,8134,R1.0.2A,added site option" .sS \*Lsec_admin\*O [\*L-site\*O \*Vname\*O] [\*L-nq\*O] .sE .SH "OPTIONS" .VL 1i .LI "\*L-site\*O \*Vname\*O" The \*L-site\*O option causes \*Lsec_admin\*O to bind to the replica specified by the \*Vname\*O argument. If the option is not supplied, \*Lsec_admin\*O binds randomly to any replica in the local cell. .PP The \*Vname\*O argument can be: .ML .LI A specific cell_name (or \*L/.:\*O for the local cell) to bind to any replica in the named cell. .LI The global name of a replica to bind to that specific replica in that specific cell. .LI The name of a replica as it appears on the replica list to bind to that replica in the local cell. .LI A string binding to a specific replica. An example of a string binding is \*Lncadg_ip_udp:15.22.144.163\*O. This form is used primarily for debugging or if the Cell Directory Service is not available. .LE .zZ "def,8134,R1.0.2A,added site option" .LI "\*L-nq\*O The \*L-nq\*O flag turns off queries initiated by certain \*Lsec_admin\*O subcommands before they perform a specified operation. For example the \*Ldelrep\*O subcommand deletes a registry replica. Before \*Lsec_admin\*O performs the deletion, it prompts for verification. If you invoke \*Lsec_admin\*O with the \*L-nq\*O option, the subcommand performs the deletion without prompting. .LE .zA "defect, 11818, R1.1, Added caveat" .SH "NOTES" With the exception of the following subcommands, this command is replaced at Revision 1.1 by the \*Ldcecp\*O command. This command may be fully replaced by the \*Ldcecp\*O command in a future release of DCE, and may no longer be supported at that time. .P .ML .LI \*Lmonitor\*O .LI \*Lexit\*O .LI \*Lhelp\*O .LI \*Lquit\*O .LE .zZ "defect, 11818, R1.1, Added caveat" .SH "DESCRIPTION" .PP The registry database is replicated: each instance of a registry server, \*Lsecd\*O, maintains a working copy of the database in virtual memory and on disk. One server, called the master replica, accepts updates and handles the subsequent propagation of changes to all other replicas. All other replicas are slave replicas, which accept only queries. Each cell has one master replica and numerous slave replicas. .PP Using the \*Lsec_admin\*O command you can: .ML .LI View a list of replicas .LI Delete a replica .LI Reinitialize a replica .LI Stop a replica .LI Put the master replica into and out of the maintenance state .LI Generate a new master key used to encrypt principal keys .zA "enh,10774,R1.1,added change_master, become" .LI Turn the master registry into a slave registry and a slave registry into the master registry.. .zZ "enh,10774,R1.1,added change_master, become" .LE .PP Note that \*Lsec_admin\*O cannot add, delete, or modify information in the database, such as names and accounts. Use \*Lrgy_edit\*O to modify registry database entries. .PP .SH "THE DEFAULT REPLICA AND DEFAULT CELL" .PP Most \*Lsec_admin\*O commands are directed to a default replica. When \*Lsec_admin\*O is invoked, it automatically binds to a replica in the local cell. This replica becomes the default replica. .SS "Identifying the Default Replica and the Default Cell" You use the \*Lsite\*O subcommand to change the default replica and, optionally, the default cell. When you use the \*Lsite\*O command, you can supply the name of a specific replica, or you can simply supply the name of a cell. If you supply a cell name, \*Lsec_admin\*O binds to a replica in that cell randomly. If you supply a specific replica name, \*Lsec_admin\*O binds to that replica. .PP Specifically, you can supply any of the following names to the \*Lsite\*O subcommand: .ML .LI A cell name. If you enter a cell name, the named cell becomes the default cell. The \*Lsec_admin\*O command randomly chooses a replica to bind to in the named cell, and that replica becomes the default replica. .LI The global name given to the replica when it was created. A global name identifies a specific replica in a specific cell. That cell becomes the default cell and that replica the default replica. .LI The replica's name as it appears on the replica list (a list maintained by each Security Server containing the network addresses of each replica in the local cell). That replica becomes the default replica and the cell in which the replica exists becomes the default cell. .LI The network address of the host on which the replica is running. The replica on that host becomes the default replica, and the cell in which the host exists becomes the default cell. .LE .PP .SS "Naming the Default Replica" As an example, assume a replica named \*Lsubsys/dce/sec/rs_server_250_2\*O: .ML .LI Exists in the local cell \*L/.../dresden.com\*O .LI Has a global name of \*L/.../dresden.com/subsys/dce/sec/rs_server_250_2\*O .LI Is named \*Lsubsys/dce/sec/rs_server_250_2\*O on the replica list .LI Runs on a host whose \*Lip\*O network address is \*L15.22.144.248\*O .LE .PP This replica can then be identified to the \*Lsite\*O subcommand in any of the following ways: .ML .LI \*L/.../dresden.com/subsys/dce/sec/rs_server_250_2\*O \(em The replica's full global name. .LI \*Lsubsys/dce/sec/rs_server_250_2\*O \(em The replica's cell-relative name on the replica list. .LI \*Lncadg_ip_udp:15.22.144.248 \*O \(em The network address of the host on which the replica runs. .LE .PP .SS "Naming the Default Cell" .PP When a default replica is identified specifically, its cell becomes the default cell. In the example in "Naming the Default Replica" above, the default cell is \*L/.../dresden.com\*O. .P You can specify simply a cell name to the \*Lsite\*O subcommand. When this is done, any replica in that cell is selected as the default replica. .PP For example, assume .PP \*L/.../bayreuth.com/subsys/dce/sec/rs_server_300_1\*O .PP and .PP \*L/.../bayreuth.com/subsys/dce/sec/rs_server_300_2\*O .PP are replicas in the cell \*L/.../bayreuth.com\*O. .PP If you type .iS \*Lsite /.../bayreuth.com\*O .iE .PP then .PP \*L/.../bayreuth.com\*O .PP becomes the default cell and either .PP \*L/.../bayreuth.com/subsys/dce/sec/rs_server_300_1\*O .PP or .PP \*L/.../bayreuth.com/subsys/dce/sec/rs_server_300_2\*O .PP becomes the default replica. .PP .SH "AUTOMATIC BINDING TO THE MASTER" .PP Some of the \*Lsec_admin\*O subcommands can act only on the master registry and thus require binding to the master registry. If you execute a subcommand that acts only on the master and the master is not the default replica, \*Lsec_admin\*O attempts to bind to the master replica in the current default cell automatically. If this attempt is successful, \*Lsec_admin\*O displays a warning message informing you that the default replica has been changed to the master registry. The master registry will then remain the default replica until you change it with the \*Lsite\*O subcommand. If the attempt to bind is not successful, \*Lsec_admin\*O displays an error message, and the subcommand fails. .PP .zA "def,9373,R1.1,moved states" .zZ "def,9373,R1.1,moved states" .SH "INVOKING sec_admin" .PP .zA "def,9306,r1.1,fix initial message" When you invoke \*Lsec_admin\*O, it displays the current default replica's full global name and the cell in which the replica exists. Then it displays the \*Csec_admin>\*O prompt. .oS \*C$\*L sec_admin\*C Default replica: /.../dresden.com/subsys/dce/sec/music Default cell: /.../dresden.com\*C sec_admin>\*O .oE .zZ "def,9306,r1.1,fix initial message" .PP At the \*Csec_admin>\*O prompt, you can enter any of the \*Lsec_admin\*O subcommands. .PP .SH "SUBCOMMANDS" The subcommand descriptions that follow use \*Vdefault_replica\*O to indicate the default replica and \*Vother_replica\*O to indicate a replica other than the default. \*Vother_replica\*O must identify a replica in the default cell. It is specified by its name on the cell's replica list (that is, by its cell-relative name). Use the \*Llrep\*O subcommand to view the default cell's replica list. .VL 1i .zA "enh,10774,R1.1,added change_master, become" .LI "\*Lbecome\*O [ \*L-master\*O ] [ \*L-slave\*O ] The \*L-master\*O option makes the current default replica (which must be a slave) the master replica. .PP The \*L-slave\*O option makes the current default replica (which must be the master) a slave replica. .PP This method of changing to master or slave can cause updates to be lost. The \*Lchange_master\*O subcommand is the preferred means of designating a different master replica. However, you may find the \*Lbecome -master\*O command useful if the master server is irrevocably damaged and you are unable to use \*Lchange_master\*O. .PP .LI "\*Lchange_master -to\*O \*Vother_replica\*O Make the replica specified by \*Vother_replica\*O the master replica. To perform this operation, \*Vother_replica\*O must be a slave, and the current default replica must be the master. If the current default replica is not the master, \*Lsec_admin\*O attempts to bind to the master. .PP If the change operation is successful, the current master: .AL .LI Applies all updates to \*Vother_replica\*O .LI Becomes a slave .LI Tells \*Vother_replica\*O to become the master .LE .PP .zZ "enh,10774,R1.1,added change_master, become" .LI "\*Ldelr\*O[\*Lep\*O] \*Vother_replica\*O [\*L-force \*O] Delete the registry replica identified by \*Vother_replica\*O. To perform this operation, the current default replica must be the master. If it is not, \*Lsec_admin\*O attempts to bind to the master. .PP If the delete operation is successful, the master: .AL .LI Marks \*Vother_replica\*O as deleted .LI Propagates the deletion to all replicas on its replica list .LI Delivers the delete request to \*Vother_replica\*O .LI Removes \*Vother_replica\*O from its replica list .LE .PP The \*L-force\*O option causes a more drastic deletion. It causes the master to first delete \*Vother_replica\*O from its replica list and then to propagate the deletion to the replicas that remain on its list. Since this operation never communicates with the deleted replica, you should use \*L-force\*O only when the replica has died irrecoverably. If you use \*L-force\*O while \*Vother_replica\*O is still running, you should then use the \*Ldestroy\*O subcommand to eliminate the deleted replica. .PP .LI "\*Lh\*O[\*Lelp\*O] [\*Vcommand\*O] Lists the \*Lsec_admin\*O subcommands and shows their allowed abbreviations. If \*Vcommand\*O is specified, displays help for the specified command. .LI "\*Linfo\*O [\*L-full\*O] Displays status information about the default replica. .PP The \*Linfo\*O subcommand contacts the default replica to obtain the appropriate information. If this information is not available, \*Linfo\*O prints the replica name and a message stating the information is not available. .PP Without the \*L-full\*O option, \*Linfo\*O displays: .ML .LI The default replica's name and the name of the cell in which the replica exists .LI Whether the replica is a master or a slave .LI The date and time the replica was last updated and the update sequence number .LI .zA "def,9373,R1.1,add states" An indication of the replica's state, as follows: .ML .LI \*LBad State\*O \(em The state of the replica prohibits the requested operation. .LI \*LUninitialized\*O \(em The database is a stub database that has not been initialized by the master replica or another up-to-date replica .zA "def,9360,R1.0.3,fix typo" .LI \*LInitializing\*O \(em The replica is in the process of being initialized by the master replica or another up-to-date replica .zZ "def,9360,R1.0.3,fix typo" .LI \*LIn Service\*O \(em The replica is available for queries and propagation updates if it is a slave replica or queries and updates if it is the master replica ...\" .LI ...\" \*LRenaming\*O \(em The replica is in process of renaming itself .LI \*LCopying Database\*O \(em The replica is in the process of initializing (copying its database to) another replica .LI \*LSaving Database\*O \(em The replica is in the process of saving its database to disk. .LI \*LIn Maintenance\*O \(em The replica is unavailable for updates but will accept queries .zA "def,7274,R1.0.2,State name change" .LI \*LChanging Master Key\*O \(em The replica is in the process of having its master key changed .zZ "def,7274,R1.0.2,State name change" .zA "enh,10774,R1.1,added change_master, become" .LI \*LBecoming Master\*O\(em The replica is in the process of becoming the master replica (applicable to slave replicas only) .LI \*LBecoming Slave\*O\(em The master replica is in the process of becoming a slave replica (applicable to the master replicas only) .zZ "enh,10774,R1.1,added change_master, become" .LI \*LClosed\*O \(em The replica is in the process of stopping .LI \*LDeleted\*O \(em The replica is in the process of deleting itself .LI \*LDuplicate Master\*O \(em The replica a duplicate master and should be deleted. .LE .zZ "def,9373,R1.1,add states" .PP The master replica is available for queries when it is in the in-service, copying-database, in-maintenance, master-key-changing and becoming-slave states. It is available for updates only when it is in the in-service state. .PP A slave replica is available for queries when it is in the in-service, copying-database, master-key-changing and becoming-master states. .zZ "enh,10774,R1.1,added change_master, become" It accepts updates from the master replica only when it is in the in-service state. It accepts a request from the master replica to initialize only when it is in the uninitialized or in-service state. .LE .PP The \*L-full\*O option displays all the above information and the following information: .ML .LI The default replica's unique identifier .LI The replica's network addresses .LI The unique identifier of the cell's master replica .LI The network addresses of the cell's master replica .LI The master sequence number, which is the sequence number of the event that made the replica the master .LI If the replica is the master replica, the update sequence numbers that are still in the propagation queue and have yet to be propagated .zA "def,9368,R1.1 add entries .LI The DCE software version number. .LE .zZ "def,9368,R1.1 add entries" .PP .LI "\*Linitr\*O[\*Lep]\*O \*Vother_replica\*O Reinitializes a replica by copying an up-to-date database to \*Vother_replica\*O. .PP The master replica initiates and guides the operation. If the operation is successful .AL .LI The master replica .AL .LI Marks \*Vother_replica\*O for reinitialization .LI Tells \*Vother_replica\*O to reinitialize itself .LI Gives \*Vother_replica\*O a list of replicas with up-to-date databases .LE .LI The \*Vother_replica\*O picks a replica from the list and asks that replica to initialize it (that is, to copy its database to \*Vother_replica\*O) .LE .PP To perform this operation, \*Vother_replica\*O must be a slave, and the current default replica must be the master. If the current default replica is not the master, \*Lsec_admin\*O attempts to bind to the master. .PP This subcommand is generally not used under normal conditions. .PP .LI "\*Llr\*O[\*Lep\*O] [\*L-s\*O[\*Ltate\*O]] [\*L-u\*O[\*Luid\*O]] [\*L-a\*O[\*Lddr\*O]] [\*L-p\*O[\*Lrop\*O]] [\*L-al\*O[\*Ll\*O]]" Lists the replicas on the default replica's replica list. .PP If you enter no options, the display includes the replica name and whether or not it is the master replica. In addition if the master replica's list is being displayed, slave replicas marked for deletion are noted. With options, the display includes this information and the information described in the following paragraphs. .PP The \*L-state\*O option shows each replica's current state, the date and time the replica was last updated, and the update sequence number. To obtain this information, \*Llrep\*O contacts each replica. If this information is not available from the replica, \*Llrep\*O prints the replica name and a message stating the information is not available. .PP The \*L-addr\*O option shows each replica's network addresses. .PP The \*L-uuid\*O option shows each replica's unique identifier. .PP The \*L-prop\*O option shows: .ML .LI The date and time of the last update the master sent to each slave replica .LI The sequence number of the last update to each slave replica .LI The number of updates not yet applied to each slave replica .LI The status of the master replica's last communication with each slave replica .zA "def,9373,R1.1,add states" .LI The propagation state of each slave replica. This state, illustrates how the master replica views the slave replica, can be any of the following: .ML .LI \*LBad State\*O\(emThe state of the replica prohibits the requested operation. .LI \*LMarked for Initialization\*O\(emThe replica has been marked for deletion by the master replica. .LI \*LInitialized\*O\(emThe replica has been marked for initialization by the master replica. .LI \*LInitializing\*O\(emThe replica is in the process of being initialized by the master replica. .LI \*LReady for Updates\*O\(emThe replica has been initialized by the master replica and in now available for propagation updates from the master replica. .LI \*LMarked for Deletion\*O\(emThe replica has been marked for deletion by the master replica. .LE .zZ "def,9373,R1.1,add states" .LE .PP This information is obtained from the master replica; the slave replicas are not contacted for this information. .PP The \*L-prop\*O option is valid only for the master. .PP For slave replicas, the \*L-all\*O option shows all the information above except that displayed by the \*L-prop\*O option. For the master replica, the \*L-all\*O option shows all the information. .LI "\*Lmas\*O[\*Lter_key\*O] Generates a new master key for the default replica and reencrypts account keys using the new key. The new master key is randomly generated. .PP Each replica (master and slaves) maintains its own master key used to access the data in its copy of the database. .PP .LI "\*Lmonitor \*O[\*L-r \*Vm\*O] Periodically list the registry replicas stored in the current default replica's replica list. The list includes each replica's current state, the date and time the replica was last updated and the update sequence number. Note that this is the same information as that displayed by the \*Linfo\*O subcommand with no options. .PP The \*Lmonitor\*O subcommand contacts each replica to obtain the information it displays. If this information is not available from the replica, \*Lmonitor\*O prints the replica name and a message stating the information is not available. .PP The \*L-r\*O option causes the replicas to be listed at intervals you specify. \*Vm\*O is a number of minutes between intervals. The default is 15 minutes. .LI "\*Ldestroy\*O \*Vdefault_replica\*O Destroy the current default replica. To perform this operation, the current default replica and the default replica you name as \*Vdefault_replica\*O must be the same. This is to confirm your desire to perform the deletion. .PP If the operation is successful, the default replica deletes its copy of the registry database and stops running. This subcommand does not delete \*Vdefault_replica\*O from the replica lists. .zA "def,7274,R1.0.2,add delrep use" Use the \*Ldelrep -force\*O subcommand to delete the replica from the other replica lists. .zZ "def,7274,R1.0.2,add delrep use" .PP The preferred way to delete replicas is to use the \*Ldelrep\*O subcommand. However, the \*Ldestroy\*O subcommand can be used if \*Ldelrep\*O is unusable because the master is unreachable or the replica is not on the master's replica list. .LI "\*Lsite\*O [\*Vname\*O [\*L-u\*O[\*Lpdate\*O]]] Set or display the default cell and the default replica. .PP The \*Vname\*O argument identifies the replica to set as the default replica and, as a consequence, the default cell. It can be: .ML .LI A specific cell_name (or \*L/.:\*O for the local cell) to make any replica in the named cell the default. .LI The global name of a replica to make the specified replica in the specified cell the default. .LI The name of a replica as it appears on the replica list to make the named replica (which exists in the default cell) the default replica. .LI A string binding to a specific replica. An example of a string binding is \*Lncadg_ip_udp:15.22.144.163\*O. This form is used primarily for debugging or if the Cell Directory Service is not available. .LE .PP The \*L-u\*O option specifies that \*Lsec_admin\*O should find the master replica. Normally you specify the name of a cell for \*Vname\*O in conjunction with the \*L-u\*O option. In this case \*Lsec_admin\*O finds the master replica in that cell. If you use a replica name for \*Vname\*O, \*Lsec_admin\*O queries the named replica to find the master replica in the named replica's cell. .PP If you supply no arguments, \*Lsec_admin\*O displays the current default replica and default cell. .PP .LI "\*Lstop\*O Stops the Security Server (\*Lsecd\*O) associated with the default replica. .LI "\*Lsta\*O[\*Lte\*O]\*L -maintenance\*O | \*L-service\*O Puts the master replica into maintenance state or takes it out of maintenance state. This subcommand is useful for performing backups of the registry database. .PP If the current default replica is not the master, \*Lsec_admin\*O attempts to bind to the master. .PP The \*L-maintenance\*O flag causes the master replica to save its database to disk and refuse any updates. .PP .zA "def,7274,R1.0.2,does not reload db from disk" The \*L-service\*O flag causes the master replica to return to its normal "in service" state and start accepting updates. .zZ "def,7274,R1.0.2,does not reload db from disk" .LI "\*Le\*O[\*Lxit\*O] or \*Lq\*O[\*Lui\*Ot] The \*Lquit\*O and \*Lexit\*O subcommands end the \*Lsec_admin\*O session. .LE .SH "EXAMPLES" .AL .LI The following example, invokes \*Lsec_admin\*O and uses the \*Llrep\*O subcommand to list replicas on the replica list and their states: .zA "def,9306,r1.1,fix initial message" .iS \*C$\*L /opt/dcelocal/bin/sec_admin\*C Default replica: /.../dresden.com/subsys/dce/sec/rs_server_250_2 Default cell: /.../dresden.com \*Csec_admin> \*Llrep -st\*C Replicas in cell /.../dresden.com (master) subsys/dce/sec/master state: in service Last update received at: 1993/11/16.12:46:59 Last update's seqno: 0.3bc subsys/dce/sec/rs_server_250_2 state: in service Last update received at: 1993/11/16.12:46:59 Last update's seqno: 0.3bc subsys/dce/sec/rs_server_250_3 state: in service Last update received at: 1993/11/16.12:46:59 Last update's seqno: 0.3bc sec_admin>\*O .iE .zZ "def,9306,r1.1,fix initial message" .LI The following example, sets the default replica to the master in the local cell: .zA "def,9306,r1.1,fix initial message" .iS \*Csec_admin> \*Lsite /.: -u\*C Default replica: /.../dresden.com/subsys/dce/sec/master Default cell: /.../dresden.com sec_admin>\*O .iE .zZ "def,9306,r1.1,fix initial message" .LE .zZ "enh,6450,R1.0.2,update for replication" .iX "-]" "Security Servers" "administering" .iX "-]" "Security Service commands" "\*Lsec_admin\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright Hewlett-Packard Company 1991 ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" .HS ...\" 10.0;sec_create_db, revision 1.0, 91/12/17 ...\" sec_create_db -- Create a registry database. ...\" usage: /install/tools/sec_create_db ...\" .HE ...\" .\".TH SEC_CREATE _DB ...\" .if '\nv'1' .TH SEC_CREATE_DB 1 domain ...\" .if '\nv'4' .TH SEC_CREATE_DB 8 domain ...\" .if '\nv'5' .TH SEC_CREATE_DB 1M domain ...\" .if !\nh \{ ...\" .rm zA .rm zZ .TH sec_create_db "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "Security Service commands" "\*Lsec_create_db\*O" .iX "-[" "registry database" "creating" .SH NAME \*Lsec_create_db\*O \- registry database creation utility .SH "SYNOPSIS" .zA "enh,6619,R1.0.2,add -master and -slave" .zA "defect,6211,R1.0.3,remove full path in SYNOPSIS" .sS \*Lsec_create_db \*O{\*L-master\*O | \*L-slave\*O} \*L-my\*O[\*Lname\*O] \*Vmy_server_name \*O .br [\*L-cr\*O[\*Leator\*O] \*Vcreator_name\*O] .br [\*L-cu[nix_id]\*O \*Vcreator_unix_id\*O] .br [\*L-g[roup_low_id\*O] \*Vg_unix_id\*O] .br [\*L-k[eyseed] \*Vkeyseed\*O] .br [\*L-ma[x_unix_id] \*Vmax_unix_id\*O] .br [\*L-o[rg_low_unix_id]\*O \*Vo_unix_id\*O] [\*L-pa[ssword] \*Vdefault_password\*O] .br [-\*Lp[erson_low_unix_id]\*O \*Vp_unix_id\*O] .br [\*L-u[uid \*Vcell_uuid\*O] .br [\*L-v[erbose]\*O] .sE .zZ "defect,6211,R1.0.3,remove full path in SYNOPSIS" .SH "OPTIONS" .VL .LI "\*L{-master | -slave}\*O Specifies whether the database for the master replica should be created (\*L-master\*O) or a database for a slave replica should be created (\*L-slave\*O). All other \*Lsec_create_db\*O options can be used with the \*L-master\*O option. Only the \*L-myname\*O, \*L-keyseed\*O, and \*L-verbose\*O options can be used with the \*L-slave\*O option. .zZ "enh,6619,R1.0.2,add -master and -slave" .LI "\*L-my[name]\*O" Specifies the name that will be used by the Directory Service to locate the machine on which the cell's Security Server is running. .LI "\*L-cr[eator]\*O" Specifies the principal name of the initial privileged user of the registry database (known as the "registry creator"). .LI "\*L-cu[nix_id]\*O" Specifies the UNIX ID of the initial privileged user of the registry database. If you do not enter the UNIX ID, it is assigned dynamically. .LI "\*L-g[roup_low_unix_id]\*O" Specifies the starting point for UNIX IDs automatically generated by the Security Service when groups are added with the \*Lrgy_edit\*O command. .zA "def,7274,R1.0.2,keyseed set for master and slave" .LI "\*Lk[eyseed]\*O Specifies a character string used to seed the random key generator in order to create the master key for the database you are creating. .zA "enh,10420,R1.1,addition" It should be string that cannot be easily guessed. .zZ "enh,10420,R1.1,addition" The master key is used to encrypt all account passwords. Each instance of a replica (master or slave) has its own master key. You can change the master key using the \*Lsec_admin\*O command. .zZ "def,7274,R1.0.2,keyseed set for master and slave" .LI "\*Lma[x]\*O" Specifies the highest UNIX ID that can be assigned to a principal, group, or organization. .LI "\*L-o[rg_low_unix_id]" Specifies the starting point for UNIX IDs automatically generated by the Security Service when organizations are added with the \*Lrgy_edit\*O command. .zA "def,6619,R1.0.2,changed parenthetical note" .LI "\*L-pa[ssword]\*O" The default password assigned to the accounts created by \*Lsec_create_db\*O, including the account for the registry creator. If you do not specify a default password,\*L -dce- \*Ois used. (Note that the \*Lhosts\*O/\*Vlocal_host\*L/self none none\*O, \*Lkrbtgt\*O\*E/\*O\*Vcell_name\*O \*Lnone none\*O, and \*Lnobody none none\*O accounts are not assigned the default password, but instead a randomly generated password.) .zZ "def,6619,R1.0.2,changed parenthetical note" .LI "\*L-p[erson_low_unix_id]\*O" Specifies the starting point for UNIX IDs automatically generated by the Security Service when principals are added with the \*Lrgy_edit\*O command. .LI "\*L-u[uid]\*O" Specifies the cell's UUID. If you do not enter this UUID, it is assigned dynamically. .LI "\*L-v[erbose]\*O" Specifies that \*Lsec_create_db\*O runs in verbose mode and displays all activity. .LE .SH "DESCRIPTION" .zA "def,7274,R1.0.2,differentiate between master and slave db" .PP The \*Lsec_create_db\*O tool creates new master and slave databases in \*Vdcelocal\*L/var/security/rgy_data\*O on the machine from which \*Lsec_create_db\*O is run. Normally, these databases are created only once by the system configuration tool, \*Ldce_config\*O. However, you can use \*Lsec_create_db\*O if you need to re-create the master or a slave databse from scratch. You must be root to invoke \*Lsec_create_db\*O. .PP The \*Lsec_create_db -master\*O option creates the master database on the machine on which it is run. This database is initialized with names and accounts, some of them reserved. You must use the \*Lrgy_edit\*O command to populate the database with objects and accounts. .PP When the master registry database is created, default ACL entries for registry objects are also created. These entries give the most privileged permission set to the principal named in the \*L\-cr[eator]\*O option. If the principal is not one of the reserved names and accounts, \*Lsec_create_db\*O adds it as a new principal and adds an account for that new principal. If the \*L-cr\*O option is not used, root is the creator. .PP The \*Lsec_create_db -slave\*O option creates a slave database on the machine on which it is run. This command creates a stub database on the local node in \*Vdcelocal\*L/var/security/rgy_data\*O and adds the newly created replica to the master's replica list. The master then marks the replica to be initialized when a Security Server is started on the slave's node. .PP The \*Lsec_create_db\*O command also creates a registry configuration file, named \*Vdcelocal\*L/etc/security/pe_site\*O, that contains the network address of the machine on which the database is created. This file supplies the binding address of the \*Lsecd\*O master server if the Naming Service is not available. .zZ "def,7274,R1.0.2,differentiate between master and slave db" .SH "FILES" .VL .LI "\*V/dcelocal\*L/etc/security/pe_site\*O" The file containing the network address of the machine on which the security database is created. .LI "\*V/dcelocal\*L/var/security/rgy_data\*O" The directory in which the registry database files are stored. .LE .SH "RELATED INFORMATION" .PP Commands: \*Lsecd(1m)\*O, \*Lsec_admin(1m)\*O .iX "-]" "Security Service commands" "\*Lsec_create_db\*O" .iX "-]" "registry database" "creating" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\"Copyright Hewlett-Packard Company 1991 ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" .rm zA .rm zZ .TH sec_intro 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "Security Service commands" "summary" .SH NAME .PP \*Lsec_intro\*O - Introduction to the DCE Security administrative commands .SH "DESCRIPTION" .PP This section describes DCE Security commands for system administration. These commands are .zA "enh,5923,R1.1,move User's Guide & Ref pages to Admin Ref" .VL .LI "\*Lacl_edit\*O " Manages Access Control Lists (ACLs) for DCE objects .zA "enh,10234,R1.1" .LI "\*Lauditd\*O Starts the DCE Audit Daemon .zZ "enh,10234,R1.1" .LI "\*Lchpass\*O " Changes user information, such as login name, password, home directory, password and account expiration dates, and login shell. .zA "def,8628,R1.1,chpass is vendor-specific" The implementation of this utility is platform-specific. Use the chpass utility supplied by your platform vendor for changing user information. .zZ "def,8628,R1.1,chpass is vendor-specific" .LI "\*Ldce_login\*O " Validates a principal's identity and obtains a principal's network credentials. This command is used primarily during DCE configuration. Use the login utility supplied by your platform vendor for user login. .LI "\*Lkdestroy\*O " Destroys your login context and credentials .LI "\*Lkinit\*O " Obtains and caches a ticket granting ticket .LI "\*Lklist\*O " Lists cached tickets .LI "\*Lpasswd_export\*O " Updates local password and group files from DCE registry data .LI "\*Lpasswd_import\*O " Creates DCE registry entries based on password and group file entries .LI "\*Lpasswd_override\*O " Establishes DCE registry overrides for a principal on a local node .zA "enh,,R1.1,Added for pwd mgmt" .LI "\*Lpwd_strengthd\*O " Sample password management server .zZ "enh,,R1.1,Added for pwd mgmt" .LI "\*Lrgy_edit\*O " Edits the registry database .LI "\*Lsec_admin\*O " Administers the Security Server .zA "def,10220,R1.1,Remove reference to rpcd and sec_clientd" .zZ "def,10220,R1.1,Remove reference to rpcd and sec_clientd" .LI "\*Lsec_create_db\*O " Creates registry databases .LI "\*Lsecd\*O " The Security Server daemon .zA "def,6809,R1.0.2,add sec_salvage_db" .LI "\*Lsec_salvage_db\*O Reconstructs or recovers a registry database .zZ "def,6809,R1.0.2,add sec_salvage_db" .LI "\*Lsu\*O" Allows you to assume another user's identity. .zA "def,8628,R1.1,su is vendor-specifc" The implementation of this utility is platform-specific. Use the su utility supplied by your platform vendor. .zZ "def,8628,R1.1,su is vendor-specific" .LE .zZ "enh,5923,R1.1,move User's Guide & Ref pages to Admin Ref" .PP See the command's reference page for further information on each command. ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" Copyright (c) 1992 Hewlett-Packard Company ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" .rm zA .rm zZ .TH sec_salvage_db "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "Security Service commands" "\*Lsec_salvage_db\*O" .iX "registry database" "recovery" .SH NAME \*Lsec_salvage_db\*O - Recover a corrupted registry database .nS note The \*Lsec_salvage_db -check\*O and \*L-fix\*O options are not currently available. .nE .SH "SYNOPSIS" .PP .sS \*Lsec_salvage_db -print \*O[\*L-dbpath \*Vdb_pathname\*O] [\*L-prtpath \*Vprint_pathname\*O] .br [\*Vprint_options\*O] [\*L\-verbose\*O] [\*L-sort\*O] [\*L-dce1.0.3\*O] .sE .PP .sS \*Lsec_salvage_db \*L-reconstruct [\*L-dbpath \*Vdb_pathname\*O] [\*L-prtpath \*Vprint_pathname\*O] .br [\*Vreconstruct_options\*O] [\*L-verbose\*O] .sE .PP .sS \*Lsec_salvage_db -check \*O[\*L-dbpath \*Vdb_pathname\*O] [\*Vdb_options\*O] [\*L-verbose\*O] .sE .PP .sS \*Lsec_salvage_db -fix \*O[\*L-dbpath \*Vdb_pathname\*O] [\*Vdb_options\*O] [\*L-force\*O] [\*L-verbose\*O] .sE .SH "OPTIONS" .VL 1i .LI "\*L-check\*O" Check the database elements specified by \*Vdb_options\*O for inconsistencies. This option sends a list to standard output of all bad list links, internal id references, and database keys and any detectable data inconsistencies. The \*L-check\*O option does not check fields for legal values. .PP .LI "\*Vdb_options\*O" Specify the database elements to be acted on by the \*L-check\*O or \*L-fix\*O options. If no \*Vdb_options\*O are specified, all are selected. The \*Vdb_options\*O are .ML .LI \*L-princ\*O \(em Principals .LI \*L-group\*O \(em Groups .LI \*L -org\*O \(em Organizations .LI \*L-acct\*O \(em Accounts .LI \*L -acl\*O \(em ACLs .LI \*L-policy\*O \(em Policy .LI \*L-state\*O \(em Database State .LI \*L-replicas\*O \(em Replicas .LE .nS note The \*L.mkey.prt\*O file and the \*Lprinc.prt\*O file contain unencrypted authentication keys. Ensure that only the privileged account can access these files and that they are never transferred over a network for viewing or backup. .nE .LI "\*L-fix\*O Check the database for inconsistencies and prompt for whether to fix each inconsistency. After all inconsistencies have been processed, the option prompts for whether to save all fixes. .LI "\*L-force\*O" Check the database for inconsistencies and fix each one without prompting. After all inconsistencies have been processed, the option prompts for whether to save all fixes. This option is valid only when used with the \*L-fix\*O option. .LI "\*L-print\*O" Create files containing ASCII-formatted database records. These files are used by the \*L-reconstruct\*O option as a source for recreating the database. You can also manually edit the files to change information or fix problems. A separate file is created for each of the \*Vprint_options\*O specified. .PP By default the \*L-print\*O option stores the master key file in the current directory and the database files in the \*Lrgy_print\*O directory in the current directory. The \*L\-prtpath\*O option lets you specify a different directory. .LI "\*L-dce1.0.3\*O" Supports backwards conversion of a registry database from DCE 1.1 to DCE 1.0.3. .LI "\*Vprint_options\*O Specify the database elements to be acted on by the \*L-print\*O option. If the files exist, they are overwritten. If no \*Vprint_options\*O are specified, all are selected. The \*Vprint_options\*O and the files they create are .ML .LI \*L-princ\*O \(em Put principal records in the file \*Lprinc.prt\*O and master key information in the file \*L.mkey.prt\*O. .LI \*L-group\*O \(em Put group records in the file \*Lgroup.prt\*O. .LI \*L-org\*O \(em Put organization records in the file \*Lorg.prt\*O. .LI \*L-policy\*O \(em Put policy records in the file \*Lpolicy.pr\*Ot. .LI \*L-state\*O \(em Put information about the state of the database in the file \*Lrgy_state.prt\*O. .LI \*L-replicas\*O \(em Put replica information in the file \*Lreplicas.prt\*O. .LE .LI "\*L-reconstruct\*O" Reconstruct the registry database from the ASCII-formatted print files created by the \*L\-print\*O option. The \*Vreconstruct_options\*O specify the print files to use. .PP .LI \*Vreconstruct_options\*O .nS note The \*Vreconstruct_options\*O options are not available in Release 1.0.3. For this release, \*Lsec_salvage_db\*O reconstructs all elements of the registry database. .nE Specifies which elements of the registry database to reconstruct. If no \*Vreconstruct_options\*O are specified, all are selected. The \*Vreconstruct_options\*O are .ML .LI \*L-pgo\*O \(em Use data in the \*Lprinc.prt\*O,\*L group.prt\*O, \*Lorg.prt\*O, and \*L.mkey.prt\*O files to reconstruct: .ML .LI Principals, groups, organizations .LI Principal's accounts .LI ACL's on database objects .LI The master key file .LE .LI \*L-policy\*O \(em Use data from the \*Lpolicy.prt\*O file to reconstruct registry policies. .LI \*L-state\*O \(em Use data from the \*Lrgy_state.prt\*O file to reconstruct information about the state of the database. .LI \*L-replicas\*O \(em Use data from the \*Lreplicas.prt\*O file to reconstruct the master replica list. .LE .LI "\*L-dbpath \*Vdb_pathname\*O" For the \*L-print\*O and \*L-check\*O options, \*L-dbpath\*O specifies the directory in which the registry database and the master key file are located. For the \*L\-reconstruct\*O and \*L\-fix\*O options, \*L-dbpath\*O specifies the directory in which to store the reconstructed or salvaged database. .PP The \*L-print\*O and \*L-check\*O options expects to find the master key file, \*L.mkey\*O, in the directory above the directory that holds the database files. For example, if \*Vdb_pathname\*O is \*Vdcelocal\*L/var/security/new_rgy\*O, the options look for the master key file in \*Vdcelocal\*L/var/security\*O and the database files in \*Vdcelocal\*L/var/security/new_rgy\*O. .PP If this option is not specified, the default pathname is \*Vdcelocal\*L/var/security/rgy_data\*O. .PP \*Vdb_pathname\*O can be a global pathname or a cell-relative name. .PP .LI "\*L-prtpath \*Vprint_pathname\*O" For the \*Lprint\*O and \*L-reconstruct\*O options only, \*L-prtpath\*O specifies the directory in which to create (\*L-print\*O) the print files, or find (\*L-reconstruct\*O) the print files from which to reconstruct the database. .PP By default the \*L-print\*O option creates and the \*L-reconstruct\*O option looks for the master key file in the current directory and the database files in the \*Lrgy_print\*O subdirectory of the current directory. \*L-prtpath\*O lets you specify the directory that should be used instead of the current directory. For example, if you specify \*Vprint_pathname\*O as \*Vdcelocal\*O\*L/var/security/registry\*O, the master key print file will be created in that directory and the database print files in \*Vdcelocal\*O\*L/var/security/registry/rgy_print\*O. .PP If any or all of the print files exist in \*Vprint_pathname\*O or the default directory, their contents are overwritten. .PP \*Vprint_pathname\*O can be a global pathname or a cell-relative name. .LE .PP .SH "DESCRIPTION" .PP The \*Lsec_salvage_db\*O tool is an aid to database administration and troubleshooting. Although day-to-day administration is handled by the \*Lrgy_edit\*O command, \*Lsec_salvage_db\*O can be useful for listing registry data, reconstructing databases, and salvaging corrupted databases. .PP The \*Lsec_salvage_db\*O command supports two methods of operation: the check and fix method and the print and reconstruct method. These methods can be used in tandem. .PP .SS "Check and Fix Method" .PP .nS note The \*L-check\*O and \*L-fix\*O options are not currently available. .nE The check and fix method recovers data from a corrupted database, fixing corrupted data links, data retrieval keys, and other internal references. You can use it on a database so corrupted that it prevents the Security Server (\*Lsecd\*O) from running or registry clients from operating correctly. The check and fix method repairs the database structure so that \*Lsecd\*O can run. (Note that data may be lost if corrupted pointers in the registry data files irreversibly sever the links between records.) The check and fix method uses the \*Lsec_salvage_db\*O \*L-check\*O, \*L-fix\*O, and \*L-force\*O options. .PP The \*L-check\*O option accesses each record in the database and reports all errors, but makes no fixes. Although you can run it to see the state of the database before you run the \*L-fix\*O option, it is not required to be run. .PP The \*L-fix\*O option also accesses each record in the database and reports all errors, but as it finds each error, it prompts for whether or not to fix the error. When processing is complete, \*Lsec_salvage_db\*O prompts for whether or not to save the changes. .PP The \*L-force\*O option can only be used with the \*L-fix\*O option. If you use it, \*Lsec_salvage_db\*O does not prompt for confirmation before it fixes each error it finds. \*Lsec_salvage_db\*O will still prompt for confirmation before it saves the changes. .PP .SS "The Print and Reconstruct Method" .PP The print and reconstruct method allows you to reconstruct a database. It first creates ASCII files, called print files, that contain all accessible data in the database. Then, it reads the data in these files to construct a new database. If you cannot start a Security Server on the database host machine, you cannot use the print and reconstruct method, but must use the check and fix method. (Note that before you run \*Lsec_salvage_db\*O with the \*L\-print\*O and \*L\-reconstruct\*O options, you must stop the Security Server.) .PP In addition to reconstructing the database, the print and reconstruct method has other uses. You can use it to .ML .LI Make changes to the database by manually editing the print files created by the \*L-print\*O option and then reconstructing them from the changed print files. This can be especially useful for changing many user passwords, which may be necessary if the master key file is corrupted. ...\" or for re-adding data missing from a corrupted database. .LI Obtain a listing of database contents. .LI Copy databases between different platforms. .LE To use the print and reconstruct method run \*Lsec_salvage_db\*O first with the \*L-print\*O option and then with the \*L-reconstruct\*O option. .PP The \*L-print\*O option creates the ASCII print files from the registry database files. These files can be reviewed and edited to correct faulty information, such as name-to-UNIX ID mismatches or missing data, or to update existing data. The \*L-reconstruct\*O option recreates the registry database files from the print files. .PP Because the \*L-print\*O option creates files containing all data in the database and the \*L-reconstruct\*O option recreates the database based on these files, you can use this method to move a database to another machine or even another cell. For example, if you run \*Lsec_salvage_db -print\*O on an uncorrupted database, you can then run \*Lsec_salvage_db -reconstruct\*O and specify a pathname on a different machine for where the database should be created. .SS "Converting a DCE 1.1 Registry Database to a DCE 1.0.3 Database" The \*Lsec_salvage_db -dce1.0.3\*O option supports backwards conversion of a registry database from DCE 1.1 to DCE 1.0.3. To convert a DCE 1.1 registry database to a DCE 1.0.3 database perform the following procedure: .AL .LI Stop all DCE 1.1 servers. .LI Run the \*Lsec_salvage_db\*O command with the \*L-print\*O and \*L-dce1.0.3\*O options (and any other options you need) to create ASCII print files of the Registry database. .P Note that for polymorphous objects (that is, an object that can be both a directory and a person, group, or organization), \*Lsec_salvage_db\*O creates a print file entry for a directory as as default. It then stores the information related to the person, group, or organization in a file named \*Linfo.prt\*O. To recreate a person, group, or organization instead of a directory, manually add the information in the \*Linfo.prt\*O file to the appropriate ASCII print files. .LI Clean up the remnants of the Registry database by deleting the \*L/opt/dcelocal/var/rpc/rpcdep.dat\*O file and all files in the following directories: .ML .LI \*L/opt/dcelocal/var/security/rgy_data\*O .LI \*L/opt/dcelocal/var/security/rcache\*O .LI \*L/opt/dcelocal/var/security/creds\*O .LE .LI Reload the DCE 1.0.3 bits. .LI Run the \*Lsec_salvage_db\*O command with the \*L-reconstruct\*O option (and any other options you need) to create the database from the ASCII print files. .LI Restart DCE 1.0.3 servers. .LE .PP .SH "EDITING THE PRINT FILES" .PP To edit the print files, your entries must be in the following format .iS \*Vfield_name optional_white_space\*L=\*Voptional_white_space value\*O .iE Although you can leave spaces between the field name, the equals sign, and the value, field names and values cannot contain white space. .PP A sample \*Lorg.prt\*O file follows. .PP .iS Record_Number = 2 Object_Type = ORG Name = org/none UUID = 0000000C-D751-21CA-A002-08001E039D7D Unix_ID = 12 Is_Alias_Flag = false Is_Required_Flag = false Fullname = Member_Name = nobody Member_Name = root Member_Name = daemon Member_Name = uucp Member_Name = bin Member_Name = dce-ptgt Member_Name = dce-rgy Member_Name = krbtgt/abc.com Member_Name = hosts/zebra/self Obj_Acl_Def_Cell_Name = /.../abc.com Obj_Acl_Entry = unauthenticated:r-t----- Obj_Acl_Entry = user:root:rctDnfmM Obj_Acl_Entry = other_obj:r-t----- Obj_Acl_Entry = any_other:r-t----- .iE .PP ...\" .SS "Updating Entries" ...\" .PP To update existing entries, simply supply a new value. For example, to update a principal's full name, the entry in the \*Lprinc.prt\*O file is .iS \*LFullnsme = \*Vfullname\*O .iE .PP The \*Vfullname\*O variable is the principal's full name. The \*Lprinc.prt\*O file contains the following entry that allows you to update a principal's password in plain text: .iS \*LPlaintext_Passwd =\*O .iE .P This field does not display the principal's password. To update the password, simply enter the new one in plain text after the equals sign. When the database is reconstructed, the password is encrypted and any keys derived from that password are regenerated and used to overwrite any existing encryption key entries. .PP To specify a NULL value, delete the existing value. For example, to specify a NULL value for a fullname in the \*Lprinc.prt\*O file, the entry is .iS \*LFullname = .iE .PP ...\" .SS "Defining New Entries" ...\" In addition to editing the print files to update existing entries, you can ...\" add new database entries by adding them to the print file. ...\" .PP ...\" THEY WOULDN'T ADD RYG_STATE and REPLICAS WOULD THEY. ALSO WE DO NEED SOME ...\" GUIDELINES FOR WHICH FIELDS THEY SHOULD ENTER ...\" .PP ...\" When you add new entries, you must specify all the fields listed in the ...\" print file. However you are required to enter values only for those ...\" fields that are required. The other will either default to a value or ...\" contain a NULL value, depending on the field. (The tables of print file ...\" fields later in this reference page describe each field and whether it is ...\" required.) ...\" .PP .PP .SH "PRINT FILE FIELDS AND VALUES" .PP The fields in the \*Lprinc.prt\*O, \*Lgroup.prt,\*O \*Lorg.prt\*O, \*L.mkey.prt\*O, \*Lpolicy.prt\*O, \*Lrgy_state.prt\*O and \*Lreplicas.prt\*O files are described in the following tables. .PP .ne 2i .TB "princ.prt File Fields" .PP .TS center,tab(@); |lB | lB| |l | lw(4.0i)|. _ Field Name@Field Values _ \*LFor all Records:\*O _ _ Record_Number@T{ The sequential number of the record in the database. T} _ Object_Type@T{ An indication of the type of object: \*LPRINC\*O=principal, \*LDIR\*O=directory. T} _ Name@T{ Name of the object. T} _ UUID@T{ Unique Identifier of the object. T} _ \*LFor Principals:\*O _ _ Unix_ID@T{ The principal's Unix ID. T} _ Is_Alias_Flag@T{ An indication of whether or not the principal name is an alias or a primary name: \*Ltrue\*O=alias, \*Lfalse\*O=primary. T} _ Is_Required_Flag@T{ An indication of whether or not the principal is reserved: \*Ltrue\*O=principal is reserved and cannot be deleted, \*Lfalse\*O=principal is not reserved. T} _ Quota@T{ The principal's object creation quota: a non-negative integer or \*Lunlimited\*O. T} _ Fullname@T{ The principal's fullname: a text string. T} _ Member_Name*@T{ The names of the groups to which the principal belongs. T} _ Obj_Acl_Def_Cell_Name@T{ The default cell name of this principal's object ACL. T} _ Num_Acl_Entries@T{ The number of entries in the principals object ACL. T} _ Obj_Acl_Entry*+@T{ The contents of the principal's object ACL. T} _ Acct_Group_Name@T{ The account's group name. T} _ Acct_Org_Name@T{ The account's organization name. T} _ Acct_Creator_Name@T{ The name of principal who created this account. T} _ \*OAcct_Creation_Time@T{ \*OThe date and time the account was created in \*Vyyyy/mm/dd.hh:mm\*O format. The first two digits of the year, the hours, and the minutes are optional. T} _ Acct_Changer_Name@T{ Name of principal who last changed the account. T} _ Acct_Change_Time@T{ The date and time the account was last changed in \*Vyyyy/mm/dd.hh:mm\*O format. (The first two digits of the year, the hours and the minutes are optional.) T} _ Acct_Expire_Time@T{ The date and time the account expires or \*Lnone\*O for no expiration date. The date and time are in \*Vyyyy/mm/dd.hh:mm\*O format. (The first two digits of the year, the hours and the minutes are optional.) T} _ Acct_Good_Since_Time@T{ The date and time the principal's account was last known to be in an uncompromised state in \*Vyyyy/mm/dd.hh:mm\*O, format or \*Lno\*O for current time and date. (The first two digits of the year, the hours and the minutes are optional.) T} _ Acct_Valid_For_Login_Flag@T{ An indication of whether or not the account can be logged into: \*Ltrue\*O=account is valid for login, \*Lfalse\*O=account cannot be logged into. T} _ .TE .PP .ne 8i .TS center,tab(@); |l | lw(4.0i)|. _ Acct_Valid_As_Server_Flag@T{ Indicates whether or not the account is a server and can engage in authenticated communication: \*Ltrue\*O=account is a server, \*Lfalse\*O=account is not server. T} _ Acct_Valid_As_Client_Flag@T{ Indicates whether or not the account is a client and can log in, acquire tickets, and be authenticated: \*Ltrue\*O=account is a client, \*Lfals\*Oe=account is not a client. T} _ Acct_Post_Dated_Cert_Ok_Flag@T{ Indicates whether or not tickets with a start time some time in the future can be issued to the account's principal: \*Ltrue\*O=postdated tickets can be issued, \*Lfalse\*O=postdated tickets cannot be issued. T} _ Acct_Forwardable_Cert_Ok_Flag@T{ Indicates whether or not a new ticket-granting ticket with a network address that differs from the present ticket-granting address can be issued to the account's principal: \*Ltrue\*O=account can get forwardable certificates, \*Lfalse\*O=account cannot. T} _ Acct_TGT_Auth_Cert_Ok_Flag@T{ Indicates whether or not tickets issued to the account's principal can use the ticket-granting-ticket authentication mechanism: \*Ltrue\*O=tickets can use the ticket-granting-ticket authentication mechanism, \*Lfalse\*O=they cannot. T} _ Acct_Renewable_Cert_Ok_Flag@T{ Indicates whether or not tickets issued to the principal's ticket-granting ticket to be renewed: \*Ltrue\*O=tickets can be renewed, \*Lfalse\*O=tickets cannot be renewed. T} _ \*OAcct_Proxiable_Cert_Ok_Flag@T{ \*OIndicates whether or not a new ticket with a different network address than the present ticket can be issued to the account's principal: \*Ltrue\*O=such a ticket can be issued, \*Lfalse\*O=such a ticket cannot be issued. T} _ Acct_Dup_Session_Key_Ok_Flag@T{ Indicates whether or not tickets issued to the account's principal can have duplicate keys: \*Ltrue\*O=account can have duplicate session keys, \*Lfalse\*O=account cannot. T} _ Unix_Key@T{ The account principal's encrypted UNIX password: ASCII string. T} _ Plaintext_Passwd@T{ Stores the principal's password in plain text. This field is provided to allow principal's passwords to be changed. When the \*Lprinc.prt\*O file is processed by the \*Lsec_salvage_db -reconstruct\*O option, this password is encrypted using UNIX system encryption. This encrypted password is then stored as the principal's encrypted UNIX password in the \*LUnix_Key\*O field. T} _ Home_Dir@T{ The account principal's home directory: text string. T} _ Shell@T{ The account principal's login shell: text string. T} _ Gecos@T{ The account's GECOS information: text string. T} _ Passwd_Valid_Flag@T{ Indicates whether or not the account principal's password is valid: \*Ltrue\*O=password is valid, \*Lfalse=\*Opassword not valid. T} _ .TE .PP .ne 8i .TS center,tab(@); |l | lw(4.0i)|. _ Passwd_Change_Time@T{ The date and time the account principal's password was last changed in \*Vyyyy/mm/dd.hh:mm\*O format or \*Lnow\*O for the current date and time. The first two digits of the year, the hours and the minutes are optional. T} _ Max_Certificate_Lifetime@T{ The number of hours before the Authentication Service must renew the account principal's service certificates: an integer indicating the time in hours or \*Ldefault-policy\*O to use the registry default. T} _ Max_Renewable_Lifetime@T{ The number of hours before a session with the account principal's identity expires and the principal must log in again to reauthenticate: an integer indicating the time in hours or \*Ldefault-policy\*O to use the registry default. T} _ Master_Key_Version@T{ The version of the master key used to encrypt the account principal's key. T} _ Num_Auth_Keys@T{ The number of the account principal's authentication keys. T} _ Auth_Key_Version*@T{ A list of the version numbers of the account principal's authentication key. The first version number on the list represents the current authentication key. T} _ Auth_Key_Pepper*@T{ The pepper algorithm used for the account principal's key: a text string or blank to use the default pepper algorithm. T} _ Auth_Key_Len*@T{ The length in bytes of the account principal's authentication key. T} _ Auth_Key*@T{ The account principal's authentication key: hex string. T} _ Auth_Key_Expire_Time*@T{ The date and time the account principal's authentication key expires or \*Lnone\*O for no expiration. Date and time are in \*Vyyyy/mm/dd.hh:mm\*O format. (The first two digits of the year, the hours and the minutes are optional.) T} _ _ \*LFor Directories:\*O _ _ \*OObj_Acl_Def_Cell_Name+@T{ The default cell name of the directory's object ACL. T} _ Num_Acl_Entries@T{ The number of entries in the directory's object ACL. T} _ Obj_Acl_Entry*+@T{ The contents of the directory's object ACL. T} _ Init_Obj_Acl_Def_Cell_Name+@T{ The default cell name of the directory's initial object ACL. T} _ Num_Acl_Entries@T{ The number of entries in the directory's initial object ACL. T} _ Init_Obj_Acl_Entry*+@T{ The contents of the directory's initial object ACL. T} _ Init_Cont_Acl_Def_Cell_Name+@T{ The default cell name of the directory's initial container ACL. T} _ Num_Acl_Entries@T{ The number of entries in the directory's initial container ACL. T} _ Init_Cont_Acl_Entry*+@T{ The contents of the directory's initial container ACL. T} _ .TE .PP * These segments/fields may appear multiple times in succession. .PP + If a stored UUID doesn't map to a name required for this field, the UUID will be displayed. .PP .ne 6.5i .TB "group.prt File Fields" .PP .TS center,tab(@); |lB | lB| |l | lw(4.0i)|. _ Field Name@Field Values _ \*LFor all Records:\*O _ _ Record_Number@T{ The sequential number of the record in the database. T} _ Object_Type@T{ An indication of the type of object: \*LGROUP\*O=group, \*LDIR\*O=directory. T} _ Name@T{ Name of the object. T} _ UUID@T{ Unique Identifier of the object. T} _ \*LFor Groups:\*O _ _ Unix_ID@T{ Unix ID of the group. T} _ Is_Alias_Flag@T{ An indication of whether or not the group name is an alias or a primary name: \*Ltrue\*O=alias, \*Lfalse\*O=primary . T} _ Is_Required_Flag@T{ An indication of whether or not the group is reserved: \*Ltrue\*O=group is reserved and cannot be deleted, \*Lfalse\*O=group is not reserved. T} _ Projlist_Ok_Flag@T{ An indication of whether or not the group can be included in project lists: \*Ltrue\*O=group can be included on project lists, \*Lfalse\*O=group cannot be included. T} _ Fullname@T{ The group's fullname: a text string. T} _ Member_Name*@T{ The names of the group's members. T} _ Obj_Acl_Def_Cell_Name+@T{ The default cell name of this group's object ACL. T} _ Num_Acl_Entries@T{ The number of entries in the group's object ACL. T} _ Obj_Acl_Entry*@T{ The contents of the group's object ACL. T} _ \*LFor Directories:\*O _ _ Obj_Acl_Def_Cell_Name+@T{ The default cell name of this directory's object ACL. T} _ Num_Acl_Entries@T{ The number of entries in the directory's object ACL. T} _ Obj_Acl_Entry*@T{ The contents of the directory's object ACL. T} _ Init_Obj_Acl_Def_Cell_Name+@T{ The default cell name of the directory's initial object ACL. T} _ Num_Acl_Entries@T{ The number of entries in the directory's initial object ACL. T} _ Init_Obj_Acl_Entry*+@T{ The contents of the directory's initial object ACL. T} _ Init_Cont_Acl_Def_Cell_Name+@T{ The default cell name of the directory's initial container ACL. T} _ Num_Acl_Entries@T{ The number of entries in the directory's initial container ACL. T} _ Init_Cont_Acl_Entry*+@T{ The contents of the directory's initial container ACL. T} _ .TE .PP * These fields may appear multiple times in succession. .PP + If a stored UUID doesn't map to a name required for this field, the UUID will be displayed. .PP .ne 8i .TB "org.prt File Fields" .PP .TS center,tab(@); |lB | lB| |l | lw(4.0i)|. _ Field Name@Field Values _ \*LFor all Records:\*O _ _ Record_Number@T{ The sequential number of the record in the database. T} _ Object_Type@T{ An indication of the type of object: \*LORG\*O=organization, \*LDIR\*O=directory. T} _ Name@T{ Name of the object. T} _ UUID@T{ Unique Identifier of the object. T} _ \*LFor Organizations:\*O _ _ Unix_ID@T{ Unix Id of the organization. T} _ Is_Alias_Flag@T{ An indication of whether or not the organization is an alias or a primary name: \*Ltrue\*O=alias, \*Lfalse\*O=primary. T} _ Is_Required_Flag@T{ An indication of whether or not the organization is reserved: \*Ltrue\*O=organization is reserved and cannot be deleted, \*Lfalse\*O=organization is not reserved. T} _ Fullname@T{ The organization's fullname: a text string. T} _ Member_Name*@T{ The names of the organization's members. T} _ Obj_Acl_Def_Cell_Name@T{ The default cell name of this organization's object ACL. T} _ Num_Acl_Entries@T{ The number of entries in the organization's object ACL. T} _ Obj_Acl_Entry*+@T{ The contents of the organization's object ACL. T} _ \*LFor Organizations with Policy:\*O _ _ Acct_Lifetime@T{ The period during which accounts for the organization are valid: a integer number representing days or \*Lforever\*O. T} _ Passwd_Min_Len@T{ The minimum length of the organization's password: a non-negative integer. T} _ Passwd_Lifetime@T{ The span in days of the lifetime of the organization's password: an integer or \*Lforever\*O. T} _ Passwd_Expire_Time@T{ The date and time the organization's password expires in \*Vyyyy/mm/dd.hh:mm\*O format. (The first two digits of the year, the hours and the minutes are optional.) T} _ Passwd_All_Spaces_Ok@T{ An indication of whether or not the organization's password can consist of all spaces: \*Ltrue\*O=can consist of spaces, \*Lfalse\*O=cannot. T} _ Passwd_All_Alphanumeric_Ok@T{ An indication of whether or not the organization's password can consist of all alphanumeric characters: \*Ltrue\*O=can be all alphanumeric, \*Lfalse\*O=cannot. T} _ \*LFor Directories:\*O _ _ Obj_Acl_Def_Cell_Name+@T{ The default cell name of the directory's object ACL. T} _ Num_Acl_Entries@T{ The number of entries in the directory's object ACL. T} _ Obj_Acl_Entry*+@T{ The contents of the directory's object ACL. T} _ Init_Obj_Acl_Def_Cell_Name+@T{ The default cell name of the directory's initial object ACL. T} _ Num_Acl_Entries@T{ The number of entries in the directory's initial object ACL. T} _ .TE .PP .ne 1.5i .TS center,tab(@); |lB | lB| |l | lw(4.0i)|. _ \*OInit_Obj_Acl_Entry*+@T{ \*OThe contents of the directory's initial object ACL. T} _ Init_Cont_Acl_Def_Cell_Name+@T{ The default cell name of the directory's initial container ACL. T} _ Num_Acl_Entries@T{ The number of entries in the directory's initial container ACL. T} _ Init_Cont_Acl_Entry*+@T{ The contents of the directory's initial container ACL. T} _ .TE .PP * These fields may appear multiple times in succession. .PP + If a stored UUID doesn't map to a name required for this field, the UUID will be displayed. .PP .ne 2i .TB ".mkey.prt File Fields" .TS center,tab(@); |lB | lB| |l | lw(4.0i)|. _ Field Name@Field Values _ Master_Key_Version@T{ The integer version of the master key. T} _ Master_Key_Keytype@T{ Always \*Ldes\*O. T} _ Master_Key_Length@T{ The length of the master key in bytes. T} _ Master_Key@T{ The master key in hex string format. T} _ .TE .PP .ne 5.5i .TB "policy.prt File Fields" .PP .TS center,tab(@); |lB | lB| |l | lw(4.0i)|. _ Field Name@Field Values _ Rgy_Policy_File_Version@T{ An integer representing the version of the policy information. T} _ Prop_Read_Version@T{ A number indicating the property record's read version. T} _ Prop_Write_Version@T{ A number indicating the property record's write version. T} _ Min_Certificate_Lifetime@T{ The minimum amount of time before the principal's ticket must be renewed in \*Vweeks\*Lw\*Vdays\*Ld\*Vhours\*Lh\*Vminutes\*Lm\*O format. T} _ Default_Certificate_Lifetime@T{ The the default lifetime for tickets issued to principals in this cell's registry in \*Vweeks\*Lw\*Vdays\*Ld\*Vhours\*Lh\*Vminutes\*Lm\*O format. T} _ Low_Unix_ID_Principal@T{ The starting point for principal UNIX IDs automatically generated by the Security Service when a principal is added: an integer, which must be less than Max_Unix_ID. T} _ Low_Unix_ID_Group@T{ The the starting point for UNIX IDs automatically generated by the Security Service when a group is added: an integer, which must be less than Max_Unix_ID. T} _ Low_Unix_ID_Org@T{ The starting point for UNIX IDs automatically generated by the Security Service when an organization is added using: an integer, which must be less than Max_Unix_ID. T} _ Max_Unix_ID@T{ The highest number that can be supplied as a UNIX ID when principals are created: an integer. T} _ Rgy_Readonly_Flag@T{ An indication of whether or not the registry is read-only: \*Ltrue\*O=read only, \*Lfalse\*O=updateable. T} _ Auth_Certificate_Unbound_Flag@T{ An indication of whether or not certificates are generated for use on any machine: \*Ltrue\*O=yes, \*Lfalse\*O=no. T} _ Shadow_Passwd_Flag@T{ Determines whether encrypted passwords are sent over the network: \*Ltrue\*O=encrypted passwords are not sent over the network, \*Lfalse\*O=encrypted passwords are sent over the network. T} _ Embedded_Unix_ID_Flag@T{ Determines if UNIX IDs are embedded in person, group, and organization UUIDs: \*Ltrue\*O=UNIX IDs are embedded, \*Lfalse\*O=UNIX IDs are not embedded. T} _ .TE .PP .ne 6.25i .TS center,tab(@); |l | lw(4.0i)|. _ Realm_Name@T{ The name of the full global pathname of realm running the \*Lsecd\*O. T} _ Realm_UUID@T{ The UUID of the realm running the \*Lsecd\*O. T} _ Unauthenticated_Quota@T{ The quota of unauthenticated users: a number or \*Lunlimited\*O. T} _ Acct_Lifetime@T{ The period during which accounts are valid: a integer number representing days or \*Lforever\*O. T} _ \*OPasswd_Min_Len@T{ \*OThe minimum length of passwords: a non-negative integer. T} _ Passwd_Lifetime@T{ The span in days of the password lifetimes: an integer or \*Lforever\*O. T} _ Passwd_Expire_Time@T{ The date and time the passwords expire in \*Vyyyy/mm/dd.hh:mm\*O format. (The first two digits of the year, the hours and the minutes are optional.) T} _ Passwd_All_Spaces_Ok@T{ An indication of whether or not passwords can consist of all spaces: \*Ltrue\*O=can consist of spaces, \*Lfalse\*O=cannot. T} _ Passwd_All_Alphanumeric_Ok@T{ Am indication of whether or not passwords can consist of all alphanumeric characters: \*Ltrue\*O=can be all alphanumeric, \*Lfalse\*O=cannot. T} _ Max_Certificate_Lifetime@T{ The number of hours before the Authentication Service must renew service certificates: an integer indicating the time in hours or \*Ldefault-policy\*O to use the registry default. T} _ Max_Renewable_Lifetime@T{ The number of hours before sessions expire and the session principal must log in again to reauthenticate: an integer indicating the time in hours or \*Ldefault-policy\*O to use the registry default. T} _ Princ_Cache_State@T{ The timestamp of the principal cache. T} _ Group_Cache_State@T{ The timestamp of the group cache. T} _ Org_Cache_State@T{ The timestamp of the organization cache. T} _ My_Name@T{ The cell-relative name of the security server. T} _ Master_Key_Version@T{ The integer version of current master key. T} _ Master_Key_Keytype@T{ Always \*Ldes\*O. T} _ Master_Key_Length@T{ The length of the master key in bytes. T} _ Master_Key@T{ The master key in hex string format. T} _ Old_Master_Key_Version@T{ The version of the previous master key. T} _ Old_Master_Key_Keytype@T{ Always \*Ldes\*O. T} _ Old_Master_Key_Length@T{ The length of the previous master key in bytes. T} _ Old_Master_Key@T{ The previous master key in hex string format. T} _ Obj_Acl_Def_Cell_Name@T{ The default cell name of the policy object ACL. T} _ Num_Acl_Entries@T{ The number of entries in the policy object ACL. T} _ Obj_Acl_Entry*+@T{ The contents of the policy object ACL. T} _ .TE .PP * These fields may appear multiple times in succession. .PP + If a stored UUID doesn't map to a name required for this field, the UUID will be displayed. .PP .ne 3.5i .TB "rgy_state.prt File Fields" .PP .TS center,tab(@); |lB | lB| |l | lw(4.0i)|. _ Field Name@Field Values _ Rgy_State_File_Version@T{ The integer version number of the format of the \*Lrgy_state\*O file. T} _ Replica_State@T{ The state of the master registry: \*Lunknown_to_master\*O, \*Luninitialized\*O, \*Lin_service\*O, \*Lin_maintenance\*O, \*Lclosed\*O, \*Ldeleted\*O, or \*Linitializing\*O. T} _ Cell_UUID@T{ The UUID of cell in which the \*Lsecd\*O resides. T} _ Server_UUID@T{ The UUID of this \*Lsecd\*O. T} _ Initialization_UUID@T{ The UUID of the last initialization event. T} _ Master_File_Version@T{ The version number of the master replica. T} _ Master_Known_Flag@T{ An indicate of whether or not the master replica is know to this replica: \*Ltrue\*O=known, \*Lfalse\*O=not known. Only if this field is \*Ltrue\*O do the other master field contain valid information. T} _ Master_UUID@T{ The UUID of the master replica. T} _ Master_Seqno@T{ The 2-digit sequence number of the event when the master became the master in \*vn\*L.\*Vn\*O format. T} _ .TE .PP .ne 2.5i .TB "replica.prt File Fields" .PP .TS center,tab(@); |lB | lB| |l | lw(4.0i)|. _ Field Name@Field Values _ Record_Number@T{ The sequential number of the record in the database. T} _ Replica_UUID@T{ The UUID listed for the replica in the replica list. T} _ Replica_Name@T{ The name of the replica as known to the Cell Directory Service. T} _ Num_Towers@T{ The number of towers. T} _ Tower_Length*@T{ The Length of the next tower (in bytes). T} _ Tower*@T{ The tower used to communicate with the replica (a byte stream that can be broken on word boundaries). T} _ Propagation_Type@T{ An indication of whether the replica is initialized, initializing, in the process of being updated, or in the process of being deleted. T} _ Initialization_UUID@T{ UUID of the last initialization. T} _ .TE .PP * These fields may appear multiple times in succession. .PP .SH "NOTES" This reference page is the version that was included in the DCE 1.0.3 Command Reference, updated with information about the \*L-dce1.0.3\*O option. It is \*Enot\*O guaranteed to correspond exactly to the DCE 1.1 usage. .SH "ERROR CONDITIONS" .PP You will receive the following error message if the default \*Lrgy_data\*O directory is being used and there is an advisory lock on the \*Lrgy_state\*O data file: .iS \*CRegistry: Error - database is locked. Put secd into maintenance mode or clear advisory lock on rgy_state file in \*Vdb_pathname\*O .iE .PP The existence of the advisory lock implies that \*Lsecd\*O is in service. Use the \*Lsec_admin\*O command to put \*Lsecd\*O in maintenance mode. If \*Lsecd\*O is not running, the advisory lock may be the result of an ungraceful shutdown of \*Lsecd\*O. To remove the advisory lock, use \*Lmv\*O to rename the \*Vdcelocal\*L/var/security/rgy_data/rgy_state\*O file, change it back to the original name. Then, re-run the \*Lsec_salvage_db\*O command. ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\"Copyright Hewlett-Packard Company 1991 ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" .rm zA .rm zZ .TH secd "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "Security Servers" "about" .iX "-[" "Security Service commands" "\*Lsecd\*O" .SH NAME \*Lsecd\*O - The DCE Security Server .SH "SYNOPSIS" .zA "enh,10970,R1.1,add -master_seqno and -cpi" .zA "def,7274,R1.0.2,add -restore_master" .zA "defect,6211,R1.0.3,remove full path in SYNOPSIS" .sS \*Lsecd\*O [\*L-b\*O[\*Lootstrap\*O]] [\*L-lockpw\*O] [\*L-locksm\*O[\*Lith]]\*O [\*Vpname\*O] [\*L-rem\*O[\*Lote\*O]] .br [\*L-master_seqno \*Vnew_master_seqno\*O] [\*L-cpi\*V time\*O] [\*L-restore_master\*O] .br [\*L-noaudfilter\*O] [\*L-v\*O[\*Lerbose\*O]] .sE .zZ "defect,6211,R1.0.3,remove full path in SYNOPSIS" .zZ "def,7274,R1.0.2,add -restore_master" .zZ "enh,10970,R1.1,add -master_seqno and -cpi" .SH "OPTIONS" .VL 1i .zA "enh,6199,R1.0.2,can only be used on master" .LI "\*L-locksm[ith]\*O Restarts the master Security Server in locksmith mode. Use this mode if you cannot access the registry as the principal with full registry access, because that principal's account has been inadvertently deleted or its password lost. .zZ "enh,6619,R1.0.2,add -master and -slave" .LI "\*Vpname\*O" The \*Vpname\*O argument is the name of the locksmith principal. If no registry account exists for this principal, \*Lsecd\*O creates one. .LI "\*L-lockpw\*O" Prompt for a new locksmith password when running in locksmith mode. This option allows you to specify a new password for the locksmith account when the old one is unknown. .LI "\*L-rem[ote]\*O" Allows the locksmith principal to log in remotely. If this option is not used, the principal must log in from the local machine on which \*Lsecd\*O will be started. .ne 2i .LI "\*L-bo[otstrap]\*O" Always waits only one minute between tries to export binding information to the Cell Directory Service during DCE configuration. If you do not specify this option, during initialization \*Lsecd\*O sleeps for 1 minute if CDS is not available when it tries to export binding information. If the export fails a second time, it sleeps for 2 minutes before it tries again. If it still fails, it sleeps for 4, 8, and 16 minutes between retries. Then, sleep time stays at 16 minutes until the binding export succeeds. .zA "enh,10970,R1.1,add -master_seqno and -cpi" .LI "\*L-master_seqno\*O" Sets a new master sequence number for the master replica. This option is used only in unusual situations when a replica that you want to be the master has a master sequence number that is lower than (or equal to) another master sequence number in the system. When the master detects that its master sequence number is lower than another one in the system, it marks itself as a duplicate master and its process exits. Each time you start the master replica, it will notice that it has been deemed a duplicate master, and its process will again exit. Use this option to assign a new master sequence number to the replica you want to be master. The new sequence number should be one digit higher than the highest master sequence number in the system. (Use the \*Ldcecp registry show -replica\*O command for each replica to find the highest master sequence number.) .LI "\*L-cpi\*O" The checkpoint interval for the master registry database. This is the interval in seconds at which the master will read its database to disk. The default is one hour. .zZ "enh,10970,R1.1,add -master_seqno and -cpi" .zA "def,7274,R1.0.2,add -restore_master" .LI "\*L-restore_master\*O" Marks all slave replicas for initialization during the master restart. Use this option only to recover from a catastrophic failure of the master security server (for example, if the database is corrupted and then restored from a backup tape). .zZ "def,7274,R1.0.2,add -restore_master" .LI "\*L-noaudfilter\*O" Disables audit filtering and enables full (unfiltered) auditing. By default \*Lsecd\*O turns audit filtering on. .LI "\*L-v[erbose]\*O" Runs in verbose mode. .LE .P All options start the Security Server on the local node. .SH "DESCRIPTION" .PP The \*Lsecd\*O daemon is the Security Server. It manages all access to the registry database. You must have root privileges to invoke the \*Lsecd\*O. .PP The Security Server can be replicated, so that several copies of the registry database exist on a network, each managed by a \*Lsecd\*O process. Only one Security Server, the master replica, can perform database update operations (such as adding an account). Other servers, the slave replicas, can perform only lookup operations (such as validating a login attempt). .PP .zA "def,7274,R1.0.2,add slaves need sec_clientd" .zA "def,10220,R1.1,Remove reference to rpcd and sec_clientd" A DCE Host daemon (\*Ldced\*O) must be running on the local node when \*Lsecd\*O is started. ...\" and nodes used as a slave replica must run \*Lsec_clientd\*O. Typically, \*Ldced\*O and \*Lsecd\*O ...\", and \*Lsec_clientd\*O are started at boot time. .zZ "def,10220,R1.1,Remove reference to rpcd and sec_clientd" .zZ "def,7274,R1.0.2,add slaves need sec_clientd" The \*Lsecd\*O server places itself in the background when it is ready to service requests. .zA "enh,6619,R1.0.2,locksmith only for master" .SS "Locksmith Mode" .PP .iX "locksmith mode" The \*Lsecd\*O \*L-locksmith\*O option starts \*Lsecd\*O in locksmith mode. The \*L-locksmith\*O option can be used only with the master replica. In locksmith mode, the principal name you specify to \*Lsecd\*O with \*Vpname\*O becomes the locksmith principal. As the locksmith principal, you can repair malicious or accidental changes that prevent you from logging in with full registry access privileges. .zZ "enh,6619,R1.0.2,locksmith only for master" .PP If no account exists for \*Vpname\*L, \*Lsecd\*O establishes one and prompts you for the account's password. (Use this password when you log in to the account as the locksmith principal.) If an account for \*Vpname\*O exists, \*Lsecd\*O changes the account and policy information as described in the tables titled "Locksmith Account Changes Made by the Security Server" and "Registry Policy Changes Made by the Security Server." These changes ensure that even if account or registry policy was tampered with, you will now be able to log in to the locksmith account. .PP In locksmith mode, all principals with valid accounts can log in and operate on the registry with normal access checking. The locksmith principal, however, is granted special access to the registry: no access checking is performed for the authenticated locksmith principal. This means that, as the locksmith principal, you can operate on the registry with full access. .TB "Locksmith Account Changes Made by the Security Server" .TS center,box,tab(@); lB | lB l | l. If the Security Server finds@It changes _ Password-Valid flag is set to no@Password-Valid flag to yes _ T{ Account Expiration date is set to less than the current time plus one hour T}@T{ Account Expiration date to the current time plus one hour T} _ Client flag is set to no@Client flag to yes _ Account-Valid flag is set to no@Account-Valid flag to yes _ Good Since date is set to greater than the current time@Good Since date to the current time _ T{ Password Expiration date is set to less than current time plus one hour T}@T{ Password Expiration date to the current time plus one hour T} .TE .ne 2i .PP .TB "Registry Policy Changes Made by the Security Server" .TS center,box,tab(@); lB | lB l | l. If the Security Server finds@It changes _ T{ Account Lifespan is set to less than the difference between the locksmith account creation date and the current time plus one hour T}@T{ Account Lifespan to the current time plus one hour minus the locksmith account creation date T} _ T{ Password Expiration date is set to greater than the time the password was last changed but less than the current time plus one hour T}@T{ Password Expiration date to the current time plus one hour T} .TE .PP Use the \*L-lockpw\*O option if the locksmith account exists but you do not know its password. This option causes \*Lsecd\*O to prompt for a new locksmith password and replace the existing password with the one entered. .PP Use the \*L-remote\*O option to allow the locksmith principal to log in from a remote machine. .PP The \*Lsecd\*O program normally runs in the background. When you start \*Lsecd\*O in locksmith mode, it runs in the foreground so that you can answer prompts. .SH "EXAMPLES" .PP All of the commands shown in the following examples must be run by root: .AL .LI Start a Security Server after you create the database with \*Lsec_create_db\*O. .iS \*C$\*O \*Vdcelocal\*L/bin/secd\*O .iE .zA "def,7274,R1.0.2,deleted example" ...\" .LI ...\" Start a slave replica on a node for the first time. ...\" .iS ...\" \*C$\*O \*Vdcelocal\*L/bin/secd -create\*O ...\" .iE .zZ "def,7274,R1.0.2,deleted example" .LI Restart an existing replica (master or slave). .iS \*C$\*O \*Vdcelocal\*L/bin/secd\*O .iE .LI Start the Security Server in locksmith mode and allow the \*Lmaster_admin\*O principal to log in on a remote machine. .iS \*C$\*O \*Vdcelocal\*L/bin/secd -locksmith master_admin -remote\*O .iE .LE ...\" .DD "secd(.8) \ ...\" network registry server daemon \ .iX "-]" "Security Servers" "about" .iX "-]" "Security Service commands" "\*Lsecd\*O" .\" $Header: see.1m,v 1.2 95/12/15 11:34:55 hmgr Exp $ .TA s .TH see 1m .SH NAME see \- access bytes in the HP SCSI disk array controller EEPROM .SH SYNOPSIS .C see -d special .PP .C see .C -b .I byte_number .C -h .I hex_byte .I device_file .SH DESCRIPTION .CR see displays, or changes bytes in the controller EEPROM of the HP SCSI disk array associated with device file .IR device_file . A 64-byte area in the EEPROM is accessible to the user. Although the command is directed to a single LUN, the EEPROM settings affect all the LUNs of the device. .SS Options .RS .TP 16 .C -d Display only. Displays the current values of the bytes in the accessible portion of the EEPROM. .TP .CI -b\ byte_number\ -v\ hex_byte Loads the hexadecimal value .CR hex_byte into the decimal byte .CR byte_number of the user accessible 64-byte region in the EEPROM. .SH BYTE DESCRIPTION The following list of user accessible bytes in the EEPROM, and their default values is provided for informational purposes only. Changing the values can result in "incorrect" controller behavior with respect to HP SCSI disk array utilities, and other support software. See WARNINGS. .PP .TS box, center; r l c c. byte meaning C2425/7 value C2430 value 0 enable synchronous negotiation 0x00 0x00 1 enable wide negotiation 0x00 0x00 2 spin-up algorithm 0x01 0x01 3 spin-up delay 0x32 0x1e 4 ready timeout 0x0a 0x17 5 host command delay at power on 0x00 0x00 6 firmware drive cmd timeout value 0x64 0x64 7 default RAID level 0x00 0x05 8 option control bits MSB 0x00 0x00 9 option control bits LSB 0x27 0x53 10 sense key for drive failures 0x06 0x06 11 inquiry data byte 7 0x12 0x32 12 ROM sequence control bits 0x01 0x01 13 synchronization control bits 0x02 0x02 14 inquiry revision level format 0x00 0x00 15 diagnostic self-test options 0x01 0x01 16 host command delay for bus reset 0x00 0x00 17 inquiry unconfigured device type 0x20 0x20 18 software command timeout value 0x14 0x14 19 software command timeout actions 0x07 0x07 20 drive bus reset to ready wait 0x08 0x08 21 host delay after data phase 0x00 0x00 22 drive scan disabled channel (MSB) 0x00 0x00 23 drive scan disabled channel (LSB) 0x00 0x00 24 time to asynchronous event 0x00 0x00 25 fan polling interval 0x00 0x00 26 power supply polling interval 0x00 0x00 27 reserved 0x00 0x00 28 Error Reporting Options (MSB) 0x01 0x01 29 Error Reporting Options (LSB) 0x00 0x00 30-63 reserved 0x00 0x00 .TE .SH RETURN VALUE .CR see returns the following values: .RS 5 .TP .C " 0" Successful completion. .PD 0 .TP .C -1 Command failed (an error occurred). .PD .PP .RE .SH DIAGNOSTICS AND ERRORS Errors can originate from problems with: .RS .TP 3 \(bu .C see .TP \(bu SCSI (device level) communications .TP \(bu system calls .RE .PP .SS Error messages generated by see: .TP .C "usage: see <-d | -b -v > " An error in command syntax has occurred. Re-enter command with the required arguments, in the order shown. .TP .C "see: Arg out of range" One of the arguments has exceeded its maximum or minimum size, or is incorrect in form. Check the size and form of each argument. .TP .C "see: device busy" .tr ~" To ensure that .CR see does not modify a disk array that is being used by another process, .CR see attempts to obtain exclusive access to the disk array. If the disk array is already opened by another process (for example, LVM \(em the Logical Volume Manager), a .RC ~ "device busy" ~ error message is returned by the driver. To eliminate the .RC ~ "device busy" ~ condition, determine what process has the device open. In the case of LVM, it is necessary to deactivate the volume group containing the array before configuring the array (see .CR vgchange (1M)). .tr ~~ .TP .C "see: LUN # too big" The LUN number, which is derived from the device special file name, is out of range. .TP .C "see: LUN does not exist" The addressed LUN is not configured, and thus is not known to the array controller. .TP .C "see: Not a raw file" Utilities must be able to open the device file for raw access. .TP .C "see: Not an HP SCSI disk array" The device being addressed is not an HP SCSI disk array. .TP .C "see: Transfer length error" The amount of data actually sent to or received from the device was not the expected amount. .PP .SS SCSI (device level) communication errors: Sense data associated with the failed operation is printed. .PP .SS Error messages generated by system calls: .CR see uses the following system calls: .IP .CR stat() , .CR open() , .CR close() , .CR read() , .CR write() , and .CR ioctl() . .PP Documentation for these HP-UX system calls contains information about the specific error conditions associated with each call. .CR see does not alter the value of .CR errno . The interpretation of .CR errno for printing purposes is performed by the system utility .CR strerror() . .SH EXAMPLES .PP To display the values of the accessible EEPROM bytes on HP SCSI disk array .CR /dev/rdsk/c2t6d0 on a Series 700: .IP .C "see -d /dev/rdsk/c2t6d0" .PP .SH WARNING Changing the values of EEPROM bytes can result in incorrect controller behavior with respect to utilities and support software that may not be immediately obvious. Also, the EEPROM can only be written to a finite number of times, and if its write count is exceeded, it must be replaced. .SH DEPENDENCIES The HP C2425 and HP C2427 disk arrays are only supported on Series 700 systems running HP-UX version 9.0X. .PP The HP C2430 disk array is supported on Series 700 and 800 systems running HP-UX versions 9.0X and 10.0X. .SH AUTHOR .PP .CR see was developed by HP. .\" .\" index@\f4see\f1 \- access EEPROM bytes in an HP SCSI disk array controller@@@\f3see(1M)\f1 .\" .\" toc@\f3see(1M)\f1:\0\0\f4see\f1@@@access EEPROM bytes in an HP SCSI disk array controller .\" .\" fileset_database@see.1m SYS-ADMIN-MAN .\" Copyright (c) 1983, 1997 Eric P. Allman .\" Copyright (c) 1988, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)sendmail.1m 8.12 (Berkeley) 2/1/97 .\" .\" $Header: sendmail.1m,v 1.1.113.5 97/08/19 02:59:33 sita Exp $ .TH sendmail 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: August 1997 .SH NAME sendmail \- an electronic mail transport agent .SH SYNOPSIS .B /usr/sbin/sendmail .RC [ flags ] .RC [ address ... ] .br .B newaliases .br .B mailq .RC [ -v ] .SH DESCRIPTION .B Sendmail sends a message to one or more .I recipients , routing the message over whatever networks are necessary. .B Sendmail does internetwork forwarding as necessary to deliver the message to the correct place. .PP .B Sendmail is not intended as a user interface routine; other programs provide user-friendly front ends; .B sendmail is used only to deliver pre-formatted messages. .PP With no flags, .B sendmail reads its standard input up to an end-of-file or a line consisting only of a single dot and sends a copy of the message found there to all of the addresses listed. It determines the network(s) to use based on the syntax and contents of the addresses. .PP Local addresses are looked up in a file and aliased appropriately. Aliasing can be prevented by preceding the address with a backslash. Normally the sender is not included in any alias expansions, e.g., if `john' sends to `group', and `group' includes `john' in the expansion, then the letter will not be delivered to `john'. .SS Parameters .RS .TP 12 .BI \-B type Set the body type to .I type. Current legal values 7BIT or 8BITMIME. .TP .B \-ba Go into .SM ARPANET mode. All input lines must end with a CR-LF, and all messages will be generated with a CR-LF at the end. Also, the ``From:'' and ``Sender:'' fields are examined for the name of the sender. .TP .B \-bd Run as a daemon. .B Sendmail will fork and run in background listening on socket 25 for incoming .SM SMTP connections. This is normally run from .I /etc/rc. .TP .B \-bD Same as .B \-bd except runs in foreground. .TP .B \-bh Print the persistent host status database. .TP .B \-bH Purge the persistent host status database. .TP .B \-bi Initialize the alias database. .TP .B \-bm Deliver mail in the usual way (default). .TP .B \-bp Print a listing of the queue. .TP .B \-bs Use the .SM SMTP protocol as described in .SM RFC821 on standard input and output. This flag implies all the operations of the .B \-ba flag that are compatible with .SM SMTP. .TP .B \-bt Run in address test mode. This mode reads addresses and shows the steps in parsing; it is used for debugging configuration tables. .TP .B \-bv Verify names only \- do not try to collect or deliver a message. Verify mode is normally used for validating users or mailing lists. .TP .BI \-C file Use alternate configuration file. .B Sendmail refuses to run as root if an alternate configuration file is specified. .TP .BI \-d X Set debugging value to .IR X . .TP .BI \-F fullname Set the full name of the sender. .TP .BI \-f name Sets the name of the ``from'' person (i.e., the sender of the mail). .B \-f can only be used by ``trusted'' users (normally .I root, .I daemon, and .I network) or if the person you are trying to become is the same as the person you are. .TP .BI \-h N Set the hop count to .I N. The hop count is incremented every time the mail is processed. When it reaches a limit, the mail is returned with an error message, the victim of an aliasing loop. If not specified, ``Received:'' lines in the message are counted. .TP .B \-i Ignore dots alone on lines by themselves in incoming messages. This should be set if you are reading data from a file. .TP .BI \-N dsn Set delivery status notification conditions to .IR dsn, which can be `never' for no notifications or a comma separated list of the values `failure' to be notified if delivery failed, `delay' to be notified if delivery is delayed, and `success' to be notified when the message is successfully delivered. .TP .B \-n Don't do aliasing. .TP .BI \-O option=value Set option .I option to the specified .I value . This form uses long names. See below for more details. .TP .BI \-o x=value Set option .I x to the specified .I value. This form uses single character names only. .TP .BI \-p protocol Set the name of the protocol used to receive the message. This can be a simple protocol name such as ``UUCP'' or a protocol and hostname, such as ``UUCP:ucbvax''. .TP .BI \-q [time] Processed saved messages in the queue at given intervals. If .I time is omitted, process the queue once. Time is given as a tagged number, with `s' being seconds, `m' being minutes, `h' being hours, `d' being days, and `w' being weeks. For example, `-q1h30m' or `-q90m' would both set the timeout to one hour thirty minutes. If .I time is specified, .B sendmail will run in background. This option can be used safely with .B \-bd. .TP .BI \-qI substr Limit processed jobs to those containing .I substr as a substring of the queue id. .TP .BI \-qR substr Limit processed jobs to those containing .I substr as a substring of one of the recipients. .TP .BI \-qS substr Limit processed jobs to those containing .I substr as a substring of the sender. .TP .BI \-R return Set the amount of the message to be returned if the message bounces. The .I return parameter can be `full' to return the entire message or `hdrs' to return only the headers. .TP .BI \-r name An alternate and obsolete form of the .B \-f flag. .TP .B \-t Read message for recipients. To:, Cc:, and Bcc: lines will be scanned for recipient addresses. The Bcc: line will be deleted before transmission. Any addresses in the argument list will be suppressed, that is, they will .I not receive copies even if listed in the message header. .TP .B \-U Initial (user) submission. This should .I always be set when called from a user agent such as .B Mail or .B exmh and .I never be set when called by a network delivery agent such as .B rmail. .TP .BI \-V envid Set the original envelope id. This is propagated across SMTP to servers that support DSNs and is returned in DSN-compliant error messages. .TP .B \-v Go into verbose mode. Alias expansions will be announced, etc. .TP .BI \-X logfile Log all traffic in and out of mailers in the indicated log file. This should only be used as a last resort for debugging mailer bugs. It will log a lot of data very quickly. .SS Options There are also a number of processing options that may be set. Normally these will only be used by a system administrator. Options may be set either on the command line using the .B \-o flag (for short names), the .B \-O flag (for long names), or in the configuration file. This is a partial list limited to those options that are likely to be useful on the command line and only shows the long names; The options are: .RS .TP 12 .BI AliasFile=file Use alternate alias file. .TP .B HoldExpensive On mailers that are considered ``expensive'' to connect to, don't initiate immediate connection. This requires queueing. .TP .BI CheckpointInterval=N Checkpoint the queue file after every .I N successful deliveries (default 10). This avoids excessive duplicate deliveries when sending to long mailing lists interrupted by system crashes. .TP .BI DeliveryMode=x Set the delivery mode to .I x. Delivery modes are `i' for interactive (synchronous) delivery, `b' for background (asynchronous) delivery, `q' for queue only \- i.e., actual delivery is done the next time the queue is run, and `d' for deferred \- the same as `q' except that database lookups (notably DNS and NIS lookups) are avoided. .TP .BI ErrorMode=x Set error processing to mode .I x. Valid modes are `m' to mail back the error message, `w' to ``write'' back the error message (or mail it back if the sender is not logged in), `p' to print the errors on the terminal (default), `q' to throw away error messages (only exit status is returned), and `e' to do special processing for the BerkNet. If the text of the message is not mailed back by modes `m' or `w' and if the sender is local to this machine, a copy of the message is appended to the file .I dead.letter in the sender's home directory. .TP .B SaveFromLine Save .SM UNIX\-style From lines at the front of messages. .TP .BI MaxHopCount=N The maximum number of times a message is allowed to ``hop'' before we decide it is in a loop. .TP .B IgnoreDots Do not take dots on a line by themselves as a message terminator. .TP .B SendMimeErrors Send error messages in MIME format. If not set, the DSN (Delivery Status Notification) SMTP extension is disabled. .TP .BI ConnectionCacheTimeout=timeout Set connection cache timeout. .TP .BI ConnectionCacheSize=N Set connection cache size. .TP .BI LogLevel=n The log level. .TP .B MeToo Send to ``me'' (the sender) also if I am in an alias expansion. .TP .B CheckAliases Validate the right hand side of aliases during a newaliases(1) command. .TP .B OldStyleHeaders If set, this message may have old style headers. If not set, this message is guaranteed to have new style headers (i.e., commas instead of spaces between addresses). If set, an adaptive algorithm is used that will correctly determine the header format in most cases. .TP .BI QueueDirectory=queuedir Select the directory in which to queue messages. .TP .BI StatusFile=file Save statistics in the named file. .TP .BI Timeout.queuereturn=time Set the timeout on undelivered messages in the queue to the specified time. After delivery has failed (e.g., because of a host being down) for this amount of time, failed messages will be returned to the sender. The default is five days. .TP .BI UserDatabaseSpec=userdatabase If set, a user database is consulted to get forwarding information. You can consider this an adjunct to the aliasing mechanism, except that the database is intended to be distributed; aliases are local to a particular host. This may not be available if your sendmail does not have the USERDB option compiled in. .TP .B ForkEachJob Fork each job during queue runs. May be convenient on memory-poor machines. .TP .B SevenBitInput Strip incoming messages to seven bits. .TP .B EightBitMode=mode Set the handling of eight bit input to seven bit destinations to .IR mode : m (mimefy) will convert to seven-bit MIME format, p (pass) will pass it as eight bits (but violates protocols), and s (strict) will bounce the message. .TP .BI MinQueueAge=timeout Sets how long a job must ferment in the queue between attempts to send it. .TP .BI DefaultCharSet=charset Sets the default character set used to label 8-bit data that is not otherwise labelled. .TP .BI DialDelay=sleeptime If opening a connection fails, sleep for .I sleeptime seconds and try again. Useful on dial-on-demand sites. .TP .BI NoRecipientAction=action Set the behaviour when there are no recipient headers (To:, Cc: or Bcc:) in the message to .IR action : none leaves the message unchanged, add-to adds a To: header with the envelope recipients, add-apparently-to adds an Apparently-To: header with the envelope recipients, add-bcc adds an empty Bcc: header, and add-to-undisclosed adds a header reading `To: undisclosed-recipients:;'. .TP .BI MaxDaemonChildren=N Sets the maximum number of children that an incoming SMTP daemon will allow to spawn at any time to .I N. .TP .BI ConnectionRateThrottle=N Sets the maximum number of connections per second to the SMTP port to .I N. .RE .PP In aliases, the first character of a name may be a vertical bar to cause interpretation of the rest of the name as a command to pipe the mail to. It may be necessary to quote the name to keep .B sendmail from suppressing the blanks from between arguments. For example, a common alias is: .PP .TP 30 msgs: "|/usr/bin/msgs -s" .PP Aliases may also have the syntax ``:include: .I filename'' to ask sendmail to read the named file for a list of recipients. For example, an alias such as: .PP .TP 30 poets: ":include:/usr/local/lib/poets.list" .Ed .PP would read .I /usr/local/lib/poets.list for the list of addresses making up the group. .PP .B Sendmail returns an exit status describing what it did. The codes are defined in .RI : .PP .PD 0 .TP 20 EX_OK Successful completion on all addresses. .TP EX_NOUSER User name not recognized. .TP EX_UNAVAILABLE Catchall meaning necessary resources were not available. .TP EX_SYNTAX Syntax error in address. .TP EX_SOFTWARE Internal software error, including bad arguments. .TP EX_OSERR Temporary operating system error, such as ``cannot fork''. .TP EX_NOHOST Host name not recognized. .TP EX_TEMPFAIL Message could not be sent immediately, but was queued. .PD .PP If invoked as .B newaliases , .B sendmail will rebuild the alias database. If invoked as .B mailq , .B sendmail will print the contents of the mail queue. .SH FILES Except for the file .IR /etc/mail/sendmail.cf itself, the following pathnames are all specified in .IR /etc/mail/sendmail.cf. Thus, these values are only approximations. .PP .PD 0 .TP 30 /etc/mail/aliases raw data for alias names .TP /etc/mail/aliases.db data base of alias names .TP /etc/mail/sendmail.cf configuration file .TP /usr/share/lib/sendmail.hf help file .TP /etc/mail/sendmail.st collected statistics .TP /var/spool/mqueue/* temp files .TP /etc/mail/sendmail.pid The process id of the daemon .TP /etc/mail/sendmail.cw The list of all hostnames that are recognized as local, which causes sendmail to accept mail for these hosts and attempt local delivery .TP /etc/nssswitch.conf The fallback mechanism for hostname and alias lookups .PD .SH SEE ALSO mail(1), mailx(1), rmail(1), elm(1), mailstats(1), praliases(1), idlookup(1), aliases(5), mailq(1), newaliases(1m), smrsh(1m), syslog(3C), identd(1m), expand_alias(1), mtail(1), killsm(1), convert_awk(1m), rc(1m). .br RFC819, RFC821, RFC822. .SH HISTORY The .B sendmail command appeared in BSD 4.2. This version of HP-UX sendmail was originally based on sendmail 8.8.6 and includes only minor changes. .\" $Header: service.switch.1m,v 78.3 96/01/21 23:19:32 ssa Exp $ .TA s .TH service.switch 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME service.switch \- indicate lookup sources and fallback mechanism .SH SYNOPSIS .CR /etc/mail/service.switch .SH DESCRIPTION .CR /etc/mail/service.switch is a .IR sendmail (1M) service switch similar to .CR /etc/nsswitch.conf (see .IR switch (5)) that indicates the lookup source for hostnames and aliases. It consists of two lines, one for hosts and one for aliases. The lookup sources are listed after the 'hosts' or 'aliases' name. For hosts, one or more of the following can be listed: files (for .CR /etc/hosts ), dns, nis, or nisplus. For aliases, one or more of the following can be listed: files (for .CR /etc/mail/aliases ), nis, or nisplus. .PP .SS Sample Configurations .TP 3 1. The default configuration for service.switch is to use dns for hostname lookups and the aliases file for aliases. (Note that due to a bug, the hostname lookup will never fallback to a file lookup, so anything listed after dns will be ignored.) .TP .RS hosts dns files aliases files .RE .PP .TP 3 2. To work with a non-dns environment that uses file lookups .RC ( /etc/hosts ), the following service.switch can be used: .TP .RS hosts files aliases files .RE .PP .TP 3 3. To work with a NIS environment that does not use DNS, the following service.switch can be used: .TP .RS hosts nis files aliases nis files .RE .PP .TP 3 4. To work with a NISPLUS environment that does not use DNS, the following service.switch can be used: .TP .RS hosts nisplus files aliases nisplus files .RE .PP .SS Modifying SENDMAIL.CF The .CR sendmail.cf file must be modified to request the usage of the .CR service.switch file. Otherwise, the default for .CR sendmail.cf is to use DNS for host name lookups, and files for alias lookups. To use NIS, NISPLUS, or files, the following line must be uncommented in .CR sendmail.cf : .TP .RS #O ServiceSwitchFile=/etc/mail/service.switch .RE .PP .SH SEE ALSO sendmail(1M) .SH HISTORY The .CR service.switch file appeared in sendmail V8. .\" .\" .\" toc@\f3service.switch(1M)\f1:\0\0\f4service.switch\f1@@@indicate lookup sources and fallback mechanism .\" .\" index@\f4service.switch\f1 \- indicate lookup sources and fallback mechanism@@@\f3service.switch(1M)\f1 .\" index@\f1service switch@@@\f3service.switch(1M)\f1 .\" index@\f1lookup sources@@@\f3service.switch(1M)\f1 .\" index@\f1fallback mechanism@@@\f3service.switch(1M)\f1 .\" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Oct 25, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH set 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "DTS servers" "modifying" .iX "-[" "DTS clerks" "modifying" .iX "-[" "\*Ldtscp\*O commands" "\*Lset\*O" .SH NAME .PP \*Lset\*O - Modifies characteristics for the DTS entity. .SH "SYNOPSIS" .PP .zA "defect,6211,R1.0.3,add control program name" .sS \*Ldtscp set \*Vcharacteristic\*O .sE .zZ "defect,6211,R1.0.3,add control program name" .SH "ARGUMENTS" .VL .LI "\*Vcharacteristic\*O" The name and value of one or more characteristics to be modified. Valid values for characteristic are described in the following list. These values are described in more detail in the description section. .ML .LI \*Lcheck interval\*O [\*Vrelative-time\*O] .LI \*Lcourier role\*O [\*Vrole\*O] .LI \*Lerror tolerance\*O [\*Vrelative-time\*O] .LI \*Lglobal set timeout\*O [\*Vrelative-time\*O] .LI \*Llocal set timeout\*O [\*Vrelative-time\*O] .LI \*Lmaximum inaccuracy\*O [\*Vrelative-time\*O] .LI \*Lquery attempts\*O [\*Vinteger\*O] .LI \*Lserver entry name\*O [\*Vname\*O] .zA "defect,7841,R1.0.3, Change to `server group name'" .zA "defect,5636,R1.0.2, Add argument 'servers group'" .LI \*Lserver group name\*O [\*Vname\*O] .zZ "defect,5636,R1.0.2, Add argument 'servers group'" .zZ "defect,7841,R1.0.3, Change to `server group name'" .LI \*Lserver principal name\*O [\*Vname\*O] .LI \*Lservers required\*O [\*Vinteger\*O] .LI \*Lsynchronization hold down\*O [\*Vrelative-time\*O] .LE .LE .SH "DESCRIPTION" The \*Lset\*O command modifies the charactistics you specify for the DTS entity. The modifiable characteristics and their values are described in the following list. ...\".SS "advertisement interval" ...\".iX "advertisement interval characteristic" ...\".PP ...\"Specifies the amount of time between a server's advertisement broadcasts. ...\".VL 11m ...\".LI "Default: 0-01:30:00.000" ...\"Value: 0-00:00:30.000\(en99-99:99:99.999 ...\".LE .VL .LI "\*Lcheck interval\*O [\*Vrelative-time\*O]" .PP Specifies the amount of time between checks for faulty servers. Applicable only for servers that have external time providers. .P Default: \*L0-01:30:00.000\*O .nL .zA "defect,5896,R1.0.2, Update range" Value: \*L0-00:00:30.000 - 10675199-02:48:05.000\*O .zZ "defect,5896,R1.0.2, Update range" .LI "\*Lcourier role\*O [\*Vrole\*O]" .PP Specifies a server's interaction with the set of global servers. .P Default: \*Lbackup courier\*O .P The following values are valid: .VL .LI "\*Lbackup courier\*O" The local server becomes a courier if none are available on the LAN. .LI "\*Lcourier\*O" The local server synchronizes with the global set of servers. .LI "\*Lnoncourier\*O" The local server does not synchronize with the global set of servers. .LE .LI "\*Lerror tolerance\*O [\*Vrelative-time\*O]" .PP Specifies the maximum separation allowed between the local clock and the computed time before synchronizations become abrupt rather than gradual (monotonic). .PP Default: \*L0-00:10:00.000\*O .nL .zA "defect,5896,R1.0.2, Update range" Value: \*L0-00:00:00.500 - 10675199-02:48:05.000\*O .zZ "defect,5896,R1.0.2, Update range" .LI "\*Lglobal set timeout\*O [\*Vrelative-time\*O]" .PP Specifies the amount of time the node waits for a response to a global synchronization request before sending another request or declaring a global server to be unavailable. The number of attempts made to reach the server is controlled by the \*Lquery attemps\*O characteristic. .P Default: \*L0-00:00:15.000\*O .nL .zA "defect,5500,R1.0.2, Update range" Value: \*L0-00:00:00.000 - 0-00:10:00.000\*O .zZ "defect,5500,R1.0.2, Update range" .LI "\*Llocal set timeout\*O [\*Vrelative-time\*O]" .PP Specifies the amount of time the node waits for a response to a local synchronization request before sending another request or declaring a server to be unavailable. The number of attempts made to reach the server is controlled by the \*Lquery attemps\*O characteristic. .zA "defect,8229,R1.0.3,add info about initial contact" .P Note that the \*Llocal set timeout\*O value controls only the initial contact with a time provider. During this initial contact, the time provider itself determines the timeout value for actually reporting back times. This allows a time provider attached to a slow source like a modem to request that \*Ldtsd\*O wait for a longer interval. .zZ "defect,8229,R1.0.3,add info about initial contact" .P .zA "defect,5500,R1.0.2, Update default and range." Default: \*L0-00:00:05.000\*O .nL Value: \*L0-00:00:00.000 - 0-00:01:00.000\*O .zZ "defect,5500,R1.0.2, Update default and range." .LI "\*Lmaximum inaccuracy\*O [\*Vrelative-time\*O]" .PP Specifies the inaccuracy limit for the node. When the node exceeds the maximum inaccuracy setting, it attempts to synchronize. .PP Default: \*L0-00:00:00.100\*O .nL .zA "defect,5896,R1.0.2, Update range" Value: \*L0-00:00:00.000 - 10675199-02:48:05.000\*O .zZ "defect,5896,R1.0.2, Update range" .LI "\*Lquery attempts\*O [\*Vinteger\*O]" .PP Specifies the number of attempts that a node makes to contact a server before the node considers the server unavailable. .PP Default: \*L3\*O .nL Value: 1-10 .LI "\*Lserver entry name\*O [\*Vname\*O]" .PP Specifies a server's CDS entry name; \*Vhostname\*O represents the name of the system or node that is the server's client. The default setting is the recommended value. .PP Default: \*L/.:/hosts/\*Vhostname\*L/dts-entity\*O ...\".SS "server group name" ...\".iX "server group name characteristic" ...\".PP ...\"Specifies the security group name for the time servers within the cell; the ...\"default setting is the recommended value. ...\".VL 11m ...\".LI "Default: /.:/subsys/dce/dts-servers" ...\"Value: See description ...\".LE .zA "defect,7841,R1.0.3, Change to `server group name'" .zA "defect,5636,R1.0.2, Add description of 'servers group'" .LI "\*Lserver group name\*O [\*Vname\*O]" .PP Specifies the name of the security group that DTS uses for authentication checks. DTS clerks and servers do not accept time values from DTS servers that are not included in this group. .zZ "defect,5636,R1.0.2, Add description of 'servers group'" .zZ "defect,7841,R1.0.3, Change to `server group name'" .LI "\*Lserver principal name\*O [\*Vname\*O]" .PP Specifies a server's principal name for authentication purposes; \*Vhostname\*O represents the name of the system or node that is the server's client. The default setting is the recommended value. .PP Default: \*L/.:/hosts/\*Vhostname\*L/self\*O .LI "\*Lservers required\*O [\*Vinteger\*O]" .PP Specifies the minimum number of servers required for a synchronization. Settings of 1 or 2 may cause unreliable computed times. .P Default: \*L1\*O (clerks) \*L3\*O (servers) .nL .zA "defect,8035,R1.0.3, Update range" .zA "defect,5500,R1.0.2, Update range" Value: \*L1-10\*O .zZ "defect,5500,R1.0.2, Update range" .zZ "defect,8035,R1.0.3, Update range" .LI "\*Lsynchronization hold down\*O [\*Vrelative-time\*O]" .PP Specifies the interval a node must wait to synchronize. Also specifies synchronization frequency when a node reaches the value specified by the \*Lmaximum inaccuracy\*O characteristic. .PP Clerks: .nL Default: \*L0-00:10:00.000\*O .nL Value: \*L0-00:00:30.000 - 01-00:00:00.000\*O .PP Servers: .nL Default: \*L0-00:02:00.000\*O .nL Value: \*L0-00:00:30.000 - 01-00:00:00.000\*O .LE .SS "Privilege Required" .PP You must have write permission on the ACL associated with the DTS entity in order to execute the command. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTES" .PP This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .zA "defect, 9518, R1.1, mention lan and wan timeout" .PP The following two commands are obsolete. Use the replacements shown. .VL .LI "\*Lset lan timeout\*O" This command is the same as \*Lset local set timeout\*O. .LI "\*Lset wan timeout\*O" This command is the same as \*Lset global set timeout\*O. .LE .zZ "defect, 9518, R1.1, mention lan and wan timeout" .SH "EXAMPLES" .PP .zA "defect,4857,R1.0.2, Added command examples." .AL .LI The following example command sets the check interval characteristic to 30 seconds: .PP .iS \*Cdtscp>\*O \*Lset check interval 00-00:00:30.000\*O .iE .LI The following example shows how to set the number of servers required before the entity can synchronize: .PP .iS \*Cdtscp>\*O \*Lset servers required 4\*O .iE .LI The following example shows how to set the courier role for a server: .PP .iS \*Cdtscp>\*O \*Lset courier role backup courier\*O .iE .LI The following example command sets the error tolerance characteristic to seven minutes: .PP .iS \*Cdtscp>\*O \*Lset error tolerance 0-00:07:00.000\*O .iE .LI The following example command the global set timeout characteristic to 45 seconds: .PP .iS \*Cdtscp>\*O \*Lset global set timeout 0-00:00:45.000\*O .iE .LI The following example command the local set timeout characteristic to five seconds: .PP .iS \*Cdtscp>\*O \*Lset local set timeout 0-00:00:05.000\*O .iE .LI The following example command sets the maximum inaccuracy characteristic to three milliseconds: .PP .iS \*Cdtscp>\*O \*Lset maximum inaccuracy 0-00:00:00.300\*O .iE .LI The following example command sets the server entry name characteristic to /.:/hosts/orion/dts-entity: .PP .iS \*Cdtscp>\*O \*Lset server entry name /.:/hosts/orion/dts-entity\*O .iE .LI The following example command sets the server principal name characteristic to /.:/hosts/vega/dts-entity: .PP .iS \*Cdtscp>\*O \*Lset server principal name /.:/hosts/vega/dts-entity\*O .iE .LI The following example command sets the synchronization hold down characteristic to 15 minutes: .PP .iS \*Cdtscp>\*O \*Lset synchronization hold down 0-00:15:00.000\*O .iE .LE .zZ "defect,4857,R1.0.2, Added command examples." .SH "RELATED INFORMATION" .PP Commands: \*Lshow (1m)\*O .iX "-]" "DTS servers" "modifying" .iX "-]" "DTS clerks" "modifying" .iX "-]" "\*Ldtscp\*O commands" "\*Lset\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "set cdscp confidence" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "CDS clerks" "setting confidence levels" .iX "\*Lcdscp\*O commands" "\*Lset cdscp confidence\*O" .SH NAME .PP \*Lset cdscp confidence\*O - Sets the confidence level of clerk calls issued as a result of CDS control program commands .wH "" .SH "SYNOPSIS" .PP \*Lcdscp\*O \*Lset cdscp confidence\*O = \*Vvalue\*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vvalue\*O" One of the following confidence levels: \*Llow\*O, \*Lmedium\*O, or \*Lhigh\*O. A low confidence level means the clerk obtains information from caches or the most convenient server. A medium level means the clerk obtains information directly from a server. A high level means the clerk obtains information only at master replicas. The initial value is \*Lmedium\*O. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lset cdscp confidence\*O command sets the confidence level of clerk calls issued as a result of CDS control program commands. You must use this command within the CDS control program. Exiting from the CDS control program removes the confidence level setting. You must reset the confidence level each time you enter the CDS control program. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command may be replaced in future releases by the \*Ldcecp\*O command, and may no longer be supported at that time. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command sets the confidence level of clerk calls to \*Lhigh\*O. .iS \*C$ \*Lcdscp\*O \*Ccdscp> \*Lset cdscp confidence = high\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Command: \*Lshow cdscp confidence(1m)\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "set cdscp preferred clearinghouse" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "clearinghouses" "preferred" .iX "\*Lcdscp\*O commands" "\*Lset cdscp preferred clearinghouse\*O" .SH NAME .PP \*Lset cdscp preferred clearinghouse\*O - Specifies a preferred clearinghouse to use for satisfying read requests that result from CDS control program commands .wH "" .SH "SYNOPSIS" .PP \*Lcdscp\*O \*Lset cdscp preferred clearinghouse\*O [\*Vclearinghouse-name\*O] .wH "" .SH "ARGUMENTS" .VL .LI "\*Vclearinghouse-name\*O" The full name of the preferred clearinghouse. If you omit this argument, the command causes CDS to revert to the default, which is to use any clearinghouse. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lset cdscp preferred clearinghouse\*O command specifies a preferred clearinghouse to use for satisfying read requests that result from CDS control program commands. You cannot specify a preferred clearinghouse for making modifications, because these requests always use the master replica. You must use this command within the CDS control program. Exiting from the CDS control program removes the preferred clearinghouse setting. You must reset the preferred clearinghouse each time you enter the CDS control program. .SS "Permissions Required" .PP None .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command specifies \*L/.:/Paris_CH\*O as the preferred clearinghouse: .iS \*C$ \*Lcdscp\*O \*Ccdscp>\*L set cdscp preferred clearinghouse /.:/Paris_CH\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Command: \*Lshow cdscp preferred clearinghouse(1m)\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed. Dec 11, 1991 Update file submission for ...\" V 1.0 final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "set directory"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "directories" "changing attribute values (CDS)" .iX "-[" "\*Lcdscp\*O commands" "\*Lset directory\*O" .SH NAME .PP \*Lset directory\*O - Changes the value of a modifiable, single-valued attribute of a directory .wH "" .SH "SYNOPSIS" .PP \*Lcdscp set directory\*O \*Vdirectory-name attribute-name\*O = \*Vattribute-value\*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vdirectory-name\*O" The full name of the directory. .LI "\*Vattribute-name\*O" The name of a particular attribute. Specify only one attribute at a time. See the \*Lcds_attributes\*O file for the list of attributes and corresponding data types that your application uses. .LI "\*Vattribute-value\*O" The value of a particular attribute. The value of an application-defined attribute is dependent on the type of attribute. .LE .wH "" .SH "DESCRIPTION" .PP The \*Lset directory\*O command changes the value of a modifiable, single-valued attribute of a directory. If the attribute does not exist, this command creates it. Usually, this task is performed through the client application. See the \*VOSF DCE Administration Guide\*O for more information about attributes. You can specify an application-defined attribute or the following attributes: .VL .LI "\*LCDS_Convergence\*O \*E= value\*O" Specifies the degree of consistency among replicas. By default, every directory inherits the convergence of its parent at creation time. The default setting on the root directory is \*Lmedium\*O. You can define one of the following for \*Evalue\*O: .VL .LI "\*Llow\*O" CDS does not immediately propagate any updates. The next skulk distributes all updates that occurred since the previous skulk. Skulks occur at least once every 24 hours. .LI "\*Lmedium\*O" CDS attempts to immediately propagate an update to all replicas. If the attempt fails, the software lets the next scheduled skulk make the replicas consistent. Skulks occur at least once every 12 hours. .LI "\*Lhigh\*O" CDS attempts to immediately propagate an update to all replicas. If that attempt fails (for example, if one of the replicas is unavailable), a skulk is scheduled for within one hour. Background skulks occur at least once every 12 hours. Use this setting temporarily and briefly because it uses extensive system resources. .LE .zA "enh,10578,R1.1,Added CDS_UpgradeTo attribute" .LI "\*LCDS_UpgradeTo\*O \*V= v.n\*O" Controls the upgrading of a directory from one version of CDS to another. By modifying this attribute, you can initiate the upgrading of a directory to a higher version of CDS. Specify the value as \*Vv.n\*O, where \*Vv\*O indicates the major version number and \*Vn\*O specifies the minor version number. There is no default. .LE .zZ "enh,10578,R1.1,Added CDS_UpgradeTo attribute" .SS "Privilege Required" .PP You must have write permission to the directory. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .PP The following command sets a low convergence value on the \*L/.:/mfg\*O directory: .iS \*Ccdscp>\*L set directory /.:/mfg CDS_Convergence = low .iE .PP The following commands upgrades the directory version on the \*L/.:/host\*O directory: .iS \*Cdcecp> \*Ldirectory modify /.:/host -add {CDS_UpgradeTO 1.2} -single .br \*Cdcecp> \*Ldirectory synchronize /.:/host .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lcreate directory(1m)\*O, \*Ldelete directory(1m)\*O, \*Llist directory(1m)\*O, \*Lremove directory(1m)\*O, \*Lset directory to skulk(1m)\*O, \*Lshow directory(1m)\*O .PP Books: \*VOSF DCE Administration Guide\*O .wH "" .wH "" .iX "-]" "directories" "changing attribute values (CDS)" .iX "-]" "\*Lcdscp\*O commands" "\*Lset directory\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "set directory to new epoch" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "replica sets" "reconstructing" .iX "-[" "\*Lcdscp\*O commands" "\*Lset directory to new epoch\*O" .SH NAME .PP \*Lset directory to new epoch\*O - Reconstructs a directory's replica set, allowing you to designate a new master replica or to exclude a replica .wH "" .SH "SYNOPSIS" .PP .sS \*Lcdscp set directory\*O \*Vdirectory-name \*Lto new epoch master\*O \*Vclearinghouse-name\*O [\*Lreadonly\*O \*Vclearinghouse-name...\*O] [\*Lexclude\*O \*Vclearinghouse-name...\*O] .sE .wH "" .SH "ARGUMENTS" .VL .LI \"*Vdirectory-name\*O" The full name of the directory. .LI \"*Vclearinghouse-name\*O" The full name of the clearinghouse in which an individual replica is located. The first \*Vclearinghouse-name\*O specifies where the master replica is stored. .LE .wH "" .SH "DESCRIPTION" .PP The \*Lset directory to new epoch\*O command reconstructs a directory's replica set, allowing you to designate a new master replica or to exclude a replica. You must list each existing replica and indicate whether an existing replica needs to be included in or excluded from the new replica set. You can include or exclude more than one replica. The ellipses (...) indicates that you can specify multiple clearinghouse names, separated by spaces. .PP .zA "defect,6045,R1.0.2, "Added description" .zA "edit,10452,R1.1,Edited text for clarity" When you set a new epoch on a directory, you must disable the clearinghouse containing the replica that is being excluded. To do this, use the \*Ldisable server\*O command (if the server has more than one clearinghouse, all its clearinghouses will be disabled). Note that all clearinghouses that are not excluded must be enabled and available before you issue the \*Ldisable server\*O command. .zZ "edit,10452,R1.1,Edited text for clarity" .zZ "defect,6045,R1.0.2, "Added description" .SS "Privilege Required" .PP You must have administer permission to the directory, and the server principal needs administer, read, and write permission to the directory. When designating a new master replica, you also need write permission to the clearinghouse that stores the new master replica, and the server principal needs write permission to each clearinghouse where the replica type is changed to read-only. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command may be replaced in future releases by the \*Ldcecp\*O command, and may no longer be supported at that time. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP .zA "defect,6077,R1.0.2,Change to readonly" The following command sets a new epoch for the directory \*L/.:/mfg\*O. The master replica is in the clearinghouse \*L/.:/Paris1_CH\*O, and read-only replicas are in the clearinghouses \*L/.:/Chicago1_CH\*O, \*L/.:/Seattle_CH\*O, and \*L/.:/NY1_CH\*O. The new replica set excludes the replica in the clearinghouse \*L/.:/NY1_CH\*). .iS \*Ccdscp> \*Lset directory /.:/mfg to new epoch master /.:/Paris1_CH \\ > readonly /.:/Chicago1_CH /.:/Seattle_CH exclude /.:/NY1_CH\*O .iE .wH "" .zZ "defect,6077,R1.0.2,Change to readonly" .SH "RELATED INFORMATION" .PP Commands: \*Lset directory to skulk(1m)\*O, \*Lshow directory(1m)\*O, \*Lshow replica(1m)\*O .wH "" .wH "" .iX "-]" "replica sets" "reconstructing" .iX "-]" "\*Lcdscp\*O commands" "\*Lset directory to new epoch\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "set directory to skulk" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "directories" "updating (CDS)" .iX "skulking" "startup command" .iX "\*Lcdscp\*O commands" "\*Lset directory to skulk\*O" .SH NAME .PP \*Lset directory to skulk\*O - Starts the skulk of a directory immediately .wH "" .SH "SYNOPSIS" .PP \*Lcdscp set directory\*O \*Vdirectory-name \*Lto skulk\*O .wH "" .SH "ARGUMENTS" .VL .LI "\*Vdirectory-name\*O" The full name of the directory. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lset directory to skulk\*O command starts the skulk of a directory immediately. The CDS control program prompt \*Ccdscp>\*O does not return until the skulk is complete. The amount of time for the skulk to complete is dependent on the location, number, and availability of replicas of the directory. .SS "Privilege Required" .PP You must have administer, write, insert, or delete permission to the directory. The server principal needs administer, read, and write permission to the directory. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command initiates a skulk on the \*L/.:/admin\*O directory: .iS \*Ccdscp> \*Lset directory /.:/admin to skulk .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ladd directory(1m)\*O, \*Lcreate directory(1m)\*O, \*Ldelete directory(1m)\*O, \*Llist directory(1m)\*O, \*Lremove directory(1m)\*O, \*Lset directory to new epoch(1m)\*O, \*Lshow directory(1m)\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed. Dec 11, 1991 Update file submission for ...\" V 1.0 final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "set link"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "soft links" "changing values" .iX "-[" "\*Lcdscp\*O commands" "\*Lset link\*O" .SH NAME .PP \*Lset link\*O - Changes the value of a modifiable, single-valued attribute of a soft link .wH "" .SH "SYNOPSIS" .PP .sS \*Lcdscp set link\*O \*Vlink-name attribute-name\*O = \*Vattribute-value\*O .sE .wH "" .SH "ARGUMENTS" .VL .LI "\*Vlink-name\*O" The full name of the soft link. .LI "\*Vattribute-name\*O" The name of the attribute to be modified. Specify only one attribute at a time. See \*LDescription\*O for valid attribute names. .LI \"*Vattribute-value\*O" The value of a particular attribute. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lset link\*O command changes the value of a modifiable, single-valued attribute of a soft link. The following are valid attributes: .VL .LI "\*LCDS_LinkTarget\*O \*E= fullname\*O Specifies the full name of the directory, object entry, or other soft link to which the soft link points. .LI "\*LCDS_LinkTimeout\*O \*E= (expiration-time extension-time) Specifies a timeout value after which the soft link is either checked or deleted. The timeout value contains both an expiration time and an extension time. If a soft link expires and its target entry is deleted, the soft link is deleted. If the soft link still points to an existing entry, its life is extended by the expiration time. Specify \*Vexpiration-time\*O in the format \*Vyyyy-mm-dd-hh:mm:ss\*O (year-month-day-hour:minute:second). Specify \*Vextension-time\*O in the format \*Vddd-hh:mm:ss\*O (day-hour:minute:second). .LE .SS "Privilege Required" .PP You must have write permission to the soft link. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command redirects a soft link named \*L/.:/admin/work_disk\*O from its current destination name, \*L/.:/admin/work_disk01\*O, to a new destination name, \*L/.:/admin/work_disk03\*O. .iS \*Ccdscp>\*L set link /.:/admin/work_disk CDS_LinkTarget = /.:/admin/work_disk03 .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lcreate link(1m)\*O, \*Ldelete link(1m)\*O, \*Llist link(1m)\*O, \*Lshow link(1m)\*O .wH "" .wH "" .iX "-]" "soft links" "changing values" .iX "-]" "\*Lcdscp\*O commands" "\*Lset link\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "set object"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "\*Lcdscp\*O commands" "\*Lset object\*O" .iX "-[" "objects" "changing attribute values" .SH NAME .PP \*Lset object\*O - Changes the value of a modifiable, single-valued attribute of an object entry .wH "" .SH "SYNOPSIS" .PP .sS \*Lcdscp set object\*O \*Vobject-name attribute-name = attribute-value\*O .sE .wH "" .SH "ARGUMENTS" .VL .LI "\*Vobject-name\*O" The full name of the object entry. .LI "\*Vattribute-name\*O" The name of the attribute to be modified. Specify only one attribute at a time. See the \*Lcds_attributes\*O file for the list of attributes and corresponding data types that your application uses. .LI "\*Vattribute-value\*O" The value of a particular attribute. The value of an application-defined attribute is dependent on the type of attribute. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lset object\*O command changes the value of a modifiable, single-valued attribute of an object entry. If the attribute does not exist, this command creates it. Usually, this task is performed through the client application. See the \*VOSF DCE Administration Guide\*O for more information about attributes. .SS "Privilege Required" .PP You must have write permission to the object entry. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP To change the value of the \*Lsales_record\*O attribute to \*Lregion2\*O of an object entry named \*L/.:/Q1_records\*O, follow these steps: .AL .LI Read the \*Lcds_attributes\*O file to check that the attribute \*Lsales_record\*O is listed, as shown in the following display: .iS \*C OID LABEL SYNTAX 1.3.22.1.3.66 sales_record char\*O .iE .LI Enter the following command to assign the value \*Lregion2\*O to the attribute \*Lsales_record\*O of an object entry named \*L/.:/Q1_records\*O. .iS \*Ccdscp>\*L set object /.:/Q1_records sales_record = region2 .iE .LE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ladd object(1m)\*O, \*Lcreate object(1m)\*O, \*Ldelete object(1m)\*O, \*Llist object(1m)\*O, \*Lremove object(1m)\*O, \*Lshow object(1m)\*O .PP Books: \*VOSF DCE Administration Guide\*O .wH "" .wH "" .iX "-]" "objects" "changing attribute values" .iX "-]" "\*Lcdscp\*O commands" "\*Lset object\*O" .\" $Header: setboot.1m,v 72.2 94/07/03 14:16:47 ssa Exp $ .TA s .TH setboot 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setboot \- display and modify variables in the stable storage .SH SYNOPSIS .CR /usr/sbin/setboot .PP .CR /usr/sbin/setboot .RC \|[ -p .IR primary_path ]\| .RC \|[ -a .IR alternate_path ]\| .RC \|[ -s .IR on \(or off ]\| .ifn .br .ifn \ \ \ \ \" .RC \|[ -b .IR on \(or off ] .SH DESCRIPTION The .CR setboot command sets the appropriate variable in the stable storage to the .CR setboot arguments. .PP If no options are specified, .CR setboot displays the current values of variables in the stable storage. .PP Only the superuser can write to the stable storage. .SS Options The .CR setboot command supports the following options: .RS .TP 20 .CI -p " primary_path" Set the primary boot path variable to .IR primary_path . .TP .CI -a " alternate_path" Set the alternate boot path variable to .IR alternate_path . .TP .CI -s " on" \f1\(or\f2 off Enable or disable the autosearch sequence. .TP .CI -b " on" \f1\(or\f2 off Enable or disable the autoboot sequence. .RE .SH RETURN VALUE .PP The .CR setboot command returns 0 upon successful completion or 1 if the command failed. .SH ERRORS .\"The command fails and returns an error if any of the following conditions .\"are true: The following conditions cause errors: .RS .IP Invalid option specified. .IP .CR /dev/kepd file not found. .IP Incorrect arguments. .IP Must be superuser to write to the stable storage. .IP Boot path not in correct format. .IP Stable storage read/write failure. .RE .SH EXAMPLES Set the primary path to .C 2/4.1.0 and enable the autoboot sequence: .IP .C "setboot -p 2/4.1.0 -b on" .PP .SH WARNINGS .\"The .\".CR setboot .\"command will fail in the following circumstances: .\".IP .\"Some architecture implementations allow limited number of .\"writes to the stable storage. .\".PP .\"Some failures might be due to hardware failure. .\"Some implementations may not have memory for the alternate boot path, .\"in which case this variable will be neither readable nor writable. The .CR setboot command fails under the following circumstances: .RS .TP \(bu The number of writes to the stable storage exceeds the number allowed by the architecture implementation. .TP \(bu Hardware failure. .TP \(bu The implementation does not have memory for the alternate boot path, in which case, this variable is neither readable nor writable. .SH AUTHOR .CR setboot was developed by HP. .SH FILES .TP 20 .C /dev/kepd Special device file used by the .CR setboot command. .SH SEE ALSO .IR "Managing SwitchOver/UX Manual" . .\" .\" toc@\f3setboot(1M)\f1:\0\0\f4setboot\f1@@@display and modify variables in the stable storage\f1 .\" .\" index@\f4setboot\f1 \- display and modify variables in the stable storage@@@\f3setboot(1M)\f1 .\" index@\f1display and modify variables in the stable storage@@@\f3setboot(1M)\f1 .\" index@\f1modify and display variables in the stable storage@@@\f3setboot(1M)\f1 .\" index@\f1variables in the stable storage, display and modify@@@\f3setboot(1M)\f1 .\" index@\f1stable storage, display and modify variables in@@@\f3setboot(1M)\f1 .\" index@\f1storage, stable, display and modify variables in @@@\f3setboot(1M)\f1 .\" $Header: setmnt.1m,v 72.7 94/11/30 14:27:20 ssa Exp $ .TA s .TH setmnt 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setmnt \- establish the file-system mount table, .CR /etc/mnttab .SH SYNOPSIS .C /usr/sbin/setmnt .SH DESCRIPTION The .CR setmnt command creates the .C /etc/mnttab table (see .IR mnttab (4)), which is needed by both the .C mount and .C umount commands (see .IR mount (1M)). .C setmnt reads the standard input and creates an entry in .C /etc/mnttab for each line of input. Input lines have the format: .IP .I filesys node .PP where .I filesys is the name of the device special file associated with the file system (such as .CR /dev/dsk/c0t5d0 ) and .I node is the root name of that file system. Thus .I filesys and .I node become the first two strings in the mount table entry. .SH WARNINGS The .C mount and .CR umount commands rewrite the .CR /etc/mnttab file whenever a file system is mounted or unmounted if .CR /etc/mnttab is found to be out of date with the mounted file system table maintained internally by the .SM HP-UX kernel. The .C syncer command also updates .CR /etc/mnttab if it is out of date (see .IR syncer (1M)). .PP .CR /etc/mnttab should never be manually edited. Use of this command to write invalid information into .CR /etc/mnttab is strongly discouraged. .PP The .C setmnt command is not intented to be run interactively; input should be directed to it from a file (for example, .CR "setmnt < /tmp/file.mnt" ). If run interactively, terminate input with a .CR "ctrl-D" . .PP .C setmnt silently enforces an upper limit on the maximum number of .C /etc/mnttab entries. .PP It is unwise to use .C setmnt to create false entries for .C mount and .CR umount . .PP This command is obsolete and it may not be available for future releases. .SH FILES .TP 25 .C /etc/mnttab Mounted file system table .SH SEE ALSO devnm(1M), mount(1M), syncer(1M), mnttab(4). .SH STANDARDS CONFORMANCE .CR setmnt ": SVID2, SVID3" .\" .\" index@\f4setmnt\f1 \- establish mount table \f4/etc/mnttab\f1@@@\f3setmnt(1M)\f1 .\" index@\f4mnttab\f1, establish mount table \f4/etc/mnttab\f1@@@\f3setmnt(1M)\f1 .\" index@mount table \f4/etc/mnttab\f1, establish@@@\f3setmnt(1M)\f1 .\" index@table \f4/etc/mnttab\f1, establish mount@@@\f3setmnt(1M)\f1 .\" index@\f4/etc/mnttab\f1, establish mount table@@@\f3setmnt(1M)\f1 .\" .\" toc@\f3setmnt(1M)\f1:\0\0\f4setmnt\f1@@@establish file-system mount table, /etc/mnttab .\" $Header: setprivgrp.1m,v 72.4 94/10/17 11:32:39 ssa Exp $ .TA s .TH setprivgrp 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setprivgrp \- set special privileges for groups .SH SYNOPSIS .CR setprivgrp .I groupname .RI [ privileges ] .PP .CR setprivgrp .CR \-g .RI [ privileges ] .PP .CR setprivgrp .CR \-n .RI [ privileges ] .PP .CR setprivgrp .CR \-f .I file .SH DESCRIPTION The .CR setprivgrp command associates a group with a list of privileges, thus providing access to certain system capabilities for members of a particular group or groups. The privileges can be displayed with the .CR getprivgrp command (see .CR getprivgrp (1)). .PP Privileges can be granted to individual groups, as defined in the .CR /etc/group file, and globally for all groups. .PP Only a superuser can use the .CR setprivgrp command. .SS Options and Arguments .CR setprivgrp recognizes the following options and arguments: .RS .TP 15 .IR privileges One or more of the keywords described below in "Privileged Capabilities". .TP .I groupname The name of a group defined in the file named .CR /etc/group . The current privileges for .IR groupname , if any, are replaced by the specified .IR privileges . To retain prior privileges, they must be respecified. .TP .CR \-g Specify global privileges that apply to all groups. The current privileges, if any, are replaced by the specified .IR privileges , To retain prior privileges, they must be respecified. .TP .CR \-n If no .I privileges are specified, delete all privileges for all groups, including global privileges. .IP If one or more .IR privileges are specified, delete the specified privileges from the current privilege lists of all groups, including the global privilege list, but do not delete unspecified privileges. .TP .CI \-f \0file Set the privileges according to entries in the file .IR file . This file is usually .CR /etc/privgroup . The entry formats are described below in "Group Privileges File Format". .RE .SS Privileged Capabilities The following system capabilities can be granted to groups: .RS .TP 15 .CR CHOWN Can use .CR chown() to change file ownerships (see .IR chown (2)). .TP .CR LOCKRDONLY Can use .CR lockf() to set locks on files that are open for reading only (see .IR lockf (2)). .\" NOTE: MPCTL remains undocumented in 10.0 per Paul Gootherts .\" even though it has appeared in usage messages; it is not supported .TP .CR MLOCK Can use .CR plock() to lock process text and data into memory, and the .CR shmctl() .CR SHM_LOCK function to lock shared memory segments (see .IR plock (2) and .IR shmctl (2)). .TP .CR RTPRIO Can use .CR rtprio() to set real-time priorities (see .IR rtprio (2)). .TP .CR RTSCHED Can use .CR sched_setparam() and .CR sched_setscheduler() to set POSIX.4 real-time priorities (see .IR rtsched (2)). .TP .CR SERIALIZE Can use .CR serialize() to force the target process to run serially with other processes that are also marked by this system call (see .IR serialize (2)). .TP .CR SETRUGID Can use .CR setuid() and .CR setgid() to change, respectively, the real user ID and real group ID of a process (see .IR setuid (2) and .IR setgid (2)). .RE .SS Group Privileges File Format The file specified with the .CR \-f option should contain one or more lines in the following formats: .IP .I groupname\c .RI \0[ privileges ] .IP .CR \-g\c .RI \0[ privileges ] .IP .CR \-n\c .RI \0[ privileges ] .PP They are described above in "Options and Arguments". .SH RETURN VALUE .CR setprivgrp exits with one of the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR >0 Failure. .PD .RE .SH AUTHOR .CR setprivgrp was developed by HP. .SH FILES .CR /etc/group .br .CR /etc/privgroup .SH SEE ALSO getprivgrp(1), chown(2), getprivgrp(2), lockf(2), plock(2), rtprio(2), rtsched(2), serialize(2), setgid(2), setuid(2), shmctl(2), privgrp(4). .\" .\" index@\f4setprivgrp\f1 \- set special privileges for group@@@\f3setprivgrp(1M)\f1 .\" index@\f1kernel capability, associate group with@@@\f3setprivgrp(1M)\f1 .\" index@\f1privileges, associate group with certain@@@\f3setprivgrp(1M)\f1 .\" index@\f1access privileges, associate group with@@@\f3setprivgrp(1M)\f1 .\" index@\f1privileges, associate group with certain@@@\f3setprivgrp(1M)\f1 .\" index@\f1appropriate privileges, associate group with certain@@@\f3setprivgrp(1M)\f1 .\" index@\f1group, associate with certain privileges@@@\f3setprivgrp(1M)\f1 .\" .\" toc@\f3setprivgrp(1M)\f1:\0\0\f4setprivgrp\f1@@@set special privileges for group .\" $Header: setuname.1m,v 72.2 94/07/22 16:18:42 ssa Exp $ .TA s .TH setuname 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setuname \- change machine information .SH SYNOPSIS .C setuname .RC [ -s .IR name ] .RC [ -n .IR node ] .RC [ -t ] .SH DESCRIPTION The .CR setuname command is used to modify the value for system name and/or the node name by using the appropriate option(s). .PP The .CR setuname command attempts to change the parameter values in both the running kernel and the system configuration to cross reboots. A temporary change affects only the running kernel. .SS Options The .CR setuname command supports the following options: .RS .TP 15 .CI -s " name" Changes the system name (e.g., HP-UX) in the .CR sysname field of the .CR utsname structure where .IR name is the new system name and consists of alphanumeric characters and the special characters dash, underbar, and dollar sign. .TP .CI -n " node" Changes the name in the .CR nodename field of the .CR utsname structure where .IR node specifies the new node name and consists of alphanumeric characters and the special characters dash, underbar, and dollar sign. .TP .C -t Signifies a temporary change. The change will not survive a reboot. .RE .PP Either or both of the .CR -s or .CR -n options must be given when invoking .CR setuname . .PP The size of the .IR name and .IR node is limited to .CR UTSLEN \(mi1 characters. .CR UTSLEN is defined in .CR . Only users having appropriate privileges can use this command. .SH EXAMPLES To permanently change the system name to .CR HP-UX and the node name to .CR the-node , issue the following command: .IP .C "setuname -s HP-UX -n the-node .PP To temporarily change the system name to .CR SYSTEM and the node name to .CR new-node , issue the following command: .IP .C "setuname -s SYSTEM -n new-node -t .SH SEE ALSO uname(1), uname(2). .\" .\" index@\f4setuname\f1 \- change machine information@@@\f3setuname(1M)\f1 .\" index@\f1change machine information@@@\f3setuname(1M)\f1 .\" index@\f1machine information, change@@@\f3setuname(1M)\f1 .\" .\" toc@\f3setuname(1M)\f1:\0\0\f4setuname\f1@@@change machine information\f1 .\" $Header: setup.1m,v 72.3 94/07/22 16:30:57 ssa Exp $ .TA s .TH setup 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setup \- set up the system for use .SH SYNOPSIS .C /usr/sbin/setup .SH DESCRIPTION The .CR setup command starts a menu-driven program that makes it easy for a privileged user to initiate or modify the system configuration. .CR setup offers context sensitive help at any point in the program by pressing the .CR F1 function key. Status messages show whether or not a task succeeded, and any errors that occurred. .PP The .CR setup command changes the system configuration in the following areas: .RS .TP Set the system clock: The user can set the date and time for the system. .TP Set the timezone: The user can select a timezone from a list of known timezones or enter a new TZ value. .TP Set the nodename: The user can set the .CR nodename field of the .CR utsname structure on the system. .TP Verify password protection on system accounts: The user can protect the system from unauthorized modification of the machine configuration and software by giving passwords to the administrative and maintenance functions. .IP The user can give passwords to system logins such as "root", "bin", etc. (provided they do not already have passwords). Once given a password, each login can only be changed by that login or by the superuser. .TP Add new users: The user is permitted to add logins to the system. .RE .SH DEPENDENCIES .CR setup runs in an X Windows environment as well as on VT100 terminals, and HP-compatible terminals with programmable function keys and on-screen display of function key labels. .RE .SH SEE ALSO passwd(1), setuname(1M), tztab(4). .\" index@\f4setup\f1 \- set up the system for use@@@\f3setup(1M)\f1 .\" index@\f1set up the system for use@@@\f3setup(1M)\f1 .\" index@\f1system, set up for use@@@\f3setup(1M)\f1 .\" .\" toc@\f3setup(1M)\f1:\0\0\f4setup\f1@@@set up the system for use\f1 ..\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Oct 25, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH show 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "DTS servers" "viewing characteristics" .iX "-[" "DTS clerks" "viewing characteristics" .iX "-[" "\*Ldtscp\*O commands" "\*Lshow\*O" .SH NAME .PP \*Lshow\*O - Displays current information about the DTS entity .SH "SYNOPSIS" .PP .zA "defect,6211,R1.0.3,add control program name" .sS \*Ldtscp show\*O \*Vattribute-group\*O | \*Vattribute-name\*O .sE .zZ "defect,6211,R1.0.3,add control program name" .SH "ARGUMENTS" .VL .LI "\*Vattribute-group\*O" The name of an attribute group or individual attribute to be displayed. The following values are valid: .ML .LI \*Lall\*O .LI \*Lall characteristics\*O .LI \*Lall counters\*O .LI \*Lall status\*O .LI \*Lglobal servers\*O .LI \*Llocal servers\*O .LE .LI "\*Vattribute-name\*O" The name of a specific attribute from the \*Lcharacteristics\*O, \*Lcounters\*O, or \*Lstatus\*O group. The attribute specifiers \*Lglobal servers\*O and \*Llocal servers\*O do not contain any other attributes. .LE .SH "DESCRIPTION" .PP The \*Lshow\*O command displays the names and values of the specified attributes or attribute groups. For attribute groups, if you do not supply a group name with the \*Lall\*O argument, all characteristics and their values are displayed. The following sections list names of individual attributes, categorized by group. .zA "defect,9002,R1.0.3,added info about output" .PP Note that the attributes displayed by the \*Lshow\*O command might be different, depending upon whether you have requested information about a server or a clerk. .zZ "defect,9002,R1.0.3,added info about output" .SS "Characteristics" .PP .zA "defect,5757,R1.0.2, Add info on maximum length and date format." Characteristic arguments can contain a maximum of 80 characters and are recalculated to a normalized date format. For example: .PP Input value: \*L0-0025:10:99.99999999\*O .nL Result: \*L1-01:11:39.990\*O .zZ "defect,5757,R1.0.2, Add info on maximum length and date format" .PP .VL .LI "\*Lacting courier role\*O" .PP .zA "defect,9002,R1.0.3,displayed for servers-only" Specifies whether a backup courier is currently functioning as a courier. If the role is \*Lnoncourier\*O, the node is not attempting to synchronize with global servers. This characteristic is shown only for servers. .zZ "defect,9002,R1.0.3,displayed for servers-only" .PP Default: \*Lnoncourier\*O .nL Value: \*Lcourier\*O or \*Lnoncourier\*O .PP .LI "\*Lautomatic tdf change\*O" .PP Specifies whether automatic changes to the time differential factor are enabled or disabled; the value is determined by the operating system. .PP Default: \*Ltrue\*O .nL Value: \*Ltrue/false\*O .PP .LI "\*Lcheck interval\*O" .PP .zA "defect,9002,R1.0.3,displayed for servers-only" Specifies the amount of time between checks for faulty servers. Applicable only to servers that have external time providers. This characteristic is shown only for servers. .zZ "defect,9002,R1.0.3,displayed for servers-only" .P Default: \*L0-01:30:00.00\*O .nL .zA "defect,5757,R1.0.2, Update maximum value to 10675199-02:48:05.478" Value: \*L0-00:00:30.000 - 10675199-02:48:05.478\*O .zZ "defect,5757,R1.0.2, Update maximum value to 10675199-02:48:05.478" .PP .LI "\*Lclock adjustment rate\*O" .PP Specifies the rate at which the DTS server or clerk entity adjusts the node's clock during a synchronization. .LI "\*Lclock resolution\*O" .PP Specifies the amount of time between system clock ticks. The value is determined by the operating system. .LI "\*Lcourier role\*O" .PP .zA "defect,9002,R1.0.3,displayed for servers-only" Specifies a server's interaction with the set of global servers. This characteristic is shown only for servers. .zZ "defect,9002,R1.0.3,displayed for servers-only" .VL .LI "\*Lbackup courier\*O" The local server becomes a courier if none are available on the LAN. .LI "\*Lcourier\*O" The local server synchronizes with the global set of servers. .LI "\*Lnoncourier\*O" The local server does not synchronize with the global set of servers. .LE .P Default: \*Lnoncourier\*O .LI "\*LDTS version\*O" .PP Specifies the DTS software version installed on the node. .LI "\*Lepoch number\*O" .PP .zA "defect,9002,R1.0.3,displayed for servers-only" Specifies the server's epoch number. The \*Lchange\*O command modifies this characteristic. This characteristic is shown only for servers. .zZ "defect,9002,R1.0.3,displayed for servers-only" .P Default: \*L0\*O .nL .zA "defect,5716,R1.0.2, Change value from '0-100' to '0-255'" Value: \*L0-255\*O .zZ "defect,5716,R1.0.2, Change value from '0-100' to '0-255'" .LI "\*Lerror tolerance\*O" .PP Specifies the maximum separation allowed between the local clock and the computed time before synchronizations become abrupt rather than gradual (monotonic). .PP Default: \*L0-00:10:00.000\*O .nL .zA "defect,5757,R1.0.2, Update maximum value to 10675199-02:48:05.478" Value: \*L0-00:00:00.500 - 10675199-02:48:05.478\*O .zZ "defect,5757,R1.0.2, Update maximum value to 10675199-02:48:05.478" .LI "\*Lglobal set timeout\*O" Specifies the amount of time the node waits for a response to a WAN synchronization request before sending another request or declaring a global server to be unavailable. The number of attempts made to reach the server is controlled by the \*Lquery attemps\*O characteristic. .PP Default: \*L0-00:00:15.000\*O .nL Value: \*L0-00:00:00.000 - 0-00:10:00.000\*O .LI "\*Llocal set timeout\*O" .PP Specifies the amount of time the node waits for a response to a synchronization request before sending another request or declaring a server to be unavailable. The number of attempts made to reach the server is controlled by the \*Lquery attemps\*O characteristic. .PP Default: \*L0-00:00:05.000\*O .nL .zA "defect,5757,R1.0.2, Update maximum value to 0-00:10:00.000" Value: \*L0-00:00:00.000 - 0-00:10:00.000\*O .zZ "defect,5757,R1.0.2, Update maximum value to 0-00:10:00.000" .zA "defect,8459,R1.0.3,local servers not a characteristic" .zZ "defect,8459,R1.0.3,local servers not a characteristic" .zA "defect,8459,R1.0.3,correct subcommand name" .LI "\*Llocal time differential factor\*O" .PP Specifies the Time Differential Factor (TDF), which is the amount of time the server varies from Greenwich mean time (GMT) or Coordinated Universal Time (UTC). .PP Default: \*L0-00:00:00.000\*O .nL Value: \*L-13-00:00:00 - 13-00:00:00\*O .zZ "defect,8459,R1.0.3,correct subcommand name" .LI "\*Lmaximum clock drift rate\*O" Specifies the worst-case drift rate of the node's clock, in nanoseconds per second, as determined by the manufacturer's specifications. .LI "\*Lmaximum inaccuracy\*O" .PP Specifies the inaccuracy limit for the node. When the node exceeds the maximum inaccuracy setting, it attempts to synchronize. .PP Default: \*L0-00:00:00.100\*O .nL .zA "defect,5757,R1.0.2, Update maximum value to '10675199-02:48:05.478'" Value: \*L0-00:00:00.0 - 10675199-02:48:05.478\*O .zZ "defect,5757,R1.0.2, Update maximum value to '10675199-02:48:05.478'" .LI "\*Lnext tdf change\*O" .PP Specifies the future time at which the time differential factor is automatically changed. The value is determined by the operating system. .LI "\*Lquery attempts\*O" .PP Specifies the number of attempts that a node makes to contact a server before the node considers the server unavailable. .PP Default: \*L3\*O .nL Value: \*L1-10\*O .LI "\*Lserver entry name\*O" .PP .zA "defect,9002,R1.0.3,displayed for servers-only" Specifies a server's ACL entry name; \*L\*O represents the name of the system or node that is the server's client. The default setting is the recommended value. This characteristic is shown only for servers. .zZ "defect,9002,R1.0.3,displayed for servers-only" .PP Default: \*L/.:/hosts//dts-entity\*O .LI "\*Lserver group name\*O" Specifies the security group name for the time servers within the cell. .PP .P Default: \*L/.:/subsys/dce/dts-servers\*O .LI "\*Lserver principal name\*O" .PP .zA "defect,9002,R1.0.3,displayed for servers-only" Specifies a server's principal name for authentication purposes; \*L\*O represents the name of the system or node that is the server's client. The default setting is the recommended value. This characteristic is shown only for servers. .zZ "defect,9002,R1.0.3,displayed for servers-only" .P .zA "defect,5757,R1.0.2, Update default: '/.:/hosts//self'" Default: \*L/.:/hosts//self\*O .zZ "defect,5757,R1.0.2, Update default: '/.:/hosts//self'" .LI "\*Lservers required\*O" .PP Specifies the minimum number of servers required for a synchronization. Settings of 1 or 2 may cause unreliable computed times. .P Default: \*L3\*O .nL .zA "defect,8035,R1.0.3, Update maximum value to '10'" .zA "defect,5757,R1.0.2, Update maximum value to '32'" Value: \*L1-10\*O .zZ "defect,5757,R1.0.2, Update maximum value to '32'" .zZ "defect,8035,R1.0.3, Update maximum value to '10'" .LI "\*Lsynchronization hold down\*O" .PP Specifies the interval a node must wait to synchronize. Also specifies synchronization frequency when a node reaches the value specified by the \*Lmaximum inaccuracy\*O characteristic. .PP Clerks: .PP Default: \*L0-00:10:00.0\*O .nL Value: \*L0-00:00:30.0 - 01 00:00:00.00\*O .PP Servers: .PP Default: \*L0-00:02.00.0\*O .nL Value: \*L0-00:00:30.0 - 01 00:00:00.00\*O .LI "\*Ltime provider present\*O" .PP Specifies whether or not the entity used an external time provider at the last successful synchronization. This attribute applies to servers only. .PP .LI "\*Ltime representation version\*O" .PP Specifies the timestamp format used by the node. .LI "\*Ltype\*O" .PP Specifies whether the node is a DTS server or clerk. The \*Lcreate\*O command modifies this characteristic. .LE .SS "Counters" .VL .LI "\*Lclock settings\*O" .PP Specifies the number of times the node clock has been set nonmonotonically (abruptly). .LI "\*Lcreation time\*O" .PP Specifies the time at which the DTS entity was created and the counters were initialized. .LI "\*Ldifferent epochs detected\*O" .PP .zA "defect,9002,R1.0.3,displayed for servers-only" Specifies the number of times the node received time response messages from servers or clerks that had epoch numbers different from its own. This counter is shown only for servers. .zZ "defect,9002,R1.0.3,displayed for servers-only" .LI "\*Ldisable directives completed\*O" .PP Specifies the number of times the DTS has been disabled. .LI "\*Lenable directives completed\*O" .PP Specifies the number of times the DTS has been enabled. .LI "\*Lepoch changes completed\*O" .PP Specifies the number of times the server's epoch has changed. .LI "\*Linsufficient resources detected\*O" .PP Specifies the number of times the node has been unable to allocate virtual memory. .zA "defect,8627,R1.0.3,deleted invalid messages detected" .zZ "defect,8627,R1.0.3,deleted invalid messages detected" .zA "defect,8627,R1.0.3,added counter" .LI "\*Llocal servers not in group .PP Specifies the number of times that a local server was contacted, but it was not in the \*Ldts\*O security group. .zZ "defect,8627,R1.0.3,added counter" .zA "defect,5757,R1.0.2, Change name to 'local times not intersecting'" .LI "\*Llocal times not intersecting\*O" .zZ "defect,5757,R1.0.2, Change name to 'local times not intersecting'" .PP Specifies the number of times the node's time interval failed to intersect with the computed interval of the servers. .LI "\*Lno global servers detected\*O" .PP .zA "defect,9002,R1.0.3,displayed for servers-only" Specifies the number of times the courier server could not contact any global servers. This counter is shown only for servers. .zZ "defect,9002,R1.0.3,displayed for servers-only" .LI "\*Lprotocol mismatches detected\*O" .PP Specifies the number of times the local node failed to process a received message containing an incompatible protocol version. .zA "defect,8627,R1.0.3,Added this counter" .LI "\*Lservers not in group\*O .PP .zA "defect,9002,R1.0.3,displayed for servers-only" Specifies the number of times that a non-local server was contacted, but it was not in the \*Ldts\*O security group. This counter is shown only for servers. .zZ "defect,9002,R1.0.3,displayed for servers-only" .zZ "defect,8627,R1.0.3,Added this counter" .LI "\*Lservers not responding\*O" .PP .zA "defect,9002,R1.0.3,displayed for servers-only" Specifies the number of times the courier server could not contact a specific global server. This counter is shown only for servers. .zZ "defect,9002,R1.0.3,displayed for servers-only" .zA "defect,5757,R1.0.2, Change name to 'servers times not intersecting'" .LI "\*Lservers times not intersecting\*O" .zZ "defect,5757,R1.0.2, Change name to 'servers times not intersecting'" .PP .zA "defect,9002,R1.0.3,displayed for servers-only" Specifies the number of times a server has detected faulty servers (other than itself). This counter is shown only for servers. .zZ "defect,9002,R1.0.3,displayed for servers-only" .LI "\*Lsynchronizations completed\*O" .PP Specifies the number of times the node successfully synchronized. .LI "\*Lsystem errors detected\*O" .PP Specifies the number of times a DTS operation detected a system error. .LI "\*Ltime provider failures detected\*O" .PP Specifies the number of times the external time provider signaled a failure or the node was unable to access the time provider. .zA "defect,8229,R1.0.3,add time provider timeouts detected" .LI "\*Ltime provider timeouts detected\*O" .PP .zA "defect,9002,R1.0.3,displayed for servers-only" Specifies the number of times a \*Ldtsd\*O server process initiated contact with a time provider and did not receive the initial response within the interval specified by \*Llocal set timeout\*O (the default interval is 5 seconds). This counter is shown only for servers. .zZ "defect,9002,R1.0.3,displayed for servers-only" .zZ "defect,8229,R1.0.3,add time provider timeouts detected" .LI "\*Ltime representation version mismatches detected\*O" .PP Specifies the number of times the local node failed to process a received message containing an incompatible timestamp format. .LI "\*Ltoo few servers detected\*O" .PP Specifies the number of times a node failed to synchronize because it could not contact the required minimum number of servers. ...\" .LI "\*Ltoo many servers detected\*O" ...\" .iX "too many servers detected counter" ...\" .PP ...\" Specifies the number of times the responses to a synchronization ...\" request overflowed the assigned system buffer. .LI "\*Lupdates initiated\*O" .PP .zA "defect,9002,R1.0.3,displayed for servers-only" Specifies the number of times a server has attempted to update its clock. This counter is shown only for servers. .zZ "defect,9002,R1.0.3,displayed for servers-only" .LE .SS "Status" .VL .LI "\*Lcurrent time\*O" .PP Specifies the current time on the node. .LI "\*Lglobal servers\*O" .PP Specifies the set of global servers known by the node. .LI "\*Llast synchronization\*O" .PP .zA "defect,10417,R1.1,show last sync should specify *attempted*" Specifies the computed time at the last attempted synchronization. .zZ "defect,10417,R1.1,show last sync should specify *attempted*" .LI "\*Llocal servers\*O" .PP Specifies the set of local servers known by the node. .LI "\*Lstate\*O" .PP Specifies the state of the DTS entity. .VL .LI "\*Loff\*O" The DTS entity is disabled. .LI "\*Lon\*O" The DTS entity is enabled. .LI "\*Lsynchronizing\*O" The DTS entity is synchronizing. .LI "\*Lupdating\*O" The DTS entity is updating the time. .LE .zA "defect,7844,R1.0.3,fixed misleading indent" .LI "\*Luid\*O" .PP .zA "defect,9002,R1.0.3,displayed for servers-only" Specifies the entity's unique identifier, which is generated when the entity is created. This attribute is shown only for servers. .zZ "defect,9002,R1.0.3,displayed for servers-only" .zZ "defect,7844,R1.0.3,fixed misleading indent" .LE .SS "Privilege Required" .PP You must have read permission on the ACL associated with the DTS entity in order to execute the command. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .zA "defect,4857,R1.0.2, Added command examples." .AL .LI The following command shows how to display the current time: .PP .iS \*Cdtscp>\*O \*Lshow current time\*O \*CCurrent Time = 1990-11-30-12:11:41.718-05:00I0.359 EST\*O .iE .zA "defect,7843,R1.0.3, Added command examples" .LI The following command shows how to display all of the entity's characteristic attribute settings: .iS \*Cdtscp>\*O \*Lshow all\*O \*CCheck Interval = +0-01:30:00.000I----- Epoch Number = 0 Error Tolerance = +0-00:10:00.000I----- Local Time Differential Factor = -0-04:00:00.000I----- Maximum Inaccuracy = +0-00:00:00.100I----- Servers Required = 3 Query Attempts = 3 Local Set Timeout = +0-00:00:05.000I----- Global Set Timeout = +0-00:00:15.000I----- Synchronization Hold Down = +0-00:02:00.000I----- Type = Server Courier Role = NonCourier Acting Courier Role = NonCourier Clock Adjustment Rate = 40000000 nsec/sec Maximum Clock Drift Rate = 1000000 nsec/sec Clock Resolution = 10000000 nsec DTS Version = V1.0.1 Time Representation Version = V1.0.0 Time Provider Present = FALSE Automatic TDF Change = FALSE Next TDF Change = 1993-10-31-06:00:00.000+00:00I0.000 Server Principal Name = hosts/system1/self Server Entry Name = hosts/system1/dts-entity Server Group Name = subsys/dce/dts-servers\*O .iE ...\"The following example was apparently added by Dave Kenney on 1/5/93 ...\"but was commented out for Release 1.0.2. ...\"\*CAdvertisement Interval = 0-01:20:00.000I0.000 ...\"Check Interval = 0-01:30:00.000I0.000 ...\"Error Tolerance = 0-00:10:00.000I0.000 ...\"Time Differential Factor = -0-05:00:00.000I0.000 ...\"Epoch Number = 0 ...\"Maximum Inaccuracy = 0-00:00:00.100I0.000 ...\"Servers Required = 3 ...\"Query Attempts = 3 ...\"LAN Timeout = 0-00:00:05.000I0.000 ...\"WAN Timeout = 0-00:00:15.000I0.000 ...\"Synchronization Hold Down = 0-00:02:00.000I0.000 ...\"Type = Server ...\"Courier Role = Backup Courier ...\"Clock Adjustment Rate = 100 ...\"Maximum Clock Drift Rate = 1 ...\"DTS Version = V1.0 ...\"Time Representation Version = V1.0\*O ...\".iE .LI The following command displays the current values of all characteristic attributes: .iS \*Cdtscp>\*O \*Lshow all characteristics\*O .iE .PP This command produces the same output as does the \*Lshow all\*O command. .cS \*CCheck Interval = +0-01:30:00.000I----- Epoch Number = 0 Error Tolerance = +0-00:10:00.000I----- Local Time Differential Factor = -0-04:00:00.000I----- Maximum Inaccuracy = +0-00:00:00.100I----- Servers Required = 3 Query Attempts = 3 Local Set Timeout = +0-00:00:05.000I----- Global Set Timeout = +0-00:00:15.000I----- Synchronization Hold Down = +0-00:02:00.000I----- Type = Server Courier Role = NonCourier Acting Courier Role = NonCourier Clock Adjustment Rate = 40000000 nsec/sec Maximum Clock Drift Rate = 1000000 nsec/sec Clock Resolution = 10000000 nsec DTS Version = V1.0.1 Time Representation Version = V1.0.0 Time Provider Present = FALSE Automatic TDF Change = FALSE Next TDF Change = 1993-10-31-06:00:00.000+00:00I0.000 Server Principal Name = hosts/system1/self Server Entry Name = hosts/system1/dts-entity Server Group Name = subsys/dce/dts-servers\*O .cE .LI The following command shows how to display all of the local servers known to the entity: .iS \*Cdtscp>\*O \*Lshow local servers\*O \*CKnown Servers ============================================================ Local /.../sisyphus.osf.org/hosts/system2/self Last Time Polled = 1993-10-15-21:01:46.124+00:00I0.809 Last Observed Time = 1993-10-15-21:03:09.041+00:00I----- Last Observed Skew = +0-00:01:22.917I----- Used in Last Synchronization = TRUE Transport Type = RPC Local /.../sisyphus.osf.org/hosts/system3/self Last Time Polled = 1993-10-15-21:01:46.124+00:00I0.809 Last Observed Time = 1993-10-15-21:01:46.143+00:00I0.817 Last Observed Skew = +0-00:00:00.019I1.625 Used in Last Synchronization = TRUE Transport Type = RPC\*O .iE ...\"The following example was apparently added by Dave Kenney on 1/5/93 ...\"but was commented out for Release 1.0.2. ...\"\*CKnown Servers ...\"============================================================== ...\"Local AA-00-00-00-00-01 (CDM) ...\"Last Time Polled = 1990-11-30-12:09:04.067-05:00I26.888 EST ...\"Last Observed Time = 1990-11-30-12:09:26.718-05:00I4.216 EST ...\"Last Observed Skew = 0-00:00:22.652 ...\"Used in Last Synchronization = TRUE ...\"Local AA-00-00-00-00-05 (DLM) ...\"Last Time Polled = 1990-11-30-12:09:04.067-05:00I26.888 EST ...\"Last Observed Time = 1990-11-30-12:09:26.723-05:00I4.221 EST ...\"Last Observed Skew = 0-00:00:22.657 ...\"Used in Last Synchronization = TRUE ...\"Local AA-00-00-00-00-03 (LMM) ...\"Last Time Polled = 1990-11-30-12:09:04.067-05:00I26.888 EST ...\"Last Observed Time = 1990-11-30-12:09:26.718-05:00I4.226 EST ...\"Last Observed Skew = 0-00:00:22.652 ...\"Used in Last Synchronization = TRUE ...\"Local AA-00-00-00-00-02 (JHM) ...\"Last Time Polled = 1990-11-30-12:09:04.067-05:00I26.888 EST ...\"Last Observed Time = 1990-11-30-12:09:26.708-05:00I4.226 EST ...\"Last Observed Skew = 0-00:00:22.642 ...\"Used in Last Synchronization = TRUE ...\"Local AA-00-00-00-00-04 (CLM) ...\"Last Time Polled = 1990-11-30-12:09:04.067-05:00I26.888 EST ...\"Last Observed Time = 1990-11-30-12:09:26.718-05:00I4.216 EST ...\"Last Observed Skew = 0-00:00:22.652 ...\"Used in Last Synchronization = TRUE)\*O ...\".iE .LI The following command displays the current values of all counter attributes: .PP .iS \*Cdtscp>\*O \*Lshow all counters\*O \*CCreation Time = 1993-10-14-16:23:57.801+00:00I0.767 Local Times Not Intersecting = 0 Server Times Not Intersecting = 0 Different Epochs Detected = 0 Too Few Servers Detected = 0 Time Provider Timeouts Detected = 1 Protocol Mismatches Detected = 0 Time Representation Mismatches Detected = 0 No Global Servers Detected = 0 Servers Not Responding = 0 Clock Settings = 0 Epoch Changes Completed = 0 System Errors Detected = 0 Synchronizations Completed = 865 Updates Initiated = 0 Enable Directives Completed = 1 Disable Directives Completed = 0 Insufficient Resources Detected = 0 Time Provider Failures Detected = 0 Local server not in group = 0 Servers not in group = 0\*O .iE .LI The following command displays the current values of all status attributes: .PP .iS \*Cdtscp>\*O \*Lshow all status\*O \*CUID = 00004e34-5e1c-2c87-8500-08005a0d4582 Last Synchronization = 1993-10-15-21:05:43.023+00:00I----- State = On\*O .iE .LI The following command displays the current value of the courier role attribute: .PP .iS \*Cdtscp>\*O \*Lshow courier role\*O \*CCourier Role = NonCourier\*O .iE .LI The following command displays the server entry name for this server: .PP .iS \*Cdtscp>\*O \*Lshow server entry name\*O \*CServer Entry Name = hosts/system1/dts-entity\*O .iE .LI The following command displays the current state of the Time Service entity: .PP .iS \*Cdtscp>\*O \*Lshow state\*O \*CState = On\*O .iE .LI The following command displays the current value of the check interval attribute: .PP .iS \*Cdtscp>\*O \*Lshow check interval\*O \*CCheck Interval = +0-01:30:00.000I-----\*O .iE .LI The following command displays the current value of the servers times not intersecting counter: .PP .iS \*Cdtscp>\*O \*Lshow servers times not intersecting\*O \*CServer Times Not Intersecting = 0\*O .iE .LE .zZ "defect,4857,R1.0.2, Added command examples." .zZ "defect,7843,R1.0.3, Added command examples" .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lset(1m)\*O .wH "" .wH "" .iX "-]" "DTS servers" "viewing characteristics" .iX "-]" "DTS clerks" "viewing characteristics" .iX "-]" "\*Ldtscp\*O commands" "\*Lshow\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed. Dec 11, 1991 Update file submission for ...\" V 1.0 final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "show cached clearinghouse" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "clearinghouses" "viewing cached" .iX "-[" "\*Lcdscp\*O commands" "\*Lshow cached clearinghouse\*O" .SH NAME .PP \*Lshow cached clearinghouse\*O - Displays current information about the specified cached clearinghouse .wH "" .SH "SYNOPSIS" .PP .sS \*Lcdscp show cached clearinghouse\*O \*Vclearinghouse-name \*O .sE .wH "" .SH "ARGUMENT" .VL .LI "\*Vclearinghouse-name\*O" A specific clearinghouse name. The name can contain wildcard characters. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lshow cached clearinghouse\*O command displays all the names and values of the attributes in the specified cached clearinghouse. The following are valid attributes: .iX "cached clearinghouse entity" .VL .LI "\*LCreation Time\*O" Specifies the time at which this clearinghouse was added to the cache .LI "\*LMiscellaneous Operations\*O" Specifies the number of operations other than read and write (that is, skulks, new epochs, and so on) performed by this clerk on the cached clearinghouse .LI "\*LRead Operations\*O" Specifies the number of lookup operations of any sort performed by the clerk on the cached clearinghouse .LI "\*LTowers\*O" Specifies the protocol sequence and Internet address of the server that maintains the cached clearinghouse .LI "\*LWrite Operations\*O" Specifies the number of write operations performed by this clerk on the cached clearinghouse .LE .SS "Privilege Required" .PP You must have read permission to the clerk. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command displays all attributes of the cached clearinghouse \*L/.:/Paris2_CH\*O. .iS \*Ccdscp>\*L show cached clearinghouse /.:/Paris2_CH \*O \*C SHOW CACHED CLEARINGHOUSE /.../abc.com/Paris2_CH AT 1991-10-15-15:58:09 Creation Time = 1991-10-01-17:03:32.32 Read Operations = 412 Write Operations = 618 Miscellaneous Operations = 278\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Llist clearinghouse(1m)\*O .wH "" .wH "" .iX "-]" "clearinghouses" "viewing cached" .iX "-]" "\*Lcdscp\*O commands" "\*Lshow cached clearinghouse\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "show cached server" 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "cache" "viewing server addresses" .iX "-[" "CDS servers" "viewing cached addresses" .iX "-[" "\*Lcdscp\*O commands" "\*Lshow cached server\*O" .SH NAME .PP \*Lshow cached server\*O - Displays address information of a server in the local clerk's cache .SH "SYNOPSIS" .sS \*Lshow cached server\*V name\*O .sE .SH "ARGUMENTS" .VL .LI "\*Vname\*O" A simple name for the cached server. The name can contain wildcard characters. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lshow cached server\*O command displays address information of a server in the local clerk's cache. The following list describes the valid attributes: .VL .LI "\*LName\*O" The directory cell name .LI "\*LTowers\*O" The protocol sequence and network address of the server node .LE .SS "Privilege Required" .PP You must have read permission to the clerk. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .PP The following command displays all attributes of the cached server \*Lemv\*O. .iS \*Ccdscp> \*Lshow cached server emv*\*O \*C SHOW CACHED NAMESERVER emv_udp AT 1991-10-15-15:56:56 Name = /.../emv.abc.com Tower = ncadg_ip_udp:14.20.14.32 Tower = ncacn_ip_tcp:14.20.14.32 SHOW CACHED NAMESERVER emv_tcp AT 1991-10-15-15:56:57 Name = /.../emv.abc.com Tower = ncadg_ip_udp:14.20.14.32 Tower = ncacn_ip_tcp:14.20.14.32\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lclear cached server(1m)\*O, \*Ldefine cached server(1m)\*O .wH "" .wH "" .iX "-]" "cache" "viewing server addresses" .iX "-]" "CDS servers" "viewing cached addresses" .iX "-]" "\*Lcdscp\*O commands" "\*Lshow cached server\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "show cdscp confidence" 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "clearinghouses" "preferred" .iX "\*Lcdscp\*O commands" "\*Lshow cdscp preferred clearinghouse\*O" .SH NAME \*Lshow cdscp confidence\*O - Displays the current confidence level of clerk calls resulting from CDS control program commands .wH "" .SH "SYNOPSIS" .sS \*Lcdscp\*O \*Lshow cdscp confidence\*O .sE .SH "DESCRIPTION" The \*Lshow cdscp confidence\*O command displays the current confidence level of clerk calls. A low confidence level means the clerk obtains information from caches or the most convenient server. A medium level means the clerk obtains information directly from a server. A high level means the clerk obtains information only at master replicas. .PP You must use this command within the CDS control program. Exiting from the CDS control program removes the confidence level setting. You must reset the confidence level each time you enter the CDS control program. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command may be replaced in future releases by the \*Ldcecp\*O command, and may no longer be supported at that time. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" The following command displays the current confidence level of clerk calls: .iS \*C$ \*Lcdscp\*O \*Ccdscp> \*Lshow cdscp confidence\*O \*C Confidence used is medium\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lset cdscp confidence(1m)\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "show cdscp preferred clearinghouse" 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "clearinghouses" "preferred" .iX "\*Lcdscp\*O commands" "\*Lshow cdscp preferred clearinghouse\*O" .SH NAME \*Lshow cdscp preferred clearinghouse\*O - Displays the preferred clearinghouse for satisfying read requests that result from CDS control program commands .wH "" .SH "SYNOPSIS" .sS \*Lcdscp\*O \*Lshow cdscp preferred clearinghouse\*O .sE .SH "DESCRIPTION" The \*Lshow cdscp preferred clearinghouse\*O command displays the preferred clearinghouse for satisfying read requests that result from CDS control program commands. You can only read attribute values for entries stored in the specified clearinghouse. .PP You must use this command within the CDS control program. Exiting from the CDS control program removes the preferred clearinghouse setting. You must reset the preferred clearinghouse each time you enter the CDS control program. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" The following command displays the current clearinghouse: .iS \*C$ \*Lcdscp\*O \*Ccdscp> \*Lshow cdscp preferred clearinghouse\*O \*C read attribute values from clearinghouse /.../abc.com/Paris_CH\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lset cdscp preferred clearinghouse(1m)\*O .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "show cell"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "Domain Name Service (DNS)" "defining cell names" .iX "-[" "Global Directory Service (GDS)" "defining cell names" .iX "-[" "cell names" "creating" .iX "-[" "\*Lcdscp\*O commands" "\*Lshow cell\*O" .SH NAME .PP \*Lshow cell\*O - Displays the information you need to create a cell entry in either DNS or GDS .wH "" .SH "SYNOPSIS" .PP .zA "defect,4723,R1.0.2, "Corrected syntax" .sS \*Lcdscp show cell \*O \*Vcell-name\*O [\*Las\*O \*Vtype\*O] .sE .zZ "defect,4723,R1.0.2, "Corrected syntax" .wH "" .SH "ARGUMENTS" .VL .LI "\*Vcell-name\*O" The global name of the cell. .LI "\*Vtype\*O" The global namespace in which you want to define the cell. Enter either of the values \*Ldns\*O or \*Lgds\*O. The default is \*Lgds\*O. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lshow cell\*O command displays the information you need to create a cell entry in either the Domain Name System (DNS) or the Global Directory Service (GDS). DCE does not support cells registered simultaneously in GDS and DNS. If you want to define a cell in DNS, you can use this command to produce a preformatted set of resource records. You can then edit the appropriate DNS data file and copy the output directly into the file. In GDS, cell information is contained in two attributes: \*LCDS-Cell\*O and \*LCDS-Replica\*O. If you want to define a cell in GDS, you can use this command to obtain the data you need to supply when creating the \*LCDS-Cell\*O and \*LCDS-Replica\*O attributes. For details, see the \*VOSF DCE Administration Guide\*O. .SS "Privilege Required" .PP You must have read permission to the cell root directory. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command may be replaced in future releases by the \*Ldcecp\*O command, and may no longer be supported at that time. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .PP The following command displays the GDS-formatted output in the local cell: .iS \*Ccdscp>\*L show cell /.../abc.com as gds\*O \*C SHOW CELL /.../abc.com AT 1991-10-15-15:58:25 Namespace Uuid = 2d2d50ad-8b1a-11ba-8983-08002b0f79aa Clearinghouse Uuid = 2ab024a8-8b1a-11ba-8983-08002b0f79aa Clearinghouse Name = /.../abc.com/NY_CH Replica Type = Master Tower 1 = ncadg_ip_udp:16.18.17.33 Tower 2 = ncacn_ip_tcp:16.18.17.33 Namespace Uuid = 2d2d50ad-8b1a-11ba-8983-08002b0f79aa Clearinghouse Uuid = 49757f28-8b1a-11ba-8983-08002b0f79aa Clearinghouse Name = /.../abc.com/Boston_CH Replica Type = Readonly Tower 1 = ncadg_ip_udp:16.18.17.33 Tower 2 = ncacn_ip_tcp:16.18.17.33 .iE .wH "" .SH "RELATED INFORMATION" .PP Books: \*VOSF DCE Administration Guide\*O .wH "" .wH "" .iX "-]" "Domain Name Service (DNS)" "defining cell names" .iX "-]" "Global Directory Service (GDS)" "defining cell names" .iX "-]" "cell names" "creating" .iX "-]" "\*Lcdscp\*O commands" "\*Lshow cell\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed. Dec 11, 1991 Update file submission for ...\" V 1.0 final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "show child"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "child pointers" "viewing attributes" .iX "-[" "\*Lcdscp\*O commands" "\*Lshow child\*O" .SH NAME .PP \*Lshow child\*O - Displays attribute information about the specified child pointer .wH "" .SH "SYNOPSIS" .PP .sS \*Lcdscp show child\*O \*Vchild-name\*O [\*Vattribute-name\*O] [\*Lwith\*O \*Vattribute-name = attribute-value\*O] .sE .wH "" .SH "ARGUMENTS" .VL .LI "\*Vchild-name\*O" The full name of a specific child pointer. The last simple name can contain wildcard characters. .LI "\*Vattribute-name\*O" The name of an attribute; see \*LDescription\*O for valid attribute names. .LI "\*Vattribute-value\*O" The value of a particular attribute. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lshow child\*O command displays the names and values of the attributes specified in \*Vattribute-name\*O. You can use a combination of attributes in a single command. Use a space to separate multiple attributes. You can use a \*Lwith\*O \*Vattribute-name = attribute-value\*O clause to limit output only to child pointers whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). .P If you do not supply any attributes, the command displays all attributes and their values. The following is a description of child pointer attributes: .iX "child entity" .VL .LI "\*LCDS_CTS\*O" Specifies the creation timestamp (CTS) of the specified child pointer. .LI "\*LCDS_ObjectUUID\*O" Specifies the unique identifier of the directory to which the child pointer refers. .LI "\*LCDS_Replicas\*O" Specifies the address, UUID, and name of a set of clearinghouses where a copy of the child directory referenced by the child pointer is located. This attribute also specifies whether the directory in a particular clearinghouse is a master or read-only replica. .LI "\*LCDS_UTS\*O" Specifies the timestamp of the most recent update to an attribute of the child pointer. .LE .SS "Privilege Required" .PP You must have read permission to the child pointer. If you specify a wildcard child name, you also need read permission to the parent directory. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command displays all of the attributes and values of the child directory to which the child pointer \*L/.:/admin\*O refers: .iS \*Ccdscp> \*Lshow child /.:/admin\*O \*C SHOW CHILD /.../abc.com/admin AT 1991-10-15-15:56:01 CDS_CTS = 1991-10-15-19:55:52.000000003/08-00-2b-1c-8f-1f CDS_UTS = 1991-10-15-19:55:52.000000006/08-00-2b-1c-8f-1f CDS_ObjectUUID = 6b5362e8-8b1c-11ca-8981-08002b0f79aa CDS_Replicas = : Clearinghouse's UUID = 2ab024a8-8b1a-11ca-8981-08002b0f79aa Tower = ncadg_ip_udp:16.18.16.32 Tower = ncacn_ip_tcp:16.18.16.32 Replica type = master Clearinghouse's Name = /.../abc.com/Boston_CH\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lcreate child(1m)\*O, \*Ldelete child(1m)\*O, \*Llist child(1m)\*O .wH "" .wH "" .iX "-]" "child pointers" "viewing attributes" .iX "-]" "\*Lcdscp\*O commands" "\*Lshow child\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed Oct 30, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "show clearinghouse" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "clearinghouses" "viewing attributes" .iX "-[" "\*Lcdscp\*O commands" "\*Lshow clearinghouse\*O" .SH NAME .PP \*Lshow clearinghouse\*O - Displays attribute information about the specified clearinghouse .wH "" .SH "SYNOPSIS" .PP .sS \*Lcdscp show clearinghouse\*O \*Vclearinghouse-name\*O [\*Vattribute-name\*O]\*O [\*Lwith\*O \*Vattribute-name = attribute-value\*O] .sE .wH "" .SH "ARGUMENTS" .VL .LI "\*Vclearinghouse-name\*O" The full name of a specific clearinghouse. The last simple name can contain wildcard characters. .LI "\*Vattribute-name\*O" The name of a particular attribute; see \*LDescription\*O for valid attribute names. .LI "\*Vattribute-value\*O" The value of a particular attribute. .LE .wH "" .SH "DESCRIPTION" .PP The \*Lshow clearinghouse\*O command displays the names and values of the attributes specified in \*Vattribute-name\*O. You can use a combination of attributes in any sequence in a single command. Use a space to separate multiple attributes. You can use a \*Lwith\*O \*Vattribute-name = attribute-value\*O clause to limit output only to clearinghouses whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). .P If you do not supply any attributes, the command displays all attributes and their values. The following list describes the clearinghouse attributes: .VL .LI "\*LCDS_AllUpTo\*O" Indicates the date and time the clearinghouse object has been updated to reflect the \*LCDS_CHDirectories\*O attribute. .LI "\*LCDS_CHDirectories\*O" Specifies the full name and unique identifier (UUID) of every directory that has a replica in this clearinghouse. .LI "\*LCDS_CHLastAddress\*O" Specifies the current reported network address of the clearinghouse. .LI "\*LCDS_CHName\*O" Specifies the full name of the clearinghouse. .LI "\*LCDS_CHState\*O" Specifies the state of the clearinghouse. The state \*Von\*O indicates the clearinghouse is running and available. .zA "def,CR 8033,R1.0.3,CDS_CellnametoCDS_NSCellname " .LI "\*LCDS_NSCellname\*O" .zZ "def,CR 8033,R1.0.3,CDS_CellnametoCDS_NSCellname" Specifies the name of the cell in which the clearinghouse resides. .LI "\*LCDS_CTS\*O" Specifies the creation timestamp (CTS) of the clearinghouse. .LI "\*LCDS_DirectoryVersion\*O" Specifies the directory version for new directories that are created in the clearinghouse. .LI "\*LCDS_ObjectUUID\*O" Specifies the unique identifier of the clearinghouse. .LI "\*LCDS_ReplicaVersion\*O" Specifies the current version of the replica in which the directory was created. .LI "\*LCDS_UTS\*O" Specifies the timestamp of the most recent update to an attribute of the clearinghouse. .LE .zA "def,8031,R1.0.3,'attribs'->'counters' & correct wording" .PP The following counters and their values are displayed only when you use this command to display all attributes and their values: .VL .LI "\*LData Corruption Count\*O" Specifies the number of times that the \*Vdata corruption\*O event was generated .LI "\*LEnables\*O" Specifies the number of times that the clearinghouse was enabled since it was last started .LI "\*LRead Accesses\*O" Specifies the number of read operations directed to this clearinghouse .LI "\*LReferences Returned\*O" Specifies the number of requests directed to this clearinghouse that resulted in the return of a partial answer instead of satisfying the client's request .LI "\*LSkulk Failures\*O" Specifies the number of times that a skulk of a directory, initiated from this clearinghouse, failed to complete\(em usually because one of the replicas in the replica set was unreachable .LI "\*LEntry Missing Count\*O" Specifies the number of times the \*Vclearinghouse entry missing\*O event was generated .LI "\*LRoot Not Reachable Count\*O" Specifies the number of times the \*Vroot lost\*O event was generated .LI "\*LUpgrades Failed Counts\*O" Specifies the number of times that upgrades failed .LI "\*LWrite Accesses\*O" Specifies the number of write operations directed to this clearinghouse .LI "\*LDisables\*O" Specifies the number of times that the clearinghouse was disabled since it wsa last started .LE .zZ "def,8031,R1.0.3,'attribs'->'counters' & correct wording" .SS "Privilege Required" .PP You must have read permission to the clearinghouse. If you specify a wildcard clearinghouse name, you also need read permission to the cell root directory. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command displays the current values of the \*LCDS_UTS\*O and \*LCDS_ObjectUUID\*O attributes associated with the \*L/.:/Chicago1_CH\*O clearinghouse: .iS \*Ccdscp> \*Lshow clearinghouse /.:/Chicago1_CH CDS_UTS CDS-ObjectUUID \*C SHOW CLEARINGHOUSE /.../abc.com/Chicago1_CH AT 1991-10-21-13:12:30 CDS_UTS = 1991-10-21-13:04:04.000000009/08-00-2b-1c-8f-1f CDS_ObjectUUID = 3706d70c-8b05-11ca-9002-08002b1c8f1f\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lclear clearinghouse(1m)\*O, \*Lcreate clearinghouse(1m)\*O, \*Ldelete clearinghouse(1m)\*O, \*Llist clearinghouse(1m)\*O, \*Lset cdscp preferred clearinghouse(1m)\*O, \*Lshow cdscp preferred clearinghouse(1m)\*O .wH "" .wH "" .iX "-]" "clearinghouses" "viewing attributes" .iX "-]" "\*Lcdscp\*O commands" "\*Lshow clearinghouse\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed. Dec 11, 1991 Update file submission for ...\" V 1.0 final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "show clerk" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "CDS clerks" "viewing attributes" .iX "-[" "\*Lcdscp\*O commands" "\*Lshow clerk\*O" .SH NAME .PP \*Lshow clerk\*O - Displays attribute information about the CDS clerk on the local system .wH "" .SH "SYNOPSIS" .PP .sS \*Lcdscp show clerk\*O .sE .wH "" .SH "DESCRIPTION" .PP .zA "defect,5006,R1.0.2, Added description" The \*Lshow clerk\*O command displays all the names and values of the clerk attributes on the local system. The clerk must be enabled when you use this command. The following are valid attributes: .zZ "defect,5006,R1.0.2, Added description" .iX "clerk entity" .PP .VL .LI "\*LAuthentication Failures\*O" Specifies the number of times a requesting principal failed authentication procedures. .LI "\*LCache Bypasses\*O" Specifies the number of requests to read attributes for which the clerk was specifically directed by the requesting application to bypass its own cache. Instead, a server is contacted to get the requested information. This attribute does not account for requests that the clerk is unable to satisfy from the cache or for requests to look up names or enumerate the contents of directories. .LI "\*LCache Hits\*O" Specifies the total number of read requests directed to this clerk that were satisfied entirely by the information contained in its own cache. This attribute accounts only for requests to read attribute values and does not include requests to look up names or enumerate the contents of directories. .LI "\*LCreation Time\*O" Specifies the time when this entity was created. .LI "\*LMiscellaneous Operations\*O" Specifies the number of operations other than read and write (that is, skulks, enumerating contents of directories, and so on) performed by this clerk. .LI "\*LRead Operations\*O" Specifies the number of lookup operations performed by this clerk. This attribute accounts only for requests to read attributes and does not include requests to look up names or enumerate the contents of directories. .LI "\*LWrite Operations\*O" Specifies how many requests to modify data were processed by this clerk. .LE .SS "Privilege Required" .PP You must have read permission to the clerk. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command may be replaced in future releases by the \*Ldcecp\*O command, and may no longer be supported at that time. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command displays the attributes of the clerk on the local system: .iS \*Ccdscp>\*L show clerk\*O \*C SHOW CLERK AT 1991-10-15-15:56:50 Creation Time = 1991-10-15-15:38:19.000000051-04:00I0.000000000 Authentication failures = 0 Read Operations = 1068 Cache Hits = 137 Cache bypasses = 433 Write operations = 1250 Miscellaneous operations = 590\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ldisable clerk(1m)\*O .wH "" .wH "" .iX "-]" "CDS clerks" "viewing attributes" .iX "-]" "\*Lcdscp\*O commands" "\*Lshow clerk\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed. Dec 11, 1991 Update file submission for ...\" V 1.0 final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "show directory"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "directories" "viewing attributes (CDS)" .iX "-[" "\*Lcdscp\*O commands" "\*Lshow directory\*O" .SH NAME .PP \*Lshow directory\*O - Displays attribute information about the specified directory .wH "" .SH "SYNOPSIS" .PP .sS \*Lcdscp show directory\*O \*Vdirectory-name\*O [\*Vattribute-name\*O] [\*Lwith\*O \*Vattribute-name = attribute-value\*O] .sE .wH "" .SH "ARGUMENTS" .VL .LI "\*Vdirectory-name\*O" The full name of a specific directory. The last simple name can contain wildcard characters. .LI "\*Vattribute-name\*O" The name of a particular attribute; see \*LDescription\*O for valid attribute names. .LI "\*Vattribute-value\*O" The value of a particular attribute. .LE .wH "" .SH "DESCRIPTION" .zA "edit,10578,R1.1,Removed inchname and ringpointer' .zA "enh,10578,R1.1,Added CDS_UpgradeTo attribute" .PP The \*Lshow directory\*O command displays the names and values of the attributes specified in \*Vattribute-name\*O. You can use a combination of attributes in any sequence in a single command. Use a space to separate multiple attributes. You can use a \*Lwith\*O \*Vattribute-name = attribute-value\*O clause to limit output only to directories whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). If you do not supply any attributes, the command displays all attributes and their values. In addition to the following directory attributes, application-specific attributes can exist for a directory: .iX "directory entity" .VL .LI "\*LCDS_AllUpTo\*O" Indicates the date and time of the last successful skulk on the directory. All replicas of the directory are guaranteed to receive all updates whose timestamps are less than the value of this attribute. .LI "\*LCDS_Convergence\*O" Specifies the degree of consistency among replicas. This attribute's value is defined as one of the following: .VL .LI "\*Llow\*O" CDS does not immediately propagate an update. The next skulk distributes all updates that occurred since the previous skulk. Skulks occur at least once every 24 hours. .LI "\*Lmedium\*O" CDS attempts to immediately propagate an update to all replicas. If the attempt fails, the next scheduled skulk makes the replicas consistent. Skulks occur at least once every 12 hours. .LI "\*Lhigh\*O" CDS attempts to immediately propagate an update to all replicas. If the attempt fails (for example, if one of the replicas is unavailable), a skulk is scheduled for within one hour. Skulks usually occur at least once every 12 hours. Use this setting temporarily and briefly, because it uses extensive system resources. .LE .PP By default, every directory inherits the convergence setting of its parent at creation time. The default setting on the root directory is \*Lmedium\*O. .LI "\*LCDS_CTS\*O" Specifies the creation timestamp (CTS) of the CDS directory. .LI "\*LCDS_DirectoryVersion\*O" Specifies the minimum of all the values of the \*LCDS_ReplicaVersion\*O attribute on the directory replicas. .LI "\*LCDS_Epoch\*O" A UUID that identifies a particular incarnation of the directory. .LI "\*LCDS_LastSkulk\*O" Records the timestamp of the last skulk performed on this directory. .LI "\*LCDS_LastUpdate\*O" Records the timestamp of the most recent change to any attribute of a directory replica, or any change to an entry in the replica. .LI "\*LCDS_ObjectUUID\*O" Specifies the unique identifier of the directory. .LI "\*LCDS_ParentPointer\*O" Contains a pointer to this directory's parent in the namespace. .LI "\*LCDS_Replicas\*O" Specifies the address, UUID, and name of every clearinghouse where a copy of this directory is located. This attribute also specifies whether the replica in a particular clearinghouse is a master or read-only replica. .LI "\*LCDS_ReplicaState\*O" Specifies whether a directory replica can be accessed. .LI "\*LCDS_ReplicaType\*O" Indicates whether a directory replica is a master or read-only replica. .LI "\*LCDS_ReplicaVersion\*O" Specifies the version of a replica of the directory. .zA "def,10309,R1.1,add CDS_RingPointer attribute" .LI "\*LCDS_RingPointer\*O" Specifies the UUID of a clearinghouse containing another replica of this directory. This attribute is written by the system and is read-only to users. It will appear on older directories, but \*Enot\*O on DCE 1.1 directories. .zZ "def,10309,R1.1,add CDS_RingPointer attribute" .LI "\*LCDS_UpgradeTo\*O" Controls the upgrading of a directory from one version of CDS to another. By modifying this attribute, you can initiate the upgrading of a directory to a new version of CDS. .LI "\*LCDS_UTS\*O" Specifies the timestamp of the most recent update to an attribute of the directory. .zA "def,10309,R1.1,add RPC_ClassVersion attribute" .LI "\*LRPC_ClassVersion\*O" Specifies the RPC runtime software version that can be used to import on the directory. .zZ "def,10309,R1.1,add RPC_ClassVersion attribute" .LE .zZ "enh,10578,R1.1,Added CDS_UpgradeTo attribute" .zZ "edit,10578,R1.1,Removed inchname and ringpointer" .SS "Privilege Required" .PP You must have read permission to the directory. If you specify a wildcard directory name, you also need read permission to the directory's parent directory. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command displays the current values of all the attributes associated with the \*L/.:/admin\*O directory: .zA "def,10309,R1.1,add RPC_ClassVersion attribute" .iS \*Ccdscp>\*L show directory /.:/admin\*O \*C SHOW DIRECTORY /.../abc.com/admin AT 1991-10-15-15:43:59 RPC_ClassVersion = 0100 CDS_CTS = 1991-10-15-13:09:47.000000003/08-00-2b-1c-8f-1f CDS_UTS = 1991-10-17-08:59:50.000000006/08-00-2b-1c-8f-1f CDS_ObjectUUID = ba700c98-8b1a-11ca-8981-08002b0f79aa CDS_Replicas = : Clearinghouse's UUID = 2ab024a8-8b1a-11ca-8981-08002b0f79aa Tower = ncadg_ip_udp:16.20.16.32 Tower = ncacn_ip_tcp:16.20.16.32 Replica type = master Clearinghouse's Name = /.../abc.com/Paris_CH CDS_AllUpTo = 1991-10-17-08:51:18.000000032/08-00-2b-1c-8f-1f CDS_Convergence = medium CDS_ParentPointer = : Parent's UUID = b773525c-8b1a-11ca-8981-08002b0f79aa Timeout = : Expiration = 1991-10-16-19:43:50.516 Extension = +1-00:00:00.000 CDS_DirectoryVersion = 3.0 CDS_ReplicaState = on CDS_ReplicaType = master CDS_LastSkulk = 1991-10-17-08:51:18.000000032/08-00-2b-1c-8f-1f CDS_LastUpdate = 1991-10-21-13:04:02.000000044/08-00-2b-1c-8f-1f CDS_RingPointer = 2ab024a8-8b1a-11ca-8981-08002b0f79aa CDS_Epoch = bd8b2c50-8b1a-11ca-8981-08002b0f79aa CDS_ReplicaVersion = 3.0\*O .iE .zZ "def,10309,R1.1,add RPC_ClassVersion attribute" .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ladd directory(1m)\*O, \*Lcreate directory(1m)\*O, \*Ldelete directory(1m)\*O, \*Llist directory(1m)\*O, \*Lremove directory(1m)\*O, \*Lset directory(1m)\*O .wH "" .wH "" .iX "-]" "directories" "viewing attributes (CDS)" .iX "-]" "\*Lcdscp\*O commands" "\*Lshow directory\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed. Dec 11, 1991 Update file submission for ...\" V 1.0 final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "show link"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "soft links" "viewing attributes" .iX "-[" "\*Lcdscp\*O commands" "\*Lshow link\*O" .SH NAME .PP \*Lshow link\*O - Displays attribute information about the specified soft link .wH "" .SH "SYNOPSIS" .PP .sS \*Lcdscp show link\*O \*Vlink-name\*O [\*Vattribute-name\*O] [\*Lwith\*O \*Vattribute-name = attribute-value\*O] .wH "" .sE .SH "ARGUMENTS" .VL .LI "\*Vlink-name\*O" The full name of a specific soft link. The last simple name can contain wildcard characters. .LI "\*Vattribute-name\*O" The name of a particular attribute; see \*LDescription\*O for valid attribute names. .LI "\*Vattribute-value\*O" The value of a particular attribute. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lshow link\*O command displays the names and values of the attributes specified in \*Vattribute-name\*O. You can use a combination of attributes in any sequence in a single command. Use a space to separate multiple attributes. You can use a \*Lwith\*O \*Vattribute-name = attribute-value\*O clause to limit output only to soft links whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). If you do not supply any attributes, the command displays all attributes and their values. The following is a description of soft link attributes: .iX "link entity" .VL .LI "\*LCDS_CTS\*O" Specifies the creation timestamp (CTS) of this soft link .LI "\*LCDS_LinkTarget\*O" Specifies the full name of the directory, object entry, or other soft link to which the soft link points .LI "\*LCDS_LinkTimeout\*O" Specifies a timeout value after which the soft link is either checked or deleted .LI "\*LCDS_UTS\*O" Specifies the timestamp of the most recent update to an attribute of the soft link .LE .SS "Privilege Required" .PP You must have read permission to the soft link. If you specify a wildcard soft link name, you also need read permission to the directory that stores the soft link. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command displays the current values of all the attributes associated with the soft link \*L/.:/sales/region1\*O. .iS \*Ccdscp>\*L show link /.:/sales/region1\*O \*C SHOW SOFTLINK /.../abc.com/sales/region1 AT 1991-10-15-15:54:40 CDS_CTS = 1991-10-15-19:54:35.00000003/08-00-2b-1c-8f-1f CDS_UTS = 1991-10-15-19:54:35.00000006/08-00-2b-1c-8f-1f CDS_LinkTarget = /.../abc.com/sales/service SHOW SOFTLINK /.../abc.com/sales/region1 AT 1991-10-15-15:54:41 CDS_CTS = 1991-10-15-19:54:36.00000077/08-00-2b-1c-8f-1f CDS_UTS = 1991-10-15-19:54:36.00000009/08-00-2b-1c-8f-1f CDS_LinkTarget = /.../abc.com/sales/software CDS_LinkTimeout = : Expiration = 1991-10-15-00:00:00.0 Extension = +1-00:00:00.000\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lcreate link(1m)\*O, \*Ldelete link(1m)\*O, \*Llist link(1m)\*O, \*Lremove link(1m)\*O, \*Lset link(1m)\*O .wH "" .wH "" .iX "-]" "soft links" "viewing attributes" .iX "-]" "\*Lcdscp\*O commands" "\*Lshow link\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed. Dec 11, 1991 Update file submission for ...\" V 1.0 final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "show object"1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "objects" "viewing attributes" .iX "-[" "\*Lcdscp\*O commands" "\*Lshow object\*O" .SH NAME .PP \*Lshow object\*O - Displays attribute information about the specified object entry .wH "" .SH "SYNOPSIS" .PP .sS \*Lcdscp show object\*O \*Vobject-name\*O [\*Vattribute-name\*O] [\*Lwith\*O \*Vattribute-name = attribute-value\*O] .wH "" .sE .SH "ARGUMENTS" .VL .LI "\*Vobject-name\*O" The full name of a specific object entry. The last simple name can contain wildcard characters. .LI "\*Vattribute-name\*O" The name of a particular attribute; see \*LDescription\*O for valid attribute names. .LI "\*Vattribute-value\*O" The value of a particular attribute. .wH "" .LE .SH "DESCRIPTION" .PP The \*Lshow object\*O command displays the names and values of the attributes specified in \*Vattribute-name\*O. You can use a combination of attributes in a single command. Use a space to separate multiple attributes. You can use a \*Lwith\*O \*Vattribute-name = attribute-value\*O clause to limit output only to object entries whose attributes have values equal to the specified values. If you do not supply any attributes, the command displays all attributes and their values. In addition to the following attributes, any application-defined attributes that might exist will be included in the output of this command. The following is a description of object entry attributes: .iX "object entity" .VL .LI "\*LCDS_Class\*O" Specifies the class to which an object belongs. .LI "\*LCDS_ClassVersion\*O" Contains the version number of the object's class. This allows applications to build in compatibility with entries created by earlier versions. .LI "\*LCDS_CTS\*O" Specifies the creation timestamp (CTS) of this object entry. .LI "\*LCDS_ObjectUUID\*O" Specifies a unique identifier for the object being referenced. .LI "\*LCDS_UTS\*O" Specifies the timestamp of the most recent update to an attribute of the object entry. .LE .SS "Privilege Required" .PP You must have read permission to the object entry. If you specify a wildcard object entry name, you also need read permission to the directory that stores the object entry. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command lists all the attributes and their values of the object entry \*L/.:/sales/east/floor1cp\*O. .iS \*Ccdscp>\*L show object /.:/sales/east/floor1cp\*O \*C SHOW OBJECT /.../abc.com/sales/floor1cp AT 1991-10-15-15:53:07 CDS_CTS = 1991-10-15-19:53:03.00000003/08-00-2b-1c-8f-1f CDS_UTS = 1991-10-15-19:53:03.00000006/08-00-2b-1c-8f-1f\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Ladd object(1m)\*O, \*Lcreate object(1m)\*O, \*Ldelete object(1m)\*O, \*Llist object(1m)\*O, \*Lremove object(1m)\*O, \*Lset object(1m)\*O .wH "" .wH "" .iX "-]" "objects" "viewing attributes" .iX "-]" "\*Lcdscp\*O commands" "\*Lshow object\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed. Dec 11, 1991 Update file submission for ...\" V 1.0 final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "show replica" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "replicas" "viewing attributes (CDS)" .iX "-[" "\*Lcdscp\*O commands" "\*Lshow replica\*O" .SH NAME .PP \*Lshow replica\*O - Displays attribute information about the specified replica .wH "" .SH "SYNOPSIS" .PP .sS \*Lcdscp show replica\*O \*Vdirectory-name\*O \*Lclearinghouse\*O \*Vclearinghouse-name\*O [\*Vattribute-name\*O] .sE .wH "" .SH "ARGUMENTS" .VL .LI "\*Vdirectory-name\*O" The full name of the directory .LI "\*Vclearinghouse-name\*O" The full name of the clearinghouse .LI "\*Vattribute-name\*O" The name of a particular attribute; see \*LDescription\*O for valid attribute names. .wH "" .LE .SH "DESCRIPTION" .zA "edit,10578,R1.1,Removed inchname and ringpointer" .PP .zA "def,8056,R1.0.3,add that command displays application-defined attributes" The \*Lshow replica\*O command displays the directory-specific attributes as well as the per-replica attributes of the specified directory. If you do not supply any attributes, the command displays all attributes and their values; any application-defined attributes that might exist will be included in the output of this command. You can enter one or more of the following attributes: .zZ "def,8056,R1.0.3,add that command displays application-defined attributes" .VL .LI "\*LCDS_AllUpTo\*O" Indicates the date and time of the last successful skulk on the directory. All replicas of the directory are guaranteed to have received all updates whose timestamps are less than the value of this attribute. .LI "\*LCDS_Convergence\*O" Specifies the degree of consistency among replicas. This attribute's value is defined as one of the following: .VL .LI "\*Llow\*O" CDS does not immediately propagate an update. The next skulk distributes all updates that occurred since the previous skulk. Skulks occur at least once every 24 hours. .LI "\*Lmedium\*O" CDS attempts to immediately propagate an update to all replicas. If the attempt fails, the next scheduled skulk makes the replicas consistent. Skulks occur at least once every 12 hours. .LI "\*Lhigh\*O" CDS attempts to immediately propagate an update to all replicas. If the attempt fails (for example, if one of the replicas is unavailable), a skulk is scheduled for within one hour. Skulks usually occur at least once every 12 hours. Use this setting temporarily and briefly, because it uses extensive system resources. .LE .PP By default, every directory inherits the convergence setting of its parent at creation time. The default setting on the root directory is \*Lmedium\*O. .LI "\*LCDS_CTS\*O" Specifies the creation timestamp (CTS) of the directory of which this replica is a copy. .LI "\*LCDS_DirectoryVersion\*O" Specifies the minimum of all the values of the \*LCDS_ReplicaVersion\*O attribute on the directory replicas. .LI "\*LCDS_Epoch\*O" A UUID that identifies a particular incarnation of the directory. .LI "\*LCDS_LastSkulk\*O" Records the timestamp of the last skulk performed on this particular replica of a directory. .LI "\*LCDS_LastUpdate\*O" Records the timestamp of the last update to any attribute of the replica, or any change to the contents of the replica, including object entries, child pointers, and soft links. .LI "\*LCDS_ObjectUUID\*O" Specifies the unique identifier of the directory of which this replica is a copy. .LI "\*LCDS_ParentPointer\*O" Contains a pointer to this directory's parent in the namespace. .LI "\*LCDS_Replicas\*O" Specifies the address, UUID, and name of every clearinghouse where a replica of this directory is located. This attribute also specifies whether the replica in a particular clearinghouse is a master or read-only replica. .LI "\*LCDS_ReplicaState\*O" Specifies the internal state of a replica. When you create or delete a replica, it goes through various states. .LI "\*LCDS_ReplicaType\*O" Specifies the replica type of a directory. .LI "\*LCDS_ReplicaVersion\*O" Specifies the replica version of a directory. .zA "def,10309,R1.1,add CDS_RingPointer attribute" .LI "\*LCDS_RingPointer\*O" Specifies the UUID of a clearinghouse containing another replica of this directory. This attribute is written by the system and is read-only to users. It will appear on older directories, but \*Enot\*O on DCE 1.1 directories. .zZ "def,10309,R1.1,add CDS_RingPointer attribute" .LI "\*LCDS_UTS\*O" Specifies the timestamp of the most recent update to an attribute of the directory. .zA "def,10309,R1.1,add RPC_ClassVersion attribute" .LI "\*LRPC_ClassVersion\*O" Specifies the RPC runtime software version that can be used to import on the directory. .zZ "def,10309,R1.1,add RPC_ClassVersion attribute" .LE .zZ "edit,10578,R1.1,Removed inchname and ringpointer" .SS "Privilege Required" .PP You must have read permission to the directory from which the replica is created. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command displays the current values of all the attributes of the replica of the \*L/.:/eng\*O directory in the \*L/.:/Chicago2_CH\*O clearinghouse: .zA "def,10309,R1.1,add RPC_ClassVersion attribute" .iS \*Ccdscp>\*L show replica /.:/eng clearinghouse /.:/Chicago2_CH \*C SHOW REPLICA /.../abc.com/eng AT 1991-10-15-15:55:29 RPC_ClassVersion = 0100 CDS_CTS = 1991-10-15-12:09:47.000000003/08-00-2b-1c-8f-1f CDS_UTS = 1991-10-17-07:59:50.000000006/08-00-2b-1c-8f-1f CDS_ObjectUUID = 5816da70-8b1c-11ca-8981-08002b0f79aa CDS_Replicas = : Clearinghouse's UUID = 2ab024a8-8b1a-11ca-8981-08002b0f79aa Tower = ncadg_ip_udp:16.20.16.32 Tower = ncacn_ip_tcp:16.20.16.32 Replica type = master Clearinghouse's Name = /.../abc.com/Chicago1_CH CDS_Replicas = : Clearinghouse's UUID = 49757f28-8b1a-11ca-8981-08002b0f79aa Tower = ncadg_ip_udp:16.20.16.32 Tower = ncacn_ip_tcp:16.20.16.32 Replica type = readonly Clearinghouse's Name = /.../abc.com/Chicago2_CH CDS_AllUpTo = 1991-10-17-07:51:18.000000032/08-00-2b-1c-8f-1f CDS_Convergence = medium CDS_ParentPointer = : Parent's UUID = 560f1ad0-8b1c-11ca-8981-08002b0f79aa Timeout = : Expiration = 1991-10-15-19:55:18.711 Extension = +1-00:00:00.000 CDS_DirectoryVersion = 3.0 CDS_ReplicaState = on CDS_ReplicaType = readonly CDS_LastSkulk = 1991-10-17-07:51:18.000000032/08-00-2b-1c-8f-1f CDS_LastUpdate = 1991-10-21-12:04:02.000000044/08-00-2b-1c-8f-1f CDS_RingPointer = 2ab024a8-8b1a-11ca-8981-08002b0f79aa CDS_Epoch = 58472144-8b1c-11ca-8981-08002b0f79aa CDS_ReplicaVersion = 3.0\*O .zA "def,10309,R1.1,add RPC_ClassVersion attribute" .iE .wH "" .SH "RELATED INFORMATION" .PP Commands: \*Lcreate replica(1m)\*O, \*Ldelete replica(1m)\*O .wH "" .wH "" .iX "-]" "replicas" "viewing attributes (CDS)" .iX "-]" "\*Lcdscp\*O commands" "\*Lshow replica\*O" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Wed. Dec 11, 1991 Update file submission for ...\" V 1.0 final integration at IBM. ...\" ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH "show server" "1m" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "-[" "CDS servers" "viewing attributes" .iX "-[" "\*Lcdscp\*O commands" "\*Lshow server\*O" .SH NAME .PP \*Lshow server\*O - Displays attribute information about the server running on the local system .wH "" .SH "SYNOPSIS" .PP .sS \*Lcdscp show server\*O .wH "" .sE .SH "DESCRIPTION" .PP .zA "defect,5006,R1.0.2, Added description" The \*Lshow server\*O command displays all the names and values from the attributes named in this entity. The server must be enabled when you use this command. The following are valid attribute names: .zZ "defect,5006,R1.0.2, Added description" .iX "server entity" .VL .LI "\*LChild Update Failures\*O" Specifies the number of times the server was unable to contact all the clearinghouses that store a replica of a particular child directory's parent directory and apply the child updates that have occurred since the last skulk. This counter is incremented by the \*CCannot Update Child Pointer\*O event. .LI "\*LCreation Time\*O" Specifies the time when the CDS control program process was started. .LI "\*LCrucial Replicas\*O" Specifies the number of times a user attempted (from this server) to remove a replica that is crucial to the connectivity of a directory hierarchy. The server background process prevents users from accidentally disconnecting lower-level directories from higher-level directories. When it detects an attempt to remove a crucial replica, it does not execute the command to do so. This counter is incremented by the \*CCrucial Replica\*O event. .LI "\*LFuture Skew Time\*O" Specifies the maximum amount of time that a timestamp on a new or modified entry can vary from local system time at the server system. .LI "\*LKnown Clearinghouses\*O" Specifies the clearinghouse or clearinghouses known to the server. .LI "\*LRead Operations\*O" Specifies the number of read operations directed to this CDS server. .LI "\*LSecurity Failures\*O" Specifies the number of times a server principal for this server was found to have inadequate permissions to perform a requested operation. .LI "\*LSkulks Completed\*O" Specifies the number of skulks successfully completed by this CDS server. .LI "\*LSkulks Initiated\*O" Specifies the number of skulks initiated by this CDS server. .LI "\*LTimes Lookup Paths Broken\*O" Specifies the number of broken connections between clearinghouses on this server and clearinghouses closer to the root. Incoming requests to this server that require a downward lookup in the directory hierarchy still succeed, but requests that require a lookup in directories closer to the root will fail. This counter is incremented by the \*CBroken Lookup Paths\*O event. .LI "\*LWrite Operations\*O" Specifies the number of write operations to this CDS server. .LE .SS "Privilege Required" .PP You must have read permission to the server. .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command may be replaced in future releases by the \*Ldcecp\*O command, and may no longer be supported at that time. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLE" .PP The following command displays the current values of all the attributes associated with the server running on the local system: .iS \*Ccdscp>\*L show server\*O \*C SHOW SERVER AT 1991-10-15-15:56:47 Creation Time = 1991-10-15-15:39:35.35 Future Skew Time = 300 Read Operations = 757 Write Operations = 542 Skulks Initiated = 219 Skulks Completed = 219 Times Lookup Paths Broken = 1 Crucial Replicas = 0 Child Update Failures = 1 Security Failures = 0 Known Clearinghouses = /.../abc.com/Boston_CH = /.../abc.com/NY_CH\*O .iE .wH "" .SH "RELATED INFORMATION" .PP Command: \*Ldisable server(1m)\*O .wH "" .wH "" .iX "-]" "CDS servers" "viewing attributes" .iX "-]" "\*Lcdscp\*O commands" "\*Lshow server\*O" .\" $Header: showmount.1m,v 72.5 94/08/09 12:06:19 ssa Exp $ .TA s .TH showmount 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME showmount \- show all remote mounts .SH SYNOPSIS .C /usr/sbin/showmount .RC [ -a ] .RC [ -d ] .RC [ -e ] .RI [ \|host\| ] .SH DESCRIPTION .C showmount lists all clients that have remotely mounted a filesystem from .IR host . This information is maintained by the .C mountd server on .I host (see .IR mountd (1M)). The default value for .I host is the value returned by .C hostname (see .IR hostname (1)). .SS Options .TP 5 .C -a Print all remote mounts in the format .RS .IP .IC name : directory .RE .IP where .I hostname is the name of the client, and .I directory is the directory or root of the file system that was mounted. .TP .C -d List directories that have been remotely mounted by clients. .TP .C -e Print the list of exported file systems. .SH WARNINGS If a client crashes, executing .C showmount on the server will show that the client still has a file system mounted. In other words, the client's entry is not removed from .C /etc/rmtab until the client reboots and executes: .IP .C umount -a .PP Also, if a client mounts the same remote directory twice, only one entry appears in .CR /etc/rmtab . Doing a .C umount of one of these directories removes the single entry and .C showmount no longer indicates that the remote directory is mounted. .SH AUTHOR .C showmount was developed by Sun Microsystems, Inc. .SH SEE ALSO hostname(1), exportfs(1M), mountd(1M), exports(4), rmtab(4). .\" .\" index@\f4showmount\f1 \- show all remote mounts@@@\f3showmount(1M)\f1 .\" index@\f1show all remote mounts@@@\f3showmount(1M)\f1 .\" index@\f1remote mounts, show all@@@\f3showmount(1M)\f1 .\" index@\f1mounts, show all remote@@@\f3showmount(1M)\f1 .\" .\" toc@\f3showmount(1M)\f1:\0\0\f4showmount\f1@@@show all remote mounts .\" $Header: acctsh.1m,v 72.4 94/11/14 12:02:10 ssa Exp $ .TA a .TH acctsh 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chargefee, ckpacct, dodisk, lastlogin, monacct, nulladm, prctmp, prdaily, prtacct, shutacct, startup, turnacct \- shell procedures for accounting .SH SYNOPSIS .C /usr/sbin/acct/chargefee .I login-name number .PP .C /usr/sbin/acct/ckpacct .RI [ \|blocks\| ] .PP .C /usr/sbin/acct/dodisk .RC [ -o ] .RI [ \|files \0 ...\|] .PP .C /usr/sbin/acct/lastlogin .PP .C /usr/sbin/acct/monacct .I number .PP .C /usr/sbin/acct/nulladm .I file .PP .C /usr/sbin/acct/prctmp .PP .C /usr/sbin/acct/prdaily .RC [ -l ] .RC [ -c ] .RC [ \c .IR mmdd\| ] .PP .C /usr/sbin/acct/prtacct .I file .RI [ \|heading\| ] .PP .C /usr/sbin/acct/shutacct .RI [ \|reason\| ] .PP .C /usr/sbin/acct/startup .PP .C /usr/sbin/acct/turnacct .CR on \0\(or\0 off \0\(or\0 switch .SH DESCRIPTION .TP 15 .C chargefee Can be invoked to charge a .I number of units to .IR login-name . A record is written to .CR /var/adm/fee , to be merged with other accounting records during the night. .TP .C ckpacct Should be initiated via .IR cron (1M). It periodically checks the size of .CR /var/adm/pacct . If the size exceeds .IR blocks , 1000 by default, .C turnacct is invoked with argument .IR switch . If the number of free disk blocks in the .C /var file system falls below 500, .C ckpacct automatically turns off the collection of process accounting records via the .C off argument to .CR turnacct . When at least this number of blocks is restored, the accounting will be activated again. This feature is sensitive to the frequency at which .C ckpacct is executed, usually by .CR cron . .TP .C dodisk Should be invoked by .C cron to perform the disk accounting functions. By default, it will do disk accounting on the special files in .C /etc/fstab. If the .C -o flag is used, it does a slower version of disk accounting by login directory. .I files specifies the one or more filesystem names where disk accounting is to be done. If .I files is used, disk accounting will be done on these filesystems only. If the .C -o flag is used, .I files should be mount points of mounted filesystem. If omitted, they should be the special file names of mountable filesystems. .TP .C lastlogin Invoked by .C runacct to update .C /var/adm/acct/sum/loginlog which shows the last date on which each user logged in (see .IR runacct (1M)). .TP .C monacct Should be invoked once each month or each accounting period. .I number indicates which month or period it is. If .I number is not given, it defaults to the current month (01 through 12). This default is useful if .C monacct is to executed via .CR cron on the first day of each month. .C monacct creates summary files in .C /var/adm/acct/fiscal and restarts summary files in .CR /var/adm/acct/sum . .TP .C nulladm Creates .I file with mode 664 and ensures that owner and group are .CR adm . It is called by various accounting shell procedures. .TP .C prctmp Can be used to print the session record file normally .C /var/adm/acct/nite/ctmp created by .C acctcon1 (see .IR acctcon (1M)). .TP .C prdaily Invoked by .C runacct (see .IR runacct (1M)) to format a report of the previous day's accounting data. The report resides in .CI /var/adm/acct/sum/rprt mmdd where .I mmdd is the month and day of the report. The current daily accounting reports may be printed by typing .IR prdaily . Previous days' accounting reports can be printed by using the .I mmdd option and specifying the exact report date desired. The .C -l flag prints a report of exceptional usage by login id for the specifed date. Previous daily reports are cleaned up and therefore inaccessible after each invocation of .CR monacct . The .C -c flag prints a report of exceptional resource usage by command, and can be used on current day's accounting data only. .TP .C prtacct Can be used to format and print any total accounting .RC ( tacct ) file. .TP .C shutacct Should be invoked during a system shutdown to turn process accounting off and append a ``reason'' record to .CR /var/adm/wtmp . .TP .C startup Should be called by system startup scripts to turn the accounting on whenever the system is brought up. .TP .C turnacct An interface to .C accton (see .IR acct (1M)) to turn process accounting .C on or .CR off . The .C switch argument turns accounting off, moves the current .C /var/adm/pacct to the next free name in .CI /var/adm/pacct incr then turns accounting back on again. .RI ( incr is a number starting with .C 1 and incrementing by one for each additional .C pacct file.) .C turnacct is called by .CR ckpacct , and thus can be run under .C cron and used to keep .C pacct to a reasonable size. .SH FILES .TP 40 .C /usr/sbin/acct holds all accounting commands listed in section (1M) of this manual .PD 0 .TP .C /var/adm/fee accumulator for fees .TP .C /var/adm/acct/nite working directory .TP .C /var/adm/pacct current file for per-process accounting .TP .C /var/adm/pacct* used if .C pacct gets large, and during execution of daily accounting procedure .TP .C /usr/sbin/acct/ptecms.awk contains the limits for exceptional usage by command name .TP .C /usr/sbin/acct/ptelus.awk contains the limits for exceptional usage by login id .TP .C /var/adm/acct/sum summary directory, should be saved .TP .C /var/adm/wtmp login/logoff summary .PD .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), cron(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR chargefee ": SVID2, SVID3" .PP .CR ckpacct ": SVID2, SVID3" .PP .CR dodisk ": SVID2, SVID3" .PP .CR lastlogin ": SVID2, SVID3" .PP .CR monacct ": SVID2, SVID3" .PP .CR prctmp ": SVID2, SVID3" .PP .CR prdaily ": SVID2, SVID3" .PP .CR prtacct ": SVID2, SVID3" .PP .CR shutacct ": SVID2, SVID3" .PP .CR startup ": SVID2, SVID3" .PP .CR turnacct ": SVID2, SVID3" .\" .\" .\" index@\f1process accounting@@@see accounting .\" index@\f1accounting: \f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4turnacct\f1 \- turn on or turn off process accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1bill fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1user, bill fee to, based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1disk accounting, perform@@@\f3acctsh(1M)\f1 .\" index@\f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1user, show last login date for each@@@\f3acctsh(1M)\f1 .\" index@\f1last login date, show for each user@@@\f3acctsh(1M)\f1 .\" index@\f1login date, show last for each user@@@\f3acctsh(1M)\f1 .\" index@\f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1periodic accounting summary files, create@@@\f3acctsh(1M)\f1 .\" index@\f1accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1files: accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1summary files, accounting, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1create empty administration file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1empty administration file owned by \f3adm\f1 with mode 664, create@@@\f3acctsh(1M)\f1 .\" index@\f1administration file owned by \f3adm\f1 with mode 664, create empty@@@\f3acctsh(1M)\f1 .\" index@\f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f4acctcon1\f1 \- print session record file created by@@@\f3acctsh(1M)\f1 .\" index@\f1print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1files, accounting: print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1session record file created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f1record file, session, created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1total accounting (\f4tacct\f1) file, print any@@@\f3acctsh(1M)\f1 .\" index@\f1accounting (\f4tacct\f1) file, print any total@@@\f3acctsh(1M)\f1 .\" index@\f4tacct\f1 (total accounting) file, print any@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting: \f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" index@\f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting data and command usage summary, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f1command usage summary and accounting data, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1system shutdown, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f1shutdown, system, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1system startup, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f1startup, system, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f4turnacct\f1 \- turn process accounting on or off@@@\f3acctsh(1M)\f1 .\" index@\f1shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f1system accounting, shell procedures for@@@\f3acctsh(1M)\f1 .\" .\"" Main TOC entry .\" toc@\f3acctsh(1M)\f1:\0\0\f4chargefee\f1, \f4ckpacct\f1, \f4dodisk\f1, \f4lastlogin\f1, \f4monacct\f1, \f4nulladm\f1, \f4prctmp\f1, \f4prdaily\f1,\n\f4prtacct\f1, \f4shutacct\f1, \f4startup\f1, \f4turnacct\f1@@@shell procedures for accounting .\" .\" toc@\f4chargefee\f1:\0\0shell procedures for accounting, charge fee to user@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4ckpacct\f1:\0\0shell procedures for accounting, check size of accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4dodisk\f1:\0\0shell procedures for accounting, perform disk accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4lastlogin\f1:\0\0shell procedures for accounting, show last login date@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4monacct\f1:\0\0shell procedures for accounting, create accounting summary@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4nulladm\f1:\0\0shell procedures for accounting, create null file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prctmp\f1:\0\0shell procedures for accounting, print session record file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prdaily\f1:\0\0shell procedures for accounting, print daily report@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prtacct\f1:\0\0shell procedures for accounting, print accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4shutacct\f1:\0\0shell procedures for accounting, turn off accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4startup\f1:\0\0shell procedures for accounting, start up accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4turnacct\f1:\0\0shell procedures for accounting, turn on or off process accounting@@@\f1see \f3acctsh(1M)\f1 .\" .\" links@acctsh.1m chargefee.1m .\" links@acctsh.1m ckpacct.1m .\" links@acctsh.1m dodisk.1m .\" links@acctsh.1m lastlogin.1m .\" links@acctsh.1m monacct.1m .\" links@acctsh.1m nulladm.1m .\" links@acctsh.1m prctmp.1m .\" links@acctsh.1m prdaily.1m .\" links@acctsh.1m prtacct.1m .\" links@acctsh.1m shutacct.1m .\" links@acctsh.1m startup.1m .\" links@acctsh.1m turnacct.1m .\" .\" fileset_database@acctsh.1m SYS-ADMIN-MAN .\" $Header: shutdown.1m,v 76.1 95/08/07 11:43:28 ssa Exp $ .TA s .TH shutdown 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shutdown \- terminate all processing .SH SYNOPSIS .CR /sbin/shutdown .RC [ \-h \(or \-r ] .RC [ \-y ] .RC [ \-o ] .RI [ grace ] .SH DESCRIPTION The .CR shutdown command is part of the HP-UX system operation procedures. Its primary function is to terminate all currently running processes in an orderly and cautious manner. .CR shutdown can be used to put the system in single-user mode for administrative purposes such as backup or file system consistency checks (see .IR fsck (1M)), and to halt or reboot the system. By default, .CR shutdown is an interactive program. .SS Options and Arguments .CR shutdown recognizes the following options and arguments. .RS .TP 10 .CR \-h Shut down the system and halt. .TP .CR \-r Shut down the system and reboot automatically. .TP .CR \-y Do not require any interactive responses from the user. (Respond .CR yes or .CR no as appropriate to all questions, such that the user does not interact with the shutdown process.) .TP .CR \-o When executed on the cluster .I server in a diskless cluster environment, shutdown the .I server only and do not reboot .I clients. If this argument is not entered the default behavior is to reboot all .I clients when the .I server is shutdown. .TP .I grace Either a decimal integer that specifies the duration in seconds of a grace period for users to log off before the system shuts down, or the word .CR now . The default is 60. If .I grace is either 0 or .CR now , .C shutdown runs more quickly, giving users very little time to log out. .PP If neither .C -r (reboot) nor .C -h (halt) is specified, .I standalone and .I server systems are placed in single-user state. Either .C -r (reboot) or .C -h (halt) must be specified for a .I client; shutdown to single-user state is not allowed for a .I client. See .IR dcnodes(1M), .IR init (1M). .RE .SS Shutdown Procedure .CR shutdown goes through the following steps: .RS .TP 3 \(bu The .CR PATH environment variable is reset to .CR /usr/bin:/usr/sbin:/sbin . .TP \(bu The .CR IFS environment variable is reset to space, tab, newline. .TP \(bu The user is checked for authorization to execute the .CR shutdown command. Only authorized users can execute the .CR shutdown command. See FILES for more information on the .C /etc/shutdown.allow authorization file. .TP \(bu The current working directory is changed to the root directory .RC ( / ). .TP \(bu All file systems' super blocks are updated; see .IR sync (1M). This must be done before rebooting the system to ensure file system integrity. .TP \(bu The real user ID is set to that of the superuser. .TP \(bu A broadcast message is sent to all users currently logged in on the system telling them to log out. The administrator can specify a message at this time; otherwise, a standard warning message is displayed. .TP \(bu The next step depends on whether a system is .I standalone, a .I server, or a .I client. .RS .TP 3 \(bu If the system is .I standalone, .CR /sbin/rc is executed to shut down subsystems, unmount file systems, and perform other tasks to bring the system to run level 0. .TP 3 \(bu If the system is a .I server, the optional .C -o argument is used to determine if all .I clients in the cluster should also be rebooted. The default behavior (command line parameter .C -o is not entered) is to reboot all .I clients using .C /sbin/reboot; entering .C -o results in the .I server only being rebooted and the .I clients being left alone. Then .CR /sbin/rc is executed to shut down subsystems, unmount file systems, and perform other tasks to bring the system to run level 0. .TP 3 \(bu If the system is a .I client, .CR /sbin/rc is executed to bring the system down to run-level 2, and then .C /sbin/reboot is executed. Shutdown to the single-user state is not an allowed option for .I clients. .RE .TP \(bu The system is rebooted or halted by executing .CR /sbin/reboot if the .CR \-h or .CR \-r option was chosen. If the system was not a cluster client and the system was being brought down to single-user state, a signal is sent to the .CR init process to change states (see .IR init (1M)). .RE .PP .SH DIAGNOSTICS .TP .C "device busy" .IP This is the most commonly encountered error diagnostic, and happens when a particular file system could not be unmounted; see .IR mount (1M). .TP .C "user not allowed to shut down this system" .IP User is not authorized to shut down the system. User and system must both be included in the authorization file .CR /etc/shutdown.allow . .SH EXAMPLES Immediately reboot the system and run HP-UX again: .IP .C "shutdown \-r 0" .PP Halt the system in 5 minutes (300 seconds) with no interactive questions and answers: .IP .C "shutdown \-h \-y 300" .PP Go to run-level .CR s in 10 minutes: .IP .C "shutdown 600" .SH FILES .TP 10 .CR /etc/shutdown.allow .IP Authorization file. .IP The file contains lines that consist of a system host name and the login name of a user who is authorized to reboot or halt the system. A superuser's login name must be included in this file in order to execute .CR shutdown . However, if the file is missing or of zero length, the .CR root user can run the .CR shutdown program to bring the system down. .IP This file does not affect authorization to bring the system down to single-user state for maintenance purposes; that operation is permitted only when invoked by a superuser. .IP A comment character, .CR # , at the beginning of a line causes the rest of the line to be ignored (comments cannot span multiple lines without additional comment characters). Blank lines are also ignored. .IP The wildcard character .CR + can be used in place of a host name or a user name to specify all hosts or all users, respectively (see .IR hosts.equiv (4)). .IP For example: .RS .nf .IP .C "# user1 can shut down systemA and systemB" .C "systemA user1" .C "systemB user1" .C "# root can shut down any system" .C "+ root" .C "# Any user can shut down systemC" .C "systemC +" .fi .RE .SH WARNINGS The user name compared with the entry in the .CR shutdown.allow file is obtained using .CR getlogin() or, if that fails, using .CR getpwuid() (see .IR getlogin (3) and .IR getpwuid (3)). .PP The hostname in .CR /etc/shutdown.allow is compared with the hostname obtained using .CR gethostbyname() (see .IR gethostbyname (3)). .PP .CR shutdown must be executed from a directory on the root volume, such as the .CR / directory. .PP The maximum broadcast message that can be sent is approximately 970 characters. .PP When executing .CR shutdown on an NFS diskless cluster server and the .CR -o option is not entered, clients of the server will be rebooted. No clients should be individually rebooted or shutdown while the cluster is being shutdown. .SH SEE ALSO dcnodes(1M), fsck(1M), init(1M), killall(1M), mount(1M), reboot(1M), sync(1M), dcnodes(3), gethostbyname(3), getpwuid(3), hosts.equiv(4). .\" .\" index@\f4shutdown\f1 \- terminate all processing@@@\f3shutdown(1M)\f1 .\" index@\f1halt system operation@@@\f3shutdown(1M)\f1 .\" index@\f1mode, place system in single-user@@@\f3shutdown(1M)\f1 .\" index@\f1reboot system automatically after shutting system down@@@\f3shutdown(1M)\f1 .\" index@\f1run-level \f4s\f1, place system in@@@\f3shutdown(1M)\f1 .\" index@\f1single-user mode, place system in@@@\f3shutdown(1M)\f1 .\" index@\f1stop system operation@@@\f3shutdown(1M)\f1 .\" index@\f1terminate all system processing@@@\f3shutdown(1M)\f1 .\" .\" toc@\f3shutdown(1M)\f1:\0\0\f4shutdown\f1@@@terminate all processing .\" $Header: sig_named.1m,v 80.3 96/10/23 15:59:04 ssa Exp $ .TA s .TH sig_named 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 11.00: October 1997 .SH NAME sig_named \- send signals to the domain name server .SH SYNOPSIS .C sig_named .RC [ -v ] .RC [ debug .RC [ + ] .I debug-level \(or .C dump \(or .C kill \(or .C restart \(or .C stats \(or .CR trace\| ] .SH DESCRIPTION .CR sig_named sends the appropriate signal to the domain name server .CR /usr/sbin/named . The process ID is obtained from .CR /var/run/named.pid or from .IR ps (1) if .CR /var/run/named.pid does not exist. .SS Options .CR sig_named recognizes the following options and command-line arguments: .RS .TP 15 .C -v Verify that the name server is running before sending the signal. The verification is done using .CR ps (see .IR ps (1)). .TP .CR debug \0[ + ]\f2debug-level\fP Set the debugging output sent to .CR /var/tmp/named.run to .IR debug-level . If debugging is already on, it is turned off before the debug level is set. If .CR + precedes .IR debug-level , the current debugging level is raised by the amount indicated. If .IR debug-level is zero, debugging is turned off. .TP .CR dump Signal the name server to dump its database. The database is dumped to .CR /var/tmp/named_dump.db . .TP .C kill Kill the name server process. .TP .C restart Signal the name server to reload its database. .TP .C stats Remove the old statistics file, .CR /var/tmp/named.stats . Signal the name server to dump its statistics. Show the statistics file on the standard output. .TP .C trace Toggles tracing of incoming queries to .CR /var/adm/syslog/syslog.log. .RE .SH AUTHOR .CR sig_named was developed by HP. .SH FILES .TP 33 .C /var/run/named.pid Process ID .PD 0 .TP .C /var/tmp/named.run Debug output .TP .C /var/tmp/named_dump.db Dump of the name server database .TP .C /var/tmp/named.stats Nameserver statistics data .PD .SH SEE ALSO kill(1), named(1M). .\" .\" index@\f4sig_named\f1 \- send signals to domain name server@@@\f3sig_named(1M)\f1 .\" index@\f1send signals to domain name server@@@\f3sig_named(1M)\f1 .\" index@\f1signals, send to domain name server@@@\f3sig_named(1M)\f1 .\" index@\f1domain name server, send signals to@@@\f3sig_named(1M)\f1 .\" index@\f1name server, domain, send signals to@@@\f3sig_named(1M)\f1 .\" index@\f1server, domain name, send signals to@@@\f3sig_named(1M)\f1 .\" .\" toc@\f3sig_named(1M)\f1:\0\0\f4sig_named\f1@@@send signals to the domain name server .\" .\" fileset_database@sig_named.1m INETSVCS-MAN .\" Copyright (c) 1993 Eric P. Allman .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)smrsh.1m 8.2 (Berkeley) 1/9/96 .\" .TH smrsh 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: August 1997 .SH NAME smrsh \- restricted shell for sendmail .SH SYNOPSIS .B smrsh .B \-c command .SH DESCRIPTION The .I smrsh program is intended as a replacement for .I sh for use in the ``prog'' mailer in .IR sendmail (1M) configuration files. It sharply limits the commands that can be run using the ``|program'' syntax of .I sendmail in order to improve the over all security of your system. Briefly, even if a ``bad guy'' can get sendmail to run a program without going through an alias or forward file, .I smrsh limits the set of programs that he or she can execute. .PP Briefly, .I smrsh limits programs to be in the directory /var/adm/sm.bin, allowing the system administrator to choose the set of acceptable commands. It also rejects any commands with the characters `\`', `<', `>', `|', `;', `&', `$', `(', `)', `\er' (carriage return), or `\en' (newline) on the command line to prevent ``end run'' attacks. .PP Initial pathnames on programs are stripped, so forwarding to ``/usr/ucb/vacation'', ``/usr/bin/vacation'', ``/home/server/mydir/bin/vacation'', and ``vacation'' all actually forward to ``/var/adm/sm.bin/vacation''. .PP System administrators should be conservative about populating /usr/adm/sm.bin. Reasonable additions are .IR vacation (1), .IR rmail (1) and the like. No matter how brow-beaten you may be, never include any shell or shell-like program (such as .IR perl (1)) in the sm.bin directory. Note that this does not restrict the use of shell or perl scripts in the sm.bin directory (using the ``#!'' syntax); it simply disallows execution of arbitrary programs. .SH FILES /var/adm/sm.bin \- directory for restricted programs .SH SEE ALSO sendmail(1M). .\" $Header: snmpd.1m,v 76.1 95/07/24 16:10:33 ssa Exp $ .ds sS snmpd .ds sA snmpd, snmpdm .ds sM snmpdm .ds sH libSaHpunix.sl .ds s2 libSaMib2.sl .ds sl subagt_ld .ds su subagt_unld .ds Fs /usr/sbin/snmpd .ds Fm /usr/sbin/snmpdm .ds fH /usr/lib/libSaHpunix.sl .ds f2 /usr/lib/libSaMib2.sl .ds Fl /usr/sbin/subagt_ld .ds Fu /usr/sbin/subagt_unld .ds sC /etc/SnmpAgent.d/snmpd.conf .ds sE /etc/SnmpAgent.d/snmpd.extend .ds dS /sbin/SnmpAgtStart.d .ds fL /var/adm/snmpd.log .ds fS /etc/services .ds fM /opt/OV/snmp_mibs/ .ds sV /opt/OV .TA s .TH \*(sS 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \*(sA \- Simple Network Management Protocol (SNMP) Daemon .SH SYNOPSIS .C \*(sS .RC [ \|\-a\| ] .RC [ \|\-authfail\| ] .RC [ \|\-C .IR contact\| ] .RC [ \|\-Contact .IR contact\| ] .RC [ \|\-h\| ] .RC [ \|\-help\| ] .RC [ \|\-L .IR location\| ] .RC [ \|\-Location .IR location\| ] .RC [ \|\-l .IR logfile\| ] .RC [ \|\-logfile .IR logfile\| ] .RC [ \|\-P .IR portnum\| ] .RC [ \|\-Port .IR portnum\| ] .RC [ \|\-m .IR logmask\| ] .RC [ \|\-mask .IR logmask\| ] .RC [ \|\-n\| ] .RC [ \|\-sys .IR description\| ] .RC [ \|\-sysDescr .IR description\| ] .PP .C \*(sS .RC [ \|\-c\| ] .RC [ \|\-configure\| ] .RC [ \|\-h\| ] .RC [ \|\-help\| ] .RC [ \|\-k\| ] .RC [ \|\-kill\| ] .RC [ \|\-M .IR logmask\| ] .RC [ \|\-Mask .IR logmask\| ] .PP .C \*(sM .RC [ \|\-a\| ] .RC [ \|\-authfail\| ] .RC [ \|\-C .IR contact\| ] .RC [ \|\-Contact .IR contact\| ] .RC [ \|\-h\| ] .RC [ \|\-help\| ] .RC [ \|\-L .IR location\| ] .RC [ \|\-Location .IR location\| ] .RC [ \|\-l .IR logfile\| ] .RC [ \|\-logfile .IR logfile\| ] .RC [ \|\-P .IR portnum\| ] .RC [ \|\-Port .IR portnum\| ] .RC [ \|\-m .IR logmask\| ] .RC [ \|\-mask .IR logmask\| ] .RC [ \|\-n\| ] .RC [ \|\-sys .IR description\| ] .RC [ \|\-sysDescr .IR description\| ] .PP .C \*(sM .RC [ \|\-c\| ] .RC [ \|\-configure\| ] .RC [ \|\-h\| ] .RC [ \|\-help\| ] .RC [ \|\-k\| ] .RC [ \|\-kill\| ] .RC [ \|\-M .IR logmask\| ] .RC [ \|\-Mask .IR logmask\| ] .PP .C \*(sl .IR SharedLibrarySubAgentPath \| .PP .C \*(su .IR SharedLibrarySubAgentPath \| .PP .SH DESCRIPTION The Master SNMP Agent (\c .CR snmpdm ) and the collection of subAgents (\c .CR /usr/lib/libSa...sl\ ) that have attached to the Master Agent collectively form a single SNMP Agent. The SNMP Agent accepts SNMP Get, GetNext and Set requests from an SNMP Manager which cause it to read or write the Management Information Base (\c .CR MIB ). The .CR MIB objects are instrumented by the subAgents. .PP The Master Agent can bind to separate process subAgents and to shared library subAgents. The .CR \*(sl command is used to bind a shared library subAgent to the Master Agent process. The .CR \*(su is used to remove or unload a shared library subAgent from the Master Agent process. .PP .SS Options .C \*(sS and .C \*(sM recognizes the following options: .RS .TP 15 .C \-authfail .TP .C \-a Suppress sending authenticationFailure traps. .TP .C \-configure .TP .C \-c Send a special SNMP message to the running .CR \*(sM which causes it to reconfigure itself (force the running .C \*(sM to re-read .CR \*(sC ). This does not reset the subAgents. To reset a subAgent you must stop the subAgent and then restart it. This option should not be used when starting up the Master Agent. Attempting to start .CR \*(sM with this option will generate an error message since there is no agent running to receive the message. .TP .CI \-Contact \ contact .TP .CI \-C \ contact Specify the contact person responsible for the network management agent. This option overrides the contact person specified in the Master Agent configuration file .CR \*(sC . It does not alter the value in .CR \*(sC . By default, the agent's contact is a blank string. To configure the agent's contact, add the contact to .CR \*(sC or use the .CR -C option. .TP .CI \-help .TP .CI \-h Display command line options and log mask values. .TP .CI \-kill .TP .CI \-k Send a special SNMP message to the running .CR \*(sM which causes it to terminate. This will also terminate all shared library subAgents which have connected to the Master Agent. The subsequent behavior of separate process subAgents is subAgent dependent. This option should not be used when starting up the Master Agent. Attempting to start .CR \*(sM with this option will generate an error message since there is no agent running to receive the message. .TP .CI \-Location \ location .TP .CI \-L \ location Specify the location of the agent. This option overrides the location specified in .CR \*(sC . It does not alter the value in .CR \*(sC . By default, the agent's location is a blank string. To configure the agent's location, add the location to .CR \*(sC or use the .CR -L option. .TP .CI \-logfile \ logfile .TP .CI \-l \ logfile Use .IR logfile for logging rather than the default logfile, .CR \*(fL . A value of .CR \- will direct logging to .CR stdout . .TP .CI \-Mask \ logmask .TP .CI \-M \ logmask Send a message to the currently running .CR \*(sM to change its logging mask to .IR logmask. See the \f3SNMP Agent Logging\fP section for valid values. To set the .CR \*(sM logging mask at startup, see option .CR -m . This option should not be used when starting up the Master Agent. Attempting to start .CR \*(sM with this option will generate an error message since there is no agent running to receive the message. .IP This command line option only changes the logging mask within the Master Agent. SubAgents typically read the Master Agent's logging mask when they connect to the Master Agent. Whether a particular subAgent subsequently re-reads the Master Agent's logging mask is subAgent dependent. .TP .CI \-mask \ logmask .TP .CI \-m \ logmask Sets the initial logging mask to .IR logmask. See the \f3SNMP Agent Logging\fP section for valid values. This argument only takes effect as you are starting the agent. To change the mask of an agent that is already running use option .CR -M . .TP .C \-n Normally .CR \*(sM puts itself into the background as if the command was terminated with an ampersand. This option inhibits that behavior. .TP .CI \-Port \ portnum .TP .CI \-P \ portnum Specify the UDP port number that the agent will listen on for SNMP requests. The default is port 161. The value can also be specified in .CR \*(fS . Only the super-user can start .CR \*(sM and only one .CR \*(sM can execute on a particular UDP port. .DS .TP .CI \-sysDescr \ description .TP .CI \-sys \ description Allows the user to specify the value for the .CR system.sysDescr .CR MIB object. The format is a text string enclosed in quotes. This option overrides the .CR sysDescr specified in .CR \*(sC . .IP For example, .nf snmpdm -sys "nsmd1, test system" .fi .DE .RE .PP .SS SNMPv1 Security Each .CR SNMP request is accompanied by a community name, which is essentially a password that enables .CR SNMP access to .CR MIB values on an agent. A manager can request to read a .CR MIB value by issuing an .CR SNMP GetRequest, or a manager may request to alter a .CR MIB value by issuing an .CR SNMP SetRequest. .PP By default, the agent responds to all .CR SNMP GetRequests, regardless of the community name used in the request. To configure the agent to respond only to a specific community name, add a .CR get-community-name to .CR \*(sC . See the .IR snmpd.conf (4) man page. .PP By default, the agent does not allow managers to alter .CR MIB values (it returns errors for .CR SNMP SetRequests). To configure the agent to respond to .CR SNMP SetRequests, add a .CR set-community-name to .CR \*(sC . .RE .PP .SS SNMPv2 Security Simple Network Management Protocol Version 2 (\c .CR SNMPv2 ) is not supported in this version of the .CR SNMP Agent. .RE .PP .SS Traps The agent also sends information to a manager without an explicit request from the manager. Such an operation is called a "trap." By default, .CR SNMP traps are not sent to any destination. To configure the agent to send traps to one or more specific destinations, add the trap destinations to .CR \*(sC . .PP Then Master Agent (\c .CR \*(sM ) and the MIB-2 subAgent (\c .CR \*(s2 ) collaborate to send the following .CR SNMP traps: .RS .TP 15 .C coldStart Sends a coldStart trap when the SNMP Agent is invoked. .TP .C linkDown Sends a linkDown trap when an interface goes down. .TP .C linkUp Sends a linkUp trap when an interface comes up. .TP .C authenticationFailure Sends an authenticationFailure trap when an .CR SNMP request is sent to the SNMP Agent with a community name that does not match the community names specified in .CR \*(sC . .PP .SS SNMP Agent Logging The SNMP Agent provides the capability to log various types of errors and events. Two levels of reporting are available .IR Customer and .IR Factory logging. Note that in previous releases the agent provided error logging and some degree of tracing. This capability is preserved and accessed as .IR Customer .IR Error , .IR Warning and Trace logging. .IR Factory logs (error, warn, and trace) provide additional information that is typically only used by factory engineers or subAgent developers. .PP .C Log Masks .PP Log masks enable the user to specify the particular classes of messages that should be logged to .CR \*(fL or .IR logfile . There are three different ways that you can specify the logmask that you want. They are; (1) decimal number, (2) hex number, or (3) text string. The three may not be used in combination. .PP To select multiple output types do the following. For decimal or hex format simply add the individual logmask values together and enter that number. When entering strings, place multiple strings on the same line, space separated, without quotes. .PP .DS .nf .C " ===================================================================" .C " LOG MASK VALUES" .C " FUNCTION Decimal Hex String " .C " ===================================================================" .C " Turn off logging. 0 0x00000000 LOGGING_OFF" .C .C " Log authenticationFailure traps 1 0x00000001 AUTH_FAIL" .C .C " Log customer errors 2 0x00000002 CUST_ERROR" .C .C " Log configuration requests 4 0x00000004 CONFIG_REQ" .C .C " Log requests and replies 8 0x00000008 REQ_REPLY" .C .C " Log requests and replies for 16 0x00000010 ADD_OBJ" .C " objects that have been added " .C .C " Log hexdumps of packets 32 0x00000020 EA_PKTS" .C " received and sent by snmpd " .C .C " Log customer trace messages 64 0x00000040 CUST_TRACE" .C .C " Log customer warning messages 128 0x00000080 CUST_WARN" .C .C " Log factory trace messages 8388608 0x00800000 FACTORY_TRACE" .C .C " Log factory warning messages 268435456 0x10000000 FACTORY_WARN" .C .C " Log factory error messages 536870912 0x20000000 FACTORY_ERROR" .fi .DE .DS .PP .nf EXAMPLES: .PP Turn on authenticationFailure traps and trace messages: .C " decimal format: snmpdm -m 65" .C " hex format: snmpdm -m 0x41" .C " string format: snmpdm -m AUTH_FAIL USER_TRACE" .fi .DE .PP .C Log File Format: .PP These customer logs are printed in an easy to read format. A log entry will contain the following header information: .PP .DS .nf .C " IDstring: A unique string placed in each log that maps the" .C " specific log back to the call made in the code. " .C " Date: The date and time of the log was made." .C " Level: Basically represents the log mask that you entered." .fi .DE .PP Following this header will be the actual log data. .PP Below is an example authentication failure log. .PP .DS .nf .C " ==================================================================" .C " IDstring: MASTER200" .C " Date: Wed Mar 15 16:21:43 1995" .C " Level: AUTHENTICATION_FAILURE" .C .C " Authentication failure:" .C " Source IP & Port: 0x7f000001, 4130" .C .C " ==================================================================" .fi .DE .RE .PP .SS Supported MIB Objects The Management Information Base (\c .CR MIB ) is a conceptual database of values on the agent. The Master SNMP Agent implements a small number of .CR MIB objects but most .CR MIB objects are implemented by subAgents that have attached to the Master Agent. See .CR \*(fM on systems with OpenView products installed for definitions of particular .CR MIB objects. .PP This version of the SNMP Agent includes two subAgents, .CR \*(s2 and .CR \*(sH which implement the MIB-2 and hp-unix MIBs respectfully. These MIBs are described by .CR \*(fMrfc1213-MIB-II and .CR \*(fMhp-unix on systems with OpenView products installed. .PP The MIB-2 subAgent supports most of the objects in .CR RFC1213 . The .CR EGP group is not supported. The hp-unix subAgent supports most of the objects in the hp-unix MIB. .PP .SS DEPRECATED MIBS The ieee8023Mac .CR MIB group corresponding to the following OID is no longer supported: .PP private(4).enterprises(1).hp(11).nm(2).interface(4).ieee8023Mac(1) .PP This .CR MIB group is replaced with the "Ether-Like" .CR MIB group (RFC1398) which corresponds to OID: .PP mgmt(2).mib-2(1).transmission(10).dot3(7) .PP .SH SNMP Agent Startup The SNMP Agent startup mechanism is built upon the System V.4 file system paradigm. The startup script, .CR /etc/netmanrc , which was used in previous releases of the SNMP Agent is no longer used. .PP .C Automatic Startup: .PP As installed, the SNMP Master Agent and all subAgents should startup automatically each time the system re-boots or anytime the system transitions from run level 1 to run level 2. When the system enters run level 2 the operating system will execute .CR /sbin/init.d/SnmpMaster which will startup the Master Agent. Similarly, .CR /sbin/init.d/SnmpMib2 and .CR /sbin/init.d/SnmpHpunix will startup the MIB2 and HP Unix subAgents respectfully immediately after the Master Agent is started. .PP Prior to executing these startup scripts the system will examine all scripts in .CR /etc/rc.config.d for environment variables which could potentially influence the startup of the Master Agent and each subAgent. See the particular startup script or configuration file for details on supported environment variables. The user should never modify scripts in .CR /sbin/init.d . Instead the startup behavior should be controlled by adjusting values in the appropriate configuration script in .CR /etc/rc.config.d . .PP .C Manual Startup: .PP There are two ways to start the SNMP Agent manually. The first way is to execute .CR \*(sM and then start each subAgent. Separate process subAgents are started by invoking the particular subAgent executable. Shared library subAgents are started by executing the .CR subagt_ld command with the absolute path to the shared library as an argument. .PP The second and simplest way to start the SNMP Agent manually is to execute the .CR \*(sS startup script which will invoke the Master Agent and all subAgents who have been installed and designed to operate in this paradigm. The .CR \*(sS script script is layered upon the V.4 startup paradigm and so makes use of the component startup scripts in .CR /sbin/init.d and configuration scripts in .CR /etc/rc.config.d . When .CR \*(sS is invoked it passes all its command line arguments to .CR \*(sM and then executes each script found in .CR \*(dS . .PP .SH EXTERNAL INFLUENCES .SS Environment Variables LANG determines the language in which messages appear. If LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of LANG. If any internationalization variable contains an invalid setting, .CR \*(sS behaves as if all internationalization variables are set to "C." See .IR environ (5). Many SNMP Agent log messages are only available in English. .SS International Code Set Support Supports single-byte character code sets. .SH AUTHOR .CR \*(sS was developed by HP, Massachusetts Institute of Technology and SNMP Research. .SH FILES .CR \*(Fs .br .CR \*(Fm .br .CR \*(f2 .br .CR \*(fH .br .CR \*(Fl .br .CR \*(Fu .br .CR \*(sC .br .CR \*(fL .br .CR \*(fM .br .CR \*(dS/ .SH SEE ALSO snmpd.conf(4). .PP RFC 1155, RFC 1157, RFC 1212, RFC 1213, RFC 1231, RFC 1398. .\" .\" index@\f4snmpd\f1 \- daemon that responds to SNMP requests@@@\f3snmpd(1M)\f1 .\" index@\f1daemon that responds to SNMP requests@@@\f3snmpd(1M)\f1 .\" index@\f1SNMP requests, daemon that responds to@@@\f3snmpd(1M)\f1 .\" index@\f1requests, daemon that responds to SNMP@@@\f3snmpd(1M)\f1 .\" .\" toc@\f3snmpd(1M)\f1:\0\0\f4snmpd\f1@@@daemon that responds to SNMP requests .\" .\" fileset_database@snmpd.1m LAN-MAN .\" $Header: softpower.1m,v 76.2 95/07/06 15:05:22 ssa Exp $ .TA s .TH softpower 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME softpower \- determine if softpower hardware is installed on the system .SH SYNOPSIS .CR /sbin/softpower .SH DESCRIPTION The .CR softpower command determines whether a software controlled power switch is installed on the system. .SH RETURN VALUE .CR softpower returns the following values: .RS .TP .PD 0 .CR 0 Softpower hardware detected on the system. .TP .CR 1 Softpower hardware was not detected on the system. .TP .CR 2 The command failed because it is being run on an earlier version of HP-UX that does not support the appropriate .CR sysconf call. .SH AUTHOR .CR softpower was developed by HP. .PD .RE .SH SEE ALSO sysconf(2). .\" .\" .\" index@\f4softpower\f1 \- determine if softpower hardware is installed@@@\f3softpower(1M)\f1 .\" index@\f1softpower hardware@@@\f3softpower(1M)\f1 .\" .\" toc@\f3softpower(1M)\f1:\0\0\f4softpower\f1@@@determine if softpower hardware is installed .\" .\" .\"========================================================= .\" (c) 1992 Hewlett-Packard Company. All Rights Reserved. .\" Author: Hewlett-Packard DMD .\"========================================================= .\" .\"@(#) $Header: spd.1m,v 1.2 95/12/15 11:34:29 hmgr Exp $ .TA s .TH spd 1M .SH NAME spd \- set physical drive parameters on an .SM HP SCSI disk array .SH SYNOPSIS .HP .C spd .RC [ -a ] .RC [ -c ] .RC [ -d ] .RC [ -f ] .RC [ -r ] .RC [ -x ] .RC [ -M ] .I drive device_file .SH DESCRIPTION .C spd changes the status of a drive on an .SM HP SCSI disk array associated with device file .IR device_file . .SS Options .RS .TP 15 .C -a Add drive. Adds a drive to the set of drives known by the controller. .TP .C -c Clear the warning, or "failed disk" error status. Parity checking via .C scn must be performed immediately following this operation. See .SM WARNING. .TP .C -d Delete drive. Deletes a drive from the set of drives known by the controller. .TP .C -f Fail drive. Marks the drive as failed, and may place the .SM LUN\c (s) residing on it in a dead or degraded state, depending on .SM RAID level, and the presence of other failed drives in the .SM LUN. .TP .C -r Replace drive. Marks the drive as replaced, which instructs the controller to start reconstructing the .SM LUN\c (s) associated with this replaced drive. .TP .C -x Replace and format drive. Marks a drive as replaced, and instructs the controller to physically format the drive before starting .SM LUN reconstruction. .TP .C -M Force the selected option. By altering the state of individual disk mechanisms contained within a disk array, the state of configured .SM LUN devices may also be altered. For example, if the disk array has a .SM LUN configured into a .SM RAID 5 configuration, and one of the disk mechanisms used to create the .SM LUN is in a .SM FAILED state, the disk array will be operating in a .SM DEGRADED mode. If the user selected the .SM FAIL DRIVE option on one of the functioning disk mechanisms of the .SM LUN, the state of the .SM LUN would be changed from .SM DEGRADED to .SM DEAD. .C spd will warn the user of any significant change in .SM LUN state resulting from their selected option. The .C -M option suppresses these warnings and performs the selected operation. .TP .I drive Specified in the form .CI c X i Y , where .I X (a decimal number) represents the .SM SCSI channel number, and .I Y (a decimal number) represents the .SM SCSI-ID number of the disk drive. .SH RETURN VALUE .C spd returns the following values: .RS 5 .TP .B " 0" Successful completion. .PD 0 .TP .B -1 Command failed (an error occurred). .PD .PP .RE .SH DIAGNOSTICS AND ERRORS Errors can originate from problems with: .RS .TP 3 \(bu .C spd .TP \(bu .SM SCSI (device level) communications .TP \(bu system calls .RE .PP .SS Error messages generated by spd: .TP .C "usage: spd <-a | -c | -d | -f | -r | -x> <-M> " An error in command syntax has occurred. Enter command again with all required arguments, in the order shown. .TP .C "spd: device busy" .tr ~" To ensure that .C spd does not modify a disk array that is being used by another process, .C spd attempts to obtain exclusive access to the disk array. If the disk array is already opened by another process (for example, LVM \(em the Logical Volume Manager), a .RC ~ "device busy" ~ error message is returned by the driver. To eliminate the .RC ~ "device busy" ~ condition, determine what process has the device open. In the case of LVM, it is necessary to deactivate the volume group containing the array before configuring the array (see .CR vgchange (1M)). .tr ~~ .TP .C "spd: Arg out of range" One of the arguments has exceeded its maximum or minimum size, or is incorrect in form. Check the size and form of each argument. .TP .C "spd: LUN does not exist" The addressed .SM LUN is not configured, and thus is not known to the array controller. .TP .C "spd: LUN # too big" The .SM LUN number, which is derived from the device file name, is out of range. .TP .C "spd: Not a raw file" Utilities must be able to open the device file for raw access. .TP .C "spd: Not an HP SCSI disk array" The device being addressed is not an .SM HP SCSI disk array. .PP .SS SCSI (device level) communication errors: Sense data associated with the failed operation is printed. .TP .C "spd: Transfer length error" The amount of data actually sent to or received from the device was not the expected amount. .PP .SS Error messages generated by system calls: .C spd uses the following system calls: .IP .CR malloc() , .CR free() , .CR stat() , .CR open() , .CR close() , .CR read() , .CR write() , and .CR ioctl() . .PP Documentation for these .SM HP-UX system calls contains information about the specific error conditions associated with each call. .C spd does not alter the value of .CR errno . The interpretation of .C errno for printing purposes is performed by the system utility .CR strerror() . .SH EXAMPLES .PP The following command clears the .SM FAILED state of the drive at .SM ID 3 on channel 2 on the .SM HP SCSI disk array .C /dev/rdsk/c2t6d0 on a series 700. The .C -M option must be selected to suppress warning messages. The .C scn operation must be performed immediately to ensure accurate data parity information. .IP .C "spd -c -M c2i3 /dev/rdsk/c2t6d0" .IP .C "scn /dev/rdsk/c2t6d0" .PP To add the drive at .SM ID 3 on channel 2 to the set of drives the array controller knows about on the .SM HP SCSI disk array .C /dev/rdsk/c2t6d0 on a series 700: .IP .C "spd -a c2i3 /dev/rdsk/c2t6d0" .PP To delete the drive at .SM ID 3 on channel 2 from the set of drives the array controller knows about on the .SM HP SCSI disk array .C /dev/rdsk/c2t6d0 on a series 800: .IP .C "spd -d c2i3 /dev/rdsk/c2t6d0" .PP To mark the drive at .SM ID 3 on channel 2 as failed, thus rendering any redundant .SM RAID mode .SM LUN (s) residing on it as dead or degraded, on the .SM HP SCSI disk array .C /dev/rdsk/c2t6d0 on a series 700: .IP .C "spd -f -M c2i3 /dev/rdsk/c2t6d0" .PP To mark the drive at .SM ID 3 on channel 2 as replaced, thus initiating the reconstruction of any redundant .SM RAID mode .SM LUN (s) residing on it, on the .SM HP SCSI disk array .C /dev/rdsk/c2t6d0 on a series 700: .IP .C "spd -r b2a3 /dev/rdsk/c2t6d0" .SH NOTE Failing a drive on a .SM RAID\c _0 .SM LUN will leave it with an "optimal" .SM LUN status, even though the controller will no longer access the failed drive and its data. .SH WARNING Clearing a "failed" disk status might leave the array with inconsistent parity. This can lead to corrupted data if the array .SM LUN ever operates in "degraded" state. Parity scan and repair must be performed immediately after clearing the "failed" state of a disk array. .SH DEPENDENCIES The HP C2425 and HP C2427 disk arrays are only supported on Series 700 systems running HP-UX version 9.0X. .PP The HP C2430 disk array is supported on Series 700 and 800 systems running HP-UX versions 9.0X and 10.0X. .SH AUTHOR .PP .C spd was developed by .SM HP. .\" .\" index@\f4spd\f1 \- set physical drive parameters for an \s-1HP SCSI\s+1 disk array@@@\f3spd(1M)\f1 .\" index@disk array: set physical drive parameters for@@@\f3spd(1M)\f1 .\" .\" toc@\f3spd(1M)\f1:\0\0\f4spd\f1@@@set physical drive parameters for an \s-1HP SCSI\s+1 disk array .\" .\" fileset_database@spd.1m SYS-ADMIN-MAN .\" $Header: spray.1m,v 72.5 94/08/09 12:09:06 ssa Exp $ .TA s .TH spray 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME spray \- spray packets .SH SYNOPSIS .C /usr/sbin/spray .I host .RC [ -c .IR count\| ] .RC [ -l .IR length\| ] .SH DESCRIPTION .C spray sends a one-way stream of packets to .I host using RPC, then reports how many were received by .I host and what the transfer rate was. The host name can be either a name or an internet address. .SS Options .C spray recognizes the following options and command-line arguments: .RS .TP 15 .CI -c \0count Specifies how many packets to send. The default value of .I count is the number of packets required to make the total stream size 100\|000 bytes. .TP .CI -l \0length The number of bytes in the Ethernet packet holding the RPC call message. Since the data is encoded using XDR, and XDR only deals with 32-bit quantities, not all values of .I length are possible. The .I spray command rounds up to the nearest possible value. When .I length is greater than the size of an Ethernet packet, the system breaks the datagram into multiple Ethernet packets. The default value of .I length is 86 bytes (the size of the RPC and UDP headers). .RE .SH AUTHOR .C spray was developed by Sun Microsystems, Inc. .SH SEE ALSO ping(1M), sprayd(1M). .\" .\" index@\f4spray\f1 \- spray packets@@@\f3spray(1M)\f1 .\" index@\f1spray packets@@@\f3spray(1M)\f1 .\" index@\f1packets, spray@@@\f3spray(1M)\f1 .\" .\" toc@\f3spray(1M)\f1:\0\0\f4spray\f1@@@spray packets .\" $Header: sprayd.1m,v 72.5 94/08/09 12:19:43 ssa Exp $ .TA s .TH sprayd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sprayd \- spray server .SH SYNOPSIS .C /usr/lib/netsvc/spray/rpc.sprayd .RC [ -l .IR log_file\| ] .RC [ -e \(or -n ] .SH DESCRIPTION .C sprayd is an RPC server that records the packets sent by .C spray from another system (see .IR spray (1M)). .PP .C inetd invokes .C sprayd through .C /etc/inetd.conf (see .IR inetd (1M)). .SS Options .C sprayd recognizes the following options and command-line arguments: .RS .TP 15 .CI -l \0log_file Log any errors to the named log file, .IR log_file . Errors are not logged if the .C -l option is not specified. .IP Information logged to the file includes date and time of the error, host name, process id and name of the function generating the error, and the error message. Note that different services can share a single log file since enough information is included to uniquely identify each error. .TP .C -e Exit after serving each RPC request. Using the .C -e option, the .C inetd security file .C /var/adm/inetd.sec can control access to RPC services. .TP .C -n Exit only if .RS .RS .TP 3 \(bu .C portmap dies (see .IR portmap (1M)), .TP \(bu Another .C rpc.sprayd registers with .CR portmap , or .TP \(bu .C rpc.sprayd becomes unregistered with .IR portmap . .RE .RE .RE .PP The .C -n option is more efficient because a new process is not launched for each RPC request. .C -n is the default. .SH AUTHOR .C sprayd was developed by Sun Microsystems, Inc. .SH SEE ALSO inetd(1M), spray(1M), portmap(1M), inetd.conf(4), inetd.sec(4), services(4). .\" .\" index@\f4sprayd\f1 \- spray server@@@\f3sprayd(1M)\f1 .\" index@\f1spray server@@@\f3sprayd(1M)\f1 .\" index@\f1server, spray@@@\f3sprayd(1M)\f1 .\" .\" toc@\f3sprayd(1M)\f1:\0\0\f4sprayd\f1@@@spray server .\"@(#) $Header: sss.1m,v 1.2 95/12/15 11:33:06 hmgr Exp $ .TA s .TH sss 1m .SH NAME sss \- set spindle sync state of drives in an HP SCSI disk array .SH SYNOPSIS .HP .C sss -d .RI [ drive_list ] .I device_file .PP .C sss -on .RC [ -s ] .RI [ drive_list ] .I device_file .PP .C sss -off .RI [ drive_list ] .I device_file .br .SH DESCRIPTION .C sss displays or changes the spindle synchronization state of the disk drives in the HP SCSI disk array associated with device file .IR device_file . Though .I device_file is the name of a device file corresponding to a LUN, .C sss operates (by default) on all disk drives physically connected to the array controller, without regard to the drives' LUN ownership. Even if multiple LUNs (or sub-LUNs) are present, .C sss should be directed to only one of them (that is, specify the name of the device file for only one of the LUNs in the .C sss command line). To affect a subset of the physical drives in the array, specify which drives to affect in .IR drive_list . .SS Options .RS .TP 16 .C -d Display only. Displays the current spindle synchronization status. This has two components: the drive's master or slave status and its state of spindle synchronization (on or off). .TP .C -on Sync on. Enables spindle synchronization; one drive is designated master and the rest are designated slaves, unless the .C -s "slave only" tag is present, in which case all designated drives will be slaves. If only one drive is designated, it will be a master. .TP .C \-off Sync off. Disables spindle synchronization. .TP .C \-s Slave only. Only used with the .C \-on option. Make all designated drives slaves. This is useful when replacing a drive in a set of drives which already have spindle synchronization enabled. If you have replaced the master drive, use the .C -on option without .C -s , and specify the new drive only. .TP .I drive_list A list of drives used to specify which drives in the array will be affected by the synchronization operation. .I drive_list is in the form .CI c X i Y , where .I X (a decimal number) represents the SCSI channel number, and .I Y (a decimal number) represents the SCSI-ID number of the desired drive. Drives names in .I drive_list are separated by commas. If no .I drive_list is present, .C sss defaults to all physical drives attached to the array controller, regardless of which LUNs they belong to. .SH RETURN VALUE .C sss returns the following values: .RS 5 .TP .B " 0" Successful completion. .PD 0 .TP .B -1 Command failed (an error occurred). .PD .PP .RE .SH DIAGNOSTICS AND ERRORS Errors can originate from problems with: .RS .TP 3 \(bu .C sss .TP \(bu SCSI (device level) communications .TP \(bu system calls .RE .PP .SS Error messages generated by sss: .TP .C "usage: sss <-d | -on [-s] | -off> [cXiY,...] " .C sss encountered an error in command syntax. Enter the command again with the required arguments, in the order shown. .TP .C "sss: Arg out of range" One of the arguments has exceeded its maximum or minimum size, or is incorrect in form. Check the size and form of each argument. .TP .C "sss: device busy" .tr ~" To ensure that .C sss does not modify a disk array that is being used by another process, .C sss attempts to obtain exclusive access to the disk array. If the disk array is already opened by another process (for example, LVM \(em the Logical Volume Manager), a .RC ~ "device busy" ~ error message is returned by the driver. To eliminate the .RC ~ "device busy" ~ condition, determine what process has the device open. In the case of LVM, it is necessary to deactivate the volume group containing the array before configuring the spindle sync state of the drives in the array (see .CR vgchange (1M)). .tr ~~ .TP .C "sss: LUN # too big" The LUN number, which is derived from the device file name, is out of range. .TP .C "sss: Not a raw file" .C sss must be able to open the device file for raw access. .TP .C "sss: Not an HP SCSI disk array" The device being addressed is not an HP SCSI disk array. .PD .TP .C "sss: Transfer length error" The amount of data actually sent to or received from the device was not the expected amount. .PP .SS SCSI (device level) communication errors: Sense data associated with the failed operation is printed. .PP .SS Error messages generated by system calls: .C sss uses the following system calls: .IP .CR malloc() , .CR free() , .CR stat() , .CR open() , .CR close() , .CR read() , .CR write() , and .CR ioctl() . .PP Documentation for these HP-UX system calls contains information about the specific error conditions associated with each call. .C sss does not alter the value of .CR errno . The interpretation of .C errno for printing purposes is performed by the system utility .CR strerror() . .SH EXAMPLES .PP To display the spindle synchronization status of drives on HP SCSI disk array .C /dev/rdsk/c2t6d0 on a Series 800: .IP .C "sss -d /dev/rdsk/c2t6d0" .PP To enable spindle synchronization on all drives of the HP SCSI disk array .C /dev/rdsk/c2t6d0 on a Series 700: .IP .C "sss -on /dev/rdsk/c2t6d0" .PP The drive on SCSI channel 3 at SCSI ID .C 0 of the HP SCSI disk array .C /dev/rdsk/c2t6d0 has just been replaced. The other drives in the array are synchronized, and the replaced one was a slave. To enable spindle synchronization on the new drive on a Series 700: .IP .C "sss -on -s c3i0 /dev/rdsk/c2t6d0" .PP If, in the replacement scenario above, the replaced drive was the master, to enable spindle synchronization and make the new drive a master: .IP .C "sss -on c3i0 /dev/rdsk/c2t6d0" .PP or, alternatively, enable the whole set again: .IP .C "sss -on /dev/rdsk/c2t6d0" .PP .SH DEPENDENCIES The HP C2425 and HP C2427 disk arrays are only supported on Series 700 systems running HP-UX version 9.0X. .PP The HP C2430 disk array is supported on Series 700 and 800 systems running HP-UX versions 9.0X and 10.0X. .SH AUTHOR .PP .C sss was developed by HP. .\" index@\f4sss\f1 \- set spindle synchronization state of drives in an \s-1HP SCSI\s+1 disk array@@@\f3sss(1M)\f1 .\" index@disk array, set spindle synchronization state of drives in@@@\f3sss(1M)\f1 .\" .\" toc@\f3sss(1M)\f1:\0\0\f4sss\f1@@@set spindle synchronization state of drives in an \s-1HP SCSI\s+1 disk array .\" .\" fileset_database@sss.1m SYS-ADMIN-MAN .\" $Header: acctsh.1m,v 72.4 94/11/14 12:02:10 ssa Exp $ .TA a .TH acctsh 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chargefee, ckpacct, dodisk, lastlogin, monacct, nulladm, prctmp, prdaily, prtacct, shutacct, startup, turnacct \- shell procedures for accounting .SH SYNOPSIS .C /usr/sbin/acct/chargefee .I login-name number .PP .C /usr/sbin/acct/ckpacct .RI [ \|blocks\| ] .PP .C /usr/sbin/acct/dodisk .RC [ -o ] .RI [ \|files \0 ...\|] .PP .C /usr/sbin/acct/lastlogin .PP .C /usr/sbin/acct/monacct .I number .PP .C /usr/sbin/acct/nulladm .I file .PP .C /usr/sbin/acct/prctmp .PP .C /usr/sbin/acct/prdaily .RC [ -l ] .RC [ -c ] .RC [ \c .IR mmdd\| ] .PP .C /usr/sbin/acct/prtacct .I file .RI [ \|heading\| ] .PP .C /usr/sbin/acct/shutacct .RI [ \|reason\| ] .PP .C /usr/sbin/acct/startup .PP .C /usr/sbin/acct/turnacct .CR on \0\(or\0 off \0\(or\0 switch .SH DESCRIPTION .TP 15 .C chargefee Can be invoked to charge a .I number of units to .IR login-name . A record is written to .CR /var/adm/fee , to be merged with other accounting records during the night. .TP .C ckpacct Should be initiated via .IR cron (1M). It periodically checks the size of .CR /var/adm/pacct . If the size exceeds .IR blocks , 1000 by default, .C turnacct is invoked with argument .IR switch . If the number of free disk blocks in the .C /var file system falls below 500, .C ckpacct automatically turns off the collection of process accounting records via the .C off argument to .CR turnacct . When at least this number of blocks is restored, the accounting will be activated again. This feature is sensitive to the frequency at which .C ckpacct is executed, usually by .CR cron . .TP .C dodisk Should be invoked by .C cron to perform the disk accounting functions. By default, it will do disk accounting on the special files in .C /etc/fstab. If the .C -o flag is used, it does a slower version of disk accounting by login directory. .I files specifies the one or more filesystem names where disk accounting is to be done. If .I files is used, disk accounting will be done on these filesystems only. If the .C -o flag is used, .I files should be mount points of mounted filesystem. If omitted, they should be the special file names of mountable filesystems. .TP .C lastlogin Invoked by .C runacct to update .C /var/adm/acct/sum/loginlog which shows the last date on which each user logged in (see .IR runacct (1M)). .TP .C monacct Should be invoked once each month or each accounting period. .I number indicates which month or period it is. If .I number is not given, it defaults to the current month (01 through 12). This default is useful if .C monacct is to executed via .CR cron on the first day of each month. .C monacct creates summary files in .C /var/adm/acct/fiscal and restarts summary files in .CR /var/adm/acct/sum . .TP .C nulladm Creates .I file with mode 664 and ensures that owner and group are .CR adm . It is called by various accounting shell procedures. .TP .C prctmp Can be used to print the session record file normally .C /var/adm/acct/nite/ctmp created by .C acctcon1 (see .IR acctcon (1M)). .TP .C prdaily Invoked by .C runacct (see .IR runacct (1M)) to format a report of the previous day's accounting data. The report resides in .CI /var/adm/acct/sum/rprt mmdd where .I mmdd is the month and day of the report. The current daily accounting reports may be printed by typing .IR prdaily . Previous days' accounting reports can be printed by using the .I mmdd option and specifying the exact report date desired. The .C -l flag prints a report of exceptional usage by login id for the specifed date. Previous daily reports are cleaned up and therefore inaccessible after each invocation of .CR monacct . The .C -c flag prints a report of exceptional resource usage by command, and can be used on current day's accounting data only. .TP .C prtacct Can be used to format and print any total accounting .RC ( tacct ) file. .TP .C shutacct Should be invoked during a system shutdown to turn process accounting off and append a ``reason'' record to .CR /var/adm/wtmp . .TP .C startup Should be called by system startup scripts to turn the accounting on whenever the system is brought up. .TP .C turnacct An interface to .C accton (see .IR acct (1M)) to turn process accounting .C on or .CR off . The .C switch argument turns accounting off, moves the current .C /var/adm/pacct to the next free name in .CI /var/adm/pacct incr then turns accounting back on again. .RI ( incr is a number starting with .C 1 and incrementing by one for each additional .C pacct file.) .C turnacct is called by .CR ckpacct , and thus can be run under .C cron and used to keep .C pacct to a reasonable size. .SH FILES .TP 40 .C /usr/sbin/acct holds all accounting commands listed in section (1M) of this manual .PD 0 .TP .C /var/adm/fee accumulator for fees .TP .C /var/adm/acct/nite working directory .TP .C /var/adm/pacct current file for per-process accounting .TP .C /var/adm/pacct* used if .C pacct gets large, and during execution of daily accounting procedure .TP .C /usr/sbin/acct/ptecms.awk contains the limits for exceptional usage by command name .TP .C /usr/sbin/acct/ptelus.awk contains the limits for exceptional usage by login id .TP .C /var/adm/acct/sum summary directory, should be saved .TP .C /var/adm/wtmp login/logoff summary .PD .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), cron(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR chargefee ": SVID2, SVID3" .PP .CR ckpacct ": SVID2, SVID3" .PP .CR dodisk ": SVID2, SVID3" .PP .CR lastlogin ": SVID2, SVID3" .PP .CR monacct ": SVID2, SVID3" .PP .CR prctmp ": SVID2, SVID3" .PP .CR prdaily ": SVID2, SVID3" .PP .CR prtacct ": SVID2, SVID3" .PP .CR shutacct ": SVID2, SVID3" .PP .CR startup ": SVID2, SVID3" .PP .CR turnacct ": SVID2, SVID3" .\" .\" .\" index@\f1process accounting@@@see accounting .\" index@\f1accounting: \f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4turnacct\f1 \- turn on or turn off process accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1bill fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1user, bill fee to, based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1disk accounting, perform@@@\f3acctsh(1M)\f1 .\" index@\f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1user, show last login date for each@@@\f3acctsh(1M)\f1 .\" index@\f1last login date, show for each user@@@\f3acctsh(1M)\f1 .\" index@\f1login date, show last for each user@@@\f3acctsh(1M)\f1 .\" index@\f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1periodic accounting summary files, create@@@\f3acctsh(1M)\f1 .\" index@\f1accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1files: accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1summary files, accounting, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1create empty administration file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1empty administration file owned by \f3adm\f1 with mode 664, create@@@\f3acctsh(1M)\f1 .\" index@\f1administration file owned by \f3adm\f1 with mode 664, create empty@@@\f3acctsh(1M)\f1 .\" index@\f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f4acctcon1\f1 \- print session record file created by@@@\f3acctsh(1M)\f1 .\" index@\f1print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1files, accounting: print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1session record file created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f1record file, session, created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1total accounting (\f4tacct\f1) file, print any@@@\f3acctsh(1M)\f1 .\" index@\f1accounting (\f4tacct\f1) file, print any total@@@\f3acctsh(1M)\f1 .\" index@\f4tacct\f1 (total accounting) file, print any@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting: \f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" index@\f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting data and command usage summary, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f1command usage summary and accounting data, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1system shutdown, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f1shutdown, system, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1system startup, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f1startup, system, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f4turnacct\f1 \- turn process accounting on or off@@@\f3acctsh(1M)\f1 .\" index@\f1shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f1system accounting, shell procedures for@@@\f3acctsh(1M)\f1 .\" .\"" Main TOC entry .\" toc@\f3acctsh(1M)\f1:\0\0\f4chargefee\f1, \f4ckpacct\f1, \f4dodisk\f1, \f4lastlogin\f1, \f4monacct\f1, \f4nulladm\f1, \f4prctmp\f1, \f4prdaily\f1,\n\f4prtacct\f1, \f4shutacct\f1, \f4startup\f1, \f4turnacct\f1@@@shell procedures for accounting .\" .\" toc@\f4chargefee\f1:\0\0shell procedures for accounting, charge fee to user@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4ckpacct\f1:\0\0shell procedures for accounting, check size of accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4dodisk\f1:\0\0shell procedures for accounting, perform disk accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4lastlogin\f1:\0\0shell procedures for accounting, show last login date@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4monacct\f1:\0\0shell procedures for accounting, create accounting summary@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4nulladm\f1:\0\0shell procedures for accounting, create null file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prctmp\f1:\0\0shell procedures for accounting, print session record file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prdaily\f1:\0\0shell procedures for accounting, print daily report@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prtacct\f1:\0\0shell procedures for accounting, print accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4shutacct\f1:\0\0shell procedures for accounting, turn off accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4startup\f1:\0\0shell procedures for accounting, start up accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4turnacct\f1:\0\0shell procedures for accounting, turn on or off process accounting@@@\f1see \f3acctsh(1M)\f1 .\" .\" links@acctsh.1m chargefee.1m .\" links@acctsh.1m ckpacct.1m .\" links@acctsh.1m dodisk.1m .\" links@acctsh.1m lastlogin.1m .\" links@acctsh.1m monacct.1m .\" links@acctsh.1m nulladm.1m .\" links@acctsh.1m prctmp.1m .\" links@acctsh.1m prdaily.1m .\" links@acctsh.1m prtacct.1m .\" links@acctsh.1m shutacct.1m .\" links@acctsh.1m startup.1m .\" links@acctsh.1m turnacct.1m .\" .\" fileset_database@acctsh.1m SYS-ADMIN-MAN .\" $Header: statd.1m,v 78.1 96/01/03 15:27:52 ssa Exp $ .TA s .TH statd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME statd \- network status monitor .SH SYNOPSIS .C /usr/sbin/rpc.statd .RC [ -l .IR log_file ] .SH DESCRIPTION .CR statd is an RPC server. It interacts with .CR lockd to provide crash and recovery functions for the locking services on NFS (see .IR lockd (1M)). .SS Options .CR statd recognizes the following options and command-line arguments: .TP 15 .CI -l \0log_file Log any errors to the named log file, .IR log_file . Errors are not logged if the .CR -l option is not specified. .IP Information logged to the file includes date and time of the error, host name, process id and name of the function generating the error, and the error message. .SH FILES .CR /var/statmon/sm/* .br .CR /var/statmon/sm.bak/* .br .CR /var/statmon/state .SH WARNINGS Changes in status of a site are detected only upon startup of a new status monitor and lock daemon. .SH AUTHOR .CR statd was developed by Sun Microsystems, Inc. .SH SEE ALSO fcntl(2), lockf(2), signal(2), lockd(1M), sm(4). .\" .\" index@\f4statd\f1 \- network status monitor@@@\f3statd(1M)\f1 .\" index@\f1network status monitor@@@\f3statd(1M)\f1 .\" index@\f1status monitor, network@@@\f3statd(1M)\f1 .\" index@\f1monitor, network status@@@\f3statd(1M)\f1 .\" .\" toc@\f3statd(1M)\f1:\0\0\f4statd\f1@@@network status monitor .\" .\" links@statd.1m rpc.statd.1m .\" $Header: stcode.1m,v 72.4 94/10/27 14:46:35 ssa Exp $ .TA s .TH stcode 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME stcode \- translate hexadecimal status code value to textual message .SH SYNOPSIS .C /usr/sbin/ncs/stcode .I hex_stat_code .SH DESCRIPTION .C stcode prints the textual message associated with a hexadecimal status code. This command is useful when a program produces a hexadecimal status code instead of a textual message. .PP .C stcode processes predefined status codes. No provision is currently made to add user-defined status codes to the error text database. .PP .I hex_stat_code is the hexadecimal status code to be translated. .SH EXAMPLES Translate the hexadecimal status code 1c010003: .IP .C $ stcode 1c010003 .br unknown interface (network computing system/RPC runtime) .\" .\" index@\f4stcode\f1 \- translate hexadecimal status code value to textual message@@@\f3stcode(1M)\f1 .\" index@translate hexadecimal status code value to textual message@@@\f3stcode(1M)\f1 .\" index@status code value to textual message, translate hexadecimal@@@\f3stcode(1M)\f1 .\" index@code value to textual message, translate hexadecimal status@@@\f3stcode(1M)\f1 .\" index@value to textual message, translate hexadecimal status code@@@\f3stcode(1M)\f1 .\" index@textual message, translate hexadecimal status code value to@@@\f3stcode(1M)\f1 .\" index@message, translate hexadecimal status code value to textual@@@\f3stcode(1M)\f1 .\" .\" toc@\f3stcode(1M)\f1:\0\0\f4stcode\f1@@@translate hexadecimal status code value to textual message .\" .\" fileset_database@stcode.1m SYS-ADMIN-MAN .\" $Header: strace.1m,v 72.2 94/08/30 16:59:44 ssa Exp $ .TA s .TH strace 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strace \- write STREAMS event trace messages to standard output .SH SYNOPSIS .C strace [ .I mod sub pri .C ] ... .SH DESCRIPTION .C strace gets STREAMS event trace messages from STREAMS drivers and modules via the STREAMS log driver .RC ( strlog(7) ), and writes these messages to standard output. By default, .C strace without arguments writes all STREAMS trace messages from all drivers and modules. .C strace with command-line arguments limits the trace messages received. .PP The arguments, which must be specified in groups of three, are: .RS .TP .I mod Specifies the STREAMS module identification number from the streamtab entry. .TP .I sub Specifies a subidentification number (often corresponding to a minor device). .TP .I pri Specifies a tracing priority level. .C strace gets messages of a level equal to or less than the value specified by .IR pri. Only positive integer values are allowed. .RE .PP The value .C all can be used for any argument in the .C strace command line to indicate that there are no restrictions for that argument. .PP Multiple sets of the three arguments can be specified to obtain the messages from more than one driver or module. .PP Only one .C strace process can open the STREAMS log driver at a time. .PP When .C strace is invoked, the log driver compares the sets of command line arguments with actual trace messages, returning only messages that satisfy the specified criteria. .PP STREAMS event trace messages have the following format: .IP .I seq time tick pri ind mod \c .I sub text .PP Components are interpreted as follows: .RS .TP .I seq Trace event sequence number. .TP .I time Time the message was sent expressed in .I hh:mm:ss. .TP .I tick Time the message was sent expressed in machine ticks since the last boot. .TP .I pri Tracing priority level as defined by the STREAMS driver or module that originates the messages. .TP .I ind Can be any combination of the following three message indicators: .RS .RS .TP .C E The message has also been saved in the error log. .TP .C F The message signaled a fatal error. .TP .C N The message has also been mailed to the system administrator. .RE .RE .TP .I mod Module identification number of the trace message source. .TP .I sub Subidentification number of the trace message source. .TP .I text Trace message text. .RE .PP .C strace runs until terminated by the user. .SH EXAMPLES Display all trace messages received from the driver or module identified by .I mod .CR 28 : .IP .C strace 28 all all .PP Display trace messages of any tracing priority level from the driver or module identified by .I mod .C 28 and its minor devices identified by the .IR sub .CR 2 , .CR 3 , or .CR 4 : .IP .C "strace 28 2 all 28 3 all 28 4 all" .PP Display the trace messages from the same driver or module and .IR subs but limit the priority levels to 0 for .IR subs 2 and 3; 1 for .I sub 4, driver or module .CR 28 : .IP .C "strace 28 2 0 28 3 0 28 4 1" .PP .RE .SH WARNINGS Running .C strace with several sets of arguments can impair STREAMS performance, particularly for those modules and drivers that are sending the messages. .PP Also be aware that .C strace may not be able to handle a large number of messages. If drivers and modules return messages to .C strace too quickly, some may be lost. .SH FILES .TP 50 .C /usr/lib/nls/msg/C/strace.cat NLS catalog for .CR strace . .SH SEE ALSO strclean(1M), strerr(1M), strlog(7). .\" .\" index@\f4strace\f1 \- write STREAMS event trace messages to standard output@@@\f3strace(1M)\f1 .\" index@\f1write STREAMS event trace messages to standard output@@@\f3strace(1M)\f1 .\" index@\f1STREAMS event trace messages to standard output, write@@@\f3strace(1M)\f1 .\" index@\f1event trace messages to standard output, write STREAMS event trace messages@@@\f3strace(1M)\f1 .\" index@\f1trace messages to standard output, write STREAMS event trace messages@@@\f3strace(1M)\f1 .\" .\" toc@\f3strace(1M)\f1:\0\0\f4strace\f1@@@write STREAMS event trace messages to standard output .\" .\" fileset_database@strace.1m STREAMS-MAN .\" $Header: strchg.1m,v 78.1 95/12/20 11:12:57 ssa Exp $ .TA s .TH strchg 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strchg, strconf \- change or query stream configuration .SH SYNOPSIS .CI "strchg -h " module1\c .RC [ , .IR module2 ]... .PP .CR "strchg -p" [ .CR -a \(or -u .IR module ] .PP .CR "strchg -f" .I file .PP .CR strconf .PP .CR "strconf -t" .PP .CI "strconf -m " module .SH DESCRIPTION The .CR strchg and .CR strconf commands are used to change or query the configuration of the stream associated with the user's standard input. The .CR strchg command pushes modules on and/or pops modules off the stream. The .CR strconf command queries the configuration of the stream. Only the superuser or owner of a STREAMS device may alter the configuration of that stream. .P .SS strchg Options The .CR strchg command uses the following options: .P .TP 20 .C "-h " \f2module1\f1[,\f2 module2 \f1] ... .CR strchg pushes modules onto a stream. The modules are pushable STREAMS modules as defined by .IR module1 , .IR module2 , and so on. The modules are pushed in order. That is, .IR module1 is pushed first, .IR module2 is pushed second, etc. .TP 20 .CR -p With the .CR -p option alone, .CR strchg pops the topmost module from the stream. .TP 20 .CR -a With the .CR -p and .CR -a options, all the modules above the topmost driver are popped. .TP 20 .CI "-u " module With the .CR -p and .CR -u .IR module options, all modules above but not including module are popped off the stream. .P The .CR -a and .CR -u options are mutually exclusive. .TP 20 .CI "-f " file The user can specify a .IR file that contains a list of modules representing the desired configuration of the stream. Each module name must appear on a separate line where the first name represents the topmost module and the last name represents the module that should be closest to the driver. The .CR strchg command will determine the current configuration of the stream and pop and push the necessary modules in order to end up with the desired configuration. .P The .CR -h , .CR -f , and .CR -p options are mutually exclusive. .P .SS strconf Options Invoked without any arguments, .CR strconf prints a list of all the modules in the stream as well as the topmost driver. The list is printed in one name per line where the first name printed is the topmost module on the stream (if one exists) and the last item printed is the name of the driver. .P The .CR strconf command uses the following options: .TP 15 .CR -t Only the topmost module (if one exists) is printed. .TP 15 .CI "-m " module .CR strconf checks if the named .IR module is present on the stream. If so, .CR strconf prints the message, .CR yes , and returns zero. If not, .CR strconf prints the message, .CR no , and returns a non-zero value. .P The .CR -t and .CR -m options are mutually exclusive. .SS Notes If the user is neither the owner of the stream nor the superuser, the .CR strchg command will fail. If the user does not have read permissions on the stream and is not the superuser, the .CR strconf command will fail. .P If modules are pushed in the wrong order, one could end up with a stream that does not function as expected. For ttys, if the line discipline module is not pushed in the correct place, one could have a terminal that does not respond to any commands. .SH DIAGNOSTICS .CR strchg returns zero on success. It prints an error message and returns non-zero status for various error conditions, including usage error, bad module name, too many modules to push, failure of an .CR ioctl on the stream, or failure to open file from the .CR -f option. .P .CR strconf returns zero on success (for the .CR -m or .CR -t option, "success" means the named or topmost module is present). It returns a non-zero status if invoked with the .CR -m or .CR -t option and the module is not present. It prints an error message and returns non-zero status for various error conditions, including usage error or failure of an .CR ioctl on the stream. .P .SH EXAMPLES The following command pushes the module .CR ldterm on the stream associated with the user's standard input: .P .C strchg -h ldterm .P The following command pops the topmost module from the stream associated with .CR /dev/term/24 . The user must be the owner of this device or be superuser. .P .C strchg -p < /dev/term/24 .P If the file, .CR fileconf , contains the following: .P .C compat .PP .C ldterm .PP .C ptem .P then the command .P .C strchg -f fileconf .P will configure the user's standard input stream so that the module .CR ptem is pushed over the driver, followed by .CR ldterm and .CR compat closest to the stream head. .P The .CR strconf command with no arguments lists the modules and topmost driver on the stream. For a stream that only has the module .CR ldterm pushed above the ports driver, it would produce the following output: .P .C ldterm .PP .C ports .P The following command asks if .CR ldterm is on the stream: .P .C strconf -m ldterm .P and produces the following output while returning an exit status of 0: .P .C yes .P .SH FILES .PD 0 .TP 50 .CR /usr/lib/nls/msg/C/strchg.cat NLS catalogs .TP .CR /usr/lib/nls/msg/C/strconf.cat NLS catalogs .PD .SH SEE ALSO streamio(7). .\" .\" index@\f4strchg\f1 \- change or query stream configuration@@@\f3strchg(1M)\f1 .\" index@\f4strconf\f1 \- query stream configuration@@@\f3strchg(1M)\f1 .\" index@\f1change or query stream configuration@@@\f3strchg(1M)\f1 .\" index@\f1query stream configuration@@@\f3strchg(1M)\f1 .\" index@\f1stream configuration, change or query@@@\f3strchg(1M)\f1 .\" index@\f1STREAMS, change or query stream configuration@@@\f3strchg(1M)\f1 .\" .\" Main TOC entry .\" toc@\f3strchg(1M)\f1:\0\0\f4strchg\f1, \f4strconf\f1@@@change or query stream configuration .\" .\" toc@\f4strconf\f1:\0\0query stream configuration@@@\f1see \f3strchg(1M)\f1 .\" .\" links@strchg.1m strconf.1m .\" fileset_database@strchg.1m STREAMS-MAN .\" $Header: strclean.1m,v 78.1 95/12/20 11:14:01 ssa Exp $ .TA s .TH strclean 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strclean \- remove outdated STREAMS error log files .SH SYNOPSIS .C strclean .RC [ -d .IR logdir\| ] .RC [ -a .IR age\| ] .SH DESCRIPTION .C strclean cleans the STREAMS error logger directory of log files .RC ( error.\c .IR mm-dd ) that contain error messages sent by the STREAMS log driver .RC ( strlog(7) ). If the .CR -d option is not used to specify another directory, .C strclean removes error log files in the .C /var/adm/streams directory. If the .CR -a option is not used to specify another age, .C strclean removes error log files that have not been modified in three days. .SS Options .C strclean recognizes the following options and command-line arguments: .TP 15 .CI -d \0logdir Specifies a directory for the location of the STREAMS error log files to be removed if this is not the default directory .CR /var/adm/streams . .TP .CI -a \0age Specifies a maximum age in days for the STREAMS error log files if this not the default age of 3. The value of .I age must be an integer greater than or less than 3. .SH EXAMPLES Remove day-old error log files from a directory called .CR /tmp/streams : .IP .C "strclean -d /tmp/streams -a 1" .SH FILES .TP 35 .CI /var/adm/streams/error.mm-dd One or more error log file or files on which .C strclean operates. The .I mm-dd in the filename indicates the month and day of the messages contained in the file. .TP 35 .C /usr/lib/nls/msg/C/strclean.cat NLS catalog for .CR strclean . .RE .SH SEE ALSO strerr(1M), strlog(7). .\" .\" index@\f4strclean\f1 \- remove outdated STREAMS error log files@@@\f3strclean(1M)\f1 .\" index@\f1remove outdated STREAMS error log files@@@\f3strclean(1M)\f1 .\" index@\f1STREAMS error log files, remove outdated files@@@\f3strclean(1M)\f1 .\" index@\f1error log files, remove outdated STREAMS error log files@@@\f3strclean(1M)\f1 .\" index@\f1log files, remove outdated STREAMS error log files@@@\f3strclean(1M)\f1 .\" index@\f1files, remove outdated STREAMS error log files@@@\f3strclean(1M)\f1 .\" .\" toc@\f3strclean(1M)\f1:\0\0\f4strclean\f1@@@remove outdated STREAMS error log files .\" .\" fileset_database@strclean.1m STREAMS-MAN .\" $Header: strchg.1m,v 78.1 95/12/20 11:12:57 ssa Exp $ .TA s .TH strchg 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strchg, strconf \- change or query stream configuration .SH SYNOPSIS .CI "strchg -h " module1\c .RC [ , .IR module2 ]... .PP .CR "strchg -p" [ .CR -a \(or -u .IR module ] .PP .CR "strchg -f" .I file .PP .CR strconf .PP .CR "strconf -t" .PP .CI "strconf -m " module .SH DESCRIPTION The .CR strchg and .CR strconf commands are used to change or query the configuration of the stream associated with the user's standard input. The .CR strchg command pushes modules on and/or pops modules off the stream. The .CR strconf command queries the configuration of the stream. Only the superuser or owner of a STREAMS device may alter the configuration of that stream. .P .SS strchg Options The .CR strchg command uses the following options: .P .TP 20 .C "-h " \f2module1\f1[,\f2 module2 \f1] ... .CR strchg pushes modules onto a stream. The modules are pushable STREAMS modules as defined by .IR module1 , .IR module2 , and so on. The modules are pushed in order. That is, .IR module1 is pushed first, .IR module2 is pushed second, etc. .TP 20 .CR -p With the .CR -p option alone, .CR strchg pops the topmost module from the stream. .TP 20 .CR -a With the .CR -p and .CR -a options, all the modules above the topmost driver are popped. .TP 20 .CI "-u " module With the .CR -p and .CR -u .IR module options, all modules above but not including module are popped off the stream. .P The .CR -a and .CR -u options are mutually exclusive. .TP 20 .CI "-f " file The user can specify a .IR file that contains a list of modules representing the desired configuration of the stream. Each module name must appear on a separate line where the first name represents the topmost module and the last name represents the module that should be closest to the driver. The .CR strchg command will determine the current configuration of the stream and pop and push the necessary modules in order to end up with the desired configuration. .P The .CR -h , .CR -f , and .CR -p options are mutually exclusive. .P .SS strconf Options Invoked without any arguments, .CR strconf prints a list of all the modules in the stream as well as the topmost driver. The list is printed in one name per line where the first name printed is the topmost module on the stream (if one exists) and the last item printed is the name of the driver. .P The .CR strconf command uses the following options: .TP 15 .CR -t Only the topmost module (if one exists) is printed. .TP 15 .CI "-m " module .CR strconf checks if the named .IR module is present on the stream. If so, .CR strconf prints the message, .CR yes , and returns zero. If not, .CR strconf prints the message, .CR no , and returns a non-zero value. .P The .CR -t and .CR -m options are mutually exclusive. .SS Notes If the user is neither the owner of the stream nor the superuser, the .CR strchg command will fail. If the user does not have read permissions on the stream and is not the superuser, the .CR strconf command will fail. .P If modules are pushed in the wrong order, one could end up with a stream that does not function as expected. For ttys, if the line discipline module is not pushed in the correct place, one could have a terminal that does not respond to any commands. .SH DIAGNOSTICS .CR strchg returns zero on success. It prints an error message and returns non-zero status for various error conditions, including usage error, bad module name, too many modules to push, failure of an .CR ioctl on the stream, or failure to open file from the .CR -f option. .P .CR strconf returns zero on success (for the .CR -m or .CR -t option, "success" means the named or topmost module is present). It returns a non-zero status if invoked with the .CR -m or .CR -t option and the module is not present. It prints an error message and returns non-zero status for various error conditions, including usage error or failure of an .CR ioctl on the stream. .P .SH EXAMPLES The following command pushes the module .CR ldterm on the stream associated with the user's standard input: .P .C strchg -h ldterm .P The following command pops the topmost module from the stream associated with .CR /dev/term/24 . The user must be the owner of this device or be superuser. .P .C strchg -p < /dev/term/24 .P If the file, .CR fileconf , contains the following: .P .C compat .PP .C ldterm .PP .C ptem .P then the command .P .C strchg -f fileconf .P will configure the user's standard input stream so that the module .CR ptem is pushed over the driver, followed by .CR ldterm and .CR compat closest to the stream head. .P The .CR strconf command with no arguments lists the modules and topmost driver on the stream. For a stream that only has the module .CR ldterm pushed above the ports driver, it would produce the following output: .P .C ldterm .PP .C ports .P The following command asks if .CR ldterm is on the stream: .P .C strconf -m ldterm .P and produces the following output while returning an exit status of 0: .P .C yes .P .SH FILES .PD 0 .TP 50 .CR /usr/lib/nls/msg/C/strchg.cat NLS catalogs .TP .CR /usr/lib/nls/msg/C/strconf.cat NLS catalogs .PD .SH SEE ALSO streamio(7). .\" .\" index@\f4strchg\f1 \- change or query stream configuration@@@\f3strchg(1M)\f1 .\" index@\f4strconf\f1 \- query stream configuration@@@\f3strchg(1M)\f1 .\" index@\f1change or query stream configuration@@@\f3strchg(1M)\f1 .\" index@\f1query stream configuration@@@\f3strchg(1M)\f1 .\" index@\f1stream configuration, change or query@@@\f3strchg(1M)\f1 .\" index@\f1STREAMS, change or query stream configuration@@@\f3strchg(1M)\f1 .\" .\" Main TOC entry .\" toc@\f3strchg(1M)\f1:\0\0\f4strchg\f1, \f4strconf\f1@@@change or query stream configuration .\" .\" toc@\f4strconf\f1:\0\0query stream configuration@@@\f1see \f3strchg(1M)\f1 .\" .\" links@strchg.1m strconf.1m .\" fileset_database@strchg.1m STREAMS-MAN .\" $Header: strdb.1m,v 78.1 95/12/20 11:14:48 ssa Exp $ .TA s .TH strdb 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strdb \- STREAMS debugging tool .SH SYNOPSIS .C strdb .RI [ \0\|system\| \0[ \0\|core\| \0]\0] .SH DESCRIPTION .C strdb symbolically displays the contents of various STREAMS data structures. The arguments, .I system and .I core, allow substitutes for the defaults .C /stand/vmunix and .CR /dev/kmem . .PP .C strdb runs in two modes, STREAMS subsystem and primary. STREAMS subsystem commands report the status of open streams. Primary commands display STREAMS data structures. .PP In a typical .C strdb session, you will do the following: .RS .TP 3 .C \(bu Run .CR strdb . When .C strdb starts up, you are in primary mode. .TP .C \(bu Execute the .CR :S command to enter STREAMS subsystem mode. .TP .C \(bu Enter STREAMS subsystem commands such as .CR s , .CR d , and .CR la to find the open stream you want to examine. .TP .C \(bu Enter the .CR qh command to select a stream and display the stream head read queue. This command returns you to primary mode. .TP .C \(bu Enter primary mode navigation keys to display fields in the stream head read queue, and traverse the rest of the stream's queues. .RE .PP The following commands are available in primary mode. .RS .TP 18 .C :? Display a help menu for primary mode. .TP .C ^D Exit from .CR strdb . .TP .C :q Exit from .CR strdb . .TP .C ^K If logging is enable, dump current screen to log file .TP .C ^L Refresh the screen. .TP .C :u Disable data structure stacking. By default data structure stacking is turned on. When stacking is on, \c .C strdb pushes each structure it displays onto a stack so that it can be reviewed later. See .C ^P and other stack commands described below. .TP .C :s Re-enable data structure stacking. By default data structure stacking is turned on. The .C :u command turns it off. When stacking is on, \c .C strdb pushes each structure it displays onto a stack so that it can be reviewed later. See .C ^P and other stack commands described below. .TP .C :l \0\f2name\fP \0o \f1|\fP c If the \c .C o option is specified, open a log file, .I name, and start logging. Alternatively if the \c .C c option is specified, close a log file, .I name, and stop logging. .TP .C :S Enter STREAMS subsystem mode. .TP .IR "navigation key" Display the field specified by .IR "navigation key" in the currently displayed data structure. .C strdb provides different navigation keys for each STREAMS data structure. Each key indicates a particular field in the data structure to display. The navigation keys for STREAMS data structures are described after the STREAMS subsystem commands below. .TP .C ? Display a help menu for the displayed data structure's navigation keys. .TP .C ^R Update the displayed data structure with new values from \c .C /dev/kmem on a running system. This command has no effect when examining a core file. .TP .C ^P Pop the displayed data structure off the data structure stack, and display the data structure now at the top of the stack. .TP .C :m Mark the displayed data structure. Later the data structure stack can be popped back to this structure using .C ^U as described below. .TP .C ^U Pop the data structure stack back to a structure marked with .CR :m , and display this structure. .TP .C ^T Transpose the top two data structure stack entries. Unlike .CR ^P , this command allows the data structure on the top of the stack to be saved for later viewing. .TP .CI :b \0\f2addr \0\f1[\fP\0\f2len\fP\0\f1]\fP Display .I len bytes of binary data at address .I addr. The default for .I len is 256. .TP .C :x \0\f2name \0\f2addr\fP Display structure .I name located at address .I addr. .TP .C :x ? Display the structure names accepted by .CR :x . .RE .sp 1 .PP The following commands are available in STREAMS subsystem mode. .RS .TP 18 .C ? Display a help menu for STREAMS subsystem mode. .TP .C h Display a help menu for STREAMS subsystem mode. .TP .C q Exit from STREAMS subsystem mode to primary mode. .TP .C v Print the version of STREAMS data structures displayed. .TP .C s \0d \f1|\fP m If the .C d option is specified, list the STREAMS drivers included in the kernel .C S800 or .C dfile file. Alternatively if the .C m option is specified, list the included modules. .TP .C la \0\f2name List all open streams for device .I name. The .I name is one of those shown by the .C s command. .TP 20 .C lm \0\f2name \0\f2minor\fP List all modules pushed on the stream for device .IR name and minor .IR minor . .TP .C ll \0\f2name \0\f2minor\fP List all drivers linked under the multiplexor .IR name with minor .IR minor . .TP .C lp \0\f2name \0\f2minor\fP List all drivers persistently linked under the multiplexor .IR name with minor .IR minor . .TP .C qc \0\f2name \0\f2file\fP Write the .C q_count values for the driver .IR name into file, .IR file . .TP .C qh \0\f2name \0\f2minor\fP Display the streams head read queue for the STREAMS driver .IR name and minor .IR minor . This command returns the user to primary mode. .RE .sp 1 .PP .C strdb provides different navigation keys for each STREAMS data structure it displays. Each key indicates a particular data structure field to display. The navigation keys for each STREAMS data structure are described in the following paragraphs. .PP The navigation keys for the STREAMS .C queue structure are: .RS .TP 18 .C i Displays the .C q_init structure pointed to by the .C q_qinfo field. .TP .C m Displays the .C msgb structure pointed to by the .C q_first field. .TP .C z Displays the .C msgb structure pointed to by the .C q_last field. .TP .C n Displays the .C queue structure pointed to by the .C q_next field. .TP .C l Displays the .C queue structure pointed to by the .C q_link field. .TP .C b Displays the .C qband structure pointed to by the .C q_bandp field. .TP .C o Displays the .C queue structure pointed to by the .C q_other field. .RE .sp 1 .PP The navigation keys for the STREAMS .C qinit structure are: .RS .TP 18 .C i Displays the .C module_info structure pointed to by the .C qi_minfo field. .TP .C s Displays the .C module_stat field pointed to by the .C qi_mstat field. .RE .sp 1 .PP The navigation keys for the STREAMS .C msgb structure are: .RS .TP 18 .C n Displays the .C msgb structure pointed to by the .C b_next field. .TP .C p Displays the .C msgb structure pointed to by the .C b_prev field. .TP .C m Displays the data pointed to by the .C b_rptr field. .TP .C c Displays the .C msgb structure pointed to by the .C b_cont field. .TP .C d Displays the .C datab structure pointed to by the .C b_datap field. .RE .sp 1 .PP The navigation keys for the STREAMS .C datab structure are: .RS .TP 18 .C d Displays the .C a__datab structure pointed to by the .C db_f field. .RE .sp 1 .PP The navigation keys for the STREAMS .C qband structure are: .RS .TP 18 .C n Displays the .C qband structure pointed to by the .C qb_next field. .TP .C f Displays the .C msgb structure pointed to by the .C qb_first field. .TP .C l Displays the .C msgb structure pointed to by the .C qb_last field. .SH AUTHOR .C strdb was developed by HP. .SH SEE ALSO .IR "STREAMS/UX for HP9000 Reference Manual" . .\" .\" index@\f4strdb\f1 \- STREAMS debugging tool@@@\f3strdb(1M)\f1 .\" index@\f1STREAMS debugging tool@@@\f3strdb(1M)\f1 .\" index@\f1debugging tool, STREAMS debugging tool@@@\f3strdb(1M)\f1 .\" index@\f1show STREAMS structures@@@\f3strdb(1M)\f1 .\" index@\f1display STREAMS structures@@@\f3strdb(1M)\f1 .\" index@\f1STREAMS structures show@@@\f3strdb(1M)\f1 .\" index@\f1structures show STREAMS@@@\f3strdb(1M)\f1 .\" .\" toc@\f3strdb(1M)\f1:\0\0\f4strdb\f1@@@STREAMS debugging tool .\" .\" fileset_database@strdb.1M STREAMS-MAN .\" $Header: strerr.1m,v 78.1 95/12/20 11:15:29 ssa Exp $ .TA s .TH strerr 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strerr \- receive error messages from the STREAMS log driver .SH SYNOPSIS .C strerr .RC [ -a .IR sys_admin_mail_name\| ] .RC [ -d .IR logdir\| ] .SS Options .C strerr recognizes the following options and command-line arguments: .TP 30 .CI -a \0sys_admin_mail_name Specify the user's mail name for sending mail messages. Mail is sent to the system administrator by default. .TP 30 .CI -d \0logdir Specify the directory to contain the error log file. Default is .CR /var/adm/streams . .SH DESCRIPTION The .C strerr daemon receives error messages from the STREAMS log driver .RC ( strlog(7) ) for addition to the STREAMS error log files .RC ( error.\c .IR mm-dd ) in the STREAMS error logger directory .RC ( /var/adm/streams by default). When first called, .C strerr creates the log file .CI error. mm-dd\f1. This is a daily log file, where .I mm indicates the month and .I dd indicates the day of the logged messages. .C strerr then appends error messages to the log file as they are received from the STREAMS log driver. .PP STREAMS error log messages have the following format: .IP .I seq time tick pri ind mod \c .I sub text .PP Components are interpreted as follows: .RS .TP .I seq Error event sequence number. .TP .I time Time the message was sent expressed in .I hh:mm:ss. .TP .I tick Time the message was sent expressed in machine ticks since the last boot. .TP .I pri Error priority level as defined by the STREAMS driver or module that originates the messages. .TP .I ind Can be any combination of the following three message indicators: .RS .RS .TP .C T The message has also been saved in the trace log. .TP .C F The message signaled a fatal error. .TP .C N The message has also been mailed to the system administrator. .RE .RE .TP .I mod Module identification number of the error message source. .TP .I sub Subidentification number of the error message source. .TP .I text Error message text. .RE .PP .C strerr runs continuously until terminated by the user. .SH WARNINGS Only one .C strerr process can open the STREAMS log driver at a time. This restriction is intended to maximize performance. .PP The STREAMS error logging mechanism works best when it is not overused. .C strerr can degrade STREAMS performance by affecting the response, throughput, and other behaviors of the drivers and modules that invoke it. .C strerr also fails to capture messages if drivers and modules generate messages at a higher rate than its optimum read rate. If there are missing sequence numbers among the messages in a log file, messages have been lost. .SH FILES .TP 35 .C /usr/lib/nls/msg/C/strerr.cat NLS catalog for .CR strerr . .TP 35 .CI /var/adm/streams/error.mm-dd error log file or files on which .C strerr operates .SH SEE ALSO strace(1M), strlog(7). .\" .\" index@\f4strerr\f1 \- receive error messages from the STREAMS log driver@@@\f3strerr(1M)\f1 .\" index@\f1receive error messages from the STREAMS log driver@@@\f3strerr(1M)\f1 .\" index@\f1error messages from the STREAMS log driver@@@\f3strerr(1M)\f1 .\" index@\f1STREAMS log driver, receive error messages@@@\f3strerr(1M)\f1 .\" index@\f1log driver, receive error messages from the STREAMS log driver@@@\f3strerr(1M)\f1 .\" .\" toc@\f3strerr(1M)\f1:\0\0\f4strerr\f1@@@receive error messages from the STREAMS log driver .\" .\" fileset_database@strerr.1m STREAMS-MAN .\" $Header: strvf.1m,v 78.1 95/12/20 11:17:15 ssa Exp $ .TA s .TH strvf 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strvf \- STREAMS verification tool .SH SYNOPSIS .C strvf .RC [ -v ] .SH DESCRIPTION .C strvf executes a series of subcommands that verify whether or not STREAMS is currently installed and configured on your system. All output is sent to .CR stdout . Verbose output is always sent to the logfile .CR /var/adm/streams/strvf.log . .P These subcommands make sure that the STREAMS kernel daemons are running and that .CR open() , .CR putmsg() , .CR getmsg() , .CR ioctl() , and .CR close() can be performed on .CR /dev/echo . .SS Options .TP 15 .CI -v Specifies verbose output to be displayed .SH EXAMPLES .TP 20 .CR "strvf" Verify STREAMS is working. Brief summary of status is displayed on screen. Verbose description of each subcommand and its status is copied to the logfile. .TP 20 .CR "strvf -v" Verify STREAMS is working. Verbose description of each subcommand and its status is displayed on the screen and copied to the logfile. This option is useful in troubleshooting .C strvf failures. .SH FILES .TP 40 .CI /var/adm/streams/strvf.log Logfile containing a verbose description and status of all sub-commands. .TP .CI /dev/echo Loopback STREAMS driver used by .CR strvf . .RE .SH SEE ALSO open(2), close(2), getmsg(2), putmsg(2), streamio(7). .\" .\" index@\f4strvf\f1 \- STREAMS verification tool@@@\f3strvf(1M)\f1 .\" index@\f1STREAMS verification tool@@@\f3strvf(1M)\f1 .\" index@\f1verification tool, STREAMS@@@\f3strvf(1M)\f1 .\" .\" toc@\f3strvf(1M)\f1:\0\0\f4strvf\f1@@@STREAMS verification tool .\" .\" fileset_database@strvf.1m STREAMS-MAN ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\"Copyright Hewlett-Packard Company 1991 ...\" ...\"All Rights Reserved. Reproduction, adaptation, ...\"or translation without prior written permission ...\"is prohibited, except as allowed under the ...\"copyright laws. ...\" Copyright (c) 1988, 1990 The Regents of the University of California. ...\" All rights reserved. ...\" ...\" Redistribution and use in source and binary forms are permitted provided ...\" that: (1) source distributions retain this entire copyright notice and ...\" comment, and (2) distributions including binaries display the following ...\" acknowledgement: ``This product includes software developed by the ...\" University of California, Berkeley and its contributors'' in the ...\" documentation or other materials provided with the distribution and in ...\" all advertising materials mentioning features or use of this software. ...\" 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 ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED ...\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF ...\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. ...\" ...\" @(#)su.1 6.11 (Berkeley) 6/24/90 ...\" .rm zA .rm zZ .TH su "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lsu\*O command" ...\" .iX "Security Service commands" "\*Lsu\*O" ...\" .iX "accounts" "changing user identity" ...\" .iX "logging in" "changing user identity" .SH NAME \*Lsu\*O \- Substitutes user ID temporarily .zA "def,8628,R1.1,command platform-specific" .PP This command is platform specific. Consult your local operating system documentation for information on how to use your version of the \*Lsu\*O command. .zZ "def,8628,R1.1,command platform-specific" ...\" .SH "SYNOPSIS" ...\" .sS ...\" \*Lsu\*O ...\" \*O[\*L-K\*O] ...\" \*O[\*L-f\*O] ...\" \*O[\*L-l\*O] ...\" \*O[\*L-m\*O] ...\" \*O[\*Vlogin\*O] ...\" .sE ...\" .SH "OPTIONS" ...\" .VL 1i ...\" .LI "\*L-K\*O" ...\" Disables Kerberos authentication. ...\" .LI "\*L-f\*O" ...\" Prevents \*Lcsh(1)\*O from executing the \*L.cshrc\*O file. ...\" .LI "\*L-l\*O" ...\" Simulates a full login. The environment is discarded except for ...\" \*LHOME\*O, \*LSHELL\*O, \*LPATH\*O, \*LTERM\*O, and \*LUSER\*O. ...\" \*LHOME\*O and \*LSHELL\*O are set to the target login's login ...\" shell and home directory. The \*Lsu\*O command changes the current ...\" directory to the target login's home directory. ...\" \*LUSER\*O is set to the target login. ...\" \*LPATH\*O is set to \*L/bin:/usr/bin\*O. ...\" \*LTERM\*O is imported from your current environment. ...\" This option can not be specified with the ...\" \*L\-m\*O option. They are mutually exclusive. ...\" .LI "\*L-m\*O ...\" Leaves the environment unmodified. ...\" The invoked shell is your login shell, and no directory changes are made. ...\" As a security precaution, if the target user's shell is a nonstandard ...\" shell (as defined by \*Lgetusershell(3)\*O) and the caller's real UNIX ID is ...\" nonzero, \*Lsu\*O will fail. This option cannot be specified with the ...\" \*L\-l\*O option. They are mutually exclusive. ...\" .LE ...\" .SH "ARGUMENTS" ...\" .VL 1i ...\" .LI \*Vlogin\*O ...\" The target user ID. If \*Vlogin\*O is not specified, the root user ID is ...\" assumed. Note that only users in group 0 (normally \*Lwheel\*O) ...\" can use \*Lsu\*O to become root. ...\" .PP ...\" By default (unless the prompt is reset by a startup file), the superuser ...\" prompt is set to \*L#\*O (number sign) to remind one of its awesome power. ...\" .LE ...\" .SH "DESCRIPTION" ...\" The \*Lsu\*O command lets you assume the identity of a different user. ...\" Note that the funtionality of the \*Lsu\*O command as described in this ...\" reference page may change, depending on the platform on which you ...\" are running the command. ...\" .PP ...\" The \*Lsu\*O command ...\" requests the password for \*Vlogin\*O or, if \*Vlogin\*O is ...\" not supplied, the password for root. ...\" If the correct password is supplied, \*Lsu\*O switches to ...\" that user and group ID after obtaining a ticket-granting ticket. ...\" A shell is then invoked with the real and effective person and ...\" group UNIX IDs of the new user. If authentication is disabled or not ...\" available, \*Lsu\*O uses the local \*L/etc/passwd\*O file for authentication. ...\" .PP ...\" If the \*Lsu\*O command ...\" is executed by root, no password is requested and a shell ...\" with the appropriate user ID is invoked; no additional Kerberos tickets ...\" are obtained. ...\" .PP ...\" Unless you specify the \*L\-l\*O or \*L\-m\*O option, when \*Lsu\*O is invoked ...\" the user environment is unmodified with the exception of ...\" the following: ....\" ML ...\" .LI ...\" \*LHOME\*O and \*LSHELL\*O are set to the target login's default values. The ...\" current directory is changed to the target's login directory, and ...\" the target login's shell is invoked. ...\" .LI ...\" \*LUSER\*O is set to the target login value, unless the target login has a user ...\" ID of 0, in which case it is unmodified. The invoked shell is the target ...\" login's. This is the traditional behavior of \*Lsu\*O. ...\" .LE ...\" .SH "RELATED INFORMATION" ...\" .PP ...\" Commands: ...\" \*Lcsh(1)\*O, \*Llogin(1)\*O, \*Lsh(1)\*O, ...\" \*Lkinit(1m)\*O, \*Lkerberos(1)\*O, ...\" \*Lpasswd(5)\*O, \*Lgroup(5)\*O, \*Lenviron(7)\*O. .\" $Header: swacl.1m,v 78.2 96/05/09 12:31:10 ssa Exp $ .\" -*-Nroff-*- .\" $Header: swacl.1m,v 78.2 96/05/09 12:31:10 ssa Exp $ .\" .ds RZ \&HP CONFIDENTIAL .\" .ds RL Release B.10.0x .\" .ds MT Software Distributor B.10.0x .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro, e.g. .CR, .RI, .\" etc. A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .\" .ds PN Release B.10.0x .TA s .TH swacl 1M " " "Hewlett-Packard Company" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ds )H Software Distributor .\" .ds ]W Release B.10.0x .SH NAME swacl \- View or modify the Access Control Lists (ACLs) which protect software products .SH SYNOPSIS .C swacl .C -l .I \|level\| .\".RC [ -v ] .RC [ -M\| .IR acl_entry\| | .CR -D\| .IR acl_entry\| | .C -F\| .IR acl_file\| ] .\".IR acl_file\| | .\".CR -K ] .RC [ -x .IR option=value\| ] .br .RC [ -X\| .IR option_file\| ] .RC [ -f\| .IR software_file\| ] .RC [ -t\| .IR target_file\| ] .\".RC [ -S\| .\".IR session_file\| ] .RI [ software_selections ]\0[\c \*(at .IR \0target_selections ] .PP .SS Remarks: SD-UX commands are included with the HP-UX Operating System and manage software on the .I local host only. To install and manage software simultaneously on multiple .I remote hosts (including PCs) from a central controller, you must purchase the .B "HP OpenView Software Distributor" (HP Prod. No. B1996AA) which provides extended software management and multi-site software distribution capabilities. While most of the information in this manual page applies to both SD-UX commands and the OpenView product, some applies .B only to the OpenView product. Where this is the case, you will see: .RS .IP .IR "Applies only to HP OpenView Software Distributor" .RE .PP .SH DESCRIPTION The .C swacl command displays or modifies the Access Control Lists (ACLs) which: .RS .TP 2 \(bu Protect the specified .IR target_selections (software depots or root filesystems). .TP \(bu Protect the specified .IR software_selections on each of the specified .IR target_selections (software depots only). .RE .P All root filesystems, software depots, and products in software depots are protected by ACLs. The SD commands permit or prevent specific operations based on whether the ACLs on these objects permit the operation. The .C swacl command is used to view, edit, and manage these ACLs. The ACL must exist and the user must have the appropriate permission (granted by the ACL itself) in order to modify it. .P ACLs offer a greater degree of selectivity than standard file permissions. ACLs allow an object's owner (i.e. the user who created the object) or the local superuser to define specific read, write, or modify permissions to a specific list of users, groups, or combinations thereof. .PP .SS Protected Objects .P The following objects are protected by ACLs: .PP .RS .TP 2 \(bu Each host system on which software is being managed by SD, .TP \(bu Each root filesystem on a host (including alternate roots), .TP \(bu Each software depot on a host, .TP \(bu Each software product contained within a depot. .RE .\".PP .\".B Template ACLs .\".PP .\"To simplify ACL administration, an ACL does not need to be present on .\"every SD object in order for that object to be protected. SD provides .\"an ACL inheritance mechanism for depots, roots, and objects that have no .\"real ACL. .\".PP .\"If an object has no real ACL protecting it, SD uses a template ACL .\"defined for the depot or root in which the object is contained. .\"If this depot or root container has no template ACL, SD uses .\"the template ACL of the host system (which always exists). .\".PP .\"If a product is protected by a real ACL, it is used to determine access rights .\"to the product. The container and object ACLs are "virtual" ACLs. .PP .SS Options When none of the .CR -M , .CR -D , or .CR -F .\".CR -K options are specified, .C swacl prints the requested ACL(s) to the standard output. .P The .C swacl command supports the following options: .RS .TP 12 .\".C -v .\"Turns on verbose output to stdout. This option is .\"enabled by default. .\".TP .CI -l \0level Defines which level of SD ACLs to view/modify. The supported .I levels are: .RS .TP 8 .C "host" View/modify the ACL protecting the host system(s) identified by the .IR target_selections . .TP .C "depot" View/modify the ACL protecting the software depot(s) identified by the .IR target_selections . .TP .C "root" View/modify the ACL protecting the root filesystem(s) identified by the .IR target_selections . .TP .C "product" View/modify the ACL protecting the software product identified by he .IR software_selection . Applies only to products in depots, not installed products in roots. .TP .C "product_template" View/modify the template ACL used to initialize the ACL(s) of future product(s) added to the software depot(s) identified by the .IR target_selections . .TP .C "global_soc_template" View/modify the template ACL used to initialize the ACL(s) of future software depot(s) or root filesystem(s) added to the host(s) identified by the .IR target_selections . .TP .C "global_product_template" View/modify the template ACL used to initialize the .C product_template ACL(s) of future software depot(s) added to the host(s) identified by the .IR target_selections . .RE .PD .TP .CI -M \0acl_entry Adds a new ACL entry or changes the permissions of an existing entry. Multiple .C -M options can be specified. .TP .CI -D \0acl_entry Deletes an existing entry from the ACL associated with the specified object(s). (For this option, the permission field of the acl entry is not required.) Multiple .C -D options can be specified. .TP .CI -F \0acl_file Assigns the ACL contained in .IR acl_file to the object. All existing entries are removed and replaced by the entries in the file. Only the ACL's entries are replaced; none of the information contained in the comment portion (lines with the prefix ``#'') of an ACL listing is modified with this option. The .I acl_file is usually the edited output of a .C swacl list operation. .IP If the replacement ACL contains no syntax errors and the user has .B control permission on the ACL (or is the local super user), the replacement succeeds. .TP .CI -x \0option=value Set the session .I option to .I value and override the default value (or a value in an alternate .IR option_file specified with the .C -X option). Multiple .C -x options can be specified. .TP .CI -X \0option_file Read the session options and behaviors from .IR option_file . .TP .CI -f \0software_file Read the list of .I software_selections from .I software_file instead of (or in addition to) the command line. .TP .CI -t \0target_file Read the list of .I target_selections from .I file instead of (or in addition to) the command line. .\".TP .\".CI -S \0session_file .\"Execute .\".C swacl .\"based on the options and operands saved from a previous session, .\"as defined in .\".IR session_file . .RE .PP Only one of the .CR -M , .CR -D , or .CR -F options can be specified for an invocation of .CR swacl . (E.g. the .C -M and .C -D options cannot be specified together.) .PP .SS Operands The .C swacl command supports the following syntax for each .IR software_selection : .IP .C bundle[.product[.subproduct][.fileset]][,version] .br or .br .C product[.subproduct][.fileset][,version] .br .P The .C version component has the form: .IP .C [,r .IR .C revision][,a .IR .C arch][,v .IR .C vendor][,c .IR .C category] .P or .IP .C [instance_id] (numerical only) .P where .IR can be: ==, >=, <=, <, >, or != which performs individual comparisons on dot-separated fields. For example, r>=B.10.00 means choose all revisions that are greater than or equal to B.10.00. The system will compare each dot-separated field to find matches. Software will only be selected when matches within each field are satisfied. Wildcards are not allowed with these operators. .P The .C = (equals) relational operator is also allowed to specify a particular version component. .P All version components are repeatable within a single specification (e.g. r>=A.12, r new_acl_file" .br .C "vi new_acl_file" .br .C "swacl -l depot -F new_acl_file" .P To add an entry for user .C george on host .C newdist to the ACL protecting .C COBOL in the default depot at host .CR lehi : .IP .C "swacl -l product -M user:george\c" \*(at .C "newdist:crwit COBOL\0\c" \*(at .CR "\0lehi:" .P To deny all access to the users .C steve and .C george for the depot .C /var/spool/sw at host .CR newdist : .IP .C "swacl -l depot -M user:steve:- -M user:george:-" \*(at .CR "\0newdist:/var/spool/sw" .P To delete entries for local user .C rick from all products in the default local depot: .IP .C "swacl -l product -D user:rick \e*" .PP .SH WARNINGS .PP It is possible to edit an ACL in such a way as to render it .BR inaccessible ! Caution should be used to avoid removing all .CR control permissions on an ACL. As a safeguard against such a catastrophe, the local super-user may always edit SD ACLs. .PP .C swacl is not a general purpose ACL editor, it works only on ACLs protecting SD objects. .RS .IP .IR "The following line applies only to HP OpenView Software Distributor" .RE .PP For PC Controllers, the user and group configured to have all access may always edit SD ACLs. .P .\".PP .\".SH DEPENDENCIES .SH LIMITATIONS .PP .\" The SunOS and SD-UX versions of .C swacl do not support the viewing and modification of Access Control Lists on remote targets. .PP .RS .IP .IR "The following limitation applies only to HP OpenView Software Distributor" .RE .PPThe .C root ACLs do not apply to PC controllers. When installing to PC targets, the .C depot and .C product ACLs on the PC controller apply, since the install is enacted by first copying the PC products into the PC depot. .PP .SH FILES .PP .PP .\" .C /var/adm/sw/ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. This directory is also the default location of logfiles. .RE .\" .C /usr/lib/sw/sys.defaults .br .RS 8 Contains the master list of current SD options (with their default values). .RE .\" .C /var/adm/sw/defaults .br .RS 8 Contains the active system-wide default values for some or all SD options. .RE .\" .C $HOME/.sw/defaults .br .RS 8 Contains the user-specific default values for some or all SD options. .RE .\" .C /var/adm/sw/security/ .br .RS 8 The directory which contains ACLs for the system itself, template ACLS, and the secrets file used to authenticate remote requests. .RE .\" .C /var/adm/sw/products/ .br .RS 8 The Installed Products Database (IPD), a catalog of all products installed on a system. .RE .\" .C /var/spool/sw/ .br .RS 8 The default location of a source and target software depot. .RE .PP .SH PC FILES .PP .RS .IP .IR "The following files apply only to HP OpenView Software Distributor" .RE .PP .\" .C ...\\\\SD\\\\DATA\\\\ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. .RE .\" .C ...\\\\SD\\\\DATA\\\\DEPOT\\\\ .br .RS 8 The default location of the source and target PC depot. .RE .\" .C ...\\\\SD\\\\DATA\\\\SECURITY\\\\ .br .RS 8 The directory which contains ACLs for the system itself, template ACLS, and the secrets file used to authenticate remote requests. .RE .\" .C \\\\SWAGENTD.INI .br .RS 8 Contains the configurable options for the SD PC Controller, including the user and group granted all SD access. .RE .PP .SH AUTHOR .PP .C swacl was developed by the Hewlett-Packard Company. .PP .SH SEE ALSO .PP sd(4), sd(5), swagentd(1M), swcluster(1M), swconfig(1M), swcopy(1M), swgettools(1M), swinstall(1M), swjob(1M), swlist(1M), swmodify(1M), swpackage(1M), swpackage(4), swreg(1M), swremove(1M), swverify(1M), update(1M), and the .IR "Managing HP-UX Software with SD-UX" or .IR "HP OpenView Software Distributor Administrator's Guide" manuals. .\" index@\f4swacl\f1 \- view or modify Access Control Lists@@@\f3swacl(1M)\f1 .\" index@\f1view or modify Access Control Lists@@@\f3swacl(1M)\f1 .\" index@\f1modify or view Access Control Lists@@@\f3swacl(1M)\f1 .\" index@\f1ACL, view or modify@@@\f3swacl(1M)\f1 .\" index@\f1Access Control Lists, view or modify@@@\f3swacl(1M)\f1 .\" toc@\f3swacl(1M)\f1:\0\0\f4swacl\f1@@@view or modify Access Control Lists\f1 .\" $Header: swagentd.1m,v 78.2 96/05/09 12:31:57 ssa Exp $ .\" -*-Nroff-*- .\" $Header: swagentd.1m,v 78.2 96/05/09 12:31:57 ssa Exp $ .\" .ds RZ \&HP CONFIDENTIAL .\" .ds RL Release B.10.0x .\" .ds MT Software Distributor B.10.0x .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro, e.g. .CR, .RI, .\" etc. A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .\" .ds PN Release B.10.0x .TA s .TH swagentd 1M " " "Hewlett-Packard Company" swagent(1M) .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ds )H Software Distributor .\" .ds ]W Release B.10.0x .SH NAME swagentd \- Serve local or remote SD software management tasks, including invoking a .CR swagent command. .PP swagent \- Perform SD software management tasks as the agent of an SD command. .PP SWAGENTD.EXE \- Perform HP OpenView Software Distributor PC software management tasks, or serve local PC software for distribution. See "Remarks:" below. .PP .SH SYNOPSIS .C swagentd .RC [ -k ] .RC [ -n ] .RC [ -r ] .RC [ -x\| .IR option=value\| ] .RC [ -X\| .IR option_file\| ] .P .C SWAGENTD.EXE\| .IR "(HP OpenView Software Distributor only)" .PP .SS Remarks: SD-UX commands are included with the HP-UX Operating System and manage software on the .I local host only. To install and manage software simultaneously on multiple .I remote hosts (including PCs) from a central controller, you must purchase the .B "HP OpenView Software Distributor" (HP Prod. No. B1996AA) which provides extended software management, multi-site software distribution capabilities and distribution to PCs. While most of the information in this manual page applies to both SD-UX commands and the OpenView product, some applies .B only to the OpenView product. Where this is the case, you will see: .PP .RS .IP .IR "The following xxx applies only to HP OpenView Software Distributor" .RE .PP .SH DESCRIPTION The roles of UNIX target and source systems require two processes known as the .B daemon and .BR agent . For most purposes, the distinction between these two processes is invisible to the user and they can be viewed as a single process. .P Each SD command interacts with the daemon and agent to perform its requested tasks. .P The .C swagentd daemon process must be scheduled before a UNIX system is available as a target or source system. This can be done either manually or in the system start-up script. The .C swagent agent process is executed by .C swagentd to perform specific software management tasks. The .C swagent agent is never invoked by the user. .PP .RS .IP .IR "The following paragraph applies only to HP OpenView Software Distributor" .RE .PP The roles of PC target and source systems require a single Windows application, .CR SWAGENTD.EXE , which combines the .C swagent and .C swagentd functionality. Each PC running the .C SWAGENTD.EXE is a PC Controller. When distributing PC software, it acts as a fanout server to PC targets. (These targets run SD PC agent programs to perform the actual software installation tasks.) .PP .SS Options The .C swagentd command supports the following options to control its behavior: .RS .TP 15 .C -k The .I "kill" option stops the currently running daemon. Stopping the daemon will not stop any agent processes currently performing management tasks (such as installing or removing software), but will cause any subsequent management requests to this host to be refused. This option is equivalent to sending a SIGTERM to the daemon that is running. .TP .C -n The .I "no fork" option runs the daemon as a synchronous process rather than the default behavior of forking to run it asynchronously. This is intended for running the daemon from other utilities that schedule processes, such as .CR init . .TP .C -r The .I "restart" option stops the currently running daemon, and then restarts a new daemon. This operation is required whenever modifying default options that apply to the daemon, since defaults are only processed on startup. .TP .CI -x \0option=value Set the .I option to .I value and override the default value (or a value in an .IR option_file specified with the .C -X option). Multiple .C -x options can be specified. .TP .CI -X \0option_file Read the session options and behaviors from .IR options_file . .RE .bp .PP .SH EXTERNAL INFLUENCES .PP .SS Defaults File .PP In addition to the standard options, several .C swagentd and .C swagent behaviors and policy options can be changed by editing the default values found in: .IP .C /var/adm/sw/defaults - the system-wide default values, .IP .C $HOME/.sw/defaults - the user-specific default values. .P Values must be specified in the defaults file using this syntax: .PP .IP .CI swagentd. option = value .br .CI swagent. option = value .PP The default values for .C swagentd can be overridden by specifying an options file with the .C -X option, or by specifying .CI -x\0 option = value on the command line. .PP .B "Daemon options" .br These options apply only to the daemon, .CR swagentd . After changing daemon options, the daemon must be restarted in order for these options to be recognized (see the .C -r option). .\".PP .\".C loglevel=1 .\".IP .\"The default daemon loglevel is set to 1. .PP .RS .TP 10 .C agent=/usr/lbin/swagent The location of the agent program invoked by the daemon. .TP .C logdetail=false[true] The SD .I loglevel and .I logdetail options allow you to choose what amount of information you need in your logfiles - from no detail to complete information. The .I loglevel=0 option allows no information to be written to the logfile. This essentially turns off the logfile process. The .I logdetail=true[false] option controls the amount of detail written to the logfile. Here are the possible combinations of .I loglevel and .I logdetail options: .ifn .bp .ift .bp .nf .TS tab(@); lB| lB| lB lf4| lf4| l. Log Level@Log Detail@Information Included _ loglevel=0@@T{ No information is written to the logfile. T} _ loglevel=1@logdetail=false@T{ Only POSIX events are logged; this is the default. T} _ loglevel=1@logdetail=true@T{ POSIX detail as above plus task progress messages. Setting loglevel=1 is not necessary, it is the default. T} _ loglevel=2@logdetail=false@T{ POSIX and file level messages only. Setting the logdetail=false option is not necessary. T} _ loglevel=2@logdetail=true@T{ All information is logged. Setting both loglevel=2 and logdetail=true options is required. With this combination you may get the same logfile behavior as previous HP-UX 10.x releases. T} .fi .TE .TP .C logfile=/var/adm/sw/swagentd.log .IP This is the default log file for the .C swagentd daemon. .TP .C max_agents=-1 The maximum number of agents that are permitted to run simultaneously. The value of -1 means that there is no limit. .P .RS .IP .IR "The following option applies only to HP OpenView Software Distributor" .RE .TP 10 .C minimum_job_polling_interval=1 Defines how often, in minutes, the daemon will wake up and scan the job queue to determine if any scheduled jobs need to be initiated or if any active jobs need their remote target status cached locally (see .CR swinstall.job_polling_interval ). If set to 0, no scheduled jobs will be initiated, and no caching of active jobs will occur. .TP .C swagentd.rpc_binding_info=ncacn_ip_tcp:[2121] ncadg_ip_udp:[2121] .br This defines the protocol sequences and endpoints which may be used to contact the .CR swagentd process (the protocols and endpoints that the .C swagentd process is listening on). This value should be consistent among all hosts that work together. .TP .C swagent.rpc_binding_info_alt_source=ncadg_ip_udp:[2121] This option supports the same syntax and semantics as for the .C swagentd option (described above). This option is effecgive only when the agent attempts to contact an alternate source depot (as specified by the .C alt_source option). .RE .PP .B "Agent options" .br These options apply only to the agent, .CR swagent . .PP .RS .TP 10 .C alternate_source= If the .C swinstall or .C swcopy controller has set .CR use_alternate_source=true , the target agent will consult and use the configured value of its own .CR alternate_source option to determine the source that it will use in the install or copy. .IP The agent's value for .C alternate_source is specified using the .CR host:path syntax. If the host portion is not specified, then the local host is used. If the path portion is not specified, then the path sent by the command is used. If there is no configured value at all for .CR alternate_source , the agent will apply the controller-supplied path to its own local host. .TP .C compress_cmd=/usr/contrib/bin/gzip Defines the command called by the source agent to compress files before transmission. If the .C compression_type is set to other than .C gzip or .CR compress , this path must be changed. .TP .C compression_type=gzip Defines the default .C compression_type used by the agent when it compresses files during or after transmission. If .C uncompress_files is set to false, the .C compression_type is recorded for each file compressed so that the correct uncompression can later be applied during a .CR swinstall , or a .C swcopy with .C uncompress_files set to true. The .C compress_cmd specified must produce files with the .C compression_type specified. The .C uncompress_cmd must be able to process files of the .C compression_type specified unless the format is .CR gzip , which is uncompressed by the internal uncompressor (\c .CR funzip ). The only supported compression types are .CR compress and .CR gzip . .TP .C config_cleanup_cmd=/usr/lbin/sw/config_clean Defines the script called by the agent to perform release-specific configure cleanup steps. For and NFSD client update, this script will invoke the .C tlink command. .TP .C install_cleanup_cmd=/usr/lbin/sw/install_clean Defines the script called by the agent to perform release-specific install cleanup steps immediately after the last postinstall script has been run. For an OS update, this script should at least remove commands that were saved by the .CR install_setup script. This script is executed after all filesets have been installed, just before the reboot to the new operating system. .TP .C install_setup_cmd=/usr/lbin/sw/install_setup Defines the script called by the agent to perform release-specific install preparation. For an OS update, this script should at least copy commands needed for the checkinstall, preinstall, and postinstall scripts to a path where they can be accessed while the real commands are being updated. This script is executed before any kernel filesets are loaded. .TP .C kernel_build_cmd=/usr/sbin/mk_kernel Defines the script called by the agent for kernel building after kernel filesets have been loaded. .TP .C kernel_path=/stand/vmunix Defines the path to the system's bootable kernel. This path is passed to the .C kernel_build_cmd via the .C SW_KERNEL_PATH environment variable. .TP .C mount_cmd=/sbin/mount Defines the command called by the agent to mount all filesystems. .TP .C reboot_cmd=/sbin/reboot Defines the command called by the agent to reboot the system after all filesets have been loaded, if any of the filesets were filesets requiring reboot. .TP .C rpc_binding_info=ncadg_ip_udp:[2121] .br This defines the protocol sequence and endpoint used when the agent attempts to contact an alternate source depot (as specified by the .CR alternate_source option). See sd(5) for details on specifying this option. .TP .C remove_setup_cmd=/usr/lbin/sw/remove_setup Defines the script called by the agent to perform release-specific remove preparation. For an OS update, this script will invoke the .C tlink command when a fileset is removed. .bp .TP .C system_file_path=/stand/system Defines the path to the kernel's template file. This path is passed to the .C system_prep_cmd via the .C SW_SYSTEM_FILE_PATH environment variable. .TP .C system_prep_cmd=/usr/lbin/sysadm/system_prep Defines the kernel build preparation script called by the agent. This script must do any necessary preparation so that control scripts can correctly configure the kernel about to be built. This script is called before any kernel filesets have been loaded. .TP .C uncompress_cmd= Defines the command called by the target agent to uncompress files after transmission. This command processes files which were stored on the media in a compressed format. If the compression_type store with the file is .CR gzip then the internal uncompression (\c .CR funzip ) is used instead of the external .CR uncompress_cmd . The default value for HP-UX is undefined. .RE .\".PP .\".C use_dce_directory_service=false .\".IP .\"Should the DCE directory or naming services be used? .\".PP .\".C dce_server_register=/.:/hosts/%s/sdu .\".IP .\"The default location in the DCE namespace for the daemon to register itself. .\"The "%s" is replaced by the local hostname. This option applies only when .\"DCE naming services are available. .\".PP .\".C authentication_service=internal .\".PP .\".C protection_level=none .PP The .C swagent (target) log files cannot be relocated. They always exist relative to the root or depot target path (e.g. .C /var/adm/sw/swagent.log for the root .C / and .C /var/spool/sw/swagent.log for the depot .C /var/spool/sw ). .RS .IP .IR "The following line applies only to HP OpenView Software Distributor" .RE .PP The target log files may be viewed using the .C swjob command. .PP .SS Session File .PP The .C swagentd and .C swagent do not use a session file. .PP .SS Environment Variables .PP The .C swagent program sets these environment variables for use by the control scripts being executed on behalf of the SD commands: .PP .C LANG .IP Determines the language in which messages are displayed. If LANG is not specified or is set to the empty string, a default value of .C C is used. See .C lang(5) for more information. .IP NOTE: The language in which the SD agent and daemon log messages are displayed is set by the system configuration variable script, .CR /etc/rc.config.d/LANG . For example, .CR /etc/rc.config.d/LANG , must be set to .CR LANG=ja_JP.SJIS or .CR LANG=ja_JP.eucJP to make the agent and daemon log messages display in Japanese. .PP .C SW_PATH .IP A PATH variable which defines a minimum set of commands available to for use in a control script (e.g. .CR /bin:/usr/bin ). .PP .C SW_ROOT_DIRECTORY .IP Defines the root directory in which the session is operating, either "/" or an alternate root directory. This variable tells control scripts the root directory in which the products are installed. A script must use this directory as a prefix to SW_LOCATION to locate the product's installed files. .PP .C SW_LOCATION .IP Defines the location of the product, which may have been changed from the default product directory. When combined with the .CR SW_ROOT_DIRECTORY , this variable tells scripts where the product files are located. .PP .C SW_SOFTWARE_SPEC .IP This variable contains the fully qualified software specification of the current product or fileset. The software specification allows the product or fileset to be uniquely identified. .PP .C SW_CONTROL_DIRECTORY .IP Defines the current directory of the script being executed, either a temporary catalog directory, or a directory within in the Installed Products Database (IPD). This variable tells scripts where other control scripts for the software are located (e.g. subscripts). .PP .C SW_INITIAL_INSTALL .IP This variable is normally unset. If it is set, the .C swinstall session is being run as the back end of an initial system software installation ("cold" install). .PP .C SW_DEFERRED_KERNBLD .IP This variable is normally unset. If it is set, the actions necessary for preparing the system file .CR /stand/system cannot be accomplished from within the .IR postinstall scripts, but instead must be accomplished by the .IR configure scripts . This occurs whenever software is installed to a directory other than .IR / , such as for a cluster client system. This variable should be read only by the .IR configure and .IR postinstall scripts of a kernel fileset. The .CR swinstall command sets these environment variables for use by the kernel preparation and build scripts. .PP .C SW_KERNEL_PATH .IP The path to the kernel. The default value is .CR /stand/vmunix , defined by the .CR swagent option or .CR kernel_path . .PP .C SW_SYSTEM_FILE_PATH .IP The path to the kernel's system file. The default value is .CR /stand/system . .PP .SS Signals .PP The daemon ignores SIGHUP, SIGINT and SIGQUIT. It immediately exits gracefully after receiving SIGTERM and SIGUSR2. After receiving SIGUSR1, it waits for completion of a copy or remove from a depot session before exiting, so that it can register or unregister depots. Requests to start new sessions are refused during this wait. .P The agent ignores SIGHUP, SIGINT, and SIGQUIT. It immediately exits gracefully after receiving SIGTERM, SIGUSR1, or SIGUSR2. Killing the agent may leave corrupt software on the system, and thus should only be done if absolutely necessary. Note that when an SD command is killed, the agent does not terminate until completing the task in progress. .\"You should let the agent complete a test execution before killing it to avoid .\"leaving corrupt software on the system. .PP .SS Locking .PP The .C swagentd ensures that only one copy of itself is running on the system. .PP Each copy of .C swagent that is invoked uses appropriate access control for the operation it is performing and the object it is operating on. .PP .RS .IP .IR "The following section on the Initialization File applies only to HP OpenView Software Distributor" .RE .PP .SS Windows Initialization File .PP The .C SWAGENTD.EXE supports the following configuration values in the file: .IP .C \\\\SWAGENTD.INI - the initialization file for the PC Controller. .P Values must be specified in the initialization file using this syntax: .PP .IP .CI [ section ] .br .IC keyword = value .PP (These values are usually modified using the .CR SWAGENTD.EXE 's Configure dialog.) .PP .B "Environment Section" .br These keywords are defined in the .C Environment section of the initialization file. .PP .RS .TP 10 .C DataDirectory=...\\\\sd\\\\data The data directory set at installation, which contains the PC depot and other PC Controller data files. .TP .C ViewCommand=sdview.exe The command used to display the PC Controller logfile when the View Log... menu item is selected. .RE .P Note that .C SWAGENTD.EXE does not allow the configuration of the .C rpc_binding_info option, as described for .C swagentd and .C swagent above. To allow correct execution on a variety of TCP/IP stacks, the .C SWAGENTD.EXE always uses the value .CR ncacn_ip_tcp:[2121] . .PP .B "Security Section" .br These keywords are defined in the .C Security section of the initialization file. .PP .RS .TP 10 .C user=root The UNIX user at the specified UNIX host (below) who is granted all SD access permissions to the PC Controller. (I.e. This remote user has permission to perform any SD action at this PC Controller.) .TP .C group=swadm The UNIX group at the specified UNIX host (below) which is granted all SD access permissions to the PC Controller. (I.e. This remote group has permission to perform any SD action at this PC Controller.) .TP .CI hostname= hostname The UNIX host from which the specified user and group (above) is granted all SD access permissions. .TP .C secret=-sdu- The secret password used in SD's internal form of authentication. (The .C -sdu- default value matches the default value defined for the SD commands.) .RE .PP .SH RETURN VALUES .PP When the .C -n option is not specified, the .C swagentd returns: .RS .TP 4 .C 0 The daemon is successfully initialized and is now running in the background. .PD 0 .TP .C non-zero Initialization failed and the daemon terminated. .PD .RE When the .C -n option is specified, the .C swagentd returns: .RS .TP 4 .C 0 The daemon successfully initialized and then successfully shutdown. .PD 0 .TP .C non-zero Initialization failed or the daemon unsuccessfully terminated. .PD .RE .PP .SH DIAGNOSTICS .PP The .C swagentd and .C swagent commands log events to their specific logfiles. .PP .TP Daemon Log .br The daemon logs all events to .IR /var/adm/sw/swagentd.log . (The user can specify a different logfile by modifying the .C logfile option.) .TP Agent Log .br When operating on (alternate) root filesystems, the .C swagent logs messages to the file .I var/adm/sw/swagent.log beneath the root directory (e.g. .C / or an alternate root directory). .sp When operating on software depots, the .C swagent logs messages to the file .I swagent.log beneath the depot directory (e.g. .IR /var/spool/sw ). When accessing a read-only software depot (e.g. as a source), the .C swagent logs messages to the file .IR /tmp/swagent.log . .PP .SH EXAMPLES .PP To start the daemon: .IP .C "/usr/sbin/swagentd" .\".SH WARNINGS .\".PP .\".PP .\".SH DEPENDENCIES .\".PP .\".PP .\" Moved to Description above! .\".SH LIMITATIONS .\".PP .\"The .\".C swagentd .\"and .\".C swagent .\"programs do not apply to PC controllers. .\"Similar functionality is provided by the .\".C SWAGENTD.EXE .\"program that runs on the PC controller. .SH FILES .PP .\" .C /var/adm/sw/ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. This directory is also the default location of logfiles. .RE .\" .C /var/adm/sw/host_object .br .RS 8 The file which stores the list of depots registered at the local host. .RE .\" .C /usr/lib/sw/sys.defaults .br .RS 8 Contains the master list of current SD options (with their default values). .RE .\" .C /var/adm/sw/defaults .br .RS 8 Contains the active system-wide default values for some or all SD options. .RE .\" .C $HOME/.sw/defaults .br .RS 8 Contains the user-specific default values for some or all SD options. .RE .RS .IP .IR "The following on PC files applies only to HP OpenView Software Distributor" .RE .PP .SH PC FILES .PP .\" .C ...\\\\SD\\\\DATA\\\\ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. .RE .\" .C \\\\SWAGENTD.INI .br .RS 8 Contains the configurable options for the SD PC Controller. .RE .PP .SH AUTHOR .PP .C swagentd and .C swagent were developed by the Hewlett-Packard Company. .PP .SH SEE ALSO .PP sd(4), sd(5), swacl(1M), swcluster(1M), swconfig(1M), swcopy(1M), swgettools(1M), swinstall(1M), swjob(1M), swlist(1M), swmodify(1M), swpackage(1M), swpackage(4), swreg(1M), swremove(1M), swverify(1M), update(1M), and the .IR "HP OpenView Software Distributor Administrator's Guide" or .IR "Managing HP-UX Software with SD-UX" manuals. .\" .\" index@\f4swagentd\f1 \- serve local or remote software management tasks@@@\f3swagentd(1M)\f1 .\" index@\f4swagent\f1 \- perform software management tasks as the agent of an SD command@@@\f3swagentd(1M)\f1 .\" toc@\f3swagentd(1M)\f1:\0\0\f4swagentd\f1, \f4swagent\f1@@@serve local or remote SD-UX software management tasks .\" toc@\f4swagent\f1:\0\0perform software management tasks as the agent of an SD command@@@\f1see \f3swagentd(1M)\f1 .\" .\" links@swagentd.1m swagent.1m .\" $Header: swagentd.1m,v 78.2 96/05/09 12:31:57 ssa Exp $ .\" -*-Nroff-*- .\" $Header: swagentd.1m,v 78.2 96/05/09 12:31:57 ssa Exp $ .\" .ds RZ \&HP CONFIDENTIAL .\" .ds RL Release B.10.0x .\" .ds MT Software Distributor B.10.0x .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro, e.g. .CR, .RI, .\" etc. A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .\" .ds PN Release B.10.0x .TA s .TH swagentd 1M " " "Hewlett-Packard Company" swagent(1M) .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ds )H Software Distributor .\" .ds ]W Release B.10.0x .SH NAME swagentd \- Serve local or remote SD software management tasks, including invoking a .CR swagent command. .PP swagent \- Perform SD software management tasks as the agent of an SD command. .PP SWAGENTD.EXE \- Perform HP OpenView Software Distributor PC software management tasks, or serve local PC software for distribution. See "Remarks:" below. .PP .SH SYNOPSIS .C swagentd .RC [ -k ] .RC [ -n ] .RC [ -r ] .RC [ -x\| .IR option=value\| ] .RC [ -X\| .IR option_file\| ] .P .C SWAGENTD.EXE\| .IR "(HP OpenView Software Distributor only)" .PP .SS Remarks: SD-UX commands are included with the HP-UX Operating System and manage software on the .I local host only. To install and manage software simultaneously on multiple .I remote hosts (including PCs) from a central controller, you must purchase the .B "HP OpenView Software Distributor" (HP Prod. No. B1996AA) which provides extended software management, multi-site software distribution capabilities and distribution to PCs. While most of the information in this manual page applies to both SD-UX commands and the OpenView product, some applies .B only to the OpenView product. Where this is the case, you will see: .PP .RS .IP .IR "The following xxx applies only to HP OpenView Software Distributor" .RE .PP .SH DESCRIPTION The roles of UNIX target and source systems require two processes known as the .B daemon and .BR agent . For most purposes, the distinction between these two processes is invisible to the user and they can be viewed as a single process. .P Each SD command interacts with the daemon and agent to perform its requested tasks. .P The .C swagentd daemon process must be scheduled before a UNIX system is available as a target or source system. This can be done either manually or in the system start-up script. The .C swagent agent process is executed by .C swagentd to perform specific software management tasks. The .C swagent agent is never invoked by the user. .PP .RS .IP .IR "The following paragraph applies only to HP OpenView Software Distributor" .RE .PP The roles of PC target and source systems require a single Windows application, .CR SWAGENTD.EXE , which combines the .C swagent and .C swagentd functionality. Each PC running the .C SWAGENTD.EXE is a PC Controller. When distributing PC software, it acts as a fanout server to PC targets. (These targets run SD PC agent programs to perform the actual software installation tasks.) .PP .SS Options The .C swagentd command supports the following options to control its behavior: .RS .TP 15 .C -k The .I "kill" option stops the currently running daemon. Stopping the daemon will not stop any agent processes currently performing management tasks (such as installing or removing software), but will cause any subsequent management requests to this host to be refused. This option is equivalent to sending a SIGTERM to the daemon that is running. .TP .C -n The .I "no fork" option runs the daemon as a synchronous process rather than the default behavior of forking to run it asynchronously. This is intended for running the daemon from other utilities that schedule processes, such as .CR init . .TP .C -r The .I "restart" option stops the currently running daemon, and then restarts a new daemon. This operation is required whenever modifying default options that apply to the daemon, since defaults are only processed on startup. .TP .CI -x \0option=value Set the .I option to .I value and override the default value (or a value in an .IR option_file specified with the .C -X option). Multiple .C -x options can be specified. .TP .CI -X \0option_file Read the session options and behaviors from .IR options_file . .RE .bp .PP .SH EXTERNAL INFLUENCES .PP .SS Defaults File .PP In addition to the standard options, several .C swagentd and .C swagent behaviors and policy options can be changed by editing the default values found in: .IP .C /var/adm/sw/defaults - the system-wide default values, .IP .C $HOME/.sw/defaults - the user-specific default values. .P Values must be specified in the defaults file using this syntax: .PP .IP .CI swagentd. option = value .br .CI swagent. option = value .PP The default values for .C swagentd can be overridden by specifying an options file with the .C -X option, or by specifying .CI -x\0 option = value on the command line. .PP .B "Daemon options" .br These options apply only to the daemon, .CR swagentd . After changing daemon options, the daemon must be restarted in order for these options to be recognized (see the .C -r option). .\".PP .\".C loglevel=1 .\".IP .\"The default daemon loglevel is set to 1. .PP .RS .TP 10 .C agent=/usr/lbin/swagent The location of the agent program invoked by the daemon. .TP .C logdetail=false[true] The SD .I loglevel and .I logdetail options allow you to choose what amount of information you need in your logfiles - from no detail to complete information. The .I loglevel=0 option allows no information to be written to the logfile. This essentially turns off the logfile process. The .I logdetail=true[false] option controls the amount of detail written to the logfile. Here are the possible combinations of .I loglevel and .I logdetail options: .ifn .bp .ift .bp .nf .TS tab(@); lB| lB| lB lf4| lf4| l. Log Level@Log Detail@Information Included _ loglevel=0@@T{ No information is written to the logfile. T} _ loglevel=1@logdetail=false@T{ Only POSIX events are logged; this is the default. T} _ loglevel=1@logdetail=true@T{ POSIX detail as above plus task progress messages. Setting loglevel=1 is not necessary, it is the default. T} _ loglevel=2@logdetail=false@T{ POSIX and file level messages only. Setting the logdetail=false option is not necessary. T} _ loglevel=2@logdetail=true@T{ All information is logged. Setting both loglevel=2 and logdetail=true options is required. With this combination you may get the same logfile behavior as previous HP-UX 10.x releases. T} .fi .TE .TP .C logfile=/var/adm/sw/swagentd.log .IP This is the default log file for the .C swagentd daemon. .TP .C max_agents=-1 The maximum number of agents that are permitted to run simultaneously. The value of -1 means that there is no limit. .P .RS .IP .IR "The following option applies only to HP OpenView Software Distributor" .RE .TP 10 .C minimum_job_polling_interval=1 Defines how often, in minutes, the daemon will wake up and scan the job queue to determine if any scheduled jobs need to be initiated or if any active jobs need their remote target status cached locally (see .CR swinstall.job_polling_interval ). If set to 0, no scheduled jobs will be initiated, and no caching of active jobs will occur. .TP .C swagentd.rpc_binding_info=ncacn_ip_tcp:[2121] ncadg_ip_udp:[2121] .br This defines the protocol sequences and endpoints which may be used to contact the .CR swagentd process (the protocols and endpoints that the .C swagentd process is listening on). This value should be consistent among all hosts that work together. .TP .C swagent.rpc_binding_info_alt_source=ncadg_ip_udp:[2121] This option supports the same syntax and semantics as for the .C swagentd option (described above). This option is effecgive only when the agent attempts to contact an alternate source depot (as specified by the .C alt_source option). .RE .PP .B "Agent options" .br These options apply only to the agent, .CR swagent . .PP .RS .TP 10 .C alternate_source= If the .C swinstall or .C swcopy controller has set .CR use_alternate_source=true , the target agent will consult and use the configured value of its own .CR alternate_source option to determine the source that it will use in the install or copy. .IP The agent's value for .C alternate_source is specified using the .CR host:path syntax. If the host portion is not specified, then the local host is used. If the path portion is not specified, then the path sent by the command is used. If there is no configured value at all for .CR alternate_source , the agent will apply the controller-supplied path to its own local host. .TP .C compress_cmd=/usr/contrib/bin/gzip Defines the command called by the source agent to compress files before transmission. If the .C compression_type is set to other than .C gzip or .CR compress , this path must be changed. .TP .C compression_type=gzip Defines the default .C compression_type used by the agent when it compresses files during or after transmission. If .C uncompress_files is set to false, the .C compression_type is recorded for each file compressed so that the correct uncompression can later be applied during a .CR swinstall , or a .C swcopy with .C uncompress_files set to true. The .C compress_cmd specified must produce files with the .C compression_type specified. The .C uncompress_cmd must be able to process files of the .C compression_type specified unless the format is .CR gzip , which is uncompressed by the internal uncompressor (\c .CR funzip ). The only supported compression types are .CR compress and .CR gzip . .TP .C config_cleanup_cmd=/usr/lbin/sw/config_clean Defines the script called by the agent to perform release-specific configure cleanup steps. For and NFSD client update, this script will invoke the .C tlink command. .TP .C install_cleanup_cmd=/usr/lbin/sw/install_clean Defines the script called by the agent to perform release-specific install cleanup steps immediately after the last postinstall script has been run. For an OS update, this script should at least remove commands that were saved by the .CR install_setup script. This script is executed after all filesets have been installed, just before the reboot to the new operating system. .TP .C install_setup_cmd=/usr/lbin/sw/install_setup Defines the script called by the agent to perform release-specific install preparation. For an OS update, this script should at least copy commands needed for the checkinstall, preinstall, and postinstall scripts to a path where they can be accessed while the real commands are being updated. This script is executed before any kernel filesets are loaded. .TP .C kernel_build_cmd=/usr/sbin/mk_kernel Defines the script called by the agent for kernel building after kernel filesets have been loaded. .TP .C kernel_path=/stand/vmunix Defines the path to the system's bootable kernel. This path is passed to the .C kernel_build_cmd via the .C SW_KERNEL_PATH environment variable. .TP .C mount_cmd=/sbin/mount Defines the command called by the agent to mount all filesystems. .TP .C reboot_cmd=/sbin/reboot Defines the command called by the agent to reboot the system after all filesets have been loaded, if any of the filesets were filesets requiring reboot. .TP .C rpc_binding_info=ncadg_ip_udp:[2121] .br This defines the protocol sequence and endpoint used when the agent attempts to contact an alternate source depot (as specified by the .CR alternate_source option). See sd(5) for details on specifying this option. .TP .C remove_setup_cmd=/usr/lbin/sw/remove_setup Defines the script called by the agent to perform release-specific remove preparation. For an OS update, this script will invoke the .C tlink command when a fileset is removed. .bp .TP .C system_file_path=/stand/system Defines the path to the kernel's template file. This path is passed to the .C system_prep_cmd via the .C SW_SYSTEM_FILE_PATH environment variable. .TP .C system_prep_cmd=/usr/lbin/sysadm/system_prep Defines the kernel build preparation script called by the agent. This script must do any necessary preparation so that control scripts can correctly configure the kernel about to be built. This script is called before any kernel filesets have been loaded. .TP .C uncompress_cmd= Defines the command called by the target agent to uncompress files after transmission. This command processes files which were stored on the media in a compressed format. If the compression_type store with the file is .CR gzip then the internal uncompression (\c .CR funzip ) is used instead of the external .CR uncompress_cmd . The default value for HP-UX is undefined. .RE .\".PP .\".C use_dce_directory_service=false .\".IP .\"Should the DCE directory or naming services be used? .\".PP .\".C dce_server_register=/.:/hosts/%s/sdu .\".IP .\"The default location in the DCE namespace for the daemon to register itself. .\"The "%s" is replaced by the local hostname. This option applies only when .\"DCE naming services are available. .\".PP .\".C authentication_service=internal .\".PP .\".C protection_level=none .PP The .C swagent (target) log files cannot be relocated. They always exist relative to the root or depot target path (e.g. .C /var/adm/sw/swagent.log for the root .C / and .C /var/spool/sw/swagent.log for the depot .C /var/spool/sw ). .RS .IP .IR "The following line applies only to HP OpenView Software Distributor" .RE .PP The target log files may be viewed using the .C swjob command. .PP .SS Session File .PP The .C swagentd and .C swagent do not use a session file. .PP .SS Environment Variables .PP The .C swagent program sets these environment variables for use by the control scripts being executed on behalf of the SD commands: .PP .C LANG .IP Determines the language in which messages are displayed. If LANG is not specified or is set to the empty string, a default value of .C C is used. See .C lang(5) for more information. .IP NOTE: The language in which the SD agent and daemon log messages are displayed is set by the system configuration variable script, .CR /etc/rc.config.d/LANG . For example, .CR /etc/rc.config.d/LANG , must be set to .CR LANG=ja_JP.SJIS or .CR LANG=ja_JP.eucJP to make the agent and daemon log messages display in Japanese. .PP .C SW_PATH .IP A PATH variable which defines a minimum set of commands available to for use in a control script (e.g. .CR /bin:/usr/bin ). .PP .C SW_ROOT_DIRECTORY .IP Defines the root directory in which the session is operating, either "/" or an alternate root directory. This variable tells control scripts the root directory in which the products are installed. A script must use this directory as a prefix to SW_LOCATION to locate the product's installed files. .PP .C SW_LOCATION .IP Defines the location of the product, which may have been changed from the default product directory. When combined with the .CR SW_ROOT_DIRECTORY , this variable tells scripts where the product files are located. .PP .C SW_SOFTWARE_SPEC .IP This variable contains the fully qualified software specification of the current product or fileset. The software specification allows the product or fileset to be uniquely identified. .PP .C SW_CONTROL_DIRECTORY .IP Defines the current directory of the script being executed, either a temporary catalog directory, or a directory within in the Installed Products Database (IPD). This variable tells scripts where other control scripts for the software are located (e.g. subscripts). .PP .C SW_INITIAL_INSTALL .IP This variable is normally unset. If it is set, the .C swinstall session is being run as the back end of an initial system software installation ("cold" install). .PP .C SW_DEFERRED_KERNBLD .IP This variable is normally unset. If it is set, the actions necessary for preparing the system file .CR /stand/system cannot be accomplished from within the .IR postinstall scripts, but instead must be accomplished by the .IR configure scripts . This occurs whenever software is installed to a directory other than .IR / , such as for a cluster client system. This variable should be read only by the .IR configure and .IR postinstall scripts of a kernel fileset. The .CR swinstall command sets these environment variables for use by the kernel preparation and build scripts. .PP .C SW_KERNEL_PATH .IP The path to the kernel. The default value is .CR /stand/vmunix , defined by the .CR swagent option or .CR kernel_path . .PP .C SW_SYSTEM_FILE_PATH .IP The path to the kernel's system file. The default value is .CR /stand/system . .PP .SS Signals .PP The daemon ignores SIGHUP, SIGINT and SIGQUIT. It immediately exits gracefully after receiving SIGTERM and SIGUSR2. After receiving SIGUSR1, it waits for completion of a copy or remove from a depot session before exiting, so that it can register or unregister depots. Requests to start new sessions are refused during this wait. .P The agent ignores SIGHUP, SIGINT, and SIGQUIT. It immediately exits gracefully after receiving SIGTERM, SIGUSR1, or SIGUSR2. Killing the agent may leave corrupt software on the system, and thus should only be done if absolutely necessary. Note that when an SD command is killed, the agent does not terminate until completing the task in progress. .\"You should let the agent complete a test execution before killing it to avoid .\"leaving corrupt software on the system. .PP .SS Locking .PP The .C swagentd ensures that only one copy of itself is running on the system. .PP Each copy of .C swagent that is invoked uses appropriate access control for the operation it is performing and the object it is operating on. .PP .RS .IP .IR "The following section on the Initialization File applies only to HP OpenView Software Distributor" .RE .PP .SS Windows Initialization File .PP The .C SWAGENTD.EXE supports the following configuration values in the file: .IP .C \\\\SWAGENTD.INI - the initialization file for the PC Controller. .P Values must be specified in the initialization file using this syntax: .PP .IP .CI [ section ] .br .IC keyword = value .PP (These values are usually modified using the .CR SWAGENTD.EXE 's Configure dialog.) .PP .B "Environment Section" .br These keywords are defined in the .C Environment section of the initialization file. .PP .RS .TP 10 .C DataDirectory=...\\\\sd\\\\data The data directory set at installation, which contains the PC depot and other PC Controller data files. .TP .C ViewCommand=sdview.exe The command used to display the PC Controller logfile when the View Log... menu item is selected. .RE .P Note that .C SWAGENTD.EXE does not allow the configuration of the .C rpc_binding_info option, as described for .C swagentd and .C swagent above. To allow correct execution on a variety of TCP/IP stacks, the .C SWAGENTD.EXE always uses the value .CR ncacn_ip_tcp:[2121] . .PP .B "Security Section" .br These keywords are defined in the .C Security section of the initialization file. .PP .RS .TP 10 .C user=root The UNIX user at the specified UNIX host (below) who is granted all SD access permissions to the PC Controller. (I.e. This remote user has permission to perform any SD action at this PC Controller.) .TP .C group=swadm The UNIX group at the specified UNIX host (below) which is granted all SD access permissions to the PC Controller. (I.e. This remote group has permission to perform any SD action at this PC Controller.) .TP .CI hostname= hostname The UNIX host from which the specified user and group (above) is granted all SD access permissions. .TP .C secret=-sdu- The secret password used in SD's internal form of authentication. (The .C -sdu- default value matches the default value defined for the SD commands.) .RE .PP .SH RETURN VALUES .PP When the .C -n option is not specified, the .C swagentd returns: .RS .TP 4 .C 0 The daemon is successfully initialized and is now running in the background. .PD 0 .TP .C non-zero Initialization failed and the daemon terminated. .PD .RE When the .C -n option is specified, the .C swagentd returns: .RS .TP 4 .C 0 The daemon successfully initialized and then successfully shutdown. .PD 0 .TP .C non-zero Initialization failed or the daemon unsuccessfully terminated. .PD .RE .PP .SH DIAGNOSTICS .PP The .C swagentd and .C swagent commands log events to their specific logfiles. .PP .TP Daemon Log .br The daemon logs all events to .IR /var/adm/sw/swagentd.log . (The user can specify a different logfile by modifying the .C logfile option.) .TP Agent Log .br When operating on (alternate) root filesystems, the .C swagent logs messages to the file .I var/adm/sw/swagent.log beneath the root directory (e.g. .C / or an alternate root directory). .sp When operating on software depots, the .C swagent logs messages to the file .I swagent.log beneath the depot directory (e.g. .IR /var/spool/sw ). When accessing a read-only software depot (e.g. as a source), the .C swagent logs messages to the file .IR /tmp/swagent.log . .PP .SH EXAMPLES .PP To start the daemon: .IP .C "/usr/sbin/swagentd" .\".SH WARNINGS .\".PP .\".PP .\".SH DEPENDENCIES .\".PP .\".PP .\" Moved to Description above! .\".SH LIMITATIONS .\".PP .\"The .\".C swagentd .\"and .\".C swagent .\"programs do not apply to PC controllers. .\"Similar functionality is provided by the .\".C SWAGENTD.EXE .\"program that runs on the PC controller. .SH FILES .PP .\" .C /var/adm/sw/ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. This directory is also the default location of logfiles. .RE .\" .C /var/adm/sw/host_object .br .RS 8 The file which stores the list of depots registered at the local host. .RE .\" .C /usr/lib/sw/sys.defaults .br .RS 8 Contains the master list of current SD options (with their default values). .RE .\" .C /var/adm/sw/defaults .br .RS 8 Contains the active system-wide default values for some or all SD options. .RE .\" .C $HOME/.sw/defaults .br .RS 8 Contains the user-specific default values for some or all SD options. .RE .RS .IP .IR "The following on PC files applies only to HP OpenView Software Distributor" .RE .PP .SH PC FILES .PP .\" .C ...\\\\SD\\\\DATA\\\\ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. .RE .\" .C \\\\SWAGENTD.INI .br .RS 8 Contains the configurable options for the SD PC Controller. .RE .PP .SH AUTHOR .PP .C swagentd and .C swagent were developed by the Hewlett-Packard Company. .PP .SH SEE ALSO .PP sd(4), sd(5), swacl(1M), swcluster(1M), swconfig(1M), swcopy(1M), swgettools(1M), swinstall(1M), swjob(1M), swlist(1M), swmodify(1M), swpackage(1M), swpackage(4), swreg(1M), swremove(1M), swverify(1M), update(1M), and the .IR "HP OpenView Software Distributor Administrator's Guide" or .IR "Managing HP-UX Software with SD-UX" manuals. .\" .\" index@\f4swagentd\f1 \- serve local or remote software management tasks@@@\f3swagentd(1M)\f1 .\" index@\f4swagent\f1 \- perform software management tasks as the agent of an SD command@@@\f3swagentd(1M)\f1 .\" toc@\f3swagentd(1M)\f1:\0\0\f4swagentd\f1, \f4swagent\f1@@@serve local or remote SD-UX software management tasks .\" toc@\f4swagent\f1:\0\0perform software management tasks as the agent of an SD command@@@\f1see \f3swagentd(1M)\f1 .\" .\" links@swagentd.1m swagent.1m .\" $Header: swapinfo.1m,v 76.1 95/08/07 11:45:13 ssa Exp $ .TA s .TH swapinfo 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME swapinfo \- system paging space information .SH SYNOPSIS .C /usr/sbin/swapinfo .RC [ -mtadfnrMqw ] .SH DESCRIPTION .C swapinfo prints information about device and file system paging space. (Note: the term `swap' refers to an obsolete implementation of virtual memory; .SM HP-UX actually implements virtual memory by way of paging rather than swapping. This command and others retain names derived from `swap' for historical reasons.) .P By default, .C swapinfo prints to standard output a two line header as shown here, followed by one line per paging area: .nf .IP .C " Kb Kb Kb PCT START/ Kb" .C "TYPE AVAIL USED FREE USED LIMIT RESERVE PRI NAME" .fi .PP The fields are: .TP 12 .C TYPE One of: .RS .TP 11 .C dev Paging space residing on a mass storage device, either taking up the entire device or, if the device contains a file system, taking up the space between the end of the file system and the end of the device. This space is exclusively reserved for paging, and even if it is not being used for paging, it cannot be used for any other purpose. Device paging areas typically provide the fastest paging. .TP .C fs Dynamic paging space available from a file system. When this space is needed, the system creates files in the file system and uses them as paging space. File system paging is typically slower than device paging, but allows the space to be used for other things (user files) when not needed for paging. .TP .C localfs File system paging space (see .C fs above) on a file system residing on a local disk. .TP .C network File system paging space (see .C fs above) on a file system residing on another machine. This file system would have been mounted on the local machine via .SM NFS. .TP .C reserve Paging space on reserve. This is the amount of paging space that could be needed by processes that are currently running, but that has not yet been allocated from one of the above paging areas. See "Paging Allocation" below. .TP .C memory Memory paging area (also known as pseudo-swap). This is the amount of system memory that can be used to hold pages in the event that all of the above paging areas are used up. See "Paging Allocation" below. This line appears only if memory paging is enabled. .RE .TP .C Kb AVAIL The total available space from the paging area, in blocks of 1024 bytes (rounded to nearest whole block if necessary), including any paging space already in use. .IP For file system paging areas the value is not necessarily constant. It is the current space allocated for paging (even if not currently used), plus the free blocks available on the file system to ordinary users, minus RESERVE (but never less than zero). AVAIL is never more than LIMIT if LIMIT is non-zero. Since paging space is allocated in large chunks, AVAIL is rounded down to the nearest full allocation chunk. .IP For the memory paging area this value is also not necessarily constant, because it reflects allocation of memory by the kernel as well as by processes that might need to be paged. .TP .C Kb USED The current number of 1-Kbyte blocks used for paging in the paging area. For the memory paging area, this count also includes memory used for other purposes and thus unavailable for paging. .TP .C Kb FREE The amount of space that can be used for future paging. Usually this is the difference between Kb AVAIL and Kb USED. There could be a difference if some portion of a device paging area is unusable, perhaps because the size of the paging area is not a multiple of the allocation chunk size, or because the tunable parameter .C maxswapchunks is not set high enough. .TP .C PCT USED The percentage of capacity in use, based on Kb USED divided by Kb AVAIL; 100% if Kb AVAIL is zero. .TP .C START/LIMIT For device paging areas, START is the block address on the mass storage device of the start of the paging area. The value is normally 0 for devices dedicated to paging, or the end of the file system for devices containing both a file system and paging space. .IP For file system paging areas, LIMIT is the maximum number of 1-Kbyte blocks that will be used for paging, the same as the .I limit value given to .CR swapon . A file system LIMIT value of .C none means there is no fixed limit; all space is available except that used for files, less the blocks represented by .C minfree (see .IR fs (4)) plus RESERVE. .TP .C RESERVE For device paging areas, this value is always ``\(em''. For file system paging areas, this value is the number of 1-Kbyte blocks reserved for file system use by ordinary users, the same as the .I reserve value given to .CR swapon . .TP .C PRI The same as the .I priority value given to .CR swapon . This value indicates the order in which space is taken from the devices and file systems used for paging. Space is taken from areas with lower priority values first. .I priority can have a value between 0 and 10. See "Paging Allocation" below. .TP .C NAME For device paging areas, the block special file name whose major and minor numbers match the device's ID. The .C swapinfo command searches the .C /dev tree to find device names. If no matching block special file is found, .C swapinfo prints the device ID (major and minor values), for example, .CR 28,0x15000 . .IP For file system swap areas, NAME is the name of a directory on the file system in which the paging files are stored. .SS Paging Allocation Paging areas are enabled at boot time (for device paging areas configured into the kernel) or by the .C swapon command (see .IR swapon (1M)), often invoked by .C /sbin/init.d/swap_start during system initialization based on the contents of .CR /etc/fstab . When a paging area is enabled, some portion of that area is allocated for paging space. For device paging areas, the entire device is allocated, less any leftover fraction of an allocation chunk. (The size of an allocation chunk is controlled by the tunable parameter .CR swchunk , and is typically 2 MB.) For file system paging areas, the .I minimum value given to .C swapon (rounded up to the nearest allocation chunk) is allocated. .P When a process is created, or requests additional space, space is reserved for it by increasing the space shown on the .C reserve line above. When paging activity actually occurs, space is used in one of the paging areas (the one with the lowest priority number that has free space available, already allocated), and that space will be shown as used in that area. .P The sum of the space used in all of the paging areas, plus the amount of space reserved, can never exceed the total amount allocated in all of the paging areas. If a request for more memory occurs which would cause this to happen, the system tries several options: .TP 5 1. The system tries to increase the total space available by allocating more space in file system paging areas. .TP 2. If all file system paging areas are completely allocated and the request is still not satisfied, the system will try to use memory paging as described on the .C memory line above. (Memory paging is controlled by the tunable parameter .CR swapmem_on , which defaults to 1 (on). If this parameter is turned off, the .C memory line will not appear.) .TP 3. If memory paging also cannot satisfy the request, because it is full or turned off, the request is denied. .PP Several implications of this procedure are noteworthy for understanding the output of .CR swapinfo : .TP \(bu Paging space will not be allocated in a file system paging area (except for the .I minimum specified when the area is first enabled) until all device paging space has been reserved, even if the file system paging area has a lower priority value. .TP \(bu When paging space is allocated to a file system paging area, that space becomes unavailable for user files, even if there is no paging activity to it. .TP \(bu Requests for more paging space will fail when they cannot be satisfied by reserving device, file system, or memory paging, even if some of the reserved paging space is not yet in use. Thus it is possible for requests for more paging space to be denied when some, or even all, of the paging areas show zero usage \(em space in those areas is completely reserved. .TP \(bu System available memory is shared between the paging subsystem and kernel memory allocators. Thus, the system may show memory paging usage before all available disk paging space is completely reserved or fully allocated. .SS Options .C swapinfo recognizes the following options: .RS .TP .B \-m Display the AVAIL, USED, FREE, LIMIT, and RESERVE values in Mbytes instead of Kbytes, rounding off to the nearest whole Mbyte (multiples of .ifn 1024^2). .ift 1024\u\s-22\s0\d). The output header format changes from .C Kb to .C Mb accordingly. .TP .C \-t Add a totals line with a TYPE of .CR total . This line totals only the paging information displayed above it, not all paging areas; this line might be misleading if a subset of .C \-dfrM is specified. .TP .C \-a Show all device paging areas, including those configured into the kernel but currently disabled. (These are normally omitted.) The word .C disabled appears after the NAME, and the Kb AVAIL, Kb USED, and Kb FREE values are 0. The .C \-a option is ignored unless the .C \-d option is present or is true by default. .TP .C \-d Print information about device paging areas only. This modifies the output header appropriately. .TP .C \-f Print information about file system paging areas only. This modifies the output header appropriately. .TP .C \-n Categorize file system paging area information into .C localfs areas and .C network areas, instead of calling them both .C fs areas. .TP .C \-r Print information about reserved paging space only. .TP .C \-M Print information about memory paging space only. .IP The .CR \-d , .CR \-f , .CR \-n , .CR \-r and .C \-M options can be combined. The default is .CR \-dfnrM . .TP .C \-q Quiet mode. Print only a total "Kb AVAIL" value (with the .C \-m option, Mb AVAIL\s0); that is, the total paging space available on the system (device, file system, reserve, or memory paging space only if .CR \-d , .CR \-f , .CR \-r , or .C \-M is specified), for possible use by programs that want a quick total. If .C \-q is specified, the .C \-t and .C \-a options are ignored. .TP .C \-w Print a warning about each device paging area that contains wasted space; that is, any device paging area whose allocated size is less than its total size. This option is effective only if .C \-d is also specified or true by default. .RE .SH RETURN VALUE .C swapinfo returns 0 if it completes successfully (including if any warnings are issued), or 1 if it reports any errors. .SH DIAGNOSTICS .C swapinfo prints messages to standard error if it has any problems. .SH EXAMPLES List all file system paging areas with a totals line: .IP .C swapinfo -ft .SH WARNINGS .C swapinfo needs kernel access for some information. If the user does not have appropriate privileges for kernel access, .C swapinfo will print a warning and assume that the defaults for that information have not been changed. .PP Users of .C swapinfo must not rely on the exact field widths and spacing of its output, as these will vary depending on the system, the release of .SM HP-UX, and the data to be displayed. .PP The information in this manual page about paging allocation and other implementation details may change without warning; users should not rely on the accuracy of this information. .SH AUTHOR .C swapinfo was developed by HP. .SH SEE ALSO swapon(1M), swapon(2), fstab(4), fs(4). .\" .\" toc@\f3swapinfo(1M)\f1:\0\0\f4swapinfo\f1@@@system paging space information .\" .\" index@\f4swapinfo\f1 \- system paging space information@@@\f3swapinfo(1M)\f1 .\" index@\f1system paging space information@@@\f3swapinfo(1M)\f1 .\" index@\f1paging space information, system@@@\f3swapinfo(1M)\f1 .\" index@\f1space information, system paging@@@\f3swapinfo(1M)\f1 .\" index@\f1information, system paging space@@@\f3swapinfo(1M)\f1 .\" index@\f1swap space information, system@@@\f3swapinfo(1M)\f1 .\" .\" fileset_database@swapinfo.1m SYS-ADMIN-MAN .\" $Header: swapon.1m,v 74.1 95/03/16 16:38:18 ssa Exp $ .TA s .TH swapon 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME swapon \- enable device or file system for paging .SH SYNOPSIS .SS Preferred Forms: .CR /usr/sbin/swapon .CR \-a .RC [ \-u ] .RC [ \-t .IR type ]...\& .PP .CR /usr/sbin/swapon .RC [ \-e .RC \(or \-f ] .RC [ \-p .IR priority ] .RC [ \-u ] .IR device \0...\& .PP .CR /usr/sbin/swapon .RC [ \-m .IR min ] .RC [ \-l .IR limit ] .RC [ \-r .IR reserve ] .RC [ \-p .IR priority ] .ifn .br .ifn \0\0\0\0 .IR directory \0...\& .SS Obsolescent Form: .CR /usr/sbin/swapon .I directory .RI [ min .I limit .I reserve .IR priority ] .SH DESCRIPTION The .CR swapon command enables devices or file systems on which paging is to take place. (\f3NOTE:\f1 the term `swap' refers to an obsolete implementation of virtual memory; .SM HP-UX actually implements virtual memory by way of paging rather than swapping. This command and others retain names derived from `swap' for historical reasons.) .PP By enabling a .B device for paging, the device can be accessed directly (without going through the file system) during paging activity. When a .B file system is enabled for paging, the device(s) on which the file system resides are accessed indirectly through the file system. There are advantages and disadvantages to both type of paging. Keep the following tradeoffs in mind when enabling devices or file systems for paging. .PP Paging directly to a .B device is significantly faster than doing so through the file system. However, the space on the device that is allocated to paging cannot be used for anything else, even if it is not being actively used for paging. .PP Paging through a .BR "file system" , while slower, provides a more efficient use of the space on the device. Space that is not being used for paging in this case can be used by the file system. Paging across a network to a remote machine is always file system paging. .PP The system begins by paging on only a single device so that only one disk is required at bootstrap time. Calls to .CR swapon normally occur in the system startup script .CR /sbin/init.d/swap_start making all paging space available so that the paging activity is interleaved across several disks. .PP Normally, the .CR \-a argument is given, causing all devices marked as .CR swap and all file systems marked as .CR swapfs in the file .CR /etc/fstab to be made available to the paging system. By using the fields in .CR /etc/fstab .RI ( "special_file_name" or .IR "directory" ; see .IR fstab (5)), the system determines which block device or file system to use. The .I "special_file_name" specified for each .CR swap entry must specify a block special file. The .I directory specified for each .CR swapfs entry must specify a directory within the file system to be enabled. .PP The second form of .CR swapon enables individual block devices to be used for paging. The .I device name must specify a block special file. If more than one device is given, any options specified will be applied to all devices. If a file system exists on the specified block device and neither an .CR \-e nor .CR \-f option is specified, .CR swapon fails and an error message is given. This prevents a file system from being inadvertently destroyed. To request paging in the space between the end of the file system and the end of the device, use .CR \-e . To force paging to a device containing a file system (destroying the file system), the .CR \-f option can be used. Use this with extreme caution! .PP In either of the previous forms, an attempt to enable paging to a device will fail and a warning message will be issued if .CR swapon determines that the device is being used by the .CR savecore command to retrieve system dump information (see .IR savecore (1M)). The .CR \-u option can be used to forcibly enable paging to devices being used by .CR savecore ; however, this may overwrite system dump information contained on the device. .PP The last two forms of .CR swapon provide two different methods for enabling file systems for paging. The third form is the preferred method, with the fourth being provided only for backward compatibility. The .I directory name specifies a directory on the file system that is to be enabled for paging. A directory named .CR /paging is created at the root of the specified file system (unless the file system's name ends with .CR /paging ). All paging files are created within this directory. The optional arguments to the fourth form have the same meaning as the arguments to the options in the third form. Note that, in the fourth form, if any of the optional arguments are specified, all must be specified. In the third form, if more than one directory is given, any options specified will be applied to all directories. .PP After a file system has been enabled for paging, the optional arguments can be modified by subsequent .CR swapon commands. .br .ne 4 .SS Options .CR swapon recognizes the following options and arguments: .RS .TP 15 .CR \-a Cause all devices marked as .CR swap and all file systems marked as .CR swapfs in the file .CR /etc/fstab to be made available to the paging system. The .I options field in .CR /etc/fstab entries is read by .CR swapon , and must contain elements formatted as follows: .RS .TP 15 .CI min= min See the .CI \-m option for the value of .IR min . .TP .CI lim= limit See the .CI \-l option for the value of .IR limit . (File system paging areas only.) .TP .CI res= reserve See the .CI \-r option for the value of .IR reserve . (File system paging areas only.) .TP .CI pri= priority See the .CI \-p option for the value of .IR priority . (File system paging areas only.) .TP .CR end See the .CI \-e option for the meaning of this option. (Device paging areas only.) .RE .IP See .IR fstab (4) for an example entry. .TP .CR \-e Use space after the end of the file system on the block device for paging. An error message is returned if no file system is found on the device. This option cannot be used with the .CR \-f option. Do not confuse this with paging to a file system. This option is for use with a disk that has .I both a file system and dedicated paging space on it. .TP .CR \-f Force the .I device to be enabled, which will destroy the file system on it. Use with extreme caution. Normally, if a file system exists on the .I device to be enabled, .CR swapon fails and displays an error message. This option cannot be used with the .CR \-e option. .TP .CI \-l \0limit .I limit specifies the maximum space the paging system is allowed to take from the disk, provided space is available that is not reserved for exclusive use by the file system. The value of .I limit is rounded up so that it is a multiple of the paging allocation chunk size, which is set with the kernel tunable parameter .CR swchunk (see .IR config (1M) and .IR swapinfo (1M)). See WARNINGS. The default value for .I limit is 0, indicating there is no limit to the amount of file system space the paging system can use. .IP .I limit can be specified in decimal (no prefix), octal .RC ( 0 prefix), or hexadecimal .RC ( 0x prefix). It may be specified in units of kilobytes .RC ( k suffix), megabytes .RC ( M suffix), or file system blocks (no suffix). (A kilobyte is 1024 bytes; a megabyte is 1024 kilobytes; the size of a file system block is determined by the administrator when the file system is created.) .TP .CI \-m \0min .I min indicates the space the paging system will initially take from the file system. The value of .I min is rounded up so that it is a multiple of the paging allocation chunk size, which is set with the kernel tunable parameter .CR swchunk (see .IR config (1M) and .IR swapinfo (1M)). The default value for .I min is 0, indicating no paging space is to be allocated initially. .I min can be specified in the same forms as .IR limit , above. .TP .CI \-p \0priority .I priority indicates the order in which space is taken from the file systems and devices used for paging. Space is taken from the systems with lower priority numbers first. Under most circumstances, space is taken from device paging areas before file system paging areas, regardless of priority. See "Paging Allocation" in .IR swapinfo (1M) for more information. .I priority can have a value from 0 to 10 and has a default value of 1. .TP .CI \-r \0reserve .I reserve specifies the space, in addition to the space currently occupied by the file system, that is reserved for file system use only, making it unavailable to the paging system. This reserved space is in addition to the minimum free space specified by the administrator when the file system was created. See WARNINGS. The default value for .I reserve is 0 indicating that no file system space is reserved for file system use only. .I reserve can be specified in the same forms as .IR limit , above. .TP .CI \-t \0type Restrict the type of the paging area. If the .CR \-t option is omitted, all of the paging areas defined in .CR /etc/fstab are made available. .I type can have one of the following values: .RS .TP 10 .CR dev Device paging areas. .TP .CR fs File system paging areas. .TP .CR local Paging areas defined on the local system. .TP .CR remote Paging areas defined on remote systems. .RE .TP .CR \-u Unlock block device files which are being used by the .CR savecore command. Normally, .CR swapon will not enable paging on a device if it is being used by .CR savecore to retrieve system dump information. The list of devices in use is maintained in the file .CR "/etc/savecore.LCK" . This option forces the device to be enabled, which may overwrite any system dump information contained on the device. This option should be used with extreme caution. .RE .SH RETURN VALUE .CR swapon returns one of the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR >0 An error condition occurred. .RE .PD .SH EXAMPLES The first two examples enable paging to the file system containing the .CR /paging directory. The maximum number of file system blocks available to the paging system is set to 5000, the number of file system blocks reserved for file system use only is set to 10000, and the priority is set to 2. The number of file system blocks initially taken by the paging system defaults to 0 in the first example, and is set to 0 in the second example. On a file system with the default 8kB block size, these examples allocate approximately 40MB of file system paging. .IP .C "/usr/sbin/swapon \-l 5000 \-r 10000 \-p 2 /paging" .IP .C "/usr/sbin/swapon /paging 0 5000 10000 2" .PP This example enables paging to two block devices and sets the priority of both devices to 0. .IP .C "/usr/sbin/swapon \-p 0 /dev/dsk/c10t0d0 /dev/dsk/c13t0d0" .PP This example enables paging to a block device, using the space after the end of the file system for paging and letting the priority default to 1. .IP .C "/usr/sbin/swapon \-e /dev/dsk/c4t0d0" .PP This example enables paging to a block device, forcing paging even if a file system exists on the device. .IP .C "/usr/sbin/swapon \-f /dev/dsk/c12t0d0" .SH WARNINGS Once file system blocks have been allocated for paging space, the file system cannot be unmounted unless the system is rebooted. .PP If any paging area becomes unavailable while the system is running, for example if a network failure occurs while paging to a remote system, the system will immediately halt. .PP The file system block size used by the .CR \-l , .CR \-m , and .CR \-r options varies between file systems, and is defined by the system administrator at the time the file system is created. The .CR dumpfs command can be used to determine the block size for a particular file system (see .IR dumpfs (1M)). .PP When using the .CR \-l and .CR \-r options, the reserve space specified by the .CR \-r option takes precedence over the .CR \-l option. Thus, if: .RS .TP 10 .PD 0 .I D = Total disk space available to ordinary users .TP .I R = Reserve space specified by the .CR \-r option .TP .I limit = Paging space limit specified by the .CR \-l option .TP .I L = Space currently available to the paging system .TP .I F = Space currently occupied by the file system .PD .RE .PP the following relationships hold: .RS .TP 20 .IR F " + " R " + " limit " < \f2D\fP" In normal operation .TP .IR L " = 0" If .I F + .I R >= .I D .TP .RI "0 <= " L " <= " limit If .I F + .I R + .I limit >= .I D .RE .SH FILES .TP 35 .PD 0 .CI /dev/dsk/c card t target d device Normal paging devices .TP .CR /etc/fstab File system table .TP .CR /etc/savecore.LCK List of devices being used by .CR savecore .PD .SH AUTHOR .CR swapon was developed by HP and the University of California, Berkeley. .SH SEE ALSO config(1M), savecore(1M), swapinfo(1M), swapon(2), fstab(4). .\" index@\f4swapon\f1 \- enable device or file system for paging@@@\f3swapon(1M)\f1 .\" index@\f1enable device or file system for paging@@@\f3swapon(1M)\f1 .\" index@\f1paging, enable device or file system@@@\f3swapon(1M)\f1 .\" index@\f1swapping, enable device or file system@@@\f3swapon(1M)\f1 .\" index@\f1device for paging, enable@@@\f3swapon(1M)\f1 .\" index@\f1file system for paging, enable@@@\f3swapon(1M)\f1 .\" .\" toc@\f3swapon(1M)\f1:\0\0\f4swapon\f1@@@enable device or file system for paging .\" $Header: swcluster.1m,v 78.2 96/05/09 15:28:09 ssa Exp $ .\" .\" $Header: swcluster.1m,v 78.2 96/05/09 15:28:09 ssa Exp $ .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro, e.g. .CR, .RI, .\" etc. A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .TA s .TH swcluster 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME swcluster \- install or remove software from diskless server .SH SYNOPSIS .C swcluster .RI [ "XToolkit Options" ] .RC [ -v ][v] .RC [ -i ] .RC [ -p ] .RC [ -f ] .RC [ -r ] .RC [ -b ] .RC [ -l .IR list_class\| ] .RC [ -n ] .RC [ -s .IR source\| ] .br .RC [ -C\| .IR session_file\| ] .RC [ -S\| .IR session_file\| ] .RC [ -x .IR option=value\| ] .RC [ -X\| .IR option_file\| ] .RI [ software_selections ]\0[\c \*(at .IR \0target_selections ] .PP .SH DESCRIPTION The .C swcluster command launches SD commands such as .C swinstall and .C swremove to install or remove software from a HP-UX 10.* NFS diskless cluster. The .C swcluster command may only be run on a diskless server or a stand alone system, not on a client. On stand alone systems, .C swcluster operates in interactive mode only. .PP .C swcluster can be run in .I install mode, which causes software to be installed to a diskless server and its clients, in .I remove mode, which removes non kernel software from a cluster and its clients, or in .I list mode, which lists various parameters of an NFS diskless cluster. .PP .B Install Mode .br In install mode, .C swcluster installs software from a software source, which must be a valid SD depot, to the local diskless server. If the selected software does not require a kernel build, this software is then installed to the diskless clients, and all the clients which are booted will then mount the software from the server and run the .C swconfig command to configure the software. If the software does require a kernel build, then the diskless clients will be halted. As part of the software installation to the server, the server will rebuild its kernel and reboot. After the server boots and runs configure scripts, a server RC script will run .C swcluster again, installing the software to the diskless clients. These clients must then be turned on by hand, at which time they will boot and configure the software. .PP .B Remove Mode .br In remove mode (using the .B -r flag), .C swcluster only supports the removal of non kernel software from clusters. When non kernel software is removed, .C swcluster first contacts all booted clients and unconfigures the software. It then removes the software from the clients, and lastly, from the server. Clients which are not currently booted or are not accessible will not have the software unconfigured. .PP Both install and remove modes support the .B -n flag, which causes .C swcluster to skip the installation or removal of the software from the diskless server. This is useful, for example, if the software is already installed on the server and simply needs to be propagated to the clients. .PP In all modes, .C swcluster is normally silent in the absence of warnings or errors. Using the .B -v flag causes status messages to be printed during operation. More than one flag (i.e. .B -vvv ) may be used to generate more verbose output. Up to 4 .B -v flags are meaningful. .PP .SS Options .C swcluster recognizes the following options: .RS .TP 18 .CI -f \0software_file The parameter specifies a file from which to read software selections. Not valid in interactive (-i) mode. .TP .C -i Invoke the command in interactive mode. Software selections are read using a graphical user interface and need not be specified on the command line. If .I -i is used, the .I "-s, -S," and .I -f options are invalid. .TP .C -p Preview operation only. Operations which change the state of the system (such as installs, removals, .I /etc/fstab modifications, etc.) are not performed. However, other analyses, such as the determination of the client nodes, happen normally. .TP .C -r Operate in removal mode. In this mode software is removed from the cluster instead of being installed. .TP .C -b Forces a shutdown of all clients even if non-kernel software is being installed. .TP .C -l Display information about a cluster. List_class can be one of: .RS .TP 30 .C shroot Lists shared roots. .TP .C prroot Lists private roots. .TP .C clients Lists all clients .TP .C booted_clients Lists booted clients only. .TP .C bundle @ Lists bundles on root. .TP .C product @ Lists products on root. .TP .C subproduct @ Lists subproducts on root. .TP .C fileset @ Lists filesets on root. .RE .TP .CI -s \0source The next parameter specifies the software source for install operations. If the .C -n option is used, .C -s is not needed, since the source is always set to the local diskless server's installed software. .TP .C -n Skips installation or removal of the software to or from the server. This can be used to propagate software already on the diskless server to the clients. .TP .CI -x \0option=value Propagates the given option to the .C SD .C swinstall or .C swremove commands used to perform the install or removal task. .TP .CI -C \0session_file Save the current options and operands to .IR session_file . You can enter a relative or absolute path with the file name. The default directory for session files is .CR /.sw/sessions/ . You can recall a session file with the .C -S option. .TP .CI -S \0session_file Reads options from .CR sessionfile , including the software source and software selections. You can save session information to a file with the .C -C option. .PP .SH EXAMPLES Install the UUCP software package from a depot source on hpdepot named .CR "/release/10.0" to the local S700 diskless cluster, using very verbose output: .IP .C "swcluster -vvv -s hpdepot:/release/10.0 UUCP\0\c \*(at\0" / .PP Remove the UUCP software package from the local HP Series 700 diskless cluster using very verbose output: .IP .C "swcluster -vvv -r UUCP\0\c \*(at\0" / .PP Install the UUCP software package to the local diskless clients, given that UUCP is already installed on the diskless server: .IP .CI "swcluster -vvv -n UUCP\0\c \*(at\0" / .PP .SH AUTHOR .C swcluster was developed by .SM HP. .SH FILES .TP 38 .C /var/adm/sw/swinstall.log Log files from swinstall commands. .TP .C /var/adm/sw/swremove.log Log files from swremove commands. .TP .C /var/adm/sw/swcluster.log Log files from swcluster commands. .TP .C /var/adm/sw/swagent.log Log files from swagent commands. .TP .C /sbin/init.d/swcluster Cluster install startup script. .TP .C /etc/bootptab Control file for .C bootpd (see .IR bootpd (1M)) that contains most of the client information returned by .C dcnodes .SH SEE ALSO sd(4), sd(5), swacl(1M), swagent(1M), swconfig(1M), swcopy(1M), swgettools(1M), swinstall(1M), swjob(1M), swlist(1M), swmodify(1M), swpackage(1M), swpackage(4), swreg(1M), swremove(1M), swverify(1M), update(1M), sam(1M), and the .IR "Managing HP-UX Software with SD-UX" or .IR "HP OpenView Software Distributor Administrator's Guide" manuals. .\" index@\f4swcluster\f1 \- install or remove software from diskless server@@@\f3swcluster(1M)\f1 .\" index@\f1remove software from diskless server@@@\f3swcluster(1M)\f1 .\" index@\f1install software from diskless server@@@\f3swcluster(1M)\f1 .\" index@\f1diskless server, install or remove software from@@@\f3swcluster(1M)\f1 .\" toc@\f3swcluster(1M)\f1:\0\0\f4swcluster\f1@@@install or remove software from diskless server\f1 .\" $Header: swconfig.1m,v 78.2 96/05/09 12:32:48 ssa Exp $ .\" -*-Nroff-*- .\" $Header: swconfig.1m,v 78.2 96/05/09 12:32:48 ssa Exp $ .\" .ds RZ \&HP CONFIDENTIAL .\" .ds RL Release 10.0x .\" .ds MT Software Distributor B.10.0x .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro, e.g. .CR, .RI, .\" etc. A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .\" .ds PN Release B.10.0x .TA s .TH swconfig 1M " " "Hewlett-Packard Company" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ds )H Software Distributor .\" .ds ]W Release B.10.0x .SH NAME swconfig \- Configure, unconfigure, or reconfigure installed software .PP .SH SYNOPSIS .C swconfig .RC [ -p ] .RC [ -v ] .RC [ -u ] .RC [ -x .IR option=value\| ] .RC [ -X\| .IR option_file\| ] .RC [ -f\| .IR software_file\| ] .RC [ -t\| .IR target_file\| ] .br .RC [ -C\| .IR session_file\| ] .RC [ -S\| .IR session_file\| ] .RC [ -Q\| .IR date\| ] .RC [ -J\| .IR jobid\| ] .RI [ software_selections ]\0[\c \*(at .IR \0target_selections ] .PP .SS Remarks: SD-UX commands are included with the HP-UX Operating System and manage software on the .I local host only. To install and manage software simultaneously on multiple .I remote hosts (including PCs) from a central controller, you must purchase the .B "HP OpenView Software Distributor" (HP Prod. No. B1996AA) which provides extended software management, multi-site software distribution capabilities and distribution to PCs. While most of the information in this manual page applies to both SD-UX commands and the OpenView product, some applies .B only to the OpenView product. Where this is the case, you will see: .RS .IP .IR "The following xxx applies only to HP OpenView Software Distributor" .RE .PP .SH DESCRIPTION .PP The .C swconfig command configures, unconfigures, and reconfigures installed and linkinstalled software products for execution on the specified targets. The .C swconfig command transitions software between INSTALLED and CONFIGURED states. .PP Software is automatically configured and unconfigured as part of the .C swinstall and .C swremove commands (respectively). The user can defer configuration when software is installed. The .C swconfig command can (un)configure software independent of .C swinstall and .CR swremove , e.g. to configure (unconfigure) hosts that share software from a server host where the software is actually installed. The .C swconfig command must also be executed when the initial configuration by .C swinstall failed, was deferred, or needs to be changed. .PP Configuration primarily involves the execution of vendor-supplied configure scripts. These scripts perform configuration tasks which enable the use of the software on the target hosts. The .C swconfig command also allows software to unconfigure the hosts on which it no longer will be run. A vendor can supply unconfigure scripts to "undo" the configuration performed by the configure script. .P The configure scripts are not run by .C swinstall and .C swremove when an alternate root directory is specified. Instead, the .C swconfig command must be run after that software has been made available to client hosts, to configure those hosts. Similarly, .C swconfig must be used on client hosts to unconfigure those hosts. Configuration can also be deferred on software installed to the root directory .CR / , for example when multiple configured versions have been allowed, by using the .C defer_configure option with .CR swinstall . .PP Other features of .C swconfig include: .RS .TP 2 \(bu The .C swconfig command supports only configuration of compatible software by default, controllable through the .C allow_incompatible option. .TP \(bu If a fileset specifies a prerequisite on other software, that software must be in a "configured" state before the software specifying the dependency will be configured. .TP \(bu The .C swconfig command will configure multiple versions of a product if the user has set .CR allow_multiple_versions=true . The vendor must therefore detect and prevent multiple configured versions in their configure scripts, if that is necessary. .TP \(bu A vendor's configure script is as useful for operations required for software updates as for new installs. The scripts must also be designed to handle reinstall. .RE .PP .SS Options .C swconfig supports the following options: .RS .TP 15 .C -p Previews a configuration task by running the session through the analysis phase only. .TP .C -v Turns on verbose output to stdout. (The .C swconfig logfile is not affected by this option.) Verbose output is enabled by default, see the .C verbose option below. .TP .C -u Causes .C swconfig to unconfigure the software instead of configuring it. .TP .CI -x \0option=value Set the session .I option to .I value and override the default value (or a value in an alternate .IR option_file specified with the .C -X option). Multiple .C -x options can be specified. .TP .CI -X \0option_file Read the session options and behaviors from .IR option_file . .TP .CI -f \0software_file Read the list of .I software_selections from .I software_file instead of (or in addition to) the command line. .TP .CI -t \0target_file Read the list of .I target_selections from .I target_file instead of (or in addition to) the command line. .TP .CI -C \0session_file Save the current options and operands to .IR session_file . You can enter a relative or absolute path with the file name. The default directory for session files is .CR /.sw/sessions/ . You can recall a session file with the .C -S option. .TP .CI -S \0session_file Execute .C swconfig based on the options and operands saved from a previous session, as defined in .IR session_file . You can save session information to a file with the .C -C option. .P .RS .IP .IR "The -Q and -J options apply only to HP OpenView Software Distributor" .RE .TP 15 .CI -Q \0date Schedules the job for this date. The date's format can be changed by modifying the file .IR /var/adm/sw/getdate.templ . .TP .CI -J \0jobid Executes the previously scheduled job. This is the syntax used by the daemon to start the job. .RE .PP .SS Operands .PP The .C swconfig command supports the following syntax for each .IR software_selection : .IP .C bundle[.product[.subproduct][.fileset]][,version] .P or .IP .C product[.subproduct][.fileset][,version] .br .P The .C version component has the form: .IP .C [,r .IR .C revision][,a .IR .C arch][,v .IR .C vendor][,c .IR .C category] .P or .IP .C [instance_id] .P where .IR can be: ==, >=, <=, <, >, or != which performs individual comparisons on dot-separated fields. For example, r>=B.10.00 means choose all revisions that are greater than or equal to B.10.00. The system will compare each dot-separated field to find matches. Software will only be selected when matches within each field are satisfied. Wildcards are not allowed with these operators. .P The .C = (equals) relational operator is also allowed to specify a particular version component. .P All version components are repeatable within a single specification (e.g. r>=A.12, r ) if the .IR autorecover_product option is set to .CR true ; those that can not be overwritten are moved aside (to # ). .TP \(bu The .C swinstall command supports kernel building scripts and rebooting. Before or after software which modifies the kernel is installed (or updated), .C swinstall will execute system-specific scripts to prepare for or build the new version of the kernel. The remaining .IR software_selections are then installed. These scripts are defined in .C swagent options and include: .CR install_setup_cmd , .CR system_prep_cmd , .CR kernel_build_cmd , and .CR install_cleanup_cmd . .IP After software which requires a system reboot is installed (or updated), .C swinstall will automatically reboot the system. The reboot command is defined by the .C swagent option: .CR reboot_cmd . .IP When updating the operating system to a new revision, installing kernel software first ensures that a new kernel can be generated before the rest of the operating system is updated. After all the .I software_selections are updated (or installed), .C swinstall reboots using the new kernel, then executes the configure scripts for each .IR software_selection . After these scripts complete, it reboots the system again to restore it to its normal state. .TP \(bu No kernel building or system reboots are performed by .CR swcopy . .TP \(bu Both the .C swinstall and .C swcopy commands perform various checks prior to installing/copying the .IR software_selections , for example disc space analysis. .RE .bp .PP .SS Options .C swinstall and .C swcopy support the following options: .RS .TP 15 .IR "XToolKit Options" The .CR swinstall and .CR swcopy commands support a subset of the standard X Toolkit options to control the appearance of the GUI. The supported options are: .CR -bg , .CR -background , .CR -fg , .CR -foreground , .CR -display , .CR -name , .CR -xrm , and .CR -synchronous . See the .C X(1) manual page for a definition of these options. .TP .C -p Previews an install task by running the session through the analysis phase only. .TP .C -i Runs the command in interactive mode (invokes the Graphical User Interface). [Note: The Graphical User Interface is not supported on SunOS]. The SD-UX .CR swinstall , .CR swcopy , and .C swremove commands also support an interactive terminal user interface (text based) in which screen navigation is done with the keyboard (no mouse). .TP .C -l Runs the command in .I linkinstall mode which makes software installed under a server's .IR "shared root" available to a diskless client's .IR "private root" . .IP When run in the .IR linkinstall mode, .CR swinstall : .RS .TP 3 \(bu Creates NFS mounts to the software to make it accessible from the target. This may involve delayed mounting for alternate roots. .TP \(bu Modifies the target's .IR fstab file. .TP \(bu Modifies the source's .C exports file to add mount permission for the target. .RE .IP Mounts are created by examining the .IR share_link product attribute. Not all products support .CR linkinstall . Some products may be visible without creating a new mount if they reside under an old one. The .C -l option is used by the .C swcluster command in installing to diskless clusters. .TP .C -r Causes .C swinstall to install software into alternate root directories (e.g. root filesystems other than .CR / ). As of HP-UX release 10.2*, .CR -r is optional but is allowed to maintain compatibility with previous versions. .TP .C -v Turns on verbose output to stdout. (The .C swinstall or .C swcopy logfile is not affected by this option.) Verbose output is enabled by default, see the .C verbose option below. .TP .CI -s \0source Specifies the source depot (or tape) from which software will be installed or copied. The default source type is .IR directory. .TP .CI -x \0option=value Set the session .I option to .I value and override the default value (or a value in an alternate .IR option_file specified with the .C -X option). Multiple .C -x options can be specified. .TP .CI -X \0option_file Read the session options and behaviors from .IR option_file . .TP .CI -f \0software_file Read the list of .I software_selections from .I software_file instead of (or in addition to) the command line. .TP .CI -t \0target_file Read the list of .I target_selections from .I target_file instead of (or in addition to) the command line. Installing to multiple remote targets is available only via the HP OpenView Software Distributor product (HP Prod. No. B1996AA) which provides extended software management plus multi-site software distribution capabilities. .TP .CI -C \0session_file Save the current options and operands to .IR session_file . You can enter a relative or absolute path with the file name. The default directory for session files is .CR /.sw/sessions/ . You can recall a session file with the .C -S option. .TP .CI -S \0session_file Execute .C swinstall or .C swcopy based on the options and operands saved from a previous session, as defined in .IR session_file . You can save session information from a command-line session with the .C -C .I session_file option. .P .RS .IP .IR "The -Q and -J options apply only to HP OpenView Software Distributor" .RE .TP 15 .CI -Q \0date Schedules the job for this date. The date's format can be changed by modifying the file .CR /var/adm/sw/getdate.templ . .TP .CI -J \0jobid Executes the previously scheduled job. This is the syntax used by the daemon to start the job. .RE .PP .SS Operands .PP The .C swinstall and .C swcopy commands support the following syntax for each .IR software_selection : .IP .C bundle[.product[.subproduct][.fileset]][,version] .P or .IP .C product[.subproduct][.fileset][,version] .P The .C version component has the form: .IP .C [,r .IR .C revision][,a .IR .C arch][,v .IR .C vendor][,c .IR .C category] .P or .IP .C [instance_id] .P where .IR can be: *, ==, >=, <=, <, >, or != which performs individual comparisons on dot-separated fields. For example, r>=B.10.00 means choose all revisions that are greater than or equal to B.10.00. The system will compare each dot-separated field to find matches. Software will only be selected when matches within each field are satisfied. Wildcards are not allowed with these operators. .P The .C = (equals) relational operator is also allowed to specify a particular version component. .PP All version components are repeatable within a single specification (e.g. r>=A.12, r.log This is the default command log file for the .C swinstall and .C swcopy commands. For .CR swinstall , the default value is .CR /var/adm/sw/swinstall.log . For .CR swcopy , the default value is .CR /var/adm/sw/swcopy.log . .TP .C loglevel=1 Controls the log level for the events logged to the command logfile, and the target agent logfile. A value of .C 0 provides no information to the logfile. A value of .C 1 enables verbose logging to the logfiles. A value of .C 2 enables very verbose logging to the logfiles. .TP .C log_mesgid=0 Controls whether numeric identification numbers are prepended to logfile messages produced by SD. A value of 0 (default) indicates no such identifiers are attached. Values of 1-4 indicate that identifiers are attached to messages: .RS .TP 3 \(bu 1 applies to ERROR messages only .TP \(bu 2 applies to ERROR and WARNING messages .TP \(bu 3 applies to ERROR, WARNING, and NOTE messages .TP \(bu 4 applies to ERROR, WARNING, NOTE, and certain other logfile messages. .RE .TP .C layout_version=1.0 The object and attribute syntax of SD now conforms to the .C layout_version of 1.0 from the IEEE POSIX 1387.2 Software Administration standard. This options controls to which .C layout_version the SD commands write distributions and .C swlist output. Supported values are .C 0.8 and .CR 1.0 . The value of .C 1.0 should be used for future compatibility; the SD commands still accept the old keyword names as well as the new ones. The value of .C 0.8 should only be used to create distributions readable by older versions of SD. .\" .bp .TP .C match_target=false Applies only to .CR swinstall . If set to .CR true , other software selections are ignored and software selection is done by locating filesets on the source that match the target system's installed filesets. If multiple targets are specified, the first in the list is used as the basis for selections. .TP .C mount_all_filesystems=true Attempt to mount all filesystems in the .IR /etc/fstab file at the beginning of the analysis phase, to ensure that all listed filesystems are mounted before proceeding. This policy helps to ensure that files are not loaded into a directory that may be below a future mount point. .IP If set to .CR false , the mount operation is not attempted, and no check of the current mounts is performed. .TP .C polling_interval=2 Defines the polling interval, in seconds, used by the interactive GUI or TUI of the controller. It specifies how often each target agent will be polled to obtain status information about the task being performed. When operating across wide-area networks, the polling interval can be increased to reduce network overhead. .TP .C register_new_depot=true Applies only to .CR swcopy . Causes .C swcopy to register a newly created depot with the local .CR swagentd . This action allows other SD commands to automatically "see" this depot. If set to .CR false , a new depot will not be automatically registered. (It can be registered later with the .C swreg command.) .TP .C register_new_root=true Applies only to .CR swinstall . Causes alternate roots to be registered during .CR swinstall . These can be listed with .CR swlist . .TP .C reinstall=false When re-installing (or re-copying) an existing revision of a fileset, this option causes that fileset to be skipped, i.e. not re-installed. If set to .CR true , the fileset will be re-installed (re-copied). .TP .C reinstall_files=true Causes all the files in a fileset to always be reinstalled or recopied, even when the file already exists at the target and is identical to the new file. If set to .CR false , files that have the same .IR checksum (see next option), size and timestamp will not be re-installed. This check enhances performance on slow networks or slow discs. .TP .C reinstall_files_use_cksum=true This option affects the operation when the .CR reinstall_files option is set to false. It causes the checksums of the new and old file to be computed and compared to determine if the new file should replace the old one. (The checksum is slower, but is a more robust way to check for files being equivalent.) If set to .CR false , the checksums are not computed, and files are (not) reinstalled based only on their size and timestamp. .TP .C retry_rpc=0 For HP OpenView Software Distributor .CR retry_rpc=1 . Defines the number of times a lost source connection will be retried during file transfers in .CR swinstall or .CR swcopy . A lost connection is one that has timed out. When used in conjunction with the .C rpc_timeout option, the success of installing over slow or busy networks can be increased. If set to zero, then any .C rpc_timeout to the source will cause the task to abort. If set from 1 to 9, then the install of each fileset will be attempted that number of times. The .C reinstall_files option should also be set to false to avoid installing files within the fileset that were successfully installed. .TP .C rpc_binding_info=ncadg_ip_udp:[2121] Defines the protocol sequence and endpoint which will be used to contact .CR swagentd . HP-UX supports both the .IR udp .CR(ncadg_ip_udp:[2121] and .IR tcp .CR (ncacn_ip_tcp:[2121] protocol sequence/endpoint. This value should be consistent among all hosts that work together. See sd(5) for details on specifying this option. .TP .C rpc_timeout=7 For HP OpenView Software Distributor .CR rpc_timeout=5 . Relative length of the communications timeout. This is a value in the range from 0 to 9 and is interpreted by the DCE RPC. Higher values mean longer times; you may need a higher value for a slow or busy network. Lower values will give faster recognition on attempts to contact hosts that are not up, or are not running the .CR swagentd . Each value is approximately twice as long as the preceding value. A value of 5 is about 30 seconds for .CR ncadg_ip_udp . .TP .C select_local=true If no .IR target_selections are specified, select the default root directory .CR / .RC ( swinstall ), or the default .CR target_directory .RC ( swcopy ), at the local host as the target of the command. .TP .C software= Defines the default .IR software_selections . There is no supplied default. If there is more than software selection, they must be separated by spaces. .TP .C software_view=all_bundles For HP OpenView Software Distributor, the default is .CR products . Indicates the software view to be used by the SD-UX interactive interface of the commands. It can be set to .CR products , .CR all_bundles , or a bundle category tag (to indicate to show only bundles of that category). The default software view (bundles) will also show top level software (products and bundles). .TP .C source_cdrom=/SD_CDROM Defines the default location of the source CD-ROM. This syntax can be .CR host:path . .TP .C source_directory=/var/spool/sw Defines the default location of the source depot. This syntax can be .CR host:path . The .C -s option overrides this value. .TP .C source_tape=/dev/rmt/0m Defines the default location of the source tape, usually the character-special file of a local tape device. If the .CR host:path syntax is used, the host must match the local host. The .C -s option overrides this value. .TP .C source_type=directory Defines the default source type: .CR cdrom , .CR directory , or .CR tape . The source type derived from the .C -s option overrides this value. .TP .C target_directory=/var/spool/sw Applies only to .CR swcopy . Defines the default location of the target depot. .TP .C targets= Defines the default .IR target_selections . There is no supplied default (see .C select_local above). If there is more than target selection, they must be separated by spaces. .TP .C uncompress_files=false Applies only to .CR swcopy . If the files being transferred from a source are compressed, setting this option will uncompress the files before storing them on the target depot. .TP .C use_alternate_source=false Empowers each target agent to use its own, configured alternate source, instead of the one specified by the user. If .CR false , each target agent will use the same source, namely the source specified by the user and validated by the command. If .CR true , each target agent will instead use its own configured value for the source. .TP .C verbose=1 Controls the verbosity of the .C swinstall or .C swcopy output (stdout). A value of .C 0 disables output to stdout. (Error and warning messages are always written to stderr). A value of .C 1 enables verbose messaging to stdout. .TP .C write_remote_files=false Prevents the installation or copying of files to a target which exists on a remote (NFS) filesystem. All files destined for a remote filesystem will be skipped. .IP If set to .CR true and if the superuser has write permission on the remote filesystem, the remote files will not be skipped, but will be installed or copied. .RE .SS Session File .PP Each invocation of the .C swinstall or .C swcopy command defines an installation or copy session. The invocation options, source information, software selections, and target hosts are saved before the installation or copy task actually commences. This lets you re-execute the command even if the session ends before proper completion. .PP Each session is automatically saved to the file .I $HOME/.sw/sessions/swinstall{swcopy}.last. This file is overwritten by each invocation of .C swinstall or .CR swcopy . .PP You can also save session information from interactive or command-line sessions. From an interactive session, you can save session information into a file at any time by selecting the .I Save Session or .I Save Session As option from the .I File menu. From a command-line session, you can save session information by executing .C swinstall or .C swcopy with the .C -C .I session__file option. .PP A session file uses the same syntax as the defaults files. You can specify an absolute path for a session file. If you do not specify a directory, the default location for a session file is .I /.sw/sessions/ . .PP To re-execute a saved session from an interactive session, use the .I Recall Session option from the .I File menu. To re-execute a session from a command-line, specify the session file as the argument for the .C -S .I session__file option of .CR swinstall or .CR swcopy . .PP Note that when you re-execute a session file, the values in the session file take precedence over values in the system defaults file. Likewise, any command line options or parameters that you specify when you invoke .CR swinstall or .CR swcopy take precedence over the values in the session file. .PP .SS Software and Target Lists .PP The .C swinstall and .C swcopy commands support software and target selections from separate input files (see the .C -f and .C -t options). Software and targets specified in these files will be selected for operation. .P Additionally, the interactive interface for these commands read a list of possible hosts to operate on from the values found in: .IP .C /var/adm/sw/defaults.hosts - the system-wide default list of hosts, .IP .C $HOME/.sw/defaults.hosts - the user-specific default list of hosts. .P Hosts in this file will not be marked for operation, but provide a default list from which to choose. For each interactive command, target hosts containing roots, containing depots, and hosts serving as PC controllers are specified in separate lists ( .CR hosts , .CR hosts_with_depots , and .C pc_controllers respectively). The list of hosts are enclosed in {} braces and separated by white space (blank, tab and newline). For example: .RS .TP 4 .C swinstall.hosts={hostA hostB hostC hostD .PD 0 .TP .C hostE hostF} .TP .C swinstall.pc_controllers={pc1 pc2} (HP OpenView Software Distributor only) .TP .C swcopy.hosts_with_depots={hostS} .TP .C swcopy.pc_controllers={pc1 pc2} (HP OpenView Software Distributor only) .PD .RE .P .RS .IP .IR "The following paragraph applies only to HP OpenView Software Distributor" .RE .PP For PC software installation, the interactive interface generates PC target lists by querying the PC Controller (and it's associated fileserver). All users, groups, and machines returned from this query will be included in the default list from which to choose. Additionally, all machines returned from this query will by default be selected for installation when the user selects a PC Controller. .bp .PP .SS Environment Variables .PP The .C swinstall program sets these environment variables for use by the software control scripts being executed: .PP .C LANG .IP Determines the language in which messages are displayed. If LANG is not specified or is set to the empty string, a default value of .C C is used. See .C lang(5) for more information. .IP NOTE: The language in which the SD agent and daemon log messages are displayed is set by the system configuration variable script, .CR /etc/rc.config.d/LANG . For example, .CR /etc/rc.config.d/LANG , must be set to .CR LANG=ja_JP.SJIS or .CR LANG=ja_JP.eucJP to make the agent and daemon log messages display in Japanese. .PP .C SW_CONTROL_DIRECTORY .IP Defines the current directory of the script being executed, either a temporary catalog directory, or a directory within in the Installed Products Database (IPD). This variable tells scripts where other control scripts for the software are located (e.g. subscripts). .PP .C SW_DEFERRED_KERNBLD .IP This variable is normally unset. If it is set, the actions necessary for preparing the system file .CR /stand/system cannot be accomplished from within the .IR postinstall scripts, but instead must be accomplished by the .IR configure scripts . This occurs whenever software is installed to a directory other than .IR / , such as for a cluster client system. This variable should be read only by the .IR configure and .IR postinstall scripts of a kernel fileset. The .CR swinstall command sets these environment variables for use by the kernel preparation and build scripts. .PP .C SW_INITIAL_INSTALL .IP This variable is normally unset. If it is set, the .C swinstall session is being run as the back end of an initial system software installation ("cold" install). .PP .C SW_KERNEL_PATH .IP The path to the kernel. The default value is .CR /stand/vmunix , defined by the .CR swagent option or .CR kernel_path . .PP .C SW_LOCATION .IP Defines the location of the product, which may have been changed from the default product directory. When combined with the .CR SW_ROOT_DIRECTORY , this variable tells scripts where the product files are located. .PP .C SW_PATH .IP A PATH variable which defines a minimum set of commands available to for use in a control script (e.g. .CR /sbin:/usr/bin ). .PP .C SW_ROOT_DIRECTORY .IP Defines the root directory in which the session is operating, either "/" or an alternate root directory. This variable tells control scripts the root directory in which the products are installed. A script must use this directory as a prefix to SW_LOCATION to locate the product's installed files. The configure script is only run when SW_ROOT_DIRECTORY is "/". .PP .C SW_SESSION_IS_KERNEL .IP Indicates whether a kernel build is scheduled for a kernel fileset selected for installation. This variable is exported to a fileset's control scripts and must be tested by .I preremove scripts to determine whether any additions must be performed by the fileset's .I postinstall script at install time. .IP A .C "TRUE" value indicates that the selected kernel fileset is scheduled for a kernel build and that changes to .I /stand/system are required. A null value, indicates that a kernel build is not scheduled and that changes to .I /stand/system is not required. .IP The value of this variable is always equal to the value of .CR SW_SESSION_IS_REBOOT . .PP .C SW_SESSION_IS_REBOOT .IP Indicates whether a reboot is scheduled for a fileset selected for installation. Because all HP-UX kernel filesets are also reboot filesets, the values of this variables is always equal to the value of .CR SW_SESSION_IS_KERNEL . .PP .C SW_SOFTWARE_SPEC .IP This variable contains the fully qualified software specification of the current product or fileset. The software specification allows the product or fileset to be uniquely identified. .PP .C SW_SYSTEM_FILE_PATH .IP The path to the kernel's system file. The default value is .CR /stand/system . .PP .SS Signals The .C swinstall and .C swcopy commands catch the signals SIGQUIT and SIGINT. If these signals are received, the command prints a message, sends a Remote Procedure Call (RPC) to the agents to wrap up, and then exits. .P Each agent will complete the install/copy task (if the execution phase has already started) before it wraps up. This avoids leaving software in a corrupt state. .PP .SS Locking .PP SD commands use a common locking mechanism for reading and modifying both the Installed Products Database (IPD) and software depots. This mechanism allows multiple readers but only one writer on an IPD or depot: .PP .BR "Write Locks" .IP .C swinstall commands that modify the IPD are restricted from simultaneous modification using .IR fcntl (2) locking on the file .IP .C /swlock .IP (e.g. .CR /var/adm/sw/products/swlock ). .PP .BR "Depot Modification Locks" .IP .C swcopy commands that modify a software depot are also restricted from simultaneous modification using .IR fcntl (2) locking on the file .IP .C /catalog/swlock .IP (e.g. .CR /var/spool/sw/catalog/swlock ). .PP .BR "Read Locks" .IP Both .C swinstall and .C swcopy commands set .C fcntl(2) read locks on either IPDs or depots using the .C swlock file mentioned above. When a read lock is set, it prevents all SDU commands from performing modifications (i.e. from setting write locks). Specifically, with .C swinstall and .CR swcopy , the source depot is read locked for the duration of the command session. If a read lock cannot be set, the depot/media cannot be used as the software source. .IP During the analysis phase of .CR swinstall , the IPD is read locked while obtaining information about the installed products. If a read lock cannot be set, the analysis fails. .PP .RS .TP 15 .IR "The Terminal User Interface (TUI) is only supported on SD-UX" .RE .SS VT320 Terminal Support Because the VT320 terminal has predefined local functions for keys labeled as F1, F2, F3 and F4, users should use following mapping when they desire to use function keys: .PP .RS .TP 20 HP or Wyse60 VT320 or HP 700/60 in VT320 mode .TP F1 PF2 .CR " !" .TP F2 PF1 .CR " !" .TP F3 space bar .TP F4 PF3 .CR " !" .TP F5 F10, [ EXIT ], F5 .CR " *" .TP F6 none .TP F7 F18, first unlabeled key to right of Pause/Break* .TP F8 F19, second unlabeled key to right of Pause/Break* .TP 5 .CR "*" - When using PC-AT keyboard with HP 700/60 in VT320 mode .TP .CR "!" - See "Configuration: HP 700/60 in DEC mode, or DEC terminals with PC-AT type keyboard" .RE .RS .PP Further, since DEC terminals do not support softkey menu, no such menu is displayed on these terminals. .PP Many applications tend to use TAB for forward navigation (moving from one field to another) and shift-TAB is used for backward navigation. Users having DEC terminals or using terminals in DEC emulation modes such as VT100 or VT320 may note that these terminals/emulators may give out same character for TAB and shift-TAB. As such, it is impossible for an application to distinguish between TAB and shift-TAB, and both of them treated as if a TAB key was pressed. It might present slight overhead to users in case they want to go backwards. Now instead, they should complete rest of the inputs and get back to the desired field later. .PP .SS VT100 Terminal Support VT100 does not allow the (f1-f8) function keys to be configured. Therefore, the following keyboard mappings will apply to VT100 terminals: .RS .TP 20 HP or Wyse60 VT100 or HP 700/60 in VT100 mode .TP F1 PF2 .CR " !" .TP F2 PF1 .CR " !" .TP F3 space bar .TP F4 [PF3], [space bar] or [PF3], [=] .CR " !" .TP F5 return .TP F6 none .TP F7 none .TP F8 none .TP 5 .CR "!" - See "Configuration: HP 700/60 in DEC mode, or DEC terminals with PC-AT type keyboard" .RE .RS .PP Further, since DEC terminals do not support softkey menu, no such menu is displayed on these terminals. .PP Many applications tend to use TAB for forward navigation (moving from one field to another) and shift-TAB is used for backward navigation. Users having DEC terminals or using terminals in DEC emulation modes such as VT100 or VT320 may note that these terminals/emulators may give out same character for TAB and shift-TAB. As such, it is impossible for an application to distinguish between TAB and shift-TAB, and both of them treated as if a TAB key was pressed. It might present slight overhead to users in case they want to go backwards. Instead, they should complete rest of the inputs and get back to the desired field later. .PP .SS "Configuration: HP 700/60 terminal in DEC mode, or DEC terminal with PC-AT type keyboard" .PP Customers using the following configuration may want to be aware of the following keyboard difference. .PP It may be possible for a user with the "HP 700/60 terminal in DEC mode, or DEC terminal with PC-AT type keyboard" configuration to be told to press function key F1 through F4 to achieve some desired result. For HP 700/60 terminal in DEC mode or DEC terminals, these functions keys may be mapped onto PF1-PF4 keys. (see "Keyboard Mappings"). However, the PC-AT type keyboard does not provide PF1, PF2, PF3, or PF4 keys, as does the DEC/ANSI keyboard. .PP .B "Keyboard Mappings" .PP .RS .TP 20 "Num Lock" maps to "PF1" .TP "/" maps to "PF2" .TP "*" maps to "PF3" .TP "-" maps to "PF4" .RE .RS The "Num Lock", "/", "*", and "-" keys are located on the keyboard, in a row, above the number pad on the right side of the keyboard. Please note that although this keyboard is called a PC-AT type keyboard, it is supplied by HP. A PC-AT type keyboard can be recognized by location of ESC key at the left-top of the keyboard. .SS "Wyse60 Terminal Support" .PP On Wyse60, use DEL (located next to Backspace) key to backspace. On an HP 700/60 with a PC-AT type keyboard in Wyse60 mode, the DEL key is located in the bottom row on the number pad. .PP Wyse60 terminals provide a single line to display softkey labels unlike HP terminals which provide two lines. Sometimes this may result in truncated softkey labels. For example, "Help on Context" label for F1 may appear as "Help on C". Some standard labels for screen-oriented applications such as SAM and swinstall are as follows: .PP .RS .TP 35 On wyse60 may appear as .. means .TP Help On C Help On Context .TP Select/D Select/Deselect .TP Menubar Menubar on/off .RE .PP .SH RETURN VALUES .PP An interactive .C swinstall or .C swcopy session always returns 0. A non-interactive .C swinstall or .C swcopy session returns: .RS .TP 4 .C 0 The .I software_selections were successfully installed/copied. .PD 0 .TP .C 1 The install/copy operation failed on all .IR target_selections . .TP .C 2 The install/copy operation failed on some .IR target_selections . .PD .RE .PP .SH DIAGNOSTICS .PP The .C swinstall and .C swcopy commands write to stdout, stderr, and to specific logfiles. .PP .SS Standard Output .PP An interactive .C swinstall or .C swcopy session does not write to stdout. A non-interactive .C swinstall or .C swcopy session writes messages for significant events. These include: .RS .TP 2 \(bu a begin and end session message, .PD 0 .TP \(bu selection, analysis, and execution task messages for each .IR target_selection . .PD .RE .PP .SS Standard Error .PP An interactive .C swinstall or .C swcopy session does not write to stderr. A non-interactive .C swinstall or .C swcopy session writes messages for all WARNING and ERROR conditions to stderr. .PP .SS Logging .PP Both interactive and non-interactive .C swinstall and .C swcopy sessions log summary events at the host where the command was invoked. They log detailed events to the .C swagent logfile associated with each .IR target_selection . .PP .TP Command Log .br The .C swinstall and .C swcopy commands log all stdout and stderr messages to the the logfile .IR /var/adm/sw/swinstall.log .RI ( /var/adm/sw/swcopy.log ). Similar messages are logged by an interactive .C swinstall and .C swcopy session. (The user can specify a different logfile by modifying the .C logfile option.) .TP Target Log .br A .C swagent process performs the actual install/copy operation at each .IR target_selection . For install tasks, the .C swagent logs messages to the file .I var/adm/sw/swagent.log beneath the root directory (e.g. .C / or an alternate root directory). For copy tasks, the .C swagent logs messages to the file .I swagent.log beneath the depot directory (e.g. .CR /var/spool/sw ). .\".PP .\"When operating on a readonly or serial distribution object (for example, a .\"CD-ROM located at /mnt/cd or a tape media .\"located at /dev/rmt/0m) the logfile .\".C /swagent.log .\"cannot be used. If the agent cannot write to this logfile, then it logs .\"to .\".IR /tmp/swagent.log. .PP .RS .IP .IR "The following line applies only to HP OpenView Software Distributor" .RE .PP Command and target log files can be viewed using the .C swjob command. .PP .SH EXAMPLES .PP .SS swinstall .PP To invoke an interactive session of .CR swinstall : .IP .C "swinstall" .PP Select the C and Pascal products from the network source software server (sw_server) and start an interactive session: .IP .C "swinstall -i -s sw_server cc pascal" .PP .RS .IP .IR "The following example applies only to HP OpenView Software Distributor" .RE .PP Install the C and Pascal products to a set of remote hosts: .IP .C "swinstall -s sw_server cc pascal" \*(at .C " hostA hostB hostC" .PP Update the HP Omniback product from a CD-ROM mounted at /cd : .IP .C "swinstall -s /cd/swmedia Omniback" .PP Install an incompatible version of HP Omniback into the directory .IR /exports: .IP .C "swinstall -x allow_incompatible=true -s/products Omniback,a=arch" \*(at .C " /exports" .PP Install all products from the cartridge tape .IR /dev/rmt/0: .IP .C "swinstall -s /dev/rmt/0 \e*" .PP Reinstall the .I software_selections listed in the file .C /tmp/install.products on the hosts listed in the file .C tmp/install.hosts: .IP .C "swinstall -x reinstall=true -f/tmp/install.products -t/tmp/install.hosts" .PP Execute .C swinstall interactively using the session file .C /tmp/case.selections as a basis: .IP .C "swinstall -i -S /tmp/case.selections" .PP To .IR linkinstall the product TEST to the clients .C "clientA, clientB" from the server: .IP .C "swinstall -l -r -s :OS_700 TEST" \*(at .C "clientA clientB" .PP To .IR linkinstall product TEST2 to your own "/" directory from an application server on "serve": .IP .C "swinstall -l -s serve TEST2" .PP .RS .IP .IR "The following example applies only to HP OpenView Software Distributor" .RE .PP Install the C product to a set of PC end targets: .IP .C "swinstall -s sw_serve cc @ pc_controller::PC1 pc_controller::PC2 To schedule the above installation to run at the indicated time: .IP .C "swinstall -Q 12/01,11:00 -s sw_serve cc @ pc_controller::PC1 pc_controller::PC2" .PP .SS swcopy .PP Invoke an interactive session of .CR swcopy : .IP .C "swcopy" .PP Invoke an interactive session, using default depot at hostX as the source: .IP .C "swcopy -i -s hostX" .PP Copy all products from the cartridge tape .C /dev/rmt/0m to the default depot on the local host: .IP .C "swcopy -s /dev/rmt/0m \e*" .PP Load the .I software_selections listed in the file .C /tmp/load.products using the default source/depot: .IP .C "swcopy -f /tmp/load.products" .PP .RS .IP .IR "The following example applies only to HP OpenView Software Distributor" .RE .PP Copy the C and Pascal products to some local and remote depots: .IP .C "swcopy -s sw_server cc pascal" \*(at .C " /var/spool/sw hostA:/tmp/sw hostB" .PP .\".SH WARNINGS .\".PP .\".PP .\".SH DEPENDENCIES .PP .SH LIMITATIONS .PP .\" The SunOS and SD-UX versions of .C swinstall and .C swcopy do not support the installation and configuration of software products on remote targets. .PP The SunOS version of .C swinstall and .C swcopy does not provide a graphical user interface to install and configure software products. .PP .RS .IP .IR "The following PC information applies only to HP OpenView Software Distributor" .RE .PP When copying software to a PC Controller, the .C swcopy command only supports a single PC depot (configured on the PC Controller). .PP For PC software installation, the .C swinstall command first copies software to the PC depot, where it is then accessed by the SD PC agent at each PC target. Only options that apply to .C swcopy apply when installing PC software to the PC Controller. The following options are not supported: .IP .PD 0 .C -r .IP .C allow_downdate .IP .C allow_multiple_versions .IP .C enforce_scripts .IP .C enforce_kernbld_failure .IP .C defer_configure .IP .C register_new_root .PD .PP When packaging PC software using the PC Console, functionality similar to the following .C swinstall options can be set via the Job Settings dialog: .IP .PD 0 .C autorecover_product .IP .C autoreboot .IP .C retry_rpc .IP .C enforce_dsa .IP .C loglevel .PD .P In addition, the following .C swcopy options do not apply to PC Controllers: .IP .PD 0 .C autoselect_dependencies .IP .C enforce_dependencies .IP .C create_target_path .IP .C autoselect_reference_bundles .IP .C mount_all_filesystems .IP .C target_directory .IP .C use_alternate_source .IP .C write_remote_files .PD .PP .SH FILES .PP .\" .C /var/adm/sw/ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. This directory is also the default location of logfiles. .RE .\" .C /usr/lib/sw/sys.defaults .br .RS 8 Contains the master list of current SD options (with their default values). .RE .\" .C /var/adm/sw/defaults .br .RS 8 Contains the active system-wide default values for some or all SD options. .RE .\" .C $HOME/.sw/defaults .br .RS 8 Contains the user-specific default values for some or all SD options. .RE .\" .C /var/adm/sw/defaults.hosts .br .RS 8 Contains the system-wide default list of hosts to manage. .RE .\" .C $HOME/.sw/defaults.hosts .br .RS 8 Contains the user-specific default list of hosts to manage. .RE .\" .C /var/adm/sw/getdate.templ .br .RS 8 Contains the set of date/time templates used when scheduling jobs. .RE .\" .C $HOME/.sw/sessions/ .br .RS 8 Contains session files automatically saved by the SD commands, or explicitly saved by the user. .RE .\" .C /var/adm/sw/products/ .br .RS 8 The Installed Products Database (IPD), a catalog of all products installed on a system. .RE .\" .C /var/spool/sw/ .br .RS 8 The default location of a source and target software depot. .RE .RS .IP .IR "The following applies only to HP OpenView Software Distributor" .RE .PP .C /var/adm/sw/queue/ .br .RS 8 The directory which contains the information about all active and complete install jobs, copy jobs, and other jobs initiated by the SD commands. .RE .PP .SH PC FILES .PP .RE .RS .IP .IR "The following applies only to HP OpenView Software Distributor" .RE .PP .\" .C ...\\\\SD\\\\DATA\\\\ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. .RE .\" .C ...\\\\SD\\\\DATA\\\\DEPOT\\\\ .br .RS 8 The default location of a source and target PC depot. .RE .PP .SH AUTHOR .PP .C swinstall and .C swcopy were developed by the Hewlett-Packard Company. .PP .SH SEE ALSO .PP sd(4), sd(5), swacl(1M), swagentd(1M), swcluster(1M), swconfig(1M), swgettools(1M), swjob(1M), swlist(1M), swmodify(1M), swpackage(1M), swpackage(4), swreg(1M), swremove(1M), swverify(1M), update(1M), and the .IR "HP OpenView Software Distributor Administrator's Guide" or .IR "Managing HP-UX Software with SD-UX" manuals. .\" .\ ====================================================================== .\" index@\f4swinstall\f1 \- install and configure software products@@@\f3swinstall(1M)\f1 .\" index@\f4swcopy\f1 \- copy software products for subsequent installation or distribution@@@\f3swinstall(1M)\f1 .\" index@\f1software products, install, configure, and copy@@@\f3swinstall(1M)\f1 .\" index@\f1install, software products@@@\f3swinstall(1M)\f1 .\" index@\f1copy, software products@@@\f3swinstall(1M)\f1 .\" index@\f1configure, software products@@@\f3swinstall(1M)\f1 .\" .\" index@\f1terminals, VT320, VT100, Wyse60@@@\f3swinstall(1M)\f1 .\" index@\f1VT320 terminal@@@\f3swinstall(1M)\f1 .\" index@\f1VT100 terminal@@@\f3swinstall(1M)\f1 .\" index@\f1Wyse60 terminal@@@\f3swinstall(1M)\f1 .\" .\" toc@\f3swinstall(1M)\f1:\0\0\f4swcopy\f1, \f4swinstall\f1@@@install and configure software products, copy software products\f1 .\" toc@\f4swcopy\f1:\0\0copy software products for subsequent installation or distribution@@@\f1see \f3swinstall(1M)\f1 .\" .\" links@swinstall.1m swcopy.1m .\" .\" $Header: swgettools.1m,v 78.1 96/02/29 01:18:54 ssa Exp $ .\" -*-Nroff-*- .\" .ds RZ \&HP CONFIDENTIAL .\" .ds RL Release B.10.1 .\" .ds MT Software Distributor B.10.1 .\" The '@' hoses eroff, so use a display and don't .\" put the display inside of a font macro, e.g. .CR, .RI, etc. Instead split .\" the word containing the @ using the \c (continuation) and \0 (space) appropriately. .\" .ift .ds at \f4\s+1@\s0\fP\c .\" .ifn .ds at \f3@\fP\c .\" .ds PN Release B.10.1 .TA s .TH swgettools 1M " " "Hewlett-Packard Company" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ds )H Software Distributor .\" .ds ]W Release B.10.1 .SH NAME swgettools \- Utility for retrieving the SD product from new SD media .PP .SH SYNOPSIS .C "swgettools -s" .IR \| .RC [ -t .IR \| ] .PP .SH DESCRIPTION .PP The .C swgettools command is used to install the SW-DIST product onto an existing system from new media. The .C swgettools command must first be loaded in a temporary directory on the host system from the new SD media using either .CR cp , .CR rcp , or .C tar depending on the format of the new SD media. .C swgettools is located on the media in the .I catalog/SW-DIST/pfiles directory. It is then invoked with the appropriate command line options to load the new SW-DIST product from the new SD media onto the host system. Once the new SW-DIST product is installed, it can be used to install the other software items from the new SD media. The .I -s option is used to identify the location of the media containing the SW-DIST product. The type of media is determined automatically by .C swgettools based on the location that is specified. The .I -t option specifies the temporary directory to use during the .C swgettools process. By default .I /var/tmp is used. .PP .SS Options The .C swgettools command supports the following options: .RS .TP 10 .CI -s \0 This argument is used to specify the source media location. Possible locations are: a local directory that is an SD depot, a character-special tape device file connected to a tape drive that has an SD media tape loaded, a CD-ROM mount point that has an SD media CD-ROM loaded, or a remote machine and depot combination. All paths used in the .I argument must be absolute paths. If .I is a remote machine and depot combination, the remote machine should be specified first, followed by the absolute path to the remote depot, separated by a colon with no spaces; for example: .I swperf:/var/spool/sw .TP .CI -t \0 The .I is the temporary directory to use during the .C swgettools process. An absolute pathname is required. By default .I /var/tmp is used. The temporary directory must exist. .RE .PP .SH RETURN VALUES .PP The .C swgettools command returns: .RS .TP 4 .C 0 Successful completion .PD 0 .TP .C 1 Usage incorrect .PD 0 .TP .C 2 Error during execution .PD .RE .PP .SH EXAMPLES .PP To install the new SW-DIST product from CD-ROM media at .I /mnt/cdrom_depot .IP .C "cp /mnt/cdrom_depot/catalog/SW-DIST/pfiles/swgettools /var/tmp" .br .C "/var/tmp/swgettools -s /mnt/cdrom_depot" .br .PP To install the new SW-DIST product from tape media at .I /dev/rmt/0m .IP .C "cd /var/tmp" .br .C "tar -xvf /dev/rmt/0m catalog/SW-DIST/pfiles/swgettools" .br .C "cp /var/tmp/catalog/SW-DIST/pfiles/swgettools /var/tmp/swgettools" .br .C "rm -rf /var/tmp/catalog" .br .C "/var/tmp/swgettools -s /dev/rmt/0m" .PP To install the new SW-DIST from a remote depot on .I swperf at .I /var/spool/sw .IP .C "rcp swperf:/var/spool/sw/catalog/SW-DIST/pfiles/swgettools /var/tmp" .br .C "/var/tmp/swgettools -s swperf:/var/spool/sw" .PP .SH AUTHOR .PP .C swgettools was developed by the Hewlett-Packard Company. .PP .SH SEE ALSO .PP sd(4), sd(5), swacl(1M), swagentd(1M), swcluster(1M), swconfig(1M), swcopy(1M), swinstall(1M), swjob(1M), swlist(1M), swmodify(1M), swpackage(1M), swpackage(4), swreg(1M), swremove(1M), swverify(1M), update(1M), and the .IR "HP OpenView Software Distributor Administrator's Guide" and .IR "Managing HP-UX Software with SD-UX" manuals. .\" toc@\f3swgettools(1M)\f1:\0\0\f4swgettools\f1@@@utility for retrieving the SD product from new SD media .\" index@\f4swgettools\f1 \- utility for retrieving the SD product from new SD media@@@\f3swgettools(1M)\f1 .\" index@\f1retrieve SD product from new SD media@@@\f3swgettools(1M)\f1 .\" index@\f1SD product from new SD media@@@\f3swgettools(1M)\f1 .\" .\" $Header: swinstall.1m,v 78.2 96/05/09 12:33:24 ssa Exp $ .\" -*-Nroff-*- .\" $Header: swinstall.1m,v 78.2 96/05/09 12:33:24 ssa Exp $ .\" .ds RZ \&HP CONFIDENTIAL .\" .ds RL Release B.10.0x .\" .ds MT Software Distributor B.10.0x .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro, e.g. .CR, .RI, .\" etc. A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .\" .ds PN Release B.10.0x .TA s .TH swinstall 1M " " "Hewlett-Packard Company" swcopy(1M) .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ds )H Software Distributor .\" .ds ]W Release B.10.0x .SH NAME swinstall \- Install and configure software products .PP swcopy \- Copy software products for subsequent installation or distribution .SH SYNOPSIS .C swinstall .RI [ "XToolkit Options" ] .RC [ -i ] .RC [ -p ] .RC [ -v ] .RC [ -r ] .RC [ -s .IR source\| ] .RC [ -x .IR option=value\| ] .RC [ -X\| .IR option_file\| ] .br .RC [ -f\| .IR software_file\| ] .RC [ -t\| .IR target_file\| ] .RC [ -C .IR session_file\| ] .RC [ -S\| .IR session_file\| ] .RC [ -Q\| .IR date\| ] .RC [ -J\| .IR jobid\| ] .br .RI [ software_selections ]\0[\c \*(at .IR \0target_selections ] .PP .C swcopy .RI [ "XToolkit Options" ] .RC [ -i ] .RC [ -p ] .RC [ -v ] .RC [ -s .IR source\| ] .RC [ -x .IR option=value\| ] .RC [ -X\| .IR option_file\| ] .br .RC [ -f\| .IR software_file\| ] .RC [ -t\| .IR target_file\| ] .RC [ -C\| .IR session_file\| ] .RC [ -S\| .IR session_file\| ] .RC [ -Q\| .IR date\| ] .RC [ -J\| .IR jobid\| ] .br .RI [ software_selections ]\0[\c \*(at .IR \0target_selections ] .PP .SS Remarks: SD-UX commands are included with the HP-UX Operating System and manage software on the .I local host only. To install and manage software simultaneously on multiple .I remote hosts (including PCs) from a central controller, you must purchase the .B "HP OpenView Software Distributor" (HP Prod. No. B1996AA) which provides extended software management, multi-site software distribution capabilities and distribution to PCs. While most of the information in this manual page applies to both SD-UX commands and the OpenView product, some applies .B only to the OpenView product. Where this is the case, you will see: .RS .IP .IR "The following xxx applies only to HP OpenView Software Distributor" .RE .PP .SH DESCRIPTION The .C swinstall command installs the .I software_selections from a software .I source to either the local host or, in the case of the HP OpenView Software Distributor product, to one or more .I target_selections (root filesystems). By default, the software is configured for use on the target after it is installed. (The software is not configured when installed into an alternate root directory.) .PP The SD .C swcluster command is used when installing software to an HP-UX NFS (Network File System) diskless cluster. See the .C "NFS Diskless Concepts and Administration" whitepaper (found in .IR /usr/share/doc ) and the .C swcluster(1) manpage for more information on network file system concepts and installing to diskless servers. .PP The .C swcopy command copies or merges .I software_selections from a software .I source to one or more .I target_selections (software depots). These depots can then be accessed as a software source by the .C swinstall command. .PP .RS .IP .IR "The following paragraph applies only to HP OpenView Software Distributor" .RE .PP .\" PC description For PC software installation, the .C swinstall command first copies or merges .I software_selections from a software .I source to one or more PC .I target_selections (PC Controllers). Each PC Controller is a fanout server, providing the .I software_selections (copied to it) to PC targets. At each PC target an SD PC agent process performs the actual installation. .PP The key difference between .C swinstall and .C swcopy is that .C swinstall installs software for actual (or eventual) use, while .C swcopy copies software into a depot, making it then available as a source for installation by .CR swinstall . .P NOTE: To copy to a tape, see the .C swpackage(1M) manpage. .PP Other features (differences) include: .RS .TP 2 \(bu The .C swinstall command executes several vendor-supplied scripts during the installation and configuration of the .IR software_selections . The .C swcopy command does not execute these scripts. The .C swinstall command supports the following scripts: .RS .TP .CR checkinstall a script executed during the analysis of a .CR target_selection , it checks that the installation can be attempted. If this check fails, the software product will not be installed. .TP .CR preinstall a script executed immediately before the software's files are installed. .TP .CR postinstall a script executed immediately after the software's files are installed. .TP .CR configure a script executed during the configuration of a .IR target_selection , it configures the target for the software (and the software for the target). The .C preinstall and .C postinstall scripts are not intended to be used for configuration tasks. They are to be used for simple file management needs such as removing obsolete files from the previous revision (which was just updated). .TP .CR unpreinstall a script executed immediately after the software's actual files are restored if the software install will fail and the .C autorecover_product option is set to .CR true . The script undoes the steps performed by .C preinstall script. .TP .CR unpostinstall a script executed immediately before the software's actual files are restored if the software install failed and the .C autorecover_product option is set to .CR true . The script undoes the steps performed by .C postinstall script. .RE .TP \(bu When a depot is created or modified using .CR swcopy , .IR "catalog files" are built that describe the depot (as opposed to the .IR "Installed Products Database" (IPD) files that are built by the .C swinstall command). .TP \(bu By default, the .C swinstall command only allows the selection of compatible software from the .IR source . This constraint ensures that the architecture of the software matches that of the .IR target_selections . No compatibility checks are performed by the .C swcopy command, unless explicitly requested by the user. (A depot can be a repository of software targeted for a variety of architectures and operating systems.) .TP \(bu By default, .C swinstall supports updates to higher revisions of software. If a .IR software_selection of the same revision is already installed, .C swinstall will not reinstall it. If a .IR software_selection has a lower revision than the same software which is already installed, .C swinstall will not reinstall it. (The user can override these behaviors with control options.) .TP \(bu The .C swinstall command creates hard links and symbolic links as specified for the software. If it encounters a symbolic link where it expected a regular file, .C swinstall follows the symbolic link and updates the file to which it points. .TP \(bu The .C swinstall command does not remove a product's current files before installing the new ones. A fileset's install scripts can perform this operation (if necessary). Files being replaced are overwritten where possible, or they are temporarily saved (to # ) if the .IR autorecover_product option is set to .CR true ; those that can not be overwritten are moved aside (to # ). .TP \(bu The .C swinstall command supports kernel building scripts and rebooting. Before or after software which modifies the kernel is installed (or updated), .C swinstall will execute system-specific scripts to prepare for or build the new version of the kernel. The remaining .IR software_selections are then installed. These scripts are defined in .C swagent options and include: .CR install_setup_cmd , .CR system_prep_cmd , .CR kernel_build_cmd , and .CR install_cleanup_cmd . .IP After software which requires a system reboot is installed (or updated), .C swinstall will automatically reboot the system. The reboot command is defined by the .C swagent option: .CR reboot_cmd . .IP When updating the operating system to a new revision, installing kernel software first ensures that a new kernel can be generated before the rest of the operating system is updated. After all the .I software_selections are updated (or installed), .C swinstall reboots using the new kernel, then executes the configure scripts for each .IR software_selection . After these scripts complete, it reboots the system again to restore it to its normal state. .TP \(bu No kernel building or system reboots are performed by .CR swcopy . .TP \(bu Both the .C swinstall and .C swcopy commands perform various checks prior to installing/copying the .IR software_selections , for example disc space analysis. .RE .bp .PP .SS Options .C swinstall and .C swcopy support the following options: .RS .TP 15 .IR "XToolKit Options" The .CR swinstall and .CR swcopy commands support a subset of the standard X Toolkit options to control the appearance of the GUI. The supported options are: .CR -bg , .CR -background , .CR -fg , .CR -foreground , .CR -display , .CR -name , .CR -xrm , and .CR -synchronous . See the .C X(1) manual page for a definition of these options. .TP .C -p Previews an install task by running the session through the analysis phase only. .TP .C -i Runs the command in interactive mode (invokes the Graphical User Interface). [Note: The Graphical User Interface is not supported on SunOS]. The SD-UX .CR swinstall , .CR swcopy , and .C swremove commands also support an interactive terminal user interface (text based) in which screen navigation is done with the keyboard (no mouse). .TP .C -l Runs the command in .I linkinstall mode which makes software installed under a server's .IR "shared root" available to a diskless client's .IR "private root" . .IP When run in the .IR linkinstall mode, .CR swinstall : .RS .TP 3 \(bu Creates NFS mounts to the software to make it accessible from the target. This may involve delayed mounting for alternate roots. .TP \(bu Modifies the target's .IR fstab file. .TP \(bu Modifies the source's .C exports file to add mount permission for the target. .RE .IP Mounts are created by examining the .IR share_link product attribute. Not all products support .CR linkinstall . Some products may be visible without creating a new mount if they reside under an old one. The .C -l option is used by the .C swcluster command in installing to diskless clusters. .TP .C -r Causes .C swinstall to install software into alternate root directories (e.g. root filesystems other than .CR / ). As of HP-UX release 10.2*, .CR -r is optional but is allowed to maintain compatibility with previous versions. .TP .C -v Turns on verbose output to stdout. (The .C swinstall or .C swcopy logfile is not affected by this option.) Verbose output is enabled by default, see the .C verbose option below. .TP .CI -s \0source Specifies the source depot (or tape) from which software will be installed or copied. The default source type is .IR directory. .TP .CI -x \0option=value Set the session .I option to .I value and override the default value (or a value in an alternate .IR option_file specified with the .C -X option). Multiple .C -x options can be specified. .TP .CI -X \0option_file Read the session options and behaviors from .IR option_file . .TP .CI -f \0software_file Read the list of .I software_selections from .I software_file instead of (or in addition to) the command line. .TP .CI -t \0target_file Read the list of .I target_selections from .I target_file instead of (or in addition to) the command line. Installing to multiple remote targets is available only via the HP OpenView Software Distributor product (HP Prod. No. B1996AA) which provides extended software management plus multi-site software distribution capabilities. .TP .CI -C \0session_file Save the current options and operands to .IR session_file . You can enter a relative or absolute path with the file name. The default directory for session files is .CR /.sw/sessions/ . You can recall a session file with the .C -S option. .TP .CI -S \0session_file Execute .C swinstall or .C swcopy based on the options and operands saved from a previous session, as defined in .IR session_file . You can save session information from a command-line session with the .C -C .I session_file option. .P .RS .IP .IR "The -Q and -J options apply only to HP OpenView Software Distributor" .RE .TP 15 .CI -Q \0date Schedules the job for this date. The date's format can be changed by modifying the file .CR /var/adm/sw/getdate.templ . .TP .CI -J \0jobid Executes the previously scheduled job. This is the syntax used by the daemon to start the job. .RE .PP .SS Operands .PP The .C swinstall and .C swcopy commands support the following syntax for each .IR software_selection : .IP .C bundle[.product[.subproduct][.fileset]][,version] .P or .IP .C product[.subproduct][.fileset][,version] .P The .C version component has the form: .IP .C [,r .IR .C revision][,a .IR .C arch][,v .IR .C vendor][,c .IR .C category] .P or .IP .C [instance_id] .P where .IR can be: *, ==, >=, <=, <, >, or != which performs individual comparisons on dot-separated fields. For example, r>=B.10.00 means choose all revisions that are greater than or equal to B.10.00. The system will compare each dot-separated field to find matches. Software will only be selected when matches within each field are satisfied. Wildcards are not allowed with these operators. .P The .C = (equals) relational operator is also allowed to specify a particular version component. .PP All version components are repeatable within a single specification (e.g. r>=A.12, r.log This is the default command log file for the .C swinstall and .C swcopy commands. For .CR swinstall , the default value is .CR /var/adm/sw/swinstall.log . For .CR swcopy , the default value is .CR /var/adm/sw/swcopy.log . .TP .C loglevel=1 Controls the log level for the events logged to the command logfile, and the target agent logfile. A value of .C 0 provides no information to the logfile. A value of .C 1 enables verbose logging to the logfiles. A value of .C 2 enables very verbose logging to the logfiles. .TP .C log_mesgid=0 Controls whether numeric identification numbers are prepended to logfile messages produced by SD. A value of 0 (default) indicates no such identifiers are attached. Values of 1-4 indicate that identifiers are attached to messages: .RS .TP 3 \(bu 1 applies to ERROR messages only .TP \(bu 2 applies to ERROR and WARNING messages .TP \(bu 3 applies to ERROR, WARNING, and NOTE messages .TP \(bu 4 applies to ERROR, WARNING, NOTE, and certain other logfile messages. .RE .TP .C layout_version=1.0 The object and attribute syntax of SD now conforms to the .C layout_version of 1.0 from the IEEE POSIX 1387.2 Software Administration standard. This options controls to which .C layout_version the SD commands write distributions and .C swlist output. Supported values are .C 0.8 and .CR 1.0 . The value of .C 1.0 should be used for future compatibility; the SD commands still accept the old keyword names as well as the new ones. The value of .C 0.8 should only be used to create distributions readable by older versions of SD. .\" .bp .TP .C match_target=false Applies only to .CR swinstall . If set to .CR true , other software selections are ignored and software selection is done by locating filesets on the source that match the target system's installed filesets. If multiple targets are specified, the first in the list is used as the basis for selections. .TP .C mount_all_filesystems=true Attempt to mount all filesystems in the .IR /etc/fstab file at the beginning of the analysis phase, to ensure that all listed filesystems are mounted before proceeding. This policy helps to ensure that files are not loaded into a directory that may be below a future mount point. .IP If set to .CR false , the mount operation is not attempted, and no check of the current mounts is performed. .TP .C polling_interval=2 Defines the polling interval, in seconds, used by the interactive GUI or TUI of the controller. It specifies how often each target agent will be polled to obtain status information about the task being performed. When operating across wide-area networks, the polling interval can be increased to reduce network overhead. .TP .C register_new_depot=true Applies only to .CR swcopy . Causes .C swcopy to register a newly created depot with the local .CR swagentd . This action allows other SD commands to automatically "see" this depot. If set to .CR false , a new depot will not be automatically registered. (It can be registered later with the .C swreg command.) .TP .C register_new_root=true Applies only to .CR swinstall . Causes alternate roots to be registered during .CR swinstall . These can be listed with .CR swlist . .TP .C reinstall=false When re-installing (or re-copying) an existing revision of a fileset, this option causes that fileset to be skipped, i.e. not re-installed. If set to .CR true , the fileset will be re-installed (re-copied). .TP .C reinstall_files=true Causes all the files in a fileset to always be reinstalled or recopied, even when the file already exists at the target and is identical to the new file. If set to .CR false , files that have the same .IR checksum (see next option), size and timestamp will not be re-installed. This check enhances performance on slow networks or slow discs. .TP .C reinstall_files_use_cksum=true This option affects the operation when the .CR reinstall_files option is set to false. It causes the checksums of the new and old file to be computed and compared to determine if the new file should replace the old one. (The checksum is slower, but is a more robust way to check for files being equivalent.) If set to .CR false , the checksums are not computed, and files are (not) reinstalled based only on their size and timestamp. .TP .C retry_rpc=0 For HP OpenView Software Distributor .CR retry_rpc=1 . Defines the number of times a lost source connection will be retried during file transfers in .CR swinstall or .CR swcopy . A lost connection is one that has timed out. When used in conjunction with the .C rpc_timeout option, the success of installing over slow or busy networks can be increased. If set to zero, then any .C rpc_timeout to the source will cause the task to abort. If set from 1 to 9, then the install of each fileset will be attempted that number of times. The .C reinstall_files option should also be set to false to avoid installing files within the fileset that were successfully installed. .TP .C rpc_binding_info=ncadg_ip_udp:[2121] Defines the protocol sequence and endpoint which will be used to contact .CR swagentd . HP-UX supports both the .IR udp .CR(ncadg_ip_udp:[2121] and .IR tcp .CR (ncacn_ip_tcp:[2121] protocol sequence/endpoint. This value should be consistent among all hosts that work together. See sd(5) for details on specifying this option. .TP .C rpc_timeout=7 For HP OpenView Software Distributor .CR rpc_timeout=5 . Relative length of the communications timeout. This is a value in the range from 0 to 9 and is interpreted by the DCE RPC. Higher values mean longer times; you may need a higher value for a slow or busy network. Lower values will give faster recognition on attempts to contact hosts that are not up, or are not running the .CR swagentd . Each value is approximately twice as long as the preceding value. A value of 5 is about 30 seconds for .CR ncadg_ip_udp . .TP .C select_local=true If no .IR target_selections are specified, select the default root directory .CR / .RC ( swinstall ), or the default .CR target_directory .RC ( swcopy ), at the local host as the target of the command. .TP .C software= Defines the default .IR software_selections . There is no supplied default. If there is more than software selection, they must be separated by spaces. .TP .C software_view=all_bundles For HP OpenView Software Distributor, the default is .CR products . Indicates the software view to be used by the SD-UX interactive interface of the commands. It can be set to .CR products , .CR all_bundles , or a bundle category tag (to indicate to show only bundles of that category). The default software view (bundles) will also show top level software (products and bundles). .TP .C source_cdrom=/SD_CDROM Defines the default location of the source CD-ROM. This syntax can be .CR host:path . .TP .C source_directory=/var/spool/sw Defines the default location of the source depot. This syntax can be .CR host:path . The .C -s option overrides this value. .TP .C source_tape=/dev/rmt/0m Defines the default location of the source tape, usually the character-special file of a local tape device. If the .CR host:path syntax is used, the host must match the local host. The .C -s option overrides this value. .TP .C source_type=directory Defines the default source type: .CR cdrom , .CR directory , or .CR tape . The source type derived from the .C -s option overrides this value. .TP .C target_directory=/var/spool/sw Applies only to .CR swcopy . Defines the default location of the target depot. .TP .C targets= Defines the default .IR target_selections . There is no supplied default (see .C select_local above). If there is more than target selection, they must be separated by spaces. .TP .C uncompress_files=false Applies only to .CR swcopy . If the files being transferred from a source are compressed, setting this option will uncompress the files before storing them on the target depot. .TP .C use_alternate_source=false Empowers each target agent to use its own, configured alternate source, instead of the one specified by the user. If .CR false , each target agent will use the same source, namely the source specified by the user and validated by the command. If .CR true , each target agent will instead use its own configured value for the source. .TP .C verbose=1 Controls the verbosity of the .C swinstall or .C swcopy output (stdout). A value of .C 0 disables output to stdout. (Error and warning messages are always written to stderr). A value of .C 1 enables verbose messaging to stdout. .TP .C write_remote_files=false Prevents the installation or copying of files to a target which exists on a remote (NFS) filesystem. All files destined for a remote filesystem will be skipped. .IP If set to .CR true and if the superuser has write permission on the remote filesystem, the remote files will not be skipped, but will be installed or copied. .RE .SS Session File .PP Each invocation of the .C swinstall or .C swcopy command defines an installation or copy session. The invocation options, source information, software selections, and target hosts are saved before the installation or copy task actually commences. This lets you re-execute the command even if the session ends before proper completion. .PP Each session is automatically saved to the file .I $HOME/.sw/sessions/swinstall{swcopy}.last. This file is overwritten by each invocation of .C swinstall or .CR swcopy . .PP You can also save session information from interactive or command-line sessions. From an interactive session, you can save session information into a file at any time by selecting the .I Save Session or .I Save Session As option from the .I File menu. From a command-line session, you can save session information by executing .C swinstall or .C swcopy with the .C -C .I session__file option. .PP A session file uses the same syntax as the defaults files. You can specify an absolute path for a session file. If you do not specify a directory, the default location for a session file is .I /.sw/sessions/ . .PP To re-execute a saved session from an interactive session, use the .I Recall Session option from the .I File menu. To re-execute a session from a command-line, specify the session file as the argument for the .C -S .I session__file option of .CR swinstall or .CR swcopy . .PP Note that when you re-execute a session file, the values in the session file take precedence over values in the system defaults file. Likewise, any command line options or parameters that you specify when you invoke .CR swinstall or .CR swcopy take precedence over the values in the session file. .PP .SS Software and Target Lists .PP The .C swinstall and .C swcopy commands support software and target selections from separate input files (see the .C -f and .C -t options). Software and targets specified in these files will be selected for operation. .P Additionally, the interactive interface for these commands read a list of possible hosts to operate on from the values found in: .IP .C /var/adm/sw/defaults.hosts - the system-wide default list of hosts, .IP .C $HOME/.sw/defaults.hosts - the user-specific default list of hosts. .P Hosts in this file will not be marked for operation, but provide a default list from which to choose. For each interactive command, target hosts containing roots, containing depots, and hosts serving as PC controllers are specified in separate lists ( .CR hosts , .CR hosts_with_depots , and .C pc_controllers respectively). The list of hosts are enclosed in {} braces and separated by white space (blank, tab and newline). For example: .RS .TP 4 .C swinstall.hosts={hostA hostB hostC hostD .PD 0 .TP .C hostE hostF} .TP .C swinstall.pc_controllers={pc1 pc2} (HP OpenView Software Distributor only) .TP .C swcopy.hosts_with_depots={hostS} .TP .C swcopy.pc_controllers={pc1 pc2} (HP OpenView Software Distributor only) .PD .RE .P .RS .IP .IR "The following paragraph applies only to HP OpenView Software Distributor" .RE .PP For PC software installation, the interactive interface generates PC target lists by querying the PC Controller (and it's associated fileserver). All users, groups, and machines returned from this query will be included in the default list from which to choose. Additionally, all machines returned from this query will by default be selected for installation when the user selects a PC Controller. .bp .PP .SS Environment Variables .PP The .C swinstall program sets these environment variables for use by the software control scripts being executed: .PP .C LANG .IP Determines the language in which messages are displayed. If LANG is not specified or is set to the empty string, a default value of .C C is used. See .C lang(5) for more information. .IP NOTE: The language in which the SD agent and daemon log messages are displayed is set by the system configuration variable script, .CR /etc/rc.config.d/LANG . For example, .CR /etc/rc.config.d/LANG , must be set to .CR LANG=ja_JP.SJIS or .CR LANG=ja_JP.eucJP to make the agent and daemon log messages display in Japanese. .PP .C SW_CONTROL_DIRECTORY .IP Defines the current directory of the script being executed, either a temporary catalog directory, or a directory within in the Installed Products Database (IPD). This variable tells scripts where other control scripts for the software are located (e.g. subscripts). .PP .C SW_DEFERRED_KERNBLD .IP This variable is normally unset. If it is set, the actions necessary for preparing the system file .CR /stand/system cannot be accomplished from within the .IR postinstall scripts, but instead must be accomplished by the .IR configure scripts . This occurs whenever software is installed to a directory other than .IR / , such as for a cluster client system. This variable should be read only by the .IR configure and .IR postinstall scripts of a kernel fileset. The .CR swinstall command sets these environment variables for use by the kernel preparation and build scripts. .PP .C SW_INITIAL_INSTALL .IP This variable is normally unset. If it is set, the .C swinstall session is being run as the back end of an initial system software installation ("cold" install). .PP .C SW_KERNEL_PATH .IP The path to the kernel. The default value is .CR /stand/vmunix , defined by the .CR swagent option or .CR kernel_path . .PP .C SW_LOCATION .IP Defines the location of the product, which may have been changed from the default product directory. When combined with the .CR SW_ROOT_DIRECTORY , this variable tells scripts where the product files are located. .PP .C SW_PATH .IP A PATH variable which defines a minimum set of commands available to for use in a control script (e.g. .CR /sbin:/usr/bin ). .PP .C SW_ROOT_DIRECTORY .IP Defines the root directory in which the session is operating, either "/" or an alternate root directory. This variable tells control scripts the root directory in which the products are installed. A script must use this directory as a prefix to SW_LOCATION to locate the product's installed files. The configure script is only run when SW_ROOT_DIRECTORY is "/". .PP .C SW_SESSION_IS_KERNEL .IP Indicates whether a kernel build is scheduled for a kernel fileset selected for installation. This variable is exported to a fileset's control scripts and must be tested by .I preremove scripts to determine whether any additions must be performed by the fileset's .I postinstall script at install time. .IP A .C "TRUE" value indicates that the selected kernel fileset is scheduled for a kernel build and that changes to .I /stand/system are required. A null value, indicates that a kernel build is not scheduled and that changes to .I /stand/system is not required. .IP The value of this variable is always equal to the value of .CR SW_SESSION_IS_REBOOT . .PP .C SW_SESSION_IS_REBOOT .IP Indicates whether a reboot is scheduled for a fileset selected for installation. Because all HP-UX kernel filesets are also reboot filesets, the values of this variables is always equal to the value of .CR SW_SESSION_IS_KERNEL . .PP .C SW_SOFTWARE_SPEC .IP This variable contains the fully qualified software specification of the current product or fileset. The software specification allows the product or fileset to be uniquely identified. .PP .C SW_SYSTEM_FILE_PATH .IP The path to the kernel's system file. The default value is .CR /stand/system . .PP .SS Signals The .C swinstall and .C swcopy commands catch the signals SIGQUIT and SIGINT. If these signals are received, the command prints a message, sends a Remote Procedure Call (RPC) to the agents to wrap up, and then exits. .P Each agent will complete the install/copy task (if the execution phase has already started) before it wraps up. This avoids leaving software in a corrupt state. .PP .SS Locking .PP SD commands use a common locking mechanism for reading and modifying both the Installed Products Database (IPD) and software depots. This mechanism allows multiple readers but only one writer on an IPD or depot: .PP .BR "Write Locks" .IP .C swinstall commands that modify the IPD are restricted from simultaneous modification using .IR fcntl (2) locking on the file .IP .C /swlock .IP (e.g. .CR /var/adm/sw/products/swlock ). .PP .BR "Depot Modification Locks" .IP .C swcopy commands that modify a software depot are also restricted from simultaneous modification using .IR fcntl (2) locking on the file .IP .C /catalog/swlock .IP (e.g. .CR /var/spool/sw/catalog/swlock ). .PP .BR "Read Locks" .IP Both .C swinstall and .C swcopy commands set .C fcntl(2) read locks on either IPDs or depots using the .C swlock file mentioned above. When a read lock is set, it prevents all SDU commands from performing modifications (i.e. from setting write locks). Specifically, with .C swinstall and .CR swcopy , the source depot is read locked for the duration of the command session. If a read lock cannot be set, the depot/media cannot be used as the software source. .IP During the analysis phase of .CR swinstall , the IPD is read locked while obtaining information about the installed products. If a read lock cannot be set, the analysis fails. .PP .RS .TP 15 .IR "The Terminal User Interface (TUI) is only supported on SD-UX" .RE .SS VT320 Terminal Support Because the VT320 terminal has predefined local functions for keys labeled as F1, F2, F3 and F4, users should use following mapping when they desire to use function keys: .PP .RS .TP 20 HP or Wyse60 VT320 or HP 700/60 in VT320 mode .TP F1 PF2 .CR " !" .TP F2 PF1 .CR " !" .TP F3 space bar .TP F4 PF3 .CR " !" .TP F5 F10, [ EXIT ], F5 .CR " *" .TP F6 none .TP F7 F18, first unlabeled key to right of Pause/Break* .TP F8 F19, second unlabeled key to right of Pause/Break* .TP 5 .CR "*" - When using PC-AT keyboard with HP 700/60 in VT320 mode .TP .CR "!" - See "Configuration: HP 700/60 in DEC mode, or DEC terminals with PC-AT type keyboard" .RE .RS .PP Further, since DEC terminals do not support softkey menu, no such menu is displayed on these terminals. .PP Many applications tend to use TAB for forward navigation (moving from one field to another) and shift-TAB is used for backward navigation. Users having DEC terminals or using terminals in DEC emulation modes such as VT100 or VT320 may note that these terminals/emulators may give out same character for TAB and shift-TAB. As such, it is impossible for an application to distinguish between TAB and shift-TAB, and both of them treated as if a TAB key was pressed. It might present slight overhead to users in case they want to go backwards. Now instead, they should complete rest of the inputs and get back to the desired field later. .PP .SS VT100 Terminal Support VT100 does not allow the (f1-f8) function keys to be configured. Therefore, the following keyboard mappings will apply to VT100 terminals: .RS .TP 20 HP or Wyse60 VT100 or HP 700/60 in VT100 mode .TP F1 PF2 .CR " !" .TP F2 PF1 .CR " !" .TP F3 space bar .TP F4 [PF3], [space bar] or [PF3], [=] .CR " !" .TP F5 return .TP F6 none .TP F7 none .TP F8 none .TP 5 .CR "!" - See "Configuration: HP 700/60 in DEC mode, or DEC terminals with PC-AT type keyboard" .RE .RS .PP Further, since DEC terminals do not support softkey menu, no such menu is displayed on these terminals. .PP Many applications tend to use TAB for forward navigation (moving from one field to another) and shift-TAB is used for backward navigation. Users having DEC terminals or using terminals in DEC emulation modes such as VT100 or VT320 may note that these terminals/emulators may give out same character for TAB and shift-TAB. As such, it is impossible for an application to distinguish between TAB and shift-TAB, and both of them treated as if a TAB key was pressed. It might present slight overhead to users in case they want to go backwards. Instead, they should complete rest of the inputs and get back to the desired field later. .PP .SS "Configuration: HP 700/60 terminal in DEC mode, or DEC terminal with PC-AT type keyboard" .PP Customers using the following configuration may want to be aware of the following keyboard difference. .PP It may be possible for a user with the "HP 700/60 terminal in DEC mode, or DEC terminal with PC-AT type keyboard" configuration to be told to press function key F1 through F4 to achieve some desired result. For HP 700/60 terminal in DEC mode or DEC terminals, these functions keys may be mapped onto PF1-PF4 keys. (see "Keyboard Mappings"). However, the PC-AT type keyboard does not provide PF1, PF2, PF3, or PF4 keys, as does the DEC/ANSI keyboard. .PP .B "Keyboard Mappings" .PP .RS .TP 20 "Num Lock" maps to "PF1" .TP "/" maps to "PF2" .TP "*" maps to "PF3" .TP "-" maps to "PF4" .RE .RS The "Num Lock", "/", "*", and "-" keys are located on the keyboard, in a row, above the number pad on the right side of the keyboard. Please note that although this keyboard is called a PC-AT type keyboard, it is supplied by HP. A PC-AT type keyboard can be recognized by location of ESC key at the left-top of the keyboard. .SS "Wyse60 Terminal Support" .PP On Wyse60, use DEL (located next to Backspace) key to backspace. On an HP 700/60 with a PC-AT type keyboard in Wyse60 mode, the DEL key is located in the bottom row on the number pad. .PP Wyse60 terminals provide a single line to display softkey labels unlike HP terminals which provide two lines. Sometimes this may result in truncated softkey labels. For example, "Help on Context" label for F1 may appear as "Help on C". Some standard labels for screen-oriented applications such as SAM and swinstall are as follows: .PP .RS .TP 35 On wyse60 may appear as .. means .TP Help On C Help On Context .TP Select/D Select/Deselect .TP Menubar Menubar on/off .RE .PP .SH RETURN VALUES .PP An interactive .C swinstall or .C swcopy session always returns 0. A non-interactive .C swinstall or .C swcopy session returns: .RS .TP 4 .C 0 The .I software_selections were successfully installed/copied. .PD 0 .TP .C 1 The install/copy operation failed on all .IR target_selections . .TP .C 2 The install/copy operation failed on some .IR target_selections . .PD .RE .PP .SH DIAGNOSTICS .PP The .C swinstall and .C swcopy commands write to stdout, stderr, and to specific logfiles. .PP .SS Standard Output .PP An interactive .C swinstall or .C swcopy session does not write to stdout. A non-interactive .C swinstall or .C swcopy session writes messages for significant events. These include: .RS .TP 2 \(bu a begin and end session message, .PD 0 .TP \(bu selection, analysis, and execution task messages for each .IR target_selection . .PD .RE .PP .SS Standard Error .PP An interactive .C swinstall or .C swcopy session does not write to stderr. A non-interactive .C swinstall or .C swcopy session writes messages for all WARNING and ERROR conditions to stderr. .PP .SS Logging .PP Both interactive and non-interactive .C swinstall and .C swcopy sessions log summary events at the host where the command was invoked. They log detailed events to the .C swagent logfile associated with each .IR target_selection . .PP .TP Command Log .br The .C swinstall and .C swcopy commands log all stdout and stderr messages to the the logfile .IR /var/adm/sw/swinstall.log .RI ( /var/adm/sw/swcopy.log ). Similar messages are logged by an interactive .C swinstall and .C swcopy session. (The user can specify a different logfile by modifying the .C logfile option.) .TP Target Log .br A .C swagent process performs the actual install/copy operation at each .IR target_selection . For install tasks, the .C swagent logs messages to the file .I var/adm/sw/swagent.log beneath the root directory (e.g. .C / or an alternate root directory). For copy tasks, the .C swagent logs messages to the file .I swagent.log beneath the depot directory (e.g. .CR /var/spool/sw ). .\".PP .\"When operating on a readonly or serial distribution object (for example, a .\"CD-ROM located at /mnt/cd or a tape media .\"located at /dev/rmt/0m) the logfile .\".C /swagent.log .\"cannot be used. If the agent cannot write to this logfile, then it logs .\"to .\".IR /tmp/swagent.log. .PP .RS .IP .IR "The following line applies only to HP OpenView Software Distributor" .RE .PP Command and target log files can be viewed using the .C swjob command. .PP .SH EXAMPLES .PP .SS swinstall .PP To invoke an interactive session of .CR swinstall : .IP .C "swinstall" .PP Select the C and Pascal products from the network source software server (sw_server) and start an interactive session: .IP .C "swinstall -i -s sw_server cc pascal" .PP .RS .IP .IR "The following example applies only to HP OpenView Software Distributor" .RE .PP Install the C and Pascal products to a set of remote hosts: .IP .C "swinstall -s sw_server cc pascal" \*(at .C " hostA hostB hostC" .PP Update the HP Omniback product from a CD-ROM mounted at /cd : .IP .C "swinstall -s /cd/swmedia Omniback" .PP Install an incompatible version of HP Omniback into the directory .IR /exports: .IP .C "swinstall -x allow_incompatible=true -s/products Omniback,a=arch" \*(at .C " /exports" .PP Install all products from the cartridge tape .IR /dev/rmt/0: .IP .C "swinstall -s /dev/rmt/0 \e*" .PP Reinstall the .I software_selections listed in the file .C /tmp/install.products on the hosts listed in the file .C tmp/install.hosts: .IP .C "swinstall -x reinstall=true -f/tmp/install.products -t/tmp/install.hosts" .PP Execute .C swinstall interactively using the session file .C /tmp/case.selections as a basis: .IP .C "swinstall -i -S /tmp/case.selections" .PP To .IR linkinstall the product TEST to the clients .C "clientA, clientB" from the server: .IP .C "swinstall -l -r -s :OS_700 TEST" \*(at .C "clientA clientB" .PP To .IR linkinstall product TEST2 to your own "/" directory from an application server on "serve": .IP .C "swinstall -l -s serve TEST2" .PP .RS .IP .IR "The following example applies only to HP OpenView Software Distributor" .RE .PP Install the C product to a set of PC end targets: .IP .C "swinstall -s sw_serve cc @ pc_controller::PC1 pc_controller::PC2 To schedule the above installation to run at the indicated time: .IP .C "swinstall -Q 12/01,11:00 -s sw_serve cc @ pc_controller::PC1 pc_controller::PC2" .PP .SS swcopy .PP Invoke an interactive session of .CR swcopy : .IP .C "swcopy" .PP Invoke an interactive session, using default depot at hostX as the source: .IP .C "swcopy -i -s hostX" .PP Copy all products from the cartridge tape .C /dev/rmt/0m to the default depot on the local host: .IP .C "swcopy -s /dev/rmt/0m \e*" .PP Load the .I software_selections listed in the file .C /tmp/load.products using the default source/depot: .IP .C "swcopy -f /tmp/load.products" .PP .RS .IP .IR "The following example applies only to HP OpenView Software Distributor" .RE .PP Copy the C and Pascal products to some local and remote depots: .IP .C "swcopy -s sw_server cc pascal" \*(at .C " /var/spool/sw hostA:/tmp/sw hostB" .PP .\".SH WARNINGS .\".PP .\".PP .\".SH DEPENDENCIES .PP .SH LIMITATIONS .PP .\" The SunOS and SD-UX versions of .C swinstall and .C swcopy do not support the installation and configuration of software products on remote targets. .PP The SunOS version of .C swinstall and .C swcopy does not provide a graphical user interface to install and configure software products. .PP .RS .IP .IR "The following PC information applies only to HP OpenView Software Distributor" .RE .PP When copying software to a PC Controller, the .C swcopy command only supports a single PC depot (configured on the PC Controller). .PP For PC software installation, the .C swinstall command first copies software to the PC depot, where it is then accessed by the SD PC agent at each PC target. Only options that apply to .C swcopy apply when installing PC software to the PC Controller. The following options are not supported: .IP .PD 0 .C -r .IP .C allow_downdate .IP .C allow_multiple_versions .IP .C enforce_scripts .IP .C enforce_kernbld_failure .IP .C defer_configure .IP .C register_new_root .PD .PP When packaging PC software using the PC Console, functionality similar to the following .C swinstall options can be set via the Job Settings dialog: .IP .PD 0 .C autorecover_product .IP .C autoreboot .IP .C retry_rpc .IP .C enforce_dsa .IP .C loglevel .PD .P In addition, the following .C swcopy options do not apply to PC Controllers: .IP .PD 0 .C autoselect_dependencies .IP .C enforce_dependencies .IP .C create_target_path .IP .C autoselect_reference_bundles .IP .C mount_all_filesystems .IP .C target_directory .IP .C use_alternate_source .IP .C write_remote_files .PD .PP .SH FILES .PP .\" .C /var/adm/sw/ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. This directory is also the default location of logfiles. .RE .\" .C /usr/lib/sw/sys.defaults .br .RS 8 Contains the master list of current SD options (with their default values). .RE .\" .C /var/adm/sw/defaults .br .RS 8 Contains the active system-wide default values for some or all SD options. .RE .\" .C $HOME/.sw/defaults .br .RS 8 Contains the user-specific default values for some or all SD options. .RE .\" .C /var/adm/sw/defaults.hosts .br .RS 8 Contains the system-wide default list of hosts to manage. .RE .\" .C $HOME/.sw/defaults.hosts .br .RS 8 Contains the user-specific default list of hosts to manage. .RE .\" .C /var/adm/sw/getdate.templ .br .RS 8 Contains the set of date/time templates used when scheduling jobs. .RE .\" .C $HOME/.sw/sessions/ .br .RS 8 Contains session files automatically saved by the SD commands, or explicitly saved by the user. .RE .\" .C /var/adm/sw/products/ .br .RS 8 The Installed Products Database (IPD), a catalog of all products installed on a system. .RE .\" .C /var/spool/sw/ .br .RS 8 The default location of a source and target software depot. .RE .RS .IP .IR "The following applies only to HP OpenView Software Distributor" .RE .PP .C /var/adm/sw/queue/ .br .RS 8 The directory which contains the information about all active and complete install jobs, copy jobs, and other jobs initiated by the SD commands. .RE .PP .SH PC FILES .PP .RE .RS .IP .IR "The following applies only to HP OpenView Software Distributor" .RE .PP .\" .C ...\\\\SD\\\\DATA\\\\ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. .RE .\" .C ...\\\\SD\\\\DATA\\\\DEPOT\\\\ .br .RS 8 The default location of a source and target PC depot. .RE .PP .SH AUTHOR .PP .C swinstall and .C swcopy were developed by the Hewlett-Packard Company. .PP .SH SEE ALSO .PP sd(4), sd(5), swacl(1M), swagentd(1M), swcluster(1M), swconfig(1M), swgettools(1M), swjob(1M), swlist(1M), swmodify(1M), swpackage(1M), swpackage(4), swreg(1M), swremove(1M), swverify(1M), update(1M), and the .IR "HP OpenView Software Distributor Administrator's Guide" or .IR "Managing HP-UX Software with SD-UX" manuals. .\" .\ ====================================================================== .\" index@\f4swinstall\f1 \- install and configure software products@@@\f3swinstall(1M)\f1 .\" index@\f4swcopy\f1 \- copy software products for subsequent installation or distribution@@@\f3swinstall(1M)\f1 .\" index@\f1software products, install, configure, and copy@@@\f3swinstall(1M)\f1 .\" index@\f1install, software products@@@\f3swinstall(1M)\f1 .\" index@\f1copy, software products@@@\f3swinstall(1M)\f1 .\" index@\f1configure, software products@@@\f3swinstall(1M)\f1 .\" .\" index@\f1terminals, VT320, VT100, Wyse60@@@\f3swinstall(1M)\f1 .\" index@\f1VT320 terminal@@@\f3swinstall(1M)\f1 .\" index@\f1VT100 terminal@@@\f3swinstall(1M)\f1 .\" index@\f1Wyse60 terminal@@@\f3swinstall(1M)\f1 .\" .\" toc@\f3swinstall(1M)\f1:\0\0\f4swcopy\f1, \f4swinstall\f1@@@install and configure software products, copy software products\f1 .\" toc@\f4swcopy\f1:\0\0copy software products for subsequent installation or distribution@@@\f1see \f3swinstall(1M)\f1 .\" .\" links@swinstall.1m swcopy.1m .\" .\" $Header: swjob.1m,v 78.2 96/05/09 12:33:56 ssa Exp $ .\" -*-Nroff-*- .\" $Header: swjob.1m,v 78.2 96/05/09 12:33:56 ssa Exp $ .\" .ds RZ \&HP CONFIDENTIAL .\" .ds RL Release B.10.0x .\" .ds MT Software Distributor B.10.0x .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro, e.g. .CR, .RI, .\" etc. A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .\" .ds PN Release B.10.0x .TA s .TH swjob 1M " " "Hewlett-Packard Company" sd(1M) .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ds )H Software Distributor .\" .ds ]W Release B.10.0x .SH NAME swjob \- Display job information and remove jobs. .PP sd \- Interactive interface for creating and monitoring jobs. .PP For a description of the HP OpenView Software Distributor objects, attributes and data formats, see the .C sd(4) manual page by typing: .PD 0 .IP .C "man 4 sd" .PD .PP For an overview of all HP OpenView Software Distributor commands, see the .C sd(5) manual page by typing: .PD 0 .IP .C "man 5 sd" .PD .PP .SH SYNOPSIS .C swjob .RC [ -i ] .RC [ -u ] .RC [ -v ] .RC [ -R ] .RC [ -a\| .IR attribute\| ] .RC [ -x\| .IR option=value\| ] .RC [ -X\| .IR option_file\| ] .RC [ -f\| .IR jobid_file\| ] .br .RC [ -t\| .IR target_file\| ] .RC [ -C\| .IR session_file\| ] .RC [ -S\| .IR session_file\| ] .RI \c .RI \0[ jobid(s) ] .RI [\c \*(at .IR \0target_selections\| ] .PP .C sd .RC [ -x\| .IR option=value\| ] .RC [ -X\| .IR option_file\| ] .PP .SS Remarks: .B "This command applies only to the HP OpenView Software Distributor" .B "product (HP Prod. No. B1996AA). It is not part of the SD-UX command" .B "set shipped with the HP-UX operating system." .PP .SH DESCRIPTION .PP The .C swjob command displays job information and removes jobs. It supports these features: .RS .TP 2 \(bu Display the current install jobs, copy jobs, and other SD jobs initiated by the SD commands. .TP \(bu Specify a specific job to list or remove. .TP \(bu Display the command logfile for a specific job. .TP \(bu Display the target logfile for a specific target. .RE .PP The .C sd command is used to invoke the interactive interface to create, monitor and remove job status and logs. It provides an interactive interface to the same functionality that .C swjob provides; in addition, it can be used to initiate new install, copy, and remove jobs. .PP .SS Options When no options or operands are specified, .C swjob lists the jobs that exist on the local host. These jobs may be pending, active, in the background or completed. The .C swjob command supports the following options: .RS .TP 15 .C -i Runs the command in interactive mode (invokes the Graphical User Interface). This invocation, "swjob -i", is an alias for the command "sd". [Note: The Graphical User Interface is not supported on SunOS]. .TP .C -u Causes .C swjob to remove the specified job(s). .TP .C -v Causes .C swjob to list all available attributes, one per line. The option applies only to the default list. .TP .C -R Applies to target lists as a shorthand for .CR "@*::*" . .TP .CI -a \0attribute Each job has its own set of attributes. These attributes include such things as job title, schedule date, or results. The .C -a option selects a specific attribute to display. You can specify multiple .C -a options to display multiple attributes. See also .C sd(4) for details on these attributes. This option applies only to the default list. The logfiles summarizing a job or detailing target actions can be displayed using .CR "-a log" , if .C -a log is specified and no other attribute is specified (i.e. no other attribute may be specified). .TP .CI -x \0option=value Set the session .I option to .I value and override the default value (or a value in an alternate .IR option_file specified with the .C -X option). Multiple .C -x options can be specified. .TP .CI -X \0option_file Read the session options and behaviors from .IR option_file . .TP .CI -f \0jobid_file Read the list of .I jobids from .I jobid_file instead of (or in addition to) the command line. .TP .CI -t \0target_file Read the list of .I target_selections from .I target_file instead of (or in addition to) the command line. .TP .CI -C \0session_file Save the current options and operands to .IR session_file . You can enter a relative or absolute path with the file name. The default directory for session files is .CR /.sw/sessions/ . You can recall a session file with the .C -S option. .TP .CI -S \0session_file Execute .C swjob based on the options and operands saved from a previous session, as defined in .IR session_file . You can save session information to a file with the .C -C option. .RE .PP .SS Operands .PP The .C swjob command supports the following syntax for each .IR jobid : .IP .C "jobid" .P The .C swjob command supports the following syntax for each .IR target_selection : .IP .C "[target]" .PP Additionally, the .C swjob command supports the syntax: .IP .C "[pc_controller][::][pc_target]" .PP This syntax only applies to PCs. The PC controller is a fanout server. The PC target may be a PC machine, user, or group name. Valid targets for a PC controller can be listed using .CR "swlist -l machine|user|group" . PC targets can be further qualified for whether they refer to a PC machine, user, or group type with the following syntax: .IP .CI name[,t= type ][,k= address ] .PP The .I type only needs to be specified if a name applies to both (more than one) of a .CR machine , .CR user , or .CR group . (The .I address is used internally for machines and is generally not needed on the command line.) The keyword .C * can be substituted for .CR pc_targets , specifying an operation to all target machines: .IP .C "@ pc_controller::*" .P The .C * cannot be used when retrieving logfiles using .CR "-a log" . .PP .SH EXTERNAL INFLUENCES .PP .SS Defaults File .PP In addition to the standard options, several .C swjob behaviors and policy options can be changed by editing the default values found in: .IP .C /var/adm/sw/defaults - the system-wide default values, .IP .C $HOME/.sw/defaults - the user-specific default values. .P Values must be specified in the defaults file using this syntax: .PP .IP .CI swjob. option = value .PP The default values can be overridden by specifying an options file with the .C -X option, or by specifying .CI -x\0 option = value on the command line. The policy options that apply to .C swjob are: .PP .RS .TP 10 .C agent_timeout_minutes=1440 Causes a target agent to exit if it has been inactive for the specified time. The default of 1440 (24 hours) applies only when the interactive UI is used. Usually, the command line controller resets this to 10 minutes. If you change this value to anything other than 1440, that value will be used even if the controller is using an interactive UI. When using command line invocation of HP OpenView Software Distributor with multiple targets and you have not changed this value from 1440, the value will be reset to 9 minutes plus the number of targets. .\" .bp .\" .TP .C force_job_removal=false By default, the master job is removed from the controller only after a removal of the job information stored on each of its targets succeeds. If the job should be removed regardless of the success of the removal of job information from its targets, set this option to .CR true . .TP .C one_liner={jobid operation state progress results title} Defines the attributes which will be listed for each job when no .C -a option is specified. Each attribute included in the .C one_liner definition is separated by or . Any attributes, except .C log may be included in the .C one_liner definition. If a particular attribute does not exist for an object, then that attribute is silently ignored. .TP .C poll_now=false The status information displayed for a job is as recent as the last time the daemon polled remote targets for information (the .C swinstall option .CR job_polling_interval ). If the most recent status is wanted set this option to .CR true . .TP .C remove_fanout_depot=true When a job is removed the depot software associated with that job is automatically removed. If the software that is part of this job is the same software being used by another job, then be sure to not delete the software as part of the job removal. If the depot software should be retained, set this option to .CR false . .TP .C rpc_binding_info=ncadg_ip_udp:[2121] Defines the protocol sequence and endpoint which will be used to contact .CR swagentd . This value should be consistent among all hosts that work together. See sd(5) for details on specifying this option. .TP .C rpc_timeout=5 Relative length of the communications timeout. This is a value in the range from 0 to 9 and is interpreted by the DCE RPC. Higher values mean longer times; you may need a higher value for a slow or busy network. Lower values will give faster recognition on attempts to contact hosts that are not up, or are not running the .CR swagentd . Each value is approximately twice as long as the preceding value. A value of 5 is about 30 seconds for .CR ncadg_ip_udp . .TP .C targets= Defines the default .IR target_selections . There is no supplied default. If there is more than one target selection, they must be separated by spaces. .TP .C verbose=0 Controls how attribute values are displayed. A value of .C 0 displays only the attribute value. A value of .C 1 displays both the attribute keyword and value. (See the .C -v option above.) .RE .PP .SS Session File .PP Each invocation of the .C swjob command defines a job display session. The invocation options, source information, software selections, and target hosts are saved before the installation or copy task actually commences. This lets you re-execute the command even if the session ends before proper completion. .PP Each session is automatically saved to the file .I $HOME/.sw/sessions/swinstall{swcopy}.last. This file is overwritten by each invocation of .CR swjob . .PP You can also save session information to a specific file by executing .C swjob with the .C -C .I session__file option. .PP A session file uses the same syntax as the defaults files. You can specify an absolute path for the session file. If you do not specify a directory, the default location for a session file is .IR "/.sw/sessions/" . .PP To re-execute a session file, specify the session file as the argument for the .C -S .I session__file option of .CR swjob . .PP Note that when you re-execute a session file, the values in the session file take precedence over values in the system defaults file. Likewise, any command line options or parameters that you specify when you invoke .CR swjob take precedence over the values in the session file. .PP .SS Environment Variables .PP The .C swjob command does not use environment variables. .PP .C LANG .IP Determines the language in which messages are displayed. If LANG is not specified or is set to the empty string, a default value of .C C is used. See .C lang(5) for more information. .IP NOTE: The language in which the SD agent and daemon log messages are displayed is set by the system configuration variable script, .CR /etc/rc.config.d/LANG . For example, .CR /etc/rc.config.d/LANG , must be set to .CR LANG=ja_JP.SJIS or .CR LANG=ja_JP.eucJP to make the agent and daemon log messages display in Japanese. .PP .SS Signals .PP The .C swjob command catches the signals SIGQUIT and SIGINT. If these signals are received, .C swjob prints a message, sends a Remote Procedure Call (RPC) to the daemons to wrap up, and then exits. .PP Each agent will complete the list task before it wraps up. .PP .SH OPERATION .PP Different views of the job information are available. The types of listings that can be selected are given below. .RS .TP 2 \(bu Default Listing .TP \(bu Target Listing .TP \(bu Logfile Listing .RE .PP .SS "Default Listing" .PP If .C swjob is invoked with no options or operands, it lists all jobs that are on the local host. This listing contains one line for each job. The line includes the job tag attribute and all other attributes selected via the .C one_liner option. .PP Listing jobs on a remote controller is not supported. If a .IR jobid is given, information for only that job is displayed. .PP .SS "Status Listing" .PP If a .IR -R or .I @ target_specification is given, the targets for that job and their status are displayed. By default the status information includes Type, State, Progress and Results. .PP .SS "Logfile Listing" .PP One of the attributes "log" encompasses a variety of logfile types. The type of logfile returned when the -a log attribute is given depends on the operands given. The types of logfiles: .PP .RS .TP 27 .C "No target_selections" Show the controller logfile (default). .TP .C "@ target" Show the agent or PC controller logfile. .TP .C "@ pc_controller::pc_target" Show the PC target logfile. .RE .RE .PP .SH RETURN VALUES .PP The .C swjob command returns: .RS .TP 4 .C 0 The job information was successfully listed or the job was successfully removed. .PD 0 .TP .C 1 The list /remove operation failed for all .IR jobids . .PD 0 .TP .C 2 The list /remove operation failed for some .IR jobids . .PD .RE .PP .SH DIAGNOSTICS .PP The .C swjob command writes to stdout, stderr, and to the agent logfile. .PP .SS Standard Output .PP All listings are printed to stdout. .PP .SS Standard Error .PP The .C swjob command writes messages for all WARNING and ERROR conditions to stderr. .\" .\" .\" .bp .\" .PP .SS Logging .PP The .C swjob command does not log summary events. It logs events about each read task to the .CR swagent logfile associated with each .IR target_selection . .PP .SH EXAMPLES .PP To list all of the jobs that exist on the local host: .IP .C "swjob" .P To show the scheduled date for job hostA-0001: .IP .C "swjob -a schedule hostA-0001" .P For job hostA-0001 list the targets and their status: .IP .C "swjob -R hostA-0001" or .C "swjob hostA-0001 @ *" .P For job hostA-0001 give the status for pc_controller1 and all its PC targets .IP .C "swjob hostA-0001 \*(at .C " pc_controller1"::*" .P For job hostA-0001 list the controller log: .IP .C "swjob -a log hostA-0001" .P For job hostA-0001 list the log for pc_controller1: .IP .C "swjob -a log hostA-0001" \*(at .C " pc_controller1" .P For job hostA-0001 list the log for PC target pc1 on pc_controller1: .IP .C "swjob -a log hostA-0001" \*(at .C " pc_controller1::pc1" .SH LIMITATIONS The .C swjob command only runs on HP-UX. Any .C PC controller target selections apply only to PCs. .PP .SH FILES .PP .\" .C /var/adm/sw/ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. This directory is also the default location of logfiles. .RE .\" .C /var/adm/sw/queue/ .br .RS 8 The directory which contains the information about all active and complete install jobs, copy jobs, and other jobs initiated by the SD commands. .RE .\" .C /usr/lib/sw/sys.defaults .br .RS 8 Contains the master list of current SD options (with their default values). .RE .\" .C /var/adm/sw/defaults .br .RS 8 Contains the active system-wide default values for some or all SD options. .RE .\" .C $HOME/.sw/defaults .br .RS 8 Contains the user-specific default values for some or all SD options. .RE .PP .SH PC FILES .PP .\" .C ...\\\\SD\\\\DATA\\\\ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. .RE .\" .C ...\\\\SD\\\\DATA\\\\QUEUE\\\\ .br .RS 8 The directory which contains the information about all active and complete install, remove, and other jobs at the PC Controller. .RE .PP .SH AUTHOR .PP .C swjob was developed by the Hewlett-Packard Company. .PP .SH SEE ALSO .PP sd(4), sd(5), swacl(1M), swagentd(1M), swcluster(1M), swconfig(1M), swcopy(1M), swgettools(1M), swinstall(1M), swlist(1M), swmodify(1M), swpackage(1M), swpackage(4), swreg(1M), swremove(1M), swverify(1M), update(1M), and the .IR "HP OpenView Software Distributor Administrator's Guide". .\" .\" toc@\f3swjob(1M)\f1:\0\0\f4swjob\f1, \f4sd\f1@@@display job information, remove jobs, create and monitor jobs .\" .\" toc@\f4sd\f1:\0\0create and monitor jobs@@@\f1see \f3swjob(1M)\f1 .\" .\" index@\f4swjob\f1 \- display job information and remove jobs@@@\f3swjob(1M)\f1 .\" index@\f4sd\f1 \- create and monitor jobs@@@\f3swjob(1M)\f1 .\" .\" index@\f1display job information and remove jobs@@@\f3swjob(1M)\f1 .\" index@\f1create and monitor jobs@@@\f3swjob(1M)\f1 .\" .\" links@swjob.1m sd.1m .\" $Header: swlist.1m,v 78.2 96/05/09 12:34:32 ssa Exp $ .\" -*-Nroff-*- .\" $Header: swlist.1m,v 78.2 96/05/09 12:34:32 ssa Exp $ .\" .ds RZ \&HP CONFIDENTIAL .\" .ds RL Release B.10.0x .\" .ds MT Software Distributor B.10.0x .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro, e.g. .CR, .RI, .\" etc. A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .\" .ds PN Release B.10.0x .TA s .TH swlist 1M " " "Hewlett-Packard Company" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ds )H Software Distributor .\" .ds ]W Release B.10.0x .SH NAME swlist \- Display information about software products .PP .SH SYNOPSIS .C swlist .RC [ -d | -r ] .RC [ -l .IR level ] .RC [ -v ] .RC [ -a\| .IR attribute\| ] .RC [ -R ] .RC [ -s\| .IR source\| ] .RC [ -x .IR option=value\| ] .RC [ -X\| .IR option_file\| ] .br .RC [ -f\| .IR software_file\| ] .RC [ -t\| .IR target_file\| ] .RC [ -C\| .IR session_file\| ] .RC [ -S\| .IR session_file\| ] .RI [ software_selections ]\0[\c \*(at .IR \0target_selections ] .PP .SS Remarks: SD-UX commands are included with the HP-UX Operating System and manage software on the .I local host only. To install and manage software simultaneously on multiple .I remote hosts (including PCs) from a central controller, you must purchase the .B "HP OpenView Software Distributor" (HP Prod. No. B1996AA) which provides extended software management, multi-site software distribution capabilities and distribution to PCs. While most of the information in this manual page applies to both SD-UX commands and the OpenView product, some applies .B only to the OpenView product. Where this is the case, you will see: .RS .IP .IR "The following xxx applies only to HP OpenView Software Distributor" .RE .PP .SH DESCRIPTION The .C swlist command displays information about software products installed at or available from the specified .IR target_selections . It supports these features: .PP .RS .TP 2 \(bu Specify bundles, products, subproducts, and/or filesets to list. .TP \(bu Display the files contained in each fileset. .TP \(bu Display a table of contents from a software source. .TP \(bu Specify the attributes to display for each software object. .TP \(bu Display all attributes for bundles, products, subproducts, filesets and/or files. .TP \(bu Display the structure of software selections. .\".TP .\"\(bu .\"List software by installation location (a multiple version or relocated .\"software. .TP \(bu Display the depots on a specified host. .TP \(bu Create a list of products, subproducts, and/or filesets to use as input to the .C swinstall or .C swremove commands. .RE .PP .SS Options When no options or operands are specified, .C swlist lists the software bundles (and products which are not part of a bundle) that are installed at the local host. .C swlist supports the following options: .RS .TP 5 .C -d List software available from a depot (instead of software installed on a root filesystem). .TP .C -r List products installed on an alternate root filesystem (instead of software installed on .CR / ). As of HP-UX release 10.2*, .CR -r is optional but is allowed to maintain compatibility with previous versions. .TP .CI -l \0level List all objects down to the specified .IR level . The supported levels are: .RS .IP .IR "The machine, user and group levels apply only to HP OpenView Software Distributor" .RE .PP .RS .TP 10 .C "machine" Show the .IR machines known to a PC controller. .TP .C "user" Show the .IR users known to a PC controller. .TP .C "group" Show the .IR groups known to a PC controller. .TP .C shroot List all registered shared roots. .TP .C prroot List all registered private roots. .TP .C root List all roots. .TP .C "depot" Show only the depot level (i.e. depots which exist at the specified target hosts). .TP .C "bundle" Show all objects down to the bundle level. .TP .C "product" Show all objects down to the product level (i.e. depots and products). .TP .C "subproduct" Show all objects down to the subproduct level (i.e. depots, products, and subproducts). .TP .C "fileset" Show all objects down to the fileset level (i.e. depots, products, and filesets). If subproducts are wanted, use "-l fileset -l subproduct". .TP .C "file" Show all objects down to the file level (i.e. depots, products, filesets, and files). If subproducts are wanted, use "-l file -l subproduct". .RE .IP Both the specified level(s) and the depth of the specified .IR software_selections control the depth of the .C swlist output. .TP 5 .C -v If no .C -a options are specified, then list all the attributes for an object, one attribute per line. The attributes are listed in the format: .RS .IP .C "keyword value" .RE .\"The .\"descriptive, state, and relational attributes are displayed for each .\"software selection (product, subproduct or fileset) or depot given. .IP If one or more .C -a options are specified, then list the selected attributes in the above format. .TP .CI -a \0attribute Each object has its own set of attributes. These attributes include such things as revision, description, vendor information, size, and many others. The .C -a option selects a specific .I attribute to display. You can specify multiple .C -a options to display multiple attributes. .IP Note that the .C tag attribute (i.e. the identifier) is always displayed for product, subproduct, and fileset objects. The .C path attribute (i.e. the filename) is always displayed for file objects. .IP The full set of attributes for a given software object can be obtained using the .C -v option. See also .IR sd (4) for details on these attributes. .TP .C -R Shorthand for .IR "-l bundle -l subproduct -l fileset" . .\".IP .\"An attribute containing a great amount of information .\"(e.g. a README) is physically .\"stored as a separate file. The attribute is not listed with all the other .\"software attributes when the verbose option is used but is .\"requested separately. .TP .CI -s \0source Specifies the software source to list. This is an alternate way to list a source depot. Sources can also be specified as target depots and listed using the .C -d option. .TP .CI -x \0option=value Set the session .I option to .I value and override the default value (or a value in an alternate .IR option_file specified with the .C -X option). Multiple .C -x options can be specified. .TP .CI -X \0option_file Read the session options and behaviors from .IR option_file . .TP .CI -f \0software_file Read the list of .I software_selections from .I software_file instead of (or in addition to) the command line. .TP .CI -t \0target_file Read the list of .I target_selections from .I target_file instead of (or in addition to) the command line. .TP .CI -C \0session_file Save the current options and operands to .IR session_file . You can enter a relative or absolute path with the file name. The default directory for session files is .CR /.sw/sessions/ . You can recall a session file with the .C -S option. .TP .CI -S \0session_file Execute .C swlist based on the options and operands saved from a previous session, as defined in .IR session_file . You can save session information to a file with the .C -C option. .bp .PP .SS Operands The .C swlist command supports the following syntax for each .IR software_selection : .IP .C bundle[.product[.subproduct][.fileset]][,version] .P or .IP .C product[.subproduct][.fileset][,version] .P The .C version component has the form: .IP .C [,r .IR .C revision][,a .IR .C arch][,v .IR .C vendor][,c .IR .C category] .P or .IP .C [instance_id] .P where .IR can be: ==, >=, <=, <, >, or != which performs individual comparisons on dot-separated fields. For example, r>=B.10.00 means choose all revisions that are greater than or equal to B.10.00. The system will compare each dot-separated field to find matches. Software will only be selected when matches within each field are satisfied. Wildcards are not allowed with these operators. .P The .C = (equals) relational operator is also allowed. It provides the shell pattern matching notations []*?! or wildcards to specify selections as opposed to comparing dot-separated fields. .P All version components are repeatable within a single specification (e.g. r>=A.12, r or . Any attributes may be included in the .C one_liner definition. If a particular attribute does not exist for an object, then that attribute is silently ignored. For example, the .CR description attribute is valid for products, subproducts, and filesets, but the .CR architecture attribute is only valid for products. .\".IP .\"In the absence of the .\".C -v .\"or .\".C -a .\"option, .\".C swlist .\"will display .\".IR one_liner .\"information for each software object .\"(products, subproducts, and filesets) but not file objects. .TP .C rpc_binding_info=ncadg_ip_udp:[2121] Defines the protocol sequence and endpoint which will be used to contact .CR swagentd . This value should be consistent among all hosts that work together. See sd(5) for details on specifying this option. .TP .C rpc_timeout=7 For HP OpenView Software Distributor .CR rpc_timeout=5 . Relative length of the communications timeout. This is a value in the range from 0 to 9 and is interpreted by the DCE RPC. Higher values mean longer times; you may need a higher value for a slow or busy network. Lower values will give faster recognition on attempts to contact hosts that are not up, or are not running the .CR swagentd . Each value is approximately twice as long as the preceding value. A value of 5 is about 30 seconds for .CR ncadg_ip_udp . .TP .C select_local=true If no .IR target_selections are specified, select the default root directory .CR / , or the default .CR target_directory (when the .C -d option is specified), at the local host as the target of the command. .TP .C software= Defines the default .IR software_selections . There is no supplied default. If there is more than software selection, they must be separated by spaces. .TP .C software_view=all_bundles For HP OpenView Software Distributor .CR software_view=products . Indicates the software view to be used as the default level for the software listing. It can be set to .CR products , .CR all_bundles , or a bundle category tag (to indicate to show only bundles of that category). .TP .C target_directory=/var/spool/sw Defines the default location of the target depot. .bp .TP .C targets= Defines the default .IR target_selections . There is no supplied default (see .C select_local above). If there is more than target selection, they must be separated by spaces. .TP .C verbose=0 Controls how attribute values are displayed. A value of .C 0 displays only the attribute value. A value of .C 1 displays both the attribute keyword and value. (See the .C -v option above.) .RE .PP .SS Session File .PP Each invocation of the .C swlist command defines a list session. The invocation options, source information, software selections, and target hosts are saved before the installation or copy task actually commences. This lets you re-execute the command even if the session ends before proper completion. .PP Each session is automatically saved to the file .I $HOME/.sw/sessions/swinstall{swcopy}.last. This file is overwritten by each invocation of .CR swlist . .PP You can also save session information to a specific file by executing .C swlist with the .C -C .I session__file option. .PP A session file uses the same syntax as the defaults files. You can specify an absolute path for the session file. If you do not specify a directory, the default location for a session file is .IR /.sw/sessions/ . .PP To re-execute a session file, specify the session file as the argument for the .C -S .I session__file option of .CR swlist . .PP Note that when you re-execute a session file, the values in the session file take precedence over values in the system defaults file. Likewise, any command line options or parameters that you specify when you invoke .CR swlist take precedence over the values in the session file. .PP .SS Environment Variables .PP The .C swlist program sets the following environment variable, which is used by the software control scripts being executed. .PP .C LANG .IP Determines the language in which messages are displayed. If LANG is not specified or is set to the empty string, a default value of .C C is used. See .C lang(5) for more information. .IP NOTE: The language in which the SD agent and daemon log messages are displayed is set by the system configuration variable script, .CR /etc/rc.config.d/LANG . For example, .CR /etc/rc.config.d/LANG , must be set to .CR LANG=ja_JP.SJIS or .CR LANG=ja_JP.eucJP to make the agent and daemon log messages display in Japanese. .PP .SS Signals .PP The .C swlist command catches the signals SIGQUIT and SIGINT. If these signals are received, .C swlist prints a message, sends a Remote Procedure Call (RPC) to the agents to wrap up, and then exits. .P Each agent will complete the list task (if the execution phase has already started) before it wraps up. .PP .SH OPERATION .PP .\"The .\".C swlist .\"session consists of only one phase, selection. This phase .\"takes place on the controller. .\".P The output from .C swlist follows this rule with all options: only the lowest level listed (product, subproduct, fileset or file) will be uncommented. Among other things, this allows the output from swlist to be used as input to other commands. The one exception is the list that contains files; file-level output is not accepted by other commands. .P The types of listings that can be selected are given below. Some of these listings are not exclusive choices, but rather ways to view the objects while controlling the amount of output. .RS .TP 2 \(bu Default Listing .TP \(bu Software Listing .TP \(bu Root Listing .TP \(bu Depot Listing .TP \(bu Multiple Targets Listing .TP \(bu Verbose Listing .TP \(bu Fanout Listing .IR "(HP OpenView Software Distributor only)" .RE .PP .SS "Default Listing" .PP If .C swlist is invoked with no .IR software_selections and no .IR target_selections , a listing of all installed products on the local host is produced. This listing contains one line for each product. The line includes the product tag attributes and all other attributes selected via the .C one_liner option. .P If .IR target_selections (i.e. target hosts) are specified, this same format listing is produced for the installed software at each of the specified hosts. .PP .SS "Software Listing" .PP A listing of software objects is controlled by the specified .IR software_selections , and also by the .C -l option ( .CR swlist.level= ). .P For each software object specified in the .IR software_selections , .C swlist lists the contents of each. For example, if you specify product selections, then the subproducts and/or filesets contained immediately below each product will be listed. If you specify fileset selections, then the files contained in each fileset will be listed. .P The depth of objects listed is controlled with the .C -l option. This option can expand or restrict the depth in concert with the specified software selections. By default, the contents of a specified software selection are always listed (as described above). The .C -l option can defeat this listing by specifying a level equivalent to the level of objects in the .IR software_selections . For example, if you want to list specific product selections but not their contents, use .CR "-l product" . If you want to list specific fileset selections but not their contained files, use .CR "-l fileset" . The .I software_selection options do not apply if the level is: .br .CR machine , .IR "(HP OpenView Software Distributor only)" .br .CR user , .IR "(HP OpenView Software Distributor only)" .br .CR group , .IR "(HP OpenView Software Distributor only)" .br .CR root , or .br .CR depot . In these cases, all objects of that type are listed. .\"The default depth is one level, with the .\"level above printed when more than one starting point is specified. Given the .\"following software level: .\".RS .\".TP .\".C Product selection .\".IP .\"List the subproducts or filesets in the specified product. .\".TP .\".C Product.Sub-product .\".IP .\"List the filesets in the specified subproduct. .\".TP .\".C "Product.Sub-product.Fileset" .\".IP .\"List the files in the specified fileset. .\".RE .\".PP .PP .SS "Depot Listing" .PP Another class of objects that .C swlist can display are software depots. For example, the user can list all registered depots on a given host. A combination of the .C "-l depot" option and .IR target_selections operands can produce a variety of depot listings. .PP .SS "Multiple Targets Listing" .PP Multiple .IR target_selections (i.e. root filesystems, alternate roots, or depots) are listed sequentially: list all the requested objects and attributes from the first .IR target_selection , followed by the second .IR target_selection , etc. .PP .SS "Verbose Listing" .PP The .C -v option causes a verbose listing to be generated. A verbose listing includes all attributes defined for an object. The .C swlist command will print the keyword and value for each attribute. The attributes are listed one per line. The user can post-process (filter) the output with .IR grep (1), .IR awk (1), and/or .IR sed (1) to get the fields of interest. .P The depot's attributes are displayed if .C swlist is called with the .C -v and .C "-l depot" options, and a specific depot .IR target_selection . .PP Attributes for a particular software level .RC ( product/subproduct/fileset/file ) are displayed based on the depth of the specified .IR software_selections . For example, .IR "swlist -v product1.fileset1" will give all fileset attributes for .IR fileset1. If the .C -v option is used with the .CR "-l option" , the different listing are: .RS .TP 2 \(bu To display attributes for all products, use .C "swlist -v -l product" .TP \(bu To display attributes for all products and subproducts, use .C "swlist -vl subproduct" .TP \(bu To display attributes for all products, subproducts, and filesets, use .C "swlist -vl fileset" .TP \(bu To display attributes for all products, subproducts, and filesets, and files, use .C "swlist -vl file" .RE .bp .PP .SS "Fanout Listing" .RS .IP .IR "The following applies only to HP OpenView Software Distributor" .RE .PP The .C swlist command can also list the users, groups, or machines associated with a PC Controller; i.e. the valid PC targets which are available for installation through the PC Controller. To list these PC targets, use the .CR "-l user" , .CR "-l group" , or .CR "-l machine" options. .PP .SH RETURN VALUE .PP The .C swlist command returns: .RS .TP 4 .C 0 The .I software_selections and/or .I target_selections were successfully listed. .PD 0 .TP .C 1 The list operation failed on all .IR target_selections . .TP .C 2 The list operation failed on some .IR target_selections . .PD .RE .PP .SH DIAGNOSTICS .PP The .C swlist command writes to stdout, stderr, and to the agent logfile. .PP .SS Standard Output .PP All listings are printed to stdout. .PP .SS Standard Error .PP The .C swlist command writes messages for all WARNING and ERROR conditions to stderr. .SS Logging .PP The .C swlist command does not log summary events. It logs events about each read task to the .C swagent logfile associated with each .IR target_selection . .PP .PP .SH EXAMPLES .PP To list all of the products installed on the local host: .IP .C swlist .PP Generate a comprehensive listing that includes all filesets for the product NETWORKING: .IP .C "swlist -v -l fileset NETWORKING" .PP List all the attributes for the ARPA-RUN fileset: .IP .C "swlist -v NETWORKING.ARPA.ARPA-RUN" .PP List the C product installed on several remote hosts: .IP .C "swlist cc" \*(at .C " hostA hostB hostC" .PP List the FRAME product relocated to directory .IR /opt on host1: .IP .C "swlist FRAME,1=/opt" \*(at .C " host1" .PP List all the versions of the FRAME product installed on the toolserver host: .IP .C "swlist FRAME" \*(at .C " toolserver" .PP List all products in a shared root: .IP .C "swlist -r" \*(at .C "/export/shared_roots/OS_700" .PP List products in a client's private root: .IP .C "swlist -r" \*(at .C "/export/private_roots/client" .PP List the contents of the local tape, .IR /dev/rmt/0m : .IP .C "swlist -d" \*(at .C " /dev/rmt/0m" .P or, alternatively: .IP .C "swlist -s /dev/rmt/0m" .PP List the tag and revision attributes for all products on the local tape .IR /dev/rmt/0m : .IP .C "swlist -d -a revision \*" \*(at .C " /dev/rmt/0m" .PP or, alternatively: .IP .C "swlist -a revision -s /dev/rmt/0m \*" .PP Display the README file for the FRAME product: .IP .C "swlist -a readme FRAME" .PP List the products stored in a remote depot: .IP .C "swlist -d" \*(at .C " hostA:/depot" .PP List all depots on a host: .IP .C "swlist -l depot" \*(at .C " hostA" .PP .RS .IP .IR "The next two examples apply only to HP OpenView Software Distributor" .RE .PP List all machines known to a PC controller: .IP .C "swlist -l machine" \*(at .C " server" .PP List all users known to a PC controller: .IP .C "swlist -l user" \*(at .C " server" .PP .\".SH WARNINGS .\".PP .\".PP .\".SH DEPENDENCIES .PP .SH LIMITATIONS .PP .RS .IP .IR "The following applies only to HP OpenView Software Distributor" .RE .PP For PCs, the .C swlist command only applies to the PC controller, and the PC depot on the PC controller. .PP .SH FILES .\" .C /var/adm/sw/ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. This directory is also the default location of logfiles. .RE \" .C /usr/lib/sw/sys.defaults .br .RS 8 Contains the master list of current SD options (with their default values). .RE .\" .C /var/adm/sw/defaults .br .RS 8 Contains the active system-wide default values for some or all SD options. .RE .\" .C $HOME/.sw/defaults .br .RS 8 Contains the user-specific default values for some or all SD options. .RE .\" .C $HOME/.sw/sessions/ .br .RS 8 Contains session files automatically saved by the SD commands, or explicitly saved by the user. .RE .\" .C /var/adm/sw/products/ .br .RS 8 The Installed Products Database (IPD), a catalog of all products installed on a system. .RE .\" .C /var/spool/sw/ .br .RS 8 The default location of a source and target software depot. .RE .\" .C /var/adm/sw/host_object .br .RS 8 The file which stores the list of depots registered at the local host. .RE .PP .SH AUTHOR .PP .C swlist was developed by the Hewlett-Packard Company. .PP .SH SEE ALSO .PP sd(4), sd(5), swacl(1M), swagentd(1M), swcluster(1M), swconfig(1M), swcopy(1M), swgettools(1M), swinstall(1M), swjob(1M), swmodify(1M), swpackage(1M), swpackage(4), swreg(1M), swremove(1M), swverify(1M), update(1M), and the .IR "HP OpenView Software Distributor Administrator's Guide" or .IR "Managing HP-UX Software with SD-UX" manuals. .\" index@\f4swlist\f1 \- display information about software products@@@\f3swlist(1M)\f1 .\" index@\f1software products, display information about@@@\f3swlist(1M)\f1 .\" index@\f1information, display software product@@@\f3swlist(1M)\f1 .\" toc@\f3swlist(1M)\f1:\0\0\f4swlist\f1@@@display information about software products\f1 .\" $Header: swmodify.1m,v 78.2 96/05/09 12:35:00 ssa Exp $ .\" '\" t .\" so SunOS will invoke the tbl preprocessor before the man macros .\" -*-Nroff-*- .\" $Header: swmodify.1m,v 78.2 96/05/09 12:35:00 ssa Exp $ .\" .ds RZ \&HP CONFIDENTIAL .\" .ds RL Release B.10.0x .\" .ds MT Software Distributor B.10.0x .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro, e.g. .CR, .RI, .\" etc. A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .\" .ds PN Release B.10.0x .TA s .TH swmodify 1M " " "Hewlett-Packard Company" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ds )H Software Distributor .\" .ds ]W Release B.10.0x .SH NAME swmodify \- Modify software products in a target root or depot .PP .SH SYNOPSIS .C swmodify .RC [ -d | -r ] .RC [ -p ] .RC [ -P\| .IR pathname_file\| ] .RC [ -v [ v ]] .RC [ -V ] .RC [ -u ] .br .RC [ -s\| .IR product_specification_file | .CR -a\| .IR attribute =[ value ]] .RC [ -x .IR option=value\| ] .RC [ -X\| .IR option_file\| ] .br .RC [ -f\| .IR software_file\| ] .RC [ -C\| .IR session_file\| ] .RC [ -S\| .IR session_file\| ] .RI [ software_selections ]\0[\c \*(at .IR \0target_selection ] .PP .SS Remarks: SD-UX commands are included with the HP-UX Operating System and manage software on the .I local host only. To install and manage software simultaneously on multiple .I remote hosts (including PCs) from a central controller, you must purchase the .B "HP OpenView Software Distributor" (HP Prod. No. B1996AA) which provides extended software management, multi-site software distribution capabilities and distribution to PCs. While most of the information in this manual page applies to both SD-UX commands and the OpenView product, some applies .B only to the OpenView product. Where this is the case, you will see: .RS .IP .IR "The following xxx applies only to HP OpenView Software Distributor" .RE .PP .SH DESCRIPTION .\"The .\".C swmodify .\"command adds, modifies, or deletes objects and/or attributes defined in .\"a software depot, primary root, or alternate root. It provides a direct .\"interface with a depot's catalog, or a root's installed products .\"database (IPD). .\".PP The .C swmodify command modifies the definitions of software objects installed into a primary or alternate root, or available from a software depot. It supports the following features: .RS .TP 2 \(bu adding new objects - The user can add new bundles, products, subproducts, filesets, control files, and files to existing objects (which will contain them). .TP \(bu deleting existing objects - The user can delete existing bundles, products, subproducts, filesets, control files, and files from the objects which contain them. .TP \(bu modifying attribute values - The user can add an attribute, delete an attribute, or change the existing value of an attribute for any existing object. When adding a new object, the user can at the same time define attributes for it. .RE .PP The .C swmodify commands does not manipulate the actual files which make up a product (fileset). It can only manipulate the catalog information which describes the files. .PP Common uses of .C swmodify include: .RS .TP 2 \(bu adding file definitions to the existing list of file definitions in a fileset. Example: If a fileset's control scripts add new files to the installed filesystem, the scripts can call .C swmodify to "make a record" of those new files. .TP \(bu changing the values of existing attributes. Example: If a product provides a more complex configuration process (beyond the SD configure script), that script can set the fileset's state to CONFIGURED upon successful execution. .TP \(bu defining new objects. Example: to "import" the definition of an existing application that was not installed by SD, construct a simple PSF describing the product. Then invoke .C swmodify to load the definition of the existing application into the IPD. .RE .PP .SS Options .C swmodify supports the following options: .RS .TP 10 .C -d Perform modifications on a depot (not on a primary or alternate root). The given .I target_selection must be a depot. .TP .C -r Perform modifications on an alternate root (and not the primary root, .IR / ). The given .I target_selection must be an alternate root.) .TP .C -p Previews a modify session without modifying anything within the .IR target_selection . .TP .CI -P \0pathname_file Specifies a file containing the pathnames of files being added to, or deleted from the IPD instead of having to specify them individually on the command line. .TP .C -v[v] Turns on verbose output to stdout. (The .C swmodify logfile is not affected by this option.) A second .C -v will turn on very verbose output. .TP .C -V List all the .C SD layout_versions this command supports. .TP .C -u If no .I "-a attribute=value" options are specified, then delete the given .I software_selections from withing the given .IR target_selection . This action deletes the definitions of the software objects from the depot catalog or installed products database. .IP If .I "-a attribute" options are specified, then delete these attribute definitions from the given .I software_selections (from within the given .IR target_selection ). .TP .CI -s \0product_specification_file The source .IR "Product Specification File" (PSF) describes the product, subproduct, fileset, and/or file definitions which will be added or modified by .CR swmodify . .IP The .C -s and .C -u options are mutually exclusive, the .C -s option cannot be specified when the .C -u option is specified. .TP .CI -a \0attribute\f1[=\fPvalue\f1]\fP Add, modify, or delete the .I value of the given .IR attribute . If the .C -u option is specified, then delete the .I attribute from the given .I software_selections (or delete the .I value from the set of values currently defined for the .IR attribute ). Otherwise add/modify the .I attribute for each .I software_selection by setting it to the given .IR value . .IP Multiple .C -a options can be specified. Each attribute modification will be applied to every .IR software_selection . .IP The .C -s and .C -a options are mutually exclusive, the .C -s option cannot be specified when the .C -a option is specified. .TP .CI -x \0option=value Set the session .I option to .I value and override the default value (or a value in an alternate .IR options_file specified with the .C -X option). Multiple .C -x options can be specified. .TP .CI -X \0option_file Read the session options and behaviors from .IR options_file . .TP .CI -f \0software_file Read the list of .I software_selections from .I software_file instead of (or in addition to) the command line. .TP .CI -C \0session_file Save the current options and operands to .IR session_file . You can enter a relative or absolute path with the file name. The default directory for session files is .CR /.sw/sessions/ . You can recall a session file with the .C -S option. .TP .CI -S \0session_file Execute .C swmodify based on the options and operands saved from a previous session, as defined in .IR session_file . You can save session information to a file with the .C -C option. .\" .SS Operands .PP The .C swmodify command supports the following syntax for each .IR software_selection : .IP .C bundle[.product[.subproduct][.fileset]][,version] .P or .IP .C product[.subproduct][.fileset][,version] .br .P The .C version component has the form: .IP .C [,r .IR .C revision][,a .IR .C arch][,v .IR .C vendor][,c .IR .C category] .P or .IP .C [instance_id] .P where .IR can be: ==, >=, <=, <, >, or != which performs individual comparisons on dot-separated fields. For example, r>=BB.10.00 means choose all revisions that are greater than or equal to BB.10.00. The system will compare each dot-separated field to find matches. Software will only be selected when matches within each field are satisfied. Wildcards are not allowed with these operators. .P The .C = (equals) relational operator is also allowed. It provides the shell pattern matching notations []*?! or wildcards to specify selections as opposed to comparing dot-separated fields. .P All version components are repeatable within a single specification (e.g. r>=AA.12, r\|"\|-x target_type=tape\|-s \| The .C | symbol and command must be quoted because it is interpreted by .C swpackage and not the shell. .TP .CI -x \0option=value Set the session .I option to .I value and override the default value (or a value in an alternate .IR options_file specified with the .C -X option). Multiple .C -x options can be specified. .TP .CI -X \0option_file Read the session options and behaviors from .IR options_file . .TP .CI -f \0software_file Read the list of .I software_selections from .I software_file instead of (or in addition to) the command line. .TP .CI -C \0session_file Save the current options and operands to .IR session_file . You can enter a relative or absolute path with the file name. The default directory for session files is .CR /.sw/sessions/ . You can recall a session file with the .C -S option. .TP .CI -S \0session_file Execute .C swpackage based on the options and operands saved from a previous session, as defined in .IR session_file . You can save session information to a file with the .C -C option. .RE .PP .SS Operands .PP The .C swpackage command supports the following syntax for each .IR software_selection : .IP .C bundle[.product[.subproduct][.fileset]][,version] .P or .IP .C product[.subproduct][.fileset][,version] .P The .C version component has the form: .IP .C [,r .IR .C revision][,a .IR .C arch][,v .IR .C vendor][,c .IR .C category] .P or .IP .C [instance_id] .P where .IR can be: ==, >=, <=, <, >, or != which performs individual comparisons on dot-separated fields. For example, r>=BB.10.00 means choose all revisions that are greater than or equal to BB.10.00. The system will compare each dot-separated field to find matches. Software will only be selected when matches within each field are satisfied. Wildcards are not allowed with these operators. .P The .C = (equals) relational operator is also allowed. It provides the shell pattern matching notations []*?! or wildcards to specify selections as opposed to comparing dot-separated fields. .P All version components are repeatable within a single specification (e.g. r>=AA.12, r] .PP .RS [] .PP [] .PP .RS [] .RE .PP .PP .RS [] .PP [] .PP [] .PP .RS .PP [] .PP .RE .PP [] .PP ... .PP .RE [] .PP ... .RE .RE .PP Errors encountered while parsing the PSF result in no valid product definitions, then .C swpackage terminates. (All errors are logged to both stderr and the logfile.) In summary, the .C swpackage user can: .RS .TP 5 \(bu Specify one or more products; .TP \(bu For each product, specify one or more filesets. .TP \(bu For each fileset, specify one or more files. .TP \(bu (optional) Specify attributes for the target depot/tape; .TP \(bu (optional) Specify one or more bundles, defining the bundle contents; .TP \(bu (optional) Specify vendor information for groups of products and bundles (including all products), or for individual products. .TP \(bu (optional) For each product, specify one or more subproducts, defining the subproduct contents; .TP \(bu (optional) For each product or fileset, specify one or more control scripts. .RE .PP .SH RETURN VALUES .PP The .C swpackage command returns: .RS .TP .C 0 The products specified in the .IR product_specification_file were successfully packaged into the target depot/tape. .TP .C 1 An error occurred during the .C swpackage session (e.g. bad syntax in the .IR product_specification_file .) Review stderr or the log file for details. .PD .RE .PP .SH DIAGNOSTICS .PP The .C swpackage command writes to stdout, stderr, and to the logfile. .PP .SS Standard Output .PP The .C swpackage command writes messages for significant events. These include: .RS .TP 2 \(bu a begin and end session message, .PD 0 .TP \(bu selection, analysis, packaging, and tape creation messages. .PD .RE .PP .SS Standard Error .PP The .C swpackage command writes messages for all WARNING and ERROR conditions to stderr. .PP .SS Logfile .PP The .C swpackage command logs detailed events to the log file .IR /var/adm/sw/swpackage.log . (The user can specify a different logfile by modifying the .C logfile option.) .PP .SH EXAMPLES .PP Package the products defined in the PSF .I products into the default target depot: .IP .C "swpackage -s products" .PP Preview the same operation (do not create the target depot), and generate very verbose output: .IP .C "swpackage -p -vv -s products" .PP Package the products into the target depot .IR no_files , insert references to the source files instead of copying them into the depot: .IP .C "swpackage -s products -x package_in_place=true" \*(at .C \0no_files .PP Re-package a specific fileset: .IP .C "swpackage -s products -x package_in_place=true product.fileset" \*(at .C \0no_files .PP Re-package the entire contents of the depot .I /var/spool/sw onto the tape at .IR /dev/rmt/0m : .IP .C "swpackage -s /var/spool/sw -x target_type=tape \*" \*(at .C \0/dev/rmt/0m .\".SH WARNINGS .\".PP .\".PP .\".SH DEPENDENCIES .SH LIMITATIONS .PP The .C swpackage command does not apply to HP OpenView Software Distributor PC software. PC software is packaged on the PC Controller using the PC Console, then copied to a UNIX depot for subsequent distribution. .PP .SH FILES .PP .\" .C /var/adm/sw/ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. This directory is also the default location of logfiles. .RE .\" .C /usr/lib/sw/sys.defaults .br .RS 8 Contains the master list of current SD options (with their default values). .RE .\" .C /var/adm/sw/defaults .br .RS 8 Contains the active system-wide default values for some or all SD options. .RE .\" .C $HOME/.sw/defaults .br .RS 8 Contains the user-specific default values for some or all SD options. .RE .\" .C $HOME/.sw/sessions/ .br .RS 8 Contains session files automatically saved by the SD commands, or explicitly saved by the user. .RE .C /var/spool/sw/ .br .RS 8 The default location of a source and target software depot. .RE .\" .C /dev/rmt/0m .br .RS 8 The default location of a source and target tape. .RE .PP .SH AUTHOR .PP .C swpackage was developed by the Hewlett-Packard Company. .PP .SH SEE ALSO swpackage(4), sd(4), sd(5), swacl(1M), swagentd(1M), swcluster(1M), swconfig(1M), swcopy(1M), swgettools(1M), swinstall(1M), swjob(1M), swlist(1M), swmodify(1M), swreg(1M), swremove(1M), swverify(1M), update(1M), and the .IR "HP OpenView Software Distributor Administrator's Guide" or .IR "Managing HP-UX Software with SD-UX" manuals. .\" .\" index@\f4swpackage\f1 \- package software products into a target depot or tape@@@\f3swpackage(1M)\f1 .\" index@\f1software products, package into target depot or tape@@@\f3swpackage(1M)\f1 .\" index@\f1target depot, package software products into@@@\f3swpackage(1M)\f1 .\" index@\f1tape, package software products into@@@\f3swpackage(1M)\f1 .\" toc@\f3swpackage(1M)\f1:\0\0\f4swpackage\f1@@@package software products into a target depot or tape\f1 .\" .\" $Header: swreg.1m,v 78.2 96/05/09 12:36:14 ssa Exp $ .\" -*-Nroff-*- .\" $Header: swreg.1m,v 78.2 96/05/09 12:36:14 ssa Exp $ .\" .ds RZ \&HP CONFIDENTIAL .\" .ds RL Release B.10.0x .\" .ds MT Software Distributor B.10.0x .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro, e.g. .CR, .RI, .\" etc. A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .\" .ds PN Release B.10.0x .TA s .TH swreg 1M " " "Hewlett-Packard Company" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ds )H Software Distributor .\" .ds ]W Release B.10.0x .SH NAME swreg \- Register or unregister depots and roots .PP .SH SYNOPSIS .C swreg .C -l .I \|level\| .RC [-u ] .RC [-v ] .RC [ -x .IR option=value\| ] .RC [ -X\| .IR option_file\| ] .RC [ -f\| .IR object_file\| ] .RC [ -t\| .IR target_file\| ] .br .RC [ -C\| .IR session_file\| ] .RC [ -S\| .IR session_file\| ] .RI \c .RI [ objects_to_(un)register ]\0[\c \*(at .IR \0target_selections ] .PP .SS Remarks: SD-UX commands are included with the HP-UX Operating System and manage software on the .I local host only. To install and manage software simultaneously on multiple .I remote hosts (including PCs) from a central controller, you must purchase the .B "HP OpenView Software Distributor" (HP Prod. No. B1996AA) which provides extended software management, multi-site software distribution capabilities and distribution to PCs. While most of the information in this manual page applies to both SD-UX commands and the OpenView product, some applies .B only to the OpenView product. Where this is the case, you will see: .RS .IP .IR "The following xxx applies only to HP OpenView Software Distributor" .RE .PP .SH DESCRIPTION .PP The .C swreg command controls the visibility of depots and roots to users who are performing software management tasks. It must be used to register depots created by .CR swpackage . .PP By default, the .C swcopy command registers newly created depots. By default, the .C swinstall command registers newly created alternate roots (the root, "/", is not automatically registered). The .C swremove command unregisters a depot, or root, when or if the depot is empty. The user invokes .C swreg to explicitly (un)register a depot when the automatic behaviors of .CR swcopy , .CR swinstall , .CR swpackage , and .C swremove do not suffice. For example: .RS .TP 2 \(bu making a CD-ROM or other removable media available as a registered depot. .TP \(bu registering a depot created directly by .CR swpackage . .TP \(bu unregistering a depot without removing it with .CR swremove . .RE .PP .P The possible types of .I roots that can be managed are .CR roots , .CR "shared roots" , and .CR "private roots" . There is no default behavior for registering or unregistering roots. .PP .SS Options The .C swreg command supports the following options: .RS .TP 15 .CI -l \0level Specify the .I level of the object to register or unregister. Exactly one level must be specified. The supported levels are: .RS .TP 10 .C root The object to be registered is a root. .TP .C "shroot" The object to register is a shared root. .TP .C "prroot" The object to register is a private root. .TP .C depot The object to be registered is a depot. .RE .RE .RS .TP 15 .C -u Causes .C swreg to unregister the specified objects instead of registering them. .TP .C -v Turns on verbose output to stdout. (The .C swreg logfile is not affected by this option.) Verbose output is enabled by default, see the .C verbose option below. .TP .CI -x \0option=value Set the session .I option to .I value and override the default value (or a value in an alternate .IR option_file specified with the .C -X option). Multiple .C -x options can be specified. .TP .CI -X \0option_file Read the session options and behaviors from .IR option_file . .TP .CI -f \0object_file Read the list of depot or root objects to register or unregister from .I object_file instead of (or in addition to) the command line. .TP .CI -t \0target_file Read the list of target .I hosts on which to register the depot or root objects from .I target_file instead of (or in addition to) the command line. .TP .CI -C \0session_file Save the current options and operands to .IR session_file . You can enter a relative or absolute path with the file name. The default directory for session files is .CR /.sw/sessions/ . You can recall a session file with the .C -S option. .TP .CI -S \0session_file Execute .C swreg based on the options and operands saved from a previous session, as defined in .IR session_file . You can save session information to a file with the .C -C option. .RE .PP .SS Operands .PP The .C swreg command supports the following syntax for each .IR object_to_register : .IP .C "path" .PP Each operand specifies an object to be registered or unregistered. .PP The .C swreg command supports the following syntax for each .IR target_selection : .IP .C "[host]" .SH EXTERNAL INFLUENCES .PP .SS Defaults File .PP In addition to the standard options, several .C swreg behaviors and policy options can be changed by editing the default values found in: .IP .C /var/adm/sw/defaults - the system-wide default values, .IP .C $HOME/.sw/defaults - the user-specific default values. .PP Values must be specified in the defaults file using this syntax: .PP .IP .CI swreg. option = value .PP The default values can be overridden by specifying an options file with the .C -X option, or by specifying .CI -x\0 option = value on the command line. The policy options that apply to .C swreg are: .PP .RS .TP 10 .C level= Defines the default level of objects to list. The valid levels are: .CR root , .CR shroot , .CR prroot , and .CR depot . .TP .C logfile=/var/adm/sw/swreg.log This is the default command log file for the .C swreg command. .TP .C logdetail=false[true] The SD .I loglevel and .I logdetail options allow you to choose what amount of information you need in your logfiles - from no detail to complete information. The .I loglevel=0 option allows no information to be written to the logfile. This essentially turns off the logfile process. The .I logdetail=true[false] option controls the amount of detail written to the logfile. Here are the possible combinations of .I loglevel and .I logdetail options: .bp .nf .TS tab(@); lB| lB| lB lf4| lf4| l. Log Level@Log Detail@Information Included _ loglevel=0@@T{ No information is written to the logfile. T} _ loglevel=1@logdetail=false@T{ Only POSIX events are logged; this is the default. T} _ loglevel=1@logdetail=true@T{ POSIX detail as above plus task progress messages. Setting loglevel=1 is not necessary, it is the default. T} _ loglevel=2@logdetail=false@T{ POSIX and file level messages only. Setting the logdetail=false option is not necessary. T} _ loglevel=2@logdetail=true@T{ All information is logged. Setting both loglevel=2 and logdetail=true options is required. With this combination you may get the same logfile behavior as previous HP-UX 10.x releases. T} .TE .fi .TP .C loglevel=1 Controls the log level for the events logged to the command logfile, and the target daemon logfile. A value of .C 0 prevents information from being logged. A value of .C 1 enables verbose logging to the logfiles. A value of .C 2 enables very verbose logging to the logfiles. .TP .C log_mesgid=0 Controls whether numeric identification numbers are prepended to logfile messages produced by SD. A value of 0 (default) indicates no such identifiers are attached. Values of 1-4 indicate that identifiers are attached to messages: .RS .TP 3 \(bu 1 applies to ERROR messages only .TP \(bu 2 applies to ERROR and WARNING messages .TP \(bu 3 applies to ERROR, WARNING, and NOTE messages .TP \(bu 4 applies to ERROR, WARNING, NOTE, and certain other logfile messages. .RE .TP .C objects_to_register= Defines the default objects to register or unregister. There is no supplied default (see .C target_directory above). If there is more than one object, they must be separated by spaces. .TP .C rpc_binding_info=ncadg_ip_udp:[2121] Defines the protocol sequence and endpoint which will be used to contact .CR swagentd . This value should be consistent among all hosts that work together. See sd(5) for details on specifying this option. .TP .C rpc_timeout=7 For HP OpenView Software Distributor the default is .CR rpc_timeout=5 . Relative length of the communications timeout. This is a value in the range from 0 to 9 and is interpreted by the DCE RPC. Higher values mean longer times; you may need a higher value for a slow or busy network. Lower values will give faster recognition on attempts to contact hosts that are not up, or are not running the .CR swagentd . Each value is approximately twice as long as the preceding value. A value of 5 is about 30 seconds for .CR ncadg_ip_udp . .TP .C select_local=true If no .IR target_selections are specified, select the local host as the target of the command. .TP .C target_directory=/var/spool/sw Defines the location of the depot object to register if no objects are specified. .TP .C targets= Defines the default .IR target hosts on which to register or unregister the specified root or depot objects. There is no supplied default (see .C select_local above). If there is more than target selection, they must be separated by spaces. .TP .C verbose=1 Controls the verbosity of the .C swreg output (stdout). A value of .C 0 disables output to stdout. (Error and warning messages are always written to stderr). A value of .C 1 enables verbose messaging to stdout. .RE .PP .SS Session File .PP Each invocation of the .C swreg command defines a registration session. The invocation options, source information, software selections, and target hosts are saved before the installation or copy task actually commences. This lets you re-execute the command even if the session ends before proper completion. .PP Each session is automatically saved to the file .IR $HOME/.sw/sessions/swinstall{swcopy}.last . This file is overwritten by each invocation of .CR swreg . .PP You can also save session information to a specific file by executing .C swreg with the .C -C .I session__file option. .PP A session file uses the same syntax as the defaults files. You can specify an absolute path for the session file. If you do not specify a directory, the default location for a session file is .CR /.sw/sessions/ . .PP To re-execute a session file, specify the session file as the argument for the .C -S .I session__file option of .CR swreg . .PP Note that when you re-execute a session file, the values in the session file take precedence over values in the system defaults file. Likewise, any command line options or parameters that you specify when you invoke .CR swreg take precedence over the values in the session file. .PP .SS Environment Variables .PP The .C swreg program sets the following environment variable, which is used by the software control scripts being executed. .PP .C LANG .IP Determines the language in which messages are displayed. If LANG is not specified or is set to the empty string, a default value of .C C is used. See .C lang(5) for more information. .IP NOTE: The language in which the SD agent and daemon log messages are displayed is set by the system configuration variable script, .CR /etc/rc.config.d/LANG . For example, .CR /etc/rc.config.d/LANG , must be set to .CR LANG=ja_JP.SJIS or .CR LANG=ja_JP.eucJP to make the agent and daemon log messages display in Japanese. .PP .SS Signals .PP The .C swreg command catches the signals SIGQUIT and SIGINT. If these signals are received, .C swreg prints a message, sends a Remote Procedure Call (RPC) to the daemons to wrap up, and then exits. .PP .SH RETURN VALUES .PP The .C swreg command returns: .RS .TP 4 .C 0 The .I objects_to_register were successfully (un)registered. .PD 0 .TP .C 1 The register or unregister operation failed on all .IR target_selections . .PD 0 .TP .C 2 The register or unregister operation failed on some .IR target_selections . .PD .RE .bp .PP .SH DIAGNOSTICS .PP The .C swreg command writes to stdout, stderr, and to the daemon logfile. .PP .SS Standard Output .PP The .C swreg command writes messages for significant events. These include: .RS .TP 2 \(bu a begin and end session message, .PD 0 .TP \(bu selection and execution task messages for each .IR target_selection . .PD .RE .PP .SS Standard Error .PP The .C swreg command writes messages for all WARNING and ERROR conditions to stderr. .SS Logging .PP The .C swreg command logs summary events at the host where the command was invoked. It logs events about each (un)register operation to the .C swagentd logfile associated with each .IR target_selection . .PP .SH EXAMPLES .PP Create a new depot with .CR swpackage , then register it with .CR swreg : .IP .C "swpackage -s psf -d /var/spool/sw" .br .C "swreg -l depot /var/spool/sw" .PP .RS .IP .IR "The following example applies only to HP OpenView Software Distributor" .RE .PP Unregister the default depot at several hosts: .IP .C "swreg -u -l depot /var/spool/sw" \*(at .C " hostA hostB hostC" .PP Unregister a specific depot at the local host: .IP .C "swreg -u -l depot /cdrom" .PP .\".SH WARNINGS .\".PP .\".PP .\".SH DEPENDENCIES .\".PP .PP .SH LIMITATIONS .PP .\" The SunOS and SD-UX versions of .C swreg do not support the registration or unregistration of software depots on remote targets. .PP For PCs (HP OpenView Software Distributor), the .C swreg command only operates on a single depot, configured at the PC Controller. .PP .SH FILES .PP .\" .C /var/adm/sw/ .br .RS 8 The directory which contains all of the configurable (and non-configurable) data for SD. This directory is also the default location of logfiles. .RE .\" .C /var/adm/sw/host_object .br .RS 8 The file which stores the list of depots registered at the local host. .RE .\" .C /usr/lib/sw/sys.defaults .br .RS 8 Contains the master list of current SD options (with their default values). .RE .\" .C /var/adm/sw/defaults .br .RS 8 Contains the active system-wide default values for some or all SD options. .RE .\" .C $HOME/.sw/defaults .br .RS 8 Contains the user-specific default values for some or all SD options. .RE .PP .SH PC FILES .RS .IP .IR "The following applies only to HP OpenView Software Distributor" .RE .PP .\" .C ...\\\\SD\\\\DATA\\\\HOST_OBJ .br .RS 8 The file which stores the list PC depot registered with the PC Controller. .RE .PP .SH AUTHOR .PP .C swreg was developed by the Hewlett-Packard Company. .PP .SH SEE ALSO .PP sd(4), sd(5), swacl(1M), swagentd(1M), swcluster(1M), swconfig(1M), swcopy(1M), swgettools(1M), swinstall(1M), swjob(1M), swlist(1M), swmodify(1M), swpackage(1M), swpackage(4), swremove(1M), swverify(1M), update(1M), and the .IR "HP OpenView Software Distributor Administrator's Guide" or .IR "Managing HP-UX Software with SD-UX" manuals. .\" index@\f4swreg\f1 \- register or unregister depots and roots@@@\f3swreg(1M)\f1 .\" index@\f1depots and roots, register or unregister@@@\f3swreg(1M)\f1 .\" index@\f1roots and depots, register or unregister@@@\f3swreg(1M)\f1 .\" index@\f1unregister or register depots and roots@@@\f3swreg(1M)\f1 .\" toc@\f3swreg(1M)\f1:\0\0\f4swreg\f1@@@register or unregister depots and roots\f1 .\" $Header: swremove.1m,v 78.2 96/05/09 12:36:51 ssa Exp $ .\" -*-Nroff-*- .\" .ds RZ \&HP CONFIDENTIAL .\" .ds RL Release B.10.0x .\" .ds MT Software Distributor B.10.0x .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro, e.g. .CR, .RI, .\" etc. A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .\" .ds PN Release B.10.0x .TA s .TH swremove 1M " " "Hewlett-Packard Company" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" .ds )H Software Distributor .\" .ds ]W Release B.10.0x .SH NAME swremove \- Unconfigure and remove software products .PP .SH SYNOPSIS .C swremove .RI [ "XToolkit Options" ] .RC [ -i ] .RC [ -p ] .RC [ -v ] .RC [ -d | -r ] .RC [ -x .IR option=value\| ] .RC [ -X\| .IR option_file\| ] .RC [ -f\| .IR software_file\| ] .RC [ -t\| .IR target_file\| ] .RC [ -C\| .IR session_file\| ] .RC [ -S\| .IR session_file\| ] .RC [ -Q\| .IR date\| ] .RC [ -J\| .IR jobid\| ] .RI [ software_selections ]\0[\c \*(at .IR \0target_selections ] .PP .SS Remarks: SD-UX commands are included with the HP-UX Operating System and manage software on the .I local host only. To install and manage software simultaneously on multiple .I remote hosts (including PCs) from a central controller, you must purchase the .B "HP OpenView Software Distributor" (HP Prod. No. B1996AA) which provides extended software management, multi-site software distribution capabilities and distribution to PCs. While most of the information in this manual page applies to both SD-UX commands and the OpenView product, some applies .B only to the OpenView product. Where this is the case, you will see: .RS .IP .IR "The following xxx applies only to HP OpenView Software Distributor" .RE .PP .SH DESCRIPTION .PP The .C swremove command removes .\"both physically installed and linkinstalled .I software_selections from .I target_selections (e.g. root filesystems). .\"Unlike .\".C swinstall , .\"it does not need an explicit command line switch ( .\".C -l ) .\"to remove linkinstalled software. When removing installed software, .C swremove also unconfigures the software before it is removed. The software is not unconfigured when removed from an alternate root directory since it was not configured during installation. When removing available software (within a depot), .C swremove also does not perform the unconfiguration task. .P .B Note: Selecting a bundle for removal .I "does not always" remove all filesets in that bundle. If a particular fileset is required by another bundle, that fileset will not be removed. For example, if the bundles .C Pascal and .C FORTRAN both use the fileset .IR Debugger.Run and you try to remove .C FORTRAN , the fileset .IR Debugger.Run will not be removed because it is also used by the bundle .CR Pascal . This is done to prevent the removal of one bundle from inadvertently causing the removal of filesets needed by another bundle. .P Use the .C swcluster command to remove software from NFSD clients. .PP .RS .IP .IR "The following sentence applies only to HP OpenView Software Distributor" .RE .PP For PC software removal, the .C swremove command also removes .I software_selections from one or more target PC depots. .P .B Control Scripts .P When removing installed software, the .C swremove command executes several vendor-supplied scripts (if they exist) during the removal of the .IR software_selections . The .C swremove command supports the following scripts: .RS .TP .CR checkremove a script executed during the analysis of each .IR target_selection , it checks to make sure the removal can be attempted. If this check fails, the software product will not be removed. .TP .CR preremove a script executed immediately before the software files are removed. .TP .CR postremove a script executed immediately after the software files are removed. .TP .CR unconfigure a script executed during the unconfiguration of each .IR target_selection , it unconfigures the host for the software (and the software for the host). The .CR preremove and .CR postremove scripts are not intended for unconfiguration tasks. They are to be used for simple file management needs such as restoring files moved during install. The .CR unconfigure script allows the .C swremove command to unconfigure the hosts on which it has been running before removing the software specified. .sp 5 .PP .SS Options The .C swremove supports the following options: .RS .TP 15 .IR "XToolKit Options" The .CR swremove command supports a subset of the standard X Toolkit options to control the appearance of the GUI. The supported options are: .CR -bg , .CR -background , .CR -fg , .CR -foreground , .CR -display , .CR -name , .CR -xrm , and .CR -synchronous . See the .C X(1) manual page for a definition of these options. .TP .C -p Previews a remove task by running the session through the analysis phase only. .TP .C -i Runs .C swremove in interactive mode (invokes the Graphical User Interface). The .C swremove command also supports an interactive terminal user interface (TUI) in which screen navigation is done with the keyboard (no mouse). .TP .C -v Turns on verbose output to stdout. (The .C swremove logfile is not affected by this option.) Verbose output is controlled by the default .CR verbose=x . .TP .C -d Operate on a depot rather than installed software. .TP .C -r Operate on an alternate root rather than .CR / . Unconfigure scripts are not run when removing software from an alternate root directory. As of HP-UX release 10.2*, .CR -r is optional but is allowed to maintain compatibility with previous versions. .TP .CI -x \0option=value Set the session .I option to .I value and override the default value (or a value in an alternate .IR option_file specified with the .C -X option). Multiple .C -x options can be specified. .TP .CI -X \0option_file Read the session options and behaviors from .IR option_file . .TP .CI -f \0software_file Read the list of .I software_selections from .I software_file instead of (or in addition to) the command line. .TP .CI -t \0target_file Read the list of .I target_selections from .I target_file instead of (or in addition to) the command line. .TP .CI -C \0session_file Save the current options and operands to .IR session_file . You can enter a relative or absolute path with the file name. The default directory for session files is .CR /.sw/sessions/ . You can recall a session file with the .C -S option. .TP .CI -S \0session_file Execute .C swremove based on the options and operands saved from a previous session, as defined in .IR session_file . You can save session information to a file with the .C -C option. .RS .IP .IR "The -Q and -J options apply only to HP OpenView Software Distributor" .RE .PP .TP 15 .CI -Q \0date Schedules the job for this date. The date's format can be changed by modifying the file .I /var/adm/sw/getdate.templ . .TP .CI -J \0jobid Executes the previously scheduled job. This is the syntax used by the daemon to start the job. .RE .PP .SS Operands .PP The .C swremove command supports the following syntax for each .IR software_selection : .IP .C bundle[.product[.subproduct][.fileset]][,version] .P or .IP .C product[.subproduct][.fileset][,version] .sp 5 .P The .C version component has the form: .IP .C [,r .IR .C revision][,a .IR .C arch][,v .IR .C vendor][,c .IR .C category] .P or .IP .C [instance_id] .P where .IR can be: ==, >=, <=, < or *, >, or != which performs individual comparisons on dot-separated fields. For example, r>=BB.10.00 means choose all revisions that are greater than or equal to BB.10.00. The system will compare each dot-separated field to find matches. Software will only be selected when matches within each field are satisfied. Wildcards are not allowed with these operators. .P The .C = (equals) relational operator is also allowed to specify a particular version component. .P All version components are repeatable within a single specification (e.g. r>=A.12, r .C revision][,a .IR .C arch][,v .IR .C vendor][,c .IR .C category] .P or .IP .C [instance_id] .P where .IR can be: ==, >=, <=, < or *, >, or != which performs individual comparisons on dot-separated fields. For example, r>=BB.10.00 means choose all revisions that are greater than or equal to BB.10.00. The system will compare each dot-separated field to find matches. Software will only be selected when matches within each field are satisfied. Wildcards are not allowed with these operators. .P The .C = (equals) relational operator is also allowed to specify a particular version component. .P All version components are repeatable within a single specification (e.g. r>=A.12, r\*O \*Lsynchronize\*O .iE .LI The following example shows how to initiate a synchronization for the entity, followed by an abrupt reset of the clock: .iS \*Cdtscp>\*O \*Lsynchronize set clock true\*O .iE .LE .\" $Header: sysdef.1m,v 72.7 94/11/29 13:27:13 ssa Exp $ .TA s .TH sysdef 1M "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sysdef \- display system definition .SH SYNOPSIS .CR /usr/sbin/sysdef .RI \|[ kernel .RI \|[ master ]\|]\| .SH DESCRIPTION The command .CR sysdef analyzes the currently running system and reports on its tunable configuration parameters. .I kernel is the file used to retrieve the kernel namelist; if not specified, .CR /stand/vmunix is used. .I master is not used, but can be specified for standards compliance. .PP For each configuration parameter, the following information is printed: .RS .TP 15 .CR NAME The name and description of the parameter. .TP .CR VALUE The current value of the parameter. .TP .CR BOOT The value of the parameter at boot time, if different from the current value. .TP .CR MIN The minimum allowed value of the parameter, if any. .TP .CR MAX The maximum allowed value of the parameter, if any. .TP .CR UNITS Where appropriate, the units by which the parameter is measured. .TP .CR FLAGS Flags that further describe the parameter. The following flag is defined: .RS .TP 3 .CR M Parameter can be modified without rebooting. .RE .RE .SH EXAMPLES Analyze the system using the .CR /stand/vmunix kernel file: .IP .CR sysdef .PP Analyze the system using the kernel file .CR /os_file : .IP .C "sysdef /os_file" .SH WARNINGS Users of .C sysdef must not rely on the exact field widths and spacing of its output, as these will vary depending on the system, the release of HP-UX, and the data to be displayed. .SH FILES .TP 30 .CR /stand/vmunix Default kernel file .TP .CR /usr/conf/master.d Directory containing master files .\" .\" toc@\f3sysdef(1M)\f1:\0\0\f4sysdef\f1@@@display system definition .\" .\" index@\f4sysdef\f1 \- display system definition@@@\f3sysdef(1M)\f1 .\" index@display system definition@@@\f3sysdef(1M)\f1 .\" index@system definition, display@@@\f3sysdef(1M)\f1 .\" index@definition, display system@@@\f3sysdef(1M)\f1 .\" index@parameters, display system@@@\f3sysdef(1M)\f1 .\" index@tunable parameters, display system@@@\f3sysdef(1M)\f1 .\" index@kernel definition, display system@@@\f3sysdef(1M)\f1 .\" $Header: syslogd.1m,v 72.7 94/10/27 14:27:29 ssa Exp $ .TA s .TH syslogd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME syslogd \- log system messages .SH SYNOPSIS .CR /usr/sbin/syslogd .RC [ \-d ] .RC [ \-D ] .RC [ \-f .IR configfile ] .RC [ \-m .IR markinterval ] .SH DESCRIPTION The .CR syslogd command reads and logs messages into a set of files described by the configuration file .CR /etc/syslog.conf . .SS Options .CR syslogd recognizes the following options: .RS .TP 20 .CR \-d Turn on debugging. .TP .CR \-D Prevent the kernel from directly printing its messages on the system console. In this case, .CR syslogd is responsible for routing all kernel messages to their proper destination. .TP .CI \-f \0configfile Use .I configfile instead of .CR /etc/syslog.conf . .TP .CI \-m \0markinterval Wait .I markinterval minutes between mark messages, instead of 20 minutes. .RE .PP .CR syslogd creates the file .CR /var/run/syslog.pid , if possible, containing a single line with its process ID. This can be used to kill or reconfigure .CR syslogd . .PP To kill .CR syslogd , send it a terminate signal: .IP .C "kill `cat /var/run/syslog.pid`" .PP To make .CR syslogd , re-read its configuration file, send it a .CR HANGUP signal: .IP .C "kill \-HUP `cat /var/run/syslog.pid`" .PP .CR syslogd collects messages from the UNIX domain socket .CR /dev/log.un , an Internet domain socket specified in .CR /etc/services , the named pipe .CR /dev/log , and from the kernel log device .CR /dev/klog . By default, local programs calling .CR syslog() send log messages to the UNIX domain socket (see .IR syslog (3C)). If UNIX domain sockets are not configured on the system, they write to the named pipe instead. If INET domain sockets are not configured, .CR syslogd does not receive messages forwarded from other hosts, nor does it forward messages (see below). .PP Each message is one line. A message can contain a priority code, marked by a number in angle braces at the beginning of the line. Priorities are defined in the header file .CR . .PP .CR syslogd configures itself when it starts up and whenever it receives a hangup signal. Lines in the configuration file consist of a .I selector to determine the message priorities to which the line applies and an .IR action . The .I action field is separated from the selector by one or more tabs. .PP Selectors are semicolon separated lists of priority specifiers. Each priority has a .I facility indicating the subsystem that generated the message, a dot, and a .I level indicating the severity of the message. Symbolic names can be used. An asterisk selects all facilities. All messages of the specified level or higher (greater severity) are selected. More than one facility can be selected, using commas to separate them. For example: .IP .C "*.emerg;mail,daemon.crit" .PP selects all facilities at the .CR emerg level and the .CR mail and .CR daemon facilities at the .CR crit level. .PP The known facilities and levels recognized by .CR syslogd are those listed in .IR syslog (3C) converted to lowercase without the leading .CR LOG_ . The additional facility .CR mark has a message at priority .CR LOG_INFO sent to it every 20 minutes (this can be changed with the .CR \-m flag). The .CR mark facility is not enabled by a facility field containing an asterisk. The level .CR none can be used to disable a particular facility. For example, .IP .C "*.debug;mail.none" .PP selects all messages except .CR mail messages. .PP The second part of each line describes where the message is to be logged if this line is selected. There are four forms: .RS .TP 3 \(bu A file name (beginning with a leading slash). The file is opened in append mode. If the file does not exist, it is created. .TP \(bu A host name preceded by an .ift \f4\s+1@\s0\fP .ifn \f3@\fP character. Selected messages are forwarded to the .CR syslogd on the named host. .TP \(bu A comma-separated list of users. Selected messages are written to those users' terminals if they are logged in. .TP \(bu An asterisk. Selected messages are written to the terminals of all logged-in users. .RE .PP Blank lines and lines beginning with a .CR # character are ignored. .PP For example, the configuration file: .RS .nf .PP .C "kern,mark.debug /dev/console" .C "mail.debug /var/adm/syslog/mail.log" .C "*.info;mail.none /var/adm/syslog/syslog.log" .C "*.alert /dev/console" .C "*.alert root,eric,kridle" .C "*.emerg *" .C "*.emerg @admin" .fi .RE .PP logs all kernel messages and 20 minute marks onto the system console, all mail system messages to .CR /var/adm/syslog/mail.log , and all messages at .CR info and above, except mail messages, to the file .CR /var/adm/syslog/syslog.log . Messages at .CR alert and above are logged to the console and to the users .CR root , .CR eric , and .CR kridle if they are logged in. .CR emerg messages are written to all logged-in users' terminals, and forwarded to the host .CR admin . .PP Only a superuser can invoke .CR syslogd . .\" EDITOR: This section was commented out in 10.0 merge because .\" /etc/netlinkrc is obsolete in 10.0 and no comment was .\" immediately available from the B1/BLS group. -allanp .\" #ifdef B1 .\" .PP .\" .CR syslogd .\" can be started from the .\" .CR /etc/netlinkrc .\" script with the following command: .\" .IP .\" .C "epa \-l root \-c syshi \-s syshi /usr/sbin/syslogd" .\" #endif .SH WARNINGS A configuration file selector selects all messages at the specified level .IR "or higher" . The configuration lines: .nf .IP .C "user.debug /tmp/logfile" .C "user.info /tmp/logfile" .fi .PP cause the logfile to get .I two copies of all .CR user messages at level .CR info and above. .PP Kernel panic messages are not sent to .CR syslogd. .PP All HP-UX kernel messages are treated as if they had the .CR crit priority level. .PP If .CR syslogd is invoked with the .CR \-D option and .CR syslogd terminates abnormally, kernel messages will not appear on the system console. In that case, reinvoke .CR syslogd without the .CR \-D option to enable the kernel to send its messages to the system console. .SH DEPENDENCIES .SS Series 700 Kernel logging through the special log device .CR /dev/klog is not supported. .PP The .CR \-D option is not supported. .SH AUTHOR .CR syslogd was developed by the University of California, Berkeley. .SH FILES .TP 30 .PD 0 .CR /dev/klog The kernel log device .TP .CR /dev/log The named pipe on which .CR syslogd reads log messages .TP .CR /dev/log.un The UNIX domain socket on which .CR syslogd reads log messages .TP .CR /etc/syslog.conf Configuration file .TP .CR /var/run/syslog.pid Process ID .PD .SH SEE ALSO logger(1), syslog(3C). .\" .\" index@\f4syslogd\f1 \- log system messages@@@\f3syslogd(1M)\f1 .\" index@log system messages@@@\f3syslogd(1M)\f1 .\" index@system messages, log@@@\f3syslogd(1M)\f1 .\" index@messages from system, log@@@\f3syslogd(1M)\f1 .\" .\" toc@\f3syslogd(1M)\f1:\0\0\f4syslogd\f1@@@log systems messages .\" $Header: talkd.1m,v 76.2 95/06/12 14:01:09 ssa Exp $ .TA t .TH talkd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" Copyright (c) 1983, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)talkd.8 8.1 (Berkeley) 6/4/93 .\" .SH NAME talkd \- remote user communication server .SH SYNOPSIS .C talkd .SH DESCRIPTION .CR Talkd is the server that notifies a user that someone wants to initiate a conversation. It acts as a repository of invitations, responding to requests by clients wishing to initiate a conversation. To initiate a conversation, the client (the .CR talk command) sends a message of type LOOK_UP to the server (see .CR /usr/include/protocols/talkd.h ). This causes the server to search its invitation table to check if an invitation currently exists for the caller to talk to the callee specified in the message. If the lookup fails, the caller then sends a message of type ANNOUNCE, which causes the server to display an announcement on the callee's terminal requesting contact. When the callee responds, the local server uses the recorded invitation to respond with the appropriate rendezvous address and the caller and callee client programs establish a stream connection through which the conversation takes place. .PP To activate the talk service, the following entry must be added to the .CR /etc/inetd.conf file: .sp .RS .I ntalk dgram udp wait root /usr/lbin/ntalkd ntalkd .RE .SH SEE ALSO talk(1), write(1). .\" .\" toc@\f3talkd(1M)\f1:\0\0\f4talkd\f1@@@remote user communication server .\" .\" .\" index@\f4talkd\f1 \- remote user communication server@@@\f3talkd(1M)\f1 .\" index@\f1remote user communication server@@@\f3talkd(1M)\f1 .\" $Header: telnetd.1m,v 78.1 96/01/03 12:04:36 ssa Exp $ .TA t .TH telnetd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME telnetd \- TELNET protocol server .SH SYNOPSIS .CR /usr/lbin/telnetd .RC [ \-b .RI [ bannerfile ]\|] .SH DESCRIPTION The .CR telnetd daemon executes a server that supports the DARPA standard TELNET virtual terminal protocol. The Internet daemon .RC ( inetd ) executes .CR telnetd when it receives a service request at the port listed in the services data base for .CR telnet using the .CR tcp protocol (see .IR inetd (1M) and .IR services (4)). .PP .CR telnetd operates by allocating a pseudo-terminal device (see .IR pty (7)) for a client, then creating a login process which has the slave side of the pseudo-terminal as .CR stdin , .CR stdout , and .CR stderr . .CR telnetd manipulates the master side of the pseudo-terminal, implementing the TELNET protocol, and passing characters between the client and login process. .PP When a TELNET session is started up, .CR telnetd sends TELNET options to the client side, indicating a willingness to do .I remote echo of characters, to .IR "suppress go ahead", and to receive .I terminal speed and .I terminal type information from the remote client. If the remote client is willing, the remote terminal type is propagated in the environment of the created login process. The pseudo-terminal allocated to the client is configured as a normal terminal for login, with the exception of echoing characters (see .IR tty (7)). .IP .CR telnetd is willing to .IR do : .IR echo , .IR binary , .IR "suppress go ahead" , and .IR "timing mark" . .IP .CR telnetd is willing to have the remote client .IR do : .IR binary , .IR "flow control" , .IR "terminal speed" , .IR "terminal type" , and .IR "suppress go ahead". .PP The flow control option permits applications running on a remote host to toggle the flow control on the local host. To toggle flow control for a .CR telnet session programmatically, the application program must first call the .CR tcgetattr function to get the current termios settings. For example, .IP .CR tcgetattr(filedes, \ &termios_p) .PP Then, the .CR c_iflag of the termios structure must have .CR IXON set(reset) to enable(disable) flow control. .PP Finally, the .CR tcsetattr function call can implement the change. For example, .IP .CR tcsetattr(filedes, \ TCSANOW, \ &termios_p) .PP To toggle the flow control interactively, the user can issue a .CR stty command using the input options .CR -ixon to disable, or .CR ixon to enable flow control. (see .IR stty(1)). .PP The terminal speed option permits applications running on a remote host to obtain the terminal speed of the local host session using either .IR ioctl or .IR stty. .PP The .CR telnet server also supports the TAC User ID (also known as the TAC Access Control System, or TACACS User ID) option, whereby users telneting to two or more consenting hosts may avoid going through a second login sequence. .PP To start .CR telnetd from the Internet daemon, the configuration file .CR /etc/inetd.conf must contain an entry as follows: .IP .C "telnet stream tcp nowait root /usr/lbin/telnetd telnetd" .PP To override the standard .CR telnetd login banner, specify a file containing a custom banner with the .CR \-b .I bannerfile option. For example, to use .CR /etc/issue as the login banner, have .CR inetd start .CR telnetd with the following lines in .CR /etc/inetd.conf .RC ( \e provides line continuation): .nf .IP .C "telnet stream tcp nowait root /usr/lbin/telnetd \e" .C " telnetd -b/etc/issue" .fi .PP If .I bannerfile is not specified, .CR telnetd does not print a login banner. .PP The system administrator can enable the TAC User ID option on servers designated as participating hosts by having .CR inetd start .CR telnetd with the .CR -t option in .CR /etc/inetd.conf : .IP .C "telnet stream tcp nowait root /usr/lbin/telnetd telnetd -t" .fi .PP In order for the TAC User ID option to work as specified, the system administrator must assign to all authorized users of the option the same login name and unique user ID (UUID) on every participating system to which they are allowed TAC User ID access. These same UUIDs should not be assigned to non-authorized users. .PP Users cannot use the feature on systems where their local and remote UUIDs differ, but they can always use the normal .CR telnet login sequence. Also, there may be a potential security breach where a user with one UUID may be able to gain entry to participating systems and accounts where that UUID is assigned to someone else, unless the above restrictions are followed. .PP A typical configuration may consist of one or more secure front-end systems and a network of participating hosts. Users who have successfully logged onto the front-end system may .CR telnet directly to any participating system without being prompted for another login. .PP .CR telnet uses the same files as .CR rlogin to verify participating systems and authorized users, .CR hosts.equiv and .rhosts . (See .IR host.equiv (4) and the network security section of the .IR "System Administration Tasks" manual, PN 2355-90051, for configuration details.) .SH DIAGNOSTICS If any error is encountered by .CR telnetd in establishing the connection, an error message is returned through the connection, after which the connection is closed and the server exits. Any errors generated by the login process or its descendents are passed through as ordinary data. .PP The following diagnostic messages are displayed by .CR telnetd : .RS .TP .C "All ptys on remote host in use" .IP The server was unable to obtain a pseudo-terminal for use with the login process. Either all pseudo-terminals were in use or the .CR pty driver has not been properly set up (see .IR pty (7)). .IP .I Next step: Check the .CR pty configuration of the host where .CR telnetd is executing. .TP .C "fork: No more processes" .IP .CR telnetd was unable to fork a process to handle the incoming connection. .IP .I Next step: Wait a period of time and try again. If this message persists, the server's host may have runaway processes that are using all the entries in the process table. .TP .CR "/usr/bin/login: " ... .IP The login program could not be started via .CI exec * () for the reason indicated (see .IR exec (2)). .RE .SH WARNINGS The terminal type name received from the remote client is converted to lowercase. .PP .CR telnetd never sends TELNET .I go ahead commands. .SH AUTHOR .CR telnetd was developed by the University of California, Berkeley. .SH SEE ALSO login(1), rlogin(1), telnet(1), inetd(1M), ioctl(2), hosts(4), inetd.conf(4), inetd.sec(4), services(4), pty(7), stty(1), tty(7). .PP DOD MIL_STD 1782. .PP RFC 854 for the TELNET protocol specification. .\" .\" index@\f4telnetd\f1 \- TELNET protocol server@@@\f3telnetd(1M)\f1 .\" index@TELNET protocol server@@@\f3telnetd(1M)\f1 .\" index@protocol server, TELNET@@@\f3telnetd(1M)\f1 .\" index@server, TELNET protocol@@@\f3telnetd(1M)\f1 .\" .\" toc@\f3telnetd(1M)\f1:\0\0\f4telnetd\f1@@@TELNET protocol server .\" $Header: tftpd.1m,v 72.6 94/12/09 15:07:35 ssa Exp $ " .TA t .TH tftpd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tftpd \- trivial file transfer protocol server .SH SYNOPSIS .CR /usr/lbin/tftpd .RC \|[ -R .IR retran-seconds ]\| .RC \|[ -T .IR total-seconds ]\| .RI \|[ path \0...]\| .SH DESCRIPTION .CR tftpd is a server that supports the Internet Trivial File Transfer Protocol (RFC783). The TFTP server operates at the port indicated in the .CR tftp service description (see .IR services (4)). The server is normally started by .CR inetd using the .CR /etc/inetd.conf file (see .IR inetd (1M) and .IR inetd.conf (4)). .PP The .CR -R option specifies the per-packet retransmission timeout, in seconds. The default value is 5 seconds. .PP The .CR -T option specifies the total retransmission timeout, in seconds. The default value is 25 seconds. .PP The .IR path parameter has the following effects: .RS 3 \" START OF STANDARD path DESCRIPTION .TP 3 \(bu .C tftpd operates in either of two modes or their combination. The first mode requires a defined home directory for the pseudo-user .CR tftp , and looks for files relative to that path. The second mode requires one or more .I paths be specified on the command line, and allows access only to files whose paths match or begin with one of the command line specifications. The first mode is backward-compatible with previous releases of HP-UX and supports somewhat tighter security. The second mode is compatible with other vendors' implementations of .C tftpd and allows greater flexibility in accessing files. .TP \(bu If no .IR path is specified on the command line, .CR tftpd requires an entry in the .CR /etc/passwd database (see .IR passwd (4)) for an account (pseudo-user) named .CR tftp . The password field should be .CR * , the group membership should be .CR guest , and the login shell should be .CR /usr/bin/false . For example: .RS .IP .C "tftp:*:510:guest:tftp server:/home/tftpdir:/usr/bin/false" .RE .IP .CR tftpd uses a call to .CR chroot() to change its root directory to be the same as the home directory of the pseudo-user .CR tftp . This restricts access by .CR tftp clients to only those files found below the .CR tftp home directory (see .IR chroot (2)). Furthermore, .CR tftp clients can only read files in that directory if they are readable by the pseudo-user .CR tftp , and .CR tftp clients can only write files in that directory if they exist and are writable by the pseudo-user .CR tftp . .TP \(bu If any .IR path is specified on the command line, .CR tftpd does not require that a pseudo-user named .CR tftp exist in .CR /etc/passwd . The specified .IR path s control access to files by .CR tftp clients. Each .IR path is treated as being relative to .CR / (not the .CR tftp home directory), and can be either a directory or a file. .CR tftpd disallows a client access to any file that does not match entirely or in its initial components one of the restriction .IR path s. It also disallows access to any file path containing .RC `` .. ''. However, an accessed file can be a symbolic link that points outside the set of restricted paths. .TP \(bu If any .IR path is specified on the command line and the .CR tftp home directory is defined and is not .CR / , .CR tftpd first looks for a file relative to (under) the home directory. If the file is not found there, then .CR tftpd looks for the file relative to .CR / with path restrictions applied. Thus if two files with the same name can be found in both locations, .CR tftpd accesses the one under .CR tftp 's home directory. .RE \" END OF STANDARD path DESCRIPTION .PP Note that .C inetd allows continuation of command lines in .C inetd.conf by ending continued lines with a backlash. .PP Defining the .CR tftp pseudo-user is strongly recommended even when .IR path s are specified, because client access is further restricted to files that can be read and/or written by this pseudo-user. It is safe to set the .CR tftp pseudo-user's home directory to .CR / in this case. .SH DIAGNOSTICS The following diagnostics are logged to the .CR syslogd facility at the .CR err log level (see .IR syslogd (1M)). .RS .TP .C "No security mechanism exists" The pseudo-user .CR tftp was not found in the password database .RC ( /etc/passwd ), and .CR tftpd was invoked without any .IR path arguments. .IP Add or correct the entry for the pseudo-user .CR tftp in the password database .CR /etc/passwd . Or, add an access list .RI ( path arguments) to the .CR tftpd arguments in the .CR inetd configuration file .CR /etc/inetd.conf . Reconfigure .CR inetd with the command .CR "inetd -c" . .TP .CI "Unknown option \&" option " ignored" An invalid option was specified in the .CR tftpd arguments in the .CR inetd configuration file .CR /etc/inetd.conf . .IP Remove or correct the option. Restart .CR inetd with the command .CR "inetd -c" . .TP .CI "Invalid total timeout \&" value The value given for the .CR -T option was not a number or was a negative number. .IP Correct the value given for the .CR -T option. Reconfigure .CR inetd with the command .CR "inetd -c" . .TP .CI "Invalid retransmission timeout \&" value The value given for the .CR -R option was not a number or was a negative number. .IP Correct the value given for the .CR -R option. Reconfigure .CR inetd with the command .CR "inetd -c" . .TP .IC "system call" ":" The named .IR "system call" failed. See the corresponding manual entry for a description of the system call. The reason for the failure is explained in the error message appended to the system call. .RE .SH WARNINGS When invoked with no .IR path arguments, .CR tftpd cannot follow symbolic links that refer to paths outside of the home directory of the pseudo-user .CR tftp , because it performs a .CR chroot() . .SH AUTHOR .CR tftpd was developed by the University of California, Berkeley, and Hewlett-Packard. .SH SEE ALSO tftp(1), inetd(1M), syslogd(1M), chroot(2), inetd.conf(4), passwd(4). .\" .\" toc@\f3tftpd(1M)\f1:\0\0\f4tftpd\f1@@@trivial file transfer protocol server .\" .\" index@\f4tftpd\f1 \- trivial file transfer protocol server@@@\f3tftpd(1M)\f1 .\" index@\f1trivial file transfer protocol server@@@\f3tftpd(1M)\f1 .\" index@\f1file transfer protocol server, trivial@@@\f3tftpd(1M)\f1 .\" index@\f1transfer protocol server, trivial file@@@\f3tftpd(1M)\f1 .\" index@\f1protocol server, trivial file transfer@@@\f3tftpd(1M)\f1 .\" index@\f1server, trivial file transfer protocol@@@\f3tftpd(1M)\f1 .\" .\" fileset_database@tftpd.1m INETSVCS-MAN .\" $Header: tic.1m,v 72.5 94/11/14 15:23:37 ssa Exp $ .TA t .TH tic 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tic \- terminfo compiler .SH SYNOPSIS .CR tic .RC [ -v .RI [ n ] ] .IR file \0... .SH DESCRIPTION .CR tic translates terminfo files from source format into the compiled format. Results are placed in the directory .CR /usr/share/lib/terminfo . .PP The .CR -v (verbose) option causes .CR tic to output trace information showing its progress. If the optional integer .I n is appended, the level of verbosity can be increased. .PP .CR tic compiles all terminfo descriptions in the given files. When a .CR use= field is discovered, .CR tic searches first the current file, then the master file which is .CR ./terminfo.src . .PP If the environment variable .CR TERMINFO is set, the results are placed in the location specified by .CR TERMINFO instead of in .CR /usr/share/lib/terminfo . .PP Limitations: total compiled entries cannot exceed 4096 bytes. The name field cannot exceed 128 bytes. .SH FILES .TP 35 .CR /usr/share/lib/terminfo/?/* compiled terminal capability data base .SH SEE ALSO untic(1M), curses(3X), terminfo(4). .SH BUGS Instead of searching .CR ./terminfo.src , .CR tic should check for an existing compiled entry. .SH STANDARDS CONFORMANCE .CR tic ": SVID2, SVID3" .\" .\" index@\f4tic\f1 \- terminfo data base compiler@@@\f3tic(1M)\f1 .\" index@terminfo data base compiler@@@\f3tic(1M)\f1 .\" index@compilers: terminfo data base compiler@@@\f3tic(1M)\f1 .\" index@data base compiler, terminfo@@@\f3tic(1M)\f1 .\" .\" toc@\f3tic(1M)\f1:\0\0\f4tic\f1@@@terminfo compiler .\" .\" fileset_database@tic.1m SYS-ADMIN-MAN .\" $Header: tsm.lpadmin.1m,v 72.7 94/09/22 09:53:50 ssa Exp $ .TA t .TH tsm.lpadmin 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tsm.lpadmin \- add or remove a printer for use with \f2tsm\f1(1) .SH SYNOPSIS .C /usr/tsm/bin/tsm.lpadmin -p .I printer .C -m .I model .br .C /usr/tsm/bin/tsm.lpadmin -x .I printer .SH DESCRIPTION .CR tsm.lpadmin is used to add (or remove) a printer to the LP spooling system when the printer is connected to the system through a terminal running the Terminal Session Manager (see .IR tsm (1)). .CR tsm.lpadmin is a shell script that uses .CR lpadmin in the normal way but also creates a named pipe to which LP output is directed (see .IR lpadmin (1)). This named pipe is opened by TSM and data flowing from it is sent to the printer through the terminal. .SS Options .CR tsm.lpadmin recognizes the following options: .RS .TP 15 .CI -p \0printer Names a printer to be created with an associated pipe. If .CR -p is used, .CR -m must also be specified. .TP .CI -m \0model Selects a model interface program for .IR printer . .IR model is one of the model interface names supplied with the LP software (see the Models topic in the .IR lpadmin (1)) manual entry. If .CR -m is used, .CR -p must also be specified. .TP .CI -x \0printer Removes .IR printer from the LP system. No other options are allowed with .CR -x . .RE .SS Restrictions To use .CR tsm.lpadmin you must be user .CR lp or .CR root . .SH AUTHOR .CR tsm.lpadmin was developed by HP. .SH FILES .CR /var/spool/lp/tsm.pipes/* .SH SEE ALSO lpadmin(1M), tsm(1). .\" .\" index@\f4tsm.lpadmin\f1 \- add or remove a printer for use with \f4tsm\f1(1)@@@\f3tsm.lpadmin(1M)\f1 .\" index@\f1add a printer for use with \f4tsm\f1(1)@@@\f3tsm.lpadmin(1M)\f1 .\" index@\f1remove a printer for use with \f4tsm\f1(1), add@@@\f3tsm.lpadmin(1M)\f1 .\" index@\f1printer for use with \f4tsm\f1(1), add or remove a@@@\f3tsm.lpadmin(1M)\f1 .\" index@\f4tsm\f1(1), add or remove a printer for use with@@@\f3tsm.lpadmin(1M)\f1 .\" .\" toc@\f3tsm.lpadmin(1M)\f1:\0\0\f4tsm.lpadmin\f1@@@add or remove a printer for use with \f4tsm\f1(1) .\" .\" fileset_database@tsm.lpadmin.1m SYS-ADMIN-MAN .\" $Header: tunefs.1m,v 72.5 94/11/29 05:59:01 ssa Exp $ .TA t .TH tunefs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tunefs \- tune up an existing HFS file system .SH SYNOPSIS .C /usr/sbin/tunefs .RC [ -A ] .RC [ -v ] .RC [ -a .IR maxcontig\| ] .RC [ -d .IR rotdelay\| ] .ifn .br .ifn \0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0 .RC [ -e .IR maxbpg\| ] .RC [ -m .IR minfree\| ] .I special-device .SH DESCRIPTION The .C tunefs command is used to alter dynamic parameters that affect HFS file system layout policies. Parameters to be altered are specified by the options and arguments provided on the command line as described below. .PP .C tunefs affects how the file system blocks are laid out on the disk. The default .I rotdelay value set by the .C newfs and .C mkfs commands (see .IR newfs (1M) and .IR mkfs (1M)) is 0 milliseconds, causing file system blocks to be written and read consecutively. In general, this should be the optimal tuning, making the use of .C tunefs -d unnecessary. .SS Options .C tunefs recognizes the following options and command-line arguments: .RS .TP 15 .CI -a " maxcontig" Set the maximum number of contiguous blocks that will be laid out before forcing a rotational delay to .I maxcontig (see .C -d below). The default value is .CR 1 , because most device drivers require one interrupt per disk transfer. For device drivers that can chain several buffers together in a single transfer, set .I maxcontig to the maximum chain length. .TP .CI -d " rotdelay" .I rotdelay is the expected time (in milliseconds) to service a transfer completion interrupt and initiate a new transfer on the same disk. It is used to determine how much rotational spacing to place between successive blocks in a file. .TP .CI -e " maxbpg" .I maxbpg specifies the maximum number of blocks any single file can allocate out of a cylinder group before it is forced to begin allocating blocks from another cylinder group. Typically this value is set to about one fourth of the total blocks in a cylinder group. The intent is to prevent any single file from using up all the blocks in a single cylinder group, thus degrading access times for all files subsequently allocated in that cylinder group. The effect of this limit is to cause large files to do long seeks more frequently than if they were allowed to allocate all the blocks in a cylinder group before seeking elsewhere. For file systems with exclusively large files, this parameter should be set higher. .TP .CI -m " minfree" .I minfree specifies the percentage of space that is not available to normal users; i.e., the minimum free space threshold. The default value used is 10%. This value can be set to zero. If set to zero, throughput performance drops to as little as one-third of the efficiency expected when the threshold is set at 10%. Note that if .I minfree is raised above the current usage level, users cannot allocate files until enough files have been deleted to meet the new threshold requirement. .TP .C -v (visual) Display current values contained in the primary super-block to standard output. .TP .C -A (all) Modify redundant super-blocks as well as the primary super-block as stipulated by the configuration options and arguments. .TP .I special-device is the name of the file system to be tuned. It is either a block or character special file if the file system is not mounted, or a block special file if the file system is mounted. .SH WARNINGS .PP Root file system tuning is normally done during initial system software installation. Tuning the root file system after installation has little useful effect because so many files have already been written. .PP You can tune a file system, but you can't tune a fish. .SH AUTHOR .C tunefs was developed by the University of California, Berkeley. .SH SEE ALSO dumpfs(1M), mkfs(1M), newfs(1M), fs(4). .\" index@\f4tunefs\f1 \- tune up an existing HFS file system@@@\f3tunefs(1M)\f1 .\" index@optimize an existing HFS file system@@@\f3tunefs(1M)\f1 .\" index@file system: optimize an existing HFS file system@@@\f3tunefs(1M)\f1 .\" index@file system: tune an existing HFS file system@@@\f3tunefs(1M)\f1 .\" index@HFS file system: tune an existing file system@@@\f3tunefs(1M)\f1 .\" .\" links@tunefs.1m tunefs_hfs.1m .\" toc@\f3tunefs(1M)\f1:\0\0\f4tunefs\f1@@@tune up an existing HFS file system .\" $Header: tunefs.1m,v 72.5 94/11/29 05:59:01 ssa Exp $ .TA t .TH tunefs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tunefs \- tune up an existing HFS file system .SH SYNOPSIS .C /usr/sbin/tunefs .RC [ -A ] .RC [ -v ] .RC [ -a .IR maxcontig\| ] .RC [ -d .IR rotdelay\| ] .ifn .br .ifn \0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0 .RC [ -e .IR maxbpg\| ] .RC [ -m .IR minfree\| ] .I special-device .SH DESCRIPTION The .C tunefs command is used to alter dynamic parameters that affect HFS file system layout policies. Parameters to be altered are specified by the options and arguments provided on the command line as described below. .PP .C tunefs affects how the file system blocks are laid out on the disk. The default .I rotdelay value set by the .C newfs and .C mkfs commands (see .IR newfs (1M) and .IR mkfs (1M)) is 0 milliseconds, causing file system blocks to be written and read consecutively. In general, this should be the optimal tuning, making the use of .C tunefs -d unnecessary. .SS Options .C tunefs recognizes the following options and command-line arguments: .RS .TP 15 .CI -a " maxcontig" Set the maximum number of contiguous blocks that will be laid out before forcing a rotational delay to .I maxcontig (see .C -d below). The default value is .CR 1 , because most device drivers require one interrupt per disk transfer. For device drivers that can chain several buffers together in a single transfer, set .I maxcontig to the maximum chain length. .TP .CI -d " rotdelay" .I rotdelay is the expected time (in milliseconds) to service a transfer completion interrupt and initiate a new transfer on the same disk. It is used to determine how much rotational spacing to place between successive blocks in a file. .TP .CI -e " maxbpg" .I maxbpg specifies the maximum number of blocks any single file can allocate out of a cylinder group before it is forced to begin allocating blocks from another cylinder group. Typically this value is set to about one fourth of the total blocks in a cylinder group. The intent is to prevent any single file from using up all the blocks in a single cylinder group, thus degrading access times for all files subsequently allocated in that cylinder group. The effect of this limit is to cause large files to do long seeks more frequently than if they were allowed to allocate all the blocks in a cylinder group before seeking elsewhere. For file systems with exclusively large files, this parameter should be set higher. .TP .CI -m " minfree" .I minfree specifies the percentage of space that is not available to normal users; i.e., the minimum free space threshold. The default value used is 10%. This value can be set to zero. If set to zero, throughput performance drops to as little as one-third of the efficiency expected when the threshold is set at 10%. Note that if .I minfree is raised above the current usage level, users cannot allocate files until enough files have been deleted to meet the new threshold requirement. .TP .C -v (visual) Display current values contained in the primary super-block to standard output. .TP .C -A (all) Modify redundant super-blocks as well as the primary super-block as stipulated by the configuration options and arguments. .TP .I special-device is the name of the file system to be tuned. It is either a block or character special file if the file system is not mounted, or a block special file if the file system is mounted. .SH WARNINGS .PP Root file system tuning is normally done during initial system software installation. Tuning the root file system after installation has little useful effect because so many files have already been written. .PP You can tune a file system, but you can't tune a fish. .SH AUTHOR .C tunefs was developed by the University of California, Berkeley. .SH SEE ALSO dumpfs(1M), mkfs(1M), newfs(1M), fs(4). .\" index@\f4tunefs\f1 \- tune up an existing HFS file system@@@\f3tunefs(1M)\f1 .\" index@optimize an existing HFS file system@@@\f3tunefs(1M)\f1 .\" index@file system: optimize an existing HFS file system@@@\f3tunefs(1M)\f1 .\" index@file system: tune an existing HFS file system@@@\f3tunefs(1M)\f1 .\" index@HFS file system: tune an existing file system@@@\f3tunefs(1M)\f1 .\" .\" links@tunefs.1m tunefs_hfs.1m .\" toc@\f3tunefs(1M)\f1:\0\0\f4tunefs\f1@@@tune up an existing HFS file system .\" $Header: acctsh.1m,v 72.4 94/11/14 12:02:10 ssa Exp $ .TA a .TH acctsh 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chargefee, ckpacct, dodisk, lastlogin, monacct, nulladm, prctmp, prdaily, prtacct, shutacct, startup, turnacct \- shell procedures for accounting .SH SYNOPSIS .C /usr/sbin/acct/chargefee .I login-name number .PP .C /usr/sbin/acct/ckpacct .RI [ \|blocks\| ] .PP .C /usr/sbin/acct/dodisk .RC [ -o ] .RI [ \|files \0 ...\|] .PP .C /usr/sbin/acct/lastlogin .PP .C /usr/sbin/acct/monacct .I number .PP .C /usr/sbin/acct/nulladm .I file .PP .C /usr/sbin/acct/prctmp .PP .C /usr/sbin/acct/prdaily .RC [ -l ] .RC [ -c ] .RC [ \c .IR mmdd\| ] .PP .C /usr/sbin/acct/prtacct .I file .RI [ \|heading\| ] .PP .C /usr/sbin/acct/shutacct .RI [ \|reason\| ] .PP .C /usr/sbin/acct/startup .PP .C /usr/sbin/acct/turnacct .CR on \0\(or\0 off \0\(or\0 switch .SH DESCRIPTION .TP 15 .C chargefee Can be invoked to charge a .I number of units to .IR login-name . A record is written to .CR /var/adm/fee , to be merged with other accounting records during the night. .TP .C ckpacct Should be initiated via .IR cron (1M). It periodically checks the size of .CR /var/adm/pacct . If the size exceeds .IR blocks , 1000 by default, .C turnacct is invoked with argument .IR switch . If the number of free disk blocks in the .C /var file system falls below 500, .C ckpacct automatically turns off the collection of process accounting records via the .C off argument to .CR turnacct . When at least this number of blocks is restored, the accounting will be activated again. This feature is sensitive to the frequency at which .C ckpacct is executed, usually by .CR cron . .TP .C dodisk Should be invoked by .C cron to perform the disk accounting functions. By default, it will do disk accounting on the special files in .C /etc/fstab. If the .C -o flag is used, it does a slower version of disk accounting by login directory. .I files specifies the one or more filesystem names where disk accounting is to be done. If .I files is used, disk accounting will be done on these filesystems only. If the .C -o flag is used, .I files should be mount points of mounted filesystem. If omitted, they should be the special file names of mountable filesystems. .TP .C lastlogin Invoked by .C runacct to update .C /var/adm/acct/sum/loginlog which shows the last date on which each user logged in (see .IR runacct (1M)). .TP .C monacct Should be invoked once each month or each accounting period. .I number indicates which month or period it is. If .I number is not given, it defaults to the current month (01 through 12). This default is useful if .C monacct is to executed via .CR cron on the first day of each month. .C monacct creates summary files in .C /var/adm/acct/fiscal and restarts summary files in .CR /var/adm/acct/sum . .TP .C nulladm Creates .I file with mode 664 and ensures that owner and group are .CR adm . It is called by various accounting shell procedures. .TP .C prctmp Can be used to print the session record file normally .C /var/adm/acct/nite/ctmp created by .C acctcon1 (see .IR acctcon (1M)). .TP .C prdaily Invoked by .C runacct (see .IR runacct (1M)) to format a report of the previous day's accounting data. The report resides in .CI /var/adm/acct/sum/rprt mmdd where .I mmdd is the month and day of the report. The current daily accounting reports may be printed by typing .IR prdaily . Previous days' accounting reports can be printed by using the .I mmdd option and specifying the exact report date desired. The .C -l flag prints a report of exceptional usage by login id for the specifed date. Previous daily reports are cleaned up and therefore inaccessible after each invocation of .CR monacct . The .C -c flag prints a report of exceptional resource usage by command, and can be used on current day's accounting data only. .TP .C prtacct Can be used to format and print any total accounting .RC ( tacct ) file. .TP .C shutacct Should be invoked during a system shutdown to turn process accounting off and append a ``reason'' record to .CR /var/adm/wtmp . .TP .C startup Should be called by system startup scripts to turn the accounting on whenever the system is brought up. .TP .C turnacct An interface to .C accton (see .IR acct (1M)) to turn process accounting .C on or .CR off . The .C switch argument turns accounting off, moves the current .C /var/adm/pacct to the next free name in .CI /var/adm/pacct incr then turns accounting back on again. .RI ( incr is a number starting with .C 1 and incrementing by one for each additional .C pacct file.) .C turnacct is called by .CR ckpacct , and thus can be run under .C cron and used to keep .C pacct to a reasonable size. .SH FILES .TP 40 .C /usr/sbin/acct holds all accounting commands listed in section (1M) of this manual .PD 0 .TP .C /var/adm/fee accumulator for fees .TP .C /var/adm/acct/nite working directory .TP .C /var/adm/pacct current file for per-process accounting .TP .C /var/adm/pacct* used if .C pacct gets large, and during execution of daily accounting procedure .TP .C /usr/sbin/acct/ptecms.awk contains the limits for exceptional usage by command name .TP .C /usr/sbin/acct/ptelus.awk contains the limits for exceptional usage by login id .TP .C /var/adm/acct/sum summary directory, should be saved .TP .C /var/adm/wtmp login/logoff summary .PD .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), cron(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .SH STANDARDS CONFORMANCE .CR chargefee ": SVID2, SVID3" .PP .CR ckpacct ": SVID2, SVID3" .PP .CR dodisk ": SVID2, SVID3" .PP .CR lastlogin ": SVID2, SVID3" .PP .CR monacct ": SVID2, SVID3" .PP .CR prctmp ": SVID2, SVID3" .PP .CR prdaily ": SVID2, SVID3" .PP .CR prtacct ": SVID2, SVID3" .PP .CR shutacct ": SVID2, SVID3" .PP .CR startup ": SVID2, SVID3" .PP .CR turnacct ": SVID2, SVID3" .\" .\" .\" index@\f1process accounting@@@see accounting .\" index@\f1accounting: \f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: \f4turnacct\f1 \- turn on or turn off process accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f4chargefee\f1 \- charge fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1bill fee to user based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f1user, bill fee to, based on system usage@@@\f3acctsh(1M)\f1 .\" index@\f4ckpacct\f1 \- check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: check size of process accounting file@@@\f3acctsh(1M)\f1 .\" index@\f4dodisk\f1 \- perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1accounting: perform disk accounting@@@\f3acctsh(1M)\f1 .\" index@\f1disk accounting, perform@@@\f3acctsh(1M)\f1 .\" index@\f4lastlogin\f1 \- show last login date for each user@@@\f3acctsh(1M)\f1 .\" index@\f1user, show last login date for each@@@\f3acctsh(1M)\f1 .\" index@\f1last login date, show for each user@@@\f3acctsh(1M)\f1 .\" index@\f1login date, show last for each user@@@\f3acctsh(1M)\f1 .\" index@\f4monacct\f1 \- create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1create periodic accounting summary files@@@\f3acctsh(1M)\f1 .\" index@\f1periodic accounting summary files, create@@@\f3acctsh(1M)\f1 .\" index@\f1accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1files: accounting summary files, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f1summary files, accounting, create periodic@@@\f3acctsh(1M)\f1 .\" index@\f4nulladm\f1 \- create empty file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1create empty administration file owned by \f3adm\f1 with mode 664@@@\f3acctsh(1M)\f1 .\" index@\f1empty administration file owned by \f3adm\f1 with mode 664, create@@@\f3acctsh(1M)\f1 .\" index@\f1administration file owned by \f3adm\f1 with mode 664, create empty@@@\f3acctsh(1M)\f1 .\" index@\f4prctmp\f1 \- print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f4acctcon1\f1 \- print session record file created by@@@\f3acctsh(1M)\f1 .\" index@\f1print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1files, accounting: print session record file created by \f4acctcon1\f1@@@\f3acctsh(1M)\f1 .\" index@\f1session record file created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f1record file, session, created by \f4acctcon1\f1, print@@@\f3acctsh(1M)\f1 .\" index@\f4prdaily\f1 \- print daily accounting report@@@\f3acctsh(1M)\f1 .\" index@\f4prtacct\f1 \- print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1print any total accounting (\f4tacct\f1) file@@@\f3acctsh(1M)\f1 .\" index@\f1total accounting (\f4tacct\f1) file, print any@@@\f3acctsh(1M)\f1 .\" index@\f1accounting (\f4tacct\f1) file, print any total@@@\f3acctsh(1M)\f1 .\" index@\f4tacct\f1 (total accounting) file, print any@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting: \f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" index@\f4runacct\f1 \- accumulate accounting data and command usage summary@@@\f3acctsh(1M)\f1 .\" .\" index@\f1accounting data and command usage summary, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f1command usage summary and accounting data, accumulate@@@\f3acctsh(1M)\f1 .\" index@\f4shutacct\f1 \- turn off accounting for system shutdown@@@\f3acctsh(1M)\f1 .\" index@\f1system shutdown, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f1shutdown, system, turn accounting off for@@@\f3acctsh(1M)\f1 .\" index@\f4startup\f1 \- start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1start accounting process at system startup@@@\f3acctsh(1M)\f1 .\" index@\f1system startup, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f1startup, system, start accounting process at@@@\f3acctsh(1M)\f1 .\" index@\f4turnacct\f1 \- turn process accounting on or off@@@\f3acctsh(1M)\f1 .\" index@\f1shell procedures for system accounting@@@\f3acctsh(1M)\f1 .\" index@\f1system accounting, shell procedures for@@@\f3acctsh(1M)\f1 .\" .\"" Main TOC entry .\" toc@\f3acctsh(1M)\f1:\0\0\f4chargefee\f1, \f4ckpacct\f1, \f4dodisk\f1, \f4lastlogin\f1, \f4monacct\f1, \f4nulladm\f1, \f4prctmp\f1, \f4prdaily\f1,\n\f4prtacct\f1, \f4shutacct\f1, \f4startup\f1, \f4turnacct\f1@@@shell procedures for accounting .\" .\" toc@\f4chargefee\f1:\0\0shell procedures for accounting, charge fee to user@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4ckpacct\f1:\0\0shell procedures for accounting, check size of accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4dodisk\f1:\0\0shell procedures for accounting, perform disk accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4lastlogin\f1:\0\0shell procedures for accounting, show last login date@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4monacct\f1:\0\0shell procedures for accounting, create accounting summary@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4nulladm\f1:\0\0shell procedures for accounting, create null file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prctmp\f1:\0\0shell procedures for accounting, print session record file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prdaily\f1:\0\0shell procedures for accounting, print daily report@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4prtacct\f1:\0\0shell procedures for accounting, print accounting file@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4shutacct\f1:\0\0shell procedures for accounting, turn off accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4startup\f1:\0\0shell procedures for accounting, start up accounting@@@\f1see \f3acctsh(1M)\f1 .\" toc@\f4turnacct\f1:\0\0shell procedures for accounting, turn on or off process accounting@@@\f1see \f3acctsh(1M)\f1 .\" .\" links@acctsh.1m chargefee.1m .\" links@acctsh.1m ckpacct.1m .\" links@acctsh.1m dodisk.1m .\" links@acctsh.1m lastlogin.1m .\" links@acctsh.1m monacct.1m .\" links@acctsh.1m nulladm.1m .\" links@acctsh.1m prctmp.1m .\" links@acctsh.1m prdaily.1m .\" links@acctsh.1m prtacct.1m .\" links@acctsh.1m shutacct.1m .\" links@acctsh.1m startup.1m .\" links@acctsh.1m turnacct.1m .\" .\" fileset_database@acctsh.1m SYS-ADMIN-MAN .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for .\" the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" Copyright (C) 1989, 1991, Transarc Corporation ...\" The Gulf Tower ...\" 707 Grant Street ...\" Pittsburgh, PA 15219 ...\" .rm zA .rm zZ .TH "udebug" "1m" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "defect,8393,R1.0.3,Document the udebug command" .iX "-[" "\*Ludebug\*O command" .iX "-[" "Ubik" "listing status" .SH NAME .PP \*Ludebug\*O \- Displays Ubik status information relevant to the specified DFS database server .SH "SYNOPSIS" .sS \*Ludebug -rpcgroup \*VRPC_server_group\*O [\*L\-server \*Vmachine\*O] [\*L\-long\*O] [\*L\-help\*O] .sE .SH "OPTIONS" .VL .LI "\*L\-rpcgroup \*VRPC_server_group\*O" Specifies the RPC server group of the Ubik database servers whose status information you want to display. By convention, this is \*L/.:/fs\*O for the \*Lflserver\*O processes and \*L/.:/subsys/dce/dfs/bak\*O for the \*Lbakserver\*O processes. .LI "\*L\-server \*Vmachine\*O" Names the machine containing the database server whose Ubik status information is to be displayed; if a machine name is omitted, the command uses the name of the local machine. Specify the server machine using the full DCE pathname, abbreviated host name, or IP address. .LI "\*L\-long\*O" Directs the command to provide additional information about the other database servers in the specified RPC server group. This flag is \*Enot\*O necessary if the server specified with the \*L\-server\*O option is the Ubik synchronization site because the information about the other database servers is provided automatically. .LI "\*L\-help\*O" Prints the online help for this command. All other valid options specified with this option are ignored. .LE .SH "DESCRIPTION" .PP The \*Ludebug\*O command displays Ubik status information on the specified server in the specified RPC server group. If the specified server is the synchronization site or the \*L\-long\*O flag is used with the command, the command displays information on all of the servers in the RPC server group. .PP .SS "Privilege Required" .PP No privileges are required. .SH "OUTPUT" .PP The output for the \*Ludebug\*O command always provides the following information for the specified database server: .ML .LI The IP address of the specified server machine. In the first example, this is \*C192.56.207.146\*O. .LI The difference in seconds between the clock on the specified server machine and the machine on which the \*Ludebug\*O command was run. In the first example, this is \*C0\*O. .nS "Note" If the message \*C****clock\*O \*Cmay\*O \*Cbe\*O \*Cbad\*O appears, the difference between the two clocks is greater than 40 seconds, and you must synchronize the clocks on all of the server machines in the RPC server group. .nE .LI The IP address of the server machine that this server voted for to be the synchronization site and the time that the vote was cast. In the first example, this is \*C192.56.207.26\*O at \*C-10\*O. .nS "Note" Unless noted otherwise, all time is calculated and displayed as the number of seconds before (negative) or after (positive) the current time according to the clock on the local machine on which the \*Ludebug\*O command is run. .nE .LI The time at which the last round of sync-site voting began. In the first example, this is \*C\-11\*O. .LI The version of the database in use on this server machine. In the first example, this is \*C750478963.1\*O. .LI Whether the server is the synchronization site; if it is, the duration of the synchronization site status and the number of servers in the RPC server group are also provided. In the first example, the message \*CI\*O \*Cam\*O \*Cnot\*O \*Csync\*O \*Csite\*O indicates that the server is not the sync site. .LI If the server is \*Enot\*O the synchronization site, the following information is displayed: .ML .LI The IP address of the lowest server in the RPC server group and the time that a beacon was last sent from that server to the specified server. In the first example, this is \*C192.56.207.26\*O at \*C-10\*O. .LI The IP address of the synchronization site and the time that a beacon was last sent from that server. In the first example, this is \*C192.56.207.26\*O at \*C-10\*O. .LE .P If the server is the synchronization site, the current state of the server is displayed, using one of the following flags. In the second example, this is \*C1f\*O. .ML .LI 1 \- Indicates that the server is the synchronization site. .LI 3 \- Indicates that the server is the synchronization site and that it has found the latest version of the database. .LI 7 \- Indicates that the server is the synchronization site and that it has fetched the latest version of the database. .LI f \- Indicates that the server is the synchronization site and a quorum has been reached in the RPC server group, but the synchronization site has not distributed the latest version of the database to all servers in the RPC server group. .LI 1f \- Indicates that server is the synchronization site, a quorum has been reached in the RPC server group, and the synchronization site has distributed the latest version of the database to all servers in the RPC server group. .LE .LI The version of the database in use at the synchronization site. In the first example, this is \*C750478963.1\*O. .LI The total number of database pages locked and the number of database pages locked for write purposes on the server. (Anything other than a 0 indicates database activity.) In the first example, this is \*C0\*O and \*C0\*O. .LI The time that the server was the synchronization site, if it ever has been, or a message indicating that the server has never been the synchronization site. In the first example, the message \*CThis\*O \*Cserver\*O \*Chas\*O \*Cnever\*O \*Cbeen\*O \*Csync\*O \*Csite\*O indicates that the server has never been the synchronization site. .LE If the \*Ludebug\*O command specifies the synchronization site of the RPC server group or if the \*L\-long\*O option is used with the command, the following additional information is displayed for each of the other database servers in the RPC server group: .ML .LI The IP address of each server machine. In the second example, the first server machine listed has the IP address \*C192.56.207.36\*O. .LI The version of the database in use on each server machine. (A 0.0 indicates that the server does not have a version of the database.) In the second example, the first server listed uses the database version \*C750478963.1\*O. .LI The last time a vote was received from this server by the server specified with the \*L\-server\*O option. In the second example, the server with IP address \*C192.56.207.26\*O received a vote from the first server with IP address \*C192.56.207.36\*O at \*C-8\*O. .LI The last time a beacon requesting a vote was sent to each server. In the second example, the first server received a beacon at \*C-9\*O. .LI The last vote, yes or no, cast by each server. In the second example, the first server cast a \*Cyes\*O vote. .LI A flag (\*Cdbcurrent\*O) indicating whether the version of the database in use on each server machine is current with the synchronization site; 0 indicates no, 1 indicates yes. In the second example, the first server has a current version of the database. .LI A flag (\*Cup\*O) indicating whether the corresponding server process on each server machine is up; 0 indicates no, 1 indicates yes. In the second example, the first server is up. .LI A flag (\*CbeaconSince\*O) indicating whether a response (vote) to the latest beacon was sent by each server to the synchronization site. In the second example, the first server sent a response to the latest beacon. .LE .PP .SH "EXAMPLES" .PP The following command displays information on a specified database server that is not a synchronization site: .iS \*C$\*O \*Ludebug /.:/fs fs2\*O .iE .oS Host 192.56.207.146, his time is 0 Vote: Last yes vote for 192.56.207.26 at -10 (sync site); Last vote started at -11 Local db version is 750478963.1 I am not sync site Lowest host 192.56.207.26 at -10 Sync host 192.56.207.26 at -10 Sync site's db version is 750478963.1 0 locked pages, 0 of them for write This server has never been sync site .oE .PP The following command displays information on a specified database server that is a synchronization site; the output also provides information on the other database servers in the RPC server group: .iS \*C$\*O \*Ludebug /.:/fs fs4\*O .iE .oS Host 192.56.207.26, his time is 0 Vote: Last yes vote for 192.56.207.26 at -9 (sync site); Last vote started at -9 Local db version is 750478963.1 I am sync site until 81 (4 servers) Recovery state 1f Sync site's db version is 750478963.1 0 locked pages, 0 of them for write This server last became sync site at -38195 .oE .oS Server 192.56.207.36: (db 750478963.1) last vote rcvd at -8, last beacon sent at -9, last vote was yes dbcurrent=1, up=1 beaconSince=1 .oE .oS Server 192.56.207.146: (db 750478963.1) last vote rcvd at -8, last beacon sent at -9, last vote was yes dbcurrent=1, up=1 beaconSince=1 .oE .oS Server 192.56.207.94: (db 750478963.1) last vote rcvd at -8, last beacon sent at -9, last vote was yes dbcurrent=1, up=1 beaconSince=1 .oE .SH "RELATED INFORMATION" .PP Commands: \*Lbakserver(1m)\*O, \*Lflserver(1m)\*O .iX "-]" "\*Ludebug\*O command" .iX "-]" "Ubik" "listing status" .zZ "defect,8393,R1.0.3,Document the udebug command" .\" $Header: udpublickey.1m,v 72.2 94/08/25 14:13:02 ssa Exp $ .TA u .TH udpublickey 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME udpublickey \- update the publickey database file and the NIS map .SH SYNOPSIS .C udpublickey .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .CR udpublickey is executed from the .IR updaters (1M) makefile when either .CR newkey or .C rpc.ypupdated updates the .C /etc/publickey database file. .PP .CR udpublickey receives the following information from .CR newkey or .C rpc.ypupdated: .RS .TP .C "Requestor's name (a string)" .TP .C "Type of update" .TP .C "Number of bytes in key" .TP .C "Key" .TP .C "Number of bytes in data" .TP .C "Data" .RE .PP After receiving this information, .CR udpublickey attempts to update the publickey database file, .CR /etc/publickey . .PP If the update is successful, .CR udpublickey makes the NIS map, .CR publickey.byname . .PP If the update is completely successful, .CR udpublickey exits with a zero (0) status; otherwise .CR udpublickey exits with a valid NIS error. .PP This command should not be run interactively. .PP .SH AUTHOR .CR udpublickey was developed by Sun Microsystems, Inc. .SH FILES .TP 25 .C /etc/publickey .SH SEE ALSO newkey(1M), rpc.ypupdated(1M), updaters(1M), publickey(4). .\" .\" index@\f4udpublickey\f1 \- updates the \f4publickey\f1 database file and NIS map@@@\f3udpublickey(1M)\f1 .\" index@\f1updates the \f4publickey\f1 database file and NIS map@@@\f3udpublickey(1M)\f1 .\" index@\f1\f4publickey\f1 database file, updates to@@@\f3udpublickey(1M)\f1 .\" index@\f1NIS map, updates to@@@\f3udpublickey(1M)\f1 .\" .\" toc@\f3udpublickey(1M)\f1:\0\0\f4udpublickey\f1@@@updates the \f4publickey\f1 database file and the NIS map .\" $Header: mount.1m,v 78.1 96/01/22 22:34:31 ssa Exp $ .TA m .TH mount 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mount (generic), umount (generic) \- mount and unmount file systems .SH SYNOPSIS .C /usr/sbin/mount .RC [ -l ] .RC [ -p \(or -v ] .PP .C /usr/sbin/mount .C -a .RC [ -F .IR FStype ] .RC [ -eQ ] .PP .C /usr/sbin/mount .RC [ -F .IR FStype ] .RC [ -eQrV ] .RC [ -o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .RI { special \(or directory } .PP .C /usr/sbin/mount .RC [ -F .IR FStype ] .RC [ -eQrV ] .RC [ -o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .I special .I directory .ift .sp .5v \" add extra space to separate the two command groups .PP .C /usr/sbin/umount .RC [ -v ] .RC [ -V ] .RI { special \(or directory } .PP .C /usr/sbin/umount .C -a .RC [ -F .IR FStype ] .RC [ -v ] .SH DESCRIPTION The .CR mount command mounts file systems. Only a superuser can mount file systems. Other users can use .CR mount to list mounted file systems. .PP The .CR mount command attaches .IR special , a removable file system, to .IR directory , a directory on the file tree. .IR directory , which must already exist, will become the name of the root of the newly mounted file system. .IR special and .IR directory must be given as absolute path names. If either .IR special or .IR directory is omitted, .CR mount attempts to determine the missing value from an entry in the .CR /etc/fstab file. .CR mount can be invoked on any removable file system, except .CR / . .PP If .CR mount is invoked without any arguments, it lists all of the mounted file systems from the file system mount table, .CR /etc/mnttab . .PP The .CR umount command unmounts mounted file systems. Only a superuser can unmount file systems. .SS Options (mount) The .CR mount command recognizes the following options: .RS .TP 15 .CR -a Attempt to mount all file systems described in .CR /etc/fstab . All optional fields in .CR /etc/fstab must be included and supported. If the .CR -F option is specified, all file systems in .CR /etc/fstab with that .I FStype are mounted. File systems are not necessarily mounted in the order listed in .CR /etc/fstab . .TP .CR -e Verbose mode. Write a message to the standard output indicating which file system is being mounted. .TP .CI -F \0FStype Specify .IR FStype , the file system type on which to operate. See .IR fstyp (1M). If this option is not included on the command line, then it is determined from either .CR /etc/fstab , by matching .I special with an entry in that file, or from file system statistics of .IR special , obtained by .CR statfsdev() (see .IR statfsdev (3C)). .TP .CR -l Limit actions to local file systems only. .TP .CI -o \0specific_options Specify options specific to each file system type. .I specific_options is a list of comma separated suboptions and/or keyword/attribute pairs intended for a .IR FStype -specific version of the command. See the .IR FStype -specific manual entries for a description of the .I specific_options supported, if any. .TP .CR -p Report the list of mounted file systems in the .CR /etc/fstab format. .TP .CR -Q Prevent the display of error messages that result from an attempt to mount already mounted file systems. .TP .CR -r Mount the specified file system as read-only. Physically write-protected file systems must be mounted in this way or errors occur when access times are updated, whether or not any explicit write is attempted. .TP .CR -v Report the regular output with file system type and flags; however, the .IR directory and .IR special fields are reversed. .TP .CR -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .SS Options (umount) The .CR umount command recognizes the following options: .RS .TP 15 .CR -a Attempt to unmount all file systems described in .CR /etc/mnttab . All optional fields in .CR /etc/mnttab must be included and supported. If .I FStype is specified, all file systems in .CR /etc/mnttab with that .I FStype are unmounted. File systems are not necessarily unmounted in the order listed in .CR /etc/mnttab . .TP .CI -F \0FStype Specify .IR FStype , the file system type on which to operate. If this option is not included on the command line, then it is determined from .CR /etc/mnttab by matching .I special with an entry in that file. If no match is found, the command fails. .TP .CR -v Verbose mode. Write a message to standard output indicating which file system is being unmounted. .TP .CR -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR "/etc/fstab" . This option allows the user to verify the command line. .RE .SH EXAMPLES List the file systems currently mounted: .IP .CR mount .PP Mount the HFS file system .CR /dev/dsk/c1d2s0 at directory .CR /home : .IP .C "mount -F hfs /dev/dsk/c1d2s0 /home" .PP Unmount the same file system: .IP .C "umount /dev/dsk/c1d2s0" .SH AUTHOR .CR mount was developed by HP, AT&T, the University of California, Berkeley, and Sun Microsystems. .SH FILES .TP 25 .PD 0 .CR /etc/fstab Static information about the systems .TP .CR /etc/mnttab Mounted file system table .PD .SH SEE ALSO .RI mount_ FStype (1M), mount(2), fstab(4), mnttab(4), fs_wrapper(5), quota(5). .SH STANDARDS COMPLIANCE .CR mount ": SVID3" .PP .CR umount ": SVID3" .\" .\" index@\f4mount\f1 \- mount a file system (generic)@@@\f3mount(1M)\f1 .\" index@\f4umount\f1 \- unmount a file system (generic)@@@\f3mount(1M)\f1 .\" index@\f1unmount a file system (generic)@@@\f3mount(1M)\f1 .\" index@\f1dismount (unmount) a file system (generic)@@@\f3mount(1M)\f1 .\" index@\f1file system, mount or unmount (generic)@@@\f3mount(1M)\f1 .\" index@\f1generic file system, mount or unmount@@@\f3mount(1M)\f1 .\" .\" index@\f4default_disk_ir\f1 tunable parameter@@@\f3mount(1M)\f1 .\" index@\f1tunable parameter, \f4default_disk_ir\f1@@@\f3mount(1M)\f1 .\" .\" toc@\f3mount(1M)\f1:\0\0\f4mount\f1, \f4umount\f1@@@mount and unmount a file system (generic)\f1 .\" toc@\f4umount\f1:\0\0unmount a file system (generic)@@@\f1see \f3mount(1M)\f1 .\" .\" links@mount.1m umount.1m .\" $Header: mount_cdfs.1m,v 78.2 96/01/22 22:37:04 ssa Exp $ .TA m .TH mount_cdfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mount(cdfs), umount(cdfs) \- mount and unmount an CDFS file systems .SH SYNOPSIS .CR /usr/sbin/mount .RC [ \-l ] .RC [ \-p | \-v ] .PP .CR /usr/sbin/mount .CR \-a .RC [ \-F .CR cdfs ] .RC [ \-eQ ] .PP .CR /usr/sbin/mount .RC [ \-F .CR cdfs ] .RC [ \-eQrV ] .RC [ \-o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .RI { special \(or directory } .PP .CR /usr/sbin/mount .RC [ \-F .CR cdfs ] .RC [ \-eQrV ] .RC [ \-o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .I special .I directory .sp .PP .CR /usr/sbin/umount .CR \-a .RC [ \-F .CR cdfs ] .RC [ \-v ] .PP .CR /usr/sbin/umount .RC [ \-v ] .RC [ \-V ] .RI { special \(or directory } .SH DESCRIPTION The .CR mount command mounts file systems. Only a superuser can mount file systems. Other users can use .CR mount to list mounted file systems. .PP The .CR mount command attaches .IR special , a removable file system, to .IR directory , a directory on the file tree. .IR directory , which must already exist, will become the name of the root of the newly mounted file system. .IR special and .IR directory must be given as absolute path names. If either .IR special or .IR directory is omitted, .CR mount attempts to determine the missing value from an entry in the .CR /etc/fstab file. .CR mount can be invoked on any removable file system, except .CR / . .PP If .CR mount is invoked without any arguments, it lists all of the mounted file systems from the file system mount table, .CR /etc/mnttab . .PP The .CR umount command unmounts mounted file systems. Only a superuser can unmount file systems. .SS Options (mount) .CR mount recognizes the following options: .RS .TP 15 .CR \-a Attempt to mount all file systems described in .CR /etc/fstab . All optional fields in .CR /etc/fstab must be included and supported. If .CR \-F .CR cdfs is specified, all CDFS file systems in .CR /etc/fstab are mounted. File systems are not necessarily mounted in the order listed in .CR /etc/fstab . .TP .CR \-e Verbose mode. Write a message to standard output indicating which file system is being mounted. .TP .CR \-F\0cdfs Specify the CDFS file system type (see .IR fstyp (1m)). .TP .CR \-l Limit actions to local file systems only. .\" AAA .TP .CI \-o \0specific_options Specify options specific to the CDFS file system type. .I specific_options is a list of comma separated suboptions and/or keyword/attribute pairs intended for the CDFS specific module of the command. .IP The following .IR specific_options are valid on CDFS file systems. .RS .RS .TP 15 .CR cdcase Suppress the display of version numbers. Show and match file names as lower case. .TP .CR defaults Use all default options. When given, this must be the only option specified. .TP .CR ro Mount read-only (default). .TP .CR suid Allow set-user-ID execution (default). .TP .CR nosuid Do not allow set-user-ID execution. .RE .RE .TP .CR \-p Report the list of mounted file systems in the .CR /etc/fstab format. .TP .CR \-Q Prevent the display of error messages resulting from an attempt to mount already mounted file systems. .TP .CR \-r Mount the specified file system as read-only. This option is equivalent to the .CR "\-o\ ro" .IR specific_option . For CDFS file systems this is a default option. .TP .CR \-v Report the regular output with file system type and flags; however, .IR directory and .IR special fields are reversed. .TP .CR \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SS Options (umount) .CR umount recognizes the following options: .RS .TP 15 .CR \-a Attempt to unmount all file systems described in .CR /etc/mnttab . All optional fields in .CR /etc/mnttab must be included and supported. If .CR \-F .CR cdfs is specified, all CDFS file systems in .CR /etc/mnttab are unmounted. File systems are not necessarily unmounted in the order listed in .CR /etc/mnttab . .TP .CR \-F\0cdfs Specify the CDFS file system type (see .IR fstyp (1m)). .TP .CR \-v Verbose mode. Write a message to standard output indicating which file system is being unmounted. .TP .CR \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SH DIAGNOSTICS .PP .CR umount complains if the special file is not mounted or if it is busy. The file system is busy if it contains an open file or some logged-in user's working directory. .SH EXAMPLES Mount a local CDFS disk: .IP .C "mount -F cdfs /dev/dsk/c0d0s4 /cdrom" .PP Unmount a local CDFS disk: .IP .C "umount /dev/dsk/c0d0s4" .SH WARNINGS .PP Some degree of validation is done on the file system, however, it is generally unwise to mount file systems that are defective, corrupt, or of unknown origin. .SH AUTHOR .CR mount was developed by HP, AT&T, the University of California, Berkeley, and Sun Microsystems. .SH FILES .TP 20 .PD 0 .CR /etc/fstab Static information about the file systems .TP .CR /etc/mnttab Mounted file system table .PD .SH SEE ALSO fsclean(1M), mount(1M), quotaon(1M), mount(2), fstab(4), mnttab(4), fs_wrapper(5), quota(5). .SH STANDARDS COMPLIANCE .CR mount ": SVID3" .br .CR umount ": SVID3" .\" .\" index@\f4mount\f1 \- mount CDFS file systems@@@\f3mount_cdfs(1M)\f1 .\" index@\f4umount\f1 \- unmount CDFS file systems@@@\f3mount_cdfs(1M)\f1 .\" index@\f1unmount CDFS file systems@@@\f3mount_cdfs(1M)\f1 .\" index@\f1CDFS file systems, mount and unmount@@@\f3mount_cdfs(1M)\f1 .\" index@\f1dismount (unmount) CDFS file systems@@@\f3mount_cdfs(1M)\f1 .\" index@\f1file systems, mount and unmount CDFS@@@\f3mount_cdfs(1M)\f1 .\" .\" toc@\f3mount_cdfs(1M)\f1:\0\0\f4mount\f1, \f4umount\f1@@@mount and unmount CDFS file systems .\" toc@\f4umount\f1:\0\0mount and unmount CDFS file systems@@@see \f3mount_cdfs(1M)\f1 .\" .\" links@mount_cdfs.1m umount_cdfs.1m .\" $Header: mount_hfs.1m,v 78.1 96/01/22 22:40:15 ssa Exp $ .TA m .TH mount_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mount(hfs), umount(hfs) \- mount and unmount an HFS file systems .SH SYNOPSIS .CR /usr/sbin/mount .RC [ \-l ] .RC [ \-p | \-v ] .PP .CR /usr/sbin/mount .CR \-a .RC [ \-F .CR hfs ] .RC [ \-eQ ] .RC [ \-f ] .PP .CR /usr/sbin/mount .RC [ \-F .CR hfs ] .RC [ \-eQrV ] .RC [ \-f ] .RC [ \-o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .RI { special \(or directory } .PP .CR /usr/sbin/mount .RC [ \-F .CR hfs ] .RC [ \-eQrV ] .RC [ \-f ] .RC [ \-o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .I special .I directory .sp .PP .CR /usr/sbin/umount .CR \-a .RC [ \-F .CR hfs ] .RC [ \-v ] .PP .CR /usr/sbin/umount .RC [ \-v ] .RC [ \-V ] .RI { special \(or directory } .SH DESCRIPTION The .CR mount command mounts file systems. Only a superuser can mount file systems. Other users can use .CR mount to list mounted file systems. .PP The .CR mount command attaches .IR special , a removable file system, to .IR directory , a directory on the file tree. .IR directory , which must already exist, will become the name of the root of the newly mounted file system. .IR special and .IR directory must be given as absolute path names. If either .IR special or .IR directory is omitted, .CR mount attempts to determine the missing value from an entry in the .CR /etc/fstab file. .CR mount can be invoked on any removable file system, except .CR / . .PP If .CR mount is invoked without any arguments, it lists all of the mounted file systems from the file system mount table, .CR /etc/mnttab . .PP The .CR umount command unmounts mounted file systems. Only a superuser can unmount file systems. .SS Options (mount) .CR mount recognizes the following options: .RS .TP 15 .CR \-a Attempt to mount all file systems described in .CR /etc/fstab . All optional fields in .CR /etc/fstab must be included and supported. If .CR \-F .CR hfs is specified, all HFS file systems in .CR /etc/fstab are mounted. File systems are not necessarily mounted in the order listed in .CR /etc/fstab . .TP .CR \-e Verbose mode. Write a message to standard output indicating which file system is being mounted. .TP .CR \-f Force the file system to be mounted, even if the file system clean flag indicates that the file system should have .CR fsck run on it before mounting (see .IR fsck (1M)). This option is valid only on HFS file systems. .TP .CR \-F\0hfs Specify the HFS file system type (see .IR fstyp (1M)). .TP .CR \-l Limit actions to local file systems only. .\" AAA .TP .CI \-o \0specific_options Specify options specific to the HFS file system type. .I specific_options is a list of comma separated suboptions and/or keyword/attribute pairs intended for the HFS specific module of the command. .IP The following .IR specific_options are valid on HFS file systems. .RS .RS .TP 15 .CR defaults Use all default options. When given, this must be the only option specified. .TP .CR rw Mount read-write (default). .TP .CR ro Mount read-only. .TP .CR suid Allow set-user-ID execution (default). .TP .CR nosuid Do not allow set-user-ID execution. .RE .RE .RS .RS .TP 15 .CR behind Enable, where possible, asynchronous writes to disk. This is the default on 700 systems. .TP 15 .CR delayed Enable delayed or buffered writes to disk. This is the default on 800 systems. .TP 15 .CR fs_async Enable relaxed posting of file system metadata. .TP 15 .CR no_fs_async Enable rigorous posting of file system metadata. This is the default. .TP 15 .CR largefiles Attempt to enable the creation of files greater than 2 gigabytes in size. File systems have to be created or configured to enable large files (see .IR mkfs_hfs(1M) and .IR fsadm_hfs(1M)). .TP 15 .CR nolargefiles Attempt to disable the creation of files greater than 2 gigabytes in size. File systems have to be created or configured to disable large files. (see .IR mkfs_hfs(1M) and .IR fsadm_hfs(1M)). .TP 15 .CR quota Enable disk quotas (valid only for .CR rw file systems). .TP .CR noquota Disable disk quotas (default). .PP Mounting with the .CR quota option also enables quotas for the file system, unlike some other systems, which require the additional invocation of the .CR quotaon command after the file system has been mounted (see .IR quotaon (1M)). Running .CR quotaon does no harm, but it is not necessary. .RE .RE .TP .CR \-p Report the list of mounted file systems in the .CR /etc/fstab format. .TP .CR \-Q Prevent the display of error messages resulting from an attempt to mount already mounted file systems. .TP .CR \-r Mount the specified file system as read-only. This option is equivalent to the .CR "\-o\ ro" .IR specific_option . Physically write-protected file systems must be mounted in this way or errors occur when access times are updated, whether or not any explicit write is attempted. .TP .CR \-v Report the regular output with file system type and flags; however, .IR directory and .IR special fields are reversed. .TP .CR \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SS Options (umount) .CR umount recognizes the following options: .RS .TP 15 .CR \-a Attempt to unmount all file systems described in .CR /etc/mnttab . All optional fields in .CR /etc/mnttab must be included and supported. If .CR \-F .CR hfs is specified, all HFS file systems in .CR /etc/mnttab are unmounted. File systems are not necessarily unmounted in the order listed in .CR /etc/mnttab . .TP .CR \-F\0hfs Specify the HFS file system type (see .IR fstyp (1M)). .TP .CR \-v Verbose mode. Write a message to standard output indicating which file system is being unmounted. .TP .CR \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SH DIAGNOSTICS .PP .CR umount complains if the special file is not mounted or if it is busy. The file system is busy if it contains an open file or some logged-in user's working directory. .SH EXAMPLES Mount a local HFS disk: .IP .C "mount -F hfs /dev/dsk/c0d0s4 /usr" .PP Unmount a local HFS disk: .IP .C "umount /dev/dsk/c0d0s4" .SH WARNINGS .PP Some degree of validation is done on the file system, however, it is generally unwise to mount file systems that are defective, corrupt, or of unknown origin. .SH AUTHOR .CR mount was developed by HP, AT&T, the University of California, Berkeley, and Sun Microsystems. .SH FILES .TP 20 .PD 0 .CR /etc/fstab Static information about the file systems .TP .CR /etc/mnttab Mounted file system table .PD .SH SEE ALSO fsclean(1M), mount(1M), mkfs_hfs(1M), fsadm_hfs(1M), quotaon(1M), mount(2), fstab(4), mnttab(4), fs_wrapper(5), quota(5). .SH STANDARDS COMPLIANCE .CR mount ": SVID3" .br .CR umount ": SVID3" .\" .\" index@\f4mount\f1 \- mount HFS file systems@@@\f3mount_hfs(1M)\f1 .\" index@\f4umount\f1 \- unmount HFS file systems@@@\f3mount_hfs(1M)\f1 .\" index@\f1unmount HFS file systems@@@\f3mount_hfs(1M)\f1 .\" index@\f1HFS file systems, mount and unmount@@@\f3mount_hfs(1M)\f1 .\" index@\f1dismount (unmount) HFS file systems@@@\f3mount_hfs(1M)\f1 .\" index@\f1file systems, mount and unmount HFS@@@\f3mount_hfs(1M)\f1 .\" .\" toc@\f3mount_hfs(1M)\f1:\0\0\f4mount\f1, \f4umount\f1@@@mount and unmount HFS file systems .\" toc@\f4umount\f1:\0\0mount and unmount HFS file systems@@@see \f3mount_hfs(1M)\f1 .\" .\" links@mount_hfs.1m umount_hfs.1m .\" $Header: mount_lofs.1m,v 78.1 96/01/22 22:41:08 ssa Exp $ .TA m .TH mount_lofs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mount(lofs), umount(lofs) \- mount and unmount an LOFS file system .SH SYNOPSIS .CR /usr/sbin/mount .RC [ -p | -v ] .PP .CR /usr/sbin/mount .CR -a .RC [ -F .CR lofs ] .RC [ -eQ ] .PP .CR /usr/sbin/mount .RC [ -F .CR lofs ] .RC [ -eQrV ] .RC [ -o .IR specific_options ] .br \0\0\0\0 .RI { special_directory \(or directory } .PP .CR /usr/sbin/mount .RC [ -F .CR lofs ] .RC [ -eQrV ] .RC [ -o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .I special_directory .I directory .sp .PP .C /usr/sbin/umount .RC [ -v ] .RC [ -V ] .RI { special_directory \(or directory } .PP .C /usr/sbin/umount .C -a .RC [ -F .CR lofs ] .RC [ -v ] .SH DESCRIPTION The .CR mount command mounts LOFS file systems. Only superuser can mount LOFS file systems. Other users can use .CR mount to list mounted file systems. .PP .CR mount , attaches .IR special_directory , a directory from one of the mounted file systems, to .IR directory , an another directory in one of the mounted file systems. This enables new file systems to be created, which provide access to existing directories or file systems using alternate path names. Both .IR special_directory and .IR directory should already exist. .I directory will become the root of the newly mounted LOFS file system, containing the file system hierarchy under .IR special_directory . .IR special_directory and .IR directory must be specified as absolute path names. If either .IR special_directory or .IR directory is omitted, .CR mount attempts to determine the missing value from an entry in the .CR /etc/fstab file. .CR mount can be invoked on any removable file system, except .CR / . .PP If .CR mount is invoked without any arguments, it lists all the mounted file systems from the file system mount table, .CR /etc/mnttab . .PP The .CR umount command unmounts mounted file systems. Only a superuser can unmount file systems. .SS Options (mount) .CR mount recognizes the following options: .RS .TP 15 .CR -a Attempt to mount all file systems described in .CR /etc/fstab . All optional fields in .CR /etc/fstab must be included and supported. If .CR "-F lofs" is specified, all LOFS file systems in .CR /etc/fstab are mounted. File systems are not necessarily mounted in the order listed in .CR /etc/fstab . .TP .CR -e Verbose mode. Write a message to standard output indicating which file system is being mounted. .TP .CR -F\0lofs Specify the LOFS file system type (see .IR fstyp (1M)). .TP .CR -l Limit actions to local file systems only. LOFS is a local file system. .TP .CI \-o \0specific_options Specify options specific to the LOFS file system type. .I specific_options is a list of comma separated suboptions and/or keyword/attribute pairs intended for the LOFS specific module of the command. .IP The following .I specific_options are valid on an LOFS file system: .RS .RS .TP 15 .CR defaults Use all default options. When used, this must be the only option specified. .TP .CR ro Read-only. .RE .RE .TP .CR -p Report the list of mounted file systems in the .CR /etc/fstab format. .TP .CR -Q Prevent display of error messages resulting from an attempt to mount already mounted file systems. .TP .CR -r Mount the specified file system as read-only. .TP .CR -v Report the output in a new style. The new style has the file system type and flags displayed in addition to the old output. The .IR directory and .IR special_directory fields are reversed. .TP .CR -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .SS Options (umount) The .CR umount command recognizes the following options: .RS .TP 15 .CR -a Attempt to unmount all file systems described in .CR /etc/mnttab . All optional fields in .CR /etc/mnttab must be included and supported. If .CR "-F lofs" file system type is specified, all the LOFS file systems in .CR /etc/mnttab are unmounted. File systems are not necessarily unmounted in the order listed in .CR /etc/mnttab . .TP .CR -F\0lofs Specify the LOFS file system type (see .IR fstyp (1M)). .TP .CR -v Verbose mode. Write a message to standard output indicating which file system is being unmounted. .TP .CR -V Echo the completed command line, but perform no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR "/etc/fstab" . This option allows the user to verify the command line. .SH EXAMPLES Mount an LOFS file system: .IP .C "mount /usr /tmp/usr" .PP Mount another LOFS file system: .IP .C "mount -F lofs /usr/sbin /tmp/sbin" .SH WARNINGS LOFS file systems provide the user with numerous applications; however, they may be potentially confusing. LOFS file systems should generally be created by an experienced user. .SH AUTHOR .CR mount was developed by HP, AT&T, the University of California, Berkeley, and Sun Microsystems. .SH FILES .TP 25 .CR /etc/fstab Static information about the file systems .PD 0 .TP .CR /etc/mnttab Mounted file system table .PD .SH SEE ALSO mount(1M), mount(2), fstab(4), mnttab(4). .SH STANDARDS CONFORMANCE .PP .CR mount ": SVID3" .\" .\" index@\f4mount\f1 \- mount an LOFS file system@@@\f3mount_lofs(1M)\f1 .\" index@file system, mount an LOFS@@@\f3mount_lofs(1M)\f1 .\" index@LOFS file system, mount@@@\f3mount_lofs(1M)\f1 .\" .\" toc@\f3mount_lofs(1M)\f1:\0\0\f4mount\f1@@@mount an LOFS file system .\" .\" links@mount_lofs.1m umount_lofs.1m .\" $Header: mount_nfs.1m,v 78.2 96/01/22 22:42:46 ssa Exp $ .TA m .TH mount_nfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mount(nfs), umount(nfs) \- mount and unmount an NFS file systems .SH SYNOPSIS .CR /usr/sbin/mount .RC [ \-l ] .RC [ \-p | \-v ] .PP .CR /usr/sbin/mount .CR \-a .RC [ \-F .CR nfs ] .RC [ \-eQ ] .PP .CR /usr/sbin/mount .RC [ \-F .CR nfs ] .RC [ \-eQrV ] .RC [ \-o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .RI { host:path \(or directory } .PP .CR /usr/sbin/mount .RC [ \-F .CR nfs ] .RC [ \-eQrV ] .RC [ \-o .IR specific_options ] .ifn .br .ifn \0\0\0\0 .I host:path .I directory .sp .PP .CR /usr/sbin/umount .CR \-a .RC [ \-F .CR nfs ] .RC [ \-h .IR host ] .RC [ \-v ] .PP .CR /usr/sbin/umount .RC [ \-v ] .RC [ \-V ] .RI { host:path \(or directory } .SH DESCRIPTION The .CR mount command mounts file systems. Only a superuser can mount file systems. Other users can use .CR mount to list mounted file systems. .PP The .CR mount command attaches .IR host:path to .IR directory. .IR host is a remote system, .IR path is a directory on this remote system and .IR directory is a directory on the local file tree. .IR directory must already exist, be given as an absolute path name and will become the name of the root of the newly mounted file system. If either .IR host:path or .IR directory is omitted, .CR mount attempts to determine the missing value from an entry in the .CR /etc/fstab file. .CR mount can be invoked on any removable file system, except .CR / . .PP If .CR mount is invoked without any arguments, it lists all of the mounted file systems from the file system mount table, .CR /etc/mnttab . .PP The .CR umount command unmounts mounted file systems. Only a superuser can unmount file systems. .SS Options (mount) .CR mount recognizes the following options: .RS .TP 15 .CR \-a Attempt to mount all file systems described in .CR /etc/fstab . All optional fields in .CR /etc/fstab must be included and supported. If .CR \-F .CR nfs is specified, all NFS file systems in .CR /etc/fstab are mounted. File systems are not necessarily mounted in the order listed in .CR /etc/fstab . .TP .CR \-e Verbose mode. Write a message to standard output indicating which file system is being mounted. .TP .CR \-F\0nfs Specify the NFS file system type (see .IR fstyp (1M)). .TP .CR \-l Limit actions to local file systems only. .\" AAA .TP .CI \-o \0specific_options Specify options specific to the NFS file system type. .I specific_options is a list of comma separated suboptions and/or keyword/attribute pairs intended for the NFS specific module of the command. .IP The following .IR specific_options are valid on NFS file systems. .RS .RS .TP 15 .CR defaults Use all default options. When given, this must be the only option specified. .TP .CR rw Mount read-write (default). .TP .CR ro Mount read-only. .TP .CR suid Allow set-user-ID execution (default). .TP .CR nosuid Do not allow set-user-ID execution. .PP Additional .IR specific_options for the NFS file systems are listed under NETWORKING FEATURES below. .RE .RE .TP .CR \-p Report the list of mounted file systems in the .CR /etc/fstab format. .TP .CR \-Q Prevent the display of error messages resulting from an attempt to mount already mounted file systems. .TP .CR \-r Mount the specified file system as read-only. This option is equivalent to the .CR "\-o\ ro" .IR specific_option . Physically write-protected file systems must be mounted in this way or errors occur when access times are updated, whether or not any explicit write is attempted. .SS Options (umount) .CR umount recognizes the following options: .RS .TP 15 .CR \-a Attempt to unmount all file systems described in .CR /etc/mnttab . All optional fields in .CR /etc/mnttab must be included and supported. If .CR \-F .CR nfs option is specified, all NFS file systems in .CR /etc/mnttab are unmounted. File systems are not necessarily unmounted in the order listed in .CR /etc/mnttab . .TP .CR \-F\0nfs Specify the NFS file system type (see .IR fstyp (1M)). .TP .CI \-h \0host Unmount only those file systems listed in .CR /etc/mnttab that are remote-mounted from .IR host . .TP .CR \-v Verbose mode. Write a message to standard output indicating which file system is being unmounted. .TP .CR \-V Echo the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .SH NETWORKING FEATURES .SS NFS The following .I specific_options are applicable to NFS file systems: .RS .TP 15 .CI acdirmax= n Hold cached attributes for no more than .IR n seconds after directory update. .TP .CI acdirmin= n Hold cached attributes for at least .IR n seconds after directory update. .TP .CI acregmax= n Hold cached attributes for no more than .IR n seconds after file modification. .TP .CI acregmin= n Hold cached attributes for at least .IR n seconds after file modification. .TP .CI actimeo= n Set minimum and maximum times for regular files and directories to .IR n seconds. .TP .CR bg If the first .CR mount attempt fails, retry in the background. .\" not supported in B1-NFS; will be supported in 10.0x .TP .CR devs Allow access to local devices (default). .TP .CR fg Retry in foreground (default). .TP .CR hard Once the file system is mounted, retry subsequent NFS requests until server responds (default). .TP .CR intr Permit interrupts for hard mounts (default). .TP .CR noac Suppress attribute and name (lookup) caching. .TP .CR nocto Suppress fresh attributes when opening a file. .\" not supported in B1-NFS; will be supported in 10.0x .TP .CR nodevs Deny access to local devices. .TP .CR nointr Ignore interrupts for hard mounts. .TP .CI port= n Set server UDP port number to .IR n (the default is the port customarily used for NFS servers). .TP .CI retrans= n Set number of NFS retransmissions to .IR n (the default = 4). .TP .CI retry= n Set number of .CR mount failure retries to .IR n (the default = 1). .TP .CI rsize= n Set read buffer size to .IR n bytes (the default is set by kernel). .TP .CR soft Once the file system is mounted, return error if server does not respond. .TP .CI timeo= n Set NFS timeout to .IR n tenths of a second (the default = 7). .TP .CI wsize= n Set write buffer size to .IR n bytes (the default is set by kernel). .RE .PP The regular defaults are: .IP .CR acregmin=3\0\0acregmax=60\0\0acdirmin=30\0\0acdirmax=60 .PP .CR actimeo has no default; it sets .CR acregmin , .CR acregmax , .CR acdirmin , and .CR acdirmax to the value specified. .PP .CR bg causes .CR mount to run in the background if the server's mount daemon does not respond. .PP .CR mount attempts each request .CI retry= n times before giving up. .PP Once the file system is mounted, each NFS request made in the kernel waits .CI timeo= n tenths of a second for a response. If no response arrives, the timeout is multiplied by 2 and the request is retransmitted. When .CI retrans= n retransmissions have been sent with no reply, a .CR soft mounted file system returns an error on the request and a .CR hard mounted file system retries the request. .PP By default, the .CR retry requests for a .CR hard mounted file system can be interrupted. If the .CR nointr option is specified, .CR retry requests for a .CR hard mounted file system are not interruptable which means that .CR retry requests continue until successful. File systems that are mounted .CR rw (read-write) should use the .CR hard option. .PP The number of bytes in a read or write request can be set with the .CR rsize and .CR wsize options. .PP The .CR devs option allows access to devices attached to the NFS client via device files located on the mounted NFS file system. The .CR nodevs option denies access to devices attached to the NFS client by causing attempts to read or write to NFS device files to return an error. .SS File Attributes The attribute cache retains file attributes for the client. Attributes for a file are assigned a time to be flushed. If the file is modified before the flush time, the flush time is extended by the time since the last modification (under the assumption that files that have changed recently are likely to change again soon). There is a minimum and maximum flush time extension for regular files and for directories. Setting .CI actimeo= n extends flush time by .IR n seconds for both regular files and directories. .SH DIAGNOSTICS .CR umount complains if the host:path is not mounted or if it is busy. The file system is busy if it contains an open file or some logged-in user's working directory. .PP Cascaded distributed mounts (mounts whose mount point resides on another client node's locally mounted disk) are not supported. .SH EXAMPLES Mount a remote file system: .IP .C "mount \-F nfs serv:/usr/src /usr/src" .PP Same as above: .IP .C "mount serv:/usr/src /usr/src" .PP Same as above but with a soft mount; the file system is mounted read-only: .IP .C "mount \-o soft,ro serv:/usr/src /usr/src" .SH WARNINGS A directory or file must be exported by the .CR exportfs command before it is NFS-mounted (see .IR exportfs (1M)). .PP Some degree of validation is done on the file system. However, it is generally unwise to mount file systems that are defective, corrupt, or of unknown origin. .SH AUTHOR .CR mount was developed by HP, AT&T, the University of California, Berkeley, and Sun Microsystems. .SH FILES .TP 20 .PD 0 .CR /etc/fstab Static information about the file systems .TP .CR /etc/mnttab Mounted file system table .PD .SH SEE ALSO fsclean(1M), mount(1M), quotaon(1M), mount(2), fstab(4), mnttab(4), fs_wrapper(5), quota(5). .SH STANDARDS COMPLIANCE .CR mount ": SVID3" .br .CR umount ": SVID3" .\" .\" index@\f4mount\f1 \- mount NFS file systems@@@\f3mount_nfs(1M)\f1 .\" index@\f4umount\f1 \- unmount NFS file systems@@@\f3mount_nfs(1M)\f1 .\" index@\f1unmount NFS CDFS file systems@@@\f3mount_nfs(1M)\f1 .\" index@\f1NFS file systems, mount and unmount@@@\f3mount_nfs(1M)\f1 .\" index@\f1dismount (unmount) NFS file systems@@@\f3mount_nfs(1M)\f1 .\" index@\f1file systems, mount and unmount NFS@@@\f3mount_nfs(1M)\f1 .\" .\" toc@\f3mount_nfs(1M)\f1:\0\0\f4mount\f1, \f4umount\f1@@@mount and unmount NFS file systems .\" toc@\f4umount\f1:\0\0mount and unmount NFS file systems@@@see \f3mount_nfs(1M)\f1 .\" .\" links@mount_nfs.1m umount_nfs.1m .\" $Header: mount_vxfs.1m,v 78.2 96/02/13 13:23:44 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA m .TH mount_vxfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mount, umount (vxfs) \- mount and unmount a VxFS file system .SH SYNOPSIS .C /usr/sbin/mount .RC [ \-l ] .RC [ \-v | \-p ] .br .C /usr/sbin/mount .RC [ \-F .CR vxfs\| ] .RC [ \-eQ ] .C \-a .br .\" Use .na and .nh to turn off line adjustment and hyphenation, so .\" that troff/nroff can determine the best way to print the options. .na .nh .C /usr/sbin/mount .RC [ \-F .CR vxfs\| ] .RC [ \-eQrV ] .RS .RC [ \-o .IR specific_options ] .RI { special | mount_point } .RE .br .\" Use .na and .nh to turn off line adjustment and hyphenation, so .\" that troff/nroff can determine the best way to print the options. .na .nh .C /usr/sbin/mount .RC [ \-F .CR vxfs\| ] .RC [ \-eQrV ] .RS .RC [ \-o .IR specific_options ] .I special mount_point .RE .br .\" Use .na and .nh to turn off line adjustment and hyphenation, so .\" that troff/nroff can determine the best way to print the options. .na .nh .C /usr/sbin/umount .RC [ \-V ] .RC [ \-v ] .RI { \|special " |" " directory\|" } .br .C /usr/sbin/umount .RC [ \-F .CR vxfs\| ] .RC [ \-v ] .C \-a .\" Turn adjustment and hyphenation back on. .ad .hy .SH DESCRIPTION The .C mount command attaches .IR special , a removable file system, to .IR directory , a directory on the file tree. .IR directory , which must already exist, will become the name of the root of the newly mounted file system. .C mount can be invoked on any removable file system, except .IR / . If .C mount is invoked with no arguments it lists all the mounted file systems from the mounted file system table, .CR /etc/mnttab . .IR special \0and \0directory must be given as absolute path names. .PP The .C umount command unmounts mounted file systems. .PP Only the superuser can .CR mount " and" " umount" file systems. Other users can use .CR mount to list mounted file systems. .SS Options .CR mount recognizes the following options: .RS .TP 15 .C \-a Attempt to mount all file systems described in .C /etc/fstab. All optional fields in .C /etc/fstab must be included and supported. If .C "\-F vxfs " is specified, all VxFS file systems in .C /etc/fstab are mounted. File systems are not necessarily mounted in the order listed in .CR /etc/fstab . .TP 15 .C \-e Verbose mode. Write a message to the standard output indicating which file system is being mounted. .TP 15 .C "\-F vxfs" Specifies the file system type .RC ( vxfs ). .TP .C \-l Limit actions to local file systems only. .TP .CI \-o " specific_options" Specifies options specific to the VxFS file system type. .I specific_options is a list of comma separated suboptions and/or keyword/attribute pairs intended for the VxFS-specific module of the command. .IP The following .I specific_options are valid on a VxFS file system: .RS .TP 15 .C rw Read-write (default). .TP .C ro Read-only. .TP .C suid Set-user-\c .SM ID execution allowed (default). .TP .C nosuid Set-user-\c .SM ID execution not allowed. .TP 15 .C quota Disk quotas enabled (valid only for .C rw type file systems). VxFS maintains quota information in a private area of the file system. If the file system is mounted with quotas enabled, and the file system was previously mounted with quotas disabled and was modified, then the quota information is rebuilt. This may take awhile. .TP .C remount Changes the mount options for a mounted file system, such as logging and caching policies or whether the file system can be written to. .TP .C log|delaylog|tmplog|nolog Controls intent logging. File system integrity across system failure requires that logging be enabled. The default is .CR log . In .C log mode, file system structural changes are logged to disk before the system call returns to the application. If the system crashes, .IR fsck_vxfs (1M) will complete logged operations that have not completed. .IP In .C delaylog mode, some system calls return before the intent log is written. This improves the performance of the system, but some changes are not guaranteed until a short time later when the intent log is written. This mode approximates traditional UNIX system guarantees for correctness in case of system failures. .IP In .C tmplog mode, the intent log is almost always delayed. This improves performance, but recent changes may disappear if the system crashes. This mode is only recommended for temporary file systems. .IP In .C nolog mode, the intent log is disabled. The other three logging modes provide fast file system recovery; .C nolog does not provide fast file system recovery. With .C nolog mode, a full structural check must be performed after a crash; this may result in loss of substantial portions of the file system, depending upon activity at the time of the crash. Usually, a .C nolog file system should be rebuilt with .IR mkfs_vxfs (1m) after a crash. The .C nolog mode should only be used for memory resident or very temporary file systems. .TP .C blkclear Ensure that all data extents are cleared before being allocated to a file (requires synchronous zeroing, on disk, of certain newly allocated extents). This prevents uninitialized data from appearing in a file being written at the time of a system crash. .TP .CI snapof= filesystem Mount the file system as a snapshot of .IR filesystem , where .I filesystem is either the directory on which a VxFS file system is mounted, or is the block special file containing a mounted VxFS file system. An explicit .CI "\-F vxfs" option is required to mount a snapshot file system. .TP .CI snapsize= blocks Used in conjunction with .CR snapof . .I blocks is the size in sectors of the snapshot file system being mounted. This option is required only when the device driver is incapable of determining the size of .IR special , and will default to the entire device if not specified. .TP .C mincache=direct|dsync|closesync|tmpcache This option is used to alter the caching behavior of the file system. .IP The .C direct value causes any writes without the O_SYNC flag and all reads to be handled as if the VX_DIRECT caching advisory was set instead. .IP The .C dsync value causes any writes without either the O_SYNC flag or the VX_DIRECT caching advisory to be handled as if the VX_DSYNC caching advisory has been set. .IP The .CR closesync , .C dsync and .C direct values all cause the equivalent of an .IR fsync (2) to be run when the file is closed. See .IR vxfsio (7) for an explanation of VX_DIRECT and VX_DSYNC. .IP The .C tmpcache value disables delayed extending writes, trading off integrity for performance. When this option is chosen, VxFS does not zero out new extents allocated as files are sequentially written. Uninitialized data may appear in files being written at the time of a system crash. .TP .C convosync=direct|dsync|closesync|delay This option is used to alter the caching behavior of the file system for O_SYNC I/O operations. .IP The .C direct value causes any reads or writes with the O_SYNC flag to be handled as if the VX_DIRECT caching advisory was set instead. .IP The .C dsync value causes any writes with the O_SYNC flag to be handled as if the VX_DSYNC caching advisory was set instead. .IP The .C closesync value causes O_SYNC writes to be delayed rather than to take effect immediately. The .CR closesync , .CR dsync , and .C direct values all cause the equivalent of an .IR fsync (2) to be run when any file is accessed with the O_SYNC flag is closed. .IP The .C delay value causes O_SYNC writes to be delayed rather than to take effect immediately. Choosing this option causes VxFS to change all O_SYNC writes into delayed writes. No special action is performed when closing a file. This option effectively cancels any data integrity guarantees normally provided by opening a file with O_SYNC. .TP .C datainlog|nodatainlog Normally, the VxFS file system performs small O_SYNC write requests and NFS write requests by logging both the data and the time change to the inode .RC ( datainlog ). If the .C nodatainlog option is used, the logging of synchronous write data is disabled; such writes will write the data into the file and update the inode synchronously before returning to the user. .TP .C largefiles|nolargefiles If one of these options is specified, the file system mount will fail if the .I largefile compatibility bit for the file system does not match the option specified. If .C nolargefiles is specified and the mount succeeds, then the file system does not contain any files whose size is 2 gigabytes or larger, and such files cannot be created. If .C largefiles is specified and the mount succeeds, then the file system may contain files whose size is 2 gigabytes or larger, and large files can be created. The default is to mount the file system according to the .IR "largefile compatibility bit" (see .IR fsadm_vxfs (1M) and .IR mkfs_vxfs (1M).) .RE .TP .C \-p Report the list of mounted file systems in the .CR /etc/fstab format. .TP .C \-Q Prevent display of error messages, resulting from an attempt to mount already mounted file systems. .TP .C \-r Mount the specified file system as read-only. Physically write-protected file systems must be mounted in this way or errors occur when access times are updated, whether or not any explicit write is attempted. .TP .C \-v Reports the regular output with file system type and flags, however, .IR directory " and" " special" fields are reversed. .TP .C \-V Echoes the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR "/etc/fstab" . This option allows the user to verify the command line. .SS .CR umount recognizes the following options: .RS .TP 15 .C \-a Attempt to unmount all file systems described in .CR /etc/mnttab . All optional fields in .C /etc/mnttab must be included and supported. If .C "\-F vxfs" is specified, all VxFS file systems in .C /etc/mnttab are unmounted. File systems are not necessarily unmounted in the order listed in .CR /etc/mnttab . .TP 15 .C "\-F vxfs" Specifies the file system type .RC ( vxfs ). .TP 15 .C \-v Verbose mode. Write a message to the standard output indicating which file system is being unmounted. .TP .C \-V Echoes the completed command line, but performs no other action. The command line is generated by incorporating the user-specified options and other information derived from .CR "/etc/fstab" . This option allows the user to verify the command line. .SH EXAMPLES List the file systems currently mounted: .IP .C mount .PP Mount a VxFS file system .C /dev/dsk/c1d2s0 at directory .C /home .IP .C mount \-F vxfs /dev/dsk/c1d2s0 /home .PP Unmount the same file system: .IP .C umount /dev/dsk/c1d2s0 .SH FILES .TP 20 .PD 0 .C /etc/fstab Static information about the file systems .TP .C /etc/mnttab Mounted file system table .PD .SH SEE ALSO fsadm_vxfs(1M), fsck_vxfs(1M), mkfs_vxfs(1M), mount(1M), mount(2), fsync(2), fstab(4), mnttab(4), quota(5), vxfsio(7). .SH STANDARDS CONFORMANCE .PP .C mount: SVID3 .br .C umount: SVID3 .\" .\" toc@\f3mount_vxfs(1M)\f1:\0\0\f(CWmount\f1, \f(CWunmount\f1@@@mount and unmount VxFS file system .\" toc@\f(CWunmount\f1:\0\0unmount VxFS file system@@@\f1see \f3mount_vxfs(1M)\f1 .\" .\" index@\f(CWmount_vxfs\f1 \- mount and unmount VxFS file system@@@\f3mount_vxfs(1M)\f1 .\" index@\f(CWmount\f1 \- mount VxFS file system@@@\f3mount_vxfs(1M)\f1 .\" index@\f(CWumount\f1 \- unmount VxFS file system@@@\f3mount_vxfs(1M)\f1 .\" .\" index@\f1mount and unmount VxFS file system@@@\f3mount_vxfs(1M)\f1 .\" index@\f1unmount VxFS file system@@@\f3mount_vxfs(1M)\f1 .\" index@\f1VxFS file system, mount and unmount@@@\f3mount_vxfs(1M)\f1 .\" index@\f1file system, mount and unmount VxFS@@@\f3mount_vxfs(1M)\f1 .\" .\" links@mount_vxfs.1m umount_vxfs.1m .\" $Header: mountall.1m,v 76.1 95/07/06 15:04:16 ssa Exp $ .TA m .TH mountall 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mountall, umountall \- mount and unmount multiple file systems .SH SYNOPSIS .C /sbin/mountall .RC [ -F .IR FStype ] .RC [ -l | -r ] .RI [ file_system_table | .CR - ] .br .C /sbin/mountall .RC [ -l | -r ] .RC [ -m ] .br .C /sbin/mountall .RC [ -n ] .br .C /sbin/umountall .RC [ -F .IR FStype ] .RC [ -k ] .RC [ -l | -r ] .SH DESCRIPTION .C mountall is used to mount file systems according to .I file_system_table. By default, .C /etc/fstab is the .IR file_system_table . If a dash .RC ( - ) is specified, .CR mountall reads .I file_system_table from the standard input; the standard input must be in the same format as the .CR /etc/fstab . .PP Before each file system is mounted, a check is done using .CR fsck (see .IR fsck (1M)) to ensure that the file system is mountable. If the file system is not mountable, it is repaired by .CR fsck before the mount is attempted. .PP .C umountall causes all mounted file systems except the non-removable file systems such as .CR root to be unmounted. .SS Options .C mountall and .C umountall recognize the following options: .RS .TP 15 .CI -F " FStype" Specify the file system type .RI ( FStype ) to be mounted or unmounted. .TP 15 .C -l Specify action on local file systems only. .TP 15 .C -r Specify action on remote file systems only. .TP 15 .C -k Send a .C SIGKILL signal to processes that have files opened. .TP 15 .C -m Attempt to mount all the unmounted file systems. This option will not perform the file system consistency check and repair. .TP 15 .C -n Perform the file system consistency check and repair on all unmounted file system. This option will not mount the file systems. .SH DIAGNOSTICS Error and warning messages may originate from .CR fsck , .CR mount , .CR fuser , or .CR umount . See .IR fsck (1M), .IR mount (1M), or .IR fuser (1M) to interpret the error and warning messages. .SH EXAMPLES .PP Mount all unmounted file systems listed in .CR /etc/fstab : .IP .C mountall .PP Mount all local file systems listed in .CR /etc/fstab : .IP .C mountall -l .PP Mount all remote file systems listed in .CR /etc/fstab : .IP .C mountall -r .PP Mount all local hfs file systems: .IP .C mountall -F hfs -l .PP Unmount all NFS file systems and kill any processes that have files opened in the file system: .IP .C umountall -F nfs -k .SH WARNINGS .PP .CR umountall , especially with the .CR -k option, should be used with extreme caution, because it can cause severe damage. .PP The .C -n option may not be available in future releases. .PP .C mountall may not be effective with some cases of LOFS file systems. .SH FILES .TP 20 .C /etc/fstab Static information about the file systems .PD 0 .TP .C /etc/mnttab Mounted file system table .PD .SH SEE ALSO fsck(1M), mount(1M), fuser(1M), mnttab(4), fstab(4), signal(2) .\" .\" toc@\f3mountall(1M)\f1:\0\0\f4mountall\f1, \f4umountall\f1@@@mount and unmount multiple file systems .\" index@\f4mountall\f1 \- mount multiple file systems@@@\f3mountall(1M)\f1 .\" index@\f4umountall\f1 \- unmount multiple file systems@@@\f3mountall(1M)\f1 .\" index@\f1 unmount multiple file systems@@@\f3mountall(1M)\f1 .\" index@\f1 mount multiple file systems@@@\f3mountall(1M)\f1 .\" index@\f1 multiple file systems, mount and unmount@@@\f3mountall(1M)\f1 .\" index@\f1 file systems, mount and unmount multiple@@@\f3mountall(1M)\f1 .\" .\" links@mountall.1m umountall.1m .\" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" HISTORY COMMENTS: ...\" ...\" DATE: COMMENT: ...\" ...\" Fri Oct 25, 1991 Initial File Submission for final ...\" integration at IBM ...\" ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH unadvertise 1m .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .iX "\*Ldtscp\*O commands" "\*Lunadvertise\*O" .iX "-l" "global servers" "removing entries" .iX "-m" "DTS servers" "removing entries from profile" .SH NAME .PP \*Lunadvertise\*O - Removes the global server entry from the cell profile .SH "SYNOPSIS" .PP .zA "defect,6211,R1.0.3,add control program name" .sS \*Ldtscp unadvertise\*O .sE .zZ "defect,6211,R1.0.3,add control program name" .SH "DESCRIPTION" .PP The \*Lunadvertise\*O command causes DTS to remove the server's name from the cell profile and binding from the related CDS entry, deleting the server's global status. .SS "Privilege Required" .PP You must have write permission on the ACL associated with the DTS entity in order to execute the command. ...\".SH "EXIT VALUES" ...\".PP ...\".VL 8m ...\".LI "System Error" ...\"The command failed due to an operating system ...\"error. ...\".LI "Wrong State" ...\"The command failed because the DTS ...\"entity is in the \*Loff\*O state. ...\".LE .zA "defect, 11818, R1.1, Added caveat" .SH "NOTE" This command is replaced at Revision 1.1 by the \*Ldcecp\*O command and may not be provided in future releases of DCE. .zZ "defect, 11818, R1.1, Added caveat" .SH "EXAMPLES" .PP .iS \*Cdtscp>\*O \*Lunadvertise\*O .iE .SH "RELATED INFORMATION" .PP Commands: \*Ladvertise(1m)\*O .\" $Header: link.1m,v 76.1 95/07/10 17:05:32 ssa Exp $ .TA l .TH link 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME link, unlink \- execute .CR link() and .CR unlink() system calls without error checking .SH SYNOPSIS .CR /usr/sbin/link .I file1 .I file2 .PP .CR /usr/sbin/unlink .I file .SH DESCRIPTION The .CR link and .CR unlink commands perform their respective system calls .RC ( link() \ or\ unlink() ) on their arguments, abandoning most error checking. .PP These commands can be executed only by users who have appropriate privileges. .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_MESSAGES determines the language in which messages are displayed. .PP If .C LC_MESSAGES is not specified in the environment or is set to the empty string, the value of .C LANG is used as a default for each unspecified or empty variable. If .C LANG is not specified or is set to the empty string, a default of "C" (see .IR lang (5)) is used instead of .CR LANG . .PP If any internationalization variable contains an invalid setting, .C link behaves as if all internationalization variables are set to "C". See .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .CR link and .CR unlink return the following values: .RS .TP .PD 0 .CR 0 Operation successful. .TP .CR 1 Input syntax error. .TP .CR 2 The .CR link() or .CR unlink() call failed. .PD .RE .SH WARNINGS If a directory that contains files other than .CR . and .CR .. is unlinked, the files become orphans, unless they are also linked by some other directory. .PP Not all file systems permit linking to directories. .SH SEE ALSO ln(1), rm(1), link(2), unlink(2). .SH STANDARDS CONFORMANCE .CR link ": SVID2, SVID3" .PP .CR unlink ": SVID2, SVID3" .\" .\" index@\f4link\f1 \- execute \f4link()\f1 system call without error checks@@@\f3link(1M)\f1 .\" index@\f4unlink\f1 \- execute \f4unlink()\f1 system call without error checks@@@\f3link(1M)\f1 .\" index@\f4link()\f1 system call, execute without error checks@@@\f3link(1M)\f1 .\" index@\f4unlink()\f1 system call, execute without error checks@@@\f3link(1M)\f1 .\" .\" toc@\f3link(1M)\f1:\0\0\f4link\f1, \f4unlink\f1@@@execute \f4link()\f1 and \f4unlink()\f1 system calls without error checking .\" toc@\f4unlink\f1:\0\0execute \f4unlink()\f1 system call without error checking@@@see \f3link(1M)\f1 .\" .\" links@link.1m unlink.1m .\" $Header: untic.1m,v 72.4 94/06/30 15:33:09 ssa Exp $ .TA u .TH untic 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME untic \- terminfo de-compiler .SH SYNOPSIS .C untic .RI [ term ] .RC [ -f .IR file ] .SH DESCRIPTION .CR untic translates a terminfo file from the compiled format into the source format. If the environment variable .CR TERMINFO is set to a path name, .CR untic checks for a compiled terminfo description of the terminal under the path specified by .CR TERMINFO before checking .CR /usr/share/lib/terminfo . Otherwise, only .CR /usr/share/lib/terminfo is checked. .PP Normally .CR untic uses the terminal type obtained from the .CR TERM environment variable. With the .I term (terminal type) argument, however, the user can specify the terminal type used. .PP With the .I file argument the user can specify the file used for translation. This option bypasses the use of the .CR TERM and .CR TERMINFO environment variables. .PP .CR untic sends the de-compiled terminfo description result to standard output. .SH AUTHOR .CR untic was developed by HP. .SH FILES .TP 30 .CR /usr/share/lib/terminfo/?/* compiled terminal capability data base .SH SEE ALSO tic(1M), curses(3X), terminfo(4). .\" .\" index@\f4untic\f1 \- terminfo de-compiler@@@\f3untic(1M)\f1 .\" index@terminfo de-compiler@@@\f3untic(1M)\f1 .\" index@uncompile terminfo data base@@@\f3untic(1M)\f1 .\" index@de-compile terminfo data base@@@\f3untic(1M)\f1 .\" index@terminfo data base, de-compile@@@\f3untic(1M)\f1 .\" index@data base, terminfo, de-compile@@@\f3untic(1M)\f1 .\" .\" toc@\f3untic(1M)\f1:\0\0\f4untic\f1@@@terminfo de-compiler .\" .\" fileset_database@untic.1m SYS-ADMIN-MAN .\" $Header: update.1m,v 78.2 96/05/09 11:05:40 ssa Exp $ .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro, e.g. .CR, .RI, .\" etc. A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .TA u .TH update 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME update, updist \- update or install \s-1HP-UX\s+1 files (software products) .SH SYNOPSIS .RC [ UPDATESCRIPT='\c .RI [ \|filename\| ]\c .CR ' ] .br .C /usr/sbin/update .RC [ -F ] .RC [ -s .IR source\| ] .RC [ -S .IR series\| ] .RC [ -P .IR port\| ] .RC [ -d .IR destination\| ] .RC [ -f .IR file\| ] .RI [ fileset ...] .br .C /usr/sbin/update .C -c .RC [ -s .IR source\| ] .RC [ -S .IR series\| ] .RC [ -P .IR port\| ] .PP .RC [ UPDISTSCRIPT='\c .RI [ \|filename\| ]\c .CR '\| ] .br .C /usr/sbin/updist (same options as .CR /usr/sbin/update ) .PP .SH DESCRIPTION .C update on .SM HP-UX 10.0* is used interactively or non-interactively to: .RS .TP 3 \(bu Install new .SM HP-UX application software (optional products) .TP \(bu Update existing application software .RE .PP Note that .C update on .SM HP-UX 10.* no longer updates or installs operating system and core product files. .PP The .C updist command is similar to .CR update , except that it installs or updates the application files as ``fileset packages'' in a special directory. This allows the system to be a network file distribution (netdist) server. The .C netdistd network server daemon finds the files in this special directory and supplies them to a remote .C update process on request (see .IR netdistd (1M)). .PP If no options or fileset names are specified, .C update and .C updist run interactively, providing help screens to aid in selection of installation or update options. To set default values for interactive sessions, use an ``update script'' (see Update Scripts below). If one or more options or fileset names are specified, .C update and .C updist run non-interactively as indicated by the options and fileset names given. .PP .C update and .C updist load files from these types of update media: .RS .TP 3 \(bu .CR tar -format serial media, normally nine-track, cartridge, or .SM DDS tapes, or an ordinary file containing an appropriate .C tar image .TP \(bu systems configured to be netdist servers .RE .PP Tape update media consist of simple .C tar archives containing product files and directories (see .IR tar (1)), plus a few leading information files, and specially-crafted file paths that allow files to be grouped into filesets (see Filesets and Partitions below; also .IR update (4)). When run non-interactively, .C update and .C updist run unattended and therefore do not allow loading from multiple media units (tapes). If an attempt is made to load from multiple media non-interactively, .C update refuses to begin loading; .C updist loads from the first media unit only, then terminates with a warning message. .PP When updating from a netdist server system, the update ``media'' consists of a collection of files in a directory hierarchy plus various information files that, together, act as a single media volume. .PP Before loading any filesets, .C update and .C updist calculate the additional disk space consumed by the installation or update. This prevents loading of filesets when sufficient disk space is not available. .PP Only the super-user can run .C update and .CR updist . .SS Options .C update and .C updist support the following options when used non-interactively: .TP 15 .C -F Force non-interactive loading to proceed even if certain conditions are encountered that normally would be errors. These conditions would all be warnings if the program were run interactively. They include: .RS .RS .TP 3 \(bu Fileset version older on update media than already loaded on system. .TP \(bu Disk space short (invades minfree) but sufficient on one or more volumes. .TP \(bu Swap space insufficient or cannot be determined (S800 only). .RE .RE .TP .CI -s \0source Specify a non-default source for the update. .I source can be: .RS .RS .TP 3 \(bu Absolute path name of local special file representing a nine-track, cartridge, or .SM DDS tape. .PD 0 .TP \(bu Absolute path name of regular file containing an update media image in .C tar format. .TP \(bu Hostname of a netdist server system running the .C netdistd daemon. .PD .RE .RE .IP The default .I source is .C /dev/rmt/0m on all systems. .TP .CI -S \0series Specify Series 700 .RC ( -S700 ), or Series 800 .RC ( -S800 ) for the type of files you expect to extract from the source media. The default is the type of system on which .C update or .C updist is run. Use this option when: .RS .RS .TP 3 \(bu Loading files for the non-default system type from a netdist server system. .TP \(bu Using .C updist to load a netdist tree using update media that is made for more than one type of system. (Beginning at .SM HP-UX Release 8.05, media can be made for all series of .SM HP 9000 computers. Older media for Series 800 systems can be loaded on Series 700 systems too, although in most cases this is not advisable.) .RE .IP The value of the .C -S option is ignored except when it is needed for either of the two above purposes. .RE .TP .CI -P \0port Set the port number for the netdist service (applies only if the source is a netdist server). This option overrides the number in the network services database (see .SM FILES below). It is useful when a netdist server system offers various software packages through different netdist servers at different port numbers. .TP .CI -d \0destination Specify a non-default destination directory under which filesets are unpacked. For .CR update , the default destination is .CR / . Some filesets .I require that the destination directory be .CR / . This option is used for updating an application that can be installed anywhere on the file system. .IP For .CR updist , the default destination is .CR /netdist . This option is used for creating alternate source trees for .CR netdistd . .TP .CI -f \0file Read from the specified file, rather than from the command line, the list of filesets or partitions to be loaded (see Filesets and Partitions below). Blank lines and comments in the file are ignored. Comments are remainders of lines beginning with .C # following whitespace or at the start of a line. .TP .C -c Produce a table of contents from the source media. .C update and .C updist write a list of .IC partition \|.\| fileset names to standard output, one name per line (see Filesets and Partitions below). The output includes comments describing the size of each fileset, its media unit number, any associated fileset flags (see .IR update (4)), its version number, and its description. The output is usable as input to the .C -f option. Comment out or delete the lines for any filesets you do not want to load. .PP The .C -f option cannot be used when naming filesets explicitly, and vice-versa. .SS Filesets and Partitions .C update and .C updist load units called ``filesets'' that are groups of related files. One or more filesets can be further grouped into logical ``partitions''. Filesets and partitions are the items that you can choose from when updating. .PP One or more filesets or partitions can be selected for loading. The format of partition/fileset names is: .IP .IC partition \|.\| fileset .PP The following shorthand specifications are allowed: .RS .TP 15 .I partition Select all filesets in a partition. .TP .I fileset Select an individual fileset. .TP .C * Select all filesets on the media. The .C * must be escaped in the command line to prevent its expansion by the shell. .RE .PP Any fileset might require other filesets on which it depends. The update media includes this dependency information. Thus, selection of a fileset with dependencies (interactively or from the command line) causes automatic selection of other required filesets if they are not already present on the system (or for .CR updist , in the netdist source tree) with a version number equal to or greater than that required. (Version numbers are stored in per-fileset index files; see .SM FILES below.) Likewise, interactive unselection of a fileset causes automatic unselection of its other required filesets, unless you explicitly selected them or selected other filesets that require them. .PP .C update creates or rewrites fileset lists in ``fileset files'' under the filesets directory (see .SM FILES below). Each file in this directory has the same name as the fileset it represents. Each line in a filesets file is the full, absolute path name (actual destination) of a corresponding file loaded as part of the fileset. .PP .SS Updating Netdist Server Master Files .C updist transfers filesets from update media to a special tree under the local file system of an .C update server system and prepares the filesets for use by the .C netdistd server process. .C updist differs from .C update as follows: .RS .TP 3 \(bu The default destination is .CR /netdist . .PD 0 .TP \(bu Fileset files are not created. .TP \(bu Customize scripts are not run. .TP \(bu Other information files are prepared under the special tree. .PD .RE .SS Mounted Volumes and Links .C update and .C updist avoid loading files under directories that are on read-only file systems or those normally used as .SM NFS mount points. Both commands begin by executing .C mount -a with errors ignored. They then check and require that all disks listed in .C /etc/fstab are indeed mounted (the disks must be listed in .CR /etc/mnttab ). .PP .C update and .C updist break hard links when re-creating updated files. They also follow symbolic links and update the targets of the symbolic links. .C update records in fileset files the absolute path of updated files, after resolving any symbolic links. .SS Update Scripts An update script is a shell script that captures the program status of an interactive session. This is helpful if you want to run .C update or .C updist non-interactively later (for example, via .C remsh on a different system, or possibly repeated on the same system). Saved values from a previous interactive session also provide an optional set of default values for the next time you run .C update or .C updist interactively, as described below. The update script also serves as an added audit trail. .PP The update script is created or rewritten just before confirmation is requested to begin loading, each time that that point is reached (if confirmation is denied). .C update writes to the .C /var/tmp/update.script file and .C updist writes to .CR /var/tmp/updist.script . .PP Note: some conditions that cause warnings when running interactively cause errors when running non-interactively. Also, the update script is not guaranteed to run successfully on a remote system where the context is different, especially if it is of a different Series type. .PP If the .C UPDATESCRIPT (for .CR updist , .CR UPDISTSCRIPT ) environment variable is set, .C update or .C updist attempts to read the file named in the variable as an update script (shell script) in a specific format emitted by an earlier invocation of the same program. For example: .IP .C UPDATESCRIPT='/var/tmp/update.script' /usr/sbin/update .PP If the variable value is null, the program reads the appropriate default update script name. For example, the following causes .C updist to read .CR /tmp/updist.script : .IP .C UPDISTSCRIPT='' /etc/updist .PP In the unlikely event you want to create an update script by hand, the update script format is documented in .IR update (4). .PP If the program is able to ``read back'' the update script correctly, it uses the values found there as default values for selected environment variables, the update source and destination and related values, the target Series type, kernel building information, and selected fileset names. .PP If the previous invocation of .C update or .C updist involved the ``Select Only Filesets Currently on your System'' choice, and no changes were then made to the auto-selected filesets, the update script file contains the .C -m option and no fileset names. If on the other hand the update script does contain a list of fileset names, they are automatically pre-selected after readback. However, this only occurs if and when the first selection option chosen on the main screen is .CR "Select/View Partitions and Filesets" . Also, only listed filesets found on the current update media are selected this way. .SH DIAGNOSTICS Messages are displayed during interactive execution, and error messages result from invalid non-interactive invocation. For information about any failures encountered while loading filesets in either mode, inspect the log file (see .SM FILES below). .SH EXAMPLES Update or install the filesets .C DATA1 and .C DATA2 on the system using the default source device and destination directory: .IP .C update DATA1 DATA2 .PP Update or install all filesets on the media in the default source device under the directory .CR /tmp : .IP .C update -d /tmp '*' .PP Print the contents of the update media accessed through special file .CR /dev/rmt : .IP .C update -c -s /dev/rmt .PP Extract fileset .C TEXT-FMT from the default source device and make it available to other systems via .CR netdistd . In this example, .C /pseudoroot is the directory from which .C netdistd draws its files: .IP .C "updist -d /pseudoroot TEXT-FMT" .SH WARNINGS Always review the log file .C /var/tmp/update.log after an update for relevant errors, warnings, and other messages. .PP If any loaded fileset is flagged for reboot, that flag is ignored. .PP The .C rmfn command cannot be used to remove packages loaded by .CR updist . .PP When run interactively, .C update and .C updist depend on the .C TERM environment variable to determine the display type. If the variable is absent or has the wrong value, the display might behave oddly. .PP Interactive .C update and .C updist use special function keys .SM (SFKs) extensively. They do not save or restore user function-key definitions after the update is complete. .SH DEPENDENCIES .SS \s-1NFS\s0 .C update and .C updist refuse to update files on remote systems over .SM NFS network connections. They pre-mount all normally mounted volumes, including .SM NFS mounts, to ensure that such files are detected and that unwanted files are not deposited under the mount point on the local disk. .C update and .C updist complete loading all local files, give warnings about remote files not loaded, and return 0 if no other problems are detected. .SS Networking To load files from a netdist server system, networking services must be configured into the local kernel and turned on. .SH AUTHOR .C update and .C updist were developed by .SM HP. .SH FILES .PD 0 .TP 30 .C /dev/rmt/0m default source for Series 700 and 800 systems .TP .C / default destination for .C update .TP .C /netdist default destination for .C updist and source for .C netdistd .TP .C /var/adm/rupdate/filesets directory where fileset files are stored .TP .C /var/adm/rupdate/system directory containing important information about and customize scripts for each fileset .TP .CI /var/adm/rupdate/system/ fileset /index provides information about the fileset, in particular, its version .RC ( update uses the version to decide if a dependee fileset is already current on the system and need not be reloaded) .TP .CI /var/adm/rupdate/system/ fileset /update_dest names the destination directory under which a fileset was loaded, if other than .CR / . .TP .C /var/tmp/update.log log file describing the events that occurred during the update process, including errors, warnings, and notes .TP .C /var/tmp/update.cleanup list of files logged as non-removable, usually due to ``text file busy'' .TP .C /var/tmp/update.script file written during interactive invocation for later non-interactive invocation and for readback of default values .TP .C /var/tmp/updist.script same, but emitted by .C updist .TP .C /var/tmp/update.kernbld used by cluster nodes to rebuild their kernels at the next reboot .TP .C /usr/lib/rupdate/jam directory containing .SM JAM user interface information .TP .C /usr/lib/rupdate/update directory containing files used by .C update and .C updist when run interactively .TP .C /etc/services networking services database, file describing networking services, including the netdist service .TP .C /etc/fstab list of volumes that should be mounted .TP .C /etc/mnttab list of volumes currently mounted .PD .SH SEE ALSO tar(1), sam(1M), mount(1M), sd(4), sd(5), swacl(1M), swagentd(1M), swcluster(1M), swconfig(1M), swcopy(1M), swgettools(1M), swinstall(1M), swjob(1M), swlist(1M), swmodify(1M), swpackage(1M), swpackage(4), swreg(1M), swremove(1M), swverify(1M), and the .IR "HP OpenView Software Distributor Administrator's Guide" or .IR "Managing HP-UX Software with SD-UX" manuals. . .\" index@\f4update\f1, \f4updist\f1 \- update or install \s-1HP-UX\s+1 files (software products)@@@\f3update(1M)\f1 .\" index@\f4updist\f1 \- update or install \s-1HP-UX\s+1 files for network distribution@@@\f3update(1M)\f1 .\" index@install or update \s-1HP-UX\s+1 files (software products)@@@\f3update(1M)\f1 .\" index@distributed install or update of \s-1HP-UX\s+1 files (software products)@@@\f3update(1M)\f1 .\" index@network install or update of \s-1HP-UX\s+1 files (software products)@@@\f3update(1M)\f1 .\" index@remote install or update of \s-1HP-UX\s+1 files (software products)@@@\f3update(1M)\f1 .\" index@\s-1HP-UX\s+1 files (software products), update or install@@@\f3update(1M)\f1 .\" index@optional \s-1HP-UX\s+1 software products, update or install@@@\f3update(1M)\f1 .\" index@software products, \s-1HP-UX\s+1, update or install@@@\f3update(1M)\f1 .\" index@products, software, \s-1HP-UX\s+1, update or install@@@\f3update(1M)\f1 .\" .\" toc@\f3update(1M)\f1:\0\0\f4update\f1, \f4updist\f1@@@update or install \s-1HP-UX\s+1 files (software products) .\" toc@\f4updist\f1 \- update or install \s-1HP-UX\s+1 files (software products)@@@see \f3update(1M)\f1 .\" .\" links@update.1m updist.1m .\" $Header: updaters.1m,v 72.2 94/08/25 14:14:57 ssa Exp $ .TA u .TH updaters 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME updaters \- configuration file for NIS updating .SH SYNOPSIS .C updaters .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. .SH DESCRIPTION .CR updaters is a makefile used for updating the Network Information Service (NIS) databases. Databases can be updated only if the network is secure, that is, only if there is a NIS .CR publickey database ( .CR publickey.byname ). The default .CR updaters script will update only the .CR publickey.byname map. .PP An entry in the file is a make target for a particular NIS database. For example, if you wanted to add .CR passwd.byname to this script, you would create a make target named passwd.byname with the command to update that database. See .CR udpublickey (1M). .PP The information necessary to make the update is passed to the update command through standard input. The information passed is described below. All items are followed by a NEW LINE except for Actual bytes of key and Actual bytes of data. .PP .RS .TP .C "Network name of client wishing to make the update (a string)" .TP .C "Kind of update (an integer)" .TP .C "Number of bytes in key (an integer)" .TP .C "Actual bytes of key" .TP .C "Number of bytes in data (an integer)" .TP .C "Actual bytes of data" .RE .PP After receiving this information through standard input, the command to update the particular database should decide whether the user is allowed to make the requested change. .PP If not, the command should exit with the status .CR YPERR_ACCESS . .PP If the user is allowed to make the change, the command should make the change and exit with a status of zero. .PP If there are any errors that may prevent the updater from making the change, it should exit with the status that matches a valid NIS error code described in .CR . .SH AUTHOR .CR updaters was developed by Sun Microsystems, Inc. .SH SEE ALSO make(1), newkey(1M), rpc.ypupdated(1M), udpublickey(1M), publickey(4). .\" .\" toc@\f3updaters(1M)\f1:\0\0\f4updaters\f1@@@configuration file for NIS updating .\" .\" index@\f4updaters\f1\- configuration file for NIS updating@@@\f3updaters(1M)\f1 .\" .\" index@configuration file for NIS updating@@@\f3updaters(1M)\f1 .\" index@NIS updating, configuration file for@@@\f3updaters(1M)\f1 .\" index@updating, configuration file for NIS@@@\f3updaters(1M)\f1 .\" $Header: update.1m,v 78.2 96/05/09 11:05:40 ssa Exp $ .\" .\" The '@' symbol (indicated by '\*(at' without the quotes) gives .\" eroff problems. To prevent these problems, '@' must be used as .\" a display and cannot appear inside of a font macro, e.g. .CR, .RI, .\" etc. A line containing the '@' must be split using the \c .\" (continuation) and \0 (space) commands appropriately. .\" .\" The following two .if command lines MUST appear at the beginning .\" of the file for the '\*(at' sequence to display the '@' symbol properly: .\" .ift .ds at \f4\s+1@\s0\fP\c .ifn .ds at \f3@\fP\c .TA u .TH update 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME update, updist \- update or install \s-1HP-UX\s+1 files (software products) .SH SYNOPSIS .RC [ UPDATESCRIPT='\c .RI [ \|filename\| ]\c .CR ' ] .br .C /usr/sbin/update .RC [ -F ] .RC [ -s .IR source\| ] .RC [ -S .IR series\| ] .RC [ -P .IR port\| ] .RC [ -d .IR destination\| ] .RC [ -f .IR file\| ] .RI [ fileset ...] .br .C /usr/sbin/update .C -c .RC [ -s .IR source\| ] .RC [ -S .IR series\| ] .RC [ -P .IR port\| ] .PP .RC [ UPDISTSCRIPT='\c .RI [ \|filename\| ]\c .CR '\| ] .br .C /usr/sbin/updist (same options as .CR /usr/sbin/update ) .PP .SH DESCRIPTION .C update on .SM HP-UX 10.0* is used interactively or non-interactively to: .RS .TP 3 \(bu Install new .SM HP-UX application software (optional products) .TP \(bu Update existing application software .RE .PP Note that .C update on .SM HP-UX 10.* no longer updates or installs operating system and core product files. .PP The .C updist command is similar to .CR update , except that it installs or updates the application files as ``fileset packages'' in a special directory. This allows the system to be a network file distribution (netdist) server. The .C netdistd network server daemon finds the files in this special directory and supplies them to a remote .C update process on request (see .IR netdistd (1M)). .PP If no options or fileset names are specified, .C update and .C updist run interactively, providing help screens to aid in selection of installation or update options. To set default values for interactive sessions, use an ``update script'' (see Update Scripts below). If one or more options or fileset names are specified, .C update and .C updist run non-interactively as indicated by the options and fileset names given. .PP .C update and .C updist load files from these types of update media: .RS .TP 3 \(bu .CR tar -format serial media, normally nine-track, cartridge, or .SM DDS tapes, or an ordinary file containing an appropriate .C tar image .TP \(bu systems configured to be netdist servers .RE .PP Tape update media consist of simple .C tar archives containing product files and directories (see .IR tar (1)), plus a few leading information files, and specially-crafted file paths that allow files to be grouped into filesets (see Filesets and Partitions below; also .IR update (4)). When run non-interactively, .C update and .C updist run unattended and therefore do not allow loading from multiple media units (tapes). If an attempt is made to load from multiple media non-interactively, .C update refuses to begin loading; .C updist loads from the first media unit only, then terminates with a warning message. .PP When updating from a netdist server system, the update ``media'' consists of a collection of files in a directory hierarchy plus various information files that, together, act as a single media volume. .PP Before loading any filesets, .C update and .C updist calculate the additional disk space consumed by the installation or update. This prevents loading of filesets when sufficient disk space is not available. .PP Only the super-user can run .C update and .CR updist . .SS Options .C update and .C updist support the following options when used non-interactively: .TP 15 .C -F Force non-interactive loading to proceed even if certain conditions are encountered that normally would be errors. These conditions would all be warnings if the program were run interactively. They include: .RS .RS .TP 3 \(bu Fileset version older on update media than already loaded on system. .TP \(bu Disk space short (invades minfree) but sufficient on one or more volumes. .TP \(bu Swap space insufficient or cannot be determined (S800 only). .RE .RE .TP .CI -s \0source Specify a non-default source for the update. .I source can be: .RS .RS .TP 3 \(bu Absolute path name of local special file representing a nine-track, cartridge, or .SM DDS tape. .PD 0 .TP \(bu Absolute path name of regular file containing an update media image in .C tar format. .TP \(bu Hostname of a netdist server system running the .C netdistd daemon. .PD .RE .RE .IP The default .I source is .C /dev/rmt/0m on all systems. .TP .CI -S \0series Specify Series 700 .RC ( -S700 ), or Series 800 .RC ( -S800 ) for the type of files you expect to extract from the source media. The default is the type of system on which .C update or .C updist is run. Use this option when: .RS .RS .TP 3 \(bu Loading files for the non-default system type from a netdist server system. .TP \(bu Using .C updist to load a netdist tree using update media that is made for more than one type of system. (Beginning at .SM HP-UX Release 8.05, media can be made for all series of .SM HP 9000 computers. Older media for Series 800 systems can be loaded on Series 700 systems too, although in most cases this is not advisable.) .RE .IP The value of the .C -S option is ignored except when it is needed for either of the two above purposes. .RE .TP .CI -P \0port Set the port number for the netdist service (applies only if the source is a netdist server). This option overrides the number in the network services database (see .SM FILES below). It is useful when a netdist server system offers various software packages through different netdist servers at different port numbers. .TP .CI -d \0destination Specify a non-default destination directory under which filesets are unpacked. For .CR update , the default destination is .CR / . Some filesets .I require that the destination directory be .CR / . This option is used for updating an application that can be installed anywhere on the file system. .IP For .CR updist , the default destination is .CR /netdist . This option is used for creating alternate source trees for .CR netdistd . .TP .CI -f \0file Read from the specified file, rather than from the command line, the list of filesets or partitions to be loaded (see Filesets and Partitions below). Blank lines and comments in the file are ignored. Comments are remainders of lines beginning with .C # following whitespace or at the start of a line. .TP .C -c Produce a table of contents from the source media. .C update and .C updist write a list of .IC partition \|.\| fileset names to standard output, one name per line (see Filesets and Partitions below). The output includes comments describing the size of each fileset, its media unit number, any associated fileset flags (see .IR update (4)), its version number, and its description. The output is usable as input to the .C -f option. Comment out or delete the lines for any filesets you do not want to load. .PP The .C -f option cannot be used when naming filesets explicitly, and vice-versa. .SS Filesets and Partitions .C update and .C updist load units called ``filesets'' that are groups of related files. One or more filesets can be further grouped into logical ``partitions''. Filesets and partitions are the items that you can choose from when updating. .PP One or more filesets or partitions can be selected for loading. The format of partition/fileset names is: .IP .IC partition \|.\| fileset .PP The following shorthand specifications are allowed: .RS .TP 15 .I partition Select all filesets in a partition. .TP .I fileset Select an individual fileset. .TP .C * Select all filesets on the media. The .C * must be escaped in the command line to prevent its expansion by the shell. .RE .PP Any fileset might require other filesets on which it depends. The update media includes this dependency information. Thus, selection of a fileset with dependencies (interactively or from the command line) causes automatic selection of other required filesets if they are not already present on the system (or for .CR updist , in the netdist source tree) with a version number equal to or greater than that required. (Version numbers are stored in per-fileset index files; see .SM FILES below.) Likewise, interactive unselection of a fileset causes automatic unselection of its other required filesets, unless you explicitly selected them or selected other filesets that require them. .PP .C update creates or rewrites fileset lists in ``fileset files'' under the filesets directory (see .SM FILES below). Each file in this directory has the same name as the fileset it represents. Each line in a filesets file is the full, absolute path name (actual destination) of a corresponding file loaded as part of the fileset. .PP .SS Updating Netdist Server Master Files .C updist transfers filesets from update media to a special tree under the local file system of an .C update server system and prepares the filesets for use by the .C netdistd server process. .C updist differs from .C update as follows: .RS .TP 3 \(bu The default destination is .CR /netdist . .PD 0 .TP \(bu Fileset files are not created. .TP \(bu Customize scripts are not run. .TP \(bu Other information files are prepared under the special tree. .PD .RE .SS Mounted Volumes and Links .C update and .C updist avoid loading files under directories that are on read-only file systems or those normally used as .SM NFS mount points. Both commands begin by executing .C mount -a with errors ignored. They then check and require that all disks listed in .C /etc/fstab are indeed mounted (the disks must be listed in .CR /etc/mnttab ). .PP .C update and .C updist break hard links when re-creating updated files. They also follow symbolic links and update the targets of the symbolic links. .C update records in fileset files the absolute path of updated files, after resolving any symbolic links. .SS Update Scripts An update script is a shell script that captures the program status of an interactive session. This is helpful if you want to run .C update or .C updist non-interactively later (for example, via .C remsh on a different system, or possibly repeated on the same system). Saved values from a previous interactive session also provide an optional set of default values for the next time you run .C update or .C updist interactively, as described below. The update script also serves as an added audit trail. .PP The update script is created or rewritten just before confirmation is requested to begin loading, each time that that point is reached (if confirmation is denied). .C update writes to the .C /var/tmp/update.script file and .C updist writes to .CR /var/tmp/updist.script . .PP Note: some conditions that cause warnings when running interactively cause errors when running non-interactively. Also, the update script is not guaranteed to run successfully on a remote system where the context is different, especially if it is of a different Series type. .PP If the .C UPDATESCRIPT (for .CR updist , .CR UPDISTSCRIPT ) environment variable is set, .C update or .C updist attempts to read the file named in the variable as an update script (shell script) in a specific format emitted by an earlier invocation of the same program. For example: .IP .C UPDATESCRIPT='/var/tmp/update.script' /usr/sbin/update .PP If the variable value is null, the program reads the appropriate default update script name. For example, the following causes .C updist to read .CR /tmp/updist.script : .IP .C UPDISTSCRIPT='' /etc/updist .PP In the unlikely event you want to create an update script by hand, the update script format is documented in .IR update (4). .PP If the program is able to ``read back'' the update script correctly, it uses the values found there as default values for selected environment variables, the update source and destination and related values, the target Series type, kernel building information, and selected fileset names. .PP If the previous invocation of .C update or .C updist involved the ``Select Only Filesets Currently on your System'' choice, and no changes were then made to the auto-selected filesets, the update script file contains the .C -m option and no fileset names. If on the other hand the update script does contain a list of fileset names, they are automatically pre-selected after readback. However, this only occurs if and when the first selection option chosen on the main screen is .CR "Select/View Partitions and Filesets" . Also, only listed filesets found on the current update media are selected this way. .SH DIAGNOSTICS Messages are displayed during interactive execution, and error messages result from invalid non-interactive invocation. For information about any failures encountered while loading filesets in either mode, inspect the log file (see .SM FILES below). .SH EXAMPLES Update or install the filesets .C DATA1 and .C DATA2 on the system using the default source device and destination directory: .IP .C update DATA1 DATA2 .PP Update or install all filesets on the media in the default source device under the directory .CR /tmp : .IP .C update -d /tmp '*' .PP Print the contents of the update media accessed through special file .CR /dev/rmt : .IP .C update -c -s /dev/rmt .PP Extract fileset .C TEXT-FMT from the default source device and make it available to other systems via .CR netdistd . In this example, .C /pseudoroot is the directory from which .C netdistd draws its files: .IP .C "updist -d /pseudoroot TEXT-FMT" .SH WARNINGS Always review the log file .C /var/tmp/update.log after an update for relevant errors, warnings, and other messages. .PP If any loaded fileset is flagged for reboot, that flag is ignored. .PP The .C rmfn command cannot be used to remove packages loaded by .CR updist . .PP When run interactively, .C update and .C updist depend on the .C TERM environment variable to determine the display type. If the variable is absent or has the wrong value, the display might behave oddly. .PP Interactive .C update and .C updist use special function keys .SM (SFKs) extensively. They do not save or restore user function-key definitions after the update is complete. .SH DEPENDENCIES .SS \s-1NFS\s0 .C update and .C updist refuse to update files on remote systems over .SM NFS network connections. They pre-mount all normally mounted volumes, including .SM NFS mounts, to ensure that such files are detected and that unwanted files are not deposited under the mount point on the local disk. .C update and .C updist complete loading all local files, give warnings about remote files not loaded, and return 0 if no other problems are detected. .SS Networking To load files from a netdist server system, networking services must be configured into the local kernel and turned on. .SH AUTHOR .C update and .C updist were developed by .SM HP. .SH FILES .PD 0 .TP 30 .C /dev/rmt/0m default source for Series 700 and 800 systems .TP .C / default destination for .C update .TP .C /netdist default destination for .C updist and source for .C netdistd .TP .C /var/adm/rupdate/filesets directory where fileset files are stored .TP .C /var/adm/rupdate/system directory containing important information about and customize scripts for each fileset .TP .CI /var/adm/rupdate/system/ fileset /index provides information about the fileset, in particular, its version .RC ( update uses the version to decide if a dependee fileset is already current on the system and need not be reloaded) .TP .CI /var/adm/rupdate/system/ fileset /update_dest names the destination directory under which a fileset was loaded, if other than .CR / . .TP .C /var/tmp/update.log log file describing the events that occurred during the update process, including errors, warnings, and notes .TP .C /var/tmp/update.cleanup list of files logged as non-removable, usually due to ``text file busy'' .TP .C /var/tmp/update.script file written during interactive invocation for later non-interactive invocation and for readback of default values .TP .C /var/tmp/updist.script same, but emitted by .C updist .TP .C /var/tmp/update.kernbld used by cluster nodes to rebuild their kernels at the next reboot .TP .C /usr/lib/rupdate/jam directory containing .SM JAM user interface information .TP .C /usr/lib/rupdate/update directory containing files used by .C update and .C updist when run interactively .TP .C /etc/services networking services database, file describing networking services, including the netdist service .TP .C /etc/fstab list of volumes that should be mounted .TP .C /etc/mnttab list of volumes currently mounted .PD .SH SEE ALSO tar(1), sam(1M), mount(1M), sd(4), sd(5), swacl(1M), swagentd(1M), swcluster(1M), swconfig(1M), swcopy(1M), swgettools(1M), swinstall(1M), swjob(1M), swlist(1M), swmodify(1M), swpackage(1M), swpackage(4), swreg(1M), swremove(1M), swverify(1M), and the .IR "HP OpenView Software Distributor Administrator's Guide" or .IR "Managing HP-UX Software with SD-UX" manuals. . .\" index@\f4update\f1, \f4updist\f1 \- update or install \s-1HP-UX\s+1 files (software products)@@@\f3update(1M)\f1 .\" index@\f4updist\f1 \- update or install \s-1HP-UX\s+1 files for network distribution@@@\f3update(1M)\f1 .\" index@install or update \s-1HP-UX\s+1 files (software products)@@@\f3update(1M)\f1 .\" index@distributed install or update of \s-1HP-UX\s+1 files (software products)@@@\f3update(1M)\f1 .\" index@network install or update of \s-1HP-UX\s+1 files (software products)@@@\f3update(1M)\f1 .\" index@remote install or update of \s-1HP-UX\s+1 files (software products)@@@\f3update(1M)\f1 .\" index@\s-1HP-UX\s+1 files (software products), update or install@@@\f3update(1M)\f1 .\" index@optional \s-1HP-UX\s+1 software products, update or install@@@\f3update(1M)\f1 .\" index@software products, \s-1HP-UX\s+1, update or install@@@\f3update(1M)\f1 .\" index@products, software, \s-1HP-UX\s+1, update or install@@@\f3update(1M)\f1 .\" .\" toc@\f3update(1M)\f1:\0\0\f4update\f1, \f4updist\f1@@@update or install \s-1HP-UX\s+1 files (software products) .\" toc@\f4updist\f1 \- update or install \s-1HP-UX\s+1 files (software products)@@@see \f3update(1M)\f1 .\" .\" links@update.1m updist.1m .\" $Header: ups_mond.1m,v 72.2 94/11/01 23:56:32 ssa Exp $ .TA u .TH ups_mond 1M "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not implemented on Series 700 computers (yet) .SH NAME ups_mond \- HP PowerTrust Uninterruptible Power System monitor daemon .SH SYNOPSIS .C /usr/lbin/ups_mond .RC [ -f .IR configfile\| ] .RC [ -s\| ] .SH DESCRIPTION When it detects a loss of AC power for a period of time exceeding a configured limit, .C ups_mond ensures file system integrity by shutting down .SM HP-UX. To do this, .C ups_mond uses the device special files specified in its configuration file .RC ( /etc/ups_conf by default) to monitor the state of each HP PowerTrust Uninterruptible Power System (UPS) attached to the system. .PP Use the .C -f option to specify a configuration file other than .CR /etc/ups_conf . See .IR ups_conf (4) for a description of the configuration file format. .PP By default, .CR ups_mond is locked into memory (see .IR plock (2)). That is, .CR ups_mond is not swappable. Although extreme caution is required, you can make .CR ups_mond swappable if all swap disks are powered by an uninterruptible power system (assured to have power when the primary power source fails). To make .CR ups_mond swappable, use the .CR -s option. .PP .CR ups_mond is started by .CR init (see .IR init (1M)) by means of an entry in the file .CR /etc/inittab (see .IR inittab (4)). The .CR inittab entry uses the .CR respawn option to automatically restart .C ups_mond if .C ups_mond is terminated by the .C kill command (see .IR kill (1)). This entry should follow the entry: .PP \f4 sqnc::wait:/sbin/rc /dev/console 2>&1 # system initialization\f1 .PP so that .C ups_mond is started after the system logging daemon .RC ( syslogd ). It should also be run with real-time priority to assure its execution (see .IR rtprio (1)). .PP .C ups_mond logs messages, and when appropriate invokes .C /usr/sbin/shutdown using the .C -h option, or .CR /usr/sbin/reboot . For each configured UPS, .C ups_mond can be instructed (in .CR /etc/ups_conf ) to log messages only, without taking .CR shutdown or .CR reboot action. See .SM MSG_ONLY in .IR ups_conf (4). By default .C ups_mond performs the .CR shutdown and .CR reboot actions. .PP Note that when the shutdown is performed, UPSs that have lost AC line voltage will be turned off once the .I shutdown_timeout_mins time has expired (see .IR upd_conf (4)). .PP .C ups_mond uses the .C syslog message logging facility to log these occurrences (see .IR syslog (3C)). Messages are written to the console if .C ups_mond is unable to send them to .CR syslogd . Critical messages (see DIAGNOSTICS section) are also sent to the console. .SH RETURN VALUE .PP .C ups_mond returns the following values: .RS .TP 13 zero (0) Successful Completion .PD 0 .TP non-zero Error encountered. See ERRORS below. .PD .RE .SH EXAMPLES .PP The entry in .C /etc/inittab should be similar to this: .PP .C "ups::respawn:rtprio 0 /usr/lbin/ups_mond -f /etc/ups_conf" .SH DIAGNOSTICS .PP Messages resulting from normal operation: .RS .PP .CI "UPS Monitor daemon starting; using configuration file <" "configfilename" ">." .PP .CI "UPS <" "tty special file name" "> OK: AC Power back on." .PP .CI "AC Power to all recognized, system critical UPS's OK! System will not shutdown." .PP .RE Messages resulting in exit of daemon: .RS .PP .CI "usage: ups_mond [-f configfile]." .PP .CI "cannot exec /usr/lbin/ups_mond -f <" "configfilename" "> -e ups_monchild due to <" "error" ">." .PP .CI "permission denied; must be superuser." .PP .CI "exiting; unable to lock process in memory: <" "errno" ">." .PP .CI "aborted, configfile <" "configfilename" "> open received error: <" "errno" ">." .PP .CI "aborted, configfile <" "configfilename" "> fseek error: <" "errno" ">." .PP .CI "aborted, malloc error: <" "errno" ">." .PP .CI "terminated by signal <" "decimal value of signal" ">." .RE .PP Messages for which .CR shutdown might be run (depends on UPS configuration): .RS .PP .CI "UPS <" "tty special file name" "> AC POWER FAILURE - running on UPS battery." .PP .CI "If power is not returned within previously configured time period, your system will automatically go to graceful shutdown." .RE .PP Messages for which .CR reboot might be run (depends on UPS configuration): .RS .PP .CI "UPS <" "tty special file name" "> battery low." .PP .CI "UPS <" "tty special file name" "> no output - either switch setting wrong on UPS or bad UPS." .PP .CI "UPS <" "tty special file name" "> failed - requires repair." .PP .CI "UPS <" "tty special file name" "> current overload; UPS turned itself off - either UPS bad or too many devices connected." .PP .CI "UPS <" "tty special file name" "> ambient temperature too high; UPS turned itself off - reduce heat in area." .PP .CI "UPS <" "tty special file name" "> output voltage too high; UPS turned itself off - requires repair." .PP .CI "UPS <" "tty special file name" "> output voltage too low; UPS turned itself off - requires repair." .PP .CI "cannot exec shutdown due to <" "errno" ">." .PP The above messages are followed by the following message: .PP .CI "reboot -halt invoked due to UPS error cited in previous syslog message." .RE .PP Messages that are only logged (no .CR shutdown / reboot action is taken): .RS .PP .CI "warning - no upstty: UPS's found in configfile <" "configfilename" ">; daemon running for no purpose." .PP .CI "warning - shutdown delay or shutdown timeout parameter in configfile <" "configfilename" "> missing or not greater than zero; using default." .PP .CI "UPS <" "tty special file name" "> in bypass-mode; no AC Power-loss protection." .PP .CI "UPS <" "tty special file name" "> interrupted, but read of ups status failed - possible UPS hardware problem." .PP .CI "upstty <" "tty special file name" "> failed open: <" "errno" ">; ignoring that tty and continuing." .PP .CI "UPS <" "tty special file name" "> ioctl(TCGETA) failed: <" "errno" ">; ignoring that UPS." .PP .CI "UPS <" "tty special file name" "> ioctl(TCSETAF) failed <" "errno" ">; ignoring that UPS." .PP .CI "UPS <" "tty special file name" "> line too noisy; ignoring that UPS." .PP .CI "UPS <" "tty special file name" "> could not enable; loss of power would not be detectable." .PP .CI "UPS <" "tty special file name" "> read failed: <" "errno" ">; Uninterruptible Power Supply has not been connected correctly; loss of power would not be detectable." .PP .CI "UPS <" "tty special file name" "> write failed: <" "errno" ">; ignoring that UPS." .PP .CI "UPS <" "tty special file name" "> read of status received ILLEGAL CMD or NOISY LINE." .PP .CI "UPS <" "tty special file name" "> read of status received <" "number" "> bytes of unexpected data" .CI "(octal: <" "octal returned" ">): <" "string returned" ">." .PP .CI "UPS <" "tty special file name" "> read of status failed: <" "errno" ">." .PP .CI "UPS <" "tty special file name" "> write failed: <" "errno" ">." .PP .CI "UPS <" "tty special file name" "> turned-off Failure Alarm." .PP .CI "UPS <" "tty special file name" "> turned-off Inverter Failure Alarm." .PP .CI "UPS <" "tty special file name" "> turned-off No Battery Alarm." .PP .CI "UPS <" "tty special file name" "> turned-off Battery Charger Fault Alarm." .PP .CI "UPS <" "tty special file name" "> turned-off Current Overload Alarm." .PP .CI "UPS <" "tty special file name" "> turned-off High Ambient Temperature Alarm." .PP .CI "UPS <" "tty special file name" "> turned-off Battery Failure Alarm." .PP .CI "UPS <" "tty special file name" "> turned-off High Battery Voltage Alarm." .PP .CI "UPS <" "tty special file name" "> turned-off Low Battery Voltage Alarm." .PP .CI "UPS <" "tty special file name" "> turned-off High Output Voltage Alarm." .PP .CI "UPS <" "tty special file name" "> turned-off Low Output Voltage Alarm." .PP .CI "UPS <" "tty special file name" "> Inverter Failure requires repair." .PP .CI "UPS <" "tty special file name" "> No Battery - ensure UPS battery installed." .PP .CI "UPS <" "tty special file name" "> Battery Charger Fault- requires repair." .PP .CI "UPS <" "tty special file name" "> Current Overload - either UPS bad or too many devices connected." .PP .CI "UPS <" "tty special file name" "> High Ambient Temperature- reduce area temperature." .PP .CI "UPS <" "tty special file name" "> Battery Failure- requires repair." .PP .CI "UPS <" "tty special file name" "> High Battery Voltage - requires repair." .PP .CI "UPS <" "tty special file name" "> Low Battery Voltage - requires repair." .PP .CI "UPS <" "tty special file name" "> UNKNOWN status/alarm <" "hex number" "> - may require repair." .PP .CI "write to UPS <" "tty special file name" "> of" .CI "command <" "cmd string" "> Failed: <" "errno" ">." .PP .CI "read from UPS <" "tty special file name" "> after sending command to it failed; <" "errno" ">." .PP .CI "UPS <" "tty special file name" "> could not execute command <" "cmd string" ">; returned" .CI "(octal: <" "octal returned" ">): <" "string returned" "> - possible bad signal cable." .RE .PP Messages relating to Timer Controlled Power On and Off: .RS .PP .CI "Timer Controlled On/Off information invalid; ignored." .PP .CI "mknod error: <" "errno" "> for Timed On/Off fifo file /var/tmp/timed_off; continuing without." .PP .CI "open error: <" "errno" "> for Timed On/Off fifo file /var/tmp/timed_off; continuing without." .PP .CI "Timer Controlled On value exceeds UPS <" "tty special file name" "> maximum. The maximum value of <" "maximum supported decimal value" "> will be used for this UPS." .RE .SH ERRORS .PP .C ups_mond returns the following error values: .PP .RS .TP 13 .C EINVAL .C ups_mond encountered an incorrect parameter. .PD 0 .TP .C EPERM Insufficient privileges. .C ups_mond must be started by a superuser. .TP .C EINTR .C ups_mond was interrupted (terminated) by .CR signal () or .CR kill (). See .CR signal (2) and .CR kill (1). .TP one (1) For all other error conditions. .PD .SH FILES .PP .PD 0 .C /dev/tty* .PP .C /etc/ups_conf .PP .C /var/tmp/timed_off .PP .C /var/adm/syslog/syslog.log .PD .SH SEE ALSO .PP kill(1) init(1M) plock(2) signal(2) syslog(3C) inittab(4) ups_conf(4) .\" .\" index@\f4ups_mond\f1 \- Uninterruptible Power System monitor daemon@@@\f3ups_mond(1M)\f1 .\" index@\f4ups_mond\f1 \- HP PowerTrust Uninterruptible Power System monitor daemon@@@\f3ups_mond(1M)\f1 .\" index@\f4ups_mond\f1 \- HP PowerTrust monitor daemon@@@\f3ups_mond(1M)\f1 .\" index@daemon, Uninterruptible Power System (UPS) monitor@@@\f3ups_mond(1M)\f1 .\" index@Uninterruptible Power System (UPS), monitor daemon@@@\f3ups_mond(1M)\f1 .\" index@UPS, monitor daemon@@@\f3ups_mond(1M)\f1 .\" .\" toc@\f3ups_mond(1M)\f1:\0\0\f4ups_mond\f1@@@Uninterruptible Power System monitor daemon .\" $Header: useradd.1m,v 78.1 96/05/09 11:06:35 ssa Exp $ .TA u .TH useradd 1M .SH NAME useradd \- add a new user login to the system .SH SYNOPSIS .C useradd .RC [ -u .I uid .RC [ -o ] .RC \|] .RC [ -g .IR group ] .RC [ -G .IR "group " [\|, .IR "group ...\&" \|] .RC \|[ -d .IR dir ] .ifn .br .RC [ -s .IR shell ] .RC [ -c .IR comment ] .ift .br .RC [ "-m " .RC \|[ -k .IR skel_dir ]\|] .RC \|[ -f .IR inactive ] .RC [ -e .IR expire ] .I " login .PP .C useradd -D .RC [ -g .IR group ] .RC [ -b .IR base_dir ] .RC [ -f .IR inactive ] .RC [ -e .IR expire ] .SH DESCRIPTION The .CR useradd command creates a user login on the system by adding the appropriate entry to the .CR /etc/passwd file and any security files, modifying the .CR /etc/group file as necessary, creating a home directory, and copying the appropriate default files into the home directory. The new login remains locked until the .CR passwd (see .IR passwd (1M)) command is invoked. .SS Options The .CR useradd command supports the following options: .RS .TP 15 .CI "-u " uid Specifies the .SM UID for the new user. .I uid must be a non-negative decimal integer less than .CR MAXUID as it is defined in the .RC < param.h > header file. .I uid defaults to the next available unique number above the maximum currently assigned number. .SM UID\c s from 0-99 are reserved. .TP .C -o Allows the .SM UID to be non-unique (i.e., a duplicate). .TP .CI "-g " group Specifies the integer group .SM ID or character string name of an existing group. This defines the primary group membership of the new login. The default for this option can be reset by invoking .CR "useradd -D -g" .IR group . .TP .CI "-G " group Specifies the integer group .SM ID or character string name of an existing group. This defines the supplemental group memberships of the new login. Multiple groups may be specified as a comma separated list. Duplicates within .I group with the .CR -g and .CR -G options are ignored. .TP .CI "-d " dir Specifies the home directory of the new login. It defaults to .IR base_dir/login , where .I login is the new login and .I base_dir is the base directory for new login home directories. .TP .CI "-s " shell Specifies the full pathname of the new login shell. The default is an empty field, which causes the system to use .CR /sbin/sh as the login shell. The value of .I shell must be a valid executable file. .TP .CI "-c " comment Specifies the comment field present in the .CR /etc/passwd entry for this login. This can be any text string. A short description of the new login is suggested for this field. .TP .C -m Creates the home directory for the new login if it does not exist. If the home directory exists, the directory must have read, write, and execute permission by .IR group , where .I group is the primary group of the new login. .TP .CI "-k " skel_dir Specifies the skeleton directory that contains information that can be copied to the new login's home directory. This directory must exist. The system provides a skeleton directory, .CR /etc/skel , that can be used for this purpose. .TP .CI "-f " inactive Specifies the maximum number of days of continuous inactivity of the login before the login is declared invalid. Normal values are positive integers, while a value of \(mi1 defeats this status. .TP .CI "-e " expire Specifies the date on which this login can no longer be used. After .IR expire , no user will be able to access this login. This option is used to create temporary logins. .IR expire , which is a date, may be typed in any format, except a Julian date. For example, a date may be entered in either of the following formats: .RS .IP .CR "July 13, 1993" .br .CR 7/13/93 .RE .IP A value of .CR "''''" defeats the expired date status. .TP .C -D Manages the defaults for various options. When .CR useradd is invoked with this option only, the default values for .IR group , .IR base_dir , .IR skel_dir , .IR shell , .IR inactive , and .I expire are displayed. Invoking .CR useradd with this option and other allowed options sets the default values for those options. .TP .CI "-b " base_dir Specifies the default base directory for the system. If .CI "-d " dir is not specified, .I base_dir is concatenated with the new login name to define the path of the new home directory. .I base_dir must exist. .RE .PP The .CR useradd command may be used with the .I login argument, where .I login is the new login name, specified as a string of printable characters. It may not contain a colon (:) or a newline (\\n). .PP Unless enhanced security is installed (see .IR pwconv (1M)), the .CR "-e " and " -f" options are not supported and will return an error. .SH NETWORKING FEATURES .SS \s-1NIS\s0 This command is aware of .SM NIS user and group entries. Only local users and groups may be modified with this command. Attempts to modify an .SM NIS user or group will result in an error. .SM NIS users and groups must be administered from the .SM NIS server. .SM NIS users are checked when verifying uniqueness of the new .SM UID or new user name, which may result in the error .IP .CI "login " x " not unique" .PP (return value 9), or the error .IP .CR "UID # is not unique (when -o is not used)" .PP (return value 4) even though the user or .SM UID is not present in the local .CR /etc/passwd file. The error .IP .CR "Cannot modify /etc/group file, /etc/passwd was modified" .PP (return value 10) is returned if a group specified with either the .CR -g option or the .CR -G option is an .SM NIS group (see .IR group (4)). .SS \s-1NFS\s0 Errors may occur with the .CR -m or .CR -k options if the indicated directory is within an .SM NFS mounted file system that does not allow root privileges across the .SM NFS mount, and the directory or files within the directory do not have sufficient permissions. .SH RETURN VALUE .CR useradd exits with one of the following values: .RS .TP 5 .C 0 Successful completion. .TP .C 2 Invalid command syntax. .TP .C 3 Invalid argument supplied to an option. .TP .C 4 .I uid is not unique (when .CR -o is not used). .TP .C 6 The .I group specified with the .CR -g option does not exist. .TP .C 9 .I login is not unique. .TP .C 10 Cannot modify the .CR /etc/group file. The login was added to the .CR /etc/passwd file, but not to the .CR /etc/group file. .TP .C 12 Unable to create the home directory (while using the .CR -m option) or unable to complete the copy of .I skel_dir to the new home directory. .TP .C 13 Unable to open .CR /etc/ptmp file or .CR /etc/default file, or .CR /etc/passwd file is non-existent. .TP .C 14 .CR /etc/passwd , or .CR /etc/ptmp , or .CR /etc/default file busy. Another command may be modifying the .CR /etc/passwd file. .TP .C 16 Cannot add the entry into the .CR /etc/passwd file. .RE .SH EXAMPLES Add the user .CR otto to the system with all of the default attributes. .IP .C useradd otto .PP Add the user .CR otto to the system with a .SM UID of .CR 222 and a primary group of .CR staff . .IP .C useradd -u 222 -g staff otto .PP List the defaults for the primary group, base directory, inactivity timeout, and skeleton directory. .IP .C useradd -D .PP Change the default primary group to .CR staff . .IP .C useradd -D -g staff .SH WARNINGS A directory can be shared between the users belonging to the same group. If the home directory is in the unshared mode and a new user is allocated to that directory then it will be put into the shared mode by setting the permissions of that directory to 775 (i.e. includes the write permissions to the group as well). Also, the directory which will be shared should have .C read and .C execute permissions for the group. Otherwise, .CR useradd will report an error. As many users may try to write the .CR /etc/passwd file simultaneously, a passwd locking mechanism was deviced. If this locking fails after subsequent retrying, .CR useradd terminates. .SH FILES .C /etc/passwd .br .C /etc/skel .br .C /etc/group .br .C /etc/ptmp .SH SEE ALSO passwd(1), users(1), groupadd(1M), groupdel(1M), groupmod(1M), logins(1M), passwd(1M), userdel(1M), usermod(1M), group(4). .SH STANDARDS COMPLIANCE .CR useradd ": SVID3" .\" toc@\f3useradd(1M)\f1:\0\0\f4useradd\f1@@@add a user login on the system\f1 .\" index@\f4useradd\f1 \- add a user login on the system@@@\f3useradd(1M)\f1 .\" index@\f1add a user login on the system@@@\f3useradd(1M)\f1 .\" index@\f1login, add a user@@@\f3useradd(1M)\f1 .\" $Header: userdel.1m,v 78.1 96/05/09 11:07:22 ssa Exp $ .TA u .TH userdel 1M .SH NAME userdel \- delete a user login from the system .SH SYNOPSIS .C userdel .RC [ -r ] .I \|login .SH DESCRIPTION The .CR userdel command deletes a user login from the system by modifying the appropriate login related files. .PP The .CR userdel command requires the .I login argument. .I login is the name to be deleted, specified as a string of printable characters. It may not contain a colon (:) or a newline (\\n). .SS Option The following option is available to this command: .RS .TP 10 .C -r The home directory of .I login is removed from the system. This directory must exist. Following the successful execution of this command, none of the files and directories under the home directory will be available. If a user is deleted and the home directory is shared by others then this directory is not deleted even with the .C -r option. .RE In the event where a directory is shared by users of the same group and the owner of that directory is deleted, then the ownership of that directory is propagated to the next user who is sharing that directory. The new owner is determined by looking at the order in which the users sharing this directory are added to the .CR /etc/passwd file. If there is only one user remaining then the directory is brought back to unshared mode by resetting the permissions .C 755 from .C 775 .SH NETWORKING FEATURES .SS \s-1NIS\s0 This command is aware of .SM NIS user and group entries. Only local users and groups may be deleted or modified with this command. Attempts to delete or modify .SM NIS users or groups will result in an error. NIS users and groups must be administered from the .SM NIS server. The .CR userdel command may fail with the error .IP .CI "login " x " does not exist" .PP (return value 6) if the user specified is an .SM NIS user (see .IR passwd (4)). The error .IP .C Cannot modify /etc/group file, /etc/passwd was modified .PP (return value 10) is returned if a local user belongs to an .SM NIS group (see .IR group (4)). .SS \s-1NFS\s0 Errors may occur with the .CR -r option if the affected directory is within an .SM NFS mounted file system that does not allow root privileges across the .SM NFS mount, and the directory or files within the directory do not have sufficient permissions. .SH RETURN VALUES .CR userdel exits with one of the following values: .RS .TP 5 .C 0 Successful completion. .TP .C 2 Invalid command syntax. .TP .C 3 Invalid argument supplied to an option. .TP .C 6 The .I login to be removed does not exist. .TP .C 8 The .I login to be removed is in use. .TP .C 10 Cannot modify the .CR /etc/group file, but the login was removed from the .CR /etc/passwd file. .TP .C 12 Unable to remove or modify the home directory. .TP .C 13 Unable to open .CR /etc/ptmp file or .CR /etc/passwd file is non-existent. .TP .C 14 .CR /etc/passwd file or .CR /etc/ptmp file busy. Another command may be modifying the .CR /etc/passwd file. .TP .C 17 Cannot delete entry from .CR /etc/passwd file. .RE .SH EXAMPLES Remove the user .CR otto from the system: .IP .C userdel otto .PP Remove the user .CR bob from the system and delete .CR bob 's home directory from the system: .IP .C userdel -r bob .SH WARNINGS As many users may try to write the .CR /etc/passwd file simultaneously, a passwd locking mechanism was deviced. If this locking fails after subsequent retrying, .CR userdel terminates. .SH FILES .C /etc/passwd .br .C /etc/group .br .C /etc/ptmp .SH SEE ALSO passwd(1), users(1), groupadd(1M), groupdel(1M), groupmod(1M), logins(1M), passwd(1M), useradd(1M), usermod(1M), group(4). .SH STANDARDS COMPLIANCE .CR userdel ": SVID3" .\" toc@\f3userdel(1M)\f1:\0\0\f4userdel\f1@@@delete a user login from the system\f1 .\" index@\f4userdel\f1 \- delete a user login from the system@@@\f3userdel(1M)\f1 .\" index@\f1delete a user login from the system@@@\f3userdel(1M)\f1 .\" index@\f1login, delete a user@@@\f3userdel(1M)\f1 .\" $Header: usermod.1m,v 78.1 96/05/09 11:08:32 ssa Exp $ .TA u .TH usermod 1M .SH NAME usermod \- modify a user login on the system .SH SYNOPSIS .C usermod .RC [ -u .I uid .RC [ -o ] .RC \|]\| .RC [ -g .IR group ]\| .RC [ -G .IR "group " \|[\|, .IR group ...]\|] .ifn .br .RC [ -d .I dir .RC [ -m ] .RC \|] .RC [ -s .IR shell ] .RC [ -c .IR comment ] \| .ift .br .RC [ -f .IR inactive ] .RC [ -l .IR new_logname ] .RC [ -e .IR expire ] .I " login" .SH DESCRIPTION The .CR usermod command modifies a user login on the system by changing the appropriate login related files. .PP The .CR usermod command requires the .I login argument. .I login is a new login name, specified as a string of printable characters. It may not contain a colon (:) or a newline (\\n). .SS Options The .CR usermod command supports the following options: .RS .TP 20 .CI "-u " uid Specifies the .SM UID for the new user. .I uid must be a non-negative decimal integer less than .CR MAXUID as it is defined in the .RC < param.h > header file. .TP .C -o Allows the .SM UID to be non-unique (i.e., a duplicate). .TP .CI "-g " group Specifies the integer group .SM ID or character string name of an existing group. This redefines the primary group membership of the new login. .TP .CI "-G " group Specifies the integer group .SM ID or character string name of an existing group. This redefines the supplemental group memberships of the new login. Duplicates within .I group with the .CR -g and .CR -G options are ignored. .TP .CI "-d " dir Specifies the new home directory of the login. It defaults to .IR base_dir/login , where .I login is the new login and .I base_dir is the base directory for new login home directories. .TP .C -m Move the user's home directory to the directory specified with the .CR -d option. If the home directory exists, the directory must have read, write, and execute permission by .IR group , where .I group is the primary group of the login. .TP .CI "-s " shell Specifies the full pathname of the login shell. The value of .I shell must be a valid executable file. .TP .CI "-c " comment Specifies the comment field present in the .CR /etc/passwd entry of this login. This can be any text string. A short description of the new login is suggested for this field. .TP .CI "-f " inactive Specifies the maximum number of days of continuous inactivity of the login before the login is declared invalid. Normal values are positive integers, while a value of \(mi1 defeats this status. .TP .CI "-l " new_logname Specifies the new login name for the user. It consists of a string of printable characters that does not contain a colon (:) or a newline (\\n). .TP .CI "-e " expire Specifies the date on which this login can no longer be used. After .IR expire , no user will be able to access this login. This option is used to create temporary logins. .IR expire , which is a date, may be typed in any desired format, except a Julian date. For example, a date may be entered as either of the following: .RS .IP .CR "July 13, 1993" .IP .CR "7/13/93" .RE .IP A value of .CR "''''" defeats the expired date status. .RE .PP Unless enhanced security is installed (see .IR pwconv (1M)), the .CR -e " and " -f" . options are not supported and will return an error. A directory can be shared between the users belonging to the same group. If the home directory is in the unshared mode and a new user is allocated to that directory then it will be put into the shared mode by setting the permissions of that directory to .C 775 (i.e. includes the write permissions to the group as well). Also, the directory which will be shared should have read and execute permissions for the group. In the event where a directory is shared by users of the same group and the owner of that directory is modified, then the ownership of that directory is propagated to the next user who is sharing that directory. The new owner is determined by looking at the order in which the users sharing this directory are added to the .CR /etc/passwd file. If there is only one user remaining then the directory is brought back to unshared mode by setting the permissions back to .C 755 from .C 775 If a directory is shared by users then one cannot change the primary group of any of these users unless the home directory of that user is also changed. .SH NETWORKING FEATURES .SS \s-1NIS\s0 The .CR usermod command is aware of .SM NIS user and group entries. Only local users and groups may be modified with this command. Attempts to modify an .SM NIS user or group will result in an error. .SM NIS users and groups must be administered from the .SM NIS server. This command may fail with the error .IP .CI "login " x " does not exist" .PP (return value 6) if the user specified is an .SM NIS user (see .IR passwd (4)). However, .SM NIS users are checked when verifying uniqueness of the new .SM UID or the new user name. Also, the error .IP .C "Cannot modify /etc/group file, /etc/passwd was modified" .PP (return value 10) may be returned if a group specified with either the .CR -g option or the .CR -G option is an .SM NIS group (see .IR group (4)). .SS \s-1NFS\s0 Errors may occur with the .CR -m option if either the source or the target directory is within an .SM NFS mounted file system that does not allow root privileges across the .SM NFS mount and the directory or files within the directory do not have sufficient permissions. .SH RETURN VALUE .CR usermod exits with one of the following values: .RS .TP 5 .C 0 Successful completion. .TP .C 2 Invalid command syntax. .TP .C 3 Invalid argument supplied to an option. .TP .C 4 .I uid is not unique (when .CR -o is not used). .TP .C 6 The .I login to be modified or the .I group specified with the .CR -g option does not exist. .TP .C 8 The .I login to be modified is in use. .TP .C 9 .I new_logname is not unique. .TP .C 10 Cannot modify the .CR /etc/group file. The other parts of the update request will be performed. .TP .C 11 There is insufficient space to move the home directory (with the .CR -m option). The other parts of the update request will be performed. .TP .C 12 Unable to complete the move of the home directory to the new home directory. .TP .C 13 Unable to open .CR /etc/ptmp file, or .CR /etc/passwd file is non-existent. .TP .C 14 .CR /etc/passwd file or .CR /etc/ptmp file busy. Another command may be modifying the .CR /etc/passwd file. .TP .C 15 Cannot modify the entry in the .CR /etc/passwd file. .RE .SH EXAMPLES Change .CR otto 's primary group to .CR staff . .IP .C usermod -g staff otto .PP Change .CR otto 's user .SM ID to .CR 333 and change the login name to .CR bob . .IP .C usermod -u 333 -l bob otto .SH WARNINGS As many users may try to write the .CR /etc/passwd file simultaneously, a passwd locking mechanism was deviced. If this locking fails after subsequent retrying, .CR usermod terminates. .SH FILES .C /etc/passwd .br .C /etc/group .br .C /etc/ptmp .SH SEE ALSO passwd(1), users(1), groupadd(1M), groupdel(1M), groupmod(1M), logins(1M), passwd(1M), useradd(1M), userdel(1M), group(4). .SH STANDARDS COMPLIANCE .CR usermod ": SVID3" .\" toc@\f3usermod(1M)\f1:\0\0\f4usermod\f1@@@modify a user login on the system\f1 .\" index@\f4usermod\f1 \- modify a user login on the system@@@\f3usermod(1M)\f1 .\" index@\f1modify a user login on the system@@@\f3usermod(1M)\f1 .\" index@\f1login, modify a user@@@\f3usermod(1M)\f1 .\" $Header: acct.1m,v 72.5 94/11/14 12:00:17 ssa Exp $ .TA a .TH acct 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acctdisk, acctdusg, accton, acctwtmp, closewtmp, utmp2wtmp \- overview of accounting and miscellaneous accounting commands .SH SYNOPSIS .C /usr/sbin/acct/acctdisk .PP .C /usr/sbin/acct/acctdusg .RC [ -u .IR file\| ] .RC [ -p .IR file\| ] .PP .C /usr/sbin/acct/accton .RI [ \|file\| ] .PP .C /usr/sbin/acct/acctwtmp .I reason .PP .C /usr/sbin/acct/closewtmp .PP .C /usr/sbin/acct/utmp2wtmp .SH DESCRIPTION Accounting software is structured as a set of tools (consisting of both C programs and shell procedures) that can be used to build accounting systems. The shell procedures, described in .IR acctsh (1M), are built on top of the C programs. .PP Connect time accounting is handled by various programs that write records into .CR /etc/utmp , as described in .IR utmp (4). The programs described in .IR acctcon (1M) convert this file into session and charging records which are then summarized by .C acctmerg (see .IR acctmerg (1M)). .PP Process accounting is performed by the .SM HP-UX system kernel. Upon termination of a process, one record per process is written to a file (normally .CR /var/adm/pacct ). The programs in .IR acctprc (1M) summarize this data for charging purposes; .C acctcms is used to summarize command usage (see .IR acctcms (1M)). Current process data can be examined using .C acctcom (see .IR acctcom (1M)). .PP Process accounting and connect time accounting (or any accounting records in the format described in .IR acct (4)) can be merged and summarized into total accounting records by .C acctmerg (see .C tacct format in .IR acct (4)). .C prtacct is used to format any or all accounting records (see .IR acctsh (1M)). .PP .C acctdisk reads lines that contain user .SM ID, login name, and number of disk blocks, and converts them to total accounting records that can be merged with other accounting records. .PP .C acctdusg reads its standard input (usually from .CR "find -print" ) and computes disk resource consumption (including indirect blocks) by login. Only files found under login directories (as determined from the password file) are accounted for. All files under a login directory are assumed to belong to that user regardless of actual owner. If .C -u is given, records consisting of those file names for which .C acctdusg charges no one are placed in .I file (a potential source for finding users trying to avoid disk charges). If .C -p is given, .I file is the name of the password file. This option is not needed if the password file is .CR /etc/passwd . (See .IR diskusg (1M) for more details.) .PP .C accton turns process accounting off if the optional .I file argument is omitted. If .I file is given, it must be the name of an existing file, to which the kernel appends process accounting records (see .IR acct (2) and .IR acct (4)). .PP .C acctwtmp writes a .IR utmp (4) record to its standard output. The record contains the current time and a string of characters that describe the .I reason for writing the record. A record type of .SM ACCOUNTING is assigned (see .IR utmp (4)). The string argument .I reason must be 11 or fewer characters, numbers, .CR $ , or spaces. For example, the following are suggestions for use in reboot and shutdown procedures, respectively: .IP .C "acctwtmp `uname` >> /var/adm/wtmp" .IP .C "acctwtmp ""file save"" >> /var/adm/wtmp .PP .C closewtmp writes a .SM DEAD_PROCESS record, for each user currently logged in, to the file .CR /var/adm/wtmp . This program is invoked by .I runacct to close the existing .C wtmp file before creating a new one. .PP .C utmp2wtmp writes a .SM USER_PROCESS record, for each user currently logged in, to the file .CR /var/adm/wtmp . This program is invoked by .I runacct to initialize the newly created .C wtmp file. .SH FILES .TP 30 .C /usr/sbin/acct Holds all accounting commands listed in section (1M) of this manual. .TP .C /var/adm/pacct Current process accounting file. .TP .C /etc/passwd Used for converting login name to user. .SM ID .TP .C /var/adm/wtmp Login/logoff history file. .SH SEE ALSO acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), acctsh(1M), diskusg(1M), fwtmp(1M), runacct(1M), acct(2), acct(4), utmp(4). .PP System Accounting topics in .I HP-UX System Administrator manuals. .SH STANDARDS CONFORMANCE .CR acctdisk ": SVID2, SVID3" .PP .CR accton ": SVID2, SVID3" .PP .CR acctwtmp ": SVID2, SVID3" .\" .\" index@accounting: \f4acctdisk\f1 \- create disk usage accounting records@@@\f3acct(1M)\f1 .\" index@accounting: \f4acctdusg\f1 \- compute disk usage by login name@@@\f3acct(1M)\f1 .\" index@accounting: \f4accton\f1 \- define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@accounting: \f4acctwtmp\f1 \- write \f4utmp\f1 record and reason for writing@@@\f3acct(1M)\f1 .\" index@\f4acctdisk\f1 \- create disk usage accounting records@@@\f3acct(1M)\f1 .\" index@\f4acctdusg\f1 \- compute disk usage by login name@@@\f3acct(1M)\f1 .\" index@\f4accton\f1 \- define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@\f4acctwtmp\f1 \- write \f4utmp\f1 record and reason for writing@@@\f3acct(1M)\f1 .\" index@disk usage accounting records, create@@@\f3acct(1M)\f1 .\" index@disk usage by login name, compute@@@\f3acct(1M)\f1 .\" index@define kernel process accounting output file or disable accounting@@@\f3acct(1M)\f1 .\" index@disable accounting or define kernel process accounting output file@@@\f3acct(1M)\f1 .\" index@\f4utmp\f1 record, write and include reason for writing@@@\f3acct(1M)\f1 .\" .\" toc@\f3acct(1M)\f1:\0\0\f4acctdisk\f1, \f4acctdusg\f1, \f4accton\f1,\n\f4acctwtmp\f1@@@overview of accounting and miscellaneous accounting commands .\" toc@\f4acctdisk\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4acctdusg\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4accton\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" toc@\f4acctwtmp\f1:\0\0miscellaneous accounting command@@@see \f3acct(1M)\f1 .\" .\" links@acct.1m acctdisk.1m .\" links@acct.1m acctdusg.1m .\" links@acct.1m accton.1m .\" links@acct.1m acctwtmp.1m .\" links@acct.1m closewtmp.1m .\" links@acct.1m utmp2wtmp.1m .\" .\" fileset_database@acct.1m SYS-ADMIN-MAN .\" $Header: uucheck.1m,v 72.4 94/07/25 17:00:06 ssa Exp $ .TA u .TH uucheck 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uucheck \- check the uucp directories and permissions file .SH SYNOPSIS .C /usr/lbin/uucp/uucheck .RC [ -v ] .RC [ -x .IR debug_level\| ] .SH DESCRIPTION .C uucheck checks for the presence of the files and directories required by .C uucp (see .IR uucp (1)). .C uucheck is executed from the .SM UUCP makefile before the installation occurs. .C uucheck also checks for various obvious errors in the .C /etc/uucp/Permissions file. .SS Options .C uucheck recognizes the following options and command-line arguments: .RS .TP 15 .C -v (verbose) Print a detailed explanation of how .C uucp programs will interpret the .C Permissions file. .TP .CI -x \0debug_level Debug. .I debug_level is a single digit; the higher the number, the more detail returned. .RE .PP Note that .C uucheck can only be used by the super-user or .CR uucp . .SH FILES .nf .C /etc/uucp/Systems .C /etc/uucp/Permissions .C /etc/uucp/Devices .C /etc/uucp/Maxuuxqts .C /etc/uucp/Maxuuscheds .C /var/spool/uucp/* .C /var/spool/locks/LCK* .C /var/spool/uucppublic/* .fi .SH SEE ALSO uucp(1), uustat(1), uux(1), uucico(1M), uusched(1M). .PP .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .\" .\" index@\f4uucheck\f1 \- check the \f4uucp\f1 directories and permissions file@@@\f3uucheck(1M)\f1 .\" index@check the \f4uucp\f1 directories and permissions file@@@\f3uucheck(1M)\f1 .\" index@permissions file, check the \f4uucp\f1 directories and@@@\f3uucheck(1M)\f1 .\" index@uucp: check the \f4uucp\f1 directories and permissions file@@@\f3uucheck(1M)\f1 .\" .\" toc@\f3uucheck(1M)\f1:\0\0\f4uucheck\f1@@@check the uucp directories and permissions file .\" .\" fileset_database@uucheck.1m SYS-ADMIN-MAN .\" $Header: uucico.1m,v 72.4 94/07/25 16:56:08 ssa Exp $ .TA u .TH uucico 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uucico \- transfer files for the uucp system .SH SYNOPSIS .C /usr/lbin/uucp/uucico -r1 -s .I system .RC [ -x .IR debug_level\| ] .RC [ -d .IR spool_directory\| ] .PP .C /usr/lbin/uucp/uucico .RC [ -x .IR debug_level\| ] .RC [ -d .IR spool_directory\| ] .SH DESCRIPTION .C uucico scans the .C /var/spool/uucp directories for work files. If such files exist, a connection to a remote system is attempted using the line protocol for the remote system specified in file .CR /etc/uucp/Systems . .C uucico then executes all requests for work and logs the results. .SS Options .C uucico recognizes the following options: .RS .TP 15 .C -r1 Start .C uucico in the .SM MASTER mode. The default is .SM SLAVE mode. .TP .CI -s " system" Do work only for the system specified by .IR system . If there is no work for .I system on the local spool directory, initiate a connection to .I system to determine if .I system has work for the local system. This option must be used if .C -r1 is specified. .TP .CI -d " spool_directory" Search directory .I spool_directory instead of the default spool directories (usually .CR /var/spool/uucp/* ). .TP .CI -x " debug_level" Use debugging option. .I debug_level is an integer in the range 1 through 9. More debugging information is given for larger values of .IR debug_level . .PP .C uucico is usually started by a local program such as .CR cron , .CR uucp , or .C uuxqt (see .IR cron (1M), .IR uucp (1), and .IR uuxqt (1M)). It when debugging should a user initiate .C uucico directly. .PP When started by a local program, .C uucico is considered the .SM MASTER and attempts a connection to a remote system. If .C uucico is started by a remote system, it is considered to be in .SM SLAVE mode. .PP For the .C uucico connection to a remote system to be successful, there must be an entry in the .C /etc/passwd file on the remote system of the form: .IP .C "uucp::5:5::/var/spool/uucppublic:/usr/lbin/uucp/uucico" .PP .SH FILES .nf .C /etc/uucp/Systems .C /etc/uucp/Permissions .C /etc/uucp/Devices .C /etc/uucp/Maxuuxqts .C /etc/uucp/Maxuuscheds .C /var/spool/uucp/* .C /var/spool/locks/LCK* .C /var/spool/uucppublic/* .fi .SH SEE ALSO uucp(1), uustat(1), uux(1), cron(1M), uusched(1M), uutry(1M). .PP .SM .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .\" .\" index@\f2uucico\f1 \- transfer \f2uucp\f1-system files@@@\f3uucico(1M)\f1 .\" index@transfer \f2uucp\f1-system files in or out@@@\f3uucico(1M)\f1 .\" index@files: transfer \f2uucp\f1-system files in or out@@@\f3uucico(1M)\f1 .\" index@\f2uucp\f1-system files, transfer in or out@@@\f3uucico(1M)\f1 .\" index@copy in, copy out \- transfer \f2uucp\f1-system files in or out@@@\f3uucico(1M)\f1 .\" .\" toc@\f3uucico(1M)\f1:\0\0\f2uucico\f1@@@transfer files for the uucp system .\" .\" fileset_database@uucico.1m SYS-ADMIN-MAN .\" $Header: uuclean.1m,v 72.4 94/07/25 16:49:17 ssa Exp $ .TA u .TH uuclean 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uuclean \- uucp spool directory clean-up .SH SYNOPSIS .C /usr/lbin/uucp/uuclean .RI [ \|options\| ] .SH DESCRIPTION .C uuclean scans the spool directories for files with the specified prefix and deletes all those that are older than the specified number of hours. .SS Options .C uuclean recognizes the following options: .RS .TP 15 .CI -d directory Clean .I directory instead of the spool directory. If .I directory is not a valid spool directory, it cannot contain ``work files''; i.e., files whose names start with .CR C. . These files have special meaning to .C uuclean pertaining to .C uucp job statistics. .TP .CI -p pre Scan for files with .I pre as the file prefix. Up to 10 .C -p arguments can be specified. A .C -p without any .I pre following will cause all files older than the specified time to be deleted. .TP .CI -n time Files whose age is more than .I time hours are deleted if the prefix test is satisfied (default time is 72 hours). .TP .CI -w file The default action for .C uuclean is to remove files that are older than a specified time (see .C -n option). The .C -w option is used to find files older than .I time hours; however, the files are not deleted. If the argument .I file is present the warning is placed in .IR file ; otherwise, the warnings go to the standard output. .TP .CI -s sys Only files destined for system .I sys are examined. Up to 10 .C -s arguments can be specified. .TP .CI -m file The .C -m option sends mail to the owner of the file when it is deleted. If a .I file is specified, an entry is placed in .IR file . .RE .PP This program is typically started by .C cron (see .IR cron (1M)). .SH FILES .PD 0 .TP 25 .C /var/spool/uucp/* spool directory .PD .SH SEE ALSO uucp(1), uux(1), cron(1M), uucleanup(1M). .PP .SM .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .\" .\" index@\f4uuclean\f1 \- \f4uucp\f1 spool directory clean-up@@@\f3uuclean(1M)\f1 .\" index@uucp: \f4uucleanup\f1 \- \f4uucp\f1 spool directory clean-up@@@\f3uuclean(1M)\f1 .\" index@\f4uucp\f1 spool directory clean-up@@@\f3uuclean(1M)\f1 .\" index@spool directory clean-up, \f4uucp\f1@@@\f3uuclean(1M)\f1 .\" .\" toc@\f3uuclean(1M)\f1:\0\0\f4uuclean\f1@@@uucp spool directory clean-up .\" .\" fileset_database@uuclean.1m SYS-ADMIN-MAN .\" $Header: uucleanup.1m,v 72.4 94/07/25 16:47:43 ssa Exp $ .TA u .TH uucleanup 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uucleanup \- uucp spool directory clean-up .SH SYNOPSIS .C /usr/lbin/uucp/uucleanup .RC [ -C .IR time\| ] .RC [ -D .IR time\| ] .RC [ -W .IR time\| ] .RC [ -X .IR time\| ] .RC [ -m .IR string\| ] .RC [ -o .IR time\| ] .RC [ -s .IR system\| ] .RC [ -x .IR debug_level\| ] .SH DESCRIPTION .C uucleanup scans the spool directories for old files and takes appropriate action to remove them. Depending on the options selected, .C uucleanup performs the following: .RS .TP 3 \(bu Informs the requestor of send and/or receive requests for systems that cannot be reached. .TP \(bu Returns mail that cannot be delivered to the sender. .TP \(bu Removes all other files. .RE .PP In addition, .C uucleanup warns users of requestors who have been waiting for a given number of days (the default is 1 day). Note that unless .I time is specifically set, the default .I time values for the following options are used. .SS Options .C uucleanup recognizes the following options: .RS .TP 15 .CI -C time Any .C C. files greater or equal to .I time days old are removed with appropriate information to the requestor. The default .I time is 7 days. .TP .CI -D time Any .C D. files greater or equal to .I time days old are removed. An attempt is made to deliver mail messages and execute news when appropriate. The default .I time is 7 days. .TP .CI -W time Any .C C. files equal to .I time cause a message to be mailed to the requestor warning about the delay in contacting the remote. The message includes the .SM .IR JOBID , and in the case of mail, the mail message. The administrator can include a message line telling who to call to correct the problem (see the .C -m option). The default .I time is 1 day. .TP .CI -X time Any .C X. files greater than or equal to .I time days old are removed. The .C D. files are probably not present (if they were, the .C X. could be executed). But, if .C D. files are present, they are taken care of by .C D. processing. The default .I time is 2 days. .TP .CI -m string This string is included in the warning message generated by the .C -W option. The default string is .C "See your local administrator to locate the problem." .TP .CI -o time Other files whose age is more than .I time days are deleted. The default time is 2 days. .TP .CI -s system Clean-up the spool directory for .I system only. The default is to clean-up all spool directories. .TP .CI -x debug_level The debug level is a single digit between 0 and 9. The higher the numbers, the more detailed the debugging information returned. .RE .PP This program is typically started by the script .CR uudemon.cleanu , which should be started by .C cron (see .IR cron (1M)). .SH FILES .TP 25 .PD 0 .C /var/spool/uucp/* spool directory .PD .SH SEE ALSO cron(1M), uucp(1), uux(1), uuclean(1M). .PP .SM .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .\" .\" index@\f4uucleanup\f1 \- \f4uucp\f1 spool directory clean-up@@@\f3uucleanup(1M)\f1 .\" index@\f4uucp\f1 spool directory clean-up@@@\f3uucleanup(1M)\f1 .\" index@spool directory clean-up, \f4uucp\f1@@@\f3uucleanup(1M)\f1 .\" index@directory clean-up, \f4uucp\f1 spool@@@\f3uucleanup(1M)\f1 .\" index@clean-up, \f4uucp\f1 spool directory@@@\f3uucleanup(1M)\f1 .\" .\" toc@\f3uucleanup(1M)\f1:/0/0\f4uucleanup\f1@@@\f4uucp\f1 spool directory clean-up .\" .\" fileset_database@uucleanup.1m SYS-ADMIN-MAN .\" $Header: uucpd.1m,v 72.3 94/12/08 12:11:57 ssa Exp $ .TA u .TH uucpd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME /usr/sbin/uucpd \- UUCP over TCP/IP server daemon .SH DESCRIPTION .B uucpd is the server for supporting UUCP connections over TCP/IP networks. .B uucpd is invoked by .IR "inetd" (1M) when a UUCP connection is established (that is, a connection to the port indicated in the "uucp" service specification; see .IR "services" (4)), and executes the following protocol: .nf 1) The server prompts with "login:", the uucico process at the other end must supply a username. 2) Unless the username refers to an account without a password, the server then prompts with "Password:", the uucico process at the other end must supply the password for that account. .fi If the username is not valid or is valid but refers to an account that does not have .B /usr/lbin/uucp/uucico as its login shell, or if the password is not the correct password for that account, the connection is dropped. Otherwise, .IR "uucico" (1M) is run. Entries are made in .B /var/adm/wtmp traceable with .IR "who" (1) and .IR "last" (1M). .SH PROTOCOL RESTRICTION Only 'g' protocol for uucico is supported. .SH DIAGNOSTICS All diagnostic messages are returned on the connection, after which the connection is closed. .B user read .nf An error occurred while reading the username. .fi .B passwd read .nf An error occurred while reading the password. .fi .B login incorrect .nf The username or the password is invalid or the user's login shell for this account is not /usr/lbin/uucp/uucico. .fi .SH WARNINGS On Trusted Systems uucpd prohibits uucico to start if any of the following are true : .PP .in +0.5i .ll -0.5i .ta +0.2i .ti -0.2i \(bu the login account is locked (several causes). .ti -0.2i \(bu current time doesn't match existing time-of-day restrictions for this account. .ll +0.5i .in -0.5i .PP Under such conditions uucpd will return the message .B login incorrect to the connection. The connection is then dropped. .SH AUTHOR .B uucpd was developed by the University of California, Berkeley and HP. .SH FILES .TP 25 .C /etc/inetd.conf configuration file for inetd .PD 0 .TP .C /var/adm/inetd.sec optional security file for inetd .TP .C /etc/services service name data base .TP .C /var/adm/wtmp login data base .PD .SH SEE ALSO inetd(1M), services(4), uucico(1M). .\"toc@\f3uucpd(1M)\f1:\0\0\f4uucpd()\f1@@@server for supporting UUCP over TCP/IP networks .\"toc@\f4uucpd()\f1: server for supporting UUCP over TCP/IP networks@@@see \f3uucpd(1M)\f1 .\"index@\f4uucpd()\fP \- server for supporting UUCP over TCP/IP networks@@@\f3uucpd(1M)\f1 .\" $Header: uugetty.1m,v 72.4 94/07/25 16:20:22 ssa Exp $ .TA u .TH uugetty 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uugetty \- set terminal type, modes, speed and line discipline .SH SYNOPSIS .C /usr/lbin/uucp/uugetty .RC [ -h ] .RC [ -t .IR timeout\| ] .RC [ -r ] .I line .RI [ \|speed .RI [ \|type .RI [ \|linedisc\| ]\|]\|] .br .C /usr/lbin/uucp/uugetty -c .I file .SH DESCRIPTION .C uugetty sets terminal type, modes, speed and line discipline. It is similar to .CR getty , except that .C uugetty supports using the line in both directions (see .IR getty (1M)). This allows users to log in, but, if the line is free, .CR uucico , .CR cu , and .C ct can dial out (see .IR uucico (1), .IR cu (1), and .IR ct (1)). When devices are used with .CR uucico , .CR cu , and .CR ct , lock files are created. Therefore, when the call to .C open() returns (see .IR open (2)) (or the first character is read when the .C -r option is used), the status of the lock files indicates whether the line is used by .CR uucico , .CR cu , .CR ct , or someone trying to log in. See .IR getty (1M) for more information. .PP Note that with the .C -r option, several carriage-return characters might be required before the login message is output. When .C uucico is trying to log in, it can be instructed to enter numerous carriage-return characters with the following login script: .IP .CR "\er\ed\er\ed\er\ed\er in:-in: " ... .PP where ... represents whatever would normally be used for the login sequence. .PP An entry for an intelligent modem or direct line that has a .C uugetty on each end must use the .C -r option (this causes .I uugetty to wait to read a character before it enters the login message, thus preventing two instances of .C uugetty from looping). If there is a .C uugetty on one end of a direct line, there must be a .C uugetty on the other end as well. .SH EXAMPLES The following line is an .C /etc/inittab entry using .C uugetty on an intelligent modem or direct line: .IP .C "30:2:respawn:/usr/lbin/uucp/uugetty -r -t 60 tty12 1200" .SH WARNINGS .C ct does not work when .C uugetty is used with an intelligent modem such as a Penril or a Ventel. .SH FILES .nf .C /etc/gettydefs .C /etc/issue .C /var/spool/locks/LCK* .fi .SH SEE ALSO ct(1), cu(1), login(1), uucico(1M), getty(1M), init(1M), ioctl(2), gettydefs(4), inittab(4), tty(7). .PP .SM .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .\" .\" index@\f4uugetty\f1 \- set terminal type, modes, speed and line discipline for 2-way line@@@\f3uugetty(1M)\f1 .\" index@set terminal type, modes, speed and line discipline for 2-way line@@@\f3uugetty(1M)\f1 .\" index@uucp: set terminal type, modes, speed and line discipline for 2-way line@@@\f3uugetty(1M)\f1 .\" index@terminal type, modes, speed and line discipline, set for 2-way line@@@\f3uugetty(1M)\f1 .\" index@terminal connection, set terminal type, modes, speed and line discipline for 2-way line@@@\f3uugetty(1M)\f1 .\" index@\f4getty\f1 for 2-way line accessible to \f4uucp\f1@@@\f3uugetty(1M)\f1 .\" .\" toc@\f3uugetty(1M)\f1:\0\0\f4uugetty\f1@@@set terminal type, modes, speed and line discipline .\" .\" fileset_database@uugetty.1m SYS-ADMIN-MAN .\" $Header: uuid_gen.1m,v 72.4 94/10/27 14:47:03 ssa Exp $ .TA u .TH uuid_gen 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uuid_gen \- \s-1UUID\s0 generating program .SH SYNOPSIS .C /usr/sbin/ncs/uuid_gen .RC [ -c ] .RC [ -p ] .RC [ -C ] .RC [ -P ] .RC [ -t ] .RC [ - .IR version\| ] .SH DESCRIPTION .I uuid_gen generates Universal Unique Identifiers .SM (UUIDs). .PP Without options, .C uuid_gen generates the character-string representation of a .SM UUID. The .C -c and .C -p options are used when generating templates for Network Interface Definition Language .SM (NIDL) files. The .C -C and .C -P options generate source-code representations of .SM UUID\c s, suitable for initializing variables of type .CR uuid_$t . .PP Multiple options can be used in the same command line to generate several representations for the same .SM UUID. To generate the default character-string representation as well as one of the optional representations, use the .C -t option. .PP .C uuid_gen creates .SM NCS UUIDs . To create a .SM DCE UUID , use the .C uuidgen executable. .SS Options .C uuid_gen recognizes the following options: .RS .TP 10 .C -C Generate the C source-code representation of a .SM UUID. .TP .C -c Generate a template, including a .SM UUID attribute, for an interface definition in the C syntax of .SM NIDL. .TP .C -Pf1 Generate the Pascal source-code representation of a .SM UUID. .TP .C -pf1 Generate a template, including a .SM UUID attribute, for an interface definition in the Pascal syntax of .SM NIDL. .TP .C -t Generate the character-string representation of a .SM UUID. This option allows you to request the default output of .C uuid_gen while also requesting optional output forms. .TP .C -version Display the version of .SM NCK that this .C uuid_gen belongs to, but do not generate a .SM UUID. .RE .SH EXAMPLES Generate the character-string representation of a .SM UUID: .IP .C /usr/sbin/ncs/uuid_gen .br .C 34dc23469000.0d.00.00.7c.5f.00.00.00 .PP Generate a template for an interface definition in the C syntax of .SM NIDL: .nf .IP .RC $ \0/usr/sbin/ncs/uuid_gen\0-c .C %c .C [ .C uuid(34dc239ec000.0d.00.00.7c.5f.00.00.00), .C version(1) .C ] .C interface INTERFACENAME { .IP .C } .fi .PP Generate the C source-code representation of a .SM UUID: .nf .IP .RC $ \0/usr/sbin/ncs/uuid_gen\0\-C .C = { 0x34dc23af, .C " 0xf000," .C " 0x0000," .C " 0x0d," .C " {0x00, 0x00, 0x7c, 0x5f, 0x00, 0x00, 0x00} };" .fi .PP Generate both the character-string representation and the C source-code representation of a .SM UUID: .nf .IP .RC $ \0/usr/sbin/ncs/uuid_gen\0\-t\0\-C .C 450ccaed6000.0d.00.02.18.cb.00.00.00 .C = { 0x450ccaed, .C " 0x6000, .C " 0x0000, .C " 0x0d, .C " {0x00, 0x02, 0x18, 0xcb, 0x00, 0x00, 0x00} }; .fi .SH SEE ALSO uuidgen(1M) .PP .I Managing NCS Software .PP .I "NCS 1.5.1 to DCE RPC Transition Guide" .\" .\" index@\f4uuid_gen\f1 \- \s-1UUID\s0 generating program@@@\f3uuid_gen(1M)\f1 .\" index@Universal-Unique-Identifier generating program@@@\f3uuid_gen(1M)\f1 .\" index@\s-1UUID\s0 generating program@@@\f3uuid_gen(1M)\f1 .\" index@program, \s-1UUID\s0 generating@@@\f3uuid_gen(1M)\f1 .\" .\" toc@\f3uuid_gen(1M)\f1:\0\0\f4uuid_gen\f1@@@\s-1UUID\s0 generating program .\" .\" fileset_database@uuid_gen.1m SYS-ADMIN-MAN .\" $Header: uuls.1m,v 72.2 94/07/25 16:00:41 ssa Exp $ .TA u .TH uuls 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uuls \- list spooled uucp transactions grouped by transaction .SH SYNOPSIS .B uuls .RB [ \|\-m\| ] .RI [ \|directories\| ...] .br .B uuls .RB [ \|\-s\| ] .RB [ \|\-m\| ] .RI [ \|directories\| ...] .br .B uuls .RB [ \|\-k\| ] .RB [ \|\-m\| ] .RI [ \|directories\| ...] .SH DESCRIPTION This command lists the contents of .SM UUCP spool directories (default .BR /var/spool/uucp/* ) with the files in each directory grouped into three categories: .IP \(bu\0Transactions, .br \(bu\0Orphans, and .br \(bu\0Others. .SS Transactions Each output line starts with a transaction control filename, and includes the name of each local (same-directory) subfile referenced by the control file (see below). Each is possibly followed by the total size in bytes .RB ( \-s option) or Kbytes .RB ( \-k option) in the transaction (see below). The .B \-m (meanings) option replaces the subfile names with nodename, user, and .I commandline information (see below). .SS Orphans All subfiles not referenced by any control file. .SS Others All other files in the directory (all files not listed under one of the above categories). .PP Filenames are formatted into columns, so there can be more than one file per line. If a transaction has more subfiles than fit on one line, it is followed by continuation lines which are indented further. .PP The .B \-s (size in bytes) and .B \-k (Kbytes) options cause the command to follow each transaction in the .B Transactions section with a total size for all stat-able, sendable files in that transaction. This includes .B D.\(** files only, not .B C.\(** or .B X.\(** files. It does include stat-able files outside the spool directory that are indirectly referenced by .B C.\(** files. Sizes are either in bytes or rounded to the nearest Kbyte (1024 bytes), respectively. A totals line is also added at the end of the .B Transactions section. .PP The .B \-m (meanings) option causes the command to follow .B C.\(** and .B X.\(** files with a .IB nodename ! username .I commandline line, instead of subfilenames. For .B C files, one line is printed per remote execution .RB ( D\(**X\(** ) subfile it references. .I nodename is truncated at seven characters, .I username at eight, and .I commandline at however much fits on one line. .PP If .B \-m is given, for each .B C file with no remote execution files, the command instead shows the meaning of the .B C file itself on one or more lines. Each line consists of a username, then .B R (receive) or .B S (send), then the name of the file to be transferred. See below for details. .PP Filenames are listed in ascending collation order within each section (see Environment Variables below), except that the first section is only sorted by the control filename. Every file in the directory except .B . and .B .\|. appears exactly once in the entire list, unless .B \-m is used. .SS Details Transaction files are those whose names start with .B C. or .BR X. . Subfilenames, which usually start with .BR D. , are gleaned from control file lines, at most one per line, from blank-separated fields, as follows: .RS .PP .nf C.\(**: R - C.\(**: S - X.\(**: F .fi .RE .PP Lines that do not begin with the appropriate character .RB ( R , .BR S , or .BR F ) are ignored. .PP In the .B R (receive) case, is used to print the .BR C -file meaning, and its transaction size is taken as zero (unknown). .PP In the .B S (send) case, if is .BR D.0 , is a file not in the spool directory, resulting from a typical .B uucp call without the .B \-C (copy) option. In this case is used for the transaction size, if stat-able, and to print the .BR C -file meaning. .PP .B uucp \-C and .B uux both set to a true (spooled) subfile name. .PP Orphan files are those whose names start with .B D. and which are not referenced by any control files. .PP This algorithm extracts from control files the names of all subfiles that should exist in the spool directory when the transaction is not being actively processed. It is not unusual to see "missing subfiles" and "orphans" if you .B uuls a spool directory while .BR uucico , .BR uucp , .BR uux , or .B uuxqt is active. .PP .I Meanings information is obtained by reading each .B D\(**X\(** subfile referenced by each .B C.\(** file, and by reading .B X\(**X\(** files. .IB nodename ! username is taken from the last line in the file which is of the form: .IP U .PP Likewise, .I commandline is taken from the last line of the form: .IP C .PP If a subfile name is referenced more than once, references after the first show the subfile as missing. If a subfile name appears in a (corrupt) directory more than once, the name is only found once, but then it is listed again under .BR Orphans . .PP .SH EXTERNAL INFLUENCES .SS Environment Variables .SM LC_COLLATE determines the order in which the output is sorted. .PP If .SM LC_COLLATE is not specified in the environment or is set to the empty string, the value of .SM LANG is used as a default. If .SM LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .SM LANG. If any internationalization variable contains an invalid setting, .I uuls behaves as if all internationalization variables are set to ``C'' (see .IR environ (5)). .SH AUTHOR .I uuls was developed by HP. .SH SEE ALSO mail(1), uucp(1), uuto(1), uux(1), uuxqt(1M), stat(2). .PP .SH DIAGNOSTICS The program writes an appropriate message to standard error if it has any problems dealing with a specified file (directory), including failure to get heap space. It always returns zero as its exit value. .PP If a control file is unopenable (wrong permissions or it disappeared while .B uuls was running), its name is preceded by a .B \(** and the size of the transaction is zero. If a subfile is missing (filename not found in the directory being listed) or not stat-able (if required for .B \-s or .BR \-k ), its name is preceded by a .B \(** and it contributes zero bytes to the size of the transaction. .PP If .B \-m is specified and a .B D\(**X\(** file is missing or unreadable, its name is given with a .B \(** prefixed, as usual. .SH BUGS This command uses .IR chdir (2) to change to each directory in turn. If more than one is specified, the second through last directories must be absolute (not relative) pathnames, or the .IR chdir (\|) may fail. .\" .\" index@\f2uuls\f1 \- list spooled \f2uucp\f1 transactions grouped by transaction@@@\f3uuls(1M)\f1 .\" index@transactions, list spooled \f2uucp\f1 transactions grouped by transaction@@@\f3uuls(1M)\f1 .\" index@uucp: list spooled \f2uucp\f1 transactions grouped by transaction@@@\f3uuls(1M)\f1 .\" index@spooled \f2uucp\f1 transactions grouped by transaction, list@@@\f3uuls(1M)\f1 .\" .\" toc@\f3uuls(1M)\f1:\0\0\f2uuls\f1@@@list spooled uucp transactions grouped by transaction .\" .\" fileset_database@uuls.1m@SYS-ADMIN-MAN .\" $Header: uusched.1m,v 72.4 94/07/25 15:53:03 ssa Exp $ .TA u .TH uusched 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uusched \- schedule uucp transport files .SH SYNOPSIS .C /usr/lbin/uucp/uusched .RC [ -u .IR debug_level\| ] .RC [ -x .IR debug_level\| ] .SH DESCRIPTION .C uusched is the .SM UUCP file transport scheduler. It is usually started by the daemon .CR uudemon.hour , which is started by .C cron (see .IR cron (1M)) from the following entry in .CR /var/spool/cron : .IP .C "39 * * * * /usr/bin/su uucp -c */usr/lbin/uucp/uudemon.hour > /dev/null*" .SS Options .C uusched recognizes two options which are provided for debugging purposes only. .RS .TP 20 .CI -x \0debug_level Output debugging messages. .TP .CI -u \0debug_level Pass as .C -x to .C uucico (see .IR uucico (1M)). The .I debug_level is a number between 0 and 9. The higher the number, the more detailed the information returned. .SH FILES .nf .C /etc/uucp/Systems .C /etc/uucp/Permissions .C /etc/uucp/Devices .C /var/spool/uucp/* .C /var/spool/locks/\s-1LCK\s0* .C /var/spool/uucppublic/* .fi .SH SEE ALSO cron(1M), uucico(1M), uusched(1M), uucp(1), uustat(1), uux(1). .PP .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .\" .\" index@\f4uusched\f1 \- schedule \f4uucp\f1 transport files@@@\f3uusched(1M)\f1 .\" index@schedule \f4uucp\f1 transport files@@@\f3uusched(1M)\f1 .\" index@files: schedule \f4uucp\f1 transport files@@@\f3uusched(1M)\f1 .\" index@uucp: schedule \f4uucp\f1 transport files@@@\f3uusched(1M)\f1 .\" index@transport files, schedule \f4uucp\f1@@@\f3uusched(1M)\f1 .\" .\" toc@\f3uusched(1M)\f1:\0\0\f4uusched\f1@@@schedule uucp transport files .\" .\" fileset_database@uusched.1m SYS-ADMIN-MAN .\" $Header: uusnap.1m,v 72.4 94/07/25 15:51:36 ssa Exp $ .TA u .TH uusnap 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uusnap \- show snapshot of the UUCP system .SH SYNOPSIS .C uusnap .SH DESCRIPTION .I uusnap displays in tabular format a synopsis of the current .SM UUCP situation. The format of each line is as follows: .IP .I site\0\0\0\0N Cmds\0\0\0\0N Data\0\0\0\0N Xqts\0\0\0\0Message .PP Where .I site is the name of the site with work, .I N is a count of each of the three possible types of work (command, data, or remote execute), and .I Message is the current status message for that site as found in the .C STST file. .PP Included in .I Message may be the time left before .SM UUCP can re-try the call, and the count of the number of times that .SM UUCP has tried to reach the site. The process id of .C uucico may also be shown if it is in a .SM TALKING state. .SH AUTHOR .C uusnap was developed by the University of California, Berkeley. .SH SEE ALSO uucp(1). .PP .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .\" .\" index@\f4uusnap\f1 \- show snapshot of the \s-1UUCP\s+1 system@@@\f3uusnap(1M)\f1 .\" index@snapshot of the \s-1UUCP\s+1 system@@@\f3uusnap(1M)\f1 .\" index@uucp: show snapshot of the \s-1UUCP\s+1 system@@@\f3uusnap(1M)\f1 .\" index@current status of the \s-1UUCP\s+1 system@@@\f3uusnap(1M)\f1 .\" index@status, current, of the \s-1UUCP\s+1 system@@@\f3uusnap(1M)\f1 .\" .\" toc@\f3uusnap(1M)\f1:\0\0\f4uusnap\f1@@@show snapshot of the UUCP system .\" .\" fileset_database@uusnap.1m SYS-ADMIN-MAN .\" $Header: uusnaps.1m,v 72.4 94/07/25 15:50:31 ssa Exp $ .TA u .TH uusnaps 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uusnaps \- sort and embellish uusnap output .SH SYNOPSIS .C uusnaps .SH DESCRIPTION .C uusnaps runs .C uusnap (see .IR uusnap (1M)) and post-processes the output into a more useful form. It sorts output lines in ``Pareto-style'', showing first those remote systems with the greatest number of .C Cmds files, next .C Data files, and then .C Xqts files. .PP .C uusnaps inserts a .C * after the number of .C Xqts files on those lines where .C Data is not equal to (2 \(mu .CR Cmds ) + .CR Xqts . This may be a sign of missing or orphaned transaction parts. Use .C uuls to check (see .IR uuls (1)). .PP .C uusnaps adds summary information after all .C uusnap output. The first line is a total of the numbers of .CR Cmds , .CR Data , and .CR Xqts files. The second line contains a grand total number of transaction files, followed by the number of directory bytes this represents. This is an indication of the true size of the directory itself if all empty entries were squeezed out. Finally, if it appears that transaction files might be missing or orphaned, .C uusnaps returns the number of missing or excess files. .PP .SH WARNINGS .C uusnaps assumes that each directory entry takes 24 bytes. .SH SEE ALSO uusnap(1M), uuls(1). .PP .\" .\" index@\f4uusnaps\f1 \- sort and embellish \f4uusnap\f1 output@@@\f3uusnaps(1M)\f1 .\" index@\f4uusnap\f1 output, sort and embellish@@@\f3uusnaps(1M)\f1 .\" index@sort and embellish \f4uusnap\f1 output@@@\f3uusnaps(1M)\f1 .\" .\" toc@\f3uusnaps(1M)\f1:\0\0\f4uusnaps\f1@@@sort and embellish uusnap output .\" .\" fileset_database@uusnaps.1m SYS-ADMIN-MAN .\" $Header: uusub.1m,v 72.4 94/07/25 15:47:43 ssa Exp $ .TA u .TH uusub 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uusub \- monitor uucp network .SH SYNOPSIS .C /usr/lbin/uucp/uusub .RI [ \|options\| ] .SH DESCRIPTION .C uusub defines a .C uucp subnetwork and monitors the connection and traffic among the members of the subnetwork. .SS Options .C uusub recognizes the following options: .RS .TP 12 .CI -a sys Add .I sys to the subnetwork. .TP .CI -d sys Delete .I sys from the subnetwork. .TP .C -l Report the statistics on connections. .TP .C -r Report the statistics on traffic amount. .TP .C -f Flush the connection statistics. .TP .CI -u hr Gather the traffic statistics over the past .I hr hours. .TP .CI -c sys Exercise the connection to the system .IR sys . If .I sys is specified as .CR all , exercise the connection to all the systems in the subnetwork. .RE .PP The connections report is formatted as follows: .RS .IP sys #call #ok time #dev #login #nack #other .PP Format interpretation: .RS .TP 15 .I sys remote system name, .TP .I #call number of times the local system tried to call .I sys since the last flush was done, .TP .I #ok number of successful connections, .TP .I time latest successful connect time, .TP .I #dev number of unsuccessful connections because of no available device (e.g., .SM ACU\c ), .TP .I #login number of unsuccessful connections because of login failure, .TP .I #nack number of unsuccessful connections because of no response (e.g. line busy, system down), .TP .I #other number of unsuccessful connections because of other reasons. .RE .RE .PP Traffic statistics are reported as follows: .RS .IP sfile sbyte rfile rbyte .PP Format interpretation: .RS .TP 15 .I sfile number of files sent, .TP .I sbyte number of bytes sent over the period of time indicated in the latest .I uusub command with the .CI -u hr option, .TP .I rfile number of files received, .TP .I rbyte number of bytes received. .RE .RE .PP The command: .IP .C "uusub -c all -u 24" .PP is typically started by .C cron once a day. .PP .SH FILES .TP 30 .C /var/uucp/.Admin/L_sub connection statistics .PD 0 .TP .C /var/uucp/.Admin/R_sub traffic statistics .TP .C /var/uucp/.Log/* system log file .PD .SH SEE ALSO uucp(1), uustat(1). .PP .SM .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .\" .\" index@\f4uusub\f1 \- monitor \f4uucp\f1 subnetwork activity@@@\f3uusub(1M)\f1 .\" index@monitor \f4uucp\f1 subnetwork activity@@@\f3uusub(1M)\f1 .\" index@\f4uucp\f1 subnetwork activity, monitor@@@\f3uusub(1M)\f1 .\" index@network, monitor \f4uucp\f1 subnetwork activity@@@\f3uusub(1M)\f1 .\" .\" toc@\f3uusub(1M)\f1:\0\0\f4uusub\f1@@@monitor uucp network .\" .\" fileset_database@uusub.1m SYS-ADMIN-MAN .\" $Header: uuxqt.1m,v 74.1 95/03/23 18:10:57 ssa Exp $ .TA u .TH uuxqt 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uuxqt \- execute remote uucp or uux command requests .SH SYNOPSIS .C /usr/lbin/uucp/uuxqt .RB [ \|\-s\| .IR system\| ] .RB [ \|\-x .IR debug_level\| ] .SH DESCRIPTION .C uuxqt executes remote job requests generated by use of the .C uux command (see .IR uux (1)). .C uux generates .C X. files and places them in the spool directory, where .C uuxqt searches for them. For each .C X. file, .C uuxqt determines whether the required data files are available and accessible, and if file commands are permitted for the requesting system. The .C Permissions file is used to validate file accessibility and command execute permission. Then .C uuxqt performs execution of the commands. .PP Two environment variables are set before the .C uuxqt command is executed: .C UU_MACHINE is the machine that sent the previous job and .C UU_USER is the user who sent the job. These can be used in writing commands that remote systems can execute to provide information, auditing, or restrictions. .PP .C uuxqt recognizes the following options: .RS .TP 20 .CI -s \0system Execute commands on the specified .IR system . .TP .CI -x \0debug_level Produce debugging output on standard output. .I debug_level is a single digit between 0 and 9. The higher the number, the more detailed debugging information returned. .RE .PP .SH FILES .nf .C /etc/uucp/Permissions .C /etc/uucp/Maxuuxqts .C /var/spool/uucp/* .C /var/spool/locks/LCK* .fi .SH SEE ALSO uucp(1), uustat(1), uux(1), uucico(1M). .PP .SM .TP Tim O'Reilly and Grace Todino, .IR "Managing UUCP and Usenet", O'Reilly & Associates, Inc. USA. .TP Grace Todino and Dale Dougherty, .IR "Using UUCP and Usenet", O'Reilly & Associates, Inc. USA. .\" index@\f4uuxqt\f1 \- execute remote \f4uucp\f1 or \f4uux\f1 command requests on local system@@@\f3uuxqt(1M)\f1 .\" index@execute remote \f4uucp\f1 or \f4uux\f1 command requests on local system@@@\f3uuxqt(1M)\f1 .\" index@remote \f4uucp\f1 or \f4uux\f1 command requests, execute on local system@@@\f3uuxqt(1M)\f1 .\" index@\f4uucp\f1 or \f4uux\f1 command requests from remote, execute on local system@@@\f3uuxqt(1M)\f1 .\" index@\f4uux\f1 or \f4uucp\f1 command requests from remote, execute on local system@@@\f3uuxqt(1M)\f1 .\" .\" toc@\f3uuxqt(1M)\f1:\0\0\f4uuxqt\f1@@@execute remote uucp or uux command requests .\" .\" fileset_database@uuxqt.1m SYS-ADMIN-MAN .\" $Header: vgcfgbackup.1m,v 72.4 94/08/26 17:10:31 ssa Exp $ .TA v .TH vgcfgbackup 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vgcfgbackup \- create or update LVM volume group configuration backup file .SH SYNOPSIS .CR /sbin/vgcfgbackup .RC [ -f .IR vg_conf_path ] .RC [ -u ] .I vg_name .SH DESCRIPTION The .CR vgcfgbackup command saves the LVM configuration for a volume group in a default or alternate configuration backup file (see the .CR -f option). .PP By default, .CR vgcfgbackup runs automatically each time an LVM command changes the LVM configuration. In this case, it always uses the default configuration backup file. An existing default configuration backup file is renamed with an extension of .CR ".old" . .SS Options and Arguments .CR vgcfgbackup recognizes the following options and arguments: .RS .TP 20 .I vg_name The path name of a volume group. .TP .CI -f \0vg_conf_path Save the configuration using an alternate file name specified by .IR vg_conf_path . .IP If .CR -f is omitted, the default file name is in the form: .RS .IP .CI /etc/lvmconf/ base_vg_name .conf .RE .IP .I base_vg_name is the base name of .IR vg_name . For example, if .I vg_name is specified as .CR /dev/vg00 , .I base_vg_name is .CR vg00 . .TP .CR -u Update the configuration backup file with the latest LVM configuration. Only those physical volumes added since the configuration backup file was last modified need to be online. .IP If .CR -u is omitted, all physical volumes for .I vg_name must be online. .RE .SH RETURN VALUE .CR vgcfgbackup exits with one of the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR >0 Failure. Errors occurred when information from the volume group was being accessed. .PD .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Back up LVM configuration information for volume group .CR /dev/vg00 in the default backup file .CR /etc/lvmconf/vg00.conf : .IP .C "vgcfgbackup /dev/vg00" .PP Update LVM configuration information corresponding to volume group .CR /dev/vg00 in the default backup file .CR /etc/lvmconf/vg00.conf : .IP .C "vgcfgbackup -u /dev/vg00" .PP Back up LVM configuration information for volume group .CR /dev/vg00 in the alternate configuration backup file .CR /tmp/vg00.backup : .IP .C "vgcfgbackup -f /tmp/vg00.backup vg00" .SH WARNINGS .PP It is recommended that any alternate configuration backup file be created in the root file system (as is the case with the default path name). This facilitates easy volume group recovery during maintenance mode, such as after a system crash. .SH AUTHOR .CR vgcfgbackup was developed by HP. .SH SEE ALSO vgcfgrestore(1M). .\" .\" toc@\f3vgcfgbackup(1M)\f1:\0\0\f4vgcfgbackup\f1@@@create or update LVM volume group configuration backup file .\" .\" index@\f4vgcfgbackup\f1 \- create LVM volume group configuration backup file@@@\f3vgcfgbackup(1M)\f1 .\" index@create backup LVM volume group configuration file@@@\f3vgcfgbackup(1M)\f1 .\" index@update backup LVM volume group configuration file@@@\f3vgcfgbackup(1M)\f1 .\" index@LVM volume group configuration backup file, create or update@@@\f3vgcfgbackup(1M)\f1 .\" index@volume group (LVM) configuration backup file, create or update@@@\f3vgcfgbackup(1M)\f1 .\" index@configuration backup file, create or update LVM volume group@@@\f3vgcfgbackup(1M)\f1 .\" index@backup file, create or update LVM volume group configuration@@@\f3vgcfgbackup(1M)\f1 .\" $Header: vgcfgrestor.1m,v 72.4.1.1 98/02/05 11:01:46 ssa Exp $ .TA v .TH vgcfgrestore 1M .SH NAME vgcfgrestore \- display or restore LVM volume group configuration from backup file .SH SYNOPSIS .PP .CR /sbin/vgcfgrestore .CR -n .IR vg_name .CR -l .PP .CR /sbin/vgcfgrestore .CR [-F] .CR -n .IR vg_name .RC [ -o .IR old_pv_path ] .I pv_path .PP .CR /sbin/vgcfgrestore .CR -f .IR vg_conf_path .CR -l .PP .CR /sbin/vgcfgrestore .CR [-F] .CR -f .IR vg_conf_path .RC [ -o .IR old_pv_path ] .I pv_path .SH DESCRIPTION The .CR vgcfgrestore command restores the LVM configuration data from a default .RC ( -n option) or alternate .RC ( -f option) configuration backup file to the physical volume named by .IR pv_path . Or it displays the configuration data on standard output .RC ( -l option). .PP The configuration stored for one physical volume, .IR old_pv_path , can be copied to another physical volume .IR pv_path .RC ( -o option). .SS Options and Arguments .CR vgcfgrestore recognizes the following options and arguments: .RS .TP 20 .IR pv_path The raw (character) device path name of a physical volume that is currently online. .IP If the .CR -o option is omitted, .I pv_path must specify a physical volume whose configuration is stored in the configuration backup file. .TP .CI -f \0vg_conf_path Get configuration information from the alternate configuration backup file .IR vg_conf_path . .TP .CI -F This option will force restoring the LVM configuration data even if the physical volume has alternate block(s) allocated inside the user data area. This option should be used with extreme caution. User is advised to fix the problem because potential data corruption could occur. .TP .CR -l List the configuration information saved in the specified configuration backup file. .TP .CI -n \0vg_name Get configuration information from the default configuration backup file: .RS .IP .CI /etc/lvmconf/ base_vg_name .conf .RE .IP .I vg_name is the path name of the volume group. .IP .I base_vg_name is the base name of .IR vg_name . For example, if .I vg_name is specified as .CR /dev/vg00 , .I base_vg_name is .CR vg00 . .TP .CI -o \0old_pv_path Restore the configuration information saved for physical volume .I old_pv_path to physical volume .IR pv_path . .IP This option is useful when a physical volume's name has changed since the configuration backup file was created or updated. .IP .I old_pv_path must be the path name of a physical volume whose configuration is stored in the configuration backup file. It need not be currently online. .IP .I pv_path must be the path name of a physical volume that is currently online. Its configuration need not be stored in the configuration backup file. .RE #ifdef B1 .SS Security Restrictions .PP You must have the .CR lvm secondary subsystem authorization to use this command. #endif .SH RETURN VALUE .CR vgcfgrestore exits with one of the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR >0 Failure. Errors occurred during the restore operation. .PD .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Restore the LVM configuration information for the physical volume .CR /dev/rdsk/c0t7d0 that was saved in the default file .CR /etc/lvmconf/vg00.conf : .IP .C "vgcfgrestore -n /dev/vg00 /dev/rdsk/c0t7d0" .PP Restore the LVM configuration information to physical volume .CR /dev/rdsk/c0t4d0 using alternate configuration file .CR /tmp/vg00.backup : .IP .C "vgcfgrestore -f /tmp/vg00.backup /dev/rdsk/c0t4d0" .PP List backup information saved in default configuration file .CR /etc/lvmconf/vg00.conf : .IP .C "vgcfgrestore -n /dev/vg00 -l" .PP which might display the following: .nf .IP .C "Volume Group Configuration information in ""/etc/lvmconf/vg00.conf""" .C "VG Name /dev/vg00" .C " ---- Physical volumes : 2 ----" .C " /dev/rdsk/c0t6d0 (Bootable)" .C " /dev/rdsk/c0t5d0 (Non-bootable)" .fi .PP Restore LVM configuration information stored for .CR /dev/rdsk/c0t7d0 in default configuration file .CR /etc/lvmconf/vg01.conf to physical volume .CR /dev/rdsk/c0t6d0 : .IP .C "vgcfgrestore -n /dev/vg01 -o /dev/rdsk/c0t7d0 /dev/rdsk/c0t6d0" .SH WARNINGS Preferably, the volume group should be made unavailable before executing .CR vgcfgrestore by executing the command .IP .CR "vgchange -a n" .IR vg_name .SH AUTHOR .CR vgcfgrestore was developed by HP. .SH SEE ALSO vgcfgbackup(1M). .\" .\" toc@\f3vgcfgrestore(1M)\f1:\0\0\f4vgcfgrestore\f1@@@restore volume group configuration .\" .\" index@\f4vgcfgrestore\f1 \- restore volume group configuration@@@\f3vgcfgrestore(1M)\f1 .\" index@restore volume group configuration@@@\f3vgcfgrestore(1M)\f1 .\" index@volume group configuration, restore@@@\f3vgcfgrestore(1M)\f1 .\" index@group configuration, restore volume@@@\f3vgcfgrestore(1M)\f1 .\" index@configuration, restore volume group@@@\f3vgcfgrestore(1M)\f1 .\" $Header: vgchange.1m,v 78.2.1.1 98/02/05 10:47:15 ssa Exp $ .TA v .TH vgchange 1M .SH NAME vgchange \- set LVM volume group availability .SH SYNOPSIS .SS "Activate volume group" .CR /sbin/vgchange .CR -a .IR availability .RC [ -l ] .RC [ -p ] .RC [ -q .IR quorum ] .RC [ -s ] .RC [ -P .IR resync_daemon_count ] .RI [ vg_name .RI ...] .SS "Assign to high availability cluster and mark volume group sharable" .CR /sbin/vgchange .CR -c .IR cluster .CR -S .IR shareable .IR vg_name .SS Remarks .ss 12 MC/ServiceGuard cluster operations require the installation of the optional MC/ServiceGuard software, which is not included in the standard HP-UX operating system. .PP Lock Manager cluster operations require the installation MC/LockManager software which is not included with the standard HP-UX operating system. .PP Mirror disk operations require the installation of the optional HP MirrorDisk/UX software, which is not included in the standard HP-UX operating system. .SH DESCRIPTION The .CR vgchange command with the .CR -a option activates or deactivates one or more volume groups. .PP The .CR vgchange command with the .CR -c option controls the membership of one or more volume groups in a high availability cluster. The .CR vgchange command with the .CR -c and .CR -S options control the membership of a volume group and mark it sharable. .PP The .CR vgchange command without the .CR -P .IR resync_daemon_count option (default) will spawn one nomwcsyncd process for each NOMWC/NONE Volume Group being activated. This may create a lot of nomwcsyncd processes running concurrently when it activates a large number of NOMWC/NONE Volume Groups and overload. .PP The .CR -P .IR resync_daemon_count option provides a way to control the number of concurrent nomwcsyncd processes. The count is an advisory number and a different count might be chosen internally if load balance or other reason is needed. When specified, there are up to .IR resync_daemon_count .CR + .CR 1 nomwcsyncd processes, one of them is the controlling processing to spawn others. .CR -P .CR 0 will use the system default (currently defined to be 4). .PP .IR vg_name must be defined as a volume group in the file .CR /etc/lvmtab . If .IR vg_name is omitted, all volume groups defined in .CR /etc/lvmtab are affected. .SS High Availability Cluster Overview .PP Volume groups can be defined on disk volumes that are connected to two or more systems in a high availability cluster. This situation has a high potential for data corruption unless special software is used to coordinate shared access to the same volume group by all systems. This coordination is provided by MC/ServiceGuard or MC/LockManager. .PP A volume group can be marked as part of a MC/ServiceGuard cluster. When such a group is activated in exclusive mode, it can be accessed for exclusive read-write activity by only one of the systems at a time; the other systems can have read-only access to the data. .PP A volume group can be marked as a part of an MC/LockManager cluster. In this case, the volume group can be marked as sharable, and may be activated in shared mode for read-write access by all the nodes in the cluster. Shared read-write access by multiple cluster nodes is coordinated by MC/LockManager's distributed lock manager (DLM). .SS Options and Arguments .CR vgchange recognizes the following options and arguments: .RS .TP 20 .I vg_name The path name of a volume group. .TP .CI -a \0availability Set volume group availability. .I availability can have one of the following values: .RS .RS .TP .CR y Activate each specified volume group and all associated physical and logical volumes for read-write access. If a volume group is marked as part of a high availability cluster, it is activated in exclusive read-write mode, as for the .CR "-a e" option. .TP .CR e Activate each specified volume group and all associated physical and logical volumes for exclusive read-write access. The volume group must be marked as part of a high availability cluster, and the availability software must be running on the system; otherwise, the volume group is not activated. .TP .CR s Activate each specified volume group and all associated physical and logical volume for shared read-write access. The volume group must be marked as part of a high availability cluster and marked sharable, otherwise, the volume group is not activated. If any of the logical volumes in the volume group are mirrored, and if there are more than two systems in the high availability cluster, this volume group will not be activated because HP MirrorDisk/UX software is only supported in a clustered environment with a maximum of two nodes configured. .PP If the .CR "-a y" or .CR "-a e" option is executed on a currently active volume group, .CR vgchange attempts to include any physical volumes that were previously listed as missing. This is useful if a physical volume has come back online. However, no automatic synchronization of any mirrored logical volumes is done. If synchronization is required, execute the .CR vgsync command (see .IR vgsync (1M)). .TP .CR r Activate each specified volume group and all associated physical and logical volumes for read-only access. This option is ignored for a volume group that is already activated. .IP If a volume group is marked as part of a high availability cluster, the high availability software must be running on the system; otherwise, the volume group is not activated. .TP .CR n Deactivate each specified volume group and its associated logical volumes. You must close the logical volumes prior to executing this option. For example, if the logical volume contains a file system, the file system must be unmounted. .RE .RE .TP .CI -c \0cluster Control the membership of volume groups in a high availability cluster. .I cluster can have one of the following values: .RS .RS .TP .CR y Mark each specified volume group as a member of the high availability cluster. The high availability software must be running; otherwise, the volume group is not marked. Needs to be done on one node only. .TP .CR n Remove each specified volume group from membership in the high availability cluster. The high availability software does not need to be running. .RE .RE .IP The volume group must be deactivated with the .CR "-a n" option before a .CR "-c y" \(or n option can be executed. .TP .CI -S \0sharable Control the sharability of volume groups in a high availability cluster. .I sharable can have one of the following values: .RS .RS .TP .CR y Mark each specified volume group as sharable. The high availability software must be running; otherwise, the volume group is not marked. Needs to be done on one node only. .TP .CR n Remove the shared attribute from the volume group. The high availability software does not need to be running. .RE .RE .IP The volume group must be deactivated with the .CR "-a n" option before a .CR "-S y" \(or n option can be executed. .TP .CR -l Disable the open of logical volumes that belong to each specified volume group. If the .CR -l option is set, later attempts to open the logical volumes fail. To allow an open of these logical volumes to succeed, execute .CR "lvchange -a y" . .TP .CR -p Activate each specified volume group only if all of the physical volumes that belong to it are available. .TP .CI -q \0quorum Set the quorum enforcement for each specified volume group. .I quorum can have one of the following values: .RS .RS .TP .CR y Enforce the quorum requirement. This is the default. .TP .CR n Ignore the quorum requirement. .RE .RE .IP The .CR "-q n" option can be used to activate the volume group when the disk quorum is not maintained because too many disks were lost. Since it ensures the integrity of the LVM configuration information, it is normally not advisable to override the quorum. .TP .CR -s Disable the synchronization of stale physical extents within the volume group specified by .IR vg_name . This option is only effective when used with the .CR "-a y" or .CR "-a e" option. .TP .CI -P resync_daemon_count gives the advisory count to control the number of nomwcsyncd processes on Volume Groups' activation. .RE \" (from beginning of Options subsection) .SS Mirror Disk Activation When the optional MirrorDisk/UX software is running, and a volume group is activated, LVM performs the necessary mirror consistency recovery for each logical volume in the volume group based on the state of the Mirror Write Cache and Mirror Consistency Recovery (see the Consistency Recovery section of .CR lvdisplay (1M)). In a non-shared environment, LVM supports .CR MWC, .CR NOMWC and the .CR NONE recovery. But in shared environment, LVM only supports .CR NOMWC and the .CR NONE recovery. .RS .TP 10 .CR MWC Recover mirror consistency by using the Mirror Write Cache and Mirror Consistency Record. This mode implies that the Mirror Write Cache is on. .TP .CR NOMWC Recover mirror consistency by searching all logical extents and copying data from a non-stale copy to the other mirror copies. This mode implies that the Mirror Write Cache is off. .TP .CR NONE Do not recover mirror consistency during volume group activation on this logical volume. This mode implies that the Mirror Write Cache is off. .RE .PP Next, mirror synchronization refreshes stale mirror copies by copying data from a nonstale copy. If the .CR -s option is specified on the command line, mirror synchronization does not occur. However, for those logical volumes that have Mirror Write Cache turned off, mirror synchronization is done independently of whether the .CR -s option appears on the command line. .SS General Activation If .CR vgchange cannot access a physical volume, it lists the volume's status as missing. If too many physical volumes in the volume group are missing, .CR vgchange reports that the group does not have a quorum and cannot be activated. The lack of a quorum can be overridden with the .CR "-q n" option. #ifdef B1 .SS Security Restrictions .PP You must have the .CR lvm secondary subsystem authorization to use this command. #endif .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES .PP Activate volume group .CR /dev/vg03 : .IP .C "vgchange -a y /dev/vg03" .PP Deactivate volume group .CR /dev/vg03 : .IP .C "vgchange -a n /dev/vg03" .PP Activate volume group .CR /dev/vg03 without synchronizing extents that are not current on logical volumes that have Mirror Write Cache turned on: .IP .C "vgchange -a y -s /dev/vg03" .SS Exclusive Activation .PP Set up volume group .CR /dev/vg03 for use in a high availability cluster: .IP .CI "vgchange -a n /dev/vg03 # Deactivate volume group" .br .CI "vgchange -c y /dev/vg03 # Enable volume group for HA cluster" .br .CI "vgchange -c y -S y /dev/vg03 #Enable volume group for HA cluster and mark as sharable .br .CI "vgchange -a e /dev/vg03 # Activate volume group in exclusive mode" .br .CI "vgchange -a s /dev/vg03 # Activate volume group in shared mode" .IP .CR "vgchange -a y" will activate all volume groups. It will activate those that are marked for membership in a high availability cluster in exclusive mode. .IP .CR "vgchange -a e" will activate all volumes that are marked for membership in a high availability cluster in exclusive mode. .SH WARNINGS .SS Ordinary Operation In ordinary operation (i.e., without the optional high availability software), it is possible to activate a volume group for read-write access from more than one physically connected system, leading to a high potential for data corruption. Therefore, if access is desired from more than one system to a single volume group, it is important that only one system activate the volume group for read-write access; the other systems can use read-only access. There is no problem if all systems activate the volume group for read-only access. .PP Furthermore, volume group information is only read from the disks during volume group activation. Dynamic changes to the volume group such as the following are not propagated to other systems sharing the volume group. .IP Logical volume configuration changes. .br Changes to the status of the mirrored extents. .br Bad-block relocation that occurs during write operations. .PP Because of these limitations, when sharing volume groups between systems it is recommended that logical volumes be accessed only by one system at a time. If logical volumes need to be accessed simultaneously, the logical volumes should not be mirrored and should not have bad-block relocation turned on, or all systems should use read-only access to the logical volumes. .SH SEE ALSO umount(1M), vgcreate(1M), vgextend(1M), vgreduce(1M), vgdisplay(1M). .TP If MC/ServiceGuard is installed: cmcheckconf(1M), cmquerycl(1M). .IP .IR "Managing MC/ServiceGuard" . .\" .\" toc@\f3vgchange(1M)\f1:\0\0\f4vgchange\f1@@@set LVM volume group availability .\" .\" index@\f4vgchange\f1 \- set LVM volume group availability@@@\f3vgchange(1M)\f1 .\" index@set LVM volume group availability@@@\f3vgchange(1M)\f1 .\" index@LVM volume group availability, set@@@\f3vgchange(1M)\f1 .\" index@volume group availability (LVM), set@@@\f3vgchange(1M)\f1 .\" index@group availability (LVM), set volume@@@\f3vgchange(1M)\f1 .\" index@availability (LVM), set volume group@@@\f3vgchange(1M)\f1 .\" $Header: vgchgid.1m,v 78.2 98/03/05 14:33:59 ssa Exp $ .\" Brand new manpage for 10.20 patch, created 12/97 .TA v .TH vgchgid 1M .SH NAME vgchgid \- modify the Volume Group ID (VGID) on a given set of physical devices. .SH SYNOPSIS .CR /usr/sbin/vgchgid .I PhysicalVolumePath .RI "[" PhysicalVolumePath "] ..." .SH DESCRIPTION The .CR vgchgid command is designed to change the LVM Volume Group ID (VGID) on a supplied set of disks. It is primarily targeted for use on EMC Symmetrix disks with EMC's product offering .IR TimeFinder (formerly called .CR "Symmetrix Multiple Mirror Facility " - .CR SMMF ). The .CR vgchgid command accepts a set of raw physical devices and checks the following criteria before it alters the VGID: .RS 0 .TP 3 \(bu All raw physical volume devices in the command line are EMC Symmetrix disks with the BCV attributes. .TP \(bu All raw physical volume devices in the command line belong to the same VG. .RE .PP Once the checks are successful, the same VGID is set on all the disks. It should be noted that for multi-PV volume groups all the physical volumes should be split-off and supplied in a single invocation of the .CR vgchgid command. .SS Options .CR vgchgid recognizes the following options and arguments: .RS .TP .I PhysicalVolumePath The raw devices path name of a physical volume. .RE .SS Background The EMC devices have a feature which allows a user to split-off a set of mirrored copies of physical volumes (termed .CR BCV s) just as LVM split-off logical volumes with .CR lvsplit command. As the result of the "BCV split", the split-off devices will have the same VGID as the original disks. The .CR vgchgid command is needed to modify the VGID on the BCV devices. Once the VGID has been altered, the BCV disks can be imported into a new volume group by using the .CR vgimport command. .SH WARNINGS Once the VGID has been changed, the original VGID is lost until a BCV device is re-mirrored with the original devices via the EMC command "BCV establish". (See EMC documentation for detail description of the command.) If .CR vgchgid command is used on a subset of BCV devices (e.g. two out of four BCV devices), the two groups of BCV devices would not be able to be imported into the same VG since they have different VGID on them. The solution is to re-mirror all four of the BCV devices and re-run the .CR vgchgid command on all four BCV devices at the same time, and then use the .CR vgimport command to import them into the same new VG. .SH RETURN VALUE .CR vgchgid command returns the following values: .RS .TP 3 0 VGID were modified with no error .PD 0 .TP 1 VGID were not modified .PD .RE .SH EXAMPLES An example showing how .CR vgchgid command might be used follows. .RS 0 .TP 3 1. System administrator issues the "BCV establish" command, and the "BCV split" command. Three BCV disks are created. .TP 2. Change the VGID on the BCV disks. .IP .C "vgchgid /dev/rdsk/c0t0d0 /dev/rdsk/c0t0d1 /dev/rdsk/c0t0d2" .TP 3. Make a new volume group using the BCV disks. .IP .PD 0 .C "mkdir /dev/vgbcv" .IP .C "mknod /dev/vgbcv/group c 64 0x040000" .PD .TP 4. Import the BCV disks into the new volume group. .IP .C "vgimport /dev/vgbcv /dev/dsk/c0t0d0 /dev/dsk/c0t0d1 /dev/dsk/c0t0d2" .TP 5. Activate the new volume group. .IP .C "vgchange -a y /dev/vgbcv" .TP 6. Backup the new volume group. .IP .C "vgcfgbackup /dev/vgbcv" .TP 7. Mount the associated logical volumes. .IP .PD 0 .C "mkdir /bcv/lvol1 /bcv/lvol2" .IP .C "mount /dev/vgbcv/lvol1 /bcv/lvol1" .IP .C "mount /dev/vgbcv/lvol2 /bcv/lvol2" .PD .RE .SH SEE ALSO vgimport(1M), vgscan(1M), vgcfgbackup(1M). .\" .\" index@\f4vgchgid\f1 \- modify the Volume Group ID (VGID) on a given set of physical devices@@@\f3vgchgid(1M)\f1 .\" index@\f1modify the Volume Group ID (VGID) on a given set of physical devices@@@\f3vgchgid(1M)\f1 .\" index@\f1Volume Group ID (VGID), modify, on a given set of physical devices@@@\f3vgchgid(1M)\f1 .\" index@\f1VGID, modify the Volume Group ID (VGID) on a given set of physical devices@@@\f3vgchgid(1M)\f1 .\" .\" toc@\f3vgchgid(1M)\f1:\0\0\f4vgchgid\f1@@@modify the Volume Group ID (VGID) on a given set of physical devices .\" $Header: vgcreate.1m,v 76.1.1.1 98/02/05 10:35:56 ssa Exp $ .TA v .TH vgcreate 1M .SH NAME vgcreate \- create LVM volume group .SH SYNOPSIS .CR /sbin/vgcreate .RC [ -f ] .RC [ -A .IR autobackup ] .RC [ -x .IR extensibility ] .RC [ -e .IR max_pe ] .ifn .br .ifn \0\0\0\0 .RC [ -l .IR max_lv ] .RC [ -p .IR max_pv ] .ift .br .ift \0\0\0\0 .RC [ -s .IR pe_size ] .RC [ -g .IR pvg_name ] .ifn .br .ifn \0\0\0\0 .I vg_name .IR pv_path \ ... .SH DESCRIPTION The .CR vgcreate command creates a new volume group. .I vg_name is a symbolic name for the volume group and must be used in all references to it. .I vg_name is the path to a directory entry under .CR /dev which must contain a character special file named .CR group . Except for the .CR group entry, the directory .I vg_name should be empty. The .I vg_name directory and the .CR group file have to be created by the user (see .IR lvm (7)). .PP .CR vgcreate leaves the volume group in an active state. .PP Before assigning a physical volume to a volume group, the physical volume has to be created using the .CR pvcreate command (see .IR pvcreate (1M)). .PP If .CR vgcreate fails to install the first specified physical volume into the volume group, the volume group is not created. If, for any reason, one of the remaining specified physical volumes cannot be installed into the volume group, an error message is printed, but the installation continues until the end of the list of physical volumes. .SS Options and Arguments .CR vgcreate recognizes the following options and arguments: .RS .TP 20 .I pv_path The block device path name of a physical volume that will be assigned to the new volume group. You can specify physical volume links .I (pv-links) for a physical volume providing different paths that reference the same physical volume in the .I pv_path list. The order in which the paths are listed is important. The first path becomes the .CI "primary link" to the physical volume, the second becomes an .CI "alternate link" to the physical volume. The .CI "primary link" is the default path used to access the physical volume. If the .CI "primary link" becomes unavailable, LVM automatically switches to the .CI "alternate link" to access the physical volume. .TP .I vg_name The path name of a subdirectory of the .CR /dev directory. .I vg_name must be empty except for a character special file named .CR group . Typically, this directory name is in the form .CI /dev/vg NN\f1, where .I NN numbers sequentially from .CR 00 . .TP .CI -A \0autobackup Set automatic backup for this invocation of this command. .I autobackup can have one of the following values: .RS .RS .TP .CR y Automatically back up configuration changes made to the volume group. This is the default. .IP After this command executes, the .CR vgcfgbackup command (see .IR vgcfgbackup (1M)) is executed for the volume group. .TP .CR n Do not back up configuration changes this time. .RE .RE .TP .CI -e \0max_pe Set the maximum number of physical extents that can be allocated from any of the physical volumes in the volume group. The default value for .I max_pe is .CR 1016 . However, if the size of any physical volume exceeds .CR 1016 times the .IR pe_size , the default value for .I max_pe is adjusted to match the physical volume size. The maximum number of physical extents can be a value in the range 1 to 65535. .TP .CI -f This option will force a volume group to be created with a physical volume which has alternate block(s) already allocated, (i.e. this physical volume was not initialized using .CR pvcreate -f.) This option should be used with extreme caution. If the volume group to be created has a different physical extent size, the alternate block(s) might be inside the user data area. Potential data corruption could occur. .TP .CI -g \0pvg_name Create a new physical volume group with the name .IR pvg_name . All physical volumes specified in the .I pv_path parameter become a member of the newly created physical volume group. .IP The physical volume group information is stored in an ASCII file, .CR /etc/lvmpvg . The file can be edited to create a physical volume group instead of using the .CR vgcreate command. However, ensure that the physical volumes to be used have already been installed in the volume group prior to creating the physical volume group. .IP The physical volume group name must be unique within a volume group although identical physical volume group names can appear in different volume groups (see .IR lvmpvg (4) for format details). .TP .CI -l \0max_lv Set the maximum number of logical volumes that the volume group is allowed to contain. The default value for .I max_lv is .CR 255 . The maximum number of logical volumes can be a value in the range 1 to 255. .TP .CI -p \0max_pv Set the maximum number of physical volumes that the volume group is allowed to contain. The default value for .I max_pv is .CR 16 . The maximum number of physical volumes can be a value in the range 1 to 255. .TP .CI -s \0pe_size Sets the number of megabytes in each physical extent, where .I pe_size is expressed in units of megabytes (MB) in the range 1 to 256. .I pe_size must be equal to a power of 2 (1, 2, 4, 8, etc.). The default value for .I pe_size is .CR 4 (four megabytes). .TP .CI -x \0extensibility Set the allocation permission for adding physical extents on the physical volumes specified by the .I pv_path parameter. .I extensibility can have one of the following values: .RS .RS .TP .CR y Allow allocation of additional physical extents on the physical volume. This is the default. .TP .CR n Prohibit allocation of additional physical extents on the physical volume. Logical volumes residing on the physical volume can still be accessed after the volume group has been activated by the .CR "vgchange -a y" command. .RE .RE .RE #ifdef B1 .SS Security Restrictions .PP You must have the .CR lvm secondary subsystem authorization to use this command. #endif .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Create a volume group named .I /dev/vg00 containing two physical volumes with extent size set to 2 MB, from scratch. .RS .PP First, create the directory .CR /dev/vg00 with the character special file called .CR group . .IP .C "mkdir /dev/vg00" .br .C "mknod /dev/vg00/group c 64 0x030000" .PP The minor number for the .CR group file should be unique among all the volume groups on the system. It has the format .CI 0x NN 0000 \f1, where .IR NN runs from .CR 00 to .CR 09 . The maximum value of .IR NN is controlled by the kernel tunable parameter .CR maxvgs . .PP Initialize the disks using .IR pvcreate (1M). .IP .C "pvcreate /dev/rdsk/c1t0d0" .br .C "pvcreate /dev/rdsk/c1t2d0" .PP Create the volume group. .IP .C "vgcreate -s 2 /dev/vg00 /dev/dsk/c1t0d0 /dev/dsk/c1t2d0" .PP Create a volume group named .CR /dev/vg01 that can contain a maximum of three logical volumes, with extent size set to 8 MB: .IP .C "vgcreate -l 3 -s 8 /dev/vg01 /dev/dsk/c3t4d0" .PP Create a volume group named .CR /dev/vg00 and a physical volume group named .CR PVG0 with two physical volumes: .IP .C "vgcreate -g PVG0 /dev/vg00 /dev/dsk/c1t0d0 /dev/dsk/c2t0d0" .PP Using the .CI "PV Links" feature to create a volume group named .CR /dev/vg00 with a physical volume which can be referenced by two different paths. .CR /dev/dsk/c3t0d0 and .CR /dev/dsk/c4t0d0 refer to the same physical volume, accessed via different controller hardware paths. In this example, .CR /dev/dsk/c3t0d0 becomes the .CI "primary link" to the physical volume. .CR /dev/dsk/c4t0d0 becomes an .CI "alternate link" to the physical volume. .IP .C "vgcreate /dev/vg00 /dev/dsk/c3t0d0 /dev/dsk/c4t0d0" .RE .SH WARNINGS It is not possible to create a volume group that contains both HP-IB devices and devices using another type of interface. .SH SEE ALSO pvcreate(1M), vgchange(1M), vgdisplay(1M), vgextend(1M), vgreduce(1M), lvm(7). .\" .\" toc@\f3vgcreate(1M)\f1:\0\0\f4vgcreate\f1@@@create LVM volume group .\" .\" index@\f4vgcreate\f1 \- create LVM volume group@@@\f3vgcreate(1M)\f1 .\" index@create LVM volume group@@@\f3vgcreate(1M)\f1 .\" index@LVM volume group, create@@@\f3vgcreate(1M)\f1 .\" index@volume group (LVM), create@@@\f3vgcreate(1M)\f1 .\" $Header: vgdisplay.1m,v 78.1 96/02/13 13:56:11 ssa Exp $ .TA v .TH vgdisplay 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vgdisplay \- display information about LVM volume groups .SH SYNOPSIS .CR /sbin/vgdisplay .RC [ -v ] .RI [ vg_name \ ...] .SH DESCRIPTION The .CR vgdisplay command displays information about volume groups. For each .I vg_name specified, .CR vgdisplay displays information for that volume group only. If no .I vg_name is specified, .CR vgdisplay displays names and corresponding information for all defined volume groups. .PP The volume group must be activated (see .IR vgchange (1M)) before it can be displayed. .SS Options and Arguments .CR vgdisplay recognizes the following option and argument: .RS .TP .I vg_name The path name of the volume group, for example, .CR /dev/vg00 . .TP .CR -v For each volume group, display additional information about each logical volume, physical volume, and physical volume group. .RE .SS Display Without \(miv Option If you omit the .CR -v option, only the following information is displayed: .TP .CR "--- Volume groups ---" .RS .TP 20 .CR "VG Name" The path name of the volume group. .TP .CR "VG Write Access" Current access mode of the volume group. Possible values are .CR read/write and .CR read-only . .TP .CR "VG Status" State of the volume group: always .CR available , as after a .CR "vgchange\ -a\ y" command, since deactivated volume groups are not displayed. .\" EDITOR NOTE: the alternate is "unavailable" (if restriction is removed) .TP .CR "Max LV" Maximum number of logical volumes allowed in the volume group. .TP .CR "Cur LV" Current number of logical volumes in the volume group. .TP .CR "Open LV" Number of logical volumes currently open in the volume group. .TP .CR "Max PV" Maximum number of physical volumes allowed in the volume group. .TP .CR "Cur PV" Current number of physical volumes in the volume group. .TP .CR "Act PV" Number of physical volumes that are currently active. .TP .CR "Max PE per PV" Maximum number (limit) of physical extents that can be allocated from any of the physical volumes in the volume group. .TP .CR "VGDA" Number of Volume Group Descriptor Areas within the volume group. .TP .CR "PE Size" Size of each physical extent. .TP .CR "Total PE" Total number of physical extents within the volume group: the sum of the number of physical extents belonging to each available physical volume in the volume group. .TP .CR "Alloc PE" Number of physical extents currently allocated to logical volumes. .TP .CR "Free PE" Number of physical extents not allocated. .TP .CR "Total PVG" Total number of physical volume groups within the volume group. .RE .SS Display With \(miv Option If you specify the .CR -v option, .CR vgdisplay lists the following additional information for each logical volume, for each physical volume, and for each physical volume group in the volume group: .TP .CR "--- Logical volumes ---" .IP Information about logical volumes belonging to .IR vg_name : .RS .TP 20 .CR "LV Name" The block device path name of a logical volume in the volume group. .TP .CR "LV Status" State of the logical volume: .RS .TP 25 .CR available/stale Logical volume available but contains physical extents that are not current. .TP .CR available/syncd Logical volume available and synchronized. .TP .CR available Logical volume available; stale/syncd state cannot be confidently determined because logical volumes have both the Mirror Write Cache and Mirror Consistency Recovery turned off. .TP .CR unavailable Logical volume is not available for use. .RE .TP .CR "LV Size (Mbytes)" Size of the logical volume. .TP .CR "Current LE" Number of logical extents in the logical volume. .TP .CR "Allocated PE" Number of physical extents used by the logical volume. .TP .CR "Used PV" Number of physical volumes used by the logical volume. .RE .TP .CR "--- Physical volumes ---" .IP Information about physical volumes belonging to .IR vg_name : .RS .TP 20 .CR "PV Name" The block device path name of a physical volume in the group. When an alternate link to a physical volume has been added, "Alternate Link" is displayed next to the device path name. .TP .CR "PV Status" State of the physical volume. .TP .CR "Total PE" Total number of physical extents on the physical volume. .TP .CR "Free PE" Number of free physical extents on the physical volume. .RE .TP .CR "--- Physical volume groups ---" .IP Information about physical volume groups belonging to .IR vg_name : .RS .TP 20 .CR "PVG Name" Name of a physical volume group in the volume group. .TP .CR "PV Name" The block device path name of a physical volume in the physical volume group. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Display information about all the volume groups within the system: .IP .C "vgdisplay" .PP Display all of the information about one volume group, including the characteristics and status of both the logical and physical extents of the volume group: .IP .C "vgdisplay -v /dev/vg02" .SH SEE ALSO lvdisplay(1M), pvdisplay(1M), vgchange(1M), vgcreate(1M). .\" .\" toc@\f3vgdisplay(1M)\f1:\0\0\f4vgdisplay\f1@@@display information about LVM volume groups .\" .\" index@\f4vgdisplay\f1 \- display information about LVM volume groups@@@\f3vgdisplay(1M)\f1 .\" index@display information about LVM volume groups@@@\f3vgdisplay(1M)\f1 .\" index@LVM volume groups, display information about@@@\f3vgdisplay(1M)\f1 .\" index@volume groups (LVM), display information about@@@\f3vgdisplay(1M)\f1 .\" $Header: vgexport.1m,v 76.2.1.1 98/02/04 15:04:27 ssa Exp $ .TA v .TH vgexport 1M .SH NAME vgexport \- export an LVM volume group and its associated logical volumes .SH SYNOPSIS .CR /sbin/vgexport .RC [ -m .IR mapfile ] .RC [ -p ] .RC [ -v ] .I vg_name .PP .CR /sbin/vgexport .C -m .IR mapfile .CR -s .CR -p .CR -v .I vg_name .SH DESCRIPTION Using the format of the first command line of the .BR SYNOPSIS above, the .CR vgexport command can be used to remove a volume group from the system. The volume group would be removed without modifying the logical volume information found on the physical volumes. .PP The volume group identified by .I vg_name is removed from the .CR /etc/lvmtab file, and the associated device files including the .I vg_name directory and .CR group file are removed from the system. .PP The volume group information and data is untouched on the physical volume. These disks can be imported to other system with the .CR vgimport command (see .IR vgimport (1M)). .SS Shareable Option, Series 800 Only In the second format of the command line, the .CR vgexport command generates a mapfile that contains a description of the volume group and its associated logical volume(s) (if any). The logical volume information found on the physical volumes is not modified. The volume group is not removed from the system. (See the second example below). .PP This mapfile can be copied to other systems that are part of a high availability cluster and the .CR vgimport command (see .IR vgimport (1M)) can be used to recreate the volume group. See also .IR vgchange (1M). .PP The volume group specified in the mapfile can be shared with the importing systems. The volume group is not removed from the exporting system. .sp .SS Options and Arguments .CR vgexport recognizes the following options and arguments: .RS .TP 15 .I vg_name The path name of the volume group. .TP .CI -m \0mapfile Specify the name of the file to which logical volume names and numbers are to be written. This file can be used as input to .CR vgimport (see .IR vgimport (1M)). If this option is not specified, a file named .CR mapfile is created in the current directory. When used with the .CR -s option, the volume group specified in the mapfile can be shared with other systems in the high availability cluster. .TP .CR -p Preview the actions to be taken but do not update the .CR /etc/lvmtab file or remove the devices file. This option is best used in conjunction with the .CR -v option. .TP .CR -v Print verbose messages including the names of the physical volumes associated with this volume group. .TP .CR -s Shareable option, Series 800 only. When the .CR -s option is specified, then the .CR -p , .CR -v , and .CR -m options must also be specified. A mapfile is created that can be used to create volume group entries on other systems in the high availability cluster (with the .CR vgimport command). .RE #ifdef B1 .SS Security Restrictions .PP You must have the .CR lvm secondary subsystem authorization to use this command. #endif .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES .PP Export the volume group .CR /dev/vg01 into mapfile .CR vg01.mapfile . The volume group will be removed from the exporting system. .IP .C "vgexport -m vg01.mapfile /dev/vg01" .PP Create a mapfile to be copied to other systems in a high availability cluster to build the volume group information for the volume group, .CR /dev/vg02 . Note that the volume group is not removed from the exporting system. The importing systems will create the volume group with the .CR vgimport command using the .CR -s and .CR -m options. .IP .C "vgexport -s -p -m vg02.mapfile /dev/vg02" .sp .SH "SEE ALSO" vgimport(1M), vgscan(1M). .\" .\" toc@\f3vgexport(1M)\f1:\0\0\f4vgexport\f1@@@export an LVM volume group and its associated logical volumes .\" .\" index@\f4vgexport\f1 \- export an LVM volume group and its associated logical volumes@@@\f3vgexport(1M)\f1 .\" index@export an LVM volume group and its associated logical volumes@@@\f3vgexport(1M)\f1 .\" index@volume group and its associated logical volumes (LVM), export@@@\f3vgexport(1M)\f1 .\" index@LVM volume group and its associated logical volumes, export@@@\f3vgexport(1M)\f1 .\" index@logical volumes, export an LVM volume group and its associated@@@\f3vgexport(1M)\f1 .\" $Header: vgextend.1m,v 76.1.1.1 98/02/04 14:54:26 ssa Exp $ .TA v .TH vgextend 1M .SH NAME vgextend \- extend an LVM volume group by adding physical volumes .SH SYNOPSIS .CR /sbin/vgextend .RC [ -f ] .RC [ -A .IR autobackup ] .RC [ -g .IR pvg_name ] .RC [ -x .IR extensibility ] .ifn .br .ifn \0\0\0\0 .I vg_name .I pv_path \&... .SS Remarks .CR vgextend cannot be performed if the volume group is activated in shared mode. .SH DESCRIPTION The .CR vgextend command assigns physical volumes to volume group .IR vg_name . The volume group must be active. .PP Volume groups are extended by adding one or more physical volumes specified by .IR pv_path \&.... .PP After the physical volumes have been successfully added to the volume group, they can be used. .PP Before assigning a physical volume to a volume group, create the physical volume with the .CR pvcreate command (see .IR pvcreate (1M)). .PP If, for any reason, a specified physical volume cannot be installed into the volume group, an error message is printed. However, the installation continues to the end of the list of physical volumes. .PP When a .IR pv_path refers to one of the physical volumes already in the volume group by a different .IR pv-link name, this new path becomes an .CI "alternate pv-link" to the physical volume. When multiple paths that reference the same disk are provided in the .IR pv_path list, the order of the paths is important. The first path becomes the .CI "primary link" to the physical volume, the second becomes an .CI "alternate link" to the physical volume. The .CI "primary link" is the path used to access the physical volume. If the .CI "primary link" becomes unavailable, LVM automatically switches to the .CI "alternate link" to access the physical volume. .SS Options and Arguments .CR vgextend recognizes the following options and arguments: .RS .TP 20 .I pv_path The block device path name of a physical volume. .TP .I vg_name The path name of the volume group. .TP .CI -A \0autobackup Set automatic backup for this invocation of this command. .I autobackup can have one of the following values: .RS .RS .TP .CR y Automatically back up configuration changes made to the volume group. This is the default. .IP After this command executes, the .CR vgcfgbackup command (see .IR vgcfgbackup (1M)) is executed for the volume group. .TP .CR n Do not back up configuration changes this time. .RE .RE .TP .CI -f This option will force a volume group to be extended with a physical volume which has alternate block(s) already allocated, (i.e. this physical volume was not initialized using .CR pvcreate -f.) This option should be used with extreme caution. If the disk is being extended to a volume group with a different physical extent size, the alternate block(s) might be inside the user data area. Potential data corruption could occur. .TP .CI -g \0pvg_name Extend an existing physical volume group while the volume group is being extended by adding all the physical volumes in the .I pv_path parameter to the physical volume group specified by .IR pv_group_name . .IP If the specified physical volume group does not exist, it is created, thus providing a means for creating new physical volume groups after the volume group has been created. Another way to extend or add a physical volume group is to edit the .CR /etc/lvmpvg file as described in .IR vgcreate (1M). See .IR lvmpvg (4) for format details. .TP .CI -x \0extensibility Set allocation permission for additional physical extents on the physical volume specified by .IR pv_path . .I extensibility can have one of the following values: .RS .RS .TP .CR y Allow allocation of additional physical extents on the physical volume. .TP .CR n Prohibit allocation of additional physical extents on the physical volume. Logical volumes residing on the physical volume can still be accessed. .RE .RE .RE #ifdef B1 .SS Security Restrictions .PP You must have the .CR lvm secondary subsystem authorization to use this command. #endif .IP .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Add physical volumes .CR /dev/dsk/c0t1d0 and .CR /dev/dsk/c0t2d0 to volume group .CR /dev/vg03 : .IP .C "vgextend /dev/vg03 /dev/dsk/c0t1d0 /dev/dsk/c0t2d0" .PP Extend physical volume group .CR PVG0 while adding physical volumes .CR /dev/dsk/c0t3d0 and .CR /dev/dsk/c0t4d0 to volume group .CR /dev/vg03 : .IP .C "vgextend -g PVG0 /dev/vg03 /dev/dsk/c0t3d0 /dev/dsk/c0t4d0" .PP Add a .CI "PV link" to one of the physical volumes in the volume group. Where .CR /dev/dsk/c0t4d0 and .CR /dev/dsk/c1t4d0 refer to the same physical volume (referenced via different controllers), and the volume group already contains .CR /dev/dsk/c0t4d0. .CR /dev/dsk/c0t4d0 remains the .CI "primary link" (in use) and .CR /dev/dsk/c1t4d0 becomes an .CI"alternate link"\f1. .IP .C "vgextend /dev/vg03 /dev/dsk/c1t4d0" .SH WARNINGS It is not possible to extend a volume group such that it contains both HP-IB devices and devices that use another type of interface. .PP The new physical volume which has been added to the volume group could potentially have different block size compared to physical volumes already in the volume group. .PP If a logical volume created on two or more physical volumes which have different block size, it is not possible to use such logical volume for file system purposes. See extendfs(1M). .PP For example, when a logical volume contains physical volumes that all have 1k block size, and then it is extended to contain a physical volume with 2k block size, then the block size of the volume group is increased to 2k. .SH ADDITIONAL WARNINGS Starting 10.20, the .CR vgextend command is supporting additional EMC Symmetrix disk product functionality (see .IR vgchgid (1M)). The .CR vgextend command will be enforcing a new rule such that a physical device, to be extended to a volume group, must have the same EMC Symmetrix attributes as the physical volumes already in the volume group. Clearly this checking only applies if the disks involved (those already in the volume group and those being added) in the operation are EMC Symmetrix. Should the command find an incompatibility, a message of the following type will be produced: .IP "Attempt to mix incompatible EMC Symmetrix disk types failed. Volume group contains standard disks, but physical volume /dev/dsk/cxtxdx contains EMC BCV DISK. Please consult the EMC Symmetrix documentation, if applicable". .SH SEE ALSO pvchange(1M), pvcreate(1M), vgchange(1M), vgcreate(1M), vgdisplay(1M). .\" .\" toc@\f3vgextend(1M)\f1:\0\0\f4vgextend\f1@@@extend an LVM volume group by adding physical volumes .\" .\" index@\f4vgextend\f1 \- extend an LVM volume group by adding physical volumes@@@\f3vgextend(1M)\f1 .\" index@extend an LVM volume group by adding physical volumes@@@\f3vgextend(1M)\f1 .\" index@volume group (LVM), extend by adding physical volumes@@@\f3vgextend(1M)\f1 .\" index@LVM volume group, extend by adding physical volumes@@@\f3vgextend(1M)\f1 .\" index@add physical volumes to extend an LVM volume group@@@\f3vgextend(1M)\f1 .\" index@physical volumes, extend an LVM volume group by adding@@@\f3vgextend(1M)\f1 .\" $Header: vgimport.1m,v 76.2.1.1 98/01/29 15:06:57 ssa Exp $ .\" Patch for 10.20 .TA v .TH vgimport 1M .SH NAME vgimport \- import an LVM volume group onto the system .SH SYNOPSIS .CR /sbin/vgimport .RC [ -m .IR mapfile ] .RC [ -p ] .RC [ -v ] .I vg_name .I pv_path \&... .PP .CR /sbin/vgimport .CR -m .IR mapfile .CR -s .CR -v .I vg_name .SH DESCRIPTION The .CR vgimport command adds the specified volume group to the system. The physical volumes, specified as .IR pv_path \&..., are scanned to obtain the volume group information and logical volume information. This command works much like .CR vgcreate by requiring that the volume group device directory and the .CR group special file be created before the command is executed (see .IR vgcreate (1M)). The .I vg_name is added from the .CR /etc/lvmtab file, and the associated logical volume device files are added to the system. .PP .CR vgimport assumes that the volume group information has already been created on the physical volumes. .PP This command is useful in conjunction with the .CR vgexport command (see .IR vgexport (1M)), to move volume groups from one system to other systems within a high availability cluster. .PP .CR vgimport creates logical volume devices files under the .I vg_name directory using the naming convention given in .IR mapfile or using the default naming convention used by the .CR lvcreate command (see .IR lvcreate (1M)). .PP .SS Shareable Option, Series 800 Only In the second format of the command line shown in .CR SYNOPSIS , the volume group specified in the mapfile is shared. .PP .CR vgimport does not activate the imported volume group due to the many possible options at volume group activation time. To activate the volume group once it has been successfully imported, use the .CR vgchange command (see .IR vgchange (1M)). .SS Options and Arguments .CR vgimport recognizes the following options and arguments: .RS .TP 15 .I pv_path The block device path names of a physical volume. This argument is not used with the .CR -s and related options. .TP .I vg_name The path name of the volume group. .TP .CI -m \0mapfile Specify the name of the file from which logical volume names and numbers are to be read. This option is optional when used as in the first command line format of the .BR SYNOPSIS. If this option is not specified, logical volume names are created using the default naming convention .CI lvol nn where .I nn is the logical volume minor number. When used with the .CR -s option, the volume group specified in the mapfile can be shared among the exporting system and the importing systems. .TP 15 .CR -s Shareable option, Series 800 Only. When the .CR -s option is specified, then the .CR -p , .CR -v , and .CR -m options must also be specified. The specified mapfile is the same mapfile specified by using the .CR vgexport command also using the .CR -p , .CR -m , and .CR -s options. The mapfile is used to create the volume groups on the importing systems. .TP 15 .CR -p Preview the actions to be taken but do not update the .CR /etc/lvmtab file or add the devices file. This option is best used in conjunction with the .CR -v option. .TP .CR -v Print verbose messages including names of the logical volumes. .RE #ifdef B1 .SS Security Restrictions .PP You must have the .CR lvm secondary subsystem authorization to use this command. #endif .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH WARNINGS Starting 10.20, the .CR vgimport command is supporting additional EMC Symmetrix disk product functionality (see .IR vgchgid (1M)). The .CR vgimport command will be enforcing a new rule such that the group of disks to be imported must have the same EMC Symmetrix attributes. Clearly this checking only applies if the disks involved in the operation are EMC Symmetrix. Should the command find an incompatibility, a message of the following type will be produced: .IP "Attempt to mix incompatible EMC Symmetrix disk types failed. Physical volume /dev/dsk/cxtxdx is EMC BCV disk, but physical volume /dev/dsk/cxtxdx is a standard disk. Please consult the EMC Symmetrix documentation, if applicable". .PP Note that EMC Symmetrix disks which do not have any of the additional attributes can still be mixed with non-EMC disks in a single volume group. .SH EXAMPLES Import the volume group .CR /dev/vg01 that is located on physical disks .CR /dev/dsk/c0t1d0 and .CR /dev/dsk/c0t3d0 : .IP .C "vgimport -v /dev/vg01 /dev/dsk/c0t1d0 /dev/dsk/c0t3d0" .PP Activate the volume group following a successful import: .IP .C "vgchange -a y vg01" .PP Import the volume group .CR /dev/vg01 using the mapfile, .CR /tmp/vg01.mapfile . The mapfile was previously specified by the .CR vgexport command on another system. The volume group, .CR /dev/vg01 , is specified in the mapfile and will be used by the importing system only. .IP .C "vgimport -v -m /tmp/vg01.mapfile /dev/vg01 /dev/dsk/c0t5d0 /dev/dsk/c0t7d0" .PP Import the volume group .CR /dev/vg02 using the mapfile, .CR /tmp/vg02.mapfile . The mapfile was previously specified by the .CR vgexport command on another system. The volume group, .CR /dev/vg02 , is specified in the mapfile and will be shared among the exporting system, this system, and other systems importing the volume group as shared. .IP .C "vgimport -v -s -m /tmp/vg02.mapfile /dev/vg02" .SH SEE ALSO vgexport(1M), vgscan(1M). .\" .\" toc@\f3vgimport(1M)\f1:\0\0\f4vgimport\f1@@@import an LVM volume group onto the system .\" .\" index@\f4vgimport\f1 \- import an LVM volume group onto the system@@@\f3vgimport(1M)\f1 .\" index@import an LVM volume group onto the system@@@\f3vgimport(1M)\f1 .\" index@LVM volume group, import onto the system@@@\f3vgimport(1M)\f1 .\" index@volume group (LVM), import onto the system@@@\f3vgimport(1M)\f1 .\" $Header: vgreduce.1m,v 78.1 96/02/13 13:56:41 ssa Exp $ .TA v .TH vgreduce 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vgreduce \- remove physical volumes from an LVM volume group .SH SYNOPSIS .CR /sbin/vgreduce .I vg_name .I pv_path \&... .PP .CR /sbin/vgreduce -f .I vg_name .SS Remarks .CR vgreduce cannot be performed if the volume group is activated in shared mode. .SH DESCRIPTION The .CR vgreduce command removes each physical volume specified by a .I pv_path argument from volume group .IR vg_name . .PP The .CR vgreduce command with -f option removes all missing physical volume from the volume group. .PP All but one physical volume can be removed. The last physical volume must remain in the volume group so that the logical volume driver can continue to operate. The last physical volume in the volume group can be removed with the .CR vgremove command (see .IR vgremove (1M)). .PP Before executing .CR vgreduce , remove all logical volumes residing on each physical volume represented by a .I pv_path by executing .CR lvremove (see .IR lvremove (1M)). .PP Any physical volume in the .I pv_path list that is also a member of a physical volume group (as defined in .CR /etc/lvmpvg ) is also removed from the physical volume group. If the physical volume happens to be the last one in the physical volume group, the physical volume group is also removed from the volume group. .PP When a physical volume in the .I pv_path list has multiple .CI "PV-links", the physical volume is .I not removed from the volume group, until all the links to the volume are removed. When a physical volume in the .I pv_path list is the .CI "primary link" (in use) to a physical volume, removing the link forces LVM to switch to the .CI "alternate link" to access the physical volume. When the .I pv_path removed is an .CI "alternate link" to the device, only the link is removed; the volume group and physical volume are otherwise unchanged. .SS Options and Arguments .CR vgreduce recognizes the following option and arguments: .RS .TP 15 .CI -f \0vg_name force reduction of missing physical volume(s) in a given volume group. .CR vgreduce obtains the name of each physical volume (PV) belonging to the volume group from the file .CR /etc/lvmtab . It then reads the LVM structures from each PV and compares these with that held by the kernel to work out which PVs are missing. PVs which are missing will be candidates for removal. If all the physical extents on the missing PV are free then it will be removed from the volume group. Otherwise .CR vgreduce will report the physical to logical extent mapping. For missing PVs which have extents in use you must free up all the extents by using .IR lvreduce (1M) and re-run .CR vgreduce with the .CR -f option. This option is most commonly used when the .IR vgdisplay (1M) command shows "Cur PV" higher than "Act PV" and all of the PVs belonging to the volume group are attached. .TP .I pv_path The block device path name of a physical volume. .TP .I vg_name The path name of the volume group. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Remove physical volume .CR /dev/dsk/c0t1d0 from volume group .CR /dev/vg01 : .IP .C "vgreduce /dev/vg01 /dev/dsk/c0t1d0" .PP Force reduction of missing PVs from volume group: .CR vg01 .IP .C "vgreduce -f /dev/vg01" .PP The following messages will appear after missing PVS has been removed successfully: .IP PV with key 0 sucessfully deleted from vg .CR /dev/vg01 .IP Repair done, please do the following steps.....: .IP 1. Save .CR /etc/lvmtab to another file. .IP 2. Remove .CR /etc/lvmtab . .IP 3. Use .CR "vgscan -v" to recreate .CR /etc/lvmtab . .IP 4. NOW use .IR vgcfgbackup (1M) to save the LVM setup. .SH SEE ALSO vgchange(1M), vgcreate(1M), vgdisplay(1M), vgextend(1M). .\" .\" toc@\f3vgreduce(1M)\f1:\0\0\f4vgreduce\f1@@@remove physical volumes from an LVM volume group .\" .\" index@\f4vgreduce\f1 \- remove physical volumes from an LVM volume group@@@\f3vgreduce(1M)\f1 .\" index@\f1remove physical volumes from an LVM volume group@@@\f3vgreduce(1M)\f1 .\" index@\f1reduce LVM volume group by removing physical volumes@@@\f3vgreduce(1M)\f1 .\" index@\f1LVM volume group, reduce by removing physical volumes@@@\f3vgreduce(1M)\f1 .\" index@\f1volume group (LVM), reduce by removing physical volumes@@@\f3vgreduce(1M)\f1 .\" index@\f1physical volumes, reduce LVM volume group by removing@@@\f3vgreduce(1M)\f1 .\" $Header: vgremove.1m,v 72.4 94/08/26 17:15:33 ssa Exp $ .TA v .TH vgremove 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME .PP vgremove \- remove LVM volume group definition from the system .SH SYNOPSIS .CR /sbin/vgremove .I vg_name ... .SH DESCRIPTION The .CR vgremove command removes from the system the last physical volume of the volume group and the definition of the volume group or groups specified by .IR vg_name \&.... Since all system knowledge of the volume group and its contents are removed, the volume group can no longer be accessed. .PP To move a volume group from one system to another, use the .CR vgexport command instead (see .IR vgexport (1M)). .PP Before executing .CR vgremove , remove all logical volumes residing on the last physical volume by executing .CR lvremove (see .IR lvremove (1M)). .PP .CR vgremove is equivalent to the inverse of executing .CR vgcreate for one physical volume (see .IR vgcreate (1M)). .PP Before removing a volume group, two steps are necessary: .RS .TP 4 1. Remove all the logical volumes belonging to the group by using the .CR lvremove command (see .IR lvremove (1M)). .TP 2. Remove all but one physical volume belonging to the volume group by using the .CR vgreduce command (see .IR vgreduce (1M)). .RE .PP If there is any physical volume group created under .IR vg_name \&..., the physical volume group information is also removed from file .CR /etc/lvmpvg . .SS Arguments .CR vgremove recognizes the following argument: .RS .TP 15 .IR vg_name The path name of a volume group. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Remove volume group .CR /dev/vg02 from the system: .IP .C "vgremove /dev/vg02" .SH SEE ALSO lvremove(1M), vgchange(1M), vgreduce(1M). .\" .\" toc@\f3vgremove(1M)\f1:\0\0\f4vgremove\f1@@@remove LVM volume group definition from the system .\" .\" index@\f4vgremove\f1 \- remove LVM volume group definition from the system@@@\f3vgremove(1M)\f1 .\" index@\f1remove LVM volume group definition from the system@@@\f3vgremove(1M)\f1 .\" index@\f1LVM volume group definition, remove from the system@@@\f3vgremove(1M)\f1 .\" index@\f1volume group definition (LVM), remove from the system@@@\f3vgremove(1M)\f1 .\" $Header: vgscan.1m,v 78.1.1.1 98/01/29 14:01:36 ssa Exp $ .TA v .TH vgscan 1M .SH NAME vgscan \- scan physical volumes for LVM volume groups .SH SYNOPSIS .CR /sbin/vgscan .RC [ \-a ] .RC [ \-p ] .RC [ \-v ] .SH DESCRIPTION The .CR vgscan command allows the re-creation of the .CR /etc/lvmtab file and possibly the associated volume group device files. This command should be run only in the event of a catastrophic error such as the deletion of the .CR /etc/lvmtab file or the mismatch of names of the physical volumes in the .CR /etc/lvmtab file to the actual physical volume path configuration. If the .CR /etc/lvmtab file exists, the information contained in the file is used to assist in rebuilding the file, but the existing file is updated with the new corrected configuration. .PP .CR vgscan searches each physical volume connected to the system, looking for logical volumes. If there are dual controller devices, only the primary controller device path is scanned, unless you specify the .CR \-a option to allow access to all paths. It groups these physical volumes into volume groups by matching the volume group information found on the physical volumes. Then it searches the .CR /dev directory for all .CR group device files with the LVM major number, and tries to match device files with the logical volumes' information found on the physical volumes. .PP If matches occur, it determines the volume group name from the device file path, and updates the .CR /etc/lvmtab file with the volume group name and the list of physical volumes paths contained in that volume group. For volume groups where the device files cannot be matched, it prints the list of physical volumes for each volume group. .PP After .CR vgscan completes successfully, run the .CR vgimport command on each set of unmatched physical volumes (see .IR vgimport (1M)). .SS Options .CR vgscan recognizes the following options: .RS .TP .CR \-a Scan all controller device paths for all disks. .TP .CR \-p Preview the actions that would be taken but do not update file .CR /etc/lvmtab . This option is best used in conjunction with the .CR \-v option. .TP .CR \-v Print verbose messages. .RE #ifdef B1 .SS Security Restrictions .PP You must have the .CR lvm secondary subsystem authorization to use this command. #endif .SH WARNINGS The following warning only applies to dual controller devices (NIKE), or disks with alternate path: .PP Since .CR vgscan search each disks on the system in the order of where they have configured. When .CR vgscan reconstruct .CR /etc/lvmtab file, the order of disks in the file could be different than it was before. The following will happen: .IP The designated primary and alternate link might not be the same as it was configured before. .IP Alternate links will be added to the .CR /etc/lvmtab file even if they might not be configured in the volume group initially. .IP The boot information might be incorrect due to different order of disks in the new .CR /etc/lvmtab file. .PP In order to correct the above problems, do the following: .IP Use .CR vgchange with .CR -a option to activate all volume groups. .IP Use .CR lvlnboot with -R option to correct boot information on disk. .IP Use .CR vgreduce to reduce any alternate links that were added to the .CR /etc/lvmtab file by .CR vgscan, but they were not needed. .IP If the original primary path of a disks become an alternate path after .CR /etc/lvmtab file is reconstructed, the order can be easily reverted by using .CR vgreduce to remove the primary path and use .CR vgextend to add the path back again. .PP If .CR /etc/lvmtab is destroyed, do not use .CR vgscan to re-construct .CR /etc/lvmtab if the system is heavily loaded by an application. Otherwise, .CR vgscan will create an incomplete .CR /etc/lvmtab due to a known NIKE/LVM limitation issue. It's important to quiesce the logical volume's I/O before re-constructing the .CR /etc/lvmtab . .PP If for some reason, there is a need to re-construct .CR /etc/lvmtab when the system is running production application, .CR vgscan will create a partial .CR /etc/lvmtab . In this case, most of the primary paths should be included in the .CR /etc/lvmtab . Use .CR vgextend to include any missing alternate paths in the VG. .SH EMC DISK WARNINGS Starting 10.20, the .CR vgscan command is supporting additional EMC Symmetrix disk product functionality (see .IR vgchgid (1M)). The .CR vgscan command will be enforcing a new rule such that only EMC disks with the same attributes can belong to the same volume group. Note that an EMC disk, without any of the additional attributes, can still be mixed with non-EMC disks in the same volume group. Please consult your EMC Symmetrix documentation, if applicable. .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Scan the primary controller device paths for all the physical volumes on the system, but do not update the .CR /etc/lvmtab file: .IP .C "vgscan \-p \-v" .PP Scan all controller device paths to all physical volumes on the system: .IP .C "vgscan \-a \-v" .PP Scan the primary controller device paths for all the physical volumes on the system and re-create .CR /etc/lvmtab file: .IP .C "vgscan \-v" .PP The following messages will appear after .CR /etc/lvmtab file is re-created. .IP *** LVMTAB has been created successfully. .IP *** If PV links are configured in the system .IP *** Do the following to resync information on disk. .IP *** #1. vgchange -a y .IP *** #2. lvlnboot -R .SH SEE ALSO vgexport(1M), vgimport(1M). .\" .\" toc@\f3vgscan(1M)\f1:\0\0\f4vgscan\f1@@@scan physical volumes for LVM volume groups .\" .\" index@\f4vgscan\f1 \- scan physical volumes for LVM volume groups@@@\f3vgscan(1M)\f1 .\" index@\f1scan physical volumes for LVM volume groups@@@\f3vgscan(1M)\f1 .\" index@\f1search physical volumes for LVM volume groups@@@\f3vgscan(1M)\f1 .\" index@\f1physical volumes, scan for LVM volume groups@@@\f3vgscan(1M)\f1 .\" index@\f1look for LVM volume groups on physical volumes@@@\f3vgscan(1M)\f1 .\" index@\f1LVM volume groups, scan physical volumes for@@@\f3vgscan(1M)\f1 .\" index@\f1volume groups (LVM), scan physical volumes for@@@\f3vgscan(1M)\f1 .\" $Header: vgsync.1m,v 72.4 94/08/26 17:16:31 ssa Exp $ .TA v .TH vgsync 1M "Requires Optional HP MirrorDisk/UX Software" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vgsync \- synchronize stale logical volume mirrors in LVM volume groups .SH SYNOPSIS .CR /sbin/vgsync .I vg_name ... .SS Remarks This command requires the installation of the optional HP MirrorDisk/UX software, which is not included in the standard HP-UX operating system. .SH DESCRIPTION The .CR vgsync command synchronizes the physical extents of each mirrored logical volume in the volume group specified by .IR vg_name \& .... Synchronization occurs only on the physical extents that are stale mirrors of the original logical extent. .PP The synchronization process can be time consuming, depending on the hardware characteristics and the amount of data. Unless disabled, the mirrors within a volume group are synchronized automatically when the volume group is activated by the .CR "vgchange -a y" command. .SS Arguments .CR vgsync recognizes the following argument: .RS .TP 15 .I vg_name The path name of a volume group. .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR LANG determines the language in which messages are displayed. .PP If .CR LANG is not specified or is null, it defaults to "C" (see .IR lang (5)). .PP If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see .IR environ (5)). .SH EXAMPLES Synchronize the mirrors on volume group .CR /dev/vg04 : .IP .C "vgsync /dev/vg04" .SH WARNINGS It is not advisable to interrupt a .CR vgsync process. .SH SEE ALSO lvsync(1M), vgchange(1M), vgdisplay(1M). .\" .\" index@\f1logical volume mirrors in LVM volume groups, synchronize stale@@@\f3vgsync(1M)\f1 .\" index@\f1mirrors in LVM volume groups, synchronize stale logical volume@@@\f3vgsync(1M)\f1 .\" index@\f1stale logical volume mirrors in LVM volume groups, synchronize@@@\f3vgsync(1M)\f1 .\" index@\f1synchronize stale logical volume mirrors in LVM volume groups@@@\f3vgsync(1M)\f1 .\" index@\f1LVM volume groups, synchronize stale logical volume mirrors@@@\f3vgsync(1M)\f1 .\" index@\f1volume groups (LVM), synchronize stale logical volume mirrors@@@\f3vgsync(1M)\f1 .\" index@\f1volume mirrors in LVM volume groups, synchronize stale logical@@@\f3vgsync(1M)\f1 .\" index@\f4vgsync\f1 \- synchronize stale logical volume mirrors in LVM volume groups@@@\f3vgsync(1M)\f1 .\" .\" toc@\f3vgsync(1M)\f1:\0\0\f4vgsync\f1@@@synchronize stale logical volume mirrors in LVM volume groups .\" $Header: vhe_altlog.1m,v 72.5 94/09/22 10:16:17 ssa Exp $ .TA v .TH vhe_altlog 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vhe_altlog \- login when Virtual Home Environment (VHE) home machine is not available .SH SYNOPSIS .C /usr/sbin/vhe/vhe_altlog .SH DESCRIPTION .CR vhe_altlog is a shell script that permits a user to log in when the home machine is not accessible through Virtual Home Environment (VHE). This script is executed when a login using the user name of .I altlogin is completed. After the user logs in using the user login name .CR altlogin , .CR vhe_altlog asks for a user name and password. If these are valid, the user is logged in on the machine and the home directory is a temporary directory such as .CR /tmp . This provides user access to other machines in the group of VHE nodes even though a home machine is not available. .PP A user entry for .CR altlogin must be present in .CR /etc/passwd for it to be a valid login name. A typical entry resembles the following: .IP .CR altlogin::6:1::/tmp:/usr/sbin/vhe/vhe_altlog .SH DIAGNOSTICS If an invalid user name or password is supplied, the attempted login is rejected. .SH AUTHOR .CR vhe_altlog was developed by HP. .SH FILES .CR /etc/passwd .SH SEE ALSO vhe_mounter(1M), vhe_u_mnt(1M), vhe_list(4). .\" .\" index@\f4vhe_altlog\f1: login when VHE home machine is not available@@@\f3vhe_altlog(1M)\f1 .\" index@login when VHE home machine is not available@@@\f3vhe_altlog(1M)\f1 .\" index@VHE home machine is not available, login when@@@\f3vhe_altlog(1M)\f1 .\" index@home machine is not available, login when VHE@@@\f3vhe_altlog(1M)\f1 .\" index@machine is not available, login when VHE home@@@\f3vhe_altlog(1M)\f1 .\" index@available, login when VHE home machine is not@@@\f3vhe_altlog(1M)\f1 .\" .\" toc@\f3vhe_altlog(1M)\f1:\0\0\f4vhe_altlog\f1@@@login when Virtual Home Environment (VHE) home machine is unavailable .\" $Header: vhe_mounter.1m,v 72.4 94/06/30 15:05:52 ssa Exp $ .TA v .TH vhe_mounter 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vhe_mounter \- start the Virtual Home Environment (VHE) .SH SYNOPSIS .C /usr/sbin/vhe/vhe_mounter .SH DESCRIPTION .CR vhe_mounter is a shell script that configures a machine to operate with the Virtual Home Environment (VHE). VHE enables users to have the same view of their execution environments when logging in on machines interconnected with VHE. Machines connected with VHE must also be running the Network File System (NFS). .PP Information needed by .CR vhe_mounter is provided by file .CR /etc/vhe_list which contains a list of host names included in the group of VHE machines. .SH DIAGNOSTICS .CR vhe_mounter always returns exit code .CR 0 . .SH AUTHOR .CR vhe_mounter was developed by HP. .SH FILES .C /etc/vhe_list .SH SEE ALSO vhe_altlog(1M), vhe_u_mnt(1M), vhe_list(4). .\" .\" index@\f4vhe_mounter\f1: start the Virtual Home Environment \s-1(VHE)\s0@@@\f3vhe_mounter(1M)\f1 .\" index@start the Virtual Home Environment \s-1(VHE)\s0@@@\f3vhe_mounter(1M)\f1 .\" index@Virtual Home Environment \s-1(VHE)\s0, start the@@@\f3vhe_mounter(1M)\f1 .\" .\" toc@\f3vhe_mounter(1M)\f1: \f4vhe_mounter\f1@@@start the Virtual Home Environment \s-1(VHE)\s0 .\" $Header: vhe_u_mnt.1m,v 72.4 94/06/30 15:07:25 ssa Exp $ .TA v .TH vhe_u_mnt 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vhe_u_mnt \- perform Network File System (\s-1NFS\s0) mount to remote file system .SH SYNOPSIS .C /usr/sbin/vhe/vhe_u_mnt .SH DESCRIPTION .CR vhe_u_mnt enables a user to perform a Network File System (NFS) mount to a remote file system. .CR vhe_u_mnt is executed upon completion of a login using user name .CR mounter . After logging in as user .CR mounter , .CR vhe_u_mnt asks for the name of the machine to which an NFS mount is to be done. If that machine name is listed in file .CR /etc/vhe_list , mounts that are valid for that machine are made. This prevents the command from giving a user the ability to do NFS mounts to arbitrary machines. File .CR /etc/vhe_list contains a list of hostnames that are part of the VHE group. .PP User name .CR mounter must be present in file .CR /etc/passwd file for it to be a valid login name. A typical entry resembles: .IP .CR mounter::6:1::/:/usr/sbin/vhe/vhe_u_mnt .SH DIAGNOSTICS If a machine name is supplied that is not contained in .CR /etc/vhe_list , an error message is produced indicating that the machine is not on the list of machines available for mounting. .SH AUTHOR .CR vhe_u_mnt was developed by HP. .SH FILES .C /etc/passwd .br .C /etc/vhe_list .SH SEE ALSO vhe_altlog(1M), vhe_mounter(1M), vhe_list(4). .\" .\" index@\f4vhe_u_mnt\f1: perform \s-1NFS\s0 mount to remote file system@@@\f3vhe_u_mnt(1M)\f1 .\" index@perform \s-1NFS\s0 mount to remote file system@@@\f3vhe_u_mnt(1M)\f1 .\" index@Network File System \s-1(NFS)\s0 mount to remote file system, perform@@@\f3vhe_u_mnt(1M)\f1 .\" index@\s-1(NFS)\s0 mount to remote file system, perform Network File System@@@\f3vhe_u_mnt(1M)\f1 .\" index@mount to remote file system, perform Network File System@@@\f3vhe_u_mnt(1M)\f1 .\" index@remote file system, perform Network File System mount to@@@\f3vhe_u_mnt(1M)\f1 .\" index@file system, perform Network File System mount to remote@@@\f3vhe_u_mnt(1M)\f1 .\" .\" toc@\f3vhe_u_mnt(1M)\f1: \f4vhe_u_mnt\f1@@@perform Network File System \s-1(NFS)\s0 mount to remote file system .\" $Header: vipw.1m,v 72.4 93/12/06 19:59:59 ssa Exp $ .TA v .TH vipw 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vipw \- edit the password file .SH SYNOPSIS .C vipw .SH DESCRIPTION .C vipw edits the password file while setting the appropriate locks, and does any necessary processing after the password file is unlocked. If the password file is already being edited, you will be told to try again later. The .C vi editor is used unless the environment variable .C EDITOR indicates an alternate editor. .C vipw performs a number of consistency checks on the password entry for .CR root , and does not allow a password file with an incorrectly formatted root entry to be installed. .SH WARNINGS An .C /etc/passwd.tmp file not removed when a system crashes prevents further editing of the .C /etc/passwd file using .C vipw after the system is rebooted. .SH AUTHOR .C vipw was developed by the University of California, Berkeley. .SH FILES .C /etc/passwd.tmp .SH SEE ALSO passwd(1), passwd(4). .\" .\" index@\f4vipw\f1 \- edit the password file@@@\f3vipw(1M)\f1 .\" index@\f4vi\f1 edit on the password file@@@\f3vipw(1M)\f1 .\" index@edit the password file using \f4vi\f1 editor@@@\f3vipw(1M)\f1 .\" index@password file, edit using \f4vi\f1 editor@@@\f3vipw(1M)\f1 .\" index@files: password file, edit using \f4vi\f1 editor@@@\f3vipw(1M)\f1 .\" .\" toc@\f3vipw(1M)\f1:\0\0\f4vipw\f1@@@edit the password file .\" .\" fileset_database@vipw.1m SYS-ADMIN-MAN .\" $Header: vme_config.1m, updated 5/14/96 -rod@acm.org $ .TH vme_config 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Rel. 10.20: August, 1996 .SH NAME vme_config \- VME configuration utility .SH SYNOPSIS .SS "Store configuration in nonvolatile memory" .CR vme_config .RC [ \-f .IR cfgfile ] .RC [ \-D .IR name ] .RC [ \-U .IR name ] .SS "Display address map for address modifier" .CR vme_config .CI \-m " address_modifier" .RC [ \-f .IR cfgfile ] .RC [ \-D .IR name ] .RC [ \-U .IR name ] .SS "Display holes in address map for address modifier" .CR vme_config .CI \-h " address_modifier" .RC [ \-f .IR cfgfile ] .RC [ \-D .IR name ] .RC [ \-U .IR name ] .SS "Display entity information" .CR vme_config .CI \-e " entity_name" .RC [ \-f .IR cfgfile ] .RC [ \-D .IR name ] .RC [ \-U .IR name ] .SS "Perform syntax check" .CR vme_config .CR \-c .RC [ \-f .IR cfgfile ] .RC [ \-D .IR name ] .RC [ \-U .IR name ] .SS "Display the CPU/card number" .CR vme_config .CR \-N .SS "Set the CPU/card number" .CR vme_config .CI \-N " cpu_number" .SH DESCRIPTION The .CR vme_config utility creates a VME system configuration by reading required resources from an ASCII configuration file. The configuration file specifies what address ranges each processor, card, or shared memory space occupies, which interrupt levels each processor handles, and assigns other VME resources. The configuration file format is described in .IR vme.CFG (4). .PP When .CR vme_config is invoked without command line parameters, it generates a configuration from the default file .CR /etc/vme/vme.CFG . The configuration information for the current CPU is saved to the system's nonvolatile memory. .PP The current CPU is identified by the CPU number stored in nonvolatile memory. This value may be changed by using the .CR \-N .I cpu_number option. For more information on VME configuration and configuration file format, see the .IR "HP-UX 10.20 VME Services Guide" . .br .PP .CR vme_config should be run before system shutdown to install cards or other processors. .PP Storing configuration information to nonvolatile memory requires that the .CR vme2 device driver be installed in the kernel. The .CR vme2 device driver is in the VME_SERV fileset. .SS Options .CR vme_config recognizes the following options in the combinations specified in the SYNOPSIS section: .TP .CR \-c Perform a syntax check on the configuration file. The configuration is not saved in the system's nonvolatile memory. .TP .CI \-e "\0entity_name" Display information about the specified entity. .I entity_name is the name of a processor, card, or memory entity declared in the configuration file. This option is useful in determining where .CR vme_config has placed dynamically locatable memory entities. For more information on dynamically configured memory entities, see .IR vme.CFG (4). .TP .CI \-f "\0cfgfile" Use the specified configuration file instead of .CR /etc/vme/vme.CFG . .TP .CI \-h "\0address_modifier" Display the holes in the address map of the address space indicated by the specified address modifier. This option is helpful in determining where a new card or CPU can be placed. .TP .CI \-m "\0address_modifier" Display the address map of the address space indicated by the specified address modifier. See .IR vme.CFG (4). .TP .CR \-N Print the CPU/card number of this processor (in decimal) on standard output. .TP .CI \-N "\0cpu_number" Change the CPU/card number of this processor. .PP Options passed to .CR cpp : .TP .PD 0 .CI \-D "\0name" .TP .PD .CI \-D "\0name=def" Passed to .CR cpp to define .I name as if by a .CR #define directive. If no .CI = def is given, .I name is defined as 1. .TP .CI \-U "\0name" Passed to .CR cpp to remove any initial definition of .IR name . .PP The .CR \-D option has lower precedence than the .CR \-U option. Thus, if the same name is used in both a .CR \-D option and a .CR \-U option, the name is undefined, regardless of the order of the options. .SS "Configuration Process" To configure a VME system, follow these steps. For further information, refer to the .IR "HP-UX 10.20 VME Services Guide" . .br .RS 2 .TP 3 1. Create a configuration file .CR /etc/vme/vme.CFG and edit another file to reflect the desired VME system. Information on cards or other processors should be provided by the vendor. Information on HP processors is available in example configuration files in the directory .CR /etc/vme . .TP 2. Execute .CR vme_config on each HP-UX processor in the VME system, using the same configuration file for every processor. .CR vme_config builds a conflict-free configuration, then saves the configuration to nonvolatile memory (NVM). .TP 3. Install appropriate drivers and device files. .TP 4. Shut down the system. .TP 5. Install the other processors and cards. Some cards have hardware switches that must be set according to the configuration. Refer to the card's documentation for information about any hardware switches. .TP 6. Reboot the system. The HP-UX kernel initializes the VME hardware according to the contents of NVM. .RE .SS EXAMPLES .PP Loading nonvolatile memory with configuration specified in .CR /etc/vme/vme.CFG . .IP .C "vme_config" .PP Loading nonvolatile memory with configuration specified in a different file. .IP .C "vme_config -f my_cfg.CFG" .PP Changing the CPU number. .IP .C "vme_config -N 2" .PP Displaying address space generated from a specific file. .IP .C "vme_config -f my_cfg.CFG -m A24" .SH RETURN VALUES .CR vme_config returns the following values: .RS .TP .CR 0 Successful completion. .TP .CR 1 There is a syntax error in the configuration file. .TP .CR 2 There is an internal or system error. .RE .SH WARNINGS .CR vme_config asks for confirmation before overwriting values stored in nonvolatile memory. .PP A system reboot is required before the stored configuration information takes effect. .PP The .CR vme2 device driver must be in the kernel before .CR vme_config can save configuration information in nonvolatile memory. The .CR vme2 driver is in the fileset .CR VME-SERV . .SH AUTHOR .CR vme_config was developed by HP. .SH FILES .TP 10 .CR /etc/vme/vme.CFG The default CFG file. .TP .CR /etc/vme/example.CFG An example CFG file showing various record formats. .TP .CR /etc/vme/example2.CFG An example CFG file showing a configuration for two HP processors in the same VME system. .TP .CR /etc/vme/example3.CFG An example CFG file showing a configuration for many processors and cards in the same VME system. .TP .CR /var/adm/vme/system.log This file contains the current system configuration. .SH SEE ALSO bp_config(1m), cpp(1), vme.CFG(4). .PP .IR "HP-UX 10.20 VME Services Guide" . .RE .SH DIAGNOSTICS Error messages are displayed on standard output. .TP .C "Warning 000: Memory collision detected" .IP .CR vme_config detected a memory range collision, which implies that two or more memory entities were assigned address ranges that overlap. .IP If a memory overlap exists, multiple hardware devices can attempt to put data on the data transfer bus simultaneously. This causes data bus contention, which will probably cause a system crash. .IP However, because certain types of hardware may allow memory range overlaps, memory collisions are flagged as a warning rather than an error. This warning may be ignored only if the conditions under which it occurs are fully understood. .IP Because memory collisions occur when two or more entities attempt to map into the same memory range, you can resolve the collision by moving one of the entities. Recall that an entity can only be moved to an address range that the underlying hardware supports. .IP Use the command .CI vme_config\0\-h \0address_modifier to show the current unused addresses in the requested address space. .TP .C "Warning 001: Unknown record keyword" .IP The beginning of a new record was expected, but the word or symbol found is not a known record keyword. .IP Because HP-UX and HP-RT use different utilities to provide VME configuration functionality, the keyword may indicate a record used by one utility and not the other. .IP Also ensure you didn't make a typographical error in the keyword. .TP .C "Warning 002: Unknown CPU option" .IP An option used with a processor declaration record is not a known option. .IP Ensure you didn't make a typographical error in the option. .TP .C "Warning 003: Unknown or user address modifier. No range checking." .IP The address modifier specified in a memory record is either incorrect or a user address modifier .RC ( 0x10 \(mi 0x1f ). .IP If it is a user address modifier, .CR vme_config cannot determine if the address ranges associated with entities within this memory record are correct. .CR vme_config will still detect address collisions. .TP .C "Warning 004: Address will be truncated to fit address space" .IP Certain cards can occupy multiple address spaces that have different maximum address limitations. For these cards, the appropriate most significant bits of the address are truncated for the smaller of the spaces. .IP For example, if a card responds to both A16 and A24 space, it ignores the upper 8 bits for addresses above 64 KB (64 KB is the maximum address for A16 space). Hence, the address 0x004567 will be 0x004567 in both A24 and A16 space. The address 0x034567 will be 0x034567 in A24 space and 0x004567 in A16 space. .IP .CR vme_config performs similar truncation when building memory maps for entities that exist in more than one address space. .IP If the card you are using supports address truncation, you can safely ignore this warning. If you are not sure if your card supports this truncation, do not ignore this warning. Instead, create a configuration that does not generate the warning: .RS .TP \(bu If the memory record uses the form .IC starting_address \- ending_address or .IC starting_address : size\f1, change the hard-coded addresses. .TP \(bu If the memory record uses the form .CI "align " requirement : size\f1, addresses are allocated dynamically. In dynamic allocation, .CR vme_config attempts to allocate the same address in all spaces. .RE .IP This warning is produced if .CR vme_config cannot allocate the same address in all spaces. Hence, some other entity is occupying the correct space and its memory record should be changed. .TP .C "Warning 005: Unknown hint" .IP A hint associated with an entity is not in the list of currently known hints. .IP Because HP-UX and HP-RT use different utilities to provide VME configuration functionality, the hint may be used by one utility and not the other. .IP Also ensure you didn't make a typographical error in the hint. .TP .C "Warning 006: Unknown VME ID or wildcard. No checking will be performed" .IP If the ID associated with a processor in a processor record is not known or is a wildcard (indicating that it is a non-HP processor), .CR vme_config cannot perform consistency checking on the resources assigned to that processor. .TP .C "Warning 007: Not all interrupt request lines assigned to processors" .IP One or more interrupt request lines have not been assigned to a processor. Interrupt assignments are made in interrupt records in the configuration file. .IP If the interrupt request line is not used by any card or software driver in the system, this warning may be ignored. .TP .C "Warning 008: sgc_rod=value is obsolete. Use keep_bus=value instead." .IP The .CR sgc_rod= { TRUE | FALSE } field is obsolete. Use the .CR keep_bus= { TRUE | FALSE } field instead, and set it to .CR FALSE (the default), unless you want a minor improvement in VME transfer rate at the expense of the performance of all other subsystems. .TP .C "Warning 009: eir_pass=value is obsolete. Use keep_bus=value instead." .IP The .CR eir_pass= { TRUE | FALSE } field is obsolete. Use the .CR keep_bus= { TRUE | FALSE } field instead, and set it to .CR FALSE (the default), unless you want a minor improvement in VME transfer rate at the expense of the performance of all other subsystems. .TP .C "Warning 010: a24_direct_mapped_size is obsolete." .br .C "Use access=direct_map_to PA_address instead." .IP Explicit .CR a24_direct_mapped_size records are no longer used. Instead, use a memory record to declare a memory entity. Set .CI "access=direct_map_to " PA_address\f1, where .IR PA_address is the PA address target of the direct mapped window. (For HP Models 742 and 747, .IR PA_address must be 0.) .TP .C "Warning 011: Entity records are obsolete." .br .C "Move name, hints, and permissions to memory records." .IP A version of .CR vme_config prior to HP-UX 9.05 defined memory entities with a combination of entity records and memory records. This version defines memory entities with an enhanced memory record, and no longer uses entity records. For more information, see . .br .TP .C "Warning 012: Cannot set slave mapper on non-HP processor" .IP .CR access=slave can only be used for memory supplied by HP processors. For memory supplied by third-party processors or VME cards, omit the .CR access= field. .TP .C "Warning 013: Cannot set FIFO on non-HP processor" .IP .CR access=fifo can only be used for memory supplied by HP processors. For memory supplied by third-party processors or VME cards, omit the .CR access= field. .TP .C "Warning 014: Cannot set location monitor on non-HP processor" .IP .CR access=loc_mon can only be used for memory supplied by HP processors. For memory supplied by third-party processors or VME cards, omit the .CR access= field. .TP .C "Warning 015: Cannot set direct mapped window on non-HP processor" .IP .CI "access=direct_map_to " PA_address can only be used for memory supplied by HP processors. For memory supplied by third-party processors or VME cards, omit the .CR access= field. .TP .C "Warning 017: Cannot set DMA parameters on non-HP processor" .IP .CR vme_config cannot configure DMA hardware on third-party processors. If you are using an HP processor, check the ID field in the proc record. .TP .C "Warning 018: Cannot set DMA parameters on HP Model 742 or 747" .IP HP Models 742 and 747 do not have a DMA controller. .TP .C "Warning 019: DMA parameters already set" .IP DMA parameters for this processor have already been set. Delete the duplicate .CR dma_params record. (Subsequent .CR dma_params records overwrite previous values.) .TP .C "Warning 020: Duplicate field" .IP This record contains two or more entries for the same field. Delete the duplicate fields. Note that subsequent fields overwrite previous values. .IP .TP .C "Syntax Error 100: Newline expected" .IP The current line should be terminated by a newline. This error usually occurs on the first line of a complex record. .CR vme_config uses the ordering of .CR { and newline to distinguish between single line and complex records. .TP .C "Syntax Error 101: '{' expected" .IP An opening brace .RC ( { ) is expected here. This error usually occurs on the first line of a complex record. .CR vme_config uses the ordering of .CR { and newline to distinguish between single line and complex records. Complex records are indicated by a .CR { occurring before the first newline in the record. .IP For example, a correct format of a memory record looks like this: .nf .IP .C "// Space for A32 direct mapped window" .C "memory A32 {" .C "// address Name Card or Proc Options" .C "// Name" .C " align 256M:256M i7a32dw hp747i access=direct_map_to 0x0 \" .C " hints=SYSTEM_ONLY, PRIVATE" .C "}" .fi .IP An incorrect format looks like this: .nf .IP .C "// Space for A32 direct mapped window" .C "memory A32 " .C "{" .C "// address Name Card or Proc Options" .C "// Name" .C " align 256M:256M i7a32dw hp747i access=direct_map_to 0x0 \" .C " hints=SYSTEM_ONLY, PRIVATE" .C " }" .fi .TP .C "Syntax Error 102: Processor name expected" .IP A processor name is required for processor description records. The first character of the name must be one of .CR a \(mi z , .CR A \(mi Z , and .CR _ . The subsequent characters can be any of .CR a \(mi z , .CR A \(mi Z , .CR 0 \(mi 9 , and .CR _ . The name cannot contain more than 80 characters. .TP .C "Syntax Error 103: End address expected" .IP The .CR \- range indicator in a memory record indicates that the memory entity will be described as a starting and ending address pair. The ending address is missing. .IP An address must be an integer constant. See Syntax Error 120 for a definition of integer constants. .TP .C "Syntax Error 104: Unexpected input" .IP An unrecognizable sequence of ASCII values was found in the configuration file. .TP .C "Syntax Error 105: CPU/Card number must be between 0 and 31" .IP .CR vme_config allows no more than 32 different cards or processors in the system. .TP .C "Syntax Error 106: Card or processor has non-unique CPU/Card number" .IP The CPU/card number of this entity conflicts with that of a previously declared entity. .IP For third-party processors and cards, use a wildcard .RC ( * ). The wildcard tells .CR vme_config to choose a unique CPU/card number. .TP .C "Syntax Error 107: Undeclared memory entity name" .IP .CR vme_config could not find a memory entity, card, or processor name. Ensure you didn't make a typographical error in the name. .TP .C "Syntax Error 108: Address/size combination exceeds space" .IP This error occurs if the ending address exceeds the boundary of the current address space. .IP An address range consists of all of the addresses between the starting address and the ending address. If you specified a size instead of an ending address, the ending address can be determined by adding the entity's size (minus 1 byte) to the starting address. .IP Change the hard-coded address, then run .CR vme_config again. .TP .C "Syntax Error 109: '=' expected" .IP The assignment operator .CR ( = ) is used to assign a value to a parameter. This error indicates that the value cannot be assigned because the assignment operator is missing. .TP .C "Syntax Error 110: Access, permission, or hints field expected" .IP In memory records, only access, permission, or hint fields can follow the card or processor name field. .TP .C "Syntax Error 111: Card or processor name is expected" .IP Memory entities must always be associated with a card or processor that supplies the physical memory backing the entity. You must supply a card or processor name that was defined in another card or processor record. .IP CPU/card number in nonvolatile memory:number .TP .C "Syntax Error 113: No processor record associated with this CPU/card" .br .C "number" .IP .CR vme_config uses the CPU/card number stored in the computer's nonvolatile memory to determine which processor record in the configuration file to use. In this case, the stored CPU/card number does not correspond to a CPU/card number in any processor record. .TP .C "Syntax Error 114: Timeout value expected: [10|20|40|80|160|320|640|1000]" .IP Valid timeout values are 10, 20, 40, 80, 160, 320, 640, or 1000 (microseconds). This field must contain one of these values. .TP .C "Syntax Error 115: Arbitration mode expected: [PRI|RRS]" .IP The arbitration mode must be Priority (PRI) or Round Robin Select (RRS). .TP .C "Syntax Error 116: Request mode expected: [RWD|ROR|FAIR]" .IP The processor bus request mode must be one of the following: Release When Done (RWD), Release on Request (ROR), or Fair (FAIR). .TP .C "Syntax Error 117: Request level expected: [BR0|BR1|BR2|BR3]" .IP The processor bus request level must be one of the following: BR0, BR1, BR2, or BR3. .TP .C "Syntax Error 120: Incorrect integer constant." .IP Integer constants must be of the following form (shown as a regular expression): .RS .TP 25 .CR [0-9]* decimal notation .TP .CR 0[0-7]* octal notation .TP .CR 0x[0-9a-fA-F]* hexadecimal notation .RE .IP All integer constants may also have a .CR K , .CR M , or .CR G suffix. .CR K indicates the value is in kilobytes (1024 bytes), .CR M indicates megabytes (1,048,576 bytes), and .CR G indicates gigabytes (1,073,741,824 bytes). If no suffix is used, the value is assumed to be in bytes. Including any .CR K , .CR M , or .CR G multiplier, integer constants cannot exceed 4,294,967,294. .TP .C "Syntax Error 121: Interrupt request line(s) previously assigned" .IP An interrupt request line was assigned to more than one processor. Only one processor can be assigned to each interrupt request line. .TP .C "Syntax Error 122: Card name expected" .IP A card name is required for card description records. The first character of the name must be one of .CR a \(mi z , .CR A \(mi Z , and .CR _ . The subsequent characters can be any of .CR a \(mi z , .CR A \(mi Z , .CR 0 \(mi 9 , and .CR _ . The name cannot contain more than 80 characters. .TP .C "Syntax Error 123: Range or size indicator expected: ':' or '-'" .IP Address descriptions that begin with a starting address must have one of the following forms: .RS .TP 35 .IC starting_address : size e.g., .CR 0x00100000:8K .TP .IC starting_address \- ending_address e.g., .CR 0x00100000\-0x00101fff .RE .TP .C "Syntax Error 124: Size indicator expected: ':'" .IP The size indicator .RC ( : ) is expected because a size must always be associated with an alignment requirement in a memory record. .TP .C "Syntax Error 125: Memory range/size/alignment or '}' expected" .IP The syntax of a memory record is not correct. .CR vme_config found something other than expected. .TP .C "Syntax Error 126: Slot 1 keyword expected" .IP If a slot 1 function record is specified, only .CR timeout , .CR arb_mode , or .CR powerup_reset fields are allowed because these are the only Slot 1 functions that can be set on an HP processor (slot 1 card). .TP .C "Syntax Error 127: One or more address modifiers and '{' expected" .IP A memory record may contain multiple address modifiers. The address modifier list immediately follows the keyword memory and ends with the opening brace of the complex record. .IP This error indicates that something other than a recognized address modifier or list terminator appeared in the list. .TP .C "Syntax Error 128: Nonzero value for alignment required for nonzero size" .IP The alignment requirement of an entity must be a nonzero value if the size is nonzero. For shared memory, the alignment requirement should be rounded up to 4 KB. .IP Note that a zero size is equivalent to not specifying a memory requirement for an entity. This is useful with C preprocessor #defines. .TP .C "Syntax Error 129: Interrupt request line [1-7] or '}' expected" .IP This error indicates that .CR vme_config expects either a valid interrupt request line or a closing brace .RC ( } ) to close the interrupt record. The valid interrupt request lines are 1, 2, 3, 4, 5, 6, and 7. .TP .C "Syntax Error 130: Alignment boundary value expected" .IP The keyword align must be followed by an integer representing the alignment requirement. .IP See Syntax Error 120 for a definition of integer constants. .TP .C "Syntax Error 131: Size value expected" .IP A size value is expected here. This value must be an integer. See Syntax Error 120 for a definition of integer constants. .TP .C "Syntax Error 132: User defined subspace value [0x0-0xf] expected" .IP The subspaces within the user defined address modifier range must be specified. The value must be an integer in the range 0x0 through 0xf (0 to 15). See Syntax Error 120 for a definition of integer constants. .TP .C "Syntax Error 133: Permissions value expected" .IP An integer value is expected for the permission field. For information on permission setting, see the HP-RT system administration documentation. .IP See Syntax Error 120 for a definition of integer constants. .TP .C "Syntax Error 134: CPU/card number or wildcard expected" .IP All memory objects must have a unique CPU/card number. .IP For third-party processors and cards, use a wildcard .CR ( * ). The wildcard tells .CR vme_config to choose a unique CPU/card number. However, some HP-RT applications may require a specific CPU/card number. .TP .C "Syntax Error 135: Memory entity name expected" .IP All memory entity declarations must have names. .TP .C "Syntax Error 136: Undeclared processor name" .IP A processor name was referenced but was not previously declared in a processor record. .TP .C "Syntax Error 140: Exceeded the maximum string length of 80 characters" .IP The maximum length of a symbolic name is 80 characters. .TP .C "Syntax Error 141: Processor ID or Wildcard expected" .IP A processor record must have an ID or indicate that it does not by using a wildcard. .TP .C "Syntax Error 142: Processor requires an explicit CPU/Card number" .IP For HP processors, you must provide an explicit CPU/card number. .IP A CPU/card number is stored in the nonvolatile memory of every HP processor and should match the CPU/card number in the processor record. The number can be modified with the .CI vme_config\0\-N \0number option. .br .TP .C "Syntax Error 143: Maximum number of entities exceeded. Max is 100" .IP The maximum number of entities is 100. The maximum number of entities is different from the maximum CPU/Card number, because a card or processor can be referenced by multiple entities. .TP .C "Syntax Error 144: Illegal shared memory address modifier on HP CPU" .IP Address modifiers for shared memory regions provided by an HP processor's local memory cannot be any of the following: .IP .C A16 .C A24NP .C A24SP .C A32NP .C A32SP .IP In addition, HP Models 742 and 747 cannot use A24L or A32L. .TP .C "Syntax Error 145: Cannot allocate VME address space for slave mapper" .IP .CR vme_config could not locate an unused 1 MB piece of memory to allocate for the slave mapper. .IP In the .IR cfgfile , comment out a large A24 or A32 memory entity, then use the command .CI vme_config\0\-h \0address_modifier\f1, which allows you to view the empty locations in the affected memory space. .TP .C "Syntax Error 146: Shared memory entity not in same 1M window as previous" .IP All shared memory entities for a particular processor must be located within the same 1 MB window. This window begins on a 1 MB boundary. .TP .C "Syntax Error 147: Shared memory entity size cannot exceed 1M" .IP The total of all shared memory for a particular processor must be 1 MB or less in size. This error indicates that the size is larger than 1 MB. .TP .C "Syntax Error 148: Shared memory entity crosses a 1M boundary" .IP Shared memory cannot cross a 1 MB boundary, due to the constraints of the underlying shared memory mapping hardware. Change the location of the shared memory. .TP .C "Syntax Error 149: Shared memory entity cannot fit into 1M window" .IP There is not enough space left for this shared memory entity in the current shared memory window. .TP .C "Syntax Error 150: Duplicate proc, card, or memory entity name" .IP Processor, card, and memory entity names must be unique. .TP .C "Syntax Error 151: HP processor memory requirements not met" .IP HP Models 742 and 747 have the following memory requirements: .RS .TP 3 \(bu 1 KB on a 1-KB alignment boundary in A16, A24, and A32 space, .CR access=fifo . .TP \(bu 1 KB on a 1-KB alignment boundary in A16, A24, and A32 space, .CR access=loc_mon . .TP \(bu 256 MB on a 256-MB alignment boundary in A32 space, .CR "access=direct_map_to 0" . .RE .IP All other HP processors have the following memory requirements: .RS .TP \(bu 1 KB or 4 bytes on a 1-KB or 4-byte alignment boundary in A16, A24, and A32 space, .CR access=fifo . .TP \(bu 1 KB or 2 bytes on a 1-KB or 2-byte alignment boundary in A16, A24, and A32 space, .CR access=loc_mon . .RE .IP See .CR /sbin/lib/vme/example2.CFG for example records. .TP .C "Syntax Error 152: Only one Slot 1 function record allowed" .IP A configuration file can contain only one slot 1 function data record. This error indicates that more than one slot 1 record exists. .TP .C "Syntax Error 153: Conflicting memory declarations for memory entity" .IP This error indicates that a memory entity cannot be allocated as specified. For example, the specified address and size may exceed the maximum address of the address space. .TP .C "Syntax Error 156: keep_bus condition expected: [true|false]" .IP The .CR keep_bus value may be .CR TRUE or .CR FALSE . Set it to .CR FALSE (the default) unless you want a minor improvement in VME transfer rate at the expense of the performance of all other subsystems. .TP .C "Syntax Error 157: vme_sysreset condition expected: [true|false]" .IP The .CR vme_sysreset value may be .CR TRUE or .CR FALSE . The default is .CR TRUE , which causes the system to reset when a VME sysreset signal is received. .IP On HP Models 742 and 747, this option cannot be set .CR FALSE . This option does not apply to third party slot 1 controllers. .TP .C "Syntax Error 158: pb_reset condition expected: [true|false]" .IP The .CR pb_reset value may be .CR TRUE or .CR FALSE . The default is .CR TRUE , which causes the system to reset when the processor's reset button is pushed. .IP On HP Models 742 and 747, this option cannot be set .CR FALSE . This option does not apply to third party slot 1 controllers. .TP .C "Syntax Error 159: powerup_reset condition expected: [true|false]" .IP The .CR powerup_reset value may be .CR TRUE or .CR FALSE . The default is .CR TRUE , which causes the slot 1 HP processor to assert VME sysreset when HP-UX initializes the VME subsystem. This option does not apply to third party slot 1 controllers. .TP .C "Syntax Error 160: Access type expected:" .br .C "[fifo|loc_mon|direct_map_to PA_address]" .IP If the memory is supplied by an HP processor, four access types are supported: .CR slave , .CR fifo , .CR loc_mon , and .CR direct_map_to .IR PA_address . See "Memory Records" in .CR "HP-UX 10.20 VME Services Guide" . .IP For memory supplied by non-HP processors or VME cards, omit the .CR access= field. .TP .C "Syntax Error 161: Main memory address (direct map target) expected" .IP The PA address of the direct map target must be specified as .CI "access=direct_map_to " PA_address\f1. .TP .C "Syntax Error 162: Direct map can only be in A24 or A32 space" .IP Memory declared with .CI "access=direct_map_to " PA_address cannot be accessed in A16 space. .TP .C "Syntax Error 164: FIFO already assigned" .IP This HP processor's FIFO has already been assigned .RC ( access=fifo ) to another memory entity. .TP .C "Syntax Error 165: Location monitor already assigned" .IP This HP processor's location monitor has already been assigned .RC ( access=loc_mon ) to another memory entity. .TP .C "Syntax Error 166: A24 direct mapped window already assigned" .IP This HP processor's A24 direct mapped window has already been assigned .RC ( "access=direct_map_to " \f2PA_address\f1) to another memory entity. .TP .C "Syntax Error 167: A32 direct mapped window already assigned" .IP This HP processor's A32 direct mapped window has already been assigned .RC ( "access=direct_map_to " \f2PA_address\f1) to another memory entity. .TP .C "Syntax Error 168: FIFO must be 1K in size, aligned on a 1K boundary" .IP This message applies only to HP Models 742 and 747. Check the size and address alignment of the memory entity with .CR access=fifo . .TP .C "Syntax Error 169: FIFO must be 1K or 4 bytes in size," .br .C "aligned on a 1K or 4 byte boundary" .IP Check the size and address alignment of the memory entity with .CR access=fifo . .TP .C "Syntax Error 170: Location monitor must be 1K bytes in size," .br .C "aligned on a 1K boundary" .IP This message applies only to HP Models 742 and 747. Check the size and address alignment of the memory entity with .CR access=loc_mon . .TP .C "Syntax Error 171: Location monitor must be 1K or 2 bytes in size," .br .C "aligned on a 1K or 2 byte boundary" .IP Check the size and address alignment of the memory entity with .CR access=loc_mon . .TP .C "Syntax Error 172: A24 direct mapped window must be 0, 1M, 2M, 4M," .br .C "or 8M bytes in size, with natural alignment" .IP This message applies only to HP Models 742 and 747. Check the size and address alignment of the memory entity with .CI "access=direct_map_to " PA_address\f1. Both the VME address and the PA address must be aligned to the size of the window (natural alignment). .TP .C "Syntax Error 173: A24 direct map must be 0, 64K, 128K, 256K," .br .C "1M, 2M, 4M, or 8M bytes in size, with natural alignment" .IP Check the size and address alignment of the memory entity with .CI "access=direct_map_to " PA_address\f1. Both the VME address and the PA address must be aligned to the size of the window (natural alignment). .TP .C "Syntax Error 174: A24 direct mapped window target address must be zero" .IP This message applies only to HP Models 742 and 747. The A24 direct mapped window can only map to PA memory address 0 .RC ( "access=direct_map_to 0" ). .TP .C "Syntax Error 175: A24 direct mapped window target address" .br .C "must be naturally aligned" .IP The direct mapped window must be naturally aligned. For example, a 64 KB window must be aligned on a 64 KB boundary, a 2 MB window must be aligned on a 2 MB boundary, and so on. .TP .C "Syntax Error 176: A32 direct mapped window must be 256M bytes in size," .br .C "aligned on a 256M boundary" .IP This message applies only to HP Models 742 and 747. The A32 direct mapped window is a fixed 256 MB in size. .TP .C "Syntax Error 177: A32 direct mapped window must be 0, 64K, 128K, 256K," .br .C "1M, 2M, 4M, 8M, 16M, 32M, 64M, 128M, 256M, 512M," .C "or 1G bytes in size, with natural alignment" .IP Check the size and address alignment of the memory entity with .CI "access=direct_map_to " PA_address\f1. The direct mapped window must be naturally aligned. For example, a 64 KB window must be aligned on a 64-KB boundary, a 2 MB window must be aligned on a 2-MB boundary, and so on. .TP .C "Syntax Error 178: A32 direct mapped window target address must be zero" .IP This message applies only to HP Models 742 and 747. The A32 direct mapped window can only map to PA memory address 0 .RC ( "access=direct_map_to 0" ). .TP .C "Syntax Error 179: A32 direct mapped window target address" .br .C "must be naturally aligned" .IP The direct mapped window must be naturally aligned. For example, a 64 KB window must be aligned on a 64-KB boundary, a 2 MB window must be aligned on a 2-MB boundary, and so on. .TP .C "Syntax Error 180: DMA bus ownership time expected: 0 \- 51 (microseconds)" .IP The third field in the .CR dma_params must be the bus ownership time. The default value is 51 microseconds. .TP .C "Syntax Error 181: DMA bus wait time expected: 0 \- 51 (microseconds)" .IP The fourth field in the .CR dma_params must be the bus wait time. The default value is 0. .TP .C "Syntax Error 182: DMA option expected: [req_lv|req_mode|keep_bus]" .IP For information on the valid DMA options, see the .IR "HP-UX 10.20 VME Services Guide" . .br .TP .C "Syntax Error 183: VME address collision with memory entity name" .IP The memory entity on the indicated line number overlaps with the previously-defined memory entity name. Change the address specification of one or both memory entities. .TP .C "Syntax Error 184: Cannot allocate VME address space" .br .C "for this memory entity" .IP The memory entity on the indicated line number was declared with an .CI "align " alignment : size address specification. .CR vme_config could not find an unused VME address range in the specified address modifier codes for this memory entity. .IP Comment out the memory entity that caused the error. Then run .CI vme_config\0\-h \0address_modifier\f1, specifying the address modifier that the memory entity would use. Using the information that this command provides, try to rearrange other memory entities to create an unused address range for this memory entity. .TP .C "Syntax Error 185: Slave mapper collision with memory entity name" .IP The .IR cfgfile specified a shared memory entity. All shared memory entities must be located within the 1 MB piece of memory used by the slave mapper. When .CR vme_config tried to allocate a 1 MB piece for the slave mapper that included the shared memory entity, the slave mapper collided with a previously defined entity. .IP Change the address specification of the specified shared memory entity, the memory entity it collided with, or both. .TP .C "Internal Error 200: VME device special file ""/dev/vme2"" open failed" .IP .CR vme_config saves configuration information to the nonvolatile memory of the current system. It uses the .CR vme2 device driver. If this device driver is not in the current HP-UX kernel, the open of the device special file will fail. .IP To determine if the .CR vme2 driver is in the kernel, see "Verifying the vme2 Driver" in the .CR "HP-UX 10.20 VME Network Services Guide" . .br .TP .C "Internal Error 201: Memory allocation failure" .IP .CR vme_config must allocate various structures for its internal operation. This message indicates that a memory allocation has failed. .IP To fix this error, increase the value of the kernel parameter maxdsize. See the .I "HP-UX System Administration Tasks" manual for information on the .CR maxdsize parameter and changing kernel parameters with SAM. .TP .C "Internal Error 202: VME device special file ""/dev/vme2""" .br .C "cannot be created" .IP .CR vme_config saves configuration information to the nonvolatile memory of the current system. It uses the .CR vme2 device driver. .IP .CR vme_config will normally create the device special file if it does not exist. This error indicates such an attempt has failed. .IP Try removing the .CR /dev/vme2 file and running .CR vme_config again. .TP .C "Internal Error 203: VME device special file ""/dev/vme2"" ioctl failed" .IP .CR vme_config saves configuration information in the nonvolatile memory of the current system. It uses ioctls with the .CR vme2 device driver. This error indicates that one of those ioctls has failed. The most likely cause is that your version of .CR vme_config is not compatible with your version of HP-UX. .TP .C "Internal Error 204: Cannot open the input file" .IP The current configuration file cannot be opened. This may mean that .CR /sbin/lib/vme/vme.CFG has been removed, or that the file name specified by a .CR \-f option does not exist. Ensure that the file name does not contain a typographical error. .TP .C "Internal Error 205: Attempted execution of ""/lib/cpp"" failed" .IP .CR vme_config first passes the configuration file through the C preprocessor .CR cpp . In this case, execution of the preprocessor failed. Ensure that .CR /lib/cpp exists. .TP .C "Internal Error 206: ""/lib/cpp"" generated errors" .IP .CR vme_config first passes the configuration file through the C preprocessor .CR cpp . In this case, .CR cpp has generated errors of its own. These messages are displayed on your screen. For more information on .CR cpp error format and how to fix the errors, see .IR cpp (1). .TP .C "Internal Error 207: Cannot create ""/var/adm/vme/system.log""" .IP The current configuration is stored in the file .CR /var/adm/vme/system.log . This file could not be created. .TP .C "Internal Error 208: Cannot remove previous ""/var/adm/vme/system.log""" .IP The current configuration is stored in the file .CR /var/adm/vme/system.log . The previous version of this file could not be removed. .TP .C "Internal Error 209: Cannot remove ""/tmp/vmecfgpid""" .IP During execution, .CR vme_config uses a temporary file named .CI /tmp/vmecfg pid\f1, where .IR pid represents the process ID of .CR vme_config . If the configuration is successful, this file becomes .CR /var/adm/vme/system.log . The .CI /tmp/vmecfg pid file could not be removed. .TP .C "Internal Error 210: CPU/Card number must be between 0 and 31" .IP The CPU/card number specified with the .CR \-N option must be between 0 and 31. .RE .PP .SS Diagnostic Error Messages .PP These errors indicate conditions that you probably cannot fix yourself. Please contact your Hewlett-Packard support representative for assistance. .TP .C "Diagnostic Error 300: ""/lib/cpp"" created an unknown directive" .IP .CR vme_config first passes the configuration file through the C preprocessor .CR cpp . In this case, .CR cpp has generated an output directive that .CR vme_config cannot interpret. .TP .C "Diagnostic Error 301: Cannot close the input file" .IP The current configuration file cannot be closed. .TP .C "Diagnostic Error 302: ""/lib/cpp"" output file cannot be opened" .IP .CR vme_config first passes the configuration file through the C preprocessor .CR cpp . In this case, .CR vme_config cannot open the output file that .CR cpp created. .TP .C "Diagnostic Error 303: Cannot close device special file ""/dev/vme2""" .IP .CR vme_config saves configuration information to the nonvolatile memory of the current system. In this case, the device special file could not be closed. .\" $Header: volcopy.1m,v 72.6 94/11/29 13:27:56 ssa Exp $ .TA v .TH volcopy 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME volcopy, labelit (generic) \- copy a file system with label checking .SH SYNOPSIS .CR /usr/sbin/volcopy .RI [ options ]\& .I fsname .I special1 .I volname1 .I special2 .ifn .br .ifn \0\0\0\0 .I volname2 .PP .CR /usr/sbin/labelit .RI [ options ]\& .I special .RI [ fsname .I volume .RC [ \-n ]\|] .SH DESCRIPTION The .CR volcopy command makes a literal copy of the file system using a block size matched to the device. .SS Options .CR volcopy recognizes the following options: .RS .TP 15 .CI \-F \0FStype Specify the file system type on which to operate (see .IR fstyp (1M) and .IR fs_wrapper (5)). If this option is not included on the command line, then the file system type is determined from the file .CR /etc/fstab by matching .I special with an entry in that file. If there is no entry in .CR /etc/fstab , then the file system type is determined from the file .CR /etc/default/fs . .TP .CR \-a Invoke a verification sequence requiring a positive operator response instead of the standard delay before the copy is made. .TP .CI \-o \0specific_options Specify options specific to the file system type. .I specific_options is a list of suboptions and/or keyword/attribute pairs intended for an .IR FStype -specific module of the command. See the file system specific manual entries for a description of the .I specific_options that are supported, if any. .TP .CR \-s (default) Invoke the DEL-if-wrong verification sequence. .TP .CR \-V Echo the completed command line, but perform no other actions. The command line is generated by incorporating the user-specified options and arguments with other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .PP Other options are used with 9-track magnetic tapes: .RS .TP 15 .CI \-bpi \0density Bits per inch. .TP .CI \-feet \0size Size of reel in feet. .TP .CI \-reel \0num Beginning reel number for a restarted copy. .TP .CR \-buf Use double buffered I/O. .RE .PP The .CR volcopy command requests length and density information if they are not given on the command line and they are not recorded on an input tape label. If the file system is too large to fit on one reel, the .CR volcopy command prompts for additional reels. Labels of all reels are checked. Tapes can be mounted alternately on two or more drives. If the .CR volcopy command is interrupted, it asks if the user wants to quit or wants to escape to the command interpreter. In the latter case, other operations (such as executing the .CR labelit command) can be performed before returning to the .CR volcopy command by exiting the command interpreter. .TP 10 .I fsname The file system name on the device (e.g., .CR root ) being copied. .TP .I special The physical disk section or tape (e.g., .CR /dev/rdsk/1s3 or .CR /dev/rmt/c0t0d0BEST ). .TP .I volname The physical volume name; it should match the external sticker. Such label names are limited to six or fewer characters. The argument .I volname can be .CR - to use the existing volume name. .TP .I special1 The device from which the copy of the file system is being extracted. .TP .I volname1 The volume from which the copy of the file system is being extracted. .TP .I special2 The target device. .TP .I volname2 The target volume. .PP The .CR labelit command can be used to provide initial labels for unmounted disk or tape file systems. With the optional arguments omitted, the .CR labelit command prints current label values. The .CR \-n option provides for initial labeling of new tapes only (this destroys previous contents). The .CR \-F , .CR \-V , and .CR \-o options can be specified for the .CR labelit command. The behavior of the .CR \-F , .CR \-V , and .CR \-o options is similar to their behavior in the .CR volcopy command. .SH FILES .TP 20 .PD 0 .CR /etc/default/fs File that specifies the default file system type. .TP .CR /etc/fstab Static information about the file systems. .PD .SH SEE ALSO .RI volcopy_ FStype (1M), fs_wrapper(5). .\" .\" toc@\f3volcopy(1M)\f1:\0\0\f4volcopy\f1, \f4labelit\f1@@@copy file systems with label checking .\" toc@\f4labelit\f1 \- copy file systems with label checking@@@see \f3volcopy(1M)\f1 .\" .\" index@\f4volcopy\f1 \- copy file systems with label checking@@@\f3volcopy(1M)\f1 .\" index@\f4labelit\f1 \- copy file systems with label checking@@@\f3volcopy(1M)\f1 .\" index@copy file systems with label checking@@@\f3volcopy(1M)\f1 .\" index@file systems with label checking, copy@@@\f3volcopy(1M)\f1 .\" index@systems with label checking, copy file@@@\f3volcopy(1M)\f1 .\" index@label checking, copy file systems with@@@\f3volcopy(1M)\f1 .\" index@checking, copy file systems with label@@@\f3volcopy(1M)\f1 .\" .\" links@volcopy.1m labelit.1m .\" $Header: volcopy_hfs.1m,v 72.3 94/11/29 13:28:18 ssa Exp $ .TA v .TH volcopy_hfs 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME volcopy, labelit (hfs) \- copy an HFS file system with label checking .SH SYNOPSIS .CR /usr/sbin/volcopy .RI [ options ]\& .I fsname .I special1 .I volname1 .I special2 .ifn .br .ifn \0\0\0\0 .I volname2 .PP .CR /usr/sbin/labelit .RI [ options ]\& .I special .RI [ fsname .I volume .RC [ \-n ]\|] .SH DESCRIPTION The .CR volcopy command makes a literal copy of an HFS file system using a block size matched to the device. .SS Options .CR volcopy recognizes the following options: .RS .TP 15 .CR \-F\0hfs Specifies the HFS file system type. .TP .CR \-a Invoke a verification sequence requiring a positive operator response instead of the standard delay before the copy is made. .TP .CR \-s (default) Invoke the DEL-if-wrong verification sequence. .TP .CR \-V Echo the completed command line, but perform no other actions. The command line is generated by incorporating the user-specified options and arguments with other information derived from .CR /etc/fstab . This option allows the user to verify the command line. .RE .PP Other options are used with 9-track magnetic tapes: .RS .TP 15 .CI \-bpi \0density Bits per inch. .TP .CI \-feet \0size Size of reel in feet. .TP .CI \-reel \0num Beginning reel number for a restarted copy. .TP .CR \-buf Use double buffered I/O. .RE .PP The .CR volcopy command requests length and density information if they are not given on the command line and they are not recorded on an input tape label. If the file system is too large to fit on one reel, the .CR volcopy command prompts for additional reels. Labels of all reels are checked. Tapes can be mounted alternately on two or more drives. If the .CR volcopy command is interrupted, it asks if the user wants to quit or wants to escape to the command interpreter. In the latter case, other operations (such as executing the .CR labelit command) can be performed before returning to the .CR volcopy command by exiting the command interpreter. .TP 10 .I fsname The file system name on the device (e.g., .CR root ) being copied. .TP .I special The physical disk section or tape (e.g., .CR /dev/rdsk/1s3 or .CR /dev/rmt/c0t0d0BEST ). .TP .I volname The physical volume name; it should match the external sticker. Such label names are limited to six or fewer characters. The argument .I volname can be .CR - to use the existing volume name. .TP .I special1 The device from which the copy of the file system is being extracted. .TP .I volname1 The volume from which the copy of the file system is being extracted. .TP .I special2 The target device. .TP .I volname2 The target volume. .PP The .CR labelit command can be used to provide initial labels for unmounted disk or tape file systems. With the optional arguments omitted, the .CR labelit command prints current label values. The .CR \-n option provides for initial labeling of new tapes only (this destroys previous contents). The .CR \-F and .CR \-V options can be specified for the .CR labelit command. The behavior of the .CR \-F and .CR \-V options is similar to their behavior in the .CR volcopy command. .SH SEE ALSO fstyp(1M), volcopy(1M), fs_wrapper(5). .\" .\" toc@\f3volcopy_hfs(1M)\f1:\0\0\f4volcopy\f1, \f4labelit\f1@@@copy file systems with label checking .\" toc@\f4labelit\f1 \- copy file systems with label checking@@@see \f3volcopy_hfs(1M)\f1 .\" .\" index@\f4volcopy\f1 \- copy file systems with label checking@@@\f3volcopy_hfs(1M)\f1 .\" index@\f4labelit\f1 \- copy file systems with label checking@@@\f3volcopy_hfs(1M)\f1 .\" index@copy file systems with label checking@@@\f3volcopy_hfs(1M)\f1 .\" index@file systems with label checking, copy@@@\f3volcopy_hfs(1M)\f1 .\" index@systems with label checking, copy file@@@\f3volcopy_hfs(1M)\f1 .\" index@label checking, copy file systems with@@@\f3volcopy_hfs(1M)\f1 .\" index@checking, copy file systems with label@@@\f3volcopy_hfs(1M)\f1 .\" .\" links@volcopy_hfs.1m labelit_hfs.1m .\" $Header: volcopy_vxfs.1m,v 78.1 96/02/13 14:02:39 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA v .TH volcopy_vxfs 1M "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME volcopy, labelit (vxfs) \- copy a VxFS file system with label checking .SH SYNOPSIS .CR /usr/sbin/volcopy .RC [ "\-F vxfs" ] .RC [ \-V ] .RC [ \-a ] .RC [ \-s ] .br \0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0 .I fsname\0special1\0volname1\0special2\0volname2 .PP .C /usr/sbin/labelit .RC [ "\-F vxfs" ] .RC [ \-V ] .RC [ \-n ] .I special .RI [ "fsname volume" ] .SH DESCRIPTION The .C volcopy command makes a literal copy of a VxFS file system using a block size matched to the device. .SS Options .C volcopy recognizes the following options and command-line arguments: .RS .TP 15 .C \-F vxfs Specify the file-system type .RC ( vxfs ). .TP .C \-V Validate the command line options, however, the command is not executed. If the options specified are valid, the complete command line is echoed. If the options specified are not valid, an error message is printed. .TP .C \-a Normally, before copying the file system, .C volcopy delays so that the user can interrupt the copying if needed. This option invokes a verification sequence requiring a positive operator response instead of the standard delay. .TP .C \-s (default) Before copying the file system, prints a message and allows the user to interrupt the copy if needed. .RE .PP Other options are used with 9-track magnetic tapes: .RS .TP 15 .CI \-bpi \0density Bits per inch. .TP .CI \-feet \0size Size of reel in feet. .TP .CI \-reel \0num Beginning reel number for a restarted copy. .TP .C \-buf Use double buffered I/O. .RE .PP The .C volcopy command requests length and density information it is not given on the command line or if it is not recorded on an input tape label. If the file system is too large to fit on one reel, .C volcopy prompts for additional reels. Labels of all reels are checked. Tapes can be mounted alternately on two or more drives. If .C volcopy is interrupted, it asks if the user wants to quit or to escape to the command interpreter. In the later case, other operations (such as .CR labelit ) can be performed before returning to .C volcopy by exiting the command interpreter. .PP The .I fsname argument represents the file system name on the device (e.g., .CR root ) being copied. .PP .I special should be the physical disk section or tape (e.g., .C /dev/rdsk/c0t4d0s0 or .CR /dev/rmt/0mb ). .PP .I volname is the physical volume name; it should match the external sticker. Such label names are limited to six or fewer characters. The argument .I volname can be .C \- to use the existing volume name. .PP The arguments .I special1 and .I volname1 are the device and volume, respectively, from which the copy of the file system is being extracted. The arguments .I special2 and .I volname2 are the target device and volume, respectively. .PP The .C labelit command can be used to provide initial labels for unmounted disk or tape file systems. With the optional arguments omitted, .C labelit prints current label values. .C \-F and .C \-V options can be specified for .CR labelit . The behavior of .C \-F and .C \-V options are similar to the behavior of .CR volcopy . The option .C \-n of .C labelit provides for initial labeling of new tapes (this destroys previous contents). .SH SEE ALSO volcopy(1M), labelit(1M). .\" .\" toc@\f3volcopy_vxfs(1M)\f1:\0\0\f(CWvolcopy\f1, \f(CWlabelit\f1@@@copy VxFS file system with label checking .\" toc@\f(CWlabelit\f1:\0\0label for VxFS file system@@@see \f3volcopy_vxfs(1M)\f1 .\" .\" index@\f(CWvolcopy_vxfs\f1 \- copy VxFS file system with label checking@@@\f3volcopy_vxfs(1M)\f1 .\" index@\f(CWvolcopy\f1 \- copy VxFS file system with label checking@@@\f3volcopy_vxfs(1M)\f1 .\" .\" index@\f(CWlabelit\f1 \- label for VxFS file system@@@\f3volcopy_vxfs(1M)\f1 .\" index@\f1copy VxFS file system with label checking@@@\f3volcopy_vxfs(1M)\f1 .\" index@\f1VxFS file system with label checking@@@\f3volcopy_vxfs(1M)\f1 .\" index@\f1label checking, VxFS file system@@@\f3volcopy_vxfs(1M)\f1 .\" index@\f1checking VxFS file system with label@@@\f3volcopy_vxfs(1M)\f1 .\" .\" links@volcopy_vxfs.1m labelit_vxfs.1m .\" $Header: vtdaemon.1m,v 72.5 94/12/16 09:55:50 ssa Exp $ .TA v .TH vtdaemon 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vtdaemon \- respond to vt requests .SH SYNOPSIS .C vtdaemon .RC [ -g [ \f2ngateway\fP] ] .RC [ -n ] .I lan_device .IR lan_device \0... .SH DESCRIPTION .CR vtdaemon responds to requests from other systems (via local area network) made by .CR vt (see .IR vt (1)). .CR vtdaemon spawns a server to respond to each request that it receives. .SS Options .CR vtdaemon recognizes the following command-line options and arguments: .RS .TP 10 .CR -g [ \f2ngateway\fP ] Causes .CR vtdaemon to rebroadcast all requests received on one lan device to all other lan devices specified on the command line. The optional parameter .I ngateway specifies the maximum number of .I vtgateway servers that can be in operation concurrently. If .I ngateway is not specified, there is no limit on the number of vtgateway servers that can be in operation concurrently. .TP .CR -n Causes .I vtdaemon to ignore all requests that have come through a gateway. .RE .PP The remaining arguments are the full path names of lan devices that .I vtdaemon looks for requests on. If no lan devices are specified, the default lan device is used. The major number for this device must correspond to a IEEE 802.3 local area network device. .PP Another function of .CR vtdaemon is to create .I portals and service portal requests. A .I portal is a callout device that can be used by .CR uucico to communicate to another machine via local area network (see .IR uucico (1M)). Portals are created by .CR vtdaemon according to the configuration information found in the file .CR /etc/uucp/L-vtdevices . Each line in .CR L-vtdevices has the format: .IP [,] .PP For each line, .CR vtdaemon creates a portal named .I calldev in .CR /dev . Whenever this device is opened, .CR vtdaemon spawns a server that creates a connection to the system specified by .I nodename via the lan device specified. If no lan device is specified, the first one specified on the command line when .CR vtdaemon was started is used (or the default lan device is used if no lan devices were specified on the command line). .PP .CR vtdaemon should be terminated by sending signal .CR SIGTERM to it. When .CR vtdaemon receives this signal it removes all of the portals it created in .CR /dev before exiting. .SH DIAGNOSTICS Diagnostics messages produced by .CR vtdaemon are written to .CR /var/adm/vtdaemonlog . .SH WARNINGS .CR vtdaemon uses the Hewlett-Packard .CR LLA (Link Level Access) direct interface to the HP network drivers. .CR vtdaemon uses the multicast address .CR 0x01AABBCCBBAA . It should not be used or deleted by other applications accessing the network. .CR vtdaemon uses the following IEEE 802.3 .I sap (service access point) values: .CR 0x90 , .CR 0x94 , .CR 0x98 , .CR 0x9C , .CR 0xA0 , .CR 0xA4 , .CR 0xA8 , .CR 0xAC , .CR 0xB0 , .CR 0xB4 , .CR 0xB8 , .CR 0xBC , .CR 0xC0 , .CR 0xC4 , .CR 0xC8 , .CR 0xCC , .CR 0xD0 , and .CR 0xD4 . They should not be used by other applications accessing the network. .PP .SS Desktop HP-UX If your system has been installed with the Desktop HP-UX product, then both .CR ptydaemon and .CR vtdaemon will not be started by default. In order to start these daemons, change .I PTYDAEMON_START and .I VTDAEMON_START from a "0" to a "1" in the .CR /etc/rc.config.d/ptydaemon and .CR /etc/rc.config.d/vt files, respectively. The system must either be rebooted for these changes to take effect, or you can manually start both daemons by typing : .PP .RS 4 .CR /usr/sbin/ptydaemon .RE and .CR /usr/sbin/vtdaemon .I /dev/lan0 .PP where .I /dev/lan0 is the character special device file corresponding to the IEEE802.3 local area network device. .br .ne 8v .SH FILES .TP 30 .CR /var/adm/vtdaemonlog logfile used by .I vtdaemon. .PD 0 .TP .CR /dev/lan0 default lan device name. .PD .SH SEE ALSO vt(1), uucico(1M). .\" .\" index@\f4vtdaemon\f1 \- respond to \f4vt\f1 requests@@@\f3vtdaemon(1M)\f1 .\" index@respond to \f4vt\f1 requests from other systems@@@\f3vtdaemon(1M)\f1 .\" index@service \f4vt\f1 requests from other systems@@@\f3vtdaemon(1M)\f1 .\" index@\f4vt\f1 requests from other systems, respond to@@@\f3vtdaemon(1M)\f1 .\" index@virtual terminal requests from other systems, respond to@@@\f3vtdaemon(1M)\f1 .\" .\" toc@\f3vtdaemon(1M)\f1:\0\0\f4vtdaemon\f1@@@respond to \f4vt\f1 requests .\" $Header: vxdiskusg.1m,v 78.1 96/02/13 14:04:07 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA v .TH vxdiskusg 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vxdiskusg (vxfs) \- generate disk accounting data of VxFS file systems by user ID .SH SYNOPSIS .CR /usr/sbin/acct/vxdiskusg .RI [ \|options\| ] .RI [ \|file ...\| ] .SH DESCRIPTION .C vxdiskusg generates intermediate disk accounting information from data in .IR file , or the standard input if the .C -s flag is specified and .I file is omitted. .C vxdiskusg outputs lines on the standard output, one per user, in the following format: .IP .I "uid login #blocks" .PP where: .RS .TP 10 .I uid User's numerical user .SM ID, .TP .I login User's login name, and .TP .I #blocks Total number of disk blocks allocated to this user. .RE .PP Without the .C -s option, .I file ... is the special filename of device(s) containing file systems. .C vxdiskusg reads only the inodes of file systems for disk accounting. .SS Options .C vxdiskusg recognizes the following options: .RS .TP 15 .C -s Input data is already in .C vxdiskusg output format. .C vxdiskusg combines all lines for a single user into a single line. .TP .C -v verbose. Print a list on standard error of all files that are charged to no one. .TP .CI -i \0ignlist Ignore the data on those file systems whose file system name is in .IR ignlist . .I ignlist is a list of file system names, separated by commas or separated by spaces and enclosed within quotes. .C vxdiskusg compares each name in this list with the file system name stored in the .I volume name (see .CR volcopy_vxfs (1M)), if it exists. .TP .CI -p \0file Use .I file as the name of the password file to generate login names. .C /etc/passwd is used by default. .TP .CI -u \0file Write records to .I file of files that are charged to no one. Records consist of the special file name, the inode number, and the user .SM ID. .RE .PP The output of .C vxdiskusg is normally the input to .C acctdisk (see .IR acct (1M)) which generates total accounting records that can be merged with other accounting records. .C vxdiskusg is normally run in .C dodisk (see .IR acctsh (1M)). .SH EXAMPLES The following generates daily disk accounting information for the file systems on these disks: .nf .IP .C "for i in /dev/vg00/lvol1 /dev/vg00/lvol6 /dev/vg00/lvol7; do" .C " vxdiskusg $i > dtmp.`basename $i` &" .C done .C wait .C "vxdiskusg -s dtmp.* | sort +0n +1 | acctdisk > disktacct" .fi .SH FILES .TP 20 .C /etc/passwd used for user-\c .SM ID\c -to-login-name conversions .SH SEE ALSO .CR acct (1M), .CR acctsh (1M), .CR volcopy (1M), .CR volcopy_vxfs (1M), .CR acct (4), .CR diskusg (1M). .SH STANDARDS CONFORMANCE .CR vxdiskusg ": SVID2, SVID3" .\" .\" index@\f(CWvxdiskusg\f1 \- generate disk accounting data of VxFS file system by user \s-1ID\s+1@@@\f3vxdiskusg(1M)\f1 .\" index@\f1disk usage, generate disk accounting data of VxFS file system by user \s-1ID\s+1@@@\f3vxdiskusg(1M)\f1 .\" index@\f1disk accounting data of VxFS file system , disk usage by user \s-1ID\s+1@@@\f3diskusg(1M)\f1 .\" index@\f1accounting data of VxFS file system, disk usage by user \s-1ID\s+1@@@\f3vxdiskusg(1M)\f1 .\" index@\f1VxFS file system, disk accounting data by user \s-1ID\s+1@@@\f3vxdiskusg(1M)\f1 .\" .\" toc@\f3vxdiskusg(1M)\f1:\0\0\f(CWvxdiskusg\f1@@@generate disk accounting data of VxFS file system by user ID .\" .\" $Header: vxdump.1m,v 78.1 96/02/13 14:07:01 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1996 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .\" Copyright (c) 1980, 1991, 1993 .\" Regents of the University of California. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .so /usr/share/lib/macros/vxfs.an .TA v .TH vxdump 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vxdump, rvxdump (vxfs) \- incremental file system dump, local or across network .SH SYNOPSIS .CR /usr/sbin/vxdump .RC [ \-nuwW ] .RC [ \-0123456789 ] .RC [ \-f .IR file_name ] .RS .RC [ \-d .IR density ] .RC [ \-s .IR size ] .RC [ \-T .IR time ] .RC [ \-b .IR block_size ] .RE .RS .RC [ \-B .IR records ] .I filesystem .RE .PP .C /usr/sbin/rvxdump .RC [ \-nuwW ] .RC [ \-0123456789 ] .RC [ \-f .IR file_name ] .RS .RC [ \-d .IR density ] .RC [ \-s .IR size ] .RC [ \-T .IR time ] .RC [ \-b .IR block_size ] .RE .RS .RC [ \-B .IR records ] .I filesystem .RE .PP .C /usr/sbin/vxdump .RI [ option .RI [ argument " ...]" .IR filesystem ] .PP .C /usr/sbin/rvxdump .RI [ option .RI [ argument " ...]" .IR filesystem ] .SH DESCRIPTION .CR vxdump and .CR rvxdump copy to magnetic tape all files in the .CR vxfs .I filesystem that have been changed after a certain date. This information is derived from the files .CR /var/adm/dumpdates and .CR /etc/fstab . .PP .CR vxdump and .CR rvxdump support both .IR getopt (3C) and traditional .CR dump command line invocations as shown above. The original .CR dump command line style is supported for compatibility with previous versions of .CR vxdump and for synonymy with the existing .CR dump program used for hfs file systems. For the traditional command line style, .I option consists of characters from the set .CR 0123456789bBdfnsTuWw without any intervening white space. .PP On most devices .C vxdump can detect end-of-media and prompt for the media to be changed, so it is not necessary to specify the size of the device. However, if the dump will require multiple tapes and the tapes are to be read using an older version of .CR vxrestore , or if the tape device handles end-of-media in a way that .C vxdump doesn't understand, then the size of the device must be specified using either the .CR \-B option or a combination of the .CR \-d " and " \-s options. .SS Options .RS .TP 10 .CI \- number Where .I number is in the range [0\-9]. This number is the dump level. All files modified since the last date stored in the file .CR /var/adm/dumpdates for the same file system at a lesser dump level will be dumped. Thus, the option .CR \-0 causes the entire file system to be dumped. If no date is determined by the level, the beginning of time is assumed. .TP .CI \-B " records" The number of logical records per volume. The .CR vxdump logical record size is 1024 bytes. .I records can also be specified with a suffix to indicate a unit of measure other than 1024 bytes. A .CR k , .CR m , or .CR g can be appended to the number to indicate that the value is in kilobytes, megabytes, or gigabytes, respectively. This option overrides the calculation of tape size based on length and density. .TP .CI \-b " block_size" The blocking factor is taken from the .I block_size option argument. (default is 63 if .C \-b is not specified). Block size is defined as the logical record size times the blocking factor. .CR vxdump writes logical records of 1024 bytes. Older versions of .C vxdump used a blocking factor of 10 for tapes with densities less than 6250 BPI, and 32 for tapes with densities of 6250 BPI or greater. .CR vxrestore will dynamically determine the blocking factor. .TP .CI \-d " density" The density of the tape (expressed in BPI). This is used in calculating the amount of tape used per tape reel. If the .C \-s option is specified, a default density value of 1600 is assumed a for a reel tape. .TP .CI \-f " file_name" Place the dump on the file .I file_name instead of the tape. If the name of the file is .CR \- , .CR vxdump writes to the standard output. This option can be of the form .IC machine : device to specify a tape device on a remote machine. .TP .C \-n Whenever .CR vxdump requires operator attention, notify all users in group .CR operator by means similar to that described by .IR wall (1). .TP .CI \-s " size" .I size is the size of the dump tape, specified in feet. When the specified size is reached, .CR vxdump waits for reels to be changed. If the .C \-d option is specified, a default size value of 2300 is assumed a for a reel tape. .TP .C \-u If the dump completes successfully, write on file .CR /var/adm/dumpdates the date when the dump started. This file records a separate date for each file system and each dump level. The format of .CR /var/adm/dumpdates is user-readable and consists of one free-format record per line: file system name, increment level and dump date in .IR ctime (3C) format. The file .CR /var/adm/dumpdates can be edited to change any of the fields if necessary. .TP .CI \-T " date" Use the specified date as the starting time for the dump instead of the time determined from looking in .CR /var/adm/dumpdates . The format of .I date is the same as that of .IR ctime (3C) This option is useful for automated dump scripts that wish to dump over a specific period of time. The .C \-T option is mutually exclusive with the .C \-u option. .TP .C \-W For each file system in .CR /var/adm/dumpdates , print the most recent dump date and level, indicating which file systems should be dumped. If the .CR \-W option is set, all other options are ignored and .CR vxdump exits immediately. .TP .C \-w Operates like .CR W , but prints only file systems that need to be dumped. .RE .PP If no arguments are given, the options are assumed to be .CR \-9u and a default file system is dumped to the default tape. .SS Operator Interaction .PP .CR vxdump requires operator intervention for any of the following conditions: .RS .TP 3 \(bu end of tape, .PD 0 .TP \(bu end of dump, .TP \(bu tape-write error, .TP \(bu tape-open error, or .TP \(bu disk-read error (if errors exceed threshold of 32). .RE .PD .PP In addition to alerting all operators implied by the .C \-n option, .CR vxdump interacts with the control terminal operator by posing questions requiring .CR yes or .CR no answers when it can no longer proceed or if something is grossly wrong. .PP Since making a full dump involves considerable time and effort, .CR vxdump establishes a checkpoint at the start of each tape volume. If, for any reason, writing that volume fails, .CR vxdump will, with operator permission, restart from the checkpoint after the old tape has been rewound and removed and a new tape has been mounted. .PP .CR vxdump periodically reports information to the operator, including estimates (typically low) of the number of blocks to write, the number of tapes it will require, time needed for completion, and the time remaining until tape change. The output is verbose to inform other users that the terminal controlling .CR vxdump is busy and will be for some time. .SS Compatibility The dump tape format is independent of the VxFS disk layout. A dump of a file system with the Version 3 disk layout can be restored on a file system using the Version 2 disk layout or even a file system of another file system type, with the following exceptions: .TP 3 \(bu Files larger than 2 Gbyte cannot be restored by earlier versions of .CR vxrestore . If a file larger than 2 Gbyte is encountered, .C vxrestore will skip the file and produce the diagnostic: .RS 1i .CI "Resync restore, skipped " num " blocks" .RE .TP \(bu Files larger than 2 Gbyte cannot be restored on a file system that does not support large files (see .CR mount_vxfs(1m) ). .TP \(bu A file with a large .I uid (user ID of the file owner) or large .I gid (group ID of the file owner) cannot be restored correctly on a file system that does not support large IDs. Instead, the owner and/or group of the file will be that of the user invoking .CR vxrestore . (A large ID is a value grater than 65535. The VxFS Version 2 disk layout does not support lage IDs). .TP \(bu Files with VxFS extent attributes (see setext(1m)) cannot be restored on a file system of a type that does not support extent attributes. .PP If you use .CR vxdump to produce a dump intended for an earlier version of .CR vxrestore, and if the dump requires multiple tapes, you should use the .CR -s , .CR -d , or .CR -B option. .PP Dumps produced by older versions of .CR vxdump can be read by the current version of .CR vxrestore. .ig Tapes produced by .CR vxdump on other platforms can also be read by .CR vxrestore , provided they are not from a version of .CR vxdump more recent the version of .CR vxrestore in use. .. .SH NOTES Dumps should be performed with the file system unmounted or the system in single-user environment (see .CR init (1M)) to insure a consistent dump. If the VxFS Advanced package is installed, the dump can be performed in the multi-user environment using a snapshot file system with the online backup facility (see the .CI snapof=file option of .CR mount_vxfs (1M)). .PP Up to 32 read errors on the file system are ignored. .PP Each reel requires a new process; thus parent processes for reels already written remain until the entire tape is written. .PP .CR vxdump creates a server, .CR /usr/sbin/rmt , on the remote machine to access the tape device. .PP .ig The .CR vxdump and .CR vxrestore commands are fully interoperable with the .CR dump and .CR restore commands: tapes created by .CR vxdump can be restored by .CR restore ; and tapes created by .CR dump can be restored by .CR vxrestore . .. .SH EXAMPLES In the following example, assume that the file system .CR /mnt is normally attached to the file tree at the root directory, .RC ( / ). .PP This example causes the entire file system .RC ( /mnt ) to be dumped on .CR /dev/rmt/0m and specifies that the the size of the tape is 2 gigabytes. .IP .C vxdump -0 -B 2g -f /dev/rmt/0m /mnt .PP Or, using the traditional command line syntax and specifying the tape size in logical records: .IP .C vxdump 0Bf 2097152 /dev/rmt/0m /mnt .PP where the option argument ``2097152'' goes with the option letter .C B as it is the first option letter that requires an option argument, and where the option argument ``/dev/rmt/0m'' goes with the option letter .C f as it is the second option letter that requires an option argument. .SH AUTHOR .C vxdump and .C rvxdump are based on the .CR dump and .CR rdump programs from the 4.4 Berkeley Software Distribution, developed by the the University of California, Berkeley, and its contributors. .SH FILES .PD 0 .TP 30 .C /dev/rdsk/c0t0d0 Default file system to dump from. .TP .C /dev/rmt/0m Default tape unit to dump to. .TP .C /var/adm/dumpdates New format-dump-date record. .TP .C /etc/fstab Dump table: file systems and frequency. .TP .C /etc/mnttab Mounted file system table. .TP .C /etc/group Used to find group .CR operator . .PD .SH SEE ALSO rmt(1M), vxrestore(1M), fstab(4). .\" .\" toc@\f3vxdump(1M)\f1:\0\0\f(CWrvxdump\f1, \f(CWvxdump\f1@@@incremental file system dump, local or across network\f1 .\" toc@\f(CWrvxdump\f1:\0\0incremental file system dump across network@@@\f1see \f3vxdump(1M)\f1 .\" .\" index@\f(CWvxdump\f1 \- local incremental file system dump@@@\f3vxdump(1M)\f1 .\" index@\f(CWrvxdump\f1 \- incremental file system dump across network@@@\f3vxdump(1M)\f1 .\" index@\f1dump, incremental file system, local@@@\f3vxdump(1M)\f1 .\" index@\f1dump, incremental file system, across network@@@\f3vxdump(1M)\f1 .\" index@\f1file system, dump across network@@@\f3vxdump(1M)\f1 .\" index@\f1file system, local dump@@@\f3vxdump(1M)\f1 .\" index@\f1local, dump of file system@@@\f3vxdump(1M)\f1 .\" index@\f1network, dump of file system across@@@\f3vxdump(1M)\f1 .\" .\" links@vxdump.1m rvxdump.1m .\" $Header: vxrestore.1m,v 78.1 96/02/13 14:07:35 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" (c) Copyright 1996 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .\" Copyright (c) 1980, 1991, 1993 .\" Regents of the University of California. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .so /usr/share/lib/macros/vxfs.an .TA v .TH vxrestore 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vxrestore, rvxrestore (vxfs) \- restore file system incrementally, local or across network .SH SYNOPSIS .CR /usr/sbin/vxrestore .RC [ \-rRtxihmvy ] .RC [ \-s .IR number ] .RS .RC [ \-b .IR block_size ] .RC [ \-e .IR opt ] .RC [ \-f .IR file ] .RI [ \|file_name \0...\|] .RE .PP .C /usr/sbin/rvxrestore .RC [ \-rRtxihmvy ] .RC [ \-s .IR number ] .RS .RC [ \-b .IR block_size ] .RC [ \-e .IR opt ] .RC [ \-f .IR file ] .RI [ \|file_name \0...\|] .RE .PP .C /usr/sbin/vxrestore .I key .RI [ \|file_name \0...\|] .PP .C /usr/sbin/rvxrestore .I key .RI [ \|file_name \0...\|] .SH DESCRIPTION .C rvxrestore is another name for .CR vxrestore . .C vxrestore reads tapes previously dumped by the .C vxdump or .C rvxdump command (see .IR vxdump (1M) ). .PP .CR vxrestore and .CR rvxrestore support both .IR getopt (3C) and traditional .CR restore command line invocations as shown above. The original .CR restore command line style is supported for compatibility with previous versions of .CR vxrestore and for synonymy with the existing .CR restore program used for hfs file systems. .PP For the original .CR restore command line style, actions taken are controlled by the .I key argument where .I key is a string of characters containing exactly one function letter from the group .CR rRxtsi , and zero or more function modifiers from the group .CR befhmvy . One or more .I file_name arguments, if present, are file or directory names specifying the files that are to be restored. Unless the .C h modifier is specified (see below), the appearance of a directory name refers to the files and (recursively) subdirectories of that directory. .SS Options .RS .TP 6 .CR \-r Read the tape and load into the current directory. .C \-r should be used only after careful consideration, and only to restore a complete dump tape onto a clear file system or to restore an incremental dump tape after a full-level zero restore. Thus, .RS .IP .nf .C /usr/sbin/newfs -F vxfs /dev/rdsk/c0t0d0 .C /usr/sbin/mount -F vxfs /dev/dsk/c0t0d0 /mnt .C cd /mnt .C vxrestore -r .fi .RE .IP is a typical sequence to restore a complete dump. Another .C vxrestore can then be performed to restore an incremental dump on top of this. Note that .C vxrestore leaves a file .C restoresymtab in the root directory of the file system to pass information between incremental .C vxrestore passes. This file should be removed when the last incremental tape has been restored. .TP .C \-R Resume a full restore. .C vxrestore restarts from a checkpoint it created during a full restore (see .C \-r above). It requests a particular tape of a multi-volume set on which to restart a full restore. This provides a means for interrupting and restarting a multi-volume .CR vxrestore . .TP .C \-x Extract named files from the tape. If the named file matches a directory whose contents had been written onto the tape, and the .C \-h option is not specified, the directory is recursively extracted. The owner, modification time, and mode are restored (if possible). If no .I file_name argument is given, the root directory is extracted, which results in the entire contents of the tape being extracted, unless .C \-h has been specified. .TP .C \-t Names of .I file_names, as specified on the command line, are listed if they occur on the tape. If no .I file_name is given, the root directory is listed, which results in the entire content of the tape being listed, unless .C \-h has been specified. .TP .CI \-s number .I number is used as the dump file number to recover. This is useful if there is more than one dump file on a tape. .TP .C \-i This option allows interactive restoration of files from a dump tape. After reading in the directory information from the tape, .C vxrestore provides a shell-like interface that allows the user to move around the directory tree selecting files to be extracted. The available commands are given below; for those commands that require an argument, the default is the current directory. .RS .RS .TP 15 .CR add \0[\f2arg\fP] The current directory or specified argument is added to the list of files to be extracted. If a directory is specified, it and all its descendents are added to the extraction list (unless the .C h key is specified on the command line). File names on the extraction list are displayed with a leading .C \(** when listed by .CR ls . .TP .CR cd \0[\f2arg\fP] Change the current working directory to the specified argument. .TP .CR delete \0[\f2arg\fP] The current directory or specified argument is deleted from the list of files to be extracted. If a directory is specified, it and all its descendents are deleted from the extraction list (unless .C h is specified on the command line). The most expedient way to extract most files from a directory is to add the directory to the extraction list, then delete unnecessary files. .TP .C extract All files named on the extraction list are extracted from the dump tape. .C vxrestore asks which volume the user wants to mount. The fastest way to extract a few files is to start with the last volume, then work toward the first volume. .TP .C help List a summary of the available commands. .TP .CR ls \0[\f2arg\fP] List the current or specified directory. Entries that are directories are displayed with a trailing .CR / . Entries marked for extraction are displayed with a leading .CR \(** . If the verbose key is set, the inode number of each entry is also listed. .TP .C pwd Print the full pathname of the current working directory. .TP .C quit .C vxrestore immediately exits, even if the extraction list is not empty. .TP .C set-modes Set the owner, modes, and times of all directories that are added to the extraction list. Nothing is extracted from the tape. This setting is useful for cleaning up after a restore aborts prematurely. .TP .C verbose The sense of the .C v modifier is toggled. When set, the verbose key causes the .C ls command to list the inode numbers of all entries. It also causes .C vxrestore to print out information about each file as it is extracted. .RE .RE .RE The following options can be used in addition to the letter that selects the primary function desired: .RS .TP 6 .CI \-b " block_size" Specify the block size of the tape in Kbytes. If the .C \-b option is not specified, .C vxrestore will determine the tape block size dynamically. [This option is exists to preserve backwards compatibility with previous versions of .CR vxrestore .] .TP .CI \-e " opt" Specify how to handle a .I vxfs file that has extent attribute information. Extent attributes include reserved space, a fixed extent size, and extent alignment. It may not be possible to preserve the information if the destination file system does not support extent attributes, has a different block size than the source file system, or lack free extents appropriate to satisfy the extent attribute requirements. Valid values for .I opt are: .RS .TP 10 .C warn Issue a warning message if extent attribute information cannot be kept (the default). .TP .C force Fail to restore the file if extent attribute information cannot be kept. .TP .C ignore Ignore extent attribute information entirely. .RE .TP .CI \-f " file" Specify the name of the archive instead of .CR /dev/rmt/0m . If the name of the file is .CR \- , .C vxrestore reads from standard input. Thus, .C vxdump and .C vxrestore can be used in a pipeline to vxdump and vxrestore a file system with the command .RS .IP .C "vxdump 0f \- /usr | (cd /mnt; vxrestore xf \-) .RE .IP An archive name of the form .IC machine : device can be used to specify a tape device on a remote machine. .TP .C \-h Extract the actual directory, rather than the files to which it refers. This prevents hierarchical restoration of complete subtrees. .TP .C \-m Extract by inode numbers rather than by file name. This is useful if only a few files are being extracted and one wants to avoid regenerating the complete pathname to the file. .TP .C \-v Type the name of each file restored, preceded by its file type. Normally .C vxrestore does its work silently; the .C \-v option specifies verbose output. .TP .C \-y Do not ask whether to abort the operation if .C vxrestore encounters a tape error. Normally .C vxrestore asks whether to continue after encountering a read error. With this option, .C vxrestore continues without asking, attempting to skip over the bad tape block(s) and continue as best it can. .RE .PP .C vxrestore creates a server, .CR /usr/sbin/rmt , on the remote machine to access the tape device. .SH DIAGNOSTICS .PP .C vxrestore complains if a read error is encountered. If the .C \-y option has been specified, or the user responds .CR y , .C vxrestore attempts to continue the restore. .PP If the dump extends over more than one tape, .C vxrestore asks the user to change tapes. If the .C \-x or .C \-i option has been specified, .C vxrestore also asks which volume the user wants to mount. The fastest way to extract a few files is to start with the last volume and work towards the first volume. .PP There are numerous consistency checks that can be listed by .CR vxrestore . Most checks are self-explanatory or can ``never happen''. Here are some common errors: .RS .TP .IC filename ": not found on tape" The specified file name was listed in the tape directory but not found on the tape. This is caused by tape read errors while looking for the file, and from using a dump tape created on an active file system. .TP .CI "expected next file " inumber ", got " inumber A file not listed in the directory showed up. This can occur when using a dump tape created on an active file system. Dumps should be performed with the file system unmounted or the system in single-user environment (see .CR init (1M)) to insure a consistent dump. If the VxFS Advanced package is installed, the dump can be performed in the multi-user environment using a snapshot file system with the online backup facility (see the .CI snapof=file option of .CR mount_vxfs (1M)). .TP .C "Incremental tape too low" When doing an incremental restore, a tape that was written before the previous incremental tape, or that has too low an incremental level has been loaded. .TP .C "Incremental tape too high" When doing an incremental restore, a tape that does not begin its coverage where the previous incremental tape left off, or that has too high an incremental level has been loaded. .TP .CI "Tape read error while restoring " filename" .PD 0 .TP .CI "Tape read error while skipping over inode " inumber" .TP .C "Tape read error while trying to resynchronize" A tape-read error has occurred. If a file name is specified, the contents of the restored files are probably partially wrong. If .C vxrestore is skipping an inode or is trying to resynchronize the tape, no extracted files are corrupted, although files may not be found on the tape. .PD .TP .CI "Resync restore, skipped " num " blocks" After a tape-read error, .C vxrestore may have to resynchronize itself. This message indicates the number of blocks skipped over. This message will also be generated by older versions of .C vxrestore while skipping over files larger than 2 Gbyte dumped by a more recent version of .CR vxdump . .SH NOTES If the dump tape contains files larger than 2 Gbyte, and if the file system being restored to does not support files larger than 2 Gbyte, the file will not be restored correctly. Instead it will be truncated to 2 Gbyte. .PP A file with a large .I uid (user ID of the file owner) or large .I gid (group ID of the file owner) cannot be restored correctly on a file system that does not support large IDs. Instead, the owner and/or group of the file will be that of the user invoking .CR vxrestore . (A large ID is a value grater than 65535. The VxFS Version 2 disk layout does not support lage IDs). .PP Dumps produced by older versions of .CR vxdump can be read by the current version of .CR vxrestore . .ig Dumps produced by .CR vxdump on other platforms can also be read by .CR vxrestore , provided they are not from a version of .CR vxdump more recent the version of .CR vxrestore in use. .. .PP .C vxrestore can restore files to a file system of a type other than VxFS. If the file system type does not support extent attributes, than the extent attributes will not be restored (see the .C -e option). .PP .SH WARNINGS .C vxrestore can get confused when doing incremental restores from dump tapes that were made on active file systems. .PP A level-zero dump (see the .CR vxdump (1M) manual page) must be done after a full restore. Since .C vxrestore runs in user code, it has no control over inode allocation; thus a full dump must be done to get a new set of directories reflecting the new inode numbering, even though the contents of the files are unchanged. .SH AUTHOR .CR vxrestore and .CR rvxrestore are based on the .CR restore program distributed in the 4.4 Berkeley Software Distribution, developed by the the University of California, Berkeley, and its contributors. .SH FILES .TP 20 .C /dev/rmt/0m default tape drive .TP .C /tmp/rstdr\(** file containing directories on the tape .TP .C /tmp/rstmd\(** owner, mode, and time stamps for directories .TP .C ./restoresymtab information passed between incremental restores .SH SEE ALSO .CR vxdump (1M), .CR extendfs_vxfs (1M), .CR fsadm_vxfs (1M), .CR mkfs (1M), .CR mount (1M), .CR newfs (1M), .CR rmt (1M). .\" toc@\f3vxrestore(1M)\f1:\0\0\f(CWvxrestore\f1, \f(CWrvxrestore\f1@@@restore file system incrementally, local or across network\f1 .\" toc@\f(CWrvxrestore\f1:\0\0 restore file system incrementally across network\f1@@@see \f3vxrestore(1M)\f1 .\" index@\f(CWvxrestore\f1 \- restore file system incrementally, local or across network@@@\f3vxrestore(1M)\f1 .\" index@\f(CWrvxrestore\f1 \- restore file system incrementally across network@@@\f3vxrestore(1M)\f1 .\" index@restore file system incrementally, local or across network@@@\f3vxrestore(1M)\f1 .\" index@file system, restore incrementally, local or across network @@@\f3vxrestore(1M)\f1 .\" index@local file system, restore incrementally@@@\f3vxrestore(1M)\f1 .\" index@remote file system, restore incrementally@@@\f3rvxrestore(1M)\f1 .\" links@vxrestore.1m rvxrestore.1m .\" $Header: wall.1m,v 74.2 95/04/04 14:52:17 ssa Exp $ .TA w .TH wall 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wall, cwall \- write message to all users .SH SYNOPSIS .CR /usr/sbin/wall .RC [ -g\c .IR groupname ] .RI [ file ] .PP .CR /usr/sbin/cwall .RC [ -g\c .IR groupname ] .RI [ file ] .SH DESCRIPTION Without arguments, the .CR wall command reads a message from standard input until end-of-file. Then it sends this message to all currently logged-in users preceded by: .IP .CR "Broadcast Message from " ... .PP If the .CI -g groupname option is specified, .CR wall sends the message to all currently logged-in .I groupname members (as specified in .CR /etc/group ) preceded by: .IP .CR "Broadcast Message from " ... " to group" .I groupname .PP If .I file is specified, .CR wall reads .I file instead of standard input. .PP .CR wall is typically used to warn all users prior to shutting down the system. .PP In a diskless cluster, .C cwall can be used to write to all users in the cluster. .PP The sender must have appropriate privileges to override any protections the users may have invoked (see .IR mesg (1)). .PP .CR wall has timing delays, and takes at least 30 seconds to complete. .PP You must have appropriate privileges to override any protections users may have invoked (see .IR mesg (1)). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multibyte character code sets are supported. .SH DIAGNOSTICS .PP .CR "Cannot send to " ... .IP The open on a user's tty file failed. .SH AUTHOR .CR wall was developed by AT&T and HP. .SH FILES .CR /dev/tty* .SH SEE ALSO mesg(1), write(1). .SH STANDARDS CONFORMANCE .CR wall ": SVID2, SVID3, XPG2, XPG3" .\" .\" index@\f4wall\f1 \- write message to all users@@@\f3wall(1M)\f1 .\" index@\f4cwall\f1 \- write message to all users in a cluster@@@\f3wall(1M)\f1 .\" index@\f1broadcast message simultaneously to all users@@@\f3wall(1M)\f1 .\" index@\f1message, broadcast simultaneously to all users@@@\f3wall(1M)\f1 .\" index@\f1send a message simultaneously to all users@@@\f3wall(1M)\f1 .\" index@\f1write a message simultaneously to all users@@@\f3wall(1M)\f1 .\" index@\f1cluster, write a message simultaneously to all users@@@\f3wall(1M)\f1 .\" .\" toc@\f3wall(1M)\f1:\0\0\f4cwall\f1, \f4wall\f1@@@write message to all users .\" toc@\f4cwall\f1:\0\0write message to all users in cluster@@@\f1see \f3wall(1M)\f1 .\" .\" links@wall.1m cwall.1m .\" .\" $Header: whodo.1m,v 72.5 94/11/14 15:23:46 ssa Exp $ .TA w .TH whodo 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME whodo \- which users are doing what .SH SYNOPSIS .C /usr/sbin/whodo .SH DESCRIPTION The .CR whodo command produces merged, reformatted, and dated output from the .CR who and .CR ps commands (see .IR who (1) and .IR ps (1)). .SH EXTERNAL INFLUENCES .SS Environment Variables .C LC_COLLATE determines the order in which the output is sorted. .PP If .CR LC_COLLATE is not specified in the environment or is set to the empty string, the value of .CR LANG is used as a default. If .CR LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, .CR whodo behaves as if all internationalization variables are set to ``C'' (see .IR environ (5)). .SH FILES .C /etc/passwd .SH SEE ALSO ps(1), who(1). .SH STANDARDS CONFORMANCE .CR whodo ": SVID2, SVID3" .\" .\" index@users: list current users and what they are doing@@@\f3whodo(1M)\f1 .\" index@current users and processes, list@@@\f3whodo(1M)\f1 .\" index@users and processes, list current@@@\f3whodo(1M)\f1 .\" index@processes and users, list current@@@\f3whodo(1M)\f1 .\" index@\f4whodo\f1 \- which users are doing what@@@\f3whodo(1M)\f1 .\" .\" toc@\f3whodo(1M)\f1:\0\0\f4whodo\f1@@@which users are doing what .\" .\" fileset_database@whodo.1m SYS-ADMIN-MAN .\" $Header: fwtmp.1m,v 72.3 94/11/14 15:22:43 ssa Exp $ .TA f .TH fwtmp 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fwtmp, wtmpfix \- manipulate connect accounting records .SH SYNOPSIS .B /usr/sbin/acct/fwtmp .RB [ \|\-ic\| ] .br .B /usr/sbin/acct/wtmpfix .RI [ \|files\| ] .SH DESCRIPTION .SS fwtmp .I fwtmp reads from the standard input and writes to the standard output, converting binary records of the type found in .B wtmp to formatted .SM ASCII records. The .SM ASCII version is useful to enable editing, via .IR ed (1), bad records or general purpose maintenance of the file. .PP The argument .B \-ic is used to denote that input is in .SM ASCII form, and output is to be written in binary form. (The arguments .B i and .B c are independent, respectively specifying .SM ASCII input and binary output, thus .B \-i is an .SM ASCII to .SM ASCII copy and .B \-c is a binary to binary copy). .SS wtmpfix .I wtmpfix examines the standard input or named files in .B wtmp format, corrects the time/date stamps to make the entries consistent, and writes to the standard output. A .B \- can be used in place of .I files to indicate the standard input. If time/date corrections are not performed, .I acctcon1 will fault when it encounters certain date-change records. .PP Each time the date is set, a pair of date change records is written to .BR /var/adm/wtmp . The first record is the old date denoted by the string .B "old time" placed in the line field and the flag .SM .B OLD_TIME placed in the type field of the .RB < utmp.h > structure. The second record specifies the new date, and is denoted by the string .B "new time" placed in the line field and the flag .SM .B NEW_TIME placed in the type field. .I wtmpfix uses these records to synchronize all time stamps in the file. .I wtmpfix nullifies date change records when writing to the standard output by setting the time field of the .RB < utmp.h > structure in the old date change record equal to the time field in the new date change record. This prevents .I wtmpfix and .I acctcon1 from factoring in a date change record pair more than once. .PP In addition to correcting time/date stamps, .I wtmpfix checks the validity of the name field to ensure that it consists solely of alphanumeric characters or spaces. If it encounters a name that is considered invalid, it changes the login name to .SM .B INVALID and write a diagnostic to the standard error. This minimizes the risk that .I acctcon1 will fail when processing connect accounting records. .SH DIAGNOSTICS .I wtmpfix generates the following diagnostics messages: .IP Cannot make temporary: xxx failed to make temp file .br Input truncated at offset: xxx missing half of date pair .br New date expected at offset: xxx missing half of date pair .br Cannot read from temp: xxx some error reading .br Bad file at offset: xxx ut_line entry not digit, alpha, nor \(bv or .B { (first character only checked) .br Out of core: .I malloc fails. (Saves table of date changes) .br No dtab: software error (rarely seen, if ever) .SH FILES /usr/include/utmp.h .br /var/adm/wtmp .SH SEE ALSO acct(1M), acctcms(1M), acctcom(1M), acctcon(1M), acctmerg(1M), acctprc(1M), acctsh(1M), ed(1), runacct(1M), acct(2), acct(4), utmp(4). .SH BUGS .I fwtmp generates no errors, even on garbage input. .SH STANDARDS CONFORMANCE .CR fwtmp ": SVID2, SVID3" .PP .CR wtmpfix ": SVID2, SVID3" .\" .\" index@\f4fwtmp\f1 \- manipulate connect accounting records@@@\f3fwtmp(1M)\f1 .\" index@\f4wtmpfix\f1 \- manipulate connect accounting records@@@\f3fwtmp(1M)\f1 .\" index@\f1manipulate connect accounting records@@@\f3fwtmp(1M)\f1 .\" index@\f1connect accounting records, manipulate@@@\f3fwtmp(1M)\f1 .\" index@\f1accounting records, manipulate@@@\f3fwtmp(1M)\f1 .\" .\" toc@\f3fwtmp(1M)\f1:\0\0\f4fwtmp\f1, \f4wtmpfix\f1@@@manipulate connect accounting records .\" toc@\f4wtmpfix\f1:\0\0manipulate connect accounting records@@@\f1see \f3fwtmp(1M)\f1 .\" .\" links@fwtmp.1m wtmpfix.1m .\" .\" fileset_database@fwtmp.1m SYS-ADMIN-MAN .\" $Header: xntpd.1m,v 74.1 95/03/23 18:11:25 ssa Exp $ .TA x .TH xntpd 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xntpd - Network Time Protocol daemon .SH SYNOPSIS .C xntpd [ .C -ab ] [ .C -c .I conffile ] [ .C -e .I authdelay ] [ .C -f .I driftfile ] [ .C -k .I keyfile ] [ .C -l .I loopfile ] [ .C -p .I pidfile ] [ .C -r .I broaddelay ] [ .C -s .I statsdir ] [ .C -t .I trustedkey ] .SH DESCRIPTION .CR xntpd is a daemon which maintains a UNIX system's time\-of\-day in agreement with Internet standard time servers. .CR xntpd is a complete implementation of the Network Time Protocol (NTP) version 3 standard as defined by RFC 1305 and also retains compatibility with version 2 servers as defined by RFC 1119 and version 1 servers as defined by RFC 1059. .CR xntpd does all computations in fixed point arithmetic and is entirely free of floating point code. The computations done in the protocol and clock adjustment code are carried out with high precision to try to maintain an accuracy suitable for synchronizing with even the most precise external time source. .PP .CR xntpd exits if it detects that the system clock is off by 1000 seconds or more. Ordinarily, .CR xntpd reads its configuration from a file at startup time. The default configuration file is .CR /etc/ntp.conf , though this may be overridden from the command line. It is also possible to specify a working, though limited, .CR xntpd configuration entirely on the command line, obviating the need for a configuration file. This may be particularly appropriate when .CR xntpd is to be configured as a broadcast client, with all peers being determined by listening to broadcasts at run time. .PP The following command line arguments are understood by .CR xntpd (see the configuration file description for a more complete functional description): .TP 8 .C -a .CR xntpd will run in authenticate mode. .TP .C -b .CR xntpd will listen for broadcast NTP and sync to this if available. .TP .C -c It specifies an alternate configuration file .I filename. .TP .C -e It specifies the time (in seconds) .CR xntpd takes to compute the NTP encryption field on this computer. .TP .C -f It specifies the location of the drift file. .TP .C -k It specifies the location of the file which contains the NTP authentication keys. .TP .C -l It specifies the name of the file to record loop filter statistics. .TP .C -p It specifies the name of the file to record the daemon's process id. .TP .C -r It specifies the default round trip delay (in seconds) to be used when synchronizing to broadcasts .TP .C -s It specifies a directory to be used for creating statistics files. .TP .C -t It adds a key number to the trusted key list. .PP .SS "Configuration File Options" .CR xntpd 's configuration file is relatively free format. Comments, which may be freely inserted, begin with a .CR # character and extend to the end of the line. Blank lines are ignored. Configuration statements include an initial keyword followed by white space separated arguments, some of which may be optional. Configuration statements may not be continued over multiple lines. Arguments may be network numbers (which must be written in numeric, dotted\-quad form), integers, floating point numbers (when specifying times in seconds) and text strings. Optional arguments are delimited by .CR \[] in the following descriptions, while alternatives are separated by\| .CR |\| . .PP .C peer .I host_address [ .C key .I # ] [ .C version .I # ] [ .C minpoll .I interval ] [ .C prefer ] .br .C server .I host_address [ .C key .I # ] [ .C version .I # ] [ .C minpoll .I interval ] [ .C prefer ] .br .C broadcast .I host_address [ .C key .I # ] [ .C version .I # ] [ .C minpoll .I interval ] .PP These three statements specify various time servers to be used and/or time services to be provided. The .CR peer statement specifies that the given host is to be polled in .CR "symmetric active" mode, i.e. that the host is requested to provide time to which you might synchronize and, in addition, indicates that you are willing to have the remote host synchronize to your time. The .CR server statement specifies that the given host is to be polled in .CR client mode, i.e. that the host is requested to provide time to which you might synchronize but that you are unwilling to have the remote host synchronize to your own time. The .CR broadcast statement requests your local daemon to transmit broadcast NTP to the specified address. The latter is usually the broadcast address on [one of] your local network[s]. .PP .TP 10 .C key This option, when included, indicates that all packets sent to the address are to include authentication fields encrypted using the specified key number (the range of which is that of an unsigned 32 bit integer). The default is to not include an encryption field. .TP .C version This option allows one to specify the version number to be used for outgoing NTP packets. Versions 1, 2, and 3 are the choices, version 3 is the default. .TP .C minpoll It specifies the polling interval. The valid value for .I interval should be between 6-10 inclusive, which specifies that the minimum polling interval is 2** .I interval seconds minimum even when the local daemon isn't using the remote server's data for synchronization. The default minpoll interval value is 6 (64 seconds). .TP .C prefer This option marks the host as a preferred host. Preferred hosts determined the validity of the PPS signal and are the primary selection for synchronization when found in the set of suitable synchronization sources. .PP .C precision .I # .PP Indicates the precision of local timekeeping. The value is an integer which is approximately the base 2 logarithm of the local timekeeping precision in seconds. By default this value is set to -6. .PP The precision declared by an implementation can affect several aspects of server operation, and can be used as a tuning parameter for your synchronization subnet. It should probably not be changed from the default value, however, unless there is a good reason to do so. .PP .C driftfile .I filename .PP Specifies the name of the file used to record the \*(L"drift\*(R" (or frequency error) value .CR xntpd has computed. If the file exists on startup, it is read and the value used to initialize .CR xntpd 's internal value of the frequency error. The file is then updated once every hour by replacing the old file with a new one containing the current value of the frequency error. Note that the file is updated by first writing the current drift value into a temporary file and then using .IR rename (2) to replace the old version. This implies that .CR xntpd must have write permission for the directory the drift file is located in, and that file system links, symbolic or otherwise, should probably be avoided. .PP .C "broadcastclient yes|no" .PP This indicates whether the local server should listen for, and attempt to synchronize to, broadcast NTP. The default is .CR no . .PP .C broadcastdelay .I seconds .PP Specifies the default round trip delay to the host whose broadcasts are being synchronized to. The value is specified in seconds and is typically (for ethernet) a number between 0.007 and 0.015 seconds. This initial estimate may be improved by polling each server to determine a more accurate value. Defaults to 0.008 seconds. .PP .C "authenticate yes|no" .PP Indicates whether the local server should operate in authenticate mode or not. If .CR yes , only peers which include an authentication field encrypted with one of our trusted keys (see below) will be considered as candidates for synchronizing to. The default is .CR no . .PP .C authdelay .I seconds .PP Indicates the amount of time it takes to encrypt an NTP authentication field on the local computer. This value is used to correct transmit timestamps when the authentication is used on outgoing packets. The value usually lies somewhere in the range 0.0001 seconds to 0.003 seconds, though it is very dependent on the CPU speed of the host computer. .PP .C keys .I filename .PP Specifies the name of a file which contains the encryption keys which are to be used by .CR xntpd . The format of this file is described below. .PP .C trustedkey .I # [ .I "# ..." ] .PP Allows the specification of the encryption key numbers which are trusted for the purposes of determining peers suitable for time synchronization, when authentication is enabled. Only peers using one of these keys for encryption of the authentication field, and whose authenticity can be verified by successful decryption, will be considered as synchronization candidates. The arguments are 32 bit unsigned integers. Note, however, that NTP key 0 is fixed and globally known. If meaningful authentication is to be performed the 0 key should not be trusted. .PP .C controlkey .I # .PP Certain changes can be made to the .CR xntpd server via mode 6 control messages, in particular the setting of leap second indications in a server with a radio clock. The .CR controlkey statement specifies an encryption key number to be used for authenticating such messages. Omitting this statement will cause control messages which would change the state of the server to be ignored. .PP .C restrict .I address [ .C mask .I numeric_mask ] [ .I flag ] [ .I ... ] .PP .CR xntpd implements a general purpose address\-and\-mask based restriction list. The list is sorted by address and by mask, and the list is searched in this order for matches, with the last match found defining the restriction flags associated with the incoming packets. The source address of incoming packets is used for the match, with the 32 bit address being and'ed with the mask associated with the restriction entry and then compared with the entry's address (which has also been and'ed with the mask) to look for a match. The .CR mask argument defaults to 255.255.255.255, meaning that the .I address is treated as the address of an individual host. A default entry (address 0.0.0.0, mask 0.0.0.0) is always included and, given the sort algorithm, is always the first entry in the list. Note that, while .I address is normally given as a dotted\-quad address, the text string .IR default , with no mask option, may be used to indicate the default entry. .PP In the current implementation, flags always restrict access; i.e. an entry with no flags indicates that free access to the server is to be given. The flags are not orthogonal, in that more restrictive flags will often make less restrictive ones redundant. The flags can generally be classed into two categories, those which restrict time service and those which restrict informational queries and attempts to do run time reconfiguration of the server. One or more of the following flags may be specified: .TP 10 .I ignore Ignore all packets from hosts which match this entry. If this flag is specified neither queries nor time server polls will be responded to. .TP .I noquery Ignore all NTP mode 6 and 7 packets (i.e. information queries and configuration requests) from the source. Time service is not affected. .TP .I nomodify Ignore all NTP mode 6 and 7 packets which attempt to modify the state of the server (i.e. run time reconfiguration). Queries which return information are permitted. .TP .I noserve Ignore NTP packets whose mode is other than 6 or 7. In effect, time service is denied, though queries may still be permitted. .TP .I nopeer Provide stateless time service to polling hosts, but do not allocate peer memory resources to these hosts even if they otherwise might be considered useful as future synchronization partners. .TP .I notrust Treat these hosts normally in other respects, but never use them as synchronization sources. .TP .I ntpport This is actually a match algorithm modifier, rather than a restriction flag. Its presence causes the restriction entry to be matched only if the source port in the packet is the standard NTP UDP port (123). .PP Default restriction list entries, with the flags .I ignore, ntpport, for each of the local host's interface addresses are inserted into the table at startup to prevent the server from attempting to synchronize to its own time. A default entry is also always present, though if it is otherwise unconfigured no flags are associated with the default entry (i.e. everything besides your own NTP server is unrestricted). .PP The restriction facility was added to allow the current access policies of the time servers running on the NSFnet backbone to be implemented with .CR xntpd as well. While this facility may be otherwise useful for keeping unwanted or broken remote time servers from affecting your own, it should not be considered an alternative to the standard NTP authentication facility. Source address based restrictions are easily circumvented by a determined cracker. .PP .C statsdir .I "/directory/\[ prefix \]" .PP Indicates the full path of a directory where statistics files should be created (see below). This optional .I prefix allows the modification of the filename prefix of the file generation sets used for handling statistics logs (see .CR filegen and .CR statistics statement below). .PP .C statistics .IR names .PP Enables writing of statistics records. .I names can be one or more statistics names separated by space. Currently two kinds of statistics are supported: .TP 10 .I loopstats enables recording of loop filter statistics information. Each computation of the local clock parameters outputs a line of the following form to the file generation set named \*(L"loopstats\*(R": .PP .RS 10 48773 10847.650 0.0001307 17.3478 2 .RE .RS 10 The first two fields show the date (modified Julian) and time (seconds and fraction past UTC midnight). The next three fields show last offset, current drift compensation value and time constant of the loop filter. .RE .TP 10 .I peerstats enables recording of peer statistics information. This includes statistics records of all peers of a NTP server and of the PPS filter, if PPS signal handling is supported by the server. Each valid update appends a line of the following form to the current element of a file generation set named \*(L"peerstats\*(R": .PP .RS 10 48773 10847.650 127.127.4.1 9714 -0.001605 0.00000 0.00142 .RE .RS 10 The first two fields show the date (modified Julian) and time (seconds and fraction past UTC midnight), while the next two fields are the peer address and status, respectively. The final three fields show offset, delay and dispersion. .RE .PP Statistic files are managed using file generation sets (see .CR filegen below). The information obtained by enabling statistics recording allows analysis of temporal properties of a .CR xntpd server. It is usually only useful to primary servers or maybe main campus servers. .PP .C filegen .I name [ .C file .I filename ] [ .C type .I typename ] [ .CR link \|| nolink ] [ .CR enable \|| disable ] .PP Configures setting of generation file set .IR name. Generation file sets provides a mean for handling files that are continuously growing during the lifetime of a server. Server statistics are a typical example for such files. Generation file sets provide access to a set of files used to store the actual data. At any time at most one element of the set is being written to. The .CR type given specifies when and how data will be directed to a new element of the set. This way, information stored in elements of a file set that are currently unused are available for administrational operations without the risk of disturbing the operation of .CR xntpd . (Most important: they can be removed to free space for new data produced.) Filenames of set members are built from three elements. .I name is name of the statistic to be collected. Currently only two kinds of statistics are supported: .I loopstats and .IR peerstats . .TP 10 .C file Defines a .I filename string directly concatenated to the .I prefix mentioned above (no intervening \/ (slash)) if .I prefix is defined in the .CR statsdir statement. .TP .C type This part reflects individual elements of a file set. It is generated according to the .I type of a file set as explained below. A file generation set is characterized by its type. The following .I typenames are supported: .RS 10 .TP 10 .I none The file set is actually a single plain file. .TP .I pid One element of file set is used per incarnation of a .CR xntpd server. This type does not perform any changes to file set members during runtime, however it provides an easy way of separating files belonging to different .CR xntpd server incarnations. The set member filename is built by appending a dot .BR . to the concatenated .I prefix and .I filename strings, and appending the decimal representation of the process id of the .CR xntpd server process. (e.g .I . ) .TP .I day One file generation set element is created per day. The term .I day is based on .IR UTC. A day is defined as the period between 00:00 and 24:00 UTC. The file set member suffix consists of a dot and a day specification in the form .RI < YYYYMMDD >. .I YYYY is a 4 digit year number (e.g. 1992). .I MM is a two digit month number. .I DD is a two digit day number. Thus, all information written at December 10th, 1992 would end up in a file named .I .19921210 .TP .I week Any file set member contains data related to a certain week of a year. The term .I week is defined by computing day of year modulo 7. Elements of such a file generation set are distinguished by appending the following suffix to the file set filename base: A dot, a four digit year number, the letter .B W and a two digit week number. For example, information from January, 10th 1992 would end up in a file with suffix .I .1992W1. .TP .I month One generation file set element is generated per month. The file name suffix consists of a dot, a four digit year number, and a two digit month. .TP .I year One generation file elment is generated per year. The filename suffix consists of a dot and a 4 digit year number. .TP .I age This type of file generation sets changes to a new element of the file set every 24 hours of server operation. The filename suffix consists of a dot, the letter .B a, and an eight digit number. This number is taken to be the number of seconds the server is running at the start of the corresponding 24 hour period. .RE .TP 10 .B enabled/disabled Information is only written to a file generation set when this set is .CR enabled . Output is prevented by specifying .CR disabled . The default is .CR enabled . .PP .TP .C link/nolink It is convenient to be able to access the .I current element of a file generation set by a fixed name. This feature is enabled by specifying .CR link and disabled using .CR nolink. The default is .CR link . If .CR link is specified, a hard link from the current file set element to a file without suffix is created. When there is already a file with this name and the number of links of this file is one, it is renamed appending a dot, the letter \*(L"C\*(R", and the pid of the .CR xntpd server process. When the number of links is greater than one, the file is unlinked. This allows the current file to be accessed by a constant name. .SS "Authentication Key File Format" .PP The NTP standard specifies an extension allowing verification of the authenticity of received NTP packets, and to provide an indication of authenticity in outgoing packets. This is implemented in .CR xntpd using the DES encryption algorithm. The specification allows any one of a possible 4 billion keys, numbered with 32 bit unsigned integers, to be used to authenticate an association. The servers involved in an association must agree on the value of the key used to authenticate their data, though they must each learn the key independently. The keys are standard 56 bit DES keys. .PP Additionally, another authentication algorithm is available which uses an MD5 message digest to compute an authenticator. The length of the key or password is limited to 8 characters. .CR xntpd reads its keys from a file specified using the .B -k command line option or the .B keys statement in the configuration file. While key number 0 is fixed by the NTP standard (as 56 zero bits) and may not be changed, one or more of the keys numbered 1 through 15 may be arbitrarily set in the keys file. .PP The key file uses the same comment conventions as the configuration file. Key entries use a fixed format of the form .IP "" 5 .I "keyno type key" .PP where .I keyno is a positive integer, .I type is a single character which defines the format the key is given in, and .I key is the key itself. .PP The key may be given in one of four different formats, controlled by the \*(L"type\*(R" character. The four key types, and corresponding formats, are listed following. .TP 5 .I S The \*(L"key\*(R" is a 64 bit hexadecimal number in the format specified in the DES document, that is the high order 7 bits of each octet are used to form the 56 bit key while the low order bit of each octet is given a value such that odd parity is maintained for the octet. Leading zeroes must be specified (i.e. the key must be exactly 16 hex digits long) and odd parity must be maintained. Hence a zero key, in standard format, would be given as .I 0101010101010101 . .TP .I N The \*(L"key\*(R" is a 64 bit hexadecimal number in the format specified in the NTP standard. This is the same as the DES format except the bits in each octet have been rotated one bit right so that the parity bit is now the high order bit of the octet. Leading zeroes must be specified and odd parity must be maintained. A zero key in NTP format would be specified as .I 8080808080808080 .TP .I A The \*(L"key\*(R" is a 1\-to\-8 character ASCII string. A key is formed from this by using the lower order 7 bits of the ASCII representation of each character in the string, with zeroes being added on the right when necessary to form a full width 56 bit key, in the same way that encryption keys are formed from Unix passwords. .TP .I M The \*(L"key\*(R" is a 1\-to\-32 character ASCII string, using the MD5 authentication scheme. Note that both the keys and the authentication schemes (DES or MD5) must be identical between a set of peers sharing the same key number. .PP .SS Primary Clock Support .PP .CR xntpd can be optionally compiled to include support for a number of types of reference clocks. A reference clock will generally (though not always) be a radio timecode receiver which is synchronized to a source of standard time such as the services offered by the NRC in Canada and NIST in the U.S. The interface between the computer and the timecode receiver is device dependent and will vary, but is often a serial port. .PP For the purposes of configuration, .CR xntpd treats reference clocks in a manner analogous to normal NTP peers as much as possible. Reference clocks are referred to by address, much as a normal peer is, though an invalid IP address is used to distinguish them from normal peers. Reference clock addresses are of the form .I 127.127.t.u where .I t is an integer denoting the clock type and .I u indicates the type\-specific unit number. Reference clocks are normally enabled by configuring the clock as a server using a .CR server statement in the configuration file which references the clock's address. Clock addresses may generally be used anywhere else in the configuration file a normal IP address can be used, for example in .CR restrict statements. .PP There is one additional configuration statement which becomes valid when reference clock support is used. The format is: .PP .C fudge .I 127.127.t.u [ .C time1 .I secs ] [ .C time2 .I secs ] [ .C value1 .I int ] [ .C value2 .I int ] [ .C flag1 .I 0|1 ] [ .C flag2 .I 0|1 ] .PP There are two times (whose values are specified in fixed point seconds), two integral values and two binary flags available for customizing the operation of a clock. The configuration and interpretation of these values, and whether they are used at all, is a function of the needs of the particular clock driver. .PP .CR xntpd on HP-UX currently supports the Spectracom's Netclock/2 plus a special pseudo\-clock which synchronizes to the local system clock and can be used for backup or when no other clock source is available. The clock drivers, and the addresses used to configure them, are described as the followings: .PP .B 127.127.1.u \- Local synchronization clock driver .PP This driver doesn't support an actual clock, but rather allows the server to synchronize to its own clock, in essence to free run without its stratum increasing to infinity. This can be used to run an isolated NTP synchronization network where no standard time source is available, by allowing a free running clock to appear as if it has external synchronization to other servers. By running the local clock at an elevated stratum it can also be used to prevent a server's stratum from rising above a fixed value, this allowing a synchronization subnet to synchronize to a single local server for periods when connectivity to the primary servers is lost. .PP The unit number of the clock (the least significant octet in the address) must lie in the range 0 through 15 inclusive and is used as the stratum the local clock will run at. Note that the server, when synchronized to the local clock, will advertise a stratum one greater than the clock peer's stratum. More than one local clock may be configured (indeed all 16 units may be active at once), though this hardly seems useful. .PP The local clock driver uses only the .CR time1 parameter of the .CR fudge statement. This parameter actually provides read and write access to the local clock drift compensation register. This value, which actually provides a fine resolution speed adjustment for the local clock, is settable but will remain unchanged from any set value when the clock is free running without external synchronization. The .CR "fudge time1" parameter thus provides a way to manually adjust the speed of the clock to maintain reasonable synchronization with, say, a voice time announcement. .PP .B 127.127.4.u .PP This driver provides an interface to the Spectracom Netclock/2 WWVB Synchronized Clocks in either Format-0 or Format-2 mode of operation at 9600 bps. When the clock is set to Format-0, the .CR "time zone" switch on the clock should be set to 0 ( .CR UTC time). When the clock is set to Format-2, the .CR "time zone" switch can be set to the zone which reflects the local time. .PP A device file .I \/dev\/wwvb%d needs to be created, where .I %d is the unit number .I u. The valid unit number lies in the range 0 through 4 inclusive. The driver opens the RS232 output on the .I \/dev\/wwvb%d device file. This driver does not require a 1-pulse-per-second (pps) signal and automatically compensates for the baud rate on the serial port. It does not require the clock discipline or STREAMs modules. .PP .CR Fudge statement is used as a general calibration factor for Netclock2. A positive .CR time1 value will advance the time and a negative .CR time1 value will retard the time. The parameter defaults to zero, which should be appropriate if the clock's propagation delay switches have been set appropriately. The .CR value1 parameter can be used to set the stratum at which the peer operates. The default is 0, which is correct if you want the clock to be considered for synchronization whenever it is operating. .PP .SH AUTHOR .PP .CR xntpd was developed by Dennis Ferguson at the University of Toronto. .br Text amended by David Mills at the University of Delaware. .SH FILES .PD 0 .TP 28 .C /etc/ntp.conf The default name of the configuration file. .TP .C /etc/ntp.drift The conventional name of the drift file. .TP .C /etc/ntp.keys The conventional name of the key file. .PD .SH SEE ALSO .PP ntpq (1M), ntpdate (1M). .\" .\" index@\f4xntpd\f1 \- Network Time Protocol daemon@@@\f3xntpd(1M)\f1 .\" index@\f1NTP daemon@@@\f3xntpd(1M)\f1 .\" index@\f1Network Time Protocol (NTP) daemon@@@\f3xntpd(1M)\f1 .\" .\" toc@\f3xntpd(1M)\f1:\0\0\f4xntpd\f1@@@Network Time Protocol daemon .\" $Header: ypserv.1m,v 72.6 94/09/12 17:02:06 ssa Exp $ .TA y .TH ypserv 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypserv, ypbind, ypxfrd \- Network Information Service (NIS) server, binder, and transfer processes .SH SYNOPSIS .CR /usr/lib/netsvc/yp/ypserv .RC [ -l .IR log_file ] .PP .CR /usr/lib/netsvc/yp/ypbind .RC [ -l .IR log_file ] .RC [ -s ] .RC [ -ypset \(or -ypsetme ] .PP .CR /usr/sbin/ypxfrd .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (YP). The functionality remains the same; only the name has changed. .SH DESCRIPTION The Network Information Service (NIS) provides a simple network lookup service consisting of databases and processes. The databases are files in a directory tree rooted at .CR /var/yp (see .IR ypfiles (4)). The processes are .IR /usr/lib/netsvc/yp/ypserv , the NIS database lookup server, and .IR /usr/lib/netsvc/yp/ypbind , the NIS binder. Both .CR ypserv and .CR ypbind are daemon processes activated at system startup time when the .C NIS_MASTER_SERVER or .C NIS_SLAVE_SERVER variable is set to 1, for .C ypserv, and the .C NIS_CLIENT variable is set to 1, for .C ypbind, in the .CR /etc/rc.config.d/namesvrs file. .PP The NIS programmatic interface is described in .IR ypclnt (3C). Administrative tools are described in .IR ypwhich (1), .IR yppoll (1M), .IR yppush (1M), .IR ypset (1M) and .IR ypxfr (1M). Tools to see the contents of NIS maps (databases) are described in .IR ypcat (1) and .IR ypmatch (1). Database generation and maintenance tools are described in .IR makedbm (1M), .IR ypinit (1M), and .IR ypmake (1M). The command to set or show the default NIS domain is .IR domainname (1). .PP .CR ypxfrd transfers entire NIS maps in an efficient manner. For systems that use this daemon, map transfers will be faster, depending on the map. .CR ypxfrd should be run on a server running HP-UX release 10.0. .CR ypxfr (see .IR ypxfr (1M)) will attempt to use .CR ypxfrd first. If that fails, it will use the older transfer method. The .CR ypxfrd daemon is activated at system startup time when the .C NIS_MASTER_SERVER or .C NIS_SLAVE_SERVER variable is set to 1 in the .CR /etc/rc.config.d/namesvrs file. .PP The .CR ypserv daemon's primary function is to look up information in its local collection of NIS maps. It runs only on NIS server machines providing data from NIS databases. Communication to and from .CR ypserv is by means of RPC. Lookup functions are described in .IR ypclnt (3C). .PP Four lookup functions perform on a specific map within a NIS domain: .CR Match , .CR Get_first , .CR Get_next , and .CR Get_all . The .CR Match operation matches a key to a record in the database and returns its associated value. The .CR Get_first operation returns the first key-value pair (record) from the map, and .CR Get_next enumerates (sequentially retrieves) the remainder of the records. .CR Get_all returns all records in the map to the requester as the response to a single RPC request. .PP Two other functions supply information about the map other than normal map entries: .CR Get_order_number and .CR Get_master_name . The order number is the time of last modification of a map. The master name is the host name of the machine on which the master map is stored. Both order number and master name exist in the map as special key-value pairs, but the server does not return these through the normal lookup functions. (If you examine the map with .CR makedbm or .CR yppoll (see .IR makedbm (1M) or .IR yppoll (1M)), they will be visible.) Other functions are used within the NIS system and are not of general interest to NIS clients. They include: .nf .IP .CR Do_you_serve_this_domain? .CR Transfer_map .CR Reinitialize_internal_state .fi .PP The .CR ypbind daemon remembers information that lets client processes on its machine communicate with a .CR ypserv process. The .CR ypbind daemon must run on every machine using NIS services, both NIS servers and clients. The .CR ypserv daemon may or may not be running on a NIS client machine, but it must be running somewhere on the network or be available through a gateway. .PP The information that .CR ypbind remembers is called a .BR binding : the association of a NIS domain name with the Internet address of the NIS server and the port on that host at which the .CR ypserv process is listening for service requests. This information is cached in the directory .CR /var/yp/binding using a filename in the form .IC domainname . version\f1. .PP Client requests drive the binding process. As a request for an unbound domain comes in, the .CR ypbind process broadcasts on the network trying to find a .CR ypserv process serving maps within that NIS domain. Since the binding is established by broadcasting, at least one .CR ypserv process must exist on every network. Once a binding is established for a client, it is given to subsequent client requests. Execute .CR ypwhich to query the .CR ypbind process (local and remote) for its current binding (see .IR ypwhich (1)). .PP Bindings are verified before they are given to a client process. If .CR ypbind is unable to transact with the .CR ypserv process it is bound to, it marks the domain as unbound, tells the client process that the domain is unbound, and tries to bind again. Requests received for an unbound domain fail immediately. Generally, a bound domain is marked as unbound when the node running .CR ypserv crashes or is overloaded. In such a case, .CR ypbind binds to any NIS server (typically one that is less heavily loaded) that is available on the network. .PP The .CR ypbind daemon also accepts requests to set its binding for a particular domain. .CR ypset accesses the .CR Set_domain facility; it is for unsnarling messes and is not for casual use. .SS Options .CR ypserv recognizes the following options: .RS .TP 15 .CI -l \0log_file Log diagnostic and error messages to the file, .IR log_file . .IP If .CR ypserv is started without the .CR -l option, .CR ypserv writes its messages to .CR /var/yp/ypserv.log if that file exists. .IP If .CR ypbind is started without the .CR -l option, .CR ypbind writes its messages directly to the system console, .CR /dev/console . .IP Information logged to the file includes the date and time of the message, the host name, the process id and name of the function generating the message, and the message itself. Note that different services can share a single log file since enough information is included to uniquely identify each message. .RE .PP .CR ypbind recognizes the following options: .RS .TP 15 .CI -l \0log_file Log diagnostic and error messages to the file, .IR log_file . See the description above. .TP .CR -s Secure. When specified, only NIS servers bound to a reserved port are used. This allows for a slight increase in security in completely controlled environments, where there are no computers operated by untrusted individuals. It offers no real increase in security. .TP .CR -ypset Allow .CR ypset to be used to change the binding (see .IR ypset (1M)). For maximum security, this option should be used only when debugging the network from a remote machine. .TP .CR -ypsetme Allow .CR ypset to be issued from this machine (see .IR ypset (1M)). Security is based on IP address checking, which can be defeated on networks where untrusted individuals may inject packets. This option is not recommended. .RE .SH AUTHOR .CR ypserv , .CR ypbind , and .CR ypxfrd were developed by Sun Microsystems, Inc. .SH FILES .TP 35 .CI /var/yp/binding/ domainname . version These files cache the last successful binding created for the given domain, in order to to speed up the binding process. When a binding is requested, these files are checked for validity and then used. .TP .CR /var/yp/securenets This file is read by .CR ypxfrd and .CR ypserv . It contains a list of IP addresses that these servers will allow a binding to. .TP .CR /var/yp/secureservers This file is read by ypbind. It contains a list of IP addresses that ypbind will receive a binding from. .SH SEE ALSO domainname(1), ypcat(1), ypmatch(1), yppasswd(1), ypwhich(1), makedbm(1M), rpcinfo(1M), ypinit(1M), ypmake(1M), yppasswdd(1M), yppoll(1M), yppush(1M), ypset(1M), ypxfr(1M), ypclnt(3C), yppasswd(3N), ypfiles(4). .\" .\" index@\f4ypserv\f1: Network Information Service (NIS) server processes@@@\f3ypserv(1M)\f1 .\" index@\f4ypxfrd\f1: Network Information Service (NIS) transfer processes@@@\f3ypserv(1M)\f1 .\" index@\f4ypbind\f1: Network Information Service (NIS) binder processes@@@\f3ypserv(1M)\f1 .\" index@Network Information Service (NIS) binder processes@@@\f3ypserv(1M)\f1 .\" index@NIS (Network Information Service) binder processes@@@\f3ypserv(1M)\f1 .\" index@binder processes, Network Information Service (NIS)@@@\f3ypserv(1M)\f1 .\" index@processes, Network Information Service (NIS) binder@@@\f3ypserv(1M)\f1 .\" .\" toc@\f3ypserv(1M)\f1: \f4ypserv\f1, \f4ypbind\f1, \f4ypxfrd\f1@@@Network Information Service (NIS) server and binder processes .\" toc@\f4ypbind\f1:\0\0Network Information Service (NIS) binder processes@@@\f1see \f3ypserv(1M)\f1 .\" toc@\f4ypxfrd\f1:\0\0Network Information Service (NIS) transfer processes@@@\f1see \f3ypserv(1M)\f1 .\" .\" links@ypserv.1m ypbind.1m .\" links@ypserv.1m ypxfrd.1m .\" $Header: ypinit.1m,v 72.6 94/10/31 13:44:40 ssa Exp $ .TA y .TH ypinit 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypinit \- build and install Network Information Service databases .SH SYNOPSIS .C /usr/sbin/ypinit -m .RC [ DOM=\c .I NIS\c .IR _domain\| ] .br .C /usr/sbin/ypinit -s .I NIS\c .I _server_name .RC [ DOM=\c .I NIS\c .IR _domain\| ] .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .CR ypinit is a shell script that creates Network Information Service (NIS) databases on either a master or slave NIS server. .CR ypinit asks a few self-explanatory questions, and reports success or failure to the terminal. For an overview of Network Information Service, see .IR ypfiles (4) and .IR ypserv (1M). .SS Options .CR ypinit recognizes the following options and command-line arguments: .RS .TP 20 .C -m Create the local host as the master server to all maps (databases) provided in the NIS domain (see .IR domainname (1)). All maps are built from scratch, either from information provided to .CR ypinit at run-time, or from ASCII files in .CR /etc . All such files should be complete and unabbreviated, unlike how they may exist on a NIS client machine (see .IR passwd (4) for examples of abbreviated files). .IP See .IR ypmake (1M) for more information on how NIS databases are built on the master server. Note that .CR ypinit uses the .CR NOPUSH=1 option when invoking .CR make , so newly formed maps are not immediately copied to slave servers (see .IR ypmake (1M)). .TP .C -s Create NIS databases on a slave server by copying the databases from an existing NIS server that serves the NIS domain. .IP The .I NIS\c .I _server_name argument should be the host name of either the master server for all the maps or a server on which the maps are current and stable. .TP .CI DOM= \s-1NIS\s0_domain Causes .CR ypinit to construct maps for the specified .I NIS\c .IR domain . .CR DOM defaults to the NIS domain shown by the .CR domainname command (see .IR domainname (1). .RE .SH DIAGNOSTICS .CR ypinit returns exit code 0 if no errors occur; otherwise, it returns exit code 1. .SH AUTHOR .CR ypinit was developed by Sun Microsystems, Inc. .SH FILES .nf .C /etc/group .C /etc/hosts .C /etc/netgroup .C /etc/networks .C /etc/passwd .C /etc/protocols .C /etc/publickey .C /etc/rpc .C /etc/services .C /etc/vhe_list .C /etc/auto_master .C /etc/mail/aliases .fi .SH SEE ALSO domainname(1), makedbm(1M), vhe_altlog(1M), vhe_mounter(1M), vhe_u_mnt(1M), ypmake(1M), yppush(1M), ypserv(1M), ypxfr(1M), ypxfrd(1M), group(4), hosts(4), netgroup(4), networks(4), passwd(4), protocols(4), publickey(4), rpc(4), services(4), vhe_list(4), ypfiles(4). .\" .\" index@\f4ypinit\f1 \- build and install Network Information Service databases@@@\f3ypinit(1M)\f1 .\" index@build and install Network Information Service databases@@@\f3ypinit(1M)\f1 .\" index@install Network Information Service databases, build and@@@\f3ypinit(1M)\f1 .\" index@Network Information Service databases, build and install@@@\f3ypinit(1M)\f1 .\" index@databases, build and install Network Information Service@@@\f3ypinit(1M)\f1 .\" .\" toc@\f3ypinit(1M)\f1:\f4ypinit\f1@@@build and install Network Information Service databases .\" $Header: ypmake.1m,v 72.5 94/09/12 16:57:56 ssa Exp $ .TA y .TH ypmake 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypmake \- create or rebuild Network Information Service databases .SH SYNOPSIS .CR /var/yp/ypmake .RC [ DIR=\c .IR source_directory\| ] .CR [ DOM=\c .SM .I NIS\c .IR _domain\| ]\0\e .br .RC \h'.3i'[ NOPUSH=1 ] .RC [ PWFILE=\c .IR passwd_file\| ] .RI [ \|map .RI [ \|map \0...\|]\|] .PP .C cd /var/yp; make .RC [ DIR=\c .IR source_directory\| ] .CR [ DOM=\c .SM .I NIS\c .IR _domain\| ]\0\e .br .RC \h'.3i'[ NOPUSH=1 ] .RC [ PWFILE=\c .IR passwd_file\| ] .RI [ \|map \0...\|] .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .C ypmake is a shell script that builds one or more Network Information Service .SM (NIS) maps (databases) on a master .SM NIS server. If no arguments are specified, .C ypmake either creates maps if they do not already exist or rebuilds maps that are not current. These maps are constructed from .SM ASCII files. .C ypmake then executes .C yppush to notify slave .SM NIS servers of the change and make the slave servers copy the updated maps to their machines (see .IR yppush (1M)). .PP If any .I maps are supplied on the command line, .C ypmake creates or updates those .I maps only. Permissible names for .I maps are the filenames in .C /etc listed under .SM FILES below. In addition, specific .I maps can be named, such as .C netgroup.byuser or .CR rpc.bynumber . .PP The .C make command can be used instead of .C ypmake (see .IR make (1)). The .C Makefile no longer calls the .C ypmake script but now actually constructs the maps. All .SM NIS commands have been modified to use the .C Makefile instead of .C ypmake. The .C Makefile and .C ypmake can co-exist, but it is recommended that you consider using the .C Makefile which is the standard mechanism for building maps on other vendor's machines. .PP Both the .C Makefile and .C ypmake script use four variables: .RS .TP 25 .CI DIR= source_directory The directory containing the .SM ASCII source files from which maps are constructed. .C DIR defaults to .CR /etc . .TP .CI DOM= \s-1NIS\s0_domain Causes .C ypmake to construct maps for the specified .SM .I NIS\c .IR _domain . .C DOM defaults to the .SM NIS domain shown by .C domainname (see .IR domainname (1)). .TP .C NOPUSH=1 When non-null (null by default), .C NOPUSH inhibits copying the new or updated databases to the slave .SM NIS servers. Only slave .SM NIS servers in the specified .I domain receive .C yppush notification when .C NOPUSH is null. .TP .CI PWFILE= passwd_file Specifies the full pathname of the .SM ASCII file that .C ypmake should use when building the .SM NIS passwd maps. .C PWFILE defaults to .CR $DIR/passwd . .RE .PP The order of arguments passed to .C ypmake is unimportant, but the maps are built or updated in the left-to-right order provided. .PP Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of Network Information Service. .SH DIAGNOSTICS .C ypmake returns one of the following exit codes upon completion: .RS .TP 5 .B 0 Normal termination; no problems. .PD 0 .TP .B 1 One or more unrecognized arguments were passed. .TP .B 2 The .SM NIS domain name is not set. .TP .B 3 The subdirectory used to contain maps for a specific .SM NIS domain, .CR /var/yp/domain_name , does not exist or is not writable. .TP .B 4 An error was encountered when building at least one of the maps. .TP .B 5 One or more maps' .SM ASCII files do not exist or are unreadable. .PD .RE .SH EXAMPLES Create or rebuild the password databases (both the .C passwd.byname and .C passwd.byuid maps) from .C /etc/passwd and use .C yppush to copy the databases to any slave .SM NIS servers in the default .SM NIS .IR domain : .IP .C "ypmake passwd.byname" .PP Create or rebuild the hosts databases from .C /etc/hosts but do not copy the databases to any slave .SM NIS servers: .IP .C ypmake hosts NOPUSH=1 .PP Create or rebuild the network maps from .C /nis/sourcefiles/networks and copy the maps to any slave .SM NIS servers in .SM NIS domain .CR DAE_NIS : .IP .C "ypmake DOM=DAE_NIS networks DIR=/nis/sourcefiles" .SH AUTHOR .C ypmake was developed by Sun Microsystems, Inc. .SH FILES .nf .C /etc/group .C /etc/hosts .C /etc/netgroup .C /etc/networks .C /etc/passwd .C /etc/protocols .C /etc/publickey .C /etc/rpc .C /etc/services .C /etc/vhe_list .fi .SH SEE ALSO domainname(1), make(1), makedbm(1M), vhe_altlog(1M), vhe_mounter(1M), vhe_u_mnt(1M), ypinit(1M), yppush(1M), ypserv(1M), group(4), hosts(4), netgroup(4), networks(4), passwd(4), protocols(4), publickey(4), rpc(4), services(4), vhe_list(4), ypfiles(4). .\" .\" index@\f4ypmake\f1 \- create or rebuild Network Information Service database@@@\f3ypmake(1M)\f1 .\" index@create or rebuild Network Information Service database@@@\f3ypmake(1M)\f1 .\" index@rebuild Network Information Service database, create or@@@\f3ypmake(1M)\f1 .\" index@Network Information Service database, create or rebuild@@@\f3ypmake(1M)\f1 .\" index@database, create or rebuild Network Information Service@@@\f3ypmake(1M)\f1 .\" .\" toc@\f3ypmake(1M)\f1: \f4ypmake\f1@@@create or rebuild Network Information Service databases .\" $Header: yppasswdd.1m,v 1.1.113.2 98/02/09 10:18:15 mlang Exp $ .TA y .TH yppasswdd 1M .SH NAME yppasswdd \- daemon for modifying Network Information Service passwd database .SH SYNOPSIS .C /usr/lib/netsvc/yp/rpc.yppasswdd .I passwd_file .RC [ -l .IR log_file ] .ifn .br .ifn \0\0\0\0 .RC [ -m .RI [ "\|arg1 arg2\|" \0...\|]\|] .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION The .C yppasswdd daemon handles password change requests from .C yppasswd (see .IR yppasswd (1)). It changes a password entry in .IR passwd_file , which must be in the format defined by .IR passwd (4). The change is made only if the old password provided by .C yppasswd matches the encrypted password of that entry. .PP .C yppasswdd should be executed only on the master Network Information Service (NIS) server for the passwd database (map). The .C yppasswdd daemon is not executed by default, nor can it be started by .C inetd (see .CR inetd (1M)). To enable automatic startup of .C yppasswdd at boot time, the .C NIS_MASTER_SERVER variable should be set to 1 in file .C /etc/rc.config.d/namesvrs on the master NIS server. .SS Options .C yppasswdd recognizes the following options and command-line arguments: .RS .TP 20 .CI -l \0log_file Log diagnostic and error messages to .IR log_file . These messages are not available if .C yppasswdd is started without the .C -l option. .IP Information logged to the file includes date and time of the message, the host name, process ID and name of the function generating the message, and the message itself. Note that different services can share a single log file because enough information is included to uniquely identify each message. .TP .CR -m " [\|\f2arg1 arg2\fP\0...\|]" After .I passwd_file is modified, and if using the .C -m option, .C yppasswdd executes .C make to update the NIS passwd database (see .IR ypmake (1M) Any arguments following the .C -m flag are passed to .CR make . .IP To ensure that the passwd map is rebuilt to contain the new password and all slave NIS servers have their passwd maps properly updated to include the change, always use the .C -m option to .CR yppasswdd , but do not use the .C NOPUSH=1 argument to .CR make . .SH EXAMPLES Assume the .C yppasswdd daemon is started on the master NIS server as follows: .nf .IP .C "/usr/lib/netsvc/yp/rpc.yppasswdd /var/yp/src/passwd \e" .CR " \-l /var/adm/yppasswdd.log \e" .C " \-m passwd DIR=/var/yp/src" .fi .PP This indicates that the ASCII file from which the NIS passwd database is built is .CR /var/yp/src/passwd . When this file is updated by a request from .CR yppasswd , the NIS passwd database is rebuilt and copied to all slave NIS servers in the master's NIS domain (see .IR domainname (1)). .PP Log messages are written to the file .CR /var/adm/yppasswdd.log . .SH WARNINGS .C yppasswdd uses lock file .C /var/adm/ptmp to get exclusive access to .I passwd_file when updating it. The file .C /var/adm/ptmp may persist if .I passwd_file is being updated and .RS .TP 3 \(bu The system crashes or .TP \(bu .C yppasswdd is killed using .C SIGKILL (see .IR kill (1) and .IR signal (2)). .RE .PP File .C /var/adm/ptmp must be removed before .C yppasswdd can function properly again. .PP .C vipw also uses .C /var/adm/ptmp when updating .C /etc/passwd (see .IR vipw (1M)). As a result, .C yppasswdd competes with .C vipw when it updates .I passwd_file if .I passwd_file is .CR /etc/passwd . .SH AUTHOR .C yppasswdd was developed by Sun Microsystems, Inc. .SH FILES .TP 15 .C /var/adm/ptmp lock file used when updating .I passwd_file .SH SEE ALSO domainname(1), yppasswd(1), vipw(1M), ypmake(1M), yppasswd(3N), passwd(4), publickey(4), ypfiles(4). .\" .\" index@\f4yppasswdd\f1 \- daemon for modifying Network Information Service \f4passwd\f1 database@@@\f3yppasswdd(1M)\f1 .\" index@daemon for modifying Network Information Service \f4passwd\f1 database@@@\f3yppasswdd(1M)\f1 .\" index@modifying Network Information Service \f4passwd\f1 database, daemon for@@@\f3yppasswdd(1M)\f1 .\" index@Network Information Service \f4passwd\f1 database, daemon for modifying@@@\f3yppasswdd(1M)\f1 .\" index@passwd database, daemon for modifying Network Information Service@@@\f3yppasswdd(1M)\f1 .\" index@database, daemon for modifying Network Information Service \f4passwd\f1@@@\f3yppasswdd(1M)\f1 .\" .\" toc@\f3yppasswdd(1M)\f1: \f4yppasswdd\f1@@@daemon for modifying Network Information Service passwd database .\" $Header: yppoll.1m,v 72.5 94/08/25 17:02:30 ssa Exp $ .TA y .TH yppoll 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME yppoll \- query NIS server for information about NIS map .SH SYNOPSIS .C /usr/sbin/yppoll .RC [ -h .IR host ] .RC [ -d .IR domain ] .I mapname .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .CR yppoll asks a Network Information Service (NIS) server process (see .IR ypserv (1M)) to return the order number (the .CR time in seconds when the map was built \(mi .IR time (2)) and master NIS server's host name for a NIS database named .IR mapname . .CR yppoll then writes them to standard output. If the server uses Version 1 NIS protocol, .CR yppoll uses this older protocol to communicate with it. .CR yppoll also prints the old style diagnostic messages in case of failure. .PP See .IR ypfiles (4) and .IR ypserv (1M) for an overview of Network Information Service. .SS Options .TP 15 .CI -h \0host Ask the .CR ypserv process on .I host to return the map information (see .IR ypserv (1M)). If .CI -h \0host is not specified, the host returned by .CR ypwhich is used (see .IR ypwhich (1)). .TP .CI -d \0domain Use .I domain instead of the domain returned by .CR domainname (see .IR domainname (1)). .SH AUTHOR .CR yppoll was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), ypwhich(1), ypserv(1M), ypfiles(4). .\" .\" index@\f4yppoll\f1 \- query an NIS server for information about an NIS map@@@\f3yppoll(1M)\f1 .\" index@\f1query an NIS server for information about an NIS map@@@\f3yppoll(1M)\f1 .\" index@\f1NIS server for information about an NIS map, query an@@@\f3yppoll(1M)\f1 .\" index@\f1server for information about an NIS map, query an NIS@@@\f3yppoll(1M)\f1 .\" index@\f1information about an NIS map, query an NIS server for@@@\f3yppoll(1M)\f1 .\" index@\f1Network Information Service: NIS map, query an NIS server for information about an@@@\f3yppoll(1M)\f1 .\" index@\f1NIS map, query an NIS server for information about an@@@\f3yppoll(1M)\f1 .\" index@\f1map, query an NIS server for information about an NIS@@@\f3yppoll(1M)\f1 .\" .\" toc@\f3yppoll(1M)\f1:\0\0\f4yppoll\f1@@@query NIS server for information about an NIS map .\" $Header: yppush.1m,v 72.5 94/08/25 17:00:02 ssa Exp $ .TA y .TH yppush 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME yppush \- force propagation of Network Information Service database .SH SYNOPSIS .C /usr/sbin/yppush .RC [ -d .IR domain\| ] .RC [ -m .IR maxm\| ] .RC [ -t .IR mint\| ] .RC [ -v ] .I mapname .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .CR yppush copies a Network Information Service (NIS) map (database), .IR mapname , from the map's master NIS server to each slave NIS server. It is usually executed only on the master NIS server by shell script .CR ypmake which is run either after changes are made to one or more of the master's NIS databases or when the NIS databases are first created. See .IR ypmake (1M) and .IR ypinit (1M) for more information on these processes. .PP .CR yppush constructs a list of NIS server host names by reading the NIS map .CR ypservers within the .IR domain . Keys within the .CR ypservers map are the host names of the machines on which the NIS servers run. .CR yppush then sends a "transfer map" request to the NIS server at each host, along with the information needed by the transfer agent (the program that actually moves the map) to call back .CR yppush . .PP When the transfer attempt is complete, whether successful or not, and the transfer agent sends .CR yppush a status message, the results can be printed to standard output. Messages are printed when a transfer is not possible, such as when the request message is undeliverable or when the timeout period on responses expires. .PP Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of Network Information Service. .SS Options .CR yppush recognizes the following options: .RS .TP 12 .CI -d \0domain Copy .I mapname to the NIS servers in .IR domain rather than to the .I domain returned by .CR domainname (see .IR domainname (1)). .TP .CI -m \0maxm Attempt to run .I maxm transfers in parallel to as many servers simultaneously. Without the .CR -m option, .CR yppush attempts to transfer a map to each server, one at a time. When a network has many servers, such serial transfers can result in long delays to complete all transfers. A .I maxm value greater than 1 reduces total transfer time through better utilization of CPU time at the master. .I maxm can be any value from 1 through the number of NIS servers in the domain. .TP .CI -t \0mint Set the minimum timeout value to .I mint seconds. When transferring to one slave at a time, .CR yppush waits up to 80 seconds for the transfer to complete, after which it begins transferring to the next slave. When multiple parallel transfers are attempted by use of the .CR -m option, it may be necessary to set the transfer timeout limit to a value larger than the default 80 seconds to prevent timeouts caused by network delays related to parallel transfers. .TP .CR -v Verbose mode: messages are printed when each server is called and when each response is received. If this option is omitted, only error messages are printed. .RE .SH WARNINGS In the current implementation (Version 2 NIS protocol), the transfer agent is .IR ypxfr (1M) which is started by the .IR ypserv (1M) program at .IR yppush 's request (see .IR ypxfr (1M) and .IR ypserv (1M)). If .I yppush detects it is interacting with a Version 1 NIS protocol server, it uses the older protocol to send a Version 1 .CR YPPROC_GET request and issues a message to that effect. Unfortunately, there is no way of knowing if or when the map transfer is performed for Version 1 servers. .CR yppush prints a comment saying that a Version 1 message was sent. The system administrator should then verify by other means that the transfer actually occurred. .SH AUTHOR .CR yppush was developed by Sun Microsystems, Inc. .SH FILES .C /usr/sbin/\f2domain\f1/ypservers.{dir, pag} .br .C /usr/sbin/\f2domain\f1/\f2mapname\f1.{dir, pag} .SH SEE ALSO domainname(1), ypserv(1M), ypxfr(1M), ypfiles(4). .\" .\" index@\f4yppush\f1 \- force propagation of a Network Information Service database@@@\f3yppush(1M)\f1 .\" index@\f1force propagation of a Network Information Service database@@@\f3yppush(1M)\f1 .\" index@\f1propagation of a Network Information Service database, force@@@\f3yppush(1M)\f1 .\" index@\f1Network Information Service database, force propagation of a@@@\f3yppush(1M)\f1 .\" index@\f1database, force propagation of a Network Information Service@@@\f3yppush(1M)\f1 .\" .\" toc@\f3yppush(1M)\f1:\0\0\f4yppush\f1@@@force propagation of a Network Information Service database .\" $Header: ypserv.1m,v 72.6 94/09/12 17:02:06 ssa Exp $ .TA y .TH ypserv 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypserv, ypbind, ypxfrd \- Network Information Service (NIS) server, binder, and transfer processes .SH SYNOPSIS .CR /usr/lib/netsvc/yp/ypserv .RC [ -l .IR log_file ] .PP .CR /usr/lib/netsvc/yp/ypbind .RC [ -l .IR log_file ] .RC [ -s ] .RC [ -ypset \(or -ypsetme ] .PP .CR /usr/sbin/ypxfrd .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (YP). The functionality remains the same; only the name has changed. .SH DESCRIPTION The Network Information Service (NIS) provides a simple network lookup service consisting of databases and processes. The databases are files in a directory tree rooted at .CR /var/yp (see .IR ypfiles (4)). The processes are .IR /usr/lib/netsvc/yp/ypserv , the NIS database lookup server, and .IR /usr/lib/netsvc/yp/ypbind , the NIS binder. Both .CR ypserv and .CR ypbind are daemon processes activated at system startup time when the .C NIS_MASTER_SERVER or .C NIS_SLAVE_SERVER variable is set to 1, for .C ypserv, and the .C NIS_CLIENT variable is set to 1, for .C ypbind, in the .CR /etc/rc.config.d/namesvrs file. .PP The NIS programmatic interface is described in .IR ypclnt (3C). Administrative tools are described in .IR ypwhich (1), .IR yppoll (1M), .IR yppush (1M), .IR ypset (1M) and .IR ypxfr (1M). Tools to see the contents of NIS maps (databases) are described in .IR ypcat (1) and .IR ypmatch (1). Database generation and maintenance tools are described in .IR makedbm (1M), .IR ypinit (1M), and .IR ypmake (1M). The command to set or show the default NIS domain is .IR domainname (1). .PP .CR ypxfrd transfers entire NIS maps in an efficient manner. For systems that use this daemon, map transfers will be faster, depending on the map. .CR ypxfrd should be run on a server running HP-UX release 10.0. .CR ypxfr (see .IR ypxfr (1M)) will attempt to use .CR ypxfrd first. If that fails, it will use the older transfer method. The .CR ypxfrd daemon is activated at system startup time when the .C NIS_MASTER_SERVER or .C NIS_SLAVE_SERVER variable is set to 1 in the .CR /etc/rc.config.d/namesvrs file. .PP The .CR ypserv daemon's primary function is to look up information in its local collection of NIS maps. It runs only on NIS server machines providing data from NIS databases. Communication to and from .CR ypserv is by means of RPC. Lookup functions are described in .IR ypclnt (3C). .PP Four lookup functions perform on a specific map within a NIS domain: .CR Match , .CR Get_first , .CR Get_next , and .CR Get_all . The .CR Match operation matches a key to a record in the database and returns its associated value. The .CR Get_first operation returns the first key-value pair (record) from the map, and .CR Get_next enumerates (sequentially retrieves) the remainder of the records. .CR Get_all returns all records in the map to the requester as the response to a single RPC request. .PP Two other functions supply information about the map other than normal map entries: .CR Get_order_number and .CR Get_master_name . The order number is the time of last modification of a map. The master name is the host name of the machine on which the master map is stored. Both order number and master name exist in the map as special key-value pairs, but the server does not return these through the normal lookup functions. (If you examine the map with .CR makedbm or .CR yppoll (see .IR makedbm (1M) or .IR yppoll (1M)), they will be visible.) Other functions are used within the NIS system and are not of general interest to NIS clients. They include: .nf .IP .CR Do_you_serve_this_domain? .CR Transfer_map .CR Reinitialize_internal_state .fi .PP The .CR ypbind daemon remembers information that lets client processes on its machine communicate with a .CR ypserv process. The .CR ypbind daemon must run on every machine using NIS services, both NIS servers and clients. The .CR ypserv daemon may or may not be running on a NIS client machine, but it must be running somewhere on the network or be available through a gateway. .PP The information that .CR ypbind remembers is called a .BR binding : the association of a NIS domain name with the Internet address of the NIS server and the port on that host at which the .CR ypserv process is listening for service requests. This information is cached in the directory .CR /var/yp/binding using a filename in the form .IC domainname . version\f1. .PP Client requests drive the binding process. As a request for an unbound domain comes in, the .CR ypbind process broadcasts on the network trying to find a .CR ypserv process serving maps within that NIS domain. Since the binding is established by broadcasting, at least one .CR ypserv process must exist on every network. Once a binding is established for a client, it is given to subsequent client requests. Execute .CR ypwhich to query the .CR ypbind process (local and remote) for its current binding (see .IR ypwhich (1)). .PP Bindings are verified before they are given to a client process. If .CR ypbind is unable to transact with the .CR ypserv process it is bound to, it marks the domain as unbound, tells the client process that the domain is unbound, and tries to bind again. Requests received for an unbound domain fail immediately. Generally, a bound domain is marked as unbound when the node running .CR ypserv crashes or is overloaded. In such a case, .CR ypbind binds to any NIS server (typically one that is less heavily loaded) that is available on the network. .PP The .CR ypbind daemon also accepts requests to set its binding for a particular domain. .CR ypset accesses the .CR Set_domain facility; it is for unsnarling messes and is not for casual use. .SS Options .CR ypserv recognizes the following options: .RS .TP 15 .CI -l \0log_file Log diagnostic and error messages to the file, .IR log_file . .IP If .CR ypserv is started without the .CR -l option, .CR ypserv writes its messages to .CR /var/yp/ypserv.log if that file exists. .IP If .CR ypbind is started without the .CR -l option, .CR ypbind writes its messages directly to the system console, .CR /dev/console . .IP Information logged to the file includes the date and time of the message, the host name, the process id and name of the function generating the message, and the message itself. Note that different services can share a single log file since enough information is included to uniquely identify each message. .RE .PP .CR ypbind recognizes the following options: .RS .TP 15 .CI -l \0log_file Log diagnostic and error messages to the file, .IR log_file . See the description above. .TP .CR -s Secure. When specified, only NIS servers bound to a reserved port are used. This allows for a slight increase in security in completely controlled environments, where there are no computers operated by untrusted individuals. It offers no real increase in security. .TP .CR -ypset Allow .CR ypset to be used to change the binding (see .IR ypset (1M)). For maximum security, this option should be used only when debugging the network from a remote machine. .TP .CR -ypsetme Allow .CR ypset to be issued from this machine (see .IR ypset (1M)). Security is based on IP address checking, which can be defeated on networks where untrusted individuals may inject packets. This option is not recommended. .RE .SH AUTHOR .CR ypserv , .CR ypbind , and .CR ypxfrd were developed by Sun Microsystems, Inc. .SH FILES .TP 35 .CI /var/yp/binding/ domainname . version These files cache the last successful binding created for the given domain, in order to to speed up the binding process. When a binding is requested, these files are checked for validity and then used. .TP .CR /var/yp/securenets This file is read by .CR ypxfrd and .CR ypserv . It contains a list of IP addresses that these servers will allow a binding to. .TP .CR /var/yp/secureservers This file is read by ypbind. It contains a list of IP addresses that ypbind will receive a binding from. .SH SEE ALSO domainname(1), ypcat(1), ypmatch(1), yppasswd(1), ypwhich(1), makedbm(1M), rpcinfo(1M), ypinit(1M), ypmake(1M), yppasswdd(1M), yppoll(1M), yppush(1M), ypset(1M), ypxfr(1M), ypclnt(3C), yppasswd(3N), ypfiles(4). .\" .\" index@\f4ypserv\f1: Network Information Service (NIS) server processes@@@\f3ypserv(1M)\f1 .\" index@\f4ypxfrd\f1: Network Information Service (NIS) transfer processes@@@\f3ypserv(1M)\f1 .\" index@\f4ypbind\f1: Network Information Service (NIS) binder processes@@@\f3ypserv(1M)\f1 .\" index@Network Information Service (NIS) binder processes@@@\f3ypserv(1M)\f1 .\" index@NIS (Network Information Service) binder processes@@@\f3ypserv(1M)\f1 .\" index@binder processes, Network Information Service (NIS)@@@\f3ypserv(1M)\f1 .\" index@processes, Network Information Service (NIS) binder@@@\f3ypserv(1M)\f1 .\" .\" toc@\f3ypserv(1M)\f1: \f4ypserv\f1, \f4ypbind\f1, \f4ypxfrd\f1@@@Network Information Service (NIS) server and binder processes .\" toc@\f4ypbind\f1:\0\0Network Information Service (NIS) binder processes@@@\f1see \f3ypserv(1M)\f1 .\" toc@\f4ypxfrd\f1:\0\0Network Information Service (NIS) transfer processes@@@\f1see \f3ypserv(1M)\f1 .\" .\" links@ypserv.1m ypbind.1m .\" links@ypserv.1m ypxfrd.1m .\" $Header: ypset.1m,v 72.5 94/09/12 17:02:30 ssa Exp $ .TA y .TH ypset 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypset \- bind to particular Network Information Service server .SH SYNOPSIS .C /usr/sbin/ypset .RC [ -V1 ] .RC [ -h .IR host\| ] .RC [ -d .IR domain\| ] .I server .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .C ypset tells .C ypbind to get Network Information Service .SM (NIS) services for the specified .I domain from the .C ypserv process running on .I server (see .IR ypserv (1M) and .IR ypbind (1M)). .I server is the .SM NIS server that the .SM NIS client binds to, and is specified as either a host name or an .SM IP address. If .I server is down or is not running .CR ypserv , this is not discovered until a local .SM NIS client process tries to obtain a binding for the domain. The .C ypbind daemon then tests the binding set by .CR ypset . If the binding cannot be made to the requested server, .C ypbind attempts to rebind to another server in the same domain. .PP The .C ypset command is useful for binding a client node that is not on a broadcast network, since broadcasting is the method by which .C ypbind locates a .SM NIS server. If a client node exists on a broadcast network which has no .SM NIS server running, and if there is a network with one running that is available via a gateway, .C ypset can establish a binding through that gateway. It is also useful for debugging .SM NIS client applications such as when a .SM NIS map exists only at a single .SM NIS server. .PP In cases where several hosts on the local net are supplying .SM NIS services, it is possible for .C ypbind to rebind to another host, even while you attempt to find out if the .C ypset operation succeeded. For example, typing .C ypset host1 followed by .C ypwhich and receiving the reply .C host2 may be confusing. It could occur when .I host1 does not respond to .C ypbind because its .C ypserv process is not running or is overloaded, and .IR host2 , running .CR ypserv , gets the binding. .PP Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of the Network Information Service. .SS Options .C ypset recognizes the following options and comman-line arguments: .RS .TP 15 .C -V1 Bind .I server for the (old) Version 1 .SM NIS protocol. .TP .CI -h \0host Set the binding on .I host instead of locally. .I host can be specified as a host name or an .SM IP address. .TP .CI -d \0domain Use .I domain instead of the default domain returned by .C domainname (see .IR domainname (1)). .RE .SH DIAGNOTICS .TP .C "Sorry, ypbind on host 'name' has rejected your request." The user is not root, or ypbind was run without the .C -ypset flags. See .C ypserv(1m) for explanations of the .C -ypset flags. .TP .C "Sorry, I couldn't send my rpc message to ypbind on host 'name'." The user is not root, or ypbind was run without one of the .C -ypset flags. See .C ypserv(1m) for explanations of the .C -ypset flags. .SH WARNINGS The .I server is the .SM NIS server to bind to, specified as either a host name or an IP address. If .I server is a host name, .C ypset uses the .SM NIS services' .C hosts database (built from .C /etc/hosts on the master server) to resolve the name to an IP address. This process works only if the node currently has a valid binding for the domain in question. In most cases, .I server should be specified as an .SM IP address. .SH AUTHOR .C ypset was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), ypwhich(1), ypserv(1m), ypfiles(4). .\" .\" index@\f4ypset\f1 \- bind to a particular Network Information Service server@@@\f3ypset(1M)\f1 .\" index@bind to a particular Network Information Service server@@@\f3ypset(1M)\f1 .\" index@particular Network Information Service server, bind to a@@@\f3ypset(1M)\f1 .\" index@specific Network Information Service server, bind to a@@@\f3ypset(1M)\f1 .\" index@Network Information Service server, bind to a particular@@@\f3ypset(1M)\f1 .\" .\" toc@\f3ypset(1M)\f1: \f4ypset\f1@@@bind to particular Network Information Service server .\" $Header: ypupdated.1m,v 76.1 95/07/10 17:17:31 ssa Exp $ .TA y .TH ypupdated 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypupdated, rpc.ypupdated \- server for changing NIS information .SH SYNOPSIS .C /usr/lib/netsvc/yp/rpc.ypupdated [-is] .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .CR ypupdated is a daemon that updates information in the .CR "Network Information Service (NIS)" databases. It is activated at system startup when the .C NIS_MASTER_SERVER variable is set to 1 in .CR /etc/rc.config.d/namesvrs file on the NIS master server. .CR ypupdated consults the file .CR updaters in the directory .CR /var/yp to determine which NIS maps should be updated and how to change them. .PP By default, the daemon requires the most secure method of authentication available to it, either DES (secure) or UNIX (without augmented security). .SS Options .CR ypupdated supports the following options: .RS .TP .C -i Accept RPC calls with the insecure AUTH_UNIX credentials. This allows programmatic updating of the NIS maps in all networks. .TP .C -s Accept only calls authenticated using the secure RPC mechanism (AUTH_DES authentication). This disables programmatic updating of the NIS maps unless the network supports these calls. .SH AUTHOR .CR ypupdated was developed by Sun Microsystems, Inc. .SH FILES .TP 25 .CR /var/yp/updaters .SH SEE ALSO keyserv(1M), updaters(1M). .\" .\" toc@\f3ypupdated(1M)\f1:\0\0\f4ypupdated\f1, \f4rpc.ypupdated\f1@@@server for changing NIS information .\" .\" toc@\f4rpc.ypupdated\f1:\0\0hex encryption and utility routines@@@see \f3ypupdated(1M)\f1 .\" .\" index@\f4ypupdated\f1, \f4rpc.ypupdated\f1 \- server for changing NIS information@@@\f3ypupdated(1M)\f1 .\" .\" index@\f4rpc.ypupdated\f1, \f4ypupdated\f1, \- server for changing NIS information@@@\f3ypupdated(1M)\f1 .\" .\" index@server for changing NIS information@@@\f3ypupdated(1M)\f1 .\" index@changing NIS information, server for@@@\f3ypupdated(1M)\f1 .\" index@NIS information, server for changing@@@\f3ypupdated(1M)\f1 .\" .\" links@ypupdated.1m rpc.ypupdated.1m .\" $Header: ypxfr.1m,v 72.5 94/11/29 11:52:03 ssa Exp $ .TA y .TH ypxfr 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypxfr, ypxfr_1perday, ypxfr_1perhour, ypxfr_2perday \- transfer \s-1NIS\s+1 database from server to local node .SH SYNOPSIS .C /usr/sbin/ypxfr .RC [ b ] .RC [ -c ] .RC [ -d .IR domain\| ] .RC [ -f ] .RC [ -h .IR host\| ] .RC [ -s .IR domain ] .ifn .br .ifn \0\0\0\0 .RC [ -C .I tid prog ipaddr .IR port\| ] .I mapname .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION .CR ypxfr copies a Network Information Service (NIS) map (database) to the local host from a NIS server by using the NIS services. A map can be copied regardless of its age, or it can be copied depending on whether its modification time (order number) is more recent than that of the local map. .PP The .CR ypxfr command creates a temporary map in directory .CR /var/yp/domain where .I domain is the NIS .IR domain . The .CR ypxfr command fills the map with .I mapname entries, obtains the map parameters (master and order number), and loads them. It then clears the old version of .I mapname and moves the temporary map to the existing .IR mapname . .PP If .CR ypxfr is run interactively, it writes messages to standard output. If .CR ypxfr is invoked without a controlling terminal and if the log file .CR /var/yp/ypxfr.log exists, .CR ypxfr appends all its messages to that file. Since .CR ypxfr is usually run from root's .CR crontab file (see .IR crontab (1)) or by .CR yppush (see .IR yppush (1M)), the log file can retain a record of what .CR ypxfr attempted and what the results were. .PP To maintain consistency between NIS servers, .CR ypxfr should be executed periodically for every map in the NIS. Different maps change at different rates. For example, the .CR services.byname map may not change for months at a time, and might therefore be checked for changes only once a day, such as in the early morning hours. However, .CR passwd.byname may change several times per day, so hourly checks for updates might be more appropriate. .PP A .CR crontab file can perform these periodic checks and transfers automatically. Rather than having a separate .CR crontab file for each map, .CR ypxfr requests can be grouped in a shell script to update several maps at once. Example scripts (mnemonically named) are in .CR /var/yp : .CR ypxfr_1perday , .CR ypxfr_2perday , and .CR ypxfr_1perhour . They serve as reasonable rough drafts that can be changed as appropriate. .PP Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of the Network Information Service. .SS Options .CR ypxfr recognizes the following options and command-line arguments: .RS .TP 15 .C -b Preserve the resolver flag in the map during transfer. .TP .CR -c Do not send a "clear current map" request to the local .CR ypserv process. Use this flag if .CR ypserv is not running locally when you are running .CR ypxfr . Otherwise, .CR ypxfr complains that it cannot talk to the local .CR ypserv , and the transfer fails. If .CR ypserv is running locally, do not use this flag. .TP .CI -d \0domain Copy the map from a NIS server in .I domain rather than the .I domain returned by .CR domainname (see .IR domainname (1)). .TP .CR -f Force the map to be copied, even if its order number at the remote NIS server is not more recent than the order number of the local map. .TP .CI -h \0host Obtain the map from .IR host , regardless of its master server. If this option is not used, .CR ypxfr asks the NIS service for the master's host name and tries to obtain its map. The .I host can be a name or an IP address of the form .IR "a.b.c.d" . .TP .CI -s \0domain Specify a source domain from which to transfer a map that should be the same across domains (such as the .CR services.byname map. .TP .CI -C " tid prog ipaddr port" .I This option is used by .CR ypserv .IR only . When .CR ypserv invokes .CR ypxfr , it specifies that .CR ypxfr should call back a .CR yppush process (that initiated the transfer) at the host with IP address .IR ipaddr , registered as program number .IR prog , listening on port .IR port , and waiting for a response to transaction .IR tid . .SH AUTHOR .CR ypxfr was developed by Sun Microsystems, Inc. .SH FILES .TP 30 .CR /usr/sbin/ypxfr.log log file .PP The following scripts are suggested for use with .CR cron . .TP 30 .CR /usr/sbin/ypxfr_1perday run one transfer per day .TP .CR /usr/sbin/ypxfr_2perday run two transfers per day .TP .CR /usr/sbin/ypxfr_1perhour hourly transfers of "volatile" maps .SH SEE ALSO crontab(1), domainname(1), cron(1M), ypinit(1M), yppush(1M), ypserv(1M), ypfiles(4). .\" .\" index@\f4ypxfr\f1 \- transfer NIS database from NIS server to local node@@@\f3ypxfr(1M)\f1 .\" index@\f4ypxfr_1perday\f1 \- transfer NIS database from NIS server to local node@@@\f3ypxfr(1M)\f1 .\" index@\f4ypxfr_1perhour\f1 \- transfer NIS database from NIS server to local node@@@\f3ypxfr(1M)\f1 .\" index@\f4ypxfr_2perday\f1 \- transfer NIS database from NIS server to local node@@@\f3ypxfr(1M)\f1 .\" index@transfer NIS database from NIS server to local node@@@\f3ypxfr(1M)\f1 .\" index@NIS database from NIS server to local node, transfer@@@\f3ypxfr(1M)\f1 .\" index@database from NIS server to local node, transfer NIS@@@\f3ypxfr(1M)\f1 .\" index@NIS server to local node, transfer NIS database from@@@\f3ypxfr(1M)\f1 .\" index@server to local node, transfer NIS database from NIS@@@\f3ypxfr(1M)\f1 .\" index@local node, transfer NIS database from NIS server to@@@\f3ypxfr(1M)\f1 .\" index@node, transfer NIS database from NIS server to local@@@\f3ypxfr(1M)\f1 .\" .\" toc@\f3ypxfr(1M)\f1: \f4ypxfr\f1, \f4ypxfr_1perday\f1,\n\f4ypxfr_1perhour\f1, \f4ypxfr_2perday\f1@@@transfer NIS database from NIS server to local node .\" $Header: ypserv.1m,v 72.6 94/09/12 17:02:06 ssa Exp $ .TA y .TH ypserv 1M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypserv, ypbind, ypxfrd \- Network Information Service (NIS) server, binder, and transfer processes .SH SYNOPSIS .CR /usr/lib/netsvc/yp/ypserv .RC [ -l .IR log_file ] .PP .CR /usr/lib/netsvc/yp/ypbind .RC [ -l .IR log_file ] .RC [ -s ] .RC [ -ypset \(or -ypsetme ] .PP .CR /usr/sbin/ypxfrd .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (YP). The functionality remains the same; only the name has changed. .SH DESCRIPTION The Network Information Service (NIS) provides a simple network lookup service consisting of databases and processes. The databases are files in a directory tree rooted at .CR /var/yp (see .IR ypfiles (4)). The processes are .IR /usr/lib/netsvc/yp/ypserv , the NIS database lookup server, and .IR /usr/lib/netsvc/yp/ypbind , the NIS binder. Both .CR ypserv and .CR ypbind are daemon processes activated at system startup time when the .C NIS_MASTER_SERVER or .C NIS_SLAVE_SERVER variable is set to 1, for .C ypserv, and the .C NIS_CLIENT variable is set to 1, for .C ypbind, in the .CR /etc/rc.config.d/namesvrs file. .PP The NIS programmatic interface is described in .IR ypclnt (3C). Administrative tools are described in .IR ypwhich (1), .IR yppoll (1M), .IR yppush (1M), .IR ypset (1M) and .IR ypxfr (1M). Tools to see the contents of NIS maps (databases) are described in .IR ypcat (1) and .IR ypmatch (1). Database generation and maintenance tools are described in .IR makedbm (1M), .IR ypinit (1M), and .IR ypmake (1M). The command to set or show the default NIS domain is .IR domainname (1). .PP .CR ypxfrd transfers entire NIS maps in an efficient manner. For systems that use this daemon, map transfers will be faster, depending on the map. .CR ypxfrd should be run on a server running HP-UX release 10.0. .CR ypxfr (see .IR ypxfr (1M)) will attempt to use .CR ypxfrd first. If that fails, it will use the older transfer method. The .CR ypxfrd daemon is activated at system startup time when the .C NIS_MASTER_SERVER or .C NIS_SLAVE_SERVER variable is set to 1 in the .CR /etc/rc.config.d/namesvrs file. .PP The .CR ypserv daemon's primary function is to look up information in its local collection of NIS maps. It runs only on NIS server machines providing data from NIS databases. Communication to and from .CR ypserv is by means of RPC. Lookup functions are described in .IR ypclnt (3C). .PP Four lookup functions perform on a specific map within a NIS domain: .CR Match , .CR Get_first , .CR Get_next , and .CR Get_all . The .CR Match operation matches a key to a record in the database and returns its associated value. The .CR Get_first operation returns the first key-value pair (record) from the map, and .CR Get_next enumerates (sequentially retrieves) the remainder of the records. .CR Get_all returns all records in the map to the requester as the response to a single RPC request. .PP Two other functions supply information about the map other than normal map entries: .CR Get_order_number and .CR Get_master_name . The order number is the time of last modification of a map. The master name is the host name of the machine on which the master map is stored. Both order number and master name exist in the map as special key-value pairs, but the server does not return these through the normal lookup functions. (If you examine the map with .CR makedbm or .CR yppoll (see .IR makedbm (1M) or .IR yppoll (1M)), they will be visible.) Other functions are used within the NIS system and are not of general interest to NIS clients. They include: .nf .IP .CR Do_you_serve_this_domain? .CR Transfer_map .CR Reinitialize_internal_state .fi .PP The .CR ypbind daemon remembers information that lets client processes on its machine communicate with a .CR ypserv process. The .CR ypbind daemon must run on every machine using NIS services, both NIS servers and clients. The .CR ypserv daemon may or may not be running on a NIS client machine, but it must be running somewhere on the network or be available through a gateway. .PP The information that .CR ypbind remembers is called a .BR binding : the association of a NIS domain name with the Internet address of the NIS server and the port on that host at which the .CR ypserv process is listening for service requests. This information is cached in the directory .CR /var/yp/binding using a filename in the form .IC domainname . version\f1. .PP Client requests drive the binding process. As a request for an unbound domain comes in, the .CR ypbind process broadcasts on the network trying to find a .CR ypserv process serving maps within that NIS domain. Since the binding is established by broadcasting, at least one .CR ypserv process must exist on every network. Once a binding is established for a client, it is given to subsequent client requests. Execute .CR ypwhich to query the .CR ypbind process (local and remote) for its current binding (see .IR ypwhich (1)). .PP Bindings are verified before they are given to a client process. If .CR ypbind is unable to transact with the .CR ypserv process it is bound to, it marks the domain as unbound, tells the client process that the domain is unbound, and tries to bind again. Requests received for an unbound domain fail immediately. Generally, a bound domain is marked as unbound when the node running .CR ypserv crashes or is overloaded. In such a case, .CR ypbind binds to any NIS server (typically one that is less heavily loaded) that is available on the network. .PP The .CR ypbind daemon also accepts requests to set its binding for a particular domain. .CR ypset accesses the .CR Set_domain facility; it is for unsnarling messes and is not for casual use. .SS Options .CR ypserv recognizes the following options: .RS .TP 15 .CI -l \0log_file Log diagnostic and error messages to the file, .IR log_file . .IP If .CR ypserv is started without the .CR -l option, .CR ypserv writes its messages to .CR /var/yp/ypserv.log if that file exists. .IP If .CR ypbind is started without the .CR -l option, .CR ypbind writes its messages directly to the system console, .CR /dev/console . .IP Information logged to the file includes the date and time of the message, the host name, the process id and name of the function generating the message, and the message itself. Note that different services can share a single log file since enough information is included to uniquely identify each message. .RE .PP .CR ypbind recognizes the following options: .RS .TP 15 .CI -l \0log_file Log diagnostic and error messages to the file, .IR log_file . See the description above. .TP .CR -s Secure. When specified, only NIS servers bound to a reserved port are used. This allows for a slight increase in security in completely controlled environments, where there are no computers operated by untrusted individuals. It offers no real increase in security. .TP .CR -ypset Allow .CR ypset to be used to change the binding (see .IR ypset (1M)). For maximum security, this option should be used only when debugging the network from a remote machine. .TP .CR -ypsetme Allow .CR ypset to be issued from this machine (see .IR ypset (1M)). Security is based on IP address checking, which can be defeated on networks where untrusted individuals may inject packets. This option is not recommended. .RE .SH AUTHOR .CR ypserv , .CR ypbind , and .CR ypxfrd were developed by Sun Microsystems, Inc. .SH FILES .TP 35 .CI /var/yp/binding/ domainname . version These files cache the last successful binding created for the given domain, in order to to speed up the binding process. When a binding is requested, these files are checked for validity and then used. .TP .CR /var/yp/securenets This file is read by .CR ypxfrd and .CR ypserv . It contains a list of IP addresses that these servers will allow a binding to. .TP .CR /var/yp/secureservers This file is read by ypbind. It contains a list of IP addresses that ypbind will receive a binding from. .SH SEE ALSO domainname(1), ypcat(1), ypmatch(1), yppasswd(1), ypwhich(1), makedbm(1M), rpcinfo(1M), ypinit(1M), ypmake(1M), yppasswdd(1M), yppoll(1M), yppush(1M), ypset(1M), ypxfr(1M), ypclnt(3C), yppasswd(3N), ypfiles(4). .\" .\" index@\f4ypserv\f1: Network Information Service (NIS) server processes@@@\f3ypserv(1M)\f1 .\" index@\f4ypxfrd\f1: Network Information Service (NIS) transfer processes@@@\f3ypserv(1M)\f1 .\" index@\f4ypbind\f1: Network Information Service (NIS) binder processes@@@\f3ypserv(1M)\f1 .\" index@Network Information Service (NIS) binder processes@@@\f3ypserv(1M)\f1 .\" index@NIS (Network Information Service) binder processes@@@\f3ypserv(1M)\f1 .\" index@binder processes, Network Information Service (NIS)@@@\f3ypserv(1M)\f1 .\" index@processes, Network Information Service (NIS) binder@@@\f3ypserv(1M)\f1 .\" .\" toc@\f3ypserv(1M)\f1: \f4ypserv\f1, \f4ypbind\f1, \f4ypxfrd\f1@@@Network Information Service (NIS) server and binder processes .\" toc@\f4ypbind\f1:\0\0Network Information Service (NIS) binder processes@@@\f1see \f3ypserv(1M)\f1 .\" toc@\f4ypxfrd\f1:\0\0Network Information Service (NIS) transfer processes@@@\f1see \f3ypserv(1M)\f1 .\" .\" links@ypserv.1m ypbind.1m .\" links@ypserv.1m ypxfrd.1m .\" $Header: sysconf.2,v 72.10 94/12/08 16:33:04 ssa Exp $ .TA s .TH sysconf 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sysconf() \- get configurable system variables .SH SYNOPSIS .C "#include " .PP .C "long sysconf(int name);" .PP .C "int CPU_IS_PA_RISC(long cpuvers);" .SH DESCRIPTION The .CR sysconf() system call provides a way for applications to determine the current value of a configurable limit or variable. .PP The .I name argument represents the system variable being queried. .PP The following table lists the configuration variables whose values can be determined by calling .CR sysconf() , and for each variable, the associated value of the .I name argument and the value returned: .PP .in 0 \" override left margin (next .PP restores it) .TS tab(:); cB cB cB lf4 lf4 lw(2.4i). Variable:Value for \f2name\fP:Value Returned _ AES_OS_VERSION:_SC_AES_OS_VERSION:T{ Version number of OSF/AES OSC supported T} .ift .sp .5v .ifn .sp 1v ARG_MAX:_SC_ARG_MAX:T{ Maximum total length of the arguments for .CR exec() in bytes, including environment data (see .IR exec (2)) T} .ift .sp .5v .ifn .sp 1v ATEXIT_MAX:_SC_ATEXIT_MAX:T{ Maximum number of functions that can be registered with .CR atexit() (see .IR atexit (2)) T} .ift .sp .5v .ifn .sp 1v BC_BASE_MAX:_SC_BC_BASE_MAX:T{ Maximum ibase (input number radix) and obase (output number radix) allowed by .CR bc (see .IR bc (1)) T} .ift .sp .5v .ifn .sp 1v BC_DIM_MAX:_SC_BC_DIM_MAX:T{ Maximum number of elements in an array permitted by .CR bc (see .IR bc (1)) T} .ift .sp .5v .ifn .sp 1v BC_SCALE_MAX:_SC_BC_SCALE_MAX:T{ Maximum scale factor (number of digits to the right of the decimal point) allowed by .CR bc (see .IR bc (1)) T} .ift .sp .5v .ifn .sp 1v BC_STRING_MAX:_SC_BC_STRING_MAX:T{ Maximum length of strings allowed by .CR bc (see .IR bc (1)) T} .ift .sp .5v .ifn .sp 1v CHILD_MAX:_SC_CHILD_MAX:T{ Maximum number of simultaneous processes per user ID (see .IR fork (2)) T} .ift .sp .5v .ifn .sp 1v CLK_TCK:_SC_CLK_TCK:T{ Number of clock intervals per second for .CR times() (see .IR times (2)) T} .ift .sp .5v .ifn .sp 1v CLOCKS_PER_SEC:_SC_CLOCKS_PER_SEC:T{ Number of clock ticks per second for .CR clock() (see .IR clock (3C)) T} .ift .sp .5v .ifn .sp 1v COLL_WEIGHTS_MAX:_SC_COLL_WEIGHTS_MAX:T{ Maximum number of weights that can be assigned to an entry of the .CR "LC_COLLATE order" keyword in a .CR localedef input file (see .IR localedef (1M)) T} .ift .sp .5v .ifn .sp 1v CPU_KEYBITS1:_SC_CPU_KEYBITS1:T{ Processor Extensions (see below) T} .ift .sp .5v .ifn .sp 1v CPU_VERSION:_SC_CPU_VERSION:T{ Version of CPU architecture (see below) T} .ift .sp .5v .ifn .sp 1v EXPR_NEST_MAX:_SC_EXPR_NEST_MAX:T{ Maximum parenthesis nesting level for .CR expr expressions (see .IR expr (1)) T} .ift .sp .5v .ifn .sp 1v IO_TYPE:_SC_IO_TYPE:T{ Type of I/O drivers the kernel supports, currently, only the value .CR IO_TYPE_CDIO T} .ift .sp .5v .ifn .sp 1v LINE_MAX:_SC_LINE_MAX:T{ Maximum number of bytes in an input line (including the newline) for POSIX.2 utilities T} .ift .sp .5v .ifn .sp 1v NGROUPS_MAX:_SC_NGROUPS_MAX:T{ Maximum number of simultaneous supplementary group IDs per process T} .ift .sp .5v .ifn .sp 1v OPEN_MAX:_SC_OPEN_MAX:T{ Maximum number of files that one process can have open at one time T} .ift .sp .5v .ifn .sp 1v PAGE_SIZE:_SC_PAGE_SIZE:T{ Kernel memory page size T} .ift .sp .5v .ifn .sp 1v PASS_MAX:_SC_PASS_MAX:T{ Maximum number of significant bytes in a password T} .ift .sp .5v .ifn .sp 1v POSIX_FSYNC:_SC_FSYNC:T{ Positive if the File Synchronization option is supported (see .IR fsync (2)) T} .ift .sp .5v .ifn .sp 1v POSIX_JOB_CONTROL:_SC_JOB_CONTROL:T{ Positive if the system supports POSIX job control; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX_PRIORITY_SCHEDULING:_SC_PRIORITY_SCHEDULING:T{ Positive if the system supports POSIX.4 priority scheduling; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX_SAVED_IDS:_SC_SAVED_IDS:T{ Positive if each process has a saved set-user-ID and a saved set-group-ID; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX_SYNCHRONIZED_IO:_SC_SYNCHRONIZED_IO:T{ Positive if the Synchronized IO option is supported (see .IR open (2)) T} .ift .sp .5v .ifn .sp 1v POSIX_TIMERS:_SC_TIMERS:T{ Positive if the system supports POSIX.4 clocks and timers; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX_VERSION:_SC_VERSION:T{ Approval date of the POSIX.1 Standard (such as 199009 for POSIX.1-1990) to which the system conforms. This value indicates the year (first four digits) and month (next two digits) that the standard was approved by the IEEE Standards Board. T} .ift .sp .5v .ifn .sp 1v POSIX2_C_BIND:_SC_2_C_BIND:T{ Equal to 1 if the POSIX.2 C Language Bindings Option is available through the .CR c89 utility; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX2_C_DEV:_SC_2_C_DEV:T{ Equal to 1 if the POSIX.2 C Language Development Utilities Option is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX2_C_VERSION:_SC_2_C_VERSION:T{ Current version of the POSIX.2 C Language Binding Option supported (same format as .CR _POSIX_VERSION ); \(mi1 otherwise. T} .ift .sp .5v .ifn .sp 1v POSIX2_FORT_DEV:_SC_2_FORT_DEV:T{ Equal to 1 if the POSIX.2 FORTRAN Development Utilities Option is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX2_FORT_RUN:_SC_2_FORT_RUN:T{ Equal to 1 if the POSIX.2 Fortran Runtime Utilities Option is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX2_LOCALEDEF:_SC_2_LOCALEDEF:T{ Equal to 1 if locales can be created with the POSIX.2 .IR localedef utility; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX2_SW_DEV:_SC_2_SW_DEV:T{ Equal to 1 if the POSIX.2 Software Development Utilities Option is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX2_UPE:_SC_2_UPE:T{ Equal to 1 if the POSIX.2 User Portability Utilities Option is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX2_VERSION:_SC_2_VERSION:T{ Current version of POSIX.2 (same format as .CR _POSIX_VERSION ) T} .ift .sp .5v .ifn .sp 1v PROC_RSRC_MGR:_SC_PROC_RSRC_MGR:T{ Equal to 1 if the optional HP Process Resource Management (PRM) software is installed and configured; 0 otherwise (see .IR prmconfig (1)) T} .ift .sp .5v .ifn .sp 1v RE_DUP_MAX:_SC_RE_DUP_MAX:T{ Maximum number of repeated occurrences of a regular expression permitted when using the interval notation .CI \e{ m , n \e} (see .IR regcomp (3C)) T} .ift .sp .5v .ifn .sp 1v SECURITY_CLASS:_SC_SECURITY_CLASS:T{ .CR SEC_CLASS-NONE (No DoD security level supported) T} .ift .sp .5v .ifn .sp 1v STREAM_MAX:_SC_STREAM_MAX:T{ Maximum number of stdio streams that one process can have open at one time T} .ift .sp .5v .ifn .sp 1v TIMER_MAX:_SC_TIMER_MAX:T{ Maximum number of POSIX.4 timers per process, if POSIX.4 timers are supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v TZNAME_MAX:_SC_TZNAME_MAX:T{ Maximum number of bytes in a time zone name for the .CR TZ environment variable T} .ift .sp .5v .ifn .sp 1v XOPEN_CRYPT:_SC_XOPEN_CRYPT:T{ Equal to 1 if the X/Open Encryption Feature Group is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v XOPEN_ENH_I18N:_SC_XOPEN_ENH_I18N:T{ Equal to 1 if the X/Open Enhanced Internationalization Feature Group is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v XOPEN_SHM:_SC_XOPEN_SHM:T{ Equal to 1 if the X/Open Shared Memory Feature Group is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v XOPEN_VERSION:_SC_XOPEN_VERSION:T{ Issue number of .IR "X/Open Portability Guide" supported T} _ .TE .PP Some of the variables in the table are defined as constants in .CR (see .IR limits (5)). The associated values of the .I name argument are defined in .CR . .PP The possible values of the .CR CPU_VERSION variable returned by .CR sysconf(_SC_CPU_VERSION) and their meanings are: .PP .TS center tab(:); cB cB lf4p+1w(15n) lw(3i). Value:Meaning _ CPU_PA_RISC1_0:HP Precision Architecture RISC Version 1.0 CPU_PA_RISC1_1:HP Precision Architecture RISC Version 1.1 .\"CPU_PA_RISC2_0:HP Precision Architecture RISC Version 2.0 .TE .PP The .CR CPU_IS_PA_RISC() function classifies .IR cpuvers , a value of the .CR CPU_VERSION variable, as to its processor family. .PP The availability of architecture specific instructions is indicated by the key bit data returned by .CR sysconf(_SC_CPU_KEYBITS1) . Upon successful completion, the data returned will be the logical OR of the defined values for the features supported. .PP The possible values returned by .CR sysconf(_SC_CPU_KEYBITS1) and their meanings are shown in the following table. .PP .TS center tab(:); cB cB lf4p+1w(15n) lw(3i). Return Value:Instruction Supported _ HARITH:Halfword parallel add, subtract, and average HSHIFT:Halfword parallel shift-and-add .TE .PP .SH RETURN VALUE Upon successful completion, .CR sysconf() returns the value of the named variable. If the value of .I name is not valid, .CR sysconf() returns .CR \(mi1 and sets .CR errno to indicate the error. If the variable corresponding to .I name is not defined, .CR sysconf() returns .CR \(mi1 , but does not change .CR errno . .PP .CR CPU_IS_PA_RISC() returns positive nonzero if .IR cpuvers is an HP PA-RISC processor; zero if not. .ift .br .ift .ne 8 .SH ERRORS If .CR sysconf() fails, the value of .CR errno (see .IR errno (2)) is set to: .RS .TP 15 [EINVAL] The value of .I name is not valid. .RE .SH EXAMPLES The following example determines the number of times the system clock ticks each second: .IP .C "#include " .IP .C "long ticks;" .br \0\0... .IP .C "ticks = sysconf(_SC_CLK_TCK);" .PP The following example determines if the current processor is an HP PA-RISC machine: .IP .C "#include " .IP .C "if (CPU_IS_PA_RISC(sysconf(_SC_CPU_VERSION)))" .br \0\0... .SH WARNINGS .CR CPU_IS_PA_RISC() is implemented as a macro. .PP Normally, the values returned from .CR sysconf() do not change during the lifetime of the calling process. However, the value of the symbolic constant .CR _POSIX_VERSION and thus the value of .CR sysconf(_SC_VERSION) can vary under certain circumstances. If either of the feature test macros .CR _POSIX1_1988 or .CR _XPG3 is defined by the programmer prior to including .CR , the value of .CR _POSIX_VERSION is defined as .CR 198808 , in conformance with POSIX.1-1988, FIPS 151-1, and XPG3. Otherwise, the value of .CR _POSIX_VERSION is defined as .CR 199009 , in conformance with POSIX.1-1990. .PP Similarly, the value of the symbolic constant .CR _XOPEN_VERSION and thus the value of .CR sysconf(_SC_XOPEN_VERSION) can vary under certain circumstances. If the feature test macro .CR _XPG3 is defined by the programmer prior to including .CR , the value of .CR _XOPEN_VERSION is defined as .CR 3 , in conformance with XPG3. Otherwise, the value of .CR _XOPEN_VERSION is defined as .CR 4 , in conformance with XPG4. .PP See .IR stdsyms (5) for more information about these feature test macros. .SH AUTHOR .CR sysconf() was developed by HP and POSIX. .PP .CR CPU_IS_PA_RISC() was developed by HP. .SH SEE ALSO getconf(1), atexit(2), exec(2), fork(2), getrlimit(2), pathconf(2), times(2), clock(3C), regcomp(3C), limits(5), stdsyms(5), unistd(5), x_open(5). .PP HP Process Resource Manager: prmconfig(1) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR sysconf() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.2, POSIX.4" .\" .\" index@\f4sysconf()\f1 \- get configurable system variables@@@\f3sysconf(2)\f1 .\" index@\f1get configurable system variables@@@\f3sysconf(2)\f1 .\" index@\f1configurable system variables, get@@@\f3sysconf(2)\f1 .\" index@\f1system variables, get configurable@@@\f3sysconf(2)\f1 .\" index@\f1variables, system, get configurable@@@\f3sysconf(2)\f1 .\" index@\f1processor type, determine@@@\f3sysconf(2)\f1 .\" .\" toc@\f3sysconf(2)\f1:\0\0\f4sysconf()\f1@@@get configurable system variables\f1 .\" .\" links@sysconf.2 CPU_IS_PA_R.2 .\" $Header: rtsched.2,v 72.6 94/11/14 15:26:03 ssa Exp $ .TA r .TH rtsched 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtsched: sched_get_priority_max(), sched_get_priority_min(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setparam(), sched_setscheduler(), sched_yield(), PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX() \- real-time scheduling operations .SH SYNOPSIS .nf .C "#include " .PP .C "int sched_setparam(" .C " pid_t pid," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getparam(" .C " pid_t pid," .C " struct sched_param *param" .C ");" .PP .C "int sched_setscheduler(" .C " pid_t pid," .C " int policy," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getscheduler(" .C " pid_t pid" .C ");" .PP .C "int sched_yield();" .PP .C "int sched_get_priority_max(" .C " int policy" .C ");" .PP .C "int sched_get_priority_min(" .C " int policy" .C ");" .PP .C "int sched_rr_get_interval(" .C " pid_t pid," .C " struct timespec *interval" .C ");" .PP .C "int PRI_POSIX_TO_HPUX(" .C " const struct sched_param *param" .C ");" .PP .C "int PRI_HPUX_TO_POSIX(" .C " int pri," .C " struct sched_param *param" .C ");" .fi .SH DESCRIPTION .SS Summary .TP 35 .PD 0 .CR sched_get_priority_max() Get maximum scheduling policy .TP .CR sched_get_priority_min() Get minimum scheduling policy .TP .CR sched_getparam() Get scheduling parameters of process .TP .CR sched_getscheduler() Get scheduling policy of process .TP .CR sched_rr_get_interval() Update execution time limit for a process .TP .CR sched_setparam() Set scheduling parameters of process .TP .CR sched_setscheduler() Set scheduling policy and parameters of process .TP .CR sched_yield() Requeue current process in process list .TP .CR PRI_HPUX_TO_POSIX() Convert HP-UX priority to POSIX .TP .CR PRI_POSIX_TO_HPUX() Convert POSIX priority to HP-UX .PD .SS sched_setparam() The .CR sched_setparam() function sets the scheduling parameters of the process specified by .I pid to the values specified by the .I sched_param structure pointed to by .IR param . The value of the .I sched_priority member in the .I param structure is any integer within the inclusive priority range for the current scheduling policy of the process specified by .IR pid . .PP Higher numerical values for the priority represent higher (stronger) priorities. Note that this is different from the .CR SCHED_HPUX , .CR SCHED_TIMESHARE , and .CR SCHED_RTPRIO scheduling policies, where higher numerical values represent lower (weaker) priorities. See the .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() functions, and .CR SCHED_RTPRIO and .CR SCHED_OTHER in "Scheduling Policies" below. .PP If a process described by .I pid exists and if the calling process has permission, the scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are set for the calling process. .PP Only a superuser may change the scheduling parameters of another process. .PP The calling process must have the appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setparam() . .PP The target process, whether it is running or not running, will resume execution after all other runnable processes of equal or greater priority have been scheduled to run. .PP If the priority of the process specified by the .I pid argument is set higher than that of the lowest priority running process, and if the specified process is ready to run, the process specified by the .I pid argument will preempt a lowest-priority running process. Similarly, if the process calling .CR sched_setparam() sets its own priority lower than that of one or more other nonempty process lists, then the process that is the head of the highest priority list will also preempt the calling process. Thus, in either case, the originating process may not receive notification of the completion of the requested priority change until the higher priority process has executed. .SS sched_getparam() The .CR sched_getparam() function returns the scheduling parameters of a process specified by .I pid in the .I sched_param structure pointed to by .IR param . .PP If a process described by .I pid exists, the scheduling parameters are returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are returned for the calling process. .SS sched_setscheduler() The .CR sched_setscheduler() function sets the scheduling policy and scheduling parameters of the process specified by .I pid to .I policy and the parameters specified in the .I sched_param structure pointed to by .IR param , respectively. The value of the .I sched_priority member in the .I param structure can be any integer within the inclusive priority range for the scheduling policy specified by .IR policy . .PP The possible values for the .I policy parameter are defined in the header file .CR , and mentioned below. .PP If a process described by .I pid exists, the scheduling policy and scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy and scheduling parameters are set for the calling process. .PP Appropriate privileges are required to change the scheduling parameters of another process. .PP The calling process must have appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setscheduler() . .PP The .CR sched_setscheduler() function is considered successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by .I pid to the values specified by .I policy and the structure .IR param , respectively. .PP .SS sched_getscheduler() The .CR sched_getscheduler() function returns the scheduling policy of the process specified by .IR pid . .PP The values that can be returned by .CR sched_getscheduler() are defined in the header file .CR (see .CR sched_setscheduler() ). .PP If a process described by .I pid exists, the scheduling policy is returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy is returned for the calling process. .SS sched_yield() The .CR sched_yield() function forces the running process to relinquish the processor until it again becomes the head of its process list. It takes no arguments. .SS sched_get_priority_max() .SS sched_get_priority_min() The .CR sched_get_priority_max() and .CR sched_get_priority_min() functions return the appropriate maximum or minimum, respectively, for the scheduling policy specified by .IR policy . .PP The value of .I policy must be one of the scheduling policy values defined in .CR . .SS sched_rr_get_interval() The .CR sched_rr_get_interval() function updates the .I timespec structure referenced by the .I interval argument to contain the current execution time limit (that is, time quantum) for the process indicated by .I pid under the .CR SCHED_RR policy, at which a scheduling decision will be made when another process at the same priority is ready to execute. If .I pid is zero, the current execution time limit for the calling process is returned. .SS PRI_HPUX_TO_POSIX() .SS PRI_POSIX_TO_HPUX() These two functions serve to map (translate) the range of HP-UX priorities into the POSIX.4 model. These translations are necessary because the POSIX.4 standard chose .I larger numbers to represent stronger priorities and the existing HP-UX behavior, which must be maintained for backward compatibility, uses .I smaller numbers for stronger priorities. .PP The .CR PRI_HPUX_TO_POSIX() function returns, in the .I sched_param structure pointed to by .IR param , the POSIX.4 scheduling priority corresponding to the HP-UX priority passed in the argument .IR pri . The argument .I pri must contain a valid HP-UX priority. .PP The .CR PRI_POSIX_TO_HPUX() function returns an HP-UX process priority corresponding to the .I sched_priority member in the .I sched_param structure specified. The value of the .I sched_priority member can be any integer within the inclusive priority range for the .CR SCHED_HPUX scheduling policy. The HP-UX priority returned is comparable to the values returned by .CR getpriority() (see .IR getpriority (2)). .SS Scheduling Policies The scheduling policies described are defined in terms of a conceptual model, which contains a set of process lists. There is, conceptually, one process list for each priority. Any runnable process may be in any process list. Multiple scheduling policies are provided. Each nonempty list is ordered, and contains a head as one end of its order, and a tail as the other. The purpose of a scheduling policy is to define the allowable operations on this set of lists (for example, moving processes between and within lists). .PP Each process will be controlled by an associated scheduling policy and priority. These parameters may be specified by explicit application execution of the .CR sched_setscheduler() or .CR sched_setparam() functions. .PP Associated with each policy is a priority range. The priority ranges for each policy can (but need not) overlap the priority ranges of other policies. .PP When a process is to be selected to run, the process that is at the head of the highest priority nonempty process list is chosen. It is then removed from its process list. .PP The following scheduling policies are defined: .RS .TP 15 .CR SCHED_FIFO First in-first out (FIFO) scheduling policy. .IP Processes scheduled under this policy are chosen from a process list that is ordered by the time its processes have been in the list without being executed. Generally, the head of the list is the process that has been in the list the longest time, and the tail is the process that has been in the list the shortest time. .IP Under the .CR SCHED_FIFO policy, the modification of the definitional process lists is as follows: .RS .RS .TP 3 \(bu When a running process becomes a preempted process, it becomes the head of the process list for its priority. .TP \(bu When a blocked process becomes a runnable process, it becomes the tail of the process list for its priority. .TP \(bu When a running process calls the .CR sched_setscheduler() function, the process specified in the function call is modified to the policy and priority specified by the .I param argument. If the process whose policy and priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process calls the .CR sched_setparam() function, the priority of the process specified in the function call is modified to the priority specified by the .I param argument. If the process whose priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process issues the .CR sched_yield() function, the process becomes the tail of the process list for its priority. .TP \(bu At no other time is the position of a process with this scheduling policy within the process lists affected. .RE .RE .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_FIFO is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR Round-robin scheduling policy, with a per-system time slice (time quantum). .IP This policy is identical to the .CR SCHED_FIFO policy with the additional condition that when the implementation detects that a running process has been executing as a running process for a time period of length returned by the function .CR sched_rr_get_interval() , or longer, the process becomes the tail of its process list, and the head of that process list is removed and made a running process. .IP The effect of this policy is to ensure that if there are multiple .CR SCHED_RR processes at the same priority, one of them will not monopolize the processor. An application should not rely only on the use of .CR SCHED_RR to ensure application progress among multiple processes if the application includes processes using the .CR SCHED_FIFO policy at the same or higher priority levels, or .CR SCHED_RR processes at a higher priority level. .IP A process under this policy that is preempted and subsequently resumes execution as a running process completes the unexpired portion of its round-robin interval time period. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR2 Round-robin scheduling policy, with a per-priority time slice (time quantum). .IP This policy is identical to the .CR SCHED_RR policy, except that the round-robin time slice interval returned by .CR sched_rr_get_interval() depends upon the priority of the specified process. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RTPRIO Real-time scheduling policy with nondecaying priorities (like .CR SCHED_FIFO and .CR SCHED_RR ) with a priority range between the POSIX real-time policies and the HP-UX policies, described below (see .IR rtprio(2)). .IP For processes executing under this policy, the implementation must use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RTPRIO is provided as the parameter. Note that, for the .CR SCHED_RTPRIO scheduling policy, .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_RTPRIO is weaker than the weakest priority in the priority ranges for any of the POSIX policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .TP .CR SCHED_OTHER " (" SCHED_HPUX ", " SCHED_TIMESHARE ) Another scheduling policy. .IP The .CR SCHED_OTHER policy, also known as .CR SCHED_HPUX and .CR SCHED_TIMESHARE , provides a way for applications to indicate, in a portable way, that they no longer need a real-time scheduling policy. .IP For processes executing under this policy, the implementation can use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_OTHER is provided as the parameter. Note that for the .CR SCHED_OTHER scheduling policy, like .CR SCHED_RTPRIO , .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_OTHER is weaker than the weakest priority in the priority ranges for any of the other policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .RE .SH RETURN VALUE The functions return the following values: .SS sched_getparam() .SS sched_rr_get_interval() .SS sched_setparam() .SS sched_yield() .SS PRI_HPUX_TO_POSIX() .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_setscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the former scheduling policy of the specified process. .TP .CR -1 Failure. The policy and scheduling parameters remain unchanged. .CR errno is set to indicate the error. .PD .RE .SS sched_getscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the scheduling policy of the specified process. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the maximum or minimum value, respectively. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS PRI_POSIX_TO_HPUX() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the the HP-UX priority corresponding to the .I sched_priority member in the .I param structure. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If the functions fail, .CR errno is set to one of the following values. .SS sched_setparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] One or more of the requested scheduling parameters is outside the range defined for the scheduling policy of the specified .IR pid . .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling parameters for the specified process, or does not have the appropriate privilege to invoke .CR sched_setparam() . .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_setscheduler() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] The value of the .I policy parameter is invalid, or one or more of the parameters contained in .I param is outside the valid range for the specified scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling policy of the specified process. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getscheduler() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_yield() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP 15 [EINVAL] The value of the .I policy parameter does not represent a defined scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .RE .SS sched_rr_get_interval() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS PRI_POSIX_TO_HPUX() .RS .TP 15 [EINVAL] The priority specified in the .I sched_priority member of the .I param argument is outside the range defined for the .CR SCHED_HPUX scheduling policy. .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS PRI_HPUX_TO_POSIX() .RS .TP 15 [EINVAL] The priority specified in the .I pri argument is not a valid HP-UX priority. .TP [ENOSYS] The function is not supported by this implementation. .RE .SH EXAMPLES Change the calling process to use the strongest .CR FIFO priority: .IP .nf .C "#include " .IP .C "struct sched_param param;" .C "int maxpri;" .IP .C "maxpri = sched_get_priority_max(SCHED_FIFO);" .C "if (maxpri == -1) {" .C " perror(""sched_get_priority_max() failed"");" .C " exit(1);" .C "}" .C "param.sched_priority = maxpri;" .C "if (sched_setscheduler(getpid(), SCHED_FIFO, ¶m) == -1) {" .C " perror(""sched_setscheduler() failed"");" .C " exit(1);" .C "}" .fi .SH AUTHOR The .CI sched_ * () functions were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .PP .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() were developed by HP. .SH SEE ALSO rtsched(1), rtprio(2). .SH STANDARDS CONFORMANCE .CR sched_get_priority_max() ": POSIX.4" .PP .CR sched_get_priority_min() ": POSIX.4" .PP .CR sched_getparam() ": POSIX.4" .PP .CR sched_getscheduler() ": POSIX.4" .PP .CR sched_rr_getinterval() ": POSIX.4" .PP .CR sched_setparam() ": POSIX.4" .PP .CR sched_setscheduler() ": POSIX.4" .PP .CR sched_yield() ": POSIX.4" .\" .\" index entries: .\" index@\f1rtsched\f1 \- real time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f4PRI_HPUX_TO_POSIX()\f1 \- return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f4PRI_POSIX_TO_HPUX()\f1 \- return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_max()\f1 \- return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_min()\f1 \- return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_getparam()\f1 \- return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_getscheduler()\f1 \- return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_rr_get_interval()\f1 \- update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4sched_setparam()\f1 \- set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_setscheduler()\f1 \- set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_yield()\f1 \- force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1operations, real-time scheduling@@@\f3rtsched(2)\f1 .\" index@\f1real-time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f1return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1scheduling operations, real-time@@@\f3rtsched(2)\f1 .\" index@\f1scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" links entries: .\" links@rtsched.2 PRI_HPUX_TO.2 .\" links@rtsched.2 PRI_POSIX_T.2 .\" links@rtsched.2 pri_hpux_to.2 .\" links@rtsched.2 pri_posix_t.2 .\" links@rtsched.2 sched_get_p.2 .\" links@rtsched.2 sched_getpa.2 .\" links@rtsched.2 sched_getsc.2 .\" links@rtsched.2 sched_rr_ge.2 .\" links@rtsched.2 sched_setpa.2 .\" links@rtsched.2 sched_setsc.2 .\" links@rtsched.2 sched_yield.2 .\" toc entries: .\" toc@\f3rtsched(2)\f1:\0\0\f4sched_get_priority_max()\f1, \f4sched_get_priority_min()\f1,\n\f4sched_getparam()\f1, \f4sched_getscheduler()\f1, \f4sched_rr_get_interval()\f1,\n\f4sched_setparam()\f1, \f4sched_setscheduler()\f1, \f4sched_yield()\f1,\n\f4PRI_HPUX_TO_POSIX()\f1, \f4PRI_POSIX_TO_HPUX()\f1@@@real-time scheduling operations .\" toc@\f4PRI_HPUX_TO_POSIX()\f1:\0\0return POSIX.4 process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4PRI_POSIX_TO_HPUX()\f1:\0\0return HP-UX process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_max()\f1:\0\0return maximum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_min()\f1:\0\0return minimum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getparam()\f1:\0\0return scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getscheduler()\f1:\0\0return scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_rr_get_interval()\f1:\0\0update execution time limit@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setparam()\f1:\0\0set scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setscheduler()\f1:\0\0set scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_yield()\f1:\0\0force process to relinquish processor@@@\f1see \f3rtsched(2)\f1 .\" $Header: rtsched.2,v 72.6 94/11/14 15:26:03 ssa Exp $ .TA r .TH rtsched 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtsched: sched_get_priority_max(), sched_get_priority_min(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setparam(), sched_setscheduler(), sched_yield(), PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX() \- real-time scheduling operations .SH SYNOPSIS .nf .C "#include " .PP .C "int sched_setparam(" .C " pid_t pid," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getparam(" .C " pid_t pid," .C " struct sched_param *param" .C ");" .PP .C "int sched_setscheduler(" .C " pid_t pid," .C " int policy," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getscheduler(" .C " pid_t pid" .C ");" .PP .C "int sched_yield();" .PP .C "int sched_get_priority_max(" .C " int policy" .C ");" .PP .C "int sched_get_priority_min(" .C " int policy" .C ");" .PP .C "int sched_rr_get_interval(" .C " pid_t pid," .C " struct timespec *interval" .C ");" .PP .C "int PRI_POSIX_TO_HPUX(" .C " const struct sched_param *param" .C ");" .PP .C "int PRI_HPUX_TO_POSIX(" .C " int pri," .C " struct sched_param *param" .C ");" .fi .SH DESCRIPTION .SS Summary .TP 35 .PD 0 .CR sched_get_priority_max() Get maximum scheduling policy .TP .CR sched_get_priority_min() Get minimum scheduling policy .TP .CR sched_getparam() Get scheduling parameters of process .TP .CR sched_getscheduler() Get scheduling policy of process .TP .CR sched_rr_get_interval() Update execution time limit for a process .TP .CR sched_setparam() Set scheduling parameters of process .TP .CR sched_setscheduler() Set scheduling policy and parameters of process .TP .CR sched_yield() Requeue current process in process list .TP .CR PRI_HPUX_TO_POSIX() Convert HP-UX priority to POSIX .TP .CR PRI_POSIX_TO_HPUX() Convert POSIX priority to HP-UX .PD .SS sched_setparam() The .CR sched_setparam() function sets the scheduling parameters of the process specified by .I pid to the values specified by the .I sched_param structure pointed to by .IR param . The value of the .I sched_priority member in the .I param structure is any integer within the inclusive priority range for the current scheduling policy of the process specified by .IR pid . .PP Higher numerical values for the priority represent higher (stronger) priorities. Note that this is different from the .CR SCHED_HPUX , .CR SCHED_TIMESHARE , and .CR SCHED_RTPRIO scheduling policies, where higher numerical values represent lower (weaker) priorities. See the .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() functions, and .CR SCHED_RTPRIO and .CR SCHED_OTHER in "Scheduling Policies" below. .PP If a process described by .I pid exists and if the calling process has permission, the scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are set for the calling process. .PP Only a superuser may change the scheduling parameters of another process. .PP The calling process must have the appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setparam() . .PP The target process, whether it is running or not running, will resume execution after all other runnable processes of equal or greater priority have been scheduled to run. .PP If the priority of the process specified by the .I pid argument is set higher than that of the lowest priority running process, and if the specified process is ready to run, the process specified by the .I pid argument will preempt a lowest-priority running process. Similarly, if the process calling .CR sched_setparam() sets its own priority lower than that of one or more other nonempty process lists, then the process that is the head of the highest priority list will also preempt the calling process. Thus, in either case, the originating process may not receive notification of the completion of the requested priority change until the higher priority process has executed. .SS sched_getparam() The .CR sched_getparam() function returns the scheduling parameters of a process specified by .I pid in the .I sched_param structure pointed to by .IR param . .PP If a process described by .I pid exists, the scheduling parameters are returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are returned for the calling process. .SS sched_setscheduler() The .CR sched_setscheduler() function sets the scheduling policy and scheduling parameters of the process specified by .I pid to .I policy and the parameters specified in the .I sched_param structure pointed to by .IR param , respectively. The value of the .I sched_priority member in the .I param structure can be any integer within the inclusive priority range for the scheduling policy specified by .IR policy . .PP The possible values for the .I policy parameter are defined in the header file .CR , and mentioned below. .PP If a process described by .I pid exists, the scheduling policy and scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy and scheduling parameters are set for the calling process. .PP Appropriate privileges are required to change the scheduling parameters of another process. .PP The calling process must have appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setscheduler() . .PP The .CR sched_setscheduler() function is considered successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by .I pid to the values specified by .I policy and the structure .IR param , respectively. .PP .SS sched_getscheduler() The .CR sched_getscheduler() function returns the scheduling policy of the process specified by .IR pid . .PP The values that can be returned by .CR sched_getscheduler() are defined in the header file .CR (see .CR sched_setscheduler() ). .PP If a process described by .I pid exists, the scheduling policy is returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy is returned for the calling process. .SS sched_yield() The .CR sched_yield() function forces the running process to relinquish the processor until it again becomes the head of its process list. It takes no arguments. .SS sched_get_priority_max() .SS sched_get_priority_min() The .CR sched_get_priority_max() and .CR sched_get_priority_min() functions return the appropriate maximum or minimum, respectively, for the scheduling policy specified by .IR policy . .PP The value of .I policy must be one of the scheduling policy values defined in .CR . .SS sched_rr_get_interval() The .CR sched_rr_get_interval() function updates the .I timespec structure referenced by the .I interval argument to contain the current execution time limit (that is, time quantum) for the process indicated by .I pid under the .CR SCHED_RR policy, at which a scheduling decision will be made when another process at the same priority is ready to execute. If .I pid is zero, the current execution time limit for the calling process is returned. .SS PRI_HPUX_TO_POSIX() .SS PRI_POSIX_TO_HPUX() These two functions serve to map (translate) the range of HP-UX priorities into the POSIX.4 model. These translations are necessary because the POSIX.4 standard chose .I larger numbers to represent stronger priorities and the existing HP-UX behavior, which must be maintained for backward compatibility, uses .I smaller numbers for stronger priorities. .PP The .CR PRI_HPUX_TO_POSIX() function returns, in the .I sched_param structure pointed to by .IR param , the POSIX.4 scheduling priority corresponding to the HP-UX priority passed in the argument .IR pri . The argument .I pri must contain a valid HP-UX priority. .PP The .CR PRI_POSIX_TO_HPUX() function returns an HP-UX process priority corresponding to the .I sched_priority member in the .I sched_param structure specified. The value of the .I sched_priority member can be any integer within the inclusive priority range for the .CR SCHED_HPUX scheduling policy. The HP-UX priority returned is comparable to the values returned by .CR getpriority() (see .IR getpriority (2)). .SS Scheduling Policies The scheduling policies described are defined in terms of a conceptual model, which contains a set of process lists. There is, conceptually, one process list for each priority. Any runnable process may be in any process list. Multiple scheduling policies are provided. Each nonempty list is ordered, and contains a head as one end of its order, and a tail as the other. The purpose of a scheduling policy is to define the allowable operations on this set of lists (for example, moving processes between and within lists). .PP Each process will be controlled by an associated scheduling policy and priority. These parameters may be specified by explicit application execution of the .CR sched_setscheduler() or .CR sched_setparam() functions. .PP Associated with each policy is a priority range. The priority ranges for each policy can (but need not) overlap the priority ranges of other policies. .PP When a process is to be selected to run, the process that is at the head of the highest priority nonempty process list is chosen. It is then removed from its process list. .PP The following scheduling policies are defined: .RS .TP 15 .CR SCHED_FIFO First in-first out (FIFO) scheduling policy. .IP Processes scheduled under this policy are chosen from a process list that is ordered by the time its processes have been in the list without being executed. Generally, the head of the list is the process that has been in the list the longest time, and the tail is the process that has been in the list the shortest time. .IP Under the .CR SCHED_FIFO policy, the modification of the definitional process lists is as follows: .RS .RS .TP 3 \(bu When a running process becomes a preempted process, it becomes the head of the process list for its priority. .TP \(bu When a blocked process becomes a runnable process, it becomes the tail of the process list for its priority. .TP \(bu When a running process calls the .CR sched_setscheduler() function, the process specified in the function call is modified to the policy and priority specified by the .I param argument. If the process whose policy and priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process calls the .CR sched_setparam() function, the priority of the process specified in the function call is modified to the priority specified by the .I param argument. If the process whose priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process issues the .CR sched_yield() function, the process becomes the tail of the process list for its priority. .TP \(bu At no other time is the position of a process with this scheduling policy within the process lists affected. .RE .RE .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_FIFO is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR Round-robin scheduling policy, with a per-system time slice (time quantum). .IP This policy is identical to the .CR SCHED_FIFO policy with the additional condition that when the implementation detects that a running process has been executing as a running process for a time period of length returned by the function .CR sched_rr_get_interval() , or longer, the process becomes the tail of its process list, and the head of that process list is removed and made a running process. .IP The effect of this policy is to ensure that if there are multiple .CR SCHED_RR processes at the same priority, one of them will not monopolize the processor. An application should not rely only on the use of .CR SCHED_RR to ensure application progress among multiple processes if the application includes processes using the .CR SCHED_FIFO policy at the same or higher priority levels, or .CR SCHED_RR processes at a higher priority level. .IP A process under this policy that is preempted and subsequently resumes execution as a running process completes the unexpired portion of its round-robin interval time period. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR2 Round-robin scheduling policy, with a per-priority time slice (time quantum). .IP This policy is identical to the .CR SCHED_RR policy, except that the round-robin time slice interval returned by .CR sched_rr_get_interval() depends upon the priority of the specified process. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RTPRIO Real-time scheduling policy with nondecaying priorities (like .CR SCHED_FIFO and .CR SCHED_RR ) with a priority range between the POSIX real-time policies and the HP-UX policies, described below (see .IR rtprio(2)). .IP For processes executing under this policy, the implementation must use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RTPRIO is provided as the parameter. Note that, for the .CR SCHED_RTPRIO scheduling policy, .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_RTPRIO is weaker than the weakest priority in the priority ranges for any of the POSIX policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .TP .CR SCHED_OTHER " (" SCHED_HPUX ", " SCHED_TIMESHARE ) Another scheduling policy. .IP The .CR SCHED_OTHER policy, also known as .CR SCHED_HPUX and .CR SCHED_TIMESHARE , provides a way for applications to indicate, in a portable way, that they no longer need a real-time scheduling policy. .IP For processes executing under this policy, the implementation can use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_OTHER is provided as the parameter. Note that for the .CR SCHED_OTHER scheduling policy, like .CR SCHED_RTPRIO , .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_OTHER is weaker than the weakest priority in the priority ranges for any of the other policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .RE .SH RETURN VALUE The functions return the following values: .SS sched_getparam() .SS sched_rr_get_interval() .SS sched_setparam() .SS sched_yield() .SS PRI_HPUX_TO_POSIX() .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_setscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the former scheduling policy of the specified process. .TP .CR -1 Failure. The policy and scheduling parameters remain unchanged. .CR errno is set to indicate the error. .PD .RE .SS sched_getscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the scheduling policy of the specified process. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the maximum or minimum value, respectively. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS PRI_POSIX_TO_HPUX() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the the HP-UX priority corresponding to the .I sched_priority member in the .I param structure. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If the functions fail, .CR errno is set to one of the following values. .SS sched_setparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] One or more of the requested scheduling parameters is outside the range defined for the scheduling policy of the specified .IR pid . .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling parameters for the specified process, or does not have the appropriate privilege to invoke .CR sched_setparam() . .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_setscheduler() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] The value of the .I policy parameter is invalid, or one or more of the parameters contained in .I param is outside the valid range for the specified scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling policy of the specified process. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getscheduler() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_yield() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP 15 [EINVAL] The value of the .I policy parameter does not represent a defined scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .RE .SS sched_rr_get_interval() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS PRI_POSIX_TO_HPUX() .RS .TP 15 [EINVAL] The priority specified in the .I sched_priority member of the .I param argument is outside the range defined for the .CR SCHED_HPUX scheduling policy. .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS PRI_HPUX_TO_POSIX() .RS .TP 15 [EINVAL] The priority specified in the .I pri argument is not a valid HP-UX priority. .TP [ENOSYS] The function is not supported by this implementation. .RE .SH EXAMPLES Change the calling process to use the strongest .CR FIFO priority: .IP .nf .C "#include " .IP .C "struct sched_param param;" .C "int maxpri;" .IP .C "maxpri = sched_get_priority_max(SCHED_FIFO);" .C "if (maxpri == -1) {" .C " perror(""sched_get_priority_max() failed"");" .C " exit(1);" .C "}" .C "param.sched_priority = maxpri;" .C "if (sched_setscheduler(getpid(), SCHED_FIFO, ¶m) == -1) {" .C " perror(""sched_setscheduler() failed"");" .C " exit(1);" .C "}" .fi .SH AUTHOR The .CI sched_ * () functions were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .PP .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() were developed by HP. .SH SEE ALSO rtsched(1), rtprio(2). .SH STANDARDS CONFORMANCE .CR sched_get_priority_max() ": POSIX.4" .PP .CR sched_get_priority_min() ": POSIX.4" .PP .CR sched_getparam() ": POSIX.4" .PP .CR sched_getscheduler() ": POSIX.4" .PP .CR sched_rr_getinterval() ": POSIX.4" .PP .CR sched_setparam() ": POSIX.4" .PP .CR sched_setscheduler() ": POSIX.4" .PP .CR sched_yield() ": POSIX.4" .\" .\" index entries: .\" index@\f1rtsched\f1 \- real time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f4PRI_HPUX_TO_POSIX()\f1 \- return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f4PRI_POSIX_TO_HPUX()\f1 \- return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_max()\f1 \- return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_min()\f1 \- return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_getparam()\f1 \- return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_getscheduler()\f1 \- return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_rr_get_interval()\f1 \- update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4sched_setparam()\f1 \- set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_setscheduler()\f1 \- set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_yield()\f1 \- force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1operations, real-time scheduling@@@\f3rtsched(2)\f1 .\" index@\f1real-time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f1return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1scheduling operations, real-time@@@\f3rtsched(2)\f1 .\" index@\f1scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" links entries: .\" links@rtsched.2 PRI_HPUX_TO.2 .\" links@rtsched.2 PRI_POSIX_T.2 .\" links@rtsched.2 pri_hpux_to.2 .\" links@rtsched.2 pri_posix_t.2 .\" links@rtsched.2 sched_get_p.2 .\" links@rtsched.2 sched_getpa.2 .\" links@rtsched.2 sched_getsc.2 .\" links@rtsched.2 sched_rr_ge.2 .\" links@rtsched.2 sched_setpa.2 .\" links@rtsched.2 sched_setsc.2 .\" links@rtsched.2 sched_yield.2 .\" toc entries: .\" toc@\f3rtsched(2)\f1:\0\0\f4sched_get_priority_max()\f1, \f4sched_get_priority_min()\f1,\n\f4sched_getparam()\f1, \f4sched_getscheduler()\f1, \f4sched_rr_get_interval()\f1,\n\f4sched_setparam()\f1, \f4sched_setscheduler()\f1, \f4sched_yield()\f1,\n\f4PRI_HPUX_TO_POSIX()\f1, \f4PRI_POSIX_TO_HPUX()\f1@@@real-time scheduling operations .\" toc@\f4PRI_HPUX_TO_POSIX()\f1:\0\0return POSIX.4 process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4PRI_POSIX_TO_HPUX()\f1:\0\0return HP-UX process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_max()\f1:\0\0return maximum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_min()\f1:\0\0return minimum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getparam()\f1:\0\0return scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getscheduler()\f1:\0\0return scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_rr_get_interval()\f1:\0\0update execution time limit@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setparam()\f1:\0\0set scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setscheduler()\f1:\0\0set scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_yield()\f1:\0\0force process to relinquish processor@@@\f1see \f3rtsched(2)\f1 .\" $Header: exit.2,v 72.4 94/11/14 15:23:53 ssa Exp $ .TA e .TH exit 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME exit, _exit \- terminate process .SH SYNOPSIS .C "#include " .PP .C "void exit(int status);" .PP .C "#include " .PP .C "void _exit(int status);" .SH DESCRIPTION .C exit() terminates the calling process and passes .I status to the system for inspection, see .IR wait (2). Returning from .I main in a C program has the same effect as .CR exit() ; the .I status value is the function value returned by .IR main (this value is undefined if .I main does not take care to return a value or to call .C exit() explicitly). .PP .C exit() cannot return to its caller. The result of an .C exit() call during exit processing is undefined. .PP The functions .C exit() and .CR _exit() , are equivalent, except that .C exit() calls functions registered by .C atexit() and flushes standard .SM I/O buffers, while .C _exit() does not. Both .C exit() and .C _exit() terminate the calling process with the following consequences: .IP Functions registered by .C atexit() (see .IR atexit (2)) are called in reverse order of registration. .IP All file descriptors open in the calling process are closed. .IP All files created by .C tmpfile() are removed (see .IR tmpfile (3S)). .IP If the parent process of the calling process is executing a .CR wait() , .CR wait3() , or .CR waitpid() , it is notified of the calling process's termination, and the low-order eight bits; i.e., bits 0377 of .I status are made available to it (see .IR wait (2)). .IP If the parent process of the calling process is not executing a .CR wait() , .CR wait3() , or .CR waitpid() , and does not have .C SIGCLD set to .CR SIG_IGN , the calling process is transformed into a .BR "zombie process" . A .B zombie process is a process that only occupies a slot in the process table. It has no other space allocated either in user or kernel space. Time accounting information is recorded for use by .C times() (see .IR times (2)). .IP The parent process .SM ID is set to 1 for all of the calling process's existing child processes and zombie processes. This means the initialization process (proc1) inherits each of these processes. .IP Each attached shared memory segment is detached and the value of .C shm_nattach in the data structure associated with its shared memory identifier is decremented by 1 (see .IR shmop (2)). .IP For each semaphore for which the calling process has set a semadj value (see .IR semop (2)), that semadj value is added to the semval of the specified semaphore. .IP If the process has a process, text, or data lock, an .C unlock() is performed, see .IR plock (2). .IP An accounting record is written on the accounting file if the system's accounting routine is enabled (see .IR acct (2)). .IP A .C SIGCHLD signal is sent to the parent process. .IP If the calling process is a controlling process, the .C SIGHUP signal is sent to each process in the foreground process group of the controlling terminal belonging to the calling process. The controlling terminal associated with the session is disassociated from the session, allowing it to be acquired by a new controlling process. .IP If the exit of the calling process causes a process group to become orphaned, and if any member of the newly-orphaned process group is stopped, all processes in the newly-orphaned process group are sent .C SIGHUP and .C SIGCONT signals. .IP If the current process has any child processes that are being traced, they are sent a .C SIGKILL signal. .SH AUTHOR .C exit() was developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO Exit conditions .RB ( $? ) in sh(1), .br acct(2), plock(2), semop(2), shmop(2), times(2), vfork(2), wait(2), signal(5). .SH STANDARDS CONFORMANCE .CR exit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR _exit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4exit()\fP, \f4_exit()\fP \(mi terminate process@@@\f3exit(2)\f1 .\" index@process, terminate@@@\f3exit(2)\f1 .\" .\" toc@\f3exit(2)\f1:\0\0\f4exit()\fP, \f4_exit()\fP@@@terminate process .\" .\" links@exit.2 _exit.2 .\" .\" fileset_database@exit.2 PROGRAMING-MAN .\" $Header: accept.2,v 78.2 96/03/15 15:44:26 ssa Exp $ .TA a .TH accept 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME accept \- accept a connection on a socket .SH SYNOPSIS .C "#include " .SS AF_CCITT only .C "#include " .PP .C "int accept(int s, void *addr, int *addrlen);" .SS _XOPEN_SOURCE_EXTENDED only .C "int accept(int s, struct sockaddr *addr, size_t *addrlen);" .SH DESCRIPTION The .CR accept() system call is used with connection-based socket types, such as .CR SOCK_STREAM . The argument, .IR s , is a socket descriptor created with .CR socket() , bound to a local address by .CR bind() , and listening for connections after a .CR listen() . .CR accept() extracts the first connection on the queue of pending connections, creates a new socket with the same properties as .IR s , and returns a new file descriptor, .IR ns , for the socket. .PP If no pending connections are present on the queue and nonblocking mode has not been enabled with the .CR fcntl() .CR O_NONBLOCK or .CR O_NDELAY flags or the .CR ioctl() .CR FIOSNBIO request, .CR accept() blocks the caller until a connection is present. .CR O_NONBLOCK and .CR O_NDELAY are defined in .CR (see .IR fcntl (2) .IR fcntl (5), and .IR socket (7)). .CR FIOSNBIO and the equivalent request .CR FIONBIO are defined in .CR , although use of .CR FIONBIO is not recommended (see .IR ioctl (2), .IR ioctl (5), and .IR socket (7)). .PP If the socket has nonblocking mode enabled and no pending connections are present on the queue, .CR accept() returns an error as described below. The accepted socket, .IR ns , cannot be used to accept more connections. The original socket .I s remains open for incoming connection requests. To determine whether a listening socket has pending connection requests ready for an .CR accept() call, use .CR select() for reading. .PP The argument .I addr should point to a socket address structure. The .CR accept() call fills in this structure with the address of the connecting entity, as known to the underlying protocol. In the case of AF_UNIX sockets, the peer's address is filled in only if the peer had done an explicit .CR bind() before doing a .CR connect() . Therefore, for AF_UNIX sockets, in the common case, when the peer had not done an explicit .CR bind() before doing a .CR connect() , the structure is filled with a string of nulls for the address. The format of the address depends upon the protocol and the address-family of the socket .IR s . .I addrlen is a pointer to an .CR int ; it should initially contain the size of the structure pointed to by .IR addr . On return, it contains the actual length (in bytes) of the address returned. If the memory pointed to by .I addr is not large enough to contain the entire address, only the first .I addrlen bytes of the address are returned. If .I addr is NULL or .I addrlen contains 0, then the connecting entity's address will not be returned. .PP The .CR fcntl() .CR O_NONBLOCK and .CR O_NDELAY flags and .CR ioctl() .CR FIOSNBIO request are all supported. These features interact as follows: .RS 3 .TP 3 \(bu If the .CR O_NONBLOCK or .CR O_NDELAY flag has been set, .CR accept() requests behave accordingly, regardless of any .CR FIOSNBIO requests. .TP \(bu If neither the .CR O_NONBLOCK flag nor the .CR O_NDELAY flag has been set, .CR FIOSNBIO requests control the behavior of .CR accept() . .RE .PP .SS AF_CCITT only The .I addr parameter to .CR accept() returns addressing information for the connecting entity, except for the .CR x25ifname[] field of .I addr which contains the name of the local X.25 interface through which the connection request arrived. Call-acceptance can be controlled with the .CR ioctl() .CR X25_CALL_ACPT_APPROVAL request (see .IR socketx25 (7)). .SH RETURN VALUE Upon successful completion, .CR accept() returns a nonnegative integer which is a descriptor for the accepted socket. .PP If an error occurs, .CR accept() returns .CR -1 and sets .CR errno to indicate the cause. .SH ERRORS If .CR accept() fails, .CR errno is set to one of the following values: .TP 20 .SM [EAGAIN] Nonblocking I/O is enabled using .CR O_NONBLOCK and no connections are present to be accepted. .TP .SM [EBADF] The argument, .IR s , is not a valid file descriptor. .TP .SM [EFAULT] The .I addr parameter is not a valid pointer. .TP .SM [EINTR] The call was interrupted by a signal before a valid connection arrived. .TP .SM [EINVAL] The socket referenced by .I s is not currently a listen socket or has been shut down with .CR shutdown() . A .CR listen() must be done before an .CR accept() is allowed. .TP .SM [EMFILE] The maximum number of file descriptors for this process are currently open. .TP .SM [ENFILE] The system's table of open files is full and no more .CR accept() calls can be processed at this time. .TP .SM [ENOBUFS] No buffer space is available. The .CR accept() cannot complete. The queued socket connect request is aborted. .TP .SM [ENOTSOCK] The argument, .IR s , is a valid file descriptor, but it is not a socket. .TP .SM [EOPNOTSUPP] The socket referenced by .IR s does not suppport .CR accept () . .TP 20 .SM [EWOULDBLOCK] Nonblocking I/O is enabled using .CR O_NDELAY or .CR FIOSNBIO and no connections are present to be accepted. .SH AUTHOR .CR accept() was developed by the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO bind(2), connect(2), listen(2), select(2), socket(2) socketx25(7), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR accept() ": XPG4" .\" .\" index@\f4accept()\f1 \- accept connection on a socket@@@\f3accept(2)\f1 .\" index@\f1connection on a socket, accept@@@\f3accept(2)\f1 .\" index@\f1socket, accept connection on a@@@\f3accept(2)\f1 .\" .\" toc@\f3accept(2)\f1:\0\0\f4accept()\f1@@@accept connection on a socket .\" $Header: access.2,v 72.5 94/11/14 12:00:05 ssa Exp $ .TA a .TH access 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME access \- determine accessibility of a file .SH SYNOPSIS .CR "#include " .PP .CR "int access(char *path, int amode);" .SH DESCRIPTION The .CR access() system call checks the file pointed to by .IR path for accessibility according to the bit pattern contained in .IR amode . .CR access() uses the real user ID, not the effective user ID, and the real group ID, not the effective group ID. .PP The value of .I amode is either the bit-wise inclusive OR of the access permissions to be checked, or the existence test. You can use the following symbolic constants, defined in .CR , to test for permissions: .RS .TP 10 .CR R_OK Read access .PD 0 .TP .CR W_OK Write access .TP .CR X_OK Execute (search) access .TP .CR F_OK Check existence of file .PD .RE .PP The owner of a file has permission checked with respect to the "user" read, write, and execute mode bits. Members of the file's group other than the owner have permissions checked with respect to the "group" mode bits. All others have permissions checked with respect to the "other" mode bits. .PP If a file is currently open for execution, .CR access() reports that it is not writable, regardless of the setting of its mode. .SS "Access Control Lists - HFS File Systems Only" .PP Read, write, and execute/search permissions are checked against the file's access control list (ACL). Each mode is checked separately since different ACL entries can grant different permissions. The real user ID is combined with the process's real group ID and each group in its supplementary groups list, and the access control list is searched for a match. Search proceeds in order of specificity and ends when one or more matching entries are found at a specific level. More than one .IC user . group or .CI %. group entry can match a user if that user has a nonnull supplementary groups list. If any matching entry has the appropriate permission bit set, access is permitted. .PP If a shared text file is currently open for execution, .CR access() reports that it is not writable, regardless of its access control list. However, .CR access() does not report that a shared text file open for writing is not executable, since the check is not easily done. .PP It also reports that a file on a read-only file system is not writable. .SH RETURN VALUE .CR access() returns the following values: .RS .TP .CR \00 Successful completion. The requested access is permitted. .IP If the path is valid and the real user ID is superuser, .CR access() always returns 0, except when .I amode includes .CR X_OK , the path is not a directory, and none of the execute bits are set in the file's mode. .TP .CR \-1 Failure. .CR errno is set to indicate the error. .RE .SH ERRORS If .CR access() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] Search permission is denied on a component of the path prefix. .TP [EACCES] The access control list does not permit the requested access and the real user ID is not a user with appropriate privileges. .TP [EFAULT] .I path points outside the allocated address space for the process. The reliable detection of this error is implementation dependent. .TP [ELOOP] Too many symbolic links were encountered in translating the path name. .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] Read, write, or execute (search) permission is requested for a null path name. .TP [ENOENT] The named file does not exist. .TP [ENOTDIR] A component of the path prefix is not a directory. .TP [EROFS] Write access is requested for a file on a read-only file system. .TP [ETXTBSY] Write access is requested for a pure procedure (shared text) file that is being executed. .RE .SH SEE ALSO chmod(2), stat(2), setacl(2),\"STD acl(5),\"STD unistd(5). .SH STANDARDS CONFORMANCE .CR access() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4access()\f1 \- determine accessibility of a file@@@\f3access(2)\f1 .\" index@\f1accessibility of a file, determine@@@\f3access(2)\f1 .\" index@\f1determine accessibility of a file@@@\f3access(2)\f1 .\" index@\f1file, determine accessibility@@@\f3access(2)\f1 .\" .\" toc@\f3access(2)\f1:\0\0\f4access()\f1@@@determine accessibility of a file .\" $Header: acct.2,v 72.6 94/11/14 12:00:30 ssa Exp $ .TA a .TH acct 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acct() \- enable or disable process accounting .SH SYNOPSIS .C "#include " .PP .C "int acct(const char *path);" .SH DESCRIPTION The .CR acct() system call enables or disables the system's process accounting routine. If the routine is enabled, an accounting record is written on an accounting file for each process that terminates. Termination can be caused by one of two things: an .CR exit() call or a signal (see .IR exit (2) and .IR signal (5)). The effective user ID of the calling process must be superuser to use this call. .PP .I path points to a path name naming the accounting file. The accounting file format is described in .IR acct (4). .PP The accounting routine is enabled if .I path is nonzero and no errors occur during the system call. It is disabled if .I path is zero and no errors occur during the system call. .PP When the amount of free space on the file system containing the accounting file falls below a configurable threshold, the system prints a message on the console and disables process accounting. Another message is printed and the process accounting is reenabled when the space reaches a second configurable threshold. .PP If the size of the process accounting file reaches 5000 blocks, records for processes terminating after that point will be silently lost. However, in that case the .CR turnacct command would still sense that process accounting is still enabled. This loss of records can be prevented with the .CR ckpacct command. .CR ckpacct and .CR turnacct are described in .IR acctsh (1M)). .SH RETURN VALUE .CR acct() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR acct() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] The file named by .I path is not an ordinary file. .TP [EBUSY] An attempt is being made to enable accounting when it is already enabled. .TP [EFAULT] .I path points to an illegal address. The reliable detection of this error simplementation dependent. .TP [ELOOP] Too many symbolic links were encountered in translating the path name. .TP [ENAMETOOLONG] The accounting file path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] One or more components of the accounting file path name do not exist. .TP [ENOTDIR] A component of the path prefix is not a directory. .TP [EPERM] The effective user ID of the calling process is not superuser. .\" ZZZ .TP [EROFS] The named file resides on a read-only file system. .TP [ETXTBSY] .I path points to a text file which is currently open. .RE .SH SEE ALSO acct(1M), acctsh(1M), exit(2), acct(4), signal(5). .SH STANDARDS CONFORMANCE .CR acct() ": SVID2, SVID3, XPG2" .\" .\" index@\f4acct()\f1 \- enable or disable process accounting@@@\f3acct(2)\f1 .\" index@accounting: enable or disable process accounting@@@\f3acct(2)\f1 .\" index@enable or disable process accounting@@@\f3acct(2)\f1 .\" index@disable or enable process accounting@@@\f3acct(2)\f1 .\" index@process accounting, enable or disable@@@\f3acct(2)\f1 .\" .\" toc@\f3acct(2)\f1:\0\0\f4acct()\f1@@@enable or disable process accounting .\" $Header: adjtime.2,v 72.2 94/09/13 11:32:59 ssa Exp $ .TA a .TH adjtime 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME adjtime() \- correct the time to synchronize the system clock .SH SYNOPSIS .C "#include " .PP .nf .PD 0 .C "int adjtime(" .IP .C "const struct timeval *delta," .C "struct timeval *olddelta" .PP .C ");" .PD .fi .SH DESCRIPTION The function .C adjtime() adjusts the current time of the system. The time is either advanced or retarded by the amount of time specified in the struct timeval pointed to by .I delta. .PP The adjustment is made by applying small correctional adjustments to the value of current time that the system keeps. The time is always increasing monotonically, but at a rate slightly slower or faster than normal. .PP A time correction for an earlier call to .C adjtime() may not be complete when .C adjtime() is called. The second call to .C adjtime() stops the first call to .C adjtime() if .I delta is non-NULL, but does not undo the effects of the previous call. If .I delta is NULL, then no time correction will be done. .PP If .I olddelta is not a NULL pointer, then the structure it points to will contain, upon return, the number of seconds and/or microseconds still to be corrected from the earlier call. If .I olddelta is a NULL pointer, the corresponding information will not be returned. .PP The call to .C adjtime() returns immediately, though its effect will continue until the whole correction is made or until modified by another call to either .C adjtime() with a non-NULL .I delta or to change the system time (see "Interaction with Other System Calls"). .PP Only a user with appropriate privileges can call .C adjtime() successfully with a non-NULL .I delta. Any user can call .C adjtime() with a NULL delta to report the correction left from the previous call. .SS Limits struct timeval is defined in .RC < time.h > as having at least 2 members: .nf .IP .C struct timeval { .C " unsigned long tv_sec; /* seconds */" .C " long tv_usec; /* and microseconds */" .C }; .fi .PP When .C adjtime() is called, if the delta.tv_sec field is greater than 31536000 (approx. 365 days), or less than \(mi31536000, then .C adjtime() fails with an errno of EINVAL. The tv_usec field is not used in the calculations to determine the limits, and so the actual limit on adjustments are [\(mi31536000\(miLONG_MIN, 31536000+LONG_MAX]. .PP Note that the desired seconds may be negative. Since the type of the tv_sec field is (unsigned long), any negative values for tv_sec need to be cast. .PP Any .I olddelta value returned by the .C adjtime() function will be returned such that the signs of non-zero members are the same. .SS Interaction with Other System Calls A call to change the system time terminates the .C adjtime() correction currently in effect. A subsequent call to .C adjtime() will return {0, 0} for the .I olddelta parameter. This includes system calls such as .C settimeofday(), .C stime(), and .C clock_settime(). .SH RETURN VALUE Upon successful completion, .C adjtime() returns a value of 0; otherwise, it returns a value \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C adjtime() fails if one or more of the following is true: .RS .TP 15 .SM [EPERM] if the process does not have the appropriate privilege. .TP .SM [EFAULT] The address specified for .I delta (or .I olddelta ) is invalid. .TP .SM [EINVAL] If .I delta.tv_sec is greater than 31536000 (approx. 365 days) or less than \(mi31536000. The .I delta.tv_usec field is not used in calculation of these limits. If the user wants to adjust time greater than these limits, an appropriate alternative interface should be used. .SH EXAMPLES The following code snippet will take the time forward 20 minutes. .nf .IP .C " struct timeval forward;" .IP .C " forward.tv_sec = 20 * 60; /* 20 minutes */" .C " forward.tv_usec = 0;" .IP .C " if (adjtime(&forward, (struct timeval *)NULL) == -1)" .C " perror(""adjtime() failure"");" .IP .C " /*" .C " * If adjtime() succeeds, the system time will move forward" .C " * 20 minutes over a period of time." .C " */" .fi .PP The following code fragment will repeatedly call a user-defined function adjustment_still_in_progress() until the adjustment requested in a previous call to .C adjtime() (called from either the same process or another process) is completed. .nf .IP .C " struct timeval report;" .C "" .C " if (adjtime((struct timeval *)NULL, &report) == -1)" .C " perror(""adjtime() failure"");" .C "" .C " while (report.tv_sec || report.tv_usec) {" .C " adjustment_still_in_progress(); .C "" .C " if (adjtime((struct timeval *)NULL, &report) == -1)" .C " perror(""adjtime() failure"");" .C " }" .fi .SH AUTHOR .C adjtime() was developed by the University of California, Berkeley and AT&T. .SH SEE ALSO date(1), gettimeofday(2), settimeofday(2), stime(2), clock_settime(2), getitimer(2), setitimer(2), alarm(2). .\" toc@\f3adjtime(2)\f1:\0\0\f4adjtime()\f1@@@correct the time to synchronize the system clock .\" index@\f4adjtime()\f1 \- correct the time to synchronize the system clock@@@\f3adjtime(2)\f1 .\" index@\f1correct the time to synchronize the system clock@@@\f3adjtime(2)\f1 .\" index@\f1synchronize the system clock, correct the time to@@@\f3adjtime(2)\f1 .\" index@\f1system clock, correct the time to synchronize the@@@\f3adjtime(2)\f1 .\" index@\f1clock, correct the time to synchronize the system@@@\f3adjtime(2)\f1 .\" $Header: alarm.2,v 72.4 94/11/14 12:02:41 ssa Exp $ .TA a .TH alarm 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME alarm \- set a process's alarm clock .SH SYNOPSIS .C "#include " .PP .C "unsigned int alarm(unsigned int sec);" .SH DESCRIPTION .C alarm() instructs the alarm clock of the calling process to send the signal .SM SIGALRM to the calling process after the number of real-time seconds specified by .I sec have elapsed; see .IR signal (5). Specific implementations might place limitations on the maximum supported alarm time. The constant .SM MAX_ALARM defined in .RC < sys/param.h > specifies the implementation-specific maximum. Whenever .I sec is greater that this maximum, it is silently rounded down to it. On all implementations, .C MAX_ALARM is guaranteed to be at least 31 days (in seconds). .PP Alarm requests are not stacked; successive calls reset the alarm clock of the calling process. .PP If .I sec is 0, any previously made alarm request is canceled. .PP Alarms are not inherited by a child process across a .CR fork() , but are inherited across an .CR exec() . .PP On systems that support the .C getitimer() and .C setitimer() system calls, the timer mechanism used by .C alarm() is the same as that used by .I ITIMER_REAL. Thus successive calls to .CR alarm() , .CR getitimer() , and .C setitimer() set and return the state of a single timer. In addition, .C alarm() sets the timer interval to zero. .SH RETURN VALUE .C alarm() returns the amount of time previously remaining in the alarm clock of the calling process. .SH WARNINGS In some implementations, error bounds for alarm are \(mi1, +0 seconds (for the posting of the alarm, not the restart of the process). Thus a delay of 1 second can return immediately. The .C setitimer() routine can be used to create a more precise delay. .SH "SEE ALSO" sleep(1), exec(2), getitimer(2), pause(2), signal(5), sleep(3C). .SH STANDARDS CONFORMANCE .CR alarm() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4alarm()\fP \(mi set a process's alarm clock@@@\f3alarm(2)\f1 .\" index@set a process's alarm clock@@@\f3alarm(2)\f1 .\" index@process's alarm clock, set@@@\f3alarm(2)\f1 .\" index@alarm clock, set a process's@@@\f3alarm(2)\f1 .\" .\" toc@\f3alarm(2)\f1:\0\0\f4alarm()\fP@@@set a process's alarm clock .\" .\" fileset_database@alarm.2 PROGRAMING-MAN .\" $Header: nfssvc.2,v 72.3 93/01/14 14:44:13 ssa Exp $ .TA n .TH nfssvc 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nfssvc, async_daemon \- \s-1NFS\s0 daemons .SH SYNOPSIS .nf .C int nfssvc(int sock); .PP .C void async_daemon(); .SH DESCRIPTION .C nfssvc() starts an .SM NFS daemon listening on socket .IR sock . The socket must be .SM AF_INET and .SM SOCK_DGRAM (protocol .SM UDP/IP\s0). The system call returns only if the process is killed. .PP .I async_daemon implements the .SM NFS daemon that handles asynchronous .SM I/O for an .SM NFS client. The system call never returns. .SH ERRORS .C nfssvc() fails if any of the following conditions is encountered, and sets .C errno accordingly: .RS .TP 15 .SM [EBADF] .I sock is not a valid socket descriptor. .TP 15 .SM [EINVAL] .I sock refers to a socket that is not an .SM AF_INET and .SM SOCK_DGRAM socket. .RE .PP .I async_daemon fails if the following condition is encountered, and sets .C errno accordingly: .RS .TP 15 .SM [ENOMEM] There are not enough resources to create the process. .RE .SH WARNINGS This call should be used only by HP-supplied commands and is not recommended for use by non-HP-supplied programs. .PP These two system calls allow kernel processes to have user context. .SH AUTHOR .C nfssvc() was developed by Sun Microsystems, Inc. .SH SEE ALSO mountd(1M), nfsd(1M). .\" .\" index@\f4nfssvc()\fP: \s-1NFS\s+1 daemon@@@\f3nfssvc(2)\f1 .\" index@\f2async_daemon\f1: \s-1NFS\s+1 daemon@@@\f3nfssvc(2)\f1 .\" index@\s-1NFS\s+1 daemons@@@\f3nfssvc(2)\f1 .\" index@daemons, \s-1NFS\s+1@@@\f3nfssvc(2)\f1 .\" .\" toc@\f3nfssvc(2)\f1: \f4nfssvc()\fP, \f2async_daemon\f1@@@\s-1NFS\s0 daemons .\" .\" links@nfssvc.2 async_daemo.2 .\" .\" fileset_database@nfssvc.2 PROGRAMING-MAN .\" $Header: atexit.2,v 72.4 94/11/14 12:05:07 ssa Exp $ .TA a .TH atexit 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME atexit \- register a function to be called at program termination .SH SYNOPSIS .C "#include " .PP .C "int atexit(void (*func)(void));" .SH DESCRIPTION .C atexit() registers the function .I func to be called, without arguments, at normal program termination. Functions registered by .C atexit() are called in reverse order of registration. .PP An .C atexit() call during exit processing is always unsuccessful. .PP The number of registered functions should not exceed .C ATEXIT_MAX as specified in .RC < limits.h >. .SH RETURN VALUE .C atexit() returns zero if the registration is successful; non-zero if unsuccessful. .SH SEE ALSO exit(2). .SH STANDARDS CONFORMANCE .CR atexit() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4atexit()\fP \(mi register a function to be called at program termination@@@\f3atexit(2)\f1 .\" index@register a function to be called at program termination@@@\f3atexit(2)\f1 .\" index@exit, register a function to be called at@@@\f3atexit(2)\f1 .\" index@function to be called at program termination, register a@@@\f3atexit(2)\f1 .\" index@program termination, register a function to be called at@@@\f3atexit(2)\f1 .\" index@termination, register a function to be called at program@@@\f3atexit(2)\f1 .\" .\" toc@\f3atexit(2)\f1:\0\0\f4atexit()\fP@@@register a function to be called at program termination .\" .\" fileset_database@atexit.2 PROGRAMING-MAN .\" $Header: audctl.2,v 72.3 93/01/14 14:31:47 ssa Exp $ .TA a .TH audctl 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME audctl \- start or halt the auditing system and set or get audit files .SH SYNOPSIS .C "#include " .PP .C "int audctl(int cmd, char *cpath, char *npath, mode_t mode);" .SH DESCRIPTION .C audctl() sets or gets the auditing system "current" and "next" audit files, and starts or halts the auditing system. This call is restricted to superusers. .I cpath and .I npath hold the absolute path names of the "current" and "next" files. .I mode specifies the audit file's permission bits. .I cmd is one of the following specifications: .RS .TP 20 .C AUD_ON The caller issues the .C AUD_ON command with the required "current" and "next" files to turn on the auditing system. If the auditing system is currently off, it is turned on; the file specified by the .I cpath parameter is used as the "current" audit file, and the file specified by the .I npath parameter is used as the "next" audit file. If the audit files do not already exist, they are created with the .I mode specified. The auditing system then begins writing to the specified "current" file. An empty string or .SM NULL .I npath can be specified if the caller wants to designate that no "next" file be available to the auditing system. If the auditing system is already on, no action is performed; .C -1 is returned and .C errno is set to .SM EBUSY. .TP .C AUD_GET The caller issues the .C AUD_GET command to retrieve the names of the "current" and "next" audit files. If the auditing system is on, the names of the "current" and "next" audit files are returned via the .I cpath and .I npath parameters (which must point to character buffers of sufficient size to hold the file names). .I mode is ignored. If the auditing system is on and there is no available "next" file, the "current" audit file name is returned via the .I cpath parameter, .I npath is set to an empty string; .C -1 is returned, and .C errno is set to .SM ENOENT. If the auditing system is off, no action is performed; .C -1 is returned and .C errno is set to .SM EALREADY. .TP .C AUD_SET The caller issues the .C AUD_SET command to change both the "current" and "next" files. If the audit system is on, the file specified by .I cpath is used as the "current" audit file, and the file specified by .I npath is used as the "next" audit file. If the audit files do not already exist, they are created with the specified .IR mode . The auditing system begins writing to the specified "current" file. Either an empty string or .SM NULL .I npath can be specified if the caller wants to designate that no "next" file be available to the auditing system. If the auditing system is off, no action is performed; .C -1 is returned and .C errno is set to .SM EALREADY. .TP .C AUD_SETCURR The caller issues the .C AUD_SETCURR command to change only the "current" audit file. If the audit system is on, the file specified by .I cpath is used as the "current" audit file. If the specified "current" audit file does not exist, it is created with the specified .IR mode . .I npath is ignored. The auditing system begins writing to the specified "current" file. If the audit system is off, no action is performed; .C -1 is returned and .C errno is set to .SM EALREADY. .TP .C AUD_SETNEXT The caller issues the .C AUD_SETNEXT command to change only the "next" audit file. If the auditing system is on, the file specified by .I npath is used as the "next" audit file. .I cpath is ignored. If the "next" audit file specified does not exist, it is created with the specified .IR mode . Either an empty string or .SM NULL .I npath can be specified if the caller wants to designate that no "next" file be available to the auditing system. If the auditing system is off, no action is performed; .C -1 is returned, and .C errno is set to .SM EALREADY. .TP .C AUD_SWITCH The caller issues the .C AUD_SWITCH command to cause auditing system to switch audit files. If the auditing system is on, it uses the "next" file as the new "current" audit file and sets the new "next" audit file to .SM NULL. .IR cpath , .IR npath , and .I mode are ignored. The auditing system begins writing to the new "current" file. If the auditing system is off, no action is performed; .C -1 is returned, and .C errno is set to .SM EALREADY. If the auditing system is on and there is no available "next" file, no action is performed; .C -1 is returned, and .C errno is set to .SM ENOENT. .TP .C AUD_OFF The caller issues the .C AUD_OFF command to halt the auditing system. If the auditing system is on, it is turned off and the "current" and "next" audit files are closed. .IR cpath , .IR npath , and .I mode are ignored. If the audit system is already off, .C -1 is returned and .C errno is set to .SM EALREADY. .RE .SH RETURN VALUE Upon successful completion, a value of .C 0 is returned. Otherwise, .C -1 is returned and the global variable .C errno is set to indicate the error. .SH EXAMPLES In the following example, .C audctl() is used to determine whether the auditing system is on, and to retrieve the names of the audit files that are currently in use by the system. .nf .IP .ft 4 .ps +1 char c_file[PATH_MAX+1], x_file[PATH_MAX+1]; int mode=0600; .IP .ft 4 .ps +1 if (audctl(\s-1AUD_GET\s+1, c_file, x_file, mode)) switch ( errno ) { case \s-1ENOENT\s+1: strcpy(x_file,"-none-"); break; case \s-1EALREADY\s+1: printf("The auditing system is \s-1OFF\s+1\en"); return 0; case default: fprintf(stderr, "Audctl failed: errno=%d\en", errno); return 1; } .IP .ft 4 .ps +1 printf("The auditing system is ON: c_file=%s x_file=%s\en", c_file, x_file); return 0; .fi .ft P .SH ERRORS .C audctl() fails if one of the following is true: .RS .TP 20 .SM [EPERM] The caller does not have superuser privilege, or one or both of the given files are not regular files and cannot be used. .TP .SM [EALREADY] The .CR AUD_OFF , .CR AUD_SET , .CR AUD_SETCURR , .CR AUD_SETNEXT , .CR AUD_SWITCH , or .C AUD_GET .I cmd was specified while the auditing system is off. .TP .SM [EBUSY] User attempt to start the auditing system failed because auditing is already on. .TP .SM [EFAULT] Bad pointer. One or more of the required function parameters is not accessible. .TP .SM [EINVAL] The .I cpath or .I npath is greater than .C PATH_MAX in length, the .I cpath or .I npath specified is not an absolute path name. .TP .SM [ENOENT] No available "next" file when .I cmd is .C AUD_GETNEXT or .CR AUD_SWITCH . .RE .SH AUTHOR .C audctl() was developed by HP. .SH SEE ALSO audit(5), audsys(1M), audomon(1M). .\" .\" index@\f4audctl()\fP \(mi start or halt auditing system; set or get audit files@@@\f3audctl(2)\f1 .\" index@audit: start or halt auditing system@@@\f3audctl(2)\f1 .\" index@audit: set or get audit files@@@\f3audctl(2)\f1 .\" index@auditing system, start or halt@@@\f3audctl(2)\f1 .\" index@audit files, set or get@@@\f3audctl(2)\f1 .\" index@files, audit, set or get@@@\f3audctl(2)\f1 .\" index@start or halt auditing system@@@\f3audctl(2)\f1 .\" index@set or get audit files@@@\f3audctl(2)\f1 .\" index@halt or start auditing system@@@\f3audctl(2)\f1 .\" index@get or set audit files@@@\f3audctl(2)\f1 .\" toc@\f3audctl(2)\f1:\0\0\f4audctl()\fP@@@start or halt auditing system; set or get audit files .\" .\" fileset_database@audctl.2 PROGRAMING-MAN .\" $Header: audswitch.2,v 72.3 93/01/14 14:40:57 ssa Exp $ .TA a .TH audswitch 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME audswitch \- suspend or resume auditing on the current process .SH SYNOPSIS .C "#include " .PP .C "int audswitch(int aflag);" .SH DESCRIPTION .C audswitch() suspends or resumes auditing within the current process. This call is restricted to superusers. .PP One of the following .I aflags must be used: .RS 3 .TP 20 .C AUD_SUSPEND Suspend auditing on the current process. .TP .C AUD_RESUME Resume auditing on the current process. .RE .PP .C audswitch() can be used in self-auditing privileged processes to temporarily suspend auditing during intervals where auditing is to be handled by the process itself. Auditing is suspended by a call to .C audswitch() with the .C AUD_SUSPEND parameter and resumed later by a call to .C audswitch() with the .C AUD_RESUME parameter. .PP An .C audswitch() call to resume auditing serves only to reverse the action of a previous .C audswitch() call to suspend auditing. A call to .C audswitch() to resume auditing when auditing is not suspended has no effect. .PP .C audswitch() affects only the current process. For example, .C audswitch() cannot suspend auditing for processes .CR exec 'ed from the current process. (Use .C setaudproc (see .IR setaudproc (2)) to enable or disable auditing for a process and its children). .SH RETURN VALUE Upon successful completion, .C audswitch() returns .CR 0 . If an error occurs, .C -1 is returned and the global variable .C errno is set to indicate the error. .SH ERRORS .C audswitch() fails if one of the following is true: .TP 15 .SM [EPERM] The user is not a superuser. .TP .SM [EINVAL] The input parameter is neither .SM .C AUD_RESUME nor .CR AUD_SUSPEND . .SH AUTHOR .C audswitch() was developed by HP. .SH SEE ALSO audit(5), setaudproc(2), audusr(1M), audevent(1M). .\" .\" index@\f4audswitch()\fP \(mi suspend or resume auditing on current process@@@\f3audswitch(2)\f1 .\" index@suspend or resume auditing on current process@@@\f3audswitch(2)\f1 .\" index@resume or suspend auditing on current process@@@\f3audswitch(2)\f1 .\" index@auditing, suspend or resume on current process@@@\f3audswitch(2)\f1 .\" index@process, suspend or resume auditing on current@@@\f3audswitch(2)\f1 .\" index@current process, suspend or resume auditing on@@@\f3audswitch(2)\f1 .\" toc@\f3audswitch(2)\f1:\0\0\f4audswitch()\fP@@@suspend or resume auditing on current process .\" .\" fileset_database@audswitch.2 PROGRAMING-MAN .\" $Header: audwrite.2,v 72.3 93/01/14 14:39:59 ssa Exp $ .TA a .TH audwrite 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME audwrite \- write an audit record for a self-auditing process .SH SYNOPSIS .C "#include " .PP .C "int audwrite(const struct self_audit_rec *audrec_p);" .SH DESCRIPTION .C audwrite() is called by trusted self-auditing processes, which are capable of turning off the regular auditing (using .IR audswitch (2)) and doing higher-level auditing on their own. .C audwrite() is restricted to superusers. .PP .C audwrite() checks to see if the auditing system is on and the calling process and the event specified are being audited. If these conditions are met, .C audwrite() writes the audit record pointed to by .I audrec_p into the audit file. The record consists of an audit record body and a header with the following fields: .RS .TP 25 .C u_long ah_time; /\(** Date/time (tv_sec of timeval) \(**/ .PD 0 .TP .C u_short ah_pid; /\(** Process ID \(**/ .TP .C u_short ah_error; /\(** Success/failure \(**/ .TP .C u_short ah_event; /\(** Event being audited \(**/ .TP .C u_short ah_len; /\(** Length of variant part \(**/ .RE .PD .PP The header has the same format as the regular audit record, while the body contains additional information about the high-level audit event. The header fields .CR ah_error , .CR ah_event , and .C ah_len are specified by the calling process. .C audwrite() fills in .C ah_time and .C ah_pid fields with the correct values. this is done to reduce the risk of forgery. After the header is completed, the record body is attached and the entire record is written into the current audit file. .SH RETURN VALUE If the write is successful, a value of .C 0 is returned. Otherwise, a value of .C -1 is returned and .C errno is set to indicate the reason for the failure. .SH ERRORS .C audwrite() fails if one of the following is true: .RS .TP 15 .SM [EPERM] The caller is not a superuser. .TP .SM [EINVAL] The event number in the audit record is invalid. .RE .SH WARNINGS If .I audwrite causes a file space overflow, the calling process might be suspended until the file space is cleaned up. However a returned call with the return value of 0 indicates that the audit record has been successfully written. .SH AUTHOR .C audwrite() was developed by HP. .SH SEE ALSO audswitch(2), audit(4). .\" index@\f4audwrite()\fP \(mi write audit record for self-auditing process@@@\f3audwrite(2)\f1 .\" index@write audit record for self-auditing process@@@\f3audwrite(2)\f1 .\" index@audit record, write for self-auditing process@@@\f3audwrite(2)\f1 .\" index@record, audit, write for self-auditing process@@@\f3audwrite(2)\f1 .\" index@self-auditing process, write audit record for@@@\f3audwrite(2)\f1 .\" index@process, self-auditing, write audit record for@@@\f3audwrite(2)\f1 .\" toc@\f3audwrite(2)\f1:\0\0\f4audwrite()\fP@@@write audit record for self-auditing process .\" .\" fileset_database@audwrite.2 PROGRAMING-MAN .\" $Header: bind.2,v 78.2 96/03/15 15:45:30 ssa Exp $ .TA b .TH bind 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bind \- bind an address to a socket .SH SYNOPSIS .C #include .SS AF_CCITT only .C #include .SS AF_INET only .C #include .SS AF_UNIX only .C #include .PP .C "int bind(int s, const void *addr, int addrlen);" .SS _XOPEN_SOURCE_EXTENDED only .C "int bind(int s, const struct sockaddr *addr, size_t addrlen);" .SH DESCRIPTION The .CR bind() system call assigns an address to an unbound socket. When a socket is created with .CR socket() , it exists in an address space (address family) but has no address assigned. .CR bind() causes the socket whose descriptor is .I s to become bound to the address specified in the socket address structure pointed to by .IR addr . .PP .I addrlen must specify the size of the address structure. Since the size of the socket address structure varies between socket address families, the correct socket address structure should be used with each address family (for example, .CR "struct sockaddr_in" for AF_INET, and .CR "struct sockaddr_un" for AF_UNIX). Typically, the .CR sizeof() function is used to pass this value in the .CR bind() call (for example, .CR "sizeof(struct sockaddr_in)" ). .PP The rules used in address binding vary between communication domains. For example, when binding an AF_UNIX socket to a path name (such as .CR /tmp/mysocket ), an open file having that name is created in the file system. When the bound socket is closed, that file still exists unless it is removed or unlinked. When binding an AF_INET socket, .I sin_port can be a port number or it can be zero. If .I sin_port is zero, the system assigns an unused port number automatically. .SH RETURN VALUE .CR bind() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR bind() fails, .CR errno is set to one of the following values. .RS .TP 22 [EACCES] The requested address is protected, and the current user has inadequate permission to access it. (This error can be returned by AF_INET only.) .TP [EADDRINUSE] The specified address is already in use. .TP [EADDRNOTAVAIL] The specified address is invalid or not available from the local machine, or for AF_CCITT sockets which use "wild card" addressing, the specified address space overlays the address space of an existing bind. .TP [EAFNOSUPPORT] The specified address is not a valid address for the address family of this socket. .TP [EBADF] .I s is not a valid file descriptor. .TP [EDESTADDRREQ] No .I addr parameter was specified. .TP [EFAULT] .I addr is not a valid pointer. .TP [EINVAL] The socket is already bound to an address, the socket has been shut down, .I addrlen is a bad value, or an attempt was made to .CR bind() an AF_UNIX socket to an NFS-mounted (remote) name. .IP AF_CCITT: The protocol-ID length is negative or greater than 8, the X.121 address string contains an illegal character, or the X.121 address string is greater than 15 digits long. .TP [ENETDOWN] The .I x25ifname field name specifies an interface that was shut down, or never initialized, or whose Level 2 protocol indicates that the link is not working: Wires might be broken, the interface hoods on the modem are broken, the modem failed, the phone connection failed (this error can be returned by AF_CCITT only), noise interfered with the line for a long period of time. .TP [ENETUNREACH] The X.25 Level 2 protocol is down. The X.25 link is not working: Wires might be broken, or connections are loose on the interface hoods at the modem, the modem failed, or noise interfered with the line for an extremely long period of time. .TP [ENOBUFS] No buffer space is available. The .CR bind() cannot complete. .TP [ENODEV] The .I x25ifname field name specifies a nonexistent interface. (This error can be returned by AF_CCITT only.) .TP [ENOTSOCK] .I s is a valid file descriptor, but it is not a socket. .TP [EOPNOTSUPP] The socket referenced by .I s does not support address binding. .SH AUTHOR .CR bind() was developed by the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO connect(2), getsockname(2), listen(2), socket(2), af_ccitt(7F), inet(7F), socketx25(7), tcp(7P), udp(7P), unix(7P), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR bind() ": XPG4" .\" .\" index@\f4bind()\f1 \- bind an address to a socket@@@\f3bind(2)\f1 .\" index@\f1address to a socket, bind@@@\f3bind(2)\f1 .\" index@\f1socket, bind address to a@@@\f3bind(2)\f1 .\" .\" toc@\f3bind(2)\f1:\0\0\f4bind()\f1@@@bind an address to a socket .\" $Header: brk.2,v 72.4 94/11/14 13:03:14 ssa Exp $ .TA b .TH brk 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME brk, sbrk \- change data segment space allocation .SH SYNOPSIS .C "#include " .PP .C "int brk(const void *endds);" .PP .C "void *sbrk(int incr);" .SH DESCRIPTION .C brk() and .C sbrk() are used to change dynamically the amount of space allocated for the calling process's data segment; see .IR exec (2). The change is made by resetting the process's break value and allocating the appropriate amount of space. The break value is the address of the first location beyond the end of the data segment. The amount of allocated space increases as the break value increases. The newly allocated space is set to zero. .PP .C brk() sets the break value to .I endds and changes the allocated space accordingly. .PP .C sbrk() adds .I incr bytes to the break value and changes the allocated space accordingly. .I incr can be negative, in which case the amount of allocated space is decreased. .SH ERRORS .C brk() and .C sbrk() fail without making any change in the allocated space if one or more of the following are true: .TP 15 .SM [ENOMEM] Such a change would result in more space being allocated than is allowed by a system-imposed maximum (see .IR ulimit (2)). .TP .SM [ENOMEM] Such a change would cause a conflict between addresses in the data segment and any attached shared memory segment (see .IR shmop (2)). .TP .SM [ENOMEM] Such a change would be impossible as there is insufficient swap space available. .SH WARNINGS The pointer returned by .C sbrk() is not necessarily word-aligned. Loading or storing words through this pointer could cause word alignment problems. .PP Be very careful when using either .CR brk or .CR sbrk in conjunction with calls to the .IR malloc (3C) library routines. There is only one program data segment from which all three of these routines allocate and deallocate program data memory. .SH RETURN VALUE Upon successful completion, .C brk() returns a value of 0 and .C sbrk() returns the old break value. Otherwise, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH AUTHOR .C brk() and .C sbrk() were developed by AT&T and HP. .SH SEE ALSO exec(2), shmop(2), ulimit(2), end(3C), malloc(3C). .SH STANDARDS CONFORMANCE .CR brk() ": XPG2" .PP .CR sbrk() ": XPG2" .\" .\" index@\f4brk()\fP, \f4sbrk()\fP \(mi change data segment space allocation@@@\f3brk(2)\f1 .\" index@\f4sbrk()\fP \(mi increase data segment space allocation@@@\f3brk(2)\f1 .\" index@allocation, change data segment space@@@\f3brk(2)\f1 .\" index@change data segment space allocation@@@\f3brk(2)\f1 .\" index@data segment space allocation, change@@@\f3brk(2)\f1 .\" index@increase data segment space allocation@@@\f3brk(2)\f1 .\" index@space allocation, change data segment@@@\f3brk(2)\f1 .\" .\" toc@\f3brk(2)\f1:\0\0\f4brk()\fP, \f4sbrk()\fP@@@change data segment space allocation .\" toc@\f4sbrk()\fP:\0\0change data segment space allocation@@@see \f3brk(2)\f1 .\" .\" links@brk.2 sbrk.2 .\" .\" fileset_database@brk.2 PROGRAMING-MAN .\" $Header: bsdproc.2,v 72.3 93/01/14 14:32:23 ssa Exp $ .TA b .TH bsdproc 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME killpg, getpgrp, setpgrp, sigvec, signal \- 4.2 \s-1BSD\s0-compatible process control facilities .SH SYNOPSIS .C "#include " .PP .C "int killpg(int pgrp, int sig);" .PP .C "int getpgrp(int pid);" .PP .C "int setpgrp(int pid, int pgrp);" .PP .C "int sigvec(" .PD 0 .nf .IP .C "int sig," .C "struct sigvec *vec," .C "struct sigvec *ovec" .PP .C ");" .fi .PD .PP .C "void (*signal(int sig, void (*func)(int)))(int);" .SH DESCRIPTION These calls simulate (and are provided for backward compatibility with) functions of the same name in the 4.2 Berkeley Software Distribution. .PP This version of .C setpgrp() is equivalent to the system call .IR setpgid ( \|pid , \ pgrp\| ) (see .IR setpgid (2)). .PP This version of .C getpgrp() is equivalent to the system call .CI getpgrp2( \|pid\| ) (see .IR getpid (2)). .PP .C killpg() is equivalent to the system call .CI kill(- pgrp , \0sig ) (see .IR kill (2)). .PP .C sigvec() is equivalent to the system call .CI sigvector( sig , .IC vec , \ ovec ) (see .IR sigvector (2)), except for the following: .IP When .SM SIGCHLD or .SM SIGCLD is used and .I vec specifies a catching function, the routine acts as if the .C SV_BSDSIG flag were included in the .C sv_flags field of .IR vec . .IP The name .C sv_onstack can be used as a synonym for the name of the .C sv_flags field of .I vec and .IR ovec . .IP If .I vec is not a null pointer and the value of .RI ( vec \(mi> sv_flags & 1) is "true", the routine acts as if the .C SV_ONSTACK flag were set. .IP If .I ovec is not a null pointer, the flag word returned in .IR ovec \(mi> sv_flags (and therefore the value of .IR ovec \(mi> sv_onstack ) will be equal to 1 if the system was reserving space for processing of that signal because of a call to .IR sigspace (2), and 0 if not. The .C SV_BSDSIG bit in the value placed in .IR ovec \(mi> sv_flags is always clear. .IP If the reception of a caught signal occurs during certain system calls, the call will always be restarted, regardless of the return value from a catching function installed with .CR sigvec() . The affected calls are .IR wait (2), .IR semop (2), .IR msgsnd (2), .IR msgrcv (2), and .IR read (2) or .IR write (2) on a slow device (such as a terminal or pipe, but not a file). Other interrupted system calls are not restarted. .PP This version of .C signal() has the same effect as .CR sigvec ( sig , .IC vec , \ ovec )\c \&, where .IR vec \(mi> sv_handler is equal to .IR func , .IR vec \(mi> sv_mask is equal to 0, and .IR vec \(mi> sv_flags is equal to 0. .C signal() returns the value that would be stored in .IR ovec \(mi> sv_handler if the equivalent .CR sigvec() call would have succeeded. Otherwise, .C signal() returns \(mi1 and .C errno is set to indicate the reason as it would have been set by the equivalent call to .CR sigvec() . .PP These functions can be linked into a program by giving the .C -lBSD option to .IR ld (1). .SH WARNINGS While the 4.3 .SM BSD release defined extensions to some of the interfaces described here, only the 4.2 .SM BSD interfaces are emulated by this package. .PP .C bsdproc() should not be used in conjunction with the facilities described under .IR sigset (2V). .SH AUTHOR .C bsdproc() was developed by HP and the University of California, Berkeley. .SH SEE ALSO ld(1), kill(2), getpid(2), msgsnd(2), msgrcv(2), read(2), semop(2), setpgid(2), setsid(2), sigvector(2), wait(2), write(2), sigset(2V), sigstack(2), signal(5). .\" index@\f4killpg()\fP \(mi 4.2 \s-1BSD\s+1-compatible \f4kill()\fP system call@@@\f3bsdproc(2)\f1 .\" index@\f4sigvec()\fP \(mi 4.2 \s-1BSD\s+1-compatible \f4sigvec()\fP system call@@@\f3bsdproc(2)\f1 .\" index@\f4signal()\fP \(mi 4.2 \s-1BSD\s+1-compatible \f4signal()\fP system call@@@\f3bsdproc(2)\f1 .\" index@\s-1BSD-4.2\s+1-compatible \f4kill()\fP, \f4sigvec()\fP, and \f4signal()\fP system calls@@@\f3bsdproc(2)\f1 .\" index@system calls, \s-1BSD-4.2\s+1-compatible \f4kill()\fP, \f4sigvec()\fP, and \f4signal()\fP@@@\f3bsdproc(2)\f1 .\" index@calls, system, \s-1BSD-4.2\s+1-compatible \f4kill()\fP, \f4sigvec()\fP, and \f4signal()\fP@@@\f3bsdproc(2)\f1 .\" index@\f4kill()\fP system call, 4.2 \s-1BSD\s+1-compatible@@@\f3bsdproc(2)\f1 .\" index@\f4sigvec()\fP system call, 4.2 \s-1BSD\s+1-compatible@@@\f3bsdproc(2)\f1 .\" index@\f4signal()\fP system call, 4.2 \s-1BSD\s+1-compatible@@@\f3bsdproc(2)\f1 .\" .\" toc@\f3bsdproc(2)\f1:\0\0\f4killpg()\fP, \f4getpgrp()\fP, \f4setpgrp()\fP, \f4sigvec()\fP,\n\f4signal()\fP@@@4.2 \s-1BSD\s+1-compatible process control facilities .\" toc@\f4killpg()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" toc@\f4getpgrp()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" toc@\f4setpgrp()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" toc@\f4sigvec()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" toc@\f4signal()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" .\" links@bsdproc.2 killpg.2 .\" links@bsdproc.2 sigvec.2 .\" .\" fileset_database@bsdproc.2 PROGRAMING-MAN .\" $Header: chdir.2,v 72.4 94/11/14 13:06:02 ssa Exp $ .TA c .TH chdir 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chdir, fchdir \- change working directory .SH SYNOPSIS .C "#include " .PP .C "int chdir(const char *path);" .PP .C "int fchdir(int fildes);" .SH DESCRIPTION .C chdir() and .C fchdir() cause a directory pointed to by .I path or .I fildes to become the current working directory, the starting point for path searches of path names not beginning with .CR / . .I path points to the path name of a directory. .I fildes is an open file descriptor of a directory. .PP For a directory to become the current working directory, a process must have execute (search) access to the directory. .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .C chdir() fails and the current working directory remains unchanged if one or more of the following are true: .TP 25 .SM [ENOTDIR] A component of the path name is not a directory. .TP .SM [ENOENT] The named directory does not exist. .TP .SM [EACCES] Search permission is denied for any component of the path name. .TP .SM [EFAULT] .I path points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP .SM [ENOENT] .I path is null. .TP .SM [ENAMETOOLONG] The length of the specified path name exceeds .C PATH_MAX bytes, or the length of a component of the path name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the path name. .PP .C fchdir() fails and the current working directory remains unchanged if one or more of the following are true: .TP 25 .SM [EACCES] Search permission is denied for .IR fildes . .TP .SM [EBADF] .I fildes is not an open file descriptor. .TP .SM [ENOTDIR] The open file descriptor .I fildes does not refer to a directory. .SH AUTHOR .C chdir() and .C fchdir() were developed by AT&T Bell Laboratories and HP. .SH SEE ALSO cd(1), chroot(2). .SH STANDARDS CONFORMANCE .CR chdir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4chdir()\fP \(mi change working directory@@@\f3chdir(2)\f1 .\" index@\f4fchdir()\fP \(mi change working directory@@@\f3chdir(2)\f1 .\" index@directory: change working directory@@@\f3chdir(2)\f1 .\" index@change working directory@@@\f3chdir(2)\f1 .\" index@working directory, change@@@\f3chdir(2)\f1 .\" .\" toc@\f3chdir(2)\f1:\0\0\f4chdir()\fP@@@change working directory .\" toc@\f2fchdir(2)\f1:\0\0change working directory@@@see \f3chdir(2)\f1 .\" .\" links@chdir.2 fchdir.2 .\" .\" fileset_database@chdir.2 PROGRAMING-MAN .\" $Header: chmod.2,v 72.5 94/11/14 13:06:28 ssa Exp $ .TA c .TH chmod 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chmod(), fchmod() \- change file mode access permissions .SH SYNOPSIS .CR "#include " .PP .CR "int chmod(const char *path, mode_t mode);" .PP .CR "int fchmod(int fildes, mode_t mode);" .SH DESCRIPTION The .CR chmod() and .CR fchmod() system calls set the access permission portion of the file's mode according to the bit pattern contained in .IR mode . .IR path points to a path name naming a file. .IR fildes is a file descriptor. .PP The following symbolic constants representing the access permission bits are defined with the indicated values in .CR and are used to construct the .IR mode argument. The value of .IR mode is the bit-wise inclusive OR of the values for the desired permissions. .nf .IP .CR "S_ISUID 04000 " "Set user ID on execution." .CR "S_ISGID 02000 " "Set group ID on execution." .CR "S_ENFMT 02000 " "Record locking enforced." .CR "S_ISVTX 01000 " "Save text image after execution." .CR "S_IRUSR 00400 " "Read by owner." .CR "S_IWUSR 00200 " "Write by owner." .CR "S_IXUSR 00100 " "Execute (search) by owner." .CR "S_IRGRP 00040 " "Read by group." .CR "S_IWGRP 00020 " "Write by group." .CR "S_IXGRP 00010 " "Execute (search) by group." .CR "S_IROTH 00004 " "Read by others (that is, anybody else)." .CR "S_IWOTH 00002 " "Write by others." .CR "S_IXOTH 00001 " "Execute (search) by others." .fi .PP To change the mode of a file, the effective user ID of the process must match that of the owner of the file or a user with appropriate privileges. .PP If the effective user ID of the process is not that of a user with appropriate privileges, mode bit .CR S_ISVTX is cleared. .PP If the effective user ID of the process is not that of a user with appropriate privileges, and the effective group ID of the process does not match the group ID of the file and none of the group IDs in the supplementary groups list match the group ID of the file, mode bit .CR S_ISGID is cleared. .PP The mode bit .CR S_ENFMT (same as .CR S_ISGID ) is used to enforce file-locking mode (see .IR lockf (2) and .IR fcntl (2)) on files that are not group executable. This might affect future calls to .CR open() , .CR creat() , .CR read() , and .CR write() on such files (see .IR open (2), .IR creat (2), .IR read (2), and .IR write (2)). .PP If an executable file is prepared for sharing, mode bit .CR S_ISVTX prevents the system from abandoning the swap-space image of the program-text portion of the file when its last user terminates. Then, when the next user of the file executes it, the text need not be read from the file system but can simply be swapped in, thus saving time. .PP If the path given to .CR chmod() contains a symbolic link as the last element, this link is traversed and path name resolution continues. .CR chmod() changes the access mode of the symbolic link's target, rather than the access mode of the link. .SS "Access Control Lists - HFS File Systems Only" All optional entries in a file's access control list are deleted when .CR chmod() is executed. (This behavior conforms to the IEEE Standard POSIX 1003.1-1988.) To preserve optional entries in a file's access control list, it is necessary to save and restore them using .CR getacl() and .CR setacl() (see .IR getacl (2) and .IR setacl (2)). .PP To set the permission bits of access control list entries, use .CR setacl() instead of .CR chmod() . .PP For more information on access control list entries, see .IR acl (5). .SH RETURN VALUE .CR chmod() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR chmod() or .CR fchmod() fails, the file mode is unchanged. .CR errno is set to one of the following values. .RS .TP 20 [EACCES] Search permission is denied on a component of the path prefix. .TP [EBADF] .I fildes is not a valid file descriptor. .TP [EFAULT] .I path points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP [EINVAL] .I path or .I fildes descriptor does not refer to an appropriate file. It may be a special file, such as a pipe or socket. .TP [ELOOP] Too many symbolic links were encountered in translating .CR path . .TP [ENAMETOOLONG] A component of .I path exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect or .I path exceeds .CR PATH_MAX bytes. .TP [ENOENT] A component of .I path or the file named by .I path does not exist. .TP [ENOTDIR] A component of the path prefix is not a directory. .TP [EPERM] The effective user ID does not match that of the owner of the file, and the effective user ID is not that of a user with appropriate privileges. .TP [EROFS] The named file resides on a read-only file system. .SH AUTHOR .CR chmod() was developed by AT&T, the University of California, Berkeley, and HP. .PP .CR fchmod() was developed by the University of California, Berkeley. .SH SEE ALSO chmod(1), chown(2), creat(2), fcntl(2), getacl(2), read(2), lockf(2), mknod(2), open(2), setacl(2), write(2), acl(5). .SH STANDARDS CONFORMANCE .CR chmod() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR fchmod() ": AES, SVID3" .\" .\" index@\f4chmod()\f1 \- change file mode access permissions@@@\f3chmod(2)\f1 .\" index@\f4fchmod()\f1 \- change file mode access permissions@@@\f3chmod(2)\f1 .\" index@access permissions, change file mode@@@\f3chmod(2)\f1 .\" index@change file mode access permissions@@@\f3chmod(2)\f1 .\" index@context-dependent file@@@\f3chmod(2)\f1 .\" index@file mode, change access permissions@@@\f3chmod(2)\f1 .\" index@file, change file mode access permissions@@@\f3chmod(2)\f1 .\" index@file, context-dependent@@@\f3chmod(2)\f1 .\" index@file, hidden@@@\f3chmod(2)\f1 .\" index@hidden file@@@\f3chmod(2)\f1 .\" index@mode, change file access permissions@@@\f3chmod(2)\f1 .\" index@permissions, change file mode access@@@\f3chmod(2)\f1 .\" .\" links@chmod.2 fchmod.2 .\" .\" toc@\f3chmod(2)\f1:\0\0\f4chmod()\f1, \f4fchmod()\f1@@@change file mode access permissions .\" toc@\f4fchmod()\f1:\0\0change file mode access permissions@@@see \f3chmod(2)\f1 .\" $Header: chown.2,v 78.1 96/01/19 20:09:55 ssa Exp $ .TA c .TH chown 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chown(), fchown(), lchown() \- change owner and group of a file .SH SYNOPSIS .C "#include " .PP .C "int chown(const char *path, uid_t owner, gid_t group);" .PP .C "int lchown(const char *path, uid_t owner, gid_t group);" .PP .C "int fchown(int fildes, uid_t owner, gid_t group);" .SH DESCRIPTION The .CR chown() system call changes the user and group ownership of a file. .IR path points to the path name of a file. .CR chown() sets the owner ID and group ID of the file to the numeric values contained in .IR owner and .IR group respectively. A value of .CR UID_NO_CHANGE or .CR GID_NO_CHANGE can be specified in .IR owner or .IR group to leave unchanged the file's owner ID or group ID, respectively. Note that .IR owner and .IR group should be less than .CR UID_MAX (see .IR limits (5)). .PP Only processes with an effective user ID equal to the file owner or a user having appropriate privileges can change the ownership of a file. If privilege groups are supported, the owner of a file can change the ownership only as a member of a privilege group allowing CHOWN, as set up by the .CR setprivgrp command (see .IR setprivgrp (1M)). All users get the CHOWN privilege by default. .PP The group ownership of a file can be changed to any group in the current process's access list or to the real or effective group ID of the current process. If privilege groups are supported and the user has the CHOWN privilege, the file can be given to any group. .PP If .CR chown() is invoked on a regular file by anyone other than the superuser, the set-user-ID and set-group-ID bits of the file mode are cleared. Whether .CR chown() preserves or clears these bits on files of other types is implementation dependent. .PP If the path given to .CR chown() contains a symbolic link as the last element, this link is traversed and path name resolution continues. .CR chown() changes the owner and group of the symbolic link's target, rather than the owner and group of the link. .PP The .CR fchown() system call functions exactly like .CR chown() , exept that it operates on a file descriptor instead of a path name. .IR fildes is a file descriptor. .PP The .CR lchown() system call sets the owner ID and group ID of the named file just as .CR chown() does, except in the case where the named file is a symbolic link. In this case, .CR lchown() changes the owner and group of the symbolic link file itself. .SS "Access Control Lists - HFS File Systems Only A user can allow or deny specific individuals and groups access to a file by using the file's access control list (see .IR acl (5)). When using .CR chown () in conjunction with ACLs, if the new owner and/or group does not have an optional ACL entry corresponding to .IC user .% and/or .CI %. group in the file's access control list, the file's access permission bits remain unchanged. However, if the new owner and/or group is already designated by an optional ACL entry of .IC user .% and/or .CI %. group\f1, .CR chown() sets the file's permission bits (and the three basic ACL entries) to the permissions contained in that entry. .SH RETURN VALUE .CR chown() and .CR fchown() return the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. The owner and group of the file remain unchanged. .CR errno is set to indicate the error. .PD .SH ERRORS If .CR chown() or .CR fchown() fails, .CR errno is set to one of the following values: .TP 15 [EACCES] Search permission is denied on a component of the path prefix. .TP [EBADF] .IR fildes is not a valid file descriptor. .TP [EFAULT] .IR path points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP [EINVAL] Either .IR owner or .IR group is greater than or equal to .CR UID_MAX , or is an illegal negative value. .TP [ELOOP] Too many symbolic links were encountered in translating .IR path . .TP [ENAMETOOLONG] A component of .IR path exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect, or .IR path exceeds .CR PATH_MAX bytes. .TP [ENOENT] The file named by .IR path does not exist. .TP [ENOTDIR] A component of the path prefix is not a directory. .TP [EPERM] The effective user ID is not a user having appropriate privileges and one or more of the following conditions exist: .RS .TP 3 \(bu The effective user ID does not match the owner of the file. .TP \(bu When changing the owner of the file, the owner of the file is not a member of a privilege group allowing the CHOWN privilege. .TP \(bu When changing the group of the file, the owner of the file is not a member of a privilege group allowing the CHOWN privilege and the group number is not in the current process's access list. .RE .TP [EROFS] The named file resides on a read-only file system. .SH AUTHOR .CR chown() was developed by AT&T. .PP .CR fchown() was developed by the University of California, Berkeley. .SH SEE ALSO chown(1), setprivgrp(1M), chmod(2), setacl(2), acl(5), limits(5). .SH STANDARDS CONFORMANCE .CR chown() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR fchown() ": AES, SVID3" .\" .\" index@\f4chown()\f1 \- change owner and group of a file@@@\f3chown(2)\f1 .\" index@\f4fchown()\f1 \- change owner and group of a file@@@\f3chown(2)\f1 .\" index@\f1file: change owner and group@@@\f3chown(2)\f1 .\" index@\f1change owner and group of a file@@@\f3chown(2)\f1 .\" index@\f1owner and group of a file, change@@@\f3chown(2)\f1 .\" index@\f1group and owner of a file, change@@@\f3chown(2)\f1 .\" .\" toc@\f3chown(2)\f1:\0\0\f4chown()\f1, \f4fchown()\f1@@@change owner and group of a file .\" toc@\f4fchown()\f1:\0\0change owner and group of a file@@@see \f3chown(2)\f1 .\" .\" links@chown.2 fchown.2 .\" links@chown.2 lchown.2 .\" $Header: chroot.2,v 72.5 94/11/14 13:07:34 ssa Exp $ .TA c .TH chroot 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chroot \- change root directory .SH SYNOPSIS .C "#include " .PP .C "int chroot(const char *path);" .SH DESCRIPTION .C chroot() causes the named directory to become the root directory, the starting point for path searches for path names beginning with .CR / . .I path points to a path name naming a directory. The user's working directory is unaffected by the .C chroot() system call. .PP The effective user .SM ID of the process must be a user having appropriate privileges to change the root directory. .PP The .C .. entry in the root directory is interpreted to mean the root directory itself. Thus, .C .. cannot be used to access files outside the subtree rooted at the root directory. .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .C chroot() fails and the root directory remains unchanged if one or more of the following is true: .RS .TP 25 .SM [ENOTDIR] Any component of the path name is not a directory. .TP .SM [ENOENT] The named directory does not exist or a component of the .I path does not exist. .TP .SM [EPERM] The effective user .SM ID is not a user who has appropriate privileges. .TP .SM [EFAULT] .I path points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP .SM [ENAMETOOLONG] The length of the specified path name exceeds .C PATH_MAX bytes, or the length of a component of the path name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the path name. .RE .SH SEE ALSO chroot(1M), chdir(2). .SH STANDARDS CONFORMANCE .CR chroot() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4chroot()\fP \(mi change root directory@@@\f3chroot(2)\f1 .\" index@change root directory@@@\f3chroot(2)\f1 .\" index@directory: change root directory@@@\f3chroot(2)\f1 .\" index@root directory, change@@@\f3chroot(2)\f1 .\" .\" toc@\f3chroot(2)\f1:\0\0\f4chroot()\fP@@@change root directory .\" .\" fileset_database@chroot.2 PROGRAMING-MAN .\" $Header: clocks.2,v 72.3 94/11/14 13:08:56 ssa Exp $ .TA c .TH clocks 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clock_settime(), clock_gettime(), clock_getres() \- clock operations .SH SYNOPSIS .C "#include " .PP .nf .C "int clock_settime(" .PD 0 .IP .C "clockid_t clock_id," .C "const struct timespec *tp" .PP .C ");" .PD .C "int clock_gettime(" .PD 0 .IP .C "clockid_t clock_id," .C "struct timespec *tp" .PP .C ");" .PD .C "int clock_getres(" .PD 0 .IP .C "clockid_t clock_id," .C "struct timespec *res" .PP .C ");" .PD .SH DESCRIPTION .SS clock_settime() The .CR clock_settime() function sets the specified clock, .CR clock_id , to the value specified by .CR tp . Time values that are between two consecutive non-negative integer multiples of the resolution of the specified clock are truncated down to the smaller multiple of the resolution. .PP .SS clock_gettime() The .CR clock_gettime() function returns the current value .CR tp for the specified clock, .CR clock_id . .PP .SS clock_getres() The resolution of any clock can be obtained by calling .CR clock_getres() . Clock resolutions are implementation defined and are not settable by a process. If the argument .CR res is not .SM NULL, the resolution of the specified clock is stored into the location pointed to by .CR res . If .CR res is .SM NULL, the clock resolution is not returned. .PP A clock may be system wide, that is, visible to all processes; or per-process, measuring time that is meaningful only within a process. .PP The following clocks are supported: .RS .TP 12 .CR CLOCK_REALTIME This clock represents the realtime clock for the system. For this clock, the values returned by .CR clock_gettime() and specified by .CR clock_settime() represent the amount of time (in seconds and nanoseconds) since the Epoch. It is a system wide clock. Appropriate privileges are required to set this clock. .TP .CR CLOCK_VIRTUAL This clock represents the amount of time (in seconds and nanoseconds) that the calling process has spent executing code in the user's context. It is a per-process clock. It cannot be set by the user. .TP .CR CLOCK_PROFILE This clock represents the amount of time (in seconds and nanoseconds) that the calling process has spent executing code in both the user's context and in the operating system on behalf of the calling process. It is a per-process clock. It cannot be set by the user. .TP .C "RTTIMER0 RTTIMER1" These clocks are high resolution hardware clocks present on .SM HP-RT realtime systems. It is included here so that applications accessing this hardware can be compiled on .SM HP-UX systems and then ported to an .SM HP-RT target. .SM HP-UX does not support .CR RTTIMER0 or .CR RTTIMER1 . .RE .SH RETURN VALUE A return of zero indicates that the call succeeded. A return value of \(mi1 indicates that an error occurred, and .CR errno is set to indicate the error. .ift .bp .SH ERRORS If any of the following conditions occur, the .CR clock_settime() , .CR clock_gettime() , and .CR clock_getres() functions return \(mi1 and set .CR errno (see .IR errno (2)) to the corresponding value: .RS .TP 12 .SM [ENOSYS] The functions .CR clock_settime() , .CR clock_gettime() , and .CR clock_getres() are not supported by this implementation. .TP .SM [EINVAL] The .CR clock_id argument does not specify a known clock. .TP .SM [EINVAL] The .CR tp argument to .CR clock_settime() is outside the range for the given .CR clock_id . .TP .SM [EINVAL] The .CR tp argument specified a nanosecond value less than zero or greater than or equal to 1000 million. .TP .SM [EPERM] The requesting process does not have the necessary privileges to set the specified clock. .TP .SM [EFAULT] The .CR tp or .CR res argument points to an invalid address. .RE .SH EXAMPLES Advance the system wide realtime clock approximately one hour: .PD 0 .nf .RS .C "#include " .C "#include " .C " " .C struct timespec cur_time, new_time; .C " " .C if (clock_gettime(CLOCK_REALTIME, &cur_time)) { .RS .C perror("clock_gettime(CLOCK_REALTIME) failed"); .C exit(1); .RE .C } .C new_time.tv_sec = cur_time.tv_sec + 3600; .C new_time.tv_nsec = cur_time.tv_nsec; .C if (clock_settime(CLOCK_REALTIME, &new_time)) { .RS .C perror("clock_settime(CLOCK_REALTIME) failed"); .C exit(2); .RE .C } .RE .PD .fi .PP Get the resolution of the user profiling clock: .PD 0 .nf .RS .C "#include " .C "#include " .C " " .C struct timespec resolution; .C " " .C if (clock_getres(CLOCK_PROFILE, &resolution)) { .RS .C perror("clock_getres(CLOCK_PROFILE) failed"); .C exit(1); .RE .C } .C (void)printf("Resolution of user profiling clock is:\en"); .C (void)printf("%d seconds and %d nanoseconds.\en", .RS .RS .RS .C resolution.tv_sec, resolution.tv_nsec); .RE .RE .RE .RE .PD .fi .SH AUTHOR .CR clock_settime() , .CR clock_gettime() , and .CR clock_getres() were derived from the proposed IEEE POSIX P1003.4 Standard, Draft 14. .SH SEE ALSO timers(2). .SH STANDARDS CONFORMANCE .CR clock_getres() ": POSIX.4" .PP .CR clock_gettime() ": POSIX.4" .PP .CR clock_settime() ": POSIX.4" .\" .\" index@\f3clocks(2)\f1, \- clock operations@@@\f3clocks(2)\f1 .\" index@\f4clock_settime()\f1 \- set clock time value@@@\f3clocks(2)\f1 .\" index@\f4clock_gettime()\f1 \- get clock time value@@@\f3clocks(2)\f1 .\" index@\f4clock_getres()\f1 \- get clock resolution@@@\f3clocks(2)\f1 .\" index@clock time value, set@@@\f3clocks(2)\f1 .\" index@clock time value, get@@@\f3clocks(2)\f1 .\" index@clock resolution, get@@@\f3clocks(2)\f1 .\" index@clock operations@@@\f3clocks(2)\f1 .\" index@operations, clock@@@\f3clocks(2)\f1 .\" toc@\f3clocks(2)\f1:\0\0\f4clock_settime()\f1, \f4clock_gettime()\f1, \f4clock_getres()\f1@@@clock operations .\" toc@\f4clock_settime()\f1:\0\0clock operation@@@see \f3clocks(2)\f1 .\" toc@\f4clock_gettime()\f1:\0\0clock operation@@@see \f3clocks(2)\f1 .\" toc@\f4clock_getres()\f1:\0\0clock operation@@@see \f3clocks(2)\f1 .\" links@clocks.2 clock_settime.2 .\" links@clocks.2 clock_gettime.2 .\" links@clocks.2 clock_getres.2 .\" $Header: clocks.2,v 72.3 94/11/14 13:08:56 ssa Exp $ .TA c .TH clocks 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clock_settime(), clock_gettime(), clock_getres() \- clock operations .SH SYNOPSIS .C "#include " .PP .nf .C "int clock_settime(" .PD 0 .IP .C "clockid_t clock_id," .C "const struct timespec *tp" .PP .C ");" .PD .C "int clock_gettime(" .PD 0 .IP .C "clockid_t clock_id," .C "struct timespec *tp" .PP .C ");" .PD .C "int clock_getres(" .PD 0 .IP .C "clockid_t clock_id," .C "struct timespec *res" .PP .C ");" .PD .SH DESCRIPTION .SS clock_settime() The .CR clock_settime() function sets the specified clock, .CR clock_id , to the value specified by .CR tp . Time values that are between two consecutive non-negative integer multiples of the resolution of the specified clock are truncated down to the smaller multiple of the resolution. .PP .SS clock_gettime() The .CR clock_gettime() function returns the current value .CR tp for the specified clock, .CR clock_id . .PP .SS clock_getres() The resolution of any clock can be obtained by calling .CR clock_getres() . Clock resolutions are implementation defined and are not settable by a process. If the argument .CR res is not .SM NULL, the resolution of the specified clock is stored into the location pointed to by .CR res . If .CR res is .SM NULL, the clock resolution is not returned. .PP A clock may be system wide, that is, visible to all processes; or per-process, measuring time that is meaningful only within a process. .PP The following clocks are supported: .RS .TP 12 .CR CLOCK_REALTIME This clock represents the realtime clock for the system. For this clock, the values returned by .CR clock_gettime() and specified by .CR clock_settime() represent the amount of time (in seconds and nanoseconds) since the Epoch. It is a system wide clock. Appropriate privileges are required to set this clock. .TP .CR CLOCK_VIRTUAL This clock represents the amount of time (in seconds and nanoseconds) that the calling process has spent executing code in the user's context. It is a per-process clock. It cannot be set by the user. .TP .CR CLOCK_PROFILE This clock represents the amount of time (in seconds and nanoseconds) that the calling process has spent executing code in both the user's context and in the operating system on behalf of the calling process. It is a per-process clock. It cannot be set by the user. .TP .C "RTTIMER0 RTTIMER1" These clocks are high resolution hardware clocks present on .SM HP-RT realtime systems. It is included here so that applications accessing this hardware can be compiled on .SM HP-UX systems and then ported to an .SM HP-RT target. .SM HP-UX does not support .CR RTTIMER0 or .CR RTTIMER1 . .RE .SH RETURN VALUE A return of zero indicates that the call succeeded. A return value of \(mi1 indicates that an error occurred, and .CR errno is set to indicate the error. .ift .bp .SH ERRORS If any of the following conditions occur, the .CR clock_settime() , .CR clock_gettime() , and .CR clock_getres() functions return \(mi1 and set .CR errno (see .IR errno (2)) to the corresponding value: .RS .TP 12 .SM [ENOSYS] The functions .CR clock_settime() , .CR clock_gettime() , and .CR clock_getres() are not supported by this implementation. .TP .SM [EINVAL] The .CR clock_id argument does not specify a known clock. .TP .SM [EINVAL] The .CR tp argument to .CR clock_settime() is outside the range for the given .CR clock_id . .TP .SM [EINVAL] The .CR tp argument specified a nanosecond value less than zero or greater than or equal to 1000 million. .TP .SM [EPERM] The requesting process does not have the necessary privileges to set the specified clock. .TP .SM [EFAULT] The .CR tp or .CR res argument points to an invalid address. .RE .SH EXAMPLES Advance the system wide realtime clock approximately one hour: .PD 0 .nf .RS .C "#include " .C "#include " .C " " .C struct timespec cur_time, new_time; .C " " .C if (clock_gettime(CLOCK_REALTIME, &cur_time)) { .RS .C perror("clock_gettime(CLOCK_REALTIME) failed"); .C exit(1); .RE .C } .C new_time.tv_sec = cur_time.tv_sec + 3600; .C new_time.tv_nsec = cur_time.tv_nsec; .C if (clock_settime(CLOCK_REALTIME, &new_time)) { .RS .C perror("clock_settime(CLOCK_REALTIME) failed"); .C exit(2); .RE .C } .RE .PD .fi .PP Get the resolution of the user profiling clock: .PD 0 .nf .RS .C "#include " .C "#include " .C " " .C struct timespec resolution; .C " " .C if (clock_getres(CLOCK_PROFILE, &resolution)) { .RS .C perror("clock_getres(CLOCK_PROFILE) failed"); .C exit(1); .RE .C } .C (void)printf("Resolution of user profiling clock is:\en"); .C (void)printf("%d seconds and %d nanoseconds.\en", .RS .RS .RS .C resolution.tv_sec, resolution.tv_nsec); .RE .RE .RE .RE .PD .fi .SH AUTHOR .CR clock_settime() , .CR clock_gettime() , and .CR clock_getres() were derived from the proposed IEEE POSIX P1003.4 Standard, Draft 14. .SH SEE ALSO timers(2). .SH STANDARDS CONFORMANCE .CR clock_getres() ": POSIX.4" .PP .CR clock_gettime() ": POSIX.4" .PP .CR clock_settime() ": POSIX.4" .\" .\" index@\f3clocks(2)\f1, \- clock operations@@@\f3clocks(2)\f1 .\" index@\f4clock_settime()\f1 \- set clock time value@@@\f3clocks(2)\f1 .\" index@\f4clock_gettime()\f1 \- get clock time value@@@\f3clocks(2)\f1 .\" index@\f4clock_getres()\f1 \- get clock resolution@@@\f3clocks(2)\f1 .\" index@clock time value, set@@@\f3clocks(2)\f1 .\" index@clock time value, get@@@\f3clocks(2)\f1 .\" index@clock resolution, get@@@\f3clocks(2)\f1 .\" index@clock operations@@@\f3clocks(2)\f1 .\" index@operations, clock@@@\f3clocks(2)\f1 .\" toc@\f3clocks(2)\f1:\0\0\f4clock_settime()\f1, \f4clock_gettime()\f1, \f4clock_getres()\f1@@@clock operations .\" toc@\f4clock_settime()\f1:\0\0clock operation@@@see \f3clocks(2)\f1 .\" toc@\f4clock_gettime()\f1:\0\0clock operation@@@see \f3clocks(2)\f1 .\" toc@\f4clock_getres()\f1:\0\0clock operation@@@see \f3clocks(2)\f1 .\" links@clocks.2 clock_settime.2 .\" links@clocks.2 clock_gettime.2 .\" links@clocks.2 clock_getres.2 .\" $Header: clocks.2,v 72.3 94/11/14 13:08:56 ssa Exp $ .TA c .TH clocks 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clock_settime(), clock_gettime(), clock_getres() \- clock operations .SH SYNOPSIS .C "#include " .PP .nf .C "int clock_settime(" .PD 0 .IP .C "clockid_t clock_id," .C "const struct timespec *tp" .PP .C ");" .PD .C "int clock_gettime(" .PD 0 .IP .C "clockid_t clock_id," .C "struct timespec *tp" .PP .C ");" .PD .C "int clock_getres(" .PD 0 .IP .C "clockid_t clock_id," .C "struct timespec *res" .PP .C ");" .PD .SH DESCRIPTION .SS clock_settime() The .CR clock_settime() function sets the specified clock, .CR clock_id , to the value specified by .CR tp . Time values that are between two consecutive non-negative integer multiples of the resolution of the specified clock are truncated down to the smaller multiple of the resolution. .PP .SS clock_gettime() The .CR clock_gettime() function returns the current value .CR tp for the specified clock, .CR clock_id . .PP .SS clock_getres() The resolution of any clock can be obtained by calling .CR clock_getres() . Clock resolutions are implementation defined and are not settable by a process. If the argument .CR res is not .SM NULL, the resolution of the specified clock is stored into the location pointed to by .CR res . If .CR res is .SM NULL, the clock resolution is not returned. .PP A clock may be system wide, that is, visible to all processes; or per-process, measuring time that is meaningful only within a process. .PP The following clocks are supported: .RS .TP 12 .CR CLOCK_REALTIME This clock represents the realtime clock for the system. For this clock, the values returned by .CR clock_gettime() and specified by .CR clock_settime() represent the amount of time (in seconds and nanoseconds) since the Epoch. It is a system wide clock. Appropriate privileges are required to set this clock. .TP .CR CLOCK_VIRTUAL This clock represents the amount of time (in seconds and nanoseconds) that the calling process has spent executing code in the user's context. It is a per-process clock. It cannot be set by the user. .TP .CR CLOCK_PROFILE This clock represents the amount of time (in seconds and nanoseconds) that the calling process has spent executing code in both the user's context and in the operating system on behalf of the calling process. It is a per-process clock. It cannot be set by the user. .TP .C "RTTIMER0 RTTIMER1" These clocks are high resolution hardware clocks present on .SM HP-RT realtime systems. It is included here so that applications accessing this hardware can be compiled on .SM HP-UX systems and then ported to an .SM HP-RT target. .SM HP-UX does not support .CR RTTIMER0 or .CR RTTIMER1 . .RE .SH RETURN VALUE A return of zero indicates that the call succeeded. A return value of \(mi1 indicates that an error occurred, and .CR errno is set to indicate the error. .ift .bp .SH ERRORS If any of the following conditions occur, the .CR clock_settime() , .CR clock_gettime() , and .CR clock_getres() functions return \(mi1 and set .CR errno (see .IR errno (2)) to the corresponding value: .RS .TP 12 .SM [ENOSYS] The functions .CR clock_settime() , .CR clock_gettime() , and .CR clock_getres() are not supported by this implementation. .TP .SM [EINVAL] The .CR clock_id argument does not specify a known clock. .TP .SM [EINVAL] The .CR tp argument to .CR clock_settime() is outside the range for the given .CR clock_id . .TP .SM [EINVAL] The .CR tp argument specified a nanosecond value less than zero or greater than or equal to 1000 million. .TP .SM [EPERM] The requesting process does not have the necessary privileges to set the specified clock. .TP .SM [EFAULT] The .CR tp or .CR res argument points to an invalid address. .RE .SH EXAMPLES Advance the system wide realtime clock approximately one hour: .PD 0 .nf .RS .C "#include " .C "#include " .C " " .C struct timespec cur_time, new_time; .C " " .C if (clock_gettime(CLOCK_REALTIME, &cur_time)) { .RS .C perror("clock_gettime(CLOCK_REALTIME) failed"); .C exit(1); .RE .C } .C new_time.tv_sec = cur_time.tv_sec + 3600; .C new_time.tv_nsec = cur_time.tv_nsec; .C if (clock_settime(CLOCK_REALTIME, &new_time)) { .RS .C perror("clock_settime(CLOCK_REALTIME) failed"); .C exit(2); .RE .C } .RE .PD .fi .PP Get the resolution of the user profiling clock: .PD 0 .nf .RS .C "#include " .C "#include " .C " " .C struct timespec resolution; .C " " .C if (clock_getres(CLOCK_PROFILE, &resolution)) { .RS .C perror("clock_getres(CLOCK_PROFILE) failed"); .C exit(1); .RE .C } .C (void)printf("Resolution of user profiling clock is:\en"); .C (void)printf("%d seconds and %d nanoseconds.\en", .RS .RS .RS .C resolution.tv_sec, resolution.tv_nsec); .RE .RE .RE .RE .PD .fi .SH AUTHOR .CR clock_settime() , .CR clock_gettime() , and .CR clock_getres() were derived from the proposed IEEE POSIX P1003.4 Standard, Draft 14. .SH SEE ALSO timers(2). .SH STANDARDS CONFORMANCE .CR clock_getres() ": POSIX.4" .PP .CR clock_gettime() ": POSIX.4" .PP .CR clock_settime() ": POSIX.4" .\" .\" index@\f3clocks(2)\f1, \- clock operations@@@\f3clocks(2)\f1 .\" index@\f4clock_settime()\f1 \- set clock time value@@@\f3clocks(2)\f1 .\" index@\f4clock_gettime()\f1 \- get clock time value@@@\f3clocks(2)\f1 .\" index@\f4clock_getres()\f1 \- get clock resolution@@@\f3clocks(2)\f1 .\" index@clock time value, set@@@\f3clocks(2)\f1 .\" index@clock time value, get@@@\f3clocks(2)\f1 .\" index@clock resolution, get@@@\f3clocks(2)\f1 .\" index@clock operations@@@\f3clocks(2)\f1 .\" index@operations, clock@@@\f3clocks(2)\f1 .\" toc@\f3clocks(2)\f1:\0\0\f4clock_settime()\f1, \f4clock_gettime()\f1, \f4clock_getres()\f1@@@clock operations .\" toc@\f4clock_settime()\f1:\0\0clock operation@@@see \f3clocks(2)\f1 .\" toc@\f4clock_gettime()\f1:\0\0clock operation@@@see \f3clocks(2)\f1 .\" toc@\f4clock_getres()\f1:\0\0clock operation@@@see \f3clocks(2)\f1 .\" links@clocks.2 clock_settime.2 .\" links@clocks.2 clock_gettime.2 .\" links@clocks.2 clock_getres.2 .\" $Header: clocks.2,v 72.3 94/11/14 13:08:56 ssa Exp $ .TA c .TH clocks 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clock_settime(), clock_gettime(), clock_getres() \- clock operations .SH SYNOPSIS .C "#include " .PP .nf .C "int clock_settime(" .PD 0 .IP .C "clockid_t clock_id," .C "const struct timespec *tp" .PP .C ");" .PD .C "int clock_gettime(" .PD 0 .IP .C "clockid_t clock_id," .C "struct timespec *tp" .PP .C ");" .PD .C "int clock_getres(" .PD 0 .IP .C "clockid_t clock_id," .C "struct timespec *res" .PP .C ");" .PD .SH DESCRIPTION .SS clock_settime() The .CR clock_settime() function sets the specified clock, .CR clock_id , to the value specified by .CR tp . Time values that are between two consecutive non-negative integer multiples of the resolution of the specified clock are truncated down to the smaller multiple of the resolution. .PP .SS clock_gettime() The .CR clock_gettime() function returns the current value .CR tp for the specified clock, .CR clock_id . .PP .SS clock_getres() The resolution of any clock can be obtained by calling .CR clock_getres() . Clock resolutions are implementation defined and are not settable by a process. If the argument .CR res is not .SM NULL, the resolution of the specified clock is stored into the location pointed to by .CR res . If .CR res is .SM NULL, the clock resolution is not returned. .PP A clock may be system wide, that is, visible to all processes; or per-process, measuring time that is meaningful only within a process. .PP The following clocks are supported: .RS .TP 12 .CR CLOCK_REALTIME This clock represents the realtime clock for the system. For this clock, the values returned by .CR clock_gettime() and specified by .CR clock_settime() represent the amount of time (in seconds and nanoseconds) since the Epoch. It is a system wide clock. Appropriate privileges are required to set this clock. .TP .CR CLOCK_VIRTUAL This clock represents the amount of time (in seconds and nanoseconds) that the calling process has spent executing code in the user's context. It is a per-process clock. It cannot be set by the user. .TP .CR CLOCK_PROFILE This clock represents the amount of time (in seconds and nanoseconds) that the calling process has spent executing code in both the user's context and in the operating system on behalf of the calling process. It is a per-process clock. It cannot be set by the user. .TP .C "RTTIMER0 RTTIMER1" These clocks are high resolution hardware clocks present on .SM HP-RT realtime systems. It is included here so that applications accessing this hardware can be compiled on .SM HP-UX systems and then ported to an .SM HP-RT target. .SM HP-UX does not support .CR RTTIMER0 or .CR RTTIMER1 . .RE .SH RETURN VALUE A return of zero indicates that the call succeeded. A return value of \(mi1 indicates that an error occurred, and .CR errno is set to indicate the error. .ift .bp .SH ERRORS If any of the following conditions occur, the .CR clock_settime() , .CR clock_gettime() , and .CR clock_getres() functions return \(mi1 and set .CR errno (see .IR errno (2)) to the corresponding value: .RS .TP 12 .SM [ENOSYS] The functions .CR clock_settime() , .CR clock_gettime() , and .CR clock_getres() are not supported by this implementation. .TP .SM [EINVAL] The .CR clock_id argument does not specify a known clock. .TP .SM [EINVAL] The .CR tp argument to .CR clock_settime() is outside the range for the given .CR clock_id . .TP .SM [EINVAL] The .CR tp argument specified a nanosecond value less than zero or greater than or equal to 1000 million. .TP .SM [EPERM] The requesting process does not have the necessary privileges to set the specified clock. .TP .SM [EFAULT] The .CR tp or .CR res argument points to an invalid address. .RE .SH EXAMPLES Advance the system wide realtime clock approximately one hour: .PD 0 .nf .RS .C "#include " .C "#include " .C " " .C struct timespec cur_time, new_time; .C " " .C if (clock_gettime(CLOCK_REALTIME, &cur_time)) { .RS .C perror("clock_gettime(CLOCK_REALTIME) failed"); .C exit(1); .RE .C } .C new_time.tv_sec = cur_time.tv_sec + 3600; .C new_time.tv_nsec = cur_time.tv_nsec; .C if (clock_settime(CLOCK_REALTIME, &new_time)) { .RS .C perror("clock_settime(CLOCK_REALTIME) failed"); .C exit(2); .RE .C } .RE .PD .fi .PP Get the resolution of the user profiling clock: .PD 0 .nf .RS .C "#include " .C "#include " .C " " .C struct timespec resolution; .C " " .C if (clock_getres(CLOCK_PROFILE, &resolution)) { .RS .C perror("clock_getres(CLOCK_PROFILE) failed"); .C exit(1); .RE .C } .C (void)printf("Resolution of user profiling clock is:\en"); .C (void)printf("%d seconds and %d nanoseconds.\en", .RS .RS .RS .C resolution.tv_sec, resolution.tv_nsec); .RE .RE .RE .RE .PD .fi .SH AUTHOR .CR clock_settime() , .CR clock_gettime() , and .CR clock_getres() were derived from the proposed IEEE POSIX P1003.4 Standard, Draft 14. .SH SEE ALSO timers(2). .SH STANDARDS CONFORMANCE .CR clock_getres() ": POSIX.4" .PP .CR clock_gettime() ": POSIX.4" .PP .CR clock_settime() ": POSIX.4" .\" .\" index@\f3clocks(2)\f1, \- clock operations@@@\f3clocks(2)\f1 .\" index@\f4clock_settime()\f1 \- set clock time value@@@\f3clocks(2)\f1 .\" index@\f4clock_gettime()\f1 \- get clock time value@@@\f3clocks(2)\f1 .\" index@\f4clock_getres()\f1 \- get clock resolution@@@\f3clocks(2)\f1 .\" index@clock time value, set@@@\f3clocks(2)\f1 .\" index@clock time value, get@@@\f3clocks(2)\f1 .\" index@clock resolution, get@@@\f3clocks(2)\f1 .\" index@clock operations@@@\f3clocks(2)\f1 .\" index@operations, clock@@@\f3clocks(2)\f1 .\" toc@\f3clocks(2)\f1:\0\0\f4clock_settime()\f1, \f4clock_gettime()\f1, \f4clock_getres()\f1@@@clock operations .\" toc@\f4clock_settime()\f1:\0\0clock operation@@@see \f3clocks(2)\f1 .\" toc@\f4clock_gettime()\f1:\0\0clock operation@@@see \f3clocks(2)\f1 .\" toc@\f4clock_getres()\f1:\0\0clock operation@@@see \f3clocks(2)\f1 .\" links@clocks.2 clock_settime.2 .\" links@clocks.2 clock_gettime.2 .\" links@clocks.2 clock_getres.2 .\" $Header: close.2,v 72.4 94/11/14 13:09:09 ssa Exp $ .TA c .TH close 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME close \- close a file descriptor .SH SYNOPSIS .C "#include " .PP .C "int close(int fildes);" .SH DESCRIPTION .C close() closes the file descriptor indicated by .IR fildes . .I fildes is a file descriptor obtained from a .CR creat() , .CR open() , .CR dup() , .CR fcntl() , or .C pipe() system call. All associated file segments which have been locked by this process with the .C lockf() function are released (i.e., unlocked). .SH RETURN VALUE Upon successful completion, .C close() returns a value of 0; otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C close() fails if the any of following conditions are encountered: .RS .TP 15 .SM [EBADF] .I fildes is not a valid open file descriptor. .TP .SM [EINTR] An attempt to close a slow device or connection was interrupted by a signal. The file descriptor still points to an open device or connection. .TP .SM [ENOSPC] Not enough space on the file system. This error can occur when closing a file on an .SM NFS file system. [When a .C write() system call is executed on a local file system and if a new buffer needs to be allocated to hold the data, the buffer is mapped onto the disk at that time. A full disk is detected at this time and .C write() returns an error. When the .C write() system call is executed on an .SM NFS file system, the new buffer is allocated without communicating with the .SM NFS server to see if there is space for the buffer (to improve .SM NFS performance). It is only when the buffer is written to the server (at file close or the buffer is full) that the disk-full condition is detected.] .RE .SH SEE ALSO creat(2), dup(2), exec(2), fcntl(2), lockf(2), open(2), pipe(2). .SH STANDARDS CONFORMANCE .CR close() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4close()\fP \(mi close a file descriptor@@@\f3close(2)\f1 .\" index@file: close a file descriptor@@@\f3close(2)\f1 .\" index@descriptor, close a file@@@\f3close(2)\f1 .\" .\" toc@\f3close(2)\f1:\0\0\f4close()\fP@@@close a file descriptor .\" .\" fileset_database@close.2 PROGRAMING-MAN .\" $Header: connect.2,v 78.1 96/01/12 18:06:14 ssa Exp $ .TA c .TH connect 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME connect \- initiate a connection on a socket .SH SYNOPSIS .C "#include " .SS AF_CCITT only .C "#include " .SS AF_INET only .C "#include " .SS AF_UNIX only .C "#include " .PP .C "int connect(int s, const void *addr, int addrlen);" .SS _XOPEN_SOURCE_EXTENDED only .C "int connect(int s, const struct sockaddr *addr, size_t addrlen);" .SH DESCRIPTION The .CR connect() function initiates a connection on a socket. .PP .I s is a socket descriptor. .PP .I addr is a pointer to a socket address structure containing the address of a remote socket to which a connection is to be established. .PP .I addrlen is the size of this address structure. Since the size of the socket address structure varies among socket address families, the correct socket address structure should be used with each address family (for example, .CR "struct\ sockaddr_in" for AF_INET and .CR "struct\ sockaddr_un" for AF_UNIX). Typically, the .CR sizeof() function is used to pass this value (for example, .CR "sizeof(struct\ sockaddr_in)" ). .PP If the socket is of type .CR SOCK_DGRAM , .CR connect() specifies the peer address to which messages are to be sent, and the call returns immediately. Furthermore, this socket can only receive messages sent from this address. .PP If the socket is of type .CR SOCK_STREAM , .CR connect() attempts to contact the remote host to make a connection between the remote socket (peer) and the local socket specified by .IR s . The call normally blocks until the connection completes. If nonblocking mode has been enabled with the .CR O_NONBLOCK or .CR O_NDELAY .CR fcntl() flags or the .CR FIOSNBIO .CR ioctl() request and the connection cannot be completed immediately, .CR connect() returns an error as described below. In these cases, .CR select() can be used on this socket to determine when the connection has completed by selecting it for writing. .PP The .CR connect() system call will complete if remote program has a pending .CR listen() even though remote program had not yet issued an .CR accept() system call. .PP .CR O_NONBLOCK and .CR O_NDELAY are defined in .CR and explained in .IR fcntl (2), .IR fcntl (5), and .IR socket (7). .CR FIOSNBIO is defined in .CR and explained in .IR ioctl (2), .IR ioctl (5), and .IR socket (7). .PP If .I s is a .CR SOCK_STREAM socket that is bound to the same local address as another .CR SOCK_STREAM socket, .CR connect() returns [EADDRINUSE] if .I addr is the same as the peer address of that other socket. This situation can only happen if the .CR SO_REUSEADDR option has been set on .IR s , which is an AF_INET socket (see .IR getsockopt (2)). .PP If the AF_INET socket does not already have a local address bound to it (see .IR bind (2)), .CR connect() also binds the socket to a local address chosen by the system. .PP Generally, stream sockets may successfully connect only once; datagram sockets may use .CR connect() multiple times to change the peer address. For datagram sockets, a side effect of attempting to connect to some invalid address (see ERRORS below) is that the peer address is no longer maintained by the system. An example of an invalid address for a datagram socket is .I addrlen set to 0 and .I addr set to any value. .SS AF_CCITT Only Use the .CR x25addrstr struct for the address structure. The caller must know the X.121 address of the DTE to which the connection is to be established, including any subaddresses or protocol IDs that may be needed. Refer to .IR af_ccitt (7F) for a detailed description of the .CR x25addrstr address structure. If address-matching by protocol ID, specify the protocol ID with the .CR X25_WR_USER_DATA .CR ioctl() call before issuing the .CR connect() call. The .CR X25_WR_USER_DATA .CR ioctl() call is described in .IR socketx25 (7). .SH DEPENDENCIES .SS AF_CCITT The .CR SO_REUSEADDR option to .CR setsockopt() is not supported for sockets in the AF_CCITT address family. .SH RETURN VALUE .CR connect() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .SH ERRORS If .CR connect() fails, .CR errno is set to one of the following values. .RS .TP 25 [EADDRINUSE] The specified address is already in use. .IP For datagram sockets, the peer address is no longer maintained by the system. .TP [EADDRNOTAVAIL] The specified address is not available on this machine, or the socket is a TCP/UDP socket and the zero port number is specified. .IP For datagram sockets, the peer address is no longer maintained by the system. .TP [EAFNOSUPPORT] The specified address is not a valid address for the address family of this socket. .IP For datagram sockets, the peer address is no longer maintained by the system. .TP [EALREADY] Nonblocking I/O is enabled with .CR O_NONBLOCK , .CR O_NDELAY , or .CR FIOSNBIO , and a previous connection attempt has not yet completed. .TP [EBADF] .I s is not a valid file descriptor. .TP [ECONNREFUSED] The attempt to connect was forcefully rejected. .TP [EFAULT] .I addr is not a valid pointer. .TP [EINPROGRESS] Nonblocking I/O is enabled using .CR O_NONBLOCK , .CR O_NDELAY , or .CR FIOSNBIO, and the connection cannot be completed immediately. This is not a failure. Make the .CR connect() call again a few seconds later. Alternatively, wait for completion by calling .CR select() and selecting for write. .TP [EINTR] The connect was interrupted by a signal before the connect sequence was complete. The building of the connection still takes place, even though the user is not blocked on the .CR connect() call. .TP [EINVAL] The socket has already been shut down or has a .CR listen() active on it; .I addrlen is a bad value; an attempt was made to .CR connect() an AF_UNIX socket to an NFS-mounted (remote) name; the X.121 address length is zero, negative, or greater than 15 digits. .IP For datagram sockets, if .I addrlen is a bad value, the peer address is no longer maintained by the system. .TP [EISCONN] The socket is already connected. .TP [ENETDOWN] The X.25 interface specified in the .I addr struct was found but was not in the initialized state. .I x25ifname field name is an interface which has been shut down or never initialized or suffered a power failure which erased its state information. .TP [ENETUNREACH] The network is not reachable from this host. .IP For AF_CCITT only: X.25 Level 2 is down. The X.25 link is not working: wires might be broken, connections are loose on the interface hoods at the modem, the modem failed, or noise interfered with the line for an extremely long period of time. .TP [ENOBUFS] No buffer space is available. The .CR connect() has failed. .TP [ENODEV] The .IR x25ifname field refers to a nonexistent interface. .TP [ENOSPC] All available virtual circuits are in use. .TP [ENOTSOCK] .IR s is a valid file descriptor, but it is not a socket. .TP [EOPNOTSUPP] The socket referenced by .IR s does not support .CR connect() . With X.25 an attempt was made to issue a .CR connect() call on a .CR listen() socket. .TP [ETIMEDOUT] Connection establishment timed out without establishing a connection. One reason could be that the connection requests queue at the remote socket may be full (see .CR listen(2) ). .SH AUTHOR .CR connect() was developed by the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO accept(2), getsockname(2), select(2), socket(2), af_ccitt(7F), socket(7), socketx25(7), xopen_networking(7). .\" .\" index@\f1connection on a socket, initiate@@@\f3connect(2)\f1 .\" index@\f1initiate connection on a socket@@@\f3connect(2)\f1 .\" index@\f1socket, initiate connection@@@\f3connect(2)\f1 .\" index@\f4connect()\f1 \- initiate connection on socket@@@\f3connect(2)\f1 .\" .\" toc@\f3connect(2)\f1:\0\0\f4connect()\f1@@@initiate a connection on a socket .\" $Header: creat.2,v 78.1 96/02/12 13:35:58 ssa Exp $ .TA c .TH creat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME creat \- create a new file or rewrite an existing one .SH SYNOPSIS .C "#include " .PP .C "int creat(const char *path, mode_t mode);" .SH DESCRIPTION The .CR creat() system call creates a new regular file or prepares to rewrite an existing file named by the path name pointed to by .IR path . .PP If the file exists, its length is truncated to 0, and its mode and owner are unchanged. Otherwise, the file's owner ID is set to the effective user ID of the process. If the set-group-ID bit of the parent directory is set, the file's group ID is set to the group ID of the parent directory. Otherwise, the file's group ID is set to the process's effective group ID. The low-order 12 bits of the file mode are set to the value of .I mode modified as follows: .RS .TP 3 \(bu All bits set in the process's file mode creation mask are cleared (see .IR umask (2)). .TP \(bu The "save text image after execution" bit of the mode is cleared (see .IR chmod (2)). .RE .PP Upon successful completion, the file descriptor is returned and the file is open for writing (only), even if the .I mode does not permit writing. The file offset is set to the beginning of the file. The file descriptor is set to remain open across .CI exec * () system calls (see .IR fcntl (2)). Each process has a limit on how many files it can open simultaneously. Refer to .IR getrlimit (2) for the open files limit. This is also discussed in .IR open (2). A new file can be created with a mode that forbids writing. .SS "Access Control Lists - HFS File Systems Only" On systems that support access control lists, three base ACL entries are created corresponding to the file access permission bits. An existing file's access control list is unchanged by .CR creat() (see .IR setacl (2), .IR chmod (2), and .IR acl (5)). .SH RETURN VALUE .CR creat() returns the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the value of the file descriptor. It is nonnegative. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR creat() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] Search permission is denied on a component of the path prefix. .TP [EACCES] The file does not exist and the directory in which the file is to be created does not permit writing. .TP [EACCES] The file exists and write permission is denied. .TP [EAGAIN] The file exists, enforcement mode file and record locking is set and there are outstanding record locks on the file. .TP [EDQUOT] User's disk quota block or inode limit has been reached for this file system. .TP [EFAULT] .I path points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP [EISDIR] The named file is an existing directory. .TP [ELOOP] Too many symbolic links were encountered in translating the path name. .TP [EMFILE] More than the maximum number of file descriptors are currently open. .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENFILE] The system file table is full. .TP [ENOENT] The named file does not exist (for example, .I path is null, or a component of .I path does not exist). .TP [ENOSPC] Not enough space on the file system. .TP [ENOTDIR] A component of the path prefix is not a directory. .TP [ENXIO] The named file is a character special or block special file, and the device associated with this special file does not exist. .TP [EOVERFLOW] The named file is a regular file and the size of the file cannot be represented correctly in an object of type .CR off_t . .TP [EROFS] The named file resides or would reside on a read-only file system. .TP [ETXTBSY] The file is a pure procedure (shared text) file that is being executed. .RE .SH SEE ALSO chmod(2), close(2), creat64(2), dup(2), fcntl(2), lockf(2), lseek(2), open(2), open64(2), read(2), setacl(2), truncate(2), umask(2), write(2), acl(5).\"STD .SH STANDARDS CONFORMANCE .CR creat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4creat()\fP \(mi create a new file or rewrite an existing one@@@\f3creat(2)\f1 .\" index@file: create a new file or rewrite an existing one@@@\f3creat(2)\f1 .\" index@file: rewrite an existing file@@@\f3creat(2)\f1 .\" index@file: truncate an existing file to zero for rewriting@@@\f3creat(2)\f1 .\" index@create a new file or rewrite an existing one@@@\f3creat(2)\f1 .\" index@create a new file@@@\f3creat(2)\f1 .\" index@new file, create@@@\f3creat(2)\f1 .\" index@rewrite an existing file@@@\f3creat(2)\f1 .\" index@truncate an existing file to zero for rewriting@@@\f3creat(2)\f1 .\" index@existing file, truncate to zero for rewriting@@@\f3creat(2)\f1 .\" .\" toc@\f3creat(2)\f1:\0\0\f4creat()\fP@@@create a new file or rewrite an existing one .\" $Header: creat64.2,v 78.2 96/02/12 13:37:12 ssa Exp $ .TA c .TH creat64 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME creat64(\|), fstat64(\|), getrlimit64(\|), lockf64(\|), lseek64(\|), lstat64(\|), mmap64(\|), open64(\|), prealloc64(\|), setrlimit64(\|), stat64(\|), statvfs64(\|), truncate64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0creat64(const\0char\0*path,\0mode_t\0mode);" .PP .C "#include " .PP .C "int\0fstat64(int\0fildes,\0struct\0stat64\0*buf);" .PP .C "include\0" .PP .C "int\0getrlimit64(int resource,\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0lock64(int\0*fildes,\0int\0function,\0off64_t\0size);" .PP .C "#include " .PP .C "off64_t\0lseek64(int\0*fildes,\0off64_t\0offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0lstat64(const\0char\0*,\0struct\0stat64\0*);" .PP .C "#include " .PP .C "void\0mmap64(void\0addr,\0size_t\0len,\0int\0prot,\0int\0flags,\0int\0fildes,\0off64_t\0off);" .PP .C "#include " .PP .C "int\0open64(const\0char\0*path,\0int\0oflag,...);" .PP .C "#include " .PP .C "int\0prealloc64(int\0fildes,\0off64_t\0size);" .PP .C "include\0" .PP .C "int\0setrlimit64(int\0resource,\0const\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0stat64(const\0char\0*path,\0struct\0stat64\0*buf);" .PP .C "#include " .PP .C "int\0statvfs64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "int\0truncate64(const\0char\0*path,\0off64_t\0length);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 18 .C creat64() The .C creat64() function is identical to .C creat() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. .C creat64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR creat() . .TP .C fstat64() The .C fstat64() function is identical to .C fstat() except that .C fstat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C getrlimit64 The .C getrlimit64() function is identical to .C getrlimit() except that .C getrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .CR "struct rlimit" . All other functional behaviors, returns, and errors are identical. .TP .C lock64() The .C lock64() function is identical to .C lockf() except that .C lockf64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C lseek64() The .C lseek64() function is identical to .C lseek() except that .C lseek64() accepts an .CR off64_t type as the desired offset and has a return value of .CR off64_t. All other functional behaviors, returns, and errors are identical. .TP .C lstat64() The .C lstat64() function is identical to .C lstat() except that .C lstat64() returns file status in a .C struct stat64 instead of .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C mmap64() The .C mmap64() function is identical to .C mmap() except that .C mmap64() accepts the file offset as an .CR off64_t . .TP .C open64() The .C open64() function is identical to .C open() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. The .C open64() function is equivalent to .C open() function (in 32-bit compile environment) with .C O_LARGEFILE flag set. .C open64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR open() . .TP .C prealloc64() The .C prealloc64() function is identical to .C prealloc() except that .C prealloc64() accepts the file offset as an .CR off64_t . All other functional behaviors, returns, and errors are identical to .CR prealloc() . .TP .C setrlimit64 The .C setrlimit64() function is identical to .C setrlimit() except that .C setrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .C struct rlimit. All other functional behaviors, returns, and errors are identical. .TP .C stat64() The .C stat64() function is identical to .C stat() except that .C stat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . .TP .C statvfs64() Refer to .CR fstatvfs64() . .TP .C truncate64() The .C truncate64() function is identical to .C truncate() except that .C truncate64() accepts the length parameter as an .C off64_t instead of .CR off_t . All other functional behaviors, returns, and errors are identical to .CR truncate() . .\" .\" toc@\f4creat64(2)\f1:\0\0\f4fstat64\f1, \f4getrlimit64\f1, \f4lockf64\f1, \f4lseek64\f1, \f4lstat64\f1, \f4mmap64\f1, \f4open64\f1, \n\f4prealloc64\f1, \f4setrlimit64\f1, \f4stat64\f1, \f4statvfs64\f1, \f4truncate64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4creat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4fstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4getrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lockf64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lseek64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4mmap64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4open64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4prealloc64()\f1 \- file sysmmaptem API to support large files@@@\f3creat64(2)\f1 .\" index@\f4setrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4stat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4statvfs64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4truncate64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3creat64(2)\f1 .\" .\" links@creat64.2 fstat64.2 .\" links@creat64.2 getrlimit64.2 .\" links@creat64.2 lockf64.2 .\" links@creat64.2 lseek64.2 .\" links@creat64.2 lstat64.2 .\" links@creat64.2 mmap64.2 .\" links@creat64.2 open64.2 .\" links@creat64.2 prealloc64.2 .\" links@creat64.2 setrlimit64.2 .\" links@creat64.2 stat64.2 .\" links@creat64.2 statvfs64.2 .\" links@creat64.2 truncate64.2 .\" .\" $Header: dup.2,v 72.4 94/11/14 15:23:48 ssa Exp $ .TA d .TH dup 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dup \- duplicate an open file descriptor .SH SYNOPSIS .C "#include " .PP .C "int dup(int fildes);" .SH DESCRIPTION .I fildes is a file descriptor obtained from a .CR creat() , .CR open() , .CR dup() , .CR fcntl() , or .C pipe() system call. .C dup() returns a new file descriptor having the following in common with the original: .RS .TP 3 \(bu Same open file (or pipe). .TP \(bu Same file pointer (i.e., both file descriptors share one file pointer). .TP \(bu Same access mode (read, write or read/write). .TP \(bu Same file status flags (see .IR fcntl (2), .CR F_DUPFD ). .RE .PP The new file descriptor is set to remain open across .C exec() system calls. See .IR fcntl (2). .PP The file descriptor returned is the lowest one available. .SH RETURN VALUE Upon successful completion, the file descriptor is returned as a non-negative integer. Otherwise, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .C dup() fails if one or more of the following is true: .TP 25 .SM [EBADF] .I fildes is not a valid open file descriptor. .TP .SM [EMFILE] Request violates the maximum number of open file descriptors. .SH AUTHOR .C dup() was developed by AT&T and HP. .SH SEE ALSO close(2), creat(2), dup2(2), exec(2), fcntl(2), open(2), pipe(2). .SH STANDARDS CONFORMANCE .CR dup() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4dup()\fP \(mi duplicate an open file descriptor@@@\f3dup(2)\f1 .\" index@duplicate an open file descriptor@@@\f3dup(2)\f1 .\" index@open file descriptor, duplicate an@@@\f3dup(2)\f1 .\" index@file descriptor: duplicate an open file descriptor@@@\f3dup(2)\f1 .\" .\" toc@\f3dup(2)\f1:\0\0\f4dup()\fP@@@duplicate an open file descriptor .\" .\" fileset_database@dup.2 PROGRAMING-MAN .\" $Header: dup2.2,v 72.4 94/11/14 15:23:49 ssa Exp $ .TA d .TH dup2 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dup2 \- duplicate an open file descriptor to a specific slot .SH SYNOPSIS .C "#include " .PP .C "int dup2(int fildes, int fildes2);" .SH DESCRIPTION .I fildes is a file descriptor obtained from a .CR creat() , .CR open() , .CR dup() , .CR fcntl() , or .C pipe() system call. .PP .I fildes2 is a non-negative integer less than the maximum value allowed for file descriptors. .PP .C dup2() causes .I fildes2 to refer to the same file as .IR fildes . If .I fildes2 refers to an already open file, the open file is closed first. .PP The file descriptor returned by .C dup2() has the following in common with .IR fildes : .RS .TP 3 \(bu Same open file (or pipe). .TP \(bu Same file pointer (that is, both file descriptors share one file pointer.) .TP \(bu Same access mode (read, write or read/write). .TP \(bu Same file status flags (see .IR fcntl (2), .CR F_DUPFD ). .RE .PP The new file descriptor is set to remain open across .C exec() system calls. See .IR fcntl (2). .PP This routine is found in the C library. Programs using .C dup2() but not using other routines from the Berkeley importability library (such as the routines described in .IR bsdproc (2)) should not give the .C -lBSD option to .IR ld (1). .SH RETURN VALUE Upon successful completion, .C dup2() returns the new file descriptor as a non-negative integer, .IR fildes2 . Otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C dup2() fails if the following is true: .TP 15 .SM [EBADF] .I fildes is not a valid open file descriptor or .I fildes2 is not in the range of legal file descriptors. .TP .SM [EINTR] An attempt to close .I fildes2 was interrupted by a signal. The file is still open. .SH SEE ALSO close(2), creat(2), dup(2), exec(2), fcntl(2), open(2), pipe(2). .SH STANDARDS CONFORMANCE .CR dup2() ": AES, SVID2, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4dup2()\fP \(mi duplicate an open file descriptor to a specific slot@@@\f3dup2(2)\f1 .\" index@duplicate an open file descriptor to a specific slot@@@\f3dup2(2)\f1 .\" index@file descriptor: duplicate an open file descriptor to a specific slot@@@\f3dup2(2)\f1 .\" index@open file descriptor to a specific slot, duplicate an@@@\f3dup2(2)\f1 .\" .\" toc@\f3dup2(2)\f1:\0\0\f4dup2()\fP@@@duplicate an open file descriptor to a specific slot .\" .\" fileset_database@dup2.2 PROGRAMING-MAN .\" $Header: errno.2,v 72.7 94/11/14 15:23:50 ssa Exp $ .TA e .TH errno 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME errno \- error indicator for function calls .SH SYNOPSIS .C "#include " .PP .C "extern int errno;" .SH DESCRIPTION Many functions in the HP-UX operating system indicate an error condition by returning an otherwise out-of-range value (usually .CR -1 ). Most of these functions set the external variable .C errno to a nonzero code value that more specifically identifies the particular error condition that was encountered. .PP All errors detected and the corresponding error code values stored in .C errno are documented in the ERRORS section on manual pages for those functions that set it. .PP The value of .C errno is zero immediately after a successful call to any of the functions described by .IR exec (2) and .IR ptrace (2), but it is never set to zero by any other HP-UX function. Functions for which the use of .C errno is not described may nevertheless change its value to a nonzero value. .PP Since .C errno is .I not cleared on successful function calls, its value should be checked or used .I only when an error has been indicated and when the function's ERRORS section documents the error codes. .PP Applications should not attempt to take the address of .CR errno , because it may be converted to a macro in a future release. .PP The following is a complete list of the error codes. The numeric values can be found in .RC < errno.h > but they should not be used in an application program because they can vary from system to system. .TP 15 .SM [E2BIG] Arg list too long. An argument and or environment list longer than maximum supported size is presented to a member of the .C exec() family. Other possibilities include: message size or number of semaphores exceeds system limit .RC ( msgop , \ semop ), or too many privileged groups have been set up .RC ( setprivgrp ). .TP .SM [EACCES] Permission denied. An attempt was made to access a file or IPC object in a way forbidden by the protection system. .TP .SM [EADDRINUSE] Address already in use. Only one usage of each address is normally permitted. .TP .SM [EADDRNOTAVAIL] Cannot assign requested address. Normally results from an attempt to create a socket with an address not on this machine. .TP .SM [EAFNOSUPPORT] Address family not supported by protocol family. An address incompatible with the requested protocol was used. For example, you should not necessarily expect to be able to use PUP Internet addresses with ARPA Internet protocols. .TP .SM [EAGAIN] Resource temporarily unavailable. This is likely a temporary condition, and later calls to the same routine may complete normally. .TP .SM [EALREADY] Operation already in progress. An operation was attempted on a nonblocking object which already had an operation in progress. .TP .SM [EBADF] Bad file number. Either a file descriptor refers to no open file, a read (respectively write) request is made to a file which is open only for writing (respectively reading), or the file descriptor is not in the legal range of file descriptors. .TP .SM [EBUSY] Device or resource busy. An attempt to mount a device that was already mounted or an attempt was made to dismount a device on which there is an active file (open file, current directory, mounted-on file, active text segment). It will also occur if an attempt is made to enable accounting when it is already enabled. The device or resource is currently unavailable, such as when a nonsharable device file is in use. .TP .SM [ECHILD] No child processes. A .C wait() was executed by a process that had no existing or unwaited-for child processes. .TP .SM [ECONNABORTED] Software caused connection abort. A connection abort was caused internal to your host machine. .TP .SM [ECONNREFUSED] Connection refused. No connection could be made because the target machine actively refused it. This usually results from trying to connect to a service that is inactive on the foreign host. .TP .SM [ECONNRESET] Connection reset by peer. A connection was forcibly closed by a peer. This normally results from the peer executing a .C shutdown() call (see .IR shutdown (2)). .TP .SM [EDEADLK] Resource deadlock would occur. A process which has locked a system resource would have been put to sleep while attempting to access another process' locked resource. .TP .SM [EDESTADDRREQ] Destination address required. A required address was omitted from an operation on a socket. .TP .SM [EDOM] Math argument. The argument of a function in the math package (3M) is out of the domain of the function. .TP .SM [EEXIST] File exists. An existing file was mentioned in an inappropriate context; e.g., .CR link() . .TP .SM [EFAULT] Bad address. The system encountered a hardware fault in attempting to use an argument of a system call; can also result from passing the wrong number of parameters to a system call. The reliable detection of this error is implementation dependent. .TP .SM [EFBIG] File too large. The size of a file exceeded the maximum file size (for the file system) or .C ULIMIT was exceeded (see .IR ulimit (2)), or a bad semaphore number in a .C semop() call (see .IR semop (2)). .TP .SM [EHOSTDOWN] Host is down. A socket operation encountered a dead host. Networking activity on the local host has not been initiated. .TP .SM [EHOSTUNREACH] No route to host. A socket operation was attempted to an unreachable host. .TP .SM [EIDRM] Identifier Removed. This error is returned to processes that resume execution due to the removal of an identifier from the file system's name space (see .IR msgctl (2), .IR semctl (2), and .IR shmctl (2)). .TP .SM [EILSEQ] Illegal byte sequence. A wide character code has been detected that does not correspond to a valid character, or a byte sequence does not form a valid wide character code. .TP .SM [EINPROGRESS] Operation now in progress. An operation that takes a long time to complete was attempted on a nonblocking object (see .IR ioctl (2) and .IR fcntl (2)). .TP .SM [EINTR] Interrupted system call. An asynchronous signal (such as interrupt or quit), which the user has elected to catch, occurred during a system call. If execution is resumed after processing the signal, it will appear as if the interrupted system call returned this error condition unless the system call is restarted (see .IR sigvector (2)). .TP .SM [EINVAL] Invalid argument. Some invalid argument (such as unmounting a device that is not currently mounted, mentioning an undefined signal in .C signal() or .CR kill() , or reading or writing a file for which .C lseek() has generated a negative pointer). Also set by the math functions described in the (3M) entries of this manual. .TP .SM [EIO] I/O error \(mi some physical I/O error. This error may in some cases occur on a call following the one to which it actually applies. .TP .SM [EISCONN] Socket is already connected. A .C connect() request was made on an already connected socket, or, a .C sendto() or .C sendmsg() request on a connected socket specified a destination other than the connected party. .TP .SM [EISDIR] Is a directory. An attempt to open a directory for writing. .TP .SM [ELOOP] Too many levels of symbolic links. A path name search involved more than .C MAXSYMLINKS symbolic links. .C MAXSYMLINKS is defined in .RC < sys/param.h >. .TP .SM [EMFILE] Too many open files. No process may have more than a system-defined number of file descriptors open at a time. .TP .SM [EMLINK] Too many links. An attempt to make more than the maximum number of links to a file. .TP .SM [EMSGSIZE] Message too long. The socket requires that the message be sent atomically, and the size of the message to be sent made this impossible. .TP .SM [ENAMETOOLONG] File name too long. A path specified exceeds the maximum path length for the system. The maximum path length is specified by .C PATH_MAX and is defined in .RC < limits.h >. PATH_MAX is guaranteed to be at least 1023 bytes. This error is also generated if the length of a path name component exceeds .C NAME_MAX and the .C _POSIX_NO_TRUNC option is in effect for the specified path. Currently, .C _POSIX_NO_TRUNC is in effect only for HFS file systems configured to allow path name components up to 255 bytes long (see .IR convertfs (1M)) and therefore only path names referring to such file systems can generate the error for this case. The values of .CR NAME_MAX , .CR PATH_MAX , and .C _POSIX_NO_TRUNC for a particular path name can be queried by using the .C pathconf() system call (see .IR pathconf (2)). .TP .SM [ENETDOWN] Network is down. A socket operation encountered a dead network. .TP .SM [ENETRESET] Network dropped connection on reset. The host you were connected to crashed and rebooted. .TP .SM [ENETUNREACH] Network is unreachable. A socket operation was attempted to an unreachable network. .TP .SM [ENFILE] File table overflow. The system's table of open files is full, and temporarily no more .CR open() s can be accepted. .TP .SM [ENOBUFS] No buffer space available. An operation on a socket was not performed because the system lacked sufficient buffer space. .TP .SM [ENODEV] No such device. An attempt was made to apply an inappropriate system call to a device (such as read a write-only device). .TP .SM [ENOENT] No such file or directory. This error occurs when a file name is specified and the file should exist but does not, or when one of the directories in a path name does not exist. It also occurs with .CR msgget() , .CR semget() , and .C shmget() when .I key does not refer to any object and the .C IPC_CREAT flag is not set. .TP .SM [ENOEXEC] Exec format error. A request is made to execute a file which, although it has the appropriate permissions, does not start with a valid magic number (see .IR a.out (4)), or the file is too small to have a valid executable file header. .TP .SM [ENOLCK] System lock table is full. Too many files have file locks on them, or there are too many record locks on files, or there are too many instances of a reading or writing process sleeping until an enforcement mode lock clears. This error may also indicate system problems in handling a lock request on a remote NFS file. This error is also currently returned for all attempts to perform locking operations on a remote NFS file that has its locking enforcement mode bit set, since the stateless nature of NFS prevents maintaining the necessary lock information. .TP .SM [ENOMEM] Not enough space. During a system call such as .CR exec() , .CR brk() , .CR fork() , or .CR sbrk() , a program asks for more space than the system is able to supply. This may not be a temporary condition; the maximum space size is a system parameter. The error can also occur if there is not enough swap space during a .CR fork() . .TP .SM [ENOMSG] No message of desired type. An attempt was made to receive a message of a type that does not exist on the specified message queue; see .IR msgop (2). .TP .SM [ENOPROTOOPT] Protocol not available. A bad option was specified in a .C getsockopt() or .C setsockopt() call (see .IR getsockopt (2)). .TP .SM [ENOSPC] No space left on device. During a .C write() to an ordinary file, there is no free space left on the device; or no space in system table during .CR msgget() , .CR semget() , or .C semop() while .C SEM_UNDO flag is set. .TP .SM [ENOSYM] Symbol does not exist in executable. The dynamic loader was unable to resolve a symbolic reference in a shared library during a call to one of the dynamic loader interface routines (see .IR shl_load (3X). The program may be in an inconsistent state and should be terminated immediately. .TP .SM [ENOSYS] Function is not available. The requested function or operation is not implemented or not configured in the system. .TP .SM [ENOTBLK] Block device required. A nonblock file was mentioned where a block device was required, such as in .CR mount() . .TP .SM [ENOTCONN] Socket is not connected. A request to send or receive data was disallowed because the socket was not connected. .TP .SM [ENOTDIR] Not a directory. A nondirectory was specified where a directory is required, such as in a path prefix or as an argument to .CR chdir() . .TP .SM [ENOTEMPTY] Directory not empty. An attempt was made to remove a nonempty directory. .TP .SM [ENOTSOCK] Socket operation on nonsocket. An operation was attempted on something that is not a socket. .TP .SM [ENOTTY] Not a typewriter. The .RC ( ioctl() ) command is inappropriate to the selected device type. .TP .SM [ENXIO] No such device or address. I/O on a special file refers to a subdevice that does not exist, or is beyond the limits of the device. It can also occur when, for example, a tape drive is not on line or no disk pack is loaded on a drive. .TP .SM [EOPNOTSUPP] Operation not supported. The requested operation on a socket or NFS file is either invalid or unsupported. For example, this might occur when an attempt to .C accept() a connection on a datagram socket fails. .TP .SM [EPERM] Not owner. Typically, this error indicates an attempt to modify a file in some way forbidden except to its owner or the superuser, such as to change its mode. It is also returned for attempts by ordinary users to do things for which they need, but lack, a special privilege. .TP .SM [EPFNOSUPPORT] Protocol family not supported. The protocol family has not been configured into the system or no implementation for it exists. The socket is not connected. .TP .SM [EPIPE] Broken pipe. Data has been written to a pipe for which the other (reading) end has been closed. This most often occurs when the reading process exits before the writing process. This condition also generates the signal .CR SIGPIPE ; the error is returned if the signal is ignored. .TP .SM [EPROTONOSUPPORT] Protocol not supported. The protocol has not been configured into the system or no implementation for it exists. .TP .SM [EPROTOTYPE] Protocol wrong type for socket. A protocol was specified that does not support the semantics of the socket type requested. For example, ARPA Internet UDP protocol cannot be used with type .C SOCK_STREAM. .TP .SM [ERANGE] Result too large. The value of a function in the math package (3M) is not representable within machine precision, or a .C semop() call would cause either a semaphore value or a semaphore adjust value to exceed it system-imposed maximum. .TP .SM [EROFS] Read-only file system. An attempt to modify a file or directory was made on a device mounted read-only. .TP .SM [ESHUTDOWN] Cannot send after socket shutdown. A request to send data was disallowed because the socket had already been shut down with a previous .C shutdown() call. .TP .SM [ESOCKTNOSUPPORT] Socket type not supported. The support for the socket type has not been configured into the system or no implementation for it exists. .TP .SM [ESPIPE] Illegal seek. An .C lseek() was issued to a pipe. .TP .SM [ESRCH] No such process. No process can be found corresponding to that specified by .I pid in .CR kill() , .CR rtprio() , or .CR ptrace() , or the process is not accessible. .TP .SM [ETIMEDOUT] Connection timed out. A .C connect() request failed because the connected party did not properly respond after a period of time (timeout period varies, depending on the communication protocol). .TP .SM [ETXTBSY] Text file busy. An attempt to execute an executable file which is currently open for writing (or reading). Also, an attempt to open for writing an otherwise writable file which is currently open for execution. .TP .SM [EWOULDBLOCK] Operation would block. An operation which would cause a process to block was attempted on an object in nonblocking mode (see .IR ioctl (2) and .IR fcntl (2)). .TP .SM [EXDEV] Cross-device link. A link to a file on another device was attempted. .SH DEPENDENCIES The following NFS errors are also defined: .RE 5 .TP 15 .PD .SM [EREFUSED] The same error as ECONNREFUSED. The external variable .C errno is defined as ECONNREFUSED for NFS compatibility. .TP .SM [EREMOTE] Too many levels of remote in path. An attempt was made to remotely mount an NFS file system into a path which already has a remotely mounted NFS file system component. .TP .SM [ESTALE] Stale NFS file handle. A client referenced an open file, but the file was previously deleted. .RE .SH STANDARDS CONFORMANCE .CR errno ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4errno()\f1 \- error indicator for system calls@@@\f3errno(2)\f1 .\" index@\f1error indicator for system calls@@@\f3errno(2)\f1 .\" index@\f1system-calls error indicator@@@\f3errno(2)\f1 .\" .\" toc@\f3errno(2)\f1:\0\0\f4errno()\f1@@@error indicator for system calls .\" $Header: exec.2,v 78.1 95/12/20 10:45:59 ssa Exp $ .TA e .TH exec 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME execl(), execle(), execlp(), execv(), execve(), execvp() \- execute a file .SH SYNOPSIS .nf .C "#include " .PP .C "extern char **environ;" .PP .CR "int execl(const char *path, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0" .CR " */" .CR ");" .PP .CR "int execle(const char *path, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0," .CR " * char * const envp[]" .CR " */" .CR ");" .PP .CR "int execlp(const char *file, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0" .CR " */" .CR ");" .PP .C "int execv(const char *path, char * const argv[]);" .PP .C "int execve(const char *path, char * const argv[], char * const envp[]);" .PP .C "int execvp(const char *file, char * const argv[]);" .fi .SS Remarks The ANSI C "\c .CR ", ...\&\c" " construct denotes a variable length argument list whose optional and required members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION The .CI exec * () system calls, in all their forms, load a program from an ordinary, executable file into the current process, replacing the current program. The .IR path or .IR file argument refers to either an executable object file or a file of data for an interpreter. In the latter case, the file of data is also called a script file. .PP An executable object file consists of a header (see .IR a.out (4)), text segment, and data segment. The data segment contains an initialized portion and an uninitialized portion (bss). For .CR execlp() and .CR execvp() the Bourne shell (see .IR sh-bourne (1)) can be loaded to interpret a script instead. A successful call to .CI exec * () does not return because the new program overwrites the calling program. .PP When a C program is executed, it is called as follows: .PP .RS .nf .C "main (argc, argv, envp)" .C "int argc;" .C "char **argv, **envp;" .fi .RE .PP where .IR argc is the argument count and .IR argv is the address of an array of character pointers to the arguments themselves. As indicated, .IR argc usually has a value of at least one, and the first member of the array points to a string containing the name of the file. Exit conditions from .IR main are discussed in .IR exit (2). .PP .IR path points to a path name that identifies the executable file containing the new program. .PP .IR file (in .CR execlp() or .CR execvp() ) points to a file name identifying the executable file containing the new program. The path prefix for this file is obtained by searching the directories passed in the environment variable .CR PATH (see .IR environ (5)). The environment is supplied by the shell (see .IR sh (1)). If .IR file does not have an executable magic number (see .IR magic (4)), it is passed to the Bourne shell as a shell script. .PP .IR arg0 ", ...," .IR argn are one or more pointers to null-terminated character strings. These strings constitute the argument list available to the new program. By convention, at least .IR arg0 must be present and point to a string identical to .IR path or to .IR path 's last component. .PP .IR argv is an array of character pointers to null-terminated strings. These strings constitute the argument list available to the new program. By convention, .IR argv must have at least one member, and must point to a string that is identical to .IR path or .IR path 's last component. .IR argv is terminated by a null pointer. .PP .IR envp is an array of character pointers to null-terminated strings. These strings constitute the environment in which the new program runs. .IR envp is terminated by a null pointer. For .CR execle() and .CR execve() , the C run-time start-off routine places a pointer to the environment of the calling program in the global cell: .IP .C "extern char **environ;" .PP and it is used to pass the environment of the calling program to the new program. .PP Open file descriptors remain open, except for those whose close-on-exec flag is set (see .IR fcntl (2)). The file offset, access mode, and status flags of open file descriptors are unchanged. .PP Note that normal executable files are open only briefly when they start execution. Other executable file types can be kept open for a long time, or even indefinitely under some circumstances. .PP The processing of signals by the process is unchanged by .CI exec * () \f1, except that signals caught by the process are set to their default values (see .IR signal (2)). .PP If the set-user-ID mode bit of the executable file pointed to by .IR path or .IR file is set (see .IR chmod (2)), .CI exec * () sets the effective user ID of the new process to the user ID of the executable file. Similarly, if the set-group-ID mode bit of the executable file is set, the effective group ID of the process is set to the group ID of the executable file. The real user ID and real group ID of the process are unchanged. Note that the set-user-ID and set-group-ID functions do not apply to scripts; thus, if .CR execlp() or .CR execvp() executes a script, the set-user-ID and set-group-ID bits are ignored, even if they are set. .PP The saved user ID and saved group ID of the process are always set to the effective user ID and effective group ID, respectively, of the process at the end of the .CI exec * () \f1, whether or not set-user-ID or set-group-ID is in effect. .PP The shared memory segments attached to the calling program are not attached to the new program (see .IR shmop (2)). .PP Text and data segment memory locks are not passed on to the new program (see .IR plock (2)). .PP Profiling is disabled for the new process (see .IR profil (2)). .PP The process also retains the following attributes: .RS .TP 3 .PD 0 \(bu current working directory .TP \(bu file creation mode mask (see .IR umask (2)) .TP \(bu file locks (see .IR fcntl (2)), except for files closed-on-execution .TP \(bu file size limit (see .IR ulimit (2)) .TP \(bu interval timers (see .IR getitimer (2)) .TP \(bu nice value (see .IR nice (2)) .TP \(bu nice value (see parent process ID) .TP \(bu pending signals .TP \(bu process ID .TP \(bu process group ID .TP \(bu real user ID .TP \(bu real group ID .TP \(bu process start time .TP \(bu real-time priority (see .IR rtprio (2)) .TP \(bu root directory (see .IR chroot (2)) .TP \(bu .IR semadj values (see .IR semop (2)) .TP \(bu session membership .TP \(bu signal mask (see .IR sigvector (2)) .TP \(bu supplementary group IDs .TP \(bu time left until an alarm clock signal (see .IR alarm (2)) .TP \(bu trace flag (see the .CR PT_SETTRC request of .IR ptrace (2)) .TP \(bu .CR tms_utime , .CR tms_stime , .CR tms_cutime , and .CR tms_cstime (see .IR times (2)) .RE .PD .PP The initial line of a script file must begin with .CR #!\& as the first two bytes, followed by zero or more spaces, followed by .IR interpreter or .IR "interpreter argument" , as in: .IP .CI "#!\& \&" interpreter\0\f1[\f2argument\f1] .PP One or more spaces or tabs must separate .IR interpreter and .IR argument . The first line should end with either a newline or a null character. .PP When the script file is executed, the system executes the specified .IR interpreter as an executable object file. Even in the case of .CR execlp() or .CR execvp() , no path searching is done of the interpreter name. .PP The .IR argument is anything that follows .IR interpreter and tabs or spaces. If an .IR argument is given, it is passed to the .IR interpreter as .CR argv[1] , and the name of the script file is passed as .CR argv[2] . Otherwise, the name of the script file is passed as .CR argv[1] . .CR argv[0] is passed as specified in the .CI exec * () call, unless either .CR argv or .CR argv[0] is null as specified, in which case a pointer to a null string is passed as .CR argv[0] . All other arguments specified in the .CI exec * () call are passed following the name of the script file (that is, beginning at .CR argv[3] if there is an argument; otherwise, at .CR argv[2] ). .PP If the initial line of the script file exceeds a system-defined maximum number of characters, .CI exec * () fails. The minimum value for this limit is 32. .PP The set-user-ID and set-group-ID bits are honored for the script but not for the interpreter. .SH RETURN VALUE If .CI exec * () returns to the calling program, an error has occurred; the return value is .CR -1 and .CR errno is set to indicate the error. .SH ERRORS If .CI exec * () fails and returns to the calling program, .CR errno is set to one of the following values: .RS .TP 20 [E2BIG] The number of bytes in the new program's argument list is greater than the system-imposed limit. This limit is at least 5120 bytes on HP-UX systems. .TP [EACCES] Read permission is denied for the executable file or interpreter, and the trace flag (see .IR ptrace (2) request .CR PT_SETTRC ) of the process is set. .TP [EACCES] Search permission is denied for a directory listed in the executable file's or the interpreter's path prefix. .TP [EACCES] The executable file or the interpreter is not an ordinary file. .TP [EACCES] The file described by .IR path or .IR file is not executable. The superuser cannot execute a file unless at least one access permission bit or entry in its access control list has an execute bit set. .TP [EFAULT] .IR path , .IR argv , or .IR envp point to an illegal address. The reliable detection of this error is implementation dependent. .TP [EINVAL] The executable file is incompatible with the architecture on which the .CI exec * () has been performed, and is presumed to be for a different architecture. It is not guaranteed that every architecture's executable files will be recognized. .TP [ELOOP] Too many symbolic links were encountered in translating the path name. .TP [ENAMETOOLONG] The executable file's path name or the interpreter's path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] .IR path is null. .TP [ENOENT] One or more components of the executable file's path name or the interpreter's path name does not exist. .TP [ENOEXEC] The executable file is shorter than indicated by the size values in its header, or is otherwise inconsistent. The reliable detection of this error is implementation dependent. .TP [ENOEXEC] The function call is not .CR execlp() or .CR execvp() , and the executable file has the appropriate access permission, but there is neither a valid magic number nor the characters .CR #!\& as the first two bytes of the file's initial line. .TP [ENOEXEC] The number of bytes in the initial line of a script file exceeds the system's maximum. .TP [ENOMEM] The new process requires more memory than is available or allowed by the system-imposed maximum. .TP [ENOTDIR] A component of the executable file's path prefix or the interpreter's path prefix is not a directory. .TP [ETXTBSY] The executable file is currently open for writing. .RE .SH WARNINGS .PP Unsharable executable files are not supported. These are files whose .CR EXEC_MAGIC magic number was produced with the .CR -N option of .CR ld (see .IR ld (1)). .SH DEPENDENCIES .SS HP Process Resource Manager If the optional HP Process Resource Manager (PRM) software is installed and configured, the process's process resource group ID is not changed by .CI exec * (). See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for the definition of process resource group. .SH SEE ALSO sh(1), sh-bourne(1), alarm(2), exit(2), fork(2), nice(2), ptrace(2), semop(2), signal(2), times(2), ulimit(2), umask(2), a.out(4), acl(5),\" STD only environ(5), signal(5). .PP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR environ ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execle() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execlp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execv() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execve() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execvp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f1execute a file@@@\f3exec(2)\f1 .\" index@\f1file: execute a file@@@\f3exec(2)\f1 .\" index@\f1object-code file, execute@@@\f3exec(2)\f1 .\" index@\f4execl()\f1, \f4execle()\f1, \f4execlp()\f1, \f4execv()\f1, \f4execve()\f1, \f4execvp()\f1 \- execute a file@@@\f3exec(2)\f1 .\" .\" index@\f1PRM@@@\f2see \f1Process Resource Manager .\" index@\f1Process Resource Manager@@@\f3exec(2)\f1 .\" .\" toc@\f3exec(2)\f1:\0\0\f4execl()\f1, \f4execle()\f1, \f4execlp()\f1, \f4execv()\f1, \f4execve()\f1, \f4execvp()\f1@@@execute a file .\" toc@\f4execl()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execle()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execlp()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execv()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execve()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execvp()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" .\" links@exec.2 execl.2 .\" links@exec.2 execle.2 .\" links@exec.2 execlp.2 .\" links@exec.2 execv.2 .\" links@exec.2 execve.2 .\" links@exec.2 execvp.2 .\" $Header: exec.2,v 78.1 95/12/20 10:45:59 ssa Exp $ .TA e .TH exec 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME execl(), execle(), execlp(), execv(), execve(), execvp() \- execute a file .SH SYNOPSIS .nf .C "#include " .PP .C "extern char **environ;" .PP .CR "int execl(const char *path, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0" .CR " */" .CR ");" .PP .CR "int execle(const char *path, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0," .CR " * char * const envp[]" .CR " */" .CR ");" .PP .CR "int execlp(const char *file, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0" .CR " */" .CR ");" .PP .C "int execv(const char *path, char * const argv[]);" .PP .C "int execve(const char *path, char * const argv[], char * const envp[]);" .PP .C "int execvp(const char *file, char * const argv[]);" .fi .SS Remarks The ANSI C "\c .CR ", ...\&\c" " construct denotes a variable length argument list whose optional and required members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION The .CI exec * () system calls, in all their forms, load a program from an ordinary, executable file into the current process, replacing the current program. The .IR path or .IR file argument refers to either an executable object file or a file of data for an interpreter. In the latter case, the file of data is also called a script file. .PP An executable object file consists of a header (see .IR a.out (4)), text segment, and data segment. The data segment contains an initialized portion and an uninitialized portion (bss). For .CR execlp() and .CR execvp() the Bourne shell (see .IR sh-bourne (1)) can be loaded to interpret a script instead. A successful call to .CI exec * () does not return because the new program overwrites the calling program. .PP When a C program is executed, it is called as follows: .PP .RS .nf .C "main (argc, argv, envp)" .C "int argc;" .C "char **argv, **envp;" .fi .RE .PP where .IR argc is the argument count and .IR argv is the address of an array of character pointers to the arguments themselves. As indicated, .IR argc usually has a value of at least one, and the first member of the array points to a string containing the name of the file. Exit conditions from .IR main are discussed in .IR exit (2). .PP .IR path points to a path name that identifies the executable file containing the new program. .PP .IR file (in .CR execlp() or .CR execvp() ) points to a file name identifying the executable file containing the new program. The path prefix for this file is obtained by searching the directories passed in the environment variable .CR PATH (see .IR environ (5)). The environment is supplied by the shell (see .IR sh (1)). If .IR file does not have an executable magic number (see .IR magic (4)), it is passed to the Bourne shell as a shell script. .PP .IR arg0 ", ...," .IR argn are one or more pointers to null-terminated character strings. These strings constitute the argument list available to the new program. By convention, at least .IR arg0 must be present and point to a string identical to .IR path or to .IR path 's last component. .PP .IR argv is an array of character pointers to null-terminated strings. These strings constitute the argument list available to the new program. By convention, .IR argv must have at least one member, and must point to a string that is identical to .IR path or .IR path 's last component. .IR argv is terminated by a null pointer. .PP .IR envp is an array of character pointers to null-terminated strings. These strings constitute the environment in which the new program runs. .IR envp is terminated by a null pointer. For .CR execle() and .CR execve() , the C run-time start-off routine places a pointer to the environment of the calling program in the global cell: .IP .C "extern char **environ;" .PP and it is used to pass the environment of the calling program to the new program. .PP Open file descriptors remain open, except for those whose close-on-exec flag is set (see .IR fcntl (2)). The file offset, access mode, and status flags of open file descriptors are unchanged. .PP Note that normal executable files are open only briefly when they start execution. Other executable file types can be kept open for a long time, or even indefinitely under some circumstances. .PP The processing of signals by the process is unchanged by .CI exec * () \f1, except that signals caught by the process are set to their default values (see .IR signal (2)). .PP If the set-user-ID mode bit of the executable file pointed to by .IR path or .IR file is set (see .IR chmod (2)), .CI exec * () sets the effective user ID of the new process to the user ID of the executable file. Similarly, if the set-group-ID mode bit of the executable file is set, the effective group ID of the process is set to the group ID of the executable file. The real user ID and real group ID of the process are unchanged. Note that the set-user-ID and set-group-ID functions do not apply to scripts; thus, if .CR execlp() or .CR execvp() executes a script, the set-user-ID and set-group-ID bits are ignored, even if they are set. .PP The saved user ID and saved group ID of the process are always set to the effective user ID and effective group ID, respectively, of the process at the end of the .CI exec * () \f1, whether or not set-user-ID or set-group-ID is in effect. .PP The shared memory segments attached to the calling program are not attached to the new program (see .IR shmop (2)). .PP Text and data segment memory locks are not passed on to the new program (see .IR plock (2)). .PP Profiling is disabled for the new process (see .IR profil (2)). .PP The process also retains the following attributes: .RS .TP 3 .PD 0 \(bu current working directory .TP \(bu file creation mode mask (see .IR umask (2)) .TP \(bu file locks (see .IR fcntl (2)), except for files closed-on-execution .TP \(bu file size limit (see .IR ulimit (2)) .TP \(bu interval timers (see .IR getitimer (2)) .TP \(bu nice value (see .IR nice (2)) .TP \(bu nice value (see parent process ID) .TP \(bu pending signals .TP \(bu process ID .TP \(bu process group ID .TP \(bu real user ID .TP \(bu real group ID .TP \(bu process start time .TP \(bu real-time priority (see .IR rtprio (2)) .TP \(bu root directory (see .IR chroot (2)) .TP \(bu .IR semadj values (see .IR semop (2)) .TP \(bu session membership .TP \(bu signal mask (see .IR sigvector (2)) .TP \(bu supplementary group IDs .TP \(bu time left until an alarm clock signal (see .IR alarm (2)) .TP \(bu trace flag (see the .CR PT_SETTRC request of .IR ptrace (2)) .TP \(bu .CR tms_utime , .CR tms_stime , .CR tms_cutime , and .CR tms_cstime (see .IR times (2)) .RE .PD .PP The initial line of a script file must begin with .CR #!\& as the first two bytes, followed by zero or more spaces, followed by .IR interpreter or .IR "interpreter argument" , as in: .IP .CI "#!\& \&" interpreter\0\f1[\f2argument\f1] .PP One or more spaces or tabs must separate .IR interpreter and .IR argument . The first line should end with either a newline or a null character. .PP When the script file is executed, the system executes the specified .IR interpreter as an executable object file. Even in the case of .CR execlp() or .CR execvp() , no path searching is done of the interpreter name. .PP The .IR argument is anything that follows .IR interpreter and tabs or spaces. If an .IR argument is given, it is passed to the .IR interpreter as .CR argv[1] , and the name of the script file is passed as .CR argv[2] . Otherwise, the name of the script file is passed as .CR argv[1] . .CR argv[0] is passed as specified in the .CI exec * () call, unless either .CR argv or .CR argv[0] is null as specified, in which case a pointer to a null string is passed as .CR argv[0] . All other arguments specified in the .CI exec * () call are passed following the name of the script file (that is, beginning at .CR argv[3] if there is an argument; otherwise, at .CR argv[2] ). .PP If the initial line of the script file exceeds a system-defined maximum number of characters, .CI exec * () fails. The minimum value for this limit is 32. .PP The set-user-ID and set-group-ID bits are honored for the script but not for the interpreter. .SH RETURN VALUE If .CI exec * () returns to the calling program, an error has occurred; the return value is .CR -1 and .CR errno is set to indicate the error. .SH ERRORS If .CI exec * () fails and returns to the calling program, .CR errno is set to one of the following values: .RS .TP 20 [E2BIG] The number of bytes in the new program's argument list is greater than the system-imposed limit. This limit is at least 5120 bytes on HP-UX systems. .TP [EACCES] Read permission is denied for the executable file or interpreter, and the trace flag (see .IR ptrace (2) request .CR PT_SETTRC ) of the process is set. .TP [EACCES] Search permission is denied for a directory listed in the executable file's or the interpreter's path prefix. .TP [EACCES] The executable file or the interpreter is not an ordinary file. .TP [EACCES] The file described by .IR path or .IR file is not executable. The superuser cannot execute a file unless at least one access permission bit or entry in its access control list has an execute bit set. .TP [EFAULT] .IR path , .IR argv , or .IR envp point to an illegal address. The reliable detection of this error is implementation dependent. .TP [EINVAL] The executable file is incompatible with the architecture on which the .CI exec * () has been performed, and is presumed to be for a different architecture. It is not guaranteed that every architecture's executable files will be recognized. .TP [ELOOP] Too many symbolic links were encountered in translating the path name. .TP [ENAMETOOLONG] The executable file's path name or the interpreter's path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] .IR path is null. .TP [ENOENT] One or more components of the executable file's path name or the interpreter's path name does not exist. .TP [ENOEXEC] The executable file is shorter than indicated by the size values in its header, or is otherwise inconsistent. The reliable detection of this error is implementation dependent. .TP [ENOEXEC] The function call is not .CR execlp() or .CR execvp() , and the executable file has the appropriate access permission, but there is neither a valid magic number nor the characters .CR #!\& as the first two bytes of the file's initial line. .TP [ENOEXEC] The number of bytes in the initial line of a script file exceeds the system's maximum. .TP [ENOMEM] The new process requires more memory than is available or allowed by the system-imposed maximum. .TP [ENOTDIR] A component of the executable file's path prefix or the interpreter's path prefix is not a directory. .TP [ETXTBSY] The executable file is currently open for writing. .RE .SH WARNINGS .PP Unsharable executable files are not supported. These are files whose .CR EXEC_MAGIC magic number was produced with the .CR -N option of .CR ld (see .IR ld (1)). .SH DEPENDENCIES .SS HP Process Resource Manager If the optional HP Process Resource Manager (PRM) software is installed and configured, the process's process resource group ID is not changed by .CI exec * (). See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for the definition of process resource group. .SH SEE ALSO sh(1), sh-bourne(1), alarm(2), exit(2), fork(2), nice(2), ptrace(2), semop(2), signal(2), times(2), ulimit(2), umask(2), a.out(4), acl(5),\" STD only environ(5), signal(5). .PP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR environ ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execle() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execlp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execv() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execve() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execvp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f1execute a file@@@\f3exec(2)\f1 .\" index@\f1file: execute a file@@@\f3exec(2)\f1 .\" index@\f1object-code file, execute@@@\f3exec(2)\f1 .\" index@\f4execl()\f1, \f4execle()\f1, \f4execlp()\f1, \f4execv()\f1, \f4execve()\f1, \f4execvp()\f1 \- execute a file@@@\f3exec(2)\f1 .\" .\" index@\f1PRM@@@\f2see \f1Process Resource Manager .\" index@\f1Process Resource Manager@@@\f3exec(2)\f1 .\" .\" toc@\f3exec(2)\f1:\0\0\f4execl()\f1, \f4execle()\f1, \f4execlp()\f1, \f4execv()\f1, \f4execve()\f1, \f4execvp()\f1@@@execute a file .\" toc@\f4execl()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execle()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execlp()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execv()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execve()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execvp()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" .\" links@exec.2 execl.2 .\" links@exec.2 execle.2 .\" links@exec.2 execlp.2 .\" links@exec.2 execv.2 .\" links@exec.2 execve.2 .\" links@exec.2 execvp.2 .\" $Header: exec.2,v 78.1 95/12/20 10:45:59 ssa Exp $ .TA e .TH exec 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME execl(), execle(), execlp(), execv(), execve(), execvp() \- execute a file .SH SYNOPSIS .nf .C "#include " .PP .C "extern char **environ;" .PP .CR "int execl(const char *path, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0" .CR " */" .CR ");" .PP .CR "int execle(const char *path, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0," .CR " * char * const envp[]" .CR " */" .CR ");" .PP .CR "int execlp(const char *file, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0" .CR " */" .CR ");" .PP .C "int execv(const char *path, char * const argv[]);" .PP .C "int execve(const char *path, char * const argv[], char * const envp[]);" .PP .C "int execvp(const char *file, char * const argv[]);" .fi .SS Remarks The ANSI C "\c .CR ", ...\&\c" " construct denotes a variable length argument list whose optional and required members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION The .CI exec * () system calls, in all their forms, load a program from an ordinary, executable file into the current process, replacing the current program. The .IR path or .IR file argument refers to either an executable object file or a file of data for an interpreter. In the latter case, the file of data is also called a script file. .PP An executable object file consists of a header (see .IR a.out (4)), text segment, and data segment. The data segment contains an initialized portion and an uninitialized portion (bss). For .CR execlp() and .CR execvp() the Bourne shell (see .IR sh-bourne (1)) can be loaded to interpret a script instead. A successful call to .CI exec * () does not return because the new program overwrites the calling program. .PP When a C program is executed, it is called as follows: .PP .RS .nf .C "main (argc, argv, envp)" .C "int argc;" .C "char **argv, **envp;" .fi .RE .PP where .IR argc is the argument count and .IR argv is the address of an array of character pointers to the arguments themselves. As indicated, .IR argc usually has a value of at least one, and the first member of the array points to a string containing the name of the file. Exit conditions from .IR main are discussed in .IR exit (2). .PP .IR path points to a path name that identifies the executable file containing the new program. .PP .IR file (in .CR execlp() or .CR execvp() ) points to a file name identifying the executable file containing the new program. The path prefix for this file is obtained by searching the directories passed in the environment variable .CR PATH (see .IR environ (5)). The environment is supplied by the shell (see .IR sh (1)). If .IR file does not have an executable magic number (see .IR magic (4)), it is passed to the Bourne shell as a shell script. .PP .IR arg0 ", ...," .IR argn are one or more pointers to null-terminated character strings. These strings constitute the argument list available to the new program. By convention, at least .IR arg0 must be present and point to a string identical to .IR path or to .IR path 's last component. .PP .IR argv is an array of character pointers to null-terminated strings. These strings constitute the argument list available to the new program. By convention, .IR argv must have at least one member, and must point to a string that is identical to .IR path or .IR path 's last component. .IR argv is terminated by a null pointer. .PP .IR envp is an array of character pointers to null-terminated strings. These strings constitute the environment in which the new program runs. .IR envp is terminated by a null pointer. For .CR execle() and .CR execve() , the C run-time start-off routine places a pointer to the environment of the calling program in the global cell: .IP .C "extern char **environ;" .PP and it is used to pass the environment of the calling program to the new program. .PP Open file descriptors remain open, except for those whose close-on-exec flag is set (see .IR fcntl (2)). The file offset, access mode, and status flags of open file descriptors are unchanged. .PP Note that normal executable files are open only briefly when they start execution. Other executable file types can be kept open for a long time, or even indefinitely under some circumstances. .PP The processing of signals by the process is unchanged by .CI exec * () \f1, except that signals caught by the process are set to their default values (see .IR signal (2)). .PP If the set-user-ID mode bit of the executable file pointed to by .IR path or .IR file is set (see .IR chmod (2)), .CI exec * () sets the effective user ID of the new process to the user ID of the executable file. Similarly, if the set-group-ID mode bit of the executable file is set, the effective group ID of the process is set to the group ID of the executable file. The real user ID and real group ID of the process are unchanged. Note that the set-user-ID and set-group-ID functions do not apply to scripts; thus, if .CR execlp() or .CR execvp() executes a script, the set-user-ID and set-group-ID bits are ignored, even if they are set. .PP The saved user ID and saved group ID of the process are always set to the effective user ID and effective group ID, respectively, of the process at the end of the .CI exec * () \f1, whether or not set-user-ID or set-group-ID is in effect. .PP The shared memory segments attached to the calling program are not attached to the new program (see .IR shmop (2)). .PP Text and data segment memory locks are not passed on to the new program (see .IR plock (2)). .PP Profiling is disabled for the new process (see .IR profil (2)). .PP The process also retains the following attributes: .RS .TP 3 .PD 0 \(bu current working directory .TP \(bu file creation mode mask (see .IR umask (2)) .TP \(bu file locks (see .IR fcntl (2)), except for files closed-on-execution .TP \(bu file size limit (see .IR ulimit (2)) .TP \(bu interval timers (see .IR getitimer (2)) .TP \(bu nice value (see .IR nice (2)) .TP \(bu nice value (see parent process ID) .TP \(bu pending signals .TP \(bu process ID .TP \(bu process group ID .TP \(bu real user ID .TP \(bu real group ID .TP \(bu process start time .TP \(bu real-time priority (see .IR rtprio (2)) .TP \(bu root directory (see .IR chroot (2)) .TP \(bu .IR semadj values (see .IR semop (2)) .TP \(bu session membership .TP \(bu signal mask (see .IR sigvector (2)) .TP \(bu supplementary group IDs .TP \(bu time left until an alarm clock signal (see .IR alarm (2)) .TP \(bu trace flag (see the .CR PT_SETTRC request of .IR ptrace (2)) .TP \(bu .CR tms_utime , .CR tms_stime , .CR tms_cutime , and .CR tms_cstime (see .IR times (2)) .RE .PD .PP The initial line of a script file must begin with .CR #!\& as the first two bytes, followed by zero or more spaces, followed by .IR interpreter or .IR "interpreter argument" , as in: .IP .CI "#!\& \&" interpreter\0\f1[\f2argument\f1] .PP One or more spaces or tabs must separate .IR interpreter and .IR argument . The first line should end with either a newline or a null character. .PP When the script file is executed, the system executes the specified .IR interpreter as an executable object file. Even in the case of .CR execlp() or .CR execvp() , no path searching is done of the interpreter name. .PP The .IR argument is anything that follows .IR interpreter and tabs or spaces. If an .IR argument is given, it is passed to the .IR interpreter as .CR argv[1] , and the name of the script file is passed as .CR argv[2] . Otherwise, the name of the script file is passed as .CR argv[1] . .CR argv[0] is passed as specified in the .CI exec * () call, unless either .CR argv or .CR argv[0] is null as specified, in which case a pointer to a null string is passed as .CR argv[0] . All other arguments specified in the .CI exec * () call are passed following the name of the script file (that is, beginning at .CR argv[3] if there is an argument; otherwise, at .CR argv[2] ). .PP If the initial line of the script file exceeds a system-defined maximum number of characters, .CI exec * () fails. The minimum value for this limit is 32. .PP The set-user-ID and set-group-ID bits are honored for the script but not for the interpreter. .SH RETURN VALUE If .CI exec * () returns to the calling program, an error has occurred; the return value is .CR -1 and .CR errno is set to indicate the error. .SH ERRORS If .CI exec * () fails and returns to the calling program, .CR errno is set to one of the following values: .RS .TP 20 [E2BIG] The number of bytes in the new program's argument list is greater than the system-imposed limit. This limit is at least 5120 bytes on HP-UX systems. .TP [EACCES] Read permission is denied for the executable file or interpreter, and the trace flag (see .IR ptrace (2) request .CR PT_SETTRC ) of the process is set. .TP [EACCES] Search permission is denied for a directory listed in the executable file's or the interpreter's path prefix. .TP [EACCES] The executable file or the interpreter is not an ordinary file. .TP [EACCES] The file described by .IR path or .IR file is not executable. The superuser cannot execute a file unless at least one access permission bit or entry in its access control list has an execute bit set. .TP [EFAULT] .IR path , .IR argv , or .IR envp point to an illegal address. The reliable detection of this error is implementation dependent. .TP [EINVAL] The executable file is incompatible with the architecture on which the .CI exec * () has been performed, and is presumed to be for a different architecture. It is not guaranteed that every architecture's executable files will be recognized. .TP [ELOOP] Too many symbolic links were encountered in translating the path name. .TP [ENAMETOOLONG] The executable file's path name or the interpreter's path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] .IR path is null. .TP [ENOENT] One or more components of the executable file's path name or the interpreter's path name does not exist. .TP [ENOEXEC] The executable file is shorter than indicated by the size values in its header, or is otherwise inconsistent. The reliable detection of this error is implementation dependent. .TP [ENOEXEC] The function call is not .CR execlp() or .CR execvp() , and the executable file has the appropriate access permission, but there is neither a valid magic number nor the characters .CR #!\& as the first two bytes of the file's initial line. .TP [ENOEXEC] The number of bytes in the initial line of a script file exceeds the system's maximum. .TP [ENOMEM] The new process requires more memory than is available or allowed by the system-imposed maximum. .TP [ENOTDIR] A component of the executable file's path prefix or the interpreter's path prefix is not a directory. .TP [ETXTBSY] The executable file is currently open for writing. .RE .SH WARNINGS .PP Unsharable executable files are not supported. These are files whose .CR EXEC_MAGIC magic number was produced with the .CR -N option of .CR ld (see .IR ld (1)). .SH DEPENDENCIES .SS HP Process Resource Manager If the optional HP Process Resource Manager (PRM) software is installed and configured, the process's process resource group ID is not changed by .CI exec * (). See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for the definition of process resource group. .SH SEE ALSO sh(1), sh-bourne(1), alarm(2), exit(2), fork(2), nice(2), ptrace(2), semop(2), signal(2), times(2), ulimit(2), umask(2), a.out(4), acl(5),\" STD only environ(5), signal(5). .PP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR environ ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execle() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execlp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execv() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execve() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execvp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f1execute a file@@@\f3exec(2)\f1 .\" index@\f1file: execute a file@@@\f3exec(2)\f1 .\" index@\f1object-code file, execute@@@\f3exec(2)\f1 .\" index@\f4execl()\f1, \f4execle()\f1, \f4execlp()\f1, \f4execv()\f1, \f4execve()\f1, \f4execvp()\f1 \- execute a file@@@\f3exec(2)\f1 .\" .\" index@\f1PRM@@@\f2see \f1Process Resource Manager .\" index@\f1Process Resource Manager@@@\f3exec(2)\f1 .\" .\" toc@\f3exec(2)\f1:\0\0\f4execl()\f1, \f4execle()\f1, \f4execlp()\f1, \f4execv()\f1, \f4execve()\f1, \f4execvp()\f1@@@execute a file .\" toc@\f4execl()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execle()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execlp()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execv()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execve()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execvp()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" .\" links@exec.2 execl.2 .\" links@exec.2 execle.2 .\" links@exec.2 execlp.2 .\" links@exec.2 execv.2 .\" links@exec.2 execve.2 .\" links@exec.2 execvp.2 .\" $Header: exec.2,v 78.1 95/12/20 10:45:59 ssa Exp $ .TA e .TH exec 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME execl(), execle(), execlp(), execv(), execve(), execvp() \- execute a file .SH SYNOPSIS .nf .C "#include " .PP .C "extern char **environ;" .PP .CR "int execl(const char *path, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0" .CR " */" .CR ");" .PP .CR "int execle(const char *path, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0," .CR " * char * const envp[]" .CR " */" .CR ");" .PP .CR "int execlp(const char *file, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0" .CR " */" .CR ");" .PP .C "int execv(const char *path, char * const argv[]);" .PP .C "int execve(const char *path, char * const argv[], char * const envp[]);" .PP .C "int execvp(const char *file, char * const argv[]);" .fi .SS Remarks The ANSI C "\c .CR ", ...\&\c" " construct denotes a variable length argument list whose optional and required members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION The .CI exec * () system calls, in all their forms, load a program from an ordinary, executable file into the current process, replacing the current program. The .IR path or .IR file argument refers to either an executable object file or a file of data for an interpreter. In the latter case, the file of data is also called a script file. .PP An executable object file consists of a header (see .IR a.out (4)), text segment, and data segment. The data segment contains an initialized portion and an uninitialized portion (bss). For .CR execlp() and .CR execvp() the Bourne shell (see .IR sh-bourne (1)) can be loaded to interpret a script instead. A successful call to .CI exec * () does not return because the new program overwrites the calling program. .PP When a C program is executed, it is called as follows: .PP .RS .nf .C "main (argc, argv, envp)" .C "int argc;" .C "char **argv, **envp;" .fi .RE .PP where .IR argc is the argument count and .IR argv is the address of an array of character pointers to the arguments themselves. As indicated, .IR argc usually has a value of at least one, and the first member of the array points to a string containing the name of the file. Exit conditions from .IR main are discussed in .IR exit (2). .PP .IR path points to a path name that identifies the executable file containing the new program. .PP .IR file (in .CR execlp() or .CR execvp() ) points to a file name identifying the executable file containing the new program. The path prefix for this file is obtained by searching the directories passed in the environment variable .CR PATH (see .IR environ (5)). The environment is supplied by the shell (see .IR sh (1)). If .IR file does not have an executable magic number (see .IR magic (4)), it is passed to the Bourne shell as a shell script. .PP .IR arg0 ", ...," .IR argn are one or more pointers to null-terminated character strings. These strings constitute the argument list available to the new program. By convention, at least .IR arg0 must be present and point to a string identical to .IR path or to .IR path 's last component. .PP .IR argv is an array of character pointers to null-terminated strings. These strings constitute the argument list available to the new program. By convention, .IR argv must have at least one member, and must point to a string that is identical to .IR path or .IR path 's last component. .IR argv is terminated by a null pointer. .PP .IR envp is an array of character pointers to null-terminated strings. These strings constitute the environment in which the new program runs. .IR envp is terminated by a null pointer. For .CR execle() and .CR execve() , the C run-time start-off routine places a pointer to the environment of the calling program in the global cell: .IP .C "extern char **environ;" .PP and it is used to pass the environment of the calling program to the new program. .PP Open file descriptors remain open, except for those whose close-on-exec flag is set (see .IR fcntl (2)). The file offset, access mode, and status flags of open file descriptors are unchanged. .PP Note that normal executable files are open only briefly when they start execution. Other executable file types can be kept open for a long time, or even indefinitely under some circumstances. .PP The processing of signals by the process is unchanged by .CI exec * () \f1, except that signals caught by the process are set to their default values (see .IR signal (2)). .PP If the set-user-ID mode bit of the executable file pointed to by .IR path or .IR file is set (see .IR chmod (2)), .CI exec * () sets the effective user ID of the new process to the user ID of the executable file. Similarly, if the set-group-ID mode bit of the executable file is set, the effective group ID of the process is set to the group ID of the executable file. The real user ID and real group ID of the process are unchanged. Note that the set-user-ID and set-group-ID functions do not apply to scripts; thus, if .CR execlp() or .CR execvp() executes a script, the set-user-ID and set-group-ID bits are ignored, even if they are set. .PP The saved user ID and saved group ID of the process are always set to the effective user ID and effective group ID, respectively, of the process at the end of the .CI exec * () \f1, whether or not set-user-ID or set-group-ID is in effect. .PP The shared memory segments attached to the calling program are not attached to the new program (see .IR shmop (2)). .PP Text and data segment memory locks are not passed on to the new program (see .IR plock (2)). .PP Profiling is disabled for the new process (see .IR profil (2)). .PP The process also retains the following attributes: .RS .TP 3 .PD 0 \(bu current working directory .TP \(bu file creation mode mask (see .IR umask (2)) .TP \(bu file locks (see .IR fcntl (2)), except for files closed-on-execution .TP \(bu file size limit (see .IR ulimit (2)) .TP \(bu interval timers (see .IR getitimer (2)) .TP \(bu nice value (see .IR nice (2)) .TP \(bu nice value (see parent process ID) .TP \(bu pending signals .TP \(bu process ID .TP \(bu process group ID .TP \(bu real user ID .TP \(bu real group ID .TP \(bu process start time .TP \(bu real-time priority (see .IR rtprio (2)) .TP \(bu root directory (see .IR chroot (2)) .TP \(bu .IR semadj values (see .IR semop (2)) .TP \(bu session membership .TP \(bu signal mask (see .IR sigvector (2)) .TP \(bu supplementary group IDs .TP \(bu time left until an alarm clock signal (see .IR alarm (2)) .TP \(bu trace flag (see the .CR PT_SETTRC request of .IR ptrace (2)) .TP \(bu .CR tms_utime , .CR tms_stime , .CR tms_cutime , and .CR tms_cstime (see .IR times (2)) .RE .PD .PP The initial line of a script file must begin with .CR #!\& as the first two bytes, followed by zero or more spaces, followed by .IR interpreter or .IR "interpreter argument" , as in: .IP .CI "#!\& \&" interpreter\0\f1[\f2argument\f1] .PP One or more spaces or tabs must separate .IR interpreter and .IR argument . The first line should end with either a newline or a null character. .PP When the script file is executed, the system executes the specified .IR interpreter as an executable object file. Even in the case of .CR execlp() or .CR execvp() , no path searching is done of the interpreter name. .PP The .IR argument is anything that follows .IR interpreter and tabs or spaces. If an .IR argument is given, it is passed to the .IR interpreter as .CR argv[1] , and the name of the script file is passed as .CR argv[2] . Otherwise, the name of the script file is passed as .CR argv[1] . .CR argv[0] is passed as specified in the .CI exec * () call, unless either .CR argv or .CR argv[0] is null as specified, in which case a pointer to a null string is passed as .CR argv[0] . All other arguments specified in the .CI exec * () call are passed following the name of the script file (that is, beginning at .CR argv[3] if there is an argument; otherwise, at .CR argv[2] ). .PP If the initial line of the script file exceeds a system-defined maximum number of characters, .CI exec * () fails. The minimum value for this limit is 32. .PP The set-user-ID and set-group-ID bits are honored for the script but not for the interpreter. .SH RETURN VALUE If .CI exec * () returns to the calling program, an error has occurred; the return value is .CR -1 and .CR errno is set to indicate the error. .SH ERRORS If .CI exec * () fails and returns to the calling program, .CR errno is set to one of the following values: .RS .TP 20 [E2BIG] The number of bytes in the new program's argument list is greater than the system-imposed limit. This limit is at least 5120 bytes on HP-UX systems. .TP [EACCES] Read permission is denied for the executable file or interpreter, and the trace flag (see .IR ptrace (2) request .CR PT_SETTRC ) of the process is set. .TP [EACCES] Search permission is denied for a directory listed in the executable file's or the interpreter's path prefix. .TP [EACCES] The executable file or the interpreter is not an ordinary file. .TP [EACCES] The file described by .IR path or .IR file is not executable. The superuser cannot execute a file unless at least one access permission bit or entry in its access control list has an execute bit set. .TP [EFAULT] .IR path , .IR argv , or .IR envp point to an illegal address. The reliable detection of this error is implementation dependent. .TP [EINVAL] The executable file is incompatible with the architecture on which the .CI exec * () has been performed, and is presumed to be for a different architecture. It is not guaranteed that every architecture's executable files will be recognized. .TP [ELOOP] Too many symbolic links were encountered in translating the path name. .TP [ENAMETOOLONG] The executable file's path name or the interpreter's path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] .IR path is null. .TP [ENOENT] One or more components of the executable file's path name or the interpreter's path name does not exist. .TP [ENOEXEC] The executable file is shorter than indicated by the size values in its header, or is otherwise inconsistent. The reliable detection of this error is implementation dependent. .TP [ENOEXEC] The function call is not .CR execlp() or .CR execvp() , and the executable file has the appropriate access permission, but there is neither a valid magic number nor the characters .CR #!\& as the first two bytes of the file's initial line. .TP [ENOEXEC] The number of bytes in the initial line of a script file exceeds the system's maximum. .TP [ENOMEM] The new process requires more memory than is available or allowed by the system-imposed maximum. .TP [ENOTDIR] A component of the executable file's path prefix or the interpreter's path prefix is not a directory. .TP [ETXTBSY] The executable file is currently open for writing. .RE .SH WARNINGS .PP Unsharable executable files are not supported. These are files whose .CR EXEC_MAGIC magic number was produced with the .CR -N option of .CR ld (see .IR ld (1)). .SH DEPENDENCIES .SS HP Process Resource Manager If the optional HP Process Resource Manager (PRM) software is installed and configured, the process's process resource group ID is not changed by .CI exec * (). See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for the definition of process resource group. .SH SEE ALSO sh(1), sh-bourne(1), alarm(2), exit(2), fork(2), nice(2), ptrace(2), semop(2), signal(2), times(2), ulimit(2), umask(2), a.out(4), acl(5),\" STD only environ(5), signal(5). .PP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR environ ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execle() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execlp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execv() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execve() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execvp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f1execute a file@@@\f3exec(2)\f1 .\" index@\f1file: execute a file@@@\f3exec(2)\f1 .\" index@\f1object-code file, execute@@@\f3exec(2)\f1 .\" index@\f4execl()\f1, \f4execle()\f1, \f4execlp()\f1, \f4execv()\f1, \f4execve()\f1, \f4execvp()\f1 \- execute a file@@@\f3exec(2)\f1 .\" .\" index@\f1PRM@@@\f2see \f1Process Resource Manager .\" index@\f1Process Resource Manager@@@\f3exec(2)\f1 .\" .\" toc@\f3exec(2)\f1:\0\0\f4execl()\f1, \f4execle()\f1, \f4execlp()\f1, \f4execv()\f1, \f4execve()\f1, \f4execvp()\f1@@@execute a file .\" toc@\f4execl()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execle()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execlp()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execv()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execve()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execvp()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" .\" links@exec.2 execl.2 .\" links@exec.2 execle.2 .\" links@exec.2 execlp.2 .\" links@exec.2 execv.2 .\" links@exec.2 execve.2 .\" links@exec.2 execvp.2 .\" $Header: exec.2,v 78.1 95/12/20 10:45:59 ssa Exp $ .TA e .TH exec 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME execl(), execle(), execlp(), execv(), execve(), execvp() \- execute a file .SH SYNOPSIS .nf .C "#include " .PP .C "extern char **environ;" .PP .CR "int execl(const char *path, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0" .CR " */" .CR ");" .PP .CR "int execle(const char *path, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0," .CR " * char * const envp[]" .CR " */" .CR ");" .PP .CR "int execlp(const char *file, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0" .CR " */" .CR ");" .PP .C "int execv(const char *path, char * const argv[]);" .PP .C "int execve(const char *path, char * const argv[], char * const envp[]);" .PP .C "int execvp(const char *file, char * const argv[]);" .fi .SS Remarks The ANSI C "\c .CR ", ...\&\c" " construct denotes a variable length argument list whose optional and required members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION The .CI exec * () system calls, in all their forms, load a program from an ordinary, executable file into the current process, replacing the current program. The .IR path or .IR file argument refers to either an executable object file or a file of data for an interpreter. In the latter case, the file of data is also called a script file. .PP An executable object file consists of a header (see .IR a.out (4)), text segment, and data segment. The data segment contains an initialized portion and an uninitialized portion (bss). For .CR execlp() and .CR execvp() the Bourne shell (see .IR sh-bourne (1)) can be loaded to interpret a script instead. A successful call to .CI exec * () does not return because the new program overwrites the calling program. .PP When a C program is executed, it is called as follows: .PP .RS .nf .C "main (argc, argv, envp)" .C "int argc;" .C "char **argv, **envp;" .fi .RE .PP where .IR argc is the argument count and .IR argv is the address of an array of character pointers to the arguments themselves. As indicated, .IR argc usually has a value of at least one, and the first member of the array points to a string containing the name of the file. Exit conditions from .IR main are discussed in .IR exit (2). .PP .IR path points to a path name that identifies the executable file containing the new program. .PP .IR file (in .CR execlp() or .CR execvp() ) points to a file name identifying the executable file containing the new program. The path prefix for this file is obtained by searching the directories passed in the environment variable .CR PATH (see .IR environ (5)). The environment is supplied by the shell (see .IR sh (1)). If .IR file does not have an executable magic number (see .IR magic (4)), it is passed to the Bourne shell as a shell script. .PP .IR arg0 ", ...," .IR argn are one or more pointers to null-terminated character strings. These strings constitute the argument list available to the new program. By convention, at least .IR arg0 must be present and point to a string identical to .IR path or to .IR path 's last component. .PP .IR argv is an array of character pointers to null-terminated strings. These strings constitute the argument list available to the new program. By convention, .IR argv must have at least one member, and must point to a string that is identical to .IR path or .IR path 's last component. .IR argv is terminated by a null pointer. .PP .IR envp is an array of character pointers to null-terminated strings. These strings constitute the environment in which the new program runs. .IR envp is terminated by a null pointer. For .CR execle() and .CR execve() , the C run-time start-off routine places a pointer to the environment of the calling program in the global cell: .IP .C "extern char **environ;" .PP and it is used to pass the environment of the calling program to the new program. .PP Open file descriptors remain open, except for those whose close-on-exec flag is set (see .IR fcntl (2)). The file offset, access mode, and status flags of open file descriptors are unchanged. .PP Note that normal executable files are open only briefly when they start execution. Other executable file types can be kept open for a long time, or even indefinitely under some circumstances. .PP The processing of signals by the process is unchanged by .CI exec * () \f1, except that signals caught by the process are set to their default values (see .IR signal (2)). .PP If the set-user-ID mode bit of the executable file pointed to by .IR path or .IR file is set (see .IR chmod (2)), .CI exec * () sets the effective user ID of the new process to the user ID of the executable file. Similarly, if the set-group-ID mode bit of the executable file is set, the effective group ID of the process is set to the group ID of the executable file. The real user ID and real group ID of the process are unchanged. Note that the set-user-ID and set-group-ID functions do not apply to scripts; thus, if .CR execlp() or .CR execvp() executes a script, the set-user-ID and set-group-ID bits are ignored, even if they are set. .PP The saved user ID and saved group ID of the process are always set to the effective user ID and effective group ID, respectively, of the process at the end of the .CI exec * () \f1, whether or not set-user-ID or set-group-ID is in effect. .PP The shared memory segments attached to the calling program are not attached to the new program (see .IR shmop (2)). .PP Text and data segment memory locks are not passed on to the new program (see .IR plock (2)). .PP Profiling is disabled for the new process (see .IR profil (2)). .PP The process also retains the following attributes: .RS .TP 3 .PD 0 \(bu current working directory .TP \(bu file creation mode mask (see .IR umask (2)) .TP \(bu file locks (see .IR fcntl (2)), except for files closed-on-execution .TP \(bu file size limit (see .IR ulimit (2)) .TP \(bu interval timers (see .IR getitimer (2)) .TP \(bu nice value (see .IR nice (2)) .TP \(bu nice value (see parent process ID) .TP \(bu pending signals .TP \(bu process ID .TP \(bu process group ID .TP \(bu real user ID .TP \(bu real group ID .TP \(bu process start time .TP \(bu real-time priority (see .IR rtprio (2)) .TP \(bu root directory (see .IR chroot (2)) .TP \(bu .IR semadj values (see .IR semop (2)) .TP \(bu session membership .TP \(bu signal mask (see .IR sigvector (2)) .TP \(bu supplementary group IDs .TP \(bu time left until an alarm clock signal (see .IR alarm (2)) .TP \(bu trace flag (see the .CR PT_SETTRC request of .IR ptrace (2)) .TP \(bu .CR tms_utime , .CR tms_stime , .CR tms_cutime , and .CR tms_cstime (see .IR times (2)) .RE .PD .PP The initial line of a script file must begin with .CR #!\& as the first two bytes, followed by zero or more spaces, followed by .IR interpreter or .IR "interpreter argument" , as in: .IP .CI "#!\& \&" interpreter\0\f1[\f2argument\f1] .PP One or more spaces or tabs must separate .IR interpreter and .IR argument . The first line should end with either a newline or a null character. .PP When the script file is executed, the system executes the specified .IR interpreter as an executable object file. Even in the case of .CR execlp() or .CR execvp() , no path searching is done of the interpreter name. .PP The .IR argument is anything that follows .IR interpreter and tabs or spaces. If an .IR argument is given, it is passed to the .IR interpreter as .CR argv[1] , and the name of the script file is passed as .CR argv[2] . Otherwise, the name of the script file is passed as .CR argv[1] . .CR argv[0] is passed as specified in the .CI exec * () call, unless either .CR argv or .CR argv[0] is null as specified, in which case a pointer to a null string is passed as .CR argv[0] . All other arguments specified in the .CI exec * () call are passed following the name of the script file (that is, beginning at .CR argv[3] if there is an argument; otherwise, at .CR argv[2] ). .PP If the initial line of the script file exceeds a system-defined maximum number of characters, .CI exec * () fails. The minimum value for this limit is 32. .PP The set-user-ID and set-group-ID bits are honored for the script but not for the interpreter. .SH RETURN VALUE If .CI exec * () returns to the calling program, an error has occurred; the return value is .CR -1 and .CR errno is set to indicate the error. .SH ERRORS If .CI exec * () fails and returns to the calling program, .CR errno is set to one of the following values: .RS .TP 20 [E2BIG] The number of bytes in the new program's argument list is greater than the system-imposed limit. This limit is at least 5120 bytes on HP-UX systems. .TP [EACCES] Read permission is denied for the executable file or interpreter, and the trace flag (see .IR ptrace (2) request .CR PT_SETTRC ) of the process is set. .TP [EACCES] Search permission is denied for a directory listed in the executable file's or the interpreter's path prefix. .TP [EACCES] The executable file or the interpreter is not an ordinary file. .TP [EACCES] The file described by .IR path or .IR file is not executable. The superuser cannot execute a file unless at least one access permission bit or entry in its access control list has an execute bit set. .TP [EFAULT] .IR path , .IR argv , or .IR envp point to an illegal address. The reliable detection of this error is implementation dependent. .TP [EINVAL] The executable file is incompatible with the architecture on which the .CI exec * () has been performed, and is presumed to be for a different architecture. It is not guaranteed that every architecture's executable files will be recognized. .TP [ELOOP] Too many symbolic links were encountered in translating the path name. .TP [ENAMETOOLONG] The executable file's path name or the interpreter's path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] .IR path is null. .TP [ENOENT] One or more components of the executable file's path name or the interpreter's path name does not exist. .TP [ENOEXEC] The executable file is shorter than indicated by the size values in its header, or is otherwise inconsistent. The reliable detection of this error is implementation dependent. .TP [ENOEXEC] The function call is not .CR execlp() or .CR execvp() , and the executable file has the appropriate access permission, but there is neither a valid magic number nor the characters .CR #!\& as the first two bytes of the file's initial line. .TP [ENOEXEC] The number of bytes in the initial line of a script file exceeds the system's maximum. .TP [ENOMEM] The new process requires more memory than is available or allowed by the system-imposed maximum. .TP [ENOTDIR] A component of the executable file's path prefix or the interpreter's path prefix is not a directory. .TP [ETXTBSY] The executable file is currently open for writing. .RE .SH WARNINGS .PP Unsharable executable files are not supported. These are files whose .CR EXEC_MAGIC magic number was produced with the .CR -N option of .CR ld (see .IR ld (1)). .SH DEPENDENCIES .SS HP Process Resource Manager If the optional HP Process Resource Manager (PRM) software is installed and configured, the process's process resource group ID is not changed by .CI exec * (). See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for the definition of process resource group. .SH SEE ALSO sh(1), sh-bourne(1), alarm(2), exit(2), fork(2), nice(2), ptrace(2), semop(2), signal(2), times(2), ulimit(2), umask(2), a.out(4), acl(5),\" STD only environ(5), signal(5). .PP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR environ ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execle() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execlp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execv() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execve() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execvp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f1execute a file@@@\f3exec(2)\f1 .\" index@\f1file: execute a file@@@\f3exec(2)\f1 .\" index@\f1object-code file, execute@@@\f3exec(2)\f1 .\" index@\f4execl()\f1, \f4execle()\f1, \f4execlp()\f1, \f4execv()\f1, \f4execve()\f1, \f4execvp()\f1 \- execute a file@@@\f3exec(2)\f1 .\" .\" index@\f1PRM@@@\f2see \f1Process Resource Manager .\" index@\f1Process Resource Manager@@@\f3exec(2)\f1 .\" .\" toc@\f3exec(2)\f1:\0\0\f4execl()\f1, \f4execle()\f1, \f4execlp()\f1, \f4execv()\f1, \f4execve()\f1, \f4execvp()\f1@@@execute a file .\" toc@\f4execl()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execle()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execlp()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execv()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execve()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execvp()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" .\" links@exec.2 execl.2 .\" links@exec.2 execle.2 .\" links@exec.2 execlp.2 .\" links@exec.2 execv.2 .\" links@exec.2 execve.2 .\" links@exec.2 execvp.2 .\" $Header: exec.2,v 78.1 95/12/20 10:45:59 ssa Exp $ .TA e .TH exec 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME execl(), execle(), execlp(), execv(), execve(), execvp() \- execute a file .SH SYNOPSIS .nf .C "#include " .PP .C "extern char **environ;" .PP .CR "int execl(const char *path, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0" .CR " */" .CR ");" .PP .CR "int execle(const char *path, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0," .CR " * char * const envp[]" .CR " */" .CR ");" .PP .CR "int execlp(const char *file, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0" .CR " */" .CR ");" .PP .C "int execv(const char *path, char * const argv[]);" .PP .C "int execve(const char *path, char * const argv[], char * const envp[]);" .PP .C "int execvp(const char *file, char * const argv[]);" .fi .SS Remarks The ANSI C "\c .CR ", ...\&\c" " construct denotes a variable length argument list whose optional and required members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION The .CI exec * () system calls, in all their forms, load a program from an ordinary, executable file into the current process, replacing the current program. The .IR path or .IR file argument refers to either an executable object file or a file of data for an interpreter. In the latter case, the file of data is also called a script file. .PP An executable object file consists of a header (see .IR a.out (4)), text segment, and data segment. The data segment contains an initialized portion and an uninitialized portion (bss). For .CR execlp() and .CR execvp() the Bourne shell (see .IR sh-bourne (1)) can be loaded to interpret a script instead. A successful call to .CI exec * () does not return because the new program overwrites the calling program. .PP When a C program is executed, it is called as follows: .PP .RS .nf .C "main (argc, argv, envp)" .C "int argc;" .C "char **argv, **envp;" .fi .RE .PP where .IR argc is the argument count and .IR argv is the address of an array of character pointers to the arguments themselves. As indicated, .IR argc usually has a value of at least one, and the first member of the array points to a string containing the name of the file. Exit conditions from .IR main are discussed in .IR exit (2). .PP .IR path points to a path name that identifies the executable file containing the new program. .PP .IR file (in .CR execlp() or .CR execvp() ) points to a file name identifying the executable file containing the new program. The path prefix for this file is obtained by searching the directories passed in the environment variable .CR PATH (see .IR environ (5)). The environment is supplied by the shell (see .IR sh (1)). If .IR file does not have an executable magic number (see .IR magic (4)), it is passed to the Bourne shell as a shell script. .PP .IR arg0 ", ...," .IR argn are one or more pointers to null-terminated character strings. These strings constitute the argument list available to the new program. By convention, at least .IR arg0 must be present and point to a string identical to .IR path or to .IR path 's last component. .PP .IR argv is an array of character pointers to null-terminated strings. These strings constitute the argument list available to the new program. By convention, .IR argv must have at least one member, and must point to a string that is identical to .IR path or .IR path 's last component. .IR argv is terminated by a null pointer. .PP .IR envp is an array of character pointers to null-terminated strings. These strings constitute the environment in which the new program runs. .IR envp is terminated by a null pointer. For .CR execle() and .CR execve() , the C run-time start-off routine places a pointer to the environment of the calling program in the global cell: .IP .C "extern char **environ;" .PP and it is used to pass the environment of the calling program to the new program. .PP Open file descriptors remain open, except for those whose close-on-exec flag is set (see .IR fcntl (2)). The file offset, access mode, and status flags of open file descriptors are unchanged. .PP Note that normal executable files are open only briefly when they start execution. Other executable file types can be kept open for a long time, or even indefinitely under some circumstances. .PP The processing of signals by the process is unchanged by .CI exec * () \f1, except that signals caught by the process are set to their default values (see .IR signal (2)). .PP If the set-user-ID mode bit of the executable file pointed to by .IR path or .IR file is set (see .IR chmod (2)), .CI exec * () sets the effective user ID of the new process to the user ID of the executable file. Similarly, if the set-group-ID mode bit of the executable file is set, the effective group ID of the process is set to the group ID of the executable file. The real user ID and real group ID of the process are unchanged. Note that the set-user-ID and set-group-ID functions do not apply to scripts; thus, if .CR execlp() or .CR execvp() executes a script, the set-user-ID and set-group-ID bits are ignored, even if they are set. .PP The saved user ID and saved group ID of the process are always set to the effective user ID and effective group ID, respectively, of the process at the end of the .CI exec * () \f1, whether or not set-user-ID or set-group-ID is in effect. .PP The shared memory segments attached to the calling program are not attached to the new program (see .IR shmop (2)). .PP Text and data segment memory locks are not passed on to the new program (see .IR plock (2)). .PP Profiling is disabled for the new process (see .IR profil (2)). .PP The process also retains the following attributes: .RS .TP 3 .PD 0 \(bu current working directory .TP \(bu file creation mode mask (see .IR umask (2)) .TP \(bu file locks (see .IR fcntl (2)), except for files closed-on-execution .TP \(bu file size limit (see .IR ulimit (2)) .TP \(bu interval timers (see .IR getitimer (2)) .TP \(bu nice value (see .IR nice (2)) .TP \(bu nice value (see parent process ID) .TP \(bu pending signals .TP \(bu process ID .TP \(bu process group ID .TP \(bu real user ID .TP \(bu real group ID .TP \(bu process start time .TP \(bu real-time priority (see .IR rtprio (2)) .TP \(bu root directory (see .IR chroot (2)) .TP \(bu .IR semadj values (see .IR semop (2)) .TP \(bu session membership .TP \(bu signal mask (see .IR sigvector (2)) .TP \(bu supplementary group IDs .TP \(bu time left until an alarm clock signal (see .IR alarm (2)) .TP \(bu trace flag (see the .CR PT_SETTRC request of .IR ptrace (2)) .TP \(bu .CR tms_utime , .CR tms_stime , .CR tms_cutime , and .CR tms_cstime (see .IR times (2)) .RE .PD .PP The initial line of a script file must begin with .CR #!\& as the first two bytes, followed by zero or more spaces, followed by .IR interpreter or .IR "interpreter argument" , as in: .IP .CI "#!\& \&" interpreter\0\f1[\f2argument\f1] .PP One or more spaces or tabs must separate .IR interpreter and .IR argument . The first line should end with either a newline or a null character. .PP When the script file is executed, the system executes the specified .IR interpreter as an executable object file. Even in the case of .CR execlp() or .CR execvp() , no path searching is done of the interpreter name. .PP The .IR argument is anything that follows .IR interpreter and tabs or spaces. If an .IR argument is given, it is passed to the .IR interpreter as .CR argv[1] , and the name of the script file is passed as .CR argv[2] . Otherwise, the name of the script file is passed as .CR argv[1] . .CR argv[0] is passed as specified in the .CI exec * () call, unless either .CR argv or .CR argv[0] is null as specified, in which case a pointer to a null string is passed as .CR argv[0] . All other arguments specified in the .CI exec * () call are passed following the name of the script file (that is, beginning at .CR argv[3] if there is an argument; otherwise, at .CR argv[2] ). .PP If the initial line of the script file exceeds a system-defined maximum number of characters, .CI exec * () fails. The minimum value for this limit is 32. .PP The set-user-ID and set-group-ID bits are honored for the script but not for the interpreter. .SH RETURN VALUE If .CI exec * () returns to the calling program, an error has occurred; the return value is .CR -1 and .CR errno is set to indicate the error. .SH ERRORS If .CI exec * () fails and returns to the calling program, .CR errno is set to one of the following values: .RS .TP 20 [E2BIG] The number of bytes in the new program's argument list is greater than the system-imposed limit. This limit is at least 5120 bytes on HP-UX systems. .TP [EACCES] Read permission is denied for the executable file or interpreter, and the trace flag (see .IR ptrace (2) request .CR PT_SETTRC ) of the process is set. .TP [EACCES] Search permission is denied for a directory listed in the executable file's or the interpreter's path prefix. .TP [EACCES] The executable file or the interpreter is not an ordinary file. .TP [EACCES] The file described by .IR path or .IR file is not executable. The superuser cannot execute a file unless at least one access permission bit or entry in its access control list has an execute bit set. .TP [EFAULT] .IR path , .IR argv , or .IR envp point to an illegal address. The reliable detection of this error is implementation dependent. .TP [EINVAL] The executable file is incompatible with the architecture on which the .CI exec * () has been performed, and is presumed to be for a different architecture. It is not guaranteed that every architecture's executable files will be recognized. .TP [ELOOP] Too many symbolic links were encountered in translating the path name. .TP [ENAMETOOLONG] The executable file's path name or the interpreter's path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] .IR path is null. .TP [ENOENT] One or more components of the executable file's path name or the interpreter's path name does not exist. .TP [ENOEXEC] The executable file is shorter than indicated by the size values in its header, or is otherwise inconsistent. The reliable detection of this error is implementation dependent. .TP [ENOEXEC] The function call is not .CR execlp() or .CR execvp() , and the executable file has the appropriate access permission, but there is neither a valid magic number nor the characters .CR #!\& as the first two bytes of the file's initial line. .TP [ENOEXEC] The number of bytes in the initial line of a script file exceeds the system's maximum. .TP [ENOMEM] The new process requires more memory than is available or allowed by the system-imposed maximum. .TP [ENOTDIR] A component of the executable file's path prefix or the interpreter's path prefix is not a directory. .TP [ETXTBSY] The executable file is currently open for writing. .RE .SH WARNINGS .PP Unsharable executable files are not supported. These are files whose .CR EXEC_MAGIC magic number was produced with the .CR -N option of .CR ld (see .IR ld (1)). .SH DEPENDENCIES .SS HP Process Resource Manager If the optional HP Process Resource Manager (PRM) software is installed and configured, the process's process resource group ID is not changed by .CI exec * (). See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for the definition of process resource group. .SH SEE ALSO sh(1), sh-bourne(1), alarm(2), exit(2), fork(2), nice(2), ptrace(2), semop(2), signal(2), times(2), ulimit(2), umask(2), a.out(4), acl(5),\" STD only environ(5), signal(5). .PP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR environ ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execle() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execlp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execv() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execve() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execvp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f1execute a file@@@\f3exec(2)\f1 .\" index@\f1file: execute a file@@@\f3exec(2)\f1 .\" index@\f1object-code file, execute@@@\f3exec(2)\f1 .\" index@\f4execl()\f1, \f4execle()\f1, \f4execlp()\f1, \f4execv()\f1, \f4execve()\f1, \f4execvp()\f1 \- execute a file@@@\f3exec(2)\f1 .\" .\" index@\f1PRM@@@\f2see \f1Process Resource Manager .\" index@\f1Process Resource Manager@@@\f3exec(2)\f1 .\" .\" toc@\f3exec(2)\f1:\0\0\f4execl()\f1, \f4execle()\f1, \f4execlp()\f1, \f4execv()\f1, \f4execve()\f1, \f4execvp()\f1@@@execute a file .\" toc@\f4execl()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execle()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execlp()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execv()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execve()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execvp()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" .\" links@exec.2 execl.2 .\" links@exec.2 execle.2 .\" links@exec.2 execlp.2 .\" links@exec.2 execv.2 .\" links@exec.2 execve.2 .\" links@exec.2 execvp.2 .\" $Header: exec.2,v 78.1 95/12/20 10:45:59 ssa Exp $ .TA e .TH exec 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME execl(), execle(), execlp(), execv(), execve(), execvp() \- execute a file .SH SYNOPSIS .nf .C "#include " .PP .C "extern char **environ;" .PP .CR "int execl(const char *path, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0" .CR " */" .CR ");" .PP .CR "int execle(const char *path, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0," .CR " * char * const envp[]" .CR " */" .CR ");" .PP .CR "int execlp(const char *file, .CR " const char *arg0, ..." .CR " /*" .CR " * " [ "const char *arg1," " ..." ", const char *argn," ] .CR " * (char *)0" .CR " */" .CR ");" .PP .C "int execv(const char *path, char * const argv[]);" .PP .C "int execve(const char *path, char * const argv[], char * const envp[]);" .PP .C "int execvp(const char *file, char * const argv[]);" .fi .SS Remarks The ANSI C "\c .CR ", ...\&\c" " construct denotes a variable length argument list whose optional and required members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION The .CI exec * () system calls, in all their forms, load a program from an ordinary, executable file into the current process, replacing the current program. The .IR path or .IR file argument refers to either an executable object file or a file of data for an interpreter. In the latter case, the file of data is also called a script file. .PP An executable object file consists of a header (see .IR a.out (4)), text segment, and data segment. The data segment contains an initialized portion and an uninitialized portion (bss). For .CR execlp() and .CR execvp() the Bourne shell (see .IR sh-bourne (1)) can be loaded to interpret a script instead. A successful call to .CI exec * () does not return because the new program overwrites the calling program. .PP When a C program is executed, it is called as follows: .PP .RS .nf .C "main (argc, argv, envp)" .C "int argc;" .C "char **argv, **envp;" .fi .RE .PP where .IR argc is the argument count and .IR argv is the address of an array of character pointers to the arguments themselves. As indicated, .IR argc usually has a value of at least one, and the first member of the array points to a string containing the name of the file. Exit conditions from .IR main are discussed in .IR exit (2). .PP .IR path points to a path name that identifies the executable file containing the new program. .PP .IR file (in .CR execlp() or .CR execvp() ) points to a file name identifying the executable file containing the new program. The path prefix for this file is obtained by searching the directories passed in the environment variable .CR PATH (see .IR environ (5)). The environment is supplied by the shell (see .IR sh (1)). If .IR file does not have an executable magic number (see .IR magic (4)), it is passed to the Bourne shell as a shell script. .PP .IR arg0 ", ...," .IR argn are one or more pointers to null-terminated character strings. These strings constitute the argument list available to the new program. By convention, at least .IR arg0 must be present and point to a string identical to .IR path or to .IR path 's last component. .PP .IR argv is an array of character pointers to null-terminated strings. These strings constitute the argument list available to the new program. By convention, .IR argv must have at least one member, and must point to a string that is identical to .IR path or .IR path 's last component. .IR argv is terminated by a null pointer. .PP .IR envp is an array of character pointers to null-terminated strings. These strings constitute the environment in which the new program runs. .IR envp is terminated by a null pointer. For .CR execle() and .CR execve() , the C run-time start-off routine places a pointer to the environment of the calling program in the global cell: .IP .C "extern char **environ;" .PP and it is used to pass the environment of the calling program to the new program. .PP Open file descriptors remain open, except for those whose close-on-exec flag is set (see .IR fcntl (2)). The file offset, access mode, and status flags of open file descriptors are unchanged. .PP Note that normal executable files are open only briefly when they start execution. Other executable file types can be kept open for a long time, or even indefinitely under some circumstances. .PP The processing of signals by the process is unchanged by .CI exec * () \f1, except that signals caught by the process are set to their default values (see .IR signal (2)). .PP If the set-user-ID mode bit of the executable file pointed to by .IR path or .IR file is set (see .IR chmod (2)), .CI exec * () sets the effective user ID of the new process to the user ID of the executable file. Similarly, if the set-group-ID mode bit of the executable file is set, the effective group ID of the process is set to the group ID of the executable file. The real user ID and real group ID of the process are unchanged. Note that the set-user-ID and set-group-ID functions do not apply to scripts; thus, if .CR execlp() or .CR execvp() executes a script, the set-user-ID and set-group-ID bits are ignored, even if they are set. .PP The saved user ID and saved group ID of the process are always set to the effective user ID and effective group ID, respectively, of the process at the end of the .CI exec * () \f1, whether or not set-user-ID or set-group-ID is in effect. .PP The shared memory segments attached to the calling program are not attached to the new program (see .IR shmop (2)). .PP Text and data segment memory locks are not passed on to the new program (see .IR plock (2)). .PP Profiling is disabled for the new process (see .IR profil (2)). .PP The process also retains the following attributes: .RS .TP 3 .PD 0 \(bu current working directory .TP \(bu file creation mode mask (see .IR umask (2)) .TP \(bu file locks (see .IR fcntl (2)), except for files closed-on-execution .TP \(bu file size limit (see .IR ulimit (2)) .TP \(bu interval timers (see .IR getitimer (2)) .TP \(bu nice value (see .IR nice (2)) .TP \(bu nice value (see parent process ID) .TP \(bu pending signals .TP \(bu process ID .TP \(bu process group ID .TP \(bu real user ID .TP \(bu real group ID .TP \(bu process start time .TP \(bu real-time priority (see .IR rtprio (2)) .TP \(bu root directory (see .IR chroot (2)) .TP \(bu .IR semadj values (see .IR semop (2)) .TP \(bu session membership .TP \(bu signal mask (see .IR sigvector (2)) .TP \(bu supplementary group IDs .TP \(bu time left until an alarm clock signal (see .IR alarm (2)) .TP \(bu trace flag (see the .CR PT_SETTRC request of .IR ptrace (2)) .TP \(bu .CR tms_utime , .CR tms_stime , .CR tms_cutime , and .CR tms_cstime (see .IR times (2)) .RE .PD .PP The initial line of a script file must begin with .CR #!\& as the first two bytes, followed by zero or more spaces, followed by .IR interpreter or .IR "interpreter argument" , as in: .IP .CI "#!\& \&" interpreter\0\f1[\f2argument\f1] .PP One or more spaces or tabs must separate .IR interpreter and .IR argument . The first line should end with either a newline or a null character. .PP When the script file is executed, the system executes the specified .IR interpreter as an executable object file. Even in the case of .CR execlp() or .CR execvp() , no path searching is done of the interpreter name. .PP The .IR argument is anything that follows .IR interpreter and tabs or spaces. If an .IR argument is given, it is passed to the .IR interpreter as .CR argv[1] , and the name of the script file is passed as .CR argv[2] . Otherwise, the name of the script file is passed as .CR argv[1] . .CR argv[0] is passed as specified in the .CI exec * () call, unless either .CR argv or .CR argv[0] is null as specified, in which case a pointer to a null string is passed as .CR argv[0] . All other arguments specified in the .CI exec * () call are passed following the name of the script file (that is, beginning at .CR argv[3] if there is an argument; otherwise, at .CR argv[2] ). .PP If the initial line of the script file exceeds a system-defined maximum number of characters, .CI exec * () fails. The minimum value for this limit is 32. .PP The set-user-ID and set-group-ID bits are honored for the script but not for the interpreter. .SH RETURN VALUE If .CI exec * () returns to the calling program, an error has occurred; the return value is .CR -1 and .CR errno is set to indicate the error. .SH ERRORS If .CI exec * () fails and returns to the calling program, .CR errno is set to one of the following values: .RS .TP 20 [E2BIG] The number of bytes in the new program's argument list is greater than the system-imposed limit. This limit is at least 5120 bytes on HP-UX systems. .TP [EACCES] Read permission is denied for the executable file or interpreter, and the trace flag (see .IR ptrace (2) request .CR PT_SETTRC ) of the process is set. .TP [EACCES] Search permission is denied for a directory listed in the executable file's or the interpreter's path prefix. .TP [EACCES] The executable file or the interpreter is not an ordinary file. .TP [EACCES] The file described by .IR path or .IR file is not executable. The superuser cannot execute a file unless at least one access permission bit or entry in its access control list has an execute bit set. .TP [EFAULT] .IR path , .IR argv , or .IR envp point to an illegal address. The reliable detection of this error is implementation dependent. .TP [EINVAL] The executable file is incompatible with the architecture on which the .CI exec * () has been performed, and is presumed to be for a different architecture. It is not guaranteed that every architecture's executable files will be recognized. .TP [ELOOP] Too many symbolic links were encountered in translating the path name. .TP [ENAMETOOLONG] The executable file's path name or the interpreter's path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] .IR path is null. .TP [ENOENT] One or more components of the executable file's path name or the interpreter's path name does not exist. .TP [ENOEXEC] The executable file is shorter than indicated by the size values in its header, or is otherwise inconsistent. The reliable detection of this error is implementation dependent. .TP [ENOEXEC] The function call is not .CR execlp() or .CR execvp() , and the executable file has the appropriate access permission, but there is neither a valid magic number nor the characters .CR #!\& as the first two bytes of the file's initial line. .TP [ENOEXEC] The number of bytes in the initial line of a script file exceeds the system's maximum. .TP [ENOMEM] The new process requires more memory than is available or allowed by the system-imposed maximum. .TP [ENOTDIR] A component of the executable file's path prefix or the interpreter's path prefix is not a directory. .TP [ETXTBSY] The executable file is currently open for writing. .RE .SH WARNINGS .PP Unsharable executable files are not supported. These are files whose .CR EXEC_MAGIC magic number was produced with the .CR -N option of .CR ld (see .IR ld (1)). .SH DEPENDENCIES .SS HP Process Resource Manager If the optional HP Process Resource Manager (PRM) software is installed and configured, the process's process resource group ID is not changed by .CI exec * (). See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for the definition of process resource group. .SH SEE ALSO sh(1), sh-bourne(1), alarm(2), exit(2), fork(2), nice(2), ptrace(2), semop(2), signal(2), times(2), ulimit(2), umask(2), a.out(4), acl(5),\" STD only environ(5), signal(5). .PP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR environ ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execle() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execlp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execv() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execve() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR execvp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f1execute a file@@@\f3exec(2)\f1 .\" index@\f1file: execute a file@@@\f3exec(2)\f1 .\" index@\f1object-code file, execute@@@\f3exec(2)\f1 .\" index@\f4execl()\f1, \f4execle()\f1, \f4execlp()\f1, \f4execv()\f1, \f4execve()\f1, \f4execvp()\f1 \- execute a file@@@\f3exec(2)\f1 .\" .\" index@\f1PRM@@@\f2see \f1Process Resource Manager .\" index@\f1Process Resource Manager@@@\f3exec(2)\f1 .\" .\" toc@\f3exec(2)\f1:\0\0\f4execl()\f1, \f4execle()\f1, \f4execlp()\f1, \f4execv()\f1, \f4execve()\f1, \f4execvp()\f1@@@execute a file .\" toc@\f4execl()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execle()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execlp()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execv()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execve()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" toc@\f4execvp()\f1:\0\0execute a file@@@see \f3exec(2)\f1 .\" .\" links@exec.2 execl.2 .\" links@exec.2 execle.2 .\" links@exec.2 execlp.2 .\" links@exec.2 execv.2 .\" links@exec.2 execve.2 .\" links@exec.2 execvp.2 .\" $Header: exit.2,v 72.4 94/11/14 15:23:53 ssa Exp $ .TA e .TH exit 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME exit, _exit \- terminate process .SH SYNOPSIS .C "#include " .PP .C "void exit(int status);" .PP .C "#include " .PP .C "void _exit(int status);" .SH DESCRIPTION .C exit() terminates the calling process and passes .I status to the system for inspection, see .IR wait (2). Returning from .I main in a C program has the same effect as .CR exit() ; the .I status value is the function value returned by .IR main (this value is undefined if .I main does not take care to return a value or to call .C exit() explicitly). .PP .C exit() cannot return to its caller. The result of an .C exit() call during exit processing is undefined. .PP The functions .C exit() and .CR _exit() , are equivalent, except that .C exit() calls functions registered by .C atexit() and flushes standard .SM I/O buffers, while .C _exit() does not. Both .C exit() and .C _exit() terminate the calling process with the following consequences: .IP Functions registered by .C atexit() (see .IR atexit (2)) are called in reverse order of registration. .IP All file descriptors open in the calling process are closed. .IP All files created by .C tmpfile() are removed (see .IR tmpfile (3S)). .IP If the parent process of the calling process is executing a .CR wait() , .CR wait3() , or .CR waitpid() , it is notified of the calling process's termination, and the low-order eight bits; i.e., bits 0377 of .I status are made available to it (see .IR wait (2)). .IP If the parent process of the calling process is not executing a .CR wait() , .CR wait3() , or .CR waitpid() , and does not have .C SIGCLD set to .CR SIG_IGN , the calling process is transformed into a .BR "zombie process" . A .B zombie process is a process that only occupies a slot in the process table. It has no other space allocated either in user or kernel space. Time accounting information is recorded for use by .C times() (see .IR times (2)). .IP The parent process .SM ID is set to 1 for all of the calling process's existing child processes and zombie processes. This means the initialization process (proc1) inherits each of these processes. .IP Each attached shared memory segment is detached and the value of .C shm_nattach in the data structure associated with its shared memory identifier is decremented by 1 (see .IR shmop (2)). .IP For each semaphore for which the calling process has set a semadj value (see .IR semop (2)), that semadj value is added to the semval of the specified semaphore. .IP If the process has a process, text, or data lock, an .C unlock() is performed, see .IR plock (2). .IP An accounting record is written on the accounting file if the system's accounting routine is enabled (see .IR acct (2)). .IP A .C SIGCHLD signal is sent to the parent process. .IP If the calling process is a controlling process, the .C SIGHUP signal is sent to each process in the foreground process group of the controlling terminal belonging to the calling process. The controlling terminal associated with the session is disassociated from the session, allowing it to be acquired by a new controlling process. .IP If the exit of the calling process causes a process group to become orphaned, and if any member of the newly-orphaned process group is stopped, all processes in the newly-orphaned process group are sent .C SIGHUP and .C SIGCONT signals. .IP If the current process has any child processes that are being traced, they are sent a .C SIGKILL signal. .SH AUTHOR .C exit() was developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO Exit conditions .RB ( $? ) in sh(1), .br acct(2), plock(2), semop(2), shmop(2), times(2), vfork(2), wait(2), signal(5). .SH STANDARDS CONFORMANCE .CR exit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR _exit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4exit()\fP, \f4_exit()\fP \(mi terminate process@@@\f3exit(2)\f1 .\" index@process, terminate@@@\f3exit(2)\f1 .\" .\" toc@\f3exit(2)\f1:\0\0\f4exit()\fP, \f4_exit()\fP@@@terminate process .\" .\" links@exit.2 _exit.2 .\" .\" fileset_database@exit.2 PROGRAMING-MAN .\" $Header: chdir.2,v 72.4 94/11/14 13:06:02 ssa Exp $ .TA c .TH chdir 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chdir, fchdir \- change working directory .SH SYNOPSIS .C "#include " .PP .C "int chdir(const char *path);" .PP .C "int fchdir(int fildes);" .SH DESCRIPTION .C chdir() and .C fchdir() cause a directory pointed to by .I path or .I fildes to become the current working directory, the starting point for path searches of path names not beginning with .CR / . .I path points to the path name of a directory. .I fildes is an open file descriptor of a directory. .PP For a directory to become the current working directory, a process must have execute (search) access to the directory. .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .C chdir() fails and the current working directory remains unchanged if one or more of the following are true: .TP 25 .SM [ENOTDIR] A component of the path name is not a directory. .TP .SM [ENOENT] The named directory does not exist. .TP .SM [EACCES] Search permission is denied for any component of the path name. .TP .SM [EFAULT] .I path points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP .SM [ENOENT] .I path is null. .TP .SM [ENAMETOOLONG] The length of the specified path name exceeds .C PATH_MAX bytes, or the length of a component of the path name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the path name. .PP .C fchdir() fails and the current working directory remains unchanged if one or more of the following are true: .TP 25 .SM [EACCES] Search permission is denied for .IR fildes . .TP .SM [EBADF] .I fildes is not an open file descriptor. .TP .SM [ENOTDIR] The open file descriptor .I fildes does not refer to a directory. .SH AUTHOR .C chdir() and .C fchdir() were developed by AT&T Bell Laboratories and HP. .SH SEE ALSO cd(1), chroot(2). .SH STANDARDS CONFORMANCE .CR chdir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4chdir()\fP \(mi change working directory@@@\f3chdir(2)\f1 .\" index@\f4fchdir()\fP \(mi change working directory@@@\f3chdir(2)\f1 .\" index@directory: change working directory@@@\f3chdir(2)\f1 .\" index@change working directory@@@\f3chdir(2)\f1 .\" index@working directory, change@@@\f3chdir(2)\f1 .\" .\" toc@\f3chdir(2)\f1:\0\0\f4chdir()\fP@@@change working directory .\" toc@\f2fchdir(2)\f1:\0\0change working directory@@@see \f3chdir(2)\f1 .\" .\" links@chdir.2 fchdir.2 .\" .\" fileset_database@chdir.2 PROGRAMING-MAN .\" $Header: chmod.2,v 72.5 94/11/14 13:06:28 ssa Exp $ .TA c .TH chmod 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chmod(), fchmod() \- change file mode access permissions .SH SYNOPSIS .CR "#include " .PP .CR "int chmod(const char *path, mode_t mode);" .PP .CR "int fchmod(int fildes, mode_t mode);" .SH DESCRIPTION The .CR chmod() and .CR fchmod() system calls set the access permission portion of the file's mode according to the bit pattern contained in .IR mode . .IR path points to a path name naming a file. .IR fildes is a file descriptor. .PP The following symbolic constants representing the access permission bits are defined with the indicated values in .CR and are used to construct the .IR mode argument. The value of .IR mode is the bit-wise inclusive OR of the values for the desired permissions. .nf .IP .CR "S_ISUID 04000 " "Set user ID on execution." .CR "S_ISGID 02000 " "Set group ID on execution." .CR "S_ENFMT 02000 " "Record locking enforced." .CR "S_ISVTX 01000 " "Save text image after execution." .CR "S_IRUSR 00400 " "Read by owner." .CR "S_IWUSR 00200 " "Write by owner." .CR "S_IXUSR 00100 " "Execute (search) by owner." .CR "S_IRGRP 00040 " "Read by group." .CR "S_IWGRP 00020 " "Write by group." .CR "S_IXGRP 00010 " "Execute (search) by group." .CR "S_IROTH 00004 " "Read by others (that is, anybody else)." .CR "S_IWOTH 00002 " "Write by others." .CR "S_IXOTH 00001 " "Execute (search) by others." .fi .PP To change the mode of a file, the effective user ID of the process must match that of the owner of the file or a user with appropriate privileges. .PP If the effective user ID of the process is not that of a user with appropriate privileges, mode bit .CR S_ISVTX is cleared. .PP If the effective user ID of the process is not that of a user with appropriate privileges, and the effective group ID of the process does not match the group ID of the file and none of the group IDs in the supplementary groups list match the group ID of the file, mode bit .CR S_ISGID is cleared. .PP The mode bit .CR S_ENFMT (same as .CR S_ISGID ) is used to enforce file-locking mode (see .IR lockf (2) and .IR fcntl (2)) on files that are not group executable. This might affect future calls to .CR open() , .CR creat() , .CR read() , and .CR write() on such files (see .IR open (2), .IR creat (2), .IR read (2), and .IR write (2)). .PP If an executable file is prepared for sharing, mode bit .CR S_ISVTX prevents the system from abandoning the swap-space image of the program-text portion of the file when its last user terminates. Then, when the next user of the file executes it, the text need not be read from the file system but can simply be swapped in, thus saving time. .PP If the path given to .CR chmod() contains a symbolic link as the last element, this link is traversed and path name resolution continues. .CR chmod() changes the access mode of the symbolic link's target, rather than the access mode of the link. .SS "Access Control Lists - HFS File Systems Only" All optional entries in a file's access control list are deleted when .CR chmod() is executed. (This behavior conforms to the IEEE Standard POSIX 1003.1-1988.) To preserve optional entries in a file's access control list, it is necessary to save and restore them using .CR getacl() and .CR setacl() (see .IR getacl (2) and .IR setacl (2)). .PP To set the permission bits of access control list entries, use .CR setacl() instead of .CR chmod() . .PP For more information on access control list entries, see .IR acl (5). .SH RETURN VALUE .CR chmod() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR chmod() or .CR fchmod() fails, the file mode is unchanged. .CR errno is set to one of the following values. .RS .TP 20 [EACCES] Search permission is denied on a component of the path prefix. .TP [EBADF] .I fildes is not a valid file descriptor. .TP [EFAULT] .I path points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP [EINVAL] .I path or .I fildes descriptor does not refer to an appropriate file. It may be a special file, such as a pipe or socket. .TP [ELOOP] Too many symbolic links were encountered in translating .CR path . .TP [ENAMETOOLONG] A component of .I path exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect or .I path exceeds .CR PATH_MAX bytes. .TP [ENOENT] A component of .I path or the file named by .I path does not exist. .TP [ENOTDIR] A component of the path prefix is not a directory. .TP [EPERM] The effective user ID does not match that of the owner of the file, and the effective user ID is not that of a user with appropriate privileges. .TP [EROFS] The named file resides on a read-only file system. .SH AUTHOR .CR chmod() was developed by AT&T, the University of California, Berkeley, and HP. .PP .CR fchmod() was developed by the University of California, Berkeley. .SH SEE ALSO chmod(1), chown(2), creat(2), fcntl(2), getacl(2), read(2), lockf(2), mknod(2), open(2), setacl(2), write(2), acl(5). .SH STANDARDS CONFORMANCE .CR chmod() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR fchmod() ": AES, SVID3" .\" .\" index@\f4chmod()\f1 \- change file mode access permissions@@@\f3chmod(2)\f1 .\" index@\f4fchmod()\f1 \- change file mode access permissions@@@\f3chmod(2)\f1 .\" index@access permissions, change file mode@@@\f3chmod(2)\f1 .\" index@change file mode access permissions@@@\f3chmod(2)\f1 .\" index@context-dependent file@@@\f3chmod(2)\f1 .\" index@file mode, change access permissions@@@\f3chmod(2)\f1 .\" index@file, change file mode access permissions@@@\f3chmod(2)\f1 .\" index@file, context-dependent@@@\f3chmod(2)\f1 .\" index@file, hidden@@@\f3chmod(2)\f1 .\" index@hidden file@@@\f3chmod(2)\f1 .\" index@mode, change file access permissions@@@\f3chmod(2)\f1 .\" index@permissions, change file mode access@@@\f3chmod(2)\f1 .\" .\" links@chmod.2 fchmod.2 .\" .\" toc@\f3chmod(2)\f1:\0\0\f4chmod()\f1, \f4fchmod()\f1@@@change file mode access permissions .\" toc@\f4fchmod()\f1:\0\0change file mode access permissions@@@see \f3chmod(2)\f1 .\" $Header: chown.2,v 78.1 96/01/19 20:09:55 ssa Exp $ .TA c .TH chown 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chown(), fchown(), lchown() \- change owner and group of a file .SH SYNOPSIS .C "#include " .PP .C "int chown(const char *path, uid_t owner, gid_t group);" .PP .C "int lchown(const char *path, uid_t owner, gid_t group);" .PP .C "int fchown(int fildes, uid_t owner, gid_t group);" .SH DESCRIPTION The .CR chown() system call changes the user and group ownership of a file. .IR path points to the path name of a file. .CR chown() sets the owner ID and group ID of the file to the numeric values contained in .IR owner and .IR group respectively. A value of .CR UID_NO_CHANGE or .CR GID_NO_CHANGE can be specified in .IR owner or .IR group to leave unchanged the file's owner ID or group ID, respectively. Note that .IR owner and .IR group should be less than .CR UID_MAX (see .IR limits (5)). .PP Only processes with an effective user ID equal to the file owner or a user having appropriate privileges can change the ownership of a file. If privilege groups are supported, the owner of a file can change the ownership only as a member of a privilege group allowing CHOWN, as set up by the .CR setprivgrp command (see .IR setprivgrp (1M)). All users get the CHOWN privilege by default. .PP The group ownership of a file can be changed to any group in the current process's access list or to the real or effective group ID of the current process. If privilege groups are supported and the user has the CHOWN privilege, the file can be given to any group. .PP If .CR chown() is invoked on a regular file by anyone other than the superuser, the set-user-ID and set-group-ID bits of the file mode are cleared. Whether .CR chown() preserves or clears these bits on files of other types is implementation dependent. .PP If the path given to .CR chown() contains a symbolic link as the last element, this link is traversed and path name resolution continues. .CR chown() changes the owner and group of the symbolic link's target, rather than the owner and group of the link. .PP The .CR fchown() system call functions exactly like .CR chown() , exept that it operates on a file descriptor instead of a path name. .IR fildes is a file descriptor. .PP The .CR lchown() system call sets the owner ID and group ID of the named file just as .CR chown() does, except in the case where the named file is a symbolic link. In this case, .CR lchown() changes the owner and group of the symbolic link file itself. .SS "Access Control Lists - HFS File Systems Only A user can allow or deny specific individuals and groups access to a file by using the file's access control list (see .IR acl (5)). When using .CR chown () in conjunction with ACLs, if the new owner and/or group does not have an optional ACL entry corresponding to .IC user .% and/or .CI %. group in the file's access control list, the file's access permission bits remain unchanged. However, if the new owner and/or group is already designated by an optional ACL entry of .IC user .% and/or .CI %. group\f1, .CR chown() sets the file's permission bits (and the three basic ACL entries) to the permissions contained in that entry. .SH RETURN VALUE .CR chown() and .CR fchown() return the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. The owner and group of the file remain unchanged. .CR errno is set to indicate the error. .PD .SH ERRORS If .CR chown() or .CR fchown() fails, .CR errno is set to one of the following values: .TP 15 [EACCES] Search permission is denied on a component of the path prefix. .TP [EBADF] .IR fildes is not a valid file descriptor. .TP [EFAULT] .IR path points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP [EINVAL] Either .IR owner or .IR group is greater than or equal to .CR UID_MAX , or is an illegal negative value. .TP [ELOOP] Too many symbolic links were encountered in translating .IR path . .TP [ENAMETOOLONG] A component of .IR path exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect, or .IR path exceeds .CR PATH_MAX bytes. .TP [ENOENT] The file named by .IR path does not exist. .TP [ENOTDIR] A component of the path prefix is not a directory. .TP [EPERM] The effective user ID is not a user having appropriate privileges and one or more of the following conditions exist: .RS .TP 3 \(bu The effective user ID does not match the owner of the file. .TP \(bu When changing the owner of the file, the owner of the file is not a member of a privilege group allowing the CHOWN privilege. .TP \(bu When changing the group of the file, the owner of the file is not a member of a privilege group allowing the CHOWN privilege and the group number is not in the current process's access list. .RE .TP [EROFS] The named file resides on a read-only file system. .SH AUTHOR .CR chown() was developed by AT&T. .PP .CR fchown() was developed by the University of California, Berkeley. .SH SEE ALSO chown(1), setprivgrp(1M), chmod(2), setacl(2), acl(5), limits(5). .SH STANDARDS CONFORMANCE .CR chown() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR fchown() ": AES, SVID3" .\" .\" index@\f4chown()\f1 \- change owner and group of a file@@@\f3chown(2)\f1 .\" index@\f4fchown()\f1 \- change owner and group of a file@@@\f3chown(2)\f1 .\" index@\f1file: change owner and group@@@\f3chown(2)\f1 .\" index@\f1change owner and group of a file@@@\f3chown(2)\f1 .\" index@\f1owner and group of a file, change@@@\f3chown(2)\f1 .\" index@\f1group and owner of a file, change@@@\f3chown(2)\f1 .\" .\" toc@\f3chown(2)\f1:\0\0\f4chown()\f1, \f4fchown()\f1@@@change owner and group of a file .\" toc@\f4fchown()\f1:\0\0change owner and group of a file@@@see \f3chown(2)\f1 .\" .\" links@chown.2 fchown.2 .\" links@chown.2 lchown.2 .\" $Header: fcntl.2,v 78.2 96/02/12 13:43:52 ssa Exp $ .TA f .TH fcntl 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fcntl \- file control .SH SYNOPSIS .C "#include " .PP .C "int fcntl(int fildes, int cmd, ... /* arg */);" .SS Remarks The ANSI C "\c .CR ", ...\$\c" " construct denotes a variable length argument list whose optional [or required] \" EDITOR: make this line fit the specific page members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION .CR fcntl() provides for control over open files. .I fildes is an open file descriptor. .PP The following are possible values for the .I cmd argument: .RS .TP 15 .C F_DUPFD Return a new file descriptor having the following characteristics: .RS .RS .TP 3 \(bu Lowest numbered available file descriptor greater than or equal to .IB arg. val . .TP \(bu Same open file (or pipe) as the original file. .TP \(bu Same file pointer as the original file (that is, both file descriptors share one file pointer). .TP \(bu Same access mode (read, write or read/write). .TP \(bu Same file status flags (that is, both file descriptors share the same file status flags). .TP \(bu The close-on-exec flag associated with the new file descriptor is set to remain open across .IR exec (2) system calls. .RE .RE .TP .C F_GETFD Get the close-on-exec flag associated with the file descriptor .IR fildes . If the low-order bit is .C 0 the file will remain open across .IR exec (2), otherwise the file will be closed upon execution of .IR exec (2). .TP .C F_SETFD Set the close-on-exec flag associated with .I fildes to the low-order bit of .IB arg. val (see .CR F_GETFD ). .TP .C F_GETFL Get file status flags and access modes; see .IR fcntl (5). .TP .C F_SETFL Set file status flags to .IC arg . val. Only certain flags can be set; see .IR fcntl (5). It is not possible to set both .CR O_NDELAY and .CR O_NONBLOCK . .TP .C F_GETLK Get the first lock that blocks the lock described by the variable of type .C struct flock pointed to by .IR arg . The information retrieved overwrites the information passed to .C fcntl() in the .C flock structure. If no lock is found that would prevent this lock from being created, the structure is passed back unchanged, except that the lock type is set to .CR F_UNLCK . .TP .C F_SETLK Set or clear a file segment lock according to the variable of type .C struct flock pointed to by .IC arg . lockdes (see .IR fcntl (5)). The .I cmd .C F_SETLK is used to establish read .RC (\| F_RDLCK \|) and write .RC (\| F_WRLCK \|) locks, as well as to remove either type of lock .RC (\| F_UNLCK \|). If a read or write lock cannot be set, .C fcntl() returns immediately with an error value of .CR \(mi1 . .TP .C F_SETLKW This .I cmd is the same as .CR F_SETLK except that if a read or write lock is blocked by other locks, the process will sleep until the segment is free to be locked. .TP .C F_GETOWN If .I fildes refers to a socket, .C fcntl() returns the process or process group ID specified to receive .C SIGURG signals when out-of-band data is available. Positive values indicate a process ID; negative values, other than -1, indicate a process group ID. .TP .C F_SETOWN If .I fildes refers to a socket, .C fcntl() sets the process or process group ID specified to receive .C SIGURG signals when out-of-band data is available, using the value of the third argument, arg, taken as type int. Positive values indicate a process ID; negative values, other than -1, indicate a process group ID. .TP .C F_GETLK64 Same as .CR F_GETLK, except .IR arg is a pointer to .C struct flock64 instead of .CR "struct flock" . .TP .C F_SETLK64 Same as .CR F_SETLK , except .IR arg is a pointer to .CR "struct flock64" instead of .CR "struct flock" . .TP .C F_SETLKW64 Same as .CR F_SETLKW , except .IR arg is a pointer to .C struct flock64 instead of .CR "struct flock" . .PP Turning the .C O_LARGEFILE flag on and off can be done with .CR F_SETFL . .PP A read lock prevents any other process from write-locking the protected area. More than one read lock can exist for a given segment of a file at a given time. The file descriptor on which a read lock is being placed must have been opened with read access. .PP A write lock prevents any other process from read-locking or write-locking the protected area. Only one write lock may exist for a given segment of a file at a given time. The file descriptor on which a write lock is being placed must have been opened with write access. .PP The structure .CR flock describes the type .RC ( l_type ), starting offset .RC ( l_whence ), relative offset .RC ( l_start ), size .RC ( l_len ), and process ID .RC ( l_pid ) of the segment of the file to be affected. The process ID field is only used with the .C F_GETLK .I cmd to return the value of a block in lock. Locks can start and extend beyond the current end of a file, but cannot be negative relative to the beginning of the file. A lock can be set to always extend to the end of file by setting .C l_len to zero (0). If such a lock also has .C l_start set to zero (0), the whole file will be locked. Changing or unlocking a segment from the middle of a larger locked segment leaves two smaller segments for either end. Locking a segment already locked by the calling process causes the old lock type to be removed and the new lock type to take effect. All locks associated with a file for a given process are removed when a file descriptor for that file is closed by that process or the process holding that file descriptor terminates. Locks are not inherited by a child process in a .IR fork (2) system call. .PP When enforcement-mode file and record locking is activated on a file (see .IR chmod (2)), future .C read() and .C write() system calls on the file are affected by the record locks in effect. .SH NETWORKING FEATURES .TP 5 .B NFS The advisory record-locking capabilities of .IR fcntl(2) are implemented throughout the network by the ``network lock daemon'' (see .IR lockd(1M)). If the file server crashes and is rebooted, the lock daemon attempts to recover all locks associated with the crashed server. If a lock cannot be reclaimed, the process that held the lock is issued a .CR SIGLOST signal. .IP Record locking, as implemented for NFS files, is only advisory. .SH RETURN VALUE Upon successful completion, the value returned depends on .I cmd as follows: .RS .TP 15 .C F_DUPFD A new file descriptor. .TP 15 .C F_GETFD Value of close-on-exec flag (only the low-order bit is defined). .TP .C F_SETFD Value other than \(mi1. .TP .C F_GETFL Value of file status flags and access modes. .TP .C F_SETFL Value other than \(mi1. .TP .C F_GETLK Value other than \(mi1. .TP .C F_SETLK Value other than \(mi1. .TP .C F_SETLKW Value other than \(mi1. .TP .C F_GETOWN Value of process or process group ID specified to receive .C SIGURG signals when out-of-band data is available. .TP .C F_SETOWN Value other than \(mi1. .TP .C F_GETLK64 Value other than \(mi1. .TP .C F_SETLK64 Value other than \(mi1. .TP .C F_SETLKW64 Value other than \(mi1. .RE .PP Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS .CR fcntl() fails if any of the following conditions occur: .RS .TP 15 [EBADF] .I fildes is not a valid open file descriptor, or was not opened for reading when setting a read lock or for writing when setting a write lock. .TP [EMFILE] .I cmd is .C F_DUPFD and the maximum number of file descriptors is currently open. .TP [EMFILE] .I cmd is .CR F_SETLK or .CR F_SETLKW , the type of lock is a read or write lock, and no more file-locking headers are available (too many files have segments locked). .TP [EMFILE] .I cmd is .CR F_DUPFD and .IC arg . val is greater than or equal to the maximum number of file descriptors. .TP [EMFILE] .I cmd is .CR F_DUPFD and .IC arg . val is negative. .TP [EINVAL] .I cmd is .CR F_GETLK , .CR F_SETLK , or .CR F_SETLKW , and .IC arg . lockdes or the data it points to is not valid, or .I fildes refers to a file that does not support locking. .TP [EINVAL] .I cmd is not a valid command. .TP [EINVAL] .I cmd is .C F_SETFL and both .CR O_NONBLOCK and .CR O_NDELAY are specified. .TP [EINTR] .I cmd is .CR F_SETLKW and the call was interrupted by a signal. .TP [EACCES] .I cmd is .CR F_SETLK , the type of lock .RC ( l_type ) is a read lock .RC (\| F_RDLCK \|) or write lock .RC (\| F_WRLCK \|) and the segment of a file to be locked is already write-locked by another process, or the type is a write lock .RC (\| F_WRLCK \|) and the segment of a file to be locked is already read- or write-locked by another process. .TP [ENOLCK] .I cmd is .CR F_SETLK or .CR F_SETLKW , the type of lock is a read or write lock, and no more file-locking headers are available (too many files have segments locked), or no more record locks are available (too many file segments locked). .TP [ENOLCK] .I cmd is .C F_SETLK or .CR F_SETLKW , the type of lock .RC ( l_type ) is a read lock .RC (\| F_RDLCK \|) or write lock .RC (\| F_WRLCK \|) and the file is an NFS file with access bits set for enforcement mode. .TP [ENOLCK] .I cmd is .CR F_GETLK , .CR F_SETLK , or .CR F_SETLKW , the file is an NFS file, and a system error occurred on the remote node. .TP [EOVERFLOW] .I cmd is .CR F_GETLK and the blocking lock's starting offset or length would not fit in the caller's structure. .TP [EDEADLK] .I cmd is .CR F_SETLKW , when the lock is blocked by a lock from another process and sleeping (waiting) for that lock to become free. This causes a deadlock situation. .TP [EAGAIN] .I cmd is .CR F_SETLK or .CR F_SETLKW , and the file is mapped in to virtual memory via the .CR mmap() system call (see .IR mmap (2)). .TP [EFAULT] .I cmd is either .CR F_GETLK , .CR F_SETLK , or .CR F_SETLKW , and .I arg points to an illegal address. .TP [ENOTSOCK] .I cmd is .CR F_GETOWN or .CR F_SETOWN , and .I fildes does not refer to a socket. .RE .SH AUTHOR .CR fcntl() was developed by HP, AT&T and the University of California, Berkeley. .SH APPLICATION USAGE Because in the future the external variable .CR errno will be set to EAGAIN rather than EACCES when a section of a file is already locked by another process, portable application programs should expect and test for either value, for example: .nf .IP .C "flk->l_type = F_RDLCK;" .C " if (fcntl(fd, F_SETLK, flk) == -1)" .C " if ((errno == EACCES) || (errno == EAGAIN))" .C " /*" .C " * section locked by another process," .C " * check for either EAGAIN or EACCES" .C " * due to different implementations" .C " */" .C " else if ..." .C " /*" .C " * check for other errors" .C " */" .fi .SH SEE ALSO lockd(1M), statd(1M), chmod(2), close(2), exec(2), lockf(2), lockf64(), open(2), read(2), write(2), fcntl(5). .SH FUTURE DIRECTIONS The error condition which currently sets .CR errno to EACCES will instead set .CR errno to EAGAIN (see also APPLICATION USAGE above). .SH STANDARDS CONFORMANCE .CR fcntl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4fcntl()\fP \(mi open-file control@@@\f3fcntl(2)\f1 .\" index@open-file control@@@\f3fcntl(2)\f1 .\" index@file: open-file control routines@@@\f3fcntl(2)\f1 .\" index@control routines for open-files@@@\f3fcntl(2)\f1 .\" .\" toc@\f3fcntl(2)\f1:\0\0\f4fcntl()\fP@@@file control .\" .\" $Header: fsync.2,v 72.5 94/11/14 15:24:04 ssa Exp $ .TA f .TH fsync 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fsync, fdatasync \- synchronize a file's in-core and on-disk states .SH SYNOPSIS .C "#include " .PP .C "int fsync(int fildes);" .PP .C "int fdatasync(int fildes);" .SH DESCRIPTION .C fsync() and .C fdatasync() cause all modified data and attributes of .I fildes 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. .C fsync() and .C fdatasync() apply to ordinary files, and apply to block special devices on systems which permit .SM I/O to block special devices. .PP .C fsync() and .C fdatasync() should be used by programs that require a file to be in a known state, such as when building a simple transaction facility. .PP .C fdatasync() causes all modified data and file attributes of .I fildes required to retrieve the data to be written to disk. .PP .C fsync() causes all modified data and all file attributes of .I fildes (including access time, modification time and status change time) to be written to disk. .PP Together, .C fsync() and .C fdatasync() constitute support for File Synchronization. .SH RETURN VALUE .C fsync() and .C fdatasync() return 0 on success or \(mi1 if an error occurs, and set .C errno to indicate the error. .SH ERRORS .IR fsync and .IR fdatasync fail if any of the following conditions are encountered: .RS .TP 15 .SM [EBADF] .I fildes is not a valid descriptor. .TP .SM [EINVAL] .I fildes refers to a file type to which .C fsync() or .C fdatasync() does not apply. .RE .SH WARNINGS The current implementation of these functions is inefficient for large files. .SH AUTHOR .C fsync() was developed by the the University of California, Berkeley and HP. .SH SEE ALSO fcntl(2), fcntl(5), open(2), select(2), sync(2), sync(1M), unistd(5). .SH STANDARDS CONFORMANCE .CR fsync() ": AES, SVID3, XPG3, XPG4, POSIX.4" .PP .CR fdatasync() ": POSIX.4" .\" .\" index@\f4fsync()\fP, \f4fdatasync()\fP \(mi synchronize a file's in-core state with its state on disk@@@\f3fsync(2)\f1 .\" index@synchronize a file's in-core state with its state on disk@@@\f3fsync(2)\f1 .\" index@file's in-core state with its state on disk, synchronize a@@@\f3fsync(2)\f1 .\" index@in-core state with its state on disk, synchronize a file's@@@\f3fsync(2)\f1 .\" index@state with its state on disk, synchronize a file's in-core@@@\f3fsync(2)\f1 .\" index@disk, synchronize a file's in-core state with its state on@@@\f3fsync(2)\f1 .\" .\" toc@\f3fsync(2)\f1:\0\0\f4fsync()\fP, \f4fdatasync()\fP@@@synchronize a file's in-core state with its state on disk .\" toc@\f4fdatasync()\fP:\0\0synchronize a file's in-core state with its state on disk@@@see \f3fsync(2)\f1 .\" .\" links@fsync.2 fdatasync.2 .\" .\" fileset_database@fsync.2 PROGRAMING-MAN .\" $Header: getacl.2,v 72.5 94/09/19 09:13:15 ssa Exp $ .TA g .TH getacl 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getacl, fgetacl \- get access control list (ACL) information (HFS File Systems only) .SH SYNOPSIS .C "#include " .PP .C "int getacl(" .nf .PD 0 .IP .C "const char *path," .C "int nentries," .C "struct acl_entry *acl" .PP .C ");" .PD .PP .C "int fgetacl(int fildes, int nentries, struct acl_entry *acl);" .fi .SH DESCRIPTION .C getacl() returns a complete listing of all .SM ACL entries .RI ( uid.gid , .IR mode ) in an existing file's access control list. .I path points to a path name of a file. .PP Similarly, .C fgetacl() returns a complete listing of all .SM ACL entries for an open file known by the file descriptor .IR fildes . .PP .I nentries is the number of entries being reported on, and is never more than the constant .C NACLENTRIES defined in .RC < sys/acl.h >. If .I nentries is non-zero, it must be at least as large as the number of entries in the file's .SM ACL, including base entries (see .IR setacl (2)). .C getacl() returns the number of entries in the file's .SM ACL, as well as the .SM ACL entries themselves in the array of structures .I acl declared by the calling program. .PP If .I nentries is zero, .C getacl() returns the number of entries in the file's .SM ACL, including base .SM ACL entries, and .I acl is ignored. .PP Entries are reported in groups of decreasing order of specificity (see .IR setacl (2)), then sorted in each group by user .SM ID and group .SM ID. The content of array entries beyond the number of defined entries for the file is undefined. .SH RETURN VALUE Upon successful completion, .C getacl() and .C fgetacl() return a non-negative value. If an error occurs, a value of \(mi1 is returned, and .CR errno is set to indicate the error. .SH ERRORS .C getacl() or .C fgetacl() fail to modify the .I acl array if any of the following is true: .RS .TP 15 .SM [ENOTDIR] A component of the .I path prefix is not a directory. .TP .SM [ENOENT] The named file does not exist (for example, .I path is null or a component of .I path does not exist). .TP .SM [EBADF] .I fildes is not a valid file descriptor. .TP .SM [EACCES] A component of the .I path prefix denies search permission. .TP .SM [EFAULT] .I path or a portion of .I acl to be written points outside the allocated address space of the process. .TP .SM [EINVAL] .I nentries is non-zero and less than the number of entries in the file's .SM ACL, or it is greater than .CR NACLENTRIES . .TP .SM [EOPNOTSUPP] .C getacl() is not supported on remote files by some networking services. .TP .SM [ENFILE] The system file table is full. .TP .SM [ENAMETOOLONG] The length of .I path exceeds .C PATH_MAX bytes, or the length of a component of .I path exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the .I path name. .RE .SH EXAMPLES The following call returns the number of entries in the .SM ACL on file .CR /users/bill/mcfile . .IP .C #include .IP .ift .ft 4 .ifn .ft 3 .ps +1 entries = getacl ("/users/bill/mcfile", 0, (struct acl_entry \(**) 0); .PP The following call returns in .I acl all entries in the .SM ACL on the file opened with file descriptor 5. .nf .IP .C #include .IP .C int nentries; .C struct acl_entry acl [NACLENTRIES]; .IP .C entries = fgetacl (5, NACLENTRIES, acl); .fi .SH DEPENDENCIES .C getacl() and .C fgetacl() are only supported on HFS file system on standard HP-UX operating system. .SH AUTHOR .C getacl() and .C fgetacl() were developed by HP. .SH SEE ALSO access(2), chmod(2), getaccess(2), setacl(2), stat(2), unistd(5). .\" .\" index@\f4getacl()\fP, \f4fgetacl()\fP \(mi get access control list (\s-1ACL\s+1) information@@@\f3getacl(2)\f1 .\" index@\f4fgetacl()\fP \(mi get access control list (\s-1ACL\s+1) information@@@\f3getacl(2)\f1 .\" index@get access control list (\s-1ACL\s+1) information@@@\f3getacl(2)\f1 .\" index@access control list (\s-1ACL\s+1) information, get@@@\f3getacl(2)\f1 .\" .\" toc@\f3getacl(2)\f1:\0\0\f4getacl()\fP, \f4fgetacl()\fP@@@get access control list (\s-1ACL\s+1) information .\" toc@\f4fgetacl()\fP: get access control list (\s-1ACL\s+1) information@@@see \f3getacl(2)\f1 .\" .\" links@getacl.2 fgetacl.2 .\" .\" fileset_database@getacl.2 PROGRAMING-MAN .\" $Header: fork.2,v 72.6 94/11/14 15:24:00 ssa Exp $ .TA f .TH fork 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fork \- create a new process .SH SYNOPSIS .C "#include " .PP .C "pid_t fork(void);" .SH DESCRIPTION The .CR fork() system call causes the creation of a new process. The new process (the child process) is an exact copy of the calling process (the parent process). This means that the child process inherits the following attributes from the parent process: .RS .TP 3 .PD 0 \(bu Real, effective, and saved user IDs. .TP \(bu Real, effective, and saved group IDs. .TP \(bu List of supplementary group IDs (see .IR getgroups (2)). .TP \(bu Process group ID. .TP \(bu Environment. .TP \(bu File descriptors. .TP \(bu Close-on-exec flags (see .IR exec (2)). .TP \(bu Signal handling settings .RC ( SIG_DFL , .CR SIG_IGN , .IR address ). .TP \(bu Signal mask (see .IR sigvector (2)). .TP \(bu Profiling on/off status (see .IR profil (2)). .TP \(bu Command name in the accounting record (see .IR acct (4)). .TP \(bu Nice value (see .IR nice (2)). .TP \(bu All attached shared memory segments (see .IR shmop (2)). .TP \(bu Current working directory .TP \(bu Root directory (see .IR chroot (2)). .TP \(bu File mode creation mask (see .IR umask (2)). .TP \(bu File size limit (see .IR ulimit (2)). .TP \(bu Real-time priority (see .IR rtprio (2)). .PD .RE .PP Each of the child's file descriptors shares a common open file description with the corresponding file descriptor of the parent. This implies that changes to the file offset, file access mode, and file status flags of file descriptors in the parent also affect those in the child, and vice-versa. .PP The child process differs from the parent process in the following ways: .IP The child process has a unique process ID. .IP The child process ID does not match any active process group ID. .IP The child process has a different parent process ID (which is the process ID of the parent process). .IP The set of signals pending for the child process is initialized to the empty set. .IP The trace flag (see the .IR ptrace (2) .CR PT_SETTRC request) is cleared in the child process. .IP The .CR AFORK flag in the .CR ac_flags component of the accounting record is set in the child process. .IP Process locks, text locks, and data locks are not inherited by the child (see .IR plock (2)). .IP All .CR semadj values are cleared (see .IR semop (2)). .IP The child process's values for .CR tms_utime , .CR tms_stime , .CR tms_cutime , and .CR tms_cstime are set to zero (see .IR times (2)). .IP The time left until an alarm clock signal is reset to 0 (clearing any pending alarm), and all interval timers are set to 0 (disabled). .PP The .IR vfork (2) system call can be used to fork processes more quickly than .CR fork() , but has some restrictions. See .IR vfork (2) for details. .PP If a parent and child process both have a file opened and the parent or child closes the file, the file is still open for the other process. .SH RETURN VALUE Upon successful completion, .CR fork() returns a value of .CR 0 to the child process and returns the process ID of the child process to the parent process. Otherwise, a value of \(mi1 is returned to the parent process, no child process is created, and .CR errno is set to indicate the error. .PP The parent and child processes resume execution immediately after the .CR fork() call; they are distinguished by the value returned by .IR fork . .SH ERRORS If .CR fork() fails, .CR errno is set to one of the following values. .RS .TP 15 [EAGAIN] The system-imposed limit on the total number of processes under execution would be exceeded. .TP [EAGAIN] The system-imposed limit on the total number of processes under execution by a single user would be exceeded. .TP [ENOMEM] There is insufficient swap space and/or physical memory available in which to create the new process. .RE .SH WARNINGS Standard I/O streams (see .IR stdio (3S)) are duplicated in the child. Therefore, if .IR fork is called after a buffered I/O operation without first closing or flushing the associated standard I/O stream (see .IR fclose (3S)), the buffered input or output might be duplicated. .SH DEPENDENCIES .SS HP Process Resource Manager If the optional HP Process Resource Manager (PRM) software is installed and configured, the child process inherits the parent's process resource group ID. See .IR prmconfig (1) for a description of how to configure HP PRM, and .IR prmconf (4) for the definition of process resource group. .SH AUTHOR .CR fork() was developed by AT&T, the University of California, Berkeley, and HP. .SH SEE ALSO acct(2), chroot(2), exec(2), exit(2), fcntl(2), getgroups(2), lockf(2), nice(2), plock(2), profil(2), ptrace(2), rtprio(2), semop(2), setpgrp(2), setuid(2), shmop(2), times(2), ulimit(2), umask(2), vfork(2), wait(2), fclose(3S), stdio(3S), acct(4), signal(5). .PP HP Process Resource Manager: prmconfig(1), prmconf(4) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR fork() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4fork()\f1 \- create a new process@@@\f3fork(2)\f1 .\" index@create a new process@@@\f3fork(2)\f1 .\" index@new process, create a@@@\f3fork(2)\f1 .\" index@process, create a new@@@\f3fork(2)\f1 .\" index@child process@@@\f3fork(2)\f1 .\" index@parent process@@@\f3fork(2)\f1 .\" .\" toc@\f3fork(2)\f1:\0\0\f4fork()\f1@@@create a new process .\" $Header: pathconf.2,v 78.1 96/02/12 14:08:34 ssa Exp $ .TA p .TH pathconf 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pathconf(\|), fpathconf(\|) \- get configurable path name variables .SH SYNOPSIS .C "#include " .PP .C "long pathconf(const char *path, int name);" .PP .C "long fpathconf(int fildes, int name);" .SH DESCRIPTION The .CR pathconf() and .CR fpathconf() functions provide a method for applications to determine the value of a configurable limit or option associated with a file or directory (see .IR limits (5) and .CR ). .PP For .CR pathconf() , the .IR path argument points to the path name of a file or directory. .PP For .CR fpathconf() , the .IR fildes argument is an open file descriptor. .PP For both functions, the .IR name argument represents the variable to be queried regarding the file or directory to which the other argument refers. .PP The following table lists the configuration variables available from .CR pathconf() and .CR fpathconf() , and lists for each variable the associated value of the .IR name argument: .PP .TS center tab(@); cB | cB | cB lf4 | lf4 | l. Variable@Value of \f2name\f1@Notes _ LINK_MAX@_PC_LINK_MAX@1 MAX_CANON@_PC_MAX_CANON@2 MAX_INPUT@_PC_MAX_INPUT@2 @_PC_FILESIZEBITS@3, 4, 10 NAME_MAX@_PC_NAME_MAX@3, 4 PATH_MAX@_PC_PATH_MAX@4, 5 PIPE_BUF@_PC_PIPE_BUF@6 _POSIX_CHOWN_RESTRICTED@_PC_CHOWN_RESTRICTED@7, 8 _POSIX_NO_TRUNC@_PC_NO_TRUNC@3, 4 _POSIX_SYNC_IO@_PC_SYNC_IO@9 _POSIX_VDISABLE@_PC_V_DISABLE@2 .TE .PP The variables in the table are defined as constants in .CR or .CR if they do not vary from one path name to another. The associated values of the .I name argument are defined in .CR . .SH RETURN VALUE The following notes further qualify the table above. .RS .TP 5 1. If .I path or .I fildes refers to a directory, the value returned applies to the directory itself. .TP 2. If the variable is constant, the value returned is identical to the variable's definition in .CR or .CR regardless of the type of .IR fildes or .IR path . The behavior is undefined if .I path or .I fildes does not refer to a terminal file. .TP 3. If .I path or .I fildes refers to a directory, the value returned applies to the file names within the directory. .TP 4. If .I path or .I fildes does not refer to a directory, .CR pathconf() or .CR fpathconf() returns \(mi1 and sets .CR errno to EINVAL. .TP 5. If .I path or .I fildes refers to a directory, the value returned is the maximum length of a relative path name when the specified directory is the working directory. .TP 6. If .I path refers to a FIFO, or if .I fildes refers to a pipe or FIFO, the value returned applies to the pipe or FIFO itself. If .I path or .I fildes refers to a directory, the value returned applies to any FIFOs that exist or can be created within the directory. If .CR PIPE_BUF is a constant, the value returned is identical to the definition of .CR PIPE_BUF in .CR regardless of the type of .I fildes or .IR path . The behavior is undefined for a file other than a directory, FIFO, or pipe. .TP 7. If .I path or .I fildes refers to a directory, the value returned applies to files of any type, other than directories, that exist or can be created within the directory. .TP 8. .CR _POSIX_CHOWN_RESTRICTED is defined if the privilege group .CR PRIV_GLOBAL has been granted the .CR CHOWN privilege (see .IR getprivgrp (2) and .IR chown (2)). In all other cases, .CR _POSIX_CHOWN_RESTRICTED is undefined and .CR pathconf() or .CR fpathconf() returns \(mi1 without changing .CR errno . To determine if .CR chown() can be performed on a file, it is simplest to attempt the .CR chown() operation and check the return value for failure or success. .TP 9. .CR _POSIX_SYNC_IO , when defined, determines whether synchronized IO operations may be performed for the associated file (see .IR open (2)). If .I path or .I fildes refers to a directory, it is unspecified whether or not the implementation supports an association of the variable name with the specified file. .TP 10. For file systems that are not large file enabled, the .CR _PC_FILESIZEBITS return value will be less than or equal to 32. For file systems that are large file enabled, the .CR _PC_FILESIZEBITS return value will be between 33 and 63. .RE .PP If the variable corresponding to .IR name is not defined for .IR path or .IR fildes , the .CR pathconf() and .CR fpathconf() functions succeed and return a value of \(mi1, without changing the value of .CR errno . .PP Upon any other successful completion, these functions return the value of the named variable with respect to the specified file or directory, as described above. .PP Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR pathconf() and .CR fpathconf() fail if any of the following conditions are encountered: .RS .TP 25 [EACCES] A component of the path prefix denies search permission. .TP [EBADF] The .IR fildes argument is not a valid open file descriptor. .TP [EFAULT] .I path points outside the allocated address space of the process. .TP [EINVAL] The value of .I name is not valid or the implementation does not support an association of the variable .IR name with the specified file. .TP [ELOOP] Too many symbolic links were encountered in translating .IR path . .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] The file named by .I path does not exist (for example, .I path is null, or a component of .I path does not exist). .TP [ENOTDIR] A component of the path prefix is not a directory. .\" The following should be included if actual device opens are .\" required to determine tty/line discipline parameters. .\" .TP .\" .SM [ENXIO] .\" The specified file is a character special or block special file, .\" and the device associated with this special file does not exist. .RE .SH EXAMPLES The following example sets .IR val to the value of .CR MAX_CANON for the device file being used as the standard input. If the standard input is a terminal, this value is the maximum number of input characters that can be entered on a single input line before typing the newline character: .nf .IP .C "if (isatty(0))" .RS .C "val = fpathconf(0, _PC_MAX_CANON);" .fi .RE .PP The following code segment shows two calls to .IR pathconf . The first determines whether a file name longer than .CR NAME_MAX bytes will be truncated to .CR NAME_MAX bytes in the .C /tmp directory. If so, the second call is made to determine the actual value of .CR NAME_MAX so that an error can be printed if a user-supplied file name stored in .I filebuf will be truncated in this directory: .nf .RS .IP .C "extern int errno;" .C "char *filebuf;" .RS .C "errno = 0; /* reset errno */" .C "if ( pathconf(""/tmp"" _PC_NO_TRUNC) == -1 ) {" .RS .C "/* _POSIX_NO_TRUNC is not in effect for this directory */" .C "if (strlen(filebuf) > pathconf("/tmp", PC_NAME_MAX)) {" .RS .C "fprintf(stderr, ""Filename %s too long.\\n"", filebuf);" .C "/* take error action */" .RE .C } .C else .RS .RS .C "if (errno) {" .RS .C "perror(""pathconf"");" .C "/* take error action */" .RE .C } .RE .C } .RE .RE .RE .C "/* otherwise, _POSIX_NO_TRUNC is in effect for this directory */" .RS .C "if ((fd = open(filebuf, O_CREAT, mode)) < 0)" .RS .C "perror(filebuf);" .fi .SH DEPENDENCIES .SS NFS The following error can occur: .RS .TP 20 [EOPNOTSUPP] .I path or .I fildes refers to a file for which a value for .I name cannot be determined. In particular, .CR _PC_LINK_MAX , .CR _PC_NAME_MAX , .CR _PC_PIPE_BUF , .CR _PC_PATH_MAX , .CR _PC_NO_TRUNC , and .CR _PC_CHOWN_RESTRICTED , cannot be determined for an NFS file. .RE .SH AUTHOR .CR pathconf() and .CR fpathconf() were developed by HP. .SH SEE ALSO chown(2), errno(2), limits(5), unistd(5), termio(7). .SH STANDARDS CONFORMANCE .CR pathconf() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.2, POSIX.4" .PP .CR fpathconf() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.2, POSIX.4" .\" .\" index@\f4pathconf()\f1 \- get configurable path name variables@@@\f3pathconf(2)\f1 .\" index@\f4fpathconf()\f1 \- get configurable path name variables@@@\f3pathconf(2)\f1 .\" index@\f4fpathconf()\f1 \- get configurable path name variables@@@\f3pathconf(2)\f1 .\" index@\f1get configurable path name variables@@@\f3pathconf(2)\f1 .\" index@\f1configurable path name variables, get@@@\f3pathconf(2)\f1 .\" index@\f1path name variables, get configurable@@@\f3pathconf(2)\f1 .\" index@\f1variables, configurable path name, get@@@\f3pathconf(2)\f1 .\" .\" toc@\f3pathconf(2)\f1:\0\0\f4pathconf()\f1, \f4fpathconf()\f1@@@get configurable path name variables\f1 .\" toc@\f4fpathconf()\f1:\0\0get configurable path name variables\f1@@@see \f3pathconf(2)\f1 .\" .\" links@pathconf.2 fpathconf.2 .\" .\" $Header: fsctl.2,v 72.4 94/09/19 09:12:12 ssa Exp $ .TA f .TH fsctl 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fsctl \- file system control .SH SYNOPSIS .C "#include " .PP .nf .PD 0 .C "int fsctl(" .IP .C "int fildes," .C "int command," .C "void *outbuf," .C "size_t outlen" .PP .C ");" .PD .fi .SH DESCRIPTION .C fsctl() provides access to file-system-specific information. .I fildes is an open file descriptor for a file in the file system of interest. The possible values for .I command depend on the type of file system. Currently, defined .IR command s exist only for the CDFS file system (see .CR sys/cdfsdir.h ). .PP .I outbuf is a pointer to the data area in which data is returned from the file system. .I outlen gives the length of the data area pointed to by .IR outbuf . .PP The CDFS .IR command s are: .RS .TP 18 .C CDFS_DIR_REC Returns the directory record for the file or directory indicated by .IR fildes . The record is returned in a structure of type .IR cddir , defined in .RC < sys/cdfsdir.h >. .TP .C CDFS_XAR Returns the extended attribute record, if any, for the file or directory indicated by .IR fildes . Because the size of an extended attribute record varies, be sure .I outbuf points to a data area of sufficient size. To find the necessary size, do the following: .RS .RS .TP 5 1. Use .IR statfs (2). to get the logical block size of the CDFS volume. .TP 2. Use an .C fsctl() call with the .C CDFS_DIR_REC command to get the extended attribute record size (in blocks) for the file or directory of interest. The .C mincdd_xar_len field in the returned structure contains the size of the extended attribute record in logical blocks. (If this field is zero, the file or directory has no extended attribute record.) .TP 3. Multiply .C mincdd_xar_len by the logical block size obtained in step 1 to get the total space needed. .TP 4. Once you get the extended attribute record, cast .I outbuf into a pointer to a structure of type .C cdxar_iso (defined in .RC < sys/cdfsdir.h >). This enables you to access those fields that are common to all extended attribute records. (See EXAMPLES below for an example of this process.) .IP If the extended attribute record contains additional system use or application use data, that data will have to be accessed manually. .RE .RE .TP .C CDFS_AFID Returns the abstract file identifier for the primary volume whose root directory is specified by .IR fildes , terminated with a NULL character. Note that the constant .C CDMAXNAMLEN defined in .RC < sys/cdfsdir.h > gives the maximum length a file identifier can have. Thus, .C CDMAXNAMLEN + 1 can be used for .I outlen and the size of .IR outbuf . .TP .C CDFS_BFID Returns the bibliographic file identifier for the primary volume whose root directory is specified by .IR fildes , terminated with a NULL character. .C CDMAXNAMLEN + 1 can be used for the value of .I outlen and the size of .IR outbuf . .TP .C CDFS_CFID Returns the copyright file identifier for the primary volume whose root directory is specified by .IR fildes , terminated with a NULL character. .C CDMAXNAMLEN + 1 can be used for the value of .I outlen and the size of .IR outbuf . .TP .C CDFS_VOL_ID Returns the volume ID for the primary volume specified by .IR fildes , terminated with a NULL character. The maximum size of the volume ID is 32 bytes, so a length of 33 can be used for .I outlen and the size of .IR utbuf . .TP .C CDFS_VOL_SET_ID Returns the volume set ID for the primary volume specified by .IR fildes , terminated with a NULL character. The maximum size of the volume set ID is 128 bytes, so a length of 129 can be used for .I outlen and the size of .IR outbuf . .RE .SH EXAMPLES The following code fragment gets the extended attribute record for a file on a CDFS volume. The filename is passed in as the first argument to the routine. Note that error checking is omitted for brevity. .nf .IP .C "#include " .C "#include " .C "#include " .C "#include " .C "main(argc, argv)" .C "int argc;" .C "char *argv[];" .C "{" .C " int fildes, size = 0;" .C " char *malloc(), *outbuf;" .C " struct statfs buf;" .C " struct cddir cdrec;" .C " struct cdxar_iso *xar;" .C " ." .C " ." .C " ." .C " statfs(argv[1], &buf); /* get logical block size */" .C " fildes = open(argv[1], O_RDONLY); /* open file arg */" .C " /* get directory record for file arg */" .C " fsctl(fildes, CDFS_DIR_REC, &cdrec, sizeof(cdrec));" .C " size = buf.f_bsize * cdrec.cdd_min.mincdd_xar_len; /* compute size */" .C " if(size) { /* if size != 0 then there is an xar */" .C " outbuf = malloc(size); /* malloc sufficient memory */" .C " fsctl(fildes, CDFS_XAR, outbuf, size); /* get xar */" .C " xar = (struct cdxar_iso *)outbuf; /* cast outbuf to access fields */" .C " ." .C " ." .C " ." .C " }" .C " ." .C " ." .C " ." .C "}" .fi .SH RETURN VALUE .C fsctl() returns the number of bytes read if successful. If an error occurs, \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .C fsctl() fails if any of the following conditions are encountered: .RS .TP 15 [EBADF] .I fildes is not a valid open file descriptor. .TP [EFAULT] .I outbuf points to an invalid address. .TP [ENOENT] The requested information does not exist. .TP [EINVAL] .I command is not a valid command. .TP [EINVAL] .I outlen is negative, or .I fildes does not refer to a CDFS file system. .RE .SH SEE ALSO statfs(2), cdfs(4), cdfsdir(4), cdnode(4), cdrom(4). .\" .\" index@\f4fsctl()\fP \(mi file system control@@@\f3fsctl(2)\f1 .\" index@file system control@@@\f3fsctl(2)\f1 .\" index@control, file system@@@\f3fsctl(2)\f1 .\" .\" toc@\f3fsctl(2)\f1:\0\0\f4fsctl()\fP@@@file system control .\" .\" fileset_database@fsctl.2 PROGRAMING-MAN .\" $Header: setacl.2,v 72.4 94/08/30 16:52:57 ssa Exp $ .TA s .TH setacl 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setacl, fsetacl \- set access control list (ACL) information .SH SYNOPSIS .C "#include " .PP .nf .C "int setacl(" .PD 0 .IP .C "const char *path," .C "size_t nentries," .C "const struct acl_entry *acl" .PP .C ");" .PD .PP .C "int fsetacl(" .PD 0 .IP .C "int fildes," .C "size_t nentries," .C "const struct acl_entry *acl" .PP .C ");" .PD .fi .SH DESCRIPTION .C setacl() sets an existing file's access control list (ACL) or deletes optional entries from it. .I path points to a path name of a file. .PP Similarly, .C fsetacl() sets an existing file's access control list for an open file known by the file descriptor .IR fildes . .PP The effective user ID of the process must match the owner of the file or be the super-user to set a file's ACL. .PP A successful call to .C setacl() deletes all of a file's previous optional ACL entries (see explanation below), if any. .I nentries indicates how many valid entries are defined in the .I acl parameter. If .I nentries is zero or greater, the new ACL is applied to the file. If any of the file's base entries (see below) is not mentioned in the new ACL, it is retained but its access mode is set to zero (no access). Hence, routine calls of .C setacl() completely define the file's ACL. .PP As a special case, if .I nentries is negative (that is, a value of .C ACL_DELOPT (defined in .CR ), the .I acl parameter is ignored, all of the file's optional entries, if any, are deleted, and its base entries are left unaltered. .PP Some of the miscellaneous mode bits in the file's mode might be turned off as a consequence of calling .CR setacl() . See .IR chmod (2). .SS "Access Control Lists" An ACL consists of a series of entries. Entries can be categorized in four levels of specificity: .RS .TP 15 .RC ( \f2u\fP.\f2g\fP, " \f2mode\fP)" applies to user .I u in group .I g .PD 0 .TP .RC ( \f2u\fP.%, " \f2mode\fP)" applies to user .I u in any group .TP .RC ( %.\f2g\fP, " \f2mode\fP)" applies to any user in group .I g .TP .RC ( %.%, " \f2mode\fP)" applies to any user in any group .PD .RE .PP Entries in the ACL must be unique; no two entries can have the same user ID .RI ( uid ) and group ID .RI ( gid ) (see below). Entries can appear in any order. The system orders them as needed for access checking. .PP The .CR header file defines .C ACL_NSUSER as the non-specific .I uid value and .C ACL_NSGROUP as the non-specific .I gid value represented by .C % above. If .I uid in an entry is .CR ACL_NSUSER , it is a .CI %. g entry. If .I gid in an entry is .CR ACL_NSGROUP , it is a .IC u .% entry. If both .I uid and .I gid are non-specific, the file's entry is .CR %.% . .PP The .CR header file defines meanings of mode bits in ACL entries (\c .CR R_OK , .CR W_OK , and .CR X_OK ). Irrelevant bits in mode values must be zero. .PP Every file's ACL has three base entries which cannot be added or deleted, but only modified. The base ACL entries are mapped directly from the file's permission bits. .nf .IP ( . ACL_NSGROUP, ) (ACL_NSUSER . , ) (ACL_NSUSER . ACL_NSGROUP, ) .fi .PP In addition, up to 13 optional ACL entries can be set to restrict or grant access to a file. .PP Altering a base ACL entry's modes with .C setacl() changes the file's corresponding permission bits. The permission bits can be altered also by using .C chmod() (see .IR chmod (2)) and read using .C stat() (see .IR stat (2)). .PP The number of entries allowed per file (see .C NACLENTRIES in .CR ) is small for space and performance reasons. User groups should be created as needed for access control purposes. Since ordinary users cannot create groups, their ability to control file access with ACLs might be somewhat limited. .SH RETURN VALUE Upon successful completion, .C setacl() and .C fsetacl() return a value of zero. If an error occurs, they return \(mi1, the file's ACL is not modified, and .C errno is set to indicate the error. .SH ERRORS .C setacl() and .C fsetacl() fail if any of the following conditions are encountered: .RS .TP 20 [ENOTDIR] A component of the .I path prefix is not a directory. .TP [ENOENT] The named file does not exist (for example, .I path is null or a component of .I path does not exist). .TP [EBADF] .I fildes is not a valid file descriptor. .TP [EACCES] A component of the .I path prefix denies search permission. .TP [EPERM] The effective user ID does not match the owner of the file and the effective user ID is not super-user. .TP [EROFS] The named file resides on a read-only file system. .TP [EFAULT] .I path or .I acl points outside the allocated address space of the process, or .I acl is not as large as indicated by .IR nentries . .TP [EINVAL] There is a redundant entry in the ACL, or .I acl contains an invalid .IR uid , .IR gid , or .I mode value. .TP [E2BIG] An attempt was made to set an ACL with more than .C NACLENTRIES entries. .TP [EOPNOTSUPP] ACLs are only supported on HFS file systems. Additionally, .CR setacl() is not supported on remote files by some networking services. .TP [ENOSPC] Not enough space on the file system. .TP [ENFILE] System file table is full. .TP [ENAMETOOLONG] The length of .I path exceeds .C PATH_MAX bytes, or the length of a component of .I path exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP [ELOOP] Too many symbolic links were encountered in translating the .I path name. .TP [EDQUOT] User's disk quota block or inode limit has been reached for this file system. .RE .SH EXAMPLES The following code fragment defines and sets an ACL on file .C ../shared which allows the file's owner to read, write, and execute or search the file, and allows user 103, group 204 to read the file. .nf .IP .C #include .C #include .C #include .IP .ifn .ft 3 .ift .ft 4 .ps +1 char *filename = "../shared"; .ft .ps .C struct acl_entry acl [2]; .C struct stat statbuf; .IP .C if (stat (filename, & statbuf) < 0) .C " error (...);" .IP .C "acl [0] . uid = statbuf . st_uid; /* file owner */" .C "acl [0] . gid = ACL_NSGROUP;" .C "acl [0] . mode = R_OK | W_OK | X_OK;" .IP .C "acl [1] . uid = 103;" .C "acl [1] . gid = 204;" .C "acl [1] . mode = R_OK;" .IP .C "if (setacl (filename, 2, acl))" .C " error (...);\f1" .fi .PP The following call deletes all optional ACL entries from .CR file1 : .IP .ifn .ft 3 .ift .ft 4 .ps +1 setacl ("file1", ACL_DELOPT, (struct acl_entry *) 0); .ft .ps .SH DEPENDENCIES .SS NFS .C setacl() and .C fsetacl() are not supported on remote files. .SS HFS ACLs are only supported on HFS file systems. .SH AUTHOR .C setacl() and .C fsetacl() were developed by HP. .SH SEE ALSO access(2), chmod(2), getaccess(2), getacl(2), stat(2), acl(5), unistd(5). .\" .\" index@\f4setacl()\f1, \f4fsetacl()\f1 \- set access control list (ACL) information@@@\f3setacl(2)\f1 .\" index@\f4fsetacl()\f1 \- set access control list (ACL) information@@@\f3setacl(2)\f1 .\" index@\f1set access control list (ACL) information@@@\f3setacl(2)\f1 .\" index@\f1access control list (ACL) information, set@@@\f3setacl(2)\f1 .\" .\" toc@\f3setacl(2)\f1:\0\0\f4setacl()\f1, \f4fsetacl()\f1@@@set access control list (ACL) information .\" toc@\f4fsetacl()\f1\0\0set access control list (ACL) information@@@\f1see \f3setacl(2)\f1 .\" .\" links@setacl.2 fsetacl.2 .\" .\" fileset_database@setacl.2 PROGRAMING-MAN .\" $Header: fstat.2,v 78.1 96/02/12 13:48:28 ssa Exp $ .TA f .TH fstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fstat \- get file status .SH SYNOPSIS .SH OH .C "#include " .PP .C "#include " .PP .C "int fstat(int fildes, struct stat *buf);" .SH DESCRIPTION The .CR fstat() function obtains information about an open file associated with the file descriptor .IR fildes , and writes it to the area pointed to by .IR buf . The .IR buf argument is a pointer to a .CR stat structure, as defined in .CR , into which information is placed concerning the file. .PP The structure members .IR st_mode , .IR st_ino , .IR st_dev , .IR st_uid , .IR st_gid , .IR st_atime , .IR st_ctime , and .IR st_mtime will have meaningful values for all file types defined in this document. The value of the member .IR st_nlink will be set to the number of links to the file. .PP An implementation that provides additional or alternative file access control mechanisms may, under implementation\-dependent conditions, cause .CR fstat() to fail. .PP The .CR fstat() function updates any time\-related fields as described in File Times Update (see the XBD specification, Chapter 4, Character Set), before writing into the .CR stat structure. .SH RETURN VALUE Upon successful completion, 0 is returned. Otherwise, \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR fstat() function will fail if: .RS .TP 25 [EBADF] The .IR fildes argument is not a valid file descriptor. .\" UX .TP [EIO] An I/O error occurred while reading from the file system. .\" ? .\" UX .RE .PP The .CR fstat() function may fail if: .RS .TP 25 [EOVERFLOW] One of the values is too large to store into the structure pointed to by the .IR buf argument. .\" ? .SH SEE ALSO lstat(), stat(), , . .SH CHANGE HISTORY First released in Issue 1. .PP Derived from Issue 1 of the SVID. .SH Issue 4 .PP The following changes are incorporated in the DESCRIPTION section for alignment with the ISO POSIX-1 standard: .RS .TP 3 \(bu A paragraph defining the contents of .CR stat structure members is added. .TP 3 \(bu The words "extended security controls" are replaced by "additional or alternative file access control mechanisms." .RE .PP Another change is incorporated as follows: .RS .TP 3 \(bu The header .CR is now marked as optional (OH); this header need not be included on XSI-conformant systems. .SH Issue 4, Version 2 .PP The ERRORS section is updated for X/OPEN UNIX conformance as follows: .RS .TP 3 \(bu The EIO error is added as a mandatory error indicated the occurrence of an I/O error. .TP 3 \(bu The EOVERFLOW error is added as an optional error indicating that one of the values is too large to store in the area pointed to by .IR buf . .TA .TH fstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH DESCRIPTION If the chosen path name or file descriptor refers to a Multi\-Level Directory (MLD), and the process does not have the multilevel effective privilege, the i\-node number returned in .IR st_ino is the i\-node of the MLD itself. .PP The parameters for the .CR fstat() function is as follows: .RS .TP 15 .IR buf is a pointer to a .CR stat() structure, which is where the file status information is stored. .TP .IR fildes is a file descriptor for an open file, which is created with the successful completion of an .CR open() , .CR creat() , .CR dup() , .CR fcntl() , or .CR pipe() system call (see .IR open (2), .IR creat (2), .IR dup (2), .IR fcntl (2), or .IR pipe (2)). .RE .PP The .CR stat structure contains the following members: .PP .TS center tab (#); lf4#lf4#lf4. dev_t#st_dev;#/* ID of device containing a */ ##/* directory entry for this file */ ino_t#st_ino;#/* Inode number */ ushort#st_fstype;#/* Type of filesystem this file */ ##/* is in; see sysfs(2) */ ushort#st_mode;#/* File type, attributes, and */ ##/* access control summary */ ushort#st_basemode#/* Permission bits (see chmod(1)) */ ushort#st_nlink;#/* Number of links */ uid_t#st_uid;#/* User ID of file owner */ gid_t#st_gid;#/* Group ID of file group */ dev_t#st_rdev;#/* Device ID; this entry defined */ ##/* only for char or blk spec files */ off_t#st_size;#/* File size (bytes) */ time_t#st_atime;#/* Time of last access */ time_t#st_mtime;#/* Last modification time */ time_t#st_ctime;#/* Last file status change time */ ##/* Measured in secs since */ ##/* 00:00:00 GMT, Jan 1, 1970 */ long#st_blksize;#/* File system block size */ uint#st_acl:1;#/* Set if the file has optional */ ##/* access control list entries */ ##/* HFS File Systems only */ .TE .PP (Note that the position of items in this list does not necessarily reflect the order of the members in the structure.) .PP The fields contain the following information: .RS .TP 15 .IR st_atime Time when file data was last accessed. Changed by the following system calls: .CR creat() , .CR mknod() , .CR pipe() , .CR read() , .CR readv() (see .IR read (2)), and .IR utime (). If a file is mapped into virtual memory, accesses of file data through the mapping may also modify .IR st_mtime . See .IR mmap (2). .TP .IR st_mtime Time when data was last modified. Changed by the following system calls: .CR creat() , .CR truncate() , .CR ftruncate() , (see .IR truncate (2)), .IR mknod (), .IR pipe () , .IR prealloc (), .IR utime (), .IR write (), and .IR writev () (see .IR write (2)). Also changed by .CR close() when the reference count reaches zero on a named pipe (FIFO special) file that contains data. If a file is mapped into virtual memory, updates of file data through the mapping may also modify .IR st_mtime . See .IR mmap (2). .TP .IR st_ctime Time when file status was last changed. Changed by the following system calls: .CR chmod() , .CR chown() , .CR creat() , .CR fchmod() , .CR fchown() , .CR truncate() , .CR ftruncate() , (see .IR truncate (2)), .IR link (), .IR mknod (), .IR pipe (), .IR prealloc (), .IR rename (), .IR setacl (), .IR unlink (), .IR utime (), .IR write (), and .IR writev () (see .IR write (2)). The .CR touch command (see .IR touch (1) can be used to explicitly control the times of a file. .TP .IR st_mode The value returned in this field is the bit\-wise inclusive OR of a value indicating the file's type, attribute bits, and a value summarizing its access permission. See .IR mknod (2). For ordinary users, the least significant nine bits consist of the file's permission bits modified to reflect the access granted or denied to the caller by optional entries in the file's access control list. For users with appropriate privileges the least significant nine bits are the file's access permission bits. In addition, the .CR S_IXUSR (execute by owner) mode bit is set if the following conditions are met: .RS .RS .TP 3 \(bu The file is a regular file, .TP 3 \(bu No permission execute bits are set, and .TP 3 \(bu An execute bit is set in one or more of the file's optional access control list entries. .RE .PP The write bit is not cleared for a file on a read\-only file system or a shared\-text program file that is being executed. However, .CR getaccess() clears this bit under these conditions (see .IR getaccess (2). .RE .SH ERRORS .RS .TP 15 [EFAULT] .IR buf or .IR path points to an invalid address. The reliable detection of this error is implementation\-dependent. .TP [EOVERFLOW] The file size in bytes or the number of blocks allocated to the file cannot be represented correctly in the structure pointed to by .IR buf. .RE .PP .SS NFS .PP The .IR st_basemode and .IR st_acl fields are zero on files accessed remotely. .IR st_acl field is applicable to HFS File Systems only. .SH WARNINGS .SS "Access Control Lists \- HFS File Systems only" .PP Access control list descriptions in this entry apply only to HFS file systems on standard HP\-UX operating systems. .SH DEPENDENCIES .SS "CD-ROM" .PP The .IR st_uid and .IR st_gid fields are set to \(mi1 if they are not specified on the disk for a given file. .SH AUTHOR .CR stat() and .CR fstat() were developed by AT&T. .CR lstat() was developed by the University of California, Berkeley. .SH SEE ALSO touch(1), chmod(2), chown(2), creat(2), fstat64(2), link(2), mknod(2), pipe(2), read(2), rename(2), setacl(2), sysfs(2), time(2), truncate(2), unlink(2), utime(2), write(2), acl(5), privileges(5), stat(5). .SH STANDARDS CONFORMANCE fstat(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 .\" .\" index@\f4fstat()\f1 \- get file status@@@\f3fstat(2)\f1 .\" index@\f1get file status@@@\f3fstat(2)\f1 .\" index@\f1file status, get@@@\f3fstat(2)\f1 .\" index@\f1status, get file status@@@\f3fstat(2)\f1 .\" index@\f1files: get status@@@\f3fstat(2)\f1 .\" .\" toc@\f3fstat(2)\f1:\0\0\f4fstat()\f1@@@get file status .\" .\" $Header: creat64.2,v 78.2 96/02/12 13:37:12 ssa Exp $ .TA c .TH creat64 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME creat64(\|), fstat64(\|), getrlimit64(\|), lockf64(\|), lseek64(\|), lstat64(\|), mmap64(\|), open64(\|), prealloc64(\|), setrlimit64(\|), stat64(\|), statvfs64(\|), truncate64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0creat64(const\0char\0*path,\0mode_t\0mode);" .PP .C "#include " .PP .C "int\0fstat64(int\0fildes,\0struct\0stat64\0*buf);" .PP .C "include\0" .PP .C "int\0getrlimit64(int resource,\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0lock64(int\0*fildes,\0int\0function,\0off64_t\0size);" .PP .C "#include " .PP .C "off64_t\0lseek64(int\0*fildes,\0off64_t\0offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0lstat64(const\0char\0*,\0struct\0stat64\0*);" .PP .C "#include " .PP .C "void\0mmap64(void\0addr,\0size_t\0len,\0int\0prot,\0int\0flags,\0int\0fildes,\0off64_t\0off);" .PP .C "#include " .PP .C "int\0open64(const\0char\0*path,\0int\0oflag,...);" .PP .C "#include " .PP .C "int\0prealloc64(int\0fildes,\0off64_t\0size);" .PP .C "include\0" .PP .C "int\0setrlimit64(int\0resource,\0const\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0stat64(const\0char\0*path,\0struct\0stat64\0*buf);" .PP .C "#include " .PP .C "int\0statvfs64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "int\0truncate64(const\0char\0*path,\0off64_t\0length);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 18 .C creat64() The .C creat64() function is identical to .C creat() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. .C creat64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR creat() . .TP .C fstat64() The .C fstat64() function is identical to .C fstat() except that .C fstat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C getrlimit64 The .C getrlimit64() function is identical to .C getrlimit() except that .C getrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .CR "struct rlimit" . All other functional behaviors, returns, and errors are identical. .TP .C lock64() The .C lock64() function is identical to .C lockf() except that .C lockf64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C lseek64() The .C lseek64() function is identical to .C lseek() except that .C lseek64() accepts an .CR off64_t type as the desired offset and has a return value of .CR off64_t. All other functional behaviors, returns, and errors are identical. .TP .C lstat64() The .C lstat64() function is identical to .C lstat() except that .C lstat64() returns file status in a .C struct stat64 instead of .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C mmap64() The .C mmap64() function is identical to .C mmap() except that .C mmap64() accepts the file offset as an .CR off64_t . .TP .C open64() The .C open64() function is identical to .C open() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. The .C open64() function is equivalent to .C open() function (in 32-bit compile environment) with .C O_LARGEFILE flag set. .C open64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR open() . .TP .C prealloc64() The .C prealloc64() function is identical to .C prealloc() except that .C prealloc64() accepts the file offset as an .CR off64_t . All other functional behaviors, returns, and errors are identical to .CR prealloc() . .TP .C setrlimit64 The .C setrlimit64() function is identical to .C setrlimit() except that .C setrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .C struct rlimit. All other functional behaviors, returns, and errors are identical. .TP .C stat64() The .C stat64() function is identical to .C stat() except that .C stat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . .TP .C statvfs64() Refer to .CR fstatvfs64() . .TP .C truncate64() The .C truncate64() function is identical to .C truncate() except that .C truncate64() accepts the length parameter as an .C off64_t instead of .CR off_t . All other functional behaviors, returns, and errors are identical to .CR truncate() . .\" .\" toc@\f4creat64(2)\f1:\0\0\f4fstat64\f1, \f4getrlimit64\f1, \f4lockf64\f1, \f4lseek64\f1, \f4lstat64\f1, \f4mmap64\f1, \f4open64\f1, \n\f4prealloc64\f1, \f4setrlimit64\f1, \f4stat64\f1, \f4statvfs64\f1, \f4truncate64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4creat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4fstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4getrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lockf64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lseek64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4mmap64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4open64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4prealloc64()\f1 \- file sysmmaptem API to support large files@@@\f3creat64(2)\f1 .\" index@\f4setrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4stat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4statvfs64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4truncate64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3creat64(2)\f1 .\" .\" links@creat64.2 fstat64.2 .\" links@creat64.2 getrlimit64.2 .\" links@creat64.2 lockf64.2 .\" links@creat64.2 lseek64.2 .\" links@creat64.2 lstat64.2 .\" links@creat64.2 mmap64.2 .\" links@creat64.2 open64.2 .\" links@creat64.2 prealloc64.2 .\" links@creat64.2 setrlimit64.2 .\" links@creat64.2 stat64.2 .\" links@creat64.2 statvfs64.2 .\" links@creat64.2 truncate64.2 .\" .\" $Header: statfs.2,v 72.5 94/07/05 16:35:17 ssa Exp $ .TA s .TH statfs 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME statfs, fstatfs \- get file system statistics .SH SYNOPSIS .C "#include " .PP .C "int statfs(const char *path, struct statfs *buf);" .PP .C "int fstatfs(int fildes, struct statfs *buf);" .SH DESCRIPTION .C statfs() returns status information for a mounted file system. .PP .C fstatfs() returns similar information for an open file. .PP The parameters for the .C statfs() and .C fstatfs() functions are as follows: .RS .TP 20 .I path is a pointer to a path name of any file within the mounted file system. .TP .I buf is a pointer to a .C statfs() structure, which is where the file system status information is stored. .TP .I fildes is a file descriptor for an open file, which is created with the successful completion of an .CR open() , .CR creat() , .CR dup() , .CR fcntl() , or .CR pipe() system call (see .IR open (2), .IR creat (2), .IR dup (2), .IR fcntl (2), or .IR pipe (2)). .RE .PP The .C statfs() structure contains the following members: .nf .IP .C "long f_bavail; /* free blocks available to non-superuser */ .C "long f_bfree; /* free blocks */ .C "long f_blocks; /* total blocks in file system */ .C "long f_bsize; /* fundamental file system block size in bytes */ .C "long f_ffree; /* free file nodes in file system */ .C "long f_files; /* total file nodes in file system */ .C "long f_type; /* type of info, zero for now */ .C "fsid_t f_fsid /* file system ID. f_fsid[1] is the file system .C " type; see sysfs(2) */ .fi .PP The fields .CR f_blocks , .CR f_bavail and .CR f_bfree are expressed in terms of blocks of size .CR f_bsize. .PP A .I file node is a structure in the file system hierarchy that describes a file. .PP Fields that are undefined for a particular file system are set to \(mi1. .SH RETURN VALUE .C statfs() and .C fstatfs() return 0 upon successful completion; otherwise, they return \(mi1 and set .C errno to indicate the error. .SH ERRORS If .C statfs() fails, .C errno is set to one of the following values: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of the path prefix. .TP .SM [EFAULT] .I buf or .I path point to an invalid address. .TP .SM [EIO] An I/O error occurred while reading from or writing to the file system. .TP .SM [ELOOP] Too many symbolic links are encountered during path-name translation. .TP .SM [ENAMETOOLONG] The length of the specified path name exceeds .C PATH_MAX bytes, or the length of a component of the path name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ENOENT] The named file does not exist (for example, .I path is null or a component of .I path does not exist). .TP .SM [ENOTDIR] A component of the path prefix is not a directory. .RE .PP If .C fstatfs() fails, .C errno is set to one of the following values: .RS .TP 20 .SM [EBADF] .I fildes is not a valid open file descriptor. .TP .SM [EFAULT] .I buf points to an invalid address. .TP .SM [EIO] An I/O error occurs while reading from or writing to the file system. .RE .SH AUTHOR .C statfs() and .C fstatfs() were developed by Sun Microsystems, Inc. .SH SEE ALSO df(1M), stat(2), ustat(2). .\" .\" index@\f4statfs()\f1, \f4fstatfs()\f1 \- get file system statistics@@@\f3statfs(2)\f1 .\" index@\f4fstatfs()\f1, \f4statfs()\f1 \- get file system statistics@@@\f3statfs(2)\f1 .\" index@\f1get file system statistics@@@\f3statfs(2)\f1 .\" index@\f1file system statistics, get@@@\f3statfs(2)\f1 .\" index@\f1statistics, get file system@@@\f3statfs(2)\f1 .\" .\" toc@\f3statfs(2)\f1:\0\0\f4statfs()\f1, \f4fstatfs()\f1@@@get file system statistics .\" toc@\f4fstatfs()\f1:\0\0get file system statistics@@@see \f3statfs(2)\f1 .\" .\" links@statfs.2 fstatfs.2 .\" $Header: statvfs.2,v 78.1 96/02/12 14:17:07 ssa Exp $ .TA s .TH statvfs 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME statvfs, fstatvfs \- get file system information .SH SYNOPSIS .PP .C "#include " .PP .C "#include " .PP .C "int statvfs (const char *path, struct statvfs *buf);" .PP .C "int fstatvfs (int fildes, struct statvfs *buf);" .SH DESCRIPTION .C statvfs() returns information about a mounted file system. .PP .C fstatvfs() returns similar information about an open file. .PP The parameters for the .C statvfs() and .C fstatvfs() functions are as follows: .RS .TP 20 .I path is a pointer to a path name of any file within the mounted file system. .TP .I buf is a pointer to a .C statvfs() structure, which is where the file system status information is stored. .TP .I fildes is a file descriptor for an open file, which is created with the successful completion of an .CR open() , .CR creat() , .CR dup() , .CR fcntl() , or .CR pipe() system call (see .IR open (2), .IR creat (2), .IR dup (2), .IR fcntl (2), or .IR pipe (2)). .RE .PP The .C statvfs() structure contains the following members: .nf .IP .C "ulong f_bsize; /* preferred file system block size */" .C "ulong f_frsize; /* fundamental file system block size */" .C "ulong f_blocks; /* total blocks of f_frsize on file system */" .C "ulong f_size; /* size of file system in f_frsize unit */" .C "ulong f_bfree; /* free blocks */" .C "ulong f_bavail; /* blocks available to non-superuser */" .C "long f_files; /* total file nodes in file system */" .C "long f_ffree; /* free file nodes in file system */" .C "long f_favail; /* file nodes available to non-superuser */" .C "long f_fsid; /* file system ID for file system */" .C " /* type; see sysfs(2) */" .C "char f_basetype[FSTYPSZ]; /* file system type name is null-terminated */" .C "long f_flag; /* bit mask of flags */" .C "long f_namemax /* maximum file name length */" .C "char f_fstr[32]; /* file system specific string */" .C "time_t f_time; /* Last time file system was written */" .PP The field f_basetype contains a null-terminated file-system-type name. .fi .PP The constant .C [FSTYPSZ] is defined in the header file .CR . .PP The following flags can be returned in the f_flag field: .RS .TP 20 .C ST_LARGEFILES File system is enabled for large files. .TP .C ST_RDONLY File system is read-only. .TP .C ST_NOSUID File system does not support .C setuid and .C setgid semantics. .TP .C ST_EXPORTED File system is exported (NFS). .TP .C ST_QUOTA Quotas are enabled on this file system. .RE .SH RETURN VALUE .C statvfs() and .C fstatvfs() return 0 upon successful completion; otherwise, they return -1 and set .C errno to indicate the error. .SH ERRORS If .C statvfs() fails, .C errno is set to one of the following values: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of the path prefix. .TP .SM [ELOOP] Too many symbolic links are encountered during path-name translation. .TP .SM [ENAMETOOLONG] The length of the specified path name exceeds .C PATH_MAX bytes, or the length of a component of the path name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ENOENT] The named file does not exist (for example, .I path is null or a component of .I path does not exist). .TP .SM [ENOTDIR] A component of the path prefix is not a directory. .RE .PP If .C fstatvfs() fails, .C errno is set to the following value: .RS .TP 20 .SM [EBADF] .I fildes is not a valid open file descriptor. .RE .PP When both .C statvfs() and .C fstatvfs() fail, .C errno is set to one of the following values: .RS .TP 20 .SM [EFAULT] .I buf points to an invalid address. .TP .SM [EIO] An I/O error occurred while reading from or writing to the file system. .RE .SH SEE ALSO df(1M), fstatfs(2), fstatvfs64(2), quotactl(2), stat(2), statfs(2), statvfs64(2), sysfs(2), ustat(2). .\" .\" index@\f4statvfs()\f1, \f4fstatvfs()\f1 \- get file status@@@\f3statvfs(2)\f1 .\" index@\f4fstatvfs()\f1, (\f4statvfs()\f1) \- get open file status@@@\f3statvfs(2)\f1 .\" index@\f1get file status@@@\f3statvfs(2)\f1 .\" index@\f1file, get file status@@@\f3statvfs(2)\f1 .\" index@\f1status, get file@@@\f3statvfs(2)\f1 .\" .\" toc@\f3statvfs(2)\f1:\0\0\f4statvfs()\f1, \f4fstatvfs()\f1@@@get file status .\" toc@\f4fstatvfs()\f1:\0\0get file status@@@see \f3statvfs(2)\f1 .\" .\" links@statvfs.2 fstatvfs.2 .\" $Header: fsync.2,v 72.5 94/11/14 15:24:04 ssa Exp $ .TA f .TH fsync 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fsync, fdatasync \- synchronize a file's in-core and on-disk states .SH SYNOPSIS .C "#include " .PP .C "int fsync(int fildes);" .PP .C "int fdatasync(int fildes);" .SH DESCRIPTION .C fsync() and .C fdatasync() cause all modified data and attributes of .I fildes 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. .C fsync() and .C fdatasync() apply to ordinary files, and apply to block special devices on systems which permit .SM I/O to block special devices. .PP .C fsync() and .C fdatasync() should be used by programs that require a file to be in a known state, such as when building a simple transaction facility. .PP .C fdatasync() causes all modified data and file attributes of .I fildes required to retrieve the data to be written to disk. .PP .C fsync() causes all modified data and all file attributes of .I fildes (including access time, modification time and status change time) to be written to disk. .PP Together, .C fsync() and .C fdatasync() constitute support for File Synchronization. .SH RETURN VALUE .C fsync() and .C fdatasync() return 0 on success or \(mi1 if an error occurs, and set .C errno to indicate the error. .SH ERRORS .IR fsync and .IR fdatasync fail if any of the following conditions are encountered: .RS .TP 15 .SM [EBADF] .I fildes is not a valid descriptor. .TP .SM [EINVAL] .I fildes refers to a file type to which .C fsync() or .C fdatasync() does not apply. .RE .SH WARNINGS The current implementation of these functions is inefficient for large files. .SH AUTHOR .C fsync() was developed by the the University of California, Berkeley and HP. .SH SEE ALSO fcntl(2), fcntl(5), open(2), select(2), sync(2), sync(1M), unistd(5). .SH STANDARDS CONFORMANCE .CR fsync() ": AES, SVID3, XPG3, XPG4, POSIX.4" .PP .CR fdatasync() ": POSIX.4" .\" .\" index@\f4fsync()\fP, \f4fdatasync()\fP \(mi synchronize a file's in-core state with its state on disk@@@\f3fsync(2)\f1 .\" index@synchronize a file's in-core state with its state on disk@@@\f3fsync(2)\f1 .\" index@file's in-core state with its state on disk, synchronize a@@@\f3fsync(2)\f1 .\" index@in-core state with its state on disk, synchronize a file's@@@\f3fsync(2)\f1 .\" index@state with its state on disk, synchronize a file's in-core@@@\f3fsync(2)\f1 .\" index@disk, synchronize a file's in-core state with its state on@@@\f3fsync(2)\f1 .\" .\" toc@\f3fsync(2)\f1:\0\0\f4fsync()\fP, \f4fdatasync()\fP@@@synchronize a file's in-core state with its state on disk .\" toc@\f4fdatasync()\fP:\0\0synchronize a file's in-core state with its state on disk@@@see \f3fsync(2)\f1 .\" .\" links@fsync.2 fdatasync.2 .\" .\" fileset_database@fsync.2 PROGRAMING-MAN .\" $Header: ftime.2,v 72.3 93/01/14 14:33:01 ssa Exp $ .TA f .TH ftime 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ftime \- get date and time more precisely .SH SYNOPSIS .C "#include " .PP .C "int ftime(struct timeb *tp);" .SH REMARKS This facility is provided for backwards compatibility with Version 7 systems. Either .C time() or .C gettimeofday() should be used in new programs. .SH DESCRIPTION .C ftime() fills in a structure pointed to by its argument, as defined by .RC < sys/timeb.h >: .nf .IP .C "/*" .C " * Structure returned by ftime system call" .C " */" .C "struct timeb {" .C " time_t time;" .C " unsigned short millitm;" .C " short timezone;" .C " short dstflag;" .C "};" .fi .PP The structure contains the time in seconds since 00:00:00 .SM UTC (Coordinated Universal Time), January 1, 1970, up to 1000 milliseconds of more-precise interval, the local timezone (measured in minutes of time westward from UTC), and a flag that, if nonzero, indicates that Daylight Saving time applies locally during the appropriate part of the year. Consult .IR gettimeofday (2) for more details on the meaning of the timezone field. .PP This function can be accessed by giving the .C -lV7 option to the .C ld command (see .IR ld (1)). .PP .C ftime() can fail for exactly the same reasons as .IR gettimeofday (2). .SH SEE ALSO date(1), gettimeofday(2), stime(2), time(2), ctime(3C). .SH WARNINGS The millisecond value usually has a granularity greater than one due to the resolution of the system clock. Depending on any granularity (particularly a granularity of one) renders code non-portable. .\" index@\f4ftime()\fP \(mi get date and time more precisely (Version 7 compatibility only)@@@\f3ftime(2)\f1 .\" index@get: date and time more precisely (Version 7 compatibility only)@@@\f3ftime(2)\f1 .\" index@date and time, get more precisely (Version 7 compatibility only)@@@\f3ftime(2)\f1 .\" index@time and date, get more precisely (Version 7 compatibility only)@@@\f3ftime(2)\f1 .\" .\" toc@\f3ftime(2)\f1:\0\0\f4ftime()\fP@@@get date and time more precisely .\" .\" fileset_database@ftime.2 PROGRAMING-MAN .\" $Header: truncate.2,v 78.1 96/02/12 14:20:55 ssa Exp $ .TA t .TH truncate 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ftruncate, truncate \- truncate a file to a specified length .SH SYNOPSIS .\" UX .C "#include " .PP .C "int ftruncate(int fildes, off_t length);" .PP .C "int truncate(const char *path, off_t length);" .\" ? .SH DESCRIPTION The .CR ftruncate() function causes the regular file referenced by .IR fildes to have a size of .IR length bytes. .PP The .CR truncate() function causes the regular file named by .IR path to have a size of .IR length bytes. .PP The effect of .CR ftruncate() and .CR truncate() on other types of files is unspecified. If the file previously was larger than .IR length , the extra data is lost. If it was previously shorter than .IR length, bytes between the old and new lengths are read as zeroes. With .CR ftruncate() , the file must be open for writing; for .CR truncate() , the process must have write permission for the file. .PP If the request would cause the file size to exceed the soft file size limit for the process, the request will fail and the implementation will generate the .CR SIGXFSZ signal for the process. .PP These functions do not modify the file offset for any open file descriptions associated with the file. On successful completion, if the file size is changed, these functions will mark for update the .IR st_ctime and .IR st_mtime fields of the file, and if the file is a regular file, the .CR S_ISUID and .CR S_ISGID bits of the file mode may be cleared. .SH RETURN VALUE Upon successful completion, .CR ftruncate() and .CR truncate() returns 0. Otherwise a \(mi1 is returned, and .CR errno is set to indicate the error. .SH ERRORS The .CR ftruncate() and .CR truncate() functions will fail if: .RS .TP 25 [EINTR] A signal was caught during execution. .TP [EINVAL] The .IR length argument was less than 0. .TP [EFBIG] or [EINVAL] The .IR length argument was greater than the maximum file size. .TP [EIO] An I/O error occurred while reading from or writing to a file system. .RE .PP. The .CR ftruncate() function will fail if: .RS .TP 25 [EBADF] or [EINVAL] The .IR fildes argument is not a file descriptor open for writing. .TP [EINVAL] The .IR fildes argument references a file that was opened without write permission. .RE .PP The .CR truncate() function will fail if: .RS .TP 25 [EACCES] A component of the .IR path prefix denies search permission, or write permission is denied on the file. .TP [EISDIR] The named file is a directory. .TP [ELOOP] Too many symbolic links were encountered in resolving .IR path . .TP [ENAMETOOLONG] The length of the specified pathname exceeds .CR PATH_MAX bytes, or the length of a component of the pathname exceeds .CR NAME_MAX bytes. .TP [ENOENT] A component of .CR path does not name an existing file or path is an empty string. .TP [ENOTDIR] A component of the .IR path prefix of path is not a directory. .TP [EROFS] The named file resides on a read\-only file system. .RE .PP The .CR truncate() function may fail if: .RS .TP 25 [ENAMETOOLONG] Pathname resolution of a symbolic link produced an intermediate result whose length exceeds .CR {PATH_MAX} . .SH SEE ALSO open(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .TA .TH ftruncate .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH SYNOPSIS .C "int truncate(const char *path, size_t length);" .PP .C "int ftruncate(int fildes, size_t length);" .SH ERRORS If truncate() fails, .CR errno is set to one of the following values: .RS .TP 15 [EACCES] MAC access is denied on the file. .TP [EDQUOT] The user's disk quota block limit has been reached for this file system. .TP [EFAULT] .IR path points outside the process's allocated address space. The reliable detection of this error is implementation dependent. .TP [EINVAL] .IR length was greater than the maximum file size. .TP [ETXTBSY] The file is a pure procedure (shared text) file that is being executed. .RE .PP If .CR ftruncate() fails, .CR errno is set to one of the following values: .RS .TP 15 [EDQUOT] The user's disk quota block limit has been reached for this file system. .RE .SH AUTHOR .CR truncate() was developed by the University of California, Berkeley. .SH SEE ALSO ftruncate64(2), open(2), truncate64(2). .SH STANDARDS CONFORMANCE truncate(): AES ftruncate(): AES, SVID3 .\" .\" index@\f4ftruncate()\f1 \- truncate a file to a specified length@@@\f3truncate(2)\f1 .\" index@\f4truncate()\f1 \- truncate a file to a specified length@@@\f3truncate(2)\f1 .\" index@\f1file: truncate a file to a specified length@@@\f3truncate(2)\f1 .\" .\" toc@\f3truncate(2)\f1:\0\0\f4ftruncate()\f1, \f4truncate()\f1@@@truncate a file to a specified length .\" toc@\f4ftruncate()\f1:\0\0truncate a file to a specified length@@@see \f3truncate(2)\f1 .\" .\" links@truncate.2 ftruncate.2 .\" $Header: getaccess.2,v 72.4 94/09/19 09:12:51 ssa Exp $ .TA g .TH getaccess 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getaccess \- get a user's effective access rights to a file .SH SYNOPSIS .C "#include " .PP .C "int getaccess(" .PD 0 .nf .IP .C "const char *path," .C "uid_t uid," .C "int ngroups," .C "const gid_t *gidset," .C "void *label," .C "void *privs" .PP .C ");" .PD .fi .SH DESCRIPTION .C getaccess() identifies the access rights (read, write, execute/search) a specific user .SM ID has to an existing file. .I path points to a path name of a file. If the call succeeds, it returns a value of zero or greater, representing the specified user's effective access rights (modes) to the file. The rights are expressed as the logical .SM OR of bits .RC ( R_OK , .CR W_OK , and .CR X_OK ) whose values are defined in the header .RC < unistd.h >. A return of zero means that access is denied. .PP The .I uid parameter is a user .SM ID. Special values, defined in .RC < sys/getaccess.h >, represent the calling process's effective, real, or saved user .SM ID: .RS .TP 15 .PD 0 .C UID_EUID Effective user .SM ID. .TP .C UID_RUID Real user .SM ID. .TP .C UID_SUID Saved user .SM ID. .PD .RE .PP .I ngroups is the number of group .SM IDs in .IR gidset , not to exceed .C NGROUPS_MAX + 1 .RC ( NGROUPS_MAX is defined in .RC < limits.h >). If the .I ngroups parameter is positive, the .I gidset parameter is an array of group .SM ID values to use in the check. If .I ngroups is a recognized negative value, .I gidset is ignored. Special negative values of .IR ngroups , defined in .RC < sys/getaccess.h >, represent various combinations of the process's effective, real, or saved user .SM ID and its supplementary groups list: .RS .TP 25 .PD 0 .C NGROUPS_EGID Use process's effective group .SM ID only. .TP .C NGROUPS_RGID Use process's real group .SM ID only. .TP .C NGROUPS_SGID Use process's saved group .SM ID only. .TP .C NGROUPS_SUPP Use process's supplementary groups only. .TP .C NGROUPS_EGID_SUPP Use process's effective group .SM ID plus supplementary groups. .TP .C NGROUPS_RGID_SUPP Use process's real group .SM ID plus supplementary groups. .TP .C NGROUPS_SGID_SUPP Use process's saved group .SM ID plus supplementary groups. .PD .RE .PP The .I label and .I privs parameters are placeholders for future extensions. For now, the values of these parameters must be .CR "(void *) 0" . .PP The access check rules for access control lists are described in .IR acl (5). In addition, the .C W_OK bit is cleared for files on read-only file systems or shared-text programs being executed. Note that as in .IR access (2), the .C X_OK bit is not turned off for shared-text programs open for writing because there is no easy way to know that a file open for writing is a shared-text program. .PP If the caller's user .SM ID is 0, or if it is .CR UID_EUID , .CR UID_RUID , or .C UID_SUID (see .RC < sys/getaccess.h >) and the process's respective user .SM ID is 0, .C R_OK and .C W_OK are always set except when .C W_OK is cleared for files on read-only file systems or shared-text programs being executed. .C X_OK is set if and only if the file is not a regular file or the execute bit is set in any of the file's .SM ACL entries. .PP .C getaccess() checks each directory component of .I path by first using the caller's effective user .SM ID, effective group .SM ID, and supplementary groups list, regardless of the user .SM ID specified. An error occurs, distinct from ``no access allowed,'' if the caller cannot search the path to the file. (In this case it is inappropriate for the caller to learn anything about the file.) .SS "Comparison of \f2access\f1(2) and \f2getaccess\f1(2)" The following table compares various attributes of .C access() and .CR getaccess() . .\" Separate tables for nroff and troff: .ifn \{.PP .nf \f3access()\fP \f3getaccess()\fP +=================================================================+ | checks all ACL entries | same | | (HFS File Systems only) | | +-----------------------------------------------------------------+ | uses real uid, real gid, and | uses specified uid and groups| | supplementary groups list | list; macros available | | | for typical values | +-----------------------------------------------------------------+ | checks specific mode value, | returns all mode bits, each | | returns succeed or fail | on or off | +-----------------------------------------------------------------+ | checks path to file using | same | | caller's effective ID | | +-----------------------------------------------------------------+ | W_OK false if shared-text | same | | file currently being executed | | +-----------------------------------------------------------------+ | W_OK false if file on | same | | read-only file system | | +-----------------------------------------------------------------+ | X_OK not modified for file | same | | currently open for writing | | +-----------------------------------------------------------------+ | R_OK and W_OK always true for | same | | superuser (except as above) | | +-----------------------------------------------------------------+ | X_OK always true for | X_OK true for super-user | | superuser | if file is not a regular | | | file OR execute is set in | | | any ACL entry | +-----------------------------------------------------------------+\} .fi .ift \{.PP .TS center box tab(:); cf4w(2.5i)|cf4w(2.5i) l|l. access():getaccess() = checks all ACL entries:same (HFS File Systems only) _ uses real uid, real gid, and : uses specified uid and groups list; supplementary groups list : macros available for typical values _ checks specific mode value, : returns all mode bits, each on or off returns succeed or fail _ checks path to file using caller's effective IDs:same _ W_OK false if shared-text file : same currently being executed _ \f4W_OK\fP false if file on : same read-only file system _ \f4X_OK\fP not modified for file:same currently open for writing _ \f4R_OK\fP and \f4W_OK\fP always true for superuser:same (except as above) _ \f4X_OK\fP always true for superuser: \f4X_OK\fP true for super-user if file is not a regular \&:file \f2or\fP execute is set in any \s-1ACL\s0 entry .TE\} .SH RETURN VALUE Upon successful completion, .C getaccess() returns a non-negative value representing the access rights of the specified user to the specified file. If an error occurs, a value of .C -1 is returned and .C errno is set to indicate the error. .SH ERRORS .C getaccess() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EACCES] A component of the .I path prefix denies search permission to the caller. .TP .SM [EFAULT] .I path or .I gidset points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP .SM [EINVAL] .I ngroups is invalid; .I ngroups is either zero, an unrecognized negative value, or a value larger than .C NGROUPS + 1. .TP .SM [EINVAL] .I gidset contains an invalid group .SM ID value. .TP .SM [EINVAL] The value of .I label or .I privs is not a null pointer. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the .I path name. .TP .SM [ENAMETOOLONG] The length of the specified path name exceeds .C PATH_MAX bytes, or the length of a component of the path name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ENOENT] The named file does not exist (for example, .I path is null or a component of .I path does not exist). .TP .SM [ENOTDIR] A component of the .I path prefix is not a directory. .TP .SM [EOPNOTSUPP] .CR getaccess () is not supported on some types of remote files. .SH EXAMPLES The following call determines the caller's effective access rights to file ``test,'' and succeeds if the user has read access: .nf .IP .C #include .C #include .IP .C int mode; .ift .ft 4 .ifn .ft 3 .ps +1 mode = getaccess ("test", UID_EUID, NGROUPS_EGID_SUPP, (int \(**) 0, (void \(**) 0, (void \(**) 0); .ft .ps .IP .C "if ((mode >= 0) && (mode & R_OK)) ..." .fi .PP Here is one way to test access rights to file .B /tmp/hold for user .SM ID .CR 23 , group .SM ID .CR 109 : .nf .IP .C "int gid = 109;" .C "int mode;" .IP .ift .ft 4 .ifn .ft 3 .ps +1 mode = getaccess ("/tmp/hold", 23, 1, & gid, (void \(**) 0, (void \(**) 0); .ft .ps .fi .PP Should the need arise, the following code builds a .I gidset that includes the process's effective group .SM ID: .nf .IP .C "#include " .IP .C "int gidset [NGROUPS_MAX + 1];" .C "int ngroups;" .IP .C "gidset [0] = getegid();" .C "ngroups = 1 + getgroups (NGROUPS_MAX, & gidset [1]);" .fi .SH AUTHOR .C getaccess() was developed by HP. .SH SEE ALSO access(2), chmod(2), getacl(2), setacl(2), stat(2), acl(5), unistd(5). .\" .\" index@\f4getaccess()\fP \(mi get a user's effective access rights to a file@@@\f3getaccess(2)\f1 .\" index@get a user's effective access rights to a file@@@\f3getaccess(2)\f1 .\" index@user's effective access rights to a file, get a@@@\f3getaccess(2)\f1 .\" index@effective access rights to a file, get a user's@@@\f3getaccess(2)\f1 .\" index@access rights to a file, get a user's effective@@@\f3getaccess(2)\f1 .\" index@rights to a file, get a user's effective access@@@\f3getaccess(2)\f1 .\" index@file, get a user's effective access rights to a@@@\f3getaccess(2)\f1 .\" .\" toc@\f3getaccess(2)\f1:\0\0\f4getaccess()\fP@@@get a user's effective access rights to a file .\" .\" fileset_database@getaccess.2 PROGRAMING-MAN .\" $Header: getacl.2,v 72.5 94/09/19 09:13:15 ssa Exp $ .TA g .TH getacl 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getacl, fgetacl \- get access control list (ACL) information (HFS File Systems only) .SH SYNOPSIS .C "#include " .PP .C "int getacl(" .nf .PD 0 .IP .C "const char *path," .C "int nentries," .C "struct acl_entry *acl" .PP .C ");" .PD .PP .C "int fgetacl(int fildes, int nentries, struct acl_entry *acl);" .fi .SH DESCRIPTION .C getacl() returns a complete listing of all .SM ACL entries .RI ( uid.gid , .IR mode ) in an existing file's access control list. .I path points to a path name of a file. .PP Similarly, .C fgetacl() returns a complete listing of all .SM ACL entries for an open file known by the file descriptor .IR fildes . .PP .I nentries is the number of entries being reported on, and is never more than the constant .C NACLENTRIES defined in .RC < sys/acl.h >. If .I nentries is non-zero, it must be at least as large as the number of entries in the file's .SM ACL, including base entries (see .IR setacl (2)). .C getacl() returns the number of entries in the file's .SM ACL, as well as the .SM ACL entries themselves in the array of structures .I acl declared by the calling program. .PP If .I nentries is zero, .C getacl() returns the number of entries in the file's .SM ACL, including base .SM ACL entries, and .I acl is ignored. .PP Entries are reported in groups of decreasing order of specificity (see .IR setacl (2)), then sorted in each group by user .SM ID and group .SM ID. The content of array entries beyond the number of defined entries for the file is undefined. .SH RETURN VALUE Upon successful completion, .C getacl() and .C fgetacl() return a non-negative value. If an error occurs, a value of \(mi1 is returned, and .CR errno is set to indicate the error. .SH ERRORS .C getacl() or .C fgetacl() fail to modify the .I acl array if any of the following is true: .RS .TP 15 .SM [ENOTDIR] A component of the .I path prefix is not a directory. .TP .SM [ENOENT] The named file does not exist (for example, .I path is null or a component of .I path does not exist). .TP .SM [EBADF] .I fildes is not a valid file descriptor. .TP .SM [EACCES] A component of the .I path prefix denies search permission. .TP .SM [EFAULT] .I path or a portion of .I acl to be written points outside the allocated address space of the process. .TP .SM [EINVAL] .I nentries is non-zero and less than the number of entries in the file's .SM ACL, or it is greater than .CR NACLENTRIES . .TP .SM [EOPNOTSUPP] .C getacl() is not supported on remote files by some networking services. .TP .SM [ENFILE] The system file table is full. .TP .SM [ENAMETOOLONG] The length of .I path exceeds .C PATH_MAX bytes, or the length of a component of .I path exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the .I path name. .RE .SH EXAMPLES The following call returns the number of entries in the .SM ACL on file .CR /users/bill/mcfile . .IP .C #include .IP .ift .ft 4 .ifn .ft 3 .ps +1 entries = getacl ("/users/bill/mcfile", 0, (struct acl_entry \(**) 0); .PP The following call returns in .I acl all entries in the .SM ACL on the file opened with file descriptor 5. .nf .IP .C #include .IP .C int nentries; .C struct acl_entry acl [NACLENTRIES]; .IP .C entries = fgetacl (5, NACLENTRIES, acl); .fi .SH DEPENDENCIES .C getacl() and .C fgetacl() are only supported on HFS file system on standard HP-UX operating system. .SH AUTHOR .C getacl() and .C fgetacl() were developed by HP. .SH SEE ALSO access(2), chmod(2), getaccess(2), setacl(2), stat(2), unistd(5). .\" .\" index@\f4getacl()\fP, \f4fgetacl()\fP \(mi get access control list (\s-1ACL\s+1) information@@@\f3getacl(2)\f1 .\" index@\f4fgetacl()\fP \(mi get access control list (\s-1ACL\s+1) information@@@\f3getacl(2)\f1 .\" index@get access control list (\s-1ACL\s+1) information@@@\f3getacl(2)\f1 .\" index@access control list (\s-1ACL\s+1) information, get@@@\f3getacl(2)\f1 .\" .\" toc@\f3getacl(2)\f1:\0\0\f4getacl()\fP, \f4fgetacl()\fP@@@get access control list (\s-1ACL\s+1) information .\" toc@\f4fgetacl()\fP: get access control list (\s-1ACL\s+1) information@@@see \f3getacl(2)\f1 .\" .\" links@getacl.2 fgetacl.2 .\" .\" fileset_database@getacl.2 PROGRAMING-MAN .\" $Header: getaudid.2,v 78.2 96/01/19 20:11:19 ssa Exp $ .TA g .TH getaudid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getaudid \- get the audit ID (aid) for the current process .SH SYNOPSIS .C "#include " .PP .C "int getaudid(void);" .SH DESCRIPTION .C getaudid() returns the audit ID .RI ( \|aid\| ) for the current process. This call is restricted to the super-user. .SH RETURN VALUE Upon successful completion, the audit .SM ID is returned; otherwise, a .C -1 is returned. .SH ERRORS .C getaudid() fails if the following is true: .TP 15 .SM [EPERM] The caller is not super-user. .SH AUTHOR .C getaudid() was developed by HP. .SH SEE ALSO setaudid(2). .\" index@\f4getaudid()\fP \(mi get audit \s-1ID\s+1 (\f4aid()\fP) for current process@@@\f3getaudid(2)\f1 .\" index@get audit \s-1ID\s+1 (\f4aid()\fP) for current process@@@\f3getaudid(2)\f1 .\" index@audit \s-1ID\s+1 (\f4aid()\fP) for current process, get@@@\f3getaudid(2)\f1 .\" index@current process, get audit \s-1ID\s+1 (\f4aid()\fP) for@@@\f3getaudid(2)\f1 .\" index@process, get audit \s-1ID\s+1 (\f4aid()\fP) for current@@@\f3getaudid(2)\f1 .\" toc@\f3getaudid(2)\f1:\0\0\f4getaudid()\fP@@@get the audit \s-1ID\s+1 (\f4aid()\fP) for the current process .\" .\" $Header: getaudproc.2,v 72.3 93/01/14 14:33:15 ssa Exp $ .TA g .TH getaudproc 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getaudproc \- get the audit process flag for the calling process .SH SYNOPSIS .C "#include " .PP .C "int getaudproc(void);" .SH DESCRIPTION .C getaudproc() returns the audit process flag for the calling process. The audit process flag .RI ( u_audproc ) determines whether the process run by a given user should be audited. The process is audited if the returned flag is 1. If the returned flag is 0, the process is not audited. This call is restricted to the super-user. .SH RETURN VALUE Upon successful completion, the audit process flag is returned; otherwise, a .C -1 is returned and .C errno is set to indicate the error. .SH ERRORS .C getaudproc() fails if the following is true: .TP 15 .SM [EPERM] The caller is not the super-user. .SH AUTHOR .C getaudproc() was developed by HP. .SH SEE ALSO setaudproc(2). .\" index@\f4getaudproc()\fP \(mi get audit process flag for calling process@@@\f3getaudproc(2)\f1 .\" index@get audit process flag for calling process@@@\f3getaudproc(2)\f1 .\" index@audit process flag for calling process, get@@@\f3getaudproc(2)\f1 .\" index@flag for calling process, get audit process@@@\f3getaudproc(2)\f1 .\" index@calling process, get audit process flag for@@@\f3getaudproc(2)\f1 .\" index@process, get audit process flag for calling@@@\f3getaudproc(2)\f1 .\" toc@\f3getaudproc(2)\f1:\0\0\f4getaudproc()\fP@@@get audit process flag for calling process .\" .\" fileset_database@getaudproc.2 PROGRAMING-MAN .\" $Header: getcontext.2,v 76.1 95/07/07 14:35:46 ssa Exp $ .TA g .TH getcontext 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getcontext, setcontext \- get and set current user context .SH SYNOPSIS .\" UX .PP .C "#include " .PP .C "int getcontext(ucontext_t *ucp);" .PP .C "int setcontext(const ucontext_t *ucp);" .\" ? .SH DESCRIPTION The .CR getcontext() function initialises the structure pointed to by .IR ucp to the current user context of the calling process. The .IR ucontext_t type that .IR ucpa points to defines the user context and includes the contents of the calling process' machine registers, the signal mask, and the current execution stack. .PP The .CR setcontext() function restores the user context pointed to by .IR ucp . A successful call to .CR setcontext() does not return; program execution resumes at the point specified by the .IR ucp argument passed to .CR setcontext() . The .IR ucp argument should be created either by a prior call to .CR getcontext() , or by being passed as an argument to a signal handler. If the .IR ucp argument was created with .CR getcontext() , program execution continues as if the corresponding call of .CR getcontext() had just returned. If the .IR ucp argument was created with .CR makecontext() , program execution continues with the function passed to .CR makecontext() . When that function returns, the process continues as if after a call to .CR setcontext() with the .IR ucp argument that was input to .CR makecontext() . If the .IR ucp argument was passed to a signal handler, program execution continues with the program instruction following the instruction interrupted by the signal. If the .IR uc_link member of the .CR ucontext_t structure pointed to by the .IR ucp argument is equal to 0, then this context is the main context, and the process will exit when this context returns. The effects of passing a .IR ucp argument obtained from any other source are unspecified. .PP .SH RETURN VALUE On successful completion, .CR setcontext() does not return and .CR getcontext() returns 0. Otherwise, a value of \(mi1 is returned. .SH ERRORS No errors are defined. .SH APPLICATION USAGE When a signal handler is executed, the current user context is saved and a new context is created. If the process leaves the signal handler via .CR longjmp() , then it is unspecified whether the context at the time of the corresponding .CR setjmp() call is restored and thus whether future calls to .CR getcontext() will provide an accurate representation of the current context, since the context restored by .CR longjmp() may not contain all the information that .CR setcontext() requires. Signal handlers should use .CR siglongjmp() or .CR setcontext() instead. .PP Portable applications should not modify or access the .IR uc_mcontext member of .IR ucontext_t . A portable application cannot assume that context includes any process\-wide static data, possibly including .CR errno . Users manipulating contexts should take care to handle these explicitly when required. .SH SEE ALSO bsd_signal(), makecontext(), setjmp(), sigaction(), sigaltstack(), sigprocmask(), sigsetjmp(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4getcontext()\f1 \- get and set current user context@@@\f3getcontext(2)\f1 .\" index@\f4setcontext()\f1 \- get and set current user context@@@\f3getcontext(2)\f1 .\" index@\f1get and set current user context@@@\f3getcontext(2)\f1 .\" index@\f1set and get current user context@@@\f3getcontext(2)\f1 .\" index@\f1current user context, get and set@@@\f3getcontext(2)\f1 .\" index@\f1user context, get and set current@@@\f3getcontext(2)\f1 .\" .\" toc@\f3getcontext(2)\f1:\0\0\f4getcontext()\f1, \f4setcontext()\f1@@@get and set current user context .\" toc@\f4setcontext()\f1:\0\0get and set current user context@@@see \f3getcontext(2)\f1 .\" .\" links@getcontext.2 setcontext.2 .\" $Header: getdirentri.2,v 72.7 94/09/21 11:02:15 ssa Exp $ .TA g .TH getdirentries 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getdirentries() \- get entries from a directory in a file-system-independent format .SH SYNOPSIS .CR "#include " .nf .PP .CR "int getdirentries( .CR " int fildes," .CR " struct direct *buf," .CR " size_t nbytes," .CR " off_t *basep" .CR ");" .fi .SH DESCRIPTION The .CR getdirentries() system call places directory entries from the directory referenced by the file descriptor .I fildes into the buffer pointed to by .IR buf , in a file-system-independent format. Up to .I nbytes of data are transferred. .I nbytes must be greater than or equal to the block size associated with the file; see .C st_blksize in .IR stat (2). (Smaller block sizes can cause errors on certain file systems.) .I nbytes must be less than or equal to 65536 (64K). .PP The data in the buffer consists of a series of .CR direct structures, each containing the following entries: .nf .IP .C "unsigned long d_fileno;" .C "unsigned short d_reclen;" .C "unsigned short d_namlen;" .C "char d_name[MAXNAMLEN + 1];" .fi .PP The .CR d_fileno entry is a number unique for each distinct file in the file system. Files linked by hard links (see .IR link (2)) have the same .CR d_fileno . The .CR d_reclen entry identifies the length, in bytes, of the directory record. The .CR d_name entry contains a null-terminated file name. The .CR d_namlen entry specifies the length of the file name. Thus the actual size of .CR d_name can vary from 2 to .CR MAXNAMLEN + 1. Note that the .CR direct structures in the buffer are not necessarily tightly packed. The .CR d_reclen entry must be used as an offset from the beginning of a .CR direct structure to the next structure, if any. .PP The return value of the system call is the actual number of bytes transferred. The current position pointer associated with .I fildes is set to point to the next block of entries. The pointer is not necessarily incremented by the number of bytes returned by .CR getdirentries() . If the value returned is zero, the end of the directory has been reached. .PP The current position pointer is set and retrieved by .CR lseek() ; see .IR lseek (2). .CR getdirentries() writes the position of the block read into the location pointed to by .IR basep . The current position pointer can be set safely only to a value previously returned by .CR lseek() , to a value previously returned in the location pointed to by .IR basep , or to zero. Any other manipulation of the position pointer causes undefined results. .SH RETURN VALUE .CR getdirentries() returns the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the number of bytes actually transferred. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .SH ERRORS If .CR getdirentries() fails, .CR errno is set to one of the following values: .RS .TP 15 [EBADF] .I fildes is not a valid file descriptor open for reading. .TP [EFAULT] Either .I buf or .I basep points outside the allocated address space. .TP [EINTR] A read from a slow device was interrupted by the delivery of a signal before any data arrived. .TP [EINVAL] .I nbytes is greater than the size of the .CR direct structure pointed to by .IR buf . .TP [EINVAL] .I nbytes is greater than 65536 or is smaller than the size of a single directory entry. .TP [EIO] An I/O error occurred while reading from or writing to the file system. .RE .SH AUTHOR .CR getdirentries() was developed by Sun Microsystems, Inc. .SH SEE ALSO lseek(2), open(2). .\" .\" toc@\f3getdirentries(2)\f1:\0\0\f4getdirentries()\f1@@@get entries from a directory in a file-system-independent format .\" .\" index@\f4getdirentries()\f1 \- get entries from a directory in a file-system-independent format@@@\f3getdirentries(2)\f1 .\" index@directory, get entries in a file-system-independent format@@@\f3getdirentries(2)\f1 .\" index@entries from a directory, get in a file-system-independent format@@@\f3getdirentries(2)\f1 .\" index@get entries from a directory in a file-system-independent format@@@\f3getdirentries(2)\f1 .\" $Header: getdomainna.2,v 72.5 94/07/05 17:44:12 ssa Exp $ .TA g .TH getdomainname 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getdomainname, setdomainname \- get/set name of current Network Information Service domain .SH SYNOPSIS .C "int getdomainname(char *name, int namelen);" .PP .C "int setdomainname(char *name, int namelen);" .SH DESCRIPTION .C getdomainname() returns the name of the Network Information Service (NIS) domain for the current processor, as previously set by .CR setdomainname() . The parameter .I namelen specifies the size of the .I name array. The returned value is null-terminated unless the area pointed to by .I name is not large enough to hold the domain name plus the null byte. In this case, only the .I namelen number of bytes is returned. .PP .C setdomainname() sets the domain of the host machine to .IR name , which has a length of .IR namelen . This call is restricted to the superuser and is normally used only when the system is booted. .PP These Network Information Service domains enable two distinct networks with common host names to merge. Each network is distinguished by having a different domain name. Currently, only the Network Information Service uses these domains. .SH RETURN VALUE If the call succeeds, a value of 0 is returned. If the call fails, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS If .C getdomainname() or .C setdomainname() fail, .CR errno is set to one of the following values: .RS .TP 15 .SM [EFAULT] .I name points outside the accessible address space. .TP 15 .SM [EPERM] The caller is not superuser. This error only applies to .CR setdomainname() . .RE .SH WARNINGS The length of the .I name array should be at least 65; NIS domain names can be up to 64 characters long. .PP NIS servers use the NIS domain name as the name of a subdirectory of .CR /var/yp . Since the NIS domain name can be as long as 64 characters, the domain name set with .C setdomainname() can exceed the maximum file name length allowed on the local file system. If that length is exceeded, the name of the subdirectory is the truncated NIS domain name. .SH AUTHOR .I getdomainname was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), ypserv(1M), ypfiles(4). .\" .\" index@\f4getdomainname()\f1 \- get name of current NIS domain@@@\f3getdomainname(2)\f1 .\" index@\f1get name of current NIS domain@@@\f3getdomainname(2)\f1 .\" index@\f1set name of current NIS domain@@@\f3getdomainname(2)\f1 .\" index@\f1NIS domain, get or set name of current@@@\f3getdomainname(2)\f1 .\" index@\f1domain, get or set name of current NIS@@@\f3getdomainname(2)\f1 .\" index@\f1name of current NIS domain, get or set@@@\f3getdomainname(2)\f1 .\" index@\f4setdomainname()\f1 \- set name of current NIS domain@@@\f3getdomainname(2)\f1 .\" .\" toc@\f3getdomainname(2)\f1:\0\0\f4getdomainname()\f1, \f4setdomainname()\f1@@@get/set name of current NIS domain .\" .\" links@getdomainna.2 setdomainna.2 .\" $Header: getuid.2,v 74.1 95/05/10 21:05:10 ssa Exp $ .TA g .TH getuid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getuid, geteuid, getgid, getegid \- get real user, effective user, real group, and effective group \s-1ID\s0s .SH SYNOPSIS .C "#include " .PP .C "uid_t getuid(void);" .PP .C "uid_t geteuid(void);" .PP .C "gid_t getgid(void);" .PP .C "gid_t getegid(void);" .SH DESCRIPTION The following functions return the information indicated: .RS .TP 18 .C getuid() Real-user-\c .SM ID of the calling process. .TP .C geteuid() Effective-user-\c .SM ID of the calling process. .TP .C getgid() Real-group-\c .SM ID of the calling process. .TP .C getegid() Effective-group-\c .SM ID of the calling process. .RE .PP No means is available for ascertaining the saved-user-\c .SM ID or saved-group-\c .SM ID of a process. .SH SEE ALSO setuid(2). .SH STANDARDS CONFORMANCE .CR getuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getegid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR geteuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4getuid()\fP \(mi get real user \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\f4geteuid()\fP \(mi get effective user \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\f4getgid()\fP \(mi get real group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\f4getegid()\fP \(mi get effective group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@get: real or effective user or group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\s-1ID\s+1, get real or effective user or group@@@\f3getuid(2)\f1 .\" index@user \s-1ID\s+1, get real or effective@@@\f3getuid(2)\f1 .\" index@group \s-1ID\s+1: get real or effective group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@real or effective user or group \s-1ID\s+1, get@@@\f3getuid(2)\f1 .\" index@effective or real user or group \s-1ID\s+1, get@@@\f3getuid(2)\f1 .\" .\" toc@\f3getuid(2)\f1:\0\0\f4getuid()\fP, \f4geteuid()\fP, \n\f4getgid()\fP, \f4getegid()\fP@@@get real user, effective user, real group, and effective group \s-1ID\s+1s .\" toc@\f4geteuid()\fP:\0\0get effective user group \s-1ID\s+1@@@see \f3getuid(2)\f1 .\" toc@\f4getgid()\fP:\0\0get real group \s-1ID\s+1@@@see \f3getuid(2)\f1 .\" toc@\f4getegid()\fP:\0\0get effective group \s-1ID\s+1@@@see \f3getuid(2)\f1 .\" .\" links@getuid.2 geteuid.2 .\" links@getuid.2 getgid.2 .\" links@getuid.2 getegid.2 .\" .\" fileset_database@getuid.2 PROGRAMING-MAN .\" $Header: getuid.2,v 74.1 95/05/10 21:05:10 ssa Exp $ .TA g .TH getuid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getuid, geteuid, getgid, getegid \- get real user, effective user, real group, and effective group \s-1ID\s0s .SH SYNOPSIS .C "#include " .PP .C "uid_t getuid(void);" .PP .C "uid_t geteuid(void);" .PP .C "gid_t getgid(void);" .PP .C "gid_t getegid(void);" .SH DESCRIPTION The following functions return the information indicated: .RS .TP 18 .C getuid() Real-user-\c .SM ID of the calling process. .TP .C geteuid() Effective-user-\c .SM ID of the calling process. .TP .C getgid() Real-group-\c .SM ID of the calling process. .TP .C getegid() Effective-group-\c .SM ID of the calling process. .RE .PP No means is available for ascertaining the saved-user-\c .SM ID or saved-group-\c .SM ID of a process. .SH SEE ALSO setuid(2). .SH STANDARDS CONFORMANCE .CR getuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getegid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR geteuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4getuid()\fP \(mi get real user \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\f4geteuid()\fP \(mi get effective user \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\f4getgid()\fP \(mi get real group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\f4getegid()\fP \(mi get effective group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@get: real or effective user or group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\s-1ID\s+1, get real or effective user or group@@@\f3getuid(2)\f1 .\" index@user \s-1ID\s+1, get real or effective@@@\f3getuid(2)\f1 .\" index@group \s-1ID\s+1: get real or effective group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@real or effective user or group \s-1ID\s+1, get@@@\f3getuid(2)\f1 .\" index@effective or real user or group \s-1ID\s+1, get@@@\f3getuid(2)\f1 .\" .\" toc@\f3getuid(2)\f1:\0\0\f4getuid()\fP, \f4geteuid()\fP, \n\f4getgid()\fP, \f4getegid()\fP@@@get real user, effective user, real group, and effective group \s-1ID\s+1s .\" toc@\f4geteuid()\fP:\0\0get effective user group \s-1ID\s+1@@@see \f3getuid(2)\f1 .\" toc@\f4getgid()\fP:\0\0get real group \s-1ID\s+1@@@see \f3getuid(2)\f1 .\" toc@\f4getegid()\fP:\0\0get effective group \s-1ID\s+1@@@see \f3getuid(2)\f1 .\" .\" links@getuid.2 geteuid.2 .\" links@getuid.2 getgid.2 .\" links@getuid.2 getegid.2 .\" .\" fileset_database@getuid.2 PROGRAMING-MAN .\" $Header: getevent.2,v 72.3 93/01/14 14:33:18 ssa Exp $ .TA g .TH getevent 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getevent \- get events and system calls that are currently being audited .SH SYNOPSIS .C "#include " .PP .C "int getevent(" .PD 0 .nf .IP .C "struct aud_type *a_syscall," .C "struct aud_event_tbl *a_event" .PP .C ");" .PD .SH DESCRIPTION .C getevent() gets the events and system calls being audited. The events are returned in a table pointed to by .IR a_event . The system calls are returned in a table pointed to by .IR a_syscall . This call is restricted to the super-user. .SH RETURN VALUE Upon successful completion, a value of 0 is returned; otherwise, a \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .C getevent() fails if the following is true: .TP 15 .SM [EPERM] The caller is not super-user. .SH AUTHOR .C getevent() was developed by HP. .SH SEE ALSO setevent(2), audevent(1M). .\" .\" index@\f4getevent()\fP \(mi get events and system calls currently being audited@@@\f3getevent(2)\f1 .\" index@audit: get events and system calls currently being audited@@@\f3getevent(2)\f1 .\" index@get events and system calls currently being audited@@@\f3getevent(2)\f1 .\" index@events and system calls currently being audited, get@@@\f3getevent(2)\f1 .\" index@system calls and events currently being audited, get@@@\f3getevent(2)\f1 .\" .\" toc@\f3getevent(2)\f1:\0\0\f4getevent()\fP@@@get events and system calls currently being audited .\" .\" fileset_database@getevent.2 PROGRAMING-MAN .\" $Header: getfh.2,v 72.5 94/09/19 09:33:24 ssa Exp $ .TA g .TH getfh 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getfh() \- return file handle for file on remote node .SH SYNOPSIS .nf .C #include .C #include .C #include .C #include .PP .C "int getfh(char *path, fhandle_t *fhp);" .fi .SH DESCRIPTION The .CR getfh() system call returns a file handle in the .CR struct pointed to by .I fhp for the file pointed to by .IR path . This information is used to perform an NFS mount for a remote node. .CR getfh() is executed on the remote node; results are passed back to the program doing the NFS mount. The caller should never examine the file handle contents. The file handle only identifies a file to the node that produced the file handle. (The term "file handle" refers to an NFS concept.) .PP The effective user ID of the calling process must be superuser. .SH RETURN VALUE .CR getfh() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR getfh() fails, .CR errno is set to one of the following values. .RS .TP 15 [EINVAL] Invalid argument, or the file or directory has not been exported by .CR exportfs (see .IR exportfs (1M)). .TP [ENOENT] File or directory specified by .I path does not exist. .TP [EPERM] The effective user ID is not superuser. .TP [EREMOTE] The file or directory specified by .I path is a remote file or directory. .RE .SH WARNINGS This call should be used only by HP-supplied commands and is not recommended for use by non-HP-supplied programs. .SH AUTHOR .CR getfh() was developed by Sun Microsystems, Inc. .SH SEE ALSO exportfs(1M), mount(1M), vfsmount(2). .\" .\" index@\f4getfh()\f1 \- get file handle for file on remote node@@@\f3getfh(2)\f1 .\" index@get file handle for file on remote node@@@\f3getfh(2)\f1 .\" index@get file handle for file on remote node, get@@@\f3getfh(2)\f1 .\" index@file on remote node, get file handle for@@@\f3getfh(2)\f1 .\" index@remote node, get file handle for file on@@@\f3getfh(2)\f1 .\" .\" toc@\f3getfh(2)\f1:\0\0\f4getfh()\f1@@@get file handle for file on remote node. .\" .\" fileset_database@getfh.2 PROGRAMING-MAN .\" $Header: getuid.2,v 74.1 95/05/10 21:05:10 ssa Exp $ .TA g .TH getuid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getuid, geteuid, getgid, getegid \- get real user, effective user, real group, and effective group \s-1ID\s0s .SH SYNOPSIS .C "#include " .PP .C "uid_t getuid(void);" .PP .C "uid_t geteuid(void);" .PP .C "gid_t getgid(void);" .PP .C "gid_t getegid(void);" .SH DESCRIPTION The following functions return the information indicated: .RS .TP 18 .C getuid() Real-user-\c .SM ID of the calling process. .TP .C geteuid() Effective-user-\c .SM ID of the calling process. .TP .C getgid() Real-group-\c .SM ID of the calling process. .TP .C getegid() Effective-group-\c .SM ID of the calling process. .RE .PP No means is available for ascertaining the saved-user-\c .SM ID or saved-group-\c .SM ID of a process. .SH SEE ALSO setuid(2). .SH STANDARDS CONFORMANCE .CR getuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getegid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR geteuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4getuid()\fP \(mi get real user \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\f4geteuid()\fP \(mi get effective user \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\f4getgid()\fP \(mi get real group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\f4getegid()\fP \(mi get effective group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@get: real or effective user or group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\s-1ID\s+1, get real or effective user or group@@@\f3getuid(2)\f1 .\" index@user \s-1ID\s+1, get real or effective@@@\f3getuid(2)\f1 .\" index@group \s-1ID\s+1: get real or effective group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@real or effective user or group \s-1ID\s+1, get@@@\f3getuid(2)\f1 .\" index@effective or real user or group \s-1ID\s+1, get@@@\f3getuid(2)\f1 .\" .\" toc@\f3getuid(2)\f1:\0\0\f4getuid()\fP, \f4geteuid()\fP, \n\f4getgid()\fP, \f4getegid()\fP@@@get real user, effective user, real group, and effective group \s-1ID\s+1s .\" toc@\f4geteuid()\fP:\0\0get effective user group \s-1ID\s+1@@@see \f3getuid(2)\f1 .\" toc@\f4getgid()\fP:\0\0get real group \s-1ID\s+1@@@see \f3getuid(2)\f1 .\" toc@\f4getegid()\fP:\0\0get effective group \s-1ID\s+1@@@see \f3getuid(2)\f1 .\" .\" links@getuid.2 geteuid.2 .\" links@getuid.2 getgid.2 .\" links@getuid.2 getegid.2 .\" .\" fileset_database@getuid.2 PROGRAMING-MAN .\" $Header: getgroups.2,v 72.4 94/11/14 15:24:06 ssa Exp $ .TA g .TH getgroups 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getgroups \- get group access list .SH SYNOPSIS .C "#include " .PP .C "int getgroups(int ngroups, gid_t gidset[\|]);" .SH DESCRIPTION .C getgroups() gets the current group access list of the user process and stores it in the array .IR gidset . The parameter .I ngroups indicates the number of entries which may be placed in .I gidset. No more than .CR NGROUPS , as defined in .RC < sys/param.h >, is ever returned. .PP As a special case, if the .I ngroups argument is zero, .C getgroups() returns the number of group entries for the process. In this case, the array pointed to by the .I gidset argument is not modified. .SH EXAMPLES The following call to .IR getgroups (2) retrieves the group access list of the calling process and stores the group ids in array mygidset: .nf .IP .C "int ngroups = \s-1NGROUPS\s0;" .C "gid_t mygidset[\s-1NGROUPS\s0];" .C "int ngrps; " .IP .C "ngrps = getgroups (ngroups, mygidset);" .fi .SH RETURN VALUE If successful, .C getgroups() returns a non-negative value indicating the number of elements returned in .IR gidset . If an error occurs, a value of \(mi1 is returned and .C errno is set to indicate the type of error. .SH ERRORS .C getgroups() fails if any of the following conditions are encountered: .TP 15 .SM [EFAULT] .I gidset specifies an invalid address. The reliable detection of this error is implementation dependent. .TP 15 .SM [EINVAL] The argument .I ngroups is not zero and is less than the number of groups in the current group access list of the process. .SH AUTHOR .C getgroups() was developed by .SM HP and the University of California, Berkeley .SH SEE ALSO setgroups(2), initgroups(3C) .SH STANDARDS CONFORMANCE .CR getgroups() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4getgroups()\fP \(mi get group access list@@@\f3getgroups(2)\f1 .\" index@group access list: get group access list@@@\f3getgroups(2)\f1 .\" index@access list, get group@@@\f3getgroups(2)\f1 .\" index@list, get group access@@@\f3getgroups(2)\f1 .\" .\" toc@\f3getgroups(2)\f1:\0\0\f4getgroups()\fP@@@get group access list .\" .\" fileset_database@getgroups.2 PROGRAMING-MAN .\" $Header: gethostid.2,v 76.2 95/07/07 14:39:26 ssa Exp $ .TA g .TH gethostid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gethostid \- get an identifier for the current host .SH SYNOPSIS .\" UX .PP .C "#include " .PP .C "long gethostid(void);" .\" ? .SH DESCRIPTION The .CR gethostid() function retrieves a 32\-bit identifier for the current host. .SH RETURN VALUE Upon successful completion, .CR gethostid() returns an identifier for the current host. .SH ERRORS No errors are defined. .SH APPLICATION USAGE X/Open does not define the domain in which the return value is unique. .SH SEE ALSO random(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4gethostid()\f1 \- get an identifier for the current host@@@\f3gethostid(2)\f1 .\" index@\f1get an identifier for the current host@@@\f3gethostid(2)\f1 .\" index@\f1identifier, get for the current host@@@\f3gethostid(2)\f1 .\" index@\f1current host, get an identifier for@@@\f3gethostid(2)\f1 .\" .\" toc@\f3gethostid(2)\f1:\0\0\f4gethostid()\f1@@@get an identifier for the current host .\" $Header: gethostname.2,v 72.3 93/01/14 14:33:31 ssa Exp $ .TA g .TH gethostname 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gethostname \- get name of current host .SH SYNOPSIS .C "#include " .PP .C "int gethostname(char *hostname, size_t size);" .SH DESCRIPTION .C gethostname() returns in the array to which .I hostname points, the standard host name for the current processor as set by .C sethostname() (see .IR sethostname (2)). .I size specifies the length of the .I hostname array. .I hostname is null-terminated unless insufficient space is provided. .SH RETURN VALUE .C gethostname() returns 0 if successful. Otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C gethostname() can fail if the following is true: .TP 15 .SM [EFAULT] .I hostname points to an illegal address. The reliable detection of this error is implementation dependent. .SH AUTHOR .C gethostname() was developed by the University of California, Berkeley. .SH SEE ALSO hostname(1), uname(1), sethostname(2), uname(2). .\" index@\f4gethostname()\fP \(mi get name of current host@@@\f3gethostname(2)\f1 .\" index@get: name of current host@@@\f3gethostname(2)\f1 .\" index@name: get name of current host@@@\f3gethostname(2)\f1 .\" index@current host, get name of@@@\f3gethostname(2)\f1 .\" index@host, current, get name of@@@\f3gethostname(2)\f1 .\" .\" toc@\f3gethostname(2)\f1:\0\0\f4gethostname()\fP@@@get name of current host .\" .\" fileset_database@gethostname.2 PROGRAMING-MAN .\" $Header: getitimer.2,v 76.1 95/07/07 14:40:29 ssa Exp $ .TA g .TH getitimer 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getitimer, setitimer \- get/set value of interval timer .SH SYNOPSIS .C "#include " .PP .C "int getitimer(int which, struct itimerval *value);" .PP .C "int setitimer(" .PD 0 .nf .IP .C "int which," .C "const struct itimerval *value," .C "struct itimerval *ovalue .PP .C ");" .PD .SH DESCRIPTION The .CR getitimer() function stores the current value of the timer specified by which into the structure pointed to by value. The .CR setitimer() function sets the timer specified by .IR which to the value specified in the structure pointed to by value, and if .IR ovalue is not a null pointer, stores the previous value of the timer in the structure pointed to by .IR ovalue. .PP A timer value is defined by the .IR itimerval structure. If .IR it_value is non-zero, it indicates the time to the next timer expiration. If .IR it_interval is non- zero, it specifies a value to be used in reloading .IR it_value when the timer expires. Setting .IR it_value to 0 disables a timer, regardless of the value of .IR it_interval . Setting .IR it_interval to 0 disables a timer after its next expiration (assuming .IR it_value is non-zero). .PP Implementations may place limitations on the granularity of timer values. For each interval timer, if the requested timer value requires a finer granularity than the implementation supports, the actual timer value will be rounded up to the next supported value. .PP An XSI-conforming implementation provides each process with at least three interval timers, which are indicated by the .IR which argument: .RS .TP 25 .C ITIMER_REAL Decrements in real time. A .CR SIGALRM signal is delivered when this timer expires. .TP .C ITIMER_VIRTUAL Decrements in process virtual time. It runs only when the process is executing. A .CR SIGVTALRM signal is delivered when it expires. .TP .C ITIMER_PROF Decrements both in process virtual time and when the system is running on behalf of the process. It is designed to be used by interpreters in statistically profiling the execution of interpreted programs. .RE .PP The interaction between .CR setitimer() and any of .CR alarm() , .CR sleep() or .CR usleep() is unspecified. .SH RETURN VALUE Upon successful completion, .CR getitimer() or .CR setitimer() returns 0. Otherwise, -1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR setitimer() function will fail if: .RS .TP 15 [EINVAL] The value argument is not in canonical form.(In canonical form, the number of microseconds is a non-negative integer less than 1,000,000 and the number of seconds is a non-negative integer.) .RE .PP The .CR getitimer() and .CR setitimer() functions may fail if: .RS .TP 15 [EINVAL] The which argument is not recognised. .SH SEE ALSO alarm() , sleep() , ualarm() , usleep() , , . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" $Header: getitimer.2,v 76.1 95/07/07 14:40:29 ssa Exp $ .TA g .TH getitimer 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH DESCRIPTION A timer value is defined by the .I itimerval structure: .nf .IP .C struct itimerval { .C " struct timeval it_interval; /* timer interval */" .C " struct timeval it_value; /* current value */" .C }; .fi .PP Time values smaller than the resolution of the system clock are rounded up to this resolution. The machine-dependent clock resolution is .RC 1\|/\| HZ seconds, where the constant .C HZ is defined in .RC < sys/param.h >. Time values larger than an implementation-specific maximum value are rounded down to this maximum. The maximum values for the three interval timers are specified by the constants .CR MAX_ALARM , .CR MAX_VTALARM , and .C MAX_PROF defined in .RC < sys/param.h >. On all implementations, these values are guaranteed to be at least 31 days (in seconds). .PP Each time the .CR ITIMER_PROF timer expires, the .CR SIGPROF signal is delivered. Since this signal can interrupt in-progress system calls, programs using this timer must be prepared to restart interrupted system calls. .PP Interval timers are not inherited by a child process across a .CR fork() , but are inherited across an .CR exec() . .PP Three macros for manipulating time values are defined in .RC < time.h >: .RS .TP 18 .C timerclear Set a time value to zero. .TP .C timerisset Test if a time value is non-zero. .TP .C timercmp Compare two time values. (Beware that .C >= and .C <= do not work with the .C timercmp macro.) .RE .PP The timer used with .C ITIMER_REAL is also used by .C alarm() (see .IR alarm (2)). Thus successive calls to .CR alarm() , .CR getitimer() , and .C setitimer() set and return the state of a single timer. In addition, a call to .C alarm() sets the timer interval to zero. .SH ERRORS .C getitimer() or .C setitimer() fail if any of the following conditions are encountered: .RS .TP 15 .SM [EFAULT] The .I value structure specified a bad address. Reliable detection of this error is implementation dependent. .TP .SM [EINVAL] A .I value structure specified a microsecond value less that zero or greater than or equal to one million. .TP .SM [EINVAL] .I which does not specify one of the three possible timers. .RE .SH EXAMPLES The following call to .C setitimer() sets the real-time interval timer to expire initially after 10 seconds and every 0.5 seconds thereafter: .nf .IP .C struct itimerval rttimer; .C struct itimerval old_rttimer; .IP .C "rttimer.it_value.tv_sec = 10;" .C "rttimer.it_value.tv_usec = 0;" .C "rttimer.it_interval.tv_sec = 0;" .C "rttimer.it_interval.tv_usec = 500000;" .IP .C "setitimer (ITIMER_REAL, &rttimer, &old_rttimer);" .fi .SH AUTHOR .C getitimer() was developed by the University of California, Berkeley. .SH SEE ALSO alarm(2) , exec(2) , gettimeofday(2) , signal(5). .\" .\" index@\f4getitimer()\f1 \- get value of process interval timer@@@\f3getitimer(2)\f1 .\" index@\f4setitimer()\f1 \- set value of process interval timer@@@\f3getitimer(2)\f1 .\" index@set value of process interval timer@@@\f3getitimer(2)\f1 .\" index@get: value of process interval timer@@@\f3getitimer(2)\f1 .\" index@value of process interval timer, set or get@@@\f3getitimer(2)\f1 .\" index@process interval timer, set or get value of@@@\f3getitimer(2)\f1 .\" index@interval timer, set or get value of process@@@\f3getitimer(2)\f1 .\" index@timer, set or get value of process interval@@@\f3getitimer(2)\f1 .\" .\" toc@\f3getitimer(2)\f1:\0\0\f4getitimer()\fP, \f4setitimer()\fP@@@get/set value of interval timer .\" toc@\f4setitimer()\f1:\0\0set value of interval timer@@@see \f3getitimer(2)\f1 .\" .\" links@getitimer.2 setitimer.2 .\" .\" fileset_database@getitimer.2 PROGRAMING-MAN .\" $Header: getmsg.2,v 74.1 95/03/31 16:57:55 ssa Exp $ .TA g .TH getmsg 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getmsg, getpmsg - receive next message from a STREAMS file .SH SYNOPSIS .nf .C #include .PP .nf .CR "int getmsg(fildes, ctlptr, dataptr, flagsp);" .CR "int fildes;" .CR "struct strbuf *ctlptr;" .CR "struct strbuf *dataptr;" .CR "long *flagsp;" .CR "int getpmsg(fildes, ctlptr, dataptr, band, flagsp);" .CR "int fildes;" .CR "struct strbuf *ctlptr;" .CR "struct strbuf *dataptr;" .CR "int *band;" .CR "long *flagsp;" .fi .SH DESCRIPTION The .CR getmsg() function retrieves the contents of a message located at the head of the stream head read queue associated with a STREAMS file and places the contents into one or more buffers. The message contains either a data part, a control part, or both. The data and control parts of the message are placed into separate buffers, as described below. The semantics of each part is defined by the originator of the message. .P The .CR getpmsg() function does the same thing as .CR getmsg() , but provides finer control over the priority of the messages received. Except where noted, all requirements on .CR getmsg() also pertain to .CR getpmsg() . .P The .IR fildes argument specifies a file descriptor referencing a STREAMS-based file. .P The .IR ctlptr and .IR dataptr arguments each point to a .CR strbuf structure, in which the .IR buf member points to a buffer in which the data or control information is to be placed, and the .IR maxlen member indicates the maximum number of bytes this buffer can hold. On return, the .IR len member contains the number of bytes of data or control information actually received. The .IR len member is set to 0 if there is a zero-length control or data part and .IR len is set to -1 if no data or control information is present in the message. .P When .CR getmsg() is called, .IR flagsp should point to an integer that indicates the type of message the process is able to receive. This is described further below. .P The .IR ctlptr argument is used to hold the control part of the message, and .IR dataptr is used to hold the data part of the message. If .IR ctlptr (or .IR dataptr ) is a null pointer or the .IR maxlen members is \(mi1, the control (or data) part of the message is not processed and is left on the stream head read queue, and if the .IR ctlptr (or .IR dataptr ) is not a null pointer, .IR len is set to \(mi1. If the .IR maxlen member is set to 0 and there is a zero-length control (or data) part, that zero-length part is removed from the read queue and .IR len is set to 0. If the .IR maxlen member is set to 0 and there are more than 0 bytes of control (or data) information, that information is left on the read queue and .IR len is set to 0. If the .IR maxlen member in .IR ctlptr (or .IR dataptr ) is less than the control (or data) part of the message, .IR maxlen bytes are retrieved. In this case, the remainder of the message is left on the stream head read queue and a on-zero return value is provided. .P By default, .CR getmsg() processes the first available message on the stream head read queue. However, a process may choose to retrieve only high-priority messages by setting the integer pointed to by .IR flagsp to .CR RS_HIPRI . In this case, .CR getmsg() will only process the next message if it is a high-priority message. When the integer pointed to by .IR flagsp is 0, any message will be retrieved. In this case, on return, the integer pointed to by .IR flagsp will be set to .CR RS_HIPRI if a high-priority message was retrieved, or 0 otherwise. .P For .CR getpmsg() , the flags are different. The .IR flagsp argument points to a bitmask with the following mutually-exclusive flags defined. .CR MSG_HIPRI , .CR MSG_BAND , and .CR MSG_ANY . Like .CR getmsg() , .CR getpmsg() processes the first available message on the stream head read queue. A process may choose to retrieve only high-priority message by setting the integer pointed to by .IR flagsp to .CR MSG_HIPRI and the integer pointed to by .IR bandp to 0. In this case, .CR getpmsg() will only process the next message if is a high-priority message. In a similar manner, a process may choose to retrieve a message from a particular priority band by setting the integer pointed to by .IR flagsp to .CR MSG_BAND and the integer pointed to by .IR bandp to the priority band of interest. In this case, .CR getpmsg() will only process the next message if it is in a priority band equal to, or greater than, the integer pointed to by .IR bandp , or if it is a high-priority message. If a process just wants to get the first message off the queue, the integer pointed to by .IR bandp should be set to 0. On return, if the message retrieved was a high-priority message, the integer pointed to by .IR flagsp will be set to .CR MSG_HIPRI and the integer pointed to by .IR bandp will be set to 0. Otherwise, the integer pointed to by .IR flagsp will be set to .CR MSG_BAND and the integer pointed to by .IR bandp will be set to the priority band of the message. .P If .CR O_NONBLOCK is not set, .CR getmsg() and .CR getpmsg() will not block until a message of the type specified by .IR flagsp is available at the front of the stream head read queue. If .CR O_NONBLOCK is set and a message of the specified type is not present at the front of the read queue, .CR getmsg() and .CR getpmsg() fail and set .CR errno to [EAGAIN]. .P If a hangup occurs on the stream from which messages are to be retrieved, .CR getmsg() and .CR getpmsg() continue to operate normally, as described above, until the stream head read queue is empty. Thereafter, they return 0 in the .IR len members of .IR ctlptr and .IR dataptr . .SH RETURN VALUE Upon successful completion, .CR getmsg() and .CR getpmsg() return a non-negative value. A value of 0 indicates that a full message was read successfully. A return value of .CR MORECTL indicates that more control information is waiting for retrieval. A return value of .CR MOREDATA indicates that more data is waiting for retrieval. A return value of the bitwise logical OR of .CR MORECTL and .CR MOREDATA indicates that both types of information remain. Subsequent .CR getmsg() and .CR getpmsg() calls retrieve the remainder of the message. However, if a message of higher priority has come in on the stream head read queue, the next call to .CR getmsg() or .CR getpmsg() retrieves that higher-priority message before retrieving the remainder of the previously-received partial message. .P Upon failure, .CR getmsg() and .CR getpmsg() return -1 and set .CR errno to indicate the error. .SH ERRORS The .CR getmsg() and .CR getpmsg() functions will fail if: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set and no messages are available. .TP [EBADF] The .IR fildes argument is not a valid file descriptor open for reading. .TP [EBADMSG] The queued message to be read is not valid for .CR getmsg() or .CR getpmsg() or a pending file descriptor is at the stream head. .TP [EINTR] A signal was caught during .CR getmsg() or .CR getpmsg() . .TP [EINVAL] An illegal value was specified by .IR flagsp , or the stream or multiplexor referenced by .IR fildes is linked (directly or indirectly) downstream from a multiplexor. .TP [ENOSTR] A stream is not associated with .IR fildes . .RE .SH SEE ALSO poll(2), putmsg(2), read(2), write(2), , streamio(7). .\" .\" index@\f4getmsg()\f1 \- receive next message from a STREAMS file@@@\f3getmsg(2)\f1 .\" index@\f4getpmsg()\f1 \- receive next message from a STREAMS file in a priority order@@@\f3getmsg(2)\f1 .\" index@\f1STREAMS file, receive next message@@@\f3getmsg(2)\f1 .\" index@\f1file: receive next message from a STREAMS file@@@\f3getmsg(2)\f1 .\" Main TOC entry .\" toc@\f3getmsg(2)\f1:\0\0\f4getmsg()\f1, \f4getpmsg()\f1@@@receive next message from a STREAMS file .\" .\" toc@\f4getpmsg()\f1:\0\0receive next message from a STREAMS file in a priority order@@@\f1see \f3getmsg(2)\f1 .\" .\" links@getmsg.2 getpmsg.2 .\" .\" fileset_database@getmsg.2 STREAMS-MAN .\" $Header: getpagesize.2,v 76.2 95/07/07 14:41:16 ssa Exp $ .TA g .TH getpagesize 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpagesize \- get the current page size .SH SYNOPSIS .\" UX .PP .C #include .PP .C int getpagesize(void); .\" ? .SH DESCRIPTION The .CR getpagesize() function returns the current page size. .PP The .CR getpagesize() function is equivalent to .C "sysconf(_SC_PAGE_SIZE)" and .CR "sysconf(_SC_PAGESIZE)" . .SH RETURN VALUE The .CR getpagesize() function returns the current page size. .SH ERRORS No errors are defined. .SH APPLICATION USAGE The value returned by .CR getpagesize() need not be the minimum value that .CR malloc() can allocate. Moreover, the application cannot assume that an object of this size can be allocated with .CR malloc() . .SH SEE ALSO brk(), getrlimit(), mmap(), mprotect(), munmap(), msync(), sysconf(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4getpagesize()\f1 \- get the current page size@@@\f3getpagesize(2)\f1 .\" index@\f1get the current page size@@@\f3getpagesize(2)\f1 .\" index@\f1current page size, get@@@\f3getpagesize(2)\f1 .\" index@\f1page size, get the current@@@\f3getpagesize(2)\f1 .\" .\" toc@\f3getpagesize(2)\f1:\0\0\f4getpagesize()\f1@@@get the current page size .\" $Header: getpeername.2,v 78.2 96/01/19 20:12:16 ssa Exp $ .TA g .TH getpeername 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpeername \- get address of connected peer .SH SYNOPSIS .C #include .SS \s-1AF_CCITT\s0 only: .C #include .PP .C "int getpeername(int s, void *addr, int *addrlen);" .SS _XOPEN_SOURCE_EXTENDED only .C "int getpeername(int s, struct sockaddr *addr, size_t *addrlen);" .SH DESCRIPTION .C getpeername() returns the address of the peer socket connected to the socket indicated by .IR s , where .I s is a socket descriptor. .I addr points to a socket address structure in which this address is returned. .I addrlen points to an object of type .CR int , which should be initialized to indicate the size of the address structure. On return, it contains the actual size of the address returned (in bytes). If .I addr does not point to enough space to contain the whole address of the peer, only the first .I addrlen bytes of the address are returned. .SS \s-1AF_CCITT\s0 only: The .I addr struct contains the .SM X.25 addressing information of the .I remote peer socket connected to socket .IR s . However, the .C x25ifname[] field of the .I addr struct contains the name of the .I local .SM X.25 interface through which the call arrived. .SH RETURN VALUE Upon successful completion, .C getpeername() returns 0; otherwise it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C getpeername() fails if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR s is not a valid file descriptor. .TP .SM [ENOTSOCK] .I s is a valid file descriptor, but it is not a socket. .TP .SM [ENOTCONN] The socket is not connected. .TP .SM [ENOBUFS] No buffer space is available to perform the operation. .TP .SM [EFAULT] .IR addr or .IR addrlen are not valid pointers. .TP .SM [EINVAL] The socket has been shut down. .TP .SM [EOPNOTSUPP] Operation not supported for .SM AF_UNIX sockets. .RE .SH AUTHOR .C getpeername() was developed by the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO bind(2), socket(2), getsockname(2), inet(7F), af_ccitt(7F), xopen_networking(7). .\" .\" index@\f4getpeername()\f1 \- get address of connected peer@@@\f3getpeername(2)\f1 .\" index@\f1get address of connected peer@@@\f3getpeername(2)\f1 .\" index@\f1address of connected peer, get@@@\f3getpeername(2)\f1 .\" index@\f1connected peer, get address of@@@\f3getpeername(2)\f1 .\" index@\f1peer, get address of connected@@@\f3getpeername(2)\f1 .\" .\" toc@\f3getpeername(2)\f1:\0\0\f4getpeername()\f1@@@get address of connected peer .\" .\" fileset_database@getpeername.2 PROGRAMING-MAN .\" $Header: getpid.2,v 72.5 94/11/14 15:24:08 ssa Exp $ .TA g .TH getpid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpid(), getpgid(), getpgrp(), getpgrp2(), getppid() \- get process, process group and parent process ID. .SH SYNOPSIS .C "#include " .PP .C "pid_t getpgid (pid_t pid);" .PP .C "pid_t getpgrp(void);" .PP .C "pid_t getpgrp2(pid_t pid);" .PP .C "pid_t getpid(void);" .PP .C "pid_t getppid(void);" .SH DESCRIPTION These functions return process, process group and parent process IDs, as follows: .RS .TP 20 .CR getpgid() Process group ID of the specified process. If .I pid is zero, the call applies to the calling process. Same result as .CR getpgrp2() . .TP .CR getpgrp() Process group ID of the calling process. .TP .CR getpgrp2() Process group ID of the specified process. If .I pid is zero, the call applies to the calling process. Same result as .CR getpgid() . .TP .CR getpid() Process ID of the calling process. .TP .CR getppid() Parent process ID of the calling process. .RE .SH RETURN VALUE The functions return the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .IR n is a nonnegative process ID, as described above. .TP .CR -1 Failure: .CR getpgid() and .CR getgrp2() only. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR getpgid() or .CR getpgrp2() fails, .CR errno is set to one of the following values: .RS .TP 15 [EPERM] The current process and .I pid are not in the same session (see .IR setsid (2)). .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SH AUTHOR .CR getpid() , .CR getppid() , .CR getpgrp() , and .CR getpgrp2() were developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO exec(2), fork(2), setpgid(2), setsid(2), signal(5). .SH STANDARDS CONFORMANCE .CR getpid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpgrp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getppid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f1get process, process group, or parent process ID@@@\f3getpid(2)\f1 .\" index@\f1parent process ID, get@@@\f3getpid(2)\f1 .\" index@\f1process ID, get@@@\f3getpid(2)\f1 .\" index@\f1process group ID, get@@@\f3getpid(2)\f1 .\" index@\f4getpgid()\fP \- get process group ID of specified process@@@\f3getpid(2)\f1 .\" index@\f4getpgrp()\fP \- get process group ID@@@\f3getpid(2)\f1 .\" index@\f4getpgrp2()\f1 \- get process group ID of specified process@@@\f3getpid(2)\f1 .\" index@\f4getpid()\fP \- get process ID@@@\f3getpid(2)\f1 .\" index@\f4getppid()\fP \- get parent process ID@@@\f3getpid(2)\f1 .\" .\" links@getpid.2 getpgid.2 .\" links@getpid.2 getpgrp.2 .\" links@getpid.2 getpgrp2.2 .\" links@getpid.2 getppid.2 .\" .\" toc@\f3getpid(2)\f1:\0\0\f4getpgid()\f1, \f4getpgrp()\f1, \f4getpgrp2()\f1, \f4getpid()\f1, \f4getppid()\f1\n@@@get process, process group, and parent process ID .\" toc@\f4getpgid()\f1: get process group ID@@@see \f3getpid(2)\f1 .\" toc@\f4getpgrp()\f1: get process group ID@@@see \f3getpid(2)\f1 .\" toc@\f4getpgrp2()\f1: get process group ID of specified process@@@see \f3getpid(2)\f1 .\" toc@\f4getppid()\f1: get parent process ID@@@see \f3getpid(2)\f1 .\" $Header: getpid.2,v 72.5 94/11/14 15:24:08 ssa Exp $ .TA g .TH getpid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpid(), getpgid(), getpgrp(), getpgrp2(), getppid() \- get process, process group and parent process ID. .SH SYNOPSIS .C "#include " .PP .C "pid_t getpgid (pid_t pid);" .PP .C "pid_t getpgrp(void);" .PP .C "pid_t getpgrp2(pid_t pid);" .PP .C "pid_t getpid(void);" .PP .C "pid_t getppid(void);" .SH DESCRIPTION These functions return process, process group and parent process IDs, as follows: .RS .TP 20 .CR getpgid() Process group ID of the specified process. If .I pid is zero, the call applies to the calling process. Same result as .CR getpgrp2() . .TP .CR getpgrp() Process group ID of the calling process. .TP .CR getpgrp2() Process group ID of the specified process. If .I pid is zero, the call applies to the calling process. Same result as .CR getpgid() . .TP .CR getpid() Process ID of the calling process. .TP .CR getppid() Parent process ID of the calling process. .RE .SH RETURN VALUE The functions return the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .IR n is a nonnegative process ID, as described above. .TP .CR -1 Failure: .CR getpgid() and .CR getgrp2() only. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR getpgid() or .CR getpgrp2() fails, .CR errno is set to one of the following values: .RS .TP 15 [EPERM] The current process and .I pid are not in the same session (see .IR setsid (2)). .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SH AUTHOR .CR getpid() , .CR getppid() , .CR getpgrp() , and .CR getpgrp2() were developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO exec(2), fork(2), setpgid(2), setsid(2), signal(5). .SH STANDARDS CONFORMANCE .CR getpid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpgrp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getppid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f1get process, process group, or parent process ID@@@\f3getpid(2)\f1 .\" index@\f1parent process ID, get@@@\f3getpid(2)\f1 .\" index@\f1process ID, get@@@\f3getpid(2)\f1 .\" index@\f1process group ID, get@@@\f3getpid(2)\f1 .\" index@\f4getpgid()\fP \- get process group ID of specified process@@@\f3getpid(2)\f1 .\" index@\f4getpgrp()\fP \- get process group ID@@@\f3getpid(2)\f1 .\" index@\f4getpgrp2()\f1 \- get process group ID of specified process@@@\f3getpid(2)\f1 .\" index@\f4getpid()\fP \- get process ID@@@\f3getpid(2)\f1 .\" index@\f4getppid()\fP \- get parent process ID@@@\f3getpid(2)\f1 .\" .\" links@getpid.2 getpgid.2 .\" links@getpid.2 getpgrp.2 .\" links@getpid.2 getpgrp2.2 .\" links@getpid.2 getppid.2 .\" .\" toc@\f3getpid(2)\f1:\0\0\f4getpgid()\f1, \f4getpgrp()\f1, \f4getpgrp2()\f1, \f4getpid()\f1, \f4getppid()\f1\n@@@get process, process group, and parent process ID .\" toc@\f4getpgid()\f1: get process group ID@@@see \f3getpid(2)\f1 .\" toc@\f4getpgrp()\f1: get process group ID@@@see \f3getpid(2)\f1 .\" toc@\f4getpgrp2()\f1: get process group ID of specified process@@@see \f3getpid(2)\f1 .\" toc@\f4getppid()\f1: get parent process ID@@@see \f3getpid(2)\f1 .\" $Header: getpid.2,v 72.5 94/11/14 15:24:08 ssa Exp $ .TA g .TH getpid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpid(), getpgid(), getpgrp(), getpgrp2(), getppid() \- get process, process group and parent process ID. .SH SYNOPSIS .C "#include " .PP .C "pid_t getpgid (pid_t pid);" .PP .C "pid_t getpgrp(void);" .PP .C "pid_t getpgrp2(pid_t pid);" .PP .C "pid_t getpid(void);" .PP .C "pid_t getppid(void);" .SH DESCRIPTION These functions return process, process group and parent process IDs, as follows: .RS .TP 20 .CR getpgid() Process group ID of the specified process. If .I pid is zero, the call applies to the calling process. Same result as .CR getpgrp2() . .TP .CR getpgrp() Process group ID of the calling process. .TP .CR getpgrp2() Process group ID of the specified process. If .I pid is zero, the call applies to the calling process. Same result as .CR getpgid() . .TP .CR getpid() Process ID of the calling process. .TP .CR getppid() Parent process ID of the calling process. .RE .SH RETURN VALUE The functions return the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .IR n is a nonnegative process ID, as described above. .TP .CR -1 Failure: .CR getpgid() and .CR getgrp2() only. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR getpgid() or .CR getpgrp2() fails, .CR errno is set to one of the following values: .RS .TP 15 [EPERM] The current process and .I pid are not in the same session (see .IR setsid (2)). .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SH AUTHOR .CR getpid() , .CR getppid() , .CR getpgrp() , and .CR getpgrp2() were developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO exec(2), fork(2), setpgid(2), setsid(2), signal(5). .SH STANDARDS CONFORMANCE .CR getpid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpgrp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getppid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f1get process, process group, or parent process ID@@@\f3getpid(2)\f1 .\" index@\f1parent process ID, get@@@\f3getpid(2)\f1 .\" index@\f1process ID, get@@@\f3getpid(2)\f1 .\" index@\f1process group ID, get@@@\f3getpid(2)\f1 .\" index@\f4getpgid()\fP \- get process group ID of specified process@@@\f3getpid(2)\f1 .\" index@\f4getpgrp()\fP \- get process group ID@@@\f3getpid(2)\f1 .\" index@\f4getpgrp2()\f1 \- get process group ID of specified process@@@\f3getpid(2)\f1 .\" index@\f4getpid()\fP \- get process ID@@@\f3getpid(2)\f1 .\" index@\f4getppid()\fP \- get parent process ID@@@\f3getpid(2)\f1 .\" .\" links@getpid.2 getpgid.2 .\" links@getpid.2 getpgrp.2 .\" links@getpid.2 getpgrp2.2 .\" links@getpid.2 getppid.2 .\" .\" toc@\f3getpid(2)\f1:\0\0\f4getpgid()\f1, \f4getpgrp()\f1, \f4getpgrp2()\f1, \f4getpid()\f1, \f4getppid()\f1\n@@@get process, process group, and parent process ID .\" toc@\f4getpgid()\f1: get process group ID@@@see \f3getpid(2)\f1 .\" toc@\f4getpgrp()\f1: get process group ID@@@see \f3getpid(2)\f1 .\" toc@\f4getpgrp2()\f1: get process group ID of specified process@@@see \f3getpid(2)\f1 .\" toc@\f4getppid()\f1: get parent process ID@@@see \f3getpid(2)\f1 .\" $Header: getpid.2,v 72.5 94/11/14 15:24:08 ssa Exp $ .TA g .TH getpid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpid(), getpgid(), getpgrp(), getpgrp2(), getppid() \- get process, process group and parent process ID. .SH SYNOPSIS .C "#include " .PP .C "pid_t getpgid (pid_t pid);" .PP .C "pid_t getpgrp(void);" .PP .C "pid_t getpgrp2(pid_t pid);" .PP .C "pid_t getpid(void);" .PP .C "pid_t getppid(void);" .SH DESCRIPTION These functions return process, process group and parent process IDs, as follows: .RS .TP 20 .CR getpgid() Process group ID of the specified process. If .I pid is zero, the call applies to the calling process. Same result as .CR getpgrp2() . .TP .CR getpgrp() Process group ID of the calling process. .TP .CR getpgrp2() Process group ID of the specified process. If .I pid is zero, the call applies to the calling process. Same result as .CR getpgid() . .TP .CR getpid() Process ID of the calling process. .TP .CR getppid() Parent process ID of the calling process. .RE .SH RETURN VALUE The functions return the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .IR n is a nonnegative process ID, as described above. .TP .CR -1 Failure: .CR getpgid() and .CR getgrp2() only. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR getpgid() or .CR getpgrp2() fails, .CR errno is set to one of the following values: .RS .TP 15 [EPERM] The current process and .I pid are not in the same session (see .IR setsid (2)). .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SH AUTHOR .CR getpid() , .CR getppid() , .CR getpgrp() , and .CR getpgrp2() were developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO exec(2), fork(2), setpgid(2), setsid(2), signal(5). .SH STANDARDS CONFORMANCE .CR getpid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpgrp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getppid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f1get process, process group, or parent process ID@@@\f3getpid(2)\f1 .\" index@\f1parent process ID, get@@@\f3getpid(2)\f1 .\" index@\f1process ID, get@@@\f3getpid(2)\f1 .\" index@\f1process group ID, get@@@\f3getpid(2)\f1 .\" index@\f4getpgid()\fP \- get process group ID of specified process@@@\f3getpid(2)\f1 .\" index@\f4getpgrp()\fP \- get process group ID@@@\f3getpid(2)\f1 .\" index@\f4getpgrp2()\f1 \- get process group ID of specified process@@@\f3getpid(2)\f1 .\" index@\f4getpid()\fP \- get process ID@@@\f3getpid(2)\f1 .\" index@\f4getppid()\fP \- get parent process ID@@@\f3getpid(2)\f1 .\" .\" links@getpid.2 getpgid.2 .\" links@getpid.2 getpgrp.2 .\" links@getpid.2 getpgrp2.2 .\" links@getpid.2 getppid.2 .\" .\" toc@\f3getpid(2)\f1:\0\0\f4getpgid()\f1, \f4getpgrp()\f1, \f4getpgrp2()\f1, \f4getpid()\f1, \f4getppid()\f1\n@@@get process, process group, and parent process ID .\" toc@\f4getpgid()\f1: get process group ID@@@see \f3getpid(2)\f1 .\" toc@\f4getpgrp()\f1: get process group ID@@@see \f3getpid(2)\f1 .\" toc@\f4getpgrp2()\f1: get process group ID of specified process@@@see \f3getpid(2)\f1 .\" toc@\f4getppid()\f1: get parent process ID@@@see \f3getpid(2)\f1 .\" $Header: getmsg.2,v 74.1 95/03/31 16:57:55 ssa Exp $ .TA g .TH getmsg 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getmsg, getpmsg - receive next message from a STREAMS file .SH SYNOPSIS .nf .C #include .PP .nf .CR "int getmsg(fildes, ctlptr, dataptr, flagsp);" .CR "int fildes;" .CR "struct strbuf *ctlptr;" .CR "struct strbuf *dataptr;" .CR "long *flagsp;" .CR "int getpmsg(fildes, ctlptr, dataptr, band, flagsp);" .CR "int fildes;" .CR "struct strbuf *ctlptr;" .CR "struct strbuf *dataptr;" .CR "int *band;" .CR "long *flagsp;" .fi .SH DESCRIPTION The .CR getmsg() function retrieves the contents of a message located at the head of the stream head read queue associated with a STREAMS file and places the contents into one or more buffers. The message contains either a data part, a control part, or both. The data and control parts of the message are placed into separate buffers, as described below. The semantics of each part is defined by the originator of the message. .P The .CR getpmsg() function does the same thing as .CR getmsg() , but provides finer control over the priority of the messages received. Except where noted, all requirements on .CR getmsg() also pertain to .CR getpmsg() . .P The .IR fildes argument specifies a file descriptor referencing a STREAMS-based file. .P The .IR ctlptr and .IR dataptr arguments each point to a .CR strbuf structure, in which the .IR buf member points to a buffer in which the data or control information is to be placed, and the .IR maxlen member indicates the maximum number of bytes this buffer can hold. On return, the .IR len member contains the number of bytes of data or control information actually received. The .IR len member is set to 0 if there is a zero-length control or data part and .IR len is set to -1 if no data or control information is present in the message. .P When .CR getmsg() is called, .IR flagsp should point to an integer that indicates the type of message the process is able to receive. This is described further below. .P The .IR ctlptr argument is used to hold the control part of the message, and .IR dataptr is used to hold the data part of the message. If .IR ctlptr (or .IR dataptr ) is a null pointer or the .IR maxlen members is \(mi1, the control (or data) part of the message is not processed and is left on the stream head read queue, and if the .IR ctlptr (or .IR dataptr ) is not a null pointer, .IR len is set to \(mi1. If the .IR maxlen member is set to 0 and there is a zero-length control (or data) part, that zero-length part is removed from the read queue and .IR len is set to 0. If the .IR maxlen member is set to 0 and there are more than 0 bytes of control (or data) information, that information is left on the read queue and .IR len is set to 0. If the .IR maxlen member in .IR ctlptr (or .IR dataptr ) is less than the control (or data) part of the message, .IR maxlen bytes are retrieved. In this case, the remainder of the message is left on the stream head read queue and a on-zero return value is provided. .P By default, .CR getmsg() processes the first available message on the stream head read queue. However, a process may choose to retrieve only high-priority messages by setting the integer pointed to by .IR flagsp to .CR RS_HIPRI . In this case, .CR getmsg() will only process the next message if it is a high-priority message. When the integer pointed to by .IR flagsp is 0, any message will be retrieved. In this case, on return, the integer pointed to by .IR flagsp will be set to .CR RS_HIPRI if a high-priority message was retrieved, or 0 otherwise. .P For .CR getpmsg() , the flags are different. The .IR flagsp argument points to a bitmask with the following mutually-exclusive flags defined. .CR MSG_HIPRI , .CR MSG_BAND , and .CR MSG_ANY . Like .CR getmsg() , .CR getpmsg() processes the first available message on the stream head read queue. A process may choose to retrieve only high-priority message by setting the integer pointed to by .IR flagsp to .CR MSG_HIPRI and the integer pointed to by .IR bandp to 0. In this case, .CR getpmsg() will only process the next message if is a high-priority message. In a similar manner, a process may choose to retrieve a message from a particular priority band by setting the integer pointed to by .IR flagsp to .CR MSG_BAND and the integer pointed to by .IR bandp to the priority band of interest. In this case, .CR getpmsg() will only process the next message if it is in a priority band equal to, or greater than, the integer pointed to by .IR bandp , or if it is a high-priority message. If a process just wants to get the first message off the queue, the integer pointed to by .IR bandp should be set to 0. On return, if the message retrieved was a high-priority message, the integer pointed to by .IR flagsp will be set to .CR MSG_HIPRI and the integer pointed to by .IR bandp will be set to 0. Otherwise, the integer pointed to by .IR flagsp will be set to .CR MSG_BAND and the integer pointed to by .IR bandp will be set to the priority band of the message. .P If .CR O_NONBLOCK is not set, .CR getmsg() and .CR getpmsg() will not block until a message of the type specified by .IR flagsp is available at the front of the stream head read queue. If .CR O_NONBLOCK is set and a message of the specified type is not present at the front of the read queue, .CR getmsg() and .CR getpmsg() fail and set .CR errno to [EAGAIN]. .P If a hangup occurs on the stream from which messages are to be retrieved, .CR getmsg() and .CR getpmsg() continue to operate normally, as described above, until the stream head read queue is empty. Thereafter, they return 0 in the .IR len members of .IR ctlptr and .IR dataptr . .SH RETURN VALUE Upon successful completion, .CR getmsg() and .CR getpmsg() return a non-negative value. A value of 0 indicates that a full message was read successfully. A return value of .CR MORECTL indicates that more control information is waiting for retrieval. A return value of .CR MOREDATA indicates that more data is waiting for retrieval. A return value of the bitwise logical OR of .CR MORECTL and .CR MOREDATA indicates that both types of information remain. Subsequent .CR getmsg() and .CR getpmsg() calls retrieve the remainder of the message. However, if a message of higher priority has come in on the stream head read queue, the next call to .CR getmsg() or .CR getpmsg() retrieves that higher-priority message before retrieving the remainder of the previously-received partial message. .P Upon failure, .CR getmsg() and .CR getpmsg() return -1 and set .CR errno to indicate the error. .SH ERRORS The .CR getmsg() and .CR getpmsg() functions will fail if: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set and no messages are available. .TP [EBADF] The .IR fildes argument is not a valid file descriptor open for reading. .TP [EBADMSG] The queued message to be read is not valid for .CR getmsg() or .CR getpmsg() or a pending file descriptor is at the stream head. .TP [EINTR] A signal was caught during .CR getmsg() or .CR getpmsg() . .TP [EINVAL] An illegal value was specified by .IR flagsp , or the stream or multiplexor referenced by .IR fildes is linked (directly or indirectly) downstream from a multiplexor. .TP [ENOSTR] A stream is not associated with .IR fildes . .RE .SH SEE ALSO poll(2), putmsg(2), read(2), write(2), , streamio(7). .\" .\" index@\f4getmsg()\f1 \- receive next message from a STREAMS file@@@\f3getmsg(2)\f1 .\" index@\f4getpmsg()\f1 \- receive next message from a STREAMS file in a priority order@@@\f3getmsg(2)\f1 .\" index@\f1STREAMS file, receive next message@@@\f3getmsg(2)\f1 .\" index@\f1file: receive next message from a STREAMS file@@@\f3getmsg(2)\f1 .\" Main TOC entry .\" toc@\f3getmsg(2)\f1:\0\0\f4getmsg()\f1, \f4getpmsg()\f1@@@receive next message from a STREAMS file .\" .\" toc@\f4getpmsg()\f1:\0\0receive next message from a STREAMS file in a priority order@@@\f1see \f3getmsg(2)\f1 .\" .\" links@getmsg.2 getpmsg.2 .\" .\" fileset_database@getmsg.2 STREAMS-MAN .\" $Header: getpid.2,v 72.5 94/11/14 15:24:08 ssa Exp $ .TA g .TH getpid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpid(), getpgid(), getpgrp(), getpgrp2(), getppid() \- get process, process group and parent process ID. .SH SYNOPSIS .C "#include " .PP .C "pid_t getpgid (pid_t pid);" .PP .C "pid_t getpgrp(void);" .PP .C "pid_t getpgrp2(pid_t pid);" .PP .C "pid_t getpid(void);" .PP .C "pid_t getppid(void);" .SH DESCRIPTION These functions return process, process group and parent process IDs, as follows: .RS .TP 20 .CR getpgid() Process group ID of the specified process. If .I pid is zero, the call applies to the calling process. Same result as .CR getpgrp2() . .TP .CR getpgrp() Process group ID of the calling process. .TP .CR getpgrp2() Process group ID of the specified process. If .I pid is zero, the call applies to the calling process. Same result as .CR getpgid() . .TP .CR getpid() Process ID of the calling process. .TP .CR getppid() Parent process ID of the calling process. .RE .SH RETURN VALUE The functions return the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .IR n is a nonnegative process ID, as described above. .TP .CR -1 Failure: .CR getpgid() and .CR getgrp2() only. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR getpgid() or .CR getpgrp2() fails, .CR errno is set to one of the following values: .RS .TP 15 [EPERM] The current process and .I pid are not in the same session (see .IR setsid (2)). .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SH AUTHOR .CR getpid() , .CR getppid() , .CR getpgrp() , and .CR getpgrp2() were developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO exec(2), fork(2), setpgid(2), setsid(2), signal(5). .SH STANDARDS CONFORMANCE .CR getpid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpgrp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getppid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f1get process, process group, or parent process ID@@@\f3getpid(2)\f1 .\" index@\f1parent process ID, get@@@\f3getpid(2)\f1 .\" index@\f1process ID, get@@@\f3getpid(2)\f1 .\" index@\f1process group ID, get@@@\f3getpid(2)\f1 .\" index@\f4getpgid()\fP \- get process group ID of specified process@@@\f3getpid(2)\f1 .\" index@\f4getpgrp()\fP \- get process group ID@@@\f3getpid(2)\f1 .\" index@\f4getpgrp2()\f1 \- get process group ID of specified process@@@\f3getpid(2)\f1 .\" index@\f4getpid()\fP \- get process ID@@@\f3getpid(2)\f1 .\" index@\f4getppid()\fP \- get parent process ID@@@\f3getpid(2)\f1 .\" .\" links@getpid.2 getpgid.2 .\" links@getpid.2 getpgrp.2 .\" links@getpid.2 getpgrp2.2 .\" links@getpid.2 getppid.2 .\" .\" toc@\f3getpid(2)\f1:\0\0\f4getpgid()\f1, \f4getpgrp()\f1, \f4getpgrp2()\f1, \f4getpid()\f1, \f4getppid()\f1\n@@@get process, process group, and parent process ID .\" toc@\f4getpgid()\f1: get process group ID@@@see \f3getpid(2)\f1 .\" toc@\f4getpgrp()\f1: get process group ID@@@see \f3getpid(2)\f1 .\" toc@\f4getpgrp2()\f1: get process group ID of specified process@@@see \f3getpid(2)\f1 .\" toc@\f4getppid()\f1: get parent process ID@@@see \f3getpid(2)\f1 .\" $Header: getpriority.2,v 78.1 96/01/19 20:12:55 ssa Exp $ .TA g .TH getpriority 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpriority, setpriority \- get or set process priority .SH SYNOPSIS .CR "#include " .PP .CR "int getpriority(int which, int who);" .PP .CR "int setpriority(int which, int who, int priority);" .SH DESCRIPTION .CR getpriority() returns the priority of the indicated processes. .PP .CR setpriority() sets the priority of the indicated processes to .IR priority . .PP The processes are indicated by .IR which and .IR who , where .IR which can have one of the following values: .RS .TP 20 .CR PRIO_PROCESS Get or set the priority of the specified process where .IR who is the process ID. A .IR who of .CR 0 implies the process ID of the calling process. .TP .CR PRIO_PGRP Get or set the priority of the specified process group where .IR who is the process-group ID, indicating all processes belonging to that process-group. A .IR who of .CR 0 implies the process-group ID of the calling process. .TP .CR PRIO_USER Get or set the priority of the specified user where .IR who is the user ID, indicating all processes owned by that user. A .IR who of .CR 0 implies the user ID of the calling process. .RE .PP If more than one process is indicated, the value returned by .CR getpriority() is the lowest valued priority of all the indicated processes, and .CR setpriority() sets the priority of all indicated processes. .PP .IR priority is a value from .CR -20 to .CR 20 , where lower values indicate better priorities. The default priority for a process is 0. Negative priorities require appropriate privileges. .SH RETURN VALUE .CR getpriority() returns the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .IR n is an integer priority in the range .CR -20 to .CR 20 . .TP .CR -1 Failure. .CR errno is set to indicate the error. See WARNINGS below. .PD .RE .PP .CR setpriority() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR getpriority() or .CR setpriority() fails, .CR errno is set to one of the following values: .RS .TP 15 [EACCES] The calling process does not have access rights to change one or more of the indicated processes. All processes for which access is allowed are still affected. .TP [EINVAL] .IR which is not one of the choices listed above, or .IR who is out of range. .TP [EPERM] The calling process attempted to change the priority of a process to a smaller priority value without having appropriate privileges. .TP [ESRCH] Processes indicated by .IR which and .IR who cannot be found. .RE .SH WARNINGS .CR getpriority() can return .CR -1 both when it successfully finds a priority of .CR -1 and when it fails. To determine whether a failure occurred, set .CR errno to .CR 0 before calling .CR getpriority() , then examine .CR errno after the call returns. .SH AUTHOR .CR getpriority() and .CR setpriority() were developed by the University of California, Berkeley. .SH SEE ALSO nice(1), renice(1), nice(2). .\" .\" index@\f4getpriority()\f1 \- get process priority@@@\f3getpriority(2)\f1 .\" index@\f4setpriority()\f1 \- set process priority@@@\f3getpriority(2)\f1 .\" index@get process priority@@@\f3getpriority(2)\f1 .\" index@set process priority@@@\f3getpriority(2)\f1 .\" index@process priority, get or set@@@\f3getpriority(2)\f1 .\" index@priority, get or set process@@@\f3getpriority(2)\f1 .\" .\" toc@\f3getpriority(2)\f1:\0\0\f4getpriority()\f1, \f4setpriority()\f1@@@get or set process priority .\" toc@\f4setpriority()\f1:\0\0set process priority@@@see \f3getpriority(2)\f1 .\" .\" links@getpriority.2 setpriority.2 .\" $Header: getprivgrp.2,v 78.1 96/01/19 20:13:52 ssa Exp $ .TA g .TH getprivgrp 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprivgrp(), setprivgrp() \- get and set special attributes for group .SH SYNOPSIS .C "#include " .PP .C "int getprivgrp(struct privgrp_map *grplist);" .PP .C "int setprivgrp(gid_t grpid, const int *mask);" .SH DESCRIPTION .SS getprivgrp() The .CR getprivgrp() system call returns a table of the privileged group assignments into a user-supplied structure. .IR grplist points to an array of structures of type .CR privgrp_map , associating a group ID with a privilege mask. Privilege masks are formed by ORing together elements from the access types specified in .CR . The array may have gaps in it, distinguished as having a .CR priv_groupno field value of .CR PRIV_NONE . The group number .CR PRIV_GLOBAL gives the global privilege mask. Only information about groups which are in the user's group access list, or about the user's real or effective group ID, is returned to an ordinary user. The complete set is returned to a privileged user. .SS setprivgrp() The .CR setprivgrp() system call associates a kernel capability with a group ID. This allows subletting of superuser-like privileges to members of a particular group or groups. .CR setprivgrp() takes two arguments: .IR grpid , the integer group ID, and .IR mask , a mask of permissions. The mask is created by treating the access types defined in .CR as bit numbers (using 1 for the least significant bit). Thus, privilege number 5 would be represented by the bits .CR 1<<(5-1) or 16. More generally, privilege .IR p is represented by: .IP .CI "mask[((" p "-1) / BITS_PER_INT)] & (1 << ((" p "-1) % BITS_PER_INT))" .PP where .CR BITS_PER_INT is .CR 8*sizeof(mask[0]) given 8 bits per byte. As it is possible to have more than .IR "word-size" distinct privileges, mask is a pointer to an integer array of size .CR PRIV_MASKSIZ . .PP .CR setprivgrp() privileges include those specified in the file .CR . A process can access the system call protected by a specific privileged group if it belongs to or has an effective group ID of a group having access to the system call. All processes are considered to belong to the pseudo-group .CR PRIV_GLOBAL . .PP Specifying a .IR grpid of .CR PRIV_NONE causes privileges to be revoked on all privileged groups that have any of the privileges specified in .IR mask . Specifying a .IR grpid of .CR PRIV_GLOBAL causes privileges to be granted to all processes. .PP The constant .CR PRIV_MAXGRPS in .CR defines the system limit on the number of groups that can be assigned privileges. One of these is always the psuedo-group .CR PRIV_GLOBAL , allowing for .CR "PRIV_MAXGRPS - 1" actual groups. .PP Only processes with appropriate privileges can use .CR setprivgrp() . .SH RETURN VALUE .CR getprivgrp() and .CR setprivgrp() return the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .SH ERRORS If .CR getprivgrp() fails, .CR errno is set to one of the following values. .RS .TP 15 [EFAULT] .IR grplist points to an illegal address. The reliable detection of this error is implementation dependent. .RE If .CR setprivgrp() fails, .CR errno is set to one of the following values. .RS .TP 15 [E2BIG] The request would require assigning privileges to more than .CR PRIV_MAXGRPS groups. .TP [EFAULT] .IR mask points to an illegal address. The reliable detection of this error is implementation dependent. .TP [EINVAL] .IR mask has bits set for one or more unknown privileges. .TP [EINVAL] .IR grpid is out of range. .TP [EPERM] The caller is not a privileged user. .SH EXAMPLES The following example prints out .CR PRIV_GLOBAL and the group IDs of the privilege groups to which the user belongs: .nf .IP .C "#include .IP .C "struct privgrp_map pgrplist[PRIV_MAXGRPS]; .C "int i; .C "gid_t pgid; .IP .C "getprivgrp (pgrplist); .C "for (i=0; i .PP .C "int getrlimit(int resource, struct rlimit *rlp);" .PP .C "int setrlimit(int resource, const struct rlimit *rlp);" .SH DESCRIPTION Limits on the consumption of a variety of resources by the calling process may be obtained with .CR getrlimit() and set with .CR setrlimit(). .PP Each call to either .CR getrlimit() or .CR setrlimit() identifies a specific resource to be operated upon as well as a resource limit. A resource limit is represented by an .CR rlimit structure. The .CR rlim_cur member specifies the current or soft limit and the .CR rlim_max member specifies the maximum or hard limit. Soft limits may be changed by a process to any value that is less than or equal to the hard limit. A process may (irreversibly) lower its hard limit to any value that is greater than or equal to the soft limit. Only a process with appropriate privileges can raise a hard limit. Both hard and soft limits can be changed in a single call to .CR setrlimit() subject to the constraints described above. .PP The value .CR RLIM_INFINITY , defined in .CR , is considered to be larger than any other limit value. If a call to .CR getrlimit() returns .CR RLIM_INFINITY for a resource, it means the implementation does not enforce limits on that resource. Specifying .CR RLIM_INFINITY as any resource limit value on a successful call to .CR setrlimit() inhibits enforcement of that resource limit. .PP The following resources are defined: .RS .TP 25 .C RLIMIT_CORE This is the maximum size of a core file in bytes that may be created by a process. A limit of 0 will prevent the creation of a core file. If this limit is exceeded, the writing of a core file will terminate at this size. .TP .C RLIMIT_CPU This is the maximum amount of CPU time in seconds used by a process. If this limit is exceeded, .CR SIGXCPU is generated for the process. If the process is blocking, catching or ignoring .CR SIGXCPU , the behaviour is unspecified. .TP .C RLIMIT_DATA This is the maximum size of a process' data segment in bytes. If this limit is exceeded, the .CR brk() , .CR malloc() , and .CR sbrk() functions will fail with .CR errno set to ENOMEM. .TP .C RLIMIT_FSIZE This is the maximum size of a file in bytes that may be created by a process. A limit of 0 will prevent the creation of a file. If a write or truncate operation would cause this limit to be exceeded, .CR SIGXFSZ is generated for the process. If the process is blocking, catching or ignoring .CR SIGXFSZ, continued attempts to increase the size of a file from end-of-file to beyond the limit will fail with .CR errno set to EFBIG. .TP .C RLIMIT_NOFILE This is a number one greater than the maximum value that the system may assign to a newly-created descriptor. If this limit is exceeded, functions that allocate new file descriptors may fail with .CR errno set to EMFILE. This limit constrains the number of file descriptors that a process may allocate. .TP .C RLIMIT_STACK This is the maximum size of a process' stack in bytes. The implementation will not automatically grow the stack beyond this limit. If this limit is exceeded, .CR SIGSEGV is generated for the process. If the process is blocking or ignoring .CR SIGSEGV , or is catching .CR SIGSEGV and has not made arrangements to use an alternate stack, the disposition of .CR SIGSEGV will be set to .CR SIG_DFL before it is generated. .TP .C RLIMIT_AS This is the maximum size of a process' total available memory, in bytes. If this limit is exceeded, the .CR brk() , .CR malloc() , .CR mmap() , and .CR sbrk() functions will fail with .CR errno set to ENOMEM. In addition, the automatic stack growth will fail with the effects outlined above. .RE .SH RETURN VALUE Upon successful completion, .CR getrlimit() and .CR setrlimit() return 0. Otherwise, these functions return -1 and set .CR errno to indicate the error. .SH ERRORS The .CR getrlimit() and .CR setrlimit() functions will fail if: .RS .TP 15 [EINVAL] An invalid resource was specified; or in a .CR setrlimit() call, the new .IR rlim_cur exceeds the new .IR rlim_max . .TP [EPERM] The limit specified to .CR setrlimit() would have raised the maximum limit value, and the calling process does not have appropriate privileges. .RE .PP The .CR setrlimit() function may fail if: .RS .TP 15 [EINVAL] The limit specified cannot be lowered because current usage is already higher than the limit. .RE .SH SEE ALSO brk(), exec, fork(), getdtablesize(), malloc(), open(), sigaltstack(), sysconf(), ulimit(), , . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" $Header: getrlimit.2,v 78.1 96/02/12 13:49:39 ssa Exp $ .TA g .TH getrlimit 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH DESCRIPTION The .I resource parameter selects the system resource limits to be set or retrieved. The possible values for .I resource are defined in .CR . Currently, only the following values are supported: .RS .TP 25 .C RLIMIT_NOFILE The maximum number of files a process can have open. The soft limit for this resource is the same as the value returned by .CR sysconf(_SC_OPEN_MAX) . .TP .C RLIMIT_OPEN_MAX Defined to be the same as .CR RLIMIT_NOFILE . .RE .PP The .I rlp argument points to an object of type struct .CR rlimit , which is defined in .CR , and includes the following members: .nf .IP .C "int rlim_cur Current (soft) limit" .C "int rlim_max Hard limit" .fi .PP For .CR getrlimit() , the system stores the two limits on the specified resource in the structure to which .I rlp points. .PP For .CR setrlimit() , the system reads new values for the two limits on the specified resource from the structure to which .I rlp points. .SH ERRORS If the .CR getrlimit() or .CR setlimit() system call fails, .CR errno (see .I errno (2)) is set to one of the following values: .RS .TP 15 [EFAULT] The address specified for .I rlp is invalid. Reliable detection of this error is implementation dependent. .RE .PP If .CR setrlimit() fails it may set .CR errno (see .IR errno (2)) to one of the following values: .RS .TP 15 [EINVAL] The .I rlp argument specified a hard or soft limit higher than the current hard limit value, and the caller does not have the appropriate privileges. .TP 15 [EINVAL] A user with appropriate privileges has attempted to raise .IR rlp \(mi> rlim_cur or .IR rlp \(mi> rlim_max to a value greater than the system is capable of supporting. .TP [EINVAL] The value of .IR rlp \(mi> rlim_cur is less than the number of file descriptors the process already has allocated. .TP [EINVAL] The value of .IR rlp \(mi> rlim_max is less than the current soft limit. .RE .ifn .ne 8 .SH WARNINGS The maximum size of a file returned by .CR getrlimit() is in terms of bytes. The maximum size of a file returned by .CR ulimit (see .IR ulimit (2)) with .CR UL_GETFSIZE is in terms of blocks of size 512 bytes. The value returned by .CR ulimit with .CR UL_GETFSIZE may thus have to be rounded down to a multiple of 512. .SH AUTHOR .CR getrlimit() and .CR setrlimit() were developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO getrlimit64(2), setrlimit64(2), sysconf(2), ulimit(2). .\" .\" index@\f4getrlimit()\f1 \- get system resource consumption limit@@@\f3getrlimit(2)\f1 .\" index@\f4setrlimit()\f1 \- set system resource consumption limit@@@\f3getrlimit(2)\f1 .\" index@\f1set system resource consumption limit@@@\f3getrlimit(2)\f1 .\" index@\f1get system resource consumption limit@@@\f3getrlimit(2)\f1 .\" index@\f1control system resource consumption limit@@@\f3getrlimit(2)\f1 .\" index@\f1system resource consumption limit, get or set@@@\f3getrlimit(2)\f1 .\" index@\f1resource consumption limit, get or set system@@@\f3getrlimit(2)\f1 .\" index@\f1consumption limit, get or set system resource@@@\f3getrlimit(2)\f1 .\" index@\f1limit, get or set system resource consumption@@@\f3getrlimit(2)\f1 .\" .\" toc@\f3getrlimit(2)\f1:\0\0\f4getrlimit()\f1, \f4setrlimit()\f1@@@control consumption of system resources .\" toc@\f4setrlimit()\f1:\0\0control consumption of system resources@@@\f1see \f3getrlimit(2)\f1 .\" .\" links@getrlimit.2 setrlimit.2 .\" $Header: creat64.2,v 78.2 96/02/12 13:37:12 ssa Exp $ .TA c .TH creat64 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME creat64(\|), fstat64(\|), getrlimit64(\|), lockf64(\|), lseek64(\|), lstat64(\|), mmap64(\|), open64(\|), prealloc64(\|), setrlimit64(\|), stat64(\|), statvfs64(\|), truncate64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0creat64(const\0char\0*path,\0mode_t\0mode);" .PP .C "#include " .PP .C "int\0fstat64(int\0fildes,\0struct\0stat64\0*buf);" .PP .C "include\0" .PP .C "int\0getrlimit64(int resource,\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0lock64(int\0*fildes,\0int\0function,\0off64_t\0size);" .PP .C "#include " .PP .C "off64_t\0lseek64(int\0*fildes,\0off64_t\0offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0lstat64(const\0char\0*,\0struct\0stat64\0*);" .PP .C "#include " .PP .C "void\0mmap64(void\0addr,\0size_t\0len,\0int\0prot,\0int\0flags,\0int\0fildes,\0off64_t\0off);" .PP .C "#include " .PP .C "int\0open64(const\0char\0*path,\0int\0oflag,...);" .PP .C "#include " .PP .C "int\0prealloc64(int\0fildes,\0off64_t\0size);" .PP .C "include\0" .PP .C "int\0setrlimit64(int\0resource,\0const\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0stat64(const\0char\0*path,\0struct\0stat64\0*buf);" .PP .C "#include " .PP .C "int\0statvfs64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "int\0truncate64(const\0char\0*path,\0off64_t\0length);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 18 .C creat64() The .C creat64() function is identical to .C creat() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. .C creat64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR creat() . .TP .C fstat64() The .C fstat64() function is identical to .C fstat() except that .C fstat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C getrlimit64 The .C getrlimit64() function is identical to .C getrlimit() except that .C getrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .CR "struct rlimit" . All other functional behaviors, returns, and errors are identical. .TP .C lock64() The .C lock64() function is identical to .C lockf() except that .C lockf64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C lseek64() The .C lseek64() function is identical to .C lseek() except that .C lseek64() accepts an .CR off64_t type as the desired offset and has a return value of .CR off64_t. All other functional behaviors, returns, and errors are identical. .TP .C lstat64() The .C lstat64() function is identical to .C lstat() except that .C lstat64() returns file status in a .C struct stat64 instead of .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C mmap64() The .C mmap64() function is identical to .C mmap() except that .C mmap64() accepts the file offset as an .CR off64_t . .TP .C open64() The .C open64() function is identical to .C open() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. The .C open64() function is equivalent to .C open() function (in 32-bit compile environment) with .C O_LARGEFILE flag set. .C open64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR open() . .TP .C prealloc64() The .C prealloc64() function is identical to .C prealloc() except that .C prealloc64() accepts the file offset as an .CR off64_t . All other functional behaviors, returns, and errors are identical to .CR prealloc() . .TP .C setrlimit64 The .C setrlimit64() function is identical to .C setrlimit() except that .C setrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .C struct rlimit. All other functional behaviors, returns, and errors are identical. .TP .C stat64() The .C stat64() function is identical to .C stat() except that .C stat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . .TP .C statvfs64() Refer to .CR fstatvfs64() . .TP .C truncate64() The .C truncate64() function is identical to .C truncate() except that .C truncate64() accepts the length parameter as an .C off64_t instead of .CR off_t . All other functional behaviors, returns, and errors are identical to .CR truncate() . .\" .\" toc@\f4creat64(2)\f1:\0\0\f4fstat64\f1, \f4getrlimit64\f1, \f4lockf64\f1, \f4lseek64\f1, \f4lstat64\f1, \f4mmap64\f1, \f4open64\f1, \n\f4prealloc64\f1, \f4setrlimit64\f1, \f4stat64\f1, \f4statvfs64\f1, \f4truncate64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4creat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4fstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4getrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lockf64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lseek64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4mmap64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4open64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4prealloc64()\f1 \- file sysmmaptem API to support large files@@@\f3creat64(2)\f1 .\" index@\f4setrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4stat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4statvfs64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4truncate64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3creat64(2)\f1 .\" .\" links@creat64.2 fstat64.2 .\" links@creat64.2 getrlimit64.2 .\" links@creat64.2 lockf64.2 .\" links@creat64.2 lseek64.2 .\" links@creat64.2 lstat64.2 .\" links@creat64.2 mmap64.2 .\" links@creat64.2 open64.2 .\" links@creat64.2 prealloc64.2 .\" links@creat64.2 setrlimit64.2 .\" links@creat64.2 stat64.2 .\" links@creat64.2 statvfs64.2 .\" links@creat64.2 truncate64.2 .\" .\" $Header: getrusage.2,v 76.2 95/07/07 14:42:15 ssa Exp $ .TA g .TH getrusage 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getrusage \- get information about resource utilisation .SH SYNOPSIS .\" UX .PP .C #include .PP .C int getrusage(int who, struct rusage *r_usage); .\"? .SH DESCRIPTION The .CR getrusage() function provides measures of the resources used by the current process or its terminated and waited\-for child processes. If the value of the who argument is .CR RUSAGE_SELF , information is returned about resources used by the current process. If the value of the who argument is .CR RUSAGE_CHILDREN , information is returned about resources used by the terminated and waited\-for children of the current process. If the child is never waited for (for instance, if the parent has .CR SA_NOCLDWAIT set or sets .CR SIGCHLD to .CR SIG_IGN ), the resource information for the child process is discarded and not included in the resource information provided by .CR getrusage() . The .IR r_usage argument is a pointer to an object of type .CR struct .CR rusage in which the returned information is stored. .SH RETURN VALUE Upon successful completion, .CR getrusage() returns 0. Otherwise, \(mi1 is returned, and .CR errno is set to indicate the error. .SH ERRORS The .CR getrusage() function will fail if: .RS .TP 15 [EINVAL] The value of the who argument is not valid. .RE .SH SEE ALSO exit(), sigaction(), time(), times(), wait(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4getrusage()\f1 \- get information about resource utilisation@@@\f3getrusage(2)\f1 .\" index@\f1get information about resource utilisation@@@\f3getrusage(2)\f1 .\" index@\f1information about resource utilisation, get@@@\f3getrusage(2)\f1 .\" index@\f1resource utilisation, get information@@@\f3getrusage(2)\f1 .\" .\" toc@\f3getrusage(2)\f1:\0\0\f4getrusage()\f1@@@get information about resource utilisation .\" $Header: getsid.2,v 72.2 94/08/12 11:08:57 ssa Exp $ .TA g .TH getsid (2) .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getsid() \- get session ID .SH SYNOPSIS .C #include .PP .C pid_t getsid (pid_t pid); .SH DESCRIPTION The .CR getsid() function returns the session ID of the specified process. If .I pid is .CR 0 , the call applies to the current process. For this to be allowed, the current process and the referenced process must be in the same session. .SH RETURN VALUE Upon successful completion, .CR getsid() returns the session ID of the specified process. Otherwise, it returns a value of .CR \(mil and sets .CR errno to indicate the error. .SH ERRORS If the .CR getsid() function fails, it sets .CR errno (see .IR errno (2)) to one of the following values: .RS .TP 15 [EPERM] The current process and the specified process are not in the same session. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SH SEE ALSO exec(2), fork(2), getpgid(2), getpid(2), setpgid(2), setsid(2), tcgetsid(3C). .\" toc@\f3getsid(2)\f1:\0\0\f4getsid()\f1@@@get session ID\f1 .\" .\" index@\f4getsid()\f1 \- get session ID@@@\f3getsid(2)\f1 .\" index@\f1session ID, get@@@\f3getsid(2)\f1 .\" index@\f1ID, get session@@@\f3getsid(2)\f1 .\" $Header: getsockname.2,v 78.2 96/03/15 15:58:32 ssa Exp $ .TA g .TH getsockname 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getsockname \- get socket address .SH SYNOPSIS .C #include .SS \s-1AF_CCITT\s0 only: .C #include .PP .C "int getsockname(int s, void *addr, int *addrlen);" .SS _XOPEN_SOURCE_EXTENDED only .C "int getsockname(int s, struct sockaddr *addr, size_t *addrlen);" .SH DESCRIPTION .C getsockname() returns the local address of the socket indicated by .IR s , where .I s is a socket descriptor. .I addr points to a socket address structure in which this address is returned. .I addrlen points to an .C int which should be initialized to indicate the size of the address structure. On return it contains the actual size of the address returned (in bytes). If .I addr does not point to enough space to contain the whole address of the socket, only the first .I addrlen bytes of the address are returned. .SS \s-1AF_CCITT\s0 only: The .C x25_host[] field of the .I addr struct returns the .SM X.25 addressing information of the local socket .IR s . The .C x25ifname[] field of the .I addr struct contains the name of the local .SM X.25 interface through which the call arrived. .SH RETURN VALUE Upon successful completion, .C getsockname() returns 0; otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C getsockname() fails if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR s is not a valid file descriptor. .TP .SM [ENOTSOCK] .IR s is a valid file descriptor, but it is not a socket. .TP .SM [ENOBUFS] No buffer space is available to perform the operation. .TP .SM [EFAULT] .IR addr or .IR addrlen are not valid pointers. .TP .SM [EINVAL] The socket has been shut down. .TP .SM [EOPNOTSUPP] Operation not supported for .SM AF_UNIX sockets. .RE .SH AUTHOR .C getsockname() was developed by the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO bind(2), socket(2), getpeername(2), inet(7F), af_ccitt(7F), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR getsockname() ": XPG4" .\" .\" index@\f4getsockname()\f1 \- get socket address@@@\f3getsockname(2)\f1 .\" index@\f1get socket address@@@\f3getsockname(2)\f1 .\" index@\f1socket address, get@@@\f3getsockname(2)\f1 .\" index@\f1address, get socket@@@\f3getsockname(2)\f1 .\" .\" toc@\f3getsockname(2)\f1:\0\0\f4getsockname()\f1@@@get socket address .\" .\" $Header: getsockopt.2,v 78.2 96/03/15 15:58:47 ssa Exp $ .TA g .TH getsockopt 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getsockopt(), setsockopt() \- get and set options on sockets .SH SYNOPSIS .nf .C "#include " .PP .C "int getsockopt(" .C " int s," .C " int level," .C " int optname," .C " void *optval," .C " int *optlen" .C ");" .PP .C "int setsockopt(" .C " int s," .C " int level," .C " int optname," .C " const void *optval," .C " int optlen" .C ");" .fi .SS "_XOPEN_SOURCE_EXTENDED only" .SH .nf .C "int getsockopt(" .C " int s," .C " int level," .C " int optname," .C " void *optval," .C " size_t *optlen" .C ");" .PP .C "int setsockopt(" .C " int s," .C " int level," .C " int optname," .C " const void *optval," .C " size_t optlen" .C ");" .fi .SH DESCRIPTION The .CR getsockopt() and .CR setsockopt() system calls manipulate options associated with a socket. The socket is identified by the socket descriptor .IR s . Options can exist at multiple protocol levels, and they are always present at the uppermost "socket" level (see .IR socket (2)) . .PP When manipulating socket options, the level at which the option resides .RI ( level ) and the name of the option .RI ( optname ) must be specified. To manipulate options at the "socket" level, .I level is specified as .CR SOL_SOCKET . To specify options at another level, .I level should be the protocol number specified in .RC < netinet/in.h > (for example, .CR IPPROTO_TCP ). .PP The parameters .I optval and .I optlen specify the value of the option. .I optval is the address of the data structure that contains the option value, and .I optlen is the length of the data structure. The type and value of the data structure that .I optval points to depends on the option. For "boolean" options, the value may be zero (not set) or non-zero (set). The value of other options depends on the purpose of the option. Usually, neither .I optval nor .I optlen may be the .SM NULL address or zero; see individual protocol manual entries for any exceptions, such as .IR tcp (7P) and .IR ip (7P). .PP For .CR setsockopt() , .I optval and .I optlen are used to pass information from the application to the system. .I optval is the address of a location in memory that contains the option information to be passed to the system. The parameter .I optlen is an integer value that specifies the size, in bytes, of the data structure pointed to by .IR optval . .PP For .CR getsockopt() , .I optval and .I optlen are used to pass information from the system to the application. The parameter .I optlen is the address of an .C int variable. Before calling .CR getsockopt() , the application should set the value of the variable to the maximum size, in bytes, of the data structure pointed to by .IR optval . Normally, upon return, the variable pointed to by .I optlen is set to the actual size the data returned in the structure pointed to by .IR optval, if .C getsockopt() returns without error. .PP The following ``socket'' level option names .RI ( optname ) are defined in .RC < sys/socket.h >. The type of the variable pointed to by .I optval is indicated in parentheses. Options for other protocol levels are described in the individual protocol manual pages, such as .IR tcp (7P) and .IR ip (7P). .RS .TP 25 .C SO_ACCEPTCONN .RC ( int ; boolean ) Returns a non-zero value if socket listening is enabled, otherwise returns a zero value. .TP .C SO_BROADCAST .RC ( int ; boolean; AF_INET SOCK_DGRAM sockets only) Allows the application to send messages to a broadcast address. .CR Default : disallowed. .TP .C SO_DEBUG .RC ( int ; boolean; AF_INET SOCK_STREAM sockets only) Enables or disables the recording of internal debug information. .CR Default : disabled. .TP .C SO_DONTROUTE .RC ( int ; boolean; AF_INET sockets only) Causes outbound messages to bypass normal routing facilities. Instead, messages are sent through the appropriate network interface based on the network portion of the destination address. .CR Default : disabled. .TP .C SO_ERROR .RC ( int ) Returns any pending error on the socket, and clears the error status. The value returned by .C SO_ERROR would be the value of .C errno after the next socket data transfer system call. .TP .C SO_KEEPALIVE .RC ( int ; boolean; AF_INET SOCK_STREAM sockets only) If enabled, keeps an otherwise idle TCP connection active. .CR Default : disabled. .TP .C SO_LINGER .RC ( "struct linger" ; AF_INET SOCK_STREAM sockets only) Controls whether or not an application "lingers" (waits) if there are untransmitted data in the send socket buffer when the socket is closed. The data type .C "struct linger" is defined in .RC < sys/socket.h >. .CR Default : disabled, as if .C l_onoff had been set to zero. (See details below.) .TP .C SO_OOBINLINE .RC ( int ; boolean; AF_INET SOCK_STREAM sockets only) If enabled, specifies that out-of-band data (TCP "urgent data") should be left "in-line" among the normal data stream. Otherwise, one byte of out-of-band data is pulled out of the data stream, and it is accessible only by setting .SM MSG_OOB in the .I flags parameter when the application reads the data (see .IR recv (2)). .CR Default : disabled. .TP .C SO_PMTU .RC ( int ; boolean; AF_INET sockets only) If enabled, specifies that Path MTU Discovery is to be used to determine the optimal datagram size for the route. .CR Default : enabled for .SM SOCK_STREAM sockets; disabled for .SM SOCK_DGRAM sockets. .TP .C SO_RCVBUF .RC ( int ) Specifies the maximum size, in bytes, of the receive socket buffer. For .SM SOCK_DGRAM sockets, the receive buffer size may limit the maximum size of messages that the socket can receive. .CR Default : protocol-dependent; see individual protocol manual entries, such as .IR tcp (7P) and .IR udp (7P). .TP .C SO_REUSEADDR .RC ( int ; boolean; AF_INET sockets only) If enabled, allows a local address to be reused in subsequent calls to .CR bind() . .CR Default : disallowed. .TP .C SO_SNDBUF .RC ( int ) Specifies the maximum size, in bytes, of the send socket buffer. For .SM SOCK_STREAM sockets, the send buffer size limits how much data can be queued for transmission before the application is blocked. For .SM SOCK_DGRAM sockets, the send buffer size may limit the maximum size of messages that the application can send through the socket. .CR Default : protocol-dependent; see individual protocol manual entries, such as .IR tcp (7P) and .IR udp (7P). .TP .C SO_TYPE .RC ( int ) Returns the socket type. .TP .C SO_USELOOPBACK .RC ( int ; boolean) Not used internally; provided only for compatibility. .RE .PP Setting the .C SO_BROADCAST option allows the application to send messages through the .SM SOCK_DGRAM socket to a broadcast destination address. .PP If .C SO_DONTROUTE is set, the system does not use the network routing tables when determining which interface to use to send an outbound message. Instead, the system sends the message through the interface whose network address matches the network portion of the destination address. If .C SO_DONTROUTE is not set (default), the system uses the network routing tables. .PP If .C SO_KEEPALIVE is disabled (default), a TCP connection may remain idle until the connection is released at the protocol layer. If .C SO_KEEPALIVE is enabled and the connection has been idle for two hours, TCP sends a packet to the remote TCP to acknowledge that the connection is still active. If the remote TCP does not respond within 75 seconds, TCP sends another packet. If TCP sends a total of 8 packets without receiving any response from the remote TCP (that is, after 10 minutes have passed), TCP drops the connection. In that case, the next attempt to read from the socket (for example, by calling .CR recv() ) returns an error, and .C errno is set to .SM ETIMEDOUT. .PP .C SO_LINGER controls the actions to be taken when there are untransmitted data in a .SM SOCK_STREAM send socket buffer when the socket is closed, either due to an explicit call to .C close() or because the application terminates normally or abnormally. The action is determined by the values of members of the .C struct linger data structure pointed to by .I optval in a call to .CR setsockopt() . The data type .C struct linger is defined in .RC < sys/socket.h >. If .C l_onoff is zero (the default action), .C close() returns immediately, but the system tries to transmit any unsent data and release the protocol connection gracefully. If .C l_onoff is non-zero and .C l_linger is zero, .C close() returns immediately, any unsent data is discarded, and the protocol connection is aborted. If both .C l_onoff and .C l_linger are non-zero, .C close() does not return until the system has tried to transmit all unsent data and release the connection gracefully. In that case, .C close() can return an error, and .C errno may be set to .SM ETIMEDOUT, if the system is unable to transmit the data after a protocol-defined time limit. Note that the value of .C l_linger is treated simply as a boolean; a non-zero value is .I not interpreted as a time limit( see .CR "_XOPEN_SOURCE_EXTENDED only" below). .C SO_LINGER does not affect the actions taken when the function .C shutdown() is called. .PP If .C SO_OOBINLINE is set, out-of-band data (TCP "urgent data") is left "in-line" among the normal data stream. In that case, the SIOCATMARK .C ioctl() request must be used to determine if the inbound data stream has been read up to the point where the out-of-band data begins. If multiple transmissions of out-of-band data are received before the application reads them, all of the data is left in-line; however, SIOCATMARK indicates the location of only the last transmission of out-of-band data. If .C SO_OOBINLINE is not set (default), only one byte of out-of-band is saved. This byte is pulled out of the normal data stream, and it is accessible only by setting .SM MSG_OOB in the .I flags parameter when the application reads the data (see .IR recv (2)). In that case, if multiple transmissions of out-of-band data are received before the application reads them, previous bytes of out-of-band data are lost. .PP If .C SO_PMTU is enabled for .SM SOCK_STREAM sockets (default), the Don't Fragment (DF) bit in IP datagrams is set for all TCP transmissions. If a datagram is dropped by a gateway because it is too big to be forwarded without fragmenting, the originating system will receive an ICMP "Datagram Too Big" message with the new PMTU information. TCP will automatically adjust to the new datagram size, and none of the TCP applications will be notified of the ICMP "Datagram Too Big" message. The dropped data will be retransmitted when the TCP retransmission timer expires. If .C SO_PMTU is disabled for .SM SOCK_STREAM sockets, the datagrams may be fragmented by intermediate gateways, which sometimes results in non-optimal network usage and lower throughput. .PP If .C SO_PMTU is enabled for .SM SOCK_DGRAM sockets, the application is notified of any ICMP "Datagram Too Big" messages received for the UDP port. The system notifies the corresponding UDP application by returning .C errno set to EAGAIN for the next call to .C send() or .CR recv() after the ICMP "Datagram Too Big" message is received. If the socket is using asynchronous I/O (see .SM FIOASYNC and .SM SIOCSPGRP in .IR socket (7)), the system also sends a SIGIO signal to the process or process group. As usual, the UDP application is responsible for handling the retransmission of any undelivered datagrams. If .C SO_PMTU is disabled for .SM SOCK_DGRAM sockets (default), UDP messages are automatically fragmented as needed. .PP Setting the .C SO_REUSEADDR option allows the local socket address to be reused in subsequent calls to .CR bind() . This permits multiple .SM SOCK_STREAM sockets to be bound to the same local address, as long as all existing sockets with the desired local address are in a connected state before .C bind() is called for a new socket. For .SM SOCK_DGRAM sockets, .C SO_REUSEADDR allows multiple sockets to receive UDP multicast datagrams addressed to the bound port number. For all .SM SOCK_DGRAM sockets bound to the same local address, .C SO_REUSEADDR must be set .I before calling .CR bind() . .PP .C SO_RCVBUF and .C SO_SNDBUF specify the maximum number of bytes that the system may allocate, as needed, for the receive and send buffers, respectively. These limits are merely approximate because of the way in which memory is allocated. For example, a large number of small transmissions may require more memory than the sum of the number of data bytes sent. The default receive and send buffer sizes are protocol-specific. For more information, see the appropriate manual entries, such as .IR tcp (7P) and .IR udp (7P). .PP For .SM SOCK_STREAM sockets, larger buffer sizes can improve performance. An application can increase the size of the receive buffer at any time; however, it can decrease the receive buffer size only prior to calling .C connect() or .CR listen() . An application can increase or decrease the send buffer at any time. .PP For .SM SOCK_DGRAM sockets, the size of the receive and send buffers limits the size of the maximum datagram that can be received and sent, respectively. These limits include socket buffer space that is also used to save the sender's socket address .RC ( "struct sockaddr" ) which is associated with each datagram transmission. The sender's socket address can be returned in the .I from parameter when .C recvfrom() is called (see .IR recv (2)). .RE .SS AF_CCITT .CR SO_SNDBUF and .CR SO_RCVBUF are the only options supported for sockets of the AF_CCITT address family. .SH _XOPEN_SOURCE_EXTENDED only The value of .C l_linger in the .I linger structure is interpreted as a time limit in seconds. .SH RETURN VALUE .CR getsockopt() and .CR setsockopt() return the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR getsockopt() or .CR setsockopt() fails, .CR errno is set to one of the following values: .TP 20 [EBADF] The argument .I s is not a valid descriptor. .TP [EFAULT] The .I optval or .I optlen address is not valid. .TP [EINVAL] The .I level or .I optlen value is not valid; or .I optval is the .SM NULL address; or the protocol connection has been released. .TP [ENOBUFS] Insufficient memory is available for internal system data structures. .TP [ENOPROTOOPT] The option is not recognized at the specified option level. .TP [ENOTSOCK] The argument .I s is not a socket descriptor. .TP [EOPNOTSUPP] The option is not supported by the socket family or socket type. .SH AUTHOR .CR getsockopt() and .CR setsockopt() were developed by the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO socket(2), getprotoent(3N), af_ccitt(7F), tcp(7P), udp(7P), unix(7P), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR getsockopt() ": XPG4" .\" .\" index@\f4getsockopt()\f1 \- get options on sockets@@@\f3getsockopt(2)\f1 .\" index@\f4setsockopt()\f1 \- set options on sockets@@@\f3getsockopt(2)\f1 .\" index@\f1options on sockets, get or set@@@\f3getsockopt(2)\f1 .\" index@\f1sockets, get or set options@@@\f3getsockopt(2)\f1 .\" .\" toc@\f3getsockopt(2)\f1:\0\0\f4getsockopt()\f1, \f4setsockopt()\f1@@@get or set options on sockets .\" toc@\f4setsockopt()\f1: set options on sockets@@@see \f3getsockopt(2)\f1 .\" .\" links@getsockopt.2 setsockopt.2 .\" $Header: gettimeofda.2,v 76.1 95/07/07 14:42:34 ssa Exp $ .TA g .TH gettimeofday 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gettimeofday \- get the date and time .SH SYNOPSIS .\" UX .PP .C #include .PP .C int gettimeofday(struct timeval *tp, void *tzp); .\"? .SH DESCRIPTION The .CR gettimeofday() function obtains the current time, expressed as seconds and microseconds since 00:00 Coordinated Universal Time (UTC), January 1, 1970, and stores it in the .CR timeval structure pointed to by .IR tp . The resolution of the system clock is unspecified. .PP If .IR tzp is not a null pointer, the behaviour is unspecified. .SH RETURN VALUE The .CR gettimeofday() function returns 0 and no value is reserved to indicate an error. .SH ERRORS No errors are defined. .SH SEE ALSO ctime(), ftime(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" $Header: gettimeofda.2,v 76.1 95/07/07 14:42:34 ssa Exp $ .TA g .TH gettimeofday 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP-\UX EXTENSIONS .sp 2 .SH SYNOPSIS .nf .C "#include " .PP .C "int gettimeofday(struct timeval *tp," .C " struct timezone *tzp);" .fi .SH DESCRIPTION The structures pointed to by .I tp and .I tzp are defined in .CR as: .nf .IP .C "struct timeval {" .C " unsigned long tv_sec; /* seconds since Jan. 1, 1970 */" .C " long tv_usec; /* and microseconds */" .C "};" .IP .C "struct timezone {" .C " int tz_minuteswest; /* of UTC */" .C " int tz_dsttime; /* type of DST correction to apply */" .C "};" .fi .PP The .C timezone structure indicates the local time zone (measured in minutes of time westward from UTC), and a flag that, if nonzero, indicates that Daylight Savings Time applies locally during the appropriate part of the year. Programs should use this time zone information only in the absence of the TZ environment variable. .SS Security Restrictions .PP Only a user with appropriate privileges can set the time of day. .SH RETURN VALUE .CR gettimeofday() return the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS .CR gettimeofday() fails, .CR errno is set to the following value. .RS .TP 15 [EFAULT] An argument address referenced invalid memory. The reliable detection of this error is implementation dependent. .RE .SH EXAMPLES The following example calls .CR gettimeofday() twice. It then computes the lapsed time between the calls in seconds and microseconds and stores the result in a timeval structure: .nf .IP .C "struct timeval first," .C " second," .C " lapsed;" .IP .C "struct timezone tzp;" .IP .C " gettimeofday (&first, &tzp);" .IP .C "/* lapsed time */" .IP .C " gettimeofday (&second, &tzp);" .IP .C "if (first.tv_usec > second.tv_usec) {" .C " second.tv_usec += 1000000;" .C " second.tv_sec--;" .C "}" .IP .C "lapsed.tv_usec = second.tv_usec - first.tv_usec;" .C "lapsed.tv_sec = second.tv_sec - first.tv_sec;" .fi .SH WARNINGS The microsecond value usually has a granularity much greater than one due to the resolution of the system clock. Relying on any granularity (particularly of one) will render code nonportable. .SH AUTHOR .CR gettimeofday() was developed by the University of California, Berkeley, and SecureWare Inc. .SH SEE ALSO date(1), stime(2), time(2), ctime(3C). .\" .\" index@\f4gettimeofday()\f1 \- get system clock date and time@@@\f3gettimeofday(2)\f1 .\" index@\f1get system clock date and time@@@\f3gettimeofday(2)\f1 .\" index@\f1system clock date and time, get@@@\f3gettimeofday(2)\f1 .\" index@\f1clock date and time, get system@@@\f3gettimeofday(2)\f1 .\" index@\f1date, get system clock@@@\f3gettimeofday(2)\f1 .\" index@\f1time, get system clock@@@\f3gettimeofday(2)\f1 .\" .\" toc@\f3gettimeofday(2)\f1:\0\0\f4gettimeofday()\f1@@@get date and time .\" $Header: getuid.2,v 74.1 95/05/10 21:05:10 ssa Exp $ .TA g .TH getuid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getuid, geteuid, getgid, getegid \- get real user, effective user, real group, and effective group \s-1ID\s0s .SH SYNOPSIS .C "#include " .PP .C "uid_t getuid(void);" .PP .C "uid_t geteuid(void);" .PP .C "gid_t getgid(void);" .PP .C "gid_t getegid(void);" .SH DESCRIPTION The following functions return the information indicated: .RS .TP 18 .C getuid() Real-user-\c .SM ID of the calling process. .TP .C geteuid() Effective-user-\c .SM ID of the calling process. .TP .C getgid() Real-group-\c .SM ID of the calling process. .TP .C getegid() Effective-group-\c .SM ID of the calling process. .RE .PP No means is available for ascertaining the saved-user-\c .SM ID or saved-group-\c .SM ID of a process. .SH SEE ALSO setuid(2). .SH STANDARDS CONFORMANCE .CR getuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getegid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR geteuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4getuid()\fP \(mi get real user \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\f4geteuid()\fP \(mi get effective user \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\f4getgid()\fP \(mi get real group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\f4getegid()\fP \(mi get effective group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@get: real or effective user or group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@\s-1ID\s+1, get real or effective user or group@@@\f3getuid(2)\f1 .\" index@user \s-1ID\s+1, get real or effective@@@\f3getuid(2)\f1 .\" index@group \s-1ID\s+1: get real or effective group \s-1ID\s+1@@@\f3getuid(2)\f1 .\" index@real or effective user or group \s-1ID\s+1, get@@@\f3getuid(2)\f1 .\" index@effective or real user or group \s-1ID\s+1, get@@@\f3getuid(2)\f1 .\" .\" toc@\f3getuid(2)\f1:\0\0\f4getuid()\fP, \f4geteuid()\fP, \n\f4getgid()\fP, \f4getegid()\fP@@@get real user, effective user, real group, and effective group \s-1ID\s+1s .\" toc@\f4geteuid()\fP:\0\0get effective user group \s-1ID\s+1@@@see \f3getuid(2)\f1 .\" toc@\f4getgid()\fP:\0\0get real group \s-1ID\s+1@@@see \f3getuid(2)\f1 .\" toc@\f4getegid()\fP:\0\0get effective group \s-1ID\s+1@@@see \f3getuid(2)\f1 .\" .\" links@getuid.2 geteuid.2 .\" links@getuid.2 getgid.2 .\" links@getuid.2 getegid.2 .\" .\" fileset_database@getuid.2 PROGRAMING-MAN .\" $Header: stty.2,v 72.4 94/10/27 14:25:21 ssa Exp $ .TA s .TH stty 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME stty(), gtty() \- control terminal device (Bell Version 6 compatibility) .SH SYNOPSIS .C "#include " .PP .C "int stty(int fildes, const struct sgttyb *argp);" .PP .C "int gtty(int fildes, struct sgttyb *argp);" .SS Remarks These system calls are preserved for backward compatibility with Bell Version 6. They provide as close an approximation as possible to the old Version 6 functions. All new code should use the .CR TCSETA and .CR TCGETA .CR ioctl() calls described in .IR termio (7). .SH DESCRIPTION For certain status settings and status inquiries about terminal devices, the functions .CR stty() and .CR gtty() are equivalent to .IP .C "ioctl(fildes, TIOCSETP, argp)" .PP and .IP .C "ioctl(fildes, TIOCGETP, argp)" .PP respectively (see .IR ioctl (2) and .IR termio (7). .SH RETURN VALUE .CR gtty() and .CR stty() return the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR gtty() or .CR stty() fails, .CR errno is set to one of the following values: .TP 15 [EBADF] .CR fildes is not a valid file descriptor. .TP [EFAULT] .CR argp points to an invalid address. .SH SEE ALSO stty(1), exec(2), ioctl(2), sttyV6(7), termio(7), tty(7). .\" .\" index@\f4gtty()\f1 \- control terminal device (Bell Version 6 compatibility)@@@\f3stty(2)\f1 .\" index@\f4stty()\f1 \- control terminal device (Bell Version 6 compatibility)@@@\f3stty(2)\f1 .\" index@\f1control terminal device (Bell Version 6 compatibility)@@@\f3stty(2)\f1 .\" index@\f1terminal device, control (Bell Version 6 compatibility)@@@\f3stty(2)\f1 .\" index@\f1device, control terminal (Bell Version 6 compatibility)@@@\f3stty(2)\f1 .\" .\" links@stty.2 gtty.2 .\" .\" toc@\f3stty(2)\f1:\0\0\f4stty()\f1, \f4gtty()\f1@@@control terminal device (Bell Version 6 compatibility) .\" toc@\f4gtty()\f1:\0\0control terminal device (Bell Version 6 compatibility)@@@see \f3stty(2)\f1 .\" $Header: intro.2,v 72.3 93/01/14 14:33:38 ssa Exp $ .TA a .TH intro 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME intro \- introduction to system calls .SH DESCRIPTION This section describes all of the system calls. All of these calls return a function result. This result indicates the status of the call. Typically, a zero or positive result indicates that the call completed successfully, and \(mi1 indicates an error. The individual descriptions specify the details. An error number is also made available in the external variable .C errno (see .IR errno (2)). Note: .C errno is not cleared on successful calls. Therefore, it should be tested only after an error has been indicated. .SH SEE ALSO intro(3), errno(2), hier(5). .PP The introduction to this manual. .\" index@introduction to system calls@@@\f3intro(2)\f1 .\" index@system calls, introduction to@@@\f3intro(2)\f1 .\" .\" toc@\f3intro(2)\f1:\0\0\f2intro\f1@@@introduction to system calls .\" .\" fileset_database@intro.2 PROGRAMING-MAN .\" $Header: ioctl.2,v 72.6 94/11/14 15:24:18 ssa Exp $ .TA i .TH ioctl 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ioctl \- control device .SH SYNOPSIS .C "#include " .PP .C "int ioctl(int fildes, int request, ... /* arg */);" .SS Remarks The ANSI C "\c .CR ", ...\$\c" " construct denotes a variable length argument list whose optional [or required] \" EDITOR: make this line fit the specific page members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION .C ioctl() performs a variety of functions on character special files (devices), or regular files and directories on VxFS file systems. The write-ups of various devices in Section (7) discuss how .CR ioctl() applies to them. The type of .I arg is dependent on the specific .CR ioctl() call, as described in Section (7). .PP .I request is made up of several fields which encode the size and direction of the argument (referenced by .IR arg ), as well as the desired command. An enumeration of the request fields are: .RS .TP 20 .C IOC_IN Argument is read by the driver (meaning that the argument is copied from the application to the driver). .TP .C IOC_OUT Argument is written by the driver (meaning that the argument is copied from the driver to the application). Ignored if an error occurs. .TP .C IOCSIZE_MASK Number of bytes in the passed argument. A nonzero size indicates that .I arg is a pointer to the passed argument. A zero size indicates that .I arg is the passed argument (if the driver wants to use it), and is not treated as a pointer. .TP .C IOCCMD_MASK The request command itself. .RE .PP When both .CR IOC_IN and .CR IOC_OUT are zero, it can be assumed that .I request is not encoded for size and direction, for compatibility purposes. Requests that do not require any data to be passed and requests that use .I arg as a value (as opposed to a pointer), have the .CR IOC_IN bit set to one and the .CR IOCSIZE_MASK field set to zero. .PP The following macros are used to create the request argument. .I x and .I y are concatenated .RC ( "(x<<8) | y" ) to form .CR IOCCMD and shifted into the proper location according to .CR IOCCMD_MASK . .CR t is the type (e.g. .CR "struct hpib_cmd" ) of the actual argument that the request references, and its size is taken and shifted into the appropriate place according to .CR IOCSIZE_MASK . .RS .TP 20 .C _IOR(x,y,t) Sets .CR IOC_OUT and initializes the values at .CR IOCCMD_MASK and .CR IOCSIZE_MASK accordingly. .TP .C _IOW(x,y,t) Sets .CR IOC_IN and initializes the values at .CR IOCCMD_MASK and .CR IOCSIZE_MASK accordingly. .TP .C _IOWR(x,y,t) Sets both .CR IOC_IN and .CR IOC_OUT and initializes the values at .CR IOCCMD_MASK and .CR IOCSIZE_MASK . .RE .PP Note: any data structure referenced by .I arg must .I not contain any pointers. .SH RETURN VALUE If an error has occurred, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .CR ioctl() fails if one or more of the following are true: IOC_OUT is ignored if an error occurs. .RS .TP 15 [EBADF] .I fildes is not a valid open file descriptor. .TP [ENOTTY] The request is not appropriate to the selected device. .TP [EINVAL] .I request or .I arg is not valid. .TP [EINTR] A signal was caught during the .CR ioctl() system call. .TP [EPERM] Typically this error indicates that an ioctl request was attempted that is forbidden in some way to the calling process. .RE .SH WARNINGS Check all references to .IR signal (5) for appropriateness on systems that support .IR sigvector (2). .IR sigvector (2) can affect the behavior described on this page. .SH AUTHOR .CR ioctl() was developed by AT&T and HP. .SH "SEE ALSO" ioctl(5), arp(7), socket(7), termio(7). .SH STANDARDS CONFORMANCE .CR ioctl() ": SVID2, SVID3, XPG2" .\" .\" index@\f4ioctl()\f1 \(mi control character device special file@@@\f3ioctl(2)\f1 .\" index@control character device special file@@@\f3ioctl(2)\f1 .\" index@I/O, control character device special file@@@\f3ioctl(2)\f1 .\" index@character device special file, control@@@\f3ioctl(2)\f1 .\" index@device special file, control character@@@\f3ioctl(2)\f1 .\" index@special file, control character device@@@\f3ioctl(2)\f1 .\" .\" toc@\f3ioctl(2)\f1:\0\0\f4ioctl()\fP@@@control device .\" .\" fileset_database@ioctl.2 PROGRAMING-MAN .\" $Header: iscomsec.2,v 72.2 94/08/30 16:20:17 ssa Exp $ .TA i .TH iscomsec 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iscomsec \- check if the system has been converted to a trusted system. .SH SYNOPSIS .nf .CR "#include .PP .CR "int iscomsec();" .fi .SH DESCRIPTION .CR iscomsec returns a zero (0) if the system is not a trusted system. If the system has been converted to a trusted system, .CR iscomsec returns a one (1). .PP .SH NOTES .CR iscomsec determines if the system is a trusted system or not by checking the file, .CR /tcb/files/auth/system/default. If the file exists, then the system is a trusted system. If the file does not exist, then the system is not a trusted system. On a trusted system, .CR /tcb/files/auth/system/default should never be deleted. .PP .SH AUTHOR .CR iscomsec was developed by HP. .PP .SH FILES .TP 50 .CR /tcb/files/auth/system/default Trusted system default file .PD 0 .\" .\" index@\f4iscomsec\f1 \- check if system has been converted to a trusted system@@@\f3iscomsec(2)\f1 .\" index@\f1check if system has been converted to a trusted system@@@\f3iscomsec(2)\f1 .\" index@\f1trusted system, check if converted@@@\f3iscomsec(2)\f1 .\" index@\f1converted trusted system, check if@@@\f3iscomsec(2)\f1 .\" .\" toc@\f3iscomsec(2)\f1:\0\0\f4iscomsec()\f1@@@check if system has been converted to a trusted system .\" .\" fileset_database@iscomsec.2 UX-CORE-MAN?? .\" $Header: kill.2,v 72.6 94/11/14 15:24:25 ssa Exp $ .TA k .TH kill 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME kill(), raise() \- send a signal to a process or a group of processes .SH SYNOPSIS .C "#include " .PP .C "int kill(pid_t pid, int sig);" .PP .C "int raise(int sig);" .SH DESCRIPTION The .CR kill() system call sends a signal to a process or a group of processes, as specified by .IR pid . The signal to be sent is specified by .I sig and is either one from the list given in .IR signal (2), or .CR 0 . .PP The .CR raise() system call sends a signal to the executing program. The signal to be sent is specified by .I sig and is either one from the list given in .IR signal (2), or .CR 0 . .PP If .I sig is .CR 0 (the null signal), error checking is performed but no signal is actually sent. This can be used to check the validity of .IR pid . .PP The real or effective user ID of the sending process must match the real or saved user ID of the receiving process unless the effective user ID of the sending process is a user who has appropriate privileges. .PP As a single special case, the continue signal .CR SIGCONT can be sent to any process that is a member of the same session as the sending process. .PP The value .CR KILL_ALL_OTHERS is defined in the file .CR and is guaranteed not to be the ID of any process in the system or the negation of the ID of any process in the system. .PP If .I pid is greater than zero and not equal to .CR KILL_ALL_OTHERS , .I sig is sent to the process whose process ID is equal to .IR pid . .I pid can equal .CR 1 unless .IR sig is .CR SIGKILL or .CR SIGSTOP . .PP If .I pid is .CR 0 , .I sig is sent to all processes excluding special system processes whose process group ID is equal to the process group ID of the sender. .PP If .I pid is .CR \-1 and the effective user ID of the sender is not a user who has appropriate privileges. .I sig is sent to all processes excluding special system processes whose real or saved user ID is equal to the real or effective user ID of the sender. .PP If .I pid is .CR \-1 and the effective user ID of the sender is a user who has appropriate privileges, .I sig is sent to all processes excluding special system processes. .PP If .I pid is .CR KILL_ALL_OTHERS , .CR kill() behaves much as when .I pid is equal to .CR \-1 , except that .I sig is not sent to the calling process. .PP If .I pid is negative but not .CR \-1 or .CR KILL_ALL_OTHERS , .I sig is sent to all processes (excluding special system processes) whose process group ID is equal to the absolute value of .IR pid , and whose real and/or effective user ID meets the constraints described above for matching user IDs. .SH RETURN VALUE Upon successful completion, a value of .CR 0 is returned. Otherwise, a value of .CR \-1 is returned and .CR errno is set to indicate the error. .SH ERRORS .PP If .CR kill() fails, no signal is sent. .CR errno is set to one of the following values. .RS .TP 15 [EINVAL] .I sig is neither a valid signal number nor zero. .TP [EINVAL] .I sig is .CR SIGKILL or .CR SIGSTOP and .I pid is .CR 1 (process 1). .TP [EPERM] The user ID of the sending process is not a user who has appropriate privileges and its real or effective user ID does not match the real or saved user ID of the receiving process. .TP [EPERM] The sending and receiving processes are not in the same session and the real or effective user ID does not match the real or saved user ID of the receiving process. .TP [ESRCH] No process or process group can be found corresponding to that specified by .IR pid . .RE .PP If .CR raise() fails, no signal is sent. .CR errno is set to one of the following values. .RS .TP 15 [EINVAL] .I sig is neither a valid signal number nor zero. .RE .SH AUTHOR .CR kill() was developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO kill(1), getpid(2), setsid(2), signal(2). .SH STANDARDS CONFORMANCE .CR kill() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR raise() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4kill()\f1 \- send signal to process or group of processes@@@\f3kill(2)\f1 .\" index@\f4raise()\f1 \- send signal to executing program@@@\f3kill(2)\f1 .\" index@\f1send signal to executing program@@@\f3kill(2)\f1 .\" index@\f1executing program, send signal@@@\f3kill(2)\f1 .\" index@\f1process or group of processes, send signal@@@\f3kill(2)\f1 .\" index@\f1group of processes, send signal@@@\f3kill(2)\f1 .\" index@\f1signal, send to process or group of processes@@@\f3kill(2)\f1 .\" index@\f1software signal, send to process or group of processes@@@\f3kill(2)\f1 .\" .\" toc@\f3kill(2)\f1:\0\0\f4kill()\f1, \f4raise()\f1@@@send a signal to a process or a group of processes .\" toc@\f4raise()\f1:\0\0send a signal to executing program@@@see \f3kill(2)\f1 .\" .\" links@kill.2 raise.2 .\" $Header: bsdproc.2,v 72.3 93/01/14 14:32:23 ssa Exp $ .TA b .TH bsdproc 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME killpg, getpgrp, setpgrp, sigvec, signal \- 4.2 \s-1BSD\s0-compatible process control facilities .SH SYNOPSIS .C "#include " .PP .C "int killpg(int pgrp, int sig);" .PP .C "int getpgrp(int pid);" .PP .C "int setpgrp(int pid, int pgrp);" .PP .C "int sigvec(" .PD 0 .nf .IP .C "int sig," .C "struct sigvec *vec," .C "struct sigvec *ovec" .PP .C ");" .fi .PD .PP .C "void (*signal(int sig, void (*func)(int)))(int);" .SH DESCRIPTION These calls simulate (and are provided for backward compatibility with) functions of the same name in the 4.2 Berkeley Software Distribution. .PP This version of .C setpgrp() is equivalent to the system call .IR setpgid ( \|pid , \ pgrp\| ) (see .IR setpgid (2)). .PP This version of .C getpgrp() is equivalent to the system call .CI getpgrp2( \|pid\| ) (see .IR getpid (2)). .PP .C killpg() is equivalent to the system call .CI kill(- pgrp , \0sig ) (see .IR kill (2)). .PP .C sigvec() is equivalent to the system call .CI sigvector( sig , .IC vec , \ ovec ) (see .IR sigvector (2)), except for the following: .IP When .SM SIGCHLD or .SM SIGCLD is used and .I vec specifies a catching function, the routine acts as if the .C SV_BSDSIG flag were included in the .C sv_flags field of .IR vec . .IP The name .C sv_onstack can be used as a synonym for the name of the .C sv_flags field of .I vec and .IR ovec . .IP If .I vec is not a null pointer and the value of .RI ( vec \(mi> sv_flags & 1) is "true", the routine acts as if the .C SV_ONSTACK flag were set. .IP If .I ovec is not a null pointer, the flag word returned in .IR ovec \(mi> sv_flags (and therefore the value of .IR ovec \(mi> sv_onstack ) will be equal to 1 if the system was reserving space for processing of that signal because of a call to .IR sigspace (2), and 0 if not. The .C SV_BSDSIG bit in the value placed in .IR ovec \(mi> sv_flags is always clear. .IP If the reception of a caught signal occurs during certain system calls, the call will always be restarted, regardless of the return value from a catching function installed with .CR sigvec() . The affected calls are .IR wait (2), .IR semop (2), .IR msgsnd (2), .IR msgrcv (2), and .IR read (2) or .IR write (2) on a slow device (such as a terminal or pipe, but not a file). Other interrupted system calls are not restarted. .PP This version of .C signal() has the same effect as .CR sigvec ( sig , .IC vec , \ ovec )\c \&, where .IR vec \(mi> sv_handler is equal to .IR func , .IR vec \(mi> sv_mask is equal to 0, and .IR vec \(mi> sv_flags is equal to 0. .C signal() returns the value that would be stored in .IR ovec \(mi> sv_handler if the equivalent .CR sigvec() call would have succeeded. Otherwise, .C signal() returns \(mi1 and .C errno is set to indicate the reason as it would have been set by the equivalent call to .CR sigvec() . .PP These functions can be linked into a program by giving the .C -lBSD option to .IR ld (1). .SH WARNINGS While the 4.3 .SM BSD release defined extensions to some of the interfaces described here, only the 4.2 .SM BSD interfaces are emulated by this package. .PP .C bsdproc() should not be used in conjunction with the facilities described under .IR sigset (2V). .SH AUTHOR .C bsdproc() was developed by HP and the University of California, Berkeley. .SH SEE ALSO ld(1), kill(2), getpid(2), msgsnd(2), msgrcv(2), read(2), semop(2), setpgid(2), setsid(2), sigvector(2), wait(2), write(2), sigset(2V), sigstack(2), signal(5). .\" index@\f4killpg()\fP \(mi 4.2 \s-1BSD\s+1-compatible \f4kill()\fP system call@@@\f3bsdproc(2)\f1 .\" index@\f4sigvec()\fP \(mi 4.2 \s-1BSD\s+1-compatible \f4sigvec()\fP system call@@@\f3bsdproc(2)\f1 .\" index@\f4signal()\fP \(mi 4.2 \s-1BSD\s+1-compatible \f4signal()\fP system call@@@\f3bsdproc(2)\f1 .\" index@\s-1BSD-4.2\s+1-compatible \f4kill()\fP, \f4sigvec()\fP, and \f4signal()\fP system calls@@@\f3bsdproc(2)\f1 .\" index@system calls, \s-1BSD-4.2\s+1-compatible \f4kill()\fP, \f4sigvec()\fP, and \f4signal()\fP@@@\f3bsdproc(2)\f1 .\" index@calls, system, \s-1BSD-4.2\s+1-compatible \f4kill()\fP, \f4sigvec()\fP, and \f4signal()\fP@@@\f3bsdproc(2)\f1 .\" index@\f4kill()\fP system call, 4.2 \s-1BSD\s+1-compatible@@@\f3bsdproc(2)\f1 .\" index@\f4sigvec()\fP system call, 4.2 \s-1BSD\s+1-compatible@@@\f3bsdproc(2)\f1 .\" index@\f4signal()\fP system call, 4.2 \s-1BSD\s+1-compatible@@@\f3bsdproc(2)\f1 .\" .\" toc@\f3bsdproc(2)\f1:\0\0\f4killpg()\fP, \f4getpgrp()\fP, \f4setpgrp()\fP, \f4sigvec()\fP,\n\f4signal()\fP@@@4.2 \s-1BSD\s+1-compatible process control facilities .\" toc@\f4killpg()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" toc@\f4getpgrp()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" toc@\f4setpgrp()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" toc@\f4sigvec()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" toc@\f4signal()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" .\" links@bsdproc.2 killpg.2 .\" links@bsdproc.2 sigvec.2 .\" .\" fileset_database@bsdproc.2 PROGRAMING-MAN .\" $Header: chown.2,v 78.1 96/01/19 20:09:55 ssa Exp $ .TA c .TH chown 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chown(), fchown(), lchown() \- change owner and group of a file .SH SYNOPSIS .C "#include " .PP .C "int chown(const char *path, uid_t owner, gid_t group);" .PP .C "int lchown(const char *path, uid_t owner, gid_t group);" .PP .C "int fchown(int fildes, uid_t owner, gid_t group);" .SH DESCRIPTION The .CR chown() system call changes the user and group ownership of a file. .IR path points to the path name of a file. .CR chown() sets the owner ID and group ID of the file to the numeric values contained in .IR owner and .IR group respectively. A value of .CR UID_NO_CHANGE or .CR GID_NO_CHANGE can be specified in .IR owner or .IR group to leave unchanged the file's owner ID or group ID, respectively. Note that .IR owner and .IR group should be less than .CR UID_MAX (see .IR limits (5)). .PP Only processes with an effective user ID equal to the file owner or a user having appropriate privileges can change the ownership of a file. If privilege groups are supported, the owner of a file can change the ownership only as a member of a privilege group allowing CHOWN, as set up by the .CR setprivgrp command (see .IR setprivgrp (1M)). All users get the CHOWN privilege by default. .PP The group ownership of a file can be changed to any group in the current process's access list or to the real or effective group ID of the current process. If privilege groups are supported and the user has the CHOWN privilege, the file can be given to any group. .PP If .CR chown() is invoked on a regular file by anyone other than the superuser, the set-user-ID and set-group-ID bits of the file mode are cleared. Whether .CR chown() preserves or clears these bits on files of other types is implementation dependent. .PP If the path given to .CR chown() contains a symbolic link as the last element, this link is traversed and path name resolution continues. .CR chown() changes the owner and group of the symbolic link's target, rather than the owner and group of the link. .PP The .CR fchown() system call functions exactly like .CR chown() , exept that it operates on a file descriptor instead of a path name. .IR fildes is a file descriptor. .PP The .CR lchown() system call sets the owner ID and group ID of the named file just as .CR chown() does, except in the case where the named file is a symbolic link. In this case, .CR lchown() changes the owner and group of the symbolic link file itself. .SS "Access Control Lists - HFS File Systems Only A user can allow or deny specific individuals and groups access to a file by using the file's access control list (see .IR acl (5)). When using .CR chown () in conjunction with ACLs, if the new owner and/or group does not have an optional ACL entry corresponding to .IC user .% and/or .CI %. group in the file's access control list, the file's access permission bits remain unchanged. However, if the new owner and/or group is already designated by an optional ACL entry of .IC user .% and/or .CI %. group\f1, .CR chown() sets the file's permission bits (and the three basic ACL entries) to the permissions contained in that entry. .SH RETURN VALUE .CR chown() and .CR fchown() return the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. The owner and group of the file remain unchanged. .CR errno is set to indicate the error. .PD .SH ERRORS If .CR chown() or .CR fchown() fails, .CR errno is set to one of the following values: .TP 15 [EACCES] Search permission is denied on a component of the path prefix. .TP [EBADF] .IR fildes is not a valid file descriptor. .TP [EFAULT] .IR path points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP [EINVAL] Either .IR owner or .IR group is greater than or equal to .CR UID_MAX , or is an illegal negative value. .TP [ELOOP] Too many symbolic links were encountered in translating .IR path . .TP [ENAMETOOLONG] A component of .IR path exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect, or .IR path exceeds .CR PATH_MAX bytes. .TP [ENOENT] The file named by .IR path does not exist. .TP [ENOTDIR] A component of the path prefix is not a directory. .TP [EPERM] The effective user ID is not a user having appropriate privileges and one or more of the following conditions exist: .RS .TP 3 \(bu The effective user ID does not match the owner of the file. .TP \(bu When changing the owner of the file, the owner of the file is not a member of a privilege group allowing the CHOWN privilege. .TP \(bu When changing the group of the file, the owner of the file is not a member of a privilege group allowing the CHOWN privilege and the group number is not in the current process's access list. .RE .TP [EROFS] The named file resides on a read-only file system. .SH AUTHOR .CR chown() was developed by AT&T. .PP .CR fchown() was developed by the University of California, Berkeley. .SH SEE ALSO chown(1), setprivgrp(1M), chmod(2), setacl(2), acl(5), limits(5). .SH STANDARDS CONFORMANCE .CR chown() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR fchown() ": AES, SVID3" .\" .\" index@\f4chown()\f1 \- change owner and group of a file@@@\f3chown(2)\f1 .\" index@\f4fchown()\f1 \- change owner and group of a file@@@\f3chown(2)\f1 .\" index@\f1file: change owner and group@@@\f3chown(2)\f1 .\" index@\f1change owner and group of a file@@@\f3chown(2)\f1 .\" index@\f1owner and group of a file, change@@@\f3chown(2)\f1 .\" index@\f1group and owner of a file, change@@@\f3chown(2)\f1 .\" .\" toc@\f3chown(2)\f1:\0\0\f4chown()\f1, \f4fchown()\f1@@@change owner and group of a file .\" toc@\f4fchown()\f1:\0\0change owner and group of a file@@@see \f3chown(2)\f1 .\" .\" links@chown.2 fchown.2 .\" links@chown.2 lchown.2 .\" $Header: link.2,v 72.5 94/11/14 15:24:31 ssa Exp $ .TA l .TH link 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME link() \- link to a file .SH SYNOPSIS .C "#include .PP .C "int link(const char *path1, const char *path2);" .SH DESCRIPTION The .CR link() system call creates a new link (directory entry) for the existing file. .I path1 points to a path name naming an existing file. .I path2 points to a path name naming the new directory entry to be created. .SH RETURN VALUE Upon successful completion, .CR link() returns zero. Otherwise, it returns \(mi1 and sets .CR errno (see .IR errno (2)) to indicate the error. .SH ERRORS The .CR link() system call fails and no link is created if one or more of the following is true: .RS .TP 25 [EACCES] A component of either path prefix denies search permission. .TP [EACCES] The requested link requires writing in a directory that does not permit writing. .TP [EDQUOT] The user's disk quota block limit has been reached for this file system. .TP [EEXIST] The link named by .I path2 exists. .TP [ENOENT] The file named by .I path1 does not exist. .TP [ENOENT] A component of either path prefix does not exist. .TP [ENOENT] .I path2 points to a null path name. .TP [ENOSPC] The directory to contain the file cannot be extended. .TP [ENOTDIR] A component of either path prefix is not a directory. .TP [EPERM] The file named by .I path1 is a directory and the effective user ID is not a user who has appropriate privileges. Some file systems return this error whenever .I path1 names a directory, regardless of the user ID. .TP [EXDEV] The link named by .I path2 and the file named by .I path1 are on different logical devices (file systems). .TP [EROFS] The requested link requires writing in a directory on a read-only file system. .TP [EFAULT] .I path points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP [ENOENT] .I path1 or .I path2 is null. .TP [EMLINK] The maximum number of links to a file would be exceeded. .TP [ENAMETOOLONG] Either the specified path exceeds .CR PATH_MAX bytes, or a component of either specified path exceeds .CR NAME_MAX while .CR POSIX_NO_TRUNC is in effect. .TP [ELOOP] Too many symbolic links were encountered in translating either path name. .RE .SH DEPENDENCIES .SS Series 700 If .I path2 names a symbolic link, .CR link() fails without creating the link, it returns \(mi1, and sets .CR errno to the following value: .RS .TP 25 [EEXIST] .I path2 names a symbolic link. .RE .SH SEE ALSO cp(1), link(1M), symlink(2), unlink(2), symlink(4). .SH STANDARDS CONFORMANCE .CR link() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4link()\f1 \- link additional name to an existing file@@@\f3link(2)\f1 .\" index@\f1file, link additional name to an existing@@@\f3link(2)\f1 .\" .\" toc@\f3link(2)\f1:\0\0\f4link()\f1@@@link to a file\f1 .\" $Header: listen.2,v 78.2 96/03/15 15:59:15 ssa Exp $ .TA l .TH listen 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME listen \- listen for connections on a socket .SH SYNOPSIS .C "#include " .PP .C "int listen(int s, int backlog);" .SH DESCRIPTION To accept connections, a socket is first created using .CR socket() , a queue for incoming connections is activated using .CR listen() , and then connections are accepted using .CR accept() . .C listen() applies only to unconnected sockets of type .SM SOCK_STREAM. If the socket has not been bound to a local port before .C listen() is invoked, the system automatically binds a local port for the socket to listen on (see .IR inet (7F)). For sockets in the address family .SM AF_CCITT, the socket .I must be bound to an address by using .C bind() before connection establishment can continue, otherwise an .SM EADDREQUIRED error is returned. .PP A listen queue is established for the socket specified by the .I s parameter, which is a socket descriptor. .PP .I backlog defines the desirable queue length for pending connections. The actual queue length may be greater than the specified .I backlog . If a connection request arrives when the queue is full, the client will receive an .SM ETIMEDOUT error. .PP .I backlog is limited to the range of 0 to .CR SOMAXCONN, which is defined in .CR . .CR SOMAXCONN is currently set to 20. If any other value is specified, the system automatically assigns the closest value within the range. A .I backlog of 0 specifies only 1 pending connection is allowed at any given time. .SH DEPENDENCIES .SS \s-1AF_CCITT\s0: Call-acceptance can be controlled by the .C X25_CALL_ACPT_APPROVAL .C ioctl() call described in .SM RETURN VALUE . Upon successful completion, .C listen() returns 0; otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C listen() fails if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .I s is not a valid file descriptor. .TP .SM [EDESTADDRREQ] The socket .I s has not been bound to an address by using .C bind() . .TP .SM [ENOTSOCK] .I s is a valid file descriptor but it is not a socket. .TP .SM [EOPNOTSUPP] The socket referenced by .I s does not support .C listen() . .TP .SM [EINVAL] The socket has been shut down or is already connected (see .IR socketx25 (7)). .RE .SH AUTHOR .C listen() was developed by the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO accept(2), connect(2), socket(2), socketx25(7), af_ccitt(7F), inet(7F), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR listen() ": XPG4" .\" .\" index@\f4listen()\fP \(mi listen for connections on a socket@@@\f3listen(2)\f1 .\" index@listen for connections on a socket@@@\f3listen(2)\f1 .\" index@connections on a socket, listen for@@@\f3listen(2)\f1 .\" index@socket, listen for connections on a@@@\f3listen(2)\f1 .\" .\" toc@\f3listen(2)\f1:\0\0\f4listen()\fP@@@listen for connections on a socket .\" .\" $Header: lockf.2,v 78.1 96/02/12 14:03:12 ssa Exp $ .TA l .TH lockf 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lockf \- provide semaphores and record locking on files .SH SYNOPSIS .C "#include " .PP .C "int lockf(int fildes, int function, off_t size);" .SH DESCRIPTION The .CR lockf() function allows regions of a file to be used as semaphores (advisory locks) or restricts access to only the locking process (enforcement-mode record locks). Other processes that attempt to access the locked resource either return an error or sleep until the resource becomes unlocked. All locks for a process are released upon the first close of the file, even if the process still has the file opened, and all locks held by a process are released when the process terminates. .PP .I fildes is an open file descriptor. The file descriptor must have been opened with write-only permission .RC ( O_WRONLY ) or read-write permission .RC ( O_RDWR ) in order to establish a lock with this function call (see .IR open (2)). .PP If the calling process is a member of a group that has the .CR PRIV_LOCKRDONLY privilege (see .IR setprivgrp (2)), it can also use .CR lockf() to lock files opened with read-only permission .RC ( O_RDONLY ). .PP .I function is a control value that specifies the action to be taken. Permissible values for .I function are defined in .CR as follows: .nf .IP .C "#define F_ULOCK 0 /* unlock a region */" .C "#define F_LOCK 1 /* lock a region */" .C "#define F_TLOCK 2 /* test and lock a region */" .C "#define F_TEST 3 /* test region for lock */" .fi .PP All other values of .I function are reserved for future extensions and result in an error return if not implemented. .PP .CR F_TEST is used to detect whether a lock by another process is present on the specified region. .CR lockf() returns zero if the region is accessible and .CR \(mi1 if it is not; in which case .CR errno is set to EACCES. .CR F_LOCK and .CR F_TLOCK both lock a region of a file if the region is available. .CR F_ULOCK removes locks from a region of the file. .PP .I size is the number of contiguous bytes to be locked or unlocked. The resource to be locked starts at the current offset in the file, and extends forward for a positive .IR size , and backward for a negative .I size (the preceding bytes up to but not including the current offset). If .I size is zero, the region from the current offset through the end of the largest possible file is locked (that is, from the current offset through the present or any future end-of-file). An area need not be allocated to the file in order to be locked, because such locks can exist past the end of the file. .PP Regions locked with .CR F_LOCK or .CR F_TLOCK can, in whole or in part, contain or be contained by a previously locked region for the same process. When this occurs or if adjacent regions occur, the regions are combined into a single region. If the request requires that a new element be added to the table of active locks but the table is already full, an error is returned, and the new region is not locked. .PP .CR F_LOCK and .CR F_TLOCK requests differ only by the action taken if the resource is not available: .CR F_LOCK causes the calling process to sleep until the resource is available, whereas .CR F_TLOCK returns an EACCES error if the region is already locked by another process. .PP .CR F_ULOCK requests can, in whole or part, release one or more locked regions controlled by the process. When regions are not fully released, the remaining regions are still locked by the process. Releasing the center section of a locked region requires an additional element in the table of active locks. If this table is full, an EDEADLK error is returned, and the requested region is not released. .PP Regular files with the file mode of .CR S_ENFMT , not having the group execute bit set, will have an enforcement policy enabled. With enforcement enabled, reads and writes that would access a locked region sleep until the entire region is available if .CR O_NDELAY is clear, but return \(mi1 with .CR errno set if .CR O_NDELAY is set. File access by other system functions, such as .CR exec() , are not subject to the enforcement policy. Locks on directories, pipes, and special files are advisory only; no enforcement policy is used. .ift .bp .PP A potential for deadlock occurs if a process controlling a locked resource is put to sleep by accessing the locked resource of another process. Thus, calls to .CR fcntl() , .CR lockf() , .CR read() , or .CR write() (see .IR fcntl (2), .IR lockf (2), .IR read (2), and .IR write (2)) scan for a deadlock prior to sleeping on a locked resource. Deadlock is not checked for the .CR wait() and .CR pause() system calls (see .IR wait (2) and .IR pause (2)), so potential for deadlock is not eliminated. A .CR creat() call or an .CR open() call with the .CR O_CREATE and .CR O_TRUNC flags set on a regular file returns error EAGAIN if another process has locked part of the file and the file is currently in enforcement mode. .SH NETWORKING FEATURES .SS NFS The advisory record-locking capabilities of .CR lockf() are implemented throughout the network by the ``network lock daemon'' (see .IR lockd (1M)). If the file server crashes and is rebooted, the lock daemon attempts to recover all locks associated with the crashed server. If a lock cannot be reclaimed, the process that held the lock is issued a .CR SIGLOST signal. .PP Only advisory record locking is implemented for NFS files. .SH RETURN VALUE Upon successful completion, a value of .CR 0 is returned. Otherwise, a value of .CR \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS .CR lockf() fails if any of the following occur: .RS .TP 15 [EACCES] .I function is .CR F_TLOCK or .CR F_TEST and the region is already locked by another process. .TP [EBADF] .I fildes is not a valid, open file descriptor. .TP [EDEADLK] A deadlock would occur or the number of entries in the system lock table would exceed a system-dependent maximum. HP-UX guarantees this value to be at least 50. .TP [EAGAIN] .I function is .CR F_LOCK or .CR F_TLOCK and the file is mapped in to virtual memory via the .CR mmap() system call (see .IR mmap (2)). .TP [EINTR] A signal was caught during the .CR lockf() system call. .TP [EINVAL] Either .I function is not one of the functions specified above, or .I size plus current offset produces a negative offset into the file. .TP [EINVAL] .I size plus current offset cannot be represented correctly by an object of size .C off_t. .TP [ENOLCK] Either .I function is .CR F_TLOCK or .CR F_LOCK and the file is an NFS file with access bits set for enforcement mode, or the file is an NFS file and a system error occurred on the remote node. .RE .SH WARNINGS Deadlock conditions may arise when either the .CR wait() or .CR pause() system calls are used in conjunction with enforced locking (see .IR wait (2) and .IR pause (2) for details). .PP When a file descriptor is closed, all locks on the file from the calling process are deleted, even if other file descriptors for that file (obtained through .CR dup() or .CR open() , for example) still exist. .PP Unexpected results may occur in processes that use buffers in the user address space. The process may later read or write data which is or was locked. The standard I/O package, .IR stdio (3S), is the most common source of unexpected buffering. .PP In a hostile environment, locking can be misused by holding key public resources locked. This is particularly true with public read files that have enforcement enabled. .PP It is not recommended that the .CR PRIV_LOCKRDONLY capability be used because it is provided for backward compatibility only. This feature may be modified or dropped from future HP-UX releases. .PP Locks default to advisory mode unless the .CR setgid bit of the file permissions is set. .ift .bp .SS Application Usage Because in the future the variable .CR errno will be set to EAGAIN rather than EACCES when a section of a file is already locked by another process, portable application programs should expect and test for either value. For example: .nf .IP .C " if (lockf(fd, F_TLOCK, siz) == -1)" .C " if ((errno == EAGAIN) || (errno == \EACCES))" .C " /*" .C " * section locked by another process" .C " * check for either EAGAIN or EACCES" .C " * due to different implementations" .C " */" .C " else if ..." .C " /*" .C " * check for other errors" .C " */" .fi .SH SEE ALSO lockd(1M), statd(1M), chmod(2), close(2), creat(2), fcntl(2), lockf64(2), open(2), pause(2), read(2), stat(2), wait(2), write(2), unistd(5). .SH STANDARDS CONFORMANCE .CR lockf() ": SVID2, SVID3, XPG2" .\" .\" index@\f4lockf()\f1 \- provide semaphores and record locking on files@@@\f3lockf(2)\f1 .\" index@\f1file locking, provide semaphores and record locking on files@@@\f3lockf(2)\f1 .\" index@\f1provide semaphores and record locking on files@@@\f3lockf(2)\f1 .\" index@\f1semaphores and record locking on files, provide@@@\f3lockf(2)\f1 .\" index@\f1record locking and semaphores on files, provide@@@\f3lockf(2)\f1 .\" index@\f1locking on files, provide semaphores and record@@@\f3lockf(2)\f1 .\" .\" toc@\f3lockf(2)\f1:\0\0\f4lockf()\f1@@@provide semaphores and record locking on files\f1 .\" $Header: creat64.2,v 78.2 96/02/12 13:37:12 ssa Exp $ .TA c .TH creat64 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME creat64(\|), fstat64(\|), getrlimit64(\|), lockf64(\|), lseek64(\|), lstat64(\|), mmap64(\|), open64(\|), prealloc64(\|), setrlimit64(\|), stat64(\|), statvfs64(\|), truncate64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0creat64(const\0char\0*path,\0mode_t\0mode);" .PP .C "#include " .PP .C "int\0fstat64(int\0fildes,\0struct\0stat64\0*buf);" .PP .C "include\0" .PP .C "int\0getrlimit64(int resource,\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0lock64(int\0*fildes,\0int\0function,\0off64_t\0size);" .PP .C "#include " .PP .C "off64_t\0lseek64(int\0*fildes,\0off64_t\0offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0lstat64(const\0char\0*,\0struct\0stat64\0*);" .PP .C "#include " .PP .C "void\0mmap64(void\0addr,\0size_t\0len,\0int\0prot,\0int\0flags,\0int\0fildes,\0off64_t\0off);" .PP .C "#include " .PP .C "int\0open64(const\0char\0*path,\0int\0oflag,...);" .PP .C "#include " .PP .C "int\0prealloc64(int\0fildes,\0off64_t\0size);" .PP .C "include\0" .PP .C "int\0setrlimit64(int\0resource,\0const\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0stat64(const\0char\0*path,\0struct\0stat64\0*buf);" .PP .C "#include " .PP .C "int\0statvfs64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "int\0truncate64(const\0char\0*path,\0off64_t\0length);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 18 .C creat64() The .C creat64() function is identical to .C creat() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. .C creat64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR creat() . .TP .C fstat64() The .C fstat64() function is identical to .C fstat() except that .C fstat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C getrlimit64 The .C getrlimit64() function is identical to .C getrlimit() except that .C getrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .CR "struct rlimit" . All other functional behaviors, returns, and errors are identical. .TP .C lock64() The .C lock64() function is identical to .C lockf() except that .C lockf64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C lseek64() The .C lseek64() function is identical to .C lseek() except that .C lseek64() accepts an .CR off64_t type as the desired offset and has a return value of .CR off64_t. All other functional behaviors, returns, and errors are identical. .TP .C lstat64() The .C lstat64() function is identical to .C lstat() except that .C lstat64() returns file status in a .C struct stat64 instead of .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C mmap64() The .C mmap64() function is identical to .C mmap() except that .C mmap64() accepts the file offset as an .CR off64_t . .TP .C open64() The .C open64() function is identical to .C open() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. The .C open64() function is equivalent to .C open() function (in 32-bit compile environment) with .C O_LARGEFILE flag set. .C open64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR open() . .TP .C prealloc64() The .C prealloc64() function is identical to .C prealloc() except that .C prealloc64() accepts the file offset as an .CR off64_t . All other functional behaviors, returns, and errors are identical to .CR prealloc() . .TP .C setrlimit64 The .C setrlimit64() function is identical to .C setrlimit() except that .C setrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .C struct rlimit. All other functional behaviors, returns, and errors are identical. .TP .C stat64() The .C stat64() function is identical to .C stat() except that .C stat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . .TP .C statvfs64() Refer to .CR fstatvfs64() . .TP .C truncate64() The .C truncate64() function is identical to .C truncate() except that .C truncate64() accepts the length parameter as an .C off64_t instead of .CR off_t . All other functional behaviors, returns, and errors are identical to .CR truncate() . .\" .\" toc@\f4creat64(2)\f1:\0\0\f4fstat64\f1, \f4getrlimit64\f1, \f4lockf64\f1, \f4lseek64\f1, \f4lstat64\f1, \f4mmap64\f1, \f4open64\f1, \n\f4prealloc64\f1, \f4setrlimit64\f1, \f4stat64\f1, \f4statvfs64\f1, \f4truncate64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4creat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4fstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4getrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lockf64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lseek64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4mmap64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4open64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4prealloc64()\f1 \- file sysmmaptem API to support large files@@@\f3creat64(2)\f1 .\" index@\f4setrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4stat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4statvfs64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4truncate64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3creat64(2)\f1 .\" .\" links@creat64.2 fstat64.2 .\" links@creat64.2 getrlimit64.2 .\" links@creat64.2 lockf64.2 .\" links@creat64.2 lseek64.2 .\" links@creat64.2 lstat64.2 .\" links@creat64.2 mmap64.2 .\" links@creat64.2 open64.2 .\" links@creat64.2 prealloc64.2 .\" links@creat64.2 setrlimit64.2 .\" links@creat64.2 stat64.2 .\" links@creat64.2 statvfs64.2 .\" links@creat64.2 truncate64.2 .\" .\" $Header: lseek.2,v 78.2 96/02/12 14:03:37 ssa Exp $ .TA l .TH lseek 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lseek \- move read/write file pointer; seek .SH SYNOPSIS .C "#include " .PP .C "off_t lseek(int fildes, off_t offset, int whence);" .SH DESCRIPTION .C lseek() sets the file pointer associated with the file descriptor as follows: .RS .TP 3 \(bu If .I whence is .CR SEEK_SET , the pointer is set to .I offset bytes. .TP \(bu If .I whence is .CR SEEK_CUR , the pointer is set to its current location plus .IR offset . .TP \(bu If .I whence is .CR SEEK_END , the pointer is set to the size of the file plus .IR offset . .RE .PP These symbolic constants are defined in .CR . .SH RETURN VALUE When .C lseek() completes successfully, it returns an integer, which is the resulting file offset as measured in bytes from the beginning of the file. Otherwise, a value of .C -1 is returned and .C errno is set to indicate the error. .PP For all files that are not character or block special files, the integer returned on successful completion is non-negative. For character or block special files that correspond to disk sections larger than 2 gigabytes, a non-negative integer is returned for successful seeks beyond 2 gigabytes. This value is the resulting file offset as measured in bytes from the beginning of the file, when taken as an unsigned value. .C -1 always indicates an error return, even when encountered on greater than 2 gigabyte disk sections. .SH ERRORS .C lseek() fails and the file offset remains unchanged if one or more of the following is true: .TP 15 .SM [EBADF] .I fildes is not an open file descriptor. .TP .SM [ESPIPE] .I fildes is associated with a pipe, socket, or .SM FIFO. .TP .SM [EINVAL] .I whence is not one of the supported values. .TP .SM [EINVAL] The resulting file offset would be negative. .TP .SM [EINVAL] The resulting file .I offset would be a value which cannot be represented correctly in an object of type .CR off_t . .SH WARNINGS Some devices are incapable of seeking. The value of the file offset associated with such a device is undefined. .PP Using .C lseek() with a .I whence of .C SEEK_END on device special files is not supported and the results are not defined. .SH SEE ALSO creat(2), dup(2), fcntl(2), lseek64(2), open(2), unistd(5). .SH STANDARDS CONFORMANCE .CR lseek() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4lseek()\fP \(mi move read/write file pointer; seek@@@\f3lseek(2)\f1 .\" index@\f1move read/write file pointer; seek@@@\f3lseek(2)\f1 .\" index@\f1read/write file pointer, move@@@\f3lseek(2)\f1 .\" index@\f1write/read file pointer, move@@@\f3lseek(2)\f1 .\" index@\f1file pointer: move read/write file pointer@@@\f3lseek(2)\f1 .\" index@\f1pointer, file, move read/write@@@\f3lseek(2)\f1 .\" index@\f1seek; move read/write file pointer@@@\f3lseek(2)\f1 .\" .\" toc@\f3lseek(2)\f1:\0\0\f4lseek()\fP@@@move read/write file pointer; seek .\" .\" $Header: creat64.2,v 78.2 96/02/12 13:37:12 ssa Exp $ .TA c .TH creat64 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME creat64(\|), fstat64(\|), getrlimit64(\|), lockf64(\|), lseek64(\|), lstat64(\|), mmap64(\|), open64(\|), prealloc64(\|), setrlimit64(\|), stat64(\|), statvfs64(\|), truncate64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0creat64(const\0char\0*path,\0mode_t\0mode);" .PP .C "#include " .PP .C "int\0fstat64(int\0fildes,\0struct\0stat64\0*buf);" .PP .C "include\0" .PP .C "int\0getrlimit64(int resource,\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0lock64(int\0*fildes,\0int\0function,\0off64_t\0size);" .PP .C "#include " .PP .C "off64_t\0lseek64(int\0*fildes,\0off64_t\0offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0lstat64(const\0char\0*,\0struct\0stat64\0*);" .PP .C "#include " .PP .C "void\0mmap64(void\0addr,\0size_t\0len,\0int\0prot,\0int\0flags,\0int\0fildes,\0off64_t\0off);" .PP .C "#include " .PP .C "int\0open64(const\0char\0*path,\0int\0oflag,...);" .PP .C "#include " .PP .C "int\0prealloc64(int\0fildes,\0off64_t\0size);" .PP .C "include\0" .PP .C "int\0setrlimit64(int\0resource,\0const\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0stat64(const\0char\0*path,\0struct\0stat64\0*buf);" .PP .C "#include " .PP .C "int\0statvfs64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "int\0truncate64(const\0char\0*path,\0off64_t\0length);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 18 .C creat64() The .C creat64() function is identical to .C creat() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. .C creat64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR creat() . .TP .C fstat64() The .C fstat64() function is identical to .C fstat() except that .C fstat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C getrlimit64 The .C getrlimit64() function is identical to .C getrlimit() except that .C getrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .CR "struct rlimit" . All other functional behaviors, returns, and errors are identical. .TP .C lock64() The .C lock64() function is identical to .C lockf() except that .C lockf64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C lseek64() The .C lseek64() function is identical to .C lseek() except that .C lseek64() accepts an .CR off64_t type as the desired offset and has a return value of .CR off64_t. All other functional behaviors, returns, and errors are identical. .TP .C lstat64() The .C lstat64() function is identical to .C lstat() except that .C lstat64() returns file status in a .C struct stat64 instead of .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C mmap64() The .C mmap64() function is identical to .C mmap() except that .C mmap64() accepts the file offset as an .CR off64_t . .TP .C open64() The .C open64() function is identical to .C open() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. The .C open64() function is equivalent to .C open() function (in 32-bit compile environment) with .C O_LARGEFILE flag set. .C open64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR open() . .TP .C prealloc64() The .C prealloc64() function is identical to .C prealloc() except that .C prealloc64() accepts the file offset as an .CR off64_t . All other functional behaviors, returns, and errors are identical to .CR prealloc() . .TP .C setrlimit64 The .C setrlimit64() function is identical to .C setrlimit() except that .C setrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .C struct rlimit. All other functional behaviors, returns, and errors are identical. .TP .C stat64() The .C stat64() function is identical to .C stat() except that .C stat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . .TP .C statvfs64() Refer to .CR fstatvfs64() . .TP .C truncate64() The .C truncate64() function is identical to .C truncate() except that .C truncate64() accepts the length parameter as an .C off64_t instead of .CR off_t . All other functional behaviors, returns, and errors are identical to .CR truncate() . .\" .\" toc@\f4creat64(2)\f1:\0\0\f4fstat64\f1, \f4getrlimit64\f1, \f4lockf64\f1, \f4lseek64\f1, \f4lstat64\f1, \f4mmap64\f1, \f4open64\f1, \n\f4prealloc64\f1, \f4setrlimit64\f1, \f4stat64\f1, \f4statvfs64\f1, \f4truncate64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4creat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4fstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4getrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lockf64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lseek64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4mmap64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4open64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4prealloc64()\f1 \- file sysmmaptem API to support large files@@@\f3creat64(2)\f1 .\" index@\f4setrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4stat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4statvfs64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4truncate64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3creat64(2)\f1 .\" .\" links@creat64.2 fstat64.2 .\" links@creat64.2 getrlimit64.2 .\" links@creat64.2 lockf64.2 .\" links@creat64.2 lseek64.2 .\" links@creat64.2 lstat64.2 .\" links@creat64.2 mmap64.2 .\" links@creat64.2 open64.2 .\" links@creat64.2 prealloc64.2 .\" links@creat64.2 setrlimit64.2 .\" links@creat64.2 stat64.2 .\" links@creat64.2 statvfs64.2 .\" links@creat64.2 truncate64.2 .\" .\" $Header: lstat.2,v 78.1 96/02/12 14:06:25 ssa Exp $ .TA l .TH lstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lstat \- get symbolic link status .SH SYNOPSIS .\" UX .PP .C "#include " .PP .C "int lstat(const char *path, struct stat *buf);" .\" ? .SH DESCRIPTION The .CR lstat() function has the same effect as .CR stat() , except when .IR path refers to a symbolic link. In that case .CR lstat() returns information about the link, while .CR stat() returns information about the file the link references. .PP For symbolic links, the .IR st_mode member will contain meaningful information when used with the file type macros, and the .IR st_size member will contain the length of the pathname contained in the symbolic link. File mode bits and the contents of the remaining members of the .CR stat structure are unspecified. The value returned in the .IR st_size member is the length of the contents of the symbolic link, and does not count any trailing null. .SH RETURN VALUE Upon successful completion, .CR lstat() returns 0. Otherwise, it returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS The .CR lstat() function will fail if: .RS .TP 25 [EACCES] A component of the path prefix denies search permission. .TP [EIO] An error occurred while reading from the file system. .TP [ELOOP] Too many symbolic links were encountered in resolving path. .TP [ENAMETOOLONG] The length of a pathname exceeds .CR {PATH_MAX} , or pathname component is longer than .CR {NAME_MAX} . .TP [ENOTDIR] A component of the .IR path prefix is not a directory. .TP [ENOENT] A component of .IR path does not name an existing file or .IR path is an empty string. .TP [EOVERFLOW] The file size in bytes or the number of blocks allocated to the file cannot be represented correctly in the structure pointed to by .IR buf. .RE .PP The .CR lstat() function may fail if: .RS .TP 25 [ENAMETOOLONG] Pathname resolution of a symbolic link produced an intermediate result whose length exceeds .CR {PATH_MAX} . .SH SEE ALSO fstat(), readlink(), stat(), symlink(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .TA .TH lstat .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH SYNOPSIS .C "#include " .SH DESCRIPTION If the chosen path name or file descriptor refers to a Multi\-Level Directory (MLD), and the process does not have the multilevel effective privilege, the i\-node number returned in .IR st_ino is the i\-node of the MLD itself. .PP The parameters for the .CR lstat() function is as follows: .RS .TP 15 .IR path is a pointer to a path name of any file within the mounted file system. (All directories listed in the path name must be searchable.) .TP .IR buf is a pointer to a .CR stat structure, which is where the file status information is stored. .RE .PP The .CR stat structure contains the following members: .PP .TS center tab (#); lf4#lf4#lf4. dev_t#st_dev;#/* ID of device containing a */ ##/* directory entry for this file */ ino_t#st_ino;#/* Inode number */ ushort#st_fstype;#/* Type of filesystem this file */ ##/* is in; see sysfs(2) */ ushort#st_mode;#/* File type, attributes, and */ ##/* access control summary */ ushort#st_basemode#/* Permission bits (see chmod(1)) */ ushort#st_nlink;#/* Number of links */ uid_t#st_uid;#/* User ID of file owner */ gid_t#st_gid;#/* Group ID of file group */ dev_t#st_rdev;#/* Device ID; this entry defined */ ##/* only for char or blk spec files */ off_t#st_size;#/* File size (bytes) */ time_t#st_atime;#/* Time of last access */ time_t#st_mtime;#/* Last modification time */ time_t#st_ctime;#/* Last file status change time */ ##/* Measured in secs since */ ##/* 00:00:00 GMT, Jan 1, 1970 */ long#st_blksize;#/* File system block size */ uint#st_acl:1;#/* Set if the file has optional */ ##/* access control list entries */ ##/* HFS File Systems only */ .TE .PP (Note that the position of items in this list does not necessarily reflect the order of the members in the structure.) .SH ERRORS .RS .TP 15 [EFAULT] .IR buf points to an invalid address. The reliable detection of this error is implementation dependent. .RE .PP No ERROR for the following: .RS .TP 15 [EIO] An error occurred while reading from the file system. .SH NFS The .IR st_basemode and .IR st_acl fields are zero on files accessed remotely. .IR st_acl field is applicable to HFS File Systems only. .SH WARNINGS .PP Access Control Lists \- HFS File Systems only .PP Access control list descriptions in this entry apply only to HFS file systems on standard HP-UX operating systems. .SH DEPENDENCIES .RS CD-ROM .RE .PP The .IR st_uid and .IR st_gid fields are set to \(mi1 if they are not specified on the disk for a given file. .SH AUTHOR .CR stat() and .CR fstat() were developed by AT&T. .CR lstat() was developed by the University of California, Berkeley. .SH SEE ALSO touch(1), chmod(2), chown(2), creat(2), link(2), lstat64(2), mknod(2), pipe(2), read(2), rename(2), setacl(2), sysfs(2), time(2), truncate(2), unlink(2), utime(2), write(2), stat(5), privileges(5), acl(5), stat(5). .SH STANDARDS CONFORMANCE lstat(): AES, SVID3 .\" .\" index@\f4lstat()\f1 \- get symbolic link status@@@\f3lstat(2)\f1 .\" index@\f1get, symbolic link status@@@\f3lstat(2)\f1 .\" index@\f1symbolic link, get status@@@\f3lstat(2)\f1 .\" index@\f1status, get symbolic link@@@\f3lstat(2)\f1 .\" .\" toc@\f3lstat(2)\f1:\0\0\f4lstat()\f1@@@get symbolic link status .\" $Header: creat64.2,v 78.2 96/02/12 13:37:12 ssa Exp $ .TA c .TH creat64 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME creat64(\|), fstat64(\|), getrlimit64(\|), lockf64(\|), lseek64(\|), lstat64(\|), mmap64(\|), open64(\|), prealloc64(\|), setrlimit64(\|), stat64(\|), statvfs64(\|), truncate64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0creat64(const\0char\0*path,\0mode_t\0mode);" .PP .C "#include " .PP .C "int\0fstat64(int\0fildes,\0struct\0stat64\0*buf);" .PP .C "include\0" .PP .C "int\0getrlimit64(int resource,\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0lock64(int\0*fildes,\0int\0function,\0off64_t\0size);" .PP .C "#include " .PP .C "off64_t\0lseek64(int\0*fildes,\0off64_t\0offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0lstat64(const\0char\0*,\0struct\0stat64\0*);" .PP .C "#include " .PP .C "void\0mmap64(void\0addr,\0size_t\0len,\0int\0prot,\0int\0flags,\0int\0fildes,\0off64_t\0off);" .PP .C "#include " .PP .C "int\0open64(const\0char\0*path,\0int\0oflag,...);" .PP .C "#include " .PP .C "int\0prealloc64(int\0fildes,\0off64_t\0size);" .PP .C "include\0" .PP .C "int\0setrlimit64(int\0resource,\0const\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0stat64(const\0char\0*path,\0struct\0stat64\0*buf);" .PP .C "#include " .PP .C "int\0statvfs64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "int\0truncate64(const\0char\0*path,\0off64_t\0length);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 18 .C creat64() The .C creat64() function is identical to .C creat() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. .C creat64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR creat() . .TP .C fstat64() The .C fstat64() function is identical to .C fstat() except that .C fstat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C getrlimit64 The .C getrlimit64() function is identical to .C getrlimit() except that .C getrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .CR "struct rlimit" . All other functional behaviors, returns, and errors are identical. .TP .C lock64() The .C lock64() function is identical to .C lockf() except that .C lockf64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C lseek64() The .C lseek64() function is identical to .C lseek() except that .C lseek64() accepts an .CR off64_t type as the desired offset and has a return value of .CR off64_t. All other functional behaviors, returns, and errors are identical. .TP .C lstat64() The .C lstat64() function is identical to .C lstat() except that .C lstat64() returns file status in a .C struct stat64 instead of .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C mmap64() The .C mmap64() function is identical to .C mmap() except that .C mmap64() accepts the file offset as an .CR off64_t . .TP .C open64() The .C open64() function is identical to .C open() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. The .C open64() function is equivalent to .C open() function (in 32-bit compile environment) with .C O_LARGEFILE flag set. .C open64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR open() . .TP .C prealloc64() The .C prealloc64() function is identical to .C prealloc() except that .C prealloc64() accepts the file offset as an .CR off64_t . All other functional behaviors, returns, and errors are identical to .CR prealloc() . .TP .C setrlimit64 The .C setrlimit64() function is identical to .C setrlimit() except that .C setrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .C struct rlimit. All other functional behaviors, returns, and errors are identical. .TP .C stat64() The .C stat64() function is identical to .C stat() except that .C stat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . .TP .C statvfs64() Refer to .CR fstatvfs64() . .TP .C truncate64() The .C truncate64() function is identical to .C truncate() except that .C truncate64() accepts the length parameter as an .C off64_t instead of .CR off_t . All other functional behaviors, returns, and errors are identical to .CR truncate() . .\" .\" toc@\f4creat64(2)\f1:\0\0\f4fstat64\f1, \f4getrlimit64\f1, \f4lockf64\f1, \f4lseek64\f1, \f4lstat64\f1, \f4mmap64\f1, \f4open64\f1, \n\f4prealloc64\f1, \f4setrlimit64\f1, \f4stat64\f1, \f4statvfs64\f1, \f4truncate64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4creat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4fstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4getrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lockf64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lseek64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4mmap64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4open64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4prealloc64()\f1 \- file sysmmaptem API to support large files@@@\f3creat64(2)\f1 .\" index@\f4setrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4stat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4statvfs64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4truncate64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3creat64(2)\f1 .\" .\" links@creat64.2 fstat64.2 .\" links@creat64.2 getrlimit64.2 .\" links@creat64.2 lockf64.2 .\" links@creat64.2 lseek64.2 .\" links@creat64.2 lstat64.2 .\" links@creat64.2 mmap64.2 .\" links@creat64.2 open64.2 .\" links@creat64.2 prealloc64.2 .\" links@creat64.2 setrlimit64.2 .\" links@creat64.2 stat64.2 .\" links@creat64.2 statvfs64.2 .\" links@creat64.2 truncate64.2 .\" .\" $Header: sync.2,v 72.6 94/11/14 15:27:04 ssa Exp $ .TA s .TH sync 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sync \- update disk .SH SYNOPSIS .C "#include " .PP .C "void sync(void);" .SH DESCRIPTION .C sync() causes all information in memory that should be on disk to be written out. This includes modified file system meta-data and delayed block I/O. .PP It should be used by commands and programs that examine a file system, such as .CR fsck , .CR df , etc. It is mandatory before a shutdown. .PP The writing, although scheduled, is not necessarily complete upon return from .IR sync . .PP In some HP-UX systems, .C sync() may be reduced to a no-op. This is permissible on a system which does not cache buffers, or in a system that in some way ensures that the disks are always in a consistent state. .SH AUTHOR .C sync() was developed by HP and AT&T Bell Laboratories. .SH SEE ALSO sync(1M), fdatasync(2), fsync(2). .SH STANDARDS CONFORMANCE .CR sync() ": SVID2, SVID3, XPG2" .\" .\" index@\f4sync()\f1 \- update super-block@@@\f3sync(2)\f1 .\" index@\f1update super-block@@@\f3sync(2)\f1 .\" index@\f1super-block, update@@@\f3sync(2)\f1 .\" index@\f1flush buffers to disk@@@\f3sync(2)\f1 .\" index@\f1disk, flush buffers to@@@\f3sync(2)\f1 .\" index@\f1buffers, flush to disk@@@\f3sync(2)\f1 .\" .\" toc@\f3sync(2)\f1:\0\0\f4sync()\fP@@@update super-block .\" .\" links@sync.2 lsync.2 .\" $Header: madvise.2,v 78.1 95/12/20 11:00:39 ssa Exp $ .TA m .TH madvise 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME madvise() \- advise the system of a process's expected paging behavior .SH SYNOPSIS .nf .C "#include " .PP .C "int madvise(" .C " caddr_t addr," .C " size_t len, .C " int behav );" .fi .SH DESCRIPTION The .CR madvise system call permits a process to advise the system about its expected future behavior in referencing a mapped file or an anonymous memory region. Certain implementations can use this information to optimize the use of resources. .PP .I addr and .I len specify the address and length in bytes of the region to which the advice refers. For .CR MADV_DONTNEED , the address and length must be contained within a successful call to .CR mmap() (see .IR mmap (2)); otherwise, .CR madvise() fails with an [EINVAL] error. .PP The .I behav argument is one the following flags defined in the header .CR : .RS .TP .CR MADV_NORMAL Removes any previous advice and sets the default behavior. By default, the kernel tracks access patterns on data objects and performs I/Os based on process trends (that is, sequential versus random). Sequential trends cause larger "read-ahead" I/Os, while random accesses reduce the amount of I/O to avoid unnecessary I/O. .PP .TP .CR MADV_RANDOM Informs the kernel that any objects mapped in this range will be accessed in a random matter. The kernel will read only the minimal amount of data to satisfy the user fault. .PP .TP .CR MADV_SEQUENTIAL Informs the kernel that any objects mapped in this range will be accessed in a sequential matter. The kernel will perform the maximum read-ahead for every fault. The kernel does not pay attention to access patterns and trends, but instead assumes sequentiality for every access on the object. .PP .TP .CR MADV_DONTNEED Informs the kernel that the specified range is no longer needed by the process. This allows the kernel to release the physical pages associated with an address range back to the system for use by other processes. .IP .CR MADV_DONTNEED is restricted to object ranges created with calls to .CR mmap() . Attempting to use .CR MADV_DONTNEED on an object that was not created using a call to .CR mmap() will result in [EINVAL] being returned to the caller. .PP .TP .CR MADV_WILLNEED Will need these pages. .PP .TP .CR MADV_SPACEAVAIL Ensure that resources are reserved. .PD .SH WARNINGS The current implementation of .CR madvise() defines .CR MADV_SPACEAVAIL and .CR MADV_WILLNEED as null operations. .SH RETURN VALUE .CR madvise() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR madvise() fails, .CR errno is set to one of the following values. .RS .TP 15 [EFAULT] The range specified by .RI ( addr , .IR addr + len ) is invalid for a process's address space, or permission was incorrect on the object for the .I behav specified. .TP [EINVAL] .I behav contains an invalid value, or .I addr is not a multiple of the page size as returned by the system call .CR sysconf(_SC_PAGE_SIZE) . .TP [EINVAL] The address range specified by .I addr and .I len was not created by a successful call to .CR mmap() . .SH AUTHOR .CR madvise() was developed by HP and OSF. .SH SEE ALSO mmap(2), sysconf(2). .SH STANDARDS CONFORMANCE .CR madvise() ": AES, SVID3" .\" .\" index@\f1advise system of process's expected paging behavior@@@\f3madvise(2)\f1 .\" index@\f1behavior, advise system of process's expected paging@@@\f3madvise(2)\f1 .\" index@\f1paging behavior, advise system of process's expected@@@\f3madvise(2)\f1 .\" index@\f1process's expected paging behavior, advise system of@@@\f3madvise(2)\f1 .\" index@\f1system of process's expected paging behavior, advise@@@\f3madvise(2)\f1 .\" index@\f4madvise\f1 \- advise system of process's expected paging behavior@@@\f3madvise(2)\f1 .\" .\" toc@\f3madvise(2)\f1:\0\0\f4madvise()\f1@@@advise system of process's expected paging behavior .\" $Header: makecontext.2,v 76.2 95/07/07 14:45:12 ssa Exp $ .TA m .TH makecontext 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME makecontext, swapcontext \- manipulate user contexts .SH SYNOPSIS .\" UX .PP .C "#include " .PP .C "void makecontext(ucontext_t *ucp, (void *func)(), int argc, ...);" .PP .C "int swapcontext(ucontext_t *oucp, const ucontext_t *ucp);" .\" ? .SH DESCRIPTION The .CR makecontext() function modifies the context specified by .IR ucp , which has been initialised using .CR tcontext() . When this context is resumed using .CR swapcontext() or .CR setcontext() , program execution continues by calling .CR func() , passing it the arguments that follow .IR argc in the makecontext() call. .PP Before a call is made to .CR makecontext() , the context being modified should have a stack allocated for it. The value of .IR argc must match the number of integer arguments passed to .CR func() , otherwise the behaviour is undefined. .PP The .IR uc_link member is used to determine the context that will be resumed when the context being modified by .CR makecontext() returns. The .IR uc_link member should be initialised prior to the call to .CR makecontext() . .PP The .CR swapcontext() function saves the current context in the context structure pointed to by .IR oucp and sets the context to the context structure pointed to by .IR ucp . .SH RETURN VALUE On successful completion, .CR swapcontext() returns 0. Otherwise, \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR makecontext() and .CR swapcontext() functions will fail if: .RS .TP 25 [ENOMEM] The .IR ucp argument does not have enough stack left to complete the operation. .SH SEE ALSO exit(), getcontext(), sigaction(), sigprocmask(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4makecontext()\f1 \- manipulate user contexts@@@\f3makecontext(2)\f1 .\" index@\f4swapcontext()\f1 \- manipulate user contexts@@@\f3makecontext(2)\f1 .\" .\" index@\f1manipulate user contexts@@@\f3makecontext(2)\f1 .\" index@\f1user contexts, manipulate@@@\f3makecontext(2)\f1 .\" .\" toc@\f3makecontext(2)\f1:\0\0\f4makecontext()\f1, \f4swapcontext()\f1@@@manipulate user contexts .\" toc@\f4swapcontext()\f1:\0\0manipulate user contexts@@@see \f3makecontext(2)\f1 .\" .\" links@makecontext.2 swapcontext.2 .\" $Header: mkdir.2,v 76.1 95/06/12 17:16:59 ssa Exp $ .TA m .TH mkdir 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mkdir \- make a directory file .SH SYNOPSIS .C "#include " .PP .C "int mkdir(const char *path, mode_t mode);" .SH DESCRIPTION The .CR mkdir() system call creates a new directory file named by .IR path . The file permission bits of the new directory are initialized from .IR mode , and are modified by the process's file mode creation mask. For each bit set in the process's file mode creation mask, the corresponding bit in the new directory's mode is cleared (see .IR umask (2)). .PP The directory's owner ID is set to the process's effective-user-ID. If the set-group-ID bit of the parent directory is set, the directory's group ID is set to the group ID of the parent directory. Otherwise, the directory's group ID is set to the process's effective-group-ID. The set-group-ID bit of the new directory is set to the same value as the set-group-ID bit of the parent directory. .PP Symbolic constants defining the access permission bits are found in the .CR header and are used to construct the argument .IR mode . The value of the argument .I mode is the bitwise inclusive OR of the values of the desired permissions. .RS .TP 15 .CR S_IRUSR Read by owner. .PD 0 .TP .CR S_IWUSR Write by owner. .TP .CR S_IXUSR Execute (search) by owner. .TP .CR S_IRGRP Read by group. .TP .CR S_IWGRP Write by group. .TP .CR S_IXGRP Execute (search) by group. .TP .CR S_IROTH Read by others (that is, anybody else). .TP .CR S_IWOTH Write by others. .TP .CR S_IXOTH Execute (search) by others. .PD .RE .SS "Access Control Lists (ACLs) On systems implementing access control lists, the directory is created with three base ACL entries, corresponding to the file access permission bits (see .IR acl (5)). .SH RETURN VALUE .CR mkdir() returns one of the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR \-1 Failure. An error code is stored in .CR errno . .PD .RE .SH ERRORS If .CR mkdir() fails, no directory is created and .CR errno is set to one of the following values: .TP 15 [EACCES] A component of the path prefix denies search permission. .TP [EACCES] The parent directory of the new directory denies write permission. .TP [EEXIST] The named file already exists. .TP [EFAULT] .I path points outside the process's allocated address space. The reliable detection of this error is implementation dependent. .TP [EIO] An I/O error occurred while writing to the file system. .TP [ELOOP] Too many symbolic links are encountered in translating the path name. .TP [EMLINK] The maximum number of links to the parent directory, .CR {LINK_MAX} , would be exceeded. .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] A component of the path prefix does not exist. .TP [ENOSPC] Not enough space on the file system. .TP [ENOTDIR] A component of the path prefix is not a directory. .TP [EROFS] The named file resides on a read-only file system. .TP [EDQUOT] User's disk quota block or inode limit has been reached for this file system. .SH AUTHOR .CR mkdir() was developed by the University of California, Berkeley. .SH SEE ALSO chmod(2), setacl(2), stat(2), umask(2), acl(5), limits(5). .SH STANDARDS CONFORMANCE .CR mkdir() ": AES, SVID2, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4mkdir()\fP \(mi make a directory file@@@\f3mkdir(2)\f1 .\" index@create a directory file@@@\f3mkdir(2)\f1 .\" index@make a directory file@@@\f3mkdir(2)\f1 .\" index@directory: make a directory file@@@\f3mkdir(2)\f1 .\" .\" toc@\f3mkdir(2)\f1:\0\0\f4mkdir()\fP@@@make a directory file .\" $Header: mknod.2,v 72.6 94/11/14 15:24:41 ssa Exp $ .TA m .TH mknod 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mknod() \- make directory, special, or ordinary file .SH SYNOPSIS .C "#include " .PP .C "int mknod(const char *path, mode_t mode, dev_t dev);" .fi .SH DESCRIPTION The .CR mknod() system call creates a new file named by the path name pointed to by .IR path . The mode of the new file is specified by the .I mode argument. .PP Symbolic constants that define the file type and file access permission bits are found in the .CR header file and are used to construct the .IR mode argument. The value of the .I mode argument should be the bit-wise inclusive OR of the values of the desired file type, miscellaneous mode bits, and access permissions. See .IR stat (5) for a description of the components of the file mode. .PP The owner ID of the file is set to the effective-user-ID of the process. If the set-group-ID bit of the parent directory is set, the new file's group ID is set to the group ID of the parent directory. Otherwise, the new file's group ID is set to the effective-group-ID of the process. .PP The file access permission bits of .I mode are modified by the process's file mode creation mask: for each bit set in the process's file mode creation mask, the corresponding bit in the file's mode is cleared (see .IR umask (2)). .PP The new file is created with three base access-control-list (ACL) entries, corresponding to the file access permission bits (see .IR acl (5)). .PP The .I dev argument is meaningful only if .I mode indicates a block or character special file, and is ignored otherwise. It is an implementation- and configuration-dependent specification of a character or block I/O device. The value of .I dev is created by using the .CR makedev() macro defined in .CR . The .CR makedev() macro takes as arguments the major and minor device numbers, and returns a device identification number which is of type .CR dev_t . The value and interpretation of the major and minor device numbers are implementation-dependent. For more information, see .IR mknod (5) and the System Administration manuals for your system. .PP Only users having appropriate privileges can invoke .CR mknod() for file types other than FIFO files. .SH RETURN VALUE .CR mknod() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. The new file is not created. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR mknod() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] The directory in which .I path would be created denies write permission, .I mode is for a FIFO file and the caller does not have appropriate privileges. .TP [EACCES] A component of the path prefix denies search permission. .TP [EDQUOT] The user's disk quota block or inode limit has been reached for this file system. .TP [EEXIST] The named path already exists. .TP [EFAULT] The .I path argument points outside the process's allocated address space. The reliable detection of this error is implementation dependent. .TP [ELOOP] Too many symbolic links were encountered in translating the path name. .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] The .I path argument is null. .TP [ENOENT] A component of the path prefix does not exist. .TP [ENOSPC] Not enough space on the file system. .TP [ENOTDIR] A component of the path prefix is not a directory. .TP [EPERM] The effective-user-ID of the process does not match that of a user who has appropriate privileges, and the file type is not FIFO special. .TP [EROFS] The directory in which the file is to be created is located on a read-only file system. .RE .SH AUTHOR .CR mknod() was developed by AT&T and HP. .SH SEE ALSO mknod(1M), chmod(2), exec(2), mkdir(2), setacl(2),\"STD umask(2), fs(4), acl(5),\"STD mknod(5), stat(5), types(5). .SH STANDARDS CONFORMANCE .CR mknod() ": SVID2, SVID3, XPG2" .\" .\" index@\f4mknod()\f1 \- make directory, special, or ordinary file@@@\f3mknod(2)\f1 .\" index@make a directory, special, or ordinary file@@@\f3mknod(2)\f1 .\" index@create a directory, special, or ordinary file@@@\f3mknod(2)\f1 .\" index@directory file, make@@@\f3mknod(2)\f1 .\" index@file, make a directory, special, or ordinary@@@\f3mknod(2)\f1 .\" index@special file, make@@@\f3mknod(2)\f1 .\" index@ordinary file, make@\f3mknod(2)\f1 .\" .\" toc@\f3mknod(2)\f1:\0\0\f4mknod()\f1@@@make directory, special, or ordinary file .\" $Header: mmap.2,v 78.1 96/02/12 14:06:44 ssa Exp $ .TA m .TH mmap 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mmap \- map pages of memory .SH SYNOPSIS .nf .C "#include " .PP .C "void *mmap(void *addr, size_t len, int prot, int flags," .PD 0 .IP .C int fildes, off_t off); .PD .SH DESCRIPTION The .CR mmap() function establishes a mapping between a process' address space and a file. The format of the call is as follows: .IP .C pa=mmap(addr, len, prot, flags, fildes, off); .br .PD .PP The .CR mmap() function establishes a mapping between the process' address space at an address .IR pa for .IR len bytes and the file associated with the file descriptor .IR fildes at offset .IR off for .IR len bytes. The value of .IR pa is an unspecified function of the argument .IR addr and values of flags, further described below. A successful .CR mmap() call returns .IR pa as its result. The address ranges covered by .RI [ pa , .IR pa + len ] and .RI [ off , .IR off + len ] must be legitimate for the possible (not necessarily current) address space of a process and the file, respectively. .PP If the size of the mapped file changes after the call to .CR mmap() , the effect of references to portions of the mapped region that correspond to added or removed portions of the file is unspecified. .PP The .CR mmap() function is supported for regular files. Support for any other type of file is unspecified. .PP The .IR prot argument determines whether read, write, execute, or some combination of accesses are permitted to the pages being mapped. The protection options are defined in .CR : .RS .TP 25 .C PROT_READ Page can be read. .TP .C PROT_WRITE Page can be written. .TP .C PROT_EXEC Page can be executed. .TP .C PROT_NONE Page cannot be accessed. .RE .PP Implementations need not enforce all combinations of access permissions. However, writes shall only be permitted when .CR PROT_WRITE has been set. .PP The .IR flags argument provides other information about the handling of the mapped pages. The options are defined in .CR : .RS .TP 25 .C MAP_SHARED Share changes. .TP .C MAP_PRIVATE Changes are private. .TP .C MAP_FIXED Interpret .IR addr exactly. .RE .PP The .CR MAP_PRIVATE and .CR MAP_SHARED flags control the visibility of write references to the memory region. Exactly one of these flags must be specified. The mapping type is retained across a .CR fork() . .PP If .CR MAP_SHARED is set in flags, write references to the memory region by the calling process may change the file and are visible in all .CR MAP_SHARED mappings of the same portion of the file by any process. .PP If .CR MAP_PRIVATE is set in flags, write references to the memory region by the calling process do not change the file and are not visible to any process in other mappings of the same portion of the file. .PP It is unspecified whether write references by processes that have mapped the memory region using .CR MAP_SHARED are visible to processes that have mapped the same portion of the file using .CR MAP_PRIVATE . .PP It is also unspecified whether write references to a memory region mapped with .CR MAP_SHARED are visible to processes reading the file and whether writes to a file are visible to processes that have mapped the modified portion of that file, except for the effect of .CR msync() . .PP When .CR MAP_FIXED is set in the .IR flags argument, the implementation is informed that the value of .IR pa must be .IR addr , exactly. If .CR MAP_FIXED is set, .CR mmap() may return (void *)\(mi1 and set .CR errno to .CR EINVAL . If a .CR MAP_FIXED request is successful, the mapping established by .CR mmap() replaces any previous mappings for the process' pages in the range .RI [ pa , .IR pa + len ]. .PP When .CR MAP_FIXED is not set, the implementation uses .IR addr in an unspecified manner to arrive at .IR pa . The .IR pa so chosen will be an area of the address space which the implementation deems suitable for a mapping of .CR len bytes to the file. All implementations interpret an .IR addr value of 0 as granting the implementation complete freedom in selecting .IR pa , subject to constraints described below. A non-zero value of .IR addr is taken to be a suggestion of a process address near which the mapping should be placed. When the implementation selects a value for .IR pa , it never places a mapping at address 0, nor does it replace any extant mapping, nor map into dynamic memory allocation areas. .PP The .IR off argument is constrained to be aligned and sized according to the value returned by .CR sysconf() when passed .CR _SC_PAGESIZE or .CR _SC_PAGE_SIZE . When .C MAP_FIXED is specified, the argument .IR addr must also meet these constraints. The implementation performs mapping operations over whole pages. Thus, while the argument .IR len need not meet a size or alignment constraint, the implementation will include, in any umapping operation, any partial page specified by the range .RI [ pa , .IR pa + len ]. .PP The implementation always zero-fills any partial page at the end of a memory region. Further, the implementation never writes out any modified portions of the last page of a file that are beyond the end of the mapped portion of the file. If the mapping established by .CR mmap() extends into pages beyond the page containing the last byte of the file, an application reference to any of the pages in the mapping that are beyond the last page results in the delivery of a .CR SIGBUS or .CR SIGSEGV signal. The .CR mmap() function adds an extra reference to the file associated with the file descriptor .IR fildes which is not removed by a subsequent .CR close() on that file descriptor. This reference is removed when there are no more mappings to the file. The .IR st_atime field of the mapped file may be marked for update at any time between the .CR mmap() call and the corresponding .CR munmap() call. The initial read or write reference to a mapped region will cause the file's .IR st_atime field to be marked for update if it has not already been marked for update. .PP The .IR st_ctime and .IR st_mtime fields of a file that is mapped with .CR MAP_SHARED and .CR PROT_WRITE , will be marked for update at some point in the interval between a write reference to the mapped region and the next call to .CR msync() with .CR MS_ASYNC or .CR MS_SYNC for that portion of the file by any process. If there is no such call, these fields may be marked for update at any time after a write reference if the underlying file is modified as a result. .PP There may be implementation-dependent limits on the number of memory regions that can be mapped (per process or per system). If such a limit is imposed, whether the number of memory regions that can be mapped by a process is decreased by the use of .CR shmat() is implementation-dependent. .SH RETURN VALUE Upon successful completion, .CR mmap() returns the address at which the mapping was placed .IR ( pa ). Otherwise, it returns a value of \(mi1 and sets .CR errno to indicate the error. .SH ERRORS The .CR mmap() function will fail if: .RS .TP 15 [EBADF] The .IR fildes argument is not a valid open file descriptor. .TP [EACCES] The .IR fildes argument is not open for read, regardless of the protection specified, or .IR fildes is not open for write and .CR PROT_WRITE was specified for a .CR MAP_SHARED type mapping. .TP [ENXIO] Addresses in the range .RI [ off , .IR off + len ] are invalid for .IR fildes . .TP [EINVAL] The .IR addr argument (if .CR MAP_FIXED was specified) or off is not a multiple of the page size as returned by .CR sysconf() , or are considered invalid by the implementation. .TP [EINVAL] The value of .IR flags is invalid (neither .CR MAP_PRIVATE nor .CR MAP_SHARED is set). .TP [EMFILE] The number of mapped regions would exceed an implementation-dependent limit (per process or per system). .TP [ENODEV] The .IR fildes argument refers to a file whose type is not supported by .CR mmap() . .TP [ENOMEM] .CR MAP_FIXED was specified, and the range .RI [ addr , .IR addr + len ] exceeds that allowed for the address space of a process; or if .CR MAP_FIXED was not specified and there is insufficient room in the address space to effect the mapping. .SH APPLICATION USAGE Use of .CR mmap() may reduce the amount of memory available to other memory allocation functions. .PP Use of .CR MAP_FIXED may result in unspecified behaviour in further use of .CR brk() , .CR sbrk() , .CR malloc() , and .CR shmat() . The use of .CR MAP_FIXED is discouraged, as it may prevent an implementation from making the most effective use of resources. .PP The application must ensure correct synchronisation when using .CR mmap() in conjunction with any other file access method, such as .CR read() and .CR write() , standard input/output, and .CR shmat() . .PP The .CR mmap() function allows access to resources via address space manipulations, instead of .CR read() / write() . Once a file is mapped, all a process has to do to access it is use the data at the address to which the file was mapped. So, using pseudo-code to illustrate the way in which an existing program might be changed to use .CR mmap() , the following: .IP .C fildes = open(...) .br .C lseek(fildes, some_offset) .br .C read(fildes, buf, len) .br .C /* use data in buf */ .PD .PP becomes: .IP .C fildes = open(...) .br .C address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset) .br .C /* use data at address */ .PD .SH SEE ALSO exec, fcntl(), fork(), lockf(), msync(), munmap(), mprotect(), shmat(), sysconf(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" $Header: mmap.2,v 78.1 96/02/12 14:06:44 ssa Exp $ .TA m .TH mmap 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH SYNOPSIS .nf .C "#include " .PP .PD 0 .C "caddr_t mmap(" .IP .C "caddr_t addr," .C "size_t len," .C "int prot," .C "int flags," .C "int fildes," .C "off_t off);" .PD .fi .SH DESCRIPTION .RS .TP 20 .C MAP_FILE Create a mapped file region. .TP .C MAP_ANONYMOUS Create an unnamed memory region. .TP .C MAP_VARIABLE Place region at implementation-computed address. .RE .PP The .C MAP_FILE and .C MAP_ANONYMOUS flags control whether the region to be mapped is a mapped file region or an anonymous shared memory region. Exactly one of these flags must be selected. .PP If .C MAP_FILE is set in .IR flags : .RS .TP 5 \(bu A new mapped file region is created, mapping the file associated with .IR fildes . .TP \(bu .I off specifies the file byte offset at which the mapping starts. This offset must be a multiple of the page size returned by .CR sysconf(_SC_PAGE_SIZE) . .TP \(bu If the end of the mapped file region is beyond the end of the file, any reference to an address in the mapped file region corresponding to an offset beyond the end of the file results in the delivery of a .C SIGBUS signal to the process, unless the address lies in the last partial page corresponding to the range beyond the end of the file. The last partial page mapping the range beyond the end of the file is always initialized to zeros, and any modified portions of the last page of a file which are beyond its end are not written back to the file. .RE .PP If .C MAP_ANONYMOUS is set in .IR flags : .RS .TP 5 \(bu A new memory region is created and initialized to all zeros. This memory region can be shared only with descendants of the current process. .TP \(bu If the .I fildes argument is not \(mi1, an EINVAL error is generated. .TP \(bu The value of .I off is meaningless because there is no underlying file object for the memory region. .RE .PP The .C MAP_VARIABLE and .C MAP_FIXED flags control the placement of the region as described below. Exactly one of these flags must be selected. .PP If .C MAP_VARIABLE is set in .IR flags : .RS .TP 5 \(bu If the requested address is NULL, or if it is not possible for the system to place the region at the requested address, the region is placed at an address selected by the system. If the requested address is not a multiple of the page size returned by .CR sysconf(_SC_PAGE_SIZE) , the system treats the address as if it were rounded up to the next larger page size multiple. .RE .PP If .C MAP_FIXED is set in .IR flags : .RS .TP 5 \(bu .I addr must be a multiple of the page size returned by .CR sysconf(_SC_PAGE_SIZE) . .RE .PP The .I prot argument can be .CR PROT_NONE , or any combination of .CR PROT_READ , PROT_WRITE , and .C PROT_EXEC ORed together. If .C PROT_NONE is not specified, the system may grant other access permissions to the region in addition to those explicitly requested, except that write access will not be granted unless .C PROT_WRITE is specified. .PP .C mmap() cannot create a mapped file region unless the file descriptor used to map the file is open for reading. For a mapped file region that is mapped with .CR MAP_SHARED , .C mmap() grants write access permission only if the file descriptor is open for writing. If a region was mapped with either .C MAP_PRIVATE or .CR MAP_ANONYMOUS , .C mmap() grants all requested access permissions. .PP After the successful completion of .CR mmap() , .I fildes can be closed without effect on the mapped region or on the contents of the mapped file. Each mapped region creates a file reference, similar to an open file descriptor, that prevents the file data from being deallocated. .PP Whether modifications made to the file using .C write() are visible to mapped regions, and whether modification to a mapped region are visible with .CR read() , is undefined except for the effect of .CR msync() . .PP If an enforcement-mode file lock is in effect for any range of a file, a call to .C mmap() to map any range of the file with access rights that would violate the lock fails. The .CR msem_lock() and .CR msem_unlock() semaphore interfaces can be used to coordinate shared access to a region created with the .C MAP_SHARED flag. The advisory locks of the .C lockf() or .C fcntl() interfaces have no effect on memory mapped access, but they can be used to coordinate shared access to a .C MAP_SHARED mapped file region. .PP For a memory mapped file, the .IR st_atime and .IR st_mtime values returned by .C stat() are updated when a page in the memory mapped region is read from or written to the file system. .PP After a call to .CR fork() , the child process inherits all mapped regions with the same data and the same sharing and protection attributes as in the parent process. Each mapped file and anonymous memory region created with .C mmap() is unmapped upon process exit, and by a successful call to any of the .C exec functions. .PP A .C SIGBUS signal is delivered to a process when a write reference to a mapped file region would cause a file system error condition such as exceeding quota or file system space limits. .PP A .C SIGBUS signal is delivered to a process upon a write reference to a region without .C PROT_WRITE protection, or any reference to a region with .C PROT_NONE protection. .PP A call to .C mmap() with .C PROT_EXECUTE specified, but without .C PROT_WRITE specified for a .C MAP_SHARED|MAP_FILE mapping is treated by the system as the execution of the underlying file. This implies that such a call fails if the file is currently open for writing or mapped with .C MAP_SHARED|PROT_WRITE options by any process, and that if the call succeeds, the file cannot be opened for writing or subsequently mapped with .C MAP_SHARED|PROT_WRITE options as long as such mappings are present. A file's status as an active executable file is determined only at the time of an .CR exec() , .CR exit() , or .CR mmap() operation. .C mprotect() operations on a .C MAP_FILE|MAP_SHARED mapping have no effect on the underlying file's status as an active executable file. .SH ERRORS .RS .TP 15 .SM [EACCES] The file referred to by .I fildes is not open for read access, or the file is not open for write access and .C PROT_WRITE was set for a .C MAP_SHARED mapping operation, or .C PROT_EXECUTE was set for a .C MAP_SHARED mapping operation and the underlying file does not have execute permission. .TP .SM [EAGAIN] The file represented by .I fildes has enforcement-mode file locking in effect for some range in the file. (see .IR lockf (2), or .IR fcntl (2)). .TP [EOVERFLOW] The file is a regular file and the value of .IR off + len exceeds the offset maximum established in the open file description associated with .IR fildes. .TP .SM [ETXTBSY] .C MAP_SHARED and .C MAP_FILE are set, and .C PROT_EXECUTE is set and .C PROT_WRITE is not set, and the file being mapped is currently open for writing. .TP [EINVAL] The value of .IR off + len exceeds the maximum supported offset for mapped files. .RE .SH DEPENDENCIES .SS Series 700/800 Because the PA-RISC memory architecture utilizes a globally shared virtual address space between processes, and discourages multiple virtual address translations to the same physical address, all concurrently existing .C MAP_SHARED mappings of a file range must share the same virtual address offsets and hardware translations. PA-RISC-based HP-UX systems allocate virtual address ranges for shared memory and shared mapped files in the range 0x80000000 through 0xefffffff. This address range is used globally for .I all memory objects shared between processes. .PP This implies the following: .RS .TP 5 \(bu Any single range of a file cannot be mapped multiply into different virtual address ranges. .TP \(bu After the initial .C MAP_SHARED mmap() of a file range, all subsequent .C MAP_SHARED calls to .C mmap() to map the same range of a file must either specify .C MAP_VARIABLE in .I flags and inherit the virtual address range the system has chosen for this range, or specify .C MAP_FIXED with an .I addr that corresponds exactly to the address chosen by the system for the initial mapping. Only after all mappings for a file range have been destroyed can that range be mapped to a different virtual address. .TP \(bu In most cases, two separate calls to .C mmap() cannot map overlapping ranges in a file. The virtual address range reserved for a file range is determined at the time of the initial mapping of the file range into a process address space. The system allocates only the virtual address range necessary to represent the initial mapping. As long as the initial mapping exists, subsequent attempts to map a different file range that includes any portion of the initial range may fail with an ENOMEM error if an extended contiguous address range that preserves the mappings of the initial range cannot be allocated. .TP \(bu Separate calls to .C mmap() to map contiguous ranges of a file do not necessarily return contiguous virtual address ranges. The system may allocate virtual addresses for each call to .C mmap() on a first available basis. .TP \(bu The use of .C MAP_FIXED is strongly discouraged because it is not portable. Using .C MAP_FIXED is generally unsuccessful on this implementation, and when it is successful, it may prevent the system from optimally allocating virtual address space. .RE .PP MAP_FIXED is discouraged, but there are some applications which by design must fix pointer offsets into file data. The application must map the file at a specific address in order for the file offsets embedded in the file to make sense. .PP Processes cannot control the usage of global virtual address space, but they can control what happens within their private data area. The .C Series 700/800 allows a single process to .I exclusively map a file .C MAP_SHARED into it's private data space. When a process specifies .C MAP_SHARED and .C MAP_FIXED with a private data address(i.e. second quadrant), the kernel interprets this as an exclusive mapping of the file. The request will only succeed if no other processes in the system currently have that file mapped through .CR MAP_SHARED . If the file is already mapped the caller receives an .I EBUSY error. If the call is successful, the calling process is the only process allowed to map that file using .C MAP_SHARED until it unmaps the file using .CR munmap() . Because it is exclusive, the .CR mmap() is not inherited across .CR fork() . When a file is exclusively mapped only .C MAP_PRIVATE mappings are allowed by other processes. .PP The following combinations of protection modes are supported: .IP .C PROT_NONE .br .C PROT_READ .br .C PROT_READ|PROT_EXECUTE .br .C PROT_READ|PROT_WRITE .br .C PROT_READ|PROT_WRITE|PROT_EXECUTE .PD .PP If a .C MAP_PRIVATE mapping is created of a file for which a .C MAP_SHARED mapping exists, a separate copy of a page for the .C MAP_PRIVATE mapping is created at the time of the first access to the page through the private mapping. .PP .SH AUTHOR .C mmap() was developed by HP, AT&T, and OSF. .SH SEE ALSO fcntl(2), fork(2), ftruncate(2), lockf(2), madvise(2), mmap64(2), mprotect(2), msem_init(2), msem_lock(2), msem_unlock(2), msync(2), munmap(2), sysconf(2), mman(5), stat(5). .SH STANDARDS CONFORMANCE .CR mmap() ": AES, SVID3" .\" .\" index@\f4mmap\f1 \- map object into virtual memory@@@\f3mmap(2)\f1 .\" index@\f1map object into virtual memory@@@\f3mmap(2)\f1 .\" index@\f1object into virtual memory, map@@@\f3mmap(2)\f1 .\" index@\f1virtual memory, map object into@@@\f3mmap(2)\f1 .\" index@\f1memory, map object into virtual@@@\f3mmap(2)\f1 .\" .\" toc@\f3mmap(2)\f1:\0\0\f4mmap\f1@@@map object into virtual memory .\" $Header: creat64.2,v 78.2 96/02/12 13:37:12 ssa Exp $ .TA c .TH creat64 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME creat64(\|), fstat64(\|), getrlimit64(\|), lockf64(\|), lseek64(\|), lstat64(\|), mmap64(\|), open64(\|), prealloc64(\|), setrlimit64(\|), stat64(\|), statvfs64(\|), truncate64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0creat64(const\0char\0*path,\0mode_t\0mode);" .PP .C "#include " .PP .C "int\0fstat64(int\0fildes,\0struct\0stat64\0*buf);" .PP .C "include\0" .PP .C "int\0getrlimit64(int resource,\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0lock64(int\0*fildes,\0int\0function,\0off64_t\0size);" .PP .C "#include " .PP .C "off64_t\0lseek64(int\0*fildes,\0off64_t\0offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0lstat64(const\0char\0*,\0struct\0stat64\0*);" .PP .C "#include " .PP .C "void\0mmap64(void\0addr,\0size_t\0len,\0int\0prot,\0int\0flags,\0int\0fildes,\0off64_t\0off);" .PP .C "#include " .PP .C "int\0open64(const\0char\0*path,\0int\0oflag,...);" .PP .C "#include " .PP .C "int\0prealloc64(int\0fildes,\0off64_t\0size);" .PP .C "include\0" .PP .C "int\0setrlimit64(int\0resource,\0const\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0stat64(const\0char\0*path,\0struct\0stat64\0*buf);" .PP .C "#include " .PP .C "int\0statvfs64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "int\0truncate64(const\0char\0*path,\0off64_t\0length);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 18 .C creat64() The .C creat64() function is identical to .C creat() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. .C creat64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR creat() . .TP .C fstat64() The .C fstat64() function is identical to .C fstat() except that .C fstat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C getrlimit64 The .C getrlimit64() function is identical to .C getrlimit() except that .C getrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .CR "struct rlimit" . All other functional behaviors, returns, and errors are identical. .TP .C lock64() The .C lock64() function is identical to .C lockf() except that .C lockf64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C lseek64() The .C lseek64() function is identical to .C lseek() except that .C lseek64() accepts an .CR off64_t type as the desired offset and has a return value of .CR off64_t. All other functional behaviors, returns, and errors are identical. .TP .C lstat64() The .C lstat64() function is identical to .C lstat() except that .C lstat64() returns file status in a .C struct stat64 instead of .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C mmap64() The .C mmap64() function is identical to .C mmap() except that .C mmap64() accepts the file offset as an .CR off64_t . .TP .C open64() The .C open64() function is identical to .C open() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. The .C open64() function is equivalent to .C open() function (in 32-bit compile environment) with .C O_LARGEFILE flag set. .C open64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR open() . .TP .C prealloc64() The .C prealloc64() function is identical to .C prealloc() except that .C prealloc64() accepts the file offset as an .CR off64_t . All other functional behaviors, returns, and errors are identical to .CR prealloc() . .TP .C setrlimit64 The .C setrlimit64() function is identical to .C setrlimit() except that .C setrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .C struct rlimit. All other functional behaviors, returns, and errors are identical. .TP .C stat64() The .C stat64() function is identical to .C stat() except that .C stat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . .TP .C statvfs64() Refer to .CR fstatvfs64() . .TP .C truncate64() The .C truncate64() function is identical to .C truncate() except that .C truncate64() accepts the length parameter as an .C off64_t instead of .CR off_t . All other functional behaviors, returns, and errors are identical to .CR truncate() . .\" .\" toc@\f4creat64(2)\f1:\0\0\f4fstat64\f1, \f4getrlimit64\f1, \f4lockf64\f1, \f4lseek64\f1, \f4lstat64\f1, \f4mmap64\f1, \f4open64\f1, \n\f4prealloc64\f1, \f4setrlimit64\f1, \f4stat64\f1, \f4statvfs64\f1, \f4truncate64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4creat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4fstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4getrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lockf64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lseek64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4mmap64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4open64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4prealloc64()\f1 \- file sysmmaptem API to support large files@@@\f3creat64(2)\f1 .\" index@\f4setrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4stat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4statvfs64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4truncate64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3creat64(2)\f1 .\" .\" links@creat64.2 fstat64.2 .\" links@creat64.2 getrlimit64.2 .\" links@creat64.2 lockf64.2 .\" links@creat64.2 lseek64.2 .\" links@creat64.2 lstat64.2 .\" links@creat64.2 mmap64.2 .\" links@creat64.2 open64.2 .\" links@creat64.2 prealloc64.2 .\" links@creat64.2 setrlimit64.2 .\" links@creat64.2 stat64.2 .\" links@creat64.2 statvfs64.2 .\" links@creat64.2 truncate64.2 .\" .\" $Header: mount.2,v 72.7 94/11/14 15:24:43 ssa Exp $ .TA m .TH mount 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mount() \- mount a file system .SH SYNOPSIS .nf .C "#include " .PP .C "int mount(const char *fs, const char *path, int mflag);" .PP .C "int mount(const char *fs," .C " const char *path," .C " int mflag," .C " const char *fstype," .C " const char *dataptr," .C " int datalen);" .fi .SH DESCRIPTION The .CR mount() system call requests that a file system identified by .IR fs be mounted on the file identified by .IR path. .PP .IR mflag contains a bit-mask of flags (described below). Note that the .CR MS_DATA flag must be set for the six-argument version of the call. .PP .IR fstype is the file system type name. It is the same name that .IR sysfs (2) uses. .PP The last two arguments together describe a block of file-system-specific data at address .IR dataptr of length .IR datalen . This is interpreted by file-system-specific code within the operating system and its format depends upon the file system type. A particular file system type may not require this data, in which case .IR dataptr and .IR datalen should both be zero. The mounting of some file system types may be restricted to a user with appropriate privileges. .PP .CR mount() can be invoked only by a user who has appropriate privileges. .PP Upon successful completion, references to the file .IR path will refer to the root directory of the mounted file system. .PP .IR mflag contains a bit-mask of flag values, which includes the following defined in .CR : .RS .TP 15 .CR MS_DATA This is ordinarily required. It indicates the presence of the .IR fstype, .IR dataptr, and .IR datalen arguments. .IP (For backward compatibility, if this flag is not set, the .IR fstype is assumed to be that of the root file system, and .IR dataptr and .IR datalen are assumed to be zero.) .TP .CR MS_RDONLY This is used to control write permission on the mounted file system. If not set, writing is permitted according to individual file accessibility. .TP .CR MS_NOSUID This flag disables set-user-ID and set-group-ID behavior on this file system. .TP .CR MS_QUOTA This causes quotas to be enabled if the file system supports quotas. .RE .PP If .IR fstype is specified as: .RS .TP 15 .CR MNTTYPE_HFS Mount a local HFS file system. .I dataptr points to a structure of the following format, if the options described below need to be specified for the mount: .RS .nf .IP .C "struct ufs_args {" .C " char *fspec;" .C " int flags;" .C "};" .fi .PP .I fspec points to the name of the block special file that is to be mounted. This is identical in use and function to the first argument, .IR fs , of the system call. .PP .I flags points to a bit map that sets options. The following values of the bits are defined in .CR : .TP 20 .CR MS_DELAY Writes to disks are to be delayed until the buffer needs to be reused. This is the default on Series 800 systems, as it was prior to release 10.0. .TP .CR MS_BEHIND Writes to disks are to be done asynchronously, where possible, without waiting for completion. This is the default on Series 700 systems, as it was prior to release 10.0. .IP .CR MS_BEHIND and .CR MS_DELAY are mutually exclusive. .TP .CR MS_NO_FSASYNC Rigorous posting of file system metadata is to be used. This is the default. .TP .CR MS_FSASYNC Relaxed posting of file system metadata is to be used. This may lead to better performance for certain applications; but there is increased potential for data loss in case of a crash. .IP .CR MS_FSASYNC and .CR MS_NO_FSASYNC are mutually exclusive. .RE .RE .SH RETURN VALUE .CR mount() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR \-1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR mount() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] A component of the path prefix denies search permission. .TP [EBUSY] .IR path is currently mounted on, is someone's current working directory, or is otherwise busy. .TP [EBUSY] The file system associated with .IR fs is currently mounted. .TP [EBUSY] The system cannot allocate the necessary resources for this mount. .TP [EFAULT] .IR fs, .IR path or .IR dataptr points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP [EINVAL] An argument to the system call is invalid, or a sanity check failed. .TP [ELOOP] Too many symbolic links were encountered in translating a path name argument. .TP [ENAMETOOLONG] The length of a path name exceeds .CR PATH_MAX, or a path name component is longer than .CR NAME_MAX while .CR _POSIX_NO_TRUNC is in effect. .TP [ENODEV] .IR fstype is a file system that is not been configured into the kernel. .TP [ENOENT] A named file does not exist. .TP [ENOENT] .IR fs or .IR path is null. .TP [ENOTBLK] .IR fs is not a block special device and the file system type requires it to be. .TP [ENOTDIR] A component of a path prefix is not a directory. .TP [ENOTDIR] .IR path is not a directory. .TP [ENXIO] The device associated with .IR fs does not exist and the file system type requires it to be. .TP [EPERM] The process does not have the appropriate privilege and the file system type requires it. .TP [EROFS] The requested file system is write protected and .IR mflag requests write permission. .RE .SH WARNINGS If .CR mount() is called from the program level (i.e., not called with the .CR mount command (see .IR mount (1M)), the table of mounted devices contained in .CR /etc/mnttab is not updated. The updating of .CR /etc/mnttab is performed by the .CR mount and .CR syncer commands (see .IR mount (1M) and .IR syncer (1M)). .SH SEE ALSO mount(1M), syncer(1M), sysfs(2), umount(2). .\" .\" index@\f4mount()\f1 \- mount a file system@@@\f3mount(2)\f1 .\" index@\f1file system, mount@@@\f3mount(2)\f1 .\" .\" toc@\f3mount(2)\f1:\0\0\f4mount()\f1@@@mount a file system .\" $Header: mpctl.2,v 78.5 96/04/07 07:35:16 ssa Exp $ .TA m .TH mpctl 2 "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mpctl \- multiprocessor control .SH SYNOPSIS .C "#include " .PP .nf .PD 0 .C "int mpctl(" .IP .C "mpc_request_t request," .C "spu_t spu," .C "pid_t pid" .PP .C ");" .PD .PP .PD 0 .C "int mpctl(" .IP .C "mpc_request_t request," .C "spu_t spu," .C "lwpid_t lwpid" .PP .C ");" .PD .fi .SH REMARKS Much of the functionality of this capability is highly dependent on the underlying hardware. An application that uses this system call should not be expected to be portable across architectures or implementations. .SH DESCRIPTION .CR mpctl provides a means of determining how many processors are installed in the system and assigning proceses/lightweight processes to run on specific processors. .PP This call is expected to be used to increase performance in certain applications, but should not be used to ensure correctness of an application. Specifically, cooperating processes/lightweight processes should not rely on processor assignment in lieu of a synchronization mechanism (such as semaphores). .PP The .I request argument determines the precise action to be taken by .CR mpctl and is one of the following: .RS .TP 18 .C MPC_GETNUMSPUS This request returns the number of spus (processors) in the system. It will always be greater than or equal to 1. The .I spu and .I pid (or .IR lwpid ) arguments are ignored. .TP .C MPC_GETFIRSTSPU This request returns the number of the first processor in the system. The .I spu and .I pid (or .IR lwpid ) arguments are ignored. .TP .C MPC_GETNEXTSPU This request returns the number of the next processor in the system after .IR spu . Typically, MPC_GETFIRSTSPU is called to determine the first spu. MPC_GETNEXTSPU is then called in a loop (until the call returns -1) to determine the numbers of the remaining spus. The .I pid (or .IR lwpid ) argument is ignored. .TP .C MPC_GETCURRENTSPU This request returns the number of the processor the process is currently running on (NOT the processor assignment of the caller). The number of the processor the process is currently running on is undefined if the process is multithreaded. The .I spu and .I pid (or .IR lwpid ) arguments are ignored. This information may be out\-of\-date arbitrarily soon after the call completes. .TP .C MPC_SETPROCESS This call is .IR advisory . This request asynchronously assigns process .I pid to processor .IR spu . Since the new .I spu assignment is returned, the .I spu MPC_SPUNOCHANGE may be passed to read the current assignment. The .I pid MPC_SELFPID may be used to refer to the calling process. The .I spu MPC_SPUFLOAT may be used to break any specific\-processor assignment. This allows the process to float to any processor. .IP Note: This call is .IR advisory . If the scheduling policy for a process conflicts with this processor assignment, the scheduling policy takes precedence. For example, when a processor is ready choose another process/lightweight process to execute, and the highest priority .C SCHED_FIFO process is bound to a different processor, that process will execute on the selecting processor rather than waiting for the specified processor to which it was bound. .IP If the process specified by .I pid is a multithreaded process, all threads (lightweight processes) in the target process will have their processor assignment changed to what is specified. .TP .C MPC_SETPROCESS_FORCE This call is identical to MPC_SETPROCESS except that the process to processor binding will override the scheduling policy. This call is synchronous. For example, when a processor is ready choose another process/lightweight process) to execute, and the highest priority .C SCHED_FIFO process is bound to a different processor, that process will not be selected to execute on the selecting processor, but instead wait for the specified processor to which it was bound. The selecting processor will then choose a lower priority process to execute on the processor. .IP Note: This option will not guarantee compliance with POSIX real-time scheduling algorithms. .IP If the process specified by .I pid is a multithreaded process, all threads (lightweight processes) in the target process will have their processor assignment changed to what is specified. .TP .C MPC_SETLWP This call is .IR advisory . This request asynchronously assigns thread (lightweight process - LWP) .I lwpid to processor .IR spu . This option is only available to change the assignment for threads (LWPs) in the current process. Since the new .I spu assignment is returned, the .I spu MPC_SPUNOCHANGE may be passed to read the current assignment. The .I lwpid MPC_SELFLWPID may be used to refer to the calling thread (LWP). The .I spu MPC_SPUFLOAT may be used to break any specific\-processor assignment. This allows the thread (LWP) to float to any processor. .IP Note: This call is .IR advisory . If the scheduling policy for a thread (LWP) conflicts with this processor assignment, the scheduling policy takes precedence. For example, when a processor is ready choose another thread (LWP) to execute, and the highest priority .C SCHED_FIFO thread (LWP) is bound to a different processor, that thread (LWP) will execute on the selecting processor rather than waiting for the specified processor to which it was bound. .TP .C MPC_SETLWP_FORCE This call is identical to MPC_SETLWP except that the thread (LWP) to processor binding will override the scheduling policy. This call is synchronous. For example, when a processor is ready choose another thread (LWP) to execute, and the highest priority .C SCHED_FIFO thread (LWP) is bound to a different processor, that thread (LWP) will not be selected to execute on the selecting processor, but instead wait for the specified processor to which it was bound. The selecting processor will then choose a lower priority thread (LWP) to execute on the processor. .IP Note: This option will not guarantee compliance with POSIX real-time scheduling algorithms. .PP To change the processor assignment of another process, the caller must be a member of a group having PRIV_MPCTL access (or be the super-user). .PP If the .I request argument specifies MPC_SETPROCESS or MPC_SETPROCESS_FORCE and the process specified by .I pid is a multi-threaded process, the processor binding specified shall be applied for all lightweight processes contained within .IR pid . .PP Each process shall contain a specified processor binding. Each lightweight process shall contain a processor binding. The processor binding for a lightweight process does not have to match the processor binding for the process. .PP When a process creates another process (via .CR fork() or .CR vfork() ) the child process will inherit the parent processes processor binding. The initial lightweight process in the child process shall inherit its processor binding from the child process. Lightweight processes other than the initial lightweight process shall inherit their processor binding from the creating lightweight process. .SH ERRORS In general, .CR mpctl fails if one or more of the following is true: .RS .TP 10 [EINVAL] .I request is an illegal number. .TP [EINVAL] .I request is MPC_GETNEXTSPU and .I spu identifies the last processor. .TP [ESRCH] .I pid or .I lwpid identifies a process or LWP that does not exist. .TP [EPERM] .I request is MPC_SETPROCESS or MPC_SETPROCESS_FORCE, .I spu is not MPC_SPUNOCHANGE, .I pid identifies another process, and the caller is not the super-user or a member of a group having PRIV_MPCTL access. .RE .SH SEE ALSO getprivgrp(1), setprivgrp(1M), getprivgrp(2), fork(2), privgrp(4). .\" .\" index@\f4mpctl\f1 \- multiprocessor control@@@\f3mpctl(2)\f1 .\" index@\f1multiprocessor control@@@\f3mpctl(2)\f1 .\" index@\f1control, multiprocessor@@@\f3mpctl(2)\f1 .\" .\" toc \f3mpctl(2)\f1:\0\0\f4mpctl\f1@@@multiprocessor control .\" $Header: mprotect.2,v 76.1 95/07/07 14:47:02 ssa Exp $ .TA m .TH mprotect 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mprotect \- set protection of memory mapping .SH SYNOPSIS .nf .C "#include " .PP .PD 0 .C "int mprotect(void *addr, size_t len, int prot);" .PD .fi .SH DESCRIPTION The .CR mprotect() function changes the access protections on the mappings specified by the range .RI [ addr , .IR addr + len ], rounding .IR len up to the next multiple of the page size as returned by .CR sysconf() , to be that specified by .IR prot . Legitimate values for .IR prot are the same as those permitted for .CR mmap() and are defined in .CR : .RS .TP 15 .CR PROT_READ Page can be read. .TP .CR PROT_WRITE Page can be written. .TP .CR PROT_EXEC Page can be executed. .TP .CR PROT_NONE Page cannot be accessed. .RE .PP When .CR mprotect() fails for reasons other than EINVAL, the protections on some of the pages in the range .RI [ addr , .IR addr + len ] may have been changed. .SH RETURN VALUE Upon successful completion, .CR mprotect() returns 0. Otherwise, it returns -1 and sets .CR errno to indicate the error. .SH ERRORS The .CR mprotect() function will fail if: .RS .TP 15 [EACCES] The .IR prot argument specifies a protection that violates the access permission the process has to the underlying memory object. .TP [EINVAL] The .IR addr argument is not a multiple of the page size as returned by .CR sysconf() . .TP [ENOMEM] Addresses in the range .RI [ addr , .IR addr + len ] are invalid for the address space of a process, or specify one or more pages which are not mapped. .RE .PP The .CR mprotect() function may fail if: .TP 15 [EAGAIN] The .IR prot argument specifies .CR PROT_WRITE over a .CR MAP_PRIVATE mapping and there are insufficient memory resources to reserve for locking the private page. .SH SEE ALSO mmap(2), sysconf(2), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .TA m .TH mprotect 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH SYNOPSIS .nf .PD 0 .C "int mprotect(" .IP .C "caddr_t addr," .C "size_t len," .C "int prot );" .PD .fi .SH DESCRIPTION If the address range does not correspond to one created by a successful call to .CR mmap() , .CR mprotect() returns an error. .IR prot determines whether read, write, execute, or some combination of accesses are permitted to the data being mapped. .PP If the address range being modified corresponds to a mapped file that was mapped with .CR MAP_SHARED , .CR mprotect() grants write access permission only if the file descriptor used to map the file was opened for writing. If the address range corresponds to a mapped file that was mapped with the .CR MAP_PRIVATE or the .CR MAP_ANONYMOUS flag, .CR mprotect() grants all requested access permissions. .PP For example, suppose an error occurs on some page at an .IR addr2 ; .CR mprotect() may have modified the protections of all whole pages in the range .RI [ addr , addr2 ]. .SH ERRORS .RS .TP 15 [EINVAL] .IR prot is invalid, or .IR addr is not a multiple of the page size as returned by .CR sysconf(_SC_PAGE_SIZE) . .TP [EFAULT] The range specified by .RI [ addr , .IR addr + len ] (from, and including, .IR addr to, but not including, .IR addr + len ) is invalid for a process' address space, or the range specifies one or more unmapped pages. .\" .TP .\" .SM [EINVAL] .\" The address range specified by .\" .I addr .\" and .\" .I len .\" was not created by a successful call to .\" .CR mmap() . .SH AUTHOR .CR mprotect() was developed by HP, AT&T, and OSF. .SH SEE ALSO mmap(2), sysconf(2). .SH STANDARDS CONFORMANCE .CR mprotect(): AES, SVID3 .\" .\" toc@\f3mprotect(2)\f1:\0\0\f4mprotect\f1@@@modify memory mapping access protections .\" .\" index@\f4mprotect\f1 \- modify memory mapping access protections@@@\f3mprotect(2)\f1 .\" index@modify memory mapping access protections@@@\f3mprotect(2)\f1 .\" index@memory mapping access protections, modify@@@\f3mprotect(2)\f1 .\" index@mapping access protections, modify memory@@@\f3mprotect(2)\f1 .\" index@access protections, modify memory mapping@@@\f3mprotect(2)\f1 .\" index@protections, modify memory mapping access@@@\f3mprotect(2)\f1 .\" .\" fileset_database@mprotect.2 PROGRAMING-MAN .\" $Header: msem_init.2,v 72.5 94/11/14 15:24:56 ssa Exp $ .TA m .TH msem_init 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME msem_init \(mi initialize a semaphore in a mapped file or anonymous memory region .SH SYNOPSIS .C "#include " .PP .C "msemaphore *msem_init(msemaphore *sem, int initial_value);" .SH DESCRIPTION .C msem_init() allocates a new binary semaphore and initializes the state of the new semaphore. .PP .I sem points to an .C msemaphore structure in which the state of the semaphore is to be stored. .PP If .I initial_value is .CR MSEM_LOCKED , the new semaphore is initialized in the locked state. If .I initial_value is .CR MSEM_UNLOCKED , the new semaphore is initialized in the unlocked state. .PP The .C msemaphore structure must be located within a mapped file or anonymous memory region created by a successful call to .C mmap() and have both read and write access. .PP If a semaphore is created in a mapped file region, any reference by a process that has mapped the same file, using a .C (struct msemaphore *) pointer that resolves to the same file offset is interpreted as a reference to the same semaphore. If a semaphore is created in an anonymous memory region, any reference by a process sharing the same region by use of a .C (struct msemaphore *) pointer that resolves to the same offset from the start of the region is interpreted as a reference to the same semaphore. .PP Any previous semaphore state stored in the .C msemaphore structure will be ignored and overwritten. .SS Implementation Notes In order to ensure that an .C msemaphore structure is entirely contained in a single memory page, .I sem must be at an address that is an exact multiple of .CR "sizeof(struct msemaphore)" . The size of the .C msemaphore structure is guaranteed to prevent semaphores that cross page boundaries given the above restriction. .PP For a memory mapped file region, the system deallocates memory that corresponds to a range of the file that has been truncated with .C ftruncate() or .CR truncate() . If a semaphore is located in memory so deallocated, the effect is equivalent to an .C msem_remove() on the semaphore. .SH RETURN VALUE .C msem_init() returns the address of the initialized .C msemaphore structure; otherwise, it returns NULL and sets .C errno to indicate the error. NOTE: This error return value may change to \(mi1 in a future HP-UX release. For portability, applications should check for a zero or negative value for error returns. .\" (OSF AES specifies NULL as the error return; but system calls by .\" convention return -1) .SH ERRORS .C msem_init() fails if any of the following conditions are encountered: .RS .TP 15 [EINVAL] .I sem points to an .C msemaphore structure that is not located in a mapped region created by .C mmap() and with read and write access, or .I initial_value is not valid. .TP [ENOMEM] A new semaphore could not be created. .TP [EFAULT] .I sem is an invalid pointer. .SH AUTHOR .C msem_init() was developed by HP and OSF. .SH SEE ALSO mmap(2), msem_lock(2), msem_remove(2), msem_unlock(2), mman(5). .SH STANDARDS CONFORMANCE .CR msem_init() ": AES" .\" .\" toc@\f3msem_init(2)\f1:\0\0\f4msem_init()\f1@@@initialize semaphore in mapped file or anonymous memory region .\" .\" index@\f4msem_init()\f1 \- initialize semaphore in mapped file or anonymous memory region@@@\f3msem_init(2)\f1 .\" index@\f1initialize semaphore in mapped file or anonymous memory region@@@\f3msem_init(2)\f1 .\" index@\f1semaphore in mapped file or anonymous memory region, initialize@@@\f3msem_init(2)\f1 .\" index@\f1mapped file or anonymous memory region, initialize semaphore in@@@\f3msem_init(2)\f1 .\" index@\f1file or anonymous memory region, initialize semaphore in mapped@@@\f3msem_init(2)\f1 .\" index@\f1anonymous memory region, initialize semaphore in mapped file or@@@\f3msem_init(2)\f1 .\" index@\f1memory region, initialize semaphore in mapped file or anonymous@@@\f3msem_init(2)\f1 .\" index@\f1region, initialize semaphore in mapped file or anonymous memory@@@\f3msem_init(2)\f1 .\" .\" fileset_database@msem_init.2 PROGRAMING-MAN .\" $Header: msem_lock.2,v 72.4 94/11/14 15:24:57 ssa Exp $ .TA m .TH msem_lock 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME msem_lock \(mi lock a semaphore .SH SYNOPSIS .nf .C "#include " .PP .C "int msem_lock(msemaphore *sem, int condition);" .SH DESCRIPTION .C msem_lock() attempts to lock a binary semaphore. .PP .I sem points to an .C msemaphore structure which specifies the semaphore to be locked. .PP If the semaphore is not currently locked, it becomes locked and the function returns successfully. .PP If the semaphore is currently locked, and .I condition is .CR MSEM_IF_NOWAIT , then the function returns with an error. If the semaphore is currently locked and .I condition is zero, the function does not return until either the calling process is able to successfully lock the semaphore, or an error condition occurs. .PP All calls to .C msem_lock() and .C msem_unlock() by multiple processes sharing a common .C msemaphore structure behave as if the calls were serialized. .PP If the .C msemaphore structure contains any value not resulting from a call to .C msem_init() followed by a (possibly empty) sequence of calls to .C msem_lock() and .CR msem_unlock() , the results are undefined. The address of an .C msemaphore uniquely identifies the semaphore. If the .C msemaphore structure contains any value copied from an .C msemaphore structure at a different address, the result is undefined. .SH IMPLEMENTATION NOTES If blocked on a locked semaphore, .C msem_lock() suspends the calling process at a priority such that the process can be interrupted by a signal. .PP The system attempts to ignore or recover from invalid values written to the .C msemaphore structure, but this is not guaranteed for all cases. .PP .C msem_lock() successfully acquires a semaphore that is locked by a process that has exited. .SH RETURN VALUE Upon success, .C msem_lock() returns zero; otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C msem_lock() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EAGAIN] .C MSEM_IF_NOWAIT was specified and the semaphore was already locked. .TP .SM [EINVAL] .I sem points to an .C msemaphore structure that has been removed, or .I condition is invalid. .TP .SM [EINTR] .C msem_lock() was interrupted by a signal that was caught. .TP .SM [EDEADLK] The semaphore is currently locked, .I condition is zero, and waiting to lock the semaphore would create a deadlock. .TP .SM [EFAULT] .I sem is not a properly aligned address or is otherwise an invalid pointer. .SH AUTHOR .C msem_lock() was developed by HP and OSF. .SH SEE ALSO msem_init(2), msem_remove(2), msem_unlock(2), mman(5). .SH STANDARDS CONFORMANCE .CR msem_lock() ": AES" .\" .\" toc@\f3msem_lock(2)\f1:\0\0\f4msem_lock\f1@@@lock a semaphore .\" .\" index@\f4msem_lock\f1 \(mi lock a semaphore@@@\f3msem_lock(2)\f1 .\" index@lock a semaphore@@@\f3msem_lock(2)\f1 .\" index@semaphore, lock a@@@\f3msem_lock(2)\f1 .\" .\" fileset_database@msem_lock.2 PROGRAMING-MAN .\" $Header: msem_remove.2,v 72.4 94/11/14 15:24:59 ssa Exp $ .TA m .TH msem_remove 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME msem_remove \- remove a semaphore in mapped file or anonymous region .SH SYNOPSIS .C "#include " .PP .C "int *msem_remove(msemaphore *sem);" .SH DESCRIPTION .C msem_remove() removes a binary semaphore. .PP .I sem points to an .C msemaphore structure that specifies the semaphore to be removed. Any subsequent use of the .C msemaphore structure before it is again initialized by calling .C msem_init() produces undefined results. .PP .C msem_remove() also causes any process waiting in the .C msem_lock() function on the removed semaphore to return with an error. .PP If the .C msemaphore structure contains any value not resulting from a call to .C msem_init() followed by a (possibly empty) sequence of calls to .C msem_lock() and .C msem_unlock(), the results are undefined. The address of an .C msemaphore uniquely identifies the semaphore. If the .C msemaphore structure contains any value copied from a .C msemaphore structure at a different address, the result is undefined. .SH RETURN VALUE Upon success, .C msem_remove() returns zero; otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C msem_remove() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EINVAL] .I sem points to an .C msemaphore structure that has been removed. .TP .SM [EFAULT] .I sem is an invalid pointer. .SH AUTHOR .C msem_remove() was developed by HP and OSF. .SH SEE ALSO msem_init(2), msem_lock(2), msem_remove(2), mman(5). .SH STANDARDS CONFORMANCE .CR msem_remove() ": AES" .\" .\" toc@\f3msem_remove(2)\f1:\0\0\f4msem_remove\f1@@@remove semaphore in mapped file or anonymous region .\" .\" index@\f4msem_remove\f1 \(mi remove semaphore in mapped file or anonymous region@@@\f3msem_remove(2)\f1 .\" index@remove semaphore in mapped file or anonymous region@@@\f3msem_remove(2)\f1 .\" index@semaphore in mapped file or anonymous region, remove@@@\f3msem_remove(2)\f1 .\" index@mapped file or anonymous region, remove semaphore in@@@\f3msem_remove(2)\f1 .\" index@file or anonymous region, remove semaphore in mapped@@@\f3msem_remove(2)\f1 .\" index@anonymous region, remove semaphore in mapped file or@@@\f3msem_remove(2)\f1 .\" index@region, remove semaphore in mapped file or anonymous@@@\f3msem_remove(2)\f1 .\" .\" fileset_database@msem_remove.2 PROGRAMING-MAN .\" $Header: msem_unlock.2,v 72.4 94/11/14 15:25:00 ssa Exp $ .TA m .TH msem_unlock 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME msem_unlock \- unlock a semaphore .SH SYNOPSIS .C "#include " .PP .C "int msem_unlock(msemaphore *sem, int condition);" .SH DESCRIPTION .C msem_unlock() unlocks a binary semaphore. .PP .I sem points to an .C msemaphore structure that specifies the semaphore to be unlocked. .PP If the .I condition argument is zero, the semaphore will be unlocked, whether or not any other processes are currently attempting to lock it. If the .I condition argument is .CR MSEM_IF_WAITERS , and some other process is waiting to lock the semaphore or the implementation cannot reliably determine whether some process is waiting to lock the semaphore, the semaphore is unlocked by the calling process. If the .I condition argument is .CR MSEM_IF_WAITERS , and no process is waiting to lock the semaphore, the semaphore is not unlocked and an error is returned. .PP All calls to .C msem_lock() and .C msem_unlock() by multiple processes sharing a common .C msemaphore structure behave as if the calls were serialized. .PP If the .C msemaphore structure contains any value not resulting from a call to .C msem_init() followed by a (possibly empty) sequence of calls to .C msem_lock() and .CR msem_unlock() , the results are undefined. The address of an .C msemaphore uniquely identifies the semaphore. If the .C msemaphore structure contains any value copied from a .C msemaphore structure at a different address, the result is undefined. .SH IMPLEMENTATION NOTES The system attempts to ignore or recover from invalid values placed in the .C msemaphore structure, but this is not guaranteed for all cases. .SH RETURN VALUE Upon success, .C msem_unlock() returns zero; otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C msem_unlock() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EAGAIN] .C MSEM_IF_NOWAIT was specified and there were no waiters. .TP .SM [EINVAL] .I sem points to an .C msemaphore structure that has been removed, or .I condition is invalid. .TP .SM [EFAULT] .I sem is an invalid pointer. .SH AUTHOR .C msem_unlock() was developed by HP and OSF. .SH SEE ALSO msem_init(2), msem_lock(2), msem_remove(2), mman(5). .SH STANDARDS CONFORMANCE .CR msem_unlock() ": AES" .\" .\" toc@\f3msem_unlock(2)\f1:\0\0\f4msem_unlock\f1@@@unlock a semaphore .\" .\" index@\f4msem_unlock\f1 \(mi unlock a semaphore@@@\f3msem_unlock(2)\f1 .\" index@unlock a semaphore@@@\f3msem_unlock(2)\f1 .\" index@semaphore, unlock a@@@\f3msem_unlock(2)\f1 .\" .\" fileset_database@msem_unlock.2 PROGRAMING-MAN .\" $Header: msgctl.2,v 78.1 96/01/19 20:16:37 ssa Exp $ .TA m .TH msgctl 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME msgctl \- message control operations .SH SYNOPSIS .C "#include " .PP .C "int msgctl(int msqid, int cmd, struct msqid_ds *buf);" .SH DESCRIPTION .C msgctl() provides a variety of message control operations as specified by .IR cmd . The following .IR cmd s are available: .RS .TP 15 .C IPC_STAT Place the current value of each member of the data structure associated with .I msqid into the structure pointed to by .IR buf . The contents of this structure are defined in .IR glossary (9). .TP .C IPC_SET Set the value of the following members of the data structure associated with .I msqid to the corresponding value found in the structure pointed to by .IR buf : .RS .RS .C msg_perm.uid .br .C msg_perm.gid .br .C "msg_perm.mode /* only low 9 bits */" .br .C msg_qbytes .RE .RE .IP This .I cmd can only be executed by a process that has an effective user .SM ID equal to either that of super-user or to the value of either .C msg_perm.uid or .C msg_perm.cuid in the data structure associated with .IR msqid . Only super-user can raise the value of .CR msg_qbytes . .TP .C IPC_RMID Remove the message queue identifier specified by .I msqid from the system and destroy the message queue and data structure associated with it. This .I cmd can only be executed by a process that has an effective user .SM ID equal to either that of super-user or to the value of either .C msg_perm.uid or .C msg_perm.cuid in the data structure associated with .IR msqid . .RE .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .C msgctl() fails if one or more of the following is true: .TP 15 .SM [EINVAL] .I msqid is not a valid message queue identifier. .TP .SM [EINVAL] .I cmd is not a valid command, or the command contains invalid parameters. .TP .SM [EACCES] .I cmd is equal to .C IPC_STAT and Read operation permission is denied to the calling process (see .I message operation permissions in .IR glossary (9)). .TP .SM [EPERM] .I cmd is equal to .C IPC_RMID or .C IPC_SET and the effective user .SM ID of the calling process is not equal to that of a user who has appropriate privileges and it is not equal to the value of either .C msg_perm.uid or .C msg_perm.cuid in the data structure associated with .IR msqid . .TP .SM [EPERM] .I cmd is equal to .CR IPC_SET , an attempt is being made to increase to the value of .CR msg_qbytes , and the effective user .SM ID of the calling process is not equal to that of super-user. .TP .SM [EFAULT] .I buf points to an illegal address. Reliable detection of this error is implementation dependent. .SH SEE ALSO ipcrm(1), ipcs(1), msgget(2), msgop(2), stdipc(3C). .SH STANDARDS CONFORMANCE .CR msgctl() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4msgctl()\fP \(mi message control operations@@@\f3mstctl(2)\f1 .\" index@message control operations@@@\f3mstctl(2)\f1 .\" index@control operations, message@@@\f3mstctl(2)\f1 .\" index@operations, message control@@@\f3mstctl(2)\f1 .\" .\" toc@\f3mstctl(2)\f1:\0\0\f4msgctl()\fP@@@message control operations .\" .\" fileset_database@msgctl.2 PROGRAMING-MAN .\" $Header: msgget.2,v 72.4 94/11/14 15:25:03 ssa Exp $ .TA m .TH msgget 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME msgget \- get message queue .SH SYNOPSIS .C "#include " .PP .C "int msgget(key_t key, int msgflg);" .SH DESCRIPTION .C msgget() returns the message queue identifier associated with .IR key . .PP A message queue identifier and associated message queue and data structure are created for .I key if one of the following is true: .IP .I key is equal to .CR IPC_PRIVATE . This call creates a new identifier, subject to available resources. The identifier will never be returned by another call to .C msgget() until it has been released by a call to .CR msgctl() . The identifier should be used among the calling process and its descendents; however, it is not a requirement. The resource can be accessed by any process having the proper permissions. .IP .I key does not already have a message queue identifier associated with it, and .RI ( msgflg .CR "& IPC_CREAT" ) is ``true''. .PP Upon creation, the data structure associated with the new message queue identifier is initialized as follows: .IP .CR msg_perm.cuid , .CR msg_perm.uid , .CR msg_perm.cgid , and .C msg_perm.gid are set equal to the effective user .SM ID and effective group .SM ID, respectively, of the calling process. .IP The low-order 9 bits of .C msg_perm.mode are set equal to the low-order 9 bits of .IR msgflg . .IP .CR msg_qnum , .CR msg_lspid , .CR msg_lrpid , .CR msg_stime , and .C msg_rtime are set equal to 0. .IP .C msg_ctime is set equal to the current time. .IP .C msg_qbytes is set equal to the system limit. .SH RETURN VALUE Upon successful completion, a non-negative integer, namely a message queue identifier, is returned. Otherwise, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .C msgget() fails if one or more of the following is true: .TP 15 .SM [EACCES] A message queue identifier exists for .IR key , but operation permission as specified by the low-order 9 bits of .I msgflg would not be granted. .TP .SM [ENOENT] A message queue identifier does not exist for .I key and .RI ( msgflg .CR "& IPC_CREAT" ) is ``false''. .TP .SM [ENOSPC] A message queue identifier is to be created but the system-imposed limit on the maximum number of allowed message queue identifiers system wide would be exceeded. .TP .SM [EEXIST] A message queue identifier exists for .I key but .RI (\|( msgflg " & " .CR IPC_CREAT ) && .RI ( msgflg & .CR IPC_EXCL )\|) is ``true''. .SH SEE ALSO ipcrm(1), ipcs(1), msgctl(2), msgop(2), stdipc(3C). .SH STANDARDS CONFORMANCE .CR msgget() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4msgget()\fP \(mi get message queue@@@\f3msgget(2)\f1 .\" index@get: message queue@@@\f3msgget(2)\f1 .\" index@message queue, get@@@\f3msgget(2)\f1 .\" .\" toc@\f3msgget(2)\f1:\0\0\f4msgget()\fP@@@get message queue .\" .\" fileset_database@msgget.2 PROGRAMING-MAN .\" $Header: msgop.2,v 72.5 94/11/14 15:25:07 ssa Exp $ .TA m .TH msgop 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME msgsnd, msgrcv \- message operations .SH SYNOPSIS .C "#include " .nf .PP .C "int msgsnd(" .C " int msqid," .C " const void *msgp," .C " size_t msgsz," .C " int msgflg" .C ");" .PP .C "int msgrcv(" .C " int msqid," .C " void *msgp," .C " size_t msgsz," .C " long msgtyp," .C " int msgflg" .C ");" .fi .SH DESCRIPTION The .CR msgsnd() system call sends a message to the queue associated with the message queue identifier specified by .IR msqid . .PP .I msgp points to a user-defined buffer that must contain first a field of type .CR long that specifies the type of the message, followed by a data portion that will hold the data bytes of the message. The structure below is an example of what this user-defined buffer might look like: .nf .IP .C "long mtype; /* message type */" .C "char mtext[]; /* message text */" .fi .RE .PP .I mtype is a positive integer that can be used by the receiving process for message selection (see .CR msgrcv() below). .I mtext is any text of length .I msgsz bytes. .I msgsz can range from 0 to a system-imposed maximum. .PP .I msgflg specifies the action to be taken if one or more of the following is true: .RS 2 .TP 3 \(bu The number of bytes already on the queue is equal to .CR msg_qbytes (see .B "message queue identifier" in .IR glossary (9)). .TP 3 \(bu The total number of messages on all queues system-wide is equal to the system-imposed limit. .RE .PP These actions are as follows: .RS .PP If .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is true, the message is not sent and the calling process returns immediately. .PP If .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is false, the calling process suspends execution until one of the following occurs: .RS 2 .TP 3 \(bu The condition responsible for the suspension no longer exists, in which case the message is sent. .TP \(bu .I msqid is removed from the system (see .IR msgctl (2)). When this occurs, .CR errno is set to [EIDRM] and a value of .CR -1 is returned. .TP \(bu The calling process receives a signal to be caught. In this case, the message is not sent and the calling process resumes execution in the manner prescribed in .IR signal (5). .RE .RE .PP Upon successful completion, the following actions are taken with respect to the data structure associated with .IR msqid : .RS .PP .CR msg_qnum is incremented by 1. .PP .CR msg_lspid is set to the process ID of the calling process. .PP .CR msg_stime is set to the current time. .RE .PP The .CR msgrcv() system call reads a message from the queue associated with the message queue identifier specified by .IR msqid and places it in the structure pointed to by .IR msgp . This structure is composed of the following members: .nf .IP .C "long mtype; /* message type */" .C "char mtext[]; /* message text */" .fi .PP .I mtype is the received message's type as specified by the sending process. .I mtext is the text of the message. .I msgsz specifies the size in bytes of .I mtext . The received message is truncated to .I msgsz bytes if it is larger than .I msgsz and .RI ( msgflg\c .CR "\0& MSG_NOERROR" ) is true. The truncated part of the message is lost and no indication of the truncation is given to the calling process. .PP .I msgtyp specifies the type of message requested as follows: .RS .TP 12 .IR msgtyp " = 0" First message on the queue is received. .TP .IR msgtyp " > 0" First message of type .I msgtyp is received. .TP .IR msgtyp " < 0" First message of the lowest type that is less than or equal to the absolute value of .I msgtyp is received. .RE .PP .I msgflg specifies the action to be taken if a message of the desired type is not on the queue. These are as follows: .RS .PP If .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is true, the calling process returns immediately with a value of .CR -1 and .CR errno set to [ENOMSG]. .PP If .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is false, the calling process suspends execution until one of the following occurs: .RS 2 .TP 3 \(bu A message of the desired type is placed on the queue. .TP \(bu .I msqid is removed from the system. When this occurs, .CR errno is set to [EIDRM] and a value of \(mi1 is returned. .TP \(bu The calling process receives a signal that is to be caught. In this case, a message is not received and the calling process resumes execution in the manner prescribed in .IR signal (5)). .RE .RE .PP Upon successful completion, the following actions are taken with respect to the data structure associated with .IR msqid . .IP .CR msg_qnum is decremented by 1. .IP .CR msg_lrpid is set to the process ID of the calling process. .IP .CR msg_rtime is set to the current time. .SH RETURN VALUES Upon successful completion, the return value is as follows: .IP .CR msgsnd() returns a value of .CR 0 . .IP .CR msgrcv() returns a value equal to the number of bytes actually placed into .IR mtext . .PP Otherwise, a value of .CR -1 is returned and .CR errno is set to indicate the error. .SH ERRORS If .CR msgrcv() fails, .CR errno is set to one of the following values. .RS .TP 15 [E2BIG] .I mtext is greater than .I msgsz and .RI ( msgflg\c .CR "\0& MSG_NOERROR" ) is false. .TP [EACCES] Operation permission is denied to the calling process. .TP [EFAULT] .I msgp points to an illegal address. The reliable detection of this error is implementation dependent. .TP [EIDRM] The message queue identifier .I msqid has been removed from the system. .TP [EINTR] The function .CR msgrcv() was interrupted by a signal. .TP [EINVAL] .I msqid is not a valid message queue identifier. .TP [EINVAL] .I msgsz is less than 0. .TP [ENOMSG] The queue does not contain a message of the desired type and .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is true. .RE .PP If .CR msgsnd() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] Operation permission is denied to the calling process. .TP [EAGAIN] The message cannot be sent for one of the reasons cited above and .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is true. .TP [EFAULT] .I msgp points to an illegal address. The reliable detection of this error is implementation dependent. .TP [EIDRM] The message queue identifier .I msqid has been removed from the system. .TP [EINTR] .CR msgsnd() was interrupted by a signal. .TP [EINVAL] .I msqid is not a valid message queue identifier. .TP [EINVAL] .I mtype is less than 1. .TP [EINVAL] .I msgsz is less than zero or greater than the system-imposed limit. .RE .SH WARNINGS Check all references to .IR signal (5) for appropriateness on systems that support .IR sigvector (2). .IR sigvector (2) can affect the behavior described on this page. .SH SEE ALSO ipcs(1), msgctl(2), msgget(2), stdipc(3C), signal(5). .SH STANDARDS CONFORMANCE .CR msgrcv() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR msgsnd() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4msgrcv()\f1 \- receive message from message queue@@@\f3msgop(2)\f1 .\" index@\f4msgsnd()\f1 \- send message to message queue@@@\f3msgop(2)\f1 .\" index@\f1message operations@@@\f3msgop(2)\f1 .\" index@\f1message, send or receive message queue message@@@\f3msgop(2)\f1 .\" index@\f1receive message from message queue@@@\f3msgop(2)\f1 .\" index@\f1send message to message queue@@@\f3msgop(2)\f1 .\" .\" toc@\f3msgop(2)\f1:\0\0\f4msgrcv()\f1, \f4msgsnd()\f1@@@message operations .\" toc@\f4msgrcv()\f1:\0\0receive message from message queue@@@see \f3msgop(2)\f1 .\" toc@\f4msgsnd()\f1:\0\0send message to message queue@@@see \f3msgop(2)\f1 .\" .\" links@msgop.2 msgrcv.2 .\" links@msgop.2 msgsnd.2 .\" $Header: msgop.2,v 72.5 94/11/14 15:25:07 ssa Exp $ .TA m .TH msgop 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME msgsnd, msgrcv \- message operations .SH SYNOPSIS .C "#include " .nf .PP .C "int msgsnd(" .C " int msqid," .C " const void *msgp," .C " size_t msgsz," .C " int msgflg" .C ");" .PP .C "int msgrcv(" .C " int msqid," .C " void *msgp," .C " size_t msgsz," .C " long msgtyp," .C " int msgflg" .C ");" .fi .SH DESCRIPTION The .CR msgsnd() system call sends a message to the queue associated with the message queue identifier specified by .IR msqid . .PP .I msgp points to a user-defined buffer that must contain first a field of type .CR long that specifies the type of the message, followed by a data portion that will hold the data bytes of the message. The structure below is an example of what this user-defined buffer might look like: .nf .IP .C "long mtype; /* message type */" .C "char mtext[]; /* message text */" .fi .RE .PP .I mtype is a positive integer that can be used by the receiving process for message selection (see .CR msgrcv() below). .I mtext is any text of length .I msgsz bytes. .I msgsz can range from 0 to a system-imposed maximum. .PP .I msgflg specifies the action to be taken if one or more of the following is true: .RS 2 .TP 3 \(bu The number of bytes already on the queue is equal to .CR msg_qbytes (see .B "message queue identifier" in .IR glossary (9)). .TP 3 \(bu The total number of messages on all queues system-wide is equal to the system-imposed limit. .RE .PP These actions are as follows: .RS .PP If .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is true, the message is not sent and the calling process returns immediately. .PP If .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is false, the calling process suspends execution until one of the following occurs: .RS 2 .TP 3 \(bu The condition responsible for the suspension no longer exists, in which case the message is sent. .TP \(bu .I msqid is removed from the system (see .IR msgctl (2)). When this occurs, .CR errno is set to [EIDRM] and a value of .CR -1 is returned. .TP \(bu The calling process receives a signal to be caught. In this case, the message is not sent and the calling process resumes execution in the manner prescribed in .IR signal (5). .RE .RE .PP Upon successful completion, the following actions are taken with respect to the data structure associated with .IR msqid : .RS .PP .CR msg_qnum is incremented by 1. .PP .CR msg_lspid is set to the process ID of the calling process. .PP .CR msg_stime is set to the current time. .RE .PP The .CR msgrcv() system call reads a message from the queue associated with the message queue identifier specified by .IR msqid and places it in the structure pointed to by .IR msgp . This structure is composed of the following members: .nf .IP .C "long mtype; /* message type */" .C "char mtext[]; /* message text */" .fi .PP .I mtype is the received message's type as specified by the sending process. .I mtext is the text of the message. .I msgsz specifies the size in bytes of .I mtext . The received message is truncated to .I msgsz bytes if it is larger than .I msgsz and .RI ( msgflg\c .CR "\0& MSG_NOERROR" ) is true. The truncated part of the message is lost and no indication of the truncation is given to the calling process. .PP .I msgtyp specifies the type of message requested as follows: .RS .TP 12 .IR msgtyp " = 0" First message on the queue is received. .TP .IR msgtyp " > 0" First message of type .I msgtyp is received. .TP .IR msgtyp " < 0" First message of the lowest type that is less than or equal to the absolute value of .I msgtyp is received. .RE .PP .I msgflg specifies the action to be taken if a message of the desired type is not on the queue. These are as follows: .RS .PP If .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is true, the calling process returns immediately with a value of .CR -1 and .CR errno set to [ENOMSG]. .PP If .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is false, the calling process suspends execution until one of the following occurs: .RS 2 .TP 3 \(bu A message of the desired type is placed on the queue. .TP \(bu .I msqid is removed from the system. When this occurs, .CR errno is set to [EIDRM] and a value of \(mi1 is returned. .TP \(bu The calling process receives a signal that is to be caught. In this case, a message is not received and the calling process resumes execution in the manner prescribed in .IR signal (5)). .RE .RE .PP Upon successful completion, the following actions are taken with respect to the data structure associated with .IR msqid . .IP .CR msg_qnum is decremented by 1. .IP .CR msg_lrpid is set to the process ID of the calling process. .IP .CR msg_rtime is set to the current time. .SH RETURN VALUES Upon successful completion, the return value is as follows: .IP .CR msgsnd() returns a value of .CR 0 . .IP .CR msgrcv() returns a value equal to the number of bytes actually placed into .IR mtext . .PP Otherwise, a value of .CR -1 is returned and .CR errno is set to indicate the error. .SH ERRORS If .CR msgrcv() fails, .CR errno is set to one of the following values. .RS .TP 15 [E2BIG] .I mtext is greater than .I msgsz and .RI ( msgflg\c .CR "\0& MSG_NOERROR" ) is false. .TP [EACCES] Operation permission is denied to the calling process. .TP [EFAULT] .I msgp points to an illegal address. The reliable detection of this error is implementation dependent. .TP [EIDRM] The message queue identifier .I msqid has been removed from the system. .TP [EINTR] The function .CR msgrcv() was interrupted by a signal. .TP [EINVAL] .I msqid is not a valid message queue identifier. .TP [EINVAL] .I msgsz is less than 0. .TP [ENOMSG] The queue does not contain a message of the desired type and .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is true. .RE .PP If .CR msgsnd() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] Operation permission is denied to the calling process. .TP [EAGAIN] The message cannot be sent for one of the reasons cited above and .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is true. .TP [EFAULT] .I msgp points to an illegal address. The reliable detection of this error is implementation dependent. .TP [EIDRM] The message queue identifier .I msqid has been removed from the system. .TP [EINTR] .CR msgsnd() was interrupted by a signal. .TP [EINVAL] .I msqid is not a valid message queue identifier. .TP [EINVAL] .I mtype is less than 1. .TP [EINVAL] .I msgsz is less than zero or greater than the system-imposed limit. .RE .SH WARNINGS Check all references to .IR signal (5) for appropriateness on systems that support .IR sigvector (2). .IR sigvector (2) can affect the behavior described on this page. .SH SEE ALSO ipcs(1), msgctl(2), msgget(2), stdipc(3C), signal(5). .SH STANDARDS CONFORMANCE .CR msgrcv() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR msgsnd() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4msgrcv()\f1 \- receive message from message queue@@@\f3msgop(2)\f1 .\" index@\f4msgsnd()\f1 \- send message to message queue@@@\f3msgop(2)\f1 .\" index@\f1message operations@@@\f3msgop(2)\f1 .\" index@\f1message, send or receive message queue message@@@\f3msgop(2)\f1 .\" index@\f1receive message from message queue@@@\f3msgop(2)\f1 .\" index@\f1send message to message queue@@@\f3msgop(2)\f1 .\" .\" toc@\f3msgop(2)\f1:\0\0\f4msgrcv()\f1, \f4msgsnd()\f1@@@message operations .\" toc@\f4msgrcv()\f1:\0\0receive message from message queue@@@see \f3msgop(2)\f1 .\" toc@\f4msgsnd()\f1:\0\0send message to message queue@@@see \f3msgop(2)\f1 .\" .\" links@msgop.2 msgrcv.2 .\" links@msgop.2 msgsnd.2 .\" $Header: msgop.2,v 72.5 94/11/14 15:25:07 ssa Exp $ .TA m .TH msgop 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME msgsnd, msgrcv \- message operations .SH SYNOPSIS .C "#include " .nf .PP .C "int msgsnd(" .C " int msqid," .C " const void *msgp," .C " size_t msgsz," .C " int msgflg" .C ");" .PP .C "int msgrcv(" .C " int msqid," .C " void *msgp," .C " size_t msgsz," .C " long msgtyp," .C " int msgflg" .C ");" .fi .SH DESCRIPTION The .CR msgsnd() system call sends a message to the queue associated with the message queue identifier specified by .IR msqid . .PP .I msgp points to a user-defined buffer that must contain first a field of type .CR long that specifies the type of the message, followed by a data portion that will hold the data bytes of the message. The structure below is an example of what this user-defined buffer might look like: .nf .IP .C "long mtype; /* message type */" .C "char mtext[]; /* message text */" .fi .RE .PP .I mtype is a positive integer that can be used by the receiving process for message selection (see .CR msgrcv() below). .I mtext is any text of length .I msgsz bytes. .I msgsz can range from 0 to a system-imposed maximum. .PP .I msgflg specifies the action to be taken if one or more of the following is true: .RS 2 .TP 3 \(bu The number of bytes already on the queue is equal to .CR msg_qbytes (see .B "message queue identifier" in .IR glossary (9)). .TP 3 \(bu The total number of messages on all queues system-wide is equal to the system-imposed limit. .RE .PP These actions are as follows: .RS .PP If .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is true, the message is not sent and the calling process returns immediately. .PP If .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is false, the calling process suspends execution until one of the following occurs: .RS 2 .TP 3 \(bu The condition responsible for the suspension no longer exists, in which case the message is sent. .TP \(bu .I msqid is removed from the system (see .IR msgctl (2)). When this occurs, .CR errno is set to [EIDRM] and a value of .CR -1 is returned. .TP \(bu The calling process receives a signal to be caught. In this case, the message is not sent and the calling process resumes execution in the manner prescribed in .IR signal (5). .RE .RE .PP Upon successful completion, the following actions are taken with respect to the data structure associated with .IR msqid : .RS .PP .CR msg_qnum is incremented by 1. .PP .CR msg_lspid is set to the process ID of the calling process. .PP .CR msg_stime is set to the current time. .RE .PP The .CR msgrcv() system call reads a message from the queue associated with the message queue identifier specified by .IR msqid and places it in the structure pointed to by .IR msgp . This structure is composed of the following members: .nf .IP .C "long mtype; /* message type */" .C "char mtext[]; /* message text */" .fi .PP .I mtype is the received message's type as specified by the sending process. .I mtext is the text of the message. .I msgsz specifies the size in bytes of .I mtext . The received message is truncated to .I msgsz bytes if it is larger than .I msgsz and .RI ( msgflg\c .CR "\0& MSG_NOERROR" ) is true. The truncated part of the message is lost and no indication of the truncation is given to the calling process. .PP .I msgtyp specifies the type of message requested as follows: .RS .TP 12 .IR msgtyp " = 0" First message on the queue is received. .TP .IR msgtyp " > 0" First message of type .I msgtyp is received. .TP .IR msgtyp " < 0" First message of the lowest type that is less than or equal to the absolute value of .I msgtyp is received. .RE .PP .I msgflg specifies the action to be taken if a message of the desired type is not on the queue. These are as follows: .RS .PP If .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is true, the calling process returns immediately with a value of .CR -1 and .CR errno set to [ENOMSG]. .PP If .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is false, the calling process suspends execution until one of the following occurs: .RS 2 .TP 3 \(bu A message of the desired type is placed on the queue. .TP \(bu .I msqid is removed from the system. When this occurs, .CR errno is set to [EIDRM] and a value of \(mi1 is returned. .TP \(bu The calling process receives a signal that is to be caught. In this case, a message is not received and the calling process resumes execution in the manner prescribed in .IR signal (5)). .RE .RE .PP Upon successful completion, the following actions are taken with respect to the data structure associated with .IR msqid . .IP .CR msg_qnum is decremented by 1. .IP .CR msg_lrpid is set to the process ID of the calling process. .IP .CR msg_rtime is set to the current time. .SH RETURN VALUES Upon successful completion, the return value is as follows: .IP .CR msgsnd() returns a value of .CR 0 . .IP .CR msgrcv() returns a value equal to the number of bytes actually placed into .IR mtext . .PP Otherwise, a value of .CR -1 is returned and .CR errno is set to indicate the error. .SH ERRORS If .CR msgrcv() fails, .CR errno is set to one of the following values. .RS .TP 15 [E2BIG] .I mtext is greater than .I msgsz and .RI ( msgflg\c .CR "\0& MSG_NOERROR" ) is false. .TP [EACCES] Operation permission is denied to the calling process. .TP [EFAULT] .I msgp points to an illegal address. The reliable detection of this error is implementation dependent. .TP [EIDRM] The message queue identifier .I msqid has been removed from the system. .TP [EINTR] The function .CR msgrcv() was interrupted by a signal. .TP [EINVAL] .I msqid is not a valid message queue identifier. .TP [EINVAL] .I msgsz is less than 0. .TP [ENOMSG] The queue does not contain a message of the desired type and .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is true. .RE .PP If .CR msgsnd() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] Operation permission is denied to the calling process. .TP [EAGAIN] The message cannot be sent for one of the reasons cited above and .RI ( msgflg\c .CR "\0& IPC_NOWAIT" ) is true. .TP [EFAULT] .I msgp points to an illegal address. The reliable detection of this error is implementation dependent. .TP [EIDRM] The message queue identifier .I msqid has been removed from the system. .TP [EINTR] .CR msgsnd() was interrupted by a signal. .TP [EINVAL] .I msqid is not a valid message queue identifier. .TP [EINVAL] .I mtype is less than 1. .TP [EINVAL] .I msgsz is less than zero or greater than the system-imposed limit. .RE .SH WARNINGS Check all references to .IR signal (5) for appropriateness on systems that support .IR sigvector (2). .IR sigvector (2) can affect the behavior described on this page. .SH SEE ALSO ipcs(1), msgctl(2), msgget(2), stdipc(3C), signal(5). .SH STANDARDS CONFORMANCE .CR msgrcv() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR msgsnd() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4msgrcv()\f1 \- receive message from message queue@@@\f3msgop(2)\f1 .\" index@\f4msgsnd()\f1 \- send message to message queue@@@\f3msgop(2)\f1 .\" index@\f1message operations@@@\f3msgop(2)\f1 .\" index@\f1message, send or receive message queue message@@@\f3msgop(2)\f1 .\" index@\f1receive message from message queue@@@\f3msgop(2)\f1 .\" index@\f1send message to message queue@@@\f3msgop(2)\f1 .\" .\" toc@\f3msgop(2)\f1:\0\0\f4msgrcv()\f1, \f4msgsnd()\f1@@@message operations .\" toc@\f4msgrcv()\f1:\0\0receive message from message queue@@@see \f3msgop(2)\f1 .\" toc@\f4msgsnd()\f1:\0\0send message to message queue@@@see \f3msgop(2)\f1 .\" .\" links@msgop.2 msgrcv.2 .\" links@msgop.2 msgsnd.2 .\" $Header: msync.2,v 78.2 96/02/26 13:47:09 ssa Exp $ .TA m .TH msync 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME msync \- synchronize memory with physical storage .SH SYNOPSIS .C "#include " .PP .C "int msync(void *addr,size_t len, int flags);" .SH DESCRIPTION The .CR msync() function writes all modified copies of pages over the range .RI [ addr , .IR addr + len ] to the underlying hardware, or invalidates any copies so that further references to the pages will be obtained by the system from their permanent storage locations. .PP The .IR flags argument is one of the following: .RS .TP 25 .C MS_ASYNC perform asynchronous writes .TP .C MS_SYNC perform synchronous writes .TP .C MS_INVALIDATE invalidate mappings .RE .PP If .IR flags is .CR MS_ASYNC or .CR MS_SYNC , the function synchronizes the file contents to match the current contents of the memory region. .RS .TP 10 \- All write references to the memory region made prior to the call are visible by subsequent read operations on the file. .TP \- It is unspecified whether writes to the same portion of the file prior to the call are visible by read references to the memory region. .TP \- It is unspecified whether unmodified pages in the specified range are also written to the underlying hardware. .RE .PP If flags is .CR MS_ASYNC , the function may return immediately once all write operations are scheduled; if .IR flags is .CR MS_SYNC , the function does not return until all write operations are completed. .PP If .IR flags is .CR MS_INVALIDATE , the function synchronizes the contents of the memory region to match the current file contents. .RS .TP 10 \- All writes to the mapped portion of the file made prior to the call are visible by subsequent read references to the mapped memory region. .TP \- It is unspecified whether write references prior to the call, by any process, to memory regions mapped to the same portion of the file using .CR MAP_SHARED , are visible by read references to the region. .RE .PP If .CR msync() causes any write to the file, then the file's .IR st_ctime and .IR st_mtime fields are marked for update. .SH RETURN VALUE Upon successful completion, .CR msync() returns 0. Otherwise, it returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS The .CR msync() function will fail if: .RS .TP 25 .C [EINVAL] The .IR addr argument is not a multiple of the page size as returned by .CR sysconf() . .TP .C [EIO] An I/O error occurred while reading from or writing to the file system. .TP .C [ENOMEM] Some or all the addresses in the range .RI [ addr , .IR addr + len ] are invalid for the address space of the process or pages not mapped are specified. .RE .SH APPLICATION USAGE The .CR msync() function should be used by programs that require a memory object to be in a known state, for example in building transaction facilities. .PP Normal system activity can cause pages to be written to disk. Therefore, there are no guarantees that .CR msync() is the only control over when pages are or are not written to disk. .SH SEE ALSO mmap(), sysconf(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" $Header: msync.2,v 78.2 96/02/26 13:47:09 ssa Exp $ .TA m .TH msync 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH NAME msync \- synchronize a mapped file .SH SYNOPSIS .C "int msync(caddr_t addr,size_t len, int flags);" .SH DESCRIPTION .C msync controls the caching operations of a mapped file region. .PP .I addr and .I len specify the region to be synchronized. If these are not the address and length of a region created by a previous successful call to .CR mmap() , .C msync() returns an error. The behavior of .C msync() upon a region created with the .C MAP_ANONYMOUS or .C MAP_PRIVATE flags is undefined. .PP After a successful call to .C msync() with .C MS_SYNC specified, all previous modifications to the mapped region are visible to processes using .CR read() . Previous modifications to the file using .C write() may be lost. .PP After a successful call to .C msync() with only .C MS_INVALIDATE specified, all previous modifications to the file using .C write() are visible to the mapped region. Previous direct modifications to the mapped region may be lost. .SS Performance Considerations The following performance considerations only apply when using the .C MS_INVALIDATE option with .CR msync() . These performance constraints do not apply when either .C MS_ASYNC or .C MS_SYNC are exclusively used with .CR msync() . .PP Direct read/write references to portions of a mapped memory region currently undergoing an .CR msync() operation (with MS_INVALIDATE specified), may be blocked until all scheduled write operations are completed. This is especially true when performing an .CR msync() operation across a relatively large address range that requires many individual write operations to be scheduled out to the underlying hardware. HP-UX will schedule a separate write operation for each contiguous group of modified pages on disk. As more write operations are queued out to the device, the overall suspension time of direct read/write references to the same portions of the memory region will generally increase. .PP The suspension times of direct read/write references can be reduced by issuing .CR msync() requests over smaller portions of the memory region, but issuing them more frequently than a corresponding larger synchronization request. This will serve to more evenly distribute I/O activity across the mapped file, while reducing the number of write operations per .CR msync() . .SH ERRORS .RS .TP 15 .SM [EINVAL] .I addr is not a multiple of the page size as returned by .CR sysconf(_SC_PAGE_SIZE) . .TP .SM [EINVAL] The address range specified by .I addr and .I len was not created by a successful call to .CR mmap() . .SH AUTHOR .C msync() was developed by HP, AT&T, and OSF. .SH SEE ALSO mmap(2), sysconf(2). .SH STANDARDS CONFORMANCE .CR msync() ": AES, SVID3" .\" .\" toc@\f3msync(2)\f1:\0\0\f4msync\f1@@@synchronize a mapped file .\" .\" index@\f4msync\f1 \- synchronize a mapped file@@@\f3msync(2)\f1 .\" index@synchronize a mapped file@@@\f3msync(2)\f1 .\" index@mapped file, synchronize a@@@\f3msync(2)\f1 .\" index@file, synchronize a mapped@@@\f3msync(2)\f1 .\" .\" $Header: munmap.2,v 76.1 95/07/07 14:47:50 ssa Exp $ .TA m .TH munmap 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME munmap \- unmap pages of memory .SH SYNOPSIS .C "#include " .PP .C "int munmap(void *addr, size_t len);" .SH DESCRIPTION The .C munmap() function removes the mappings for pages in the range .RI [ addr , .IR addr + len ], rounding the .IR len argument up to the next multiple of the page size as returned by .CR sysconf() . If .IR addr is not the address of a mapping established by a prior call to .CR mmap() , the behaviour is undefined. After a successful call to .CR munmap() and before any subsequent mapping of the unmapped pages, further references to these pages will result in the delivery of a .CR SIGBUS or .CR SIGSEGV signal to the process. .SH RETURN VALUE Upon successful completion, .CR munmap() returns 0. Otherwise, it returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS The .CR munmap() function will fails if: .RS .TP 15 [EINVAL] The .IR addr argument is not a multiple of the page size as returned by .CR sysconf() . .TP [EINVAL] Addresses in the range .RI [ addr , .IR addr + len ], are outside the valid range for the address space of a process. .TP [EINVAL] The .IR len argument is 0. .SH SEE ALSO mmap*() , sysconf() , , . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" $Header: munmap.2,v 76.1 95/07/07 14:47:50 ssa Exp $ .TA m .TH munmap 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH SYNOPSIS .C "int munmap(caddr_t addr, size_t len);" .SH DESCRIPTION .C munmap() unmaps a mapped file or anonymous memory region. .PP If the address range specified by .I addr and .I len was not created by a successful call to .CR mmap() , .C munmap() returns an error. .PP If the specified address range was created by multiple calls to .CR mmap() , .C munmap() succeeds in unmapping all of the specified regions, provided they form a contiguous address range. .PP If the region was created with the .C MAP_PRIVATE option, any modifications made to the region are discarded. .SH ERRORS .RS .TP 15 [EINVAL] .I addr is not a multiple of the page size as returned by .CR sysconf(_SC_PAGE_SIZE) . .TP .SM [EINVAL] The address range specified by .I addr and .I len was not created by a successful call to .CR mmap() . .SH AUTHOR .C munmap() was developed by HP, AT&T, and OSF. .SH SEE ALSO mmap(2), sysconf(2). .SH STANDARDS CONFORMANCE .CR munmap() ": AES, SVID3" .\" .\" toc@\f3munmap(2)\f1:\0\0\f4munmap\f1@@@unmap a mapped region .\" .\" index@\f4munmap\f1 \- unmap a mapped region@@@\f3munmap(2)\f1 .\" index@unmap a mapped region@@@\f3munmap(2)\f1 .\" index@mapped region, unmap a@@@\f3munmap(2)\f1 .\" index@region, unmap a mapped@@@\f3munmap(2)\f1 .\" .\" fileset_database@munmap.2 PROGRAMING-MAN .\" $Header: nanosleep.2,v 74.1 95/03/23 18:05:15 ssa Exp $ .TA n .TH nanosleep 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nanosleep() \- high resolution sleep .SH SYNOPSIS .C "#include " .PP .nf .C "int nanosleep(" .PD 0 .IP .C "const struct timespec *rqtp," .C "struct timespec *rmtp" .PP .C ");" .PD .SH DESCRIPTION The .CR nanosleep() function causes the current process to be suspended from execution until either the time interval specified by the .CR rqtp argument has elapsed, or a signal is delivered to the calling process and its action is to invoke a signal-catching function or to terminate the process. The suspension time may be longer than that requested because the argument value is rounded up to an integer multiple of the sleep resolution or because of the scheduling of other activity by the system. But, except for the case of being interrupted by a signal, the suspension time will not be less than the time specified by .CR rqtp , as measured by the system clock, .CR CLOCK_REALTIME . .PP The use of the .CR nanosleep() function has no effect on the action or blockage of any signal. .SH RETURN VALUE If the .CR nanosleep() function returns because the requested time has elapsed, its return value is zero. .PP If the .CR nanosleep() function returns because it has been interrupted by a signal, the function returns a value of \(mi1 and sets .CR errno to indicate the interruption. If the .CR rmtp argument is non-\c .SM NULL, the .I timespec structure referenced by it is updated to contain the amount of time remaining in the interval (the requested time minus the time actually slept). If the .CR rmtp argument is .SM NULL, the remaining time is not returned. .PP If .CR nanosleep() fails, it returns a value of \(mi1 and sets .CR errno to indicate the error. .SH ERRORS If any of the following conditions occur, the .CR nanosleep() function returns \(mi1 and sets .CR errno (see .IR errno (2)) to the corresponding value: .RS .TP 12 .SM [EINTR] .C nanosleep() was interrupted by a signal. .TP .SM [EINVAL] The .CR rqtp argument specified a nanosecond value less than zero or greater than or equal to 1000 million. .TP .SM [ENOSYS] The function .CR nanosleep() is not supported by this implementation. .TP .SM [EFAULT] The .CR rqtp or .CR rmtp arguments specify an invalid address. .RE .SH EXAMPLES Suspend execution of the current process for half a second: .PD 0 .nf .IP .C "#include " .C "#include " .C " " .C struct timespec interval, remainder; .C " " .C interval.tv_sec = 0; .C interval.tv_nsec = 500000000; .C if (nanosleep(&interval, &remainder) == -1) { .RS .RS .C if (errno == EINTR) { .RS .C (void)printf("nanosleep interrupted\en"); .C (void)printf("Remaining secs: %d\en", remainder.tv_sec); .C (void)printf("Remaining nsecs: %d\en", remainder.tv_nsec); .RE .C } .C else perror("nanosleep"); .RE .C } .PD .fi .SH AUTHOR .CR nanosleep was derived from the proposed IEEE POSIX P1003.4 Standard, Draft 14. .SH SEE ALSO clocks(2), timers(2), sleep(3C). .SH STANDARDS CONFORMANCE .CR nanosleep() ": POSIX.4" .\" .\" toc@\f3nanosleep(2)\f1:\0\0\f4nanosleep()\f1@@@high resolution sleep\f1 .\" index@\f4nanosleep\f1 \- high resolution sleep@@@\f3nanosleep(2)\f1 .\" index@\f1high resolution sleep@@@\f3nanosleep(2)\f1 .\" index@\f1sleep, high resolution@@@\f3nanosleep(2)\f1 .\" $Header: nfssvc.2,v 72.3 93/01/14 14:44:13 ssa Exp $ .TA n .TH nfssvc 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nfssvc, async_daemon \- \s-1NFS\s0 daemons .SH SYNOPSIS .nf .C int nfssvc(int sock); .PP .C void async_daemon(); .SH DESCRIPTION .C nfssvc() starts an .SM NFS daemon listening on socket .IR sock . The socket must be .SM AF_INET and .SM SOCK_DGRAM (protocol .SM UDP/IP\s0). The system call returns only if the process is killed. .PP .I async_daemon implements the .SM NFS daemon that handles asynchronous .SM I/O for an .SM NFS client. The system call never returns. .SH ERRORS .C nfssvc() fails if any of the following conditions is encountered, and sets .C errno accordingly: .RS .TP 15 .SM [EBADF] .I sock is not a valid socket descriptor. .TP 15 .SM [EINVAL] .I sock refers to a socket that is not an .SM AF_INET and .SM SOCK_DGRAM socket. .RE .PP .I async_daemon fails if the following condition is encountered, and sets .C errno accordingly: .RS .TP 15 .SM [ENOMEM] There are not enough resources to create the process. .RE .SH WARNINGS This call should be used only by HP-supplied commands and is not recommended for use by non-HP-supplied programs. .PP These two system calls allow kernel processes to have user context. .SH AUTHOR .C nfssvc() was developed by Sun Microsystems, Inc. .SH SEE ALSO mountd(1M), nfsd(1M). .\" .\" index@\f4nfssvc()\fP: \s-1NFS\s+1 daemon@@@\f3nfssvc(2)\f1 .\" index@\f2async_daemon\f1: \s-1NFS\s+1 daemon@@@\f3nfssvc(2)\f1 .\" index@\s-1NFS\s+1 daemons@@@\f3nfssvc(2)\f1 .\" index@daemons, \s-1NFS\s+1@@@\f3nfssvc(2)\f1 .\" .\" toc@\f3nfssvc(2)\f1: \f4nfssvc()\fP, \f2async_daemon\f1@@@\s-1NFS\s0 daemons .\" .\" links@nfssvc.2 async_daemo.2 .\" .\" fileset_database@nfssvc.2 PROGRAMING-MAN .\" $Header: nice.2,v 72.4 94/11/14 15:25:25 ssa Exp $ .TA n .TH nice 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nice \- change priority of a process .SH SYNOPSIS .C "#include .PP .C "int nice(int priority_change);" .SH DESCRIPTION .C nice() adds the value of .I priority_change to the nice value of the calling process. A process's .B nice value is a positive number for which a more positive value results in lower .SM CPU priority. .PP A maximum nice value of 39 and a minimum nice value of 0 are imposed by the system. Requests for values above or below these limits result in the nice value being set to the corresponding limit. .SH RETURN VALUE Upon successful completion, .C nice() returns the new nice value minus 20. Otherwise, a value of \(mi1 is returned and .C errno is set to indicate the error. .PP Note that .C nice() assumes a user process priority value of 20. If a user having appropriate privileges has changed the user process priority value to something less than 20, certain values for .I priority_change can cause .C nice() to return \(mi1, which is indistinguishable from an error return. .SH ERRORS .TP 15 .SM [EPERM] .C nice() fails and does not change the nice value if .I priority_change is negative or greater than 40, and the effective user .SM ID of the calling process is not a user having appropriate privileges. .SH SEE ALSO nice(1), renice(1), exec(2). .SH STANDARDS CONFORMANCE .CR nice() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4nice()\fP \(mi change priority of a process@@@\f3nice(2)\f1 .\" index@change priority of a process@@@\f3nice(2)\f1 .\" index@priority of a process, change@@@\f3nice(2)\f1 .\" index@process, change priority of a@@@\f3nice(2)\f1 .\" .\" toc@\f3nice(2)\f1:\0\0\f4nice()\fP@@@change priority of a process .\" .\" fileset_database@nice.2 PROGRAMING-MAN .\" $Header: open.2,v 78.1 96/02/12 14:07:23 ssa Exp $ .TA o .TH open 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME open() \- open file for reading or writing .SH SYNOPSIS .C "#include " .PP .CR "int open(const char *path, int oflag, ... /* " [ "mode_t mode" ] " */ );" .SS Remarks The ANSI C "\c .CR ", ...\&\c" " construct specifies a variable length argument list whose optional member is given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION The .CR open() system call opens a file descriptor for the named file and sets the file status flags according to the value of .IR oflag . .PP The .I path argument points to a path name naming a file, and must not exceed .CR PATH_MAX bytes in length. .PP The .I oflag argument is a value that is the bitwise inclusive OR of flags listed in "Read-Write Flags," "General Flags," and "Synchronized I/O Flags" below. .PP The optional .I mode argument is only effective when the .CR O_CREAT flag is specified. .PP The file pointer used to mark the current position within the file is set to the beginning of the file. .PP The new file descriptor is set to remain open across .CI exec * () system calls. See .IR fcntl (2). .SS Read-Write Flags Exactly one of the .CR O_RDONLY , .CR O_WRONLY , or .CR O_RDWR flags must be used in composing the value of .IR oflag . If none or more than one is used, the behavior is undefined. .RS .TP 15 .CR O_RDONLY Open for reading only. .TP .CR O_WRONLY Open for writing only. .TP .CR O_RDWR Open for reading and writing. .RE .SS General Flags Several of the flags listed below can be changed with the .CR fcntl() system call while the file is open. See .IR fcntl (2) and .IR fcntl (5) for details. .RS .TP 15 .CR O_APPEND If set, the file offset is set to the end of the file prior to each write. .TP .CR O_CREAT If the file exists, this flag has no effect, except as noted under .CR O_EXCL below. Otherwise, the owner ID of the file is set to the effective user ID of the process, the group ID of the file is set to the effective group ID of the process if the set-group-ID bit of the parent directory is not set, or to the group ID of the parent directory if the set-group-ID bit of the parent directory is set. .IP The file access permission bits of the new file mode are set to the value of .IR mode , modified as follows (see .IR creat (2)): .RS .RS 2 .TP 3 \(bu For each bit set in the file mode creation mask of the process, the corresponding bit in the new file mode is cleared (see .IR umask (2)). .TP \(bu The "save text image after execution" bit of the new file mode is cleared. See .IR chmod (2). .TP \(bu On systems with access control lists, three base ACL entries are created corresponding to the file access permissions (see .IR acl (5)). .RE .RE .TP .CR O_EXCL If .CR O_EXCL and .CR O_CREAT are set and the file exists, .CR open() fails. .TP .CR O_LARGEFILE When the filesystem is mounted as large files enabled and the file is opened with the .CR O_LARGEFILE option, the file can grow over 2 GB. .TP .CR O_NDELAY This flag might affect subsequent reads and writes. See .IR read (2) and .IR write (2). .IP When opening a FIFO with .CR O_RDONLY or .CR O_WRONLY set: .RS .IP If .CR O_NDELAY is set: .RS .IP A read-only .CR open() returns without delay. .IP A write-only .CR open() returns an error if no process currently has the file open for reading. .RE .IP If .CR O_NDELAY is clear: .RS .IP A read-only .CR open() does not return until a process opens the file for writing. .IP A write-only .CR open() does not return until a process opens the file for reading. .RE .RE .IP When opening a file associated with a communication line: .RS .IP If .CR O_NDELAY is set: .RS .IP The .CR open() returns without waiting for carrier. .RE .IP If .CR O_NDELAY is clear: .RS .IP The .CR open() does not return until carrier is present. .RE .RE .TP .CR O_NOCTTY If set, and .I path identifies a terminal device, .CR open() does not cause the terminal to become the controlling terminal for the process. .TP .CR O_NONBLOCK Same effect as .CR O_NDELAY for .IR open (2), but slightly different effect in .IR read (2) and .IR write (2). If both .CR O_NONBLOCK and .CR O_NDELAY are specified, .CR O_NONBLOCK takes precedence. .TP .CR O_TRUNC If the file exists, its length is truncated to 0 and the mode and owner are unchanged. .RE .SS Synchronized I/O Flags Together, the .CR O_DSYNC , .CR O_RSYNC , and .CR O_SYNC flags constitute support for Synchronized I/O. These flags are ignored for files other than ordinary files and block special files on those systems that permit I/O to block special devices (see .IR pathconf (2)). If both the .CR O_DSYNC and .CR O_SYNC flags are set, the effect is as if only the .CR O_SYNC flag was set. The .CR O_RSYNC flag is ignored if it is not set along with the .CR O_DSYNC or .CR O_SYNC flag. .RS .TP .CR O_DSYNC If a file is opened with .CR O_DSYNC or that flag is set with the .CR F_SETFL option of .CR fcntl() , writes to that file by the process block until the data specified in the write request and all file attributes required to retrieve the data are written to the disk. File attributes that are not necessary for data retrieval (access time, modification time, status change time) are not necessarily written to the disk prior to returning to the calling process. .TP .CR O_SYNC Identical to .CR O_DSYNC , with the addition that all file attributes changed by the write operation (including access time, modification time, and status change time) are also written to the disk prior to returning to the calling process. .TP .CR O_RSYNC|O_DSYNC " (specified together)" Identical to .CR O_DSYNC for file system writes. .IP For file system reads, the calling process blocks until the data being read and all file attributes required to retrieve the data are the same as their image on disk. Writes pending on the data to be read are executed prior to returning to the calling process. .TP .CR O_RSYNC|O_SYNC " (specified together)" Identical to .CR O_SYNC for file system writes. .IP Identical to .CR O_RSYNC|O_DSYNC for file system reads, with the addition that all file attributes changed by the read operation (including access time, modification time, and status change time) too are the same as their image on disk. .RE .SH RETURN VALUE .CR open() returns the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .I n is a file descriptor for the opened file. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR open() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] .I oflag permission is denied for the named file. .TP [EACCES] A component of the path prefix denies search permission. .TP [EACCES] The file does not exist and the directory in which the file is to be created does not permit writing. .TP [EACCES] .CR O_TRUNC is specified and write permission is denied. .TP [EAGAIN] The file exists, enforcement mode file/record locking is set (see .IR chmod (2)), there are outstanding record locks on the file with the .CR lockf() or .CR fcntl() system calls, and .CR O_TRUNC is set. .TP [EDQUOT] User's disk quota block or inode limit has been reached for this file system. .TP [EEXIST] .CR O_CREAT and .CR O_EXCL are set and the named file exists. .TP [EFAULT] .I path points outside the allocated address space of the process. .TP [EINTR] A signal was caught during the .CR open() system call, and the system call was not restarted (see .IR signal (5) and .IR sigvector (2)). .TP [EINVAL] .I oflag specifies both .CR O_WRONLY and .CR O_RDWR . .TP [EINVAL] .I oflag specifies both .CR O_NONBLOCK and .CR O_NDELAY . .TP [EISDIR] The named file is a directory and .I oflag is write or read/write. .TP [ELOOP] Too many symbolic links are encountered in translating the path name. .TP [EMFILE] The maximum number of file descriptors allowed are currently open. .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENFILE] The system file table is full. .TP [ENODEV] The named file is a character special or block special file, and the device associated with this special file either does not exist, or the driver for this device has not been configured into the kernel. .TP [ENOENT] The named file does not exist (for example, .I path is null or a component of .I path does not exist, or the file itself does not exist and .CR O_CREAT is not set). .TP [ENOTDIR] A component of the path prefix is not a directory. .TP [ENXIO] .CR O_NDELAY is set, the named file is a FIFO, .CR O_WRONLY is set, and no process has the file open for reading. .TP [ENOSPC] .CR O_CREAT is specified, the file does not already exist, and the directory that would contain the file cannot be extended. .TP [EOVERFLOW] The named file is a regular file and the size of the file cannot be represented correctly in an object of size .CR off_t . .TP [EROFS] The named file resides on a read-only file system and .I oflag is write or read/write. .TP [ETXTBSY] The file is open for execution and .I oflag is write or read/write. Normal executable files are only open for a short time when they start execution. Other executable file types can be kept open for a long time, or indefinitely under some circumstances. .RE .SH EXAMPLES The following call to .CR open() opens file .CR inputfile for reading only and returns a file descriptor for .CR inputfile . For an example of reading from file .CR inputfile , see the .IR read (2) manual entry. .IP .C "int infd;" .br .C "infd = open (""inputfile"", O_RDONLY);" .PP The following call to .CR open() opens file .CR outputfile for writing and returns a file descriptor for .CR outputfile . For an example of preallocating disk space for .CR outputfile , see the .IR prealloc (2) manual entry. For an example of writing to .CR outputfile , see the .IR write (2) manual entry. .IP .C "int outfd;" .br .C "outfd = open (""outputfile"", O_WRONLY);" .PP The following call opens file .CR iofile for synchronized I/O file integrity for reads and writes. .IP .C "int iofd;" .br .C "iofd = open (""iofile"", O_RDWR|O_SYNC|O_RSYNC);" .SH AUTHOR .CR open() was developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO chmod(2), close(2), creat(2), dup(2), fcntl(2), lockf(2), lseek(2), open64(2), pathconf(2), read(2), select(2), umask(2), write(2), setacl(2),\"STD acl(5),\"STD fcntl(5), signal(5), unistd(5). .SH STANDARDS CONFORMANCE .CR open() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.4" .\" .\" index@\f4open()\f1 \- open file for reading or writing@@@\f3open(2)\f1 .\" index@\f1file, open for reading or writing@@@\f3open(2)\f1 .\" index@\f1reading, open file for@@@\f3open(2)\f1 .\" index@\f1writing, open file for@@@\f3open(2)\f1 .\" .\" toc@\f3open(2)\f1:\0\0\f4open()\f1@@@open file for reading or writing .\" $Header: creat64.2,v 78.2 96/02/12 13:37:12 ssa Exp $ .TA c .TH creat64 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME creat64(\|), fstat64(\|), getrlimit64(\|), lockf64(\|), lseek64(\|), lstat64(\|), mmap64(\|), open64(\|), prealloc64(\|), setrlimit64(\|), stat64(\|), statvfs64(\|), truncate64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0creat64(const\0char\0*path,\0mode_t\0mode);" .PP .C "#include " .PP .C "int\0fstat64(int\0fildes,\0struct\0stat64\0*buf);" .PP .C "include\0" .PP .C "int\0getrlimit64(int resource,\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0lock64(int\0*fildes,\0int\0function,\0off64_t\0size);" .PP .C "#include " .PP .C "off64_t\0lseek64(int\0*fildes,\0off64_t\0offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0lstat64(const\0char\0*,\0struct\0stat64\0*);" .PP .C "#include " .PP .C "void\0mmap64(void\0addr,\0size_t\0len,\0int\0prot,\0int\0flags,\0int\0fildes,\0off64_t\0off);" .PP .C "#include " .PP .C "int\0open64(const\0char\0*path,\0int\0oflag,...);" .PP .C "#include " .PP .C "int\0prealloc64(int\0fildes,\0off64_t\0size);" .PP .C "include\0" .PP .C "int\0setrlimit64(int\0resource,\0const\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0stat64(const\0char\0*path,\0struct\0stat64\0*buf);" .PP .C "#include " .PP .C "int\0statvfs64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "int\0truncate64(const\0char\0*path,\0off64_t\0length);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 18 .C creat64() The .C creat64() function is identical to .C creat() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. .C creat64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR creat() . .TP .C fstat64() The .C fstat64() function is identical to .C fstat() except that .C fstat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C getrlimit64 The .C getrlimit64() function is identical to .C getrlimit() except that .C getrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .CR "struct rlimit" . All other functional behaviors, returns, and errors are identical. .TP .C lock64() The .C lock64() function is identical to .C lockf() except that .C lockf64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C lseek64() The .C lseek64() function is identical to .C lseek() except that .C lseek64() accepts an .CR off64_t type as the desired offset and has a return value of .CR off64_t. All other functional behaviors, returns, and errors are identical. .TP .C lstat64() The .C lstat64() function is identical to .C lstat() except that .C lstat64() returns file status in a .C struct stat64 instead of .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C mmap64() The .C mmap64() function is identical to .C mmap() except that .C mmap64() accepts the file offset as an .CR off64_t . .TP .C open64() The .C open64() function is identical to .C open() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. The .C open64() function is equivalent to .C open() function (in 32-bit compile environment) with .C O_LARGEFILE flag set. .C open64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR open() . .TP .C prealloc64() The .C prealloc64() function is identical to .C prealloc() except that .C prealloc64() accepts the file offset as an .CR off64_t . All other functional behaviors, returns, and errors are identical to .CR prealloc() . .TP .C setrlimit64 The .C setrlimit64() function is identical to .C setrlimit() except that .C setrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .C struct rlimit. All other functional behaviors, returns, and errors are identical. .TP .C stat64() The .C stat64() function is identical to .C stat() except that .C stat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . .TP .C statvfs64() Refer to .CR fstatvfs64() . .TP .C truncate64() The .C truncate64() function is identical to .C truncate() except that .C truncate64() accepts the length parameter as an .C off64_t instead of .CR off_t . All other functional behaviors, returns, and errors are identical to .CR truncate() . .\" .\" toc@\f4creat64(2)\f1:\0\0\f4fstat64\f1, \f4getrlimit64\f1, \f4lockf64\f1, \f4lseek64\f1, \f4lstat64\f1, \f4mmap64\f1, \f4open64\f1, \n\f4prealloc64\f1, \f4setrlimit64\f1, \f4stat64\f1, \f4statvfs64\f1, \f4truncate64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4creat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4fstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4getrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lockf64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lseek64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4mmap64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4open64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4prealloc64()\f1 \- file sysmmaptem API to support large files@@@\f3creat64(2)\f1 .\" index@\f4setrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4stat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4statvfs64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4truncate64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3creat64(2)\f1 .\" .\" links@creat64.2 fstat64.2 .\" links@creat64.2 getrlimit64.2 .\" links@creat64.2 lockf64.2 .\" links@creat64.2 lseek64.2 .\" links@creat64.2 lstat64.2 .\" links@creat64.2 mmap64.2 .\" links@creat64.2 open64.2 .\" links@creat64.2 prealloc64.2 .\" links@creat64.2 setrlimit64.2 .\" links@creat64.2 stat64.2 .\" links@creat64.2 statvfs64.2 .\" links@creat64.2 truncate64.2 .\" .\" $Header: pathconf.2,v 78.1 96/02/12 14:08:34 ssa Exp $ .TA p .TH pathconf 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pathconf(\|), fpathconf(\|) \- get configurable path name variables .SH SYNOPSIS .C "#include " .PP .C "long pathconf(const char *path, int name);" .PP .C "long fpathconf(int fildes, int name);" .SH DESCRIPTION The .CR pathconf() and .CR fpathconf() functions provide a method for applications to determine the value of a configurable limit or option associated with a file or directory (see .IR limits (5) and .CR ). .PP For .CR pathconf() , the .IR path argument points to the path name of a file or directory. .PP For .CR fpathconf() , the .IR fildes argument is an open file descriptor. .PP For both functions, the .IR name argument represents the variable to be queried regarding the file or directory to which the other argument refers. .PP The following table lists the configuration variables available from .CR pathconf() and .CR fpathconf() , and lists for each variable the associated value of the .IR name argument: .PP .TS center tab(@); cB | cB | cB lf4 | lf4 | l. Variable@Value of \f2name\f1@Notes _ LINK_MAX@_PC_LINK_MAX@1 MAX_CANON@_PC_MAX_CANON@2 MAX_INPUT@_PC_MAX_INPUT@2 @_PC_FILESIZEBITS@3, 4, 10 NAME_MAX@_PC_NAME_MAX@3, 4 PATH_MAX@_PC_PATH_MAX@4, 5 PIPE_BUF@_PC_PIPE_BUF@6 _POSIX_CHOWN_RESTRICTED@_PC_CHOWN_RESTRICTED@7, 8 _POSIX_NO_TRUNC@_PC_NO_TRUNC@3, 4 _POSIX_SYNC_IO@_PC_SYNC_IO@9 _POSIX_VDISABLE@_PC_V_DISABLE@2 .TE .PP The variables in the table are defined as constants in .CR or .CR if they do not vary from one path name to another. The associated values of the .I name argument are defined in .CR . .SH RETURN VALUE The following notes further qualify the table above. .RS .TP 5 1. If .I path or .I fildes refers to a directory, the value returned applies to the directory itself. .TP 2. If the variable is constant, the value returned is identical to the variable's definition in .CR or .CR regardless of the type of .IR fildes or .IR path . The behavior is undefined if .I path or .I fildes does not refer to a terminal file. .TP 3. If .I path or .I fildes refers to a directory, the value returned applies to the file names within the directory. .TP 4. If .I path or .I fildes does not refer to a directory, .CR pathconf() or .CR fpathconf() returns \(mi1 and sets .CR errno to EINVAL. .TP 5. If .I path or .I fildes refers to a directory, the value returned is the maximum length of a relative path name when the specified directory is the working directory. .TP 6. If .I path refers to a FIFO, or if .I fildes refers to a pipe or FIFO, the value returned applies to the pipe or FIFO itself. If .I path or .I fildes refers to a directory, the value returned applies to any FIFOs that exist or can be created within the directory. If .CR PIPE_BUF is a constant, the value returned is identical to the definition of .CR PIPE_BUF in .CR regardless of the type of .I fildes or .IR path . The behavior is undefined for a file other than a directory, FIFO, or pipe. .TP 7. If .I path or .I fildes refers to a directory, the value returned applies to files of any type, other than directories, that exist or can be created within the directory. .TP 8. .CR _POSIX_CHOWN_RESTRICTED is defined if the privilege group .CR PRIV_GLOBAL has been granted the .CR CHOWN privilege (see .IR getprivgrp (2) and .IR chown (2)). In all other cases, .CR _POSIX_CHOWN_RESTRICTED is undefined and .CR pathconf() or .CR fpathconf() returns \(mi1 without changing .CR errno . To determine if .CR chown() can be performed on a file, it is simplest to attempt the .CR chown() operation and check the return value for failure or success. .TP 9. .CR _POSIX_SYNC_IO , when defined, determines whether synchronized IO operations may be performed for the associated file (see .IR open (2)). If .I path or .I fildes refers to a directory, it is unspecified whether or not the implementation supports an association of the variable name with the specified file. .TP 10. For file systems that are not large file enabled, the .CR _PC_FILESIZEBITS return value will be less than or equal to 32. For file systems that are large file enabled, the .CR _PC_FILESIZEBITS return value will be between 33 and 63. .RE .PP If the variable corresponding to .IR name is not defined for .IR path or .IR fildes , the .CR pathconf() and .CR fpathconf() functions succeed and return a value of \(mi1, without changing the value of .CR errno . .PP Upon any other successful completion, these functions return the value of the named variable with respect to the specified file or directory, as described above. .PP Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR pathconf() and .CR fpathconf() fail if any of the following conditions are encountered: .RS .TP 25 [EACCES] A component of the path prefix denies search permission. .TP [EBADF] The .IR fildes argument is not a valid open file descriptor. .TP [EFAULT] .I path points outside the allocated address space of the process. .TP [EINVAL] The value of .I name is not valid or the implementation does not support an association of the variable .IR name with the specified file. .TP [ELOOP] Too many symbolic links were encountered in translating .IR path . .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] The file named by .I path does not exist (for example, .I path is null, or a component of .I path does not exist). .TP [ENOTDIR] A component of the path prefix is not a directory. .\" The following should be included if actual device opens are .\" required to determine tty/line discipline parameters. .\" .TP .\" .SM [ENXIO] .\" The specified file is a character special or block special file, .\" and the device associated with this special file does not exist. .RE .SH EXAMPLES The following example sets .IR val to the value of .CR MAX_CANON for the device file being used as the standard input. If the standard input is a terminal, this value is the maximum number of input characters that can be entered on a single input line before typing the newline character: .nf .IP .C "if (isatty(0))" .RS .C "val = fpathconf(0, _PC_MAX_CANON);" .fi .RE .PP The following code segment shows two calls to .IR pathconf . The first determines whether a file name longer than .CR NAME_MAX bytes will be truncated to .CR NAME_MAX bytes in the .C /tmp directory. If so, the second call is made to determine the actual value of .CR NAME_MAX so that an error can be printed if a user-supplied file name stored in .I filebuf will be truncated in this directory: .nf .RS .IP .C "extern int errno;" .C "char *filebuf;" .RS .C "errno = 0; /* reset errno */" .C "if ( pathconf(""/tmp"" _PC_NO_TRUNC) == -1 ) {" .RS .C "/* _POSIX_NO_TRUNC is not in effect for this directory */" .C "if (strlen(filebuf) > pathconf("/tmp", PC_NAME_MAX)) {" .RS .C "fprintf(stderr, ""Filename %s too long.\\n"", filebuf);" .C "/* take error action */" .RE .C } .C else .RS .RS .C "if (errno) {" .RS .C "perror(""pathconf"");" .C "/* take error action */" .RE .C } .RE .C } .RE .RE .RE .C "/* otherwise, _POSIX_NO_TRUNC is in effect for this directory */" .RS .C "if ((fd = open(filebuf, O_CREAT, mode)) < 0)" .RS .C "perror(filebuf);" .fi .SH DEPENDENCIES .SS NFS The following error can occur: .RS .TP 20 [EOPNOTSUPP] .I path or .I fildes refers to a file for which a value for .I name cannot be determined. In particular, .CR _PC_LINK_MAX , .CR _PC_NAME_MAX , .CR _PC_PIPE_BUF , .CR _PC_PATH_MAX , .CR _PC_NO_TRUNC , and .CR _PC_CHOWN_RESTRICTED , cannot be determined for an NFS file. .RE .SH AUTHOR .CR pathconf() and .CR fpathconf() were developed by HP. .SH SEE ALSO chown(2), errno(2), limits(5), unistd(5), termio(7). .SH STANDARDS CONFORMANCE .CR pathconf() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.2, POSIX.4" .PP .CR fpathconf() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.2, POSIX.4" .\" .\" index@\f4pathconf()\f1 \- get configurable path name variables@@@\f3pathconf(2)\f1 .\" index@\f4fpathconf()\f1 \- get configurable path name variables@@@\f3pathconf(2)\f1 .\" index@\f4fpathconf()\f1 \- get configurable path name variables@@@\f3pathconf(2)\f1 .\" index@\f1get configurable path name variables@@@\f3pathconf(2)\f1 .\" index@\f1configurable path name variables, get@@@\f3pathconf(2)\f1 .\" index@\f1path name variables, get configurable@@@\f3pathconf(2)\f1 .\" index@\f1variables, configurable path name, get@@@\f3pathconf(2)\f1 .\" .\" toc@\f3pathconf(2)\f1:\0\0\f4pathconf()\f1, \f4fpathconf()\f1@@@get configurable path name variables\f1 .\" toc@\f4fpathconf()\f1:\0\0get configurable path name variables\f1@@@see \f3pathconf(2)\f1 .\" .\" links@pathconf.2 fpathconf.2 .\" .\" $Header: pause.2,v 72.4 94/11/14 15:25:29 ssa Exp $ .TA p .TH pause 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pause \- suspend process until signal .SH SYNOPSIS .C "#include .PP .C "int pause(void);" .SH DESCRIPTION .C pause() suspends the calling process until it receives a signal. The signal must be one that is not currently set to be ignored or blocked (masked) by the calling process. .PP If the signal causes termination of the calling process, .C pause() does not return. .PP If the signal is .I caught by the calling process and control is returned from the signal-catching function (see .IR signal (5)), the calling process resumes execution from the point of suspension; with a return value of \(mi1 from .C pause() and .C errno set to .SM EINTR. .SH WARNING Check all references to .IR signal (5) for appropriateness on systems that support .IR sigvector (2). .C sigvector() can affect the behavior described on this page. .SH SEE ALSO alarm(2), kill(2), sigvector(2), wait(2), signal(5). .SH STANDARDS CONFORMANCE .CR pause() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4pause()\fP \(mi suspend process until signal@@@\f3pause(2)\f1 .\" index@suspend process until signal@@@\f3pause(2)\f1 .\" index@process, suspend until signal@@@\f3pause(2)\f1 .\" index@signal, suspend process until@@@\f3pause(2)\f1 .\" .\" toc@\f3pause(2)\f1:\0\0\f4pause()\fP@@@suspend process until signal .\" .\" fileset_database@pause.2 PROGRAMING-MAN .\" $Header: pipe.2,v 72.6 94/11/14 15:25:30 ssa Exp $ .TA p .TH pipe 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pipe \- create an interprocess channel .SH SYNOPSIS .C "int pipe(int fildes[2]);" .SH DESCRIPTION .C pipe() creates an .SM I/O mechanism called a pipe and returns two file descriptors, .IR fildes [0] and .IR fildes [1]. .IR fildes [0] is opened for reading and .IR fildes [1] is opened for writing. .PP A read-only file descriptor .IR fildes [0] accesses the data written to .IR fildes [1] on a first-in-first-out .SM (FIFO) basis. For details of the .SM I/O behavior of pipes see .IR read (2) and .IR write (2). .PP By default, HP-UX pipes are not STREAMS-based. It is possible to generate the kernel so that all pipes created on a system are STREAMS-based. This can only be done for HP-UX releases 10.0 and later. STREAMS-based FIFOs (created by .C mknod or .CR mkfifo ) are not supported on HP-UX. .PP To generate a kernel that supports STREAMS-based pipes: .TP 3 \(bu STREAMS/UX must be installed. .TP \(bu The module .C pipemod and the driver .C pipedev must be included in the .C /stand/system file. (When STREAMS/UX is installed, .C pipemod and .C pipedev are automatically added to the system file.) .TP \(bu The tunable parameter "streampipes" must be set to 1 in the .C /stand/system file. (This is not automatically done when STREAMS/UX is installed.) .TP \(bu The kernel must be generated and the system rebooted. Once this is done, all pipes created by .C pipe() will be STREAMS-based. .PP For more information, see .IR "STREAMS/UX for the HP 9000 Reference Manual" . .SH EXAMPLES The following example uses .C pipe() to implement the command string .CR "ls | sort" : .nf .IP .C #include .C pid_t pid; .C int pipefd[2]; .IP /* Assumes file descriptor 0 and 1 are open */ .C pipe (pipefd); .IP .ift .ft 4 .ifn .ft 3 .ps +1 if ((pid = fork()) == (pid_t)0) /* check process id of child process */ { close(1); /* close stdout */ dup (pipefd[1]); /* points pipefd at file descriptor */ close (pipefd[0]); execlp ("ls", "ls", (char *)0); /* child process does ls */ } else if (pid > (pid_t)0) { close(0); /* close stdin */ dup (pipefd[0]); /* point the child's standard output to parent's standard input */ close (pipefd[1]); execlp ("sort", "sort", (char *)0); /* parent process does sort */ } .ft .ps .fi .RE .SH RETURN VALUE Upon successful completion, a value of .C 0 is returned. Otherwise, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .C pipe() fails if one or more of the following is true: .TP 15 .SM [EMFILE] .C NFILE\c \(mi1 or more file descriptors are currently open. .TP .SM [ENFILE] The system file table is full. .TP .SM [ENOSPC] The file system lacks sufficient space to create the pipe. .TP .SM [ENOSR] Could not allocate resources for both Stream heads (STREAMS-based pipes only). .SH SEE ALSO sh(1), read(2), write(2), popen(3S), streamio(7). .SH STANDARDS CONFORMANCE .CR pipe() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4pipe()\f1 \(mi create an interprocess channel@@@\f3pipe(2)\f1 .\" index@\f1create an interprocess channel@@@\f3pipe(2)\f1 .\" index@\f1interprocess channel, create an@@@\f3pipe(2)\f1 .\" index@\f1channel, create an interprocess@@@\f3pipe(2)\f1 .\" .\" toc@\f3pipe(2)\f1:\0\0\f4pipe()\f1@@@create an interprocess channel .\" .\" fileset_database@pipe.2 PROGRAMING-MAN .\" $Header: plock.2,v 72.5 94/11/14 15:25:32 ssa Exp $ .TA p .TH plock 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME plock() \- lock process, text, data, stack, or shared library in memory .SH SYNOPSIS .C "#include " .PP .C "int plock(int op);" .SH DESCRIPTION The .CR plock() system call allows the calling process to lock the text segment of the process (text lock), its data segment (data lock), or both its text and data segment (process lock) into memory. Stack segments are also locked when data segments are locked. Shared library text and shared library data segments (shlib lock) can also be locked. Locked segments are immune to all routine swapping. .CR plock() also allows these segments to be unlocked. .PP The effective user ID of the calling process must be a superuser or the user must be a member of a group that has the MLOCK privilege (see .IR getprivgrp (2) and .IR setprivgrp (1M)) .PP .I op must be one of the following: .RS .TP 20 .CR PROCLOCK Lock text and data segments into memory (process lock) .TP .CR TXTLOCK Lock text segment into memory (text lock) .TP .CR DATLOCK Lock data segment into memory (data lock) .TP .CR UNLOCK Remove locks .TP .CR SHLIBLOCK Lock shared library text and shared library data segments (shared library lock) .TP .CR PROCSHLIBLOCK Lock text, data and shared library text and shared library data segments into memory (process and shared library lock) .TP .CR TXTSHLIBLOCK Lock text, shared library text and shared library data segments into memory (text and shared library lock) .TP .CR DATSHLIBLOCK Lock data, shared library text and shared library data segments into memory (data and shared library lock) .RE .SH RETURN VALUE .CR plock() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. The requested operation is not performed. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR plock() fails, .CR errno is set to one of the following values. .RS .TP 15 [EINVAL] .I op is equal to .CR PROCLOCK and a process lock, a text lock, or a data lock already exists on the calling process. .TP [EINVAL] .I op is equal to .CR TXTLOCK and a text lock or process lock already exists on the calling process. .TP [EINVAL] .I op is equal to .CR DATLOCK and a data lock, or process lock already exists on the calling process. .TP [EINVAL] .I op is equal to .CR UNLOCK and no type of lock exists on the calling process. .TP [EINVAL] .I op is equal to .CR SHLIBLOCK and there are no unlocked shared library segments in the calling process. .TP [EINVAL] .I op is equal to .CR PROCSHLIBLOCK and a process lock, a text lock, or a data lock already exists on the calling process. .TP [EINVAL] .I op is equal to .CR TXTSHLIBLOCK and a text lock or process lock already exists on the calling process. .TP [EINVAL] .I op is equal to .CR DATSHLIBLOCK and a data lock, or process lock already exists on the calling process. .TP [EINVAL] .I op is not equal to one of the values specified in DESCRIPTION. .TP [EINVAL] .CR plock() is not allowed in a .RC [ vfork , exec ] window. See .IR vfork (2). .TP [ENOMEM] There is not enough lockable memory in the system to satisfy the locking request. .TP [EPERM] The effective user ID of the calling process is not a superuser and the user does not belong to a group that has the .CR MLOCK privilege. .RE .SH EXAMPLES The following call to .CR plock() locks the calling process in memory: .IP .C "plock(PROCLOCK);" .SH SEE ALSO setprivgrp(1M), exec(2), exit(2), fork(2), getprivgrp(2), vfork(2). .SH STANDARDS CONFORMANCE .CR plock() ": SVID2, SVID3, XPG2" .\" .\" index@\f4plock()\f1 \- lock process, text, data, stack, or shared library in memory@@@\f3plock(2)\f1 .\" index@\f1data, lock in memory@@@\f3plock(2)\f1 .\" index@\f1lock process, text, or data in memory@@@\f3plock(2)\f1 .\" index@\f1memory, lock process, text, data, stack, or shared library in@@@\f3plock(2)\f1 .\" index@\f1process, lock in memory@@@\f3plock(2)\f1 .\" index@\f1shared library, lock in memory@@@\f3plock(2)\f1 .\" index@\f1stack, lock in memory@@@\f3plock(2)\f1 .\" index@\f1text, lock in memory@@@\f3plock(2)\f1 .\" .\" toc@\f3plock(2)\f1:\0\0\f4plock()\f1@@@lock process, text, data, stack, or shared library in memory .\" $Header: poll.2,v 72.5 94/11/30 15:45:04 ssa Exp $ .TA p .TH poll 2 "" "Series 700 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME poll \- monitor \s-1I/O\s0 conditions on multiple file descriptors .SH SYNOPSIS .nf .C #include .PP .C int poll( .PD 0 .IP .C struct pollfd fds[], .C int nfds, .C int timeout .PP .C ); .fi .PD .SH DESCRIPTION .C poll() provides a general mechanism for reporting .SM I/O conditions associated with a set of file descriptors and for waiting until one or more specified conditions becomes true. Specified conditions include the ability to read or write data without blocking, and error conditions. .SS Arguments .RS .TP 15 .I fds Points to an array of .C pollfd structures, one for each file descriptor of interest. .TP .I nfds Specifies the number of .C pollfd structures in the .I fds array. .TP .I timeout Specifies the maximum length of time (in milliseconds) to wait for at least one of the specified conditions to occur. .RE .PP Each .C pollfd structure includes the following members: .RS .TP 20 .C int fd File descriptor .PD 0 .TP .C short events Requested conditions .TP .C short revents Reported conditions .PD .RE .PP The .C fd member of each .C pollfd structure specifies an open file descriptor. The .C poll() function uses the .C events member to determine what conditions to report for this file descriptor. If one or more of these conditions is true, .C poll() sets the associated .C revents member. .PP .C poll() ignores any .C pollfd structure whose .C fd member is negative. If the .C fd member of all .C pollfd structures is negative, .C poll() returns 0 and has no other results. .PP The .C events and .C revents members of the .C pollfd structure are bit masks. The calling process sets the .C events bit mask, and .C poll() sets the .C revents bit masks. These bit masks contain .SM OR\c ed combinations of condition flags. The following condition flags are defined: .RS .TP 20 .C POLLIN Data can be read without blocking. For streams, this flag means that a message that is not high priority is at the front of the stream head read queue. This message can be of zero length. .PD0 .TP .C POLLNORM Synonym for .C POLLIN .TP .C POLLPRI A high priority message is available. For streams, this message can be of zero length. .TP .C POLLOUT Data can be written without blocking. For streams, this flag specifies that normal data (not high priority or priority band > 0) can be written without being blocked by flow control. This flag is not used for high priority data, because it can be written even if the stream is flow controlled. .TP .C POLLERR An error has occurred on the file descriptor. .TP .C POLLHUP The device has been disconnected. For streams, this flag in .C revents is mutually exclusive with .CR POLLOUT , since a stream cannot be written to after a hangup occurs. This flag and .CR POLLIN , .CR POLLPRI , .CR POLLRDNORM , .CR POLLRDBAND , and .C POLLMSG are not mutually exclusive. .TP .C POLLNVAL .C fd is not a valid file descriptor. .TP .C POLLRDNORM A non-priority message is available. For streams, this flag means that a normal message (not high priority or priority band > 0) is at the front of the stream head read queue. This message can be of zero length. .TP .C POLLRDBAND A priority message (priority band > 0) is at the front of the stream head read queue. This message can be read without blocking. The message can be of zero length. .TP .C POLLWRNORM Same as .C POLLOUT .TP .C POLLWRBAND Priority data (priority band > 0) can be written without being blocked by flow control. Only previously written bands are checked. .TP .C POLLMSG A .C M_SIG or .C M_PCSIG message specifying .C SIGPOLL has reached the front of the stream head read queue. .PD .RE .PP The conditions indicated by .C POLLNORM and .C POLLOUT are true if and only if at least one byte of data can be read or written without blocking. The exception is regular files, which always poll true for .C POLLNORM and .CR POLLOUT . Also, streams return .C POLLNORM in .C revents even if the available message is of zero length. .PP The condition flags .CR POLLERR , .CR POLLHUP , and .C POLLNVAL are always set in .C revents if the conditions they indicate are true for the specified file descriptor, whether or not these flags are set in .CR events . .PP For each call to .CR poll() , the set of reportable conditions for each file descriptor consists of those conditions that are always reported, together with any further conditions for which flags are set in .CR events . If any reportable condition is true for any file descriptor, .C poll() returns with flags set in .C revents for each true condition for that file descriptor. .PP If no reportable condition is true for any of the file descriptors, .C poll() waits up to .I timeout milliseconds for a reportable condition to become true. If, in that time interval, a reportable condition becomes true for any of the file descriptors, .C poll() reports the condition in the file descriptor's associated .C revents member and returns. If no reportable condition becomes true, .C poll() returns without setting any .C revents bit masks. .PP If the .I timeout parameter is a value of \(mi1, .C poll() does not return until at least one specified event has occurred. If the value of the .I timeout parameter is 0, .C poll() does not wait for an event to occur but returns immediately, even if no specified event has occurred. The behavior of .C poll() is not affected by whether the .C O_NONBLOCK flag is set on any of the specified file descriptors. .SH RETURN VALUES Upon successful completion, .C poll() returns a nonnegative value. If the call returns 0, .C poll() has timed out and has not set any of the .C revents bit masks. A positive value indicates the number of file descriptors for which .C poll() has set the .C revents bit mask. If .C poll() fails, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C poll() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EAGAIN] Allocation of internal data structures failed. A later call to .C poll() may complete successfully. .TP .SM [EINTR] A signal was delivered before any of the selected for conditions occurred or before the time limit expired. .TP .SM [EINVAL] .I timeout is a negative number other than \(mi1, or .I nfds is negative. .TP .SM [EFAULT] The .I fds parameter in conjunction with the .I nfds parameter addresses a location outside of the allocated address space of the process. Reliable detection of this error is implementation-dependent. .SH EXAMPLES Wait for input on file descriptor 0: .nf .IP .C #include .C struct pollfd fds; .IP .C fds.fd = 0; .C fds.events = POLLNORM; .C poll(&fds, 1, -1); .fi .PP Wait for input on .C ifd1 and .CR ifd2 , output on .CR ofd , giving up after 10 seconds: .RS .PP .nf .ift .ft 4 #include struct pollfd fds[3]; int ifd1, ifd2, ofd, count; .ift .sp .5v .ifn .sp fds[0].fd = ifd1; fds[0].events = POLLNORM; fds[1].fd = ifd2; fds[1].events = POLLNORM; fds[2].fd = ofd; fds[2].events = POLLOUT; count = poll(fds, 3, 10000); if (count == -1) { perror("poll failed"); exit(1); } if (count==0) printf("No data for reading or writing\en"); if (fds[0].revents & POLLNORM) printf("There is data for reading fd %d\en", fds[0].fd); if (fds[1].revents & POLLNORM) printf("There is data for reading fd %d\en", fds[1].fd); if (fds[2].revents & POLLOUT) printf("There is room to write on fd %d\en", fds[2].fd); .ift .ft .fi .RE .PP Check for input or output on file descriptor 5 without waiting: .RS .PP .nf .ift .ft 4 #include struct pollfd fds; .ift .sp .5v .ifn .sp fds.fd = 5; fds.events = POLLNORM|POLLOUT; poll(&fds, 1, 0); if (fds.revents & POLLNORM) printf("There is data available on fd %d\en", fds.fd); if (fds.revents & POLLOUT) printf("There is room to write on fd %d\en", fds.fd); .ift .ft .RE .fi .PP Wait 3.5 seconds: .nf .IP .C #include .C #include .IP .C "poll((struct pollfd *) NULL, 0, 3500);" .fi .PP Wait for a high priority, priority, or normal message on streams file descriptor 0: .nf .IP .C #include .C struct pollfd fds; .IP .C fds.fd = 0; .C fds.events = POLLIN|POLLPRI; .C poll(&fds, 1, -1); .fi .SH WARNINGS In some countries, electioneering is illegal within one hundred feet of a polling place. .SH SEE ALSO .PP read(2), write(2), select(2), getmsg(2), putmsg(2), streamio(7). .SH STANDARDS CONFORMANCE .CR poll() ": AES, SVID2, SVID3" .\" .\" toc \f3poll(2)\f1:\0\0\f4poll\f1 \(mi monitor \s-1I/O\s0 conditions on multiple file descriptors .\" .\" index@\f4poll\f1 \(mi monitor \s-1I/O\s0 conditions on multiple file descriptors@@@\f3poll(2)\f1 .\" index@monitor \s-1I/O\s0 conditions on multiple file descriptors@@@\f3poll(2)\f1 .\" index@monitor \s-1I/O\s0 conditions on multiple file descriptors@@@\f3poll(2)\f1 .\" .\" fileset_database@poll.2 PROGRAMING-MAN .\" $Header: prealloc.2,v 78.1 96/02/12 14:10:59 ssa Exp $ .TA p .TH prealloc 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME prealloc \- preallocate fast disk storage .SH SYNOPSIS .C "#include .PP .C "int prealloc(int fildes, off_t size);" .SH DESCRIPTION .C prealloc() is used to preallocate space on a disk for faster storage operations. .PP .I fildes is a file descriptor obtained from a .CR creat() , .CR open() , .CR dup() , or .C fcntl() system call for an ordinary file of zero length. It must be opened writable, because it will be written to by .CR prealloc() . .I size is the size in bytes to be preallocated for the file specified by .IR fildes . At least .I size bytes will be allocated. Space is allocated in an implementation-dependent fashion for fast sequential reads and writes. The EOF in an extended file is left at the end of the preallocated area. The current file pointer is left at zero. The file is zero-filled. .PP Using .C prealloc() on a file does .I not give the file an attribute that is inherited when copying or restoring the file using a program such as .C cp or .C tar (see .IR cp (1) and .IR tar (1)). It simply ensures that disk space has been preallocated for .I size bytes in a manner suited for sequential access. The file can be extended beyond these limits by .C write() operations past the original end of file. However, this space will not necessarily be allocated using any special strategy. .SH RETURN VALUE Upon successful completion, .C prealloc() returns 0; otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C prealloc() fails and no disk space is allocated if any of the following conditions are encountered: .RS .TP 15 [EBADF] .I fildes is not a valid open file descriptor opened for writing. .TP [EDQUOT] User's disk quota block limit has been reached for this file system. .TP [EFBIG] .I size exceeds the maximum file size or the process's file size limit. See .IR ulimit (2). .TP [ENOSPC] Not enough space is left on the device to allocate the requested amount; no space was allocated. .TP 17 [ENOTEMPTY] .I fildes not associated with an ordinary file of zero length. .SH EXAMPLES Assuming a process has opened a file for writing, the following call to .C prealloc() preallocates at least 50\|000 bytes on disk for the file represented by file descriptor .IR outfd : .IP .C prealloc (outfd, 50000); .SH WARNINGS Allocation of the file space is highly dependent on current disk usage. A successful return does not tell you how fragmented the file actually might be if the disk is nearing its capacity. .SH AUTHOR .C prealloc() was developed by HP. .SH SEE ALSO prealloc(1), creat(2), dup(2), fcntl(2), open(2), prealloc64(2), read(2), ulimit(2), write(2). .\" .\" index@\f4prealloc()\f1 \- preallocate fast disk storage@@@\f3prealloc(2)\f1 .\" index@\f1preallocate fast disk storage@@@\f3prealloc(2)\f1 .\" index@\f1fast disk storage, preallocate@@@\f3prealloc(2)\f1 .\" index@\f1disk storage, preallocate fast@@@\f3prealloc(2)\f1 .\" index@\f1storage, preallocate fast disk@@@\f3prealloc(2)\f1 .\" .\" toc@\f3prealloc(2)\f1:\0\0\f4prealloc()\f1@@@preallocate fast disk storage .\" .\" $Header: creat64.2,v 78.2 96/02/12 13:37:12 ssa Exp $ .TA c .TH creat64 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME creat64(\|), fstat64(\|), getrlimit64(\|), lockf64(\|), lseek64(\|), lstat64(\|), mmap64(\|), open64(\|), prealloc64(\|), setrlimit64(\|), stat64(\|), statvfs64(\|), truncate64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0creat64(const\0char\0*path,\0mode_t\0mode);" .PP .C "#include " .PP .C "int\0fstat64(int\0fildes,\0struct\0stat64\0*buf);" .PP .C "include\0" .PP .C "int\0getrlimit64(int resource,\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0lock64(int\0*fildes,\0int\0function,\0off64_t\0size);" .PP .C "#include " .PP .C "off64_t\0lseek64(int\0*fildes,\0off64_t\0offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0lstat64(const\0char\0*,\0struct\0stat64\0*);" .PP .C "#include " .PP .C "void\0mmap64(void\0addr,\0size_t\0len,\0int\0prot,\0int\0flags,\0int\0fildes,\0off64_t\0off);" .PP .C "#include " .PP .C "int\0open64(const\0char\0*path,\0int\0oflag,...);" .PP .C "#include " .PP .C "int\0prealloc64(int\0fildes,\0off64_t\0size);" .PP .C "include\0" .PP .C "int\0setrlimit64(int\0resource,\0const\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0stat64(const\0char\0*path,\0struct\0stat64\0*buf);" .PP .C "#include " .PP .C "int\0statvfs64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "int\0truncate64(const\0char\0*path,\0off64_t\0length);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 18 .C creat64() The .C creat64() function is identical to .C creat() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. .C creat64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR creat() . .TP .C fstat64() The .C fstat64() function is identical to .C fstat() except that .C fstat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C getrlimit64 The .C getrlimit64() function is identical to .C getrlimit() except that .C getrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .CR "struct rlimit" . All other functional behaviors, returns, and errors are identical. .TP .C lock64() The .C lock64() function is identical to .C lockf() except that .C lockf64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C lseek64() The .C lseek64() function is identical to .C lseek() except that .C lseek64() accepts an .CR off64_t type as the desired offset and has a return value of .CR off64_t. All other functional behaviors, returns, and errors are identical. .TP .C lstat64() The .C lstat64() function is identical to .C lstat() except that .C lstat64() returns file status in a .C struct stat64 instead of .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C mmap64() The .C mmap64() function is identical to .C mmap() except that .C mmap64() accepts the file offset as an .CR off64_t . .TP .C open64() The .C open64() function is identical to .C open() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. The .C open64() function is equivalent to .C open() function (in 32-bit compile environment) with .C O_LARGEFILE flag set. .C open64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR open() . .TP .C prealloc64() The .C prealloc64() function is identical to .C prealloc() except that .C prealloc64() accepts the file offset as an .CR off64_t . All other functional behaviors, returns, and errors are identical to .CR prealloc() . .TP .C setrlimit64 The .C setrlimit64() function is identical to .C setrlimit() except that .C setrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .C struct rlimit. All other functional behaviors, returns, and errors are identical. .TP .C stat64() The .C stat64() function is identical to .C stat() except that .C stat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . .TP .C statvfs64() Refer to .CR fstatvfs64() . .TP .C truncate64() The .C truncate64() function is identical to .C truncate() except that .C truncate64() accepts the length parameter as an .C off64_t instead of .CR off_t . All other functional behaviors, returns, and errors are identical to .CR truncate() . .\" .\" toc@\f4creat64(2)\f1:\0\0\f4fstat64\f1, \f4getrlimit64\f1, \f4lockf64\f1, \f4lseek64\f1, \f4lstat64\f1, \f4mmap64\f1, \f4open64\f1, \n\f4prealloc64\f1, \f4setrlimit64\f1, \f4stat64\f1, \f4statvfs64\f1, \f4truncate64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4creat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4fstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4getrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lockf64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lseek64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4mmap64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4open64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4prealloc64()\f1 \- file sysmmaptem API to support large files@@@\f3creat64(2)\f1 .\" index@\f4setrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4stat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4statvfs64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4truncate64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3creat64(2)\f1 .\" .\" links@creat64.2 fstat64.2 .\" links@creat64.2 getrlimit64.2 .\" links@creat64.2 lockf64.2 .\" links@creat64.2 lseek64.2 .\" links@creat64.2 lstat64.2 .\" links@creat64.2 mmap64.2 .\" links@creat64.2 open64.2 .\" links@creat64.2 prealloc64.2 .\" links@creat64.2 setrlimit64.2 .\" links@creat64.2 stat64.2 .\" links@creat64.2 statvfs64.2 .\" links@creat64.2 truncate64.2 .\" .\" $Header: rtsched.2,v 72.6 94/11/14 15:26:03 ssa Exp $ .TA r .TH rtsched 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtsched: sched_get_priority_max(), sched_get_priority_min(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setparam(), sched_setscheduler(), sched_yield(), PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX() \- real-time scheduling operations .SH SYNOPSIS .nf .C "#include " .PP .C "int sched_setparam(" .C " pid_t pid," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getparam(" .C " pid_t pid," .C " struct sched_param *param" .C ");" .PP .C "int sched_setscheduler(" .C " pid_t pid," .C " int policy," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getscheduler(" .C " pid_t pid" .C ");" .PP .C "int sched_yield();" .PP .C "int sched_get_priority_max(" .C " int policy" .C ");" .PP .C "int sched_get_priority_min(" .C " int policy" .C ");" .PP .C "int sched_rr_get_interval(" .C " pid_t pid," .C " struct timespec *interval" .C ");" .PP .C "int PRI_POSIX_TO_HPUX(" .C " const struct sched_param *param" .C ");" .PP .C "int PRI_HPUX_TO_POSIX(" .C " int pri," .C " struct sched_param *param" .C ");" .fi .SH DESCRIPTION .SS Summary .TP 35 .PD 0 .CR sched_get_priority_max() Get maximum scheduling policy .TP .CR sched_get_priority_min() Get minimum scheduling policy .TP .CR sched_getparam() Get scheduling parameters of process .TP .CR sched_getscheduler() Get scheduling policy of process .TP .CR sched_rr_get_interval() Update execution time limit for a process .TP .CR sched_setparam() Set scheduling parameters of process .TP .CR sched_setscheduler() Set scheduling policy and parameters of process .TP .CR sched_yield() Requeue current process in process list .TP .CR PRI_HPUX_TO_POSIX() Convert HP-UX priority to POSIX .TP .CR PRI_POSIX_TO_HPUX() Convert POSIX priority to HP-UX .PD .SS sched_setparam() The .CR sched_setparam() function sets the scheduling parameters of the process specified by .I pid to the values specified by the .I sched_param structure pointed to by .IR param . The value of the .I sched_priority member in the .I param structure is any integer within the inclusive priority range for the current scheduling policy of the process specified by .IR pid . .PP Higher numerical values for the priority represent higher (stronger) priorities. Note that this is different from the .CR SCHED_HPUX , .CR SCHED_TIMESHARE , and .CR SCHED_RTPRIO scheduling policies, where higher numerical values represent lower (weaker) priorities. See the .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() functions, and .CR SCHED_RTPRIO and .CR SCHED_OTHER in "Scheduling Policies" below. .PP If a process described by .I pid exists and if the calling process has permission, the scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are set for the calling process. .PP Only a superuser may change the scheduling parameters of another process. .PP The calling process must have the appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setparam() . .PP The target process, whether it is running or not running, will resume execution after all other runnable processes of equal or greater priority have been scheduled to run. .PP If the priority of the process specified by the .I pid argument is set higher than that of the lowest priority running process, and if the specified process is ready to run, the process specified by the .I pid argument will preempt a lowest-priority running process. Similarly, if the process calling .CR sched_setparam() sets its own priority lower than that of one or more other nonempty process lists, then the process that is the head of the highest priority list will also preempt the calling process. Thus, in either case, the originating process may not receive notification of the completion of the requested priority change until the higher priority process has executed. .SS sched_getparam() The .CR sched_getparam() function returns the scheduling parameters of a process specified by .I pid in the .I sched_param structure pointed to by .IR param . .PP If a process described by .I pid exists, the scheduling parameters are returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are returned for the calling process. .SS sched_setscheduler() The .CR sched_setscheduler() function sets the scheduling policy and scheduling parameters of the process specified by .I pid to .I policy and the parameters specified in the .I sched_param structure pointed to by .IR param , respectively. The value of the .I sched_priority member in the .I param structure can be any integer within the inclusive priority range for the scheduling policy specified by .IR policy . .PP The possible values for the .I policy parameter are defined in the header file .CR , and mentioned below. .PP If a process described by .I pid exists, the scheduling policy and scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy and scheduling parameters are set for the calling process. .PP Appropriate privileges are required to change the scheduling parameters of another process. .PP The calling process must have appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setscheduler() . .PP The .CR sched_setscheduler() function is considered successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by .I pid to the values specified by .I policy and the structure .IR param , respectively. .PP .SS sched_getscheduler() The .CR sched_getscheduler() function returns the scheduling policy of the process specified by .IR pid . .PP The values that can be returned by .CR sched_getscheduler() are defined in the header file .CR (see .CR sched_setscheduler() ). .PP If a process described by .I pid exists, the scheduling policy is returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy is returned for the calling process. .SS sched_yield() The .CR sched_yield() function forces the running process to relinquish the processor until it again becomes the head of its process list. It takes no arguments. .SS sched_get_priority_max() .SS sched_get_priority_min() The .CR sched_get_priority_max() and .CR sched_get_priority_min() functions return the appropriate maximum or minimum, respectively, for the scheduling policy specified by .IR policy . .PP The value of .I policy must be one of the scheduling policy values defined in .CR . .SS sched_rr_get_interval() The .CR sched_rr_get_interval() function updates the .I timespec structure referenced by the .I interval argument to contain the current execution time limit (that is, time quantum) for the process indicated by .I pid under the .CR SCHED_RR policy, at which a scheduling decision will be made when another process at the same priority is ready to execute. If .I pid is zero, the current execution time limit for the calling process is returned. .SS PRI_HPUX_TO_POSIX() .SS PRI_POSIX_TO_HPUX() These two functions serve to map (translate) the range of HP-UX priorities into the POSIX.4 model. These translations are necessary because the POSIX.4 standard chose .I larger numbers to represent stronger priorities and the existing HP-UX behavior, which must be maintained for backward compatibility, uses .I smaller numbers for stronger priorities. .PP The .CR PRI_HPUX_TO_POSIX() function returns, in the .I sched_param structure pointed to by .IR param , the POSIX.4 scheduling priority corresponding to the HP-UX priority passed in the argument .IR pri . The argument .I pri must contain a valid HP-UX priority. .PP The .CR PRI_POSIX_TO_HPUX() function returns an HP-UX process priority corresponding to the .I sched_priority member in the .I sched_param structure specified. The value of the .I sched_priority member can be any integer within the inclusive priority range for the .CR SCHED_HPUX scheduling policy. The HP-UX priority returned is comparable to the values returned by .CR getpriority() (see .IR getpriority (2)). .SS Scheduling Policies The scheduling policies described are defined in terms of a conceptual model, which contains a set of process lists. There is, conceptually, one process list for each priority. Any runnable process may be in any process list. Multiple scheduling policies are provided. Each nonempty list is ordered, and contains a head as one end of its order, and a tail as the other. The purpose of a scheduling policy is to define the allowable operations on this set of lists (for example, moving processes between and within lists). .PP Each process will be controlled by an associated scheduling policy and priority. These parameters may be specified by explicit application execution of the .CR sched_setscheduler() or .CR sched_setparam() functions. .PP Associated with each policy is a priority range. The priority ranges for each policy can (but need not) overlap the priority ranges of other policies. .PP When a process is to be selected to run, the process that is at the head of the highest priority nonempty process list is chosen. It is then removed from its process list. .PP The following scheduling policies are defined: .RS .TP 15 .CR SCHED_FIFO First in-first out (FIFO) scheduling policy. .IP Processes scheduled under this policy are chosen from a process list that is ordered by the time its processes have been in the list without being executed. Generally, the head of the list is the process that has been in the list the longest time, and the tail is the process that has been in the list the shortest time. .IP Under the .CR SCHED_FIFO policy, the modification of the definitional process lists is as follows: .RS .RS .TP 3 \(bu When a running process becomes a preempted process, it becomes the head of the process list for its priority. .TP \(bu When a blocked process becomes a runnable process, it becomes the tail of the process list for its priority. .TP \(bu When a running process calls the .CR sched_setscheduler() function, the process specified in the function call is modified to the policy and priority specified by the .I param argument. If the process whose policy and priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process calls the .CR sched_setparam() function, the priority of the process specified in the function call is modified to the priority specified by the .I param argument. If the process whose priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process issues the .CR sched_yield() function, the process becomes the tail of the process list for its priority. .TP \(bu At no other time is the position of a process with this scheduling policy within the process lists affected. .RE .RE .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_FIFO is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR Round-robin scheduling policy, with a per-system time slice (time quantum). .IP This policy is identical to the .CR SCHED_FIFO policy with the additional condition that when the implementation detects that a running process has been executing as a running process for a time period of length returned by the function .CR sched_rr_get_interval() , or longer, the process becomes the tail of its process list, and the head of that process list is removed and made a running process. .IP The effect of this policy is to ensure that if there are multiple .CR SCHED_RR processes at the same priority, one of them will not monopolize the processor. An application should not rely only on the use of .CR SCHED_RR to ensure application progress among multiple processes if the application includes processes using the .CR SCHED_FIFO policy at the same or higher priority levels, or .CR SCHED_RR processes at a higher priority level. .IP A process under this policy that is preempted and subsequently resumes execution as a running process completes the unexpired portion of its round-robin interval time period. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR2 Round-robin scheduling policy, with a per-priority time slice (time quantum). .IP This policy is identical to the .CR SCHED_RR policy, except that the round-robin time slice interval returned by .CR sched_rr_get_interval() depends upon the priority of the specified process. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RTPRIO Real-time scheduling policy with nondecaying priorities (like .CR SCHED_FIFO and .CR SCHED_RR ) with a priority range between the POSIX real-time policies and the HP-UX policies, described below (see .IR rtprio(2)). .IP For processes executing under this policy, the implementation must use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RTPRIO is provided as the parameter. Note that, for the .CR SCHED_RTPRIO scheduling policy, .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_RTPRIO is weaker than the weakest priority in the priority ranges for any of the POSIX policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .TP .CR SCHED_OTHER " (" SCHED_HPUX ", " SCHED_TIMESHARE ) Another scheduling policy. .IP The .CR SCHED_OTHER policy, also known as .CR SCHED_HPUX and .CR SCHED_TIMESHARE , provides a way for applications to indicate, in a portable way, that they no longer need a real-time scheduling policy. .IP For processes executing under this policy, the implementation can use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_OTHER is provided as the parameter. Note that for the .CR SCHED_OTHER scheduling policy, like .CR SCHED_RTPRIO , .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_OTHER is weaker than the weakest priority in the priority ranges for any of the other policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .RE .SH RETURN VALUE The functions return the following values: .SS sched_getparam() .SS sched_rr_get_interval() .SS sched_setparam() .SS sched_yield() .SS PRI_HPUX_TO_POSIX() .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_setscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the former scheduling policy of the specified process. .TP .CR -1 Failure. The policy and scheduling parameters remain unchanged. .CR errno is set to indicate the error. .PD .RE .SS sched_getscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the scheduling policy of the specified process. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the maximum or minimum value, respectively. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS PRI_POSIX_TO_HPUX() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the the HP-UX priority corresponding to the .I sched_priority member in the .I param structure. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If the functions fail, .CR errno is set to one of the following values. .SS sched_setparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] One or more of the requested scheduling parameters is outside the range defined for the scheduling policy of the specified .IR pid . .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling parameters for the specified process, or does not have the appropriate privilege to invoke .CR sched_setparam() . .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_setscheduler() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] The value of the .I policy parameter is invalid, or one or more of the parameters contained in .I param is outside the valid range for the specified scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling policy of the specified process. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getscheduler() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_yield() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP 15 [EINVAL] The value of the .I policy parameter does not represent a defined scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .RE .SS sched_rr_get_interval() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS PRI_POSIX_TO_HPUX() .RS .TP 15 [EINVAL] The priority specified in the .I sched_priority member of the .I param argument is outside the range defined for the .CR SCHED_HPUX scheduling policy. .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS PRI_HPUX_TO_POSIX() .RS .TP 15 [EINVAL] The priority specified in the .I pri argument is not a valid HP-UX priority. .TP [ENOSYS] The function is not supported by this implementation. .RE .SH EXAMPLES Change the calling process to use the strongest .CR FIFO priority: .IP .nf .C "#include " .IP .C "struct sched_param param;" .C "int maxpri;" .IP .C "maxpri = sched_get_priority_max(SCHED_FIFO);" .C "if (maxpri == -1) {" .C " perror(""sched_get_priority_max() failed"");" .C " exit(1);" .C "}" .C "param.sched_priority = maxpri;" .C "if (sched_setscheduler(getpid(), SCHED_FIFO, ¶m) == -1) {" .C " perror(""sched_setscheduler() failed"");" .C " exit(1);" .C "}" .fi .SH AUTHOR The .CI sched_ * () functions were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .PP .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() were developed by HP. .SH SEE ALSO rtsched(1), rtprio(2). .SH STANDARDS CONFORMANCE .CR sched_get_priority_max() ": POSIX.4" .PP .CR sched_get_priority_min() ": POSIX.4" .PP .CR sched_getparam() ": POSIX.4" .PP .CR sched_getscheduler() ": POSIX.4" .PP .CR sched_rr_getinterval() ": POSIX.4" .PP .CR sched_setparam() ": POSIX.4" .PP .CR sched_setscheduler() ": POSIX.4" .PP .CR sched_yield() ": POSIX.4" .\" .\" index entries: .\" index@\f1rtsched\f1 \- real time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f4PRI_HPUX_TO_POSIX()\f1 \- return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f4PRI_POSIX_TO_HPUX()\f1 \- return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_max()\f1 \- return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_min()\f1 \- return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_getparam()\f1 \- return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_getscheduler()\f1 \- return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_rr_get_interval()\f1 \- update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4sched_setparam()\f1 \- set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_setscheduler()\f1 \- set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_yield()\f1 \- force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1operations, real-time scheduling@@@\f3rtsched(2)\f1 .\" index@\f1real-time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f1return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1scheduling operations, real-time@@@\f3rtsched(2)\f1 .\" index@\f1scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" links entries: .\" links@rtsched.2 PRI_HPUX_TO.2 .\" links@rtsched.2 PRI_POSIX_T.2 .\" links@rtsched.2 pri_hpux_to.2 .\" links@rtsched.2 pri_posix_t.2 .\" links@rtsched.2 sched_get_p.2 .\" links@rtsched.2 sched_getpa.2 .\" links@rtsched.2 sched_getsc.2 .\" links@rtsched.2 sched_rr_ge.2 .\" links@rtsched.2 sched_setpa.2 .\" links@rtsched.2 sched_setsc.2 .\" links@rtsched.2 sched_yield.2 .\" toc entries: .\" toc@\f3rtsched(2)\f1:\0\0\f4sched_get_priority_max()\f1, \f4sched_get_priority_min()\f1,\n\f4sched_getparam()\f1, \f4sched_getscheduler()\f1, \f4sched_rr_get_interval()\f1,\n\f4sched_setparam()\f1, \f4sched_setscheduler()\f1, \f4sched_yield()\f1,\n\f4PRI_HPUX_TO_POSIX()\f1, \f4PRI_POSIX_TO_HPUX()\f1@@@real-time scheduling operations .\" toc@\f4PRI_HPUX_TO_POSIX()\f1:\0\0return POSIX.4 process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4PRI_POSIX_TO_HPUX()\f1:\0\0return HP-UX process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_max()\f1:\0\0return maximum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_min()\f1:\0\0return minimum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getparam()\f1:\0\0return scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getscheduler()\f1:\0\0return scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_rr_get_interval()\f1:\0\0update execution time limit@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setparam()\f1:\0\0set scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setscheduler()\f1:\0\0set scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_yield()\f1:\0\0force process to relinquish processor@@@\f1see \f3rtsched(2)\f1 .\" $Header: rtsched.2,v 72.6 94/11/14 15:26:03 ssa Exp $ .TA r .TH rtsched 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtsched: sched_get_priority_max(), sched_get_priority_min(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setparam(), sched_setscheduler(), sched_yield(), PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX() \- real-time scheduling operations .SH SYNOPSIS .nf .C "#include " .PP .C "int sched_setparam(" .C " pid_t pid," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getparam(" .C " pid_t pid," .C " struct sched_param *param" .C ");" .PP .C "int sched_setscheduler(" .C " pid_t pid," .C " int policy," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getscheduler(" .C " pid_t pid" .C ");" .PP .C "int sched_yield();" .PP .C "int sched_get_priority_max(" .C " int policy" .C ");" .PP .C "int sched_get_priority_min(" .C " int policy" .C ");" .PP .C "int sched_rr_get_interval(" .C " pid_t pid," .C " struct timespec *interval" .C ");" .PP .C "int PRI_POSIX_TO_HPUX(" .C " const struct sched_param *param" .C ");" .PP .C "int PRI_HPUX_TO_POSIX(" .C " int pri," .C " struct sched_param *param" .C ");" .fi .SH DESCRIPTION .SS Summary .TP 35 .PD 0 .CR sched_get_priority_max() Get maximum scheduling policy .TP .CR sched_get_priority_min() Get minimum scheduling policy .TP .CR sched_getparam() Get scheduling parameters of process .TP .CR sched_getscheduler() Get scheduling policy of process .TP .CR sched_rr_get_interval() Update execution time limit for a process .TP .CR sched_setparam() Set scheduling parameters of process .TP .CR sched_setscheduler() Set scheduling policy and parameters of process .TP .CR sched_yield() Requeue current process in process list .TP .CR PRI_HPUX_TO_POSIX() Convert HP-UX priority to POSIX .TP .CR PRI_POSIX_TO_HPUX() Convert POSIX priority to HP-UX .PD .SS sched_setparam() The .CR sched_setparam() function sets the scheduling parameters of the process specified by .I pid to the values specified by the .I sched_param structure pointed to by .IR param . The value of the .I sched_priority member in the .I param structure is any integer within the inclusive priority range for the current scheduling policy of the process specified by .IR pid . .PP Higher numerical values for the priority represent higher (stronger) priorities. Note that this is different from the .CR SCHED_HPUX , .CR SCHED_TIMESHARE , and .CR SCHED_RTPRIO scheduling policies, where higher numerical values represent lower (weaker) priorities. See the .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() functions, and .CR SCHED_RTPRIO and .CR SCHED_OTHER in "Scheduling Policies" below. .PP If a process described by .I pid exists and if the calling process has permission, the scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are set for the calling process. .PP Only a superuser may change the scheduling parameters of another process. .PP The calling process must have the appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setparam() . .PP The target process, whether it is running or not running, will resume execution after all other runnable processes of equal or greater priority have been scheduled to run. .PP If the priority of the process specified by the .I pid argument is set higher than that of the lowest priority running process, and if the specified process is ready to run, the process specified by the .I pid argument will preempt a lowest-priority running process. Similarly, if the process calling .CR sched_setparam() sets its own priority lower than that of one or more other nonempty process lists, then the process that is the head of the highest priority list will also preempt the calling process. Thus, in either case, the originating process may not receive notification of the completion of the requested priority change until the higher priority process has executed. .SS sched_getparam() The .CR sched_getparam() function returns the scheduling parameters of a process specified by .I pid in the .I sched_param structure pointed to by .IR param . .PP If a process described by .I pid exists, the scheduling parameters are returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are returned for the calling process. .SS sched_setscheduler() The .CR sched_setscheduler() function sets the scheduling policy and scheduling parameters of the process specified by .I pid to .I policy and the parameters specified in the .I sched_param structure pointed to by .IR param , respectively. The value of the .I sched_priority member in the .I param structure can be any integer within the inclusive priority range for the scheduling policy specified by .IR policy . .PP The possible values for the .I policy parameter are defined in the header file .CR , and mentioned below. .PP If a process described by .I pid exists, the scheduling policy and scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy and scheduling parameters are set for the calling process. .PP Appropriate privileges are required to change the scheduling parameters of another process. .PP The calling process must have appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setscheduler() . .PP The .CR sched_setscheduler() function is considered successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by .I pid to the values specified by .I policy and the structure .IR param , respectively. .PP .SS sched_getscheduler() The .CR sched_getscheduler() function returns the scheduling policy of the process specified by .IR pid . .PP The values that can be returned by .CR sched_getscheduler() are defined in the header file .CR (see .CR sched_setscheduler() ). .PP If a process described by .I pid exists, the scheduling policy is returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy is returned for the calling process. .SS sched_yield() The .CR sched_yield() function forces the running process to relinquish the processor until it again becomes the head of its process list. It takes no arguments. .SS sched_get_priority_max() .SS sched_get_priority_min() The .CR sched_get_priority_max() and .CR sched_get_priority_min() functions return the appropriate maximum or minimum, respectively, for the scheduling policy specified by .IR policy . .PP The value of .I policy must be one of the scheduling policy values defined in .CR . .SS sched_rr_get_interval() The .CR sched_rr_get_interval() function updates the .I timespec structure referenced by the .I interval argument to contain the current execution time limit (that is, time quantum) for the process indicated by .I pid under the .CR SCHED_RR policy, at which a scheduling decision will be made when another process at the same priority is ready to execute. If .I pid is zero, the current execution time limit for the calling process is returned. .SS PRI_HPUX_TO_POSIX() .SS PRI_POSIX_TO_HPUX() These two functions serve to map (translate) the range of HP-UX priorities into the POSIX.4 model. These translations are necessary because the POSIX.4 standard chose .I larger numbers to represent stronger priorities and the existing HP-UX behavior, which must be maintained for backward compatibility, uses .I smaller numbers for stronger priorities. .PP The .CR PRI_HPUX_TO_POSIX() function returns, in the .I sched_param structure pointed to by .IR param , the POSIX.4 scheduling priority corresponding to the HP-UX priority passed in the argument .IR pri . The argument .I pri must contain a valid HP-UX priority. .PP The .CR PRI_POSIX_TO_HPUX() function returns an HP-UX process priority corresponding to the .I sched_priority member in the .I sched_param structure specified. The value of the .I sched_priority member can be any integer within the inclusive priority range for the .CR SCHED_HPUX scheduling policy. The HP-UX priority returned is comparable to the values returned by .CR getpriority() (see .IR getpriority (2)). .SS Scheduling Policies The scheduling policies described are defined in terms of a conceptual model, which contains a set of process lists. There is, conceptually, one process list for each priority. Any runnable process may be in any process list. Multiple scheduling policies are provided. Each nonempty list is ordered, and contains a head as one end of its order, and a tail as the other. The purpose of a scheduling policy is to define the allowable operations on this set of lists (for example, moving processes between and within lists). .PP Each process will be controlled by an associated scheduling policy and priority. These parameters may be specified by explicit application execution of the .CR sched_setscheduler() or .CR sched_setparam() functions. .PP Associated with each policy is a priority range. The priority ranges for each policy can (but need not) overlap the priority ranges of other policies. .PP When a process is to be selected to run, the process that is at the head of the highest priority nonempty process list is chosen. It is then removed from its process list. .PP The following scheduling policies are defined: .RS .TP 15 .CR SCHED_FIFO First in-first out (FIFO) scheduling policy. .IP Processes scheduled under this policy are chosen from a process list that is ordered by the time its processes have been in the list without being executed. Generally, the head of the list is the process that has been in the list the longest time, and the tail is the process that has been in the list the shortest time. .IP Under the .CR SCHED_FIFO policy, the modification of the definitional process lists is as follows: .RS .RS .TP 3 \(bu When a running process becomes a preempted process, it becomes the head of the process list for its priority. .TP \(bu When a blocked process becomes a runnable process, it becomes the tail of the process list for its priority. .TP \(bu When a running process calls the .CR sched_setscheduler() function, the process specified in the function call is modified to the policy and priority specified by the .I param argument. If the process whose policy and priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process calls the .CR sched_setparam() function, the priority of the process specified in the function call is modified to the priority specified by the .I param argument. If the process whose priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process issues the .CR sched_yield() function, the process becomes the tail of the process list for its priority. .TP \(bu At no other time is the position of a process with this scheduling policy within the process lists affected. .RE .RE .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_FIFO is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR Round-robin scheduling policy, with a per-system time slice (time quantum). .IP This policy is identical to the .CR SCHED_FIFO policy with the additional condition that when the implementation detects that a running process has been executing as a running process for a time period of length returned by the function .CR sched_rr_get_interval() , or longer, the process becomes the tail of its process list, and the head of that process list is removed and made a running process. .IP The effect of this policy is to ensure that if there are multiple .CR SCHED_RR processes at the same priority, one of them will not monopolize the processor. An application should not rely only on the use of .CR SCHED_RR to ensure application progress among multiple processes if the application includes processes using the .CR SCHED_FIFO policy at the same or higher priority levels, or .CR SCHED_RR processes at a higher priority level. .IP A process under this policy that is preempted and subsequently resumes execution as a running process completes the unexpired portion of its round-robin interval time period. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR2 Round-robin scheduling policy, with a per-priority time slice (time quantum). .IP This policy is identical to the .CR SCHED_RR policy, except that the round-robin time slice interval returned by .CR sched_rr_get_interval() depends upon the priority of the specified process. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RTPRIO Real-time scheduling policy with nondecaying priorities (like .CR SCHED_FIFO and .CR SCHED_RR ) with a priority range between the POSIX real-time policies and the HP-UX policies, described below (see .IR rtprio(2)). .IP For processes executing under this policy, the implementation must use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RTPRIO is provided as the parameter. Note that, for the .CR SCHED_RTPRIO scheduling policy, .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_RTPRIO is weaker than the weakest priority in the priority ranges for any of the POSIX policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .TP .CR SCHED_OTHER " (" SCHED_HPUX ", " SCHED_TIMESHARE ) Another scheduling policy. .IP The .CR SCHED_OTHER policy, also known as .CR SCHED_HPUX and .CR SCHED_TIMESHARE , provides a way for applications to indicate, in a portable way, that they no longer need a real-time scheduling policy. .IP For processes executing under this policy, the implementation can use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_OTHER is provided as the parameter. Note that for the .CR SCHED_OTHER scheduling policy, like .CR SCHED_RTPRIO , .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_OTHER is weaker than the weakest priority in the priority ranges for any of the other policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .RE .SH RETURN VALUE The functions return the following values: .SS sched_getparam() .SS sched_rr_get_interval() .SS sched_setparam() .SS sched_yield() .SS PRI_HPUX_TO_POSIX() .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_setscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the former scheduling policy of the specified process. .TP .CR -1 Failure. The policy and scheduling parameters remain unchanged. .CR errno is set to indicate the error. .PD .RE .SS sched_getscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the scheduling policy of the specified process. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the maximum or minimum value, respectively. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS PRI_POSIX_TO_HPUX() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the the HP-UX priority corresponding to the .I sched_priority member in the .I param structure. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If the functions fail, .CR errno is set to one of the following values. .SS sched_setparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] One or more of the requested scheduling parameters is outside the range defined for the scheduling policy of the specified .IR pid . .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling parameters for the specified process, or does not have the appropriate privilege to invoke .CR sched_setparam() . .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_setscheduler() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] The value of the .I policy parameter is invalid, or one or more of the parameters contained in .I param is outside the valid range for the specified scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling policy of the specified process. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getscheduler() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_yield() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP 15 [EINVAL] The value of the .I policy parameter does not represent a defined scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .RE .SS sched_rr_get_interval() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS PRI_POSIX_TO_HPUX() .RS .TP 15 [EINVAL] The priority specified in the .I sched_priority member of the .I param argument is outside the range defined for the .CR SCHED_HPUX scheduling policy. .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS PRI_HPUX_TO_POSIX() .RS .TP 15 [EINVAL] The priority specified in the .I pri argument is not a valid HP-UX priority. .TP [ENOSYS] The function is not supported by this implementation. .RE .SH EXAMPLES Change the calling process to use the strongest .CR FIFO priority: .IP .nf .C "#include " .IP .C "struct sched_param param;" .C "int maxpri;" .IP .C "maxpri = sched_get_priority_max(SCHED_FIFO);" .C "if (maxpri == -1) {" .C " perror(""sched_get_priority_max() failed"");" .C " exit(1);" .C "}" .C "param.sched_priority = maxpri;" .C "if (sched_setscheduler(getpid(), SCHED_FIFO, ¶m) == -1) {" .C " perror(""sched_setscheduler() failed"");" .C " exit(1);" .C "}" .fi .SH AUTHOR The .CI sched_ * () functions were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .PP .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() were developed by HP. .SH SEE ALSO rtsched(1), rtprio(2). .SH STANDARDS CONFORMANCE .CR sched_get_priority_max() ": POSIX.4" .PP .CR sched_get_priority_min() ": POSIX.4" .PP .CR sched_getparam() ": POSIX.4" .PP .CR sched_getscheduler() ": POSIX.4" .PP .CR sched_rr_getinterval() ": POSIX.4" .PP .CR sched_setparam() ": POSIX.4" .PP .CR sched_setscheduler() ": POSIX.4" .PP .CR sched_yield() ": POSIX.4" .\" .\" index entries: .\" index@\f1rtsched\f1 \- real time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f4PRI_HPUX_TO_POSIX()\f1 \- return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f4PRI_POSIX_TO_HPUX()\f1 \- return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_max()\f1 \- return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_min()\f1 \- return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_getparam()\f1 \- return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_getscheduler()\f1 \- return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_rr_get_interval()\f1 \- update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4sched_setparam()\f1 \- set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_setscheduler()\f1 \- set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_yield()\f1 \- force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1operations, real-time scheduling@@@\f3rtsched(2)\f1 .\" index@\f1real-time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f1return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1scheduling operations, real-time@@@\f3rtsched(2)\f1 .\" index@\f1scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" links entries: .\" links@rtsched.2 PRI_HPUX_TO.2 .\" links@rtsched.2 PRI_POSIX_T.2 .\" links@rtsched.2 pri_hpux_to.2 .\" links@rtsched.2 pri_posix_t.2 .\" links@rtsched.2 sched_get_p.2 .\" links@rtsched.2 sched_getpa.2 .\" links@rtsched.2 sched_getsc.2 .\" links@rtsched.2 sched_rr_ge.2 .\" links@rtsched.2 sched_setpa.2 .\" links@rtsched.2 sched_setsc.2 .\" links@rtsched.2 sched_yield.2 .\" toc entries: .\" toc@\f3rtsched(2)\f1:\0\0\f4sched_get_priority_max()\f1, \f4sched_get_priority_min()\f1,\n\f4sched_getparam()\f1, \f4sched_getscheduler()\f1, \f4sched_rr_get_interval()\f1,\n\f4sched_setparam()\f1, \f4sched_setscheduler()\f1, \f4sched_yield()\f1,\n\f4PRI_HPUX_TO_POSIX()\f1, \f4PRI_POSIX_TO_HPUX()\f1@@@real-time scheduling operations .\" toc@\f4PRI_HPUX_TO_POSIX()\f1:\0\0return POSIX.4 process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4PRI_POSIX_TO_HPUX()\f1:\0\0return HP-UX process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_max()\f1:\0\0return maximum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_min()\f1:\0\0return minimum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getparam()\f1:\0\0return scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getscheduler()\f1:\0\0return scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_rr_get_interval()\f1:\0\0update execution time limit@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setparam()\f1:\0\0set scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setscheduler()\f1:\0\0set scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_yield()\f1:\0\0force process to relinquish processor@@@\f1see \f3rtsched(2)\f1 .\" $Header: profil.2,v 72.4 94/11/14 15:25:34 ssa Exp $ .TA p .TH profil 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME profil \- execution time profile .SH SYNOPSIS .C "#include " .PP .nf .PD 0 .C "void profil(" .IP .C "unsigned short int *buff," .C "size_t bufsiz," .C "size_t offset," .C "unsigned int scale" .PP .C ");" .PD .fi .SH DESCRIPTION .C profil() controls profiling, by which the system maintains estimates of the amount of time the calling program spends executing at various places in its address space. .PP The .I buff argument must point to an area of memory whose length (in bytes) is given by .IR bufsiz . When profiling is on, the process's program counter (pc) is examined each clock tick .RC ( CLK_TCK times per second), .I offset is subtracted from the pc value, and the result is multiplied by .IR scale . If the resulting number corresponds to an element inside the array of .CR "unsigned short int" s to which .I buff points, that element is incremented. .PP The number of samples per second for a given implementation is given by .CR CLK_TCK , which is defined in .RC < time.h >. .PP The scale is interpreted as an unsigned, sixteen bit, fixed-point fraction with binary point at the left: 0177777 (octal) gives a one-to-one mapping of pc's to words in .IR buff ; 077777 (octal) maps each pair of instruction words together. 02(octal) maps all instructions onto the beginning of .I buff (producing a non-interrupting core clock). .PP Profiling is turned off by giving a .I scale of 0 or 1. It is rendered ineffective by giving a .I bufsiz of 0. Profiling is turned off when one of the .C exec() functions is executed, but remains on in child and parent both after a .CR fork() . Profiling is turned off if an update in .I buff would cause a memory fault. .SH RETURN VALUE No value is returned. .SH SEE ALSO prof(1), monitor(3C). .SH STANDARDS CONFORMANCE .CR profil() ": SVID2, SVID3, XPG2" .\" .\" index@\f4profil()\fP \(mi execution time profile@@@\f3profil(2)\f1 .\" index@execution time profile@@@\f3profil(2)\f1 .\" index@time profile, execution@@@\f3profil(2)\f1 .\" index@profile, execution time@@@\f3profil(2)\f1 .\" .\" toc@\f3profil(2)\f1:\0\0\f4profil()\fP@@@execution time profile .\" .\" fileset_database@profil.2 PROGRAMING-MAN .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: pstat.2,v 78.1 96/02/12 14:11:22 ssa Exp $ .TA p .TH pstat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat() \- get system information .SH SYNOPSIS .CR "#include " .PP .CR "#include " .PP .CR "int pstat_getstatic(" .nf .PD 0 .IP .CR "struct pst_static *buf, size_t elemsize, size_t elemcount," .CR "int index" .PP .CR ");" .PP .CR "int pstat_getdynamic(" .nf .PD 0 .IP .CR "struct pst_dynamic *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getvminfo(" .nf .PD 0 .IP .CR "struct pst_vminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getipc(" .nf .PD 0 .IP .CR "struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocessor(" .nf .PD 0 .IP .CR "struct pst_processor *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getproc(" .nf .PD 0 .IP .CR "struct pst_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getprocvm(" .nf .PD 0 .IP .CR "struct pst_vm_status *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getdisk(" .nf .PD 0 .IP .CR "struct pst_diskinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getlv(" .nf .PD 0 .IP .CR "struct pst_lv *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getswap(" .nf .PD 0 .IP .CR "struct pst_swapinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getsem(" .nf .PD 0 .IP .CR "struct pst_seminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getmsg(" .nf .PD 0 .IP .CR "struct pst_msginfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getshm(" .nf .PD 0 .IP .CR "struct pst_shminfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getfile(" .nf .PD 0 .IP .CR "struct pst_fileinfo *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat_getstable(" .nf .PD 0 .IP .CR "struct pst_stable *buf, size_t elemsize, size_t elemcount," .CR " int index" .PP .CR ");" .PP .CR "int pstat(" .nf .PD 0 .IP .CR "int, union pstun, size_t, size_t, int" .PP .CR ");" .PD .SS Remarks The underlying function .CR "pstat()" is provided for backward compatibility. Use of the .CR "pstat_get*()" wrapper functions (for example, .CR "pstat_getproc()" ) is recommended to avoid the polymorphic typing of the .CR "union pstun" parameter. .SH DESCRIPTION The .CR pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs .CR pst_static , .CR pst_dynamic , .CR pst_vminfo , .CR pst_ipcinfo , .CR pst_processor , .CR pst_diskinfo , .CR pst_swapinfo , .CR pst_status , .CR pst_vm_status , .CR pst_lvinfo , .CR pst_seminfo , .CR pst_msginfo , .CR pst_shminfo , .CR pst_fileinfo and .CR pst_stable are declared in the header file .CR . The header contains descriptions of the fields of each of the context data structures. .SS Summary of Available Contexts The .CR pstat routines support the following contexts of information. Detailed descriptions of each routine follow. .PP .ifn .RS -5 .ift .RS 10 .ifn .ne 25 .ift .ne 18 .vs +1 .TS tab(;) ; Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 Lf3 2| Lf3 2| Lf3 2| Lf3 2| Lf3 L 2| Lf4 2| Lf4 2| L 2| L. _ ;;;;Short Context;Struct;Routine;Instances;Cut _ Static;pst_static;pstat_getstatic();1; Dynamic;pst_dynamic;pstat_getdynamic();1; VM;pst_vminfo;pstat_getvminfo();1; IPC;pst_ipcinfo;pstat_getipc();1; Stable Store;pst_stable;pstat_getstable();1; _ Processor;pst_processor;pstat_getprocessor();1 per processor; Disk;pst_diskinfo;pstat_getdisk();1 per disk; Swap;pst_swapinfo;pstat_getswap();1 per swap area; _ Process;pst_status;pstat_getproc();1 per process;yes Process VM;pst_vm_status;pstat_getprocvm();1 per process region;yes LVM Vol;pst_lvinfo;pstat_getlv();1 per lvol;yes Sema Set;pst_seminfo;pstat_getsem();1 per sem set;yes Msg Queue;pst_msginfo;pstat_getmsg();1 per msg queue;yes Shared Mem;pst_shminfo;pstat_getshm();1 per shm seg;yes _ Open File;pst_fileinfo;pstat_getfile();1 per file;yes _ .sp .5 .TE .vs .RE .PP .SS Wrapper Function Descriptions .RS .TP 10 .CR pstat_getstatic() Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_static" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getdynamic() Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_dynamic" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getvminfo() Returns information about the virtual memory subsystem. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_vminfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getipc() Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_ipcinfo" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .TP .CR pstat_getprocessor() Returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_processor pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_processor that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processors. .TP .CR pstat_getdisk() Returns information specific to a particular disk. There is one instance of this context for each disk configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_diskinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_diskinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of disks. .TP .CR pstat_getswap() Returns information specific to a particular swap area. There is one instance of this context for each swap area (block or filesystem) configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_swapinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_swapinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of swap areas. .TP .CR pstat_getproc() Returns information specific to a particular process. There is one instance of this context for each active process on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_status pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_status that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of processes. As a shortcut, information for a single process may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM PID of that process. .TP .CR pstat_getprocvm() Returns information specific to a particular process' address space. There is one instance of this context for each process region contained in the process' address space. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct .CR pst_vm_status pointed to by .CR buf . Only at most one instance (process region) is returned for each call to .CR pstat_getprocvm() . The .CR elemcount parameter identifies the process for which address space information is to be returned. An .CR elemcount parameter of zero indicates that address space information for the currently executing process should be returned. The .CR index parameter specifies the starting index (beginning with 0) within the context of process regions for the indicated process. For example, an .CR index of 3 indicates the 4th process region within the indicated process' address space. As a shortcut, information for a specific process (other than the currently executing one) may be obtained by setting .CR elemcount to the .SM PID of that process. .TP .CR pstat_getlv() Returns information specific to a particular logical volume. There is one instance of this context for each logical volume configured into the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_lvinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_lvinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of logical volumes. As a shortcut, information for a single logical volume may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM dev_t of that logical volume. .TP .CR pstat_getsem() Returns information specific to a particular .SM "System V" semaphore set. There is one instance of this context for each .SM "System V" semaphore set on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_seminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_seminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" semaphore sets. As a shortcut, information for a single semaphore set may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM semid of that semaphore set. .TP .CR pstat_getmsg() Returns information specific to a particular .SM "System V" message queue. There is one instance of this context for each .SM "System V" message queue on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_msginfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_msginfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" message queues. As a shortcut, information for a single message queue may be obtained by setting .CR elemcount to zero and setting index to the .SM msqid of that message queue. .TP .CR pstat_getshm() Returns information specific to a particular .SM "System V" shared memory segment. There is one instance of this context for each .SM "System V" shared memory segment on the system. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_shminfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_shminfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of .SM "System V" shared memory segments. As a shortcut, information for a single shared memory segment may be obtained by setting .CR elemcount to zero and setting .CR index to the .SM shmid of that shared memory segment. .TP .CR pstat_getfile() Returns information specific to a particular open file for a specified process. For the specified process, there is one instance of this context for each open file descriptor. For each instance requested, data, up to a maximum of .CR elemsize bytes, are returned in the .CR struct s .CR pst_fileinfo pointed to by .CR buf . The .CR elemcount parameter specifies the number of .CR struct s .CR pst_fileinfo that are available at .CR buf to be filled in. The .CR index parameter specifies the starting index within the context of open files for the specified process: it is a 32-bit quantity constructed of the .CR pst_idx field of the 'owning' process, obtained via .CR pstat_getproc() , described above, as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits. Example: .IP .CR "index = ((pst_idx << 16) | (file_index & 0xffff));" As a shortcut, information for a single file within the specified process may be obtained by setting .CR elemcount to zero and setting the least significant 16 bits to the file descriptor number (the most significant 16 bits are still set to the .CR pst_idx field from the .CR pst_status structure for the process). .IP The .CR pst_fileinfo structure contains both a .CR psf_offset and .CR psf_offset64 element. The .CR psf_offset element can correctly store a 32-bit value, whereas the .CR psf_offset64 element can store a 64-bit value. .CR pstat_getfile() will fill in both .CR psf_offset and .CR psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in .CR psf_offset , then .CR psf_offset will contain a -1. No error will be set in this case. .TP .CR pstat_getstable() Returns information contained in the system's stable storage area. There is one global instance of this context. Data, up to a maximum of .CR elemsize bytes, are returned in the .CR "struct pst_stable" pointed to by .CR buf . The .CR elemcount parameter must be 1. The .CR index parameter must be 0. .SH RETURN VALUE Upon successful completion, .CR pstat() and the various wrapper routines (for example, .CR pstat_getprocessor() ) return the number of instances filled in at the address .CR buf . Otherwise, a value of \(mi1 is returned and .CR errno is set to indicate the error. .PP .RS .SH ERRORS The .CR pstat functions fail if any of the following conditions are encountered: .PP .RS .TP 15 [EFAULT] .CR buf points to an invalid address. .TP [ESRCH] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in .CR index (for example, .SM PID for .CR pstat_getproc() ). .TP [EINVAL] For the .CR pstat_getproc() , .CR pstat_getprocvm() , .CR pstat_getlv() , .CR pstat_getsem() , .CR pstat_getmsg() , .CR pstat_getshm() or .CR pstat_getfile() calls, .CR elemcount was not zero, and .CR index was less than zero. .TP [EINVAL] .CR elemsize is less than or equal to zero or .CR elemsize is larger than the size of the associated data structure (for example, .CR elemsize > sizeof ( .CR "struct pst_processor" ) for the .CR pstat_getprocessor() call). .TP [EINVAL] .CR elemcount is not 1 or .CR index is not zero for the .CR pstat_getstatic() , .CR pstat_getdynamic() , .CR pstat_getvminfo() , .CR pstat_getipc() or .CR pstat_getstable() calls. .TP [EINVAL] .CR elemcount is not greater than or equal to 1 or .CR index is not greater than or equal to zero for the .CR pstat_getprocessor() , .CR pstat_getdisk() or .CR pstat_getswap() calls. .TP [EOVERFLOW] Offset element is too large to store into the structure pointed to by the .CR buf argument. .SH BACKWARD COMPATIBILITY The specific calling convention of passing the expected data structure size is used in order to allow for future expansion of the interface, while preserving backwards source and object compatibility for programs written using the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the operating system. .RS .RS .TP 3 \(bu New data for a context are added to the end of that context's data structure. .TP \(bu Old, obsolete data members are .CI NOT deleted from the data structure. .TP \(bu The operating system honors the .CR elemsize parameter of the call and only returns the first .CR elemsize bytes of the context data, even if the actual data structure has since been enlarged. .RE .RE .PP In this way, an application which passes its compile-time size of the context's data structure (for example, .CR "sizeof(struct pst_processor" ) for the per-process context) as the .CR elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context data structures. If the program is recompiled, it will also continue to execute on that and future releases. Note that the reverse is not true: a program using the .CR pstat interfaces compiled on, say, .SM HP-UX release 10.0 will not work on .SM HP-UX release 9.0. .PP The code examples, below, demonstrate the calling conventions described above. .SH EXAMPLES .PD 0 .CR "#include " .PP .CR "#include " .PP .CR "#include " .nf .CR "/*" .CR " * Example 1: get static global information" .CR " */" .CR { .RS .CR "struct pst_static pst;" .CR " " .CR "if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)" .RS .CR (void)printf("page size is %d bytes\en", pst.page_size); .RE .CR else .RS .C perror("pstat_getstatic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 2: get information about all processors, first obtaining" .C " * number of processor context instances" .C " */" .C { .RS .C "struct pst_dynamic psd;" .C "struct pst_processor *psp;" .C " " .C "if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) {" .RS .C "size_t nspu = psd.psd_proc_cnt;" .C "psp = (struct pst_processor *)malloc(nspu * sizeof(*psp));" .C "if (pstat_getprocessor(psp, sizeof(*psp), nspu, 0) != -1) {" .RS .C "int i;" .C "int total_execs = 0;" .C "for (i = 0; i < nspu; i++) {" .RS .C "int execs = psp[i].psp_sysexec;" .C "total_execs += execs;" .C (void)printf("%d exec()s on processor #%d\en", .RS .RS .C "execs, i);" .RE .RE .RE .C } .C " " .C (void)printf("total execs for the system were %d\en", .RS .RS .C "total_execs);" .RE .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C else .RS .C perror("pstat_getdynamic"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 3: get information about all per-process -- 10 at a time" .C " * done this way since current count of active processes unknown" .C " */" .C { .C "#define BURST ((size_t)10)" .C " " .RS .C "struct pst_status pst[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C "/* loop until count == 0, will occur all have been returned */" .C "while ((count = pstat_getproc(pst, sizeof(pst[0]), BURST, idx)) > 0) {" .RS .C "/* got count (max of BURST) this time. process them */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("pid is %d, command is %s\en", .RS .RS .C "pst[i].pst_pid, pst[i].pst_ucomm);" .RE .RE .RE .C } .C " " .C "/*" .C " * now go back and do it again, using the next index after" .C " * the current 'burst'" .C " */" .C "idx = pst[count-1].pst_idx + 1;" .RE .C } .C " " .C "if (count == -1)" .RS .C perror("pstat_getproc()"); .RE .RE .C " " .C "#undef BURST" .C } .C " " .fi .nf .C "/*" .C " * Example 4: Get a particular process' information" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)" .RS .C (void)printf("Parent started at %s", ctime(&pst.pst_start)); .RE .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 5: get information about all shared memory segments" .C " */" .C { .RS .C "struct pst_ipcinfo psi;" .C "struct pst_shminfo *pss;" .C " " .C "if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {" .RS .C "size_t num_shm = psi.psi_shmmni;" .C "pss = (struct pst_shminfo *)malloc(num_shm * sizeof(*pss));" .C "if (pstat_getshm(pss, sizeof(*pss), num_shm, 0) != -1) {" .RS .C "int i;" .C (void)printf("owner\etkey\etsize\en"); .C "for (i = 0; i < num_shm; i++) {" .RS .C "/* skip inactive segments */" .C "if (!(pss[i].psh_flags & PS_SHM_ALLOC))" .RS .C "continue;" .RE .C (void)printf("%d\et%#x\et%d\en", .RS .RS .C "pss[i].psh_uid, pss[i].psh_key," .C "pss[i].psh_segsz);" .RE .RE .RE .C } .RE .C } .C else .RS .C perror("pstat_getshm"); .RE .RE .C } .C else .RS .C perror("pstat_getipc"); .RE .RE .C } .C " " .fi .nf .C "/*" .C " * Example 6: List all the open files for a process" .C " */" .C { .RS .C "struct pst_status pst;" .C "int target = (int)getppid(); .C " " .C "/*" .C " * First get the desired process to get its 'index'." .C " * This will be used when retrieving the file data." .C " */" .C "if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) {" .RS .RS .C "int pidx = pst.pst_idx;" .RE .RE .RE .C "#define BURST ((size_t)10)" .RS .RS .RS .C "struct pst_fileinfo psf[BURST];" .C "int i, count;" .C "int idx = 0; /* index within the context */" .C " " .C (void)printf("Open files for process PID %d\en", pst.pst_pid); .C " " .C "/*" .C " * Construct the index into the per-process file context:" .C " * Most significant 16 bits are the process' index (above)." .C " * Least significant 16 bits are the file's index." .C " * For a given process, the file index starts at 0." .C " */" .C "idx = (pidx << 16) | (0 & 0xffff);" .C " " .C "/* loop until all fetched */" .C "while (count = pstat_getfile(psf, sizeof(psf[0]), .RS .RS .C "BURST, idx) > 0) {" .RE .RE .RS .C "/* process them (max of BURST) at a time */" .C "for (i = 0; i < count; i++) {" .RS .C (void)printf("fd #%x\etFSid %x:%x\etfileid %d\en", .RS .RS .C "psf[i].psf_fd," .C "psf[i].psf_id.psf_fsid.psfs_id," .C "psf[i].psf_id.psf_fsid.psfs_type," .C "psf[i].psf_id.psf_fileid);" .RE .RE .RE .C } .C " " .C "/*" .C " * Now go back and do it again, using the" .C " * next index after the current 'burst'" .C " */" .C "idx = psf[count-1].psf_idx + 1;" .RE .C } .C "if (count == -1)" .RS .C perror("pstat_getfile()"); .RE .C " " .RE .RE .RE .C "#undef BURST" .RS .RS .RE .C } .C else .RS .C perror("pstat_getproc"); .RE .RE .C } .fi .PD .SH AUTHOR The .C pstat routines were developed by HP. .SH FILES .TP 30 /usr/include/sys/pstat.h Contains detailed descriptions of context data structures and fields. .SH SEE ALSO ps(1), top(1), vmstat(1), iostat(1), fuser(1), vgdisplay(1), lvdisplay(1), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2), fileno(3S). .\" .\" .\" toc@\f3pstat(2)\f1:\0\0\f4pstat_getstatic()\f1, \f4pstat_getdynamic()\f1, \f4pstat_getproc()\f1, \f4pstat_getprocessor()\f1,\n \f4pstat_getvminfo()\f1, \f4pstat_getdisk()\f1, \f4pstat_getlv()\f1, \f4pstat_getswap()\f1,\f4pstat_getfile()\f1,\n \f4pstat_getipc()\f1, \f4pstat_getsem()\f1, \f4pstat_getmsg()\f1, \f4pstat_getshm()\f1,\n \f4pstat_getprocvm()\f1, \f4pstat_getstable()\f1, \f4pstat()\f1@@@get system information .\" .\" toc@\f4pstat_getstatic()\f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdynamic() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getproc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getprocessor() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getvminfo() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getdisk() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getlv() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getswap() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getfile() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getipc() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getsem() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getmsg() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getshm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" toc@\f4pstat_getprocvm() \f1@@@\f1see \f3pstat(2)\f1 .\" toc@\f4pstat_getstable() \f1@@@\f1see \f3pstat(2)\f1 .\" .\" index@\f4pstat()\f1 \- get system information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstatic()\f1-\ get static system information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdynamic() \f1\- get dynamic system information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getproc() \f1\- get information about a process@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getprocessor() \f\- get information about a processor1@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getvminfo() \f1\- get virtual memory information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getdisk() \f1\- get disk information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getlv() \f1\- get logical volume information@@@\f1 \f3pstat(2)\f1 .\" index@\f4pstat_getswap() \f1\- get swap area information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getfile() \f1\- get open file information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getipc() \f1\- get IPC information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getsem() \f1\- get semaphore set information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getmsg() \f1\- get message queue information@@@\f1\f3pstat(2)\f1 .\" index@\f4pstat_getshm() \f1\- get shared memory segment information @@@\f1\f3pstat(2)\f1 .\" index@\f4pstat() \f1\- set system information @@@\f1\f3pstat(2)\f1 .\" .\" .\" index@\f4pstat_getprocvm() \f1\- get process address space information@@@\f3pstat(2)\f1 .\" index@\f4pstat_getstable() \f1\- get information contained in system's stable storage area@@@\f3pstat(2)\f1 .\" .\" links@pstat.2 pstat_getstatic.2 .\" links@pstat.2 pstat_getdynamic.2 .\" links@pstat.2 pstat_getproc.2 .\" links@pstat.2 pstat_getprocessor.2 .\" links@pstat.2 pstat_getvminfo.2 .\" links@pstat.2 pstat_getdisk.2 .\" links@pstat.2 pstat_getlv.2 .\" links@pstat.2 pstat_getswap.2 .\" links@pstat.2 pstat_getfile.2 .\" links@pstat.2 pstat_getipc.2 .\" links@pstat.2 pstat_getsem.2 .\" links@pstat.2 pstat_getmsg.2 .\" links@pstat.2 pstat_getshm.2 .\" links@pstat.2 pstat_getprocvm.2 .\" links@pstat.2 pstat_getstable.2 .\" $Header: ptrace.2,v 72.5 94/11/14 15:25:40 ssa Exp $ .TA p .TH ptrace 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ptrace() \- process trace .SH SYNOPSIS .nf .C "#include " .PP .C "int ptrace(" .C " int request," .C " pid_t pid," .C " int addr," .C " int data," .C " int addr2" .C ");" .fi .SS Remarks Much of the functionality of .CR ptrace() is highly dependent on the underlying hardware. An application that uses this system call should not be expected to be portable across architectures or implementations. .SH DESCRIPTION The .CR ptrace() system call provides a means by which a process can control the execution of another process. Its primary use is for the implementation of breakpoint debugging (see .IR adb (1)). The traced process behaves normally until it encounters a signal (see .IR signal (2) for the list), at which time it enters a stopped state and the tracing process is notified via .CR wait() (see .IR wait (2)). .PP A traced process may also enter the stopped state without encountering a signal. This can happen if the traced process stops in response to specific .I events that it encounters during the course of its execution. To make this happen, the tracing process has to set specific event flags in the context of the traced process. This mechanism will be described later in greater detail. .PP When the traced process is in the stopped state, the tracing process can use .CR ptrace() to examine and modify the "core image". Also, the tracing process can cause the traced process to either terminate or continue, with the possibility of ignoring the signal that caused it to stop. .PP To forestall possible fraud, .CR ptrace() inhibits the set-user-ID facility on subsequent .CI exec * () calls. If a traced process calls .CI exec * () \f1, it stops before executing the first instruction of the new image, showing signal .CR SIGTRAP . .PP The .I request argument determines the precise action to be taken by .CR ptrace() . It is one of the values described in the rest of this section. .PP The following request is used by the child process that will be traced. .RS .TP 15 .CR PT_SETTRC This request must be issued by a child process if it is to be traced by its parent. It turns on the child's trace flag, which stipulates that the child should be left in a stopped state upon receipt of a signal rather than the state specified by .IR func (see .IR signal (2)). The .IR pid , .IR addr , .IR data , and .IR addr2 arguments are ignored, and a return value is not defined for this request. Peculiar results occur if the parent does not expect to trace the child. .RE .PP The remainder of the requests can only be used by the tracing process. For each, .I pid is the process ID of the process being traced, which must be in a stopped state before these requests are made. The responsibility of ensuring that the traced process is in a stopped state before a request is issued, lies with the tracing process. .RS .TP 15 .PD 0 .CR PT_RDUSER .TP .CR PT_RIUSER .PD With these requests, the word at location .I addr in the address space of the traced process is returned to the tracing process. If instruction (I) and data (D) space are separated, request .CR PT_RIUSER returns a word from I space, and request .CR PT_RDUSER returns a word from D space. If I and D space are not separated, either request produces equivalent results. The .I data and .I addr2 arguments are ignored. .IP These two requests fail if .I addr is not the start address of a word, in which case a value of \(mi1 is returned to the tracing process and its .CR errno is set to [EIO]. .TP .CR PT_RUAREA With this request, the word at location .I addr in the user area of the traced process in the system's address space (see .CR ) is returned to the tracing process. Addresses in this area are system dependent, but start at zero. The limit can be derived from .CR . The .I data and .I addr2 arguments are ignored. .IP This request fails if .I addr is not the start address of a word or is outside the user area, in which case a value of \(mi1 is returned to the tracing process and its .CR errno is set to [EIO]. .TP .PD 0 .CR PT_WDUSER .TP .CR PT_WIUSER .PD With these requests, the value given by the .I data argument is written into the address space of the traced process at location .IR addr . .CR PT_WIUSER writes a word into I space, and .CR PT_WDUSER writes a word in D space. Upon successful completion, the value written into the address space of the traced process is returned to the tracing process. The .I addr2 argument is ignored. .IP These two requests fail if .I addr is not the start address of a word, or if .I addr is a location in a pure procedure space and either another process is executing in that space or the tracing process does not have write access for the executable file corresponding to that space. Upon failure, a value of \(mi1 is returned to the tracing process and its .CR errno is set to [EIO]. .TP .CR PT_WUAREA This request is not supported. Therefore, it returns \(mi1, sets .CR errno to [EIO] and does not affect the user area of the traced process. .TP .CR PT_RUREGS With this request, the word at location .I addr in the .CR save_state structure at the base of the per-process kernel stack is returned to the tracing process. .I addr must be word-aligned and less than .CR STACKSIZE*NBPG (see .CR and .CR ). The .CR save_state structure contains the registers and other information about the process. The .IR data and .IR addr2 arguments are ignored. .TP .CR PT_WUREGS The .CR save_state structure at the base of the per-process kernel stack is written as it is read with request .CR PT_RUREGS . Only a few locations can be written in this way: the general registers, most floating-point registers, a few control registers, and certain bits of the interruption processor status word. The .IR addr2 argument is ignored. .TP .PD 0 .CR PT_RDDATA .TP .CR PT_RDTEXT .PD These requests are identical to .CR PT_RDUSER and .CR PT_RIUSER , except that the .I data argument specifies the number of bytes to read and the .I addr2 argument specifies where to store that data in the tracing process. .TP .PD 0 .CR PT_WRDATA .TP .CR PT_WRTEXT .PD These requests are identical to .CR PT_WDUSER and .CR PT_WIUSER , except that the .I data argument specifies the number of bytes to write and the .I addr2 argument specifies where to read that data in the tracing process. .TP .CR PT_CONTIN This request causes the traced process to resume execution. If the .I data argument is 0, all pending signals, including the one that caused the traced process to stop, are canceled before it resumes execution. If the .I data argument is a valid signal number, the traced process resumes execution as if it had incurred that signal, and any other pending signals are canceled. The .I addr2 argument is ignored. .IP If the .I addr argument is not 1, the Instruction Address Offset Queue (program counter) is loaded with the values .I addr and .IC addr +4 before execution resumes. Otherwise, execution resumes from the point where it was interrupted. .IP Upon successful completion, the value of .I data is returned to the tracing process. .IP This request fails if .I data is not 0 or a valid signal number, in which case a value of \(mi1 is returned to the tracing process and its .CR errno is set to [EIO]. .TP .CR PT_EXIT This request causes the traced process to terminate with the same consequences as .CR exit() . The .IR addr , .IR data , and .IR addr2 arguments are ignored. .TP .CR PT_SINGLE This request causes a flag to be set so that an interrupt occurs upon the completion of one machine instruction. It then executes the same steps as listed above for request .CR PT_CONTIN . If the processor does not provide a trace bit, this request returns an error. This effectively allows single-stepping of the traced process. .IP Whether or not the trace bit remains set after this interrupt is a function of the hardware. .TP .CR PT_ATTACH This request stops the process identified by .I pid and allows the calling process to trace it. Process .I pid does not have to be a child of the calling process, but the effective user ID of the calling process must match the real and saved user ID of process .I pid unless the effective user ID of the tracing process is superuser. The calling process can use the .CR wait() system call to wait for process .IR pid to stop. The .IR addr , .IR data , and .I addr2 arguments are ignored. .TP .CR PT_DETACH This request detaches the traced process .I pid and allows it to continue its execution in the manner of .CR PT_CONTIN . .IP If the .I addr argument is not 1, the Instruction Address Offset Queue (program counter) is loaded with the values .I addr and .IR addr2 . .TP .CR PT_CONTIN1 This request causes the traced process to resume execution with all its pending signals intact. If the .I data argument is 0, the signal that caused the traced process to stop is canceled before the traced process resumes execution. If the .I data argument is a valid signal number, the traced process resumes execution as if it had received that signal. The .I addr argument must be equal to 1 for this request. The .I addr2 argument is ignored. Upon successful completion, the value of .I data is returned to the tracing process. .IP This request fails if .I data is not 0 or a valid signal number, in which case a value of \(mi1 is returned to the tracing process and its .CR errno is set to [EIO]. .TP .CR PT_SINGLE1 This request causes a flag to be set so that an interrupt occurs upon the completion of one machine instruction. It then executes the same steps as listed above for request .CR PT_CONTIN1 . If the processor does not provide a trace bit, this request returns an error. This effectively allows single stepping of the traced process. .IP Whether or not the trace bit remains set after this interrupt is a function of the hardware. .RE .PP As noted earlier, a tracing process can set event flags in the context of the traced process to make it respond to specific events, during its execution. These events are: .RS .TP 15 .CR PTRACE_SIGNAL This event flag indicates that, when processing signals, the traced process needs to examine signal mask bits set in its context by the tracing process. See the .I ptrace_event structure description under .CR PT_SET_EVENT_MASK for further details. .IP If the signal being processed has its signal mask bit set, signal processing continues as though the process were not traced. The traced process is not stopped and the tracing process is not notified of the signal. If the signal mask bit is not set for the signal being processed, the traced process is stopped and the tracing process is notified via .CR wait() (see .IR wait (2)). .IP Note that the .CR SIGKILL signal is an exception to this rule in that it can never be unmasked; that is, it behaves as though its mask bit were always set, regardless of whether or not its mask bit is in fact set. Consequently, a .CR SIGKILL signal cannot be used to stop a traced process. .IP In this respect, a .CR SIGTRAP signal is also special in that it is specifically used to stop traced processes. A .CR SIGTRAP signal should therefore never be masked. Setting a mask bit for .CR SIGTRAP will result in unexpected system behavior. .TP .CR PTRACE_FORK This event flag indicates that the traced process needs to take special action when it invokes .CR fork(). When set, both the parent and child processes stop (the child after marking itself as a traced process and adopting its parent's debugger). Both processes log the fact that they stopped in response to a .CR PTRACE_FORK event. Further, the child's .I pid is logged in the parent's context, and the parent's .I pid is logged in the child's context. The child does not inherit its parent's event flags. See the .I ptrace_state structure description under .CR PT_GET_PROCESS_STATE for further details. .TP .CR PTRACE_VFORK This event flag indicates that the traced process needs to take special action when it invokes .CR vfork() . When set, the child process stops after marking itself as a traced process and adopting its parent's debugger. The fact that a .CR PTRACE_VFORK event was responded to is logged in the context of both the parent and child processes. Further, the child's .I pid is logged in the parent's context, and the parent's .I pid is logged in the child's context. The child does not inherit its parent's event flags. See the .I ptrace_state structure description under .CR PT_GET_PROCESS_STATE for further details. It is important to note that the warnings with respect to .CR vfork() (see .IR vfork (2)), continue to apply here. In particular, it needs to be remembered that, when the child process stops, its parent process is suspended, and that the child borrows the parent's memory and thread of control until a call to .CI exec * () or an exit (either by a call to .CR exit() or abnormally (see .IR exec (2) and .IR exit (2))). .TP .CR PTRACE_EXEC This event flag indicates that the traced process needs to take special action when it invokes .CI exec * () \f1. When set, the traced process stops after logging the fact that it stopped in response to a .CR PTRACE_EXEC event. It also logs information pertaining to the path or file argument of .CI exec * () \f1. This includes a pointer to the path name string and the length of the path name string. See the .I ptrace_state structure description under .CR PT_GET_PROCESS_STATE for further details. .TP .CR PTRACE_EXIT This event flag indicates that the traced process needs to take special action when it invokes .CR exit() . When set, the traced process stops after logging the fact that it stopped in response to a .CR PTRACE_EXIT event. .TP .CR PT_SET_EVENT_MASK This request is used by the calling process to specify event flags and signal mask values that it wants the traced process to respond to. It does so by writing the contents of the .I ptrace_event data structure in the user space pointed to by .I addr into the context of the traced process. The .I data argument specifies the number of bytes to be transferred. The .I addr2 argument is ignored. .IP The request fails if the number of bytes specified is less than zero or greater than the size of the .I ptrace_event structure, and its .CR errno is set to [EIO]. .RS .nf .IP .C "typedef struct ptrace_event{" .C " sigset_t pe_signals;" .C " events_t pe_set_event;" .C "} ptrace_event_t;" .fi .RE .IP Event flags are set in the .I pe_set_event member of the .I ptrace_event data structure. An event flag is set when the tracing process wants the traced process to respond to a particular event. As detailed earlier, the event flags defined are .CR PTRACE_EXEC , .CR PTRACE_EXIT , .CR PTRACE_FORK , .CR PTRACE_SIGNAL , and .CR PTRACE_VFORK . See the definition of .I events_t in .CR for more details. .IP Signal mask values are set in the .I pe_signals member of the .I ptrace_event structure. This field is qualified by a .CR PTRACE_SIGNAL event flag being set in the .I pe_set_event member. Mask values set in the .I pe_signals member correspond to signals that need to be masked from the tracing process when received by the traced process; that is, these are signals received by the traced process that the tracing process does not want to be informed about. The .I pe_signals member is described by the type definition .IR sigset_t , which is defined in .CR . .TP .CR PT_GET_EVENT_MASK This request is used by the calling process to determine the event flags and signal mask values that have been set in the traced process's context by the last .CR PT_SET_EVENT_MASK request. The .I data argument specifies the number bytes to be read from the context of the traced process into the .I ptrace_event data structure in user space pointed to by .I addr . The .I addr2 argument is ignored. .IP The request fails if the number of bytes requested is less than zero or greater than the size of the .I ptrace_event structure, and its .CR errno is set to [EIO]. .TP .CR PT_GET_PROCESS_STATE This request is used by the calling process to access state information logged by the traced process after it (the traced process) has responded to an event. The request reads .I data bytes of data from the traced process's context into the .I ptrace_state data structure in user space pointed to by .I addr . The .I addr2 argument is ignored. .IP The .I ptrace_state data structure is described in .CR and has the following members: .RS .nf .IP .C "typedef struct ptrace_state{" .C " events_t pe_report_event;" .C " int pe_path_len;" .C " pid_t pe_other_pid;" .C "} ptrace_state_t;" .fi .RE .IP The event that the traced process responded to and stopped is logged in the .I pe_report_event member. One of .CR PTRACE_EXEC , .CR PTRACE_EXIT , .CR PTRACE_FORK , .CR PTRACE_SIGNAL , or .CR PTRACE_VFORK is logged here. See the definition of .I events_t in .CR for more details. .IP If the event that the traced process responded to was .CR PTRACE_EXEC , then the .I pe_path_len member provides the length of the path name string (which is the path name of the executable file) not including the null terminating character. .IP If the event that the traced process responded to was .CR PTRACE_FORK or .CR PTRACE_VFORK , then the .I pe_other_pid member provides the parent's .I pid when accessed from the child's context, and the child's .I pid when accessed from the parent's context. .IP The request fails if the number of bytes requested is less than zero or greater than the size of the .I ptrace_event structure and its .CR errno is set to [EIO]. .TP .CR PT_GET_PROCESS_PATHNAME If the event that the traced process responded to and stopped was .CR PTRACE_EXEC , then this request is used by the calling process to access the path name of the executable file provided as a .I path or .I file argument to .CI exec * () \f1. The request reads .I data bytes of data of the path name string from the traced process's context into the data buffer in user space pointed to by .I addr . The .I addr2 argument is ignored. In the typical case, .I data is equal to the value of the .I pe_path_len member of the .I ptrace_state structure returned via the .CR PT_GET_PROCESS_STATE request. .IP If the number of bytes requested is greater than zero but less than the length of the path name string, then the number of bytes requested is returned. If the number of bytes requested is greater than the length of the path name string, then the full path name string (including the null terminating character) is returned. .IP The request fails if the number of bytes requested is less than zero, and its .CR errno is set to [EIO]. .RE .SH EXAMPLES The following example illustrates the use of some of the .CR ptrace() requests by a tracing process. .nf .PP .C "#include " .C "#include " .C "#include " .C "#include " .C "#define BUFSIZ 1024" .C "#define MAXPATH 1024" .PP .C "pid_t npid, cpid, pid;" .C "int status, errors=0, pathlength;" .C "ptrace_event_t *event_addr;" .C "ptrace_state_t *state_addr;" .C "char *buf_addr;" .C "size_t event_len, state_len;" .C "int filed[2];" .PP .C "child()" .C "{" .C " int n, bar;" .PP .C " close(filed[1]);" .C " /* Wait for parent to write to pipe */" .C " while ((n = read(filed[0], &bar, BUFSIZ)) == 0);" .PP .C " /* Now the child can exec. */" .C " if (execlp(""ls"", ""ls"", (char *)0) < 0) /* error during exec */" .C " printf(""Child: exec failed\en"");" .C " exit(0);" .C "}" .PP .C "parent()" .C "{" .C " close(filed[0]);" .PP .C " /* Before child does an exec, attach it and set its event flag. */" .C " if (ptrace(PT_ATTACH,pid)) /* failed to attach process */" .C " printf(""Parent: Failed to attach child\en"");" .C " if (pid != wait(&status)) /* wait failed */" .C " printf(""Parent: attach failed with wrong wait status\en"");" .C " if (!WIFSTOPPED(status) || (WSTOPSIG(status) != SIGTRAP))" .C " printf(""Parent: SIGTRAP didn't stop child\en"");" .PP .C " /*" .C " * The child process has now stopped. Set its event flag indicating" .C " * that it needs to trigger on a PTRACE_EXEC event." .C " */" .C " event_addr->pe_set_event = PTRACE_EXEC;" .C " if (ptrace(PT_SET_EVENT_MASK, pid, event_addr, event_len))" .C " printf(""Parent: PT_SET_EVENT_MASK ptrace request failed\en"");" .C " if (pid != wait(&status)) /* wait failed */" .C " printf(""Parent: wait() failed with wrong wait status\en"");" .PP .C " /*" .C " * Send the child a message so it can break out of the while loop." .C " * Get it running so it can exec." .C " */" .C " write(filed[1], ""now run"", 7);" .C " if (ptrace(PT_CONTIN, pid, 1, 0) != 0)" .C " printf(""Parent: failed to get child process running\en"");" .C " /*" .C " * Wait for the traced child to stop after the exec system call in" .C " * response to an exec event set in its ptrace_event structure." .C " */" .C " if (pid != (npid = wait(&status))) /* wait failed */" .C " printf(""Parent: wait() failed with wrong status\en"");" .C " if (!WIFSTOPPED(status))" .C " printf(""Parent: invalid wait() completion\en"");" .PP .C " /*" .C " * Child has stopped; fetch its process state and examine state" .C " * information. " .C " */" .C " if (ptrace(PT_GET_PROCESS_STATE, pid, state_addr, state_len) < 0)" .C " printf(""Parent: PT_GET_PROCESS_STATE ptrace request failed\en"");" .C " if (pid != wait(&status)) /* wait failed */" .C " printf(""Parent: wait() failed with wrong wait status\en"");" .PP .C " /* Check if the pathlength value returned is non-zero */" .C " if ((pathlength = state_addr->pe_path_len) == 0)" .C " printf(""Parent: zero length pathname returned\en"");" .PP .C " /* Fetch exec'd file pathname and store it in the buffer. */" .C " if (ptrace(PT_GET_PROCESS_PATHNAME, pid, buf_addr, (pathlength+1)) .C " < 0){" .C " printf(""Parent: Failed to get exec pathname\en"");" .C " } else {" .C " printf(""Parent: the exec pathname is %s\en"", buf_addr);" .C " if (pid != wait(&status)) /* wait failed */" .C " printf(""Parent: wait() failed with wrong status\en"");" .C " }" .C "}" .PP .C "main()" .C "{" .C " event_len = sizeof(ptrace_event_t);" .C " state_len = sizeof(ptrace_state_t);" .C " event_addr = calloc(event_len, 1);" .C " state_addr = calloc(state_len, 1);" .C " buf_addr = calloc(MAXPATH, 1);" .C " pipe(filed);" .C " switch (pid = fork()) {" .C " case -1:" .C " exit(1);" .C " case 0:" .C " child();" .C " break;" .C " default:" .C " parent();" .C " break;" .C " }" .C "}" .fi .SH ERRORS If .CR ptrace() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] The executable image of the process being attached resides across an interruptible NFS mount. .TP [EIO] .I request is an illegal number. .TP [EIO] The .CR PT_SETTRC request is used with a .I data argument that is less than zero or not a multiple of four, or .I data is not word-aligned. .TP [EIO] Attempting to write to a memory segment of the traced process that is not writeable, or attempting to write to page 0, or the .I request argument is out of range. .TP [EIO] The .CR PT_CONTIN request is being used with an invalid .I data argument (signal number). .TP [EIO] Attempting to write to the user area via the .CR PT_WUAREA request. .TP [EPERM] The specified process cannot be attached for tracing. .TP [EPERM] The process .I pid is already being traced or .I pid refers to the calling process itself. .TP [ESRCH] .I pid identifies a process to be traced that does not exist or has not executed a .CR ptrace() with request .CR PT_SETTRC . .RE .SH SEE ALSO adb(1), exec(2), exit(2), signal(2), wait(2). .SH STANDARDS CONFORMANCE .CR ptrace() ": SVID2, SVID3, XPG2" .\" .\" index@\f4ptrace()\f1 \- process trace@@@\f3ptrace(2)\f1 .\" index@\f1process trace@@@\f3ptrace(2)\f1 .\" index@\f1trace, process@@@\f3ptrace(2)\f1 .\" .\" toc@\f3ptrace(2)\f1:\0\0\f4ptrace()\fP@@@process trace .\" $Header: putmsg.2,v 74.1 95/03/31 16:56:00 ssa Exp $ .TA p .TH putmsg 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putmsg, putpmsg - send a message on a stream .SH SYNOPSIS .nf .C "#include " .PP .nf .CR "int putmsg(fildes, ctlptr, dataptr, flags); .CR "int fildes; .CR "struct strbuf *ctlptr; .CR "struct strbuf *dataptr; .CR "long flags; .CR "int putpmsg(fildes, ctlptr, dataptr, band, flags); .CR "int fildes; .CR "struct strbuf *ctlptr; .CR "struct strbuf *dataptr; .CR "int band; .CR "long flags;" .fi .SH DESCRIPTION The .CR putmsg() function creates a message from a process buffer(s) and sends the message to a STREAMS file. The message may contain either a data part, a control part, or both. The data and control parts are distinguished by placement in separate buffers, as described below. The semantics of each part is defined by the STREAMS module that receives the message. .P The .CR putpmsg() function does the same things a .CR putmsg() , but the process can send messages in different priority bands. Except where noted, all requirements on .CR putmsg() also pertain to .CR putpmsg() . .P The .IR fildes argument specifies a file descriptor referencing an open stream. The .IR ctlptr and .IR dataptr arguments each point to a .CR strbuf structure. .P The .IR ctlptr argument points to the structure describing the control part, if any, to be included in the message. The .IR buf member in the .CR strbuf structure points to the buffer where the control information resides, and the .IR len member indicates the number of bytes sent. The .IR maxlen member is not used by .CR putmsg() . In a similar manner, the argument .IR dataptr specifies the data, if any, to be included in the message. The .IR flags argument indicates what type of message should be sent and is described further below. .P To send the data part of a message, .IR dataptr must not be a null pointer and the .IR len member of .IR dataptr must be 0 or greater. To send the control part of a message, the corresponding values must be set for .IR ctlptr . No data (control) part will be sent if either .IR dataptr (\c .IR ctlptr ) is a null pointer or the .IR len member of .IR dataptr (\c .IR ctlptr ) is set to \(mi1. .P For .CR putmsg() , if a control part is specified and .IR flags is set to .CR RS_HIPRI , a high priority message is sent. If no control part is specified, and .IR flags is set to .CR RS_HIPRI , .CR putmsg() fails and sets .CR errno to [EINVAL]. If .IR flags is set to 0, a normal message (priority band equal to 0) is sent. If a control part and data part are not specified and .IR flags is set to 0, no message is sent and 0 is returned. .P The stream head guarantees that the control part of a message generated by .CR putmsg() is at least 64 bytes in length. .P For .CR putpmsg() , the flags are different. The .IR flags argument is a bitmask with the following mutually-exclusive flags defined: .CR MSG_HIPRI and .CR MSG_BAND . If .IR flags is set to 0, .CR putpmsg() fails and sets .CR errno to [EINVAL]. If a control part is specified and .IR flags is set to .CR MSG_HIPRI and .IR band is set to 0, a high-priority message is sent. If .IR flags is set to .CR MSG_HIPRI and either no control part is specified or .IR band is set to a non-zero value, .CR putpmsg() fails and set .CR errno to [EINVAL]. If .IR flags is set to .CR MSG_BAND , then a message is sent in the priority band specified by .IR band . If a control part and data part are not specified and .IR flags is set to .CR MSG_BAND , no message is sent and 0 is returned. .P The .CR putmsg() function blocks if the stream write queue is full due to internal flow control conditions. For high-priority messages, .CR putmsg() does not block on this condition. For other messages, .CR putmsg() does not block when the write queue is full and .CR O_NONBLOCK is set. .P The .CR putmsg() function also blocks, unless prevented by lack of internal resources, while for the availability of message blocks in the stream, regardless of priority of whether .CR O_NONBLOCK has been specified. No partial message is sent. .SH RETURN VALUE Upon successful completion, .CR putmsg() and .CR putpmsg() return 0. Otherwise, they return -1 and set .CR errno to indicate the error. .SH ERRORS .TP 15 [EAGAIN] A non-priority message was specified, the .CR O_NONBLOCK flag is set, and the stream write queue is full due to internal flow control conditions, or buffers could not be allocated for the message that was to be created. .TP [EBADF] .IR fildes is not a valid file descriptor open for writing. .TP [EINTR] A signal was caught during .CR putmsg() or .CR putpmsg() . .TP [EINVAL] An undefined value is specified in .IR flags , or .IR flags is set to .CR RS_HIPRI or .CR MSG_HIPRI and no control part is supplied, or the stream or multiplexor referenced by .IR fildes is linked (directly or indirectly) downstream from a multiplexor, or .IR flags is set to .CR MSG_HIPRI and .IR band is non-zero (for .CR putpmsg() only). .TP [ENOSTR] A stream is not associated with .IR fildes . .TP [ENXIO] A hangup condition was generated downstream for the specified stream. .TP [EPIPE] or [EIO] The .IR fildes argument refers to a STREAMS-based pipe and the other end of the pipe is closed. A .CR SIGPIPE signal is generated for the calling process. .TP [ERANGE] The size of the data part of the message does not fall within the range specified by the maximum and minimum packet sizes of the topmost STREAMS module. This value is also returned if the control part of the message is larger than the maximum configured size of the control part of a message, or if the data part of the message is larger than the maximum configured size of the data part of a message. .P In addition, .CR putmsg() and .CR putpmsg() will fail if the stream head had processed an asynchronous error before the call. In this case, the value of .CR errno does not reflect the result of .CR putmsg() or .CR putpmsg() but reflects the prior error. .SH SEE ALSO getmsg(2), poll(2), read(2), write(2), , streamio(7). .\" .\" index@\f4putmsg()\f1 \- send a message on a stream@@@\f3putmsg(2)\f1 .\" index@\f4putpmsg()\f1 \- send a message on a stream in different priority bands@@@\f3putmsg(2)\f1 .\" index@\f1STREAMS, send a message on a stream@@@\f3putmsg(2)\f1 .\" index@\f1send a message on a stream@@@\f3putmsg(2)\f1 .\" index@\f1message, send a message on a stream@@@\f3putmsg(2)\f1 .\" Main TOC entry .\" toc@\f3putmsg(2)\f1:\0\0\f4putmsg()\f1, \f4putpmsg()\f1@@@send a message on a stream .\" .\" toc@\f4putpmsg()\f1:\0\0send a message on a stream in different priority bands@@@\f1see \f3putmsg(2)\f1 .\" .\" links@putmsg.2 putpmsg.2 .\" .\" fileset_database@putmsg.2 STREAMS-MAN .\" $Header: putmsg.2,v 74.1 95/03/31 16:56:00 ssa Exp $ .TA p .TH putmsg 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putmsg, putpmsg - send a message on a stream .SH SYNOPSIS .nf .C "#include " .PP .nf .CR "int putmsg(fildes, ctlptr, dataptr, flags); .CR "int fildes; .CR "struct strbuf *ctlptr; .CR "struct strbuf *dataptr; .CR "long flags; .CR "int putpmsg(fildes, ctlptr, dataptr, band, flags); .CR "int fildes; .CR "struct strbuf *ctlptr; .CR "struct strbuf *dataptr; .CR "int band; .CR "long flags;" .fi .SH DESCRIPTION The .CR putmsg() function creates a message from a process buffer(s) and sends the message to a STREAMS file. The message may contain either a data part, a control part, or both. The data and control parts are distinguished by placement in separate buffers, as described below. The semantics of each part is defined by the STREAMS module that receives the message. .P The .CR putpmsg() function does the same things a .CR putmsg() , but the process can send messages in different priority bands. Except where noted, all requirements on .CR putmsg() also pertain to .CR putpmsg() . .P The .IR fildes argument specifies a file descriptor referencing an open stream. The .IR ctlptr and .IR dataptr arguments each point to a .CR strbuf structure. .P The .IR ctlptr argument points to the structure describing the control part, if any, to be included in the message. The .IR buf member in the .CR strbuf structure points to the buffer where the control information resides, and the .IR len member indicates the number of bytes sent. The .IR maxlen member is not used by .CR putmsg() . In a similar manner, the argument .IR dataptr specifies the data, if any, to be included in the message. The .IR flags argument indicates what type of message should be sent and is described further below. .P To send the data part of a message, .IR dataptr must not be a null pointer and the .IR len member of .IR dataptr must be 0 or greater. To send the control part of a message, the corresponding values must be set for .IR ctlptr . No data (control) part will be sent if either .IR dataptr (\c .IR ctlptr ) is a null pointer or the .IR len member of .IR dataptr (\c .IR ctlptr ) is set to \(mi1. .P For .CR putmsg() , if a control part is specified and .IR flags is set to .CR RS_HIPRI , a high priority message is sent. If no control part is specified, and .IR flags is set to .CR RS_HIPRI , .CR putmsg() fails and sets .CR errno to [EINVAL]. If .IR flags is set to 0, a normal message (priority band equal to 0) is sent. If a control part and data part are not specified and .IR flags is set to 0, no message is sent and 0 is returned. .P The stream head guarantees that the control part of a message generated by .CR putmsg() is at least 64 bytes in length. .P For .CR putpmsg() , the flags are different. The .IR flags argument is a bitmask with the following mutually-exclusive flags defined: .CR MSG_HIPRI and .CR MSG_BAND . If .IR flags is set to 0, .CR putpmsg() fails and sets .CR errno to [EINVAL]. If a control part is specified and .IR flags is set to .CR MSG_HIPRI and .IR band is set to 0, a high-priority message is sent. If .IR flags is set to .CR MSG_HIPRI and either no control part is specified or .IR band is set to a non-zero value, .CR putpmsg() fails and set .CR errno to [EINVAL]. If .IR flags is set to .CR MSG_BAND , then a message is sent in the priority band specified by .IR band . If a control part and data part are not specified and .IR flags is set to .CR MSG_BAND , no message is sent and 0 is returned. .P The .CR putmsg() function blocks if the stream write queue is full due to internal flow control conditions. For high-priority messages, .CR putmsg() does not block on this condition. For other messages, .CR putmsg() does not block when the write queue is full and .CR O_NONBLOCK is set. .P The .CR putmsg() function also blocks, unless prevented by lack of internal resources, while for the availability of message blocks in the stream, regardless of priority of whether .CR O_NONBLOCK has been specified. No partial message is sent. .SH RETURN VALUE Upon successful completion, .CR putmsg() and .CR putpmsg() return 0. Otherwise, they return -1 and set .CR errno to indicate the error. .SH ERRORS .TP 15 [EAGAIN] A non-priority message was specified, the .CR O_NONBLOCK flag is set, and the stream write queue is full due to internal flow control conditions, or buffers could not be allocated for the message that was to be created. .TP [EBADF] .IR fildes is not a valid file descriptor open for writing. .TP [EINTR] A signal was caught during .CR putmsg() or .CR putpmsg() . .TP [EINVAL] An undefined value is specified in .IR flags , or .IR flags is set to .CR RS_HIPRI or .CR MSG_HIPRI and no control part is supplied, or the stream or multiplexor referenced by .IR fildes is linked (directly or indirectly) downstream from a multiplexor, or .IR flags is set to .CR MSG_HIPRI and .IR band is non-zero (for .CR putpmsg() only). .TP [ENOSTR] A stream is not associated with .IR fildes . .TP [ENXIO] A hangup condition was generated downstream for the specified stream. .TP [EPIPE] or [EIO] The .IR fildes argument refers to a STREAMS-based pipe and the other end of the pipe is closed. A .CR SIGPIPE signal is generated for the calling process. .TP [ERANGE] The size of the data part of the message does not fall within the range specified by the maximum and minimum packet sizes of the topmost STREAMS module. This value is also returned if the control part of the message is larger than the maximum configured size of the control part of a message, or if the data part of the message is larger than the maximum configured size of the data part of a message. .P In addition, .CR putmsg() and .CR putpmsg() will fail if the stream head had processed an asynchronous error before the call. In this case, the value of .CR errno does not reflect the result of .CR putmsg() or .CR putpmsg() but reflects the prior error. .SH SEE ALSO getmsg(2), poll(2), read(2), write(2), , streamio(7). .\" .\" index@\f4putmsg()\f1 \- send a message on a stream@@@\f3putmsg(2)\f1 .\" index@\f4putpmsg()\f1 \- send a message on a stream in different priority bands@@@\f3putmsg(2)\f1 .\" index@\f1STREAMS, send a message on a stream@@@\f3putmsg(2)\f1 .\" index@\f1send a message on a stream@@@\f3putmsg(2)\f1 .\" index@\f1message, send a message on a stream@@@\f3putmsg(2)\f1 .\" Main TOC entry .\" toc@\f3putmsg(2)\f1:\0\0\f4putmsg()\f1, \f4putpmsg()\f1@@@send a message on a stream .\" .\" toc@\f4putpmsg()\f1:\0\0send a message on a stream in different priority bands@@@\f1see \f3putmsg(2)\f1 .\" .\" links@putmsg.2 putpmsg.2 .\" .\" fileset_database@putmsg.2 STREAMS-MAN .\" $Header: quotactl.2,v 78.1 96/01/19 20:17:12 ssa Exp $ .TA q .TH quotactl 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME quotactl \- manipulate disk quotas .SH SYNOPSIS .C #include .PP .C "int quotactl(int cmd, const char *special, uid_t uid, void *addr);" .SH DESCRIPTION .C quotactl() manipulates disk quotas. .I cmd indicates a command to be applied to the user .SM ID .IR uid . Parameter .I special is a pointer to a null-terminated string containing the path name of the block special device for the file system being manipulated. The block special device must be mounted. The parameter .I addr is the address of an optional, command-specific, data structure which is copied in or out of the system. The interpretation of .I addr is explained with each command below: .RS .TP 15 .C Q_QUOTAON Turn on quotas for a file system. The parameter .I addr points to the path name of file containing the quotas for the file system. The quota file must exist; it is normally created using the .C quotacheck command (see .IR quotacheck (1M)). The .I uid parameter is ignored. This call is restricted to users having appropriate privileges. .TP .C Q_QUOTAOFF Turn off quotas for a file system. The .I addr and .I uid parameters are ignored. This call is restricted to the user with appropriate privileges. .TP .C Q_GETQUOTA Get disk quota limits and current usage for user .IR uid . .I addr is a pointer to a .C dqblk structure (defined in .CR ). Only users having appropriate privileges can get the quotas of a user other than himself. .TP .C Q_SETQUOTA Set disk quota limits and current usage of files and blocks for user .IR uid . Note .CR vxfs does not allow the current usage fields to be changed .I addr is a pointer to a .C dqblk structure (defined in .CR ). This call is restricted to users with appropriate privileges. .TP .C Q_SETQLIM Set disk quota limits for user .IR uid . The parameter .I addr is a pointer to a .C dqblk structure (defined in .CR ). This call is restricted to users with appropriate privileges. .TP .C Q_SYNC Update the on-disk copy of quota usages for a file system. If .I special is null, all file systems with active quotas are synced. The parameters .I addr and .I uid are ignored. .RE .SH RETURN VALUE Upon successful completion, .C quotactl() returns 0; otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C quotactl() fails when any of the following occurs: .RS .TP 15 .SM [ENOSYS] The kernel has not been configured with the disk quota subsystem. .TP .SM [EINVAL] The parameters .I cmd and/or .I uid are invalid. .TP .SM [ESRCH] No disc quota is found for the indicated user or quotas have not been turned on for this file system. .TP .SM [EPERM] The call is privileged and the calling process does not have appropriate privileges. .TP .SM [ENODEV] The parameter .I special contains a type of file system that does not support quotas. Currently, quotas are supported on .SM HFS and .SM VxFS file systems. .TP .SM [ENOTBLK] The parameter .I special is not a block device. .TP .SM [EACCES] .RC ( Q_QUOTAON ) The quota file pointed to by .I addr exists but is either not a regular file or is not on the file system pointed to by .IR special . .TP .SM [EBUSY] .C Q_QUOTAON attempted while another .C Q_QUOTAON or .C Q_QUOTAOFF is in progress. .TP .SM [ENOENT] The file specified by .I special or .I addr does not exist. .TP .SM [EFAULT] The .I addr or .I special parameter points to an invalid address. Reliable detection of this error is implementation-dependent. .TP .SM [EDQUOT] User's disk quota block limit has been reached for this file system. .RE .SH WARNINGS The .C quotactl() system call is incompatible with the 4.2/4.3\s-1BSD\s0 implementation of Melbourne quotas which uses a different system call interface and on-disk data structure. .SH AUTHOR .C quotactl() was developed by HP and Sun Microsystems, Inc. .SH SEE ALSO quota (1), edquota (1M), rquotad (1M), quotacheck (1M), quotaon (1M), mount (2), quota (5), quota (5). .\" .\" index@\f4quotactl()\fP \(mi manipulate disk quotas@@@\f3quotactl(2)\f1 .\" index@manipulate disk quotas@@@\f3quotactl(2)\f1 .\" index@disk quotas, manipulate@@@\f3quotactl(2)\f1 .\" index@quotas, manipulate disk@@@\f3quotactl(2)\f1 .\" .\" toc@\f3quotactl(2)\f1:\0\0\f4quotactl()\fP@@@manipulate disk quotas .\" .\" fileset_database@quotactl.2 PROGRAMING-MAN .\" $Header: kill.2,v 72.6 94/11/14 15:24:25 ssa Exp $ .TA k .TH kill 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME kill(), raise() \- send a signal to a process or a group of processes .SH SYNOPSIS .C "#include " .PP .C "int kill(pid_t pid, int sig);" .PP .C "int raise(int sig);" .SH DESCRIPTION The .CR kill() system call sends a signal to a process or a group of processes, as specified by .IR pid . The signal to be sent is specified by .I sig and is either one from the list given in .IR signal (2), or .CR 0 . .PP The .CR raise() system call sends a signal to the executing program. The signal to be sent is specified by .I sig and is either one from the list given in .IR signal (2), or .CR 0 . .PP If .I sig is .CR 0 (the null signal), error checking is performed but no signal is actually sent. This can be used to check the validity of .IR pid . .PP The real or effective user ID of the sending process must match the real or saved user ID of the receiving process unless the effective user ID of the sending process is a user who has appropriate privileges. .PP As a single special case, the continue signal .CR SIGCONT can be sent to any process that is a member of the same session as the sending process. .PP The value .CR KILL_ALL_OTHERS is defined in the file .CR and is guaranteed not to be the ID of any process in the system or the negation of the ID of any process in the system. .PP If .I pid is greater than zero and not equal to .CR KILL_ALL_OTHERS , .I sig is sent to the process whose process ID is equal to .IR pid . .I pid can equal .CR 1 unless .IR sig is .CR SIGKILL or .CR SIGSTOP . .PP If .I pid is .CR 0 , .I sig is sent to all processes excluding special system processes whose process group ID is equal to the process group ID of the sender. .PP If .I pid is .CR \-1 and the effective user ID of the sender is not a user who has appropriate privileges. .I sig is sent to all processes excluding special system processes whose real or saved user ID is equal to the real or effective user ID of the sender. .PP If .I pid is .CR \-1 and the effective user ID of the sender is a user who has appropriate privileges, .I sig is sent to all processes excluding special system processes. .PP If .I pid is .CR KILL_ALL_OTHERS , .CR kill() behaves much as when .I pid is equal to .CR \-1 , except that .I sig is not sent to the calling process. .PP If .I pid is negative but not .CR \-1 or .CR KILL_ALL_OTHERS , .I sig is sent to all processes (excluding special system processes) whose process group ID is equal to the absolute value of .IR pid , and whose real and/or effective user ID meets the constraints described above for matching user IDs. .SH RETURN VALUE Upon successful completion, a value of .CR 0 is returned. Otherwise, a value of .CR \-1 is returned and .CR errno is set to indicate the error. .SH ERRORS .PP If .CR kill() fails, no signal is sent. .CR errno is set to one of the following values. .RS .TP 15 [EINVAL] .I sig is neither a valid signal number nor zero. .TP [EINVAL] .I sig is .CR SIGKILL or .CR SIGSTOP and .I pid is .CR 1 (process 1). .TP [EPERM] The user ID of the sending process is not a user who has appropriate privileges and its real or effective user ID does not match the real or saved user ID of the receiving process. .TP [EPERM] The sending and receiving processes are not in the same session and the real or effective user ID does not match the real or saved user ID of the receiving process. .TP [ESRCH] No process or process group can be found corresponding to that specified by .IR pid . .RE .PP If .CR raise() fails, no signal is sent. .CR errno is set to one of the following values. .RS .TP 15 [EINVAL] .I sig is neither a valid signal number nor zero. .RE .SH AUTHOR .CR kill() was developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO kill(1), getpid(2), setsid(2), signal(2). .SH STANDARDS CONFORMANCE .CR kill() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR raise() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4kill()\f1 \- send signal to process or group of processes@@@\f3kill(2)\f1 .\" index@\f4raise()\f1 \- send signal to executing program@@@\f3kill(2)\f1 .\" index@\f1send signal to executing program@@@\f3kill(2)\f1 .\" index@\f1executing program, send signal@@@\f3kill(2)\f1 .\" index@\f1process or group of processes, send signal@@@\f3kill(2)\f1 .\" index@\f1group of processes, send signal@@@\f3kill(2)\f1 .\" index@\f1signal, send to process or group of processes@@@\f3kill(2)\f1 .\" index@\f1software signal, send to process or group of processes@@@\f3kill(2)\f1 .\" .\" toc@\f3kill(2)\f1:\0\0\f4kill()\f1, \f4raise()\f1@@@send a signal to a process or a group of processes .\" toc@\f4raise()\f1:\0\0send a signal to executing program@@@see \f3kill(2)\f1 .\" .\" links@kill.2 raise.2 .\" $Header: read.2,v 76.1 95/07/07 14:48:07 ssa Exp $ .TA r .TH read 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME read, readv \- read from file .SH SYNOPSIS .C "#include " .PP .C "ssize_t read(int fildes, void *buf, size_t nbyte);" .\" UX .PP .C "#include " .PP .C "ssize_t readv(int fildes, const struct iovec *iov, int iovcnt);" .\" ? .SH DESCRIPTION The .CR read() function attempts to read .IR nbyte bytes from the file associated with the open file descriptor, .IR fildes , into the buffer pointed to by .IR buf. .PP If .IR nbyte is 0, .CR read() will return 0 and have no other results. .PP On files that support seeking (for example, a regular file), the .CR read() starts at a position in the file given by the file offset associated with .IR fildes . The file offset is incremented by the number of bytes actually read. .PP Files that do not support seeking, for example, terminals, always read from the current position. The value of a file offset associated with such a file is undefined. .PP No data transfer will occur past the current end\- of-file. If the starting position is at or after the end\-of\-file, 0 will be returned. If the file refers to a device special file, the result of subsequent .CR read() requests is implementation\-dependent. .PP If the value of .IR nbyte is greater than .CR {SSIZE_MAX} the result is implementation\-dependent. .PP When attempting to read from an empty pipe or FIFO: .RS .TP 3 \(bu If no process has the pipe open for writing, .CR read() will return 0 to indicate end\-of\-file. .TP 3 \(bu If some process has the pipe open for writing and .CR O_NONBLOCK is set, .CR read() will return \(mi1 and set .CR errno to .CR EAGAIN . .TP 3 \(bu If some process has the pipe open for writing and .CR O_NONBLOCK is clear, .CR read() will block until some data is written or the pipe is closed by all processes that had the pipe open for writing. .RE .PP When attempting to read a file (other than a pipe or FIFO) that supports non\-blocking reads and has no data currently available: .RS .TP 3 \(bu If .CR O_NONBLOCK is set, .CR read() will return a \(mi1 and set .CR errno to .CR EAGAIN . .TP 3 \(bu If .CR O_NONBLOCK is clear, .CR read() will block until some data becomes available. .TP 3 \(bu The use of the .CR O_NONBLOCK flag has no effect if there is some data available. .RE .PP The .CR read() function reads data previously written to a file. If any portion of a regular file prior to the end\-of\-file has not been written, .CR read() returns bytes with value 0. For example, .CR lseek() allows the file offset to be set beyond the end of existing data in the file. If data is later written at this point, subsequent reads in the gap between the previous end of data and the newly written data will return bytes with value 0 until data is written into the gap. .PP Upon successful completion, where .IR nbyte is greater than 0, .CR read() will mark for update the .IR st_atime field of the file, and return the number of bytes read. This number will never be greater than .IR nbyte . The value returned may be less than .IR nbyte if the number of bytes left in the file is less than .IR nbyte , if the .CR read() request was interrupted by a signal, or if the file is a pipe or FIFO or special file and has fewer than .IR nbyte bytes immediately available for reading. For example, a .CR read() from a file associated with a terminal may return one typed line of data. .PP If a .CR read() is interrupted by a signal before it reads any data, it will return \(mi1 with .CR errno set to .CR [EINTR] . .\" FIPS .PP If a .CR read() is interrupted by a signal after it has successfully read some data, it will return the number of bytes read. .\" ? .\" UX .PP A .CR read() from a .CR STREAMS file can read data in three different modes: byte-stream mode, message\-ondiscard mode, and message\-discard mode. The default is byte\-stream mode. This can be changed using the .CR I_SRDOPT .CR ioctl() request, and can be tested with the .CR I_GRDOPT .CR ioctl() . In byte\-stream mode, .CR read() retrieves data from the .CR STREAM until as many bytes as were requested are transferred, or until there is no more data to be retrieved. Byte\-stream mode ignores message boundaries. .PP In .CR STREAMS message\-nondiscard mode, .CR read() retrieves data until as many bytes as were requested are transferred, or until a message boundary is reached. If .C read() does not retrieve all the data in a message, the remaining data is left on the .C STREAM , and can be retrieved by the next .CR read() call. Message\-discard mode also retrieves data until as many bytes as were requested are transferred, or a message boundary is reached. However, unread data remaining in a message after the .CR read() returns is discarded, and is not available for a subsequent .CR read() , .CR readv() , or .CR getmsg() call. .PP How .CR read() handles zero\-byte .CR STREAMS messages is determined by the current read mode setting. In byte\-stream mode, .CR read() accepts data until it has read .IR nbyte bytes, or until there is no more data to read, or until a zero\-byte message block is encountered. The .CR read() function then returns the number of bytes read, and places the zero\-byte message back on the .CR STREAM to be retrieved by the next .CR read() , .CR readv() , or .CR getmsg() . In message\-nondiscard mode or message\-discard mode, a zero\-byte message returns 0 and the message is removed from the .CR STREAM . When a zero\-byte message is read as the first message on a .CR STREAM , the message is removed from the .CR STREAM and 0 is returned, regardless of the read mode. .PP A .CR read() from a .CR STREAMS file returns the data in the message at the front of the .CR STREAM head read queue, regardless of the priority band of the message. .PP By default, .CR STREAM s are in control\-normal mode, in which a .CR read() from a .CR STREAMS file can only process messages that contain a data part but do not contain a control part. The .CR read() fails if a message containing a control part is encountered at the .CR STREAM head. This default action can be changed by placing the .CR STREAM in either control\-data mode or control\-discard mode with the .CR I_SRDOPT .CR ioctl() command. In control\-data mode, .CR read() converts any control part to data and passes it to the application before passing any data part originally present in the same message. In control\-discard mode, .CR read() discards message control parts but returns to the process any data part in the message. .PP In addition, .CR read() and .CR readv() will fail if the .CR STREAM head had processed an asynchronous error before the call. In this case, the value of .CR errno does not reflect the result of .CR read() or .CR readv() but reflects the prior error. If a hangup occurs on the .CR STREAM being read, .CR read() continues to operate normally until the .CR STREAM head read queue is empty. Thereafter, it returns 0. .\" ? .\" UX .PP The .CR readv() function is equivalent to .CR read() , but places the input data into the .IR iovcnt buffers specified by the members of the .IR iov array: .IR iov [ 0 ] , .IR iov [ 1 ] , .CR ... , .IR iov [ iovcnt \(mi1]. The .IR iovcnt argument is valid if greater than 0 and less than or equal to .CR {IOV_MAX} . .PP Each .IR iovec entry specifies the base address and length of an area in memory where data should be placed. The .CR readv() function always fills an area completely before proceeding to the next. .PP Upon successful completion, .CR readv() marks for update the .IR st_atime field of the file. .\" ? .SH RETURN VALUE Upon successful completion, .CR read() and .CR readv() return a non\-negative integer indicating the number of bytes actually read. Otherwise, the functions return \(mi1 and set .CR errno to indicate the error. .SH ERRORS .\" UX The .CR read() and .CR readv() functions will fail if: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor and the process .\" UX would be delayed in .CR read() or .CR readv() . .\" ? .TP [EBADF] The .IR fildes argument is not a valid file descriptor open for reading. .\" UX .TP [EBADMSG] The file is a .CR STREAM file that is set to control\-normal mode and the message waiting to be read includes a control part. .\" ? .TP [EINTR] The read operation was terminated due to the receipt of a signal, and no data was transferred. .\" UX .TP [EINVAL] The .CR STREAM or multiplexer referenced by .IR fildes is linked (directly or indirectly) downstream from a multiplexer. .TP [EIO] A physical I\/O error has occurred. .\" ? .TP [EIO] The process is a member of a background process attempting to read from its controlling terminal, the process is ignoring or blocking the .CR SIGTTIN signal or the process group is orphaned. This error may also be generated for implementation\-dependent reasons. .\" UX .TP [EISDIR] The .IR fildes argument refers to a directory and the implementation does not allow the directory to be read using .CR read() or .CR readv() . The .CR readdir() function should be used instead. .RE .PP The .CR readv() function will fail if: .RS .TP 15 [EINVAL] The sum of the .IR iov_len values in the .IR iov array overflowed an .IR ssize_t . .\" ? .\" UX .RE .PP The .CR read() .\" ! and .CR readv() functions may fail if: .RS .TP 15 .\" EX [ENXIO] A request was made of a non\-existent device, or the request was outside the capabilities of the device. .\" ? .\" UX .RE .PP The .CR readv() function may fail if: .RS .TP 15 [EINVAL] The .CR iovcnt argument was less than or equal to 0, or greater than .CR {IOV_MAX} . .\" ? .SH SEE ALSO fcntl(), ioctl(), lseek(), open(), pipe(), , , , XBD Specification, Chapter 9, General Terminal Interface. .SH CHANGE HISTORY First released in Issue 1. .PP Derived from Issue 1 of the SVID. .SH Issue 4 .PP The following changes are incorporated for alignment with the ISO POSIX\-1 standard: .RS .TP 3 \(bu The type of the argument .IR buf is changed from .I char * .R to .IR void* , and the type of the argument .IR nbyte is changed from unsigned to .IR size_t . .TP 3 \(bu The DESCRIPTION section now states that the result is implementation\-dependentif .IR nbyte is greater than .CR {SSIZE_MAX} . This limit was defined by the constant .CR {INT_MAX} in Issue 3. .RE .PP The following change is incorporated for alignment with the FIPS requirements: .RS .TP 3 \(bu The last paragraph of the DESCRIPTION section now states that if .CR read() is interrupted by a signal after it has successfully read some data, it will return the number of bytes read. In Issue 3 it was optional whether .CR read() returned the number of bytes read, or whether it returned \(mi1 with .CR errno set to .CR EINTR . .RE .PP Other changes are incorporated as follows: .RS .TP 3 \(bu The header .CR is added to the SYNOPSIS section. .TP 3 \(bu The DESCRIPTION section is rearranged for clarity and to align more closely with the ISO POSIX\-1 standard. No functional changes are made other than as noted elsewhere in this CHANGE HISTORY section. .TP 3 \(bu In the ERRORS section in previous issues, generation of the .CR EIO error depended on whether or not an implementation supported Job Control. This functionality is now defined as mandatory. .TP 3 \(bu The .CR ENXIO error is marked as an extension. .TP 3 \(bu The APPLICATION USAGE section is removed. .TP 3 \(bu The description of .CR EINTR is amended. .RE .SH Issue 4, Version 2 .PP The following changes are incorporated for X\/OPEN UNIX conformance: .RS .TP 3 \(bu The .CR readv() function is added to the SYNOPSIS. .TP 3 \(bu The DESCRIPTION is updated to describe the reading of data from .CR STREAMS files. An operational description of the .CR readv() function is also added. .TP 3 \(bu References to the .CR readv() function are added to the RETURN VALUE and ERRORS sections in appropriate places. .TP 3 \(bu The ERRORS section has been restructured to describe errors that apply generally (that is, to both .CR read() and .CR readv() ), and to describe those that apply to .CR readv() specifically. The .CR EBADMSG , .CR EINVAL , and .CR EISDIR errors are also added. .RE .\" $Header: read.2,v 76.1 95/07/07 14:48:07 ssa Exp $ .TA r .TH read 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP-\UX EXTENSIONS .sp 2 .SH DESCRIPTION For .CR readv() , the .C iovec structure is defined as: .nf .IP .C struct iovec { .C " caddr_t iov_base;" .C " int iov_len;" .C }; .fi .PP For ordinary files, if the .CR O_RSYNC | O_DSYNC file status flag is set, the calling process blocks until the data being read and all file attributes required to retrieve the data are the same as their image on disk. Writes pending on the data to be read are executed before returning to the calling process. If the .CR O_RSYNC | O_SYNC file status flag is set, the behavior is identical to that for .CR O_RSYNC | O_DSYNC with this addition: all file attributes changed by the read operation (including access time, modification time and status change time) must also be the same as their image on disk. For block special files, if either the .CR O_RSYNC | O_DSYNC or .CR O_RSYNC | O_SYNC status flag is set, the calling process blocks until the data being read is an image of the data on the disk. Writes pending on the data to be read are executed before returning to the calling process. .PP When attempting to read from a regular file with enforcement-mode file and record locking set (see .IR chmod (2)), and the segment of the file to be read is blocked by a write lock owned by another process, the behavior is determined by the .C O_NDELAY and .C O_NONBLOCK file status flags: .RS .TP 3 \(bu If .C O_NDELAY or .C O_NONBLOCK is set, .C read() returns \(mi1 and .C errno is set to .SM [EAGAIN]. .TP \(bu If .C O_NDELAY and .C O_NONBLOCK are clear, .C read() does not return until the blocking write lock is removed. .RE .PP When attempting to read from an empty pipe (or FIFO): .RS .TP 3 \(bu If no process has the pipe open for writing, the read returns a 0. .TP \(bu If some process has the pipe open for writing and .C O_NONBLOCK is set, the read returns \(mi1 and .C errno is set to .SM [EAGAIN]. .TP \(bu If .C O_NDELAY is set, the read returns a 0. .TP \(bu If some process has the pipe open for writing and .C O_NDELAY and .C O_NONBLOCK are clear, the read blocks until data is written to the file or the file is no longer open for writing. .RE .PP When attempting to read a file associated with a tty that has no data currently available: .RS .TP 3 \(bu If .C O_NDELAY is set, the read returns 0. .TP \(bu If .C O_NDELAY and .C O_NONBLOCK are clear, the read blocks until data becomes available. .RE .PP .SH RETURN VALUE Upon successful completion, .C read() returns the number of bytes actually read and placed in the buffer; this number may be less than .I nbyte if: .RS .TP 3 \(bu The file is associated with a communication line (see .IR ioctl (2) and .IR termio (7)), or .TP \(bu The number of bytes left in the file is less than .I nbyte bytes. .TP \(bu .C read() was interrupted by a signal after it had successfully read some, but not all of the data requested. .RE .PP When an end-of-file is reached, a value of 0 is returned. Otherwise, a \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .C read() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EBADF] .I fildes is not a valid file descriptor open for reading. .TP .SM [EINTR] A signal was caught before any data was transferred (see .IR sigvector (2)). .TP .SM [EAGAIN] Enforcement-mode file and record locking is set, .C O_NDELAY or .C O_NONBLOCK is set, and there is a blocking write lock. .TP .SM [EDEADLK] A resource deadlock would occur as a result of this operation (see .IR lockf (2) and .IR fcntl (2)). .TP .SM [EFAULT] .I buf points outside the allocated address space. Reliable detection of this error is implementation dependent. .TP .SM [ENOLCK] The system record lock table is full, preventing the read from sleeping until the blocking write lock is removed. .RE .PP In addition, .C readv() can return one of the following errors: .RS .TP 15 .SM [EFAULT] .I iov_base or .I iov points outside of the allocated address space. The reliable detection of this error is implementation\-dependent. .RE .SH EXAMPLES Assuming a process opened a file for reading, the following call to .IR read (2) reads .C BUFSIZ bytes from the file into the buffer pointed to by .IR mybuf : .nf .IP .C "#include /* include this for BUFSIZ definition */" .IP .C "char mybuf[BUFSIZ];" .C int nbytes, fildes; .IP .C "nbytes = read (fildes, mybuf, BUFSIZ);" .SH WARNINGS Record locking might not be enforced by the system, depending on the setting of the file's mode bits (see .IR lockf (2)). .PP Character-special devices, and raw disks in particular, apply constraints on how .C read() can be used. See the specific Section (7) entries for details on particular devices. .PP Check all references to .IR signal (5) for appropriateness on systems that support .IR sigvector (2). .CR sigvector() can affect the behavior described on this page. .PP In general, avoid using .C read() to get the contents of a directory; use the .C readdir() library routine (see .IR directory (3C)). .SH DEPENDENCIES .SS NFS When obtaining the contents of a directory on an NFS file system, the .C readdir() library routine must be used (see .IR directory (3C)). .C read() returns with an error if used to read a directory using NFS. .SH AUTHOR .C read() was developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO creat(2), dup(2), fcntl(2), ioctl(2), lockf(2), open(2), pipe(2), select(2), ustat(2), tty(7), directory(3C). .SH STANDARDS CONFORMANCE .CR read() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.4" .\" .\" index@\f4read()\f1 \- read contiguous data from a file@@@\f3read(2)\f1 .\" index@\f4readv()\f1 \- read noncontiguous data from a file@@@\f3read(2)\f1 .\" index@\f1data from a file, read@@@\f3read(2)\f1 .\" index@\f1file, read data from@@@\f3read(2)\f1 .\" .\" toc@\f3read(2)\f1:\0\0\f4read()\f1, \f4readv()\f1@@@read input .\" toc@\f4readv()\f1:\0\0read input@@@see \f3read(2)\f1 .\" .\" links@read.2 readv.2 .\" $Header: readlink.2,v 76.1 95/07/07 14:48:27 ssa Exp $ .TA r .TH readlink 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME readlink() \- read the contents of a symbolic link .SH SYNOPSIS .nf .C "#include .PP .C "int readlink(" .C " const char *path," .C " char *buf," .C " size_t bufsiz" .C ");" .fi .SH DESCRIPTION The .CR readlink() function places the contents of the symbolic link referred to by path in the buffer .IR buf which has size .IR bufsiz . If the number of bytes in the symbolic link is less than .IR bufsiz , the contents of the remainder of .IR buf are unspecified. .SH RETURN VALUE Upon successful completion, .CR readlink() returns the count of bytes placed in the buffer. Otherwise, it returns a value of \(mi1, leaves the buffer unchanged, and sets .CR errno to indicate the error. .SH ERRORS The .CR readlink() function will fail if: .RS .TP 15 [EACCES] Search permission is denied for a component of the path prefix of path. .TP [EINVAL] The path argument names a file that is not a symbolic link. .TP [EIO] An I/O error occurred while reading from the file system. .TP [ENOENT] A component of path does not name an existing file or path is an empty string. .TP [ELOOP] Too many symbolic links were encountered in resolving path. .TP [ENAMETOOLONG] The length of path exceeds .CR PATH_MAX , or a pathname component is longer than .CR NAME_MAX . .TP [ENOTDIR] A component of the path prefix is not a directory. .RE .PP The .CR readlink() function may fail if: .RS .TP 15 [EACCES] Read permission is denied for the directory. .TP [ENAMETOOLONG] Pathname resolution of a symbolic link produced an intermediate result whose length exceeds .CR PATH_MAX. .SH APPLICATION USAGE Portable applications should not assume that the returned contents of the symbolic link are null- terminated. .SH SEE ALSO stat(), symlink(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" $Header: readlink.2,v 76.1 95/07/07 14:48:27 ssa Exp $ .TA r .TH readlink 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH SYNOPSIS .nf .C "#include .fi .SH DESCRIPTION If the length of the path name string is less than .IR bufsiz , the string will be null-terminated when returned. If the length of the path name string is exactly .IR bufsiz , the string will not be null-terminated when returned. .SH ERRORS .RS .TP 15 [EACCES] Search permission is denied for a component of the path prefix. .TP [EFAULT] .I buf or .I path points outside the process's allocated address space. Reliable detection of this error is implementation-dependent. .TP [ENAMETOOLONG] A component of .I path exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect, or .I path exceeds .CR PATH_MAX bytes. .RE .SH AUTHOR .CR readlink() was developed by the University of California, Berkeley. .SH SEE ALSO stat(2), symlink(2), symlink(4). .SH STANDARDS CONFORMANCE .CR readlink() ": AES, SVID3" .\" .\" index@\f4readlink()\f1 \- read value of a symbolic link@@@\f3readlink(2)\f1 .\" index@\f1link, symbolic, read value of@@@\f3readlink(2)\f1 .\" index@\f1read value of a symbolic link@@@\f3readlink(2)\f1 .\" index@\f1value of a symbolic link, read@@@\f3readlink(2)\f1 .\" index@\f1symbolic link, read value of@@@\f3readlink(2)\f1 .\" .\" toc@\f3readlink(2)\f1:\0\0\f4readlink()\f1@@@read value of a symbolic link .\" $Header: read.2,v 76.1 95/07/07 14:48:07 ssa Exp $ .TA r .TH read 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME read, readv \- read from file .SH SYNOPSIS .C "#include " .PP .C "ssize_t read(int fildes, void *buf, size_t nbyte);" .\" UX .PP .C "#include " .PP .C "ssize_t readv(int fildes, const struct iovec *iov, int iovcnt);" .\" ? .SH DESCRIPTION The .CR read() function attempts to read .IR nbyte bytes from the file associated with the open file descriptor, .IR fildes , into the buffer pointed to by .IR buf. .PP If .IR nbyte is 0, .CR read() will return 0 and have no other results. .PP On files that support seeking (for example, a regular file), the .CR read() starts at a position in the file given by the file offset associated with .IR fildes . The file offset is incremented by the number of bytes actually read. .PP Files that do not support seeking, for example, terminals, always read from the current position. The value of a file offset associated with such a file is undefined. .PP No data transfer will occur past the current end\- of-file. If the starting position is at or after the end\-of\-file, 0 will be returned. If the file refers to a device special file, the result of subsequent .CR read() requests is implementation\-dependent. .PP If the value of .IR nbyte is greater than .CR {SSIZE_MAX} the result is implementation\-dependent. .PP When attempting to read from an empty pipe or FIFO: .RS .TP 3 \(bu If no process has the pipe open for writing, .CR read() will return 0 to indicate end\-of\-file. .TP 3 \(bu If some process has the pipe open for writing and .CR O_NONBLOCK is set, .CR read() will return \(mi1 and set .CR errno to .CR EAGAIN . .TP 3 \(bu If some process has the pipe open for writing and .CR O_NONBLOCK is clear, .CR read() will block until some data is written or the pipe is closed by all processes that had the pipe open for writing. .RE .PP When attempting to read a file (other than a pipe or FIFO) that supports non\-blocking reads and has no data currently available: .RS .TP 3 \(bu If .CR O_NONBLOCK is set, .CR read() will return a \(mi1 and set .CR errno to .CR EAGAIN . .TP 3 \(bu If .CR O_NONBLOCK is clear, .CR read() will block until some data becomes available. .TP 3 \(bu The use of the .CR O_NONBLOCK flag has no effect if there is some data available. .RE .PP The .CR read() function reads data previously written to a file. If any portion of a regular file prior to the end\-of\-file has not been written, .CR read() returns bytes with value 0. For example, .CR lseek() allows the file offset to be set beyond the end of existing data in the file. If data is later written at this point, subsequent reads in the gap between the previous end of data and the newly written data will return bytes with value 0 until data is written into the gap. .PP Upon successful completion, where .IR nbyte is greater than 0, .CR read() will mark for update the .IR st_atime field of the file, and return the number of bytes read. This number will never be greater than .IR nbyte . The value returned may be less than .IR nbyte if the number of bytes left in the file is less than .IR nbyte , if the .CR read() request was interrupted by a signal, or if the file is a pipe or FIFO or special file and has fewer than .IR nbyte bytes immediately available for reading. For example, a .CR read() from a file associated with a terminal may return one typed line of data. .PP If a .CR read() is interrupted by a signal before it reads any data, it will return \(mi1 with .CR errno set to .CR [EINTR] . .\" FIPS .PP If a .CR read() is interrupted by a signal after it has successfully read some data, it will return the number of bytes read. .\" ? .\" UX .PP A .CR read() from a .CR STREAMS file can read data in three different modes: byte-stream mode, message\-ondiscard mode, and message\-discard mode. The default is byte\-stream mode. This can be changed using the .CR I_SRDOPT .CR ioctl() request, and can be tested with the .CR I_GRDOPT .CR ioctl() . In byte\-stream mode, .CR read() retrieves data from the .CR STREAM until as many bytes as were requested are transferred, or until there is no more data to be retrieved. Byte\-stream mode ignores message boundaries. .PP In .CR STREAMS message\-nondiscard mode, .CR read() retrieves data until as many bytes as were requested are transferred, or until a message boundary is reached. If .C read() does not retrieve all the data in a message, the remaining data is left on the .C STREAM , and can be retrieved by the next .CR read() call. Message\-discard mode also retrieves data until as many bytes as were requested are transferred, or a message boundary is reached. However, unread data remaining in a message after the .CR read() returns is discarded, and is not available for a subsequent .CR read() , .CR readv() , or .CR getmsg() call. .PP How .CR read() handles zero\-byte .CR STREAMS messages is determined by the current read mode setting. In byte\-stream mode, .CR read() accepts data until it has read .IR nbyte bytes, or until there is no more data to read, or until a zero\-byte message block is encountered. The .CR read() function then returns the number of bytes read, and places the zero\-byte message back on the .CR STREAM to be retrieved by the next .CR read() , .CR readv() , or .CR getmsg() . In message\-nondiscard mode or message\-discard mode, a zero\-byte message returns 0 and the message is removed from the .CR STREAM . When a zero\-byte message is read as the first message on a .CR STREAM , the message is removed from the .CR STREAM and 0 is returned, regardless of the read mode. .PP A .CR read() from a .CR STREAMS file returns the data in the message at the front of the .CR STREAM head read queue, regardless of the priority band of the message. .PP By default, .CR STREAM s are in control\-normal mode, in which a .CR read() from a .CR STREAMS file can only process messages that contain a data part but do not contain a control part. The .CR read() fails if a message containing a control part is encountered at the .CR STREAM head. This default action can be changed by placing the .CR STREAM in either control\-data mode or control\-discard mode with the .CR I_SRDOPT .CR ioctl() command. In control\-data mode, .CR read() converts any control part to data and passes it to the application before passing any data part originally present in the same message. In control\-discard mode, .CR read() discards message control parts but returns to the process any data part in the message. .PP In addition, .CR read() and .CR readv() will fail if the .CR STREAM head had processed an asynchronous error before the call. In this case, the value of .CR errno does not reflect the result of .CR read() or .CR readv() but reflects the prior error. If a hangup occurs on the .CR STREAM being read, .CR read() continues to operate normally until the .CR STREAM head read queue is empty. Thereafter, it returns 0. .\" ? .\" UX .PP The .CR readv() function is equivalent to .CR read() , but places the input data into the .IR iovcnt buffers specified by the members of the .IR iov array: .IR iov [ 0 ] , .IR iov [ 1 ] , .CR ... , .IR iov [ iovcnt \(mi1]. The .IR iovcnt argument is valid if greater than 0 and less than or equal to .CR {IOV_MAX} . .PP Each .IR iovec entry specifies the base address and length of an area in memory where data should be placed. The .CR readv() function always fills an area completely before proceeding to the next. .PP Upon successful completion, .CR readv() marks for update the .IR st_atime field of the file. .\" ? .SH RETURN VALUE Upon successful completion, .CR read() and .CR readv() return a non\-negative integer indicating the number of bytes actually read. Otherwise, the functions return \(mi1 and set .CR errno to indicate the error. .SH ERRORS .\" UX The .CR read() and .CR readv() functions will fail if: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor and the process .\" UX would be delayed in .CR read() or .CR readv() . .\" ? .TP [EBADF] The .IR fildes argument is not a valid file descriptor open for reading. .\" UX .TP [EBADMSG] The file is a .CR STREAM file that is set to control\-normal mode and the message waiting to be read includes a control part. .\" ? .TP [EINTR] The read operation was terminated due to the receipt of a signal, and no data was transferred. .\" UX .TP [EINVAL] The .CR STREAM or multiplexer referenced by .IR fildes is linked (directly or indirectly) downstream from a multiplexer. .TP [EIO] A physical I\/O error has occurred. .\" ? .TP [EIO] The process is a member of a background process attempting to read from its controlling terminal, the process is ignoring or blocking the .CR SIGTTIN signal or the process group is orphaned. This error may also be generated for implementation\-dependent reasons. .\" UX .TP [EISDIR] The .IR fildes argument refers to a directory and the implementation does not allow the directory to be read using .CR read() or .CR readv() . The .CR readdir() function should be used instead. .RE .PP The .CR readv() function will fail if: .RS .TP 15 [EINVAL] The sum of the .IR iov_len values in the .IR iov array overflowed an .IR ssize_t . .\" ? .\" UX .RE .PP The .CR read() .\" ! and .CR readv() functions may fail if: .RS .TP 15 .\" EX [ENXIO] A request was made of a non\-existent device, or the request was outside the capabilities of the device. .\" ? .\" UX .RE .PP The .CR readv() function may fail if: .RS .TP 15 [EINVAL] The .CR iovcnt argument was less than or equal to 0, or greater than .CR {IOV_MAX} . .\" ? .SH SEE ALSO fcntl(), ioctl(), lseek(), open(), pipe(), , , , XBD Specification, Chapter 9, General Terminal Interface. .SH CHANGE HISTORY First released in Issue 1. .PP Derived from Issue 1 of the SVID. .SH Issue 4 .PP The following changes are incorporated for alignment with the ISO POSIX\-1 standard: .RS .TP 3 \(bu The type of the argument .IR buf is changed from .I char * .R to .IR void* , and the type of the argument .IR nbyte is changed from unsigned to .IR size_t . .TP 3 \(bu The DESCRIPTION section now states that the result is implementation\-dependentif .IR nbyte is greater than .CR {SSIZE_MAX} . This limit was defined by the constant .CR {INT_MAX} in Issue 3. .RE .PP The following change is incorporated for alignment with the FIPS requirements: .RS .TP 3 \(bu The last paragraph of the DESCRIPTION section now states that if .CR read() is interrupted by a signal after it has successfully read some data, it will return the number of bytes read. In Issue 3 it was optional whether .CR read() returned the number of bytes read, or whether it returned \(mi1 with .CR errno set to .CR EINTR . .RE .PP Other changes are incorporated as follows: .RS .TP 3 \(bu The header .CR is added to the SYNOPSIS section. .TP 3 \(bu The DESCRIPTION section is rearranged for clarity and to align more closely with the ISO POSIX\-1 standard. No functional changes are made other than as noted elsewhere in this CHANGE HISTORY section. .TP 3 \(bu In the ERRORS section in previous issues, generation of the .CR EIO error depended on whether or not an implementation supported Job Control. This functionality is now defined as mandatory. .TP 3 \(bu The .CR ENXIO error is marked as an extension. .TP 3 \(bu The APPLICATION USAGE section is removed. .TP 3 \(bu The description of .CR EINTR is amended. .RE .SH Issue 4, Version 2 .PP The following changes are incorporated for X\/OPEN UNIX conformance: .RS .TP 3 \(bu The .CR readv() function is added to the SYNOPSIS. .TP 3 \(bu The DESCRIPTION is updated to describe the reading of data from .CR STREAMS files. An operational description of the .CR readv() function is also added. .TP 3 \(bu References to the .CR readv() function are added to the RETURN VALUE and ERRORS sections in appropriate places. .TP 3 \(bu The ERRORS section has been restructured to describe errors that apply generally (that is, to both .CR read() and .CR readv() ), and to describe those that apply to .CR readv() specifically. The .CR EBADMSG , .CR EINVAL , and .CR EISDIR errors are also added. .RE .\" $Header: read.2,v 76.1 95/07/07 14:48:07 ssa Exp $ .TA r .TH read 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP-\UX EXTENSIONS .sp 2 .SH DESCRIPTION For .CR readv() , the .C iovec structure is defined as: .nf .IP .C struct iovec { .C " caddr_t iov_base;" .C " int iov_len;" .C }; .fi .PP For ordinary files, if the .CR O_RSYNC | O_DSYNC file status flag is set, the calling process blocks until the data being read and all file attributes required to retrieve the data are the same as their image on disk. Writes pending on the data to be read are executed before returning to the calling process. If the .CR O_RSYNC | O_SYNC file status flag is set, the behavior is identical to that for .CR O_RSYNC | O_DSYNC with this addition: all file attributes changed by the read operation (including access time, modification time and status change time) must also be the same as their image on disk. For block special files, if either the .CR O_RSYNC | O_DSYNC or .CR O_RSYNC | O_SYNC status flag is set, the calling process blocks until the data being read is an image of the data on the disk. Writes pending on the data to be read are executed before returning to the calling process. .PP When attempting to read from a regular file with enforcement-mode file and record locking set (see .IR chmod (2)), and the segment of the file to be read is blocked by a write lock owned by another process, the behavior is determined by the .C O_NDELAY and .C O_NONBLOCK file status flags: .RS .TP 3 \(bu If .C O_NDELAY or .C O_NONBLOCK is set, .C read() returns \(mi1 and .C errno is set to .SM [EAGAIN]. .TP \(bu If .C O_NDELAY and .C O_NONBLOCK are clear, .C read() does not return until the blocking write lock is removed. .RE .PP When attempting to read from an empty pipe (or FIFO): .RS .TP 3 \(bu If no process has the pipe open for writing, the read returns a 0. .TP \(bu If some process has the pipe open for writing and .C O_NONBLOCK is set, the read returns \(mi1 and .C errno is set to .SM [EAGAIN]. .TP \(bu If .C O_NDELAY is set, the read returns a 0. .TP \(bu If some process has the pipe open for writing and .C O_NDELAY and .C O_NONBLOCK are clear, the read blocks until data is written to the file or the file is no longer open for writing. .RE .PP When attempting to read a file associated with a tty that has no data currently available: .RS .TP 3 \(bu If .C O_NDELAY is set, the read returns 0. .TP \(bu If .C O_NDELAY and .C O_NONBLOCK are clear, the read blocks until data becomes available. .RE .PP .SH RETURN VALUE Upon successful completion, .C read() returns the number of bytes actually read and placed in the buffer; this number may be less than .I nbyte if: .RS .TP 3 \(bu The file is associated with a communication line (see .IR ioctl (2) and .IR termio (7)), or .TP \(bu The number of bytes left in the file is less than .I nbyte bytes. .TP \(bu .C read() was interrupted by a signal after it had successfully read some, but not all of the data requested. .RE .PP When an end-of-file is reached, a value of 0 is returned. Otherwise, a \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .C read() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EBADF] .I fildes is not a valid file descriptor open for reading. .TP .SM [EINTR] A signal was caught before any data was transferred (see .IR sigvector (2)). .TP .SM [EAGAIN] Enforcement-mode file and record locking is set, .C O_NDELAY or .C O_NONBLOCK is set, and there is a blocking write lock. .TP .SM [EDEADLK] A resource deadlock would occur as a result of this operation (see .IR lockf (2) and .IR fcntl (2)). .TP .SM [EFAULT] .I buf points outside the allocated address space. Reliable detection of this error is implementation dependent. .TP .SM [ENOLCK] The system record lock table is full, preventing the read from sleeping until the blocking write lock is removed. .RE .PP In addition, .C readv() can return one of the following errors: .RS .TP 15 .SM [EFAULT] .I iov_base or .I iov points outside of the allocated address space. The reliable detection of this error is implementation\-dependent. .RE .SH EXAMPLES Assuming a process opened a file for reading, the following call to .IR read (2) reads .C BUFSIZ bytes from the file into the buffer pointed to by .IR mybuf : .nf .IP .C "#include /* include this for BUFSIZ definition */" .IP .C "char mybuf[BUFSIZ];" .C int nbytes, fildes; .IP .C "nbytes = read (fildes, mybuf, BUFSIZ);" .SH WARNINGS Record locking might not be enforced by the system, depending on the setting of the file's mode bits (see .IR lockf (2)). .PP Character-special devices, and raw disks in particular, apply constraints on how .C read() can be used. See the specific Section (7) entries for details on particular devices. .PP Check all references to .IR signal (5) for appropriateness on systems that support .IR sigvector (2). .CR sigvector() can affect the behavior described on this page. .PP In general, avoid using .C read() to get the contents of a directory; use the .C readdir() library routine (see .IR directory (3C)). .SH DEPENDENCIES .SS NFS When obtaining the contents of a directory on an NFS file system, the .C readdir() library routine must be used (see .IR directory (3C)). .C read() returns with an error if used to read a directory using NFS. .SH AUTHOR .C read() was developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO creat(2), dup(2), fcntl(2), ioctl(2), lockf(2), open(2), pipe(2), select(2), ustat(2), tty(7), directory(3C). .SH STANDARDS CONFORMANCE .CR read() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.4" .\" .\" index@\f4read()\f1 \- read contiguous data from a file@@@\f3read(2)\f1 .\" index@\f4readv()\f1 \- read noncontiguous data from a file@@@\f3read(2)\f1 .\" index@\f1data from a file, read@@@\f3read(2)\f1 .\" index@\f1file, read data from@@@\f3read(2)\f1 .\" .\" toc@\f3read(2)\f1:\0\0\f4read()\f1, \f4readv()\f1@@@read input .\" toc@\f4readv()\f1:\0\0read input@@@see \f3read(2)\f1 .\" .\" links@read.2 readv.2 .\" $Header: reboot.2,v 72.6 94/10/17 11:33:35 ssa Exp $ .TA r .TH reboot 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME reboot \- boot the system .SH SYNOPSIS .C "#include " .PP .C "int reboot (int howto); .SH DESCRIPTION .CR reboot() causes the system to reboot. .IR howto is a mask of reboot options (see .RC < sys/reboot.h >), specified as follows: .RS .TP 20 .C RB_AUTOBOOT A file system sync is performed (unless .CR RB_NOSYNC is set) and the processor is rebooted from the default device and file. .TP .C RB_HALT The processor is simply halted. A sync of the file system is performed unless the .CR RB_NOSYNC flag is set. .CR RB_HALT should be used with caution. .TP .C RB_NOSYNC A sync of the file system is not performed. .RE .PP Unless the .CR RB_NOSYNC flag has been specified, .IR reboot (2) unmounts all mounted file systems and marks them clean so that it will not be necessary to run .IR fsck (1M) on these file systems when the system reboots. .PP Only users with appropriate privileges can reboot a machine. .SH RETURN VALUE If successful, this call never returns. Otherwise, a \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS .CR reboot() fails if this condition is encountered: .RS .TP 20 [EPERM] The effective user ID of the caller is not a user with appropriate privileges. .RE .SH DEPENDENCIES The default file and device for .CR RB_AUTOBOOT is .CR /stand/vmunix on the current root device. .SH AUTHOR .CR reboot() was developed by HP and the University of California, Berkeley. .SH SEE ALSO reboot(1M), clusterconf(4). .\" index@\f4reboot()\fP \(mi boot the system@@@\f3reboot(2)\f1 .\" index@boot the system@@@\f3reboot(2)\f1 .\" index@system, boot@@@\f3reboot(2)\f1 .\" .\" toc@\f3reboot(2)\f1:\0\0\f4reboot()\fP@@@boot the system .\" .\" fileset_database@reboot.2 PROGRAMING-MAN .\" $Header: recv.2,v 78.3 96/03/15 16:44:00 ssa Exp $ 2 .TA r .TH recv 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME recv, recvfrom, recvmsg \- receive a message from a socket .SH SYNOPSIS .nf .C "#include " .PP .C "int recv(int s, void *buf, int len, int flags);" .PP .C "int recvfrom(" .C " int s," .C " void *buf," .C " int len," .C " int flags," .C " void *from," .C " int *fromlen" .C ");" .PP .C "int recvmsg(int s, struct msghdr msg[], int flags);" .fi .SS _XOPEN_SOURCE_EXTENDED only .SH .nf .C "ssize_t recv(int s, void *buf, size_t len, int flags);" .PP .C "ssize_t recvfrom(" .C " int s," .C " void *buf," .C " size_t len," .C " int flags," .C " struct sockaddr *from," .C " size_t *fromlen" .C ");" .PP .C "ssize_t recvmsg(int s, struct msghdr *msg, int flags);" .fi .SH DESCRIPTION The .CR recv() , .CR recvfrom() , and .CR recvmsg() system calls are used to receive messages from a socket. .PP .I s is a socket descriptor from which messages are received. .PP .I buf is a pointer to the buffer into which the messages are placed. .PP .I len is the maximum number of bytes that can fit in the buffer referenced by .IR buf . .PP If the socket uses connection-based communications, such as a SOCK_STREAM socket, these calls can only be used after the connection has been established (see .IR connect (2)). For connectionless sockets such as SOCK_DGRAM, these calls can be used whether a connection has been specified or not. .PP .CR recvfrom() operates in the same manner as .CR recv() except that it is able to return the address of the socket from which the message was sent. For connected datagram sockets, .CR recvfrom() simply returns the same address as .CR getpeername() (see .IR getpeername (2)). For stream sockets, .CR recvfrom() retrieves data in the same manner as .CR recv() , but does not return the socket address of the sender. If .I from is nonzero, the source address of the message is placed in the socket address structure pointed to by .IR from . .I fromlen is a value-result parameter, initialized to the size of the structure associated with .IR from , and modified on return to indicate the actual size of the address stored there. If the memory pointed to by .I from is not large enough to contain the entire address, only the first .I fromlen bytes of the address are returned. .PP For message-based sockets such as SOCK_DGRAM, the entire message must be read in a single operation. If a message is too long to fit in the supplied buffer, the excess bytes are discarded. For stream-based sockets such as SOCK_STREAM, there is no concept of message boundaries. In this case, data is returned to the user as soon as it becomes available, and no data is discarded. See the AF_CCITT Only subsection below for a list of the exceptions to this behavior for connections in the address family AF_CCITT. .PP .CR recvmsg() performs the same action as .CR recv() , but scatters the read data into the buffers specified in the .CR msghdr structure ( see .CR "_XOPEN_SOURCE_EXTENDED only" below ). This structure is defined in .CR , and has the following form : .nf .IP .CR "HP-UX BSD Sockets only" .PP .IP .C "struct msghdr {" .C " caddr_t msg_name; /* optional address */" .C " int msg_namelen; /* size of address */" .C " struct iovec *msg_iov; /* scatter array for data */" .C " int msg_iovlen; /* # of elements in msg_iov */" .C " caddr_t msg_accrights; /* access rights */" .C " int msg_accrightslen; /* size of msg_accrights */" .C "}" .fi .PP .I msg_name points to a .CR sockaddr structure in which the address of the sending socket is to be stored, if the socket is connectionless; .I msg_name may be a null pointer if no name is specified. .I msg_iov specifies the locations of the character arrays for storing the incoming data. .I msg_accrights specifies a buffer to receive any access rights sent along with the message. Access rights are limited to file descriptors of size .IR int . If access rights are not being transferred, set the .I msg_accrights field to NULL. Access rights are supported only for AF_UNIX. .PP If no data is available to be received, .CR recv() waits for a message to arrive unless nonblocking mode is enabled. There are three ways to enable nonblocking mode: .RS 2 .TP 3 .PD 0 \(bu With the .CR FIOSNBIO .CR ioctl() request .TP \(bu With the .CR O_NONBLOCK .CR fcntl() flag .TP \(bu With the .CR O_NDELAY .CR fcntl() flag .PD .RE .PP Although the use of .CR FIONBIO is not recommended, if nonblocking I/O is enabled using .CR FIOSNBIO or the equivalent .CR FIONBIO request (defined in .CR and explained in .IR ioctl (2), .IR ioctl (5) and .IR socket (7)), the .CR recv() request completes in one of three ways: .RS 2 .TP 3 \(bu If there is enough data available to satisfy the entire request, .CR recv() completes successfully, having read all of the data, and returns the number of bytes read. .TP \(bu If there is not enough data available to satisfy the entire request, .CR recv() complete successfully, having read as much data as possible, and returns the number of bytes it was able to read. .TP \(bu If there is no data available, .CR recv() fails and .CR errno is set to .RC [ EWOULDBLOCK ]. .RE .PP If nonblocking I/O is disabled using .CR FIOSNBIO , .CR recv() always executes completely (blocking as necessary) and returns the number of bytes read. .PP If the .CR O_NONBLOCK flag is set using .CR fcntl() (defined in .CR and explained in .IR fcntl (2) and .IR fcntl (5)), POSIX-style nonblocking I/O is enabled. In this case, the .CR recv() request completes in one of three ways: .RS 2 .TP 3 \(bu If there is enough data available to satisfy the entire request, .CR recv() completes successfully, having read all the data, and returns the number of bytes read. .TP \(bu If there is not enough data available to satisfy the entire request, .CR recv() completes successfully, having read as much data as possible, and returns the number of bytes it was able to read. .TP \(bu If there is no data available, .CR recv() completes, having read no data, and returns \(mi1 with .CR errno set to [EAGAIN]. .RE .PP If the .CR O_NDELAY flag is set using .CR fcntl() (defined in .CR and explained in .IR fcntl (2) and .IR fcntl (5)), nonblocking I/O is enabled. In this case, the .CR recv() request completes in one of three ways: .RS 2 .TP 3 \(bu If there is enough data available to satisfy the entire request, .CR recv() completes successfully, having read all the data, and returns the number of bytes read. .TP \(bu If there is not enough data available to satisfy the entire request, .CR recv() completes successfully, having read as much data as possible, and returns the number of bytes it was able to read. .TP \(bu If there is no data available, .CR recv() completes successfully, having read no data, and returns 0. .RE .PP If the .CR O_NONBLOCK or .CR O_NDELAY flag is cleared using .CR fcntl() , the corresponding style of nonblocking I/O, if previously enabled, is disabled. In this case, .CR recv() always executes completely (blocking as necessary) and returns the number of bytes read. .PP Since both the .CR fcntl() .CR O_NONBLOCK and .CR O_NDELAY flags and .CR ioctl() .CR FIOSNBIO request are supported, some clarification on how these features interact is necessary. If the .C O_NONBLOCK or .C O_NDELAY flag has been set, .C recv() requests behave accordingly, regardless of any .C FIOSNBIO requests. If neither the .C O_NONBLOCK flag nor the .C O_NDELAY flag has been set, .C FIOSNBIO requests control the the behavior of .C recv() . .PP By default nonblocking I/O is disabled. .PP .CR select() can be used to determine when more data arrives by selecting the socket for reading. .PP The .I flags parameter can be set to .CR MSG_PEEK , .CR MSG_OOB , both, or zero. If it is set to .CR MSG_PEEK , any data returned to the user still is treated as if it had not been read. The next .CR recv() rereads the same data. The .CR MSG_OOB flag is used to receive out-of-band data. For TCP SOCK_STREAM sockets, both the .CR MSG_PEEK and .CR MSG_OOB flags can be set at the same time. The .CR MSG_OOB flag value is supported for TCP SOCK_STREAM sockets only. .CR MSG_OOB is not supported for AF_UNIX sockets. .PP A .CR read() call made to a socket behaves in exactly the same way as a .CR recv() with .I flags set to zero. .PP .SS AF_CCITT Only Connections in the address family AF_CCITT support message-based sockets only. Although the user specifies connection-based communications (SOCK_STREAM), the X.25 subsystem communicates via messages. This address family does not support SOCK_DGRAM socket types. .PP Normally, each .CR recv() returns one complete X.25 message. If the socket is in nonblocking mode, .CR recv() behaves as described above. Note that if the user specifies .I len less than the actual X.25 message size, the excess data is discarded and no error indication is returned. The size of the next available message as well as the state of MDTF, D, and Q bits can be obtained with .CR "ioctl(X25_NEXT_MSG_STAT)" . .PP Connections of the address family AF_CCITT receive data in the same way as message-based connections described above, with the following additions and exceptions: .RS 2 .TP 3 \(bu .CR recvfrom() is supported; however, the .I from and .I fromlen parameters are ignored (that is, it works in the same manner as .CR recv() ). .TP \(bu To receive a message in fragments of the complete X.25 message, use .CR ioctl(X25_SET_FRAGMENT_SIZE) . The state of the MDTF bit is 1 for all except the last fragment of the message. .TP \(bu The .CR MSG_OOB flag is supported. .TP \(bu The .CR MSG_PEEK flag is supported; the two flags can be combined. .TP \(bu If a message is received that is larger than the user-controlled maximum message size (see .IR af_ccitt (7F)), the X.25 subsystem RESETs the circuit, discards the data, and sends the out-of-band event .CR OOB_VC_MESSAGE_TOO_BIG to the socket. .RE .SH DEPENDENCIES .SS AF_CCITT .CR recvfrom() is supported; however, the .I from and .I fromlen parameters are ignored (i.e., it works in the same manner as .CR recv() ). .PP The .CR O_NDELAY .CR fcntl() call is not supported over X.25 links. Use the .CR FIOSNBIO .CR ioctl() call instead to enable nonblocking I/0. .SH _XOPEN_SOURCE_EXTENDED only .CR "X/Open Sockets msghdr" has the following form : .nf .IP .C "struct msghdr {" .C " void *msg_name; /* optional address */" .C " size_t msg_namelen; /* size of address */" .C " struct iovec *msg_iov; /* scatter array for data */" .C " int msg_iovlen; /* # of elements in msg_iov */" .C " void *msg_control; /* ancillary data, see below */" .C " size_t msg_controllen; /* ancillary data buffer len */" .C " int msg_flags; /* flags on received message */" .C "}" .fi .PP .I msg_control specifies a buffer to receive any ancillary data sent along with the message. Ancillary data consists of a sequence of pairs, each consisting of a .I cmsghdr structure followed by a data array. The data array contains the ancillary data message, and the .I cmsghdr structure contains descriptive information that allows an application to correctly parse the data. .I cmsghdr has the following structure: .nf .IP .C "struct cmsghdr {" .C " size_t cmsg_len; /* data byte count, including hdr*/" .C " int cmsg_level; /* originating protocol */" .C " int cmsg_type; /* protocol-specific type */" .C "}" .fi .PP The supported value for cmsg_level is SOL_SOCKET, and the supported value for cmsg_type is SCM_RIGHTS. Together they indicate that the data array contains the access rights to be received. Access rights are supported only for AF_UNIX. Access rights are limited to file descriptors of size .IR int . If ancillary data are not being transferred, set the .I msg_control field to NULL and set the .I msg_controllen field to 0. .PP The .I flags parameter accepts a new value, .CR MSG_WAITALL, which requests that the function block until the full amount of data requested can be returned. The function may return a smaller amount of data if a signal is caught, the connection is terminated, or an error is pending for the socket. On successful completion of recvmsg(), the .I msg_flags member of the message header is the bitwise-inclusive OR of all of the following flags that indicate conditions detected for the received message. .RS .TP 20 .CR MSG_EOR End of record was received(if supported by the protocol). .TP .CR MSG_OOB Out-of-band data was received. .TP .CR MSG_TRUNC Normal data was truncated. .TP .CR MSG_CTRUNC Control data was truncated. .SH RETURN VALUE .CR recv() , .CR recvfrom() , and .CR recvmsg() returns the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .IR n is the number of bytes received. .TP .CR \00 The socket is blocking and the transport connection to the remote node failed. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR recv() , .CR recvfrom() , or .CR recvmsg() fails, .CR errno is set to one of the following values. .RS .TP 20 [EAGAIN] Non-blocking I/O is enabled using .CR O_NONBLOCK flag with .CR fcntl() and the receive operation would block, or the socket has an error that was set asynchronously. An asynchronous error can be caused by a gateway failing to forward a datagram because the datagram exceeds the MTU of the next-hop network and the "Don't Fragment" (DF) bit in the datagram is set. (See .CR SO_PMTU in .IR getsockopt (2).) .TP [EBADF] The argument .I s is an invalid descriptor. .TP [ECONNRESET] A connection was forcibly closed by a peer. .TP [EFAULT] An invalid pointer was specified in the .I buf , .I from , or .I fromlen parameter, or in the msghdr structure. .TP [EINTR] The receive was interrupted by delivery of a signal before any data was available for the receive. .TP [EINVAL] The .I len parameter or a length in the msghdr structure is invalid; or no data is available on receive of out of band data. .TP [EMSGSIZE] A length in the msghdr structure is invalid. .TP [ENOBUFS] Insufficient resources were available in the system to perform the operation. .TP [ENOTCONN] Receive on a SOCK_STREAM socket that is not yet connected. .TP [ENOTSOCK] The argument .I s is a valid file descriptor, but it is not a socket. .TP [EOPNOTSUPP] The .CR MSG_OOB flag was set for a UDP SOCK_DGRAM message-based socket, or .CR MSG_OOB or .CR MSG_PEEK was set for any AF_UNIX socket. The .CR MSG_OOB flag is supported only for stream-based TCP SOCK_STREAM sockets. Neither .CR MSG_PEEK nor .CR MSG_OOB is supported for AF_UNIX sockets. .IP AF_CCITT only: .CR recv() was issued on a .CR listen() socket. .TP [ETIMEDOUT] The connection timed out during connection establishment, or due to a transmission timeout on active connection. .TP [EWOULDBLOCK] Non-blocking I/O is enabled using .CR ioctl() .CR FIOSNBIO request, and the requested operation would block. .RE .SH AUTHOR .CR recv() was developed by the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO getsockopt(2), read(2), select(2), send(2), socket(2), af_ccitt(7F), inet(7F), socket(7), socketx25(7), tcp(7P), udp(7P), unix(7P), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR recv() ": XPG4" .\" .\" index@\f1message from a socket, receive@@@\f3recv(2)\f1 .\" index@\f1receive message from a socket@@@\f3recv(2)\f1 .\" index@\f1socket, receive message from a@@@\f3recv(2)\f1 .\" index@\f4recv()\f1 \- receive message from a socket@@@\f3recv(2)\f1 .\" index@\f4recvfrom()\f1 \- receive message from a socket@@@\f3recv(2)\f1 .\" index@\f4recvmsg()\f1 \- receive message from a socket@@@\f3recv(2)\f1 .\" .\" links@recv.2 recvfrom.2 .\" links@recv.2 recvmsg.2 .\" .\" toc@\f3recv(2)\f1:\0\0\f4recv()\f1, \f4recvfrom()\f1, \f4recvmsg()\f1@@@receive message from a socket .\" toc@\f4recvfrom()\f1:\0\0receive message from a socket@@@see \f3recv(2)\f1 .\" toc@\f4recvmsg()\f1:\0\0receive message from a socket@@@see \f3recv(2)\f1 .\" $Header: recv.2,v 78.3 96/03/15 16:44:00 ssa Exp $ 2 .TA r .TH recv 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME recv, recvfrom, recvmsg \- receive a message from a socket .SH SYNOPSIS .nf .C "#include " .PP .C "int recv(int s, void *buf, int len, int flags);" .PP .C "int recvfrom(" .C " int s," .C " void *buf," .C " int len," .C " int flags," .C " void *from," .C " int *fromlen" .C ");" .PP .C "int recvmsg(int s, struct msghdr msg[], int flags);" .fi .SS _XOPEN_SOURCE_EXTENDED only .SH .nf .C "ssize_t recv(int s, void *buf, size_t len, int flags);" .PP .C "ssize_t recvfrom(" .C " int s," .C " void *buf," .C " size_t len," .C " int flags," .C " struct sockaddr *from," .C " size_t *fromlen" .C ");" .PP .C "ssize_t recvmsg(int s, struct msghdr *msg, int flags);" .fi .SH DESCRIPTION The .CR recv() , .CR recvfrom() , and .CR recvmsg() system calls are used to receive messages from a socket. .PP .I s is a socket descriptor from which messages are received. .PP .I buf is a pointer to the buffer into which the messages are placed. .PP .I len is the maximum number of bytes that can fit in the buffer referenced by .IR buf . .PP If the socket uses connection-based communications, such as a SOCK_STREAM socket, these calls can only be used after the connection has been established (see .IR connect (2)). For connectionless sockets such as SOCK_DGRAM, these calls can be used whether a connection has been specified or not. .PP .CR recvfrom() operates in the same manner as .CR recv() except that it is able to return the address of the socket from which the message was sent. For connected datagram sockets, .CR recvfrom() simply returns the same address as .CR getpeername() (see .IR getpeername (2)). For stream sockets, .CR recvfrom() retrieves data in the same manner as .CR recv() , but does not return the socket address of the sender. If .I from is nonzero, the source address of the message is placed in the socket address structure pointed to by .IR from . .I fromlen is a value-result parameter, initialized to the size of the structure associated with .IR from , and modified on return to indicate the actual size of the address stored there. If the memory pointed to by .I from is not large enough to contain the entire address, only the first .I fromlen bytes of the address are returned. .PP For message-based sockets such as SOCK_DGRAM, the entire message must be read in a single operation. If a message is too long to fit in the supplied buffer, the excess bytes are discarded. For stream-based sockets such as SOCK_STREAM, there is no concept of message boundaries. In this case, data is returned to the user as soon as it becomes available, and no data is discarded. See the AF_CCITT Only subsection below for a list of the exceptions to this behavior for connections in the address family AF_CCITT. .PP .CR recvmsg() performs the same action as .CR recv() , but scatters the read data into the buffers specified in the .CR msghdr structure ( see .CR "_XOPEN_SOURCE_EXTENDED only" below ). This structure is defined in .CR , and has the following form : .nf .IP .CR "HP-UX BSD Sockets only" .PP .IP .C "struct msghdr {" .C " caddr_t msg_name; /* optional address */" .C " int msg_namelen; /* size of address */" .C " struct iovec *msg_iov; /* scatter array for data */" .C " int msg_iovlen; /* # of elements in msg_iov */" .C " caddr_t msg_accrights; /* access rights */" .C " int msg_accrightslen; /* size of msg_accrights */" .C "}" .fi .PP .I msg_name points to a .CR sockaddr structure in which the address of the sending socket is to be stored, if the socket is connectionless; .I msg_name may be a null pointer if no name is specified. .I msg_iov specifies the locations of the character arrays for storing the incoming data. .I msg_accrights specifies a buffer to receive any access rights sent along with the message. Access rights are limited to file descriptors of size .IR int . If access rights are not being transferred, set the .I msg_accrights field to NULL. Access rights are supported only for AF_UNIX. .PP If no data is available to be received, .CR recv() waits for a message to arrive unless nonblocking mode is enabled. There are three ways to enable nonblocking mode: .RS 2 .TP 3 .PD 0 \(bu With the .CR FIOSNBIO .CR ioctl() request .TP \(bu With the .CR O_NONBLOCK .CR fcntl() flag .TP \(bu With the .CR O_NDELAY .CR fcntl() flag .PD .RE .PP Although the use of .CR FIONBIO is not recommended, if nonblocking I/O is enabled using .CR FIOSNBIO or the equivalent .CR FIONBIO request (defined in .CR and explained in .IR ioctl (2), .IR ioctl (5) and .IR socket (7)), the .CR recv() request completes in one of three ways: .RS 2 .TP 3 \(bu If there is enough data available to satisfy the entire request, .CR recv() completes successfully, having read all of the data, and returns the number of bytes read. .TP \(bu If there is not enough data available to satisfy the entire request, .CR recv() complete successfully, having read as much data as possible, and returns the number of bytes it was able to read. .TP \(bu If there is no data available, .CR recv() fails and .CR errno is set to .RC [ EWOULDBLOCK ]. .RE .PP If nonblocking I/O is disabled using .CR FIOSNBIO , .CR recv() always executes completely (blocking as necessary) and returns the number of bytes read. .PP If the .CR O_NONBLOCK flag is set using .CR fcntl() (defined in .CR and explained in .IR fcntl (2) and .IR fcntl (5)), POSIX-style nonblocking I/O is enabled. In this case, the .CR recv() request completes in one of three ways: .RS 2 .TP 3 \(bu If there is enough data available to satisfy the entire request, .CR recv() completes successfully, having read all the data, and returns the number of bytes read. .TP \(bu If there is not enough data available to satisfy the entire request, .CR recv() completes successfully, having read as much data as possible, and returns the number of bytes it was able to read. .TP \(bu If there is no data available, .CR recv() completes, having read no data, and returns \(mi1 with .CR errno set to [EAGAIN]. .RE .PP If the .CR O_NDELAY flag is set using .CR fcntl() (defined in .CR and explained in .IR fcntl (2) and .IR fcntl (5)), nonblocking I/O is enabled. In this case, the .CR recv() request completes in one of three ways: .RS 2 .TP 3 \(bu If there is enough data available to satisfy the entire request, .CR recv() completes successfully, having read all the data, and returns the number of bytes read. .TP \(bu If there is not enough data available to satisfy the entire request, .CR recv() completes successfully, having read as much data as possible, and returns the number of bytes it was able to read. .TP \(bu If there is no data available, .CR recv() completes successfully, having read no data, and returns 0. .RE .PP If the .CR O_NONBLOCK or .CR O_NDELAY flag is cleared using .CR fcntl() , the corresponding style of nonblocking I/O, if previously enabled, is disabled. In this case, .CR recv() always executes completely (blocking as necessary) and returns the number of bytes read. .PP Since both the .CR fcntl() .CR O_NONBLOCK and .CR O_NDELAY flags and .CR ioctl() .CR FIOSNBIO request are supported, some clarification on how these features interact is necessary. If the .C O_NONBLOCK or .C O_NDELAY flag has been set, .C recv() requests behave accordingly, regardless of any .C FIOSNBIO requests. If neither the .C O_NONBLOCK flag nor the .C O_NDELAY flag has been set, .C FIOSNBIO requests control the the behavior of .C recv() . .PP By default nonblocking I/O is disabled. .PP .CR select() can be used to determine when more data arrives by selecting the socket for reading. .PP The .I flags parameter can be set to .CR MSG_PEEK , .CR MSG_OOB , both, or zero. If it is set to .CR MSG_PEEK , any data returned to the user still is treated as if it had not been read. The next .CR recv() rereads the same data. The .CR MSG_OOB flag is used to receive out-of-band data. For TCP SOCK_STREAM sockets, both the .CR MSG_PEEK and .CR MSG_OOB flags can be set at the same time. The .CR MSG_OOB flag value is supported for TCP SOCK_STREAM sockets only. .CR MSG_OOB is not supported for AF_UNIX sockets. .PP A .CR read() call made to a socket behaves in exactly the same way as a .CR recv() with .I flags set to zero. .PP .SS AF_CCITT Only Connections in the address family AF_CCITT support message-based sockets only. Although the user specifies connection-based communications (SOCK_STREAM), the X.25 subsystem communicates via messages. This address family does not support SOCK_DGRAM socket types. .PP Normally, each .CR recv() returns one complete X.25 message. If the socket is in nonblocking mode, .CR recv() behaves as described above. Note that if the user specifies .I len less than the actual X.25 message size, the excess data is discarded and no error indication is returned. The size of the next available message as well as the state of MDTF, D, and Q bits can be obtained with .CR "ioctl(X25_NEXT_MSG_STAT)" . .PP Connections of the address family AF_CCITT receive data in the same way as message-based connections described above, with the following additions and exceptions: .RS 2 .TP 3 \(bu .CR recvfrom() is supported; however, the .I from and .I fromlen parameters are ignored (that is, it works in the same manner as .CR recv() ). .TP \(bu To receive a message in fragments of the complete X.25 message, use .CR ioctl(X25_SET_FRAGMENT_SIZE) . The state of the MDTF bit is 1 for all except the last fragment of the message. .TP \(bu The .CR MSG_OOB flag is supported. .TP \(bu The .CR MSG_PEEK flag is supported; the two flags can be combined. .TP \(bu If a message is received that is larger than the user-controlled maximum message size (see .IR af_ccitt (7F)), the X.25 subsystem RESETs the circuit, discards the data, and sends the out-of-band event .CR OOB_VC_MESSAGE_TOO_BIG to the socket. .RE .SH DEPENDENCIES .SS AF_CCITT .CR recvfrom() is supported; however, the .I from and .I fromlen parameters are ignored (i.e., it works in the same manner as .CR recv() ). .PP The .CR O_NDELAY .CR fcntl() call is not supported over X.25 links. Use the .CR FIOSNBIO .CR ioctl() call instead to enable nonblocking I/0. .SH _XOPEN_SOURCE_EXTENDED only .CR "X/Open Sockets msghdr" has the following form : .nf .IP .C "struct msghdr {" .C " void *msg_name; /* optional address */" .C " size_t msg_namelen; /* size of address */" .C " struct iovec *msg_iov; /* scatter array for data */" .C " int msg_iovlen; /* # of elements in msg_iov */" .C " void *msg_control; /* ancillary data, see below */" .C " size_t msg_controllen; /* ancillary data buffer len */" .C " int msg_flags; /* flags on received message */" .C "}" .fi .PP .I msg_control specifies a buffer to receive any ancillary data sent along with the message. Ancillary data consists of a sequence of pairs, each consisting of a .I cmsghdr structure followed by a data array. The data array contains the ancillary data message, and the .I cmsghdr structure contains descriptive information that allows an application to correctly parse the data. .I cmsghdr has the following structure: .nf .IP .C "struct cmsghdr {" .C " size_t cmsg_len; /* data byte count, including hdr*/" .C " int cmsg_level; /* originating protocol */" .C " int cmsg_type; /* protocol-specific type */" .C "}" .fi .PP The supported value for cmsg_level is SOL_SOCKET, and the supported value for cmsg_type is SCM_RIGHTS. Together they indicate that the data array contains the access rights to be received. Access rights are supported only for AF_UNIX. Access rights are limited to file descriptors of size .IR int . If ancillary data are not being transferred, set the .I msg_control field to NULL and set the .I msg_controllen field to 0. .PP The .I flags parameter accepts a new value, .CR MSG_WAITALL, which requests that the function block until the full amount of data requested can be returned. The function may return a smaller amount of data if a signal is caught, the connection is terminated, or an error is pending for the socket. On successful completion of recvmsg(), the .I msg_flags member of the message header is the bitwise-inclusive OR of all of the following flags that indicate conditions detected for the received message. .RS .TP 20 .CR MSG_EOR End of record was received(if supported by the protocol). .TP .CR MSG_OOB Out-of-band data was received. .TP .CR MSG_TRUNC Normal data was truncated. .TP .CR MSG_CTRUNC Control data was truncated. .SH RETURN VALUE .CR recv() , .CR recvfrom() , and .CR recvmsg() returns the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .IR n is the number of bytes received. .TP .CR \00 The socket is blocking and the transport connection to the remote node failed. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR recv() , .CR recvfrom() , or .CR recvmsg() fails, .CR errno is set to one of the following values. .RS .TP 20 [EAGAIN] Non-blocking I/O is enabled using .CR O_NONBLOCK flag with .CR fcntl() and the receive operation would block, or the socket has an error that was set asynchronously. An asynchronous error can be caused by a gateway failing to forward a datagram because the datagram exceeds the MTU of the next-hop network and the "Don't Fragment" (DF) bit in the datagram is set. (See .CR SO_PMTU in .IR getsockopt (2).) .TP [EBADF] The argument .I s is an invalid descriptor. .TP [ECONNRESET] A connection was forcibly closed by a peer. .TP [EFAULT] An invalid pointer was specified in the .I buf , .I from , or .I fromlen parameter, or in the msghdr structure. .TP [EINTR] The receive was interrupted by delivery of a signal before any data was available for the receive. .TP [EINVAL] The .I len parameter or a length in the msghdr structure is invalid; or no data is available on receive of out of band data. .TP [EMSGSIZE] A length in the msghdr structure is invalid. .TP [ENOBUFS] Insufficient resources were available in the system to perform the operation. .TP [ENOTCONN] Receive on a SOCK_STREAM socket that is not yet connected. .TP [ENOTSOCK] The argument .I s is a valid file descriptor, but it is not a socket. .TP [EOPNOTSUPP] The .CR MSG_OOB flag was set for a UDP SOCK_DGRAM message-based socket, or .CR MSG_OOB or .CR MSG_PEEK was set for any AF_UNIX socket. The .CR MSG_OOB flag is supported only for stream-based TCP SOCK_STREAM sockets. Neither .CR MSG_PEEK nor .CR MSG_OOB is supported for AF_UNIX sockets. .IP AF_CCITT only: .CR recv() was issued on a .CR listen() socket. .TP [ETIMEDOUT] The connection timed out during connection establishment, or due to a transmission timeout on active connection. .TP [EWOULDBLOCK] Non-blocking I/O is enabled using .CR ioctl() .CR FIOSNBIO request, and the requested operation would block. .RE .SH AUTHOR .CR recv() was developed by the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO getsockopt(2), read(2), select(2), send(2), socket(2), af_ccitt(7F), inet(7F), socket(7), socketx25(7), tcp(7P), udp(7P), unix(7P), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR recv() ": XPG4" .\" .\" index@\f1message from a socket, receive@@@\f3recv(2)\f1 .\" index@\f1receive message from a socket@@@\f3recv(2)\f1 .\" index@\f1socket, receive message from a@@@\f3recv(2)\f1 .\" index@\f4recv()\f1 \- receive message from a socket@@@\f3recv(2)\f1 .\" index@\f4recvfrom()\f1 \- receive message from a socket@@@\f3recv(2)\f1 .\" index@\f4recvmsg()\f1 \- receive message from a socket@@@\f3recv(2)\f1 .\" .\" links@recv.2 recvfrom.2 .\" links@recv.2 recvmsg.2 .\" .\" toc@\f3recv(2)\f1:\0\0\f4recv()\f1, \f4recvfrom()\f1, \f4recvmsg()\f1@@@receive message from a socket .\" toc@\f4recvfrom()\f1:\0\0receive message from a socket@@@see \f3recv(2)\f1 .\" toc@\f4recvmsg()\f1:\0\0receive message from a socket@@@see \f3recv(2)\f1 .\" $Header: recv.2,v 78.3 96/03/15 16:44:00 ssa Exp $ 2 .TA r .TH recv 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME recv, recvfrom, recvmsg \- receive a message from a socket .SH SYNOPSIS .nf .C "#include " .PP .C "int recv(int s, void *buf, int len, int flags);" .PP .C "int recvfrom(" .C " int s," .C " void *buf," .C " int len," .C " int flags," .C " void *from," .C " int *fromlen" .C ");" .PP .C "int recvmsg(int s, struct msghdr msg[], int flags);" .fi .SS _XOPEN_SOURCE_EXTENDED only .SH .nf .C "ssize_t recv(int s, void *buf, size_t len, int flags);" .PP .C "ssize_t recvfrom(" .C " int s," .C " void *buf," .C " size_t len," .C " int flags," .C " struct sockaddr *from," .C " size_t *fromlen" .C ");" .PP .C "ssize_t recvmsg(int s, struct msghdr *msg, int flags);" .fi .SH DESCRIPTION The .CR recv() , .CR recvfrom() , and .CR recvmsg() system calls are used to receive messages from a socket. .PP .I s is a socket descriptor from which messages are received. .PP .I buf is a pointer to the buffer into which the messages are placed. .PP .I len is the maximum number of bytes that can fit in the buffer referenced by .IR buf . .PP If the socket uses connection-based communications, such as a SOCK_STREAM socket, these calls can only be used after the connection has been established (see .IR connect (2)). For connectionless sockets such as SOCK_DGRAM, these calls can be used whether a connection has been specified or not. .PP .CR recvfrom() operates in the same manner as .CR recv() except that it is able to return the address of the socket from which the message was sent. For connected datagram sockets, .CR recvfrom() simply returns the same address as .CR getpeername() (see .IR getpeername (2)). For stream sockets, .CR recvfrom() retrieves data in the same manner as .CR recv() , but does not return the socket address of the sender. If .I from is nonzero, the source address of the message is placed in the socket address structure pointed to by .IR from . .I fromlen is a value-result parameter, initialized to the size of the structure associated with .IR from , and modified on return to indicate the actual size of the address stored there. If the memory pointed to by .I from is not large enough to contain the entire address, only the first .I fromlen bytes of the address are returned. .PP For message-based sockets such as SOCK_DGRAM, the entire message must be read in a single operation. If a message is too long to fit in the supplied buffer, the excess bytes are discarded. For stream-based sockets such as SOCK_STREAM, there is no concept of message boundaries. In this case, data is returned to the user as soon as it becomes available, and no data is discarded. See the AF_CCITT Only subsection below for a list of the exceptions to this behavior for connections in the address family AF_CCITT. .PP .CR recvmsg() performs the same action as .CR recv() , but scatters the read data into the buffers specified in the .CR msghdr structure ( see .CR "_XOPEN_SOURCE_EXTENDED only" below ). This structure is defined in .CR , and has the following form : .nf .IP .CR "HP-UX BSD Sockets only" .PP .IP .C "struct msghdr {" .C " caddr_t msg_name; /* optional address */" .C " int msg_namelen; /* size of address */" .C " struct iovec *msg_iov; /* scatter array for data */" .C " int msg_iovlen; /* # of elements in msg_iov */" .C " caddr_t msg_accrights; /* access rights */" .C " int msg_accrightslen; /* size of msg_accrights */" .C "}" .fi .PP .I msg_name points to a .CR sockaddr structure in which the address of the sending socket is to be stored, if the socket is connectionless; .I msg_name may be a null pointer if no name is specified. .I msg_iov specifies the locations of the character arrays for storing the incoming data. .I msg_accrights specifies a buffer to receive any access rights sent along with the message. Access rights are limited to file descriptors of size .IR int . If access rights are not being transferred, set the .I msg_accrights field to NULL. Access rights are supported only for AF_UNIX. .PP If no data is available to be received, .CR recv() waits for a message to arrive unless nonblocking mode is enabled. There are three ways to enable nonblocking mode: .RS 2 .TP 3 .PD 0 \(bu With the .CR FIOSNBIO .CR ioctl() request .TP \(bu With the .CR O_NONBLOCK .CR fcntl() flag .TP \(bu With the .CR O_NDELAY .CR fcntl() flag .PD .RE .PP Although the use of .CR FIONBIO is not recommended, if nonblocking I/O is enabled using .CR FIOSNBIO or the equivalent .CR FIONBIO request (defined in .CR and explained in .IR ioctl (2), .IR ioctl (5) and .IR socket (7)), the .CR recv() request completes in one of three ways: .RS 2 .TP 3 \(bu If there is enough data available to satisfy the entire request, .CR recv() completes successfully, having read all of the data, and returns the number of bytes read. .TP \(bu If there is not enough data available to satisfy the entire request, .CR recv() complete successfully, having read as much data as possible, and returns the number of bytes it was able to read. .TP \(bu If there is no data available, .CR recv() fails and .CR errno is set to .RC [ EWOULDBLOCK ]. .RE .PP If nonblocking I/O is disabled using .CR FIOSNBIO , .CR recv() always executes completely (blocking as necessary) and returns the number of bytes read. .PP If the .CR O_NONBLOCK flag is set using .CR fcntl() (defined in .CR and explained in .IR fcntl (2) and .IR fcntl (5)), POSIX-style nonblocking I/O is enabled. In this case, the .CR recv() request completes in one of three ways: .RS 2 .TP 3 \(bu If there is enough data available to satisfy the entire request, .CR recv() completes successfully, having read all the data, and returns the number of bytes read. .TP \(bu If there is not enough data available to satisfy the entire request, .CR recv() completes successfully, having read as much data as possible, and returns the number of bytes it was able to read. .TP \(bu If there is no data available, .CR recv() completes, having read no data, and returns \(mi1 with .CR errno set to [EAGAIN]. .RE .PP If the .CR O_NDELAY flag is set using .CR fcntl() (defined in .CR and explained in .IR fcntl (2) and .IR fcntl (5)), nonblocking I/O is enabled. In this case, the .CR recv() request completes in one of three ways: .RS 2 .TP 3 \(bu If there is enough data available to satisfy the entire request, .CR recv() completes successfully, having read all the data, and returns the number of bytes read. .TP \(bu If there is not enough data available to satisfy the entire request, .CR recv() completes successfully, having read as much data as possible, and returns the number of bytes it was able to read. .TP \(bu If there is no data available, .CR recv() completes successfully, having read no data, and returns 0. .RE .PP If the .CR O_NONBLOCK or .CR O_NDELAY flag is cleared using .CR fcntl() , the corresponding style of nonblocking I/O, if previously enabled, is disabled. In this case, .CR recv() always executes completely (blocking as necessary) and returns the number of bytes read. .PP Since both the .CR fcntl() .CR O_NONBLOCK and .CR O_NDELAY flags and .CR ioctl() .CR FIOSNBIO request are supported, some clarification on how these features interact is necessary. If the .C O_NONBLOCK or .C O_NDELAY flag has been set, .C recv() requests behave accordingly, regardless of any .C FIOSNBIO requests. If neither the .C O_NONBLOCK flag nor the .C O_NDELAY flag has been set, .C FIOSNBIO requests control the the behavior of .C recv() . .PP By default nonblocking I/O is disabled. .PP .CR select() can be used to determine when more data arrives by selecting the socket for reading. .PP The .I flags parameter can be set to .CR MSG_PEEK , .CR MSG_OOB , both, or zero. If it is set to .CR MSG_PEEK , any data returned to the user still is treated as if it had not been read. The next .CR recv() rereads the same data. The .CR MSG_OOB flag is used to receive out-of-band data. For TCP SOCK_STREAM sockets, both the .CR MSG_PEEK and .CR MSG_OOB flags can be set at the same time. The .CR MSG_OOB flag value is supported for TCP SOCK_STREAM sockets only. .CR MSG_OOB is not supported for AF_UNIX sockets. .PP A .CR read() call made to a socket behaves in exactly the same way as a .CR recv() with .I flags set to zero. .PP .SS AF_CCITT Only Connections in the address family AF_CCITT support message-based sockets only. Although the user specifies connection-based communications (SOCK_STREAM), the X.25 subsystem communicates via messages. This address family does not support SOCK_DGRAM socket types. .PP Normally, each .CR recv() returns one complete X.25 message. If the socket is in nonblocking mode, .CR recv() behaves as described above. Note that if the user specifies .I len less than the actual X.25 message size, the excess data is discarded and no error indication is returned. The size of the next available message as well as the state of MDTF, D, and Q bits can be obtained with .CR "ioctl(X25_NEXT_MSG_STAT)" . .PP Connections of the address family AF_CCITT receive data in the same way as message-based connections described above, with the following additions and exceptions: .RS 2 .TP 3 \(bu .CR recvfrom() is supported; however, the .I from and .I fromlen parameters are ignored (that is, it works in the same manner as .CR recv() ). .TP \(bu To receive a message in fragments of the complete X.25 message, use .CR ioctl(X25_SET_FRAGMENT_SIZE) . The state of the MDTF bit is 1 for all except the last fragment of the message. .TP \(bu The .CR MSG_OOB flag is supported. .TP \(bu The .CR MSG_PEEK flag is supported; the two flags can be combined. .TP \(bu If a message is received that is larger than the user-controlled maximum message size (see .IR af_ccitt (7F)), the X.25 subsystem RESETs the circuit, discards the data, and sends the out-of-band event .CR OOB_VC_MESSAGE_TOO_BIG to the socket. .RE .SH DEPENDENCIES .SS AF_CCITT .CR recvfrom() is supported; however, the .I from and .I fromlen parameters are ignored (i.e., it works in the same manner as .CR recv() ). .PP The .CR O_NDELAY .CR fcntl() call is not supported over X.25 links. Use the .CR FIOSNBIO .CR ioctl() call instead to enable nonblocking I/0. .SH _XOPEN_SOURCE_EXTENDED only .CR "X/Open Sockets msghdr" has the following form : .nf .IP .C "struct msghdr {" .C " void *msg_name; /* optional address */" .C " size_t msg_namelen; /* size of address */" .C " struct iovec *msg_iov; /* scatter array for data */" .C " int msg_iovlen; /* # of elements in msg_iov */" .C " void *msg_control; /* ancillary data, see below */" .C " size_t msg_controllen; /* ancillary data buffer len */" .C " int msg_flags; /* flags on received message */" .C "}" .fi .PP .I msg_control specifies a buffer to receive any ancillary data sent along with the message. Ancillary data consists of a sequence of pairs, each consisting of a .I cmsghdr structure followed by a data array. The data array contains the ancillary data message, and the .I cmsghdr structure contains descriptive information that allows an application to correctly parse the data. .I cmsghdr has the following structure: .nf .IP .C "struct cmsghdr {" .C " size_t cmsg_len; /* data byte count, including hdr*/" .C " int cmsg_level; /* originating protocol */" .C " int cmsg_type; /* protocol-specific type */" .C "}" .fi .PP The supported value for cmsg_level is SOL_SOCKET, and the supported value for cmsg_type is SCM_RIGHTS. Together they indicate that the data array contains the access rights to be received. Access rights are supported only for AF_UNIX. Access rights are limited to file descriptors of size .IR int . If ancillary data are not being transferred, set the .I msg_control field to NULL and set the .I msg_controllen field to 0. .PP The .I flags parameter accepts a new value, .CR MSG_WAITALL, which requests that the function block until the full amount of data requested can be returned. The function may return a smaller amount of data if a signal is caught, the connection is terminated, or an error is pending for the socket. On successful completion of recvmsg(), the .I msg_flags member of the message header is the bitwise-inclusive OR of all of the following flags that indicate conditions detected for the received message. .RS .TP 20 .CR MSG_EOR End of record was received(if supported by the protocol). .TP .CR MSG_OOB Out-of-band data was received. .TP .CR MSG_TRUNC Normal data was truncated. .TP .CR MSG_CTRUNC Control data was truncated. .SH RETURN VALUE .CR recv() , .CR recvfrom() , and .CR recvmsg() returns the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .IR n is the number of bytes received. .TP .CR \00 The socket is blocking and the transport connection to the remote node failed. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR recv() , .CR recvfrom() , or .CR recvmsg() fails, .CR errno is set to one of the following values. .RS .TP 20 [EAGAIN] Non-blocking I/O is enabled using .CR O_NONBLOCK flag with .CR fcntl() and the receive operation would block, or the socket has an error that was set asynchronously. An asynchronous error can be caused by a gateway failing to forward a datagram because the datagram exceeds the MTU of the next-hop network and the "Don't Fragment" (DF) bit in the datagram is set. (See .CR SO_PMTU in .IR getsockopt (2).) .TP [EBADF] The argument .I s is an invalid descriptor. .TP [ECONNRESET] A connection was forcibly closed by a peer. .TP [EFAULT] An invalid pointer was specified in the .I buf , .I from , or .I fromlen parameter, or in the msghdr structure. .TP [EINTR] The receive was interrupted by delivery of a signal before any data was available for the receive. .TP [EINVAL] The .I len parameter or a length in the msghdr structure is invalid; or no data is available on receive of out of band data. .TP [EMSGSIZE] A length in the msghdr structure is invalid. .TP [ENOBUFS] Insufficient resources were available in the system to perform the operation. .TP [ENOTCONN] Receive on a SOCK_STREAM socket that is not yet connected. .TP [ENOTSOCK] The argument .I s is a valid file descriptor, but it is not a socket. .TP [EOPNOTSUPP] The .CR MSG_OOB flag was set for a UDP SOCK_DGRAM message-based socket, or .CR MSG_OOB or .CR MSG_PEEK was set for any AF_UNIX socket. The .CR MSG_OOB flag is supported only for stream-based TCP SOCK_STREAM sockets. Neither .CR MSG_PEEK nor .CR MSG_OOB is supported for AF_UNIX sockets. .IP AF_CCITT only: .CR recv() was issued on a .CR listen() socket. .TP [ETIMEDOUT] The connection timed out during connection establishment, or due to a transmission timeout on active connection. .TP [EWOULDBLOCK] Non-blocking I/O is enabled using .CR ioctl() .CR FIOSNBIO request, and the requested operation would block. .RE .SH AUTHOR .CR recv() was developed by the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO getsockopt(2), read(2), select(2), send(2), socket(2), af_ccitt(7F), inet(7F), socket(7), socketx25(7), tcp(7P), udp(7P), unix(7P), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR recv() ": XPG4" .\" .\" index@\f1message from a socket, receive@@@\f3recv(2)\f1 .\" index@\f1receive message from a socket@@@\f3recv(2)\f1 .\" index@\f1socket, receive message from a@@@\f3recv(2)\f1 .\" index@\f4recv()\f1 \- receive message from a socket@@@\f3recv(2)\f1 .\" index@\f4recvfrom()\f1 \- receive message from a socket@@@\f3recv(2)\f1 .\" index@\f4recvmsg()\f1 \- receive message from a socket@@@\f3recv(2)\f1 .\" .\" links@recv.2 recvfrom.2 .\" links@recv.2 recvmsg.2 .\" .\" toc@\f3recv(2)\f1:\0\0\f4recv()\f1, \f4recvfrom()\f1, \f4recvmsg()\f1@@@receive message from a socket .\" toc@\f4recvfrom()\f1:\0\0receive message from a socket@@@see \f3recv(2)\f1 .\" toc@\f4recvmsg()\f1:\0\0receive message from a socket@@@see \f3recv(2)\f1 .\" $Header: rename.2,v 72.5 94/11/14 15:25:56 ssa Exp $ .TA r .TH rename 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rename \- change the name of a file .SH SYNOPSIS .C "#include " .PP .C "int rename(const char *source, const char *target);" .SH DESCRIPTION The .CR rename() system call causes the .I source file to be renamed to .IR target . If .I target exists, it is first removed. Both .I source and .I target must be of the same type (that is, either directories or nondirectories), and must reside on the same file system. .PP If .I target can be created or if it existed before the call, .CR rename() guarantees that an instance of .I target will exist, even if the system crashes in the midst of the operation. .PP If the final component of .I source is a symbolic link, the symbolic link is renamed, not the file or directory to which the symbolic link points. .SH RETURN VALUE .CR rename() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. Neither file is affected. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR rename() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] A component of either path prefix denies search permission. .TP [EACCES] The requested link requires writing to a directory without write permission. .TP [EBUSY] .I target or .I source is an existing directory that is the mount point for a mounted file system. .TP [EDQUOT] User's disk quota block or inode limit has been reached for this file system. .TP [EEXIST] .I target is a directory and is not empty. .TP [EFAULT] .I source or .I target points outside the allocated address space of the process. Reliable detection of this error is implementation dependent. .TP [EINVAL] .I source is a parent directory of .IR target , or an attempt is made to rename the .CR . or .CR .. directory. .TP [EISDIR] .I target is a directory, but .I source is not. .TP [ELOOP] Too many symbolic links were encountered in translating either path name. .TP [ENAMETOOLONG] A component of either path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect, or the entire length of either path name exceeds .CR PATH_MAX bytes. .TP [ENOENT] A component of the .I source path does not exist, or a path prefix of .I target does not exist. .TP [ENOSPC] The destination directory cannot be extended because of a lack of space on the file system containing the directory. .TP [ENOTDIR] A component of either path prefix is not a directory. .TP [ENOTDIR] .I source is a directory, but .I target is not. .TP [EPERM] The directory containing .I source has the sticky bit set, and neither the containing directory nor the .I source are owned by the effective user ID. .TP [EPERM] The .I target file exists, the directory containing .I target has the sticky bit set, and neither the containing directory nor the .I target are owned by the effective user ID. .TP [EROFS] The requested link requires writing in a directory on a read-only file system. .TP [EXDEV] The paths named by .I source and .I target are on different logical devices (file systems). .PD .RE .SH AUTHOR .CR rename() was developed by the University of California, Berkeley. .SH SEE ALSO open(2). .SH STANDARDS CONFORMANCE .CR rename() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4rename()\fP \- change the name of a file@@@\f3rename(2)\f1 .\" index@file: change the name of a file@@@\f3rename(2)\f1 .\" index@change the name of a file@@@\f3rename(2)\f1 .\" index@name: change the name of a file@@@\f3rename(2)\f1 .\" .\" toc@\f3rename(2)\f1:\0\0\f4rename()\fP@@@change the name of a file .\" $Header: rmdir.2,v 72.5 94/11/14 15:26:01 ssa Exp $ .TA r .TH rmdir 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rmdir() \- remove a directory file .SH SYNOPSIS .C "#include " .PP .C "int rmdir(const char *path);" .SH DESCRIPTION The .CR rmdir() system call removes a directory file whose name is given by .IR path . The directory must be empty (except for the files .CR . and .CR .. ) before it can be removed. .SH RETURN VALUE .CR rmdir() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR rmdir() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] A component of the path prefix denies search permission. .TP [EACCES] Write permission is denied on the directory containing the link to be removed. .TP [EACCES] The process does not have read/write access permission to the parent directory. .TP [EBUSY] The directory to be removed is the mount point for a mounted file system. .TP [EEXIST] The named directory is not empty. It contains files other than .CR . and .CR .. . .TP [EFAULT] .I path points outside the process's allocated address space. The reliable detection of this error is implementation-dependent. .TP [EINVAL] The path is .CR . . .TP [ELOOP] Too many symbolic links were encountered in translating the path name. .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] The named file does not exist. .TP [ENOTDIR] A component of the path is not a directory. .TP [EPERM] The directory containing the directory to be removed has the sticky bit set and neither the containing directory nor the directory to be removed are owned by the effective user ID. .TP [EROFS] The directory entry to be removed resides on a read-only file system. .RE .SH AUTHOR .CR rmdir() was developed by the University of California, Berkeley and HP. .SH SEE ALSO mkdir(2), unlink(2), remove(3C). .SH STANDARDS CONFORMANCE .CR rmdir() ": AES, SVID2, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4rmdir()\f1 \- remove a directory file@@@\f3rmdir(2)\f1 .\" index@directory file, remove a@@@\f3rmdir(2)\f1 .\" index@file, directory, remove@@@\f3rmdir(2)\f1 .\" index@remove a directory file@@@\f3rmdir(2)\f1 .\" .\" toc@\f3rmdir(2)\f1:\0\0\f4rmdir()\f1@@@remove a directory file .\" $Header: rtprio.2,v 72.5 94/04/04 14:20:57 ssa Exp $ .TA r .TH rtprio 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtprio \- change or read real-time priority .SH SYNOPSIS .C "#include " .PP .C "int rtprio(pid_t pid, int prio);" .SH DESCRIPTION The .CR rtprio() system call sets or reads the real-time priority of a process. .PP If .I pid is zero, it specifies the calling process; otherwise, it specifies the process .SM ID of a process. .PP When setting the real-time priority of another process, the real or effective user .SM ID of the calling process must match the real or saved user .SM ID of the process to be modified, or the effective user .SM ID of the calling process must be that of a user having appropriate privileges. The calling process must also be a member of a privilege group allowing .CR rtprio() (see .IR getprivgrp (2)) or the effective user .SM ID of the calling process must be a user having appropriate privileges. .PP Simply reading real-time priorities requires no special privilege. .PP Real-time scheduling policies differ from normal timesharing policies in that the real-time priority is used to absolutely order all real-time processes. This priority is not degraded over time. All real-time processes are of higher priority than normal user and system processes, although some system processes may run at real-time priorities. If there are several eligible processes at the same priority level, they are run in a round robin fashion as long as no process with a higher priority intervenes. A real-time process receives .SM CPU service until it either voluntarily gives up the .SM CPU or is preempted by a process of equal or higher priority. Interrupts can also preempt a real-time process. .PP Valid real-time priorities run from zero to 127. Zero is the highest (most important) priority. This real-time priority is inherited across forks (see .IR fork (2)) and execs (see .IR exec (2)). .PP .I prio can have the following values: .RS .TP 20 .CR 0 \0to\0\& 127 Set the process to this real-time priority. .TP .CR RTPRIO_NOCHG Do not change the real-time priority. This is used to read the process real-time priority. .TP .CR RTPRIO_RTOFF Set the process to no longer have a real-time priority. It resumes a normal timesharing priority. .IP Any process, regardless of privilege, is allowed to turn off its own real-time priority using a .I pid of zero. .RE .SH RETURN VALUE .CR rtprio() returns the following values: .RS .TP 20 .CR 0 \0to\0\& 127 The process was a real-time process. The value is the process's former (before the call) real-time priority. .TP .CR RTPRIO_RTOFF The process was not a real-time process. .TP .CR -1 An error occurred. .CR errno is set to indicate the error. .RE .SH ERRORS If .CR rtprio() fails, .CR errno is set to one of the following values: .RS .TP 20 .SM [EINVAL] .I prio is not .CR RTPRIO_NOCHG , .CR RTPRIO_RTOFF , or in the range 0 to 127. .TP .SM [EPERM] The calling process is not a user having appropriate privileges, and neither its real nor effective user .SM ID match the real or saved user .SM ID of the process indicated by .IR pid . .TP .SM [EPERM] The group access list of the calling process does not contain a group having .CR PRIV_RTPRIO capability and .I prio is not .CR RTPRIO_NOCHG, or .CR RTPRIO_RTOFF with a .I pid of zero. .TP .SM [ESRCH] No process can be found corresponding to that specified by .I pid. .RE .SH EXAMPLES The following call to .CR rtprio() sets the calling process to a real-time priority of 90: .IP .C rtprio(0, 90); .SH WARNINGS Normally, compute-bound programs should not be run at real-time priorities, because all timesharing work on the .SM CPU would come to a complete halt. .SH DEPENDENCIES .SS Series 800 .\" does not apply to Series 700 Because processes executing at real-time priorities get scheduling preference over a system process executing at a lower priority, unexpected system behavior can occur after a power failure on systems that support power-fail recovery. For example, when .CR init (see .IR init (1M)) receives the powerfail signal .CR SIGPWR , it normally reloads programmable hardware such as terminal multiplexers. If a higher-priority real-time process is eligible to run after the power failure, the running of .CR init is delayed. This condition temporarily prevents terminal input to any process, including real-time shells of higher priority than the eligible real-time process. To avoid this situation, a real-time process should catch .CR SIGPWR and suspend itself until .CR init has finished its powerfail processing. .SH AUTHOR .CR rtprio() was developed by HP. .SH SEE ALSO rtprio(1), getprivgrp(2), nice(2), plock(2). .\" .\" index@\f4rtprio()\f1 \- change or read real-time priority@@@\f3rtprio(2)\f1 .\" index@change real-time priority@@@\f3rtprio(2)\f1 .\" index@read real-time priority@@@\f3rtprio(2)\f1 .\" .\" toc@\f3rtprio(2)\f1:\0\0\f4rtprio()\f1@@@change or read real-time priority .\" $Header: rtsched.2,v 72.6 94/11/14 15:26:03 ssa Exp $ .TA r .TH rtsched 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtsched: sched_get_priority_max(), sched_get_priority_min(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setparam(), sched_setscheduler(), sched_yield(), PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX() \- real-time scheduling operations .SH SYNOPSIS .nf .C "#include " .PP .C "int sched_setparam(" .C " pid_t pid," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getparam(" .C " pid_t pid," .C " struct sched_param *param" .C ");" .PP .C "int sched_setscheduler(" .C " pid_t pid," .C " int policy," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getscheduler(" .C " pid_t pid" .C ");" .PP .C "int sched_yield();" .PP .C "int sched_get_priority_max(" .C " int policy" .C ");" .PP .C "int sched_get_priority_min(" .C " int policy" .C ");" .PP .C "int sched_rr_get_interval(" .C " pid_t pid," .C " struct timespec *interval" .C ");" .PP .C "int PRI_POSIX_TO_HPUX(" .C " const struct sched_param *param" .C ");" .PP .C "int PRI_HPUX_TO_POSIX(" .C " int pri," .C " struct sched_param *param" .C ");" .fi .SH DESCRIPTION .SS Summary .TP 35 .PD 0 .CR sched_get_priority_max() Get maximum scheduling policy .TP .CR sched_get_priority_min() Get minimum scheduling policy .TP .CR sched_getparam() Get scheduling parameters of process .TP .CR sched_getscheduler() Get scheduling policy of process .TP .CR sched_rr_get_interval() Update execution time limit for a process .TP .CR sched_setparam() Set scheduling parameters of process .TP .CR sched_setscheduler() Set scheduling policy and parameters of process .TP .CR sched_yield() Requeue current process in process list .TP .CR PRI_HPUX_TO_POSIX() Convert HP-UX priority to POSIX .TP .CR PRI_POSIX_TO_HPUX() Convert POSIX priority to HP-UX .PD .SS sched_setparam() The .CR sched_setparam() function sets the scheduling parameters of the process specified by .I pid to the values specified by the .I sched_param structure pointed to by .IR param . The value of the .I sched_priority member in the .I param structure is any integer within the inclusive priority range for the current scheduling policy of the process specified by .IR pid . .PP Higher numerical values for the priority represent higher (stronger) priorities. Note that this is different from the .CR SCHED_HPUX , .CR SCHED_TIMESHARE , and .CR SCHED_RTPRIO scheduling policies, where higher numerical values represent lower (weaker) priorities. See the .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() functions, and .CR SCHED_RTPRIO and .CR SCHED_OTHER in "Scheduling Policies" below. .PP If a process described by .I pid exists and if the calling process has permission, the scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are set for the calling process. .PP Only a superuser may change the scheduling parameters of another process. .PP The calling process must have the appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setparam() . .PP The target process, whether it is running or not running, will resume execution after all other runnable processes of equal or greater priority have been scheduled to run. .PP If the priority of the process specified by the .I pid argument is set higher than that of the lowest priority running process, and if the specified process is ready to run, the process specified by the .I pid argument will preempt a lowest-priority running process. Similarly, if the process calling .CR sched_setparam() sets its own priority lower than that of one or more other nonempty process lists, then the process that is the head of the highest priority list will also preempt the calling process. Thus, in either case, the originating process may not receive notification of the completion of the requested priority change until the higher priority process has executed. .SS sched_getparam() The .CR sched_getparam() function returns the scheduling parameters of a process specified by .I pid in the .I sched_param structure pointed to by .IR param . .PP If a process described by .I pid exists, the scheduling parameters are returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are returned for the calling process. .SS sched_setscheduler() The .CR sched_setscheduler() function sets the scheduling policy and scheduling parameters of the process specified by .I pid to .I policy and the parameters specified in the .I sched_param structure pointed to by .IR param , respectively. The value of the .I sched_priority member in the .I param structure can be any integer within the inclusive priority range for the scheduling policy specified by .IR policy . .PP The possible values for the .I policy parameter are defined in the header file .CR , and mentioned below. .PP If a process described by .I pid exists, the scheduling policy and scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy and scheduling parameters are set for the calling process. .PP Appropriate privileges are required to change the scheduling parameters of another process. .PP The calling process must have appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setscheduler() . .PP The .CR sched_setscheduler() function is considered successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by .I pid to the values specified by .I policy and the structure .IR param , respectively. .PP .SS sched_getscheduler() The .CR sched_getscheduler() function returns the scheduling policy of the process specified by .IR pid . .PP The values that can be returned by .CR sched_getscheduler() are defined in the header file .CR (see .CR sched_setscheduler() ). .PP If a process described by .I pid exists, the scheduling policy is returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy is returned for the calling process. .SS sched_yield() The .CR sched_yield() function forces the running process to relinquish the processor until it again becomes the head of its process list. It takes no arguments. .SS sched_get_priority_max() .SS sched_get_priority_min() The .CR sched_get_priority_max() and .CR sched_get_priority_min() functions return the appropriate maximum or minimum, respectively, for the scheduling policy specified by .IR policy . .PP The value of .I policy must be one of the scheduling policy values defined in .CR . .SS sched_rr_get_interval() The .CR sched_rr_get_interval() function updates the .I timespec structure referenced by the .I interval argument to contain the current execution time limit (that is, time quantum) for the process indicated by .I pid under the .CR SCHED_RR policy, at which a scheduling decision will be made when another process at the same priority is ready to execute. If .I pid is zero, the current execution time limit for the calling process is returned. .SS PRI_HPUX_TO_POSIX() .SS PRI_POSIX_TO_HPUX() These two functions serve to map (translate) the range of HP-UX priorities into the POSIX.4 model. These translations are necessary because the POSIX.4 standard chose .I larger numbers to represent stronger priorities and the existing HP-UX behavior, which must be maintained for backward compatibility, uses .I smaller numbers for stronger priorities. .PP The .CR PRI_HPUX_TO_POSIX() function returns, in the .I sched_param structure pointed to by .IR param , the POSIX.4 scheduling priority corresponding to the HP-UX priority passed in the argument .IR pri . The argument .I pri must contain a valid HP-UX priority. .PP The .CR PRI_POSIX_TO_HPUX() function returns an HP-UX process priority corresponding to the .I sched_priority member in the .I sched_param structure specified. The value of the .I sched_priority member can be any integer within the inclusive priority range for the .CR SCHED_HPUX scheduling policy. The HP-UX priority returned is comparable to the values returned by .CR getpriority() (see .IR getpriority (2)). .SS Scheduling Policies The scheduling policies described are defined in terms of a conceptual model, which contains a set of process lists. There is, conceptually, one process list for each priority. Any runnable process may be in any process list. Multiple scheduling policies are provided. Each nonempty list is ordered, and contains a head as one end of its order, and a tail as the other. The purpose of a scheduling policy is to define the allowable operations on this set of lists (for example, moving processes between and within lists). .PP Each process will be controlled by an associated scheduling policy and priority. These parameters may be specified by explicit application execution of the .CR sched_setscheduler() or .CR sched_setparam() functions. .PP Associated with each policy is a priority range. The priority ranges for each policy can (but need not) overlap the priority ranges of other policies. .PP When a process is to be selected to run, the process that is at the head of the highest priority nonempty process list is chosen. It is then removed from its process list. .PP The following scheduling policies are defined: .RS .TP 15 .CR SCHED_FIFO First in-first out (FIFO) scheduling policy. .IP Processes scheduled under this policy are chosen from a process list that is ordered by the time its processes have been in the list without being executed. Generally, the head of the list is the process that has been in the list the longest time, and the tail is the process that has been in the list the shortest time. .IP Under the .CR SCHED_FIFO policy, the modification of the definitional process lists is as follows: .RS .RS .TP 3 \(bu When a running process becomes a preempted process, it becomes the head of the process list for its priority. .TP \(bu When a blocked process becomes a runnable process, it becomes the tail of the process list for its priority. .TP \(bu When a running process calls the .CR sched_setscheduler() function, the process specified in the function call is modified to the policy and priority specified by the .I param argument. If the process whose policy and priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process calls the .CR sched_setparam() function, the priority of the process specified in the function call is modified to the priority specified by the .I param argument. If the process whose priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process issues the .CR sched_yield() function, the process becomes the tail of the process list for its priority. .TP \(bu At no other time is the position of a process with this scheduling policy within the process lists affected. .RE .RE .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_FIFO is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR Round-robin scheduling policy, with a per-system time slice (time quantum). .IP This policy is identical to the .CR SCHED_FIFO policy with the additional condition that when the implementation detects that a running process has been executing as a running process for a time period of length returned by the function .CR sched_rr_get_interval() , or longer, the process becomes the tail of its process list, and the head of that process list is removed and made a running process. .IP The effect of this policy is to ensure that if there are multiple .CR SCHED_RR processes at the same priority, one of them will not monopolize the processor. An application should not rely only on the use of .CR SCHED_RR to ensure application progress among multiple processes if the application includes processes using the .CR SCHED_FIFO policy at the same or higher priority levels, or .CR SCHED_RR processes at a higher priority level. .IP A process under this policy that is preempted and subsequently resumes execution as a running process completes the unexpired portion of its round-robin interval time period. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR2 Round-robin scheduling policy, with a per-priority time slice (time quantum). .IP This policy is identical to the .CR SCHED_RR policy, except that the round-robin time slice interval returned by .CR sched_rr_get_interval() depends upon the priority of the specified process. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RTPRIO Real-time scheduling policy with nondecaying priorities (like .CR SCHED_FIFO and .CR SCHED_RR ) with a priority range between the POSIX real-time policies and the HP-UX policies, described below (see .IR rtprio(2)). .IP For processes executing under this policy, the implementation must use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RTPRIO is provided as the parameter. Note that, for the .CR SCHED_RTPRIO scheduling policy, .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_RTPRIO is weaker than the weakest priority in the priority ranges for any of the POSIX policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .TP .CR SCHED_OTHER " (" SCHED_HPUX ", " SCHED_TIMESHARE ) Another scheduling policy. .IP The .CR SCHED_OTHER policy, also known as .CR SCHED_HPUX and .CR SCHED_TIMESHARE , provides a way for applications to indicate, in a portable way, that they no longer need a real-time scheduling policy. .IP For processes executing under this policy, the implementation can use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_OTHER is provided as the parameter. Note that for the .CR SCHED_OTHER scheduling policy, like .CR SCHED_RTPRIO , .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_OTHER is weaker than the weakest priority in the priority ranges for any of the other policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .RE .SH RETURN VALUE The functions return the following values: .SS sched_getparam() .SS sched_rr_get_interval() .SS sched_setparam() .SS sched_yield() .SS PRI_HPUX_TO_POSIX() .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_setscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the former scheduling policy of the specified process. .TP .CR -1 Failure. The policy and scheduling parameters remain unchanged. .CR errno is set to indicate the error. .PD .RE .SS sched_getscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the scheduling policy of the specified process. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the maximum or minimum value, respectively. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS PRI_POSIX_TO_HPUX() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the the HP-UX priority corresponding to the .I sched_priority member in the .I param structure. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If the functions fail, .CR errno is set to one of the following values. .SS sched_setparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] One or more of the requested scheduling parameters is outside the range defined for the scheduling policy of the specified .IR pid . .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling parameters for the specified process, or does not have the appropriate privilege to invoke .CR sched_setparam() . .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_setscheduler() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] The value of the .I policy parameter is invalid, or one or more of the parameters contained in .I param is outside the valid range for the specified scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling policy of the specified process. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getscheduler() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_yield() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP 15 [EINVAL] The value of the .I policy parameter does not represent a defined scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .RE .SS sched_rr_get_interval() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS PRI_POSIX_TO_HPUX() .RS .TP 15 [EINVAL] The priority specified in the .I sched_priority member of the .I param argument is outside the range defined for the .CR SCHED_HPUX scheduling policy. .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS PRI_HPUX_TO_POSIX() .RS .TP 15 [EINVAL] The priority specified in the .I pri argument is not a valid HP-UX priority. .TP [ENOSYS] The function is not supported by this implementation. .RE .SH EXAMPLES Change the calling process to use the strongest .CR FIFO priority: .IP .nf .C "#include " .IP .C "struct sched_param param;" .C "int maxpri;" .IP .C "maxpri = sched_get_priority_max(SCHED_FIFO);" .C "if (maxpri == -1) {" .C " perror(""sched_get_priority_max() failed"");" .C " exit(1);" .C "}" .C "param.sched_priority = maxpri;" .C "if (sched_setscheduler(getpid(), SCHED_FIFO, ¶m) == -1) {" .C " perror(""sched_setscheduler() failed"");" .C " exit(1);" .C "}" .fi .SH AUTHOR The .CI sched_ * () functions were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .PP .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() were developed by HP. .SH SEE ALSO rtsched(1), rtprio(2). .SH STANDARDS CONFORMANCE .CR sched_get_priority_max() ": POSIX.4" .PP .CR sched_get_priority_min() ": POSIX.4" .PP .CR sched_getparam() ": POSIX.4" .PP .CR sched_getscheduler() ": POSIX.4" .PP .CR sched_rr_getinterval() ": POSIX.4" .PP .CR sched_setparam() ": POSIX.4" .PP .CR sched_setscheduler() ": POSIX.4" .PP .CR sched_yield() ": POSIX.4" .\" .\" index entries: .\" index@\f1rtsched\f1 \- real time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f4PRI_HPUX_TO_POSIX()\f1 \- return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f4PRI_POSIX_TO_HPUX()\f1 \- return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_max()\f1 \- return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_min()\f1 \- return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_getparam()\f1 \- return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_getscheduler()\f1 \- return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_rr_get_interval()\f1 \- update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4sched_setparam()\f1 \- set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_setscheduler()\f1 \- set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_yield()\f1 \- force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1operations, real-time scheduling@@@\f3rtsched(2)\f1 .\" index@\f1real-time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f1return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1scheduling operations, real-time@@@\f3rtsched(2)\f1 .\" index@\f1scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" links entries: .\" links@rtsched.2 PRI_HPUX_TO.2 .\" links@rtsched.2 PRI_POSIX_T.2 .\" links@rtsched.2 pri_hpux_to.2 .\" links@rtsched.2 pri_posix_t.2 .\" links@rtsched.2 sched_get_p.2 .\" links@rtsched.2 sched_getpa.2 .\" links@rtsched.2 sched_getsc.2 .\" links@rtsched.2 sched_rr_ge.2 .\" links@rtsched.2 sched_setpa.2 .\" links@rtsched.2 sched_setsc.2 .\" links@rtsched.2 sched_yield.2 .\" toc entries: .\" toc@\f3rtsched(2)\f1:\0\0\f4sched_get_priority_max()\f1, \f4sched_get_priority_min()\f1,\n\f4sched_getparam()\f1, \f4sched_getscheduler()\f1, \f4sched_rr_get_interval()\f1,\n\f4sched_setparam()\f1, \f4sched_setscheduler()\f1, \f4sched_yield()\f1,\n\f4PRI_HPUX_TO_POSIX()\f1, \f4PRI_POSIX_TO_HPUX()\f1@@@real-time scheduling operations .\" toc@\f4PRI_HPUX_TO_POSIX()\f1:\0\0return POSIX.4 process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4PRI_POSIX_TO_HPUX()\f1:\0\0return HP-UX process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_max()\f1:\0\0return maximum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_min()\f1:\0\0return minimum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getparam()\f1:\0\0return scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getscheduler()\f1:\0\0return scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_rr_get_interval()\f1:\0\0update execution time limit@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setparam()\f1:\0\0set scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setscheduler()\f1:\0\0set scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_yield()\f1:\0\0force process to relinquish processor@@@\f1see \f3rtsched(2)\f1 .\" $Header: brk.2,v 72.4 94/11/14 13:03:14 ssa Exp $ .TA b .TH brk 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME brk, sbrk \- change data segment space allocation .SH SYNOPSIS .C "#include " .PP .C "int brk(const void *endds);" .PP .C "void *sbrk(int incr);" .SH DESCRIPTION .C brk() and .C sbrk() are used to change dynamically the amount of space allocated for the calling process's data segment; see .IR exec (2). The change is made by resetting the process's break value and allocating the appropriate amount of space. The break value is the address of the first location beyond the end of the data segment. The amount of allocated space increases as the break value increases. The newly allocated space is set to zero. .PP .C brk() sets the break value to .I endds and changes the allocated space accordingly. .PP .C sbrk() adds .I incr bytes to the break value and changes the allocated space accordingly. .I incr can be negative, in which case the amount of allocated space is decreased. .SH ERRORS .C brk() and .C sbrk() fail without making any change in the allocated space if one or more of the following are true: .TP 15 .SM [ENOMEM] Such a change would result in more space being allocated than is allowed by a system-imposed maximum (see .IR ulimit (2)). .TP .SM [ENOMEM] Such a change would cause a conflict between addresses in the data segment and any attached shared memory segment (see .IR shmop (2)). .TP .SM [ENOMEM] Such a change would be impossible as there is insufficient swap space available. .SH WARNINGS The pointer returned by .C sbrk() is not necessarily word-aligned. Loading or storing words through this pointer could cause word alignment problems. .PP Be very careful when using either .CR brk or .CR sbrk in conjunction with calls to the .IR malloc (3C) library routines. There is only one program data segment from which all three of these routines allocate and deallocate program data memory. .SH RETURN VALUE Upon successful completion, .C brk() returns a value of 0 and .C sbrk() returns the old break value. Otherwise, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH AUTHOR .C brk() and .C sbrk() were developed by AT&T and HP. .SH SEE ALSO exec(2), shmop(2), ulimit(2), end(3C), malloc(3C). .SH STANDARDS CONFORMANCE .CR brk() ": XPG2" .PP .CR sbrk() ": XPG2" .\" .\" index@\f4brk()\fP, \f4sbrk()\fP \(mi change data segment space allocation@@@\f3brk(2)\f1 .\" index@\f4sbrk()\fP \(mi increase data segment space allocation@@@\f3brk(2)\f1 .\" index@allocation, change data segment space@@@\f3brk(2)\f1 .\" index@change data segment space allocation@@@\f3brk(2)\f1 .\" index@data segment space allocation, change@@@\f3brk(2)\f1 .\" index@increase data segment space allocation@@@\f3brk(2)\f1 .\" index@space allocation, change data segment@@@\f3brk(2)\f1 .\" .\" toc@\f3brk(2)\f1:\0\0\f4brk()\fP, \f4sbrk()\fP@@@change data segment space allocation .\" toc@\f4sbrk()\fP:\0\0change data segment space allocation@@@see \f3brk(2)\f1 .\" .\" links@brk.2 sbrk.2 .\" .\" fileset_database@brk.2 PROGRAMING-MAN .\" $Header: rtsched.2,v 72.6 94/11/14 15:26:03 ssa Exp $ .TA r .TH rtsched 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtsched: sched_get_priority_max(), sched_get_priority_min(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setparam(), sched_setscheduler(), sched_yield(), PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX() \- real-time scheduling operations .SH SYNOPSIS .nf .C "#include " .PP .C "int sched_setparam(" .C " pid_t pid," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getparam(" .C " pid_t pid," .C " struct sched_param *param" .C ");" .PP .C "int sched_setscheduler(" .C " pid_t pid," .C " int policy," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getscheduler(" .C " pid_t pid" .C ");" .PP .C "int sched_yield();" .PP .C "int sched_get_priority_max(" .C " int policy" .C ");" .PP .C "int sched_get_priority_min(" .C " int policy" .C ");" .PP .C "int sched_rr_get_interval(" .C " pid_t pid," .C " struct timespec *interval" .C ");" .PP .C "int PRI_POSIX_TO_HPUX(" .C " const struct sched_param *param" .C ");" .PP .C "int PRI_HPUX_TO_POSIX(" .C " int pri," .C " struct sched_param *param" .C ");" .fi .SH DESCRIPTION .SS Summary .TP 35 .PD 0 .CR sched_get_priority_max() Get maximum scheduling policy .TP .CR sched_get_priority_min() Get minimum scheduling policy .TP .CR sched_getparam() Get scheduling parameters of process .TP .CR sched_getscheduler() Get scheduling policy of process .TP .CR sched_rr_get_interval() Update execution time limit for a process .TP .CR sched_setparam() Set scheduling parameters of process .TP .CR sched_setscheduler() Set scheduling policy and parameters of process .TP .CR sched_yield() Requeue current process in process list .TP .CR PRI_HPUX_TO_POSIX() Convert HP-UX priority to POSIX .TP .CR PRI_POSIX_TO_HPUX() Convert POSIX priority to HP-UX .PD .SS sched_setparam() The .CR sched_setparam() function sets the scheduling parameters of the process specified by .I pid to the values specified by the .I sched_param structure pointed to by .IR param . The value of the .I sched_priority member in the .I param structure is any integer within the inclusive priority range for the current scheduling policy of the process specified by .IR pid . .PP Higher numerical values for the priority represent higher (stronger) priorities. Note that this is different from the .CR SCHED_HPUX , .CR SCHED_TIMESHARE , and .CR SCHED_RTPRIO scheduling policies, where higher numerical values represent lower (weaker) priorities. See the .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() functions, and .CR SCHED_RTPRIO and .CR SCHED_OTHER in "Scheduling Policies" below. .PP If a process described by .I pid exists and if the calling process has permission, the scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are set for the calling process. .PP Only a superuser may change the scheduling parameters of another process. .PP The calling process must have the appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setparam() . .PP The target process, whether it is running or not running, will resume execution after all other runnable processes of equal or greater priority have been scheduled to run. .PP If the priority of the process specified by the .I pid argument is set higher than that of the lowest priority running process, and if the specified process is ready to run, the process specified by the .I pid argument will preempt a lowest-priority running process. Similarly, if the process calling .CR sched_setparam() sets its own priority lower than that of one or more other nonempty process lists, then the process that is the head of the highest priority list will also preempt the calling process. Thus, in either case, the originating process may not receive notification of the completion of the requested priority change until the higher priority process has executed. .SS sched_getparam() The .CR sched_getparam() function returns the scheduling parameters of a process specified by .I pid in the .I sched_param structure pointed to by .IR param . .PP If a process described by .I pid exists, the scheduling parameters are returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are returned for the calling process. .SS sched_setscheduler() The .CR sched_setscheduler() function sets the scheduling policy and scheduling parameters of the process specified by .I pid to .I policy and the parameters specified in the .I sched_param structure pointed to by .IR param , respectively. The value of the .I sched_priority member in the .I param structure can be any integer within the inclusive priority range for the scheduling policy specified by .IR policy . .PP The possible values for the .I policy parameter are defined in the header file .CR , and mentioned below. .PP If a process described by .I pid exists, the scheduling policy and scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy and scheduling parameters are set for the calling process. .PP Appropriate privileges are required to change the scheduling parameters of another process. .PP The calling process must have appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setscheduler() . .PP The .CR sched_setscheduler() function is considered successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by .I pid to the values specified by .I policy and the structure .IR param , respectively. .PP .SS sched_getscheduler() The .CR sched_getscheduler() function returns the scheduling policy of the process specified by .IR pid . .PP The values that can be returned by .CR sched_getscheduler() are defined in the header file .CR (see .CR sched_setscheduler() ). .PP If a process described by .I pid exists, the scheduling policy is returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy is returned for the calling process. .SS sched_yield() The .CR sched_yield() function forces the running process to relinquish the processor until it again becomes the head of its process list. It takes no arguments. .SS sched_get_priority_max() .SS sched_get_priority_min() The .CR sched_get_priority_max() and .CR sched_get_priority_min() functions return the appropriate maximum or minimum, respectively, for the scheduling policy specified by .IR policy . .PP The value of .I policy must be one of the scheduling policy values defined in .CR . .SS sched_rr_get_interval() The .CR sched_rr_get_interval() function updates the .I timespec structure referenced by the .I interval argument to contain the current execution time limit (that is, time quantum) for the process indicated by .I pid under the .CR SCHED_RR policy, at which a scheduling decision will be made when another process at the same priority is ready to execute. If .I pid is zero, the current execution time limit for the calling process is returned. .SS PRI_HPUX_TO_POSIX() .SS PRI_POSIX_TO_HPUX() These two functions serve to map (translate) the range of HP-UX priorities into the POSIX.4 model. These translations are necessary because the POSIX.4 standard chose .I larger numbers to represent stronger priorities and the existing HP-UX behavior, which must be maintained for backward compatibility, uses .I smaller numbers for stronger priorities. .PP The .CR PRI_HPUX_TO_POSIX() function returns, in the .I sched_param structure pointed to by .IR param , the POSIX.4 scheduling priority corresponding to the HP-UX priority passed in the argument .IR pri . The argument .I pri must contain a valid HP-UX priority. .PP The .CR PRI_POSIX_TO_HPUX() function returns an HP-UX process priority corresponding to the .I sched_priority member in the .I sched_param structure specified. The value of the .I sched_priority member can be any integer within the inclusive priority range for the .CR SCHED_HPUX scheduling policy. The HP-UX priority returned is comparable to the values returned by .CR getpriority() (see .IR getpriority (2)). .SS Scheduling Policies The scheduling policies described are defined in terms of a conceptual model, which contains a set of process lists. There is, conceptually, one process list for each priority. Any runnable process may be in any process list. Multiple scheduling policies are provided. Each nonempty list is ordered, and contains a head as one end of its order, and a tail as the other. The purpose of a scheduling policy is to define the allowable operations on this set of lists (for example, moving processes between and within lists). .PP Each process will be controlled by an associated scheduling policy and priority. These parameters may be specified by explicit application execution of the .CR sched_setscheduler() or .CR sched_setparam() functions. .PP Associated with each policy is a priority range. The priority ranges for each policy can (but need not) overlap the priority ranges of other policies. .PP When a process is to be selected to run, the process that is at the head of the highest priority nonempty process list is chosen. It is then removed from its process list. .PP The following scheduling policies are defined: .RS .TP 15 .CR SCHED_FIFO First in-first out (FIFO) scheduling policy. .IP Processes scheduled under this policy are chosen from a process list that is ordered by the time its processes have been in the list without being executed. Generally, the head of the list is the process that has been in the list the longest time, and the tail is the process that has been in the list the shortest time. .IP Under the .CR SCHED_FIFO policy, the modification of the definitional process lists is as follows: .RS .RS .TP 3 \(bu When a running process becomes a preempted process, it becomes the head of the process list for its priority. .TP \(bu When a blocked process becomes a runnable process, it becomes the tail of the process list for its priority. .TP \(bu When a running process calls the .CR sched_setscheduler() function, the process specified in the function call is modified to the policy and priority specified by the .I param argument. If the process whose policy and priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process calls the .CR sched_setparam() function, the priority of the process specified in the function call is modified to the priority specified by the .I param argument. If the process whose priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process issues the .CR sched_yield() function, the process becomes the tail of the process list for its priority. .TP \(bu At no other time is the position of a process with this scheduling policy within the process lists affected. .RE .RE .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_FIFO is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR Round-robin scheduling policy, with a per-system time slice (time quantum). .IP This policy is identical to the .CR SCHED_FIFO policy with the additional condition that when the implementation detects that a running process has been executing as a running process for a time period of length returned by the function .CR sched_rr_get_interval() , or longer, the process becomes the tail of its process list, and the head of that process list is removed and made a running process. .IP The effect of this policy is to ensure that if there are multiple .CR SCHED_RR processes at the same priority, one of them will not monopolize the processor. An application should not rely only on the use of .CR SCHED_RR to ensure application progress among multiple processes if the application includes processes using the .CR SCHED_FIFO policy at the same or higher priority levels, or .CR SCHED_RR processes at a higher priority level. .IP A process under this policy that is preempted and subsequently resumes execution as a running process completes the unexpired portion of its round-robin interval time period. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR2 Round-robin scheduling policy, with a per-priority time slice (time quantum). .IP This policy is identical to the .CR SCHED_RR policy, except that the round-robin time slice interval returned by .CR sched_rr_get_interval() depends upon the priority of the specified process. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RTPRIO Real-time scheduling policy with nondecaying priorities (like .CR SCHED_FIFO and .CR SCHED_RR ) with a priority range between the POSIX real-time policies and the HP-UX policies, described below (see .IR rtprio(2)). .IP For processes executing under this policy, the implementation must use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RTPRIO is provided as the parameter. Note that, for the .CR SCHED_RTPRIO scheduling policy, .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_RTPRIO is weaker than the weakest priority in the priority ranges for any of the POSIX policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .TP .CR SCHED_OTHER " (" SCHED_HPUX ", " SCHED_TIMESHARE ) Another scheduling policy. .IP The .CR SCHED_OTHER policy, also known as .CR SCHED_HPUX and .CR SCHED_TIMESHARE , provides a way for applications to indicate, in a portable way, that they no longer need a real-time scheduling policy. .IP For processes executing under this policy, the implementation can use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_OTHER is provided as the parameter. Note that for the .CR SCHED_OTHER scheduling policy, like .CR SCHED_RTPRIO , .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_OTHER is weaker than the weakest priority in the priority ranges for any of the other policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .RE .SH RETURN VALUE The functions return the following values: .SS sched_getparam() .SS sched_rr_get_interval() .SS sched_setparam() .SS sched_yield() .SS PRI_HPUX_TO_POSIX() .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_setscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the former scheduling policy of the specified process. .TP .CR -1 Failure. The policy and scheduling parameters remain unchanged. .CR errno is set to indicate the error. .PD .RE .SS sched_getscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the scheduling policy of the specified process. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the maximum or minimum value, respectively. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS PRI_POSIX_TO_HPUX() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the the HP-UX priority corresponding to the .I sched_priority member in the .I param structure. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If the functions fail, .CR errno is set to one of the following values. .SS sched_setparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] One or more of the requested scheduling parameters is outside the range defined for the scheduling policy of the specified .IR pid . .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling parameters for the specified process, or does not have the appropriate privilege to invoke .CR sched_setparam() . .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_setscheduler() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] The value of the .I policy parameter is invalid, or one or more of the parameters contained in .I param is outside the valid range for the specified scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling policy of the specified process. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getscheduler() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_yield() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP 15 [EINVAL] The value of the .I policy parameter does not represent a defined scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .RE .SS sched_rr_get_interval() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS PRI_POSIX_TO_HPUX() .RS .TP 15 [EINVAL] The priority specified in the .I sched_priority member of the .I param argument is outside the range defined for the .CR SCHED_HPUX scheduling policy. .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS PRI_HPUX_TO_POSIX() .RS .TP 15 [EINVAL] The priority specified in the .I pri argument is not a valid HP-UX priority. .TP [ENOSYS] The function is not supported by this implementation. .RE .SH EXAMPLES Change the calling process to use the strongest .CR FIFO priority: .IP .nf .C "#include " .IP .C "struct sched_param param;" .C "int maxpri;" .IP .C "maxpri = sched_get_priority_max(SCHED_FIFO);" .C "if (maxpri == -1) {" .C " perror(""sched_get_priority_max() failed"");" .C " exit(1);" .C "}" .C "param.sched_priority = maxpri;" .C "if (sched_setscheduler(getpid(), SCHED_FIFO, ¶m) == -1) {" .C " perror(""sched_setscheduler() failed"");" .C " exit(1);" .C "}" .fi .SH AUTHOR The .CI sched_ * () functions were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .PP .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() were developed by HP. .SH SEE ALSO rtsched(1), rtprio(2). .SH STANDARDS CONFORMANCE .CR sched_get_priority_max() ": POSIX.4" .PP .CR sched_get_priority_min() ": POSIX.4" .PP .CR sched_getparam() ": POSIX.4" .PP .CR sched_getscheduler() ": POSIX.4" .PP .CR sched_rr_getinterval() ": POSIX.4" .PP .CR sched_setparam() ": POSIX.4" .PP .CR sched_setscheduler() ": POSIX.4" .PP .CR sched_yield() ": POSIX.4" .\" .\" index entries: .\" index@\f1rtsched\f1 \- real time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f4PRI_HPUX_TO_POSIX()\f1 \- return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f4PRI_POSIX_TO_HPUX()\f1 \- return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_max()\f1 \- return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_min()\f1 \- return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_getparam()\f1 \- return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_getscheduler()\f1 \- return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_rr_get_interval()\f1 \- update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4sched_setparam()\f1 \- set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_setscheduler()\f1 \- set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_yield()\f1 \- force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1operations, real-time scheduling@@@\f3rtsched(2)\f1 .\" index@\f1real-time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f1return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1scheduling operations, real-time@@@\f3rtsched(2)\f1 .\" index@\f1scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" links entries: .\" links@rtsched.2 PRI_HPUX_TO.2 .\" links@rtsched.2 PRI_POSIX_T.2 .\" links@rtsched.2 pri_hpux_to.2 .\" links@rtsched.2 pri_posix_t.2 .\" links@rtsched.2 sched_get_p.2 .\" links@rtsched.2 sched_getpa.2 .\" links@rtsched.2 sched_getsc.2 .\" links@rtsched.2 sched_rr_ge.2 .\" links@rtsched.2 sched_setpa.2 .\" links@rtsched.2 sched_setsc.2 .\" links@rtsched.2 sched_yield.2 .\" toc entries: .\" toc@\f3rtsched(2)\f1:\0\0\f4sched_get_priority_max()\f1, \f4sched_get_priority_min()\f1,\n\f4sched_getparam()\f1, \f4sched_getscheduler()\f1, \f4sched_rr_get_interval()\f1,\n\f4sched_setparam()\f1, \f4sched_setscheduler()\f1, \f4sched_yield()\f1,\n\f4PRI_HPUX_TO_POSIX()\f1, \f4PRI_POSIX_TO_HPUX()\f1@@@real-time scheduling operations .\" toc@\f4PRI_HPUX_TO_POSIX()\f1:\0\0return POSIX.4 process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4PRI_POSIX_TO_HPUX()\f1:\0\0return HP-UX process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_max()\f1:\0\0return maximum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_min()\f1:\0\0return minimum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getparam()\f1:\0\0return scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getscheduler()\f1:\0\0return scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_rr_get_interval()\f1:\0\0update execution time limit@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setparam()\f1:\0\0set scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setscheduler()\f1:\0\0set scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_yield()\f1:\0\0force process to relinquish processor@@@\f1see \f3rtsched(2)\f1 .\" $Header: rtsched.2,v 72.6 94/11/14 15:26:03 ssa Exp $ .TA r .TH rtsched 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtsched: sched_get_priority_max(), sched_get_priority_min(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setparam(), sched_setscheduler(), sched_yield(), PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX() \- real-time scheduling operations .SH SYNOPSIS .nf .C "#include " .PP .C "int sched_setparam(" .C " pid_t pid," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getparam(" .C " pid_t pid," .C " struct sched_param *param" .C ");" .PP .C "int sched_setscheduler(" .C " pid_t pid," .C " int policy," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getscheduler(" .C " pid_t pid" .C ");" .PP .C "int sched_yield();" .PP .C "int sched_get_priority_max(" .C " int policy" .C ");" .PP .C "int sched_get_priority_min(" .C " int policy" .C ");" .PP .C "int sched_rr_get_interval(" .C " pid_t pid," .C " struct timespec *interval" .C ");" .PP .C "int PRI_POSIX_TO_HPUX(" .C " const struct sched_param *param" .C ");" .PP .C "int PRI_HPUX_TO_POSIX(" .C " int pri," .C " struct sched_param *param" .C ");" .fi .SH DESCRIPTION .SS Summary .TP 35 .PD 0 .CR sched_get_priority_max() Get maximum scheduling policy .TP .CR sched_get_priority_min() Get minimum scheduling policy .TP .CR sched_getparam() Get scheduling parameters of process .TP .CR sched_getscheduler() Get scheduling policy of process .TP .CR sched_rr_get_interval() Update execution time limit for a process .TP .CR sched_setparam() Set scheduling parameters of process .TP .CR sched_setscheduler() Set scheduling policy and parameters of process .TP .CR sched_yield() Requeue current process in process list .TP .CR PRI_HPUX_TO_POSIX() Convert HP-UX priority to POSIX .TP .CR PRI_POSIX_TO_HPUX() Convert POSIX priority to HP-UX .PD .SS sched_setparam() The .CR sched_setparam() function sets the scheduling parameters of the process specified by .I pid to the values specified by the .I sched_param structure pointed to by .IR param . The value of the .I sched_priority member in the .I param structure is any integer within the inclusive priority range for the current scheduling policy of the process specified by .IR pid . .PP Higher numerical values for the priority represent higher (stronger) priorities. Note that this is different from the .CR SCHED_HPUX , .CR SCHED_TIMESHARE , and .CR SCHED_RTPRIO scheduling policies, where higher numerical values represent lower (weaker) priorities. See the .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() functions, and .CR SCHED_RTPRIO and .CR SCHED_OTHER in "Scheduling Policies" below. .PP If a process described by .I pid exists and if the calling process has permission, the scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are set for the calling process. .PP Only a superuser may change the scheduling parameters of another process. .PP The calling process must have the appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setparam() . .PP The target process, whether it is running or not running, will resume execution after all other runnable processes of equal or greater priority have been scheduled to run. .PP If the priority of the process specified by the .I pid argument is set higher than that of the lowest priority running process, and if the specified process is ready to run, the process specified by the .I pid argument will preempt a lowest-priority running process. Similarly, if the process calling .CR sched_setparam() sets its own priority lower than that of one or more other nonempty process lists, then the process that is the head of the highest priority list will also preempt the calling process. Thus, in either case, the originating process may not receive notification of the completion of the requested priority change until the higher priority process has executed. .SS sched_getparam() The .CR sched_getparam() function returns the scheduling parameters of a process specified by .I pid in the .I sched_param structure pointed to by .IR param . .PP If a process described by .I pid exists, the scheduling parameters are returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are returned for the calling process. .SS sched_setscheduler() The .CR sched_setscheduler() function sets the scheduling policy and scheduling parameters of the process specified by .I pid to .I policy and the parameters specified in the .I sched_param structure pointed to by .IR param , respectively. The value of the .I sched_priority member in the .I param structure can be any integer within the inclusive priority range for the scheduling policy specified by .IR policy . .PP The possible values for the .I policy parameter are defined in the header file .CR , and mentioned below. .PP If a process described by .I pid exists, the scheduling policy and scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy and scheduling parameters are set for the calling process. .PP Appropriate privileges are required to change the scheduling parameters of another process. .PP The calling process must have appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setscheduler() . .PP The .CR sched_setscheduler() function is considered successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by .I pid to the values specified by .I policy and the structure .IR param , respectively. .PP .SS sched_getscheduler() The .CR sched_getscheduler() function returns the scheduling policy of the process specified by .IR pid . .PP The values that can be returned by .CR sched_getscheduler() are defined in the header file .CR (see .CR sched_setscheduler() ). .PP If a process described by .I pid exists, the scheduling policy is returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy is returned for the calling process. .SS sched_yield() The .CR sched_yield() function forces the running process to relinquish the processor until it again becomes the head of its process list. It takes no arguments. .SS sched_get_priority_max() .SS sched_get_priority_min() The .CR sched_get_priority_max() and .CR sched_get_priority_min() functions return the appropriate maximum or minimum, respectively, for the scheduling policy specified by .IR policy . .PP The value of .I policy must be one of the scheduling policy values defined in .CR . .SS sched_rr_get_interval() The .CR sched_rr_get_interval() function updates the .I timespec structure referenced by the .I interval argument to contain the current execution time limit (that is, time quantum) for the process indicated by .I pid under the .CR SCHED_RR policy, at which a scheduling decision will be made when another process at the same priority is ready to execute. If .I pid is zero, the current execution time limit for the calling process is returned. .SS PRI_HPUX_TO_POSIX() .SS PRI_POSIX_TO_HPUX() These two functions serve to map (translate) the range of HP-UX priorities into the POSIX.4 model. These translations are necessary because the POSIX.4 standard chose .I larger numbers to represent stronger priorities and the existing HP-UX behavior, which must be maintained for backward compatibility, uses .I smaller numbers for stronger priorities. .PP The .CR PRI_HPUX_TO_POSIX() function returns, in the .I sched_param structure pointed to by .IR param , the POSIX.4 scheduling priority corresponding to the HP-UX priority passed in the argument .IR pri . The argument .I pri must contain a valid HP-UX priority. .PP The .CR PRI_POSIX_TO_HPUX() function returns an HP-UX process priority corresponding to the .I sched_priority member in the .I sched_param structure specified. The value of the .I sched_priority member can be any integer within the inclusive priority range for the .CR SCHED_HPUX scheduling policy. The HP-UX priority returned is comparable to the values returned by .CR getpriority() (see .IR getpriority (2)). .SS Scheduling Policies The scheduling policies described are defined in terms of a conceptual model, which contains a set of process lists. There is, conceptually, one process list for each priority. Any runnable process may be in any process list. Multiple scheduling policies are provided. Each nonempty list is ordered, and contains a head as one end of its order, and a tail as the other. The purpose of a scheduling policy is to define the allowable operations on this set of lists (for example, moving processes between and within lists). .PP Each process will be controlled by an associated scheduling policy and priority. These parameters may be specified by explicit application execution of the .CR sched_setscheduler() or .CR sched_setparam() functions. .PP Associated with each policy is a priority range. The priority ranges for each policy can (but need not) overlap the priority ranges of other policies. .PP When a process is to be selected to run, the process that is at the head of the highest priority nonempty process list is chosen. It is then removed from its process list. .PP The following scheduling policies are defined: .RS .TP 15 .CR SCHED_FIFO First in-first out (FIFO) scheduling policy. .IP Processes scheduled under this policy are chosen from a process list that is ordered by the time its processes have been in the list without being executed. Generally, the head of the list is the process that has been in the list the longest time, and the tail is the process that has been in the list the shortest time. .IP Under the .CR SCHED_FIFO policy, the modification of the definitional process lists is as follows: .RS .RS .TP 3 \(bu When a running process becomes a preempted process, it becomes the head of the process list for its priority. .TP \(bu When a blocked process becomes a runnable process, it becomes the tail of the process list for its priority. .TP \(bu When a running process calls the .CR sched_setscheduler() function, the process specified in the function call is modified to the policy and priority specified by the .I param argument. If the process whose policy and priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process calls the .CR sched_setparam() function, the priority of the process specified in the function call is modified to the priority specified by the .I param argument. If the process whose priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process issues the .CR sched_yield() function, the process becomes the tail of the process list for its priority. .TP \(bu At no other time is the position of a process with this scheduling policy within the process lists affected. .RE .RE .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_FIFO is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR Round-robin scheduling policy, with a per-system time slice (time quantum). .IP This policy is identical to the .CR SCHED_FIFO policy with the additional condition that when the implementation detects that a running process has been executing as a running process for a time period of length returned by the function .CR sched_rr_get_interval() , or longer, the process becomes the tail of its process list, and the head of that process list is removed and made a running process. .IP The effect of this policy is to ensure that if there are multiple .CR SCHED_RR processes at the same priority, one of them will not monopolize the processor. An application should not rely only on the use of .CR SCHED_RR to ensure application progress among multiple processes if the application includes processes using the .CR SCHED_FIFO policy at the same or higher priority levels, or .CR SCHED_RR processes at a higher priority level. .IP A process under this policy that is preempted and subsequently resumes execution as a running process completes the unexpired portion of its round-robin interval time period. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR2 Round-robin scheduling policy, with a per-priority time slice (time quantum). .IP This policy is identical to the .CR SCHED_RR policy, except that the round-robin time slice interval returned by .CR sched_rr_get_interval() depends upon the priority of the specified process. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RTPRIO Real-time scheduling policy with nondecaying priorities (like .CR SCHED_FIFO and .CR SCHED_RR ) with a priority range between the POSIX real-time policies and the HP-UX policies, described below (see .IR rtprio(2)). .IP For processes executing under this policy, the implementation must use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RTPRIO is provided as the parameter. Note that, for the .CR SCHED_RTPRIO scheduling policy, .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_RTPRIO is weaker than the weakest priority in the priority ranges for any of the POSIX policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .TP .CR SCHED_OTHER " (" SCHED_HPUX ", " SCHED_TIMESHARE ) Another scheduling policy. .IP The .CR SCHED_OTHER policy, also known as .CR SCHED_HPUX and .CR SCHED_TIMESHARE , provides a way for applications to indicate, in a portable way, that they no longer need a real-time scheduling policy. .IP For processes executing under this policy, the implementation can use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_OTHER is provided as the parameter. Note that for the .CR SCHED_OTHER scheduling policy, like .CR SCHED_RTPRIO , .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_OTHER is weaker than the weakest priority in the priority ranges for any of the other policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .RE .SH RETURN VALUE The functions return the following values: .SS sched_getparam() .SS sched_rr_get_interval() .SS sched_setparam() .SS sched_yield() .SS PRI_HPUX_TO_POSIX() .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_setscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the former scheduling policy of the specified process. .TP .CR -1 Failure. The policy and scheduling parameters remain unchanged. .CR errno is set to indicate the error. .PD .RE .SS sched_getscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the scheduling policy of the specified process. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the maximum or minimum value, respectively. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS PRI_POSIX_TO_HPUX() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the the HP-UX priority corresponding to the .I sched_priority member in the .I param structure. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If the functions fail, .CR errno is set to one of the following values. .SS sched_setparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] One or more of the requested scheduling parameters is outside the range defined for the scheduling policy of the specified .IR pid . .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling parameters for the specified process, or does not have the appropriate privilege to invoke .CR sched_setparam() . .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_setscheduler() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] The value of the .I policy parameter is invalid, or one or more of the parameters contained in .I param is outside the valid range for the specified scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling policy of the specified process. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getscheduler() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_yield() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP 15 [EINVAL] The value of the .I policy parameter does not represent a defined scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .RE .SS sched_rr_get_interval() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS PRI_POSIX_TO_HPUX() .RS .TP 15 [EINVAL] The priority specified in the .I sched_priority member of the .I param argument is outside the range defined for the .CR SCHED_HPUX scheduling policy. .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS PRI_HPUX_TO_POSIX() .RS .TP 15 [EINVAL] The priority specified in the .I pri argument is not a valid HP-UX priority. .TP [ENOSYS] The function is not supported by this implementation. .RE .SH EXAMPLES Change the calling process to use the strongest .CR FIFO priority: .IP .nf .C "#include " .IP .C "struct sched_param param;" .C "int maxpri;" .IP .C "maxpri = sched_get_priority_max(SCHED_FIFO);" .C "if (maxpri == -1) {" .C " perror(""sched_get_priority_max() failed"");" .C " exit(1);" .C "}" .C "param.sched_priority = maxpri;" .C "if (sched_setscheduler(getpid(), SCHED_FIFO, ¶m) == -1) {" .C " perror(""sched_setscheduler() failed"");" .C " exit(1);" .C "}" .fi .SH AUTHOR The .CI sched_ * () functions were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .PP .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() were developed by HP. .SH SEE ALSO rtsched(1), rtprio(2). .SH STANDARDS CONFORMANCE .CR sched_get_priority_max() ": POSIX.4" .PP .CR sched_get_priority_min() ": POSIX.4" .PP .CR sched_getparam() ": POSIX.4" .PP .CR sched_getscheduler() ": POSIX.4" .PP .CR sched_rr_getinterval() ": POSIX.4" .PP .CR sched_setparam() ": POSIX.4" .PP .CR sched_setscheduler() ": POSIX.4" .PP .CR sched_yield() ": POSIX.4" .\" .\" index entries: .\" index@\f1rtsched\f1 \- real time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f4PRI_HPUX_TO_POSIX()\f1 \- return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f4PRI_POSIX_TO_HPUX()\f1 \- return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_max()\f1 \- return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_min()\f1 \- return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_getparam()\f1 \- return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_getscheduler()\f1 \- return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_rr_get_interval()\f1 \- update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4sched_setparam()\f1 \- set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_setscheduler()\f1 \- set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_yield()\f1 \- force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1operations, real-time scheduling@@@\f3rtsched(2)\f1 .\" index@\f1real-time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f1return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1scheduling operations, real-time@@@\f3rtsched(2)\f1 .\" index@\f1scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" links entries: .\" links@rtsched.2 PRI_HPUX_TO.2 .\" links@rtsched.2 PRI_POSIX_T.2 .\" links@rtsched.2 pri_hpux_to.2 .\" links@rtsched.2 pri_posix_t.2 .\" links@rtsched.2 sched_get_p.2 .\" links@rtsched.2 sched_getpa.2 .\" links@rtsched.2 sched_getsc.2 .\" links@rtsched.2 sched_rr_ge.2 .\" links@rtsched.2 sched_setpa.2 .\" links@rtsched.2 sched_setsc.2 .\" links@rtsched.2 sched_yield.2 .\" toc entries: .\" toc@\f3rtsched(2)\f1:\0\0\f4sched_get_priority_max()\f1, \f4sched_get_priority_min()\f1,\n\f4sched_getparam()\f1, \f4sched_getscheduler()\f1, \f4sched_rr_get_interval()\f1,\n\f4sched_setparam()\f1, \f4sched_setscheduler()\f1, \f4sched_yield()\f1,\n\f4PRI_HPUX_TO_POSIX()\f1, \f4PRI_POSIX_TO_HPUX()\f1@@@real-time scheduling operations .\" toc@\f4PRI_HPUX_TO_POSIX()\f1:\0\0return POSIX.4 process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4PRI_POSIX_TO_HPUX()\f1:\0\0return HP-UX process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_max()\f1:\0\0return maximum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_min()\f1:\0\0return minimum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getparam()\f1:\0\0return scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getscheduler()\f1:\0\0return scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_rr_get_interval()\f1:\0\0update execution time limit@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setparam()\f1:\0\0set scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setscheduler()\f1:\0\0set scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_yield()\f1:\0\0force process to relinquish processor@@@\f1see \f3rtsched(2)\f1 .\" $Header: rtsched.2,v 72.6 94/11/14 15:26:03 ssa Exp $ .TA r .TH rtsched 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtsched: sched_get_priority_max(), sched_get_priority_min(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setparam(), sched_setscheduler(), sched_yield(), PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX() \- real-time scheduling operations .SH SYNOPSIS .nf .C "#include " .PP .C "int sched_setparam(" .C " pid_t pid," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getparam(" .C " pid_t pid," .C " struct sched_param *param" .C ");" .PP .C "int sched_setscheduler(" .C " pid_t pid," .C " int policy," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getscheduler(" .C " pid_t pid" .C ");" .PP .C "int sched_yield();" .PP .C "int sched_get_priority_max(" .C " int policy" .C ");" .PP .C "int sched_get_priority_min(" .C " int policy" .C ");" .PP .C "int sched_rr_get_interval(" .C " pid_t pid," .C " struct timespec *interval" .C ");" .PP .C "int PRI_POSIX_TO_HPUX(" .C " const struct sched_param *param" .C ");" .PP .C "int PRI_HPUX_TO_POSIX(" .C " int pri," .C " struct sched_param *param" .C ");" .fi .SH DESCRIPTION .SS Summary .TP 35 .PD 0 .CR sched_get_priority_max() Get maximum scheduling policy .TP .CR sched_get_priority_min() Get minimum scheduling policy .TP .CR sched_getparam() Get scheduling parameters of process .TP .CR sched_getscheduler() Get scheduling policy of process .TP .CR sched_rr_get_interval() Update execution time limit for a process .TP .CR sched_setparam() Set scheduling parameters of process .TP .CR sched_setscheduler() Set scheduling policy and parameters of process .TP .CR sched_yield() Requeue current process in process list .TP .CR PRI_HPUX_TO_POSIX() Convert HP-UX priority to POSIX .TP .CR PRI_POSIX_TO_HPUX() Convert POSIX priority to HP-UX .PD .SS sched_setparam() The .CR sched_setparam() function sets the scheduling parameters of the process specified by .I pid to the values specified by the .I sched_param structure pointed to by .IR param . The value of the .I sched_priority member in the .I param structure is any integer within the inclusive priority range for the current scheduling policy of the process specified by .IR pid . .PP Higher numerical values for the priority represent higher (stronger) priorities. Note that this is different from the .CR SCHED_HPUX , .CR SCHED_TIMESHARE , and .CR SCHED_RTPRIO scheduling policies, where higher numerical values represent lower (weaker) priorities. See the .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() functions, and .CR SCHED_RTPRIO and .CR SCHED_OTHER in "Scheduling Policies" below. .PP If a process described by .I pid exists and if the calling process has permission, the scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are set for the calling process. .PP Only a superuser may change the scheduling parameters of another process. .PP The calling process must have the appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setparam() . .PP The target process, whether it is running or not running, will resume execution after all other runnable processes of equal or greater priority have been scheduled to run. .PP If the priority of the process specified by the .I pid argument is set higher than that of the lowest priority running process, and if the specified process is ready to run, the process specified by the .I pid argument will preempt a lowest-priority running process. Similarly, if the process calling .CR sched_setparam() sets its own priority lower than that of one or more other nonempty process lists, then the process that is the head of the highest priority list will also preempt the calling process. Thus, in either case, the originating process may not receive notification of the completion of the requested priority change until the higher priority process has executed. .SS sched_getparam() The .CR sched_getparam() function returns the scheduling parameters of a process specified by .I pid in the .I sched_param structure pointed to by .IR param . .PP If a process described by .I pid exists, the scheduling parameters are returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are returned for the calling process. .SS sched_setscheduler() The .CR sched_setscheduler() function sets the scheduling policy and scheduling parameters of the process specified by .I pid to .I policy and the parameters specified in the .I sched_param structure pointed to by .IR param , respectively. The value of the .I sched_priority member in the .I param structure can be any integer within the inclusive priority range for the scheduling policy specified by .IR policy . .PP The possible values for the .I policy parameter are defined in the header file .CR , and mentioned below. .PP If a process described by .I pid exists, the scheduling policy and scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy and scheduling parameters are set for the calling process. .PP Appropriate privileges are required to change the scheduling parameters of another process. .PP The calling process must have appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setscheduler() . .PP The .CR sched_setscheduler() function is considered successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by .I pid to the values specified by .I policy and the structure .IR param , respectively. .PP .SS sched_getscheduler() The .CR sched_getscheduler() function returns the scheduling policy of the process specified by .IR pid . .PP The values that can be returned by .CR sched_getscheduler() are defined in the header file .CR (see .CR sched_setscheduler() ). .PP If a process described by .I pid exists, the scheduling policy is returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy is returned for the calling process. .SS sched_yield() The .CR sched_yield() function forces the running process to relinquish the processor until it again becomes the head of its process list. It takes no arguments. .SS sched_get_priority_max() .SS sched_get_priority_min() The .CR sched_get_priority_max() and .CR sched_get_priority_min() functions return the appropriate maximum or minimum, respectively, for the scheduling policy specified by .IR policy . .PP The value of .I policy must be one of the scheduling policy values defined in .CR . .SS sched_rr_get_interval() The .CR sched_rr_get_interval() function updates the .I timespec structure referenced by the .I interval argument to contain the current execution time limit (that is, time quantum) for the process indicated by .I pid under the .CR SCHED_RR policy, at which a scheduling decision will be made when another process at the same priority is ready to execute. If .I pid is zero, the current execution time limit for the calling process is returned. .SS PRI_HPUX_TO_POSIX() .SS PRI_POSIX_TO_HPUX() These two functions serve to map (translate) the range of HP-UX priorities into the POSIX.4 model. These translations are necessary because the POSIX.4 standard chose .I larger numbers to represent stronger priorities and the existing HP-UX behavior, which must be maintained for backward compatibility, uses .I smaller numbers for stronger priorities. .PP The .CR PRI_HPUX_TO_POSIX() function returns, in the .I sched_param structure pointed to by .IR param , the POSIX.4 scheduling priority corresponding to the HP-UX priority passed in the argument .IR pri . The argument .I pri must contain a valid HP-UX priority. .PP The .CR PRI_POSIX_TO_HPUX() function returns an HP-UX process priority corresponding to the .I sched_priority member in the .I sched_param structure specified. The value of the .I sched_priority member can be any integer within the inclusive priority range for the .CR SCHED_HPUX scheduling policy. The HP-UX priority returned is comparable to the values returned by .CR getpriority() (see .IR getpriority (2)). .SS Scheduling Policies The scheduling policies described are defined in terms of a conceptual model, which contains a set of process lists. There is, conceptually, one process list for each priority. Any runnable process may be in any process list. Multiple scheduling policies are provided. Each nonempty list is ordered, and contains a head as one end of its order, and a tail as the other. The purpose of a scheduling policy is to define the allowable operations on this set of lists (for example, moving processes between and within lists). .PP Each process will be controlled by an associated scheduling policy and priority. These parameters may be specified by explicit application execution of the .CR sched_setscheduler() or .CR sched_setparam() functions. .PP Associated with each policy is a priority range. The priority ranges for each policy can (but need not) overlap the priority ranges of other policies. .PP When a process is to be selected to run, the process that is at the head of the highest priority nonempty process list is chosen. It is then removed from its process list. .PP The following scheduling policies are defined: .RS .TP 15 .CR SCHED_FIFO First in-first out (FIFO) scheduling policy. .IP Processes scheduled under this policy are chosen from a process list that is ordered by the time its processes have been in the list without being executed. Generally, the head of the list is the process that has been in the list the longest time, and the tail is the process that has been in the list the shortest time. .IP Under the .CR SCHED_FIFO policy, the modification of the definitional process lists is as follows: .RS .RS .TP 3 \(bu When a running process becomes a preempted process, it becomes the head of the process list for its priority. .TP \(bu When a blocked process becomes a runnable process, it becomes the tail of the process list for its priority. .TP \(bu When a running process calls the .CR sched_setscheduler() function, the process specified in the function call is modified to the policy and priority specified by the .I param argument. If the process whose policy and priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process calls the .CR sched_setparam() function, the priority of the process specified in the function call is modified to the priority specified by the .I param argument. If the process whose priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process issues the .CR sched_yield() function, the process becomes the tail of the process list for its priority. .TP \(bu At no other time is the position of a process with this scheduling policy within the process lists affected. .RE .RE .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_FIFO is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR Round-robin scheduling policy, with a per-system time slice (time quantum). .IP This policy is identical to the .CR SCHED_FIFO policy with the additional condition that when the implementation detects that a running process has been executing as a running process for a time period of length returned by the function .CR sched_rr_get_interval() , or longer, the process becomes the tail of its process list, and the head of that process list is removed and made a running process. .IP The effect of this policy is to ensure that if there are multiple .CR SCHED_RR processes at the same priority, one of them will not monopolize the processor. An application should not rely only on the use of .CR SCHED_RR to ensure application progress among multiple processes if the application includes processes using the .CR SCHED_FIFO policy at the same or higher priority levels, or .CR SCHED_RR processes at a higher priority level. .IP A process under this policy that is preempted and subsequently resumes execution as a running process completes the unexpired portion of its round-robin interval time period. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR2 Round-robin scheduling policy, with a per-priority time slice (time quantum). .IP This policy is identical to the .CR SCHED_RR policy, except that the round-robin time slice interval returned by .CR sched_rr_get_interval() depends upon the priority of the specified process. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RTPRIO Real-time scheduling policy with nondecaying priorities (like .CR SCHED_FIFO and .CR SCHED_RR ) with a priority range between the POSIX real-time policies and the HP-UX policies, described below (see .IR rtprio(2)). .IP For processes executing under this policy, the implementation must use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RTPRIO is provided as the parameter. Note that, for the .CR SCHED_RTPRIO scheduling policy, .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_RTPRIO is weaker than the weakest priority in the priority ranges for any of the POSIX policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .TP .CR SCHED_OTHER " (" SCHED_HPUX ", " SCHED_TIMESHARE ) Another scheduling policy. .IP The .CR SCHED_OTHER policy, also known as .CR SCHED_HPUX and .CR SCHED_TIMESHARE , provides a way for applications to indicate, in a portable way, that they no longer need a real-time scheduling policy. .IP For processes executing under this policy, the implementation can use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_OTHER is provided as the parameter. Note that for the .CR SCHED_OTHER scheduling policy, like .CR SCHED_RTPRIO , .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_OTHER is weaker than the weakest priority in the priority ranges for any of the other policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .RE .SH RETURN VALUE The functions return the following values: .SS sched_getparam() .SS sched_rr_get_interval() .SS sched_setparam() .SS sched_yield() .SS PRI_HPUX_TO_POSIX() .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_setscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the former scheduling policy of the specified process. .TP .CR -1 Failure. The policy and scheduling parameters remain unchanged. .CR errno is set to indicate the error. .PD .RE .SS sched_getscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the scheduling policy of the specified process. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the maximum or minimum value, respectively. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS PRI_POSIX_TO_HPUX() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the the HP-UX priority corresponding to the .I sched_priority member in the .I param structure. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If the functions fail, .CR errno is set to one of the following values. .SS sched_setparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] One or more of the requested scheduling parameters is outside the range defined for the scheduling policy of the specified .IR pid . .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling parameters for the specified process, or does not have the appropriate privilege to invoke .CR sched_setparam() . .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_setscheduler() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] The value of the .I policy parameter is invalid, or one or more of the parameters contained in .I param is outside the valid range for the specified scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling policy of the specified process. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getscheduler() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_yield() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP 15 [EINVAL] The value of the .I policy parameter does not represent a defined scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .RE .SS sched_rr_get_interval() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS PRI_POSIX_TO_HPUX() .RS .TP 15 [EINVAL] The priority specified in the .I sched_priority member of the .I param argument is outside the range defined for the .CR SCHED_HPUX scheduling policy. .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS PRI_HPUX_TO_POSIX() .RS .TP 15 [EINVAL] The priority specified in the .I pri argument is not a valid HP-UX priority. .TP [ENOSYS] The function is not supported by this implementation. .RE .SH EXAMPLES Change the calling process to use the strongest .CR FIFO priority: .IP .nf .C "#include " .IP .C "struct sched_param param;" .C "int maxpri;" .IP .C "maxpri = sched_get_priority_max(SCHED_FIFO);" .C "if (maxpri == -1) {" .C " perror(""sched_get_priority_max() failed"");" .C " exit(1);" .C "}" .C "param.sched_priority = maxpri;" .C "if (sched_setscheduler(getpid(), SCHED_FIFO, ¶m) == -1) {" .C " perror(""sched_setscheduler() failed"");" .C " exit(1);" .C "}" .fi .SH AUTHOR The .CI sched_ * () functions were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .PP .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() were developed by HP. .SH SEE ALSO rtsched(1), rtprio(2). .SH STANDARDS CONFORMANCE .CR sched_get_priority_max() ": POSIX.4" .PP .CR sched_get_priority_min() ": POSIX.4" .PP .CR sched_getparam() ": POSIX.4" .PP .CR sched_getscheduler() ": POSIX.4" .PP .CR sched_rr_getinterval() ": POSIX.4" .PP .CR sched_setparam() ": POSIX.4" .PP .CR sched_setscheduler() ": POSIX.4" .PP .CR sched_yield() ": POSIX.4" .\" .\" index entries: .\" index@\f1rtsched\f1 \- real time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f4PRI_HPUX_TO_POSIX()\f1 \- return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f4PRI_POSIX_TO_HPUX()\f1 \- return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_max()\f1 \- return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_min()\f1 \- return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_getparam()\f1 \- return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_getscheduler()\f1 \- return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_rr_get_interval()\f1 \- update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4sched_setparam()\f1 \- set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_setscheduler()\f1 \- set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_yield()\f1 \- force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1operations, real-time scheduling@@@\f3rtsched(2)\f1 .\" index@\f1real-time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f1return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1scheduling operations, real-time@@@\f3rtsched(2)\f1 .\" index@\f1scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" links entries: .\" links@rtsched.2 PRI_HPUX_TO.2 .\" links@rtsched.2 PRI_POSIX_T.2 .\" links@rtsched.2 pri_hpux_to.2 .\" links@rtsched.2 pri_posix_t.2 .\" links@rtsched.2 sched_get_p.2 .\" links@rtsched.2 sched_getpa.2 .\" links@rtsched.2 sched_getsc.2 .\" links@rtsched.2 sched_rr_ge.2 .\" links@rtsched.2 sched_setpa.2 .\" links@rtsched.2 sched_setsc.2 .\" links@rtsched.2 sched_yield.2 .\" toc entries: .\" toc@\f3rtsched(2)\f1:\0\0\f4sched_get_priority_max()\f1, \f4sched_get_priority_min()\f1,\n\f4sched_getparam()\f1, \f4sched_getscheduler()\f1, \f4sched_rr_get_interval()\f1,\n\f4sched_setparam()\f1, \f4sched_setscheduler()\f1, \f4sched_yield()\f1,\n\f4PRI_HPUX_TO_POSIX()\f1, \f4PRI_POSIX_TO_HPUX()\f1@@@real-time scheduling operations .\" toc@\f4PRI_HPUX_TO_POSIX()\f1:\0\0return POSIX.4 process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4PRI_POSIX_TO_HPUX()\f1:\0\0return HP-UX process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_max()\f1:\0\0return maximum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_min()\f1:\0\0return minimum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getparam()\f1:\0\0return scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getscheduler()\f1:\0\0return scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_rr_get_interval()\f1:\0\0update execution time limit@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setparam()\f1:\0\0set scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setscheduler()\f1:\0\0set scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_yield()\f1:\0\0force process to relinquish processor@@@\f1see \f3rtsched(2)\f1 .\" $Header: rtsched.2,v 72.6 94/11/14 15:26:03 ssa Exp $ .TA r .TH rtsched 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtsched: sched_get_priority_max(), sched_get_priority_min(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setparam(), sched_setscheduler(), sched_yield(), PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX() \- real-time scheduling operations .SH SYNOPSIS .nf .C "#include " .PP .C "int sched_setparam(" .C " pid_t pid," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getparam(" .C " pid_t pid," .C " struct sched_param *param" .C ");" .PP .C "int sched_setscheduler(" .C " pid_t pid," .C " int policy," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getscheduler(" .C " pid_t pid" .C ");" .PP .C "int sched_yield();" .PP .C "int sched_get_priority_max(" .C " int policy" .C ");" .PP .C "int sched_get_priority_min(" .C " int policy" .C ");" .PP .C "int sched_rr_get_interval(" .C " pid_t pid," .C " struct timespec *interval" .C ");" .PP .C "int PRI_POSIX_TO_HPUX(" .C " const struct sched_param *param" .C ");" .PP .C "int PRI_HPUX_TO_POSIX(" .C " int pri," .C " struct sched_param *param" .C ");" .fi .SH DESCRIPTION .SS Summary .TP 35 .PD 0 .CR sched_get_priority_max() Get maximum scheduling policy .TP .CR sched_get_priority_min() Get minimum scheduling policy .TP .CR sched_getparam() Get scheduling parameters of process .TP .CR sched_getscheduler() Get scheduling policy of process .TP .CR sched_rr_get_interval() Update execution time limit for a process .TP .CR sched_setparam() Set scheduling parameters of process .TP .CR sched_setscheduler() Set scheduling policy and parameters of process .TP .CR sched_yield() Requeue current process in process list .TP .CR PRI_HPUX_TO_POSIX() Convert HP-UX priority to POSIX .TP .CR PRI_POSIX_TO_HPUX() Convert POSIX priority to HP-UX .PD .SS sched_setparam() The .CR sched_setparam() function sets the scheduling parameters of the process specified by .I pid to the values specified by the .I sched_param structure pointed to by .IR param . The value of the .I sched_priority member in the .I param structure is any integer within the inclusive priority range for the current scheduling policy of the process specified by .IR pid . .PP Higher numerical values for the priority represent higher (stronger) priorities. Note that this is different from the .CR SCHED_HPUX , .CR SCHED_TIMESHARE , and .CR SCHED_RTPRIO scheduling policies, where higher numerical values represent lower (weaker) priorities. See the .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() functions, and .CR SCHED_RTPRIO and .CR SCHED_OTHER in "Scheduling Policies" below. .PP If a process described by .I pid exists and if the calling process has permission, the scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are set for the calling process. .PP Only a superuser may change the scheduling parameters of another process. .PP The calling process must have the appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setparam() . .PP The target process, whether it is running or not running, will resume execution after all other runnable processes of equal or greater priority have been scheduled to run. .PP If the priority of the process specified by the .I pid argument is set higher than that of the lowest priority running process, and if the specified process is ready to run, the process specified by the .I pid argument will preempt a lowest-priority running process. Similarly, if the process calling .CR sched_setparam() sets its own priority lower than that of one or more other nonempty process lists, then the process that is the head of the highest priority list will also preempt the calling process. Thus, in either case, the originating process may not receive notification of the completion of the requested priority change until the higher priority process has executed. .SS sched_getparam() The .CR sched_getparam() function returns the scheduling parameters of a process specified by .I pid in the .I sched_param structure pointed to by .IR param . .PP If a process described by .I pid exists, the scheduling parameters are returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are returned for the calling process. .SS sched_setscheduler() The .CR sched_setscheduler() function sets the scheduling policy and scheduling parameters of the process specified by .I pid to .I policy and the parameters specified in the .I sched_param structure pointed to by .IR param , respectively. The value of the .I sched_priority member in the .I param structure can be any integer within the inclusive priority range for the scheduling policy specified by .IR policy . .PP The possible values for the .I policy parameter are defined in the header file .CR , and mentioned below. .PP If a process described by .I pid exists, the scheduling policy and scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy and scheduling parameters are set for the calling process. .PP Appropriate privileges are required to change the scheduling parameters of another process. .PP The calling process must have appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setscheduler() . .PP The .CR sched_setscheduler() function is considered successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by .I pid to the values specified by .I policy and the structure .IR param , respectively. .PP .SS sched_getscheduler() The .CR sched_getscheduler() function returns the scheduling policy of the process specified by .IR pid . .PP The values that can be returned by .CR sched_getscheduler() are defined in the header file .CR (see .CR sched_setscheduler() ). .PP If a process described by .I pid exists, the scheduling policy is returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy is returned for the calling process. .SS sched_yield() The .CR sched_yield() function forces the running process to relinquish the processor until it again becomes the head of its process list. It takes no arguments. .SS sched_get_priority_max() .SS sched_get_priority_min() The .CR sched_get_priority_max() and .CR sched_get_priority_min() functions return the appropriate maximum or minimum, respectively, for the scheduling policy specified by .IR policy . .PP The value of .I policy must be one of the scheduling policy values defined in .CR . .SS sched_rr_get_interval() The .CR sched_rr_get_interval() function updates the .I timespec structure referenced by the .I interval argument to contain the current execution time limit (that is, time quantum) for the process indicated by .I pid under the .CR SCHED_RR policy, at which a scheduling decision will be made when another process at the same priority is ready to execute. If .I pid is zero, the current execution time limit for the calling process is returned. .SS PRI_HPUX_TO_POSIX() .SS PRI_POSIX_TO_HPUX() These two functions serve to map (translate) the range of HP-UX priorities into the POSIX.4 model. These translations are necessary because the POSIX.4 standard chose .I larger numbers to represent stronger priorities and the existing HP-UX behavior, which must be maintained for backward compatibility, uses .I smaller numbers for stronger priorities. .PP The .CR PRI_HPUX_TO_POSIX() function returns, in the .I sched_param structure pointed to by .IR param , the POSIX.4 scheduling priority corresponding to the HP-UX priority passed in the argument .IR pri . The argument .I pri must contain a valid HP-UX priority. .PP The .CR PRI_POSIX_TO_HPUX() function returns an HP-UX process priority corresponding to the .I sched_priority member in the .I sched_param structure specified. The value of the .I sched_priority member can be any integer within the inclusive priority range for the .CR SCHED_HPUX scheduling policy. The HP-UX priority returned is comparable to the values returned by .CR getpriority() (see .IR getpriority (2)). .SS Scheduling Policies The scheduling policies described are defined in terms of a conceptual model, which contains a set of process lists. There is, conceptually, one process list for each priority. Any runnable process may be in any process list. Multiple scheduling policies are provided. Each nonempty list is ordered, and contains a head as one end of its order, and a tail as the other. The purpose of a scheduling policy is to define the allowable operations on this set of lists (for example, moving processes between and within lists). .PP Each process will be controlled by an associated scheduling policy and priority. These parameters may be specified by explicit application execution of the .CR sched_setscheduler() or .CR sched_setparam() functions. .PP Associated with each policy is a priority range. The priority ranges for each policy can (but need not) overlap the priority ranges of other policies. .PP When a process is to be selected to run, the process that is at the head of the highest priority nonempty process list is chosen. It is then removed from its process list. .PP The following scheduling policies are defined: .RS .TP 15 .CR SCHED_FIFO First in-first out (FIFO) scheduling policy. .IP Processes scheduled under this policy are chosen from a process list that is ordered by the time its processes have been in the list without being executed. Generally, the head of the list is the process that has been in the list the longest time, and the tail is the process that has been in the list the shortest time. .IP Under the .CR SCHED_FIFO policy, the modification of the definitional process lists is as follows: .RS .RS .TP 3 \(bu When a running process becomes a preempted process, it becomes the head of the process list for its priority. .TP \(bu When a blocked process becomes a runnable process, it becomes the tail of the process list for its priority. .TP \(bu When a running process calls the .CR sched_setscheduler() function, the process specified in the function call is modified to the policy and priority specified by the .I param argument. If the process whose policy and priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process calls the .CR sched_setparam() function, the priority of the process specified in the function call is modified to the priority specified by the .I param argument. If the process whose priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process issues the .CR sched_yield() function, the process becomes the tail of the process list for its priority. .TP \(bu At no other time is the position of a process with this scheduling policy within the process lists affected. .RE .RE .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_FIFO is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR Round-robin scheduling policy, with a per-system time slice (time quantum). .IP This policy is identical to the .CR SCHED_FIFO policy with the additional condition that when the implementation detects that a running process has been executing as a running process for a time period of length returned by the function .CR sched_rr_get_interval() , or longer, the process becomes the tail of its process list, and the head of that process list is removed and made a running process. .IP The effect of this policy is to ensure that if there are multiple .CR SCHED_RR processes at the same priority, one of them will not monopolize the processor. An application should not rely only on the use of .CR SCHED_RR to ensure application progress among multiple processes if the application includes processes using the .CR SCHED_FIFO policy at the same or higher priority levels, or .CR SCHED_RR processes at a higher priority level. .IP A process under this policy that is preempted and subsequently resumes execution as a running process completes the unexpired portion of its round-robin interval time period. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR2 Round-robin scheduling policy, with a per-priority time slice (time quantum). .IP This policy is identical to the .CR SCHED_RR policy, except that the round-robin time slice interval returned by .CR sched_rr_get_interval() depends upon the priority of the specified process. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RTPRIO Real-time scheduling policy with nondecaying priorities (like .CR SCHED_FIFO and .CR SCHED_RR ) with a priority range between the POSIX real-time policies and the HP-UX policies, described below (see .IR rtprio(2)). .IP For processes executing under this policy, the implementation must use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RTPRIO is provided as the parameter. Note that, for the .CR SCHED_RTPRIO scheduling policy, .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_RTPRIO is weaker than the weakest priority in the priority ranges for any of the POSIX policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .TP .CR SCHED_OTHER " (" SCHED_HPUX ", " SCHED_TIMESHARE ) Another scheduling policy. .IP The .CR SCHED_OTHER policy, also known as .CR SCHED_HPUX and .CR SCHED_TIMESHARE , provides a way for applications to indicate, in a portable way, that they no longer need a real-time scheduling policy. .IP For processes executing under this policy, the implementation can use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_OTHER is provided as the parameter. Note that for the .CR SCHED_OTHER scheduling policy, like .CR SCHED_RTPRIO , .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_OTHER is weaker than the weakest priority in the priority ranges for any of the other policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .RE .SH RETURN VALUE The functions return the following values: .SS sched_getparam() .SS sched_rr_get_interval() .SS sched_setparam() .SS sched_yield() .SS PRI_HPUX_TO_POSIX() .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_setscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the former scheduling policy of the specified process. .TP .CR -1 Failure. The policy and scheduling parameters remain unchanged. .CR errno is set to indicate the error. .PD .RE .SS sched_getscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the scheduling policy of the specified process. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the maximum or minimum value, respectively. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS PRI_POSIX_TO_HPUX() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the the HP-UX priority corresponding to the .I sched_priority member in the .I param structure. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If the functions fail, .CR errno is set to one of the following values. .SS sched_setparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] One or more of the requested scheduling parameters is outside the range defined for the scheduling policy of the specified .IR pid . .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling parameters for the specified process, or does not have the appropriate privilege to invoke .CR sched_setparam() . .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_setscheduler() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] The value of the .I policy parameter is invalid, or one or more of the parameters contained in .I param is outside the valid range for the specified scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling policy of the specified process. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getscheduler() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_yield() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP 15 [EINVAL] The value of the .I policy parameter does not represent a defined scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .RE .SS sched_rr_get_interval() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS PRI_POSIX_TO_HPUX() .RS .TP 15 [EINVAL] The priority specified in the .I sched_priority member of the .I param argument is outside the range defined for the .CR SCHED_HPUX scheduling policy. .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS PRI_HPUX_TO_POSIX() .RS .TP 15 [EINVAL] The priority specified in the .I pri argument is not a valid HP-UX priority. .TP [ENOSYS] The function is not supported by this implementation. .RE .SH EXAMPLES Change the calling process to use the strongest .CR FIFO priority: .IP .nf .C "#include " .IP .C "struct sched_param param;" .C "int maxpri;" .IP .C "maxpri = sched_get_priority_max(SCHED_FIFO);" .C "if (maxpri == -1) {" .C " perror(""sched_get_priority_max() failed"");" .C " exit(1);" .C "}" .C "param.sched_priority = maxpri;" .C "if (sched_setscheduler(getpid(), SCHED_FIFO, ¶m) == -1) {" .C " perror(""sched_setscheduler() failed"");" .C " exit(1);" .C "}" .fi .SH AUTHOR The .CI sched_ * () functions were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .PP .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() were developed by HP. .SH SEE ALSO rtsched(1), rtprio(2). .SH STANDARDS CONFORMANCE .CR sched_get_priority_max() ": POSIX.4" .PP .CR sched_get_priority_min() ": POSIX.4" .PP .CR sched_getparam() ": POSIX.4" .PP .CR sched_getscheduler() ": POSIX.4" .PP .CR sched_rr_getinterval() ": POSIX.4" .PP .CR sched_setparam() ": POSIX.4" .PP .CR sched_setscheduler() ": POSIX.4" .PP .CR sched_yield() ": POSIX.4" .\" .\" index entries: .\" index@\f1rtsched\f1 \- real time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f4PRI_HPUX_TO_POSIX()\f1 \- return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f4PRI_POSIX_TO_HPUX()\f1 \- return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_max()\f1 \- return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_min()\f1 \- return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_getparam()\f1 \- return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_getscheduler()\f1 \- return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_rr_get_interval()\f1 \- update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4sched_setparam()\f1 \- set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_setscheduler()\f1 \- set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_yield()\f1 \- force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1operations, real-time scheduling@@@\f3rtsched(2)\f1 .\" index@\f1real-time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f1return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1scheduling operations, real-time@@@\f3rtsched(2)\f1 .\" index@\f1scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" links entries: .\" links@rtsched.2 PRI_HPUX_TO.2 .\" links@rtsched.2 PRI_POSIX_T.2 .\" links@rtsched.2 pri_hpux_to.2 .\" links@rtsched.2 pri_posix_t.2 .\" links@rtsched.2 sched_get_p.2 .\" links@rtsched.2 sched_getpa.2 .\" links@rtsched.2 sched_getsc.2 .\" links@rtsched.2 sched_rr_ge.2 .\" links@rtsched.2 sched_setpa.2 .\" links@rtsched.2 sched_setsc.2 .\" links@rtsched.2 sched_yield.2 .\" toc entries: .\" toc@\f3rtsched(2)\f1:\0\0\f4sched_get_priority_max()\f1, \f4sched_get_priority_min()\f1,\n\f4sched_getparam()\f1, \f4sched_getscheduler()\f1, \f4sched_rr_get_interval()\f1,\n\f4sched_setparam()\f1, \f4sched_setscheduler()\f1, \f4sched_yield()\f1,\n\f4PRI_HPUX_TO_POSIX()\f1, \f4PRI_POSIX_TO_HPUX()\f1@@@real-time scheduling operations .\" toc@\f4PRI_HPUX_TO_POSIX()\f1:\0\0return POSIX.4 process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4PRI_POSIX_TO_HPUX()\f1:\0\0return HP-UX process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_max()\f1:\0\0return maximum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_min()\f1:\0\0return minimum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getparam()\f1:\0\0return scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getscheduler()\f1:\0\0return scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_rr_get_interval()\f1:\0\0update execution time limit@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setparam()\f1:\0\0set scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setscheduler()\f1:\0\0set scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_yield()\f1:\0\0force process to relinquish processor@@@\f1see \f3rtsched(2)\f1 .\" $Header: rtsched.2,v 72.6 94/11/14 15:26:03 ssa Exp $ .TA r .TH rtsched 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtsched: sched_get_priority_max(), sched_get_priority_min(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setparam(), sched_setscheduler(), sched_yield(), PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX() \- real-time scheduling operations .SH SYNOPSIS .nf .C "#include " .PP .C "int sched_setparam(" .C " pid_t pid," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getparam(" .C " pid_t pid," .C " struct sched_param *param" .C ");" .PP .C "int sched_setscheduler(" .C " pid_t pid," .C " int policy," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getscheduler(" .C " pid_t pid" .C ");" .PP .C "int sched_yield();" .PP .C "int sched_get_priority_max(" .C " int policy" .C ");" .PP .C "int sched_get_priority_min(" .C " int policy" .C ");" .PP .C "int sched_rr_get_interval(" .C " pid_t pid," .C " struct timespec *interval" .C ");" .PP .C "int PRI_POSIX_TO_HPUX(" .C " const struct sched_param *param" .C ");" .PP .C "int PRI_HPUX_TO_POSIX(" .C " int pri," .C " struct sched_param *param" .C ");" .fi .SH DESCRIPTION .SS Summary .TP 35 .PD 0 .CR sched_get_priority_max() Get maximum scheduling policy .TP .CR sched_get_priority_min() Get minimum scheduling policy .TP .CR sched_getparam() Get scheduling parameters of process .TP .CR sched_getscheduler() Get scheduling policy of process .TP .CR sched_rr_get_interval() Update execution time limit for a process .TP .CR sched_setparam() Set scheduling parameters of process .TP .CR sched_setscheduler() Set scheduling policy and parameters of process .TP .CR sched_yield() Requeue current process in process list .TP .CR PRI_HPUX_TO_POSIX() Convert HP-UX priority to POSIX .TP .CR PRI_POSIX_TO_HPUX() Convert POSIX priority to HP-UX .PD .SS sched_setparam() The .CR sched_setparam() function sets the scheduling parameters of the process specified by .I pid to the values specified by the .I sched_param structure pointed to by .IR param . The value of the .I sched_priority member in the .I param structure is any integer within the inclusive priority range for the current scheduling policy of the process specified by .IR pid . .PP Higher numerical values for the priority represent higher (stronger) priorities. Note that this is different from the .CR SCHED_HPUX , .CR SCHED_TIMESHARE , and .CR SCHED_RTPRIO scheduling policies, where higher numerical values represent lower (weaker) priorities. See the .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() functions, and .CR SCHED_RTPRIO and .CR SCHED_OTHER in "Scheduling Policies" below. .PP If a process described by .I pid exists and if the calling process has permission, the scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are set for the calling process. .PP Only a superuser may change the scheduling parameters of another process. .PP The calling process must have the appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setparam() . .PP The target process, whether it is running or not running, will resume execution after all other runnable processes of equal or greater priority have been scheduled to run. .PP If the priority of the process specified by the .I pid argument is set higher than that of the lowest priority running process, and if the specified process is ready to run, the process specified by the .I pid argument will preempt a lowest-priority running process. Similarly, if the process calling .CR sched_setparam() sets its own priority lower than that of one or more other nonempty process lists, then the process that is the head of the highest priority list will also preempt the calling process. Thus, in either case, the originating process may not receive notification of the completion of the requested priority change until the higher priority process has executed. .SS sched_getparam() The .CR sched_getparam() function returns the scheduling parameters of a process specified by .I pid in the .I sched_param structure pointed to by .IR param . .PP If a process described by .I pid exists, the scheduling parameters are returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are returned for the calling process. .SS sched_setscheduler() The .CR sched_setscheduler() function sets the scheduling policy and scheduling parameters of the process specified by .I pid to .I policy and the parameters specified in the .I sched_param structure pointed to by .IR param , respectively. The value of the .I sched_priority member in the .I param structure can be any integer within the inclusive priority range for the scheduling policy specified by .IR policy . .PP The possible values for the .I policy parameter are defined in the header file .CR , and mentioned below. .PP If a process described by .I pid exists, the scheduling policy and scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy and scheduling parameters are set for the calling process. .PP Appropriate privileges are required to change the scheduling parameters of another process. .PP The calling process must have appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setscheduler() . .PP The .CR sched_setscheduler() function is considered successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by .I pid to the values specified by .I policy and the structure .IR param , respectively. .PP .SS sched_getscheduler() The .CR sched_getscheduler() function returns the scheduling policy of the process specified by .IR pid . .PP The values that can be returned by .CR sched_getscheduler() are defined in the header file .CR (see .CR sched_setscheduler() ). .PP If a process described by .I pid exists, the scheduling policy is returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy is returned for the calling process. .SS sched_yield() The .CR sched_yield() function forces the running process to relinquish the processor until it again becomes the head of its process list. It takes no arguments. .SS sched_get_priority_max() .SS sched_get_priority_min() The .CR sched_get_priority_max() and .CR sched_get_priority_min() functions return the appropriate maximum or minimum, respectively, for the scheduling policy specified by .IR policy . .PP The value of .I policy must be one of the scheduling policy values defined in .CR . .SS sched_rr_get_interval() The .CR sched_rr_get_interval() function updates the .I timespec structure referenced by the .I interval argument to contain the current execution time limit (that is, time quantum) for the process indicated by .I pid under the .CR SCHED_RR policy, at which a scheduling decision will be made when another process at the same priority is ready to execute. If .I pid is zero, the current execution time limit for the calling process is returned. .SS PRI_HPUX_TO_POSIX() .SS PRI_POSIX_TO_HPUX() These two functions serve to map (translate) the range of HP-UX priorities into the POSIX.4 model. These translations are necessary because the POSIX.4 standard chose .I larger numbers to represent stronger priorities and the existing HP-UX behavior, which must be maintained for backward compatibility, uses .I smaller numbers for stronger priorities. .PP The .CR PRI_HPUX_TO_POSIX() function returns, in the .I sched_param structure pointed to by .IR param , the POSIX.4 scheduling priority corresponding to the HP-UX priority passed in the argument .IR pri . The argument .I pri must contain a valid HP-UX priority. .PP The .CR PRI_POSIX_TO_HPUX() function returns an HP-UX process priority corresponding to the .I sched_priority member in the .I sched_param structure specified. The value of the .I sched_priority member can be any integer within the inclusive priority range for the .CR SCHED_HPUX scheduling policy. The HP-UX priority returned is comparable to the values returned by .CR getpriority() (see .IR getpriority (2)). .SS Scheduling Policies The scheduling policies described are defined in terms of a conceptual model, which contains a set of process lists. There is, conceptually, one process list for each priority. Any runnable process may be in any process list. Multiple scheduling policies are provided. Each nonempty list is ordered, and contains a head as one end of its order, and a tail as the other. The purpose of a scheduling policy is to define the allowable operations on this set of lists (for example, moving processes between and within lists). .PP Each process will be controlled by an associated scheduling policy and priority. These parameters may be specified by explicit application execution of the .CR sched_setscheduler() or .CR sched_setparam() functions. .PP Associated with each policy is a priority range. The priority ranges for each policy can (but need not) overlap the priority ranges of other policies. .PP When a process is to be selected to run, the process that is at the head of the highest priority nonempty process list is chosen. It is then removed from its process list. .PP The following scheduling policies are defined: .RS .TP 15 .CR SCHED_FIFO First in-first out (FIFO) scheduling policy. .IP Processes scheduled under this policy are chosen from a process list that is ordered by the time its processes have been in the list without being executed. Generally, the head of the list is the process that has been in the list the longest time, and the tail is the process that has been in the list the shortest time. .IP Under the .CR SCHED_FIFO policy, the modification of the definitional process lists is as follows: .RS .RS .TP 3 \(bu When a running process becomes a preempted process, it becomes the head of the process list for its priority. .TP \(bu When a blocked process becomes a runnable process, it becomes the tail of the process list for its priority. .TP \(bu When a running process calls the .CR sched_setscheduler() function, the process specified in the function call is modified to the policy and priority specified by the .I param argument. If the process whose policy and priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process calls the .CR sched_setparam() function, the priority of the process specified in the function call is modified to the priority specified by the .I param argument. If the process whose priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process issues the .CR sched_yield() function, the process becomes the tail of the process list for its priority. .TP \(bu At no other time is the position of a process with this scheduling policy within the process lists affected. .RE .RE .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_FIFO is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR Round-robin scheduling policy, with a per-system time slice (time quantum). .IP This policy is identical to the .CR SCHED_FIFO policy with the additional condition that when the implementation detects that a running process has been executing as a running process for a time period of length returned by the function .CR sched_rr_get_interval() , or longer, the process becomes the tail of its process list, and the head of that process list is removed and made a running process. .IP The effect of this policy is to ensure that if there are multiple .CR SCHED_RR processes at the same priority, one of them will not monopolize the processor. An application should not rely only on the use of .CR SCHED_RR to ensure application progress among multiple processes if the application includes processes using the .CR SCHED_FIFO policy at the same or higher priority levels, or .CR SCHED_RR processes at a higher priority level. .IP A process under this policy that is preempted and subsequently resumes execution as a running process completes the unexpired portion of its round-robin interval time period. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR2 Round-robin scheduling policy, with a per-priority time slice (time quantum). .IP This policy is identical to the .CR SCHED_RR policy, except that the round-robin time slice interval returned by .CR sched_rr_get_interval() depends upon the priority of the specified process. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RTPRIO Real-time scheduling policy with nondecaying priorities (like .CR SCHED_FIFO and .CR SCHED_RR ) with a priority range between the POSIX real-time policies and the HP-UX policies, described below (see .IR rtprio(2)). .IP For processes executing under this policy, the implementation must use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RTPRIO is provided as the parameter. Note that, for the .CR SCHED_RTPRIO scheduling policy, .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_RTPRIO is weaker than the weakest priority in the priority ranges for any of the POSIX policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .TP .CR SCHED_OTHER " (" SCHED_HPUX ", " SCHED_TIMESHARE ) Another scheduling policy. .IP The .CR SCHED_OTHER policy, also known as .CR SCHED_HPUX and .CR SCHED_TIMESHARE , provides a way for applications to indicate, in a portable way, that they no longer need a real-time scheduling policy. .IP For processes executing under this policy, the implementation can use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_OTHER is provided as the parameter. Note that for the .CR SCHED_OTHER scheduling policy, like .CR SCHED_RTPRIO , .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_OTHER is weaker than the weakest priority in the priority ranges for any of the other policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .RE .SH RETURN VALUE The functions return the following values: .SS sched_getparam() .SS sched_rr_get_interval() .SS sched_setparam() .SS sched_yield() .SS PRI_HPUX_TO_POSIX() .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_setscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the former scheduling policy of the specified process. .TP .CR -1 Failure. The policy and scheduling parameters remain unchanged. .CR errno is set to indicate the error. .PD .RE .SS sched_getscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the scheduling policy of the specified process. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the maximum or minimum value, respectively. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS PRI_POSIX_TO_HPUX() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the the HP-UX priority corresponding to the .I sched_priority member in the .I param structure. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If the functions fail, .CR errno is set to one of the following values. .SS sched_setparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] One or more of the requested scheduling parameters is outside the range defined for the scheduling policy of the specified .IR pid . .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling parameters for the specified process, or does not have the appropriate privilege to invoke .CR sched_setparam() . .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_setscheduler() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] The value of the .I policy parameter is invalid, or one or more of the parameters contained in .I param is outside the valid range for the specified scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling policy of the specified process. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getscheduler() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_yield() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP 15 [EINVAL] The value of the .I policy parameter does not represent a defined scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .RE .SS sched_rr_get_interval() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS PRI_POSIX_TO_HPUX() .RS .TP 15 [EINVAL] The priority specified in the .I sched_priority member of the .I param argument is outside the range defined for the .CR SCHED_HPUX scheduling policy. .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS PRI_HPUX_TO_POSIX() .RS .TP 15 [EINVAL] The priority specified in the .I pri argument is not a valid HP-UX priority. .TP [ENOSYS] The function is not supported by this implementation. .RE .SH EXAMPLES Change the calling process to use the strongest .CR FIFO priority: .IP .nf .C "#include " .IP .C "struct sched_param param;" .C "int maxpri;" .IP .C "maxpri = sched_get_priority_max(SCHED_FIFO);" .C "if (maxpri == -1) {" .C " perror(""sched_get_priority_max() failed"");" .C " exit(1);" .C "}" .C "param.sched_priority = maxpri;" .C "if (sched_setscheduler(getpid(), SCHED_FIFO, ¶m) == -1) {" .C " perror(""sched_setscheduler() failed"");" .C " exit(1);" .C "}" .fi .SH AUTHOR The .CI sched_ * () functions were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .PP .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() were developed by HP. .SH SEE ALSO rtsched(1), rtprio(2). .SH STANDARDS CONFORMANCE .CR sched_get_priority_max() ": POSIX.4" .PP .CR sched_get_priority_min() ": POSIX.4" .PP .CR sched_getparam() ": POSIX.4" .PP .CR sched_getscheduler() ": POSIX.4" .PP .CR sched_rr_getinterval() ": POSIX.4" .PP .CR sched_setparam() ": POSIX.4" .PP .CR sched_setscheduler() ": POSIX.4" .PP .CR sched_yield() ": POSIX.4" .\" .\" index entries: .\" index@\f1rtsched\f1 \- real time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f4PRI_HPUX_TO_POSIX()\f1 \- return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f4PRI_POSIX_TO_HPUX()\f1 \- return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_max()\f1 \- return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_min()\f1 \- return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_getparam()\f1 \- return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_getscheduler()\f1 \- return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_rr_get_interval()\f1 \- update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4sched_setparam()\f1 \- set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_setscheduler()\f1 \- set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_yield()\f1 \- force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1operations, real-time scheduling@@@\f3rtsched(2)\f1 .\" index@\f1real-time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f1return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1scheduling operations, real-time@@@\f3rtsched(2)\f1 .\" index@\f1scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" links entries: .\" links@rtsched.2 PRI_HPUX_TO.2 .\" links@rtsched.2 PRI_POSIX_T.2 .\" links@rtsched.2 pri_hpux_to.2 .\" links@rtsched.2 pri_posix_t.2 .\" links@rtsched.2 sched_get_p.2 .\" links@rtsched.2 sched_getpa.2 .\" links@rtsched.2 sched_getsc.2 .\" links@rtsched.2 sched_rr_ge.2 .\" links@rtsched.2 sched_setpa.2 .\" links@rtsched.2 sched_setsc.2 .\" links@rtsched.2 sched_yield.2 .\" toc entries: .\" toc@\f3rtsched(2)\f1:\0\0\f4sched_get_priority_max()\f1, \f4sched_get_priority_min()\f1,\n\f4sched_getparam()\f1, \f4sched_getscheduler()\f1, \f4sched_rr_get_interval()\f1,\n\f4sched_setparam()\f1, \f4sched_setscheduler()\f1, \f4sched_yield()\f1,\n\f4PRI_HPUX_TO_POSIX()\f1, \f4PRI_POSIX_TO_HPUX()\f1@@@real-time scheduling operations .\" toc@\f4PRI_HPUX_TO_POSIX()\f1:\0\0return POSIX.4 process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4PRI_POSIX_TO_HPUX()\f1:\0\0return HP-UX process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_max()\f1:\0\0return maximum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_min()\f1:\0\0return minimum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getparam()\f1:\0\0return scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getscheduler()\f1:\0\0return scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_rr_get_interval()\f1:\0\0update execution time limit@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setparam()\f1:\0\0set scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setscheduler()\f1:\0\0set scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_yield()\f1:\0\0force process to relinquish processor@@@\f1see \f3rtsched(2)\f1 .\" $Header: rtsched.2,v 72.6 94/11/14 15:26:03 ssa Exp $ .TA r .TH rtsched 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtsched: sched_get_priority_max(), sched_get_priority_min(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setparam(), sched_setscheduler(), sched_yield(), PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX() \- real-time scheduling operations .SH SYNOPSIS .nf .C "#include " .PP .C "int sched_setparam(" .C " pid_t pid," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getparam(" .C " pid_t pid," .C " struct sched_param *param" .C ");" .PP .C "int sched_setscheduler(" .C " pid_t pid," .C " int policy," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getscheduler(" .C " pid_t pid" .C ");" .PP .C "int sched_yield();" .PP .C "int sched_get_priority_max(" .C " int policy" .C ");" .PP .C "int sched_get_priority_min(" .C " int policy" .C ");" .PP .C "int sched_rr_get_interval(" .C " pid_t pid," .C " struct timespec *interval" .C ");" .PP .C "int PRI_POSIX_TO_HPUX(" .C " const struct sched_param *param" .C ");" .PP .C "int PRI_HPUX_TO_POSIX(" .C " int pri," .C " struct sched_param *param" .C ");" .fi .SH DESCRIPTION .SS Summary .TP 35 .PD 0 .CR sched_get_priority_max() Get maximum scheduling policy .TP .CR sched_get_priority_min() Get minimum scheduling policy .TP .CR sched_getparam() Get scheduling parameters of process .TP .CR sched_getscheduler() Get scheduling policy of process .TP .CR sched_rr_get_interval() Update execution time limit for a process .TP .CR sched_setparam() Set scheduling parameters of process .TP .CR sched_setscheduler() Set scheduling policy and parameters of process .TP .CR sched_yield() Requeue current process in process list .TP .CR PRI_HPUX_TO_POSIX() Convert HP-UX priority to POSIX .TP .CR PRI_POSIX_TO_HPUX() Convert POSIX priority to HP-UX .PD .SS sched_setparam() The .CR sched_setparam() function sets the scheduling parameters of the process specified by .I pid to the values specified by the .I sched_param structure pointed to by .IR param . The value of the .I sched_priority member in the .I param structure is any integer within the inclusive priority range for the current scheduling policy of the process specified by .IR pid . .PP Higher numerical values for the priority represent higher (stronger) priorities. Note that this is different from the .CR SCHED_HPUX , .CR SCHED_TIMESHARE , and .CR SCHED_RTPRIO scheduling policies, where higher numerical values represent lower (weaker) priorities. See the .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() functions, and .CR SCHED_RTPRIO and .CR SCHED_OTHER in "Scheduling Policies" below. .PP If a process described by .I pid exists and if the calling process has permission, the scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are set for the calling process. .PP Only a superuser may change the scheduling parameters of another process. .PP The calling process must have the appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setparam() . .PP The target process, whether it is running or not running, will resume execution after all other runnable processes of equal or greater priority have been scheduled to run. .PP If the priority of the process specified by the .I pid argument is set higher than that of the lowest priority running process, and if the specified process is ready to run, the process specified by the .I pid argument will preempt a lowest-priority running process. Similarly, if the process calling .CR sched_setparam() sets its own priority lower than that of one or more other nonempty process lists, then the process that is the head of the highest priority list will also preempt the calling process. Thus, in either case, the originating process may not receive notification of the completion of the requested priority change until the higher priority process has executed. .SS sched_getparam() The .CR sched_getparam() function returns the scheduling parameters of a process specified by .I pid in the .I sched_param structure pointed to by .IR param . .PP If a process described by .I pid exists, the scheduling parameters are returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are returned for the calling process. .SS sched_setscheduler() The .CR sched_setscheduler() function sets the scheduling policy and scheduling parameters of the process specified by .I pid to .I policy and the parameters specified in the .I sched_param structure pointed to by .IR param , respectively. The value of the .I sched_priority member in the .I param structure can be any integer within the inclusive priority range for the scheduling policy specified by .IR policy . .PP The possible values for the .I policy parameter are defined in the header file .CR , and mentioned below. .PP If a process described by .I pid exists, the scheduling policy and scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy and scheduling parameters are set for the calling process. .PP Appropriate privileges are required to change the scheduling parameters of another process. .PP The calling process must have appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setscheduler() . .PP The .CR sched_setscheduler() function is considered successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by .I pid to the values specified by .I policy and the structure .IR param , respectively. .PP .SS sched_getscheduler() The .CR sched_getscheduler() function returns the scheduling policy of the process specified by .IR pid . .PP The values that can be returned by .CR sched_getscheduler() are defined in the header file .CR (see .CR sched_setscheduler() ). .PP If a process described by .I pid exists, the scheduling policy is returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy is returned for the calling process. .SS sched_yield() The .CR sched_yield() function forces the running process to relinquish the processor until it again becomes the head of its process list. It takes no arguments. .SS sched_get_priority_max() .SS sched_get_priority_min() The .CR sched_get_priority_max() and .CR sched_get_priority_min() functions return the appropriate maximum or minimum, respectively, for the scheduling policy specified by .IR policy . .PP The value of .I policy must be one of the scheduling policy values defined in .CR . .SS sched_rr_get_interval() The .CR sched_rr_get_interval() function updates the .I timespec structure referenced by the .I interval argument to contain the current execution time limit (that is, time quantum) for the process indicated by .I pid under the .CR SCHED_RR policy, at which a scheduling decision will be made when another process at the same priority is ready to execute. If .I pid is zero, the current execution time limit for the calling process is returned. .SS PRI_HPUX_TO_POSIX() .SS PRI_POSIX_TO_HPUX() These two functions serve to map (translate) the range of HP-UX priorities into the POSIX.4 model. These translations are necessary because the POSIX.4 standard chose .I larger numbers to represent stronger priorities and the existing HP-UX behavior, which must be maintained for backward compatibility, uses .I smaller numbers for stronger priorities. .PP The .CR PRI_HPUX_TO_POSIX() function returns, in the .I sched_param structure pointed to by .IR param , the POSIX.4 scheduling priority corresponding to the HP-UX priority passed in the argument .IR pri . The argument .I pri must contain a valid HP-UX priority. .PP The .CR PRI_POSIX_TO_HPUX() function returns an HP-UX process priority corresponding to the .I sched_priority member in the .I sched_param structure specified. The value of the .I sched_priority member can be any integer within the inclusive priority range for the .CR SCHED_HPUX scheduling policy. The HP-UX priority returned is comparable to the values returned by .CR getpriority() (see .IR getpriority (2)). .SS Scheduling Policies The scheduling policies described are defined in terms of a conceptual model, which contains a set of process lists. There is, conceptually, one process list for each priority. Any runnable process may be in any process list. Multiple scheduling policies are provided. Each nonempty list is ordered, and contains a head as one end of its order, and a tail as the other. The purpose of a scheduling policy is to define the allowable operations on this set of lists (for example, moving processes between and within lists). .PP Each process will be controlled by an associated scheduling policy and priority. These parameters may be specified by explicit application execution of the .CR sched_setscheduler() or .CR sched_setparam() functions. .PP Associated with each policy is a priority range. The priority ranges for each policy can (but need not) overlap the priority ranges of other policies. .PP When a process is to be selected to run, the process that is at the head of the highest priority nonempty process list is chosen. It is then removed from its process list. .PP The following scheduling policies are defined: .RS .TP 15 .CR SCHED_FIFO First in-first out (FIFO) scheduling policy. .IP Processes scheduled under this policy are chosen from a process list that is ordered by the time its processes have been in the list without being executed. Generally, the head of the list is the process that has been in the list the longest time, and the tail is the process that has been in the list the shortest time. .IP Under the .CR SCHED_FIFO policy, the modification of the definitional process lists is as follows: .RS .RS .TP 3 \(bu When a running process becomes a preempted process, it becomes the head of the process list for its priority. .TP \(bu When a blocked process becomes a runnable process, it becomes the tail of the process list for its priority. .TP \(bu When a running process calls the .CR sched_setscheduler() function, the process specified in the function call is modified to the policy and priority specified by the .I param argument. If the process whose policy and priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process calls the .CR sched_setparam() function, the priority of the process specified in the function call is modified to the priority specified by the .I param argument. If the process whose priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process issues the .CR sched_yield() function, the process becomes the tail of the process list for its priority. .TP \(bu At no other time is the position of a process with this scheduling policy within the process lists affected. .RE .RE .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_FIFO is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR Round-robin scheduling policy, with a per-system time slice (time quantum). .IP This policy is identical to the .CR SCHED_FIFO policy with the additional condition that when the implementation detects that a running process has been executing as a running process for a time period of length returned by the function .CR sched_rr_get_interval() , or longer, the process becomes the tail of its process list, and the head of that process list is removed and made a running process. .IP The effect of this policy is to ensure that if there are multiple .CR SCHED_RR processes at the same priority, one of them will not monopolize the processor. An application should not rely only on the use of .CR SCHED_RR to ensure application progress among multiple processes if the application includes processes using the .CR SCHED_FIFO policy at the same or higher priority levels, or .CR SCHED_RR processes at a higher priority level. .IP A process under this policy that is preempted and subsequently resumes execution as a running process completes the unexpired portion of its round-robin interval time period. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR2 Round-robin scheduling policy, with a per-priority time slice (time quantum). .IP This policy is identical to the .CR SCHED_RR policy, except that the round-robin time slice interval returned by .CR sched_rr_get_interval() depends upon the priority of the specified process. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RTPRIO Real-time scheduling policy with nondecaying priorities (like .CR SCHED_FIFO and .CR SCHED_RR ) with a priority range between the POSIX real-time policies and the HP-UX policies, described below (see .IR rtprio(2)). .IP For processes executing under this policy, the implementation must use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RTPRIO is provided as the parameter. Note that, for the .CR SCHED_RTPRIO scheduling policy, .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_RTPRIO is weaker than the weakest priority in the priority ranges for any of the POSIX policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .TP .CR SCHED_OTHER " (" SCHED_HPUX ", " SCHED_TIMESHARE ) Another scheduling policy. .IP The .CR SCHED_OTHER policy, also known as .CR SCHED_HPUX and .CR SCHED_TIMESHARE , provides a way for applications to indicate, in a portable way, that they no longer need a real-time scheduling policy. .IP For processes executing under this policy, the implementation can use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_OTHER is provided as the parameter. Note that for the .CR SCHED_OTHER scheduling policy, like .CR SCHED_RTPRIO , .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_OTHER is weaker than the weakest priority in the priority ranges for any of the other policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .RE .SH RETURN VALUE The functions return the following values: .SS sched_getparam() .SS sched_rr_get_interval() .SS sched_setparam() .SS sched_yield() .SS PRI_HPUX_TO_POSIX() .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_setscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the former scheduling policy of the specified process. .TP .CR -1 Failure. The policy and scheduling parameters remain unchanged. .CR errno is set to indicate the error. .PD .RE .SS sched_getscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the scheduling policy of the specified process. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the maximum or minimum value, respectively. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS PRI_POSIX_TO_HPUX() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the the HP-UX priority corresponding to the .I sched_priority member in the .I param structure. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If the functions fail, .CR errno is set to one of the following values. .SS sched_setparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] One or more of the requested scheduling parameters is outside the range defined for the scheduling policy of the specified .IR pid . .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling parameters for the specified process, or does not have the appropriate privilege to invoke .CR sched_setparam() . .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_setscheduler() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] The value of the .I policy parameter is invalid, or one or more of the parameters contained in .I param is outside the valid range for the specified scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling policy of the specified process. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getscheduler() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_yield() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP 15 [EINVAL] The value of the .I policy parameter does not represent a defined scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .RE .SS sched_rr_get_interval() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS PRI_POSIX_TO_HPUX() .RS .TP 15 [EINVAL] The priority specified in the .I sched_priority member of the .I param argument is outside the range defined for the .CR SCHED_HPUX scheduling policy. .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS PRI_HPUX_TO_POSIX() .RS .TP 15 [EINVAL] The priority specified in the .I pri argument is not a valid HP-UX priority. .TP [ENOSYS] The function is not supported by this implementation. .RE .SH EXAMPLES Change the calling process to use the strongest .CR FIFO priority: .IP .nf .C "#include " .IP .C "struct sched_param param;" .C "int maxpri;" .IP .C "maxpri = sched_get_priority_max(SCHED_FIFO);" .C "if (maxpri == -1) {" .C " perror(""sched_get_priority_max() failed"");" .C " exit(1);" .C "}" .C "param.sched_priority = maxpri;" .C "if (sched_setscheduler(getpid(), SCHED_FIFO, ¶m) == -1) {" .C " perror(""sched_setscheduler() failed"");" .C " exit(1);" .C "}" .fi .SH AUTHOR The .CI sched_ * () functions were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .PP .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() were developed by HP. .SH SEE ALSO rtsched(1), rtprio(2). .SH STANDARDS CONFORMANCE .CR sched_get_priority_max() ": POSIX.4" .PP .CR sched_get_priority_min() ": POSIX.4" .PP .CR sched_getparam() ": POSIX.4" .PP .CR sched_getscheduler() ": POSIX.4" .PP .CR sched_rr_getinterval() ": POSIX.4" .PP .CR sched_setparam() ": POSIX.4" .PP .CR sched_setscheduler() ": POSIX.4" .PP .CR sched_yield() ": POSIX.4" .\" .\" index entries: .\" index@\f1rtsched\f1 \- real time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f4PRI_HPUX_TO_POSIX()\f1 \- return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f4PRI_POSIX_TO_HPUX()\f1 \- return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_max()\f1 \- return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_min()\f1 \- return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_getparam()\f1 \- return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_getscheduler()\f1 \- return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_rr_get_interval()\f1 \- update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4sched_setparam()\f1 \- set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_setscheduler()\f1 \- set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_yield()\f1 \- force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1operations, real-time scheduling@@@\f3rtsched(2)\f1 .\" index@\f1real-time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f1return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1scheduling operations, real-time@@@\f3rtsched(2)\f1 .\" index@\f1scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" links entries: .\" links@rtsched.2 PRI_HPUX_TO.2 .\" links@rtsched.2 PRI_POSIX_T.2 .\" links@rtsched.2 pri_hpux_to.2 .\" links@rtsched.2 pri_posix_t.2 .\" links@rtsched.2 sched_get_p.2 .\" links@rtsched.2 sched_getpa.2 .\" links@rtsched.2 sched_getsc.2 .\" links@rtsched.2 sched_rr_ge.2 .\" links@rtsched.2 sched_setpa.2 .\" links@rtsched.2 sched_setsc.2 .\" links@rtsched.2 sched_yield.2 .\" toc entries: .\" toc@\f3rtsched(2)\f1:\0\0\f4sched_get_priority_max()\f1, \f4sched_get_priority_min()\f1,\n\f4sched_getparam()\f1, \f4sched_getscheduler()\f1, \f4sched_rr_get_interval()\f1,\n\f4sched_setparam()\f1, \f4sched_setscheduler()\f1, \f4sched_yield()\f1,\n\f4PRI_HPUX_TO_POSIX()\f1, \f4PRI_POSIX_TO_HPUX()\f1@@@real-time scheduling operations .\" toc@\f4PRI_HPUX_TO_POSIX()\f1:\0\0return POSIX.4 process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4PRI_POSIX_TO_HPUX()\f1:\0\0return HP-UX process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_max()\f1:\0\0return maximum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_min()\f1:\0\0return minimum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getparam()\f1:\0\0return scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getscheduler()\f1:\0\0return scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_rr_get_interval()\f1:\0\0update execution time limit@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setparam()\f1:\0\0set scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setscheduler()\f1:\0\0set scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_yield()\f1:\0\0force process to relinquish processor@@@\f1see \f3rtsched(2)\f1 .\" $Header: rtsched.2,v 72.6 94/11/14 15:26:03 ssa Exp $ .TA r .TH rtsched 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rtsched: sched_get_priority_max(), sched_get_priority_min(), sched_getparam(), sched_getscheduler(), sched_rr_get_interval(), sched_setparam(), sched_setscheduler(), sched_yield(), PRI_HPUX_TO_POSIX(), PRI_POSIX_TO_HPUX() \- real-time scheduling operations .SH SYNOPSIS .nf .C "#include " .PP .C "int sched_setparam(" .C " pid_t pid," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getparam(" .C " pid_t pid," .C " struct sched_param *param" .C ");" .PP .C "int sched_setscheduler(" .C " pid_t pid," .C " int policy," .C " const struct sched_param *param" .C ");" .PP .C "int sched_getscheduler(" .C " pid_t pid" .C ");" .PP .C "int sched_yield();" .PP .C "int sched_get_priority_max(" .C " int policy" .C ");" .PP .C "int sched_get_priority_min(" .C " int policy" .C ");" .PP .C "int sched_rr_get_interval(" .C " pid_t pid," .C " struct timespec *interval" .C ");" .PP .C "int PRI_POSIX_TO_HPUX(" .C " const struct sched_param *param" .C ");" .PP .C "int PRI_HPUX_TO_POSIX(" .C " int pri," .C " struct sched_param *param" .C ");" .fi .SH DESCRIPTION .SS Summary .TP 35 .PD 0 .CR sched_get_priority_max() Get maximum scheduling policy .TP .CR sched_get_priority_min() Get minimum scheduling policy .TP .CR sched_getparam() Get scheduling parameters of process .TP .CR sched_getscheduler() Get scheduling policy of process .TP .CR sched_rr_get_interval() Update execution time limit for a process .TP .CR sched_setparam() Set scheduling parameters of process .TP .CR sched_setscheduler() Set scheduling policy and parameters of process .TP .CR sched_yield() Requeue current process in process list .TP .CR PRI_HPUX_TO_POSIX() Convert HP-UX priority to POSIX .TP .CR PRI_POSIX_TO_HPUX() Convert POSIX priority to HP-UX .PD .SS sched_setparam() The .CR sched_setparam() function sets the scheduling parameters of the process specified by .I pid to the values specified by the .I sched_param structure pointed to by .IR param . The value of the .I sched_priority member in the .I param structure is any integer within the inclusive priority range for the current scheduling policy of the process specified by .IR pid . .PP Higher numerical values for the priority represent higher (stronger) priorities. Note that this is different from the .CR SCHED_HPUX , .CR SCHED_TIMESHARE , and .CR SCHED_RTPRIO scheduling policies, where higher numerical values represent lower (weaker) priorities. See the .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() functions, and .CR SCHED_RTPRIO and .CR SCHED_OTHER in "Scheduling Policies" below. .PP If a process described by .I pid exists and if the calling process has permission, the scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are set for the calling process. .PP Only a superuser may change the scheduling parameters of another process. .PP The calling process must have the appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setparam() . .PP The target process, whether it is running or not running, will resume execution after all other runnable processes of equal or greater priority have been scheduled to run. .PP If the priority of the process specified by the .I pid argument is set higher than that of the lowest priority running process, and if the specified process is ready to run, the process specified by the .I pid argument will preempt a lowest-priority running process. Similarly, if the process calling .CR sched_setparam() sets its own priority lower than that of one or more other nonempty process lists, then the process that is the head of the highest priority list will also preempt the calling process. Thus, in either case, the originating process may not receive notification of the completion of the requested priority change until the higher priority process has executed. .SS sched_getparam() The .CR sched_getparam() function returns the scheduling parameters of a process specified by .I pid in the .I sched_param structure pointed to by .IR param . .PP If a process described by .I pid exists, the scheduling parameters are returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling parameters are returned for the calling process. .SS sched_setscheduler() The .CR sched_setscheduler() function sets the scheduling policy and scheduling parameters of the process specified by .I pid to .I policy and the parameters specified in the .I sched_param structure pointed to by .IR param , respectively. The value of the .I sched_priority member in the .I param structure can be any integer within the inclusive priority range for the scheduling policy specified by .IR policy . .PP The possible values for the .I policy parameter are defined in the header file .CR , and mentioned below. .PP If a process described by .I pid exists, the scheduling policy and scheduling parameters are set for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy and scheduling parameters are set for the calling process. .PP Appropriate privileges are required to change the scheduling parameters of another process. .PP The calling process must have appropriate privileges or be a member of a group having .CR PRIV_RTSCHED access to successfully call .CR sched_setscheduler() . .PP The .CR sched_setscheduler() function is considered successful if it succeeds in setting the scheduling policy and scheduling parameters of the process specified by .I pid to the values specified by .I policy and the structure .IR param , respectively. .PP .SS sched_getscheduler() The .CR sched_getscheduler() function returns the scheduling policy of the process specified by .IR pid . .PP The values that can be returned by .CR sched_getscheduler() are defined in the header file .CR (see .CR sched_setscheduler() ). .PP If a process described by .I pid exists, the scheduling policy is returned for the process whose process ID is equal to .IR pid . .PP If .I pid is zero, the scheduling policy is returned for the calling process. .SS sched_yield() The .CR sched_yield() function forces the running process to relinquish the processor until it again becomes the head of its process list. It takes no arguments. .SS sched_get_priority_max() .SS sched_get_priority_min() The .CR sched_get_priority_max() and .CR sched_get_priority_min() functions return the appropriate maximum or minimum, respectively, for the scheduling policy specified by .IR policy . .PP The value of .I policy must be one of the scheduling policy values defined in .CR . .SS sched_rr_get_interval() The .CR sched_rr_get_interval() function updates the .I timespec structure referenced by the .I interval argument to contain the current execution time limit (that is, time quantum) for the process indicated by .I pid under the .CR SCHED_RR policy, at which a scheduling decision will be made when another process at the same priority is ready to execute. If .I pid is zero, the current execution time limit for the calling process is returned. .SS PRI_HPUX_TO_POSIX() .SS PRI_POSIX_TO_HPUX() These two functions serve to map (translate) the range of HP-UX priorities into the POSIX.4 model. These translations are necessary because the POSIX.4 standard chose .I larger numbers to represent stronger priorities and the existing HP-UX behavior, which must be maintained for backward compatibility, uses .I smaller numbers for stronger priorities. .PP The .CR PRI_HPUX_TO_POSIX() function returns, in the .I sched_param structure pointed to by .IR param , the POSIX.4 scheduling priority corresponding to the HP-UX priority passed in the argument .IR pri . The argument .I pri must contain a valid HP-UX priority. .PP The .CR PRI_POSIX_TO_HPUX() function returns an HP-UX process priority corresponding to the .I sched_priority member in the .I sched_param structure specified. The value of the .I sched_priority member can be any integer within the inclusive priority range for the .CR SCHED_HPUX scheduling policy. The HP-UX priority returned is comparable to the values returned by .CR getpriority() (see .IR getpriority (2)). .SS Scheduling Policies The scheduling policies described are defined in terms of a conceptual model, which contains a set of process lists. There is, conceptually, one process list for each priority. Any runnable process may be in any process list. Multiple scheduling policies are provided. Each nonempty list is ordered, and contains a head as one end of its order, and a tail as the other. The purpose of a scheduling policy is to define the allowable operations on this set of lists (for example, moving processes between and within lists). .PP Each process will be controlled by an associated scheduling policy and priority. These parameters may be specified by explicit application execution of the .CR sched_setscheduler() or .CR sched_setparam() functions. .PP Associated with each policy is a priority range. The priority ranges for each policy can (but need not) overlap the priority ranges of other policies. .PP When a process is to be selected to run, the process that is at the head of the highest priority nonempty process list is chosen. It is then removed from its process list. .PP The following scheduling policies are defined: .RS .TP 15 .CR SCHED_FIFO First in-first out (FIFO) scheduling policy. .IP Processes scheduled under this policy are chosen from a process list that is ordered by the time its processes have been in the list without being executed. Generally, the head of the list is the process that has been in the list the longest time, and the tail is the process that has been in the list the shortest time. .IP Under the .CR SCHED_FIFO policy, the modification of the definitional process lists is as follows: .RS .RS .TP 3 \(bu When a running process becomes a preempted process, it becomes the head of the process list for its priority. .TP \(bu When a blocked process becomes a runnable process, it becomes the tail of the process list for its priority. .TP \(bu When a running process calls the .CR sched_setscheduler() function, the process specified in the function call is modified to the policy and priority specified by the .I param argument. If the process whose policy and priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process calls the .CR sched_setparam() function, the priority of the process specified in the function call is modified to the priority specified by the .I param argument. If the process whose priority has been modified is a running process or is runnable, it then becomes the tail of the process list for its new priority. .TP \(bu When a running process issues the .CR sched_yield() function, the process becomes the tail of the process list for its priority. .TP \(bu At no other time is the position of a process with this scheduling policy within the process lists affected. .RE .RE .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_FIFO is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR Round-robin scheduling policy, with a per-system time slice (time quantum). .IP This policy is identical to the .CR SCHED_FIFO policy with the additional condition that when the implementation detects that a running process has been executing as a running process for a time period of length returned by the function .CR sched_rr_get_interval() , or longer, the process becomes the tail of its process list, and the head of that process list is removed and made a running process. .IP The effect of this policy is to ensure that if there are multiple .CR SCHED_RR processes at the same priority, one of them will not monopolize the processor. An application should not rely only on the use of .CR SCHED_RR to ensure application progress among multiple processes if the application includes processes using the .CR SCHED_FIFO policy at the same or higher priority levels, or .CR SCHED_RR processes at a higher priority level. .IP A process under this policy that is preempted and subsequently resumes execution as a running process completes the unexpired portion of its round-robin interval time period. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RR2 Round-robin scheduling policy, with a per-priority time slice (time quantum). .IP This policy is identical to the .CR SCHED_RR policy, except that the round-robin time slice interval returned by .CR sched_rr_get_interval() depends upon the priority of the specified process. .IP For this policy, valid priorities are within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RR is provided as the parameter. The priority range for this policy contains at least 32 priorities. .TP .CR SCHED_RTPRIO Real-time scheduling policy with nondecaying priorities (like .CR SCHED_FIFO and .CR SCHED_RR ) with a priority range between the POSIX real-time policies and the HP-UX policies, described below (see .IR rtprio(2)). .IP For processes executing under this policy, the implementation must use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_RTPRIO is provided as the parameter. Note that, for the .CR SCHED_RTPRIO scheduling policy, .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_RTPRIO is weaker than the weakest priority in the priority ranges for any of the POSIX policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .TP .CR SCHED_OTHER " (" SCHED_HPUX ", " SCHED_TIMESHARE ) Another scheduling policy. .IP The .CR SCHED_OTHER policy, also known as .CR SCHED_HPUX and .CR SCHED_TIMESHARE , provides a way for applications to indicate, in a portable way, that they no longer need a real-time scheduling policy. .IP For processes executing under this policy, the implementation can use only priorities within the range returned by the functions .CR sched_get_priority_max() and .CR sched_get_priority_min() when .CR SCHED_OTHER is provided as the parameter. Note that for the .CR SCHED_OTHER scheduling policy, like .CR SCHED_RTPRIO , .I smaller numbers represent higher (stronger) priorities, which is the opposite of the POSIX scheduling policies. This is done to provide continuing support for existing applications that depend on this priority ordering. However, it is guaranteed that the priority range for the .CR SCHED_OTHER scheduling policy is properly disjoint from the priority ranges of all of the other scheduling policies described and the strongest priority in the priority range for .CR SCHED_OTHER is weaker than the weakest priority in the priority ranges for any of the other policies, .CR SCHED_FIFO , .CR SCHED_RR , and .CR SCHED_RR2 . .RE .SH RETURN VALUE The functions return the following values: .SS sched_getparam() .SS sched_rr_get_interval() .SS sched_setparam() .SS sched_yield() .SS PRI_HPUX_TO_POSIX() .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_setscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the former scheduling policy of the specified process. .TP .CR -1 Failure. The policy and scheduling parameters remain unchanged. .CR errno is set to indicate the error. .PD .RE .SS sched_getscheduler() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the scheduling policy of the specified process. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the maximum or minimum value, respectively. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SS PRI_POSIX_TO_HPUX() .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the the HP-UX priority corresponding to the .I sched_priority member in the .I param structure. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If the functions fail, .CR errno is set to one of the following values. .SS sched_setparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] One or more of the requested scheduling parameters is outside the range defined for the scheduling policy of the specified .IR pid . .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling parameters for the specified process, or does not have the appropriate privilege to invoke .CR sched_setparam() . .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getparam() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_setscheduler() .RS .TP 15 [EFAULT] The .I param argument points to an invalid address. .TP [EINVAL] The value of the .I policy parameter is invalid, or one or more of the parameters contained in .I param is outside the valid range for the specified scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .TP [EPERM] The requesting process does not have permission to set the scheduling policy of the specified process. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_getscheduler() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS sched_yield() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS sched_get_priority_max() .SS sched_get_priority_min() .RS .TP 15 [EINVAL] The value of the .I policy parameter does not represent a defined scheduling policy. .TP [ENOSYS] The function is not supported by this implementation. .RE .SS sched_rr_get_interval() .RS .TP 15 [ENOSYS] The function is not supported by this implementation. .TP [ESRCH] No process can be found corresponding to that specified by .IR pid . .RE .SS PRI_POSIX_TO_HPUX() .RS .TP 15 [EINVAL] The priority specified in the .I sched_priority member of the .I param argument is outside the range defined for the .CR SCHED_HPUX scheduling policy. .TP 15 [ENOSYS] The function is not supported by this implementation. .RE .SS PRI_HPUX_TO_POSIX() .RS .TP 15 [EINVAL] The priority specified in the .I pri argument is not a valid HP-UX priority. .TP [ENOSYS] The function is not supported by this implementation. .RE .SH EXAMPLES Change the calling process to use the strongest .CR FIFO priority: .IP .nf .C "#include " .IP .C "struct sched_param param;" .C "int maxpri;" .IP .C "maxpri = sched_get_priority_max(SCHED_FIFO);" .C "if (maxpri == -1) {" .C " perror(""sched_get_priority_max() failed"");" .C " exit(1);" .C "}" .C "param.sched_priority = maxpri;" .C "if (sched_setscheduler(getpid(), SCHED_FIFO, ¶m) == -1) {" .C " perror(""sched_setscheduler() failed"");" .C " exit(1);" .C "}" .fi .SH AUTHOR The .CI sched_ * () functions were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .PP .CR PRI_HPUX_TO_POSIX() and .CR PRI_POSIX_TO_HPUX() were developed by HP. .SH SEE ALSO rtsched(1), rtprio(2). .SH STANDARDS CONFORMANCE .CR sched_get_priority_max() ": POSIX.4" .PP .CR sched_get_priority_min() ": POSIX.4" .PP .CR sched_getparam() ": POSIX.4" .PP .CR sched_getscheduler() ": POSIX.4" .PP .CR sched_rr_getinterval() ": POSIX.4" .PP .CR sched_setparam() ": POSIX.4" .PP .CR sched_setscheduler() ": POSIX.4" .PP .CR sched_yield() ": POSIX.4" .\" .\" index entries: .\" index@\f1rtsched\f1 \- real time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f4PRI_HPUX_TO_POSIX()\f1 \- return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f4PRI_POSIX_TO_HPUX()\f1 \- return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_max()\f1 \- return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_get_priority_min()\f1 \- return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_getparam()\f1 \- return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_getscheduler()\f1 \- return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_rr_get_interval()\f1 \- update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4sched_setparam()\f1 \- set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f4sched_setscheduler()\f1 \- set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4sched_yield()\f1 \- force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1force process to relinquish processor@@@\f3rtsched(2)\f1 .\" index@\f1operations, real-time scheduling@@@\f3rtsched(2)\f1 .\" index@\f1real-time scheduling operations@@@\f3rtsched(2)\f1 .\" index@\f1return HP-UX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return POSIX process priority@@@\f3rtsched(2)\f1 .\" index@\f1return maximum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return minimum for scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1return scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1scheduling operations, real-time@@@\f3rtsched(2)\f1 .\" index@\f1scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling parameters@@@\f3rtsched(2)\f1 .\" index@\f1set scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f1update execution time limit@@@\f3rtsched(2)\f1 .\" index@\f4FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_FIFO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_HPUX\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_OTHER\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR2\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RR\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_RTPRIO\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4SCHED_TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" index@\f4TIMESHARE\f1 scheduling policy@@@\f3rtsched(2)\f1 .\" links entries: .\" links@rtsched.2 PRI_HPUX_TO.2 .\" links@rtsched.2 PRI_POSIX_T.2 .\" links@rtsched.2 pri_hpux_to.2 .\" links@rtsched.2 pri_posix_t.2 .\" links@rtsched.2 sched_get_p.2 .\" links@rtsched.2 sched_getpa.2 .\" links@rtsched.2 sched_getsc.2 .\" links@rtsched.2 sched_rr_ge.2 .\" links@rtsched.2 sched_setpa.2 .\" links@rtsched.2 sched_setsc.2 .\" links@rtsched.2 sched_yield.2 .\" toc entries: .\" toc@\f3rtsched(2)\f1:\0\0\f4sched_get_priority_max()\f1, \f4sched_get_priority_min()\f1,\n\f4sched_getparam()\f1, \f4sched_getscheduler()\f1, \f4sched_rr_get_interval()\f1,\n\f4sched_setparam()\f1, \f4sched_setscheduler()\f1, \f4sched_yield()\f1,\n\f4PRI_HPUX_TO_POSIX()\f1, \f4PRI_POSIX_TO_HPUX()\f1@@@real-time scheduling operations .\" toc@\f4PRI_HPUX_TO_POSIX()\f1:\0\0return POSIX.4 process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4PRI_POSIX_TO_HPUX()\f1:\0\0return HP-UX process priority@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_max()\f1:\0\0return maximum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_get_priority_min()\f1:\0\0return minimum for scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getparam()\f1:\0\0return scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_getscheduler()\f1:\0\0return scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_rr_get_interval()\f1:\0\0update execution time limit@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setparam()\f1:\0\0set scheduling parameters@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_setscheduler()\f1:\0\0set scheduling policy@@@\f1see \f3rtsched(2)\f1 .\" toc@\f4sched_yield()\f1:\0\0force process to relinquish processor@@@\f1see \f3rtsched(2)\f1 .\" $Header: select.2,v 76.1 95/07/07 14:50:04 ssa Exp $ .TA s .TH select 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME select \- synchronous I/O multiplexing .SH SYNOPSIS .C "#include " .PP .C "int select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval *timeout);" .PP .C "void FD_CLR(int fd, fd_set *fdset);" .PP "int FD_ISSET(int fd, fd_set *fdset);" .C "void FD_SET(int fd, fd_set *fdset);" .PP .C "void FD_ZERO(fd_set *fdset);" .SH DESCRIPTION The .CR select() function indicates which of the specified file descriptors is ready for reading, ready for writing, or has an error condition pending. If the specified condition is false for all of the specified file descriptors, .CR select() blocks, up to the specified timeout interval, until the specified condition is true for at least one of the specified file descriptors. .PP The .CR select() function supports regular files, terminal and pseudo-terminal devices, STREAMS-based files, FIFOs and pipes. The behaviour of .CR select() on file descriptors that refer to other types of file is unspecified. .PP The .IR nfds argument specifies the range of file descriptors to be tested. The .CR select() function tests file descriptors in the range of 0 to .IR nfds \(mi1. .PP If the .IR readfs argument is not a null pointer, it points to an object of type .IR fd_set that on input specifies the file descriptors to be checked for being ready to read, and on output indicates which file descriptors are ready to read. .PP If the .IR writefs argument is not a null pointer, it points to an object of type .IR fd_set that on input specifies the file descriptors to be checked for being ready to write, and on output indicates which file descriptors are ready to write. .PP If the .IR errorfds argument is not a null pointer, it points to an object of type .IR fd_set that on input specifies the file descriptors to be checked for error conditions pending, and on output indicates which file descriptors have error conditions pending. .PP On successful completion, the objects pointed to by the .IR readfs , .IR writefs , and .IR errorfds arguments are modified to indicate which file descriptors are ready for reading, ready for writing, or have an error condition pending, respectively. For each file descriptor less than .IR nfds , the corresponding bit will be set on successful completion if it was set on input and the associated condition is true for that file descriptor. .PP If the .IR timeout argument is not a null pointer, it points to an object of type .IR struct timeval that specifies a maximum interval to wait for the selection to complete. If the .IR timeout argument points to an object of type .IR struct timeval whose members are 0, .CR select() does not block. If the .IR timeout argument is a null pointer, .CR select() blocks until an event causes one of the masks to be returned with a valid (non-zero) value. If the time limit expires before any event occurs that would cause one of the masks to be set to a non-zero value, .CR select() completes successfully and returns 0. .PP Implementations may place limitations on the maximum timeout interval supported. On all implementations, the maximum timeout interval supported will be at least 31 days. If the timeout argument specifies a timeout interval greater than the implementation- dependent maximum value, the maximum value will be used as the actual timeout value. Implementations may also place limitations on the granularity of timeout intervals. If the requested timeout interval requires a finer granularity than the implementation supports, the actual timeout interval will be rounded up to the next supported value. .PP If the .IR readfs , .IR writefs , and .IR errorfds arguments are all null pointers and the timeout argument is not a null pointer, .CR select() blocks for the time specified, or until interrupted by a signal. If the .IR readfs , .IR writefs , and .IR errorfds arguments are all null pointers and the .IR timeout argument is a null pointer, .CR select() blocks until interrupted by a signal. .PP File descriptors associated with regular files always select true for ready to read, ready to write, and error conditions. .PP On failure, the objects pointed to by the .IR readfs , .IR writefs , and .IR errorfds arguments are not modified. If the timeout interval expires without the specified condition being true for any of the specified file descriptors, the objects pointed to by the .IR readfs , .IR writefs , and .IR errorfds arguments have all bits set to 0. .PP File descriptor masks of type .IR fd_set can be initialised and tested with .CR FD_CLR() , .CR FD_ISSET() , .CR FD_SET() , and .CR FD_ZERO() . It is unspecified whether each of these is a macro or a function. If a macro definition is suppressed in order to access an actual function, or a program defines an external identifier with any of these names, the behaviour is undefined. .RS .TP 30 .C FD_CLR(fd, &fdset) Clears the bit for the file descriptor .IR fd in the file descriptor set .IR fdset . .TP .C FD_ISSET(fd, &fdset) Returns a non-zero value if the bit for the file descriptor .IR fd is set in the file descriptor set pointed to by .IR fdset , and 0 otherwise. .TP .C FD_SET(fd, &fdset) Sets the bit for the file descriptor .IR fd in the file descriptor set .IR fdset . .TP .C FD_ZERO(&fdset) Initialises the file descriptor set .IR fdset to have zero bits for all file descriptors. The behaviour of these macros is undefined if the .IR fd argument is less than 0 or greater than or equal to .CR FD_SETSIZE. .RE .SH RETURN VALUE .CR FD_CLR() , .CR FD_SET() , and .CR FD_ZERO() return no value. .CR FD_ISSET() returns a non-zero value if the bit for the file descriptor .IR fd is set in the file descriptor set pointed to by .IR fdset , and 0 otherwise. .PP On successful completion, .CR select() returns the total number of bits set in the bit masks. Otherwise, \(mi1 is returned, and .CR errno is set to indicate the error. .SH ERRORS Under the following conditions, .CR select() fails and sets .CR errno to: .RS .TP 15 [EBADF] One or more of the file descriptor sets specified a file descriptor that is not a valid open file descriptor. .TP [EINTR] The .CR select() function was interrupted before any of the selected events occurred and before the .IR timeout interval expired. If .CR SA_RESTART has been set for the interrupting signal, it is implementation-dependent whether .CR select() restarts or returns with .CR EINTR . .TP [EINVAL] An invalid timeout interval was specified. .TP [EINVAL] The .IR nfds argument is less than 0, or greater than or equal to .CR FD_SETSIZE. .TP [EINVAL] One of the specified file descriptors refers o a STREAM or multiplexer that is linked (directly or indirectly) downstream from a multiplexer. .RE .SH APPLICATION USAGE The use of a timeout does not affect any pending timers set up by .CR alarm() , .CR ualarm() , or .CR settimer() . .PP On successful completion, the object pointed to by the .IR timeout argument may be modified. .SH SEE ALSO fcntl(), poll(), read(), write(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" $Header: select.2,v 76.1 95/07/07 14:50:04 ssa Exp $ .TA s .TH select 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH SYNOPSIS .C "#include " .PP .PD 0 .nf .C "int select(" .IP .C "size_t nfds," .C "int *readfds," .C "int *writefds," .C "int *exceptfds," .C "const struct timeval *timeout" .PP .C ");" .PD .fi .SH DESCRIPTION .CR select() examines the files or devices associated with the file descriptors specified by the bit masks .IR readfds , .IR writefds , and .IR exceptfds . The bits from 0 through .IR nfds \(mi1 are examined. File descriptor .I f is represented by the bit .RI 1<< f in the masks. More formally, a file descriptor is represented by: .IP fds[(f\ /\ BITS_PER_INT)]\ &\ (1\ <<\ (f\ %\ BITS_PER_INT)) .PP Ttys and sockets are ready for reading or writing, respectively, if a .CR read() or .CR write() would not block for one or more of the following reasons: .P .RS .TP 3 \(bu input data is available. .TP 3 \(bu output data can be accepted. .TP 3 \(bu an error condition exists, such as a broken pipe, no carrier, or a lost connection. .RE .P Sockets select true on reads and/or exceptions if out-of-band data is available. .P Pipes are ready for reading if there is any data in the pipe, or if there are no writers left for the pipe. Pipes are ready for writing if there is room for more data in the pipe AND there are one or more readers for the pipe, OR there are no readers left for the pipe. .CR select() returns the same results for a pipe whether a file descriptor associated with the read-only end or the write-only end of the pipe is used, since both file descriptors refer to the same underlying pipe. So a .CR select() of a read-only file descriptor that is associated with a pipe can return ready to write, even though that particular file descriptor cannot be written to. .SH ERRORS .RS .TP 15 [EFAULT] One or more of the pointers was invalid. The reliable detection of this error is implementation dependent. .RE .SH EXAMPLES The following call to .C select() checks if any of 4 terminals are ready for reading. .C select() times out after 5 seconds if no terminals are ready for reading. Note that the code for opening the terminals or reading from the terminals is not shown in this example. Also, note that this example must be modified if the calling process has more than 32 file descriptors open. Following this first example is an example of select with more than 32 file descriptors. .nf .IP .C "#define MASK(f) (1 << (f))" .C "#define NTTYS 4" .IP .C "int tty[NTTYS];" .C "int ttymask[NTTYS];" .C "int readmask = 0;" .C "int readfds;" .C "int nfound, i;" .C "struct timeval timeout;" .IP .C " /* First open each terminal for reading and put the" .C " * file descriptors into array tty[NTTYS]. The code" .C " * for opening the terminals is not shown here." .C " */" .IP .C "for (i=0; i < NTTYS; i++) {" .C " ttymask[i] = MASK(tty[i]);" .C " readmask |= ttymask[i];" .C "}" .IP .C "timeout.tv_sec = 5;" .C "timeout.tv_usec = 0;" .C "readfds = readmask;" .IP .C "/* select on NTTYS+3 file descriptors if stdin, stdout" .C " * and stderr are also open" .C " */" .C "if ((nfound = select (NTTYS+3, &readfds, 0, 0, &timeout)) == -1)" .ift .ft 4 .ifn .ft 3 .ps +1 perror ("select failed"); else if (nfound == 0) printf ("select timed out \\n"); else for (i=0; i < NTTYS; i++) if (ttymask[i] & readfds) /* Read from tty[i]. The code for reading * is not shown here. */ else printf ("tty[%d] is not ready for reading \\n",i); .fi .ft .ps .PP The following example is the same as the previous example, except that it works for more than 32 open files. Definitions for .CR howmany , .CR fd_set , and .C NFDBITS are in .CR "". .nf .IP .C "#include " .C "#include " .C "#include " .IP .C "#define MASK(f) (1 << (f))" .C "#define NTTYS NOFILE - 3" .C "#define NWORDS howmany(FD_SETSIZE, NFDBITS)" .IP .C "int tty[NTTYS];" .C "int ttymask[NTTYS];" .C "struct fd_set readmask, readfds;" .C "int nfound, i, j, k;" .C "struct timeval timeout;" .IP .C " /* First open each terminal for reading and put the" .C " * file descriptors into array tty[NTTYS]. The code" .C " * for opening the terminals is not shown here." .C " */ .IP .C " for (k=0; k < NWORDS; k++)" .C " readmask.fds_bits[k] = 0;" .IP .C " for (i=0, k=0; i < NTTYS && k < NWORDS; k++)" .C " for (j=0; j < NFDBITS && i < NTTYS; j++, i++) {" .C " ttymask[i] = MASK(tty[i]);" .C " readmask.fds_bits[k] |= ttymask[i];" .C " }" .IP .C " timeout.tv_sec = 5;" .C " timeout.tv_usec = 0;" .C " for (k=0; k < NWORDS; k++)" .C " readfds.fds_bits[k] = readmask.fds_bits[k];" .IP .C " /* select on NTTYS+3 file descriptors if stdin, stdout" .C " * and stderr are also open" .C " */" .C " if ((nfound = select (NTTYS+3, &readfds, 0, 0, &timeout)) == -1)" .ift .ft 4 .ifn .ft 3 .ps +1 perror ("select failed"); else if (nfound == 0) printf ("select timed out \\n"); else for (i=0, k=0; i < NTTYS && k < NWORDS; k++) for (j=0; j < NFDBITS && i < NTTYS; j++, i++) if (ttymask[i] & readfds.fds_bits[k]) /* Read from tty[i]. The code for reading * is not shown here. */ else printf ("tty[%d] is not ready for reading \\n",i); .nf .ps .ft .SH WARNINGS Check all references to .IR signal (5) for appropriateness on systems that support .CR sigvector() . .CR sigvector() can affect the behavior described on this manpage. .PP The file descriptor masks are always modified on return, even if the call returns as the result of a timeout. .SH DEPENDENCIES .CR select() supports the following devices and file types: .RS .RS .TP 3 \(bu pipes .PD 0 .TP \(bu fifo special files (named pipes) .TP \(bu all serial devices .TP \(bu All ITEs (internal terminal emulators) and HP-HIL input devices .TP \(bu .IR hpib (7) special files .TP \(bu .IR lan (7) special files .TP \(bu .IR pty (7) special files .TP \(bu sockets .PD .RE .SH AUTHOR .C select() was developed by HP and the University of California, Berkeley. .SH SEE ALSO fcntl(2), read(2), write(2). .\" index@\f4select()\f1 \- synchronous I/O multiplexing@@@\f3select(2)\f1 .\" index@\f1synchronous I/O multiplexing@@@\f3select(2)\f1 .\" index@\f1I/O multiplexing, synchronous@@@\f3select(2)\f1 .\" index@\f1multiplexing, synchronous I/O@@@\f3select(2)\f1 .\" .\" toc@\f3select(2)\f1:\0\0\f4select()\f1@@@synchronous I/O multiplexing .\" .\" fileset_database@select.2 PROGRAMING-MAN .\" $Header: semctl.2,v 78.1 96/01/19 20:17:49 ssa Exp $ .TA s .TH semctl 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME semctl \- semaphore control operations .SH SYNOPSIS .C "#include " .PP .nf .C "int semctl(int semid," .C " int semnum," .C " int cmd, ..." .C " /* arg */" .C ");" .fi .SS Remarks The ANSI C "\c .CR ", ...\$\c" " construct denotes a variable length argument list whose optional [or required] \" EDITOR: make this line fit the specific page members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION The .CR semctl() system call provides a variety of semaphore control operations as specified by .IR cmd . For the meaning of unspecified variables, see .IR "semaphore identifier" in .IR glossary (9). .PP The following values for .IR cmd are executed with respect to the semaphore specified by .IR semid and .IR semnum : .RS .TP 15 .CR GETVAL Return the value of .IR semval . Requires semaphore Read permission. .TP .CR SETVAL Set the value of .IR semval to .IR arg , where .IR arg is the fourth argument of .CR semctl() taken as an .CR int . When this .IR cmd is successfully executed, the .IR semadj value corresponding to the specified semaphore in all processes is cleared. Requires semaphore Alter permission. .TP .CR GETPID Return the value of .IR sempid . Requires semaphore Read permission. .TP .CR GETNCNT Return the value of .IR semncnt . Requires semaphore Read permission. .TP .CR GETZCNT Return the value of .IR semzcnt . Requires semaphore Read permission. .RE .PP The following values for .IR cmd return and set, respectively, every .IR semval in the set of semaphores. .RS .TP 15 .CR GETALL Place .IR semval s into array pointed to by .IR arg , where .IR arg is the fourth argument of .CR semctl() taken as a pointer to .CR "unsigned short int" . Requires semaphore Read permission. .TP .CR SETALL Set .IR semval s according to the array pointed to by .IR arg , where .IR arg is the fourth argument of .CR semctl() taken as a pointer to .CR "unsigned short int" . When this .IR cmd is successfully executed, the .IR semadj values corresponding to each specified semaphore in all processes are cleared. Requires semaphore Alter permission. .RE .PP The following values for .IR cmd are also available: .RS .TP 15 .CR IPC_STAT Place the current value of each member of the data structure associated with .IR semid into the structure pointed to by .IR arg , where .IR arg is the fourth argument of .CR semctl() taken as a pointer to .CR "struct semid_ds" . The contents of this structure are defined in .IR glossary (9). Requires semaphore Read permission. .TP .CR IPC_SET Set the value of the following members of the data structure associated with .IR semid to the corresponding value found in the structure pointed to by .IR arg , where .IR arg is the fourth argument of .CR semctl() taken as a pointer to .CR "struct semid_ds" : .RS .RS .nf .IP .CR sem_perm.uid .CR sem_perm.gid .C "sem_perm.mode /* only low 9 bits */" .fi .RE .RE .IP This .IR cmd can only be executed by a process that has an effective user ID equal to either that of superuser or to the value of either .CR sem_perm.uid or .CR sem_perm.cuid in the data structure associated with .IR semid . .TP .CR IPC_RMID Remove the semaphore identifier specified by .IR semid from the system and destroy the set of semaphores and data structure associated with it. This .IR cmd can only be executed by a process that has an effective user ID equal to either that of superuser or to the value of either .CR sem_perm.uid or .CR sem_perm.cuid in the data structure associated with .IR semid . .SH RETURN VALUE Upon successful completion, .CR semctl() returns a value based on .IR cmd as follows: .RS .TP 15 .CR GETVAL The value of .IR semval . .PD 0 .TP .CR GETNCNT The value of .IR semncnt . .TP .CR GETZCNT The value of .IR semzcnt . .TP .CR GETPID The value of .IR sempid . .PD .RE .PP All others return .CR 0 . .PP If it fails, it returns .CR -1 and sets .CR errno to indicate the error. .SH ERRORS If .CR semctl() fails, it sets .CR errno to one of the following values: .RS .TP 15 [EACCES] Operation permission is denied to the calling process (see .I "semaphore operation permissions" in .IR glossary (9). .TP [EFAULT] .IR cmd is .CR SETVAL , .CR GETALL , .CR SETALL , .CR IPC_SET , or .CR IPC_STAT , and .IR arg is an invalid pointer. .TP [EINVAL] .IR semid is not a valid semaphore identifier. .TP [EINVAL] .IR semnum is less than zero or greater than or equal .CR sem_nsems . .TP [EINVAL] .IR cmd is not a valid command, or the command contains invalid parameters. .TP [EPERM] .IR cmd is equal to .CR IPC_RMID or .CR IPC_SET and the process does not have an effective user ID equal to either that of superuser or to the value of either .CR sem_perm.uid or .CR sem_perm.cuid in the data structure associated with .IR semid . .TP [ERANGE] .IR cmd is .CR SETVAL or .CR SETALL and the value to which .IR semval is to be set is greater than the system imposed maximum. .SH EXAMPLES The following call to .CR semctl() initializes the set of 4 semaphores to the values 0, 1, 0, and 1 respectively. This example assumes the process has a valid .IR semid representing a set of 4 semaphores as shown in the .IR semget (2) manual entry. For an example of performing "P" and "V" operations on the semaphores below, refer to .IR semop (2). .nf .IP .C ushort semarray[4]; .IP .C semarray[0] = 0; .C semarray[1] = 1; .C semarray[2] = 0; .C semarray[3] = 1; .IP .C semctl (mysemid, 0, SETALL, semarray); .fi .SH SEE ALSO ipcrm(1), ipcs(1), semget(2), semop(2), stdipc(3C), glossary(9). .SH STANDARDS CONFORMANCE .CR semctl() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4semctl()\f1 \- semaphore control operations@@@\f3semctl(2)\f1 .\" index@\f1semaphore control operations@@@\f3semctl(2)\f1 .\" index@\f1control operations, semaphore@@@\f3semctl(2)\f1 .\" index@\f1operations, semaphore control@@@\f3semctl(2)\f1 .\" .\" toc@\f3semctl(2)\f1:\0\0\f4semctl()\f1@@@semaphore control operations .\" .\" fileset_database@semctl.2 PROG-AUX-MAN .\" $Header: semget.2,v 72.4 94/11/14 15:26:06 ssa Exp $ .TA s .TH semget 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME semget \- get set of semaphores .SH SYNOPSIS .C "#include " .PP .C "int semget(key_t key, int nsems, int semflg);" .SH DESCRIPTION .C semget() returns the semaphore identifier associated with .IR key . .PP A semaphore identifier and associated data structure and set containing .I nsems semaphores are created for .I key if one of the following is true: .IP .I key is equal to .CR IPC_PRIVATE . This call creates a new identifier, subject to available resources. The identifier is never returned by another call to .C semget() until it has been released by a call to .CR semctl() . The identifier should be used among the calling process and its descendents; however, it is not a requirement. The resource can be accessed by any process having the proper permissions. .IP .I key does not already have a semaphore identifier associated with it, and .RI ( semflg & .CR IPC_CREAT ) is ``true''. .PP Specific behavior can be requested by .SM OR\s0ing the following masks into .IR semflg . .IP .CR IPC_CREAT : Create a semaphore identifier if one does not already exist for .IR key. .IP .CR IPC_EXCL : If .C IPC_CREAT is specified and .I key already has a semaphore identifier associated with it, return an error. .PP The low-order 9 bits of .I semflg are the semaphore operation permissions which are defined in .IR glossary (9). .PP Upon creation, the data structure associated with the new semaphore identifier is initialized as follows: .IP In the operation-permission structure, .C sem_perm.cuid and .C sem_perm.uid are set equal to the effective-user-ID of the calling process, while .C sem_perm.cgid and .C sem_perm.gid are set to the effective-group-ID of the calling process. .IP The low-order 9 bits of .C sem_perm.mode are set equal to the low-order 9 bits of .IR semflg . .IP .C sem_nsems is set equal to the value of .IR nsems . .IP .C sem_otime is set equal to 0 and .C sem_ctime is set equal to the current time. .SH EXAMPLES The following call to .C semget() returns a semid associated with the key returned by .C ftok("myfile", 'A'). If a semid associated with the key does not exist, a new semid, set of 4 semaphores, and associated data structure will be created. If a semid for the key already exists, the semid is simply returned. .IP .C int semid; .br .ift .ft 4 .ifn .ft 3 .ps +1 mysemid = semget (ftok("myfile",'A'), 4, IPC_CREAT | 0600); .ps .ft .SH RETURN VALUE Upon successful completion, a non-negative integer, namely a semaphore identifier, is returned. Otherwise, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .C semget() fails if one or more of the following is true: .RS .TP 15 .SM [EINVAL] .I nsems is either less than or equal to zero or greater than the system-imposed limit. .TP .SM [EACCES] A semaphore identifier exists for .IR key , but operation permission as specified by the low-order 9 bits of .I semflg would not be granted. .TP .SM [EINVAL] A semaphore identifier exists for .IR key , but the number of semaphores in the set associated with it is less than .IR nsems , and .I nsems is not equal to zero. .TP .SM [ENOENT] A semaphore identifier does not exist for .I key and .RI ( semflg & .CR IPC_CREAT ) is ``false''. .TP .SM [ENOSPC] A semaphore identifier is to be created, but the system-imposed limit on the maximum number of allowed semaphore identifiers system wide would be exceeded. .TP .SM [EEXIST] A semaphore identifier exists for .I key but .CI (( semflg "& IPC_CREAT) && (" semflg " & IPC_EXCL)) is ``true''. .RE .SH SEE ALSO ipcrm(1), ipcs(1), semctl(2), semop(2), stdipc(3C). .SH STANDARDS CONFORMANCE .CR semget() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4semget()\fP \(mi get set of semaphores@@@\f3semget(2)\f1 .\" index@get: set of semaphores@@@\f3semget(2)\f1 .\" index@set of semaphores, get@@@\f3semget(2)\f1 .\" index@semaphores, get set of@@@\f3semget(2)\f1 .\" .\" toc@\f3semget(2)\f1:\0\0\f4semget()\fP@@@get set of semaphores .\" .\" fileset_database@semget.2 PROGRAMING-MAN .\" $Header: semop.2,v 72.4 94/11/14 15:26:07 ssa Exp $ .TA s .TH semop 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME semop \- semaphore operations .SH SYNOPSIS .C "#include " .PP .nf .PD 0 .C "int semop(" .IP .C "int semid," .C "struct sembuf *sops," .C "unsigned int nsops" .PP .C ");" .PD .fi .SH DESCRIPTION .C semop() is used to atomically perform an array of semaphore operations on the set of semaphores associated with the semaphore identifier specified by .IR semid . .I sops is a pointer to the array of semaphore-operation structures. .I nsops is the number of such structures in the array. The contents of each structure includes the following members: .nf .IP .C "ushort sem_num; /* semaphore number */" .C "short sem_op /* semaphore operation */" .C "short sem_flg; /* operation flags */" .fi .PP Each semaphore operation specified by .I sem_op is performed on the corresponding semaphore specified by .I semid and .IR sem_num . Semaphore array operations are atomic in that none of the semaphore operations are performed until blocking conditions on all of the semaphores in the array have been removed. .PP .I sem_op specifies one of three semaphore operations as follows: .PP .RS If .I sem_op is a negative integer, one of the following occurs: .RS .PP If semval (see .I semaphore identifier in .IR glossary (9)) is greater than or equal to the absolute value of .IR sem_op , the absolute value of .I sem_op is subtracted from semval. Also, if .RI ( sem_flg " &" .CR SEM_UNDO ) is ``true'', the absolute value of .I sem_op is added to the calling process's semadj value (see .IR glossary (9) and .IR exit (2)) for the specified semaphore. .PP If semval is less than the absolute value of .I sem_op and .RI ( sem_flg " &" .CR IPC_NOWAIT ) is ``true'', .C semop() returns immediately. .PP If semval is less than the absolute value of .I sem_op and .RI ( sem_flg " &" .CR IPC_NOWAIT ) is ``false'', .C semop() increments the semncnt associated with the specified semaphore and suspend execution of the calling process until one of the following conditions occur: .RS .PP semval becomes greater than or equal to the absolute value of .IR sem_op . When this occurs, the value of semncnt associated with the specified semaphore is decremented, the absolute value of .I sem_op is subtracted from semval and, if .RI ( sem_flg " &" .CR SEM_UNDO ) is ``true'', the absolute value of .I sem_op is added to the calling process's semadj value for the specified semaphore. .PP The semid for which the calling process is awaiting action is removed from the system (see .IR semctl (2)). When this occurs, .C errno is set equal to .SM EIDRM, and a value of \(mi1 is returned. .PP The calling process receives a signal that is to be caught. When this occurs, the value of semncnt associated with the specified semaphore is decremented, and the calling process resumes execution in the manner prescribed in .IR signal (5). .RE .RE .PP If .I sem_op is a positive integer, the value of .I sem_op is added to semval and, if .RI ( sem_flg " &" .CR SEM_UNDO ) is ``true'', the value of .I sem_op is subtracted from the calling process's semadj value for the specified semaphore. .PP If .I sem_op is zero, one of the following occurs: .RS .PP If semval is zero, .C semop() proceeds to the next semaphore operation specified by .I sops, or returns immediately if this is the last operation. .PP If semval is not equal to zero and .RI ( sem_flg " &" .CR IPC_NOWAIT ) is ``true'', .C semop() returns immediately. .PP If semval is not equal to zero and .RI ( sem_flg " &" .CR IPC_NOWAIT ) is ``false'', .C semop() increments the semzcnt associated with the specified semaphore and suspends execution of the calling process until one of the following occurs: .RS .PP .I semval becomes zero, at which time the value of semzcnt associated with the specified semaphore is decremented. .PP The semid for which the calling process is awaiting action is removed from the system. When this occurs, .C errno is set equal to .SM EIDRM, and a value of \(mi1 is returned. .PP The calling process receives a signal that is to be caught. When this occurs, the value of semzcnt associated with the specified semaphore is decremented, and the calling process resumes execution in the manner prescribed in .IR signal (5). .RE .RE .RE .SH EXAMPLES The following call to .C semop() atomically performs a "P" or "get" operation on the second semaphore in the semaphore set and a "V" or "release" operation on the third semaphore in the set. This example assumes the process has a valid semid which represents a set of 4 semaphores as shown on the .IR semget (2) manual page. It also assumes that the semvals of the semaphores in the set have been initialized as shown in the .IR semctl (2) manual entry. .nf .IP .C struct sembuf sops[4]; .IP .C sops[0].sem_num = 1; .CR "sops[0].sem_op = -1;" "\h'.6i'/* P (get) */" .C sops[0].sem_flg = 0; .C sops[1].sem_num = 2; .CR "sops[1].sem_op = 1;" "\h'.6i'/* V (release) */" .C sops[1].sem_flg = 0; .IP .C semop (mysemid, sops, 2); .fi .SH RETURN VALUE If .C semop() returns due to the receipt of a signal, a value of \(mi1 is returned to the calling process and .C errno is set to .SM EINTR. If it returns due to the removal of a .I semid from the system, a value of \(mi1 is returned and .C errno is set to .SM EIDRM. .PP Upon successful completion, a non-negative value is returned. Otherwise, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .C semop() fails if one or more of the following is true for any of the semaphore operations specified by .IR sops : .RS .TP 15 .SM [EINVAL] .I semid is not a valid semaphore identifier. .TP .SM [EFBIG] .I sem_num is less than zero or greater than or equal to the number of semaphores in the set associated with .IR semid . .TP .SM [E2BIG] .I nsops is greater than the system-imposed maximum. .TP .SM [EACCES] Operation permission is denied to the calling process (see .IR glossary (9)). .TP .SM [EAGAIN] The operation would result in suspension of the calling process but .RI ( sem_flg " &" .CR IPC_NOWAIT ) is ``true''. .TP .SM [ENOSPC] The limit on the number of individual processes requesting an .C SEM_UNDO would be exceeded. .TP .SM [EINVAL] The number of individual semaphores for which the calling process requests a .C SEM_UNDO would exceed the limit. .TP .SM [ERANGE] An operation would cause a semval to overflow the system-imposed limit. .TP .SM [ERANGE] An operation would cause a semadj value to overflow the system-imposed limit. .TP .SM [EFAULT] .I sops points to an illegal address. The reliable detection of this error will be implementation dependent. .PP Upon successful completion, the value of sempid for each semaphore specified in the array pointed to by .I sops is set equal to the process .SM ID of the calling process. The value of .C sem_otime in the data structure associated with the semaphore identifier will be set to the current time. .RE .SH WARNINGS Check all references to .IR signal (5) for appropriateness on systems that support .IR sigvector (2). .IR sigvector (2) can affect the behavior described on this page. .SH SEE ALSO ipcs(1), exec(2), exit(2), fork(2), semctl(2), semget(2), stdipc(3C), signal(5). .SH STANDARDS CONFORMANCE .CR semop() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4semop()\fP \(mi semaphore operations@@@\f3semop(2)\f1 .\" index@semaphore operations@@@\f3semop(2)\f1 .\" index@operations, semaphore@@@\f3semop(2)\f1 .\" .\" toc@\f3semop(2)\f1:\0\0\f4semop()\fP@@@semaphore operations .\" .\" fileset_database@semop.2 PROGRAMING-MAN .\" $Header: send.2,v 78.2 96/03/15 16:44:31 ssa Exp $ .TA s .TH send 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME send(), sendmsg(), sendto() \- send a message from a socket .SH SYNOPSIS .nf .C "#include " .PP .C "int send(int s, const void *msg, int len, int flags);" .PP .C "int sendto(" .C " int s," .C " const void *msg," .C " int len," .C " int flags," .C " const void *to," .C " int tolen" .C ");" .PP .C "int sendmsg(int s, const struct msghdr msg[], int flags);" .fi .SS _XOPEN_SOURCE_EXTENDED only .SH .nf .C "ssize_t send(int s, const void *msg, size_t len, int flags);" .PP .C "ssize_t sendto(" .C " int s," .C " const void *msg," .C " size_t len," .C " int flags," .C " const struct sockaddr *to," .C " size_t tolen" .C ");" .PP .C "ssize_t sendmsg(int s, const struct msghdr *msg, int flags);" .fi .SH DESCRIPTION The .CR send() , .CR sendmsg() , and .CR sendto() system calls transmit a message to another socket. .CR send() can be used only when the socket is in a connected state, whereas .CR sendmsg() and .CR sendto() can be used at any time. .CR sendmsg() allows the send data to be gathered from several buffers specified in the .CR msghdr structure. See .IR recv (2) for a description of the .CR msghdr structure. .PP .I s is a socket descriptor that specifies the socket on which the message will be sent. .PP .I msg points to the buffer containing the message. .PP If the socket uses connection-based communications, such as a SOCK_STREAM socket, these calls can only be used after the connection has been established (see .IR connect (2)). In this case, any destination specified by .I to is ignored. For connectionless sockets, such as SOCK_DGRAM, .CR sendto() must be used unless the destination address has already been specified by .CR connect() . If the destination address has been specified and .CR sendto() is used, an error results if any address is specified by .IR to . .PP The address of the target socket is contained in a socket address structure pointed to by .IR to with .I tolen specifying the size of the structure. .PP If a .CR sendto() is attempted on a SOCK_DGRAM socket before any local address has been bound to it, the system automatically selects a local address to be used for the message. In this case, there is no guarantee that the same local address will be used for successive .CR sendto() requests on the same socket. .PP The length of the message is given by .IR len in bytes. The length of data actually sent is returned. If the message is too long to pass atomically through the underlying protocol, the message is not transmitted, .CR \(mi1 is returned, and .CR errno is set to [EMSGSIZE]. For SOCK_DGRAM sockets, this size is fixed by the implementation (see the DEPENDENCIES section). Otherwise there is no size limit. .PP When .CR send() or .CR sendto() returns a positive value, it only indicates this number of bytes have been sent to the local transport provider. It does not mean this number of bytes have been delivered to the peer socket application. A SOCK_DGRAM socket does not guarantee end-to-end delivery. A SOCK_STREAM socket guarantees eventual end-to-end delivery, however its underlying transport provider may later detect an irrecoverable error and returns a value of .CR \(mi1 at another socket function call. .PP When send() or .CR sendto() returns a value of .CR \(mi1 , it indicates a locally detected error. .CR errno is set to indicate the error. .PP If no buffer space is available to hold the data to be transmitted, .CR send() blocks unless nonblocking mode is enabled. The three ways to enable nonblocking mode are: .RS .TP 3 \(bu with the .CR FIOSNBIO .CR ioctl() request, .TP \(bu with the .CR O_NONBLOCK flag, and .TP \(bu with the .CR O_NDELAY .CR fcntl() flag. .RE .ift .br .ift .ne 12 .PP If nonblocking I/O is enabled using .CR FIOSNBIO or the equivalent .CR FIONBIO request (defined in .CR and explained in .IR ioctl (2), .IR ioctl (5), and .IR socket (7)), although the use of .CR FIONBIO is not recommended, the .CR send() request completes in one of three ways: .RS .TP 3 \(bu If there is enough space available in the system to buffer all of the data, .CR send() completes successfully, having written out all of the data, and returns the number of bytes written. .TP \(bu If there is not enough space in the buffer to write out the entire request, .CR send() completes successfully, having written as much data as possible, and returns the number of bytes it was able to write. .TP \(bu If there is no space in the system to buffer any of the data, .CR send() fails, having written no data, and .CR errno is set to [EWOULDBLOCK]. .RE .PP If nonblocking I/O is disabled using .CR FIOSNBIO , .CR send() always executes completely (blocking as necessary) and returns the number of bytes written. .PP If the .CR O_NONBLOCK flag is set using .CR fcntl() (defined in .CR and explained in .IR fcntl (2) and .IR fcntl (5)), POSIX-style nonblocking I/O is enabled. In this case, the .CR send() request completes in one of three ways: .RS .TP 3 \(bu If there is enough space available in the system to buffer all of the data, .CR send() completes successfully, having written out all of the data, and returns the number of bytes written. .TP \(bu If there is not enough space in the buffer to write out the entire request, .CR send() completes successfully, having written as much data as possible, and returns the number of bytes it was able to write. .TP \(bu If there is no space in the system to buffer any of the data, .CR send() completes, having written no data, and returns \(mi1, with .CR errno set to [EAGAIN]. .RE .PP If the .CR O_NDELAY flag is set using .CR fcntl() (defined in .CR and explained in .IR fcntl (2) and .IR fcntl (5)), nonblocking I/O is enabled. In this case, the .CR send() request completes in one of three ways: .RS .TP 3 \(bu If there is enough space available in the system to buffer all of the data, .CR send() completes successfully, having written out all of the data, and returns the number of bytes written. .TP \(bu If there is not enough space in the buffer to write out the entire request, .CR send() completes successfully, having written as much data as possible, and returns the number of bytes it was able to write. .TP \(bu If there is no space in the system to buffer any of the data, .CR send() completes successfully, having written no data, and returns 0. .RE .PP If the .CR O_NDELAY flag is cleared using .CR fcntl() , nonblocking I/O is disabled. In this case, the .CR send() always executes completely (blocking as necessary) and returns the number of bytes written. .PP Since the .CR fcntl() .CR O_NONBLOCK and .CR O_NDELAY flags and .CR ioctl() .CR FIOSNBIO requests are supported, the following clarifies on how these features interact. If the .CR O_NONBLOCK or .CR O_NDELAY flag has been set, .CR send() requests behave accordingly, regardless of any .CR FIOSNBIO requests. If neither the .CR O_NONBLOCK flag nor the .CR O_NDELAY flag has been set, .CR FIOSNBIO requests control the behavior of .CR send() . .PP By default nonblocking I/O is disabled. .PP The supported values for .I flags are zero or .CR MSG_OOB (to send out-of-band data). A .CR write() call made to a socket behaves in exactly the same way as .CR send() with .I flags set to zero. .CR MSG_OOB is not supported for AF_UNIX sockets. .PP .IR select (2) can be used to determine when it is possible to send more data. .SS AF_CCITT Only Sockets of the address family AF_CCITT operate in message mode. Although they are specified as connection-based (SOCK_STREAM) sockets, the X.25 subsystem communicates via messages. They require that a connection be established with the .CR connect() or .CR accept() calls. .PP The .CR O_NDELAY flag is not supported. Use .CR FIOSNBIO requests to control nonblocking I/O. If the available buffer space is not large enough for the entire message and the socket is in nonblocking mode, .CR errno is set to [EWOULDBLOCK]. If the amount of data in the .CR send() exceeds the maximum outbound message size, .CR errno is set to [EMSGSIZE]. .PP The .CR sendto() call is not supported. .PP Each call sends either a complete or a partial X.25 message. This is controlled by the setting of the More-Data-To-Follow (MDTF) bit. If the user wants to send a partial message, MDTF should be set to 1 before the .CR send() call. The MDTF bit should be cleared to 0 before sending the final message fragment. .PP Message fragment length may range from 0 bytes up to the size of the socket's send buffer (see .IR af_ccitt (7F)). The MDTF bit and multiple .CR send() calls can be combined to transmit complete X.25 packet sequences (i.e., zero or more DATA packets in which the More Data bit is set, followed by one DATA packet in which the More Data bit is clear) of arbitrary length. Note that a 0-byte message is not actually sent, but may be necessary to flush a complete X.25 message if the user is controlling the MDTF bit. .PP Sockets of the AF_CCITT address family can send 1 byte of out-of-band data (known as an INTERRUPT data packet in X.25 terminology), or up to 32 bytes if the X.25 interface is configured for 1984 CCITT X.25 recommendations. INTERRUPT data packets sent in blocking mode cause the process to block until confirmation is received. INTERRUPT data packets sent with the socket in nonblocking mode do not cause the process to block; instead, an out-of-band message is queued to the socket when the INTERRUPT confirmation packet is received (see .IR recv (2)). .SH _XOPEN_SOURCE_EXTENDED only .CR "X/Open Sockets msghdr" has the following form : .nf .IP .C "struct msghdr {" .C " void *msg_name; /* optional address */" .C " size_t msg_namelen; /* size of address */" .C " struct iovec *msg_iov; /* scatter array for data */" .C " int msg_iovlen; /* # of elements in msg_iov */" .C " void *msg_control; /* ancillary data, see below */" .C " size_t msg_controllen; /* ancillary data buffer len */" .C " int msg_flags; /* flags on received message */" .C "}" .fi .PP .I msg_control specifies a buffer of ancillary data to send along with the message. Ancillary data consists of a sequence of pairs, each consisting of a .I cmsghdr structure followed by a data array. The data array contains the ancillary data message, and the .I cmsghdr structure contains descriptive information that allows an application to correctly parse the data. .I cmsghdr has the following structure: .nf .IP .C "struct cmsghdr {" .C " size_t cmsg_len; /* data byte count, including hdr*/" .C " int cmsg_level; /* originating protocol */" .C " int cmsg_type; /* protocol-specific type */" .C "}" .fi .PP The supported value for cmsg_level is SOL_SOCKET. and the supported value for cmsg_type is SCM_RIGHTS. Together they indicate the data array contains the access rights to be sent. Access rights are supported only for AF_UNIX. Access rights are limited to file descriptors of size .IR int . If ancillary data are not being transferred, set the .I msg_control field to NULL and set the .I msg_controllen field to 0. .PP The .I msg_flags member is ignored. .SH RETURN VALUE .CR send() , .CR sendmsg() , and .CR sendto() return the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the number of bytes sent. .TP .CR \(mi1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR send() , .CR sendmsg() , or .CR sendto() fails, .CR errno is set to one of the following values. .RS .TP 20 [EACCES] Process doing a .CR send() of a broadcast packet does not have broadcast capability enabled for the socket. Use .CR setsockopt() to enable broadcast capability. .TP [EAFNOSUPPORT] The specified address is not a valid address for the address family of this socket. .TP [EAGAIN] Nonblocking I/O is enabled using the .CR O_NONBLOCK flag with .CR fcntl() , and the requested operation would block, or the socket has an error that was set asynchronously. An asynchronous error can be caused by a gateway failing to forward a datagram from this socket because the datagram exceeds the MTU of the next-hop network and the "Don't Fragment" (DF) bit in the datagram is set. (See .CR SO_PMTU in .IR getsockopt (2)). .TP [EBADF] .I s is not a valid file descriptor. .TP [ECONNRESET] A connection was forcibly closed by a peer. .TP [EDESTADDRREQ] The .I to parameter needs to specify a destination address for the message. This is also given if the specified address contains unspecified fields (see .IR inet (7F)). .TP [EFAULT] An invalid pointer was specified in the .I msg or .I to parameter, or in the .CR msghdr structure. .TP [EINTR] The operation was interrupted by a signal before any data was sent. (If some data was sent, .CR send() returns the number of bytes sent before the signal, and [EINTR] is not set). .TP [EINVAL] The .I len or .I tolen parameter, or a length in the .CR msghdr structure is invalid. A .CR sendto() system call was issued on an X.25 socket, or the connection is in its reset sequence and cannot accept data. .TP [EIO] A timeout occurred. .TP [EISCONN] An address was specified by .I to for a SOCK_DGRAM socket which is already connected. .TP [EMSGSIZE] A length in the .CR msghdr structure is invalid. The socket requires that messages be sent atomically, and the size of the message to be sent made this impossible. .IP SOCK_DGRAM/AF_INET or SOCK_STREAM/AF_CCITT: The message size exceeded the outbound buffer size. .TP [ENETDOWN] The interface used for the specified address is "down" (see .IR ifconfig (1M)), no interface for the specified address can be found (SO_DONTROUTE socket option in use), or the X.25 Level 2 is down. .TP [EHOSTUNREACH] The destination host is not reachable. .TP [ENETUNREACH] The destination network is not reachable. Some of the possible causes for this error are: .IP (LAN) All encapsulations (e.g., ether, ieee) have been turned off (see also .IR lanconfig (1M), and .IR ifconfig (1M)). .IP (X.25) The X.25 Level 2 is down. The X.25 link layer is not working (wires might be broken, connections are loose on the interface hoods at the modem, the modem failed, the packet switch at the remote end lost power or failed for some reason, or electrical noise interfered with the line for an extremely long period of time). .TP [ENOBUFS] No buffer space is available in the system to perform the operation. .TP [ENOTCONN] A .CR send() on a socket that is not connected, or a .CR send() on a socket that has not completed the connect sequence with its peer, or is no longer connected to its peer. .TP [ENOTSOCK] .I s is a valid file descriptor, but it is not a socket. .TP [EOPNOTSUPP] The .CR MSG_OOB flag was specified; it is not supported for AF_UNIX sockets. .TP .RC "[EPIPE] and " SIGPIPE " signal" An attempt was made to send on a socket that was connected, but the connection has been shut down either by the remote peer or by this side of the connection. Note that the default action for .CR SIGPIPE , unless the process has established a signal handler for this signal, is to terminate the process. .TP [EWOULDBLOCK] Nonblocking I/O is enabled using .CR ioctl() .CR FIOSNBIO request and the requested operation would block. .\" ZZZ .SH DEPENDENCIES UDP messages are fragmented at the IP level into Maximum Transmission Unit (MTU) sized pieces; MTU varies for different link types. These pieces, called IP fragments, can be transmitted, but IP does not guarantee delivery. Sending large messages may cause too many fragments and overrun a receiver's ability to receive them. If this happens the complete message cannot be reassembled. This affects the apparent reliability and throughput of the network as viewed by the end user. .PP The default and maximum buffer sizes are protocol-specific. Refer to the appropriate entries in Sections 7F and 7P for details. The buffer size can be set by calling .CR setsockopt() with .CR SO_SNDBUF . .SS AF_CCITT If the receiving process is on a Series 700/800 HP-UX system and the connection has been set up to use the D-bit, data sent with the D-bit set is acknowledged when the receiving process has read the data. Otherwise, the acknowledgement is sent when the firmware receives it. .SH AUTHOR .CR send() was developed at the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO ifconfig(1M), lanconfig(1M), getsockopt(2), recv(2), select(2), setsockopt(2), socket(2), socket(7), socketx25(7), af_ccitt(7F), inet(7F), tcp(7P), udp(7P), unix(7P), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR send() ": XPG4" .\" .\" index@\f4send()\f1 \- send message to a socket@@@\f3send(2)\f1 .\" index@\f4sendmsg()\f1 \- send message to a socket@@@\f3send(2)\f1 .\" index@\f4sendto()\f1 \- send message to a socket@@@\f3send(2)\f1 .\" index@message, send to a socket@@@\f3send(2)\f1 .\" index@send message to a socket@@@\f3send(2)\f1 .\" index@socket, send message to a@@@\f3send(2)\f1 .\" .\" links@send.2 sendmsg.2 .\" links@send.2 sendto.2 .\" .\" toc@\f3send(2)\f1:\0\0\f4send()\f1, \f4sendto()\f1@@@send message to a socket .\" toc@\f4sendmsg()\f1:\0\0send message to a socket@@@see \f3send(2)\f1 .\" toc@\f4sendto()\f1:\0\0send message to a socket@@@see \f3send(2)\f1 .\" $Header: send.2,v 78.2 96/03/15 16:44:31 ssa Exp $ .TA s .TH send 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME send(), sendmsg(), sendto() \- send a message from a socket .SH SYNOPSIS .nf .C "#include " .PP .C "int send(int s, const void *msg, int len, int flags);" .PP .C "int sendto(" .C " int s," .C " const void *msg," .C " int len," .C " int flags," .C " const void *to," .C " int tolen" .C ");" .PP .C "int sendmsg(int s, const struct msghdr msg[], int flags);" .fi .SS _XOPEN_SOURCE_EXTENDED only .SH .nf .C "ssize_t send(int s, const void *msg, size_t len, int flags);" .PP .C "ssize_t sendto(" .C " int s," .C " const void *msg," .C " size_t len," .C " int flags," .C " const struct sockaddr *to," .C " size_t tolen" .C ");" .PP .C "ssize_t sendmsg(int s, const struct msghdr *msg, int flags);" .fi .SH DESCRIPTION The .CR send() , .CR sendmsg() , and .CR sendto() system calls transmit a message to another socket. .CR send() can be used only when the socket is in a connected state, whereas .CR sendmsg() and .CR sendto() can be used at any time. .CR sendmsg() allows the send data to be gathered from several buffers specified in the .CR msghdr structure. See .IR recv (2) for a description of the .CR msghdr structure. .PP .I s is a socket descriptor that specifies the socket on which the message will be sent. .PP .I msg points to the buffer containing the message. .PP If the socket uses connection-based communications, such as a SOCK_STREAM socket, these calls can only be used after the connection has been established (see .IR connect (2)). In this case, any destination specified by .I to is ignored. For connectionless sockets, such as SOCK_DGRAM, .CR sendto() must be used unless the destination address has already been specified by .CR connect() . If the destination address has been specified and .CR sendto() is used, an error results if any address is specified by .IR to . .PP The address of the target socket is contained in a socket address structure pointed to by .IR to with .I tolen specifying the size of the structure. .PP If a .CR sendto() is attempted on a SOCK_DGRAM socket before any local address has been bound to it, the system automatically selects a local address to be used for the message. In this case, there is no guarantee that the same local address will be used for successive .CR sendto() requests on the same socket. .PP The length of the message is given by .IR len in bytes. The length of data actually sent is returned. If the message is too long to pass atomically through the underlying protocol, the message is not transmitted, .CR \(mi1 is returned, and .CR errno is set to [EMSGSIZE]. For SOCK_DGRAM sockets, this size is fixed by the implementation (see the DEPENDENCIES section). Otherwise there is no size limit. .PP When .CR send() or .CR sendto() returns a positive value, it only indicates this number of bytes have been sent to the local transport provider. It does not mean this number of bytes have been delivered to the peer socket application. A SOCK_DGRAM socket does not guarantee end-to-end delivery. A SOCK_STREAM socket guarantees eventual end-to-end delivery, however its underlying transport provider may later detect an irrecoverable error and returns a value of .CR \(mi1 at another socket function call. .PP When send() or .CR sendto() returns a value of .CR \(mi1 , it indicates a locally detected error. .CR errno is set to indicate the error. .PP If no buffer space is available to hold the data to be transmitted, .CR send() blocks unless nonblocking mode is enabled. The three ways to enable nonblocking mode are: .RS .TP 3 \(bu with the .CR FIOSNBIO .CR ioctl() request, .TP \(bu with the .CR O_NONBLOCK flag, and .TP \(bu with the .CR O_NDELAY .CR fcntl() flag. .RE .ift .br .ift .ne 12 .PP If nonblocking I/O is enabled using .CR FIOSNBIO or the equivalent .CR FIONBIO request (defined in .CR and explained in .IR ioctl (2), .IR ioctl (5), and .IR socket (7)), although the use of .CR FIONBIO is not recommended, the .CR send() request completes in one of three ways: .RS .TP 3 \(bu If there is enough space available in the system to buffer all of the data, .CR send() completes successfully, having written out all of the data, and returns the number of bytes written. .TP \(bu If there is not enough space in the buffer to write out the entire request, .CR send() completes successfully, having written as much data as possible, and returns the number of bytes it was able to write. .TP \(bu If there is no space in the system to buffer any of the data, .CR send() fails, having written no data, and .CR errno is set to [EWOULDBLOCK]. .RE .PP If nonblocking I/O is disabled using .CR FIOSNBIO , .CR send() always executes completely (blocking as necessary) and returns the number of bytes written. .PP If the .CR O_NONBLOCK flag is set using .CR fcntl() (defined in .CR and explained in .IR fcntl (2) and .IR fcntl (5)), POSIX-style nonblocking I/O is enabled. In this case, the .CR send() request completes in one of three ways: .RS .TP 3 \(bu If there is enough space available in the system to buffer all of the data, .CR send() completes successfully, having written out all of the data, and returns the number of bytes written. .TP \(bu If there is not enough space in the buffer to write out the entire request, .CR send() completes successfully, having written as much data as possible, and returns the number of bytes it was able to write. .TP \(bu If there is no space in the system to buffer any of the data, .CR send() completes, having written no data, and returns \(mi1, with .CR errno set to [EAGAIN]. .RE .PP If the .CR O_NDELAY flag is set using .CR fcntl() (defined in .CR and explained in .IR fcntl (2) and .IR fcntl (5)), nonblocking I/O is enabled. In this case, the .CR send() request completes in one of three ways: .RS .TP 3 \(bu If there is enough space available in the system to buffer all of the data, .CR send() completes successfully, having written out all of the data, and returns the number of bytes written. .TP \(bu If there is not enough space in the buffer to write out the entire request, .CR send() completes successfully, having written as much data as possible, and returns the number of bytes it was able to write. .TP \(bu If there is no space in the system to buffer any of the data, .CR send() completes successfully, having written no data, and returns 0. .RE .PP If the .CR O_NDELAY flag is cleared using .CR fcntl() , nonblocking I/O is disabled. In this case, the .CR send() always executes completely (blocking as necessary) and returns the number of bytes written. .PP Since the .CR fcntl() .CR O_NONBLOCK and .CR O_NDELAY flags and .CR ioctl() .CR FIOSNBIO requests are supported, the following clarifies on how these features interact. If the .CR O_NONBLOCK or .CR O_NDELAY flag has been set, .CR send() requests behave accordingly, regardless of any .CR FIOSNBIO requests. If neither the .CR O_NONBLOCK flag nor the .CR O_NDELAY flag has been set, .CR FIOSNBIO requests control the behavior of .CR send() . .PP By default nonblocking I/O is disabled. .PP The supported values for .I flags are zero or .CR MSG_OOB (to send out-of-band data). A .CR write() call made to a socket behaves in exactly the same way as .CR send() with .I flags set to zero. .CR MSG_OOB is not supported for AF_UNIX sockets. .PP .IR select (2) can be used to determine when it is possible to send more data. .SS AF_CCITT Only Sockets of the address family AF_CCITT operate in message mode. Although they are specified as connection-based (SOCK_STREAM) sockets, the X.25 subsystem communicates via messages. They require that a connection be established with the .CR connect() or .CR accept() calls. .PP The .CR O_NDELAY flag is not supported. Use .CR FIOSNBIO requests to control nonblocking I/O. If the available buffer space is not large enough for the entire message and the socket is in nonblocking mode, .CR errno is set to [EWOULDBLOCK]. If the amount of data in the .CR send() exceeds the maximum outbound message size, .CR errno is set to [EMSGSIZE]. .PP The .CR sendto() call is not supported. .PP Each call sends either a complete or a partial X.25 message. This is controlled by the setting of the More-Data-To-Follow (MDTF) bit. If the user wants to send a partial message, MDTF should be set to 1 before the .CR send() call. The MDTF bit should be cleared to 0 before sending the final message fragment. .PP Message fragment length may range from 0 bytes up to the size of the socket's send buffer (see .IR af_ccitt (7F)). The MDTF bit and multiple .CR send() calls can be combined to transmit complete X.25 packet sequences (i.e., zero or more DATA packets in which the More Data bit is set, followed by one DATA packet in which the More Data bit is clear) of arbitrary length. Note that a 0-byte message is not actually sent, but may be necessary to flush a complete X.25 message if the user is controlling the MDTF bit. .PP Sockets of the AF_CCITT address family can send 1 byte of out-of-band data (known as an INTERRUPT data packet in X.25 terminology), or up to 32 bytes if the X.25 interface is configured for 1984 CCITT X.25 recommendations. INTERRUPT data packets sent in blocking mode cause the process to block until confirmation is received. INTERRUPT data packets sent with the socket in nonblocking mode do not cause the process to block; instead, an out-of-band message is queued to the socket when the INTERRUPT confirmation packet is received (see .IR recv (2)). .SH _XOPEN_SOURCE_EXTENDED only .CR "X/Open Sockets msghdr" has the following form : .nf .IP .C "struct msghdr {" .C " void *msg_name; /* optional address */" .C " size_t msg_namelen; /* size of address */" .C " struct iovec *msg_iov; /* scatter array for data */" .C " int msg_iovlen; /* # of elements in msg_iov */" .C " void *msg_control; /* ancillary data, see below */" .C " size_t msg_controllen; /* ancillary data buffer len */" .C " int msg_flags; /* flags on received message */" .C "}" .fi .PP .I msg_control specifies a buffer of ancillary data to send along with the message. Ancillary data consists of a sequence of pairs, each consisting of a .I cmsghdr structure followed by a data array. The data array contains the ancillary data message, and the .I cmsghdr structure contains descriptive information that allows an application to correctly parse the data. .I cmsghdr has the following structure: .nf .IP .C "struct cmsghdr {" .C " size_t cmsg_len; /* data byte count, including hdr*/" .C " int cmsg_level; /* originating protocol */" .C " int cmsg_type; /* protocol-specific type */" .C "}" .fi .PP The supported value for cmsg_level is SOL_SOCKET. and the supported value for cmsg_type is SCM_RIGHTS. Together they indicate the data array contains the access rights to be sent. Access rights are supported only for AF_UNIX. Access rights are limited to file descriptors of size .IR int . If ancillary data are not being transferred, set the .I msg_control field to NULL and set the .I msg_controllen field to 0. .PP The .I msg_flags member is ignored. .SH RETURN VALUE .CR send() , .CR sendmsg() , and .CR sendto() return the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the number of bytes sent. .TP .CR \(mi1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR send() , .CR sendmsg() , or .CR sendto() fails, .CR errno is set to one of the following values. .RS .TP 20 [EACCES] Process doing a .CR send() of a broadcast packet does not have broadcast capability enabled for the socket. Use .CR setsockopt() to enable broadcast capability. .TP [EAFNOSUPPORT] The specified address is not a valid address for the address family of this socket. .TP [EAGAIN] Nonblocking I/O is enabled using the .CR O_NONBLOCK flag with .CR fcntl() , and the requested operation would block, or the socket has an error that was set asynchronously. An asynchronous error can be caused by a gateway failing to forward a datagram from this socket because the datagram exceeds the MTU of the next-hop network and the "Don't Fragment" (DF) bit in the datagram is set. (See .CR SO_PMTU in .IR getsockopt (2)). .TP [EBADF] .I s is not a valid file descriptor. .TP [ECONNRESET] A connection was forcibly closed by a peer. .TP [EDESTADDRREQ] The .I to parameter needs to specify a destination address for the message. This is also given if the specified address contains unspecified fields (see .IR inet (7F)). .TP [EFAULT] An invalid pointer was specified in the .I msg or .I to parameter, or in the .CR msghdr structure. .TP [EINTR] The operation was interrupted by a signal before any data was sent. (If some data was sent, .CR send() returns the number of bytes sent before the signal, and [EINTR] is not set). .TP [EINVAL] The .I len or .I tolen parameter, or a length in the .CR msghdr structure is invalid. A .CR sendto() system call was issued on an X.25 socket, or the connection is in its reset sequence and cannot accept data. .TP [EIO] A timeout occurred. .TP [EISCONN] An address was specified by .I to for a SOCK_DGRAM socket which is already connected. .TP [EMSGSIZE] A length in the .CR msghdr structure is invalid. The socket requires that messages be sent atomically, and the size of the message to be sent made this impossible. .IP SOCK_DGRAM/AF_INET or SOCK_STREAM/AF_CCITT: The message size exceeded the outbound buffer size. .TP [ENETDOWN] The interface used for the specified address is "down" (see .IR ifconfig (1M)), no interface for the specified address can be found (SO_DONTROUTE socket option in use), or the X.25 Level 2 is down. .TP [EHOSTUNREACH] The destination host is not reachable. .TP [ENETUNREACH] The destination network is not reachable. Some of the possible causes for this error are: .IP (LAN) All encapsulations (e.g., ether, ieee) have been turned off (see also .IR lanconfig (1M), and .IR ifconfig (1M)). .IP (X.25) The X.25 Level 2 is down. The X.25 link layer is not working (wires might be broken, connections are loose on the interface hoods at the modem, the modem failed, the packet switch at the remote end lost power or failed for some reason, or electrical noise interfered with the line for an extremely long period of time). .TP [ENOBUFS] No buffer space is available in the system to perform the operation. .TP [ENOTCONN] A .CR send() on a socket that is not connected, or a .CR send() on a socket that has not completed the connect sequence with its peer, or is no longer connected to its peer. .TP [ENOTSOCK] .I s is a valid file descriptor, but it is not a socket. .TP [EOPNOTSUPP] The .CR MSG_OOB flag was specified; it is not supported for AF_UNIX sockets. .TP .RC "[EPIPE] and " SIGPIPE " signal" An attempt was made to send on a socket that was connected, but the connection has been shut down either by the remote peer or by this side of the connection. Note that the default action for .CR SIGPIPE , unless the process has established a signal handler for this signal, is to terminate the process. .TP [EWOULDBLOCK] Nonblocking I/O is enabled using .CR ioctl() .CR FIOSNBIO request and the requested operation would block. .\" ZZZ .SH DEPENDENCIES UDP messages are fragmented at the IP level into Maximum Transmission Unit (MTU) sized pieces; MTU varies for different link types. These pieces, called IP fragments, can be transmitted, but IP does not guarantee delivery. Sending large messages may cause too many fragments and overrun a receiver's ability to receive them. If this happens the complete message cannot be reassembled. This affects the apparent reliability and throughput of the network as viewed by the end user. .PP The default and maximum buffer sizes are protocol-specific. Refer to the appropriate entries in Sections 7F and 7P for details. The buffer size can be set by calling .CR setsockopt() with .CR SO_SNDBUF . .SS AF_CCITT If the receiving process is on a Series 700/800 HP-UX system and the connection has been set up to use the D-bit, data sent with the D-bit set is acknowledged when the receiving process has read the data. Otherwise, the acknowledgement is sent when the firmware receives it. .SH AUTHOR .CR send() was developed at the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO ifconfig(1M), lanconfig(1M), getsockopt(2), recv(2), select(2), setsockopt(2), socket(2), socket(7), socketx25(7), af_ccitt(7F), inet(7F), tcp(7P), udp(7P), unix(7P), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR send() ": XPG4" .\" .\" index@\f4send()\f1 \- send message to a socket@@@\f3send(2)\f1 .\" index@\f4sendmsg()\f1 \- send message to a socket@@@\f3send(2)\f1 .\" index@\f4sendto()\f1 \- send message to a socket@@@\f3send(2)\f1 .\" index@message, send to a socket@@@\f3send(2)\f1 .\" index@send message to a socket@@@\f3send(2)\f1 .\" index@socket, send message to a@@@\f3send(2)\f1 .\" .\" links@send.2 sendmsg.2 .\" links@send.2 sendto.2 .\" .\" toc@\f3send(2)\f1:\0\0\f4send()\f1, \f4sendto()\f1@@@send message to a socket .\" toc@\f4sendmsg()\f1:\0\0send message to a socket@@@see \f3send(2)\f1 .\" toc@\f4sendto()\f1:\0\0send message to a socket@@@see \f3send(2)\f1 .\" $Header: send.2,v 78.2 96/03/15 16:44:31 ssa Exp $ .TA s .TH send 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME send(), sendmsg(), sendto() \- send a message from a socket .SH SYNOPSIS .nf .C "#include " .PP .C "int send(int s, const void *msg, int len, int flags);" .PP .C "int sendto(" .C " int s," .C " const void *msg," .C " int len," .C " int flags," .C " const void *to," .C " int tolen" .C ");" .PP .C "int sendmsg(int s, const struct msghdr msg[], int flags);" .fi .SS _XOPEN_SOURCE_EXTENDED only .SH .nf .C "ssize_t send(int s, const void *msg, size_t len, int flags);" .PP .C "ssize_t sendto(" .C " int s," .C " const void *msg," .C " size_t len," .C " int flags," .C " const struct sockaddr *to," .C " size_t tolen" .C ");" .PP .C "ssize_t sendmsg(int s, const struct msghdr *msg, int flags);" .fi .SH DESCRIPTION The .CR send() , .CR sendmsg() , and .CR sendto() system calls transmit a message to another socket. .CR send() can be used only when the socket is in a connected state, whereas .CR sendmsg() and .CR sendto() can be used at any time. .CR sendmsg() allows the send data to be gathered from several buffers specified in the .CR msghdr structure. See .IR recv (2) for a description of the .CR msghdr structure. .PP .I s is a socket descriptor that specifies the socket on which the message will be sent. .PP .I msg points to the buffer containing the message. .PP If the socket uses connection-based communications, such as a SOCK_STREAM socket, these calls can only be used after the connection has been established (see .IR connect (2)). In this case, any destination specified by .I to is ignored. For connectionless sockets, such as SOCK_DGRAM, .CR sendto() must be used unless the destination address has already been specified by .CR connect() . If the destination address has been specified and .CR sendto() is used, an error results if any address is specified by .IR to . .PP The address of the target socket is contained in a socket address structure pointed to by .IR to with .I tolen specifying the size of the structure. .PP If a .CR sendto() is attempted on a SOCK_DGRAM socket before any local address has been bound to it, the system automatically selects a local address to be used for the message. In this case, there is no guarantee that the same local address will be used for successive .CR sendto() requests on the same socket. .PP The length of the message is given by .IR len in bytes. The length of data actually sent is returned. If the message is too long to pass atomically through the underlying protocol, the message is not transmitted, .CR \(mi1 is returned, and .CR errno is set to [EMSGSIZE]. For SOCK_DGRAM sockets, this size is fixed by the implementation (see the DEPENDENCIES section). Otherwise there is no size limit. .PP When .CR send() or .CR sendto() returns a positive value, it only indicates this number of bytes have been sent to the local transport provider. It does not mean this number of bytes have been delivered to the peer socket application. A SOCK_DGRAM socket does not guarantee end-to-end delivery. A SOCK_STREAM socket guarantees eventual end-to-end delivery, however its underlying transport provider may later detect an irrecoverable error and returns a value of .CR \(mi1 at another socket function call. .PP When send() or .CR sendto() returns a value of .CR \(mi1 , it indicates a locally detected error. .CR errno is set to indicate the error. .PP If no buffer space is available to hold the data to be transmitted, .CR send() blocks unless nonblocking mode is enabled. The three ways to enable nonblocking mode are: .RS .TP 3 \(bu with the .CR FIOSNBIO .CR ioctl() request, .TP \(bu with the .CR O_NONBLOCK flag, and .TP \(bu with the .CR O_NDELAY .CR fcntl() flag. .RE .ift .br .ift .ne 12 .PP If nonblocking I/O is enabled using .CR FIOSNBIO or the equivalent .CR FIONBIO request (defined in .CR and explained in .IR ioctl (2), .IR ioctl (5), and .IR socket (7)), although the use of .CR FIONBIO is not recommended, the .CR send() request completes in one of three ways: .RS .TP 3 \(bu If there is enough space available in the system to buffer all of the data, .CR send() completes successfully, having written out all of the data, and returns the number of bytes written. .TP \(bu If there is not enough space in the buffer to write out the entire request, .CR send() completes successfully, having written as much data as possible, and returns the number of bytes it was able to write. .TP \(bu If there is no space in the system to buffer any of the data, .CR send() fails, having written no data, and .CR errno is set to [EWOULDBLOCK]. .RE .PP If nonblocking I/O is disabled using .CR FIOSNBIO , .CR send() always executes completely (blocking as necessary) and returns the number of bytes written. .PP If the .CR O_NONBLOCK flag is set using .CR fcntl() (defined in .CR and explained in .IR fcntl (2) and .IR fcntl (5)), POSIX-style nonblocking I/O is enabled. In this case, the .CR send() request completes in one of three ways: .RS .TP 3 \(bu If there is enough space available in the system to buffer all of the data, .CR send() completes successfully, having written out all of the data, and returns the number of bytes written. .TP \(bu If there is not enough space in the buffer to write out the entire request, .CR send() completes successfully, having written as much data as possible, and returns the number of bytes it was able to write. .TP \(bu If there is no space in the system to buffer any of the data, .CR send() completes, having written no data, and returns \(mi1, with .CR errno set to [EAGAIN]. .RE .PP If the .CR O_NDELAY flag is set using .CR fcntl() (defined in .CR and explained in .IR fcntl (2) and .IR fcntl (5)), nonblocking I/O is enabled. In this case, the .CR send() request completes in one of three ways: .RS .TP 3 \(bu If there is enough space available in the system to buffer all of the data, .CR send() completes successfully, having written out all of the data, and returns the number of bytes written. .TP \(bu If there is not enough space in the buffer to write out the entire request, .CR send() completes successfully, having written as much data as possible, and returns the number of bytes it was able to write. .TP \(bu If there is no space in the system to buffer any of the data, .CR send() completes successfully, having written no data, and returns 0. .RE .PP If the .CR O_NDELAY flag is cleared using .CR fcntl() , nonblocking I/O is disabled. In this case, the .CR send() always executes completely (blocking as necessary) and returns the number of bytes written. .PP Since the .CR fcntl() .CR O_NONBLOCK and .CR O_NDELAY flags and .CR ioctl() .CR FIOSNBIO requests are supported, the following clarifies on how these features interact. If the .CR O_NONBLOCK or .CR O_NDELAY flag has been set, .CR send() requests behave accordingly, regardless of any .CR FIOSNBIO requests. If neither the .CR O_NONBLOCK flag nor the .CR O_NDELAY flag has been set, .CR FIOSNBIO requests control the behavior of .CR send() . .PP By default nonblocking I/O is disabled. .PP The supported values for .I flags are zero or .CR MSG_OOB (to send out-of-band data). A .CR write() call made to a socket behaves in exactly the same way as .CR send() with .I flags set to zero. .CR MSG_OOB is not supported for AF_UNIX sockets. .PP .IR select (2) can be used to determine when it is possible to send more data. .SS AF_CCITT Only Sockets of the address family AF_CCITT operate in message mode. Although they are specified as connection-based (SOCK_STREAM) sockets, the X.25 subsystem communicates via messages. They require that a connection be established with the .CR connect() or .CR accept() calls. .PP The .CR O_NDELAY flag is not supported. Use .CR FIOSNBIO requests to control nonblocking I/O. If the available buffer space is not large enough for the entire message and the socket is in nonblocking mode, .CR errno is set to [EWOULDBLOCK]. If the amount of data in the .CR send() exceeds the maximum outbound message size, .CR errno is set to [EMSGSIZE]. .PP The .CR sendto() call is not supported. .PP Each call sends either a complete or a partial X.25 message. This is controlled by the setting of the More-Data-To-Follow (MDTF) bit. If the user wants to send a partial message, MDTF should be set to 1 before the .CR send() call. The MDTF bit should be cleared to 0 before sending the final message fragment. .PP Message fragment length may range from 0 bytes up to the size of the socket's send buffer (see .IR af_ccitt (7F)). The MDTF bit and multiple .CR send() calls can be combined to transmit complete X.25 packet sequences (i.e., zero or more DATA packets in which the More Data bit is set, followed by one DATA packet in which the More Data bit is clear) of arbitrary length. Note that a 0-byte message is not actually sent, but may be necessary to flush a complete X.25 message if the user is controlling the MDTF bit. .PP Sockets of the AF_CCITT address family can send 1 byte of out-of-band data (known as an INTERRUPT data packet in X.25 terminology), or up to 32 bytes if the X.25 interface is configured for 1984 CCITT X.25 recommendations. INTERRUPT data packets sent in blocking mode cause the process to block until confirmation is received. INTERRUPT data packets sent with the socket in nonblocking mode do not cause the process to block; instead, an out-of-band message is queued to the socket when the INTERRUPT confirmation packet is received (see .IR recv (2)). .SH _XOPEN_SOURCE_EXTENDED only .CR "X/Open Sockets msghdr" has the following form : .nf .IP .C "struct msghdr {" .C " void *msg_name; /* optional address */" .C " size_t msg_namelen; /* size of address */" .C " struct iovec *msg_iov; /* scatter array for data */" .C " int msg_iovlen; /* # of elements in msg_iov */" .C " void *msg_control; /* ancillary data, see below */" .C " size_t msg_controllen; /* ancillary data buffer len */" .C " int msg_flags; /* flags on received message */" .C "}" .fi .PP .I msg_control specifies a buffer of ancillary data to send along with the message. Ancillary data consists of a sequence of pairs, each consisting of a .I cmsghdr structure followed by a data array. The data array contains the ancillary data message, and the .I cmsghdr structure contains descriptive information that allows an application to correctly parse the data. .I cmsghdr has the following structure: .nf .IP .C "struct cmsghdr {" .C " size_t cmsg_len; /* data byte count, including hdr*/" .C " int cmsg_level; /* originating protocol */" .C " int cmsg_type; /* protocol-specific type */" .C "}" .fi .PP The supported value for cmsg_level is SOL_SOCKET. and the supported value for cmsg_type is SCM_RIGHTS. Together they indicate the data array contains the access rights to be sent. Access rights are supported only for AF_UNIX. Access rights are limited to file descriptors of size .IR int . If ancillary data are not being transferred, set the .I msg_control field to NULL and set the .I msg_controllen field to 0. .PP The .I msg_flags member is ignored. .SH RETURN VALUE .CR send() , .CR sendmsg() , and .CR sendto() return the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the number of bytes sent. .TP .CR \(mi1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR send() , .CR sendmsg() , or .CR sendto() fails, .CR errno is set to one of the following values. .RS .TP 20 [EACCES] Process doing a .CR send() of a broadcast packet does not have broadcast capability enabled for the socket. Use .CR setsockopt() to enable broadcast capability. .TP [EAFNOSUPPORT] The specified address is not a valid address for the address family of this socket. .TP [EAGAIN] Nonblocking I/O is enabled using the .CR O_NONBLOCK flag with .CR fcntl() , and the requested operation would block, or the socket has an error that was set asynchronously. An asynchronous error can be caused by a gateway failing to forward a datagram from this socket because the datagram exceeds the MTU of the next-hop network and the "Don't Fragment" (DF) bit in the datagram is set. (See .CR SO_PMTU in .IR getsockopt (2)). .TP [EBADF] .I s is not a valid file descriptor. .TP [ECONNRESET] A connection was forcibly closed by a peer. .TP [EDESTADDRREQ] The .I to parameter needs to specify a destination address for the message. This is also given if the specified address contains unspecified fields (see .IR inet (7F)). .TP [EFAULT] An invalid pointer was specified in the .I msg or .I to parameter, or in the .CR msghdr structure. .TP [EINTR] The operation was interrupted by a signal before any data was sent. (If some data was sent, .CR send() returns the number of bytes sent before the signal, and [EINTR] is not set). .TP [EINVAL] The .I len or .I tolen parameter, or a length in the .CR msghdr structure is invalid. A .CR sendto() system call was issued on an X.25 socket, or the connection is in its reset sequence and cannot accept data. .TP [EIO] A timeout occurred. .TP [EISCONN] An address was specified by .I to for a SOCK_DGRAM socket which is already connected. .TP [EMSGSIZE] A length in the .CR msghdr structure is invalid. The socket requires that messages be sent atomically, and the size of the message to be sent made this impossible. .IP SOCK_DGRAM/AF_INET or SOCK_STREAM/AF_CCITT: The message size exceeded the outbound buffer size. .TP [ENETDOWN] The interface used for the specified address is "down" (see .IR ifconfig (1M)), no interface for the specified address can be found (SO_DONTROUTE socket option in use), or the X.25 Level 2 is down. .TP [EHOSTUNREACH] The destination host is not reachable. .TP [ENETUNREACH] The destination network is not reachable. Some of the possible causes for this error are: .IP (LAN) All encapsulations (e.g., ether, ieee) have been turned off (see also .IR lanconfig (1M), and .IR ifconfig (1M)). .IP (X.25) The X.25 Level 2 is down. The X.25 link layer is not working (wires might be broken, connections are loose on the interface hoods at the modem, the modem failed, the packet switch at the remote end lost power or failed for some reason, or electrical noise interfered with the line for an extremely long period of time). .TP [ENOBUFS] No buffer space is available in the system to perform the operation. .TP [ENOTCONN] A .CR send() on a socket that is not connected, or a .CR send() on a socket that has not completed the connect sequence with its peer, or is no longer connected to its peer. .TP [ENOTSOCK] .I s is a valid file descriptor, but it is not a socket. .TP [EOPNOTSUPP] The .CR MSG_OOB flag was specified; it is not supported for AF_UNIX sockets. .TP .RC "[EPIPE] and " SIGPIPE " signal" An attempt was made to send on a socket that was connected, but the connection has been shut down either by the remote peer or by this side of the connection. Note that the default action for .CR SIGPIPE , unless the process has established a signal handler for this signal, is to terminate the process. .TP [EWOULDBLOCK] Nonblocking I/O is enabled using .CR ioctl() .CR FIOSNBIO request and the requested operation would block. .\" ZZZ .SH DEPENDENCIES UDP messages are fragmented at the IP level into Maximum Transmission Unit (MTU) sized pieces; MTU varies for different link types. These pieces, called IP fragments, can be transmitted, but IP does not guarantee delivery. Sending large messages may cause too many fragments and overrun a receiver's ability to receive them. If this happens the complete message cannot be reassembled. This affects the apparent reliability and throughput of the network as viewed by the end user. .PP The default and maximum buffer sizes are protocol-specific. Refer to the appropriate entries in Sections 7F and 7P for details. The buffer size can be set by calling .CR setsockopt() with .CR SO_SNDBUF . .SS AF_CCITT If the receiving process is on a Series 700/800 HP-UX system and the connection has been set up to use the D-bit, data sent with the D-bit set is acknowledged when the receiving process has read the data. Otherwise, the acknowledgement is sent when the firmware receives it. .SH AUTHOR .CR send() was developed at the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO ifconfig(1M), lanconfig(1M), getsockopt(2), recv(2), select(2), setsockopt(2), socket(2), socket(7), socketx25(7), af_ccitt(7F), inet(7F), tcp(7P), udp(7P), unix(7P), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR send() ": XPG4" .\" .\" index@\f4send()\f1 \- send message to a socket@@@\f3send(2)\f1 .\" index@\f4sendmsg()\f1 \- send message to a socket@@@\f3send(2)\f1 .\" index@\f4sendto()\f1 \- send message to a socket@@@\f3send(2)\f1 .\" index@message, send to a socket@@@\f3send(2)\f1 .\" index@send message to a socket@@@\f3send(2)\f1 .\" index@socket, send message to a@@@\f3send(2)\f1 .\" .\" links@send.2 sendmsg.2 .\" links@send.2 sendto.2 .\" .\" toc@\f3send(2)\f1:\0\0\f4send()\f1, \f4sendto()\f1@@@send message to a socket .\" toc@\f4sendmsg()\f1:\0\0send message to a socket@@@see \f3send(2)\f1 .\" toc@\f4sendto()\f1:\0\0send message to a socket@@@see \f3send(2)\f1 .\" $Header: serialize.2,v 72.2 94/07/22 15:59:29 ssa Exp $ .TA s .TH serialize 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME serialize() \- force target process to run serially with other processes .SH SYNOPSIS .C "#include .PP .C "int serialize(timeshare, pid);" .SH DESCRIPTION The .CR serialize() system call is used to force the target process referenced by the .IR pid value passed in to run serially with other processes also marked for serialization. If the value of .IR pid is zero, then the currently running process is marked for serialization. Once a process has been marked by .CR serialize() , the process stays marked until process completion, unless .CR serialize() is reissued on the serialized process with .IR timeshare set to 1. If .IR timeshare is set to 1, the process specified in .CR pid will be returned to normal timeshare scheduling algorithms. .PP This call is used to improve process throughput since process throughput usually increases for large processes when they are executed serially instead of allowing each program to run for only a short period of time. By running large processes one at a time, the system makes more efficient use of the CPU as well as system memory, since each process does not end up constantly faulting in its working set, to only have the pages stolen when another process starts running. As long as there is enough memory in the system, processes marked by .CR serialize() behave no differently from other processes in the system. However, once memory becomes tight, processes marked by .CR serialize() are run one at a time with the highest priority processes being run first. Each process runs for a finite interval of time before another serialized process is allowed to run. .SH RETURN VALUE .CR serialize() returns zero upon successful completion, or nonzero if the system call failed. .SH ERRORS If .CR serialize() fails, it sets .CR errno (see .IR errno (2)) to the following value: .RS .TP 15 [ESRCH] The .IR pid passed in does not exist. .RE .SH WARNINGS The user has no way of forcing an execution order on serialized processes. .SH AUTHOR .CR serialize() was developed by HP. .SH SEE ALSO serialize(1). .\" .\" toc@\f3serialize(2)\f1:\0\0\f4serialize()\f1@@@force target process to run serially with other processes\f1 .\" .\" index@\f4serialize()\f1 \-force target process to run serially with other processes@@@\f3serialize(2)\f1 .\" index@\f1force target process to run serially with other processes@@@\f3serialize(2)\f1 .\" index@\f1process, force target to run serially with other processes@@@\f3serialize(2)\f1 .\" $Header: setacl.2,v 72.4 94/08/30 16:52:57 ssa Exp $ .TA s .TH setacl 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setacl, fsetacl \- set access control list (ACL) information .SH SYNOPSIS .C "#include " .PP .nf .C "int setacl(" .PD 0 .IP .C "const char *path," .C "size_t nentries," .C "const struct acl_entry *acl" .PP .C ");" .PD .PP .C "int fsetacl(" .PD 0 .IP .C "int fildes," .C "size_t nentries," .C "const struct acl_entry *acl" .PP .C ");" .PD .fi .SH DESCRIPTION .C setacl() sets an existing file's access control list (ACL) or deletes optional entries from it. .I path points to a path name of a file. .PP Similarly, .C fsetacl() sets an existing file's access control list for an open file known by the file descriptor .IR fildes . .PP The effective user ID of the process must match the owner of the file or be the super-user to set a file's ACL. .PP A successful call to .C setacl() deletes all of a file's previous optional ACL entries (see explanation below), if any. .I nentries indicates how many valid entries are defined in the .I acl parameter. If .I nentries is zero or greater, the new ACL is applied to the file. If any of the file's base entries (see below) is not mentioned in the new ACL, it is retained but its access mode is set to zero (no access). Hence, routine calls of .C setacl() completely define the file's ACL. .PP As a special case, if .I nentries is negative (that is, a value of .C ACL_DELOPT (defined in .CR ), the .I acl parameter is ignored, all of the file's optional entries, if any, are deleted, and its base entries are left unaltered. .PP Some of the miscellaneous mode bits in the file's mode might be turned off as a consequence of calling .CR setacl() . See .IR chmod (2). .SS "Access Control Lists" An ACL consists of a series of entries. Entries can be categorized in four levels of specificity: .RS .TP 15 .RC ( \f2u\fP.\f2g\fP, " \f2mode\fP)" applies to user .I u in group .I g .PD 0 .TP .RC ( \f2u\fP.%, " \f2mode\fP)" applies to user .I u in any group .TP .RC ( %.\f2g\fP, " \f2mode\fP)" applies to any user in group .I g .TP .RC ( %.%, " \f2mode\fP)" applies to any user in any group .PD .RE .PP Entries in the ACL must be unique; no two entries can have the same user ID .RI ( uid ) and group ID .RI ( gid ) (see below). Entries can appear in any order. The system orders them as needed for access checking. .PP The .CR header file defines .C ACL_NSUSER as the non-specific .I uid value and .C ACL_NSGROUP as the non-specific .I gid value represented by .C % above. If .I uid in an entry is .CR ACL_NSUSER , it is a .CI %. g entry. If .I gid in an entry is .CR ACL_NSGROUP , it is a .IC u .% entry. If both .I uid and .I gid are non-specific, the file's entry is .CR %.% . .PP The .CR header file defines meanings of mode bits in ACL entries (\c .CR R_OK , .CR W_OK , and .CR X_OK ). Irrelevant bits in mode values must be zero. .PP Every file's ACL has three base entries which cannot be added or deleted, but only modified. The base ACL entries are mapped directly from the file's permission bits. .nf .IP ( . ACL_NSGROUP, ) (ACL_NSUSER . , ) (ACL_NSUSER . ACL_NSGROUP, ) .fi .PP In addition, up to 13 optional ACL entries can be set to restrict or grant access to a file. .PP Altering a base ACL entry's modes with .C setacl() changes the file's corresponding permission bits. The permission bits can be altered also by using .C chmod() (see .IR chmod (2)) and read using .C stat() (see .IR stat (2)). .PP The number of entries allowed per file (see .C NACLENTRIES in .CR ) is small for space and performance reasons. User groups should be created as needed for access control purposes. Since ordinary users cannot create groups, their ability to control file access with ACLs might be somewhat limited. .SH RETURN VALUE Upon successful completion, .C setacl() and .C fsetacl() return a value of zero. If an error occurs, they return \(mi1, the file's ACL is not modified, and .C errno is set to indicate the error. .SH ERRORS .C setacl() and .C fsetacl() fail if any of the following conditions are encountered: .RS .TP 20 [ENOTDIR] A component of the .I path prefix is not a directory. .TP [ENOENT] The named file does not exist (for example, .I path is null or a component of .I path does not exist). .TP [EBADF] .I fildes is not a valid file descriptor. .TP [EACCES] A component of the .I path prefix denies search permission. .TP [EPERM] The effective user ID does not match the owner of the file and the effective user ID is not super-user. .TP [EROFS] The named file resides on a read-only file system. .TP [EFAULT] .I path or .I acl points outside the allocated address space of the process, or .I acl is not as large as indicated by .IR nentries . .TP [EINVAL] There is a redundant entry in the ACL, or .I acl contains an invalid .IR uid , .IR gid , or .I mode value. .TP [E2BIG] An attempt was made to set an ACL with more than .C NACLENTRIES entries. .TP [EOPNOTSUPP] ACLs are only supported on HFS file systems. Additionally, .CR setacl() is not supported on remote files by some networking services. .TP [ENOSPC] Not enough space on the file system. .TP [ENFILE] System file table is full. .TP [ENAMETOOLONG] The length of .I path exceeds .C PATH_MAX bytes, or the length of a component of .I path exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP [ELOOP] Too many symbolic links were encountered in translating the .I path name. .TP [EDQUOT] User's disk quota block or inode limit has been reached for this file system. .RE .SH EXAMPLES The following code fragment defines and sets an ACL on file .C ../shared which allows the file's owner to read, write, and execute or search the file, and allows user 103, group 204 to read the file. .nf .IP .C #include .C #include .C #include .IP .ifn .ft 3 .ift .ft 4 .ps +1 char *filename = "../shared"; .ft .ps .C struct acl_entry acl [2]; .C struct stat statbuf; .IP .C if (stat (filename, & statbuf) < 0) .C " error (...);" .IP .C "acl [0] . uid = statbuf . st_uid; /* file owner */" .C "acl [0] . gid = ACL_NSGROUP;" .C "acl [0] . mode = R_OK | W_OK | X_OK;" .IP .C "acl [1] . uid = 103;" .C "acl [1] . gid = 204;" .C "acl [1] . mode = R_OK;" .IP .C "if (setacl (filename, 2, acl))" .C " error (...);\f1" .fi .PP The following call deletes all optional ACL entries from .CR file1 : .IP .ifn .ft 3 .ift .ft 4 .ps +1 setacl ("file1", ACL_DELOPT, (struct acl_entry *) 0); .ft .ps .SH DEPENDENCIES .SS NFS .C setacl() and .C fsetacl() are not supported on remote files. .SS HFS ACLs are only supported on HFS file systems. .SH AUTHOR .C setacl() and .C fsetacl() were developed by HP. .SH SEE ALSO access(2), chmod(2), getaccess(2), getacl(2), stat(2), acl(5), unistd(5). .\" .\" index@\f4setacl()\f1, \f4fsetacl()\f1 \- set access control list (ACL) information@@@\f3setacl(2)\f1 .\" index@\f4fsetacl()\f1 \- set access control list (ACL) information@@@\f3setacl(2)\f1 .\" index@\f1set access control list (ACL) information@@@\f3setacl(2)\f1 .\" index@\f1access control list (ACL) information, set@@@\f3setacl(2)\f1 .\" .\" toc@\f3setacl(2)\f1:\0\0\f4setacl()\f1, \f4fsetacl()\f1@@@set access control list (ACL) information .\" toc@\f4fsetacl()\f1\0\0set access control list (ACL) information@@@\f1see \f3setacl(2)\f1 .\" .\" links@setacl.2 fsetacl.2 .\" .\" fileset_database@setacl.2 PROGRAMING-MAN .\" $Header: setaudid.2,v 78.2 96/01/19 20:28:37 ssa Exp $ .TA s .TH setaudid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setaudid \- set the audit \s-1ID\s0 (aid) for the current process .SH SYNOPSIS .C "#include " .PP .C "int setaudid(aid_t audid);" .SH DESCRIPTION .C setaudid() sets the audit .SM ID .RI ( aid ) for the current process. This call is restricted to the super-user. .SH RETURN VALUE Upon successful completion, .C setaudid() returns a value of 0; otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C setaudid() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EPERM] The caller is not a superuser. .TP .SM [EINVAL] The audit ID (audid) is invalid. .RE .SH AUTHOR .C setaudid() was developed by HP. .SH SEE ALSO getaudid(2). .\" index@\f4setaudid()\fP \(mi set audit \s-1ID\s+1 (\f4aid()\fP) for current process@@@\f3setaudid(2)\f1 .\" index@set audit \s-1ID\s+1 (\f4aid()\fP) for current process@@@\f3setaudid(2)\f1 .\" index@audit \s-1ID\s+1 (\f4aid()\fP), set for current process@@@\f3setaudid(2)\f1 .\" index@current process, set audit \s-1ID\s+1 (\f4aid()\fP) for@@@\f3setaudid(2)\f1 .\" index@process, set audit \s-1ID\s+1 (\f4aid()\fP) for current@@@\f3setaudid(2)\f1 .\" toc@\f3setaudid(2)\f1:\0\0\f4setaudid()\fP@@@set audit \s-1ID\s+1 (\f4aid()\fP) for current process .\" .\" $Header: setaudproc.2,v 72.3 93/01/14 14:41:20 ssa Exp $ .TA s .TH setaudproc 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setaudproc \- controls process level auditing for the current process and its decendents .SH SYNOPSIS .C "#include " .PP .C "int setaudproc(int aflag);" .SH DESCRIPTION .C setaudproc() controls process level auditing for the current process and its decendents. It accomplishes this by setting or clearing the .C u_audproc flag in the .C u area of the calling process. When this flag is set, the system audits the process; when it is cleared, the process is not audited. This call is restricted to super-users. .PP One of the following .I aflags must be used: .RS .TP 15 .C AUD_PROC Audit the calling process and its decendents. .PD 0 .TP .C AUD_CLEAR Do not audit the calling process and its decendents. .RE .PD .PP The .C u_audproc flag is inherited by the descendents of a process. consequently, the effect of a call to .C setaudproc() is not limited to the current process, but propagates to all its decendents as well. For example, if .C setaudproc() is called with the .C AUD_PROC flag, all subsequent audited system calls in the current process .I and its decendents are audited until .C setaudproc() is called with the .C AUD_CLEAR flag. .PP Further, .C setaudproc() performs its action regardless of whether the user executing the process has been selected to be audited or not. For example, if .C setaudproc() is called with the .C AUD_PROC (or the .CR AUD_CLEAR ) flag, all subsequent audited system calls will be audited (or not audited), regardless of whether the user executing the process has been selected for auditing or not. .PP Due to these features, .C setaudproc() should not be used in most self-auditing applications. .CR audswitch() should be used (see .IR audswitch (2)) when the objective is to suspend auditing within a process without affecting its decendents or overriding the user selection aspect of the auditing system. .SH RETURN VALUE Upon successful completion, .C setaudproc() returns 0; otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH AUTHOR .C setaudproc() was developed by HP. .SH SEE ALSO getaudproc(2), audswitch(2), audusr(1M), audevent(1M), audit(5). .\" .\" index@\f4setaudproc()\fP \(mi set or clear auditing on calling process@@@\f3setaudproc(2)\f1 .\" index@set or clear auditing on calling process@@@\f3setaudproc(2)\f1 .\" index@clear or set auditing on calling process@@@\f3setaudproc(2)\f1 .\" index@audit: set or clear auditing on calling process@@@\f3setaudproc(2)\f1 .\" index@auditing, set or clear on calling process@@@\f3setaudproc(2)\f1 .\" index@process, calling, set or clear auditing on@@@\f3setaudproc(2)\f1 .\" index@calling process, set or clear auditing on@@@\f3setaudproc(2)\f1 .\" .\" toc@\f3setaudproc(2)\f1:\0\0\f4setaudproc()\fP@@@set or clear auditing on calling process .\" .\" fileset_database@setaudproc.2 PROGRAMING-MAN .\" $Header: getcontext.2,v 76.1 95/07/07 14:35:46 ssa Exp $ .TA g .TH getcontext 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getcontext, setcontext \- get and set current user context .SH SYNOPSIS .\" UX .PP .C "#include " .PP .C "int getcontext(ucontext_t *ucp);" .PP .C "int setcontext(const ucontext_t *ucp);" .\" ? .SH DESCRIPTION The .CR getcontext() function initialises the structure pointed to by .IR ucp to the current user context of the calling process. The .IR ucontext_t type that .IR ucpa points to defines the user context and includes the contents of the calling process' machine registers, the signal mask, and the current execution stack. .PP The .CR setcontext() function restores the user context pointed to by .IR ucp . A successful call to .CR setcontext() does not return; program execution resumes at the point specified by the .IR ucp argument passed to .CR setcontext() . The .IR ucp argument should be created either by a prior call to .CR getcontext() , or by being passed as an argument to a signal handler. If the .IR ucp argument was created with .CR getcontext() , program execution continues as if the corresponding call of .CR getcontext() had just returned. If the .IR ucp argument was created with .CR makecontext() , program execution continues with the function passed to .CR makecontext() . When that function returns, the process continues as if after a call to .CR setcontext() with the .IR ucp argument that was input to .CR makecontext() . If the .IR ucp argument was passed to a signal handler, program execution continues with the program instruction following the instruction interrupted by the signal. If the .IR uc_link member of the .CR ucontext_t structure pointed to by the .IR ucp argument is equal to 0, then this context is the main context, and the process will exit when this context returns. The effects of passing a .IR ucp argument obtained from any other source are unspecified. .PP .SH RETURN VALUE On successful completion, .CR setcontext() does not return and .CR getcontext() returns 0. Otherwise, a value of \(mi1 is returned. .SH ERRORS No errors are defined. .SH APPLICATION USAGE When a signal handler is executed, the current user context is saved and a new context is created. If the process leaves the signal handler via .CR longjmp() , then it is unspecified whether the context at the time of the corresponding .CR setjmp() call is restored and thus whether future calls to .CR getcontext() will provide an accurate representation of the current context, since the context restored by .CR longjmp() may not contain all the information that .CR setcontext() requires. Signal handlers should use .CR siglongjmp() or .CR setcontext() instead. .PP Portable applications should not modify or access the .IR uc_mcontext member of .IR ucontext_t . A portable application cannot assume that context includes any process\-wide static data, possibly including .CR errno . Users manipulating contexts should take care to handle these explicitly when required. .SH SEE ALSO bsd_signal(), makecontext(), setjmp(), sigaction(), sigaltstack(), sigprocmask(), sigsetjmp(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4getcontext()\f1 \- get and set current user context@@@\f3getcontext(2)\f1 .\" index@\f4setcontext()\f1 \- get and set current user context@@@\f3getcontext(2)\f1 .\" index@\f1get and set current user context@@@\f3getcontext(2)\f1 .\" index@\f1set and get current user context@@@\f3getcontext(2)\f1 .\" index@\f1current user context, get and set@@@\f3getcontext(2)\f1 .\" index@\f1user context, get and set current@@@\f3getcontext(2)\f1 .\" .\" toc@\f3getcontext(2)\f1:\0\0\f4getcontext()\f1, \f4setcontext()\f1@@@get and set current user context .\" toc@\f4setcontext()\f1:\0\0get and set current user context@@@see \f3getcontext(2)\f1 .\" .\" links@getcontext.2 setcontext.2 .\" $Header: getdomainna.2,v 72.5 94/07/05 17:44:12 ssa Exp $ .TA g .TH getdomainname 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getdomainname, setdomainname \- get/set name of current Network Information Service domain .SH SYNOPSIS .C "int getdomainname(char *name, int namelen);" .PP .C "int setdomainname(char *name, int namelen);" .SH DESCRIPTION .C getdomainname() returns the name of the Network Information Service (NIS) domain for the current processor, as previously set by .CR setdomainname() . The parameter .I namelen specifies the size of the .I name array. The returned value is null-terminated unless the area pointed to by .I name is not large enough to hold the domain name plus the null byte. In this case, only the .I namelen number of bytes is returned. .PP .C setdomainname() sets the domain of the host machine to .IR name , which has a length of .IR namelen . This call is restricted to the superuser and is normally used only when the system is booted. .PP These Network Information Service domains enable two distinct networks with common host names to merge. Each network is distinguished by having a different domain name. Currently, only the Network Information Service uses these domains. .SH RETURN VALUE If the call succeeds, a value of 0 is returned. If the call fails, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS If .C getdomainname() or .C setdomainname() fail, .CR errno is set to one of the following values: .RS .TP 15 .SM [EFAULT] .I name points outside the accessible address space. .TP 15 .SM [EPERM] The caller is not superuser. This error only applies to .CR setdomainname() . .RE .SH WARNINGS The length of the .I name array should be at least 65; NIS domain names can be up to 64 characters long. .PP NIS servers use the NIS domain name as the name of a subdirectory of .CR /var/yp . Since the NIS domain name can be as long as 64 characters, the domain name set with .C setdomainname() can exceed the maximum file name length allowed on the local file system. If that length is exceeded, the name of the subdirectory is the truncated NIS domain name. .SH AUTHOR .I getdomainname was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), ypserv(1M), ypfiles(4). .\" .\" index@\f4getdomainname()\f1 \- get name of current NIS domain@@@\f3getdomainname(2)\f1 .\" index@\f1get name of current NIS domain@@@\f3getdomainname(2)\f1 .\" index@\f1set name of current NIS domain@@@\f3getdomainname(2)\f1 .\" index@\f1NIS domain, get or set name of current@@@\f3getdomainname(2)\f1 .\" index@\f1domain, get or set name of current NIS@@@\f3getdomainname(2)\f1 .\" index@\f1name of current NIS domain, get or set@@@\f3getdomainname(2)\f1 .\" index@\f4setdomainname()\f1 \- set name of current NIS domain@@@\f3getdomainname(2)\f1 .\" .\" toc@\f3getdomainname(2)\f1:\0\0\f4getdomainname()\f1, \f4setdomainname()\f1@@@get/set name of current NIS domain .\" .\" links@getdomainna.2 setdomainna.2 .\" $Header: setevent.2,v 72.3 93/01/14 14:36:13 ssa Exp $ .TA s .TH setevent 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setevent \- set current events and system calls which are to be audited .SH SYNOPSIS .C "#include " .PP .C "int setevent(" .nf .PD 0 .IP .C "const struct aud_type a_syscall[]," .C "const struct aud_event_tbl a_event[]" .PP .C ");" .PD .SH DESCRIPTION .C setevent() sets the events and system calls to be audited. The event and system call settings in the tables pointed to by .I a_syscall and .I a_event become the current settings. This call is restricted to the super-user. .SH RETURN VALUE Upon successful completion, .C setevent() returns 0; otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C setevent() fails if the following condition is encountered: .TP 15 .SM [EPERM] The caller is not super-user. .SH AUTHOR .C setevent() was developed by HP. .SH SEE ALSO getevent(2), audevent(1M). .\" index@\f4setevent()\fP \(mi set current events and system calls to be audited@@@\f3setevent(2)\f1 .\" index@audit: set current events and system calls to be audited@@@\f3setevent(2)\f1 .\" index@current events and system calls to be audited@@@\f3setevent(2)\f1 .\" index@events and system calls to be audited@@@\f3setevent(2)\f1 .\" index@system calls and events to be audited@@@\f3setevent(2)\f1 .\" toc@\f3setevent(2)\f1:\0\0\f4setevent()\fP@@@set current events and system calls to be audited .\" .\" fileset_database@setevent.2 PROGRAMING-MAN .\" $Header: setuid.2,v 72.5 94/11/14 15:26:19 ssa Exp $ .TA s .TH setuid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setuid, setgid \- set user and group IDs .SH SYNOPSIS .C "#include " .PP .C "int setuid(uid_t uid);" .PP .C "int setgid(gid_t gid);" .SH DESCRIPTION .C setuid() sets the real-user-\c .SM ID .RI ( ruid ), effective-user-\c .SM ID .RI ( euid ), and/or saved-user-\c .SM ID .RI ( suid ) of the calling process. The super-user's .I euid is zero. The following conditions govern .IR setuid 's behavior: .RS .TP 3 \(bu If the .I euid is zero, .C setuid() sets the .IR ruid , .IR euid , and .I suid to .IR uid . .TP \(bu If the .I euid is not zero, but the argument .I uid is equal to the .I ruid or the .IR suid , .C setuid() sets the .I euid to .IR uid ; the .I ruid and .I suid remain unchanged. (If a set-user-\c .SM ID program is not running as super-user, it can change its .I euid to match its .I ruid and reset itself to the previous .I euid value.) .TP \(bu If .I euid is not zero, but the argument .I uid is equal to the .IR euid , and the calling process is a member of a group that has the .C PRIV_SETRUGID privilege (see .IR privgrp (4)), .C setuid() sets the .I ruid to .IR uid ; the .I euid and .I suid remain unchanged. .RE .PP .C setgid() sets the real-group-\c .SM ID .RI ( rgid ), effective-group-\c .SM ID .RI ( egid ), and/or saved-group-\c .SM ID .RI ( sgid ) of the calling process. The following conditions govern .CR setgid() 's behavior: .RS .TP 3 \(bu If .I euid is zero, .C setgid() sets the .I rgid and .I egid to .IR gid . .TP \(bu If .I euid is not zero, but the argument .I gid is equal to the .I rgid or the .IR sgid , .C setgid() sets the .I egid to .IR gid ; the .I rgid and .I sgid remain unchanged. .TP \(bu If .I euid is not zero, but the argument .I gid is equal to the .IR egid , and the calling process is a member of a group that has the .C PRIV_SETRUGID privilege (see .IR privgrp (4)), .C setgid() sets the .I rgid to .IR gid ; the .I egid and .I sgid remain unchanged. .RE .SH RETURN VALUE Upon successful completion, .C setuid() and .C setgid() returned 0; otherwise, they return \(mi1 and set .C errno to indicate the error. .SH ERRORS .C setuid() and .C setgid() fail and return \(mi1 if any of the following conditions are encountered: .RS .TP 15 .SM [EPERM] None of the conditions above are met. .TP .SM [EINVAL] .I uid .RI ( gid ) is not a valid user (group) .SM ID. .RE .SH WARNINGS It is recommended that the .C PRIV_SETRUGID capability be avoided, as it is provided for backward compatibility. This feature may be modified or dropped from future .SM HP-UX releases. When changing the real user .SM ID and real group .SM ID, use of .C setresuid() and .C setresgid() (see .IR setresuid (2)) are recommended instead. .SH AUTHOR .C setuid() was developed by AT&T, the University of California, Berkeley, and HP. .PP .C setgid() was developed by AT&T. .SH SEE ALSO exec(2), getprivgrp(2), getuid(2), setresuid(2) privgrp(4). .SH STANDARDS CONFORMANCE .CR setuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4setuid()\fP \(mi set user \s-1ID\s+1@@@\f3setuid(2)\f1 .\" index@\f4setgid()\fP \(mi set group \s-1ID\s+1@@@\f3setuid(2)\f1 .\" index@set user or group \s-1ID\s+1@@@\f3setuid(2)\f1 .\" index@\s-1ID\s+1, set user or group@@@\f3setuid(2)\f1 .\" index@user \s-1ID\s+1, set@@@\f3setuid(2)\f1 .\" index@group \s-1ID\s+1: set group \s-1ID\s+1@@@\f3setuid(2)\f1 .\" .\" toc@\f3setuid(2)\f1:\0\0\f4setuid()\fP, \f4setgid()\fP@@@set user and group \s-1ID\s+1s .\" toc@\f4setgid()\fP:\0\0set group \s-1ID\s+1@@@see \f3setuid(2)\f1 .\" .\" links@setuid.2 setgid.2 .\" $Header: setgroups.2,v 72.4 94/11/14 15:26:08 ssa Exp $ .TA s .TH setgroups 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setgroups \- set group access list .SH SYNOPSIS .C "#include " .PP .C "int setgroups(int ngroups, const gid_t *gidset);" .SH DESCRIPTION .C setgroups() sets the group access list of the current user process according to the array .IR gidset . The parameter .I ngroups indicates the number of entries in the array and must be no more than .CR NGROUPS , as defined in .RC < sys/param.h >. .PP Only super-user can set new groups by adding to the group access list of the current user process; any user can delete groups from it. .SH RETURN VALUE Upon successful completion, .C setgroups() returns 0; otherwise it returns \(mi1 and sets .C errno to indicate the error. .SH "ERRORS .C setgroups() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EPERM] The caller is not super-user and has attempted to set new groups. .TP .SM [EFAULT] The address specified for .I gidset is outside the process address space. The reliable detection of this error is implementation dependent. .TP .SM [EINVAL] .I ngroups is greater than .SM NGROUPS or not positive. .TP .SM [EINVAL] An entry in .I gidset is not a valid group .SM ID. .RE .SH AUTHOR .C setgroups() was developed by the University of California, Berkeley. .SH SEE ALSO getgroups(2), initgroups(3C) .SH STANDARDS CONFORMANCE .CR setgroups() ": AES, SVID3" .\" .\" index@\f4setgroups()\fP \(mi set group access list@@@\f3setgroups(2)\f1 .\" index@set group access list@@@\f3setgroups(2)\f1 .\" index@group access list: set group access list@@@\f3setgroups(2)\f1 .\" index@access list, set group@@@\f3setgroups(2)\f1 .\" index@list, set group access@@@\f3setgroups(2)\f1 .\" .\" toc@\f3setgroups(2)\f1:\0\0\f4setgroups()\fP@@@set group access list .\" .\" fileset_database@setgroups.2 PROGRAMING-MAN .\" $Header: sethostname.2,v 72.7 94/11/02 11:53:22 ssa Exp $ .TA s .TH sethostname 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sethostname \- set name of host cpu .SH SYNOPSIS .C "#include " .PP .C "int sethostname(const char *name, size_t namelen);" .SH DESCRIPTION The .CR sethostname() system call sets the name of the host processor to .IR name , which has a length of .I namelen characters. At system boot time .CR sethostname() is normally executed by the .CR hostname command (see .IR hostname (1)) in the .CR /sbin/init.d/hostname script. Host names are limited to .CR MAXHOSTNAMELEN characters, as defined in .CR . .SH RETURN VALUE .CR sethostname() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR sethostname() fails, .CR errno is set to one of the following values. .RS .TP 15 [EFAULT] .I name points to an illegal address. The reliable detection of this error is implementation dependent. .TP [EPERM] The user does not have appropriate privileges. .RE .SH AUTHOR .CR sethostname() was developed by the University of California, Berkeley. .SH SEE ALSO hostname(1), uname(1), gethostname(2), uname(2). .\" .\" index@\f4sethostname()\f1 \- set name of host cpu@@@\f3sethostname(2)\f1 .\" index@cpu, set name of host@@@\f3sethostname(2)\f1 .\" index@host cpu, set name of@@@\f3sethostname(2)\f1 .\" index@name: set the name of host cpu@@@\f3sethostname(2)\f1 .\" index@set name of host cpu@@@\f3sethostname(2)\f1 .\" .\" toc@\f3sethostname(2)\f1:\0\0\f4sethostname()\f1@@@set name of host cpu .\" $Header: getitimer.2,v 76.1 95/07/07 14:40:29 ssa Exp $ .TA g .TH getitimer 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getitimer, setitimer \- get/set value of interval timer .SH SYNOPSIS .C "#include " .PP .C "int getitimer(int which, struct itimerval *value);" .PP .C "int setitimer(" .PD 0 .nf .IP .C "int which," .C "const struct itimerval *value," .C "struct itimerval *ovalue .PP .C ");" .PD .SH DESCRIPTION The .CR getitimer() function stores the current value of the timer specified by which into the structure pointed to by value. The .CR setitimer() function sets the timer specified by .IR which to the value specified in the structure pointed to by value, and if .IR ovalue is not a null pointer, stores the previous value of the timer in the structure pointed to by .IR ovalue. .PP A timer value is defined by the .IR itimerval structure. If .IR it_value is non-zero, it indicates the time to the next timer expiration. If .IR it_interval is non- zero, it specifies a value to be used in reloading .IR it_value when the timer expires. Setting .IR it_value to 0 disables a timer, regardless of the value of .IR it_interval . Setting .IR it_interval to 0 disables a timer after its next expiration (assuming .IR it_value is non-zero). .PP Implementations may place limitations on the granularity of timer values. For each interval timer, if the requested timer value requires a finer granularity than the implementation supports, the actual timer value will be rounded up to the next supported value. .PP An XSI-conforming implementation provides each process with at least three interval timers, which are indicated by the .IR which argument: .RS .TP 25 .C ITIMER_REAL Decrements in real time. A .CR SIGALRM signal is delivered when this timer expires. .TP .C ITIMER_VIRTUAL Decrements in process virtual time. It runs only when the process is executing. A .CR SIGVTALRM signal is delivered when it expires. .TP .C ITIMER_PROF Decrements both in process virtual time and when the system is running on behalf of the process. It is designed to be used by interpreters in statistically profiling the execution of interpreted programs. .RE .PP The interaction between .CR setitimer() and any of .CR alarm() , .CR sleep() or .CR usleep() is unspecified. .SH RETURN VALUE Upon successful completion, .CR getitimer() or .CR setitimer() returns 0. Otherwise, -1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR setitimer() function will fail if: .RS .TP 15 [EINVAL] The value argument is not in canonical form.(In canonical form, the number of microseconds is a non-negative integer less than 1,000,000 and the number of seconds is a non-negative integer.) .RE .PP The .CR getitimer() and .CR setitimer() functions may fail if: .RS .TP 15 [EINVAL] The which argument is not recognised. .SH SEE ALSO alarm() , sleep() , ualarm() , usleep() , , . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" $Header: getitimer.2,v 76.1 95/07/07 14:40:29 ssa Exp $ .TA g .TH getitimer 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH DESCRIPTION A timer value is defined by the .I itimerval structure: .nf .IP .C struct itimerval { .C " struct timeval it_interval; /* timer interval */" .C " struct timeval it_value; /* current value */" .C }; .fi .PP Time values smaller than the resolution of the system clock are rounded up to this resolution. The machine-dependent clock resolution is .RC 1\|/\| HZ seconds, where the constant .C HZ is defined in .RC < sys/param.h >. Time values larger than an implementation-specific maximum value are rounded down to this maximum. The maximum values for the three interval timers are specified by the constants .CR MAX_ALARM , .CR MAX_VTALARM , and .C MAX_PROF defined in .RC < sys/param.h >. On all implementations, these values are guaranteed to be at least 31 days (in seconds). .PP Each time the .CR ITIMER_PROF timer expires, the .CR SIGPROF signal is delivered. Since this signal can interrupt in-progress system calls, programs using this timer must be prepared to restart interrupted system calls. .PP Interval timers are not inherited by a child process across a .CR fork() , but are inherited across an .CR exec() . .PP Three macros for manipulating time values are defined in .RC < time.h >: .RS .TP 18 .C timerclear Set a time value to zero. .TP .C timerisset Test if a time value is non-zero. .TP .C timercmp Compare two time values. (Beware that .C >= and .C <= do not work with the .C timercmp macro.) .RE .PP The timer used with .C ITIMER_REAL is also used by .C alarm() (see .IR alarm (2)). Thus successive calls to .CR alarm() , .CR getitimer() , and .C setitimer() set and return the state of a single timer. In addition, a call to .C alarm() sets the timer interval to zero. .SH ERRORS .C getitimer() or .C setitimer() fail if any of the following conditions are encountered: .RS .TP 15 .SM [EFAULT] The .I value structure specified a bad address. Reliable detection of this error is implementation dependent. .TP .SM [EINVAL] A .I value structure specified a microsecond value less that zero or greater than or equal to one million. .TP .SM [EINVAL] .I which does not specify one of the three possible timers. .RE .SH EXAMPLES The following call to .C setitimer() sets the real-time interval timer to expire initially after 10 seconds and every 0.5 seconds thereafter: .nf .IP .C struct itimerval rttimer; .C struct itimerval old_rttimer; .IP .C "rttimer.it_value.tv_sec = 10;" .C "rttimer.it_value.tv_usec = 0;" .C "rttimer.it_interval.tv_sec = 0;" .C "rttimer.it_interval.tv_usec = 500000;" .IP .C "setitimer (ITIMER_REAL, &rttimer, &old_rttimer);" .fi .SH AUTHOR .C getitimer() was developed by the University of California, Berkeley. .SH SEE ALSO alarm(2) , exec(2) , gettimeofday(2) , signal(5). .\" .\" index@\f4getitimer()\f1 \- get value of process interval timer@@@\f3getitimer(2)\f1 .\" index@\f4setitimer()\f1 \- set value of process interval timer@@@\f3getitimer(2)\f1 .\" index@set value of process interval timer@@@\f3getitimer(2)\f1 .\" index@get: value of process interval timer@@@\f3getitimer(2)\f1 .\" index@value of process interval timer, set or get@@@\f3getitimer(2)\f1 .\" index@process interval timer, set or get value of@@@\f3getitimer(2)\f1 .\" index@interval timer, set or get value of process@@@\f3getitimer(2)\f1 .\" index@timer, set or get value of process interval@@@\f3getitimer(2)\f1 .\" .\" toc@\f3getitimer(2)\f1:\0\0\f4getitimer()\fP, \f4setitimer()\fP@@@get/set value of interval timer .\" toc@\f4setitimer()\f1:\0\0set value of interval timer@@@see \f3getitimer(2)\f1 .\" .\" links@getitimer.2 setitimer.2 .\" .\" fileset_database@getitimer.2 PROGRAMING-MAN .\" $Header: setpgid.2,v 72.5 94/11/14 15:26:10 ssa Exp $ .TA s .TH setpgid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setpgid(), setpgrp2() \- set process group ID for job control .SH SYNOPSIS .C "#include " .PP .C "int setpgid(pid_t pid, pid_t pgid);" .PP .C "int setpgrp2(pid_t pid, pid_t pgid);" .SH DESCRIPTION The .CR setpgid() and .CR setpgrp2() system calls cause the process specified by .I pid to join an existing process group or create a new process group within the session of the calling process. The process group ID of the process whose process ID is .I pid is set to .IR pgid . If .I pid is zero, the process ID of the calling process is used. If .I pgid is zero, the process ID of the indicated process is used. The process group ID of a session leader does not change. .PP .CR setpgrp2() is provided for backward compatibility only. .SH RETURN VALUE .CR setpgid() and .CR setpgrp2() return the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR setpgid() or .CR setpgrp2() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] The value of .I pid matches the process ID of a child process of the calling process and the child process has successfully executed one of the .IR exec (2) functions. .TP [EINVAL] The value of .I pgid is less than zero or is outside the range of valid process group ID values. .TP [EPERM] The process indicated by .I pid is a session leader. .TP [EPERM] The value of .I pid is valid but matches the process ID of a child process of the calling process, and the child process is not in the same session as the calling process. .TP [EPERM] The value of .I pgid does not match the process ID of the process indicated by .I pid and there is no process with a process group ID that matches the value of .I pgid in the same session as the calling process. .TP [ESRCH] The value of .I pid does not match the process ID of the calling process or of a child process of the calling process. .RE .SH AUTHOR .CR setpgid() and .CR setpgrp2() were developed by HP and the University of California, Berkeley. .SH SEE ALSO bsdproc(2), exec(2), exit(2), fork(2), getpid(2), kill(2), setsid(2), signal(2), termio(7). .SH STANDARDS CONFORMANCE .CR setpgid() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4setpgid()\f1 \- set process group ID for job control@@@\f3setpgid(2)\f1 .\" index@\f4setpgrp2()\f1 \- set process group ID for job control@@@\f3setpgid(2)\f1 .\" index@ID for job control, set process group@@@\f3setpgid(2)\f1 .\" index@group ID for job control, set process@@@\f3setpgid(2)\f1 .\" index@job control, set process group ID for@@@\f3setpgid(2)\f1 .\" index@process group ID for job control, set@@@\f3setpgid(2)\f1 .\" index@set process group ID for job control@@@\f3setpgid(2)\f1 .\" .\" links@setpgid.2 setpgrp2.2 .\" .\" toc@\f3setpgid(2)\f1:\0\0\f4setpgid()\f1, \f4setpgrp2()\f1@@@set process group ID for job control .\" toc@\f4setpgrp2()\f1:\0\0set process group ID@@@see \f3setpgid(2)\f1 .\" $Header: setpgrp.2,v 76.2 95/07/07 14:50:49 ssa Exp $ .TA s .TH setpgrp 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" Note: this manpage was covered in setsid.2 in MLP - nchuang .SH NAME setpgrp \- set process group ID .SH SYNOPSIS .\" UX .PP .C #include .PP .C pid_t setpgrp(void); .\"? .SH DESCRIPTION If the calling process is not already a session leader, .CR setpgrp() sets the process group ID of the calling process to the process ID of the calling process. If .CR setpgrp() creates a new session, then the new session has no controlling terminal. .PP The .CR setpgrp() function has no effect when the calling process is a session leader. .SH RETURN VALUE Upon successful completion, .CR setpgrp() returns the new process group ID. .SH ERRORS No errors are defined. .SH SEE ALSO exec, fork(), getpid(), getsid(), kill(), setsid(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4setpgrp()\f1 \- set process group ID@@@\f3setpgrp(2)\f1 .\" index@\f1set process group ID@@@\f3setpgrp(2)\f1 .\" index@\f1process group ID, set@@@\f3setpgrp(2)\f1 .\" index@\f1group ID, set process group ID@@@\f3setpgrp(2)\f1 .\" index@\f1ID, set process group ID@@@\f3setpgrp(2)\f1 .\" .\" toc@\f3setpgrp(2)\f1:\0\0\f4setpgrp()\f1@@@set process group ID .\" .\" fileset_database@setpgrp.2 .\" $Header: setpgid.2,v 72.5 94/11/14 15:26:10 ssa Exp $ .TA s .TH setpgid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setpgid(), setpgrp2() \- set process group ID for job control .SH SYNOPSIS .C "#include " .PP .C "int setpgid(pid_t pid, pid_t pgid);" .PP .C "int setpgrp2(pid_t pid, pid_t pgid);" .SH DESCRIPTION The .CR setpgid() and .CR setpgrp2() system calls cause the process specified by .I pid to join an existing process group or create a new process group within the session of the calling process. The process group ID of the process whose process ID is .I pid is set to .IR pgid . If .I pid is zero, the process ID of the calling process is used. If .I pgid is zero, the process ID of the indicated process is used. The process group ID of a session leader does not change. .PP .CR setpgrp2() is provided for backward compatibility only. .SH RETURN VALUE .CR setpgid() and .CR setpgrp2() return the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR setpgid() or .CR setpgrp2() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] The value of .I pid matches the process ID of a child process of the calling process and the child process has successfully executed one of the .IR exec (2) functions. .TP [EINVAL] The value of .I pgid is less than zero or is outside the range of valid process group ID values. .TP [EPERM] The process indicated by .I pid is a session leader. .TP [EPERM] The value of .I pid is valid but matches the process ID of a child process of the calling process, and the child process is not in the same session as the calling process. .TP [EPERM] The value of .I pgid does not match the process ID of the process indicated by .I pid and there is no process with a process group ID that matches the value of .I pgid in the same session as the calling process. .TP [ESRCH] The value of .I pid does not match the process ID of the calling process or of a child process of the calling process. .RE .SH AUTHOR .CR setpgid() and .CR setpgrp2() were developed by HP and the University of California, Berkeley. .SH SEE ALSO bsdproc(2), exec(2), exit(2), fork(2), getpid(2), kill(2), setsid(2), signal(2), termio(7). .SH STANDARDS CONFORMANCE .CR setpgid() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4setpgid()\f1 \- set process group ID for job control@@@\f3setpgid(2)\f1 .\" index@\f4setpgrp2()\f1 \- set process group ID for job control@@@\f3setpgid(2)\f1 .\" index@ID for job control, set process group@@@\f3setpgid(2)\f1 .\" index@group ID for job control, set process@@@\f3setpgid(2)\f1 .\" index@job control, set process group ID for@@@\f3setpgid(2)\f1 .\" index@process group ID for job control, set@@@\f3setpgid(2)\f1 .\" index@set process group ID for job control@@@\f3setpgid(2)\f1 .\" .\" links@setpgid.2 setpgrp2.2 .\" .\" toc@\f3setpgid(2)\f1:\0\0\f4setpgid()\f1, \f4setpgrp2()\f1@@@set process group ID for job control .\" toc@\f4setpgrp2()\f1:\0\0set process group ID@@@see \f3setpgid(2)\f1 .\" $Header: getpriority.2,v 78.1 96/01/19 20:12:55 ssa Exp $ .TA g .TH getpriority 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpriority, setpriority \- get or set process priority .SH SYNOPSIS .CR "#include " .PP .CR "int getpriority(int which, int who);" .PP .CR "int setpriority(int which, int who, int priority);" .SH DESCRIPTION .CR getpriority() returns the priority of the indicated processes. .PP .CR setpriority() sets the priority of the indicated processes to .IR priority . .PP The processes are indicated by .IR which and .IR who , where .IR which can have one of the following values: .RS .TP 20 .CR PRIO_PROCESS Get or set the priority of the specified process where .IR who is the process ID. A .IR who of .CR 0 implies the process ID of the calling process. .TP .CR PRIO_PGRP Get or set the priority of the specified process group where .IR who is the process-group ID, indicating all processes belonging to that process-group. A .IR who of .CR 0 implies the process-group ID of the calling process. .TP .CR PRIO_USER Get or set the priority of the specified user where .IR who is the user ID, indicating all processes owned by that user. A .IR who of .CR 0 implies the user ID of the calling process. .RE .PP If more than one process is indicated, the value returned by .CR getpriority() is the lowest valued priority of all the indicated processes, and .CR setpriority() sets the priority of all indicated processes. .PP .IR priority is a value from .CR -20 to .CR 20 , where lower values indicate better priorities. The default priority for a process is 0. Negative priorities require appropriate privileges. .SH RETURN VALUE .CR getpriority() returns the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .IR n is an integer priority in the range .CR -20 to .CR 20 . .TP .CR -1 Failure. .CR errno is set to indicate the error. See WARNINGS below. .PD .RE .PP .CR setpriority() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR getpriority() or .CR setpriority() fails, .CR errno is set to one of the following values: .RS .TP 15 [EACCES] The calling process does not have access rights to change one or more of the indicated processes. All processes for which access is allowed are still affected. .TP [EINVAL] .IR which is not one of the choices listed above, or .IR who is out of range. .TP [EPERM] The calling process attempted to change the priority of a process to a smaller priority value without having appropriate privileges. .TP [ESRCH] Processes indicated by .IR which and .IR who cannot be found. .RE .SH WARNINGS .CR getpriority() can return .CR -1 both when it successfully finds a priority of .CR -1 and when it fails. To determine whether a failure occurred, set .CR errno to .CR 0 before calling .CR getpriority() , then examine .CR errno after the call returns. .SH AUTHOR .CR getpriority() and .CR setpriority() were developed by the University of California, Berkeley. .SH SEE ALSO nice(1), renice(1), nice(2). .\" .\" index@\f4getpriority()\f1 \- get process priority@@@\f3getpriority(2)\f1 .\" index@\f4setpriority()\f1 \- set process priority@@@\f3getpriority(2)\f1 .\" index@get process priority@@@\f3getpriority(2)\f1 .\" index@set process priority@@@\f3getpriority(2)\f1 .\" index@process priority, get or set@@@\f3getpriority(2)\f1 .\" index@priority, get or set process@@@\f3getpriority(2)\f1 .\" .\" toc@\f3getpriority(2)\f1:\0\0\f4getpriority()\f1, \f4setpriority()\f1@@@get or set process priority .\" toc@\f4setpriority()\f1:\0\0set process priority@@@see \f3getpriority(2)\f1 .\" .\" links@getpriority.2 setpriority.2 .\" $Header: getprivgrp.2,v 78.1 96/01/19 20:13:52 ssa Exp $ .TA g .TH getprivgrp 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprivgrp(), setprivgrp() \- get and set special attributes for group .SH SYNOPSIS .C "#include " .PP .C "int getprivgrp(struct privgrp_map *grplist);" .PP .C "int setprivgrp(gid_t grpid, const int *mask);" .SH DESCRIPTION .SS getprivgrp() The .CR getprivgrp() system call returns a table of the privileged group assignments into a user-supplied structure. .IR grplist points to an array of structures of type .CR privgrp_map , associating a group ID with a privilege mask. Privilege masks are formed by ORing together elements from the access types specified in .CR . The array may have gaps in it, distinguished as having a .CR priv_groupno field value of .CR PRIV_NONE . The group number .CR PRIV_GLOBAL gives the global privilege mask. Only information about groups which are in the user's group access list, or about the user's real or effective group ID, is returned to an ordinary user. The complete set is returned to a privileged user. .SS setprivgrp() The .CR setprivgrp() system call associates a kernel capability with a group ID. This allows subletting of superuser-like privileges to members of a particular group or groups. .CR setprivgrp() takes two arguments: .IR grpid , the integer group ID, and .IR mask , a mask of permissions. The mask is created by treating the access types defined in .CR as bit numbers (using 1 for the least significant bit). Thus, privilege number 5 would be represented by the bits .CR 1<<(5-1) or 16. More generally, privilege .IR p is represented by: .IP .CI "mask[((" p "-1) / BITS_PER_INT)] & (1 << ((" p "-1) % BITS_PER_INT))" .PP where .CR BITS_PER_INT is .CR 8*sizeof(mask[0]) given 8 bits per byte. As it is possible to have more than .IR "word-size" distinct privileges, mask is a pointer to an integer array of size .CR PRIV_MASKSIZ . .PP .CR setprivgrp() privileges include those specified in the file .CR . A process can access the system call protected by a specific privileged group if it belongs to or has an effective group ID of a group having access to the system call. All processes are considered to belong to the pseudo-group .CR PRIV_GLOBAL . .PP Specifying a .IR grpid of .CR PRIV_NONE causes privileges to be revoked on all privileged groups that have any of the privileges specified in .IR mask . Specifying a .IR grpid of .CR PRIV_GLOBAL causes privileges to be granted to all processes. .PP The constant .CR PRIV_MAXGRPS in .CR defines the system limit on the number of groups that can be assigned privileges. One of these is always the psuedo-group .CR PRIV_GLOBAL , allowing for .CR "PRIV_MAXGRPS - 1" actual groups. .PP Only processes with appropriate privileges can use .CR setprivgrp() . .SH RETURN VALUE .CR getprivgrp() and .CR setprivgrp() return the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .SH ERRORS If .CR getprivgrp() fails, .CR errno is set to one of the following values. .RS .TP 15 [EFAULT] .IR grplist points to an illegal address. The reliable detection of this error is implementation dependent. .RE If .CR setprivgrp() fails, .CR errno is set to one of the following values. .RS .TP 15 [E2BIG] The request would require assigning privileges to more than .CR PRIV_MAXGRPS groups. .TP [EFAULT] .IR mask points to an illegal address. The reliable detection of this error is implementation dependent. .TP [EINVAL] .IR mask has bits set for one or more unknown privileges. .TP [EINVAL] .IR grpid is out of range. .TP [EPERM] The caller is not a privileged user. .SH EXAMPLES The following example prints out .CR PRIV_GLOBAL and the group IDs of the privilege groups to which the user belongs: .nf .IP .C "#include .IP .C "struct privgrp_map pgrplist[PRIV_MAXGRPS]; .C "int i; .C "gid_t pgid; .IP .C "getprivgrp (pgrplist); .C "for (i=0; i" .PP .C "int setresuid(uid_t ruid, uid_t euid, uid_t suid);" .PP .C "int setresgid(gid_t rgid, gid_t egid, gid_t sgid);" .SH DESCRIPTION .C setresuid() sets the real, effective and/or saved user ID of the calling process. .PP If the current real, effective or saved user ID is equal to that of a user having appropriate privileges, .C setresuid() sets the real, effective and saved user IDs to .IR ruid , .IR euid , and .IR suid , respectively. Otherwise, .C setresuid() only sets the real, effective, and saved user IDs if .IR ruid , .IR euid , and .IR suid each match at least one of the current real, effective, or saved user IDs. .PP If .IR ruid , .IR euid , or .I suid is .CR -1 , .C setresuid() leaves the current real, effective or saved user ID unchanged. .PP .C setresgid() sets the real, effective and/or saved group ID of the calling process. .PP If the current real, effective or saved user ID is equal to that of a user having appropriate privileges, .C setresgid() sets the real, effective, and saved group ID to .IR rgid , .IR egid , and .IR sgid , respectively. Otherwise, .C setresgid() only sets the real, effective and saved group ID if .IR rgid , .IR egid , and .I sgid each match at least one of the current real, effective or saved group ID. .PP If .IR rgid , .IR egid , or .I sgid is .CR -1 , .C setresgid() leaves the current real, effective or saved group ID unchanged. .SH RETURN VALUE Upon successful completion, .C setresuid() and .C setresgid() return 0; otherwise, they return \(mi1 and set .C errno to indicate the error. .SH ERRORS .C setresuid() and .C setresgid() fail if any of the following conditions are encountered: .RS .TP 15 [EINVAL] .IR ruid , .IR euid , or .I suid .RI ( rgid , .IR egid , or .IR sgid ) is not a valid user (group) ID. .TP [EPERM] None of the conditions above are met. .SH AUTHOR .C setresuid() and .C setresgid() were developed by HP. .SH SEE ALSO exec(2), getuid(2), setuid(2). .\" index@\f4setresuid()\f1 \- set real, effective, and/or saved user IDs@@@\f3setresuid(2)\f1 .\" index@\f4setresgid()\f1 \- set real, effective, and/or saved group IDs@@@\f3setresuid(2)\f1 .\" index@\f1set real, effective, and/or saved user or group IDs@@@\f3setresuid(2)\f1 .\" index@\f1real, effective, and/or saved user or group IDs, set@@@\f3setresuid(2)\f1 .\" index@\f1effective, real, and/or saved user or group IDs, set@@@\f3setresuid(2)\f1 .\" index@\f1saved, real, and/or effective user or group IDs, set@@@\f3setresuid(2)\f1 .\" index@\f1user or group IDs, set real, effective, and/or saved@@@\f3setresuid(2)\f1 .\" index@\f1group ID: set real, effective, and/or saved group or user IDs@@@\f3setresuid(2)\f1 .\" .\" toc@\f3setresuid(2)\f1:\0\0\f4setresuid()\f1, \f4setresgid()\f1@@@set real, effective, and saved user and group IDs .\" toc@\f4setresgid()\f1:\0\0set real, effective, and saved group IDs@@@\f1see \f3setresuid(2)\f1 .\" .\" links@setresuid.2 setresgid.2 .\" .\" fileset_database@setresuid.2 PROGRAMING-MAN .\" $Header: setresuid.2,v 72.4 94/08/30 16:54:41 ssa Exp $ .TA s .TH setresuid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setresuid, setresgid \- set real, effective, and saved user and group IDs .SH SYNOPSIS .C "#include " .PP .C "int setresuid(uid_t ruid, uid_t euid, uid_t suid);" .PP .C "int setresgid(gid_t rgid, gid_t egid, gid_t sgid);" .SH DESCRIPTION .C setresuid() sets the real, effective and/or saved user ID of the calling process. .PP If the current real, effective or saved user ID is equal to that of a user having appropriate privileges, .C setresuid() sets the real, effective and saved user IDs to .IR ruid , .IR euid , and .IR suid , respectively. Otherwise, .C setresuid() only sets the real, effective, and saved user IDs if .IR ruid , .IR euid , and .IR suid each match at least one of the current real, effective, or saved user IDs. .PP If .IR ruid , .IR euid , or .I suid is .CR -1 , .C setresuid() leaves the current real, effective or saved user ID unchanged. .PP .C setresgid() sets the real, effective and/or saved group ID of the calling process. .PP If the current real, effective or saved user ID is equal to that of a user having appropriate privileges, .C setresgid() sets the real, effective, and saved group ID to .IR rgid , .IR egid , and .IR sgid , respectively. Otherwise, .C setresgid() only sets the real, effective and saved group ID if .IR rgid , .IR egid , and .I sgid each match at least one of the current real, effective or saved group ID. .PP If .IR rgid , .IR egid , or .I sgid is .CR -1 , .C setresgid() leaves the current real, effective or saved group ID unchanged. .SH RETURN VALUE Upon successful completion, .C setresuid() and .C setresgid() return 0; otherwise, they return \(mi1 and set .C errno to indicate the error. .SH ERRORS .C setresuid() and .C setresgid() fail if any of the following conditions are encountered: .RS .TP 15 [EINVAL] .IR ruid , .IR euid , or .I suid .RI ( rgid , .IR egid , or .IR sgid ) is not a valid user (group) ID. .TP [EPERM] None of the conditions above are met. .SH AUTHOR .C setresuid() and .C setresgid() were developed by HP. .SH SEE ALSO exec(2), getuid(2), setuid(2). .\" index@\f4setresuid()\f1 \- set real, effective, and/or saved user IDs@@@\f3setresuid(2)\f1 .\" index@\f4setresgid()\f1 \- set real, effective, and/or saved group IDs@@@\f3setresuid(2)\f1 .\" index@\f1set real, effective, and/or saved user or group IDs@@@\f3setresuid(2)\f1 .\" index@\f1real, effective, and/or saved user or group IDs, set@@@\f3setresuid(2)\f1 .\" index@\f1effective, real, and/or saved user or group IDs, set@@@\f3setresuid(2)\f1 .\" index@\f1saved, real, and/or effective user or group IDs, set@@@\f3setresuid(2)\f1 .\" index@\f1user or group IDs, set real, effective, and/or saved@@@\f3setresuid(2)\f1 .\" index@\f1group ID: set real, effective, and/or saved group or user IDs@@@\f3setresuid(2)\f1 .\" .\" toc@\f3setresuid(2)\f1:\0\0\f4setresuid()\f1, \f4setresgid()\f1@@@set real, effective, and saved user and group IDs .\" toc@\f4setresgid()\f1:\0\0set real, effective, and saved group IDs@@@\f1see \f3setresuid(2)\f1 .\" .\" links@setresuid.2 setresgid.2 .\" .\" fileset_database@setresuid.2 PROGRAMING-MAN .\" $Header: setreuid.2,v 76.2 95/07/07 14:51:47 ssa Exp $ .TA s .TH setreuid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setreuid \- set real and effective user IDs .SH SYNOPSIS .\" UX .PP .C#include .PP .C int setreuid(uid_t ruid, uid_t euid); .\"? .SH DESCRIPTION The .CR setreuid() function sets the real and effective user IDs of the current process to the values specified by the .IR ruid and .IR euid arguments. If .IR ruid or .IR euid is \(mi1, the corresponding effective or real user ID of the current process is left unchanged. .PP A process with appropriate privileges can set either ID to any value. An unprivileged process can only set the effective user ID if the .IR euid argument is equal to either the real, effective, or saved user ID of the process. .PP It is unspecified whether a process without appropriate privileges is permitted to change the real user ID to match the current real, effective or saved user ID of the process. .SH RETURN VALUE Upon successful completion, 0 is returned. Otherwise, \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR setreuid() function will fail if: .RS .TP 25 [EINVAL] The value of the .IR ruid or .IR euid argument is invalid or out-of-range. .TP [EPERM] The current process does not have appropriate privileges, and either an attempt was made to change the effective user ID to a value other than the real user ID or the saved set-user-ID or an attempt was made to change the real user ID to a value not permitted by the implementation. .SH SEE ALSO getuid(), setuid(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4seetreuid()\f1 \- set real and effective user IDs@@@\f3setreuid(2)\f1 .\" index@\f1set real and effective user IDs@@@\f3setreuid(2)\f1 .\" index@\f1real and effective user IDs, set@@@\f3setreuid(2)\f1 .\" index@\f1effective and real user IDs, set@@@\f3setreuid(2)\f1 .\" index@\f1user IDs, set real and effective user IDs@@@\f3setreuid(2)\f1 .\" index@\f1IDs, set real and effective user IDs@@@\f3setreuid(2)\f1 .\" .\" toc@\f3setreuid(2)\f1:\0\0\f4setreuid()\f1@@@set real and effective user IDs .\" .\" fileset_database@setreuid.2 .\" $Header: getrlimit.2,v 78.1 96/02/12 13:49:39 ssa Exp $ .TA g .TH getrlimit 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getrlimit(), setrlimit() \- control maximum resource consumption .SH SYNOPSIS .C #include .PP .C "int getrlimit(int resource, struct rlimit *rlp);" .PP .C "int setrlimit(int resource, const struct rlimit *rlp);" .SH DESCRIPTION Limits on the consumption of a variety of resources by the calling process may be obtained with .CR getrlimit() and set with .CR setrlimit(). .PP Each call to either .CR getrlimit() or .CR setrlimit() identifies a specific resource to be operated upon as well as a resource limit. A resource limit is represented by an .CR rlimit structure. The .CR rlim_cur member specifies the current or soft limit and the .CR rlim_max member specifies the maximum or hard limit. Soft limits may be changed by a process to any value that is less than or equal to the hard limit. A process may (irreversibly) lower its hard limit to any value that is greater than or equal to the soft limit. Only a process with appropriate privileges can raise a hard limit. Both hard and soft limits can be changed in a single call to .CR setrlimit() subject to the constraints described above. .PP The value .CR RLIM_INFINITY , defined in .CR , is considered to be larger than any other limit value. If a call to .CR getrlimit() returns .CR RLIM_INFINITY for a resource, it means the implementation does not enforce limits on that resource. Specifying .CR RLIM_INFINITY as any resource limit value on a successful call to .CR setrlimit() inhibits enforcement of that resource limit. .PP The following resources are defined: .RS .TP 25 .C RLIMIT_CORE This is the maximum size of a core file in bytes that may be created by a process. A limit of 0 will prevent the creation of a core file. If this limit is exceeded, the writing of a core file will terminate at this size. .TP .C RLIMIT_CPU This is the maximum amount of CPU time in seconds used by a process. If this limit is exceeded, .CR SIGXCPU is generated for the process. If the process is blocking, catching or ignoring .CR SIGXCPU , the behaviour is unspecified. .TP .C RLIMIT_DATA This is the maximum size of a process' data segment in bytes. If this limit is exceeded, the .CR brk() , .CR malloc() , and .CR sbrk() functions will fail with .CR errno set to ENOMEM. .TP .C RLIMIT_FSIZE This is the maximum size of a file in bytes that may be created by a process. A limit of 0 will prevent the creation of a file. If a write or truncate operation would cause this limit to be exceeded, .CR SIGXFSZ is generated for the process. If the process is blocking, catching or ignoring .CR SIGXFSZ, continued attempts to increase the size of a file from end-of-file to beyond the limit will fail with .CR errno set to EFBIG. .TP .C RLIMIT_NOFILE This is a number one greater than the maximum value that the system may assign to a newly-created descriptor. If this limit is exceeded, functions that allocate new file descriptors may fail with .CR errno set to EMFILE. This limit constrains the number of file descriptors that a process may allocate. .TP .C RLIMIT_STACK This is the maximum size of a process' stack in bytes. The implementation will not automatically grow the stack beyond this limit. If this limit is exceeded, .CR SIGSEGV is generated for the process. If the process is blocking or ignoring .CR SIGSEGV , or is catching .CR SIGSEGV and has not made arrangements to use an alternate stack, the disposition of .CR SIGSEGV will be set to .CR SIG_DFL before it is generated. .TP .C RLIMIT_AS This is the maximum size of a process' total available memory, in bytes. If this limit is exceeded, the .CR brk() , .CR malloc() , .CR mmap() , and .CR sbrk() functions will fail with .CR errno set to ENOMEM. In addition, the automatic stack growth will fail with the effects outlined above. .RE .SH RETURN VALUE Upon successful completion, .CR getrlimit() and .CR setrlimit() return 0. Otherwise, these functions return -1 and set .CR errno to indicate the error. .SH ERRORS The .CR getrlimit() and .CR setrlimit() functions will fail if: .RS .TP 15 [EINVAL] An invalid resource was specified; or in a .CR setrlimit() call, the new .IR rlim_cur exceeds the new .IR rlim_max . .TP [EPERM] The limit specified to .CR setrlimit() would have raised the maximum limit value, and the calling process does not have appropriate privileges. .RE .PP The .CR setrlimit() function may fail if: .RS .TP 15 [EINVAL] The limit specified cannot be lowered because current usage is already higher than the limit. .RE .SH SEE ALSO brk(), exec, fork(), getdtablesize(), malloc(), open(), sigaltstack(), sysconf(), ulimit(), , . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" $Header: getrlimit.2,v 78.1 96/02/12 13:49:39 ssa Exp $ .TA g .TH getrlimit 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH DESCRIPTION The .I resource parameter selects the system resource limits to be set or retrieved. The possible values for .I resource are defined in .CR . Currently, only the following values are supported: .RS .TP 25 .C RLIMIT_NOFILE The maximum number of files a process can have open. The soft limit for this resource is the same as the value returned by .CR sysconf(_SC_OPEN_MAX) . .TP .C RLIMIT_OPEN_MAX Defined to be the same as .CR RLIMIT_NOFILE . .RE .PP The .I rlp argument points to an object of type struct .CR rlimit , which is defined in .CR , and includes the following members: .nf .IP .C "int rlim_cur Current (soft) limit" .C "int rlim_max Hard limit" .fi .PP For .CR getrlimit() , the system stores the two limits on the specified resource in the structure to which .I rlp points. .PP For .CR setrlimit() , the system reads new values for the two limits on the specified resource from the structure to which .I rlp points. .SH ERRORS If the .CR getrlimit() or .CR setlimit() system call fails, .CR errno (see .I errno (2)) is set to one of the following values: .RS .TP 15 [EFAULT] The address specified for .I rlp is invalid. Reliable detection of this error is implementation dependent. .RE .PP If .CR setrlimit() fails it may set .CR errno (see .IR errno (2)) to one of the following values: .RS .TP 15 [EINVAL] The .I rlp argument specified a hard or soft limit higher than the current hard limit value, and the caller does not have the appropriate privileges. .TP 15 [EINVAL] A user with appropriate privileges has attempted to raise .IR rlp \(mi> rlim_cur or .IR rlp \(mi> rlim_max to a value greater than the system is capable of supporting. .TP [EINVAL] The value of .IR rlp \(mi> rlim_cur is less than the number of file descriptors the process already has allocated. .TP [EINVAL] The value of .IR rlp \(mi> rlim_max is less than the current soft limit. .RE .ifn .ne 8 .SH WARNINGS The maximum size of a file returned by .CR getrlimit() is in terms of bytes. The maximum size of a file returned by .CR ulimit (see .IR ulimit (2)) with .CR UL_GETFSIZE is in terms of blocks of size 512 bytes. The value returned by .CR ulimit with .CR UL_GETFSIZE may thus have to be rounded down to a multiple of 512. .SH AUTHOR .CR getrlimit() and .CR setrlimit() were developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO getrlimit64(2), setrlimit64(2), sysconf(2), ulimit(2). .\" .\" index@\f4getrlimit()\f1 \- get system resource consumption limit@@@\f3getrlimit(2)\f1 .\" index@\f4setrlimit()\f1 \- set system resource consumption limit@@@\f3getrlimit(2)\f1 .\" index@\f1set system resource consumption limit@@@\f3getrlimit(2)\f1 .\" index@\f1get system resource consumption limit@@@\f3getrlimit(2)\f1 .\" index@\f1control system resource consumption limit@@@\f3getrlimit(2)\f1 .\" index@\f1system resource consumption limit, get or set@@@\f3getrlimit(2)\f1 .\" index@\f1resource consumption limit, get or set system@@@\f3getrlimit(2)\f1 .\" index@\f1consumption limit, get or set system resource@@@\f3getrlimit(2)\f1 .\" index@\f1limit, get or set system resource consumption@@@\f3getrlimit(2)\f1 .\" .\" toc@\f3getrlimit(2)\f1:\0\0\f4getrlimit()\f1, \f4setrlimit()\f1@@@control consumption of system resources .\" toc@\f4setrlimit()\f1:\0\0control consumption of system resources@@@\f1see \f3getrlimit(2)\f1 .\" .\" links@getrlimit.2 setrlimit.2 .\" $Header: creat64.2,v 78.2 96/02/12 13:37:12 ssa Exp $ .TA c .TH creat64 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME creat64(\|), fstat64(\|), getrlimit64(\|), lockf64(\|), lseek64(\|), lstat64(\|), mmap64(\|), open64(\|), prealloc64(\|), setrlimit64(\|), stat64(\|), statvfs64(\|), truncate64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0creat64(const\0char\0*path,\0mode_t\0mode);" .PP .C "#include " .PP .C "int\0fstat64(int\0fildes,\0struct\0stat64\0*buf);" .PP .C "include\0" .PP .C "int\0getrlimit64(int resource,\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0lock64(int\0*fildes,\0int\0function,\0off64_t\0size);" .PP .C "#include " .PP .C "off64_t\0lseek64(int\0*fildes,\0off64_t\0offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0lstat64(const\0char\0*,\0struct\0stat64\0*);" .PP .C "#include " .PP .C "void\0mmap64(void\0addr,\0size_t\0len,\0int\0prot,\0int\0flags,\0int\0fildes,\0off64_t\0off);" .PP .C "#include " .PP .C "int\0open64(const\0char\0*path,\0int\0oflag,...);" .PP .C "#include " .PP .C "int\0prealloc64(int\0fildes,\0off64_t\0size);" .PP .C "include\0" .PP .C "int\0setrlimit64(int\0resource,\0const\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0stat64(const\0char\0*path,\0struct\0stat64\0*buf);" .PP .C "#include " .PP .C "int\0statvfs64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "int\0truncate64(const\0char\0*path,\0off64_t\0length);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 18 .C creat64() The .C creat64() function is identical to .C creat() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. .C creat64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR creat() . .TP .C fstat64() The .C fstat64() function is identical to .C fstat() except that .C fstat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C getrlimit64 The .C getrlimit64() function is identical to .C getrlimit() except that .C getrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .CR "struct rlimit" . All other functional behaviors, returns, and errors are identical. .TP .C lock64() The .C lock64() function is identical to .C lockf() except that .C lockf64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C lseek64() The .C lseek64() function is identical to .C lseek() except that .C lseek64() accepts an .CR off64_t type as the desired offset and has a return value of .CR off64_t. All other functional behaviors, returns, and errors are identical. .TP .C lstat64() The .C lstat64() function is identical to .C lstat() except that .C lstat64() returns file status in a .C struct stat64 instead of .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C mmap64() The .C mmap64() function is identical to .C mmap() except that .C mmap64() accepts the file offset as an .CR off64_t . .TP .C open64() The .C open64() function is identical to .C open() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. The .C open64() function is equivalent to .C open() function (in 32-bit compile environment) with .C O_LARGEFILE flag set. .C open64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR open() . .TP .C prealloc64() The .C prealloc64() function is identical to .C prealloc() except that .C prealloc64() accepts the file offset as an .CR off64_t . All other functional behaviors, returns, and errors are identical to .CR prealloc() . .TP .C setrlimit64 The .C setrlimit64() function is identical to .C setrlimit() except that .C setrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .C struct rlimit. All other functional behaviors, returns, and errors are identical. .TP .C stat64() The .C stat64() function is identical to .C stat() except that .C stat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . .TP .C statvfs64() Refer to .CR fstatvfs64() . .TP .C truncate64() The .C truncate64() function is identical to .C truncate() except that .C truncate64() accepts the length parameter as an .C off64_t instead of .CR off_t . All other functional behaviors, returns, and errors are identical to .CR truncate() . .\" .\" toc@\f4creat64(2)\f1:\0\0\f4fstat64\f1, \f4getrlimit64\f1, \f4lockf64\f1, \f4lseek64\f1, \f4lstat64\f1, \f4mmap64\f1, \f4open64\f1, \n\f4prealloc64\f1, \f4setrlimit64\f1, \f4stat64\f1, \f4statvfs64\f1, \f4truncate64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4creat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4fstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4getrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lockf64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lseek64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4mmap64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4open64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4prealloc64()\f1 \- file sysmmaptem API to support large files@@@\f3creat64(2)\f1 .\" index@\f4setrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4stat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4statvfs64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4truncate64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3creat64(2)\f1 .\" .\" links@creat64.2 fstat64.2 .\" links@creat64.2 getrlimit64.2 .\" links@creat64.2 lockf64.2 .\" links@creat64.2 lseek64.2 .\" links@creat64.2 lstat64.2 .\" links@creat64.2 mmap64.2 .\" links@creat64.2 open64.2 .\" links@creat64.2 prealloc64.2 .\" links@creat64.2 setrlimit64.2 .\" links@creat64.2 stat64.2 .\" links@creat64.2 statvfs64.2 .\" links@creat64.2 truncate64.2 .\" .\" $Header: setsid.2,v 72.6 94/11/14 15:26:11 ssa Exp $ .TA s .TH setsid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setsid, setpgrp, setpgrp3 \- create session and set process group ID .SH SYNOPSIS .C "#include " .PP .C "pid_t setsid(void);" .PP .C "pid_t setpgrp(void);" .PP .C "pid_t setpgrp3(void);" .SH DESCRIPTION If the calling process is not a process group leader, .CR setsid() or .CR setpgrp() creates a new session. The calling process becomes the session leader of this new session, it becomes the process group leader of a new process group, and it has no controlling terminal. The process group ID of the calling process is set equal to the process ID of the calling process. The calling process is the only process in the new process group, and the only process in the new session. .PP The .CR setpgrp() function is provided for backward compatibility only. .PP .CR setpgrp3() function is provided for HPUX compatibity in future releases. .CR setpgrp3() is functionally equivalent to setpgrp(). .SH RETURN VALUE Upon successful completion, .CR setsid() returns the value of the new process group ID of the calling process. Otherwise, it returns a value of .CR \(mi1 , and sets .CR errno to indicate the error. .PP The .CR setpgrp() function returns the value of the process group ID of the calling process. .SH ERRORS If .CR setsid() fails, no changes occur, and .CR errno (see .IR errno (2)) is set to one of the following values: .RS .TP 15 [EPERM] The calling process is already a process group leader. .TP [EPERM] The process group ID of a process other than the calling process matches the process ID of the calling process. .RE .SH WARNINGS The semantics for .CR setpgrp() may change in a future release (see setpgrp3()). .RE .SH AUTHOR .CR setpgrp() and .CR setsid() were developed by HP and AT&T. .SH SEE ALSO exec(2), exit(2), fork(2), getpid(2), kill(2), setpgid(2), signal(2), termio(7). .SH STANDARDS CONFORMANCE .CR setsid() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setpgrp() ": SVID2, SVID3, XPG2" .\" .\" index@\f4setsid()\f1 \- create session and set process group ID@@@\f3setsid(2)\f1 .\" index@\f4setpgrp()\f1 \- create session and set process group ID@@@\f3setsid(2)\f1 .\" index@\f4setpgrp3()\f1 \- create session and set process group ID@@@\f3setsid(2)\f1 .\" index@\f1create session and set process group ID@@@\f3setsid(2)\f1 .\" index@\f1session, create and set process group ID@@@\f3setsid(2)\f1 .\" index@\f1set process group ID, create session and@@@\f3setsid(2)\f1 .\" index@\f1process group ID, create session and set@@@\f3setsid(2)\f1 .\" index@\f1group ID, create session and set process@@@\f3setsid(2)\f1 .\" index@\f1ID, create session and set process group@@@\f3setsid(2)\f1 .\" .\" toc@\f3setsid(2)\f1:\0\0\f4setsid()\f1, \f4setpgrp()\f1, \f4setpgrp3()\f1@@@create session and set process group ID\f1 .\" toc@\f4setpgrp()\f1:\0\0create session and set process group ID@@@\f1see \f3setsid(2)\f1 .\" toc@\f4setpgrp3()\f1:\0\0create session and set process group ID@@@\f1see \f3setsid(2)\f1 .\" $Header: getsockopt.2,v 78.2 96/03/15 15:58:47 ssa Exp $ .TA g .TH getsockopt 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getsockopt(), setsockopt() \- get and set options on sockets .SH SYNOPSIS .nf .C "#include " .PP .C "int getsockopt(" .C " int s," .C " int level," .C " int optname," .C " void *optval," .C " int *optlen" .C ");" .PP .C "int setsockopt(" .C " int s," .C " int level," .C " int optname," .C " const void *optval," .C " int optlen" .C ");" .fi .SS "_XOPEN_SOURCE_EXTENDED only" .SH .nf .C "int getsockopt(" .C " int s," .C " int level," .C " int optname," .C " void *optval," .C " size_t *optlen" .C ");" .PP .C "int setsockopt(" .C " int s," .C " int level," .C " int optname," .C " const void *optval," .C " size_t optlen" .C ");" .fi .SH DESCRIPTION The .CR getsockopt() and .CR setsockopt() system calls manipulate options associated with a socket. The socket is identified by the socket descriptor .IR s . Options can exist at multiple protocol levels, and they are always present at the uppermost "socket" level (see .IR socket (2)) . .PP When manipulating socket options, the level at which the option resides .RI ( level ) and the name of the option .RI ( optname ) must be specified. To manipulate options at the "socket" level, .I level is specified as .CR SOL_SOCKET . To specify options at another level, .I level should be the protocol number specified in .RC < netinet/in.h > (for example, .CR IPPROTO_TCP ). .PP The parameters .I optval and .I optlen specify the value of the option. .I optval is the address of the data structure that contains the option value, and .I optlen is the length of the data structure. The type and value of the data structure that .I optval points to depends on the option. For "boolean" options, the value may be zero (not set) or non-zero (set). The value of other options depends on the purpose of the option. Usually, neither .I optval nor .I optlen may be the .SM NULL address or zero; see individual protocol manual entries for any exceptions, such as .IR tcp (7P) and .IR ip (7P). .PP For .CR setsockopt() , .I optval and .I optlen are used to pass information from the application to the system. .I optval is the address of a location in memory that contains the option information to be passed to the system. The parameter .I optlen is an integer value that specifies the size, in bytes, of the data structure pointed to by .IR optval . .PP For .CR getsockopt() , .I optval and .I optlen are used to pass information from the system to the application. The parameter .I optlen is the address of an .C int variable. Before calling .CR getsockopt() , the application should set the value of the variable to the maximum size, in bytes, of the data structure pointed to by .IR optval . Normally, upon return, the variable pointed to by .I optlen is set to the actual size the data returned in the structure pointed to by .IR optval, if .C getsockopt() returns without error. .PP The following ``socket'' level option names .RI ( optname ) are defined in .RC < sys/socket.h >. The type of the variable pointed to by .I optval is indicated in parentheses. Options for other protocol levels are described in the individual protocol manual pages, such as .IR tcp (7P) and .IR ip (7P). .RS .TP 25 .C SO_ACCEPTCONN .RC ( int ; boolean ) Returns a non-zero value if socket listening is enabled, otherwise returns a zero value. .TP .C SO_BROADCAST .RC ( int ; boolean; AF_INET SOCK_DGRAM sockets only) Allows the application to send messages to a broadcast address. .CR Default : disallowed. .TP .C SO_DEBUG .RC ( int ; boolean; AF_INET SOCK_STREAM sockets only) Enables or disables the recording of internal debug information. .CR Default : disabled. .TP .C SO_DONTROUTE .RC ( int ; boolean; AF_INET sockets only) Causes outbound messages to bypass normal routing facilities. Instead, messages are sent through the appropriate network interface based on the network portion of the destination address. .CR Default : disabled. .TP .C SO_ERROR .RC ( int ) Returns any pending error on the socket, and clears the error status. The value returned by .C SO_ERROR would be the value of .C errno after the next socket data transfer system call. .TP .C SO_KEEPALIVE .RC ( int ; boolean; AF_INET SOCK_STREAM sockets only) If enabled, keeps an otherwise idle TCP connection active. .CR Default : disabled. .TP .C SO_LINGER .RC ( "struct linger" ; AF_INET SOCK_STREAM sockets only) Controls whether or not an application "lingers" (waits) if there are untransmitted data in the send socket buffer when the socket is closed. The data type .C "struct linger" is defined in .RC < sys/socket.h >. .CR Default : disabled, as if .C l_onoff had been set to zero. (See details below.) .TP .C SO_OOBINLINE .RC ( int ; boolean; AF_INET SOCK_STREAM sockets only) If enabled, specifies that out-of-band data (TCP "urgent data") should be left "in-line" among the normal data stream. Otherwise, one byte of out-of-band data is pulled out of the data stream, and it is accessible only by setting .SM MSG_OOB in the .I flags parameter when the application reads the data (see .IR recv (2)). .CR Default : disabled. .TP .C SO_PMTU .RC ( int ; boolean; AF_INET sockets only) If enabled, specifies that Path MTU Discovery is to be used to determine the optimal datagram size for the route. .CR Default : enabled for .SM SOCK_STREAM sockets; disabled for .SM SOCK_DGRAM sockets. .TP .C SO_RCVBUF .RC ( int ) Specifies the maximum size, in bytes, of the receive socket buffer. For .SM SOCK_DGRAM sockets, the receive buffer size may limit the maximum size of messages that the socket can receive. .CR Default : protocol-dependent; see individual protocol manual entries, such as .IR tcp (7P) and .IR udp (7P). .TP .C SO_REUSEADDR .RC ( int ; boolean; AF_INET sockets only) If enabled, allows a local address to be reused in subsequent calls to .CR bind() . .CR Default : disallowed. .TP .C SO_SNDBUF .RC ( int ) Specifies the maximum size, in bytes, of the send socket buffer. For .SM SOCK_STREAM sockets, the send buffer size limits how much data can be queued for transmission before the application is blocked. For .SM SOCK_DGRAM sockets, the send buffer size may limit the maximum size of messages that the application can send through the socket. .CR Default : protocol-dependent; see individual protocol manual entries, such as .IR tcp (7P) and .IR udp (7P). .TP .C SO_TYPE .RC ( int ) Returns the socket type. .TP .C SO_USELOOPBACK .RC ( int ; boolean) Not used internally; provided only for compatibility. .RE .PP Setting the .C SO_BROADCAST option allows the application to send messages through the .SM SOCK_DGRAM socket to a broadcast destination address. .PP If .C SO_DONTROUTE is set, the system does not use the network routing tables when determining which interface to use to send an outbound message. Instead, the system sends the message through the interface whose network address matches the network portion of the destination address. If .C SO_DONTROUTE is not set (default), the system uses the network routing tables. .PP If .C SO_KEEPALIVE is disabled (default), a TCP connection may remain idle until the connection is released at the protocol layer. If .C SO_KEEPALIVE is enabled and the connection has been idle for two hours, TCP sends a packet to the remote TCP to acknowledge that the connection is still active. If the remote TCP does not respond within 75 seconds, TCP sends another packet. If TCP sends a total of 8 packets without receiving any response from the remote TCP (that is, after 10 minutes have passed), TCP drops the connection. In that case, the next attempt to read from the socket (for example, by calling .CR recv() ) returns an error, and .C errno is set to .SM ETIMEDOUT. .PP .C SO_LINGER controls the actions to be taken when there are untransmitted data in a .SM SOCK_STREAM send socket buffer when the socket is closed, either due to an explicit call to .C close() or because the application terminates normally or abnormally. The action is determined by the values of members of the .C struct linger data structure pointed to by .I optval in a call to .CR setsockopt() . The data type .C struct linger is defined in .RC < sys/socket.h >. If .C l_onoff is zero (the default action), .C close() returns immediately, but the system tries to transmit any unsent data and release the protocol connection gracefully. If .C l_onoff is non-zero and .C l_linger is zero, .C close() returns immediately, any unsent data is discarded, and the protocol connection is aborted. If both .C l_onoff and .C l_linger are non-zero, .C close() does not return until the system has tried to transmit all unsent data and release the connection gracefully. In that case, .C close() can return an error, and .C errno may be set to .SM ETIMEDOUT, if the system is unable to transmit the data after a protocol-defined time limit. Note that the value of .C l_linger is treated simply as a boolean; a non-zero value is .I not interpreted as a time limit( see .CR "_XOPEN_SOURCE_EXTENDED only" below). .C SO_LINGER does not affect the actions taken when the function .C shutdown() is called. .PP If .C SO_OOBINLINE is set, out-of-band data (TCP "urgent data") is left "in-line" among the normal data stream. In that case, the SIOCATMARK .C ioctl() request must be used to determine if the inbound data stream has been read up to the point where the out-of-band data begins. If multiple transmissions of out-of-band data are received before the application reads them, all of the data is left in-line; however, SIOCATMARK indicates the location of only the last transmission of out-of-band data. If .C SO_OOBINLINE is not set (default), only one byte of out-of-band is saved. This byte is pulled out of the normal data stream, and it is accessible only by setting .SM MSG_OOB in the .I flags parameter when the application reads the data (see .IR recv (2)). In that case, if multiple transmissions of out-of-band data are received before the application reads them, previous bytes of out-of-band data are lost. .PP If .C SO_PMTU is enabled for .SM SOCK_STREAM sockets (default), the Don't Fragment (DF) bit in IP datagrams is set for all TCP transmissions. If a datagram is dropped by a gateway because it is too big to be forwarded without fragmenting, the originating system will receive an ICMP "Datagram Too Big" message with the new PMTU information. TCP will automatically adjust to the new datagram size, and none of the TCP applications will be notified of the ICMP "Datagram Too Big" message. The dropped data will be retransmitted when the TCP retransmission timer expires. If .C SO_PMTU is disabled for .SM SOCK_STREAM sockets, the datagrams may be fragmented by intermediate gateways, which sometimes results in non-optimal network usage and lower throughput. .PP If .C SO_PMTU is enabled for .SM SOCK_DGRAM sockets, the application is notified of any ICMP "Datagram Too Big" messages received for the UDP port. The system notifies the corresponding UDP application by returning .C errno set to EAGAIN for the next call to .C send() or .CR recv() after the ICMP "Datagram Too Big" message is received. If the socket is using asynchronous I/O (see .SM FIOASYNC and .SM SIOCSPGRP in .IR socket (7)), the system also sends a SIGIO signal to the process or process group. As usual, the UDP application is responsible for handling the retransmission of any undelivered datagrams. If .C SO_PMTU is disabled for .SM SOCK_DGRAM sockets (default), UDP messages are automatically fragmented as needed. .PP Setting the .C SO_REUSEADDR option allows the local socket address to be reused in subsequent calls to .CR bind() . This permits multiple .SM SOCK_STREAM sockets to be bound to the same local address, as long as all existing sockets with the desired local address are in a connected state before .C bind() is called for a new socket. For .SM SOCK_DGRAM sockets, .C SO_REUSEADDR allows multiple sockets to receive UDP multicast datagrams addressed to the bound port number. For all .SM SOCK_DGRAM sockets bound to the same local address, .C SO_REUSEADDR must be set .I before calling .CR bind() . .PP .C SO_RCVBUF and .C SO_SNDBUF specify the maximum number of bytes that the system may allocate, as needed, for the receive and send buffers, respectively. These limits are merely approximate because of the way in which memory is allocated. For example, a large number of small transmissions may require more memory than the sum of the number of data bytes sent. The default receive and send buffer sizes are protocol-specific. For more information, see the appropriate manual entries, such as .IR tcp (7P) and .IR udp (7P). .PP For .SM SOCK_STREAM sockets, larger buffer sizes can improve performance. An application can increase the size of the receive buffer at any time; however, it can decrease the receive buffer size only prior to calling .C connect() or .CR listen() . An application can increase or decrease the send buffer at any time. .PP For .SM SOCK_DGRAM sockets, the size of the receive and send buffers limits the size of the maximum datagram that can be received and sent, respectively. These limits include socket buffer space that is also used to save the sender's socket address .RC ( "struct sockaddr" ) which is associated with each datagram transmission. The sender's socket address can be returned in the .I from parameter when .C recvfrom() is called (see .IR recv (2)). .RE .SS AF_CCITT .CR SO_SNDBUF and .CR SO_RCVBUF are the only options supported for sockets of the AF_CCITT address family. .SH _XOPEN_SOURCE_EXTENDED only The value of .C l_linger in the .I linger structure is interpreted as a time limit in seconds. .SH RETURN VALUE .CR getsockopt() and .CR setsockopt() return the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR getsockopt() or .CR setsockopt() fails, .CR errno is set to one of the following values: .TP 20 [EBADF] The argument .I s is not a valid descriptor. .TP [EFAULT] The .I optval or .I optlen address is not valid. .TP [EINVAL] The .I level or .I optlen value is not valid; or .I optval is the .SM NULL address; or the protocol connection has been released. .TP [ENOBUFS] Insufficient memory is available for internal system data structures. .TP [ENOPROTOOPT] The option is not recognized at the specified option level. .TP [ENOTSOCK] The argument .I s is not a socket descriptor. .TP [EOPNOTSUPP] The option is not supported by the socket family or socket type. .SH AUTHOR .CR getsockopt() and .CR setsockopt() were developed by the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO socket(2), getprotoent(3N), af_ccitt(7F), tcp(7P), udp(7P), unix(7P), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR getsockopt() ": XPG4" .\" .\" index@\f4getsockopt()\f1 \- get options on sockets@@@\f3getsockopt(2)\f1 .\" index@\f4setsockopt()\f1 \- set options on sockets@@@\f3getsockopt(2)\f1 .\" index@\f1options on sockets, get or set@@@\f3getsockopt(2)\f1 .\" index@\f1sockets, get or set options@@@\f3getsockopt(2)\f1 .\" .\" toc@\f3getsockopt(2)\f1:\0\0\f4getsockopt()\f1, \f4setsockopt()\f1@@@get or set options on sockets .\" toc@\f4setsockopt()\f1: set options on sockets@@@see \f3getsockopt(2)\f1 .\" .\" links@getsockopt.2 setsockopt.2 .\" $Header: setuid.2,v 72.5 94/11/14 15:26:19 ssa Exp $ .TA s .TH setuid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setuid, setgid \- set user and group IDs .SH SYNOPSIS .C "#include " .PP .C "int setuid(uid_t uid);" .PP .C "int setgid(gid_t gid);" .SH DESCRIPTION .C setuid() sets the real-user-\c .SM ID .RI ( ruid ), effective-user-\c .SM ID .RI ( euid ), and/or saved-user-\c .SM ID .RI ( suid ) of the calling process. The super-user's .I euid is zero. The following conditions govern .IR setuid 's behavior: .RS .TP 3 \(bu If the .I euid is zero, .C setuid() sets the .IR ruid , .IR euid , and .I suid to .IR uid . .TP \(bu If the .I euid is not zero, but the argument .I uid is equal to the .I ruid or the .IR suid , .C setuid() sets the .I euid to .IR uid ; the .I ruid and .I suid remain unchanged. (If a set-user-\c .SM ID program is not running as super-user, it can change its .I euid to match its .I ruid and reset itself to the previous .I euid value.) .TP \(bu If .I euid is not zero, but the argument .I uid is equal to the .IR euid , and the calling process is a member of a group that has the .C PRIV_SETRUGID privilege (see .IR privgrp (4)), .C setuid() sets the .I ruid to .IR uid ; the .I euid and .I suid remain unchanged. .RE .PP .C setgid() sets the real-group-\c .SM ID .RI ( rgid ), effective-group-\c .SM ID .RI ( egid ), and/or saved-group-\c .SM ID .RI ( sgid ) of the calling process. The following conditions govern .CR setgid() 's behavior: .RS .TP 3 \(bu If .I euid is zero, .C setgid() sets the .I rgid and .I egid to .IR gid . .TP \(bu If .I euid is not zero, but the argument .I gid is equal to the .I rgid or the .IR sgid , .C setgid() sets the .I egid to .IR gid ; the .I rgid and .I sgid remain unchanged. .TP \(bu If .I euid is not zero, but the argument .I gid is equal to the .IR egid , and the calling process is a member of a group that has the .C PRIV_SETRUGID privilege (see .IR privgrp (4)), .C setgid() sets the .I rgid to .IR gid ; the .I egid and .I sgid remain unchanged. .RE .SH RETURN VALUE Upon successful completion, .C setuid() and .C setgid() returned 0; otherwise, they return \(mi1 and set .C errno to indicate the error. .SH ERRORS .C setuid() and .C setgid() fail and return \(mi1 if any of the following conditions are encountered: .RS .TP 15 .SM [EPERM] None of the conditions above are met. .TP .SM [EINVAL] .I uid .RI ( gid ) is not a valid user (group) .SM ID. .RE .SH WARNINGS It is recommended that the .C PRIV_SETRUGID capability be avoided, as it is provided for backward compatibility. This feature may be modified or dropped from future .SM HP-UX releases. When changing the real user .SM ID and real group .SM ID, use of .C setresuid() and .C setresgid() (see .IR setresuid (2)) are recommended instead. .SH AUTHOR .C setuid() was developed by AT&T, the University of California, Berkeley, and HP. .PP .C setgid() was developed by AT&T. .SH SEE ALSO exec(2), getprivgrp(2), getuid(2), setresuid(2) privgrp(4). .SH STANDARDS CONFORMANCE .CR setuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4setuid()\fP \(mi set user \s-1ID\s+1@@@\f3setuid(2)\f1 .\" index@\f4setgid()\fP \(mi set group \s-1ID\s+1@@@\f3setuid(2)\f1 .\" index@set user or group \s-1ID\s+1@@@\f3setuid(2)\f1 .\" index@\s-1ID\s+1, set user or group@@@\f3setuid(2)\f1 .\" index@user \s-1ID\s+1, set@@@\f3setuid(2)\f1 .\" index@group \s-1ID\s+1: set group \s-1ID\s+1@@@\f3setuid(2)\f1 .\" .\" toc@\f3setuid(2)\f1:\0\0\f4setuid()\fP, \f4setgid()\fP@@@set user and group \s-1ID\s+1s .\" toc@\f4setgid()\fP:\0\0set group \s-1ID\s+1@@@see \f3setuid(2)\f1 .\" .\" links@setuid.2 setgid.2 .\" $Header: uname.2,v 72.6 94/11/14 15:27:15 ssa Exp $ .\" NOTE: If this page changes, uname.1 probably changes too. .TA u .TH uname 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uname(), setuname() \- get information about computer system; set node name (system name) .SH SYNOPSIS .C "#include " .PP .C "int uname(struct utsname *name);" .PP .C "int setuname(const char *name, size_t namelen);" .SH DESCRIPTION .SS uname() The .C uname() system call places information identifying the computer system in the .CR utsname structure pointed to by .IR name . .PP The .CR utsname structure, defined in .CR , is set up as follows: .nf .IP .C "#define UTSLEN 9" .C "#define SNLEN 15" .C "char sysname[UTSLEN];" .C "char nodename[UTSLEN];" .C "char release[UTSLEN];" .C "char version[UTSLEN];" .C "char machine[UTSLEN];" .C "char idnumber[SNLEN];" .fi .PP Each field is a null-terminated string. .PP The .CR sysname field contains the name of the operating system, .CR HP-UX on standard HP-UX systems. .PP The .CR nodename field contains the name by which the computer system is known in a communications network. .PP The .CR release field contains the release identifier of the operating system, such as .CR A.09.01 . .PP The .CR version field contains additional information about the operating system. This value can change in future releases. The first character of the .CR version field identifies the license level: .RS .TP .PD 0 .CR A Two-user system .TP .CR B 16-user system .TP .CR C 32-user system .TP .CR D 64-user system .TP .CR E 8-user system .TP .CR U 128-user, 256-user, or unlimited-user system .PD .RE .PP The .CR machine field contains the hardware and model identifiers of the computer system. .PP The .CR idnumber field contains a unique identification number within that class of hardware, possibly a hardware or software serial number. This field contains a null string if there is no identification number. .SS setuname() The .CR setuname() system call sets the node name (system name), as returned in the .CR nodename field of the .CR utsname structure, to .IR name , which has a length of .I namelen characters. This is usually executed by .CR /sbin/init.d/hostname at system boot time. Names are limited to .C UTSLEN - 1 characters; .CR UTSLEN is defined in .CR . .SH RETURN VALUE .CR uname() and .CR setuname() return the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .IR n is a nonnegative value. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR uname() or .CR setuname() fails, .CR errno is set to one of the following values. .TP 15 [EFAULT] .I name points to an illegal address. The reliable detection of this error is implementation dependent. .TP [EPERM] .CR setuname() was attempted by a process lacking appropriate privileges. .SH AUTHOR .CR uname() was developed by AT&T and HP. .SH SEE ALSO hostname(1), uname(1), setuname(1M), gethostname(2), sethostname(2). .SH STANDARDS CONFORMANCE .CR uname() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" links@uname.2 setuname.2 .\" .\" index@\f1computer system information, get@@@\f3uname(2)\f1 .\" index@\f1computer system, set node name@@@\f3uname(2)\f1 .\" index@\f1get information about computer system@@@\f3uname(2)\f1 .\" index@\f1license level of operating system, get@@@\f3uname(2)\f1 .\" index@\f1machine identification, get@@@\f3uname(2)\f1 .\" index@\f1machine number, get@@@\f3uname(2)\f1 .\" index@\f1name of operating system, get@@@\f3uname(2)\f1 .\" index@\f1name of operating system, get@@@\f3uname(2)\f1 .\" index@\f1node name, get/set@@@\f3uname(2)\f1 .\" index@\f1operating system information, get@@@\f3uname(2)\f1 .\" index@\f1operating system name, get@@@\f3uname(2)\f1 .\" index@\f1release level of operating system, get@@@\f3uname(2)\f1 .\" index@\f1release of operating system, get@@@\f3uname(2)\f1 .\" index@\f1set node name@@@\f3uname(2)\f1 .\" index@\f1set system name@@@\f3uname(2)\f1 .\" index@\f1system information, get@@@\f3uname(2)\f1 .\" index@\f1system name, get/set@@@\f3uname(2)\f1 .\" index@\f1system, get information@@@\f3uname(2)\f1 .\" index@\f1system, set node name@@@\f3uname(2)\f1 .\" index@\f1version level of operating system, get@@@\f3uname(2)\f1 .\" index@\f4setuname()\f1 \- set node name (system name)@@@\f3uname(2)\f1 .\" index@\f4uname()\f1 \- get information about computer system@@@\f3uname(2)\f1 .\" .\" toc@\f3uname(2)\f1:\0\0\f4uname()\f1@@@get information about computer system; set node name (system name) .\" toc@\f4setuname(2)\f1:\0\0set node name (system name)@@@see \f3uname(2) .\" $Header: shmop.2,v 72.5 94/11/14 15:26:32 ssa Exp $ .TA s .TH shmop 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shmat(), shmdt() \- shared memory operations .SH SYNOPSIS .C "#include " .PP .C "void *shmat(int shmid, void *shmaddr, int shmflg);" .PP .C "int shmdt(void *shmaddr);" .SH DESCRIPTION .CR shmat() attaches the shared memory segment associated with the shared memory identifier specified by .I shmid to the data segment of the calling process. .PP The segment is attached for reading if .RI ( shmflg .CR & .CR SHM_RDONLY ) is "true"; otherwise, it is attached for reading and writing. It is not possible to attach a segment for write only. .PP If the shared memory segment has never been attached to by any process prior to the current .CR shmat() call, .I shmaddr must be specified as zero and the segment is attached at a location selected by the operating system. That location is identical in all processes accessing that shared memory object. Once the operating system selects a location for a shared memory segment, the same location will be used across any subsequent .CR shmat() and .CR shmdt() calls on the segment until it is removed by the .CR IPC_RMID operation of .CR shmctl() . .PP If this is not the first .CR shmat() call on the shared memory segment throughout the system, .I shmaddr must either be zero or contain a nonzero address that is identical to the one returned from previous .CR shmat() calls for that segment. Even if no processes are currently attached to the segment, as long as the segment has been attached before, the same rule applies. .PP If the calling process is already attached to the shared memory segment, .CR shmat() fails and returns \(mi1 regardless of what value is passed in .I shmaddr. .PP .CR shmdt() detaches from the calling process's data segment the shared memory segment located at the address specified by .IR shmaddr . .SH RETURN VALUE .CR shmat() returns the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the data segment start address of the attached shared memory segment. .TP .CR \-1 Failure. The shared memory segment is not attached. .CR errno is set to indicate the error. .PD .RE .PP .CR shmdt() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR \-1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR shmat() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] Operation permission is denied to the calling process. .TP [EINVAL] .I shmid is not a valid shared memory identifier, or the calling process is already attached to .IR shmid . .TP [EINVAL] .I shmaddr is not zero and the machine does not permit nonzero values, or .I shmaddr is not equal to the current attach location for the shared memory segment. .TP [ENOMEM] The available data space is not large enough to accommodate the shared memory segment. .TP [EMFILE] The number of shared memory segments attached to the calling process exceed the system-imposed limit. .RE .PP If .CR shmdt() fails, .CR errno is set to one of the following values. .RS .TP 15 [EINVAL] .I shmaddr is not the data segment start address of a shared memory segment. .RE .SH EXAMPLES The following call to .CR shmat() attaches the shared memory segment to the process. This example assumes the process has a valid .IR shmid , which can be obtained by calling .IR shmget (2). .IP .C "char *shmptr, *shmat();" .br .C "shmptr = shmat(myshmid, (char *)0, 0);" .PP The following call to .CR shmdt() then detaches the shared memory segment. .IP .C "shmdt (shmptr);" .SH SEE ALSO ipcs(1), exec(2), exit(2), fork(2), shmctl(2), shmget(2), stdipc(3C). .SH STANDARDS CONFORMANCE .CR shmat() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR shmdt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4shmat()\f1 \- attach shared memory to data segment@@@\f3shmop(2)\f1 .\" index@\f4shmdt()\f1 \- detach shared memory from data segment@@@\f3shmop(2)\f1 .\" index@attach shared memory to data segment@@@\f3shmop(2)\f1 .\" index@data segment and shared memory, attach or detach@@@\f3shmop(2)\f1 .\" index@detach shared memory from data segment@@@\f3shmop(2)\f1 .\" index@shared memory and data segment, attach or detach@@@\f3shmop(2)\f1 .\" .\" links@shmop.2 shmat.2 .\" links@shmop.2 shmdt.2 .\" .\" toc@\f3shmop(2)\f1:\0\0\f4shmat()\f1, \f4shmdt()\f1@@@shared memory operations .\" toc@\f4shmat()\f1:\0\0attach shared memory to data segment@@@see \f3shmop(2)\f1 .\" toc@\f4shmdt()\f1:\0\0detach shared memory from data segment@@@see \f3shmop(2)\f1 .\" $Header: shmctl.2,v 78.1 96/01/19 20:38:57 ssa Exp $ .TA s .TH shmctl 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shmctl() \- shared memory control operations .SH SYNOPSIS .C "#include " .PP .C "int shmctl(int shmid, int cmd, struct shmid_ds *buf);" .SH DESCRIPTION The .CR shmctl() system call provides a variety of shared memory control operations as specified by the .IR cmd argument. .IR cmd can have the following values: .RS .TP 15 .CR IPC_STAT Place the current value of each member of the data structure associated with .I shmid into the structure pointed to by .IR buf . The contents of this structure are defined in .IR glossary (9). .TP .CR IPC_SET Set the value of the following members of the data structure associated with .I shmid to the corresponding value found in the structure pointed to by .IR buf : .RS .nf .IP .C "shm_perm.uid" .C "shm_perm.gid" .C "shm_perm.mode /* only low 9 bits */" .fi .RE .IP This .I cmd can only be executed by a process that has an effective user ID equal to either that of a user having appropriate privileges or to the value of either .CR shm_perm.uid or .CR shm_perm.cuid in the data structure associated with .IR shmid . .TP .CR IPC_RMID Remove the shared memory identifier specified by .I shmid from the system and destroy the shared memory segment and data structure associated with it. If the segment is attached to one or more processes, then the segment key is changed to .CR IPC_PRIVATE and the segment is marked removed. The segment disappears when the last attached process detaches it. This .I cmd can only be executed by a process that has an effective user ID equal to either that of a user with appropriate privileges or to the value of either .CR shm_perm.uid or .CR shm_perm.cuid in the data structure associated with .IR shmid . .TP .CR SHM_LOCK Lock the shared memory segment specified by .I shmid in memory. This .I cmd can only be executed by a process that either has an effective user ID equal to that of a user having appropriate privileges or has an effective user ID equal to the value of either .CR shm_perm.uid or .CR shm_perm.cuid in the data structure associated with .IR shmid and has the .CR PRIV_MLOCK privilege (see .IR getprivgrp (2)). .TP .CR SHM_UNLOCK Unlock the shared memory segment specified by .IR shmid . This .I cmd can only be executed by a process that either has an effective user ID equal to a user having appropriate privileges or has an effective user ID equal to the value of either .CR shm_perm.uid or .CR shm_perm.cuid in the data structure associated with .IR shmid and has the .CR PRIV_MLOCK privilege (see .IR getprivgrp (2)). .RE .SH RETURN VALUE .CR shmctl() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR shmctl() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] .I cmd is equal to .CR IPC_STAT and Read operation permission is denied to the calling process (see .B "shared memory operation permissions" in .IR glossary (9)). .TP [EFAULT] .I buf points to an illegal address. The reliable detection of this error is implementation dependent. .TP [EINVAL] .I cmd is equal to .CR SHM_UNLOCK and the shared-memory segment specified by .I shmid is not locked in memory. .TP [EINVAL] .I shmid is not a valid shared memory identifier. .TP [EINVAL] .I cmd is not a valid command, or the command contains invalid parameters. .TP [ENOMEM] .I cmd is equal to .CR SHM_LOCK and there is not sufficient lockable memory to fill the request. .TP [EPERM] .I cmd is equal to .CR IPC_RMID , .CR IPC_SET , .CR SHM_LOCK , or .CR SHM_UNLOCK and the effective user ID of the calling process is not equal to that of a user having appropriate privileges and it is not equal to the value of either .CR shm_perm.uid or .CR shm_perm.cuid in the data structure associated with .IR shmid . .TP [EPERM] .I cmd is equal to .CR SHM_LOCK or .CR SHM_UNLOCK and the effective user ID of the calling process is not equal to that of a user having appropriate privileges and the calling process does not have the .CR PRIV_MLOCK privilege (see .IR getprivgrp (2)). .RE .SH EXAMPLES The following call to .CR shmctl() locks in memory the shared memory segment represented by .CR myshmid . This example assumes the process has a valid shmid, which can be obtained by calling .IR shmget (2). .IP .C "shmctl (myshmid, SHM_LOCK, 0);" .PP The following call to .CR shmctl() removes the shared memory segment represented by .CR myshmid . This example assumes the process has a valid .IR shmid , which can be obtained by calling .CR shmget() (see .IR shmget (2). .IP .C "shmctl (myshmid, IPC_RMID, 0);" .SH AUTHOR .CR shmctl() was developed by AT&T and HP. .SH SEE ALSO ipcrm(1), ipcs(1), shmget(2), shmop(2), stdipc(3C). .SH STANDARDS CONFORMANCE .CR shmctl() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4shmctl()\f1 \- shared memory control operations@@@\f3shmctl(2)\f1 .\" index@\f1control operations, shared memory@@@\f3shmctl(2)\f1 .\" index@\f1memory control operations, shared@@@\f3shmctl(2)\f1 .\" index@\f1operations, shared memory control@@@\f3shmctl(2)\f1 .\" index@\f1shared memory control operations@@@\f3shmctl(2)\f1 .\" .\" toc@\f3shmctl(2)\f1:\0\0\f4shmctl()\f1@@@shared memory control operations .\" $Header: shmop.2,v 72.5 94/11/14 15:26:32 ssa Exp $ .TA s .TH shmop 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shmat(), shmdt() \- shared memory operations .SH SYNOPSIS .C "#include " .PP .C "void *shmat(int shmid, void *shmaddr, int shmflg);" .PP .C "int shmdt(void *shmaddr);" .SH DESCRIPTION .CR shmat() attaches the shared memory segment associated with the shared memory identifier specified by .I shmid to the data segment of the calling process. .PP The segment is attached for reading if .RI ( shmflg .CR & .CR SHM_RDONLY ) is "true"; otherwise, it is attached for reading and writing. It is not possible to attach a segment for write only. .PP If the shared memory segment has never been attached to by any process prior to the current .CR shmat() call, .I shmaddr must be specified as zero and the segment is attached at a location selected by the operating system. That location is identical in all processes accessing that shared memory object. Once the operating system selects a location for a shared memory segment, the same location will be used across any subsequent .CR shmat() and .CR shmdt() calls on the segment until it is removed by the .CR IPC_RMID operation of .CR shmctl() . .PP If this is not the first .CR shmat() call on the shared memory segment throughout the system, .I shmaddr must either be zero or contain a nonzero address that is identical to the one returned from previous .CR shmat() calls for that segment. Even if no processes are currently attached to the segment, as long as the segment has been attached before, the same rule applies. .PP If the calling process is already attached to the shared memory segment, .CR shmat() fails and returns \(mi1 regardless of what value is passed in .I shmaddr. .PP .CR shmdt() detaches from the calling process's data segment the shared memory segment located at the address specified by .IR shmaddr . .SH RETURN VALUE .CR shmat() returns the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the data segment start address of the attached shared memory segment. .TP .CR \-1 Failure. The shared memory segment is not attached. .CR errno is set to indicate the error. .PD .RE .PP .CR shmdt() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR \-1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR shmat() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] Operation permission is denied to the calling process. .TP [EINVAL] .I shmid is not a valid shared memory identifier, or the calling process is already attached to .IR shmid . .TP [EINVAL] .I shmaddr is not zero and the machine does not permit nonzero values, or .I shmaddr is not equal to the current attach location for the shared memory segment. .TP [ENOMEM] The available data space is not large enough to accommodate the shared memory segment. .TP [EMFILE] The number of shared memory segments attached to the calling process exceed the system-imposed limit. .RE .PP If .CR shmdt() fails, .CR errno is set to one of the following values. .RS .TP 15 [EINVAL] .I shmaddr is not the data segment start address of a shared memory segment. .RE .SH EXAMPLES The following call to .CR shmat() attaches the shared memory segment to the process. This example assumes the process has a valid .IR shmid , which can be obtained by calling .IR shmget (2). .IP .C "char *shmptr, *shmat();" .br .C "shmptr = shmat(myshmid, (char *)0, 0);" .PP The following call to .CR shmdt() then detaches the shared memory segment. .IP .C "shmdt (shmptr);" .SH SEE ALSO ipcs(1), exec(2), exit(2), fork(2), shmctl(2), shmget(2), stdipc(3C). .SH STANDARDS CONFORMANCE .CR shmat() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR shmdt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4shmat()\f1 \- attach shared memory to data segment@@@\f3shmop(2)\f1 .\" index@\f4shmdt()\f1 \- detach shared memory from data segment@@@\f3shmop(2)\f1 .\" index@attach shared memory to data segment@@@\f3shmop(2)\f1 .\" index@data segment and shared memory, attach or detach@@@\f3shmop(2)\f1 .\" index@detach shared memory from data segment@@@\f3shmop(2)\f1 .\" index@shared memory and data segment, attach or detach@@@\f3shmop(2)\f1 .\" .\" links@shmop.2 shmat.2 .\" links@shmop.2 shmdt.2 .\" .\" toc@\f3shmop(2)\f1:\0\0\f4shmat()\f1, \f4shmdt()\f1@@@shared memory operations .\" toc@\f4shmat()\f1:\0\0attach shared memory to data segment@@@see \f3shmop(2)\f1 .\" toc@\f4shmdt()\f1:\0\0detach shared memory from data segment@@@see \f3shmop(2)\f1 .\" $Header: shmget.2,v 72.5 94/11/14 15:26:31 ssa Exp $ .TA s .TH shmget 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shmget \- get shared memory segment .SH SYNOPSIS .C "#include " .PP .C "int shmget(key_t key, size_t size, int shmflg);" .SH DESCRIPTION .C shmget() returns the shared memory identifier associated with .IR key . .PP A shared memory identifier and associated data structure and shared memory segment of size .I size bytes (see .IR glossary (9)) are created for .I key if one of the following is true: .RS .TP 3 \(bu .I key is equal to .CR IPC_PRIVATE . This call creates a new identifier, subject to available resources. The identifier will never be returned by another call to .C shmget() until it has been released by a call to .CR shmctl() . The identifier should be used among the calling process and its descendents; however, it is not a requirement. The resource can be accessed by any process having the proper permissions. .TP \(bu .I key does not already have a shared memory identifier associated with it, and .RI ( shmflg " & " .CR IPC_CREAT ) is ``true''. .RE .PP Upon creation, the data structure associated with the new shared memory identifier is initialized as follows: .RS .TP 3 \(bu .CR shm_perm.cuid , .CR shm_perm.uid , .CR shm_perm.cgid , and .C shm_perm.gid are set equal to the effective user .SM ID and effective group .SM ID, respectively, of the calling process. .TP \(bu .CR shm_perm.cuid , The low-order 9 bits of .C shm_perm.mode are set equal to the low-order 9 bits of .IR shmflg . .C shm_segsz is set equal to the value of .IR size . .TP \(bu .CR shm_lpid , .CR shm_nattch , .CR shm_atime , and .C shm_dtime are set equal to 0. .TP \(bu .C shm_ctime is set equal to the current time. .RE .SH EXAMPLES The following call to .C shmget() returns a unique shmid for the newly created shared memory segment of 4096 bytes: .IP .C int myshmid; .IP .C myshmid = shmget (IPC_PRIVATE, 4096, 0600); .SH RETURN VALUE Upon successful completion, a non-negative integer, namely a shared memory identifier is returned. Otherwise, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .C shmget() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EINVAL] .I size is less than the system-imposed minimum or greater than the system-imposed maximum. .TP .SM [EACCES] A shared memory identifier exists for .I key but operation permission (see .IR glossary (9)) as specified by the low-order 9 bits of .I shmflg would not be granted. .TP .SM [EINVAL] A shared memory identifier exists for .I key but the size of the segment associated with it is less than .I size and .I size is not equal to zero. .TP .SM [ENOENT] A shared memory identifier does not exist for .I key and .RI ( shmflg " &" .SM .CR IPC_CREAT ) is ``false''. .TP .SM [ENOSPC] A shared memory identifier is to be created but the system-imposed limit on the maximum number of allowed shared memory identifiers system wide would be exceeded. .TP .SM [ENOMEM] A shared memory identifier and associated shared memory segment are to be created, but the amount of available physical memory is not sufficient to fill the request. .TP .SM [EEXIST] A shared memory identifier exists for .I key but .RI (\|( shmflg & .CR IPC_CREAT ) && .RI ( shmflg & .CR IPC_EXCL )\|) is ``true''. .SH SEE ALSO ipcrm(1), ipcs(1), shmctl(2), shmop(2), stdipc(3C). .SH STANDARDS CONFORMANCE .CR shmget() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4shmget()\fP \(mi get shared memory segment@@@\f3shmget(2)\f1 .\" index@get: shared memory segment@@@\f3shmget(2)\f1 .\" index@shared memory segment, get@@@\f3shmget(2)\f1 .\" index@memory segment, get shared@@@\f3shmget(2)\f1 .\" index@segment, get shared memory@@@\f3shmget(2)\f1 .\" .\" toc@\f3shmget(2)\f1:\0\0\f4shmget()\fP@@@get shared memory segment .\" $Header: shmop.2,v 72.5 94/11/14 15:26:32 ssa Exp $ .TA s .TH shmop 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shmat(), shmdt() \- shared memory operations .SH SYNOPSIS .C "#include " .PP .C "void *shmat(int shmid, void *shmaddr, int shmflg);" .PP .C "int shmdt(void *shmaddr);" .SH DESCRIPTION .CR shmat() attaches the shared memory segment associated with the shared memory identifier specified by .I shmid to the data segment of the calling process. .PP The segment is attached for reading if .RI ( shmflg .CR & .CR SHM_RDONLY ) is "true"; otherwise, it is attached for reading and writing. It is not possible to attach a segment for write only. .PP If the shared memory segment has never been attached to by any process prior to the current .CR shmat() call, .I shmaddr must be specified as zero and the segment is attached at a location selected by the operating system. That location is identical in all processes accessing that shared memory object. Once the operating system selects a location for a shared memory segment, the same location will be used across any subsequent .CR shmat() and .CR shmdt() calls on the segment until it is removed by the .CR IPC_RMID operation of .CR shmctl() . .PP If this is not the first .CR shmat() call on the shared memory segment throughout the system, .I shmaddr must either be zero or contain a nonzero address that is identical to the one returned from previous .CR shmat() calls for that segment. Even if no processes are currently attached to the segment, as long as the segment has been attached before, the same rule applies. .PP If the calling process is already attached to the shared memory segment, .CR shmat() fails and returns \(mi1 regardless of what value is passed in .I shmaddr. .PP .CR shmdt() detaches from the calling process's data segment the shared memory segment located at the address specified by .IR shmaddr . .SH RETURN VALUE .CR shmat() returns the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .I n is the data segment start address of the attached shared memory segment. .TP .CR \-1 Failure. The shared memory segment is not attached. .CR errno is set to indicate the error. .PD .RE .PP .CR shmdt() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR \-1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR shmat() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] Operation permission is denied to the calling process. .TP [EINVAL] .I shmid is not a valid shared memory identifier, or the calling process is already attached to .IR shmid . .TP [EINVAL] .I shmaddr is not zero and the machine does not permit nonzero values, or .I shmaddr is not equal to the current attach location for the shared memory segment. .TP [ENOMEM] The available data space is not large enough to accommodate the shared memory segment. .TP [EMFILE] The number of shared memory segments attached to the calling process exceed the system-imposed limit. .RE .PP If .CR shmdt() fails, .CR errno is set to one of the following values. .RS .TP 15 [EINVAL] .I shmaddr is not the data segment start address of a shared memory segment. .RE .SH EXAMPLES The following call to .CR shmat() attaches the shared memory segment to the process. This example assumes the process has a valid .IR shmid , which can be obtained by calling .IR shmget (2). .IP .C "char *shmptr, *shmat();" .br .C "shmptr = shmat(myshmid, (char *)0, 0);" .PP The following call to .CR shmdt() then detaches the shared memory segment. .IP .C "shmdt (shmptr);" .SH SEE ALSO ipcs(1), exec(2), exit(2), fork(2), shmctl(2), shmget(2), stdipc(3C). .SH STANDARDS CONFORMANCE .CR shmat() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR shmdt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4shmat()\f1 \- attach shared memory to data segment@@@\f3shmop(2)\f1 .\" index@\f4shmdt()\f1 \- detach shared memory from data segment@@@\f3shmop(2)\f1 .\" index@attach shared memory to data segment@@@\f3shmop(2)\f1 .\" index@data segment and shared memory, attach or detach@@@\f3shmop(2)\f1 .\" index@detach shared memory from data segment@@@\f3shmop(2)\f1 .\" index@shared memory and data segment, attach or detach@@@\f3shmop(2)\f1 .\" .\" links@shmop.2 shmat.2 .\" links@shmop.2 shmdt.2 .\" .\" toc@\f3shmop(2)\f1:\0\0\f4shmat()\f1, \f4shmdt()\f1@@@shared memory operations .\" toc@\f4shmat()\f1:\0\0attach shared memory to data segment@@@see \f3shmop(2)\f1 .\" toc@\f4shmdt()\f1:\0\0detach shared memory from data segment@@@see \f3shmop(2)\f1 .\" $Header: shutdown.2,v 78.2 96/03/15 16:44:45 ssa Exp $ .TA s .TH shutdown 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shutdown \- shut down a socket .SH SYNOPSIS .C #include .PP .C "int shutdown(int s, int how);" .SH DESCRIPTION The .C shutdown() system call is used to shut down a socket. In the case of a full-duplex connection, .C shutdown() can be used to either partially or fully shut down the socket, depending upon the value of .IR how. .RS .TP 20 .I how .B Interpretation .PD 0 .TP .C "SHUT_RD or 0" Further receives are disallowed .TP .C "SHUT_WR or 1" Further sends are disallowed .TP .C "SHUT_RDWR or 2" Further sends and receives are disallowed .RE .PD .PP The .I s parameter is a socket descriptor for the socket to be shut down. .PP Once the socket has been shut down for receives, all further .C recv() calls return an end-of-file condition. A socket that has been shut down for sending causes further .C send() calls to return an .SM EPIPE error and send the .C SIGPIPE signal. After a socket has been fully shut down, operations other than .C recv() and .C send() return appropriate errors, and the only other thing that can be done to the socket is a .CR close() . .PP Multiple shutdowns on a connected socket and shutdowns on a socket that is not connected may not return errors. .PP A .C shutdown() on a connectionless socket, such as .C SOCK_DGRAM , only marks the socket as unable to do further .C send() or .C recv() calls, depending upon the value of .IR how . Once this type of socket has been disabled for both sending and receiving data, it becomes fully shut down. For .C SOCK_STREAM sockets, if .I how is .C 1 or .CR 2 , the connection begins to be closed gracefully in addition to the normal actions. However, the .C shutdown() call does not wait for the completion of the graceful disconnection. The disconnection is complete when both sides of the connection have done a .C shutdown() with .I how equal to .C 1 or .CR 2 . Once the connection has been completely terminated, the socket becomes fully shut down. The .C SO_LINGER option (see .IR socket (2)) does not have any meaning for the .C shutdown() call, but does for the .C close() call. For more information on how the .C close() call interacts with sockets, see .IR socket (2). .PP If a .C shutdown() is performed on a .C SOCK_STREAM socket that has a .C listen() pending on it, that socket becomes fully shut down when .I how = 1. .SS \s-1AF_CCITT\s0 only: The .I how parameter behaves differently if the socket is of the the .C AF_CCITT address family. If .I how is set to .C 0 the specified socket can no longer receive data. The .SM SVC is not cleared and remains intact. However, if data is subsequently received on the .SM SVC, it is cleared. The connection is not completely down until either side executes a .C close() or .C shutdown() with .I how set to .C 1 or .CR 2 . .PP If .I how is set to .C 1 or .CR 2 , the .SM SVC can no longer send or receive data and the .SM SVC is cleared. The socket's resources are maintained so that data arriving prior to the .C shutdown() call can still be read. .SH RETURN VALUE Upon successful completion, .C shutdown() returns 0; otherwise it returns \(mi1 and .C errno is set to indicate the error. .SH ERRORS .C shutdown() fails if any of the following conditions are encountered: .TP 15 .SM [EBADF] .I s is not a valid file descriptor. .TP .SM [ENOTSOCK] .I s is a valid file descriptor, but it is not a socket. .TP .SM [EINVAL] .CR "HP-UX BSD Sockets only." The specified socket is not connected. .TP .SM [ENOTCONN] .CR "_XOPEN_SOURCE_EXTENDED only." The specified socket is not connected. .TP .SM [EINVAL] .CR "_XOPEN_SOURCE_EXTENDED only." The .I how argument is invalid. .SH AUTHOR .C shutdown() was developed by the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO close(2), connect(2), socket(2), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR shutdown() ": XPG4" .\" .\" index@\f4shutdown()\fP \(mi shut down a socket@@@\f3shutdown(2)\f1 .\" index@shut down a socket@@@\f3shutdown(2)\f1 .\" index@socket, shut down a@@@\f3shutdown(2)\f1 .\" .\" toc@\f3shutdown(2)\f1:\0\0\f4shutdown()\fP@@@shut down a socket .\" .\" $Header: sigaction.2,v 76.1 95/07/07 14:52:21 ssa Exp $ .TA s .TH sigaction 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigaction \- examine and change signal action .SH SYNOPSIS .C "#include " .PP .C "int sigaction (" .PD 0 .nf .IP .C "int sig," .C "const struct sigaction *act," .C "struct sigaction *oact" .PP .C ");" .PD .fi .SH DESCRIPTION The .CR sigaction() function allows the calling process to examine and/or specify the action to be associated with a specific signal. The argument .IR sig specifies the signal; acceptable values are defined in .CR . .PP The structure sigaction, used to describe an action to be taken, is defined in the header .CR to include at least the following members: .PP .TS tab(@); LBw(1.5i)@LBw(1i)@LBw(2i) lf4@lf4@l. Member Type@Member Name@Description void(*)(int)@sa_handler@T{ SIG_DFL, SIG_IGN or pointer to a function. T} sigset_t@sa_mask@T{ Additional set of signals to be blocked during execution of signal-catching function. T} int@sa_flags@T{ Special flags to affect behavior of signal. T} .\"code in margin: "UX"UX void(*)(int, siginfo_t*,void *)@sa_sigaction@T{ signal-catching function. T} .TE .PP If the argument .IR act is not a null pointer, it points to a structure specifying the action to be associated with the specified signal. If the argument .IR oact is not a null pointer, the action previously associated with the signal is stored in the location pointed to by the argument .IR oact . If the argument act is a null pointer, signal handling is unchanged; thus, the call can be used to enquire about the current handling of a given signal. The .IR sa_handler field of the .CR sigaction structure identifies the action to be associated with the specified signal. If the .IR sa_handler field specifies a signal-catching function, the .IR sa_mask field identifies a set of signals that will be added to the process' signal mask before the signal-catching function is invoked. The .CR SIGKILL and .CR SIGSTOP signals will not be added to the signal mask using this mechanism; this restriction will be enforced by the system without causing an error to be indicated. .PP The .IR sa_flags field can be used to modify the behaviour of the specified signal. The following flags, defined in the header .CR , can be set in .IR sa_flags : .RS .TP 23 .C SA_NOCLDSTOP Do not generate .CR SIGCHLD when children stop. .TP .\" Margin note: "UX" .C SA_ONSTACK If set and an alternate signal stack has been declared with .CR sigaltstack() or .CR sigstack() , the signal will be delivered to the calling process on that stack. Otherwise, the signal will be delivered on the current stack. .TP .C SA_RESETHAND If set, the disposition of the signal will be reset to .CR SIG_DFL and the .CR SA_SIGINFO flag will be cleared on entry to the signal handler (Note: .CR SIGILL and .CR SIGTRAP cannot be automatically reset when delivered; the system silently enforces this restriction). Otherwise, the disposition of the signal will not be modified on entry to the signal handler. In addition, if this flag is set, .CR sigaction() behaves as if the .CR SA_NODEFER flag were also set. .TP .C SA_RESTART This flag affects the behaviour of interruptible functions; that is, those specified to fail with .CR errno set to .CR EINTR . If set, and a function specified as interruptible is interrupted by this signal, the function will restart and will not fail with .C EINTR unless otherwise specified. If the flag is not set, interruptible functions interrupted by this signal will fail with .CR errno set to .CR EINTR. .TP .C SA_SIGINFO If cleared and the signal is caught, the signal-catching function will be entered as: .IP .C "void func(int signo);" where .CR signo is the only argument to the signal catching function. In this case the .IR sa_handler member must be used to describe the signal catching function and the application must not modify the .IR sa_sigaction member. .IP If .CR SA_SIGINFO is set and the signal is caught, the signal-catching function will be entered as: .IP .C "void func(int signo, siginfo_t *info, void *context);" where two additional arguments are passed to the signal catching function. If the second argument is not a null pointer, it will point to an object of type .IR siginfo_t explaining the reason why the signal was generated; the third argument can be cast to a pointer to an object of type .IR ucontext_t to refer to the receiving process' context that was interrupted when the signal was delivered. In this case the .IR sa_sigaction member must be used to describe the signal catching function and the application must not modify the .IR sa_handler member. .IP The .IR si_signo member contains the system\-generated signal number. .IP The .IR si_errno member may contain implementation\-dependent additional error information; if non\-zero, it contains an error number identifying the condition that caused the signal to be generated. .IP The .IR si_code member contains a code identifying the cause of the signal. If the value of .IR si_code is less than or equal to 0, then the signal was generated by a process and .IR si_pid and .IR si_uid respectively indicate the process ID and the real user ID of the sender. The values of .IR si_pid and .IR si_uid are otherwise meaningless. .TP .C SA_NOCLDWAIT If set, and .IR sig equals .CR SIGCHLD , child processes of the calling processes will not be transformed into zombie processes when they terminate. If the calling process subsequently waits for its children, and the process has no unwaited for children that were transformed into zombie processes, it will block until all of its children terminate, and .CR wait() , .CR wait3() , .CR waitid() , and .CR waitpid() will fail and set errno to .CR ECHILD . Otherwise, terminating child processes will be transformed into zombie processes, unless .CR SIGCHLD is set to .CR SIG_IGN . .TP .C SA_NODEFER If set and .IR sig is caught, .IR sig will not be added to the process' signal mask on entry to the signal handler unless it is included in .IR sa_mask . Otherwise, .IR sig will always be added to the process' signal mask on entry to the signal handler. ./"? .RE .PP If .IR sig is .CR SIGCHLD and the .CR SA_NOCLDSTOP flag is not set in .IR sa_flags , and the implementation supports the .CR SIGCHLD signal, then a .CR SIGCHLD signal will be generated for the calling process whenever any of its child processes stop. If .IR sig is .CR SIGCHLD and the .CR SA_NOCLDSTOP flag is set in .IR sa_flags , then the implementation will not generate a .CR SIGCHLD signal in this way. .PP When a signal is caught by a signal-catching function installed by .CR sigaction() , a new signal mask is calculated and installed for the duration of the signal-catching function (or until a call to either .CR sigprocmask() or .CR sigsuspend() is made). This mask is formed by taking the union of the current signal mask and the value of the .IR sa_mask for the signal being delivered .\"code in margin: "UX" .\"! unless .CR SA_NODEFER or .CR SA_RESETHAND is set, and then including the signal being delivered. If and when the user's signal handler returns normally, the original signal mask is restored. .PP Once an action is installed for a specific signal, it remains installed until another action is explicitly requested (by another call to .\"code in margin: "UX" .CR sigaction() ), until the .CR SA_RESETHAND flag causes resetting of the handler, or until one of the exec functions is called. .PP If the previous action for .IR sig had been established by .CR signal() , the values of the fields returned in the structure pointed to by .IR oact are unspecified, and in particular .IR oact->sa_handler is not necessarily the same value passed to .CR signal() . However, if a pointer to the same structure or a copy thereof is passed to a subsequent call to .CR sigaction() via the .IR act argument, handling of the signal will be as if the original call to .CR signal() were repeated. .PP If .CR sigaction() fails, no new signal handler is installed. .PP It is unspecified whether an attempt to set the action for a signal that cannot be caught or ignored to .CR SIG_DFL is ignored or causes an error to be returned with .CR errno set to .CR EINVAL. .PP A signal is said to be generated for (or sent to) a process when the event that causes the signal first occurs. Examples of such events include detection of hardware faults, timer expiration and terminal activity, as well as the invocation of .CR kill() . In some circumstances, the same event generates signals for multiple processes. .PP Each process has an action to be taken in response to each signal defined by the system (see Signal Actions). A signal is said to be delivered to a process when the appropriate action for the process and signal is taken. .PP During the time between the generation of a signal and its delivery, the signal is said to be pending. Ordinarily, this interval cannot be detected by an application. However, a signal can be blocked from delivery to a process. If the action associated with a blocked signal is anything other than to ignore the signal, and if that signal is generated for the process, the signal will remain pending until either it is unblocked or the action associated with it is set to ignore the signal. If the action associated with a blocked signal is to ignore the signal and if that signal is generated for the process, it is unspecified whether the signal is discarded immediately upon generation or remains pending. .PP Each process has a signal mask that defines the set of signals currently blocked from delivery to it. The signal mask for a process is initialised from that of its parent. The .CR sigaction() , .CR sigprocmask() , and .CR sigsuspend() functions control the manipulation of the signal mask. .PP The determination of which action is taken in response to a signal is made at the time the signal is delivered, allowing for any changes since the time of generation. This determination is independent of the means by which the signal was originally generated. If a subsequent occurrence of a pending signal is generated, it is implementation-dependent as to whether the signal is delivered more than once. The order in which multiple, simultaneously pending signals are delivered to a process is unspecified. .PP When any stop signal ( .CR SIGSTOP , .CR SIGTSTP , .CR SIGTTIN , .CR SIGTTOU ) is generated for a process, any pending .CR SIGCONT signals for that process will be discarded. Conversely, when .CR SIGCONT is generated for a process, all pending stop signals for that process will be discarded. When .CR SIGCONT is generated for a process that is stopped, the process will be continued, even if the .CR SIGCONT signal is blocked or ignored. If .CR SIGCONT is blocked and not ignored, it will remain pending until it is either unblocked or a stop signal is generated for the process. .PP An implementation will document any condition not specified by this document under which the implementation generates signals. .PP Signal Actions .PP. There are three types of action that can be associated with a signal: .CR SIG_DFL , .CR SIG_IGN or a pointer to a function. Initially, all signals will be set to .CR SIG_DFL or .CR SIG_IGN prior to entry of the .CR main() routine (see the .CR exec functions). The actions prescribed by these values are as follows: .PP .CR SIG_DFL \- signal\-specific default action .RS .TP 3 \(bu The default actions for the signals defined in this document are specified under .CR . .TP 3 \(bu If the default action is to stop the process, the execution of that process is temporarily suspended. When a process stops, a .CR SIGCHLD signal will be generated for its parent process, unless the parent process has set the .CR SA_NOCLDSTOP flag. While a process is stopped, any additional signals that are sent to the process will not be delivered until the process is continued, except .CR SIGKILL which always terminates the receiving process. A process that is a member of an orphaned process group will not be allowed to stop in response to the .CR SIGTSTP , .CR SIGTTIN , or .CR SIGTTOU signals. In cases where delivery of one of these signals would stop such a process, the signal will be discarded. .TP 3 \(bu Setting a signal action to .CR SIG_DFL for a signal that is pending, and whose default action is to ignore the signal (for example, .CR SIGCHLD ), will cause the pending signal to be discarded, whether or not it is blocked. .RE .PP .CR SIG_IGN \- ignore signal .RS .TP 3 \(bu Delivery of the signal will have no effect on the process. The behaviour of a process is undefined after it ignores a .CR SIGFPE , .CR SIGILL , or .CR SIGSEGV signal that was not generated by .CR kill() or .CR raise() . .TP 3 \(bu The system will not allow the action for the signals .CR SIGKILL or .CR SIGSTOP to be set to .CR SIG_IGN . .TP 3 \(bu Setting a signal action to .CR SIG_IGN for a signal that is pending will cause the pending signal to be discarded, whether or not it is blocked. .TP 3 \(bu If a process sets the action for the .CR SIGCHLD signal to .CR SIG_IGN , the behaviour is .\"code in margin: "UX" UX unspecified, except as specified below. .IP If the action for the .CR SIGCHLD signal is set to .CR SIG_IGN , child processes of the calling processes will not be transformed into zombie processes when they terminate. If the calling process subsequently waits for its children, and the process has no unwaited for children that were transformed into zombie processes, it will block until all of its children terminate, and .CR wait() , .CR wait3() , .CR waitid() , and .CR waitpid() will fail and set .CR errno to .CR ECHILD . .\" ? .RE .PP Pointer to a function \- catch signal .RS .TP 3 \(bu On delivery of the signal, the receiving process is to execute the signal-catching function at the specified address. After returning from the signal-catching function, the receiving process will resume execution at the point at which it was interrupted. .\" UX .TP 3 \(bu If .CR SA_SIGINFO is cleared, the signal- catching function will be entered as: .IP .C void func(int signo); .PP where .CR func is the specified signal-catching function and .IR signo is the signal number of the signal being delivered. .\" UX .TP 3 \(bu If .CR SA_SIGINFO is set, the signal-catching function will be entered as: .IP .C void func(int signo, siginfo_t *siginfo, void *ucontextptr); .PP where .CR func is the specified signal-catching function, .CR signo is the signal number of the signal being delivered, .IR siginfo points to an object of type .IR siginfo_t associated with the signal being delivered, and .CR ucontextptr points to a .IR ucontext_t . .\" ? .TP 3 \(bu The behaviour of a process is undefined after it returns normally from a signal\- .\" UX catching function for a .\"! .CR SIGBUS , .CR SIGFPE , .CR SIGILL , or .CR SIGSEGV signal that was not generated by .CR kill() or .CR raise() . .TP 3 \(bu The system will not allow a process to catch the signals .CR SIGKILL and .CR SIGSTOP . .TP 3 \(bu If a process establishes a signal-catching function for the .CR SIGCHLD signal while it has a terminated child process for which it has not waited, it is unspecified whether a .CR SIGCHILD signal is generated to indicate that child process. .TP 3 \(bu When signal\-catching functions are invoked asynchronously with process execution, the behaviour of some of the functions defined by this document is unspecified if they are called from a signal\-catching function. .IP The following table defines a set of functions that are either reentrant or not interruptible by signals. Therefore applications may invoke them, without restriction, from signal-catching functions: .PP .TS center tab(#); lf4#lf4#lf4#lf4. access()#fstat()#read()#sysconf() alarm()#getegid()#rename()#tcdrain() cfgetispeed()#geteuid()#rmdir()#tcflow() cfgetospeed()#getgid()#setgid()#tcflush() cfsetispeed()#getgroups()#setpgid()#tcgetattr() cfsetospeed()#getpgrp()#setsid()#tcgetpgrp() chdir()#getpid()#setuid()#tcsendbreak() chmod()#getppid()#sigaction()#tcsetattr() chown()#getuid()#sigaddset()#tcsetpgrp() close()#kill()#sigdelset()#time() creat()#link()#sigemptyset()#times() dup2()#lseek()#sigfillset()#umask() dup()#mkdir()#sigismember()#uname() execle()#mkfifo()#signal()#unlink() execve()#open()#sigpending()#utime() _exit()#pathconf()#sigprocmask()#wait() fcntl()#pause()#sigsuspend()#waitpid() fork()#pipe()#sleep()#write() .\" EX fpathconf()#raise()#stat() .TE .PP All functions not in the above table are considered to be unsafe with respect to signals. In the presence of signals, all functions defined by this document will behave as defined when called from or interrupted by a signal-catching function, with a single exception: when a signal interrupts an unsafe function and the signal-catching function calls an unsafe function, the behaviour is undefined. .RE .PP Signal Effects on Other Functions .PP Signals affect the behaviour of certain functions defined by this document if delivered to a process while it is executing such a function. If the action of the signal is to terminate the process, the process will be terminated and the function will not return. If the action of the signal is to stop the process, the process will stop until continued or terminated. Generation of a .CR SIGCONT signal for the process causes the process to be continued, and the original function will continue at the point the process was stopped. If the action of the signal is to invoke a signal-catching function, the signal-catching function will be invoked; in this case the original function is said to be interrupted by the signal. If the signal-catching function executes a return statement, the behaviour of the interrupted function will be as described individually for that function. Signals that are ignored will not affect the behaviour of any function; signals that are blocked will not affect the behaviour of any function until they are unblocked and then delivered. .SH RETURN VALUE Upon successful completion, .CR sigaction() returns 0. Otherwise \(mi1 is returned, .CR errno is set to indicate the error and no new signal-catching function will be installed. .SH ERRORS The .CR sigaction() function will fail if: .RS .TP 25 [EINVAL] The .IR sig argument is not a valid signal number or an attempt is made to catch a signal that cannot be caught or ignore a signal that cannot be ignored. .RE .PP The .CR sigaction() function may fail if: .RS .TP 25 [EINVAL] An attempt was made to set the action to .CR SIG_DFL for a signal that cannot be caught or ignored (or both). .RE .SH APPLICATION USAGE The .CR sigaction() function supersedes the .CR signal() interface, and should be used in preference. In particular, .CR sigaction() and .CR signal() should not be used in the same process to control the same signal. The behaviour of reentrant functions, as defined in the description, is as specified by this document, regardless of invocation from a signal-catching function. This is the only intended meaning of the statement that reentrant functions may be used in signal-catching functions without restrictions. Applications must still consider all effects of such functions on such things as data structures, files and process state. In particular, application writers need to consider the restrictions on interactions when interrupting .CR sleep() and interactions among multiple handles for a file description. The fact that any specific function is listed as reentrant does not necessarily mean that invocation of that function from a signal\-catching function is recommended. .PP In order to prevent errors arising from interrupting non-reentrant function calls, applications should protect calls to these functions either by blocking the appropriate signals or through the use of some programmatic semaphore. This document does not address the more general problem of synchronising access to shared data structures. Note in particular that even the "safe" functions may modify the global variable .CR errno ; the signal\-catching function may want to save and restore its value. Naturally, the same principles apply to the reentrancy of application routines and asynchronous data access. Note that .CR longjmp() and .CR siglongjmp() are not in the list of reentrant functions. This is because the code executing after .CR longjmp() and .CR siglongjmp() can call any unsafe functions with the same danger as calling those unsafe functions directly from the signal handler. Applications that use .CR longjmp() and .CR siglongjmp() from within signal handlers require rigorous protection in order to be portable. Many of the other functions that are excluded from the list are traditionally implemented using either .CR malloc() or .CR free() functions or the standard I/O library, both of which traditionally use data structures in a non-reentrant manner. Because any combination of different functions using a common data structure can cause reentrancy problems, this document does not define the behaviour when any unsafe function is called in a signal handler that interrupts an unsafe function. .PP If the signal occurs other than as the result of calling .CR abort() , .CR kill() , or .CR raise() , the behaviour is undefined if the signal handler calls any function in the standard library other than one of the functions listed in the table above or refers to any object with static storage duration other than by assigning a value to a static storage duration variable of type volatile .IR sig_atomic_t . Furthermore, if such a call fails, the value of .CR errno is indeterminate. .\" UX .PP Usually, the signal is executed on the stack that was in effect before the signal was delivered. An alternate stack may be specified to receive a subset of the signals being caught. .PP When the signal handler returns, the receiving process will resume execution at the point it was interrupted unless the signal handler makes other arrangements. If .CR longjmp() or .CR _longjmp() is used to leave the signal handler, then the signal mask must be explicitly restored by the process. .PP POSIX.4-1993 defines the third argument of a signal handling function when .CR SA_SIGINFO is set as a .I void .I * instead of a .I ucontext_t .I * , but without requiring type checking. New applications should explicitly cast the third argument of the signal handling function to .IR uncontext_ t .IR * . .PP The BSD optional four argument signal handling function is not supported by this specification. The BSD declaration would be .IP .C void handler(int sig, int code, struct sigcontext *scp, char *addr); where .IR sig is the signal number, code is additional information on certain signals, .IR scp is a pointer to the .CR sigcontext structure, and .IR addr is additional address information. Much the same information is available in the objects pointed to by the second argument of the signal handler specified when .CR SA_SIGINFO is set. .\" ? ? .SH FUTURE DIRECTIONS The .CR fpathconf() function is marked as an extension in the list of safe functions because it is not included in the corresponding list in the ISO POSIX-1 standard, but it is expected to be added in a future revision of that standard. .SH SEE ALSO bsd_signal(), kill(), _longjmp(), longjmp(), raise(), sigaddset(), sigaltstack(), sigdelset(), sigemptyset(), sigfillset(), sigismember(), signal(), sigprocmask(), sigsuspend(), wait(), wait3(), waitid(), waitpid(), , . .SH CHANGE HISTORY First released in Issue 3. .PP Entry included for alignment with the POSIX.1-1988 standard. .SH Issue 4 The following changes are incorporated for alignment with the ISO POSIX-1 standard: .RS .TP 3 \(bu The type of argument act is changed from .CR struct .CR sigaction .CR * to .CR const .CR struct .CR sigaction .CR * . .TP 3 \(bu A statement is added to the DESCRIPTION section indicating that the consequence of attempting to set .CR SIG_DFL for a signal that cannot be caught or ignored is unspecified. The .CR EINVAL error, describing one possible reaction to this condition, is added to the ERRORS section. .RE .PP Other changes are incorporated as follows: .RS .TP 3 \(bu The .CR raise() and .CR signal() functions are added to the list of functions that are either reentrant or not interruptible by signals; .CR fpathconf() is also added to this list and marked as an extension; .CR ustat() is removed from the list, as this function is withdrawn from the interface definition. It is no longer specified whether .CR abort() , .CR chroot(), .CR exit() , and .CR longjmp() also fall into this category of functions. .TP 3 \(bu The APPLICATION USAGE section is added. Most of this text is moved from the DESCRIPTION SECTION in Issue 3. .TP 3 \(bu The FUTURE DIRECTIONS section is added. .RE .SH Issue 4, Version 2 The following changes are incorporated for X/OPEN UNIX conformance: .RS .TP 3 \(bu The DESCRIPTION describes .CR sa_sigaction , the member of the sigaction structure that is the signal-catching function. .TP 3 \(bu The DESCRIPTION describes the .CR SA_ONSTACK , .CR SA_RESETHAND , .CR SA_RESTART , .CR SA_SIGINFO , .CR SA_NOCLDWAIT , and .CR SA_NODEFER settings of .IR sa_flags . The text describes the implications of the use of .CR SA_SIGINFO for the number of arguments passed to the signal-catching function. The text also describes the effects of the .CR SA_NODEFER and .CR SA_RESETHAND flags on the delivery of a signal and on the permanence of an installed action. .TP 3 \(bu The DESCRIPTION specifies the effect if the action for the .CR SIGCHLD signal is set to .CR SIG_IGN . .TP 3 \(bu In the DESCRIPTION, additional text describes the effect if the action is a pointer to a function. A new bullet covers the case where .CR SA_SIGINFO is set . .CR SIGBUS is given as an additional signal for which the behaviour of a process is undefined following a normal return from the signal-catching function. .TP 3 \(bu The APPLICATION USAGE section is updated to describe use of an alternate signal stack; resumption of the process receiving the signal; coding for compatibility with POSIX.4-1993; and implementation of signal-handling functions in BSD. .RE .\" $Header: sigaction.2,v 76.1 95/07/07 14:52:21 ssa Exp $ .TA s .TH sigaction 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH DESCRIPTION More details on the semantics of specific signals can be found in the .IR signal (5) manual entry. .\" NOTE: We may want to edit this too!! .RS .TP 15 .C SIG_DFL Upon receipt of the signal .I sig, the default action (specified on .IR signal (5)) is performed. .RE .SH ERRORS .RS .TP 15 [EFAULT] .IR act or .IR oact points to an invalid address. The reliable detection of this error is implementation dependent. .RE .SH AUTHOR .C sigaction() was derived from the .SM IEEE POSIX 1003.1-1988 Standard. .SH SEE ALSO ptrace(2), sigpending(2), sigspace(2), sigsetops(3C). .SH STANDARDS CONFORMANCE .CR sigaction() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4sigaction()\f1 \- examine and change signal action@@@\f3sigaction(2)\f1 .\" index@\f1examine and change signal action@@@\f3sigaction(2)\f1 .\" index@\f1change or examine signal action@@@\f3sigaction(2)\f1 .\" index@\f1signal action, examine and change@@@\f3sigaction(2)\f1 .\" .\" toc@\f3sigaction(2)\f1:\0\0\f4sigaction()\f1@@@examine and change signal action .\" $Header: sigaltstack.2,v 76.2 95/07/07 14:53:01 ssa Exp $ .TA s .TH sigaltstack 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigaltstack \- set and/or get signal alternate stack context. .SH SYNOPSIS .\" UX .C "#include " .PP .C "int sigaltstack(const stack_t *ss, stack_t *oss);" .\" ? .SH DESCRIPTION The .CR sigaltstack() function allows a process to define an examine the state of an alternate stack for signal handlers. Signals that have been explicitly declared to execute on the alternate stack will be delivered on the alternate stack. .PP If .IR ss is not a null pointer, it points to a .CR stack_t structure that specifies the alternate signal stack that will take effect upon return from .CR sigaltstack() . The .IR ss_flags member specifies the new stack state. If it is set to .CR SS_DISABLE , the stack is disabled and .IR ss_sp and .IR ss_size are ignored. Otherwise the stack will be enabled, and the .IR ss_sp and .IR ss_size members specify the new address and size of the stack. .PP The range of addresses starting at .IR ss_sp , up to but not including .IR ss_sp+ss_size , is available to the implementation for use as the stack. This interface makes no assumptions regarding which end is the stack base and in which direction the stack grows as items are pushed. .PP If .IR oss is not a null pointer, on successful completion it will point to a .CR stack_t structure that specifies the alternate signal stack that was in effect prior to the call to .CR sigaltstack() . The .IR ss_sp and .IR ss_size members specify the address and size of that stack. The .IR ss_flags member specifies the stack's state, and may contain one of the following values: .RS .TP 25 SS_ONSTACK The process is currently executing on the alternate signal stack. Attempts to modify the alternate signal stack while the process is executing on it fails. This flag must not be modified by processes. .TP SS_DISABLE The alternate signal stack is currently disabled. .RE .PP The value .CR SIGSTKSZ is a system default specifying the number of bytes that would be used to cover the usual case when manually allocating an alternate stack area. The value .CR MINSIGSTKSZ is defined to be the minimum stack size for a signal handler. In computing an alternate stack size, a program should add that amount to its stack requirements to allow for the system implementation overhead. The constants .CR SS_ONSTACK , SS_DISABLE , SIGSTKSZ , and .CR MINSIGSTKSZ are defined in .CR . .PP After a successful call to one of the .CR exec functions, there are no alternate signal stacks in the new process image. .SH RETURN VALUE Upon successful completion, .CR sigaltstack() returns 0. Otherwise, it returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS The .CR sigaltstack() function will fail if: .RS .TP 25 [EINVAL] The .IR ss argument is not a null pointer, and the .IR ss_flags member pointed to by .IR ss contains flags other than .CR SS_DISABLE . .TP [ENOMEM] The size of the alternate stack area is less than .CR MINSIGSTKSZ . .TP [EPERM] An attempt was made to modify an active stack. .SH APPLICATION USAGE The following code fragment illustrates a method for allocating memory for an alternate stack: .RE .PP .RS .C "if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL)" .RS .C "/* error return */" .RE .C "sigstk.ss_size = SIGSTKSZ;" .C "sigstk.ss_flags = 0;" .C "if (sigaltstack(&sigstk,(stack_t *)0) < 0)" .RS .C "perror("sigaltstack")O" .RE .RE .PP In some implementations, a signal (whether or not indicated to execute on the alternate stack) will always execute on the alternate stack if it is delivered while another signal is being caught using the alternate stack. .PP On some implementations, stack space is automatically extended as needed. On those implementations, automatic extension is typically not available for an alternate stack. If the stack overflows, the behaviour is undefined. .SH SEE ALSO sigaction(), sigsetjmp(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4sigaltstack()\f1 \- set and/or get signal alternate stack context@@@\f3sigaltstack(2)\f1 .\" index@\f1set and/or get signal alternate stack context@@@\f3sigaltstack(2)\f1 .\" index@\f1set signal alternate stack context@@@\f3sigaltstack(2)\f1 .\" index@\f1get signal alternate stack context@@@\f3sigaltstack(2)\f1 .\" index@\f1signal alternate stack context, set and/or get@@@\f3sigaltstack(2)\f1 .\" index@\f1alternate stack context, set/get signal alternate stack context@@@\f3sigaltstack(2)\f1 .\" index@\f1stack context, set/get signal alternate stack context@@@\f3sigaltstack(2)\f1 .\" .\" toc@\f3sigaltstack(2)\f1:\0\0\f4sigaltstack()\f1@@@set and/or get signal alternate stack context .\" .\" fileset_database@sigalstack.2 .\" $Header: sigblock.2,v 72.4 94/09/06 15:06:01 ssa Exp $ .TA s .TH sigblock 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigblock \- block signals .SH SYNOPSIS .C "#include " .PP .C long sigblock(long mask); .SH DESCRIPTION .C sigblock() causes the signals specified in .I mask to be added to the set of signals currently being blocked from delivery. Signal .I i is blocked if the .IR i -th bit in .I mask is .CR 1 , as specified with the macro .CR sigmask(\f2i\fP) . .PP It is not possible to block signals that cannot be ignored, as documented in .IR signal (5); this restriction is silently imposed by the system. .PP Use .C sigsetmask() to set the mask absolutely (see .IR sigsetmask (2)). .SH RETURN VALUE .C sigblock() returns the previous set of masked signals. .SH EXAMPLES The following call to .C sigblock() adds the .C SIGUSR1 and .C SIGUSR2 signals to the mask of signals currently blocked for the process: .IP .C long oldmask; .IP .C "oldmask = sigblock (sigmask (SIGUSR1) | sigmask (SIGUSR2));" .SH WARNINGS Do not use .C sigblock() in conjunction with the facilities described under .IR sigset (2V). .SH AUTHOR .C sigblock() was developed by the University of California, Berkeley. .SH SEE ALSO kill(2), sigprocmask(2), sigsetmask(2), sigvector(2). .\" index@\f4sigblock()\fP \(mi block signals@@@\f3sigblock(2)\f1 .\" index@block signals@@@\f3sigblock(2)\f1 .\" index@ignore signals@@@\f3sigblock(2)\f1 .\" index@signals, block@@@\f3sigblock(2)\f1 .\" .\" toc@\f3sigblock(2)\f1:\0\0\f4sigblock()\fP@@@block signals .\" $Header: signal.2,v 76.2 95/07/24 16:18:01 ssa Exp $ .TA s .TH signal 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME signal, sigset, sighold, sigrelse, sigignore, sigpause \-signal management .SH SYNOPSIS .C "#include " .PP .C "void (*signal(int sig, void (*func)(int)))(int);" .PP .C "int sighold(int sig);" .PP .C "int sigignore(int sig);" .PP .C "int sigpause(int sig);" .PP .C "int sigrelse(int sig);" .PP .C "void (*sigset(int sig, void (*disp)(int)))(int);" .SH DESCRIPTION The .CR signal() function chooses one of three ways in which receipt of the signal number .IR sig is to be subsequently handled. If the value of func is .CR SIG_DFL , default handling for that signal will occur. If the value of .IR func is .CR SIG_IGN , the signal will be ignored. Otherwise, .IR func must point to a function to be called when that signal occurs. Such a function is called a signal handler. .PP When a signal occurs, if .IR func points to a function, first the equivalent of a: .IP .C signal(sig, SIG_DFL); .PP is executed or an implementation-dependent blocking of the signal is performed. (If the value of .IR sig is .CR SIGILL , whether the reset to .CR SIG_DFL occurs is implementation-dependent.) Next the equivalent of: .IP .C (*func)(sig); .PP is executed. The .IR func function may terminate by executing a return statement or by calling .CR abort() , .CR exit() , or .CR longjmp() . If .CR func() executes a return statement and the value of .IR sig was .CR SIGFPE or any other implementation-dependent value corresponding to a computational exception, the behaviour is undefined. Otherwise, the program will resume execution at the point it was interrupted. .PP If the signal occurs other than as the result of calling .CR abort() , .CR kill() or .CR raise() , the behaviour is undefined if the signal handler calls any function in the standard library other than one of the functions listed on the .I sigaction() page or refers to any object with static storage duration other than by assigning a value to a static storage duration variable of type volatile .IR sig_atomic_t . Furthermore, if such a call fails, the value of .CR errno is indeterminate. .PP At program startup, the equivalent of: .IP .C signal(sig, SIG_IGN); .PP is executed for some signals, and the equivalent of: .IP .C signal(sig, SIG_DFL); .PP is executed for all other signals (see .CR exec ). .PP The .CR sigset() , .CR sighold() , .CR sigignore() , .CR sigpause() and .CR segrelse() functions provide simplified signal management. .PP The .CR sigset() function is used to modify signal dispositions. The .IR sig argument specifies the signal, which may be any signal except .CR SIGKILL and .CR SIGSTOP . The .IR disp argument specifies the signal's disposition, which may be .CR SIG_DFL , .CR SIG_IGN or the address of a signal handler. If .CR sigset() is used, and .IR disp is the address of a signal handler, the system will add .IR sig to the calling process' signal mask before executing the signal handler; when the signal handler returns, the system will restore the calling process' signal mask to its state prior the delivery of the signal. In addition, if .CR sigset() is used, and .IR disp is equal to .CR SIG_HOLD , .IR sig will be added to the calling process' signal mask and .IR sig 's disposition will remain unchanged. If .CR sigset() is used, and .IR disp is not equal to .CR SIG_HOLD , .IR sig will be removed from the calling process' signal mask. .PP The .CR sighold() function adds .IR sig to the calling process' signal mask. .PP The .CR sigrelse() function removes .IR sig from the calling process' signal mask. .PP The .CR sigignore() function sets the disposition of .IR sig to .CR SIG_IGN . .PP The sigpause() function removes .IR sig from the calling process' signal mask and suspends the calling process until a signal is received. .PP If the action for the .CR SIGCHLD signal is set to .CR SIG_IGN , child processes of the calling processes will not be transformed into zombie processes when they terminate. If the calling process subsequently waits for its children, and the process has no unwaited for children that were transformed into zombie processes, it will block until all of its children terminate, and .CR wait() , .CR wait3() , .CR waitid() and .CR waitpid() will fail and set .CR errno to .CR ECHILD . .SH RETURN VALUE If the request can be honoured, .CR signal() returns the value of .CR func() for the most recent call to .CR signal() for the specified signal .IR sig . Otherwise, .CR SIG_ERR is returned and a positive value is stored in .CR errno . .PP Upon successful completion, .CR sigset() returns .CR SIG_HOLD if the signal had been blocked and the signal's previous disposition if it had not been blocked. Otherwise, .CR SIG_ERR is returned and .CR errno is set to indicate the error. .PP For all other functions, upon successful completion, 0 is returned. Otherwise, \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR signal() function will fail if: .RS .TP 15 [EINVAL] The .IR sig argument is not a valid signal number or an attempt is made to catch a signal that cannot be caught or ignore a signal that cannot be ignored. .RE .PP The .CR signal() function may fail if: .RS .TP 15 [EINVAL] An attempt was made to set the action to .CR SIG_DFL for a signal that cannot be caught or ignored (or both). .RE .PP The .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() functions will fail if: .RS .TP 15 [EINVAL] The .IR sig argument is an illegal signal number. .RE .PP The .CR sigset() , and .CR sigignore() functions will fail if: .RS .TP 15 [EINVAL] An attempt is made to catch a signal that cannot be caught, or to ignore a signal that cannot be ignored. .RE .SH APPLICATION USAGE The .CR sigaction() function provides a more comprehensive and reliable mechanism for controlling signals; new applications should use .CR sigaction() rather than .CR signal() . .PP The .CR sighold() function, in conjunction with .CR sigrelse() or .CR sigpause() , may be used to establish critical regions of code that require the delivery of a signal to be temporarily deferred. .PP The .CR sigsuspend() function should be used in preference to .CR sigpause() for broader portability. .SH SEE ALSO exec, pause(), sigaction(), waitid(), . .SH CHANGE HISTORY First released in Issue 1. .PP Derived from Issue 1 of the SVID. .SH Issue 4 The following changes are incorporated for alignment with the ISO C standard: .RS .TP 10 \- The function is no longer marked as an extension. .TP \- The argument int is added to the definition of .CR func() in the SYNOPSIS section. .TP \- In Issue 3, this interface cross-referred to .CR sigaction() . This issue provides a complete description of the function as defined in ISO C standard. .RE .PP Another change is incorporated as follows: .RS .TP 10 \- The APPLICATION USAGE section is added. .SH Issue 4, Version 2 The following changes are incorporated for X/OPEN UNIX conformance: .RS .TP 10 \- The .CR sighold() , .CR sigignore() , .CR sigpause() , .CR sigrelse() , and .CR sigset() functions are added to the SYNOPSIS. .TP \- The DESCRIPTION is updated to describe semantics of the above interfaces. .TP \- Additional text is added to the RETURN VALUE section to describe possible returns from the .CR sigset() function specifically, and all of the above functions in general. .TP \- The ERRORS section is restructured to describe possible error returns from each of the above functions individually. .TP \- The APPLICATION USAGE section is updated to describe certain programming considerations associated with the X/OPEN UNIX functions. .\" $Header: signal.2,v 76.2 95/07/24 16:18:01 ssa Exp $ .TA s .TH signal 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH SYNOPSIS .PP .C "void (*signal(int sig, void (*action)(int)))(int);" .PP .C "void (*sigset(int sig, void (*func)(int)))(int);" .PP .SH DESCRIPTION .PP The system defines a set of signals that can be delivered to a process. The set of signals is defined in .IR signal (5), along with the meaning and side effects of each signal. An alternate mechanism for handling these signals is defined here. The facilities described here should not be used in conjunction with the other facilities described under .CR signal(2) , .CR sigvector(2) , .CR sigblock(2) , .CR sigsetmask(2) , .CR sigpause(2) , and .CR sigspace(2) . .PP Acceptable values for .I sig are defined in .CR . .PP .RS .TP 12 .C SIG_DFL Execute the default action, which varies depending on the signal. The default action for most signals is to terminate the process (see .IR signal (5)). .IP A pending signal is discarded (whether or not it is blocked) if .I action is set to .C SIG_DFL but the default action of the pending signal is to ignore the signal (as in the case of .CR SIGCLD ). .TP .C SIG_IGN Ignore the signal. .br When .C signal() is called with .I action set to .C SIG_IGN and an instance of the signal .I sig is pending, the pending signal is discarded, whether or not it is blocked. .IP .C SIGKILL and .C SIGSTOP signals cannot be ignored. .TP .I address Catch the signal. .br Upon receipt of signal .IR sig , reset the value of .I action for the caught signal to .SM SIG_DFL (except signals marked with "not reset when caught"; see .IR signal (5)), call the signal-catching function to which .IR address points, and resume executing the receiving process at the point where it was interrupted. .IP The signal-catching function is called with the following three parameters: .RS .RS .TP 8 .I sig The signal number. .TP .I code A word of information usually provided by the hardware. .TP .I scp A pointer to the machine-dependent structure .I sigcontext defined in .RC < signal.h >. .RE .RE .IP The pointer .I scp is valid only during the context of the signal-catching function. The structure pointer .I scp is always defined. .IP The .I code word is always zero for all signals except .C SIGILL and .CR SIGFPE . For .CR SIGILL , .I code has the following values: .RS .RS .TP 8 .C 8 illegal instruction trap; .PD 0 .TP .C 9 break instruction trap; .TP .C 10 privileged operation trap; .TP .C 11 privileged register trap. .RE .PD .PP For .CR SIGFPE , .I code has the following values: .RS .TP 8 .C 12 overflow trap; .PD 0 .TP .C 13 conditional trap; .TP .C 14 assist exception trap; .TP .C 22 assist emulation trap. .RE .PD .PP As defined by the .SM IEEE POSIX Standard, .SM HP-UX does not raise an exception on floating-point divide by zero. The result of floating-point divide by zero is infinity which can be checked by .IR isinf (3M). .PP The signals .C SIGKILL and .C SIGSTOP cannot be caught. .RE .PP .CR sigset() allows the calling process to choose one of four ways to handle the receipt of a specific signal. .IR sig specifies the signal and .IR func specifies the choice. .PP .IR sig can be any one of the signals described under .IR signal (5) except .CR SIGKILL or .CR SIGSTOP . .PP .IR func is assigned one of four values: .CR SIG_DFL , .CR SIG_IGN , .CR SIG_HOLD , or a function address. The actions prescribed by .CR SIG_DFL and .CR SIG_IGN are described under .IR signal (5). The action prescribed by .CR SIG_HOLD and function address are described below: .RS .TP 25 .C SIG_HOLD Hold signal. The signal .IR sig is held upon receipt. Any pending signal of this signal type remains held. Only one signal of each type is held. Note: the signals .CR SIGKILL , .CR SIGCONT , and .CR SIGSTOP cannot be held. .TP 5 function address Catch signal. .IR func must be a pointer to a function, the signal\- catching handler, that is called when signal .IR sig occurs. .CR sigset() specifies that the process calls this function upon receipt of signal .IR sig . Any pending signal of this type is released. This handler address is retained across calls to the other signal management functions listed here. Upon receipt of signal .IR sig , the receiving process executes the signal\-catching function pointed to by .IR func as described under .IR signal (5) with the following differences: .PP Before calling the signal\-catching handler, the system signal action of .IR sig is set to .CR SIG_HOLD . During a normal return from the signal\-catching handler, the system signal action is restored to .IR func and any held signal of this type is released. If a non\-local goto .RC ( longjmp(3C) ) is taken, .CR sigrelse() must be called to restore the system signal action to .IR func and release any held signal of this type. .RE .PP .CR sighold() holds the signal .IR sig . .CR sigrelse() restores the system signal action of .IR sig to that specified previously by .CR sigset() . .CR sighold() and .CR sigrelse() are used to establish critical regions of code. .CR sighold() is analogous to raising the priority level and deferring or holding a signal until the priority is lowered by .CR sigrelse() . .PP .CR sigignore() sets the action for signal .IR sig to .CR SIG_IGN (see .IR signal (5)). .PP .CR sigpause() suspends the calling process until it receives an unblocked signal. If the signal .IR sig is held, it is released before the process pauses. .CR sigpause() is useful for testing variables that are changed when a signal occurs. For example, .CR sighold() should be used to block the signal first, then test the variables. If they have not changed, call .CR sigpause() to wait for the signal. .PP These functions can be linked into a program by giving the \-lV3 option to the .CR ld command (see .IR ld (1)). .SH ERRORS .CR sigset() fails and the system signal action for .IR sig is not changed if any of the following occur: .RS .TP 25 [EFAULT] The .IR func argument points to memory that is not a valid part of the process address space. Reliable detection of this error is implementation\-dependent. .RE .PP .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() fail and the system signal action for .IR sig is not changed if any of the following occur: .RS .TP 25 [EINVAL] An attempt is made to ignore, hold, or supply a handler for a signal that cannot be ignored, held, or caught; see .IR signal (5). .RE .PP .CR sigpause returns when the following occurs: .RS .TP 25 [EINTR] A signal was caught. .RE .SH EXAMPLES The following call to .C signal() sets up a signal-catching function for the .C SIGINT signal: .IP .C void myhandler(); .IP .C (void) signal(SIGINT, myhandler); .SH WARNINGS .C signal() should not be used in conjunction with the facilities described under .IR bsdproc (2), .IR sigaction (2), .IR sigset (2V), or .IR sigvector (2). .PP .C signal() does not detect an invalid value for .IR action , and if it does not equal .C SIG_DFL or .CR SIG_IGN, or point to a valid function address, subsequent receipt of the signal .IR sig causes undefined results. .RE .SH AUTHOR .C signal() was developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO kill(1), init(1M), exit(2), kill(2), lseek(2), pause(2), sigaction(2), sigvector(2), wait(2), abort(3C), setjmp(3C), signal(5). .SH STANDARDS CONFORMANCE .CR signal() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4signal()\f1 \- specify what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f4sigset()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sighold()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sigrelse()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sigignore()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f1specify what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f1define what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f1receipt of a signal, define what to do upon@@@\f3signal(2)\f1 .\" index@\f1signal, define what to do upon receipt of a@@@\f3signal(2)\f1 .\" .\" toc@\f3signal(2)\f1:\0\0\f4signal()\f1, \f4sigset()\f1, \f4sighold()\f1, \f4sigrelse()\1, \f4sigignore()\f1, \f4sigpause\f1@@@signal management .\" toc@\f4sigset()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sighold()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigrelse()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigignore()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigpause()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" .\" links@signal.2 sigset.2 .\" links@signal.2 sighold.2 .\" links@signal.2 sigrelse.2 .\" links@signal.2 sigignore.2 .\" $Header: sigset.2v,v 72.4 94/11/14 15:26:38 ssa Exp $ .TA s .TH sigset 2V .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigset, sighold, sigrelse, sigignore, sigpause \- signal management .SH SYNOPSIS .C "#include " .PP .C "void (*sigset(int sig, void (*func)(int)))(int);" .PP .C "int sighold(int sig);" .PP .C "int sigrelse(int sig);" .PP .C "int sigignore(int sig);" .PP .C "int sigpause(int sig);" .SH DESCRIPTION The system defines a set of signals that can be delivered to a process. The set of signals is defined in .IR signal (5), along with the meaning and side effects of each signal. An alternate mechanism for handling these signals is defined here. The facilities described here should not be used in conjunction with the other facilities described under .IR signal (2), .IR sigvector (2), .IR sigblock (2), .IR sigsetmask (2), .IR sigpause (2) and .IR sigspace (2). .PP .C sigset() allows the calling process to choose one of four ways to handle the receipt of a specific signal. .IR sig specifies the signal and .IR func specifies the choice. .PP .I sig can be any one of the signals described under .IR signal (5) except .C SIGKILL or .CR SIGSTOP . .PP .I func is assigned one of four values: .CR SIG_DFL , .CR SIG_IGN , .CR SIG_HOLD , or a .IR "function address" . The actions prescribed by .C SIG_DFL and .C SIG_IGN are described under .IR signal (5). The action prescribed by .C SIG_HOLD and .IR "function address" are described below: .TP 15 .C SIG_HOLD Hold signal. .br The signal .IR sig is held upon receipt. Any pending signal of this signal type remains held. Only one signal of each type is held. .IP Note: the signals .CR SIGKILL , .CR SIGCONT , and .C SIGSTOP cannot be held. .PD .TP 15 .I function address Catch signal. .br .IR func must be a pointer to a function, the signal-catching handler, that is called when signal .IR sig occurs. .C sigset() specifies that the process calls this function upon receipt of signal .IR sig . Any pending signal of this type is released. This handler address is retained across calls to the other signal management functions listed here. Upon receipt of signal .IR sig , the receiving process executes the signal-catching function pointed to by .IR func as described under .IR signal (5) with the following differences: .IP Before calling the signal-catching handler, the system signal action of .IR sig is set to .CR SIG_HOLD . During a normal return from the signal-catching handler, the system signal action is restored to .IR func and any held signal of this type is released. If a non-local goto .IR (longjmp (3C)) is taken, .C sigrelse() must be called to restore the system signal action to .IR func and release any held signal of this type. .PP .C sighold() holds the signal .IR sig. .C sigrelse() restores the system signal action of .IR sig to that specified previously by .CR sigset() . .C sighold() and .C sigrelse() are used to establish critical regions of code. .C sighold() is analogous to raising the priority level and deferring or holding a signal until the priority is lowered by .CR sigrelse() . .PP .C sigignore() sets the action for signal .IR sig to .C SIG_IGN (see .IR signal (5)). .PP .C sigpause() suspends the calling process until it receives an unblocked signal. If the signal .I sig is held, it is released before the process pauses. .C sigpause() is useful for testing variables that are changed when a signal occurs. For example, .C sighold() should be used to block the signal first, then test the variables. If they have not changed, call .C sigpause() to wait for the signal. .PP These functions can be linked into a program by giving the .C \-lV3 option to the .C ld command (see .IR ld (1)). .SH RETURN VALUE Upon successful completion, .C sigset() returns the previous value of the system signal action for the specified signal .IR sig . Otherwise, a value of .C SIG_ERR is returned and .C errno is set to indicate the error. .C SIG_ERR is defined in .RC < signal.h >. .PP For the other functions, a 0 value indicates that the call succeeded. A \-1 return value indicates an error occurred and .C errno is set to indicate the reason. .SH ERRORS .C sigset() fails and the system signal action for .I sig is not changed if any of the following occur: .RS .TP 20 [EFAULT] The .I func argument points to memory that is not a valid part of the process address space. Reliable detection of this error is implementation dependent. .RE .PP .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() fail and the system signal action for .I sig is not changed if any of the following occur: .RS .TP 20 .SM [EINVAL] .I sig is not a valid signal number. .TP .SM [EINVAL] An attempt is made to ignore, hold, or supply a handler for a signal that cannot be ignored, held, or caught; see .IR signal (5). .RE .PP .IR sigpause returns when the following occurs: .RS .TP 20 .SM [EINTR] A signal was caught. .RE .SH WARNINGS These signal facilities should not be used in conjunction with .IR bsdproc (2), .IR signal (2), .IR sigvector (2), .IR sigblock (2), .IR sigsetmask (2), .IR sigpause (2) and .IR sigspace (2). .SH SEE ALSO kill(1), kill(2), signal(2), pause(2), wait(2), abort(3C), setjmp(3C), signal(5). .SH STANDARDS CONFORMANCE .CR sigset() ": SVID2, SVID3" .PP .CR sighold() ": SVID2, SVID3" .PP .CR sigignore() ": SVID2, SVID3" .PP .CR sigpause() ": SVID2, SVID3" .PP .CR sigrelse() ": SVID2, SVID3" .\" .\" index@\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@signal management (\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP)@@@\f3sigset(2V)\f1 .\" index@management, signal (\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP)@@@\f3sigset(2V)\f1 .\" index@hold signal upon receipt@@@\f3sigset(2V)\f1 .\" index@signal, hold upon receipt@@@\f3sigset(2V)\f1 .\" index@ignore signal@@@\f3sigset(2V)\f1 .\" index@signal, ignore@@@\f3sigset(2V)\f1 .\" index@restore signal action@@@\f3sigset(2V)\f1 .\" index@signal, restore action@@@\f3sigset(2V)\f1 .\" index@signal, suspend calling process until received@@@\f3sigset(2V)\f1 .\" index@signal, select method of handling@@@\f3sigset(2V)\f1 .\" .\" toc@\f3sigset(2V)\f1:\0\0\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP@@@signal management .\" toc@\f4sighold()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigrelse()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigignore()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigpause()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" .\" links@sigset.2v sighold.2v .\" links@sigset.2v sigrelse.2v .\" links@sigset.2v sigignore.2v .\" links@sigset.2v sigpause.2v .\" .\" fileset_database@sigset.2v PROGRAMING-MAN .\" $Header: signal.2,v 76.2 95/07/24 16:18:01 ssa Exp $ .TA s .TH signal 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME signal, sigset, sighold, sigrelse, sigignore, sigpause \-signal management .SH SYNOPSIS .C "#include " .PP .C "void (*signal(int sig, void (*func)(int)))(int);" .PP .C "int sighold(int sig);" .PP .C "int sigignore(int sig);" .PP .C "int sigpause(int sig);" .PP .C "int sigrelse(int sig);" .PP .C "void (*sigset(int sig, void (*disp)(int)))(int);" .SH DESCRIPTION The .CR signal() function chooses one of three ways in which receipt of the signal number .IR sig is to be subsequently handled. If the value of func is .CR SIG_DFL , default handling for that signal will occur. If the value of .IR func is .CR SIG_IGN , the signal will be ignored. Otherwise, .IR func must point to a function to be called when that signal occurs. Such a function is called a signal handler. .PP When a signal occurs, if .IR func points to a function, first the equivalent of a: .IP .C signal(sig, SIG_DFL); .PP is executed or an implementation-dependent blocking of the signal is performed. (If the value of .IR sig is .CR SIGILL , whether the reset to .CR SIG_DFL occurs is implementation-dependent.) Next the equivalent of: .IP .C (*func)(sig); .PP is executed. The .IR func function may terminate by executing a return statement or by calling .CR abort() , .CR exit() , or .CR longjmp() . If .CR func() executes a return statement and the value of .IR sig was .CR SIGFPE or any other implementation-dependent value corresponding to a computational exception, the behaviour is undefined. Otherwise, the program will resume execution at the point it was interrupted. .PP If the signal occurs other than as the result of calling .CR abort() , .CR kill() or .CR raise() , the behaviour is undefined if the signal handler calls any function in the standard library other than one of the functions listed on the .I sigaction() page or refers to any object with static storage duration other than by assigning a value to a static storage duration variable of type volatile .IR sig_atomic_t . Furthermore, if such a call fails, the value of .CR errno is indeterminate. .PP At program startup, the equivalent of: .IP .C signal(sig, SIG_IGN); .PP is executed for some signals, and the equivalent of: .IP .C signal(sig, SIG_DFL); .PP is executed for all other signals (see .CR exec ). .PP The .CR sigset() , .CR sighold() , .CR sigignore() , .CR sigpause() and .CR segrelse() functions provide simplified signal management. .PP The .CR sigset() function is used to modify signal dispositions. The .IR sig argument specifies the signal, which may be any signal except .CR SIGKILL and .CR SIGSTOP . The .IR disp argument specifies the signal's disposition, which may be .CR SIG_DFL , .CR SIG_IGN or the address of a signal handler. If .CR sigset() is used, and .IR disp is the address of a signal handler, the system will add .IR sig to the calling process' signal mask before executing the signal handler; when the signal handler returns, the system will restore the calling process' signal mask to its state prior the delivery of the signal. In addition, if .CR sigset() is used, and .IR disp is equal to .CR SIG_HOLD , .IR sig will be added to the calling process' signal mask and .IR sig 's disposition will remain unchanged. If .CR sigset() is used, and .IR disp is not equal to .CR SIG_HOLD , .IR sig will be removed from the calling process' signal mask. .PP The .CR sighold() function adds .IR sig to the calling process' signal mask. .PP The .CR sigrelse() function removes .IR sig from the calling process' signal mask. .PP The .CR sigignore() function sets the disposition of .IR sig to .CR SIG_IGN . .PP The sigpause() function removes .IR sig from the calling process' signal mask and suspends the calling process until a signal is received. .PP If the action for the .CR SIGCHLD signal is set to .CR SIG_IGN , child processes of the calling processes will not be transformed into zombie processes when they terminate. If the calling process subsequently waits for its children, and the process has no unwaited for children that were transformed into zombie processes, it will block until all of its children terminate, and .CR wait() , .CR wait3() , .CR waitid() and .CR waitpid() will fail and set .CR errno to .CR ECHILD . .SH RETURN VALUE If the request can be honoured, .CR signal() returns the value of .CR func() for the most recent call to .CR signal() for the specified signal .IR sig . Otherwise, .CR SIG_ERR is returned and a positive value is stored in .CR errno . .PP Upon successful completion, .CR sigset() returns .CR SIG_HOLD if the signal had been blocked and the signal's previous disposition if it had not been blocked. Otherwise, .CR SIG_ERR is returned and .CR errno is set to indicate the error. .PP For all other functions, upon successful completion, 0 is returned. Otherwise, \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR signal() function will fail if: .RS .TP 15 [EINVAL] The .IR sig argument is not a valid signal number or an attempt is made to catch a signal that cannot be caught or ignore a signal that cannot be ignored. .RE .PP The .CR signal() function may fail if: .RS .TP 15 [EINVAL] An attempt was made to set the action to .CR SIG_DFL for a signal that cannot be caught or ignored (or both). .RE .PP The .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() functions will fail if: .RS .TP 15 [EINVAL] The .IR sig argument is an illegal signal number. .RE .PP The .CR sigset() , and .CR sigignore() functions will fail if: .RS .TP 15 [EINVAL] An attempt is made to catch a signal that cannot be caught, or to ignore a signal that cannot be ignored. .RE .SH APPLICATION USAGE The .CR sigaction() function provides a more comprehensive and reliable mechanism for controlling signals; new applications should use .CR sigaction() rather than .CR signal() . .PP The .CR sighold() function, in conjunction with .CR sigrelse() or .CR sigpause() , may be used to establish critical regions of code that require the delivery of a signal to be temporarily deferred. .PP The .CR sigsuspend() function should be used in preference to .CR sigpause() for broader portability. .SH SEE ALSO exec, pause(), sigaction(), waitid(), . .SH CHANGE HISTORY First released in Issue 1. .PP Derived from Issue 1 of the SVID. .SH Issue 4 The following changes are incorporated for alignment with the ISO C standard: .RS .TP 10 \- The function is no longer marked as an extension. .TP \- The argument int is added to the definition of .CR func() in the SYNOPSIS section. .TP \- In Issue 3, this interface cross-referred to .CR sigaction() . This issue provides a complete description of the function as defined in ISO C standard. .RE .PP Another change is incorporated as follows: .RS .TP 10 \- The APPLICATION USAGE section is added. .SH Issue 4, Version 2 The following changes are incorporated for X/OPEN UNIX conformance: .RS .TP 10 \- The .CR sighold() , .CR sigignore() , .CR sigpause() , .CR sigrelse() , and .CR sigset() functions are added to the SYNOPSIS. .TP \- The DESCRIPTION is updated to describe semantics of the above interfaces. .TP \- Additional text is added to the RETURN VALUE section to describe possible returns from the .CR sigset() function specifically, and all of the above functions in general. .TP \- The ERRORS section is restructured to describe possible error returns from each of the above functions individually. .TP \- The APPLICATION USAGE section is updated to describe certain programming considerations associated with the X/OPEN UNIX functions. .\" $Header: signal.2,v 76.2 95/07/24 16:18:01 ssa Exp $ .TA s .TH signal 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH SYNOPSIS .PP .C "void (*signal(int sig, void (*action)(int)))(int);" .PP .C "void (*sigset(int sig, void (*func)(int)))(int);" .PP .SH DESCRIPTION .PP The system defines a set of signals that can be delivered to a process. The set of signals is defined in .IR signal (5), along with the meaning and side effects of each signal. An alternate mechanism for handling these signals is defined here. The facilities described here should not be used in conjunction with the other facilities described under .CR signal(2) , .CR sigvector(2) , .CR sigblock(2) , .CR sigsetmask(2) , .CR sigpause(2) , and .CR sigspace(2) . .PP Acceptable values for .I sig are defined in .CR . .PP .RS .TP 12 .C SIG_DFL Execute the default action, which varies depending on the signal. The default action for most signals is to terminate the process (see .IR signal (5)). .IP A pending signal is discarded (whether or not it is blocked) if .I action is set to .C SIG_DFL but the default action of the pending signal is to ignore the signal (as in the case of .CR SIGCLD ). .TP .C SIG_IGN Ignore the signal. .br When .C signal() is called with .I action set to .C SIG_IGN and an instance of the signal .I sig is pending, the pending signal is discarded, whether or not it is blocked. .IP .C SIGKILL and .C SIGSTOP signals cannot be ignored. .TP .I address Catch the signal. .br Upon receipt of signal .IR sig , reset the value of .I action for the caught signal to .SM SIG_DFL (except signals marked with "not reset when caught"; see .IR signal (5)), call the signal-catching function to which .IR address points, and resume executing the receiving process at the point where it was interrupted. .IP The signal-catching function is called with the following three parameters: .RS .RS .TP 8 .I sig The signal number. .TP .I code A word of information usually provided by the hardware. .TP .I scp A pointer to the machine-dependent structure .I sigcontext defined in .RC < signal.h >. .RE .RE .IP The pointer .I scp is valid only during the context of the signal-catching function. The structure pointer .I scp is always defined. .IP The .I code word is always zero for all signals except .C SIGILL and .CR SIGFPE . For .CR SIGILL , .I code has the following values: .RS .RS .TP 8 .C 8 illegal instruction trap; .PD 0 .TP .C 9 break instruction trap; .TP .C 10 privileged operation trap; .TP .C 11 privileged register trap. .RE .PD .PP For .CR SIGFPE , .I code has the following values: .RS .TP 8 .C 12 overflow trap; .PD 0 .TP .C 13 conditional trap; .TP .C 14 assist exception trap; .TP .C 22 assist emulation trap. .RE .PD .PP As defined by the .SM IEEE POSIX Standard, .SM HP-UX does not raise an exception on floating-point divide by zero. The result of floating-point divide by zero is infinity which can be checked by .IR isinf (3M). .PP The signals .C SIGKILL and .C SIGSTOP cannot be caught. .RE .PP .CR sigset() allows the calling process to choose one of four ways to handle the receipt of a specific signal. .IR sig specifies the signal and .IR func specifies the choice. .PP .IR sig can be any one of the signals described under .IR signal (5) except .CR SIGKILL or .CR SIGSTOP . .PP .IR func is assigned one of four values: .CR SIG_DFL , .CR SIG_IGN , .CR SIG_HOLD , or a function address. The actions prescribed by .CR SIG_DFL and .CR SIG_IGN are described under .IR signal (5). The action prescribed by .CR SIG_HOLD and function address are described below: .RS .TP 25 .C SIG_HOLD Hold signal. The signal .IR sig is held upon receipt. Any pending signal of this signal type remains held. Only one signal of each type is held. Note: the signals .CR SIGKILL , .CR SIGCONT , and .CR SIGSTOP cannot be held. .TP 5 function address Catch signal. .IR func must be a pointer to a function, the signal\- catching handler, that is called when signal .IR sig occurs. .CR sigset() specifies that the process calls this function upon receipt of signal .IR sig . Any pending signal of this type is released. This handler address is retained across calls to the other signal management functions listed here. Upon receipt of signal .IR sig , the receiving process executes the signal\-catching function pointed to by .IR func as described under .IR signal (5) with the following differences: .PP Before calling the signal\-catching handler, the system signal action of .IR sig is set to .CR SIG_HOLD . During a normal return from the signal\-catching handler, the system signal action is restored to .IR func and any held signal of this type is released. If a non\-local goto .RC ( longjmp(3C) ) is taken, .CR sigrelse() must be called to restore the system signal action to .IR func and release any held signal of this type. .RE .PP .CR sighold() holds the signal .IR sig . .CR sigrelse() restores the system signal action of .IR sig to that specified previously by .CR sigset() . .CR sighold() and .CR sigrelse() are used to establish critical regions of code. .CR sighold() is analogous to raising the priority level and deferring or holding a signal until the priority is lowered by .CR sigrelse() . .PP .CR sigignore() sets the action for signal .IR sig to .CR SIG_IGN (see .IR signal (5)). .PP .CR sigpause() suspends the calling process until it receives an unblocked signal. If the signal .IR sig is held, it is released before the process pauses. .CR sigpause() is useful for testing variables that are changed when a signal occurs. For example, .CR sighold() should be used to block the signal first, then test the variables. If they have not changed, call .CR sigpause() to wait for the signal. .PP These functions can be linked into a program by giving the \-lV3 option to the .CR ld command (see .IR ld (1)). .SH ERRORS .CR sigset() fails and the system signal action for .IR sig is not changed if any of the following occur: .RS .TP 25 [EFAULT] The .IR func argument points to memory that is not a valid part of the process address space. Reliable detection of this error is implementation\-dependent. .RE .PP .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() fail and the system signal action for .IR sig is not changed if any of the following occur: .RS .TP 25 [EINVAL] An attempt is made to ignore, hold, or supply a handler for a signal that cannot be ignored, held, or caught; see .IR signal (5). .RE .PP .CR sigpause returns when the following occurs: .RS .TP 25 [EINTR] A signal was caught. .RE .SH EXAMPLES The following call to .C signal() sets up a signal-catching function for the .C SIGINT signal: .IP .C void myhandler(); .IP .C (void) signal(SIGINT, myhandler); .SH WARNINGS .C signal() should not be used in conjunction with the facilities described under .IR bsdproc (2), .IR sigaction (2), .IR sigset (2V), or .IR sigvector (2). .PP .C signal() does not detect an invalid value for .IR action , and if it does not equal .C SIG_DFL or .CR SIG_IGN, or point to a valid function address, subsequent receipt of the signal .IR sig causes undefined results. .RE .SH AUTHOR .C signal() was developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO kill(1), init(1M), exit(2), kill(2), lseek(2), pause(2), sigaction(2), sigvector(2), wait(2), abort(3C), setjmp(3C), signal(5). .SH STANDARDS CONFORMANCE .CR signal() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4signal()\f1 \- specify what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f4sigset()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sighold()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sigrelse()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sigignore()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f1specify what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f1define what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f1receipt of a signal, define what to do upon@@@\f3signal(2)\f1 .\" index@\f1signal, define what to do upon receipt of a@@@\f3signal(2)\f1 .\" .\" toc@\f3signal(2)\f1:\0\0\f4signal()\f1, \f4sigset()\f1, \f4sighold()\f1, \f4sigrelse()\1, \f4sigignore()\f1, \f4sigpause\f1@@@signal management .\" toc@\f4sigset()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sighold()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigrelse()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigignore()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigpause()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" .\" links@signal.2 sigset.2 .\" links@signal.2 sighold.2 .\" links@signal.2 sigrelse.2 .\" links@signal.2 sigignore.2 .\" $Header: sigset.2v,v 72.4 94/11/14 15:26:38 ssa Exp $ .TA s .TH sigset 2V .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigset, sighold, sigrelse, sigignore, sigpause \- signal management .SH SYNOPSIS .C "#include " .PP .C "void (*sigset(int sig, void (*func)(int)))(int);" .PP .C "int sighold(int sig);" .PP .C "int sigrelse(int sig);" .PP .C "int sigignore(int sig);" .PP .C "int sigpause(int sig);" .SH DESCRIPTION The system defines a set of signals that can be delivered to a process. The set of signals is defined in .IR signal (5), along with the meaning and side effects of each signal. An alternate mechanism for handling these signals is defined here. The facilities described here should not be used in conjunction with the other facilities described under .IR signal (2), .IR sigvector (2), .IR sigblock (2), .IR sigsetmask (2), .IR sigpause (2) and .IR sigspace (2). .PP .C sigset() allows the calling process to choose one of four ways to handle the receipt of a specific signal. .IR sig specifies the signal and .IR func specifies the choice. .PP .I sig can be any one of the signals described under .IR signal (5) except .C SIGKILL or .CR SIGSTOP . .PP .I func is assigned one of four values: .CR SIG_DFL , .CR SIG_IGN , .CR SIG_HOLD , or a .IR "function address" . The actions prescribed by .C SIG_DFL and .C SIG_IGN are described under .IR signal (5). The action prescribed by .C SIG_HOLD and .IR "function address" are described below: .TP 15 .C SIG_HOLD Hold signal. .br The signal .IR sig is held upon receipt. Any pending signal of this signal type remains held. Only one signal of each type is held. .IP Note: the signals .CR SIGKILL , .CR SIGCONT , and .C SIGSTOP cannot be held. .PD .TP 15 .I function address Catch signal. .br .IR func must be a pointer to a function, the signal-catching handler, that is called when signal .IR sig occurs. .C sigset() specifies that the process calls this function upon receipt of signal .IR sig . Any pending signal of this type is released. This handler address is retained across calls to the other signal management functions listed here. Upon receipt of signal .IR sig , the receiving process executes the signal-catching function pointed to by .IR func as described under .IR signal (5) with the following differences: .IP Before calling the signal-catching handler, the system signal action of .IR sig is set to .CR SIG_HOLD . During a normal return from the signal-catching handler, the system signal action is restored to .IR func and any held signal of this type is released. If a non-local goto .IR (longjmp (3C)) is taken, .C sigrelse() must be called to restore the system signal action to .IR func and release any held signal of this type. .PP .C sighold() holds the signal .IR sig. .C sigrelse() restores the system signal action of .IR sig to that specified previously by .CR sigset() . .C sighold() and .C sigrelse() are used to establish critical regions of code. .C sighold() is analogous to raising the priority level and deferring or holding a signal until the priority is lowered by .CR sigrelse() . .PP .C sigignore() sets the action for signal .IR sig to .C SIG_IGN (see .IR signal (5)). .PP .C sigpause() suspends the calling process until it receives an unblocked signal. If the signal .I sig is held, it is released before the process pauses. .C sigpause() is useful for testing variables that are changed when a signal occurs. For example, .C sighold() should be used to block the signal first, then test the variables. If they have not changed, call .C sigpause() to wait for the signal. .PP These functions can be linked into a program by giving the .C \-lV3 option to the .C ld command (see .IR ld (1)). .SH RETURN VALUE Upon successful completion, .C sigset() returns the previous value of the system signal action for the specified signal .IR sig . Otherwise, a value of .C SIG_ERR is returned and .C errno is set to indicate the error. .C SIG_ERR is defined in .RC < signal.h >. .PP For the other functions, a 0 value indicates that the call succeeded. A \-1 return value indicates an error occurred and .C errno is set to indicate the reason. .SH ERRORS .C sigset() fails and the system signal action for .I sig is not changed if any of the following occur: .RS .TP 20 [EFAULT] The .I func argument points to memory that is not a valid part of the process address space. Reliable detection of this error is implementation dependent. .RE .PP .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() fail and the system signal action for .I sig is not changed if any of the following occur: .RS .TP 20 .SM [EINVAL] .I sig is not a valid signal number. .TP .SM [EINVAL] An attempt is made to ignore, hold, or supply a handler for a signal that cannot be ignored, held, or caught; see .IR signal (5). .RE .PP .IR sigpause returns when the following occurs: .RS .TP 20 .SM [EINTR] A signal was caught. .RE .SH WARNINGS These signal facilities should not be used in conjunction with .IR bsdproc (2), .IR signal (2), .IR sigvector (2), .IR sigblock (2), .IR sigsetmask (2), .IR sigpause (2) and .IR sigspace (2). .SH SEE ALSO kill(1), kill(2), signal(2), pause(2), wait(2), abort(3C), setjmp(3C), signal(5). .SH STANDARDS CONFORMANCE .CR sigset() ": SVID2, SVID3" .PP .CR sighold() ": SVID2, SVID3" .PP .CR sigignore() ": SVID2, SVID3" .PP .CR sigpause() ": SVID2, SVID3" .PP .CR sigrelse() ": SVID2, SVID3" .\" .\" index@\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@signal management (\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP)@@@\f3sigset(2V)\f1 .\" index@management, signal (\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP)@@@\f3sigset(2V)\f1 .\" index@hold signal upon receipt@@@\f3sigset(2V)\f1 .\" index@signal, hold upon receipt@@@\f3sigset(2V)\f1 .\" index@ignore signal@@@\f3sigset(2V)\f1 .\" index@signal, ignore@@@\f3sigset(2V)\f1 .\" index@restore signal action@@@\f3sigset(2V)\f1 .\" index@signal, restore action@@@\f3sigset(2V)\f1 .\" index@signal, suspend calling process until received@@@\f3sigset(2V)\f1 .\" index@signal, select method of handling@@@\f3sigset(2V)\f1 .\" .\" toc@\f3sigset(2V)\f1:\0\0\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP@@@signal management .\" toc@\f4sighold()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigrelse()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigignore()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigpause()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" .\" links@sigset.2v sighold.2v .\" links@sigset.2v sigrelse.2v .\" links@sigset.2v sigignore.2v .\" links@sigset.2v sigpause.2v .\" .\" fileset_database@sigset.2v PROGRAMING-MAN .\" $Header: siginterrupt.2,v 76.2 95/07/07 14:54:01 ssa Exp $ .TA s .TH siginterrupt 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME siginterrupt - allow signals to interrupt functions .SH SYNOPSIS .\" UX .PP .C #include .PP .C int siginterrupt(int sig, int flag); .\" ? .SH DESCRIPTION The .CR siginterrupt() function is used to change the restart behaviour when a function is interrupted by the specified signal. The function .CR siginterrupt (\c .IR sig , .IR flag ) has an effect as if implemented as: .PP .C "siginterrupt(int sig, int flag) {" .RS .C "int ret;" .nf .C "struct sigaction act;" .nf .C " " .C "(void) sigaction(sig, NULL, &act);" .nf .C "if (flag)" .RS .C "act.sa_flags &= ~SA_RESTART;" .RE .C "else" .RS .C "act.sa_flags |= SA_RESTART;" .RE .C "ret = sigaction(sig, &act, NULL);" .nf .C "return ret;" .RE .C "}" .PP .SH RETURN VALUE Upon successful completion, .CR siginterrupt() returns 0. Otherwise \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR siginterrupt() function will fail if: .RS .TP 25 [EINVAL] The .IR sig argument is not a valid signal number. .RE .SH APPLICATION USAGE The .CR siginterrupt() function supports programs written to historical system interfaces. A portable application, when being written or rewritten, should use .CR sigaction() with the .CR SA_RESTART flag instead of .CR siginterrupt() . .SH SEE ALSO sigaction(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4siginterrupt()\f1 \- allow signals to interrupt functions@@@\f3siginterrupt(2)\f1 .\" index@\f1allow signals to interrupt functions@@@\f3siginterrupt(2)\f1 .\" index@\f1signals allowed to interrupt functions@@@\f3siginterrupt(2)\f1 .\" index@\f1interrupt functions, allowing signals to@@@\f3siginterrupt(2)\f1 .\" index@\f1functions, allow signals to interrupt@@@\f3siginterrupt(2)\f1 .\" .\" toc@\f3siginterrupt(2)\f1:\0\0\f4siginterrupt()\f1@@@allow signals to interrupt functions .\" .\" fileset_database@siginterrupt.2 PAUX-ENG-A-MAN .\" $Header: signal.2,v 76.2 95/07/24 16:18:01 ssa Exp $ .TA s .TH signal 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME signal, sigset, sighold, sigrelse, sigignore, sigpause \-signal management .SH SYNOPSIS .C "#include " .PP .C "void (*signal(int sig, void (*func)(int)))(int);" .PP .C "int sighold(int sig);" .PP .C "int sigignore(int sig);" .PP .C "int sigpause(int sig);" .PP .C "int sigrelse(int sig);" .PP .C "void (*sigset(int sig, void (*disp)(int)))(int);" .SH DESCRIPTION The .CR signal() function chooses one of three ways in which receipt of the signal number .IR sig is to be subsequently handled. If the value of func is .CR SIG_DFL , default handling for that signal will occur. If the value of .IR func is .CR SIG_IGN , the signal will be ignored. Otherwise, .IR func must point to a function to be called when that signal occurs. Such a function is called a signal handler. .PP When a signal occurs, if .IR func points to a function, first the equivalent of a: .IP .C signal(sig, SIG_DFL); .PP is executed or an implementation-dependent blocking of the signal is performed. (If the value of .IR sig is .CR SIGILL , whether the reset to .CR SIG_DFL occurs is implementation-dependent.) Next the equivalent of: .IP .C (*func)(sig); .PP is executed. The .IR func function may terminate by executing a return statement or by calling .CR abort() , .CR exit() , or .CR longjmp() . If .CR func() executes a return statement and the value of .IR sig was .CR SIGFPE or any other implementation-dependent value corresponding to a computational exception, the behaviour is undefined. Otherwise, the program will resume execution at the point it was interrupted. .PP If the signal occurs other than as the result of calling .CR abort() , .CR kill() or .CR raise() , the behaviour is undefined if the signal handler calls any function in the standard library other than one of the functions listed on the .I sigaction() page or refers to any object with static storage duration other than by assigning a value to a static storage duration variable of type volatile .IR sig_atomic_t . Furthermore, if such a call fails, the value of .CR errno is indeterminate. .PP At program startup, the equivalent of: .IP .C signal(sig, SIG_IGN); .PP is executed for some signals, and the equivalent of: .IP .C signal(sig, SIG_DFL); .PP is executed for all other signals (see .CR exec ). .PP The .CR sigset() , .CR sighold() , .CR sigignore() , .CR sigpause() and .CR segrelse() functions provide simplified signal management. .PP The .CR sigset() function is used to modify signal dispositions. The .IR sig argument specifies the signal, which may be any signal except .CR SIGKILL and .CR SIGSTOP . The .IR disp argument specifies the signal's disposition, which may be .CR SIG_DFL , .CR SIG_IGN or the address of a signal handler. If .CR sigset() is used, and .IR disp is the address of a signal handler, the system will add .IR sig to the calling process' signal mask before executing the signal handler; when the signal handler returns, the system will restore the calling process' signal mask to its state prior the delivery of the signal. In addition, if .CR sigset() is used, and .IR disp is equal to .CR SIG_HOLD , .IR sig will be added to the calling process' signal mask and .IR sig 's disposition will remain unchanged. If .CR sigset() is used, and .IR disp is not equal to .CR SIG_HOLD , .IR sig will be removed from the calling process' signal mask. .PP The .CR sighold() function adds .IR sig to the calling process' signal mask. .PP The .CR sigrelse() function removes .IR sig from the calling process' signal mask. .PP The .CR sigignore() function sets the disposition of .IR sig to .CR SIG_IGN . .PP The sigpause() function removes .IR sig from the calling process' signal mask and suspends the calling process until a signal is received. .PP If the action for the .CR SIGCHLD signal is set to .CR SIG_IGN , child processes of the calling processes will not be transformed into zombie processes when they terminate. If the calling process subsequently waits for its children, and the process has no unwaited for children that were transformed into zombie processes, it will block until all of its children terminate, and .CR wait() , .CR wait3() , .CR waitid() and .CR waitpid() will fail and set .CR errno to .CR ECHILD . .SH RETURN VALUE If the request can be honoured, .CR signal() returns the value of .CR func() for the most recent call to .CR signal() for the specified signal .IR sig . Otherwise, .CR SIG_ERR is returned and a positive value is stored in .CR errno . .PP Upon successful completion, .CR sigset() returns .CR SIG_HOLD if the signal had been blocked and the signal's previous disposition if it had not been blocked. Otherwise, .CR SIG_ERR is returned and .CR errno is set to indicate the error. .PP For all other functions, upon successful completion, 0 is returned. Otherwise, \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR signal() function will fail if: .RS .TP 15 [EINVAL] The .IR sig argument is not a valid signal number or an attempt is made to catch a signal that cannot be caught or ignore a signal that cannot be ignored. .RE .PP The .CR signal() function may fail if: .RS .TP 15 [EINVAL] An attempt was made to set the action to .CR SIG_DFL for a signal that cannot be caught or ignored (or both). .RE .PP The .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() functions will fail if: .RS .TP 15 [EINVAL] The .IR sig argument is an illegal signal number. .RE .PP The .CR sigset() , and .CR sigignore() functions will fail if: .RS .TP 15 [EINVAL] An attempt is made to catch a signal that cannot be caught, or to ignore a signal that cannot be ignored. .RE .SH APPLICATION USAGE The .CR sigaction() function provides a more comprehensive and reliable mechanism for controlling signals; new applications should use .CR sigaction() rather than .CR signal() . .PP The .CR sighold() function, in conjunction with .CR sigrelse() or .CR sigpause() , may be used to establish critical regions of code that require the delivery of a signal to be temporarily deferred. .PP The .CR sigsuspend() function should be used in preference to .CR sigpause() for broader portability. .SH SEE ALSO exec, pause(), sigaction(), waitid(), . .SH CHANGE HISTORY First released in Issue 1. .PP Derived from Issue 1 of the SVID. .SH Issue 4 The following changes are incorporated for alignment with the ISO C standard: .RS .TP 10 \- The function is no longer marked as an extension. .TP \- The argument int is added to the definition of .CR func() in the SYNOPSIS section. .TP \- In Issue 3, this interface cross-referred to .CR sigaction() . This issue provides a complete description of the function as defined in ISO C standard. .RE .PP Another change is incorporated as follows: .RS .TP 10 \- The APPLICATION USAGE section is added. .SH Issue 4, Version 2 The following changes are incorporated for X/OPEN UNIX conformance: .RS .TP 10 \- The .CR sighold() , .CR sigignore() , .CR sigpause() , .CR sigrelse() , and .CR sigset() functions are added to the SYNOPSIS. .TP \- The DESCRIPTION is updated to describe semantics of the above interfaces. .TP \- Additional text is added to the RETURN VALUE section to describe possible returns from the .CR sigset() function specifically, and all of the above functions in general. .TP \- The ERRORS section is restructured to describe possible error returns from each of the above functions individually. .TP \- The APPLICATION USAGE section is updated to describe certain programming considerations associated with the X/OPEN UNIX functions. .\" $Header: signal.2,v 76.2 95/07/24 16:18:01 ssa Exp $ .TA s .TH signal 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH SYNOPSIS .PP .C "void (*signal(int sig, void (*action)(int)))(int);" .PP .C "void (*sigset(int sig, void (*func)(int)))(int);" .PP .SH DESCRIPTION .PP The system defines a set of signals that can be delivered to a process. The set of signals is defined in .IR signal (5), along with the meaning and side effects of each signal. An alternate mechanism for handling these signals is defined here. The facilities described here should not be used in conjunction with the other facilities described under .CR signal(2) , .CR sigvector(2) , .CR sigblock(2) , .CR sigsetmask(2) , .CR sigpause(2) , and .CR sigspace(2) . .PP Acceptable values for .I sig are defined in .CR . .PP .RS .TP 12 .C SIG_DFL Execute the default action, which varies depending on the signal. The default action for most signals is to terminate the process (see .IR signal (5)). .IP A pending signal is discarded (whether or not it is blocked) if .I action is set to .C SIG_DFL but the default action of the pending signal is to ignore the signal (as in the case of .CR SIGCLD ). .TP .C SIG_IGN Ignore the signal. .br When .C signal() is called with .I action set to .C SIG_IGN and an instance of the signal .I sig is pending, the pending signal is discarded, whether or not it is blocked. .IP .C SIGKILL and .C SIGSTOP signals cannot be ignored. .TP .I address Catch the signal. .br Upon receipt of signal .IR sig , reset the value of .I action for the caught signal to .SM SIG_DFL (except signals marked with "not reset when caught"; see .IR signal (5)), call the signal-catching function to which .IR address points, and resume executing the receiving process at the point where it was interrupted. .IP The signal-catching function is called with the following three parameters: .RS .RS .TP 8 .I sig The signal number. .TP .I code A word of information usually provided by the hardware. .TP .I scp A pointer to the machine-dependent structure .I sigcontext defined in .RC < signal.h >. .RE .RE .IP The pointer .I scp is valid only during the context of the signal-catching function. The structure pointer .I scp is always defined. .IP The .I code word is always zero for all signals except .C SIGILL and .CR SIGFPE . For .CR SIGILL , .I code has the following values: .RS .RS .TP 8 .C 8 illegal instruction trap; .PD 0 .TP .C 9 break instruction trap; .TP .C 10 privileged operation trap; .TP .C 11 privileged register trap. .RE .PD .PP For .CR SIGFPE , .I code has the following values: .RS .TP 8 .C 12 overflow trap; .PD 0 .TP .C 13 conditional trap; .TP .C 14 assist exception trap; .TP .C 22 assist emulation trap. .RE .PD .PP As defined by the .SM IEEE POSIX Standard, .SM HP-UX does not raise an exception on floating-point divide by zero. The result of floating-point divide by zero is infinity which can be checked by .IR isinf (3M). .PP The signals .C SIGKILL and .C SIGSTOP cannot be caught. .RE .PP .CR sigset() allows the calling process to choose one of four ways to handle the receipt of a specific signal. .IR sig specifies the signal and .IR func specifies the choice. .PP .IR sig can be any one of the signals described under .IR signal (5) except .CR SIGKILL or .CR SIGSTOP . .PP .IR func is assigned one of four values: .CR SIG_DFL , .CR SIG_IGN , .CR SIG_HOLD , or a function address. The actions prescribed by .CR SIG_DFL and .CR SIG_IGN are described under .IR signal (5). The action prescribed by .CR SIG_HOLD and function address are described below: .RS .TP 25 .C SIG_HOLD Hold signal. The signal .IR sig is held upon receipt. Any pending signal of this signal type remains held. Only one signal of each type is held. Note: the signals .CR SIGKILL , .CR SIGCONT , and .CR SIGSTOP cannot be held. .TP 5 function address Catch signal. .IR func must be a pointer to a function, the signal\- catching handler, that is called when signal .IR sig occurs. .CR sigset() specifies that the process calls this function upon receipt of signal .IR sig . Any pending signal of this type is released. This handler address is retained across calls to the other signal management functions listed here. Upon receipt of signal .IR sig , the receiving process executes the signal\-catching function pointed to by .IR func as described under .IR signal (5) with the following differences: .PP Before calling the signal\-catching handler, the system signal action of .IR sig is set to .CR SIG_HOLD . During a normal return from the signal\-catching handler, the system signal action is restored to .IR func and any held signal of this type is released. If a non\-local goto .RC ( longjmp(3C) ) is taken, .CR sigrelse() must be called to restore the system signal action to .IR func and release any held signal of this type. .RE .PP .CR sighold() holds the signal .IR sig . .CR sigrelse() restores the system signal action of .IR sig to that specified previously by .CR sigset() . .CR sighold() and .CR sigrelse() are used to establish critical regions of code. .CR sighold() is analogous to raising the priority level and deferring or holding a signal until the priority is lowered by .CR sigrelse() . .PP .CR sigignore() sets the action for signal .IR sig to .CR SIG_IGN (see .IR signal (5)). .PP .CR sigpause() suspends the calling process until it receives an unblocked signal. If the signal .IR sig is held, it is released before the process pauses. .CR sigpause() is useful for testing variables that are changed when a signal occurs. For example, .CR sighold() should be used to block the signal first, then test the variables. If they have not changed, call .CR sigpause() to wait for the signal. .PP These functions can be linked into a program by giving the \-lV3 option to the .CR ld command (see .IR ld (1)). .SH ERRORS .CR sigset() fails and the system signal action for .IR sig is not changed if any of the following occur: .RS .TP 25 [EFAULT] The .IR func argument points to memory that is not a valid part of the process address space. Reliable detection of this error is implementation\-dependent. .RE .PP .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() fail and the system signal action for .IR sig is not changed if any of the following occur: .RS .TP 25 [EINVAL] An attempt is made to ignore, hold, or supply a handler for a signal that cannot be ignored, held, or caught; see .IR signal (5). .RE .PP .CR sigpause returns when the following occurs: .RS .TP 25 [EINTR] A signal was caught. .RE .SH EXAMPLES The following call to .C signal() sets up a signal-catching function for the .C SIGINT signal: .IP .C void myhandler(); .IP .C (void) signal(SIGINT, myhandler); .SH WARNINGS .C signal() should not be used in conjunction with the facilities described under .IR bsdproc (2), .IR sigaction (2), .IR sigset (2V), or .IR sigvector (2). .PP .C signal() does not detect an invalid value for .IR action , and if it does not equal .C SIG_DFL or .CR SIG_IGN, or point to a valid function address, subsequent receipt of the signal .IR sig causes undefined results. .RE .SH AUTHOR .C signal() was developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO kill(1), init(1M), exit(2), kill(2), lseek(2), pause(2), sigaction(2), sigvector(2), wait(2), abort(3C), setjmp(3C), signal(5). .SH STANDARDS CONFORMANCE .CR signal() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4signal()\f1 \- specify what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f4sigset()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sighold()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sigrelse()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sigignore()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f1specify what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f1define what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f1receipt of a signal, define what to do upon@@@\f3signal(2)\f1 .\" index@\f1signal, define what to do upon receipt of a@@@\f3signal(2)\f1 .\" .\" toc@\f3signal(2)\f1:\0\0\f4signal()\f1, \f4sigset()\f1, \f4sighold()\f1, \f4sigrelse()\1, \f4sigignore()\f1, \f4sigpause\f1@@@signal management .\" toc@\f4sigset()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sighold()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigrelse()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigignore()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigpause()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" .\" links@signal.2 sigset.2 .\" links@signal.2 sighold.2 .\" links@signal.2 sigrelse.2 .\" links@signal.2 sigignore.2 .\" $Header: sigpause.2,v 72.4 94/09/06 15:06:40 ssa Exp $ .TA s .TH sigpause 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigpause \- atomically release blocked signals and wait for interrupt .SH SYNOPSIS .C "#include " .PP .C "long sigpause(long mask);" .SH DESCRIPTION .C sigpause() blocks signals according to the value of .I mask in the same manner as .IR sigsetmask (2), then atomically waits for an unmasked signal to arrive. On return .C sigpause() restores the current signal mask to the value that existed before the .C sigpause() call. When no signals are to be blocked, a value of .C 0L is used for .IR mask. .PP In normal usage, a signal is blocked using .C sigblock() (see .IR sigblock (2)). To begin a critical section, variables modified on the occurrence of the signal are examined to determine that there is no work to be done, and the process pauses, awaiting work by using .C sigpause() with the mask returned by .CR sigblock() . .SH RETURN VALUE .C sigpause() terminates when it is interrupted by a signal. When .C sigpause() terminates, it returns \(mil and sets .C errno to .SM EINTR. .SH EXAMPLES The following call to .C sigpause() waits until the calling process receives a signal: .IP .C sigpause (0L); .PP The following example blocks the .SM SIGIO signal until .C sigpause() is called. When a signal is received at the .C sigpause() statement, the signal mask is restored to its value before .C sigpause() was called: .nf .IP .C long savemask; .C savemask = sigblock (sigmask (SIGIO)); /\(** critical section \(**/ .C sigpause (savemask); .fi .SH WARNINGS Check all references to .IR signal (5) for appropriateness on systems that support .IR sigvector (2). .IR sigvector() can affect the behavior described on this page. .PP Do not use .C sigpause() in conjunction with the facilities described under .IR sigset (2V). .SH AUTHOR .C sigpause() was developed by the University of California, Berkeley. .SH SEE ALSO sigblock(2), sigsetmask(2), sigsuspend(2), sigvector(2). .\" index@\f4sigpause()\fP \(mi atomically release blocked signals and wait for interrupt@@@\f3sigpause(2)\f1 .\" index@atomically release blocked signals and wait for interrupt@@@\f3sigpause(2)\f1 .\" index@release blocked signals and atomically wait for interrupt@@@\f3sigpause(2)\f1 .\" index@blocked signals, release and atomically wait for interrupt@@@\f3sigpause(2)\f1 .\" index@signals, release blocked and atomically wait for interrupt@@@\f3sigpause(2)\f1 .\" index@interrupt, atomically release blocked signals and wait for@@@\f3sigpause(2)\f1 .\" index@wait for interrupt, atomically release blocked signals and@@@\f3sigpause(2)\f1 .\" .\" toc@\f3sigpause(2)\f1:\0\0\f4sigpause()\fP@@@atomically release blocked signals and wait for interrupt .\" $Header: sigset.2v,v 72.4 94/11/14 15:26:38 ssa Exp $ .TA s .TH sigset 2V .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigset, sighold, sigrelse, sigignore, sigpause \- signal management .SH SYNOPSIS .C "#include " .PP .C "void (*sigset(int sig, void (*func)(int)))(int);" .PP .C "int sighold(int sig);" .PP .C "int sigrelse(int sig);" .PP .C "int sigignore(int sig);" .PP .C "int sigpause(int sig);" .SH DESCRIPTION The system defines a set of signals that can be delivered to a process. The set of signals is defined in .IR signal (5), along with the meaning and side effects of each signal. An alternate mechanism for handling these signals is defined here. The facilities described here should not be used in conjunction with the other facilities described under .IR signal (2), .IR sigvector (2), .IR sigblock (2), .IR sigsetmask (2), .IR sigpause (2) and .IR sigspace (2). .PP .C sigset() allows the calling process to choose one of four ways to handle the receipt of a specific signal. .IR sig specifies the signal and .IR func specifies the choice. .PP .I sig can be any one of the signals described under .IR signal (5) except .C SIGKILL or .CR SIGSTOP . .PP .I func is assigned one of four values: .CR SIG_DFL , .CR SIG_IGN , .CR SIG_HOLD , or a .IR "function address" . The actions prescribed by .C SIG_DFL and .C SIG_IGN are described under .IR signal (5). The action prescribed by .C SIG_HOLD and .IR "function address" are described below: .TP 15 .C SIG_HOLD Hold signal. .br The signal .IR sig is held upon receipt. Any pending signal of this signal type remains held. Only one signal of each type is held. .IP Note: the signals .CR SIGKILL , .CR SIGCONT , and .C SIGSTOP cannot be held. .PD .TP 15 .I function address Catch signal. .br .IR func must be a pointer to a function, the signal-catching handler, that is called when signal .IR sig occurs. .C sigset() specifies that the process calls this function upon receipt of signal .IR sig . Any pending signal of this type is released. This handler address is retained across calls to the other signal management functions listed here. Upon receipt of signal .IR sig , the receiving process executes the signal-catching function pointed to by .IR func as described under .IR signal (5) with the following differences: .IP Before calling the signal-catching handler, the system signal action of .IR sig is set to .CR SIG_HOLD . During a normal return from the signal-catching handler, the system signal action is restored to .IR func and any held signal of this type is released. If a non-local goto .IR (longjmp (3C)) is taken, .C sigrelse() must be called to restore the system signal action to .IR func and release any held signal of this type. .PP .C sighold() holds the signal .IR sig. .C sigrelse() restores the system signal action of .IR sig to that specified previously by .CR sigset() . .C sighold() and .C sigrelse() are used to establish critical regions of code. .C sighold() is analogous to raising the priority level and deferring or holding a signal until the priority is lowered by .CR sigrelse() . .PP .C sigignore() sets the action for signal .IR sig to .C SIG_IGN (see .IR signal (5)). .PP .C sigpause() suspends the calling process until it receives an unblocked signal. If the signal .I sig is held, it is released before the process pauses. .C sigpause() is useful for testing variables that are changed when a signal occurs. For example, .C sighold() should be used to block the signal first, then test the variables. If they have not changed, call .C sigpause() to wait for the signal. .PP These functions can be linked into a program by giving the .C \-lV3 option to the .C ld command (see .IR ld (1)). .SH RETURN VALUE Upon successful completion, .C sigset() returns the previous value of the system signal action for the specified signal .IR sig . Otherwise, a value of .C SIG_ERR is returned and .C errno is set to indicate the error. .C SIG_ERR is defined in .RC < signal.h >. .PP For the other functions, a 0 value indicates that the call succeeded. A \-1 return value indicates an error occurred and .C errno is set to indicate the reason. .SH ERRORS .C sigset() fails and the system signal action for .I sig is not changed if any of the following occur: .RS .TP 20 [EFAULT] The .I func argument points to memory that is not a valid part of the process address space. Reliable detection of this error is implementation dependent. .RE .PP .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() fail and the system signal action for .I sig is not changed if any of the following occur: .RS .TP 20 .SM [EINVAL] .I sig is not a valid signal number. .TP .SM [EINVAL] An attempt is made to ignore, hold, or supply a handler for a signal that cannot be ignored, held, or caught; see .IR signal (5). .RE .PP .IR sigpause returns when the following occurs: .RS .TP 20 .SM [EINTR] A signal was caught. .RE .SH WARNINGS These signal facilities should not be used in conjunction with .IR bsdproc (2), .IR signal (2), .IR sigvector (2), .IR sigblock (2), .IR sigsetmask (2), .IR sigpause (2) and .IR sigspace (2). .SH SEE ALSO kill(1), kill(2), signal(2), pause(2), wait(2), abort(3C), setjmp(3C), signal(5). .SH STANDARDS CONFORMANCE .CR sigset() ": SVID2, SVID3" .PP .CR sighold() ": SVID2, SVID3" .PP .CR sigignore() ": SVID2, SVID3" .PP .CR sigpause() ": SVID2, SVID3" .PP .CR sigrelse() ": SVID2, SVID3" .\" .\" index@\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@signal management (\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP)@@@\f3sigset(2V)\f1 .\" index@management, signal (\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP)@@@\f3sigset(2V)\f1 .\" index@hold signal upon receipt@@@\f3sigset(2V)\f1 .\" index@signal, hold upon receipt@@@\f3sigset(2V)\f1 .\" index@ignore signal@@@\f3sigset(2V)\f1 .\" index@signal, ignore@@@\f3sigset(2V)\f1 .\" index@restore signal action@@@\f3sigset(2V)\f1 .\" index@signal, restore action@@@\f3sigset(2V)\f1 .\" index@signal, suspend calling process until received@@@\f3sigset(2V)\f1 .\" index@signal, select method of handling@@@\f3sigset(2V)\f1 .\" .\" toc@\f3sigset(2V)\f1:\0\0\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP@@@signal management .\" toc@\f4sighold()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigrelse()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigignore()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigpause()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" .\" links@sigset.2v sighold.2v .\" links@sigset.2v sigrelse.2v .\" links@sigset.2v sigignore.2v .\" links@sigset.2v sigpause.2v .\" .\" fileset_database@sigset.2v PROGRAMING-MAN .\" $Header: sigpending.2,v 76.1 95/07/07 14:55:44 ssa Exp $ .TA s .TH sigpending 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigpending \- examine pending signals .SH SYNOPSIS .C "#include " .PP .C "int sigpending(sigset_t *set);" .SH DESCRIPTION .C sigpending() stores sets of signals that are blocked from delivery and are pending to the calling process, at the location pointed to by .IR set . .SH RETURN VALUE Upon successful completion, .C sigpending() returns 0. Otherwise \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS No errors are defined. .SH SEE ALSO sigaddset(), sigdelset(), sigemptyset(), sigfillset(), sigismember(), sigprocmask(), . .SH CHANGE HISTORY First release in Issue 3. .\" $Header: sigpending.2,v 76.1 95/07/07 14:55:44 ssa Exp $ .TA s .TH sigpending 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH ERRORS .C sigpending() fails if the following condition is encountered: .TP 15 [EFAULT] .I set points to an invalid address. The reliable detection of this error is implementation dependent. .SH AUTHOR .C sigpending() was derived from the .SM IEEE POSIX 1003.1-1988 Standard. .SH SEE ALSO sigaction(2), sigsuspend(2), sigprocmask(2), sigsetops(3C), signal(5). .SH STANDARDS CONFORMANCE .CR sigpending() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" .\" index@\f4sigpending()\f1 \- examine pending signals@@@\f3sigpending(2)\f1 .\" index@examine pending signals@@@\f3sigpending(2)\f1 .\" index@pending signals, examine@@@\f3sigpending(2)\f1 .\" index@signals, examine pending@@@\f3sigpending(2)\f1 .\" .\" toc@\f3sigpending(2)\f1:\0\0\f4sigpending()\fP@@@examine pending signals .\" $Header: sigprocmask.2,v 76.2 95/09/29 09:34:58 ssa Exp $ .TA s .TH sigprocmask 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigprocmask \- examine and change blocked signals .SH SYNOPSIS .C "#include " .PP .nf .PD 0 .C "int sigprocmask(" .IP .C "int how," .C "const sigset_t *set," .C "sigset_t *oset" .PP .C ");" .PD .SH DESCRIPTION The .CR sigprocmask() function allows the calling process to examine and/or change its signal mask. .PP If the argument set is not a null pointer, it points to a set of signals to be used to change the currently blocked set. .PP The argument .IR how indicates the way in which the set is changed and consists of one of the following values: .RS .TP 25 .C SIG_BLOCK The resulting set will be the union of the current set and the signal set pointed to by set. .TP .C SIG_SETMASK The resulting set will be the signal set pointed to by set. .TP .C SIG_UNBLOCK The resulting set will be the intersection of the current set andthe complement of the signal set pointed to by set. .RE .PP If the argument .IR oset is not a null pointer, the previous mask is stored in the location pointed to by .IR oset . If .IR set is a null pointer, the value of the argument .IR how is not significant and the process' signal mask is unchanged; thus the call can be used to inquire about currently blocked signals. .PP If there are any pending unblocked signals after the call to .CR sigprocmask() , at least one of those signals will be delivered before the call to .CR sigprocmask() returns. .PP It is not possible to block those signals which cannot be ignored. This is enforced by the system without causing an error to be indicated. .PP If any of the .CR SIGFPE , .CR SIGILL , or .CR SIGSEGV signals are generated while they are blocked, the result is undefined, unless the signal was generated by a call to .CR kill() or .CR raise() . .PP If .CR sigprocmask() fails, the process' signal mask is not changed. .SH RETURN VALUE Upon successful completion, .CR sigprocmask() returns 0. Otherwise \(mi1 is returned, .CR errno is set to indicate the error, and the process' signal mask will be unchanged. .SH ERRORS The .CR sigprocmask() function will fail if: .RS .TP 15 [EINVAL] The value of the how argument is not equal to one of the defined values. .RE .SH SEE ALSO sigaction(), sigaddset(), sigdelset(), sigemptyset(), sigfillset(), sigismember(), sigpending(), sigsuspend(), . .SH CHANGE HISTORY First released in Issue 3. .PP Entry included foralignment with the POSIX.1-1988 standard. .SH Issue 4 The following change is incorporated for alignment with the ISO POSIX-1 standard: .RS .TP 10 \- The type of the arguments .IR set and .IR oset are changed from .IR sigset_t* to .IR const sigset_t* . .RE Another change is incorporated as follows: .RS .TP 10 \- The DESCRIPTION section is changed to indicate that signals can also be generated by .CR raise() . .RE .\" $Header: sigprocmask.2,v 76.2 95/09/29 09:34:58 ssa Exp $ .TA s .TH sigprocmask 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH ERRORS .C sigprocmask() fails if any of the following conditions are encountered: .TP 20 .C [EFAULT] .IR set or .IR oset points to an invalid address. The reliable detection of this error is implementation dependent. .SH AUTHOR .C sigprocmask() was derived from the .SM IEEE POSIX 1003.1-1988 Standard. .SH SEE ALSO sigaction(2), sigsuspend(2), sigpending(2), sigsetops(3C), signal(5). .SH STANDARDS CONFORMANCE .CR sigprocmask() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4sigprocmask()\f1 \- examine and change blocked signals@@@\f3sigprocmask(2)\f1 .\" index@examine and change blocked signals@@@\f3sigprocmask(2)\f1 .\" index@change or examine blocked signals@@@\f3sigprocmask(2)\f1 .\" index@blocked signals, examine and change@@@\f3sigprocmask(2)\f1 .\" index@signals, blocked, examine and change@@@\f3sigprocmask(2)\f1 .\" .\" toc@\f3sigprocmask(2)\f1:\0\0\f4sigprocmask()\fP@@@examine and change blocked signals .\" $Header: signal.2,v 76.2 95/07/24 16:18:01 ssa Exp $ .TA s .TH signal 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME signal, sigset, sighold, sigrelse, sigignore, sigpause \-signal management .SH SYNOPSIS .C "#include " .PP .C "void (*signal(int sig, void (*func)(int)))(int);" .PP .C "int sighold(int sig);" .PP .C "int sigignore(int sig);" .PP .C "int sigpause(int sig);" .PP .C "int sigrelse(int sig);" .PP .C "void (*sigset(int sig, void (*disp)(int)))(int);" .SH DESCRIPTION The .CR signal() function chooses one of three ways in which receipt of the signal number .IR sig is to be subsequently handled. If the value of func is .CR SIG_DFL , default handling for that signal will occur. If the value of .IR func is .CR SIG_IGN , the signal will be ignored. Otherwise, .IR func must point to a function to be called when that signal occurs. Such a function is called a signal handler. .PP When a signal occurs, if .IR func points to a function, first the equivalent of a: .IP .C signal(sig, SIG_DFL); .PP is executed or an implementation-dependent blocking of the signal is performed. (If the value of .IR sig is .CR SIGILL , whether the reset to .CR SIG_DFL occurs is implementation-dependent.) Next the equivalent of: .IP .C (*func)(sig); .PP is executed. The .IR func function may terminate by executing a return statement or by calling .CR abort() , .CR exit() , or .CR longjmp() . If .CR func() executes a return statement and the value of .IR sig was .CR SIGFPE or any other implementation-dependent value corresponding to a computational exception, the behaviour is undefined. Otherwise, the program will resume execution at the point it was interrupted. .PP If the signal occurs other than as the result of calling .CR abort() , .CR kill() or .CR raise() , the behaviour is undefined if the signal handler calls any function in the standard library other than one of the functions listed on the .I sigaction() page or refers to any object with static storage duration other than by assigning a value to a static storage duration variable of type volatile .IR sig_atomic_t . Furthermore, if such a call fails, the value of .CR errno is indeterminate. .PP At program startup, the equivalent of: .IP .C signal(sig, SIG_IGN); .PP is executed for some signals, and the equivalent of: .IP .C signal(sig, SIG_DFL); .PP is executed for all other signals (see .CR exec ). .PP The .CR sigset() , .CR sighold() , .CR sigignore() , .CR sigpause() and .CR segrelse() functions provide simplified signal management. .PP The .CR sigset() function is used to modify signal dispositions. The .IR sig argument specifies the signal, which may be any signal except .CR SIGKILL and .CR SIGSTOP . The .IR disp argument specifies the signal's disposition, which may be .CR SIG_DFL , .CR SIG_IGN or the address of a signal handler. If .CR sigset() is used, and .IR disp is the address of a signal handler, the system will add .IR sig to the calling process' signal mask before executing the signal handler; when the signal handler returns, the system will restore the calling process' signal mask to its state prior the delivery of the signal. In addition, if .CR sigset() is used, and .IR disp is equal to .CR SIG_HOLD , .IR sig will be added to the calling process' signal mask and .IR sig 's disposition will remain unchanged. If .CR sigset() is used, and .IR disp is not equal to .CR SIG_HOLD , .IR sig will be removed from the calling process' signal mask. .PP The .CR sighold() function adds .IR sig to the calling process' signal mask. .PP The .CR sigrelse() function removes .IR sig from the calling process' signal mask. .PP The .CR sigignore() function sets the disposition of .IR sig to .CR SIG_IGN . .PP The sigpause() function removes .IR sig from the calling process' signal mask and suspends the calling process until a signal is received. .PP If the action for the .CR SIGCHLD signal is set to .CR SIG_IGN , child processes of the calling processes will not be transformed into zombie processes when they terminate. If the calling process subsequently waits for its children, and the process has no unwaited for children that were transformed into zombie processes, it will block until all of its children terminate, and .CR wait() , .CR wait3() , .CR waitid() and .CR waitpid() will fail and set .CR errno to .CR ECHILD . .SH RETURN VALUE If the request can be honoured, .CR signal() returns the value of .CR func() for the most recent call to .CR signal() for the specified signal .IR sig . Otherwise, .CR SIG_ERR is returned and a positive value is stored in .CR errno . .PP Upon successful completion, .CR sigset() returns .CR SIG_HOLD if the signal had been blocked and the signal's previous disposition if it had not been blocked. Otherwise, .CR SIG_ERR is returned and .CR errno is set to indicate the error. .PP For all other functions, upon successful completion, 0 is returned. Otherwise, \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR signal() function will fail if: .RS .TP 15 [EINVAL] The .IR sig argument is not a valid signal number or an attempt is made to catch a signal that cannot be caught or ignore a signal that cannot be ignored. .RE .PP The .CR signal() function may fail if: .RS .TP 15 [EINVAL] An attempt was made to set the action to .CR SIG_DFL for a signal that cannot be caught or ignored (or both). .RE .PP The .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() functions will fail if: .RS .TP 15 [EINVAL] The .IR sig argument is an illegal signal number. .RE .PP The .CR sigset() , and .CR sigignore() functions will fail if: .RS .TP 15 [EINVAL] An attempt is made to catch a signal that cannot be caught, or to ignore a signal that cannot be ignored. .RE .SH APPLICATION USAGE The .CR sigaction() function provides a more comprehensive and reliable mechanism for controlling signals; new applications should use .CR sigaction() rather than .CR signal() . .PP The .CR sighold() function, in conjunction with .CR sigrelse() or .CR sigpause() , may be used to establish critical regions of code that require the delivery of a signal to be temporarily deferred. .PP The .CR sigsuspend() function should be used in preference to .CR sigpause() for broader portability. .SH SEE ALSO exec, pause(), sigaction(), waitid(), . .SH CHANGE HISTORY First released in Issue 1. .PP Derived from Issue 1 of the SVID. .SH Issue 4 The following changes are incorporated for alignment with the ISO C standard: .RS .TP 10 \- The function is no longer marked as an extension. .TP \- The argument int is added to the definition of .CR func() in the SYNOPSIS section. .TP \- In Issue 3, this interface cross-referred to .CR sigaction() . This issue provides a complete description of the function as defined in ISO C standard. .RE .PP Another change is incorporated as follows: .RS .TP 10 \- The APPLICATION USAGE section is added. .SH Issue 4, Version 2 The following changes are incorporated for X/OPEN UNIX conformance: .RS .TP 10 \- The .CR sighold() , .CR sigignore() , .CR sigpause() , .CR sigrelse() , and .CR sigset() functions are added to the SYNOPSIS. .TP \- The DESCRIPTION is updated to describe semantics of the above interfaces. .TP \- Additional text is added to the RETURN VALUE section to describe possible returns from the .CR sigset() function specifically, and all of the above functions in general. .TP \- The ERRORS section is restructured to describe possible error returns from each of the above functions individually. .TP \- The APPLICATION USAGE section is updated to describe certain programming considerations associated with the X/OPEN UNIX functions. .\" $Header: signal.2,v 76.2 95/07/24 16:18:01 ssa Exp $ .TA s .TH signal 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH SYNOPSIS .PP .C "void (*signal(int sig, void (*action)(int)))(int);" .PP .C "void (*sigset(int sig, void (*func)(int)))(int);" .PP .SH DESCRIPTION .PP The system defines a set of signals that can be delivered to a process. The set of signals is defined in .IR signal (5), along with the meaning and side effects of each signal. An alternate mechanism for handling these signals is defined here. The facilities described here should not be used in conjunction with the other facilities described under .CR signal(2) , .CR sigvector(2) , .CR sigblock(2) , .CR sigsetmask(2) , .CR sigpause(2) , and .CR sigspace(2) . .PP Acceptable values for .I sig are defined in .CR . .PP .RS .TP 12 .C SIG_DFL Execute the default action, which varies depending on the signal. The default action for most signals is to terminate the process (see .IR signal (5)). .IP A pending signal is discarded (whether or not it is blocked) if .I action is set to .C SIG_DFL but the default action of the pending signal is to ignore the signal (as in the case of .CR SIGCLD ). .TP .C SIG_IGN Ignore the signal. .br When .C signal() is called with .I action set to .C SIG_IGN and an instance of the signal .I sig is pending, the pending signal is discarded, whether or not it is blocked. .IP .C SIGKILL and .C SIGSTOP signals cannot be ignored. .TP .I address Catch the signal. .br Upon receipt of signal .IR sig , reset the value of .I action for the caught signal to .SM SIG_DFL (except signals marked with "not reset when caught"; see .IR signal (5)), call the signal-catching function to which .IR address points, and resume executing the receiving process at the point where it was interrupted. .IP The signal-catching function is called with the following three parameters: .RS .RS .TP 8 .I sig The signal number. .TP .I code A word of information usually provided by the hardware. .TP .I scp A pointer to the machine-dependent structure .I sigcontext defined in .RC < signal.h >. .RE .RE .IP The pointer .I scp is valid only during the context of the signal-catching function. The structure pointer .I scp is always defined. .IP The .I code word is always zero for all signals except .C SIGILL and .CR SIGFPE . For .CR SIGILL , .I code has the following values: .RS .RS .TP 8 .C 8 illegal instruction trap; .PD 0 .TP .C 9 break instruction trap; .TP .C 10 privileged operation trap; .TP .C 11 privileged register trap. .RE .PD .PP For .CR SIGFPE , .I code has the following values: .RS .TP 8 .C 12 overflow trap; .PD 0 .TP .C 13 conditional trap; .TP .C 14 assist exception trap; .TP .C 22 assist emulation trap. .RE .PD .PP As defined by the .SM IEEE POSIX Standard, .SM HP-UX does not raise an exception on floating-point divide by zero. The result of floating-point divide by zero is infinity which can be checked by .IR isinf (3M). .PP The signals .C SIGKILL and .C SIGSTOP cannot be caught. .RE .PP .CR sigset() allows the calling process to choose one of four ways to handle the receipt of a specific signal. .IR sig specifies the signal and .IR func specifies the choice. .PP .IR sig can be any one of the signals described under .IR signal (5) except .CR SIGKILL or .CR SIGSTOP . .PP .IR func is assigned one of four values: .CR SIG_DFL , .CR SIG_IGN , .CR SIG_HOLD , or a function address. The actions prescribed by .CR SIG_DFL and .CR SIG_IGN are described under .IR signal (5). The action prescribed by .CR SIG_HOLD and function address are described below: .RS .TP 25 .C SIG_HOLD Hold signal. The signal .IR sig is held upon receipt. Any pending signal of this signal type remains held. Only one signal of each type is held. Note: the signals .CR SIGKILL , .CR SIGCONT , and .CR SIGSTOP cannot be held. .TP 5 function address Catch signal. .IR func must be a pointer to a function, the signal\- catching handler, that is called when signal .IR sig occurs. .CR sigset() specifies that the process calls this function upon receipt of signal .IR sig . Any pending signal of this type is released. This handler address is retained across calls to the other signal management functions listed here. Upon receipt of signal .IR sig , the receiving process executes the signal\-catching function pointed to by .IR func as described under .IR signal (5) with the following differences: .PP Before calling the signal\-catching handler, the system signal action of .IR sig is set to .CR SIG_HOLD . During a normal return from the signal\-catching handler, the system signal action is restored to .IR func and any held signal of this type is released. If a non\-local goto .RC ( longjmp(3C) ) is taken, .CR sigrelse() must be called to restore the system signal action to .IR func and release any held signal of this type. .RE .PP .CR sighold() holds the signal .IR sig . .CR sigrelse() restores the system signal action of .IR sig to that specified previously by .CR sigset() . .CR sighold() and .CR sigrelse() are used to establish critical regions of code. .CR sighold() is analogous to raising the priority level and deferring or holding a signal until the priority is lowered by .CR sigrelse() . .PP .CR sigignore() sets the action for signal .IR sig to .CR SIG_IGN (see .IR signal (5)). .PP .CR sigpause() suspends the calling process until it receives an unblocked signal. If the signal .IR sig is held, it is released before the process pauses. .CR sigpause() is useful for testing variables that are changed when a signal occurs. For example, .CR sighold() should be used to block the signal first, then test the variables. If they have not changed, call .CR sigpause() to wait for the signal. .PP These functions can be linked into a program by giving the \-lV3 option to the .CR ld command (see .IR ld (1)). .SH ERRORS .CR sigset() fails and the system signal action for .IR sig is not changed if any of the following occur: .RS .TP 25 [EFAULT] The .IR func argument points to memory that is not a valid part of the process address space. Reliable detection of this error is implementation\-dependent. .RE .PP .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() fail and the system signal action for .IR sig is not changed if any of the following occur: .RS .TP 25 [EINVAL] An attempt is made to ignore, hold, or supply a handler for a signal that cannot be ignored, held, or caught; see .IR signal (5). .RE .PP .CR sigpause returns when the following occurs: .RS .TP 25 [EINTR] A signal was caught. .RE .SH EXAMPLES The following call to .C signal() sets up a signal-catching function for the .C SIGINT signal: .IP .C void myhandler(); .IP .C (void) signal(SIGINT, myhandler); .SH WARNINGS .C signal() should not be used in conjunction with the facilities described under .IR bsdproc (2), .IR sigaction (2), .IR sigset (2V), or .IR sigvector (2). .PP .C signal() does not detect an invalid value for .IR action , and if it does not equal .C SIG_DFL or .CR SIG_IGN, or point to a valid function address, subsequent receipt of the signal .IR sig causes undefined results. .RE .SH AUTHOR .C signal() was developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO kill(1), init(1M), exit(2), kill(2), lseek(2), pause(2), sigaction(2), sigvector(2), wait(2), abort(3C), setjmp(3C), signal(5). .SH STANDARDS CONFORMANCE .CR signal() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4signal()\f1 \- specify what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f4sigset()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sighold()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sigrelse()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sigignore()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f1specify what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f1define what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f1receipt of a signal, define what to do upon@@@\f3signal(2)\f1 .\" index@\f1signal, define what to do upon receipt of a@@@\f3signal(2)\f1 .\" .\" toc@\f3signal(2)\f1:\0\0\f4signal()\f1, \f4sigset()\f1, \f4sighold()\f1, \f4sigrelse()\1, \f4sigignore()\f1, \f4sigpause\f1@@@signal management .\" toc@\f4sigset()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sighold()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigrelse()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigignore()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigpause()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" .\" links@signal.2 sigset.2 .\" links@signal.2 sighold.2 .\" links@signal.2 sigrelse.2 .\" links@signal.2 sigignore.2 .\" $Header: sigset.2v,v 72.4 94/11/14 15:26:38 ssa Exp $ .TA s .TH sigset 2V .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigset, sighold, sigrelse, sigignore, sigpause \- signal management .SH SYNOPSIS .C "#include " .PP .C "void (*sigset(int sig, void (*func)(int)))(int);" .PP .C "int sighold(int sig);" .PP .C "int sigrelse(int sig);" .PP .C "int sigignore(int sig);" .PP .C "int sigpause(int sig);" .SH DESCRIPTION The system defines a set of signals that can be delivered to a process. The set of signals is defined in .IR signal (5), along with the meaning and side effects of each signal. An alternate mechanism for handling these signals is defined here. The facilities described here should not be used in conjunction with the other facilities described under .IR signal (2), .IR sigvector (2), .IR sigblock (2), .IR sigsetmask (2), .IR sigpause (2) and .IR sigspace (2). .PP .C sigset() allows the calling process to choose one of four ways to handle the receipt of a specific signal. .IR sig specifies the signal and .IR func specifies the choice. .PP .I sig can be any one of the signals described under .IR signal (5) except .C SIGKILL or .CR SIGSTOP . .PP .I func is assigned one of four values: .CR SIG_DFL , .CR SIG_IGN , .CR SIG_HOLD , or a .IR "function address" . The actions prescribed by .C SIG_DFL and .C SIG_IGN are described under .IR signal (5). The action prescribed by .C SIG_HOLD and .IR "function address" are described below: .TP 15 .C SIG_HOLD Hold signal. .br The signal .IR sig is held upon receipt. Any pending signal of this signal type remains held. Only one signal of each type is held. .IP Note: the signals .CR SIGKILL , .CR SIGCONT , and .C SIGSTOP cannot be held. .PD .TP 15 .I function address Catch signal. .br .IR func must be a pointer to a function, the signal-catching handler, that is called when signal .IR sig occurs. .C sigset() specifies that the process calls this function upon receipt of signal .IR sig . Any pending signal of this type is released. This handler address is retained across calls to the other signal management functions listed here. Upon receipt of signal .IR sig , the receiving process executes the signal-catching function pointed to by .IR func as described under .IR signal (5) with the following differences: .IP Before calling the signal-catching handler, the system signal action of .IR sig is set to .CR SIG_HOLD . During a normal return from the signal-catching handler, the system signal action is restored to .IR func and any held signal of this type is released. If a non-local goto .IR (longjmp (3C)) is taken, .C sigrelse() must be called to restore the system signal action to .IR func and release any held signal of this type. .PP .C sighold() holds the signal .IR sig. .C sigrelse() restores the system signal action of .IR sig to that specified previously by .CR sigset() . .C sighold() and .C sigrelse() are used to establish critical regions of code. .C sighold() is analogous to raising the priority level and deferring or holding a signal until the priority is lowered by .CR sigrelse() . .PP .C sigignore() sets the action for signal .IR sig to .C SIG_IGN (see .IR signal (5)). .PP .C sigpause() suspends the calling process until it receives an unblocked signal. If the signal .I sig is held, it is released before the process pauses. .C sigpause() is useful for testing variables that are changed when a signal occurs. For example, .C sighold() should be used to block the signal first, then test the variables. If they have not changed, call .C sigpause() to wait for the signal. .PP These functions can be linked into a program by giving the .C \-lV3 option to the .C ld command (see .IR ld (1)). .SH RETURN VALUE Upon successful completion, .C sigset() returns the previous value of the system signal action for the specified signal .IR sig . Otherwise, a value of .C SIG_ERR is returned and .C errno is set to indicate the error. .C SIG_ERR is defined in .RC < signal.h >. .PP For the other functions, a 0 value indicates that the call succeeded. A \-1 return value indicates an error occurred and .C errno is set to indicate the reason. .SH ERRORS .C sigset() fails and the system signal action for .I sig is not changed if any of the following occur: .RS .TP 20 [EFAULT] The .I func argument points to memory that is not a valid part of the process address space. Reliable detection of this error is implementation dependent. .RE .PP .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() fail and the system signal action for .I sig is not changed if any of the following occur: .RS .TP 20 .SM [EINVAL] .I sig is not a valid signal number. .TP .SM [EINVAL] An attempt is made to ignore, hold, or supply a handler for a signal that cannot be ignored, held, or caught; see .IR signal (5). .RE .PP .IR sigpause returns when the following occurs: .RS .TP 20 .SM [EINTR] A signal was caught. .RE .SH WARNINGS These signal facilities should not be used in conjunction with .IR bsdproc (2), .IR signal (2), .IR sigvector (2), .IR sigblock (2), .IR sigsetmask (2), .IR sigpause (2) and .IR sigspace (2). .SH SEE ALSO kill(1), kill(2), signal(2), pause(2), wait(2), abort(3C), setjmp(3C), signal(5). .SH STANDARDS CONFORMANCE .CR sigset() ": SVID2, SVID3" .PP .CR sighold() ": SVID2, SVID3" .PP .CR sigignore() ": SVID2, SVID3" .PP .CR sigpause() ": SVID2, SVID3" .PP .CR sigrelse() ": SVID2, SVID3" .\" .\" index@\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@signal management (\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP)@@@\f3sigset(2V)\f1 .\" index@management, signal (\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP)@@@\f3sigset(2V)\f1 .\" index@hold signal upon receipt@@@\f3sigset(2V)\f1 .\" index@signal, hold upon receipt@@@\f3sigset(2V)\f1 .\" index@ignore signal@@@\f3sigset(2V)\f1 .\" index@signal, ignore@@@\f3sigset(2V)\f1 .\" index@restore signal action@@@\f3sigset(2V)\f1 .\" index@signal, restore action@@@\f3sigset(2V)\f1 .\" index@signal, suspend calling process until received@@@\f3sigset(2V)\f1 .\" index@signal, select method of handling@@@\f3sigset(2V)\f1 .\" .\" toc@\f3sigset(2V)\f1:\0\0\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP@@@signal management .\" toc@\f4sighold()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigrelse()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigignore()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigpause()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" .\" links@sigset.2v sighold.2v .\" links@sigset.2v sigrelse.2v .\" links@sigset.2v sigignore.2v .\" links@sigset.2v sigpause.2v .\" .\" fileset_database@sigset.2v PROGRAMING-MAN .\" $Header: sigsend.2,v 72.2 94/08/18 10:48:18 ssa Exp $ .TA s .TH sigsend 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigsend(), sigsendset() \- send a signal to a process or a group of processes .SH SYNOPSIS .C #include .PP .C #include .PP .C "int sigsend (idtype_t idtype, id_t id, int sig);" .PP .C "int sigsendset (const procset_t *psp, int sig);" .PP .SH DESCRIPTION The .CR sigsend() system call sends a signal to a process or a group of processes. The process or group of processes to which the signal is to be sent is specified by .I id and .IR idtype . The signal to be sent is specified by .I sig and is either one from the list given in .CR signal() (see .IR signal (2)) or 0. .PP If .I sig is equal to zero (the null signal), error checking is performed but no signal is actually sent. This can be used to check the validity of .I id and .IR idtype . .PP The real or effective user ID of the sending process must match the real or effective user ID of the receiving process, unless the process has appropriate privileges, or .I sig is .CR SIGCONT and the sending process has the same session ID as the receiving process. .PP .I idtype and .I id work together as follows: .RS .TP 3 \(bu If .I idtype is .CR P_PID , .I sig will be sent to the process with a process ID equal to .CR (pid_t)id . .TP \(bu If .I idtype is .CR P_PGID , .I sig will be sent to any process with a process group ID equal to .CR (pid_t)id . .TP \(bu If .I idtype is .CR P_SID , .IR sig will be sent to any process with a session ID equal to .CR (pid_t)id . .TP \(bu If .IR idtype is .CR P_UID , .I sig will be sent to any process with an effective user ID equal to .CR (uid_t)id . .TP \(bu If .IR idtype is .CR P_GID , .I sig will be sent to any process with an effective group ID equal to .CR (gid_t)id . .TP \(bu If .IR idtype is .CR P_ALL , .IR sig will be sent to all processes and .I id will be ignored. .TP \(bu If .IR id is .CR P_MYID , the value of .I id is taken from the calling process. .RE .PP The process with a process ID of .CR 0 is always excluded. The process with a process ID of .CR 1 is included only if .I idtype is equal to .CR P_PID . .PP .CR sigsendset() provides an alternate interface for sending signals to a set of processes. .PP .I psp is a pointer to a structure that includes the following members: .nf .IP .C "idop p_op;" .C "idtype_t p_lidtype;" .C "id_t p_lid;" .C "idtype_t p_ridtype;" .C "id_t p_rid;" .fi .PP The structure defines a set of processes as the result of a set operation (difference, union, intersection, or exclusion) on two operands .RI ( idtype / id pairs). The left (right) operand is specified by .CR "p_lid (p_rid)" and .CR "p_lidtype (p_ridtype)" . .CR "p_lid (p_rid)" takes the values specified by .I id and .CR "p_lidtype (p_ridtype)" takes the values specified by .I idtype in the .CR sigsend() system call defined above. .IR p_op specifies the operand, and takes one of the following values: .RS .TP 15 .C POP_DIFF Set difference. The resultant set consists of the processes that are in the left operand and not in the right operand. .TP .C POP_AND Set intersection. The resultant set consists of the processes that are in both the left and right operands. .TP .C POP_OR Set union. The resultant set consists of the processes that are in either the left or right operand or both. .TP .C POP_XOR Set exclusive .CR OR . The resultant set consists of the processes that are in either the left or right operand but not in both. .SH RETURN VALUE Upon successful completion, .CR sigsend() returns a value of .CR 0 . Otherwise, it returns a value of \(mi1 and sets .CR errno to indicate the error. .SH ERRORS If .CR sigsend() fails, it sets errno (see .IR errno (2)) to one of the following values: .RS .TP 15 [EINVAL] .I sig is neither a valid signal number nor zero. .TP [EINVAL] .I idtype is not a valid value. .TP [EINVAL] .I sig is .CR SIGKILL , .I idtype is .CR P_PID , and .I id is .CR 1 . .TP [ESRCH] No process can be found corresponding to that specified by .I id and .IR idtype . .TP [EPERM] The user ID of the sending process is not 0, and its real or effective user ID does not match the real or effective user ID of the receiving process, and the calling process is not sending .CR SIGCONT to a process that shares the same session ID. .SH SEE ALSO kill(2), signal(2). .\" .\" toc@\f3sigsend(2)\f1:\0\0\f4sigsend()\f1, \f4sigsendset()\f1@@@send a signal to a process or a group of processes .\" toc@\f4sigsendset()\f1:\0\0send a signal to a group of processes@@@\f1see \f3sigsend(2)\f1 .\" .\" index@\f4sigsend()\f1 \- send a signal to a process@@@\f3sigsend(2)\f1 .\" index@\f4sigsendset()\f1 \- send a signal to a group of processes@@@\f3sigsend(2) \f1 .\" index@\f1send a signal to a process or a group of processes@@@\f3sigsend(2)\f1 .\" index@\f1signal, send to a process or a group of processes@@@\f3sigsend(2)\f1 .\" links@sigsend.2 sigsendset.2 .\" $Header: sigsend.2,v 72.2 94/08/18 10:48:18 ssa Exp $ .TA s .TH sigsend 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigsend(), sigsendset() \- send a signal to a process or a group of processes .SH SYNOPSIS .C #include .PP .C #include .PP .C "int sigsend (idtype_t idtype, id_t id, int sig);" .PP .C "int sigsendset (const procset_t *psp, int sig);" .PP .SH DESCRIPTION The .CR sigsend() system call sends a signal to a process or a group of processes. The process or group of processes to which the signal is to be sent is specified by .I id and .IR idtype . The signal to be sent is specified by .I sig and is either one from the list given in .CR signal() (see .IR signal (2)) or 0. .PP If .I sig is equal to zero (the null signal), error checking is performed but no signal is actually sent. This can be used to check the validity of .I id and .IR idtype . .PP The real or effective user ID of the sending process must match the real or effective user ID of the receiving process, unless the process has appropriate privileges, or .I sig is .CR SIGCONT and the sending process has the same session ID as the receiving process. .PP .I idtype and .I id work together as follows: .RS .TP 3 \(bu If .I idtype is .CR P_PID , .I sig will be sent to the process with a process ID equal to .CR (pid_t)id . .TP \(bu If .I idtype is .CR P_PGID , .I sig will be sent to any process with a process group ID equal to .CR (pid_t)id . .TP \(bu If .I idtype is .CR P_SID , .IR sig will be sent to any process with a session ID equal to .CR (pid_t)id . .TP \(bu If .IR idtype is .CR P_UID , .I sig will be sent to any process with an effective user ID equal to .CR (uid_t)id . .TP \(bu If .IR idtype is .CR P_GID , .I sig will be sent to any process with an effective group ID equal to .CR (gid_t)id . .TP \(bu If .IR idtype is .CR P_ALL , .IR sig will be sent to all processes and .I id will be ignored. .TP \(bu If .IR id is .CR P_MYID , the value of .I id is taken from the calling process. .RE .PP The process with a process ID of .CR 0 is always excluded. The process with a process ID of .CR 1 is included only if .I idtype is equal to .CR P_PID . .PP .CR sigsendset() provides an alternate interface for sending signals to a set of processes. .PP .I psp is a pointer to a structure that includes the following members: .nf .IP .C "idop p_op;" .C "idtype_t p_lidtype;" .C "id_t p_lid;" .C "idtype_t p_ridtype;" .C "id_t p_rid;" .fi .PP The structure defines a set of processes as the result of a set operation (difference, union, intersection, or exclusion) on two operands .RI ( idtype / id pairs). The left (right) operand is specified by .CR "p_lid (p_rid)" and .CR "p_lidtype (p_ridtype)" . .CR "p_lid (p_rid)" takes the values specified by .I id and .CR "p_lidtype (p_ridtype)" takes the values specified by .I idtype in the .CR sigsend() system call defined above. .IR p_op specifies the operand, and takes one of the following values: .RS .TP 15 .C POP_DIFF Set difference. The resultant set consists of the processes that are in the left operand and not in the right operand. .TP .C POP_AND Set intersection. The resultant set consists of the processes that are in both the left and right operands. .TP .C POP_OR Set union. The resultant set consists of the processes that are in either the left or right operand or both. .TP .C POP_XOR Set exclusive .CR OR . The resultant set consists of the processes that are in either the left or right operand but not in both. .SH RETURN VALUE Upon successful completion, .CR sigsend() returns a value of .CR 0 . Otherwise, it returns a value of \(mi1 and sets .CR errno to indicate the error. .SH ERRORS If .CR sigsend() fails, it sets errno (see .IR errno (2)) to one of the following values: .RS .TP 15 [EINVAL] .I sig is neither a valid signal number nor zero. .TP [EINVAL] .I idtype is not a valid value. .TP [EINVAL] .I sig is .CR SIGKILL , .I idtype is .CR P_PID , and .I id is .CR 1 . .TP [ESRCH] No process can be found corresponding to that specified by .I id and .IR idtype . .TP [EPERM] The user ID of the sending process is not 0, and its real or effective user ID does not match the real or effective user ID of the receiving process, and the calling process is not sending .CR SIGCONT to a process that shares the same session ID. .SH SEE ALSO kill(2), signal(2). .\" .\" toc@\f3sigsend(2)\f1:\0\0\f4sigsend()\f1, \f4sigsendset()\f1@@@send a signal to a process or a group of processes .\" toc@\f4sigsendset()\f1:\0\0send a signal to a group of processes@@@\f1see \f3sigsend(2)\f1 .\" .\" index@\f4sigsend()\f1 \- send a signal to a process@@@\f3sigsend(2)\f1 .\" index@\f4sigsendset()\f1 \- send a signal to a group of processes@@@\f3sigsend(2) \f1 .\" index@\f1send a signal to a process or a group of processes@@@\f3sigsend(2)\f1 .\" index@\f1signal, send to a process or a group of processes@@@\f3sigsend(2)\f1 .\" links@sigsend.2 sigsendset.2 .\" $Header: signal.2,v 76.2 95/07/24 16:18:01 ssa Exp $ .TA s .TH signal 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME signal, sigset, sighold, sigrelse, sigignore, sigpause \-signal management .SH SYNOPSIS .C "#include " .PP .C "void (*signal(int sig, void (*func)(int)))(int);" .PP .C "int sighold(int sig);" .PP .C "int sigignore(int sig);" .PP .C "int sigpause(int sig);" .PP .C "int sigrelse(int sig);" .PP .C "void (*sigset(int sig, void (*disp)(int)))(int);" .SH DESCRIPTION The .CR signal() function chooses one of three ways in which receipt of the signal number .IR sig is to be subsequently handled. If the value of func is .CR SIG_DFL , default handling for that signal will occur. If the value of .IR func is .CR SIG_IGN , the signal will be ignored. Otherwise, .IR func must point to a function to be called when that signal occurs. Such a function is called a signal handler. .PP When a signal occurs, if .IR func points to a function, first the equivalent of a: .IP .C signal(sig, SIG_DFL); .PP is executed or an implementation-dependent blocking of the signal is performed. (If the value of .IR sig is .CR SIGILL , whether the reset to .CR SIG_DFL occurs is implementation-dependent.) Next the equivalent of: .IP .C (*func)(sig); .PP is executed. The .IR func function may terminate by executing a return statement or by calling .CR abort() , .CR exit() , or .CR longjmp() . If .CR func() executes a return statement and the value of .IR sig was .CR SIGFPE or any other implementation-dependent value corresponding to a computational exception, the behaviour is undefined. Otherwise, the program will resume execution at the point it was interrupted. .PP If the signal occurs other than as the result of calling .CR abort() , .CR kill() or .CR raise() , the behaviour is undefined if the signal handler calls any function in the standard library other than one of the functions listed on the .I sigaction() page or refers to any object with static storage duration other than by assigning a value to a static storage duration variable of type volatile .IR sig_atomic_t . Furthermore, if such a call fails, the value of .CR errno is indeterminate. .PP At program startup, the equivalent of: .IP .C signal(sig, SIG_IGN); .PP is executed for some signals, and the equivalent of: .IP .C signal(sig, SIG_DFL); .PP is executed for all other signals (see .CR exec ). .PP The .CR sigset() , .CR sighold() , .CR sigignore() , .CR sigpause() and .CR segrelse() functions provide simplified signal management. .PP The .CR sigset() function is used to modify signal dispositions. The .IR sig argument specifies the signal, which may be any signal except .CR SIGKILL and .CR SIGSTOP . The .IR disp argument specifies the signal's disposition, which may be .CR SIG_DFL , .CR SIG_IGN or the address of a signal handler. If .CR sigset() is used, and .IR disp is the address of a signal handler, the system will add .IR sig to the calling process' signal mask before executing the signal handler; when the signal handler returns, the system will restore the calling process' signal mask to its state prior the delivery of the signal. In addition, if .CR sigset() is used, and .IR disp is equal to .CR SIG_HOLD , .IR sig will be added to the calling process' signal mask and .IR sig 's disposition will remain unchanged. If .CR sigset() is used, and .IR disp is not equal to .CR SIG_HOLD , .IR sig will be removed from the calling process' signal mask. .PP The .CR sighold() function adds .IR sig to the calling process' signal mask. .PP The .CR sigrelse() function removes .IR sig from the calling process' signal mask. .PP The .CR sigignore() function sets the disposition of .IR sig to .CR SIG_IGN . .PP The sigpause() function removes .IR sig from the calling process' signal mask and suspends the calling process until a signal is received. .PP If the action for the .CR SIGCHLD signal is set to .CR SIG_IGN , child processes of the calling processes will not be transformed into zombie processes when they terminate. If the calling process subsequently waits for its children, and the process has no unwaited for children that were transformed into zombie processes, it will block until all of its children terminate, and .CR wait() , .CR wait3() , .CR waitid() and .CR waitpid() will fail and set .CR errno to .CR ECHILD . .SH RETURN VALUE If the request can be honoured, .CR signal() returns the value of .CR func() for the most recent call to .CR signal() for the specified signal .IR sig . Otherwise, .CR SIG_ERR is returned and a positive value is stored in .CR errno . .PP Upon successful completion, .CR sigset() returns .CR SIG_HOLD if the signal had been blocked and the signal's previous disposition if it had not been blocked. Otherwise, .CR SIG_ERR is returned and .CR errno is set to indicate the error. .PP For all other functions, upon successful completion, 0 is returned. Otherwise, \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR signal() function will fail if: .RS .TP 15 [EINVAL] The .IR sig argument is not a valid signal number or an attempt is made to catch a signal that cannot be caught or ignore a signal that cannot be ignored. .RE .PP The .CR signal() function may fail if: .RS .TP 15 [EINVAL] An attempt was made to set the action to .CR SIG_DFL for a signal that cannot be caught or ignored (or both). .RE .PP The .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() functions will fail if: .RS .TP 15 [EINVAL] The .IR sig argument is an illegal signal number. .RE .PP The .CR sigset() , and .CR sigignore() functions will fail if: .RS .TP 15 [EINVAL] An attempt is made to catch a signal that cannot be caught, or to ignore a signal that cannot be ignored. .RE .SH APPLICATION USAGE The .CR sigaction() function provides a more comprehensive and reliable mechanism for controlling signals; new applications should use .CR sigaction() rather than .CR signal() . .PP The .CR sighold() function, in conjunction with .CR sigrelse() or .CR sigpause() , may be used to establish critical regions of code that require the delivery of a signal to be temporarily deferred. .PP The .CR sigsuspend() function should be used in preference to .CR sigpause() for broader portability. .SH SEE ALSO exec, pause(), sigaction(), waitid(), . .SH CHANGE HISTORY First released in Issue 1. .PP Derived from Issue 1 of the SVID. .SH Issue 4 The following changes are incorporated for alignment with the ISO C standard: .RS .TP 10 \- The function is no longer marked as an extension. .TP \- The argument int is added to the definition of .CR func() in the SYNOPSIS section. .TP \- In Issue 3, this interface cross-referred to .CR sigaction() . This issue provides a complete description of the function as defined in ISO C standard. .RE .PP Another change is incorporated as follows: .RS .TP 10 \- The APPLICATION USAGE section is added. .SH Issue 4, Version 2 The following changes are incorporated for X/OPEN UNIX conformance: .RS .TP 10 \- The .CR sighold() , .CR sigignore() , .CR sigpause() , .CR sigrelse() , and .CR sigset() functions are added to the SYNOPSIS. .TP \- The DESCRIPTION is updated to describe semantics of the above interfaces. .TP \- Additional text is added to the RETURN VALUE section to describe possible returns from the .CR sigset() function specifically, and all of the above functions in general. .TP \- The ERRORS section is restructured to describe possible error returns from each of the above functions individually. .TP \- The APPLICATION USAGE section is updated to describe certain programming considerations associated with the X/OPEN UNIX functions. .\" $Header: signal.2,v 76.2 95/07/24 16:18:01 ssa Exp $ .TA s .TH signal 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH SYNOPSIS .PP .C "void (*signal(int sig, void (*action)(int)))(int);" .PP .C "void (*sigset(int sig, void (*func)(int)))(int);" .PP .SH DESCRIPTION .PP The system defines a set of signals that can be delivered to a process. The set of signals is defined in .IR signal (5), along with the meaning and side effects of each signal. An alternate mechanism for handling these signals is defined here. The facilities described here should not be used in conjunction with the other facilities described under .CR signal(2) , .CR sigvector(2) , .CR sigblock(2) , .CR sigsetmask(2) , .CR sigpause(2) , and .CR sigspace(2) . .PP Acceptable values for .I sig are defined in .CR . .PP .RS .TP 12 .C SIG_DFL Execute the default action, which varies depending on the signal. The default action for most signals is to terminate the process (see .IR signal (5)). .IP A pending signal is discarded (whether or not it is blocked) if .I action is set to .C SIG_DFL but the default action of the pending signal is to ignore the signal (as in the case of .CR SIGCLD ). .TP .C SIG_IGN Ignore the signal. .br When .C signal() is called with .I action set to .C SIG_IGN and an instance of the signal .I sig is pending, the pending signal is discarded, whether or not it is blocked. .IP .C SIGKILL and .C SIGSTOP signals cannot be ignored. .TP .I address Catch the signal. .br Upon receipt of signal .IR sig , reset the value of .I action for the caught signal to .SM SIG_DFL (except signals marked with "not reset when caught"; see .IR signal (5)), call the signal-catching function to which .IR address points, and resume executing the receiving process at the point where it was interrupted. .IP The signal-catching function is called with the following three parameters: .RS .RS .TP 8 .I sig The signal number. .TP .I code A word of information usually provided by the hardware. .TP .I scp A pointer to the machine-dependent structure .I sigcontext defined in .RC < signal.h >. .RE .RE .IP The pointer .I scp is valid only during the context of the signal-catching function. The structure pointer .I scp is always defined. .IP The .I code word is always zero for all signals except .C SIGILL and .CR SIGFPE . For .CR SIGILL , .I code has the following values: .RS .RS .TP 8 .C 8 illegal instruction trap; .PD 0 .TP .C 9 break instruction trap; .TP .C 10 privileged operation trap; .TP .C 11 privileged register trap. .RE .PD .PP For .CR SIGFPE , .I code has the following values: .RS .TP 8 .C 12 overflow trap; .PD 0 .TP .C 13 conditional trap; .TP .C 14 assist exception trap; .TP .C 22 assist emulation trap. .RE .PD .PP As defined by the .SM IEEE POSIX Standard, .SM HP-UX does not raise an exception on floating-point divide by zero. The result of floating-point divide by zero is infinity which can be checked by .IR isinf (3M). .PP The signals .C SIGKILL and .C SIGSTOP cannot be caught. .RE .PP .CR sigset() allows the calling process to choose one of four ways to handle the receipt of a specific signal. .IR sig specifies the signal and .IR func specifies the choice. .PP .IR sig can be any one of the signals described under .IR signal (5) except .CR SIGKILL or .CR SIGSTOP . .PP .IR func is assigned one of four values: .CR SIG_DFL , .CR SIG_IGN , .CR SIG_HOLD , or a function address. The actions prescribed by .CR SIG_DFL and .CR SIG_IGN are described under .IR signal (5). The action prescribed by .CR SIG_HOLD and function address are described below: .RS .TP 25 .C SIG_HOLD Hold signal. The signal .IR sig is held upon receipt. Any pending signal of this signal type remains held. Only one signal of each type is held. Note: the signals .CR SIGKILL , .CR SIGCONT , and .CR SIGSTOP cannot be held. .TP 5 function address Catch signal. .IR func must be a pointer to a function, the signal\- catching handler, that is called when signal .IR sig occurs. .CR sigset() specifies that the process calls this function upon receipt of signal .IR sig . Any pending signal of this type is released. This handler address is retained across calls to the other signal management functions listed here. Upon receipt of signal .IR sig , the receiving process executes the signal\-catching function pointed to by .IR func as described under .IR signal (5) with the following differences: .PP Before calling the signal\-catching handler, the system signal action of .IR sig is set to .CR SIG_HOLD . During a normal return from the signal\-catching handler, the system signal action is restored to .IR func and any held signal of this type is released. If a non\-local goto .RC ( longjmp(3C) ) is taken, .CR sigrelse() must be called to restore the system signal action to .IR func and release any held signal of this type. .RE .PP .CR sighold() holds the signal .IR sig . .CR sigrelse() restores the system signal action of .IR sig to that specified previously by .CR sigset() . .CR sighold() and .CR sigrelse() are used to establish critical regions of code. .CR sighold() is analogous to raising the priority level and deferring or holding a signal until the priority is lowered by .CR sigrelse() . .PP .CR sigignore() sets the action for signal .IR sig to .CR SIG_IGN (see .IR signal (5)). .PP .CR sigpause() suspends the calling process until it receives an unblocked signal. If the signal .IR sig is held, it is released before the process pauses. .CR sigpause() is useful for testing variables that are changed when a signal occurs. For example, .CR sighold() should be used to block the signal first, then test the variables. If they have not changed, call .CR sigpause() to wait for the signal. .PP These functions can be linked into a program by giving the \-lV3 option to the .CR ld command (see .IR ld (1)). .SH ERRORS .CR sigset() fails and the system signal action for .IR sig is not changed if any of the following occur: .RS .TP 25 [EFAULT] The .IR func argument points to memory that is not a valid part of the process address space. Reliable detection of this error is implementation\-dependent. .RE .PP .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() fail and the system signal action for .IR sig is not changed if any of the following occur: .RS .TP 25 [EINVAL] An attempt is made to ignore, hold, or supply a handler for a signal that cannot be ignored, held, or caught; see .IR signal (5). .RE .PP .CR sigpause returns when the following occurs: .RS .TP 25 [EINTR] A signal was caught. .RE .SH EXAMPLES The following call to .C signal() sets up a signal-catching function for the .C SIGINT signal: .IP .C void myhandler(); .IP .C (void) signal(SIGINT, myhandler); .SH WARNINGS .C signal() should not be used in conjunction with the facilities described under .IR bsdproc (2), .IR sigaction (2), .IR sigset (2V), or .IR sigvector (2). .PP .C signal() does not detect an invalid value for .IR action , and if it does not equal .C SIG_DFL or .CR SIG_IGN, or point to a valid function address, subsequent receipt of the signal .IR sig causes undefined results. .RE .SH AUTHOR .C signal() was developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO kill(1), init(1M), exit(2), kill(2), lseek(2), pause(2), sigaction(2), sigvector(2), wait(2), abort(3C), setjmp(3C), signal(5). .SH STANDARDS CONFORMANCE .CR signal() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4signal()\f1 \- specify what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f4sigset()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sighold()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sigrelse()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f4sigignore()\f1 \- signal management@@@\f3signal(2)\f1 .\" index@\f1specify what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f1define what to do upon receipt of a signal@@@\f3signal(2)\f1 .\" index@\f1receipt of a signal, define what to do upon@@@\f3signal(2)\f1 .\" index@\f1signal, define what to do upon receipt of a@@@\f3signal(2)\f1 .\" .\" toc@\f3signal(2)\f1:\0\0\f4signal()\f1, \f4sigset()\f1, \f4sighold()\f1, \f4sigrelse()\1, \f4sigignore()\f1, \f4sigpause\f1@@@signal management .\" toc@\f4sigset()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sighold()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigrelse()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigignore()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" toc@\f4sigpause()\f1:\0\0signal management@@@see \f3signal(2)\f1 .\" .\" links@signal.2 sigset.2 .\" links@signal.2 sighold.2 .\" links@signal.2 sigrelse.2 .\" links@signal.2 sigignore.2 .\" $Header: sigset.2v,v 72.4 94/11/14 15:26:38 ssa Exp $ .TA s .TH sigset 2V .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigset, sighold, sigrelse, sigignore, sigpause \- signal management .SH SYNOPSIS .C "#include " .PP .C "void (*sigset(int sig, void (*func)(int)))(int);" .PP .C "int sighold(int sig);" .PP .C "int sigrelse(int sig);" .PP .C "int sigignore(int sig);" .PP .C "int sigpause(int sig);" .SH DESCRIPTION The system defines a set of signals that can be delivered to a process. The set of signals is defined in .IR signal (5), along with the meaning and side effects of each signal. An alternate mechanism for handling these signals is defined here. The facilities described here should not be used in conjunction with the other facilities described under .IR signal (2), .IR sigvector (2), .IR sigblock (2), .IR sigsetmask (2), .IR sigpause (2) and .IR sigspace (2). .PP .C sigset() allows the calling process to choose one of four ways to handle the receipt of a specific signal. .IR sig specifies the signal and .IR func specifies the choice. .PP .I sig can be any one of the signals described under .IR signal (5) except .C SIGKILL or .CR SIGSTOP . .PP .I func is assigned one of four values: .CR SIG_DFL , .CR SIG_IGN , .CR SIG_HOLD , or a .IR "function address" . The actions prescribed by .C SIG_DFL and .C SIG_IGN are described under .IR signal (5). The action prescribed by .C SIG_HOLD and .IR "function address" are described below: .TP 15 .C SIG_HOLD Hold signal. .br The signal .IR sig is held upon receipt. Any pending signal of this signal type remains held. Only one signal of each type is held. .IP Note: the signals .CR SIGKILL , .CR SIGCONT , and .C SIGSTOP cannot be held. .PD .TP 15 .I function address Catch signal. .br .IR func must be a pointer to a function, the signal-catching handler, that is called when signal .IR sig occurs. .C sigset() specifies that the process calls this function upon receipt of signal .IR sig . Any pending signal of this type is released. This handler address is retained across calls to the other signal management functions listed here. Upon receipt of signal .IR sig , the receiving process executes the signal-catching function pointed to by .IR func as described under .IR signal (5) with the following differences: .IP Before calling the signal-catching handler, the system signal action of .IR sig is set to .CR SIG_HOLD . During a normal return from the signal-catching handler, the system signal action is restored to .IR func and any held signal of this type is released. If a non-local goto .IR (longjmp (3C)) is taken, .C sigrelse() must be called to restore the system signal action to .IR func and release any held signal of this type. .PP .C sighold() holds the signal .IR sig. .C sigrelse() restores the system signal action of .IR sig to that specified previously by .CR sigset() . .C sighold() and .C sigrelse() are used to establish critical regions of code. .C sighold() is analogous to raising the priority level and deferring or holding a signal until the priority is lowered by .CR sigrelse() . .PP .C sigignore() sets the action for signal .IR sig to .C SIG_IGN (see .IR signal (5)). .PP .C sigpause() suspends the calling process until it receives an unblocked signal. If the signal .I sig is held, it is released before the process pauses. .C sigpause() is useful for testing variables that are changed when a signal occurs. For example, .C sighold() should be used to block the signal first, then test the variables. If they have not changed, call .C sigpause() to wait for the signal. .PP These functions can be linked into a program by giving the .C \-lV3 option to the .C ld command (see .IR ld (1)). .SH RETURN VALUE Upon successful completion, .C sigset() returns the previous value of the system signal action for the specified signal .IR sig . Otherwise, a value of .C SIG_ERR is returned and .C errno is set to indicate the error. .C SIG_ERR is defined in .RC < signal.h >. .PP For the other functions, a 0 value indicates that the call succeeded. A \-1 return value indicates an error occurred and .C errno is set to indicate the reason. .SH ERRORS .C sigset() fails and the system signal action for .I sig is not changed if any of the following occur: .RS .TP 20 [EFAULT] The .I func argument points to memory that is not a valid part of the process address space. Reliable detection of this error is implementation dependent. .RE .PP .CR sigset() , .CR sighold() , .CR sigrelse() , .CR sigignore() , and .CR sigpause() fail and the system signal action for .I sig is not changed if any of the following occur: .RS .TP 20 .SM [EINVAL] .I sig is not a valid signal number. .TP .SM [EINVAL] An attempt is made to ignore, hold, or supply a handler for a signal that cannot be ignored, held, or caught; see .IR signal (5). .RE .PP .IR sigpause returns when the following occurs: .RS .TP 20 .SM [EINTR] A signal was caught. .RE .SH WARNINGS These signal facilities should not be used in conjunction with .IR bsdproc (2), .IR signal (2), .IR sigvector (2), .IR sigblock (2), .IR sigsetmask (2), .IR sigpause (2) and .IR sigspace (2). .SH SEE ALSO kill(1), kill(2), signal(2), pause(2), wait(2), abort(3C), setjmp(3C), signal(5). .SH STANDARDS CONFORMANCE .CR sigset() ": SVID2, SVID3" .PP .CR sighold() ": SVID2, SVID3" .PP .CR sigignore() ": SVID2, SVID3" .PP .CR sigpause() ": SVID2, SVID3" .PP .CR sigrelse() ": SVID2, SVID3" .\" .\" index@\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigignore()\fP, \f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@\f4sigpause()\fP, \f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP \- signal management@@@\f3sigset(2V)\f1 .\" index@signal management (\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP)@@@\f3sigset(2V)\f1 .\" index@management, signal (\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP)@@@\f3sigset(2V)\f1 .\" index@hold signal upon receipt@@@\f3sigset(2V)\f1 .\" index@signal, hold upon receipt@@@\f3sigset(2V)\f1 .\" index@ignore signal@@@\f3sigset(2V)\f1 .\" index@signal, ignore@@@\f3sigset(2V)\f1 .\" index@restore signal action@@@\f3sigset(2V)\f1 .\" index@signal, restore action@@@\f3sigset(2V)\f1 .\" index@signal, suspend calling process until received@@@\f3sigset(2V)\f1 .\" index@signal, select method of handling@@@\f3sigset(2V)\f1 .\" .\" toc@\f3sigset(2V)\f1:\0\0\f4sigset()\fP, \f4sighold()\fP, \f4sigrelse()\fP, \f4sigignore()\fP, \f4sigpause()\fP@@@signal management .\" toc@\f4sighold()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigrelse()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigignore()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" toc@\f4sigpause()\fP:\0\0signal management@@@see \f3sigset(2V)\f1 .\" .\" links@sigset.2v sighold.2v .\" links@sigset.2v sigrelse.2v .\" links@sigset.2v sigignore.2v .\" links@sigset.2v sigpause.2v .\" .\" fileset_database@sigset.2v PROGRAMING-MAN .\" $Header: sigsetmask.2,v 74.1 95/05/10 21:17:22 ssa Exp $ .TA s .TH sigsetmask 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigsetmask \- set current signal mask .SH SYNOPSIS .C "#include " .PP .C "long sigsetmask(long mask);" .SH DESCRIPTION .C sigsetmask() sets the current signal mask (those signals that are blocked from delivery). Signal .I i is blocked if the .IR i -th bit in .IR mask , as specified with the macro .CR sigmask(\f2i\fP) , is a .CR 1 . .PP It is not possible to mask signals that cannot be ignored, as documented in .IR signal (5); this restriction is silently imposed by the system. .PP .C sigblock() can be used to add elements to the set of blocked signals. .SH RETURN VALUE The previous set of masked signals is returned. .SH EXAMPLES The following call to .C sigsetmask() causes only the .C SIGUSR1 and .C SIGUSR2 signals to be blocked: .IP .C long oldmask; .IP .C "oldmask = sigsetmask (sigmask (SIGUSR1) | sigmask (SIGUSR2));" .SH WARNINGS Do not use .C sigsetmask() in conjunction with the facilities described under .IR sigset (2V). .SH AUTHOR .C sigsetmask() was developed by the University of California, Berkeley. .SH SEE ALSO kill(2), sigblock(2), sigpause(2), sigprocmask(2), sigvector(2). .\" .\" toc@\f3sigsetmask(2)\f1:\0\0\f4sigsetmask()\f1@@@set current signal mask .\" .\" index@\f4sigsetmask()\f1 \- set current signal mask@@@\f3sigsetmask(2)\f1 .\" index@\f1set current signal mask@@@\f3sigsetmask(2)\f1 .\" index@\f1set current ignorable signals mask@@@\f3sigsetmask(2)\f1 .\" index@\f1ignorable signals mask, set current@@@\f3sigsetmask(2)\f1 .\" index@\f1signals mask, set current ignorable@@@\f3sigsetmask(2)\f1 .\" index@\f1mask, set current ignorable signals@@@\f3sigsetmask(2)\f1 .\" .\" $Header: sigspace.2,v 72.4 94/09/06 15:07:47 ssa Exp $ .TA s .TH sigspace 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigspace \- assure sufficient signal stack space .SH SYNOPSIS .C "#include " .PP .C "size_t sigspace(size_t stacksize);" .SH DESCRIPTION .C sigspace() requests additional stack space that is guaranteed to be available for processing signals received by the calling process. .PP If the value of .I stacksize is positive, it specifies the size of a space, in bytes, which the system guarantees to be available when processing a signal. If the value of .I stacksize is zero, any guarantee of space is removed. If the value is negative, the guarantee is left unchanged; this can be used to interrogate the current guaranteed value. .PP When a signal's action indicates that its handler should use the guaranteed space (specified with a .CR sigaction() , .CR sigvector() , or .C sigvec() call (see .IR bsdproc (2)), the system checks to see if the process is currently using that space. If the process is not currently using that space, the system arranges for that space to be available for the duration of the signal handler's execution. If that space has already been made available (due to a previous signal) no change is made. Normal stack discipline is resumed when the signal handler first using the guaranteed space is exited. .PP The guaranteed space is inherited by child processes resulting from a successful .C fork() system call, but the guarantee of space is removed after any .C exec() system call (see .IR fork (2) and .IR exec (2)). .PP The guaranteed space cannot be increased in size automatically, as is done for the normal stack. If the stack overflows the guaranteed space, the resulting behavior of the process is undefined. .PP Guaranteeing space for a stack can interfere with other memory allocation routines in an implementation-dependent manner. .PP During normal execution of the program the system checks for possible overflow of the stack. Guaranteeing space might cause the space available for normal execution to be reduced. .PP Leaving the context of a service routine abnormally, such as by .C longjmp() (see .IR setjmp (3C)), removes the guarantee that the ordinary execution of the program will not extend into the guaranteed space. It might also cause the program to lose forever its ability to automatically increase the stack size, causing the program to be limited to the guaranteed space. .SH RETURN VALUE Upon successful completion, .C sigspace() returns the size of the former guaranteed space. Otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C sigspace() fails and the guaranteed amount of space remains unchanged if the following occurs: .RS .TP 20 .SM [ENOMEM] The requested space cannot be guaranteed, either because of hardware limitations or because some software-imposed limit would be exceeded. .RE .SH WARNINGS The guaranteed space is allocated using .IR malloc (3C). This use might interfere with other heap management mechanisms. .PP Methods for calculating the required size are not well developed. .PP Do not use .C sigspace() in conjunction with the facilities described under .IR sigset (2V). .PP Do not use .C sigspace() in conjunction with .IR sigstack (2). .SH AUTHOR .C sigspace() was developed by HP. .SH SEE ALSO sigaction(2), sigstack(2), sigvector(2), malloc(3C), setjmp(3C). .\" index@\f4sigspace()\fP \(mi define or delete additional signal stack space@@@\f3sigspace(2)\f1 .\" index@define additional signal stack space@@@\f3sigspace(2)\f1 .\" index@determine current signal stack space@@@\f3sigspace(2)\f1 .\" index@delete allocated signal stack space@@@\f3sigspace(2)\f1 .\" index@signal stack space, define, delete, or get amount of@@@\f3sigspace(2)\f1 .\" index@stack space for signals, define, delete, or get amount of@@@\f3sigspace(2)\f1 .\" index@space for signal stack, define, delete, or get amount of@@@\f3sigspace(2)\f1 .\" .\" toc@\f3sigspace(2)\f1:\0\0\f4sigspace()\fP@@@assure sufficient signal stack space .\" $Header: sigstack.2,v 76.1 95/07/07 14:56:22 ssa Exp $ .TA s .TH sigstack 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigstack \- set and/or get signal stack context .SH SYNOPSIS .C "#include " .PP .nf .PD 0 .C "int sigstack(" .IP .C "struct sigstack *ss," .C "struct sigstack *oss" .PP .C ");" .PD .fi .SH DESCRIPTION The .CR sigstack() function allows the calling process to indicate to the system an area of its address space to be used for processing signals received by the process. .PP If the .IR ss argument is not a null pointer, it must point to a sigstack structure. The length of the application-supplied stack must be at least .CR SIGSTKSZ bytes. If the alternate signal stack overflows, the resulting behaviour is undefined. (See APPLICATION USAGE below.) .P .RS .TP 3 \(bu The value of the .IR ss_onstack member indicates whether the process wants the system to use an alternate signal stack when delivering signals. .TP 3 \(bu The value of the .IR ss_sp member indicates the desired location of the alternate signal stack area in the process' address space. .TP 3 \(bu If the .IR ss argument is a null pointer, the current alternate signal stack context is not changed. .RE .P .PP If the .IR oss argument is not a null pointer, it points to a sigstack structure in in which the current alternate signal stack context is placed. The value stored in the .IR ss_onstack member of .IR oss will be non- zero if the process is currently executing on the alternate signal stack. If the .IR oss argument is a null pointer, the current alternate signal stack context is not returned. .PP When a signal's action indicates its handler should execute on the alternate signal stack (specified by calling .CR sigaction() ), the implementation checks to see if the process is currently executing on that stack. If the process is not currently executing on the alternate signal stack, the system arranges a switch to the alternate signal stack for the duration of the signal handler's execution. .PP After a successful call to one of the .CR exec functions, there are no alternate signal stacks in the new process image. .SH RETURN VALUE Upon successful completion, .CR sigstack() returns 0. Otherwise, it returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS The .CR sigstack() function will fail if: .RS .TP 15 [EPERM] An attempt was made to modify an active stack. .SH APPLICATION USAGE A portable application, when being written or rewritten, should use .CR sigaltstack() instead of .CR sigstack() . .PP On some implementations, stack space is automatically extended as needed. On those implementations, automatic extension is typically not available for an alternate stack. If a signal stack overflows, the resulting behaviour of the process is undefined. .PP The direction of stack growth is not indicated in the historical definition of struct .IR sigstack . The only way to portably establish a stack pointer is for the application to determine stack growth direction, or to allocate a block of storage and set the stack pointer to the middle. The implementation may assume that the size of the signal stack is .CR SIGSTKSZ as found in .CR . An implementation that would like to specify a signal stack size other than .CR SIGSTKSZ should use .CR sigaltstack() . .PP Programs should not use .CR longjmp() to leave a signal handler that is running on a stack established with .CR sigstack() . Doing so may disable future use of the signal stack. For abnormal exit from a signal handler, .CR siglongjmp() , .CR setcontext() , or .CR swapcontext() may be used. These functions fully support switching from one stack to another. .PP The .CR sigstack() function requires the application to have knowledge of the underlying system's stack architecture. For this reason, .CR sigaltstack() is recommended over this function. .SH SEE ALSO exec, fork(), _longjmp(), longjmp(), setjmp(), sigaltstack(), siglongjmp(), sigsetjmp(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" $Header: sigstack.2,v 76.1 95/07/07 14:56:22 ssa Exp $ .TA s .TH sigstack 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH SYNOPSIS .PP .nf .PD 0 .C "int sigstack(" .IP .C "const struct sigstack *ss," .C "struct sigstack *oss" .PP .C ");" .PD .fi .SH DESCRIPTION The correct use of .C sigstack() is hardware dependent, and therefore is not portable between different HP-UX implementations. .CR sigspace() is portable between different HP-UX implementations and should be used when the application does not need to know where the signal stack is located (see .IR sigspace (2)). .C sigstack() is provided for compatibility with other systems that provide this functionality. Users should note that there is no guarantee that functionality similar to this is even possible on some architectures. .PP The value stored in the .I ss_onstack member tells whether the process is currently using a signal stack, and if so, the value stored in the .I ss_sp member is the current stack pointer for the stack in use. .SH ERRORS .RS .TP 20 [EFAULT] Either of .I ss or .I oss is not a null pointer and points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .RE .SH WARNINGS Do not use .IR sigstack (2) in conjunction with .IR sigspace (2). .PP Methods for calculating the required stack size are not well developed. .PP Leaving the context of a service routine abnormally, such as by .C longjmp() (see .IR setjmp (3C)), might remove the guarantee that the ordinary execution of the program does not extend into the guaranteed space. It might also cause the program to lose forever its ability to automatically increase the stack size, causing the program to be limited to the guaranteed space. .PP Stack addresses grow from low addresses to high addresses; therefore the signal stack address provided to .IR sigstack (2) should point to the beginning of the space to be used for the signal stack. This address should be aligned to an eight-byte boundary. .SH AUTHOR .C sigstack() was developed by HP and the University of California, Berkeley. .SH SEE ALSO sigspace(2), setjmp(3C). .\" toc@\f3sigstack(2)\f1:\0\0\f4sigstack()\fP@@@set and/or get signal stack context .\" index@\f4sigstack()\f1 \- set and/or get signal stack context@@@\f3sigstack(2)\f1 .\" index@set and/or get signal stack context@@@\f3sigstack(2)\f1 .\" index@get and/or set signal stack context@@@\f3sigstack(2)\f1 .\" index@signal stack context, set and/or get@@@\f3sigstack(2)\f1 .\" index@stack context, signal, set and/or get@@@\f3sigstack(2)\f1 .\" index@context, signal stack, set and/or get@@@\f3sigstack(2)\f1 .\" $Header: sigsuspend.2,v 76.1 95/07/07 14:56:49 ssa Exp $ .TA s .TH sigsuspend 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigsuspend \- wait for a signal .SH SYNOPSIS .C "#include " .PP .C "int sigsuspend(const sigset_t *sigmask);" .SH DESCRIPTION The .CR sigsuspend() function replaces the process' current signal mask with the set of signals pointed to by .CR sigmask and then suspends the process until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process. .PP If the action is to terminate the process then .CR sigsuspend() will never return. If the action is to execute a signal-catching function, then .CR sigsuspend() will return after the signal-catching function returns, with the signal mask restored to the set that existed prior to the .CR sigsuspend() call. .PP It is not possible to block signals that cannot be ignored. This is enforced by the system without causing an error to be indicated. .SH RETURN VALUE Since .CR sigsuspend() suspends process execution indefinitely, there is no successful completion return value. If a return occurs, \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR sigsuspend() function will fail if: .RS .TP 25 [EINTR] A signal is caught by the calling process and control is returned from the signal-catching function. .RE .SH SEE ALSO pause(), sigaction(), sigaddset(), sigdelset(), sigemptyset(), sigfillset(), . .SH CHANGE HISTORY First released in Issue 3. .PP Entry included for alignment with the POSIX.1-1988 standard. .SH Issue 4 The following change is incorporated for alignment with the ISO POSIX-1 standard: .P .RS .TP 3 \(bu The type of the argument .IR sigmask is changed from .IR sigset_t* to type .IR const sigset_t* . .RE .P Another change is incorporated as follows: .P .RS .TP 3 \(bu The term "signal handler" is changed to "signal-catching function." .RE .P .\" $Header: sigsuspend.2,v 76.1 95/07/07 14:56:49 ssa Exp $ .TA s .TH sigsuspend 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH ERRORS .RS .TP 15 [EFAULT] .I sigmask points to an invalid address. The reliable detection of this error is implementation dependent. .RE .SH AUTHOR .C sigsuspend() was derived from the IEEE POSIX 1003.1-1988 Standard. .SH SEE ALSO sigaction(2), sigpending(2), sigprocmask(2), sigsetops(3C), signal(5). .SH STANDARDS CONFORMANCE .CR sigsuspend() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4sigsuspend()\f1 \- wait for a signal@@@\f3sigsuspend(2)\f1 .\" index@\f1wait for a signal@@@\f3sigsuspend(2)\f1 .\" index@\f1signal, wait for a@@@\f3sigsuspend(2)\f1 .\" .\" toc@\f3sigsuspend(2)\f1:\0\0\f4sigsuspend()\f1@@@wait for a signal .\" .\" fileset_database@sigsuspend.2 PROGRAMING-MAN .\" $Header: bsdproc.2,v 72.3 93/01/14 14:32:23 ssa Exp $ .TA b .TH bsdproc 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME killpg, getpgrp, setpgrp, sigvec, signal \- 4.2 \s-1BSD\s0-compatible process control facilities .SH SYNOPSIS .C "#include " .PP .C "int killpg(int pgrp, int sig);" .PP .C "int getpgrp(int pid);" .PP .C "int setpgrp(int pid, int pgrp);" .PP .C "int sigvec(" .PD 0 .nf .IP .C "int sig," .C "struct sigvec *vec," .C "struct sigvec *ovec" .PP .C ");" .fi .PD .PP .C "void (*signal(int sig, void (*func)(int)))(int);" .SH DESCRIPTION These calls simulate (and are provided for backward compatibility with) functions of the same name in the 4.2 Berkeley Software Distribution. .PP This version of .C setpgrp() is equivalent to the system call .IR setpgid ( \|pid , \ pgrp\| ) (see .IR setpgid (2)). .PP This version of .C getpgrp() is equivalent to the system call .CI getpgrp2( \|pid\| ) (see .IR getpid (2)). .PP .C killpg() is equivalent to the system call .CI kill(- pgrp , \0sig ) (see .IR kill (2)). .PP .C sigvec() is equivalent to the system call .CI sigvector( sig , .IC vec , \ ovec ) (see .IR sigvector (2)), except for the following: .IP When .SM SIGCHLD or .SM SIGCLD is used and .I vec specifies a catching function, the routine acts as if the .C SV_BSDSIG flag were included in the .C sv_flags field of .IR vec . .IP The name .C sv_onstack can be used as a synonym for the name of the .C sv_flags field of .I vec and .IR ovec . .IP If .I vec is not a null pointer and the value of .RI ( vec \(mi> sv_flags & 1) is "true", the routine acts as if the .C SV_ONSTACK flag were set. .IP If .I ovec is not a null pointer, the flag word returned in .IR ovec \(mi> sv_flags (and therefore the value of .IR ovec \(mi> sv_onstack ) will be equal to 1 if the system was reserving space for processing of that signal because of a call to .IR sigspace (2), and 0 if not. The .C SV_BSDSIG bit in the value placed in .IR ovec \(mi> sv_flags is always clear. .IP If the reception of a caught signal occurs during certain system calls, the call will always be restarted, regardless of the return value from a catching function installed with .CR sigvec() . The affected calls are .IR wait (2), .IR semop (2), .IR msgsnd (2), .IR msgrcv (2), and .IR read (2) or .IR write (2) on a slow device (such as a terminal or pipe, but not a file). Other interrupted system calls are not restarted. .PP This version of .C signal() has the same effect as .CR sigvec ( sig , .IC vec , \ ovec )\c \&, where .IR vec \(mi> sv_handler is equal to .IR func , .IR vec \(mi> sv_mask is equal to 0, and .IR vec \(mi> sv_flags is equal to 0. .C signal() returns the value that would be stored in .IR ovec \(mi> sv_handler if the equivalent .CR sigvec() call would have succeeded. Otherwise, .C signal() returns \(mi1 and .C errno is set to indicate the reason as it would have been set by the equivalent call to .CR sigvec() . .PP These functions can be linked into a program by giving the .C -lBSD option to .IR ld (1). .SH WARNINGS While the 4.3 .SM BSD release defined extensions to some of the interfaces described here, only the 4.2 .SM BSD interfaces are emulated by this package. .PP .C bsdproc() should not be used in conjunction with the facilities described under .IR sigset (2V). .SH AUTHOR .C bsdproc() was developed by HP and the University of California, Berkeley. .SH SEE ALSO ld(1), kill(2), getpid(2), msgsnd(2), msgrcv(2), read(2), semop(2), setpgid(2), setsid(2), sigvector(2), wait(2), write(2), sigset(2V), sigstack(2), signal(5). .\" index@\f4killpg()\fP \(mi 4.2 \s-1BSD\s+1-compatible \f4kill()\fP system call@@@\f3bsdproc(2)\f1 .\" index@\f4sigvec()\fP \(mi 4.2 \s-1BSD\s+1-compatible \f4sigvec()\fP system call@@@\f3bsdproc(2)\f1 .\" index@\f4signal()\fP \(mi 4.2 \s-1BSD\s+1-compatible \f4signal()\fP system call@@@\f3bsdproc(2)\f1 .\" index@\s-1BSD-4.2\s+1-compatible \f4kill()\fP, \f4sigvec()\fP, and \f4signal()\fP system calls@@@\f3bsdproc(2)\f1 .\" index@system calls, \s-1BSD-4.2\s+1-compatible \f4kill()\fP, \f4sigvec()\fP, and \f4signal()\fP@@@\f3bsdproc(2)\f1 .\" index@calls, system, \s-1BSD-4.2\s+1-compatible \f4kill()\fP, \f4sigvec()\fP, and \f4signal()\fP@@@\f3bsdproc(2)\f1 .\" index@\f4kill()\fP system call, 4.2 \s-1BSD\s+1-compatible@@@\f3bsdproc(2)\f1 .\" index@\f4sigvec()\fP system call, 4.2 \s-1BSD\s+1-compatible@@@\f3bsdproc(2)\f1 .\" index@\f4signal()\fP system call, 4.2 \s-1BSD\s+1-compatible@@@\f3bsdproc(2)\f1 .\" .\" toc@\f3bsdproc(2)\f1:\0\0\f4killpg()\fP, \f4getpgrp()\fP, \f4setpgrp()\fP, \f4sigvec()\fP,\n\f4signal()\fP@@@4.2 \s-1BSD\s+1-compatible process control facilities .\" toc@\f4killpg()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" toc@\f4getpgrp()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" toc@\f4setpgrp()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" toc@\f4sigvec()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" toc@\f4signal()\fP:\0\04.2 \s-1BSD\s+1-compatible process control facilities@@@see \f3bsdproc(2)\f1 .\" .\" links@bsdproc.2 killpg.2 .\" links@bsdproc.2 sigvec.2 .\" .\" fileset_database@bsdproc.2 PROGRAMING-MAN .\" $Header: sigvector.2,v 74.1 95/03/23 18:08:44 ssa Exp $ .TA s .TH sigvector 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigvector \- software signal facilities .SH SYNOPSIS .C "#include " .PP .nf .PD 0 .C "int sigvector(" .IP .C "int sig," .C "const struct sigvec *vec," .C "struct sigvec *ovec" .PP .C ");" .PD .fi .SH DESCRIPTION The system defines a set of signals that can be delivered to a process. The set of signals is defined in .IR signal (5), along with the meaning and side effects of each signal. This manual entry, along with those for .IR sigblock (2), .IR sigsetmask (2), .IR sigpause (2), and .IR sigspace (2), defines an alternate mechanism for handling these signals that ensures the delivery of signals and the integrity of signal handling procedures. The facilities described here should not be used in the same program as .IR signal (2). .PP With the .C sigvector() interface, signal delivery resembles the occurrence of a hardware interrupt: the signal is blocked from further occurrence, the current process context is saved, and a new one is built. A process can specify a handler function to be invoked when a signal is delivered, or specify that a signal should be blocked or ignored. A process can also specify that a default action should be taken by the system when a signal occurs. It is possible to ensure a minimum amount of stack space for processing signals using .C sigspace() (see .IR sigspace (2)). .PP All signals have the same priority. Signal routines execute with the signal that causes their invocation to be blocked, although other signals can yet occur. A global signal mask defines the set of signals currently blocked from delivery to a process. The signal mask for a process is initialized from that of its parent (normally .CR 0 ). It can be changed with a .CR sigblock() , .CR sigsetmask() , or .CR sigpause() call, or when a signal is delivered to the process. .PP A signal mask is represented as a .CR long , with one bit representing each signal being blocked. The following macro defined in .RC < signal.h > is used to convert a signal number to its corresponding bit in the mask: .RS .TP 35 .C #define\h'.2i'sigmask(signo) .C (1L << (signo-1)) .RE .PP When a signal condition arises for a process, the signal is added to a set of signals pending for the process. If the signal is not currently blocked by the process, it is delivered to the process. When a signal is delivered, the current state of the process is saved, a new signal mask is calculated (as described below), and the signal handler is invoked. The call to the handler is arranged so that if the signal handling routine returns normally, the process resumes execution in the same context as before the signal's delivery. If the process wishes to resume in a different context, it must arrange to restore the previous context itself. .PP When a signal is delivered to a process, a new signal mask is installed for the duration of the process' signal handler (or until a .C sigblock() or .C sigsetmask() call is made). This mask is formed by taking the current signal mask, computing the bit-wise inclusive .SM OR with the value of .IC vec . sv_mask (see below) from the most recent call to .C sigvector() for the signal to be delivered, and, unless the .C SV_RESETHAND flag is set (see below), setting the bit corresponding to the signal being delivered. When the user's signal handler returns normally, the original mask is restored. .PP .C sigvector() assigns a handler for the signal specified by .IR sig . .IR vec and .IR ovec are pointers to .IR sigvec structures that include the following elements: .RS .TP 8 .C void .CI (* sv_handler )(); .PD 0 .TP .C long .IC sv_mask ; .TP .C long .IC sv_flags ; .PD .RE .PP If .I vec is non-zero, it specifies a handler routine .RI ( sv_handler ), a mask .RI ( sv_mask ) that the system should use when delivering the specified signal, and a set of flags .RI ( sv_flags ) that modify the delivery of the signal. If .I ovec is non-zero, the previous handling information for the signal is returned to the user. If .I vec is zero, signal handling is unchanged. Thus, the call can be used to enquire about the current handling of a given signal. If .I vec and .I ovec point to the same structure, the value of .I vec is read prior to being overwritten. .PP The .I sv_flags field can be used to modify the receipt of signals. The following flag bits are defined: .RS .TP 25 .C SV_ONSTACK Use the .C sigspace() allocated space. .PD 0 .TP .C SV_BSDSIG Use the Berkeley signal semantics. .TP .C SV_RESETHAND Use the semantics of .IR signal (2). .PD .RE .PP If .C SV_ONSTACK is set, the system uses or permits the use of the space reserved for signal processing in the .C sigspace() system call. .PP If .C SV_BSDSIG is set, the signal is given the Berkeley semantics. The following signal is affected by this flag: .RS .TP 15 .C SIGCLD In addition to being sent when a child process dies, the signal is also sent when any child's status changes from running to stopped. This would normally be used by a program such as .C csh (see .IR csh (1)) when maintaining process groups under Berkeley job control. .RE .PP If .C SV_RESETHAND is set, the signal handler is installed with the same semantics as a handler installed with .IR signal (2). This affects signal mask set-up during the signal handler (see above) and whether the handler is reset after a signal is caught (see below). .PP If .C SV_RESETHAND is not set, once a signal handler is installed, it remains installed until another .C sigvector() call is made or an .C exec() system call is performed (see .IR exec (2)). If .C SV_RESETHAND is set and the signal is not one of those marked "not reset when caught" under .IR signal (5), the default action is reinstated when the signal is caught, prior to entering the signal-catching function. The "not reset when caught" distinction is not significant when .C sigvector() is called and .C SV_RESETHAND is not set. .PP The default action for a signal can be reinstated by setting .I sv_handler to .CR SIG_DFL ; this default usually results in termination of the process. If .I sv_handler is .C SIG_IGN the signal is usually subsequently ignored, and pending instances of the signal are discarded. The exact meaning of .C SIG_DFL and .C SIG_IGN for each signal is discussed in .IR signal (5). .PP Certain system calls can be interrupted by a signal; all other system calls complete before the signal is serviced. The .I scp pointer described in .IR signal (5) is never null if .C sigvector() is supported. .I scp points to a machine-dependent .I sigcontext structure. All implementations of this structure include the fields: .RS .TP 10 .C int .IR sc_syscall ; .PD 0 .TP .C char .IR sc_syscall_action ; .PD .RE .PP The value .C SYS_NOTSYSCALL for the .I sc_syscall field indicates that the signal is not interrupting a system call; any other value indicates which system call it is interrupting. .PP If a signal that is being caught occurs during a system call that can be interrupted, the signal handler is immediately invoked. If the signal handler exits normally, the value of the .I sc_syscall_action field is inspected; if the value is .CR SIG_RETURN , the system call is aborted and the interrupted program continues past the call. The result of the interrupted call is \(mi1 and .C errno is set to .SM EINTR. If the value of the .I sc_syscall_action field is .CR SIG_RESTART , the call is restarted. A call is restarted if, in the case of a .C read() or .C write() system call (see .IR read (2) or .IR write (2)), it had transferred no data. If some data had been transferred, the operation is considered to have completed with a partial transfer, and the .I sc_syscall value is .CR SYS_NOTSYSCALL . Other values are undefined and reserved for future use. .PP Exiting the handler abnormally (such as with .C longjmp() \(em see .IR setjmp (3C)) aborts the call, leaving the user responsible for the context of further execution. The value of .I scp\(mi>sc_syscall_action is ignored when the value of .I scp\(mi>sc_syscall is .CR SYS_NOTSYSCALL . .I scp\(mi>sc_syscall_action is always initialized to .C SIG_RETURN before invocation of a signal handler. When an system call that can be interrupted is interrupted by multiple signals, if any signal handler returns a value of .C SIG_RETURN in .IR scp\(mi>sc_syscall_action , all subsequent signal handlers are passed a value of .C SYS_NOTSYSCALL in .IR scp\(mi>sc_syscall . .PP Note that calls to .CR read() , .CR write() , or .CR ioctl() on fast devices (such as disks) cannot be interrupted, but .SM I/O to a slow device (such as a printer) can be interrupted. Other system calls, such as those used for networking, also can be interrupted on some implementations. In these cases additional values can be specified for .IR scp\(mi>sc_syscall . Programs that look at the values of .I scp\(mi>sc_syscall always should compare them to these symbolic constants; the numerical values represented by these constants might vary among implementations. System calls that can be interrupted and their corresponding values for .I scp\(mi>sc_syscall are listed below: .PP .ne 20 .TS center tab(#); lB | lB l | lf4. Call#sc_syscall value _ read (slow devices)#SYS_READ readv (slow devices)#SYS_READV write (slow devices)#SYS_WRITE writev (slow devices)#SYS_WRITEV open (slow devices)#SYS_OPEN ioctl (slow requests)#SYS_IOCTL close (slow requests)#SYS_CLOSE wait#SYS_WAIT select#SYS_SELECT pause#SYS_PAUSE sigpause#SYS_SIGPAUSE semop#SYS_SEMOP msgsnd#SYS_MSGSND msgrcv#SYS_MSGRCV .TE .PP These system calls are not defined if the preprocessor macro .C _XPG2 is defined when .RC < signal.h > is included. This is because the .I "X/Open Portability Guide, Issue 2" specifies a different meaning for the symbol .C SYS_OPEN (see .IR limits (5)). .PP After a .C fork() or .C vfork() system call, the child inherits all signals, the signal mask, and the reserved signal stack space. .PP .IR exec (2) resets all caught signals to the default action; ignored signals remain ignored, the signal mask remains unchanged, and the reserved signal stack space is released. .PP The mask specified in .I vec is not allowed to block signals that cannot be ignored, as defined in .IR signal (5). This is enforced silently by the system. .PP If .C sigvector() is called to catch .C SIGCLD in a process that currently has terminated (zombie) children, a .C SIGCLD signal is delivered to the calling process immediately, or as soon as .C SIGCLD is unblocked if it is currently blocked. Thus, in a process that spawns multiple children and catches .CR SIGCLD , it is sometimes advisable to reinstall the handler for .C SIGCLD after each invocation in case there are multiple zombies present. This is true even though the handling of the signal is not reset by the system, as with .IR signal (2), because deaths of multiple processes while .C SIGCLD is blocked in the handler result in delivery of only a single signal. Note that the function must reinstall itself after it has called .C wait() or .CR wait3() . Otherwise the presence of the child that caused the original signal always causes another signal to be delivered. .SH RETURN VALUE Upon successful completion, .C sigvector() returns 0; otherwise, it returns \(mi1 and sets .C errno to indicate the reason. .SH ERRORS .C sigvector() fails and no new signal handler is installed if any of the following conditions are encountered: .RS .TP 20 .SM [EFAULT] Either .I vec or .I ovec points to memory that is not a valid part of the process address space. Reliable detection of this error is implementation dependent. .TP .SM [EINVAL] .I sig is not a valid signal number. .TP .SM [EINVAL] An attempt was made to ignore or supply a handler for a signal that cannot be caught or ignored; see .IR signal (5). .RE .SH WARNINGS Restarting a .IR select (2) call can sometimes cause unexpected results. If the .C select() call has a timeout specified, the timeout is restarted with the call, ignoring any portion that had elapsed prior to interruption by the signal. Normally this simply extends the timeout and is not a problem. However, if a handler repeatedly catches signals, and the timeout specified to .C select() is longer than the time between those signals, restarting the .C select() call effectively renders the timeout infinite. .PP .C sigvector() should not be used in conjunction with the facilities described under .IR sigset (2V). .SH AUTHOR .C sigvector() was developed by HP and the University of California, Berkeley. .SH SEE ALSO kill(1), kill(2), ptrace(2), sigblock(2), signal(2), sigpause(2), sigsetmask(2), sigspace(2), setjmp(3C), signal(5), termio(7). .\" .\" index@\f4sigvector()\fP \(mi software signal facilities@@@\f3sigvector(2)\f1 .\" index@software signal facilities@@@\f3sigvector(2)\f1 .\" index@signal facilities, software@@@\f3sigvector(2)\f1 .\" index@facilities, software signal@@@\f3sigvector(2)\f1 .\" .\" toc@\f3sigvector(2)\f1:\0\0\f4sigvector()\fP@@@software signal facilities .\" $Header: socket.2,v 78.2 96/03/15 16:45:08 ssa Exp $ .TA s .TH socket 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME socket() \- create an endpoint for communication .SH SYNOPSIS .C "#include " .SS AF_CCITT Only .C "#include " .PP .C "int socket(int af, int type, int protocol);" .SH DESCRIPTION The .CR socket() system call creates an endpoint for communication and returns a descriptor. The socket descriptor returned is used in all subsequent socket-related system calls. .PP The .I af parameter specifies an address family to be used to interpret addresses in later operations that specify the socket. These address families are defined in the include files .CR and .CR . The only currently supported address families are: .RS .TP 15 .PD 0 AF_INET (DARPA Internet addresses) .TP AF_UNIX (path names on a local node) .TP AF_CCITT (CCITT X.25 addresses) .PD .RE .PP The .I type specifies the semantics of communication for the socket. Currently defined types are: .RS .TP 20 SOCK_STREAM Sequenced, reliable, two-way-connection-based byte streams. .TP SOCK_DGRAM Datagrams (connectionless, unreliable messages of a fixed, typically small, maximum length; for AF_INET only). .RE .PP .I protocol specifies a particular protocol to be used with the socket. Normally, only a single protocol exists to support a particular socket type using a given address family. However, many protocols may exist, in which case a particular protocol must be specified. The protocol number to use depends on the .B communication domain in which communication is to take place (see .IR services (4) and .IR protocols (4)). .I protocol can be specified as zero, which causes the system to choose a protocol type to use. .PP Sockets of type SOCK_STREAM are byte streams similar to pipes, except that they are full-duplex instead of half-duplex. A stream socket must be in a .I connected state before any data can be sent or received on it. A connection to another socket is created with a .CR connect() or .CR accept() call. Once connected, data can be transferred using some variant of the .CR send() and .CR recv() or the .CR read() and .CR write() calls. When a session is complete, use .CR close() or .CR shutdown() calls to terminate the connection. .PP TCP, the communications protocol used to implement SOCK_STREAM for AF_INET sockets, ensures that data is not lost or duplicated. If a peer has buffer space for data and the data cannot be successfully transmitted within a reasonable length of time, the connection is considered broken and the next .CR recv() call indicates an error with .CR errno set to [ETIMEDOUT]. If .CR SO_KEEPALIVE is set and the connection has been idle for two hours, the TCP protocol sends "keepalive" packets every 75 seconds to determine whether the connection is active. These transmissions are not visible to users and cannot be read by a .CR recv() call. If the remote system does not respond within 10 minutes (i.e., after 8 "keepalive" packets have been sent), the next socket call (e.g., .CR recv() ) returns an error with .CR errno set to [ETIMEDOUT]. A .CR SIGPIPE signal is raised if a process sends on a broken stream. This causes naive processes that do not handle the signal to exit. An end-of-file condition (zero bytes read) is returned if a process tries to read on a broken stream. .PP SOCK_DGRAM sockets allow sending of messages to correspondents named in .CR send() calls. It is also possible to receive messages at such a socket with .CR recv() . .PP The operation of sockets is controlled by socket level options set by the .CR setsockopt() system call described by the .IR getsockopt (2) manual entry. These options are defined in the file .CR and explained in the .IR getsockopt (2) manual entry. .SS X.25 Only Socket endpoints for communication over an X.25/9000 link can be in either address family, AF_INET or AF_CCITT. If the socket is in the AF_INET family, the connection behaves as described above. TCP is used if the socket type is SOCK_STREAM. UDP is used if the socket type is SOCK_DGRAM. In both cases, Internet protocol (IP) and the X.25-to-IP interface module are used. .PP If the socket is in the AF_CCITT address family, only the SOCK_STREAM socket type is supported. Refer to the topic "Comparing X.25 Level 3 Access to IP" in the .I "X.25 Programmer's Guide" for more details on the difference between programmatic access to X.25 via IP and X.25 Level 3. .PP If the socket is in the AF_CCITT family, the connection and all other operations pass data directly from the application to the X.25 Packet Level (level 3) without passing through a TCP or UDP protocol. Connections of the AF_CCITT family cannot use most of the socket level options described in .IR getsockopt (2). However, AF_CCITT connections can use many X.25-specific .CR ioctl() calls, described in .IR socketx25 (7). .SH DEPENDENCIES .SS AF_CCITT Only the SOCK_STREAM type is supported. .SH RETURN VALUE .CR socket() returns the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .I n is a valid file descriptor referring to the socket. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR socket() fails, .CR errno is set to one of the following values. .RS .TP 25 [EAFNOSUPPORT] The specified address family is not supported in this version of the system. .TP [EHOSTDOWN] The networking subsystem is not up. .TP [EINVAL] SOCK_DGRAM sockets are currently not supported for the AF_UNIX address family. .TP [EMFILE] The per-process descriptor table is full. .TP [ENFILE] The system's table of open files is temporarily full and no more .CR socket() calls can be accepted. .TP [ENOBUFS] No buffer space is available. The socket cannot be created. .TP [EPROTONOSUPPORT] The specified protocol is not supported. .TP [EPROTOTYPE] The type of socket and protocol do not match. .TP [ESOCKTNOSUPPORT] The specified socket type is not supported in this address family. .TP [ETIMEDOUT] Connection timed out. .RE .SH AUTHOR .CR socket() was developed by the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO accept(2), bind(2), connect(2), getsockname(2), getsockopt(2), ioctl(2), listen(2), recv(2), select(2), send(2), shutdown(2), af_ccitt(7F), \"STD socket(7), socketx25(7), tcp(7P), udp(7P), unix(7P), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR socket() ": XPG4" .\" .\" index@\f4socket()\f1 \- create an endpoint for communication@@@\f3socket(2)\f1 .\" index@\f1create an endpoint for communication@@@\f3socket(2)\f1 .\" index@\f1create a socket@@@\f3socket(2)\f1 .\" index@\f1endpoint for communication, create an@@@\f3socket(2)\f1 .\" index@\f1communication, create an endpoint for@@@\f3socket(2)\f1 .\" .\" toc@\f3socket(2)\f1:\0\0\f4socket()\f1@@@create an endpoint for communication .\" $Header: socketpair.2,v 78.2 96/03/15 16:45:26 ssa Exp $ .TA s .TH socketpair 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME socketpair() \- create a pair of connected sockets .SH SYNOPSIS .C "#include " .PP .C "int socketpair(int af, int type, int protocol, int sv[2]);" .SH DESCRIPTION The .CR socketpair() system call creates an unnamed pair of connected sockets and returns two file descriptors in .IR sv [0] and .IR sv [1]. The two sockets are indistinguishable. .I af specifies the address family. See .IR socket (2). .IR type specifies the semantics of communication for the socket. .I protocol specifies a particular protocol to be used. .I protocol can be specified as zero, which causes the system to choose a protocol type to use. .SH RETURN VALUE .CR socketpair() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR socketpair() fails, .CR errno is set to one of the following values. .RS .TP 20 [EAFNOSUPPORT] The specified address family is not supported in this version of the system. .TP [EFAULT] The .I sv parameter is not valid. .TP [EMFILE] The per-process file descriptor table is full. .TP [ENFILE] The system file table is temporarily full. .TP [ENOBUFS] No buffer space is available for the operation to complete. .TP [EOPNOTSUPP] The specified protocol does not support creation of socket pairs. .TP [EPROTONOSUPPORT] The specified protocol is not supported in this version of the system. .RE .SH DEPENDENCIES .CR socketpair() is supported only for AF_UNIX. .SH AUTHOR .CR socketpair() was developed by the University of California, Berkeley. .SH FUTURE DIRECTION The default behavior in this release is still the classic .CR "HP-UX BSD Sockets", however it will be changed to .CR "X/Open Sockets" in some future release. At that time, any .CR "HP-UX BSD Sockets" behavior which is incompatible with .CR "X/Open Sockets" may be obsoleted. HP customers are advised to migrate their applications to conform to .CR X/Open specification( see .I xopen_networking(7) ). .SH SEE ALSO read(2), socket(2), write(2), xopen_networking(7). .SH STANDARDS CONFORMANCE .CR socketpair() ": XPG4" .\" .\" index@\f4socketpair()\f1 \- create a pair of connected sockets@@@\f3socketpair(2)\f1 .\" index@create a pair of connected sockets@@@\f3socketpair(2)\f1 .\" index@connected sockets, create a pair@@@\f3socketpair(2)\f1 .\" index@sockets, create a pair of connected@@@\f3socketpair(2)\f1 .\" .\" toc@\f3socketpair(2)\f1:\0\0\f4socketpair()\f1@@@create a pair of connected sockets .\" $Header: stat.2,v 78.1 96/02/12 14:16:10 ssa Exp $ .TA s .TH stat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME stat \- get file status .SH SYNOPSIS .SH OH .C "#include " .C "#include " .PP .C "int stat(const char *path, struct stat *buf);" .SH DESCRIPTION The .CR stat() function obtains information about the named file and writes it to the area pointed to by the .IR buf argument. The path argument points to a pathname naming a file. Read, write or execute permission of the named file is not required, but all directories listed in the pathname leading to the file must be searchable. An implementation that provides additional or alternate file access control mechanisms may, under implementation-dependent conditions, cause .CR stat() to fail. In particular, the system may deny the existence of the file specified by .IR path . .PP The .IR buf argument is a pointer to a .CR stat structure, as defined in the header .CR , into which information is placed concerning the file. .PP The .CR stat() function updates any time-related fields (as described in the definition of File Times Update in the XBD specification), before writing into the .CR stat structure. .PP The structure members .IR st_mode , .IR st_ino , .IR st_dev , .IR st_uid , .IR st_gid , .IR st_atime , .IR st_ctime , and .IR st_mtime will have meaningful values for all file types defined in this document. The value of the member .IR st_nlink will be set to the number of links to the file. .PP .SH RETURN VALUE Upon successful completion, 0 is returned. Otherwise, \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR stat() function will fail if: .RS .TP 25 [EACCES] Search permission is denied for a component of the .IR path prefix. .TP [EIO] An error occurred while reading from the file system. .TP [ELOOP] Too many symbolic links were encountered in resolving path. .TP [ENAMETOOLONG] The length of the .IR path argument exceeds .CR {PATH_MAX} or a pathname component is longer than .CR {NAME_MAX} . .TP [ENOENT] A component of .IR path does not name an existing file or path is an empty string. .TP [ENOTDIR] A component of the .IR path prefix is not a directory. .RE .PP The .CR stat() function may fail if: .RS .TP 25 [ENAMETOOLONG] Pathname resolution of a symbolic link produced an intermediate result whose length exceeds .CR {PATH_MAX} . .TP [EOVERFLOW] A value to be stored would overflow one of the members of the .IR stat structure. .SH SEE ALSO fstat(), lstat(), , . .SH CHANGE HISTORY First released in Issue 1. .PP Derived from Issue 1 of the SVID. .SH Issue 4 The following changes are incorporated for alignment with the ISO POSIX-1 standard: .P .RS .TP 3 \(bu The type of argument .IR path is changed from .C char * .R to .C const char * .R . .TP 3 \(bu In the DESCRIPTION section, (a) statements indicating the purpose of this interface and a paragraph defining the contents of .CR stat structure members are added, and (b) the words "extended security controls" are replaced by "additional or alternate file access control mechanisms." .RE .PP The following change is incorporated for alignment with the FIPS requirements: .RS .TP 3 \(bu In the ERRORS section, the condition whereby .CR [ENAMETOOLONG] will be returned if a pathname component is larger that .C {NAME_MAX} is now defined as mandatory and marked as an extension. .RE .PP Another change is incorporated as follows: .RS .TP 3 \(bu The header .C is now marked as optional (OH); this header need not be included on XSI-conformant systems. .SH Issue 4, Version 2 The ERRORS section is updated for X/OPEN UNIX conformance as follows: .RS .TP 3 \(bu In the mandatory section, .CR EIO is added to indicate that a physical I/O error has occurred, and .CR ELOOP to indicate that too many symbolic links were encountered during pathname resolution. .TP 3 \(bu In the optional section, a second .CR ENAMETOOLONG condition is defined that may report excessive length of an intermediate result of pathname resolution of a symbolic link. .TP 3 \(bu In the optional section, .CR EOVERFLOW is added to indicate that a value to be stored in a member of the .CR stat structure would cause overflow. .\" $Header: stat.2,v 78.1 96/02/12 14:16:10 ssa Exp $ .TA s .TH stat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH DESCRIPTION If the chosen path name or file descriptor refers to a Multi-Level Directory (MLD), and the process does not have the multilevel effective privilege, the .IR i\-node number returned in .IR st_ino is the .IR i\-node of the MLD itself. .PP The parameters for the .CR stat() function are as follows: .RS .TP 15 .IR path is a pointer to a path name of any file within the mounted file system. (All directories listed in the path name must be searchable.) .TP .IR buf is a pointer to a .CR stat structure, which is where the file status information is stored. .RE .PP The .CR stat structure contains the following members: .PP .TS center tab (#); lf4#lf4#lf4. dev_t#st_dev;#/* ID of device containing a */ ##/* directory entry for this file */ ino_t#st_ino;#/* Inode number */ ushort#st_fstype;#/* Type of filesystem this file */ ##/* is in; see sysfs(2) */ ushort#st_mode;#/* File type, attributes, and */ ##/* access control summary */ ushort#st_basemode#/* Permission bits (see chmod(1)) */ ushort#st_nlink;#/* Number of links */ uid_t#st_uid;#/* User ID of file owner */ gid_t#st_gid;#/* Group ID of file group */ dev_t#st_rdev;#/* Device ID; this entry defined */ ##/* only for char or blk spec files */ off_t#st_size;#/* File size (bytes) */ time_t#st_atime;#/* Time of last access */ time_t#st_mtime;#/* Last modification time */ time_t#st_ctime;#/* Last file status change time */ ##/* Measured in secs since */ ##/* 00:00:00 GMT, Jan 1, 1970 */ long#st_blksize;#/* File system block size */ uint#st_acl:1;#/* Set if the file has optional */ ##/* access control list entries */ ##/* HFS File Systems only */ .TE .PP (Note that the position of items in this list does not necessarily reflect the order of the members in the structure.) .SH ERRORS .RS .TP 15 .SM [EFAULT] .I buf or .I path points to an invalid address. The reliable detection of this error is implementation dependent. .TP .SM [EOVERFLOW] The file size in bytes or the number of blocks allocated to the file cannot be represented correctly in the structure pointed to by .IR buf . .RE .PP .SH NFS The .IR st_basemode and .IR st_acl fields are zero on files accessed remotely. .IR st_acl field is applicable to HFS File Systems only. .PP .SH WARNINGS .SS "Access Control Lists - HFS File Systems only" .PP Access control list descriptions in this entry apply only to HFS file systems on standard HP-UX operating systems. .SH DEPENDENCIES .SS CD-ROM .PP The .C st_uid and .C st_gid fields are set to \(mi1 if they are not specified on the disk for a given file. .SH AUTHOR .CR stat() and .CR fstat() were developed by AT&T. .CR lstat() was developed by the University of California, Berkeley. .SH SEE ALSO touch(1), chmod(2), chown(2), creat(2), link(2), mknod(2), pipe(2), read(2), rename(2), setacl(2), stat64(2), sysfs(2), time(2), truncate(2), unlink(2), utime(2), write(2), acl(5), stat(5). .SH STANDARDS CONFORMANCE .CR stat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4stat()\f1 \- get file status@@@\f3stat(2)\f1 .\" index@\f1get, file status@@@\f3stat(2)\f1 .\" index@\f1file, get file status@@@\f3stat(2)\f1 .\" index@\f1status, get file@@@\f3stat(2)\f1 .\" .\" toc@\f3stat(2)\f1:\0\0\f4stat()\f1@@@get file status .\" $Header: creat64.2,v 78.2 96/02/12 13:37:12 ssa Exp $ .TA c .TH creat64 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME creat64(\|), fstat64(\|), getrlimit64(\|), lockf64(\|), lseek64(\|), lstat64(\|), mmap64(\|), open64(\|), prealloc64(\|), setrlimit64(\|), stat64(\|), statvfs64(\|), truncate64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0creat64(const\0char\0*path,\0mode_t\0mode);" .PP .C "#include " .PP .C "int\0fstat64(int\0fildes,\0struct\0stat64\0*buf);" .PP .C "include\0" .PP .C "int\0getrlimit64(int resource,\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0lock64(int\0*fildes,\0int\0function,\0off64_t\0size);" .PP .C "#include " .PP .C "off64_t\0lseek64(int\0*fildes,\0off64_t\0offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0lstat64(const\0char\0*,\0struct\0stat64\0*);" .PP .C "#include " .PP .C "void\0mmap64(void\0addr,\0size_t\0len,\0int\0prot,\0int\0flags,\0int\0fildes,\0off64_t\0off);" .PP .C "#include " .PP .C "int\0open64(const\0char\0*path,\0int\0oflag,...);" .PP .C "#include " .PP .C "int\0prealloc64(int\0fildes,\0off64_t\0size);" .PP .C "include\0" .PP .C "int\0setrlimit64(int\0resource,\0const\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0stat64(const\0char\0*path,\0struct\0stat64\0*buf);" .PP .C "#include " .PP .C "int\0statvfs64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "int\0truncate64(const\0char\0*path,\0off64_t\0length);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 18 .C creat64() The .C creat64() function is identical to .C creat() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. .C creat64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR creat() . .TP .C fstat64() The .C fstat64() function is identical to .C fstat() except that .C fstat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C getrlimit64 The .C getrlimit64() function is identical to .C getrlimit() except that .C getrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .CR "struct rlimit" . All other functional behaviors, returns, and errors are identical. .TP .C lock64() The .C lock64() function is identical to .C lockf() except that .C lockf64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C lseek64() The .C lseek64() function is identical to .C lseek() except that .C lseek64() accepts an .CR off64_t type as the desired offset and has a return value of .CR off64_t. All other functional behaviors, returns, and errors are identical. .TP .C lstat64() The .C lstat64() function is identical to .C lstat() except that .C lstat64() returns file status in a .C struct stat64 instead of .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C mmap64() The .C mmap64() function is identical to .C mmap() except that .C mmap64() accepts the file offset as an .CR off64_t . .TP .C open64() The .C open64() function is identical to .C open() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. The .C open64() function is equivalent to .C open() function (in 32-bit compile environment) with .C O_LARGEFILE flag set. .C open64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR open() . .TP .C prealloc64() The .C prealloc64() function is identical to .C prealloc() except that .C prealloc64() accepts the file offset as an .CR off64_t . All other functional behaviors, returns, and errors are identical to .CR prealloc() . .TP .C setrlimit64 The .C setrlimit64() function is identical to .C setrlimit() except that .C setrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .C struct rlimit. All other functional behaviors, returns, and errors are identical. .TP .C stat64() The .C stat64() function is identical to .C stat() except that .C stat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . .TP .C statvfs64() Refer to .CR fstatvfs64() . .TP .C truncate64() The .C truncate64() function is identical to .C truncate() except that .C truncate64() accepts the length parameter as an .C off64_t instead of .CR off_t . All other functional behaviors, returns, and errors are identical to .CR truncate() . .\" .\" toc@\f4creat64(2)\f1:\0\0\f4fstat64\f1, \f4getrlimit64\f1, \f4lockf64\f1, \f4lseek64\f1, \f4lstat64\f1, \f4mmap64\f1, \f4open64\f1, \n\f4prealloc64\f1, \f4setrlimit64\f1, \f4stat64\f1, \f4statvfs64\f1, \f4truncate64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4creat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4fstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4getrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lockf64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lseek64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4mmap64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4open64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4prealloc64()\f1 \- file sysmmaptem API to support large files@@@\f3creat64(2)\f1 .\" index@\f4setrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4stat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4statvfs64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4truncate64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3creat64(2)\f1 .\" .\" links@creat64.2 fstat64.2 .\" links@creat64.2 getrlimit64.2 .\" links@creat64.2 lockf64.2 .\" links@creat64.2 lseek64.2 .\" links@creat64.2 lstat64.2 .\" links@creat64.2 mmap64.2 .\" links@creat64.2 open64.2 .\" links@creat64.2 prealloc64.2 .\" links@creat64.2 setrlimit64.2 .\" links@creat64.2 stat64.2 .\" links@creat64.2 statvfs64.2 .\" links@creat64.2 truncate64.2 .\" .\" $Header: statfs.2,v 72.5 94/07/05 16:35:17 ssa Exp $ .TA s .TH statfs 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME statfs, fstatfs \- get file system statistics .SH SYNOPSIS .C "#include " .PP .C "int statfs(const char *path, struct statfs *buf);" .PP .C "int fstatfs(int fildes, struct statfs *buf);" .SH DESCRIPTION .C statfs() returns status information for a mounted file system. .PP .C fstatfs() returns similar information for an open file. .PP The parameters for the .C statfs() and .C fstatfs() functions are as follows: .RS .TP 20 .I path is a pointer to a path name of any file within the mounted file system. .TP .I buf is a pointer to a .C statfs() structure, which is where the file system status information is stored. .TP .I fildes is a file descriptor for an open file, which is created with the successful completion of an .CR open() , .CR creat() , .CR dup() , .CR fcntl() , or .CR pipe() system call (see .IR open (2), .IR creat (2), .IR dup (2), .IR fcntl (2), or .IR pipe (2)). .RE .PP The .C statfs() structure contains the following members: .nf .IP .C "long f_bavail; /* free blocks available to non-superuser */ .C "long f_bfree; /* free blocks */ .C "long f_blocks; /* total blocks in file system */ .C "long f_bsize; /* fundamental file system block size in bytes */ .C "long f_ffree; /* free file nodes in file system */ .C "long f_files; /* total file nodes in file system */ .C "long f_type; /* type of info, zero for now */ .C "fsid_t f_fsid /* file system ID. f_fsid[1] is the file system .C " type; see sysfs(2) */ .fi .PP The fields .CR f_blocks , .CR f_bavail and .CR f_bfree are expressed in terms of blocks of size .CR f_bsize. .PP A .I file node is a structure in the file system hierarchy that describes a file. .PP Fields that are undefined for a particular file system are set to \(mi1. .SH RETURN VALUE .C statfs() and .C fstatfs() return 0 upon successful completion; otherwise, they return \(mi1 and set .C errno to indicate the error. .SH ERRORS If .C statfs() fails, .C errno is set to one of the following values: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of the path prefix. .TP .SM [EFAULT] .I buf or .I path point to an invalid address. .TP .SM [EIO] An I/O error occurred while reading from or writing to the file system. .TP .SM [ELOOP] Too many symbolic links are encountered during path-name translation. .TP .SM [ENAMETOOLONG] The length of the specified path name exceeds .C PATH_MAX bytes, or the length of a component of the path name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ENOENT] The named file does not exist (for example, .I path is null or a component of .I path does not exist). .TP .SM [ENOTDIR] A component of the path prefix is not a directory. .RE .PP If .C fstatfs() fails, .C errno is set to one of the following values: .RS .TP 20 .SM [EBADF] .I fildes is not a valid open file descriptor. .TP .SM [EFAULT] .I buf points to an invalid address. .TP .SM [EIO] An I/O error occurs while reading from or writing to the file system. .RE .SH AUTHOR .C statfs() and .C fstatfs() were developed by Sun Microsystems, Inc. .SH SEE ALSO df(1M), stat(2), ustat(2). .\" .\" index@\f4statfs()\f1, \f4fstatfs()\f1 \- get file system statistics@@@\f3statfs(2)\f1 .\" index@\f4fstatfs()\f1, \f4statfs()\f1 \- get file system statistics@@@\f3statfs(2)\f1 .\" index@\f1get file system statistics@@@\f3statfs(2)\f1 .\" index@\f1file system statistics, get@@@\f3statfs(2)\f1 .\" index@\f1statistics, get file system@@@\f3statfs(2)\f1 .\" .\" toc@\f3statfs(2)\f1:\0\0\f4statfs()\f1, \f4fstatfs()\f1@@@get file system statistics .\" toc@\f4fstatfs()\f1:\0\0get file system statistics@@@see \f3statfs(2)\f1 .\" .\" links@statfs.2 fstatfs.2 .\" $Header: statvfs.2,v 78.1 96/02/12 14:17:07 ssa Exp $ .TA s .TH statvfs 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME statvfs, fstatvfs \- get file system information .SH SYNOPSIS .PP .C "#include " .PP .C "#include " .PP .C "int statvfs (const char *path, struct statvfs *buf);" .PP .C "int fstatvfs (int fildes, struct statvfs *buf);" .SH DESCRIPTION .C statvfs() returns information about a mounted file system. .PP .C fstatvfs() returns similar information about an open file. .PP The parameters for the .C statvfs() and .C fstatvfs() functions are as follows: .RS .TP 20 .I path is a pointer to a path name of any file within the mounted file system. .TP .I buf is a pointer to a .C statvfs() structure, which is where the file system status information is stored. .TP .I fildes is a file descriptor for an open file, which is created with the successful completion of an .CR open() , .CR creat() , .CR dup() , .CR fcntl() , or .CR pipe() system call (see .IR open (2), .IR creat (2), .IR dup (2), .IR fcntl (2), or .IR pipe (2)). .RE .PP The .C statvfs() structure contains the following members: .nf .IP .C "ulong f_bsize; /* preferred file system block size */" .C "ulong f_frsize; /* fundamental file system block size */" .C "ulong f_blocks; /* total blocks of f_frsize on file system */" .C "ulong f_size; /* size of file system in f_frsize unit */" .C "ulong f_bfree; /* free blocks */" .C "ulong f_bavail; /* blocks available to non-superuser */" .C "long f_files; /* total file nodes in file system */" .C "long f_ffree; /* free file nodes in file system */" .C "long f_favail; /* file nodes available to non-superuser */" .C "long f_fsid; /* file system ID for file system */" .C " /* type; see sysfs(2) */" .C "char f_basetype[FSTYPSZ]; /* file system type name is null-terminated */" .C "long f_flag; /* bit mask of flags */" .C "long f_namemax /* maximum file name length */" .C "char f_fstr[32]; /* file system specific string */" .C "time_t f_time; /* Last time file system was written */" .PP The field f_basetype contains a null-terminated file-system-type name. .fi .PP The constant .C [FSTYPSZ] is defined in the header file .CR . .PP The following flags can be returned in the f_flag field: .RS .TP 20 .C ST_LARGEFILES File system is enabled for large files. .TP .C ST_RDONLY File system is read-only. .TP .C ST_NOSUID File system does not support .C setuid and .C setgid semantics. .TP .C ST_EXPORTED File system is exported (NFS). .TP .C ST_QUOTA Quotas are enabled on this file system. .RE .SH RETURN VALUE .C statvfs() and .C fstatvfs() return 0 upon successful completion; otherwise, they return -1 and set .C errno to indicate the error. .SH ERRORS If .C statvfs() fails, .C errno is set to one of the following values: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of the path prefix. .TP .SM [ELOOP] Too many symbolic links are encountered during path-name translation. .TP .SM [ENAMETOOLONG] The length of the specified path name exceeds .C PATH_MAX bytes, or the length of a component of the path name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ENOENT] The named file does not exist (for example, .I path is null or a component of .I path does not exist). .TP .SM [ENOTDIR] A component of the path prefix is not a directory. .RE .PP If .C fstatvfs() fails, .C errno is set to the following value: .RS .TP 20 .SM [EBADF] .I fildes is not a valid open file descriptor. .RE .PP When both .C statvfs() and .C fstatvfs() fail, .C errno is set to one of the following values: .RS .TP 20 .SM [EFAULT] .I buf points to an invalid address. .TP .SM [EIO] An I/O error occurred while reading from or writing to the file system. .RE .SH SEE ALSO df(1M), fstatfs(2), fstatvfs64(2), quotactl(2), stat(2), statfs(2), statvfs64(2), sysfs(2), ustat(2). .\" .\" index@\f4statvfs()\f1, \f4fstatvfs()\f1 \- get file status@@@\f3statvfs(2)\f1 .\" index@\f4fstatvfs()\f1, (\f4statvfs()\f1) \- get open file status@@@\f3statvfs(2)\f1 .\" index@\f1get file status@@@\f3statvfs(2)\f1 .\" index@\f1file, get file status@@@\f3statvfs(2)\f1 .\" index@\f1status, get file@@@\f3statvfs(2)\f1 .\" .\" toc@\f3statvfs(2)\f1:\0\0\f4statvfs()\f1, \f4fstatvfs()\f1@@@get file status .\" toc@\f4fstatvfs()\f1:\0\0get file status@@@see \f3statvfs(2)\f1 .\" .\" links@statvfs.2 fstatvfs.2 .\" $Header: creat64.2,v 78.2 96/02/12 13:37:12 ssa Exp $ .TA c .TH creat64 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME creat64(\|), fstat64(\|), getrlimit64(\|), lockf64(\|), lseek64(\|), lstat64(\|), mmap64(\|), open64(\|), prealloc64(\|), setrlimit64(\|), stat64(\|), statvfs64(\|), truncate64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0creat64(const\0char\0*path,\0mode_t\0mode);" .PP .C "#include " .PP .C "int\0fstat64(int\0fildes,\0struct\0stat64\0*buf);" .PP .C "include\0" .PP .C "int\0getrlimit64(int resource,\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0lock64(int\0*fildes,\0int\0function,\0off64_t\0size);" .PP .C "#include " .PP .C "off64_t\0lseek64(int\0*fildes,\0off64_t\0offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0lstat64(const\0char\0*,\0struct\0stat64\0*);" .PP .C "#include " .PP .C "void\0mmap64(void\0addr,\0size_t\0len,\0int\0prot,\0int\0flags,\0int\0fildes,\0off64_t\0off);" .PP .C "#include " .PP .C "int\0open64(const\0char\0*path,\0int\0oflag,...);" .PP .C "#include " .PP .C "int\0prealloc64(int\0fildes,\0off64_t\0size);" .PP .C "include\0" .PP .C "int\0setrlimit64(int\0resource,\0const\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0stat64(const\0char\0*path,\0struct\0stat64\0*buf);" .PP .C "#include " .PP .C "int\0statvfs64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "int\0truncate64(const\0char\0*path,\0off64_t\0length);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 18 .C creat64() The .C creat64() function is identical to .C creat() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. .C creat64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR creat() . .TP .C fstat64() The .C fstat64() function is identical to .C fstat() except that .C fstat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C getrlimit64 The .C getrlimit64() function is identical to .C getrlimit() except that .C getrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .CR "struct rlimit" . All other functional behaviors, returns, and errors are identical. .TP .C lock64() The .C lock64() function is identical to .C lockf() except that .C lockf64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C lseek64() The .C lseek64() function is identical to .C lseek() except that .C lseek64() accepts an .CR off64_t type as the desired offset and has a return value of .CR off64_t. All other functional behaviors, returns, and errors are identical. .TP .C lstat64() The .C lstat64() function is identical to .C lstat() except that .C lstat64() returns file status in a .C struct stat64 instead of .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C mmap64() The .C mmap64() function is identical to .C mmap() except that .C mmap64() accepts the file offset as an .CR off64_t . .TP .C open64() The .C open64() function is identical to .C open() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. The .C open64() function is equivalent to .C open() function (in 32-bit compile environment) with .C O_LARGEFILE flag set. .C open64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR open() . .TP .C prealloc64() The .C prealloc64() function is identical to .C prealloc() except that .C prealloc64() accepts the file offset as an .CR off64_t . All other functional behaviors, returns, and errors are identical to .CR prealloc() . .TP .C setrlimit64 The .C setrlimit64() function is identical to .C setrlimit() except that .C setrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .C struct rlimit. All other functional behaviors, returns, and errors are identical. .TP .C stat64() The .C stat64() function is identical to .C stat() except that .C stat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . .TP .C statvfs64() Refer to .CR fstatvfs64() . .TP .C truncate64() The .C truncate64() function is identical to .C truncate() except that .C truncate64() accepts the length parameter as an .C off64_t instead of .CR off_t . All other functional behaviors, returns, and errors are identical to .CR truncate() . .\" .\" toc@\f4creat64(2)\f1:\0\0\f4fstat64\f1, \f4getrlimit64\f1, \f4lockf64\f1, \f4lseek64\f1, \f4lstat64\f1, \f4mmap64\f1, \f4open64\f1, \n\f4prealloc64\f1, \f4setrlimit64\f1, \f4stat64\f1, \f4statvfs64\f1, \f4truncate64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4creat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4fstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4getrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lockf64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lseek64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4mmap64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4open64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4prealloc64()\f1 \- file sysmmaptem API to support large files@@@\f3creat64(2)\f1 .\" index@\f4setrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4stat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4statvfs64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4truncate64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3creat64(2)\f1 .\" .\" links@creat64.2 fstat64.2 .\" links@creat64.2 getrlimit64.2 .\" links@creat64.2 lockf64.2 .\" links@creat64.2 lseek64.2 .\" links@creat64.2 lstat64.2 .\" links@creat64.2 mmap64.2 .\" links@creat64.2 open64.2 .\" links@creat64.2 prealloc64.2 .\" links@creat64.2 setrlimit64.2 .\" links@creat64.2 stat64.2 .\" links@creat64.2 statvfs64.2 .\" links@creat64.2 truncate64.2 .\" .\" $Header: stime.2,v 72.6 94/11/14 15:26:50 ssa Exp $ .TA s .TH stime 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME stime() \- set time and date .SH SYNOPSIS .C "#include " .PP .C "int stime(const time_t *tp);" .SH DESCRIPTION The .CR stime() system call sets the system time and date. .I tp points to the value of time as measured in seconds from 00:00:00 on January 1, 1970, Coordinated Universal Time (UTC). .SH RETURN VALUE .CR stime() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR stime() fails, .CR errno is set to one of the following values. .RS .TP 15 .SM [EPERM] The effective user .SM ID of the calling process is not superuser. .RE .SH SEE ALSO date(1), gettimeofday(2), time(2). .SH STANDARDS CONFORMANCE .CR stime() ": SVID2, SVID3, XPG2" .\" .\" index@\f4stime()\f1 \- set time and date@@@\f3stime(2)\f1 .\" index@set time and date@@@\f3stime(2)\f1 .\" index@time, set@@@\f3stime(2)\f1 .\" index@date, set@@@\f3stime(2)\f1 .\" .\" toc@\f3stime(2)\f1:\0\0\f4stime()\f1@@@set time and date .\" $Header: stream.2,v 72.2 94/08/30 17:07:26 ssa Exp $ .TA s .TH stream 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME stream \- STREAMS enhancements to standard system calls .SH DESCRIPTION The .CR open() , .CR close() , .CR read() , .CR readv() , .CR write() , .CR writev() , .CR ioctl() , .CR select() , and .CR signal() system calls are enhanced to support STREAMS. The new functionality is described below for each system call. .sp 1 .SS Open Enhancements .PP When calling open for a STREAMS device, the .IR oflag parameter can only be constructed from the .CR O_NONBLOCK flag values that are OR-ed with the .CR O_RDONLY , .CR O_WRONLY , or .CR O_RDWR flag values. The values of the other flags are not applicable to STREAMS devices and have no effect on them. .PP The values of the .CR O_NONBLOCK flags affect the operations of STREAMS-based device drivers, when the .CR read() , .CR write() , .CR getmsg() , .CR getpmsg() , .CR putmsg() , or .CR putpmsg() functions are used. After the stream is open, these flags can be modified by calling .CR fcntl() (see the .IR fcntl (2) man page). The effects of the flags are device specific. .PP The open of a STREAMS device may fail for one or more of the following STREAMS-specific conditions: .RS .TP 12 .C EIO A hangup occurred while the .CR open() function was attempting to open the stream. .TP .C EAGAIN The system was unable to allocate a stream. .TP .C ENODEV The device has not been generated into the system as a STREAMS device. .TP .C ENXIO The open routine of one of the modules or drivers in the stream failed. .RE .sp 1 .SS Close Enhancements .PP When all file descriptors associated with a STREAMS device have been closed, the stream is dismantled. If the file descriptor is associated with a stream that is subject to persistent links, the .CR close() function will succeed immediately, but the stream will remain open. See .CR I_PLINK documentation in .IR streamio (7). Dismantling includes popping any modules on the stream and closing the driver. If .CR O_NONBLOCK flag is set, and there are no signals posted for the stream, the .CR close() function waits for output to drain on each module's or driver's non-empty write queue. .CR close() waits for each module or driver for the amount of time set by the .CR I_SETCLTIME .CR ioctl() (see the .IR streamio (7) man page). The default is 15 seconds per module or driver. If the .CR O_NONBLOCK flag is set, or there are any pending signals, the function does not wait for output to drain and dismantles the stream immediately. If a STREAMS device is closed, and the calling process had previously registered to recieve a .CR SIGPOLL signal for events associated with that device (see "Signal Enhancements" below), .CR close() unregisters the calling process for the events associated with the stream. .sp 1 .SS Read and Readv Enhancements .PP In this section, .CR read() refers to both .CR read() and .CR readv() . For STREAMS devices, the .CR read() function operates in accordance with the read mode of the file. STREAMS has three read modes: byte-stream mode, message-nondiscard mode, and message-discard mode. The default is byte-stream mode; however, the user can change this by issuing the .CR I_SRDOPT .CR ioctl() call. The user can also test for the current read mode by issuing the .CR I_GRDOPT .CR ioctl() call. See the .CR streamio(7) man page for more information about these .CR ioctl() calls. The .CR read() function's behavior in each of the read modes of a STREAMS device is as follows: .RS .TP 3 .C \(bu In byte-stream mode, the function retrieves data from the stream associated with the file descriptor until it has retrieved .IR nbyte bytes, or until there is no more data to be retrieved. .TP .C \(bu In message-nondiscard mode, the function retrieves data until it reaches a message boundary. If it does not retrieve all of the data in the message, it places the remaining data back on the stream. This data can be retrieved by a subsequent .CR read() , .CR getmsg() , or .CR getpmsg() call. .TP .C \(bu In message-discard mode, the function retrieves data until it has retrieved .IR nbytes , or until it has reached a message boundary. However, unread data remaining in the message is discarded and is not available for reading by a subsequent .CR read() , .CR getmsg() , or .CR getpmsg() call. .RE .PP When attempting to read a STREAMS device and encountering a zero-byte message: .RS .TP 3 .C \(bu If the read mode is byte-stream, the .CR read() function returns the number of bytes of data read before encountering the zero-byte message. If data was read before receiving the zero-byte message, .CR read() returns the zero-byte message to the stream so it can be processed by a subsequent .CR read() , .CR getmsg() , or .CR getpmsg() call. If no data was read, .CR read() consumes the message. .TP .C \(bu If the read mode is message-discard or message-nondiscard, the .CR read() function returns zero, and then consumes the message. .RE .PP The .CR read() function reads the data at the front of the stream head read queue. It reads both priority band and normal data. .PP The .CR read() function processes control messages according to the STREAMS read flags: .CR RPROTNORM , .CR RPROTDAT , and .CR RPROTDIS . The default is for .CR RPROTNORM to be set; however, the user can change this by issuing the .CR I_SRDOPT .CR ioctl() call. The .CR read() function's behavior for each read flag is described below: .RS .TP 3 .C \(bu If .CR RPROTNORM is set, a read from a stream can only process data messages. It cannot process any type of control message and fails if such a message is encountered at the stream head. .TP .C \(bu If .CR RPROTDAT is set, .CR read() processes both data and control messages. The .CR read() function delivers data in both data and control messages. .TP .C \(bu If .CR RPROTDIS is set, .CR read() consumes any control messages and retrieves data from data messages only. .RE .PP The following is also true for reads to STREAMS devices. If the .CR O_NONBLOCK flag is clear, and no message is waiting to be read on the stream, the .CR read() function blocks until a message arrives at the stream head. If the .CR O_NONBLOCK flag is set, and no message is waiting to be read on the stream, the .CR read() function fails and returns ERANGE. .PP A read from a STREAMS device may fail for one or more of the following STREAMS-specific conditions: .RS .TP 12 .C EAGAIN No message is waiting to be read on the stream, and the .CR O_NONBLOCK flag is set. .TP .C EBADMSG A message is waiting to be read, but it is not a data message and the .CR RPROTNORM flag is set. .TP .C EINVAL The stream is linked to a multiplexor. .RE .PP A read from a STREAMS device also fails if an error message is received at the stream head. In this case, .CR errno is set to the value returned in the error message. .PP If a hangup occurs on the stream being read, the .CR read() function continues its operations until the stream read queues are empty. Thereafter, it returns a value of 0 (zero). .sp 1 .SS Write and Writev Enhancements .PP In this section, .CR write() refers to both .CR write() and .CR writev() . When writing to a STREAMS device, the .CR write() function sends ordinary, priority band zero, data. Other aspects of the .CR write() function's behavior are determined by the packet size that the stream will accept. .PP If .IR nbytes is not within the top module's minimum and maximum packet size range, .CR write() will return ERANGE. Two exceptions exist, however, in which .CR write() does not return an error. The first exception is if .IR nbytes is too large and either the maximum packet size is infinite or the minimum packet size is less than or equal to zero. The second exception occurs if .IR nbytes is too small and the minimum packet size is less than or equal to zero. With either exception, .CR write() does not return ERANGE, and transfers the data. .PP The .CR write() function may send the user's data buffer in multiple messages. The maximum amount of data that .CR write() sends in one message is the lower value of the top module's maximum packet size and .CR STRMSGSZ . If the maximum packet size is infinite, .CR write() compares half of the top module's high water mark to .CR STRMSGSZ instead. If the high water mark is less than or equal to zero, the page size is used. .PP If a zero-length buffer (\c .IR nbytes is 0) is passed to .CR write() , zero bytes are sent to the stream and zero bytes are returned. .PP The following is also true for writes to STREAMS devices. If the .CR O_NONBLOCK flag is clear, and the stream cannot accept data (the stream head write queue is full due to flow control conditions), the .CR write() function blocks until data can be accepted. If the .CR O_NONBLOCK flag is set, and the stream cannot accept data, the .CR write() function fails, and returns EAGAIN. If the .CR O_NONBLOCK flag is set, and the stream cannot accept data, but part of the buffer has already been written, the .CR write() function terminates and returns the number of bytes written. .PP A write to a STREAMS device may fail for one or more of the following STREAMS-specific conditions: .RS .TP 12 .C EAGAIN The .CR O_NONBLOCK flag is set, and the stream cannot accept .CR write() data because it is flow controlled. .TP .C EINVAL The .CR write() function attempts to write to a stream that is linked below a multiplexor. .TP .C ENXIO A hangup occurs on a stream while the .CR write() function is writing to the stream. .TP .C ERANGE The .IR nbytes parameter is not within the allowable range. .RE .PP The .CR write() system call will also fail if an error message has been received at the stream head of the stream to which the .CR write() function is attempting to write. In this case, the function returns with .CR errno set to the value included in the error message. .RE .sp 1 .SS Ioctl Enhancements .PP Refer to the .IR streamio (7) man page for a description of STREAMS .CR ioctl() functionality. .sp 1 .SS Select Enhancements .PP The .CR select() system call checks the status of STREAMS devices. .CR select() does not provide as much information for STREAMS devices as .CR poll() . A program calls .CR select() so that it can wait for events on both STREAMS and non-STREAMS devices. If .CR select() returns an event for a STREAMS device, the program can call .CR poll() to get more information. Refer to the .IR poll (2) man page for more information about .CR poll() . .PP .CR select() returns a read event if a .CR poll() .CR POLLIN , .CR POLLERR , .CR POLLNVAL or .CR POLLHUP event exists on the stream. In other words, .CR select() returns a read event if a normal or priority band message is waiting to be read, if a read error exists at the stream head, if a write error exists at the stream head, if the stream is linked under a multiplexor, or if a hang-up has occurred. .PP .CR select() returns a write event if a .CR poll() .CR POLLOUT , .CR POLLWRNORM , .CR POLLERR , or .CR POLLNVAL event exists on the stream. This means that .CR select() returns a write event if normal data can be written without blocking because of flow control, a read error exists at the stream head, a write error exists at the stream head, or the stream is linked under a multiplexor. .PP .CR select() returns an exception event if a .CR poll() .CR POLLPRI event exists on the stream. More specifically, .CR select() returns an exception event if a high-priority message is waiting to be read. .sp 1 .SS Signal Enhancements .PP A new signal, .CR SIGPOLL , has been added for STREAMS. Processes register to receive a .CR SIGPOLL signal for events that occur on a STREAMS device (see the .IR signal (2) man page and .CR I_SETSIG in the .IR streamio (7) man page). The default action is to ignore the signal, not to terminate the process. .SH SEE ALSO close(2), fcntl(2), getmsg(2), open(2), poll(2), putmsg(2), read(2), signal(2), select(2), write(2), streamio(7), and .IR "STREAMS/UX for HP9000 Reference Manual" . .\" .\" index@\f4stream()\f1 \- STREAMS enhancements to standard system calls@@@\f3stream(2)\f1 .\" index@\f1STREAMS system calls@@@\f3stream(2)\f1 .\" index@\f1STREAMS enhancements to system calls@@@\f3stream(2)\f1 .\" index@\f1system calls, STREAMS@@@\f3stream(2)\f1 .\" .\" toc@\f3stream(2)\f1:\0\0\f4stream()\f1@@@STREAMS enhancements to standard system calls .\" .\" fileset_database@stream.2 STREAMS-MAN .\" $Header: stty.2,v 72.4 94/10/27 14:25:21 ssa Exp $ .TA s .TH stty 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME stty(), gtty() \- control terminal device (Bell Version 6 compatibility) .SH SYNOPSIS .C "#include " .PP .C "int stty(int fildes, const struct sgttyb *argp);" .PP .C "int gtty(int fildes, struct sgttyb *argp);" .SS Remarks These system calls are preserved for backward compatibility with Bell Version 6. They provide as close an approximation as possible to the old Version 6 functions. All new code should use the .CR TCSETA and .CR TCGETA .CR ioctl() calls described in .IR termio (7). .SH DESCRIPTION For certain status settings and status inquiries about terminal devices, the functions .CR stty() and .CR gtty() are equivalent to .IP .C "ioctl(fildes, TIOCSETP, argp)" .PP and .IP .C "ioctl(fildes, TIOCGETP, argp)" .PP respectively (see .IR ioctl (2) and .IR termio (7). .SH RETURN VALUE .CR gtty() and .CR stty() return the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR gtty() or .CR stty() fails, .CR errno is set to one of the following values: .TP 15 [EBADF] .CR fildes is not a valid file descriptor. .TP [EFAULT] .CR argp points to an invalid address. .SH SEE ALSO stty(1), exec(2), ioctl(2), sttyV6(7), termio(7), tty(7). .\" .\" index@\f4gtty()\f1 \- control terminal device (Bell Version 6 compatibility)@@@\f3stty(2)\f1 .\" index@\f4stty()\f1 \- control terminal device (Bell Version 6 compatibility)@@@\f3stty(2)\f1 .\" index@\f1control terminal device (Bell Version 6 compatibility)@@@\f3stty(2)\f1 .\" index@\f1terminal device, control (Bell Version 6 compatibility)@@@\f3stty(2)\f1 .\" index@\f1device, control terminal (Bell Version 6 compatibility)@@@\f3stty(2)\f1 .\" .\" links@stty.2 gtty.2 .\" .\" toc@\f3stty(2)\f1:\0\0\f4stty()\f1, \f4gtty()\f1@@@control terminal device (Bell Version 6 compatibility) .\" toc@\f4gtty()\f1:\0\0control terminal device (Bell Version 6 compatibility)@@@see \f3stty(2)\f1 .\" $Header: makecontext.2,v 76.2 95/07/07 14:45:12 ssa Exp $ .TA m .TH makecontext 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME makecontext, swapcontext \- manipulate user contexts .SH SYNOPSIS .\" UX .PP .C "#include " .PP .C "void makecontext(ucontext_t *ucp, (void *func)(), int argc, ...);" .PP .C "int swapcontext(ucontext_t *oucp, const ucontext_t *ucp);" .\" ? .SH DESCRIPTION The .CR makecontext() function modifies the context specified by .IR ucp , which has been initialised using .CR tcontext() . When this context is resumed using .CR swapcontext() or .CR setcontext() , program execution continues by calling .CR func() , passing it the arguments that follow .IR argc in the makecontext() call. .PP Before a call is made to .CR makecontext() , the context being modified should have a stack allocated for it. The value of .IR argc must match the number of integer arguments passed to .CR func() , otherwise the behaviour is undefined. .PP The .IR uc_link member is used to determine the context that will be resumed when the context being modified by .CR makecontext() returns. The .IR uc_link member should be initialised prior to the call to .CR makecontext() . .PP The .CR swapcontext() function saves the current context in the context structure pointed to by .IR oucp and sets the context to the context structure pointed to by .IR ucp . .SH RETURN VALUE On successful completion, .CR swapcontext() returns 0. Otherwise, \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR makecontext() and .CR swapcontext() functions will fail if: .RS .TP 25 [ENOMEM] The .IR ucp argument does not have enough stack left to complete the operation. .SH SEE ALSO exit(), getcontext(), sigaction(), sigprocmask(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4makecontext()\f1 \- manipulate user contexts@@@\f3makecontext(2)\f1 .\" index@\f4swapcontext()\f1 \- manipulate user contexts@@@\f3makecontext(2)\f1 .\" .\" index@\f1manipulate user contexts@@@\f3makecontext(2)\f1 .\" index@\f1user contexts, manipulate@@@\f3makecontext(2)\f1 .\" .\" toc@\f3makecontext(2)\f1:\0\0\f4makecontext()\f1, \f4swapcontext()\f1@@@manipulate user contexts .\" toc@\f4swapcontext()\f1:\0\0manipulate user contexts@@@see \f3makecontext(2)\f1 .\" .\" links@makecontext.2 swapcontext.2 .\" $Header: swapon.2,v 72.5 94/10/12 09:35:25 ssa Exp $ .TA s .TH swapon 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME swapon \- add swap space for interleaved paging/swapping .SH SYNOPSIS .nf .CR "#include " .PP .CR "int swapon(const char *path, ..." .CR " /* " [ "int min," .CR " int limit," .CR " int reserve," ] .CR " int priority */ );" .fi .SS Remarks The ANSI C "\c .CR ",\ ...\&\c" " construct denotes a variable length argument list whose optional and required members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION The .CR swapon() system call makes a block device or a directory named .I path available to the system for paging and swapping. .PP .I priority indicates the order in which the swap space from the device or file system is used. Space is taken from the lower-priority systems first. .PP .CR swapon() can be used only by users who have appropriate privileges. .SS If \f2path\fP names a block device file .CR swapon() makes it available to the system at the specified .I priority for allocation for paging and swapping. .PP In this form, .CR swapon() takes only two arguments: the .I path to the block device file, and the .I priority. .PP The device associated with .I path can be a device already known to the system, defined at system configuration time, or it can be a previously unspecified device. .PP If the device was already defined at system configuration time and also has a start and/or size defined for that swap device, these values are used. .PP Otherwise, if a filesystem exists on the device, swap is added following the filesystem, or if no filesystem exists, the complete device is used for swap. .PP See the appropriate system administrator's manual for information on how the size of the swap area is calculated. .SS If \f2path\fP names a directory .CR swapon() makes the blocks on the file system rooted at .I path available for paging and swapping. .PP The .IR min , .IR limit , and .IR reserve arguments are passed and used only if the .I path argument names a directory. .PP .I min indicates the number of file system blocks to take from the file system when .CR swapon() is called. .PP .I limit indicates the maximum number of file system blocks the swap system is allowed to take from the file system. .PP .I reserve indicates the number of file system blocks that are saved for file system use only. .SH ERRORS If .CR swapon() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] A component of the path prefix denies search permission. .TP [EALREADY] The device or directory associated with .I path already has swap turned on. .TP [EBUSY] The device associated with .I path is already in use. .TP [EEXIST] The device associated with .I path was specified at system configuration time to add swap at a specified location, but that location is within an existing file system on the device. .TP [EFAULT] The LIF header on the device associated with .I path contains inconsistent directory data. .TP [EIO] Unable to read the device associated with .I path. .TP [ELOOP] Too many symbolic links were encountered in translating the path name. .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENODEV] The device associated with .I path does not exist. .TP [ENOENT] The system-imposed limit on the number of swap file entries has been reached. .TP [ENOSPC] There is is not enough available space on the specified file system or device. .TP [ENOSYS] The device associated with .I path was specified at system configuration time to add swap following the file system, but no file system was found. .TP [ENOTBLK] The .I path argument is not a block special file or the root directory of a file system. .TP [ENOTDIR] A component of the path is not a directory. .TP [ENXIO] The device associated with .I path could not be opened. .TP [EPERM] The effective user ID is not a user with appropriate privileges. .TP [EROFS] The device associated with .I path is read-only. .RE .SH WARNINGS No means is available to stop swapping to a device. .PP The system allocates no less than the amount specified in .IR min . However, to make the most efficient use of space, more than the amount requested might be taken from the file system. The actual amount taken will not exceed the number of file system blocks indicated in .IR reserve . .PP Swapping to a file system is usually slower than swapping to a device. .PP Once file system blocks have been allocated for swap space, the file system can not be unmounted unless the system is rebooted. .SH AUTHOR .CR swapon() was developed by the University of California, Berkeley. .SH SEE ALSO swapon(1M). .\" .\" index@\f4swapon()\fP \- add swap device for interleaved paging and swapping@@@\f3swapon(2)\f1 .\" index@add swap device for interleaved paging and swapping@@@\f3swapon(2)\f1 .\" index@swap device for interleaved paging and swapping, add a@@@\f3swapon(2)\f1 .\" index@device for interleaved paging and swapping, add swap@@@\f3swapon(2)\f1 .\" index@interleaved paging and swapping, add swap device for@@@\f3swapon(2)\f1 .\" index@paging, add swap device for interleaved@@@\f3swapon(2)\f1 .\" index@swapping, add swap device for interleaved@@@\f3swapon(2)\f1 .\" index@file system swapping@@@\f3swapon(2)\f1 .\" index@swapping, file system@@@\f3swapon(2)\f1 .\" index@dynamic file system swapping@@@\f3swapon(2)\f1 .\" .\" toc@\f3swapon(2)\f1:\0\0\f4swapon()\f1@@@add swap device for interleaved paging and swapping .\" $Header: symlink.2,v 76.2 95/09/29 09:36:15 ssa Exp $ .TA s .TH symlink 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME symlink \- make symbolic link to a file .SH SYNOPSIS .C "#include " .PP .C "int symlink(const char *path1, const char *path2);" .SH DESCRIPTION The .CR symlink() function creates a symbolic link. Its name is the pathname pointed to by .IR path2 , which must be a pathname that does not name an existing file or symbolic link. The contents of the symbolic link are the string pointed to by .IR path1 . .SH RETURN VALUE Upon successful completion, .CR symlink() returns 0. Otherwise, it returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS The .CR symlink() function will fail if: .RS .TP 25 [EACCES] Write permission is denied in the directory where the symbolic link is being created, or search permission is denied for a component of the path prefix of .IR path2 . .TP [EEXIST] The .IR path2 argument names an existing file or symbolic link. .TP [EIO] An I/O error occurs while reading from or writing to the file system. .TP [ELOOP] Too many symbolic links were encountered in resolving .IR path2 . .TP [ENAMETOOLONG] The length of the .IR path2 argument exceeds .RC { PATH_MAX }, or a pathname component is longer than .RC { NAME_MAX }. .TP [ENOENT] A component of .IR path2 does not name an existing file or .IR path2 is an empty string. .TP [ENOSPC] The directory in which the entry for the new symbolic link is being placed cannot be extended because no space is left on the file system containing the directory, or the new symbolic link cannot be created because no space is left on the file system which will contain the link, or the file system is out of file-allocation resources. .TP [ENOTDIR] A component of the path prefix of .IR path2 is not a directory. .TP [EROFS] The new symbolic link would reside on a read-only file system. .RE .PP The .CR symlink() function may fail if: .RS .TP 25 [ENAMETOOLONG] Pathname resolution of a symbolic link produced an intermediate result whose length exceeds .RC { PATH_MAX }. .RE .SH APPLICATION USAGE Like a hard link, a symbolic link allows a file to have multiple logical names. The presence of a hard link guarantees the existence of a file, even after the original name has been removed. A symbolic link provides no such assurance; in fact, the file named by the .IR path1 argument need not exist when the link is created. A symbolic link can cross file system boundaries. .PP Normal permission checks are made on each component of the symbolic link pathname during its resolution. .SH SEE ALSO lchown(), link(), lstat(), open(), readlink(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" $Header: symlink.2,v 76.2 95/09/29 09:36:15 ssa Exp $ .TA s .TH symlink 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH ERRORS If .CR symlink() fails, .CR errno is set to one of the following values. .RS .TP 25 [EFAULT] .I path1 or .I path2 points outside the process's allocated address space. The reliable detection of this error is implementation-dependent. .TP [EIO] An I/O error occurred while making the directory entry for .IR path2 , allocating the inode for .IR path2 , or writing out the link contents of .IR path2 . .TP [EIO] An I/O error occurred while making the directory entry or allocating the inode. .RE .SH AUTHOR .CR symlink() was developed by the University of California, Berkeley. .SH SEE ALSO cp(1), link(2), readlink(2), unlink(2), symlink(4). .SH STANDARDS CONFORMANCE .CR symlink() ": AES, SVID3" .\" .\" index@\f4symlink()\f1 \- make symbolic link to a file@@@\f3symlink(2)\f1 .\" index@\f1file, make a symbolic link@@@\f3symlink(2)\f1 .\" index@\f1link to a file, make a symbolic@@@\f3symlink(2)\f1 .\" index@\f1make a symbolic link to a file@@@\f3symlink(2)\f1 .\" index@\f1symbolic link to a file, make a@@@\f3symlink(2)\f1 .\" .\" toc@\f3symlink(2)\f1:\0\0\f4symlink()\f1@@@make symbolic link to a file .\" $Header: sync.2,v 72.6 94/11/14 15:27:04 ssa Exp $ .TA s .TH sync 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sync \- update disk .SH SYNOPSIS .C "#include " .PP .C "void sync(void);" .SH DESCRIPTION .C sync() causes all information in memory that should be on disk to be written out. This includes modified file system meta-data and delayed block I/O. .PP It should be used by commands and programs that examine a file system, such as .CR fsck , .CR df , etc. It is mandatory before a shutdown. .PP The writing, although scheduled, is not necessarily complete upon return from .IR sync . .PP In some HP-UX systems, .C sync() may be reduced to a no-op. This is permissible on a system which does not cache buffers, or in a system that in some way ensures that the disks are always in a consistent state. .SH AUTHOR .C sync() was developed by HP and AT&T Bell Laboratories. .SH SEE ALSO sync(1M), fdatasync(2), fsync(2). .SH STANDARDS CONFORMANCE .CR sync() ": SVID2, SVID3, XPG2" .\" .\" index@\f4sync()\f1 \- update super-block@@@\f3sync(2)\f1 .\" index@\f1update super-block@@@\f3sync(2)\f1 .\" index@\f1super-block, update@@@\f3sync(2)\f1 .\" index@\f1flush buffers to disk@@@\f3sync(2)\f1 .\" index@\f1disk, flush buffers to@@@\f3sync(2)\f1 .\" index@\f1buffers, flush to disk@@@\f3sync(2)\f1 .\" .\" toc@\f3sync(2)\f1:\0\0\f4sync()\fP@@@update super-block .\" .\" links@sync.2 lsync.2 .\" $Header: sysconf.2,v 72.10 94/12/08 16:33:04 ssa Exp $ .TA s .TH sysconf 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sysconf() \- get configurable system variables .SH SYNOPSIS .C "#include " .PP .C "long sysconf(int name);" .PP .C "int CPU_IS_PA_RISC(long cpuvers);" .SH DESCRIPTION The .CR sysconf() system call provides a way for applications to determine the current value of a configurable limit or variable. .PP The .I name argument represents the system variable being queried. .PP The following table lists the configuration variables whose values can be determined by calling .CR sysconf() , and for each variable, the associated value of the .I name argument and the value returned: .PP .in 0 \" override left margin (next .PP restores it) .TS tab(:); cB cB cB lf4 lf4 lw(2.4i). Variable:Value for \f2name\fP:Value Returned _ AES_OS_VERSION:_SC_AES_OS_VERSION:T{ Version number of OSF/AES OSC supported T} .ift .sp .5v .ifn .sp 1v ARG_MAX:_SC_ARG_MAX:T{ Maximum total length of the arguments for .CR exec() in bytes, including environment data (see .IR exec (2)) T} .ift .sp .5v .ifn .sp 1v ATEXIT_MAX:_SC_ATEXIT_MAX:T{ Maximum number of functions that can be registered with .CR atexit() (see .IR atexit (2)) T} .ift .sp .5v .ifn .sp 1v BC_BASE_MAX:_SC_BC_BASE_MAX:T{ Maximum ibase (input number radix) and obase (output number radix) allowed by .CR bc (see .IR bc (1)) T} .ift .sp .5v .ifn .sp 1v BC_DIM_MAX:_SC_BC_DIM_MAX:T{ Maximum number of elements in an array permitted by .CR bc (see .IR bc (1)) T} .ift .sp .5v .ifn .sp 1v BC_SCALE_MAX:_SC_BC_SCALE_MAX:T{ Maximum scale factor (number of digits to the right of the decimal point) allowed by .CR bc (see .IR bc (1)) T} .ift .sp .5v .ifn .sp 1v BC_STRING_MAX:_SC_BC_STRING_MAX:T{ Maximum length of strings allowed by .CR bc (see .IR bc (1)) T} .ift .sp .5v .ifn .sp 1v CHILD_MAX:_SC_CHILD_MAX:T{ Maximum number of simultaneous processes per user ID (see .IR fork (2)) T} .ift .sp .5v .ifn .sp 1v CLK_TCK:_SC_CLK_TCK:T{ Number of clock intervals per second for .CR times() (see .IR times (2)) T} .ift .sp .5v .ifn .sp 1v CLOCKS_PER_SEC:_SC_CLOCKS_PER_SEC:T{ Number of clock ticks per second for .CR clock() (see .IR clock (3C)) T} .ift .sp .5v .ifn .sp 1v COLL_WEIGHTS_MAX:_SC_COLL_WEIGHTS_MAX:T{ Maximum number of weights that can be assigned to an entry of the .CR "LC_COLLATE order" keyword in a .CR localedef input file (see .IR localedef (1M)) T} .ift .sp .5v .ifn .sp 1v CPU_KEYBITS1:_SC_CPU_KEYBITS1:T{ Processor Extensions (see below) T} .ift .sp .5v .ifn .sp 1v CPU_VERSION:_SC_CPU_VERSION:T{ Version of CPU architecture (see below) T} .ift .sp .5v .ifn .sp 1v EXPR_NEST_MAX:_SC_EXPR_NEST_MAX:T{ Maximum parenthesis nesting level for .CR expr expressions (see .IR expr (1)) T} .ift .sp .5v .ifn .sp 1v IO_TYPE:_SC_IO_TYPE:T{ Type of I/O drivers the kernel supports, currently, only the value .CR IO_TYPE_CDIO T} .ift .sp .5v .ifn .sp 1v LINE_MAX:_SC_LINE_MAX:T{ Maximum number of bytes in an input line (including the newline) for POSIX.2 utilities T} .ift .sp .5v .ifn .sp 1v NGROUPS_MAX:_SC_NGROUPS_MAX:T{ Maximum number of simultaneous supplementary group IDs per process T} .ift .sp .5v .ifn .sp 1v OPEN_MAX:_SC_OPEN_MAX:T{ Maximum number of files that one process can have open at one time T} .ift .sp .5v .ifn .sp 1v PAGE_SIZE:_SC_PAGE_SIZE:T{ Kernel memory page size T} .ift .sp .5v .ifn .sp 1v PASS_MAX:_SC_PASS_MAX:T{ Maximum number of significant bytes in a password T} .ift .sp .5v .ifn .sp 1v POSIX_FSYNC:_SC_FSYNC:T{ Positive if the File Synchronization option is supported (see .IR fsync (2)) T} .ift .sp .5v .ifn .sp 1v POSIX_JOB_CONTROL:_SC_JOB_CONTROL:T{ Positive if the system supports POSIX job control; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX_PRIORITY_SCHEDULING:_SC_PRIORITY_SCHEDULING:T{ Positive if the system supports POSIX.4 priority scheduling; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX_SAVED_IDS:_SC_SAVED_IDS:T{ Positive if each process has a saved set-user-ID and a saved set-group-ID; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX_SYNCHRONIZED_IO:_SC_SYNCHRONIZED_IO:T{ Positive if the Synchronized IO option is supported (see .IR open (2)) T} .ift .sp .5v .ifn .sp 1v POSIX_TIMERS:_SC_TIMERS:T{ Positive if the system supports POSIX.4 clocks and timers; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX_VERSION:_SC_VERSION:T{ Approval date of the POSIX.1 Standard (such as 199009 for POSIX.1-1990) to which the system conforms. This value indicates the year (first four digits) and month (next two digits) that the standard was approved by the IEEE Standards Board. T} .ift .sp .5v .ifn .sp 1v POSIX2_C_BIND:_SC_2_C_BIND:T{ Equal to 1 if the POSIX.2 C Language Bindings Option is available through the .CR c89 utility; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX2_C_DEV:_SC_2_C_DEV:T{ Equal to 1 if the POSIX.2 C Language Development Utilities Option is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX2_C_VERSION:_SC_2_C_VERSION:T{ Current version of the POSIX.2 C Language Binding Option supported (same format as .CR _POSIX_VERSION ); \(mi1 otherwise. T} .ift .sp .5v .ifn .sp 1v POSIX2_FORT_DEV:_SC_2_FORT_DEV:T{ Equal to 1 if the POSIX.2 FORTRAN Development Utilities Option is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX2_FORT_RUN:_SC_2_FORT_RUN:T{ Equal to 1 if the POSIX.2 Fortran Runtime Utilities Option is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX2_LOCALEDEF:_SC_2_LOCALEDEF:T{ Equal to 1 if locales can be created with the POSIX.2 .IR localedef utility; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX2_SW_DEV:_SC_2_SW_DEV:T{ Equal to 1 if the POSIX.2 Software Development Utilities Option is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX2_UPE:_SC_2_UPE:T{ Equal to 1 if the POSIX.2 User Portability Utilities Option is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v POSIX2_VERSION:_SC_2_VERSION:T{ Current version of POSIX.2 (same format as .CR _POSIX_VERSION ) T} .ift .sp .5v .ifn .sp 1v PROC_RSRC_MGR:_SC_PROC_RSRC_MGR:T{ Equal to 1 if the optional HP Process Resource Management (PRM) software is installed and configured; 0 otherwise (see .IR prmconfig (1)) T} .ift .sp .5v .ifn .sp 1v RE_DUP_MAX:_SC_RE_DUP_MAX:T{ Maximum number of repeated occurrences of a regular expression permitted when using the interval notation .CI \e{ m , n \e} (see .IR regcomp (3C)) T} .ift .sp .5v .ifn .sp 1v SECURITY_CLASS:_SC_SECURITY_CLASS:T{ .CR SEC_CLASS-NONE (No DoD security level supported) T} .ift .sp .5v .ifn .sp 1v STREAM_MAX:_SC_STREAM_MAX:T{ Maximum number of stdio streams that one process can have open at one time T} .ift .sp .5v .ifn .sp 1v TIMER_MAX:_SC_TIMER_MAX:T{ Maximum number of POSIX.4 timers per process, if POSIX.4 timers are supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v TZNAME_MAX:_SC_TZNAME_MAX:T{ Maximum number of bytes in a time zone name for the .CR TZ environment variable T} .ift .sp .5v .ifn .sp 1v XOPEN_CRYPT:_SC_XOPEN_CRYPT:T{ Equal to 1 if the X/Open Encryption Feature Group is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v XOPEN_ENH_I18N:_SC_XOPEN_ENH_I18N:T{ Equal to 1 if the X/Open Enhanced Internationalization Feature Group is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v XOPEN_SHM:_SC_XOPEN_SHM:T{ Equal to 1 if the X/Open Shared Memory Feature Group is supported; \(mi1 otherwise T} .ift .sp .5v .ifn .sp 1v XOPEN_VERSION:_SC_XOPEN_VERSION:T{ Issue number of .IR "X/Open Portability Guide" supported T} _ .TE .PP Some of the variables in the table are defined as constants in .CR (see .IR limits (5)). The associated values of the .I name argument are defined in .CR . .PP The possible values of the .CR CPU_VERSION variable returned by .CR sysconf(_SC_CPU_VERSION) and their meanings are: .PP .TS center tab(:); cB cB lf4p+1w(15n) lw(3i). Value:Meaning _ CPU_PA_RISC1_0:HP Precision Architecture RISC Version 1.0 CPU_PA_RISC1_1:HP Precision Architecture RISC Version 1.1 .\"CPU_PA_RISC2_0:HP Precision Architecture RISC Version 2.0 .TE .PP The .CR CPU_IS_PA_RISC() function classifies .IR cpuvers , a value of the .CR CPU_VERSION variable, as to its processor family. .PP The availability of architecture specific instructions is indicated by the key bit data returned by .CR sysconf(_SC_CPU_KEYBITS1) . Upon successful completion, the data returned will be the logical OR of the defined values for the features supported. .PP The possible values returned by .CR sysconf(_SC_CPU_KEYBITS1) and their meanings are shown in the following table. .PP .TS center tab(:); cB cB lf4p+1w(15n) lw(3i). Return Value:Instruction Supported _ HARITH:Halfword parallel add, subtract, and average HSHIFT:Halfword parallel shift-and-add .TE .PP .SH RETURN VALUE Upon successful completion, .CR sysconf() returns the value of the named variable. If the value of .I name is not valid, .CR sysconf() returns .CR \(mi1 and sets .CR errno to indicate the error. If the variable corresponding to .I name is not defined, .CR sysconf() returns .CR \(mi1 , but does not change .CR errno . .PP .CR CPU_IS_PA_RISC() returns positive nonzero if .IR cpuvers is an HP PA-RISC processor; zero if not. .ift .br .ift .ne 8 .SH ERRORS If .CR sysconf() fails, the value of .CR errno (see .IR errno (2)) is set to: .RS .TP 15 [EINVAL] The value of .I name is not valid. .RE .SH EXAMPLES The following example determines the number of times the system clock ticks each second: .IP .C "#include " .IP .C "long ticks;" .br \0\0... .IP .C "ticks = sysconf(_SC_CLK_TCK);" .PP The following example determines if the current processor is an HP PA-RISC machine: .IP .C "#include " .IP .C "if (CPU_IS_PA_RISC(sysconf(_SC_CPU_VERSION)))" .br \0\0... .SH WARNINGS .CR CPU_IS_PA_RISC() is implemented as a macro. .PP Normally, the values returned from .CR sysconf() do not change during the lifetime of the calling process. However, the value of the symbolic constant .CR _POSIX_VERSION and thus the value of .CR sysconf(_SC_VERSION) can vary under certain circumstances. If either of the feature test macros .CR _POSIX1_1988 or .CR _XPG3 is defined by the programmer prior to including .CR , the value of .CR _POSIX_VERSION is defined as .CR 198808 , in conformance with POSIX.1-1988, FIPS 151-1, and XPG3. Otherwise, the value of .CR _POSIX_VERSION is defined as .CR 199009 , in conformance with POSIX.1-1990. .PP Similarly, the value of the symbolic constant .CR _XOPEN_VERSION and thus the value of .CR sysconf(_SC_XOPEN_VERSION) can vary under certain circumstances. If the feature test macro .CR _XPG3 is defined by the programmer prior to including .CR , the value of .CR _XOPEN_VERSION is defined as .CR 3 , in conformance with XPG3. Otherwise, the value of .CR _XOPEN_VERSION is defined as .CR 4 , in conformance with XPG4. .PP See .IR stdsyms (5) for more information about these feature test macros. .SH AUTHOR .CR sysconf() was developed by HP and POSIX. .PP .CR CPU_IS_PA_RISC() was developed by HP. .SH SEE ALSO getconf(1), atexit(2), exec(2), fork(2), getrlimit(2), pathconf(2), times(2), clock(3C), regcomp(3C), limits(5), stdsyms(5), unistd(5), x_open(5). .PP HP Process Resource Manager: prmconfig(1) in .IR "HP Process Resource Manager User's Guide" . .SH STANDARDS CONFORMANCE .CR sysconf() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.2, POSIX.4" .\" .\" index@\f4sysconf()\f1 \- get configurable system variables@@@\f3sysconf(2)\f1 .\" index@\f1get configurable system variables@@@\f3sysconf(2)\f1 .\" index@\f1configurable system variables, get@@@\f3sysconf(2)\f1 .\" index@\f1system variables, get configurable@@@\f3sysconf(2)\f1 .\" index@\f1variables, system, get configurable@@@\f3sysconf(2)\f1 .\" index@\f1processor type, determine@@@\f3sysconf(2)\f1 .\" .\" toc@\f3sysconf(2)\f1:\0\0\f4sysconf()\f1@@@get configurable system variables\f1 .\" .\" links@sysconf.2 CPU_IS_PA_R.2 .\" $Header: sysfs.2,v 74.1 95/05/10 22:03:25 ssa Exp $ .TA s .TH sysfs 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sysfs - get file system type information .SH SYNOPSIS .PP .C #include .PD .PP .PP .C int sysfs(int .IR opcode, .C const char .IR *fsname .C ); .PP .C int sysfs(int .IR opcode, .C int .IR fs_index, .C char .IR *buf .C ); .PP .C int sysfs(int .IR opcode .C ); .SH DESCRIPTION .C sysfs is used to return information about the file system types configured in the system. The number arguments accepted by .C sysfs varies and depends on the .IR opcode. .PP The current recognized .IR opcodes and their functions are: .RS .TP 15 .C GETFSIND Translate .IR fsname, a null-terminated file-system type identifier, into a file-system type index. .TP .C GETFSTYP Translate .IR fs_index, a file-system type index, into a null-terminated file-system type identifier and write it into the buffer pointed to by .IR buf; this buffer must be at least of size .C FSTYPSZ as defined in .C . .TP .C GETNFSTYP Return one more than the largest file system type configured. This is not the number of file system types configured, because the type numbers may not be contiguous. See the example below. .SH RETURN VALUE Upon successful completion, .C sysfs() returns the file-system type index if the .IR opcode is .C GETFSIND, a value of 0 if the .IR opcode is .C GETFSTYP, or the number of file system types configured if the .IR opcode is .C GETNFSTYP. Otherwise, a value of -1 is returned and .C errno is set to indicate the error. .SH ERRORS .C sysfs fails if one or more of the following are true and sets .C errno to the value indicated: .RS .TP 12 .PD 1 .SM EINVAL .IR fsname points to an invalid file-system identifier; .IR fs_index is zero, or invalid; .IR opcode is invalid. .TP 12 .SM EFAULT .IR buf or .IR fsname points to an invalid user address. .RE .SH EXAMPLE .PP List the filesystem types configured in the system. .nf .IP .C "#include " .C "int max_type, error, i;" .C "char name[FSTYPSZ];" .C "" .C "max_type = sysfs(GETNFSTYP);" .C "for (i = 0; i < max_type; i++) {" .C " error = sysfs(GETFSTYP, i, name);" .C " if (error == 0)" .C " my_print(name);" .C "}" .\" .\" index@\f4sysfs()\fP \(mi get file system type info@@@\f3sysfs(2)\f1 .\" index@get file system type info@@@\f3sysfs(2)\f1 .\" index@file system type info, get@@@\f3sysfs(2)\f1 .\" .\" toc@\f3sysfs(2)\f1:\0\0\f4sysfs()\fP@@@get file system type info .\" $Header: time.2,v 72.5 94/11/14 15:27:07 ssa Exp $ .TA t .TH time 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME time \- get time .SH SYNOPSIS .C "#include " .PP .C "time_t time(time_t *tloc);" .SH DESCRIPTION .C time() returns the value of time in seconds since the Epoch. .PP If .I tloc is not a null pointer, the return value is also assigned to the object to which it points. .SH RETURN VALUE Upon successful completion, .C time() returns the value of time. Otherwise, a value of .RC ( time_t )\(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .TP 15 .SM [EFAULT] .C time() fails if .I tloc points to an illegal address. The reliable detection of this error is implementation dependent. .SH SEE ALSO date(1), gettimeofday(2), stime(2), ctime(3C), strftime(3C). .SH STANDARDS CONFORMANCE .CR time() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" .\" index@\f4time()\fP \(mi get time@@@\f3time(2)\f1 .\" index@get: time@@@\f3time(2)\f1 .\" index@time, get@@@\f3time(2)\f1 .\" .\" toc@\f3time(2)\f1:\0\0\f4time()\fP@@@get time .\" $Header: timers.2,v 78.1 95/12/20 11:20:29 ssa Exp $ .TA t .TH timers 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME timer_create(), timer_delete(), timer_settime(), timer_gettime(), timer_getoverrun() \- timer operations .SH SYNOPSIS .C "#include " .PP .nf .C "int timer_create(" .PD 0 .IP .C "clockid_t clock_id," .C "struct sigevent *evp," .C "timer_t *timerid" .PP .C ");" .PD .C "int timer_delete(" .PD 0 .IP .C "timer_t timerid" .PP .C ");" .PD .C "int timer_settime(" .PD 0 .IP .C "timer_t timerid," .C "int flags," .C "const struct itimerspec *value," .C "struct itimerspec *ovalue" .PP .C ");" .PD .C "int timer_gettime(" .PD 0 .IP .C "timer_t timerid," .C "struct itimerspec *value" .PP .C ");" .PD .C "int timer_getoverrun(" .PD 0 .IP .C "timer_t timerid" .PP .C ");" .PD .SH DESCRIPTION .SS timer_create() The .CR timer_create() function creates a per-process timer using the specified clock, .CR clock_id , as the timing base. The .CR timer_create() function returns, in the location referenced by .CR timerid , a timer .SM ID of type .CR timer_t used to identify the timer in timer requests. This timer ID will be unique within the calling process until the timer is deleted. The particular clock, .CR clock_id , is defined in .CR . The timer whose .SM ID is returned will be in a disarmed state upon return from .CR timer_create() . .PP The .CR evp argument, if non-\c .SM NULL, points to a .I sigevent structure. If the .I sigev_notify member of .CR evp is SIGEV_SIGNAL, then the structure should also specify the signal number to be sent to the process on timer expiration. The signal to be sent is specified in the .I sigev_signo field of .CR evp . If the .I sigev_notify member of .I evp is SIGEV_NONE, no notification is sent. If .CR evp is .SM NULL, then a default signal is sent to the process. The defaults for the clocks .CR CLOCK_REALTIME , .CR CLOCK_VIRTUAL , and .CR CLOCK_PROFILE are .CR SIGALRM , .CR SIGVTALRM , and .CR SIGPROF . .PP Per-process timers are not inherited by a child process across a .CR fork() and are disarmed and deleted by an .CR exec() . .SS timer_delete() .PP The .CR timer_delete() function deletes the specified timer, .CR timerid , previously created by the .CR timer_create() function. If the timer is armed when .CR timer_delete() is called, the behavior is as if the timer is automatically disarmed before removal. Any pending notifications from the timer remain. .SS timer_settime() .PP The .CR timer_settime() function sets the time until the next expiration of the timer specified by .CR timerid from the .CR it_value member of the .CR value argument and arms the timer if the .CR it_value member of .CR value is non-zero. If the specified timer was already armed when .CR timer_settime() is called, this call resets the time until next expiration to the .CR value specified. If the .CR it_value member of .CR value is zero, the timer is disarmed. Any pending notifications from the timer remain. .PP If the flag .CR TIMER_ABSTIME is not set in the argument .CR flags , .CR timer_settime() behaves as if the time until next expiration is set equal to the interval specified by the .CR it_value member of .CR value . That is, the timer will expire in .CR it_value nanoseconds from when the call is made. .PP If the flag .CR TIMER_ABSTIME is set in the argument .CR flags , .CR timer_settime() behaves as if the time until next expiration is set equal to the difference between the absolute time specified by the .CR it_value member of .CR value and the current value of the clock associated with .CR timerid . That is, the timer will expire when the clock reaches the value specified by the .CR it_value member of .CR value . If the specified time has already passed, the function will succeed and the expiration notification is made. .PP The reload value of the timer is set to the value specified by the .CR it_interval member of .CR value . When a timer is armed with a non-zero .CR it_interval , a periodic (or repetitive) timer is specified. .PP Time values that are between two consecutive non-negative integer multiples of the resolution of the specified timer are rounded up to the larger multiple of the resolution. A quantization error will not cause the timer to expire earlier than the rounded-up time value. .PP If the argument .CR ovalue is not .SM NULL, the function .CR timer_settime() stores, in the location referenced by .CR ovalue , a value representing the previous amount of time before the timer would have expired or zero if the timer was disarmed, together with the previous timer reload value. The members of .CR ovalue are subject to the resolution of the timer, and are the same values that would be returned by a .CR timer_gettime() call at that point in time. .SS timer_gettime() .PP The .CR timer_gettime() function stores the amount of time until the specified timer, .CR timerid , expires and the timer's reload value into the space pointed to by the .CR value argument. The .CR it_value member of this structure will contain the amount of time before the timer expires, or zero if the timer is disarmed. This value is returned as the interval until timer expiration, even if the timer was armed with absolute time. The .CR it_interval member of .CR value will contain the reload value last set by .CR timer_settime() . .SS timer_getoverrun() .PP Only a single signal is delivered to the process for a given timer at any point in time. When a timer for which a signal is still pending expires, no signal is delivered, and a timer overrun has occurred. When a timer expiration signal is delivered to a process, the .CR timer_getoverrun() function returns the timer expiration count for the specified timer. The overrun count returned contains the number of extra timer expirations which occurred between the time the signal was generated and when it was delivered, up to but not including an implementation defined maximum of .CR DELAYTIMER_MAX . If the number of such extra expirations is greater than or equal to .CR DELAYTIMER_MAX , then the overrun count is set to .CR DELAYTIMER_MAX . The value returned by .CR timer_getoverrun() applies to the most recent expiration signal delivery for the timer. If no expiration signal has been delivered for the timer, the meaning of the overrun count returned is undefined. .SH RETURN VALUE Upon successful completion, .CR timer_create() returns zero and updates the location referenced by .CR timerid to a .CR timer_t which can be passed to the per-process timer calls. Otherwise, .CR timer_create() returns \(mi1 and sets .CR errno to indicate the error. The value of .CR timerid is undefined if an error occurs. .PP Upon successful completion, .CR timer_delete() returns zero. Otherwise, .CR timer_delete() returns \(mi1 and sets .CR errno to indicate the error. .PP Upon successful completion, .CR timer_settime() returns zero and updates the location referenced by .CR ovalue , if .CR ovalue is non-\c .SM NULL. .PP Upon successful completion, .CR timer_gettime() returns zero and updates the location referenced by .CR value , if .CR ovalue is non-\c .SM NULL. Otherwise, .CR timer_gettime() returns \(mi1 and sets .CR errno to indicate the error. .PP Upon successful completion, .CR timer_getoverrun() returns the timer expiration overrun count as explained above. Otherwise, .CR timer_getoverrun() returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS If any of the following conditions occur, the .CR timer_create() function returns \(mi1 and sets .CR errno (see .IR errno (2)) to the corresponding value: .RS .TP 12 .SM [EAGAIN] The system lacks sufficient signal queuing resources to honor the request. .TP .SM [EAGAIN] The calling process has already created all of the timers it is allowed by this implementation. .TP .SM [EINVAL] The specified clock .SM ID is not defined. .TP .SM [EFAULT] The .CR timerid or .CR evp argument points to an invalid address. .TP .SM [ENOSYS] The function .CR timer_create() is not supported by this implementation. .RE .PP If any of the following conditions occur, the .CR timer_delete() function returns \(mi1 and sets .CR errno to the corresponding value: .RS .TP 12 .SM [EINVAL] The timer .SM ID specified by .CR timerid is not a valid timer .SM ID. .TP .SM [ENOSYS] The function .CR timer_delete() is not supported by this implementation. .RE .PP If any of the following conditions occur, the .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() functions return \(mi1 and set .CR errno to the corresponding value: .RS .TP 12 .SM [EINVAL] The .CR timerid argument does not correspond to an .SM ID returned by .CR timer_create() , but not yet deleted by .CR timer_delete() . .TP .SM [EINVAL] The .I value structure passed to .CR timer_settime() specified a nanosecond value less than zero or greater than or equal to 1000 million. .TP .SM [EFAULT] The .CR value or .CR ovalue argument points to an invalid address. .TP .SM [ENOSYS] The .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() functions are not supported by this implementation. .RE .SH EXAMPLES Create a timer, set it to go off in one minute, and deliver a .CR SIGUSR1 signal: .PD 0 .nf .RS .C #include .C #include .C timer_t timerid; .C "struct itimerspec one_minute = { {60, 0}, {0, 0} }"; .C void handler() .C { .RS .C int overrun = timer_getoverrun(timerid); .C " " .C if (overrun == -1) { .RS .C perror("handler: timer_getoverrun()"); .C exit(1); .RE .C } .C (void)printf("Timer expired, overrun count was %d, 0 expected.\en", .RS .RS .C overrun); .RE .RE .RE .C } .C int main() .C { .RS .C struct sigaction sigact; .C struct sigevent sigev; .C " " .C sigact.sa_handler = handler; .C sigemptyset(sigact.sa_mask); .C sigact.sa_flags = 0; .C " " .C if (sigaction(SIGUSR1, &sigact, (struct sigaction *)NULL) .RS .C == -1) { .RE .RS .C perror("sigaction"); .C exit(1); .RE .C } .C " " .C sigev.sigev_notify = SIGEV_SIGNAL; .C sigev.sigev_signo = SIGUSR1; .C " " .C if (timer_create(CLOCK_REALTIME, &sigev, &timerid) .RS .C == -1) { .RE .RS .C perror("timer_create"); .C exit(1); .RE .C } .C " " .C if (timer_settime(timerid, 0, &one_minute, (struct itimerspec *)NULL) .RS .C == -1) { .RE .RS .C perror("timer_create"); .C exit(1); .RE .C } .C " " .C pause(); .C if (timer_delete(timerid) == -1) { .RS .C perror("timer_delete"); .C exit(1); .RE .C } .C return 0; .RE .C } .RE .PD .fi .SH AUTHOR .CR timer_create() , .CR timer_delete() , .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .SH SEE ALSO clocks(2), getitimer(2). .SH STANDARDS CONFORMANCE .CR timer_create() ": POSIX.4" .br .CR timer_delete() ": POSIX.4" .br .CR timer_getoverrun() ": POSIX.4" .br .CR timer_gettime() ": POSIX.4" .br .CR timer_settime() ": POSIX.4" .\" .\" toc@\f3timers(2)\f1:\0\0\f4timer_create()\f1, \f4timer_delete()\f1, \f4timer_settime()\f1,\n \f4timer_gettime()\f1, \f4timer_getoverrun()\f1@@@timer operations\f1 .\" toc@\f4timer_create()\f1:\0\0create timer@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_delete()\f1:\0\0delete timer@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_settime()\f1:\0\0set timer expiration@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_gettime()\f1:\0\0store timer expiration and reload value@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_getoverrun()\f1:\0\0return timer expiration count@@@\f1see \f3timers(2)\f1 .\" .\" index@\f4timer_create()\f1 \- create timer@@@\f3timers(2)\f1 .\" index@\f4timer_delete()\f1 \- delete timer@@@\f3timers(2)\f1 .\" index@\f4timer_settime()\f1 \- set timer expiration@@@\f3timers(2)\f1 .\" index@\f4timer_gettime()\f1 \- store timer expiration and reload value@@@\f3timers(2)\f1 .\" index@\f4timer_getoverrun()\f1 \- return timer expiration count@@@\f3timers(2)\f1 .\" index@\f1timer operations@@@\f3timers(2)\f1 .\" index@\f1operations, timer@@@\f3timers(2)\f1 .\"" .\" links@timers.2 timer_create.2 .\" links@timers.2 timer_delete.2 .\" links@timers.2 timer_settime.2 .\" links@timers.2 timer_gettime.2 .\" links@timers.2 timer_getoverrun.2 .\" $Header: timers.2,v 78.1 95/12/20 11:20:29 ssa Exp $ .TA t .TH timers 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME timer_create(), timer_delete(), timer_settime(), timer_gettime(), timer_getoverrun() \- timer operations .SH SYNOPSIS .C "#include " .PP .nf .C "int timer_create(" .PD 0 .IP .C "clockid_t clock_id," .C "struct sigevent *evp," .C "timer_t *timerid" .PP .C ");" .PD .C "int timer_delete(" .PD 0 .IP .C "timer_t timerid" .PP .C ");" .PD .C "int timer_settime(" .PD 0 .IP .C "timer_t timerid," .C "int flags," .C "const struct itimerspec *value," .C "struct itimerspec *ovalue" .PP .C ");" .PD .C "int timer_gettime(" .PD 0 .IP .C "timer_t timerid," .C "struct itimerspec *value" .PP .C ");" .PD .C "int timer_getoverrun(" .PD 0 .IP .C "timer_t timerid" .PP .C ");" .PD .SH DESCRIPTION .SS timer_create() The .CR timer_create() function creates a per-process timer using the specified clock, .CR clock_id , as the timing base. The .CR timer_create() function returns, in the location referenced by .CR timerid , a timer .SM ID of type .CR timer_t used to identify the timer in timer requests. This timer ID will be unique within the calling process until the timer is deleted. The particular clock, .CR clock_id , is defined in .CR . The timer whose .SM ID is returned will be in a disarmed state upon return from .CR timer_create() . .PP The .CR evp argument, if non-\c .SM NULL, points to a .I sigevent structure. If the .I sigev_notify member of .CR evp is SIGEV_SIGNAL, then the structure should also specify the signal number to be sent to the process on timer expiration. The signal to be sent is specified in the .I sigev_signo field of .CR evp . If the .I sigev_notify member of .I evp is SIGEV_NONE, no notification is sent. If .CR evp is .SM NULL, then a default signal is sent to the process. The defaults for the clocks .CR CLOCK_REALTIME , .CR CLOCK_VIRTUAL , and .CR CLOCK_PROFILE are .CR SIGALRM , .CR SIGVTALRM , and .CR SIGPROF . .PP Per-process timers are not inherited by a child process across a .CR fork() and are disarmed and deleted by an .CR exec() . .SS timer_delete() .PP The .CR timer_delete() function deletes the specified timer, .CR timerid , previously created by the .CR timer_create() function. If the timer is armed when .CR timer_delete() is called, the behavior is as if the timer is automatically disarmed before removal. Any pending notifications from the timer remain. .SS timer_settime() .PP The .CR timer_settime() function sets the time until the next expiration of the timer specified by .CR timerid from the .CR it_value member of the .CR value argument and arms the timer if the .CR it_value member of .CR value is non-zero. If the specified timer was already armed when .CR timer_settime() is called, this call resets the time until next expiration to the .CR value specified. If the .CR it_value member of .CR value is zero, the timer is disarmed. Any pending notifications from the timer remain. .PP If the flag .CR TIMER_ABSTIME is not set in the argument .CR flags , .CR timer_settime() behaves as if the time until next expiration is set equal to the interval specified by the .CR it_value member of .CR value . That is, the timer will expire in .CR it_value nanoseconds from when the call is made. .PP If the flag .CR TIMER_ABSTIME is set in the argument .CR flags , .CR timer_settime() behaves as if the time until next expiration is set equal to the difference between the absolute time specified by the .CR it_value member of .CR value and the current value of the clock associated with .CR timerid . That is, the timer will expire when the clock reaches the value specified by the .CR it_value member of .CR value . If the specified time has already passed, the function will succeed and the expiration notification is made. .PP The reload value of the timer is set to the value specified by the .CR it_interval member of .CR value . When a timer is armed with a non-zero .CR it_interval , a periodic (or repetitive) timer is specified. .PP Time values that are between two consecutive non-negative integer multiples of the resolution of the specified timer are rounded up to the larger multiple of the resolution. A quantization error will not cause the timer to expire earlier than the rounded-up time value. .PP If the argument .CR ovalue is not .SM NULL, the function .CR timer_settime() stores, in the location referenced by .CR ovalue , a value representing the previous amount of time before the timer would have expired or zero if the timer was disarmed, together with the previous timer reload value. The members of .CR ovalue are subject to the resolution of the timer, and are the same values that would be returned by a .CR timer_gettime() call at that point in time. .SS timer_gettime() .PP The .CR timer_gettime() function stores the amount of time until the specified timer, .CR timerid , expires and the timer's reload value into the space pointed to by the .CR value argument. The .CR it_value member of this structure will contain the amount of time before the timer expires, or zero if the timer is disarmed. This value is returned as the interval until timer expiration, even if the timer was armed with absolute time. The .CR it_interval member of .CR value will contain the reload value last set by .CR timer_settime() . .SS timer_getoverrun() .PP Only a single signal is delivered to the process for a given timer at any point in time. When a timer for which a signal is still pending expires, no signal is delivered, and a timer overrun has occurred. When a timer expiration signal is delivered to a process, the .CR timer_getoverrun() function returns the timer expiration count for the specified timer. The overrun count returned contains the number of extra timer expirations which occurred between the time the signal was generated and when it was delivered, up to but not including an implementation defined maximum of .CR DELAYTIMER_MAX . If the number of such extra expirations is greater than or equal to .CR DELAYTIMER_MAX , then the overrun count is set to .CR DELAYTIMER_MAX . The value returned by .CR timer_getoverrun() applies to the most recent expiration signal delivery for the timer. If no expiration signal has been delivered for the timer, the meaning of the overrun count returned is undefined. .SH RETURN VALUE Upon successful completion, .CR timer_create() returns zero and updates the location referenced by .CR timerid to a .CR timer_t which can be passed to the per-process timer calls. Otherwise, .CR timer_create() returns \(mi1 and sets .CR errno to indicate the error. The value of .CR timerid is undefined if an error occurs. .PP Upon successful completion, .CR timer_delete() returns zero. Otherwise, .CR timer_delete() returns \(mi1 and sets .CR errno to indicate the error. .PP Upon successful completion, .CR timer_settime() returns zero and updates the location referenced by .CR ovalue , if .CR ovalue is non-\c .SM NULL. .PP Upon successful completion, .CR timer_gettime() returns zero and updates the location referenced by .CR value , if .CR ovalue is non-\c .SM NULL. Otherwise, .CR timer_gettime() returns \(mi1 and sets .CR errno to indicate the error. .PP Upon successful completion, .CR timer_getoverrun() returns the timer expiration overrun count as explained above. Otherwise, .CR timer_getoverrun() returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS If any of the following conditions occur, the .CR timer_create() function returns \(mi1 and sets .CR errno (see .IR errno (2)) to the corresponding value: .RS .TP 12 .SM [EAGAIN] The system lacks sufficient signal queuing resources to honor the request. .TP .SM [EAGAIN] The calling process has already created all of the timers it is allowed by this implementation. .TP .SM [EINVAL] The specified clock .SM ID is not defined. .TP .SM [EFAULT] The .CR timerid or .CR evp argument points to an invalid address. .TP .SM [ENOSYS] The function .CR timer_create() is not supported by this implementation. .RE .PP If any of the following conditions occur, the .CR timer_delete() function returns \(mi1 and sets .CR errno to the corresponding value: .RS .TP 12 .SM [EINVAL] The timer .SM ID specified by .CR timerid is not a valid timer .SM ID. .TP .SM [ENOSYS] The function .CR timer_delete() is not supported by this implementation. .RE .PP If any of the following conditions occur, the .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() functions return \(mi1 and set .CR errno to the corresponding value: .RS .TP 12 .SM [EINVAL] The .CR timerid argument does not correspond to an .SM ID returned by .CR timer_create() , but not yet deleted by .CR timer_delete() . .TP .SM [EINVAL] The .I value structure passed to .CR timer_settime() specified a nanosecond value less than zero or greater than or equal to 1000 million. .TP .SM [EFAULT] The .CR value or .CR ovalue argument points to an invalid address. .TP .SM [ENOSYS] The .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() functions are not supported by this implementation. .RE .SH EXAMPLES Create a timer, set it to go off in one minute, and deliver a .CR SIGUSR1 signal: .PD 0 .nf .RS .C #include .C #include .C timer_t timerid; .C "struct itimerspec one_minute = { {60, 0}, {0, 0} }"; .C void handler() .C { .RS .C int overrun = timer_getoverrun(timerid); .C " " .C if (overrun == -1) { .RS .C perror("handler: timer_getoverrun()"); .C exit(1); .RE .C } .C (void)printf("Timer expired, overrun count was %d, 0 expected.\en", .RS .RS .C overrun); .RE .RE .RE .C } .C int main() .C { .RS .C struct sigaction sigact; .C struct sigevent sigev; .C " " .C sigact.sa_handler = handler; .C sigemptyset(sigact.sa_mask); .C sigact.sa_flags = 0; .C " " .C if (sigaction(SIGUSR1, &sigact, (struct sigaction *)NULL) .RS .C == -1) { .RE .RS .C perror("sigaction"); .C exit(1); .RE .C } .C " " .C sigev.sigev_notify = SIGEV_SIGNAL; .C sigev.sigev_signo = SIGUSR1; .C " " .C if (timer_create(CLOCK_REALTIME, &sigev, &timerid) .RS .C == -1) { .RE .RS .C perror("timer_create"); .C exit(1); .RE .C } .C " " .C if (timer_settime(timerid, 0, &one_minute, (struct itimerspec *)NULL) .RS .C == -1) { .RE .RS .C perror("timer_create"); .C exit(1); .RE .C } .C " " .C pause(); .C if (timer_delete(timerid) == -1) { .RS .C perror("timer_delete"); .C exit(1); .RE .C } .C return 0; .RE .C } .RE .PD .fi .SH AUTHOR .CR timer_create() , .CR timer_delete() , .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .SH SEE ALSO clocks(2), getitimer(2). .SH STANDARDS CONFORMANCE .CR timer_create() ": POSIX.4" .br .CR timer_delete() ": POSIX.4" .br .CR timer_getoverrun() ": POSIX.4" .br .CR timer_gettime() ": POSIX.4" .br .CR timer_settime() ": POSIX.4" .\" .\" toc@\f3timers(2)\f1:\0\0\f4timer_create()\f1, \f4timer_delete()\f1, \f4timer_settime()\f1,\n \f4timer_gettime()\f1, \f4timer_getoverrun()\f1@@@timer operations\f1 .\" toc@\f4timer_create()\f1:\0\0create timer@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_delete()\f1:\0\0delete timer@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_settime()\f1:\0\0set timer expiration@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_gettime()\f1:\0\0store timer expiration and reload value@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_getoverrun()\f1:\0\0return timer expiration count@@@\f1see \f3timers(2)\f1 .\" .\" index@\f4timer_create()\f1 \- create timer@@@\f3timers(2)\f1 .\" index@\f4timer_delete()\f1 \- delete timer@@@\f3timers(2)\f1 .\" index@\f4timer_settime()\f1 \- set timer expiration@@@\f3timers(2)\f1 .\" index@\f4timer_gettime()\f1 \- store timer expiration and reload value@@@\f3timers(2)\f1 .\" index@\f4timer_getoverrun()\f1 \- return timer expiration count@@@\f3timers(2)\f1 .\" index@\f1timer operations@@@\f3timers(2)\f1 .\" index@\f1operations, timer@@@\f3timers(2)\f1 .\"" .\" links@timers.2 timer_create.2 .\" links@timers.2 timer_delete.2 .\" links@timers.2 timer_settime.2 .\" links@timers.2 timer_gettime.2 .\" links@timers.2 timer_getoverrun.2 .\" $Header: timers.2,v 78.1 95/12/20 11:20:29 ssa Exp $ .TA t .TH timers 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME timer_create(), timer_delete(), timer_settime(), timer_gettime(), timer_getoverrun() \- timer operations .SH SYNOPSIS .C "#include " .PP .nf .C "int timer_create(" .PD 0 .IP .C "clockid_t clock_id," .C "struct sigevent *evp," .C "timer_t *timerid" .PP .C ");" .PD .C "int timer_delete(" .PD 0 .IP .C "timer_t timerid" .PP .C ");" .PD .C "int timer_settime(" .PD 0 .IP .C "timer_t timerid," .C "int flags," .C "const struct itimerspec *value," .C "struct itimerspec *ovalue" .PP .C ");" .PD .C "int timer_gettime(" .PD 0 .IP .C "timer_t timerid," .C "struct itimerspec *value" .PP .C ");" .PD .C "int timer_getoverrun(" .PD 0 .IP .C "timer_t timerid" .PP .C ");" .PD .SH DESCRIPTION .SS timer_create() The .CR timer_create() function creates a per-process timer using the specified clock, .CR clock_id , as the timing base. The .CR timer_create() function returns, in the location referenced by .CR timerid , a timer .SM ID of type .CR timer_t used to identify the timer in timer requests. This timer ID will be unique within the calling process until the timer is deleted. The particular clock, .CR clock_id , is defined in .CR . The timer whose .SM ID is returned will be in a disarmed state upon return from .CR timer_create() . .PP The .CR evp argument, if non-\c .SM NULL, points to a .I sigevent structure. If the .I sigev_notify member of .CR evp is SIGEV_SIGNAL, then the structure should also specify the signal number to be sent to the process on timer expiration. The signal to be sent is specified in the .I sigev_signo field of .CR evp . If the .I sigev_notify member of .I evp is SIGEV_NONE, no notification is sent. If .CR evp is .SM NULL, then a default signal is sent to the process. The defaults for the clocks .CR CLOCK_REALTIME , .CR CLOCK_VIRTUAL , and .CR CLOCK_PROFILE are .CR SIGALRM , .CR SIGVTALRM , and .CR SIGPROF . .PP Per-process timers are not inherited by a child process across a .CR fork() and are disarmed and deleted by an .CR exec() . .SS timer_delete() .PP The .CR timer_delete() function deletes the specified timer, .CR timerid , previously created by the .CR timer_create() function. If the timer is armed when .CR timer_delete() is called, the behavior is as if the timer is automatically disarmed before removal. Any pending notifications from the timer remain. .SS timer_settime() .PP The .CR timer_settime() function sets the time until the next expiration of the timer specified by .CR timerid from the .CR it_value member of the .CR value argument and arms the timer if the .CR it_value member of .CR value is non-zero. If the specified timer was already armed when .CR timer_settime() is called, this call resets the time until next expiration to the .CR value specified. If the .CR it_value member of .CR value is zero, the timer is disarmed. Any pending notifications from the timer remain. .PP If the flag .CR TIMER_ABSTIME is not set in the argument .CR flags , .CR timer_settime() behaves as if the time until next expiration is set equal to the interval specified by the .CR it_value member of .CR value . That is, the timer will expire in .CR it_value nanoseconds from when the call is made. .PP If the flag .CR TIMER_ABSTIME is set in the argument .CR flags , .CR timer_settime() behaves as if the time until next expiration is set equal to the difference between the absolute time specified by the .CR it_value member of .CR value and the current value of the clock associated with .CR timerid . That is, the timer will expire when the clock reaches the value specified by the .CR it_value member of .CR value . If the specified time has already passed, the function will succeed and the expiration notification is made. .PP The reload value of the timer is set to the value specified by the .CR it_interval member of .CR value . When a timer is armed with a non-zero .CR it_interval , a periodic (or repetitive) timer is specified. .PP Time values that are between two consecutive non-negative integer multiples of the resolution of the specified timer are rounded up to the larger multiple of the resolution. A quantization error will not cause the timer to expire earlier than the rounded-up time value. .PP If the argument .CR ovalue is not .SM NULL, the function .CR timer_settime() stores, in the location referenced by .CR ovalue , a value representing the previous amount of time before the timer would have expired or zero if the timer was disarmed, together with the previous timer reload value. The members of .CR ovalue are subject to the resolution of the timer, and are the same values that would be returned by a .CR timer_gettime() call at that point in time. .SS timer_gettime() .PP The .CR timer_gettime() function stores the amount of time until the specified timer, .CR timerid , expires and the timer's reload value into the space pointed to by the .CR value argument. The .CR it_value member of this structure will contain the amount of time before the timer expires, or zero if the timer is disarmed. This value is returned as the interval until timer expiration, even if the timer was armed with absolute time. The .CR it_interval member of .CR value will contain the reload value last set by .CR timer_settime() . .SS timer_getoverrun() .PP Only a single signal is delivered to the process for a given timer at any point in time. When a timer for which a signal is still pending expires, no signal is delivered, and a timer overrun has occurred. When a timer expiration signal is delivered to a process, the .CR timer_getoverrun() function returns the timer expiration count for the specified timer. The overrun count returned contains the number of extra timer expirations which occurred between the time the signal was generated and when it was delivered, up to but not including an implementation defined maximum of .CR DELAYTIMER_MAX . If the number of such extra expirations is greater than or equal to .CR DELAYTIMER_MAX , then the overrun count is set to .CR DELAYTIMER_MAX . The value returned by .CR timer_getoverrun() applies to the most recent expiration signal delivery for the timer. If no expiration signal has been delivered for the timer, the meaning of the overrun count returned is undefined. .SH RETURN VALUE Upon successful completion, .CR timer_create() returns zero and updates the location referenced by .CR timerid to a .CR timer_t which can be passed to the per-process timer calls. Otherwise, .CR timer_create() returns \(mi1 and sets .CR errno to indicate the error. The value of .CR timerid is undefined if an error occurs. .PP Upon successful completion, .CR timer_delete() returns zero. Otherwise, .CR timer_delete() returns \(mi1 and sets .CR errno to indicate the error. .PP Upon successful completion, .CR timer_settime() returns zero and updates the location referenced by .CR ovalue , if .CR ovalue is non-\c .SM NULL. .PP Upon successful completion, .CR timer_gettime() returns zero and updates the location referenced by .CR value , if .CR ovalue is non-\c .SM NULL. Otherwise, .CR timer_gettime() returns \(mi1 and sets .CR errno to indicate the error. .PP Upon successful completion, .CR timer_getoverrun() returns the timer expiration overrun count as explained above. Otherwise, .CR timer_getoverrun() returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS If any of the following conditions occur, the .CR timer_create() function returns \(mi1 and sets .CR errno (see .IR errno (2)) to the corresponding value: .RS .TP 12 .SM [EAGAIN] The system lacks sufficient signal queuing resources to honor the request. .TP .SM [EAGAIN] The calling process has already created all of the timers it is allowed by this implementation. .TP .SM [EINVAL] The specified clock .SM ID is not defined. .TP .SM [EFAULT] The .CR timerid or .CR evp argument points to an invalid address. .TP .SM [ENOSYS] The function .CR timer_create() is not supported by this implementation. .RE .PP If any of the following conditions occur, the .CR timer_delete() function returns \(mi1 and sets .CR errno to the corresponding value: .RS .TP 12 .SM [EINVAL] The timer .SM ID specified by .CR timerid is not a valid timer .SM ID. .TP .SM [ENOSYS] The function .CR timer_delete() is not supported by this implementation. .RE .PP If any of the following conditions occur, the .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() functions return \(mi1 and set .CR errno to the corresponding value: .RS .TP 12 .SM [EINVAL] The .CR timerid argument does not correspond to an .SM ID returned by .CR timer_create() , but not yet deleted by .CR timer_delete() . .TP .SM [EINVAL] The .I value structure passed to .CR timer_settime() specified a nanosecond value less than zero or greater than or equal to 1000 million. .TP .SM [EFAULT] The .CR value or .CR ovalue argument points to an invalid address. .TP .SM [ENOSYS] The .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() functions are not supported by this implementation. .RE .SH EXAMPLES Create a timer, set it to go off in one minute, and deliver a .CR SIGUSR1 signal: .PD 0 .nf .RS .C #include .C #include .C timer_t timerid; .C "struct itimerspec one_minute = { {60, 0}, {0, 0} }"; .C void handler() .C { .RS .C int overrun = timer_getoverrun(timerid); .C " " .C if (overrun == -1) { .RS .C perror("handler: timer_getoverrun()"); .C exit(1); .RE .C } .C (void)printf("Timer expired, overrun count was %d, 0 expected.\en", .RS .RS .C overrun); .RE .RE .RE .C } .C int main() .C { .RS .C struct sigaction sigact; .C struct sigevent sigev; .C " " .C sigact.sa_handler = handler; .C sigemptyset(sigact.sa_mask); .C sigact.sa_flags = 0; .C " " .C if (sigaction(SIGUSR1, &sigact, (struct sigaction *)NULL) .RS .C == -1) { .RE .RS .C perror("sigaction"); .C exit(1); .RE .C } .C " " .C sigev.sigev_notify = SIGEV_SIGNAL; .C sigev.sigev_signo = SIGUSR1; .C " " .C if (timer_create(CLOCK_REALTIME, &sigev, &timerid) .RS .C == -1) { .RE .RS .C perror("timer_create"); .C exit(1); .RE .C } .C " " .C if (timer_settime(timerid, 0, &one_minute, (struct itimerspec *)NULL) .RS .C == -1) { .RE .RS .C perror("timer_create"); .C exit(1); .RE .C } .C " " .C pause(); .C if (timer_delete(timerid) == -1) { .RS .C perror("timer_delete"); .C exit(1); .RE .C } .C return 0; .RE .C } .RE .PD .fi .SH AUTHOR .CR timer_create() , .CR timer_delete() , .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .SH SEE ALSO clocks(2), getitimer(2). .SH STANDARDS CONFORMANCE .CR timer_create() ": POSIX.4" .br .CR timer_delete() ": POSIX.4" .br .CR timer_getoverrun() ": POSIX.4" .br .CR timer_gettime() ": POSIX.4" .br .CR timer_settime() ": POSIX.4" .\" .\" toc@\f3timers(2)\f1:\0\0\f4timer_create()\f1, \f4timer_delete()\f1, \f4timer_settime()\f1,\n \f4timer_gettime()\f1, \f4timer_getoverrun()\f1@@@timer operations\f1 .\" toc@\f4timer_create()\f1:\0\0create timer@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_delete()\f1:\0\0delete timer@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_settime()\f1:\0\0set timer expiration@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_gettime()\f1:\0\0store timer expiration and reload value@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_getoverrun()\f1:\0\0return timer expiration count@@@\f1see \f3timers(2)\f1 .\" .\" index@\f4timer_create()\f1 \- create timer@@@\f3timers(2)\f1 .\" index@\f4timer_delete()\f1 \- delete timer@@@\f3timers(2)\f1 .\" index@\f4timer_settime()\f1 \- set timer expiration@@@\f3timers(2)\f1 .\" index@\f4timer_gettime()\f1 \- store timer expiration and reload value@@@\f3timers(2)\f1 .\" index@\f4timer_getoverrun()\f1 \- return timer expiration count@@@\f3timers(2)\f1 .\" index@\f1timer operations@@@\f3timers(2)\f1 .\" index@\f1operations, timer@@@\f3timers(2)\f1 .\"" .\" links@timers.2 timer_create.2 .\" links@timers.2 timer_delete.2 .\" links@timers.2 timer_settime.2 .\" links@timers.2 timer_gettime.2 .\" links@timers.2 timer_getoverrun.2 .\" $Header: timers.2,v 78.1 95/12/20 11:20:29 ssa Exp $ .TA t .TH timers 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME timer_create(), timer_delete(), timer_settime(), timer_gettime(), timer_getoverrun() \- timer operations .SH SYNOPSIS .C "#include " .PP .nf .C "int timer_create(" .PD 0 .IP .C "clockid_t clock_id," .C "struct sigevent *evp," .C "timer_t *timerid" .PP .C ");" .PD .C "int timer_delete(" .PD 0 .IP .C "timer_t timerid" .PP .C ");" .PD .C "int timer_settime(" .PD 0 .IP .C "timer_t timerid," .C "int flags," .C "const struct itimerspec *value," .C "struct itimerspec *ovalue" .PP .C ");" .PD .C "int timer_gettime(" .PD 0 .IP .C "timer_t timerid," .C "struct itimerspec *value" .PP .C ");" .PD .C "int timer_getoverrun(" .PD 0 .IP .C "timer_t timerid" .PP .C ");" .PD .SH DESCRIPTION .SS timer_create() The .CR timer_create() function creates a per-process timer using the specified clock, .CR clock_id , as the timing base. The .CR timer_create() function returns, in the location referenced by .CR timerid , a timer .SM ID of type .CR timer_t used to identify the timer in timer requests. This timer ID will be unique within the calling process until the timer is deleted. The particular clock, .CR clock_id , is defined in .CR . The timer whose .SM ID is returned will be in a disarmed state upon return from .CR timer_create() . .PP The .CR evp argument, if non-\c .SM NULL, points to a .I sigevent structure. If the .I sigev_notify member of .CR evp is SIGEV_SIGNAL, then the structure should also specify the signal number to be sent to the process on timer expiration. The signal to be sent is specified in the .I sigev_signo field of .CR evp . If the .I sigev_notify member of .I evp is SIGEV_NONE, no notification is sent. If .CR evp is .SM NULL, then a default signal is sent to the process. The defaults for the clocks .CR CLOCK_REALTIME , .CR CLOCK_VIRTUAL , and .CR CLOCK_PROFILE are .CR SIGALRM , .CR SIGVTALRM , and .CR SIGPROF . .PP Per-process timers are not inherited by a child process across a .CR fork() and are disarmed and deleted by an .CR exec() . .SS timer_delete() .PP The .CR timer_delete() function deletes the specified timer, .CR timerid , previously created by the .CR timer_create() function. If the timer is armed when .CR timer_delete() is called, the behavior is as if the timer is automatically disarmed before removal. Any pending notifications from the timer remain. .SS timer_settime() .PP The .CR timer_settime() function sets the time until the next expiration of the timer specified by .CR timerid from the .CR it_value member of the .CR value argument and arms the timer if the .CR it_value member of .CR value is non-zero. If the specified timer was already armed when .CR timer_settime() is called, this call resets the time until next expiration to the .CR value specified. If the .CR it_value member of .CR value is zero, the timer is disarmed. Any pending notifications from the timer remain. .PP If the flag .CR TIMER_ABSTIME is not set in the argument .CR flags , .CR timer_settime() behaves as if the time until next expiration is set equal to the interval specified by the .CR it_value member of .CR value . That is, the timer will expire in .CR it_value nanoseconds from when the call is made. .PP If the flag .CR TIMER_ABSTIME is set in the argument .CR flags , .CR timer_settime() behaves as if the time until next expiration is set equal to the difference between the absolute time specified by the .CR it_value member of .CR value and the current value of the clock associated with .CR timerid . That is, the timer will expire when the clock reaches the value specified by the .CR it_value member of .CR value . If the specified time has already passed, the function will succeed and the expiration notification is made. .PP The reload value of the timer is set to the value specified by the .CR it_interval member of .CR value . When a timer is armed with a non-zero .CR it_interval , a periodic (or repetitive) timer is specified. .PP Time values that are between two consecutive non-negative integer multiples of the resolution of the specified timer are rounded up to the larger multiple of the resolution. A quantization error will not cause the timer to expire earlier than the rounded-up time value. .PP If the argument .CR ovalue is not .SM NULL, the function .CR timer_settime() stores, in the location referenced by .CR ovalue , a value representing the previous amount of time before the timer would have expired or zero if the timer was disarmed, together with the previous timer reload value. The members of .CR ovalue are subject to the resolution of the timer, and are the same values that would be returned by a .CR timer_gettime() call at that point in time. .SS timer_gettime() .PP The .CR timer_gettime() function stores the amount of time until the specified timer, .CR timerid , expires and the timer's reload value into the space pointed to by the .CR value argument. The .CR it_value member of this structure will contain the amount of time before the timer expires, or zero if the timer is disarmed. This value is returned as the interval until timer expiration, even if the timer was armed with absolute time. The .CR it_interval member of .CR value will contain the reload value last set by .CR timer_settime() . .SS timer_getoverrun() .PP Only a single signal is delivered to the process for a given timer at any point in time. When a timer for which a signal is still pending expires, no signal is delivered, and a timer overrun has occurred. When a timer expiration signal is delivered to a process, the .CR timer_getoverrun() function returns the timer expiration count for the specified timer. The overrun count returned contains the number of extra timer expirations which occurred between the time the signal was generated and when it was delivered, up to but not including an implementation defined maximum of .CR DELAYTIMER_MAX . If the number of such extra expirations is greater than or equal to .CR DELAYTIMER_MAX , then the overrun count is set to .CR DELAYTIMER_MAX . The value returned by .CR timer_getoverrun() applies to the most recent expiration signal delivery for the timer. If no expiration signal has been delivered for the timer, the meaning of the overrun count returned is undefined. .SH RETURN VALUE Upon successful completion, .CR timer_create() returns zero and updates the location referenced by .CR timerid to a .CR timer_t which can be passed to the per-process timer calls. Otherwise, .CR timer_create() returns \(mi1 and sets .CR errno to indicate the error. The value of .CR timerid is undefined if an error occurs. .PP Upon successful completion, .CR timer_delete() returns zero. Otherwise, .CR timer_delete() returns \(mi1 and sets .CR errno to indicate the error. .PP Upon successful completion, .CR timer_settime() returns zero and updates the location referenced by .CR ovalue , if .CR ovalue is non-\c .SM NULL. .PP Upon successful completion, .CR timer_gettime() returns zero and updates the location referenced by .CR value , if .CR ovalue is non-\c .SM NULL. Otherwise, .CR timer_gettime() returns \(mi1 and sets .CR errno to indicate the error. .PP Upon successful completion, .CR timer_getoverrun() returns the timer expiration overrun count as explained above. Otherwise, .CR timer_getoverrun() returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS If any of the following conditions occur, the .CR timer_create() function returns \(mi1 and sets .CR errno (see .IR errno (2)) to the corresponding value: .RS .TP 12 .SM [EAGAIN] The system lacks sufficient signal queuing resources to honor the request. .TP .SM [EAGAIN] The calling process has already created all of the timers it is allowed by this implementation. .TP .SM [EINVAL] The specified clock .SM ID is not defined. .TP .SM [EFAULT] The .CR timerid or .CR evp argument points to an invalid address. .TP .SM [ENOSYS] The function .CR timer_create() is not supported by this implementation. .RE .PP If any of the following conditions occur, the .CR timer_delete() function returns \(mi1 and sets .CR errno to the corresponding value: .RS .TP 12 .SM [EINVAL] The timer .SM ID specified by .CR timerid is not a valid timer .SM ID. .TP .SM [ENOSYS] The function .CR timer_delete() is not supported by this implementation. .RE .PP If any of the following conditions occur, the .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() functions return \(mi1 and set .CR errno to the corresponding value: .RS .TP 12 .SM [EINVAL] The .CR timerid argument does not correspond to an .SM ID returned by .CR timer_create() , but not yet deleted by .CR timer_delete() . .TP .SM [EINVAL] The .I value structure passed to .CR timer_settime() specified a nanosecond value less than zero or greater than or equal to 1000 million. .TP .SM [EFAULT] The .CR value or .CR ovalue argument points to an invalid address. .TP .SM [ENOSYS] The .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() functions are not supported by this implementation. .RE .SH EXAMPLES Create a timer, set it to go off in one minute, and deliver a .CR SIGUSR1 signal: .PD 0 .nf .RS .C #include .C #include .C timer_t timerid; .C "struct itimerspec one_minute = { {60, 0}, {0, 0} }"; .C void handler() .C { .RS .C int overrun = timer_getoverrun(timerid); .C " " .C if (overrun == -1) { .RS .C perror("handler: timer_getoverrun()"); .C exit(1); .RE .C } .C (void)printf("Timer expired, overrun count was %d, 0 expected.\en", .RS .RS .C overrun); .RE .RE .RE .C } .C int main() .C { .RS .C struct sigaction sigact; .C struct sigevent sigev; .C " " .C sigact.sa_handler = handler; .C sigemptyset(sigact.sa_mask); .C sigact.sa_flags = 0; .C " " .C if (sigaction(SIGUSR1, &sigact, (struct sigaction *)NULL) .RS .C == -1) { .RE .RS .C perror("sigaction"); .C exit(1); .RE .C } .C " " .C sigev.sigev_notify = SIGEV_SIGNAL; .C sigev.sigev_signo = SIGUSR1; .C " " .C if (timer_create(CLOCK_REALTIME, &sigev, &timerid) .RS .C == -1) { .RE .RS .C perror("timer_create"); .C exit(1); .RE .C } .C " " .C if (timer_settime(timerid, 0, &one_minute, (struct itimerspec *)NULL) .RS .C == -1) { .RE .RS .C perror("timer_create"); .C exit(1); .RE .C } .C " " .C pause(); .C if (timer_delete(timerid) == -1) { .RS .C perror("timer_delete"); .C exit(1); .RE .C } .C return 0; .RE .C } .RE .PD .fi .SH AUTHOR .CR timer_create() , .CR timer_delete() , .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .SH SEE ALSO clocks(2), getitimer(2). .SH STANDARDS CONFORMANCE .CR timer_create() ": POSIX.4" .br .CR timer_delete() ": POSIX.4" .br .CR timer_getoverrun() ": POSIX.4" .br .CR timer_gettime() ": POSIX.4" .br .CR timer_settime() ": POSIX.4" .\" .\" toc@\f3timers(2)\f1:\0\0\f4timer_create()\f1, \f4timer_delete()\f1, \f4timer_settime()\f1,\n \f4timer_gettime()\f1, \f4timer_getoverrun()\f1@@@timer operations\f1 .\" toc@\f4timer_create()\f1:\0\0create timer@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_delete()\f1:\0\0delete timer@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_settime()\f1:\0\0set timer expiration@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_gettime()\f1:\0\0store timer expiration and reload value@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_getoverrun()\f1:\0\0return timer expiration count@@@\f1see \f3timers(2)\f1 .\" .\" index@\f4timer_create()\f1 \- create timer@@@\f3timers(2)\f1 .\" index@\f4timer_delete()\f1 \- delete timer@@@\f3timers(2)\f1 .\" index@\f4timer_settime()\f1 \- set timer expiration@@@\f3timers(2)\f1 .\" index@\f4timer_gettime()\f1 \- store timer expiration and reload value@@@\f3timers(2)\f1 .\" index@\f4timer_getoverrun()\f1 \- return timer expiration count@@@\f3timers(2)\f1 .\" index@\f1timer operations@@@\f3timers(2)\f1 .\" index@\f1operations, timer@@@\f3timers(2)\f1 .\"" .\" links@timers.2 timer_create.2 .\" links@timers.2 timer_delete.2 .\" links@timers.2 timer_settime.2 .\" links@timers.2 timer_gettime.2 .\" links@timers.2 timer_getoverrun.2 .\" $Header: timers.2,v 78.1 95/12/20 11:20:29 ssa Exp $ .TA t .TH timers 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME timer_create(), timer_delete(), timer_settime(), timer_gettime(), timer_getoverrun() \- timer operations .SH SYNOPSIS .C "#include " .PP .nf .C "int timer_create(" .PD 0 .IP .C "clockid_t clock_id," .C "struct sigevent *evp," .C "timer_t *timerid" .PP .C ");" .PD .C "int timer_delete(" .PD 0 .IP .C "timer_t timerid" .PP .C ");" .PD .C "int timer_settime(" .PD 0 .IP .C "timer_t timerid," .C "int flags," .C "const struct itimerspec *value," .C "struct itimerspec *ovalue" .PP .C ");" .PD .C "int timer_gettime(" .PD 0 .IP .C "timer_t timerid," .C "struct itimerspec *value" .PP .C ");" .PD .C "int timer_getoverrun(" .PD 0 .IP .C "timer_t timerid" .PP .C ");" .PD .SH DESCRIPTION .SS timer_create() The .CR timer_create() function creates a per-process timer using the specified clock, .CR clock_id , as the timing base. The .CR timer_create() function returns, in the location referenced by .CR timerid , a timer .SM ID of type .CR timer_t used to identify the timer in timer requests. This timer ID will be unique within the calling process until the timer is deleted. The particular clock, .CR clock_id , is defined in .CR . The timer whose .SM ID is returned will be in a disarmed state upon return from .CR timer_create() . .PP The .CR evp argument, if non-\c .SM NULL, points to a .I sigevent structure. If the .I sigev_notify member of .CR evp is SIGEV_SIGNAL, then the structure should also specify the signal number to be sent to the process on timer expiration. The signal to be sent is specified in the .I sigev_signo field of .CR evp . If the .I sigev_notify member of .I evp is SIGEV_NONE, no notification is sent. If .CR evp is .SM NULL, then a default signal is sent to the process. The defaults for the clocks .CR CLOCK_REALTIME , .CR CLOCK_VIRTUAL , and .CR CLOCK_PROFILE are .CR SIGALRM , .CR SIGVTALRM , and .CR SIGPROF . .PP Per-process timers are not inherited by a child process across a .CR fork() and are disarmed and deleted by an .CR exec() . .SS timer_delete() .PP The .CR timer_delete() function deletes the specified timer, .CR timerid , previously created by the .CR timer_create() function. If the timer is armed when .CR timer_delete() is called, the behavior is as if the timer is automatically disarmed before removal. Any pending notifications from the timer remain. .SS timer_settime() .PP The .CR timer_settime() function sets the time until the next expiration of the timer specified by .CR timerid from the .CR it_value member of the .CR value argument and arms the timer if the .CR it_value member of .CR value is non-zero. If the specified timer was already armed when .CR timer_settime() is called, this call resets the time until next expiration to the .CR value specified. If the .CR it_value member of .CR value is zero, the timer is disarmed. Any pending notifications from the timer remain. .PP If the flag .CR TIMER_ABSTIME is not set in the argument .CR flags , .CR timer_settime() behaves as if the time until next expiration is set equal to the interval specified by the .CR it_value member of .CR value . That is, the timer will expire in .CR it_value nanoseconds from when the call is made. .PP If the flag .CR TIMER_ABSTIME is set in the argument .CR flags , .CR timer_settime() behaves as if the time until next expiration is set equal to the difference between the absolute time specified by the .CR it_value member of .CR value and the current value of the clock associated with .CR timerid . That is, the timer will expire when the clock reaches the value specified by the .CR it_value member of .CR value . If the specified time has already passed, the function will succeed and the expiration notification is made. .PP The reload value of the timer is set to the value specified by the .CR it_interval member of .CR value . When a timer is armed with a non-zero .CR it_interval , a periodic (or repetitive) timer is specified. .PP Time values that are between two consecutive non-negative integer multiples of the resolution of the specified timer are rounded up to the larger multiple of the resolution. A quantization error will not cause the timer to expire earlier than the rounded-up time value. .PP If the argument .CR ovalue is not .SM NULL, the function .CR timer_settime() stores, in the location referenced by .CR ovalue , a value representing the previous amount of time before the timer would have expired or zero if the timer was disarmed, together with the previous timer reload value. The members of .CR ovalue are subject to the resolution of the timer, and are the same values that would be returned by a .CR timer_gettime() call at that point in time. .SS timer_gettime() .PP The .CR timer_gettime() function stores the amount of time until the specified timer, .CR timerid , expires and the timer's reload value into the space pointed to by the .CR value argument. The .CR it_value member of this structure will contain the amount of time before the timer expires, or zero if the timer is disarmed. This value is returned as the interval until timer expiration, even if the timer was armed with absolute time. The .CR it_interval member of .CR value will contain the reload value last set by .CR timer_settime() . .SS timer_getoverrun() .PP Only a single signal is delivered to the process for a given timer at any point in time. When a timer for which a signal is still pending expires, no signal is delivered, and a timer overrun has occurred. When a timer expiration signal is delivered to a process, the .CR timer_getoverrun() function returns the timer expiration count for the specified timer. The overrun count returned contains the number of extra timer expirations which occurred between the time the signal was generated and when it was delivered, up to but not including an implementation defined maximum of .CR DELAYTIMER_MAX . If the number of such extra expirations is greater than or equal to .CR DELAYTIMER_MAX , then the overrun count is set to .CR DELAYTIMER_MAX . The value returned by .CR timer_getoverrun() applies to the most recent expiration signal delivery for the timer. If no expiration signal has been delivered for the timer, the meaning of the overrun count returned is undefined. .SH RETURN VALUE Upon successful completion, .CR timer_create() returns zero and updates the location referenced by .CR timerid to a .CR timer_t which can be passed to the per-process timer calls. Otherwise, .CR timer_create() returns \(mi1 and sets .CR errno to indicate the error. The value of .CR timerid is undefined if an error occurs. .PP Upon successful completion, .CR timer_delete() returns zero. Otherwise, .CR timer_delete() returns \(mi1 and sets .CR errno to indicate the error. .PP Upon successful completion, .CR timer_settime() returns zero and updates the location referenced by .CR ovalue , if .CR ovalue is non-\c .SM NULL. .PP Upon successful completion, .CR timer_gettime() returns zero and updates the location referenced by .CR value , if .CR ovalue is non-\c .SM NULL. Otherwise, .CR timer_gettime() returns \(mi1 and sets .CR errno to indicate the error. .PP Upon successful completion, .CR timer_getoverrun() returns the timer expiration overrun count as explained above. Otherwise, .CR timer_getoverrun() returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS If any of the following conditions occur, the .CR timer_create() function returns \(mi1 and sets .CR errno (see .IR errno (2)) to the corresponding value: .RS .TP 12 .SM [EAGAIN] The system lacks sufficient signal queuing resources to honor the request. .TP .SM [EAGAIN] The calling process has already created all of the timers it is allowed by this implementation. .TP .SM [EINVAL] The specified clock .SM ID is not defined. .TP .SM [EFAULT] The .CR timerid or .CR evp argument points to an invalid address. .TP .SM [ENOSYS] The function .CR timer_create() is not supported by this implementation. .RE .PP If any of the following conditions occur, the .CR timer_delete() function returns \(mi1 and sets .CR errno to the corresponding value: .RS .TP 12 .SM [EINVAL] The timer .SM ID specified by .CR timerid is not a valid timer .SM ID. .TP .SM [ENOSYS] The function .CR timer_delete() is not supported by this implementation. .RE .PP If any of the following conditions occur, the .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() functions return \(mi1 and set .CR errno to the corresponding value: .RS .TP 12 .SM [EINVAL] The .CR timerid argument does not correspond to an .SM ID returned by .CR timer_create() , but not yet deleted by .CR timer_delete() . .TP .SM [EINVAL] The .I value structure passed to .CR timer_settime() specified a nanosecond value less than zero or greater than or equal to 1000 million. .TP .SM [EFAULT] The .CR value or .CR ovalue argument points to an invalid address. .TP .SM [ENOSYS] The .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() functions are not supported by this implementation. .RE .SH EXAMPLES Create a timer, set it to go off in one minute, and deliver a .CR SIGUSR1 signal: .PD 0 .nf .RS .C #include .C #include .C timer_t timerid; .C "struct itimerspec one_minute = { {60, 0}, {0, 0} }"; .C void handler() .C { .RS .C int overrun = timer_getoverrun(timerid); .C " " .C if (overrun == -1) { .RS .C perror("handler: timer_getoverrun()"); .C exit(1); .RE .C } .C (void)printf("Timer expired, overrun count was %d, 0 expected.\en", .RS .RS .C overrun); .RE .RE .RE .C } .C int main() .C { .RS .C struct sigaction sigact; .C struct sigevent sigev; .C " " .C sigact.sa_handler = handler; .C sigemptyset(sigact.sa_mask); .C sigact.sa_flags = 0; .C " " .C if (sigaction(SIGUSR1, &sigact, (struct sigaction *)NULL) .RS .C == -1) { .RE .RS .C perror("sigaction"); .C exit(1); .RE .C } .C " " .C sigev.sigev_notify = SIGEV_SIGNAL; .C sigev.sigev_signo = SIGUSR1; .C " " .C if (timer_create(CLOCK_REALTIME, &sigev, &timerid) .RS .C == -1) { .RE .RS .C perror("timer_create"); .C exit(1); .RE .C } .C " " .C if (timer_settime(timerid, 0, &one_minute, (struct itimerspec *)NULL) .RS .C == -1) { .RE .RS .C perror("timer_create"); .C exit(1); .RE .C } .C " " .C pause(); .C if (timer_delete(timerid) == -1) { .RS .C perror("timer_delete"); .C exit(1); .RE .C } .C return 0; .RE .C } .RE .PD .fi .SH AUTHOR .CR timer_create() , .CR timer_delete() , .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .SH SEE ALSO clocks(2), getitimer(2). .SH STANDARDS CONFORMANCE .CR timer_create() ": POSIX.4" .br .CR timer_delete() ": POSIX.4" .br .CR timer_getoverrun() ": POSIX.4" .br .CR timer_gettime() ": POSIX.4" .br .CR timer_settime() ": POSIX.4" .\" .\" toc@\f3timers(2)\f1:\0\0\f4timer_create()\f1, \f4timer_delete()\f1, \f4timer_settime()\f1,\n \f4timer_gettime()\f1, \f4timer_getoverrun()\f1@@@timer operations\f1 .\" toc@\f4timer_create()\f1:\0\0create timer@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_delete()\f1:\0\0delete timer@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_settime()\f1:\0\0set timer expiration@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_gettime()\f1:\0\0store timer expiration and reload value@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_getoverrun()\f1:\0\0return timer expiration count@@@\f1see \f3timers(2)\f1 .\" .\" index@\f4timer_create()\f1 \- create timer@@@\f3timers(2)\f1 .\" index@\f4timer_delete()\f1 \- delete timer@@@\f3timers(2)\f1 .\" index@\f4timer_settime()\f1 \- set timer expiration@@@\f3timers(2)\f1 .\" index@\f4timer_gettime()\f1 \- store timer expiration and reload value@@@\f3timers(2)\f1 .\" index@\f4timer_getoverrun()\f1 \- return timer expiration count@@@\f3timers(2)\f1 .\" index@\f1timer operations@@@\f3timers(2)\f1 .\" index@\f1operations, timer@@@\f3timers(2)\f1 .\"" .\" links@timers.2 timer_create.2 .\" links@timers.2 timer_delete.2 .\" links@timers.2 timer_settime.2 .\" links@timers.2 timer_gettime.2 .\" links@timers.2 timer_getoverrun.2 .\" $Header: timers.2,v 78.1 95/12/20 11:20:29 ssa Exp $ .TA t .TH timers 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME timer_create(), timer_delete(), timer_settime(), timer_gettime(), timer_getoverrun() \- timer operations .SH SYNOPSIS .C "#include " .PP .nf .C "int timer_create(" .PD 0 .IP .C "clockid_t clock_id," .C "struct sigevent *evp," .C "timer_t *timerid" .PP .C ");" .PD .C "int timer_delete(" .PD 0 .IP .C "timer_t timerid" .PP .C ");" .PD .C "int timer_settime(" .PD 0 .IP .C "timer_t timerid," .C "int flags," .C "const struct itimerspec *value," .C "struct itimerspec *ovalue" .PP .C ");" .PD .C "int timer_gettime(" .PD 0 .IP .C "timer_t timerid," .C "struct itimerspec *value" .PP .C ");" .PD .C "int timer_getoverrun(" .PD 0 .IP .C "timer_t timerid" .PP .C ");" .PD .SH DESCRIPTION .SS timer_create() The .CR timer_create() function creates a per-process timer using the specified clock, .CR clock_id , as the timing base. The .CR timer_create() function returns, in the location referenced by .CR timerid , a timer .SM ID of type .CR timer_t used to identify the timer in timer requests. This timer ID will be unique within the calling process until the timer is deleted. The particular clock, .CR clock_id , is defined in .CR . The timer whose .SM ID is returned will be in a disarmed state upon return from .CR timer_create() . .PP The .CR evp argument, if non-\c .SM NULL, points to a .I sigevent structure. If the .I sigev_notify member of .CR evp is SIGEV_SIGNAL, then the structure should also specify the signal number to be sent to the process on timer expiration. The signal to be sent is specified in the .I sigev_signo field of .CR evp . If the .I sigev_notify member of .I evp is SIGEV_NONE, no notification is sent. If .CR evp is .SM NULL, then a default signal is sent to the process. The defaults for the clocks .CR CLOCK_REALTIME , .CR CLOCK_VIRTUAL , and .CR CLOCK_PROFILE are .CR SIGALRM , .CR SIGVTALRM , and .CR SIGPROF . .PP Per-process timers are not inherited by a child process across a .CR fork() and are disarmed and deleted by an .CR exec() . .SS timer_delete() .PP The .CR timer_delete() function deletes the specified timer, .CR timerid , previously created by the .CR timer_create() function. If the timer is armed when .CR timer_delete() is called, the behavior is as if the timer is automatically disarmed before removal. Any pending notifications from the timer remain. .SS timer_settime() .PP The .CR timer_settime() function sets the time until the next expiration of the timer specified by .CR timerid from the .CR it_value member of the .CR value argument and arms the timer if the .CR it_value member of .CR value is non-zero. If the specified timer was already armed when .CR timer_settime() is called, this call resets the time until next expiration to the .CR value specified. If the .CR it_value member of .CR value is zero, the timer is disarmed. Any pending notifications from the timer remain. .PP If the flag .CR TIMER_ABSTIME is not set in the argument .CR flags , .CR timer_settime() behaves as if the time until next expiration is set equal to the interval specified by the .CR it_value member of .CR value . That is, the timer will expire in .CR it_value nanoseconds from when the call is made. .PP If the flag .CR TIMER_ABSTIME is set in the argument .CR flags , .CR timer_settime() behaves as if the time until next expiration is set equal to the difference between the absolute time specified by the .CR it_value member of .CR value and the current value of the clock associated with .CR timerid . That is, the timer will expire when the clock reaches the value specified by the .CR it_value member of .CR value . If the specified time has already passed, the function will succeed and the expiration notification is made. .PP The reload value of the timer is set to the value specified by the .CR it_interval member of .CR value . When a timer is armed with a non-zero .CR it_interval , a periodic (or repetitive) timer is specified. .PP Time values that are between two consecutive non-negative integer multiples of the resolution of the specified timer are rounded up to the larger multiple of the resolution. A quantization error will not cause the timer to expire earlier than the rounded-up time value. .PP If the argument .CR ovalue is not .SM NULL, the function .CR timer_settime() stores, in the location referenced by .CR ovalue , a value representing the previous amount of time before the timer would have expired or zero if the timer was disarmed, together with the previous timer reload value. The members of .CR ovalue are subject to the resolution of the timer, and are the same values that would be returned by a .CR timer_gettime() call at that point in time. .SS timer_gettime() .PP The .CR timer_gettime() function stores the amount of time until the specified timer, .CR timerid , expires and the timer's reload value into the space pointed to by the .CR value argument. The .CR it_value member of this structure will contain the amount of time before the timer expires, or zero if the timer is disarmed. This value is returned as the interval until timer expiration, even if the timer was armed with absolute time. The .CR it_interval member of .CR value will contain the reload value last set by .CR timer_settime() . .SS timer_getoverrun() .PP Only a single signal is delivered to the process for a given timer at any point in time. When a timer for which a signal is still pending expires, no signal is delivered, and a timer overrun has occurred. When a timer expiration signal is delivered to a process, the .CR timer_getoverrun() function returns the timer expiration count for the specified timer. The overrun count returned contains the number of extra timer expirations which occurred between the time the signal was generated and when it was delivered, up to but not including an implementation defined maximum of .CR DELAYTIMER_MAX . If the number of such extra expirations is greater than or equal to .CR DELAYTIMER_MAX , then the overrun count is set to .CR DELAYTIMER_MAX . The value returned by .CR timer_getoverrun() applies to the most recent expiration signal delivery for the timer. If no expiration signal has been delivered for the timer, the meaning of the overrun count returned is undefined. .SH RETURN VALUE Upon successful completion, .CR timer_create() returns zero and updates the location referenced by .CR timerid to a .CR timer_t which can be passed to the per-process timer calls. Otherwise, .CR timer_create() returns \(mi1 and sets .CR errno to indicate the error. The value of .CR timerid is undefined if an error occurs. .PP Upon successful completion, .CR timer_delete() returns zero. Otherwise, .CR timer_delete() returns \(mi1 and sets .CR errno to indicate the error. .PP Upon successful completion, .CR timer_settime() returns zero and updates the location referenced by .CR ovalue , if .CR ovalue is non-\c .SM NULL. .PP Upon successful completion, .CR timer_gettime() returns zero and updates the location referenced by .CR value , if .CR ovalue is non-\c .SM NULL. Otherwise, .CR timer_gettime() returns \(mi1 and sets .CR errno to indicate the error. .PP Upon successful completion, .CR timer_getoverrun() returns the timer expiration overrun count as explained above. Otherwise, .CR timer_getoverrun() returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS If any of the following conditions occur, the .CR timer_create() function returns \(mi1 and sets .CR errno (see .IR errno (2)) to the corresponding value: .RS .TP 12 .SM [EAGAIN] The system lacks sufficient signal queuing resources to honor the request. .TP .SM [EAGAIN] The calling process has already created all of the timers it is allowed by this implementation. .TP .SM [EINVAL] The specified clock .SM ID is not defined. .TP .SM [EFAULT] The .CR timerid or .CR evp argument points to an invalid address. .TP .SM [ENOSYS] The function .CR timer_create() is not supported by this implementation. .RE .PP If any of the following conditions occur, the .CR timer_delete() function returns \(mi1 and sets .CR errno to the corresponding value: .RS .TP 12 .SM [EINVAL] The timer .SM ID specified by .CR timerid is not a valid timer .SM ID. .TP .SM [ENOSYS] The function .CR timer_delete() is not supported by this implementation. .RE .PP If any of the following conditions occur, the .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() functions return \(mi1 and set .CR errno to the corresponding value: .RS .TP 12 .SM [EINVAL] The .CR timerid argument does not correspond to an .SM ID returned by .CR timer_create() , but not yet deleted by .CR timer_delete() . .TP .SM [EINVAL] The .I value structure passed to .CR timer_settime() specified a nanosecond value less than zero or greater than or equal to 1000 million. .TP .SM [EFAULT] The .CR value or .CR ovalue argument points to an invalid address. .TP .SM [ENOSYS] The .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() functions are not supported by this implementation. .RE .SH EXAMPLES Create a timer, set it to go off in one minute, and deliver a .CR SIGUSR1 signal: .PD 0 .nf .RS .C #include .C #include .C timer_t timerid; .C "struct itimerspec one_minute = { {60, 0}, {0, 0} }"; .C void handler() .C { .RS .C int overrun = timer_getoverrun(timerid); .C " " .C if (overrun == -1) { .RS .C perror("handler: timer_getoverrun()"); .C exit(1); .RE .C } .C (void)printf("Timer expired, overrun count was %d, 0 expected.\en", .RS .RS .C overrun); .RE .RE .RE .C } .C int main() .C { .RS .C struct sigaction sigact; .C struct sigevent sigev; .C " " .C sigact.sa_handler = handler; .C sigemptyset(sigact.sa_mask); .C sigact.sa_flags = 0; .C " " .C if (sigaction(SIGUSR1, &sigact, (struct sigaction *)NULL) .RS .C == -1) { .RE .RS .C perror("sigaction"); .C exit(1); .RE .C } .C " " .C sigev.sigev_notify = SIGEV_SIGNAL; .C sigev.sigev_signo = SIGUSR1; .C " " .C if (timer_create(CLOCK_REALTIME, &sigev, &timerid) .RS .C == -1) { .RE .RS .C perror("timer_create"); .C exit(1); .RE .C } .C " " .C if (timer_settime(timerid, 0, &one_minute, (struct itimerspec *)NULL) .RS .C == -1) { .RE .RS .C perror("timer_create"); .C exit(1); .RE .C } .C " " .C pause(); .C if (timer_delete(timerid) == -1) { .RS .C perror("timer_delete"); .C exit(1); .RE .C } .C return 0; .RE .C } .RE .PD .fi .SH AUTHOR .CR timer_create() , .CR timer_delete() , .CR timer_settime() , .CR timer_gettime() , and .CR timer_getoverrun() were derived from the proposed IEEE POSIX P1003.4 standard, draft 14. .SH SEE ALSO clocks(2), getitimer(2). .SH STANDARDS CONFORMANCE .CR timer_create() ": POSIX.4" .br .CR timer_delete() ": POSIX.4" .br .CR timer_getoverrun() ": POSIX.4" .br .CR timer_gettime() ": POSIX.4" .br .CR timer_settime() ": POSIX.4" .\" .\" toc@\f3timers(2)\f1:\0\0\f4timer_create()\f1, \f4timer_delete()\f1, \f4timer_settime()\f1,\n \f4timer_gettime()\f1, \f4timer_getoverrun()\f1@@@timer operations\f1 .\" toc@\f4timer_create()\f1:\0\0create timer@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_delete()\f1:\0\0delete timer@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_settime()\f1:\0\0set timer expiration@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_gettime()\f1:\0\0store timer expiration and reload value@@@\f1see \f3timers(2)\f1 .\" toc@\f4timer_getoverrun()\f1:\0\0return timer expiration count@@@\f1see \f3timers(2)\f1 .\" .\" index@\f4timer_create()\f1 \- create timer@@@\f3timers(2)\f1 .\" index@\f4timer_delete()\f1 \- delete timer@@@\f3timers(2)\f1 .\" index@\f4timer_settime()\f1 \- set timer expiration@@@\f3timers(2)\f1 .\" index@\f4timer_gettime()\f1 \- store timer expiration and reload value@@@\f3timers(2)\f1 .\" index@\f4timer_getoverrun()\f1 \- return timer expiration count@@@\f3timers(2)\f1 .\" index@\f1timer operations@@@\f3timers(2)\f1 .\" index@\f1operations, timer@@@\f3timers(2)\f1 .\"" .\" links@timers.2 timer_create.2 .\" links@timers.2 timer_delete.2 .\" links@timers.2 timer_settime.2 .\" links@timers.2 timer_gettime.2 .\" links@timers.2 timer_getoverrun.2 .\" $Header: times.2,v 78.1 96/01/19 20:39:36 ssa Exp $ .TA t .TH times 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME times \- get process and child process times .SH SYNOPSIS .C "#include " .PP .C "clock_t times(struct tms *buffer);" .SH DESCRIPTION .C times() fills the structure pointed to by .I buffer with time-accounting information. The structure defined in .RC < sys/times.h > is as follows: .nf .IP .C "struct tms {" .C " clock_t tms_utime; /* user time */" .C " clock_t tms_stime; /* system time */"" .C " clock_t tms_cutime; /* user time, children */" .C " clock_t tms_cstime; /* system time, children */" .C "};" .fi .PP This information comes from the calling process and each of its terminated child processes for which it has executed a .CR wait() , .CR wait3() , or .CR waitpid() . The times are in units of 1\|/\|\c .C CLK_TCK seconds, where .C CLK_TCK is processor dependent The value of .C CLK_TCK can be queried using the .C sysconf() function (see .IR sysconf (2)). .PP .C tms_utime is the .SM CPU time used while executing instructions in the user space of the calling process. .PP .C tms_stime is the .SM CPU time used by the system on behalf of the calling process. .PP .C tms_cutime is the sum of the .CR tms_utime s and .CR tms_cutime s of the child processes. .PP .C tms_cstime is the sum of the .CR tms_stime s and .CR tms_cstime s of the child processes. .SH RETURN VALUE Upon successful completion, .C times() returns the elapsed real time, in units of1\|/\|\c .C CLK_TCK of a second, since an arbitrary point in the past (such as system start-up time). This point does not change from one invocation of .C times() to another. If .C times() fails, \(mi1 is returned and .C errno is set to indicate the error. .SS Remarks .C times() has a granularity of one tick. Processes which run less than one tick may not register any value. .SH ERRORS .TP 15 .SM [EFAULT] .C times() fails if .I buffer points to an illegal address. The reliable detection of this error is implementation dependent. .SH SEE ALSO time(1), gettimeofday(2), exec(2), fork(2), sysconf(2), time(2), wait(2). .SH WARNINGS Not all .SM CPU time expended by system processes on behalf of a user process is counted in the system .SM CPU time for that process. .SH STANDARDS CONFORMANCE .CR times() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4times()\fP \(mi get process and child process times@@@\f3times(2)\f1 .\" index@get: process and child process times@@@\f3times(2)\f1 .\" index@process and child process times, get@@@\f3times(2)\f1 .\" index@child process and process times, get@@@\f3times(2)\f1 .\" index@times, get process and child process@@@\f3times(2)\f1 .\" .\" toc@\f3times(2)\f1:\0\0\f4times()\fP@@@get process and child process times .\" $Header: truncate.2,v 78.1 96/02/12 14:20:55 ssa Exp $ .TA t .TH truncate 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ftruncate, truncate \- truncate a file to a specified length .SH SYNOPSIS .\" UX .C "#include " .PP .C "int ftruncate(int fildes, off_t length);" .PP .C "int truncate(const char *path, off_t length);" .\" ? .SH DESCRIPTION The .CR ftruncate() function causes the regular file referenced by .IR fildes to have a size of .IR length bytes. .PP The .CR truncate() function causes the regular file named by .IR path to have a size of .IR length bytes. .PP The effect of .CR ftruncate() and .CR truncate() on other types of files is unspecified. If the file previously was larger than .IR length , the extra data is lost. If it was previously shorter than .IR length, bytes between the old and new lengths are read as zeroes. With .CR ftruncate() , the file must be open for writing; for .CR truncate() , the process must have write permission for the file. .PP If the request would cause the file size to exceed the soft file size limit for the process, the request will fail and the implementation will generate the .CR SIGXFSZ signal for the process. .PP These functions do not modify the file offset for any open file descriptions associated with the file. On successful completion, if the file size is changed, these functions will mark for update the .IR st_ctime and .IR st_mtime fields of the file, and if the file is a regular file, the .CR S_ISUID and .CR S_ISGID bits of the file mode may be cleared. .SH RETURN VALUE Upon successful completion, .CR ftruncate() and .CR truncate() returns 0. Otherwise a \(mi1 is returned, and .CR errno is set to indicate the error. .SH ERRORS The .CR ftruncate() and .CR truncate() functions will fail if: .RS .TP 25 [EINTR] A signal was caught during execution. .TP [EINVAL] The .IR length argument was less than 0. .TP [EFBIG] or [EINVAL] The .IR length argument was greater than the maximum file size. .TP [EIO] An I/O error occurred while reading from or writing to a file system. .RE .PP. The .CR ftruncate() function will fail if: .RS .TP 25 [EBADF] or [EINVAL] The .IR fildes argument is not a file descriptor open for writing. .TP [EINVAL] The .IR fildes argument references a file that was opened without write permission. .RE .PP The .CR truncate() function will fail if: .RS .TP 25 [EACCES] A component of the .IR path prefix denies search permission, or write permission is denied on the file. .TP [EISDIR] The named file is a directory. .TP [ELOOP] Too many symbolic links were encountered in resolving .IR path . .TP [ENAMETOOLONG] The length of the specified pathname exceeds .CR PATH_MAX bytes, or the length of a component of the pathname exceeds .CR NAME_MAX bytes. .TP [ENOENT] A component of .CR path does not name an existing file or path is an empty string. .TP [ENOTDIR] A component of the .IR path prefix of path is not a directory. .TP [EROFS] The named file resides on a read\-only file system. .RE .PP The .CR truncate() function may fail if: .RS .TP 25 [ENAMETOOLONG] Pathname resolution of a symbolic link produced an intermediate result whose length exceeds .CR {PATH_MAX} . .SH SEE ALSO open(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .TA .TH ftruncate .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH SYNOPSIS .C "int truncate(const char *path, size_t length);" .PP .C "int ftruncate(int fildes, size_t length);" .SH ERRORS If truncate() fails, .CR errno is set to one of the following values: .RS .TP 15 [EACCES] MAC access is denied on the file. .TP [EDQUOT] The user's disk quota block limit has been reached for this file system. .TP [EFAULT] .IR path points outside the process's allocated address space. The reliable detection of this error is implementation dependent. .TP [EINVAL] .IR length was greater than the maximum file size. .TP [ETXTBSY] The file is a pure procedure (shared text) file that is being executed. .RE .PP If .CR ftruncate() fails, .CR errno is set to one of the following values: .RS .TP 15 [EDQUOT] The user's disk quota block limit has been reached for this file system. .RE .SH AUTHOR .CR truncate() was developed by the University of California, Berkeley. .SH SEE ALSO ftruncate64(2), open(2), truncate64(2). .SH STANDARDS CONFORMANCE truncate(): AES ftruncate(): AES, SVID3 .\" .\" index@\f4ftruncate()\f1 \- truncate a file to a specified length@@@\f3truncate(2)\f1 .\" index@\f4truncate()\f1 \- truncate a file to a specified length@@@\f3truncate(2)\f1 .\" index@\f1file: truncate a file to a specified length@@@\f3truncate(2)\f1 .\" .\" toc@\f3truncate(2)\f1:\0\0\f4ftruncate()\f1, \f4truncate()\f1@@@truncate a file to a specified length .\" toc@\f4ftruncate()\f1:\0\0truncate a file to a specified length@@@see \f3truncate(2)\f1 .\" .\" links@truncate.2 ftruncate.2 .\" $Header: creat64.2,v 78.2 96/02/12 13:37:12 ssa Exp $ .TA c .TH creat64 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME creat64(\|), fstat64(\|), getrlimit64(\|), lockf64(\|), lseek64(\|), lstat64(\|), mmap64(\|), open64(\|), prealloc64(\|), setrlimit64(\|), stat64(\|), statvfs64(\|), truncate64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0creat64(const\0char\0*path,\0mode_t\0mode);" .PP .C "#include " .PP .C "int\0fstat64(int\0fildes,\0struct\0stat64\0*buf);" .PP .C "include\0" .PP .C "int\0getrlimit64(int resource,\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0lock64(int\0*fildes,\0int\0function,\0off64_t\0size);" .PP .C "#include " .PP .C "off64_t\0lseek64(int\0*fildes,\0off64_t\0offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0lstat64(const\0char\0*,\0struct\0stat64\0*);" .PP .C "#include " .PP .C "void\0mmap64(void\0addr,\0size_t\0len,\0int\0prot,\0int\0flags,\0int\0fildes,\0off64_t\0off);" .PP .C "#include " .PP .C "int\0open64(const\0char\0*path,\0int\0oflag,...);" .PP .C "#include " .PP .C "int\0prealloc64(int\0fildes,\0off64_t\0size);" .PP .C "include\0" .PP .C "int\0setrlimit64(int\0resource,\0const\0struct\0rlimit64\0*rlp);" .PP .C "#include " .PP .C "int\0stat64(const\0char\0*path,\0struct\0stat64\0*buf);" .PP .C "#include " .PP .C "int\0statvfs64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "int\0truncate64(const\0char\0*path,\0off64_t\0length);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 18 .C creat64() The .C creat64() function is identical to .C creat() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. .C creat64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR creat() . .TP .C fstat64() The .C fstat64() function is identical to .C fstat() except that .C fstat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C getrlimit64 The .C getrlimit64() function is identical to .C getrlimit() except that .C getrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .CR "struct rlimit" . All other functional behaviors, returns, and errors are identical. .TP .C lock64() The .C lock64() function is identical to .C lockf() except that .C lockf64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C lseek64() The .C lseek64() function is identical to .C lseek() except that .C lseek64() accepts an .CR off64_t type as the desired offset and has a return value of .CR off64_t. All other functional behaviors, returns, and errors are identical. .TP .C lstat64() The .C lstat64() function is identical to .C lstat() except that .C lstat64() returns file status in a .C struct stat64 instead of .CR "struct stat" . All other functional behaviors, returns, and errors are identical. .TP .C mmap64() The .C mmap64() function is identical to .C mmap() except that .C mmap64() accepts the file offset as an .CR off64_t . .TP .C open64() The .C open64() function is identical to .C open() in 64-bit compile environment. Both functions set .C O_LARGEFILE in the file status flag to which the returned descriptor refers. The .C open64() function is equivalent to .C open() function (in 32-bit compile environment) with .C O_LARGEFILE flag set. .C open64() function returns a file descriptor which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR open() . .TP .C prealloc64() The .C prealloc64() function is identical to .C prealloc() except that .C prealloc64() accepts the file offset as an .CR off64_t . All other functional behaviors, returns, and errors are identical to .CR prealloc() . .TP .C setrlimit64 The .C setrlimit64() function is identical to .C setrlimit() except that .C setrlimit64() passes a .C struct rlimit64 as its second parameter instead of a .C struct rlimit. All other functional behaviors, returns, and errors are identical. .TP .C stat64() The .C stat64() function is identical to .C stat() except that .C stat64() returns file status in a .C struct stat64 instead of a .CR "struct stat" . .TP .C statvfs64() Refer to .CR fstatvfs64() . .TP .C truncate64() The .C truncate64() function is identical to .C truncate() except that .C truncate64() accepts the length parameter as an .C off64_t instead of .CR off_t . All other functional behaviors, returns, and errors are identical to .CR truncate() . .\" .\" toc@\f4creat64(2)\f1:\0\0\f4fstat64\f1, \f4getrlimit64\f1, \f4lockf64\f1, \f4lseek64\f1, \f4lstat64\f1, \f4mmap64\f1, \f4open64\f1, \n\f4prealloc64\f1, \f4setrlimit64\f1, \f4stat64\f1, \f4statvfs64\f1, \f4truncate64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4creat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4fstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4getrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lockf64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lseek64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4lstat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4mmap64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4open64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4prealloc64()\f1 \- file sysmmaptem API to support large files@@@\f3creat64(2)\f1 .\" index@\f4setrlimit64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4stat64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4statvfs64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f4truncate64()\f1 \- file system API to support large files@@@\f3creat64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3creat64(2)\f1 .\" .\" links@creat64.2 fstat64.2 .\" links@creat64.2 getrlimit64.2 .\" links@creat64.2 lockf64.2 .\" links@creat64.2 lseek64.2 .\" links@creat64.2 lstat64.2 .\" links@creat64.2 mmap64.2 .\" links@creat64.2 open64.2 .\" links@creat64.2 prealloc64.2 .\" links@creat64.2 setrlimit64.2 .\" links@creat64.2 stat64.2 .\" links@creat64.2 statvfs64.2 .\" links@creat64.2 truncate64.2 .\" .\" $Header: ualarm.2,v 76.2 95/07/07 14:59:47 ssa Exp $ .TA u .TH ualarm 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ualarm \- set the interval timer .SH SYNOPSIS .\" UX .PP .C #include .PP .C useconds_t ualarm(useconds_t useconds, useconds_t interval); .\" ? .PP .SH DESCRIPTION The .CR ualarm() function causes the .CR SIGALRM signal to be generated for the calling process after the number of real\-time microseconds specified by the .IR useconds argument has elapsed. When the .IR interval argument is non\-zero, repeated timeout notification occurs with a period in microseconds specified by the .IR interval argument. If the notification signal, .CR SIGALRM , is not caught or ignored, the calling process is terminated. .PP Implementations may place limitations on the granularity of timer values. For each interval timer, if the requested timer value requires a finer granularity than the implementation supports, the actual timer value will be rounded up to the next supported value. .PP Interactions between .CR ualarm() and either .CR alarm() or .CR sleep() are unspecified. .SH RETURN VALUE The .CR ualarm() function returns the number of microseconds remaining from the previous .CR ualarm() call. If no timeouts are pending or if .CR ualarm() has not previously been called, .CR ualarm() returns 0. .SH ERRORS No errors are defined. .SH APPLICATION USAGE The .CR ualarm() function is a simplified interface to .CR setitimer() , and uses the .CR ITIMER_REAL interval timer. .SH SEE ALSO alarm(), setitimer(), sleep(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4ualarm()\f1 \- set the interval timer@@@\f3ualarm(2)\f1 .\" index@\f1set the interval timer@@@\f3ualarm(2)\f1 .\" index@\f1interval timer, set@@@\f3ualarm(2)\f1 .\" index@\f1timer, set the interval timer@@@\f3ualarm(2)\f1 .\" .\" toc@\f3ualarm(2)\f1:\0\0\f4ualarm()\f1@@@set the interval timer .\" .\" fileset_database@ualarm.2 .\" $Header: ulimit.2,v 72.6 94/11/14 15:27:12 ssa Exp $ .TA u .TH ulimit 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ulimit \- get and set user limits .SH SYNOPSIS .C "#include " .PP .C "long ulimit(int cmd, ...);" .SS Remarks The ANSI C "\c .CR ", ...\$\c" " construct denotes a variable length argument list whose optional [or required] \" EDITOR: make this line fit the specific page members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION .C ulimit() provides for control over process limits. Available values for .I cmd are: .RS .TP 20 .C UL_GETFSIZE Get the file size limit of the process. The limit is in units of 512-byte blocks and is inherited by child processes. Files of any size can be read. The optional second argument is not used. .TP .C UL_SETFSIZE Set the file size limit of the process to the value of the optional second argument which is taken as a long. Any process can decrease this limit, but only a process with an effective user ID of super-user can increase the limit. Note that the limit must be specified in units of 512-byte blocks. .TP .C UL_GETMAXBRK Get the maximum possible break value (see .IR brk (2)). Depending on system resources such as swap space, this maximum might not be attainable at a given time. The optional second argument is not used. .RE .SH ERRORS .CR ulimit() fails if one or more of the following conditions is true. .RS .TP 15 [EINVAL] .I cmd is not in the correct range. .TP [EPERM] .CR ulimit() fails and the limit is unchanged if a process with an effective user ID other than super-user attempts to increase its file size limit. .RE .SH RETURN VALUE Upon successful completion, a non-negative value is returned. Errors return a \(mi1, with .CR errno set to indicate the error. .SH SEE ALSO brk(2), write(2). .SH STANDARDS CONFORMANCE .CR ulimit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4ulimit()\f1 \- get or set file size limits and break value@@@\f3ulimit(2)\f1 .\" index@get: file size limits and break value, get or set@@@\f3ulimit(2)\f1 .\" index@set: file size limits and break value, get or set@@@\f3ulimit(2)\f1 .\" index@file size limits and break value, get or set@@@\f3ulimit(2)\f1 .\" index@break value and file size limits, get or set@@@\f3ulimit(2)\f1 .\" index@value, get or set file size limits and break@@@\f3ulimit(2)\f1 .\" .\" toc@\f3ulimit(2)\f1:\0\0\f4ulimit()\fP@@@get and set user limits .\" $Header: umask.2,v 72.5 94/11/14 15:27:13 ssa Exp $ .TA u .TH umask 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME umask \- set and get file creation mask .SH SYNOPSIS .C "#include " .PP .C "mode_t umask(mode_t cmask);" .SH DESCRIPTION .C umask() sets the process's file mode creation mask to .C umask() and returns the previous value of the mask. Only the file access permission bits of the masks are used. .PP The bits set in .I cmask specify which permission bits to turn off in the mode of the created file, and should be specified using the symbolic values defined in .IR stat (5). .SH EXAMPLES The following creates a file named .C path in the current directory with permissions .CR S_IRWXU|S_IRGRP|S_IXGRP , so that the file can be written only by its owner, and can be read or executed only by the owner or processes with group permission, even though group write permission and all permissions for others are passed in to .CR creat() . .nf .IP .C #include .C #include .IP .C int fildes; .IP .C (void) umask(S_IWGRP|S_IRWXO); .ifn \f3fildes = creat("path", S_IRWXU|S_IRWXG|S_IRWXO);\fP .ift \f4\s+1fildes = creat("path", S_IRWXU|S_IRWXG|S_IRWXO);\s0\fP .fi .SH RETURN VALUE The previous value of the file mode creation mask is returned. .SH SEE ALSO mkdir(1), sh(1), mknod(1M), chmod(2), creat(2), mknod(2), open(2). .SH STANDARDS CONFORMANCE .CR umask() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4umask()\fP \(mi set and get file creation (permissions) mask@@@\f3umask(2)\f1 .\" index@set: file creation (permissions) mask, set and get@@@\f3umask(2)\f1 .\" index@set: file creation (permissions) mask, set and get@@@\f3umask(2)\f1 .\" index@file creation (permissions) mask, set and get@@@\f3umask(2)\f1 .\" index@permissions mask for file creation, set and get@@@\f3umask(2)\f1 .\" index@mask for file creation, set and get permissions@@@\f3umask(2)\f1 .\" .\" toc@\f3umask(2)\f1:\0\0\f4umask()\fP@@@set and get file creation mask .\" $Header: umount.2,v 72.5 94/11/14 15:27:14 ssa Exp $ .TA u .TH umount 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME umount \- unmount a file system .SH SYNOPSIS .C "#include " .PP .C "int umount(const char *name);" .SH DESCRIPTION .C umount() requests that a previously mounted file system contained on the block special device identified by .I name be unmounted. .I name is a pointer to a path name. After unmounting the file system, the directory upon which the file system was mounted reverts to its ordinary interpretation. .PP .C umount() can also request that a file system mounted previously on the directory identified by .I name be unmounted. After unmounting the file system, .I name reverts to its ordinary interpretation. .PP .C umount() can be invoked only by the user with the appropriate privilege. .SH NETWORKING FEATURES .SS NFS .I path must indicate a directory name when unmounting an .SM NFS file system. .SH RETURN VALUE If successful, .C umount() returns a value of .CR 0 . Otherwise, it returns a value of \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C umount() fails if one or more of the following are true: .TP 15 .SM [EPERM] The effective user ID of the process is not that of a user with appropriate privileges. .TP .SM [ENOENT] .I name does not exist. .TP .SM [ENOTBLK] .I name is not a block special device. .TP .SM [EINVAL] .I name is not mounted. .TP .SM [EBUSY] A file on .I name is busy. .TP .SM [EFAULT] .I name points outside the allocated address space of the process. Reliable detection of this error is implementation dependent. .TP .SM [ENXIO] The device associated with .I name does not exist. .TP .SM [ENOTDIR] A component of .I name is not a directory. .TP .SM [ENOENT] .I name is null. .TP .SM [ENAMETOOLONG] .I name exceeds .C PATH_MAX bytes, or a component of .I name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [EACCES] A component of the path prefix of .I name denies search permission. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the path name. .SH WARNINGS If .C umount() is called from the program level (that is, not from the .IR mount (1M) level), the table of mounted devices contained in .C /etc/mnttab is not updated automatically. Updating of .C /etc/mnttab is performed by the .C mount and .C syncer commands (see .IR mount (1M) and .IR syncer (1M) for more information). .SH SEE ALSO mount(1M), syncer(1M), mount(2), vfsmount(2). .SH STANDARDS CONFORMANCE .CR umount() ": SVID2, SVID3, XPG2" .\" .\" index@\f4umount()\fP \(mi unmount a file system@@@\f3umount(2)\f1 .\" index@unmount a file system@@@\f3umount(2)\f1 .\" index@file system: unmount a file system@@@\f3umount(2)\f1 .\" .\" toc@\f3umount(2)\f1:\0\0\f4umount()\fP@@@unmount a file system .\" $Header: uname.2,v 72.6 94/11/14 15:27:15 ssa Exp $ .\" NOTE: If this page changes, uname.1 probably changes too. .TA u .TH uname 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME uname(), setuname() \- get information about computer system; set node name (system name) .SH SYNOPSIS .C "#include " .PP .C "int uname(struct utsname *name);" .PP .C "int setuname(const char *name, size_t namelen);" .SH DESCRIPTION .SS uname() The .C uname() system call places information identifying the computer system in the .CR utsname structure pointed to by .IR name . .PP The .CR utsname structure, defined in .CR , is set up as follows: .nf .IP .C "#define UTSLEN 9" .C "#define SNLEN 15" .C "char sysname[UTSLEN];" .C "char nodename[UTSLEN];" .C "char release[UTSLEN];" .C "char version[UTSLEN];" .C "char machine[UTSLEN];" .C "char idnumber[SNLEN];" .fi .PP Each field is a null-terminated string. .PP The .CR sysname field contains the name of the operating system, .CR HP-UX on standard HP-UX systems. .PP The .CR nodename field contains the name by which the computer system is known in a communications network. .PP The .CR release field contains the release identifier of the operating system, such as .CR A.09.01 . .PP The .CR version field contains additional information about the operating system. This value can change in future releases. The first character of the .CR version field identifies the license level: .RS .TP .PD 0 .CR A Two-user system .TP .CR B 16-user system .TP .CR C 32-user system .TP .CR D 64-user system .TP .CR E 8-user system .TP .CR U 128-user, 256-user, or unlimited-user system .PD .RE .PP The .CR machine field contains the hardware and model identifiers of the computer system. .PP The .CR idnumber field contains a unique identification number within that class of hardware, possibly a hardware or software serial number. This field contains a null string if there is no identification number. .SS setuname() The .CR setuname() system call sets the node name (system name), as returned in the .CR nodename field of the .CR utsname structure, to .IR name , which has a length of .I namelen characters. This is usually executed by .CR /sbin/init.d/hostname at system boot time. Names are limited to .C UTSLEN - 1 characters; .CR UTSLEN is defined in .CR . .SH RETURN VALUE .CR uname() and .CR setuname() return the following values: .RS .TP .PD 0 .CI \0 n Successful completion. .IR n is a nonnegative value. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR uname() or .CR setuname() fails, .CR errno is set to one of the following values. .TP 15 [EFAULT] .I name points to an illegal address. The reliable detection of this error is implementation dependent. .TP [EPERM] .CR setuname() was attempted by a process lacking appropriate privileges. .SH AUTHOR .CR uname() was developed by AT&T and HP. .SH SEE ALSO hostname(1), uname(1), setuname(1M), gethostname(2), sethostname(2). .SH STANDARDS CONFORMANCE .CR uname() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" links@uname.2 setuname.2 .\" .\" index@\f1computer system information, get@@@\f3uname(2)\f1 .\" index@\f1computer system, set node name@@@\f3uname(2)\f1 .\" index@\f1get information about computer system@@@\f3uname(2)\f1 .\" index@\f1license level of operating system, get@@@\f3uname(2)\f1 .\" index@\f1machine identification, get@@@\f3uname(2)\f1 .\" index@\f1machine number, get@@@\f3uname(2)\f1 .\" index@\f1name of operating system, get@@@\f3uname(2)\f1 .\" index@\f1name of operating system, get@@@\f3uname(2)\f1 .\" index@\f1node name, get/set@@@\f3uname(2)\f1 .\" index@\f1operating system information, get@@@\f3uname(2)\f1 .\" index@\f1operating system name, get@@@\f3uname(2)\f1 .\" index@\f1release level of operating system, get@@@\f3uname(2)\f1 .\" index@\f1release of operating system, get@@@\f3uname(2)\f1 .\" index@\f1set node name@@@\f3uname(2)\f1 .\" index@\f1set system name@@@\f3uname(2)\f1 .\" index@\f1system information, get@@@\f3uname(2)\f1 .\" index@\f1system name, get/set@@@\f3uname(2)\f1 .\" index@\f1system, get information@@@\f3uname(2)\f1 .\" index@\f1system, set node name@@@\f3uname(2)\f1 .\" index@\f1version level of operating system, get@@@\f3uname(2)\f1 .\" index@\f4setuname()\f1 \- set node name (system name)@@@\f3uname(2)\f1 .\" index@\f4uname()\f1 \- get information about computer system@@@\f3uname(2)\f1 .\" .\" toc@\f3uname(2)\f1:\0\0\f4uname()\f1@@@get information about computer system; set node name (system name) .\" toc@\f4setuname(2)\f1:\0\0set node name (system name)@@@see \f3uname(2) .\" $Header: unlink.2,v 72.7 94/11/14 15:27:17 ssa Exp $ .TA u .TH unlink 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME unlink \- remove directory entry; delete file .SH SYNOPSIS .C "#include " .PP .C "int unlink(const char *path);" .SH DESCRIPTION The .CR unlink() system call removes the directory entry named by the path name pointed to by .IR path . .PP When all links to a file have been removed and no process has the file open, the space occupied by the file is freed and the file ceases to exist. If one or more processes have the file open when the last link is removed, only the directory entry is removed immediately so that processes that do not already have the file open cannot access the file. After all processes close their references to the file, if there are no more links to the file, the space occupied by the file is then freed and the file ceases to exist. .SH RETURN VALUE .CR unlink() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .SH ERRORS If .CR unlink() fails, .CR errno is set to one of the following values: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of the path prefix. .TP .SM [EACCES] Write permission is denied on the directory containing the link to be removed. .TP .SM [EACCES] The process does not have read/write access permission to the parent directory. .TP .SM [EBUSY] The entry to be unlinked is the mount point for a mounted file system. .TP .SM [EFAULT] .I path points outside the process's allocated address space. The reliable detection of this error is implementation dependent. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the path name. .TP .SM [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP .SM [ENOENT] The named file does not exist (for example, .I path is null or a component of .I path does not exist). .\" ZZZZZ .TP .SM [ENOTDIR] A component of the path prefix is not a directory. .TP .SM [EPERM] The directory containing the file to be removed has the sticky bit set and neither the containing directory nor the file to be removed are owned by the effective user .SM ID. .TP .SM [EPERM] The named file is a directory and the effective user .SM ID is not a user with appropriate privileges. .TP .SM [EROFS] The directory entry to be unlinked is part of a read-only file system. .TP .SM [ETXTBSY] The entry to be unlinked is the last link to a pure procedure (shared text) file that is being executed. .RE .SH WARNINGS If .CR unlink() is used on a directory that is .I not empty (contains files other than .CR . and .CR .. ), the directory is unlinked, the files become orphans, and the directory link count is left with an inaccurate value unless they are linked by some other directory. .PP If .CR unlink() is used on a directory that .I is empty (contains only the files .CR . and .CR .. ), the directory is unlinked, but the parent directory's link count is left with an inaccurate value. .PP In either of the above cases, the file system should be checked using .CR fsck (see .IR fsck (1M)). To avoid these types of problems, use .CR rmdir() instead (see .IR rmdir (2)). .SH SEE ALSO rm(1), close(2), link(2), open(2), rmdir(2), remove(3C). .SH STANDARDS CONFORMANCE .CR unlink() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4unlink\f1 \- remove directory entry; delete file@@@\f3unlink(2)\f1 .\" index@remove directory entry@@@\f3unlink(2)\f1 .\" index@delete file@@@\f3unlink(2)\f1 .\" index@file: delete@@@\f3unlink(2)\f1 .\" index@directory: remove entry@@@\f3unlink(2)\f1 .\" .\" toc@\f3unlink(2)\f1:\0\0\f4unlink\f1@@@remove directory entry; delete file .\" .\" fileset_database@unlink.2 PROG-AUX-MAN .\" $Header: usleep.2,v 76.2 95/07/07 15:00:44 ssa Exp $ .TA u .TH usleep 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME usleep \- suspend execution for an interval .SH SYNOPSIS .\" UX .PP .C "#include " .PP .C "int usleep(useconds_t useconds);" .\" ? .SH DESCRIPTION The .CR usleep() function suspends the current process from execution for the number of microseconds specified by the .IR useconds argument. Because of other activity, or because of the time spent in processing the call, the actual suspension time may be longer than the amount of time specified. .PP The .IR useconds argument must be less than 1,000,000. If the value of .IR useconds is 0, then the call has no effect. .PP The .CR usleep() function uses the process' real-time interval timer to indicate to the system when the process should be woken up. .PP There is one real\-time interval timer for each process. The .CR usleep() function will not interfere with a previous setting of this timer. If the process has set this timer prior to calling .CR usleep() , and if the time specified by .IR useconds equals or exceeds the interval timer's prior setting, the process will be woken up shortly before the timer was set to expire. .PP Implementations may place limitations on the granularity of timer values. For each interval timer, if the requested timer value requires a finer granularity than the implementation supports, the actual timer value will be rounded up to the next supported value. .PP Interactions between .CR usleep() and either .CR alarm() or .CR sleep() are unspecified. .SH RETURN VALUE On successful completion, .CR usleep() returns 0. Otherwise, it returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS The .CR usleep() function may fail if: .RS .P 25 [EINVAL] The time interval specified 1,000,000 or more microseconds. .RE .SH APPLICATION USAGE The .CR usleep() function is included for its historical usage. The .CR setitimer() function is preferred over this function. .SH SEE ALSO alarm(), getitimer(), sigaction(), sleep(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4usleep()\f1 \- suspend execution for an interval@@@\f3usleep(2)\f1 .\" index@\f1suspend execution for an interval@@@\f3usleep(2)\f1 .\" index@\f1execution, suspend for an interval@@@\f3usleep(2)\f1 .\" index@\f1interval, suspend execution for an interval@@@\f3usleep(2)\f1 .\" .\" toc@\f3usleep(2)\f1:\0\0\f4usleep()\f1@@@suspend execution for an interval .\" .\" fileset_database@usleep.2 .\" $Header: ustat.2,v 72.7 94/11/14 15:27:18 ssa Exp $ .TA u .TH ustat 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ustat() \- get mounted file system statistics .SH SYNOPSIS .C "#include " .PP .C "int ustat(dev_t dev, struct ustat *buf);" .SH DESCRIPTION The .CR ustat() system call returns information about a mounted file system. .I dev is a device number identifying a device containing a mounted file system. .I buf is a pointer to a .CR ustat structure (defined in .CR ) that includes the following elements: .nf .IP .C "daddr_t f_tfree; /* Total free blocks */" .C "ino_t f_tinode; /* Number of free inodes */" .C "char f_fname[6]; /* Filsys name or null */" .C "char f_fpack[6]; /* Filsys pack name or null */" .C "int f_blksize; /* Block size */" .fi .PP The value of .CR f_tfree is the number of free blocks of size .CR f_blksize . .SH RETURN VALUE .CR ustat() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR ustat() fails, .CR errno is set to one of the following values. .RS .TP 15 [EFAULT] .I buf points outside the process's allocated address space. The reliable detection of this error is implementation dependent. .TP [EINVAL] .I dev is not the device number of a device containing a mounted file system. .RE .SH WARNINGS For some file systems, the number of free inodes does not change. Such file systems will return .CR -1 in the field .CR f_tinode . .PP For some file systems, the inodes can be dynamically allocated. For such file systems, the field .CR f_tinode contains the number of free inodes at the current time. .SH AUTHOR .C ustat() was developed by AT&T and HP. .SH SEE ALSO touch(1), stat(2), statvfs(2), fs(4), fs_vxfs(4). .SH STANDARDS CONFORMANCE .CR ustat() ": SVID2, SVID3, XPG2" .\" .\" index@\f1file system, get mounted file system statistics@@@\f3ustat(2)\f1 .\" index@\f1get mounted file system statistics@@@\f3ustat(2)\f1 .\" index@\f1mounted file system statistics, get@@@\f3ustat(2)\f1 .\" index@\f1statistics, get mounted file system@@@\f3ustat(2)\f1 .\" index@\f4ustat()\f1 \- get mounted file system statistics@@@\f3ustat(2)\f1 .\" .\" toc@\f3ustat(2)\f1:\0\0\f4ustat()\f1@@@get mounted file system statistics .\" $Header: utime.2,v 72.5 94/11/14 15:27:22 ssa Exp $ .TA u .TH utime 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME utime() \- set file access and modification times .SH SYNOPSIS .C "#include " .PP .C "int utime(const char *path, const struct utimbuf *times);" .SH DESCRIPTION The .CR utime() system call sets the access and modification times of the file to which the .I path argument refers. .PP If .I times is a NULL pointer, the access and modification times of the file are set to the current time. A process must be the owner of the file or have write permission on the file to use .CR utime() in this manner. .PP If .I times is not a NULL pointer, .I times is interpreted as a pointer to a .I utimbuf structure, and the access and modification times are set to the values contained in the designated structure. Only the owner of the file or a user with appropriate privileges can use .CR utime() this way. .PP The following times in the .CR utimbuf structure defined in .CR are measured in seconds since 00:00:00 UTC (Coordinated Universal Time), January 1, 1970. .nf .IP .C "time_t actime; /* access time */" .C "time_t modtime; /* modification time */ .fi .SH RETURN VALUE .CR utime() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR utime() fails, .CR errno is set to one of the following values. .RS .TP 15 [EACCES] Search permission is denied by a component of the path prefix. .TP [EACCES] The effective user ID is not a user with appropriate privileges, and not the owner of the file, .I times is a NULL pointer, and write access is denied. .TP [EFAULT] .I times is not a NULL pointer, and it points outside the process's allocated address space. The reliable detection of this error is implementation-dependent. .TP [EFAULT] .I path points outside the process's allocated address space. The reliable detection of this error is implementation-dependent. .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] The named file does not exist. .TP [ENOTDIR] A component of the path prefix is not a directory. .TP [EPERM] The effective user ID is not a user with appropriate privileges. and not the owner of the file, and .I times is not a NULL pointer. .TP [EROFS] The file system containing the file is mounted read-only. .RE .SH DEPENDENCIES .SS NFS .CR utime() may return [EPERM] when invoked on a remote file owned by a superuser, even if the invoking user has write permission on the file. .SH SEE ALSO touch(1), stat(2). .SH STANDARDS CONFORMANCE .CR utime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4utime()\f1 \- set or update file access and modification times@@@\f3utime(2)\f1 .\" index@set file access and modification times@@@\f3utime(2)\f1 .\" index@update file access and modification times@@@\f3utime(2)\f1 .\" index@file access and modification times, set or update@@@\f3utime(2)\f1 .\" index@access times, set or update file@@@\f3utime(2)\f1 .\" index@modification times, set or update file@@@\f3utime(2)\f1 .\" index@times, file access and modification, set or update@@@\f3utime(2)\f1 .\" .\" toc@\f3utime(2)\f1:\0\0\f4utime()\f1@@@set file access and modification times .\" $Header: utimes.2,v 76.2 95/07/07 15:01:31 ssa Exp $ .TA u .TH utimes 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME utimes \- set file access and modification times .SH SYNOPSIS .\" UX .PP .C "#include " .PP .C "int utimes(const char *path, const struct timeval times[2]);" .PP .\" ? .SH DESCRIPTION The .CR utimes() function sets the access and modification times of the file pointed to by the .IR path argument to the value of the .IR times argument. The .CR utimes() function allows time specifications accurate to the microsecond. .PP For .CR utimes() , the .IR times argument is an array of .CR timeval structures. The first array member represents the date and time of last access, and the second member represents the date and time of last modification. The times in the .CR timeval structure are measured in seconds and microseconds since the Epoch, although rounding toward the nearest second may occur. .PP If the .IR times argument is a null pointer, the access and modification times of the file are set to the current time. The effective user ID of the process must be the same as the owner of the file, or must have write access to the file or appropriate privileges to use this call in this manner. Upon completion, .CR utimes() will mark the time of the last file status change, .IR st_ctime , for update. .PP .SH RETURN VALUE Upon successful completion, 0 is returned. Otherwise, \(mi1 is returned and .CR errno is set to indicate the error, and the file times will not be affected. .SH ERRORS The utimes() function will fail if: .RS .TP 25 [EACCES] Search permission is denied by a component of the .IR path prefix; or the .IR times argument is a null pointer and the effective user ID of the process does not match the owner of the file and write access is denied. .TP [ELOOP] Too many symbolic links were encountered in resolving path. .TP [ENAMETOOLONG] The length of the .IR path argument exceeds .CR {PATH_MAX} or a pathname component is longer than .CR {NAME_MAX} . .TP [ENOENT] A component of .IR path does not name an existing file or .IR path is an empty string. .TP [ENOTDIR] A component of the .IR path prefix is not a directory. .TP [EPERM] The .IR times argument is not a null pointer and the calling process' effective user ID has write access to the file but does not match the owner of the file and the calling process does not have the appropriate privileges. .TP [EROFS] The file system containing the file is read-only. .RE .PP The .CR utimes() function may fail if: .RS .TP 25 [ENAMETOOLONG] Pathname resolution of a symbolic link produced an intermediate result whose length exceeds .CR {PATH_MAX}. .SH SEE ALSO . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4utimes()\f1 \- set file access and modification times@@@\f3utimes(2)\f1 .\" index@\f1set file access and modification times@@@\f3utimes(2)\f1 .\" index@\f1file access and modification times, set@@@\f3utimes(2)\f1 .\" index@\f1access and modification times, set for files@@@\f3utimes(2)\f1 .\" index@\f1times, set file access and modification times@@@\f3utimes(2)\f1 .\" .\" toc@\f3utimes(2)\f1:\0\0\f4utimes()\f1@@@set time access and modification times .\" .\" fileset_database@utimes.2 .\" $Header: vfork.2,v 72.4 94/09/06 15:16:21 ssa Exp $ .TA v .TH vfork 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vfork \- spawn new process; share virtual memory .SH SYNOPSIS .C #include .PP .C pid_t vfork(void); .SH REMARKS .C vfork() is a higher performance version of .C fork() that is provided on some systems where a performance advantage can be attained. .PP .C vfork() differs from .C fork() only in that the child process can share code and data with the calling process (parent process). This speeds cloning activity significantly at a risk to the integrity of the parent process if .C vfork() is misused. .PP The use of .C vfork() for any purpose except as a prelude to an immediate .C exec() or .C exit() is not supported. Any program that relies upon the differences between .C fork() and .C vfork() is not portable across .SM HP-UX systems. .PP All .SM HP-UX implementations must provide the entry .CR vfork() , but it is permissible for them to treat it identically to .CR fork . On some implementations the two are not distinguished because the .C fork() implementation is as efficient as possible. Other versions may do the same to avoid the overhead of supporting two similar calls. .SH DESCRIPTION .C vfork() can be used to create new processes without fully copying the address space of the old process. If a forked process is simply going to do an .C exec() (see .IR exec (2)), the data space copied from the parent to the child by .C fork() is not used. This is particularly inefficient in a paged environment, making .C vfork is particularly useful. Depending upon the size of the parent's data space, .C vfork() can give a significant performance improvement over .CR fork() . .PP .C vfork() differs from .C fork() in that the child borrows the parent's memory and thread of control until a call to .C exec() or an exit (either by a call to .C exit() or abnormally (see .IR exec (2) and .IR exit (2)). The parent process is suspended while the child is using its resources. .PP .C vfork() returns 0 in the child's context and (later) the pid of the child in the parent's context. .PP .C vfork() can normally be used just like .CR fork() . It does not work, however, to return while running in the child's context from the procedure which called .C vfork() since the eventual return from .C vfork() would then return to a no longer existent stack frame. Be careful, also, to call .C _exit() rather than .C exit() if you cannot .CR exec() , since .C exit() flushes and closes standard .SM I/O channels, thereby damaging the parent process's standard .SM I/O data structures. (Even with .C fork() it is wrong to call .C exit() since buffered data would then be flushed twice.) .PP The .RC [ vfork , exec ] window begins at the .C vfork() call and ends when the child completes its .C exec() call. .SH RETURN VALUE Upon successful completion, .C vfork() returns a value of 0 to the child process and returns the process .SM ID of the child process to the parent process. Otherwise, a value of \(mi1 is returned to the parent, no child process is created, and .C errno is set to indicate the error. .SH ERRORS .C vfork() fails and no child process is created if any of the following conditions are encountered: .RS .TP 15 .SM [EAGAIN] The system-wide limit on the total number of processes under execution would be exceeded. .TP .SM [EAGAIN] The system-imposed limit on the total number of processes under execution by a single user would be exceeded. .RE .SH DEPENDENCIES .SS Series 800 Process times for the parent and child processes within the .RC [ vfork , exec ] window may be inaccurate. .IP Parent and child processes share the same stack space within the .RC [ vfork , exec ] window. If the size of the stack has been changed within this window by the child process (return from or call to a function, for example), it is likely that the parent and child processes will be killed with signal .C SIGSEGV or .CR SIGBUS . .IP In the .RC [ vfork , exec ] window, a call to .C signal() (see .IR signal (2) that installs a catching function can affect handling of the signal by the parent. The parent is not affected if the handling is being set to .C SIG_DFL or .CR SIG_IGN , or if either .C sigaction() or .C sigvector() is used (see .IR sigaction (2) and .IR sigvector (2)). .SH AUTHOR .C vfork() was developed by the University of California, Berkeley. .SH SEE ALSO exec(2), exit(2), fork(2), wait(2). .\" index@\f4vfork()\fP \(mi spawn new process (use \f4fork()\fP instead)@@@\f3vfork(2)\f1 .\" index@spawn new process (use \f4fork()\fP instead)@@@\f3vfork(2)\f1 .\" index@process, spawn new (use \f4fork()\fP instead)@@@\f3vfork(2)\f1 .\" .\" toc@\f3vfork(2)\f1:\0\0\f4vfork()\fP@@@spawn new process (use \f4fork()\fP instead) .\" $Header: vfsmount.2,v 72.4 94/10/31 11:34:37 ssa Exp $ .TA v .TH vfsmount 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vfsmount \- mount a file system .SH SYNOPSIS .nf .C "#include " .PP .C "int vfsmount(int type," .C " const char *dir," .C " int flags," .C " caddr_t data);" .fi .SS Remarks This routine is included only for compatibility with past releases. It works only with UFS (HFS), NFS, and CDFS file systems. For maximum portability and improved functionality, new applications should use the .CR mount() system call (see .IR mount (2)). .SH DESCRIPTION The .CR vfsmount() system call attaches a file system to a directory. After a successful return, references to directory .I dir refer to the root directory of the newly mounted file system. .I dir is a pointer to a null-terminated string containing a path name. .I dir must exist already, and must be a directory. Its old contents are inaccessible while the file system is mounted. .PP .I type indicates the type of the file system. It must be one of the types described below. .CR vfsmount() does not check that the file system is actually of type .IR type ; if .I type is incorrect, .CR vfsmount() may cause the process to hang. To prevent such problems, .CR statfsdev() (see .IR statfsdev (3c)) should be called before .CR vfsmount() to check the file system type, which .CR statfsdev() places in the .CR f_fsid[1] field of the .CR statfs structure that it returns. .PP The .I flags argument determines whether the file system can be written to. It also controls whether programs from the mounted file system are allowed to have set-user-ID execution. Physically write-protected and magnetic tape file systems must be mounted read-only. Failure to do so results in a return of \(mi1 by .CR vfsmount() and a value of [EIO] in .CR errno . The following values for the .I flags argument are defined in .CR : .RS .TP 15 .CR M_RDONLY Mount done as read-only. .TP .CR M_NOSUID Execution of set-user-ID programs not permitted. .RE .PP .I data is a pointer to a structure containing arguments specific to the value contained in .IR type . The following values for .I type are defined in .CR : .RS .TP 15 .CR MOUNT_CDFS Mount a local CD-ROM file system. .I data points to a structure of the following format: .RS .nf .IP .C "struct cdfs_args {" .C " char *fspec;" .C "};" .fi .RE .IP .I fspec points to the name of the block special file that is to be mounted. .TP .CR MOUNT_UFS Mount a local HFS file system. .I data points to a structure of the following format: .RS .nf .IP .C "struct ufs_args {" .C " char *fspec;" .C " int flags;" .C "};" .fi .PP .I fspec points to the name of the block special file that is to be mounted. This is identical in use and function to the first argument of .CR mount() (see .IR mount (2)). .PP .I flags points to a bit map that sets options. The following values of the bits are defined in .CR : .TP 20 .CR MS_DELAY Specify that the writes to disks are to be delayed till the buffer needs to be reused. This is the default on Series 800 systems, as it was prior to release 10.0. .TP .CR MS_BEHIND Specify that the writes to disks are to be done asynchronously, where possible, without waiting for completion. This is the default on Series 700 systems, as it was prior to release 10.0. .IP .CR MS_BEHIND and .CR MS_DELAY are mutually exclusive. .TP .CR MS_NO_FSASYNC Specify that rigorous posting of file system metadata is to be used. This is the default. .TP .CR MS_FSASYNC Specify that relaxed posting of file system metadata is to be used. This may lead to better performance for certain applications; but there is increased potential for data loss in case of a crash. .IP .CR MS_FSASYNC and .CR MS_NO_FSASYNC are mutually exclusive. .RE .RE .SH NETWORKING FEATURES .SS NFS An additional value for the .I type argument is supported. .RS .TP .CR MOUNT_NFS .IP Mount an NFS file system. .I data points to a structure of the following format: .RS .nf .IP .C "#include " .C "#include " .IP .C "struct nfs_args {" .C " struct sockaddr_in *addr;" .C " fhandle_t *fh;" .C " int flags;" .C " int wsize;" .C " int rsize;" .C " int timeo;" .C " int retrans;" .C " char *hostname;" .C " int acregmin;" .C " int acregmax;" .C " int acdirmin;" .C " int acdirmax;" .C "};" .fi .PP Elements in the structure as as follows: .TP 15 .CR addr Points to a local socket address structure (see .IR inet (7)), which is used by the system to communicate with the remote file server. .TP .CR fh Points to a structure containing a file handle, an abstract data type that is used by the remote file server when serving an NFS request. .TP .CR flags Bit map that sets options and indicates which of the following fields contain valid information. The following values of the bits are defined in .CR : .RS .TP 20 .CR NFSMNT_SOFT Specify whether the mount is a soft mount or a hard mount. If set, the mount is soft and will cause requests to be retried .CR retrans number of times. Otherwise, the mount is hard and requests will be tried forever. .TP .CR NFSMNT_WSIZE Set the write size. .TP .CR NFSMNT_RSIZE Set the read size. .TP .CR NFSMNT_TIMEO Set the initial timeout value. .TP .CR NFSMNT_RETRANS Set the number of request retries. .TP .CR NFSMNT_HOSTNAME Set a host name. .TP .CR NFSMNT_INT Set the option to have interruptible I/O to the mounted file system. .TP .CR NFSMNT_NODEVS Set the option to deny access to local devices via NFS device files. By default, access to local devices via NFS device files is allowed. .TP .CR NFSMNT_IGNORE Mark the file system type as .CR ignore in .CR /etc/mnttab . .TP .CR NFSMNT_NOAC Turn off attribute caching. By default, NFS caches attributes of files and directories to speed up operations on NFS files by not always getting the attributes from the server. Names are also cached to speed up path name lookup. However it does allow modifications to files on the server to not be immediately detectable on the clients. Setting .CR NFSMNT_NOAC turns off attribute caching and name lookup caching. NFS caches attributes for a length of time proportional to how much time has elapsed since the last modification. The time length is subject to .CR acregmin , .CR acregmax , .CR acdirmin , and .CR acdirmax , described below. .TP .CR NFSMNT_NOCTO Cached attributes are flushed when a NFS file is opened unless this option is specified. This option is useful where it is known that the files will not be changing as is the case for a CD-ROM drive. .TP .CR NFSMNT_ACREGMIN Use the .CR acregmin value. See .CR acregmin below. .TP .CR NFSMNT_ACDIRMIN Use the .CR acdirmin value. See .CR acdirmin below. .TP .CR NFSMNT_ACREGMAX Use the .CR acregmax value. See .CR acregmax below. .TP .CR NFSMNT_ACDIRMAX Use the .CR acdirmax value. See .CR acdirmax below. .RE .TP .CR wsize Can be used to advise the system about the maximum number of data bytes to use for a single outgoing protocol (such as UDP) message. This value must be greater than 0. The default is .CR 8192 . .TP .CR rsize Can be used to advise the system about the maximum number of data bytes to use for a single incoming protocol (such as UDP) message. This value must be greater than 0. The default is .CR 8192 . .TP .CR timeo Can be used to advise the system on the time to wait between NFS request retries. This is in units of 0.1 seconds. This value must be greater than 0. The default is .CR 7 . .TP .CR retrans Can be used to advise the system about the number of times the system will resend a request. This value must be 0 or greater. The default is .CR 4 . .TP .CR hostname A name for the file server that can be used when any messages are given concerning the server. The string can contain 0 to 32 characters. .TP .CR acregmin Can be used to advise the system of the minimum number of seconds to cache attributes for a nondirectory file. If this number is less than 0, it means to use the system-defined maximum of 3600 seconds. The number specified can not be 0. If the number is greater than 3600, 3600 will be used. The default is .CR 3 . .CR acregmin is ignored if .CR NFSMNT_NOAC is specified. .TP .CR acdirmin Can be used to advise the system of the minimum number of seconds to cache attributes for a directory. If this number is less than 0, it means to use the system-defined maximum of 3600 seconds. The number specified can not be 0. If the number is greater than 3600, 3600 will be used. The default is .CR 30 . .CR acdirmin is ignored if .CR NFSMNT_NOAC is specified. .TP .CR acregmax Can be used to advise the system of the maximum number of seconds to cache attributes for a nondirectory file. If this number is less than 0, it means to use the system defined maximum of 36000 seconds. The number specified cannot be 0. If the number is greater than 36000, 36000 is used. The default is .CR 60 . .CR acregmax is ignored if .CR NFSMNT_NOAC is specified. .TP .CR acdirmax can be used to advise the system of the maximum number of seconds to cache attributes for a directory. If this number is less than 0, it means to use the system defined maximum of 36000 seconds. The number specified cannot be 0. If the number is greater than 36000, 36000 is used. The default is .CR 60 . .CR acdirmax is ignored if .CR NFSMNT_NOAC is specified. .RE .RE .SH RETURN VALUE .CR vfsmount() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. No file system is mounted. .CR errno is set to indicate the error. .PD .RE .SH ERRORS If .CR vfsmount() fails, .CR errno is set to one of the following values. .TP 15 [EBUSY] .I dir is not a directory, or another process currently holds a reference to it. .TP [EBUSY] No space remains in the mount table. .TP [EBUSY] The superblock for the file system had a bad magic number or an out-of-range block size. .TP [EBUSY] Not enough memory was available to read the cylinder group information for the file system. .TP [EFAULT] .I data or .I dir points outside the allocated address space of the process. .TP [EINVAL] .I type is not .CR MOUNT_UFS , .CR MOUNT_NFS , or .CR MOUNT_CDFS . .TP [EIO] An I/O error occurred while reading from or writing to the file system. .TP [EIO] An attempt was made to mount a physically write protected or magnetic tape file system as read-write. .TP [ELOOP] Too many symbolic links were encountered while translating the path name of file system referred to by .I data or .IR dir . .TP [ENAMETOOLONG] The path name of the file system referred to by .I data or .I dir is longer than .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] The file system referred to by .I data or .I dir does not exist. .TP [ENOENT] The file system referred to by .I data does not exist. .TP [ENOTBLK] The file system referred to by .I data is not a block device. This message can occur only during a local mount. .TP [ENOTDIR] A component of the path prefix in .I dir is not a directory. .TP [ENOTDIR] A component of the path prefix of the file system referred to by .I data or .I dir is not a directory. .TP [ENXIO] The major device number of the file system referred to by .I data is out of range (indicating that no device driver exists for the associated hardware). .TP [EPERM] The caller does not have appropriate privileges. .SH DEPENDENCIES .SS NFS If .CR vfsmount() fails, .CR errno can also be set to one of the following values. .RS .TP 15 [EFAULT] A pointer in the .I data structure points outside the process's allocated address space. .TP [EINVAL] A value in a field of .I data is out of proper range. .TP [EREMOTE] An attempt was made to remotely mount a file system that was already mounted from another remote node. .RE .PP See .IR mountd (1M), .IR getfh (2), and .IR inet (7) for more information. .SH WARNINGS The .CR mount command (see .IR mount (1M)) is preferred over .CR vfsmount() because .CR mount supports all mounting options that are available from .CR vfsmount() directly, plus .CR mount also maintains the .CR /etc/mnttab file which lists what file systems are mounted. .SH AUTHOR .CR vfsmount() was developed by HP and Sun Microsystems, Inc. .SH SEE ALSO mount(1M), mount(2), umount(2). .\" index@\f4vfsmount()\f1 \- mount a file system@@@\f3vfsmount(2)\f1 .\" index@mount a file system@@@\f3vfsmount(2)\f1 .\" index@file system, mount@@@\f3vfsmount(2)\f1 .\" .\" toc@\f3vfsmount(2)\f1:\0\0\f4vfsmount()\f1@@@mount a file system .\" $Header: wait.2,v 76.1 95/07/07 15:04:01 ssa Exp $ .TA w .TH wait 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wait, waitpid \- wait for child process to stop or terminate .SH SYNOPSIS .\" OH .PP .C "#include OH" .C "#include " .PP .C "pid_t wait(int *stat_loc);" .PP .C "pid_t waitpid(pid_t pid, int *stat_loc, int options);" .SH DESCRIPTION The .CR wait() and .CR waitpid() functions allow the calling process to obtain status information pertaining to one of its child processes. Various options permit status information to be obtained for child processes that have terminated or stopped. If status information is available for two or more child processes, the order in which their status is reported is unspecified. .PP The .CR wait() function will suspend execution of the calling process until status information for one of its terminated child processes is available, or until delivery of a signal whose action is either to execute a signal\-catching function or to terminate the process. If status information is available prior to the call to .CR wait() , return will be immediate. .PP The .IR waitpid() function will behave identically to .CR wait() , if the .IR pid argument is .IR ( pid_t )\(mi1 and the .IR options argument is 0. Otherwise, its behaviour will be modified by the values of the .IR pid and .IR options arguments. .PP The .IR pid argument specifies a set of child processes for which status is requested. The .CR waitpid() function will only return the status of a child process from this set: .RS .TP 3 \(bu If .IR pid is equal to .RI ( pid_t )\(mi1, status is requested for any child process. In this respect, .CR waitpid() is then equivalent to .CR wait() . .TP 3 \(bu If pid is greater than 0, it specifies the process ID of a single child process for which status is requested. .TP 3 \(bu If pid is 0, status is requested for any child process whose process group ID is equal to that of the calling process. .TP 3 \(bu If .IR pid is less than .RI ( pid_t )\(mi1, status is requested for any child process whose process group ID is equal to the absolute value of .IR pid . .PP The .IR options argument is constructed from the bitwise\-inclusive OR of zero or more of the following flags, defined in the header .CR . .\" UX .RS .TP 25 .C WCONTINUED The .CR waitpid() function will report the status of any continued child process specified by .IR pid whose status has not been reported since it continued from a job control stop. .\" ? .TP .C WNOHANG The .IR waitpid() function will not suspend execution of the calling process if status is not immediately available for one of the child processes specified by .IR pid . .TP .C WUNTRACED The status of any child processes specified by .IR pid that are stopped, and whose status has not yet been reported since they stopped, will also be reported to the requesting process. .\" UX .RE .PP If the calling process has .CR SA_NOCLDWAIT set or has .CR SIGCHLD set to .CR SIG_IGN , and the process has no unwaited for children that were transformed into zombie processes, it will block until all of its children terminate, and .CR wait() and .CR waitpid() will fail and set .CR errno to .CR ECHILD . .\" ? .PP If .CR wait() or .CR waitpid() return because the status of a child process is available, these functions will return a value equal to the process ID of the child process. In this case, if the value of the argument .IR stat_loc is not a null pointer, information will be stored in the location pointed to by .IR stat_loc . If and only if the status returned is from a terminated child process that returned 0 from .CR main() or passed 0 as the status argument to .CR _exit() or .CR exit() , the value stored at the location pointed to by .IR stat_loc will be 0. Regardless of its value, this information may be interpreted using the following macros, which are defined in .CR and evaluate to integral expressions; the .IR stat_val argument is the integer value pointed to by .IR stat_loc . .RS .TP 25 .C WIFEXITED(stat_val) Evaluates to a non-zero value if status was returned for a child process that terminated normally. .C WEXITSTATUS(stat_val) If the value of .CR WIFEXITED(stat_val) is non\-zero, this macro evaluates to the low\-order 8 bits of the .IR status argument that the child process passed to .CR _exit() or .CR exit() , or the value the child process returned from .CR main() . .TP .C WIFSIGNALED(stat_val) Evaluates to non\-zero value if status was returned for a child process that terminated due to the receipt of a signal that was not caught (see .RI < signal.h >). .TP .C WTERMSIG(stat_val) If the value of .CR WIFSIGNALED(stat_val) is non\-zero, this macro evaluates to the number of the signal that caused the termination of the child process. .CR WIFSTOPPED(stat_val) Evaluates to a non\-zero value if status was returned for a child process that is currently stopped. .TP .C WSTOPSIG(stat_val) If the value of .CR WIFSTOPPED(stat_val) is non\-zero, this macro evaluates to the number of the signal that caused the child process to stop. .\" UX .TP .C WIFCONTINUED(stat_val) .\" ! Evaluates to a non\-zero value if status was returned for a child process that has continued from a job control stop. .\" ? .RE .PP If the information pointed to by .IR stat_loc was stored by a call to .CR waitpid() that specified the .CR WUNTRACED .\" UX !auX flag and did not specify the .CR WCONTINUED flag, exactly one of the macros .CR WIFEXITED(*stat_loc) , .CR WIFSIGNALED(*stat_loc) , and .CR WIFSTOPPED(*stat_loc) will evaluate to a non\-zero value. .PP If the information pointed to by .IR stat_loc was stored .\" UX by a call to .CR waitpid() that specified the .CR WUNTRACED .\" ! and .CR WCONTINUED flags, exactly one of the macros .CR WIFEXITED(*stat_loc) , .CR WIFSIGNALED(*stat_loc) , .\" UX .CR WIFSTOPPED(*stat_loc) , .\" ! and .CR WIFCONTINUED .CR (*stat_loc) will evaluate to a non\-zero value. .PP If the information pointed to by .IR stat_loc was stored by a call to .CR waitpid() that did not specify the .\" UX .CR WUNTRACED .\" ! or .CR WCONTINUED flags, or by a call to the .CR wait() function, exactly one of the macros .CR WIFEXITED(*stat_loc) and .CR WIFSIGNALED(*stat_loc) will evaluate to a non\-zero value. .PP If the information pointed to by .IR stat_loc was stored by a call to .CR waitpid() that did not specify the .\" UX .CR WUNTRACED flag .\" ! and specified the .CR WCONTINUED flag, by a call to the .CR wait() function, exactly one of the macros .CR WIFEXITED(*stat_loc) , .\" UX .CR WIFSIGNALED(*stat_loc) , . \" ! and .CR WIFCONTINUED(*stat_loc) will evaluate to a non\-zero value. .PP There may be additional implementation\-dependent circumstances under which .CR wait() or .CR waitpid() report status. This will not occur unless the calling process or one of its child processes explicitly makes use of a non\-standard extension. In these cases the interpretation of the reported status is implementation\-dependent. .PP If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes will be assigned a new parent process ID corresponding to an implementation\-dependent system process. .SH RETURN VALUE If .CR wait() or .CR waitpid() returns because the status of a child process is available, these functions will return a value equal to the process ID of the child process for which status is reported. If .CR wait() or .CR waitpid() returns due to the delivery of a signal to the calling process, \(mi1 will be returned and .CR errno will be set to .CR EINTR . If .CR waitpid() was invoked with .CR WNOHANG set in .IR options , it has at least one child process specified by .IR pid for which status is not available, and status is not available for any process specified by .IR pid , 0 will be returned. Otherwise, .IR (pid_t) \(mi1 will be returned, and .CR errno will be set to indicate the error. .SH ERRORS The .CR wait() function will fail if: .TP 15 [ECHILD] The calling process has no existing unwaited\-for child processes. .TP [EINTR] The function was interrupted by a signal. The value of the location pointed to by .IR stat_loc is undefined. .RE .PP The .CR waitpid() function will fail if: .TP 15 [ECHILD] The process or process group specified by .IR pid does not exist or is not a child of the calling process. .TP [EINTR] The function was interrupted by a signal. The value of the location pointed to by .IR stat_loc is undefined. .TP [EINVAL] The .IR options argument is not valid. .SH SEE ALSO exec, exit(), fork(), wait3(), waitid(), , . .SH CHANGE HISTORY First released in Issue 1. .PP Derived from Issue 1 of the SVID. .SH Issue 4 .PP The following change is incorporated for alignment with the ISO POSIX-1 standard: .RS .TP 3 \(bu Text describing conditions under which 0 will be returned when .CR WNOHUNG is set in .IR options is added to the RETURN VALUE section. .RE .PP Other changes are incorporated as follows: .RS .TP 3 \(bu The header .CR is now marked as optional (OH); this header need not be included on XSI\-conformant systems. .TP 3 \(bu Error return values throughout the DESCRIPTION and RETURN VALUE sections are changed to show the proper casting (that is, .RI ( pid_t )\(mi1. .TP 3 \(bu The words "If the implementation supports job control" are removed from the description of .CR WUNTRACED . This is because job control is defined as mandatory for Issue 4 conforming implementations. .RE .PP .SH Issue 4, Version 2 .PP The following changes are incorporated in the DESCRIPTION for X/OPEN UNIX conformance: .RS .TP 3 \(bu The .CR WCONTINUED .IR options flag and the .CR WIFCONTINUED(stat_val) macro are added. .TP 3 \(bu Text following the list of options flags explains the implications of setting the .CR SA_NOCLDWAIT signal flag, or setting .CR SIGCHILD to .CR SIG_IGN . .TP 3 \(bu Text following the list of macros, which explains what macros return non\-zero values in certain cases, is expanded and the value of the .CR WCONTINUED flag on the previous call to .CR waitpid() is taken into account. .TA .TH wait 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH NAME wait(), waitpid() \- wait for child or traced process to stop or terminate .SH DESCRIPTION .SH wait() If a parent process terminates without waiting for its child processes to terminate, the parent process ID of each child process is set to 1. This means the initialization process inherits the child processes. .RS .TP 25 .C WCOREDUMP(*stat_loc) If the value of .CR WIFSIGNALED(*stat_loc) is nonzero, this macro evaluates to a nonzero value if a "core image" was produced (see .IR signal (5)). .RE .SH waitpid() .RS .TP 25 .C WNOWAIT Keep the process whose status is returned in .IR *stat_loc in a waitable state. The process may be waited for again with identical results, provided the state of the process doesn't change in the interim. .TP .C WUNTRACED If and only if this flag is set, .CR waitpid() or .CR wait3() returns information on child or attached processes that are stopped but not traced (with .CR ptrace(2) ) because they received a .CR SIGTTIN , .CR SIGTTOU , .CR SIGTSTP , or .CR SIGSTOP signal, and whose status has not yet been reported. Regardless of this flag, status is returned for child or attached processes that have terminated or are stopped and traced and whose status has not yet been reported. .SH Notes Earlier HP\-UX versions documented the bit encodings of the status returned by .CR wait() rather than the macros .CR WCOREDUMP , .CR WEXITSTATUS , .CR WIFEXITED , .CR WIFSIGNALED , .CR WIFSTOPPED , .CR WSTOPSIG , and .CR WTERMSIG . Applications using those bit encodings will continue to work correctly. However, new applications should use the macros for maximum portability. .PP In earlier HP\-UX versions, the macros .CR WIFEXITED , .CR WIFSIGNALED , and .CR WIFSTOPPED have the same definitions as the correspondingly named macros in the BSD 4.3 and earlier systems. Existing applications that depend on these definitions will continue to work correctly. However, if the application is recompiled, the feature test macro .CR_BSD must be turned on for the compilation so that the old definitions of these macros are obtained. New definitions of these macros are in effect by default. The only difference between the old and new definitions is the type of the argument. Type union .CR wait is used in the BSD definitions while type .IR int is used in the default definitions. .SH ERRORS If .CR wait() or .CR waitpid() fails, .CR errno is set to one of the following values. .RS .TP 25 .C [EACCES] The calling process of .CR waitpid() does not have read permission to the .IR pid . .TP .C [EFAULT] .IR stat_loc points to an illegal address. The reliable detection of this error is implementation\-dependent. .RE .SH WARNINGS The behavior of .CR wait() and .CR waitpid() is affected if the .CR SIGCLD signal is set to .CR SIG_IGN . See the WARNINGS section of .IR signal (5). Signal handlers that cause system calls to be restarted can affect the .CR EINTR condition described above (see .IR bsdproc (2), .IR sigaction (2), and .IR sigvector (2)). .SH AUTHOR wait(), waitpid(), and wait3() were developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO Exit conditions ($?) in sh(1); exec(2), exit(2), fork(2), pause(2), ptrace(2), signal(5). .SH STANDARDS CONFORMANCE wait(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 .PP waitpid(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1 .\" .\" index@\f4wait()\f1 \- wait for child or traced process to stop or terminate@@@\f3wait(2)\f1 .\" index@\f4waitpid()\f1 \- wait for child or traced process to stop or terminate@@@\f3wait(2)\f1 .\" index@\f1child process to stop or terminate, wait for@@@\f3wait(2)\f1 .\" index@\f1process to stop or terminate, wait for child@@@\f3wait(2)\f1 .\" index@\f1stop, wait for child process to@@@\f3wait(2)\f1 .\" index@\f1terminate, wait for child process to@@@\f3wait(2)\f1 .\" .\" links@wait.2 waitpid.2 .\" .\" toc@\f3wait(2)\f1:\0\0\f4wait()\f1, \f4waitpid()\f1@@@wait for child process to stop or terminate .\" toc@\f4waitpid()\f1:\0\0wait for child process to stop or terminate@@@see \f3wait(2)\f1 .\" $Header: wait3.2,v 76.2 95/07/07 15:04:42 ssa Exp $ .TA w .TH wait3 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wait3 \- wait for child process to change state .SH SYNOPSIS .\" UX .C "#include " .PP .C "pid_t wait3 (int *stat_loc, int options," .RS .C "struct rusage *resource_usage);" .\" ? .SH DESCRIPTION The .CR wait3() function allows the calling process to obtain status information for specified child processes. .PP The following call: .PP .RS .C "wait3(stat_loc, options, resource_usage);" .RE .PP is equivalent to the call: .RS .PP .C "waitpid((pid_t)-1, stat_loc, options);" .PP .RE except that on successful completion, if the .IR resource_usage argument to .CR wait3() is not a null pointer, the .CR rusage structure that the third argument points to is filled in for the child process identified by the return value. .SH RETURN VALUE See waitpid(). .SH ERRORS In addition to the error conditions specified on .CR waitpid() , under the following conditions, .CR wait3() may fail and set .CR errno to: .RS .TP 25 [ECHILD] The calling process has no existing unwaited\-for child processes, or if the set of processes specified by the argument .IR pid can never be in the states specified by the argument .IR options . .SH SEE ALSO exec, exit(), fork(), pause(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .TA .TH wait3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-EXTENSIONS .sp 2 .SH SYNOPSIS .C "pid_t wait3(int *stat_loc, int options, int *reserved);" .SH DESCRIPTION The .CR wait3() system call is equivalent to .CR waitpid() with the value of .IR pid equal to zero. The third parameter to .CR wait3() , .IR reserved , is currently unused and must always be a null pointer. .SH ERRORS If .CR wait3() fails, .CR errno is set to one of the following values. .RS .TP 25 [EINVAL] The .IR options argument to .CR waitpid() or .CR wait3() is invalid. .TP [EINVAL] .CR wait3() was passed a nonnull pointer value for its third argument. .RE .SH WARNINGS The behavior of .CR wait3() is affected if the .CR SIGCLD signal is set to .CR SIG_IGN . See the WARNINGS section of .IR signal (5). Signal handlers that cause system calls to be restarted can affect the EINTR condition described above (see .CR bsdproc(2) , sigaction(2) , and .CR sigvector(2) ). .SH AUTHOR .CR wait3() was developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO Exit conditions ($?) in sh(1); exec(2), exit(2), fork(2), pause(2), ptrace(2), signal(5). .\" .\" index@\f4wait3()\f1 \- wait for child process to change state@@@\f3wait3(2)\f1 .\" index@\f1wait for child process to change state@@@\f3wait3(2)\f1 .\" index@\f1child process to change state, wait for@@@\f3wait3(2)\f1 .\" index@\f1process, child, wait to change state@@@\f3wait3(2)\f1 .\" index@\f1change state, wait for child process to@@@\f3wait3(2)\f1 .\" .\" toc@\f3wait3(2)\f1:\0\0\f4wait3()\f1@@@wait for child process to change state .\" .\" fileset_database@wait3.2 .\" $Header: waitid.2,v 76.2 95/07/07 15:05:50 ssa Exp $ .TA w .TH waitid 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME waitid \- wait for child process to change state .SH SYNOPSIS .PP .C "#include " .PP .C "int waitid(idtype_t idtype, id_t id, siginfo_t *infop, int options);" .PP .SH DESCRIPTION The .CR waitid() function suspends the calling process until one of its children changes state. It records the current state of a child in the structure pointed to by .IR infop . If a child process changed state prior to the call to .CR waitid() , .CR waitid() returns immediately. .PP The .IR idtype and .IR id arguments are used to specify which children .CR waitid() will wait for. .PP If .IR idtype is .CR P_PID , .CR waitid() will wait for the child with a process ID equal to .IR (pid_t)pid . .PP If .IR idtype is .CR P_PGID , .CR waitid() will wait for any child with a process group ID equal to .IR (pid_t)pid . .PP If .IR idtype is .CR P_ALL , .CR waitid() will wait for any children and id is ignored. .PP The .IR options argument is used to specify which state changes .CR waitid() will wait for. It is formed by OR\-ing together one or more of the following flags: .RS .TP 25 .C WEXITED Wait for processes that have exited. .TP .C WSTOPPED Status will be returned for any child that has stopped upon receipt of a signal. .TP .C WCONTINUED Status will be returned for any child that was stopped and has been continued. .TP .C WNOHANG Return immediately if there are no children to wait for. .TP .C WNOWAIT Keep the process whose status is returned in .IR infop in a waitable state. This will not affect the state of the process; the process may be waited for again after this call completes. .RE .PP The .IR infop argument must point to a .CR siginfo_t structure. If .CR waitid() returns because a child process was found that satisfied the conditions indicated by the arguments .IR idtype and .IR options , then the structure pointed to by .IR infop will be filled in by the system with the status of the process. The .IR si_signo member will always be equal to .CR SIGCHLD . .SH RETURN VALUE If .CR waitid() returns due to the change of state of one of its children, 0 is returned. Otherwise, \(mi1 is returned and .CR errno is set to indicate the error. .SH ERRORS The .CR waitid() function will fail if: .RS .TP 15 [ECHILD] The calling process has no existing unwaited\-for child processes. .TP [EINTR] The .CR waitid() function was interrupted due to the receipt of a signal by the calling process. .TP [EINVAL] An invalid value was specified for .IR options , or .IR idtype and .IR id specify an invalid set of processes. .RE .SH SEE ALSO exec, exit(), wait(), . .SH CHANGE HISTORY First released in Issue 4, Version 2. .\" .\" index@\f4waitid()\f1 \- wait for child process to change state@@@\f3waitid(2)\f1 .\" index@\f1wait for child process to change state@@@\f3waitid(2)\f1 .\" index@\f1child process, wait to change state@@@\f3waitid(2)\f1 .\" index@\f1process, child, wait to change state@@@\f3waitid(2)\f1 .\" index@\f1change state, wait for child process to@@@\f3waitid(2)\f1 .\" .\" toc@\f3waitid(2)\f1:\0\0\f4waitid()\f1@@@wait for child process to change state .\" .\" fileset_database@waitid.2 .\" $Header: wait.2,v 76.1 95/07/07 15:04:01 ssa Exp $ .TA w .TH wait 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wait, waitpid \- wait for child process to stop or terminate .SH SYNOPSIS .\" OH .PP .C "#include OH" .C "#include " .PP .C "pid_t wait(int *stat_loc);" .PP .C "pid_t waitpid(pid_t pid, int *stat_loc, int options);" .SH DESCRIPTION The .CR wait() and .CR waitpid() functions allow the calling process to obtain status information pertaining to one of its child processes. Various options permit status information to be obtained for child processes that have terminated or stopped. If status information is available for two or more child processes, the order in which their status is reported is unspecified. .PP The .CR wait() function will suspend execution of the calling process until status information for one of its terminated child processes is available, or until delivery of a signal whose action is either to execute a signal\-catching function or to terminate the process. If status information is available prior to the call to .CR wait() , return will be immediate. .PP The .IR waitpid() function will behave identically to .CR wait() , if the .IR pid argument is .IR ( pid_t )\(mi1 and the .IR options argument is 0. Otherwise, its behaviour will be modified by the values of the .IR pid and .IR options arguments. .PP The .IR pid argument specifies a set of child processes for which status is requested. The .CR waitpid() function will only return the status of a child process from this set: .RS .TP 3 \(bu If .IR pid is equal to .RI ( pid_t )\(mi1, status is requested for any child process. In this respect, .CR waitpid() is then equivalent to .CR wait() . .TP 3 \(bu If pid is greater than 0, it specifies the process ID of a single child process for which status is requested. .TP 3 \(bu If pid is 0, status is requested for any child process whose process group ID is equal to that of the calling process. .TP 3 \(bu If .IR pid is less than .RI ( pid_t )\(mi1, status is requested for any child process whose process group ID is equal to the absolute value of .IR pid . .PP The .IR options argument is constructed from the bitwise\-inclusive OR of zero or more of the following flags, defined in the header .CR . .\" UX .RS .TP 25 .C WCONTINUED The .CR waitpid() function will report the status of any continued child process specified by .IR pid whose status has not been reported since it continued from a job control stop. .\" ? .TP .C WNOHANG The .IR waitpid() function will not suspend execution of the calling process if status is not immediately available for one of the child processes specified by .IR pid . .TP .C WUNTRACED The status of any child processes specified by .IR pid that are stopped, and whose status has not yet been reported since they stopped, will also be reported to the requesting process. .\" UX .RE .PP If the calling process has .CR SA_NOCLDWAIT set or has .CR SIGCHLD set to .CR SIG_IGN , and the process has no unwaited for children that were transformed into zombie processes, it will block until all of its children terminate, and .CR wait() and .CR waitpid() will fail and set .CR errno to .CR ECHILD . .\" ? .PP If .CR wait() or .CR waitpid() return because the status of a child process is available, these functions will return a value equal to the process ID of the child process. In this case, if the value of the argument .IR stat_loc is not a null pointer, information will be stored in the location pointed to by .IR stat_loc . If and only if the status returned is from a terminated child process that returned 0 from .CR main() or passed 0 as the status argument to .CR _exit() or .CR exit() , the value stored at the location pointed to by .IR stat_loc will be 0. Regardless of its value, this information may be interpreted using the following macros, which are defined in .CR and evaluate to integral expressions; the .IR stat_val argument is the integer value pointed to by .IR stat_loc . .RS .TP 25 .C WIFEXITED(stat_val) Evaluates to a non-zero value if status was returned for a child process that terminated normally. .C WEXITSTATUS(stat_val) If the value of .CR WIFEXITED(stat_val) is non\-zero, this macro evaluates to the low\-order 8 bits of the .IR status argument that the child process passed to .CR _exit() or .CR exit() , or the value the child process returned from .CR main() . .TP .C WIFSIGNALED(stat_val) Evaluates to non\-zero value if status was returned for a child process that terminated due to the receipt of a signal that was not caught (see .RI < signal.h >). .TP .C WTERMSIG(stat_val) If the value of .CR WIFSIGNALED(stat_val) is non\-zero, this macro evaluates to the number of the signal that caused the termination of the child process. .CR WIFSTOPPED(stat_val) Evaluates to a non\-zero value if status was returned for a child process that is currently stopped. .TP .C WSTOPSIG(stat_val) If the value of .CR WIFSTOPPED(stat_val) is non\-zero, this macro evaluates to the number of the signal that caused the child process to stop. .\" UX .TP .C WIFCONTINUED(stat_val) .\" ! Evaluates to a non\-zero value if status was returned for a child process that has continued from a job control stop. .\" ? .RE .PP If the information pointed to by .IR stat_loc was stored by a call to .CR waitpid() that specified the .CR WUNTRACED .\" UX !auX flag and did not specify the .CR WCONTINUED flag, exactly one of the macros .CR WIFEXITED(*stat_loc) , .CR WIFSIGNALED(*stat_loc) , and .CR WIFSTOPPED(*stat_loc) will evaluate to a non\-zero value. .PP If the information pointed to by .IR stat_loc was stored .\" UX by a call to .CR waitpid() that specified the .CR WUNTRACED .\" ! and .CR WCONTINUED flags, exactly one of the macros .CR WIFEXITED(*stat_loc) , .CR WIFSIGNALED(*stat_loc) , .\" UX .CR WIFSTOPPED(*stat_loc) , .\" ! and .CR WIFCONTINUED .CR (*stat_loc) will evaluate to a non\-zero value. .PP If the information pointed to by .IR stat_loc was stored by a call to .CR waitpid() that did not specify the .\" UX .CR WUNTRACED .\" ! or .CR WCONTINUED flags, or by a call to the .CR wait() function, exactly one of the macros .CR WIFEXITED(*stat_loc) and .CR WIFSIGNALED(*stat_loc) will evaluate to a non\-zero value. .PP If the information pointed to by .IR stat_loc was stored by a call to .CR waitpid() that did not specify the .\" UX .CR WUNTRACED flag .\" ! and specified the .CR WCONTINUED flag, by a call to the .CR wait() function, exactly one of the macros .CR WIFEXITED(*stat_loc) , .\" UX .CR WIFSIGNALED(*stat_loc) , . \" ! and .CR WIFCONTINUED(*stat_loc) will evaluate to a non\-zero value. .PP There may be additional implementation\-dependent circumstances under which .CR wait() or .CR waitpid() report status. This will not occur unless the calling process or one of its child processes explicitly makes use of a non\-standard extension. In these cases the interpretation of the reported status is implementation\-dependent. .PP If a parent process terminates without waiting for all of its child processes to terminate, the remaining child processes will be assigned a new parent process ID corresponding to an implementation\-dependent system process. .SH RETURN VALUE If .CR wait() or .CR waitpid() returns because the status of a child process is available, these functions will return a value equal to the process ID of the child process for which status is reported. If .CR wait() or .CR waitpid() returns due to the delivery of a signal to the calling process, \(mi1 will be returned and .CR errno will be set to .CR EINTR . If .CR waitpid() was invoked with .CR WNOHANG set in .IR options , it has at least one child process specified by .IR pid for which status is not available, and status is not available for any process specified by .IR pid , 0 will be returned. Otherwise, .IR (pid_t) \(mi1 will be returned, and .CR errno will be set to indicate the error. .SH ERRORS The .CR wait() function will fail if: .TP 15 [ECHILD] The calling process has no existing unwaited\-for child processes. .TP [EINTR] The function was interrupted by a signal. The value of the location pointed to by .IR stat_loc is undefined. .RE .PP The .CR waitpid() function will fail if: .TP 15 [ECHILD] The process or process group specified by .IR pid does not exist or is not a child of the calling process. .TP [EINTR] The function was interrupted by a signal. The value of the location pointed to by .IR stat_loc is undefined. .TP [EINVAL] The .IR options argument is not valid. .SH SEE ALSO exec, exit(), fork(), wait3(), waitid(), , . .SH CHANGE HISTORY First released in Issue 1. .PP Derived from Issue 1 of the SVID. .SH Issue 4 .PP The following change is incorporated for alignment with the ISO POSIX-1 standard: .RS .TP 3 \(bu Text describing conditions under which 0 will be returned when .CR WNOHUNG is set in .IR options is added to the RETURN VALUE section. .RE .PP Other changes are incorporated as follows: .RS .TP 3 \(bu The header .CR is now marked as optional (OH); this header need not be included on XSI\-conformant systems. .TP 3 \(bu Error return values throughout the DESCRIPTION and RETURN VALUE sections are changed to show the proper casting (that is, .RI ( pid_t )\(mi1. .TP 3 \(bu The words "If the implementation supports job control" are removed from the description of .CR WUNTRACED . This is because job control is defined as mandatory for Issue 4 conforming implementations. .RE .PP .SH Issue 4, Version 2 .PP The following changes are incorporated in the DESCRIPTION for X/OPEN UNIX conformance: .RS .TP 3 \(bu The .CR WCONTINUED .IR options flag and the .CR WIFCONTINUED(stat_val) macro are added. .TP 3 \(bu Text following the list of options flags explains the implications of setting the .CR SA_NOCLDWAIT signal flag, or setting .CR SIGCHILD to .CR SIG_IGN . .TP 3 \(bu Text following the list of macros, which explains what macros return non\-zero values in certain cases, is expanded and the value of the .CR WCONTINUED flag on the previous call to .CR waitpid() is taken into account. .TA .TH wait 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH NAME wait(), waitpid() \- wait for child or traced process to stop or terminate .SH DESCRIPTION .SH wait() If a parent process terminates without waiting for its child processes to terminate, the parent process ID of each child process is set to 1. This means the initialization process inherits the child processes. .RS .TP 25 .C WCOREDUMP(*stat_loc) If the value of .CR WIFSIGNALED(*stat_loc) is nonzero, this macro evaluates to a nonzero value if a "core image" was produced (see .IR signal (5)). .RE .SH waitpid() .RS .TP 25 .C WNOWAIT Keep the process whose status is returned in .IR *stat_loc in a waitable state. The process may be waited for again with identical results, provided the state of the process doesn't change in the interim. .TP .C WUNTRACED If and only if this flag is set, .CR waitpid() or .CR wait3() returns information on child or attached processes that are stopped but not traced (with .CR ptrace(2) ) because they received a .CR SIGTTIN , .CR SIGTTOU , .CR SIGTSTP , or .CR SIGSTOP signal, and whose status has not yet been reported. Regardless of this flag, status is returned for child or attached processes that have terminated or are stopped and traced and whose status has not yet been reported. .SH Notes Earlier HP\-UX versions documented the bit encodings of the status returned by .CR wait() rather than the macros .CR WCOREDUMP , .CR WEXITSTATUS , .CR WIFEXITED , .CR WIFSIGNALED , .CR WIFSTOPPED , .CR WSTOPSIG , and .CR WTERMSIG . Applications using those bit encodings will continue to work correctly. However, new applications should use the macros for maximum portability. .PP In earlier HP\-UX versions, the macros .CR WIFEXITED , .CR WIFSIGNALED , and .CR WIFSTOPPED have the same definitions as the correspondingly named macros in the BSD 4.3 and earlier systems. Existing applications that depend on these definitions will continue to work correctly. However, if the application is recompiled, the feature test macro .CR_BSD must be turned on for the compilation so that the old definitions of these macros are obtained. New definitions of these macros are in effect by default. The only difference between the old and new definitions is the type of the argument. Type union .CR wait is used in the BSD definitions while type .IR int is used in the default definitions. .SH ERRORS If .CR wait() or .CR waitpid() fails, .CR errno is set to one of the following values. .RS .TP 25 .C [EACCES] The calling process of .CR waitpid() does not have read permission to the .IR pid . .TP .C [EFAULT] .IR stat_loc points to an illegal address. The reliable detection of this error is implementation\-dependent. .RE .SH WARNINGS The behavior of .CR wait() and .CR waitpid() is affected if the .CR SIGCLD signal is set to .CR SIG_IGN . See the WARNINGS section of .IR signal (5). Signal handlers that cause system calls to be restarted can affect the .CR EINTR condition described above (see .IR bsdproc (2), .IR sigaction (2), and .IR sigvector (2)). .SH AUTHOR wait(), waitpid(), and wait3() were developed by HP, AT&T, and the University of California, Berkeley. .SH SEE ALSO Exit conditions ($?) in sh(1); exec(2), exit(2), fork(2), pause(2), ptrace(2), signal(5). .SH STANDARDS CONFORMANCE wait(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1 .PP waitpid(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1 .\" .\" index@\f4wait()\f1 \- wait for child or traced process to stop or terminate@@@\f3wait(2)\f1 .\" index@\f4waitpid()\f1 \- wait for child or traced process to stop or terminate@@@\f3wait(2)\f1 .\" index@\f1child process to stop or terminate, wait for@@@\f3wait(2)\f1 .\" index@\f1process to stop or terminate, wait for child@@@\f3wait(2)\f1 .\" index@\f1stop, wait for child process to@@@\f3wait(2)\f1 .\" index@\f1terminate, wait for child process to@@@\f3wait(2)\f1 .\" .\" links@wait.2 waitpid.2 .\" .\" toc@\f3wait(2)\f1:\0\0\f4wait()\f1, \f4waitpid()\f1@@@wait for child process to stop or terminate .\" toc@\f4waitpid()\f1:\0\0wait for child process to stop or terminate@@@see \f3wait(2)\f1 .\" $Header: write.2,v 78.1 96/02/12 14:22:01 ssa Exp $ .TA w .TH write 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME write, writev \- write on a file .SH SYNOPSIS .C "#include " .PP .C "ssize_t write(int fildes, const void *buf, size_t nbyte);" .\" UX .PP .C "#include " .PP .C "ssize_t writev(int fildes, const struct iovec *iov, int iovcnt);" .\" ? .SH DESCRIPTION The .CR write() function attempts to write .IR nbyte bytes from the buffer pointed to by .IR buf to the file associated with the open file descriptor, .IR fildes . .PP If .IR nbyte is 0, .CR write() will return 0 and have no other results if the file is a regular file; otherwise, the results are unspecified. .PP On a regular file or other file capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file offset associated with .IR fildes . Before successful return from .CR write() , the file offset is incremented by the number of bytes actually written. On a regular file, if this incremented file offset is greater than the length of the file, the length of the file will be set to this file offset. .\" EX If the .CR O_SYNC flag of the file status flags is set and .IR fildes refers to a regular file, a successful .CR write() does not return until the data is delivered to the underlying hardware. .\" ? On a file not capable of seeking, writing always takes place starting at the current position. The value of a file offset associated with such a device is undefined. .PP If the .CR O_APPEND flag of the file status flags is set, the file offset will be set to the end of the file prior to each write and no intervening file modification operation will occur between changing the file offset and the write operation. .PP If a .CR write() requests that more bytes be written .\" EX than there is room for (for example, the .IR ulimit or the physical end of a medium), only as many bytes as there is room for will be written. For example, suppose there is space for 20 bytes more in a file before reaching a limit. A write of 512 bytes will return 20. The next write of a non\-zero number of bytes will give a failure return (except as noted .\" UX below) .\" ! and the implementation will generate a .CR SIGXFSZ signal for the process. .\" ? .PP If .CR write() is interrupted by a signal before it writes any data, it will return \(mi1 with .CR errno set to .CR EINTR . .\" FIPS .PP If .CR write() is interrupted by a signal after it successfully writes some data, it will return the number of bytes written. .\" ? .PP If the value of .IR nbyte is greater than .CR {SSIZE_MAX} , the result is implementation\-dependent. .PP After a .CR write() to a regular file has successfully returned: .RS .TP 3 \(bu Any successful .CR read() from each byte position in the file that was modified by that write will return the data specified by the .CR write() for that position until such byte positions are again modified. .TP 3 \(bu Any subsequent successful .CR write() to the same byte position in the file will overwrite that file data. .RE .PP Write requests to a pipe or FIFO will be handled the same as a regular file with the following exceptions: .RS .TP 3 \(bu There is no file offset associated with a pipe, hence each write request will append to the end of the pipe. .TP 3 \(bu Write requests of .CR {PIPE_BUF} bytes or less will not be interleaved with data from other processes doing writes on the same pipe. Writes of greater than .CR {PIPE_BUF} bytes may have data interleaved, on arbitrary boundaries, with writes by other processes, whether or not the .CR O_NONBLOCK flag of the file status flags is set. .TP 3 \(bu If the .CR O_NONBLOCK flag is clear, a write request may cause the process to block, but on normal completion it will return .IR nbyte . .TP 3 \(bu If the .CR O_NONBLOCK flag is set, .CR write() requests will be handled differently, in the following ways: .RS .TP 3 \- The .CR write() function will not block the process. .TP \- A write request for .CR {PIPE_BUF} or fewer bytes will have the following effect: If there is sufficient space available in the pipe, .CR write() will transfer all the data and return the number of bytes requested. Otherwise, .CR write() will transfer no data and return \(mi1 with .CR errno set to .CR EAGAIN . .TP \- A write request for more than .CR {PIPE_BUF} bytes will case one of the following: .RS .TP 3 a. When at least one byte can be written, transfer what it can and return the number of bytes written. When all data previously written to the pipe is read, it will transfer at least .CR {PIPE_BUF} bytes. .TP b. When no data can be written, transfer no data and return \(mi1 with .CR errno set to .CR EAGAIN . .RE .RE .PP When attempting to write to a file descriptor (other than a pipe or FIFO) that supports non\-blocking writes and cannot accept the data immediately: .RS .TP 3 \(bu If the .CR O_NONBLOCK flag is clear, .CR write() will block until the data can be accepted. .TP \(bu If the .CR O_NONBLOCK flag is set, .CR write() will not block the process. If some data can be written without blocking the process, .CR write() will write what it can and return the number of bytes written. Otherwise, it will return \(mi1 and .CR errno will be set to .CR EAGAIN . .RE .PP Upon successful completion, where .CR nbyte is greater than 0, .CR write() will mark for update the .IR st_ctime and .IR st_mtime fields of the file, and if the file is a regular file, the .CR S_ISUID and .CR S_ISGID bits of the file mode may be cleared. .PP .\" UX If .IR fildes refers to a STREAM, the operation of .CR write() is determined by the values of the minimum and maximum .IR nbyte range ("packet size") accepted by the STREAM. These values are determined by the topmost STREAM module. If .IR nbyte falls within the packet size range, .IR nbyte bytes will be written. If .IR nbyte does not fall within the range and the minimum packet size value is 0, .CR write() will break the buffer into maximum packet size segments prior to sending the data downstream (the last segment may contain less than the maximum packet size). If .IR nbyte does not fall within the range and the minimum value is non\-zero, .CR write() will fail with .CR errno set to .CR ERANGE . Writing a zero\-length buffer ( .IR nbyte is 0) to a STREAMS device sends 0 bytes with 0 returned. However, writing a zero\-length buffer to a STREAMS\-based pipe or FIFO sends no message and 0 is returned. The process may issue .CR I_SWROPT .CR ioctl() to enable zero\-length messages to be sent across the pipe or FIFO. .PP When writing to a STREAM, data messages are created with a priority band of 0. When writing to a STREAM that is not a pipe or FIFO: .RS .TP 3 \(bu If .C O_NONBLOCK is clear, and the .CR STREAM cannot accept data (the .CR STREAM write queue is full due to internal flow control conditions), .CR write() will block until data can be accepted. .TP \(bu If .CR O_NONBLOCK is set and the .CR STREAM cannot accept data, .CR write() will return \(mi1 and set .CR errno to .CR [EAGAIN] . .TP \(bu If .CR O_NONBLOCK is set and part of the buffer has been written while a condition in which the .CR STREAM cannot accept additional data occurs, .CR write() will terminate and return the number of bytes written. .RE .PP In addition, .CR write() and .CR writev() will fail if the .CR STREAM head had processed an asynchronous error before the call. In this case, the value of .CR errno does not reflect the result of .CR write() or .CR writev() but reflects the prior error. .PP The .CR writev() function is equivalent to .CR write() , but gathers the output data from the .IR iovcnt buffers specified by the members of the .IR iov array: .IR iov [ 0 ] , .IR iov [ 1 ] , ..., .IR iov [ iovcnt \(mi1]. .IR iovcnt is valid if greater than 0 and less than or equal to .CR {IOV_MAX} , defined in .CR . .PP Each .IR iovec entry specifies the base address and length of an area in memory from which data should be written. The .CR writev() function will always write a complete area before proceeding to the next. .PP If .IR fildes refers to a regular file and all of the .IR iov_len members in the array pointed to by .IR iov are 0, .CR writev() will return 0 and have no other effect. For other file types, the behaviour is unspecified. .PP If the sum of the .IR iov_len values is greater than .CR SSIZE_MAX , the operation fails and no data is transferred. .\" ? .SH RETURN VALUE Upon successful completion, .CR write() will return the number of bytes actually written to the file associated with .IR fildes . This number will never be greater than .IR nbyte . Otherwise, \(mi1 is returned and .CR errno is set to indicate the error. .PP .\" UX Upon successful completion, .CR writev() returns the number of bytes actually written. Otherwise, it returns a value of \(mi1, the file-pointer remains unchanged, and .CR errno is set to indicate an error. .\" ? .SH ERRORS .\" UX The .CR write() and writev() functions will fail if: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor and the process would be delayed in the .CR write() operation. .TP [EBADF] The .IR fildes argument is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write a file that exceeds the .\" EX implementation\-dependent maximum file size .\" ! or the process' file size limit. .\" ? .TP [EINTR] The write operation was terminated due to the receipt of a signal, and no data was transferred. .\" UX .TP [EIO] A physical I\/O error has occurred. .\" ? .TP [EIO] The process is a member of a background process group attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking .CR SIGTTOU and the process group of the process is orphaned. This error may also be returned under implementation\-dependent conditions. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for .\" UX reading by any process, or that only has one end open. A .CR SIGPIPE signal will also be sent to the process. .TP .\" UX [ERANGE] The transfer request size was outside the range supported by the .CR STREAMS file associated with .IR fildes . .RE .PP The .CR writev() function will fail if: .RS .TP 15 [EINVAL] The sum of the .IR iov_len values in the .IR iov array would overflow an .IR ssize_t . .\" ? .RE .PP .\" UX The .CR write() and .CR writev() functions may fail if: .\" UX .RS .TP 15 [EINVAL] The .CR STREAM or multiplexer referenced by .IR fildes is linked (directly or indirectly) downstream from a multiplexer. .\" ? .\" EX .TP [ENXIO] A request was made of a non\-existent device, or the request was outside the capabilities of the device. .\" ? .\" UX .TP [ENXIO] A hangup occurred on the .CR STREAM being written to. .\" ? .RE .PP A write to a .CR STREAMS file may fail if an error message has been received at the .CR STREAM head. In this case, .CR errno is set to the value included in the error message. .PP The .CR writev() function may fail and set .CR errno to: .RS .TP 15 [EINVAL] The .IR iovcnt argument was less than or equal to 0, or greater than .CR {IOV_MAX} . .\" ? .RE .SH SEE ALSO chmod(), creat(), dup(), fcntl(), getrlimit(), lseek(), open(), pipe(), ulimit(), , , , . .SH CHANGE HISTORY First released in Issue 1. .PP Derived from Issue 1 of the SVID. .SH Issue 4 .PP The following changes are incorporated for alignment with the ISO POSIX\-1 standard: .RS .TP 3 \(bu The type of the argument .IR buf is changed from .I char * .R to .I const void* .R, and the type of the argument .IR byte is changed from .IR unsigned .IR size_t . .TP \(bu The DESCRIPTION section is changed: .RS .TP 3 \- to indicate that writing at end\-of\-file is atomic .TP \- to identify that .CR {SSIZE_MAX} is now used to determine the maximum value of .IR nbyte .TP \- to indicate the consequences of activities after a call to the .CR write() function .TP \- To improve clarity, the text describing operations on pipes or FIFOs when .CR O_NONBLOCK is set is restructured. .RE .RE .PP Other changes are incorporated as follows: .RS .TP 3 \(bu The header .CR is added to the SYNOPSIS section. .TP 3 \(bu Reference to .IR ulimit in the DESCRIPTION section is marked as an extension. .TP 3 \(bu Reference to the process' file size limit and the .IR ulimit() function are marked as extensions in the description of the .CR EFBIG error. .TP 3 \(bu The .CR ENXIO error is marked as an extension. .TP 3 \(bu The APPLICATION USAGE section is removed. .TP 3 \(bu The description of .CR EINTR is amended. .RE .SH Issue 4, Version 2 .PP The following changes are incorporated for X\/OPEN UNIX conformance: .RS .TP 3 \(bu The .CR writev() function is added to the SYNOPSIS. .TP \(bu The DESCRIPTION is updated to describe the reading of data from .CR STREAMS files, an operational description of the .CR writev() function is included, and a statement is added indicating that .CR SIGXFSZ will be generated if an attempted write operation would cause the maximum file size to be exceeded. .TP \(bu The RETURN VALUE section is updated to describe values returned by the .CR writev() function. .TP 3 \(bu The ERRORS section has been restructured to describe errors that apply to both .CR write() and writev() apart from those that apply to .CR writev() specifically. The .CR EIO , .CR ERANGE , and .CR EINVAL errors are also added. .\" $Header: write.2,v 78.1 96/02/12 14:22:01 ssa Exp $ .TA w .TH write 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH DESCRIPTION The .CR iovec structure of the .IR iov elements is defined as follows: .nf .IP .C "struct iovec {" .C " caddr_t iov_base;" .C " int iov_len;" .C "};" .fi .PP For ordinary files, if the .CR O_DSYNC file status flag is set, the write does not return until both the file data and the file attributes required to retrieve the data are physically updated. If the .CR O_SYNC flag is set, the behavior is identical to that for .CR O_DSYNC , with the addition that all file attributes changed by the write operation (including access time, modification time and status change time) are also physically updated prior to returning to the calling process. .PP For block special files, if the .CR O_DSYNC or the .CR O_SYNC flag is set, the write does not return until the data is physically updated. How the data reaches the physical media is implementation- and hardware-dependent. .PP A write to an ordinary file is prevented if enforcement-mode file and record locking is set, and another process owns a lock on the segment of the file being written: .IP If .CR O_NDELAY or .CR O_NONBLOCK is set, the write returns \(mi1 and sets .CR errno to .CR EAGAIN . .IP If .CR O_NDELAY and .CR O_NONBLOCK are clear, the write does not complete until the blocking record lock is removed. .PP If the file being written is a pipe (or FIFO), the system-dependent maximum number of bytes that it can store is given by .CR PIPSIZ (defined in .CR ). The minimum value of .CR PIPSIZ on any HP-UX system is 8192. When writing a pipe, the following conditions apply: .RS .PP If the .CR O_NDELAY or .CR O_NONBLOCK file status flag is set: .IP If .I nbyte is less than or equal to .CR PIPSIZ and sufficient room exists in the pipe or .CR FIFO , the .CR write() succeeds and returns the number of bytes written; .IP If .I nbyte is less than or equal to .CR PIPSIZ but insufficient room exists in the pipe or .CR FIFO , the .CR write() returns having written nothing. If .CR O_NONBLOCK is set, .CR -1 is returned and .CR errno is set to [EAGAIN]. If .CR O_NDELAY is set, .CR 0 is returned. .IP If .I nbyte is greater than .CR PIPSIZ and the pipe or FIFO is full, the write returns having written nothing. If .CR O_NONBLOCK is set, .CR -1 is returned and .CR errno is set to [EAGAIN]. If .CR O_NDELAY is set, .CR 0 is returned. .IP If .I nbyte is greater than .CR PIPSIZ , and some room exists in the pipe or FIFO, as much data as fits in the pipe or FIFO is written, and .CR write() returns the number of bytes actually written, an amount less than the number of bytes requested. .PP If the .CR O_NDELAY and .CR O_NONBLOCK file status flags are clear: .IP The .CR write() always executes correctly (blocking as necessary), and returns the number of bytes written. .RE .PP For character special devices, if the .CR stopio() call was used on the same device after it was opened (see .IR stopio (2)), .CR write() returns .CR -1 , sets .CR errno to [EBADF], and issues the .CR SIGHUP signal to the process. .PP .CR write() clears the .CR potential and .CR granted privilege vectors on the file. .PP If the write is performed by any user other than the owner or a user who has appropriate privileges, .CR write() clears the set-user-ID, set-group-ID, and sticky bits on all nondirectory files. If the write is performed by the owner or a user who has appropriate privileges, the behavior is file-system dependent. In some file systems, the write clears the set-user-ID, set-group-ID, and sticky bits on a nondirectory file. In other file systems, the write does not clear these bits on a nondirectory file. .PP For directories, .CR write() does not clear the set-user-ID, set-group-ID, and sticky bits. .SH ERRORS If .CR write() or .CR writev() fails, the file offset remains unchanged and .CR errno is set to one of the following values. .RS .TP 15 [EAGAIN] Enforcement-mode file and record locking was set, .CR O_NDELAY was set, and there was a blocking record lock. .TP [EDEADLK] A resource deadlock would occur as a result of this operation (see .IR lockf (2) and .IR fcntl (2)). .TP [EDQUOT] User's disk quota block limit has been reached for this file system. .TP [EFBIG] The file is a regular file and .IR nbyte is greater than zero and the starting position is greater than or equal to the offset maximum established in the open file description associated with .IR fildes . .TP [ENOLCK] The system record lock table is full, preventing the write from sleeping until the blocking record lock is removed. .TP [ENOSPC] Not enough space on the file system. The process does not possess the .CR limit effective privilege to override this restriction. .RE .PP If .CR writev() fails, the file offset remains unchanged and .CR errno is set to one of the following values: .RS .TP 15 [EFAULT] .I iov_base or .I iov points outside of the allocated address space. The reliable detection of this error is implementation dependent. .TP [EINVAL] One of the .I iov_len values in the .I iov array is negative. .RE .PP If .CR write() or .CR writev() fails, the file offset is updated to reflect the amount of data transferred and .CR errno is set to one of the following values. .RS .TP 15 [EFAULT] .I buf points outside the process's allocated address space. The reliable detection of this error is implementation dependent. .RE .SH EXAMPLES Assuming a process opened a file for writing, the following call to .CR write() attempts to write .I mybufsize bytes to the file from the buffer to which .IR mybuf points. .nf .IP .C "#include " .IP .C "int fildes;" .C "size_t mybufsize; .C "ssize_t nbytes;" .C "char *mybuf = ""aeiou and sometimes y"";" .C "mybufsize = (size_t)strlen (mybuf);" .C "nbytes = write (fildes, (void *)mybuf, mybufsize);" .fi .SH WARNINGS Check .IR signal (5) for the appropriateness of signal references on systems that support .CR sigvector () (see .IR sigvector (2)). .CR sigvector () can affect the behavior described on this page. .PP Character special devices, and raw disks in particular, apply constraints on how .CR write() can be used. See specific Section 7 manual entries for details on particular devices. .SH AUTHOR .CR write() was developed by HP, AT&T, the University of California, Berkeley, and SecureWare Inc. .SH SEE ALSO mkfs(1M) creat(2), dup(2), fcntl(2), lockf(2), lseek(2), open(2), pipe(2), sigvector(2), stopio(2) ulimit(2), ustat(2), signal(5). .SH STANDARDS CONFORMANCE .CR write() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.4" .\" .\" index@\f4write()\f1 \- write contiguous data to a file@@@\f3write(2)\f1 .\" index@\f4writev()\f1 \- write noncontiguous data to a file@@@\f3write(2)\f1 .\" index@\f1data to a file, write@@@\f3write(2)\f1 .\" index@\f1file, write data@@@\f3write(2)\f1 .\" toc@\f3write(2)\f1:\0\0\f4write()\f1, \f4writev()\f1@@@write data to a file .\" toc@\f4writev()\f1:\0\0write data to a file@@@see \f3write(2)\f1 .\" .\" links@write.2 writev.2 .\" $Header: write.2,v 78.1 96/02/12 14:22:01 ssa Exp $ .TA w .TH write 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME write, writev \- write on a file .SH SYNOPSIS .C "#include " .PP .C "ssize_t write(int fildes, const void *buf, size_t nbyte);" .\" UX .PP .C "#include " .PP .C "ssize_t writev(int fildes, const struct iovec *iov, int iovcnt);" .\" ? .SH DESCRIPTION The .CR write() function attempts to write .IR nbyte bytes from the buffer pointed to by .IR buf to the file associated with the open file descriptor, .IR fildes . .PP If .IR nbyte is 0, .CR write() will return 0 and have no other results if the file is a regular file; otherwise, the results are unspecified. .PP On a regular file or other file capable of seeking, the actual writing of data proceeds from the position in the file indicated by the file offset associated with .IR fildes . Before successful return from .CR write() , the file offset is incremented by the number of bytes actually written. On a regular file, if this incremented file offset is greater than the length of the file, the length of the file will be set to this file offset. .\" EX If the .CR O_SYNC flag of the file status flags is set and .IR fildes refers to a regular file, a successful .CR write() does not return until the data is delivered to the underlying hardware. .\" ? On a file not capable of seeking, writing always takes place starting at the current position. The value of a file offset associated with such a device is undefined. .PP If the .CR O_APPEND flag of the file status flags is set, the file offset will be set to the end of the file prior to each write and no intervening file modification operation will occur between changing the file offset and the write operation. .PP If a .CR write() requests that more bytes be written .\" EX than there is room for (for example, the .IR ulimit or the physical end of a medium), only as many bytes as there is room for will be written. For example, suppose there is space for 20 bytes more in a file before reaching a limit. A write of 512 bytes will return 20. The next write of a non\-zero number of bytes will give a failure return (except as noted .\" UX below) .\" ! and the implementation will generate a .CR SIGXFSZ signal for the process. .\" ? .PP If .CR write() is interrupted by a signal before it writes any data, it will return \(mi1 with .CR errno set to .CR EINTR . .\" FIPS .PP If .CR write() is interrupted by a signal after it successfully writes some data, it will return the number of bytes written. .\" ? .PP If the value of .IR nbyte is greater than .CR {SSIZE_MAX} , the result is implementation\-dependent. .PP After a .CR write() to a regular file has successfully returned: .RS .TP 3 \(bu Any successful .CR read() from each byte position in the file that was modified by that write will return the data specified by the .CR write() for that position until such byte positions are again modified. .TP 3 \(bu Any subsequent successful .CR write() to the same byte position in the file will overwrite that file data. .RE .PP Write requests to a pipe or FIFO will be handled the same as a regular file with the following exceptions: .RS .TP 3 \(bu There is no file offset associated with a pipe, hence each write request will append to the end of the pipe. .TP 3 \(bu Write requests of .CR {PIPE_BUF} bytes or less will not be interleaved with data from other processes doing writes on the same pipe. Writes of greater than .CR {PIPE_BUF} bytes may have data interleaved, on arbitrary boundaries, with writes by other processes, whether or not the .CR O_NONBLOCK flag of the file status flags is set. .TP 3 \(bu If the .CR O_NONBLOCK flag is clear, a write request may cause the process to block, but on normal completion it will return .IR nbyte . .TP 3 \(bu If the .CR O_NONBLOCK flag is set, .CR write() requests will be handled differently, in the following ways: .RS .TP 3 \- The .CR write() function will not block the process. .TP \- A write request for .CR {PIPE_BUF} or fewer bytes will have the following effect: If there is sufficient space available in the pipe, .CR write() will transfer all the data and return the number of bytes requested. Otherwise, .CR write() will transfer no data and return \(mi1 with .CR errno set to .CR EAGAIN . .TP \- A write request for more than .CR {PIPE_BUF} bytes will case one of the following: .RS .TP 3 a. When at least one byte can be written, transfer what it can and return the number of bytes written. When all data previously written to the pipe is read, it will transfer at least .CR {PIPE_BUF} bytes. .TP b. When no data can be written, transfer no data and return \(mi1 with .CR errno set to .CR EAGAIN . .RE .RE .PP When attempting to write to a file descriptor (other than a pipe or FIFO) that supports non\-blocking writes and cannot accept the data immediately: .RS .TP 3 \(bu If the .CR O_NONBLOCK flag is clear, .CR write() will block until the data can be accepted. .TP \(bu If the .CR O_NONBLOCK flag is set, .CR write() will not block the process. If some data can be written without blocking the process, .CR write() will write what it can and return the number of bytes written. Otherwise, it will return \(mi1 and .CR errno will be set to .CR EAGAIN . .RE .PP Upon successful completion, where .CR nbyte is greater than 0, .CR write() will mark for update the .IR st_ctime and .IR st_mtime fields of the file, and if the file is a regular file, the .CR S_ISUID and .CR S_ISGID bits of the file mode may be cleared. .PP .\" UX If .IR fildes refers to a STREAM, the operation of .CR write() is determined by the values of the minimum and maximum .IR nbyte range ("packet size") accepted by the STREAM. These values are determined by the topmost STREAM module. If .IR nbyte falls within the packet size range, .IR nbyte bytes will be written. If .IR nbyte does not fall within the range and the minimum packet size value is 0, .CR write() will break the buffer into maximum packet size segments prior to sending the data downstream (the last segment may contain less than the maximum packet size). If .IR nbyte does not fall within the range and the minimum value is non\-zero, .CR write() will fail with .CR errno set to .CR ERANGE . Writing a zero\-length buffer ( .IR nbyte is 0) to a STREAMS device sends 0 bytes with 0 returned. However, writing a zero\-length buffer to a STREAMS\-based pipe or FIFO sends no message and 0 is returned. The process may issue .CR I_SWROPT .CR ioctl() to enable zero\-length messages to be sent across the pipe or FIFO. .PP When writing to a STREAM, data messages are created with a priority band of 0. When writing to a STREAM that is not a pipe or FIFO: .RS .TP 3 \(bu If .C O_NONBLOCK is clear, and the .CR STREAM cannot accept data (the .CR STREAM write queue is full due to internal flow control conditions), .CR write() will block until data can be accepted. .TP \(bu If .CR O_NONBLOCK is set and the .CR STREAM cannot accept data, .CR write() will return \(mi1 and set .CR errno to .CR [EAGAIN] . .TP \(bu If .CR O_NONBLOCK is set and part of the buffer has been written while a condition in which the .CR STREAM cannot accept additional data occurs, .CR write() will terminate and return the number of bytes written. .RE .PP In addition, .CR write() and .CR writev() will fail if the .CR STREAM head had processed an asynchronous error before the call. In this case, the value of .CR errno does not reflect the result of .CR write() or .CR writev() but reflects the prior error. .PP The .CR writev() function is equivalent to .CR write() , but gathers the output data from the .IR iovcnt buffers specified by the members of the .IR iov array: .IR iov [ 0 ] , .IR iov [ 1 ] , ..., .IR iov [ iovcnt \(mi1]. .IR iovcnt is valid if greater than 0 and less than or equal to .CR {IOV_MAX} , defined in .CR . .PP Each .IR iovec entry specifies the base address and length of an area in memory from which data should be written. The .CR writev() function will always write a complete area before proceeding to the next. .PP If .IR fildes refers to a regular file and all of the .IR iov_len members in the array pointed to by .IR iov are 0, .CR writev() will return 0 and have no other effect. For other file types, the behaviour is unspecified. .PP If the sum of the .IR iov_len values is greater than .CR SSIZE_MAX , the operation fails and no data is transferred. .\" ? .SH RETURN VALUE Upon successful completion, .CR write() will return the number of bytes actually written to the file associated with .IR fildes . This number will never be greater than .IR nbyte . Otherwise, \(mi1 is returned and .CR errno is set to indicate the error. .PP .\" UX Upon successful completion, .CR writev() returns the number of bytes actually written. Otherwise, it returns a value of \(mi1, the file-pointer remains unchanged, and .CR errno is set to indicate an error. .\" ? .SH ERRORS .\" UX The .CR write() and writev() functions will fail if: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor and the process would be delayed in the .CR write() operation. .TP [EBADF] The .IR fildes argument is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write a file that exceeds the .\" EX implementation\-dependent maximum file size .\" ! or the process' file size limit. .\" ? .TP [EINTR] The write operation was terminated due to the receipt of a signal, and no data was transferred. .\" UX .TP [EIO] A physical I\/O error has occurred. .\" ? .TP [EIO] The process is a member of a background process group attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking .CR SIGTTOU and the process group of the process is orphaned. This error may also be returned under implementation\-dependent conditions. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for .\" UX reading by any process, or that only has one end open. A .CR SIGPIPE signal will also be sent to the process. .TP .\" UX [ERANGE] The transfer request size was outside the range supported by the .CR STREAMS file associated with .IR fildes . .RE .PP The .CR writev() function will fail if: .RS .TP 15 [EINVAL] The sum of the .IR iov_len values in the .IR iov array would overflow an .IR ssize_t . .\" ? .RE .PP .\" UX The .CR write() and .CR writev() functions may fail if: .\" UX .RS .TP 15 [EINVAL] The .CR STREAM or multiplexer referenced by .IR fildes is linked (directly or indirectly) downstream from a multiplexer. .\" ? .\" EX .TP [ENXIO] A request was made of a non\-existent device, or the request was outside the capabilities of the device. .\" ? .\" UX .TP [ENXIO] A hangup occurred on the .CR STREAM being written to. .\" ? .RE .PP A write to a .CR STREAMS file may fail if an error message has been received at the .CR STREAM head. In this case, .CR errno is set to the value included in the error message. .PP The .CR writev() function may fail and set .CR errno to: .RS .TP 15 [EINVAL] The .IR iovcnt argument was less than or equal to 0, or greater than .CR {IOV_MAX} . .\" ? .RE .SH SEE ALSO chmod(), creat(), dup(), fcntl(), getrlimit(), lseek(), open(), pipe(), ulimit(), , , , . .SH CHANGE HISTORY First released in Issue 1. .PP Derived from Issue 1 of the SVID. .SH Issue 4 .PP The following changes are incorporated for alignment with the ISO POSIX\-1 standard: .RS .TP 3 \(bu The type of the argument .IR buf is changed from .I char * .R to .I const void* .R, and the type of the argument .IR byte is changed from .IR unsigned .IR size_t . .TP \(bu The DESCRIPTION section is changed: .RS .TP 3 \- to indicate that writing at end\-of\-file is atomic .TP \- to identify that .CR {SSIZE_MAX} is now used to determine the maximum value of .IR nbyte .TP \- to indicate the consequences of activities after a call to the .CR write() function .TP \- To improve clarity, the text describing operations on pipes or FIFOs when .CR O_NONBLOCK is set is restructured. .RE .RE .PP Other changes are incorporated as follows: .RS .TP 3 \(bu The header .CR is added to the SYNOPSIS section. .TP 3 \(bu Reference to .IR ulimit in the DESCRIPTION section is marked as an extension. .TP 3 \(bu Reference to the process' file size limit and the .IR ulimit() function are marked as extensions in the description of the .CR EFBIG error. .TP 3 \(bu The .CR ENXIO error is marked as an extension. .TP 3 \(bu The APPLICATION USAGE section is removed. .TP 3 \(bu The description of .CR EINTR is amended. .RE .SH Issue 4, Version 2 .PP The following changes are incorporated for X\/OPEN UNIX conformance: .RS .TP 3 \(bu The .CR writev() function is added to the SYNOPSIS. .TP \(bu The DESCRIPTION is updated to describe the reading of data from .CR STREAMS files, an operational description of the .CR writev() function is included, and a statement is added indicating that .CR SIGXFSZ will be generated if an attempted write operation would cause the maximum file size to be exceeded. .TP \(bu The RETURN VALUE section is updated to describe values returned by the .CR writev() function. .TP 3 \(bu The ERRORS section has been restructured to describe errors that apply to both .CR write() and writev() apart from those that apply to .CR writev() specifically. The .CR EIO , .CR ERANGE , and .CR EINVAL errors are also added. .\" $Header: write.2,v 78.1 96/02/12 14:22:01 ssa Exp $ .TA w .TH write 2 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .ce HP\-UX EXTENSIONS .sp 2 .SH DESCRIPTION The .CR iovec structure of the .IR iov elements is defined as follows: .nf .IP .C "struct iovec {" .C " caddr_t iov_base;" .C " int iov_len;" .C "};" .fi .PP For ordinary files, if the .CR O_DSYNC file status flag is set, the write does not return until both the file data and the file attributes required to retrieve the data are physically updated. If the .CR O_SYNC flag is set, the behavior is identical to that for .CR O_DSYNC , with the addition that all file attributes changed by the write operation (including access time, modification time and status change time) are also physically updated prior to returning to the calling process. .PP For block special files, if the .CR O_DSYNC or the .CR O_SYNC flag is set, the write does not return until the data is physically updated. How the data reaches the physical media is implementation- and hardware-dependent. .PP A write to an ordinary file is prevented if enforcement-mode file and record locking is set, and another process owns a lock on the segment of the file being written: .IP If .CR O_NDELAY or .CR O_NONBLOCK is set, the write returns \(mi1 and sets .CR errno to .CR EAGAIN . .IP If .CR O_NDELAY and .CR O_NONBLOCK are clear, the write does not complete until the blocking record lock is removed. .PP If the file being written is a pipe (or FIFO), the system-dependent maximum number of bytes that it can store is given by .CR PIPSIZ (defined in .CR ). The minimum value of .CR PIPSIZ on any HP-UX system is 8192. When writing a pipe, the following conditions apply: .RS .PP If the .CR O_NDELAY or .CR O_NONBLOCK file status flag is set: .IP If .I nbyte is less than or equal to .CR PIPSIZ and sufficient room exists in the pipe or .CR FIFO , the .CR write() succeeds and returns the number of bytes written; .IP If .I nbyte is less than or equal to .CR PIPSIZ but insufficient room exists in the pipe or .CR FIFO , the .CR write() returns having written nothing. If .CR O_NONBLOCK is set, .CR -1 is returned and .CR errno is set to [EAGAIN]. If .CR O_NDELAY is set, .CR 0 is returned. .IP If .I nbyte is greater than .CR PIPSIZ and the pipe or FIFO is full, the write returns having written nothing. If .CR O_NONBLOCK is set, .CR -1 is returned and .CR errno is set to [EAGAIN]. If .CR O_NDELAY is set, .CR 0 is returned. .IP If .I nbyte is greater than .CR PIPSIZ , and some room exists in the pipe or FIFO, as much data as fits in the pipe or FIFO is written, and .CR write() returns the number of bytes actually written, an amount less than the number of bytes requested. .PP If the .CR O_NDELAY and .CR O_NONBLOCK file status flags are clear: .IP The .CR write() always executes correctly (blocking as necessary), and returns the number of bytes written. .RE .PP For character special devices, if the .CR stopio() call was used on the same device after it was opened (see .IR stopio (2)), .CR write() returns .CR -1 , sets .CR errno to [EBADF], and issues the .CR SIGHUP signal to the process. .PP .CR write() clears the .CR potential and .CR granted privilege vectors on the file. .PP If the write is performed by any user other than the owner or a user who has appropriate privileges, .CR write() clears the set-user-ID, set-group-ID, and sticky bits on all nondirectory files. If the write is performed by the owner or a user who has appropriate privileges, the behavior is file-system dependent. In some file systems, the write clears the set-user-ID, set-group-ID, and sticky bits on a nondirectory file. In other file systems, the write does not clear these bits on a nondirectory file. .PP For directories, .CR write() does not clear the set-user-ID, set-group-ID, and sticky bits. .SH ERRORS If .CR write() or .CR writev() fails, the file offset remains unchanged and .CR errno is set to one of the following values. .RS .TP 15 [EAGAIN] Enforcement-mode file and record locking was set, .CR O_NDELAY was set, and there was a blocking record lock. .TP [EDEADLK] A resource deadlock would occur as a result of this operation (see .IR lockf (2) and .IR fcntl (2)). .TP [EDQUOT] User's disk quota block limit has been reached for this file system. .TP [EFBIG] The file is a regular file and .IR nbyte is greater than zero and the starting position is greater than or equal to the offset maximum established in the open file description associated with .IR fildes . .TP [ENOLCK] The system record lock table is full, preventing the write from sleeping until the blocking record lock is removed. .TP [ENOSPC] Not enough space on the file system. The process does not possess the .CR limit effective privilege to override this restriction. .RE .PP If .CR writev() fails, the file offset remains unchanged and .CR errno is set to one of the following values: .RS .TP 15 [EFAULT] .I iov_base or .I iov points outside of the allocated address space. The reliable detection of this error is implementation dependent. .TP [EINVAL] One of the .I iov_len values in the .I iov array is negative. .RE .PP If .CR write() or .CR writev() fails, the file offset is updated to reflect the amount of data transferred and .CR errno is set to one of the following values. .RS .TP 15 [EFAULT] .I buf points outside the process's allocated address space. The reliable detection of this error is implementation dependent. .RE .SH EXAMPLES Assuming a process opened a file for writing, the following call to .CR write() attempts to write .I mybufsize bytes to the file from the buffer to which .IR mybuf points. .nf .IP .C "#include " .IP .C "int fildes;" .C "size_t mybufsize; .C "ssize_t nbytes;" .C "char *mybuf = ""aeiou and sometimes y"";" .C "mybufsize = (size_t)strlen (mybuf);" .C "nbytes = write (fildes, (void *)mybuf, mybufsize);" .fi .SH WARNINGS Check .IR signal (5) for the appropriateness of signal references on systems that support .CR sigvector () (see .IR sigvector (2)). .CR sigvector () can affect the behavior described on this page. .PP Character special devices, and raw disks in particular, apply constraints on how .CR write() can be used. See specific Section 7 manual entries for details on particular devices. .SH AUTHOR .CR write() was developed by HP, AT&T, the University of California, Berkeley, and SecureWare Inc. .SH SEE ALSO mkfs(1M) creat(2), dup(2), fcntl(2), lockf(2), lseek(2), open(2), pipe(2), sigvector(2), stopio(2) ulimit(2), ustat(2), signal(5). .SH STANDARDS CONFORMANCE .CR write() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.4" .\" .\" index@\f4write()\f1 \- write contiguous data to a file@@@\f3write(2)\f1 .\" index@\f4writev()\f1 \- write noncontiguous data to a file@@@\f3write(2)\f1 .\" index@\f1data to a file, write@@@\f3write(2)\f1 .\" index@\f1file, write data@@@\f3write(2)\f1 .\" toc@\f3write(2)\f1:\0\0\f4write()\f1, \f4writev()\f1@@@write data to a file .\" toc@\f4writev()\f1:\0\0write data to a file@@@see \f3write(2)\f1 .\" .\" links@write.2 writev.2 .\" $Header: nl_tools_16.3x,v 72.2 94/11/30 15:24:00 ssa Exp $ .TA n .TH nl_tools_16 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl_tools_16: ADVANCE(), byte_status(), BYTE_STATUS(), CHARADV(), CHARAT(), c_colwidth(), C_COLWIDTH(), firstof2(), FIRSTof2(), secof2(), SECof2(), WCHAR(), WCHARADV() \- tools to process 16-bit characters .SH SYNOPSIS .C "#include " .PP .C "int firstof2(int c);" .PP .C "int secof2(int c);" .PP .C "int byte_status(int c, int laststatus);" .PP .C int c_colwidth(int c); .PP .C "int FIRSTof2(int c);" .PP .C "int SECof2(int c);" .PP .C "int BYTE_STATUS(int c, int laststatus);" .PP .C "int C_COLWIDTH(int c);" .PP .C "int CHARAT(const char *p);" .PP .C "int ADVANCE(const char *p);" .PP .C "int CHARADV(const char *p);" .PP .C "int WCHAR(wchar_t wc, char *p);" .PP .C "int WCHARADV(wchar_t wc, char *p);" .PP .C "void PCHAR(int c, char *p);" .PP .C "void PCHARADV(int c, char *p);" .SS Remarks All interfaces listed above whose names begin with a capital letter are implemented as macros; the others are functions. .PP These macros and functions are obsolete. See WARNINGS. .SH DESCRIPTION The following macros and functions perform their operations based upon the loaded NLS environment (see .IR setlocale (3C)). .TP 20 .CR FIRSTof2() Takes a byte and returns a nonzero value if it can be the first byte of a two-byte character according to the NLS environment loaded, and zero if it cannot. .TP .CR SECof2() Takes a byte and returns a nonzero value if it can be the second byte of a two-byte character according to the loaded NLS environment, and zero if it cannot. .TP .CR BYTE_STATUS() Returns one of the following values based on the value of the current byte in .I c and the status of the previous byte interpreted in .I laststatus as returned by the last call to .CR BYTE_STATUS() . These are the status values as defined in .CR : .RS .RS .TP 15 .CR ONEBYTE Single-byte character .PD 0 .TP .CR SECOF2 Second byte of two-byte character .TP .CR FIRSTOF2 First byte of two-byte character .RE .RE .PD .IP To validate a two-byte character, both the first and second bytes must be valid. If the value of .I laststatus is .CR FIRSTOF2 but .CR SECof2( c ) returns false, .CI BYTE_STATUS( c , \ laststatus ) returns .CR ONEBYTE . .TP .CR C_COLWIDTH() Takes a byte which is assumed to be either a one-byte character or the first byte of a two-byte character, and returns the number of columns the character would occupy on a terminal display. .IP For the macros .CR BYTE_STATUS() , .CR C_COLWIDTH() , .CR FIRSTof2() , and .CR SEC0of2() , results are undefined for values of .I c less than \(mi1 (EOF) or greater than 255. .TP .CR CHARAT() Takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case, .CR CHARAT() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p . .TP .CR ADVANCE() Advances its pointer argument by the byte width of the character it is pointing at (either one or two bytes). .TP .CR CHARADV() Combines the functions of .CR CHARAT() and .CR ADVANCE() in a single macro. It takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case .CR CHARADV() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p , and advances .I p beyond the last byte of the character. .TP .CR WCHAR() Converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p . .CR WCHAR() returns the .CR wchar_t value .IR wc . .TP .CR WCHARADV() Combines the functions of .CR WCHAR() and .CR ADVANCE() in a single macro. It converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p , then advances .I p past the last byte. .CR WCHARADV() returns the .CR wchar_t value .IR wc . .TP .CR firstof2() .PD 0 .TP .CR secof2() .TP .CR byte_status() .TP .CR c_colwidth() .PD Subroutine versions of the corresponding macros. These functions can be called from languages other than C. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of single and/or multibyte characters. .SH WARNINGS The HP proprietary functions and macros described in this manual entry are .BR OBSOLETE . They are not portable to other vendor's systems, and will not be provided in future HP-UX releases. .PP For maximum portability, use the routines documented in the .IR multibyte (3C) manual entry for multibyte character processing. .PP Other macros listed in this manual entry cannot be used as the first argument to .CR WCHAR() or .CR WCHARADV() . For example, .IP .C "*t++ = *f++" .PP cannot be replaced by .IP .C "WCHARADV(CHARADV (f),t)" .PP Instead, use a method such as .IP .CR "int c; " ...\& " c = CHARADV (f)," .CR "WCHARADV (c,t)" .PP .CR WCHAR() and .CR WCHARADV() may produce a "null effect" warning from .IR lint (1) if not used as part of another expression or as part of a statement. This does not affect the functionality of either macro. .PP Note that .CR WCHAR() and .CR WCHARADV() are not "replace_char" macros. They do not prevent the second byte of a two-byte character from being left dangling if .CR WCHAR() or .CR WCHARADV() overwrite the first byte of the two-byte character with a single-byte character. .PP .CR CHARAT() , .CR ADVANCE() , and .CR CHARADV() do not examine the byte following the location pointed to by the argument to verify its validity as a .CR SECof2 byte. .SH AUTHOR .CR nl_tools_16() was developed by HP. .SH SEE ALSO setlocale(3C), multibyte(3C), wconv(3X), wctype(3X), hpnls(5). .\" .\" index@\f4ADVANCE()\f1 \- advance pointer to next 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARADV()\f1 \- get character and advance pointer to next character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARAT()\f1 \- get value of 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHAR()\f1, \- put 8- or 16-bit character in memory@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHARADV()\f1, \- put character in memory and advance pointer@@@\f3nl_tools_16(3X)\f1 .\" index@\f4byte_status()\f1, \f4BYTE_STATUS()\f1 \- test for valid 1- or 2-byte character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4firstof2()\f1, \f4FIRSTof2()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4secof2()\f1, \f4SECof2()\f1 \- test for valid second byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f1characters, tools to process 16-bit@@@\f3nl_tools_16(3X)\f1 .\" index@\f1process 16-bit characters, tools to@@@\f3nl_tools_16(3X)\f1 .\" index@\f1sixteen-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f116-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f1tools to process 16-bit characters@@@\f3nl_tools_16(3X)\f1 .\" .\" links@nl_tools_16.3x ADVANCE.3x .\" links@nl_tools_16.3x BYTE_STATUS.3x .\" links@nl_tools_16.3x CHARADV.3x .\" links@nl_tools_16.3x CHARAT.3x .\" links@nl_tools_16.3x FIRSTof2.3x .\" links@nl_tools_16.3x SECof2.3x .\" links@nl_tools_16.3x WCHAR.3x .\" links@nl_tools_16.3x WCHARADV.3x .\" links@nl_tools_16.3x byte_status.3x .\" links@nl_tools_16.3x c_colwidth.3x .\" links@nl_tools_16.3x firstof2.3x .\" links@nl_tools_16.3x secof2.3x .\" .\" toc@\f3nl_tools_16(3X)\f1:\0\0\f4ADVANCE()\f1, \f4byte_status()\f1, \f4BYTE_STATUS()\f1, \f4CHARADV()\f1,\n\f4CHARAT()\f1, \f4C_COLWIDTH()\f1, \f4c_colwidth()\f1, \f4firstof2()\f1, \f4FIRSTof2()\f1,\n\f4secof2()\f1, \f4SECof2()\f1, \f4WCHAR()\f1, \f4WCHARADV()\f1@@@tools to process 16-bit characters .\" toc@\f4ADVANCE()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4byte_status()\f1, \f4BYTE_STATUS()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARAT()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4firstof2()\f1, \f4FIRSTof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4secof2()\f1, \f4SECof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHAR()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "ApplicationShell" "Intrinsics Classes" .XX "ApplicationShell" .SH "Name" .Na ApplicationShell widget class \- main shell for an application. .Nz .\" .SH "Synopsis" .IP "\s-1\f(HBPublic Headers:\fP\s0" 18n 0 \fI\fP .br \fI\fP .IP "\s-1\f(HBPrivate Header:\fP\s0" 18n 0 \fI\fP .IP "\s-1\f(HBClass\ Name:\fP\s0" 18n 0 ApplicationShell .IP "\s-1\f(HBClass\ Hierarchy:\fP\s0" 18n 0 'nh Core \(-> Composite \(-> Shell \(-> WMShell \(-> VendorShell \(-> TopLevelShell \(-> ApplicationShell .IP "\s-1\f(HBClass Pointer:\fP\s0" 18n 0 \f(CWapplicationShellWidgetClass\fP .IP "\s-1\f(HBInstantiation:\fP\s0" 18n 0 .ft CW .ps 9 \f(CIwidget\fP = XtAppInitialize(...) .br \fRor\fP .br \f(CIwidget\fP = XtAppCreateShell(\f(CIapp_name\fP,\f(CIapp_class\fP, .br applicationShellWidgetClass, ...) .br .ps 10 .ft R .IP "\s-1\f(HBFunctions/Macros:\fP\s0" 18n 0 \f(CWXtAppCreateShell(\^)\fP, \f(CWXtVaAppCreateShell(\^)\fP, .br \f(CWXtIsApplicationShell(\^)\fP .\" .SH "Description" An ApplicationShell is the normal top-level window for an application. It does not have a parent and is at the root of the widget tree. An application should have only one ApplicationShell, unless the application is implemented as multiple logical applications. Normally, an application will use TopLevelShell widgets for other top-level windows. An ApplicationShell is returned by the call to \f(CWXtVaAppInitialize(\^)\fP. It can also be created explicitly with a call to \f(CWXtVaAppCreateShell(\^)\fP. .\" .SH "New Resources" ApplicationShell defines the following resources: .br .sp 1 .in 0 .KS .TS expand linesize(2) tab(@); l l l l l lp7 lp7 lp7 lp7 lp7. \fRName@Class@Type@Default@Access\fP .sp .2 .XX "XtNargc" \f(CWXtNargc\fP@\f(CWXtCArgc\fP@\f(CWint\fP@\f(CW0\fP@\f(CWCSG\fP .XX "XtNargv" \f(CWXtNargv\fP@\f(CWXtCArgv\fP@\f(CWString *\fP@\f(CWNULL\fP@\f(CWCSG\fP .sp .2 .TE .KE .in .sp 1 .IP \f(CWXtNargc\fP 5n Number of arguments in \f(CWXtNargv\fP. .IP \f(CWXtNargv\fP 5n List of command-line arguments used to start the application. This is the standard C \f(CWargv\fP, passed in the call to \f(CWXtAppInitialize()\fP. It is used to set the WM_COMMAND property for this window. .\" .Nd 5 .SH "Inherited Resources" ApplicationShell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. .Nd 3 .sp 1 .in 0 .KS .TS H tab(@), linesize(2); lp7 lp7 lp7 lp7 lp6w(1.25i) lp6w(1i) lp6w(1.25i) lp6w(1i). \fRResource@Inherited From@Resource@Inherited From\fP .sp 2p .Th \f(CWXtNaccelerators\fP@\f(CWCore\fP@\f(CWXtNmaxAspectX\fP@\f(CWWMShell\fP \f(CWXtNallowShellResize\fP@\f(CWShell\fP@\f(CWXtNmaxAspectY\fP@\f(CWWMShell\fP \f(CWXtNancestorSensitive\fP@\f(CWCore\fP@\f(CWXtNmaxHeight\fP@\f(CWWMShell\fP \f(CWXtNbackground\fP@\f(CWCore\fP@\f(CWXtNmaxWidth\fP@\f(CWWMShell\fP \f(CWXtNbackgroundPixmap\fP@\f(CWCore\fP@\f(CWXtNminAspectX\fP@\f(CWWMShell\fP \f(CWXtNbaseHeight\fP@\f(CWWMShell\fP@\f(CWXtNminAspectY\fP@\f(CWWMShell\fP \f(CWXtNbaseWidth\fP@\f(CWWMShell\fP@\f(CWXtNminHeight\fP@\f(CWWMShell\fP \f(CWXtNborderColor\fP@\f(CWCore\fP@\f(CWXtNminWidth\fP@\f(CWWMShell\fP \f(CWXtNborderPixmap\fP@\f(CWCore\fP@\f(CWXtNmwmDecorations\fP@\f(CWVendorShell\fP \f(CWXtNborderWidth\fP@\f(CWCore\fP@\f(CWXtNmwmFunctions\fP@\f(CWVendorShell\fP \f(CWXtNchildren\fP@\f(CWComposite\fP@\f(CWXtNmwmInputMode\fP@\f(CWVendorShell\fP \f(CWXtNcolormap\fP@\f(CWCore\fP@\f(CWXtNmwmMenu\fP@\f(CWVendorShell\fP \f(CWXtNcreatePopupChild-\fP@\f(CWShell\fP@\f(CWXtNnumChildren\fP@\f(CWComposite\fP .sp -2p \0\0\f(CWProc\fP \f(CWXtNdefaultFontList\fP@\f(CWVendorShell\fP@\f(CWXtNoverrideRedirect\fP@\f(CWShell\fP \f(CWXtNdeleteResponse\fP@\f(CWVendorShell\fP@\f(CWXtNpopdownCallback\fP@\f(CWShell\fP \f(CWXtNdepth\fP@\f(CWCore\fP@\f(CWXtNpopupCallback\fP@\f(CWShell\fP \f(CWXtNdestroyCallback\fP@\f(CWCore\fP@\f(CWXtNsaveUnder\fP@\f(CWShell\fP \f(CWXtNgeometry\fP@\f(CWShell\fP@\f(CWXtNscreen\fP@\f(CWCore\fP \f(CWXtNheight\fP@\f(CWCore\fP@\f(CWXtNsensitive\fP@\f(CWCore\fP \f(CWXtNheightInc\fP@\f(CWWMShell\fP@\f(CWXtNshellUnitType\fP@\f(CWVendorShell\fP \f(CWXtNiconic\fP@\f(CWTopLevelShell\fP@\f(CWXtNtitle\fP@\f(CWWMShell\fP \f(CWXtNiconMask\fP@\f(CWWMShell\fP@\f(CWXtNtitleEncoding\fP@\f(CWWMShell\fP \f(CWXtNiconName\fP@\f(CWTopLevelShell\fP@\f(CWXtNtransient\fP@\f(CWWMShell\fP \f(CWXtNiconNameEncoding\fP@\f(CWTopLevelShell\fP@\f(CWXtNtranslations\fP@\f(CWCore\fP \f(CWXtNiconPixmap\fP@\f(CWWMShell\fP@\f(CWXtNuseAsyncGeometry\fP@\f(CWVendorShell\fP \f(CWXtNiconWindow\fP@\f(CWWMShell\fP@\f(CWXtNvisual\fP@\f(CWShell\fP \f(CWXtNiconX\fP@\f(CWWMShell\fP@\f(CWXtNwaitForWm\fP@\f(CWWMShell\fP \f(CWXtNiconY\fP@\f(CWWMShell\fP@\f(CWXtNwidth\fP@\f(CWCore\fP \f(CWXtNinitialResources-@\f(CWCore\fP@\f(CWXtNwidthInc\fP@\f(CWWMShell\fP .sp -2p \0\0Persistent \f(CWXtNinitialState\fP@\f(CWWMShell\fP@\f(CWXtNwindowGroup\fP@\f(CWWMShell\fP \f(CWXtNinput\fP@\f(CWWMShell\fP@\f(CWXtNwinGravity\fP@\f(CWWMShell\fP \f(CWXtNinsertPosition\fP@\f(CWComposite\fP@\f(CWXtNwmTimeout\fP@\f(CWWMShell\fP \f(CWXtNkeyboardFocusPolicy\fP@\f(CWVendorShell\fP@\f(CWXtNx\fP@\f(CWCore\fP \f(CWXtNmappedWhenManaged\fP@\f(CWCore\fP@\f(CWXtNy\fP@\f(CWCore\fP .sp 2p .TE .KE .in .sp 1 .\" .Nd 10 .SH "Class Structure" The ApplicationShell class structure contains only an extension field. Its declaration is similar to those of the other shells: .Ps .ta 5n 2.5i typedef struct { XtPointer extension; /* pointer to extension record */ } ApplicationShellClassPart; typedef struct _ApplicationShellClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ShellClassPart shell_class; WMShellClassPart wm_shell_class; VendorShellClassPart vendor_shell_class; TopLevelShellClassPart top_level_shell_class; ApplicationShellClassPart application_shell_class; } ApplicationShellClassRec; .Pe There are no extensions currently defined for this class, and the \f(CWextension\fP field should be \f(CWNULL\fP. .\" .SH "Instance Structure" The ApplicationShell instance structure contains at least the following fields (which need not be in this order): .Ps .ta 5n li typedef struct { char *class; XrmClass xrm_class; int argc; char **argv; } ApplicationShellPart; typedef struct { CorePart core; CompositePart composite; ShellPart shell; WMShellPart wm; VendorShellPart vendor; TopLevelShellPart topLevel; ApplicationShellPart application; } ApplicationShellRec, *ApplicationShellWidget; .Pe .\" .SH "See Also" \s-1\fIShell\fR\s+1\*(s3, \s-1\fITopLevelShell\fR\s+1\*(s3. .\"last line comment .\" $Header: nl_tools_16.3x,v 72.2 94/11/30 15:24:00 ssa Exp $ .TA n .TH nl_tools_16 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl_tools_16: ADVANCE(), byte_status(), BYTE_STATUS(), CHARADV(), CHARAT(), c_colwidth(), C_COLWIDTH(), firstof2(), FIRSTof2(), secof2(), SECof2(), WCHAR(), WCHARADV() \- tools to process 16-bit characters .SH SYNOPSIS .C "#include " .PP .C "int firstof2(int c);" .PP .C "int secof2(int c);" .PP .C "int byte_status(int c, int laststatus);" .PP .C int c_colwidth(int c); .PP .C "int FIRSTof2(int c);" .PP .C "int SECof2(int c);" .PP .C "int BYTE_STATUS(int c, int laststatus);" .PP .C "int C_COLWIDTH(int c);" .PP .C "int CHARAT(const char *p);" .PP .C "int ADVANCE(const char *p);" .PP .C "int CHARADV(const char *p);" .PP .C "int WCHAR(wchar_t wc, char *p);" .PP .C "int WCHARADV(wchar_t wc, char *p);" .PP .C "void PCHAR(int c, char *p);" .PP .C "void PCHARADV(int c, char *p);" .SS Remarks All interfaces listed above whose names begin with a capital letter are implemented as macros; the others are functions. .PP These macros and functions are obsolete. See WARNINGS. .SH DESCRIPTION The following macros and functions perform their operations based upon the loaded NLS environment (see .IR setlocale (3C)). .TP 20 .CR FIRSTof2() Takes a byte and returns a nonzero value if it can be the first byte of a two-byte character according to the NLS environment loaded, and zero if it cannot. .TP .CR SECof2() Takes a byte and returns a nonzero value if it can be the second byte of a two-byte character according to the loaded NLS environment, and zero if it cannot. .TP .CR BYTE_STATUS() Returns one of the following values based on the value of the current byte in .I c and the status of the previous byte interpreted in .I laststatus as returned by the last call to .CR BYTE_STATUS() . These are the status values as defined in .CR : .RS .RS .TP 15 .CR ONEBYTE Single-byte character .PD 0 .TP .CR SECOF2 Second byte of two-byte character .TP .CR FIRSTOF2 First byte of two-byte character .RE .RE .PD .IP To validate a two-byte character, both the first and second bytes must be valid. If the value of .I laststatus is .CR FIRSTOF2 but .CR SECof2( c ) returns false, .CI BYTE_STATUS( c , \ laststatus ) returns .CR ONEBYTE . .TP .CR C_COLWIDTH() Takes a byte which is assumed to be either a one-byte character or the first byte of a two-byte character, and returns the number of columns the character would occupy on a terminal display. .IP For the macros .CR BYTE_STATUS() , .CR C_COLWIDTH() , .CR FIRSTof2() , and .CR SEC0of2() , results are undefined for values of .I c less than \(mi1 (EOF) or greater than 255. .TP .CR CHARAT() Takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case, .CR CHARAT() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p . .TP .CR ADVANCE() Advances its pointer argument by the byte width of the character it is pointing at (either one or two bytes). .TP .CR CHARADV() Combines the functions of .CR CHARAT() and .CR ADVANCE() in a single macro. It takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case .CR CHARADV() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p , and advances .I p beyond the last byte of the character. .TP .CR WCHAR() Converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p . .CR WCHAR() returns the .CR wchar_t value .IR wc . .TP .CR WCHARADV() Combines the functions of .CR WCHAR() and .CR ADVANCE() in a single macro. It converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p , then advances .I p past the last byte. .CR WCHARADV() returns the .CR wchar_t value .IR wc . .TP .CR firstof2() .PD 0 .TP .CR secof2() .TP .CR byte_status() .TP .CR c_colwidth() .PD Subroutine versions of the corresponding macros. These functions can be called from languages other than C. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of single and/or multibyte characters. .SH WARNINGS The HP proprietary functions and macros described in this manual entry are .BR OBSOLETE . They are not portable to other vendor's systems, and will not be provided in future HP-UX releases. .PP For maximum portability, use the routines documented in the .IR multibyte (3C) manual entry for multibyte character processing. .PP Other macros listed in this manual entry cannot be used as the first argument to .CR WCHAR() or .CR WCHARADV() . For example, .IP .C "*t++ = *f++" .PP cannot be replaced by .IP .C "WCHARADV(CHARADV (f),t)" .PP Instead, use a method such as .IP .CR "int c; " ...\& " c = CHARADV (f)," .CR "WCHARADV (c,t)" .PP .CR WCHAR() and .CR WCHARADV() may produce a "null effect" warning from .IR lint (1) if not used as part of another expression or as part of a statement. This does not affect the functionality of either macro. .PP Note that .CR WCHAR() and .CR WCHARADV() are not "replace_char" macros. They do not prevent the second byte of a two-byte character from being left dangling if .CR WCHAR() or .CR WCHARADV() overwrite the first byte of the two-byte character with a single-byte character. .PP .CR CHARAT() , .CR ADVANCE() , and .CR CHARADV() do not examine the byte following the location pointed to by the argument to verify its validity as a .CR SECof2 byte. .SH AUTHOR .CR nl_tools_16() was developed by HP. .SH SEE ALSO setlocale(3C), multibyte(3C), wconv(3X), wctype(3X), hpnls(5). .\" .\" index@\f4ADVANCE()\f1 \- advance pointer to next 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARADV()\f1 \- get character and advance pointer to next character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARAT()\f1 \- get value of 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHAR()\f1, \- put 8- or 16-bit character in memory@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHARADV()\f1, \- put character in memory and advance pointer@@@\f3nl_tools_16(3X)\f1 .\" index@\f4byte_status()\f1, \f4BYTE_STATUS()\f1 \- test for valid 1- or 2-byte character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4firstof2()\f1, \f4FIRSTof2()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4secof2()\f1, \f4SECof2()\f1 \- test for valid second byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f1characters, tools to process 16-bit@@@\f3nl_tools_16(3X)\f1 .\" index@\f1process 16-bit characters, tools to@@@\f3nl_tools_16(3X)\f1 .\" index@\f1sixteen-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f116-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f1tools to process 16-bit characters@@@\f3nl_tools_16(3X)\f1 .\" .\" links@nl_tools_16.3x ADVANCE.3x .\" links@nl_tools_16.3x BYTE_STATUS.3x .\" links@nl_tools_16.3x CHARADV.3x .\" links@nl_tools_16.3x CHARAT.3x .\" links@nl_tools_16.3x FIRSTof2.3x .\" links@nl_tools_16.3x SECof2.3x .\" links@nl_tools_16.3x WCHAR.3x .\" links@nl_tools_16.3x WCHARADV.3x .\" links@nl_tools_16.3x byte_status.3x .\" links@nl_tools_16.3x c_colwidth.3x .\" links@nl_tools_16.3x firstof2.3x .\" links@nl_tools_16.3x secof2.3x .\" .\" toc@\f3nl_tools_16(3X)\f1:\0\0\f4ADVANCE()\f1, \f4byte_status()\f1, \f4BYTE_STATUS()\f1, \f4CHARADV()\f1,\n\f4CHARAT()\f1, \f4C_COLWIDTH()\f1, \f4c_colwidth()\f1, \f4firstof2()\f1, \f4FIRSTof2()\f1,\n\f4secof2()\f1, \f4SECof2()\f1, \f4WCHAR()\f1, \f4WCHARADV()\f1@@@tools to process 16-bit characters .\" toc@\f4ADVANCE()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4byte_status()\f1, \f4BYTE_STATUS()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARAT()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4firstof2()\f1, \f4FIRSTof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4secof2()\f1, \f4SECof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHAR()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" $Header: nl_tools_16.3x,v 72.2 94/11/30 15:24:00 ssa Exp $ .TA n .TH nl_tools_16 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl_tools_16: ADVANCE(), byte_status(), BYTE_STATUS(), CHARADV(), CHARAT(), c_colwidth(), C_COLWIDTH(), firstof2(), FIRSTof2(), secof2(), SECof2(), WCHAR(), WCHARADV() \- tools to process 16-bit characters .SH SYNOPSIS .C "#include " .PP .C "int firstof2(int c);" .PP .C "int secof2(int c);" .PP .C "int byte_status(int c, int laststatus);" .PP .C int c_colwidth(int c); .PP .C "int FIRSTof2(int c);" .PP .C "int SECof2(int c);" .PP .C "int BYTE_STATUS(int c, int laststatus);" .PP .C "int C_COLWIDTH(int c);" .PP .C "int CHARAT(const char *p);" .PP .C "int ADVANCE(const char *p);" .PP .C "int CHARADV(const char *p);" .PP .C "int WCHAR(wchar_t wc, char *p);" .PP .C "int WCHARADV(wchar_t wc, char *p);" .PP .C "void PCHAR(int c, char *p);" .PP .C "void PCHARADV(int c, char *p);" .SS Remarks All interfaces listed above whose names begin with a capital letter are implemented as macros; the others are functions. .PP These macros and functions are obsolete. See WARNINGS. .SH DESCRIPTION The following macros and functions perform their operations based upon the loaded NLS environment (see .IR setlocale (3C)). .TP 20 .CR FIRSTof2() Takes a byte and returns a nonzero value if it can be the first byte of a two-byte character according to the NLS environment loaded, and zero if it cannot. .TP .CR SECof2() Takes a byte and returns a nonzero value if it can be the second byte of a two-byte character according to the loaded NLS environment, and zero if it cannot. .TP .CR BYTE_STATUS() Returns one of the following values based on the value of the current byte in .I c and the status of the previous byte interpreted in .I laststatus as returned by the last call to .CR BYTE_STATUS() . These are the status values as defined in .CR : .RS .RS .TP 15 .CR ONEBYTE Single-byte character .PD 0 .TP .CR SECOF2 Second byte of two-byte character .TP .CR FIRSTOF2 First byte of two-byte character .RE .RE .PD .IP To validate a two-byte character, both the first and second bytes must be valid. If the value of .I laststatus is .CR FIRSTOF2 but .CR SECof2( c ) returns false, .CI BYTE_STATUS( c , \ laststatus ) returns .CR ONEBYTE . .TP .CR C_COLWIDTH() Takes a byte which is assumed to be either a one-byte character or the first byte of a two-byte character, and returns the number of columns the character would occupy on a terminal display. .IP For the macros .CR BYTE_STATUS() , .CR C_COLWIDTH() , .CR FIRSTof2() , and .CR SEC0of2() , results are undefined for values of .I c less than \(mi1 (EOF) or greater than 255. .TP .CR CHARAT() Takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case, .CR CHARAT() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p . .TP .CR ADVANCE() Advances its pointer argument by the byte width of the character it is pointing at (either one or two bytes). .TP .CR CHARADV() Combines the functions of .CR CHARAT() and .CR ADVANCE() in a single macro. It takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case .CR CHARADV() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p , and advances .I p beyond the last byte of the character. .TP .CR WCHAR() Converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p . .CR WCHAR() returns the .CR wchar_t value .IR wc . .TP .CR WCHARADV() Combines the functions of .CR WCHAR() and .CR ADVANCE() in a single macro. It converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p , then advances .I p past the last byte. .CR WCHARADV() returns the .CR wchar_t value .IR wc . .TP .CR firstof2() .PD 0 .TP .CR secof2() .TP .CR byte_status() .TP .CR c_colwidth() .PD Subroutine versions of the corresponding macros. These functions can be called from languages other than C. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of single and/or multibyte characters. .SH WARNINGS The HP proprietary functions and macros described in this manual entry are .BR OBSOLETE . They are not portable to other vendor's systems, and will not be provided in future HP-UX releases. .PP For maximum portability, use the routines documented in the .IR multibyte (3C) manual entry for multibyte character processing. .PP Other macros listed in this manual entry cannot be used as the first argument to .CR WCHAR() or .CR WCHARADV() . For example, .IP .C "*t++ = *f++" .PP cannot be replaced by .IP .C "WCHARADV(CHARADV (f),t)" .PP Instead, use a method such as .IP .CR "int c; " ...\& " c = CHARADV (f)," .CR "WCHARADV (c,t)" .PP .CR WCHAR() and .CR WCHARADV() may produce a "null effect" warning from .IR lint (1) if not used as part of another expression or as part of a statement. This does not affect the functionality of either macro. .PP Note that .CR WCHAR() and .CR WCHARADV() are not "replace_char" macros. They do not prevent the second byte of a two-byte character from being left dangling if .CR WCHAR() or .CR WCHARADV() overwrite the first byte of the two-byte character with a single-byte character. .PP .CR CHARAT() , .CR ADVANCE() , and .CR CHARADV() do not examine the byte following the location pointed to by the argument to verify its validity as a .CR SECof2 byte. .SH AUTHOR .CR nl_tools_16() was developed by HP. .SH SEE ALSO setlocale(3C), multibyte(3C), wconv(3X), wctype(3X), hpnls(5). .\" .\" index@\f4ADVANCE()\f1 \- advance pointer to next 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARADV()\f1 \- get character and advance pointer to next character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARAT()\f1 \- get value of 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHAR()\f1, \- put 8- or 16-bit character in memory@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHARADV()\f1, \- put character in memory and advance pointer@@@\f3nl_tools_16(3X)\f1 .\" index@\f4byte_status()\f1, \f4BYTE_STATUS()\f1 \- test for valid 1- or 2-byte character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4firstof2()\f1, \f4FIRSTof2()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4secof2()\f1, \f4SECof2()\f1 \- test for valid second byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f1characters, tools to process 16-bit@@@\f3nl_tools_16(3X)\f1 .\" index@\f1process 16-bit characters, tools to@@@\f3nl_tools_16(3X)\f1 .\" index@\f1sixteen-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f116-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f1tools to process 16-bit characters@@@\f3nl_tools_16(3X)\f1 .\" .\" links@nl_tools_16.3x ADVANCE.3x .\" links@nl_tools_16.3x BYTE_STATUS.3x .\" links@nl_tools_16.3x CHARADV.3x .\" links@nl_tools_16.3x CHARAT.3x .\" links@nl_tools_16.3x FIRSTof2.3x .\" links@nl_tools_16.3x SECof2.3x .\" links@nl_tools_16.3x WCHAR.3x .\" links@nl_tools_16.3x WCHARADV.3x .\" links@nl_tools_16.3x byte_status.3x .\" links@nl_tools_16.3x c_colwidth.3x .\" links@nl_tools_16.3x firstof2.3x .\" links@nl_tools_16.3x secof2.3x .\" .\" toc@\f3nl_tools_16(3X)\f1:\0\0\f4ADVANCE()\f1, \f4byte_status()\f1, \f4BYTE_STATUS()\f1, \f4CHARADV()\f1,\n\f4CHARAT()\f1, \f4C_COLWIDTH()\f1, \f4c_colwidth()\f1, \f4firstof2()\f1, \f4FIRSTof2()\f1,\n\f4secof2()\f1, \f4SECof2()\f1, \f4WCHAR()\f1, \f4WCHARADV()\f1@@@tools to process 16-bit characters .\" toc@\f4ADVANCE()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4byte_status()\f1, \f4BYTE_STATUS()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARAT()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4firstof2()\f1, \f4FIRSTof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4secof2()\f1, \f4SECof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHAR()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" $Header: nl_tools_16.3x,v 72.2 94/11/30 15:24:00 ssa Exp $ .TA n .TH nl_tools_16 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl_tools_16: ADVANCE(), byte_status(), BYTE_STATUS(), CHARADV(), CHARAT(), c_colwidth(), C_COLWIDTH(), firstof2(), FIRSTof2(), secof2(), SECof2(), WCHAR(), WCHARADV() \- tools to process 16-bit characters .SH SYNOPSIS .C "#include " .PP .C "int firstof2(int c);" .PP .C "int secof2(int c);" .PP .C "int byte_status(int c, int laststatus);" .PP .C int c_colwidth(int c); .PP .C "int FIRSTof2(int c);" .PP .C "int SECof2(int c);" .PP .C "int BYTE_STATUS(int c, int laststatus);" .PP .C "int C_COLWIDTH(int c);" .PP .C "int CHARAT(const char *p);" .PP .C "int ADVANCE(const char *p);" .PP .C "int CHARADV(const char *p);" .PP .C "int WCHAR(wchar_t wc, char *p);" .PP .C "int WCHARADV(wchar_t wc, char *p);" .PP .C "void PCHAR(int c, char *p);" .PP .C "void PCHARADV(int c, char *p);" .SS Remarks All interfaces listed above whose names begin with a capital letter are implemented as macros; the others are functions. .PP These macros and functions are obsolete. See WARNINGS. .SH DESCRIPTION The following macros and functions perform their operations based upon the loaded NLS environment (see .IR setlocale (3C)). .TP 20 .CR FIRSTof2() Takes a byte and returns a nonzero value if it can be the first byte of a two-byte character according to the NLS environment loaded, and zero if it cannot. .TP .CR SECof2() Takes a byte and returns a nonzero value if it can be the second byte of a two-byte character according to the loaded NLS environment, and zero if it cannot. .TP .CR BYTE_STATUS() Returns one of the following values based on the value of the current byte in .I c and the status of the previous byte interpreted in .I laststatus as returned by the last call to .CR BYTE_STATUS() . These are the status values as defined in .CR : .RS .RS .TP 15 .CR ONEBYTE Single-byte character .PD 0 .TP .CR SECOF2 Second byte of two-byte character .TP .CR FIRSTOF2 First byte of two-byte character .RE .RE .PD .IP To validate a two-byte character, both the first and second bytes must be valid. If the value of .I laststatus is .CR FIRSTOF2 but .CR SECof2( c ) returns false, .CI BYTE_STATUS( c , \ laststatus ) returns .CR ONEBYTE . .TP .CR C_COLWIDTH() Takes a byte which is assumed to be either a one-byte character or the first byte of a two-byte character, and returns the number of columns the character would occupy on a terminal display. .IP For the macros .CR BYTE_STATUS() , .CR C_COLWIDTH() , .CR FIRSTof2() , and .CR SEC0of2() , results are undefined for values of .I c less than \(mi1 (EOF) or greater than 255. .TP .CR CHARAT() Takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case, .CR CHARAT() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p . .TP .CR ADVANCE() Advances its pointer argument by the byte width of the character it is pointing at (either one or two bytes). .TP .CR CHARADV() Combines the functions of .CR CHARAT() and .CR ADVANCE() in a single macro. It takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case .CR CHARADV() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p , and advances .I p beyond the last byte of the character. .TP .CR WCHAR() Converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p . .CR WCHAR() returns the .CR wchar_t value .IR wc . .TP .CR WCHARADV() Combines the functions of .CR WCHAR() and .CR ADVANCE() in a single macro. It converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p , then advances .I p past the last byte. .CR WCHARADV() returns the .CR wchar_t value .IR wc . .TP .CR firstof2() .PD 0 .TP .CR secof2() .TP .CR byte_status() .TP .CR c_colwidth() .PD Subroutine versions of the corresponding macros. These functions can be called from languages other than C. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of single and/or multibyte characters. .SH WARNINGS The HP proprietary functions and macros described in this manual entry are .BR OBSOLETE . They are not portable to other vendor's systems, and will not be provided in future HP-UX releases. .PP For maximum portability, use the routines documented in the .IR multibyte (3C) manual entry for multibyte character processing. .PP Other macros listed in this manual entry cannot be used as the first argument to .CR WCHAR() or .CR WCHARADV() . For example, .IP .C "*t++ = *f++" .PP cannot be replaced by .IP .C "WCHARADV(CHARADV (f),t)" .PP Instead, use a method such as .IP .CR "int c; " ...\& " c = CHARADV (f)," .CR "WCHARADV (c,t)" .PP .CR WCHAR() and .CR WCHARADV() may produce a "null effect" warning from .IR lint (1) if not used as part of another expression or as part of a statement. This does not affect the functionality of either macro. .PP Note that .CR WCHAR() and .CR WCHARADV() are not "replace_char" macros. They do not prevent the second byte of a two-byte character from being left dangling if .CR WCHAR() or .CR WCHARADV() overwrite the first byte of the two-byte character with a single-byte character. .PP .CR CHARAT() , .CR ADVANCE() , and .CR CHARADV() do not examine the byte following the location pointed to by the argument to verify its validity as a .CR SECof2 byte. .SH AUTHOR .CR nl_tools_16() was developed by HP. .SH SEE ALSO setlocale(3C), multibyte(3C), wconv(3X), wctype(3X), hpnls(5). .\" .\" index@\f4ADVANCE()\f1 \- advance pointer to next 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARADV()\f1 \- get character and advance pointer to next character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARAT()\f1 \- get value of 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHAR()\f1, \- put 8- or 16-bit character in memory@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHARADV()\f1, \- put character in memory and advance pointer@@@\f3nl_tools_16(3X)\f1 .\" index@\f4byte_status()\f1, \f4BYTE_STATUS()\f1 \- test for valid 1- or 2-byte character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4firstof2()\f1, \f4FIRSTof2()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4secof2()\f1, \f4SECof2()\f1 \- test for valid second byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f1characters, tools to process 16-bit@@@\f3nl_tools_16(3X)\f1 .\" index@\f1process 16-bit characters, tools to@@@\f3nl_tools_16(3X)\f1 .\" index@\f1sixteen-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f116-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f1tools to process 16-bit characters@@@\f3nl_tools_16(3X)\f1 .\" .\" links@nl_tools_16.3x ADVANCE.3x .\" links@nl_tools_16.3x BYTE_STATUS.3x .\" links@nl_tools_16.3x CHARADV.3x .\" links@nl_tools_16.3x CHARAT.3x .\" links@nl_tools_16.3x FIRSTof2.3x .\" links@nl_tools_16.3x SECof2.3x .\" links@nl_tools_16.3x WCHAR.3x .\" links@nl_tools_16.3x WCHARADV.3x .\" links@nl_tools_16.3x byte_status.3x .\" links@nl_tools_16.3x c_colwidth.3x .\" links@nl_tools_16.3x firstof2.3x .\" links@nl_tools_16.3x secof2.3x .\" .\" toc@\f3nl_tools_16(3X)\f1:\0\0\f4ADVANCE()\f1, \f4byte_status()\f1, \f4BYTE_STATUS()\f1, \f4CHARADV()\f1,\n\f4CHARAT()\f1, \f4C_COLWIDTH()\f1, \f4c_colwidth()\f1, \f4firstof2()\f1, \f4FIRSTof2()\f1,\n\f4secof2()\f1, \f4SECof2()\f1, \f4WCHAR()\f1, \f4WCHARADV()\f1@@@tools to process 16-bit characters .\" toc@\f4ADVANCE()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4byte_status()\f1, \f4BYTE_STATUS()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARAT()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4firstof2()\f1, \f4FIRSTof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4secof2()\f1, \f4SECof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHAR()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .\" .so /home/len/hpmanpages/startup.motorola .RH "Composite" "Intrinsics Classes" .XX "Composite" .SH "Name" .Na Composite widget class \- fundamental widget with children. .Nz .\" .SH "Synopsis" .IP "\s-1\f(HBPublic Headers:\fP\s0" 18n 0 \fI\fP .br \fI\fP .IP "\s-1\f(HBPrivate Header:\fP\s0" 18n 0 \fI\fP .IP "\s-1\f(HBClass\ Name:\fP\s0" 18n 0 Composite .IP "\s-1\f(HBClass\ Hierarchy:\fP\s0" 18n 0 'nh Core \(-> Composite .IP "\s-1\f(HBClass Pointer:\fP\s0" 18n 0 \f(CWcompositeWidgetClass\fP .IP "\s-1\f(HBInstantiation:\fP\s0" 18n 0 Composite is an Intrinsics meta-class, and is not normally instantiated. .IP "\s-1\f(HBFunctions/Macros:\fP\s0" 18n 0 \f(CWXtIsComposite(\^)\fP .\" .SH "Description" Composite is the superclass of all classes that can have children. It defines methods for geometry management of those children. .\" .SH "New Resources" Composite defines the following resources: .br .sp 1 .in 0 .KS .TS linesize(2) tab(@); lp7 lp7 lp7 lp7 lp7 lp6 lp6 lp6 lp6 lp6. \fRName@Class@Type@Default@Access\fP .sp .2 .XX "XtNchildren" \f(CWXtNchildren\fP@\f(CWXtCReadOnly\fP@\f(CWWidgetList\fP@\f(CWNULL\fP@\f(CWG\fP .XX "XtNinsertPosition" \f(CWXtNinsertPosition\fP@\f(CWXtCInsertPosition\fP@\f(CW(*)(\^)\fP@\f(CWNULL\fP@\f(CWCSG\fP .XX "XtNnumChildren" \f(CWXtNnumChildren\fP@\f(CWXtCReadOnly\fP@\f(CWCardinal\fP@\f(CW0\fP@\f(CWG\fP .sp .2 .TE .KE .in .sp 1 .IP "\f(CWXtNchildren\fP" 5n List of widget's children. .IP "\f(CWXtNinsertPosition\fP" Points to an \f(CWXtOrderProc(\^)\fP function which is to be called to determine the position at which each child should be inserted into the \f(CWXtNchildren\fP array. .IP "\f(CWXtNnumChildren\fP" Length of the array in \f(CWXtNchildren\fP. .\" .SH "Inherited Resources" Composite inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. .Nd 3 .sp 1 .in 0 .KS .TS H tab(@), linesize(2); lp7 lp7 lp7 lp7 lp6w(1.23i) lp6w(1i) lp6w(1.23i) lp6w(1i). \fRResource@Inherited From@Resource@Inherited From\fP .sp 2p .Th \f(CWXtNaccelerators\fP@\f(CWCore\fP@\f(CWXtNheight\fP@\f(CWCore\fP \f(CWXtNancestor-\fP@\f(CWCore\fP@\f(CWXtNinitialResources-\fP@\f(CWCore\fP .sp -2p \0\0\f(CWSensitive\fP@@\0\0\f(CWPersistent\fP .sp .52p \f(CWXtNbackground\fP@\f(CWCore\fP@\f(CWXtNmappedWhen-\fP@\f(CWCore\fP .sp -2p @@\0\0\f(CWManaged\fP \f(CWXtNbackground-\fP@\f(CWCore\fP@\f(CWXtNscreen\fP@\f(CWCore\fP .sp -2p \0\0\f(CWPixmap\fP \f(CWXtNborderColor\fP@\f(CWCore\fP@\f(CWXtNsensitive\fP@\f(CWCore\fP \f(CWXtNborderPixmap\fP@\f(CWCore\fP@\f(CWXtNtranslations\fP@\f(CWCore\fP \f(CWXtNborderWidth\fP@\f(CWCore\fP@\f(CWXtNwidth\fP@\f(CWCore\fP \f(CWXtNcolormap\fP@\f(CWCore\fP@\f(CWXtNx\fP@\f(CWCore\fP \f(CWXtNdepth\fP@\f(CWCore\fP@\f(CWXtNy\fP@\f(CWCore\fP \f(CWXtNdestroyCallback\fP@\f(CWCore\fP .sp 2p .TE .KE .in .sp 1 .\" .SH "Class Structure" The composite class structure is defined as follows: .Ps .ta +4n +2.5i typedef struct { XtGeometryHandler geometry_manager; /* geometry manager for children */ XtWidgetProc change_managed; /* change managed state of child */ XtWidgetProc insert_child; /* physically add child to parent */ XtWidgetProc delete_child; /* physically remove child */ XPointer extension; /* pointer to extension record */ } CompositeClassPart; typedef struct { CoreClassPart core_class; CompositeClassPart composite_class; } CompositeClassRec, *CompositeWidgetClass; .Pe The fields of this class structure have the following meanings: .\" .IP "\f(CWgeometry_manager()\fP" 5n .XX "Composite class fields: geometry_manager" The \f(CWgeometry_manager()\fP method called when a child widget requests a new size or location. See the reference page in Section 4. Use \f(CWXtInheritGeometryManager\fP to inherit the \f(CWgeometry_manager()\fP method of the superclass. .\" .IP "\f(CWchange_managed()\fP" 5n .XX "Composite class fields: change_managed" The \f(CWchange_managed()\fP method called when a child or children become managed or unmanaged. See the reference page in Section 4. Use \f(CWXtInheritChangeManaged\fP to inherit the \f(CWchange_managed()\fP method of the superclass. .\" .IP "\f(CWinsert_child()\fP" 5n .XX "Composite class fields: insert_child" The \f(CWinsert_child()\fP method called to add a child to the widgets \f(CWchildren\fP instance array. See the reference page in Section 4. Use \f(CWXtInheritInsertChild\fP to inherit the \f(CWinsert_child()\fP method of the superclass. .\" .IP "\f(CWdelete_child()\fP" 5n .XX "Composite class fields: delete_child" The \f(CWdelete_child()\fP method called to add a child to the widgets \f(CWchildren\fP instance array. See the reference page in Section 4. Use \f(CWXtInheritDeleteChild\fP to inherit the \f(CWdelete_child()\fP method of the superclass. .\" .IP "\f(CWextension\fP" 5n .XX "Composite class fields: extension" A linked list of extension records, or \f(CWNULL\fP. There is currently one extension defined for Composite which allows the class to specify whether it accepts non-widget children. See below. .\" .SH "Extension Structure" There is one extension defined for the Composite class. The extension structure is shown below; the \f(CWrecord_type\fP field should be \f(CWNULLQUARK\fP, and the \f(CWversion\fP field should be \f(CWXtCompositeExtensionVersion\fP. The \f(CWaccepts_objects\fP field should be \f(CWTrue\fP if the class should accept non-widget objects as children, or \f(CWFalse\fP if it should not accept them. .Ps .ta +4n +2.3i typedef struct { XtPointer next_extension; /* next record is linked list, or NULL */ XrmQuark record_type; /* NULLQUARK */ long version; /* XtCompositeExtensionVersion */ Cardinal record_size; /* use sizeof() */ Boolean accepts_objects; } CompositeClassExtensionRec, *CompositeClassExtension; .Pe .\" .SH "Instance Structure" The composite instance structure contains at least the following fields (which need not be in this order): .Ps .ta +4n +2.2i typedef struct { WidgetList children; /* array of ALL widget children */ Cardinal num_children; /* total number of widget children */ Cardinal num_slots; /* number of slots in children array */ XtOrderProc insert_position; /* compute position of new child */ } CompositePart; typedef struct { CorePart core; CompositePart composite; } CompositeRec, *CompositeWidget; .Pe .\" .SH "See Also" \s-1\fIXtManageChildren\fR\s+1\*(s1, .br \s-1\fIXtOrderProc\fR\s+1\*(s2, .br \s-1\fICore\fR\s+1\*(s3, .br \s-1\fIchange_managed\fR\s+1\*(s4, \s-1\fIdelete_child\fR\s+1\*(s4, \s-1\fIgeometry_manager\fR\s+1\*(s4, \s-1\fIinsert_child\fR\s+1\*(s4. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "Constraint" "Intrinsics Classes" .XX "Constraint" .SH "Name" .Na Constraint widget class \- a widget that provides constraint resources for its children. .Nz .\" .SH "Synopsis" .IP "\s-1\f(HBPublic Headers:\fP\s0" 18n 0 \fI\fP .br \fI\fP .IP "\s-1\f(HBPrivate Header:\fP\s0" 18n 0 \fI\fP .IP "\s-1\f(HBClass\ Name:\fP\s0" 18n 0 Constraint .IP "\s-1\f(HBClass\ Hierarchy:\fP\s0" 18n 0 'nh Core \(-> Composite \(-> Constraint .IP "\s-1\f(HBClass Pointer:\fP\s0" 18n 0 \f(CWconstraintWidgetClass\fP .IP "\s-1\f(HBInstantiation:\fP\s0" 18n 0 Constraint is an Intrinsics meta-class, and is not normally instantiated. .IP "\s-1\f(HBFunctions/Macros:\fP\s0" 18n 0 \f(CWXtIsConstraint(\^)\fP .\" .SH "Description" .XX "resources, constraint" .XX "constraint widgets, about" Constraint widgets are a subclass of \f(CWcompositeWidgetClass\fR. Their name is derived from the fact that they may manage the geometry of their children based on constraints associated with each child. These constraints can be as simple as the maximum width and height the parent will allow the child to occupy or as complicated as how other children should change if this child is moved or resized. Constraint widgets let a parent define resources that are supplied for their children. For example, if the Constraint parent defines the maximum sizes for its children, these new size resources are retrieved for each child as if they were resources that were defined by the child widget. Accordingly, constraint resources may be included in the argument list or resource file just like any other resource for the child. .LP Constraint widgets have all the responsibilities of normal composite widgets and, in addition, must process and act upon the constraint information associated with each of their children. .LP To make it easy for widgets and the Intrinsics to keep track of the constraints associated with a child, every widget has a \f(CWconstraints\fP field, which is the address of a parent-specific structure that contains constraint information about the child. If a child's parent is not a subclass of \f(CWconstraintWidgetClass\fR, then the child's \f(CWconstraints\fP field is \f(CWNULL\fR. .LP Note that the constraint data structures are transparent to the child; that is, when a child is managed by a parent that is a subclass of a constraint widget, there is no difference, as far as the child is concerned, from being managed by a normal composite widget. .LP See the "Background" section below for more information on Constraint and constraint resources. .\" .SH "New Resources" Constraint defines no new resources. .\" .SH "Inherited Resources" Constraint inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. .Nd 3 .sp 1 .in 0 .KS .TS H tab(@), linesize(2); lp7 lp7 lp7 lp7 lp6w(1.35i) lp6w(1i) lp6w(1.35i) lp6w(1i). \fRResource@Inherited From@Resource@Inherited From\fP .sp 2p .Th \f(CWXtNaccelerators\fP@\f(CWCore\fP@\f(CWXtNheight\fP@\f(CWCore\fP \f(CWXtNancestorSensitive\fP@\f(CWCore\fP@\f(CWXtNinitialResources-\fP@\f(CWCore\fP .sp -2p @@\0\0\f(CWPersistent\fR \f(CWXtNbackground\fP@\f(CWCore\fP@\f(CWXtNinsertPosition\fP@\f(CWComposite\fP \f(CWXtNbackgroundPixmap\fP@\f(CWCore\fP@\f(CWXtNmappedWhen-@\f(CWCore\fP .sp -2p @@\0\0\f(CWManaged\fP \f(CWXtNborderColor\fP@\f(CWCore\fP@\f(CWXtNnumChildren\fP@\f(CWComposite\fP \f(CWXtNborderPixmap\fP@\f(CWCore\fP@\f(CWXtNscreen\fP@\f(CWCore\fP \f(CWXtNborderWidth\fP@\f(CWCore\fP@\f(CWXtNsensitive\fP@\f(CWCore\fP \f(CWXtNchildren\fP@\f(CWComposite\fP@\f(CWXtNtranslations\fP@\f(CWCore\fP \f(CWXtNcolormap\fP@\f(CWCore\fP@\f(CWXtNwidth\fP@\f(CWCore\fP \f(CWXtNdepth\fP@\f(CWCore\fP@\f(CWXtNx\fP@\f(CWCore\fP \f(CWXtNdestroyCallback\fP@\f(CWCore\fP@\f(CWXtNy\fP@\f(CWCore\fP .sp 2p .TE .KE .in .sp 1 .\" .SH "Class Structure" The Constraint class record is defined as follows: .Ps .ta +5n +2.4i typedef struct { XtResourceList resources; /* constraint resource list */ Cardinal num_resources; /* number of constraints in list */ Cardinal constraint_size; /* size of constraint record */ XtInitProc initialize; /* constraint initialization */ XtWidgetProc destroy; /* constraint destroy proc */ XtSetValuesFunc set_values; /* constraint set_values proc */ XtPointer extension; /* pointer to extension record */ } ConstraintClassPart; typedef struct { CoreClassPart core_class; CompositeClassPart composite_class; ConstraintClassPart constraint_class; } ConstraintClassRec, *ConstraintWidgetClass; .Pe The fields of the Constraint class part have the following meanings: .\" .IP "\f(CWresources\fP" 5n .XX "Constraint class fields: resources" An array of \f(CWXtResource\fP, each of which defines a single constraint resource for the widget class. See \f(CWXtGetApplicationResources()\fP for an explanation of how to define resources and declare an \f(CWXtResourceList\fP. .\" .IP "\f(CWnum_resources\fP" 5n .XX "Constraint class fields: num_resources" The number of element in the \f(CWresources\fP array. .\" .IP "\f(CWconstraint_size\fP" 5n .XX "Constraint class fields: constraint_size" The size of the constraint instance record for this widget class. A block this size will be automatically allocated for each child of an instance of this widget class, and will be pointed to by that child's Core \f(CWconstraints\fP instance field. Use \f(CWsizeof\fP to initialize this field. .\" .IP "\f(CWinitialize()\fP" 5n .XX "Constraint class fields: initialize" The constraint \f(CWinitialize()\fP method, called to initialize the part of constraint instance record added by this widget class. See the reference page in Section 4. This is a chained method and cannot be inherited. Use \f(CWNULL\fP if the constraint part defined by this class does not need any initialization. .\" .IP "\f(CWdestroy()\fP" 5n .XX "Constraint class fields: destroy" The constraint \f(CWdestroy()\fP method, called to deallocate any memory or other resources associated with the part of the constraint instance record added by this widget class when a child widget is destroyed. See the reference page in Section 4. This is a chained method and cannot be inherited. Use \f(CWNULL\fP if the constraint part defined by this class does not need any special deallocation. .\" .IP "\f(CWset_values()\fP" 5n .XX "Constraint class fields: set_values" The constraint \f(CWset_values()\fP method, called when \f(CWXtSetValues()\fP is called on a child widget. See the reference page in Section 4. This is a chained method and cannot be inherited. Use \f(CWNULL\fP if the constraint part defined by this class does not have any resources. .\" .IP "\f(CWextension\fP" 5n .XX "Constraint class fields: extension" A linked list of extension records, or \f(CWNULL\fP. There is currently one extension defined for Constraint which adds a \f(CWget_values_hook()\fP method; see below. .\" .SH "Extension Structure" The Intrinsics define one extension to Constraint: .Ps .ta +4n +2.3i typedef struct { XtPointer next_extension; /* next record is linked list, or NULL */ XrmQuark record_type; /* NULLQUARK */ long version; /* XtConstraintExtensionVersion */ Cardinal record_size; /* use sizeof() */ XtArgsProc get_values_hook; } ConstraintClassExtensionRec, *ConstraintClassExtension; .Pe The \f(CWrecord_type\fP field should be \f(CWNULLQUARK\fP, the \f(CWversion\fP field should be \f(CWXtConstraintExtensionVersion\fP, and the \f(CWget_values_hook()\fP field should be the \f(CWget_values_hook()\fP method for the constraint resources. See Constraint \f(CWget_values_hook\fP(4). .\" .SH "Instance Structure" The Constraint instance structure defines no new fields: .Ps .ta +4.5n +2i typedef struct _ConstraintPart { XtPointer dummy; /* No new fields, keep C compiler happy */ } ConstraintPart; .Nd 10 typedef struct { CorePart core; CompositePart composite; ConstraintPart constraint; } ConstraintRec, *ConstraintWidget; .Pe .\" .SH "Background" Constraints are allocated, initialized, deallocated and otherwise maintained insofar as possible by the Intrinsics. The constraint class record part has several entries that facilitate this. All entries in \f(CWConstraintClassPart\fP are information and procedures that are defined and implemented by the parent, but they are called whenever actions are performed on the parent's children. .LP .XX "XtCreateWidget" The \f(CWXtCreateWidget()\fR function uses the \f(CWconstraint_size\fP field to allocate a constraint record when a child is created. The \f(CWconstraint_size\fP field gives the number of bytes occupied by a constraint record. \f(CWXtCreateWidget()\fP also uses the constraint resources to fill in resource fields in the constraint record associated with a child. It then calls the constraint \f(CWinitialize()\fR methods so that the parent can compute constraint fields that are derived from constraint resources and can possibly move or resize the child to conform to the given constraints. .LP .XX "XtGetValues" .XX "XtSetValues" The \f(CWXtGetValues()\fP and \f(CWXtSetValues()\fP functions use the constraint resources to get the values or set the values of constraint associated with a child. \f(CWXtSetValues()\fP then calls the constraint \f(CWset_values()\fP methods so that a parent can recompute derived constraint fields and move or resize the child as appropriate. .LP If the Constraint widget or any of its superclasses have declared a \f(CWConstraintClassExtension\fR record in the constraint class part extension fields with a record type of \f(CW\s-1NULLQUARK\s+1\fR, and if the \f(CWget_values_hook()\fP field in the extension record is non-\f(CWNULL\fR, then \f(CWXtGetValues()\fR calls the \f(CWget_values_hook()\fR method(s) to allow the parent to return derived constraint fields. .XX "XtDestroyWidget" .LP The \f(CWXtDestroyWidget()\fP function calls the constraint destroy method to deallocate any dynamic storage associated with a constraint record. The constraint record itself must not be deallocated by the constraint destroy method; \f(CWXtDestroyWidget()\fP does this automatically. \" .SH "See Also" \s-1\fICore\fR\s+1\*(s3, \s-1\fIComposite\fR\s+1\*(s3, .br \s-1\fIConstraint destroy\fR\s+1\*(s4, \s-1\fIConstraint get_values_hook\fR\s+1\*(s4, \s-1\fIConstraint initialize\fR\s+1\*(s4, \s-1\fIConstraint set_values\fR\s+1\*(s4. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "Constraint\0destroy" "Xt \- Intrinsics Methods" .SH "Name" .Na Constraint\0destroy \- Constraint class method for freeing resources associated with a child's constraint record. .Nz .XX "constraint widgets, destroy method" .XX "methods: Constraint; destroy" .SH "Synopsis" .Sy typedef void (*XtWidgetProc)(Widget); .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget being destroyed. .SH "Description" The Constraint \f(CWdestroy()\fP method is registered on the \f(CWdestroy\fP field of the Constraint class part structure (which is not the same as the \f(CWdestroy\fP field of the Object or Core class part structure). It is called by \f(CWXtDestroyWidget()\fP when the child of a constraint widget is destroyed, and should deallocate any memory or resources associated with the part of the constraint record of \f(CIw\fP that is owned by the class. It should not deallocate the constraint record itself. .LP This method is similar to the Object \f(CWdestroy()\fP method. The Constraint \f(CWdestroy()\fP methods of a widget class and its superclasses are called in subclass-to-superclass order, starting at the class of the parent of \f(CIw\fP, and ending at the Constraint class. Therefore, the Constraint \f(CWdestroy()\fP method should deallocate only memory and resources associated with the part of the constraint record specific to its class, and not the memory or resources allocated by any of its superclasses. .LP The Constraint \f(CWdestroy()\fP method is chained, and so cannot be inherited. If a constraint widget does not need to deallocate any memory or resources associated with its constraint part structure, the \f(CWdestroy\fP field in its Constraint class part record can be \f(CWNULL\fR. .LP See \f(CWdestroy\fP(4) for more information about what should be freed and what should not. See \f(CWXtDestroyWidget\fP(1) for details on the widget and object destruction process. .\" .SH "Example" The following procedure is the Constraint \f(CWdestroy()\fP method of the Xaw Tree widget. Note that it uses a macro (defined below) to cast the specified widget's constraint field appropriately, and calls \f(CWXtParent()\fP on the specified widget to obtain the Tree widget itself. .LP This procedure is a somewhat unusual example, because it does not directly call \f(CWXtFree()\fP, \f(CWXtReleaseGC()\fP, or similar functions on fields of the constraint record. The constraint records of the Tree class are linked in a tree structure, and this procedure is used to remove a node from that tree. This might have been more appropriate in the \f(CWdelete_child()\fP method instead. .Ps static void ConstraintDestroy (w) Widget w; { TreeConstraints tc = TREE_CONSTRAINT(w); TreeWidget tw = (TreeWidget) XtParent(w); int i; /* * Remove the widget from its parent's sub-nodes list and * make all this widget's sub-nodes sub-nodes of the parent. */ if (tw->tree.tree_root == w) { if (tc->tree.n_children > 0) tw->tree.tree_root = tc->tree.children[0]; else tw->tree.tree_root = NULL; } delete_node (tc->tree.parent, (Widget) w); for (i = 0; i< tc->tree.n_children; i++) insert_node (tc->tree.parent, tc->tree.children[i]); layout_tree ((TreeWidget) (w->core.parent), FALSE); } .Pe The useful \f(CWTREE_CONSTRAINTS\fP macro is defined as follows: .Ps #define TREE_CONSTRAINT(w) ((TreeConstraints)((w)->core.constraints)) .Pe .\" .SH "See Also" .na \s-1\fIXtDestroyWidget\fR\s+1\*(s1, .br \s-1\fIConstraint\fR\s+1\*(s3, \s-1\fICore\fR\s+1\*(s3. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "Constraint\0get_values_hook" "Xt \- Intrinsics Methods" .SH "Name" .Na Constraint\0get_values_hook \- Constraint class method for obtaining values of constraint resources that do not appear in the Constraint resource list. .Nz .XS "methods, Constraint get_values_hook" .XS "Constraint get_values_hook method" .SH "Synopsis" .Sy typedef void (*XtArgsProc)(Widget, ArgList, Cardinal *); .As Widget \f(CIw\fP; ArgList \f(CIargs\fP; Cardinal *\f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget or object that is having its resources queried. .IP \f(CIargs\fP 1i Specifies the argument list that was passed to \f(CWXtGetValues()\fR. .IP \f(CInum_args\fP 1i Specifies the number of arguments in the argument list. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" The Constraint \f(CWget_values_hook()\fP method is registered on the \f(CWget_values_hook\fP field of a \f(CWConstraintClassExtensionRec\fP with \f(CWrecord_type\fP \f(CWNULLQUARK\fP, which is itself registered on the \f(CWextension\fP field of the Constraint class part structure. If such an extension exists, then this method is called when \f(CWXtGetValues()\fP is called for a child of the constraint widget, and gives the constraint widget the opportunity to set values for resources that do not appear in the Constraint resource list, or to modify any of the resource values that are to be returned. .LP The Constraint \f(CWget_values_hook()\fP method is chained in superclass-to-subclass order, and cannot be inherited. Classes that do not need a \f(CWget_value_hook()\fP method can set \f(CWNULL\fP in the Constraint extension record, or can simply omit the extension record. .LP See \f(CWXtGetValues\fP(1) for more information on when this method is invoked. .\" .SH "Usage" The usage of this method is similar to the normal \f(CWget_values_hook()\fP method: the widget can use \f(CWXtGetSubvalues()\fP or \f(CWXtGetValues()\fP to obtain the values of constraint resources that do not appear on its Constraint resource list, so that it can export them as if they did appear on that list. This method can also be used to modify the returned values in any way, by making a copy of string resource values, for example. See \f(CWget_values_hook\fP(4) for more information. .LP None of the Intrinsics widgets nor any of the Xaw widgets define a Constraint \f(CWget_values_hook()\fP method. .\" .Nd 5 .SH "See Also" .na .br \s-1\fIXtGetSubvalues\fR\s+1\*(s1, \s-1\fIXtGetValues\fR\s+1\*(s1, .br \s-1\fICore\fR\s+1\*(s3, .br \s-1\fIget_values_hook\fR\s+1\*(s4. .ad .XE "methods, Constraint get_values_hook" .XE "Constraint get_values_hook method" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "Constraint\0initialize" "Xt \- Intrinsics Methods" .SH "Name" .Na Constraint\0initialize \- Constraint class method to initialize a child object or widget's constraint record. .Nz .XX "constraint widgets, initialize method" .XX "methods: Constraint; initialize" .SH "Synopsis" .Sy typedef void (*XtInitProc)(Widget, Widget, ArgList, Cardinal *); .As Widget \f(CIrequest\fP; Widget \f(CIinit\fP; ArgList \f(CIargs\fP; Cardinal *\f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIrequest\fP 1i Specifies the newly created child widget or object instance with its constraint record resource values set as requested by the argument list, the resource database, and the constraint defaults. .IP \f(CIinit\fP 1i Specifies the same widget or object with its constraint record fields as modified by any superclass Constraint \f(CWinitialize()\fR methods. .IP \f(CIargs\fP 1i Specifies the argument list that was passed to \f(CWXtCreateWidget()\fP. .IP \f(CInum_args\fP 1i Specifies the number of entries in the argument list. .\" .SH "Description" The Constraint \f(CWinitialize()\fP method is registered on the \f(CWinitialize\fP field of the Constraint class part structure, and is called by \f(CWXtCreateWidget()\fP when a child of the constraint widget is created. The Constraint \f(CWinitialize()\fP method performs the same sort of initializations on the constraint record of a widget that the normal (Object, RectObj, or Core) \f(CWinitialize()\fP method performs on the widget instance structure. .LP The \f(CWrequest\fP and \f(CIinit\fP arguments specify the child widget that is being created. The \f(CWconstraints\fP field of the \f(CIrequest\fP widget points to a copy of the constraint record as it was after all of the constraint resources were initialized from the argument list, the resource database, or the resource list defaults. The \f(CWconstraints\fP field of the \f(CIinit\fP widget points to the actual constraints record of the widget, and has been further initialized by the Constraint \f(CWinitialize()\fP method of any Constraint superclasses of the parent widget. All modifications should be made to the \f(CIinit\fP constraints record; the \f(CIrequest\fP argument exists so that the widget class can determine which field of the constraints record have been modified by superclass Constraint \f(CWinitialize()\fP methods. .LP The Constraint \f(CWinitialize()\fP method is chained in superclass-to-subclass order, and cannot be inherited. If nothing in the constraint structure needs initialization, the Constraint class part \f(CWinitialize\fP field should be \f(CWNULL\fP. .LP The \f(CIargs\fP and \f(CInum_args\fP arguments were added to this method in Release 4. .LP See \f(CWinitialize\fP(4) for an explanation of the things that an initialize procedure should do. See \f(CWXtCreateWidget\fP(1) for full details of the widget creation process. .\" .Nd 4 .SH "Example" The following procedure is the Constraint \f(CWinitialize()\fP method, slightly modified, of the Athena Form widget class. Note how it obtains the constraint record and the parent form widget from the supplied child widget. Note also that it provides "dynamic defaults" for two of its constraint resources: if \f(CWdx\fP or \f(CWdy\fP is equal to some default value (i.e., if it was not explicitly specified), then it will be replaced by the value of the \f(CWXtNdefaultSpacing\fP resource from the Form widget itself. .LP Note that this procedure (and most other \f(CWinitialize()\fP procedures in existence) has named its \f(CIinit\fP argument \f(CWnew\fP. "new" is a reserved word in C++, and your programs will be more portable if you avoid using it in your C code. .Ps /* ARGSUSED */ static void ConstraintInitialize(request, new, args, num_args) Widget request, new; ArgList args; Cardinal *num_args; { FormConstraints form = (FormConstraints)new->core.constraints; FormWidget fw = (FormWidget)new->core.parent; form->form.virtual_width = (int) new->core.width; form->form.virtual_height = (int) new->core.height; if (form->form.dx == default_value) form->form.dx = fw->form.default_spacing; if (form->form.dy == default_value) form->form.dy = fw->form.default_spacing; form->form.deferred_resize = False; } .Pe .SH "See Also" .na \s-1\fIXtCreateWidget\fR\s+1\*(s1, .br \s-1\fIConstraint\fR\s+1\*(s3, \s-1\fICore\fR\s+1\*(s3, .br \s-1Constraint \fIdestroy\fR\s+1\*(s4, \s-1\fIinitialize\fR\s+1\*(s4, \s-1Constraint \fIset_values\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "Constraint\0set_values" "Xt \- Intrinsics Methods" .SH "Name" .Na Constraint\0set_values \- Constraint class method called to handle changes to constraint resources. .Nz .XS "constraint widgets, set_values method" .XS "methods: Constraint; set_values" .SH "Synopsis" .Sy typedef Boolean (*XtSetValuesFunc)(Widget, Widget, Widget, ArgList, .br Cardinal *); .As Widget \f(CIcurrent\fP; Widget \f(CIrequest\fP; Widget \f(CIset\fP; ArgList \f(CIargs\fP; Cardinal *\f(CInum-args\fP; .Ae .SS "Inputs" .IP \f(CIcurrent\fP 1i Specifies a copy of the child widget (and that widget's constraint record) made by \f(CWXtSetValues()\fP before any resources are changed or any class methods are called. .IP \f(CIrequest\fP 1i Specifies a copy of the child widget (and that widget's constraint record) made by \f(CWXtSetValues()\fP after the constraint and normal resources are changed as requested, but before any class \f(CWset_values()\fR methods are called. .IP \f(CIset\fP 1i Specifies the child widget with constraint and normal resources set and as modified by any superclass methods that have been called by \f(CWXtSetValues()\fP. .IP \f(CIargs\fP 1i Specifies the argument list passed to \f(CWXtSetValues()\fR. .IP \f(CInum_args\fR 1i Specifies the number of arguments in the \f(CIargs\fP. .SS "Returns" \f(CWTrue\fP if the resource changes require the child widget to be redrawn; \f(CWFalse\fP otherwise. .\" .SH "Description" The Constraint \f(CWset_values()\fP method is registered on the \f(CWset_value\fP field of the Constraint class part structure. It is invoked when \f(CWXtSetValues()\fP is called on a child of the constraint widget to do any processing necessary to handle resource changes in the child's constraint record. .LP The arguments to the Constraint \f(CWset_values()\fP method are the same as those passed to the child's Object, RectObj, or Core \f(CWset_values()\fP method. The \f(CWconstraints\fP field of each of the widget arguments points to a copy of the child's constraints procedure made at the appropriate point by \f(CWXtSetValues()\fP. The Constraint \f(CWset_values()\fP procedure must perform the same sort of processing on this record as the normal \f(CWset_values()\fP method performs on the widget instance record itself. .LP The Constraint \f(CWset_values()\fP method will deal primarily with the fields of the constraint record, but may also modify widget instance fields as necessary. If the constraint for the maximum height of a child is changed to a value that is less than the current height of the child, for example, the Constraint \f(CWset_values()\fP method may change the \f(CWheight\fP instance field of the child widget. If the parent needs to change the geometry of the child, it needn't call \f(CWXtConfigureWidget()\fP directly; if any child geometry fields are changed by this or other \f(CWset_values()\fP methods, \f(CWXtSetValues()\fP will call \f(CWXtMakeGeometryRequest()\fP, which will invoke the parent's \f(CWgeometry_manager()\fP method, which can do any necessary processing. .LP As with the Object \f(CWset_values()\fP method, the Constraint \f(CWset_values()\fP method should return \f(CWTrue\fP if the widget should be redrawn. Unless this method actually modifies fields in the widget instance structure itself, however, a redraw will never be useful because the child's \f(CWexpose()\fP method cannot take constraint fields into account. .LP The Constraint \f(CWset_values()\fP method should not assume that the child widget is realized. .LP The \f(CWargs\fP and \f(CWnum_args\fP arguments were added in Release 4. .LP The Constraint \f(CWset_values()\fP method is chained in superclass-to-subclass order, and cannot be inherited. If none of the resources in a class's constraint record need special processing when their values are changed, this method may be \f(CWNULL\fP. .LP See \f(CWset_values\fP(4) for information on the arguments to this function, and a discussion of the typical tasks of a \f(CWset_values()\fP method. See \f(CWXtSetValues\fP(1) for full details on the widget creation process. .\" .SH "Example" The following procedure is the Constraint \f(CWset_values()\fP method, lightly edited, of the Xaw Paned widget class. Note that it obtains the constraint records of the \f(CIcurrent\fP and \f(CIset\fP arguments (which are named \f(CWold\fP and \f(CWnew\fP here) and compares their fields to determine what has changed. Note also that "new" is a reserved word in C++, and your C code will be more portable if you avoid using it as an argument name. .Ps .ps 8 #define PaneInfo(w) ((Pane)(w)->core.constraints) /* ARGSUSED */ static Boolean PaneSetValues(old, request, new, args, num_args) Widget old, request, new; ArgList args; Cardinal *num_args; { Pane old_pane = PaneInfo(old); Pane new_pane = PaneInfo(new); /* Check for new min and max. */ if (old_pane->min != new_pane->min old_pane->max != new_pane->max) XawPanedSetMinMax(new, (int)new_pane->min, (int)new_pane->max); /* Check for change in XtNshowGrip. */ if (old_pane->show_grip != new_pane->show_grip) if (new_pane->show_grip == TRUE) { CreateGrip(new); if (XtIsRealized(XtParent(new))) { if (XtIsManaged(new)) /* if paned is unrealized this will happen automatically at realize time.*/ XtManageChild(PaneInfo(new)->grip); /* manage the grip. */ CommitNewLocations( (PanedWidget) XtParent(new) ); } } else if ( HasGrip(old) ) { XtDestroyWidget( old_pane->grip ); new_pane->grip = NULL; } return(False); } .ps 10 .Pe .\" .SH "See Also" .na \s-1\fIXtSetValues\fR\s+1\*(s1, .br \s-1\fIConstraint\fR\s+1\*(s3, \s-1\fICore\fR\s+1\*(s3, .br \s-1\fIset_values\fR\s+1\*(s4. .ad .XE "constraint widgets, set_values method" .XE "methods: Constraint; set_values" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH Constraint_ 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp Constraint_destroy@ConstraintA .sp .5 Constraint_get_values_hook@ConstraintB .sp .5 Constraint_initialize@ConstraintC .sp .5 Constraint_set_values@ConstraintD .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "Core" "Intrinsics Classes" .XX "Core widget" .XX "widget class, Core" .SH "Name" .Na Core widget class \- fundamental object class with a window. .Nz .\" .SH "Synopsis" .IP "\s-1\f(HBPublic Headers:\fP\s0" 18n 0 \fI\fP .br \fI\fP .IP "\s-1\f(HBPrivate Header:\fP\s0" 18n 0 \fI\fP .IP "\s-1\f(HBClass\ Name:\fP\s0" 18n 0 Core .IP "\s-1\f(HBClass\ Hierarchy:\fP\s0" 18n 0 'nh Object \(-> RectObj \(-> \fIunnamed\fP \(-> Core .IP "\s-1\f(HBClass Pointer:\fP\s0" 18n 0 \f(CWwidgetClass\fP or \f(CWcoreWidgetClass\fP .IP "\s-1\f(HBInstantiation:\fP\s0" 18n 0 Core is an Intrinsics meta-class, and is not normally instantiated. .IP "\s-1\f(HBFunctions/Macros:\fP\s0" 18n 0 \f(CWXtIsWidget()\fP .\" .SH "Description" Core is the fundamental class for windowed widgets. All widgets with windows are subclasses of Core. Core is sometimes instantiated for use as a basic drawing area. .\" .SH "New Resources" Core has the following resources (some of which are actually defined by the Object and RectObj classes): .br .sp 1 .in 0 .KS .TS H tab (@), linesize (2); l2 l2 l2 l2 l2 l2p7 l2p7 l2p7 l2p7 l2p7. \fRName@Class@Type@Default@Access\fP .sp 2p .Th .XX "XtNaccelerators" \f(CWXtNaccelerators\fP@\f(CWXtCAccelerators\fP@\f(CWXtAccelerators\fP@\f(CWNULL\fP@\f(CWCSG\fP .XX "XtNancestorSensitive" \f(CWXtNancestor-\fP@\f(CWXtCSensitive\fP@\f(CWBoolean\fP@\f(CWdynamic\fP@\f(CWG\fP .sp -2p \0\0\f(CWSensitive\fP .XX "XtNbackground" \f(CWXtNbackground\fP@\f(CWXtCBackground\fP@\f(CWPixel\fP@\f(CWdynamic\fP@\f(CWCSG\fP .XX "XtNbackgroundPixmap" \f(CWXtNbackground-@XtCPixmap@Pixmap\fP@\f(CWXmUNSPECIFIED_ .sp -2p \0\0\f(CWPixmap\fP@@@\0\0\f(CWPIXMAP\fP@\f(CWCSG\fP .XX "XtNborderColor" \f(CWXtNborderColor\fP@\f(CWXtCBorderColor\fP@\f(CWPixel\fP@\f(CWXtDefault-\fP@\f(CWCSG\fP .sp -2p @@@\0\0\f(CWForeground\fR .XX "XtNborderPixmap" \f(CWXtNborderPixmap@XtCPixmap@Pixmap\fP@T{ \f(CWXmUNSPECIFIED_\fP .br \f(CWPIXMAP\fP T}@\f(CWCSG\fP .XX "XtNborderWidth" \f(CWXtNborderWidth\fP@\f(CWXtCBorderWidth\fP@\f(CWDimension\fP@\f(CW1\fP@\f(CWCSG\fP .XX "XtNcolormap" \f(CWXtNcolormap\fP@\f(CWXtCColormap\fP@\f(CWColormap\fP@\f(CWdynamic\fP@\f(CWCG\fP .XX "XtNdepth" \f(CWXtNdepth\fP@\f(CWXtCDepth\fP@\f(CWint\fP@\f(CWdynamic\fP@\f(CWCG\fP .\"XtNdestroyCallback@XtCCallback@XtCallbackList@NULL@C .XX "XtNheight" \f(CWXtNheight\fP@\f(CWXtCHeight\fP@\f(CWDimension\fP@\f(CWdynamic\fP@\f(CWCSG\fP .XX "XtNinitialResourcesPersistent" \f(CWXtNinitial-\fP@\f(CWXtCInitial-\fP@\f(CWBoolean\fP@\f(CWTrue\fP@\f(CWCG\fP .sp -2p \0\0\f(CWResources-\fP@\0\0\f(CWResources-\fR .sp -2p \0\0\f(CWPersistent\fP@\0\0\f(CWPersistent\fR .XX "XtNmappedWhenManaged" \f(CWXtNmappedWhen-\fP@\f(CWXtCMappedWhen-\fP@\f(CWBoolean\fP@\f(CWTrue\fP@\f(CWCSG\fP \0\0\f(CWManaged\fP@\0\0\f(CWManaged\fP .XX "XtNscreen" \f(CWXtNscreen\fP@\f(CWXtCScreen\fP@\f(CWScreen *\fP@\f(CWdynamic\fP@\f(CWCG\fP .XX "XtNsensitive:and Core" \f(CWXtNsensitive\fP@\f(CWXtCSensitive\fP@\f(CWBoolean\fP@\f(CWTrue\fP@\f(CWCSG\fP .XX "XtNtranslations" \f(CWXtNtranslations\fP@\f(CWXtCTranslations\fP@\f(CWXtTranslations\fP@\f(CWNULL\fP@\f(CWCSG\fP .XX "XtNwidth" \f(CWXtNwidth\fP@\f(CWXtCWidth\fP@\f(CWDimension\fP@\f(CWdynamic\fP@\f(CWCSG\fP .XX "XtNx" \f(CWXtNx\fP@\f(CWXtCPosition\fP@\f(CWPosition\fP@\f(CW0\fP@\f(CWCSG\fP .XX "XtNy" \f(CWXtNy\fP@\f(CWXtCPosition\fP@\f(CWPosition\fP@\f(CW0\fP@\f(CWCSG\fP .sp .2 .TE .KE .in .sp 1 .ft R .IP "\f(CWXtNaccelerators\fP" 5n .br A translation table bound with its actions for a widget. A destination widget can be set up to use this accelerator table. See \f(CWXtInstallAccelerators\fP(1). .Nd 5 .IP "\f(CWXtNancestorSensitive\fP" 5n .br Specifies whether the object has an insensitive ancestor. Default value is (a) \f(CWTrue\fP (if the widget is a top-level shell), (b) copied from the \f(CWXtNancestorSensitive\fP resource of its parent (if the widget is a popup shell), or (c) the bitwise AND of the \f(CWXtNsensitive\fP and \f(CWXtNancestorSensitive\fP resources of the parent (for other widgets). See \f(CWXtSetSensitive\fP(1). .IP "\f(CWXtNbackground\fP" 5n .br Widget's background color. .IP "\f(CWXtNbackgroundPixmap\fP" 5n .br Pixmap with which to tile the background, beginning at the upper-left corner. .\"The default value, \f(CWXmUNSPECIFIED_PIXMAP\fP, .\"is valid only if the resource has never been set. .IP "\f(CWXtNborderColor\fP" 5n .br Pixel value that defines the color of the border. .IP "\f(CWXtNborderPixmap\fP" 5n .br Pixmap with which to tile the border, beginning at the upper-left corner of the border. .\"The default value, \f(CWXmUNSPECIFIED_PIXMAP\fP, .\"is valid only if the resource has never been set. .IP "\f(CWXtNborderWidth\fP" 5n .br Width (in pixels) of the window's border. .IP "\f(CWXtNcolormap\fP" 5n .br Colormap used in converting to pixel values. Previously created pixel values are unaffected. The default value is inherited from the widget's parent, or is the default colormap of the screen for root shells that have no parent. .IP "\f(CWXtNdepth\fP" 5n .br Number of bits allowed for each pixel. The Xt Intrinsics set this resource when the widget is created. As with the \f(CWXtNcolormap\fP resource, the default value comes from the screen's default or is copied from the parent. .IP "\f(CWXtNdestroyCallback\fP" 5n .br List of callbacks invoked when the widget is destroyed. .IP "\f(CWXtNheight\fP" 5n .br Window height (in pixels), excluding the border. .IP "\f(CWXtNinitialResourcesPersistent\fP" 5n .br Specifies whether resources should be reference counted. If \f(CWTrue\fP (default), it is assumed that the widget won't be destroyed while the application is running, and thus the widget's resources are not reference counted. Set this resource to \f(CWFalse\fP if your application might destroy the widget and will need to deallocate the resources. See \f(CWXtConvertAndStore\fP(1). .IP "\f(CWXtNmappedWhenManaged\fP" 5n .br If \f(CWTrue\fP (default), the widget becomes visible (is mapped) as soon as it is both realized and managed. If \f(CWFalse\fP, the application performs the mapping and unmapping of the widget. If changed to \f(CWFalse\fP after the widget is realized and managed, the widget is unmapped. See \f(CWXtSetMappedWhenManaged\fP(1). .IP "\f(CWXtNscreen\fP" 5n .br Screen of the widget. .IP "\f(CWXtNsensitive\fP" 5n .br Specifies whether a widget receives input (is sensitive). \f(CWXtSetSensitive(\^)\fP can be used to change a widget's sensitivity and to guarantee that if a parent has its \f(CWXtNsensitive\fP resource set to \f(CWFalse\fP, then its children will have their \f(CWXtNancestorSensitive\fP resource set to \f(CWFalse\fP. See \f(CWXtSetSensitive\fP(1). .IP "\f(CWXtNtranslations\fP" 5n .br Points to a translation table; must be compiled with \f(CWXtParseTranslationTable(\^)\fP. See \f(CWXtOverrideTranslations\fP(1) and \f(CWXtAugmentTranslations\fP(1). .IP "\f(CWXtNwidth\fP" 5n .br Window width (in pixels), excluding the border. .IP "\f(CWXtNx\fP" 5n .br The x-coordinate of the widget's upper-left outer corner, relative to the upper-left inner corner of its parent. .IP "\f(CWXtNy\fP" 5n .br The y-coordinate of the widget's upper-left outer corner, relative to the upper-left inner corner of its parent. .\" .SH "Class Structure" The Core class structure is defined as follows: .Ps .ta +4.5n +2.25i typedef struct _CoreClassPart { WidgetClass superclass; /* pointer to superclass ClassRec */ String class_name; /* widget resource class name */ Cardinal widget_size; /* size in bytes of widget record */ XtProc class_initialize; /* class initialization proc */ XtWidgetClassProc class_part_initialize; /* dynamic initialization */ XtEnum class_inited; /* has class been initialized? */ XtInitProc initialize; /* initialize subclass fields */ XtArgsProc initialize_hook; /* notify that initialize called */ XtRealizeProc realize; /* XCreateWindow for widget */ XtActionList actions; /* widget semantics name to proc map */ Cardinal num_actions; /* number of entries in actions */ XtResourceList resources; /* resources for subclass fields */ Cardinal num_resources; /* number of entries in resources */ XrmClass xrm_class; /* resource class quarkified */ Boolean compress_motion; /* compress MotionNotify for widget */ XtEnum compress_exposure; /* compress Expose events for widget*/ Boolean compress_enterleave; /* compress enter and leave events */ Boolean visible_interest; /* select for VisibilityNotify */ XtWidgetProc destroy; /* free data for subclass pointers */ XtWidgetProc resize; /* geom manager changed widget size */ XtExposeProc expose; /* redisplay window */ XtSetValuesFunc set_values; /* set subclass resource values */ XtArgsFunc set_values_hook; /* notify that set_values called */ XtAlmostProc set_values_almost; /* set_values got "Almost" geo reply */ XtArgsProc get_values_hook; /* notify that get_values called */ XtAcceptFocusProc accept_focus; /* assign input focus to widget */ XtVersionType version; /* version of Intrinsics used */ XtPointer callback_private; /* list of callback offsets */ String tm_table; /* default translation table */ XtGeometryHandler query_geometry; /* return preferred geometry */ XtStringProc display_accelerator; /* display your accelerator */ XtPointer extension; /* pointer to extension record */ } CoreClassPart; typedef struct { CoreClassPart core_class; } WidgetClassRec, *WidgetClass, CoreClassRec, *CoreWidgetClass; .Pe The meanings of each of the fields in the Core class structure are as follows: .\" .IP \f(CWsuperclass\fP 5n .XX "Core class fields: superclass" A pointer to the class record of this widget's superclass. That class record is declared in the superclass' private header file. .\" .IP \f(CWclass_name\fP 5n .XX "Core class fields: class_name" A constant string that names the class. .\" .IP \f(CWwidget_size\fP 5n .XX "Core class fields: widget_size" The size of the \fIinstance\fP structure for this widget. Use \f(CWsizeof\fP. .\" .IP \f(CWclass_initialize()\fP 5n .XX "Core class fields: class_initialize" The \f(CWclass_initialize()\fP method called to perform one-time initialization for this class. See the reference page in Section 4. This is a chained method which cannot be inherited. Set to \f(CWNULL\fP if no special initialization is needed for the class. .\" .IP \f(CWclass_part_initialize()\fP 5n .XX "Core class fields: class_part_initialize" The \f(CWclass_part_initialize()\fP method called to perform initialization for the class part structure. See the reference page in Section 4. This is a chained method which cannot be inherited. Set to \f(CWNULL\fP if no special initialization is needed for your class part. .\" .IP \f(CWclass_inited\fP 5n .XX "Core class fields: class_inited" Whether the class structure has been initialized yet. Always initialize to \f(CWFalse\fP. .\" .Nd 4 .IP \f(CWinitialize()\fP 5n .XX "Core class fields: initialize" The \f(CWinitialize()\fP method called to initialize the instance structure. See the reference page in Section 4. This is a chained method which cannot be inherited. Set to \f(CWNULL\fP if no special initialization of the widget instance structure is needed. .\" .IP \f(CWinitialize_hook()\fP 5n .XX "Core class fields: initialize_hook" The (obsolete) \f(CWinitialize_hook()\fP method. See the reference page in Section 4. This is a chained method which cannot be inherited. Set to \f(CWNULL\fP if no special initialization is needed. .\" .IP \f(CWrealize()\fP 5n .XX "Core class fields: realize" The \f(CWrealize()\fP method called to create a window for the widget. See the reference page in Section 4. Use \f(CWXtInheritRealize\fP to inherit the \f(CWrealize()\fP method of the superclass. .\" .IP \f(CWactions\fP 5n .XX "Core class fields: actions" The action name to action procedure mapping which will be used by this widget when binding translation tables to actions. These are automatically registered with the Intrinsics when the Core \f(CWclass_part_initialize()\fP method is performed. The array must be permanently allocated, and the Intrinsics may overwrite it with an internal compiled form of the action table. The action names must be permanently allocated strings. .\" .IP \f(CWnum_actions\fP 5n .XX "Core class fields: num_actions" The number of elements in the \f(CWactions\fP array. .\" .IP \f(CWresources\fP 5n .XX "Core class fields: resources" An array of \f(CWXtResource\fP, each element of which defines a single resource for the widget. See \f(CWXtGetApplicationResources\fP(1) for an explanation of how to define resources. .\" .IP \f(CWnum_resources\fP 5n .XX "Core class fields: num_resources" The number of elements in the \f(CWresources\fP array. .\" .IP \f(CWxrm_class\fP 5n .XX "Core class fields: xrm_class" This field is private to the Resource Manager. Initialize it to \f(CWNULLQUARK\fP. .\" .IP \f(CWcompress_motion\fP 5n .XX "Core class fields: compress_motion" If \f(CWTrue\fP, the Intrinsics will only report the last of a sequence of pointer motion events. .\" .IP \f(CWcompress_exposure\fP 5n .XX "Core class fields: compress_exposure" Specifies how \f(CWExpose\fP and \f(CWGraphicsExpose\fP events should be delivered to the widget. If \f(CWFalse\fP or \f(CWXtExposeNoCompress\fP, all exposure events will be delivered. There are a number of other possibilities; see \f(CWexpose\fP(4) for full details. .\" .IP \f(CWcompress_enterleave\fP 5n .XX "Core class fields: compress_enterleave" If \f(CWTrue\fP, the Intrinsics will discard pairs of enter and leave events from the input queue that have no intervening events between them. .\" .Nd 10 .IP \f(CWvisible_interest\fP 5n .XX "Core class fields: visible_interest" If \f(CWTrue\fP, the Intrinsics will request \f(CWVisibilityNotify\fP events for the Widget and update the \f(CWvisible\fP field of the Core \fIinstance\fP structure as they arrive. The \f(CWvisible\fP field is guaranteed to be \f(CWTrue\fP by the time an exposure event is processed (i.e., by the time the \f(CWexpose()\fP method is called) if any part of the widget is visible, but is \f(CWFalse\fP if the widget is fully obscured. If \f(CWvisible_interest\fP is \f(CWFalse\fP, then the \f(CWvisible\fP instance field is always \f(CWTrue\fP. .\" .IP \f(CWdestroy()\fP 5n .XX "Core class fields: destroy" The \f(CWdestroy()\fP method called when a widget of this class is destroyed. See the reference page in Section 4. This is a chained method and cannot be inherited. Initialize it to \f(CWNULL\fP if no special processing needs to be done when an instance of this widget class is destroyed. .\" .IP \f(CWresize()\fP 5n .XX "Core class fields: resize" The \f(CWresize()\fP method called when a widget of this class is resized by its parent. See the reference page in Section 4. Use \f(CWXtInheritResize\fP to inherit the \f(CWresize()\fP method of the superclass. .\" .IP \f(CWexpose()\fP 5n .XX "Core class fields: expose" The \f(CWexpose()\fP method called when exposure events arrive for this widget. See the reference page in Section 4. Use \f(CWXtInheritExpose\fP to inherit the \f(CWexpose()\fP method of the superclass. .\" .IP \f(CWset_values()\fP 5n .XX "Core class fields: set_values" The \f(CWset_values()\fP method called when an application sets resource values in the instance record with \f(CWXtSetValues()\fP. See the reference page in Section 4. This is a chained method and cannot be inherited. Specify \f(CWNULL\fP if the widget class has no resources. .\" .IP \f(CWset_values_hook()\fP 5n .XX "Core class fields: set_values_hook" The (obsolete) \f(CWset_values_hook()\fP method. See the reference page in Section 4. This method is chained and cannot be inherited. .\" .IP \f(CWset_values_almost()\fP 5n .XX "Core class fields: set_values_almost" The \f(CWset_values_almost()\fP method called when a geometry request in an \f(CWXtSetValues()\fP call cannot be completely satisfied. See the reference page in Section 4. Use \f(CWXtInheritSetValuesAlmost\fP to inherit the \f(CWset_values_almost()\fP method of the superclass. .\" .IP \f(CWget_values_hook()\fP 5n .XX "Core class fields: get_values_hook" The \f(CWget_values_hook()\fP method called in response to \f(CWXtGetValues()\fP. See the reference page in Section 4. This is a chained method and cannot be inherited. .\" .IP \f(CWaccept_focus()\fP 5n .XX "Core class fields: accept_focus" The \f(CWaccept_focus()\fP method called by a parent to offer keyboard focus to a child. See the reference page in Section 4. Use \f(CWXtInheritAcceptFocus\fP to inherit the \f(CWaccept_focus()\fP method of the superclass. .\" .IP \f(CWversion\fP 5n .XX "Core class fields: version" The \f(CIversion\fP field indicates the toolkit implementation version number and is used for runtime consistency checking of the toolkit and widgets in an application. Widget writers must set it to the implementation-defined symbolic value \f(CWXtVersion\fP in the widget class structure initialization. Those widget writers who believe that their widget binaries are compatible with other implementations of the Intrinsics can put the special value \f(CWXtVersionDontCheck\fP in the \f(CIversion\fP field to disable version checking for those widgets. If a widget needs to compile alternative code for different revisions of the Intrinsics interface definition, it may use the symbol \f(CWXtSpecificationRelease\fP. Use of \f(CWXtVersion\fP allows the Intrinsics implementation to recognize widget binaries that were compiled with older implementations. .\" .IP \f(CWcallback_private\fP 5n .XX "Core class fields: callback_private" This field is private to callback handling; initialize to \f(CWNULL\fP. .\" .IP \f(CWtm_table\fP 5n .XX "Core class fields: tm_table" The default translation table for widgets of this class. It may be overridden by clients that set the \f(CWXtNtranslations\fP resource of the widget instance. This field should specify a translation table in string form (see Appendix F for the syntax); the Intrinsics will automatically compile it into an internal form. Use \f(CWXtInheritTranslations\fP to inherit the translation table of the superclass. .\" .IP \f(CWquery_geometry()\fP 5n .XX "Core class fields: query_geometry" The \f(CWquery_geometry()\fP method, called by a parent widget to discover the preferred geometry of a child. See the reference page in Section 4. Use \f(CWXtInheritQueryGeometry\fP to inherit the \f(CWquery_geometry()\fP method of the superclass. .\" .IP \f(CWdisplay_accelerator()\fP 5n .XX "Core class fields: display_accelerator" The \f(CWdisplay_accelerator()\fP method, called when a widget's accelerators have been installed on a destination widget. See the reference page in Section 4. Use \f(CWXtInheritDisplayAccelerator\fP to inherit the \f(CWdisplay_accelerator()\fP method of the superclass. .\" .IP \f(CWextension\fP 5n .XX "Core class fields: extension" A linked list of extension records. There are currently no extensions defined for the Core widget class, so this field should be initialized to \f(CWNULL\fP. .\" .SH "Instance Structure" The Core instance record contains at least the following fields. The fields need not be in the order shown, but because the Object and RectObj superclasses were defined after Core was standardized, Core duplicates the instance records of those classes, and the duplicate fields must be in the same position in the Object, RectObj, and Core instance structures. .Ps .ps 8 .ta +3n +2.35i typedef struct { Widget self; /* pointer to widget itself */ WidgetClass widget_class; /* pointer to widget's ClassRec */ Widget parent; /* parent widget */ Boolean being_destroyed; /* marked for destroy */ XtCallbackList destroy_callbacks; /* called when widget destroyed */ XtPointer constraints; /* constraint record */ Position x, y; /* window position */ Dimension width, height; /* window dimensions */ Dimension border_width; /* window border width */ Boolean managed; /* is widget geometry managed? */ Boolean sensitive; /* is widget sensitive to user events */ Boolean ancestor_sensitive; /* are all ancestors sensitive? */ XtTranslations accelerators; /* accelerator translations */ Pixel border_pixel; /* window border pixel */ Pixmap border_pixmap; /* window border pixmap or NULL */ WidgetList popup_list; /* list of pop ups */ Cardinal num_popups; /* how many pop ups */ String name; /* widget resource name */ Screen *screen; /* window's screen */ Colormap colormap; /* colormap */ Window window; /* window ID */ Cardinal depth; /* number of planes in window */ Pixel background_pixel; /* window background pixel */ Pixmap background_pixmap; /* window background pixmap or NULL */ Boolean visible; /* is window mapped and not occluded? */ Boolean mapped_when_managed; /* map window if it is managed? */ } CorePart; typedef struct { CorePart core; } WidgetRec, *Widget, CoreRec, *CoreWidget; .Pe .\" .SH "See Also" \s-1\fICore\fR\s+1\*(s3, \s-1\fIObject\fR\s+1\*(s3, \s-1\fIRectObj\fR\s+1\*(s3, .br \s-1\fIclass_initialize\fR\s+1\*(s4, \s-1\fIclass_part_initialize\fR\s+1\*(s4, \s-1\fIdestroy\fR\s+1\*(s4, \s-1\fIdisplay_accelerator\fR\s+1\*(s4, \s-1\fIexpose\fR\s+1\*(s4, .br \s-1\fIget_values_hook\fR\s+1\*(s4, \s-1\fIinitialize\fR\s+1\*(s4, \s-1\fIinitialize_hook\fR\s+1\*(s4, \s-1\fIquery_geometry\fR\s+1\*(s4, \s-1\fIrealize\fR\s+1\*(s4, \s-1\fIresize\fR\s+1\*(s4, .br \s-1\fIset_values\fR\s+1\*(s4, \s-1\fIset_values_almost\fR\s+1\*(s4, \s-1\fIset_values_hook\fR\s+1\*(s4. .\"last line comment ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" ...\" ...\" ...\" ...\" ...\" ...\" [23.VII.93] ...\" ...\" ...\" ...\" ...\" ---------------------------------------------------------------------- ...\".H 1 "DCE Threads Data Types" ...\" ---------------------------------------------------------------------- ...\" .nr H1 3 ...\" .rm zA .rm zZ .TH datatypes 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .SH NAME .PP \*Lthreads data types\*O - Data Types used by DCE Threads .wH "" .SH "DESCRIPTION" .PP The DCE Threads data types can be divided into two broad categories, Primitive System and Application Level. ...\" ...\" ---------------------------------------------------------------------- ...\".H 2 "Primitive System Data Types" ...\" ---------------------------------------------------------------------- ...\" .SS "Primitive System Data Types" .PP The first consists of types that represent structures used by (and internal to) DCE Threads. These are defined as being primitive system data types: ...\" ...\" .ML .LI \*Lpthread_attr_t\*O .LI \*Lpthread_cond_t\*O .LI \*Lpthread_condattr_t\*O .LI \*Lpthread_key_t\*O .LI \*Lpthread_mutex_t\*O .LI \*Lpthread_mutexattr_t\*O .LI \*Lpthread_once_t\*O .LI \*Lpthread_t\*O .LE ...\" ...\" .PP Although applications must know about these types, passing them in and receiving them from various DCE Threads routines, the structures themselves are opaque: they cannot be directly modified by applications, and they can be manipulated only (and only in some cases) through specific DCE Threads routines. (The \*Lpthread_key_t\*O type is somewhat different from the others in this list, in that it is essentially a handle to a thread-private block of memory requested by a call to \*Lpthread_keycreate(\|)\*O.) ...\" ...\" ...\" ...\" ---------------------------------------------------------------------- ...\".H 2 "Application Level Data Types" ...\" ---------------------------------------------------------------------- ...\" .SS "Application Level Data Types" .PP The second category of DCE Threads data consists of types used to describe objects that originate in the application: ...\" ...\" .ML .LI \*Lpthread_addr_t\*O .LI \*Lpthread_destructor_t\*O .LI \*Lpthread_initroutine_t\*O .LI \*Lpthread_startroutine_t\*O .LI \*Lsigset_t\*O .LE ...\" ...\" .PP All of the above types, with the exception of the last, are various kinds of memory addresses that must be passed by callers of certain DCE Threads routines. These types are extensions to POSIX. They permit DCE Threads to be used on platforms that are not fully ANSI C compliant. While being extensions to permit the use of compilers that are not ANSI C compatible, they are fully portable data types. .PP The last data type, \*Lsigset_t\*O, exhibits properties of both primitive system and application level data types. While objects of this type originate in the application, the data type is opaque. A set of functions is provided to manipulate objects of this type. .PP For further information, see the following descriptions, listed in sorted order. ...\" ...\" ...\" There is some question about sigset_t; this seems to be some- ...\" thing that the application must fiddle with, but I don't see ...\" any description of it anywhere. ...\" ...\" ...\" ---------------------------------------------------------------------- ...\".H 2 "Data Type Descriptions" ...\" ---------------------------------------------------------------------- ...\" .nP .SH "DATA TYPE DESCRIPTIONS" .PP Following are individual descriptions of each of the DCE Threads data types. The descriptions include the routines where the data type is modified, e.g., created, changed or deleted/destroyed, but not the routines referencing or using them that do not change them. ...\" ...\" ...\" .ML .LI \*Lpthread_addr_t\*O .PP A miscellaneous data type representing an address value that must be passed by the caller of various Threads routines. Usually the \*Lpthread_addr_t\*O value is the address of an area which contains various parameters to be made accessible to an implicitly called routine. For example, when the \*Lpthread_create(\|)\*O routine is called, one of the parameters passed is a \*Lpthread_addr_t\*O value that contains an address which will be passed to the \*Vstart_routine\*O which the thread is being created to execute; presumably the routine will extract necessary parameters from the area referenced by this address. ...\" ...\" ...\" ...\" .LI \*Lpthread_attr_t\*O .PP Threads attribute object, used to specify the attributes of a thread when it is created by a call to \*Lpthread_create(\|)\*O. The object is created by a call to \*Lpthread_attr_create(\|)\*O, then modified as desired by calls to: .in 5 .ML .LI \*Lpthread_attr_setinheritsched(\|)\*O .LI \*Lpthread_attr_setprio(\|)\*O .LI \*Lpthread_attr_setsched(\|)\*O .LI \*Lpthread_attr_setstacksize(\|)\*O .LE .PP (Note that there are \*L_get\*O versions of these four calls, which can be used to retrieve the respective values.) .in -5 ...\" ...\" ...\" ...\" ...\" .LI \*Lpthread_cond_t\*O .PP Data type representing a Threads condition variable. The variable is created by a call to \*Lpthread_cond_init(\|)\*O, and destroyed by a call to \*Lpthread_cond_destroy(\|)\*O. ...\" ...\" ...\" ...\" .LI \*Lpthread_condattr_t\*O .PP Data type representing a Threads condition variable attributes object. Created by a call to \*Lpthread_condattr_create(\|)\*O. The range of possible modifications to a condition variable attributes object is not great: creation (via \*Lpthread_condattr_create(\|)\*O) and deletion (via \*Lpthread_condattr_delete(\|)\*O) are all. The object is created with default values. ...\" ...\" ...\" ...\" .LI \*Lpthread_destructor_t\*O .PP Data type, passed in a call to \*Lpthread_keycreate(\|)\*O, representing the address of a procedure to be called to destroy a data value associated with a unique thread-specific data key value when the thread terminates . ...\" ...\" ...\" ...\" ...\" ...\" .LI \*Lpthread_initroutine_t\*O .PP Data type representing the address of a procedure that performs a one-time initialization for a thread. It is passed in a call to \*Lpthread_once(\|)\*O. The \*Lpthread_once(\|)\*O routine, when called, executes the initialization routine. The specified routine is \*Vguaranteed to be executed only once\*O, even though the \*Lpthread_once(\|)\*O call occurs in multi-threaded code. ...\" ...\" ...\" ...\" .nP .LI \*Lpthread_key_t\*O .PP Data type representing a thread-specific data key, created by a call to \*Lpthread_keycreate(\|)\*O. The key is an address of memory. Associating a static block of memory with a specific thread in this way is an alternative to using stack memory for the thread. The key is destroyed by the application-supplied procedure specified by the routine specified using the \*Lpthread_destructor_t\*O data type in the call to \*Lpthread_keycreate(\|)\*O. ...\" ...\" ...\" ...\" ...\" .LI \*Lpthread_mutex_t\*O .PP Data type representing a mutex object. It is created by a call to \*Lpthread_mutex_init(\|)\*O and destroyed by a call to \*Lpthread_mutex_destroy(\|)\*O. Care should be taken not to attempt to destroy a locked object. ...\" ...\" ...\" ...\" ...\" .LI \*Lpthread_mutexattr_t\*O .PP Data type representing an attributes object which defines the characteristics of a mutex. Created by a call to \*Lpthread_mutexattr_create(\|)\*O; modified by calls to \*Lpthread_mutexattr_setkind_np(\|)\*O (which allows you to specify fast, recursive, or non-recursive mutexes); passed to \*Lpthread_mutex_init(\|)\*O to create the mutex with the specified atttributes. The only other modification allowed is to destroy the mutex attributes object, with \*Lpthread_mutexattr_delete(\|)\*O. ...\" ...\" ...\" ...\" ...\" .LI \*Lpthread_once_t\*O .PP A data structure that defines the characteristics of the one-time initialization routine executed by calling \*Lpthread_once(\|)\*O. The structure is opaque to the application, and cannot be modified by it, but it must be explicitly declared by the client code, and initialized by a call to \*Lpthread_once_init(\|)\*O. The \*Lpthread_once_t\*O type must not be an array. ...\" ...\" ...\" ...\" ...\" .LI \*Lpthread_startroutine_t\*O .PP Data type representing the address of the application routine or other routine, whatever it is, that a new thread is created to execute as its start routine. ...\" ...\" ...\" ...\" ...\" .LI \*Lpthread_t\*O .PP Data type representing a thread handle, created by a call to \*Lpthread_create(\|)\*O. The thread handle is used thenceforth to identify the thread to calls such as \*Lpthread_cancel(\|)\*O, \*Lpthread_detach(\|)\*O, \*Lpthread_equal(\|)\*O (to which two handles are passed for comparison), etc. ...\" ...\" ...\" ...\" .LI ...\" in pthread_signal_to_cancel.3: ...\" sigwait.3 ...\" \*Lsigset_t\*O .PP Data type representing a set of signals. It is always an integral or structure type. If a structure, it is intended to be a simple structure, e.g., a set of arrays as opposed to a set of pointers. It is opaque in that a set of functions called the \*Lsigsetops\*O primitives is provided to manipulate signal sets. They operate on signal set data objects addressable by the application, not on any objects known to the system. .PP The primitives are \*Lsigemptyset(\|)\*O and \*Lsigfillset(\|)\*O which initialize the set as either empty or full, \*Lsigaddset(\|)\*O and \*Lsigdelset(\|)\*O which add or delete signals from the set, and \*Lsigismember(\|)\*O which permits the application to check if a object (signal) of type \*Lsigset_t\*O is a member of the signal set. Applications must call at least one of the initialization primitives at least once for each object of type \*Lsigset_t\*O prior to any other use of that object (signal set). .PP The object, or objects, represented by this data type when used by \*Lsigaction(\|)\*O is (are) used in conjunction with a \*Lsigaction\*O structure by the \*Lsigaction\*O function to describe an action to be taken with (a) specified \*Lsigset_t\*O-type object(\|s\|). ...\" ...\" ...\" ...\" .LE ...\" ...\" ---------------------------------------------------------------------- .TH DBE 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME DBE - Double Buffer Extension .SH SYNOPSIS The Double Buffer Extension (DBE) provides a standard way to utilize double-buffering within the framework of the X Window System. Double-buffering uses two buffers, called front and back, which hold images. The front buffer is visible to the user; the back buffer is not. Successive frames of an animation are rendered into the back buffer while the previously rendered frame is displayed in the front buffer. When a new frame is ready, the back and front buffers swap roles, making the new frame visible. Ideally, this exchange appears to happen instantaneously to the user, with no visual artifacts. Thus, only completely rendered images are presented to the user, and remain visible during the entire time it takes to render a new frame. The result is a flicker-free animation. .SH DESCRIPTION .B Concepts .RS Normal windows are created using .B XCreateWindow() or .B XCreateSimpleWindow(), which allocate a set of window attributes and, for InputOutput windows, a front buffer, into which an image can be drawn. The contents of this buffer will be displayed when the window is visible. This extension enables applications to use double-buffering with a window. This involves creating a second buffer, called a back buffer, and associating one or more back buffer names .I (XIDs) with the window, for use when referring to (i.e., drawing to or reading from) the window's back buffer. The back buffer name is a drawable of type .I XdbeBackBuffer. DBE provides a relative double-buffering model. One XID, the window, always refers to the front buffer. One or more other XIDs, the back buffer names, always refer to the back buffer. After a buffer swap, the window continues to refer to the (new) front buffer, and the back buffer name continues to refer to the (new) back buffer. Thus, applications and toolkits that want to just render to the back buffer always use the back buffer name for all drawing requests to the window. Portions of an application that want to render to the front buffer always use the window XID for all drawing requests to the window. Multiple clients and toolkits can all use double-buffering on the same window. DBE does not provide a request for querying whether a window has double-buffering support, and if so, what the back buffer name is. Given the asynchronous nature of the X Window System, this would cause race conditions. Instead, DBE allows multiple back buffer names to exist for the same window; they all refer to the same physical back buffer. The first time a back buffer name is allocated for a window, the window becomes double-buffered and the back buffer name is associated with the window. Subsequently, the window already is a double-buffered window, and nothing about the window changes when a new back buffer name is allocated, except that the new back buffer name is associated with the window. The window remains double-buffered until either the window is destroyed, or until all of the back buffer names for the window are deallocated. In general, both the front and back buffers ae treated the same. In particular, here are some important characteristics: .RS Only one buffer per window can be visible at a time (the front buffer). Both buffers associated with a window have the same visual type, depth, width, height, and shape as the window. Both buffers associated with a window are "visible" (or "obscured") in the same way. When an Expose event is generated for a window, this event is considered to apply to both buffers equally. When a double-buffered window is exposed, both buffers are tiled with the window background. Even though the back buffer is not visible, terms such as obscure apply to the back buffer as well as to the front buffer. It is acceptable at any time to pass an .I XdbeBackBuffer in any function that expects a drawable. This enables an application to draw directly into .I XdbeBackBuffer in the same fashion as it would draw into any other drawable. It is an error (Window) to pass an .I XdbeBackBuffer in a function that expects a Window. An .I XdbeBackBuffer will never be sent in a reply, event, or error where a Window is specified. If backing-store and save-under applies to a double-buffered window, it applies to both buffers equally. If the .B XClearArea() or .B XClearWindow() function is executed on a double-buffered window, the same area in both the front and back buffers is cleared. .RE The effect of passing a window to a function that accepts a drawable is unchanged by this extension. The window and front buffer are synonomous with each other. This includes obeying the .B XGetImage() and .B XGetSubImage() semantics and the subwindow-mode semantics if a graphics context is involved. Regardless of whether the window was explicitly passed in an .B XGetImage() or .B XGetSubImage() call, or implicitly referenced (i.e., one of the window's ancestors was passed in the function), the front (i.e. visible) buffer is always referenced. Thus, DBE-naive screen dump clients will always get the front buffer. .B XGetImage() and .B XGetSubImage() on a back buffer return undefined image contents for any obscured regions of the back buffer that fall within the image. Drawing to a back buffer always uses the clip region that would be used to draw to the front buffer with a GC subwindow-mode of ClipByChildren. If an ancestor of a double-buffered window is drawn to with a GC having a subwindow-mode of IncludeInferiors, the effect on the double-buffered window's back buffer depends on the depth of the double-buffered window and the ancestor. If the depths are the same, the contents of the back buffer of the double-buffered window are not changed. If the depths are different, the contents of the back buffer of the double-buffered window are undefined for the pixels that the IncludeInferiors drawing touched. DBE adds no new events. DBE does not extend the semantics of any existing events with the exception of adding a new drawable type called .I XdbeBackBuffer. If events, replies, or errors that contain a drawable (e.g., GraphicsExpose) are generated in response to a request, the drawable returned will be the one specified in the request. DBE advertises which visuals support double buffering. DBE does not include any timing or synchronization facilities. Applications that need such facilities (e.g., to maintain a constant frame rate) should investigate the Synchronization Extension, an X Consortium standard. .RE .B Window Management Operations .RS The basic philosophy of DBE is that both buffers are treated the same by X window management operations. When a double-buffered window is destroyed, both buffers associated with the window are destroyed, and all back buffer names associated with the window are freed. If the size of a double-buffered window changes, both buffers assume the new size. If the window's size increases, the effect on the buffers depends on whether the implementation honors bit gravity for buffers. If bit gravity is implemented, then the contents of both buffers are moved in accordance with the window's bit gravity, and the remaining areas are tiled with the window background. If bit gravity is not implemented, then the entire unobscured region of both buffers is tiled with the window background. In either case, Expose events are generated for the region that is tiled with the window background. If the .B XGetGeometry() function is executed on an .I XdbeBackBuffer, the returned x, y, and border-width will be zero. If the Shape extension .B ShapeRectangles, ShapeMask, ShapeCombine, or .B ShapeOffset request is executed on a double-buffered window, both buffers are reshaped to match the new window shape. The region difference D = new shape - old shape is tiled with the window background in both buffers, and Expose events are generated for D. .RE .B Complex Swap Actions .RS DBE has no explicit knowledge of ancillary buffers (e.g. depth buffers or alpha buffers), and only has a limited set of defined swap actions. Some applications may need a richer set of swap actions than DBE provides. Some DBE implementations have knowledge of ancillary buffers, and/or can provide a rich set of swap actions. Instead of continually extending DBE to increase its set of swap actions, DBE provides a flexible "idiom" mechanism. If an applications's needs are served by the defined swap actions, it should use them; otherwise, it should use the following method of expressing a complex swap action as an idiom. Following this policy will ensure the best possible performance across a wide variety of implementations. As suggested by the term "idiom," a complex swap action should be expressed as a group/series of requests. Taken together, this group of requests may be combined into an atomic operation by the implementation, in order to maximize performance. The set of idioms actually recognized for optimization is implementation dependent. To help with idiom expression and interpretation, an idiom must be surrounded by two function calls: .B XdbeBeginIdiom() and .B XdbeEndIdiom(). Unless this begin-end pair surrounds the idiom, it may not be recognized by a given implementation, and performance will suffer. For example, if an application wants to swap buffers for two windows, and use X to clear only certain planes of the back buffers, the application would make the following calls as a group, and in the following order: .RS .B XdbeBeginIdiom(). .B XdbeSwapBuffers() with XIDs for two windows, each of which uses a swap action of Untouched. .B XFillRectangle() to the back buffer of one window. .B XFillRectangle() to the back buffer of the other window. .B XdbeEndIdiom(). .RE The .B XdbeBeginIdiom() and .B XdbeEndIdiom() functions do not perform any actions themselves. They are treated as markers by implementations that can combine certain groups/series of requests as idioms, and are ignored by other implementations or for non-recognized groups/series of requests. If these function calls are made out of order, or are mismatched, no errors are sent, and the functions are executed as usual, though performance may suffer. .B XdbeSwapBuffers() need not be included in an idiom. For example, if a swap action of Copied is desired, but only some of the planes should be copied, .B XCopyArea() may be used instead of .B XdbeSwapBuffers(). If .B XdbeSwapBuffers() is included in an idiom, it should immediately follow the .B XdbeBeginIdiom() call. Also, when the .B XdbeSwapBuffers() is included in an idiom, that request's swap action will still be valid, and if the swap action might overlap with another request, then the final result of the idiom must be as if the separate requests were executed serially. For example, if the specified swap action is Untouched, and if a .B XFillRectangle() using a client clip rectangle is done to the window's back buffer after the .B XdbeSwapBuffers() call, then the contents of the new back buffer (after the idiom) will be the same as if the idiom was not recognized by the implementation. It is highly recommended that API providers define, and application developers use, "convenience" functions that allow client applications to call one procedure that encapsulates common idioms. These functions will generate the .B XdbeBeginIdiom(), idiom, and .B XdbeEndIdiom() calls. Usage of these functions will ensure best possible performance across a wide variety of implementations. .SH SEE ALSO .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .\" $Header: regexp.3x,v 72.5 94/11/15 09:56:02 ssa Exp $ .TA r .TH regexp 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compile(\|), step(\|), advance(\|) \- regular expression compile and match routines .SH SYNOPSIS .C #define INIT .I "declarations" .br .C #define GETC() .I "getc statements" .br .C #define PEEKC() .I "peekc statements" .br .C #define UNGETC(c) .I "ungetc statements" .br .C #define RETURN(pointer) .I "return statements" .br .C #define ERROR(val) .I "error statements" .PP .C "#include " .PP .C "char *compile(" .nf .PD 0 .IP .C "const char *instring," .C "char *expbuf," .C "const char *endbuf," .C "int eof" .PP .C ");" .PD .fi .PP .C "int step(const char *string, const char *expbuf);" .PP .C "int advance(const char *string, const char *expbuf);" .PP .C "extern char *loc1, *loc2, *locs;" .PP .C "extern int circf, sed, nbra;" .SS Remarks Features documented in this manual entry are obsolescent and may be removed in a future .SM HP-UX release. Use of .IR regcomp (3C) functions instead is recommended. .SH DESCRIPTION These functions are general-purpose regular expression matching routines to be used in programs that perform Basic Regular Expression (see .IR regexp (5)) matching. These functions are defined in .RC < regexp.h >. .PP The functions .C step() and .C advance() do pattern matching given a character string and a compiled regular expression as input. .C compile() takes a Basic Regular Expression as input and produces a compiled expression that can be used with .C step() and .CR advance() . .PP The interface to this file is unpleasantly complex. Programs that include this file must have the following five macros declared before the .C #include statement. These macros are used by the .C compile() routine. .TP 15 .C GETC() Return the value of the next byte in the regular expression pattern. Successive calls to .C GETC() should return successive bytes of the regular expression. .TP .C PEEKC() Return the next byte in the regular expression. Successive calls to .C PEEKC() should return the same byte (which should also be the next byte returned by .CR GETC() . .TP .CI UNGETC( c ) Cause the argument .I c to be returned by the next call to .C GETC() (and .CR PEEKC() ). No more than one byte of pushback is ever needed, and this byte is guaranteed to be the last byte read by .CR GETC() . The value of the macro .CI UNGETC( c ) is always ignored. .TP .CI RETURN( pointer ) This macro is used on normal exit of the .C compile() routine. The value of the argument .I pointer is a pointer to the character after the last character of the compiled regular expression. This is useful to programs that must manage memory allocation. .TP .CI ERROR( val ) This is the abnormal return from the .C compile() routine. The argument .I val is an error number (see table below for meanings). This call should never return. .RS .RS .PD 0 .TP 8 .B Error .B Meaning .TP 11 Range endpoint too large. .TP 16 Bad number. .TP 25 ``\f3\e\f2digit\f1'' out of range. .TP 36 Illegal or missing delimiter. .TP 41 No remembered search string. .TP 42 .C \e( \e) imbalance. .TP 43 Too many .CR \e( . .TP 44 More than 2 numbers given in .CR \e{\0\e} . .TP 45 .C } expected after .CR \e . .TP 46 First number exceeds second in .CR \e{\0\e} . .TP 49 .C [ ] imbalance. .TP 50 Regular expression overflow. .RE .RE .PD .PP The syntax of the .C compile() routine is as follows: .IP .CI compile( instring , .CI expbuf , .CI endbuf , .CI eof ) .PP The first parameter .I instring is never used explicitly by the .C compile() routine, but is useful for programs that pass down different pointers to input characters. It is sometimes used in the .C INIT declaration (see below). Programs that call functions to input characters or have characters in an external array can pass down a value of .C ((char *) 0) for this parameter. .PP The next parameter .I expbuf is a character pointer. It points to the location where the compiled regular expression will be placed. .PP The parameter .I endbuf is one more than the highest address where the compiled regular expression can be placed. If the compiled expression cannot fit in .RI ( endbuf \|\(mi\| expbuf ) bytes, a call to .C ERROR(50) is made. .PP The parameter .I eof is the character which marks the end of the regular expression. For example, in .IR ed (1), this character is usually a .CR / . .PP Each program that includes this file must have a .C #define statement for .CR INIT . This definition is placed right after the declaration for the function .C compile() and the opening curly brace .CR { . It is used for dependent declarations and initializations. Most often it is used to set a register variable to point to the beginning of the regular expression so that this register variable can be used in the declarations for .CR GETC() , .CR PEEKC() , and .CR UNGETC() . Otherwise it can be used to declare external variables that might be used by .CR GETC() , .CR PEEKC() , and .CR UNGETC() . See the example below of the declarations taken from .IR grep (1). .PP .C step() also performs actual regular expression matching in this file. The call to .I step is as follows: .IP .CI step( string , .CI expbuf ) .PP The first parameter to .C step() is a pointer to a string of characters to be checked for a match. This string should be null-terminated. .PP The second parameter .I expbuf is the compiled regular expression that was obtained by a call to .CR compile() . .PP .C step() returns non-zero if the given string matches the regular expression, and zero if the expressions do not match. If there is a match, two external character pointers are set as a side effect to the call to .CR step() . The variable set in .C step() is .CR loc1 . This is a pointer to the first character that matched the regular expression. The variable .CR loc2 , which is set by the function .CR advance() , points to the character after the last character that matches the regular expression. Thus, if the regular expression matches the entire line, .C loc1 points to the first character of .I string and .C loc2 points to the null at the end of .IR string . .PP .C step() uses the external variable .CR circf() , which is set by .C compile() if the regular expression begins with .CR ^ . If this is set, .C step() tries to match the regular expression to the beginning of the string only. If more than one regular expression is to be compiled before the first is executed, the value of .I circf should be saved for each compiled expression and .I circf should be set to that saved value before each call to .CR step() . .PP .C advance() is called from .C step() with the same arguments as .CR step() . The purpose of .C step() is to step through the .I string argument and call .C advance() until .C advance() returns non-zero, which indicates a match, or until the end of .I string is reached. To constrain .I string to beginning-of-line in all cases, .C step() need not be called; simply call .CR advance() . .PP When .C advance() encounters a .C * or .C \e{\|\e} sequence in the regular expression, it advances its pointer to the string to be matched as far as possible and recursively calls itself, trying to match the rest of the string to the rest of the regular expression. As long as there is no match, .I advance backs up along the string until it finds a match or reaches the point in the string that initially matched the .C * or .CR \e{\|\e} . It is sometimes desirable to stop this backing up before the initial point in the string is reached. If the external character pointer .C locs is equal to the point in the string at sometime during the backing up process, .C advance() breaks out of the loop that backs up and returns zero. This is used by .IR ed (1) and .IR sed (1) for substitutions done globally (not just the first occurrence, but the whole line) so, for example, expressions such as .C s/y*//g do not loop forever. .PP The additional external variables .C sed and .C nbra are used for special purposes. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions. .PP The .C LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, and the characters matched by character class expressions in regular expressions. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following is an example of how the regular expression macros and calls look from .IR grep (1): .nf .IP .C "#define INIT register char *sp = instring;" .C "#define GETC() (*sp++)" .C "#define PEEKC() (*sp)" .C "#define UNGETC(c) (--sp)" .C "#define RETURN(c) return;" .C "#define ERROR(c) regerr()" .IP .C "#include " \h'.5i'.\|.\|. .C "(void) compile(*argv, expbuf, &expbuf[ESIZE], '\e0');" \h'.5i'.\|.\|. .C "if (step(linebuf, expbuf))" .C " succeed();" .fi .SH AUTHOR .CR regexp() was developed by OSF and HP. .SH SEE ALSO grep(1), regcomp(3C), setlocale(3C), regexp(5). .SH STANDARDS CONFORMANCE .CR advance() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR compile() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc1 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc2 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR locs ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR step() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4compile()\f1 \- regular expression compile routine@@@\f3regexp(3X)\f1 .\" index@\f4step()\f1 \- regular expression string comparison routine@@@\f3regexp(3X)\f1 .\" index@\f4advance()\f1 \- regular expression substring comparison routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1expression, regular, compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1compile and match routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1comparison routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1match routines for regular expressions@@@\f3regexp(3X)\f1 .\" .\" toc@\f3regexp(3X)\f1:\0\0\f4compile()\f1, \f4step()\f1, \f4advance()\f1@@@regular expression compile and match routines .\" toc@\f4compile()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4step()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4advance()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" .\" links@regexp.3x compile.3x .\" links@regexp.3x step.3x .\" links@regexp.3x advance.3x .\" links@regexp.3x INIT.3x .\" links@regexp.3x GETC.3x .\" links@regexp.3x PEEKC.3x .\" links@regexp.3x UNGETC.3x .\" links@regexp.3x RETURN.3x .\" links@regexp.3x ERROR.3x .\" .\" fileset_database@regexp.3x PROGRAMING-MAN .\" $Header: nl_tools_16.3x,v 72.2 94/11/30 15:24:00 ssa Exp $ .TA n .TH nl_tools_16 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl_tools_16: ADVANCE(), byte_status(), BYTE_STATUS(), CHARADV(), CHARAT(), c_colwidth(), C_COLWIDTH(), firstof2(), FIRSTof2(), secof2(), SECof2(), WCHAR(), WCHARADV() \- tools to process 16-bit characters .SH SYNOPSIS .C "#include " .PP .C "int firstof2(int c);" .PP .C "int secof2(int c);" .PP .C "int byte_status(int c, int laststatus);" .PP .C int c_colwidth(int c); .PP .C "int FIRSTof2(int c);" .PP .C "int SECof2(int c);" .PP .C "int BYTE_STATUS(int c, int laststatus);" .PP .C "int C_COLWIDTH(int c);" .PP .C "int CHARAT(const char *p);" .PP .C "int ADVANCE(const char *p);" .PP .C "int CHARADV(const char *p);" .PP .C "int WCHAR(wchar_t wc, char *p);" .PP .C "int WCHARADV(wchar_t wc, char *p);" .PP .C "void PCHAR(int c, char *p);" .PP .C "void PCHARADV(int c, char *p);" .SS Remarks All interfaces listed above whose names begin with a capital letter are implemented as macros; the others are functions. .PP These macros and functions are obsolete. See WARNINGS. .SH DESCRIPTION The following macros and functions perform their operations based upon the loaded NLS environment (see .IR setlocale (3C)). .TP 20 .CR FIRSTof2() Takes a byte and returns a nonzero value if it can be the first byte of a two-byte character according to the NLS environment loaded, and zero if it cannot. .TP .CR SECof2() Takes a byte and returns a nonzero value if it can be the second byte of a two-byte character according to the loaded NLS environment, and zero if it cannot. .TP .CR BYTE_STATUS() Returns one of the following values based on the value of the current byte in .I c and the status of the previous byte interpreted in .I laststatus as returned by the last call to .CR BYTE_STATUS() . These are the status values as defined in .CR : .RS .RS .TP 15 .CR ONEBYTE Single-byte character .PD 0 .TP .CR SECOF2 Second byte of two-byte character .TP .CR FIRSTOF2 First byte of two-byte character .RE .RE .PD .IP To validate a two-byte character, both the first and second bytes must be valid. If the value of .I laststatus is .CR FIRSTOF2 but .CR SECof2( c ) returns false, .CI BYTE_STATUS( c , \ laststatus ) returns .CR ONEBYTE . .TP .CR C_COLWIDTH() Takes a byte which is assumed to be either a one-byte character or the first byte of a two-byte character, and returns the number of columns the character would occupy on a terminal display. .IP For the macros .CR BYTE_STATUS() , .CR C_COLWIDTH() , .CR FIRSTof2() , and .CR SEC0of2() , results are undefined for values of .I c less than \(mi1 (EOF) or greater than 255. .TP .CR CHARAT() Takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case, .CR CHARAT() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p . .TP .CR ADVANCE() Advances its pointer argument by the byte width of the character it is pointing at (either one or two bytes). .TP .CR CHARADV() Combines the functions of .CR CHARAT() and .CR ADVANCE() in a single macro. It takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case .CR CHARADV() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p , and advances .I p beyond the last byte of the character. .TP .CR WCHAR() Converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p . .CR WCHAR() returns the .CR wchar_t value .IR wc . .TP .CR WCHARADV() Combines the functions of .CR WCHAR() and .CR ADVANCE() in a single macro. It converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p , then advances .I p past the last byte. .CR WCHARADV() returns the .CR wchar_t value .IR wc . .TP .CR firstof2() .PD 0 .TP .CR secof2() .TP .CR byte_status() .TP .CR c_colwidth() .PD Subroutine versions of the corresponding macros. These functions can be called from languages other than C. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of single and/or multibyte characters. .SH WARNINGS The HP proprietary functions and macros described in this manual entry are .BR OBSOLETE . They are not portable to other vendor's systems, and will not be provided in future HP-UX releases. .PP For maximum portability, use the routines documented in the .IR multibyte (3C) manual entry for multibyte character processing. .PP Other macros listed in this manual entry cannot be used as the first argument to .CR WCHAR() or .CR WCHARADV() . For example, .IP .C "*t++ = *f++" .PP cannot be replaced by .IP .C "WCHARADV(CHARADV (f),t)" .PP Instead, use a method such as .IP .CR "int c; " ...\& " c = CHARADV (f)," .CR "WCHARADV (c,t)" .PP .CR WCHAR() and .CR WCHARADV() may produce a "null effect" warning from .IR lint (1) if not used as part of another expression or as part of a statement. This does not affect the functionality of either macro. .PP Note that .CR WCHAR() and .CR WCHARADV() are not "replace_char" macros. They do not prevent the second byte of a two-byte character from being left dangling if .CR WCHAR() or .CR WCHARADV() overwrite the first byte of the two-byte character with a single-byte character. .PP .CR CHARAT() , .CR ADVANCE() , and .CR CHARADV() do not examine the byte following the location pointed to by the argument to verify its validity as a .CR SECof2 byte. .SH AUTHOR .CR nl_tools_16() was developed by HP. .SH SEE ALSO setlocale(3C), multibyte(3C), wconv(3X), wctype(3X), hpnls(5). .\" .\" index@\f4ADVANCE()\f1 \- advance pointer to next 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARADV()\f1 \- get character and advance pointer to next character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARAT()\f1 \- get value of 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHAR()\f1, \- put 8- or 16-bit character in memory@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHARADV()\f1, \- put character in memory and advance pointer@@@\f3nl_tools_16(3X)\f1 .\" index@\f4byte_status()\f1, \f4BYTE_STATUS()\f1 \- test for valid 1- or 2-byte character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4firstof2()\f1, \f4FIRSTof2()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4secof2()\f1, \f4SECof2()\f1 \- test for valid second byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f1characters, tools to process 16-bit@@@\f3nl_tools_16(3X)\f1 .\" index@\f1process 16-bit characters, tools to@@@\f3nl_tools_16(3X)\f1 .\" index@\f1sixteen-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f116-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f1tools to process 16-bit characters@@@\f3nl_tools_16(3X)\f1 .\" .\" links@nl_tools_16.3x ADVANCE.3x .\" links@nl_tools_16.3x BYTE_STATUS.3x .\" links@nl_tools_16.3x CHARADV.3x .\" links@nl_tools_16.3x CHARAT.3x .\" links@nl_tools_16.3x FIRSTof2.3x .\" links@nl_tools_16.3x SECof2.3x .\" links@nl_tools_16.3x WCHAR.3x .\" links@nl_tools_16.3x WCHARADV.3x .\" links@nl_tools_16.3x byte_status.3x .\" links@nl_tools_16.3x c_colwidth.3x .\" links@nl_tools_16.3x firstof2.3x .\" links@nl_tools_16.3x secof2.3x .\" .\" toc@\f3nl_tools_16(3X)\f1:\0\0\f4ADVANCE()\f1, \f4byte_status()\f1, \f4BYTE_STATUS()\f1, \f4CHARADV()\f1,\n\f4CHARAT()\f1, \f4C_COLWIDTH()\f1, \f4c_colwidth()\f1, \f4firstof2()\f1, \f4FIRSTof2()\f1,\n\f4secof2()\f1, \f4SECof2()\f1, \f4WCHAR()\f1, \f4WCHARADV()\f1@@@tools to process 16-bit characters .\" toc@\f4ADVANCE()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4byte_status()\f1, \f4BYTE_STATUS()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARAT()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4firstof2()\f1, \f4FIRSTof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4secof2()\f1, \f4SECof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHAR()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" $Header: regexp.3x,v 72.5 94/11/15 09:56:02 ssa Exp $ .TA r .TH regexp 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compile(\|), step(\|), advance(\|) \- regular expression compile and match routines .SH SYNOPSIS .C #define INIT .I "declarations" .br .C #define GETC() .I "getc statements" .br .C #define PEEKC() .I "peekc statements" .br .C #define UNGETC(c) .I "ungetc statements" .br .C #define RETURN(pointer) .I "return statements" .br .C #define ERROR(val) .I "error statements" .PP .C "#include " .PP .C "char *compile(" .nf .PD 0 .IP .C "const char *instring," .C "char *expbuf," .C "const char *endbuf," .C "int eof" .PP .C ");" .PD .fi .PP .C "int step(const char *string, const char *expbuf);" .PP .C "int advance(const char *string, const char *expbuf);" .PP .C "extern char *loc1, *loc2, *locs;" .PP .C "extern int circf, sed, nbra;" .SS Remarks Features documented in this manual entry are obsolescent and may be removed in a future .SM HP-UX release. Use of .IR regcomp (3C) functions instead is recommended. .SH DESCRIPTION These functions are general-purpose regular expression matching routines to be used in programs that perform Basic Regular Expression (see .IR regexp (5)) matching. These functions are defined in .RC < regexp.h >. .PP The functions .C step() and .C advance() do pattern matching given a character string and a compiled regular expression as input. .C compile() takes a Basic Regular Expression as input and produces a compiled expression that can be used with .C step() and .CR advance() . .PP The interface to this file is unpleasantly complex. Programs that include this file must have the following five macros declared before the .C #include statement. These macros are used by the .C compile() routine. .TP 15 .C GETC() Return the value of the next byte in the regular expression pattern. Successive calls to .C GETC() should return successive bytes of the regular expression. .TP .C PEEKC() Return the next byte in the regular expression. Successive calls to .C PEEKC() should return the same byte (which should also be the next byte returned by .CR GETC() . .TP .CI UNGETC( c ) Cause the argument .I c to be returned by the next call to .C GETC() (and .CR PEEKC() ). No more than one byte of pushback is ever needed, and this byte is guaranteed to be the last byte read by .CR GETC() . The value of the macro .CI UNGETC( c ) is always ignored. .TP .CI RETURN( pointer ) This macro is used on normal exit of the .C compile() routine. The value of the argument .I pointer is a pointer to the character after the last character of the compiled regular expression. This is useful to programs that must manage memory allocation. .TP .CI ERROR( val ) This is the abnormal return from the .C compile() routine. The argument .I val is an error number (see table below for meanings). This call should never return. .RS .RS .PD 0 .TP 8 .B Error .B Meaning .TP 11 Range endpoint too large. .TP 16 Bad number. .TP 25 ``\f3\e\f2digit\f1'' out of range. .TP 36 Illegal or missing delimiter. .TP 41 No remembered search string. .TP 42 .C \e( \e) imbalance. .TP 43 Too many .CR \e( . .TP 44 More than 2 numbers given in .CR \e{\0\e} . .TP 45 .C } expected after .CR \e . .TP 46 First number exceeds second in .CR \e{\0\e} . .TP 49 .C [ ] imbalance. .TP 50 Regular expression overflow. .RE .RE .PD .PP The syntax of the .C compile() routine is as follows: .IP .CI compile( instring , .CI expbuf , .CI endbuf , .CI eof ) .PP The first parameter .I instring is never used explicitly by the .C compile() routine, but is useful for programs that pass down different pointers to input characters. It is sometimes used in the .C INIT declaration (see below). Programs that call functions to input characters or have characters in an external array can pass down a value of .C ((char *) 0) for this parameter. .PP The next parameter .I expbuf is a character pointer. It points to the location where the compiled regular expression will be placed. .PP The parameter .I endbuf is one more than the highest address where the compiled regular expression can be placed. If the compiled expression cannot fit in .RI ( endbuf \|\(mi\| expbuf ) bytes, a call to .C ERROR(50) is made. .PP The parameter .I eof is the character which marks the end of the regular expression. For example, in .IR ed (1), this character is usually a .CR / . .PP Each program that includes this file must have a .C #define statement for .CR INIT . This definition is placed right after the declaration for the function .C compile() and the opening curly brace .CR { . It is used for dependent declarations and initializations. Most often it is used to set a register variable to point to the beginning of the regular expression so that this register variable can be used in the declarations for .CR GETC() , .CR PEEKC() , and .CR UNGETC() . Otherwise it can be used to declare external variables that might be used by .CR GETC() , .CR PEEKC() , and .CR UNGETC() . See the example below of the declarations taken from .IR grep (1). .PP .C step() also performs actual regular expression matching in this file. The call to .I step is as follows: .IP .CI step( string , .CI expbuf ) .PP The first parameter to .C step() is a pointer to a string of characters to be checked for a match. This string should be null-terminated. .PP The second parameter .I expbuf is the compiled regular expression that was obtained by a call to .CR compile() . .PP .C step() returns non-zero if the given string matches the regular expression, and zero if the expressions do not match. If there is a match, two external character pointers are set as a side effect to the call to .CR step() . The variable set in .C step() is .CR loc1 . This is a pointer to the first character that matched the regular expression. The variable .CR loc2 , which is set by the function .CR advance() , points to the character after the last character that matches the regular expression. Thus, if the regular expression matches the entire line, .C loc1 points to the first character of .I string and .C loc2 points to the null at the end of .IR string . .PP .C step() uses the external variable .CR circf() , which is set by .C compile() if the regular expression begins with .CR ^ . If this is set, .C step() tries to match the regular expression to the beginning of the string only. If more than one regular expression is to be compiled before the first is executed, the value of .I circf should be saved for each compiled expression and .I circf should be set to that saved value before each call to .CR step() . .PP .C advance() is called from .C step() with the same arguments as .CR step() . The purpose of .C step() is to step through the .I string argument and call .C advance() until .C advance() returns non-zero, which indicates a match, or until the end of .I string is reached. To constrain .I string to beginning-of-line in all cases, .C step() need not be called; simply call .CR advance() . .PP When .C advance() encounters a .C * or .C \e{\|\e} sequence in the regular expression, it advances its pointer to the string to be matched as far as possible and recursively calls itself, trying to match the rest of the string to the rest of the regular expression. As long as there is no match, .I advance backs up along the string until it finds a match or reaches the point in the string that initially matched the .C * or .CR \e{\|\e} . It is sometimes desirable to stop this backing up before the initial point in the string is reached. If the external character pointer .C locs is equal to the point in the string at sometime during the backing up process, .C advance() breaks out of the loop that backs up and returns zero. This is used by .IR ed (1) and .IR sed (1) for substitutions done globally (not just the first occurrence, but the whole line) so, for example, expressions such as .C s/y*//g do not loop forever. .PP The additional external variables .C sed and .C nbra are used for special purposes. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions. .PP The .C LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, and the characters matched by character class expressions in regular expressions. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following is an example of how the regular expression macros and calls look from .IR grep (1): .nf .IP .C "#define INIT register char *sp = instring;" .C "#define GETC() (*sp++)" .C "#define PEEKC() (*sp)" .C "#define UNGETC(c) (--sp)" .C "#define RETURN(c) return;" .C "#define ERROR(c) regerr()" .IP .C "#include " \h'.5i'.\|.\|. .C "(void) compile(*argv, expbuf, &expbuf[ESIZE], '\e0');" \h'.5i'.\|.\|. .C "if (step(linebuf, expbuf))" .C " succeed();" .fi .SH AUTHOR .CR regexp() was developed by OSF and HP. .SH SEE ALSO grep(1), regcomp(3C), setlocale(3C), regexp(5). .SH STANDARDS CONFORMANCE .CR advance() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR compile() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc1 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc2 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR locs ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR step() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4compile()\f1 \- regular expression compile routine@@@\f3regexp(3X)\f1 .\" index@\f4step()\f1 \- regular expression string comparison routine@@@\f3regexp(3X)\f1 .\" index@\f4advance()\f1 \- regular expression substring comparison routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1expression, regular, compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1compile and match routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1comparison routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1match routines for regular expressions@@@\f3regexp(3X)\f1 .\" .\" toc@\f3regexp(3X)\f1:\0\0\f4compile()\f1, \f4step()\f1, \f4advance()\f1@@@regular expression compile and match routines .\" toc@\f4compile()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4step()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4advance()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" .\" links@regexp.3x compile.3x .\" links@regexp.3x step.3x .\" links@regexp.3x advance.3x .\" links@regexp.3x INIT.3x .\" links@regexp.3x GETC.3x .\" links@regexp.3x PEEKC.3x .\" links@regexp.3x UNGETC.3x .\" links@regexp.3x RETURN.3x .\" links@regexp.3x ERROR.3x .\" .\" fileset_database@regexp.3x PROGRAMING-MAN .\" $Header: hppac.3x,v 74.1 95/05/10 21:48:10 ssa Exp $ .TA h .TH hppac 3X "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONGDIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD\s+1 \- 3000-mode packed-decimal library .SH SYNOPSIS .C "#include " .nf .PP .C "void HPPACADDD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCMPD( .PD 0 .IP .C "unsigned char \(**operand1, .C "int op1digs, .C "unsigned char \(**operand2, .C "int op2digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVAD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVBD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned short \(**source, .C "int sourcewords, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDA( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sign_control, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDB( .PD 0 .IP .C "unsigned short \(**target, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .P .C ");" .PD .PP .C "void HPPACDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACLONGDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACMPYD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACNSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int \(**shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSRD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACSUBD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .fi .SH DESCRIPTION This set of calls invokes the library functions for emulating 3000-mode .SM (MPE V/E) packed-decimal operations. These functions are in library .C libcl which is searched when the option .C -lcl is used with .IR cc (1) or .IR ld (1). .TP 15 .C HPPACADDD() Performs packed-decimal addition. .TP .C HPPACCMPD() Compares two packed-decimal numbers. .TP .C HPPACCVAD() Converts an ASCII representation to packed-decimal. .TP .C HPPACCVBD() Converts a binary representation to packed-decimal. .TP .C HPPACCVDA() Converts a packed-decimal number to ASCII. .TP .C HPPACCVDB() Converts a packed-decimal number to binary. .TP .C HPPACDIVD() Performs packed-decimal division. .TP .C HPPACLONGDIVD() Performs packed-decimal division (alternate routine). .TP .C HPPACMPYD() Performs packed-decimal multiplication. .TP .C HPPACNSLD() Performs a packed-decimal normalizing left shift. .TP .C HPPACSLD() Performs a packed-decimal left shift. .TP .C HPPACSRD() Performs a packed-decimal right shift. .TP .C HPPACSUBD() Performs packed-decimal subtraction. .PP For all operations, the value returned in the variable to which the .IR compcode argument points is one of the following values of type .C enum .CR HPPAC_CC\s0 : .RS .TP 15 .C HPPAC_CCG Result > 0 or operand1 > operand2 .TP .C HPPAC_CCL Result < 0 or operand1 < operand2 .TP .C HPPAC_CCE Result == 0 or operand1 == operand2 .RE .PP For all operations, the value returned in the variable to which the .IR pacstatus argument points is one of the following values of type .C enum .SM .CR HPPAC_STATUS\s0 . Their meanings are intended to be obvious: .IP .C HPPAC_NO_ERROR .IP .C HPPAC_DECIMAL_OVERFLOW .IP .C HPPAC_INVALID_ASCII_DIGIT .IP .C HPPAC_INVALID_PACKED_DECIMAL_DIGIT .IP .C HPPAC_INVALID_SOURCE_WORD_COUNT .IP .C HPPAC_INVALID_DECIMAL_OPERAND_LENGTH .IP .C HPPAC_DECIMAL_DIVIDE_BY_ZERO .RE .SH AUTHOR The .SM HPPAC library was developed by HP. .SH SEE ALSO .I Compiler Library/XL Reference Manual .\" .\" index@\s-1HPPAC\(**\s+1: \s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@\s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@packed decimal library, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@decimal library, packed, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@library, packed decimal, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" .\" toc@\f3hppac(3X)\f1@@@Series 800 HP\|3000-mode packed decimal library .\" .\" links@hppac.3x HPPACADDD.3x .\" links@hppac.3x HPPACCMPD.3x .\" links@hppac.3x HPPACCVAD.3x .\" links@hppac.3x HPPACCVBD.3x .\" links@hppac.3x HPPACCVDA.3x .\" links@hppac.3x HPPACCVDB.3x .\" links@hppac.3x HPPACDIVD.3x .\" links@hppac.3x HPPACLONGDI.3x .\" links@hppac.3x HPPACMPYD.3x .\" links@hppac.3x HPPACNSLD.3x .\" links@hppac.3x HPPACSLD.3x .\" links@hppac.3x HPPACSRD.3x .\" links@hppac.3x HPPACSUBD.3x .\" .\" fileset_database@hppac.3x PROGRAMING-MAN .\" $Header: hppac.3x,v 74.1 95/05/10 21:48:10 ssa Exp $ .TA h .TH hppac 3X "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONGDIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD\s+1 \- 3000-mode packed-decimal library .SH SYNOPSIS .C "#include " .nf .PP .C "void HPPACADDD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCMPD( .PD 0 .IP .C "unsigned char \(**operand1, .C "int op1digs, .C "unsigned char \(**operand2, .C "int op2digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVAD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVBD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned short \(**source, .C "int sourcewords, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDA( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sign_control, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDB( .PD 0 .IP .C "unsigned short \(**target, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .P .C ");" .PD .PP .C "void HPPACDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACLONGDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACMPYD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACNSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int \(**shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSRD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACSUBD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .fi .SH DESCRIPTION This set of calls invokes the library functions for emulating 3000-mode .SM (MPE V/E) packed-decimal operations. These functions are in library .C libcl which is searched when the option .C -lcl is used with .IR cc (1) or .IR ld (1). .TP 15 .C HPPACADDD() Performs packed-decimal addition. .TP .C HPPACCMPD() Compares two packed-decimal numbers. .TP .C HPPACCVAD() Converts an ASCII representation to packed-decimal. .TP .C HPPACCVBD() Converts a binary representation to packed-decimal. .TP .C HPPACCVDA() Converts a packed-decimal number to ASCII. .TP .C HPPACCVDB() Converts a packed-decimal number to binary. .TP .C HPPACDIVD() Performs packed-decimal division. .TP .C HPPACLONGDIVD() Performs packed-decimal division (alternate routine). .TP .C HPPACMPYD() Performs packed-decimal multiplication. .TP .C HPPACNSLD() Performs a packed-decimal normalizing left shift. .TP .C HPPACSLD() Performs a packed-decimal left shift. .TP .C HPPACSRD() Performs a packed-decimal right shift. .TP .C HPPACSUBD() Performs packed-decimal subtraction. .PP For all operations, the value returned in the variable to which the .IR compcode argument points is one of the following values of type .C enum .CR HPPAC_CC\s0 : .RS .TP 15 .C HPPAC_CCG Result > 0 or operand1 > operand2 .TP .C HPPAC_CCL Result < 0 or operand1 < operand2 .TP .C HPPAC_CCE Result == 0 or operand1 == operand2 .RE .PP For all operations, the value returned in the variable to which the .IR pacstatus argument points is one of the following values of type .C enum .SM .CR HPPAC_STATUS\s0 . Their meanings are intended to be obvious: .IP .C HPPAC_NO_ERROR .IP .C HPPAC_DECIMAL_OVERFLOW .IP .C HPPAC_INVALID_ASCII_DIGIT .IP .C HPPAC_INVALID_PACKED_DECIMAL_DIGIT .IP .C HPPAC_INVALID_SOURCE_WORD_COUNT .IP .C HPPAC_INVALID_DECIMAL_OPERAND_LENGTH .IP .C HPPAC_DECIMAL_DIVIDE_BY_ZERO .RE .SH AUTHOR The .SM HPPAC library was developed by HP. .SH SEE ALSO .I Compiler Library/XL Reference Manual .\" .\" index@\s-1HPPAC\(**\s+1: \s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@\s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@packed decimal library, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@decimal library, packed, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@library, packed decimal, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" .\" toc@\f3hppac(3X)\f1@@@Series 800 HP\|3000-mode packed decimal library .\" .\" links@hppac.3x HPPACADDD.3x .\" links@hppac.3x HPPACCMPD.3x .\" links@hppac.3x HPPACCVAD.3x .\" links@hppac.3x HPPACCVBD.3x .\" links@hppac.3x HPPACCVDA.3x .\" links@hppac.3x HPPACCVDB.3x .\" links@hppac.3x HPPACDIVD.3x .\" links@hppac.3x HPPACLONGDI.3x .\" links@hppac.3x HPPACMPYD.3x .\" links@hppac.3x HPPACNSLD.3x .\" links@hppac.3x HPPACSLD.3x .\" links@hppac.3x HPPACSRD.3x .\" links@hppac.3x HPPACSUBD.3x .\" .\" fileset_database@hppac.3x PROGRAMING-MAN .\" $Header: hppac.3x,v 74.1 95/05/10 21:48:10 ssa Exp $ .TA h .TH hppac 3X "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONGDIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD\s+1 \- 3000-mode packed-decimal library .SH SYNOPSIS .C "#include " .nf .PP .C "void HPPACADDD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCMPD( .PD 0 .IP .C "unsigned char \(**operand1, .C "int op1digs, .C "unsigned char \(**operand2, .C "int op2digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVAD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVBD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned short \(**source, .C "int sourcewords, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDA( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sign_control, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDB( .PD 0 .IP .C "unsigned short \(**target, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .P .C ");" .PD .PP .C "void HPPACDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACLONGDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACMPYD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACNSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int \(**shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSRD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACSUBD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .fi .SH DESCRIPTION This set of calls invokes the library functions for emulating 3000-mode .SM (MPE V/E) packed-decimal operations. These functions are in library .C libcl which is searched when the option .C -lcl is used with .IR cc (1) or .IR ld (1). .TP 15 .C HPPACADDD() Performs packed-decimal addition. .TP .C HPPACCMPD() Compares two packed-decimal numbers. .TP .C HPPACCVAD() Converts an ASCII representation to packed-decimal. .TP .C HPPACCVBD() Converts a binary representation to packed-decimal. .TP .C HPPACCVDA() Converts a packed-decimal number to ASCII. .TP .C HPPACCVDB() Converts a packed-decimal number to binary. .TP .C HPPACDIVD() Performs packed-decimal division. .TP .C HPPACLONGDIVD() Performs packed-decimal division (alternate routine). .TP .C HPPACMPYD() Performs packed-decimal multiplication. .TP .C HPPACNSLD() Performs a packed-decimal normalizing left shift. .TP .C HPPACSLD() Performs a packed-decimal left shift. .TP .C HPPACSRD() Performs a packed-decimal right shift. .TP .C HPPACSUBD() Performs packed-decimal subtraction. .PP For all operations, the value returned in the variable to which the .IR compcode argument points is one of the following values of type .C enum .CR HPPAC_CC\s0 : .RS .TP 15 .C HPPAC_CCG Result > 0 or operand1 > operand2 .TP .C HPPAC_CCL Result < 0 or operand1 < operand2 .TP .C HPPAC_CCE Result == 0 or operand1 == operand2 .RE .PP For all operations, the value returned in the variable to which the .IR pacstatus argument points is one of the following values of type .C enum .SM .CR HPPAC_STATUS\s0 . Their meanings are intended to be obvious: .IP .C HPPAC_NO_ERROR .IP .C HPPAC_DECIMAL_OVERFLOW .IP .C HPPAC_INVALID_ASCII_DIGIT .IP .C HPPAC_INVALID_PACKED_DECIMAL_DIGIT .IP .C HPPAC_INVALID_SOURCE_WORD_COUNT .IP .C HPPAC_INVALID_DECIMAL_OPERAND_LENGTH .IP .C HPPAC_DECIMAL_DIVIDE_BY_ZERO .RE .SH AUTHOR The .SM HPPAC library was developed by HP. .SH SEE ALSO .I Compiler Library/XL Reference Manual .\" .\" index@\s-1HPPAC\(**\s+1: \s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@\s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@packed decimal library, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@decimal library, packed, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@library, packed decimal, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" .\" toc@\f3hppac(3X)\f1@@@Series 800 HP\|3000-mode packed decimal library .\" .\" links@hppac.3x HPPACADDD.3x .\" links@hppac.3x HPPACCMPD.3x .\" links@hppac.3x HPPACCVAD.3x .\" links@hppac.3x HPPACCVBD.3x .\" links@hppac.3x HPPACCVDA.3x .\" links@hppac.3x HPPACCVDB.3x .\" links@hppac.3x HPPACDIVD.3x .\" links@hppac.3x HPPACLONGDI.3x .\" links@hppac.3x HPPACMPYD.3x .\" links@hppac.3x HPPACNSLD.3x .\" links@hppac.3x HPPACSLD.3x .\" links@hppac.3x HPPACSRD.3x .\" links@hppac.3x HPPACSUBD.3x .\" .\" fileset_database@hppac.3x PROGRAMING-MAN .\" $Header: hppac.3x,v 74.1 95/05/10 21:48:10 ssa Exp $ .TA h .TH hppac 3X "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONGDIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD\s+1 \- 3000-mode packed-decimal library .SH SYNOPSIS .C "#include " .nf .PP .C "void HPPACADDD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCMPD( .PD 0 .IP .C "unsigned char \(**operand1, .C "int op1digs, .C "unsigned char \(**operand2, .C "int op2digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVAD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVBD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned short \(**source, .C "int sourcewords, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDA( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sign_control, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDB( .PD 0 .IP .C "unsigned short \(**target, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .P .C ");" .PD .PP .C "void HPPACDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACLONGDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACMPYD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACNSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int \(**shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSRD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACSUBD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .fi .SH DESCRIPTION This set of calls invokes the library functions for emulating 3000-mode .SM (MPE V/E) packed-decimal operations. These functions are in library .C libcl which is searched when the option .C -lcl is used with .IR cc (1) or .IR ld (1). .TP 15 .C HPPACADDD() Performs packed-decimal addition. .TP .C HPPACCMPD() Compares two packed-decimal numbers. .TP .C HPPACCVAD() Converts an ASCII representation to packed-decimal. .TP .C HPPACCVBD() Converts a binary representation to packed-decimal. .TP .C HPPACCVDA() Converts a packed-decimal number to ASCII. .TP .C HPPACCVDB() Converts a packed-decimal number to binary. .TP .C HPPACDIVD() Performs packed-decimal division. .TP .C HPPACLONGDIVD() Performs packed-decimal division (alternate routine). .TP .C HPPACMPYD() Performs packed-decimal multiplication. .TP .C HPPACNSLD() Performs a packed-decimal normalizing left shift. .TP .C HPPACSLD() Performs a packed-decimal left shift. .TP .C HPPACSRD() Performs a packed-decimal right shift. .TP .C HPPACSUBD() Performs packed-decimal subtraction. .PP For all operations, the value returned in the variable to which the .IR compcode argument points is one of the following values of type .C enum .CR HPPAC_CC\s0 : .RS .TP 15 .C HPPAC_CCG Result > 0 or operand1 > operand2 .TP .C HPPAC_CCL Result < 0 or operand1 < operand2 .TP .C HPPAC_CCE Result == 0 or operand1 == operand2 .RE .PP For all operations, the value returned in the variable to which the .IR pacstatus argument points is one of the following values of type .C enum .SM .CR HPPAC_STATUS\s0 . Their meanings are intended to be obvious: .IP .C HPPAC_NO_ERROR .IP .C HPPAC_DECIMAL_OVERFLOW .IP .C HPPAC_INVALID_ASCII_DIGIT .IP .C HPPAC_INVALID_PACKED_DECIMAL_DIGIT .IP .C HPPAC_INVALID_SOURCE_WORD_COUNT .IP .C HPPAC_INVALID_DECIMAL_OPERAND_LENGTH .IP .C HPPAC_DECIMAL_DIVIDE_BY_ZERO .RE .SH AUTHOR The .SM HPPAC library was developed by HP. .SH SEE ALSO .I Compiler Library/XL Reference Manual .\" .\" index@\s-1HPPAC\(**\s+1: \s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@\s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@packed decimal library, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@decimal library, packed, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@library, packed decimal, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" .\" toc@\f3hppac(3X)\f1@@@Series 800 HP\|3000-mode packed decimal library .\" .\" links@hppac.3x HPPACADDD.3x .\" links@hppac.3x HPPACCMPD.3x .\" links@hppac.3x HPPACCVAD.3x .\" links@hppac.3x HPPACCVBD.3x .\" links@hppac.3x HPPACCVDA.3x .\" links@hppac.3x HPPACCVDB.3x .\" links@hppac.3x HPPACDIVD.3x .\" links@hppac.3x HPPACLONGDI.3x .\" links@hppac.3x HPPACMPYD.3x .\" links@hppac.3x HPPACNSLD.3x .\" links@hppac.3x HPPACSLD.3x .\" links@hppac.3x HPPACSRD.3x .\" links@hppac.3x HPPACSUBD.3x .\" .\" fileset_database@hppac.3x PROGRAMING-MAN .\" $Header: hppac.3x,v 74.1 95/05/10 21:48:10 ssa Exp $ .TA h .TH hppac 3X "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONGDIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD\s+1 \- 3000-mode packed-decimal library .SH SYNOPSIS .C "#include " .nf .PP .C "void HPPACADDD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCMPD( .PD 0 .IP .C "unsigned char \(**operand1, .C "int op1digs, .C "unsigned char \(**operand2, .C "int op2digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVAD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVBD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned short \(**source, .C "int sourcewords, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDA( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sign_control, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDB( .PD 0 .IP .C "unsigned short \(**target, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .P .C ");" .PD .PP .C "void HPPACDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACLONGDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACMPYD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACNSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int \(**shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSRD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACSUBD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .fi .SH DESCRIPTION This set of calls invokes the library functions for emulating 3000-mode .SM (MPE V/E) packed-decimal operations. These functions are in library .C libcl which is searched when the option .C -lcl is used with .IR cc (1) or .IR ld (1). .TP 15 .C HPPACADDD() Performs packed-decimal addition. .TP .C HPPACCMPD() Compares two packed-decimal numbers. .TP .C HPPACCVAD() Converts an ASCII representation to packed-decimal. .TP .C HPPACCVBD() Converts a binary representation to packed-decimal. .TP .C HPPACCVDA() Converts a packed-decimal number to ASCII. .TP .C HPPACCVDB() Converts a packed-decimal number to binary. .TP .C HPPACDIVD() Performs packed-decimal division. .TP .C HPPACLONGDIVD() Performs packed-decimal division (alternate routine). .TP .C HPPACMPYD() Performs packed-decimal multiplication. .TP .C HPPACNSLD() Performs a packed-decimal normalizing left shift. .TP .C HPPACSLD() Performs a packed-decimal left shift. .TP .C HPPACSRD() Performs a packed-decimal right shift. .TP .C HPPACSUBD() Performs packed-decimal subtraction. .PP For all operations, the value returned in the variable to which the .IR compcode argument points is one of the following values of type .C enum .CR HPPAC_CC\s0 : .RS .TP 15 .C HPPAC_CCG Result > 0 or operand1 > operand2 .TP .C HPPAC_CCL Result < 0 or operand1 < operand2 .TP .C HPPAC_CCE Result == 0 or operand1 == operand2 .RE .PP For all operations, the value returned in the variable to which the .IR pacstatus argument points is one of the following values of type .C enum .SM .CR HPPAC_STATUS\s0 . Their meanings are intended to be obvious: .IP .C HPPAC_NO_ERROR .IP .C HPPAC_DECIMAL_OVERFLOW .IP .C HPPAC_INVALID_ASCII_DIGIT .IP .C HPPAC_INVALID_PACKED_DECIMAL_DIGIT .IP .C HPPAC_INVALID_SOURCE_WORD_COUNT .IP .C HPPAC_INVALID_DECIMAL_OPERAND_LENGTH .IP .C HPPAC_DECIMAL_DIVIDE_BY_ZERO .RE .SH AUTHOR The .SM HPPAC library was developed by HP. .SH SEE ALSO .I Compiler Library/XL Reference Manual .\" .\" index@\s-1HPPAC\(**\s+1: \s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@\s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@packed decimal library, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@decimal library, packed, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@library, packed decimal, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" .\" toc@\f3hppac(3X)\f1@@@Series 800 HP\|3000-mode packed decimal library .\" .\" links@hppac.3x HPPACADDD.3x .\" links@hppac.3x HPPACCMPD.3x .\" links@hppac.3x HPPACCVAD.3x .\" links@hppac.3x HPPACCVBD.3x .\" links@hppac.3x HPPACCVDA.3x .\" links@hppac.3x HPPACCVDB.3x .\" links@hppac.3x HPPACDIVD.3x .\" links@hppac.3x HPPACLONGDI.3x .\" links@hppac.3x HPPACMPYD.3x .\" links@hppac.3x HPPACNSLD.3x .\" links@hppac.3x HPPACSLD.3x .\" links@hppac.3x HPPACSRD.3x .\" links@hppac.3x HPPACSUBD.3x .\" .\" fileset_database@hppac.3x PROGRAMING-MAN .\" $Header: hppac.3x,v 74.1 95/05/10 21:48:10 ssa Exp $ .TA h .TH hppac 3X "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONGDIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD\s+1 \- 3000-mode packed-decimal library .SH SYNOPSIS .C "#include " .nf .PP .C "void HPPACADDD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCMPD( .PD 0 .IP .C "unsigned char \(**operand1, .C "int op1digs, .C "unsigned char \(**operand2, .C "int op2digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVAD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVBD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned short \(**source, .C "int sourcewords, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDA( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sign_control, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDB( .PD 0 .IP .C "unsigned short \(**target, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .P .C ");" .PD .PP .C "void HPPACDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACLONGDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACMPYD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACNSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int \(**shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSRD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACSUBD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .fi .SH DESCRIPTION This set of calls invokes the library functions for emulating 3000-mode .SM (MPE V/E) packed-decimal operations. These functions are in library .C libcl which is searched when the option .C -lcl is used with .IR cc (1) or .IR ld (1). .TP 15 .C HPPACADDD() Performs packed-decimal addition. .TP .C HPPACCMPD() Compares two packed-decimal numbers. .TP .C HPPACCVAD() Converts an ASCII representation to packed-decimal. .TP .C HPPACCVBD() Converts a binary representation to packed-decimal. .TP .C HPPACCVDA() Converts a packed-decimal number to ASCII. .TP .C HPPACCVDB() Converts a packed-decimal number to binary. .TP .C HPPACDIVD() Performs packed-decimal division. .TP .C HPPACLONGDIVD() Performs packed-decimal division (alternate routine). .TP .C HPPACMPYD() Performs packed-decimal multiplication. .TP .C HPPACNSLD() Performs a packed-decimal normalizing left shift. .TP .C HPPACSLD() Performs a packed-decimal left shift. .TP .C HPPACSRD() Performs a packed-decimal right shift. .TP .C HPPACSUBD() Performs packed-decimal subtraction. .PP For all operations, the value returned in the variable to which the .IR compcode argument points is one of the following values of type .C enum .CR HPPAC_CC\s0 : .RS .TP 15 .C HPPAC_CCG Result > 0 or operand1 > operand2 .TP .C HPPAC_CCL Result < 0 or operand1 < operand2 .TP .C HPPAC_CCE Result == 0 or operand1 == operand2 .RE .PP For all operations, the value returned in the variable to which the .IR pacstatus argument points is one of the following values of type .C enum .SM .CR HPPAC_STATUS\s0 . Their meanings are intended to be obvious: .IP .C HPPAC_NO_ERROR .IP .C HPPAC_DECIMAL_OVERFLOW .IP .C HPPAC_INVALID_ASCII_DIGIT .IP .C HPPAC_INVALID_PACKED_DECIMAL_DIGIT .IP .C HPPAC_INVALID_SOURCE_WORD_COUNT .IP .C HPPAC_INVALID_DECIMAL_OPERAND_LENGTH .IP .C HPPAC_DECIMAL_DIVIDE_BY_ZERO .RE .SH AUTHOR The .SM HPPAC library was developed by HP. .SH SEE ALSO .I Compiler Library/XL Reference Manual .\" .\" index@\s-1HPPAC\(**\s+1: \s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@\s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@packed decimal library, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@decimal library, packed, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@library, packed decimal, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" .\" toc@\f3hppac(3X)\f1@@@Series 800 HP\|3000-mode packed decimal library .\" .\" links@hppac.3x HPPACADDD.3x .\" links@hppac.3x HPPACCMPD.3x .\" links@hppac.3x HPPACCVAD.3x .\" links@hppac.3x HPPACCVBD.3x .\" links@hppac.3x HPPACCVDA.3x .\" links@hppac.3x HPPACCVDB.3x .\" links@hppac.3x HPPACDIVD.3x .\" links@hppac.3x HPPACLONGDI.3x .\" links@hppac.3x HPPACMPYD.3x .\" links@hppac.3x HPPACNSLD.3x .\" links@hppac.3x HPPACSLD.3x .\" links@hppac.3x HPPACSRD.3x .\" links@hppac.3x HPPACSUBD.3x .\" .\" fileset_database@hppac.3x PROGRAMING-MAN .\" $Header: hppac.3x,v 74.1 95/05/10 21:48:10 ssa Exp $ .TA h .TH hppac 3X "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONGDIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD\s+1 \- 3000-mode packed-decimal library .SH SYNOPSIS .C "#include " .nf .PP .C "void HPPACADDD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCMPD( .PD 0 .IP .C "unsigned char \(**operand1, .C "int op1digs, .C "unsigned char \(**operand2, .C "int op2digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVAD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVBD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned short \(**source, .C "int sourcewords, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDA( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sign_control, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDB( .PD 0 .IP .C "unsigned short \(**target, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .P .C ");" .PD .PP .C "void HPPACDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACLONGDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACMPYD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACNSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int \(**shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSRD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACSUBD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .fi .SH DESCRIPTION This set of calls invokes the library functions for emulating 3000-mode .SM (MPE V/E) packed-decimal operations. These functions are in library .C libcl which is searched when the option .C -lcl is used with .IR cc (1) or .IR ld (1). .TP 15 .C HPPACADDD() Performs packed-decimal addition. .TP .C HPPACCMPD() Compares two packed-decimal numbers. .TP .C HPPACCVAD() Converts an ASCII representation to packed-decimal. .TP .C HPPACCVBD() Converts a binary representation to packed-decimal. .TP .C HPPACCVDA() Converts a packed-decimal number to ASCII. .TP .C HPPACCVDB() Converts a packed-decimal number to binary. .TP .C HPPACDIVD() Performs packed-decimal division. .TP .C HPPACLONGDIVD() Performs packed-decimal division (alternate routine). .TP .C HPPACMPYD() Performs packed-decimal multiplication. .TP .C HPPACNSLD() Performs a packed-decimal normalizing left shift. .TP .C HPPACSLD() Performs a packed-decimal left shift. .TP .C HPPACSRD() Performs a packed-decimal right shift. .TP .C HPPACSUBD() Performs packed-decimal subtraction. .PP For all operations, the value returned in the variable to which the .IR compcode argument points is one of the following values of type .C enum .CR HPPAC_CC\s0 : .RS .TP 15 .C HPPAC_CCG Result > 0 or operand1 > operand2 .TP .C HPPAC_CCL Result < 0 or operand1 < operand2 .TP .C HPPAC_CCE Result == 0 or operand1 == operand2 .RE .PP For all operations, the value returned in the variable to which the .IR pacstatus argument points is one of the following values of type .C enum .SM .CR HPPAC_STATUS\s0 . Their meanings are intended to be obvious: .IP .C HPPAC_NO_ERROR .IP .C HPPAC_DECIMAL_OVERFLOW .IP .C HPPAC_INVALID_ASCII_DIGIT .IP .C HPPAC_INVALID_PACKED_DECIMAL_DIGIT .IP .C HPPAC_INVALID_SOURCE_WORD_COUNT .IP .C HPPAC_INVALID_DECIMAL_OPERAND_LENGTH .IP .C HPPAC_DECIMAL_DIVIDE_BY_ZERO .RE .SH AUTHOR The .SM HPPAC library was developed by HP. .SH SEE ALSO .I Compiler Library/XL Reference Manual .\" .\" index@\s-1HPPAC\(**\s+1: \s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@\s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@packed decimal library, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@decimal library, packed, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@library, packed decimal, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" .\" toc@\f3hppac(3X)\f1@@@Series 800 HP\|3000-mode packed decimal library .\" .\" links@hppac.3x HPPACADDD.3x .\" links@hppac.3x HPPACCMPD.3x .\" links@hppac.3x HPPACCVAD.3x .\" links@hppac.3x HPPACCVBD.3x .\" links@hppac.3x HPPACCVDA.3x .\" links@hppac.3x HPPACCVDB.3x .\" links@hppac.3x HPPACDIVD.3x .\" links@hppac.3x HPPACLONGDI.3x .\" links@hppac.3x HPPACMPYD.3x .\" links@hppac.3x HPPACNSLD.3x .\" links@hppac.3x HPPACSLD.3x .\" links@hppac.3x HPPACSRD.3x .\" links@hppac.3x HPPACSUBD.3x .\" .\" fileset_database@hppac.3x PROGRAMING-MAN .\" $Header: hppac.3x,v 74.1 95/05/10 21:48:10 ssa Exp $ .TA h .TH hppac 3X "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONGDIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD\s+1 \- 3000-mode packed-decimal library .SH SYNOPSIS .C "#include " .nf .PP .C "void HPPACADDD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCMPD( .PD 0 .IP .C "unsigned char \(**operand1, .C "int op1digs, .C "unsigned char \(**operand2, .C "int op2digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVAD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVBD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned short \(**source, .C "int sourcewords, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDA( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sign_control, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDB( .PD 0 .IP .C "unsigned short \(**target, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .P .C ");" .PD .PP .C "void HPPACDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACLONGDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACMPYD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACNSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int \(**shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSRD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACSUBD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .fi .SH DESCRIPTION This set of calls invokes the library functions for emulating 3000-mode .SM (MPE V/E) packed-decimal operations. These functions are in library .C libcl which is searched when the option .C -lcl is used with .IR cc (1) or .IR ld (1). .TP 15 .C HPPACADDD() Performs packed-decimal addition. .TP .C HPPACCMPD() Compares two packed-decimal numbers. .TP .C HPPACCVAD() Converts an ASCII representation to packed-decimal. .TP .C HPPACCVBD() Converts a binary representation to packed-decimal. .TP .C HPPACCVDA() Converts a packed-decimal number to ASCII. .TP .C HPPACCVDB() Converts a packed-decimal number to binary. .TP .C HPPACDIVD() Performs packed-decimal division. .TP .C HPPACLONGDIVD() Performs packed-decimal division (alternate routine). .TP .C HPPACMPYD() Performs packed-decimal multiplication. .TP .C HPPACNSLD() Performs a packed-decimal normalizing left shift. .TP .C HPPACSLD() Performs a packed-decimal left shift. .TP .C HPPACSRD() Performs a packed-decimal right shift. .TP .C HPPACSUBD() Performs packed-decimal subtraction. .PP For all operations, the value returned in the variable to which the .IR compcode argument points is one of the following values of type .C enum .CR HPPAC_CC\s0 : .RS .TP 15 .C HPPAC_CCG Result > 0 or operand1 > operand2 .TP .C HPPAC_CCL Result < 0 or operand1 < operand2 .TP .C HPPAC_CCE Result == 0 or operand1 == operand2 .RE .PP For all operations, the value returned in the variable to which the .IR pacstatus argument points is one of the following values of type .C enum .SM .CR HPPAC_STATUS\s0 . Their meanings are intended to be obvious: .IP .C HPPAC_NO_ERROR .IP .C HPPAC_DECIMAL_OVERFLOW .IP .C HPPAC_INVALID_ASCII_DIGIT .IP .C HPPAC_INVALID_PACKED_DECIMAL_DIGIT .IP .C HPPAC_INVALID_SOURCE_WORD_COUNT .IP .C HPPAC_INVALID_DECIMAL_OPERAND_LENGTH .IP .C HPPAC_DECIMAL_DIVIDE_BY_ZERO .RE .SH AUTHOR The .SM HPPAC library was developed by HP. .SH SEE ALSO .I Compiler Library/XL Reference Manual .\" .\" index@\s-1HPPAC\(**\s+1: \s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@\s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@packed decimal library, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@decimal library, packed, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@library, packed decimal, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" .\" toc@\f3hppac(3X)\f1@@@Series 800 HP\|3000-mode packed decimal library .\" .\" links@hppac.3x HPPACADDD.3x .\" links@hppac.3x HPPACCMPD.3x .\" links@hppac.3x HPPACCVAD.3x .\" links@hppac.3x HPPACCVBD.3x .\" links@hppac.3x HPPACCVDA.3x .\" links@hppac.3x HPPACCVDB.3x .\" links@hppac.3x HPPACDIVD.3x .\" links@hppac.3x HPPACLONGDI.3x .\" links@hppac.3x HPPACMPYD.3x .\" links@hppac.3x HPPACNSLD.3x .\" links@hppac.3x HPPACSLD.3x .\" links@hppac.3x HPPACSRD.3x .\" links@hppac.3x HPPACSUBD.3x .\" .\" fileset_database@hppac.3x PROGRAMING-MAN .\" $Header: hppac.3x,v 74.1 95/05/10 21:48:10 ssa Exp $ .TA h .TH hppac 3X "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONGDIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD\s+1 \- 3000-mode packed-decimal library .SH SYNOPSIS .C "#include " .nf .PP .C "void HPPACADDD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCMPD( .PD 0 .IP .C "unsigned char \(**operand1, .C "int op1digs, .C "unsigned char \(**operand2, .C "int op2digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVAD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVBD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned short \(**source, .C "int sourcewords, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDA( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sign_control, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDB( .PD 0 .IP .C "unsigned short \(**target, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .P .C ");" .PD .PP .C "void HPPACDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACLONGDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACMPYD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACNSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int \(**shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSRD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACSUBD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .fi .SH DESCRIPTION This set of calls invokes the library functions for emulating 3000-mode .SM (MPE V/E) packed-decimal operations. These functions are in library .C libcl which is searched when the option .C -lcl is used with .IR cc (1) or .IR ld (1). .TP 15 .C HPPACADDD() Performs packed-decimal addition. .TP .C HPPACCMPD() Compares two packed-decimal numbers. .TP .C HPPACCVAD() Converts an ASCII representation to packed-decimal. .TP .C HPPACCVBD() Converts a binary representation to packed-decimal. .TP .C HPPACCVDA() Converts a packed-decimal number to ASCII. .TP .C HPPACCVDB() Converts a packed-decimal number to binary. .TP .C HPPACDIVD() Performs packed-decimal division. .TP .C HPPACLONGDIVD() Performs packed-decimal division (alternate routine). .TP .C HPPACMPYD() Performs packed-decimal multiplication. .TP .C HPPACNSLD() Performs a packed-decimal normalizing left shift. .TP .C HPPACSLD() Performs a packed-decimal left shift. .TP .C HPPACSRD() Performs a packed-decimal right shift. .TP .C HPPACSUBD() Performs packed-decimal subtraction. .PP For all operations, the value returned in the variable to which the .IR compcode argument points is one of the following values of type .C enum .CR HPPAC_CC\s0 : .RS .TP 15 .C HPPAC_CCG Result > 0 or operand1 > operand2 .TP .C HPPAC_CCL Result < 0 or operand1 < operand2 .TP .C HPPAC_CCE Result == 0 or operand1 == operand2 .RE .PP For all operations, the value returned in the variable to which the .IR pacstatus argument points is one of the following values of type .C enum .SM .CR HPPAC_STATUS\s0 . Their meanings are intended to be obvious: .IP .C HPPAC_NO_ERROR .IP .C HPPAC_DECIMAL_OVERFLOW .IP .C HPPAC_INVALID_ASCII_DIGIT .IP .C HPPAC_INVALID_PACKED_DECIMAL_DIGIT .IP .C HPPAC_INVALID_SOURCE_WORD_COUNT .IP .C HPPAC_INVALID_DECIMAL_OPERAND_LENGTH .IP .C HPPAC_DECIMAL_DIVIDE_BY_ZERO .RE .SH AUTHOR The .SM HPPAC library was developed by HP. .SH SEE ALSO .I Compiler Library/XL Reference Manual .\" .\" index@\s-1HPPAC\(**\s+1: \s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@\s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@packed decimal library, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@decimal library, packed, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@library, packed decimal, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" .\" toc@\f3hppac(3X)\f1@@@Series 800 HP\|3000-mode packed decimal library .\" .\" links@hppac.3x HPPACADDD.3x .\" links@hppac.3x HPPACCMPD.3x .\" links@hppac.3x HPPACCVAD.3x .\" links@hppac.3x HPPACCVBD.3x .\" links@hppac.3x HPPACCVDA.3x .\" links@hppac.3x HPPACCVDB.3x .\" links@hppac.3x HPPACDIVD.3x .\" links@hppac.3x HPPACLONGDI.3x .\" links@hppac.3x HPPACMPYD.3x .\" links@hppac.3x HPPACNSLD.3x .\" links@hppac.3x HPPACSLD.3x .\" links@hppac.3x HPPACSRD.3x .\" links@hppac.3x HPPACSUBD.3x .\" .\" fileset_database@hppac.3x PROGRAMING-MAN .\" $Header: hppac.3x,v 74.1 95/05/10 21:48:10 ssa Exp $ .TA h .TH hppac 3X "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONGDIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD\s+1 \- 3000-mode packed-decimal library .SH SYNOPSIS .C "#include " .nf .PP .C "void HPPACADDD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCMPD( .PD 0 .IP .C "unsigned char \(**operand1, .C "int op1digs, .C "unsigned char \(**operand2, .C "int op2digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVAD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVBD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned short \(**source, .C "int sourcewords, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDA( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sign_control, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDB( .PD 0 .IP .C "unsigned short \(**target, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .P .C ");" .PD .PP .C "void HPPACDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACLONGDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACMPYD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACNSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int \(**shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSRD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACSUBD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .fi .SH DESCRIPTION This set of calls invokes the library functions for emulating 3000-mode .SM (MPE V/E) packed-decimal operations. These functions are in library .C libcl which is searched when the option .C -lcl is used with .IR cc (1) or .IR ld (1). .TP 15 .C HPPACADDD() Performs packed-decimal addition. .TP .C HPPACCMPD() Compares two packed-decimal numbers. .TP .C HPPACCVAD() Converts an ASCII representation to packed-decimal. .TP .C HPPACCVBD() Converts a binary representation to packed-decimal. .TP .C HPPACCVDA() Converts a packed-decimal number to ASCII. .TP .C HPPACCVDB() Converts a packed-decimal number to binary. .TP .C HPPACDIVD() Performs packed-decimal division. .TP .C HPPACLONGDIVD() Performs packed-decimal division (alternate routine). .TP .C HPPACMPYD() Performs packed-decimal multiplication. .TP .C HPPACNSLD() Performs a packed-decimal normalizing left shift. .TP .C HPPACSLD() Performs a packed-decimal left shift. .TP .C HPPACSRD() Performs a packed-decimal right shift. .TP .C HPPACSUBD() Performs packed-decimal subtraction. .PP For all operations, the value returned in the variable to which the .IR compcode argument points is one of the following values of type .C enum .CR HPPAC_CC\s0 : .RS .TP 15 .C HPPAC_CCG Result > 0 or operand1 > operand2 .TP .C HPPAC_CCL Result < 0 or operand1 < operand2 .TP .C HPPAC_CCE Result == 0 or operand1 == operand2 .RE .PP For all operations, the value returned in the variable to which the .IR pacstatus argument points is one of the following values of type .C enum .SM .CR HPPAC_STATUS\s0 . Their meanings are intended to be obvious: .IP .C HPPAC_NO_ERROR .IP .C HPPAC_DECIMAL_OVERFLOW .IP .C HPPAC_INVALID_ASCII_DIGIT .IP .C HPPAC_INVALID_PACKED_DECIMAL_DIGIT .IP .C HPPAC_INVALID_SOURCE_WORD_COUNT .IP .C HPPAC_INVALID_DECIMAL_OPERAND_LENGTH .IP .C HPPAC_DECIMAL_DIVIDE_BY_ZERO .RE .SH AUTHOR The .SM HPPAC library was developed by HP. .SH SEE ALSO .I Compiler Library/XL Reference Manual .\" .\" index@\s-1HPPAC\(**\s+1: \s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@\s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@packed decimal library, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@decimal library, packed, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@library, packed decimal, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" .\" toc@\f3hppac(3X)\f1@@@Series 800 HP\|3000-mode packed decimal library .\" .\" links@hppac.3x HPPACADDD.3x .\" links@hppac.3x HPPACCMPD.3x .\" links@hppac.3x HPPACCVAD.3x .\" links@hppac.3x HPPACCVBD.3x .\" links@hppac.3x HPPACCVDA.3x .\" links@hppac.3x HPPACCVDB.3x .\" links@hppac.3x HPPACDIVD.3x .\" links@hppac.3x HPPACLONGDI.3x .\" links@hppac.3x HPPACMPYD.3x .\" links@hppac.3x HPPACNSLD.3x .\" links@hppac.3x HPPACSLD.3x .\" links@hppac.3x HPPACSRD.3x .\" links@hppac.3x HPPACSUBD.3x .\" .\" fileset_database@hppac.3x PROGRAMING-MAN .\" $Header: hppac.3x,v 74.1 95/05/10 21:48:10 ssa Exp $ .TA h .TH hppac 3X "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONGDIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD\s+1 \- 3000-mode packed-decimal library .SH SYNOPSIS .C "#include " .nf .PP .C "void HPPACADDD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCMPD( .PD 0 .IP .C "unsigned char \(**operand1, .C "int op1digs, .C "unsigned char \(**operand2, .C "int op2digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVAD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVBD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned short \(**source, .C "int sourcewords, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDA( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sign_control, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDB( .PD 0 .IP .C "unsigned short \(**target, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .P .C ");" .PD .PP .C "void HPPACDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACLONGDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACMPYD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACNSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int \(**shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSRD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACSUBD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .fi .SH DESCRIPTION This set of calls invokes the library functions for emulating 3000-mode .SM (MPE V/E) packed-decimal operations. These functions are in library .C libcl which is searched when the option .C -lcl is used with .IR cc (1) or .IR ld (1). .TP 15 .C HPPACADDD() Performs packed-decimal addition. .TP .C HPPACCMPD() Compares two packed-decimal numbers. .TP .C HPPACCVAD() Converts an ASCII representation to packed-decimal. .TP .C HPPACCVBD() Converts a binary representation to packed-decimal. .TP .C HPPACCVDA() Converts a packed-decimal number to ASCII. .TP .C HPPACCVDB() Converts a packed-decimal number to binary. .TP .C HPPACDIVD() Performs packed-decimal division. .TP .C HPPACLONGDIVD() Performs packed-decimal division (alternate routine). .TP .C HPPACMPYD() Performs packed-decimal multiplication. .TP .C HPPACNSLD() Performs a packed-decimal normalizing left shift. .TP .C HPPACSLD() Performs a packed-decimal left shift. .TP .C HPPACSRD() Performs a packed-decimal right shift. .TP .C HPPACSUBD() Performs packed-decimal subtraction. .PP For all operations, the value returned in the variable to which the .IR compcode argument points is one of the following values of type .C enum .CR HPPAC_CC\s0 : .RS .TP 15 .C HPPAC_CCG Result > 0 or operand1 > operand2 .TP .C HPPAC_CCL Result < 0 or operand1 < operand2 .TP .C HPPAC_CCE Result == 0 or operand1 == operand2 .RE .PP For all operations, the value returned in the variable to which the .IR pacstatus argument points is one of the following values of type .C enum .SM .CR HPPAC_STATUS\s0 . Their meanings are intended to be obvious: .IP .C HPPAC_NO_ERROR .IP .C HPPAC_DECIMAL_OVERFLOW .IP .C HPPAC_INVALID_ASCII_DIGIT .IP .C HPPAC_INVALID_PACKED_DECIMAL_DIGIT .IP .C HPPAC_INVALID_SOURCE_WORD_COUNT .IP .C HPPAC_INVALID_DECIMAL_OPERAND_LENGTH .IP .C HPPAC_DECIMAL_DIVIDE_BY_ZERO .RE .SH AUTHOR The .SM HPPAC library was developed by HP. .SH SEE ALSO .I Compiler Library/XL Reference Manual .\" .\" index@\s-1HPPAC\(**\s+1: \s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@\s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@packed decimal library, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@decimal library, packed, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@library, packed decimal, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" .\" toc@\f3hppac(3X)\f1@@@Series 800 HP\|3000-mode packed decimal library .\" .\" links@hppac.3x HPPACADDD.3x .\" links@hppac.3x HPPACCMPD.3x .\" links@hppac.3x HPPACCVAD.3x .\" links@hppac.3x HPPACCVBD.3x .\" links@hppac.3x HPPACCVDA.3x .\" links@hppac.3x HPPACCVDB.3x .\" links@hppac.3x HPPACDIVD.3x .\" links@hppac.3x HPPACLONGDI.3x .\" links@hppac.3x HPPACMPYD.3x .\" links@hppac.3x HPPACNSLD.3x .\" links@hppac.3x HPPACSLD.3x .\" links@hppac.3x HPPACSRD.3x .\" links@hppac.3x HPPACSUBD.3x .\" .\" fileset_database@hppac.3x PROGRAMING-MAN .\" $Header: hppac.3x,v 74.1 95/05/10 21:48:10 ssa Exp $ .TA h .TH hppac 3X "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONGDIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD\s+1 \- 3000-mode packed-decimal library .SH SYNOPSIS .C "#include " .nf .PP .C "void HPPACADDD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCMPD( .PD 0 .IP .C "unsigned char \(**operand1, .C "int op1digs, .C "unsigned char \(**operand2, .C "int op2digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVAD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVBD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned short \(**source, .C "int sourcewords, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDA( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sign_control, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDB( .PD 0 .IP .C "unsigned short \(**target, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .P .C ");" .PD .PP .C "void HPPACDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACLONGDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACMPYD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACNSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int \(**shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSRD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACSUBD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .fi .SH DESCRIPTION This set of calls invokes the library functions for emulating 3000-mode .SM (MPE V/E) packed-decimal operations. These functions are in library .C libcl which is searched when the option .C -lcl is used with .IR cc (1) or .IR ld (1). .TP 15 .C HPPACADDD() Performs packed-decimal addition. .TP .C HPPACCMPD() Compares two packed-decimal numbers. .TP .C HPPACCVAD() Converts an ASCII representation to packed-decimal. .TP .C HPPACCVBD() Converts a binary representation to packed-decimal. .TP .C HPPACCVDA() Converts a packed-decimal number to ASCII. .TP .C HPPACCVDB() Converts a packed-decimal number to binary. .TP .C HPPACDIVD() Performs packed-decimal division. .TP .C HPPACLONGDIVD() Performs packed-decimal division (alternate routine). .TP .C HPPACMPYD() Performs packed-decimal multiplication. .TP .C HPPACNSLD() Performs a packed-decimal normalizing left shift. .TP .C HPPACSLD() Performs a packed-decimal left shift. .TP .C HPPACSRD() Performs a packed-decimal right shift. .TP .C HPPACSUBD() Performs packed-decimal subtraction. .PP For all operations, the value returned in the variable to which the .IR compcode argument points is one of the following values of type .C enum .CR HPPAC_CC\s0 : .RS .TP 15 .C HPPAC_CCG Result > 0 or operand1 > operand2 .TP .C HPPAC_CCL Result < 0 or operand1 < operand2 .TP .C HPPAC_CCE Result == 0 or operand1 == operand2 .RE .PP For all operations, the value returned in the variable to which the .IR pacstatus argument points is one of the following values of type .C enum .SM .CR HPPAC_STATUS\s0 . Their meanings are intended to be obvious: .IP .C HPPAC_NO_ERROR .IP .C HPPAC_DECIMAL_OVERFLOW .IP .C HPPAC_INVALID_ASCII_DIGIT .IP .C HPPAC_INVALID_PACKED_DECIMAL_DIGIT .IP .C HPPAC_INVALID_SOURCE_WORD_COUNT .IP .C HPPAC_INVALID_DECIMAL_OPERAND_LENGTH .IP .C HPPAC_DECIMAL_DIVIDE_BY_ZERO .RE .SH AUTHOR The .SM HPPAC library was developed by HP. .SH SEE ALSO .I Compiler Library/XL Reference Manual .\" .\" index@\s-1HPPAC\(**\s+1: \s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@\s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@packed decimal library, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@decimal library, packed, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@library, packed decimal, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" .\" toc@\f3hppac(3X)\f1@@@Series 800 HP\|3000-mode packed decimal library .\" .\" links@hppac.3x HPPACADDD.3x .\" links@hppac.3x HPPACCMPD.3x .\" links@hppac.3x HPPACCVAD.3x .\" links@hppac.3x HPPACCVBD.3x .\" links@hppac.3x HPPACCVDA.3x .\" links@hppac.3x HPPACCVDB.3x .\" links@hppac.3x HPPACDIVD.3x .\" links@hppac.3x HPPACLONGDI.3x .\" links@hppac.3x HPPACMPYD.3x .\" links@hppac.3x HPPACNSLD.3x .\" links@hppac.3x HPPACSLD.3x .\" links@hppac.3x HPPACSRD.3x .\" links@hppac.3x HPPACSUBD.3x .\" .\" fileset_database@hppac.3x PROGRAMING-MAN .\" $Header: hppac.3x,v 74.1 95/05/10 21:48:10 ssa Exp $ .TA h .TH hppac 3X "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONGDIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD\s+1 \- 3000-mode packed-decimal library .SH SYNOPSIS .C "#include " .nf .PP .C "void HPPACADDD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCMPD( .PD 0 .IP .C "unsigned char \(**operand1, .C "int op1digs, .C "unsigned char \(**operand2, .C "int op2digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVAD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVBD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned short \(**source, .C "int sourcewords, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDA( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sign_control, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDB( .PD 0 .IP .C "unsigned short \(**target, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .P .C ");" .PD .PP .C "void HPPACDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACLONGDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACMPYD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACNSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int \(**shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSRD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACSUBD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .fi .SH DESCRIPTION This set of calls invokes the library functions for emulating 3000-mode .SM (MPE V/E) packed-decimal operations. These functions are in library .C libcl which is searched when the option .C -lcl is used with .IR cc (1) or .IR ld (1). .TP 15 .C HPPACADDD() Performs packed-decimal addition. .TP .C HPPACCMPD() Compares two packed-decimal numbers. .TP .C HPPACCVAD() Converts an ASCII representation to packed-decimal. .TP .C HPPACCVBD() Converts a binary representation to packed-decimal. .TP .C HPPACCVDA() Converts a packed-decimal number to ASCII. .TP .C HPPACCVDB() Converts a packed-decimal number to binary. .TP .C HPPACDIVD() Performs packed-decimal division. .TP .C HPPACLONGDIVD() Performs packed-decimal division (alternate routine). .TP .C HPPACMPYD() Performs packed-decimal multiplication. .TP .C HPPACNSLD() Performs a packed-decimal normalizing left shift. .TP .C HPPACSLD() Performs a packed-decimal left shift. .TP .C HPPACSRD() Performs a packed-decimal right shift. .TP .C HPPACSUBD() Performs packed-decimal subtraction. .PP For all operations, the value returned in the variable to which the .IR compcode argument points is one of the following values of type .C enum .CR HPPAC_CC\s0 : .RS .TP 15 .C HPPAC_CCG Result > 0 or operand1 > operand2 .TP .C HPPAC_CCL Result < 0 or operand1 < operand2 .TP .C HPPAC_CCE Result == 0 or operand1 == operand2 .RE .PP For all operations, the value returned in the variable to which the .IR pacstatus argument points is one of the following values of type .C enum .SM .CR HPPAC_STATUS\s0 . Their meanings are intended to be obvious: .IP .C HPPAC_NO_ERROR .IP .C HPPAC_DECIMAL_OVERFLOW .IP .C HPPAC_INVALID_ASCII_DIGIT .IP .C HPPAC_INVALID_PACKED_DECIMAL_DIGIT .IP .C HPPAC_INVALID_SOURCE_WORD_COUNT .IP .C HPPAC_INVALID_DECIMAL_OPERAND_LENGTH .IP .C HPPAC_DECIMAL_DIVIDE_BY_ZERO .RE .SH AUTHOR The .SM HPPAC library was developed by HP. .SH SEE ALSO .I Compiler Library/XL Reference Manual .\" .\" index@\s-1HPPAC\(**\s+1: \s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@\s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@packed decimal library, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@decimal library, packed, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@library, packed decimal, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" .\" toc@\f3hppac(3X)\f1@@@Series 800 HP\|3000-mode packed decimal library .\" .\" links@hppac.3x HPPACADDD.3x .\" links@hppac.3x HPPACCMPD.3x .\" links@hppac.3x HPPACCVAD.3x .\" links@hppac.3x HPPACCVBD.3x .\" links@hppac.3x HPPACCVDA.3x .\" links@hppac.3x HPPACCVDB.3x .\" links@hppac.3x HPPACDIVD.3x .\" links@hppac.3x HPPACLONGDI.3x .\" links@hppac.3x HPPACMPYD.3x .\" links@hppac.3x HPPACNSLD.3x .\" links@hppac.3x HPPACSLD.3x .\" links@hppac.3x HPPACSRD.3x .\" links@hppac.3x HPPACSUBD.3x .\" .\" fileset_database@hppac.3x PROGRAMING-MAN .\" $Header: regexp.3x,v 72.5 94/11/15 09:56:02 ssa Exp $ .TA r .TH regexp 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compile(\|), step(\|), advance(\|) \- regular expression compile and match routines .SH SYNOPSIS .C #define INIT .I "declarations" .br .C #define GETC() .I "getc statements" .br .C #define PEEKC() .I "peekc statements" .br .C #define UNGETC(c) .I "ungetc statements" .br .C #define RETURN(pointer) .I "return statements" .br .C #define ERROR(val) .I "error statements" .PP .C "#include " .PP .C "char *compile(" .nf .PD 0 .IP .C "const char *instring," .C "char *expbuf," .C "const char *endbuf," .C "int eof" .PP .C ");" .PD .fi .PP .C "int step(const char *string, const char *expbuf);" .PP .C "int advance(const char *string, const char *expbuf);" .PP .C "extern char *loc1, *loc2, *locs;" .PP .C "extern int circf, sed, nbra;" .SS Remarks Features documented in this manual entry are obsolescent and may be removed in a future .SM HP-UX release. Use of .IR regcomp (3C) functions instead is recommended. .SH DESCRIPTION These functions are general-purpose regular expression matching routines to be used in programs that perform Basic Regular Expression (see .IR regexp (5)) matching. These functions are defined in .RC < regexp.h >. .PP The functions .C step() and .C advance() do pattern matching given a character string and a compiled regular expression as input. .C compile() takes a Basic Regular Expression as input and produces a compiled expression that can be used with .C step() and .CR advance() . .PP The interface to this file is unpleasantly complex. Programs that include this file must have the following five macros declared before the .C #include statement. These macros are used by the .C compile() routine. .TP 15 .C GETC() Return the value of the next byte in the regular expression pattern. Successive calls to .C GETC() should return successive bytes of the regular expression. .TP .C PEEKC() Return the next byte in the regular expression. Successive calls to .C PEEKC() should return the same byte (which should also be the next byte returned by .CR GETC() . .TP .CI UNGETC( c ) Cause the argument .I c to be returned by the next call to .C GETC() (and .CR PEEKC() ). No more than one byte of pushback is ever needed, and this byte is guaranteed to be the last byte read by .CR GETC() . The value of the macro .CI UNGETC( c ) is always ignored. .TP .CI RETURN( pointer ) This macro is used on normal exit of the .C compile() routine. The value of the argument .I pointer is a pointer to the character after the last character of the compiled regular expression. This is useful to programs that must manage memory allocation. .TP .CI ERROR( val ) This is the abnormal return from the .C compile() routine. The argument .I val is an error number (see table below for meanings). This call should never return. .RS .RS .PD 0 .TP 8 .B Error .B Meaning .TP 11 Range endpoint too large. .TP 16 Bad number. .TP 25 ``\f3\e\f2digit\f1'' out of range. .TP 36 Illegal or missing delimiter. .TP 41 No remembered search string. .TP 42 .C \e( \e) imbalance. .TP 43 Too many .CR \e( . .TP 44 More than 2 numbers given in .CR \e{\0\e} . .TP 45 .C } expected after .CR \e . .TP 46 First number exceeds second in .CR \e{\0\e} . .TP 49 .C [ ] imbalance. .TP 50 Regular expression overflow. .RE .RE .PD .PP The syntax of the .C compile() routine is as follows: .IP .CI compile( instring , .CI expbuf , .CI endbuf , .CI eof ) .PP The first parameter .I instring is never used explicitly by the .C compile() routine, but is useful for programs that pass down different pointers to input characters. It is sometimes used in the .C INIT declaration (see below). Programs that call functions to input characters or have characters in an external array can pass down a value of .C ((char *) 0) for this parameter. .PP The next parameter .I expbuf is a character pointer. It points to the location where the compiled regular expression will be placed. .PP The parameter .I endbuf is one more than the highest address where the compiled regular expression can be placed. If the compiled expression cannot fit in .RI ( endbuf \|\(mi\| expbuf ) bytes, a call to .C ERROR(50) is made. .PP The parameter .I eof is the character which marks the end of the regular expression. For example, in .IR ed (1), this character is usually a .CR / . .PP Each program that includes this file must have a .C #define statement for .CR INIT . This definition is placed right after the declaration for the function .C compile() and the opening curly brace .CR { . It is used for dependent declarations and initializations. Most often it is used to set a register variable to point to the beginning of the regular expression so that this register variable can be used in the declarations for .CR GETC() , .CR PEEKC() , and .CR UNGETC() . Otherwise it can be used to declare external variables that might be used by .CR GETC() , .CR PEEKC() , and .CR UNGETC() . See the example below of the declarations taken from .IR grep (1). .PP .C step() also performs actual regular expression matching in this file. The call to .I step is as follows: .IP .CI step( string , .CI expbuf ) .PP The first parameter to .C step() is a pointer to a string of characters to be checked for a match. This string should be null-terminated. .PP The second parameter .I expbuf is the compiled regular expression that was obtained by a call to .CR compile() . .PP .C step() returns non-zero if the given string matches the regular expression, and zero if the expressions do not match. If there is a match, two external character pointers are set as a side effect to the call to .CR step() . The variable set in .C step() is .CR loc1 . This is a pointer to the first character that matched the regular expression. The variable .CR loc2 , which is set by the function .CR advance() , points to the character after the last character that matches the regular expression. Thus, if the regular expression matches the entire line, .C loc1 points to the first character of .I string and .C loc2 points to the null at the end of .IR string . .PP .C step() uses the external variable .CR circf() , which is set by .C compile() if the regular expression begins with .CR ^ . If this is set, .C step() tries to match the regular expression to the beginning of the string only. If more than one regular expression is to be compiled before the first is executed, the value of .I circf should be saved for each compiled expression and .I circf should be set to that saved value before each call to .CR step() . .PP .C advance() is called from .C step() with the same arguments as .CR step() . The purpose of .C step() is to step through the .I string argument and call .C advance() until .C advance() returns non-zero, which indicates a match, or until the end of .I string is reached. To constrain .I string to beginning-of-line in all cases, .C step() need not be called; simply call .CR advance() . .PP When .C advance() encounters a .C * or .C \e{\|\e} sequence in the regular expression, it advances its pointer to the string to be matched as far as possible and recursively calls itself, trying to match the rest of the string to the rest of the regular expression. As long as there is no match, .I advance backs up along the string until it finds a match or reaches the point in the string that initially matched the .C * or .CR \e{\|\e} . It is sometimes desirable to stop this backing up before the initial point in the string is reached. If the external character pointer .C locs is equal to the point in the string at sometime during the backing up process, .C advance() breaks out of the loop that backs up and returns zero. This is used by .IR ed (1) and .IR sed (1) for substitutions done globally (not just the first occurrence, but the whole line) so, for example, expressions such as .C s/y*//g do not loop forever. .PP The additional external variables .C sed and .C nbra are used for special purposes. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions. .PP The .C LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, and the characters matched by character class expressions in regular expressions. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following is an example of how the regular expression macros and calls look from .IR grep (1): .nf .IP .C "#define INIT register char *sp = instring;" .C "#define GETC() (*sp++)" .C "#define PEEKC() (*sp)" .C "#define UNGETC(c) (--sp)" .C "#define RETURN(c) return;" .C "#define ERROR(c) regerr()" .IP .C "#include " \h'.5i'.\|.\|. .C "(void) compile(*argv, expbuf, &expbuf[ESIZE], '\e0');" \h'.5i'.\|.\|. .C "if (step(linebuf, expbuf))" .C " succeed();" .fi .SH AUTHOR .CR regexp() was developed by OSF and HP. .SH SEE ALSO grep(1), regcomp(3C), setlocale(3C), regexp(5). .SH STANDARDS CONFORMANCE .CR advance() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR compile() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc1 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc2 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR locs ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR step() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4compile()\f1 \- regular expression compile routine@@@\f3regexp(3X)\f1 .\" index@\f4step()\f1 \- regular expression string comparison routine@@@\f3regexp(3X)\f1 .\" index@\f4advance()\f1 \- regular expression substring comparison routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1expression, regular, compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1compile and match routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1comparison routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1match routines for regular expressions@@@\f3regexp(3X)\f1 .\" .\" toc@\f3regexp(3X)\f1:\0\0\f4compile()\f1, \f4step()\f1, \f4advance()\f1@@@regular expression compile and match routines .\" toc@\f4compile()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4step()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4advance()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" .\" links@regexp.3x compile.3x .\" links@regexp.3x step.3x .\" links@regexp.3x advance.3x .\" links@regexp.3x INIT.3x .\" links@regexp.3x GETC.3x .\" links@regexp.3x PEEKC.3x .\" links@regexp.3x UNGETC.3x .\" links@regexp.3x RETURN.3x .\" links@regexp.3x ERROR.3x .\" .\" fileset_database@regexp.3x PROGRAMING-MAN ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH MrmCloseHierarchy 3X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIMrmCloseHierarchy\fP \- Closes a UID hierarchy .SH SYNOPSIS .nf .sS .iS \&#include \fI .sp \n(PDu .ta .5i 1.5i .nf Cardinal MrmCloseHierarchy(\fBhierarchy_id\fI) MrmHierarchy \fBhierarchy_id\fI; .iE .sE .SH DESCRIPTION .fi The \fIMrmCloseHierarchy\fP function closes a UID hierarchy previously opened by \fIMrmOpenHierarchyPerDisplay\fP. All files associated with the hierarchy are closed by the Motif Resource Manager (MRM) and all associated memory is returned. .IP "\fBhierarchy_id\fP" Specifies the ID of a previously opened UID hierarchy. The \fBhierarchy_id\fP was returned in a previous call to \fIMrmOpenHierarchyPerDisplay\fP. .nL .ne 15 .SH RETURN VALUE This function returns one of these status return constants: .IP "\fIMrmSUCCESS\fP" The function executed successfully. .IP "\fIMrmBAD_HIERARCHY\fP" The hierarchy ID was invalid. .IP "\fIMrmFAILURE\fP" The function failed. .SH RELATED INFORMATION .na \fIMrmOpenHierarchyPerDisplay(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH MrmFetchBitmapLiteral 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIMrmFetchBitmapLiteral\fP \- Fetches a bitmap literal from a hierarchy .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Cardinal MrmFetchBitmapLiteral(\fBhierarchy_id, index, screen, display, pixmap_return, width, height\fI) .ta .5i 1.5i .nf MrmHierarchy \fBhierarchy_id\fI; String \fBindex\fI; Screen *\fBscreen\fI; Display *\fBdisplay\fI; Pixmap *\fBpixmap_return\fI; Dimension *\fBwidth\fI; Dimension *\fBheight\fI; .iE .sE .SH DESCRIPTION .fi The \fIMrmFetchBitmapLiteral\fP function fetches a bitmap literal from an MRM hierarchy, and converts the bitmap literal to an X pixmap of depth 1. The function returns this pixmap and its width and height. .IP "\fBhierarchy_id\fP" Specifies the ID of the UID hierarchy that contains the specified icon literal. The \fBhierarchy_id\fP was returned in a previous call to \fIMrmOpenHierarchyPerDisplay\fP. .IP "\fBindex\fP" Specifies the UIL name of the bitmap literal to fetch. .IP "\fBscreen\fP" Specifies the screen used for the pixmap. The \fBscreen\fP argument specifies a pointer to the Xlib structure \fIScreen\fP which contains the information about that screen and is linked to the \fIDisplay\fP structure. For more information on the \fIDisplay\fP and \fIScreen\fPstructures, see the Xlib function \fIXOpenDisplay\fP and the associated screen information macros. .IP "\fBdisplay\fP" Specifies the display used for the pixmap. The \fBdisplay\fP argument specifies the connection to the X server. For more information on the \fIDisplay\fP structure, see the Xlib function \fIXOpenDisplay\fP. .IP "\fBpixmap_return\fP" Returns the resulting X pixmap value. .IP "\fBwidth\fP" Specifies a pointer to the width of the pixmap. .IP "\fBheight\fP" Specifies a pointer to the height of the pixmap. .SH RETURN VALUE This function returns one of these status return constants: .IP "\fIMrmSUCCESS\fP" The function executed successfully. .IP "\fIMrmBAD_HIERARCHY\fP" The hierarchy ID was invalid. .IP "\fIMrmNOT_FOUND\fP" The bitmap literal was not found in the hierarchy. .IP "\fIMrmWRONG_TYPE\fP" The caller tried to fetch a literal of a type not supported by this function. .IP "\fIMrmFAILURE\fP" The function failed. .SH RELATED INFORMATION .na \fIMrmFetchIconLiteral(3X)\fP, \fIMrmFetchLiteral(3X)\fP, and \fIXOpenDisplay(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH MrmFetchColorLiteral 3X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIMrmFetchColorLiteral\fP \- Fetches a named color literal from a UID file .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int MrmFetchColorLiteral(\fBhierarchy_id, index, display, colormap_id, pixel\fI) .ta .5i 1.5i .nf MrmHierarchy \fBhierarchy_id\fI; String \fBindex\fI; Display *\fBdisplay\fI; Colormap \fBcolormap_id\fI; Pixel *\fBpixel\fI; .iE .sE .SH DESCRIPTION .fi The \fIMrmFetchColorLiteral\fP function fetches a named color literal from a UID file, and converts the color literal to a pixel color value. .IP "\fBhierarchy_id\fP" Specifies the ID of the UID hierarchy that contains the specified literal. The \fBhierarchy_id\fP was returned in a previous call to \fIMrmOpenHierarchyPerDisplay\fP. .IP "\fBindex\fP" Specifies the UIL name of the color literal to fetch. You must define this name in UIL as an exported value. .IP "\fBdisplay\fP" Specifies the display used for the pixmap. The \fBdisplay\fP argument specifies the connection to the X server. For more information on the \fIDisplay\fP structure, see the Xlib function \fIXOpenDisplay\fP. .IP "\fBcolormap_id\fP" Specifies the ID of the color map. If NULL, the default color map is used. .IP "\fBpixel\fP" Returns the ID of the color literal. .nL .ne 9 .SH RETURN VALUE This function returns one of these status return constants: .IP "\fIMrmSUCCESS\fP" The function executed successfully. .IP "\fIMrmBAD_HIERARCHY\fP" The hierarchy ID was invalid. .IP "\fIMrmNOT_FOUND\fP" The color literal was not found in the UIL file. .IP "\fIMrmWRONG_TYPE\fP" The caller tried to fetch a literal of a type not supported by this function. .IP "\fIMrmFAILURE\fP" The function failed. .SH RELATED INFORMATION .na \fIMrmFetchBitmapLiteral(3X)\fP, \fIMrmOpenHierarchyPerDisplay(3X)\fP, \fIMrmFetchIconLiteral(3X)\fP, \fIMrmFetchLiteral(3X)\fP, and \fIXOpenDisplay(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH MrmFetchIconLiteral 3X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIMrmFetchIconLiteral\fP \- Fetches an icon literal from a hierarchy .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int MrmFetchIconLiteral(\fBhierarchy_id, index, screen, display, fgpix, bgpix, pixmap\fI) .ta .5i 1.5i .nf MrmHierarchy \fBhierarchy_id\fI; String \fBindex\fI; Screen *\fBscreen\fI; Display *\fBdisplay\fI; Pixel \fBfgpix\fI; Pixel \fBbgpix\fI; Pixmap *\fBpixmap\fI; .iE .sE .SH DESCRIPTION .fi The \fIMrmFetchIconLiteral\fP function fetches an icon literal from an MRM hierarchy, and converts the icon literal to an X pixmap. .IP "\fBhierarchy_id\fP" Specifies the ID of the UID hierarchy that contains the specified icon literal. The \fBhierarchy_id\fP was returned in a previous call to \fIMrmOpenHierarchyPerDisplay\fP. .IP "\fBindex\fP" Specifies the UIL name of the icon literal to fetch. .IP "\fBscreen\fP" Specifies the screen used for the pixmap. The \fBscreen\fP argument specifies a pointer to the Xlib structure \fIScreen\fP which contains the information about that screen and is linked to the \fIDisplay\fP structure. .ne 8 For more information on the \fIDisplay\fP and \fIScreen\fP structures, see the Xlib function \fIXOpenDisplay\fP and the associated screen information macros. .IP "\fBdisplay\fP" Specifies the display used for the pixmap. The \fBdisplay\fP argument specifies the connection to the X server. For more information on the \fIDisplay\fP structure, see the Xlib function \fIXOpenDisplay\fP. .IP "\fBfgpix\fP" Specifies the foreground color for the pixmap. .IP "\fBbgpix\fP" Specifies the background color for the pixmap. .IP "\fBpixmap\fP" Returns the resulting X pixmap value. .SH RETURN VALUE This function returns one of these status return constants: .IP "\fIMrmSUCCESS\fP" The function executed successfully. .IP "\fIMrmBAD_HIERARCHY\fP" The hierarchy ID was invalid. .IP "\fIMrmNOT_FOUND\fP" The icon literal was not found in the hierarchy. .IP "\fIMrmWRONG_TYPE\fP" The caller tried to fetch a literal of a type not supported by this function. .IP "\fIMrmFAILURE\fP" The function failed. .SH RELATED INFORMATION .na \fIMrmFetchBitmapLiteral(3X)\fP, \fIMrmOpenHierarchyPerDisplay(3X)\fP, \fIMrmFetchLiteral(3X)\fP, \fIMrmFetchColorLiteral(3X)\fP, and \fIXOpenDisplay(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH MrmFetchLiteral 3X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIMrmFetchLiteral\fP \- Fetches a literal from a UID file .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int MrmFetchLiteral(\fBhierarchy_id, index, display, value, type\fI) .ta .5i 1.5i .nf MrmHierarchy \fBhierarchy_id\fI; String \fBindex\fI; Display *\fBdisplay\fI; XtPointer *\fBvalue\fI; MrmCode *\fBtype\fI; .iE .sE .SH DESCRIPTION .fi The \fIMrmFetchLiteral\fP function reads and returns the value and type of a literal (named value) that is stored as a public resource in a single UID file. This function returns a pointer to the value of the literal. For example, an integer is always returned as a pointer to an integer, and a string is always returned as a pointer to a string. .PP Applications should not use \fIMrmFetchLiteral\fP for fetching icon or color literals. If this is attempted, \fIMrmFetchLiteral\fP returns an error. .IP "\fBhierarchy_id\fP" Specifies the ID of the UID hierarchy that contains the specified literal. The \fBhierarchy_id\fP was returned in a previous call to \fIMrmOpenHierarchyPerDisplay\fP. .IP "\fBindex\fP" Specifies the UIL name of the literal (pixmap) to fetch. You must define this name in UIL as an exported value. .IP "\fBdisplay\fP" Specifies the display used for the pixmap. The \fBdisplay\fP argument specifies the connection to the X server. For more information on the \fIDisplay\fP structure see the Xlib function \fIXOpenDisplay\fP. .IP "\fBvalue\fP" Returns the ID of the named literal's value. .IP "\fBtype\fP" Returns the named literal's data type. Types are defined in the include file \fI\fP. .SH RETURN VALUE This function returns one of these status return constants: .IP "\fIMrmSUCCESS\fP" The function executed successfully. .IP "\fIMrmBAD_HIERARCHY\fP" The hierarchy ID was invalid. .IP "\fIMrmNOT_FOUND\fP" The literal was not found in the UIL file. .IP "\fIMrmWRONG_TYPE\fP" The caller tried to fetch a literal of a type not supported by this function. .IP "\fIMrmFAILURE\fP" The function failed. .SH RELATED INFORMATION .na \fIMrmFetchBitmapLiteral(3X)\fP, \fIMrmOpenHierarchyPerDisplay(3X)\fP, \fIMrmFetchIconLiteral(3X)\fP, \fIMrmFetchColorLiteral(3X)\fP, and \fIXOpenDisplay(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH MrmFetchSetValues 3X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIMrmFetchSetValues\fP \- Fetches the values to be set from literals stored in UID files .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Cardinal MrmFetchSetValues(\fBhierarchy_id, widget, args, num_args\fI) .ta .5i 1.5i .nf MrmHierarchy \fBhierarchy_id\fI; Widget \fBwidget\fI; ArgList \fBargs\fI; Cardinal \fBnum_args\fI; .iE .sE .SH DESCRIPTION .fi The \fIMrmFetchSetValues\fP function is similar to \fIXtSetValues\fP, except that the values to be set are defined by the UIL named values that are stored in the UID hierarchy. \fIMrmFetchSetValues\fP fetches the values to be set from literals stored in UID files. .IP "\fBhierarchy_id\fP" Specifies the ID of the UID hierarchy that contains the specified literal. The \fBhierarchy_id\fP was returned in a previous call to \fIMrmOpenHierarchyPerDisplay\fP. .IP "\fBwidget\fP" Specifies the widget that is modified. .IP "\fBargs\fP" Specifies an argument list that identifies the widget arguments to be modified as well as the index (UIL name) of the literal that defines the value for that argument. The name part of each argument (args[n].name) must begin with the string \fIXmN\fP followed by the name that uniquely identifies this attribute tag. For example, \fIXmNwidth\fP is the attribute name associated with the core argument \fBwidth\fP. The value part (args[n].value) must be a string that gives the index (UIL name) of the literal. You must define all literals in UIL as exported values. .IP "\fBnum_args\fP" Specifies the number of entries in \fBargs\fP. .nL .ne 7 .PP This function sets the values on a widget, evaluating the values as public literal resource references resolvable from a UID hierarchy. Each literal is fetched from the hierarchy, and its value is modified and converted as required. This value is then placed in the argument list and used as the actual value for an \fIXtSetValues\fP call. \fIMrmFetchSetValues\fP allows a widget to be modified after creation using UID file values exactly as is done for creation values in \fIMrmFetchWidget\fP. .PP As in \fIMrmFetchWidget\fP, each argument whose value can be evaluated from the UID hierarchy is set in the widget. Values that are not found or values in which conversion errors occur are not modified. .PP Each entry in the argument list identifies an argument to be modified in the widget. The name part identifies the tag, which begins with \fIXmN\fP. The value part must be a string whose value is the index of the literal. Thus, the following code would modify the label resource of the widget to have the value of the literal accessed by the index OK_button_label in the hierarchy: .oS args[n].name = XmNlabel; args[n].value = "OK_button_label"; .oE .SH "RETURN VALUE" This function returns one of these status return constants: .IP "\fIMrmSUCCESS\fP" The function executed successfully. .IP "\fIMrmPARTIAL_SUCCESS\fP" At least one literal was successfully fetched. .IP "\fIMrmBAD_HIERARCHY\fP" The hierarchy ID was invalid. .IP "\fIMrmFAILURE\fP" The function failed. .nL .ne 10 .SH RELATED INFORMATION .na \fIMrmOpenHierarchyPerDisplay(3X)\fP, \fIXtSetValues(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH MrmFetchWidget 3X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIMrmFetchWidget\fP \- Fetches and creates any indexed (UIL named) application widgets and its children .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Cardinal MrmFetchWidget(\fBhierarchy_id, index, parent_widget, widget, class\fI) .ta .5i 1.5i .nf MrmHierarchy \fBhierarchy_id\fI; String \fBindex\fI; Widget \fBparent_widget\fI; Widget *\fBwidget\fI; MrmType *\fBclass\fI; .iE .sE .SH DESCRIPTION .fi The \fIMrmFetchWidget\fP function fetches and creates an indexed application widget and its children. The indexed application widget is any widget that is named in UIL. In .ne 2i fetch operations, the fetched widget's subtree is also fetched and created. This widget must not appear as the child of a widget within its own subtree. \fIMrmFetchWidget\fP does not execute \fIXtManageChild\fP for the newly created widget. .IP "\fBhierarchy_id\fP" Specifies the ID of the \fIuid\fP hierarchy that contains the interface definition. The \fBhierarchy_id\fP was returned in a previous call to \fIMrmOpenHierarchyPerDisplay\fP. .IP "\fBindex\fP" Specifies the UIL name of the widget to fetch. .IP "\fBparent_widget\fP" Specifies the parent widget ID. .IP "\fBwidget\fP" Returns the widget ID of the created widget. .IP "\fBclass\fP" Returns the class code identifying MRM's widget class. The widget class code for the main window widget, for example, is \fIMRMwcMainWindow\fP. Literals identifying MRM widget class codes are defined in \fIMrm.h\fP. .PP An application can fetch any named widget in the \fIuid\fP hierarchy using \fIMrmFetchWidget\fP. \fIMrmFetchWidget\fP can be called at any time to fetch a widget that was not fetched at application startup. \fIMrmFetchWidget\fP can be used to defer fetching pop-up widgets until they are first referenced (presumably in a callback), and then used to fetch them once. .PP \fIMrmFetchWidget\fP can also create multiple instances of a widget (and its subtree). In this case, the \fIuid\fP definition functions as a template; a widget definition can be fetched any number of times. An application can use this to make multiple instances of a widget, for example, in a dialog box box or menu. .PP The index (UIL name) that identifies the widget must be known to the application. .nL .ne 15 .SH RETURN VALUE This function returns one of these status return constants: .IP "\fIMrmSUCCESS\fP" The function executed successfully. .IP "\fIMrmBAD_HIERARCHY\fP" The hierarchy ID was invalid. .IP "\fIMrmNOT_FOUND\fP" The widget was not found in UID hierarchy. .IP "\fIMrmFAILURE\fP" The function failed. .SH RELATED INFORMATION .na \fIMrmOpenHierarchyPerDisplay(3X)\fP, \fIMrmFetchWidgetOverride(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH MrmFetchWidgetOverride 3X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIMrmFetchWidgetOverride\fP \- Fetches any indexed (UIL named) application widget. It overrides the arguments specified for this application widget in UIL .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Cardinal MrmFetchWidgetOverride(\fBhierarchy_id, index, parent_widget, override_name, .in +10n override_args, override_num_args, widget, class\fI) .in -10n .ta .5i 1.5i .nf MrmHierarchy \fBhierarchy_id\fI; String \fBindex\fI; Widget \fBparent_widget\fI; String \fBoverride_name\fI; ArgList \fBoverride_args\fI; Cardinal \fBoverride_num_args\fI; Widget *\fBwidget\fI; MrmType *\fBclass\fI; .iE .sE .SH DESCRIPTION .fi The \fIMrmFetchWidgetOverride\fP function is the extended version of \fIMrmFetchWidget\fP. It is identical to \fIMrmFetchWidget\fP, except that it allows the caller to override the widget's name and any arguments that \fIMrmFetchWidget\fP would otherwise retrieve from the UID file or one of the defaulting mechanisms. That is, the override argument list is not limited to those arguments in the UID file. .PP The override arguments apply only to the widget fetched and returned by this function. Its children (subtree) do not receive any override parameters. .IP "\fBhierarchy_id\fP" Specifies the ID of the UID hierarchy that contains the interface definition. The \fBhierarchy_id\fP was returned in a previous call to \fIMrmOpenHierarchyPerDisplay\fP. .IP "\fBindex\fP" Specifies the UIL name of the widget to fetch. .IP "\fBparent_widget\fP" Specifies the parent widget ID. .IP "\fBoverride_name\fP" Specifies the name to override the widget name. Use a NULL value if you do not want to override the widget name. .IP "\fBoverride_args\fP" Specifies the override argument list, exactly as given to \fIXtCreateWidget\fP (conversion complete and so forth). Use a NULL value if you do not want to override the argument list. .IP "\fBoverride_num_args\fP" Specifies the number of arguments in \fBoverride_args\fP. .IP "\fBwidget\fP" Returns the widget ID of the created widget. .IP "\fBclass\fP" Returns the class code identifying MRM's widget class. Literals identifying MRM widget class codes are defined in the include file \fI\fP. .nL .ne 15 .SH "RETURN VALUE" This function returns one of these status return constants: .IP "\fIMrmSUCCESS\fP" The function executed successfully. .IP "\fIMrmBAD_HIERARCHY\fP" The hierarchy ID was invalid. .IP "\fIMrmNOT_FOUND\fP" The widget was not found in UID hierarchy. .IP "\fIMrmFAILURE\fP" The function failed. .SH RELATED INFORMATION .na \fIMrmOpenHierarchyPerDisplay(3X)\fP, \fIMrmFetchWidget(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH MrmInitialize 3X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIMrmInitialize\fP \- Prepares an application to use MRM widget-fetching facilities .SH SYNOPSIS .nf .sS .iS void MrmInitialize() .iE .sE .SH DESCRIPTION .fi The \fIMrmInitialize\fP function must be called to prepare an application to use MRM widget-fetching facilities. You must call this function prior to fetching a widget. However, it is good programming practice to call \fIMrmInitialize\fP prior to performing any MRM operations. .PP \fIMrmInitialize\fP initializes the internal data structures that MRM needs to successfully perform type conversion on arguments and to successfully access widget creation facilities. An application must call \fIMrmInitialize\fP before it uses other MRM functions. ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH MrmOpenHierarchy 3X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIMrmOpenHierarchy\fP \- Allocates a hierarchy ID and opens all the UID files in the hierarchy .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf Cardinal MrmOpenHierarchy(\fBnum_files, file_names_list, ancillary_structures_list, hierarchy_id\fI) .ta .5i 2.5i .nf MrmCount \fBnum_files\fI; String \fBfile_names_list\fI[]; MrmOsOpenParamPtr *\fBancillary_structures_list\fI; MrmHierarchy *\fBhierarchy_id\fI; .iE .sE .SH DESCRIPTION .fi This routine is obsolete and exists for compatibility with previous releases. It is replaced by \fIMrmOpenHierarchyPerDisplay\fP. \fIMrmOpenHierarchy\fP is identical to \fIMrmOpenHierarchyPerDisplay\fP except that \fIMrmOpenHierarchy\fP does not take a \fBdisplay\fP argument. .IP "\fBnum_files\fP" Specifies the number of files in the name list. .IP "\fBfile_names_list\fP" Specifies an array of character strings that identify the UID files. .IP "\fBancillary_structures_list\fP" A list of operating-system-dependent ancillary structures corresponding to such things as filenames, clobber flag, and so forth. This argument should be NULL for most operations. If you need to reference this structure, see the definition of \fIMrmOsOpenParamPtr\fP in \fIMrmPublic.h\fP for more information. .IP "\fBhierarchy_id\fP" Returns the search hierarchy ID. The search hierarchy ID identifies the list of UID files that MRM searches (in order) when performing subsequent fetch calls. .PP Each UID file string in \fBfile_names_list\fP can specify either a full pathname or a filename. If a UID file string has a leading slash (/), it specifies a full pathname, and MRM opens the file as specified. Otherwise, the UID file string specifies a filename. In this case MRM looks for the file along a search path specified by the \fIUIDPATH\fP environment variable or by a default search path, which varies depending on whether or not the \fIXAPPLRESDIR\fP environment variable is set. .PP The \fIUIDPATH\fP environment variable specifies a search path and naming conventions associated with UID files. It can contain the substitution field %U, where the UID file string from the \fBfile_names_list\fP argument to \fIMrmOpenHierarchyPerDisplay\fP is substituted for %U. It can also contain the substitution fields accepted by \fIXtResolvePathname\fP. The substitution field %T is always mapped to \fIuid\fP. The entire path is first searched with %S mapped to \fI\&.uid\fP and then, if no file is found, is searched again with %S mapped to NULL. .P If no display is set prior to calling this function, the result of this function's call to \fIXtResolvePathname\fP is undefined. .P For example, the following \fIUIDPATH\fP value and \fIMrmOpenHierarchy\fP call cause MRM to open two separate UID files: .oS UIDPATH=/uidlib/%L/%U.uid:/uidlib/%U/%L static char *uid_files[] = {"/usr/users/me/test.uid", "test2"}; MrmHierarchy *Hierarchy_id; MrmOpenHierarchy((MrmCount)2,uid_files, NULL, Hierarchy_id) .oE .PP MRM opens the first file, \fI/usr/users/me/test.uid\fP, as specified in the \fBfile_names_list\fP argument to \fIMrmOpenHierarchy\fP, because the UID file string in the \fBfile_names_list\fP argument specifies a full pathname. MRM looks for the second file, .ne 6 \fItest2\fP, first as \fI/uidlib/%L/test2.uid\fP and second as \fI/uidlib/test2/%L\fP, where the display's language string is substituted for %L. .PP After \fIMrmOpenHierarchy\fP opens the UID hierarchy, you should not delete or modify the UID files until you close the UID hierarchy by calling \fIMrmCloseHierarchy\fP. .PP If \fIUIDPATH\fP is not set but the environment variable \fIXAPPLRESDIR\fP is set, MRM searches the following pathnames: .iS .ta 1i .nf 22:59:55S $XAPPLRESDIR/%L/uid/%N/22:59:55S $XAPPLRESDIR/%l/uid/%N/22:59:55S $XAPPLRESDIR/uid/%N/22:59:55S $XAPPLRESDIR/%L/uid/22:59:55S $XAPPLRESDIR/%l/uid/22:59:55S $XAPPLRESDIR/uid/22:59:55S $HOME/uid/22:59:55S $HOME/22:59:55S /usr/lib/X11/%L/uid/%N/22:59:55S /usr/lib/X11/%l/uid/%N/22:59:55S /usr/lib/X11/uid/%N/22:59:55S /usr/lib/X11/%L/uid/22:59:55S /usr/lib/X11/%l/uid/22:59:55S /usr/lib/X11/uid/22:59:55S /usr/include/X11/uid/22:59:55S .wH .fi .iE .PP If neither \fIUIDPATH\fP nor \fIXAPPLRESDIR\fP is set, MRM searches the following pathnames: .iS .ta 1i .nf 22:59:55S $HOME/%L/uid/%N/22:59:55S $HOME/%l/uid/%N/22:59:55S $HOME/uid/%N/22:59:55S $HOME/%L/uid/22:59:55S $HOME/%l/uid/22:59:55S $HOME/uid/22:59:55S $HOME/22:59:55S /usr/lib/X11/%L/uid/%N/22:59:55S /usr/lib/X11/%l/uid/%N/22:59:55S /usr/lib/X11/uid/%N/22:59:55S /usr/lib/X11/%L/uid/22:59:55S /usr/lib/X11/%l/uid/22:59:55S /usr/lib/X11/uid/22:59:55S /usr/include/X11/uid/22:59:55S .wH .fi .iE .PP These paths are defaults that vendors may change. For example, a vendor may use different directories for \fI/usr/lib/X11\fP and \fI/usr/include/X11\fP. .PP The following substitutions are used in these paths: .IP "\fI%U\fP" The UID file string, from the \fBfile_names_list\fP argument. .IP "\fI%N\fP" The class name of the application. .IP "\fI%L\fP" The display's language string. .IP "\fI%l\fP" The language component of the display's language string. .IP "\fI%S\fP" The suffix to the file name. The entire path is searched first with a suffix of \fI\&.uil\fP, and if no file is found, it is searched again with a NULL suffix. .nL .ne 10 .SH RETURN VALUE This function returns one of these status return constants: .IP "\fIMrmSUCCESS\fP" The function executed successfully. .IP "\fIMrmNOT_FOUND\fP" File not found. .IP "\fIMrmFAILURE\fP" The function failed. .SH RELATED INFORMATION .na \fIMrmOpenHierarchyPerDisplay(3X)\fP and \fIMrmCloseHierarchy(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH MrmOpenHierarchyPerDisplay 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIMrmOpenHierarchyPerDisplay\fP \- Allocates a hierarchy ID and opens all the UID files in the hierarchy .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf Cardinal MrmOpenHierarchyPerDisplay (\fBdisplay, num_files, file_names_list, ancillary_structures_list, hierarchy_id\fI) .ta .5i 2.25i .nf Display *\fBdisplay\fI; MrmCount \fBnum_files\fI; String \fBfile_names_list\fI[]; MrmOsOpenParamPtr *\fBancillary_structures_list\fI; MrmHierarchy *\fBhierarchy_id\fI; .iE .sE .SH DESCRIPTION .fi \fIMrmOpenHierarchyPerDisplay\fP allows you to specify the list of UID files that MRM searches in subsequent fetch operations. All subsequent fetch operations return the first occurrence of the named item encountered while traversing the UID hierarchy from the first list element (UID file specification) to the last list element. This function also allocates a hierarchy ID and opens all the UID files in the hierarchy. It initializes the optimized search lists in the hierarchy. If \fIMrmOpenHierarchyPerDisplay\fP encounters any errors during its execution, any files that were opened are closed. .PP The application must call \fIXtAppInitialize\fP before calling \fIMrmOpenHierarchyPerDisplay\fP. .IP "\fBdisplay\fP" Specifies the connection to the X server and the value to pass to \fIXtResolvePathname\fP. For more information on the Display structure, see the Xlib function \fIXOpenDisplay\fP. .IP "\fBnum_files\fP" Specifies the number of files in the name list. .IP "\fBfile_names_list\fP" Specifies an array of character strings that identify the UID files. .IP "\fBancillary_structures_list\fP" A list of operating-system-dependent ancillary structures corresponding to such things as filenames, clobber flag, and so forth. This argument should be NULL for most operations. If you need to reference this structure, see the definition of \fIMrmOsOpenParamPtr\fP in \fIMrmPublic.h\fP for more information. .IP "\fBhierarchy_id\fP" Returns the search hierarchy ID. The search hierarchy ID identifies the list of UID files that MRM searches (in order) when performing subsequent fetch calls. .PP Each UID file string in \fBfile_names_list\fP can specify either a full pathname or a filename. If a UID file string has a leading slash (/), it specifies a full pathname, and MRM opens the file as specified. Otherwise, the UID file string specifies a filename. In this case MRM looks for the file along a search path specified by the \fIUIDPATH\fP environment variable or by a default search path, which varies depending on whether or not the \fIXAPPLRESDIR\fP environment variable is set. .PP The \fIUIDPATH\fP environment variable specifies a search path and naming conventions associated with UID files. It can contain the substitution field %U, where the UID file string from the \fBfile_names_list\fP argument to \fIMrmOpenHierarchyPerDisplay\fP is substituted for %U. It can also contain the substitution fields accepted by \fIXtResolvePathname\fP. The substitution field %T is always mapped to \fIuid\fP. The entire path is first searched with %S mapped to \fI\&.uid\fP and then, if no file is found, is searched again with %S mapped to NULL. For example, the following \fIUIDPATH\fP value and \fIMrmOpenHierarchyPerDisplay\fP call cause MRM to open two separate UID files: .oS UIDPATH=/uidlib/%L/%U.uid:/uidlib/%U/%L static char *uid_files[] = {"/usr/users/me/test.uid", "test2"}; MrmHierarchy *Hierarchy_id; MrmOpenHierarchyPerDisplay((MrmCount)2,uid_files, NULL, Hierarchy_id) .oE .PP MRM opens the first file, \fI/usr/users/me/test.uid\fP, as specified in the \fBfile_names_list\fP argument to \fIMrmOpenHierarchyPerDisplay\fP, because the UID file string in the \fBfile_names_list\fP argument specifies a full pathname. MRM looks for the second file, .ne 6 \fItest2\fP, first as \fI/uidlib/%L/test2.uid\fP and second as \fI/uidlib/test2/%L\fP, where the display's language string is substituted for %L. .PP After \fIMrmOpenHierarchyPerDisplay\fP opens the UID hierarchy, you should not delete or modify the UID files until you close the UID hierarchy by calling \fIMrmCloseHierarchy\fP. .PP If \fIUIDPATH\fP is not set but the environment variable \fIXAPPLRESDIR\fP is set, MRM searches the following pathnames: .iS .ta 1i .nf 23:00:06S $XAPPLRESDIR/%L/uid/%N/23:00:06S $XAPPLRESDIR/%l/uid/%N/23:00:06S $XAPPLRESDIR/uid/%N/23:00:06S $XAPPLRESDIR/%L/uid/23:00:06S $XAPPLRESDIR/%l/uid/23:00:06S $XAPPLRESDIR/uid/23:00:06S $HOME/uid/23:00:06S $HOME/23:00:06S /usr/lib/X11/%L/uid/%N/23:00:06S /usr/lib/X11/%l/uid/%N/23:00:06S /usr/lib/X11/uid/%N/23:00:06S /usr/lib/X11/%L/uid/23:00:06S /usr/lib/X11/%l/uid/23:00:06S /usr/lib/X11/uid/23:00:06S /usr/include/X11/uid/23:00:06S .wH .fi .iE .PP If neither \fIUIDPATH\fP nor \fIXAPPLRESDIR\fP is set, MRM searches the following pathnames: .iS .ta 1i .nf 23:00:06S $HOME/%L/uid/%N/23:00:06S $HOME/%l/uid/%N/23:00:06S $HOME/uid/%N/23:00:06S $HOME/%L/uid/23:00:06S $HOME/%l/uid/23:00:06S $HOME/uid/23:00:06S $HOME/23:00:06S /usr/lib/X11/%L/uid/%N/23:00:06S /usr/lib/X11/%l/uid/%N/23:00:06S /usr/lib/X11/uid/%N/23:00:06S /usr/lib/X11/%L/uid/23:00:06S /usr/lib/X11/%l/uid/23:00:06S /usr/lib/X11/uid/23:00:06S /usr/include/X11/uid/23:00:06S .wH .fi .iE .PP These paths are defaults that vendors may change. For example, a vendor may use different directories for \fI/usr/lib/X11\fP and \fI/usr/include/X11\fP. .PP The following substitutions are used in these paths: .IP "\fI%U\fP" The UID file string, from the \fBfile_names_list\fP argument. .IP "\fI%N\fP" The class name of the application. .IP "\fI%L\fP" The display's language string. .IP "\fI%l\fP" The language component of the display's language string. .IP "\fI%S\fP" The suffix to the file name. The entire path is searched first with a suffix of \fI\&.uil\fP, and if no file is found, it is searched again with a NULL suffix. .nL .ne 10 .SH RETURN VALUE This function returns one of these status return constants: .IP "\fIMrmSUCCESS\fP" The function executed successfully. .IP "\fIMrmNOT_FOUND\fP" File not found. .IP "\fIMrmFAILURE\fP" The function failed. .SH RELATED INFORMATION .na \fIMrmCloseHierarchy(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH MrmRegisterClass 3X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIMrmRegisterClass\fP \- Saves the information needed for MRM to access the widget creation function for user-defined widgets .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Cardinal MrmRegisterClass(\fBclass_code, class_name, create_name, create_proc, class_record\fI) .ta .5i 1.5i .nf MrmType \fBclass_code\fI; String \fBclass_name\fI; String \fBcreate_name\fI; Widget (*\fBcreate_proc\fI) (); WidgetClass \fBclass_record\fI; .iE .sE .SH DESCRIPTION .fi The \fIMrmRegisterClass\fP function allows MRM to access user-defined widget classes. This function registers the necessary information for MRM to create widgets of this class. You must call \fIMrmRegisterClass\fP prior to fetching any user-defined class widget. .PP \fIMrmRegisterClass\fP saves the information needed to access the widget creation function and to do type conversion of argument lists by using the information in MRM databases. .IP "\fBclass_code\fP" This argument is ignored; it is present for compatibility with previous releases. .IP "\fBclass_name\fP" This argument is ignored; it is present for compatibility with previous releases. .IP "\fBcreate_name\fP" Specifies the case-sensitive name of the low-level widget creation function for the class. An example from the Motif Toolkit is \fIXmCreateLabel\fP. Arguments are \fBparent_widget\fP, \fBname\fP, \fBoverride_arglist\fP, and \fBoverride_argcount\fP. .PP For user-defined widgets, \fBcreate_name\fP is the creation procedure in the UIL that defines this widget. .IP "\fBcreate_proc\fP" Specifies the address of the creation function that you named in \fBcreate_name\fP. .IP "\fBclass_record\fP" Specifies a pointer to the class record. .SH RETURN VALUE This function returns one of these status return constants: .IP "\fIMrmSUCCESS\fP" The function executed successfully. .IP "\fIMrmFAILURE\fP" The function failed. ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH MrmRegisterNames 3X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIMrmRegisterNames\fP \- Registers the values associated with the names referenced in UIL (for example, UIL callback function names or UIL identifier names) .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Cardinal MrmRegisterNames(\fBregister_list, register_count\fI) .ta .5i 2.5i .nf MrmRegisterArglist \fBregister_list\fI; MrmCount \fBregister_count\fI; .iE .sE .SH DESCRIPTION .fi The \fIMrmRegisterNames\fP function registers a vector of names and associated values for access in MRM. The values can be callback functions, pointers to user-defined data, or any other values. The information provided is used to resolve symbolic references occurring in UID files to their run-time values. For callbacks, this information provides the procedure address required by the Motif Toolkit. For names used as identifiers in UIL, this information provides any run-time mapping the application needs. .PP This function is similar to \fIMrmRegisterNamesInHierarchy\fP, except that the scope of the names registered by \fIMrmRegisterNamesInHierarchy\fP is limited to the hierarchy specified in the call to that function, whereas the names registered by \fIMrmRegisterNames\fP have global scope. When MRM looks up a name, it first tries to find the name among those registered for the given hierarchy. If that lookup fails, it tries to find the name among those registered globally. .IP "\fBregister_list\fP" Specifies a list of name/value pairs for the names to be registered. Each name is a case-sensitive, NULL-terminated ASCII string. Each value is a 32-bit quantity, interpreted as a procedure address if the name is a callback function, and uninterpreted otherwise. .IP "\fBregister_count\fP" Specifies the number of entries in \fBregister_list\fP. .PP The names in the list are case-sensitive. The list can be either ordered or unordered. .PP Callback functions registered through \fIMrmRegisterNames\fP can be either regular or creation callbacks. Regular callbacks have declarations determined by Motif Toolkit and user requirements. Creation callbacks have the same format as any other callback: .sS .iS void CallBackProc(\fBwidget_id, tag, callback_data\fI) .ta .5i 2.5i .nf Widget *\fBwidget_id\fI; Opaque \fBtag\fI XmAnyCallbackStruct *\fBcallback_data\fI; .iE .sE .IP "\fBwidget_id\fP" Specifies the widget ID associated with the widget performing the callback (as in any callback function). .IP "\fBtag\fP" Specifies the tag value (as in any callback function). .IP "\fBcallback_data\fP" Specifies a widget-specific data structure. This data structure has a minimum of two members: event and reason. The reason member is always set to \fIMrmCR_CREATE\fP. .PP Note that the widget name and parent are available from the widget record accessible through \fBwidget_id\fP. .ne 8 .SH RETURN VALUE This function returns one of these status return constants: .IP "\fIMrmSUCCESS\fP" The function executed successfully. .IP "\fIMrmFAILURE\fP" The function failed. ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH MrmRegisterNamesInHierarchy 3X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIMrmRegisterNamesInHierarchy\fP \- Registers the values associated with the names referenced in UIL within a single hierarchy (for example, UIL callback function names or UIL identifier names) .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Cardinal MrmRegisterNamesInHierarchy(\fBhierarchy_id, register_list, register_count\fI) .ta .5i 2.5i .nf MrmHierarchy \fBhierarchy_id\fI; MrmRegisterArglist \fBregister_list\fI; MrmCount \fBregister_count\fI; .iE .sE .SH DESCRIPTION .fi The \fIMrmRegisterNamesInHierarchy\fP function registers a vector of names and associated values for access in MRM. The values can be callback functions, pointers to user-defined data, or any other values. The information provided is used to resolve symbolic references occurring in UID files to their run-time values.For callbacks, this information provides the procedure address required by the Motif Toolkit. For names used as identifiers in UIL, this information provides any run-time mapping the application needs. .PP This function is similar to \fIMrmRegisterNames\fP, except that the scope of the names registered by \fIMrmRegisterNamesInHierarchy\fP is limited to the hierarchy specified by \fBhierarchy_id\fP, whereas the names registered by \fIMrmRegisterNames\fP have .ne 8 global scope. When MRM looks up a name, it first tries to find the name among those registered for the given hierarchy. If that lookup fails, it tries to find the name among those registered globally. .IP "\fBhierarchy_id\fP" Specifies the hierarchy with which the names are to be associated. .IP "\fBregister_list\fP" Specifies a list of name/value pairs for the names to be registered. Each name is a case-sensitive, NULL-terminated ASCII string. Each value is a 32-bit quantity, interpreted as a procedure address if the name is a callback function, and uninterpreted otherwise. .IP "\fBregister_count\fP" Specifies the number of entries in \fBregister_list\fP. .PP The names in the list are case-sensitive. The list can be either ordered or unordered. .PP Callback functions registered through \fIMrmRegisterNamesInHierarchy\fP can be either regular or creation callbacks. Regular callbacks have declarations determined by Motif Toolkit and user requirements. Creation callbacks have the same format as any other callback: .sS .iS void CallBackProc(\fBwidget_id, tag, callback_data\fI) .ta .5i 2.5i .nf Widget *\fBwidget_id\fI; Opaque \fBtag\fI; XmAnyCallbackStruct *\fBcallback_data\fI; .iE .sE .IP "\fBwidget_id\fP" Specifies the widget ID associated with the widget performing the callback (as in any callback function). .IP "\fBtag\fP" Specifies the tag value (as in any callback function). .IP "\fBcallback_data\fP" Specifies a widget-specific data structure. This data structure has a minimum of two members: event and reason. The reason member is always set to \fIMrmCR_CREATE\fP. .PP Note that the widget name and parent are available from the widget record accessible through \fBwidget_id\fP. .SH RETURN VALUE This function returns one of these status return constants: .IP "\fIMrmSUCCESS\fP" The function executed successfully. .IP "\fIMrmFAILURE\fP" The function failed. ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH Object 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIObject\fP \- The Object widget class .SH SYNOPSIS .nf .sS .iS \&#include .wH .fP .iE .sE .SH DESCRIPTION .fi Object is never instantiated. Its sole purpose is as a supporting superclass for other widget classes. .SS "Classes" The class pointer is \fIobjectClass\fP. .PP The class name is \fIObject\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Object Resource Set Name Class Type Default Access _ XmNdestroyCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .IP "\fIXmNdestroyCallback\fP" Specifies a list of callbacks that is called when the gadget is destroyed. .SS "Translations" There are no translation for Object. .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "Object" "Intrinsics Classes" .XX "Object" .XX "widget class, Object" .SH "Name" .Na Object widget class \- fundamental object class. .Nz .\" .SH "Synopsis" .IP "\s-1\f(HBPublic Headers:\fP\s0" 18n 0 \fI\fP .br \fI\fP .IP "\s-1\f(HBPrivate Header:\fP\s0" 18n 0 \fI\fP .IP "\s-1\f(HBClass\ Name:\fP\s0" 18n 0 Object .IP "\s-1\f(HBClass\ Hierarchy:\fP\s0" 18n 0 'nh Object .IP "\s-1\f(HBClass Pointer:\fP\s0" 18n 0 \f(CWobjectClass\fP .IP "\s-1\f(HBInstantiation:\fP\s0" 18n 0 Object is an Intrinsics meta-class, and is not normally instantiated. .IP "\s-1\f(HBFunctions/Macros:\fP\s0" 18n 0 \f(CWXtIsObject(\^)\fP .\" .\" .SH "Availability" Release 4 and later. .\" .SH "Description" Object is the root of the class hierarchy; it does not have a superclass. All objects and widgets are subclasses of Object. Object encapsulates the mechanisms for resource management and is never instantiated. .LP Prior to Release 4, Core was the root of the class hierarchy. The Object class was made public in Release 4 to enable programmers to use the Intrinsics classing and resource handling mechanisms for things besides widgets. Objects make many common uses of subresources obsolete. See the "Background" section below for more information on using non-widget objects. .\" .SH "New Resources" Object defines the following resources: .br .sp 1 .in 0 .KS .TS expand linesize(2) tab(@); l l l l l lp7 lp7 lp7 lp7 lp7. \fRName@Class@Type@Default@Access\fP .sp .2 .XX "XtNdestroyCallback:and Object" \f(CWXtNdestroyCallback\fP@\f(CWXtCCallback\fP@\f(CWXtCallbackList\fP@\f(CWNULL\fP@\f(CWC\fP .sp .2 .TE .KE .in .sp 1 .IP "\f(CWXtNdestroyCallback\fP" 5n List of callbacks invoked when the Object is destroyed. .\" .SH "Class Structure" The Object class structure is shown below. Because the Object class was defined after Core was already standardized, the fields of these two class structures must match. Therefore, the fields named \f(CWobj\fIn\fR below exist only to pad out the structure. The use of each of the remaining fields is exactly as for the Core class. .XX "objects, ObjectClassRec" .XX "objects, ObjectClass" .Ps typedef struct _ObjectClassPart { WidgetClass superclass; String class_name; Cardinal widget_size; XtProc class_initialize; XtWidgetClassProc class_part_initialize; XtEnum class_inited; XtInitProc initialize; XtArgsProc initialize_hook; XtProc obj1; XtPointer obj2; Cardinal obj3; XtResourceList resources; Cardinal num_resources; XrmClass xrm_class; Boolean obj4; XtEnum obj5; Boolean obj6; Boolean obj7; XtWidgetProc destroy; XtProc obj8; XtProc obj9; XtSetValuesFunc set_values; XtArgsFunc set_values_hook; XtProc obj10; XtArgsProc get_values_hook; XtProc obj11; XtVersionType version; XtPointer callback_private; String obj12; XtProc obj13; XtProc obj14; XtPointer extension; } ObjectClassPart; typedef struct _ObjectClassRec { ObjectClassPart object_class; } ObjectClassRec, *ObjectClass; .Pe There is no extension defined for the Object class, and the \f(CWextension\fP field should be \f(CWNULL\fP. .\" .SH "Instance Structure" The Object instance structure contains at least the fields shown below. The fields need not be in the order shown, but because the Object class was defined after Core was standardized, the position of each of these fields must be the same for both classes. .XX "objects, ObjectPart" .XX "objects, ObjectRec" .Ps typedef struct _ObjectPart { Widget self; WidgetClass widget_class; Widget parent; XrmName xrm_name; Boolean being_destroyed; XtCallbackList destroy_callbacks; XtPointer constraints; } ObjectPart; typedef struct _ObjectRec { ObjectPart object; } ObjectRec, *Object; .Pe .\" .SH "Background" Composite widget classes that wish to accept non-widget children must set the \f(CWaccepts_objects\fP field in the \f(CWCompositeClassExtension\fP structure to \f(CWTrue\fP. \f(CWXtCreateWidget()\fP will otherwise generate an error message on an attempt to create a non-widget child. .LP Of the classes defined by the Intrinsics, only ApplicationShell accepts non-widget children, and the class of any non-widget child must not be \f(CWrectObjClass\fP or any subclass. The intent of allowing Object children of ApplicationShell is to provide clients a simple mechanism for establishing the resource naming root of an object hierarchy. .LP Starting in Release 4, the WidgetClass arguments to the following procedures may be \f(CWobjectClass\fP or any subclass: .IP \(bu \f(CWXtInitializeWidgetClass()\fP, \f(CWXtCreateWidget()\fP, \f(CWXtVaCreateWidget()\fP .IP \(bu \f(CWXtIsSubclass()\fP, \f(CWXtCheckSubclass()\fP .IP \(bu \f(CWXtGetResourceList()\fP, \f(CWXtGetConstraintResourceList()\fP .sp .LP The Widget arguments to the following procedures may be of class Object or any subclass: .IP \(bu \f(CWXtCreateWidget()\fP, \f(CWXtVaCreateWidget()\fP .IP \(bu \f(CWXtAddCallback()\fP, \f(CWXtAddCallbacks()\fP, \f(CWXtRemoveCallback()\fP, \f(CWXtRemoveCall\%backs\fP, \f(CWXtRemoveAllCallbacks()\fP, \f(CWXtCallCallbacks()\fP, \f(CWXtHasCallbacks()\fP, \f(CWXtCallCallbackList()\fP .IP \(bu \f(CWXtClass()\fP, \f(CWXtSuperclass()\fP, \f(CWXtIsSubclass()\fP, \f(CWXtCheckSubclass()\fP, \f(CWXtIsObject()\fP, \f(CWXtIsRectObj()\fP, \f(CWXtIsWidget()\fP, \f(CWXtIsComposite()\fP, \f(CWXtIsConstraint()\fP, \f(CWXtIsShell()\fP, \f(CWXtIsOverrideShell()\fP, \f(CWXtIsWMShell()\fP, \f(CWXtIsVendorShell()\fP, \f(CWXtIsTransientShell()\fP, \f(CWXtIsToplevelShell\fP, \f(CWXtIsApplicationShell()\fP. .IP \(bu \f(CWXtIsManaged()\fP, \f(CWXtIsSensitive()\fP .br (both will return \f(CWFalse\fP if argument is not a subclass of \f(CWRectObj\fP) .IP \(bu \f(CWXtIsRealized()\fP .br (returns the state of the nearest windowed ancestor if argument is not of a subclass of \f(CWCore\fP) .IP \(bu \f(CWXtWidgetToApplicationContext()\fP .IP \(bu \f(CWXtDestroyWidget()\fP .IP \(bu \f(CWXtDisplayOfObject()\fP, \f(CWXtScreenOfObject()\fP, \f(CWXtWindowOfObject()\fP .IP \(bu \f(CWXtSetKeyboardFocus()\fP (descendant) .IP \(bu \f(CWXtGetGC()\fP, \f(CWXtReleaseGC()\fP .IP \(bu \f(CWXtName()\fP .IP \(bu \f(CWXtSetValues()\fP, \f(CWXtGetValues()\fP, \f(CWXtVaSetValues()\fP, \f(CWXtVaGetValues()\fP, .IP \(bu \f(CWXtGetSubresources()\fP, \f(CWXtGetApplicationResources()\fP, \f(CWXtVaGetSub\%resources\fP, \f(CWXtVaGetApplicationResources()\fP .IP \(bu \f(CWXtConvert()\fP, \f(CWXtConvertAndStore()\fP .sp .LP The return value of the following procedures will be of class Object or a subclass: .IP \(bu \f(CWXtCreateWidget()\fP, \f(CWXtVaCreateWidget()\fP .IP \(bu \f(CWXtParent()\fP .IP \(bu \f(CWXtNameToWidget()\fP .sp .LP The return value of the following procedures will be \f(CWobjectClass\fP or a subclass: .IP \(bu \f(CWXtClass()\fP, \f(CWXtSuperclass()\fP .\" .SH "See Also" \s-1\fICore\fR\s+1\*(s3. .\"last line comment ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH OverrideShell 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIOverrideShell\fP \- The OverrideShell widget class .SH SYNOPSIS .nf .sS .iS \&#include \&#include .iE .sE .SH DESCRIPTION .fi OverrideShell is used for shell windows that completely bypass the window manager, for example, PopupMenu shells. .SS "Classes" OverrideShell inherits behavior and resources from \fICore\fP, \fIComposite\fP, and \fIShell\fP. .PP The class pointer is \fIoverrideShellWidgetClass\fP. .PP The class name is \fIOverrideShell\fP. .SS "New Resources" OverrideShell defines no new resources, but overrides the \fIXmNoverrideRedirect\fP and \fIXmNsaveUnder\fP resources in the \fIShell\fP class. .SS "Inherited Resources" OverrideShell inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .PP The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Shell Resource Set Name Class Type Default Access _ XmNallowShellResize XmCAllowShellResize Boolean False CG XmNcreatePopupChildProc XmCCreatePopupChildProc XtCreatePopupChildProc NULL CSG XmNgeometry XmCGeometry String NULL CSG XmNoverrideRedirect XmCOverrideRedirect Boolean True CSG XmNpopdownCallback XmCCallback XtCallbackList NULL C XmNpopupCallback XmCCallback XtCallbackList NULL C XmNsaveUnder XmCSaveUnder Boolean True CSG XmNvisual XmCVisual Visual * CopyFromParent CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 1 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Translations" There are no translations for OverrideShell. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fICore(3X)\fP, and \fIShell(3X)\fP. .ad .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "OverrideShell" "Intrinsics Classes" .XX "OverrideShell" .SH "Name" .Na OverrideShell widget class \- popup shell that bypasses window management. .Nz .\" .SH "Synopsis" .IP "\s-1\f(HBPublic Headers:\fP\s0" 18n 0 \fI\fP .br \fI\fP .IP "\s-1\f(HBPrivate Header:\fP\s0" 18n 0 \fI\fP .IP "\s-1\f(HBClass\ Name:\fP\s0" 18n 0 OverrideShell .IP "\s-1\f(HBClass\ Hierarchy:\fP\s0" 18n 0 'nh Core \(-> Composite \(-> Shell \(-> OverrideShell .IP "\s-1\f(HBClass Pointer:\fP\s0" 18n 0 \f(CWoverrideShellWidgetClass\fP .IP "\s-1\f(HBInstantiation:\fP\s0" 18n 0 .ft CW .ps 9 \f(CIwidget\fP = XtCreatePopupShell(\f(CIname\fP, .br overrideShellWidgetClass, ...) .br .ps 10 .ft R .IP "\s-1\f(HBFunctions/Macros:\fP\s0" 18n 0 \f(CWXtIsOverrideShell(\^)\fP .\" .SH "Description" OverrideShell is a direct subclass of Shell that performs no interaction with window managers. It is used for widgets (such as popup menus) that should bypass the window manager. .\" .SH "New Resources" OverrideShell defines no new resources, but it redefines the default values of both \f(CWXtNoverrideRedirect\fP and \f(CWXtNsaveUnder\fP to \f(CWTrue\fP. .\" .SH "Inherited Resources" OverrideShell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. .sp 1 .in 0 .KS .TS H tab(@), linesize(2); lp7 lp7 lp7 lp7 lp6w(1.25i) lp6w(1i) lp6w(1.25i) lp6w(1i). \fRResource@Inherited From@Resource@Inherited From\fP .sp 2p .Th \f(CWXtNaccelerators\fP@\f(CWCore\fP@\f(CWXtNinitialResources-\fP@\f(CWCore\fP .sp -2p @@\0\0\f(CWPersistent\fP \f(CWXtNallowShellResize\fP@\f(CWShell\fP@\f(CWXtNinsertPosition\fP@\f(CWComposite\fP \f(CWXtNancestorSensitive\fP@\f(CWCore\fP@\f(CWXtNmappedWhenManaged\fP@\f(CWCore\fP \f(CWXtNbackground\fP@\f(CWCore\fP@\f(CWXtNnumChildren\fP@\f(CWComposite\fP \f(CWXtNbackgroundPixmap\fP@\f(CWCore\fP@\f(CWXtNoverrideRedirect\fP@\f(CWShell\fP \f(CWXtNborderColor\fP@\f(CWCore\fP@\f(CWXtNpopdownCallback\fP@\f(CWShell\fP \f(CWXtNborderPixmap\fP@\f(CWCore\fP@\f(CWXtNpopupCallback\fP@\f(CWShell\fP \f(CWXtNborderWidth\fP@\f(CWCore\fP@\f(CWXtNsaveUnder\fP@\f(CWShell\fP \f(CWXtNchildren\fP@\f(CWComposite\fP@\f(CWXtNscreen\fP@\f(CWCore\fP \f(CWXtNcolormap\fP@\f(CWCore\fP@\f(CWXtNsensitive\fP@\f(CWCore\fP \f(CWXtNcreatePopupChild-\fP@\f(CWShell\fP@\f(CWXtNtranslations\fP@\f(CWCore\fP .sp -2p \0\0\f(CWProc\fP \f(CWXtNdepth\fP@\f(CWCore\fP@\f(CWXtNvisual\fP@\f(CWShell\fP .Nd 5 \f(CWXtNdestroyCallback\fP@\f(CWCore\fP@\f(CWXtNwidth\fP@\f(CWCore\fP \f(CWXtNgeometry\fP@\f(CWShell\fP@\f(CWXtNx\fP@\f(CWCore\fP \f(CWXtNheight\fP@\f(CWCore\fP@\f(CWXtNy\fP@\f(CWCore\fP .sp 2p .TE .KE .in .sp 1 .\" .SH "Class Structure" The OverrideShell class structure contains only an extension field. Its declaration is similar to those of the other shells: .Ps .ta 5n 2.5i typedef struct { XtPointer extension; /* pointer to extension record */ } OverrideShellClassPart; typedef struct _OverrideShellClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ShellClassPart shell_class; OverrideShellClassPart override_shell_class; } OverrideShellClassRec; .Pe There are no extensions currently defined for this class, and the \f(CWextension\fP field should be \f(CWNULL\fP. .\" .SH "Instance Structure" The OverrideShell instance structure contains no new fields: .Ps typedef struct { int empty; } OverrideShellPart; typedef struct { CorePart core; CompositePart composite; ShellPart shell; OverrideShellPart override; } OverrideShellRec, *OverrideShellWidget; .Pe .\" .SH "See Also" \s-1\fIShell\fR\s+1\*(s3. .\"last line comment .\" $Header: regexp.3x,v 72.5 94/11/15 09:56:02 ssa Exp $ .TA r .TH regexp 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compile(\|), step(\|), advance(\|) \- regular expression compile and match routines .SH SYNOPSIS .C #define INIT .I "declarations" .br .C #define GETC() .I "getc statements" .br .C #define PEEKC() .I "peekc statements" .br .C #define UNGETC(c) .I "ungetc statements" .br .C #define RETURN(pointer) .I "return statements" .br .C #define ERROR(val) .I "error statements" .PP .C "#include " .PP .C "char *compile(" .nf .PD 0 .IP .C "const char *instring," .C "char *expbuf," .C "const char *endbuf," .C "int eof" .PP .C ");" .PD .fi .PP .C "int step(const char *string, const char *expbuf);" .PP .C "int advance(const char *string, const char *expbuf);" .PP .C "extern char *loc1, *loc2, *locs;" .PP .C "extern int circf, sed, nbra;" .SS Remarks Features documented in this manual entry are obsolescent and may be removed in a future .SM HP-UX release. Use of .IR regcomp (3C) functions instead is recommended. .SH DESCRIPTION These functions are general-purpose regular expression matching routines to be used in programs that perform Basic Regular Expression (see .IR regexp (5)) matching. These functions are defined in .RC < regexp.h >. .PP The functions .C step() and .C advance() do pattern matching given a character string and a compiled regular expression as input. .C compile() takes a Basic Regular Expression as input and produces a compiled expression that can be used with .C step() and .CR advance() . .PP The interface to this file is unpleasantly complex. Programs that include this file must have the following five macros declared before the .C #include statement. These macros are used by the .C compile() routine. .TP 15 .C GETC() Return the value of the next byte in the regular expression pattern. Successive calls to .C GETC() should return successive bytes of the regular expression. .TP .C PEEKC() Return the next byte in the regular expression. Successive calls to .C PEEKC() should return the same byte (which should also be the next byte returned by .CR GETC() . .TP .CI UNGETC( c ) Cause the argument .I c to be returned by the next call to .C GETC() (and .CR PEEKC() ). No more than one byte of pushback is ever needed, and this byte is guaranteed to be the last byte read by .CR GETC() . The value of the macro .CI UNGETC( c ) is always ignored. .TP .CI RETURN( pointer ) This macro is used on normal exit of the .C compile() routine. The value of the argument .I pointer is a pointer to the character after the last character of the compiled regular expression. This is useful to programs that must manage memory allocation. .TP .CI ERROR( val ) This is the abnormal return from the .C compile() routine. The argument .I val is an error number (see table below for meanings). This call should never return. .RS .RS .PD 0 .TP 8 .B Error .B Meaning .TP 11 Range endpoint too large. .TP 16 Bad number. .TP 25 ``\f3\e\f2digit\f1'' out of range. .TP 36 Illegal or missing delimiter. .TP 41 No remembered search string. .TP 42 .C \e( \e) imbalance. .TP 43 Too many .CR \e( . .TP 44 More than 2 numbers given in .CR \e{\0\e} . .TP 45 .C } expected after .CR \e . .TP 46 First number exceeds second in .CR \e{\0\e} . .TP 49 .C [ ] imbalance. .TP 50 Regular expression overflow. .RE .RE .PD .PP The syntax of the .C compile() routine is as follows: .IP .CI compile( instring , .CI expbuf , .CI endbuf , .CI eof ) .PP The first parameter .I instring is never used explicitly by the .C compile() routine, but is useful for programs that pass down different pointers to input characters. It is sometimes used in the .C INIT declaration (see below). Programs that call functions to input characters or have characters in an external array can pass down a value of .C ((char *) 0) for this parameter. .PP The next parameter .I expbuf is a character pointer. It points to the location where the compiled regular expression will be placed. .PP The parameter .I endbuf is one more than the highest address where the compiled regular expression can be placed. If the compiled expression cannot fit in .RI ( endbuf \|\(mi\| expbuf ) bytes, a call to .C ERROR(50) is made. .PP The parameter .I eof is the character which marks the end of the regular expression. For example, in .IR ed (1), this character is usually a .CR / . .PP Each program that includes this file must have a .C #define statement for .CR INIT . This definition is placed right after the declaration for the function .C compile() and the opening curly brace .CR { . It is used for dependent declarations and initializations. Most often it is used to set a register variable to point to the beginning of the regular expression so that this register variable can be used in the declarations for .CR GETC() , .CR PEEKC() , and .CR UNGETC() . Otherwise it can be used to declare external variables that might be used by .CR GETC() , .CR PEEKC() , and .CR UNGETC() . See the example below of the declarations taken from .IR grep (1). .PP .C step() also performs actual regular expression matching in this file. The call to .I step is as follows: .IP .CI step( string , .CI expbuf ) .PP The first parameter to .C step() is a pointer to a string of characters to be checked for a match. This string should be null-terminated. .PP The second parameter .I expbuf is the compiled regular expression that was obtained by a call to .CR compile() . .PP .C step() returns non-zero if the given string matches the regular expression, and zero if the expressions do not match. If there is a match, two external character pointers are set as a side effect to the call to .CR step() . The variable set in .C step() is .CR loc1 . This is a pointer to the first character that matched the regular expression. The variable .CR loc2 , which is set by the function .CR advance() , points to the character after the last character that matches the regular expression. Thus, if the regular expression matches the entire line, .C loc1 points to the first character of .I string and .C loc2 points to the null at the end of .IR string . .PP .C step() uses the external variable .CR circf() , which is set by .C compile() if the regular expression begins with .CR ^ . If this is set, .C step() tries to match the regular expression to the beginning of the string only. If more than one regular expression is to be compiled before the first is executed, the value of .I circf should be saved for each compiled expression and .I circf should be set to that saved value before each call to .CR step() . .PP .C advance() is called from .C step() with the same arguments as .CR step() . The purpose of .C step() is to step through the .I string argument and call .C advance() until .C advance() returns non-zero, which indicates a match, or until the end of .I string is reached. To constrain .I string to beginning-of-line in all cases, .C step() need not be called; simply call .CR advance() . .PP When .C advance() encounters a .C * or .C \e{\|\e} sequence in the regular expression, it advances its pointer to the string to be matched as far as possible and recursively calls itself, trying to match the rest of the string to the rest of the regular expression. As long as there is no match, .I advance backs up along the string until it finds a match or reaches the point in the string that initially matched the .C * or .CR \e{\|\e} . It is sometimes desirable to stop this backing up before the initial point in the string is reached. If the external character pointer .C locs is equal to the point in the string at sometime during the backing up process, .C advance() breaks out of the loop that backs up and returns zero. This is used by .IR ed (1) and .IR sed (1) for substitutions done globally (not just the first occurrence, but the whole line) so, for example, expressions such as .C s/y*//g do not loop forever. .PP The additional external variables .C sed and .C nbra are used for special purposes. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions. .PP The .C LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, and the characters matched by character class expressions in regular expressions. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following is an example of how the regular expression macros and calls look from .IR grep (1): .nf .IP .C "#define INIT register char *sp = instring;" .C "#define GETC() (*sp++)" .C "#define PEEKC() (*sp)" .C "#define UNGETC(c) (--sp)" .C "#define RETURN(c) return;" .C "#define ERROR(c) regerr()" .IP .C "#include " \h'.5i'.\|.\|. .C "(void) compile(*argv, expbuf, &expbuf[ESIZE], '\e0');" \h'.5i'.\|.\|. .C "if (step(linebuf, expbuf))" .C " succeed();" .fi .SH AUTHOR .CR regexp() was developed by OSF and HP. .SH SEE ALSO grep(1), regcomp(3C), setlocale(3C), regexp(5). .SH STANDARDS CONFORMANCE .CR advance() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR compile() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc1 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc2 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR locs ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR step() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4compile()\f1 \- regular expression compile routine@@@\f3regexp(3X)\f1 .\" index@\f4step()\f1 \- regular expression string comparison routine@@@\f3regexp(3X)\f1 .\" index@\f4advance()\f1 \- regular expression substring comparison routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1expression, regular, compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1compile and match routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1comparison routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1match routines for regular expressions@@@\f3regexp(3X)\f1 .\" .\" toc@\f3regexp(3X)\f1:\0\0\f4compile()\f1, \f4step()\f1, \f4advance()\f1@@@regular expression compile and match routines .\" toc@\f4compile()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4step()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4advance()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" .\" links@regexp.3x compile.3x .\" links@regexp.3x step.3x .\" links@regexp.3x advance.3x .\" links@regexp.3x INIT.3x .\" links@regexp.3x GETC.3x .\" links@regexp.3x PEEKC.3x .\" links@regexp.3x UNGETC.3x .\" links@regexp.3x RETURN.3x .\" links@regexp.3x ERROR.3x .\" .\" fileset_database@regexp.3x PROGRAMING-MAN .\" $Header: regexp.3x,v 72.5 94/11/15 09:56:02 ssa Exp $ .TA r .TH regexp 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compile(\|), step(\|), advance(\|) \- regular expression compile and match routines .SH SYNOPSIS .C #define INIT .I "declarations" .br .C #define GETC() .I "getc statements" .br .C #define PEEKC() .I "peekc statements" .br .C #define UNGETC(c) .I "ungetc statements" .br .C #define RETURN(pointer) .I "return statements" .br .C #define ERROR(val) .I "error statements" .PP .C "#include " .PP .C "char *compile(" .nf .PD 0 .IP .C "const char *instring," .C "char *expbuf," .C "const char *endbuf," .C "int eof" .PP .C ");" .PD .fi .PP .C "int step(const char *string, const char *expbuf);" .PP .C "int advance(const char *string, const char *expbuf);" .PP .C "extern char *loc1, *loc2, *locs;" .PP .C "extern int circf, sed, nbra;" .SS Remarks Features documented in this manual entry are obsolescent and may be removed in a future .SM HP-UX release. Use of .IR regcomp (3C) functions instead is recommended. .SH DESCRIPTION These functions are general-purpose regular expression matching routines to be used in programs that perform Basic Regular Expression (see .IR regexp (5)) matching. These functions are defined in .RC < regexp.h >. .PP The functions .C step() and .C advance() do pattern matching given a character string and a compiled regular expression as input. .C compile() takes a Basic Regular Expression as input and produces a compiled expression that can be used with .C step() and .CR advance() . .PP The interface to this file is unpleasantly complex. Programs that include this file must have the following five macros declared before the .C #include statement. These macros are used by the .C compile() routine. .TP 15 .C GETC() Return the value of the next byte in the regular expression pattern. Successive calls to .C GETC() should return successive bytes of the regular expression. .TP .C PEEKC() Return the next byte in the regular expression. Successive calls to .C PEEKC() should return the same byte (which should also be the next byte returned by .CR GETC() . .TP .CI UNGETC( c ) Cause the argument .I c to be returned by the next call to .C GETC() (and .CR PEEKC() ). No more than one byte of pushback is ever needed, and this byte is guaranteed to be the last byte read by .CR GETC() . The value of the macro .CI UNGETC( c ) is always ignored. .TP .CI RETURN( pointer ) This macro is used on normal exit of the .C compile() routine. The value of the argument .I pointer is a pointer to the character after the last character of the compiled regular expression. This is useful to programs that must manage memory allocation. .TP .CI ERROR( val ) This is the abnormal return from the .C compile() routine. The argument .I val is an error number (see table below for meanings). This call should never return. .RS .RS .PD 0 .TP 8 .B Error .B Meaning .TP 11 Range endpoint too large. .TP 16 Bad number. .TP 25 ``\f3\e\f2digit\f1'' out of range. .TP 36 Illegal or missing delimiter. .TP 41 No remembered search string. .TP 42 .C \e( \e) imbalance. .TP 43 Too many .CR \e( . .TP 44 More than 2 numbers given in .CR \e{\0\e} . .TP 45 .C } expected after .CR \e . .TP 46 First number exceeds second in .CR \e{\0\e} . .TP 49 .C [ ] imbalance. .TP 50 Regular expression overflow. .RE .RE .PD .PP The syntax of the .C compile() routine is as follows: .IP .CI compile( instring , .CI expbuf , .CI endbuf , .CI eof ) .PP The first parameter .I instring is never used explicitly by the .C compile() routine, but is useful for programs that pass down different pointers to input characters. It is sometimes used in the .C INIT declaration (see below). Programs that call functions to input characters or have characters in an external array can pass down a value of .C ((char *) 0) for this parameter. .PP The next parameter .I expbuf is a character pointer. It points to the location where the compiled regular expression will be placed. .PP The parameter .I endbuf is one more than the highest address where the compiled regular expression can be placed. If the compiled expression cannot fit in .RI ( endbuf \|\(mi\| expbuf ) bytes, a call to .C ERROR(50) is made. .PP The parameter .I eof is the character which marks the end of the regular expression. For example, in .IR ed (1), this character is usually a .CR / . .PP Each program that includes this file must have a .C #define statement for .CR INIT . This definition is placed right after the declaration for the function .C compile() and the opening curly brace .CR { . It is used for dependent declarations and initializations. Most often it is used to set a register variable to point to the beginning of the regular expression so that this register variable can be used in the declarations for .CR GETC() , .CR PEEKC() , and .CR UNGETC() . Otherwise it can be used to declare external variables that might be used by .CR GETC() , .CR PEEKC() , and .CR UNGETC() . See the example below of the declarations taken from .IR grep (1). .PP .C step() also performs actual regular expression matching in this file. The call to .I step is as follows: .IP .CI step( string , .CI expbuf ) .PP The first parameter to .C step() is a pointer to a string of characters to be checked for a match. This string should be null-terminated. .PP The second parameter .I expbuf is the compiled regular expression that was obtained by a call to .CR compile() . .PP .C step() returns non-zero if the given string matches the regular expression, and zero if the expressions do not match. If there is a match, two external character pointers are set as a side effect to the call to .CR step() . The variable set in .C step() is .CR loc1 . This is a pointer to the first character that matched the regular expression. The variable .CR loc2 , which is set by the function .CR advance() , points to the character after the last character that matches the regular expression. Thus, if the regular expression matches the entire line, .C loc1 points to the first character of .I string and .C loc2 points to the null at the end of .IR string . .PP .C step() uses the external variable .CR circf() , which is set by .C compile() if the regular expression begins with .CR ^ . If this is set, .C step() tries to match the regular expression to the beginning of the string only. If more than one regular expression is to be compiled before the first is executed, the value of .I circf should be saved for each compiled expression and .I circf should be set to that saved value before each call to .CR step() . .PP .C advance() is called from .C step() with the same arguments as .CR step() . The purpose of .C step() is to step through the .I string argument and call .C advance() until .C advance() returns non-zero, which indicates a match, or until the end of .I string is reached. To constrain .I string to beginning-of-line in all cases, .C step() need not be called; simply call .CR advance() . .PP When .C advance() encounters a .C * or .C \e{\|\e} sequence in the regular expression, it advances its pointer to the string to be matched as far as possible and recursively calls itself, trying to match the rest of the string to the rest of the regular expression. As long as there is no match, .I advance backs up along the string until it finds a match or reaches the point in the string that initially matched the .C * or .CR \e{\|\e} . It is sometimes desirable to stop this backing up before the initial point in the string is reached. If the external character pointer .C locs is equal to the point in the string at sometime during the backing up process, .C advance() breaks out of the loop that backs up and returns zero. This is used by .IR ed (1) and .IR sed (1) for substitutions done globally (not just the first occurrence, but the whole line) so, for example, expressions such as .C s/y*//g do not loop forever. .PP The additional external variables .C sed and .C nbra are used for special purposes. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions. .PP The .C LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, and the characters matched by character class expressions in regular expressions. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following is an example of how the regular expression macros and calls look from .IR grep (1): .nf .IP .C "#define INIT register char *sp = instring;" .C "#define GETC() (*sp++)" .C "#define PEEKC() (*sp)" .C "#define UNGETC(c) (--sp)" .C "#define RETURN(c) return;" .C "#define ERROR(c) regerr()" .IP .C "#include " \h'.5i'.\|.\|. .C "(void) compile(*argv, expbuf, &expbuf[ESIZE], '\e0');" \h'.5i'.\|.\|. .C "if (step(linebuf, expbuf))" .C " succeed();" .fi .SH AUTHOR .CR regexp() was developed by OSF and HP. .SH SEE ALSO grep(1), regcomp(3C), setlocale(3C), regexp(5). .SH STANDARDS CONFORMANCE .CR advance() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR compile() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc1 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc2 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR locs ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR step() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4compile()\f1 \- regular expression compile routine@@@\f3regexp(3X)\f1 .\" index@\f4step()\f1 \- regular expression string comparison routine@@@\f3regexp(3X)\f1 .\" index@\f4advance()\f1 \- regular expression substring comparison routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1expression, regular, compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1compile and match routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1comparison routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1match routines for regular expressions@@@\f3regexp(3X)\f1 .\" .\" toc@\f3regexp(3X)\f1:\0\0\f4compile()\f1, \f4step()\f1, \f4advance()\f1@@@regular expression compile and match routines .\" toc@\f4compile()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4step()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4advance()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" .\" links@regexp.3x compile.3x .\" links@regexp.3x step.3x .\" links@regexp.3x advance.3x .\" links@regexp.3x INIT.3x .\" links@regexp.3x GETC.3x .\" links@regexp.3x PEEKC.3x .\" links@regexp.3x UNGETC.3x .\" links@regexp.3x RETURN.3x .\" links@regexp.3x ERROR.3x .\" .\" fileset_database@regexp.3x PROGRAMING-MAN ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH RectObj 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIRectObj\fP \- The RectObj widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi RectObj is never instantiated. Its sole purpose is as a supporting superclass for other widget classes. .SS "Classes" RectObj inherits behavior and a resource from \fIObject\fP. .PP The class pointer is \fIrectObjClass\fP. .PP The class name is \fIRectObj\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. RectObj Resource Set Name Class Type Default Access _ XmNancestorSensitive XmCSensitive Boolean dynamic G XmNborderWidth XmCBorderWidth Dimension 1 CSG XmNheight XmCHeight Dimension dynamic CSG XmNsensitive XmCSensitive Boolean True CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .nL .ne 2i .IP "\fIXmNancestorSensitive\fP" Specifies whether the immediate parent of the gadget receives input events. Use the function \fIXtSetSensitive\fP if you are changing the argument to preserve data integrity (see \fIXmNsensitive\fP below). The default is the bitwise AND of the parent's \fIXmNsensitive\fP and \fIXmNancestorSensitive\fP resources. .IP "\fIXmNborderWidth\fP" Specifies the width of the border placed around the RectObj's rectangular display area. .IP "\fIXmNheight\fP" Specifies the inside height (excluding the border) of the RectObj's rectangular display area. .IP "\fIXmNsensitive\fP" Determines whether a RectObj receives input events. If a RectObj is sensitive, the parent dispatches to the gadget all keyboard, mouse button, motion, window enter/leave, and focus events. Insensitive gadgets do not receive these events. Use the function \fIXtSetSensitive\fP to change the sensitivity argument. Using \fIXtSetSensitive\fP ensures that if a parent widget has \fIXmNsensitive\fP set to False, the ancestor-sensitive flag of all its children is appropriately set. .IP "\fIXmNwidth\fP" Specifies the inside width (excluding the border) of the RectObj's rectangular display area. .IP "\fIXmNx\fP" Specifies the x-coordinate of the upper left outside corner of the RectObj's rectangular display area. The value is relative to the upper left inside corner of the parent window. .IP "\fIXmNy\fP" Specifies the y-coordinate of the upper left outside corner of the RectObj's rectangular display area. The value is relative to the upper left inside corner of the parent window. .nL .ne 3i .SS "Inherited Resources" RectObj inherits behavior and a resource from \fIObject\fP. For a description of this resource, refer to the \fIObject\fP man page. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Object Resource Set Name Class Type Default Access _ XmNdestroyCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .nL .ne 10 .SS "Translations" There are no translations for RectObj. .SH RELATED INFORMATION .na \fIObject(3X)\fP. .ad .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "RectObj" "Intrinsics Classes" .XX "RectObj" .XX "widget class, RectObj" .SH "Name" .Na RectObj widget class \- fundamental object class with geometry. .Nz .\" .SH "Synopsis" .IP "\s-1\f(HBPublic Headers:\fP\s0" 18n 0 \fI\fP .br \fI\fP .IP "\s-1\f(HBPrivate Header:\fP\s0" 18n 0 \fI\fP .IP "\s-1\f(HBClass\ Name:\fP\s0" 18n 0 RectObj .IP "\s-1\f(HBClass\ Hierarchy:\fP\s0" 18n 0 'nh Object \(-> RectObj .IP "\s-1\f(HBClass Pointer:\fP\s0" 18n 0 \f(CWrectObjClass\fP .IP "\s-1\f(HBInstantiation:\fP\s0" 18n 0 RectObj is an Intrinsics meta-class, and is not normally instantiated. .IP "\s-1\f(HBFunctions/Macros:\fP\s0" 18n 0 \f(CWXtIsRectObj(\^)\fP .\" .\" .SH "Availability" Release 4 and later. .\" .SH "Description" RectObj is a direct subclass of Object. It does not have a window, but does have a width, height, and location, and encapsulates the mechanisms for geometry management. .LP RectObj can be subclassed to provide widget-like objects (sometimes called "gadgets") that do not use windows and that do not have features often unused in simple widgets. This can save memory resources both in the server and in applications. .LP See the "Background" section below for more information on using RectObj objects. .\" .SH "New Resources" RectObj defines the following resources: .br .sp 1 .in 0 .KS .TS expand linesize(2) tab(@); l2 l2 l2 l2 l2 l2p7 l2p7 l2p7 l2p7 l2p7. \fRName@Class@Type@Default@Access\fP .sp .2 .XX "XtNancestorSensitive" \f(CWXtNancestorSensitive\fP@\f(CWXtCSensitive\fP@\f(CWBoolean\fP@\f(CWdynamic\fP@\f(CWG\fP .XX "XtNborderWidth" \f(CWXtNborderWidth\fP@\f(CWXtCBorderWidth\fP@\f(CWDimension\fP@\f(CW1\fP@\f(CWCSG\fP .XX "XtNheight" \f(CWXtNheight\fP@\f(CWXtCHeight\fP@\f(CWDimension\fP@\f(CWdynamic\fP@\f(CWCSG\fP .XX "XtNsensitive:RectObj" \f(CWXtNsensitive\fP@\f(CWXtCSensitive\fP@\f(CWBoolean\fP@\f(CWTrue\fP@\f(CWCSG\fP .XX "XtNwidth" \f(CWXtNwidth\fP@\f(CWXtCWidth\fP@\f(CWDimension\fP@\f(CWdynamic\fP@\f(CWCSG\fP .XX "XtNx" \f(CWXtNx\fP@\f(CWXtCPosition\fP@\f(CWPosition\fP@\f(CW0\fP@\f(CWCSG\fP .XX "XtNy" \f(CWXtNy\fP@\f(CWXtCPosition\fP@\f(CWPosition\fP@\f(CW0\fP@\f(CWCSG\fP .sp .2 .TE .KE .in .sp 1 .IP "\f(CWXtNancestorSensitive\fP" 5n .br Specifies whether the object has an insensitive ancestor. Default value is the bitwise AND of the \f(CWXtNsensitive\fP and \f(CWXtNancestorSensitive\fP resources of the parent. See \f(CWXtSetSensitive\fP(1). .IP "\f(CWXtNborderWidth\fP" 5n .br Width (in pixels) of the window's border. .IP "\f(CWXtNheight\fP" 5n .br Window height (in pixels), excluding the border. .IP "\f(CWXtNsensitive\fP" 5n .br Specifies whether a gadget receives input (is sensitive). \f(CWXtSetSensitive(\^)\fP can be used to change a widget's sensitivity and to guarantee that if a parent has its \f(CWXtNsensitive\fP resource set to \f(CWFalse\fP, then its children will have their \f(CWXtNancestorSensitive\fP resource set to \f(CWFalse\fP. See \f(CWXtSetSensitive\fP(1). .IP "\f(CWXtNwidth\fP" 5n .br Window width (in pixels), excluding the border. .IP "\f(CWXtNx\fP" 5n .br The x-coordinate of the widget's upper-left outer corner, relative to the upper-left inner corner of its parent. .IP "\f(CWXtNy\fP" 5n .br The y-coordinate of the widget's upper-left outer corner, relative to the upper-left inner corner of its parent. .\" .SH "Inherited Resources" RectObj inherits the following resource. .Nd 3 .sp 1 .in 0 .KS .TS H tab(@) linesize(2); lp7 lp7 . \fRResource@Inherited From\fP .sp 2p .Th \f(CWXtNdestroyCallback@Object@\fP .sp 2p .TE .KE .in .sp 1 .\" .SH "Class Structure" The RectObj class structure is shown below. Because the RectObj class was defined after Core was already standardized, the fields of these two class structures must match. Therefore, the fields named \f(CWrect\f(CIn\fR below exist only to pad out the structure. The use of each of the remaining fields is exactly as for the Core class. .Ps typedef struct _RectObjClassPart { WidgetClass superclass; String class_name; Cardinal widget_size; XtProc class_initialize; XtWidgetClassProc class_part_initialize; XtEnum class_inited; XtInitProc initialize; XtArgsProc initialize_hook; XtProc rect1; XtPointer rect2; Cardinal rect3; XtResourceList resources; Cardinal num_resources; XrmClass xrm_class; Boolean rect4; XtEnum rect5; Boolean rect6; Boolean rect7; XtWidgetProc destroy; XtWidgetProc resize; XtExposeProc expose; XtSetValuesFunc set_values; XtArgsFunc set_values_hook; XtAlmostProc set_values_almost; XtArgsProc get_values_hook; XtProc rect9; XtVersionType version; XtPointer callback_private; String rect10; XtGeometryHandler query_geometry; XtProc rect11; XtPointer extension ; } RectObjClassPart; typedef struct _RectObjClassRec { RectObjClassPart rect_class; } RectObjClassRec, *RectObjClass; .Pe There is no extension defined for this class, and the \f(CWextension\fP field in the class part structure should be \f(CWNULL\fP. .\" .SH "Instance Structure" The RectObj instance structure contains at least the fields shown below. The fields need not be in the order shown, but because the RectObj class was defined after Core was standardized, the position of each of these fields must be the same for both classes. .Ps typedef struct _RectObjPart { Position x, y; Dimension width, height; Dimension border_width; Boolean managed; Boolean sensitive; Boolean ancestor_sensitive; } RectObjPart; typedef struct _RectObjRec { ObjectPart object; RectObjPart rectangle; } RectObjRec; .Pe .\" .SH "Background" In the following discussion, "RectObj" refers only to objects that are a subclass of RectObj and that are not a subclass of Core. .LP Composite widget classes that wish to accept RectObj children must set the \f(CWaccepts_objects\fP field in the \f(CWCompositeClassExtension\fP extension structure to \f(CWTrue\fP. \f(CWXtCreateWidget()\fP will otherwise generate an error if called to create a non-widget child. .LP If gadgets are defined in an object set, the parent is responsible for much more than the parent of a widget. The parent must request and handle input events that occur for the gadget. The parent is also responsible for making sure that when it receives an expose event, the gadget children get drawn correctly. Subclasses of RectObj have expose procedures, but the parent is free to ignore them, instead drawing the contents of the child itself. This can potentially save graphics context switching. The precise contents of the \f(CWExpose\fP event and \f(CWRegion\fP arguments to the RectObj expose procedure are not specified by the Intrinsics; a particular rectangle object is free to define not only the coordinate system origin (self-relative or parent-relative) but also whether the rectangle, the Region, or both are assumed to have been intersected by the visible region of the object. .LP Normally, a composite widget that accepts non-widget children documents those children it can handle, since a gadget, unlike a widget, cannot be viewed as a completely self-contained entity. Since a particular composite widget class is usually designed to handle gadgets of only a limited set of classes, it should check the classes of newly added children in its \f(CWinsert_child()\fP method to make sure that it can deal with them. .LP The Intrinsics will clear areas of a parent window obscured by RectObj children, causing \f(CWExpose\fP events, under the following circumstances: .IP \(bu 3 A RectObj child is managed or unmanaged. .IP \(bu 3 In a call to \f(CWXtSetValues()\fP on a RectObj child, one or more of the \f(CWset_values()\fP methods returns \f(CWTrue\fP. .IP \(bu 3 In a call to \f(CWXtConfigureWidget()\fP on a RectObj child, areas will be cleared corresponding to both the old and the new child geometries, including the border, if the geometry changes. .IP \(bu 3 In a call to \f(CWXtMoveWidget()\fP on a RectObj child, areas will be cleared corresponding to both the old and the new child geometries, including the border, if the geometry changes. .IP \(bu 3 In a call to \f(CWXtResizeWidget()\fP on a RectObj child, an single rectangle will be cleared corresponding to the larger of the old and the new child geometries, if they are different. .IP \(bu 3 In a call to \f(CWXtMakeGeometryRequest()\fP (or \f(CWXtMakeResizeRequest()\fP) on a RectObj, if the manager returns \f(CWXtGeometryYes\fP, two rectangles will be cleared corresponding to both the old and the new child geometries. .LP Stacking order is not supported for RectObjs. If the child geometries overlap, Composite widgets with RectObj children can define any semantics desired, including making this an error. .LP When a RectObj is playing the role of a widget, developers must be reminded to avoid making assumptions about the object passed in the \f(CWWidget\fP argument to a callback procedure. .LP The \f(CWWidgetClass\fP arguments to the following functions may be \f(CWrectObjClass\fP or any subclass: .IP \(bu \f(CWXtCreateManagedWidget()\fP, \f(CWXtVaCreateManagedWidget()\fP .sp .LP The \f(CWWidget\fP arguments to the following functions may be of class RectObj or any subclass: .IP \(bu \f(CWXtConfigureWidget()\fP, \f(CWXtMoveWidget()\fP, \f(CWXtResizeWidget()\fP .IP \(bu \f(CWXtMakeGeometryRequest()\fP, \f(CWXtMakeResizeRequest()\fP .IP \(bu \f(CWXtManageChildren()\fP, \f(CWXtManageChild()\fP, \f(CWXtUnmanageChildren()\fP, \f(CWXtUnmanageChild()\fP .IP \(bu \f(CWXtQueryGeometry()\fP .IP \(bu \f(CWXtSetSensitive()\fP .IP \(bu \f(CWXtTranslateCoords()\fP .sp .LP The return value of the following functions will be of class RectObj or a subclass: .IP \(bu \f(CWXtCreateManagedWidget()\fP, \f(CWXtVaCreateManagedWidget()\fP .\" .SH "See Also" \s-1\fICore\fR\s+1\*(s3, \s-1\fIObject\fR\s+1\*(s3. .\"last line comment .\" $Header: nl_tools_16.3x,v 72.2 94/11/30 15:24:00 ssa Exp $ .TA n .TH nl_tools_16 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl_tools_16: ADVANCE(), byte_status(), BYTE_STATUS(), CHARADV(), CHARAT(), c_colwidth(), C_COLWIDTH(), firstof2(), FIRSTof2(), secof2(), SECof2(), WCHAR(), WCHARADV() \- tools to process 16-bit characters .SH SYNOPSIS .C "#include " .PP .C "int firstof2(int c);" .PP .C "int secof2(int c);" .PP .C "int byte_status(int c, int laststatus);" .PP .C int c_colwidth(int c); .PP .C "int FIRSTof2(int c);" .PP .C "int SECof2(int c);" .PP .C "int BYTE_STATUS(int c, int laststatus);" .PP .C "int C_COLWIDTH(int c);" .PP .C "int CHARAT(const char *p);" .PP .C "int ADVANCE(const char *p);" .PP .C "int CHARADV(const char *p);" .PP .C "int WCHAR(wchar_t wc, char *p);" .PP .C "int WCHARADV(wchar_t wc, char *p);" .PP .C "void PCHAR(int c, char *p);" .PP .C "void PCHARADV(int c, char *p);" .SS Remarks All interfaces listed above whose names begin with a capital letter are implemented as macros; the others are functions. .PP These macros and functions are obsolete. See WARNINGS. .SH DESCRIPTION The following macros and functions perform their operations based upon the loaded NLS environment (see .IR setlocale (3C)). .TP 20 .CR FIRSTof2() Takes a byte and returns a nonzero value if it can be the first byte of a two-byte character according to the NLS environment loaded, and zero if it cannot. .TP .CR SECof2() Takes a byte and returns a nonzero value if it can be the second byte of a two-byte character according to the loaded NLS environment, and zero if it cannot. .TP .CR BYTE_STATUS() Returns one of the following values based on the value of the current byte in .I c and the status of the previous byte interpreted in .I laststatus as returned by the last call to .CR BYTE_STATUS() . These are the status values as defined in .CR : .RS .RS .TP 15 .CR ONEBYTE Single-byte character .PD 0 .TP .CR SECOF2 Second byte of two-byte character .TP .CR FIRSTOF2 First byte of two-byte character .RE .RE .PD .IP To validate a two-byte character, both the first and second bytes must be valid. If the value of .I laststatus is .CR FIRSTOF2 but .CR SECof2( c ) returns false, .CI BYTE_STATUS( c , \ laststatus ) returns .CR ONEBYTE . .TP .CR C_COLWIDTH() Takes a byte which is assumed to be either a one-byte character or the first byte of a two-byte character, and returns the number of columns the character would occupy on a terminal display. .IP For the macros .CR BYTE_STATUS() , .CR C_COLWIDTH() , .CR FIRSTof2() , and .CR SEC0of2() , results are undefined for values of .I c less than \(mi1 (EOF) or greater than 255. .TP .CR CHARAT() Takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case, .CR CHARAT() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p . .TP .CR ADVANCE() Advances its pointer argument by the byte width of the character it is pointing at (either one or two bytes). .TP .CR CHARADV() Combines the functions of .CR CHARAT() and .CR ADVANCE() in a single macro. It takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case .CR CHARADV() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p , and advances .I p beyond the last byte of the character. .TP .CR WCHAR() Converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p . .CR WCHAR() returns the .CR wchar_t value .IR wc . .TP .CR WCHARADV() Combines the functions of .CR WCHAR() and .CR ADVANCE() in a single macro. It converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p , then advances .I p past the last byte. .CR WCHARADV() returns the .CR wchar_t value .IR wc . .TP .CR firstof2() .PD 0 .TP .CR secof2() .TP .CR byte_status() .TP .CR c_colwidth() .PD Subroutine versions of the corresponding macros. These functions can be called from languages other than C. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of single and/or multibyte characters. .SH WARNINGS The HP proprietary functions and macros described in this manual entry are .BR OBSOLETE . They are not portable to other vendor's systems, and will not be provided in future HP-UX releases. .PP For maximum portability, use the routines documented in the .IR multibyte (3C) manual entry for multibyte character processing. .PP Other macros listed in this manual entry cannot be used as the first argument to .CR WCHAR() or .CR WCHARADV() . For example, .IP .C "*t++ = *f++" .PP cannot be replaced by .IP .C "WCHARADV(CHARADV (f),t)" .PP Instead, use a method such as .IP .CR "int c; " ...\& " c = CHARADV (f)," .CR "WCHARADV (c,t)" .PP .CR WCHAR() and .CR WCHARADV() may produce a "null effect" warning from .IR lint (1) if not used as part of another expression or as part of a statement. This does not affect the functionality of either macro. .PP Note that .CR WCHAR() and .CR WCHARADV() are not "replace_char" macros. They do not prevent the second byte of a two-byte character from being left dangling if .CR WCHAR() or .CR WCHARADV() overwrite the first byte of the two-byte character with a single-byte character. .PP .CR CHARAT() , .CR ADVANCE() , and .CR CHARADV() do not examine the byte following the location pointed to by the argument to verify its validity as a .CR SECof2 byte. .SH AUTHOR .CR nl_tools_16() was developed by HP. .SH SEE ALSO setlocale(3C), multibyte(3C), wconv(3X), wctype(3X), hpnls(5). .\" .\" index@\f4ADVANCE()\f1 \- advance pointer to next 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARADV()\f1 \- get character and advance pointer to next character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARAT()\f1 \- get value of 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHAR()\f1, \- put 8- or 16-bit character in memory@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHARADV()\f1, \- put character in memory and advance pointer@@@\f3nl_tools_16(3X)\f1 .\" index@\f4byte_status()\f1, \f4BYTE_STATUS()\f1 \- test for valid 1- or 2-byte character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4firstof2()\f1, \f4FIRSTof2()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4secof2()\f1, \f4SECof2()\f1 \- test for valid second byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f1characters, tools to process 16-bit@@@\f3nl_tools_16(3X)\f1 .\" index@\f1process 16-bit characters, tools to@@@\f3nl_tools_16(3X)\f1 .\" index@\f1sixteen-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f116-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f1tools to process 16-bit characters@@@\f3nl_tools_16(3X)\f1 .\" .\" links@nl_tools_16.3x ADVANCE.3x .\" links@nl_tools_16.3x BYTE_STATUS.3x .\" links@nl_tools_16.3x CHARADV.3x .\" links@nl_tools_16.3x CHARAT.3x .\" links@nl_tools_16.3x FIRSTof2.3x .\" links@nl_tools_16.3x SECof2.3x .\" links@nl_tools_16.3x WCHAR.3x .\" links@nl_tools_16.3x WCHARADV.3x .\" links@nl_tools_16.3x byte_status.3x .\" links@nl_tools_16.3x c_colwidth.3x .\" links@nl_tools_16.3x firstof2.3x .\" links@nl_tools_16.3x secof2.3x .\" .\" toc@\f3nl_tools_16(3X)\f1:\0\0\f4ADVANCE()\f1, \f4byte_status()\f1, \f4BYTE_STATUS()\f1, \f4CHARADV()\f1,\n\f4CHARAT()\f1, \f4C_COLWIDTH()\f1, \f4c_colwidth()\f1, \f4firstof2()\f1, \f4FIRSTof2()\f1,\n\f4secof2()\f1, \f4SECof2()\f1, \f4WCHAR()\f1, \f4WCHARADV()\f1@@@tools to process 16-bit characters .\" toc@\f4ADVANCE()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4byte_status()\f1, \f4BYTE_STATUS()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARAT()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4firstof2()\f1, \f4FIRSTof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4secof2()\f1, \f4SECof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHAR()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH Shell 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIShell\fP \- The Shell widget class .SH SYNOPSIS .nf .sS .iS \&#include \&#include .iE .sE .SH DESCRIPTION .fi Shell is a top-level widget (with only one managed child) that encapsulates the interaction with the window manager. .PP At the time the shell's child is managed, the child's width is used for both widgets if the shell is unrealized and no width has been specified for the shell. Otherwise, the shell's width is used for both widgets. The same relations hold for the height of the shell and its child. .SS "Classes" Shell inherits behavior and resources from \fIComposite\fP and \fICore\fP. .PP The class pointer is \fIshellWidgetClass\fP. .PP The class name is \fIShell\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Shell Resource Set Name Class Type Default Access _ XmNallowShellResize XmCAllowShellResize Boolean False CG XmNcreatePopupChildProc XmCCreatePopupChildProc XtCreatePopupChildProc NULL CSG XmNgeometry XmCGeometry String NULL CSG XmNoverrideRedirect XmCOverrideRedirect Boolean False CSG XmNpopdownCallback XmCCallback XtCallbackList NULL C XmNpopupCallback XmCCallback XtCallbackList NULL C XmNsaveUnder XmCSaveUnder Boolean False CSG XmNvisual XmCVisual Visual * CopyFromParent CSG .TE .KE .in .sp 1 .nL .ne 6 .IP "\fIXmNallowShellResize\fP" Specifies that if this resource is False, the Shell widget instance returns \fIXtGeometryNo\fP to all geometry requests from its children. .IP "\fIXmNcreatePopupChildProc\fP" Specifies the pointer to a function that is called when the Shell widget instance is popped up by \fIXtPopup\fP. The function creates the child widget when the shell is popped up instead of when the application starts up. This can be used if the child needs to be reconfigured each time the shell is popped up. The function takes one argument, the popup shell, and returns no result. It is called after the popup callbacks specified by \fIXmNpopupCallback\fP. .IP "\fIXmNgeometry\fP" Specifies the desired geometry for the widget instance. This resource is examined only when the widget instance is unrealized and the number of its managed children is changed. It is to change the values of the \fIXmNx\fP, \fIXmNy\fP, \fIXmNwidth\fP, and \fIXmNheight\fP resources. .IP "\fIXmNoverrideRedirect\fP" Specifies this is True if the widget instance is a temporary window which should be ignored by the window manager. Applications and users should not normally alter this resource. .IP "\fIXmNpopdownCallback\fP" Specifies a list of callbacks that is called when the widget instance is popped down by \fIXtPopdown\fP. .IP "\fIXmNpopupCallback\fP" Specifies a list of callbacks that is called when the widget instance is popped up by \fIXtPopup\fP. .IP "\fIXmNsaveUnder\fP" Specifies a True value if it is desirable to save the contents of the screen beneath this widget instance, avoiding expose events when the instance is unmapped. This is a hint, and an implementation may save contents whenever it desires, including always or never. .nL .ne 6 .IP "\fIXmNvisual\fP" Specifies the visual used in creating the widget. .nL .ne 3i .SS "Inherited Resources" Shell inherits behavior and resources from the following superclass. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 1 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Translations" There are no translations for Shell. .SH RELATED INFORMATION .na \fIComposite(3X)\fP and \fICore(3X)\fP. .ad .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "Shell" "Intrinsics Classes" .XX "Shell" .XX "widget class, Shell" .SH "Name" .Na Shell widget class \- fundamental widget class that controls the interaction between top-level windows and the window manager. .Nz .\" .SH "Synopsis" .IP "\s-1\f(HBPublic Headers:\fP\s0" 18n 0 \fI\fP .br \fI\fP .IP "\s-1\f(HBPrivate Header:\fP\s0" 18n 0 \fI\fP .IP "\s-1\f(HBClass\ Name:\fP\s0" 18n 0 Shell .IP "\s-1\f(HBClass\ Hierarchy:\fP\s0" 18n 0 'nh Core \(-> Composite \(-> Shell .IP "\s-1\f(HBClass Pointer:\fP\s0" 18n 0 \f(CWshellWidgetClass\fP .IP "\s-1\f(HBInstantiation\fP\s0" 18n 0 Shell is an Intrinsics meta-class, and is not normally instantiated. .IP "\s-1\f(HBFunctions/Macros:\fP\s0" 18n 0 \f(CWXtIsShell()\fP .\" .SH "Description" Shell is a subclass of Composite that handles interactions with the window manager for its single allowed child widget. .LP Widgets negotiate their size and position with their parent widget (i.e., the widget that directly contains them). Widgets at the top of the hierarchy do not have parent widgets. Instead, they must deal with the outside world. To provide for this, each top-level widget is created as a child of a special widget, called a Shell. .LP Shells have been designed to be as nearly invisible as possible. Clients have to create them (the top-level widget returned by a call to \f(CWXtAppInitialize()\fR or \f(CWXtCreateApplicationContext()\fR is a Shell widget, as is a popup widget created with \f(CWXtPopup()\fR), but they should never have to worry about their sizes. .LP If a shell widget is resized from the outside (typically by a window manager), the shell widget also resizes its child widget automatically. Similarly, if the shell's child widget needs to change size, it can make a geometry request to the shell, and the shell negotiates the size change with the outer environment. Clients should never attempt to change the size of their shells directly. .LP There are seven different types of shells. Only four of these are public (i.e., should be instantiated by applications): .XS "Shell widget: types" .XX "Shell widget: types; OverrideShell" .IP "OverrideShell" 5n Used for shell windows that completely bypass the window manager (for example, popup menu shells). .XX "Shell widget: types; TransientShell" .IP "TransientShell" Used for shell windows that can be manipulated by the window manager but are not allowed to be iconified separately (for example, Dialog boxes that make no sense without their associated application). They are iconified by the window manager only if the main application shell is iconified. .XX "Shell widget: types; TopLevelShell" .IP "TopLevelShell" Used for normal top-level windows (for example, any additional top-level widgets an application needs). .XX "Shell widget: types; ApplicationShell" .IP "ApplicationShell" Used by the window manager to define a separate application instance, which is the main top-level window of the application. .LP .Nd 5 Three classes of shells are internal and should not be instantiated or subclassed: .IP "Shell" 5n .XX "Shell widget: types; Shell" Provides the base class for shell widgets and the fields needed for all types of shells. Shell is a direct subclass of Composite. .XX "Shell widget: types; WMShell" .IP "WMShell" Contains fields needed by the common window manager protocol. .XX "Shell widget: types; VendorShell" .IP "VendorShell" Contains fields used to communicate with vendor-specific window managers. .XE "Shell widget: types" .LP Figure 1 shows the class hierarchy for Shell widgets. .\" .Pf ../figs/1.1.eps "" "" "" "" noscale .sp 2.575i \s-1\f(HI Figure 1. Class Hierarchy for Shell widget classes\fP\s0 .\" .Nd 15 .SH "New Resources" Shell defines the following resources: .br .sp 1 .in 0 .KS .TS H tab (@), linesize (2); l2 l2 l2 l2 l2 l2p7 l2p7 l2p7 l2p7 l2p7. \fRName@Class@Type@Default@Access\fP .sp 2p .Th .XX "XtNallowShellResize" \f(CWXtNallowShell-\fP@\f(CWXtCAllowShell-\fP@\f(CWBoolean\fP@\f(CWFalse\fP@\f(CWCG\fP .sp -2p \0\0\f(CWResize\fP@\0\0\f(CWResize\fP .XX "XtNcreatePopupChildProc" \f(CWXtNcreatePopup-\fP@\f(CWXtCCreatePopup-\fP@\f(CW(*)(\^)\fP@\f(CWNULL\fP@\f(CWCSG\fP .sp -2p \0\0\f(CWChildProc\fP@\0\0\f(CWChildProc\fP .XX "XtNgeometry" \f(CWXtNgeometry\fP@\f(CWXtCGeometry\fP@\f(CWString\fP@\f(CWNULL\fP@\f(CWCSG\fP .XX "XtNoverrideRedirect" \f(CWXtNoverride-\fP@\f(CWXtCOverride-\fP@\f(CWBoolean\fP@\f(CWFalse\fP@\f(CWCSG\fP .sp -2p \0\0\f(CWRedirect\fP@\0\0\f(CWRedirect\fP .XX "XtNpopdownCallback" \f(CWXtNpopdownCallback\fP@\f(CWXtCCallback\fP@\f(CWXtCallbackList\fP@\f(CWNULL\fP@\f(CWC\fP .XX "XtNpopupCallback" \f(CWXtNpopupCallback\fP@\f(CWXtCCallback\fP@\f(CWXtCallbackList\fP@\f(CWNULL\fP@\f(CWC\fP .XX "XtNsaveUnder" \f(CWXtNsaveUnder\fP@\f(CWXtCSaveUnder\fP@\f(CWBoolean\fP@\f(CWFalse\fP@\f(CWCSG\fP .XX "XtNvisual" \f(CWXtNvisual\fP@\f(CWXtCVisual\fP@\f(CWVisual *\fP@\f(CWCopyFromParent\fP@\f(CWCSG\fP .sp .2 .TE .KE .in .sp 1 .IP \f(CWXtNallowShellResize\fP 5n .br If \f(CWFalse\fP (default), the Shell widget refuses geometry requests from its children (by returning \f(CWXtGeometryNo\fP). If \f(CWTrue\fP, the shell will attempt to satisfy the geometry request by interacting with the window manager. .IP \f(CWXtNcreatePopupChildProc\fP 5n .br A pointer to a procedure that creates a child widget\-but only when the shell is popped up, not when the application is started. This is useful in menus, for example, since you don't need to create the menu until it is popped up. This procedure is called after those specified in the \f(CWXtNpopupCallback\fP resource. .IP \f(CWXtNgeometry\fP 5n .br Specifies the size and position of the window in the standard X geometry string format. This string is parsed with the Xlib function \f(CWXWMGeometry()\fP using the \f(CWXtNx\fP, \f(CWXtNy\fP, \f(CWXtNwidth\fP, and \f(CWXtNheight\fP resources from the Core part, and the \f(CWXtNwidthInc\fP and \f(CWXtNheightInc\fP and other size and position resources from the WMShell part as defaults. If the geometry specifies an x or y position, then \f(CWUSPosition\fP is set. If the geometry specifies a width or height, then \f(CWUSSize\fP is set. Any fields in the geometry specification override the corresponding values in the Core \f(CIx\fP, \f(CIy\fP, \f(CIwidth\fP, and \f(CIheight\fP fields. If \f(CIgeometry\fP is \f(CWNULL\fP or contains only a partial specification, then the Core \f(CIx\fP, \f(CIy\fP, \f(CIwidth\fP, and \f(CIheight\fP fields are used and \f(CWPPosition\fP and \f(CWPSize\fP are set as appropriate. The geometry string is not copied by any of the Intrinsics Shell classes; a client specifying the string in an arglist or varargs list must ensure that the value remains valid until the shell widget is realized. .IP \f(CWXtNoverrideRedirect\fP 5n .br If \f(CWTrue\fP, the window manager will not intercede when this window is popped up. Popup menus usually have this resource \f(CWTrue\fP. .IP \f(CWXtNpopdownCallback\fP 5n .br A list of procedures to be called immediately before the shell is popped up with \f(CWXtPopup()\fP. .IP \f(CWXtNpopupCallback\fP 5n .br A list of procedures to be called immediately after the shell is popped down with \f(CWXtPopdown()\fP. .IP \f(CWXtNsaveUnder\fP 5n .br If \f(CWTrue\fP, the X server is requested to save the screen contents that are obscured when this widget is mapped, thereby avoiding the overhead of sending expose events after the widget is unmapped. This is useful for popup menus. .IP \f(CWXtNvisual\fP 5n .br The Visual that is used when creating the widget. .\" .Nd 5 .SH "Inherited Resources" Shell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. .Nd 3 .sp 1 .in 0 .KS .TS H tab(@), linesize(2); lp7 lp7 lp7 lp7 lp6w(1.25i) lp6w(1i) lp6w(1.25i) lp6w(1i). \fRResource@Inherited From@Resource@Inherited From\fP .sp 2p .Th \f(CWXtNaccelerators\fP@\f(CWCore\fP@\f(CWXtNheight\fP@\f(CWCore\fP \f(CWXtNancestor-\fP@\f(CWCore\fP@\f(CWXtNinitial-\fP@\f(CWCore\fP .sp -2p \0\0\f(CWSensitive\fP@@\0\0\f(CWResources-\fP .sp -2p @@\0\0\f(CWPersistent\fP \f(CWXtNbackground\fP@\f(CWCore\fP@\f(CWXtNinsertPosition\fP@\f(CWComposite\fP \f(CWXtNbackground-\fP@\f(CWCore\fP@\f(CWXtNmappedWhen-\fP@\f(CWCore\fP .sp -2p \0\0\f(CWPixmap\fP@@\0\0\f(CWManaged\fP \f(CWXtNborderColor\fP@\f(CWCore\fP@\f(CWXtNnumChildren\fP@\f(CWComposite\fP \f(CWXtNborderPixmap\fP@\f(CWCore\fP@\f(CWXtNscreen\fP@\f(CWCore\fP \f(CWXtNborderWidth\fP@\f(CWCore\fP@\f(CWXtNsensitive\fP@\f(CWCore\fP \f(CWXtNchildren\fP@\f(CWComposite\fP@\f(CWXtNtranslations\fP@\f(CWCore\fP \f(CWXtNcolormap\fP@\f(CWCore\fP@\f(CWXtNwidth\fP@\f(CWCore\fP \f(CWXtNdepth\fP@\f(CWCore\fP@\f(CWXtNx\fP@\f(CWCore\fP \f(CWXtNdestroy-\fP@\f(CWCore\fP@\f(CWXtNy\fP@\f(CWCore\fP .sp -2p \0\0\f(CWCallback\fP .sp 2p .TE .KE .in .sp 1 .\" .SH "Class Structure" .XS "Shell widget: ShellClassPart" The Shell class structure contains only an extension field: .Ps .ta 5n 2i typedef struct { XtPointer extension; /* pointer to extension record */ } ShellClassPart; typedef struct _ShellClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ShellClassPart shell_class; } ShellClassRec; .Pe .\" .Nd 5 .SH "Extension Structure" There is one extension defined for the Shell class which provides a \f(CWroot_geometry_manager()\fP method. The extension structure is shown below; the \f(CWrecord_type\fP field should be \f(CWNULLQUARK\fP, and the \f(CWversion\fP field should be \f(CWXtShellExtensionVersion\fP. The \f(CWroot_geometry_manager\fP field is the procedure which negotiates geometry with the window manager. See \f(CWroot_geometry_manager\fP(4). .Ps typedef struct { XtPointer next_extension; XrmQuark record_type; long version; Cardinal record_size; XtGeometryHandler root_geometry_manager; } ShellClassExtensionRec, *ShellClassExtension; .Pe .LP If there is no \f(CWShellClassPart\fP extension record is declared with \f(CWrecord_type\fR equal to \f(CW\s-1\f(CWNULLQUARK\s+1\fR, then the \f(CWroot_geometry_manager()\fP method is inherited from the shell's superclass. .\" .SH "Instance Structure" The Shell instance structure contains at least the following fields (which need not be in this order): .Ps typedef struct { String geometry; XtCreatePopupChildProc create_popup_child_proc; XtGrabKind grab_kind; Boolean spring_loaded; Boolean popped_up; Boolean allow_shell_resize; Boolean client_specified; Boolean save_under; Boolean override_redirect; XtCallbackList popup_callback; XtCallbackList popdown_callback; Visual *visual; } ShellPart; typedef struct { CorePart core; CompositePart composite; ShellPart shell; } ShellRec, *ShellWidget; .Pe .\" .SH "See Also" \s-1\fIApplicationShell\fR\s+1\*(s3, \s-1\fIOverrideShell\fR\s+1\*(s3, \s-1\fITopLevelShell\fR\s+1\*(s3, \s-1\fITransientShell\fR\s+1\*(s3, \s-1\fIVendorShell\fR\s+1\*(s3, \s-1\fIWMShell\fR\s+1\*(s3. .\"last line comment ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH TopLevelShell 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fITopLevelShell\fP \- The TopLevelShell widget class .SH SYNOPSIS .nf .sS .iS \&#include \&#include .iE .sE .SH DESCRIPTION .fi TopLevelShell is used for normal top-level windows such as any additional top-level widgets an application needs. .SS "Classes" TopLevelShell inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIShell\fP, \fIWMShell\fP, and \fIVendorShell\fP. .PP The class pointer is \fItopLevelShellWidgetClass\fP. .PP The class name is \fITopLevelShell\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. TopLevelShell Resource Set Name Class Type Default Access _ XmNiconic XmCIconic Boolean False CSG XmNiconName XmCIconName String NULL CSG XmNiconNameEncoding XmCIconNameEncoding Atom dynamic CSG .TE .KE .in .sp 1 .IP "\fIXmNiconic" Specifies that if this is True when the widget instance is realized, the widget instance indicates to the window manager that the application wishes to start as an icon, irrespective of the \fIXmNinitialState\fP resource. .IP "\fIXmNiconName\fP" Specifies the short form of the application name to be displayed by the window manager when the application is iconified. .IP "\fIXmNiconNameEncoding\fP" Specifies a property type that represents the encoding of the \fIXmNiconName\fP string. If a language procedure has been set, the default is None; otherwise, the default is XA_STRING. When the widget is realized, if the value is None, the corresponding name is assumed to be in the current locale. The name is passed to \fIXmbTextListToTextProperty\fP with an encoding style of \fIXStdICCTextStyle\fP. The resulting encoding is "STRING" if the name is fully convertible to "STRING," otherwise "COMPOUND_TEXT." The values of the encoding resources are not changed; they remain None. .SS "Inherited Resources" TopLevelShell inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. VendorShell Resource Set Name Class Type Default Access _ XmNaudibleWarning XmCAudibleWarning unsigned char XmBELL CSG XmNbuttonFontList XmCButtonFontList XmFontList dynamic CSG XmNdefaultFontList XmCDefaultFontList XmFontList dynamic CG XmNdeleteResponse XmCDeleteResponse unsigned char XmDESTROY CSG XmNinputMethod XmCInputMethod String NULL CSG XmNkeyboardFocusPolicy XmCKeyboardFocusPolicy unsigned char XmEXPLICIT CSG XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG XmNmwmDecorations XmCMwmDecorations int -1 CSG XmNmwmFunctions XmCMwmFunctions int -1 CSG XmNmwmInputMode XmCMwmInputMode int -1 CSG XmNmwmMenu XmCMwmMenu String NULL CSG XmNpreeditType XmCPreeditType String dynamic CSG XmNshellUnitType XmCShellUnitType unsigned char XmPIXELS CSG XmNtextFontList XmCTextFontList XmFontList dynamic CSG XmNuseAsyncGeometry XmCUseAsyncGeometry Boolean False CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. WMShell Resource Set Name Class Type Default Access _ XmNbaseHeight XmCBaseHeight int XtUnspecifiedShellInt CSG XmNbaseWidth XmCBaseWidth int XtUnspecifiedShellInt CSG XmNheightInc XmCHeightInc int XtUnspecifiedShellInt CSG XmNiconMask XmCIconMask Pixmap NULL CSG XmNiconPixmap XmCIconPixmap Pixmap NULL CSG XmNiconWindow XmCIconWindow Window NULL CSG XmNiconX XmCIconX int \-1 CSG XmNiconY XmCIconY int \-1 CSG XmNinitialState XmCInitialState int NormalState CSG XmNinput XmCInput Boolean True CSG XmNmaxAspectX XmCMaxAspectX int XtUnspecifiedShellInt CSG XmNmaxAspectY XmCMaxAspectY int XtUnspecifiedShellInt CSG XmNmaxHeight XmCMaxHeight int XtUnspecifiedShellInt CSG XmNmaxWidth XmCMaxWidth int XtUnspecifiedShellInt CSG .wH .tH XmNminAspectX XmCMinAspectX int XtUnspecifiedShellInt CSG XmNminAspectY XmCMinAspectY int XtUnspecifiedShellInt CSG XmNminHeight XmCMinHeight int XtUnspecifiedShellInt CSG XmNminWidth XmCMinWidth int XtUnspecifiedShellInt CSG XmNtitle XmCTitle String dynamic CSG XmNtitleEncoding XmCTitleEncoding Atom dynamic CSG XmNtransient XmCTransient Boolean False CSG XmNwaitForWm XmCWaitForWm Boolean True CSG XmNwidthInc XmCWidthInc int XtUnspecifiedShellInt CSG XmNwindowGroup XmCWindowGroup Window dynamic CSG XmNwinGravity XmCWinGravity int dynamic CSG XmNwmTimeout XmCWmTimeout int 5000 ms CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Shell Resource Set Name Class Type Default Access _ XmNallowShellResize XmCAllowShellResize Boolean False CG XmNcreatePopupChildProc XmCCreatePopupChildProc XtCreatePopupChildProc NULL CSG XmNgeometry XmCGeometry String NULL CSG XmNoverrideRedirect XmCOverrideRedirect Boolean False CSG XmNpopdownCallback XmCCallback XtCallbackList NULL C XmNpopupCallback XmCCallback XtCallbackList NULL C XmNsaveUnder XmCSaveUnder Boolean False CSG XmNvisual XmCVisual Visual * CopyFromParent CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 1 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Translations" There are no translations for TopLevelShell. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fICore(3X)\fP, \fIShell(3X)\fP, \fIWMShell(3X)\fP, and \fIVendorShell(3X)\fP. .ad .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "TopLevelShell" "Intrinsics Classes" .XX "TopLevelShell" .SH "Name" .Na TopLevelShell widget class \- additional top-level shells for an application. .Nz .\" .SH "Synopsis" .IP "\s-1\f(HBPublic Headers:\fP\s0" 18n 0 \fI\fP .br \fI\fP .IP "\s-1\f(HBPrivate Header:\fP\s0" 18n 0 \fI\fP .IP "\s-1\f(HBClass\ Name:\fP\s0" 18n 0 TopLevelShell .IP "\s-1\f(HBClass\ Hierarchy:\fP\s0" 18n 0 'nh Core \(-> Composite \(-> Shell \(-> WMShell \(-> VendorShell \(-> TopLevelShell .IP "\s-1\f(HBClass Pointer:\fP\s0" 18n 0 \f(CWtopLevelShellWidgetClass\fP .IP "\s-1\f(HBInstantiation:\fP\s0" 18n 0 .ft CW .ps 9 \f(CIwidget\fP = XtCreatePopupShell(\f(CIname\fP, .br topLevelShellWidgetClass, ...) .ps 10 .ft R .IP "\s-1\f(HBFunctions/Macros:\fP\s0" 18n 0 \f(CWXtIsTopLevelShell(\^)\fP .\" .SH "Description" The TopLevelShell widget class is a subclass of VendorShell that is used for additional shells in applications having more than one top-level window (one of which serves as the root of a widget instance tree). .\" .SH "New Resources" TopLevelShell defines the following resources: .br .sp 1 .in 0 .KS .TS expand linesize(2) tab(@); l l l l l lp7 lp7 lp7 lp7 lp7. \fRName@Class@Type@Default@Access\fP .sp .2 .XX "XtNiconic" \f(CWXtNiconic\fP@\f(CWXtCIconic\fP@\f(CWBoolean\fP@\f(CWFalse\fP@\f(CWCSG\fP .XX "XtNiconName" \f(CWXtNiconName\fP@\f(CWXtCIconName\fP@\f(CWString\fP@\f(CWNULL\fP@\f(CWCSG\fP .XX "XtNiconNameEncoding" \f(CWXtNiconNameEncoding\fP@\f(CWXtCIconNameEncoding\fP@\f(CWAtom\fP@\f(CWXA_STRING\fP@\f(CWCSG\fP .sp .2 .TE .KE .in .sp 1 .IP \f(CWXtNiconic\fP 5n If \f(CWTrue\fP, the widget is realized as an icon, regardless of the value of the \f(CWXtNinitialState\fP resource. When the value of this resource is set for a running application, the TopLevelShell will iconify or de-iconify the window appropriately, following the conventions defined by the \fIInter-Client Communications Conventions Manual\fP. When TopLevelShell de-iconifies a window, it calls \f(CWXtPopup\fP with the \f(CIgrab_kind\fP argument set to \f(CWXtGrabNone\fP. .IP \f(CWXtNiconName\fP The icon name for the application. Stored in the WM_ICON_NAME property of the shell's window. Most window managers will interpret this property and display the name. .Nd 10 .IP \f(CWXtNiconNameEncoding\fP The property type of the encoding of the \f(CWXtNiconName\fP resource. Stored in the WM_ICON_NAME property of the shell's window. .\" .SH "Inherited Resources" TopLevelShell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. .Nd 3 .sp 1 .in 0 .KS .TS H tab(@), linesize(2); lp7 lp7 lp7 lp7 lp6w(1.25i) lp6w(1i) lp6w(1.25i) lp6w(1i). \fRResource@Inherited From@Resource@Inherited From\fP .sp 2p .Th \f(CWXtNaccelerators\fP@\f(CWCore\fP@\f(CWXtNmaxHeight\fP@\f(CWWMShell\fP \f(CWXtNallowShellResize\fP@\f(CWShell\fP@\f(CWXtNmaxWidth\fP@\f(CWWMShell\fP \f(CWXtNancestorSensitive\fP@\f(CWCore\fP@\f(CWXtNminAspectX\fP@\f(CWWMShell\fP \f(CWXtNbackground\fP@\f(CWCore\fP@\f(CWXtNminAspectY\fP@\f(CWWMShell\fP \f(CWXtNbackgroundPixmap\fP@\f(CWCore\fP@\f(CWXtNminHeight\fP@\f(CWWMShell\fP \f(CWXtNbaseHeight\fP@\f(CWWMShell\fP@\f(CWXtNminWidth\fP@\f(CWWMShell\fP \f(CWXtNbaseWidth\fP@\f(CWWMShell\fP@\f(CWXtNmwmDecorations\fP@\f(CWVendorShell\fP \f(CWXtNborderColor\fP@\f(CWCore\fP@\f(CWXtNmwmFunctions\fP@\f(CWVendorShell\fP \f(CWXtNborderPixmap\fP@\f(CWCore\fP@\f(CWXtNmwmInputMode\fP@\f(CWVendorShell\fP \f(CWXtNborderWidth\fP@\f(CWCore\fP@\f(CWXtNmwmMenu\fP@\f(CWVendorShell\fP \f(CWXtNchildren\fP@\f(CWComposite\fP@\f(CWXtNnumChildren\fP@\f(CWComposite\fP \f(CWXtNcolormap\fP@\f(CWCore\fP@\f(CWXtNoverrideRedirect\fP@\f(CWShell\fP \f(CWXtNcreatePopupChild-\fP@\f(CWShell\fP@\f(CWXtNpopdownCallback\fP@\f(CWShell\fP .sp -2p \0\0\f(CWProc\fP \f(CWXtNdefaultFontList\fP@\f(CWVendorShell\fP@\f(CWXtNpopupCallback\fP@\f(CWShell\fP \f(CWXtNdeleteResponse\fP@\f(CWVendorShell\fP@\f(CWXtNsaveUnder\fP@\f(CWShell\fP \f(CWXtNdepth\fP@\f(CWCore\fP@\f(CWXtNscreen\fP@\f(CWCore\fP \f(CWXtNdestroyCallback\fP@\f(CWCore\fP@\f(CWXtNsensitive\fP@\f(CWCore\fP \f(CWXtNgeometry\fP@\f(CWShell\fP@\f(CWXtNshellUnitType\fP@\f(CWVendorShell\fP \f(CWXtNheight\fP@\f(CWCore\fP@\f(CWXtNtitle\fP@\f(CWWMShell\fP \f(CWXtNheightInc\fP@\f(CWWMShell\fP@\f(CWXtNtitleEncoding\fP@\f(CWWMShell\fP \f(CWXtNiconMask\fP@\f(CWWMShell\fP@\f(CWXtNtransient\fP@\f(CWWMShell\fP \f(CWXtNiconPixmap\fP@\f(CWWMShell\fP@\f(CWXtNtranslations\fP@\f(CWCore\fP \f(CWXtNiconWindow\fP@\f(CWWMShell\fP@\f(CWXtNuseAsyncGeometry\fP@\f(CWVendorShell\fP \f(CWXtNiconX\fP@\f(CWWMShell\fP@\f(CWXtNvisual\fP@\f(CWShell\fP \f(CWXtNiconY\fP@\f(CWWMShell\fP@\f(CWXtNwaitForWm\fP@\f(CWWMShell\fP \f(CWXtNinitialResources-\fP@\f(CWCore\fP@\f(CWXtNwidth\fP@\f(CWCore\fP .sp -2p \0\0\f(CWPersistent\fP \f(CWXtNinitialState\fP@\f(CWWMShell\fP@\f(CWXtNwidthInc\fP@\f(CWWMShell\fP \f(CWXtNinput\fP@\f(CWWMShell\fP@\f(CWXtNwindowGroup\fP@\f(CWWMShell\fP \f(CWXtNinsertPosition\fP@\f(CWComposite\fP@\f(CWXtNwinGravity\fP@\f(CWWMShell\fP \f(CWXtNkeyboardFocusPolicy\fP@\f(CWVendorShell\fP@\f(CWXtNwmTimeout\fP@\f(CWWMShell\fP \f(CWXtNmappedWhenManaged\fP@\f(CWCore\fP@\f(CWXtNx\fP@\f(CWCore\fP \f(CWXtNmaxAspectX\fP@\f(CWWMShell\fP@\f(CWXtNy\fP@\f(CWCore\fP \f(CWXtNmaxAspectY\fP@\f(CWWMShell\fP .sp 2p .TE .KE .in .sp 1 .\" .SH "Class Structure" The TopLevelShell class structure contains only an extension field: .Ps .ta 5n 2i typedef struct { XtPointer extension; /* pointer to extension record */ } TopLevelShellClassPart; typedef struct _TopLevelShellClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ShellClassPart shell_class; WMShellClassPart wm_shell_class; VendorShellClassPart vendor_shell_class; TopLevelShellClassPart top_level_shell_class; } TopLevelShellClassRec; .Pe There is no extension defined for TopLevelShell, and the \f(CWextension\fP field should be \f(CWNULL\fP. .\" .SH "Instance Structure" The TopLevelShell instance structure contains at least the following fields (which need not be in this order): .Ps .ta .5i 3i typedef struct { String icon_name; Boolean iconic; Atom icon_name_encoding; } TopLevelShellPart; typedef struct { CorePart core; CompositePart composite; ShellPart shell; WMShellPart wm; VendorShellPart vendor; TopLevelShellPart topLevel; } TopLevelShellRec, *TopLevelShellWidget; .Pe .\" .SH "See Also" \s-1\fIShell\fR\s+1\*(s3, \s-1\fIWMShell\fR\s+1\*(s3. .\"last line comment ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH TransientShell 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fITransientShell\fP \- The TransientShell widget class .SH SYNOPSIS .nf .sS .iS \&#include \&#include .iE .sE .SH DESCRIPTION .fi TransientShell is used for shell windows that can be manipulated by the window manager but are not allowed to be iconified separately. For example, Dialog boxes make no sense without their associated application. They are iconified by the window manager only if the main application shell is iconified. .nL .ne 2i .SS "Classes" TransientShell inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIShell\fP, \fIWMShell\fP, and \fIVendorShell\fP. .PP The class pointer is \fItransientShellWidgetClass\fP. .PP The class name is \fITransientShell\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .PP In addition to these new resources, new resources, \fITransientShell\fP overrides the \fIXmNsaveUnder\fP resource in \fIShell\fP and the \fIXmNtransient\fP resource in \fIWMShell\fP. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. TransientShell Resource Set Name Class Type Default Access _ XmNtransientFor XmCTransientFor Widget NULL CSG .TE .KE .in .sp 1 .IP "\fIXmNtransientFor\fP" Specifies a widget for which the shell acts as a pop-up. If this resource is NULL or is a widget that has not been realized, the \fIXmNwindowGroup\fP is used instead. .nL .ne 1.5i .SS "Inherited Resources" TransientShell inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. VendorShell Resource Set Name Class Type Default Access _ XmNaudibleWarning XmCAudibleWarning unsigned char XmBELL CSG XmNbuttonFontList XmCButtonFontList XmFontList dynamic CSG XmNdefaultFontList XmCDefaultFontList XmFontList dynamic CG XmNdeleteResponse XmCDeleteResponse unsigned char XmDESTROY CSG XmNinputMethod XmCInputMethod String NULL CSG XmNkeyboardFocusPolicy XmCKeyboardFocusPolicy unsigned char XmEXPLICIT CSG XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG XmNmwmDecorations XmCMwmDecorations int -1 CSG XmNmwmFunctions XmCMwmFunctions int -1 CSG XmNmwmInputMode XmCMwmInputMode int -1 CSG XmNmwmMenu XmCMwmMenu String NULL CSG XmNpreeditType XmCPreeditType String dynamic CSG XmNshellUnitType XmCShellUnitType unsigned char XmPIXELS CSG XmNtextFontList XmCTextFontList XmFontList dynamic CSG XmNuseAsyncGeometry XmCUseAsyncGeometry Boolean False CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. WMShell Resource Set Name Class Type Default Access _ XmNbaseHeight XmCBaseHeight int XtUnspecifiedShellInt CSG XmNbaseWidth XmCBaseWidth int XtUnspecifiedShellInt CSG XmNheightInc XmCHeightInc int XtUnspecifiedShellInt CSG XmNiconMask XmCIconMask Pixmap NULL CSG XmNiconPixmap XmCIconPixmap Pixmap NULL CSG XmNiconWindow XmCIconWindow Window NULL CSG XmNiconX XmCIconX int \-1 CSG XmNiconY XmCIconY int \-1 CSG XmNinitialState XmCInitialState int NormalState CSG XmNinput XmCInput Boolean True CSG XmNmaxAspectX XmCMaxAspectX int XtUnspecifiedShellInt CSG XmNmaxAspectY XmCMaxAspectY int XtUnspecifiedShellInt CSG XmNmaxHeight XmCMaxHeight int XtUnspecifiedShellInt CSG XmNmaxWidth XmCMaxWidth int XtUnspecifiedShellInt CSG .wH .tH XmNminAspectX XmCMinAspectX int XtUnspecifiedShellInt CSG XmNminAspectY XmCMinAspectY int XtUnspecifiedShellInt CSG XmNminHeight XmCMinHeight int XtUnspecifiedShellInt CSG XmNminWidth XmCMinWidth int XtUnspecifiedShellInt CSG XmNtitle XmCTitle String dynamic CSG XmNtitleEncoding XmCTitleEncoding Atom dynamic CSG XmNtransient XmCTransient Boolean True CSG XmNwaitForWm XmCWaitForWm Boolean True CSG XmNwidthInc XmCWidthInc int XtUnspecifiedShellInt CSG XmNwindowGroup XmCWindowGroup Window dynamic CSG XmNwinGravity XmCWinGravity int dynamic CSG XmNwmTimeout XmCWmTimeout int 5000 ms CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Shell Resource Set Name Class Type Default Access _ XmNallowShellResize XmCAllowShellResize Boolean False CG XmNcreatePopupChildProc XmCCreatePopupChildProc XtCreatePopupChildProc NULL CSG XmNgeometry XmCGeometry String NULL CSG XmNoverrideRedirect XmCOverrideRedirect Boolean False CSG XmNpopdownCallback XmCCallback XtCallbackList NULL C XmNpopupCallback XmCCallback XtCallbackList NULL C XmNsaveUnder XmCSaveUnder Boolean True CSG XmNvisual XmCVisual Visual * CopyFromParent CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 1 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Translations" There are no translations for TransientShell. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fICore(3X)\fP, \fIShell(3X)\fP, \fIVendorShell(3X)\fP, and \fIWMShell(3X)\fP. .ad .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "TransientShell" "Intrinsics Classes" .XX "TransientShell" .XX "widget class, TransientShell" .SH "Name" .Na TransientShell widget class \- popup shell that interacts with the window manager. .Nz .\" .SH "Synopsis" .IP "\s-1\f(HBPublic Headers:\fP\s0" 18n 0 \fI\fP .br \fI\fP .IP "\s-1\f(HBPrivate Header:\fP\s0" 18n 0 \fI\fP .IP "\s-1\f(HBClass\ Name:\fP\s0" 18n 0 TransientShell .IP "\s-1\f(HBClass\ Hierarchy:\fP\s0" 18n 0 'nh Core \(-> Composite \(-> Shell \(-> WMShell \(-> VendorShell \(-> TransientShell .IP "\s-1\f(HBClass Pointer:\fP\s0" 18n 0 \f(CWtransientShellWidgetClass\fP .IP "\s-1\f(HBInstantiation:\fP\s0" 18n 0 .ft CW .ps 9 \f(CIwidget\fP = XtCreatePopupShell(\f(CIname\fP, .br transientShellWidgetClass, ...) .ps 10 .ft R .IP "\s-1\f(HBFunctions/Macros:\fP\s0" 18n 0 \f(CWXtIsTransientShell(\^)\fP .\" .SH "Description" TransientShell is a subclass of VendorShell that is used for popup shell widgets, such as dialog boxes, that don't bypass window management. Most window managers will not allow the user to iconify a TransientShell window on its own, and may iconify it automatically if the window that it is transient for is iconified. If you want a shell that can be iconified, use TopLevelShell. If you want a shell independent of the window manager, use OverrideShell. .\" .SH "New Resources" TransientShell defines the following resources: .br .sp 1 .in 0 .KS .TS expand linesize(2) tab(@); l l l l l lp7 lp7 lp7 lp7 lp7. \fRName@Class@Type@Default@Access\fP .sp .2 .XX "XtNtransientFor" \f(CWXtNtransientFor@XtCTransientFor@Widget@NULL@CSG\fP .sp .2 .TE .KE .in .sp 1 .Nd 3 .IP \f(CWXtNtransientFor\fP 5n .br The widget from which the TransientShell will pop up or some other widget that the TransientShell is logically "transient for." The window of this widget will be stored in the WM_TRANSIENT_FOR property on the TransientShell window, where it can be used by ICCCM-compliant window managers. If the value of this resource is \f(CWNULL\fP or identifies an unrealized widget, then TransientShell uses the value of the WMShell resource \f(CWXtNwindowGroup\fP. .\" .SH "Inherited Resources" TransientShell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. TransientShell sets the resources \f(CWXtNtransient\fP and \f(CWXtNsaveUnder\fP to \f(CWTrue\fP. .Nd 3 .sp 1 .in 0 .KS .TS H tab(@), linesize(2); l l l l lp6w(1.23i) lp6w(1i) lp6w(1.23i) lp6w(1i). \fRResource@Inherited From@Resource@Inherited From\fP .sp 2p .Th \f(CWXtNaccelerators\fP@\f(CWCore\fP@\f(CWXtNmaxHeight\fP@\f(CWWMShell\fP \f(CWXtNallowShellResize\fP@\f(CWShell\fP@\f(CWXtNmaxWidth\fP@\f(CWWMShell\fP \f(CWXtNancestorSensitive\fP@\f(CWCore\fP@\f(CWXtNminAspectX\fP@\f(CWWMShell\fP \f(CWXtNbackground\fP@\f(CWCore\fP@\f(CWXtNminAspectY\fP@\f(CWWMShell\fP \f(CWXtNbackgroundPixmap\fP@\f(CWCore\fP@\f(CWXtNminHeight\fP@\f(CWWMShell\fP \f(CWXtNbaseHeight\fP@\f(CWWMShell\fP@\f(CWXtNminWidth\fP@\f(CWWMShell\fP \f(CWXtNbaseWidth\fP@\f(CWWMShell\fP@\f(CWXtNmwmDecorations\fP@\f(CWVendorShell\fP \f(CWXtNborderColor\fP@\f(CWCore\fP@\f(CWXtNmwmFunctions\fP@\f(CWVendorShell\fP \f(CWXtNborderPixmap\fP@\f(CWCore\fP@\f(CWXtNmwmInputMode\fP@\f(CWVendorShell\fP \f(CWXtNborderWidth\fP@\f(CWCore\fP@\f(CWXtNmwmMenu\fP@\f(CWVendorShell\fP \f(CWXtNchildren\fP@\f(CWComposite\fP@\f(CWXtNnumChildren\fP@\f(CWComposite\fP \f(CWXtNcolormap\fP@\f(CWCore\fP@\f(CWXtNoverrideRedirect\fP@\f(CWShell\fP \f(CWXtNcreatePopupChild-\fP@\f(CWShell\fP@\f(CWXtNpopdownCallback\fP@\f(CWShell\fP .sp -2p \0\0\f(CWProc\fP \f(CWXtNdefaultFontList\fP@\f(CWVendorShell\fP@\f(CWXtNpopupCallback\fP@\f(CWShell\fP \f(CWXtNdeleteResponse\fP@\f(CWVendorShell\fP@\f(CWXtNsaveUnder\fP@\f(CWShell\fP \f(CWXtNdepth\fP@\f(CWCore\fP@\f(CWXtNscreen\fP@\f(CWCore\fP \f(CWXtNdestroyCallback\fP@\f(CWCore\fP@\f(CWXtNsensitive\fP@\f(CWCore\fP \f(CWXtNgeometry\fP@\f(CWShell\fP@\f(CWXtNshellUnitType\fP@\f(CWVendorShell\fP \f(CWXtNheight\fP@\f(CWCore\fP@\f(CWXtNtitle\fP@\f(CWWMShell\fP \f(CWXtNheightInc\fP@\f(CWWMShell\fP@\f(CWXtNtitleEncoding\fP@\f(CWWMShell\fP \f(CWXtNiconMask\fP@\f(CWWMShell\fP@\f(CWXtNtransientFor\fP@\f(CWWMShell\fP \f(CWXtNiconPixmap\fP@\f(CWWMShell\fP@\f(CWXtNtranslations\fP@\f(CWCore\fP \f(CWXtNiconWindow\fP@\f(CWWMShell\fP@\f(CWXtNuseAsyncGeometry\fP@\f(CWVendorShell\fP \f(CWXtNiconX\fP@\f(CWWMShell\fP@\f(CWXtNvisual\fP@\f(CWShell\fP \f(CWXtNiconY\fP@\f(CWWMShell\fP@\f(CWXtNwaitForWm\fP@\f(CWWMShell\fP \f(CWXtNinitialResources-\fP@\f(CWCore\fP@\f(CWXtNwidth\fP@\f(CWCore\fP .sp -2p \0\0\f(CWPersistent\fP \f(CWXtNinitialState\fP@\f(CWWMShell\fP@\f(CWXtNwidthInc\fP@\f(CWWMShell\fP \f(CWXtNinput\fP@\f(CWWMShell\fP@\f(CWXtNwindowGroup\fP@\f(CWWMShell\fP \f(CWXtNinsertPosition\fP@\f(CWComposite\fP@\f(CWXtNwinGravity\fP@\f(CWWMShell\fP \f(CWXtNkeyboardFocusPolicy\fP@\f(CWVendorShell\fP@\f(CWXtNwmTimeout\fP@\f(CWWMShell\fP \f(CWXtNmappedWhenManaged\fP@\f(CWCore\fP@\f(CWXtNx\fP@\f(CWCore\fP \f(CWXtNmaxAspectX\fP@\f(CWWMShell\fP@\f(CWXtNy\fP@\f(CWCore\fP \f(CWXtNmaxAspectY\fP@\f(CWWMShell\fP .sp 2p .TE .KE .in .sp 1 .\" .SH "Class Structure" The TransientShell class structure contains only an extension field: .Ps .ta 5n 2i typedef struct { XtPointer extension; /* pointer to extension record */ } TransientShellClassPart; typedef struct _TransientShellClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ShellClassPart shell_class; WMShellClassPart wm_shell_class; VendorShellClassPart vendor_shell_class; TransientShellClassPart transient_shell_class; } TransientShellClassRec; .Pe There is no extension defined for TransientShell, and the \f(CWextension\fP field should be \f(CWNULL\fP. .\" .SH "Instance Structure" The TransientShell instance structure contains at least the following fields (which need not be in this order): .Ps .ta .5i 3i typedef struct { Widget transient_for; } TransientShellPart; typedef struct { CorePart core; CompositePart composite; ShellPart shell; WMShellPart wm; VendorShellPart vendor; TransientShellPart transient; } TransientShellRec, *TransientShellWidget; .Pe .\" .SH "See Also" \s-1\fIShell\fR\s+1\*(s3 \s-1\fITopLevelShell\fR\s+1\*(s3, \s-1\fIWMShell\fR\s+1\*(s3. .\"last line comment .\" $Header: regexp.3x,v 72.5 94/11/15 09:56:02 ssa Exp $ .TA r .TH regexp 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compile(\|), step(\|), advance(\|) \- regular expression compile and match routines .SH SYNOPSIS .C #define INIT .I "declarations" .br .C #define GETC() .I "getc statements" .br .C #define PEEKC() .I "peekc statements" .br .C #define UNGETC(c) .I "ungetc statements" .br .C #define RETURN(pointer) .I "return statements" .br .C #define ERROR(val) .I "error statements" .PP .C "#include " .PP .C "char *compile(" .nf .PD 0 .IP .C "const char *instring," .C "char *expbuf," .C "const char *endbuf," .C "int eof" .PP .C ");" .PD .fi .PP .C "int step(const char *string, const char *expbuf);" .PP .C "int advance(const char *string, const char *expbuf);" .PP .C "extern char *loc1, *loc2, *locs;" .PP .C "extern int circf, sed, nbra;" .SS Remarks Features documented in this manual entry are obsolescent and may be removed in a future .SM HP-UX release. Use of .IR regcomp (3C) functions instead is recommended. .SH DESCRIPTION These functions are general-purpose regular expression matching routines to be used in programs that perform Basic Regular Expression (see .IR regexp (5)) matching. These functions are defined in .RC < regexp.h >. .PP The functions .C step() and .C advance() do pattern matching given a character string and a compiled regular expression as input. .C compile() takes a Basic Regular Expression as input and produces a compiled expression that can be used with .C step() and .CR advance() . .PP The interface to this file is unpleasantly complex. Programs that include this file must have the following five macros declared before the .C #include statement. These macros are used by the .C compile() routine. .TP 15 .C GETC() Return the value of the next byte in the regular expression pattern. Successive calls to .C GETC() should return successive bytes of the regular expression. .TP .C PEEKC() Return the next byte in the regular expression. Successive calls to .C PEEKC() should return the same byte (which should also be the next byte returned by .CR GETC() . .TP .CI UNGETC( c ) Cause the argument .I c to be returned by the next call to .C GETC() (and .CR PEEKC() ). No more than one byte of pushback is ever needed, and this byte is guaranteed to be the last byte read by .CR GETC() . The value of the macro .CI UNGETC( c ) is always ignored. .TP .CI RETURN( pointer ) This macro is used on normal exit of the .C compile() routine. The value of the argument .I pointer is a pointer to the character after the last character of the compiled regular expression. This is useful to programs that must manage memory allocation. .TP .CI ERROR( val ) This is the abnormal return from the .C compile() routine. The argument .I val is an error number (see table below for meanings). This call should never return. .RS .RS .PD 0 .TP 8 .B Error .B Meaning .TP 11 Range endpoint too large. .TP 16 Bad number. .TP 25 ``\f3\e\f2digit\f1'' out of range. .TP 36 Illegal or missing delimiter. .TP 41 No remembered search string. .TP 42 .C \e( \e) imbalance. .TP 43 Too many .CR \e( . .TP 44 More than 2 numbers given in .CR \e{\0\e} . .TP 45 .C } expected after .CR \e . .TP 46 First number exceeds second in .CR \e{\0\e} . .TP 49 .C [ ] imbalance. .TP 50 Regular expression overflow. .RE .RE .PD .PP The syntax of the .C compile() routine is as follows: .IP .CI compile( instring , .CI expbuf , .CI endbuf , .CI eof ) .PP The first parameter .I instring is never used explicitly by the .C compile() routine, but is useful for programs that pass down different pointers to input characters. It is sometimes used in the .C INIT declaration (see below). Programs that call functions to input characters or have characters in an external array can pass down a value of .C ((char *) 0) for this parameter. .PP The next parameter .I expbuf is a character pointer. It points to the location where the compiled regular expression will be placed. .PP The parameter .I endbuf is one more than the highest address where the compiled regular expression can be placed. If the compiled expression cannot fit in .RI ( endbuf \|\(mi\| expbuf ) bytes, a call to .C ERROR(50) is made. .PP The parameter .I eof is the character which marks the end of the regular expression. For example, in .IR ed (1), this character is usually a .CR / . .PP Each program that includes this file must have a .C #define statement for .CR INIT . This definition is placed right after the declaration for the function .C compile() and the opening curly brace .CR { . It is used for dependent declarations and initializations. Most often it is used to set a register variable to point to the beginning of the regular expression so that this register variable can be used in the declarations for .CR GETC() , .CR PEEKC() , and .CR UNGETC() . Otherwise it can be used to declare external variables that might be used by .CR GETC() , .CR PEEKC() , and .CR UNGETC() . See the example below of the declarations taken from .IR grep (1). .PP .C step() also performs actual regular expression matching in this file. The call to .I step is as follows: .IP .CI step( string , .CI expbuf ) .PP The first parameter to .C step() is a pointer to a string of characters to be checked for a match. This string should be null-terminated. .PP The second parameter .I expbuf is the compiled regular expression that was obtained by a call to .CR compile() . .PP .C step() returns non-zero if the given string matches the regular expression, and zero if the expressions do not match. If there is a match, two external character pointers are set as a side effect to the call to .CR step() . The variable set in .C step() is .CR loc1 . This is a pointer to the first character that matched the regular expression. The variable .CR loc2 , which is set by the function .CR advance() , points to the character after the last character that matches the regular expression. Thus, if the regular expression matches the entire line, .C loc1 points to the first character of .I string and .C loc2 points to the null at the end of .IR string . .PP .C step() uses the external variable .CR circf() , which is set by .C compile() if the regular expression begins with .CR ^ . If this is set, .C step() tries to match the regular expression to the beginning of the string only. If more than one regular expression is to be compiled before the first is executed, the value of .I circf should be saved for each compiled expression and .I circf should be set to that saved value before each call to .CR step() . .PP .C advance() is called from .C step() with the same arguments as .CR step() . The purpose of .C step() is to step through the .I string argument and call .C advance() until .C advance() returns non-zero, which indicates a match, or until the end of .I string is reached. To constrain .I string to beginning-of-line in all cases, .C step() need not be called; simply call .CR advance() . .PP When .C advance() encounters a .C * or .C \e{\|\e} sequence in the regular expression, it advances its pointer to the string to be matched as far as possible and recursively calls itself, trying to match the rest of the string to the rest of the regular expression. As long as there is no match, .I advance backs up along the string until it finds a match or reaches the point in the string that initially matched the .C * or .CR \e{\|\e} . It is sometimes desirable to stop this backing up before the initial point in the string is reached. If the external character pointer .C locs is equal to the point in the string at sometime during the backing up process, .C advance() breaks out of the loop that backs up and returns zero. This is used by .IR ed (1) and .IR sed (1) for substitutions done globally (not just the first occurrence, but the whole line) so, for example, expressions such as .C s/y*//g do not loop forever. .PP The additional external variables .C sed and .C nbra are used for special purposes. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions. .PP The .C LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, and the characters matched by character class expressions in regular expressions. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following is an example of how the regular expression macros and calls look from .IR grep (1): .nf .IP .C "#define INIT register char *sp = instring;" .C "#define GETC() (*sp++)" .C "#define PEEKC() (*sp)" .C "#define UNGETC(c) (--sp)" .C "#define RETURN(c) return;" .C "#define ERROR(c) regerr()" .IP .C "#include " \h'.5i'.\|.\|. .C "(void) compile(*argv, expbuf, &expbuf[ESIZE], '\e0');" \h'.5i'.\|.\|. .C "if (step(linebuf, expbuf))" .C " succeed();" .fi .SH AUTHOR .CR regexp() was developed by OSF and HP. .SH SEE ALSO grep(1), regcomp(3C), setlocale(3C), regexp(5). .SH STANDARDS CONFORMANCE .CR advance() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR compile() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc1 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc2 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR locs ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR step() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4compile()\f1 \- regular expression compile routine@@@\f3regexp(3X)\f1 .\" index@\f4step()\f1 \- regular expression string comparison routine@@@\f3regexp(3X)\f1 .\" index@\f4advance()\f1 \- regular expression substring comparison routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1expression, regular, compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1compile and match routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1comparison routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1match routines for regular expressions@@@\f3regexp(3X)\f1 .\" .\" toc@\f3regexp(3X)\f1:\0\0\f4compile()\f1, \f4step()\f1, \f4advance()\f1@@@regular expression compile and match routines .\" toc@\f4compile()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4step()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4advance()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" .\" links@regexp.3x compile.3x .\" links@regexp.3x step.3x .\" links@regexp.3x advance.3x .\" links@regexp.3x INIT.3x .\" links@regexp.3x GETC.3x .\" links@regexp.3x PEEKC.3x .\" links@regexp.3x UNGETC.3x .\" links@regexp.3x RETURN.3x .\" links@regexp.3x ERROR.3x .\" .\" fileset_database@regexp.3x PROGRAMING-MAN ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH Uil 3X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIUil\fP \- Invokes the UIL compiler from within an application .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf Uil_status_type Uil (\fBcommand_desc, compile_desc, message_cb, message_data, status_cb, status_data\fI) .ta 0.5i 2.5i .nf Uil_command_type \fB*command_desc\fI; Uil_compile_desc_type \fB*compile_desc\fI; Uil_continue_type (\fB*message_cb\fI) (); char \fB*message_data\fI; Uil_continue_type (\fB*status_cb\fI) (); char \fB*status_data\fI; .wH .fi .nL .ne 3i .iE .sE .SH DESCRIPTION .fi The \fIUil\fP function provides a callable entry point for the UIL compiler. The \fIUil\fP callable interface can be used to process a UIL source file and to generate UID files, as well as return a detailed description of the UIL source module in the form of a symbol table (parse tree). .IP "\fBcommand_desc\fP" Specifies the \fIuil\fP command line. .IP "\fBcompile_desc\fP" Returns the results of the compilation. .IP "\fBmessage_cb\fP" Specifies a callback function that is called when the compiler encounters errors in the UIL source. .IP "\fBmessage_data\fP" Specifies user data that is passed to the message callback function (message_cb). Note that this argument is not interpreted by UIL, and is used exclusively by the calling application. .nL .ne 6 .IP "\fBstatus_cb\fP" Specifies a callback function that is called to allow X applications to service X events such as updating the screen. This function is called at various check points, which have been hard coded into the UIL compiler. The status_update_delay argument in command_desc specifies the number of check points to be passed before the status_cb function is invoked. .IP "\fBstatus_data\fP" Specifies user data that is passed to the status callback function (status_cb). Note that this argument is not interpreted by the UIL compiler, and is used exclusively by the calling application. .PP The data structures \fIUil_command_type\fP and \fIUil_compile_desc_type\fP are detailed below. .oS typedef struct Uil_command_type { char *source_file; /* single source to compile */ char *resource_file; /* name of output file */ char *listing_file; /* name of listing file */ unsigned int *include_dir_count; /* number of dirs. in include_dir */ char *((*include_dir) []); /* dir. to search for include files */ unsigned listing_file_flag: 1; /* produce a listing */ unsigned resource_file_flag: 1; /* generate UID output */ unsigned machine_code_flag: 1; /* generate machine code */ unsigned report_info_msg_flag: 1; /* report info messages */ unsigned report_warn_msg_flag: 1; /* report warnings */ unsigned parse_tree_flag: 1; /* generate parse tree */ unsigned int status_update_delay; /* number of times a status point is */ /* passed before calling status_cb */ /* function 0 means called every time */ char *database; /* name of database file */ unsigned database_flag: 1; /* read a new database file */ unsigned use_setlocale_flag: 1; /* enable calls to setlocale */ }; .sp .5 typedef struct Uil_compile_desc_type { unsigned int compiler_version; /* version number of compiler */ unsigned int data_version; /* version number of structures */ char *parse_tree_root; /* parse tree output */ unsigned int message_count [Uil_k_max_status+1]; /* array of severity counts */ }; .oE .PP .ne 3.5i Following is a description of the message callback function specified by \fBmessage_cb\fP: .nL .ne 2i .sS .iS .ta 1i .nf Uil_continue_type (\fB*message_cb\fI) (\fBmessage_data, message_number, severity, msg_buffer, src_buffer, ptr_buffer, loc_buffer, message_count\fI) .ta 0.5i 1.5i .nf char \fB*message_data\fI; int \fBmessage_number\fI; int \fBseverity\fI; char \fB*msg_buffer\fI, \fB*src_buffer\fI; char \fB*ptr_buffer\fI, \fB*loc_buffer\fI; int \fBmessage_count\fI[]; .iE .sE .PP Specifies a callback function that UIL invokes instead of printing an error message when the compiler encounters an error in the UIL source. The callback should return one of these values: .IP "\fIUil_k_terminate\fP" Tells UIL to terminate processing of the source file. .IP "\fIUil_k_continue\fP" Tells UIL to continue processing the source file. .PP .ne 3 Following are the arguments: .IP "\fBmessage_data\fP" Data supplied by the application as the \fBmessage_data\fP argument to the \fIUil\fP function. UIL does not interpret this data in any way; it just passes it to the callback. .IP "\fBmessage_number\fP" An index into a table of error messages and severities, for internal use by UIL. .IP "\fBseverity\fP" An integer that indicates the severity of the error. The possible values are the status constants returned by the \fIUil\fP function. See the "RETURN VALUE" section below. .IP "\fBmsg_buffer\fP" A string that describes the error. .IP "\fBsrc_buffer\fP" A string consisting of the source line where the error occurred. This is not always available; the argument is then NULL. .nL .ne 2i .IP "\fBptr_buffer\fP" A string consisting of whitespace and a printing character in the character position corresponding to the column of the source line where the error occurred. This string may be printed beneath the source line to provide a visual indication of the column where the error occurred. This is not always available; the argument is then NULL. .IP "\fBloc_buffer\fP" A string identifying the line number and file of the source line where the error occurred. This is not always available; the argument is then NULL. .IP "\fBmessage_count\fP" An array of integers containing the number of diagnostic messages issued thus far for each severity level. To find the number of messages issued for the current severity level, use the \fBseverity\fP argument as the index into this array. .PP .ne 7 Following is a description of the status callback function specified by \fBstatus_cb\fP: .nL .ne 2i .sS .iS .ta 1i .nf Uil_continue_type (\fB*status_cb\fI) (\fBstatus_data, percent_complete, lines_processed, current_file, message_count\fI) .ta 0.5i 1.5i .nf char \fB*status_data\fI; int \fBpercent_complete\fI; int \fBlines_processed\fI; char \fB*current_file\fI; int \fBmessage_count\fI[]; .iE .sE .PP Specifies a callback function that is invoked to allow X applications to service X events such as updating the screen. The callback should return one of these values: .IP "\fIUil_k_terminate\fP" Tells UIL to terminate processing of the source file. .IP "\fIUil_k_continue\fP" Tells UIL to continue processing the source file. .PP .ne 2i Following are the arguments: .IP "\fBstatus_data\fP" Data supplied by the application as the \fBstatus_data\fP argument to the \fIUil\fP function. UIL does not interpret this data in any way; it just passes it to the callback. .IP "\fBpercent_complete\fP" An integer indicating what percentage of the current source file has been processed so far. .IP "\fBlines_processed\fP" An integer indicating how many lines of the current source file have been read so far. .IP "\fBcurrent_file\fP" A string containing the pathname of the current source file. .IP "\fBmessage_count\fP" An array of integers containing the number of diagnostic messages issued thus far for each severity level. To find the number of messages issued for a given severity level, use the severity level as the index into this array. The possible severity levels .ne 4 are the status constants returned by the \fIUil\fP function. See the "RETURN VALUE" section below. .SH RETURN VALUE This function returns one of these status return constants: .IP "\fIUil_k_success_status\fP" The operation succeeded. .IP "\fIUil_k_info_status\fP" The operation succeeded, and an informational message is returned. .IP "\fIUil_k_warning_status\fP" The operation succeeded, and a warning message is returned. .IP "\fIUil_k_error_status\fP" The operation failed due to an error. .IP "\fIUil_k_severe_status\fP" The operation failed due to an error. .SH RELATED INFORMATION .na \fIUilDumpSymbolTable(3X)\fP and \fIuil(1X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH UilDumpSymbolTable 3X .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIUilDumpSymbolTable\fP \- Dumps the contents of a named UIL symbol table to standard output .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void UilDumpSymbolTable (\fBroot_ptr\fI) .ta 0.5i 2.5i .nf sym_entry_type *\fBroot_ptr\fI; .iE .sE .SH DESCRIPTION .fi .PP The \fIUilDumpSymbolTable\fP function dumps the contents of a UIL symbol table pointer to standard output. .IP "\fBroot_ptr\fP" Specifies a pointer to the the symbol table root entry. This value can be taken from the \fIparse_tree_root\fP part of the \fIUil_compile_desc_type\fP data structure returned by \fIUil\fP. .PP .ne 20 By following the link from the root entry, you can traverse the entire parse tree. Symbol table entries are in the following format: .PP \fBhex.address\fP .nL \fBsymbol.type\fP .nL \fBsymbol.data\fP .nL \fBprev.source.position\fP .nL \fBsource.position\fP .nL \fBmodification.record\fP .PP where: .IP "\fBhex.address\fP" Specifies the hexadecimal address of this entry in the symbol table. .IP "\fBsymbol.type\fP" Specifies the type of this symbol table entry. Some possible types are \fIroot\fP, \fImodule\fP, \fIvalue\fP, \fIprocedure\fP, and \fIwidget\fP. .IP "\fBsymbol.data\fP" Specifies data for the symbol table entry. The data varies with the type of the entry. Often it contains pointers to other symbol table entries, or the actual data for the data type. .IP "\fBprev.source.position\fP" Specifies the end point in the source code for the previous source item. .IP "\fBsource.position\fP" Specifies the range of positions in the source code for this symbol. .PP The exact data structures for each symbol type are defined in the include file \fIUilSymDef.h\fP. Note that this file is automatically included when an application includes the file \fIUilDef.h\fP. .SH RELATED INFORMATION .na \fIUil(3X)\fP .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH VendorShell 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIVendorShell\fP \- The VendorShell widget class .SH SYNOPSIS .nf .sS .iS \&#include \&#include .iE .sE .SH DESCRIPTION .fi VendorShell is a Motif widget class used as a supporting superclass for all shell classes that are visible to the window manager and that are not override redirect. It contains resources that describe the MWM-specific look and feel. It also manages the MWM-specific communication needed by all VendorShell subclasses. See the \fImwm\fP(1X) man page for more information. .P If an application uses the \fIXmNmwmDecorations\fP, \fIXmNmwmFunctions\fP, or \fIXmNmwmInputMode\fP resource, it should include the file \fI\fP. .PP Setting \fIXmNheight\fP, \fIXmNwidth\fP, or \fIXmNborderWidth\fP for either a VendorShell or its managed child usually sets that resource to the same value in both the parent and the child. When an off-the-spot input method exists, the height and width of the shell may be greater than those of the managed child in order to accommodate the input method. In this case setting \fIXmNheight\fP or \fIXmNwidth\fP for the shell does not necessarily set that resource to the same value in the managed child, and setting \fIXmNheight\fP or \fIXmNwidth\fP for the child does not necessarily set that resource to the same value in the shell. .PP For the managed child of a VendorShell, regardless of the value of the shell's \fIXmNallowShellResize\fP, setting \fIXmNx\fP or \fIXmNy\fP sets the corresponding resource of the parent but does not change the child's position relative to the parent. \fIXtGetValues\fP for the child's \fIXmNx\fP or \fIXmNy\fP yields the value of the corresponding resource in the parent. The \fBx\fP and \fBy\fP coordinates of the child's upper left outside corner relative to the parent's upper left inside corner are both zero minus the value of \fIXmNborderWidth\fP. .PP Note that the \fBInter-Client Communication Conventions Manual\fP allows a window manager to change or control the border width of a reparented top-level window. .SS "Classes" VendorShell inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIShell\fP, and \fIWMShell\fP classes. .PP The class pointer is \fIvendorShellWidgetClass\fP. .PP The class name is \fIVendorShell\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a subresource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a subresource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given subresource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. VendorShell Resource Set Name Class Type Default Access _ XmNaudibleWarning XmCAudibleWarning unsigned char XmBELL CSG XmNbuttonFontList XmCButtonFontList XmFontList dynamic CSG XmNdefaultFontList XmCDefaultFontList XmFontList dynamic CG XmNdeleteResponse XmCDeleteResponse unsigned char XmDESTROY CSG XmNinputMethod XmCInputMethod String NULL CSG XmNkeyboardFocusPolicy XmCKeyboardFocusPolicy unsigned char XmEXPLICIT CSG XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG XmNmwmDecorations XmCMwmDecorations int -1 CSG XmNmwmFunctions XmCMwmFunctions int -1 CSG XmNmwmInputMode XmCMwmInputMode int -1 CSG XmNmwmMenu XmCMwmMenu String NULL CSG XmNpreeditType XmCPreeditType String dynamic CSG XmNshellUnitType XmCShellUnitType unsigned char XmPIXELS CSG XmNtextFontList XmCTextFontList XmFontList dynamic CSG XmNuseAsyncGeometry XmCUseAsyncGeometry Boolean False CSG .TE .KE .in .sp 1 .IP "\fIXmNaudibleWarning\fP" Determines whether an action activates its associated audible cue. The possible values are: \fIXmBELL\fP and \fIXmNONE\fP. .IP "\fIXmNbuttonFontList\fP" Specifies the font list used for VendorShell's button descendants. If this value is NULL at initialization and if the value of \fIXmNdefaultFontList\fP is not NULL, \fIXmNbuttonFontList\fP is initialized to the value of \fIXmNdefaultFontList\fP. If the value of \fIXmNdefaultFontList\fP is NULL, \fIXmNbuttonFontList\fP is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard, VendorShell, or XmMenuShell widget class. If such an ancestor is found, \fIXmNbuttonFontList\fP is initialized to the \fIXmNbuttonFontList\fP of the ancestor widget. If no such ancestor is found, the default is implementation dependent. .IP "\fIXmNdefaultFontList\fP" Specifies a default font list for VendorShell's descendants. This resource is obsolete and exists for compatibility with earlier releases. It has been replaced by \fIXmNbuttonFontList\fP, \fIXmNlabelFontList\fP, and \fIXmNtextFontList\fP. .IP "\fIXmNdeleteResponse\fP" Determines what action the shell takes in response to a \fIWM_DELETE_WINDOW\fP message. The setting can be one of three values: \fIXmDESTROY\fP, \fIXmUNMAP\fP, and \fIXmDO_NOTHING\fP. The resource is scanned, and the appropriate action is taken, after the \fIWM_DELETE_WINDOW\fP callback list (if any) that is registered with the Protocol manager has been called. .IP "\fIXmNinputMethod\fP" Specifies the string that sets the locale modifier for the input method. .IP "\fIXmNkeyboardFocusPolicy\fP" Determines allocation of keyboard focus within the widget hierarchy rooted at this shell. The X keyboard focus must be directed to somewhere in the hierarchy for this client-side focus management to take effect. Possible values are \fIXmEXPLICIT\fP, specifying a click-to-type policy, and \fIXmPOINTER\fP, specifying a pointer-driven policy. .IP "\fIXmNlabelFontList\fP" Specifies the font list used for VendorShell's label descendants (Labels and LabelGadgets). If this value is NULL at initialization and if the value of \fIXmNdefaultFontList\fP is not NULL, \fIXmNlabelFontList\fP is initialized to the value of \fIXmNdefaultFontList\fP. If the value of \fIXmNdefaultFontList\fP is NULL, \fIXmNlabelFontList\fP is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard, VendorShell, or XmMenuShell widget class. If such an ancestor is found, \fIXmNlabelFontList\fP is initialized to the \fIXmNlabelFontList\fP of the ancestor widget. If no such ancestor is found, the default is implementation dependent. .IP "\fIXmNmwmDecorations\fP" Specifies the decoration flags (specific decorations to add or remove from the window manager frame) for the \fI_MOTIF_WM_HINTS\fP property. If any decoration flags are specified by the \fI_MOTIF_WM_HINTS\fP property, only decorations indicated by both that property and the MWM \fIclientDecoration\fP and \fItransientDecoration\fP resources are displayed. If no decoration flags are specified by the \fI_MOTIF_WM_HINTS\fP property, decorations indicated by the MWM \fIclientDecoration\fP and \fItransientDecoration\fP resources are displayed. The default for the \fIXmNmwmDecorations\fP resource is not to specify any decoration flags for the \fI_MOTIF_WM_HINTS\fP property. .P The value of this resource is the bitwise inclusive OR of one or more flag bits. Following are the possible flag bit constants, defined in the include file \fI\fP: .TP \(bu \fIMWM_DECOR_ALL\fP \- All decorations \*Eexcept\fP those specified by other flag bits that are set .TP \(bu \fIMWM_DECOR_BORDER\fP \- Client window border .TP \(bu \fIMWM_DECOR_RESIZEH\fP \- Resize frame handles .TP \(bu \fIMWM_DECOR_TITLE\fP \- Title bar .TP \(bu \fIMWM_DECOR_MENU\fP \- Window menu button .TP \(bu \fIMWM_DECOR_MINIMIZE\fP \- Minimize window button .TP \(bu \fIMWM_DECOR_MAXIMIZE\fP \- Maximize window button .IP "\fIXmNmwmFunctions\fP" Specifies the function flags (specific window manager functions to apply or not apply to the client window) for the \fI_MOTIF_WM_HINTS\fP property. If any function flags are specified by the \fI_MOTIF_WM_HINTS\fP property, only functions indicated by both that property and the MWM \fIclientFunctions\fP and \fItransientFunctions\fP resources are applied. If no function flags are specified by the \fI_MOTIF_WM_HINTS\fP property, functions indicated by the MWM \fIclientFunctions\fP and \fItransientFunctions\fP resources are applied. The default for the \fIXmNmwmFunctions\fP resource is not to specify any function flags for the \fI_MOTIF_WM_HINTS\fP property. .P The value of this resource is the bitwise inclusive OR of one or more flag bits. Following are the possible flag bit constants, defined in the include file \fI\fP: .TP \(bu \fIMWM_FUNC_ALL\fP \- All functions \*Eexcept\fP those specified by other flag bits that are set .TP \(bu \fIMWM_FUNC_RESIZE\fP \- \fIf.resize\fP .TP \(bu \fIMWM_FUNC_MOVE\fP \- \fIf.move\fP .TP \(bu \fIMWM_FUNC_MINIMIZE\fP \- \fIf.minimize\fP .TP \(bu \fIMWM_FUNC_MAXIMIZE\fP \- \fIf.maximize\fP .TP \(bu \fIMWM_FUNC_CLOSE\fP \- \fIf.kill\fP .IP "\fIXmNmwmInputMode\fP" Specifies the input mode flag (application modal or system modal input constraints) for the \fI_MOTIF_WM_HINTS\fP property. If no input mode flag is specified by the \fI_MOTIF_WM_HINTS\fP property, no input constraints are applied, and input goes to any window. The default for the \fIXmNmwmInputMode\fP resource is not to specify any input mode flag for the \fI_MOTIF_WM_HINTS\fP property. .P An application that sets input constraints on a dialog usually uses the BulletinBoard's \fIXmNdialogStyle\fP resource rather than the parent DialogShell's \fIXmNmwmInputMode\fP resource. .P Following are the possible values for this resource, defined in the include file \fI\fP: .TP \(bu \fIMWM_INPUT_MODELESS\fP \- Input goes to any window .TP \(bu \fIMWM_INPUT_PRIMARY_APPLICATION_MODAL\fP \- Input does not go to ancestors of this window .TP \(bu \fIMWM_INPUT_SYSTEM_MODAL\fP \- Input goes only to this window .TP \(bu \fIMWM_INPUT_FULL_APPLICATION_MODAL\fP \- Input does not go to other windows in this application .IP "\fIXmNmwmMenu\fP" Specifies the menu items that the Motif window manager should add to the end of the window menu. The string contains a list of items separated by \*C\en\fP with the following format: .PP \fBlabel [mnemonic] [accelerator] function\fP .PP If more than one item is specified, the items should be separated by a newline character. .IP "\fIXmNpreeditType\fP" Specifies the input method style or styles available to the input manager. The syntax, possible values, and default value are implementation dependent. .cS If more than one style is specified, the list is in priority order. The input manager uses the first style if it is available; if not, it uses the second style, and so on. The supported input method styles are: .IP "OverTheSpot" The pre-edit window is located over the point of insertion. .IP "OffTheSpot" The pre-edit window is not located over the point of insertion. In this case, the pre-edit window is often located at the bottom of the application window. .IP "Root" The pre-edit window is a child of the root window. .PP If no input method style in this list is available, the input manager can support another input style method, but only if it does not require geometry management or any additional supporting information. .PP The Xlib XIMStyles data structure stores preedit information that describes the requirements for a given input method style. The three styles identified by \fIXmNpreeditType\fP are related to the preedit settings in an XIMStyles structure. The input styles, "OverTheSpot", "OffTheSpot" and "Root", correspond respectively to the settings XIMPreEditPosition, XIMPreEditArea, and XIMPreEditNothing. .cE .IP "\fIXmNshellUnitType\fP" Determines geometric resource interpretation. The following values are allowed: .wH .rS .TP \(bu \fIXmPIXELS\fP \- all values provided to the widget are treated as normal pixel values. .TP \(bu \fIXm100TH_MILLIMETERS\fP \- all values provided to the widget are treated as 1/100 millimeter. .TP \(bu \fIXm1000TH_INCHES\fP \- all values provided to the widget are treated as 1/1000 inch. .TP \(bu \fIXm100TH_POINTS\fP \- all values provided to the widget are treated as 1/100 point. A point is a unit used in text processing applications and is defined as 1/72 inch. .TP \(bu \fIXm100TH_FONT_UNITS\fP \- all values provided to the widget are treated as 1/100 of a font unit. A font unit has horizontal and vertical components. These are the values of the XmScreen resources \fIXmNhorizontalFontUnit\fP and \fIXmNverticalFontUnit\fP. .IP "\fIXmNtextFontList\fP" Specifies the font list used for VendorShell's Text and List descendants. If this value is NULL at initialization and if the value of \fIXmNdefaultFontList\fP is not NULL, \fIXmNtextFontList\fP is initialized to the value of \fIXmNdefaultFontList\fP. If the value of \fIXmNdefaultFontList\fP is NULL, \fIXmNtextFontList\fP is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard or VendorShell widget class. If such an ancestor is found, \fIXmNtextFontList\fP is initialized to the \fIXmNtextFontList\fP of the ancestor widget. If no such ancestor is found, the default is implementation dependent. .IP "\fIXmNuseAsyncGeometry\fP" Specifies whether the geometry manager should wait for confirmation of a geometry request to the window manager. When the value of this resource is True, the geometry manager forces \fIXmNwaitForWm\fP to False and \fIXmNwmTimeout\fP to 0, and it relies on asynchronous notification. When the value of this resource is False, \fIXmNwaitForWm\fP and \fIXmNwmTimeout\fP are unaffected. The default is False. .SS "Inherited Resources" VendorShell inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. WMShell Resource Set Name Class Type Default Access _ XmNbaseHeight XmCBaseHeight int XtUnspecifiedShellInt CSG XmNbaseWidth XmCBaseWidth int XtUnspecifiedShellInt CSG XmNheightInc XmCHeightInc int XtUnspecifiedShellInt CSG XmNiconMask XmCIconMask Pixmap NULL CSG XmNiconPixmap XmCIconPixmap Pixmap NULL CSG XmNiconWindow XmCIconWindow Window NULL CSG XmNiconX XmCIconX int \-1 CSG XmNiconY XmCIconY int \-1 CSG XmNinitialState XmCInitialState int NormalState CSG XmNinput XmCInput Boolean True CSG XmNmaxAspectX XmCMaxAspectX int XtUnspecifiedShellInt CSG XmNmaxAspectY XmCMaxAspectY int XtUnspecifiedShellInt CSG XmNmaxHeight XmCMaxHeight int XtUnspecifiedShellInt CSG XmNmaxWidth XmCMaxWidth int XtUnspecifiedShellInt CSG .wH .tH XmNminAspectX XmCMinAspectX int XtUnspecifiedShellInt CSG XmNminAspectY XmCMinAspectY int XtUnspecifiedShellInt CSG XmNminHeight XmCMinHeight int XtUnspecifiedShellInt CSG XmNminWidth XmCMinWidth int XtUnspecifiedShellInt CSG XmNtitle XmCTitle String dynamic CSG XmNtitleEncoding XmCTitleEncoding Atom dynamic CSG XmNtransient XmCTransient Boolean False CSG XmNwaitForWm XmCWaitForWm Boolean True CSG XmNwidthInc XmCWidthInc int XtUnspecifiedShellInt CSG XmNwindowGroup XmCWindowGroup Window dynamic CSG XmNwinGravity XmCWinGravity int dynamic CSG XmNwmTimeout XmCWmTimeout int 5000 ms CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Shell Resource Set Name Class Type Default Access _ XmNallowShellResize XmCAllowShellResize Boolean False CG XmNcreatePopupChildProc XmCCreatePopupChildProc XtCreatePopupChildProc NULL CSG XmNgeometry XmCGeometry String NULL CSG XmNoverrideRedirect XmCOverrideRedirect Boolean False CSG XmNpopdownCallback XmCCallback XtCallbackList NULL C XmNpopupCallback XmCCallback XtCallbackList NULL C XmNsaveUnder XmCSaveUnder Boolean False CSG XmNvisual XmCVisual Visual * CopyFromParent CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 1 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Translations" There are no translations for VendorShell. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fICore(3X)\fP, \fImwm(1X)\fP, \fIShell(3X)\fP, \fIWMShell(3X)\fP, \fIXmActivateProtocol(3X)\fP, \fIXmActivateWMProtocol(3X)\fP, \fIXmAddProtocolCallback(3X)\fP, \fIXmAddWMProtocolCallback(3X)\fP, \fIXmAddProtocols(3X)\fP, \fIXmAddWMProtocols(3X)\fP, \fIXmDeactivateProtocol(3X)\fP, \fIXmDeactivateWMProtocol(3X)\fP, \fIXmGetAtomName(3X)\fP, \fIXmInternAtom(3X)\fP, \fIXmIsMotifWMRunning(3X)\fP, \fIXmRemoveProtocolCallback(3X)\fP, \fIXmRemoveWMProtocolCallback(3X)\fP, \fIXmRemoveProtocols(3X)\fP, \fIXmRemoveWMProtocols(3X)\fP, \fIXmScreen(3X)\fP, \fIXmSetProtocolHooks(3X)\fP, and \fIXmSetWMProtocolHooks(3X)\fP. .ad .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "VendorShell" "Intrinsics Classes" .XX "VendorShell" .XX "widget class, VendorShell" .SH "Name" VendorShell widget class \- shell widget class for vendor-specific hooks for interaction with custom window managers. .\" .SH "Synopsis" .IP "\s-1\f(HBPublic Headers:\fP\s0" 18n 0 \fI\fP .br \fI\fP .IP "\s-1\f(HBPrivate Header:\fP\s0" 18n 0 \fI\fP .IP "\s-1\f(HBClass\ Name:\fP\s0" 18n 0 VendorShell .IP "\s-1\f(HBClass\ Hierarchy:\fP\s0" 18n 0 'nh Core \(-> Composite \(-> Shell \(-> WMShell \(-> VendorShell .IP "\s-1\f(HBClass Pointer:\fP\s0" 18n 0 \f(CWvendorShellWidgetClass\fP .IP "\s-1\f(HBInstantiation:\fP\s0" 18n 0 VendorShell is an Intrinsics meta-class, and is not normally instantiated. .IP "\s-1\f(HBFunctions/Macros:\fP\s0" 18n 0 \f(CWXmIsVendorShell(\^)\fP .\" .SH "Description" VendorShell is a subclass of WMShell that allows software vendors to provide hooks (class methods, resources, etc.) to support their custom window managers. As shipped by MIT, VendorShell defines no new class or instance fields, nor any resources. Vendors may implement a different VendorShell and ship that. Applications linked with this custom VendorShell will be able to interact specially with the custom window manager. .LP The Motif widget set contains a custom VendorShell which provides a number of resources not documented here. See Volume 6B, \fIMotif Reference Manual\fP for more information on that VendorShell widget. .\" .SH "New Resources" VendorShell defines no new resources. .\" .SH "Inherited Resources" VendorShell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. .Nd 3 .sp 1 .in 0 .KS .TS H tab(@), linesize(2); lp7 lp7 lp7 lp7 lp6w(1.25i) lp6w(1i) lp6w(1.25i) lp6w(1i). \fRResource@Inherited From@Resource@Inherited From\fP .sp 2p .Th \f(CWXtNaccelerators\fP@\f(CWCore\fP@\f(CWXtNmaxAspectX\fP@\f(CWWMShell\fP \f(CWXtNallowShellResize\fP@\f(CWShell\fP@\f(CWXtNmaxAspectY\fP@\f(CWWMShell\fP \f(CWXtNancestorSensitive\fP@\f(CWCore\fP@\f(CWXtNmaxHeight\fP@\f(CWWMShell\fP \f(CWXtNbackground\fP@\f(CWCore\fP@\f(CWXtNmaxWidth\fP@\f(CWWMShell\fP \f(CWXtNbackgroundPixmap\fP@\f(CWCore\fP@\f(CWXtNminAspectX\fP@\f(CWWMShell\fP \f(CWXtNbaseHeight\fP@\f(CWWMShell\fP@\f(CWXtNminAspectY\fP@\f(CWWMShell\fP \f(CWXtNbaseWidth\fP@\f(CWWMShell\fP@\f(CWXtNminHeight\fP@\f(CWWMShell\fP \f(CWXtNborderColor\fP@\f(CWCore\fP@\f(CWXtNminWidth\fP@\f(CWWMShell\fP \f(CWXtNborderPixmap\fP@\f(CWCore\fP@\f(CWXtNnumChildren\fP@\f(CWComposite\fP \f(CWXtNborderWidth\fP@\f(CWCore\fP@\f(CWXtNoverrideRedirect\fP@\f(CWShell\fP \f(CWXtNchildren\fP@\f(CWComposite\fP@\f(CWXtNpopdownCallback\fP@\f(CWShell\fP \f(CWXtNcolormap\fP@\f(CWCore\fP@\f(CWXtNpopupCallback\fP@\f(CWShell\fP \f(CWXtNcreatePopupChild-\fP@\f(CWShell\fP@\f(CWXtNsaveUnder\fP@\f(CWShell\fP .sp -2p \0\0\f(CWProc\fP \f(CWXtNdepth\fP@\f(CWCore\fP@\f(CWXtNscreen\fP@\f(CWCore\fP \f(CWXtNdestroyCallback\fP@\f(CWCore\fP@\f(CWXtNsensitive\fP@\f(CWCore\fP \f(CWXtNgeometry\fP@\f(CWShell\fP@\f(CWXtNtitle\fP@\f(CWWMShell\fP \f(CWXtNheight\fP@\f(CWCore\fP@\f(CWXtNtitleEncoding\fP@\f(CWWMShell\fP \f(CWXtNheightInc\fP@\f(CWWMShell\fP@\f(CWXtNtransient\fP@\f(CWWMShell\fP \f(CWXtNiconMask\fP@\f(CWWMShell\fP@\f(CWXtNtranslations\fP@\f(CWCore\fP \f(CWXtNiconPixmap\fP@\f(CWWMShell\fP@\f(CWXtNvisual\fP@\f(CWShell\fP \f(CWXtNiconWindow\fP@\f(CWWMShell\fP@\f(CWXtNwaitForWm\fP@\f(CWWMShell\fP \f(CWXtNiconX\fP@\f(CWWMShell\fP@\f(CWXtNwidth\fP@\f(CWCore\fP \f(CWXtNiconY\fP@\f(CWWMShell\fP@\f(CWXtNwidthInc\fP@\f(CWWMShell\fP \f(CWXtNinitialResources-\fP@\f(CWCore\fP@\f(CWXtNwindowGroup\fP@\f(CWWMShell\fP .sp -2p \0\0\f(CWPersistent\fP \f(CWXtNinitialState\fP@\f(CWWMShell\fP@\f(CWXtNwinGravity\fP@\f(CWWMShell\fP \f(CWXtNinput\fP@\f(CWWMShell\fP@\f(CWXtNwmTimeout\fP@\f(CWWMShell\fP \f(CWXtNinsertPosition\fP@\f(CWComposite\fP@\f(CWXtNx\fP@\f(CWCore\fP \f(CWXtNmappedWhenManaged\fP@\f(CWCore\fP@\f(CWXtNy\fP@\f(CWCore\fP .sp 2p .TE .KE .in .sp 1 .\" .SH "Class Structure" The VendorShell class structure contains only an extension field: .Ps .ta 5n 2i typedef struct { XtPointer extension; /* pointer to extension record */ } VendorShellClassPart; typedef struct _VendorShellClassRec { CoreClassPart core_class; CompositeClassPart composite_class; ShellClassPart shell_class; WMShellClassPart wm_shell_class; VendorShellClassPart vendor_shell_class; } VendorShellClassRec; .Pe There is not an extension defined for VendorShell (as shipped by MIT) and the \f(CWextension\fP field should be \f(CWNULL\fP. .\" .SH "Instance Structure" The VendorShell instance structure (as shipped by MIT) is defined as follows: .Ps .ta 5n 2i typedef struct { int vendor_specific; } VendorShellPart;. typedef struct { CorePart core; CompositePart composite; ShellPart shell; WMShellPart wm; VendorShellPart vendor; } VendorShellRec, *VendorShellWidget; .Pe .\" .SH "See Also" \s-1\fIShell\fR\s+1\*(s3. .\"last line comment ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH VirtualBindings 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIVirtualBindings\fP \- Bindings for virtual mouse and key events .SH DESCRIPTION .fi The 1/Motif manual pages describe translations in terms of \fBvirtual bindings\fP, based on those described in the \fBOSF/Motif Style Guide\fP. Mouse events are described in terms of \fBvirtual buttons\fP, and key events are described in terms of \fBvirtual keys\fP. The term \fBvirtual\fP implies that the events as described do not necessarily correspond to a fixed set of X Window System events. Instead, virtual buttons and keys are linked to actual events by means of virtual bindings. .SS "Virtual Modifiers" Both virtual buttons and virtual keys may contain \fBvirtual modifiers\fP. Each virtual modifier corresponds to one or more actual modifiers. The following table lists the bindings of virtual modifiers to actual modifiers in 1/Motif: .PP .sp 1 .in 0 .KS .TS tab(@) center; cb s lb lb. Virtual Modifier Bindings Virtual Modifier@Actual Modifiers _ MAlt@Mod1 MCopy@Ctrl MCtrl@Ctrl MLink@Ctrl Shift MMove@Shift MShift@Shift .TE .KE .in .sp 1 .PP \fIMod1\fP refers to the first modifier key. 1/Motif requires that it correspond to either \fIAlt\fP or \fIMeta\fP. .PP The virtual modifier \fIMAny\fP indicates that any modifier can be used. If \fIMAny\fP is not specified and the user presses an actual modifier that is not explicitly included in a translation, that modifier may prevent the translation from being matched. .SS "Virtual Buttons" Each virtual button corresponds to one or more actual button event descriptions. Each button event description contains a button name and possibly modifiers. These button event descriptions, appropriately ordered and possibly further modified, are used in translation tables. The following table lists the bindings of virtual buttons to actual button event descriptions in 1/Motif: .PP .sp 1 .in 0 .KS .TS tab(@) center; cb s lb lb. Virtual Button Bindings Virtual Button@Actual Button Events _ BCustom@ BDrag@ BExtend@Shift BMenu@ BSelect@ BToggle@Ctrl .TE .KE .in .sp 1 .SS "Virtual Keys" Each virtual key corresponds to one or more actual key event descriptions. Each key event description contains a keysym name and possibly modifiers. These key event descriptions, appropriately ordered and possibly further modified, .ne 15 are used in translation tables. The following table lists the bindings of virtual keys to actual key event descriptions in 1/Motif: .PP .sp 1 .in 0 .KS .TS tab(@) center; cb s lb | lb. Virtual Key Bindings _ Virtual Key@Actual Key Events = KActivate@Return @CtrlReturn @osfActivate _ KAddMode@osfAddMode _ KBackSpace@osfBackSpace _ KBackTab@ShiftTab _ KBeginData@CtrlosfBeginLine _ KBeginLine@osfBeginLine _ KCancel@osfCancel _ KClear@osfClear _ KCopy@osfCopy @CtrlosfInsert _ KCut@osfCut @ShiftosfDelete _ KDelete@osfDelete _ KDeselectAll@Ctrlbackslash _ KDown@osfDown _ KEndData@CtrlosfEndLine _ KEndLine@osfEndLine _ KEnter@Return _ KEscape@Escape _ KExtend@Ctrl Shiftspace @ShiftosfSelect _ KHelp@osfHelp _ KInsert@osfInsert _ .TE .KE .in .sp 1 .nL .ne 40 .sp 1 .in 0 .KS .TS tab(@) center; cb s lb | lb. Virtual Key Bindings (Continued) _ Virtual Key@Actual Key Events = KLeft@osfLeft _ KMenu@osfMenu _ KMenuBar@osfMenuBar _ KNextField@Tab @CtrlTab _ KNextMenu@CtrlosfDown @CtrlosfRight _ KPageDown@osfPageDown _ KPageLeft@CtrlosfPageUp @osfPageLeft _ KPageRight@CtrlosfPageDown @osfPageRight _ KPageUp@osfPageUp _ KPaste@osfPaste @ShiftosfInsert _ KPrevField@ShiftTab @Ctrl ShiftTab _ KPrevMenu@CtrlosfUp @CtrlosfLeft _ KPrimaryCopy@CtrlosfPrimaryPaste @Mod1osfCopy @Mod1 CtrlosfInsert _ KPrimaryCut@Mod1osfPrimaryPaste @Mod1osfCut @Mod1 ShiftosfDelete _ KPrimaryPaste@osfPrimaryPaste _ KQuickCopy@CtrlosfQuickPaste _ KQuickCut@Mod1osfQuickPaste _ KQuickExtend@ShiftosfQuickPaste _ .TE .KE .in .sp 1 .nL .ne 20 .sp 1 .in 0 .KS .TS tab(@) center; cb s lb | lb. Virtual Key Bindings (Continued) _ Virtual Key@Actual Key Events = KQuickPaste@osfQuickPaste _ KReselect@Ctrl ShiftosfSelect _ KRestore@Ctrl ShiftosfInsert _ KRight@osfRight _ KSelect@space @Ctrlspace @osfSelect _ KSelectAll@Ctrlslash _ KSpace@space _ KTab@Tab _ KUndo@osfUndo @Mod1osfBackSpace _ KUp@osfUp _ KAny@ _ .TE .KE .in .sp 1 .SS "Bindings for osf Keysyms" Keysym strings that begin with "osf" are not part of the X server's keyboard mapping. Instead, these keysyms are produced on the client side at run time. They are interpreted by the routine \fIXmTranslateKey\fP, and are used by the translation manager when the server delivers an actual key event. For each application, a mapping is maintained between "osf" keysyms and keysyms that correspond to actual keys. This mapping is based on information obtained at application startup from one of the following sources, listed in order of precedence: .TP \(bu A \fIdefaultVirtualBindings\fP application resource in the resource database. .TP \(bu A property on the root window, which can be set by \fImwm\fP on startup, or by the \fIxmbind\fP client, or on prior startup of a Motif application. .TP \(bu The file \fI\&.motifbind\fP in the user's home directory. .TP \(bu A set of bindings based on the vendor string and optionally the vendor release of the X server. Motif searches for these bindings in the following steps: .TP \(bu If the file \fIxmbind.alias\fP exists in the user's home directory, Motif searches this file for a pathname associated with the vendor string or with the vendor string and vendor release. If it finds such a pathname and if that file exists, Motif loads the bindings contained in that file. .TP \(bu If it has found no bindings, Motif next looks for the file \fIxmbind.alias\fP in the directory specified by the environment variable \fIXMBINDDIR\fP, if \fIXMBINDDIR\fP is set, or in the directory \fI/usr/lib/Xm/bindings\fP if \fIXMBINDDIR\fP is not set. If this file exists Motif searches it for a pathname associated with the vendor string or with the vendor string and vendor release. If it finds such a pathname and if that file exists, Motif loads the bindings contained in that file. .TP \(bu If it still has found no bindings, Motif loads a set of hard-coded fallback bindings. .LE .PP The \fIxmbind.alias\fP file contains zero or more lines of the form: .PP .na .wH .in +3n .ta 1.75i .nf "\fBvendor_string\fP[ \fBvendor_release\fP]" \fBbindings_file\fP .wH .in .ad .PP where \fBvendor_string\fP is the X server vendor name as returned by the X client \fIxdpyinfo\fP or the Xlib function \fIXServerVendor\fP, and must appear in double quotes. If \fBvendor_release\fP is included, it is the X server vendor release number as returned by the X client \fIxdpyinfo\fP or the Xlib function \fIXVendorRelease\fP, and must also be contained within the double quotes separated by one space from \fBvendor_string\fP. \fBvendor_release\fP is provided to allow support of changes in keyboard hardware from a vendor, assuming that the vendor increments the release number to flag such changes. Alternatively, the vendor may simply use a unique vendor string for each different keyboard. .PP \fBbindings_file\fP is the pathname of the file containing the bindings themselves. It can be a relative or absolute pathname. If it it is a relative pathname, it is relative to the location of the \fIxmbind.alias\fP file. .PP Comment lines in the \fIxmbind.alias\fP file begin with \fI!\fP. .PP The bindings found in either the \fI\&.motifbind\fP file or the vendor mapping are placed in a property on the root window. This property is used to determine the bindings for subsequent Motif applications. .PP On startup \fImwm\fP attempts to load the file \fI\&.motifbind\fP in the user's home directory. If this is unsuccessful, it loads the vendor bindings as described above. It places the bindings it loads in a property on the root window for use by subsequent Motif applications. .PP \fIxmbind\fP loads bindings from a file if that file is specified on the command line. If no file is specified on the command line, it attempts to load the file \fI\&.motifbind\fP in the user's home directory. If this fails, it loads the vendor bindings as described above. It places the bindings it loads in a property on the root window for use by subsequent Motif applications. .PP The format of the specification for mapping "osf" keysyms to actual keysyms is similar to that of a specification for an event translation. The syntax is specified here in EBNF notation using the following conventions: .PP .wH .in +3n .na .ta 1i .nf [\fBa\fP] Means either nothing or \fBa\fP .nL {\fBa\fP} Means zero or more occurrences of \fBa\fP .ad .wH .in .PP Terminals are enclosed in double quotation marks. .PP The syntax of an "osf" keysym binding specification is as follows: .PP .wH .in +3n .na .ta 1.5i 1.75i .nf binding_spec = {line "\en"} [line] .nL line = virtual_keysym ":" key_event .nL key_event = {modifier_name} "" actual_keysym .nL virtual_keysym = keysym .nL actual_keysym = keysym .nL keysym = A valid X11 keysym name that is .nL mapped by \fIXStringToKeysym\fP .ad .wH .in .PP As with event translations, more specific event descriptions must precede less specific descriptions. For example, an event description for a key with a modifier must precede a description for the same key without the same modifier. .PP Following is an example of a specification for the \fIdefaultVirtualBindings\fP resource in a resource file: .wH .in +3n .oS .ta 0.5i 2i 2.5i 3.75i .nf *defaultVirtualBindings: \e osfBackSpace : BackSpace \en\e osfInsert : InsertChar \en\e \&... osfDelete : DeleteChar .oE .wH .in .PP The format of a \fI\&.motifbind\fP file or of a file containing vendor bindings is the same, except that the binding specification for each keysym is placed on a separate line. The example specification above appears as follows in a \fI\&.motifbind\fP or vendor bindings file: .wH .in +3n .oS .ta 1.5i 2i .nf osfBackSpace : BackSpace osfInsert : InsertChar \&... osfDelete : DeleteChar .oE .wH .in .PP The following table lists the fixed fallback default bindings for "osf" keysyms: .PP .ne 7 .sp 1 .in 0 .KS .TS tab(@) center; cb s lb lb. Fallback Default Bindings for "osf" Keysyms "osf" Keysym@Fallback Default Binding _ osfActivate@ osfAddMode@Shift F8 osfBackSpace@Backspace osfBeginLine@Home osfClear@Clear osfCopy@ osfCut@ osfDelete@Delete osfDown@Down osfEndLine@End osfCancel@Escape osfHelp@F1 osfInsert@Insert osfLeft@Left osfMenu@F4 osfMenuBar@F10 osfPageDown@Next osfPageLeft@ osfPageRight@ osfPageUp@Prior osfPaste@ osfPrimaryPaste@ osfQuickPaste@ osfRight@Right osfSelect@Select osfUndo@Undo osfUp@Up .TE .KE .in .sp 1 .SH RELATED INFORMATION \fIxmbind(1X)\fP .\" $Header: nl_tools_16.3x,v 72.2 94/11/30 15:24:00 ssa Exp $ .TA n .TH nl_tools_16 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl_tools_16: ADVANCE(), byte_status(), BYTE_STATUS(), CHARADV(), CHARAT(), c_colwidth(), C_COLWIDTH(), firstof2(), FIRSTof2(), secof2(), SECof2(), WCHAR(), WCHARADV() \- tools to process 16-bit characters .SH SYNOPSIS .C "#include " .PP .C "int firstof2(int c);" .PP .C "int secof2(int c);" .PP .C "int byte_status(int c, int laststatus);" .PP .C int c_colwidth(int c); .PP .C "int FIRSTof2(int c);" .PP .C "int SECof2(int c);" .PP .C "int BYTE_STATUS(int c, int laststatus);" .PP .C "int C_COLWIDTH(int c);" .PP .C "int CHARAT(const char *p);" .PP .C "int ADVANCE(const char *p);" .PP .C "int CHARADV(const char *p);" .PP .C "int WCHAR(wchar_t wc, char *p);" .PP .C "int WCHARADV(wchar_t wc, char *p);" .PP .C "void PCHAR(int c, char *p);" .PP .C "void PCHARADV(int c, char *p);" .SS Remarks All interfaces listed above whose names begin with a capital letter are implemented as macros; the others are functions. .PP These macros and functions are obsolete. See WARNINGS. .SH DESCRIPTION The following macros and functions perform their operations based upon the loaded NLS environment (see .IR setlocale (3C)). .TP 20 .CR FIRSTof2() Takes a byte and returns a nonzero value if it can be the first byte of a two-byte character according to the NLS environment loaded, and zero if it cannot. .TP .CR SECof2() Takes a byte and returns a nonzero value if it can be the second byte of a two-byte character according to the loaded NLS environment, and zero if it cannot. .TP .CR BYTE_STATUS() Returns one of the following values based on the value of the current byte in .I c and the status of the previous byte interpreted in .I laststatus as returned by the last call to .CR BYTE_STATUS() . These are the status values as defined in .CR : .RS .RS .TP 15 .CR ONEBYTE Single-byte character .PD 0 .TP .CR SECOF2 Second byte of two-byte character .TP .CR FIRSTOF2 First byte of two-byte character .RE .RE .PD .IP To validate a two-byte character, both the first and second bytes must be valid. If the value of .I laststatus is .CR FIRSTOF2 but .CR SECof2( c ) returns false, .CI BYTE_STATUS( c , \ laststatus ) returns .CR ONEBYTE . .TP .CR C_COLWIDTH() Takes a byte which is assumed to be either a one-byte character or the first byte of a two-byte character, and returns the number of columns the character would occupy on a terminal display. .IP For the macros .CR BYTE_STATUS() , .CR C_COLWIDTH() , .CR FIRSTof2() , and .CR SEC0of2() , results are undefined for values of .I c less than \(mi1 (EOF) or greater than 255. .TP .CR CHARAT() Takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case, .CR CHARAT() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p . .TP .CR ADVANCE() Advances its pointer argument by the byte width of the character it is pointing at (either one or two bytes). .TP .CR CHARADV() Combines the functions of .CR CHARAT() and .CR ADVANCE() in a single macro. It takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case .CR CHARADV() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p , and advances .I p beyond the last byte of the character. .TP .CR WCHAR() Converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p . .CR WCHAR() returns the .CR wchar_t value .IR wc . .TP .CR WCHARADV() Combines the functions of .CR WCHAR() and .CR ADVANCE() in a single macro. It converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p , then advances .I p past the last byte. .CR WCHARADV() returns the .CR wchar_t value .IR wc . .TP .CR firstof2() .PD 0 .TP .CR secof2() .TP .CR byte_status() .TP .CR c_colwidth() .PD Subroutine versions of the corresponding macros. These functions can be called from languages other than C. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of single and/or multibyte characters. .SH WARNINGS The HP proprietary functions and macros described in this manual entry are .BR OBSOLETE . They are not portable to other vendor's systems, and will not be provided in future HP-UX releases. .PP For maximum portability, use the routines documented in the .IR multibyte (3C) manual entry for multibyte character processing. .PP Other macros listed in this manual entry cannot be used as the first argument to .CR WCHAR() or .CR WCHARADV() . For example, .IP .C "*t++ = *f++" .PP cannot be replaced by .IP .C "WCHARADV(CHARADV (f),t)" .PP Instead, use a method such as .IP .CR "int c; " ...\& " c = CHARADV (f)," .CR "WCHARADV (c,t)" .PP .CR WCHAR() and .CR WCHARADV() may produce a "null effect" warning from .IR lint (1) if not used as part of another expression or as part of a statement. This does not affect the functionality of either macro. .PP Note that .CR WCHAR() and .CR WCHARADV() are not "replace_char" macros. They do not prevent the second byte of a two-byte character from being left dangling if .CR WCHAR() or .CR WCHARADV() overwrite the first byte of the two-byte character with a single-byte character. .PP .CR CHARAT() , .CR ADVANCE() , and .CR CHARADV() do not examine the byte following the location pointed to by the argument to verify its validity as a .CR SECof2 byte. .SH AUTHOR .CR nl_tools_16() was developed by HP. .SH SEE ALSO setlocale(3C), multibyte(3C), wconv(3X), wctype(3X), hpnls(5). .\" .\" index@\f4ADVANCE()\f1 \- advance pointer to next 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARADV()\f1 \- get character and advance pointer to next character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARAT()\f1 \- get value of 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHAR()\f1, \- put 8- or 16-bit character in memory@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHARADV()\f1, \- put character in memory and advance pointer@@@\f3nl_tools_16(3X)\f1 .\" index@\f4byte_status()\f1, \f4BYTE_STATUS()\f1 \- test for valid 1- or 2-byte character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4firstof2()\f1, \f4FIRSTof2()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4secof2()\f1, \f4SECof2()\f1 \- test for valid second byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f1characters, tools to process 16-bit@@@\f3nl_tools_16(3X)\f1 .\" index@\f1process 16-bit characters, tools to@@@\f3nl_tools_16(3X)\f1 .\" index@\f1sixteen-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f116-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f1tools to process 16-bit characters@@@\f3nl_tools_16(3X)\f1 .\" .\" links@nl_tools_16.3x ADVANCE.3x .\" links@nl_tools_16.3x BYTE_STATUS.3x .\" links@nl_tools_16.3x CHARADV.3x .\" links@nl_tools_16.3x CHARAT.3x .\" links@nl_tools_16.3x FIRSTof2.3x .\" links@nl_tools_16.3x SECof2.3x .\" links@nl_tools_16.3x WCHAR.3x .\" links@nl_tools_16.3x WCHARADV.3x .\" links@nl_tools_16.3x byte_status.3x .\" links@nl_tools_16.3x c_colwidth.3x .\" links@nl_tools_16.3x firstof2.3x .\" links@nl_tools_16.3x secof2.3x .\" .\" toc@\f3nl_tools_16(3X)\f1:\0\0\f4ADVANCE()\f1, \f4byte_status()\f1, \f4BYTE_STATUS()\f1, \f4CHARADV()\f1,\n\f4CHARAT()\f1, \f4C_COLWIDTH()\f1, \f4c_colwidth()\f1, \f4firstof2()\f1, \f4FIRSTof2()\f1,\n\f4secof2()\f1, \f4SECof2()\f1, \f4WCHAR()\f1, \f4WCHARADV()\f1@@@tools to process 16-bit characters .\" toc@\f4ADVANCE()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4byte_status()\f1, \f4BYTE_STATUS()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARAT()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4firstof2()\f1, \f4FIRSTof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4secof2()\f1, \f4SECof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHAR()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" $Header: nl_tools_16.3x,v 72.2 94/11/30 15:24:00 ssa Exp $ .TA n .TH nl_tools_16 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl_tools_16: ADVANCE(), byte_status(), BYTE_STATUS(), CHARADV(), CHARAT(), c_colwidth(), C_COLWIDTH(), firstof2(), FIRSTof2(), secof2(), SECof2(), WCHAR(), WCHARADV() \- tools to process 16-bit characters .SH SYNOPSIS .C "#include " .PP .C "int firstof2(int c);" .PP .C "int secof2(int c);" .PP .C "int byte_status(int c, int laststatus);" .PP .C int c_colwidth(int c); .PP .C "int FIRSTof2(int c);" .PP .C "int SECof2(int c);" .PP .C "int BYTE_STATUS(int c, int laststatus);" .PP .C "int C_COLWIDTH(int c);" .PP .C "int CHARAT(const char *p);" .PP .C "int ADVANCE(const char *p);" .PP .C "int CHARADV(const char *p);" .PP .C "int WCHAR(wchar_t wc, char *p);" .PP .C "int WCHARADV(wchar_t wc, char *p);" .PP .C "void PCHAR(int c, char *p);" .PP .C "void PCHARADV(int c, char *p);" .SS Remarks All interfaces listed above whose names begin with a capital letter are implemented as macros; the others are functions. .PP These macros and functions are obsolete. See WARNINGS. .SH DESCRIPTION The following macros and functions perform their operations based upon the loaded NLS environment (see .IR setlocale (3C)). .TP 20 .CR FIRSTof2() Takes a byte and returns a nonzero value if it can be the first byte of a two-byte character according to the NLS environment loaded, and zero if it cannot. .TP .CR SECof2() Takes a byte and returns a nonzero value if it can be the second byte of a two-byte character according to the loaded NLS environment, and zero if it cannot. .TP .CR BYTE_STATUS() Returns one of the following values based on the value of the current byte in .I c and the status of the previous byte interpreted in .I laststatus as returned by the last call to .CR BYTE_STATUS() . These are the status values as defined in .CR : .RS .RS .TP 15 .CR ONEBYTE Single-byte character .PD 0 .TP .CR SECOF2 Second byte of two-byte character .TP .CR FIRSTOF2 First byte of two-byte character .RE .RE .PD .IP To validate a two-byte character, both the first and second bytes must be valid. If the value of .I laststatus is .CR FIRSTOF2 but .CR SECof2( c ) returns false, .CI BYTE_STATUS( c , \ laststatus ) returns .CR ONEBYTE . .TP .CR C_COLWIDTH() Takes a byte which is assumed to be either a one-byte character or the first byte of a two-byte character, and returns the number of columns the character would occupy on a terminal display. .IP For the macros .CR BYTE_STATUS() , .CR C_COLWIDTH() , .CR FIRSTof2() , and .CR SEC0of2() , results are undefined for values of .I c less than \(mi1 (EOF) or greater than 255. .TP .CR CHARAT() Takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case, .CR CHARAT() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p . .TP .CR ADVANCE() Advances its pointer argument by the byte width of the character it is pointing at (either one or two bytes). .TP .CR CHARADV() Combines the functions of .CR CHARAT() and .CR ADVANCE() in a single macro. It takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case .CR CHARADV() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p , and advances .I p beyond the last byte of the character. .TP .CR WCHAR() Converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p . .CR WCHAR() returns the .CR wchar_t value .IR wc . .TP .CR WCHARADV() Combines the functions of .CR WCHAR() and .CR ADVANCE() in a single macro. It converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p , then advances .I p past the last byte. .CR WCHARADV() returns the .CR wchar_t value .IR wc . .TP .CR firstof2() .PD 0 .TP .CR secof2() .TP .CR byte_status() .TP .CR c_colwidth() .PD Subroutine versions of the corresponding macros. These functions can be called from languages other than C. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of single and/or multibyte characters. .SH WARNINGS The HP proprietary functions and macros described in this manual entry are .BR OBSOLETE . They are not portable to other vendor's systems, and will not be provided in future HP-UX releases. .PP For maximum portability, use the routines documented in the .IR multibyte (3C) manual entry for multibyte character processing. .PP Other macros listed in this manual entry cannot be used as the first argument to .CR WCHAR() or .CR WCHARADV() . For example, .IP .C "*t++ = *f++" .PP cannot be replaced by .IP .C "WCHARADV(CHARADV (f),t)" .PP Instead, use a method such as .IP .CR "int c; " ...\& " c = CHARADV (f)," .CR "WCHARADV (c,t)" .PP .CR WCHAR() and .CR WCHARADV() may produce a "null effect" warning from .IR lint (1) if not used as part of another expression or as part of a statement. This does not affect the functionality of either macro. .PP Note that .CR WCHAR() and .CR WCHARADV() are not "replace_char" macros. They do not prevent the second byte of a two-byte character from being left dangling if .CR WCHAR() or .CR WCHARADV() overwrite the first byte of the two-byte character with a single-byte character. .PP .CR CHARAT() , .CR ADVANCE() , and .CR CHARADV() do not examine the byte following the location pointed to by the argument to verify its validity as a .CR SECof2 byte. .SH AUTHOR .CR nl_tools_16() was developed by HP. .SH SEE ALSO setlocale(3C), multibyte(3C), wconv(3X), wctype(3X), hpnls(5). .\" .\" index@\f4ADVANCE()\f1 \- advance pointer to next 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARADV()\f1 \- get character and advance pointer to next character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARAT()\f1 \- get value of 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHAR()\f1, \- put 8- or 16-bit character in memory@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHARADV()\f1, \- put character in memory and advance pointer@@@\f3nl_tools_16(3X)\f1 .\" index@\f4byte_status()\f1, \f4BYTE_STATUS()\f1 \- test for valid 1- or 2-byte character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4firstof2()\f1, \f4FIRSTof2()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4secof2()\f1, \f4SECof2()\f1 \- test for valid second byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f1characters, tools to process 16-bit@@@\f3nl_tools_16(3X)\f1 .\" index@\f1process 16-bit characters, tools to@@@\f3nl_tools_16(3X)\f1 .\" index@\f1sixteen-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f116-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f1tools to process 16-bit characters@@@\f3nl_tools_16(3X)\f1 .\" .\" links@nl_tools_16.3x ADVANCE.3x .\" links@nl_tools_16.3x BYTE_STATUS.3x .\" links@nl_tools_16.3x CHARADV.3x .\" links@nl_tools_16.3x CHARAT.3x .\" links@nl_tools_16.3x FIRSTof2.3x .\" links@nl_tools_16.3x SECof2.3x .\" links@nl_tools_16.3x WCHAR.3x .\" links@nl_tools_16.3x WCHARADV.3x .\" links@nl_tools_16.3x byte_status.3x .\" links@nl_tools_16.3x c_colwidth.3x .\" links@nl_tools_16.3x firstof2.3x .\" links@nl_tools_16.3x secof2.3x .\" .\" toc@\f3nl_tools_16(3X)\f1:\0\0\f4ADVANCE()\f1, \f4byte_status()\f1, \f4BYTE_STATUS()\f1, \f4CHARADV()\f1,\n\f4CHARAT()\f1, \f4C_COLWIDTH()\f1, \f4c_colwidth()\f1, \f4firstof2()\f1, \f4FIRSTof2()\f1,\n\f4secof2()\f1, \f4SECof2()\f1, \f4WCHAR()\f1, \f4WCHARADV()\f1@@@tools to process 16-bit characters .\" toc@\f4ADVANCE()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4byte_status()\f1, \f4BYTE_STATUS()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARAT()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4firstof2()\f1, \f4FIRSTof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4secof2()\f1, \f4SECof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHAR()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH WMShell 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIWMShell\fP \- The WMShell widget class .SH SYNOPSIS .nf .sS .iS \&#include \&#include .iE .sE .SH DESCRIPTION .fi WMShell is a top-level widget that encapsulates the interaction with the window manager. .nL .ne 2.5i .SS "Classes" WMShell inherits behavior and resources from \fICore\fP, \fIComposite\fP, and \fIShell\fP classes. .PP The class pointer is \fIwmShellWidgetClass\fP. .PP The class name is \fIWMShell\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. WMShell Resource Set Name Class Type Default Access _ XmNbaseHeight XmCBaseHeight int XtUnspecifiedShellInt CSG XmNbaseWidth XmCBaseWidth int XtUnspecifiedShellInt CSG XmNheightInc XmCHeightInc int XtUnspecifiedShellInt CSG XmNiconMask XmCIconMask Pixmap NULL CSG XmNiconPixmap XmCIconPixmap Pixmap NULL CSG XmNiconWindow XmCIconWindow Window NULL CSG XmNiconX XmCIconX int \-1 CSG XmNiconY XmCIconY int \-1 CSG XmNinitialState XmCInitialState int NormalState CSG XmNinput XmCInput Boolean False CSG XmNmaxAspectX XmCMaxAspectX int XtUnspecifiedShellInt CSG XmNmaxAspectY XmCMaxAspectY int XtUnspecifiedShellInt CSG XmNmaxHeight XmCMaxHeight int XtUnspecifiedShellInt CSG XmNmaxWidth XmCMaxWidth int XtUnspecifiedShellInt CSG .wH .tH XmNminAspectX XmCMinAspectX int XtUnspecifiedShellInt CSG XmNminAspectY XmCMinAspectY int XtUnspecifiedShellInt CSG XmNminHeight XmCMinHeight int XtUnspecifiedShellInt CSG XmNminWidth XmCMinWidth int XtUnspecifiedShellInt CSG XmNtitle XmCTitle String dynamic CSG XmNtitleEncoding XmCTitleEncoding Atom dynamic CSG XmNtransient XmCTransient Boolean False CSG XmNwaitForWm XmCWaitForWm Boolean True CSG XmNwidthInc XmCWidthInc int XtUnspecifiedShellInt CSG XmNwindowGroup XmCWindowGroup Window dynamic CSG XmNwinGravity XmCWinGravity int dynamic CSG XmNwmTimeout XmCWmTimeout int 5000 ms CSG .TE .KE .in .sp 1 .IP "\fIXmNbaseHeight\fP" Specifies the base for a progression of preferred heights for the window manager to use in sizing the widget. The preferred heights are \fIXmNbaseHeight\fP plus integral multiples of \fIXmNheightInc\fP, with a minimum of \fIXmNminHeight\fP and a maximum of \fIXmNmaxHeight\fP. If an initial value is not supplied for \fIXmNbaseHeight\fP but is supplied for \fIXmNbaseWidth\fP, the value of \fIXmNbaseHeight\fP is set to 0 when the widget is realized. .nL .ne 4 .IP "\fIXmNbaseWidth\fP" Specifies the base for a progression of preferred widths for the window manager to use in sizing the widget. The preferred widths are \fIXmNbaseWidth\fP plus integral multiples of \fIXmNwidthInc\fP, with a minimum of \fIXmNminWidth\fP and a maximum of \fIXmNmaxWidth\fP. If an initial value is not supplied for \fIXmNbaseWidth\fP but is supplied for \fIXmNbaseHeight\fP, the value of \fIXmNbaseWidth\fP is set to 0 when the widget is realized. .IP "\fIXmNheightInc\fP" Specifies the increment for a progression of preferred heights for the window manager to use in sizing the widget. The preferred heights are \fIXmNbaseHeight\fP plus integral multiples of \fIXmNheightInc\fP, with a minimum of \fIXmNminHeight\fP and a maximum of \fIXmNmaxHeight\fP. If an initial value is not supplied for \fIXmNheightInc\fP but is supplied for \fIXmNwidthInc\fP, the value of \fIXmNheightInc\fP is set to 1 when the widget is realized. .IP "\fIXmNiconMask\fP" Specifies a bitmap that could be used by the window manager to clip the \fIXmNiconPixmap\fP bitmap to make the icon nonrectangular. .IP "\fIXmNiconPixmap\fP" Specifies a bitmap that could be used by the window manager as the application's icon. .IP "\fIXmNiconWindow\fP" Specifies the ID of a window that could be used by the window manager as the application's icon. .IP "\fIXmNiconX\fP" Specifies a suitable place to put the application's icon; this is a hint to the window manager in root window coordinates. Since the window manager controls icon placement policy, this may be ignored. If no initial value is specified, the value is set to \-1 when the widget is realized. .IP "\fIXmNiconY\fP" Specifies a suitable place to put the application's icon; this is a hint to the window manager in root window coordinates. Since the window manager .ne 4 controls icon placement policy, this may be ignored. If no initial value is specified, the value is set to \-1 when the widget is realized. .IP "\fIXmNinitialState\fP" Specifies the state in which the application wishes the widget instance to start. It must be one of the constants \fINormalState\fP or \fIIconicState\fP. .IP "\fIXmNinput\fP" Specifies the application's input model for this widget and its descendants. The meaning of a True or False value for this resource depends on the presence or absence of a \fIWM_TAKE_FOCUS\fP atom in the \fIWM_PROTOCOLS\fP property: .P .ne 1.5i .sp 1 .in 0 .KS .TS tab(@) center; lb lb lb l l l. Input Model@XmNinput@WM_TAKE_FOCUS _ No input@False@Absent Passive@True@Absent Locally active@True@Present Globally active@False@Present .TE .KE .in .sp 1 .P For more information on input models, see the X Consortium Standard \fBInter-Client Communication Conventions Manual.\fP .IP "\fIXmNmaxAspectX\fP" Specifies the numerator of the maximum aspect ratio (X/Y) that the application wishes the widget instance to have. .IP "\fIXmNmaxAspectY\fP" Specifies the denominator of the maximum aspect ratio (X/Y) that the application wishes the widget instance to have. .IP "\fIXmNmaxHeight\fP" Specifies the maximum height that the application wishes the widget instance to have. If an initial value is not supplied for \fIXmNmaxHeight\fP but is supplied for \fIXmNmaxWidth\fP, the value of \fIXmNmaxHeight\fP is set to 32767 when the widget is realized. .nL .ne 6 .IP "\fIXmNmaxWidth\fP" Specifies the maximum width that the application wishes the widget instance to have. If an initial value is not supplied for \fIXmNmaxWidth\fP but is supplied for \fIXmNmaxHeight\fP, the value of \fIXmNmaxWidth\fP is set to 32767 when the widget is realized. .IP "\fIXmNminAspectX\fP" Specifies the numerator of the minimum aspect ratio (X/Y) that the application wishes the widget instance to have. .IP "\fIXmNminAspectY\fP" Specifies the denominator of the minimum aspect ratio (X/Y) that the application wishes the widget instance to have. .IP "\fIXmNminHeight\fP" Specifies the minimum height that the application wishes the widget instance to have. If an initial value is not supplied for \fIXmNminHeight\fP but is supplied for \fIXmNminWidth\fP, the value of \fIXmNminHeight\fP is set to 1 when the widget is realized. .IP "\fIXmNminWidth\fP" Specifies the minimum width that the application wishes the widget instance to have. If an initial value is not supplied for \fIXmNminWidth\fP but is supplied for \fIXmNminHeight\fP, the value of \fIXmNminWidth\fP is set to 1 when the widget is realized. .IP "\fIXmNtitle\fP" Specifies the application name to be displayed by the window manager. The default is the icon name if specified, otherwise the name of the application. .IP "\fIXmNtitleEncoding\fP" Specifies a property type that represents the encoding of the \fIXmNtitle\fP string. If a language procedure has been set, the default is None; otherwise, the default is XA_STRING. When the widget is realized, if the value is None, the corresponding name is assumed to be in the current locale. The name is passed to \fIXmbTextListToTextProperty\fP with an encoding style of \fIXStdICCTextStyle\fP. The resulting encoding is "STRING" if the name is fully convertible to "STRING," otherwise "COMPOUND_TEXT." The values of the encoding resources are not changed; they remain None. .IP "\fIXmNtransient\fP" Specifies a Boolean value that is True if the widget instance is transient, typically a popup on behalf of another widget. The window manager may treat a transient widget's window differently from other windows. For example, a window manager may .ne 7 not iconify a transient window separately from its associated application. Applications and users should not normally alter this resource. .IP "\fIXmNwaitForWm\fP" When True, specifies that the Intrinsics waits the length of time given by the \fIXmNwmTimeout\fP resource for the window manager to respond to certain actions before assuming that there is no window manager present. This resource is altered by the Intrinsics as it receives, or fails to receive, responses from the window manager. .IP "\fIXmNwidthInc\fP" Specifies the base for a progression of preferred widths for the window manager to use in sizing the widget. The preferred widths are \fIXmNbaseWidth\fP plus integral multiples of \fIXmNwidthInc\fP, with a minimum of \fIXmNminWidth\fP and a maximum of \fIXmNmaxWidth\fP. If an initial value is not supplied for \fIXmNwidthInc\fP but is supplied for \fIXmNheightInc\fP, the value of \fIXmNwidthInc\fP is set to 1 when the widget is realized. .IP "\fIXmNwindowGroup\fP" Specifies the ID of a window with which this widget instance is associated. By convention, this window is the "leader" of a group of windows. A window manager may treat all windows in a group in some way; for example, it may always move or iconify them together. .PP If no initial value is specified, the value is set to the window of the first realized ancestor widget in the parent hierarchy when the widget is realized. If a value of \fIXtUnspecifiedWindowGroup\fP is specified, no window group is set. .nL .ne 25 .IP "\fIXmNwinGravity\fP" Specifies the window gravity for use by the window manager in positioning the widget. If no initial value is specified, the value is set when the widget is realized. If \fIXmNgeometry\fP is not NULL, \fIXmNwinGravity\fP is set to the window gravity returned by \fIXWMGeometry\fP. Otherwise, \fIXmNwinGravity\fP is set to \fINorthWestGravity\fP. .IP "\fIXmNwmTimeout\fP" Specifies the length of time that the Intrinsics waits for the window manager to respond to certain actions before assuming that there is no window manager present. The value is in milliseconds and must not be negative. .SS "Inherited Resources" WMShell inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Shell Resource Set Name Class Type Default Access _ XmNallowShellResize XmCAllowShellResize Boolean False CG XmNcreatePopupChildProc XmCCreatePopupChildProc XtCreatePopupChildProc NULL CSG XmNgeometry XmCGeometry String NULL CSG XmNoverrideRedirect XmCOverrideRedirect Boolean False CSG XmNpopdownCallback XmCCallback XtCallbackList NULL C XmNpopupCallback XmCCallback XtCallbackList NULL C XmNsaveUnder XmCSaveUnder Boolean False CSG XmNvisual XmCVisual Visual * CopyFromParent CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 1 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Translations" There are no translations for WMShell. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fICore(3X)\fP, and \fIShell(3X)\fP. .ad .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .ds F1 \f(CW .ds F2 \f(CI .ds F3 \fR .RH "WMShell" "Intrinsics Classes" .XX "WMShell" .XX "widget class, WMShell" .SH "Name" .Na WMShell widget class \- fundamental shell widget class that interacts with an ICCCM-compliant window manager. .Nz .\" .SH "Synopsis" .IP "\s-1\f(HBPublic Headers:\fP\s0" 18n 0 \fI\fP .br \fI\fP .IP "\s-1\f(HBPrivate Header:\fP\s0" 18n 0 \fI\fP .IP "\s-1\f(HBClass\ Name:\fP\s0" 18n 0 WMShell .IP "\s-1\f(HBClass\ Hierarchy:\fP\s0" 18n 0 'nh Core \(-> Composite \(-> Shell \(-> WMShell .IP "\s-1\f(HBClass Pointer:\fP\s0" 18n 0 \f(CWwmShellWidgetClass\fP .IP "\s-1\f(HBInstantiation:\fP\s0" 18n 0 WMShell is an Intrinsics meta-class, and is not normally instantiated. .IP "\s-1\f(HBFunctions/Macros:\fP\s0" 18n 0 \f(CWXtIsWMShell(\^)\fP .\" .SH "Description" WMShell is a direct subclass of Shell that provides basic window manager interaction. It should not be instantiated itself; its subclasses TransientShell, TopLevelShell, and ApplicationShell provide additional functionality suitable for particular types of top-level windows. .\" .SH "New Resources" WMShell defines the following resources: .br .sp 1 .in 0 .KS .TS H expand linesize(2) tab(@); lp7 lp7 lp7 lp7 lp7 lp6 lp6 lp6 lp6 lp6. \fRName@Class@Type@Default@Access\fP .sp 2p .sp 2p .Th .XX "XtNbaseHeight" \f(CWXtNbaseHeight\fP@\f(CWXtCBaseHeight\fP@\f(CWint\fP@\f(CWXtUnspecifiedShellInt\fP@\f(CWCSG\fP .XX "XtNbaseWidth" \f(CWXtNbaseWidth\fP@\f(CWXtCBaseWidth\fP@\f(CWint\fP@\f(CWXtUnspecifiedShellInt\fP@\f(CWCSG\fP .XX "XtNheightInc" \f(CWXtNheightInc\fP@\f(CWXtCHeightInc\fP@\f(CWint\fP@\f(CWXtUnspecifiedShellInt\fP@\f(CWCSG\fP .XX "XtNiconMask" \f(CWXtNiconMask\fP@\f(CWXtCIconMask\fP@\f(CWPixmap\fP@\f(CWNULL\fP@\f(CWCSG\fP .XX "XtNiconPixmap" \f(CWXtNiconPixmap\fP@\f(CWXtCIconPixmap\fP@\f(CWPixmap\fP@\f(CWNULL\fP@\f(CWCSG\fP .XX "XtNiconWindow" \f(CWXtNiconWindow\fP@\f(CWXtCIconWindow\fP@\f(CWWindow\fP@\f(CWNULL\fP@\f(CWCSG\fP .XX "XtNiconX" \f(CWXtNiconX\fP@\f(CWXtCIconX\fP@\f(CWint\fP@\f(CW\-1\fP@\f(CWCSG\fP .XX "XtNiconY" \f(CWXtNiconY\fP@\f(CWXtCIconY\fP@\f(CWint\fP@\f(CW\-1\fP@\f(CWCSG\fP .XX "XtNinitialState" \f(CWXtNinitialState\fP@\f(CWXtCInitialState\fP@\f(CWint\fP@\f(CWNormalState\fP@\f(CWCSG\fP .XX "XtNinput" \f(CWXtNinput\fP@\f(CWXtCInput\fP@\f(CWBoolean\fP@\f(CWFalse\fP@\f(CWCSG\fP .XX "XtNmaxAspectX" \f(CWXtNmaxAspectX\fP@\f(CWXtCMaxAspectX\fP@\f(CWint\fP@\f(CWXtUnspecifiedShellInt\fP@\f(CWCSG\fP .XX "XtNmaxAspectY" \f(CWXtNmaxAspectY\fP@\f(CWXtCMaxAspectY\fP@\f(CWint\fP@\f(CWXtUnspecifiedShellInt\fP@\f(CWCSG\fP .XX "XtNmaxHeight" \f(CWXtNmaxHeight\fP@\f(CWXtCMaxHeight\fP@\f(CWint\fP@\f(CWXtUnspecifiedShellInt\fP@\f(CWCSG\fP .XX "XtNmaxWidth" \f(CWXtNmaxWidth\fP@\f(CWXtCMaxWidth\fP@\f(CWint\fP@\f(CWXtUnspecifiedShellInt\fP@\f(CWCSG\fP .XX "XtNminAspectX" \f(CWXtNminAspectX\fP@\f(CWXtCMinAspectX\fP@\f(CWint\fP@\f(CWXtUnspecifiedShellInt\fP@\f(CWCSG\fP .XX "XtNminAspectY" \f(CWXtNminAspectY\fP@\f(CWXtCMinAspectY\fP@\f(CWint\fP@\f(CWXtUnspecifiedShellInt\fP@\f(CWCSG\fP .XX "XtNminHeight" \f(CWXtNminHeight\fP@\f(CWXtCMinHeight\fP@\f(CWint\fP@\f(CWXtUnspecifiedShellInt\fP@\f(CWCSG\fP .XX "XtNminWidth" \f(CWXtNminWidth\fP@\f(CWXtCMinWidth\fP@\f(CWint\fP@\f(CWXtUnspecifiedShellInt\fP@\f(CWCSG\fP .XX "XtNtitle" \f(CWXtNtitle\fP@\f(CWXtCTitle\fP@\f(CWString\fP@\f(CWdynamic\fP@\f(CWCSG\fP .XX "XtNtitleEncoding" \f(CWXtNtitleEncoding\fP@\f(CWXtCTitleEncoding\fP@\f(CWAtom\fP@\f(CWXA_STRING\fP@\f(CWCSG\fP .XX "XtNtransient" \f(CWXtNtransient\fP@\f(CWXtCTransient\fP@\f(CWBoolean\fP@\f(CWFalse\fP@\f(CWCSG\fP .XX "XtNwaitForWm" \f(CWXtNwaitForWm\fP@\f(CWXtCWaitForWm\fP@\f(CWBoolean\fP@\f(CWTrue\fP@\f(CWCSG\fP .XX "XtNwidthInc" \f(CWXtNwidthInc\fP@\f(CWXtCWidthInc\fP@\f(CWint\fP@\f(CWXtUnspecifiedShellInt\fP@\f(CWCSG\fP .XX "XtNwindowGroup" \f(CWXtNwindowGroup\fP@\f(CWXtCWindowGroup\fP@\f(CWWindow\fP@\f(CWdynamic\fP@\f(CWCSG\fP .XX "XtNwinGravity" \f(CWXtNwinGravity\fP@\f(CWXtCWinGravity\fP@\f(CWint\fP@\f(CWdynamic\fP@\f(CWCSG\fP .XX "XtNwmTimeout" \f(CWXtNwmTimeout\fP@\f(CWXtCWmTimeout\fP@\f(CWint\fP@\f(CW5000 ms\fP@\f(CWCSG\fP .sp .2 .TE .KE .in .sp 1 .LP Many of these resources are hints to the window manager which can be set with the Xlib function \f(CWXSetWMProperties()\fP. The default value for these resources is \f(CWXtUnspecifiedShellInt\fP for integer resources, or \f(CWNone\fP for the pixmaps and windows. If any of these resources is not changed from its default value, then WMShell will not set the corresponding flag bit in the hints structure when it sets the appropriate properties, and that particular hint will be unspecified. See the Shell \f(CWXtNgeometry\fP resource for more information on size hints for a shell widget. See \f(CWXSetWMProperties()\fP and the ICCCM for more information on the window properties that are used to convey hints to window managers. .IP \f(CWXtNbaseHeight\fP 5n .ns .br .IP \f(CWXtNbaseWidth\fP 5n 0 .br The base dimensions from which the preferred height and width can be stepped up or down (as specified by \f(CWXtNheightInc\fP or \f(CWXtNwidthInc\fP). .IP \f(CWXtNheightInc\fP 5n .br The step size by which the widget's height may be adjusted. An application that displays lines of text might set this to the font height, so that it can always display a whole number of lines. The base height is \f(CWXtNbaseHeight\fP, and the height can decrement to the value of \f(CWXtNminHeight\fP or increment to the value of \f(CWXtNmaxHeight\fP. See also \f(CWXtNwidthInc\fP. .IP \f(CWXtNiconMask\fP 5n .br A bitmap that the window manager can use in order to clip the application's icon into a nonrectangular shape. .IP \f(CWXtNiconPixmap\fP 5n .br A pixmap that the window manager is requested to display as the application's icon. .IP \f(CWXtNiconWindow\fP 5n .br The ID of a window that the window manager is requested to use as the application's icon. The application is responsible for drawing in this window and handling Expose events on it. .IP \f(CWXtNiconX\fP 5n .ns .br .IP \f(CWXtNiconY\fP 5n 0 .br Window manager hints for the initial root window coordinates of the application's icon. .Nd 15 .IP \f(CWXtNinitialState\fP 5n .br The initial appearance of the widget instance. Possible values are defined in \fI\fP: .Ps 0 NormalState /* application starts as a window */ IconicState /* application starts as an icon */ .Pe 0 .IP \f(CWXtNinput\fP 5n .br A Boolean that, in conjunction with the \f(CWWM_TAKE_FOCUS\fP atom in the \f(CWWM_PROTOCOLS\fP property, determines the application's keyboard focus model. The result is determined by the value of \f(CWXtNinput\fP and the existence of the atom, as described below: .Nd 5 .RS .sp 1 .in 0 .KS .TS linesize(2) tab(@); c c c c c c lp7 lp7fR lp7fR . \fRValue of@WM_TAKE_FOCUS@Keyboard Focus\fP \f(CWXtNinput Resource\fR@Atom@Model\fP .sp 2p .sp 2p \f(CWFalse\fP@Does not exist.@No input allowed. \f(CWTrue\fP@Does not exist.@Passive. \f(CWTrue\fP@Exists.@Locally active. \f(CWFalse\fP@Exists.@Globally active. .sp 2p .TE .KE .in .sp 1 .RE See the \fIInter-Client Communications Conventions Manual\fP, Section 4.1.17 (in Appendix L of Volume Zero), for more information on these models of keyboard focus. .IP \f(CWXtNmaxAspectX\fP 5n .ns .br .IP \f(CWXtNmaxAspectY\fP 5n 0 .br The numerator and denominator, respectively, of the maximum aspect ratio requested for this widget. .IP \f(CWXtNmaxHeight\fP 5n .ns .br .IP \f(CWXtNmaxWidth\fP 5n 0 .br The maximum dimensions for the widget's preferred height or width. .IP \f(CWXtNminAspectX\fP 5n .ns .br .IP \f(CWXtNminAspectY\fP 5n 0 .br The numerator and denominator, respectively, of the minimum aspect ratio requested for this widget. .IP \f(CWXtNminHeight\fP 5n .ns .br .IP \f(CWXtNminWidth\fP 5n 0 .br The minimum dimensions for the widget's preferred height or width. .IP \f(CWXtNtitle\fP 5n .br The string that the window manager displays as the application's name. The default is the icon name, or if that isn't specified, the name of the application. .IP \f(CWXtNtitleEncoding\fP 5n .br An Atom which specifies the encoding of the \f(CWXtNtitle\fP resource. .Nd 10 .IP \f(CWXtNtransient\fP 5n .br If \f(CWTrue\fP, this indicates a popup window or some other transient widget which should have its WM_TRANSIENT_FOR property set (see the \f(CWXtNwindowGroup\fP resource below, and also the \f(CWXtNtransientFor\fP resource of the TransientShell class). Different window managers will interpret this property differently, and may provide fewer decorations (no iconify button, for example) than they would for a non-transient window. .IP \f(CWXtNwaitForWm\fP 5n .br If \f(CWTrue\fP (default), the shell waits for a response from the window manager before changing the size of a widget. The timeout interval is specified by the \f(CWXtNwmTimeout\fP resource. If the window manager does not respond within this time, this resource will be set to \f(CWFalse\fP, though it may be reset to its original value later. When this resource is \f(CWFalse\fP, the shell relies on asynchronous notification from the window manager and does not wait for a response. .IP \f(CWXtNwidthInc\fP 5n .br The step size by which the widget's width may be adjusted. The base width is \f(CWXtNbaseWidth\fP, and the width can decrement to the value of \f(CWXtNminWidth\fP or increment to the value of \f(CWXtNmaxWidth\fP. See also \f(CWXtNheightInc\fP. .Nd 3 .IP \f(CWXtNwindowGroup\fP 5n .br This is a hint to the window manager that this shell is associated with the main window or "group leader" window specified by this resource. Some window managers may allow groups of related windows to be manipulated together. If the shell widget is not the root of the widget hierarchy, then WMShell sets the default value of this resource to the window ID of the root widget if that widget is realized. This resource can be set to the special value \f(CWXtUnspecifiedWindowGroup\fP to indicate that the window group hint should not be set. If \f(CWXtNtransient\fP is \f(CWTrue\fP, and if the shell is not a subclass of \f(CWTransientShell\fP, and if this resource is not \f(CWXtUnspecifiedWindowGroup\fP, then it will be set as the value of the WM_TRANSIENT_FOR property. See also the \f(CWXtNtransientFor\fP resource of the TransientShell class. .IP \f(CWXtNwinGravity\fP 5n .br The window gravity used in positioning the widget. Unless an initial value is given, this resource will be set when the widget is realized. The default value is \f(CWNorthWestGravity\fP (if the Shell resource \f(CWXtNgeometry\fP is \f(CWNULL\fP); otherwise, \f(CWXtNwinGravity\fP assumes the value returned by the \f(CWXWMGeometry()\fP routine. .IP \f(CWXtNwmTimeout\fP 5n .br The number of milliseconds that the X Toolkit waits for a response from the window manager. This resource is meaningful when the \f(CWXtNwaitForWm\fP resource is set to \f(CWTrue\fP. If the window manager does not respond to a geometry request within this time, the shell assumes that the window manager is not functioning properly and sets \f(CWXtNwaitForWm\fP to \f(CWFalse\fP. .\" .Nd 4 .SH "Inherited Resources" WMShell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. .Nd 3 .sp 1 .in 0 .KS .TS tab(@), linesize(2); l l l l lp6w(1.25i) lp6w(1i) lp6w(1.25i) lp6w(1i). \fRResource@Inherited From@Resource@Inherited From\fP .sp 2p \f(CWXtNaccelerators\fP@\f(CWCore\fP@\f(CWXtNinitialResources-\fP@\f(CWCore\fP .sp -2p @@\0\0\f(CWPersistent\fP \f(CWXtNallowShellResize\fP@\f(CWShell\fP@\f(CWXtNinsertPosition\fP@\f(CWComposite\fP \f(CWXtNancestorSensitive\fP@\f(CWCore\fP@\f(CWXtNmappedWhenManaged\fP@\f(CWCore\fP \f(CWXtNbackground\fP@\f(CWCore\fP@\f(CWXtNnumChildren\fP@\f(CWComposite\fP \f(CWXtNbackgroundPixmap\fP@\f(CWCore\fP@\f(CWXtNoverrideRedirect\fP@\f(CWShell\fP \f(CWXtNborderColor\fP@\f(CWCore\fP@\f(CWXtNpopdownCallback\fP@\f(CWShell\fP \f(CWXtNborderPixmap\fP@\f(CWCore\fP@\f(CWXtNpopupCallback\fP@\f(CWShell\fP \f(CWXtNborderWidth\fP@\f(CWCore\fP@\f(CWXtNsaveUnder\fP@\f(CWShell\fP \f(CWXtNchildren\fP@\f(CWComposite\fP@\f(CWXtNscreen\fP@\f(CWCore\fP \f(CWXtNcolormap\fP@\f(CWCore\fP@\f(CWXtNsensitive\fP@\f(CWCore\fP \f(CWXtNcreatePopupChild-\fP@\f(CWShell\fP@\f(CWXtNtranslations\fP@\f(CWCore\fP .sp -2p \0\0\f(CWProc\fP \f(CWXtNdepth\fP@\f(CWCore\fP@\f(CWXtNvisual\fP@\f(CWShell\fP \f(CWXtNdestroyCallback\fP@\f(CWCore\fP@\f(CWXtNwidth\fP@\f(CWCore\fP \f(CWXtNgeometry\fP@\f(CWShell\fP@\f(CWXtNx\fP@\f(CWCore\fP \f(CWXtNheight\fP@\f(CWCore\fP@\f(CWXtNy\fP@\f(CWCore\fP .sp 2p .TE .KE .in .sp 1 .\" .SH "Class Structure" The WMShell class structure contains only an extension field: .Ps .ta 5n 2i typedef struct { XtPointer extension; /* pointer to extension record */ } WMShellClassPart; typedef struct { CorePart core; CompositePart composite; ShellPart shell; WMShellPart wm; } WMShellRec, *WMShellWidget; .Pe .\" .SH "Instance Structure" The WMShell instance structure contains at least the following fields (which need not be in this order): .Ps .ta .5i 1i 1.5i 2i typedef struct { String title; int wm_timeout; Boolean wait_for_wm; Boolean transient; struct _OldXSizeHints { long flags; int x, y; int width, height; int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; int y; } min_aspect, max_aspect; } size_hints; XWMHints wm_hints; int base_width, base_height, win_gravity; Atom title_encoding; } WMShellPart; .ta .5i 3i typedef struct { CorePart core; CompositePart composite; ShellPart shell; WMShellPart wm; } WMShellRec, *WMShellWidget; .Pe The \f(CWXWMHints\fP type is defined (in \fI\fP) as follows: .Ps .ps 8 .ta .5i 2i typedef struct { long flags; /* marks which fields in this structure are defined */ Bool input; /* does this application rely on the window manager to get keyboard input? */ int initial_state; /* see below */ Pixmap icon_pixmap; /* pixmap to be used as icon */ Window icon_window; /* window to be used as icon */ int icon_x, icon_y; /* initial position of icon */ Pixmap icon_mask; /* icon mask bitmap */ XID window_group; /* id of related window group */ /* this structure may be extended in the future */ } XWMHints; .Pe .\" .SH "See Also" \s-1\fIShell\fR\s+1\*(s3. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XActivateScreenSaver" "Xlib \- Screen Saver" .ds ]W Xlib Reference Manual .SH "Name" .XX "XActivateScreenSaver" .XX "screens:blanking" .XX "screen savers" .Na XActivateScreenSaver \(en activate screen blanking. .Nz .SH "Synopsis" .Sy XActivateScreenSaver\^(\^\f(CIdisplay\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Description \f(CWXActivateScreenSaver()\fP turns on the screen saver using the parameters set with \f(CWXSetScreenSaver()\fP. The screen saver blanks the screen or makes random changes to the display in order to save the phosphors from burnout when the screen is left unattended for an extended period of time. The interval that the server will wait before starting screen save activity can be set with \f(CWXSetScreenSaver()\fP. Exactly how the screen saver works is server-dependent. .LP For more information on the screen saver, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "See Also" \s-1\fIXForceScreenSaver()\fP\s+1, \s-1\fIXGetScreenSaver()\fP\s+1, \s-1\fIXResetScreenSaver()\fP\s+1, \s-1\fIXSetScreenSaver()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAddHost" "Xlib \- Host Access" .ds ]W Xlib Reference Manual .SH "Name" .XX "XAddHost" .XS "hosts:adding to access control list" .XS "access control lists:adding hosts to" .Na XAddHost \(en add a host to the access control list. .Nz .SH "Synopsis" .Sy XAddHost\^(\^\f(CIdisplay\f(CW, \f(CIhost\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XHostAddress *\f(CIhost\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIhost\fP .88i Specifies the network address of the host machine to be added. .SH Description \f(CWXAddHost()\fP adds the specified host to the access control list for the server specified by \f(CIdisplay\fP. The access control list is a primitive security feature that allows access to the server only by other machines listed in a file on the machine running the server. On UNIX-based systems, this file is called \fI/etc/X?.hosts\fR, where \fI?\fR is the number of the server. .LP The application that calls \f(CWXAddHost()\fR and the server whose list is being updated must be running on the same host machine. .LP The \f(CWaddress\fP data must be a valid address for the type of network in which the server operates, as specified in the \f(CWfamily\fP member. Internet, DECnet and ChaosNet networks are currently supported. .LP For TCP/IP, the address should be in network byte order. For the DECnet family, the server performs no automatic swapping on the address bytes. A Phase IV address is two bytes long. The first byte contains the least significant eight bits of the node number. The second byte contains the most significant two bits of the node number in the least significant two bits of the byte, and the area in the most significant six bits of the byte. .LP For more information on access control, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "Structures" .Ps typedef struct { int family; /* for example FamilyInternet */ int length; /* length of address, in bytes */ char *address; /* pointer to where to find the bytes */ } XHostAddress; /* The following constants for \f(CWfamily\fP member */ #define FamilyInternet 0 #define FamilyDECnet 1 #define FamilyChaos 2 .Pe .SH "Errors" \f(CWBadAccess\fP .br \f(CWBadValue\fP .br .ft R .SH "See Also" \s-1\fIXAddHosts()\fP\s+1, \s-1\fIXDisableAccessControl()\fP\s+1, \s-1\fIXEnableAccessControl()\fP\s+1, \s-1\fIXListHosts()\fP\s+1, \s-1\fIXRemoveHost()\fP\s+1, \s-1\fIXRemoveHosts()\fP\s+1, \s-1\fIXSetAccessControl()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAddHosts" "Xlib \- Host Access" .ds ]W Xlib Reference Manual .SH "Name" .XX "XAddHosts" .XE "hosts:adding to access control list" .XE "access control lists:adding hosts to" .Na XAddHosts \(en add multiple hosts to the access control list. .Nz .SH "Synopsis" .Sy XAddHosts\^(\^\f(CIdisplay\f(CW, \f(CIhosts\f(CW, \f(CInum_hosts\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XHostAddress *\f(CIhosts\f(CW\^; int \f(CInum_hosts\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIhosts\fP 1i Specifies each host that is to be added. .IP \f(CInum_hosts\fP 1i Specifies the number of hosts that are to be added. .SH Description \f(CWXAddHosts()\fP adds each specified host to the access control list for the server specified by \f(CIdisplay\fP. The access control list is a primitive security feature that allows access to the server only by other machines listed in a file on the machine running the server. On UNIX systems, this file is \fI/etc/X?.hosts\fR, where \fI?\fR is the number of the display. .LP The application that calls \f(CWXAddHosts()\fR and the server whose list is being updated must be running on the same host machine. .LP The \f(CWaddress\fP data must be a valid address for the type of network in which the server operates, as specified by the \f(CWfamily\fP member. Internet, DECnet and ChaosNet networks are currently supported. .LP For TCP/IP, the address should be in network byte order. For the DECnet family, the server performs no automatic swapping on the address bytes. A Phase IV address is two bytes long. The first byte contains the least significant eight bits of the node number. The second byte contains the most significant two bits of the node number in the least significant two bits of the byte, and the area in the most significant six bits of the byte. .LP For more information on access control, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "Structures" .Ps typedef struct { int family; /* for example Family Internet */ int length; /* length of address, in bytes */ char *address; /* pointer to where to find the bytes */ } XHostAddress; /* The following constants for \f(CWfamily\fP member */ #define FamilyInternet 0 #define FamilyDECnet 1 #define FamilyChaos 2 .Pe .SH "Errors" \f(CWBadAccess\fP .br \f(CWBadValue\fP .ne 6 .SH "See Also" \s-1\fIXAddHost()\fP\s+1, \s-1\fIXDisableAccessControl()\fP\s+1, \s-1\fIXEnableAccessControl()\fP\s+1, \s-1\fIXListHosts()\fP\s+1, \s-1\fIXRemoveHost()\fP\s+1, \s-1\fIXRemoveHosts()\fP\s+1, \s-1\fIXSetAccessControl()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAddPixel" "Xlib \- Images" .ds ]W Xlib Reference Manual .SH "Name" .XX "XAddPixel" .XX "pixels:adding constant values to" .Na XAddPixel \(en add a constant value to every pixel value in an image. .Nz .SH "Synopsis" .Sy XAddPixel\^(\^\f(CIximage\f(CW, \f(CIvalue\f(CW\^) .As XImage *\f(CIximage\f(CW\^; long \f(CIvalue\f(CW\^; .Ae .SH "Arguments" .IP \f(CIximage\fP 1i Specifies a pointer to the image to be modified. .IP \f(CIvalue\fP 1i Specifies the constant value that is to be added. Valid pixel value ranges depend on the visual used to create the image. If this value added to the existing value causes an overflow, extra bits in the result are truncated. .SH Description \f(CWXAddPixel()\fP adds a constant value to every pixel value in an image. This function is useful when you have a base pixel value derived from the allocation of color resources and need to manipulate an image so that the pixel values are in the same range. .LP For more information on images, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" .Ps typedef struct _XImage { int width, height; /* size of image */ int xoffset; /* number of pixels offset in X direction */ int format; /* XYBitmap, XYPixmap, ZPixmap */ char *data; /* pointer to image data */ int byte_order; /* data byte order, LSBFirst, MSBFirst */ int bitmap_unit; /* quantity of scan line 8, 16, 32 */ int bitmap_bit_order; /* LSBFirst, MSBFirst */ int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */ int depth; /* depth of image */ int bytes_per_line; /* accelerator to next line */ int bits_per_pixel; /* bits per pixel (ZPixmap) */ unsigned long red_mask; /* bits in z arrangment */ unsigned long green_mask; unsigned long blue_mask; char *obdata; /* hook for object routines to hang on */ struct funcs { /* image manipulation routines */ struct _XImage *(*create_image)(); int (*destroy_image)(); unsigned long (*get_pixel)(); .ne 8 int (*put_pixel)(); struct _XImage *(*sub_image)(); int (*add_pixel)(); } f; } XImage; .Pe .ne 3 .SH "See Also" \s-1\fIXImageByteOrder()\fP\s+1, \s-1\fIXCreateImage()\fP\s+1, \s-1\fIXDestroyImage()\fP\s+1, \s-1\fIXGetImage()\fP\s+1, \s-1\fIXGetPixel()\fP\s+1, \s-1\fIXGetSubImage()\fP\s+1, \s-1\fIXPutImage()\fP\s+1, \s-1\fIXPutPixel()\fP\s+1, \s-1\fIXSubImage()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAddToSaveSet" "Xlib \- Save Set" .ds ]W Xlib Reference Manual .SH "Name" .XX "XAddToSaveSet" .XX "save-set:adding windows to" .Na XAddToSaveSet \(en add a window to the client's save-set. .Nz .SH "Synopsis" .Sy XAddToSaveSet\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window you want to add to the client's save-set. .SH Description \f(CWXAddToSaveSet()\fR adds the specified window to the client's save-set. .LP The save-set is a safety net for windows that have been reparented by the window manager, usually to provide a titlebar or other decorations for each application. When the window manager dies unexpectedly, the windows in the save-set are reparented to their closest living ancestor, so that they remain alive. See Volume One, Chapter 15, \fIOther Programming Techniques\fP, for more information about save-sets. .LP .XX "XRemoveFromSaveSet" Use \f(CWXRemoveFromSaveSet()\fP to remove a window from the client's save-set. .ft R .SH "Errors" .IP "\f(CWBadMatch\fP" 1i \f(CIw\^\fR not created by some other client. .sp -.25 .IP "\f(CWBadWindow\fP" .ft R .SH "See Also" \s-1\fIXChangeSaveSet()\fP\s+1, \s-1\fIXRemoveFromSaveSet()\fP\s+1. .\"last line comment .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XAllDvEv.man,v 1.5 94/06/04 17:32:07 rws Exp $ .ds xL Programming With Xlib .TH XAllowDeviceEvents 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XAllowDeviceEvents \- release queued events .SH SYNTAX XAllowDeviceEvents\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fIevent_mode\fP\^, \fItime\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br int \fIevent_mode\fP\^; .br Time \fItime\fP\^; .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device from which events are to be allowed. .TP 12 .I event_mode Specifies the event mode. You can pass \fIAsyncThisDevice\fP, \fISyncThisDevice\fP, \fIReplayThisDevice\fP, \fIAsyncOtherDevices\fP, \fISyncAll\fP, or \fIAsyncAll\fP. .TP 12 .I time Specifies the time. You can pass either a timestamp or \fICurrentTime\fP. .SH DESCRIPTION The \fIXAllowDeviceEvents\fP function releases some queued events if the client has caused a device to freeze. It has no effect if the specified time is earlier than the last-grab time of the most recent active grab for the client and device, or if the specified time is later than the current X server time. .LP The following describes the processing that occurs depending on what constant you pass to the event_mode argument. .TP 12 \fIAsyncThisDevice\fP If the specified device is frozen by the client, event processing for that device continues as usual. If the device is frozen multiple times by the client on behalf of multiple separate grabs, \fIAsyncThisDevice\fP thaws for all. \fIAsyncThisDevice\fP has no effect if the specified device is not frozen by the client, but the device need not be grabbed by the client. .TP 12 \fISyncThisDevice\fP If the specified device is frozen and actively grabbed by the client, event processing for that device continues normally until the next key or button event is reported to the client. At this time, the specified device again appears to freeze. However, if the reported event causes the grab to be released, the specified device does not freeze. \fISyncThisDevice\fP has no effect if the specified device is not frozen by the client or is not grabbed by the client. .TP 12 \fIReplayThisDevice\fP If the specified device is actively grabbed by the client and is frozen as the result of an event having been sent to the client (either from the activation of a GrabDeviceButton or from a previous AllowDeviceEvents with mode SyncThisDevice, but not from a GrabDevice), the grab is released and that event is completely reprocessed. This time, however, the request ignores any passive grabs at or above (toward the root) that the grab-window of the grab just released. The request has no effect if the specified device is not grabbed by the client or if it is not frozen as the result of an event. .TP 12 \fIAsyncOtherDevices\fP If the remaining devices are frozen by the client, event processing for them continues as usual. If the other devices are frozen multiple times by the client on behalf of multiple grabs, \fIAsyncOtherDevices\fP "thaws" for all. \fIAsyncOtherDevices\fP has no effect if the devices are not frozen by the client. .TP 12 \fISyncAll\fP If all devices are frozen by the client, event processing (for all devices) continues normally until the next button or key event is reported to the client for a grabbed device, at which time all devices again appear to freeze. However, if the reported event causes the grab to be released, then the devices do not freeze. If any device is still grabbed, then a subsequent event for it will still cause all devices to freeze. \fISyncAll\fP has no effect unless all devices are frozen by the client. If any device is frozen twice by the client on behalf of two separate grabs, \fISyncAll\fP thaws for both. A subsequent freeze for \fISyncAll\fP will only freeze each device once. .TP 12 \fIAsyncAll\fP If all devices are frozen by the client, event processing for all devices continues normally. If any device is frozen multiple times by the client on behalf of multiple separate grabs, \fIAsyncAll\fP thaws for all. \fIAsyncAll\fP has no effect unless all devices are frozen by the client. .LP \fIAsyncThisDevice\fP, \fISyncThisDevice\fP, and \fIReplayThisDevice\fP have no effect on the processing of events from the remaining devices. \fIAsyncOtherDevices\fP has no effect on the processing of events from the specified device. When the event_mode is \fISyncAll\fP or \fIAsyncAll\fP, the device parameter is ignored. .LP It is possible for several grabs of different devices by the same or different clients to be active simultaneously. If a device is frozen on behalf of any grab, no event processing is performed for the device. It is possible for a single device to be frozen because of several grabs. In this case, the freeze must be released on behalf of each grab before events can again be processed. .LP \fIXAllowDeviceEvents\fP can generate a \fIBadDevice\fP or \fIBadValue\fP error. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if the specified device is the X keyboard or X pointer device. .TP 12 \fIBadValue\fP An invalid mode was specified on the request. .SH "SEE ALSO" XGrabDevice(3X11) .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAllPlanes" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XAllPlanes, AllPlanes \(en return a value with all bits set to 1 suitable for plane argument. .XX "XAllPlanes" .XX "plane_mask, GC component" .Nz .SH "Synopsis" .Sy unsigned long XAllPlanes(\^) .As .Ae .\" .\" .SH "Arguments" None. .\" .\" .SH Returns A plane mask that includes all planes. .SH Description \f(CWXAllPlanes()\fP returns a value with all bits set to 1 suitable for use in a plane mask in a GC, color allocation procedure, or in image handling. .LP The C language macro \f(CWAllPlanes()\fP is equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXAllocColorCells()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXGetGCValues()\fP\s+1, \s-1\fIXGetImage()\fP\s+1, \s-1\fIXGetSubImage()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAllocClassHint" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XAllocClassHint" .XX "XClassHint structure:allocating" .XX "structures:XClassHint" .Na XAllocClassHint \(en allocate an \f(CWXClassHint\fP structure. .Nz .SH "Synopsis" .Sy XClassHint *XAllocClassHint\^(\ \^) .ad .SH Returns The allocated structure. .SH "Availability" Release 4 and later. .SH Description .LP .XX "XSetWMProperties:calling" .XX "XSetClassHint:calling" \f(CWXAllocClassHint()\fR allocates and returns a pointer to an \f(CWXClassHint\fR structure, for use in calling \f(CWXSetWMProperties()\fP, \f(CWXGetClassHint()\fP, or \f(CWXSetClassHint()\fP. Note that the pointer fields in the \f(CWXClassHint\fR structure are initially set to \f(CWNULL\fP. If insufficient memory is available, \f(CWXAllocClassHint()\fR returns \f(CWNULL\fP. To free the memory allocated to this structure, use \f(CWXFree()\fR. .LP .XX "binary compatibility:and structure sizes" .XX "structure sizes:and binary compatibility" The purpose of this function is to avoid compiled-in structure sizes, so that object files will be binary compatible with later releases that may have new members added to structures. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .XX "XClassHint structure" .Ps 0 typedef struct { char *res_name; char *res_class; } XClassHint; .Pe .SH "See Also" \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAllocColor" "Xlib \- Color Cells" .ds ]W Xlib Reference Manual .SH "Name" .XX "XAllocColor" .XX "colorcells:read-only" .Na XAllocColor \(en allocate a read-only colormap cell with closest hardware-supported color. .Nz .SH "Synopsis" .Sy Status XAllocColor\^(\^\f(CIdisplay\f(CW, \f(CIcolormap\f(CW\^, \f(CIcolorcell_in_out\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcolormap\f(CW\^; XColor *\f(CIcolorcell_in_out\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcolormap\fP .88i Specifies the ID of the colormap in which the colorcell is to be allocated. .IP \f(CIcolorcell_in_out\fP .88i Specifies desired RGB values, and also returns the pixel value and the RGB values actually used in the colormap. .SH Returns Zero on failure, non-zero on success. .SH Description \f(CWXAllocColor()\fR returns the pixel value of a read-only (shareable) colorcell. The requested RGB values are placed in \f(CWcolorcell_in_out\fR, which is also used to return the allocated pixel value and the actual RGB values of that colorcell. If \f(CWXAllocColor()\fR succeeds, it returns non-zero. If it fails, it returns zero. .LP \f(CWXAllocColor()\fR acts differently on static and dynamic visuals. On \f(CWPseudoColor\fR, \f(CWDirectColor\fR, and \f(CWGrayScale\fR visuals, \f(CWXAllocColor()\fR fails if there are no unallocated colorcells and no allocated read-only cell exactly matches the requested RGB values. On \f(CWStaticColor\fR, \f(CWTrueColor\fR, and \f(CWStaticGray\fR visuals, \f(CWXAllocColor()\fR returns the closest RGB values available in the colormap. The \f(CWcolorcell_in_out\fR structure returns the actual RGB values allocated. .LP \f(CWXAllocColor()\fP does not use or affect the \f(CWflags\fP member of the \f(CWXColor\fP structure. .LP For more information, see Volume One, Chapter 7, \fIColor\fR. .SH "Structures" .Ps typedef struct { unsigned long pixel; unsigned short red, green, blue; char flags; /* DoRed, DoGreen, DoBlue */ char pad; } XColor; .Pe .Nd 10 .SH Errors .IP "\&\f(CWBadColor\fP" 1i \f(CWcolormap\fR is invalid. .Nd 10 .SH "See Also" \s-1\fIXBlackPixel()\fP\s+1, \s-1\fIXWhitePixel()\fP\s+1, \s-1\fIXAllocColorCells()\fP\s+1, \s-1\fIXAllocColorPlanes()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXFreeColors()\fP\s+1, \s-1\fIXLookupColor()\fP\s+1, \s-1\fIXParseColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1, \s-1\fIXStoreNamedColor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .de Su \" if $1 = +, this gives a superscript; $1 = - gives a subscript. . \" If 3 args, $2=regular text; $3=super/subscripted text w/pre-space . \" If 2 args, $1=super/subscripted text with post-space .if "\\$1"+" \{\ . if \\n(.$=3 \\$2\v'-3p'\s-3\h'2p'\\$3\v'3p'\s0 . if \\n(.$=2 \v'-3p'\s-3\\$2\v'3p'\s0\h'2p'\} .if "\\$1"-" \{\ . if \\n(.$=3 \\$2\v'3p'\s-3\h'2p'\\$3\v'-3p'\s0 . if \\n(.$=2 \v'3p'\s-3\\$2\v'-3p'\s0\h'2p'\} .. .RH "XAllocColorCells" "Xlib \- Color Cells" .ds ]W Xlib Reference Manual .SH "Name" .XX "XAllocColorCells" .XX "colorcells:read-write" .Na XAllocColorCells \(en allocate read/write (nonshared) colorcells. .Nz .SH "Synopsis" .Sy Status XAllocColorCells\^(\^\f(CIdisplay\f(CW, \f(CIcolormap\f(CW\^, \f(CIcontig\f(CW\^, \f(CIplane_masks_return\f(CW\^, \f(CInplanes\f(CW\^, \f(CIpixels_return\f(CW\^, \f(CInpixels_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcolormap\f(CW\^; Bool \f(CIcontig\f(CW\^; unsigned long \f(CIplane_masks_return\f(CW[\f(CInplanes\f(CW]\^; unsigned int \f(CInplanes\f(CW\^; unsigned long \f(CIpixels_return\f(CW[\f(CInpixels_return\f(CW]\^; unsigned int \f(CInpixels_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcolormap\fP 1i Specifies the ID of the colormap in which the colorcell is to be allocated. .IP \f(CIcontig\fP 1i Specifies a boolean value. Pass \f(CWTrue\fP if the planes must be contiguous or \f(CWFalse\fP if the planes need not be contiguous. .IP \f(CIplane_mask\fP 1i Returns an array of plane masks. .\" *** JIM: NEED MORE INFO FOR THIS. *** .IP \f(CInplanes\fP 1i Specifies the number of plane masks returned in the plane masks array. Must be nonnegative. .IP \f(CIpixels_return\fP 1i Returns an array of pixel values. .IP \f(CInpixels_return\fP 1i Specifies the number of pixel values returned in the \f(CIpixels_return\fP array. Must be positive. .SH Returns Zero on failure, non-zero on success. .SH Description \f(CWXAllocColorCells()\fP allocates read/write colorcells in a read/write colormap. If \f(CWnpixels_return\fP and \f(CWnplanes\fP are requested, then \f(CWnpixels_return\fP base values and \f(CWnplanes\fP plane masks are returned. No mask will have any bits in common with any other mask, or with any of the pixels. By ORing together each of the \f(CWpixels_return\fP with any combination of the \f(CWplane_masks_return\fP, .Su + \f(CWnpixels_return\fP*2 (\f(CInplanes\fP) distinct pixel values can be produced. For \f(CWGrayScale\fP or \f(CWPseudoColor\fP, each mask will have exactly one bit, and for \f(CWDirectColor\fP each will have exactly three bits. If \f(CIcontig\fP is \f(CWTrue\fP, then if all plane masks are ORed together, a single contiguous set of bits will be formed for .hw Gray-Scale \f(CWGrayScale\fP or \f(CWPseudoColor\fP and three contiguous sets of bits (one within each pixel subfield) for .ne 8 \f(CWDirectColor\fP. The RGB values of the allocated entries are undefined until set with \f(CWXStoreColor\fP, \f(CWXStoreColors()\fP, or \f(CWXStoreNamedColor()\fP. .LP \f(CWStatus\fP is zero on failure, and non-zero on success. .LP For more information, see Volume One, Chapter 7, \fIColor\fR. .ne 5 .SH "Errors" .IP "\f(CWBadColor\fP" 1i .sp -.25 .IP "\f(CWBadValue\fP" \f(CInplanes\fP is negative. .br \f(CInpixels_return\fP is not positive. .SH "See Also" \s-1\fIXBlackPixel()\fP\s+1, \s-1\fIXWhitePixel()\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocColorPlanes()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXFreeColors()\fP\s+1, \s-1\fIXLookupColor()\fP\s+1, \s-1\fIXParseColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1, \s-1\fIXStoreNamedColor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .de Su \" if $1 = +, this gives a superscript; $1 = - gives a subscript. . \" If 3 args, $2=regular text; $3=super/subscripted text w/pre-space . \" If 2 args, $1=super/subscripted text with post-space .if "\\$1"+" \{\ . if \\n(.$=3 \\$2\v'-3p'\s-3\h'2p'\\$3\v'3p'\s0 . if \\n(.$=2 \v'-3p'\s-3\\$2\v'3p'\s0\h'2p'\} .if "\\$1"-" \{\ . if \\n(.$=3 \\$2\v'3p'\s-3\h'2p'\\$3\v'-3p'\s0 . if \\n(.$=2 \v'3p'\s-3\\$2\v'-3p'\s0\h'2p'\} .. .RH "XAllocColorPlanes" "Xlib \- Color Cells" .ds ]W Xlib Reference Manual .SH "Name" .XX "XAllocColorPlanes" .XX "color planes:allocating read/write" .Na XAllocColorPlanes \(en allocate read/write (nonshareable) color planes. .Nz .SH "Synopsis" .Sy Status XAllocColorPlanes\^(\^\f(CIdisplay\f(CW, \f(CIcolormap\f(CW\^, \f(CIcontig\f(CW\^, \f(CIpixels_return\f(CW\^, \f(CInpixels_return\f(CW\^, \f(CInreds\f(CW\^, \f(CIngreens\f(CW\^, \f(CInblues\f(CW\^, \f(CIrmask_return\f(CW\^, \f(CIgmask_return\f(CW\^, \f(CIbmask_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcolormap\f(CW\^; Bool \f(CIcontig\f(CW\^; unsigned long \f(CIpixels_return\f(CW[\f(CInpixels\fP]\^; int \f(CInpixels\f(CW\^; int \f(CInreds\f(CW\^, \f(CIngreens\f(CW\^, \f(CInblues\f(CW\^; unsigned long *\f(CIrmask_return\f(CW\^, *\f(CIgmask_return\f(CW\^, *\f(CIbmask_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.25i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcolormap\fP Specifies the ID of the colormap to be used. .IP \f(CIcontig\fP Specifies a boolean value. Pass \f(CWTrue\fP if the planes must be contiguous or \f(CWFalse\fP if the planes do not need to be contiguous. .IP \f(CIpixels_return\fP Returns an array of pixel values. .IP \f(CInpixels\fP Specifies the number of pixel values returned in the pixels array. Must be positive. .IP \f(CInreds\fP .br .ns .IP \f(CIngreens\fP .br .ns .IP \f(CInblues\fP .sp -3 Specify the number of red, green, and blue planes (shades). Must be nonnegative. .sp .5.25 .IP \f(CIrmask_return\fP Return bit masks for the red, green, and blue planes. .br .ns .IP \f(CIgmask_return\fP .br .ns .IP \f(CIbmask_return\fP .SH Returns Zero on failure, non-zero on success. .SH Description If \f(CInpixels\fP colors, \f(CInreds\fP reds, \f(CIngreens\fP greens, and \f(CInblues\fP blues are requested, then \f(CInpixels\fP base values are returned, and the masks have \f(CInreds\fP, \f(CIngreens\fP, and \f(CInblues\fP bits set to 1 respectively. No mask will have any bits in common with any other mask, or with any of the \&\f(CIpixels_return\fP. Unique pixel values are generated by ORing together subsets of masks with each item in the \&\f(CIpixels_return\fP list (\&\f(CIpixels_return\fP does not by itself contain pixel values). In doing this, note that \f(CInpixels\fP* (\c .Su + 2 (\f(CInreds\fP+\f(CIngreens\fP+\f(CInblues\fP) ) distinct pixel values are allocated. .LP If \f(CIcontig\fP is \f(CWTrue\fP, then each mask will have a contiguous set of bits. For \f(CWDirectColor\fP, each mask will lie within the corresponding pixel subfield. .LP Note, however, that there are actually only .Su + \f(CInpixels\fP*(2 \f(CInreds\fP ) independent red entries, .Su + \f(CInpixels\fP*(2 \f(CIngreens\fP ) independent green entries, and .Su + \f(CInpixels\fP*(2 \f(CInblues\fP ) independent blue entries in the colormap. This is true even for \f(CWPseudoColor\fP. When the pixel value of a colormap entry is changed using \f(CWXStoreColors()\fP or \f(CWXStoreNamedColor()\fP, the pixel is decomposed according to \f(CIrmask_return\fP, \f(CIgmask_return\fP, and .ne 2 \f(CIbmask_return\fP and the corresponding pixel subfield entries are updated. .LP \f(CWStatus\fP is zero on failure, and non-zero on success. .LP For more information, see Volume One, Chapter 7, \fIColor\fR. .SH "Errors" .IP "\f(CWBadColor\fP" 1i \f(CWcolormap\fR is invalid. .br .IP "\f(CWBadValue\fP" \f(CInpixels_return\fP is not positive. .br At least one of \f(CInreds\fP, \f(CIngreens\fP, \f(CInblues\fP is negative. .SH "See Also" \s-1\fIXBlackPixel()\fP\s+1, \s-1\fIXWhitePixel()\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocColorCells()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXFreeColors()\fP\s+1, \s-1\fIXLookupColor()\fP\s+1, \s-1\fIXParseColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1, \s-1\fIXStoreNamedColor()\fP\s+1. .\"last line comment .TH XAllocColor.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XAllocColor@XAllocColoA .sp .5 XAllocColorCells@XAllocColoB .sp .5 XAllocColorPlanes@XAllocColoC .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAllocIconSize" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XAllocIconSize" .Na .XX "XIconSize structure:allocating" .XX "structures:XIconSize" XAllocIconSize \(en allocate an \f(CWXIconSize\fP structure. .Nz .SH "Synopsis" .Sy XIconSize *XAllocIconSize\^(\ \^) .SH Returns The allocated structure. .SH "Availability" Release 4 and later. .SH Description .XX "XGetIconSizes:calling" .XX "XSetIconSizes:calling" \f(CWXAllocIconSize()\fR allocates and returns a pointer to an \f(CWXIconSize\fR structure, for use in calling \f(CWXGetIconSizes()\fP or \f(CWXSetIconSizes()\fP. Note that all fields in the \f(CWXIconSize\fR structure are initially set to zero. If insufficient memory is available, \f(CWXAllocIconSize()\fR returns \f(CWNULL\fP. To free the memory allocated to this structure, use \f(CWXFree()\fR. .LP .XX "binary compatibility:and structure sizes" The purpose of this function is to avoid compiled-in structure sizes, so that object files will be binary compatible with later releases that may have new members added to structures. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .XX "XIconSize structure" .Ps 0 typedef struct { int min_width, min_height; int max_width, max_height; int width_inc, height_inc; } XIconSize; .Pe .SH "See Also" \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAllocNamedColor" "Xlib \- Color Cells" .ds ]W Xlib Reference Manual .SH "Name" .XX "XAllocNamedColor" .XX "colorcells:read-only" .Na XAllocNamedColor \(en allocate a read-only colorcell from color name. .Nz .SH "Synopsis" .Sy Status XAllocNamedColor\^(\^\f(CIdisplay\f(CW, \f(CIcolormap\f(CW\^, \f(CIcolor_name\f(CW\^, \f(CIscreen_def_return\f(CW\^, \f(CIexact_def_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcolormap\f(CW\^; char *\f(CIcolor_name\f(CW\^; XColor *\f(CIscreen_def_return\f(CW\^; XColor *\f(CIexact_def_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcolormap\fP 1i Specifies the ID of the colormap in which the colorcell will be allocated. .IP \f(CIcolor_name\fP 1i Specifies the color name string (for example, "red") you want. Uppercase or lowercase does not matter. If the color name is not in the Host Portable Character Encoding, the result is implementation-dependent. .IP \f(CIscreen_def_return\fP 1i Returns the pixel value and RGB values actually used in the colormap. This is the closest color supported by the hardware. .IP \f(CIexact_def_return\fP 1i Returns the exact RGB values from the database corresponding to the \f(CIcolor_name\fP supplied. .SH Returns Zero on failure, non-zero on success. .SH Description .XX "color names:determining RGB values for" .XX "color:RGB values;for color names" \f(CWXAllocNamedColor()\fP determines the RGB values for the specified \f(CIcolor_name\fP from the color database, and then allocates a read-only colorcell with the closest color available, as described under \f(CWXAllocColor()\fP. .LP Like \f(CWXAllocColor\fP, \f(CWXAllocNamedColor()\fR acts differently on static and dynamic visuals. On \f(CWPseudoColor\fR, \f(CWDirectColor\fR, and \f(CWGrayScale\fR visuals, \f(CWXAllocNamedColor()\fR fails if there are no unallocated colorcells and no allocated read-only colorcell exactly matches the database definition of the requested color. On \f(CWStaticColor\fR, \f(CWTrueColor\fR, and \f(CWStaticGray\fR visuals, \f(CWXAllocNamedColor()\fR returns the closest RGB values (to the database definition of the requested color) available in the colormap. Both the database definition of the color, and the color actually allocated are returned. .LP .ne 12 \f(CWXAllocNamedColor()\fP returns a \f(CWStatus\fP of zero if \f(CIcolor_name\fP was not found in the database or if the color could not be allocated. The function returns non-zero when it succeeds. .LP For more information, see Volume One, Chapter 7, \fIColor\fR. .SH "Errors" .IP "\f(CWBadColor\fP" 1i \f(CWcolormap\fR is invalid. .SH "Structures" .Ps typedef struct { unsigned long pixel; unsigned short red, green, blue; char flags; /* DoRed, DoGreen, DoBlue */ char pad; } XColor; .Pe .SH "See Also" \s-1\fIXBlackPixel()\fP\s+1, \s-1\fIXWhitePixel()\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocColorCells()\fP\s+1, \s-1\fIXAllocColorPlanes()\fP\s+1, \s-1\fIXFreeColors()\fP\s+1, \s-1\fIXLookupColor()\fP\s+1, \s-1\fIXParseColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1, \s-1\fIXStoreNamedColor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAllocSizeHints" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XAllocSizeHints" .XX "XSizeHints structure:allocating" .XX "structures:XSizeHints" .Na XAllocSizeHints \(en allocate an \f(CWXSizeHints\fP structure. .Nz .SH "Synopsis" .Sy XSizeHints *XAllocSizeHints\^(\ \^) .SH Returns The allocated structure. .SH "Availability" Release 4 and later. .SH Description .LP .XX "XSetWMProperties:calling" .XX "XSetWMNormalHints:calling" .XX "XGetWMNormalHints:calling" \f(CWXAllocSizeHints()\fR allocates and returns a pointer to an \f(CWXSizeHints\fR structure, for use in calling \f(CWXSetWMProperties()\fP, \f(CWXSetWMNormalHints()\fP, or \f(CWXGetWMNormalHints()\fP. Note that all fields in the \f(CWXSizeHints\fR structure are initially set to zero. If insufficient memory is available, \f(CWXAllocSizeHints()\fR returns \f(CWNULL\fP. To free the memory allocated to this structure, use \f(CWXFree()\fR. .LP The purpose of this function is to avoid compiled-in structure sizes, so that object files will be binary compatible with later releases that may have new members added to structures. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .LP .Ps typedef struct { long flags; /* marks which fields in this structure are defined */ int x, y; /* Obsolete */ int width, height; /* Obsolete */ int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; int base_width, base_height; int win_gravity; } XSizeHints; .Pe .SH "See Also" \s-1\fIXGetWMNormalHints()\fP\s+1, \s-1\fIXSetWMNormalHints()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAllocStandardColormap" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XAllocStandardColormap" .XX "XStandardColormap structure:allocating" .XX "structures:XStandardColormap" .sp -.25 .Na XAllocStandardColormap \(en allocate an \f(CWXStandardColormap\fP structure. .Nz .sp -.25 .SH "Synopsis" .Sy XStandardColormap *XAllocStandardColormap\^(\ \^) .sp -.25 .SH Returns The allocated structure. .sp -.25 .SH "Availability" Release 4 and later. .sp -.25 .SH Description .XX "XGetRGBColormaps:calling" .XX "XSetRGBColormaps:calling" \f(CWXAllocStandardColormap()\fR allocates and returns a pointer to an \f(CWXStandardColormap\fR structure for use in calling \f(CWXGetRGBColormaps()\fP or \f(CWXSetRGBColormaps()\fP. Note that all fields in the \f(CWXStandardColormap\fR structure are initially set to zero. If insufficient memory is available, \f(CWXAllocStandardColormap()\fR returns \f(CWNULL\fP. To free the memory allocated to this structure, use \f(CWXFree()\fR. .sp -.25 .LP The purpose of this function is to avoid compiled-in structure sizes, so that object files will be binary compatible with later releases that may have new members added to structures. .LP For more information, see Volume One, Chapter 7, \fIColor\fP. .SH "Structures" .ft CW .ps 9 /* value for killed field */ .sp .1 .in #define \f(CWReleaseByFreeingColormap\fR \f(CW\^( (XID) 1L)\fP .in .sp .5 .ft .ps .XX "XStandardColormap structure" .Ps 0 typedef struct { Colormap colormap; unsigned long red_max; unsigned long red_mult; unsigned long green_max; unsigned long green_mult; unsigned long blue_max; unsigned long blue_mult; unsigned long base_pixel; VisualID visualid; XID killid; } XStandardColormap; .Pe .SH "See Also" \s-1\fIXGetRGBColormaps()\fP\s+1, \s-1\fIXSetRGBColormaps()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAllocWMHints" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XAllocWMHints" .XX "XWMHints structure:allocating" .XX "structures:XWMHints" .Na XAllocWMHints \(en allocate an \f(CWXWMHints\fP structure. .Nz .SH "Synopsis" .Sy XWMHints *XAllocWMHints\^(\ \^) .SH Returns The allocated structure. .SH "Availability" Release 4 and later. .SH Description .LP .XX "XSetWMProperties:calling" .XX "XSetWMHints:calling" .XX "XGetWMHints:calling" The \f(CWXAllocWMHints()\fR function allocates and returns a pointer to an \f(CWXWMHints\fR structure, for use in calling \f(CWXSetWMProperties()\fP, \f(CWXSetWMHints()\fP, or \f(CWXGetWMHints()\fP. Note that all fields in the \f(CWXWMHints\fR structure are initially set to zero. If insufficient memory is available, \f(CWXAllocWMHints()\fR returns \f(CWNULL\fP. To free the memory allocated to this structure, use \f(CWXFree()\fR. .LP The purpose of this function is to avoid compiled-in structure sizes, so that object files will be binary compatible with later releases that may have new members added to structures. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .XX "XWMHints structure" .Ps 0 typedef struct { long flags; /* marks which fields in this structure are defined */ Bool input; /* does this application rely on the window manager to get keyboard input? */ int initial_state; /* see below */ Pixmap icon_pixmap; /* pixmap to be used as icon */ Window icon_window; /* window to be used as icon */ int icon_x, icon_y; /* initial position of icon */ Pixmap icon_mask; /* pixmap to be used as mask for icon_pixmap */ XID window_group; /* id of related window group */ /* this structure may be extended in the future */ } XWMHints; .Pe .SH "See Also" \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAllowEvents" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XAllowEvents" .XX "events:keyboard" .XX "events:pointer" .Na XAllowEvents \(en control the behavior of keyboard and pointer events when these resources are grabbed. .Nz .SH "Synopsis" .Sy XAllowEvents\^(\^\f(CIdisplay\f(CW, \f(CIevent_mode\f(CW\^, \f(CItime\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int \f(CIevent_mode\f(CW\^; Time \f(CItime\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIevent_mode\fP 1i Specifies the event mode. Pass one of these constants: \f(CWAsyncPointer\fP, \f(CWSyncPointer\fP, \f(CWAsyncKeyboard\fP, \f(CWSyncKeyboard\fP, \f(CWReplayPointer\fP, \f(CWReplayKeyboard\fP, \f(CWAsyncBoth\fP, or \f(CWSyncBoth\fP. .IP \f(CItime\fP 1i Specifies the time when the grab should take place. .hw time-stamp Pass either a timestamp, expressed in milliseconds, or the constant \f(CWCurrentTime\fP. .SH Description \f(CWXAllowEvents()\fP releases the events queued in the server since the last \f(CWXAllowEvents()\fR call for the same device and by the same client. Events are queued in the server (not released to Xlib to propagate into Xlib's queues) only when the client has caused a device to "freeze" (by grabbing the device with mode \f(CWGrabModeSync\fP). The request has no effect if \f(CItime\fP is earlier than the last-grab time or later than the current server time. .LP The \f(CIevent_mode\fP argument controls what device events are released for and just how and when they are released. The \f(CIevent_mode\fP is interpreted as follows: .IP "\f(CWAsyncPointer\fP" 1.5i .XX "AsyncPointer event mode" If \f(CWXAllowEvents()\fP is called with \f(CWAsyncPointer\fR while the pointer is frozen by the client, pointer event processing resumes normally, even if the pointer is frozen twice by the client on behalf of two separate grabs. \f(CWAsyncPointer\fP has no effect if the pointer is not frozen by the client, but the pointer need not be grabbed by the client. .XX "AsyncKeyboard event mode" .IP "\f(CWAsyncKeyboard\fP" 1.5i If \f(CWXAllowEvents()\fP is called with \f(CWAsyncKeyboard\fR while the keyboard is frozen by the client, keyboard event processing resumes normally, even if the keyboard is frozen twice by the client on behalf of two separate grabs. \f(CWAsyncKeyboard\fP has no effect if the keyboard is not frozen by the client, but the keyboard need not be grabbed by the client. .XX "SyncPointer event mode" .IP "\f(CWSyncPointer\fP" 1.5i If \f(CWXAllowEvents()\fP is called with \f(CWSyncPointer\fR while the pointer is frozen by the client, normal pointer event processing continues until the next \f(CWButtonPress\fP or \f(CWButtonRelease\fP event is reported to the client. At this time, the pointer again appears to freeze. However, if the reported event causes the pointer grab to be released, then the pointer does not freeze, which is the case when an automatic grab is released by a \f(CWButtonRelease\fP or when \f(CWXGrabButton()\fP or \f(CWXGrabKey()\fP has been called and the specified key or button is released. \f(CWSyncPointer\fP has no effect if the pointer is not frozen or not grabbed by the client. .XX "SyncKeyboard event mode" .IP \f(CWSyncKeyboard\fP 1.5i If \f(CWXAllowEvents()\fP is called with \f(CWSyncKeyboard\fR while the keyboard is frozen by the client, normal keyboard event processing continues until the next \f(CWKeyPress\fP or \f(CWKeyRelease\fP event is reported to the client. At this time, the keyboard again appears to freeze. However, if the reported event causes the keyboard grab to be released, then the keyboard does not freeze, which is the case when an automatic grab is released by a \f(CWButtonRelease\fP or when \f(CWXGrabButton()\fP or \f(CWXGrabKey()\fP has been called and the specified key or button is released. \f(CWSyncKeyboard\fP has no effect if the keyboard is not frozen or not grabbed by the client. .XX "ReplayPointer event mode" .IP "\f(CWReplayPointer\fP" 1.5i This symbol has an effect only if the pointer is grabbed by the client and thereby frozen as the result of an event. In other words, \f(CWXGrabButton()\fP must have been called and the selected button/key combination pressed, or an automatic grab (initiated by a \f(CWButtonPress\fP) must be in effect, or a previous \f(CWXAllowEvents()\fP must have been called with mode \f(CWSyncPointer\fP. If the \f(CWpointer_mode\fP of the \f(CWXGrabPointer()\fP was .hw Grab-Mode-Sync \f(CWGrabModeSync\fP, then the grab is released and the releasing event is processed as if it had occurred after the release, ignoring any passive grabs at or above in the hierarchy (towards the root) on the grab-window of the grab just released. .XX "ReplayKeyboard event mode" .IP "\f(CWReplayKeyboard\fP" 1.5i This symbol has an effect only if the keyboard is grabbed by the client and if the keyboard is frozen as the result of an event. In other words, \f(CWXGrabKey()\fP must have been called and the selected key combination pressed, or a previous \f(CWXAllowEvents()\fP must have been called with mode \f(CWSyncKeyboard\fP. If the \f(CWpointer_mode\fP or \f(CWkeyboard_mode\fP of the \f(CWXGrabKey()\fP was \f(CWGrabModeSync\fP, then the grab is released and the releasing event is processed as if it had occurred after the release, ignoring any passive grabs at or above in the hierarchy (towards the root). .XX "SyncBoth event mode" .IP \f(CWSyncBoth\fP 1.5i \f(CWSyncBoth\fP has the effect described for both \f(CWSyncKeyboard\fP and \f(CWSyncPointer\fP. \f(CWSyncBoth\fP has no effect unless both pointer and keyboard are frozen by the client. If the pointer or keyboard is frozen twice by the client on behalf of two separate grabs, \f(CWSyncBoth\fP "thaws" for both (but a subsequent freeze for \f(CWSyncBoth\fP .ne 6 will only freeze each device once). .XX "AsyncBoth event mode" .IP \f(CWAsyncBoth\fP 1.5i \f(CWAsyncBoth\fP has the effect described for both \f(CWAsyncKeyboard\fP and \f(CWAsyncPointer\fP. \f(CWAsyncBoth\fP has no effect unless both pointer and keyboard are frozen by the client. If the pointer and the keyboard were frozen by the client, or if both are frozen twice by two separate grabs, event processing (for both devices) continues normally. If a device is frozen twice by the client on behalf of the two separate grabs, \f(CWAsyncBoth\fP releases events for both. .LP \f(CWAsyncPointer\fP, \f(CWSyncPointer\fP, and \f(CWReplayPointer\fP have no effect on the processing of keyboard events. \f(CWAsyncKeyboard\fP, \f(CWSyncKeyboard\fP, and \f(CWReplayKeyboard\fP have no effect on the processing of pointer events. .LP It is possible for both a pointer grab and a keyboard grab (by the same or different clients) to be active simultaneously. If a device is frozen on behalf of either grab, no event processing is performed for the device. It is also possible for a single device to be frozen because of both grabs. In this case, the freeze must be released on behalf of both grabs before events will be released. .LP For more information on event handling, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "Errors" .IP "\f(CWBadValue\fP" 1i Invalid mode constant. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAutoRepeatOff" "Xlib \- User Preferences" .ds ]W Xlib Reference Manual .SH "Name" .XX "XAutoRepeatOff" .XX "keyboard:auto-repeat;turning off" .XX "auto-repeat:turning off .Na XAutoRepeatOff \(en turn off the keyboard auto-repeat keys. .Nz .SH "Synopsis" .Sy XAutoRepeatOff\^(\^\f(CIdisplay\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Description \f(CWXAutoRepeatOff()\fP turns off auto-repeat for the keyboard. It sets the keyboard so that holding any non-modal key down will not result in multiple events. .SH "See Also" \s-1\fIXAutoRepeatOn()\fP\s+1, \s-1\fIXBell()\fP\s+1, \s-1\fIXChangeKeyboardControl()\fP\s+1, \s-1\fIXGetDefault()\fP\s+1, \s-1\fIXGetKeyboardControl()\fP\s+1, \s-1\fIXGetPointerControl()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XAutoRepeatOn" "Xlib \- User Preferences" .ds ]W Xlib Reference Manual .SH "Name" .XX "XAutoRepeatOn" .XX "auto-repeat:turning on" .XX "keyboard:auto-repeat;turning on" .Na XAutoRepeatOn \(en turn on the keyboard auto-repeat keys. .Nz .SH "Synopsis" .Sy XAutoRepeatOn\^(\^\f(CIdisplay\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Description \f(CWXAutoRepeatOn()\fP sets the keyboard to auto-repeat; that is, holding any non-modal key down will result in multiple \f(CWKeyPress\fP and \f(CWKeyRelease\fP event pairs with the same \f(CWkeycode\fP member. Keys such as Shift Lock will still not repeat. .SH "See Also" \s-1\fIXAutoRepeatOff()\fP\s+1, \s-1\fIXBell()\fP\s+1, \s-1\fIXChangeKeyboardControl()\fP\s+1, \s-1\fIXGetDefault()\fP\s+1, \s-1\fIXGetKeyboardControl()\fP\s+1, \s-1\fIXGetPointerControl()\fP\s+1. .\"last line comment .TH XAutoRepeat.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XAutoRepeatOff@XAutoRepeaA .sp .5 XAutoRepeatOn@XAutoRepeaB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "\s-2XBaseFontNameListOfFontSet\s+2" "\s-1Xlib \- Internationalized Text Output\s+1" .ds ]W Xlib Reference Manual .SH Name .XX "XBaseFontNameListOfFontSet" .XX "font set:obtaining information about" .Na XBaseFontNameListOfFontSet \(en get the base font list of a font set. .Nz .SH Synopsis .Sy char *XBaseFontNameListOfFontSet\^(\^\f(CIfont_set\fP\^) .As XFontSet \f(CIfont_set\fP\^; .Ae .SH Arguments .IP \f(CIfont_set\fP 1i Specifies the font set. .SH Returns The base font list string. .SH Availability Release 5 and later. .SH Description \f(CWXBaseFontNameListOfFontSet()\fR returns the original base font name list supplied by the client when the \f(CWXFontSet\fR was created. A \f(CWNULL\fP-terminated string containing a list of comma-separated font names is returned as the value of the function. Whitespace may appear immediately on either side of separating commas. .LP If \f(CWXCreateFontSet()\fR obtained an XLFD (X Logical Font Description) name from the font properties for the font specified by a non-XLFD base name, the \f(CWXBaseFontNameListOfFontSet()\fR function will return the XLFD name instead of the non-XLFD base name. .LP The base font name list is owned by Xlib and should not be modified or freed by the client. It will be freed by a call to \f(CWXFreeFontSet()\fR on the associated \f(CWXFontSet\fR. Until freed, its contents will not be modified by Xlib. .SH "See Also" \s-1\fIXCreateFontSet()\fP\s+1, \s-1\fIXExtentsOfFontSet()\fP\s+1, \s-1\fIXFontsOfFontSet()\fP\s+1, \s-1\fIXLocaleOfFontSet()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XBell" "Xlib \- User Preferences" .ds ]W Xlib Reference Manual .SH "Name" .XX "XBell" .XX "bell:volume" .Na XBell \(en ring the bell. .Nz .SH "Synopsis" .Sy XBell\^(\^\f(CIdisplay\f(CW, \f(CIpercent\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int \f(CIpercent\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIpercent\fP Specifies the volume for the bell, relative to the base volume set with \f(CWXChangeKeyboardControl()\fP. Possible values are \-100 (off), through 0 (base volume), to 100 (loudest) inclusive. .SH Description Rings the bell on the keyboard at a volume relative to the base volume, if possible. \f(CIpercent\fP can range from \-100 to 100 inclusive (else a \f(CWBadValue\fP error). The volume at which the bell is rung when \f(CIpercent\fP is nonnegative is: .sp .5 .ti +5n \s9\f(CWvolume = base - [(base * \f(CIpercent\fP) / 100] + \f(CIpercent\fR\s0 .sp .5 and when \f(CIpercent\fP is negative: .sp .5 .ti +5n \s9\f(CWvolume = base + [(base * \f(CIpercent\fP) / 100]\fR\s0 .LP .XX "XChangeKeyboardControl:and bell volume" To change the base volume of the bell, set the \f(CWbell_percent\fP variable of \f(CWXChangeKeyboardControl()\fP. .SH "Errors" .IP "\f(CWBadValue\fP" 1i \f(CIpercent\fP < \-100 or \f(CIpercent\fP >100. .SH "See Also" \s-1\fIXAutoRepeatOff()\fP\s+1, \s-1\fIXAutoRepeatOn()\fP\s+1, \s-1\fIXChangeKeyboardControl()\fP\s+1, \s-1\fIXGetDefault()\fP\s+1, \s-1\fIXGetKeyboardControl()\fP\s+1, \s-1\fIXGetPointerControl()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XBitmap*" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XBitmapBitOrder, XBitmapPad, XBitmapUnit \(en query the bitmap format of a display. .XX "displays:querying bitmap format of" .Nz .SH "Synopsis" .XX "XBitmapUnit" .Sy int XBitmapUnit\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .XX "XBitmapBitOrder" .Sy int XBitmapBitOrder\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .XX "XBitmapPad" .Sy int XBitmapPad\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X Server; returned from \f(CWXOpenDisplay(\^)\fP. .SH Returns \f(CWXBitmapUnit()\fP and \f(CWXBitmapPad()\fP return a number of bits. \f(CWXBitmapBitOrder()\fP returns \f(CWLSBFirst\fP or \f(CWMSBFirst\fP. .SH Description .XX "image data:manipulating" These functions are used in connection with manipulating image data. .LP \f(CWXBitmapUnit()\fP returns the size of a bitmap's scanline unit in bits. The scanline is calculated in multiples of this value. .LP Within each bitmap unit, the left-most bit in the bitmap as displayed on the screen is either the least-significant or most-significant bit in the unit. \f(CWXBitmapBitOrder()\fP returns \f(CWLSBFirst\fP or \f(CWMSBFirst\fP to indicate the server's bit order. .LP Each scanline must be padded to a multiple of bits returned by \f(CWXBitmapPad()\fP. .LP The C language macros \f(CWBitmapUnit()\fP, \f(CWBitmapBitOrder()\fP, and \f(CWBitmapPad()\fP are equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXImageByteOrder()\fP\s+1, \s-1\fIXGetImage()\fP\s+1, \s-1\fIXPutImage()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XBlackPixel*" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XBlackPixel, XBlackPixelOfScreen, BlackPixel, BlackPixelOfScreen \(en get the black pixel value. .XX "pixel values:black" .XX "BlackPixel macro" .XX "XBlackPixel" .XX "XBlackPixelOfScreen" .Nz .SH "Synopsis" .Sy unsigned long XBlackPixelOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .Sy unsigned long XBlackPixel\^(\^\f(CIdisplay\fP\^, \^\f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; int \f(CIscreen_number\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIscreen\fP 1i Specifies the appropriate \f(CWScreen\fP structure. .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number. .\" .\" .SH Returns A pixel value. .SH Description Each screen has a default colormap which has pixel values for black and white already allocated. These functions return the black pixel value. Note that this pixel value only represents black in a screen's default colormap. .LP \f(CWXBlackPixel()\fP and \f(CWXBlackPixelOfScreen()\fP are equivalent except that they require different arguments. One requires a pointer to a \f(CWScreen\fP structure, while the other requires a screen number. Unless you already have the pointer to a \f(CWScreen\fP structure in a variable, \f(CWXBlackPixel*()\fP is more convenient. .LP The C language macros \f(CWBlackPixel()\fP and \f(CWBlackPixelOfScreen()\fP are equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXWhitePixel*()\fP\s+1, \s-1\fIXWhitePixelOfScreen()\fP\s+1, \s-1\fIXDefaultColormap*()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCellsOfScreen" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XCellsOfScreen, CellsOfScreen \(en return size of default colormap. .XX "XCellsOfScreen" .XX "colormaps:returning size of default" .Nz .SH "Synopsis" .Sy int XCellsOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIscreen\fP 1i Specifies the appropriate \f(CWScreen\fP structure. .\" .\" .SH Returns The number of colorcells in the colormap. .SH Description \f(CWXCellsOfScreen()\fP returns the number of colormap cells in the default colormap of the specified screen. .LP .XX "CellsOfScreen macro" The C language macro \f(CWCellsOfScreen()\fP is equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXDefaultColormap*()\fP\s+1, \s-1\fIXDefaultDepthOfScreen()\fP\s+1, \s-1\fIXDefaultVisualOfScreen()\fP\s+1. .\"last line comment .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XChDCtl.man,v 1.5 94/06/04 17:32:14 rws Exp $ .ds xL Programming With Xlib .TH XGetDeviceControl 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XGetDeviceControl, XChangeDeviceControl \- query and change input device controls .SH SYNTAX XDeviceControl * XGetDeviceControl\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fIcontrol\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br int *\fIcontrolType\fP\^; .br .sp int XChangeDeviceControl\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fIcontrolType\fP\^, \fIcontrol\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br int \fIcontrolType\fP\^; .br XDeviceControl *\fIcontrol\fP\^; .SH ARGUMENTS .TP 15 .I display Specifies the connection to the X server. .TP 15 .I device Specifies the device whose control is to be interrogated or modified. .TP 15 .I controlType Specifies the type of control to be interrogated or changed. .TP 15 .I control Specifies the address of an \fIXDeviceControl\fP structure that contains the new values for the Device. .SH DESCRIPTION These requests are provided to manipulate those input devices that support device control. A \fIBadMatch\fP error will be generated if the requested device does not support any device controls. .LP Valid device control types that can be used with these requests include the following: .TP 20 DEVICE_RESOLUTION Queries or changes the resolution of valuators on input devices. .LP The \fIXGetDeviceControl\fP request returns a pointer to an \fIXDeviceControl\fP structure. .LP \fIXGetDeviceControl\fP can generate a \fIBadDevice\fP or \fIBadMatch\fP error. .LP The \fIXChangeDeviceControl\fP request modifies the values of one control on the specified device. The control is identified by the id field of the \fIXDeviceControl\fP structure that is passed with the request. .LP \fIXChangeDeviceControl\fP can generate a \fIBadDevice\fP, \fIBadMatch\fP, or \fIBadValue\fP error. .SH STRUCTURES Each control is described by a structure specific to that control. These structures are defined in the file \fIXInput.h\fP. .LP \fIXDeviceControl\fP is a generic structure that contains two fields that are at the beginning of each class of control: .LP .DS .nf typedef struct { .br XID class; .br int length; .br } XDeviceControl; .fi .DE .LP The \fIXDeviceResolutionState\fP structure defines the information that is returned for device resolution for devices with valuators. .LP .DS .nf typedef struct { XID control; int length; int num_valuators; int *resolutions; int *min_resolutions; int *max_resolutions; } XDeviceResolutionState; .fi .DE .LP The \fIXDeviceResolutionControl\fP structure defines the attributes that can be controlled for keyboard Devices. .LP .DS .nf typedef struct { XID control; int length; int first_valuator; int num_valuators; int *resolutions; } XDeviceResolutionControl; .fi .DE .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if some other client has caused the specified device to become the X keyboard or X pointer device via the \fIXChangeKeyboardDevice\fP or \fIXChangePointerDevice\fP requests. .TP 12 \fIBadMatch\fP This error may occur if an \fIXGetDeviceControl\fP request was made specifying a device that has no controls or an \fIXChangeDeviceControl\fP request was made with an \fIXDeviceControl\fP structure that contains an invalid Device type. It may also occur if an invalid combination of mask bits is specified (\fIDvKey\fP but no \fIDvAutoRepeatMode\fP for keyboard Devices), or if an invalid KeySym is specified for a string Device. .TP 12 \fIBadValue\fP Some numeric value falls outside the range of values accepted by the \fIXChangeDeviceControl\fP request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error. .SH "SEE ALSO" .br \fI\*(xL\fP .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XChFCtl.man,v 1.5 94/06/04 17:32:15 rws Exp $ .ds xL Programming With Xlib .TH XGetFeedbackControl 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XGetFeedbackControl, XChangeFeedbackControl \- query and change input device feedbacks .SH SYNTAX XFeedbackState * XGetFeedbackControl\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fInum_feedbacks\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br int *\fInum_feedbacks\fP\^; .br .sp int XChangeFeedbackControl\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fImask\fP\^, \fIcontrol\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br Mask \fImask\fP\^; .br XFeedbackControl *\fIcontrol\fP\^; .SH ARGUMENTS .TP 15 .I display Specifies the connection to the X server. .TP 15 .I device Specifies the device whose feedbacks are to be queried or modified. .TP 15 .I num_feedbacks Specifies an address into which the number of feedbacks supported by the device is to be returned. .TP 15 .I mask Specifies a mask specific to each type of feedback that describes how the feedback is to be modified. .TP 15 .I control Specifies the address of an \fIXFeedbackControl\fP structure that contains the new values for the feedback. .SH DESCRIPTION These requests are provided to manipulate those input devices that support feedbacks. A \fIBadMatch\fP error will be generated if the requested device does not support feedbacks. Whether or not a given device supports feedbacks can be determined by examining the information returned by the \fIXOpenDevice\fP request. For those devices that support feedbacks, \fIXOpenDevice\fP will return an \fIXInputClassInfo\fP structure with the input_class field equal to the constant \fIFeedbackClass\fP (defined in the file \fIXI.h\fP). .LP The \fIXGetFeedbackControl\fP request returns a pointer to a list of \fIXFeedbackState\fP structures. Each item in this list describes one of the feedbacks supported by the device. The items are variable length, so each contains its length to allow traversal to the next item in the list. .LP The feedback classes that are currently defined are: \fIKbdFeedbackClass\fP, \fIPtrFeedbackClass\fP, \fIStringFeedbackClass\fP, \fIIntegerFeedbackClass\fP, \fILedFeedbackClass\fP, and \fIBellFeedbackClass\fP. These constants are defined in the file \fIXI.h\fP. An input device may support zero or more classes of feedback, and may support multiple feedbacks of the same class. Each feedback contains a class identifier and an id that is unique within that class for that input device. The id is used to identify the feedback when making an \fIXChangeFeedbackControl\fP request. .LP \fIXGetFeedbackControl\fP can generate a \fIBadDevice\fP or \fIBadMatch\fP error. .LP The \fIXChangeFeedbackControl\fP request modifies the values of one feedback on the specified device. The feedback is identified by the id field of the \fIXFeedbackControl\fP structure that is passed with the request. The fields of the feedback that are to be modified are identified by the bits of the mask that is passed with the request. .LP \fIXChangeFeedbackControl\fP can generate a \fIBadDevice\fP, \fIBadMatch\fP, or \fIBadValue\fP error. .SH STRUCTURES Each class of feedback is described by a structure specific to that class. These structures are defined in the file \fIXInput.h\fP. \fIXFeedbackState\fP and \fIXFeedbackControl\fP are generic structures that contain three fields that are at the beginning of each class of feedback: .LP .DS typedef struct { .br XID class; .br int length; .br XID id; .br } XFeedbackState, XFeedbackControl; .DE .LP The \fIXKbdFeedbackState\fP structure defines the attributes that are returned for feedbacks equivalent to those on the X keyboard. .LP .DS .nf typedef struct { XID class; int length; XID id; int click; int percent; int pitch; int duration; int led_mask; int global_auto_repeat; char auto_repeats[32]; } XKbdFeedbackState; .fi .DE .LP The \fIXPtrFeedbackState\fP structure defines the attributes that are returned for feedbacks equivalent to those on the the X pointer. .LP .DS .nf typedef struct { XID class; int length; XID id; int accelNum; int accelDenom; int threshold; } XPtrFeedbackState; .fi .DE .LP The \fIXIntegerFeedbackState\fP structure defines attributes that are returned for integer feedbacks. .LP .DS .nf typedef struct { XID class; int length; XID id; int resolution; int minVal; int maxVal; } XIntegerFeedbackState; .fi .DE .LP The \fIXStringFeedbackState\fP structure defines the attributes that are returned for string feedbacks. .LP .DS .nf typedef struct { XID class; int length; XID id; int max_symbols; int num_syms_supported; KeySym *syms_supported; } XStringFeedbackState; .fi .DE .LP The \fIXBellFeedbackState\fP structure defines the attributes that are returned for bell feedbacks. .LP .DS .nf typedef struct { XID class; int length; XID id; int percent; int pitch; int duration; } XBellFeedbackState; .fi .DE .LP The \fIXLedFeedbackState\fP structure defines the attributes that are returned for LED feedbacks. .LP .DS .nf typedef struct { XID class; int length; XID id; int led_values; } XLedFeedbackState; .fi .DE .LP The \fIXPrtFeedbackControl\fP structure defines the attributes that can be controlled for pointer feedbacks. .LP .DS .nf typedef struct { XID class; int length; XID id; int accelNum; int accelDenom; int threshold; } XPtrFeedbackControl; .fi .DE .LP The \fIXKbdFeedbackControl\fP structure defines the attributes that can be controlled for keyboard feedbacks. .LP .DS .nf typedef struct { XID class; int length; XID id; int click; int percent; int pitch; int duration; int led_mask; int led_value; int key; int auto_repeat_mode; } XKbdFeedbackControl; .fi .DE .LP The \fIXStringFeedbackControl\fP structure defines the attributes that can be controlled for string feedbacks. .LP .DS .nf typedef struct { XID class; int length; XID id; int num_keysyms; KeySym *syms_to_display; } XStringFeedbackControl; .fi .DE .LP The \fIXIntegerFeedbackControl\fP structure defines the attributes that can be controlled for integer feedbacks. .LP .DS .nf typedef struct { XID class; int length; XID id; int int_to_display; } XIntegerFeedbackControl; .fi .DE .LP The \fIXBellFeedbackControl\fP structure defines the attributes that can be controlled for bell feedbacks. .LP .DS .nf typedef struct { XID class; int length; XID id; int percent; int pitch; int duration; } XBellFeedbackControl; .fi .DE .LP The \fIXLedFeedbackControl\fP structure defines the attributes that can be controlled for LED feedbacks. .LP .DS .nf typedef struct { XID class; int length; XID id; int led_mask; int led_values; } XLedFeedbackControl; .fi .DE .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if some other client has caused the specified device to become the X keyboard or X pointer device via the \fIXChangeKeyboardDevice\fP or \fIXChangePointerDevice\fP requests. .TP 12 \fIBadMatch\fP This error may occur if an \fIXGetFeedbackControl\fP request was made specifying a device that has no feedbacks, or an \fIXChangeFeedbackControl\fP request was made with an \fIXFeedbackControl\fP structure that contains an invalid feedback type. It may also occur if an invalid combination of mask bits is specified (\fIDvKey\fP but no \fIDvAutoRepeatMode\fP for keyboard feedbacks), or if an invalid KeySym is specified for a string feedback. .TP 12 \fIBadValue\fP Some numeric value falls outside the range of values accepted by the \fIXChangeFeedbackControl\fP request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error. .SH "SEE ALSO" .br \fI\*(xL\fP .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XChKMap.man,v 1.5 94/06/04 17:32:17 rws Exp $ .ds xL Programming with Xlib .TH XGetDeviceKeyMapping 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XGetDeviceKeyMapping, XChangeDeviceKeyMapping \- query or change device key mappings .SH SYNTAX \fB XChangeDeviceKeyMapping(\^\fIdisplay\fP, \fIdevice\fP, \fIfirst_keycode\fP, \fIkeysyms_per_keycode\fP, \fIkeysyms\fP, \fIkeycode_count\fP\^) .nf Display *\fIdisplay\fP\^; XDevice *\fIdevice\fP\^; int \fIfirst_keycode\fP\^; int \fIkeysyms_per_keycode\fP\^; KeySym *\fIkeysyms\fP\^; int \fIkeycode_count\fP\^; KeySym *XGetDeviceKeyMapping(\^\fIdisplay\fP, \fIdevice\fP, \fIfirst_keycode\fP, \fIkeycode_count\fP, \fIkeysyms_per_keycode_return\fP\^) Display *\fIdisplay\fP\^; XDevice *\fIdevice\fP\^; KeyCode \fIfirst_keycode\fP\^; int \fIkeycode_count\fP\^; int *\fIkeysyms_per_keycode_return\fP\^; .fi \fP .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device whose key mapping is to be queried or modified. .TP 12 .I first_keycode Specifies the first KeyCode to be returned. .TP 12 .I keycode_count Specifies the number of KeyCodes to be returned or modified. .TP 12 .I keysyms_per_keycode Specifies the number of KeySyms per KeyCode. .TP 12 .I keysyms_per_keycode_return Specifies the address of a variable into which the number of KeySyms per KeyCode will be returned. .TP 12 .I keysyms Specifies the address of an array of KeySyms. .SH DESCRIPTION For the specified device, the \fIXGetDeviceKeyMapping\fP request returns the symbols for the specified number of KeyCodes starting with first_keycode. The value specified in first_keycode must be greater than or equal to min_keycode as returned by \fIXListInputDevices\fP, or a \fIBadValue\fP error results. In addition, the following expression must be less than or equal to max_keycode as returned by \fIXListInputDevices\fP: .LP .DS first_keycode + keycode_count \- 1 .DE .LP If this is not the case, a \fIBadValue\fP error results. The number of elements in the KeySyms list is: .LP .DS keycode_count * keysyms_per_keycode_return .DE .LP KeySym number N, counting from zero, for KeyCode K has the following index in the list, counting from zero: .DS (K \- first_code) * keysyms_per_code_return + N .DE .LP The X server arbitrarily chooses the keysyms_per_keycode_return value to be large enough to report all requested symbols. A special KeySym value of \fINoSymbol\fP is used to fill in unused elements for individual KeyCodes. To free the storage returned by \fIXGetDeviceKeyMapping\fP, use \fIXFree\fP. .LP If the specified device does not support input class keys, a \fIBadMatch\fP error will result. .LP \fIXGetDeviceKeyMapping\fP can generate a \fIBadDevice\fP, \fIBadMatch\fP, or \fIBadValue\fP error. .LP For the specified device, the \fIXChangeDeviceKeyMapping\fP request defines the symbols for the specified number of KeyCodes starting with first_keycode. The symbols for KeyCodes outside this range remain unchanged. The number of elements in keysyms must be: .LP .DS num_codes * keysyms_per_keycode .DE .LP The specified first_keycode must be greater than or equal to min_keycode returned by \fIXListInputDevices\fP, or a \fIBadValue\fP error results. In addition, the following expression must be less than or equal to max_keycode as returned by \fIXListInputDevices\fP, or a \fIBadValue\fP error results: .LP .DS first_keycode + num_codes \- 1 .DE .LP KeySym number N, counting from zero, for KeyCode K has the following index in keysyms, counting from zero: .LP .DS (K \- first_keycode) * keysyms_per_keycode + N .DE .LP The specified keysyms_per_keycode can be chosen arbitrarily by the client to be large enough to hold all desired symbols. A special KeySym value of \fINoSymbol\fP should be used to fill in unused elements for individual KeyCodes. It is legal for \fINoSymbol\fP to appear in nontrailing positions of the effective list for a KeyCode. \fIXChangeDeviceKeyMapping\fP generates a \fIDeviceMappingNotify\fP event that is sent to all clients that have selected that type of event. .LP There is no requirement that the X server interpret this mapping. It is merely stored for reading and writing by clients. .LP If the specified device does not support input class keys, a \fIBadMatch\fP error results. .LP \fIXChangeDeviceKeyMapping\fP can generate a \fIBadDevice\fP, \fIBadMatch\fP, \fIBadAlloc\fP, or \fIBadValue\fP error. .LP .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if the specified device is the X keyboard or X pointer device. .TP 12 \fIBadMatch\fP This error may occur if an \fIXGetDeviceKeyMapping\fP or \fIXChangeDeviceKeyMapping\fP request was made specifying a device that has no keys. .TP 12 \fIBadValue\fP Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error. .TP 12 \fIBadAlloc\fP The server failed to allocate the requested resource or server memory. .SH "SEE ALSO" XSetDeviceButtonMapping(3X11) .br XSetDeviceModifierMapping(3X11) .br \fI\*(xL\fP .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XChMMap.man,v 1.5 94/06/04 17:32:18 rws Exp $ .ds xL Programming With Xlib .TH XGetDeviceModifierMapping 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XGetDeviceModifierMapping, XSetDeviceModifierMapping \- query or change device modifier mappings .SH SYNTAX \fB XSetDeviceModifierMapping(\^\fIdisplay\fP, \fIdevice\fP, \fImodmap\fP\^) .nf Display *\fIdisplay\fP\^; XDevice *\fIdevice\fP\^; XModifierKeymap *\fImodmap\fP\^; XModifierKeymap *XGetDeviceModifierMapping(\^\fIdisplay\fP, \fIdevice\fP\^) Display *\fIdisplay\fP\^; XDevice *\fIdevice\fP\^; .fi \fP .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device whose modifier mapping is to be queried or modified. .TP 12 .I modmap Specifies a pointer to the \fIXModifierKeymap\fP structure. .SH DESCRIPTION The \fIXSetDeviceModifierMapping\fP request specifies the KeyCodes of the keys (if any) that are to be used as modifiers for the specified device. If it succeeds, the X server generates a \fIDeviceMappingNotify\fP event, and \fIXSetDeviceModifierMapping\fP returns \fIMappingSuccess\fP. X permits at most eight modifier keys. If more than eight are specified in the \fIXModifierKeymap\fP structure, a \fIBadLength\fP error results. .LP The modifiermap member of the \fIXModifierKeymap\fP structure contains eight sets of max_keypermod KeyCodes, one for each modifier in the order \fIShift\fP, \fILock\fP, \fIControl\fP, \fIMod1\fP, \fIMod2\fP, \fIMod3\fP, \fIMod4\fP, and \fIMod5\fP. Only nonzero KeyCodes have meaning in each set, and zero KeyCodes are ignored. In addition, all of the nonzero KeyCodes must be in the range specified by min_keycode and max_keycode as returned by \fIXListInputDevices\fP, or a \fIBadValue\fP error results. No KeyCode may appear twice in the entire map, or a \fIBadValue\fP error results. .LP An X server can impose restrictions on how modifiers can be changed, for example, if certain keys do not generate up transitions in hardware, if auto-repeat cannot be disabled on certain keys, or if multiple modifier keys are not supported. If some such restriction is violated, the status reply is \fIMappingFailed\fP, and none of the modifiers are changed. If the new KeyCodes specified for a modifier differ from those currently defined and any (current or new) keys for that modifier are in the logically down state, \fIXSetDeviceModifierMapping\fP returns \fIMappingBusy\fP, and none of the modifiers is changed. .LP \fIXSetDeviceModifierMapping\fP can generate \fIBadLength\P, \fIBadDevice\fP, \fIBadMatch\fP, \fIBadAlloc\fP, and \fIBadValue\fP errors. .LP The \fIXGetDeviceModifierMapping\fP request returns a pointer to a newly created \fIXModifierKeymap\fP structure that contains the keys being used as modifiers. The structure should be freed after use by calling \fIXFreeModifierMapping \fP. If only zero values appear in the set for any modifier, that modifier is disabled. .LP \fIXGetDeviceModifierMapping\fP can generate \fIBadDevice\fP and \fIBadMatch\fP errors. .SH STRUCTURES The \fIXModifierKeymap\fP structure contains: .LP .nf typedef struct { int max_keypermod; KeyCode *modifiermap; } XModifierKeymap; .fi .LP .SH DIAGNOSTICS .TP 12 \fIBadLength\fP More than eight keys were specified in the \fIXModifierKeymap\fP structure. .TP 12 \fIBadAlloc\fP The server failed to allocate the requested resource or server memory. .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if the specified device is the X keyboard or X pointer device. .TP 12 \fIBadMatch\fP This error may occur if an \fIXGetDeviceModifierMapping\fP or \fIXChangeDeviceModifierMapping\fP request was made specifying a device that has no keys. .TP 12 \fIBadValue\fP Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error. .SH "SEE ALSO" XSetDeviceKeyMapping(3X11) .br XSetDeviceButtonMapping(3X11) .br \fI\*(xL\fP .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XChProp.man,v 1.6 94/06/04 17:32:19 rws Exp $ .ds xL Programming With Xlib .TH XChangeDeviceDontPropagateList 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XChangeDeviceDontPropagateList, XGetDeviceDontPropagateList \- query or change the dont-propagate-list for extension devices .SH SYNTAX XChangeDeviceDontPropagateList\^(\^\fIdisplay\fP, \fIwindow\fP\^, \fIcount\fP\^, \fIevent_list\fP\^, \fImode\fP\^) .br Display *\fIdisplay\fP\^; .br Window *\fIwindow\fP\^; .br int *\fIcount\fP\^; .br XEventClass *\fIevent_list\fP\^; .br int \fImode\fP\^; .br XEventClass *XGetDeviceDontPropagateList\^(\^\fIdisplay\fP, \fIwindow\fP\^, \fIcount\fP\^) .br Display *\fIdisplay\fP\^; .br Window *\fIwindow\fP\^; .br int *\fIcount\fP\^; .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I window Specifies the window whose dont-propagate-list is to be queried or modified. .TP 12 .I event_list Specifies a pointer to a list of event classes. .TP 12 .I mode Specifies the mode. You can pass \fIAddToList\fP , or \fIDeleteFromList\fP. .TP 12 .I count Specifies the number of event classes in the list. .SH DESCRIPTION The \fIXChangeDeviceDontPropagateList\fP request modifies the list of events that should not be propagated to ancestors of the event window. This request allows extension events to be added to or deleted from that list. By default, all events are propagated to ancestor windows. Once modified, the list remains modified for the life of the window. Events are not removed from the list because the client that added them has terminated. .LP Suppression of event propagation is not allowed for all input extension events. If a specified event class is one that cannot be suppressed, a \fIBadClass\fP error will result. Events that can be suppressed include \fIDeviceKeyPress\fP, \fIDeviceKeyRelease\fP, \fIDeviceButtonPress\fP, \fIDeviceButtonRelease\fP, \fIDeviceMotionNotify\fP, \fIProximityIn\fP, and \fIProximityOut\fP. .LP \fIXChangeDeviceDontPropagateList\fP can generate a \fIBadDevice\fP, \fIBadClass\fP, or \fIBadValue\fP error. .LP The \fIXGetDeviceDontPropagateList\fP request queries the list of events that should not be propagated to ancestors of the event window. .LP \fIXGetDeviceDontPropagateList\fP can generate a \fIBadClass\fP or \fIBadWindow\fP error. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if some other client has caused the specified device to become the X keyboard or X pointer device via the \fIXChangeKeyboardDevice\fP or \fIXChangePointerDevice\fP requests. .TP 12 \fIBadValue\fP Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error. .TP 12 \fIBadWindow\fP An invalid window id was specified. .TP 12 \fIBadClass\fP An invalid event class was specified. .SH "SEE ALSO" .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XChangeActivePointerGrab" "Xlib \- Pointer" .ds ]W Xlib Reference Manual .SH "Name" .XX "XChangeActivePointerGrab" .XX "pointers:grabbing" .Na XChangeActivePointerGrab \(en change the parameters of an active pointer grab. .Nz .SH "Synopsis" .Sy XChangeActivePointerGrab\^(\^\f(CIdisplay\f(CW, \f(CIevent_mask\f(CW\^, \f(CIcursor\f(CW\^, \f(CItime\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; unsigned int \f(CIevent_mask\f(CW\^; Cursor \f(CIcursor\f(CW\^; Time \f(CItime\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIevent_mask\fP 1i Specifies which pointer events are reported to the client. This mask is the bitwise OR of one or more of these pointer event masks: \f(CWButtonPressMask\fP, \f(CWButtonReleaseMask\fP, \f(CWEnterWindowMask\fP, \f(CWLeaveWindowMask\fP, \f(CWPointerMotionMask\fP, \f(CWPointerMotionHintMask\fP, \f(CWButton1MotionMask\fP, .hw Button5-Motion-Mask \f(CWButton2MotionMask\fP, \f(CWButton3MotionMask\fP, \f(CWButton4MotionMask\fP, \f(CWButton5MotionMask\fP, \f(CWButtonMotionMask\fP, \f(CWKeymapStateMask\fP. .IP \f(CIcursor\fP 1i Specifies the cursor that is displayed. A value of \f(CWNone\fP will keep the current cursor. .IP \f(CItime\fP 1i Specifies the time when the grab should take place. Pass either a timestamp, expressed in milliseconds, or the constant \f(CWCurrentTime\fP. .SH Description .XX "XGrabButton:and XChangeActivePointerGrab" \f(CWXChangeActivePointerGrab()\fP changes the characteristics of an active pointer grab, if the specified time is no earlier than the last pointer grab time and no later than the current X server time. \f(CWXChangeActivePointerGrab()\fP has no effect on the passive parameters of \f(CWXGrabButton()\fP. .LP For more information on pointer grabbing, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "Errors" .IP "\f(CWBadCursor\fP" 1i .sp -.25 .IP "\f(CWBadValue\fP" 1i The \f(CIevent_mask\fP argument is invalid. .SH "See Also" \s-1\fIXChangePointerControl()\fP\s+1, \s-1\fIXGetPointerControl()\fP\s+1, \s-1\fIXGetPointerMapping()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXQueryPointer()\fP\s+1, \s-1\fIXSetPointerMapping()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1, \s-1\fIXWarpPointer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XChangeGC" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XChangeGC" .XX "graphics context:components;changing" .Na XChangeGC \(en change the components of a given graphics context. .Nz .SH "Synopsis" .Sy XChangeGC\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIvaluemask\f(CW\^, \f(CIvalues\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; unsigned long \f(CIvaluemask\f(CW\^; XGCValues *\^\f(CIvalues\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIvaluemask\fP 1i Specifies the components in the graphics context that you want to change. This argument is the bitwise OR of one or more of the GC component masks. .IP \f(CIvalues\fP 1i Specifies a pointer to the \f(CWXGCValues\fP structure. .SH Description \f(CWXChangeGC()\fP changes any or all of the components of a GC. The \f(CIvaluemask\fP specifies which components are to be changed; it is made by combining any number of the mask symbols listed in the Structures section using bitwise OR (\^ \^). The \f(CIvalues\fP structure contains the values to be set. These two arguments operate just like they do in \f(CWXCreateGC()\fP. Changing the \f(CWclip_mask\fP overrides any previous \f(CWXSetClipRectangles()\fP request for this GC. Changing the \f(CWdash_offset\fP or \f(CWdashes\fP overrides any previous \f(CWXSetDashes()\fP request on this GC. .LP Since consecutive changes to the same GC are buffered, there is no performance advantage to using this routine over the routines that set individual members of the GC. .LP Even if an error occurs, a subset of the components may have already been altered. The order in which components are altered and verified is server-dependent. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR, and Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" .XX "XGCValues structure" .XX "structures:XGCValues" .Ps .ta 4.5n 2.05i typedef struct { int function; /* logical operation */ unsigned long plane_mask; /* plane mask */ unsigned long foreground; /* foreground pixel */ unsigned long background; /* background pixel */ int line_width; /* line width */ int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */ int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */ int join_style; /* JoinMiter, JoinRound, JoinBevel */ int fill_style; /* FillSolid, FillTiled, FillStippled */ int fill_rule; /* EvenOddRule, WindingRule */ int arc_mode; /* ArcChord, ArcPieSlice */ Pixmap tile; /* tile pixmap for tiling operations */ Pixmap stipple; /* stipple 1 plane pixmap for stipping */ int ts_x_origin; /* offset for tile or stipple operations */ int ts_y_origin; Font font; /* default text font for text operations */ int subwindow_mode; /* ClipByChildren, IncludeInferiors */ Bool graphics_exposures; /* generate events on XCopy, Area, XCopyPlane*/ int clip_x_origin; /* origin for clipping */ int clip_y_origin; Pixmap clip_mask; /* bitmap clipping; other calls for rects */ int dash_offset; /* patterned/dashed line information */ char dashes; } XGCValues; #define GCFunction (1L<<0) #define GCPlaneMask (1L<<1) #define GCForeground (1L<<2) #define GCBackground (1L<<3) #define GCLineWidth (1L<<4) #define GCLineStyle (1L<<5) #define GCCapStyle (1L<<6) #define GCJoinStyle (1L<<7) #define GCFillStyle (1L<<8) #define GCFillRule (1L<<9) #define GCTile (1L<<10) #define GCStipple (1L<<11) #define GCTileStipXOrigin (1L<<12) #define GCTileStipYOrigin (1L<<13) #define GCFont (1L<<14) #define GCSubwindowMode (1L<<15) #define GCGraphicsExposures (1L<<16) #define GCClipXOrigin (1L<<17) #define GCClipYOrigin (1L<<18) #define GCClipMask (1L<<19) #define GCDashOffset (1L<<20) #define GCDashList (1L<<21) #define GCArcMode (1L<<22) .Pe .Nd 10 .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadFont\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .br \f(CWBadPixmap\fP .br \f(CWBadValue\fP .br .ne 7 .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXGetGCValues()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XChangeKeyboardMapping" "Xlib \- Keyboard" .ds ]W Xlib Reference Manual .SH "Name" .XX "XChangeKeyboardMapping" .XX "keyboard:mapping" .XX "mapping:keyboard" .Na XChangeKeyboardMapping \(en change the keyboard mapping. .Nz .SH "Synopsis" .Sy .nf XChangeKeyboardMapping(\^\f(CIdisplay\f(CW, \f(CIfirst_keycode\f(CW, .fi \f(CIkeysyms_per_keycode\f(CW, \f(CIkeysyms\f(CW, \f(CInum_codes\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int \f(CIfirst_keycode\f(CW\^; int \f(CIkeysyms_per_keycode\f(CW\^; KeySym *\f(CIkeysyms\f(CW\^; int \f(CInum_keycodes\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIfirst_keycode\fP Specifies the first keycode that is to be changed. .IP \f(CIkeysyms_per_keycode\fP Specifies the number of keysyms that the caller is supplying for each keycode. .IP \f(CIkeysyms\fP Specifies a pointer to the list of keysyms. .IP \f(CInum_keycodes\fP Specifies the number of keycodes that are to be changed. .SH Description Starting with \f(CIfirst_keycode\fP, \f(CWXChangeKeyboardMapping()\fP defines the keysyms for the specified number of keycodes. The symbols for keycodes outside this range remain unchanged. The number of elements in the \f(CIkeysyms\fP list must be \f(CIkeysyms_per_\p keycode\fP \(** \f(CWnum_keycodes\fR (else a \f(CWBadValue\fP error). The specified \f(CIfirst_keycode\fP must be greater than or equal to \f(CWmin_keycode\fP returned by \f(CWXDisplayKeycodes()\fR (see Appendix C, \fIMacros\fR) or a \f(CWBadValue\fR error results. In addition, the following expression must be less than or equal to \f(CWmax_keycode\fR as returned by \f(CWXDisplayKeycodes()\fR, or a \f(CWBadValue\fR error results: .LP .nf .ft CW \f(CIfirst_keycode\fP + \f(CInum_keycodes\fP - 1\s+2 .fi .ft R .LP The keysym number \fIN\fR (counting from 0) for keycode \fIK\fR has the following index in the \f(CIkeysyms\fP array (counting from 0): .LP .nf .ft CW (K - \f(CIfirst_keycode\fP) * \f(CIkeysyms_per_keycode\fP + N\s+2 .fi .ft R .LP The specified \f(CIkeysyms_per_keycode\fP can be chosen arbitrarily by the client to be large enough to hold all desired symbols. A special keysym value of \f(CWNoSymbol\fP should be used to fill in unused elements for individual keycodes. .ne 2 It is legal for \f(CWNoSymbol\fP to appear in nontrailing positions of the effective list for a keycode. .LP \f(CWXChangeKeyboardMapping()\fP generates a \f(CWMappingNotify\fP event, sent to this and all other clients, since the keycode to keysym mapping is global to all clients. .br .ne 4 .SH "Errors" .IP "\f(CWBadAlloc\fP" 1i .IP "\f(CWBadValue\fP" 1i \f(CIfirst.keycode\fP less than \f(CIdisplay\fP->\f(CWmin_keycode\fP. .br \f(CIdisplay\fP->\f(CWmax_keycode\fP exceeded (see above). .SH "See Also" \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifierMap\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeySym\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XChangeKeyboardControl" "Xlib \- User Preferences" .ds ]W Xlib Reference Manual .SH "Name" .XX "XChangeKeyboardControl" .XX "keyboard:changing user preferences" .Na XChangeKeyboardControl \(en change the keyboard preferences such as key click. .Nz .SH "Synopsis" .Sy XChangeKeyboardControl\^(\^\f(CIdisplay\f(CW, \f(CIvalue_mask\f(CW\^, \f(CIvalues\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; unsigned long \f(CIvalue_mask\f(CW\^; XKeyboardControl *\f(CIvalues\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIvalue_mask\fP 1i Specifies a mask composed of ORed symbols from the table shown in the Structures section below, specifying which fields to set. .IP \f(CIvalues\fP 1i Specifies the settings for the keyboard preferences. .SH Description \f(CWXChangeKeyboardControl()\fP sets user preferences such as key click, bell volume and duration, light state, and keyboard auto-repeat. Changing some or all these settings may not be possible on all servers. .LP The \f(CIvalue_mask\fP argument specifies which values are to be changed; it is made by combining any number of the mask symbols .LP The \f(CIvalues\fP structure contains the values to be set, as follows: .LP .XX "key clicks:setting volume" \f(CWkey_click_percent\fP sets the volume for key clicks between 0 (off) and 100 (loud) inclusive. Setting to \-1 restores the default. .LP .XX "bell:setting values for" \f(CWbell_percent\fP sets the base volume for the bell between 0 (off) and 100 (loud) inclusive. Setting to \-1 restores the default. .LP .XX "bell:pitch" \f(CWbell_pitch\fP sets the pitch (specified in Hz) of the bell. Setting to \-1 restores the default. .LP \f(CWbell_duration\fP sets the duration (specified in milliseconds) of the bell. Setting to -1 restores the default. .LP .XX "LEDs:setting values for" \f(CWled_mode\fR is either \f(CWLedModeOn\fR or \f(CWLedModeOff\fR. \f(CWled\fR is a number between 1 and 32 inclusive that specifies which light's state is to be changed. If both \f(CWled_mode\fP and \f(CWled\fP are specified, then the state of the LED specified in \f(CWled\fR is changed to the state specified in \f(CWled_mode\fR. If only \f(CWled_mode\fP is specified, then all the LEDs assume the value specified by \f(CWled_mode\fR. .LP .XX "auto-repeat" \f(CWauto_repeat_mode\fR is either \f(CWAutoRepeatModeOn\fR, \f(CWAutoRepeatModeOff\fR, or \f(CWAutoRepeatModeDefault\fR. \f(CWkey\fR is a keycode between 7 and 255 inclusive. If both \f(CWauto_repeat_mode\fP and \f(CWkey\fP are specified, then the auto-repeat mode of the key specified by \f(CWkey\fR is set as specified by \f(CWauto_repeat_mode\fR. If only \f(CWauto_repeat_mode\fP is specified, then the global auto repeat mode for the entire keyboard is changed, without affecting the settings for each key. If the \f(CWauto_repeat_mode\fR is \f(CWAutoRepeatModeDefault\fR for either case, the key or the entire keyboard is returned to its default setting for the server, which is normally to have all non-modal keys repeat. .LP When a key is being used as a modifier key, it does not repeat regardless of the individual or global auto repeat mode. .LP The order in which the changes are performed is server-dependent, and some may be completed when another causes an error. .LP For more information on user preferences, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH Structures .Ps .ta 4.5n 2.25i /* masks for ChangeKeyboardControl */ #define KBKeyClickPercent (1L<<0) #define KBBellPercent (1L<<1) #define KBBellPitch (1L<<2) #define KBBellDuration (1L<<3) #define KBLed (1L<<4) #define KBLedMode (1L<<5) #define KBKey (1L<<6) #define KBAutoRepeatMode (1L<<7) /* structure for ChangeKeyboardControl */ .XX "XKeyboardControl structure" .XX "structures:XKeyboardControl" typedef struct { int key_click_percent; int bell_percent; int bell_pitch; int bell_duration; int led; int led_mode; /* LedModeOn or LedModeOff */ int key; int auto_repeat_mode; /* AutoRepeatModeOff, AutoRepeatModeOn, AutoRepeatModeDefault */ } XKeyboardControl; .Pe .SH "Errors" .IP "\f(CWBadMatch\fP" 1i \f(CIvalues.\f(CWkey\fR specified but \f(CIvalues.\f(CWauto_repeat_mode\fR not specified. .br \f(CIvalues.\f(CWled\fR specified but \f(CIvalues.\f(CWled_mode\fR not specified. .Nd 20 .IP "\f(CWBadValue\fP" 1i \f(CIvalues.\f(CWkey_click_percent\fP < \-1. .br \f(CIvalues.\f(CWbell_percent\fP < \-1. .br \f(CIvalues.\f(CWbell_pitch\fP < \-1. .br \f(CIvalues.\f(CWbell_duration\fP < \-1. .SH "See Also" \s-1\fIXAutoRepeatOff()\fP\s+1, \s-1\fIXAutoRepeatOn()\fP\s+1, \s-1\fIXBell()\fP\s+1, \s-1\fIXGetDefault()\fP\s+1, \s-1\fIXGetKeyboardControl()\fP\s+1, \s-1\fIXGetPointerControl()\fP\s+1. .\"last line comment .TH XChangeKeyb.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XChangeKeyboardControl@XChangeKeyA .sp .5 XChangeKeyboardMapping@XChangeKeyB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XChangePointerControl" "Xlib \- Pointers" .ds ]W Xlib Reference Manual .SH "Name" .XX "XChangePointerControl" .Na .XX "pointers:changing preferences" XChangePointerControl \(en change the pointer preferences. .Nz .SH "Synopsis" .Sy XChangePointerControl\^(\^\f(CIdisplay\f(CW, \f(CIdo_accel\f(CW\^, \f(CIdo_threshold\f(CW\^, \f(CIaccel_numerator\f(CW\^, \f(CIaccel_denominator\f(CW\^, \f(CIthreshold\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Bool \f(CIdo_accel\f(CW\^, \f(CIdo_threshold\f(CW\^; int \f(CIaccel_numerator\f(CW\^, \f(CIaccel_denominator\f(CW\^; int \f(CIthreshold\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdo_accel\fP 1i Specifies a boolean value that controls whether the values for the \f(CIaccel_numerator\fP or \f(CIaccel_denominator\fP are set. You can pass one of these constants: \f(CWTrue\fP or \f(CWFalse\fP. .IP \f(CIdo_threshold\fP 1i Specifies a boolean value that controls whether the value for the threshold is set. You can pass one of these constants: \f(CWTrue\fP or \f(CWFalse\fP. .IP \f(CIaccel_numerator\fP 1i Specifies the numerator for the acceleration multiplier. .IP \f(CIaccel_denominator\fP 1i Specifies the denominator for the acceleration multiplier. .IP \f(CIthreshold\fP 1i Specifies the acceleration threshold. \f(CWTrue\fP or \f(CWFalse\fP. .SH Description .XX "acceleration:pointer" \f(CWXChangePointerControl()\fP defines how the pointing device functions. The acceleration is a fraction (\f(CIaccel_numerator\fP/\f(CIaccel_denominator\fP) which specifies how many times faster than normal the sprite on the screen moves for a given pointer movement. Acceleration takes effect only when a particular pointer motion is greater than \f(CIthreshold\fP pixels at once, and only applies to the motion beyond \f(CIthreshold\fP pixels. The values for \f(CIdo_accel\fP and \f(CIdo_threshold\fP must be \f(CWTrue\fR for the pointer values to be set; otherwise, the parameters will be unchanged. Setting any of the last three arguments to \-1 restores the default for that argument. .fl .LP The fraction may be rounded arbitrarily by the server. .\".Nd 10 .SH "Errors" .IP "\f(CWBadValue\fP" 1i \f(CIaccel_denominator\fP is 0. .br Negative value for \f(CIdo_accel\fP or \f(CIdo_threshold\fP. .br .ne 4 .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXGetPointerControl()\fP\s+1, \s-1\fIXGetPointerMapping()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXQueryPointer()\fP\s+1, \s-1\fIXSetPointerMapping()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1, \s-1\fIXWarpPointer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XChangeProperty" "Xlib \- Properties" .ds ]W Xlib Reference Manual .SH "Name" .XX "XChangeProperty" .XX "properties:and windows" .XX "windows:properties, changing" .Na XChangeProperty \(en change a property associated with a window. .Nz .SH "Synopsis" .Sy XChangeProperty\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIproperty\f(CW\^, \f(CItype\f(CW\^, \f(CIformat\f(CW\^, \f(CImode\f(CW\^, \f(CIdata\f(CW\^, \f(CInelements\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; Atom \f(CIproperty\f(CW\^, \f(CItype\f(CW\^; int \f(CIformat\f(CW\^; int \f(CImode\f(CW\^; unsigned char *\f(CIdata\f(CW\^; int \f(CInelements\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window whose property you want to change. .IP \f(CIproperty\fP 1i Specifies the property atom. .IP \f(CItype\fP 1i Specifies the type of the property. X does not interpret the type, but simply passes it back to an application that later calls \f(CWXGetWindow\%Prop\%erty\fP. .IP \f(CIformat\fP 1i Specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities. This information allows the X server to correctly perform byte-swap operations as necessary. If the format is 16-bit or 32-bit, you must explicitly cast your data pointer to a (\f(CIchar *\fP) in the call to \f(CWXChangeProperty()\fP. Possible values are \f(CW8\fP, \f(CW16\fP, and \f(CW32\fP. .\" Changed name of this file to \f(CWprop_mode\fP.a on 1/13/87 .IP \f(CImode\fP 1i Specifies the mode of the operation. Possible values are \f(CWProp\%Mode\%Replace\fP, \f(CWPropModePrepend\fP, \f(CWPropModeAppend\fP. .IP \f(CIdata\fP 1i Specifies the property data. .IP \f(CInelements\fP 1i Specifies the number of elements in the property. .SH Description .XX "PropertyNotify event:generating" \f(CWXChangeProperty()\fP changes a property and generates \f(CWPropertyNotify\fP events if they have been selected. .LP \f(CWXChangeProperty()\fP does the following according to the \f(CImode\fP argument: .IP "\(bu \f(CWPropModeReplace\fP" 5n .br Discards the previous property value and stores the new data. .IP "\(bu \f(CWPropModePrepend\fP" 5n .br Inserts the data before the beginning of the existing data. If the property is undefined, it is treated as defined with the correct type and format with zero-length data. \f(CItype\fP and \f(CIformat\fP arguments must match the existing property value; otherwise a \f(CWBadMatch\fP error occurs. .IP "\(bu \f(CWPropModeAppend \fP" 5n .br Appends the data onto the end of the existing data. If the property is undefined, it is treated as defined with the correct type and format with zero-length data. \f(CItype\fP and \f(CIformat\fP arguments must match the existing property value; otherwise a \f(CWBadMatch\fP error occurs. .LP The property may remain defined even after the client which defined it exits. The prop\%erty becomes undefined only if the application calls \f(CWXDeleteProperty()\fP, destroys the specified window, or closes the last connection to the X server. .LP The maximum size of a property is server-dependent and can vary dynamically if the server has insufficient memory. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fR. .br .ne 7 .SH "Errors" \f(CWBadAlloc .br \f(CWBadAtom\fP .br \f(CWBadMatch\fP .br \f(CWBadValue\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXDeleteProperty()\fP\s+1, \s-1\fIXGetAtomName()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXGetWindowProperty()\fP\s+1, \s-1\fIXInternAtom()\fP\s+1, \s-1\fIXListProperties()\fP\s+1, \s-1\fIXRotateWindowProperties()\fP\s+1, \s-1\fIXSetStandardProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XChangeSaveSet" "Xlib \- Window Save Set" .ds ]W Xlib Reference Manual .SH "Name" .XX "XChangeSaveSet" .XX "save-set:add or remove subwindow from" .Na XChangeSaveSet \(en add or remove a subwindow from the client's save-set. .Nz .SH "Synopsis" .Sy XChangeSaveSet\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIchange_mode\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; int \f(CIchange_mode\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window whose children you want to add or remove from the client's save-set; it must have been created by some other client. .IP \f(CIchange_mode\fP 1i Specifies the mode. Pass one of these constants: \f(CWSetModeInsert\fP (adds the window to this client's save-set) or \f(CWSetModeDelete\fP (deletes the window from this client's save-set). .SH Description .XX "windows:deleting from save-set" \f(CWXChangeSaveSet()\fP adds or deletes windows from a client's save-set. This client is usually the window manager. .LP The save-set of the window manager is a list of other client's top-level windows which have been reparented. If the window manager dies unexpectedly, these top-level application windows are children of a window manager window and therefore would normally be destroyed. The save-set prevents this by automatically reparenting the windows listed in the save-set to their closest existing ancestor, and then remapping them. .LP Windows are removed automatically from the save-set by the server when they are destroyed. .LP For more information on save-sets, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "Errors" .IP "\f(CWBadMatch\fP" 1i \f(CIw\fP not created by some other client. .IP "\f(CWBadValue\fP" .IP "\f(CWBadWindow\fP" .SH "See Also" \s-1\fIXAddToSaveSet()\fP\s+1, \s-1\fIXRemoveFromSaveSet()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XChangeWindowAttributes" "Xlib \- Window Attributes" .ds ]W Xlib Reference Manual .SH "Name" .XX "XChangeWindowAttributes" .XX "window attributes:setting" .Na XChangeWindowAttributes \(en set window attributes. .Nz .SH "Synopsis" .Sy XChangeWindowAttributes\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIvaluemask\f(CW\^, \f(CIattributes\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; unsigned long \f(CIvaluemask\f(CW\^; XSetWindowAttributes *\f(CIattributes\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window ID. .IP \f(CIvaluemask\fP 1i Specifies which window attributes are defined in the \f(CIattributes\fP argument. The mask is made by combining the appropriate mask symbols listed in the Structures section using bitwise OR ( ). If \f(CIvaluemask\fP is zero, the rest is ignored, and \f(CIattributes\fP is not referenced. The values and restrictions are the same as for \f(CWXCreateWindow()\fP. .IP \f(CIattributes\fP 1i Window attributes to be changed. The \f(CIvaluemask\fP indicates which members in this structure are referenced. .SH Description \f(CWXChangeWindowAttributes()\fP changes any or all of the window attributes that can be changed. For descriptions of the window attributes, see Volume One, Chapter 4, \fIWindow Attributes\fR. .LP Changing the background does not cause the window contents to be changed until the next \f(CWExpose\fP event or \f(CWXClearWindow()\fP call. Setting the border causes the border to be repainted immediately. Changing the background of a root window to \f(CWNone\fP or \f(CWParentRelative\fP restores the default background pixmap. Changing the border of a root window to \f(CWCopyFromParent\fR restores the default border pixmap. Drawing into the pixmap that was set as the background pixmap or border pixmap attribute has an undefined effect, because the server may or may not make copies of these pixmaps. .LP Changing the \f(CWwin_gravity\fP does not affect the current position of the window. Changing the \f(CWbacking_store\fP of an obscured window to \f(CWWhenMapped\fP or \f(CWAlways\fP may have no immediate effect. Also changing the \f(CWbacking_planes\fP, \f(CWbacking_pixel\fP, or \f(CWsave_under\fP of a mapped window may have no immediate effect. .LP Multiple clients can select input on the same window; the \f(CWevent_mask\fP attributes passed are disjoint. When an event is generated it will be reported to all interested clients. Therefore, the setting of the \f(CWevent_mask\fP attribute by one client will not affect the \f(CWevent_mask\fP of others on the same window. However, at most, one client at a time can select each of \f(CWSubstructureRedirectMask\fP, \f(CWResizeRedirectMask\fP, and \f(CWButtonPressMask\fP on any one window. If a client attempts to select on \f(CWSubtructureRedirectMask\fP, \f(CWResizeRedirectMask\fP, or \f(CWButtonPressMask\fP and some other client has already selected it on the same window, the X server generates a \f(CWBadAccess\fP error. .LP There is only one \f(CWdo_not_propagate_mask\fP for a window, not one per client. .LP Changing the colormap attribute of a window generates a \f(CWColormapNotify\fP event. Changing the colormap attribute of a visible window may have no immediate effect on the screen (because the colormap may not be installed until the window manager calls \f(CWXInstallColormap()\fP). .LP Changing the cursor of a root window to \f(CWNone\fP restores the default cursor. .LP For more information, see Volume One, Chapter 2, \fIX Concepts\fP, and Chapter 4, \fIWindow Attributes\fR. .SH "Structures" .Ps .ta 4.5n 2.5i /* * Data structure for setting window attributes. */ typedef struct { Pixmap background_pixmap; /* pixmap, None, or ParentRelative */ unsigned long background_pixel; /* background pixel */ Pixmap border_pixmap; /* pixmap, None, or CopyFromParent */ unsigned long border_pixel; /* border pixel value */ int bit_gravity; /* one of bit gravity values */ int win_gravity; /* one of the window gravity values */ int backing_store; /* NotUseful, WhenMapped, Always */ unsigned long backing_planes; /* planes to be preseved if possible */ unsigned long backing_pixel; /* value to use in restoring planes */ Bool save_under; /* should bits under be saved (popups) */ long event_mask; /* set of events that should be saved */ long do_not_propagate_mask; /* set of events that should not propagate */ Bool override_redirect; /* override redirected config request */ Colormap colormap; /* colormap to be associated with window */ Cursor cursor; /* cursor to be displayed (or None) */ } XSetWindowAttributes; /* Definitions for valuemask argument of CreateWindow and ChangeWindowAttributes */ #define CWBackPixmap (1L<<0) #define CWBackPixel (1L<<1) #define CWBorderPixmap (1L<<2) #define CWBorderPixel (1L<<3) #define CWBitGravity (1L<<4) #define CWWinGravity (1L<<5) #define CWBackingStore (1L<<6) #define CWBackingPlanes (1L<<7) #define CWBackingPixel (1L<<8) #define CWOverrideRedirect (1L<<9) #define CWSaveUnder (1L<<10) #define CWEventMask (1L<<11) #define CWDontPropagate (1L<<12) #define CWColormap (1L<<13) #define CWCursor (1L<<14) .Pe .SH "Errors" .IP "\f(CWBadAccess\fP" 1i .IP "\f(CWBadColor\fP" Specified colormap is invalid. .IP "\f(CWBadCursor\fP" .IP "\f(CWBadMatch\fP" .\" I already fixed the line below, Kismet .IP "\f(CWBadPixmap\fP" .IP "\f(CWBadValue\fP" .IP "\f(CWBadWindow\fP" .SH "See Also" \s-1\fIXGetGeometry()\fP\s+1, \s-1\fIXGetWindowAttributes()\fP\s+1, \s-1\fIXSetWindowBackground()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXSetWindowBorder()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCheckIfEvent" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCheckIfEvent" .XX "event queue:check for matching event" .XX "queues:check for matching event" .Na XCheckIfEvent \(en check the event queue for a matching event; don't wait. .Nz .SH "Synopsis" .Sy Bool XCheckIfEvent\^(\^\f(CIdisplay\f(CW, \f(CIevent_return\f(CW, \f(CIpredicate\f(CW, \f(CIarg\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XEvent *\f(CIevent_return\f(CW\^; Bool (\^*\f(CIpredicate\f(CW\^)\^(\^)\^; char *\f(CIarg\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIevent_return\fP 1i Returns the matched event structure. .IP \f(CIpredicate\fP 1i Specifies the procedure that is called to determine if the next event in the queue matches your criteria. .IP \f(CIarg\fP 1i Specifies the user-specified argument that will be passed to the predicate procedure. .SH Returns \f(CWTrue\fP if a matching event is found, else \f(CWFalse\fP. .SH Description \f(CWXCheckIfEvent()\fP returns the next event in the queue that is matched by the specified predicate procedure. If found, that event is removed from the queue, its structure is copied into the client-supplied \f(CWXEvent\fR, and \&\f(CWTrue\fP is returned. If no match is found, \f(CWXCheckIfEvent()\fP returns \f(CWFalse\fP and flushes the request buffer. No other events are removed from the queue. Later events in the queue are not searched. .LP The predicate procedure is called with the arguments \&\f(CIdisplay\fP, \&\f(CIevent\fP, and \&\f(CIarg\fP. .LP For more information, see Volume One, Chapter 8, \fIEvents\fR. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCheckMaskEvent" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCheckMaskEvent" .XX "events:remove matching" .Na XCheckMaskEvent \(en remove the next event that matches mask; don't wait. .Nz .SH "Synopsis" .Sy Bool XCheckMaskEvent\^(\^\f(CIdisplay\f(CW, \f(CIevent_mask\f(CW\^, \f(CIevent_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; long \f(CIevent_mask\f(CW\^; XEvent *\f(CIevent_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIevent_mask\fP 1i Specifies the event types to be returned. See list under \f(CWXSelectInput()\fP. .IP \f(CIevent_return\fP 1i Returns a copy of the matched event's \f(CWXEvent\fP structure. .SH Returns \f(CWTrue\fP if a matching event is found, else \f(CWFalse\fP. .SH Description \f(CWXCheckMaskEvent()\fP removes the next event in the queue that matches the passed mask. The event is copied into an \f(CWXEvent\fP supplied by the caller and \f(CWXCheckMaskEvent()\fP returns \f(CWTrue\fP. Other events earlier in the queue are not discarded. If no such event has been queued, \f(CWXCheckMaskEvent()\fP flushes the request buffer and immediately returns \f(CWFalse\fP, without waiting. .LP \f(CWXCheckMaskEvent()\fP cannot return \f(CWClientMessage\fP, \f(CWMappingNotify\fP, \f(CWSelectionClear\fP, \f(CWSelectionNotify\fP, or \f(CWSelectionRequest\fP events because these event types are by definition unmaskable. .LP For more information, see Volume One, Chapter 8, \fIEvents\fR. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCheckTypedEvent" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH Name .XX "XCheckTypedEvent" .XX "events:returning matching" .Na XCheckTypedEvent \(en return the next event in queue that matches event type; don't wait. .Nz .SH "Synopsis" .Sy Bool XCheckTypedEvent\^(\^\f(CIdisplay\f(CW, \f(CIevent_type\f(CW\^, \f(CIevent_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int \f(CIevent_type\f(CW\^; XEvent *\f(CIevent_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIevent_type\fP 1i Specifies the event type to be compared. .IP \f(CIevent_return\fP 1i Returns a copy of the matched event structure. .SH Returns \f(CWTrue\fP if a matching event is found, else \f(CWFalse\fP. .SH Description \f(CWXCheckTypedEvent()\fP searches first the event queue, then the events available on the server connection, for the specified \f(CIevent_type\fP. If there is a match, it returns the associated event structure. Events searched but not matched are not discarded. \f(CWXCheckTypedEvent()\fP returns \f(CWTrue\fP if the event is found. If the event is not found, \f(CWXCheckTypedEvent()\fP flushes the request buffer and returns \f(CWFalse\fP. .LP .XX "XCheckMaskEvent:compared to XCheckTypedEvent" This command is similar to \f(CWXCheckMaskEvent()\fP, but it searches through the queue and any events available on the server connection instead of inspecting only the last item on the queue. It also matches only a single event type instead of multiple event types as specified by a mask. .LP For more information, see Volume One, Chapter 8, \fIEvents\fR. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCheckTypedWindowEvent" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH Name .XX "XCheckTypedWindowEvent" .XX "events:returning matching" .Na XCheckTypedWindowEvent \(en return the next event in queue matching type and window; don't wait. .Nz .SH "Synopsis" .Sy Bool XCheckTypedWindowEvent\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIevent_type\f(CW\^, \f(CIevent_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; int \f(CIevent_type\f(CW\^; XEvent *\f(CIevent_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.2i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1.2i Specifies the window ID. .IP \f(CIevent_type\fP 1.2i Specifies the event type to be compared. .IP \f(CIevent_return\fP 1.2i .hw supplied Returns the matched event's associated structure into this client-supplied structure. .SH Returns \f(CWTrue\fP if a matching event is found, else \f(CWFalse\fP. .SH Description \f(CWXCheckTypedWindowEvent()\fP searches first the event queue, then any events available on the server connection, for an event that matches the specified window and the specified event type. Events searched but not matched are not discarded. .LP \f(CWXCheckTypedWindowEvent()\fP, if the event is found, removes the event from the queue, copies it into the specified \f(CWXEvent\fR structure, and returns \f(CWTrue\fR. It flushes the request buffer and returns \f(CWFalse\fP if the event is not found. .LP For more information, see Volume One, Chapter 8, \fIEvents\fR. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .TH XCheckTyped.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XCheckTypedEvent@XCheckTypeA .sp .5 XCheckTypedWindowEvent@XCheckTypeB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCheckWindowEvent" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCheckWindowEvent" .XX "events:remove matching" .Na XCheckWindowEvent \(en remove the next event matching both passed window and passed mask; don't wait. .Nz .SH "Synopsis" .Sy Bool XCheckWindowEvent\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIevent_mask\f(CW\^, \f(CIevent_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; long \f(CIevent_mask\f(CW\^; XEvent *\f(CIevent_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window ID. The event must match both the passed window and the passed event mask. .IP \f(CIevent_mask\fP 1i Specifies the event mask. See \f(CWXSelectInput()\fP for a list of mask elements. .IP \f(CIevent_return\fP 1i Returns the \f(CWXEvent\fP structure. .SH Returns \f(CWTrue\fP if a matching event is found, else \f(CWFalse\fP. .SH Description \f(CWXCheckWindowEvent()\fP removes the next event in the queue that matches both the passed window and the passed mask. If such an event exists, it is copied into an \f(CWXEvent\fP supplied by the caller. Other events earlier in the queue are not discarded. .LP If a matching event is found, \f(CWXCheckWindowEvent()\fP returns \f(CWTrue\fP. If no such event has been queued, it flushes the request buffer and returns \f(CWFalse\fP, without waiting. .LP \f(CWXCheckWindowEvent()\fP cannot return \f(CWClientMessage\fP, \f(CWMappingNotify\fP, \f(CWSelectionClear\fP, \f(CWSelectionNotify\fP, or \f(CWSelectionRequest\fP events because these event types are by definition unmaskable. .LP For more information, see Volume One, Chapter 8, \fIEvents\fR. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XChgKbd.man,v 1.5 94/06/04 17:32:20 rws Exp $ .ds xL Programming With Xlib .TH XChangeKeyboardDevice 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XChangeKeyboardDevice \- change which device is used as the X keyboard .SH SYNTAX Status XChangeKeyboardDevice\^(\^\fIdisplay\fP, \fIdevice\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device to be used as the X keyboard. .SH DESCRIPTION The \fIXChangeKeyboardDevice\fP request causes the server to use the specified device as the X keyboard. The device must have been previously opened by the requesting client via \fIXOpenDevice\fP or a \fIBadDevice\fP error will result. The device must support input class \fIKeys\fP, or a \fIBadMatch\fP error will result. If the server implementation does not support using the requested device as the X keyboard, a \fIBadDevice\fP error will result. .LP If the specified device is grabbed by another client, \fIAlreadyGrabbed\fP is returned. If the specified device is frozen by a grab on another device, \fIGrabFrozen\fP is returned. If the request is successful, \fISuccess\fP is returned. .LP If the request succeeds, a \fIChangeDeviceNotify\fP event is sent to all clients that have selected that event. A \fIMappingNotify\fP event with request = \fIMappingKeyboard\fP is sent to all clients. The specified device becomes the X keyboard and the old X keyboard becomes accessible through the input extension protocol requests. .LP \fIXChangeKeyboardDevice\fP can generate a \fIBadDevice\fP or a \fIBadMatch\fP error. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist, has not been opened by this client via \fIXOpenInputDevice\fP, or is already one of the core X device (pointer or keyboard). This error may also occur if the server implementation does not support using the specified device as the X keyboard. .TP 12 \fIBadMatch\fP This error may occur if an \fIXChangeKeyboardDevice\fP request was made specifying a device that has no keys. .SH "SEE ALSO" XChangePointerDevice .br \fI\*(xL\fP .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XChgPtr.man,v 1.5 94/06/04 17:32:21 rws Exp $ .ds xL Programming With Xlib .TH XChangePointerDevice 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XChangePointerDevice \- change which device is the X pointer .SH SYNTAX Status XChangePointerDevice\^(\^\fIdisplay\fP, \fIdevice\fP\^ \fIxaxis\fP\^, \fIyaxis\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br int \fIxaxis\fP\^; .br int \fIyaxis\fP\^; .br .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device to be used as the X pointer. .TP 12 .I xaxis Specifies the axis of the device to be used as the X pointer x-axis. .TP 12 .I yaxis Specifies the axis of the device to be used as the X pointer y-axis. .SH DESCRIPTION The \fIXChangePointerDevice\fP request causes the server to use the specified device as the X pointer. The device must have been opened by the client via \fIXOpenDevice\fP or a \fIBadDevice\fP error will result. The device must support input class \fIValuators\fP or a \fIBadMatch\fP error will result. If the implementation does not support use of the specified device as the X pointer, a \fIBadDevice\fP error will result. .LP If the specified device is grabbed by another client, \fIAlreadyGrabbed\fP is returned. If the specified device is frozen by a grab on another device, \fIGrabFrozen\fP is returned. If the request is successful, \fISuccess\fP is returned. .LP If the request succeeds, a \fIChangeDeviceNotify\fP event is sent to all clients that have selected that event. A \fIMappingNotify\fP event with request = \fIMappingPointer\fP is sent to all clients. The specified device becomes the X pointer, and the old X pointer becomes accessible through the input extension protocol requests. .LP \fIXChangePointerDevice\fP can generate a \fIBadDevice\fP or a \fIBadMatch\fP error. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist, has not been opened by this client via \fIXOpenInputDevice\fP, or is already one of the core X input devices (pointer or keyboard). This error may also occur if the server implementation does not support using the specified device as the X pointer. .TP 12 \fIBadMatch\fP This error may occur if an \fIXChangePointerDevice\fP request was made specifying a device that has less than two valuators, or specifying a valuator index beyond the range supported by the device. .SH "SEE ALSO" XChangeKeyboardDevice .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCirculateSubwindows" "Xlib \- Window Manipulation" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCirculateSubwindows" .XX "window management" .Na XCirculateSubwindows \(en circulate the stacking order of children up or down. .Nz .SH "Synopsis" .Sy XCirculateSubwindows\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIdirection\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; int \f(CIdirection\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window ID of the parent of the subwindows to be circulated. .IP \f(CIdirection\fP 1i Specifies the direction (up or down) that you want to circulate the children. Pass either \f(CWRaiseLowest\fP or \f(CWLowerHighest\fP. .SH Description .XX "children:raising/lowering" \f(CWXCirculateSubwindows()\fP circulates the children of the specified window in the specified direction, either \f(CWRaiseLowest\fP or \f(CWLowerHighest\fP. If some other client has selected \f(CWSubstructureRedirectMask\fP on the specified window, then a \f(CWCirculateRequest\fP event is generated, and no further processing is performed. If you specify \f(CWRaiseLowest\fR, this function raises the lowest mapped child (if any) that is occluded by another child to the top of the stack. If you specify \f(CWLowerHighest\fR, this function lowers the highest mapped child (if any) that occludes another child to the bottom of the stack. Exposure processing is performed on formerly obscured windows. If a child is actually restacked, the X server generates a \f(CWCirculateNotify\fR event. .LP For more information, see Volume One, Chapter 16, \fIWindow Management\fR. .SH "Errors" \f(CWBadValue\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXCirculateSubwindowsDown()\fP\s+1, \s-1\fIXCirculateSubwindowsUp()\fP\s+1, \s-1\fIXConfigureWindow()\fP\s+1, \s-1\fIXLowerWindow()\fP\s+1, \s-1\fIXMoveResizeWindow()\fP\s+1, \s-1\fIXMoveWindow()\fP\s+1, \s-1\fIXQueryTree()\fP\s+1, \s-1\fIXRaiseWindow()\fP\s+1, \s-1\fIXReparentWindow()\fP\s+1, \s-1\fIXResizeWindow()\fP\s+1, \s-1\fIXRestackWindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCirculateSubwindowsDown" "Xlib \- Window Manipulation" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCirculateSubwindowsDown" .Na XCirculateSubwindowsDown \(en circulate the bottom child to the top of the stacking order. .Nz .SH "Synopsis" .Sy XCirculateSubwindowsDown\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window ID of the parent of the windows to be circulated. .SH Description .XX "children:raising/lowering" \f(CWXCirculateSubwindowsDown()\fP lowers the highest mapped child of the specified window that partially or completely obscures another child. The lowered child goes to the bottom of the stack. Completely unobscured children are not affected. .LP This function generates exposure events on any window formerly obscured. Repeated executions lead to round-robin lowering. .XX "XCirculateSubwindows:and XCirculateSubwindowsDown" \f(CWXCirculateSubwindowsDown()\fP is equivalent to \f(CWXCirculateSubwindows\fP(\f(CIdisplay\fP, \f(CIw\fP, \f(CWLowerHighest\fP). .LP If some other client has selected \f(CWSubstructureRedirectMask\fP on the window, then a \f(CWCirculateRequest\fP event is sent to that client, and no further processing is performed. This allows the window manager to intercept this request when \f(CIw\fP is the root window. Normally, only the window manager should call \f(CWXCirculateSubwindowsDown()\fP on the root window. .LP For more information, see Volume One, Chapter 16, \fIWindow Management\fR. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXCirculateSubwindows()\fP\s+1, \s-1\fIXCirculateSubwindowsUp()\fP\s+1, \s-1\fIXConfigureWindow()\fP\s+1, \s-1\fIXLowerWindow()\fP\s+1, \s-1\fIXMoveResizeWindow()\fP\s+1, \s-1\fIXMoveWindow()\fP\s+1, \s-1\fIXQueryTree()\fP\s+1, \s-1\fIXRaiseWindow()\fP\s+1, \s-1\fIXReparentWindow()\fP\s+1, \s-1\fIXResizeWindow()\fP\s+1, \s-1\fIXRestackWindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCirculateSubwindowsUp" "Xlib \- Window Manipulation" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCirculateSubwindowsUp" .XX "windows:management" .Na XCirculateSubwindowsUp \(en circulate the top child to the bottom of the stacking order. .Nz .SH "Synopsis" .Sy XCirculateSubwindowsUp\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window ID of the parent of the windows to be circulated. .SH Description .XX "children:raising/lowering" \f(CWXCirculateSubwindowsUp()\fP raises the lowest mapped child of the specified window that is partially or completely obscured by another child. The raised child goes to the top of the stack. This generates exposure events on the raised child (and its descendents, if any). Repeated executions lead to round robin-raising. Completely unobscured children are not affected. .LP \f(CWXCirculateSubwindowsUp()\fP is equivalent to \f(CWXCirculateSubwindows\fP(\f(CIdisplay\fP, \f(CIw\fP, \f(CWRaiseLowest\fP). .LP If some other client has selected \f(CWSubstructureRedirectMask\fP on the window, then a \f(CWCirculateRequest\fP event is sent to that client, and no further processing is performed. This allows the window manager to intercept this request when \f(CIw\fP is the root window. Normally, only the window manager will call \f(CWXCirculateSubwindowsUp()\fP on the root window. .LP For more information, see Volume One, Chapter 16, \fIWindow Management\fR. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXCirculateSubwindows()\fP\s+1, \s-1\fIXCirculateSubwindowsDown()\fP\s+1, \s-1\fIXConfigureWindow()\fP\s+1, \s-1\fIXLowerWindow()\fP\s+1, \s-1\fIXMoveResizeWindow()\fP\s+1, \s-1\fIXMoveWindow()\fP\s+1, \s-1\fIXQueryTree()\fP\s+1, \s-1\fIXRaiseWindow()\fP\s+1, \s-1\fIXReparentWindow()\fP\s+1, \s-1\fIXResizeWindow()\fP\s+1, \s-1\fIXRestackWindows()\fP\s+1. .\"last line comment .TH XCirculateS.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XCirculateSubwindows@XCirculateA .sp .5 XCirculateSubwindowsDown@XCirculateB .sp .5 XCirculateSubwindowsUp@XCirculateC .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XClearArea" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .XX "XClearArea" .Na XClearArea \(en clear a rectangular area in a window. .Nz .SH "Synopsis" .Sy XClearArea\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^, \f(CIexposures\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; Bool \f(CIexposures\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the ID of an \f(CWInputOutput\fP window. .IP \f(CIx\fP .br .ns .IP \f(CIy\fP .sp -2 Specify the x and y coordinates of the upper-left corner of the rectangle to be cleared, relative to the origin of the window. .IP \f(CIwidth\fP Specify the dimensions in pixels of the rectangle to be cleared. .br .ns .IP \f(CIheight\fP .IP \f(CIexposures\fP Specifies whether exposure events are generated. Must be either \f(CWTrue\fP or \f(CWFalse\fP. .SH Description .XX "windows:clear rectangular area in" \f(CWXClearArea()\fP clears a rectangular area in a window. .LP If \f(CIwidth\fP is zero, the window is cleared from \f(CIx\fP to the right edge of the window. If \f(CIheight\fP is zero, the window is cleared from \f(CIy\fP to the bottom of the window. See the figure on the next page.. .LP If the window has a defined background tile or it is \f(CWParentRelative\fR, the rectangle is tiled with a \f(CWplane_mask\fP of all 1's, a \f(CWfunction\fP of \f(CWGXcopy\fP, and a \f(CWsubwindow_mode\fP of \f(CWClipByChildren\fP. If the window has background \f(CWNone\fP, the contents of the window are not changed. In either case, if \f(CIexposures\fP is \f(CWTrue\fP, then one or more exposure events are generated for regions of the rectangle that are either visible or are being retained in a backing store. .LP .EL For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .Nd 10 .SH "Errors" .IP "\f(CWBadMatch\fP" 1i Window is an \f(CWInputOnly\fP class window. .IP "\f(CWBadValue\fP" .IP "\f(CWBadWindow\fP" .SH "See Also" \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .Fs .Pf amp1.eps "" "" "" "" noscale .Fe "Area cleared with various width and hieght arguments" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XClearWindow" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .XX "XClearWindow" .XX "windows:clearing" .Na XClearWindow \(en clear an entire window. .Nz .SH "Synopsis" .Sy XClearWindow\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window to be cleared. .SH Description \f(CWXClearWindow()\fP clears a window, but does not cause exposure events. This function is equivalent to \f(CW\f(CWXClearArea\fP\^(\^\f(CIdisplay, w, \f(CW0, 0, 0, 0, False)\fP. .LP If the window has a defined background tile or it is \f(CWParentRelative\fR, the rectangle is tiled with a \f(CWplane_mask\fP of all 1's and \f(CWfunction\fP of \f(CWGXcopy\fP. If the window has background \f(CWNone\fP, the contents of the window are not changed. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Errors" .IP "\f(CWBadMatch\fP" 1i If \f(CIw\fP is an \f(CWInputOnly\fP class window. .IP "\f(CWBadWindow\fP" .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XClipBox" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XClipBox" .Na XClipBox \(en generate the smallest rectangle enclosing a region. .Nz .SH "Synopsis" .Sy XClipBox\^(\^\f(CIr\f(CW\^, \f(CIrect_return\f(CW\^) .As Region \f(CIr\f(CW\^; XRectangle \f(CI*rect_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIr\fP 1i Specifies the region. .IP \f(CIrect_return\fP 1i Returns the smallest rectangle enclosing region \f(CIr\fP. .SH Description .XX "rectangles:and regions" \f(CWXClipBox()\fR returns the smallest rectangle that encloses the given region. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" \f(CWRegion\fP is a pointer to an opaque structure type. .SH "See Also" \s-1\fIXCreateRegion()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCloseDisplay" "Xlib \- HouseKeeping" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCloseDisplay" .Na XCloseDisplay \(en disconnect a client program from an X server and display. .Nz .SH "Synopsis" .Sy XCloseDisplay\^(\f(CIdisplay\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Description .XX "displays:closing" \f(CWXCloseDisplay()\fP closes the connection between the current client and the X server specified by the \f(CWDisplay\fP argument. .LP The \f(CWXCloseDisplay()\fP routine destroys all windows, resource IDs (\f(CWWindow\fP, \f(CWFont\fP, \f(CWPixmap\fP, \f(CWColormap\fP, \f(CWCursor\fP, and \f(CWGContext\fP), or other resources (GCs) that the client application has created on this display, unless the close down mode of the client's resources has been changed by \f(CWXSetCloseDownMode()\fP. Therefore, these windows, resource IDs, and other resources should not be referenced again. In addition, this routine discards any requests that have been buffered but not yet sent to the server. .LP Although these operations automatically (implicitly) occur when a process exits under UNIX, you should call \f(CWXCloseDisplay()\fP anyway so that any pending errors are reported as \f(CWXCloseDisplay()\fR performs a final \f(CWXSync()\fR operation. .LP For more information, see Volume One, Chapter 3, \fIBasic Window Program\fR. .SH "Errors" .IP "\f(CWBadGC\fR" 1i Default GC already freed. .SH "See Also" \s-1\fIXDefaultScreen()\fP\s+1, \s-1\fIXFree()\fP\s+1, \s-1\fIXNoOp()\fP\s+1, \s-1\fIXOpenDisplay()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCloseIM" "Xlib \- Input Methods" .ds ]W Xlib Reference Manual .XX "XCloseIM" .XX "input methods:closing" .SH Name .Na XCloseIM \(en close an input method. .Nz .SH Synopsis .Sy Status XCloseIM\^(\^\f(CIim\fP\^) .As XIM \f(CIim\fP\^; .Ae .SH Arguments .IP \f(CIim\fP 1i Specifies the input method. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description \f(CWXCloseIM()\fP closes the connection to an input method opened with \f(CWXOpenIM()\fP. Once an input method is closed, none of the input contexts associated with that input method may be used. .SH "See Also" \s-1\fIXCreateIC()\fP\s+1, \s-1\fIXSetICFocus()\fP\s+1, \s-1\fIXSetICValues()\fP\s+1, \s-1\fIXmbResetIC()\fP\s+1, \s-1\fIXOpenIM()\fP\s+1, \s-1\fIXGetIMValues()\fP\s+1, \s-1\fIXDisplayOfIM()\fP\s+1, \s-1\fIXLocaleOfIM()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XConfigureWindow" "Xlib \- Window Manipulation" .ds ]W Xlib Reference Manual .SH "Name" .XX "XConfigureWindow" .XX "windows:configuring" .XX "border width:changing" .XX "stacking order, changing" .Na XConfigureWindow \(en change the window position, size, border width, or stacking order. .Nz .SH "Synopsis" .Sy XConfigureWindow\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIvalue_mask\f(CW\^, \f(CIvalues\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; unsigned int \f(CIvalue_mask\f(CW\^; XWindowChanges *\f(CIvalues\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window to be reconfigured. .IP \f(CIvalue_mask\fP 1i Specifies which values are to be set using information in the \f(CWvalues\fP structure. \f(CIvalue_mask\fP is the bitwise OR of any number of symbols listed in the Structures section below. .IP \f(CIvalues\fP 1i Specifies a pointer to the \f(CWXWindowChanges\fP structure containing new configuration information. See the "Structures" section below. .SH Description \f(CWXConfigureWindow()\fP changes the window position, size, border width, and/or the stacking order. If selected, a \f(CWConfigureNotify\fP event is generated to announce any changes. .LP If the window to be reconfigured is a top-level window, there will be interaction with the window manager if the \f(CWoverride_redirect\fP attribute of the window is \f(CWFalse\fR. In this case, the X server sends a \f(CWConfigureRequest\fR event to the window manager and does not reconfigure the window. The window manager receives this event and then makes the decision whether to allow the application to reconfigure its window. The client should wait for the \f(CWConfigureNotify\fP event to find out the size and position of the window. .LP In Release 4, \f(CWXReconfigureWMWindow()\fP should be used instead of \f(CWXConfigureWindow()\fP for top-level windows. This routine properly handles restacking of top-level windows. .LP If a window's size actually changes, the window's subwindows may move according to their window gravity. If they do, \f(CWGravityNotify\fP events will be generated for them. Depending on the window's bit gravity, the contents of the window also may be moved. See Volume One, Chapter 4, \fIWindow Attributes\fR, for further information. .LP Exposure processing is performed on formerly obscured windows, including the window itself and its inferiors, if regions of them were obscured but afterward are not. As a result of increasing the width or height, exposure processing is also performed on any new regions of the window and any regions where window contents are lost. .LP .ne 12 The members of \f(CWXWindowChanges\fR that you specify in \f(CIvalues\fP are: .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the upper-left outer corner of the window relative to the parent's origin. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight\fP 1i .sp -2 Specify the inside size of the window in pixels, not including the border. These arguments must be positive. .IP \f(CIborder_width\fP 1i Specifies the width of the border in pixels. .IP \f(CIsibling\fP 1i Specifies the sibling window for stacking operations. If specified, \f(CWstack_mode\fP must also be specified. .IP \f(CIstack_mode\fP 1i The stack mode can be any of these constants: \f(CWAbove\fP, \f(CWBelow\fP, \f(CWTopIf\fP, \f(CWBottomIf\fP, or \f(CWOpposite\fP. .LP The computation for the \f(CWBottomIf\fP, \f(CWTopIf\fP, and \f(CWOpposite\fP stacking modes is performed with respect to window \f(CIw\fP's final size and position (as controlled by the other arguments to \f(CWXConfigureWindow()\fP, not its initial position.) It is an error if \f(CIsibling\fP is specified without \f(CIstack_mode\fP. If \f(CIsibling\fP and \f(CIstack_mode\fP are specified, the window is restacked as follows: .sp .sp 3p .LP .sp 1 .in 0 .KS .TS linesize(2); l l lp7fCW lw(4.25i). Stacking Flag Position \f(CWAbove\fP \f(CIw\fP is placed just above \f(CIsibling\fP. \f(CWBelow\fP \f(CIw\fP is placed just below \f(CIsibling\fP. \f(CWTopIf\fP if \f(CIsibling\fP occludes \f(CIw\fP, then \f(CIw\fP is placed at the top of the stack. \f(CWBottomIf\fP if \f(CIw\fP occludes \f(CIsibling\fP, then \f(CIw\fP is placed at the bottom of the stack. \f(CWOpposite\fP if \f(CIsibling\fP occludes \f(CIw\fP, then \f(CIw\fP is placed at the top of the stack. If \f(CIw\fP occludes \f(CIsibling\fP, then \f(CIw\fP is placed at the bottom of the stack. If \f(CIw\fP and \f(CIsibling\fP do not overlap, no change is made. .TE .KE .in If a \f(CWstack_mode\fP is specified but no sibling is specified, the window is restacked as follows: .in 0 .KS .TS l l l lw(4.25i). Stacking Flag Position \f(CWAbove\fP \f(CIw\fP is placed at the top of the stack. \f(CWBelow\fP \f(CIw\fP is placed at the bottom of the stack. \f(CWTopIf\fP if any sibling occludes \f(CIw\fP, then \f(CIw\fP is placed at the top of the stack. .TE .KE .in .bp .nr tB -1 .in 0 .KS .TS linesize(2); l l l lw(4.25i). Stacking Flag Position \f(CWBottomIf\fP if \f(CIw\fP occludes any sibling, then window is placed at the bottom of the stack. \f(CWOpposite\fP if any sibling occludes \f(CIw\fP, then \f(CIw\fP is placed at the top of the stack, else if \f(CIw\fP occludes any sibling, then \f(CIw\fP is placed at the bottom of the stack. .TE .KE .in .sp 1 .br .sp -.15 Under Release 4, use \f(CWXReconfigureWMWindow()\fP to configure a top-level window. .SH "Structures" .EL .Ps typedef struct { int x, y; int width, height; int border_width; Window sibling; int stack_mode; } XWindowChanges; .sp .5 /* ConfigureWindow structure */ /* ChangeWindow value bits definitions for \f(CIvaluemask\fP */ #define CWX (1<<0) #define CWY (1<<1) #define CWWidth (1<<2) #define CWHeight (1<<3) #define CWBorderWidth (1<<4) #define CWSibling (1<<5) #define CWStackMode (1<<6) .Pe .SH "Errors" .IP "\f(CWBadMatch\fP" 1i Attempt to set any invalid attribute of \f(CWInputOnly\fP window. .br \f(CIsibling\fP specified without a \f(CIstack_mode\fP. .br The \f(CIsibling\fP window is not actually a sibling. .IP "\f(CWBadValue\fP" 1i \f(CIwidth\fP or \f(CIheight\fP is 0. .IP "\f(CWBadWindow\fP" .Nd 5 .SH "See Also" \s-1\fIXCirculateSubwindows()\fP\s+1, \s-1\fIXCirculateSubwindowsDown()\fP\s+1, \s-1\fIXCirculateSubwindowsUp()\fP\s+1, \s-1\fIXLowerWindow()\fP\s+1, \s-1\fIXMoveResizeWindow()\fP\s+1, \s-1\fIXMoveWindow()\fP\s+1, \s-1\fIXQueryTree()\fP\s+1, \s-1\fIXReconfigureWMWindow()\fP\s+1, \s-1\fIXRaiseWindow()\fP\s+1, \s-1\fIXReparentWindow()\fP\s+1, \s-1\fIXResizeWindow()\fP\s+1, \s-1\fIXRestackWindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XConnectionNumber" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XConnectionNumber, ConnectionNumber \(en get connection number or file descriptor. .XX "XConnectionNumber" .XX "connection numbers" .XX "file descriptors" .Nz .\" .\" .SH "Synopsis" .Sy int XConnectionNumber\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Returns The connection number. .SH Description \f(CWXConnectionNumber()\fP returns the connection number for the specified display. On a POSIX-conformant system, this is the file descriptor of the connection. .LP .XX "ConnectionNumber macro" The C language macro \f(CWConnectionNumber()\fP is equivalent and slightly more efficient. .\" .\" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XContextDependentDrawing" "\s-1Xlib \- Internationalized Text Output\s0" .ds ]W Xlib Reference Manual .XX "XContextDependentDrawing" .XX "font set:obtaining information about" .XX "text:context dependencies" .XX "context dependencies" .SH Name .Na XContextDependentDrawing \(en get a hint about context dependencies in the text of the locale. .Nz .SH Synopsis .Sy Bool XContextDependentDrawing\^(\^\f(CIfont_set\fP\^) .As XFontSet \f(CIfont_set\fP\^; .Ae .SH Arguments .IP \f(CIfont_set\fP 1i Specifies the font set. .SH Returns \f(CWTrue\fP or \f(CWFalse\fP as described below. .SH Availability Release 5 and later. .SH Description If \f(CWXContextDependentDrawing()\fP returns \f(CWTrue\fP, then text in the locale of the specified font set may contain context dependencies. If it returns \f(CWFalse\fP, then text drawn with the font set does not contain context dependencies. .LP When text contains context dependencies, a character may be rendered with different glyphs in different locations in the string, a single character may be rendered with multiple font glyphs, and multiple characters may be rendered with a single glyph. When there are context dependencies, drawing the characters of a string individually may have different results than drawing the string with a single call to one of the internationalized text drawing functions. When changing or inserting characters into an already drawn string, the characters surrounding the change may also need to be redrawn. .SH "See Also" \s-1\fIXCreateFontSet()\fP\s+1, \s-1\fIXExtentsOfFontSet()\fP\s+1, \s-1\fIXFontsOfFontSet()\fP\s+1, \s-1\fIXBaseFontNameListOfFontSet()\fP\s+1, \s-1\fIXLocaleOfFontSet()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XConvertSelection" "Xlib \- Selections" .ds ]W Xlib Reference Manual .SH "Name" .XX "XConvertSelection" .XX "selections:requesting conversion of" .Na XConvertSelection \(en request conversion of the selection. .Nz .SH "Synopsis" .Sy XConvertSelection\^(\^\f(CIdisplay\f(CW, \f(CIselection\f(CW\^, \f(CItarget\f(CW\^, \f(CIproperty\f(CW\^, .ti +10n \f(CIrequestor\f(CW\^, \f(CItime\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Atom \f(CIselection\f(CW\^, \f(CItarget\f(CW\^; Atom \f(CIproperty\f(CW\^; Window \f(CIrequestor\f(CW\^; Time \f(CItime\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIselection\fP 1i Specifies the selection atom. \f(CWXA_PRIMARY\fP and \f(CWXA_SECONDARY\fP are the standard selection atoms. .IP \f(CItarget\fP 1i Specifies the atom describing the desired format for the data. .IP \f(CIproperty\fP 1i Specifies the property in which the requested data is to be placed. \f(CWNone\fP is also valid, but current conventions specify that the requestor is in a better position to select a property than the selection owner. .IP \f(CIrequestor\fP 1i Specifies the requesting window. .IP \f(CItime\fP 1i Specifies the time when the conversion should take place. .hw time-stamp Pass the timestamp from the event that triggered the selection request. .SH Description .XX "SelectionRequest event:send to current selection owner" \f(CWXConvertSelection()\fP causes a \f(CWSelectionRequest\fP event to be sent to the current selection owner if there is one. This event specifies the selection property (\f(CIselection\fP), the format into which to convert that data before storing it (\f(CItarget\fP), the property in which the owner will place the information (\f(CIproperty\fP), the window that wants the information (\f(CIrequestor\fP), and the time of the conversion request (\f(CItime\fP). .LP .XX "SelectionNotify event:and XConvertSelection" The selection owner responds by sending a \f(CWSelectionNotify\fP event, which confirms the selected atom and type. If no owner for the specified selection exists, or if the owner could not convert to the type specified by requestor, the X server generates or the owner sends a \f(CWSelectionNotify\fP event to the \fIrequestor\fP with property \f(CWNone\fP. Whether or not the owner exists, the arguments are passed unchanged. See Volume One, Chapter 12, \fIInterclient Communication\fP, for a description of selection events and selection conventions. .Nd 10 .SH "Errors" \f(CWBadAtom\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXGetSelectionOwner()\fP\s+1, \s-1\fIXSetSelectionOwner()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCopyArea" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCopyArea" .XX "drawable:copying an area of" .XX "rectangles:combining" .Na XCopyArea \(en copy an area of a drawable. .Nz .SH "Synopsis" .Sy XCopyArea\^(\^\f(CIdisplay\f(CW, \f(CIsrc\f(CW\^, \f(CIdest\f(CW\^, \f(CIgc\f(CW\^, \f(CIsrc_x\f(CW\^, \f(CIsrc_y\f(CW\^, \f(CIwidth\f(CW\^, .ti +10n \f(CIheight\f(CW\^, \f(CIdest_x\f(CW\^, \f(CIdest_y\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIsrc\f(CW\^, \f(CIdest\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIsrc_x\f(CW\^, \f(CIsrc_y\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; int \f(CIdest_x\f(CW\^, \f(CIdest_y\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIsrc\fP 1i .br .ns .IP \f(CIdest\fP 1i .sp -2 Specify the source and destination rectangles to be combined. \f(CIsrc\fP and \f(CIdest\fP must have the same root and depth. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIsrc_x\fP 1i .br .ns .IP \f(CIsrc_y\fP 1i .sp -2 Specify the x and y coordinates of the upper-left corner of the source rectangle relative to the origin of the source drawable. .IP "\f(CIwidth\fP" 1i .br .ns .IP "\f(CIheight\fP" 1i .sp -2 Specify the dimensions in pixels of both the source and destination rectangles. .IP \f(CIdest_x\fP 1i Specify the x and y coordinates within the destination window. .br .ns .IP \f(CIdest_y\fP 1i .LP .SH Description \f(CWXCopyArea()\fP combines the specified rectangle of \f(CIsrc\fP with the specified rectangle of \f(CIdest\fP. \f(CIsrc\fP and \f(CIdest\fP must have the same root and depth. .LP If regions of the source rectangle are obscured and have not been .hw backing retained in \f(CWbacking_store\fP, or if regions outside the boundaries of the source drawable are specified, then those regions are not copied. Instead, the following occurs on all corresponding destination regions that are either visible or are retained in \f(CWbacking_store\fP. If \f(CIdest\fP is a window with a background other than \f(CWNone\fP, the corresponding regions of the destination are tiled (with \f(CWplane_mask\fP of all 1's and function \f(CWGXcopy\fP) with that background. Regardless of tiling, if the destination is a window and \f(CWgraphics_exposures\fP in \f(CIgc\fR is \f(CWTrue\fP, then \f(CWGraphicsExpose\fP events for all corresponding destination regions are generated. If \f(CWgraphics_exposures\fR is \f(CWTrue\fP but no regions are exposed, then a \f(CWNoExpose\fP event is generated. .LP If regions of the source rectangle are not obscured and \f(CWgraphics_exposures\fP is \f(CWFalse\fP, one \f(CWNoExpose\fP event is generated on the destination. .Nd 6 .LP \f(CWXCopyArea()\fP uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWsubwindow_mode\fP, \f(CWgraphics_exposures\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. .SH "Errors" .IP "\f(CWBadDrawable\fP" 1.2i .IP "\f(CWBadGC\fP" .IP "\f(CWBadMatch\fP" The \f(CIsrc\fP and \f(CIdest\fP rectangles do not have the same root and depth. .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCopyColormapAndFree" "Xlib \- Colormaps" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCopyColormapAndFree" .XX "colormaps:copy and free" .Na XCopyColormapAndFree \(en copy a colormap and return a new colormap ID. .Nz .SH "Synopsis" .Sy Colormap XCopyColormapAndFree\^(\^\f(CIdisplay\f(CW, \f(CI\f(CIcolormap\fR\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CI\f(CIcolormap\fR\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CI\f(CIcolormap\fR\fP 1i Specifies the colormap you are moving out of. .SH Returns The created colormap. .SH Description \f(CWXCopyColormapAndFree()\fP is used to obtain a new virtual colormap when allocating colorcells out of a previous colormap has failed due to resource exhaustion (that is, too many cells or planes were in use in the original colormap). The visual and screen for the new colormap is the same as for the old. .LP \f(CWXCopyColormapAndFree()\fP moves all of the client's existing allocations from \f(CIcolormap\fP to the returned \f(CWColormap\fP. The read/write or read-only characteristics of each cell moved are preserved in the new colormap. .LP If \f(CIcolormap\fR was created by the client with the \f(CIalloc\fR argument set to \f(CWAllocAll\fR, the new colormap is also created with \f(CWAllocAll\fR, all color values for all entries are copied from \f(CIcolormap\fR, and then all entries in \f(CIcolormap\fR are freed. .LP If \f(CIcolormap\fR was created by the client with \f(CWAllocNone\fR, or not created by the client, the allocations to be moved are all those pixels and planes that have been allocated by the client using \f(CWXAllocColor\fR, \f(CWXAllocNamedColor()\fR, \f(CWXAllocColorCells()\fR, or \f(CWXAllocColorPlanes()\fR and that have not been freed since they were allocated. Values in other entries of the new \f(CWColormap\fP are undefined. .LP For more information, see Volume One, Chapter 7, \fIColor\fR. .SH "Errors" \f(CWBadAlloc\fP .br .IP "\f(CWBadColor\fP" 1i \f(CWcolormap\fR is invalid. .br .Nd 10 .SH "See Also" \s-1\fIXDefaultColormap()\fP\s+1, \s-1\fIXDisplayCells()\fP\s+1, \s-1\fIXCreateColormap()\fP\s+1, \s-1\fIXFreeColormap()\fP\s+1, \s-1\fIXGetStandardColormap()\fP\s+1, \s-1\fIXInstallColormap()\fP\s+1, \s-1\fIXListInstalledColormaps()\fP\s+1, \s-1\fIXSetStandardColormap()\fP\s+1, \s-1\fIXSetWindowColormap()\fP\s+1, \s-1\fIXUninstallColormap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCopyGC" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCopyGC" .XX "graphics context:copying" .Na XCopyGC \(en copy a graphics context. .Nz .SH "Synopsis" .Sy XCopyGC\^(\^\f(CIdisplay\f(CW, \f(CIsrc\f(CW\^, \f(CIvaluemask\f(CW\^, \f(CIdest\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIsrc\f(CW\^; unsigned long \f(CIvaluemask\f(CW\^; GC \f(CIdest\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIsrc\fP 1i Specifies the components of the source graphics context. .IP \f(CIvaluemask\fP 1i Specifies the components in the source GC structure to be copied into the destination GC. \f(CIvaluemask\fP is made by combining any number of the mask symbols listed in the Structures section using bitwise OR (\^ \^). .IP \f(CIdest\fP 1i Specifies the destination graphics context. .SH Description \f(CWXCopyGC()\fP copies the selected elements of one graphics context to another. The source and destination GC's must have the same root and depth. \f(CWXCopyGC()\fP requires that both GC's exist before the call is made. See Volume One, Chapter 5, \fIThe Graphics Context\fR, for a description of the graphics context. .SH "Structures" The GC structure contains the following elements: .Ps .ta 3n 2.15i /* * Data structure for setting graphics context. */ typedef struct { int function; /* logical operation */ unsigned long plane_mask; /* plane mask */ unsigned long foreground; /* foreground pixel */ unsigned long background; /* background pixel */ int line_width; /* line width */ int line_style; /* Solid, OnOffDash, DoubleDash */ int cap_style; /* NotLast, Butt, Round, Projecting */ int join_style; /* Miter, Round, Bevel */ int fill_style; /* Solid, Tiled, Stippled */ int fill_rule; /* EvenOdd, Winding */ int arc_mode; /* PieSlice */ Pixmap tile; /* tile pixmap for tiling operations */ Pixmap stipple; /* stipple 1 plane pixmap for stipping */ int ts_x_origin; /* offset for tile or stipple operations */ int ts_y_origin; Font font; /* default text font for text operations */ int subwindow_mode; /* ClipByChildren, IncludeInferiors */ Bool graphics_exposures; /* boolean, should exposures be generated */ int clip_x_origin; /* origin for clipping */ int clip_y_origin; Pixmap clip_mask; /* bitmap clipping; other calls for rects */ int dash_offset; /* patterned/dashed line information */ char dashes; } XGCValues; #define GCFunction (1L<<0) #define GCPlaneMask (1L<<1) #define GCForeground (1L<<2) #define GCBackground (1L<<3) #define GCLineWidth (1L<<4) #define GCLineStyle (1L<<5) #define GCCapStyle (1L<<6) #define GCJoinStyle (1L<<7) #define GCFillStyle (1L<<8) #define GCFillRule (1L<<9) #define GCTile (1L<<10) #define GCStipple (1L<<11) #define GCTileStipXOrigin (1L<<12) #define GCTileStipYOrigin (1L<<13) #define GCFont (1L<<14) #define GCSubwindowMode (1L<<15) #define GCGraphicsExposures (1L<<16) #define GCClipXOrigin (1L<<17) #define GCClipYOrigin (1L<<18) #define GCClipMask (1L<<19) #define GCDashOffset (1L<<20) #define GCDashList (1L<<21) #define GCArcMode (1L<<22) .Pe .SH "Errors" .IP "\f(CWBadAlloc\fP" 1i .IP "\f(CWBadGC\fP" .IP "\f(CWBadMatch\fP" 1i \f(CIsrc\fP and \f(CIdest\fP do not have the same root and depth. .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXGetGCValues()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCopyPlane" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCopyPlane" .XX "planes:copying" .Na XCopyPlane \(en copy a single plane of a drawable into a drawable with depth, applying pixel values. .Nz .SH "Synopsis" .Sy XCopyPlane\^(\^\f(CIdisplay\f(CW, \f(CIsrc\f(CW\^, \f(CIdest\f(CW\^, \f(CIgc\f(CW\^, \f(CIsrc_x\f(CW\^, \f(CIsrc_y\f(CW\^, \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^, .ti +10n \f(CIdest_x\f(CW\^, \f(CIdest_y\f(CW\^, \f(CIplane\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIsrc\f(CW\^, \f(CIdest\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIsrc_x\f(CW\^, \f(CIsrc_y\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; int \f(CIdest_x\f(CW\^, \f(CIdest_y\f(CW\^; unsigned long \f(CIplane\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIsrc\fP 1i .br .ns .IP \f(CIdest\fP 1i .sp -2 Specify the source and destination drawables. .sp .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIsrc_x\fP 1i .br .ns .IP \f(CIsrc_y\fP 1i .sp -2 Specify the x and y coordinates of the upper-left corner of the source rectangle relative to the origin of the drawable. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight\fP 1i .sp -2 Specify the width and height in pixels. These are the dimensions of both the source and destination rectangles. .IP \f(CIdest_x\fP 1i .br .ns .IP \f(CIdest_y\fP 1i .sp -2 Specify the x and y coordinates at which the copied area will be placed relative to the origin of the destination drawable. .br .IP \f(CIplane\fP 1i Specifies the source bit-plane. You must set exactly one bit, and the bit must specify a plane that exists in \f(CIsrc\fP. .SH Description .LP \f(CWXCopyPlane()\fP copies a single plane of a rectangle in the source into the entire depth of a corresponding rectangle in the destination. The plane of the source drawable and the \f(CWforeground\fP/\f(CWbackground\fP pixel values in \f(CIgc\fP are combined to form a pixmap of the same depth as the destination drawable, and the equivalent of an \f(CWXCopyArea()\fP is performed, with all the same exposure semantics. .LP \f(CWXCopyPlane()\fP uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWforeground\fP, \f(CWbackground\fP, \f(CWsubwindow_mode\fP, \f(CWgraphics_exposures\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. .ad b .hy 14 .LP The \f(CIsrc\fP and \f(CIdest\fP drawables must have the same root, but need not have the same depth. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .br .ne 5 .SH "Errors" .IP "\f(CWBadDrawable\fP" 1i .IP "\f(CWBadGC\fP" 1i .IP "\f(CWBadMatch\fP" 1i \f(CIsrc\fP and \f(CIdest\fP do not have the same root. .IP "\f(CWBadValue\fP" 1i \f(CIplane\fP does not have exactly one bit set, or bit specified in \f(CIplane\fP is not a plane in \f(CIsrc\fP. .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCreateAssocTable" "Xlib \- Association Tables" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCreateAssocTable" .Na XCreateAssocTable \(en create a new association table (X10). .XX "association tables:creating" .Nz .SH "Synopsis" .Sy XAssocTable *XCreateAssocTable\^(\^\f(CIsize\f(CW\^) .As int \f(CIsize\f(CW\^; .Ae .SH "Arguments" .IP \f(CIsize\fP 1i Specifies the number of buckets in the hashed association table. .SH Returns The created association table. .SH Description \f(CWXCreateAssocTable()\fP creates an association table, which allows you to associate your own structures with X resources in a fast lookup table. This function is provided for compatibility with X Version 10. To use it you must include the file .I and link with the library \fI-loldX\fP. .LP The \f(CIsize\fP argument specifies the number of buckets in the hash system of \f(CWXAssoc\%Table\fP. For reasons of efficiency the number of buckets should be a power of two. Some size suggestions might be: use 32 buckets per 100 objects; a reasonable maximum number of object per buckets is 8. .LP If there is an error allocating memory for the \f(CWXAssocTable\fP, a \f(CWNULL\fP pointer is returned. .LP For more information on association tables, see Volume One, Appendix B, \fIX10 Compatibility\fR. .SH "Structures" .Ps typedef struct { XAssoc *buckets; /* pointer to first bucket in array */ int size; /* table size (number of buckets) */ } XAssocTable; .Pe .sp -1 .SH "See Also" \s-1\fIXDeleteAssoc()\fP\s+1, \s-1\fIXDestroyAssocTable()\fP\s+1, \s-1\fIXLookUpAssoc()\fP\s+1, \s-1\fIXMakeAssoc()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCreateBitmapFromData" "Xlib \- Pixmaps and Tiles" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCreateBitmapFromData" .XX "bitmaps:creating from X11 bitmap format data" .Na XCreateBitmapFromData \(en create a bitmap from \f(CWX11\fP bitmap format data. .Nz .SH "Synopsis" .Sy Pixmap XCreateBitmapFromData(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW, \f(CIdata\f(CW, .ti +10n \f(CIwidth\f(CW, \f(CIheight\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; char *\f(CIdata\f(CW\^; unsigned int \f(CIwidth\f(CW, \f(CIheight\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies a drawable. This determines which screen to create the bitmap on. .IP \f(CIdata\fP 1i Specifies the bitmap data, in X11 bitmap file format. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight\fP 1i .sp -2 Specify the dimensions in pixels of the created bitmap. .sp .SH Returns The created \f(CWPixmap\fR. .SH Description \f(CWXCreateBitmapFromData()\fP creates a single-plane pixmap from an array of hexadecimal data. This data may be defined in the program or included (using \f(CW#include\fR). The bitmap data must be in X version 11 format as shown below (it cannot be in X10 format). The following format is assumed for the data, where the variables are members of the \f(CWXImage\fP structure described in Volume One, Chapter 6, \fIDrawing Graphics and Text\fR: .LP .sp .5 .in +4.5n .nf .ft CW .ps 9 .vs 11 format=XYPixmap bit_order=LSBFirst byte_order=LSBFirst bitmap_unit=8 bitmap_pad=8 xoffset=0 no extra bytes per line .ps .vs .in -4.5n .fi .ft R .LP \f(CWXCreateBitmapFromData()\fP creates an image with the specified data and copies it into the created pixmap. The following is an example of creating a bitmap: .Ps .in +5n #define gray_width 16 #define gray_height 16 #define gray_x_hot 8 #define gray_y_hot 8 static char gray_bits[] = { 0xf8, 0x1f, 0xe3, 0xc7, 0xcf, 0xf3, 0x9f, 0xf9, 0xbf, 0xfd, 0x33, 0xcc, 0x7f, 0xfe, 0x7f, 0xfe, .ne 5 0x7e, 0x7e, 0x7f, 0xfe, 0x37, 0xec, 0xbb, 0xdd, 0x9c, 0x39, 0xcf, 0xf3, 0xe3, 0xc7, 0xf8, 0x1f}; Pixmap \f(CWXCreateBitmapFromData\fP(display, window, \f(CWgray_bits\fP, \f(CWgray_width\fP, \f(CWgray_height\fP); .in .Pe .LP If the call could not create a pixmap of the requested size on the server, \f(CWXCreateBitmapFromData()\fP returns \f(CWNone\fP, and the server generates a \f(CWBadAlloc\fP error. If the requested depth is not supported on the screen of the specified drawable, the server generates a \f(CWBadMatch\fP error. .LP The user should free the bitmap using \f(CWXFreePixmap()\fP when it is no longer needed. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH Errors .IP "\f(CWBadAlloc\fP" 1i Server has insufficient memory to create bitmap. .br .IP "\f(CWBadDrawable\fP" 1i .br .IP "\f(CWBadValue\fP" 1i Specified bitmap dimensions are zero. .LP .SH "See Also" \s-1\fIXCreatePixmap()\fP\s+1, \s-1\fIXCreatePixmapFromBitmapData()\fP\s+1, \s-1\fIXCreatePixmapFromBitmapData()\fP\s+1, \s-1\fIXFreePixmap()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXQueryBestStipple()\fP\s+1, \s-1\fIXQueryBestTile()\fP\s+1, \s-1\fIXReadBitmapFile()\fP\s+1, \s-1\fIXSetTile()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1, \s-1\fIXWriteBitmapFile()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCreateColormap" "Xlib \- Colormaps" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCreateColormap" .XX "colormaps:creating" .Na XCreateColormap \(en create a colormap. .Nz .SH "Synopsis" .Sy Colormap XCreateColormap\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIvisual\f(CW\^, \f(CIalloc\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; Visual *\f(CIvisual\f(CW\^; int \f(CIalloc\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies a window ID. The colormap created will be associated with the same screen as the window. .IP \f(CIvisual\fP 1i Specifies a pointer to the \f(CWVisual\fR structure for the colormap. The visual class and depth must be supported by the screen. .hw Alloc-All .IP \f(CIalloc\fP 1i Specifies how many colormap entries to allocate. Pass either \f(CWAllocNone\fP or \f(CWAllocAll\fP. .SH Returns The created colormap. .SH Description \f(CWXCreateColormap()\fP creates a colormap of the specified visual type and allocates either none or all of its entries, and returns the colormap ID. .LP It is legal to specify any visual class in the structure pointed to by the \f(CIvisual\fP argument. If the class is \f(CWStaticColor\fP, \f(CWStaticGray\fP, or \f(CWTrueColor\fP, the colorcells will have pre-allocated read-only values defined by the individual server but unspecified by the X11 protocol. In these cases, \f(CIalloc\fP must be specified as \f(CWAllocNone\fP (else a \f(CWBadMatch\fP error). .LP For the other visual classes, \f(CWPseudoColor\fP, \f(CWDirectColor\fP, and \f(CWGrayScale\fP, you can pass either \f(CWAllocAll\fP or \f(CWAllocNone\fP to the \f(CIalloc\fP argument. If you pass \f(CWAllocNone\fP, the colormap has no allocated entries. This allows your client programs to allocate read-only colorcells with \f(CWXAllocColor\fP or read/write cells with \f(CWXAllocColorCells()\fP, \f(CWAllocColorPlanes\fR and \f(CWXStoreColors()\fP. If you pass the constant \f(CWAllocAll\fP, the entire colormap is allocated writable (all the entries are read/write, nonshareable and have undefined initial RGB values), and the colors can be set with \f(CWXStoreColors()\fP. However, you cannot free these entries with \f(CWXFreeColors()\fP, and no relationships between the entries are defined. .LP If the visual class is \f(CWPseudoColor\fP or \f(CWGrayScale\fP and \f(CIalloc\fP is \f(CWAllocAll\fP, this function simulates a call to the function \f(CWXAllocColor()\fR cells returning all pixel values from \f(CW1\fR to \f(CW(map_entries - 1)\fR. For a visual class of \f(CWDirectColor\fR, the processing for \f(CWAllocAll\fR simulates a call to the function \f(CWXAllocColorPlanes()\fR, returning a pixel value of 0 and mask values the same as the \f(CWred_mask,\fR \f(CWgreen_mask,\fR and \f(CWblue_mask\fR members in \f(CIvisual\fR. .LP .ne 4 The \f(CIvisual\fR argument should be as returned from the \f(CWDefaultVisual\fR macro, \f(CWXMatchVisualInfo()\fR, or \f(CWXGetVisualInfo()\fR. .LP If the hardware colormap on the server is immutable, and therefore there is no possibility that a virtual colormap could ever be installed, \f(CWXCreateColormap()\fP returns the default colormap. Code should check the returned ID against the default colormap to catch this situation. .LP For more information on creating colormaps, see Volume One, Chapter 7, \fIColor\fR. .SH "Errors" .IP "\f(CWBadAlloc\fP" 1i .IP "\f(CWBadMatch\fP" 1i Didn't use \f(CWAllocNone\fP for \f(CWStaticColor\fP, \f(CWStaticGray\fP, or \f(CWTrueColor\fP. .br \f(CIvisual\fP type not supported on screen. .IP "\f(CWBadValue\fP" 1i .IP "\f(CWBadWindow\fP" 1i .SH "See Also" \s-1\fIXDefaultColormap()\fP\s+1, \s-1\fIXDisplayCells()\fP\s+1, \s-1\fIXCopyColormapAndFree()\fP\s+1, \s-1\fIXFreeColormap()\fP\s+1, \s-1\fIXGetStandardColormap()\fP\s+1, \s-1\fIXInstallColormap()\fP\s+1, \s-1\fIXListInstalledColormaps()\fP\s+1, \s-1\fIXSetStandardColormap()\fP\s+1, \s-1\fIXSetWindowColormap()\fP\s+1, \s-1\fIXUninstallColormap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCreateFontCursor" "Xlib \- Cursors" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCreateFontCursor" .XX "cursors:creating;from standard cursor font" .Na XCreateFontCursor \(en create a cursor from the standard cursor font. .Nz .SH "Synopsis" .Sy #include .As Cursor XCreateFontCursor\^(\^\f(CIdisplay\f(CW, \f(CIshape\f(CW\^) Display *\f(CIdisplay\f(CW\^; unsigned int \f(CIshape\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .8i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIshape\fP Specifies which character in the standard cursor font should be used for the \%cursor. .SH Returns The created cursor. .SH Description X provides a set of standard cursor shapes in a special font named "cursor." Programs are encouraged to use this interface for their cursors, since the font can be customized for the individual display type and shared between clients. .LP The hotspot comes from the information stored in the font. The initial colors of the cursor are black for the \f(CWforeground\fP and white for the \f(CWbackground\fP. \f(CWXRecolorCursor()\fP can be used to change the colors of the cursor to those desired. .Fs .Pf amp2.eps "" "" "" "" noscale .Fe "The cursor shapes in the standard cursor font" .LP .Nd 10 For more information about cursors and their shapes in fonts, see Appendix I, \fIThe Cursor Font\fR. .SH "Errors" .IP "\f(CWBadAlloc\fP" 1i .br .IP "\f(CWBadFont\fP" 1i .br .IP "\f(CWBadValue\fP" 1i The \f(CIshape\fP argument does not specify a character in the standard cursor font. .SH "See Also" \s-1\fIXCreateGlyphCursor()\fP\s+1, \s-1\fIXCreatePixmapCursor()\fP\s+1, \s-1\fIXDefineCursor()\fP\s+1, \s-1\fIXFreeCursor()\fP\s+1, \s-1\fIXQueryBestCursor()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXRecolorCursor()\fP\s+1, \s-1\fIXUndefineCursor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCreateFontSet" "Xlib \- Internationalized Text Output" .ds ]W Xlib Reference Manual .XX "XCreateFontSet" .XX "font set:creating" .SH Name .Na XCreateFontSet \(en create a font set. .Nz .SH Synopsis .Sy XFontSet XCreateFontSet\^(\^\f(CIdisplay\fP\^, \f(CIbase_font_name_list\fP\^, .br \f(CImissing_charset_list_return\fP\^, \f(CImissing_charset_count_return\fP\^, .br \f(CIdef_string_return\fP\^) .As Display *\f(CIdisplay\fP\^; char *\f(CIbase_font_name_list\fP\^; char ***\f(CImissing_charset_list_return\fP\^; int *\f(CImissing_charset_count_return\fP\^; char **\f(CIdef_string_return\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIbase_font_name_list\fP 1i Specifies the base font names. .IP \f(CImissing_charset_list_return\fP 1i Returns the missing charsets. .IP \f(CImissing_charset_count_return\fP 1i Returns the number of missing charsets. .IP \f(CIdef_string_return\fP 1i Returns the string drawn for missing charsets. .SH Returns The created font set. .SH Availability Release 5 and later. .SH Description \f(CWXCreateFontSet()\fR creates a font set for the specified display. The font set is bound to the current locale when \f(CWXCreateFontSet()\fR is called. The \f(CIfont_set\fP may be used in subsequent calls to obtain font and character information, and to image text in the locale of the \f(CIfont_set\fP. .LP The \f(CIbase_font_name_list\fP argument is a comma-separated list of base font names which Xlib uses to load the fonts needed for the locale. The string is \f(CWNULL\fP-terminated, and is assumed to be in the Host Portable Character Encoding; otherwise, the result is implementation-dependent. Whitespace immediately on either side of a separating comma is ignored. .LP Use of XLFD font names permits Xlib to obtain the fonts needed for a variety of locales from a single locale-independent base font name. When used, this single base font name should name a family of fonts whose members .ne 6 are encoded in the various charsets needed by the locales of interest. .LP Alternatively, an XLFD base font name can explicitly name a charset needed for the locale. This allows the user to specify an exact font for use with a charset required by a locale, fully controlling the font selection. .LP If a base font name is not an XLFD name, Xlib will attempt to obtain an XLFD name from the font properties for the font. If this action is successful in obtaining an XLFD name, the \f(CWXBaseFontNameListOfFontSet()\fR function will return this XLFD name instead of the client-supplied name. .LP The following algorithm is used to select the fonts that will be used to display text with the \f(CWXFontSet\fR: .LP For each font charset required by the locale, the base font name list is searched for the first one of the following cases that names a set of fonts that exist at the server: .IP 1. 3 The first XLFD-conforming base font name that specifies the required charset or a superset of the required charset in its \f(CWCharSetRegistry\fR and \f(CWCharSetEncoding\fR fields. The implementation may use a base font name whose specified charset is a superset of the required charset, for example, an ISO8859-1 font for an ASCII charset. .IP 2. 3 The first set of one or more XLFD-conforming base font names that specify one or more charsets that can be remapped to support the required charset. The Xlib implementation may recognize various mappings from a required charset to one or more other charsets, and use the fonts for those charsets. For example, JIS Roman is ASCII with tilde and backslash replaced by yen and overbar; Xlib may load an ISO8859-1 font to support this character set, if a JIS Roman font is not available. .IP 3. 3 The first XLFD-conforming font name, or the first non-XLFD font name for which an XLFD font name can be obtained, combined with the required charset (replacing the \f(CWCharSetRegistry\fR and \f(CWCharSetEncoding\fR fields in the XLFD font name). As in case 1, the implementation may use a charset which is a superset of the required charset. .IP 4. 3 The first font name that can be mapped in some implementation-dependent manner to one or more fonts that support imaging text in the charset. .LP For example, assume a locale required the charsets: .LP .DS 0 ISO8859-1 JISX0208.1983 JISX0201.1976 GB2312-1980.0 .DE .LP .Nd 10 Users could supply a \f(CIbase_font_name_list\fP which explicitly specifies the charsets, insuring that specific fonts get used if they exist: .LP .DS 0 <">-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\\ -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\\ -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\\ -Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1<"> .DE .Nd 20 .LP Or they could supply a \f(CIbase_font_name_list\fP which omits the charsets, letting Xlib select font charsets required for the locale: .LP .DS 0 <">-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\ -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\\ -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\\ -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150<"> .DE .LP Or they could simply supply a single base font name which allows Xlib to select from all available fonts which meet certain minimum XLFD property requirements: .LP .DS 0 <">-*-*-*-R-Normal--*-180-100-100-*-*<"> .DE .LP If \f(CWXCreateFontSet()\fR is unable to create the font set, either because there is insufficient memory or because the current locale is not supported, \f(CWXCreateFontSet()\fR returns \f(CWNULL\fP, \f(CImissing_charset_list_return\fP is set to \f(CWNULL\fP, and \f(CImissing_charset_count_return\fP is set to zero. If fonts exist for all of the charsets required by the current locale, \f(CWXCreateFontSet()\fR returns a valid \f(CWXFontSet\fR, \f(CImissing_charset_list_return\fP is set to \f(CWNULL\fP, and \f(CImissing_charset_count_return\fP is set to zero. .LP If no font exists for one or more of the required charsets, \f(CWXCreateFontSet()\fR sets \f(CImissing_charset_list_return\fP to a list of one or more \f(CWNULL\fP-terminated charset names for which no font exists, and sets \f(CImissing_charset_count_return\fP to the number of missing fonts. The charsets are from the list of the required charsets for the encoding of the locale, and do not include any charsets to which Xlib may be able to remap a required charset. .LP If no font exists for any of the required charsets, or if the locale definition in Xlib requires that a font exist for a particular charset and a font is not found for that charset, \f(CWXCreateFontSet()\fR returns \f(CWNULL\fP. Otherwise, \f(CWXCreateFontSet()\fR returns a valid \f(CWXFontSet\fR to \f(CIfont_set\fP. .LP When an Xmb/wc drawing or measuring function is called with an \f(CWXFontSet\fR that has missing charsets, some characters in the locale will not be drawable. If \f(CIdef_string_return\fP is non-\f(CWNULL\fP, \f(CWXCreateFontSet()\fR returns a pointer to a string which represents the glyph(s) which are drawn with this \f(CWXFontSet\fR when the charsets of the available fonts do not include all font glyph(s) required to draw a codepoint. The string does not necessarily consist of valid characters in the current locale and is not necessarily drawn with the fonts loaded for the font set, but the client can draw and measure the "default glyphs" .ne 2 by including this string in a string being drawn or measured with the \f(CWXFontSet\fR. .LP If the string returned to \f(CIdef_string_return\fP is the empty string (\f(CW""\fP), no glyphs are drawn, and the escapement is zero. The returned string is \f(CWNULL\fP-terminated. It is owned by Xlib and should not be modified or freed by the client. It will be freed by a call to \f(CWXFreeFontSet()\fR with the associated \f(CWXFontSet\fR. Until freed, its contents will not be modified by Xlib. .LP The client is responsible for constructing an error message from the missing charset and default string information, and may choose to continue operation in the case that some fonts did not exist. .LP The returned \f(CWXFontSet\fR and missing charset list should be freed with \f(CWXFreeFontSet()\fR and \f(CWXFreeStringList()\fR, respectively. The client-supplied \f(CIbase_font_name_list\fP may be freed by the client after calling \f(CWXCreateFontSet()\fR. .SH "See Also" \s-1\fIXExtentsOfFontSet()\fP\s+1, \s-1\fIXFontsOfFontSet()\fP\s+1, \s-1\fIXFreeFontSet()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCreateGC" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCreateGC" .XX "graphics context:creating" .Na XCreateGC \(en create a new graphics context for a given screen with the depth of the specified drawable. .Nz .SH "Synopsis" .Sy GC XCreateGC\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIvaluemask\f(CW\^, \f(CIvalues\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; unsigned long \f(CIvaluemask\f(CW\^; XGCValues *\^\f(CIvalues\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies a drawable. The created GC can only be used to draw in drawables of the same depth as this \f(CIdrawable\fP. .IP \f(CIvaluemask\fP 1i Specifies which members of the GC are to be set using information in the \f(CIvalues\fP structure. \f(CIvaluemask\fP is made by combining any number of the mask symbols listed in the Structures section. .IP \f(CIvalues\fP 1i Specifies a pointer to an \f(CWXGCValues\fP structure which will provide components for the new GC. .SH Returns The created GC. .SH Description \f(CWXCreateGC()\fP creates a new graphics context resource in the server. The returned GC can be used in subsequent drawing requests, but only on drawables on the same screen and of the same depth as the drawable specified in the \f(CIdrawable\fP argument. .LP The specified components of the new graphics context in \f(CIvaluemask\fP are set to the values passed in the \f(CIvalues\fP argument. Unset components default as follows: .sp .sp 1 .in 0 .KS .TS H linesize(2); l l lp7fCWw(1.5i) lp7fCWw(2.5i). Component Value .sp 2p .sp 2p .Th function GX copy plane_mask \fR\s+1all 1's\s0\fP foreground 0 background 1 line_width 0 line_style LineSolid cap_style CapButt join_style JoinMiter fill_style FillSolid fill_rule EvenOddRule arc_mode ArcPieSlice tile \fR\s+1Pixmap filled with foreground pixel\s0\fP stipple \fR\s+1Pixmap filled with 1's\s0\fP ts_x_origin 0 ts_y_origin 0 font \fR(\s+1implementation-dependent)\s0\fP subwindow_mode ClipByChildren graphics_exposures True clip_x_origin 0 clip_y_origin 0 clip_mask None dash_offset 0 dashes 4 \fR\s+1(i.e., the list [4, 4])\s0\fP .sp 5p .TE .KE .in .sp 1 .sp .5 .LP An application should minimize the number of GCs it creates, because some servers cache a limited number of GCs in the display hardware, and can attain better performance with a small number of GCs. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .SH "Errors" .IP "\f(CWBadAlloc\fP" 1i Server could not allocate memory for GC. .IP "\f(CWBadDrawable\fP" 1i Specified drawable is invalid. .IP "\f(CWBadFont\fP" 1i Font specified for \f(CIfont\fP component of GC has not been loaded. .IP "\f(CWBadMatch\fP" 1i Pixmap specified for \f(CItile\fP component has different depth or is on different screen from the specified drawable. Or pixmap specified for \f(CWstipple\fP or \f(CWclip_mask\fP component has depth other than 1. .IP "\f(CWBadPixmap\fP" 1i Pixmap specified for \f(CItile\fP, \f(CIstipple\fP, or \f(CWclip_mask\fP components is invalid. .IP "\f(CWBadValue\fP" 1i Values specified for \f(CIfunction\fP, \f(CWline_style\fP, \f(CWcap_style\fP, \f(CWjoin_style\fP, \f(CWfill_style\fP, \f(CWfill_rule\fP, \f(CWsubwindow_mode\fP, \f(CWgraphics_exposures\fP, \f(CWdashes\fP, or \f(CWarc_mode\fP are invalid, or invalid mask specified for \f(CIvaluemask\fP argument. .Nd 10 .SH "Structures" .Ps .ta 4.5n 2.2i typedef struct { int function; /* logical operation */ unsigned long plane_mask; /* plane mask */ unsigned long foreground; /* foreground pixel */ unsigned long background; /* background pixel */ int line_width; /* line width */ int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */ int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */ int join_style; /* JoinMiter, JoinRound, JoinBevel */ int fill_style; /* FillSolid, FillTiled, FillStippled */ int fill_rule; /* EvenOddRule, WindingRule */ int arc_mode; /* ArcPieSlice, ArcChord */ Pixmap tile; /* tile pixmap for tiling operations */ Pixmap stipple; /* stipple 1 plane pixmap for stipping */ int ts_x_origin; /* offset for tile or stipple operations */ int ts_y_origin; Font font; /* default text font for text operations */ int subwindow_mode; /* ClipByChildren, IncludeInferiors */ Bool graphics_exposures; /* generate events on XCopyArea, XCopyPlane */ int clip_x_origin; /* origin for clipping */ int clip_y_origin; Pixmap clip_mask; /* bitmap clipping; other calls for rects */ int dash_offset; /* patterned/dashed line information */ char dashes; } XGCValues; #define GCFunction (1L<<0) #define GCPlaneMask (1L<<1) #define GCForeground (1L<<2) #define GCBackground (1L<<3) #define GCLineWidth (1L<<4) #define GCLineStyle (1L<<5) #define GCCapStyle (1L<<6) #define GCJoinStyle (1L<<7) #define GCFillStyle (1L<<8) #define GCFillRule (1L<<9) #define GCTile (1L<<10) #define GCStipple (1L<<11) #define GCTileStipXOrigin (1L<<12) #define GCTileStipYOrigin (1L<<13) #define GCFont (1L<<14) #define GCSubwindowMode (1L<<15) #define GCGraphicsExposures (1L<<16) #define GCClipXOrigin (1L<<17) #define GCClipYOrigin (1L<<18) .ne 8 #define GCClipMask (1L<<19) #define GCDashOffset (1L<<20) #define GCDashList (1L<<21) #define GCArcMode (1L<<22) .Pe .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXGetGCValues()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCreateGlyphCursor" "Xlib \- Cursors" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCreateGlyphCursor" .XX "cursors:creating;from font glyphs" .XX "font glyphs:creating cursors from" .Na XCreateGlyphCursor \(en create a cursor from font glyphs. .Nz .SH "Synopsis" .Sy Cursor XCreateGlyphCursor\^(\^\f(CIdisplay\f(CW, \f(CIsource_font\f(CW\^, \f(CImask_font\f(CW\^, \f(CIsource_char\f(CW\^, \f(CImask_char\f(CW\^, \f(CIforeground_color\f(CW\^, \f(CIbackground_color\f(CW\^) .in -10n .As Display *\f(CIdisplay\f(CW\^; Font \f(CIsource_font\f(CW\^, \f(CImask_font\f(CW\^; unsigned int \f(CIsource_char\f(CW\^, \f(CImask_char\f(CW\^; XColor *\f(CIforeground_color\f(CW\^; XColor *\f(CIbackground_color\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIsource_font\fP 1i Specifies the font from which a character is to be used for the cursor. .\" *** JIM: NEED TO CHECK THIS. *** .IP \f(CImask_font\fP 1i Specifies the mask font or \f(CWNone\fP. .\" *** JIM: NEED TO CHECK THIS. *** .IP \f(CIsource_char\fP 1i Specifies the index into the cursor shape font. .\" *** JIM: NEED TO MORE INFO FOR THIS ONE. *** .IP \f(CImask_char\fP 1i Specifies the index into the mask shape font. Optional; specify 0 if not needed. .IP \f(CIforeground_color\fP 1i Specifies the red, green, and blue (RGB) values for the foreground. .IP \f(CIbackground_color\fP 1i Specifies the red, green, and blue (RGB) values for the background. .SH Returns The created cursor. .SH Description .XX "XCreatePixmapCursor:versus XCreateGlyphCursor" \f(CWXCreateGlyphCursor()\fP is similar to \f(CWXCreatePixmapCursor()\fP, but the source and mask bitmaps are obtained from separate font characters, perhaps in separate fonts. The mask font and character are optional. If \f(CImask_char\fP is not specified, all pixels of the source are displayed. .LP The x offset for the hotspot of the created cursor is the left-bearing for the source character, and the y offset is the ascent, each measured from the upper-left corner of the bounding rectangle of the character. .LP The origins of the source and mask (if it is defined) characters are positioned coincidently and define the hotspot. The source and mask need not have the same bounding box metrics, and there is no restriction on the placement of the hotspot relative to the bounding boxes. .LP Note that \f(CIsource_char\fP and \f(CImask_char\fP are of type \f(CWunsigned\fR \f(CWint\fR, not of type \f(CWXChar2b\fR. For two-byte matrix fonts, \f(CIsource_char\fR and \f(CImask_char\fP should be formed with the \f(CWbyte1\fP member in the most significant byte and the \f(CWbyte2\fP member in the least significant byte. .LP .ne 5 You can free the fonts with \f(CWXFreeFont()\fP if they are no longer needed after creating the glyph cursor. .LP For more information on fonts and cursors, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" .Ps typedef struct { unsigned long pixel; unsigned short red, green, blue; char flags; /* DoRed, DoGreen, DoBlue */ char pad; } XColor; .Pe .SH "Errors" .IP "\f(CWBadAlloc\fP" 1i .IP "\f(CWBadFont\fP" .IP "\f(CWBadValue\fP" \f(CIsource_char\fP not defined in \f(CIsource_font\fP. .br \f(CImask_char\fP not defined in \f(CImask_font\fP (if \f(CImask_font\fP defined). .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXCreatePixmapCursor()\fP\s+1, \s-1\fIXDefineCursor()\fP\s+1, \s-1\fIXFreeCursor()\fP\s+1, \s-1\fIXQueryBestCursor()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXRecolorCursor()\fP\s+1, \s-1\fIXUndefineCursor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCreateIC" "Xlib \- Input Contexts" .ds ]W Xlib Reference Manual .XX "XCreateIC" .XX "input contexts:creating" .XX "input contexts:attributes" .XX "input methods:creating IC associated with" .SH Name .Na XCreateIC \(en create an input context. .Nz .SH Synopsis .Sy XIC XCreateIC\^(\^\f(CIim\fP\^, ...) .As XIM \f(CIim\fP\^; .Ae .SH Arguments .IP \f(CIim\fP 1i Specifies the input method. .ds Al \ to set XIC values .IP ... 1i Specifies the variable length argument list\*(Al. .SH Returns The created input context. .SH Availability Release 5 and later. .SH Description \f(CWXCreateIC()\fP creates an input context associated with the specified input method. The first argument to this function is the "parent" input method, and it is followed by a \f(CWNULL\fP-terminated variable-length argument list of input context attribute name/value pairs. The tables below list the standard attribute names and their types. Note that the \f(CWXNInputStyle\fP attribute and \f(CWXNFontSet\fP sub-attribute for the Preedit and Status areas must be specified when the IC is created. \f(CWXNSpotLocation\fP must be specified for the Preedit area if the pre-edit interaction style is \f(CWXIMPreeditPosition\fP. All the Preedit and Status callbacks must be specified in the call to \f(CWXCreateIC()\fP if the interaction style is \f(CWXIMPreeditCallbacks\fP or \f(CWXIMStatusCallbacks\fP. Any other attributes may be set with \f(CWXCreateIC()\fR, but are not required. .sp 6p \f(HIInput Context Attributes\fP .vs 11p .sp 1 .in 0 .KS .TS tab(@), linesize(2); lb lb lb lp7fCW lp7fCW l. Name@Type@Notes .sp 2p .sp 2p XNInputStyle@XIMStyle@T{ .na Required at IC creation; may not be changed. T} .sp 2p XNClientWindow@Window@T{ .na Must be set before IC use; may not be changed. T} .sp 2p XNFocusWindow@Window@Changes may cause geometry negotiation. .sp 2p XNResourceName@char * .sp 2p XNResourceClass@char * .sp 2p XNGeometryCallback@XIMCallback * .sp 2p .ig ++ .sp 5p .TE 0 .KE .in .sp 1 .Nd 20 \f(HIInput Context Attributes (continued)\fP .sp 6p .sp 1 .in 0 .KS .TS tab(@), linesize(2); lb lb lb lp7fCW lp7fCW l. Name@Type@Notes .sp 4p .sp 2p .++ XNFilterEvents@unsigned long@Read-only attribute; may not be set. .sp 2p XNPreeditAttributes@XVaNestedList@See sub-attributes below. .sp 2p XNStatusAttributes@XVaNestedList@See sub-attributes below. .sp 3p .TE 0 .KE .in .sp 1 .Nd 12 \f(HIPre-edit and Status Area Sub-attributes\fP .sp 6p .sp 1 .in 0 .KS .TS H tab(@), linesize(2); lb lb lb lp7fCW lp7fCW lp10w(1.6i). Name@Type@Notes .sp 2p .sp 2p .Th XNArea@XRectangle * .sp 3p XNAreaNeeded@XRectangle * .sp 3p XNSpotLocation@XPoint *@T{ Required at IC creation for XIMPreeditPosition style. T} .sp 3p XNColormap@Colormap .sp 3p XNStdColormap@Atom .sp 3p XNForeground@unsigned long .sp 3p XNBackground@unsigned long .sp 3p XNBackgroundPixmap@Pixmap .sp 3p XNFontSet@XFontSet@T{ Required at IC creation; changes may cause geometry negotiation. T} .sp 3p XNLineSpacing@int@T{ Changes may cause geometry negotiation. T} .sp 3p XNCursor@Cursor .sp 3p XNPreeditStartCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} .sp 3p XNPreeditDoneCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} .sp 3p XNPreeditDrawCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} .sp 3p XNPreeditCaretCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} .sp 3p XNStatusStartCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fR style. T} .sp 3p XNStatusDoneCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fR style. T} .sp 3p XNStatusDrawCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fR style. T} .sp 5p .TE .KE .in .sp 1 .vs 12 .ig ++ .vs 10 .Ts .sp 1 .in 0 .KS .TS H tab(@), linesize(2); lb lb lb lfCWw(1.8i) lfCW lw(1.9i). .sp 2p Name@Type@Notes .sp 2p .sp 2p .Th XNInputStyle@XIMStyle@T{ Required at IC creation; may not be changed. T} .sp 4p XNClientWindow@Window@T{ Must be set before IC use; may not be changed. T} .sp 4p XNFocusWindow@Window@T{ Changes may cause geometry negotiation. T} .sp 4p XNResourceName@char * .sp 4p XNResourceClass@char * .sp 4p XNGeometryCallback@XIMCallback * .sp 4p XNFilterEvents@unsigned long@T{ .sp 4p Read-only attribute; may not be set. T} .sp 4p XNPreeditAttributes@XVaNestedList@T{ See sub-attributes below. T} .sp 4p XNStatusAttributes@XVaNestedList@T{ See sub-attributes below. T} .sp 5p .TE .KE .in .sp 1 .Te "Input Context Attributes" .Ts .sp 1 .in 0 .KS .TS h tab(@), linesize(2); lb lb lb lfCW lfCW lw(1.9i). Name@Type@Notes .sp 2p .sp 2p .Th XNArea@XRectangle * .sp 4p XNAreaNeeded@XRectangle * .sp 4p XNSpotLocation@XPoint *@T{ Required at IC creation for \f(CWXIMPreeditPosition\fR style. T} .sp 4p XNColormap@Colormap .sp 4p XNStdColormap@Atom .sp 4p XNForeground@unsigned long .sp 4p XNBackground@unsigned long .sp 4p XNBackgroundPixmap@Pixmap .sp 4p XNFontSet@XFontSet@T{ Required at IC creation; changes may cause geometry negotiation. T} .sp 4p XNLineSpacing@int@T{ Changes may cause geometry negotiation. T} .sp 4p XNCursor@Cursor .sp 4p XNPreeditStartCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fR style. T} .sp 4p XNPreeditDoneCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fR style. T} .sp 4p XNPreeditDrawCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fR style. T} .sp 4p XNPreeditCaretCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fR style. T} .sp 4p XNStatusStartCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fR style. T} .sp 4p XNStatusDoneCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fR style. T} .sp 4p XNStatusDrawCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fR style. T} .sp 5p .TE .KE .in .sp 1 .Te "Preedit and Status Area Sub-attributes" .++ .LP In addition to the attribute names above, the special name \f(CWXNVaNestedList\fR indicates that the following argument is a \f(CWXVaNestedList\fP of attribute name/value pairs. When a nested list is encountered in an argument list, the contents of the nested list are processed as if they appeared in the original argument list at that point. .LP \f(CWXCreateIC()\fR returns a \f(CWNULL\fP value if no input context could be created. A \f(CWNULL\fP value could be returned for any of the following reasons: .IP \(bu 3n A required argument was not set. .IP \(bu 3n A read-only argument was set (for example, \f(CWXNFilterEvents\fR). .IP \(bu 3n The argument name is not recognized. .IP \(bu 3n The input method encountered an implementation-dependent error. .SH Errors .IP \f(CWBadAtom\fR 1i A value for an Atom argument does not name a defined Atom. .IP \f(CWBadColor\fR 1i A value for a Colormap argument does not name a defined Colormap. .IP \f(CWBadPixmap\fR 1i A value for a Pixmap argument does not name a defined Pixmap. .IP \f(CWBadWindow\fR 1i A value for a Window argument does not name a defined Window. .SH "See Also" \s-1\fIXOpenIM()\fP\s+1, \s-1\fIXSetICFocus()\fP\s+1, \s-1\fIXSetICValues()\fP\s+1, \s-1\fIXDestroyIC()\fP\s+1, \s-1\fIXIMOfIC()\fP\s+1, \s-1\fIXmbResetIC()\fP\s+1, \s-1\fIXwcResetIC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCreateImage" "Xlib \- Images" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCreateImage" .XX "XImage structure:allocate memory for" .XX "structures:XImage" .XX "images" .Na XCreateImage \(en allocate memory for an \f(CWXImage\fP structure. .Nz .SH "Synopsis" .Sy XImage *XCreateImage\^(\^\f(CIdisplay\f(CW, \f(CIvisual\f(CW, \f(CIdepth\f(CW, \f(CIformat\f(CW, \f(CIoffset\f(CW, .in +10n \f(CIdata\f(CW, \f(CIwidth\f(CW, \f(CIheight\f(CW\^, \f(CIbitmap_pad\f(CW, \f(CIbytes_per_line\f(CW\^) .in -10n .As Display *\f(CIdisplay\f(CW\^; Visual *\f(CIvisual\f(CW\^; unsigned int \f(CIdepth\f(CW\^; int \f(CIformat\f(CW\^; int \f(CIoffset\f(CW\^; char *\f(CIdata\f(CW\^; unsigned int \f(CIwidth\f(CW\^; unsigned int \f(CIheight\f(CW\^; int \f(CIbitmap_pad\f(CW\^; int \f(CIbytes_per_line\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIvisual\fP 1i Specifies a pointer to a visual that should match the visual of the window the image is to be displayed in. .IP \f(CIdepth\fP 1i Specifies the depth of the image. .IP \f(CIformat\fP 1i Specifies the format for the image. Pass one of these constants: \f(CWXYBitmap\fR, \f(CWXYPixmap\fP, or \f(CWZPixmap\fP. .IP \f(CIoffset\fP 1i Specifies the number of pixels beyond the beginning of the data (pointed to by \f(CIdata\fR) where the image actually begins. This is useful if the image is not aligned on an even addressable boundary. .IP \f(CIdata\fP 1i Specifies a pointer to the image data. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight\fP 1i .sp -2 Specify the width and height in pixels of the image. .sp .IP \f(CIbitmap_pad\fP 1i Specifies the quantum of a scan line. In other words, the start of one scan line is separated in client memory from the start of the next scan line by an integer multiple of this many bits. You must pass one of these values: \f(CW8\fP, \f(CW16\fP, or \f(CW32\fP. .IP \f(CIbytes_per_line\fP 1i Specifies the number of bytes in the client image between the start of one scan line and the start of the next. If you pass a value of 0 here, Xlib assumes that the scan lines are contiguous in memory and thus calculates the value of \f(CWbytes_per_line\fP itself. .LP .ne 4 .SH Returns The image structure. .SH Description \f(CWXCreateImage()\fP allocates the memory needed for an \f(CWXImage\fP structure for the specified display and visual. .LP This function does not allocate space for the image itself. It initializes the structure with byte order, bit order, and bitmap unit values, and returns a pointer to the \f(CWXImage\fP structure. The red, green, and blue mask values are defined for \f(CWZPixmap\fP format images only and are derived from the \f(CWVisual\fP structure passed in. .LP Note that when the image is created using \f(CWXCreateImage()\fP, \f(CWXGetImage()\fP, or \f(CWXSubImage()\fP, the \f(CWdestroy\fP procedure that \f(CWXDestroyImage()\fP calls frees both the image structure and the data pointed to by the image structure. For a description of images, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "See Also" \s-1\fIXImageByteOrder()\fP\s+1, \s-1\fIXAddPixel()\fP\s+1, \s-1\fIXDestroyImage()\fP\s+1, \s-1\fIXGetImage()\fP\s+1, \s-1\fIXGetPixel()\fP\s+1, \s-1\fIXGetSubImage()\fP\s+1, \s-1\fIXPutImage()\fP\s+1, \s-1\fIXPutPixel()\fP\s+1, \s-1\fIXSubImage()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH XCreatePixmap "Xlib \- Pixmaps and Tiles" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCreatePixmap" .XX "pixmaps:creating" .Na XCreatePixmap \(en create a pixmap. .Nz .SH "Synopsis" .Sy Pixmap XCreatePixmap\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^, \f(CIdepth\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; unsigned int \f(CIdepth\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. May be an \f(CWInputOnly\fP window. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight\fP 1i .sp -2 Specify the width and height in pixels of the pixmap. The values must be non-zero. .IP \f(CIdepth\fP 1i Specifies the depth of the pixmap. The depth must be supported by the screen of the specified drawable. (Use \f(CWXListDepths()\fR if in doubt.) .SH Returns The created Pixmap. .SH Description \f(CWXCreatePixmap()\fP creates a \f(CIpixmap\fP resource and returns its pixmap ID. The initial contents of the pixmap are undefined. .LP The server uses the \f(CIdrawable\fR argument to determine which screen the pixmap is stored on. The pixmap can only be used on this screen. The pixmap can only be drawn drawn into with GCs of the same depth, and can only be copied to drawables of the same depth, except in \f(CWXCopyPlane()\fR. .LP A bitmap is a single-plane pixmap. There is no separate bitmap type in X Version 11. .LP Pixmaps should be considered a precious resource, since many servers have limits on the amount of off-screen memory available. .LP If you are creating a pixmap for use in \f(CWXCreatePixmapCursor()\fR, specify \f(CWdepth = 1\fR, \f(CWfg = 1\fR, and \f(CWbg = 0\fR. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .Nd 10 .SH "Errors" .IP "\f(CWBadAlloc\fP" 1i .IP "\f(CWBadDrawable\fP" 1i .IP "\f(CWBadValue\fP" 1i \f(CIwidth\fP or \f(CIheight\fP is 0. .br \f(CIdepth\fP is not supported on screen. .SH "See Also" \s-1\fIXCreateBitmapFromData()\fP\s+1, \s-1\fIXCreatePixmapFromBitmapData()\fP\s+1, \s-1\fIXFreePixmap()\fP\s+1, \s-1\fIXListDepths()\fP\s+1, \s-1\fIXListPixmapFormat\fP\s+1, \s-1\fIXQueryBestCursor()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXQueryBestStipple()\fP\s+1, \s-1\fIXQueryBestTile()\fP\s+1, \s-1\fIXReadBitmapFile()\fP\s+1, \s-1\fIXSetTile()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1, \s-1\fIXWriteBitmapFile()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCreatePixmapCursor" "Xlib \- Pixmaps and Tiles" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCreatePixmapCursor" .XX "cursors:creating;from two bitmaps" .Na XCreatePixmapCursor \(en create a cursor from two bitmaps. .Nz .SH "Synopsis" .Sy Cursor XCreatePixmapCursor\^(\^\f(CIdisplay\f(CW, \f(CIsource\f(CW\^, \f(CImask\f(CW\^, \f(CIforeground_color\f(CW\^, .br \f(CIbackground_color\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Pixmap \f(CIsource\f(CW\^; Pixmap \f(CImask\f(CW\^; XColor *\f(CIforeground_color\f(CW\^; XColor *\f(CIbackground_color\f(CW\^; unsigned int \f(CIx\f(CW\^, \f(CIy\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIsource\fP 1i Specifies the shape of the source cursor. A pixmap of depth 1. .IP \f(CImask\fP 1i Specifies the bits of the cursor that are to be displayed (the mask or stipple). A pixmap of depth 1. May be \f(CWNone\fP. .IP \f(CIforeground_color\fP 1i Specifies the red, green, and blue (RGB) values for the foreground. .IP \f(CIbackground_color\fP 1i Specifies the red, green, and blue (RGB) values for the background. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the coordinates of the cursor's hotspot relative to the source's origin. Must be a point within the source. .SH Returns The created cursor. .SH Description \f(CWXCreatePixmapCursor()\fP creates a cursor and returns a cursor ID. Foreground and background RGB values must be specified using \f(CIforeground_color\fP and \f(CIbackground_color\fP, even if the server only has a monochrome screen. The \f(CIforeground_color\fP is used for the 1 bits in the source, and the background is used for the 0 bits. Both source and mask (if specified) must have depth 1, but can have any root. The mask pixmap defines the shape of the cursor; that is, the 1 bits in the mask define which source pixels will be displayed. If no mask is given, all pixels of the source are displayed. The mask, if present, must be the same size as the source. .LP The pixmaps can be freed immediately if no further explicit references to them are to be made. .LP For more information on cursors, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fP. .Nd 6 .SH "Structures" .XX "XColor structure" .XX "structures:XColor" .Ps typedef struct { unsigned long pixel; unsigned short red, green, blue; char flags; /* DoRed, DoGreen, DoBlue */ char pad; } XColor; .Pe .SH "Errors" .IP "\f(CWBadAlloc\fP" 1i .br .IP "\f(CWBadMatch\fP" 1i Mask bitmap must be the same size as source bitmap. .br .IP "\f(CWBadPixmap\fP" 1i .LP .SH "See Also" \s-1\fIXCreateBitmapFromData()\fP\s+1, \s-1\fIXDefineCursor()\fP\s+1, \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXCreatePixmap()\fP\s+1, \s-1\fIXCreatePixmapCursor()\fP\s+1, \s-1\fIXFreeCursor()\fP\s+1, \s-1\fIXFreePixmap()\fP\s+1, \s-1\fIXQueryBestCursor()\fP\s+1, \s-1\fIXQueryBestCursor()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXReadBitmapFile()\fP\s+1, \s-1\fIXRecolorCursor()\fP\s+1, \s-1\fIXUndefineCursor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "\s-2XCreatePixmapFromBitmapData\s+2" "Xlib \- Pixmaps and Bitmaps" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCreatePixmapFromBitmapData" .XX "pixmaps:creating" .Na XCreatePixmapFromBitmapData \(en create a pixmap with depth from bitmap data. .Nz .SH "Synopsis" .Sy Pixmap XCreatePixmapFromBitmapData\^(\^\f(CIdisplay\fP, \f(CIdrawable\fP, \f(CIdata\fP, .ti +10n \f(CIwidth\fP, \f(CIheight\fP, \f(CIfg\fP, \f(CIbg\fP, \f(CIdepth\fP\^) .As Display *\f(CIdisplay\fP\^; Drawable \f(CIdrawable\fP\^; char *\f(CIdata\fP\^; unsigned int \f(CIwidth\fP, \f(CIheight\fP\^; unsigned long \f(CIfg\fP, \f(CIbg\fP\^; unsigned int \f(CIdepth\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an \f(CWDisplay\fP structure, returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies a drawable ID which indicates which screen the pixmap is to be used on. .IP \f(CIdata\fP 1i Specifies the data in bitmap format. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight\fP 1i .sp -2 Specify the width and height in pixels of the pixmap to create. .sp .IP \f(CIfg\fP 1i .br .ns .IP \f(CIbg\fP 1i .sp -2 Specify the foreground and background pixel values to use. .sp .IP \f(CIdepth\fP 1i Specifies the depth of the pixmap. Must be valid on the screen specified by \f(CIdrawable\fP. .SH Returns The created Pixmap. .SH Description \f(CWXCreatePixmapFromBitmapData()\fP creates a pixmap of the given depth using bitmap data and foreground and background pixel values. .LP The following format for the data is assigned, where the .hw X-Image variables are members of the \f(CWXImage\fP structure described in Volume One, Chapter 6, \fIDrawing Graphics and Text\fP: .LP .sp .3 .in +4.5n .ft CW .ps 9 .vs 11 .nf format=XYPixmap bit_order=LSBFirst byte_order=LSBFirst bitmap_unit=8 .Nd 10 bitmap_pad=8 xoffset=0 no extra bytes per line .ps .vs .in -4.5n .fi .ft R .sp .5 \f(CWXCreatePixmapFromBitmapData()\fP creates an image from the data and uses \f(CWXPutImage()\fP to place the data into the pixmap. For example: .in +4.5n .sp .5 .ne 10 .nf .ft CW .ps 9 .vs 11 .ta 9n #define gray_width 16 #define gray_height 16 #define gray_x_hot 8 #define gray_y_hot 8 static char gray_bits[] = { 0xf8, 0x1f, 0xe3, 0xc7, 0xcf, 0xf3, 0x9f, 0xf9, 0xbf, 0xfd, 0x33, 0xcc, 0x7f, 0xfe, 0x7f, 0xfe, 0x7e, 0x7e, 0x7f, 0xfe, 0x37, 0xec, 0xbb, 0xdd, 0x9c, 0x39, 0xcf, 0xf3, 0xe3, 0xc7, 0xf8, 0x1f}; unsigned long foreground, background; unsigned int depth; /* open display, determine colors and depth */ Pixmap \f(CWXCreatePixmapFromBitmapData\fP(display, window, gray_bits, gray_width, gray_height, foreground, background, depth); .ft R .fi .ps .vs .in -4.5n .LP If you want to use data of a different format, it is straightforward to write a routine that does this yourself, using images. .LP Pixmaps should be considered a precious resource, since many servers have limits on the amount of off-screen memory available. .LP If you are creating a pixmap for use in \f(CWXCreatePixmapCursor()\fR, specify \f(CWdepth=1\fR, \f(CWfg=1\fR, and \f(CWbg=0\fR. .SH Errors .IP "\f(CWBadAlloc\fR" .IP "\f(CWBadDrawable\fR" .IP "\f(CWBadGC\fR" .IP "\f(CWBadValue\fP" 1i \f(CIdepth\fP is not a valid depth on the screen specified by \f(CWdrawable\fP. .br .SH "See Also" \s-1\fIXCreateBitmapFromData()\fP\s+1, \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXCreatePixmap()\fP\s+1, \s-1\fIXCreatePixmapCursor()\fP\s+1, \s-1\fIXDefineCursor()\fP\s+1, \s-1\fIXFreeCursor()\fP\s+1, \s-1\fIXFreePixmap()\fP\s+1, \s-1\fIXListPixmapFormats()\fP\s+1, \s-1\fIXQueryBestCursor()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXReadBitmapFile()\fP\s+1, \s-1\fIXRecolorCursor()\fP\s+1, \s-1\fIXUndefineCursor()\fP\s+1. .\"last line comment .TH XCreatePixm.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XCreatePixmap@XCreatePixA .sp .5 XCreatePixmapCursor@XCreatePixB .sp .5 XCreatePixmapFromBitmapData@XCreatePixC .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCreateRegion" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCreateRegion" .XX "regions:creating empty" .Na XCreateRegion \(en create a new empty region. .Nz .SH "Synopsis" .Sy Region XCreateRegion\^() .SH Returns The created region. .SH Description .XX "XPolygonRegion" \f(CWXCreateRegion()\fP creates a new region of undefined size. \f(CWXPolygonRegion()\fP can be used to create a region with a defined shape and size. Many of the functions that perform operations on regions can also create regions. .LP For a description of regions, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH Structures \f(CWRegion\fP is a pointer to an opaque structure type. .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCreateSimpleWindow" "Xlib \- Window Existence" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCreateSimpleWindow" .XX "windows:creating unmapped" .Na XCreateSimpleWindow \(en create an unmapped \f(CWInputOutput\fP window. .Nz .SH "Synopsis" .Sy Window XCreateSimpleWindow(\f(CIdisplay\fP, \f(CIparent\fP, \f(CIx\fP, \f(CIy\fP, \f(CIwidth\fP, \f(CIheight\fP, \f(CIborder_width\fP, \f(CIborder\fP, \f(CIbackground\fP) .As Display *\f(CIdisplay\fP; Window \f(CIparent\fP; int \f(CIx\fP, \f(CIy\fP; unsigned int \f(CIwidth\fP, \f(CIheight\fP, \f(CIborder_width\fP; unsigned long \f(CIborder\fP; unsigned long \f(CIbackground\fP; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .92i Specifies a pointer to the \f(CIDisplay\fP structure; returned from \f(CI\f(CWXOpenDisplay()\fP. .IP \f(CIparent\fP .92i Specifies the parent window ID. Must be an \f(CIInputOutput\fP window. .IP \f(CIx\fP .92i .br .ns .IP \f(CIy\fP .92i .sp -2 Specify the x and y coordinates of the upper-left pixel of the new window's border relative to the origin of the parent (inside the parent window's border). .IP \f(CIwidth\fP .92i .br .ns .IP \f(CIheight\fP .92i .sp -2 Specify the width and height, in pixels, of the new window. These are the inside dimensions, not including the new window's borders, which are entirely outside of the window. Must be non-zero. Any part of the window that extends outside its parent window is clipped. .IP \f(CIborder_width\fP .92i Specifies the width, in pixels, of the new window's border. .IP \f(CIborder\fP .92i Specifies the pixel value for the border of the window. .IP \f(CIbackground\fP .92i Specifies the pixel value for the background of the window. .SH Returns The window. .SH Description \f(CWXCreateSimpleWindow()\fP creates an unmapped \f(CWInputOutput\fP subwindow of the specified parent window. Use \f(CWXCreateWindow()\fP if you want to set the window attributes while creating a window. (After creation, \f(CWXChangeWindowAttributes()\fP can be used.) .LP \f(CWXCreateSimpleWindow()\fP returns the ID of the created window. The new window is placed on top of the stacking order relative to its siblings. Note that the window is unmapped when it is created \- use \f(CWMapWindow\fP to display it. This function generates a \f(CWCreateNotify\fP event. .LP .ne 10 The initial conditions of the window are as follows: .IP \(bu 3n The window inherits its depth, class, and visual from its parent. All other window attributes have their default values. .IP \(bu 3n All properties have undefined values. .IP \(bu 3n The new window will not have a cursor defined; the cursor will be that of the window's parent until the cursor attribute is set with \f(CWXDefineCursor()\fP or \f(CWXChangeWindowAttributes()\fP. .IP \(bu 3n If no background or border is specified, \f(CWCopyFromParent\fP is implied. .LP For more information, see Volume One, Chapter 2, \fIX Concepts\fP, and Volume One, Chapter 3, \fIBasic Window Program\fP. .SH "Errors" .IP \f(CWBadAlloc\fP 1i .br .IP \f(CWBadMatch\fP 1i .br .IP \f(CWBadValue\fP 1i \f(CIwidth\fR or \f(CIheight\fP is zero. .IP \f(CWBadWindow\fP 1i Specified parent is an \f(CWInputOnly\fP window. .SH "See Also" \s-1\fIXCreateWindow()\fP\s+1, \s-1\fIXDestroySubwindows()\fP\s+1, \s-1\fIXDestroyWindow()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XCreateWindow" "Xlib \- Window Existence" .ds ]W Xlib Reference Manual .SH "Name" .XX "XCreateWindow" .XX "windows:creating" .Na XCreateWindow \(en create a window and set attributes. .Nz .SH "Synopsis" .Sy Window XCreateWindow\^(\^\f(CIdisplay\f(CW, \f(CIparent\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^, \f(CIborder_width\f(CW\^, \f(CIdepth\f(CW\^, \f(CIclass\f(CW\^, \f(CIvisual\f(CW\^, \f(CIvaluemask\f(CW\^, \f(CIattributes\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIparent\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; unsigned int \f(CIborder_width\f(CW\^; int \f(CIdepth\f(CW\^; unsigned int \f(CIclass\f(CW\^; Visual *\f(CIvisual\f(CW\^ unsigned long \f(CIvaluemask\f(CW\^; XSetWindowAttributes *\f(CIattributes\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIparent\fP Specifies the parent window. Parent must be \f(CWInputOutput\fP if class of window created is to be \f(CWInputOutput\fP. .IP \f(CIx\fP .br .ns .IP \f(CIy\fP .sp -2 Specify the x and y coordinates of the upper-left pixel of the new window's border relative to the origin of the parent (upper-left inside the parent's border). .IP \f(CIwidth\fP .br .ns .IP \f(CIheight\fP .sp -2 Specify the width and height, in pixels, of the window. These are the new window's inside dimensions. These dimensions do not include the new window's borders, which are entirely outside of the window. Must be non-zero, otherwise the server generates a \f(CWBadValue\fP error. .IP \f(CIborder_width\fP Specifies the width, in pixels, of the new window's border. Must be 0 for \f(CWInputOnly\fP windows, otherwise a \f(CWBadMatch\fP error is generated. .IP \f(CIdepth\fP Specifies the depth of the window, which can be different from the parent's depth. A depth of \f(CWCopyFromParent\fP means the depth is taken from the parent. Use \f(CWXListDepths()\fP if choosing an unusual depth. The specified depth paired with the \f(CIvisual\fP argument must be supported on the screen. .IP \f(CIclass\fP Specifies the new window's class. Pass one of these constants: \f(CWInputOutput\fP, \f(CWInputOnly\fP, or \f(CWCopyFromParent\fP. .IP \f(CIvisual\fP Specifies a connection to an visual structure describing the style of colormap to be used with this window. \f(CWCopyFromParent\fP is valid. .IP \f(CIvaluemask\fP Specifies which window attributes are defined in the \f(CIattributes\fP argument. If \f(CIvaluemask\fP is 0, \f(CIattributes\fP is not referenced. This mask is the bitwise OR of the valid attribute mask bits listed in the Structures section below. .IP \f(CIattributes\fP Attributes of the window to be set at creation time should be set in this structure. The \f(CIvaluemask\fP should have the appropriate bits set to indicate which attributes have been set in the structure. .SH Returns The window. .SH Description To create an unmapped subwindow for a specified parent window use \f(CWXCreateWindow()\fP or \f(CWXCreateSimpleWindow()\fP. \f(CWXCreateWindow()\fP is a more general function that allows you to set specific window attributes when you create the window. If you do not want to set specific attributes when you create a window, use \f(CWXCreateSimpleWindow()\fP, which creates a window that inherits its attributes from its parent. \f(CWXCreateSimpleWindow()\fP creates only \f(CWInputOutput\fP windows that use the default depth and visual. .LP \f(CWXCreateWindow()\fP returns the ID of the created window. \f(CWXCreateWindow()\fP causes the X server to generate a \f(CWCreateNotify\fP event. The newly created window is placed on top of its siblings in the stacking order. .LP Extension packages may define other classes of windows. .LP The visual should be \f(CWDefaultVisual()\fP or one returned by \f(CWXGetVisualInfo()\fP or \f(CWXMatchVisualInfo()\fP. The depth should be \f(CWDefaultDepth()\fP, 1, or a depth returned by \f(CWXListDepths()\fP. In current implementations of Xlib, if you specify a visual other than the one used by the parent, you must first find (using \f(CWXGetRGBColormaps()\fP) or create a colormap matching this visual and then set the colormap window attribute in the \f(CIattributes\fP and \f(CIvaluemask\fP arguments. Otherwise, you will get a \f(CWBadMatch\fP error. .LP The created window is not yet displayed (mapped) on the user's display. To display the window, call \f(CWXMapWindow\fR. The new window initially uses the same cursor as its parent. A new cursor can be defined for the new window by calling \f(CWXDefineCursor()\fR. The window will not be visible on the screen unless it and all of its ancestors are mapped and it is not obscured by any of its ancestors. .LP For more information, see Volume One, Chapter 4, \fIWindow Attributes\fR. .SH "Errors" .IP "\f(CWBadAlloc\fP" 1i .IP "\f(CWBadColor\fP" Invalid colormap in attributes. .IP "\f(CWBadCursor\fP" .Nd 12 .IP "\f(CWBadMatch\fP" Any invalid setting of a window attribute. .br Attribute besides \f(CWwin_gravity\fP, \f(CWevent_mask\fP, \f(CWdo_not_propagate_mask\fP, \f(CWoverride_redirect\fP, or \f(CWcursor\fP specified for \f(CWInputOnly\fP window. .br \f(CIdepth\fP non-zero for \f(CWInputOnly\fP. .br Parent of \f(CWInputOutput\fR is \f(CWInputOnly\fR. .br \f(CIborder_width\fP is non-zero for \f(CWInputOnly\fP, or depth or visual invalid for screen. .br \f(CIdepth\fP not supported on screen for \f(CWInputOutput\fP. .br \f(CIwidth\fP or \f(CIheight\fP is 0. .br \f(CIvisual\fP not supported on screen. .br \f(CIborder_pixel\fP not set when creating window of different depth than parent. .IP "\f(CWBadPixmap\fP" .IP "\f(CWBadValue\fP" .SH "Structures" .Ps .ta 4n 2.5i .ps 8 /* * Data structure for setting window attributes. */ typedef struct { Pixmap background_pixmap; /* background or None or ParentRelative */ unsigned long background_pixel; /* background pixel */ Pixmap border_pixmap; /* border of the window */ unsigned long border_pixel; /* border pixel value */ int bit_gravity; /* one of bit gravity values */ int win_gravity; /* one of the window gravity values */ int backing_store; /* NotUseful, WhenMapped, Always */ unsigned long backing_planes; /* planes to be preseved if possible */ unsigned long backing_pixel; /* value to use in restoring planes */ Bool save_under; /* should bits under be saved (popups) */ long event_mask; /* set of events that should be saved */ long do_not_propagate_mask; /* set of events that should not propagate */ Bool override_redirect; /* boolean value for override-redirect */ Colormap colormap; /* colormap to be associated with window */ Cursor cursor; /* cursor to be displayed (or None) */ } XSetWindowAttributes; .ne 10 /* Definitions for valuemask argument */ #define CWBackPixmap (1L<<0) #define CWBackPixel (1L<<1) #define CWBorderPixmap (1L<<2) #define CWBorderPixel (1L<<3) #define CWBitGravity (1L<<4) #define CWWinGravity (1L<<5) #define CWBackingStore (1L<<6) #define CWBackingPlanes (1L<<7) #define CWBackingPixel (1L<<8) #define CWOverrideRedirect (1L<<9) #define CWSaveUnder (1L<<10) #define CWEventMask (1L<<11) #define CWDontPropagate (1L<<12) #define CWColormap (1L<<13) #define CWCursor (1L<<14) .Pe .SH "Errors" .IP "\f(CWBadWindow\fP .SH "See Also" \s-1\fIXCreateSimpleWindow()\fP\s+1, \s-1\fIXDestroySubwindows()\fP\s+1, \s-1\fIXDestroyWindow()\fP\s+1, \s-1\fIXListDepths()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDefault" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XDefaultColormap, XDefaultColormapOfScreen, XDefaultDepth, XDefaultDepthOfScreen, XDefaultGC, XDefaultGCOfScreen, XDefaultRootWindow, XDefaultScreen, XDefaultScreenOfDisplay, XDefaultVisual, XDefaultVisualOfScreen, DefaultColormap, DefaultColormapOfScreen, DefaultDepth, DefaultDepthOfScreen, DefaultGC, DefaultGCOfScreen, DefaultRootWindow, DefaultScreen, DefaultScreenOfDisplay, DefaultVisual, DefaultVisualOfScreen \(en get information on server defaults. .XX "XDefaultColormap" .XX "XDefaultColormapOfScreen" .XX "XDefaultDepth" .XX "XDefaultDepthOfScreen" .XX "XDefaultGC" .XX "XDefaultGCOfScreen" .XX "XDefaultRootWindow" .XX "XDefaultScreen" .XX "XDefaultScreenOfDisplay" .XX "XDefaultVisual" .XX "XDefaultVisualOfScreen" .Nz .\" .\" .SH "Synopsis" .Sy Colormap XDefaultColormap\^(\^\f(CIdisplay\fP\^, \^\f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; .br int \f(CIscreen_number\fP\^; .Ae .Sy Colormap XDefaultColormapOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .Sy int XDefaultDepth\^(\^\f(CIdisplay\fP\^, \^\f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; .br int \f(CIscreen_number\fP\^; .Ae .Sy int XDefaultDepthOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .Sy GC XDefaultGC\^(\^\f(CIdisplay\fP\^, \^\f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; .br int \f(CIscreen_number\fP\^; .Ae .Sy GC XDefaultGCOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .Sy Window XDefaultRootWindow\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .Sy int XDefaultScreen\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .Sy Screen *XDefaultScreenOfDisplay\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .Sy Visual *XDefaultVisual\^(\^\f(CIdisplay\fP\^, \^\f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; .br int \f(CIscreen_number\fP\^; .Ae .Sy Visual *XDefaultVisualOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .\" .\" .Nd 10 .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number on the host server. .IP \f(CIscreen\fP 1i Specifies the appropriate \f(CWScreen\fP structure. .\" .\" .SH Description This page describes several pairs of functions such as such as \f(CWXDefaultColormap()\fP and \f(CWXDefaultColormapOfScreen()\fP. The only difference is the arguments: one takes a \f(CWDisplay\fP pointer and integer screen number, while the other takes a \f(CWScreen\fP pointer. .LP .XX "screens:numbers" \f(CWXDefaultScreen()\fP returns the default screen number referenced by the \f(CWXOpenDisplay()\fP function. .XX "screens:default" \f(CWXDefaultScreenOfDisplay()\fP return a pointer to the Screen structure of the default screen. .LP .XX "colormaps:default IDs, returning" \f(CWXDefaultColormap()\fP and \f(CWXDefaultColormapOfScreen()\fP return the default colormap ID on the specified screen. Most routine allocations of color should be made out of this colormap. .LP .XX "depth:of screen root window" \f(CWXDefaultDepth()\fP and \f(CWXDefaultDepthOfScreen()\fP return the depth (number of planes) of the root window of the specified screen. Other depths may also be supported on this screen (see \f(CWXMatchVisualInfo()\fP). .LP .XX "graphics context:returning default" \f(CWXDefaultGC()\fP and \f(CWXDefaultGCOfScreen()\fP return the default graphics context of the specified screen, which has the same depth as the root window of the screen. The GC must never be freed. .LP .XX "screens:root window, returning" .XX "screens:default visual, returning" \f(CWXDefaultRootWindow()\fP returns the root window of the default screen. .LP \f(CWXDefaultVisual()\fP and \f(CWXDefaultVisualOfScreen()\fP return the default visual of the specified screen. .LP .XX "DefaultColormap macro" .XX "DefaultColormapOfScreen macro" .XX "DefaultDepth macro" .XX "DefaultDepthOfScreen macro" .XX "DefaultGC macro" .XX "DefaultGCOfScreen macro" .XX "DefaultRootWindow macro" .XX "DefaultScreen macro" .XX "DefaultScreenOfDisplay macro" .XX "DefaultVisual macro" .XX "DefaultVisualOfScreen macro" The C language macros \f(CWDefaultColormap()\fP, \f(CWDefaultColormapOfScreen()\fP, \f(CWDefaultDepth()\fP, \f(CWDefaultDepthOfScreen()\fP, \f(CWDefaultGC()\fP, \f(CWDefaultGCOfScreen()\fP, \f(CWDefaultRootWindow()\fP, \f(CWDefaultScreen()\fP, \f(CWDefaultScreenOfDisplay()\fP, \f(CWDefaultVisual()\fP, and \f(CWDefaultVisualOfScreen()\fP are equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXOpenDisplay()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDefaultString" "Xlib \- Text Conversion" .ds ]W Xlib Reference Manual .XX "XDefaultString" .XX "text:conversion;returning default string used for" .SH Name .Na XDefaultString \(en return the default string used for text conversion. .Nz .SH Synopsis .Sy char *XDefaultString\^(\ ) .As .Ae .SH Returns The string used for unconvertible characters. .SH Availability Release 5 and later. .SH Description \f(CWXDefaultString()\fR returns the default string used by Xlib for text conversion (for example, in \f(CWXmbTextListToTextProperty()\fR). The default string is the string in the current locale which is output when an unconvertible character is found during text conversion. If the string returned by \f(CWXDefaultString()\fR is the empty string (\f(CW""\fP), no character is output in the converted text. \f(CWXDefaultString()\fR does not return \f(CWNULL\fP. .LP The string returned by \f(CWXDefaultString()\fR is independent of the default string for text drawing; see \f(CWXCreateFontSet()\fR to obtain the default string for an \f(CWXFontSet\fR. .LP The returned string is \f(CWNULL\fP-terminated. It is owned by Xlib and should not be modified or freed by the client. It may be freed after the current locale is changed. Until freed, it will not be modified by Xlib. .SH "See Also" \s-1\fIXmbTextListToTextProperty()\fP\s+1, \s-1\fIXwcTextListToTextProperty()\fP\s+1, \s-1\fIXmbTextPropertyToTextList()\fP\s+1, \s-1\fIXwcTextPropertyToTextList()\fP\s+1, \s-1\fIXwcFreeStringList()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDefineCursor" "Xlib \- Cursors" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDefineCursor" .Na XDefineCursor \(en assign a cursor to a window. .Nz .SH "Synopsis" .Sy XDefineCursor\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIcursor\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; Cursor \f(CIcursor\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window in which the cursor is to be displayed. .IP \f(CIcursor\fP 1i Specifies the cursor to be displayed when the pointer is in the specified window. Pass \f(CWNone\fP to have the parent's cursor displayed in the window, or for the root window, to have the default cursor displayed. .SH Description Sets the cursor attribute of a window, so that the specified cursor is shown whenever this window is visible and the pointer is inside. If \f(CWXDefineCursor()\fP is not called, the parent's cursor is used by default. .LP For more information on available cursors, see Appendix I, \fIThe Cursor Font\fR. .SH "Errors" \f(CWBadCursor\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXCreateGlyphCursor()\fP\s+1, \s-1\fIXCreatePixmapCursor()\fP\s+1, \s-1\fIXFreeCursor()\fP\s+1, \s-1\fIXQueryBestCursor()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXRecolorCursor()\fP\s+1, \s-1\fIXUndefineCursor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDeleteAssoc" "Xlib \- Association Tables" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDeleteAssoc" .Na XDeleteAssoc \(en delete an entry from an association table. .Nz .Nd 10 .SH "Synopsis" .Sy XDeleteAssoc\^(\^\f(CIdisplay\f(CW, \f(CItable\f(CW\^, \f(CIx_id\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XAssocTable *\f(CItable\f(CW\^; XID \f(CIx_id\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CItable\fP 1i Specifies one of the association tables created by \f(CWXCreateAssoc\%Table\fP. .IP \f(CIx_id\fP 1i Specifies the X resource ID of the association to be deleted. .SH Description This function is provided for compatibility with X Version 10. To use it you must include the file .I and link with the library \fI-loldX\fP. .LP \f(CWXDeleteAssoc()\fP deletes an association in an \f(CWXAssocTable\fP keyed on its \f(CWXID\fP. Redundant deletes (and deletes of nonexistent \f(CWXID\fP's) are meaningless and cause no problems. Deleting associations in no way impairs the performance of an \f(CWXAssocTable\fP. .LP For more information on association tables, see Volume One, Appendix B, \fIX10 Compatibility\fP. .SH "Structures" .Ps typedef struct { XAssoc *buckets; /* pointer to first bucket in array */ int size; /* table size (number of buckets) */ } XAssocTable; .Pe .SH "See Also" \s-1\fIXCreateAssocTable()\fP\s+1, \s-1\fIXDestroyAssocTable()\fP\s+1, \s-1\fIXLookUpAssoc()\fP\s+1, \s-1\fIXMakeAssoc()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDeleteContext" "Xlib \- Context Manager" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XDeleteContext" XDeleteContext \(en delete a context entry for a given window and type. .Nz .SH "Synopsis" .Sy int XDeleteContext(\^\f(CIdisplay\f(CW, \f(CIrid\f(CW, \f(CIcontext\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XID \f(CIrid\f(CW; XContext \f(CIcontext\f(CW; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIrid\fP 1i Specifies the resource ID with which the data is associated. .IP \f(CIcontext\fP 1i Specifies the context type to which the data belongs. .SH Returns \f(CWXCNOENT\fP if the context could not be found, or zero if it succeeds. .SH Description \f(CWXDeleteContext()\fP deletes the entry for the given resource ID and type from the context data structure defined in <\fIX11/Xutil.h\fR>. This function returns \f(CWXCNOENT\fP if the context could not be found, or zero if it succeeds. \f(CWXDeleteContext()\fP does not free the memory allocated for the data whose address was saved. .LP See Volume One, Chapter 15, \fIOther Programming Techniques\fR, for a description of context management. .SH "Structures" .Ps typedef int XContext; .Pe .SH "See Also" \s-1\fIXFindContext()\fP\s+1, \s-1\fIXSaveContext()\fP\s+1, \s-1\fIXUniqueContext()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDeleteModifiermapEntry" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDeleteModifiermapEntry" .Na XDeleteModifiermapEntry \(en delete an entry from an \f(CWXModifierKeymap\fR structure. .Nz .SH "Synopsis" .Sy XModifierKeymap *XDeleteModifiermapEntry\^(\^\f(CImodmap\fP, .ti +10n \f(CIkeycode_entry\fP, \f(CImodifier\fP\^) .As XModifierKeymap *\f(CImodmap\fP\^; KeyCode \f(CIkeycode_entry\fP\^; int \f(CImodifier\fP\^; .Ae .SH "Arguments" .IP \f(CImodmap\fP 1i Specifies a pointer to an \f(CWXModifierKeymap()\fP structure. .IP \f(CIkeycode_entry\fP 1i Specifies the keycode of the key to be deleted from \f(CImodmap\fP. .IP \f(CImodifier\fP 1i Specifies the modifier you no longer want mapped to the keycode specified in \f(CIkeycode_entry\fP. This should be one of the constants: \f(CWShiftMapIndex\fP, \f(CWLockMapIndex\fP, \f(CWControlMapIndex\fP, \f(CWMod1MapIndex\fR, \f(CWMod2MapIndex\fR, \f(CWMod3MapIndex\fR, \f(CWMod4MapIndex\fR, or \f(CWMod5MapIndex\fR. .SH Returns The modified structure. .SH Description \f(CWXDeleteModifiermapEntry()\fP returns an \f(CWXModifierKeymap()\fP structure suitable for calling \f(CWXSetModifierMapping()\fR, in which the specified keycode is deleted from the set of keycodes that is mapped to the specified modifier (like Shift or Control). \f(CWXDeleteModifiermapEntry()\fP itself does not change the mapping. .LP This function is normally used by calling \f(CWXGetModifierMapping()\fP to get a pointer to the current \f(CWXModifierKeymap()\fP structure for use as the \f(CImodmap\fR argument to \f(CWXDeleteModifiermapEntry()\fR. .LP For a description of the modifier map, see \f(CWXSetModifierMapping()\fP. .SH "Structures" .Ps typedef struct { int max_keypermod; /* server's max number of keys per modifier */ KeyCode *modifiermap; /* an 8 by \f(CImax_keypermod\fP array of * keycodes to be used as modifiers */ } XModifierKeymap; #define ShiftMapIndex 0 #define LockMapIndex 1 #define ControlMapIndex 2 #define Mod1MapIndex 3 #define Mod2MapIndex 4 #define Mod3MapIndex 5 #define Mod4MapIndex 6 #define Mod5MapIndex 7 .Pe .SH "See Also" \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifiermap()\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeySym\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1, \s-1\fIXInsertModifiermapEntry\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDeleteProperty" "Xlib \- Properties" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDeleteProperty" .Na XDeleteProperty \(en delete a window property. .Nz .SH "Synopsis" .Sy XDeleteProperty\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIproperty\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; Atom \f(CIproperty\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window whose property you want to delete. .IP \f(CIproperty\fP 1i Specifies the atom of the property to be deleted. .SH Description \f(CWXDeleteProperty()\fP deletes a window property, so that it no longer contains any data. Its atom, specified by \f(CIproperty\fP, still exists after the call so that it can be used again later by any application to set the property once again. If the property was defined on the specified window, \f(CWXDeleteProperty()\fP generates a \f(CWPropertyNotify\fP event. .LP See the introduction to properties in Volume One, Chapter 2, \fIX Concepts\fR, or more detailed information in Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Errors" \f(CWBadAtom\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXChangeProperty()\fP\s+1, \s-1\fIXGetAtomName()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXGetWindowProperty()\fP\s+1, \s-1\fIXInternAtom()\fP\s+1, \s-1\fIXListProperties()\fP\s+1, \s-1\fIXRotateWindowProperties()\fP\s+1, \s-1\fIXSetStandardProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDestroyAssocTable" "Xlib \- Association Tables" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDestroyAssocTable" .Na XDestroyAssocTable \(en free the memory allocated for an association table. .Nz .SH "Synopsis" .Sy XDestroyAssocTable\^(\^\f(CItable\f(CW\^) .As XAssocTable *\f(CItable\f(CW\^; .Ae .SH "Arguments" .IP \f(CItable\fP 1i Specifies the association table whose memory is to be freed. .SH Description This function is provided for compatibility with X Version 10. To use it you must include the file .I and link with the library \fI-loldX\fP. .LP Using an \f(CWXAssocTable\fP after it has been destroyed will have unpredictable consequences. .LP For more information on association tables, see Volume One, Appendix B, \fIX10 Compatibility\fP. .SH "Structures" .Ps typedef struct { XAssoc *buckets; /* pointer to first bucket in array */ int size; /* table size (number of buckets) */ } XAssocTable; .Pe .SH "See Also" \s-1\fIXCreateAssocTable()\fP\s+1, \s-1\fIXDeleteAssoc()\fP\s+1, \s-1\fIXLookUpAssoc()\fP\s+1, \s-1\fIXMakeAssoc()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDestroyIC" "Xlib \- Input Contexts" .ds ]W Xlib Reference Manual .XX "XDestroyIC" .XX "input contexts:destroying" .SH Name .Na XDestroyIC \(en destroy an input context. .Nz .SH Synopsis .Sy void XDestroyIC\^(\^\f(CIic\fP\^) .As XIC \f(CIic\fP\^; .Ae .SH Arguments .IP \f(CIic\fP 1i Specifies the input context. .SH Availability Release 5 and later. .SH Description \f(CWXDestroyIC()\fR destroys the specified input context. Once destroyed, the input context should no longer be used. .SH "See Also" \s-1\fIXSetICFocus()\fP\s+1, \s-1\fIXSetICValues()\fP\s+1, \s-1\fIXCreateIC()\fP\s+1, \s-1\fIXIMOfIC()\fP\s+1, \s-1\fIXmbResetIC()\fP\s+1, \s-1\fIXwcResetIC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDestroyImage" "Xlib \- Images" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XDestroyImage" XDestroyImage \(en deallocate memory associated with an image. .Nz .SH "Synopsis" .Sy XDestroyImage\^(\^\f(CIximage\f(CW\^) .As XImage *\^\f(CIximage\f(CW\^; .Ae .SH "Arguments" .IP \f(CIximage\fP 1i Specifies a pointer to the image. .SH Description \f(CWXDestroyImage()\fP deallocates the memory associated with an \f(CWXImage\fP structure. This memory includes both the memory holding the \f(CWXImage\fP structure, and the memory holding the actual image data. (If the image data is statically allocated, .hw XImage the pointer to the data in the \f(CWXImage\fP structure must be set to zero before calling \f(CWXDestroyImage()\fP.) .LP For more information on images, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "See Also" \s-1\fIXImageByteOrder()\fP\s+1, \s-1\fIXAddPixel()\fP\s+1, \s-1\fIXCreateImage()\fP\s+1, \s-1\fIXGetImage()\fP\s+1, \s-1\fIXGetPixel()\fP\s+1, \s-1\fIXGetSubImage()\fP\s+1, \s-1\fIXPutImage()\fP\s+1, \s-1\fIXPutPixel()\fP\s+1, \s-1\fIXSubImage()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDestroyRegion" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDestroyRegion" .Na XDestroyRegion \(en deallocate memory associated with a region. .Nz .SH "Synopsis" .Sy XDestroyRegion\^(\^\f(CIr\f(CW\^) .As Region \f(CIr\f(CW\^; .Ae .SH "Arguments" .IP \f(CIr\fP 1i Specifies the region to be destroyed. .SH Description \f(CWXDestroyRegion()\fP frees the memory associated with a region and invalidates pointer \f(CIr\fP. .LP See Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, for a description of regions. .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXCreateRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDestroySubwindows" "Xlib \- Window Existence" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDestroySubwindows" .Na XDestroySubwindows \(en destroy all subwindows of a window. .Nz .SH "Synopsis" .Sy XDestroySubwindows\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\f(CW 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\f(CW 1i Specifies the ID of the window whose subwindows are to be destroyed. .SH Description This function destroys all descendants of the specified window (recursively), in bottom to top stacking order. .LP \f(CWXDestroySubwindows()\fP generates exposure events on window \f(CIw\fP, if any mapped subwindows were actually destroyed. This is much more efficient than deleting many subwindows one at a time, since much of the work need only be performed once for all of the windows rather than for each window. It also saves multiple exposure events on the windows about to be destroyed. The subwindows should never again be referenced. The X server generates a \f(CWDestroyNotify\fR event for each window destroyed. .LP \f(CWXCloseDisplay()\fP automatically destroys all windows that have been created by that client on the specified display (unless called after a \f(CWfork\fP system call). .LP Never call \f(CWXDestroySubwindows()\fP with the window argument set to the root window! This will destroy all the applications on the screen, and if there is only one screen, often the server as well. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXCreateSimpleWindow()\fP\s+1, \s-1\fIXCreateWindow()\fP\s+1, \s-1\fIXDestroyWindow()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDestroyWindow" "Xlib \- Window Existence" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDestroyWindow" .Na XDestroyWindow \(en unmap and destroy a window and all subwindows. .Nz .SH "Synopsis" .Sy XDestroyWindow\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window to be destroyed. .SH Description If \f(CIw\fP is mapped, an \f(CWUnmapWindow\fP request is performed automatically. The window and all inferiors (recursively) are then destroyed, and a \f(CWDestroyNotify\fP event is generated for each window. The ordering of the \f(CWDestroyNotify\fP events is such that for any given window, \f(CWDestroyNotify\fP is generated on all inferiors of the window before being generated on the window itself. The ordering among siblings and across subhierarchies is not otherwise constrained. .LP The windows should never again be referenced. .LP Destroying a mapped window will generate exposure events on other windows that were obscured by the windows being destroyed. \f(CWXDestroyWindow()\fP may also generate \f(CWEnterNotify\fP events if \f(CIw\fP was mapped and contained the pointer. .LP No windows are destroyed if you try to destroy the root window. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXCreateSimpleWindow()\fP\s+1, \s-1\fIXCreateWindow()\fP\s+1, \s-1\fIXDestroySubwindows()\fP\s+1. .\"last line comment .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XDevBell.man,v 1.6 94/06/04 17:32:23 rws Exp $ .ds xL Programming With Xlib .TH XDeviceBell 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XDeviceBell \- ring a bell on a device supported through the input extension .SH SYNTAX Status XDeviceBell\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fIfeedbackclass\fP\^, \fIfeedbackid\fP\^, \fIpercent\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br XID *\fIfeedbackclass\fP\^; .br XID *\fIfeedbackid\fP\^; .br int *\fIpercent\fP\^; .br .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device with which the bell is associated. .TP 12 .I feedbackclass Specifies the class of the feedback with which the bell is associated. .TP 12 .I feedbackid Specifies the id of the feedback with which the bell is associated. .TP 12 .I percent Specifies the volume in the range -100 to 100 at which the bell should be rung. .SH DESCRIPTION The \fIXDeviceBell\fP request causes the server to ring a bell on the specified feedback of the specified device, if possible. The specified volume is relative to the base volume for the bell. If an invalid device is specified, a \fIBadDevice\fP error will be returned. The feedbackclass and feedbackid parameters contain values returned by an \fIXGetFeedbackControl\fP request and uniquely identify the bell to ring. If a feedbackclass is specified that does not support a bell, or if a nonexistent feedbackid is specified, or a percent value is specified that is not in the range -100 to 100, a \fIBadValue\fP error will be returned. .LP The volume at which the bell is rung when the percent argument is nonnegative is: .IP base \- [(base * percent) / 100] + percent .LP The volume at which the bell rings when the percent argument is negative is: .IP base + [(base * percent) / 100] .LP To change the base volume of the bell, use \fIXChangeFeedbackControl\fP. .LP \fIXDeviceBell\fP can generate a \fIBadDevice\fP or a \fIBadValue\fP error. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist, or has not been opened by this client via \fIXOpenInputDevice\fP. .TP 12 \fIBadValue\fP An invalid feedbackclass, feedbackid, or percent value was specified. .SH "SEE ALSO" XChangeFeedbackControl(3X), XBell(3X) .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDisableAccessControl" "Xlib \- Host Access" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDisableAccessControl" .Na XDisableAccessControl \(en allow access from any host. .Nz .SH "Synopsis" .Sy XDisableAccessControl\^(\^\f(CIdisplay\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Description \f(CWXDisableAccessControl()\fP instructs the server to allow access from clients on any host. This disables use of the host access list. .LP This routine can only be called from a client running on the same host as the server. .LP For more information on access control, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "Errors" \f(CWBadAccess\fP .SH "See Also" \s-1\fIXAddHost()\fP\s+1, \s-1\fIXAddHosts()\fP\s+1, \s-1\fIXEnableAccessControl()\fP\s+1, \s-1\fIXListHosts()\fP\s+1, \s-1\fIXRemoveHost()\fP\s+1, \s-1\fIXRemoveHosts()\fP\s+1, \s-1\fIXSetAccessControl()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDisplayCells" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XDisplayCells, DisplayCells \(en query number of cells in default colormap of screen. .XX "XDisplayCells" .XX "colormaps:default" .Nz .\" .\" .SH "Synopsis" .Sy int XDisplayCells\^(\^\f(CIdisplay\fP\^, \^\f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; .br int \f(CIscreen_number\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number on the host server. .\" .\" .SH Returns The number of colorcells in a colormap. .SH Description \f(CWXDisplayCells()\fP returns the number of entries in the default colormap of the specified screen. .LP .XX "DisplayCells macro" The C language macro \f(CWDisplayCells()\fP is equivalent and slightly more efficient. .LP This function is misnamed; it should really be XScreenCells(). .\" .\" .SH "See Also" \s-1\fIXDisplayPlanes()\fP\s+1, \s-1\fIXDefaultColormap*()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDisplayHeight*" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XDisplayHeight, XDisplayHeightMM, DisplayHeight, DisplayHeightMM \(en query height of screen in pixels or millimeters. .XX "XDisplayHeight" .Nz .\" .\" .SH "Synopsis" .Sy int XDisplayHeight\^(\^\f(CIdisplay\fP\^, \^\f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; int \f(CIscreen_number\fP\^; .Ae .Sy int XDisplayHeightMM\^(\^\f(CIdisplay\fP\^, \^\f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; int \f(CIscreen_number\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number on the server. .\" .\" .SH Returns The height in pixels or millimeters. .SH Description .XX "screens:height" \f(CWXDisplayHeight*()\fP returns an integer that describes the height of the screen in pixels. \f(CWXDisplayHeightMM()\fP returns the height of the specified screen in millimeters. .LP .XX "DisplayHeight macro" .XX "DisplayHeightMM macro" The C language macros \f(CWDisplayHeight()\fP and \f(CWDisplayHeightMM()\fP are equivalent and slightly more efficient. .LP These functions are misnamed; they should really be \f(CWXScreenHeight()\fR and \f(CWXScreenHeightMM()\fR. .\" .\" .SH "See Also" \s-1\fIXDisplayWidth*()\fP\s+1, \s-1\fIXDisplayWidthMM()\fP\s+1, \s-1\fIXGetWindowAttributes()\fP\s+1, \s-1\fIXGetGeometry()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDisplayKeycodes" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XDisplayKeycodes" .Na XDisplayKeycodes \(en obtain the range of legal keycodes for a server. .Nz .SH "Synopsis" .Sy XDisplayKeycodes\^(\^\f(CIdisplay\fP\^, \f(CImin_keycodes_return\fP\^, \ \f(CImax_keycodes_return\fP\^) .As Display *\f(CIdisplay\fP\^; int *\f(CImin_keycodes_return\fP\^, *\f(CImax_keycodes_return\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.2i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CImin_keycodes_return\fP 1.2i Returns the minimum keycode. .IP \f(CImax_keycodes_return\fP 1.2i Returns the maximum keycode. .SH Description .LP \f(CWXDisplayKeycodes()\fR returns the \f(CImin_keycodes_return\fP and \f(CImax_keycodes_\p return\fP supported by the specified server. The minimum keycode returned is never less than 8, and the maximum keycode returned is never greater than 255. Not all keycodes in this range are required to have corresponding keys. .LP For more information, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fP. .SH "See Also" \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXLookupString()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDisplayMotionBufferSize" "Xlib \- Event Handling" .ds ]W Xlib Reference Manual .SH "Name" .Na XDisplayMotionBufferSize \(en get motion history buffer size. .XX "XDisplayMotionBufferSize" .Nz .\" .\" .SH "Synopsis" .Sy unsigned long XDisplayMotionBufferSize\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Returns The size in events of the buffer. .SH Description .XX "motion history buffer:querying" \f(CWXDisplayMotionBufferSize()\fP queries the approximate maximum number of elements in the motion history buffer. .LP The X server may, but is not required to, retain the recent history of the pointer motion in a motion history buffer. If there is no motion history buffer, \f(CWXDisplayMotionBufferSize()\fP returns zero. .LP Motion history buffers were implemented for the first time in MIT's sample servers in Release 5, but some earlier releases of commercial servers may provide support. .LP An application gains access to the motion history buffer with \f(CWXGetMotionEvents()\fP. This buffer may contain a finer granularity of events than is reported by \f(CWMotionNotify\fP events. .LP There is no such macro as \f(CWDisplayMotionBufferSize()\fR. .\" .SH "See Also" \s-1\fIXGetMotionEvents()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDisplayName" "Xlib \- Error Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDisplayName" .Na XDisplayName \(en report the display name (when connection to a display fails). .Nz .SH "Synopsis" .Sy char *XDisplayName\^(\^\f(CIstring\f(CW\^) .As char *\f(CIstring\f(CW\^; .Ae .SH "Arguments" .IP \f(CIstring\fP 1i Specifies the character string. .SH Returns The display name string. .SH Description \f(CWXDisplayName()\fP is normally used to report the name of the display the program attempted to open with \f(CWXOpenDisplay()\fP. This is necessary because X error handling begins only after the connection to the server succeeds. .LP If a \f(CWNULL\fP string is specified, \f(CWXDisplayName()\fP looks in the DISPLAY environment variable and returns the display name that the user was requesting. Otherwise, \f(CWXDisplayName()\fP returns its own argument. .LP For more information, see Volume One, Chapter 3, \fIBasic Window Program\fR. .SH "See Also" \s-1\fIXGetErrorDatabaseText()\fP\s+1, \s-1\fIXGetErrorText()\fP\s+1, \s-1\fIXSetAfterFunction()\fP\s+1, \s-1\fIXSetErrorHandler()\fP\s+1, \s-1\fIXSetIOErrorHandler()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDisplayOfIM" "Xlib \- Input Methods" .ds ]W Xlib Reference Manual .XX "XDisplayOfIM" .XX "input methods:display of" .SH Name .Na XDisplayOfIM \(en get the display of an input method. .Nz .SH Synopsis .Sy Display *XDisplayOfIM\^(\^\f(CIim\fP\^) .As XIM \f(CIim\fP\^; .Ae .SH Arguments .IP \f(CIim\fP 1i Specifies the input method. .SH Returns The display structure. .SH Availability Release 5 and later. .SH Description \f(CWXDisplayOfIM()\fR returns the display associated with the specified input method. .SH "See Also" \s-1\fIXOpenIM()\fP\s+1, \s-1\fIXCloseIM()\fP\s+1, \s-1\fIXGetIMValues()\fP\s+1, \s-1\fIXLocaleOfIM()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDisplayOfScreen" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XDisplayOfScreen, DisplayOfScreen \(en get Display structure of specified Screen structure. .XX "XDisplayOfScreen" .Nz .\" .\" .SH "Synopsis" .Sy Display *XDisplayOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIscreen\fP 1i Specifies the appropriate \f(CWScreen\fP structure. .\" .\" .SH Returns The display structure. .SH Description .XX "screens:display, returning" \f(CWXDisplayOfScreen()\fP returns the display of the specified screen. .LP .XX "DisplayOfScreen macro" The C language macro \f(CWDisplayOfScreen()\fP is equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXScreenNumberOfScreen()\fP\s+1, \s-1\fIXScreenOfDisplay()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDisplayPlanes" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XDisplayPlanes, DisplayPlanes \(en get number of planes of specified screen. .XX "XDisplayPlanes" .Nz .\" .\" .SH "Synopsis" .Sy int XDisplayPlanes\^(\^\f(CIdisplay\fP\^, \^\f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; .br int \f(CIscreen_number\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number on the host server. .\" .\" .SH Returns The number of planes. .SH Description .XX "depth:of screen" .XX "planes:displaying \f(CWXDisplayPlanes()\fP returns the depth (number of planes or number of bits per pixel) of the root window of the specified screen. .LP .XX "DisplayPlanes macro" The C language macro \f(CWDisplayPlanes()\fP is equivalent and slightly more efficient. .LP This function is misnamed; it should really be \f(CWXScreenPlanes()\fR. .\" .\" .SH "See Also" \s-1\fIXDefaultDepth*()\fP\s+1, \s-1\fIXDefaultDepthOfScreen()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDisplayString" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XDisplayString, DisplayString \(en get string passed to \f(CWXOpenDisplay()\fP. .XX "XDisplayString" .Nz .\" .\" .SH "Synopsis" .Sy char *XDisplayString\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Returns The display name string. .SH Description .XX "strings:passed, returning" .XX "XOpenDisplay:returning strings passed to" \f(CWXDisplayString()\fP returns the string that was passed to \f(CWXOpenDisplay()\fP when the current display was opened. On POSIX-conformant systems, if the passed string was \f(CWNULL\fP, it returns the value of the DISPLAY environment variable when the current display was opened. .LP .IN "POSIX System Call" "fork" \f(CWXDisplayString()\fP is useful for printing error messages when \f(CWXOpenDisplay()\fP fails, and for applications that invoke the \f(CIfork\fR system call and want to open a new connection to the same display from the child process. .LP .XX "DisplayString macro" The C language macro \f(CWDisplayString()\fP is equivalent and slightly more efficient. \f(CWXDisplayName()\fP is also a similar function. .\" .\" .SH "See Also" \s-1\fIXOpenDisplay()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDisplayWidth*" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XDisplayWidth, XDisplayWidthMM, DisplayWidth, DisplayWidthMM \(en query width of screen in pixels or millimeters. .XX "XDisplayWidth" .XX "XDisplayWidthMM" .Nz .\" .\" .SH "Synopsis" .Sy int XDisplayWidthMM\^(\^\f(CIdisplay\fP\^, \^\f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; int \f(CIscreen_number\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number on the server. .\" .\" .SH Returns The width in pixels or millimeters. .SH Description .XX "screens:width" \f(CWXDisplayWidth*()\fP returns an integer that describes the width of the screen in pixels. \f(CWXDisplayWidthMM()\fP returns the width of the specified screen in millimeters. .LP The C language macros \f(CWDisplayWidth()\fP and \f(CWDisplayWidthMM()\fP are equivalent and slightly more efficient. .LP These functions are misnamed; they should really be \f(CWXScreenWidth()\fP and \f(CWXScreenWidthMM()\fP. .\" .\" .SH "See Also" \s-1\fIXDisplayHeight*()\fP\s+1, \s-1\fIXDisplayHeightMM()\fP\s+1, \s-1\fIXGetWindowAttributes()\fP\s+1, \s-1\fIXGetGeometry()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDoes*" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XDoesBackingStore, XDoesSaveUnders, DoesBackingStore, DoesSaveUnders \(en query server support for backing store or save unders. .XX "XDoesBackingStore" .XX "XDoesSaveUnders" .Nz .\" .\" .SH "Synopsis" .Sy int XDoesBackingStore\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .Sy Bool XDoesSaveUnders\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIscreen\fP 1i Specifies the appropriate \f(CWScreen\fP structure. .\" .\" .SH Returns \f(CWXDoesSaveUnders()\fP returns \f(CWTrue\fP or \f(CWFalse\fP. \f(CWXDoesBackingStore()\fP returns \f(CWWhenMapped\fP, \f(CWNotUseful\fP, or \f(CWAlways\fP. .SH Description .XX "save unders" \f(CWXDoesSaveUnders()\fP returns a boolean value indicating whether the screen supports save unders. If \f(CWTrue\fP, the screen supports save unders. If \f(CWFalse\fP, the screen does not support save unders. .LP .XX "backing store" \f(CWXDoesBackingStore()\fP returns a value indicating whether the screen supports backing stores. The value returned can be one of \f(CWWhenMapped\fP, \f(CWNotUseful\fP, or \f(CWAlways\fP. .LP Save unders and backing stores are optional server features controlled with window attributes. These macros tell you whether the server supports them. A "save under" is an area beneath a window (usually a menu or dialog box) that the server saves, so that when the window is removed from the screen, the underlying applications do not need to redraw their windows. This speeds up user response with a slight cost in increased server memory consumption. A "backing store" is an off-screen copy of a window, maintained even when the window is not visible or not mapped. The server uses the copy to redraw the window whenever that window would otherwise have received an \f(CWExpose\fP event. This reduces the load on applications at the expense of a possibly great increase in server memory usage. .LP .XX "DoesSaveUnders macro" .XX "DoesBackingStore macro" The C language macros \f(CWDoesSaveUnders()\fP and \f(CWDoesBackingStore()\fP are equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXChangeWindowAttributes()\fP\s+1, \s-1\fIXGetWindowAttributes()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDraw" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDraw" .Na XDraw \(en draw a polyline or curve between vertex list (from \f(CWX10)\fP. .Nz .SH "Synopsis" .Sy Status XDraw(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW, \f(CIgc\f(CW, \f(CIvlist\f(CW, \f(CIvcount\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; Vertex *\f(CIvlist\f(CW\^; int \f(CIvcount\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIvlist\fP 1i Specifies a pointer to the list of vertices that indicates what to draw. .IP \f(CIvcount\fP 1i Specifies how many vertices are in \f(CIvlist\fP. .SH Returns Zero on failure, non-zero on success. .SH Description This function is provided for compatibility with X Version 10. To use it you must include the file .I and link with the library \fI-loldX\fP. Its performance is likely to be low. .LP \f(CWXDraw\fP draws an arbitrary polygon or curve. The figure drawn is defined by the specified list of vertices (\f(CIvlist\fP). The points are connected by lines as specified in the flags member of each of the \f(CWVertex\fP structures. .LP The \f(CWVertex\fP structure contains an \f(CWx\fP,\f(CWy\fP coordinate and a bitmask called \f(CWflags\fP that specifies the drawing parameters. .LP The x and y elements of \f(CWVertex\fP are the coordinates of the vertex that are relative to either the previous vertex (if \f(CWVertexRelative\fP is 1) or the upper-left inside corner of the drawable (if \f(CWVertexRelative\fP is 0). If \f(CWVertexRelative\fP is 0 the coordinates are said to be absolute. The first vertex must be an absolute vertex. .LP If the \f(CWVertexDontDraw\fP bit is 1, no line or curve is drawn from the previous vertex to this one. This is analogous to picking up the pen and moving to another place before drawing another line. .LP If the \f(CWVertexCurved\fP bit is 1, a spline algorithm is used to draw a smooth curve from the previous vertex, through this one, to the next vertex. Otherwise, a straight line is drawn from the previous vertex to this one. It makes sense to set \f(CWVertexCurved\fP to 1 only if a .ne 6 previous and next vertex are both defined (either explicitly in the array, or through the definition of a closed curve \- see below). .LP It is permissible for \f(CWVertexDontDraw\fP bits and \f(CWVertexCurved\fP bits to both be 1. This is useful if you want to define the previous point for the smooth curve, but you do not want an actual curve drawing to start until this point. .LP If \f(CWVertexStartClosed\fP bit is 1, then this point marks the beginning of a closed curve. This vertex must be followed later in the array by another vertex whose absolute coordinates are identical and which has \f(CWVertexEndClosed\fP bit of 1. The points in between form a cycle for the purpose of determining predecessor and successor vertices for the spline algorithm. .LP \f(CWXDraw\fP achieves the effects of the X10 \f(CWXDraw\fP, \f(CWXDrawDashed\fP, and \f(CWXDrawPatterned\fP functions. .LP \f(CWXDraw\fP uses the following graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWline_width\fP, \f(CWline_style\fP, \f(CWcap_style\fP, \f(CWjoin_style\fP, \f(CWfill_style\fP, \f(CWsubwindow_ mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. This function also uses these graphics context mode-dependent components: \f(CWforeground\fP, \f(CWbackground\fP, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, \f(CWts_y_origin\fP, \f(CWdash_offset\fP, and \f(CWdashes\fP. .LP A \f(CWStatus\fP of zero is returned on failure, and non-zero on success. .LP For more information, see Volume One, Appendix B, \fIX10 Compatibility\fR. .SH "Structures" .Ps typedef struct _Vertex { short x,y; unsigned short flags; } Vertex; /* defined constants for use as \f(CIflags\fP */ #define VertexRelative 0x0001 /* else absolute */ #define VertexDontDraw 0x0002 /* else draw */ #define VertexCurved 0x0004 /* else straight */ #define VertexStartClosed 0x0008 /* else not */ #define VertexEndClosed 0x0010 /* else not */ .Pe .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH XDrawArc "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDrawArc" .Na XDrawArc \(en draw an arc fitting inside a rectangle. .Nz .SH "Synopsis" .Sy XDrawArc\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^, .ti +10n \f(CIangle1\f(CW\^, \f(CIangle2\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; int \f(CIangle1\f(CW\^, \f(CIangle2\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the upper-left corner of the rectangle that contains the arc, relative to the origin of the specified drawable. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight\fP 1i .sp -2 Specify the width and height in pixels of the major and minor axes of the arc. .sp .IP \f(CIangle1\fP 1i Specifies the start of the arc relative to the three-o'clock position from the center. Angles are specified in 64ths of a degree (360 * 64 is a complete circle). .IP \f(CIangle2\fP 1i Specifies the end of the arc relative to the start of the arc. Angles are specified in 64ths of a degree (360 * 64 is a complete circle). .SH Description \f(CWXDrawArc()\fP draws a circular or elliptical arc. An arc is specified by a rectangle and two angles. The \f(CIx\fP and \f(CIy\fP coordinates are relative to the origin of the drawable, and define the upper-left corner of the rectangle. The center of the circle or ellipse is the center of the rectangle, and the major and minor axes are specified by the \f(CWwidth\fP and \f(CWheight\fP, respectively. The angles are signed integers in 64ths of a degree, with positive values indicating counterclockwise motion and negative values indicating clockwise motion, truncated to a maximum of 360 degrees. The start of the arc is specified by \f(CIangle1\fP relative to the three-o'clock position from the center, and the path and extent of the arc is specified by \f(CIangle2\fP relative to the start of the arc. .LP By specifying one axis to be zero, a horizontal or vertical line is drawn (inefficiently). .LP Angles are computed based solely on the coordinate system and ignore the aspect ratio. In other words, if the bounding rectangle of the arc is not square and \f(CIangle1\fP is zero and \f(CIangle2\fP is (\f(CW45x64\fP), a point drawn from the center of the bounding box .ne 2 through the endpoint of the arc will pass through the corner of the rectangle. .LP For any given arc, no pixel is drawn more than once, even if \f(CIangle2\fP is greater than \f(CIangle1\fP by more than 360 degrees. See \f(CWXDrawArcs()\fR for a detailed description of the pixels drawn by \f(CWXDrawArc()\fP. .LP \f(CWXDrawArc()\fP uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWline_width\fP, \f(CWline_style\fP, \f(CWcap_style\fP, \f(CWjoin_style\fP, \f(CWfill_style\fP, \f(CWsubwindow_\fP \f(CWmode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. This function also uses these graphics context mode-dependent components: \f(CWforeground\fP, \f(CWbackground\fP, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, \f(CWts_y_origin\fP, \f(CWdash_offset\fP, and \f(CWdashes\fP. .\".ta 4.5n 2.75i .\".nf .\".ft CW .\".fi .ft R .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .Fs .Pf amp3.eps "" "" "" "" noscale .Fe "Angle and dimension measurements for drawing arcs" .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .Nd 5 .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH XDrawArcs "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDrawArcs" .Na XDrawArcs \(en draw multiple arcs. .Nz .SH "Synopsis" .Sy XDrawArcs\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIarcs\f(CW\^, \f(CInarcs\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; XArc *\f(CIarcs\f(CW\^; int \f(CInarcs\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIarcs\fP 1i Specifies a pointer to an array of arcs. .IP \f(CInarcs\fP 1i Specifies the number of arcs in the array. .SH Description This is the plural version of \f(CWXDrawArc()\fP. See \f(CWXDrawArc()\fP for details of drawing a single arc. .LP There is a limit to the number of arcs that can be drawn in a single call. It varies according to the server. To determine how many arcs you can draw in a single call, find out your server's maximum request size using \f(CWXMaxRequestSize()\fP. Subtract three and divide by three: this is the maximum number of arcs you can draw in a single \f(CWXDrawArcs()\fP call. .LP The arcs are drawn in the order listed in the \f(CIarcs\fP array. .LP By specifying one axis to be zero, a horizontal or vertical line can be drawn. Angles are computed based solely on the coordinate system, ignoring the aspect ratio. .LP For any given arc, no pixel is drawn more than once. If the last point in one arc coincides with the first point in the following arc, the two arcs will join correctly. If the first point in the first arc coincides with the last point in the last arc, the two arcs will join correctly. If two arcs join correctly and if \f(CWline_width\fP is greater than 0 and the arcs intersect, no pixel is drawn more than once. Otherwise, the intersecting pixels of intersecting arcs are drawn multiple times. Specifying an arc with one endpoint and a clockwise extent draws the same pixels as specifying the other endpoint and an equivalent counterclockwise extent, except as it affects joins. .LP \f(CWXDrawArcs()\fP uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWline_width\fP, \f(CWline_style\fP, \f(CWcap_style\fP, \f(CWjoin_style\fP, \f(CWfill_style\fP, \f(CWsubwindow_\fP \f(CWmode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. This function also uses these graphics context mode-dependent components: \f(CWforeground\fP, \f(CWbackground\fP, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, \f(CWts_y_origin\fP, \f(CWdash_offset\fP, and \f(CWdashes\fP. .LP .br .sp 3.2i .LP The following is a technical explanation of the points drawn by \f(CWXDrawArcs()\fR. For an arc specified as \f(CW[x\fR, \f(CWy\fR, \f(CWwidth\fR, \f(CWheight\fR, \f(CWangle1\fR, \f(CWangle2]\fR, the origin of the major and minor axes is at \f(CW[x+(width/2)\fP, \f(CWy+(height/2)]\fP, and the infinitely thin path describing the entire circle or ellipse intersects the horizontal axis at \f(CW[x,\^\^y+(height/2)]\fR and \f(CW[x+width\fR, \f(CWy+(height/2)]\fR and intersects the vertical axis at \f(CW[x+(width/2)\fR,\f(CWy]\fR and \f(CW[x+(width/2)\fR, \f(CWy+height]\fR. These coordinates can be fractional. That is, they are not truncated to discrete coordinates. The path should be defined by the ideal mathematical path. For a wide line with line width \f(CWline_width\fP, the bounding outlines for filling are given by the infinitely thin paths describing the arcs: .LP .ne 10 .in +4.5n \f(CW\s9[x+dx/2, y+dy/2, width-dx, height-dy, angle1, angle2]\s0\fR .in -4.5n .LP and: .LP .ft CW .nf .in +4.5n .ps 9 .vs 11 [x-line_width/2, y-line_width/2, width+line_width, height+line_width, .ti 9n angle1, angle2] .ps .vs .ft R .fi .in -4.5n .LP where: .LP .ft CW .nf .in +4.5n .ps 9 .vs 11 dx=min(line_width,width) dy=min(line_width,height) .ps .vs .ft R .fi .in -4.5n .sp .3 .Nd 4 .LP If \f(CW(height != width)\fR the angles must be specified in the effectively skewed coordinate system of the ellipse (for a circle, the angles and coordinate systems are identical). The relationship between these angles and angles expressed in the normal coordinate system of the screen (as measured with a protractor) is as follows: .LP .ft CW .nf .in +4.5n \s9skewed-angle = atan(tan(normal-angle) * width/height) + adjust\s0 .ft R .fi .in -4.5n .LP The skewed-angle and normal-angle are expressed in radians (rather than in 64ths of a degree) in the range \f(CW[0,2*PI],\fR and where \f(CWatan\fP returns a value in the range \f(CW[-PI/2,PI/2]\fR, and where \f(CWadjust\fP is: .LP .ft CW .nf .in +4.5n .ps 9 .vs 11 0 for normal-angle in the range [0,PI/2] PI for normal-angle in the range [PI/2,(3*PI)/2] 2*PI for normal-angle in the range [(3*PI)/2,2*PI] .ps .vs .ft R .fi .in -4.5n .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" .Ps typedef struct { short x, y; unsigned short width, height; short angle1, angle2; /* Start and end of arc, in */ /* 64ths of degrees */ } XArc; .Pe .ne 4 .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .Fs .Pf amp4.eps "" "" "" "" noscale .Fe "Angle and dimension measurements for drawing arcs" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDrawFilled" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDrawFilled" .Na XDrawFilled \(en draw a filled polygon or curve from vertex list (from \f(CWX10)\fP. .Nz .SH "Synopsis" .Sy Status XDrawFilled(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW, \f(CIgc\f(CW, \f(CIvlist\f(CW, \f(CIvcount\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; Vertex *\f(CIvlist\f(CW\^; int \f(CIvcount\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIvlist\fP 1i Specifies a pointer to the list of vertices. .IP \f(CIvcount\fP 1i Specifies how many vertices are in \f(CWvlist\fP. .SH Returns Zero on failure, non-zero on success. .SH Description This function is provided for compatibility with X Version 10. To use it you must include the file .I and link with the library \fI-loldX\fP. \f(CWXDrawFilled()\fP achieves the effects of the X Version 10 \f(CWXDrawTiled\fP and \f(CWXDrawFilled()\fP functions. .LP \f(CWXDrawFilled()\fP draws arbitrary polygons or curves, according to the same rules as \f(CWXDraw\fP, and then fills them. .LP .hw subwindow \f(CWXDrawFilled()\fP uses the following graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWline_width\fP, \f(CWline_style\fP, \f(CWcap_style\fP, \f(CWjoin_style\fP, \f(CWfill_style\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. This function also uses these graphics context mode-dependent components: \f(CWforeground\fP, \f(CWbackground\fP, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, \f(CWts_y_origin\fP, \f(CWdash_offset\fP, \f(CWdashes\fP, \f(CWfill_style\fP and \f(CWfill_rule\fP. .LP \f(CWXDrawFilled()\fP returns a \f(CWStatus\fP of zero on failure, and non-zero on success. .LP For more information, see Volume One, Appendix B, \fIX10 Compatibility\fR. .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDrawImageString" "Xlib \- Text" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDrawImageString" .XX "text:8-bit characters" .Na XDrawImageString \(en draw 8-bit image text characters. .Nz .SH "Synopsis" .Sy XDrawImageString\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIstring\f(CW\^, \f(CIlength\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; char *\f(CIstring\f(CW\^; int \f(CIlength\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the baseline starting position for the image text character, relative to the origin of the specified drawable. .IP \f(CIstring\fP 1i Specifies the character string. .IP \f(CIlength\fP 1i Specifies the number of characters in the \f(CIstring\fP argument. .SH Description .XX "XDrawString" \f(CWXDrawImageString\fP draws a string, but unlike \f(CWXDrawString()\fR it draws both the foreground and the background of the characters. It draws the characters in the foreground and fills the bounding box with the background. .LP \f(CWXDrawImageString()\fP uses these graphics context components: \f(CWplane_mask\fP, \f(CWforeground\fP, \f(CWbackground\fP, \f(CWfont\fP, \f(CWsubwindow_mode\fP, .hw origin \f(CWclip_x_origin\fP, \f(CWclip_y_\fP \f(CWorigin\fP, and \f(CWclip_mask\fP. The \f(CWfunction\fP and \f(CWfill_style\fP defined in \f(CIgc\fP are ignored; the effective function is \f(CWGXcopy\fP and the effective \f(CWfill_style\fP is \f(CWFillSolid\fP. .LP \f(CWXDrawImageString()\fR first fills a destination rectangle with the \f(CWbackground\fP pixel defined in \f(CIgc\fP, and then paints the text with the \f(CWforeground\fP pixel. The upper-left corner of the filled rectangle is at \f(CW[x, y - \f(CWfont_ascent\fR], the width is \f(CWoverall->width\fR and the height is \f(CWascent + descent\fP, where \f(CWoverall->width\fR, \f(CWascent\fP, and \f(CWdescent\fP are as would be returned by \f(CWXQueryTextExtents()\fP using \f(CIgc\fP and \f(CIstring\fP. .LP For fonts defined with 2-byte matrix indexing and used with \f(CWXDrawImageString()\fP, each byte is used as a byte2 with a byte1 of zero. For more information, see Volume One, Chapter\ 6, \fIDrawing Graphics and Text\fR, and Chapter 5, \fIThe Graphics Context\fR. .br .ne 5 .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .SH "See Also" \s-1\fIXDrawImageString16()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawString16()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXDrawText16()\fP\s+1, \s-1\fIXQueryTextExtents()\fP\s+1, \s-1\fIXQueryTextExtents16()\fP\s+1, \s-1\fIXTextExtents()\fP\s+1, \s-1\fIXTextExtents16()\fP\s+1, \s-1\fIXTextWidth()\fP\s+1, \s-1\fIXTextWidth16()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDrawImageString16" "Xlib \- Text" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDrawImageString16" .XX "text:16-bit characters" .Na XDrawImageString16 \(en draw 16-bit image text characters. .Nz .SH "Synopsis" .ft CW .ta 4.5n 2.5i .nf XDrawImageString16\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIstring\f(CW\^, \f(CIlength\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; XChar2b *\f(CIstring\f(CW\^; int \f(CIlength\f(CW\^; .fi .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the baseline starting position for the image text character, relative to the origin of the specified drawable. .IP \f(CIstring\fP 1i Specifies the character string. .IP \f(CIlength\fP 1i Specifies the number of characters in the \f(CIstring\fP argument. .SH Description .XX "XDrawString16:and XDrawImageString16" \f(CWXDrawImageString16()\fP draws a string, but unlike \f(CWXDrawString16()\fR it draws both the foreground and the background of the characters. It draws the characters in the foreground and fills the bounding box with the background. .LP \f(CWXDrawImageString16()\fP uses these graphics context components: \f(CWplane_mask\fP, .hw origin \f(CWforeground\fP, \f(CWbackground\fP, \f(CWfont\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_\fP \f(CWorigin\fP, and \f(CWclip_mask\fP. The \f(CWfunction\fP and \f(CWfill_style\fP defined in \f(CIgc\fP are ignored; the effective function is \f(CWGXcopy\fP and the effective \f(CWfill_style\fP is \f(CWFillSolid\fP. .LP \f(CWXDrawImageString16()\fR first fills a destination rectangle with the \f(CWbackground\fP pixel defined in \f(CIgc\fP, and then paints the text with the \f(CWforeground\fP pixel. The upper-left corner of the filled rectangle is at \f(CW[x, y - \f(CWfont_ascent]\fR, the width is \f(CWoverall->width\fR and the height is \f(CWascent + descent\fP, where \f(CWoverall->width\fR, \f(CWascent\fP, and \f(CWdescent\fP are as would be returned by \f(CWXQueryTextExtents16()\fP using \f(CIgc\fP and \f(CIstring\fP. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .br .ne 5 .SH "Structures" .Ps typedef struct { unsigned char byte1; unsigned char byte2; } XChar2b; .Pe .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawString16()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXDrawText16()\fP\s+1, \s-1\fIXQueryTextExtents()\fP\s+1, \s-1\fIXQueryTextExtents16()\fP\s+1, \s-1\fIXTextExtents()\fP\s+1, \s-1\fIXTextExtents16()\fP\s+1, \s-1\fIXTextWidth()\fP\s+1, \s-1\fIXTextWidth16()\fP\s+1. .\"last line comment .TH XDrawImageS.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XDrawImageString@XDrawImageA .sp .5 XDrawImageString16@XDrawImageB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDrawLine" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDrawLine" .XX "lines:drawing between two points" .Na XDrawLine \(en draw a line between two points. .Nz .SH "Synopsis" .Sy XDrawLine\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIx1\f(CW\^, \f(CIy1\f(CW\^, \f(CIx2\f(CW\^, \f(CIy2\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIx1\f(CW\^, \f(CIy1\f(CW\^, \f(CIx2\f(CW\^, \f(CIy2\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP "\f(CIx1\fP,\0\f(CIy1,\fP" 1i Specify the coordinates of the endpoints of the line relative to the drawable origin. .mk U& \f(CWXDrawLine()\fP connects point (\f(CIx1,\^\^y1\fP) to point (\f(CIx2,\^\^y2\fP). .sp -1.5v .IP "\f(CIx2\fP,\0\f(CIy2\fP" .os .SH Description \f(CWXDrawLine()\fP uses the components of the specified graphics context to draw a line between two points in the specified drawable. No pixel is drawn more than once. .LP \f(CWXDrawLine()\fP uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWline_width\fP, \f(CWline_style\fP, \f(CWcap_style\fP, \f(CWfill_style\fP, \f(CWsubwindow_mode\fP, \f(CWclip_\fP \f(CWx_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. \f(CWXDrawLine()\fP also uses these graphics context mode-dependent components: \f(CWforeground\fP, \f(CWbackground\fP, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, \f(CWts_y_origin\fP, \f(CWdash_offset\fP, and \f(CWdashes\fP. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .SH "Errors" .IP "\f(CWBadDrawable\fP" 1i Specified drawable is invalid. .sp -.1v .IP "\f(CWBadGC\fP" 1i Specified GC is invalid, or does not match the depth of drawable. .sp -.1v .IP "\f(CWBadMatch\fP" 1i Specified \f(CWdrawable\fP is an \f(CWInputOnly\fP window. .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDrawLines" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .XX "XDrawLines" .XX "lines:drawing multiple connected" .Na XDrawLines \(en draw multiple connected lines. .Nz .SH "Synopsis" .Sy XDrawLines\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIpoints\f(CW\^, \f(CInpoints\f(CW\^, \f(CImode\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; XPoint *\f(CIpoints\f(CW\^; int \f(CInpoints\f(CW\^; int \f(CImode\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIpoints\fP 1i Specifies a pointer to an array of points. .IP \f(CInpoints\fP 1i Specifies the number of points in the array. .IP \f(CImode\fP 1i Specifies the coordinate mode. Pass either \f(CWCoordModeOrigin\fP or \f(CWCoordModePrevious\fP. .SH Description \f(CWXDrawLines()\fP draws a series of lines joined end-to-end. .LP It draws lines connecting each point in the list (\f(CIpoints\fP array) to the next point in the list. The lines are drawn in the order listed in the \f(CIpoints\fP array. For any given line, no pixel is drawn more than once. If thin (zero line width) lines intersect, pixels will be drawn multiple times. If the first and last points coincide, the first and last lines will join correctly. If wide lines intersect, the intersecting pixels are drawn only once, as though the entire multiline request were a single filled shape. .LP There is a limit to the number of lines that can be drawn in a single call, which varies according to the server. To determine how many lines you can draw in a single call, find out your server's maximum request size using \f(CWXMaxRequestSize()\fP. Subtract three and divide by two, and this is the maximum number of lines you can draw in a single \f(CWXDrawLines()\fP call. .LP The \f(CImode\fP argument may have two values: .IP \(bu 3n \f(CWCoordModeOrigin\fP indicates that all points are relative to the drawable's origin. .IP \(bu 3n \f(CWCoordModePrevious\fP indicates that all points after the first are relative to the previous point. (The first point is always relative to the drawable's origin.) .LP \f(CWXDrawLines()\fP uses the following components of the specified graphics context to draw multiple connected lines in the specified drawable: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWline_width\fP, \f(CWline_style\fP, \f(CWcap_style\fP, \f(CWjoin_style\fP, \f(CWfill_style\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, .ne 4 \f(CWclip_y_\fP \f(CWorigin\fP, and \f(CWclip_mask\fP. This function also uses these graphics context mode-dependent components: \f(CWforeground\fP, \f(CWbackground\fP, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, \f(CWts_y_origin\fP, \f(CWdash_offset\fP, and \f(CWdashes\fP. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .SH "Structures" .Ps typedef struct { short x, y; } XPoint; .Pe .SH "Errors" .IP "\f(CWBadDrawable\fP" 1i Specified drawable is invalid. .IP "\f(CWBadGC\fP" 1i Specified GC is invalid, or does not match the depth of drawable. .IP "\f(CWBadMatch\fP" 1i Specified \f(CWdrawable\fP is an \f(CWInputOnly\fP window. .IP "\f(CWBadValue\fP" 1i Invalid \f(CWcoordinate_mode\fP. .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDrawPoint" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .Na XDrawPoint \(en draw a point. .Nz .SH "Synopsis" .Sy XDrawPoint\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the point, relative to the origin of the drawable. .SH Description \f(CWXDrawPoint()\fP draws a single point into the specified drawable. \f(CWXDrawPoint()\fP uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWforeground\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. Use \f(CWXDrawPoints()\fP to draw multiple points. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDrawPoints" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .Na XDrawPoints \(en draw multiple points. .Nz .SH "Synopsis" .Sy XDrawPoints\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIpoints\f(CW\^, \f(CInpoints\f(CW\^, \f(CImode\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; XPoint \f(CI*points\f(CW\^; int \f(CInpoints\f(CW\^; int \f(CImode\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIpoints\fP 1i Specifies a pointer to an array of \f(CWXPoint\fP structures containing the positions of the points. .IP \f(CInpoints\fP 1i Specifies the number of points to be drawn. .IP \f(CImode\fP 1i Specifies the coordinate mode. \f(CWCoordModeOrigin\fP treats all coordinates as relative to the origin, while \f(CWCoordModePrevious\fP treats all coordinates after the first as relative to the previous point, while the first is still relative to the origin. .SH Description \f(CWXDrawPoints()\fP draws one or more points into the specified drawable. \f(CWXDrawPoints()\fP draws the points in the order listed in the array. .LP In R4 and earlier, because of the maximum request size, there is a limit to the number of points that can be drawn in a single \f(CWXDrawPoints()\fP call, that varies according to the server. In R5, Xlib breaks the call up into as many requests as required. To determine how many points you can draw in a single call in R4, you find out your server's maximum request size using \f(CWXMaxRequestSize()\fP. Subtract three and this is the maximum number of points you can draw in a single \f(CWXDrawPoints()\fP call. .LP \f(CWXDrawPoints()\fP uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWforeground\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .Nd 10 .SH "Structures" .Ps typedef struct { short x, y; } XPoint; .Pe .ne 5 .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .br \f(CWBadValue\fP .br .ne 5 .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDrawRectangle" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .Na XDrawRectangle \(en draw an outline of a rectangle. .Nz .SH "Synopsis" .Sy XDrawRectangle\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the upper-left corner of the rectangle, relative to the drawable's origin. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight\fP 1i .sp -2 Specify the width and height in pixels. These dimensions define the outline of the rectangle. .SH Description \f(CWXDrawRectangle()\fP draws the outline of the rectangle by using the \f(CIx\fP and \f(CIy\fP coordinates, \f(CIwidth\fP and \f(CIheight\fP, and graphics context you specify. Specifically, \f(CWXDrawRectangle()\fP uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWline_width\fP, \f(CWline_style\fP, \f(CWjoin_style\fP, \f(CWfill_style\fP, \f(CWsubwindow_mode\fP, \f(CWclip_\fP \f(CWx_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. This function also uses these graphics context mode-dependent components: \f(CWforeground\fP, \f(CWbackground\fP, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, \f(CWts_y_origin\fP, \f(CWdash_offset\fP, and \f(CWdashes\fP. .LP For the specified rectangle, no pixel is drawn more than once. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .Nd 15 .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .Fs .Pf amp5.eps "" "" "" "" noscale .Fe "The pixels affected by XFillRectangle versus XDrawRectangle with the same arguments" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDrawRectangles" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .Na XDrawRectangles \(en draw the outlines of multiple rectangles. .Nz .SH "Synopsis" .ft CW .ta 4.5n 2.5i .nf XDrawRectangles\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIrectangles\f(CW\^, \f(CInrectangles\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; XRectangle \f(CIrectangles\f(CW[]\^; int \f(CInrectangles\f(CW\^; .fi .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIrectangles\fP 1i Specifies a pointer to an array of rectangles containing position and size information. .IP \f(CInrectangles\fP 1i Specifies the number of rectangles in the array. .SH Description \f(CWXDrawRectangles()\fP draws the outlines of the specified rectangles by using the position and size values in the array of rectangles. The x and y coordinates of each rectangle are relative to the drawable's origin, and define the upper-left corner of the rectangle. .LP The rectangles are drawn in the order listed. For any given rectangle, no pixel is drawn more than once. If rectangles intersect, pixels are drawn multiple times. .LP In R4 and earlier there is a limit to the number of rectangles that can be drawn in a single \f(CWXDrawRectangles()\fP call, based on the maximum request size, which varies according to the server. In R5, Xlib chops your call into as many protocol requests as required. To determine how many rectangles you can draw in a single call in R4, find out your server's maximum request size using \f(CWXMaxRequestSize()\fP. Subtract three and divide by two. This is the maximum number of rectangles you can draw in a single \f(CWXDrawRectangles()\fP call. .LP This function uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWline_width\fP, \f(CWline_style\fP, \f(CWjoin_style\fP, \f(CWfill_style\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. \f(CWXDrawRectangles()\fP also uses these graphics context mode-dependent components: \f(CWforeground\fP, \f(CWbackground\fP, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, \f(CWts_y_origin\fP, \f(CWdash_offset\fP, and \f(CWdashes\fP. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .br .ne 6 .SH "Structures" .Ps typedef struct { short x, y; unsigned short width, height; } XRectangle; .Pe .ne 4 .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .Fs .Pf amp6.eps "" "" "" "" noscale .Fe "The pixels affected by XFillRectangles versus XDrawRectangles with the same arguments" .\"last line comment .TH XDrawRectan.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XDrawRectangle@XDrawRectaA .sp .5 XDrawRectangles@XDrawRectaB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDrawSegments" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .Na XDrawSegments \(en draw multiple disjoint lines. .Nz .SH "Synopsis" .Sy XDrawSegments\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIsegments\f(CW\^, \f(CInsegments\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; XSegment *\f(CIsegments\f(CW\^; int \f(CInsegments\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIsegments\fP 1i Specifies a pointer to an array of line segments. .IP \f(CInsegments\fP 1i Specifies the number of segments in the array. .SH Description \f(CWXDrawSegments()\fP draws multiple line segments into the specified drawable. Each line is specified by a pair of points, so the line may be connected or disjoint. .LP For each segment, \f(CWXDrawSegments()\fP draws a line between (\f(CIx1, y1\fP) and (\f(CIx2, y2\fP). The lines are drawn in the order listed in \f(CIsegments\fP. For any given line, no pixel is drawn more than once. If lines intersect, pixels will be drawn multiple times. The lines will be drawn separately, without regard to the \f(CWjoin_style\fP. .LP In R4 and earlier there is a limit to the number of rectangles that can be drawn in a single \f(CWXDrawSegments()\fP call, based on the maximum request size, which varies according to the server. In R5, Xlib chops your call into as many protocol requests as required. To determine how many rectangles you can draw in a single call in R4, find out your server's maximum request size using \f(CWXMaxRequestSize()\fP. Subtract three and divide by two. This is the maximum number of segments you can draw in a single \f(CWXDrawSegments()\fP call. .LP \f(CWXDrawSegments()\fP uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWline_width\fP, \f(CWline_style\fP, \f(CWcap_style\fP, \f(CWfill_style\fP, \f(CWsubwindow_mode\fP, \f(CWclip_\fP \f(CWx_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. \f(CWXDrawSegments()\fP also uses these graphics context mode-dependent components: \f(CWforeground\fP, \f(CWbackground\fP, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, \f(CWts_y_origin\fP, \f(CWdash_offset\fP, and \f(CWdashes\fP. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .Nd 6 .SH "Structures" .Ps typedef struct { short x1, y1, x2, y2; } XSegment; .Pe .ne 4 .SH "Errors" .IP "\f(CWBadDrawable\fP" 1i Specified drawable is invalid. .IP "\f(CWBadGC\fP" 1i Specified GC is invalid, or does not match the depth of drawable. .IP "\f(CWBadMatch\fP" 1i Specified \f(CIdrawable\fP is an \f(CWInputOnly\fP window. .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDrawString" "Xlib \- Text" .ds ]W Xlib Reference Manual .SH "Name" .Na XDrawString \(en draw an 8-bit text string, foreground only. .Nz .SH "Synopsis" .Sy XDrawString\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIstring\f(CW\^, \f(CIlength\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; char *\f(CIstring\f(CW\^; int \f(CIlength\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the baseline starting position for the character, relative to the origin of the specified drawable. .IP \f(CIstring\fP 1i Specifies the character string. .IP \f(CIlength\fP 1i Specifies the number of characters in \f(CIstring\fP. .SH Description \f(CWXDrawString()\fP draws the given string into a drawable using the \f(CWforeground\fP only to draw set bits in the font. It does not affect any other pixels in the bounding box for each character. .LP The \f(CIy\fP coordinate defines the baseline row of pixels while the \f(CIx\fP coordinate is the point from which \f(CWlbearing\fP, \f(CWrbearing\fP, and \f(CWwidth\fP are measured. .LP \f(CWXDrawString()\fP uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWfill_style\fP, \f(CWfont\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. This function also uses these graphics context mode-dependent components: \f(CWforeground\fP, \f(CWbackground\fR, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, and \f(CWts_y_origin\fP. Each character image, as defined by the font in \f(CIgc\fP, is treated as an additional mask for a fill operation on the drawable. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .Nd 10 .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .br .ne 4 .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawImageString16()\fP\s+1, \s-1\fIXDrawString16()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXDrawText16()\fP\s+1, \s-1\fIXQueryTextExtents()\fP\s+1, \s-1\fIXQueryTextExtents16()\fP\s+1, \s-1\fIXTextExtents()\fP\s+1, \s-1\fIXTextExtents16()\fP\s+1, \s-1\fIXTextWidth()\fP\s+1, \s-1\fIXTextWidth16()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDrawString16" "Xlib \- Text" .ds ]W Xlib Reference Manual .SH "Name" .Na XDrawString16 \(en draw two-byte text strings. .Nz .SH "Synopsis" .Sy XDrawString16\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIstring\f(CW\^, \f(CIlength\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; XChar2b *\f(CIstring\f(CW\^; int \f(CIlength\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the baseline starting position for the character, relative to the origin of the specified drawable. .IP \f(CIstring\fP 1i Specifies the character string. Characters are two bytes wide. .IP \f(CIlength\fP 1i Specifies the number of characters in \f(CIstring\fP. .SH Description \f(CWXDrawString16()\fP draws a string in the foreground pixel value without drawing the surrounding pixels. .LP The \f(CIy\fP coordinate defines the baseline row of pixels while the \f(CIx\fP coordinate is the point from which \f(CWlbearing\fP, \f(CWrbearing\fP, and \f(CWwidth\fP are measured. For more information on text placement, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .LP \f(CWXDrawString16()\fP uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWfill_style\fP, \f(CWfont\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. This function also uses these graphics context mode-dependent components: \f(CWforeground\fP, \f(CWbackground\fR, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, and \f(CWts_y_origin\fP. Each character image, as defined by the font in \f(CIgc\fP, is treated as an additional mask for a fill operation on the drawable. For fonts defined with 2-byte matrix indexing and used with \f(CWXDrawString16()\fP, each byte is used as a \f(CWbyte2\fR with a \f(CWbyte1\fR of zero. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .Nd 10 .SH "Structures" .Ps typedef struct { unsigned char byte1; unsigned char byte2; } XChar2b; .Pe .ne 5 .SH "Errors" \f(CWBadDrawable\fP \f(CWBadFont\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawImageString16()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXDrawText16()\fP\s+1, \s-1\fIXQueryTextExtents()\fP\s+1, \s-1\fIXQueryTextExtents16()\fP\s+1, \s-1\fIXTextExtents()\fP\s+1, \s-1\fIXTextExtents16()\fP\s+1, \s-1\fIXTextWidth()\fP\s+1, \s-1\fIXTextWidth16()\fP\s+1. .\"last line comment .TH XDrawString.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XDrawString@XDrawStrinA .sp .5 XDrawString16@XDrawStrinB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDrawText" "Xlib \- Text" .ds ]W Xlib Reference Manual .SH "Name" .Na XDrawText \(en draw 8-bit polytext strings. .Nz .SH "Synopsis" .Sy XDrawText\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIitems\f(CW\^, \f(CInitems\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; XTextItem *\f(CIitems\f(CW\^; int \f(CInitems\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the baseline starting position for the initial string, relative to the origin of the specified drawable. .IP \f(CIitems\fP 1i Specifies a pointer to an array of text items. .IP \f(CInitems\fP 1i Specifies the number of text items in the \f(CIitems\fP array. .SH Description \f(CWXDrawText()\fP is capable of drawing multiple strings on the same horizontal line and changing fonts between strings. Each \f(CWXTextItem\fP structure contains a string, the number of characters in the string, the \f(CWdelta\fP offset from the starting position for the string, and the font. Each text item is processed in turn. The font in each \f(CWXTextItem\fP is stored in the specified GC and used for subsequent text. If the \f(CWXTextItem.font\fP is \f(CWNone\fP, the font in the GC is used for drawing and is not changed. Switching between fonts with different drawing directions is permitted. .LP The \f(CWdelta\fP in each \f(CWXTextItem\fP specifies the change in horizontal position before the string is drawn. The delta is always added to the character origin and is not dependent on the draw direction of the font. For example, if \f(CWx = 40\fR, \f(CWy = 20\fR, and \f(CWitems[0].delta = 8\fR, the string specified by \f(CWitems[0].chars\fR would be drawn starting at \f(CWx = 48\fR, \f(CWy = 20\fR. The \f(CWdelta\fP for the second string begins at the \f(CWrbearing\fP of the last character in the first string. A negative \f(CWdelta\fP would tend to overlay subsequent strings on the end of the previous string. .LP Only the pixels selected in the font are drawn (the \f(CWbackground\fP member of the GC is not used to fill the bounding box). .LP In all X releases, there is a limit to the number and size of strings that can be drawn in a single \f(CWXDrawText()\fP call, that varies according to the server. To determine how much text you can draw in a single call, you find out your server's maximum request size using \f(CWXMaxRequestSize()\fP. Subtract four, and then subtract .ne 6 \f(CW((strlen(string)+2)/4)\fP for each string. This is the maximum amount of text you can draw in a single \f(CWXDrawText()\fP call. .LP \f(CWXDrawText()\fP uses the following elements in the specified GC: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWfill_style\fP, \f(CWfont\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. This function also uses these graphics context mode-dependent .ne 2 components: \f(CWforeground\fP, \f(CWbackground\fR, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, and \f(CWts_y_origin\fP. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .SH "Structures" .Ps typedef struct { char *chars; /* pointer to string */ int nchars; /* number of characters */ int delta; /* delta between strings */ Font font; /* font to print it in, None don't change */ } XTextItem; .Pe .vs .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadFont\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawImageString16()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawString16()\fP\s+1, \s-1\fIXDrawText16()\fP\s+1, \s-1\fIXQueryTextExtents()\fP\s+1, \s-1\fIXQueryTextExtents16()\fP\s+1, \s-1\fIXTextExtents()\fP\s+1, \s-1\fIXTextExtents16()\fP\s+1, \s-1\fIXTextWidth()\fP\s+1, \s-1\fIXTextWidth16()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XDrawText16" "Xlib \- Text" .ds ]W Xlib Reference Manual .SH "Name" .Na XDrawText16 \(en draw 16-bit polytext strings. .Nz .SH "Synopsis" .Sy XDrawText16\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIitems\f(CW\^, \f(CInitems\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; XTextItem16 *\f(CIitems\f(CW\^; int \f(CInitems\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the baseline starting position for the initial string, relative to the origin of the specified drawable. .IP \f(CIitems\fP 1i Specifies a pointer to an array of text items using two-byte characters. .IP \f(CInitems\fP 1i Specifies the number of text items in the array. .SH Description \f(CWXDrawText16()\fP is capable of drawing multiple strings on the same horizontal line and changing fonts between strings. Each \f(CWXTextItem\fP structure contains a string, the number of characters in the string, the \f(CWdelta\fP offset from the starting position for the string, and the font. Each text item is processed in turn. The font in each \f(CWXTextItem\fP is stored in the specified GC and used for subsequent text. If the \f(CWXTextItem16.font\fP is \f(CWNone\fP, the font in the GC is used for drawing and is not changed. Switching between fonts with different drawing directions is permitted. .LP The \f(CWdelta\fP in each \f(CWXTextItem\fP specifies the change in horizontal position before the string is drawn. The delta is always added to the character origin and is not dependent on the drawing direction of the font. For example, if \f(CWx = 40\fR, \f(CWy = 20\fR, and \f(CWitems[0].delta = 8\fR, the string specified by \f(CWitems[0].chars\fR would be drawn starting at \f(CWx = 48\fR, \f(CWy = 20\fR. The \f(CWdelta\fP for the second string begins at the \f(CWrbearing\fP of the last character in the first string. A negative \f(CWdelta\fP would tend to overlay subsequent strings on the end of the previous string. .LP Only the pixels selected in the font are drawn (the \f(CWbackground\fP member of the GC is not used to fill the bounding box). .LP In all X releases there is a limit to the number and size of strings that can be drawn in a single \f(CWXDrawText16()\fP call, that varies according to the server. To determine how much text you can draw in a single call, you find out your server's maximum request size using \f(CWXMaxRequestSize()\fP. Subtract four, and then subtract \f(CW((strlen(string)+2)/4)\fP for each string. This is the maximum amount of text you can draw in a single \f(CWXDrawText16()\fP call. .LP \f(CWXDrawText16()\fP uses the following elements in the specified GC: \f(CWfunction\fP, \f(CWplane_\fP \f(CWmask\fP, \f(CWfill_style\fP, \f(CWfont\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. This function also uses these graphics context mode-dependent .ne 2 components: \f(CWforeground\fP, \f(CWbackground\fR, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, and \f(CWts_y_\p origin\fP. .LP Note that the \f(CWchars\fR member of the \f(CWXTextItem16\fR structure is of type \f(CWXChar2b\fR, rather than of type \f(CWchar\fR as it is in the \f(CWXTextItem\fR structure. For fonts defined with linear indexing rather than two-byte matrix indexing, the X server will interpret each member of the \f(CWXChar2b\fR structure as a 16-bit number that has been transmitted most significant byte first. In other words, the \f(CWbyte1\fR member of the \f(CWXChar2b\fR structure is taken as the most significant byte. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .SH "Structures" .Ps typedef struct { XChar2b *chars; /* 2 byte characters */ int nchars; /* number of characters */ int delta; /* delta between strings */ Font font; /* font to print it in, None don't change */ } XTextItem16; typedef struct { /* normal 16 bit characters are two bytes */ unsigned char byte1; unsigned char byte2; } XChar2b; .Pe .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadFont\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawImageString16()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawString16()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXQueryTextExtents()\fP\s+1, \s-1\fIXQueryTextExtents16()\fP\s+1, \s-1\fIXTextExtents()\fP\s+1, \s-1\fIXTextExtents16()\fP\s+1, \s-1\fIXTextWidth()\fP\s+1, \s-1\fIXTextWidth16()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XEmptyRegion" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .Na XEmptyRegion \(en determine if a region is empty. .Nz .SH "Synopsis" .Sy Bool XEmptyRegion\^(\^\f(CIr\f(CW\^) .As Region \f(CIr\f(CW\^; .Ae .ft R .SH "Arguments" .IP \f(CIr\fP 1i Specifies the region to be checked. .SH Returns \f(CWTrue\fP if it's empty, else \f(CWFalse\fP. .SH Description \f(CWXEmptyRegion()\fP will return \f(CWTrue\fP if the specified region is empty, or \f(CWFalse\fP otherwise. .SH "Structures" \f(CWRegion\fP is a pointer to an opaque structure type. .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXCreateRegion()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XEnableAccessControl" "Xlib \- Host Access" .ds ]W Xlib Reference Manual .SH "Name" .Na XEnableAccessControl \(en use access control list to allow or deny connection requests. .Nz .SH "Synopsis" .Sy XEnableAccessControl\^(\^\f(CIdisplay\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Description \f(CWXEnableAccessControl()\fP instructs the server to use the host access list to determine whether access should be granted to clients seeking a connection with the server. .LP By default, the host access list is used. If access has not been disabled with \f(CWXDisableAccessControl()\fP or \f(CWXSetAccessControl()\fP, this routine does nothing. .LP This routine can only be called by clients running on the same host as the server. .LP For more information, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "Errors" \f(CWBadAccess\fP .SH "See Also" \s-1\fIXAddHost()\fP\s+1, \s-1\fIXAddHosts()\fP\s+1, \s-1\fIXDisableAccessControl()\fP\s+1, \s-1\fIXListHosts()\fP\s+1, \s-1\fIXRemoveHost()\fP\s+1, \s-1\fIXRemoveHosts()\fP\s+1, \s-1\fIXSetAccessControl()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XEqualRegion" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .Na XEqualRegion \(en determine if two regions have the same size, offset, and shape. .Nz .SH "Synopsis" .Sy Bool XEqualRegion\^(\^\f(CIr1\f(CW\^, \f(CIr2\f(CW\^) .As Region \f(CIr1\f(CW\^, \f(CIr2\f(CW\^; .Ae .SH "Arguments" .IP \f(CIr1\fP 1i .br .ns .IP \f(CIr2\fP 1i Specify the two regions you want to compare. .sp .LP .SH Returns \f(CWTrue\fP or \f(CWFalse\fP. .SH Description \f(CWXEqualRegion()\fP returns \f(CWTrue\fP if the two regions are identical; i.e., they have the same offset, size and shape, or \f(CWFalse\fP otherwise. .LP Regions are located using an offset from a point (the \fIregion origin\fR) which is common to all regions. It is up to the application to interpret the location of the region relative to a drawable. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" \f(CWRegion\fP is a pointer to an opaque structure type. .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXCreateRegion()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XEventMaskOfScreen" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XEventMaskOfScreen, EventMaskOfScreen \(en get initial root window event mask. .XX "XEventMaskOfScreen macro equivalent" .Nz .\" .\" .SH "Synopsis" .Sy long XEventMaskOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIscreen\fP 1i Specifies the appropriate \f(CWScreen\fP structure. .\" .\" .SH Returns An event mask. .SH Description .XX "event masks:returning" \f(CWXEventMaskOfScreen()\fP returns the event mask at connection setup time of the root window for the specified screen. .LP .XX "EventMaskOfScreen" The C language macro \f(CWEventMaskOfScreen()\fP is equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXSelectEvents()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XEventsQueued" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .Na XEventsQueued \(en check the number of events in the event queue. .Nz .SH "Synopsis" .Sy int XEventsQueued\^(\^\f(CIdisplay\fP, \f(CImode\fP\^) .As Display *\f(CIdisplay\fP\^; int \f(CImode\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to a \f(CWDisplay\fP structure, returned from \f(CWXOpenDisplay()\fP. .IP \f(CImode\fP 1i Specifies whether the request buffer is flushed if there are no events in Xlib's queue. You can specify one of these constants: \f(CWQueuedAlready\fP, \f(CWQueuedAfterFlush\fP, \f(CWQueuedAfterReading\fP. .SH Returns The number of events. .SH Description \f(CWXEventsQueued()\fP checks whether events are queued. If there are events in Xlib's queue, the routine returns immediately to the calling routine. Its return value is the number of events regardless of \f(CImode\fP. .LP \f(CImode\fP specifies what happens if no events are found on Xlib's queue. .IP \(bu 3n If \f(CImode\fP is \f(CWQueuedAlready\fP, and there are no events in the queue, \f(CWXEventsQueued()\fP returns zero (it does not flush the request buffer or attempt to read more events from the connection). .IP \(bu 3n If \f(CImode\fP is \f(CWQueuedAfterFlush\fP, and there are no events in the queue, \f(CWXEventsQueued()\fP flushes the request buffer, attempts to read more events out of the application's connection, and returns the number read. .IP \(bu 3n If \f(CImode\fP is \f(CWQueuedAfterReading\fP, and there are no events in the queue, \f(CWXEventsQueued()\fP attempts to read more events out of the application's connection without flushing the request buffer and returns the number read. .LP Note that \f(CWXEventsQueued()\fP always returns immediately without I/O if there are events already in the queue. .LP \f(CWXEventsQueued()\fP with mode \f(CWQueuedAfterFlush\fP is identical in behavior to \f(CWXPending()\fP. \f(CWXEventsQueued()\fP with mode \f(CWQueuedAlready\fP is identical to the \f(CWQLength()\fP macro (see Appendix C, \fIMacros\fR). .LP For more information, see Volume One, Chapter 8, \fIEvents\fR. .Nd 6 .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XExtentsOfFontSet" "Xlib \- Text Output" .ds ]W Xlib Reference Manual .XX "XExtentsOfFontSet" .XX "font set:extents structure, obtaining maximum" .SH Name .Na XExtentsOfFontSet \(en obtain the maximum extents structure for a font set. .Nz .SH Synopsis .Sy XFontSetExtents *XExtentsOfFontSet\^(\^\f(CIfont_set\fP\^) .As XFontSet \f(CIfont_set\fP\^; .Ae .SH Arguments .IP \f(CIfont_set\fP 1i Specifies the font set. .SH Returns A structure containing the extents. .SH Availability Release 5 and later. .SH Description \f(CWXExtentsOfFontSet()\fR returns an \f(CWXFontSetExtents()\fR structure for the given font set. .LP The \f(CWXFontSetExtents()\fR structure is owned by Xlib and should not be modified or freed by the client. It will be freed by a call to \f(CWXFreeFontSet()\fR with the associated \f(CWXFontSet\fR. Until freed, its contents will not be modified by Xlib. .SH Structures The \f(CWXFontSetExtents\fR structure contains: .Ps .TA .5i 3i .ta .5i 3i typedef struct { XRectangle max_ink_extent; /*over all drawable characters*/ XRectangle max_logical_extent; /*over all drawable characters*/ } XFontSetExtents; .Pe The \f(CWXRectangles\fR used to return font set metrics are the usual Xlib screen-oriented \f(CWXRectangles\fR, with x, y giving the upper-left corner, and width and height always positive. .LP The \f(CWmax_ink_extent\fP member gives the maximum extent, over all drawable characters, of the rectangles which bound the character glyph image drawn in the foreground color, relative to a constant origin. See \f(CWXmbTextExtents\fR and \f(CWXwcTextExtents\fR for detailed semantics. .LP The \f(CWmax_logical_extent\fP member gives the maximum extent, over all drawable characters, of the rectangles which specify minimum spacing to other graphical features, relative to a constant origin. Other graphical features drawn by the client, for example, a border surrounding the text, should not intersect this rectangle. The \f(CWmax_logical_extent\fP member should be used to compute minimum .ne 2 interline spacing and the minimum area which must be allowed in a text field to draw a given number of arbitrary characters. .LP .Nd 10 Due to context-dependent rendering, appending a given character to a string may increase the string's extent by an amount which exceeds the font's max extent: .LP .Ps \s-1max possible added extent = (max_extent * ) \- prev_string_extent\s+1 .Pe .SH "See Also" \s-1\fIXCreateFontSet()\fP\s+1, \s-1\fIXFontsOfFontSet()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFetchBuffer" "Xlib \- Cut Buffers" .ds ]W Xlib Reference Manual .SH "Name" .Na XFetchBuffer \(en return data from a cut buffer. .Nz .SH "Synopsis" .Sy char *XFetchBuffer\^(\^\f(CIdisplay\f(CW, \f(CInbytes_return\f(CW\^, \f(CIbuffer\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int *\f(CInbytes_return\f(CW\^; int \f(CIbuffer\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CInbytes_return\fP 1i Returns the number of bytes in \f(CIbuffer\fP returned by \f(CWXFetchBuffer()\fR. If there is no data in the buffer, \f(CI*nbytes_return\fP is set to 0. .IP \f(CIbuffer\fP 1i Specifies which buffer you want data from. Specify an integer from 0 to 7 inclusive. .SH Returns The buffer data. .SH Description \f(CWXFetchBuffer()\fP returns data from one of the eight buffers provided for interclient communication. If the buffer contains data, \f(CWXFetchBuffer()\fP returns the number of bytes in \f(CInbytes_return\fP, otherwise it returns \f(CWNULL\fP and sets \f(CI*nbytes_return\fP to 0. The appropriate amount of storage is allocated and the pointer returned; the client must free this storage when finished with it by calling \f(CWXFree()\fP. Note that the cut buffer does not necessarily contain text, so it may contain embedded null bytes and may not terminate with a null byte. .LP Selections are preferred over cut buffers as a communication scheme. .LP For more information on cut buffers, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH Errors .IP "\f(CWBadValue\fP" 1i \f(CIbuffer\fP not an integer between 0 and 7 inclusive. .SH "See Also" \s-1\fIXFetchBytes()\fP\s+1, \s-1\fIXRotateBuffers()\fP\s+1, \s-1\fIXStoreBuffer()\fP\s+1, \s-1\fIXStoreBytes()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFetchBytes" "Xlib \- Cut Buffers" .ds ]W Xlib Reference Manual .SH "Name" .Na XFetchBytes \(en return data from cut buffer 0. .Nz .SH "Synopsis" .Sy char *XFetchBytes\^(\^\f(CIdisplay\f(CW, \f(CInbytes_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int *\f(CInbytes_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CInbytes_return\fP 1i Returns the number of bytes in the string returned by \f(CWXFetchBytes()\fP. If there is no data in the buffer, \f(CI*nbytes_return\fP is set to 0. .SH Returns The buffer data. .SH Description \f(CWXFetchBytes()\fP returns data from cut buffer 0 of the eight buffers provided for interclient communication. If the buffer contains data, \f(CWXFetchBytes()\fP returns the number of bytes in \f(CInbytes_return\fP, otherwise it returns \f(CWNULL\fP and sets \f(CI*nbytes_return\fP to 0. The appropriate amount of storage is allocated and the pointer returned; the client must free this storage when finished with it by calling \f(CWXFree()\fP. Note that the cut buffer does not necessarily contain text, so it may contain embedded null bytes and may not terminate with a null byte. .LP Use \f(CWXFetchBuffer()\fP to fetch data from any specified cut buffer. .LP Selections are preferred over cut buffers as a communication method. .LP For more information on cut buffers, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "See Also" \s-1\fIXFetchBuffer()\fP\s+1, \s-1\fIXRotateBuffers()\fP\s+1, \s-1\fIXStoreBuffer()\fP\s+1, \s-1\fIXStoreBytes()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFetchName" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .Na XFetchName \(en get a window's name (\f(CWXA_WM_NAME\fP property). .Nz .SH "Synopsis" .Sy Status XFetchName\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIwindow_name_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; char **\f(CIwindow_name_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window whose name you want a pointer set to. .IP \f(CIwindow_name_return\fP 1i Returns a pointer to the window name, which will be a \f(CWNULL\fP-terminated string. If the \f(CWXA_WM_NAME\fP property has not been set for this window, \f(CWXFetchName()\fP sets \f(CIwindow_name_return\fP to \f(CWNULL\fP. When finished with it, a client must free the name string using \f(CWXFree()\fP. .SH Returns Zero on failure, non-zero on success. .SH Description \f(CWXFetchName()\fP is superseded by \f(CWXGetWMName()\fP in Release 4. \f(CWXFetchName()\fP returns the current value of the \f(CWXA_WM_NAME\fP property for the specified window. \f(CWXFetchName()\fP returns non-zero if it succeeds, and zero if the property has not been set for the argument window. .LP If the data returned by the server is in the Latin Portable Character Encoding, then the returned string is in the Host Portable Character Encoding. Otherwise, the result is implementation-dependent. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fR, and Chapter 16, \fIWindow Management\fR. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFillArc" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .Na XFillArc \(en fill an arc. .Nz .SH "Synopsis" .Sy XFillArc\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^, \f(CIangle1\f(CW\^, \f(CIangle2\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; int \f(CIangle1\f(CW\^, \f(CIangle2\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the upper-left corner of the bounding box containing the arc, relative to the origin of the drawable. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight\fP 1i .sp -2 Specify the width and height in pixels. These are the major and minor axes of the arc. .IP \f(CIangle1\fP 1i Specifies the start of the arc relative to the three-o'clock position from the center. Angles are specified in 64ths of degrees. .IP \f(CIangle2\fP 1i Specifies the path and extent of the arc relative to the start of the arc. Angles are specified in 64ths of degrees. .SH Description \f(CWXFillArc()\fP draws a filled arc. The \f(CIx\fP, \f(CIy\fP, \f(CIwidth\fP, and \f(CIheight\fP arguments specify the bounding box for the arc. See \f(CWXDrawArc()\fP for the description of how this bounding box is used to compute the arc. Some, but not all, of the pixels drawn with \f(CWXDrawArc()\fP will be drawn by \f(CWXFillArc()\fP with the same arguments. See \f(CWXFillRectangle()\fP for an example of the differences in pixels drawn by the draw and fill routines. .LP The arc forms one boundary of the area to be filled. The other boundary is determined by the \f(CWarc_mode\fP in the GC. If the \f(CWarc_mode\fP in the GC is \f(CWArcChord\fP, the single line segment joining the endpoints of the arc is used. If \f(CWArcPieSlice\fP, the two line segments joining the endpoints of the arc with the center point are used. .LP \f(CWXFillArc()\fP uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWfill_style\fP, \f(CWarc_mode\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. .ne 6 This function also uses these graphics context mode-dependent components: \f(CWforeground\fP, \f(CWbackground\fP, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, and \f(CWts_y_\p origin\fP. .ta 4.5n 2.75i .nf .ft CW .fi .ft R .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFillArcs" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .Na XFillArcs \(en fill multiple arcs. .Nz .SH "Synopsis" .Sy XFillArcs\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIarcs\f(CW\^, \f(CInarcs\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; XArc *\f(CIarcs\f(CW\^; int \f(CInarcs\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP Specifies the drawable. .IP \f(CIgc\fP Specifies the graphics context. .IP \f(CIarcs\fP Specifies a pointer to an array of arc definitions. .IP \f(CInarcs\fP Specifies the number of arcs in the array. .SH Description For each arc, \f(CWXFillArcs()\fP fills the region closed by the specified arc and one or two line segments, depending on the \f(CWarc_mode\fP specified in the GC. It does not draw the complete outlines of the arcs, but some pixels may overlap. .LP The arc forms one boundary of the area to be filled. The other boundary is determined by the \f(CWarc_mode\fP in the GC. If the \f(CWarc_mode\fP in the GC is \f(CWArcChord\fP, the single line segment joining the endpoints of the arc is used. If \f(CWArcPieSlice\fP, the two line segments joining the endpoints of the arc with the center point are used. The arcs are filled in the order listed in the array. For any given arc, no pixel is drawn more than once. If filled arcs intersect, pixels will be drawn multiple times. .LP In R4 and earlier there is a limit to the number of rectangles that can be drawn in a single call, based on the maximum request size, which varies according to the server. In R5, Xlib chops your call into as many protocol requests as required. To determine how many rectangles you can draw in a single call in R4, you find out your server's maximum request size using \f(CWXMaxRequestSize()\fP. Subtract three and divide by three, and this is the maximum number of arcs you can fill in a single \f(CWXFillArcs()\fP call. .LP \f(CWXFillArcs()\fP use these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWfill_style\fP, \f(CWarc_mode\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. This function also uses these graphics context mode-dependent components: \f(CWforeground\fP, \f(CWbackground\fP, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, and \f(CWts_y_\p origin\fR. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .SH "Structures" .Ps typedef struct { short x, y; unsigned short width, height; short angle1, angle2; /* 64ths of Degrees */ } XArc; .Pe .ne 4 .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH XFillPolygon "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .Na XFillPolygon \(en fill a polygon. .Nz .SH "Synopsis" .Sy .nf XFillPolygon\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIpoints\f(CW\^, \f(CInpoints\f(CW\^, \f(CIshape\f(CW\^, \f(CImode\f(CW\^) .fi .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; XPoint *\f(CIpoints\f(CW\^; int \f(CInpoints\f(CW\^; int \f(CIshape\f(CW\^; int \f(CImode\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIpoints\fP 1i Specifies a pointer to an array of points. .IP \f(CInpoints\fP 1i Specifies the number of points in the array. .IP \f(CIshape\fP 1i Specifies an argument that helps the server to improve performance. Pass the last constant in this list that is valid for the polygon to be filled: \f(CWComplex\fP, \f(CWNonconvex\fP, or \f(CWConvex\fP. .IP \f(CImode\fP 1i Specifies the coordinate mode. Pass either \f(CWCoordModeOrigin\fP or \f(CWCoordModePrevious\fP. .SH Description \f(CWXFillPolygon()\fP fills the region closed by the specified path. Some but not all of the path itself will be drawn. The path is closed automatically if the last point in the list does not coincide with the first point. No pixel of the region is drawn more than once. .LP The \f(CImode\fP argument affects the interpretation of the points that define the polygon: .IP \(bu 3n \f(CWCoordModeOrigin\fP indicates that all points are relative to the drawable's origin. .IP \(bu 3n \f(CWCoordModePrevious\fP indicates that all points after the first are relative to the previous point. (The first point is always relative to the drawable's origin.) .LP The \f(CIshape\fP argument allows the fill routine to optimize its performance given tips on the configuration of the area. .IP \(bu 3n \f(CWComplex\fP indicates the path may self-intersect. The \f(CWfill_rule\fP of the GC must be consulted to determine which areas are filled. See Volume One, Chapter 5, \fIThe Graphics Context\fR, for a discussion of the fill rules \f(CWEvenOddRule\fP and \f(CWWindingRule\fP. .Nd 5 .IP \(bu 3n \f(CWNonconvex\fP indicates the path does not self-intersect, but the shape is not wholly convex. If known by the client, specifying \f(CWNonconvex\fP instead of \f(CWComplex\fP may improve performance. If you specify \f(CWNonconvex\fP for a self-intersecting path, the graphics results are undefined. .IP \(bu 3n \f(CWConvex\fP means that for every pair of points inside the polygon, the line segment connecting them does not intersect the path. \f(CWConvex\fP can improve performance even more than \f(CWNonconvex\fP, but if the path is not convex, the graphics results are undefined. .LP Contiguous coincident points in the path are not treated as self-intersection. .LP \f(CWXFillPolygon()\fP uses these graphics context components when filling the polygon area: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWfill_style\fP, \f(CWfill_rule\fP, \f(CWsubwindow_mode\fP, \f(CWclip_\fP \f(CWx_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. This function also uses these mode-dependent components of the GC: \f(CWforeground\fP, \f(CWbackground\fP, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_\p origin\fP, and \f(CWts_y_origin\fP. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .br .ne 5 .SH "Structures" .Ps typedef struct { short x, y; } XPoint; .Pe .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .br \f(CWBadValue\fP .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFillRectangle" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .Na XFillRectangle \(en fill a rectangular area. .Nz .SH "Synopsis" .Sy .nf XFillRectangle\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^) .fi .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP Specifies the drawable. .IP \f(CIgc\fP Specifies the graphics context. .IP \f(CIx\fP .br .ns .IP \f(CIy\fP .sp -2 Specify the x and y coordinates of the upper-left corner of the rectangle, relative to the origin of the drawable. .IP \f(CIwidth\fP .br .ns .IP \f(CIheight\fP Specify the dimensions in pixels of the rectangle to be filled. .sp .LP .SH Description \f(CWXFillRectangle()\fP fills the rectangular area in the specified drawable using the \f(CIx\fP and \f(CIy\fP coordinates, \f(CIwidth\fP and \f(CIheight\fP dimensions, and graphics context you specify. \f(CWXFillRectangle()\fP draws some but not all of the path drawn by \f(CWXDrawRectangle()\fP with the same arguments. .LP \f(CWXFillRectangle()\fP uses the following graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWfill_style\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_\p origin\fP, and \f(CWclip_\fP \f(CWmask\fP. This function also uses these graphics context components depending on the \f(CWfill_style\fP: \f(CWforeground\fP, \f(CWbackground\fP \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, and \f(CWts_y_origin\fP. .ta 4.5n 2.75i .nf .ft CW .fi .ft R .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .Nd 5 .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .Fs .Pf amp7.eps "" "" "" "" noscale .Fe "The pixels affected by XFillRectangle versus XDrawRectangle with the same arguments" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFillRectangles" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .Na XFillRectangles \(en fill multiple rectangular areas. .Nz .SH "Synopsis" .ft CW .ta 4.5n 2.5i .nf XFillRectangles\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIgc\f(CW\^, \f(CIrectangles\f(CW\^, \f(CInrectangles\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; GC \f(CIgc\f(CW\^; XRectangle *\f(CIrectangles\f(CW\^; int \f(CInrectangles\f(CW\^; .fi .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIrectangles\fP 1i Specifies a pointer to an array of rectangles. .IP \f(CInrectangles\fP 1i Specifies the number of rectangles in the array. .SH Description \f(CWXFillRectangles()\fP fills multiple rectangular areas in the specified drawable using the graphics context. .LP The \f(CIx\fP and \f(CIy\fP coordinates of each rectangle are relative to the drawable's origin, and define the upper left corner of the rectangle. The rectangles are drawn in the order listed. For any given rectangle, no pixel is drawn more than once. If rectangles intersect, the intersecting pixels will be drawn multiple times. .LP In R4 and earlier there is a limit to the number of rectangles that can be drawn in a single call, based on the maximum request size, which varies according to the server. In R5, Xlib chops your call into as many protocol requests as required. To determine how many rectangles you can draw in a single call in R4, find out your server's maximum request size using \f(CWXMaxRequestSize()\fP. Subtract three and divide by two, and this is the maximum number of rectangles you can fill in a single \f(CWXDrawRectangles()\fP call. .LP \f(CWXFillRectangles()\fP uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWfill_style\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_\p origin\fP, and \f(CWclip_\fP \f(CWmask\fP. This function also uses these graphics context components depending on the \f(CWfill_\fP \f(CWstyle\fP: \f(CWforeground\fP, \f(CWbackground\fP, \f(CWtile\fP, \f(CWstipple\fP, \f(CWts_x_origin\fP, and \f(CWts_y_\fP \f(CWorigin\fP. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR, and Chapter\ 5, \fIThe Graphics Context\fR. .Nd 6 .SH "Structures" .Ps typedef struct { short x, y; unsigned short width, height; } XRectangle; .Pe .ne 5 .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .SH "See Also" \s-1\fIXClearArea()\fP\s+1, \s-1\fIXClearWindow()\fP\s+1, \s-1\fIXCopyArea()\fP\s+1, \s-1\fIXCopyPlane()\fP\s+1, \s-1\fIXDraw\fP\s+1, \s-1\fIXDrawArc()\fP\s+1, \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawFilled()\fP\s+1, \s-1\fIXDrawLine()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXDrawPoint()\fP\s+1, \s-1\fIXDrawPoints()\fP\s+1, \s-1\fIXDrawRectangle()\fP\s+1, \s-1\fIXDrawRectangles()\fP\s+1, \s-1\fIXDrawSegments()\fP\s+1, \s-1\fIXFillArc()\fP\s+1, \s-1\fIXFillArcs()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1, \s-1\fIXFillRectangle()\fP\s+1, \s-1\fIXFillRectangles()\fP\s+1. .Fs .Pf amp6.eps "" "" "" "" noscale .Fe "The pixels affected by XFillRectangles versus XDrawRectangles with the same arguments" .\"last line comment .TH XFillRectan.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XFillRectangle@XFillRectaA .sp .5 XFillRectangles@XFillRectaB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFilterEvent" "Xlib \- Text Input" .ds ]W Xlib Reference Manual .XX "XFilterEvent" .XX "events:filtering" .XX "filtering events" .SH Name .Na XFilterEvent \(en filter X events for an input method. .Nz .SH Synopsis .Sy Bool XFilterEvent\^(\^\f(CIevent\fP\^, \f(CIw\fP\^) .As XEvent *\f(CIevent\fP\^; Window \f(CIw\fP\^; .Ae .SH Arguments .ds Ev event to filter .IP \f(CIevent\fP 1i Specifies the \*(Ev. .ds Wi for which the filter is to be applied .IP \f(CIw\fP 1i Specifies the window \*(Wi. .SH Returns \f(CWTrue\fP if the event was filtered, else \f(CWFalse\fP. .SH Availability Release 5 and later. .SH Description \f(CWXFilterEvent()\fP passes the specified event to any event filters registered for the specified window. This allows input methods to intercept and respond to events that they are interested in. Internationalized clients should call \f(CWXFilterEvent()\fP from their event loops, generally directly after calling \f(CWXNextEvent()\fP. If \f(CWXFilterEvent()\fP returns \f(CWTrue\fP, then some input method has filtered the event, and the client should not dispatch it any further. If \f(CWXFilterEvent()\fP returns \f(CWFalse\fP, the client should continue processing it. .LP If the window argument is \f(CWNone\fP, \f(CWXFilterEvent()\fR applies the filter to the window specified in the \f(CWXEvent\fR structure. The window argument is provided so that layers above Xlib that do event redirection can indicate to which window an event has been redirected. .LP If a grab has occurred in the client, and \f(CWXFilterEvent()\fR returns \f(CWTrue\fR, the client should ungrab the keyboard. .LP Input methods register event filters using a non-public mechanism internal to Xlib. .SH "See Also" \s-1\fIXNextEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFindContext" "Xlib \- Context Manager" .ds ]W Xlib Reference Manual .SH "Name" .Na XFindContext \(en get data from the context manager (not graphics context). .Nz .SH "Synopsis" .Sy int XFindContext(\^\f(CIdisplay\f(CW, \f(CIrid\f(CW, \f(CIcontext\f(CW, \f(CIdata_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XID \f(CIrid\f(CW\^; XContext \f(CIcontext\f(CW\^; XPointer *\f(CIdata_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIrid\fP 1i Specifies the resource ID with which the data is associated. .IP \f(CIcontext\fP 1i Specifies the context type to which the data corresponds. .IP \f(CIdata_return\fP 1i Returns the data. .SH Returns \f(CWXCNOENT\fP (a non-zero error code) if the context could not be found, or zero on success. .SH Description \f(CWXFindContext()\fP gets data that has been assigned to the specified resource ID. The context manager is used to associate data with windows for use within an application. .LP This application should have called \f(CWXUniqueContext()\fP to get a unique ID, and then \f(CWXSaveContext()\fP to save the data into the array. The meaning of the data is indicated by the context ID, but is completely up to the client. .LP \f(CWXFindContext()\fP returns \f(CWXCNOENT\fP (a non-zero error code) if the context could not be found and zero (0) otherwise. .LP For more information on the context manager, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "Structures" .Ps typedef int XContext; .Pe .SH "See Also" \s-1\fIXDeleteContext()\fP\s+1, \s-1\fIXSaveContext()\fP\s+1, \s-1\fIXUniqueContext()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFlush" "Xlib \- Output Buffer" .ds ]W Xlib Reference Manual .SH "Name" .XX "Flush" .XX "servers:sending queued requests to" .Na XFlush \(en send all queued requests to the server. .Nz .SH "Synopsis" .Sy XFlush\^(\^\f(CIdisplay\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Description \f(CWXFlush()\fP sends to the server ("flushes") all requests that have been buffered but not yet sent. .LP Flushing is done automatically when input is read if no matching events are in Xlib's queue (with \f(CWXPending()\fP, \f(CWXNextEvent()\fP, or \f(CWXWindowEvent()\fP, etc.), or when a call is made that gets information from the server (such as \f(CWXQueryPointer()\fP, \f(CWXGetFontInfo\fP) so \f(CWXFlush()\fP is seldom needed. It is used when the buffer must be flushed before any of these calls are reached. .LP For more information, see Volume One, Chapter 2, \fIX Concepts\fP, and Chapter 3, \fIBasic Window Program\fR. .SH "See Also" \s-1\fIXSync()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFlushGC" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .XX "XFlushGC" .XX "graphics context:force cached changes to server" .SH "Name" .Na XFlushGC \(en force cached GC changes to the server. .Nz .\" .\" .SH "Synopsis" .Sy void XFlushGC(\f(CIdisplay\fP, \f(CIgc\fP) .As Display *\f(CIdisplay\fP; GC \f(CIgc\fP; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIgc\fP 1i Specifies the graphics context. .\" .\" .SH "Availability" Release 5 and later. .\" .\" .SH Description Xlib normally defers sending changes to the components of a GC to the server until a graphics function is actually called with that GC. This permits batching of component changes into a single server request. In some circumstances, however, it may be necessary for the client to explicitly force sending of the changes to the server. An example might be when a protocol extension uses the GC indirectly, in such a way that the extension interface cannot know what GC will be used. In a case like this, the extension library could use \f(CWXFlushGC()\fP to force any cached changes to the GC it will use to be flushed to the server. .\" .\" .SH "See Also" \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFontSetExtents" "Xlib \- Internationalized Text Output" .ds ]W Xlib Reference Manual .XX "XFontSetExtents structure" .SH Name .Na XFontSetExtents \(en XFontSetExtents structure. .Nz .SH Structures The \f(CWXFontSetExtents\fR structure contains: .Ps .TA .5i 3i .ta .5i 3i typedef struct { XRectangle max_ink_extent; /*over all drawable characters*/ XRectangle max_logical_extent; /*over all drawable characters*/ } XFontSetExtents; .Pe The \f(CWXRectangles\fR used to return font set metrics are the usual Xlib screen-oriented \f(CWXRectangles\fR, with x, y giving the upper-left corner, and width and height always positive. .LP The max_ink_extent member gives the maximum extent, over all drawable characters, of the rectangles which bound the character glyph image drawn in the foreground color, relative to a constant origin. See \f(CWXmbTextExtents\fR and \f(CWXwcTextExtents\fR for detailed semantics. .LP The max_logical_extent member gives the maximum extent, over all drawable characters, of the rectangles which specify minimum spacing to other graphical features, relative to a constant origin. Other graphical features drawn by the client, for example, a border surrounding the text, should not intersect this rectangle. The max_logical_extent member should be used to compute minimum interline spacing and the minimum area which must be allowed in a text field to draw a given number of arbitrary characters. .LP Due to context-dependent rendering, appending a given character to a string may increase the string's extent by an amount which exceeds the font's max extent: .Ps \s-1max possible added extent = (max_extent * ) \- prev_string_extent\s+1 .Pe .SH "See Also" \s-1\fIXCreateFontSet()\fP\s+1, \s-1\fIXExtentsOfFontSet()\fP\s+1, \s-1\fIXFontsOfFontSet()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFontsOfFontSet" "Xlib \- Internationalized Text Output" .ds ]W Xlib Reference Manual .XX "XFontsOfFontSet" .XX "font set:obtaining information about" .SH Name .Na XFontsOfFontSet \(en get the list of fonts used by a font set. .Nz .SH Synopsis .Sy int XFontsOfFontSet\^(\^\f(CIfont_set\fP\^, \f(CIfont_struct_list_return\fP\^, \f(CIfont_name_list_return\fP\^) .As XFontSet \f(CIfont_set\fP\^; XFontStruct ***\f(CIfont_struct_list_return\fP\^; char ***\f(CIfont_name_list_return\fP\^; .Ae .SH Arguments .IP \f(CIfont_set\fP 1i Specifies the font set. .IP \f(CIfont_struct_list_return\fP 1i Returns the list of font structs. .IP \f(CIfont_name_list_return\fP 1i Returns the list of font names. .SH Returns The number of fonts in the list (which is also the number of elements in the lists of structures). .SH Availability Release 5 and later. .SH Description \f(CWXFontsOfFontSet()\fR returns a list of one or more \f(CWXFontStructs\fR and font names for the fonts used by the given font set. A list of pointers to the \f(CWXFontStruct\fR structures is returned to \f(CIfont_struct_list_return\fP. A list of pointers to \f(CWNULL\fP-terminated, fully specified, font name strings in the locale of the font set is returned to \f(CIfont_name_list_return\fP. The number of elements in each array is returned as the value of the function. The arrays are in the same order, and their elements correspond to one another. .LP Because it is not guaranteed that a given character will be imaged using a single font glyph, there is no provision for mapping a character or default string to the font properties, font ID, or direction hint for the font for the character. The client may access the \f(CWXFontStruct\fR list to obtain these values for all the fonts currently in use. .LP It is not required that fonts be loaded from the server at the creation of an \f(CWXFontSet\fR. Xlib may choose to cache font data, loading it only as needed to draw text or compute text dimensions. Therefore, existence of the per-char metrics in the \f(CWXFontStruct\fR structures in the \f(CWXFontStructSet\fR is undefined. .ne 2 Also, note that all properties in the \f(CWXFontStruct\fR structures are in the STRING encoding. .LP The \f(CWXFontStruct\fR and font name lists are owned by Xlib and should not be modified or freed by the client. They will be freed by a call to \f(CWXFreeFontSet()\fR on the associated \f(CWXFontSet\fR. Until freed, their contents will not be modified by Xlib. .Nd 20 .SH "See Also" \s-1\fIXCreateFontSet()\fP\s+1, \s-1\fIXExtentsOfFontSet()\fP\s+1, \s-1\fIXBaseFontNameListOfFontSet()\fP\s+1, \s-1\fIXLocaleOfFontSet()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XForceScreenSaver" "Xlib \- Screen Saver" .ds ]W Xlib Reference Manual .SH "Name" .XX "XForceScreenSaver" .XX "screen savers:turning on and off" .Na XForceScreenSaver \(en turn the screen saver on or off. .Nz .SH "Synopsis" .Sy XForceScreenSaver\^(\^\f(CIdisplay\f(CW\^, \f(CImode\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int \f(CImode\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CImode\fP 1i Specifies whether the screen saver is active or reset. The possible modes are: \f(CWScreenSaverActive\fP or \f(CWScreenSaverReset\fP. .SH Description \f(CWXForceScreenSaver()\fP resets or activates the screen saver. .LP If the specified mode is \f(CWScreenSaverActive\fP and the screen saver currently is disabled, the screen saver is activated, even if the screen saver had been disabled by calling \f(CWXSetScreenSaver()\fP with a timeout of zero (0). This means that the screen may go blank or have some random change take place to save the phosphors. .LP If the specified mode is \f(CWScreenSaverReset\fP and the screen saver currently is enabled, the screen is returned to normal, the screen saver is deactivated and the activation timer is reset to its initial state (as if device input had been received). \f(CWExpose\fP events may be generated on all visible windows if the server cannot save the entire screen contents. .LP For more information on the screen saver, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "Errors" \f(CWBadValue\fP .SH "See Also" \s-1\fIXActivateScreenSaver()\fP\s+1, \s-1\fIXGetScreenSaver()\fP\s+1, \s-1\fIXResetScreenSaver()\fP\s+1, \s-1\fIXSetScreenSaver()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFree" "Xlib \- HouseKeeping" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XFree" .XX "memory:freeing Xlib-allocated" XFree \(en free specified memory allocated by an Xlib function. .Nz .SH "Synopsis" .Sy XFree\^(\^\f(CIdata\f(CW\^) .As void \f(CI*data\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdata\fP 1i Specifies a pointer to the data that is to be freed. .SH Description \f(CWXFree()\fP is a general purpose routine for freeing memory allocated by Xlib calls. You must use it to free any objects that were allocated by Xlib, unless an alternate function is explicitly specified for the object. .SH "See Also" \s-1\fIXDefaultScreen()\fP\s+1, \s-1\fIXCloseDisplay()\fP\s+1, \s-1\fIXNoOp()\fP\s+1, \s-1\fIXOpenDisplay()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFreeColormap" "Xlib \- Colormaps" .ds ]W Xlib Reference Manual .SH "Name" .XX "XFreeColormap" .XX "colormaps:deleting" .XX "colormaps:default" .Na XFreeColormap \(en delete a colormap and install the default colormap. .Nz .SH "Synopsis" .Sy XFreeColormap\^(\^\f(CIdisplay\f(CW, \f(CIcolormap\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcolormap\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcolormap\fP 1i Specifies the colormap to delete. .SH Description \f(CWXFreeColormap()\fP destroys the specified colormap, unless it is the default colormap for a screen. That is, it not only uninstalls \f(CIcolormap\fP from the hardware colormap if it is installed, but also frees the associated memory including the colormap ID. .LP \f(CWXFreeColormap()\fP performs the following processing: .IP \(bu 3n If \f(CIcolormap\fP is an installed map for a screen, it uninstalls the colormap (see \f(CWXUninstallColormap()\fP). .IP \(bu 3n If \f(CIcolormap\fP is defined as the colormap attribute for a window (by \f(CWXCreateWindow()\fP or \f(CWXChangeWindowAttributes()\fP), it changes the colormap attribute for the window to the constant \f(CWNone\fP, generates a \f(CWColormapNotify\fP event, and frees the colormap. The colors displayed with a colormap of \f(CWNone\fP are server-dependent, since the default colormap is normally used. .LP For more information, see Volume One, Chapter 7, \fIColor\fR. .SH "Errors" .IP "\f(CWBadColor\fP" 1i Invalid colormap. .SH "See Also" \s-1\fIXDefaultColormap()\fP\s+1, \s-1\fIXDisplayCells()\fP\s+1, \s-1\fIXCopyColormapAndFree()\fP\s+1, \s-1\fIXCreateColormap()\fP\s+1, \s-1\fIXGetStandardColormap()\fP\s+1, \s-1\fIXInstallColormap()\fP\s+1, \s-1\fIXListInstalledColormaps()\fP\s+1, \s-1\fIXSetStandardColormap()\fP\s+1, \s-1\fIXSetWindowColormap()\fP\s+1, \s-1\fIXUninstallColormap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFreeColors" "Xlib \- Color Cells" .ds ]W Xlib Reference Manual .SH "Name" .XX "XFreeColors" .XX "colormaps:freeing cells or planes" .Na XFreeColors \(en free colormap cells or planes. .Nz .SH "Synopsis" .Sy XFreeColors\^(\^\f(CIdisplay\f(CW, \f(CIcolormap\f(CW\^, \f(CIpixels\f(CW\^, \f(CInpixels\f(CW\^, \f(CIplanes\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcolormap\f(CW\^; unsigned long \f(CIpixels[]\f(CW\^; int \f(CInpixels\f(CW\^; unsigned long \f(CIplanes\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcolormap\fP 1i Specifies the colormap. .IP \f(CIpixels\fP 1i Specifies an array of pixel values. .IP \f(CInpixels\fP 1i Specifies the number of pixels. .IP \f(CIplanes\fP 1i Specifies the planes you want to free. .SH Description \f(CWXFreeColors()\fP frees the cells whose values are computed by ORing together subsets of the \f(CIplanes\fP argument with each pixel value in the \f(CIpixels\fP array. .LP If the cells are read/write, they become available for reuse, unless they were allocated with \f(CWXAllocColorPlanes()\fP, in which case all the related pixels may need to be freed before any become available. .LP If the cells were read-only, they become available only if this is the last client to have allocated those shared cells. .LP For more information, see Volume One, Chapter 7, \fIColor\fR. .SH "Errors" .IP "\f(CWBadAccess\fP" 1i Attempt to free a colorcell not allocated by this client (either unallocated or allocated by another client). .IP "\f(CWBadColor\fP" \f(CWcolormap\fR is invalid. .IP "\f(CWBadValue\fP" A pixel value is not a valid index into \f(CIcolormap\fP. .LP Note: if more than one pixel value is in error, the one reported is arbitrary. .Nd 5 .SH "See Also" \s-1\fIXBlackPixel()\fP\s+1, \s-1\fIXWhitePixel()\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocColorCells()\fP\s+1, \s-1\fIXAllocColorPlanes()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXLookupColor()\fP\s+1, \s-1\fIXParseColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1, \s-1\fIXStoreNamedColor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFreeCursor" "Xlib \- Cursors" .ds ]W Xlib Reference Manual .SH "Name" .XX "XFreeCursor" .XX "cursors:freeing" .Na XFreeCursor \(en release a cursor. .Nz .SH "Synopsis" .Sy XFreeCursor\^(\^\f(CIdisplay\f(CW, \f(CIcursor\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Cursor \f(CIcursor\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcursor\fP 1i Specifies the ID of the cursor to be affected. .SH Description \f(CWXFreeCursor()\fP deletes the association between the cursor ID and the specified cursor. The cursor storage is freed when all other clients have freed it. Windows with their cursor attribute set to this cursor will have this attribute set to \f(CWNone\fP (which implies \f(CWCopyFromParent\fP). The specified cursor ID should not be referred to again. .SH "Errors" \f(CWBadCursor\fP .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXCreateGlyphCursor()\fP\s+1, \s-1\fIXCreatePixmapCursor()\fP\s+1, \s-1\fIXDefineCursor()\fP\s+1, \s-1\fIXQueryBestCursor()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXRecolorCursor()\fP\s+1, \s-1\fIXUndefineCursor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFreeExtensionList" "Xlib \- Extensions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XFreeExtensionList" .XX "memory:freeing for extension list" .Na XFreeExtensionList \(en free memory allocated for a list of installed extensions. .Nz .SH "Synopsis" .Sy XFreeExtensionList(\^\f(CIlist\f(CW\^) .As char **\f(CIlist\f(CW\^; .Ae .SH "Arguments" .IP \f(CIlist\fP 1i Specifies a pointer to the list of extensions returned from \f(CWXListExtensions()\fP. .SH Description .XX "extensions:lists, freeing" \f(CWXFreeExtensionList()\fP frees the memory allocated by \f(CWXListExtensions()\fP. .LP For more information, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "See Also" \s-1\fIXListExtensions()\fP\s+1, \s-1\fIXQueryExtension()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFreeFont" "Xlib \- Fonts" .ds ]W Xlib Reference Manual .SH "Name" .XX "XFreeFont" .XX "fonts:freeing" .Na XFreeFont \(en unload a font and free storage for the font structure. .Nz .SH "Synopsis" .Sy XFreeFont\^(\^\f(CIdisplay\f(CW, \f(CIfont_struct\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XFontStruct *\f(CIfont_struct\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIfont_struct\fP 1i Specifies the storage associated with the font. .SH Description \f(CWXFreeFont()\fP frees the memory allocated for the \f(CIfont_struct\fP font information structure (\f(CWXFontStruct\fP) filled by \f(CWXQueryFont()\fP or \f(CWXLoadQueryFont()\fP. \f(CWXFreeFont()\fP frees all storage associated with the \f(CIfont_struct\fP argument. Neither the data nor the font should be referenced again. .LP The server unloads and frees the font itself if no other client has loaded it. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" .Ps .ta 4.5n 2.25i typedef struct { XExtData *ext_data; /* hook for extension to hang data */ Font fid; /* Font ID for this font */ unsigned direction; /* hint about direction the font is painted */ unsigned min_char_or_byte2; /* first character */ unsigned max_char_or_byte2; /* last character */ unsigned min_byte1; /* first row that exists */ unsigned max_byte1; /* last row that exists */ Bool all_chars_exist; /* flag if all characters have non-zero size*/ unsigned default_char; /* char to print for undefined character */ int n_properties; /* how many properties there are */ XFontProp *properties; /* pointer to array of additional properties*/ XCharStruct min_bounds; /* minimum bounds over all existing char*/ XCharStruct max_bounds; /* maximum bounds over all existing char*/ XCharStruct *per_char; /* first_char to last_char information */ int ascent; /* logical extent above baseline for spacing */ int descent; /* logical descent below baseline for spacing */ } XFontStruct; .XX "XFontStruct structure" .XX "structures:XFontStruct" .Pe .Nd 12 .SH "Errors" \f(CWBadFont\fP .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXFreeFontInfo()\fP\s+1, \s-1\fIXFreeFontNames()\fP\s+1, \s-1\fIXFreeFontPath()\fP\s+1, \s-1\fIXGetFontPath()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXListFonts()\fP\s+1, \s-1\fIXListFontsWithInfo()\fP\s+1, \s-1\fIXLoadFont()\fP\s+1, \s-1\fIXLoadQueryFont()\fP\s+1, \s-1\fIXQueryFont()\fP\s+1, \s-1\fIXSetFont()\fP\s+1, \s-1\fIXSetFontPath()\fP\s+1, \s-1\fIXUnloadFont()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFreeFontInfo" "Xlib \- Fonts" .ds ]W Xlib Reference Manual .SH "Name" .XX "XFreeFontInfo" .XX "XListFontsWithInfo:freeing memory allocated by" .XX "XListFontsWithInfo:freeing memory allocated by" .Na XFreeFontInfo \(en free the memory allocated by \f(CWXListFontsWithInfo\fP. .Nz .SH "Synopsis" .Sy XFreeFontInfo(\^\f(CInames\f(CW, \f(CIinfo\f(CW, \f(CIactual_count\f(CW\^) .As char **\f(CInames\f(CW\^; XFontStruct *\f(CIinfo\f(CW; int \f(CIactual_count\f(CW\^; .Ae .SH "Arguments" .IP \f(CInames\fP 1i Specifies a pointer to the list of font names that were returned by \f(CWXListFontsWithInfo()\fP. .IP \f(CIinfo\fP 1i Specifies a pointer to the list of font information that was returned by \f(CWXListFontsWithInfo()\fP. .IP \f(CIactual_count\fP 1i Specifies the number of matched font names returned by \f(CWXListFontsWithInfo()\fP. .SH Description \f(CWXFreeFontInfo()\fP frees the list of font information structures allocated by \f(CWXListFontsWithInfo()\fP. It does not unload the specified fonts themselves. To free an \f(CWXFontStruct\fR structure without closing the font, call \f(CWXFreeFontInfo()\fR with the names argument specified as \f(CWNULL\fR. .SH "Structures" .Ps .ta 4.5n 2.25i typedef struct { XExtData *ext_data; /* hook for extension to hang data */ Font fid; /* Font ID for this font */ unsigned direction; /* hint about direction the font is painted */ unsigned min_char_or_byte2; /* first character */ unsigned max_char_or_byte2; /* last character */ unsigned min_byte1; /* first row that exists */ unsigned max_byte1; /* last row that exists */ Bool all_chars_exist; /* flag if all characters have non-zero size */ unsigned default_char; /* char to print for undefined character */ int n_properties; /* how many properties there are */ XFontProp *properties; /* pointer to array of additional properties */ XCharStruct min_bounds; /* minimum bounds over all existing char */ XCharStruct max_bounds; /* maximum bounds over all existing char */ XCharStruct *per_char; /* first_char to last_char information */ int ascent; /* logical extent above baseline for spacing */ int descent; /* logical descent below baseline for spacing */ } XFontStruct; .Pe .Nd 5 .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXFreeFont()\fP\s+1, \s-1\fIXFreeFontNames()\fP\s+1, \s-1\fIXGetFontPath()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXListFonts()\fP\s+1, \s-1\fIXListFontsWithInfo()\fP\s+1, \s-1\fIXLoadFont()\fP\s+1, \s-1\fIXLoadQueryFont()\fP\s+1, \s-1\fIXQueryFont()\fP\s+1, \s-1\fIXSetFont()\fP\s+1, \s-1\fIXSetFontPath()\fP\s+1, \s-1\fIXUnloadFont()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFreeFontNames" "Xlib \- Fonts" .ds ]W Xlib Reference Manual .SH "Name" .XX "XFreeFontNames" .XX "XListFonts:freeing memory allocated by" .XX "font names:freeing" .Na XFreeFontNames \(en free the memory allocated for a font name array. .Nz .SH "Synopsis" .Sy XFreeFontNames\^(\^\f(CIlist\f(CW\^) .As char *\f(CIlist\f(CW\^[\^]\^; .Ae .SH "Arguments" .IP \f(CIlist\fP 1i Specifies the array of font name strings to be freed. .SH Description \f(CWXFreeFontNames()\fP frees the array of strings returned by \f(CWXListFonts()\fP or \f(CWXListFontsWithInfo()\fP. .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXFreeFont()\fP\s+1, \s-1\fIXFreeFontInfo()\fP\s+1, \s-1\fIXFreeFontPath()\fP\s+1, \s-1\fIXGetFontPath()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXListFonts()\fP\s+1, \s-1\fIXListFontsWithInfo()\fP\s+1, \s-1\fIXLoadFont()\fP\s+1, \s-1\fIXLoadQueryFont()\fP\s+1, \s-1\fIXQueryFont()\fP\s+1, \s-1\fIXSetFont()\fP\s+1, \s-1\fIXSetFontPath()\fP\s+1, \s-1\fIXUnloadFont()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFreeFontPath" "Xlib \- Fonts" .ds ]W Xlib Reference Manual .SH "Name" .XX "XFreeFontPath" .XX "XGetFontPath:freeing memory allocated by" .XX "font path:freeing" .Na XFreeFontPath \(en free the memory allocated by \f(CWXGetFontPath\fP. .Nz .SH "Synopsis" .Sy XFreeFontPath\^(\^\f(CIlist\f(CW\^) .As char **\f(CIlist\f(CW\^; .LP .Ae .SH "Arguments" .IP \f(CIlist\fP 1i Specifies an array of strings allocated by \f(CWXGetFontPath()\fP. .SH Description \f(CWXFreeFontPath()\fP frees the array of pathnames returned by \f(CWXGetFontPath()\fP. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXFreeFont()\fP\s+1, \s-1\fIXFreeFontInfo()\fP\s+1, \s-1\fIXFreeFontNames()\fP\s+1, \s-1\fIXGetFontPath()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXListFonts()\fP\s+1, \s-1\fIXListFontsWithInfo()\fP\s+1, \s-1\fIXLoadFont()\fP\s+1, \s-1\fIXLoadQueryFont()\fP\s+1, \s-1\fIXQueryFont()\fP\s+1, \s-1\fIXSetFont()\fP\s+1, \s-1\fIXSetFontPath()\fP\s+1, \s-1\fIXUnloadFont()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFreeFontSet" "Xlib \- Internationalized Text Output" .ds ]W Xlib Reference Manual .XX "XFreeFontSet" .XX "font set:freeing" .SH Name .Na XFreeFontSet \(en free a font set. .Nz .SH Synopsis .Sy void XFreeFontSet\^(\^\f(CIdisplay\fP\^, \f(CIfont_set\fP\^) .As Display *\f(CIdisplay\fP\^; XFontSet \f(CIfont_set\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIfont_set\fP 1i Specifies the font set. .SH Availability Release 5 and later. .SH Description \f(CWXFreeFontSet()\fR frees the specified font set. The associated base font name list, font name list, \f(CWXFontStruct\fR list, and \f(CWXFontSetExtents()\fR, if any, are freed. .SH "See Also" \s-1\fIXExtentsofFontSet\fP\s+1, \s-1\fIXFontsOfFontSet()\fP\s+1, \s-1\fIXCreateFontSet()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFreeGC" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XFreeGC" .XX "graphics context:freeing" .Na XFreeGC \(en free a graphics context. .Nz .SH "Synopsis" .Sy XFreeGC\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1i Specifies the graphics context to be freed. .Nd 10 .SH Description \&\f(CWXFreeGC()\fP frees all memory associated with a graphics context, and removes the GC from the server and display hardware. .ta 4.5n 2.75i .nf .ft CW .fi .ft R .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .SH "Errors" \f(CWBadGC\fP .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFreeModifiermap" "Xlib \- Keyboard" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XFreeModifiermap" .XX "keyboard modifier mapping structure:freeing" XFreeModifiermap \(en destroy and free a keyboard modifier mapping structure. .Nz .SH "Synopsis" .Sy XFreeModifiermap(\^\f(CImodmap\f(CW\^) .As XModifierKeymap *\f(CImodmap\f(CW; .Ae .SH "Arguments" .IP \f(CImodmap\fP 1i Specifies a pointer to the \f(CWXModifierKeymap()\fP structure to be freed. .SH Description .XX "XModifierKeymap structure:freeing" \f(CWXFreeModifiermap()\fP frees an \f(CWXModifierKeymap()\fP structure originally allocated by \f(CWXNewModifierMap\fP or \f(CWXGetModifierMapping()\fP. .LP For more information, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "Structures" .Ps typedef struct { int max_keypermod; /* server's max number of keys per modifier */ KeyCode *modifiermap; /* an 8 by \f(CImax_keypermod\fP array of * keycodes to be used as modifiers */ } XModifierKeymap; .Pe .SH "See Also" \s-1\fIXChangeKeyboardMapping()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifierMap\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeySym\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFreePixmap" "Xlib \- Pixmaps and Tiles" .ds ]W Xlib Reference Manual .SH "Name" .XX "pixmaps:freeing" .XX "XFreePixmap" .Na XFreePixmap \(en free a pixmap ID. .Nz .SH "Synopsis" .Sy XFreePixmap\^(\^\f(CIdisplay\f(CW, \f(CIpixmap\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Pixmap \f(CIpixmap\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIpixmap\fP 1i Specifies the pixmap whose ID should be freed. .SH Description \f(CWXFreePixmap()\fR disassociates a pixmap ID from its resource. If no other client has an ID for that resource, it is freed by the server. The \f(CWPixmap\fP should never be referenced again by this client. If it is, the ID will be unknown and a \f(CWBadPixmap\fP error will result. .SH "Errors" \f(CWBadPixmap\fP .SH "See Also" \s-1\fIXCreateBitmapFromData()\fP\s+1, \s-1\fIXCreatePixmap()\fP\s+1, \s-1\fIXCreatePixmapFromBitmapData()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXQueryBestStipple()\fP\s+1, \s-1\fIXQueryBestTile()\fP\s+1, \s-1\fIXReadBitmapFile()\fP\s+1, \s-1\fIXSetTile()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1, \s-1\fIXWriteBitmapFile()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XFreeStringList" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XFreeStringList" .XX "string lists:freeing" .Na XFreeStringList \(en free the in-memory data associated with the specified string list. .Nz .SH "Synopsis" .Sy void XFreeStringList\^(\^\f(CIlist\fP\^) .As char **\f(CIlist\fP\^; .Ae .SH "Arguments" .IP \f(CIlist\fP 1i Specifies the list of strings to be freed. .SH "Availability" Release 4 and later. .SH Description .LP \f(CWXFreeStringList()\fR releases memory allocated by \f(CWXTextPropertyToStringList()\fR, \f(CWXmbTextPropertyToTextList()\fR, and the missing charset allocated by \f(CWXCreateFontSet()\fR. .SH "See Also" \s-1\fIXGetTextProperty()\fP\s+1, \s-1\fIXSetTextProperty()\fP\s+1, \s-1\fIXStringListToTextProperty()\fP\s+1, \s-1\fIXTextPropertytoStringList\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGContextFromGC" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XGContextFromGC" .XX "graphics context:resource ID, obtaining" XGContextFromGC \- obtain the \f(CWGContext\fP (resource ID) associated with the specified graphics context. .Nz .SH "Synopsis" .Sy GContext XGContextFromGC\^(\^\f(CIgc\f(CW\^) .As GC \f(CIgc\f(CW\^; .Ae .SH "Arguments" .IP \f(CIgc\fP 1i Specifies the graphics context of the desired resource ID. .SH Returns The \f(CWGContext\fP. .SH Description .XX "resource IDs:extracting from GC structure" \f(CWXGContextFromGC()\fP extracts the resource ID from the GC structure. The GC structure is Xlib's local cache of GC values and contains a field for the \f(CWGContext\fP ID. This function is essentially a macro that accesses this field, since the GC structure is intended to be opaque. .LP A \f(CWGContext\fP is needed to set a field of the \f(CWXVisualInfo\fP structure prior to calling \f(CWXGetVisualInfo()\fP. .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGeometry" "Xlib \- Standard Geometry" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGeometry" .XX "geometry:calculating window" .XX "windows:calculating geometry of" .Na XGeometry \(en calculate window geometry given user geometry string and default geometry. .Nz .SH "Synopsis" .Sy int XGeometry\^(\^\f(CIdisplay\f(CW\^, \f(CIscreen\f(CW\^, \f(CIposition\f(CW\^, \f(CIdefault_position\f(CW\^, \f(CIbwidth\f(CW\^, \f(CIfwidth\f(CW\^, \f(CIfheight\f(CW\^, \f(CIxadder\f(CW\^, \f(CIyadder\f(CW\^, \f(CIx_return\f(CW\^, \f(CIy_return\f(CW\^, \f(CIheight_return\f(CW\^, \f(CIwidth_return\f(CW\^, \f(CIheight_return\f(CW\^) .As Display *display; int screen; char *\f(CIposition\f(CW\^, *\f(CIdefault_position\f(CW\^; unsigned int \f(CIbwidth\f(CW\^; unsigned int \f(CIfwidth\f(CW\^, \f(CIfheight\f(CW\^; int \f(CIxadder\f(CW\^, \f(CIyadder\f(CW\^; int *\f(CIx_return\f(CW\^, *\f(CIy_return\f(CW\^, *\f(CIwidth_return\f(CW\^, *\f(CIheight_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.2i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIscreen\fP Specifies which screen the window is on. .IP \f(CIposition\fP 1.2i Specifies the user- or program-supplied geometry string, perhaps incomplete. .IP \f(CIdefault_position\fP 1.2i Specifies the default geometry string and must be complete. .IP \f(CIbwidth\fP 1.2i Specifies the border width. .IP \f(CIfheight\fP 1.2i .br .ns .IP \f(CIfwidth\fP 1.2i .sp -2 Specify the font height and width in pixels (increment size). .sp .IP \f(CIxadder\fP 1.2i .br .ns .IP \f(CIyadder\fP 1.2i .sp -2 Specify additional interior padding in pixels needed in the window. .sp .IP \f(CIx_return\fP 1.2i .br .ns .IP \f(CIy_return\fP 1.2i .sp -2 Return the user-specified or default coordinates of the window. .sp .IP \f(CIwidth_return\fP 1.2i .br .ns .IP \f(CIheight_return\fP 1.2i .sp -2 Return the window dimensions in pixels. .sp .SH Returns A bitmask composed of the symbols \f(CWXValue\fP, \f(CWYValue\fP, \f(CWWidthValue\fP, \f(CWHeightValue\fP, \f(CWXNegative\fP, and/or \f(CWYNegative\fP. .Nd 10 .SH Description .XX "XWMGeometry:and XGeometry" \f(CWXGeometry\fP has been superseded by \f(CWXWMGeometry\fP as of Release 4. .LP \f(CWXGeometry\fP returns the position and size of a window given a user-supplied geometry (allowed to be partial) and a default geometry. Each user-supplied specification is copied into the appropriate returned argument, unless it is not present, in which case the default specification is used. The default geometry should be complete while the user-supplied one may not be. .LP .ne 3 \f(CWXGeometry\fP is useful for processing command-line options and user preferences. These geometry strings are of the form: .sp .5 .ti +4.5n \s9\f(CW=<\f(CIwidth\fP>x<\f(CIheight\fP>{+-}<\f(CIxoffset\fP>{+-}<\f(CIyoffset\fP>\s0 .sp .5 .Nd 3 \fRThe "=" at the beginning of the string is now optional. (Items enclosed in <\^> are integers, and items enclosed in {\^} are a set from which one item is to be chosen. Note that the brackets should not appear in the actual string.) .LP The \f(CWXGeometry\fP return value is a bitmask that indicates which values were present in \f(CIuser_position\fP. This bitmask is composed of the exclusive OR of the symbols \f(CWXValue\fP, \f(CWYValue\fP, \f(CWWidthValue\fP, \f(CWHeightValue\fP, \f(CWXNegative\fP, or \f(CWYNegative\fP. .LP If the function returns either \f(CWXValue\fR or \f(CWYValue\fR, you should place the window at the requested position. The border width (\f(CIbwidth\fR), size of the width and height increments (typically \f(CIfwidth\fP and \f(CIfheight\fP), and any additional interior space (\f(CIxadder\fP and \f(CIyadder\fP) are passed in to make it easy to compute the resulting size. .SH "See Also" \s-1\fIXParseGeometry()\fP\s+1, \s-1\fIXTranslateCoordinates()\fP\s+1, \s-1\fIXWMGeometry\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetAtomName" "Xlib \- Properties" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetAtomName" .XX "atoms:and string names" .Na XGetAtomName \(en get a string name for a property given its atom. .Nz .SH "Synopsis" .Sy char *XGetAtomName\^(\^\f(CIdisplay\f(CW, \f(CIatom\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Atom \f(CIatom\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIatom\fP 1i Specifies the atom whose string name you want returned. .SH Returns The atom name string. .SH Description .XX "string names:and atoms" An atom is a number identifying a property. Properties also have a string name. \f(CWXGetAtomName()\fP returns the string name that was specified in the original call to \f(CWXInternAtom()\fP that returned this atom, or, for predefined atoms, a string version of the symbolic constant without the XA_ is returned. If the data returned by the server is in the Latin Portable Character Encoding, then the returned string is in the Host Portable Character Encoding. Otherwise, the result is implementation-dependent. If the specified atom is not defined, \f(CWXGetAtomName()\fR returns \f(CWNULL\fR, and generates a \f(CWBadAtom\fP error. .LP For example, \f(CWXGetAtomName()\fP returns \f(CW"XA_WM_CLASS"\fP (a string) when passed the predefined atom \f(CWXA_WM_CLASS\fP (a defined constant). .LP You should free the resulting string with \f(CWXFree()\fR when it is no longer needed. .LP \f(CWXInternAtom()\fP performs the inverse function, returning the atom given the string. .SH "Errors" \f(CWBadAtom\fP .SH "See Also" \s-1\fIXChangeProperty()\fP\s+1, \s-1\fIXDeleteProperty()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXGetWindowProperty()\fP\s+1, \s-1\fIXInternAtom()\fP\s+1, \s-1\fIXListProperties()\fP\s+1, \s-1\fIXRotateWindowProperties()\fP\s+1, \s-1\fIXSetStandardProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetClassHint" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XGetClassHint" .XX "XA_WM_CLASS property" .XX "window manager:XA_WM_CLASS property" XGetClassHint \(en get the \f(CWXA_WM_CLASS\fP property of a window. .Nz .SH "Synopsis" .Sy Status XGetClassHint\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIclass_hints_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW; XClassHint *\f(CIclass_hints_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window for which the property is desired. .IP \f(CIclass_hints_return\fP 1i Returns the \f(CWXClassHint\fP structure. .SH Returns Zero on failure, non-zero on success. .SH Description \f(CWXGetClassHint()\fP obtains the \f(CWXA_WM_CLASS\fP property for the specified window. This property stores the resource class and instance name, that the window manager uses to get any resource settings that may control how the window manager manages the application that set this property. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the result is implementation-dependent. \f(CWXGetClassHint()\fP returns a \f(CWStatus\fP of zero on failure, non-zero on success. .LP The \f(CWXClassHint\fP structure returned contains \f(CWres_class\fP, which is the name of the client such as "emacs", and \f(CWres_name\fP, which should be the first of the following that applies: .IP \(bu 3n Command-line option (\fI\-rn name\fR) .IP \(bu 3n A specific environment variable (e.g., RESOURCE_NAME) .IP \(bu 3n The trailing component of \f(CWargv\^[\^0\^]\fR (after the last /\^\^) .LP To free \f(CWres_name\fP and \f(CWres_class\fP when finished with the strings, use \f(CWXFree()\fP. .LP For more information on using hints, see Volume One, Chapter 12, \fIInterclient Communication\fR. .Nd 5 .SH "Structures" .Ps typedef struct { char *res_name; char *res_class; } XClassHint; .Pe .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXAllocClassHint()\fP\s+1, \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .\".so footer.macro .ds ]W Xlib Reference Manual .RH "XGetCommand" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .XX "XGetCommand" .XX "XA_WM_COMMAND property" .SH "Name" .Na XGetCommand \(en get the \f(CWXA_WM_COMMAND\fP property (command-line arguments). .Nz .Nz .SH "Synopsis" .Sy Status XGetCommand\^(\^\f(CIdisplay\fP, \f(CIw\fP, \f(CIargv_return\fP, \ \f(CIargc_return\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; char ***\f(CIargv_return\fP\^; int *\f(CIargc_return\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window. .IP \f(CIargv_return\fP 1i Returns the application's argument list. .IP \f(CIargc_return\fP 1i Returns the number of arguments returned. .SH Returns Zero on failure, non-zero on success. .SH Description \f(CWXGetCommand()\fP reads the \f(CWXA_WM_COMMAND\fP property from the specified window and returns a string list. If the \f(CWXA_WM_COMMAND\fP property exists, it is of type \f(CWXA_STRING\fP and format 8. If sufficient memory can be allocated to contain the string list, \f(CWXGetCommand()\fP fills in the \f(CIargv_return\fP and \f(CIargc_return\fP arguments and returns a non-zero status. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the result is implementation-dependent. Otherwise, it returns a zero status. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the result is implementation-dependent. To free the memory allocated to the string list, use \f(CWXFreeStringList()\fP. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetDefault" "Xlib \- User Preferences" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetDefault" .XX "option values:extracting from databases" .XX "resource databases:extracting option values from" .Na XGetDefault \(en extract an option value from the resource database. .Nz .SH "Synopsis" .Sy char *XGetDefault\^(\^\f(CIdisplay\f(CW, \f(CIprogram\f(CW\^, \f(CIoption\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; char *\f(CIprogram\f(CW\^; char *\f(CIoption\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIprogram\fP Specifies the program name to be looked for in the resource database. The program name is usually \f(CWargv\^[\^0\^]\fP, the first argument on the UNIX command line. .IP \f(CIoption\fP Specifies the option name or keyword. Lines containing both the \f(CIprogram\fP name and the \f(CIoption\fP name, separated only by a period or asterisk, will be matched. .SH Returns The resource value. .SH Description \f(CWXGetDefault()\fP returns a character string containing the user's default value for the specified \f(CIprogram\fP name and \f(CIoption\fP name. \f(CWXGetDefault()\fP returns \f(CWNULL\fP if no key can be found that matches \&\f(CIoption\fP and \&\f(CIprogram\fP. For a description of the matching rules, see \&\f(CWXrmGetResource()\fP. .LP The strings returned by \f(CWXGetDefault()\fP are owned by Xlib and should not be modified or freed by the client. .LP Lines in the user's resource database look like this: .LP .in +4.5n .ft CW .nf .ps 9 .vs 11 .font sans12b xterm.foreground: #c0c0ff xterm.geometry: =81x28 xterm.saveLines: 256 xterm.font: 8x13 xterm.keyMapFile: /usr/black/.keymap xterm.activeIcon: on xmh.header.font 9x15 .ps .vs .in -4.5n .fi .ft R .LP The portion on the left is known as a key; the portion on the right is the value. Uppercase or lowercase is important in keys. The convention is to capitalize only the second and successive words in each option, if any. .LP Resource specifications are usually loaded into the \f(CWXA_RESOURCE_MANAGER\fP property on the root window at login. If no such property exists, a resource file in the user's home directory is loaded. On a UNIX-based system, this file is \fI$HOME/.Xdefaults\fR. After loading these defaults, \f(CWXGetDefault()\fR merges additional defaults specified by the XENVIRONMENT environment variable. If XENVIRONMENT is defined, it contains a full path name for the additional resource file. If XENVIRONMENT is not defined, \f(CWXGetDefault()\fR looks for \fI$HOME/.Xdefaults-\fRname, where \fIname\fP specifies the name of the machine on which the application is running. .LP The first invocation of \f(CWXGetDefault()\fP reads and merges the various resource files into Xlib so that subsequent requests are fast. Therefore, changes to the resource files from the program will not be felt until the next invocation of the application. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "See Also" \s-1\fIXAutoRepeatOff()\fP\s+1, \s-1\fIXAutoRepeatOn()\fP\s+1, \s-1\fIXBell()\fP\s+1, \s-1\fIXChangeKeyboardControl()\fP\s+1, \s-1\fIXGetKeyboardControl()\fP\s+1, \s-1\fIXGetPointerControl()\fP\s+1. .\"last line comment .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XGetDvMo.man,v 1.5 94/06/04 17:32:24 rws Exp $ .ds xL Programming with Xlib .TH XGetDeviceMotionEvents 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XGetDeviceMotionEvents, XDeviceTimeCoord \- get device motion history .SH SYNTAX XDeviceTimeCoord *XGetDeviceMotionEvents\^(\fIdisplay\fP\^, \fIdevice\fP\^, \fIstart\fP\^, \fIstop\fP\^, .br \fInevents_return\fP\^, \fImode_return\fP\^, \fIaxis_count_return\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br Time \fIstart\fP\^, \fIstop\fP\^; .br int *\fInevents_return\fP\^; .br int *\fImode_return\fP\^; .br int *\fIaxis_count_return\fP\^; .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device whose motion history is to be queried. .TP 12 .I start .br .ns .TP 12 .I stop Specify the time interval in which the events are returned from the motion history buffer. You can pass a timestamp or \fICurrentTime\fP. .TP 12 .I nevents_return Returns the number of events from the motion history buffer. .TP 12 .I mode_return Returns the mode of the device (\fIAbsolute\fP or \fIRelative\fP). .TP 12 .I axis_count_return Returns the count of axes being reported. .SH DESCRIPTION The server may retain the recent history of the device motion and do so to a finer granularity than is reported by \fIDeviceMotionNotify\fP events. The \fIXGetDeviceMotionEvents\fP request makes this history available. .LP The \fIXGetDeviceMotionEvents\fP request returns all events in the motion history buffer that fall between the specified start and stop times, inclusive. If the start time is later than the stop time or if the start time is in the future, no events are returned. If the stop time is in the future, it is equivalent to specifying \fICurrentTime\fP. .LP The \fImode\fP indicates whether the device is reporting absolute positional data (mode=\fIAbsolute\fP) or relative motion data (mode=\fIRelative\fP). Some devices allow their mode to be changed via the \fIXSetDeviceMode\fP request. These constants are defined in the file XI.h. The \fIaxis_count\fP returns the number of axes or valuators being reported by the device. .LP \fIXGetDeviceMotionEvents\fP can generate a \fIBadDevice\fP, or \fIBadMatch\fP error. .SH STRUCTURES The \fIXDeviceTimeCoord\fP structure contains: .LP .nf typedef struct { Time time; int *data; } XDeviceTimeCoord; .fi .LP The time member is set to the time, in milliseconds. The data member is a pointer to an array of integers. These integers are set to the values of each valuator or axis reported by the device. There is one element in the array per axis of motion reported by the device. The value of the array elements depends on the mode of the device. If the mode is \fIAbsolute\fP, the values are the raw values generated by the device. These may be scaled by client programs using the maximum values that the device can generate. The maximum value for each axis of the device is reported in the max_val field of the \fIXAxisInfo\fP returned by the \fIXListInputDevices\fP request. If the mode is \fIRelative\fP, the data values are the relative values generated by the device. .LP You should use \fIXFreeDeviceMotionEvents\fP to free the data returned by this request. .LP Errors returned by this request: \fIBadDevice\fP, \fIBadMatch\fP. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if the specified device is the X keyboard or X pointer device. .TP 12 \fIBadMatch\fP This error may occur if an \fIXGetDeviceMotionEvents\fP request is made specifying a device that has no valuators and reports no axes of motion. .SH "SEE ALSO" .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetErrorDatabaseText" "Xlib \- Error Handling" .ds ]W Xlib Reference Manual .SH Name .Na .XX "error messages:obtaining from error databases" .XX "error databases:obtaining error messages from" XGetErrorDatabaseText \(en obtain error messages from the error database. .Nz .SH "Synopsis" .Sy .ps -1 XGetErrorDatabaseText\^(\^\f(CIdisplay\f(CW, \f(CIname\f(CW, \f(CImessage\f(CW, .ti +10n \f(CIdefault_string\f(CW, \f(CIbuffer_return\f(CW, \f(CIlength\f(CW\^) .As Display \f(CIdisplay\f(CW\^; char *\f(CIname\f(CW, *\f(CImessage\f(CW\^; char *\f(CIdefault_string\f(CW\^; char *\f(CIbuffer_return\f(CW\^; int \f(CIlength\f(CW\^; .Ae .ps +1 .SH "Arguments" .IP \f(CIdisplay\fP 1.3i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIname\fP Specifies the name of the application. .IP \f(CImessage\fP Specifies the type of the error message. One of \f(CWXProtoError\fP, \f(CWXlibMessage\fP, or \f(CWXRequest\fP (see the "Description" section below). .IP \f(CIdefault_string\fP Specifies the default error message. .IP \f(CIbuffer_return\fP Returns the error description. You allocate this memory. .IP \f(CIlength\fP Specifies the size of the return buffer. .SH Description \f(CWXGetErrorDatabaseText()\fP returns a message from the error message database. Given \f(CIname\fP and \f(CImessage\fP as keys, \f(CWXGetErrorDatabaseText()\fP uses the resource manager to look up a string and returns it in the buffer argument. Xlib uses this function internally to look up its error messages. On a UNIX-based system, the error message database is usually \fI/usr/lib/X11/XErrorDB\fR. .LP The \f(CIname\fP argument should generally be the name of your application. The \f(CImessage\fP argument should indicate which type of error message you want. If the name and message are not in the Host Portable Character Encoding, then the result is implementation-dependent. Three predefined \f(CImessage\fP types are used by Xlib to report errors: .IP "\f(CWXProtoError\fP" 1.2i The protocol error number is used as a string for the message argument. .IP "\f(CWXlibMessage\fP" These are the message strings that are used internally by Xlib. .IP "\f(CWXRequest\fP" For a core protocol request, the major request protocol number is used for the message argument. For an extension request, the extension name (as given by \f(CWInitExtension\fR) followed by a period (\f(CW.\fR) and the minor request protocol number is used for the message argument. .LP If no string is found in the error database, \f(CWXGetErrorDatabaseText()\fP returns the \f(CWdefault_string\fP that you specify to the buffer. The string in \f(CIbuffer\fP will be of length \f(CIlength\fP. The \f(CWdefault_string\fR is assumed to be in the encoding of the current locale. The \f(CWbuffer_return\fR text is in the encoding of the current locale. .LP .SH "See Also" \s-1\fIXDisplayName()\fP\s+1, \s-1\fIXGetErrorText()\fP\s+1, \s-1\fIXSetAfterFunction()\fP\s+1, \s-1\fIXSetErrorHandler()\fP\s+1, \s-1\fIXSetIOErrorHandler()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetErrorText" "Xlib \- Error Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetErrorText" .XX "errors:obtaining text of" .Na XGetErrorText \(en obtain a description of error code. .Nz .SH "Synopsis" .Sy XGetErrorText\^(\^\f(CIdisplay\f(CW, \f(CIcode\f(CW, \f(CIbuffer_return\f(CW, \f(CIlength\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int \f(CIcode\f(CW\^; char *\f(CIbuffer_return\f(CW\^; int \f(CIlength\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcode\fP 1i Specifies the error code for which you want to obtain a description. .IP \f(CIbuffer_return\fP 1i Returns the error description text. You allocate this memory. .IP \f(CIlength\fP 1i Specifies the size of the buffer. .SH Description \f(CWXGetErrorText()\fP obtains textual descriptions of errors. \f(CWXGetErrorText()\fP copies a \f(CWNULL\fP-terminated string describing the specified error code into the specified buffer with length \f(CIlength\fP. The returned text is in the encoding of the current locale. This string is copied from static data and therefore may be freed. This routine allows extensions to the Xlib library to define their own error codes and error strings that can be accessed easily. .LP For more information, see Volume One, Chapter 3, \fIBasic Window Program\fR. .SH "See Also" \s-1\fIXDisplayName()\fP\s+1, \s-1\fIXGetErrorDatabaseText()\fP\s+1, \s-1\fIXSetAfterFunction()\fP\s+1, \s-1\fIXSetErrorHandler()\fP\s+1, \s-1\fIXSetIOErrorHandler()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1. .\"last line comment .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XGetExtV.man,v 1.5 94/06/04 17:34:47 rws Exp $ .ds xL Programming With Xlib .TH XGetExtensionVersion 3X "" "X Version 11" .SH NAME XGetExtensionVersion \- query the version of the input extension. .SH SYNTAX XExtensionVersion *XGetExtensionVersion\^(\^\fIdisplay\fP, \fIname\fP\^) .br Display *\fIdisplay\fP\^; .br char *\fIname\fP\^; .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I name Specifies the extension to be queried. The input extension name is defined in the header file \fIXI.h\fP. .SH DESCRIPTION The \fIXGetExtensionVersion\fP request queries the version of the input extension, and returns an \fIXExtensionVersion\fP structure. This structure contains a major_version and minor_version number which can be compared with constants defined in \fIXI.h\fP. Support for additional protocol requests added to the input extension after its initial release is indicated by a version number corresponding to the added requests. Each version contains all the protocol requests contained by previous versions. .LP You should use \fIXFree\fP to free the \fIXExtensionVersion\fP structure. .SH STRUCTURES This request returns an XExtensionVersion structure. .DS typedef struct { int present; short major_version; short minor_version; } XExtensionVersion; .DE .SH DIAGNOSTICS none .SH "SEE ALSO" .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetFontPath" "Xlib \- Fonts" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetFontPath" .XX "fonts:search path" .Na XGetFontPath \(en get the current font search path. .Nz .SH "Synopsis" .Sy char **XGetFontPath\^(\^\f(CIdisplay\f(CW, \f(CInpaths_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int *\f(CInpaths_return\f(CW\^; .LP .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CInpaths_return\fP 1i Returns the number of strings in the font path array. .SH Returns A list of strings comprising the font search path. .SH Description \f(CWXGetFontPath()\fP allocates and returns an array of strings containing the search path for fonts. The contents of these strings are implementation-dependent and are not intended to be interpreted by client applications. The data in the font path should be freed, using \f(CWXFreeFontPath()\fR, when no longer needed. .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXFreeFont()\fP\s+1, \s-1\fIXFreeFontInfo()\fP\s+1, \s-1\fIXFreeFontNames()\fP\s+1, \s-1\fIXFreeFontPath()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXListFonts()\fP\s+1, \s-1\fIXListFontsWithInfo()\fP\s+1, \s-1\fIXLoadFont()\fP\s+1, \s-1\fIXLoadQueryFont()\fP\s+1, \s-1\fIXQueryFont()\fP\s+1, \s-1\fIXSetFont()\fP\s+1, \s-1\fIXSetFontPath()\fP\s+1, \s-1\fIXUnloadFont()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetFontProperty" "Xlib \- Properties" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetFontProperty" .XX "fonts:properties, obtaining given an atom" .Na XGetFontProperty \(en get a font property given its atom. .Nz .SH "Synopsis" .Sy Bool XGetFontProperty\^(\^\f(CIfont_struct\f(CW\^, \^\f(CIatom\f(CW\^, \^\f(CIvalue_return\f(CW\^) .As XFontStruct *\f(CIfont_struct\f(CW\^; Atom \f(CIatom\f(CW\^; unsigned long *\f(CIvalue_return\f(CW\^; .LP .Ae .SH "Arguments" .IP \f(CIfont_struct\fP 1i Specifies the storage associated with the font. .IP \f(CIatom\fP 1i Specifies the atom associated with the property name you want returned. .IP \f(CIvalue_return\fP 1i Returns the value of the font property. .SH Returns \f(CWTrue\fP if the atom was defined, else \f(CWFalse\fP. .SH Description \f(CWXGetFontProperty()\fP returns the value of the specified font property, given the atom for that property. The function returns \f(CWFalse\fP if the atom was not defined, or \f(CWTrue\fP if was defined. .LP There are a set of predefined atoms for font properties which can be found in <\fIX11/Xatom.h\fR>. These atoms are listed and described in Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. This set contains the standard properties associated with a font. The predefined font properties are likely but not guaranteed to be present for any given font. .LP See Volume 0, Appendix M, \fILogical Font Description Conventions\fP, for more information on font properties. .SH "Structures" .Ps .ta 4.5n 2.25i typedef struct { XExtData *ext_data; /* hook for extension to hang data */ Font fid; /* Font ID for this font */ unsigned direction; /* hint about direction the font is painted */ unsigned min_char_or_byte2; /* first character */ unsigned max_char_or_byte2; /* last character */ unsigned min_byte1; /* first row that exists */ unsigned max_byte1; /* last row that exists */ Bool all_chars_exist; /* flag if all characters have non-zero size*/ unsigned default_char; /* char to print for undefined character */ int n_properties; /* how many properties there are */ XFontProp *properties; /* pointer to array of additional properties*/ XCharStruct min_bounds; /* minimum bounds over all existing char*/ XCharStruct max_bounds; /* maximum bounds over all existing char*/ XCharStruct *per_char; /* first_char to last_char information */ int ascent; /* logical extent above baseline for spacing */ int descent; /* logical descent below baseline for spacing */ } XFontStruct; .XX "XFontStruct structure" .XX "structures:XFontStruct" .Pe .SH "See Also" \s-1\fIXChangeProperty()\fP\s+1, \s-1\fIXDeleteProperty()\fP\s+1, \s-1\fIXGetAtomName()\fP\s+1, \s-1\fIXGetWindowProperty()\fP\s+1, \s-1\fIXInternAtom()\fP\s+1, \s-1\fIXListProperties()\fP\s+1, \s-1\fIXRotateWindowProperties()\fP\s+1, \s-1\fIXSetStandardProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetGCValues" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XGetGCValues" .XX "graphics context:components;obtaining" .Na XGetGCValues \(en obtain components of a given GC from Xlib's GC cache. .Nz .SH "Synopsis" .Sy Status XGetGCValues\^(\^\f(CIdisplay\fP\^, \f(CIgc\fP\^, \f(CIvaluemask\fP\^, \f(CIvalues_return\fP\^) .As Display *\f(CIdisplay\fP\^; GC \f(CIgc\fP\^; unsigned long \f(CIvaluemask\fP\^; XGCValues *\f(CIvalues_return\fP\^; .Ae .sp -3p .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/GetGCValues 2.9 1993/05/28 13:28:07 stephen Exp $ .IP \f(CIgc\fP 1i Specifies the graphics context. .ds Vm returned in the \f(CWvalues_return\fP argument .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/GetGCValues 2.9 1993/05/28 13:28:07 stephen Exp $ .IP \f(CIvaluemask\fP 1i Specifies which components in the GC are to be returned in the\p \f(CWvalues_return\fP argument. This argument is the bitwise inclusive OR of zero or more of the valid GC component mask bits. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/GetGCValues 2.9 1993/05/28 13:28:07 stephen Exp $ .IP \f(CIvalues_return\fP 1i Returns the GC values in the specified \f(CWXGCValues\fR structure. .sp -2p .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description .LP \f(CWXGetGCValues()\fR returns the components specified by valuemask for the specified GC. Note that the clip mask and dash list (represented by the \f(CWGCClipMask\fR and \f(CWGCDashList\fR bits, respectively, in the valuemask) cannot be requested. Also note that an invalid resource ID (with one or more of the three most-significant bits set to one) will be returned for \f(CWGCFont\fR, \f(CWGCTile\fR, and \f(CWGCStipple\fR if the component has never been explicitly set by the client. If the valuemask contains a valid set of GC mask bits (any of those listed in the Structures section with the exception of \f(CWGCClipMask\fP and \f(CWGCDashList\fP) and no error occur, \f(CWXGetGCValues()\fR sets the requested components in \f(CWvalues_return\fP and returns a non-zero status. Otherwise, it returns a zero status. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fP. .sp -2p .SH "Structures" .Ps .ta 4.5n 2.2i typedef struct { int function; /* logical operation */ unsigned long plane_mask; /* plane mask */ unsigned long foreground; /* foreground pixel */ unsigned long background; /* background pixel */ int line_width; /* line width */ int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */ int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */ int join_style; /* JoinMiter, JoinRound, JoinBevel */ int fill_style; /* FillSolid, FillTiled, FillStippled */ int fill_rule; /* EvenOddRule, WindingRule */ int arc_mode; /* ArcPieSlice, ArcChord */ Pixmap tile; /* tile pixmap for tiling operations */ Pixmap stipple; /* stipple 1 plane pixmap for stipping */ int ts_x_origin; /* offset for tile or stipple operations */ int ts_y_origin; Font font; /* default text font for text operations */ int subwindow_mode; /* ClipByChildren, IncludeInferiors */ Bool graphics_exposures; /* generate events on XCopyArea, XCopyPlane */ int clip_x_origin; /* origin for clipping */ int clip_y_origin; Pixmap clip_mask; /* bitmap clipping; other calls for rects */ int dash_offset; /* patterned/dashed line information */ char dashes; } XGCValues; .XX "XGCValues structure" .XX "structures:XGCValues" #define GCFunction (1L<<0) #define GCPlaneMask (1L<<1) #define GCForeground (1L<<2) #define GCBackground (1L<<3) #define GCLineWidth (1L<<4) #define GCLineStyle (1L<<5) #define GCCapStyle (1L<<6) #define GCJoinStyle (1L<<7) #define GCFillStyle (1L<<8) #define GCFillRule (1L<<9) #define GCTile (1L<<10) #define GCStipple (1L<<11) #define GCTileStipXOrigin (1L<<12) #define GCTileStipYOrigin (1L<<13) #define GCFont (1L<<14) #define GCSubwindowMode (1L<<15) #define GCGraphicsExposures (1L<<16) #define GCClipXOrigin (1L<<17) #define GCClipYOrigin (1L<<18) #define GCClipMask (1L<<19) /* not valid in this call */ #define GCDashOffset (1L<<20) #define GCDashList (1L<<21) /* not valid in this call */ #define GCArcMode (1L<<22) .Pe .sp -2p .SH "See Also" \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetGeometry" "Xlib \- Window Attributes" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetGeometry" .XX "geometry:of drawables" .Na XGetGeometry \(en obtain the current geometry of drawable. .Nz .SH "Synopsis" .Sy Status XGetGeometry\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \^\f(CIroot_return\f(CW\^, \f(CIx_return\f(CW\^, \f(CIy_return\f(CW\^, \f(CIwidth_return\f(CW\^, \f(CIheight_return\f(CW\^, \f(CIborder_width_return\f(CW\^, \f(CIdepth_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; Window *\f(CIroot_return\f(CW\^; int *\f(CIx_return\f(CW\^, *\f(CIy_return\f(CW\^; unsigned int *\f(CIwidth_return\f(CW\^, *\f(CIheight_return\f(CW\^; unsigned int *\f(CIborder_width_return\f(CW\^; unsigned int *\f(CIdepth_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.25i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP Specifies the drawable, either a window or a pixmap. .IP \f(CIroot_return\fP Returns the root window ID of the specified window. .IP \f(CIx_return\fP .br .ns .IP \f(CIy_return\fP .sp -2 Return the coordinates of the upper-left pixel of the window's border, relative to its parent's origin. For pixmaps, these coordinates are always zero. .IP \f(CIwidth_return\fP .br .ns .IP \f(CIheight_return\fP .sp -2 Return the dimensions of the drawable. For a window, these return the inside size (not including the border). .IP \f(CIborder_width_return\fP Returns the borderwidth, in pixels, of the window's border, if the drawable is a window. Returns zero if the drawable is a pixmap. .IP \f(CIdepth_return\fP Returns the depth of the pixmap or window (bits per pixel for the object). .SH Returns Zero on failure, non-zero on success. .SH Description .XX "drawable:obtaining geometry of" This function gets the current geometry of a drawable, plus the ID of the root window of the screen the window is on. It is legal to pass to this function on \f(CWInputOnly\fR window. .LP \f(CWXGetGeometry()\fP returns a \f(CWStatus\fP of zero on failure, or non-zero on success. .Nd 15 .SH "Errors" \f(CWBadDrawable\fP .SH "See Also" \s-1\fIXConfigureWindow()\fP\s+1, \s-1\fIXGetWindowAttributes()\fP\s+1, \s-1\fIXMoveResizeWindow()\fP\s+1, \s-1\fIXMoveWindow()\fP\s+1, \s-1\fIXResizeWindow()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetICValues" "Xlib \- Input Contexts" .ds ]W Xlib Reference Manual .XX "XGetICValues" .XX "input contexts:attributes" .SH Name .Na XGetICValues \(en get input context attributes. .Nz .SH Synopsis .Sy char *XGetICValues\^(\^\f(CIic\fP\^, ...) .As XIC \f(CIic\fP\^; .Ae .SH Arguments .IP \f(CIic\fP 1i Specifies the input context. .ds Al \ to set or get XIC values .IP ... 1i Specifies the variable length argument list\*(Al. .SH Returns \f(CWNULL\fP if no error occurred; otherwise, the name of the first attribute that could not be obtained. .SH Availability Release 5 and later. .SH Description \f(CWXGetICValues()\fP queries the values of input context attributes. The first argument is the input context, and it is followed by a \f(CWNULL\fP-terminated variable-length argument list of attribute name/value pairs. The standard attributes and their types are listed in the tables below. .sp .50p \f(HIInput Context Attributes\fP .sp 6p .vs 11p .sp 1 .in 0 .KS .TS tab(@), linesize(2); lb lb lb lp7fCW lp7fCW l. Name@Type@Notes .sp 4p .sp 2p XNInputStyle@XIMStyle@T{ .na Required at IC creation; may not be changed. T} .sp 3p XNClientWindow@Window@T{ .na Must be set before IC use; may not be changed. T} .sp 3p XNFocusWindow@Window@Changes may cause geometry negotiation. .sp 3p XNResourceName@char * .sp 3p XNResourceClass@char * .sp 3p XNGeometryCallback@XIMCallback * .sp 3p XNFilterEvents@unsigned long@Read-only attribute; may not be set. .sp 3p XNPreeditAttributes@XVaNestedList@See sub-attributes below. .sp 3p XNStatusAttributes@XVaNestedList@See sub-attributes below. .sp 5p .TE .KE .in .sp 1 .sp .50p .ne 6 \f(HI\s-1Pre-edit and Status Area Sub-attributes\s+1\fP .sp 6p .vs 10 .sp 1 .in 0 .KS .TS tab(@), linesize(2); lb lb lb lp7fCW lp7fCW lp10w(1.6i). Name@Type@Notes .sp 2p .sp 2p XNArea@XRectangle * .sp 3p XNAreaNeeded@XRectangle * .sp 3p XNSpotLocation@XPoint *@T{ Required at IC creation for \f(CWXIMPreeditPosition\fP style. T} .sp 3p XNColormap@Colormap .sp 3p XNStdColormap@Atom .sp 3p XNForeground@unsigned long .sp 3p XNBackground@unsigned long .sp 3p XNBackgroundPixmap@Pixmap .sp 3p XNFontSet@XFontSet@T{ Required at IC creation; changes may cause geometry negotiation. T} .sp 3p XNLineSpacing@int@T{ Changes may cause geometry negotiation. T} .sp 3p XNCursor@Cursor .sp 3p XNPreeditStartCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} .sp 3p XNPreeditDoneCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} .sp 3p XNPreeditDrawCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} .sp 3p XNPreeditCaretCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} .sp 3p XNStatusStartCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fP style. T} .sp 3p XNStatusDoneCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fP style. T} .sp 3p XNStatusDrawCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fP style. T} .sp 5p .TE 0 .KE .in .sp 1 .vs 12 .Nd 10 In addition to the attribute names above, the special name \f(CWXNVaNestedList\fR indicates that the following argument is a \f(CWXVaNestedList\fP of attribute name/value pairs. When a nested list is encountered in an argument list, the contents of the nested list are processed as if they appeared in the original argument list at that point. .LP The \f(CWXGetICValues()\fR function returns \f(CWNULL\fP if no error occurred; otherwise, it returns the name of the first attribute that could not be obtained. An attribute could be not obtained for any of the following reasons: .IP \(bu 3n The attribute name is not recognized. .IP \(bu 3n The input method encountered an implementation-dependent error. .LP Each attribute value argument to \f(CWXGetICValues()\fP (the argument that follows the attribute name) must be the address of a location into which the value is to be stored. For attributes that are pointer types (\f(CWXNArea\fP, for example), \f(CWXGetICValues()\fP returns a pointer to a copy of the attribute value. In this case, the client must free the memory allocated for that copy with \f(CWXFree()\fP. .SH "See Also" \s-1\fIXCreateIC()\fP\s+1, \s-1\fIXOpenIM()\fP\s+1, \s-1\fIXSetICFocus()\fP\s+1, \s-1\fIXSetICValues()\fP\s+1, \s-1\fIXmbResetIC()\fP\s+1, \s-1\fIXwcResetIC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetIMValues" "Xlib \- Input Methods" .ds ]W Xlib Reference Manual .XX "XGetIMValues" .XX "input methods:information" .SH Name .Na XGetIMValues \(en obtain input method information. .Nz .SH Synopsis .Sy char * XGetIMValues\^(\^\f(CIim\fP\^, ...) .As XIM \f(CIim\fP\^; .Ae .SH Arguments .IP \f(CIim\fP 1i Specifies the input method. .ds Al \ to get XIM values .IP ... 1i Specifies the variable length argument list\*(Al. .SH Returns \f(CWNULL\fP if no error occurred; otherwise, the name of the first attribute that could not be obtained. .SH Availability Release 5 and later. .SH Description \f(CWXGetIMValues()\fP queries the values of input method attributes. The first argument is the input method, and it is followed by a \f(CWNULL\fP-terminated variable-length argument list of attribute name/value pairs. Only one standard attribute is defined by Xlib: \f(CWXNQueryInputStyle\fR. It is of type \f(CWXIMStyles *\fP (shown below) and is used to query the input styles supported by the input method. A client should always query the input method to determine which styles are supported. The client should then find an input style it is capable of supporting, and use that style when creating input contexts. If the client cannot find an input style that it can support it should negotiate with the user the continuation of the program (exit, choose another input method, and so on). .LP The attribute value argument (which follows the attribute name argument) must be the address of a location where the returned value will be stored. For the \f(CWXNQueryInputStyle\fP attribute, the client must pass the address of a variable of type \f(CWXIMStyles*\fP, and is responsible for freeing the memory allocated for the \f(CWXIMStyles\fR data structure with \f(CWXFree()\fR. .LP \f(CWXGetIMValues()\fP returns \f(CWNULL\fP if it succeeds. Otherwise it returns the name of the first attribute for which a value could not be obtained. .SH "Structures" .Ps #define XIMPreeditArea 0x0001L #define XIMPreeditCallbacks 0x0002L #define XIMPreeditPosition 0x0004L #define XIMPreeditNothing 0x0008L #define XIMPreeditNone 0x0010L #define XIMStatusArea 0x0100L #define XIMStatusCallbacks 0x0200L #define XIMStatusNothing 0x0400L #define XIMStatusNone 0x0800L typedef unsigned long XIMStyle; .Nd 15 typedef struct { unsigned short count_styles; XIMStyle *supported_styles; } XIMStyles; .Pe .SH "See Also" \s-1\fIXOpenIM()\fP\s+1, \s-1\fIXCloseIM()\fP\s+1, \s-1\fIXDisplayOfIM()\fP\s+1, \s-1\fIXLocaleOfIM()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetIconName" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetIconName" .XX "icon names:obtaining" .Na XGetIconName \(en get the name to be displayed in an icon. .Nz .SH "Synopsis" .Sy Status XGetIconName\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIicon_name_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; char **\f(CIicon_name_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window whose icon name you want to learn. .IP \f(CIicon_name_return\fP 1i Returns a pointer to the name to be displayed in the window's icon. The name is a \f(CWNULL\fP-terminated string. If the data returned by the server is in the Latin Portable Character Encoding, then the returned string is in the Host Portable Character Encoding. Otherwise, the result is implementation-dependent. If a name hasn't been assigned to the window, \f(CWXGetIconName()\fP sets this argument to \f(CWNULL\fP. When finished with it, a client must free the icon name string using \f(CWXFree()\fP. .SH Returns Zero on failure, non-zero on success. .SH Description .XX "XGetWMIconName:and XGetIconName" \f(CWXGetIconName()\fP is superseded by \f(CWXGetWMIconName()\fP in Release 4. \f(CWXGetIconName()\fP reads the icon name property of a window. This function is primarily used by window managers to get the name to be written in a window's icon when they need to display that icon. \f(CWXGetIconName()\fP returns a non-zero \f(CWStatus\fP if it succeeds, and zero if no icon name has been set for the argument window. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetIconSizes" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetIconSizes" .XX "icon sizes" .Na XGetIconSizes \(en get preferred icon sizes. .Nz .SH "Synopsis" .Sy Status XGetIconSizes\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIsize_list_return\f(CW, \f(CIcount_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; XIconSize **\f(CIsize_list_return\f(CW\^; int *\f(CIcount_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the window ID (usually of the root window). .IP \f(CIsize_list_return\fP Returns a pointer to the size list. .IP \f(CIcount_return\fP Returns the number of items in the size list. .SH Returns Zero on failure, non-zero on success. .SH Description .XX "XA_WM_ICON_SIZE property" \f(CWXGetIconSizes()\fP reads the \f(CWXA_WM_ICON_SIZE\fP property that should be set by the window manager to specify its desired icon sizes. \f(CWXGetIconSizes()\fP returns a \f(CWStatus\fP of zero if a window manager has not set icon sizes, and a non-zero \f(CWStatus\fP otherwise. This function should be called by all programs to find out what icon sizes are preferred by the window manager. The application should then use \f(CWXSetWMHints()\fP to supply the window manager with an icon pixmap or window in one of the supported sizes. To free the data allocated in \f(CWsize_list_return\fP, use \f(CWXFree()\fP. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Structures" .XX "structures:XIconSize" .Ps typedef struct { int min_width, min_height; int max_width, max_height; int width_inc, height_inc; } XIconSize; /* width_inc and height_inc provide the preferred increment of sizes in the * range from min_width to max_width and min_height to max_height. */ .Pe .ne 8 .SH "Errors" \f(CWBadWindow\fP .Nd 8 .SH "See Also" \s-1\fIXAllocIconSize()\fP\s+1, \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, .ne 3 \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName*()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetImage" "Xlib \- Images" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetImage" .XX "images" .Na XGetImage \(en place contents of a rectangle from drawable into an image. .Nz .SH "Synopsis" .Sy XImage *XGetImage\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^, .ti +10n \f(CIplane_mask\f(CW, \f(CIformat\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; unsigned long \f(CIplane_mask\f(CW\^; int \f(CIformat\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable to get the data from. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the upper-left corner of the rectangle, relative to the origin of the drawable. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight\fP 1i .sp -2 Specify the width and height in pixels of the image. .sp .IP \f(CIplane_mask\fP 1i Specifies a plane mask that indicates which planes are represented in the image. .IP \f(CIformat\fP 1i Specifies the format for the image. Pass either \f(CWXYPixmap\fP or \f(CWZPixmap\fP. .SH Returns The created image. .SH Description \f(CWXGetImage()\fP dumps the contents of the specified rectangle, a drawable, into a client-side \f(CWXImage\fP structure, in the format you specify. Depending on which format you pass to the format argument, the function does the following: .IP \(bu 3n If the format is \f(CWXYPixmap\fP, the function gets only the bit planes you passed to the \f(CIplane_mask\fP argument. .IP \(bu 3n If the format is \f(CWZPixmap\fP, the function sets to 0 the bits in all planes not specified in the \f(CIplane_mask\fP argument. The function performs no range checking on the values in \f(CIplane_mask\fP, and ignores extraneous bits. .LP \f(CWXGetImage()\fP returns the depth of the image to the depth member of the \f(CWXImage\fP structure. This depth is as specified when the drawable was created. .LP If the drawable is a pixmap, the specified rectangle must be completely .ne 2 inside the pixmap, or a \f(CWBadMatch\fP error will occur, and the \f(CWvisual\fP field in the image will be \f(CWNone\fP. If \f(CWXGetImage()\fR fails, it returns \f(CWNULL\fR. If the drawable is a window, the window must be viewable, and the specified rectangle must not go off the edge of the screen. Otherwise, a \f(CWBadMatch\fP error will occur. If the drawable is a window, the \f(CIvisual\fP argument will return the visual specified when the drawable was created. .LP The returned image will include any visible portions of inferiors contained in the rectangle. The image will not include the cursor. The specified area can include the borders. The returned contents of visible regions of inferiors of different depth than the specified window are undefined. .LP If the window has a backing-store, the backing-store contents are returned for regions of the window that are obscured by noninferior windows. Otherwise, the return contents of such obscured regions are undefined. .LP The data in the image structure is stored in the server's natural byte- and bit-order. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Errors" .IP "\f(CWBadDrawable\fP" 1i .IP "\f(CWBadMatch\fP" 1i See the "Description" section above. .IP "\f(CWBadValue\fP" .SH "See Also" \s-1\fIXImageByteOrder()\fP\s+1, \s-1\fIXAddPixel()\fP\s+1, \s-1\fIXCreateImage()\fP\s+1, \s-1\fIXDestroyImage()\fP\s+1, \s-1\fIXGetPixel()\fP\s+1, \s-1\fIXGetSubImage()\fP\s+1, \s-1\fIXPutImage()\fP\s+1, \s-1\fIXPutPixel()\fP\s+1, \s-1\fIXSubImage()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetInputFocus" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetInputFocus" .Na XGetInputFocus \(en return the current keyboard focus window. .Nz .SH "Synopsis" .Sy XGetInputFocus\^(\^\f(CIdisplay\f(CW, \f(CIfocus_return\f(CW\^, \f(CIrevert_to_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window *\f(CIfocus_return\f(CW\^; int *\f(CIrevert_to_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIfocus_return\fP 1i Returns the ID of the focus window, or one of the constants \f(CWPointerRoot\fP or \f(CWNone\fP. .IP \f(CIrevert_to_return\fP 1i Returns the window to which the focus would revert if the focus window became invisible. This is one of these constants: \f(CWRevertToParent\fP, \f(CWRevertToPointerRoot\fP, or \f(CWRevertToNone\fP. Must not be a window ID. .SH Description .XX "keyboard focus window" \f(CWXGetInputFocus()\fP returns the current keyboard focus window and the window to which the focus would revert if the focus window became invisible. .LP \f(CWXGetInputFocus()\fP does not report the last focus change time. This is available only from \f(CWFocusIn\fP and \f(CWFocusOut\fP events. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetKeyboardControl" "Xlib \- User Preferences" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetKeyboardControl" .XX "keyboard, preferences" .Na XGetKeyboardControl \(en obtain a list of the current keyboard preferences. .Nz .SH "Synopsis" .Sy XGetKeyboardControl\^(\^\f(CIdisplay\f(CW, \f(CIvalues_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XKeyboardState *\f(CIvalues_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIvalues_return\fP 1i Returns filled \f(CWXKeyboardState()\fP structure. .SH Description \f(CWXGetKeyboardControl()\fP returns the current control values for the keyboard. .XX "LEDs" For the LEDs (light emitting diodes), the least significant bit of \f(CIled_mask\fP corresponds to LED 1, and each bit that is set to 1 in \f(CIled_mask\fP indicates an LED that is lit. \f(CWauto_repeats\fP is a bit vector; each bit that is set to 1 indicates that auto-repeat is enabled for the corresponding key. The vector is represented as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N+7, with the least significant bit in the byte representing key 8N. .hw global \f(CIglobal_auto_repeat\fP is either \f(CWAutoRepeatModeOn\fP or \f(CWAutoRepeatModeOff\fP. .LP For the ranges of each member of \f(CWXKeyboardState()\fP, see the description of \f(CWXChangePointerControl()\fP. .LP For more information, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "Structures" .Ps typedef struct { int key_click_percent; int bell_percent; unsigned int bell_pitch, bell_duration; unsigned long led_mask; int global_auto_repeat; char auto_repeats[32]; } XKeyboardState; .Pe .SH "See Also" \s-1\fIXAutoRepeatOff()\fP\s+1, \s-1\fIXAutoRepeatOn()\fP\s+1, \s-1\fIXBell()\fP\s+1, \s-1\fIXChangeKeyboardControl()\fP\s+1, \s-1\fIXGetDefault()\fP\s+1, \s-1\fIXGetPointerControl()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetKeyboardMapping" "Xlib \- Keyboard" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetKeyboardMapping" .XX "keyboard, mapping" .Na XGetKeyboardMapping \(en return symbols for keycodes. .Nz .SH "Synopsis" .Sy KeySym *XGetKeyboardMapping(\^\f(CIdisplay\f(CW, \f(CIfirst_keycode\f(CW, \f(CIkeycode_count\f(CW, .ti +10n \f(CIkeysyms_per_keycode_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; KeyCode \f(CIfirst_keycode\f(CW\^; int \f(CIkeycode_count\f(CW\^; int *\f(CIkeysyms_per_keycode_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIfirst_keycode\fP Specifies the first keycode that is to be returned. .IP \f(CIkeycode_count\fP Specifies the number of keycodes that are to be returned. .IP \f(CIkeysyms_per_keycode_return\fP Returns the number of keysyms per keycode. .SH Returns The list of \f(CWKeySym\fPs. .SH Description Starting with \f(CIfirst_keycode\fP, \f(CWXGetKeyboardMapping()\fP returns the symbols for the specified number of keycodes. The specified \f(CIfirst_keycode\fP must be greater than or equal to \f(CWmin_keycode\fP as returned by \f(CWXDisplayKeycodes()\fP, otherwise a \f(CWBadValue\fP error occurs. In addition, the following expression must be less than or equal .hw max_-keycode to \f(CWmax_keycode\fP (also returned by \f(CWXDisplayKeycodes()\fP) as returned in the \f(CWDisplay\fP structure, otherwise a \f(CWBadValue\fP error occurs: .Ps 5n \f(CIfirst_keycode\fP + \f(CIkeycode_count\fP - 1 .Pe The number of elements in the keysyms list is: .Ps 5n \f(CIkeycode_count\fP * \f(CIkeysyms_per_keycode_return\fP .Pe Then, keysym number \fIN\fR (counting from 0) for keycode \fIK\fR has an index (counting from 0) of the following (in keysyms): .Ps 5n (K - \f(CIfirst_keycode\fP) * \f(CIkeysyms_per_keycode_return\fP + N .Pe .Nd 10 The \f(CWkeysyms_per_keycode_return\fP value is chosen arbitrarily by the server to be large enough to report all requested symbols. .ne 2 A special \f(CWKeySym\fP value of \f(CWNoSymbol\fP is used to fill in unused elements for individual keycodes. .LP Use \f(CWXFree()\fP to free the returned keysym list when you no longer need it. .LP For more information, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .br .ne 4 .SH "Errors" .IP "\f(CWBadValue\fP" 1i \f(CIfirst_keycode\fP less than \f(CIdisplay\f(CW->min_keycode. .sp .5 \f(CIdisplay\fP->max_keycode\fR exceeded. .Nd 10 .SH "See Also" \s-1\fIXChangeKeyboardMapping()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifierMap\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeySym\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .TH XGetKeyboar.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XGetKeyboardControl@XGetKeyboaA .sp .5 XGetKeyboardMapping@XGetKeyboaB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetModifierMapping" "X Programming Library" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetModifierMapping" .Na XGetModifierMapping \(en obtain the mapping of modifier keys (Shift, Control, etc.). .Nz .SH "Synopsis" .Sy XModifierKeymap *XGetModifierMapping\^(\^\f(CIdisplay\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Returns The current modifier mapping. .SH Description \f(CWXGetModifierMapping()\fP .XX "modifier keys" returns the keycodes of the keys being used as modifiers. .LP There are eight modifiers, represented by the symbols \f(CWShiftMapIndex\fP, \f(CWLockMap\%Index\fP, \f(CWControlMapIndex\fP, \f(CWMod1MapIndex\fP, \f(CWMod2MapIndex\fP, \f(CWMod3Map\%Index\fP, \f(CWMod4MapIndex\fP, and \f(CWMod5MapIndex\fP. The \f(CWmodifiermap\fP member of the \f(CWXModifierKeymap()\fP structure contains eight sets of keycodes, each set containing \f(CWmax_keypermod\fP keycodes. Zero keycodes are not meaningful. If an entire \f(CWmodifiermap\fP is filled with zero's, the corresponding modifier is disabled. No keycode will appear twice anywhere in the map. .SH "Structures" .Ps typedef struct { int max_keypermod; /* server's max number of keys per modifier */ KeyCode *modifiermap; /* an 8 by \f(CImax_keypermod\fP array of * keycodes to be used as modifiers */ } XModifierKeymap; .XX "XModifierKeymap structure" .XX "structures:XModifierKeymap" /* modifier names. Used to build a SetModifierMapping request or to read a GetModifierMapping request. */ #define ShiftMapIndex 0 #define LockMapIndex 1 #define ControlMapIndex 2 #define Mod1MapIndex 3 #define Mod2MapIndex 4 #define Mod3MapIndex 5 #define Mod4MapIndex 6 #define Mod5MapIndex 7 .Pe .sp -3p .SH "See Also" \s-1\fIXChangeKeyboardMapping()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifierMap\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeySym\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetMotionEvents" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetMotionEvents" .Na XGetMotionEvents \(en get events from pointer motion history buffer. .ta 4.5n 2.75i .Nz .SH "Synopsis" .Sy XTimeCoord *XGetMotionEvents\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIstart\f(CW\^, \f(CIstop\f(CW\^, \f(CInevents_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; Time \f(CIstart\f(CW\^, \f(CIstop\f(CW\^; int *\f(CInevents_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the ID of the window whose associated pointer motion events will be returned. .IP \f(CIstart\fP .br .ns .IP \f(CIstop\fP .sp -2 Specify the time interval for which the events are returned from the motion history buffer. Pass a time stamp (in milliseconds) or \f(CWCurrentTime\fP. .IP \f(CInevents_return\fP Returns the number of events returned from the motion history buffer. .SH Returns The list of pointer positions. .SH Description .XX "events:motion" \f(CWXGetMotionEvents()\fP returns all events in the motion history buffer that fall between the specified start and stop times (inclusive) and that have coordinates that lie within (including borders) the specified window at its present placement. The x and y coordinates of the \f(CWXTimeCoord\fP return structure are reported relative to the origin of \f(CIw\fP. .LP \f(CWXGetMotionEvent\fR returns \f(CWNULL\fR if the server does not support a motion history buffer (which is common), or if the start time is after the stop time, or if the start time is in the future. If the stop time is in the future, it is equivalent to specifying the constant \f(CWCurrentTime\fR, since the server does not wait to report future events. A motion history buffer is supported if \f(CWXDisplayMotionBufferSize()\fR (display) \f(CW> 0\fR. The pointer position at each pointer hardware interrupt is then stored for later retrieval. .LP Use \f(CWXFree()\fP to free the returned \f(CWXTimeCoord\fP structures when they are no longer needed. .LP For more information, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .Nd 5 .SH Structures .Ps typedef struct _XTimeCoord { Time time; short x, y; } XTimeCoord; .Pe .ne 3 .SH "Errors" \f(CWBadWindow\fP .br .ne 5 .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetNormalHints" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetNormalHints" .Na XGetNormalHints \(en get the size hints property of a window in normal state (not zoomed or iconified). .Nz .SH "Synopsis" .Sy Status XGetNormalHints\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIhints_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; XSizeHints *\f(CIhints_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window to be queried. .IP \f(CIhints_return\fP 1i Returns the sizing hints for the window in its normal state. .SH Returns Zero on failure, non-zero on success. .SH Description .XX "XGetWMNormalHints:and XGetNormalHints" \f(CWXGetNormalHints()\fP has been superseded by \f(CWXGetWMNormalHints()\fP as of Release 4, because new interclient communication conventions are now standard. .LP .XX "size hints" \f(CWXGetNormalHints()\fP returns the size hints for a window in its normal state by reading the \f(CWXA_WM_NORMAL_HINTS\fP property. This function is normally used only by a window manager. It returns a non-zero \f(CWStatus\fP if it succeeds, and zero if it fails (e.g., the application specified no normal size hints for this window.) .LP For more information on using hints, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Structures" .Ps typedef struct { long flags; /* which fields in structure are defined */ int x, y; int width, height; int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; } XSizeHints; .ne 10 /* flags argument in size hints */ #define USPosition (1L << 0) /* user specified x, y */ #define USSize (1L << 1) /* user specified width, height */ #define PPosition (1L << 2) /* program specified position */ #define PSize (1L << 3) /* program specified size */ #define PMinSize (1L << 4) /* program specified minimum size */ #define PMaxSize (1L << 5) /* program specified maximum size */ #define PResizeInc (1L << 6) /* program specified resize increments */ #define PAspect (1L << 7) /* program specified min/max aspect ratios */ #define PAllHints (PPosition PSize PMinSize PMaxSize PResizeInc PAspect) .Pe .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetPixel" "Xlib \- Images" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetPixel" .XX "pixels:obtaining from images" .Na XGetPixel \(en obtain a single pixel value from an image. .Nz .SH "Synopsis" .Sy unsigned long XGetPixel\^(\^\f(CIximage\f(CW, \f(CIx\f(CW, \f(CIy\f(CW\^) .As XImage *\f(CIximage\f(CW\^; int \f(CIx\f(CW\^; int \f(CIy\f(CW\^; .Ae .SH "Arguments" .IP \f(CIximage\fP 1i Specifies a pointer to the image. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the pixel whose value is to be returned. .SH Returns The pixel value. .SH Description \f(CWXGetPixel()\fP returns the specified pixel from the named image. The \f(CIx\fP and \f(CIy\fP coordinates are relative to the origin (upper-left [0,0]) of the image). The pixel value is returned in the normalized format (that is, the least-significant byte of the \f(CWlong\fR is the least-significant byte of the pixel). The x and y coordinates must be contained in the image. .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" .Ps typedef struct _XImage { int width, height; /* size of image */ int xoffset; /* number of pixels offset in X direction */ int format; /* XYBitmap, XYPixmap, ZPixmap */ char *data; /* pointer to image data */ int byte_order; /* data byte order, LSBFirst, MSBFirst */ int bitmap_unit; /* quant. of scan line 8, 16, 32 */ int bitmap_bit_order; /* LSBFirst, MSBFirst */ int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */ int depth; /* depth of image */ int bytes_per_line; /* accelerator to next line */ int bits_per_pixel; /* bits per pixel (ZPixmap) */ unsigned long red_mask; /* bits in z arrangment */ unsigned long green_mask; unsigned long blue_mask; char *obdata; /* hook for the object routines to hang on */ struct funcs { /* image manipulation routines */ struct _XImage *(*create_image)(); int (*destroy_image)(); unsigned long (*get_pixel)(); int (*put_pixel)(); struct _XImage *(*sub_image)(); int (*add_pixel)(); } f; } XImage; .XX "XImage structure" .XX "structures:XImage" .Pe .SH "See Also" \s-1\fIXImageByteOrder()\fP\s+1, \s-1\fIXAddPixel()\fP\s+1, \s-1\fIXCreateImage()\fP\s+1, \s-1\fIXDestroyImage()\fP\s+1, \s-1\fIXGetImage()\fP\s+1, \s-1\fIXGetSubImage()\fP\s+1, \s-1\fIXPutImage()\fP\s+1, \s-1\fIXPutPixel()\fP\s+1, \s-1\fIXSubImage()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetPointerControl" "Xlib \- Pointer" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetPointerControl" .XX "pointers:preferences, obtaining" .Na XGetPointerControl \(en get the current pointer preferences. .Nz .SH "Synopsis" .Sy XGetPointerControl\^(\^\f(CIdisplay\f(CW, \f(CIaccel_numerator_return\f(CW\^, .br \f(CIaccel_denominator_return\f(CW\^, \f(CIthreshold_return\f(CW\^) .br Display *\f(CIdisplay\f(CW\^; .As int *\f(CIaccel_numerator_return\f(CW\^, *\f(CIaccel_denominator_return\f(CW\^; int *\f(CIthreshold_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIaccel_numerator_return\fP 1i Returns the numerator for the acceleration multiplier. .IP \f(CIaccel_denominator_return\fP 1i Returns the denominator for the acceleration multiplier. .IP \f(CIthreshold_return\fP 1i Returns the acceleration threshold in pixels. The pointer must move more than this amount before acceleration takes effect. .SH Description \f(CWXGetPointerControl()\fP gets the pointer's current acceleration parameters. .LP \f(CIaccel_numerator_return\fP divided by \f(CIaccel_denominator_return\fR is the number of pixels the cursor moves per unit of motion of the pointer, applied only to the amount of movement over \f(CIthreshold_return\fP. .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXChangePointerControl()\fP\s+1, \s-1\fIXGetPointerMapping()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXQueryPointer()\fP\s+1, \s-1\fIXSetPointerMapping()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1, \s-1\fIXWarpPointer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetPointerMapping" "Xlib \- Pointer" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetPointerMapping" .XX "pointer button:mapping" .Na XGetPointerMapping \(en get the pointer button mapping. .Nz .SH "Synopsis" .Sy int XGetPointerMapping\^(\^\f(CIdisplay\f(CW, \f(CImap_return\f(CW, \f(CInmap\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; unsigned char \f(CImap_return\f(CW\^[]\^; int \f(CInmap\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CImap_return\fP Returns the mapping list. Array begins with \f(CWmap_return[]\fR. .IP \f(CInmap\fP Specifies the number of items in mapping list. .SH Returns The number of elements in the pointer list. .SH Description \f(CWXGetPointerMapping()\fP returns the current mapping of the pointer buttons. Information is returned in both the arguments and the function's return value. \f(CImap_return\fP is an array of the numbers of the buttons as they are currently mapped. Elements of the list are indexed starting from 1. The nominal mapping for a pointer is the identity mapping: \f(CWmap_return[i]=i+1\fR. If \f(CWmap[2]=2\fR, it means that the third physical button triggers the second logical button. .LP \f(CInmap\fP indicates the desired number of button mappings. .LP The return value of the function is the actual number of elements in the pointer list, which may be greater or less than \f(CInmap\fP. .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXChangePointerControl()\fP\s+1, \s-1\fIXGetPointerControl()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXQueryPointer()\fP\s+1, \s-1\fIXSetPointerMapping()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1, \s-1\fIXWarpPointer()\fP\s+1. .\"last line comment .TH XGetPointer.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XGetPointerControl@XGetPointeA .sp .5 XGetPointerMapping@XGetPointeB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetRGBColormaps" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XGetRGBColormaps" .XX "XStandardColormap structure" .XX "structures:XStandardColormap" .Na XGetRGBColormaps \(en obtain the \f(CWXStandardColormap\fR structure associated with the specified property. .Nz .SH "Synopsis" .Sy Status XGetRGBColormaps\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CIstd_colormap_return\fP\^, \ \f(CIcount_return\fP\^, \f(CIproperty\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XStandardColormap **\f(CIstd_colormap_return\fP\^; int *\f(CIcount_return\fP\^; Atom \f(CIproperty\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window. .IP \f(CIstd_colormap_return\fP 1i Returns the \f(CWXStandardColormap\fR structure. .ds Cn colormaps .IP \f(CIcount_return\fP 1i Returns the number of \*(Cn. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/GetRGBCmp 2.6 1993/05/28 13:28:34 stephen Exp $ .IP \f(CIproperty\fP 1i Specifies the property name. .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description .LP .XX "colormaps:RGB" .XX "RGB colormap definitions" \f(CWXGetRGBColormaps()\fR returns the RGB colormap definitions stored in the specified property on the named window. If the property exists, is of type \f(CWRGB_COLOR_MAP\fP, is of format 32, and is long enough to contain a colormap definition, \f(CWXGetRGBColormaps()\fR allocates and fills in space for the returned colormaps, and returns a non-zero status. Otherwise, none of the fields are set, and \f(CWXGetRGBColormaps()\fR returns a zero status. If the \f(CWvisualid\fR field is not present, \f(CWXGetRGBColormaps()\fR assumes the default visual for the screen on which the window is located; if the \f(CWkillid\fR field is not present, it is assumed to have a value of \f(CWNone\fR, which indicates that the resources cannot be released. Note that it is the caller's responsibility to honor the ICCCM restriction that only \f(CWRGB_DEFAULT_MAP\fP contain more than one definition. .LP \f(CWXGetRGBColormaps()\fP does not install the colormaps into the hardware colormap, it does not allocate entries, and it does not even create virtual colormaps. It just provides information about designs of colormap and the IDs of the colormaps if some other client has already created them. The application can otherwise attempt to create a virtual colormap of the appropriate type, and allocate its entries according to the information in the \f(CWXStandardColormap\fP structure. Installing the colormap must then be done with \f(CWXInstallColormap()\fP, in cooperation with the window manager. Any of these steps could fail, and the application should be prepared. .LP If the server or another client has already created a standard colormap of this type, then its ID will be returned in the \f(CWcolormap\fR member of the \f(CWXStandardColormap\fR structure. Some servers and window managers, particular on high-performance workstations, will create some or all of the standard colormaps so they can be quickly installed when needed by applications. .LP An application should go through the standard colormap creation process only if it needs the special qualities of the standard colormaps and if another client has not already created them. For one, they allow the application to convert RGB values into pixel values quickly because the mapping is predictable. Given an \f(CWXStandardColormap\fP structure for an \f(CWXA_RGB_BEST_MAP\fP colormap, and floating point RGB coefficients in the range 0.0 to 1.0, you can compose pixel values with the following C expression: .LP .nf .ft CW .ps 9 .vs 11 .ne 5 .ta 4.5n 9n pixel = \f(CWbase_pixel\fP + ((unsigned long) (0.5 + r * \f(CWred_max\fP)) * \f(CWred_mult\fP + ((unsigned long) (0.5 + g * \f(CWgreen_max\fP)) * \f(CWgreen_mult\fP + ((unsigned long) (0.5 + b * \f(CWblue_max\fP)) * \f(CWblue_mult\fP; .ps .vs .fi .ft R .LP The use of addition rather than logical-OR for composing pixel values permits allocations where the RGB value is not aligned to bit boundaries. .LP \f(CWXGetRGBColormaps()\fP supersedes \f(CWXGetStandardColormap()\fP. .LP For more information, see Volume One, Chapter 7, \fIColor\fP. .SH "Structures" .Ps typedef struct { Colormap colormap; unsigned long red_max; unsigned long red_mult; unsigned long green_max; unsigned long green_mult; unsigned long blue_max; unsigned long blue_mult; unsigned long base_pixel; VisualID visualid; /* added by ICCCM version 1 */ XID killid; /* added by ICCCM version 1 */ } XStandardColormap; .Pe .SH "Errors" \f(CWBadAtom\fR .br \f(CWBadWindow\fR .Nd 6 .SH "See Also" \s-1\fIXAllocStandardColormap()\fP\s+1, \s-1\fIXSetRGBColormaps()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetScreenSaver" "Xlib \- Screen Saver" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetScreenSaver" .XX "screen savers:obtaining parameters of" .Na XGetScreenSaver \(en get the current screen saver parameters. .Nz .SH "Synopsis" .Sy XGetScreenSaver\^(\^\f(CIdisplay\f(CW, \f(CItimeout_return\f(CW\^, \f(CIinterval_return\f(CW\^, .br \f(CIprefer_blanking_return\f(CW\^, \f(CIallow_exposures_return\f(CW\^) .br Display *\f(CIdisplay\f(CW\^; .As int *\f(CItimeout_return\f(CW\^, *\f(CIinterval_return\f(CW\^; int *\f(CIprefer_blanking_return\f(CW\^; int *\f(CIallow_exposures_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CItimeout_return\fP 1i Returns the idle time, in seconds, until the screen saver turns on. .IP \f(CIinterval_return\fP 1i Returns the interval between screen saver invocations, in seconds. .IP \f(CIprefer_blanking_return\fP 1i Returns the current screen blanking preference, one of these constants: \f(CWDontPreferBlanking\fP, \f(CWPreferBlanking\fP, or \f(CWDefaultBlanking\fP. .IP \f(CIallow_exposures_return\fP 1i Returns the current screen save control value, either \f(CWDontAllowExposures\fP, \f(CWAllowExposures\fP, or \f(CWDefaultExposures\fP. .SH Description \f(CWXGetScreenSaver()\fP returns the current settings of the screen saver, which may be set with \f(CWXSetScreenSaver()\fP. .LP A positive \f(CItimeout_return\fP indicates that the screen saver is enabled. A \f(CItimeout_return\fP of zero indicates that the screen saver is disabled. .LP If the server-dependent screen saver method supports periodic change, \f(CIinterval_return\fP serves as a hint about the length of the change period, and zero serves as a hint that no periodic change will be made. An \f(CIinterval_return\fP of zero indicates that random pattern motion is disabled. .LP For more information on the screen saver, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "See Also" \s-1\fIXActivateScreenSaver()\fP\s+1, \s-1\fIXForceScreenSaver()\fP\s+1, \s-1\fIXResetScreenSaver()\fP\s+1, \s-1\fIXSetScreenSaver()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetSelectionOwner" "Xlib \- Selections" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetSelectionOwner" .XX "selections:returning owner of" .Na XGetSelectionOwner \(en return the owner of a selection. .Nz .SH "Synopsis" .Sy Window XGetSelectionOwner\^(\^\f(CIdisplay\f(CW, \f(CIselection\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Atom \f(CIselection\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIselection\fP 1i Specifies the selection atom whose owner you want returned. .SH Returns The window associated with the selection owner. .SH Description \f(CWXGetSelectionOwner()\fP returns the window ID of the current owner of the specified selection. If no selection was specified, or there is no owner, the function returns the constant \f(CWNone\fP. .LP For more information on selections, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Errors" \f(CWBadAtom\fP .SH "See Also" \s-1\fIXConvertSelection()\fP\s+1, \s-1\fIXSetSelectionOwner()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetSizeHints" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetSizeHints" .XX "size hints" .XX "XA_WM_SIZE_HINTS property" .Na XGetSizeHints \(en read any property of type \f(CWXA_WM_SIZE_HINTS\fP. .Nz .SH "Synopsis" .Sy Status XGetSizeHints\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIhints_return\f(CW, \f(CIproperty\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; XSizeHints *\f(CIhints_return\f(CW\^; Atom \f(CIproperty\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window for which size hints will be returned. .IP \f(CIhints_return\fP 1i Returns the size hints structure. .IP \f(CIproperty\fP 1i Specifies a property atom of type \f(CWXA_WM_SIZE_HINTS\fP. .hw NORMAL May be \f(CWXA_WM_NORMAL_HINTS\fP, \f(CWXA_WM_ZOOM_HINTS\fP (in Release 3), or a property defined by an application. .SH Returns Zero on failure, non-zero on success. .SH Description .XX "XGetWMSizeHints:and XGetSizeHints" \f(CWXGetSizeHints()\fP has been superseded by \f(CWXGetWMSizeHints()\fP as of Release 4, because the interclient communication conventions are now standard. .LP \f(CWXGetSizeHints()\fP returns the \f(CWXSizeHints\fP structure for the named property and the specified window. \f(CWXGetSizeHints()\fP is used by \f(CWXGetNormalHints()\fP and \f(CWXGetZoomHints()\fP, and can be used to retrieve the value of any property of type \f(CWXA_WM_SIZE_HINTS\fP; thus, it is useful if other properties of that type get defined. This function is used almost exclusively by window managers. .LP \f(CWXGetSizeHints()\fP returns a non-zero \f(CWStatus\fP if a size hint was defined, and zero otherwise. .LP For more information on using hints, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Structures" .Ps typedef struct { long flags; /* which fields in structure are defined */ int x, y; int width, height; int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; int base_width, base_height; int win_gravity } XSizeHints; /* flags argument in size hints */ #define USPosition (1L << 0) /* user specified x, y */ #define USSize (1L << 1) /* user specified width, height */ #define PPosition (1L << 2) /* program specified position */ #define PSize (1L << 3) /* program specified size */ #define PMinSize (1L << 4) /* program specified minimum size */ #define PMaxSize (1L << 5) /* program specified maximum size */ #define PResizeInc (1L << 6) /* program specified resize increments */ #define PAspect (1L << 7) /* program specified min/max aspect ratios */ #define PAllHints (PPosition PSize PMinSize PMaxSize PResizeInc PAspect) #define PBaseSize (1L << 8) #define PWinGravity (1L << 9) .Pe .SH "Errors" \f(CWBadAtom\fP .br \f(CWBadWindow\fP .br .ne 5 .SH "See Also" \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetStandardColormap" "Xlib \- Colormaps" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetStandardColormap" .XX "colormaps:standard properties" .Na XGetStandardColormap \(en get the standard colormap property. .Nz .SH "Synopsis" .Sy Status XGetStandardColormap(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIcmap_info_return\f(CW, \f(CIproperty\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; XStandardColormap *\f(CIcolormap_return\f(CW\^; Atom \f(CIproperty\f(CW\^; .LP .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window on which the property is set. This is normally the root window. .IP \f(CIcolormap_return\fP 1i Returns the filled colormap information structure. .IP \f(CIproperty\fP 1i Specifies the atom indicating the type of standard colormap desired. The predefined standard colormap atoms are \f(CWXA_RGB_BEST_MAP\fP, \f(CWXA_RGB_RED_MAP\fP, \f(CWXA_RGB_GREEN_MAP\fP, \f(CWXA_RGB_BLUE_MAP\fP, \f(CWXA_RGB_DEFAULT_MAP\fP, and \f(CWXA_RGB_GRAY_MAP\fP. .SH Returns Zero on failure, non-zero on success. .SH Description .XX "XGetWMColormap:and XGetStandardColormap \f(CWXGetStandardColormap()\fP is superseded by \f(CWXGetRGBColormaps()\fP in Release 4. \f(CWXGetStandardColormap()\fP gets a property on the root window that describes a standard colormap. \f(CWXGetStandardColormap()\fP returns zero if it fails, or non-zero if it succeeds. .LP See Volume One, Chapter 7, \fIColor\fR, for a complete description of standard colormaps. .SH "Structures" .Ps typedef struct { Colormap colormap; /* ID of colormap created by XCreateColormap */ unsigned long red_max; unsigned long red_mult; unsigned long green_max; unsigned long green_mult; unsigned long blue_max; unsigned long blue_mult; unsigned long base_pixel; VisualID visualid; XID killid; } XStandardColormap; .Pe .Nd 10 .SH "Errors" \f(CWBadAtom\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXDefaultColormap()\fP\s+1, \s-1\fIXDisplayCells()\fP\s+1, \s-1\fIXCopyColormapAndFree()\fP\s+1, \s-1\fIXCreateColormap()\fP\s+1, \s-1\fIXFreeColormap()\fP\s+1, \s-1\fIXInstallColormap()\fP\s+1, \s-1\fIXListInstalledColormaps()\fP\s+1, \s-1\fIXSetStandardColormap()\fP\s+1, \s-1\fIXSetWindowColormap()\fP\s+1, \s-1\fIXUninstallColormap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH XGetSubImage "Xlib \- Images" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XGetSubImage" .XX "images:subimages" .XX "subimages" XGetSubImage \(en copy a rectangle in drawable to a location within the pre-existing image. .Nz .SH "Synopsis" .Sy XImage *XGetSubImage\^(\^\f(CIdisplay\f(CW, \f(CIdrawable\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^, .in +10n \f(CIplane_mask\f(CW, \f(CIformat\f(CW\^, \f(CIdest_image\f(CW\^, \f(CIdest_x\f(CW\^, \f(CIdest_y\f(CW\^) .in -10n .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIdrawable\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; unsigned long \f(CIplane_mask\f(CW\^; int \f(CIformat\f(CW\^; XImage *\f(CIdest_image\f(CW\^; int \f(CIdest_x\f(CW\^, \f(CIdest_y\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdrawable\fP 1i Specifies the drawable from which the rectangle is to be copied. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the upper-left corner of the rectangle, relative to the origin of the drawable. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight\fP 1i .sp -2 Specify the width and height in pixels of the subimage taken. .sp .IP \f(CIplane_mask\fP 1i Specifies which planes of the drawable are transferred to the image. .IP \f(CIformat\fP 1i Specifies the format for the image. Either \f(CWXYPixmap\fP or \f(CWZPixmap\fP. .IP \f(CIdest_image\fP 1i Specifies the destination image. .IP \f(CIdest_x\fP 1i .br .ns .IP \f(CIdest_y\fP 1i .sp -2 Specify the x and y coordinates of the destination rectangle's upper-left corner, relative to the image's origin. .SH Returns The same image specified by \f(CIdest_image\fP. .SH Description \f(CWXGetSubImage()\fP updates the \f(CIdest_image\fP with the specified subimage in the same manner as \f(CWXGetImage()\fP, except that it does not create the image or necessarily fill the entire image. If \f(CIformat\fP is \f(CWXYPixmap\fP, the function transmits only the bit planes you specify in \f(CIplane_mask\fP. If \f(CIformat\fP is \f(CWZPixmap\fP, the function transmits as zero the bits in all planes not specified in \f(CIplane_mask\fP. The function performs no range checking on the values in \f(CIplane_mask\fP and ignores extraneous bits. .LP The depth of the destination \f(CWXImage\fP structure must be the same as that of the drawable. Otherwise, a \f(CWBadMatch\fP error is generated. If the specified subimage does not fit at the specified location on the destination image, the right and bottom edges are clipped. If the drawable is a window, the window must be mapped or held in backing store, and it must be the case that, if there were no inferiors or overlapping windows, the .ne 2 specified rectangle of the window would be fully visible on the screen. Otherwise, a \f(CWBadMatch\fP error is generated. .LP If the window has a backing store, the backing store contents are returned for regions of the window that are obscured by noninferior windows. Otherwise, the return contents of such obscured regions are undefined. Also undefined are the returned contents of visible regions of inferiors of different depth than the specified window. .LP \f(CWXSubImage()\fP extracts a subimage from an image, instead of from a drawable like \f(CWXGetSubImage()\fP. .LP If a problem occurs, \f(CWXGetSubImage()\fR returns \f(CWNULL\fP. .LP For more information on images, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .br .ne 7 .SH "Errors" .IP "\f(CWBadDrawable\fP" 1i .IP "\f(CWBadGC\fR" .IP "\f(CWBadMatch\fP" Depth of \f(CIdest_image\fP is not the same as depth of \f(CIdrawable\fP. .IP "\f(CWBadValue\fP" .SH "See Also" \s-1\fIXImageByteOrder()\fP\s+1, \s-1\fIXAddPixel()\fP\s+1, \s-1\fIXCreateImage()\fP\s+1, \s-1\fIXDestroyImage()\fP\s+1, \s-1\fIXGetImage()\fP\s+1, \s-1\fIXGetPixel()\fP\s+1, \s-1\fIXPutImage()\fP\s+1, \s-1\fIXPutPixel()\fP\s+1, \s-1\fIXSubImage()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetTextProperty" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XGetTextProperty" .XX "text properties" .Na XGetTextProperty \(en read one of a window's text properties. .Nz .SH "Synopsis" .Sy Status XGetTextProperty\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CItext_prop_return\fP\^, \ \f(CIproperty\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XTextProperty *\f(CItext_prop_return\fP\^; Atom \f(CIproperty\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window. .IP \f(CItext_prop_return\fP 1i Returns the \f(CWXTextProperty\fR structure. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/GetTextProp 2.5 1993/05/28 13:28:43 stephen Exp $ .IP \f(CIproperty\fP 1i Specifies the property name. .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description .LP \f(CWXGetTextProperty()\fR reads the specified property from the window and stores the data in the returned \f(CWXTextProperty\fR structure. It stores the data in the \f(CWvalue\fP field, the type of the data in the \f(CWencoding\fP field, the format of the data in the \f(CWformat\fP field, and the number of items of data in the \f(CWnitems\fP field. An extra byte containing null (which is not included in the \f(CWnitems\fR number) is stored at the end of the value field of \f(CItext_prop_return\fR. The particular interpretation of the property's encoding and data as ``text'' is left to the calling application. If the specified property does not exist on the window, \f(CWXGetTextProperty()\fR sets the value field to \f(CWNULL\fP, the encoding field to \f(CWNone\fP, the format field to zero, and the \f(CWnitems\fP field to zero. .LP If it was able to set these files in the \f(CWXTextProperty\fR structure, \f(CWXGetTextProperty()\fR returns a non-zero status; otherwise, it returns a zero status. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .Nd 20 .SH "Structures" .Ps typedef struct { unsigned char *value; /* same as Property routines */ Atom encoding; /* prop type */ int format; /* prop data format: 8, 16, or 32 */ unsigned long nitems; /* number of data items in value */ } XTextProperty; .XX "XTextProperty structure" .XX "structures:XTextProperty" .Pe .SH "Errors" \f(CWBadAtom\fR .br \f(CWBadWindow\fR .Nd 10 .SH "See Also" \s-1\fIXFreeStringList()\fP\s+1, \s-1\fIXSetTextProperty()\fP\s+1, \s-1\fIXStringListToTextProperty()\fP\s+1, \s-1\fIXTextPropertytoStringList\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetTransientForHint" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XGetTransientForHint" .XX "XA_WM_TRANSIENT_FOR property" .XX "window manager:XA_WM_TRANSIENT_FOR property" XGetTransientForHint \(en get the \f(CWXA_WM_TRANSIENT_FOR\fP property of a window. .Nz .SH "Synopsis" .Sy Status XGetTransientForHint\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIprop_window_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; Window *\f(CIprop_window_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window to be queried. .IP \f(CIprop_window_return\fP 1i Returns the window contained in the \f(CWXA_WM_TRANSIENT_FOR\fP property of the specified window. .SH Returns Zero on failure, non-zero on success. .SH Description .XX "windows:temporary" \f(CWXGetTransientForHint()\fP obtains the \f(CWXA_WM_TRANSIENT_FOR\fP property for the specified window. \f(CWXGetTransientForHint()\fP is normally used by a window manager. This property should be set for windows that are to appear only temporarily on the screen, such as pop-up dialog boxes. The window returned is the main window to which this popup window is related. This lets the window manager decorate the popup window appropriately. .LP \f(CWXGetTransientForHint()\fP returns a \f(CWStatus\fP of zero on failure, and non-zero on success. .LP For more information on using hints, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetVisualInfo" "Xlib \- Visuals" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetVisualInfo" .Na XGetVisualInfo \(en find the visual information structures that match the specified template. .Nz .SH "Synopsis" .Sy XVisualInfo *XGetVisualInfo\^(\^\f(CIdisplay\f(CW, \f(CIvinfo_mask\f(CW, \f(CIvinfo_template\f(CW, \f(CInitems_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; long \f(CIvinfo_mask\f(CW\^; XVisualInfo *\f(CIvinfo_template\f(CW\^; int *\f(CInitems_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIvinfo_mask\fP 1i Specifies the visual mask value. Indicates which elements in template are to be matched. .IP \f(CIvinfo_template\fP 1i Specifies the visual attributes that are to be used in matching the visual structures. .IP \f(CInitems_return\fP 1i Returns the number of matching visual structures. .SH Returns The visual information structure. .SH Description .XX "visuals:visual structures, returning list of" \f(CWXGetVisualInfo()\fP returns a list of visual structures that describe visuals supported by the server and that match the attributes specified by the \f(CIvinfo_template\fP argument. If no visual structures match the template fields specified in \f(CWVinfo_mask\fR, \f(CWXGetVisualInfo()\fP returns a \f(CWNULL\fP. To free the data returned by this function, use \f(CWXFree()\fP. .LP For more information, see Volume One, Chapter 7, \fIColor\fR. .SH "Structures" .Ps typedef struct { Visual *visual; VisualID visualid; int screen; unsigned int depth; int class; unsigned long red_mask; unsigned long green_mask; unsigned long blue_mask; int colormap_size; int bits_per_rgb; } XVisualInfo; .XX "XVisualInfo structure" .XX "structures:XVisualInfo" .XN "visuals:(see also XVisualInfo structure) /* The symbols for the vinfo_mask argument are: */ #define VisualNoMask 0x0 #define VisualIDMask 0x1 #define VisualScreenMask 0x2 #define VisualDepthMask 0x4 #define VisualClassMask 0x8 #define VisualRedMaskMask 0x10 #define VisualGreenMaskMask 0x20 #define VisualBlueMaskMask 0x40 #define VisualColormapSizeMask 0x80 #define VisualBitsPerRGBMask 0x100 #define VisualAllMask 0x1FF .Pe .SH "See Also" \s-1\fIXDefaultVisual()\fP\s+1, \s-1\fIXVisualIDFromVisual()\fP\s+1, \s-1\fIXMatchVisualInfo()\fP\s+1, \s-1\fIXListDepths()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetWMClientMachine" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XGetWMClientMachine" .XX "WM_CLIENT_MACHINE property" .XX "window manager:WM_CLIENT_MACHINE property" .Na XGetWMClientMachine \(en get a window's \f(CWXA_WM_CLIENT_MACHINE\fP property. .Nz .SH "Synopsis" .Sy Status XGetWMClientMachine\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CItext_prop_return\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XTextProperty *\f(CItext_prop_return\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/GetWMClientMa 2.6 1993/05/28 13:28:47 stephen Exp $ .IP \f(CIw\fP 1i Specifies the window. .IP \f(CItext_prop_return\fP 1i Returns the \f(CWXTextProperty\fR structure that describes the machine the client is running on. .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description .hw CLIENT .LP .XX "window manager:client machines" .XX "XGetTextProperty:and XGetWMClientMachine" \f(CWXGetWMClientMachine()\fR performs an \f(CWXGetTextProperty()\fR to get the WM_CLIENT_MACHINE property of the specified window. This property should contain the name of the host machine on which this client is being run, as seen from the server. This function returns non-zero status in success; otherwise it returns a zero status. .LP This function is normally used along with \f(CWXGetCommand()\fP by a session manager or window manager to get complete information on how to reinvoke an application. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .Ps typedef struct { unsigned char *value; /* same as Property routines */ Atom encoding; /* prop type */ int format; /* prop data format: 8, 16, or 32 */ unsigned long nitems; /* number of data items in value */ } XTextProperty; .XX "XTextProperty structure" .XX "structures:XTextProperty" .Pe .SH "See Also" \s-1\fIXSetWMClientMachine()\fP\s+1, \s-1\fIXGetCommand()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetWMColormapWindows" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "window manager:colormap windows" .XX "XGetWMColormapWindows" .XX "WM_COLORMAP_WINDOWS property" .XX "window manager:WM_COLORMAP_WINDOWS property" .XN "window manager:(see also WM_ properties)" .Na XGetWMColormapWindows \(en get a window's WM_COLORMAP_WINDOWS property. .Nz .SH "Synopsis" .Sy Status XGetWMColormapWindows\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \ \f(CIcolormap_windows_return\fP\^, \f(CIcount_return\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; Window *\f(CIcolormap_windows_return\fP\^; int \f(CIcount_return\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/GetWMCmpWind 2.7 1993/05/28 13:28:48 stephen Exp $ .IP \f(CIw\fP 1i Specifies the top-level window of an application. .IP \f(CIcolormap_windows_return\fP 1i Returns the list of windows that have custom colormaps. .ds Cn windows in the list .IP \f(CIcount_return\fP 1i Returns the number of \*(Cn. .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description .XX "colormaps:XGetWMColormapWindows" .LP \f(CWXGetWMColormapWindows()\fR gets the WM_COLORMAP_WINDOWS property on the specified window. This property contains a list of windows that have custom colomaps that need to be installed. The \f(CWXGetWMColormapWindows()\fR function stores the list in its \f(CIcolormap_windows_return\fP argument. .LP If the property exists, if it is of type WINDOW, if it is of format 32, and if the atom WM_COLORMAP_WINDOWS can be interned, \f(CWXGetWMColormapWindows()\fP sets the \f(CIcolormap_windows_return\fP argument to a list of window identifiers, sets the \f(CIcount_return\fP argument to the number of elements in list, and returns a non-zero status. Otherwise, it sets neither of the return arguments and returns a zero status. To release the list of window identifiers, use \f(CWXFree()\fP. .LP This function is called by window managers to find out what colormaps to install and when to install them. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .ne 8 .SH "Errors" \f(CWBadWindow\fR .SH "See Also" \s-1\fIXSetWMColormapWindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetWMHints" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetWMHints" .XX "window manager:hints property" .Na XGetWMHints \(en read the window manager hints property. .Nz .SH "Synopsis" .Sy XWMHints *XGetWMHints\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP .88i Specifies the ID of the window to be queried. .SH Returns The window manager hints structure. .SH Description .XX "XA_WM_HINTS property" .XX "window manager:XA_WM_HINTS property" This function is primarily for window managers. \f(CWXGetWMHints()\fP returns \f(CWNULL\fP if no \f(CWXA_WM_HINTS\fP property was set on window \f(CIw\fP, and returns a pointer to an \f(CWXWMHints\fP structure if it succeeds. Programs must free the space used for that structure by calling \f(CWXFree()\fP. .LP For more information on using hints, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH Structures .Ps .ta 4.5n 1.8i typedef struct { long flags; /* marks which fields in this structure are defined */ Bool input; /* does application need window manager for input */ int initial_state; /* see below */ Pixmap icon_pixmap; /* pixmap to be used as icon */ Window icon_window; /* window to be used as icon */ int icon_x, icon_y; /* initial position of icon */ Pixmap icon_mask; /* icon mask bitmap */ XID window_group; /* ID of related window group */ /* this structure may be extended in the future */ } XWMHints; .XX "XWMHints structure" .XX "structures:XWMHints" /* initial state flag: */ #define DontCareState 0 #define NormalState 1 #define ZoomState 2 #define IconicState 3 #define InactiveState 4 .Pe .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXAllocWMHints()\fP\s+1, \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetWMIconName" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XGetWMIconName" .XX "XA_WM_ICON_NAME property" .XX "window manager:XA_WM_ICON_NAME property" .XX "window manager:icon names" .Na XGetWMIconName \(en read a window's \f(CWXA_WM_ICON_NAME\fP property. .Nz .SH "Synopsis" .Sy Status XGetWMIconName\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CItext_prop_return\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XTextProperty *\f(CItext_prop_return\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window. .IP \f(CItext_prop_return\fP 1i Returns the \f(CWXTextProperty\fR structure. This structure should be freed when no longer needed. .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description .XX "icon names" .XX "XGetTextProperty:and XGetWMIconName" .LP \f(CWXGetWMIconName()\fR performs an \f(CWXGetTextProperty()\fR on the \f(CWXA_WM_ICON_NAME\fP property of the specified window. \f(CWXGetWMIconName()\fP supersedes \f(CWXGetIconName()\fP. .XX "XGetIconName:and XGetWMIconName" .LP This function is primarily used by window managers to get the name to be written in a window's icon when they need to display that icon. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .Ps typedef struct { unsigned char *value; /* same as Property routines */ Atom encoding; /* prop type */ int format; /* prop data format: 8, 16, or 32 */ unsigned long nitems; /* number of data items in value */ } XTextProperty; .XX "XTextProperty structure" .XX "structures:XTextProperty" .Pe .SH "See Also" \s-1\fIXGetWMName()\fP\s+1, \s-1\fIXSetWMIconName()\fP\s+1, \s-1\fIXSetWMName()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetWMName" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "window manager:names" .XX "XGetWMName" .XX "XA_WM_NAME property" .XX "window manager:XA_WM_NAME property" .Na XGetWMName \(en read a window's \f(CWXA_WM_NAME\fP property. .Nz .SH "Synopsis" .Sy Status XGetWMName\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CItext_prop_return\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XTextProperty *\f(CItext_prop_return\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window. .IP \f(CItext_prop_return\fP 1i Returns the \f(CWXTextProperty\fR structure. This structure should be freed when no longer needed. .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description .XX "XGetTextProperty:and XGetWMName" .LP \f(CWXGetWMName()\fR performs an \f(CWXGetTextProperty()\fR on the \f(CWXA_WM_NAME\fP property of the specified window. \f(CWXGetWMName()\fP supersedes \f(CWXFetchName()\fP. .XX "XFetchName:and XGetWMName" .LP \f(CWXGetWMName()\fP returns non-zero if it succeeds, and zero if the property has not been set for the argument window. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .Ps typedef struct { unsigned char *value; /* same as Property routines */ Atom encoding; /* prop type */ int format; /* prop data format: 8, 16, or 32 */ unsigned long nitems; /* number of data items in value */ } XTextProperty; .XX "XTextProperty structure" .XX "structures:XTextProperty" .Pe .SH "See Also" \s-1\fIXGetWMIconName()\fP\s+1, \s-1\fIXSetWMIconName()\fP\s+1, \s-1\fIXSetWMName()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetWMNormalHints" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "window manager:normal hints" .XX "XGetWMNormalHints" .XX "XA_WM_NORMAL_HINTS property" .XX "window manager:XA_WM_NORMAL_HINTS property" .Na XGetWMNormalHints \(en read a window's \f(CWXA_WM_NORMAL_HINTS\fP property. .Nz .SH "Synopsis" .Sy Status XGetWMNormalHints\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CIhints_return\fP\^, \ \f(CIsupplied_return\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XSizeHints *\f(CIhints_return\fP\^; long *\f(CIsupplied_return\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/GetWMNormHint 2.6 1993/05/28 13:28:54 stephen Exp $ .IP \f(CIw\fP 1i Specifies the window. .IP \f(CIhints_return\fP 1i Returns the size hints for the window in its normal state. .IP \f(CIsupplied_return\fP 1i Returns the hints that were supplied by the user. .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description .XX "size hints:stored in XA_WM_NORMAL_HINTS property" .LP \f(CWXGetWMNormalHints()\fR returns the size hints stored in the \f(CWXA_WM_NORMAL_HINTS\fP property on the specified window. If the property is of type \f(CWXA_WM_SIZE_HINTS\fP, of format 32, and is long enough to contain either an old (pre-ICCCM) or new size hints structure, \f(CWXGetWMNormalHints()\fR sets the various fields of the \f(CWXSizeHints\fR structure, sets the \f(CIsupplied_return\fP argument to the list of fields that were supplied by the user (whether or not they contained defined values) and returns a non-zero status. \f(CWXGetWMNormalHints()\fP returns a zero status if the application specified no normal size hints for this window. .LP .XX "XGetNormalHints:and XGetWMNormalHints" \f(CWXGetWMNormalHints()\fP supersedes \f(CWXGetNormalHints()\fP. .LP If \f(CWXGetWMNormalHints()\fR returns successfully and a pre-ICCCM size hints property is read, the \f(CIsupplied_return\fP argument will contain the following bits: .Ps (USPosition USSize PPosition PSize PMinSize PMaxSize PResizeInc PAspect) .Pe .Nd 5 If the property is large enough to contain the base size and window gravity fields as well, the \f(CWsupplied\fP argument will also contain the following bits: .Ps (PBaseSize PWinGravity) .Pe This function is normally used only by a window manager. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .Ps typedef struct { long flags; /* marks which fields in this structure are defined */ int x, y; /* obsolete for new window mgrs, but clients */ int width, height; /* should set so old wm's don't mess up */ int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; int base_width, base_height; /* added by ICCCM version 1 */ int win_gravity; /* added by ICCCM version 1 */ } XSizeHints; .XX "XSizeHints structure" .XX "structures:XSizeHints" .Pe .SH "Errors" \f(CWBadWindow\fR .SH "See Also" \s-1\fIXAllocSizeHints()\fP\s+1, \s-1\fIXGetWMSizeHints()\fP\s+1, \s-1\fIXSetWMNormalHints()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1, \s-1\fIXSetWMSizeHints()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetWMProtocols" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XGetWMProtocols" .XX "WM_PROTOCOLS property" .XX "window manager:WM_PROTOCOLS property" .Na XGetWMProtocols \(en get a window's WM_PROTOCOLS property. .Nz .SH "Synopsis" .Sy Status XGetWMProtocols\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CIprotocols_return\fP\^, \ \f(CIcount_return\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; Atom **\f(CIprotocols_return\fP\^; int *\f(CIcount_return\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/GetWMProtocol 2.8 1993/05/28 13:28:56 stephen Exp $ .IP \f(CIw\fP 1i Specifies the window. .IP \f(CIprotocols_return\fP 1i Returns the list of protocols. .ds Cn protocols in the list .IP \f(CIcount_return\fP 1i Returns the number of \*(Cn. .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description .LP .XX "window manager:protocols" \f(CWXGetWMProtocols()\fR gets the list of atoms stored in the WM_PROTOCOLS property of the specified window. These atoms describe window manager protocols in which the owner of this window is willing to participate. .LP If the property exists, is of type ATOM, is of format 32, and the atom WM_PROTOCOLS can be interned, \f(CWXGetWMProtocols()\fP sets the \f(CIprotocols_return\fP argument to a list of atoms, sets the \f(CIcount_return\fP argument to the number of elements in list, and returns a a non-zero status. Otherwise, it sets neither of the return arguments and returns a zero status. .LP The list of standard protocols at present is as follows: .in +5n .XX "WM_TAKE_FOCUS protocol" .IP WM_TAKE_FOCUS 1.75i Assignment of keyboard focus. .XX "WM_SAVE_YOURSELF protocol" .IP WM_SAVE_YOURSELF 1.75i Save client state warning. .XX "WM_DELETE_UNKNOWN protocol" .IP WM_DELETE_UNKNOWN 1.75i Request to delete top-level window. .in -5n .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .Nd 8 .SH "Errors" \f(CWBadWindow\fR .SH "See Also" \s-1\fIXSetWMProtocols()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetWMSizeHints" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "window manager:size hints" .XX "XGetWMSizeHints" .XX "XA_WM_SIZE_HINTS property" .XX "window manager:XA_WM_SIZE_HINTS property" .Na XGetWMSizeHints \(en read a window's \f(CWXA_WM_SIZE_HINTS\fP property. .Nz .SH "Synopsis" .Sy .hw property Status XGetWMSizeHints\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CIhints_return\fP\^, \ \f(CIsupplied_return\fP\^, \f(CIproperty\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XSizeHints *\f(CIhints_return\fP\^; long *\f(CIsupplied_return\fP\^; Atom \f(CIproperty\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window. .IP \f(CIhints_return\fP 1i Returns the \f(CWXSizeHints\fR structure. .IP \f(CIsupplied_return\fP 1i Returns the hints that were supplied by the user. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/GetWMSizHints 2.8 1993/05/28 13:28:58 stephen Exp $ .IP \f(CIproperty\fP 1i Specifies the property name. .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description .LP \f(CWXGetWMSizeHints()\fR returns the size hints stored in the specified property on the named window. If the property is of type \f(CWXA_WM_SIZE_HINTS\fP, of format 32, and is long enough to contain either an old (pre-ICCCM) or new size hints structure, \f(CWXGetWMSizeHints()\fR sets the various fields of the \f(CWXSizeHints\fR structure, sets the \f(CIsupplied_return\fP argument to the list of fields that were supplied by the user (whether or not they contained defined values), and returns a non-zero status. If the hint was not set, it returns a zero status. To get a window's normal size hints, you can use the \f(CWXGetWMNormalHints()\fR function instead. .LP .XX "XGetSizeHints:and XGetWMSizeHints" \f(CWXGetWMSizeHints()\fP supersedes \f(CWXGetSizeHints()\fP. .LP If \f(CWXGetWMSizeHints()\fR returns successfully and a pre-ICCCM size hints property is read, the \f(CIsupplied_return\fP argument will contain the following bits: .Ps (USPosition USSize PPosition PSize PMinSize PMaxSize PResizeInc PAspect) .Pe .Nd 12 If the property is large enough to contain the base size and window gravity fields as well, the \f(CWsupplied\fP argument will also contain the following bits: .Ps (PBaseSize PWinGravity) .Pe This function is used almost exclusively by window managers. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .Ps typedef struct { long flags; /* marks which fields in this structure are defined */ int x, y; /* obsolete for new window mgrs, but clients */ int width, height; /* should set so old wm's don't mess up */ int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; int base_width, base_height; /* added by ICCCM version 1 */ int win_gravity; /* added by ICCCM version 1 */ } XSizeHints; .XX "XSizeHints structure" .XX "structures:XSizeHints" .Pe .SH "Errors" \f(CWBadAtom\fR .br \f(CWBadWindow\fR .SH "See Also" \s-1\fIXAllocSizeHints()\fP\s+1, \s-1\fIXGetWMNormalHints()\fP\s+1, \s-1\fIXSetWMNormalHints()\fP\s+1, \s-1\fIXSetWMSizeHints()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetWindowAttributes" "Xlib \- Window Attributes" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetWindowAttributes" .XX "window attributes:obtaining" .Na XGetWindowAttributes \(en obtain the current attributes of window. .Nz .SH "Synopsis" .Sy Status XGetWindowAttributes\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIwindow_attributes_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; XWindowAttributes *\f(CIwindow_attributes_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the window whose current attributes you want. .IP \f(CIwindow_attributes_return\fP Returns a filled \f(CWXWindowAttributes\fP structure, containing the current attributes for the specified window. .SH Returns Zero on failure, non-zero on success. .SH Description .XX "XWindowAttributes structure" \f(CWXGetWindowAttributes()\fP returns the \f(CWXWindowAttributes\fP structure containing the current window attributes. .LP \f(CWXGetWindowAttributes()\fP returns a \f(CWStatus\fR of zero on failure, or non-zero on success. However, it will only return zero if you have defined an error handler that does not exit, using \f(CWXSetErrorHandler()\fP. The default error handler exits, and therefore \f(CWXGetWindowAttributes()\fP never gets a chance to return. (Such error handling is relevant only if you are writing a window manager or other application that deals with windows that might have been destroyed.) .LP The following list briefly describes each member of the \f(CWXWindowAttributes\fP structure. For more information, see Volume One, Chapter 4, \fIWindow Attributes\fP. .LP .IP "\f(CWx, y\fP" 1.15i The current position of the upper-left pixel of the window's border, relative to the origin of its parent. .IP "\f(CWwidth, height\fP" The current dimensions in pixels of this window, not including the border. .IP "\f(CWborder_width\fP" The current border width of the window. .IP \f(CWdepth\fP The number of bits per pixel in this window. .IP \f(CWvisual\fP The visual structure. .IP \f(CWroot\fP The root window ID of the screen containing the window. .IP \f(CWclass\fP The window class. One of these constants: \f(CWInputOutput\fP or \f(CWInputOnly\fP. .IP \f(CWbit_gravity\fP The new position for existing contents after resize. One of the constants \f(CWForgetGravity\fP, \f(CWStaticGravity\fP, or \f(CWCenterGravity\fP, or one of the compass constants (\f(CWNorthWestGravity\fP, \f(CWNorthGravity\fP, etc.). .Nd 10 .IP \f(CWwin_gravity\fP The new position for this window after its parent is resized. One of the constants \f(CWCenterGravity\fP, \f(CWUnmapGravity\fP, \f(CWStatic\%Gravity\fP, or one of the compass constants. .IP \f(CWbacking_store\fP When to maintain contents of the window. One of these constants: \f(CWNotUseful\fP, \f(CWWhenMapped\fP, or \f(CWAlways\fP. .IP \f(CWbacking_planes\fP The bit planes to be preserved in a backing store. .IP \f(CWbacking_pixel\fP The pixel value used when restoring planes from a partial backing store. .IP \f(CWsave_under\fP A boolean value, indicating whether saving bits under this window would be useful. .IP \f(CWcolormap\fP The colormap ID being used in this window, or \f(CWNone\fP. .br .ne 4 .IP \f(CWmap_installed\fP A boolean value, indicating whether the colormap is currently installed. If \f(CWTrue\fP, the window is being displayed in its chosen colors. .IP \f(CWmap_state\fP The window's map state. One of these constants: \f(CWIsUnmapped\fP, \f(CWIsUnviewable\fP, or \f(CWIsViewable\fP. \f(CWIsUnviewable\fP indicates that the specified window is mapped but some ancestor is unmapped. .IP \f(CWall_event_masks\fP The set of events any client have selected. This member is the bitwise inclusive OR of all event masks selected on the window by all clients. .IP \f(CWyour_event_mask\fP The bitwise inclusive OR of all event mask symbols selected by the querying client. .IP \f(CWdo_not_propagate_mask\fP The bitwise inclusive OR of the event mask symbols that specify the set of events that should not propagate. This is global across all clients. .IP \f(CWoverride_redirect\fP A boolean value, indicating whether this window will override structure control facilities. This is usually only used for temporary pop-up windows such as menus. Either \f(CWTrue\fP or \f(CWFalse\fP. .IP \f(CWscreen\fP A pointer to the \f(CWScreen\fP structure for the screen containing this window. .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadWindow\fP .SH Structures The \f(CWXWindowAttributes\fP structure contains: .Ps .ta 4.5n 1.6i \f(CWtypedef struct { int x, y; /* location of window */ int width, height; /* width and height of window */ int border_width; /* border width of window */ int depth; /* depth of window */ Visual *visual; /* the associated visual structure */ Window root; /* root of screen containing window */ int class; /* InputOutput, InputOnly*/ int bit_gravity; /* one of bit gravity values */ int win_gravity; /* one of the window gravity values */ int backing_store; /* NotUseful, WhenMapped, Always */ unsigned long backing_planes; /* planes to be preserved if possible */ unsigned long backing_pixel; /* value to be used when restoring planes */ Bool save_under; /* boolean, should bits under be saved */ Colormap colormap; /* colormap to be associated with window */ Bool map_installed; /* boolean, is colormap currently installed */ int map_state; /* IsUnmapped, IsUnviewable, IsViewable */ long all_event_masks; /* set of events all people have interest in */ long your_event_mask; /* my event mask */ long do_not_propagate_mask; /* set of events that should not propagate */ Bool override_redirect; /* boolean value for override-redirect */ Screen *screen; /* pointer to correct screen */ } XWindowAttributes;\fP .XX "structures:XWindowAttributes" .Pe .SH "See Also" \s-1\fIXChangeWindowAttributes()\fP\s+1, \s-1\fIXGetGeometry()\fP\s+1, \s-1\fIXSetWindowBackground()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXSetWindowBorder()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetWindowProperty" "Xlib \- Properties" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetWindowProperty" .XX "windows:properties, obtaining" .Na XGetWindowProperty \(en obtain the atom type and property format for a window. .Nz .SH "Synopsis" .Sy int XGetWindowProperty\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIproperty\f(CW\^, \f(CIlong_offset\f(CW\^, \f(CIlong_length\f(CW\^, .in +5n \f(CIdelete\f(CW\^, \f(CIreq_type\f(CW\^, \f(CIactual_type_return\f(CW\^, \f(CIactual_format_return\f(CW\^, \f(CInitems_return\f(CW\^, \f(CIbytes_after_return\f(CW\^, \f(CIprop_return\f(CW\^) .in -5n .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; Atom \f(CIproperty\f(CW\^; long \f(CIlong_offset\f(CW\^, \f(CIlong_length\f(CW\^; Bool \f(CIdelete\f(CW\^; Atom \f(CIreq_type\f(CW\^; Atom *\f(CIactual_type_return\f(CW\^; int *\f(CIactual_format_return\f(CW\^; unsigned long *\f(CInitems_return\f(CW\^; unsigned long *\f(CIbytes_after_return\f(CW\^; unsigned char **\f(CIprop_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window whose atom type and property format you want to obtain. .IP \f(CIproperty\fP 1i Specifies the atom of the desired property. .IP \f(CIlong_offset\fP 1i Specifies the offset in 32-bit quantities where data will be retrieved. .IP \f(CIlong_length\fP 1i Specifies the length in 32-bit multiples of the data to be retrieved. .IP \f(CIdelete\fP 1i Specifies a boolean value of \f(CWTrue\fP or \f(CWFalse\fP. If you pass \f(CWTrue\fP and a property is returned, the property is deleted from the window after being read and a \f(CWPropertyNotify\fP event is generated on the window. .IP \f(CIreq_type\fP 1i Specifies an atom describing the desired format of the data. If \f(CWAnyPropertyType\fP is specified, returns the property from the specified window regardless of its type. If a type is specified, the function returns the property only if its type equals the specified type. .IP \f(CIactual_type_return\fP 1i Returns the actual type of the property. .IP \f(CIactual_format_return\fP 1i Returns the actual data type of the returned data. .Nd 5 .IP \f(CInitems_return\fP 1i Returns the actual number of 8-, 16-, or 32-bit items returned in \f(CIprop_return\fP. .IP \f(CIbytes_after_return\fP 1i Returns the number of bytes remaining to be read in the property if a partial read was performed. .br .ne 4 .IP \f(CIprop_return\fP 1i Returns a pointer to the data actually returned, in the specified format. \f(CWXGetWindowProperty()\fP always allocates one extra byte after the data and sets it to \f(CWNULL\fP. This byte is not counted in \f(CInitems_return\fP. .SH Returns \f(CWSuccess\fP on success. The failure return value is undefined. .SH Description \f(CWXGetWindowProperty()\fP gets the value of a property if it is the desired type. \f(CWXGetWindowProperty()\fP sets the return arguments acccording to the following rules: .IP \(bu 3n If the specified property does not exist for the specified window, then: \f(CIactual_type_return\fP is \f(CWNone\fP; \f(CIactual_format_return = 0\fP; and \f(CIbytes_after_return = 0\fP. \f(CIdelete\fP is ignored in this case, and \f(CInitems_return\fP is empty. .IP \(bu 3n If the specified property exists, but its type does not match \f(CIreq_type\fP, then: \f(CIactual_type_return\fP is the actual property type; \f(CIactual_format_return\fP is the actual property format (never zero); and \f(CIbytes_after_return\fP is the property length in bytes (even if \f(CIactual_format_return\fP is 16 or 32). \f(CIdelete\fP is ignored in this case, and \f(CInitems_return\fP is empty. .IP \(bu 3n If the specified property exists, and either \f(CIreq_type\fP is \f(CWAnyPropertyType\fP or the specified type matches the actual property type, then: \f(CIactual_type_return\fP is the actual property type; and \f(CIactual_format_return\fP is the actual property format (never zero). \f(CIbytes_after_return\fP and \f(CInitems_return\fP are defined by combining the following values: .Ps \f(CWN =\fR actual length of stored property in bytes (even if \f(CIactual_format_return\fP is \f(CW16\fP or \f(CW32\fP) \f(CWI = 4 * \f(CIlong_offset\fR (convert offset from \f(CIlongs\fP into bytes) \f(CWL = MINIMUM((N - I), 4 * \f(CIlong_length\fP) (BadValue if L < 0) \f(CWbytes_after = N - (I + L)\fR (number of trailing unread bytes in stored property) .Pe The returned data (in \f(CIprop_return\fP) starts at byte index \f(CII\fR in the property (indexing from 0). The actual length of the returned data in bytes is \f(CIL\fP. \f(CIL\fP is converted into the number of 8-, 16-, or 32-bit items returned by dividing by 1, 2, or 4 respectively and this value is returned in \f(CInitems_return\fP. The number of trailing unread bytes is returned in \f(CIbytes_after_return\fP. .LP .Nd 10 If \f(CIdelete\f(CW == True\fR and \f(CIbytes_after_return\f(CW == 0\fR the function deletes the property from the window and generates a \f(CWPropertyNotify\fP event on the window. .LP When \f(CWXGetWindowProperty()\fP executes successfully, it returns \f(CWSuccess\fP. .Ns R The \f(CWSuccess\fP return value and the undocumented value returned on failure are the opposite of all other routines that return \f(CWint\fR or \f(CWStatus\fR. The value of \f(CWSuccess\fP is undocumented, but is zero (0) in the current sample implementation from MIT. The failure value, also undocumented, is currently one (1). Therefore, comparing either value to \f(CWTrue\fP or \f(CWFalse\fP, or using the syntax "\f(CWif (!\f(CWXGetWindowProperty\fP(...))\fR" is incorrect. .Ne .LP To free the resulting data, use \&\f(CWXFree()\fP. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fR. .br .ne 8 .SH "Errors" .IP "\f(CWBadAtom\fP" 1i .IP "\f(CWBadValue\fP" 1i Value of \f(CIlong_offset\fP caused \f(CIL\fP to be negative above. .IP "\f(CWBadWindow\fP" 1i .br .ne 4 .SH "See Also" .hw Intern-Atom\s-1\fIXInternAtom()\fP\s+1., .hw XDelete-Property\s-1\fIXDeleteProperty()\fP\s+1, \s-1\fIXChangeProperty()\fP\s+1, \s-1\fIXGetAtomName()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXListProperties()\fP\s+1, \s-1\fIXRotateWindowProperties()\fP\s+1, \s-1\fIXSetStandardProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGetZoomHints" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGetZoomHints" .Na .XX "zoom hints" .XX "windows:zoomed" XGetZoomHints \(en read the size hints property of a zoomed window. .Nz .SH "Synopsis" .Sy Status XGetZoomHints\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIzhints_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; XSizeHints *\f(CIzhints_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the ID of the window to be queried. .IP \f(CIzhints_return\fP Returns a pointer to the zoom hints. .SH Returns Zero on failure, non-zero on success. .SH Description \f(CWXGetZoomHints()\fP is obsolete beginning in Release 4, because zoom hints are no longer defined in the ICCCM. .LP \f(CWXGetZoomHints()\fP is primarily for window managers. \f(CWXGetZoomHints()\fP returns the size hints for a window in its zoomed state (not normal or iconified) read from the \f(CWXA_WM_ZOOM_HINTS\fP property. It returns a non-zero \f(CWStatus\fP if it succeeds, and zero if the application did not specify zoom size hints for this window. .LP For more information on using hints, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Structures" .Ps typedef struct { long flags; /* which fields in structure are defined */ int x, y; int width, height; int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; } XSizeHints; /* flags argument in size hints */ #define USPosition (1L << 0) /* user specified x, y */ #define USSize (1L << 1) /* user specified width, height */ #define PPosition (1L << 2) /* program specified position */ #define PSize (1L << 3) /* program specified size */ #define PMinSize (1L << 4) /* program specified minimum size */ #define PMaxSize (1L << 5) /* program specified maximum size */ #define PResizeInc (1L << 6) /* program specified resize increments */ #define PAspect (1L << 7) /* program specified min/max aspect ratios */ #define PAllHints (PPosition PSize PMinSize PMaxSize PResizeInc PAspect) .Pe .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1. .\"last line comment .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XGrDvBut.man,v 1.6 94/06/04 17:32:26 rws Exp $ .ds xL Programming With Xlib .TH XGrabDeviceButton 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XGrabDeviceButton, XUngrabDeviceButton \- grab/ungrab extension input device buttons .SH SYNTAX \fB .nf XGrabDeviceButton\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fIbutton\fP\^, \fImodifiers\fP\^, \fImodifier_device\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_count\fP\^, \fIevent_list\fP\^, \fIthis_device_mode\fP\^, \fIother_devices_mode\fP\^) Display *\fIdisplay\fP\^; XDevice *\fIdevice\fP\^; unsigned int \fIbutton\fP\^; unsigned int \fImodifiers\fP\^; XDevice *\fImodifier_device\fP\^; Window \fIgrab_window\fP\^; Bool \fIowner_events\fP\^; unsigned int \fIevent_count\fP\^; XEventClass *\fIevent_list\fP\^; int \fIthis_device_mode\fP\^, \fIother_devices_mode\fP\^; XUngrabDeviceButton\^(\^\fIdisplay\fP\^, \fIdevice\fP\^, \fIbutton\fP\^, \fImodifiers\fP\^, \fImodifier_device\fP\^, \fIgrab_window\fP\^) Display *\fIdisplay\fP\^; XDevice *\fIdevice\fP\^; unsigned int \fIbutton\fP\^; unsigned int \fImodifiers\fP\^; XDevice *\fImodifier_device\fP\^; Window \fIgrab_window\fP\^; .fi \fP .SH ARGUMENTS .ds Bu grabbed or released .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device that is to be \*(Bu .TP 12 .I button Specifies the device button that is to be \*(Bu or \fIAnyButton\fP. .TP 12 .I modifiers Specifies the set of keymasks or \fIAnyModifier\fP. The mask is the bitwise inclusive OR of the valid keymask bits. Valid bits are: Shiftmask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. .TP 12 .I modifier_device specifies the device whose modifiers are to be used. If the modifier_device specified is NULL, the X keyboard will be used as the modifier_device. .TP 12 .I grab_window Specifies the grab window. .TP 12 .I owner_events Specifies a Boolean value that indicates whether the device events are to be reported as usual or reported with respect to the grab window if selected by the event list. .TP 12 .I event_count Specifies the number of event classes in the event list. .TP 12 .I event_list Specifies which events are reported to the client. .TP 12 .I this_device_mode Specifies further processing of events from this device. You can pass \fIGrabModeSync\fP or \fIGrabModeAsync\fP. .TP 12 .I other_devices_mode Specifies further processing of events from all other devices. You can pass \fIGrabModeSync\fP or \fIGrabModeAsync\fP. .SH DESCRIPTION The \fIXGrabDeviceButton\fP request establishes a passive grab. In the future, the device is actively grabbed (as for \fIXGrabDevice\fP, the last-grab time is set to the time at which the button was pressed (as transmitted in the \fIDeviceButtonPress\fP event), and the \fIDeviceButtonPress\fP event is reported if all of the following conditions are true: .IP \(bu 5 The device is not grabbed, and the specified button is logically pressed when the specified modifier keys are logically down on the specified modifier device and no other buttons or modifier keys are logically down. .IP \(bu 5 Either the grab window is an ancestor of (or is) the focus window, OR the grab window is a descendent of the focus window and contains the device. .IP \(bu 5 A passive grab on the same button/modifier combination does not exist on any ancestor of grab_window. .LP The interpretation of the remaining arguments is as for \fIXGrabDevice\fP. The active grab is terminated automatically when the logical state of the device has all buttons released (independent of the logical state of the modifier keys). .LP Note that the logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen. .LP This request overrides all previous grabs by the same client on the same button/modifier combinations on the same window. A modifiers of \fIAnyModifier\fP is equivalent to issuing the grab request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned KeyCodes. A button of \fIAnyButton\fP is equivalent to issuing the request for all possible buttons. Otherwise, it is not required that the specified button currently be assigned to a physical button. .LP A modifier_device of NULL indicates that the X keyboard is to be used as the modifier_device. .LP If some other client has already issued a \fIXGrabDeviceButton\fP with the same button/modifier combination on the same window, a \fIBadAccess\fP error results. When using \fIAnyModifier\fP or \fIAnyButton\fP , the request fails completely, and a \fIBadAccess\fP error results (no grabs are established) if there is a conflicting grab for any combination. \fIXGrabDeviceButton\fP has no effect on an active grab. .LP \fIXGrabDeviceButton\fP can generate \fIBadClass\fP, \fIBadDevice\fP, \fIBadMatch\fP, \fIBadValue\fP, and \fIBadWindow\fP errors. .P The \fIXUngrabDeviceButton\fP request releases the passive grab for a button/modifier combination on the specified window if it was grabbed by this client. A modifier of \fIAnyModifier\fP is equivalent to issuing the ungrab request for all possible modifier combinations, including the combination of no modifiers. A button of \fIAnyButton\fP is equivalent to issuing the request for all possible buttons. \fIXUngrabDeviceButton\fP has no effect on an active grab. .LP A modifier_device of NULL indicates that the X keyboard should be used as the modifier_device. .LP \fIXUngrabDeviceButton\fP can generate \fIBadDevice\fP, \fIBadMatch\fP, \fIBadValue\fP and \fIBadWindow\fP errors. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if the specified device is the X keyboard or X pointer device. .TP 12 \fIBadMatch\fP This error may occur if an \fIXGrabDeviceButton\fP request was made specifying a device that has no buttons, or specifying a modifier device that has no keys. .TP 12 \fIBadValue\fP Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error. .TP 12 \fIBadWindow\fP A value for a Window argument does not name a defined Window. .SH "SEE ALSO" XAllowDeviceEvents(3X), .br XGrabDevice(3X), .br XGrabDeviceKey(3X), .br \fI\*(xL\fP .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XGrDvKey.man,v 1.5 94/06/04 17:32:28 rws Exp $ .ds xL Programming with Xlib .TH XGrabDeviceKey 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XGrabDeviceKey, XUngrabDeviceKey \- grab/ungrab extension input device Keys .SH SYNTAX XGrabDeviceKey\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fIKey\fP\^, \fImodifiers\fP\^, \fImodifier_device\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, .br \fIevent_count\fP\^, \fIevent_list\fP\^, \fIthis_device_mode\fP\^, \fIother_devices_mode\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br unsigned int \fIKey\fP\^; .br unsigned int \fImodifiers\fP\^; .br XDevice *\fImodifier_device\fP\^; .br Window \fIgrab_window\fP\^; .br Bool \fIowner_events\fP\^; .br unsigned int \fIevent_count\fP\^; .br XEventClass \fIevent_list\fP\^; .br int \fIthis_device_mode\fP\^, \fIother_devices_mode\fP\^; .sp XUngrabDeviceKey\^(\fIdisplay\fP\^, \fIdevice\fP\^, \fIKey\fP\^, \fImodifiers\fP\^, \fImodifier_device\fP\^, \fIgrab_window\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br unsigned int \fIKey\fP\^; .br unsigned int \fImodifiers\fP\^; .br XDevice *\fImodifier_device\fP\^; .br Window \fIgrab_window\fP\^; .SH ARGUMENTS .ds Bu grabbed or released .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device that is to be \*(Bu .TP 12 .I Key Specifies the device Key that is to be \*(Bu or \fIAnyKey\fP. .TP 12 .I modifiers Specifies the set of keymasks or \fIAnyModifier\fP. The mask is the bitwise inclusive OR of the valid keymask bits. Valid bits are: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. .TP 12 .I modifier_device Specifies the device whose modifiers are to be used. If a modifier_device of NULL is specified, the X keyboard will be used as the modifier_device. .TP 12 .I grab_window Specifies the grab window. .TP 12 .I owner_events Specifies a Boolean value that indicates whether the device events are to be reported as usual or reported with respect to the grab window if selected by the event list. .TP 12 .I event_count Specifies the number of event classes in the event list. .TP 12 .I event_list Specifies which device events are reported to the client. .TP 12 .I this_device_mode Specifies further processing of events from this device. You can pass \fIGrabModeSync\fP or \fIGrabModeAsync\fP. .TP 12 .I other_devices_mode Specifies further processing of events from other devices. You can pass \fIGrabModeSync\fP or \fIGrabModeAsync\fP. .SH DESCRIPTION The \fIXGrabDeviceKey\fP request establishes a passive grab. In the future, the device is actively grabbed (as for \fIXGrabDevice\fP, the last-device-grab time is set to the time at which the Key was pressed (as transmitted in the \fIDeviceKeyPress\fP event), and the \fIDeviceKeyPress\fP event is reported if all of the following conditions are true: .IP \(bu 5 The device is not grabbed, and the specified key is logically pressed when the specified modifier keys are logically down, and no other keys or modifier keys are logically down. .IP \(bu 5 The grab_window is an ancestor (or is) the focus window OR the grab window is a descendant of the focus window and contains the device. .IP \(bu 5 The confine_to window (if any) is viewable. .IP \(bu 5 A passive grab on the same key/modifier combination does not exist on any ancestor of grab_window. .LP The interpretation of the remaining arguments is as for \fIXGrabDevice\fP . The active grab is terminated automatically when the logical state of the device has the specified key released. .LP Note that the logical state of a device (as seen by means of the X protocol ) may lag the physical state if device event processing is frozen. .LP If the key is not \fIAnyKey\fP, it must be in the range specified by min_keycode and max_keycode as returned by the \fIXListInputDevices\fP request. Otherwise, a \fIBadValue\fP error results. .LP This request overrides all previous grabs by the same client on the same Key/modifier combinations on the same window. A modifier of \fIAnyModifier\fP is equivalent to issuing the grab request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned KeyCodes. A key of \fIAnyKey\fP is equivalent to issuing the request for all possible keys. Otherwise, it is not required that the specified key currently be assigned to a physical Key. .LP If a modifier_device of NULL is specified, the X keyboard will be used as the modifier_device. .LP If some other client has already issued a \fIXGrabDeviceKey\fP with the same Key/modifier combination on the same window, a \fIBadAccess\fP error results. When using \fIAnyModifier\fP or \fIAnyKey\fP , the request fails completely, and a \fIBadAccess\fP error results (no grabs are established) if there is a conflicting grab for any combination. \fIXGrabDeviceKey\fP has no effect on an active grab. .LP \fIXGrabDeviceKey\fP can generate \fIBadAccess\fP, \fIBadClass\fP, \fIBadDevice\fP, \fIBadMatch\fP, \fIBadValue\fP, and \fIBadWindow\fP errors. It returns \fISuccess\fP on successful completion of the request. .P The \fIXUngrabDeviceKey\fP request releases the passive grab for a key/modifier combination on the specified window if it was grabbed by this client. A modifier of \fIAnyModifier\fP is equivalent to issuing the ungrab request for all possible modifier combinations, including the combination of no modifiers. A Key of \fIAnyKey\fP is equivalent to issuing the request for all possible Keys. \fIXUngrabDeviceKey\fP has no effect on an active grab. .LP If a modifier_device of NULL is specified, the X keyboard will be used as the modifier_device. .LP \fIXUngrabDeviceKey\fP can generate \fIBadDevice\fP, \fIBadMatch\fP, \fIBadValue\fP and \fIBadWindow\fP errors. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if the specified device is the X keyboard or X pointer device. .TP 12 \fIBadMatch\fP This error may occur if an \fIXGrabDeviceKey\fP request was made specifying a device that has no keys, or a modifier device that has no keys. .TP 12 \fIBadValue\fP Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error. .TP 12 \fIBadWindow\fP A value for a Window argument does not name a defined Window. .SH "SEE ALSO" XAllowDeviceEvents(3X), .br XGrabDevice(3X), .br XGrabDeviceButton(3X), .br .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGrabButton" "Xlib \- Grabbing" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGrabButton" .XX "pointer button:grabbing" .XX "grabbing:pointer button" .Na XGrabButton \(en grab a pointer button. .Nz .SH "Synopsis" .Sy XGrabButton\^(\^\f(CIdisplay\f(CW, \f(CIbutton\f(CW\^, \f(CImodifiers\f(CW\^, \f(CIgrab_window\f(CW\^, \f(CIowner_events\f(CW\^, \f(CIevent_mask\f(CW\^, \f(CIpointer_mode\f(CW\^, \f(CIkeyboard_mode\f(CW\^, \f(CIconfine_to\f(CW\^, \f(CIcursor\f(CW\^) .in -10n .As Display *\f(CIdisplay\f(CW\^; unsigned int \f(CIbutton\f(CW\^; unsigned int \f(CImodifiers\f(CW\^; Window \f(CIgrab_window\f(CW\^; Bool \f(CIowner_events\f(CW\^; unsigned int \f(CIevent_mask\f(CW\^; int \f(CIpointer_mode\f(CW\^, \f(CIkeyboard_mode\f(CW\^; Window \f(CIconfine_to\f(CW\^; Cursor \f(CIcursor\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIbutton\fP 1i Specifies the mouse button. May be \f(CWButton1\fP, \f(CWButton2\fP, \f(CWButton3\fP, \f(CWButton4\fP, \f(CWButton5\fP, or \f(CWAnyButton\fP. The constant \f(CWAnyButton\fP is equivalent to issuing the grab request for all possible buttons. The button symbols cannot be ORed. .IP \f(CImodifiers\fP 1i Specifies a set of keymasks. This is a bitwise OR of one or more of the following symbols: \f(CWShiftMask\fP, \f(CWLockMask\fP, \f(CWControlMask\fP, \f(CWMod1Mask\fP, \f(CWMod2Mask\fP, \f(CWMod3Mask\fP, \f(CWMod4Mask\fP, \f(CWMod5Mask\fP, or \f(CWAnyModifier\fP. \f(CWAnyModifier\fP is equivalent to issuing the grab key request for all possible modifier combinations (including no modifiers). .IP \f(CIgrab_window\fP 1i Specifies the ID of the window you want to the grab to occur in. .IP \f(CIowner_events\fP 1i Specifies a boolean value of either \f(CWTrue\fP or \f(CWFalse\fP. See the "Description" section below. .IP \f(CIevent_mask\fP 1i Specifies the event mask to take effect during the grab. This mask is the bitwise OR of one or more of these event masks: \f(CWButtonPressMask\fP, \f(CWButtonReleaseMask\fP, \f(CWEnterWindowMask\fP, \f(CWLeaveWindowMask\fP, \f(CWPointerMotionMask\fP, \f(CWPointerMotionHintMask\fP, \f(CWButton1MotionMask\fP, .hw Button5-Motion-Mask \f(CWButton2MotionMask\fP, \f(CWButton3MotionMask\fP, \f(CWButton4MotionMask\fP, \f(CWButton5MotionMask\fP, \f(CWButtonMotionMask\fP, \f(CWKeymapStateMask\fP. .IP \f(CIpointer_mode\fP 1i Controls processing of pointer events during the grab. Pass one of these constants: \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .br .ne 4 .IP \f(CIkeyboard_mode\fP 1i Controls processing of keyboard events during the grab. Pass one of these constants: \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .IP \f(CIconfine_to\fP 1i Specifies the ID of the window to confine the pointer. One possible value is the constant \f(CWNone\fP, in which case the pointer is not confined to any window. .IP \f(CIcursor\fP 1i Specifies the cursor to be displayed during the grab. One possible value you can pass is the constant \f(CWNone\fP, in which case the existing cursor is used. .SH Description \f(CWXGrabButton()\fP establishes a passive grab, such that an active grab may take place when the specified key/button combination is pressed in the specified window. After this call: .br .IP \(bu 3n IF the specified button is pressed when the specified modifier keys are down (and no other buttons or modifier keys are down), .IP \(bu 3n AND \f(CIgrab_window\fP contains the pointer, .IP \(bu 3n AND the \f(CIconfine_to\fP window (if any) is viewable, .IP \(bu 3n AND these constraints are not satisfied for any ancestor, .IP \(bu 3n THEN the pointer is actively grabbed as described in \f(CWXGrabPointer()\fP, the last pointer grab time is set to the time at which the button was pressed, and the \f(CWButtonPress\fP event is reported. .LP The interpretation of the remaining arguments is as for \f(CWXGrabPointer()\fP. The active grab is terminated automatically when all buttons are released (independent of the state of modifier keys). The \f(CWButtonRelease\fR event which terminates the active button grab is sent to the grabbing window. .LP A modifier of \f(CWAnyModifier\fP is equivalent to issuing the grab request for all possible modifier combinations (including no modifiers). A button of \f(CWAnyButton\fP is equivalent to issuing the request for all possible buttons (but at least one). .LP \f(CWXGrabButton()\fP overrides all previous passive grabs by the same client on the same key/button combination on the same window, but has no effect on an active grab. The request fails if some other client has already issued an \f(CWXGrabButton()\fP with the same button/key combination on the same window. When using \f(CWAnyModifier\fP or \f(CWAnyButton\fP, the request fails completely (no grabs are established) if there is a conflicting grab for any combination. .LP The \f(CIowner_events\fP argument specifies whether the grab window should receive all events (\f(CWFalse\fP) or whether the grabbing application should receive all events normally (\f(CWTrue\fP). .LP The \f(CIpointer_mode\fP and \f(CIkeyboard_mode\fP control the processing of events during the grab. If either is \f(CWGrab\%ModeSync\fP, events for that device are not sent from the server to Xlib until \f(CWXAllowEvents()\fP is called to release the events. If either is \f(CWGrabModeAsync\fP, events for that device are sent normally. .LP An automatic grab takes place between a \f(CWButtonPress\fP event and the corresponding \f(CWButtonRelease\fP event, so this call is not necessary in some of the most common situations. But this call is necessary for certain styles of menus. .LP For more information on grabbing, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .br .ne 10 .SH "Errors" .IP "\f(CWBadAccess\fP" 1i When using \f(CWAnyModifier\fP or \f(CWAnyButton\fP and there is a conflicting grab by another client. No grabs are established. .br .sp +.5 Another client has already issued an \f(CWXGrabButton()\fP request with the same key/button combination on the same window. .IP "\f(CWBadCursor\fP" .IP "\f(CWBadValue\fP" .IP "\f(CWBadWindow\fP" .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXGrabKey()\fP\s+1, \s-1\fIXGrabKeyboard()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXGrabServer()\fP\s+1, \s-1\fIXUngrabButton()\fP\s+1, \s-1\fIXUngrabKey()\fP\s+1, \s-1\fIXUngrabKeyboard()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1, \s-1\fIXUngrabServer()\fP\s+1. .\"last line comment .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XGrabDev.man,v 1.6 94/06/04 17:32:29 rws Exp $ .ds xL Programming With Xlib .TH XGrabDevice 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XGrabDevice, XUngrabDevice \- grab/release the specified extension device .SH SYNTAX .nf \fB int XGrabDevice\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fIgrab_window\fP\^, \fIowner_events\fP\^, \fIevent_count\fP\^, \fIevent_list\fP\^, \fIthis_device_mode\fP\^, \fIother_devices_mode\fP\^, \fItime\fP\^) Display *\fIdisplay\fP\^; XDevice *\fIdevice\fP\^; Window \fIgrab_window\fP\^; Bool \fIowner_events\fP\^; int \fIevent_count\fP\^; XEventClass *\fIevent_list\fP\^; int \fIthis_device_mode\fP\^, \fIother_devices_mode\fP\^; Time \fItime\fP\^; XUngrabDevice\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fItime\fP\^) Display *\fIdisplay\fP\^; XDevice *\fIdevice\fP\^; Time \fItime\fP\^; .fi \fP .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device to be grabbed or released. .TP 12 .I grab_window Specifies the id of a window to be associated with the device. .TP 12 .I owner_events Specifies a Boolean value that indicates whether the events from the device are to be reported as usual or reported with respect to the grab window if selected by the event list. .TP 12 .I event_count Specifies the number of elements in the event_list array. .TP 12 .I event_list Specifies a pointer to a list of event classes that indicates which events the client wishes to receive. These event classes must have been obtained specifying the device being grabbed. .TP 12 .I this_device_mode Specifies further processing of events from this device. You can pass \fIGrabModeSync\fP or \fIGrabModeAsync\fP. .TP 12 .I other_devices_mode Specifies further processing of events from other devices. You can pass \fIGrabModeSync\fP or \fIGrabModeAsync\fP. .TP 12 .I time Specifies the time. You can pass either a timestamp or \fICurrentTime\fP. .SH DESCRIPTION The \fIXGrabDevice\fP request actively grabs control of the device and generates \fIDeviceFocusIn\fP and \fIDeviceFocusOut\fP events. Further device events are reported only to the grabbing client. \fIXGrabDevice\fP overrides any active device grab by this client. event_list is a pointer to a list of event classes. This list indicates which events the client wishes to receive while the grab is active. If owner_events is \fIFalse\fP , all generated device events are reported with respect to grab_window if selected. If owner_events is \fITrue\fP and if a generated device event would normally be reported to this client, it is reported normally; otherwise, the event is reported with respect to the grab_window, and is only reported if specified in the event_list. .LP If the this_device_mode argument is \fIGrabModeAsync\fP , device event processing continues as usual. If the device is currently frozen by this client, then processing of device events is resumed. If the this_device_mode argument is \fIGrabModeSync\fP , the state of the device (as seen by client applications) appears to freeze, and the X server generates no further device events until the grabbing client issues a releasing \fIXAllowDeviceEvents\fP call or until the device grab is released. Actual device changes are not lost while the device is frozen; they are simply queued in the server for later processing. .LP If other_devices_mode is \fIGrabModeAsync\fP , processing of events from other devices is unaffected by activation of the grab. If other_devices_mode is \fIGrabModeSync\fP, the state of all devices except the grabbed device (as seen by client applications) appears to freeze, and the X server generates no further events from those devices until the grabbing client issues a releasing \fIXAllowDeviceEvents\fP call or until the device grab is released. Actual events are not lost while the devices are frozen; they are simply queued in the server for later processing. .LP If the device is actively grabbed by some other client, \fIXGrabDevice\fP fails and returns \fIAlreadyGrabbed\fP. If grab_window is not viewable, it fails and returns \fIGrabNotViewable\fP. If the device is frozen by an active grab of another client, it fails and returns \fIGrabFrozen\fP. If the specified time is earlier than the last-device-grab time or later than the current X server time, it fails and returns \fIGrabInvalidTime\fP. Otherwise, the last-device-grab time is set to the specified time \fI( CurrentTime\fP is replaced by the current X server time). .LP If a grabbed device is closed by a client while an active grab by that client is in effect, the active grab is released. If the device is frozen only by an active grab of the requesting client, it is thawed. .LP \fIXGrabDevice\fP can generate \fIBadClass\fP, \fIBadDevice\fP, \fIBadValue\fP, and \fIBadWindow\fP errors. .LP The \fIXUngrabDevice\fP request releases the device and any queued events if this client has it actively grabbed from either \fIXGrabDevice\fP or \fIXGrabDeviceKey\fP. If other devices are frozen by the grab, \fIXUngrabDevice\fP thaws them. \fIXUngrabDevice\fP does not release the device and any queued events if the specified time is earlier than the last-device-grab time or is later than the current X server time. It also generates \fIDeviceFocusIn\fP and \fIDeviceFocusOut\fP events. The X server automatically performs an \fIUngrabDevice\fP request if the event window for an active device grab becomes not viewable. .LP \fIXUngrabDevice\fP can generate a \fIBadDevice\fP error. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if the specified device is the X keyboard or X pointer device. .TP 12 \fIBadValue\fP Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error. .TP 12 \fIBadWindow\fP A value for a Window argument does not name a defined Window. .SH "SEE ALSO" XAllowDeviceEvents(3X), XGrabDeviceButton(3X), XGrabDeviceKey(3X), .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGrabKey" "Xlib \- Grabbing" .ds ]W Xlib Reference Manual .SH "Name" .XX "keys:grabbing" .XX "XGrabKey" .XX "grabbing:keys" .Na XGrabKey \(en grab a key. .Nz .SH "Synopsis" .Sy XGrabKey\^(\^\f(CIdisplay\f(CW, \f(CIkeycode\f(CW\^, \f(CImodifiers\f(CW\^, \f(CIgrab_window\f(CW\^, \f(CIowner_events\f(CW\^, .ti +10n \f(CIpointer_mode\f(CW\^, \f(CIkeyboard_mode\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int \f(CIkeycode\f(CW\^; unsigned int \f(CImodifiers\f(CW\^; Window \f(CIgrab_window\f(CW\^; Bool \f(CIowner_events\f(CW\^; int \f(CIpointer_mode\f(CW\^, \f(CIkeyboard_mode\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIkeycode\fP 1i Specifies the keycode to be grabbed. It may be a modifier key. Specifying \f(CWAnyKey\fP is equivalent to issuing the request for all key codes. .IP \f(CImodifiers\fP 1i Specifies a set of keymasks. This is a bitwise OR of one or more of the following symbols: \f(CWShiftMask\fP, \f(CWLockMask\fP, \f(CWControlMask\fP, \f(CWMod1Mask\fP, \f(CWMod2Mask\fP, \f(CWMod3Mask\fP, \f(CWMod4Mask\fP, \f(CWMod5Mask\fP, or \f(CWAnyModifier\fP. \f(CWAnyModifier\fP is equivalent to issuing the grab key request for all possible modifier combinations (including no modifiers). All specified modifiers do not need to have currently assigned keycodes. .IP \f(CIgrab_window\fP 1i Specifies the window in which the specified key combination will initiate an active grab. .IP \f(CIowner_events\fP 1i Specifies whether the grab window should receive all events (\f(CWFalse\fP) or whether the grabbing application should receive all events normally (\f(CWTrue\fP). .IP \f(CIpointer_mode\fP 1i Controls processing of pointer events during the grab. Pass one of these constants: \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .IP \f(CIkeyboard_mode\fP 1i Controls processing of keyboard events during the grab. Pass one of these constants: \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .Nd 10 .SH Description \f(CWXGrabKey()\fP establishes a passive grab on the specified keys, such that when the specified key/modifier combination is pressed, the keyboard may be grabbed, and all keyboard events sent to this application. More formally, once an \f(CWXGrabKey()\fR call has been issued on a particular key/button combination: .br .ne 5 .IP \(bu 3n \s-1IF\s+1 the keyboard is not already actively grabbed, .IP \(bu 3n \s-1AND\s+1 the specified key, which itself can be a modifier key, is logically pressed when the specified modifier keys are logically down, .IP \(bu 3n \s-1AND\s+1 no other keys or modifier keys are logically down, .IP \(bu 3n \s-1AND EITHER\s+1 the grab window is an ancestor of (or is) the focus window OR the grab window is a descendent of the focus window and contains the pointer, .IP \(bu 3n \s-1AND\s+1 a passive grab on the same key combination does not exist on any ancestor of the grab window, .IP \(bu 3n \s-1THEN\s+1 the keyboard is actively grabbed, as for \f(CWXGrabKeyboard()\fR, the last keyboard grab time is set to the time at which the key was pressed (as transmitted in the \f(CWKeyPress\fR event), and the \f(CWKeyPress\fR event is reported. .LP The active grab is terminated automatically when the specified key is released (independent of the state of the modifier keys). The \f(CWKeyRelease\fR event which terminates the active grab is sent to the grabbing window. .LP The \f(CIpointer_mode\fP and \f(CIkeyboard_mode\fP control the processing of events during the grab. If either is \f(CWGrabModeSync\fP, events for that device are not sent from the server to Xlib until \f(CWXAllowEvents()\fP is called to send the events. If either is \f(CWGrabModeAsync\fP, events for that device are sent normally. .LP For more information on grabbing, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "Errors" .IP "\f(CWBadAccess\fP" 1i When using \f(CWAnyModifier\fP or \f(CWAnyKey\fP and another client has grabbed any overlapping combinations. In this case, no grabs are established. .sp .5 Another client has issued \f(CWXGrabKey()\fP for the same key combination in \f(CIgrab_window\fP. .IP "\f(CWBadValue\fP" 1i \f(CIkeycode\fP is not in the range between \f(CWmin_keycode\fP and \f(CWmax_\p keycode\fP as returned by \f(CWXDisplayKeycodes()\fP. .IP "\f(CWBadWindow\fP" .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXGrabButton()\fP\s+1, \s-1\fIXGrabKeyboard()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXGrabServer()\fP\s+1, \s-1\fIXUngrabButton()\fP\s+1, \s-1\fIXUngrabKey()\fP\s+1, \s-1\fIXUngrabKeyboard()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1, \s-1\fIXUngrabServer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGrabKeyboard" "Xlib \- Grabbing" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGrabKeyboard" .XX "keyboard:grabbing" .XX "grabbing:keyboards" .Na XGrabKeyboard \(en grab the keyboard. .Nz .SH "Synopsis" .Sy int XGrabKeyboard\^(\^\f(CIdisplay\f(CW, \f(CIgrab_window\f(CW, \f(CIowner_events\f(CW, \f(CIpointer_mode\f(CW, .ti +10n \f(CIkeyboard_mode\f(CW, \f(CItime\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIgrab_window\f(CW\^; Bool \f(CIowner_events\f(CW\^; int \f(CIpointer_mode\f(CW\^, \f(CIkeyboard_mode\f(CW\^; Time \f(CItime\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgrab_window\fP 1i Specifies the ID of the window that requires continuous keyboard input. .IP \f(CIowner_events\fP 1i Specifies a boolean value of either \f(CWTrue\fP or \f(CWFalse\fP. See the "Description" section below. .IP \f(CIpointer_mode\fP 1i Controls processing of pointer events during the grab. Pass either \f(CWGrab\%ModeSync\fP or \f(CWGrabModeAsync\fP. .IP \f(CIkeyboard_mode\fP 1i Controls processing of keyboard events during the grab. Pass either \f(CWGrab\%ModeSync\fP or \f(CWGrabModeAsync\fP. .IP \f(CItime\fP 1i Specifies the time when the grab should take place. .hw time-stamp Pass either a timestamp, expressed in milliseconds, or the constant \f(CWCurrentTime\fP. .SH Returns \f(CWGrabSuccess\fP on success. \f(CWAlreadyGrabbed\fP, \f(CWGrabNotViewable\fP, \f(CWGrabInvalidTime\fP, or \f(CWGrabFrozen\fP on failure. .SH Description \f(CWXGrabKeyboard()\fP actively grabs control of the main keyboard. Further key events are reported only to the .XX "FocusIn event:generating with XGrabKeyboard" .XX "FocusOut event:generating with XGrabKeyboard" grabbing client. This request generates \f(CWFocusIn\fP and \f(CWFocusOut\fP events. .LP \f(CWXGrabKeyboard()\fP processing is controlled by the value in the \f(CIowner_events\fP argument: .IP \(bu 3n If \f(CIowner_events\fP is \f(CWFalse\fP, all generated key events are reported to \f(CIgrab_window\fP. .hw window .IP \(bu 3n If \f(CIowner_events\fP is \f(CWTrue\fP, then if a generated key event would normally be reported to this client, it is .hw window reported normally. Otherwise the event is reported to \f(CIgrab_window\fP. .LP Both \f(CWKeyPress\fP and \f(CWKeyRelease\fP events are always reported, independent of any event selection made by the client. .LP \f(CWXGrabKeyboard()\fP processing of pointer events and keyboard events are controlled by \f(CIpointer_mode\fP and \f(CIkeyboard_mode\fP\^: .IP \(bu 3n If the \f(CIpointer_mode\fP or \f(CIkeyboard_mode\fP is \f(CWGrabModeAsync\fP, event processing for the respective device continues normally. .IP \(bu 3n For \f(CIkeyboard_mode\fP \f(CWGrabModeAsync\fP only: if the keyboard was currently frozen by this client, then processing of keyboard events is resumed. .IP \(bu 3n If the \f(CIpointer_mode\fP or \f(CIkeyboard_mode\fP is \f(CWGrabModeSync\fP, events for the respective device are queued by the server until a releasing \f(CWXAllowEvents()\fP request occurs or until the keyboard grab is released as described above. .LP If the grab is successful, \f(CWXGrabKeyboard()\fP returns the constant \f(CWGrabSuccess\fP. \f(CWXGrabKeyboard()\fP fails under the following conditions and returns the following: .IP \(bu 3n If the keyboard is actively grabbed by some other client, it returns \f(CWAlreadyGrabbed\fP. .IP \(bu 3n If \f(CIgrab_window\fP is not viewable, it returns \f(CWGrabNotViewable\fP. .IP \(bu 3n If \f(CItime\fP is earlier than the last keyboard grab time or later than the current server time, it returns \f(CWGrabInvalidTime\fP. .IP \(bu 3n If the pointer is frozen by an active grab of another client, the request fails with a status \f(CWGrabFrozen\fP. .LP If the grab succeeds, the last keyboard grab time is set to the specified time, with \f(CWCurrentTime\fP replaced by the current X server time. .LP For more information on grabbing, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "Errors" \f(CWBadValue\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXGrabButton()\fP\s+1, \s-1\fIXGrabKey()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXGrabServer()\fP\s+1, \s-1\fIXUngrabButton()\fP\s+1, \s-1\fIXUngrabKey()\fP\s+1, \s-1\fIXUngrabKeyboard()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1, \s-1\fIXUngrabServer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGrabPointer" "Xlib \- Grabbing" .ds ]W Xlib Reference Manual .SH "Name" .XX "XGrabPointer" .XX "grabbing:pointers" .XX "pointers:grabbing" .Na XGrabPointer \(en grab the pointer. .Nz .SH "Synopsis" .Sy int XGrabPointer\^(\^\f(CIdisplay\f(CW, \f(CIgrab_window\f(CW\^, \f(CIowner_events\f(CW\^, \f(CIevent_mask\f(CW\^, .in +10n \f(CIpointer_mode\f(CW\^, \f(CIkeyboard_mode\f(CW\^, \f(CIconfine_to\f(CW\^, \f(CIcursor\f(CW\^, \f(CItime\f(CW\^) .in -10n .As Display *\f(CIdisplay\f(CW\^; Window \f(CIgrab_window\f(CW\^; Bool \f(CIowner_events\f(CW\^; unsigned int \f(CIevent_mask\f(CW\^; int \f(CIpointer_mode\f(CW\^, \f(CIkeyboard_mode\f(CW\^; Window \f(CIconfine_to\f(CW\^; Cursor \f(CIcursor\f(CW\^; Time \f(CItime\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgrab_window\fP 1i Specifies the ID of the window that should grab the pointer input independent of pointer location. .IP \f(CIowner_events\fP 1i Specifies if the pointer events are to be reported normally within this application (pass \f(CWTrue\fR) or only to the grab window (pass \f(CWFalse\fR). .IP \f(CIevent_mask\fP 1i Specifies the event mask symbols that can be ORed together. Only events selected by this mask will be delivered during the grab. The valid event masks are: \f(CWButtonPressMask\fP, \f(CWButtonReleaseMask\fP, \f(CWEnterWindowMask\fP, \f(CWLeaveWindowMask\fP, \f(CWPointerMotionMask\fP, \f(CWPointerMotionHintMask\fP, \f(CWButton1MotionMask\fP, .hw Button5-Motion-Mask \f(CWButton2MotionMask\fP, \f(CWButton3MotionMask\fP, \f(CWButton4MotionMask\fP, \f(CWButton5MotionMask\fP, \f(CWButtonMotionMask\fP, \f(CWKeymapStateMask\fP. .IP \f(CIpointer_mode\fP 1i Controls further processing of pointer events. Pass either \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .IP \f(CIkeyboard_mode\fP 1i Controls further processing of keyboard events. Pass either \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .IP \f(CIconfine_to\fP 1i Specifies the ID of the window to confine the pointer. One option is \f(CWNone\fP, in which case the pointer is not confined to any window. .IP \f(CIcursor\fP 1i Specifies the ID of the cursor that is displayed with the pointer during the grab. One option is \f(CWNone\fP, which causes the cursor to keep its current\p pattern. .hw time-stamp .Nd 10 .IP \f(CItime\fP 1i Specifies the time when the grab request took place. Pass either a timestamp, expressed in milliseconds (from an event), or the constant \f(CWCurrentTime\fP. .Nd 3 .SH Returns \f(CWGrabSuccess\fP on success. \f(CWGrabNotViewable\fP, \f(CWAlreadyGrabbed\fP, \f(CWGrabInvalidTime\fP, or \f(CWGrabFrozen\fP on failure. .SH Description \f(CWXGrabPointer()\fP actively grabs control of the pointer. Further pointer events report only to the .XX "XUngrabPointer:and XGrabPointer" grabbing client until \f(CWXUngrabPointer()\fP is called. \f(CWXGrabPointer()\fP overrides any active pointer grab by this client. .LP If \f(CIowner_events\fP is \f(CWFalse\fP, all generated pointer events are reported to \f(CIgrab_window\fP, and are only reported if selected by \f(CIevent_mask\fP. If \f(CIowner_events\fP is \f(CWTrue\fP, then if a generated pointer event would normally be reported to this client, it is reported normally; otherwise the event is reported with respect to the \f(CIgrab_window\fP, and is only reported if selected by \f(CIevent_mask\fP. For either value of \f(CIowner_events\fP, unreported events are discarded. .LP \f(CIpointer_mode\fP controls processing of pointer events during the grab, and .hw keyboard \f(CIkeyboard_mode\fP controls further processing of main keyboard events. If the mode is \f(CWGrabModeAsync\fP, event processing continues normally. If the mode is \f(CWGrabModeSync\fP, events for the device are queued by the server but not sent to clients until the grabbing client issues a releasing \f(CWXAllowEvents()\fP request or an \f(CWXUngrabPointer()\fP request. .LP If a cursor is specified, then it is displayed regardless of which window the pointer is in. If no cursor is specified, then when the pointer is in \f(CIgrab_window\fP or one of its subwindows, the normal cursor for that window is displayed. When the pointer is outside \f(CWgrab_window\fP, the cursor for \f(CIgrab_window\fP is displayed. .LP If a \f(CIconfine_to\fP window is specified, then the pointer will be restricted to that window. The \f(CIconfine_to\fP window need have no relationship to the \f(CIgrab_window\fP. If the pointer is not initially in the \f(CIconfine_to\fP window, then it is warped automatically to the closest edge (and enter/leave events generated normally) just before the grab activates. .hw confine If the \f(CIconfine_to\fP window is subsequently reconfigured, the pointer will be warped automatically as necessary to keep it contained in the window. .LP The \f(CItime\fP argument lets you avoid certain circumstances that come up if applications take a long while to respond or if there are long network delays. Consider a situation where you have two applications, both of which normally grab the pointer when clicked on. If both applications specify the timestamp from the \f(CWButtonPress\fP event, the second application will successfully grab the pointer, while the first will get a return value of \f(CWAlreadyGrabbed\fP, indicating that the other application grabbed the pointer before its request was processed. This is the desired response because the latest user action is most important in this case. .LP \f(CWXGrabPointer()\fP generates \f(CWEnterNotify\fP and \f(CWLeaveNotify\fP events. .LP .Nd 10 If the grab is successful, it returns the constant \f(CWGrabSuccess\fP. The \f(CWXGrabPointer()\fP function fails under the following conditions, with the following return values: .IP \(bu 3n If \f(CIgrab_window\fP or \f(CIconfine_to\fP window is not viewable, or if the \f(CWconfine_to\fP window is completely off the screen, \f(CWGrabNotViewable\fP is returned. .IP \(bu 3n If the pointer is actively grabbed by some other client, the constant \f(CWAlreadyGrabbed\fP is returned. .IP \(bu 3n If the pointer is frozen by an active grab of another client, \f(CWGrabFrozen\fP is returned. .Nd 4 .IP \(bu 3n If the specified time is earlier than the last-pointer-grab time or later than the current X server time, \f(CWGrabInvalidTime\fP is returned. (If the call succeeds, the last pointer grab time is set to the specified time, with the constant \f(CWCurrentTime\fP replaced by the current X server time.) .LP For more information on grabbing, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "Errors" \f(CWBadCursor\fP .br \f(CWBadValue\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXGrabButton()\fP\s+1, \s-1\fIXGrabKey()\fP\s+1, \s-1\fIXGrabKeyboard()\fP\s+1, \s-1\fIXGrabServer()\fP\s+1, \s-1\fIXUngrabButton()\fP\s+1, \s-1\fIXUngrabKey()\fP\s+1, \s-1\fIXUngrabKeyboard()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1, \s-1\fIXUngrabServer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XGrabServer" "Xlib \- Grabbing" .ds ]W Xlib Reference Manual .SH "Name" .XX "servers:grabbing" .XX "grabbing:servers" .XX "XGrabServer" .Na XGrabServer \(en grab the server. .Nz .SH "Synopsis" .Sy XGrabServer\^(\^\f(CIdisplay\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Description Grabbing the server means that only requests by the calling client will be acted on. All others will be queued in the server until the next \f(CWXUngrabServer()\fP call. The X server should not be grabbed any more than is absolutely necessary. .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXGrabButton()\fP\s+1, \s-1\fIXGrabKey()\fP\s+1, \s-1\fIXGrabKeyboard()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXUngrabButton()\fP\s+1, \s-1\fIXUngrabKey()\fP\s+1, \s-1\fIXUngrabKeyboard()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1, \s-1\fIXUngrabServer()\fP\s+1. .\"last line comment .TH XHPAcknowledge 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPAcknowledge - Send an Acknowledge to an extended input device. .SH SYNOPSIS .nf \fB #include .sp int XHPAcknowledge (display, deviceid, acknowledge) Display *display; XID deviceid; int acknowledge; \fP .fi .SH ARGUMENTS .PP .TP 12 .I display Specifies the connection to the X server. .TP 12 .I deviceid Specifies the ID of the desired device. .TP 12 .I acknowledge Specifies the acknowledge to be sent. Valid values are: \fIGENERAL_ACKNOWLEDGE\fR, \fIACKNOWLEDGE_1\fR, \fIACKNOWLEDGE_2\fR, \fIACKNOWLEDGE_3\fR, \fIACKNOWLEDGE_4\fR, \fIACKNOWLEDGE_5\fR, \fIACKNOWLEDGE_6\fR, \fIACKNOWLEDGE_7\fR. .PP .SH DESCRIPTION .PP This request is part of an HP-proprietary extension to X. Its functionality has been superseded by the standard \fIXChangeFeedbackControl\fP request. You should use \fIXChangeFeedbackControl\fP instead of \fIXHPAcknowledge\fP if possible. .PP This request sends an acknowledge to an input device. This allows a previously received prompt to be turned off. .PP A prompt is an audio or visual indication that the program controlling the input device is ready for input. The LED on an HP46086A buttonbox is an example of a prompt. A program may indicate its status by turning on a prompt on the appropriate input device. .PP Not all input devices support prompts and acknowledges. Any device that does support a particular prompt will also support the corresponding acknowledge. .PP To determine whether an input device supports a particular prompt and acknowledge, the \fIio_byte\fP field of the \fIXHPDeviceList\fP structure should be examined. The format of this structure is described in the documentation for the \fIXHPListInputDevices\fP request. .SH RETURN VALUE none .SH DIAGNOSTICS .TP 12 .I BadDevice An invalid device ID was specified. .TP 12 .I BadValue An invalid acknowledge was specified. .SH FILES /usr/include/X11/XHPlib.h .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XHPListInputDevices(3x) XHPPrompt(3x) .fi .TH XHPChangeDeviceControl 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPChangeDeviceControl - Change the control attributes of an extension input device. .PP XHPChangeDeviceKeyMapping - Change the key mapping of an extension input device. .PP .SH SYNOPSIS .nf \fB int XHPChangeDeviceControl (display, deviceid, value_mask, values) Display *display; XID deviceid; unsigned long value_mask; XHPDeviceControl *values; int XHPChangeDeviceKeyMapping (display, deviceid, first_keycode, keysyms_per_keycode, keysyms, num_codes) Display *display; XID deviceid; int first_keycode; int keysyms_per_keycode; KeySym *keysyms; int num_codes; \fP .fi .SH ARGUMENTS .PP .TP 25 .I display Specifies the connection to the X server. .TP 25 .I deviceid Specifies the ID of the device whose attributes are to be changed. .SH XHPChangeDeviceControl .TP 25 .I value_mask Specifies which attributes are to be changed. Each bit in the mask specifies one attribute of the specified device. .TP 25 .I values Specifies a pointer to the \fIXHPDeviceControl\fP structure containing the values to be changed. .SH XHPChangeDeviceKeyMapping .TP 25 .I first_keycode Specifies the first keycode that is to be changed. .TP 25 .I keysyms_per_keycode Specifies the number of keysyms per keycode. .TP 25 .I keysyms Specifies a pointer to an array of keysyms that are to be used. .TP 25 .I num_codes Specifies the number of keycodes that are to be changed. .SH DESCRIPTION .PP These requests are part of an HP-proprietary extension to X. Their functionality has been superseded by standard X input device extension requests. \fIXHPChangeDeviceControl\fP has been superseded by \fIXChangeFeedbackControl\fP, and \fIXHPChangeDeviceKeyMapping has been superseded by \fIXChangeDeviceKeyMapping\fP. You should use the standard requests instead of the HP-proprietary requests if possible. .PP These requests are provided to support the use of input devices other than the X keyboard and X pointer device. They allow the control attributes and key mapping of those input devices to be changed. The specified device must have previously been opened (turned on) using the \fIXHPSetInputDevice\fP request. .SH XHPChangeDeviceControl The attributes to be changed are specified in the \fIXHPDeviceControl\fP structure. They are not actually changed unless the corresponding bit is set in the value_mask parameter. .PP The following masks may be ORed into the value_mask: .PP .nf #define DVKeyClickPercent (1L<<0) #define DVBellPercent (1L<<1) #define DVBellPitch (1L<<2) #define DVBellDuration (1L<<3) #define DVLed (1L<<4) #define DVLedMode (1L<<5) #define DVKey (1L<<6) #define DVAutoRepeatMode (1L<<7) #define DVAccelNum (1L<<8) #define DVAccelDenom (1L<<9) #define DVThreshold (1L<<10) .fi .PP The fields of the \fIXHPDeviceControl\fP structure are defined as follows: .PP .nf typedef struct { int key_click_percent; int bell_percent; int bell_pitch; int bell_duration; int led; int led_mode; int key; int auto_repeat_mode; int accelNumerator; int accelDenominator; int threshold; } XHPDeviceControl; .fi .PP The key_click_percent member sets the volume for key clicks between 0 (off) and 100 (loud) inclusive, if possible. A setting of \-1 restores the default. Other negative values generate a \fIBadValue\fP error. .PP The bell_percent sets the base volume for the bell between 0 (off) and 100 (loud) inclusive, if possible. A setting of \-1 restores the default. Other negative values generate a \fIBadValue\fP error. .PP The bell_pitch member sets the pitch (specified in Hz) of the bell, if possible. A setting of \-1 restores the default. Other negative values generate a \fIBadValue\fP error. .PP The bell_duration member sets the duration, specified in milliseconds, of the bell, if possible. A setting of \-1 restores the default. Other negative values generate a \fIBadValue\fP error. .PP If both the led_mode and led members are specified, the state of that LED is changed, if possible. The led_mode member can be set to \fILedModeOn\fP or \fILedModeOff\fP. If only led_mode is specified, the state of all LEDs are changed, if possible. At most 32 LEDs numbered from one are supported. No standard interpretation of LEDs is defined. If an led is specified without an led_mode, a \fIBadMatch\fP error is generated .PP If both the auto_repeat_mode and key members are specified, the auto_repeat_mode of that key is changed (according to \fIAutoRepeatModeOn\fP , \fIAutoRepeatModeOff\fR , or \fIAutoRepeatModeDefault\fP ), if possible. If only auto_repeat_mode is specified, the global auto_repeat mode for the entire device is changed, if possible, and does not affect the per_key settings. If a key is specified without an auto_repeat_mode, a \fIBadMatch\fP error is generated. .SH XHPChangeDeviceKeyMapping The \fIXHPChangeDeviceKeyMapping\fP request, starting with first_keycode, defines the symbols for the specified number of KeyCodes. The symbols for KeyCodes outside this range remained unchanged. The number of elements must be: .PP .nf num_codes * keysyms_per_keycode .fi .PP Otherwise, a \fIBadLength\fP error is generated. The specified first_keycode must be greater than or equal to min_keycode as returned by the \fIXHPListInputDevices\fP request. Otherwise, it generates a \fIBadValue\fP error. In addition, the following expression must be less than or equal to max_keycode as returned by the \fIXHPListInputDevices\fP request, otherwise a \fIBadValue\fP error is generated. .PP .nf first_keycode + (num_codes / keysyms_per_keycode) - 1 .fi .PP KeySym number N, counting from zero, for KeyCode K has the following index in keysyms, counting from zero: .PP .nf (K - first_keycode) * keysyms_per_keycode + N .fi .PP The specified keysyms_per_keycode can be chosen arbitrarily by the client to be large enough to hold all desired symbols. Use a special KeySym value of \fINoSymbol\fP to fill in unused elements for individual KeyCodes. \fINoSymbol\fP may appear in nontrailing positions of the effective list for a KeyCode. \fIXHPChangeDeviceKeyMapping\fP generates a \fIDeviceMappingNotify\fP event. .PP There is no requirement that the X server interpret this mapping. It is merely stored for reading and writing by clients. .SH DIAGNOSTICS .PP \fIXHPChangeDeviceControl\fP can generate \fIBadDevice\fP, \fIBadMatch\fP, and \fIBadValue\fP errors. .PP \fIXHPChangeDeviceKeyMapping\fP can generate \fIBadDevice\fP, \fIBadLength\fP, and \fIBadValue\fP errors. .PP .TP 12 .I BadDevice The specified device does not exist, was not previously enabled via \fIXHPSetInputDevice\fP, or is the X system pointer or X system keyboard. .TP 12 .I BadMatch An LED was specified but no valid LED mode, or a key was specified but no valid AutoRepeat mode. .TP 12 .I BadValue One of the values specified was beyond the range of valid values. .TP 12 .I BadLength The number of elements passed was not equal to keysyms_per_code times num_codes. .SH RETURN VALUE none .SH FILES none .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XHPGetDeviceKeyMapping(3x) XGetKeyboardMapping(3x) XChangeKeyboardMapping(3x) XHPGetDeviceControl(3x) XGetKeyboardControl(3x) XChangeKeyboardControl(3x) XGetPointerControl(3x) XChangePointerControl(3x) .fi .TH XHPConvertLookup 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPConvertLookup \- convert key event into keysym and characters .SH SYNOPSIS \fBint .br XHPConvertLookup(event_struct, buffer_return, bytes_buffer, keysym_return, status_in_out, convert_routine) .br XKeyEvent *event_struct; .br char *buffer_return; .br int bytes_buffer; .br KeySym *keysym_return; .br XComposeStatus *status_in_out; .br int (*convert_routine)();\fP .SH DESCRIPTION .TP 15 \fIevent_struct\fP Specifies the key event structure to be used. You can pass .I XKeyPressedEvent or .I XKeyReleasedEvent . .TP 15 \fIbuffer_return\fP Returns the translated characters. .TP 15 \fIbytes_buffer\fP Specifies the length of the buffer. No more than bytes_buffer of translation are returned. .TP 15 \fIkeysym_return\fP Returns the keysym computed from the event if this argument is not NULL. .TP 15 \fIstatus_in_out\fP Specifies or returns the .I XComposeStatus structure or NULL. .TP 15 \fIconvert_routine\fP Specifies the routine which will map the keysym into a character code, if appropriate. It also handles all other processing necessary for the input language (e.g. input server control for 16-bit languages) If this value is NULL, ISO-Latin1 characters will be returned. .PP The functionality provided by this routine has been superseded by the new X11 R5 Input Method routines. This new functionality should be used whenever possible. See the routine .I XOpenIM and its associated routines. .PP The .I XHPConvertLookup function maps a key event to a keysym and a string. The modifier bits in the key event are used to indicate shift, lock, control and keyboard group. .P Shift, lock and keyboard group modifier bits are used to initially set the keysym. .P If the lock modifier has a caps_lock keysym associated with it, .I XHPConvertLookup interprets the lock modifier to perform caps lock processing using the keysym value. .P It then checks to see if that keysym has been rebound and if it has it returns the appropriate string in .IR buffer_return . .P The keysym and the modifier bits are then passed to the .I convert_routine along with .IR buffer_return , .IR bytes_buffer , and .IR status_in_out . This routine will convert the keysym into a character code if appropriate and return it in the buffer handed to it. It will also handle control processing if appropriate. .mk | The .I convert_routine may use .I status_in_out to contain state information for input. See the manual page for any convert routine used to see how it is used. Also, if multiple input servers are running at the same time, they must each be maintained by separate .I XComposeStatus parameters. .mk .P The calling sequence for .I convert_routine is as follows: .P (*convert_routine)(display, keysym, modifiers, buffer_return, bytes_buffer, status_in_out) .br Display *display; .br Keysym *keysym; .br unsigned int modifiers; .br char *buffer_return; .br int bytes_buffer; .br XComposeStatus *status_in_out; .PP The meanings of the parameters are as follows: .TP 15 \fIdisplay\fP The display from the key event .TP 15 \fIkeysym\fP A pointer to the keysym value of this key event. .TP 15 \fImodifiers\fP The modifiers (state) of this key event. .TP 15 \fIbuffer_return\fP Returns the translated characters. .TP 15 \fIbytes_buffer\fP Specifies the length of the buffer. No more than bytes_buffer of translation are returned. .TP 15 \fIstatus_in_out\fP Specifies or returns the .I XComposeStatus structure or NULL. .PP .I convert_routine will return the number of characters in buffer_return. .P .SH RETURN VALUE The return value is the length of the string returned in .IR buffer_return . .SH EXAMPLES The following example shows an application doing input in HP's Roman 8 character set. .sp .nf XKeyEvent *event; char buffer[80]; KeySym keysym; XComposeStatus *status; extern int XHPInputRoman8(); int count; .sp count = XHPConvertLookup (event, buffer, nbytes, &keysym, &status, XHPInputRoman8); .fi .P The next example shows an application that supports all the default character sets for HP's Eurasian keyboards. .sp .nf Display display; .sp count = XHPConvertLookup (event, buffer, nbytes, &keysym, &status, XHPGetEurasianCvt(display)); .fi .P An application which wished to do input in ISO-LATIN1 would use: .sp .nf count = XHPConvertLookup (event, buffer, nbytes, &keysym, &status, 0); .fi .P An application could provide its own routine to map from keysym to character code. If an application had a routine, .I InputISO_Latin2() that mapped keysyms into ISO-LATIN2 characters it would be used as follows: .sp .nf extern int InputISO_Latin2(); .sp count = XHPConvertLookup (event, buffer, nbytes, &keysym, &status, InputISO_Latin2); .fi .P .I XHPConvertLookup is provided for backwards compatibility only; this routines will be discontinued in a future release of HP-UX. Users desiring the same capabilities as those provided by these routines should use .I XOpenIM, XCreateIC, and .IR XmbLookupString . .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO XHPInputChinese_s(3X), XHPInputChinese_t(3X), XHPInputJapanese(3X), XHPInputKorean(3X), XHPInputRoman8(3X), XHPSetKeyboardLanguage(3X), .SH "INTERNATIONAL SUPPORT" 8-bit and 16-bit character data. .TH XHPDeviceAutoRepeatOn 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPDeviceAutoRepeatOn - Turn autorepeat on for an extension input device. .PP XHPDeviceAutoRepeatOff - Turn autorepeat off for an extension input device. .SH SYNOPSIS .nf \fB int XHPDeviceAutoRepeatOn (display, deviceid, rate) Display *display; XID deviceid; unsigned int rate; .sp int XHPDeviceAutoRepeatOff (display, deviceid) Display *display; XID deviceid; \fP .fi .SH ARGUMENTS .PP .TP 12 .I display Specifies the connection to the X server. .TP 12 .I deviceid Specifies the ID of the desired device. .TP 12 .I rate Valid for \fIXHPDeviceAutoRepeatOn\fP only. Specifies the auto-repeat rate. Valid values are: \fIREPEAT_30\fR, which will cause repeats to take place every 1/30th second, and \fIREPEAT_60\fR, which will cause repeats to take place every 1/60th second. .PP .SH DESCRIPTION .PP These requests are part of an HP-proprietary extension to X. Their functionality has been superseded by the standard X input device extension \fIXChangeFeedbackControl\fP request. You should use \fIXChangeFeedbackControl\fP instead of \fIXHPAutoRepeatOn\fP and \fIXHPAutoRepeatOff\fP if possible. .PP These requests are provided to support the use of input devices other than the X keyboard and X pointer device. They cannot be used to turn auto-repeat on or off for the X keyboard device. The core \fIXAutoRepeatOn\fP and \fIXAutoRepeatOff\fR requests should be used for that purpose. .PP \fIXHPDeviceAutoRepeatOn\fP turns on or changes auto-repeat for an extended input device that is attached to the specified display. .PP \fIXHPDeviceAutoRepeatOff\fP turns off autorepeat for an extended input device that is attached to the specified display. .SH RETURN VALUE none .SH DIAGNOSTICS Either request can return a \fIBadDevice\fP error. \fIXHPDeviceAutoRepeatOn\fP can return a \fIBadValue\fP error. .TP 12 .I BadDevice An invalid device ID was specified. .TP 12 .I BadValue An invalid rate was specified. .SH FILES /usr/include/X11/XHPlib.h .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XAutoRepeatOn(3x) XAutoRepeatOff(3x) .fi .TH XHPDisableReset 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPDisableReset - Disable the reset key sequence. .SH SYNOPSIS .nf \fB int XHPDisableReset (display) Display *display; \fP .fi .SH ARGUMENTS .PP .TP 12 .I display Specifies the connection to the X server. .PP .SH DESCRIPTION .PP This request is intended for use by client programs such as \fIxsecure(1)\fR that provide security to X systems. .PP \fIXHPDisableReset\fR disables the key sequence that is pressed to reset the X server. This request will fail with a \fIBadAccess\fP error if some other client has already disabled the reset key sequence. .PP If a client program disables reset, then terminates, reset will automatically be re-enabled by the X server. .SH RETURN VALUE none .SH DIAGNOSTICS .PP .TP 12 .I BadAccess Some other client has already disabled the reset key sequence. .PP .SH FILES none .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO XHPEnableReset(3x) .TH XHPEnableReset 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPEnableReset - Enable the reset key sequence. .SH SYNOPSIS .nf \fB int XHPEnableReset (display) Display *display; \fP .fi .SH ARGUMENTS .PP .TP 12 .I display Specifies the connection to the X server. .PP .SH DESCRIPTION .PP This request is intended for use by client programs such as \fIxsecure(1)\fR that provide security to X systems. .PP \fIXHPEnableReset\fR enables the key sequence that is pressed to reset the X server. The key sequence used is the one specified in the \fI/usr/lib/X11/X*pointerkeys\fR file, or the default sequence \fILeft_Shift - Control - Break\fR if that file does not exist. .PP This request is only valid for a client that has previously made a successful \fIXHPDisableReset\fR request. For other clients, a BadAccess XError will be returned. .SH DIAGNOSTICS .PP .TP 12 .I BadAccess This client did not previously disable the reset key sequence. .PP .SH RETURN VALUE none .SH FILES none .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO XHPDisableReset(3x) .TH XHPFreeDeviceList 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPFreeDeviceList - Free the input device list. .SH SYNOPSIS .nf \fB #include .sp XHPFreeDeviceList (list) XHPDeviceList *list; \fP .fi .SH ARGUMENTS .PP .TP 12 .I list Specifies the pointer to the \fIXHPDeviceList\fP array returned by a previous call to \fIXHPListInputDevices\fP. .PP .SH DESCRIPTION .PP This request is part of an HP-proprietary extension to X. Its functionality has been superseded by the standard X input device extension \fIXFreeDeviceList\fP request. You should use \fIXListInputDevices\fP and \fIXFreeDeviceList\fP instead of \fIXHPListInputDevices\fP and \fIXHPFreeDeviceList\fP if possible. .PP This request frees the array of \fIXHPDeviceList\fP structures allocated by \fIXHPListInputDevices\fP. .SH RETURN VALUE none .SH FILES /usr/include/X11/XHPlib.h .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO XHPListInputDevices(3x) .TH XHPGetCurrentDeviceMask 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPGetCurrentDeviceMask - Get the current extension event mask. .SH SYNOPSIS .nf \fB int XHPGetCurrentDeviceMask (display, window, deviceid, mask_return) Display *display; Window window; XID deviceid; Mask *mask_return; \fP .fi .SH ARGUMENTS .PP .TP 12 .I display Specifies the connection to the X server. .TP 12 .I window Specifies the ID of the desired window. .TP 12 .I deviceid Specifies the ID of the desired extension input device. .TP 12 .I mask_return Address of a variable into which the server can return the mask. .PP .SH DESCRIPTION .PP This request is part of an HP-proprietary extension to X. Its functionality has been superseded by the standard X input device extension \fIXGetSelectedExtensionEvents\fP request. You should use \fIXGetSelectedExtensionEvents\fP instead of \fIXHPCurrentDeviceMask\fP if possible. .PP This request is provided to support the use of input devices other than the X keyboard and X pointer device. .PP \fIXHPGetCurrentDeviceMask\fR returns the current event selection mask for the specified extended input device and window. This is the mask that was specified by the calling client program on a previous \fIXHPSelectExtensionEvent\fR request. .PP This request is not valid for the X pointer device or the X keyboard device. The current event selection mask for those devices can be obtained by using the \fIXGetwindowAttribute(3x)\fR request. .SH RETURN VALUE none .SH FILES none .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XGetwindowAttribute(3x) XHPSelectExtensionEvent(3x) XHPGetExtEventMask(3x) .fi .TH XHPGetDeviceFocus 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPGetDeviceFocus - Get the focus window ID for an extension input device. .PP XHPGetDeviceMotionEvents - Get the motion history buffer for a device. .PP XHPGetDeviceControl - Get the control attributes of an extension input device. .PP XHPGetDeviceKeyMapping - Get the key mapping of an extension input device. .PP XHPGetDeviceModifierMapping - Get the modifier mapping of an extension input device. .SH SYNOPSIS .nf \fB int XHPGetDeviceFocus (display, deviceid, focus_return, revert_to_return) Display *display; XID deviceid; Window *focus_return; int *revert_to_return; XHPTimeCoord *XHPGetDeviceMotionEvents (display, deviceid, w, start, stop, nevents_return) Display *display; XID deviceid; Window w; Time start, stop; int *nevents_return; int XHPGetDeviceControl (display, deviceid, values_return) Display *display; XID deviceid; XHPDeviceState *values_return; KeySym *XHPGetDeviceKeyMapping (display, deviceid, first_keycode_wanted, keycode_count, keysyms_per_keycode_return) Display *display; XID deviceid; KeyCode first_keycode_wanted; int keycode_count; int *keysyms_per_keycode_return; XModifierKeymap *XHPGetDeviceModifierMapping (display, deviceid) Display *display; XID deviceid; \fP .fi .SH ARGUMENTS .TP 30 .I display Specifies the connection to the X server. .TP 30 .I deviceid Specifies the ID of the desired device. .SH XHPGetDeviceFocus Only .TP 30 .I focus_return Specifies the address of a variable into which the server can return the ID of the window that contains the device focus. .TP 30 .I revert_to_return Specifies the address of a variable into which the server can return the current revert_to status for the device. .SH XHPGetDeviceMotionEvents Only .sp .TP 30 .I window Must contain the constant ALLWINDOWS. .TP 30 .I start Specifies the start time. .TP 30 .I stop Specifies the stop time. .TP 30 .I nevents_return Specifies the address of a variable into which the server will return the number of events in the motion buffer returned for this request. .SH XHPGetDeviceControl Only .sp .TP 30 .I values_return Specifies a pointer to an \fIXHPDeviceState\fP structure in which the device values will be returned. .SH XHPGetDeviceKeyMapping Only .sp .TP 30 .I first_keycode_wanted Specifies the first keycode that is to be returned. .TP 30 .I keycode_count Specifies the number of keycodes that are to be returned. .TP 30 .I keysyms_per_keycode_return Returns the number of keysyms per keycode. .SH DESCRIPTION .PP These requests are part of an HP-proprietary extension to X. Their functionality has been superseded by standard X input device extension requests. You should use \fIXGetDeviceFocus\fP instead of \fIXHPGetDeviceFocus\fP, \fIXGetDeviceMotionEvents\fP instead of \fIXHPGetDeviceMotionEvents\fP, \fIXGetFeedbackControl\fP instead of \fIXHPGetDeviceControl\fP, \fIXGetDeviceKeyMapping\fP instead of \fIXHPGetDeviceKeyMapping\fP, and \fIXGetDeviceModifierMapping\fP instead of \fIXHPGetDeviceModifierMapping\fP if possible. .PP These requests are provided to support the use of input devices other than the X keyboard device and X pointer device. .SH XHPGetDeviceFocus \fIXHPGetDeviceFocus\fR allows a client to determine the focus for a particular extended input device. It returns the focus window id and the current focus state of the specified extended input device. .PP This request may not be used to determine the focus of the X keyboard device. The \fIXGetInputFocus\fR request should be used for that purpose. .SH XHPGetDeviceMotionEvents .sp This request returns all events in the device's motion history buffer that fall between the specified start and stop times inclusive. If the start time is in the future, or is later than the stop time, no events are returned. .PP For all currently supported input devices, the window parameter must be the constant \fIALLWINDOWS\fR, which can be obtained by including \fI\fR. .PP The return type for this request is a structure defined as follows: .nf typedef struct { Time time; unsigned short *data; } XHPTimeCoord; .fi .PP In order to correctly interpret the data returned by this request, client programs need information about the device that generated that data. This information is reported by the \fIXHPListInputDevices\fR request. .PP The data field of the \fIXHPTimeCoord\fR structure is a pointer to an array of data items. Each item is of type short, and there is one data item per axis of motion reported by the device. The number of axes reported by the device can be determined from the \fInum_axes\fR field of the \fIHPDeviceList\fR structure for the device that is returned by the \fIXHPListInputDevices\fR request. .PP The value of the data items depends on the mode of the device, which is reported in the mode field of the \fIXHPDeviceList\fR request, and may be compared to constants defined in \fI\fR. If the mode is \fIABSOLUTE\fR, the data items are the raw values generated by the device. These may be scaled by the client program using the maximum values that the device can generate for each axis of motion that it reports. The maximum value for each axis is reported in the \fIXHPaxis_info\fR structure pointed to by the \fIXHPDeviceList\fR structure. .PP If the mode is \fIRELATIVE\fR, the data items are the relative values generated by the device. The client program must choose an initial position for the device and maintain a current position by accumulating these relative values. .PP The client program should use \fIXFree\fR to free the data returned by this request. .PP This request is not valid for the X pointer device, or for devices that do not generate motion events. Invoking this request for an invalid device will result in a \fIBadDevice\fR error. .PP The motion history buffer for the X pointer device can be obtained by using the \fIXGetMotionEvents(3x)\fR request. .SH EXAMPLE The following code fragment shows how positional data could be received from a graphics tablet via the motion buffer. It assumes that the client only is interested in the first two axes of motion. .nf #include /* Find the graphics tablet information via XHPListInputDevices */ /* Scale the input to a window whose origin is at winx, winy */ /* and whose size is winw by winh. */ slist = XHPListInputDevices (disp, &ndevices); for (i=0,list=slist; itype == TABLET) { XHPSetInputDevice (disp, list->x_id, (ON | DEVICE_EVENTS)); tablet = list->x_id; ax = list->axes; if (list->mode == ABSOLUTE) { scalex = (float) winw / (float) (ax++)->max_val; scaley = (float) winh / (float) (ax++)->max_val; } else { scalex = 1; scaley = 1; } axes = list->num_axes; } XHPFreeDeviceList (slist); buf = XHPGetDeviceMotionEvents (disp, tablet, ALLWINDOWS, start, stop, &nevents); savbuf = buff; for (i=0; idata; time = buf->time; x = winx + (*dp++ * scalex); y = winy + (*dp++ * scaley); /* now do something with the motion data. */ buf++; } XFree (savbuf); .fi .SH XHPGetDeviceControl .sp The \fIXHPGetDeviceControl\fP request returns the control attributes of the device in the \fIXHPDeviceState\fP structure. .PP The fields of the \fIXHPDeviceState\fP structure are defined as follows: .PP .nf typedef struct { int key_click_percent; int bell_percent; unsigned int bell_pitch; unsigned int bell_duration; unsigned long led_mask; int global_auto_repeat; int accelNumerator; int accelDenominator; int threshold; char auto_repeats[32]; } XHPDeviceState; .fi .PP For the LEDs, the least significant bit of led_mask corresponds to LED one, and each bit set to 1 in led_mask indicates an LED that is lit. The auto_repeats member is a bit vector. Each bit set to 1 indicates that auto-repeat is enabled for the corresponding key. The vector is represented as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N+7, with the least significant bit in the byte representing key 8N. The global_auto_repeat member can be set to either \fIAutoRepeatModeOn\fP or \fIAutoRepeatModeOff\fP. .SH XHPGetDeviceKeyMapping .sp The \fIXHPGetDeviceKeyMapping\fP request, starting with first_keycode, returns the symbols for the specified number of KeyCodes. The value specified in the first_keycode argument must be greater than or equal to min_keycode as returned by the \fIXHPListInputDevices\fP request. Otherwise, \fIXHPGetDeviceKeyMapping\fP generates a \fIBadValue\fP error. In addition, the following expression must be less than or equal to max_keycode as returned by the \fIXHPListInputDevices\fP request: .PP .nf first_keycode + keycode_count - 1 .fi .PP If this is not the case, a \fIBadValue\fP error is generated. The number of elements in the KeySyms list is: .PP .nf keycode_count * keysyms_per_keycode_return .fi .PP KeySym number N, counting from zero, for KeyCode K has the following index in the list, counting from zero: .PP .nf (K - first_code) * keysyms_per_code + N .fi .PP The keysyms_per_keycode_return value is chosen arbitrarily by the X server to be large enough to report all requested symbols. A special KeySym value of \fINoSymbol\fP is used to fill in unused elements for individual KeyCodes. .PP To free the storage returned by \fIXHPGetDeviceKeyMapping\fP, use \fIXFree\fP. .SH XHPGetDeviceModifierMapping .sp The \fIXHPGetDeviceModifierMapping\fP request returns a newly created \fIXModifierKeymap\fP structure that contains the keys being used as modifiers for the specified device. The structure should be freed after use by calling \fIXFreeModifiermap\fP. If only zero values appear in the set for any modifier, that modifier is disabled. .SH DIAGNOSTICS \fIXHPGetDeviceKeyMapping\fP can generate \fIBadDevice\fP and \fIBadValue\fP errors. .TP 12 .I BadDevice The specified device does not exist, was not previously enabled via \fIXHPSetInputDevice\fP, or is the X system pointer or X system keyboard. .TP 12 .I BadValue One of the values specified was beyond the range of valid values. .SH RETURN VALUE \fIXHPGetDeviceMotionEvents\fP returns a pointer to the motion history buffer. .PP \fIXHPGetDeviceKeyMapping\fP returns a pointer to an array of KeySyms. .PP \fIXHPGetDeviceModifierMapping\fP returns an \fIXModifierMap\fP structure that contains the keys being used as modifiers for the device. .SH FILES none .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XGetInputFocus(3x) XHPListInputDevices(3x) XHPSetDeviceFocus(3x) XGetMotionEvents(3x) XHPListInputDevices(3x) XHPChangeDeviceControl(3x) XGetKeyboardControl(3x) XChangeKeyboardControl(3x) XGetPointerControl(3x) XChangePointerControl(3x) XHPChangeDeviceKeyMapping(3x) XGetKeyboardMapping(3x) XChangeKeyboardMapping(3x) XGetModifierMapping(3x) XChangeModifierMapping(3x) XHPSetDeviceModifierMapping(3x) .fi .TH XHPGetEurasianCvt 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPGetEurasianCvt \- return the convert routine for Eurasian keyboards .SH SYNOPSIS \fB#include .sp 1 PFI .br XHPGetEurasianCvt(display) .br Display *display;\fR .SH DESCRIPTION .I XHPGetEurasianCvt will return the convert routine required by \fIXHPConvertLookup\fR to convert keysyms to HP character codes. The \fIdisplay\fR argument is used to identify the keymap currently associated with the \fIdisplay\fR structure. .P Note that calling \fIXHPGetEurasianCvt\fR forces all convert routines for all character sets that correspond to HP keyboards to be linked with your code. If this is not desired, this routine should not be used. .P Users of this routine will also want to perform initialization of the keyboard previous to its use in .IR XHPConvertLookup . A macro has been provided that will do this. This macro, .IR XHPInputInit, should be called as part of the initialization of any client making use .IR XHPGetEurasianCvt . .P .I XHPConvertLookup and .I XHPGetEurasianCvt are provided for backwards compatibility only; these routines will be discontinued in a future release of HP-UX. Users desiring the same capabilities as those provided by these routines should use .I XOpenIM, XCreateIC, and .IR XmbLookupString . .SH RETURN VALUE .I XHPGetEurasianCvt returns a pointer to the convert routine if it succeeds; it returns zero upon failure. .SH EXAMPLES The following is an extract from an application that supports all the default character sets for HP's Eurasian keyboards. The call to \fIXHPConvertLookup\fR converts a keyevent to a keysym, and then into a string of characters. The function returned by \fIXHPGetEurasianCvt\fR tells \fIXHPConvertLookup\fR into which HP character set the string is to be encoded. .sp .nf Display *display; XComposeStatus *status; .sp XHPInputInit(display, status); . . . count = XHPConvertLookup (event, buffer, nbytes, &keysym, status, XHPGetEurasianCvt(display)); .fi .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO XHPConvertLookup(3X), XHPInputChinese_s(3X), XHPInputChinese_t(3X), XHPInputJapanese(3X), XHPInputKorean(3X), XHPInputRoman8(3X), XHPSetKeyboardMapping(3X) .TH XHPGetExtEventMask 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPGetExtEventMask - Get an extension event mask. .SH SYNOPSIS .nf \fB int XHPGetExtEventMask (display, event_constant, event_type, event_mask) Display *display; long event_constant; long *event_type; /* RETURN */ Mask *event_mask; /* RETURN */ \fP .fi .SH ARGUMENTS .PP .TP 12 .I display Specifies the connection to the X server. .PP .TP 12 .I event_constant Specifies the constant corresponding to the desired event. .TP 12 .I event_type Specifies the address of a variable in which the server can return the event type of the desired event. .TP 12 .I event_mask Specifies the address of a variable in which the server can return the event mask for the desired event. .PP .SH DESCRIPTION This request is provided to support the use of input devices other than the X pointer device and X keyboard device. .PP This request is part of an HP-proprietary extension to X. Its functionality has been superseded by macros defined in the standard X input device extension header file \fIXInput.h\fP. You should use the standard input device extension instead of \fIXHPGetExtEventMask\fP if possible. .PP \fIXHPGetExtEventMask\fR is used by client programs to determine the event mask to be used in selecting extended events. The request passes a constant to the server that corresponds to the desired event. The server returns the event mask and event type for the desired event. .PP Valid constants that may be used by the client to request corresponding event masks and types are: .nf \fIHPDeviceKeyPressreq\fR \fIHPDeviceKeyReleasereq\fR \fIHPDeviceButtonPressreq\fR \fIHPDeviceButtonReleasereq\fR \fIHPDeviceMotionNotifyreq\fR \fIHPDeviceFocusInreq\fR \fIHPDeviceFocusOutreq\fR \fIHPProximityInreq\fR \fIHPProximityOutreq\fR \fIHPDeviceKeymapNotifyreq\fR .fi .PP For example, if an X system was configured with an extension key device, and a client program had determined the device ID of that device via \fIXHPListInputDevices\fR, and the client program wished to receive key presses from that device in window \fIwin\fR, it would do the following: .nf #include Display display; Window win; XID deviceid; long devicekeypresstype; Mask devicekeypressmask; (connection to the X server) (determining the device id via XHPListInputDevices) XHPGetExtEventMask (display, HPDeviceKeyPressreq, &devicekeypresstype, &devicekeypressmask); XHPSelectExtensionEvent (display, window, deviceid, devicekeypressmask); XNextEvent (display, &event); if (event.type == devicekeypresstype) (process the event) .if .SH DIAGNOSTICS .PP .TP 12 .I BadEvent The constant passed was not one of the valid constants. .SH RETURN VALUE Returns the mask if successful, -1 if failed. .SH FILES none .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XHPListInputDevices(3x) XHPSelectExtensionEvent(3x) XHPGetCurrentDeviceMask(3x) .fi .TH XHPGetServerMode 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPGetServerMode - Get the mode of the specified screen. .SH SYNOPSIS .nf \fB int XHPGetServerMode (display, screen) Display *display; int screen; \fP .fi .SH ARGUMENTS .PP .TP 12 .I display Specifies the connection to the X server. .TP 12 .I screen Specifies the number of the screen whose mode is requested. .PP .SH DESCRIPTION .PP This request enables a client program to determine the mode of a screen. The mode returned is an integer that can be compared against one of the predefined modes. The following modes are defined: .PP .TP 30 .I XHPOVERLAY_MODE The X server is running in the overlay planes. .TP 30 .I XHPIMAGE_MODE The X server is running in the image planes. .TP 30 .I XHPSTACKED_SCREENS_MODE The X server is running with the overlay and image planes on different screens. .TP 30 .I XHPCOMBINED_MODE The X server is running in both the overlay and image planes. .PP These constants can be obtained by including the file \fI/usr/include/X11/XHPproto.h\fP. .PP If an invalid screen number is used, a \-1 will be returned by this request. .SH DIAGNOSTICS The return value indicates success or failure. .PP .SH RETURN VALUE This request returns the display mode if the request is successful, and a \-1 if an invalid screen id is used. .SH FILES /usr/include/X11/XHPproto.h .SH ORIGIN Hewlett-Packard Company .TH XHPGrabDevice 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPGrabDevice - Grab an extended input device. .PP XHPGrabDeviceButton - Establish a passive grab on a button on an extension input device. .PP XHPGrabDeviceKey - Establish a passive grab on a key on an extension input device. .SH SYNOPSIS .nf \fB int XHPGrabDevice (display, deviceid, grab_window, owner_events, pointer_mode, device_mode, time) Display *display; XID deviceid; Window grab_window; Bool owner_events; int pointer_mode, device_mode; Time time; int XHPGrabDeviceButton (display, deviceid, button, modifiers, grab_window, owner_events, event_mask, pointer_mode, device_mode) Display *display; XID deviceid; unsigned int button; unsigned int modifiers; Window grab_window; Bool owner_events; unsigned int event_mask; int pointer_mode, device_mode; int XHPGrabDeviceKey (display, deviceid, keycode, modifiers, grab_window, owner_events, pointer_mode, device_mode) Display *display; XID deviceid; unsigned int keycode; unsigned int modifiers; Window grab_window; Bool owner_events; int pointer_mode, device_mode; \fP .fi .SH ARGUMENTS .PP .TP 15 .I display Specifies the connection to the X server. .TP 15 .I deviceid Specifies the ID of the desired device. .TP 15 .I grab_window Specifies the ID of a window associated with the device specified above. .TP 15 .I owner_events Specifies a boolean value of either \fITrue\fP or \fIFalse\fP. .TP 15 .I pointer_mode Only the constant \fIGrabModeAsync\fP is currently supported. .TP 15 .I device_mode Only the constant \fIGrabModeAsync\fP is currently supported. .SH XHPGrabDevice .TP 15 .I time Specifies the time. This may be either a timestamp expressed in milliseconds, or .I CurrentTime. .SH XHPGrabDeviceButton .TP 15 .I button Specifies the code of the button that is to be grabbed. You can pass either the keycode or \fIAnyButton\fP. .TP 15 .I event_mask Specifies which device events are to be reported to the client. They can be the bitwise inclusive OR of these device mask bits: \fIDeviceButtonPressMask\fP, \fIDeviceButtonReleaseMask\fP, \fIDevicePointerMotionmask\fP, \fIDeviceKeymapStateMask\fP. .SH XHPGrabDeviceKey .TP 15 .I keycode Valid for \fIXHPGrabDeviceKey\fP only. Specifies the keycode of the key that is to be grabbed. You can pass either the keycode or \fIAnyKey\fP. .SH XHPGrabDeviceKey and XHPGrabDeviceButton Only .TP 15 .I modifiers Specifies the set of keymasks. This mask is the bitwise inclusive OR of these keymask bits: \fIShiftMask\fP, \fILockMask\fP, \fIControlMask\fP, \fIMod1Mask\fP, \fIMod2Mask\fP, \fIMod3Mask\fP, \fIMod4Mask\fP, \fIMod5Mask\fP. .PP You can also pass \fIAnyModifier\fP, which is equivalent to issuing the grab key request for all possible modifier combinations (including the combination of no modifiers). .SH DESCRIPTION .PP These requests are part of an HP-proprietary extension to X. Their functionality has been superseded by standard X input device extension requests. You should use \fIXGrabDevice\fP instead of \fIXHPGrabDevice\fP, \fIXGrabDeviceButton\fP instead of \fIXHPGrabDeviceButton\fP, and \fIXGrabDeviceKey\fP instead of \fIXHPGrabDeviceKey\fP if possible. .PP These requests are provided to support the use of input devices other than the X keyboard and X pointer device. They allow a client to grab an extension input device, or a button or key on such a device. The device must have previously been opened (turned on) using the \fIXHPSetInputDevice\fP request. .PP .SH XHPGrabDevice \fIXHPGrabDevice\fP causes an \fIHPDeviceFocusIn\fP event to be sent to the client doing the grab, and an \fIHPDeviceFocusOut\fP event to be sent to the window losing the device focus. \fIXHPGrabDevice\fP cannot be used to grab the X pointer device or the X keyboard device. The core \fIXGrabPointer\fP and \fIXGrabKeyboard\fP requests should be used for that purpose. .PP If owner_events is \fIFalse\fP, events are reported with respect to the grab_window. If owner_events is \fITrue\fP, events are reported normally. .PP .SH XHPGrabDeviceButton The \fIXHPGrabDeviceButton\fP request establishes a passive grab on a device. Consequently, in the future, .IP \(bu 5 IF the device is not grabbed and the specified button is logically pressed when the specified modifier keys logically are down (and no other buttons or modifier keys are down), .IP \(bu 5 AND the grab window contains the device, .IP \(bu 5 AND a passive grab on the same device and button/key combination does not exist on any ancestor of the grab window, .IP \(bu 5 THEN the device is actively grabbed, as for \fIXHPGrabDevice\fP, the last-grab time is set to the time at which the button was pressed (as transmitted in the \fIDeviceButtonPress\fP event), and the \fIDeviceButtonPress\fP event is reported. .PP The interpretation of the remaining arguments is as for \fIXHPGrabDevice\fP. The active grab is terminated automatically when logical state of the device has all buttons released (independent of the logical state of the modifier keys). .PP Note that the logical state of a device (as seen by means of the X protocol) may lag the physical state if device event processing is frozen. .PP A modifier of \fIAnyModifier\fP is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned keycodes. A Button of \fIAnyButton\fP is equivalent to issuing the request for all possible Buttoncodes. Otherwise, it is not required that the specified button be assigned to a physical button. .PP A \fIBadAccess\fP error is generated if some other client has issued a \fIXHPGrabDeviceButton\fP with the same device and button combination on the same window. When using \fIAnyModifier\fP or \fIAnyButton\fP, the request fails completely and the X server generates a \fIBadAccess\fP error and no grabs are established if there is a conflicting grab for any combination. .PP \fIXHPGrabDeviceButton\fP can generate \fIBadDevice\fP, \fIBadAccess\fP, \fIBadWindow\fP, and \fIBadValue\fP errors. .PP This request cannot be used to grab a button on the X pointer device. The core \fIXGrabButton\fP request should be used for that purpose. .SH XHPGrabDeviceKey The \fIXHPGrabDeviceKey\fP request establishes a passive grab on a device. Consequently, in the future, .IP \(bu 5 IF the device is not grabbed and the specified key, which itself can be a modifier key, is logically pressed when the specified modifier keys logically are down (and no other keys are down), .IP \(bu 5 AND no other modifier keys logically are down, .IP \(bu 5 AND EITHER the grab window is an ancestor of (or is) the focus window OR the grab window is a descendent of the focus window and contains the pointer, .IP \(bu 5 AND a passive grab on the same device and key combination does not exist on any ancestor of the grab window, .IP \(bu 5 THEN the device is actively grabbed, as for \fIXHPGrabDevice\fP, the last-grab time is set to the time at which the key was pressed (as transmitted in the \fIDeviceKeyPress\fP event), and the \fIDeviceKeyPress\fP event is reported. .PP The interpretation of the remaining arguments is as for \fIXHPGrabDevice\fP. The active grab is terminated automatically when logical state of the device has the specified key released (independent of the logical state of the modifier keys). .PP Note that the logical state of a device (as seen by means of the X protocol) may lag the physical state if device event processing is frozen. .PP A modifier of \fIAnyModifier\fP is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned keycodes. A key of \fIAnyKey\fP is equivalent to issuing the request for all possible keycodes. Otherwise, the key must be in the range specified by min_keycode and max_keycode as returned by \fIXHPListInputDevices\fP. If it is not within that range, \fIXHPGrabDeviceKey\fP generates a \fIBadValue\fP error. .PP A \fIBadAccess\fP error is generated if some other client has issued a \fIXHPGrabDeviceKey\fP with the same device and key combination on the same window. When using \fIAnyModifier\fP or \fIAnyKey\fP, the request fails completely and the X server generates a \fIBadAccess\fP error and no grabs are established if there is a conflicting grab for any combination. .PP \fIXHPGrabDeviceKey\fP can generate \fIBadDevice\fP, \fIBadAccess\fP, \fIBadWindow\fP, and \fIBadValue\fP errors. .PP This request cannot be used to grab a key on the X keyboard device. The core \fIXGrabKey\fP request should be used for that purpose. .SH DIAGNOSTICS .TP 12 .I BadDevice An invalid device ID was specified. .TP 12 .I BadAccess An grab combination was specified that conflicts with an existing grab. .TP 12 .I BadWindow An invalid window ID was specified. .TP 12 .I BadValue An invalid mode was specified. .SH RETURN VALUE none .SH FILES none .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XHPListInputDevices(3x) XHPSetInputDevice(3x) XHPUngrabDevice(3x) XGrabKeyboard(3x) XGrabPointer(3x) XGrabButton(3x) .fi .TH XHPInputChinese_s 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPInputChinese_s \- map keysyms into Chinese_s characters. .SH SYNOPSIS \fB int XHPInputChinese_s(display, keysym, modifiers, buffer_return, bytes_buffer, status_in_out) .nf Display *display; KeySym *keysym; unsigned int modifiers; char *buffer_return; int bytes_buffer; XComposeStatus *status_in_out;\fR .fi .SH DESCRIPTION .TP 15 \fIdisplay\fP Specifies the connection to the X server. .TP 15 \fIkeysym\fP Specifies the keysym that is to be converted into a character. .TP 15 \fImodifiers\fP Specifies the modifiers to be applied to the .IR keysym . .TP 15 \fIbuffer_return\fP Returns the translated characters. .TP 15 \fIbytes_buffer\fP Specifies the length of the buffer. No more than bytes_buffer of translation are returned. .TP 15 \fIstatus_in_out\fP Specifies the .I XComposeStatus structure. .PP .I XHPInputChinese_s will convert .I keysym into an ASCII character, if appropriate. It will also handle 16-bit input using NLIO. If the value pointed to by .I keysym is used by the NLIO server, that value will be changed to .I NoSymbol. It will use .I status_in_out to keep the state information necessary to control NLIO. This structure must contain null values before this routine is first invoked, and must remain unchanged between uses. .P This routine will also process the control modifier. .P .I XHPInputChinese_s will use .I /usr/lbin/X11/xc0input as the NLIO server. NLIO input will be invoked when the right extend char key is hit, and it will be terminated when the left extend char key is hit. If the appropriate server is not running it will be started when it is first invoked. .P Users of this routine may want to exec the NLIO server previous to it being started up when the invoke key is first struck. This can also be accomplished using .IR XHPNlioctl . .P The keys used to invoke and terminate the NLIO server can also be changed using .IR XHPNlioctl . .P This routine is intended to be used in conjunction with .I XHPConvertLookup .P .I XHPConvertLookup and .I XHPInputChinese_s are provided for backwards compatibility only; these routines will be discontinued in a future release of HP-UX. Users desiring the same capabilities as those provided by these routines should use .I XOpenIM, XCreateIC, and .IR XmbLookupString . .SH RETURN VALUE The return value is the length of the string returned in .IR buffer_return . .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO XHPConvertLookup(3X), XHPNlioctl(3X) .SH "INTERNATIONAL SUPPORT" 8-bit and 16-bit character data. .TH XHPInputChinese_t 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPInputChinese_t \- map keysyms into Chinese_t characters. .SH SYNOPSIS \fB int XHPInputChinese_t(display, keysym, modifiers, buffer_return, bytes_buffer, status_in_out) .nf Display *display; KeySym *keysym; unsigned int modifiers; char *buffer_return; int bytes_buffer; XComposeStatus *status_in_out; \fR .fi .SH DESCRIPTION .TP 15 \fIdisplay\fP Specifies the connection to the X server. .TP 15 \fIkeysym\fP Specifies the keysym that is to be converted into a character. .TP 15 \fImodifiers\fP Specifies the modifiers to be applied to the .IR keysym . .TP 15 \fIbuffer_return\fP Returns the translated characters. .TP 15 \fIbytes_buffer\fP Specifies the length of the buffer. No more than bytes_buffer of translation are returned. .TP 15 \fIstatus_in_out\fP Specifies the .I XComposeStatus structure. .PP .I XHPInputChinese_t will convert .I keysym into an ASCII character, if appropriate. It will also handle 16-bit input using NLIO. If the value pointed to by .I keysym is used by the NLIO server, that value will be changed to .I NoSymbol. It will use .I status_in_out to keep the state information necessary to control NLIO. This structure must contain null values before this routine is first invoked, and must remain unchanged between uses. .P This routine will also process the control modifier. .P .I XHPInputChinese_t will use .I /usr/llib/X11/xt0input as the NLIO server. NLIO input will be invoked when the right extend char key is hit, and it will be terminated when the left extend char key is hit. If the appropriate server is not running it will be started when it is first invoked. .P Users of this routine may want to exec the NLIO server previous to it being started up when the invoke key is first struck. This can also be accomplished using .IR XHPNlioctl . .P The keys used to invoke and terminate the NLIO server can also be changed using .IR XHPNlioctl . .P This routine is intended to be used in conjunction with .I XHPConvertLookup .P .I XHPConvertLookup and .I XHPInputChinese_t are provided for backwards compatibility only; these routines will be discontinued in a future release of HP-UX. Users desiring the same capabilities as those provided by these routines should use .I XOpenIM, XCreateIC, and .IR XmbLookupString . .SH RETURN VALUE The return value is the length of the string returned in .IR buffer_return . .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO XHPConvertLookup(3X), XHPNlioctl(3X) .SH "INTERNATIONAL SUPPORT" 8-bit and 16-bit character data. .TH XHPInputISO7sub 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPInputISO7sub \- map keysyms into ISO 7-bit substitution characters. .SH SYNOPSIS \fB int XHPInputISO7sub(display, keysym, modifiers, buffer_return, bytes_buffer, status_in_out) .nf Display *display; KeySym *keysym; unsigned int modifiers; char *buffer_return; int bytes_buffer; XComposeStatus *status_in_out;\fR .fi .SH DESCRIPTION .TP 15 \fIdisplay\fP Specifies the connection to the X server. .TP 15 \fIkeysym\fP Specifies the keysym that is to be converted into an ISO 7-bit substitution character. .TP 15 \fImodifiers\fP Specifies the modifiers to be applied to the .IR keysym . .TP 15 \fIbuffer_return\fP Returns the translated characters. .TP 15 \fIbytes_buffer\fP Specifies the length of the buffer. No more than bytes_buffer of translation are returned. .TP 15 \fIstatus_in_out\fP Specifies the .I XComposeStatus structure. .PP .I XHPInputISO7sub will convert .I keysym into a ISO 7-bit substitution character, if appropriate. This routine will also process the control modifier. The return value is the length of the string returned in .IR buffer_return . This routine is intended to be used in conjunction with .IR XHPConvertLookup . .P .I status_in_out is used to hold the information necessary to perform 7-bit substitution input. This structure must contain null values before this routine is first invoked, and must remain unchanged between uses. .P .I XHPConvertLookup and .I XHPInputISO7sub are provided for backwards compatibility only; these routines will be discontinued in a future release of HP-UX. The operating system provides no direct support for processing ISO 7-bit substitution characters. Users of ISO 7-bit substitution character set should migrate their data to a supported 8-bit encoding, such as ISO 8859.1. Additionally, users desiring the same capabilities as those provided by these routines should use .I XOpenIM, XCreateIC, and .IR XmbLookupString . .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO XHPConvertLookup(3X) .TH XHPInputJapanese 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPInputJapanese \- map keysyms into Japanese characters. .SH SYNOPSIS \fB int XHPInputJapanese(display, keysym, modifiers, buffer_return, bytes_buffer, status_in_out) .nf Display *display; KeySym *keysym; unsigned int modifiers; char *buffer_return; int bytes_buffer; XComposeStatus *status_in_out; .fi \fR .SH DESCRIPTION .TP 15 \fIdisplay\fP Specifies the connection to the X server. .TP 15 \fIkeysym\fP Specifies the keysym that is to be converted into a Kanji character. .TP 15 \fImodifiers\fP Specifies the modifiers to be applied to the .IR keysym . .TP 15 \fIbuffer_return\fP Returns the translated characters. .TP 15 \fIbytes_buffer\fP Specifies the length of the buffer. No more than bytes_buffer of translation are returned. .TP 15 \fIstatus_in_out\fP Specifies the .I XComposeStatus structure. .PP .I XHPInputJapanese will convert .I keysym into a Kanji8 character, if appropriate. It will also handle 16-bit input using NLIO. If the value pointed to by .I keysym is used by the NLIO server, that value will be changed to .I NoSymbol. It will use .I status_in_out to keep the state information necessary to control NLIO. This structure must contain null values before this routine is first invoked, and must remain unchanged between uses. .P This routine will also process the control modifier. .P .I XHPInputJapanese will use /usr/llib/X11/xj0input as the NLIO server. The left extend char key will cause the state of NLIO input to be toggled between invoked and terminated. If the appropriate server is not running it will be started when it is first invoked. .P Users of this routine may want to exec the NLIO server previous to it being started up when the invoke key is first struck. This can also be accomplished using .IR XHPNlioctl . .P The keys used to invoke and terminate the NLIO server can also be changed using .IR XHPNlioctl . .P This routine is intended to be used in conjunction with .I XHPConvertLookup .P .I XHPConvertLookup and .I XHPInputJapanese are provided for backwards compatibility only; these routines will be discontinued in a future release of HP-UX. Users desiring the same capabilities as those provided by these routines should use .I XOpenIM, XCreateIC, and .IR XmbLookupString . .SH RETURN VALUE The return value is the length of the string returned in .IR buffer_return . .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO XHPConvertLookup(3X), XHPNlioctl(3X) .SH "INTERNATIONAL SUPPORT" 8-bit and 16-bit character data. .TH XHPInputKorean 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPInputKorean \- map keysyms into Korean characters. .SH SYNOPSIS \fB int XHPInputKorean(display, keysym, modifiers, buffer_return, bytes_buffer, status_in_out) .nf Display *display; KeySym *keysym; unsigned int modifiers; char *buffer_return; int bytes_buffer; XComposeStatus *status_in_out; .fi \fR .SH DESCRIPTION .TP 15 \fIdisplay\fP Specifies the connection to the X server. .TP 15 \fIkeysym\fP Specifies the keysym that is to be converted into a character. .TP 15 \fImodifiers\fP Specifies the modifiers to be applied to the .IR keysym . .TP 15 \fIbuffer_return\fP Returns the translated characters. .TP 15 \fIbytes_buffer\fP Specifies the length of the buffer. No more than bytes_buffer of translation are returned. .TP 15 \fIstatus_in_out\fP Specifies the .I XComposeStatus structure. .PP .I XHPInputKorean will convert .I keysym into an ASCII character, if appropriate. It will also handle 16-bit input using NLIO. If the value pointed to by .I keysym is used by the NLIO server, that value will be changed to .I NoSymbol. It will use .I status_in_out to keep the state information necessary to control NLIO. This structure must contain null values before this routine is first invoked, and must remain unchanged between uses. .P This routine will also process the control modifier. .P .I XHPInputKorean will use /usr/llib/X11/xk0input as the NLIO server. NLIO input will be invoked when the right extend char key is hit, and it will be terminated when the left extend char key is hit. If the appropriate server is not running it will be started when it is first invoked. .P Users of this routine may want to exec the NLIO server previous to it being started up when the invoke key is first struck. This can also be accomplished using .IR XHPNlioctl . .P The keys used to invoke and terminate the NLIO server can also be changed using .IR XHPNlioctl . .P This routine is intended to be used in conjunction with .I XHPConvertLookup .P .I XHPConvertLookup and .I XHPInputChinese_t are provided for backwards compatibility only; these routines will be discontinued in a future release of HP-UX. Users desiring the same capabilities as those provided by these routines should use .I XOpenIM, XCreateIC, and .IR XmbLookupString . .SH RETURN VALUE The return value is the length of the string returned in .IR buffer_return . .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO XHPConvertLookup(3X), XHPNlioctl(3X) .SH "INTERNATIONAL SUPPORT" 8-bit and 16-bit character data. .TH XHPInputRoman8 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPInputRoman8 \- map keysyms into Roman8 characters. .SH SYNOPSIS \fB int XHPInputRoman8(display, keysym, modifiers, buffer_return, bytes_buffer, status_in_out) .nf Display *display; KeySym *keysym; unsigned int modifiers; char *buffer_return; int bytes_buffer; XComposeStatus *status_in_out; .fi \fR .SH DESCRIPTION .TP 15 \fIdisplay\fP Specifies the connection to the X server. .TP 15 \fIkeysym\fP Specifies the keysym that is to be converted into a Roman8 character. .TP 15 \fImodifiers\fP Specifies the modifiers to be applied to the .IR keysym . .TP 15 \fIbuffer_return\fP Returns the translated characters. .TP 15 \fIbytes_buffer\fP Specifies the length of the buffer. No more than bytes_buffer of translation are returned. .TP 15 \fIstatus_in_out\fP Specifies the .I XComposeStatus structure. .PP .I XHPInputRoman8 will convert .I keysym into a Roman8 character, if appropriate. It will also handle the input of muted characters. It will use .I status_in_out to hold the state information necessary to do this. This structure must contain null values before this routine is first invoked, and must remain unchanged between uses. .P This routine will also process the control modifier. .P This routine is intended to be used in conjunction with .I XHPConvertLookup .P .I XHPConvertLookup and .I XHPInputRoman8 are provided for backwards compatibility only; these routines will be discontinued in a future release of HP-UX. Users desiring the same capabilities as those provided by these routines should use .I XOpenIM, XCreateIC, and .IR XmbLookupString . .SH RETURN VALUE The return value is the length of the string returned in .IR buffer_return . .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO XHPConvertLookup(3X) .TH XHPKeysymToRoman8 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .SH NAME XHPKeysymToRoman8, XHPRoman8ToKeysym - convert between X KeySyms and HP Roman8 characters .SH SYNTAX \fB .nf int XHPKeysymToRoman8(keysym, r8_return) KeySym keysym; char *r8_return; KeySym XHPRoman8ToKeysym(r8_char) char r8_char; \fR .fi .SH ARGUMENTS .PP .TP 12 .I keysym An X11 KeySym. .PP .TP 12 .I r8_return A pointer to a location to receive the converted Roman 8 character corresponding to \fIkeysym\fP, if any. .PP .TP 12 .I r8_char An HP Roman 8 character. .PP .SH DESCRIPTION .I XHPKeysymToRoman8 takes an X11 KeySym and converts it to an HP Roman 8 character. The character is returned to the location pointed to by \fIr8_return\fP. If no Roman 8 equivalent for \fIkeysym\fR exists, then .I XHPKeysymToRoman8 returns 0 and \fI*r8_return\fP is unchanged. If the conversion succeeds, then .I XHPKeysymToRoman8 returns 1. .PP .I XHPRoman8ToKeysym takes an HP Roman8 character and returns an X11 KeySym. .PP Most of the KeySyms returned by .I XHPRoman8ToKeysym will be in the ISO Latin 1 set and TTY functions . Two of the characters in the Roman 8 set ('S' with caron and 's' with caron) convert to KeySyms in the ISO Latin 2 set. Some KeySyms returned are unique to HP because Roman 8 contains characters that were not encoded in the KeySyms distributed by MIT. .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XLookupKeysym(3X) \fIProgramming With Xlib\fR .fi .TH XHPListInputDevices 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPListInputDevices - List all available X input devices. .SH SYNOPSIS .nf .PP \fB#include \fR .PP \fBtypedef struct { unsigned int resolution; /* resolution in counts/ meter*/ unsigned short min_val; /* min value this axis returns*/ unsigned short max_val; /* max value this axis returns*/ } XHPaxis_info; typedef struct { XID x_id; /* device X identifier */ char *name; /* device name */ XHPaxis_info *axes; /* pointer to axes array */ unsigned short type; /* device type */ unsigned short min_keycode; /* min X keycode from this dev*/ unsigned short max_keycode; /* max X keycode from this dev*/ unsigned char hil_id; /* device HIL identifier */ unsigned char mode; /* ABSOLUTE or RELATIVE */ unsigned char num_axes; /* # axes this device has */ unsigned char num_buttons; /* # buttons on this device */ unsigned char num_keys; /* # keys on this device */ unsigned char io_byte; /* device i/o descriptor byte */ unsigned short detailed_id /* device id detail */ unsigned char pad[6]; /* reserved for future use */ } XHPDeviceList;\fR .PP \fB XHPDeviceList *XHPListInputDevices (display, ndevices) Display *display; int *ndevices; /* RETURN */ \fP .fi .SH ARGUMENTS .PP .TP 12 .I display Specifies the connection to the X server. .TP 12 .I ndevices Specifies the address of a variable into which the server can return the number of input devices available to the X server. .PP .SH DESCRIPTION .PP This request is part of an HP-proprietary extension to X. Its functionality has been superseded by the standard X input device extension \fIXListInputDevices\fP request. You should use \fIXListInputDevices\fP instead of \fIXHPListInputDevices\fP if possible. .PP This request allows a client to determine which devices are available for X input and obtain information about those devices. The X pointer device and X keyboard are listed as well as any extension input devices available to the X server. .PP The X pointer device is listed first. The \fIx_id\fP field in the \fIXHPDeviceList\fP structure corresponding to the X pointer device contains the value \fIXPOINTER\fP. The X keyboard device is listed second. The \fIx_id\fP field in the \fIXHPDeviceList\fP structure corresponding to the X keyboard device contains the value \fIXKEYBOARD\fP. .PP \fIXHPListInputDevices\fR returns an array of \fIXHPDeviceList\fR structures, one for each device available to the X server. The number of entries in the list is returned in the \fIndevices\fR parameter. .PP The device name is a null-terminated string consisting of an ordinal number describing the position of the device, an underscore, and the type of the device. The device position is determined by following the HIL cable from the computer to the device and counting how many devices of that same type there are. The device type is described below. As an example, if a computer was configured with a keyboard and two graphics tablets connected in that order, the device names would be as follows: .nf FIRST_KEYBOARD FIRST_TABLET SECOND_TABLET .fi Client programs may use this name to search for a particular instance of a particular device. .PP The following device types are defined in the file \fB\fR. This file is automatically included when you include \fB\fR. .nf MOUSE TABLET KEYBOARD TOUCHSCREEN TOUCHPAD BUTTONBOX BARCODE ONE_KNOB NINE_KNOB TRACKBALL QUADRATURE ID_MODULE .fi .PP These constants may be compared with the \fItype\fR field of the \fIXHPDeviceList\fR structure to locate a particular type of device. .PP The \fImin_keycode\fR, \fImax_keycode\fR, and \fInum_keys\fR fields are valid only for devices that have keys. They will otherwise be zero. .PP The \fImax_val\fR field of the \fIXHPAxis_info\fR structure contains a value that may be used to scale the input of an absolute pointing device such as a touchscreen or graphics tablet. For each axis of absolute pointing devices, the minimum and maximum values it can generate will be returned. .PP For relative pointing devices, the \fImin_val\fR and \fImax_val\fR fields will contain 0. .PP The \fIio_byte\fR field contains the information from the device I/O Descriptor byte. The 8 bits are interpreted as follows: .PP .TP 12 Bit 7 Set if the device implements the general purpose Prompt and Acknowledge requests. .TP 12 Bits 6, 5, and 4 Indicates specific Prompt/Acknowledges implemented in the device. Zeros indicate that none of the specific Prompt/Acknowledges are implemented. A non-zero value means that Prompt/Acknowledges 1 through that value inclusive are implemented in the device. .TP 12 Bit 3 Set if the device reports Proximity In/Out information. .TP 12 Bits 2, 1, and 0 Indicates which buttons the device reports. Zeros indicate that no buttons are reported. A non-zero value means that buttons 1 through that value are reported by the device. .PP This request returns \fINULL\fR if there are no input devices to list. .SH RETURN VALUE \fIXHPListInputDevices\fP returns an array of XHPDeviceList structures. \fIXHPListInputDevices\fP returns NULL if no input devices are available to the X server. .SH FILES /usr/include/X11/XHPlib.h .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO XHPFreeDeviceList(3x) .TH XHPNlioctl 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPNlioctl \- configure the 16-bit input environment .SH SYNOPSIS \fB #include .br .sp 1 Status XHPNlioctl\^(\^display, status_in_out, command, arg\^) .br Display *display; .br XComposeStatus *status_in_out; .br int command; .br char *arg; \fR .SH DESCRIPTION .TP 15 \fIdisplay\fP Specifies the display .TP 15 \fIstatus_in_out\fP Specifies the .I XComposeStatus structure which this routine, along with .IR XHPConvertLookup , will use to maintain information about this 16-bit input server. .TP 15 \fIcommand\fP specifies the command associated with this call. .TP 15 \fIarg\fP The meaning of arg is dependent upon the value of .IR command . It is not always char *. Check with the documentation for communicating with the nlio process. .PP This routine controls the environment for the 16-bit input server maintained in .IR status_in_out . .PP The contents of .I status_in_out must be zero before its use by either .I XHPConvertLookup or .IR XHPNlioctl . Also, if multiple input servers are running at the same time, they must each be maintained by separate .I XComposeStatus parameters. .PP Upon successful completion, this routine returns 0. If an error has occurred, -1 is returned and errno is set to indicate the error. .PP The following commands are supported by this library. Other control commands may be supported by the NLIO input servers, see the documentation for the NLIO product for details. .TP .B K16_ALT_ON If the current state of the keyboard is in the alternate character set the value of the integer pointed to by .I arg to one, else set the value of the integer pointed to by .I arg to zero. .TP .B K16_EXEC_PROC Exec the 16-bit input server process associated with the keyboard mapping for .IR display . The state information for this server will be maintained in .IR status_in_out . If the server could not be started, -1 is returned and the external variable .I errno will contain the error for the last system call that .I XHPNlioctl called. The value of .I arg is ignored. .TP .B K16_GET_ENCODING Get the encoding of the character to be returned. If the encoding is HP-15, set the value of the integer pointed to by .I arg to zero. If the encoding is EUC, set the value of the integer pointed to by .I arg to one. No error is returned. .TP .B K16_GET_STATEKEYS Get the keysyms for the keys which control state for the Asian keyboards. The keys that are returned are those which control the state of NLIO (invoke/terminate) and those which control the state of the alternate keyboard (set/unset). The current values are returned in the .I K16_state structure. .IP .I NoSymbol is returned for all values for non-Asian keyboards. The default settings for the Asian keyboards are contained in the following table. .sp .TS center box; l s c | c c | c c | c c | c l s c | c c | c c | c c | c l s c | c c | c c | c c | c. Japanese _ set_alternate XK_Meta_R unset_alternate XK_Meta_R invoke_nlio XK_Meta_L terminate_nlio XK_Meta_L _ Katakana _ set_alternate XK_Meta_R unset_alternate XK_Meta_L invoke_nlio NoSymbol terminate_nlio NoSymbol _ Korean, S_Chinese, T_Chinese _ set_alternate NoSymbol unset_alternate NoSymbol invoke_nlio XK_Meta_R terminate_nlio XK_Meta_L .TE .IP A programming example follows. .sp .nf Display *display; XCompose compose; struct K16_state k16state; KeySym invoke_nlio, terminate_nlio; KeySym set_alternate, unset_alternate; XHPNlioctl (display, &compose, K16_GET_STATEKEYS, &k16state); invoke_nlio = k16state.invoke_nlio; terminate_nlio = k16state.terminate_nlio; set_alternate = k16state.set_nlio; unset_alternate = k16state.unset_nlio; .fi .TP .B K16_KILL_PROC Kill the 16-bit input server process which is being maintained in .IR status_in_out . No error is returned. The value of .I arg is ignored. .TP .B K16_NLIO_ON If the 16-bit input server is currently receiving characters, set the value of the integer pointed to by .I arg to one, else set the value of the integer pointed to by .I arg to zero. .TP .B K16_SET_ENCODING Set the encoding of the character to be returned. If the value of the integer pointed to by .I arg is zero, the encoding becomes HP-15. If the value of the integer pointed to by .I arg is one, the encoding becomes EUC. No error is returned. .TP .B K16_SET_STATEKEYS Set the keys which control state for the Asian keyboards. The keys that can be set are those which control the state of NLIO (invoke/terminate) and those which control the state of the alternate keyboard (set/unset). The keys are set by setting the proper flag and by specifying the keysym which controls a particular state in the .I K16_state structure. .IP If the keysyms that set and unset a state are the same, then that key will be a toggle key. If both keysyms are set to .I NoSymbol then that functionality is effectively disabled. Note: no checking is made for the existence of keysyms on the current keyboard. Functionality can be enabled and disabled by the use of .IR XChangeKeyboardMapping . .IP If the current keyboard mapping for .I display is that for a non-Asian keyboard the error XHPINP_INVAL is returned. If the current keyboard is other than Japanese or Katakana and .I flags has K16_ALTSTATE set, -1 is returned and errno is set to EINVAL. If the current keyboard mapping is Katakana and .I flags has K16_NLIOSTATE set, -1 is returned and errno is set to EINVAL. .IP A programming example follows. .sp .nf Display *display; XCompose compose; struct K16_state k16state; KeySym invoke_nlio, terminate_nlio; KeySym set_alternate unset_alternate k16state.flags = K16_NLIOSTATE | K16_ALTSTATE; k16state.invoke_nlio = invoke_nlio; k16state.terminate_nlio = terminate_nlio; k16state.set_alternate = set_alternate; k16state.unset_alternate = unset_alternate; XHPNlioctl (display, &compose, K16_SET_STATEKEYS, &k16state); .fi .SH ERRORS .I XHPNlioctl will fail if: .TP 15 .SM [EACCES] The user is trying to exec the input server and does not have execute permission for the input server. .TP 15 .SM [EAGAIN] The user is trying to fork the input server and a system imposed limit for the number of processes would be exceeded. .TP 15 .SM [EINVAL] An invalid parameter was passed to the routine. .TP 15 .SM [EIO] An error occurred in communicating with the input server. .TP 15 .SM [EMFILE] The user is trying to start up the input server and the maximum number of file descriptors is currently open. .TP 15 .SM [ENOENT] The user is trying to exec the input server and the file does not exist. .SH ORIGIN Hewlett-Packard Company .SH "SEE ALSO" XGetKeyboardMapping(3X), XHPConvertLookup(3X), XHPInputChinese_s(3X), XHPInputChinese_t(3X), XHPInputJapanese(3X), XHPInputKorean(3X), XHPSetKeyboardMapping(3X) .TH XHPPrompt 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPPrompt - Send a prompt to an extended input device. .SH SYNOPSIS .nf \fB #include .sp int XHPPrompt (display, deviceid, prompt) Display *display; XID deviceid; unsigned int prompt; \fP .fi .SH ARGUMENTS .PP .TP 12 .I display Specifies the connection to the X server. .TP 12 .I deviceid Specifies the ID of the desired device. .TP 12 .I Prompt Specifies the Prompt to be sent. Valid values are: \fIGENERAL_PROMPT\fR, \fIPROMPT_1\fR, \fIPROMPT_2\fR, \fIPROMPT_3\fR, \fIPROMPT_4\fR, \fIPROMPT_5\fR, \fIPROMPT_6\fR, \fIPROMPT_7\fR. .PP .SH DESCRIPTION .PP This request is part of an HP-proprietary extension to X. Its functionality has been superseded by the standard X input device extension \fIXChangeFeedbackControl\fP request. You should use \fIXChangeFeedbackControl\fP instead of \fIXHPPrompt\fP if possible. .PP This request sends a prompt to an input device. .PP A prompt is an audio or visual indication that the program controlling the input device is ready for input. The program may indicate that status by turning on a prompt on the appropriate input device. .PP Not all input devices support prompts and acknowledges. Any device that does support a particular prompt will also support the corresponding acknowledge. .PP To determine whether an input device supports a particular prompt and acknowledge, the \fIio_byte\fP field of the \fIXHPDeviceList\fP structure should be examined. The format of this structure is described in the documentation for the \fIXHPListInputDevices\fP request. .SH RETURN VALUE none .SH DIAGNOSTICS .TP 12 .I BadDevice An invalid device ID was specified. .TP 12 .I BadValue An invalid prompt was specified. .SH FILES /usr/include/X11/XHPlib.h .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XHPListInputDevices(3x) XHPAcknowledge(3x) .fi .TH XHPSSChangeNotify 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1995 .na .nh .SH NAME XHPSSChangeNotify - Allows applications to receive notification of screen saver state changes. .PP .SH SYNOPSIS .br \fB#include .nf int XHPSSChangeNotify (display, ssHandle, flags) Display *display; Atom *ssHandle; int flags; \fP .fi .SH ARGUMENTS .PP .TP 25 .I display Specifies the connection to the X server. .TP 25 .I ssHandle Specifies a pointer to an atom, into which the X server will return a unique identifying screen saver id. .TP 25 .I flags Specifies the bit mask that indicates the type of notifications the application wants to receive. The first bit (bit 0) determines screen saver 'on' and 'off' states. The second bit (bit 1) indicates the 'draw' and 'cycle' notification. .PP .SH DESCRIPTION These requests are part of an HP-proprietary extension to X. These requests allow one or more X clients to react to screen saver state changes, such as locking the screen when the screen blanks or drawing patterns on the screen. To receive 'on' and 'off' messages, the application only needs to call \fIXHPSSChangeNotify\fP(). To also receive 'draw' and 'cycle' messages, the application needs to call \fIXSetScreenSaver\fP() as well as \fIXHPSSChangeNotify\fP(). To enable the screen saver, applications must first call \fIXSetScreenSaver\fP() and set the prefer_blanking to DontPreferBlanking. The X server will not generate 'draw' and 'cycle' notification when blanking is turned on. The allow_exposures flag must be set to AllowExposures. This ensures that proper notification will be sent out when it is safe to do drawing. This can also be done with "xset s noblank s expose". .PP To begin receiving information on screen saver state changes, applications must use the \fIXHPSSChangeNotify\fP() function. Depending on how the flags have been set, the screen saver program can receive notification of the following event_types: .PP .TP 12 .I XHP_SCREEN_SAVER_ON: The screen saver timeout has initially expired. This is typically visually indicated by the screen blanking. .TP 12 .I XHP_SCREEN_SAVER_OFF: The screen saver has been reset, due to user input or mouse movement. .TP 12 .I XHP_SCREEN_SAVER_DRAW: The screen saver program can now draw into the screen saver window; the window id is supplied as part of the notification. .TP 12 .I XHP_SCREEN_SAVER_CYCLE: The cycle timeout has expired; this allows a screen saver program to modify (or animate) what it is displaying in the screen saver window. .PP Caveat: Even if you enable bit 1, thus requesting 'draw' and 'cycle' notification, you will only receive these *if* you had disabled blanking, using the calls described earlier! .PP Once you have registered interest in screen saver notification, you will receive X events whose 'type' is set to 'ClientMessage', and whose message type is the atom passed back by XHPSSChangeNotify(). 'message-type' is set to the atom returned in the 'ssHandle' parameter. For instance, the following event loop would detect and dispatch screen saver events: .PP .DS XEvent event; for (;;) { XNextEvent (display &event); if ((event.type == ClientMessage) && (event.xclient.message_type == ssHandle)) { /* add code to dispatch screen saver event */ } } .DE .PP In the case of the XHP_SCREEN_SAVER_DRAW notification, you will also receive the window id for the screen saver window. This window id is specified within the event.xclient.data.l[1] field and the event type is specified within event.xclient.data.l[0] field: .DS XClientMesssageEvent * message = (XClientMessageEvent *) &event; event_type = message->data.l[0]; window = message->data.l[1]; .DE .SH EXAMPLES This is a sequence of notification event_types a screen saver application might see: .DS Bit 1 off, or blanking enabled: ------------------------------- XHP_SCREEN_SAVER_ON (When screen saver timeout expires) XHP_SCREEN_SAVER_OFF (When input occurs or mouse is moved) Bit 1 on, and blanking disabled: -------------------------------- XHP_SCREEN_SAVER_ON (When screen saver timeout expires) XHP_SCREEN_SAVER_DRAW (When it is safe to draw in the specified window id) XHP_SCREEN_SAVER_CYCLE (When screen saver cycle timeout expires) . . . XHP_SCREEN_SAVER_CYCLE (When screen saver cycle timeout expires) XHP_SCREEN_SAVER_OFF (When input occurs or mouse is moved) .DE .PP In the case that there are more than one screen attached to the X server, applications will receive screen saver events for each screen, even screens that are not visible. Care should be taken to avoid rendering to a window using the wrong screen. To determine the screen, use the following: .PP .DS XGetWindowAttributes(display, event, window, &attr); screenNum = XScreenNumberOfScreen(attr.screen); .DE .PP \fB CAUTION: \fP An X error handler should be registered to catch attempts to draw to a non-existent window. The screen saver window is a special window that is created and destroyed by the X Server. It is possible, in the case that a short timeout is defined, that the client may issue draw requests to a window that has been destroyed before it completes all of its requests. If an error handler is not supplied, the application will most likely terminate. .SH RETURN VALUE This function returns 0 upon successful completion, -1 when the X Server is too old to support Screen Saver calls and 1 when too many screen saver clients have already registered. There can be a maximum of 10 registered screen saver clients. .SH FILES none .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XSetScreenSaver(3x) xset(1) .fi .TH XHPSelectExtensionEvent 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPSelectExtensionEvent - Select an extension event. .SH SYNOPSIS .nf \fB int XHPSelectExtensionEvent (display, window, deviceid, mask) Display *display; Window window; XID deviceid; Mask mask; \fP .fi .SH ARGUMENTS .PP .TP 12 .I display Specifies the connection to the X server. .TP 12 .I window Specifies the window from which input is desired. .TP 12 .I deviceid Specifies the device from which input is desired. .TP 12 .I mask Specifies the mask of input events that are desired. .PP .SH DESCRIPTION .PP These requests are part of an HP-proprietary extension to X. Its functionality has been superseded by the standard X input device extension \fIXSelectExtensionEvent\fP request. You should use \fIXSelectExtensionEvent\fP instead of \fIXHPSelectExtensionEvent\fP if possible. .PP This request is provided to support the use of input devices other than the X keyboard and X pointer device. It allows input from other input devices to be selected independently from that coming from the X pointer and keyboard. .PP \fIXHPSelectExtensionEvent\fR requests the server to send an extended event that matches the specified event mask and comes from the specified device and window. In order to use this request, the client program must first determine the appropriate \fIdeviceid\fP by using the \fIXHPListInputDevice\fR request, and the appropriate event mask by using the \fIXHPGetExtEventMask\fR request. Multiple event masks returned by \fIXHPGetExtEventMask\fR may be OR'd together and specified in a single request to \fIXHPSelectExtensionEvent\fR. .PP This request cannot be used to select any of the core X events, or to receive input from the X Keyboard or X pointer device. The core \fIXSelectInput\fR request should be used for that purpose. .SH DIAGNOSTICS .PP .TP 12 .I BadDevice An invalid device ID was specified. .TP 12 .I BadWindow An invalid window ID was specified. .SH RETURN VALUE none .SH FILES none .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XHPListInputDevices(3x) XHPGetExtEventMask(3x) XSelectInput(3x) .fi .TH XHPSetDeviceFocus 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPSetDeviceFocus - Set the focus for an extended input device. .PP XHPSetDeviceModifierMapping - Change the modifier mapping of an extension input device. .SH SYNOPSIS .nf \fB int XHPSetDeviceFocus (display, deviceid, focus, revert_to, time) Display *display; XID deviceid; Window focus; int revert_to; Time time; int XHPSetDeviceModifierMapping (display, deviceid, modmap) Display *display; XID deviceid; XModifierKeymap *modmap; \fP .fi .SH ARGUMENTS .PP .TP 12 .I display Specifies the connection to the X server. .TP 12 .I deviceid Specifies the ID of the desired device. .SH XHPSetDeviceFocus Only .TP 12 .I focus Specifies the ID of the window to which the device's focus should be set. This may be a window ID, or either .I PointerRoot or .I None. .TP 12 .I revert_to Specifies to which window the focus of the device should revert if the focus window becomes not viewable. One of the following constants may be passed: .I RevertToParent, .I RevertToPointerRoot, or .I RevertToNone. .TP 12 .I time Specifies the time. You can pass either a timestamp, expressed in milliseconds, or .I CurrentTime. .SH XHPSetDeviceModifierMapping Only .TP 12 .I modmap Specifies a pointer to an XModifierKeymap structure. .SH DESCRIPTION .PP These requests are part of an HP-proprietary extension to X. Their functionality has been superseded by standard X input device extension requests. You should use \fIXSetDeviceFocus\fP instead of \fIXHPSetDeviceFocus\fP and \fIXSetDeviceModifierMapping\fP instead of \fIXHPSetDeviceModifierMapping\fP if possible. .PP These requests are provided to support the use of input devices other than the X keyboard device and X pointer device. .SH XHPSetDeviceFocus \fIXHPSetDeviceFocus\fR allows a client to redirect the focus for a particular extended input device. This request causes an \fIHPDeviceFocusOut\fR event to be sent to the window losing the device focus, and an \fIHPDeviceFocusIn\fR event to be sent to the window gaining the device focus. .PP This request may not be used to set the focus of the X keyboard device. The \fIXSetInputFocus\fR request should be used for that purpose. .SH XHPSetDeviceModifierMapping This request is provided to support the use of input devices other than the X keyboard and X pointer device. It allows a client program to define the keycodes that are to be used as modifiers for an extension device. .PP The \fIXHPSetDeviceModifierMapping\fP request specifies the KeyCodes of the keys, if any, that are to be used as modifiers for the specified input device. X permits at most eight modifier keys. If more than eight are specified in the \fIXModifierKeymap\fP structure, a \fIBadLength\fP error will be generated. .PP There are eight modifiers, and the modifiermap member of the \fIXModifierKeymap\fP structure contains eight sets of max_keypermod KeyCodes, one for each modifier in the order \fIShift\fP, \fILock\fP, \fIControl\fP, \fIMod1\fP, \fIMod2\fP, \fIMod3\fP, \fIMod4\fP, and \fIMod5\fP. Only nonzero KeyCodes have meaning in each set, and zero KeyCodes are ignored. In addition, all of the nonzero KeyCodes must be in the range specified by min_keycode and max_keycode as returned by the \fIXHPListInputDevices\fP request. Otherwise, a \fIBadValue\fP error is generated. No KeyCode may appear twice in the entire map. Otherwise, a \fIBadValue\fP error will be generated. .PP A X server can impose restrictions on how modifiers can be changed, for example, if certain keys do not generate up transitions in hardware or if multiple modifier keys are not supported. If some such restriction is violated, the status reply is \fIMappingFailed\fP, and none of the modifiers are changed. If the new KeyCodes specified for a modifier differ from those currently defined and any (current or new) keys for that modifier are in the logically down state, the status reply is \fIMappingBusy\fP, and none of the modifiers are changed. \fIXHPSetDeviceModifierMapping\fP generates a \fIMappingNotify\fP event when it returns \fIMappingSuccess\fP. .PP .SH DIAGNOSTICS \fIXHPSetDeviceFocus\fP can generate \fIBadMatch\fP, \fIBadWindow\fP, and \fIBadDevice\fP errors. .PP \fIXHPSetDeviceModifierMapping\fP can generate \fIBadDevice\fP, \fIBadLength\fP, and \fIBadValue\fP errors. .TP 12 .I BadMatch The focus window was not viewable. .TP 12 .I BadWindow An invalid window ID was specified. .TP 12 .I BadDevice The specified device does not exist, was not previously enabled via \fIXHPSetInputDevice\fP, or is the X system pointer or X system keyboard. .TP 12 .I BadLength More than 8 modifier keys were specified. .TP 12 .I BadValue One of the values specified was beyond the range of valid values. .PP .SH RETURN VALUE none .SH FILES none .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XHPListInputDevices(3x) XHPSetInputDevice(3x) XHPGetDeviceFocus(3x) XHPGetDeviceModifierMapping(3x) XGetModifierMapping(3x) XSetModifierMapping(3x) .fi .TH XHPSetErrorHandler 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPSetErrorHandler - Register an X error handling routine. .SH SYNOPSIS .nf \fB #include typedef int (*PFI) (); PFI XHPSetErrorHandler (display, routine) Display *display; int (*routine) (); int routine (display, error) Display *display; XErrorEvent *error; .fi \fR .SH DESCRIPTION .PP This request registers with Xlib the address of a routine to handle X errors. It is intended to be used by libraries and drivers that wish to establish an error handling routine without interfering with any error handling routine that may have been established by the client program. .PP \fIXHPSetErrorHandler\fP records one error handling routine per connection to the server. Therefore, in order for a library or driver to set up its own error handling routine without affecting that of the client, the library or driver must first have established its own connection to the server via XOpenDisplay. .PP When an XErrorEvent is received by the client, which error handling routine is invoked is determined by the display associated with the error. If the display matches that associated with a driver error handling routine, that error handling routine will be invoked. If it does not match any driver routine, the error handling routine established by the client, if any exists, will be invoked. Otherwise, the default Xlib error handler will be invoked. .PP \fIXHPSetErrorHandler\fP returns the address of the previously established error handler. If that error handler was the default error handler, NULL is returned. .PP A driver or library may remove its error handler by invoking \fIXHPSetErrorHandler\fP with a NULL error handling routine. .SH FILES /usr/include/X11/XHPlib.h .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XSetErrorHandler(3x) .fi .TH XHPSetInputDevice 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPSetInputDevice - Open a device for X input. .SH SYNOPSIS .nf \fB #include int XHPSetInputDevice (display, deviceid, mode) Display *display; XID deviceid; int mode; \fP .fi .SH ARGUMENTS .PP .TP 12 .I display Specifies the connection to the X server. .TP 12 .I deviceid Specifies the ID of the desired device. .TP 12 .I mode Specifies the desired mode of access. .PP .SH DESCRIPTION .PP This request is part of an HP-proprietary extension to X. Its functionality has been superseded by the standard X input device extension \fIXOpenDevice\fP request. You should use \fIXOpenDevice\fP instead of \fIXHPSetInputDevice\fP if possible. .PP This request is provided to support input devices other than the X keyboard device and the X pointer device. .PP Client programs use the \fIXHPSetInputDevice\fR to open an input device for extended input and to close the device. \fIXHPSetInputDevice\fR requires a mode parameter that specifies the request being requested (\fION\fR or \fIOFF\fR) and, if the request is \fION\fR, whether the device should be opened as an extension to the X keyboard or pointer (\fISYSTEM_EVENTS\fR), or as an independently selectable device (\fIDEVICE_EVENTS\fR). The value of the mode parameter is set by ORing together the above constants, which may be obtained by including the file \fB\fR. .PP To open an input device as a device whose input can be selected independent of the X keyboard and X pointer, the client program would use the mode \fION\fR OR'd with the mode \fIDEVICE_EVENTS\fR. To open an input device as an extension of the X keyboard or X pointer, the client program would use the mode \fION\fR or'd with the mode \fISYSTEM_EVENTS\fR. Valid values for the mode parameter are: .nf ON | SYSTEM_EVENTS ON | DEVICE_EVENTS OFF .fi .PP This request will fail with a BadMode error if some other client is already using the device with a different mode. .SH DIAGNOSTICS .TP 12 .I BadMode An invalid mode was specified. .TP 12 .I BadDevice An invalid device ID was specified. .SH RETURN VALUE none .SH FILES /usr/include/X11/XHPlib.h .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XHPListInputDevices(3x) XHPGetExtEventMask(3x) XHPSelectExtensionEvent(3x) .fi .TH XHPSetKeyboardMapping 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPSetKeyboardMapping, XHPRefreshKeyboardMapping \- set/refresh the keyboard mapping .SH SYNOPSIS .br \fB#include .sp 1 Status XHPSetKeyboardMapping(display, kbd_id, force_read) .br Display *display; .br KEYBOARD_ID kbd_id; .br int force_read; .sp 1 XHPRefreshKeyboardMapping(event_map) .br XMappingEvent *event_map; .sp 1 XHPSetKbdMapInit(display, kbd_id, force_read, status_in_out) .br Display *display; .br KEYBOARD_ID kbd_id; .br int force_read; .br XComposeStatus *status_in_out;\fR .sp 1 .SH DESCRIPTION \fIXHPSetKeyboardMapping\fR allows an application to emulate other keyboards. It does this by replacing the key map associated with .IR display . The keyboard to be emulated is specified by .IR kbd_id . .P The routines described on this man page are provided for backwards compatibility only; they will be discontinued in a future release of HP-UX. \fIXHPSetKeyboardMapping\fR and \fIXHPSetKbdMapInit\fR can only manipulate the keymaps of HP keyboards connected via the HIL interface. The system cannot distinguish between an HP DIN keyboard and DIN keyboards from another source, and hence cannot safely remap these keyboards. .P \fIXHPSetKeyboardMapping\fR reads the key map from the file \fI/etc/X11/XHPKeymaps .\fR However, if the keyboard specified with \fIkbd_id\fR is the same as the physical keyboard recognized by the server as the input device, \fIXHPSetKeyboardMapping\fR requests the key map directly from the server. In this way, any changes to the key map (such as with \fIXChangeKeyboardMapping\fR) are preserved. This functionality can be overridden by setting \fIforce_read\fR to a non-NULL value; if the value of \fIforce_read\fR is non-NULL, \fIXHPSetKeyboardMapping\fR will always obtain the key map from the file \fI/etc/X11/XHPKeymaps .\fR .P .I XHPSetKeyboardMapping fails if .I kbd_id is an unrecognized value or if it cannot open the key map file; the \fIdisplay\fR's copy of the key map is not modified. .P If the server's keyboard is a non-HP keyboard or is connected to the workstation by an interface other than HIL, \fIXHPSetKeyboardMapping\fR returns an error code and does not modify the key map. .P .I XHPSetKbdMapInit is a macro defined in .BR XHPlib.h . It is intended for clients using .I XHPGetEurasianCvt and will perform the necessary initialization and cleanup for that routine, as well as setting the key map for .IR display . .P The following values for \fIkbd_id\fR are define in <\fBX11/HXPlib.h\fR>: .sp 1 .TP 21 KB_US_English specifies an HP46021A US ASCII keyboard .TP 21 KB_Canada_French specifies an HP46021AC Canadian French keyboard .TP 21 KB_German specifies an HP46021AD German keyboard .TP 21 KB_Euro_Spanish specifies an HP46021AE European Spanish keyboard .TP 21 KB_French specifies an HP46021AF French keyboard .TP 21 KB_Dutch specifies an HP46021AH Dutch keyboard .TP 21 KB_Katakana specifies an HP46021AJ Katakana keyboard .TP 21 KB_Canada_English specifies an HP46021AL Canadian English keyboard .TP 21 KB_Latin_Spanish specifies an HP46021AM Latin American Spanish keyboard .TP 21 KB_Norwegian specifies an HP46021AN Norwegian keyboard .TP 21 KB_Swiss_German2 specifies an HP46021AP Swiss German keyboard .TP 21 KB_Swiss_German specifies an HP46020 Swiss German keyboard .TP 21 KB_Swiss_French2 specifies an HP46021AQ Swiss French keyboard .TP 21 KB_Swiss_French specifies an HP46020 Swiss French keyboard .TP 21 KB_Swedish specifies an HP46021AS Swedish keyboard .TP 21 KB_UK_English specifies an HP46021AU UK English keyboard .TP 21 KB_Belgian specifies an HP46021AW Belgian keyboard .TP 21 KB_Finnish specifies an HP46021AX Finnish keyboard .TP 21 KB_Danish specifies an HP46021AY Danish keyboard .TP 21 KB_Italian specifies an HP46021AZ Italian keyboard .TP 21 KB_T_Chinese specifies an HP46021AW#ZAA Traditional Chinese keyboard .TP 21 KB_Korean specifies an HP46021AW#ZAB Korean keyboard .TP 21 KB_S_Chinese specifies an HP46021AW#ZAC Simplified Chinese keyboard .TP 21 KB_Japanese specifies an HP46021AW#ZAL Japanese keyboard .sp 2 .P \fIXHPRefreshKeyboardMapping\fR refreshes \fIdisplay\fR's copy of the key map and modifier information. It facilitates handling MappingNotify events when using \fIXHPSetKeyboardMapping\fR with the \fIforce_read\fR argument set to NULL (i.e. when the key map for the keyboard is read from the server and not from the \fIXHPKeymaps\fR file). .P If the key map has been read from \fIXHPKeymaps\fR, changes to the server's key map are irrelevant; MappingNotify events should be ignored when using \fIXHPSetKeyboardMapping\fR with \fIforce_read\fR set to a non-NULL value. .SH RETURN VALUE .I XHPSetKeyboardMapping returns zero if it succeeds, otherwise it returns one of the following values, defined in <\fBX11/HXPlib.h\fR>: .sp 1 .TP 28 XHPKB_NOKEYFILE The file \fI/etc/X11/XHPKeymaps\fR does not exist or could not be opened. .TP 28 XHPKB_BADMAGIC Either \fIlibxHP11.a\fR or \fI/etc/X11/XHPKeymaps\fR is not the latest version. .TP 28 XHPKB_BADKBID The \fIkbd_id\fR argument is set to an improper value. .TP 28 XHPKB_NONHPINPUTDEV The keyboard attached to the server is not an HP keyboard. The key map requested was not loaded. .sp 2 .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO XHPConvertLookup(3X), XHPGetEurasianCvt(3X) .TH XHPUngrabDevice 3X "Release 5" "X Version 11" .ds )H Hewlett-Packard Company .ds ]W HP-UX 9.0 August 1992 .na .nh .SH NAME XHPUngrabDevice - Release a grab of an extension input device. .PP XHPUngrabDeviceButton - Release a passive grab of a button on an extension input device. .PP XHPUngrabDeviceKey - Release a passive grab of a key on an extension input device. .SH SYNOPSIS .nf \fB int XHPUngrabDevice (display, deviceid, time) Display *display; XID deviceid; Time time; int XHPUngrabDeviceButton (display, deviceid, button, modifiers, ungrab_window) Display *display; XID deviceid; unsigned int button; unsigned int modifiers; Window ungrab_window; int XHPUngrabDeviceKey (display, deviceid, keycode, modifiers, ungrab_window) Display *display; XID deviceid; unsigned int keycode; unsigned int modifiers; Window ungrab_window; .fi \fP .SH ARGUMENTS .PP .TP 15 .I display Specifies the connection to the X server. .TP 15 .I deviceid Specifies the ID of a previously grabbed device. .SH XHPUngrabDevice .PP .TP 15 .I time Specifies a timestamp, or .I CurrentTime. .SH XHPUngrabDeviceButton .PP .TP 15 .I button Specifies the code of the button that is to be ungrabbed. You can pass either a button or \fIAnyButton\fR. .SH XHPUngrabDeviceKey .PP .TP 15 .I keycode Specifies the keycode of the key that is to be ungrabbed. You can pass either the keycode or \fIAnyKey\fR. .SH XHPUngrabDeviceButton and XHPUngrabDeviceKey Only .PP .TP 15 .I modifiers Specifies the set of keymasks. This mask is the bitwise inclusive OR of these keymask bits: \fIShiftMask\fR, \fILockMask\fR, \fIControlMask\fR, \fIMod1Mask\fR, \fIMod2Mask\fR, \fIMod3Mask\fR, \fIMod4Mask\fR, \fIMod5Mask\fR. .PP You can also pass AnyModifier, which is equivalent to issuing the ungrab key request for all possible modifier combinations (including the combination of no modifiers). .TP 15 .I ungrab_window Specifies the ID of a window associated with the device specified above. .SH DESCRIPTION .PP These requests are part of an HP-proprietary extension to X. Their functionality has been superseded by standard X input device extension requests. You should use \fIXUngrabDevice\fP instead of \fIXHPUngrabDevice\fP, \fIXUngrabDeviceButton\fP instead of \fIXHPUngrabDeviceButton\fP and \fIXUngrabDeviceKey\fP instead of \fIXHPUngrabDeviceKey\fP if possible. .PP These requests are provided to support the use of input devices other than the X keyboard and X pointer device. They allow a client to release a grab of an extended input device, or a button or key on such a device. That grab must have previously been established using the corresponding grab request. .SH XHPUngrabDevice .PP \fIXHPUngrabDevice\fP does not release the grab if the specified time is earlier than the last-device-grab time or is later than the current X server time. It also generates DeviceFocusIn and DeviceFocusOut events. The X server automatically performs an \fIXHPUngrabDevice\fP if the event window for an active device grab becomes not viewable. .PP \fIXHPUngrabDevice\fP cannot be used to release a grab of the X pointer device or the X keyboard device. The core \fIXUngrabPointer\fR and \fIXUngrabKeyboard\fR requests should be used for that purpose. .SH XHPUngrabDeviceButton .PP The \fIXHPUngrabDeviceButton\fR request removes a passive grab of a button on an extension device. A modifier of \fIAnyModifier\fP is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). \fIXHPUngrabDeviceButton\fP can generate \fIBadDevice\fR and \fIBadWindow\fR errors. .PP \fIXHPUngrabDeviceButton\fP cannot be used to ungrab a button on the X pointer device. The core \fIXUngrabButton\fR request should be used for that purpose. .SH XHPUngrabDeviceKey .PP The \fIXHPUngrabDeviceKey\fR request removes a passive grab of a key on an extension device. A modifier of \fIAnyModifier\fP is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). \fIXHPUngrabDeviceKey\fR can generate \fIBadDevice\fR and \fIBadWindow\fR errors. .PP \fIXHPUngrabDeviceKey\fP cannot be used to ungrab a key on the X keyboard device. The core \fIXUngrabKey\fR request should be used for that purpose. .SH DIAGNOSTICS .PP .TP 12 .I BadDevice An invalid device ID was specified. .TP 12 .I BadWindow An invalid window ID was specified. .PP .SH RETURN VALUE none .SH FILES none .SH ORIGIN Hewlett-Packard Company .SH SEE ALSO .nf XHPListInputDevices(3x) XHPSetInputDevice(3x) XHPGrabDevice(3x) XHPGrabDeviceButton(3x) XHPGrabDeviceKey(3x) XUngrabKeyboard(3x) XUngrabPointer(3x) XUngrabButton(3x) XUngrabKey(3x) .fi .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XHeightOfScreen" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XHeightOfScreen, XHeightMMOfScreen, HeightOfScreen, HeightMMOfScreen \(en get height of screen in pixels or millimeters .XX "XHeightOfScreen" .XX "XHeightMMOfScreen" .Nz .\" .\" .SH "Synopsis" .Sy int XHeightOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .Sy int XHeightMMOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIscreen\fP 1i Specifies the appropriate \f(CWScreen\fP structure. .\" .\" .SH Returns Height in pixels or millimeters. .SH Description .XX "screens:height" \f(CWXHeightOfScreen()\fP returns the height of the specified screen in pixels. \f(CWXHeightMMOfScreen()\fP returns the height of the specified screen in millimeters. .LP .XX "HeightOfScreen macro" .XX "HeightMMOfScreen macro" The C language macros \f(CWHeightOfScreen()\fP and \f(CWHeightMMOfScreen()\fP are equivalent and slightly more efficient. .LP These functions are equivalent to \f(CWXDisplayHeight*()\fP and \f(CWXDisplayHeightMM()\fP except that they take different arguments. .\" .\" .SH "See Also" \s-1\fIXDisplayHeight*()\fP\s+1, \s-1\fIXDisplayHeightMM()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XIMOfIC" "Xlib - Input Contexts" .ds ]W Xlib Reference Manual .XX "XIMOfIC" .XX "input contexts:getting input method of" .XX "input methods:of input contexts" .SH Name .Na XIMOfIC \- obtain the input method of an input context. .Nz .SH Synopsis .Sy XIM XIMOfIC\^(\^\f(CIic\fP\^) .As XIC \f(CIic\fP\^; .Ae .SH Arguments .IP \f(CIic\fP 1i Specifies the input context. .SH Returns The input method. .SH Availability Release 5 and later. .SH Description \f(CWXIMOfIC()\fP returns the input method associated with a given input context. .SH "See Also" \s-1\fIXSetICFocus()\fP\s+1, \s-1\fIXSetICValues()\fP\s+1, \s-1\fIXCreateIC()\fP\s+1, \s-1\fIXDestroyIC()\fP\s+1, \s-1\fIXmbResetIC()\fP\s+1, \s-1\fIXwcResetIC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XIconifyWindow" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XIconifyWindow" .XX "iconifying windows" .XX "windows:iconifying" .Na XIconifyWindow \(en request that a top-level window be iconified. .Nz .SH "Synopsis" .Sy Status XIconifyWindow\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; int \f(CIscreen_number\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/IconifyWindow 2.6 1993/05/28 13:29:13 stephen Exp $ .IP \f(CIw\fP 1i Specifies the window. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number on the server. .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description .LP \f(CWXIconifyWindow()\fR sends a \s-1WM_CHANGE_STATE\s0 \f(CWClientMessage\fR event with a format of 32 and a first data element of \f(CWIconicState\fR (as described in Section 4.1.4 of the \fIInter-Client Communication Conventions Manual\fP in Volume Zero, \fIX Protocol Reference Manual\fP), to the root window of the specified screen. Window managers may elect to receive this message and, if the window is in its normal state, may treat it as a request to change the window's state from normal to iconic. If the \s-1WM_CHANGE_STATE\s0 property cannot be interned, \f(CWXIconifyWindow()\fR does not send a message and returns a zero status. It returns a non-zero status if the client message is sent successfully; otherwise, it returns a zero status. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Errors" \f(CWBadWindow\fR .SH "See Also" \s-1\fIXReconfigureWindow\fP\s+1, \s-1\fIXWithdrawWindow()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XIfEvent" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XIfEvent" .XX "events:matching, waiting for" .XX "predicate procedures:waiting for event matched in" .Na XIfEvent \(en wait for event matched in predicate procedure. .Nz .SH "Synopsis" .Sy XIfEvent\^(\^\f(CIdisplay\f(CW, \f(CIevent_return\f(CW, \f(CIpredicate\f(CW, \f(CIargs\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XEvent *\f(CIevent_return\f(CW\^; Bool (\^*\f(CIpredicate\f(CW\^)\^(\^)\^; char *\f(CIargs\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIevent_return\fP 1i Returns the matched event. .IP \f(CIpredicate\fP 1i Specifies the procedure to be called to determine if the next event satisfies your criteria. .IP \f(CIargs\fP 1i Specifies the user-specified arguments to be passed to the predicate procedure. .SH Description \f(CWXIfEvent()\fP checks the event queue for events, uses the user-supplied routine to check if one meets certain criteria, and removes the matching event from the input queue. \f(CWXIfEvent()\fP returns only when the specified predicate procedure returns \f(CWTrue\fP for an event. The specified predicate is called once for each event on the queue until a match is made, and each time an event is added to the queue, with the arguments \&\f(CIdisplay\fP, \&\f(CIevent_return\fP, and \&\f(CIarg\fP. .LP If no matching events exist on the queue, \f(CWXIfEvent()\fR flushes the request buffer and waits for an appropriate event to arrive. Use \f(CWXCheckIfEvent()\fP if you don't want to wait for an event. .LP For more information, see Volume One, Chapter 8, \fIEvents\fR. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XImageByteOrder" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XImageByteOrder, ImageByteOrder \(en get server's byte order. .XX "XImageByteOrder" .Nz .\" .\" .SH "Synopsis" .Sy int XImageByteOrder\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" .\" .SH Returns \f(CWLSBFirst\fP or \f(CWMSBFirst\fP. .SH Description .XX "images:specifying byte order for" \f(CWXImageByteOrder()\fP specifies the required byte order for images for each scanline unit in XY format (bitmap) or for each pixel value in Z format. It can return either \f(CWLSBFirst\fP or \f(CWMSBFirst\fP. .LP .XX "ImageByteOrder macro" The C language macro \f(CWImageByteOrder()\fP is equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXGetImage()\fP\s+1, \s-1\fIXPutImage()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XInsertModifiermapEntry" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XInsertModifiermapEntry" .Na XInsertModifiermapEntry \(en add a new entry to an \f(CWXModifierKeymap\fR structure. .Nz .SH "Synopsis" .Sy XModifierKeymap *XInsertModifiermapEntry\^(\^\f(CImodmap\fP, .ti +10n \f(CIkeycode_entry\fP, \f(CImodifier\fP\^) .As XModifierKeymap *\f(CImodmap\fP\^; KeyCode \f(CIkeycode_entry\fP\^; int \f(CImodifier\fP\^; .SH "Arguments" .IP \f(CImodmap\fP 1i Specifies a pointer to an \f(CWXModifierKeymap()\fP structure. .IP \f(CIkeycode_entry\fP 1i Specifies the keycode of the key to be added to \f(CImodmap\fP. .IP \f(CImodifier\fP 1i Specifies the modifier you want mapped to the keycode specified in \f(CIkeycode_entry\fP. This should be one of the constants: \f(CWShift\%Map\%Index\fP, \f(CWLock\%Map\%Index\fP, \f(CWControl\%Map\%Index\fP, \f(CWMod1\%Map\%Index\fR, \f(CWMod2\%Map\%Index\fR, \f(CWMod3\%Map\%Index\fR, \f(CWMod4\%Map\%Index\fR, or \f(CWMod5\%Map\%Index\fR. .SH Returns The modifier map structure with the keycode added. .SH Description \f(CWXInsertModifiermapEntry()\fP returns an \f(CWXModifierKeymap\fP structure suitable for calling \f(CWXSetModifierMapping()\fR, in which the specified keycode is added to the set of keycodes that is mapped to the specified modifier (like Shift or Control). \f(CWXInsertModifiermapEntry()\fP does not change the mapping itself. .LP This function is normally used by calling \f(CWXGetModifierMapping()\fP to get a pointer to the current \f(CWXModifierKeymap\fP structure for use as the \f(CImodmap\fR argument to \f(CWXInsertModifiermapEntry()\fR. .LP Note that the structure pointed to by \f(CImodmap\fR is freed by \f(CWXInsertModifiermapEntry()\fR. It should not be freed or otherwise used by applications. .LP .XX "modifier maps" For a description of the modifier map, see \f(CWXSetModifierMapping()\fP. .SH "Structures" .Ps typedef struct { int max_keypermod; /* server's max number of keys per modifier */ KeyCode *modifiermap; /* an 8 by \f(CImax_keypermod\fP array of * keycodes to be used as modifiers */ } XModifierKeymap; .XX "XModifierKeymap structure" .XX "structures:XModifierKeymap" #define ShiftMapIndex 0 #define LockMapIndex 1 #define ControlMapIndex 2 #define Mod1MapIndex 3 #define Mod2MapIndex 4 #define Mod3MapIndex 5 #define Mod4MapIndex 6 #define Mod5MapIndex 7 .Pe .ne 6 .SH "See Also" \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifierMap\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeySym\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XInstallColormap" "Xlib \- Colormaps" .ds ]W Xlib Reference Manual .SH "Name" .XX "XInstallColormap" .XX "colormaps:installing" .Na XInstallColormap \(en install a colormap. .Nz .SH "Synopsis" .Sy XInstallColormap\^(\^\f(CIdisplay\f(CW, \f(CIcolormap_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcolormap_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcolormap_return\fP 1i Specifies the colormap to install. .SH Description \f(CWXInstallColormap()\fP installs a virtual colormap into a hardware colormap. If there is only one hardware colormap, \f(CWXInstallColormap()\fP loads a virtual colormap into the hardware colormap. All windows associated with this colormap immediately display with their chosen colors. Other windows associated with the old colormap will display with false colors. If additional hardware colormaps are possible, \f(CWXInstallColormap()\fP loads the new hardware map and keeps the existing ones. Other windows will then remain in their true colors unless the limit for colormaps has been reached. If the maximum number of allowed hardware colormaps is already installed, an old colormap is swapped out. The .XX "MinCmapsOfScreen macro" .XX "MaxCmapsOfScreen macro" \f(CW\f(CWMinCmapsOfScreen\fP(\f(CIscreen\fP)\fR and \f(CW\f(CWMaxCmapsOfScreen\fP(\f(CIscreen\fP)\fR macros can be used to determine how many hardware colormaps are supported. .LP If \f(CIcolormap_return\fP is not already an installed map, a \f(CWColormapNotify\fP event is generated on every window having \f(CIcolormap_return\fP as an attribute. If a colormap is uninstalled as a result of the install, a \f(CWColormapNotify\fP event is generated on every window having that colormap as an attribute. .LP Colormaps are usually installed and uninstalled by the window manager, not by clients. At any time, there is a subset of the installed colormaps, viewed as an ordered list, called the "required list." The length of the required list is at most the \f(CWmin_maps\fP specified for each screen in the \f(CWDisplay\fP structure. When a colormap is installed with \f(CWXInstallColormap()\fP it is added to the head of the required list and the last colormap in the list is removed if necessary to keep the length of the list at \f(CWmin_maps\fP. When a colormap is uninstalled with \f(CWXUninstallColormap()\fP and it is in the required list, it is removed from the list. No other actions by the server or the client change the required list. It is important to realize that on all but high-performance workstations, \f(CWmin_maps\fP is likely to be 1. If the hardware colormap is immutable, and therefore installing any colormap is impossible, \f(CWXInstallColormap()\fP will work but not do anything. .LP For more information, see Volume One, Chapter 7, \fIColor\fR. .ne 8 .SH "Errors" .IP "\f(CWBadColor\fP" 1i Invalid colormap. .SH "See Also" \s-1\fIXDefaultColormap()\fP\s+1, \s-1\fIXDisplayCells()\fP\s+1, \s-1\fIXCopyColormapAndFree()\fP\s+1, \s-1\fIXCreateColormap()\fP\s+1, \s-1\fIXFreeColormap()\fP\s+1, \s-1\fIXGetStandardColormap()\fP\s+1, \s-1\fIXListInstalledColormaps()\fP\s+1, \s-1\fIXSetStandardColormap()\fP\s+1, \s-1\fIXSetWindowColormap()\fP\s+1, \s-1\fIXUninstallColormap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XInternAtom" "Xlib \- Properties" .ds ]W Xlib Reference Manual .SH "Name" .XX "XInternAtom" .XX "atoms:and property name strings" .Na XInternAtom \(en return an atom for a given property name string. .Nz .SH "Synopsis" .Sy Atom XInternAtom\^(\^\f(CIdisplay\f(CW, \f(CIproperty_name\f(CW\^, \f(CIonly_if_exists\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; char *\f(CIproperty_name\f(CW\^; Bool \f(CIonly_if_exists\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIproperty_name\fP 1i Specifies the string name of the property for which you want the atom. Uppercase or lowercase is important. If the property name is not in the Host Portable Character Encoding, then the result is implementation-dependent. .IP \f(CIonly_if_exists\fP 1i Specifies a boolean value: if no such \f(CIproperty_name\fP exists \f(CWXInternAtom()\fP will return \f(CWNone\fP if this argument is set to \f(CWTrue\fP or will create the atom if it is set to \f(CWFalse\fP. .SH Returns The atom. .SH Description \f(CWXInternAtom()\fP returns the atom identifier corresponding to string \f(CIproperty_name\fP. If the atom does not exist, then \f(CWXInternAtom()\fP either returns \f(CWNone\fP (if \f(CIonly_if_exists\fP is \f(CWTrue\fP) or creates the atom and returns its ID (if \f(CIonly_if_exists\fP is \f(CWFalse\fP). The string name should be a \f(CWNULL\fP-terminated. Case matters: the strings "thing," "Thing," and "thinG" all designate different atoms. The atom will remain defined even after the client that defined it has exited. It will become undefined only when the last connection to the X server closes. Therefore, the number of atoms interned should be kept to a minimum. .LP This function is the opposite of \f(CWXGetAtomName()\fP, which returns the atom name when given an atom ID. .LP Predefined atoms require no call to \f(CWXInternAtom()\fP. Predefined atoms are defined in <\fIX11/Xatom.h\fR> and begin with the prefix \f(CWXA_\fP. Predefined atoms are the only ones that do not require a call to \f(CWXInternAtom()\fP. .Nd 10 .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadValue\fP .SH "See Also" \s-1\fIXChangeProperty()\fP\s+1, \s-1\fIXDeleteProperty()\fP\s+1, \s-1\fIXGetAtomName()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXGetWindowProperty()\fP\s+1, \s-1\fIXListProperties()\fP\s+1, \s-1\fIXRotateWindowProperties()\fP\s+1, \s-1\fIXSetStandardProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XIntersectRegion" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XIntersectRegion" .XX "regions:computing intersection of" .Na XIntersectRegion \(en compute the intersection of two regions. .Nz .SH "Synopsis" .Sy XIntersectRegion\^(\^\f(CIsra\f(CW\^, \f(CIsrb\f(CW\^, \f(CIdr_return\f(CW\^) .As Region \f(CIsra\f(CW\^, \f(CIsrb\f(CW\^; Region \f(CIdr_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIsra\fP 1i .br .ns .IP \f(CIsrb\fP 1i .sp -2 Specify the two regions with which to perform the computation. .sp .IP \f(CIdr_return\fP 1i Returns the result of the computation. .SH Description \f(CWXIntersectRegion()\fP generates a region that is the intersection of two regions. .SH "Structures" \f(CWRegion\fP is a pointer to an opaque structure type. .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXCreateRegion()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XKeycodeToKeysym" "Xlib \- Keyboard" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XKeycodeToKeysym" .XX "keycodes:and keysyms" .XX "keysyms:converting from keycodes" XKeycodeToKeysym \(en convert a keycode to a keysym. .Nz .SH "Synopsis" .Sy KeySym XKeycodeToKeysym\^(\^\f(CIdisplay\f(CW, \f(CIkeycode\f(CW, \f(CIindex\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; KeyCode \f(CIkeycode\f(CW\^; int \f(CIindex\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIkeycode\fP 1i Specifies the keycode. .IP \f(CIindex\fP 1i Specifies which keysym in the list for the keycode to return. .SH Returns The \f(CWKeySym\fP. .SH Description \f(CWXKeycodeToKeysym()\fP returns one of the keysyms defined for the specified \f(CIkeycode\fP. \f(CWXKeycodeToKeysym()\fP uses internal Xlib tables. \f(CIindex\fP specifies which keysym in the array of keysyms corresponding to a keycode should be returned. If no symbol is defined, \f(CWXKeycodeToKeysym()\fP returns \f(CWNoSymbol\fP. .SH "See Also" \s-1\fIIsCursorKey()\fP\s+1, \s-1\fIIsFunctionKey()\fP\s+1, \s-1\fIIsKeypadKey()\fP\s+1, \s-1\fIIsMiscFunctionKey()\fP\s+1, \s-1\fIIsModifierKey()\fP\s+1, \s-1\fIIsPFKey()\fP\s+1, \s-1\fIXChangeKeyboardMapping()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXDisplayKeycodes()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifiermap()\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeysym()\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XKeysymToKeycode" "Xlib \- Keyboard" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XKeysymToKeycode" .XX "keysyms:converting to keycodes" .XX "keycodes:and keysyms XKeysymToKeycode \(en convert a keysym to the appropriate keycode. .Nz .SH "Synopsis" .Sy KeyCode XKeysymToKeycode\^(\^\f(CIdisplay\f(CW, \f(CIkeysym\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Keysym \f(CIkeysym\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIkeysym\fP 1i Specifies the keysym that is to be searched for. .SH Returns The keycode. .SH Description \f(CWXKeysymToKeycode()\fP returns the keycode corresponding to the specified keysym in the current mapping. If the specified keysym is not defined for any keycode, \f(CWXKeysymToKeycode()\fP returns zero. .LP .SH "See Also" \s-1\fIIsCursorKey()\fP\s+1, \s-1\fIIsFunctionKey()\fP\s+1, \s-1\fIIsKeypadKey()\fP\s+1, \s-1\fIIsMiscFunctionKey()\fP\s+1, \s-1\fIIsModifierKey()\fP\s+1, \s-1\fIIsPFKey()\fP\s+1, \s-1\fIXChangeKeyboardMapping()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXDisplayKeycodes()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifiermap()\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeysym()\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XKeysymToString" "Xlib \- Keyboard" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XKeysymToString" .XX "keysyms:converting to strings" XKeysymToString \(en convert a keysym symbol to a string. .Nz .SH "Synopsis" .Sy char *XKeysymToString\^(\^\f(CIkeysym\f(CW\^) .As KeySym \f(CIkeysym\f(CW\^; .Ae .SH "Arguments" .IP \f(CIkeysym\fP 1i Specifies the keysym that is to be converted. .SH Returns The string mapped to the specified keysym. .SH Description \f(CWXKeysymToString()\fP converts a keysym symbol (a number) into a character string. The returned string is in a static area and must not be modified. The returned string is in the Host Portable Character Encoding. If the specified keysym is not defined, \f(CWXKeysymToString()\fP returns \f(CWNULL\fP. For example, \f(CWXKeysymToString()\fP converts \f(CWXK_Shift\fR to "Shift". .LP Note that \&\f(CWXKeysymString\fP does not return the string that is mapped to the keysym, but only a string version of the keysym itself. In other words, even if the F1 key is mapped to the string "STOP" using \&\f(CWXRebindKeysym()\fP, \&\f(CWXKeysymToString()\fP still returns "F1". \&\f(CWXLookupString()\fP, however, would return "STOP". .LP In Release 4, \f(CWXKeysymToString()\fP can process keysyms that are not defined by the Xlib standard. Note that the set of keysyms that are available in this manner and the mechanisms by which Xlib obtains them is implementation-dependent. (In the MIT sample implementation, the resource file \fI/usr/lib/X11/XKeysymDB\fR is used starting in Release 4. The keysym name is used as the resource name, and the resource value is the keysym value in uppercase hexadecimal.) .SH "See Also" \s-1\fIIsCursorKey()\fP\s+1, \s-1\fIIsFunctionKey()\fP\s+1, \s-1\fIIsKeypadKey()\fP\s+1, \s-1\fIIsMiscFunctionKey()\fP\s+1, \s-1\fIIsModifierKey()\fP\s+1, \s-1\fIIsPFKey()\fP\s+1, \s-1\fIXChangeKeyboardMapping()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifiermap()\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeysym()\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XKillClient" "Xlib \- Client Connections" .ds ]W Xlib Reference Manual .SH "Name" .XX "XKillClient" .XX "client:destroying" .Na XKillClient \(en destroy a client or its remaining resources. .Nz .SH "Synopsis" .Sy XKillClient\^(\^\f(CIdisplay\f(CW, \f(CIresource\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XID \f(CIresource\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIresource\fP 1i Specifies any resource created by the client you want to destroy, or the constant \f(CWAllTemporary\fP. .SH Description If a valid resource is specified, \f(CWXKillClient()\fP forces a close-down of the client that created the resource. .XX "RetainPermanent mode:and XKillClient" .XX "RetainTemporary mode:and XKillClient" If the client has already terminated in either \f(CWRetainPermanent\fP or \f(CWRetainTemporary\fP mode, all of the client's resources are destroyed. If \f(CWAllTemporary\fP is specified in the \f(CIresource\fR argument, then the resources of all clients that have terminated in \f(CWRetainTemporary\fP are destroyed. .LP For more information, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "Errors" \f(CWBadValue\fP .SH "See Also" \s-1\fIXSetCloseDownMode()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "\s-2XLastKnownRequestProcessed\s+2" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XLastKnownRequestProcessed, LastKnownRequestProcessed \(en get serial number of last request processed by server. .XX "XLastKnownRequestProcessed" .Nz .\" .\" .SH "Synopsis" .Sy unsigned long XLastKnownRequestProcessed\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" .\" .SH Returns The serial number. .SH Description .XX "requests:getting last processed" \f(CWXLastKnownRequestProcessed()\fP extracts the full serial number of the last request known by Xlib to have been processed by the X server. Xlib automatically sets this number when replies, events, and errors are received. This can be useful in error and warning handlers. .LP .XX "LastKnownRequestProcessed" The C language macro \f(CWLastKnownRequestProcessed()\fP is equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXNextRequest()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XListDepths" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XListDepths" .XX "depth:available on given screen" .Na XListDepths \(en determine the depths available on a given screen. .Nz .SH "Synopsis" .Sy int *XListDepths\^(\^\f(CIdisplay\fP\^, \f(CIscreen_number\fP\^, \f(CIcount_return\fP\^) .As Display *\f(CIdisplay\fP\^; int \f(CIscreen_number\fP\^; int *\f(CIcount_return\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number on the host server. .IP \f(CIcount_return\fP 1i Returns the number of depths. .SH Returns The list of depths, or \f(CWNULL\fP on failure. .SH "Availability" Release 4 and later. .SH Description \f(CWXListDepths()\fR returns the array of depths that are available on the specified screen. If the specified \f(CIscreen_number\fP is valid and sufficient memory for the array can be allocated, \f(CWXListDepths()\fR sets \f(CIcount_return\fP to the number of available depths. Otherwise, it does not set \f(CIcount_return\fP and returns \f(CWNULL\fP. To release the memory allocated for the array of depths, use \f(CWXFree()\fR. .SH "See Also" \s-1\fIXDefaultDepthOfScreen()\fP\s+1, \s-1\fIXDefaultDepth()\fP\s+1, \s-1\fIXListPixmapFormats()\fP\s+1. .\"last line comment .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XListDev.man,v 1.6 94/06/04 17:31:20 rws Exp $ .ds xL Programming with Xlib .TH XListInputDevices 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XListInputDevices, XFreeDeviceList \- list available input devices .SH SYNTAX XDeviceInfo *XListInputDevices\^(\^\fIdisplay\fP, \fIndevices_return\fP\^) .br Display *\fIdisplay\fP\^; .br int *\fIndevices_return\fP\^; .sp XFreeDeviceList\^(\^\fIlist\fP\^) .br XDeviceInfo *\fIlist\fP\^; .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I ndevices_return Specifies a pointer to a variable where the number of available devices can be returned. .TP 12 .I list Specifies the list of devices to free. The \fIXFreeDeviceList\fP function frees the list of available extension input devices. .SH DESCRIPTION The \fIXListInputDevices\fP request lists the available extension input devices. This list includes the X pointer and X keyboard, any other input devices that are currently accessible through the X server, and any input devices that are not currently accessible through the X server but could be accessed if requested. .LP Some server implementations may make all input devices available at the time the server is initialized. Others may wait until requested by a client to access an input device. In the latter case, it is possible that an input device will be listed as available at one time but not at another. .LP For each input device available to the server, the XListInputDevices request returns an XDeviceInfo structure. That structure contains a pointer to a list of structures, each of which contains information about one class of input supported by the device. The XDeviceInfo structure is defined as follows: .DS .nf typedef struct _XDeviceInfo { XID id; Atom type; char *name; int num_classes; int use; XAnyClassPtr inputclassinfo; } XDeviceInfo; .fi .DE .LP The id is a number in the range 0-128 that uniquely identifies the device. It is assigned to the device when it is initialized by the server. .LP The type field is of type Atom and indicates the nature of the device. .LP The name field contains a pointer to a null-terminated string that corresponds to one of the defined device types. The name will correspond to one of the following strings (defined in the header file \fIXI.h\fP: .LP .DS XI_MOUSE XI_TABLET XI_KEYBOARD XI_TOUCHSCREEN XI_TOUCHPAD XI_BUTTONBOX XI_BARCODE XI_TRACKBALL XI_QUADRATURE XI_ID_MODULE XI_ONE_KNOB XI_NINE_KNOB XI_KNOB_BOX XI_SPACEBALL XI_DATAGLOVE XI_EYETRACKER XI_CURSORKEYS XI_FOOTMOUSE .DE .LP These names may be directly compared with the name field of the XDeviceInfo structure, or used in an XInternAtom request to return an atom that can be compared with the type field of the XDeviceInfo structure. .LP The num_classes field is a number in the range 0-255 that specifies the number of input classes supported by the device for which information is returned by ListInputDevices. Some input classes, such as class Focus and class Proximity do not have any information to be returned by ListInputDevices. .LP The use field specifies how the device is currently being used. If the value is \fIIsXKeyboard\fP, the device is currently being used as the X keyboard. If the value is \fIIsXPointer\fP, the device is currently being used as the X pointer. If the value is \fIIsXExtensionDevice\fP, the device is available for use as an extension device. .LP The inputclassinfo field contains a pointer to the first input-class specific data. The first two fields are common to all classes. .LP The class field is a number in the range 0-255. It uniquely identifies the class of input for which information is returned. Currently defined classes are KeyClass, ButtonClass, and ValuatorClass. .LP The length field is a number in the range 0- 255. It specifies the number of bytes of data that are contained in this input class. The length includes the class and length fields. .LP The XKeyInfo structure describes the characteristics of the keys on the device. It is defined as follows: .LP .DS .nf typedef struct _XKeyInfo { XID class; int length; unsigned short min_keycode; unsigned short max_keycode; unsigned short num_keys; } XKeyInfo; .fi .DE .LP min_keycode is of type KEYCODE. It specifies the minimum keycode that the device will report. The minimum keycode will not be smaller than 8. .LP max_keycode is of type KEYCODE. It specifies the maximum keycode that the device will report. The maximum keycode will not be larger than 255. .LP num_keys specifies the number of keys that the device has. .LP The XButtonInfo structure defines the characteristics of the buttons on the device. It is defined as follows: .LP .DS .nf typedef struct _XButtonInfo { XID class; int length; short num_buttons; } XButtonInfo; .fi .DE .LP num_buttons specifies the number of buttons that the device has. .LP The XValuatorInfo structure defines the characteristics of the valuators on the device. It is defined as follows: .LP .DE .nf typedef struct _XValuatorInfo { XID class; int length; unsigned char num_axes; unsigned char mode; unsigned long motion_buffer; XAxisInfoPtr axes; } XValuatorInfo; .fi .DS num_axes contains the number of axes the device supports. .LP mode is a constant that has one of the following values: Absolute or Relative. Some devices allow the mode to be changed dynamically via the SetDeviceMode request. .LP motion_buffer_size is a cardinal number that specifies the number of elements that can be contained in the motion history buffer for the device. .LP The axes field contains a pointer to an XAxisInfo structure. .LP The XAxisInfo structure is defined as follows: .LP .DS .nf typedef struct _XAxisInfo { int resolution; int min_value; int max_value; } XAxisInfo; .fi .DE .LP The resolution contains a number in counts/meter. .LP The min_val field contains a number that specifies the minimum value the device reports for this axis. For devices whose mode is Relative, the min_val field will contain 0. .LP The max_val field contains a number that specifies the maximum value the device reports for this axis. For devices whose mode is Relative, the max_val field will contain 0. .LP To free the \fIXDeviceInfo\fP array created by \fIXListInputDevices\fP, use \fIXFreeDeviceList\fP. .SH DIAGNOSTICS none. .SH "SEE ALSO" .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XListExtensions" "Xlib \- Extensions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XListExtensions" .XX "extensions:lists, returning" .Na XListExtensions \(en return a list of all extensions to X supported by the server. .Nz .SH "Synopsis" .Sy char **XListExtensions(\^\f(CIdisplay\f(CW, \f(CInextensions_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int *\f(CInextensions\_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CInextensions_return\fP 1i Returns the number of extensions in the returned list. .SH Returns The list of extension name strings. .SH Description .XX "X:extensions to" \f(CWXListExtensions()\fP lists all the X extensions supported by the current server. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the result is implementation-dependent. .LP For more information on extensions, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "See Also" \s-1\fIXFreeExtensionList()\fP\s+1, \s-1\fIXQueryExtension()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XListFonts" "Xlib \- Fonts" .ds ]W Xlib Reference Manual .SH "Name" .XX "fonts:listing" .Na XListFonts \(en return a list of the available font names. .Nz .SH "Synopsis" .Sy char **XListFonts\^(\^\f(CIdisplay\f(CW, \f(CIpattern\f(CW\^, \f(CImaxnames\f(CW, \f(CIactual_count_return\f(CW\^) .As Display *\^\f(CIdisplay\f(CW\^; char *\^\f(CIpattern\f(CW\^; int \f(CImaxnames\f(CW\^; int *\^\f(CIactual_count_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIpattern\fP 1i Specifies the string associated with the font names you want returned. You can specify any string, including asterisks (*) and question marks (?). The asterisk indicates a wildcard for any number of characters and the question mark indicates a wildcard for a single character. Uppercase or lowercase is not important. If the pattern string is not in the Host Portable Character Encoding the result is implementation-dependent. .IP \f(CImaxnames\fP 1i Specifies the maximum number of names that are to be in the returned list. .IP \f(CIactual_count_return\fP 1i Returns the actual number of font names in the list. .SH Returns The list of font names. .SH Description \f(CWXListFonts()\fP returns a list of font names that match the string \f(CIpattern\fP. Each returned font name string is terminated by \f(CWNULL\fP. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the result is implementation-dependent. The maximum number of names returned in the list is the value you passed to \f(CImaxnames\fP. The function returns the actual number of font names in \f(CIactual_count_return\fP. .LP If no fonts match the specified names, \f(CWXListFonts()\fP returns \f(CWNULL\fP. .LP The client should call \f(CWXFreeFontNames()\fP when done with the font name list. .LP The font search path (the order in which font names in various directories are compared to \f(CIpattern\fP) is set by \f(CWXSetFontPath()\fP. .LP For more information on fonts, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .Nd 10 .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXFreeFont()\fP\s+1, \s-1\fIXFreeFontInfo()\fP\s+1, \s-1\fIXFreeFontNames()\fP\s+1, \s-1\fIXFreeFontPath()\fP\s+1, \s-1\fIXGetFontPath()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXListFontsWithInfo()\fP\s+1, \s-1\fIXLoadFont()\fP\s+1, \s-1\fIXLoadQueryFont()\fP\s+1, \s-1\fIXQueryFont()\fP\s+1, \s-1\fIXSetFont()\fP\s+1, \s-1\fIXSetFontPath()\fP\s+1, \s-1\fIXUnloadFont()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XListFontsWithInfo" "Xlib \- Fonts" .ds ]W Xlib Reference Manual .SH "Name" .XX "XListFontsWithInfo" .XX "fonts:listing;with information" .Na XListFontsWithInfo \(en obtain the names and information about available fonts. .Nz .SH "Synopsis" .Sy char **XListFontsWithInfo\^(\^\f(CIdisplay\f(CW, \f(CIpattern\f(CW, \f(CImaxnames\f(CW, .ti +10n \f(CIcount_return\f(CW, \f(CIinfo_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; char *\f(CIpattern\f(CW\^; /* NULL-terminated */ int \f(CImaxnames\f(CW\^; int *\f(CIcount_return\f(CW\^; XFontStruct **\f(CIinfo_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIpattern\fP 1i Specifies the string associated with the font names you want returned. You can specify any string, including asterisks (*) and question marks (?). The asterisk indicates a wildcard on any number of characters and the question mark indicates a wildcard on a single character. Uppercase or lowercase is not important. If the pattern string is not in the Host Portable Character Encoding the result is implementation-dependent. .IP \f(CImaxnames\fP 1i Specifies the maximum number of names that are to be in the returned list. .IP \f(CIcount_return\fP 1i Returns the actual number of matched font names. .IP \f(CIinfo_return\fP 1i Returns a pointer to a list of font information structures. \f(CWXListFontsWithInfo()\fP provides enough space for \f(CImaxnames\fP pointers. .SH Returns The list of font names. .SH Description \f(CWXListFontsWithInfo()\fP returns a list of font names that match the specified \f(CIpattern\fP and a also returns limited information about each font that matches. The list of names is limited to the size specified by the \f(CImaxnames\fP argument. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the result is implementation-dependent. .LP \f(CWXListFontsWithInfo()\fR returns \f(CWNULL\fR if no matches were found. .LP To free the allocated name array, the client should call \f(CWXFreeFontNames()\fP. To free the font information array, the client should call \f(CWXFreeFontInfo()\fP. .LP The information returned for each font is identical to what \f(CWXLoadQueryFont()\fP would return, except that the per-character metrics (\f(CWlbearing\fP, \f(CWrbearing\fP, \f(CWwidth\fP, \f(CWascent\fP, \f(CWdescent\fP for single characters) are not returned. .LP .XX "fonts:search path" The font search path (the order in which font names in various directories are compared to \f(CIpattern\fP) is set by \f(CWXSetFontPath()\fP. .LP For more information on fonts, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" .Ps .ta 4.5n 2.15i typedef struct { XExtData *ext_data; /* hook for extension to hang data */ Font fid; /* Font ID for this font */ unsigned direction; /* hint about direction the font is painted */ unsigned min_char_or_byte2; /* first character */ unsigned max_char_or_byte2; /* last character */ unsigned min_byte1; /* first row that exists */ unsigned max_byte1; /* last row that exists */ Bool all_chars_exist; /* flag if all characters have non-zero size */ unsigned default_char; /* char to print for undefined character */ int n_properties; /* how many properties there are */ XFontProp *properties; /* pointer to array of additional properties */ XCharStruct min_bounds; /* minimum bounds over all existing char */ XCharStruct max_bounds; /* maximum bounds over all existing char */ XCharStruct *per_char; /* first_char to last_char information */ int ascent; /* logical extent above baseline for spacing */ int descent; /* logical descent below baseline for spacing */ } XFontStruct; .Pe .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXFreeFont()\fP\s+1, \s-1\fIXFreeFontInfo()\fP\s+1, \s-1\fIXFreeFontNames()\fP\s+1, \s-1\fIXFreeFontPath()\fP\s+1, \s-1\fIXGetFontPath()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXListFonts()\fP\s+1, \s-1\fIXLoadFont()\fP\s+1, \s-1\fIXLoadQueryFont()\fP\s+1, \s-1\fIXQueryFont()\fP\s+1, \s-1\fIXSetFont()\fP\s+1, \s-1\fIXSetFontPath()\fP\s+1, \s-1\fIXUnloadFont()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XListHosts" "Xlib \- Host Access" .ds ]W Xlib Reference Manual .SH "Name" .XX "XListHosts" .XX "hosts:list of" .Na XListHosts \(en obtain a list of hosts having access to this display. .Nz .SH "Synopsis" .Sy XHostAddress *XListHosts\^(\^\f(CIdisplay\f(CW, \f(CInhosts_return\f(CW, \f(CIstate_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int *\f(CInhosts_return\f(CW\^; Bool *\f(CIstate_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CInhosts_return\fP 1i Returns the number of hosts currently in the access control list. .IP \f(CIstate_return\fP 1i Returns whether the access control list is currently being used by the server to process new connection requests from clients. \f(CWTrue\fP if enabled, \f(CWFalse\fP if disabled. .SH Returns The list of structures describing each host. .SH Description .XX "access control lists" \f(CWXListHosts()\fP returns the current access control list as well as whether the use of the list is enabled or disabled. \f(CWXListHosts()\fP allows a program to find out what machines make connections, by looking at a list of host structures. This \f(CWXHostAddress\fP list should be freed when it is no longer needed. .LP For more information on access control lists, see Volume One, Chapter 13, \fIOther Programming Techniques\fR. .SH Structures .Ps typedef struct { int family; int length; char *address; } XHostAddress; .Pe .SH "See Also" \s-1\fIXAddHost()\fP\s+1, \s-1\fIXAddHosts()\fP\s+1, \s-1\fIXDisableAccessControl()\fP\s+1, \s-1\fIXEnableAccessControl()\fP\s+1, \s-1\fIXRemoveHost()\fP\s+1, \s-1\fIXRemoveHosts()\fP\s+1, \s-1\fIXSetAccessControl()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XListInstalledColormaps" "Xlib \- Colormaps" .ds ]W Xlib Reference Manual .SH "Name" .XX "XListInstalledColormaps" .XX "colormaps:list of" .Na XListInstalledColormaps \(en get a list of installed colormaps. .Nz .SH "Synopsis" .Sy Colormap *XListInstalledColormaps\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CInum_return\f(CW\^) .As display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; int *\f(CInum_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window for whose screen you want the list of currently installed colormaps. .IP \f(CInum_return\fP 1i Returns the number of currently installed colormaps in the returned list. .SH Returns The list of colormaps. .SH Description \f(CWXListInstalledColormaps()\fP returns a list of the currently installed colormaps for the screen containing the specified window. The order in the list is not significant. There is no distinction in the list between colormaps actually being used by windows and colormaps no longer in use which have not yet been freed or destroyed. .LP The allocated list should be freed using \f(CWXFree()\fP when it is no longer needed. .LP For more information on installing colormaps, see Volume One, Chapter 7, \fIColor\fR. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXDefaultColormap()\fP\s+1, \s-1\fIXDisplayCells()\fP\s+1, \s-1\fIXCopyColormapAndFree()\fP\s+1, \s-1\fIXCreateColormap()\fP\s+1, \s-1\fIXFreeColormap()\fP\s+1, \s-1\fIXGetStandardColormap()\fP\s+1, \s-1\fIXInstallColormap()\fP\s+1, \s-1\fIXSetStandardColormap()\fP\s+1, \s-1\fIXSetWindowColormap()\fP\s+1, \s-1\fIXUninstallColormap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XListPixmapFormats" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XListPixmapFormats" .XX "pixmaps:obtaining formats of" .Na XListPixmapFormats \(en obtain the supported pixmap formats for a given server. .Nz .SH "Synopsis" .Sy XPixmapFormatValues *XListPixmapFormats\^(\^\f(CIdisplay\fP\^, \f(CIcount_return\fP\^) .As Display *\f(CIdisplay\fP\^; int *\f(CIcount_return\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .ds Cn pixmap formats that are supported by the server .IP \f(CIcount_return\fP 1i Returns the number of \*(Cn. .SH Returns A list of structures describing pixmap formats. .SH "Availability" Release 4 and later. .SH Description .LP \f(CWXListPixmapFormats()\fR returns an array of .XX "XPixmapFormatValues structure" .XX "structures:XPixmapFormatValues" \f(CWXPixmapFormatValues\fR structures that describe the types of Z format images that are supported by the specified server. If insufficient memory is available, \f(CWXListPixmapFormats()\fR returns \f(CWNULL\fP. To free the allocated storage for the \f(CWXPixmapFormatValues\fR structures, use \f(CWXFree()\fR. .SH "Structures" .Ps 0 typedef struct { int depth; int bits_per_pixel; int scanline_pad; } XPixmapFormatValues; .Pe .SH "See Also" \s-1\fIXListDepths()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XListProperties" "Xlib \- Properties" .ds ]W Xlib Reference Manual .SH "Name" .XX "XListProperties" .XX "property list:of windows" .Na XListProperties \(en get the property list for a window. .Nz .SH "Synopsis" .Sy Atom *XListProperties\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CInum_prop_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; int *\f(CInum_prop_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window whose property list you want. .IP \f(CInum_prop_return\fP 1i Returns the length of the properties array. .SH Returns The list of Atoms. .SH Description \f(CWXListProperties()\fP returns a pointer to an array of atoms for properties that are defined for the specified window. \f(CWXListProperties()\fR returns \f(CWNULL\fR on failure (when window \f(CIw\fP is invalid or if no properties were found). .LP To free the memory allocated by this function, use \f(CWXFree()\fP. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXChangeProperty()\fP\s+1, \s-1\fIXDeleteProperty()\fP\s+1, \s-1\fIXGetAtomName()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXGetWindowProperty()\fP\s+1, \s-1\fIXInternAtom()\fP\s+1, \s-1\fIXRotateWindowProperties()\fP\s+1, \s-1\fIXSetStandardProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XLoadFont" "Xlib \- Fonts" .ds ]W Xlib Reference Manual .SH "Name" .XX "XLoadFont" .XX "fonts:loading" .Na XLoadFont \(en load a font if not already loaded; get font ID. .Nz .SH "Synopsis" .Sy Font XLoadFont\^(\^\f(CIdisplay\f(CW, \f(CIname\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; char *\f(CIname\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIname\fP 1i Specifies the name of the font in a \f(CWNULL\fP-terminated string. As of Release 4, the * and ? wildcards are allowed and may be supported by the server. Uppercase or lowercase is not important. If the font name is not in the Host Portable Character Encoding, the result is implementation-dependent. .SH Returns The Font ID. .SH Description \f(CWXLoadFont()\fP loads a font into the server if it has not already been loaded by another client. \f(CWXLoadFont()\fP returns the font ID or, if it was unsuccessful, generates a \f(CWBadName\fP error. .XX "XUnloadFont" When the font is no longer needed, the client should call \f(CWXUnloadFont()\fP. Fonts are not associated with a particular screen. Once the font ID is available, it can be set in the \f(CWfont\fP member of any GC, and thereby used in subsequent drawing requests. .LP .XX "XLoadFontWithInfo" .XX "XQueryFont" Font information is usually necessary for locating the text. Call \f(CWXLoadFontWithInfo()\fP to get the info at the time you load the font, or call \f(CWXQueryFont()\fP if you used \f(CWXLoadFont()\fP to load the font. .LP For more information on fonts, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Errors" .IP "\f(CWBadAlloc\fP" 1i Server has insufficient memory to store font. .IP "\f(CWBadName\fP" 1i \f(CIname\fR specifies an unavailable font. .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXFreeFont()\fP\s+1, \s-1\fIXFreeFontInfo()\fP\s+1, \s-1\fIXFreeFontNames()\fP\s+1, \s-1\fIXFreeFontPath()\fP\s+1, \s-1\fIXGetFontPath()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXListFonts()\fP\s+1, \s-1\fIXListFontsWithInfo()\fP\s+1, \s-1\fIXLoadQueryFont()\fP\s+1, \s-1\fIXQueryFont()\fP\s+1, \s-1\fIXSetFont()\fP\s+1, \s-1\fIXSetFontPath()\fP\s+1, \s-1\fIXUnloadFont()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XLoadQueryFont" "Xlib \- Fonts" .ds ]W Xlib Reference Manual .SH "Name" .XX "XLoadQueryFont" .XX "fonts:loading" .Na XLoadQueryFont \(en load a font and fill information structure. .Nz .SH "Synopsis" .Sy XFontStruct *XLoadQueryFont\^(\^\f(CIdisplay\f(CW, \f(CIname\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; char *\f(CIname\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIname\fP 1i Specifies the name of the font. This name is a \f(CWNULL\fP-terminated string. As of Release 4, the * and ? wildcards are allowed and may be supported by the server. Uppercase or lowercase is not important. If the font name is not in the Host Portable Character Encoding, the result is implementation-dependent. .SH Returns The font description structure. .SH Description .XX "XLoadFont:and XLoadQueryFont" .XX "XQueryFont:and XLoadQueryFont" \f(CWXLoadQueryFont()\fP performs an \f(CWXLoadFont()\fP and \f(CWXQueryFont()\fP in a single operation. \f(CWXLoadQueryFont()\fP provides the easiest way to get character-size tables for placing a proportional font. That is, \f(CWXLoadQueryFont()\fP both opens (loads) the specified font and returns a pointer to the appropriate \f(CWXFontStruct\fP structure. If the font does not exist, \f(CWXLoadQueryFont()\fP returns \f(CWNULL\fP. .LP .XX "XFontStruct structure" .XX "structures:XFontStruct" The \f(CWXFontStruct\fP structure consists of the font-specific information and a pointer to an array of \f(CWXCharStruct\fP structures for each character in the font. .LP For more information on fonts, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Errors" .IP \f(CWBadAlloc\fR 1i Server has insufficient memory to store font. .IP \f(CWBadName\fR 1i \f(CWname\fR specifies an unavailable font. .SH "Structures" .Ps typedef struct { XExtData *ext_data; /* hook for extension to hang data */ Font fid; /* Font ID for this font */ unsigned direction; /* hint about direction the font is painted */ unsigned min_char_or_byte2; /* first character */ unsigned max_char_or_byte2; /* last character */ unsigned min_byte1; /* first row that exists */ unsigned max_byte1; /* last row that exists */ Bool all_chars_exist; /* flag if all characters have non-zero size*/ unsigned default_char; /* char to print for undefined character */ int n_properties; /* how many properties there are */ XFontProp *properties; /* pointer to array of additional properties*/ XCharStruct min_bounds; /* minimum bounds over all existing char*/ XCharStruct max_bounds; /* maximum bounds over all existing char*/ XCharStruct *per_char; /* first_char to last_char information */ int ascent; /* logical extent above baseline for spacing */ int descent; /* logical descent below baseline for spacing */ } XFontStruct; typedef struct { short lbearing; /* origin to left edge of character */ short rbearing; /* origin to right edge of character */ short width; /* advance to next char's origin */ short ascent; /* baseline to top edge of character */ short descent; /* baseline to bottom edge of character */ unsigned short attributes; /* per char flags (not predefined) */ } XCharStruct; .Pe .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXFreeFont()\fP\s+1, \s-1\fIXFreeFontInfo()\fP\s+1, \s-1\fIXFreeFontNames()\fP\s+1, \s-1\fIXFreeFontPath()\fP\s+1, \s-1\fIXGetFontPath()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXListFonts()\fP\s+1, \s-1\fIXListFontsWithInfo()\fP\s+1, \s-1\fIXLoadFont()\fP\s+1, \s-1\fIXQueryFont()\fP\s+1, \s-1\fIXSetFont()\fP\s+1, \s-1\fIXSetFontPath()\fP\s+1, \s-1\fIXUnloadFont()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XLocaleOfFontSet" "Xlib \- Internationalized Text Output" .ds ]W Xlib Reference Manual .XX "XLocaleOfFontSet" .XX "font set:locale, obtaining" .XX "locale:font set, obtaining" .SH Name .Na XLocaleOfFontSet \(en get the locale of a font set. .Nz .SH Synopsis .Sy char *XLocaleOfFontSet\^(\^\f(CIfont_set\fP\^) .As XFontSet \f(CIfont_set\fP\^; .Ae .SH Arguments .IP \f(CIfont_set\fP 1i Specifies the font set. .SH Returns The locale name (\f(CWNULL\fP-terminated). .SH Availability Release 5 and later. .SH Description \f(CWXLocaleOfFontSet()\fR returns the name of the locale bound to the specified \f(CWXFontSet\fR, as a \f(CWNULL\fP-terminated string. .LP The returned locale name string is owned by Xlib and should not be modified or freed by the client. It may be freed by a call to \f(CWXFreeFontSet()\fR with the associated \f(CWXFontSet\fR. Until freed, it will not be modified by Xlib. .hy 14 .SH "See Also" \s-1\fIXCreateFontSet()\fP\s+1, \s-1\fIXExtentsOfFontSet()\fP\s+1, \s-1\fIXFontsOfFontSet()\fP\s+1, \s-1\fIXBaseFontNameListOfFontSet()\fP\s+1, \s-1\fIXContextDependentDrawing()\fP\s+1. .\"last line comment .nh .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XLocaleOfIM" "Xlib \- Input Methods" .ds ]W Xlib Reference Manual .XX "XLocaleOfIM" .XX "input methods:locale of" .XX "locale:input methods" .SH Name .Na XLocaleOfIM \(en get the locale of an input method. .Nz .SH Synopsis .Sy char * XLocaleOfIM\^(\^\f(CIim\fP\^) .As XIM \f(CIim\fP\^; .Ae .SH Arguments .IP \f(CIim\fP .5i Specifies the input method. .SH Returns The locale name. .SH Availability Release 5 and later. .SH Description \f(CWXLocaleOfIM()\fR returns the name of the locale associated with the specified input method. The returned string is owned by Xlib and should not be freed by the client. .SH "See Also" \s-1\fIXOpenIM()\fP\s+1, \s-1\fIXCloseIM()\fP\s+1, \s-1\fIXGetIMValues()\fP\s+1, \s-1\fIXDisplayOfIM()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XLookUpAssoc" "Xlib \- Association Tables" .ds ]W Xlib Reference Manual .SH "Name" .XX "XLookUpAssoc" .XX "association tables:obtaining data from" .Na XLookUpAssoc \(en obtain data from an association table. .Nz .SH "Synopsis" .Sy char * XLookUpAssoc\^(\^\f(CIdisplay\f(CW, \f(CItable\f(CW\^, \f(CIx_id\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XAssocTable *\f(CItable\f(CW\^; XID \f(CIx_id\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CItable\fP 1i Specifies the association table. .IP \f(CIx_id\fP 1i Specifies the X resource ID. .sp -2p .SH Returns The data from the association table. .SH Description This function is provided for compatibility with X Version 10. To use it you must include the file .I and link with the library \fI-loldX\fP. .LP Association tables provide a way of storing data locally and accessing by ID. \f(CWXLookUpAssoc()\fP retrieves the data stored in an \f(CWXAssoc\%Table\fP by its \f(CWXID\fP. If the matching \f(CWXID\fP can be found in the table, the routine returns the data associated with it. If the \f(CIx_id\fP cannot be found in the table the routine returns \f(CWNULL\fP. .LP For more information on association tables, see Volume One, Appendix B, \fIX10 Compatibility\fP. .SH Structures .Ps typedef struct { XAssoc *buckets; /* pointer to first bucket in bucket array */ int size; /* table size (number of buckets) */ } XAssocTable; typedef struct _XAssoc { struct _XAssoc *next; /* next object in this bucket */ struct _XAssoc *prev; /* previous object in this bucket */ Display *display; /* display which owns the ID */ XID x_id; /* X Window System ID */ char *data; /* pointer to untyped memory */ .ne 5 } XAssoc; .Pe .sp -3p .SH "See Also" \s-1\fIXCreateAssocTable()\fP\s+1, \s-1\fIXDeleteAssoc()\fP\s+1, \s-1\fIXDestroyAssocTable()\fP\s+1, \s-1\fIXMakeAssoc()\fP\s+1. .\" Last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XLookupColor" "Xlib \- Color Cells" .ds ]W Xlib Reference Manual .SH "Name" .XX "XLookupColor" .Na XLookupColor \(en get database RGB values and closest hardware-supported RGB values from color name. .Nz .SH "Synopsis" .Sy Status XLookupColor\^(\^\f(CIdisplay\f(CW, \f(CIcolormap\f(CW, \f(CIcolorname\f(CW, \f(CIexact_def_return\f(CW, \f(CIscreen_def_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcolormap\f(CW\^; char *\f(CIcolorname\f(CW\^; XColor *\f(CIexact_def_return\f(CW, *\f(CIscreen_def_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.2i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcolormap\fP Specifies the colormap. .IP \f(CIcolorname\fP Specifies a color name string (for example "red"). Uppercase or lowercase does not matter. If the color name is not in the Host Portable Character Encoding, the result is implementation-dependent. .IP \f(CIexact_def_return\fP Returns the exact RGB values for the specified color name from the \fI/usr/lib/X11/rgb\fP database. .IP \f(CIscreen_def_return\fP Returns the closest RGB values possible on the hardware. .SH Returns Zero on failure, non-zero on success. .SH Description .XX "color:obtaining RGB values for" \f(CWXLookupColor()\fP looks up RGB values for a color given the colorname string. It returns both the exact color values and the closest values possible on tthe screen specified by \f(CIcolormap\fP. .LP \f(CWXLookupColor()\fP returns non-zero if \f(CIcolorname\fP exists in the RGB database or zero if it does not exist. .LP To determine the exact RGB values, \f(CWXLookupColor()\fP uses a database on the X server. On UNIX, this database is \fI/usr/lib/X11/rgb\fP. To read the colors provided by the database on a UNIX-based system, see \fI/usr/lib/X11/rgb.txt.\fP The location, name, and contents of this file are server-dependent. .LP For more information see Volume One, Chapter 7, \fIColor\fR, and Appendix D, \fIThe Server-side Color Database\fR, in this volume. .br .ne 8 .SH "Errors" .IP "\f(CWBadName\fP" 1i Color name not in database. .IP "\f(CWBadColor\fP" 1i Invalid colormap. .SH "Structures" .Ps typedef struct { unsigned long pixel; unsigned short red, green, blue; char flags; /* DoRed, DoGreen, DoBlue */ char pad; } XColor; .Pe .ne 5 .SH "See Also" \s-1\fIXBlackPixel()\fP\s+1, \s-1\fIXWhitePixel()\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocColorCells()\fP\s+1, \s-1\fIXAllocColorPlanes()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXFreeColors()\fP\s+1, \s-1\fIXParseColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1, \s-1\fIXStoreNamedColor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XLookupKeysym" "Xlib \- Keyboard" .ds ]W Xlib Reference Manual .SH "Name" .XX "XLookupKeysym" .XX "keysyms:corresponding to keycodes" .Na XLookupKeysym \(en get the keysym corresponding to a keycode in structure. .Nz .SH "Synopsis" .Sy KeySym XLookupKeysym(\^\f(CIevent\f(CW, \f(CIindex\f(CW\^) .As XKeyEvent *\f(CIevent\f(CW\^; int \f(CIindex\f(CW\^; .Ae .SH "Arguments" .IP \f(CIevent\fP .8i Specifies the \f(CWKeyPress\fP or \f(CWKeyRelease\fP event that is to be used. .IP \f(CIindex\fP Specifies which keysym from the list associated with the keycode in the event to return. These correspond to the modifier keys, and the symbols \f(CWShiftMapIndex\fP, \f(CWLockMapIndex\fP, \f(CWControl\%Map\%Index\fP, \f(CWMod1\%Map\%Index\fP, \f(CWMod2\%Map\%Index\fP, \f(CWMod3\%Map\%Index\fP, \f(CWMod4\%Map\%Index\fP, and \f(CWMod5\%Map\%Index\fP can be used. .SH Returns The keysym. .SH Description .XX "keycodes:and keysyms" Given a keyboard event and the \f(CIindex\fP into the list of keysyms for that keycode, \f(CWXLookupKeysym()\fP returns the keysym from the list that corresponds to the keycode in the event. If no keysym is defined for the keycode of the event, \f(CWXLookupKeysym()\fP returns \f(CWNoSymbol\fP. .LP Each keycode may have a list of associated keysyms, which are portable symbols representing the meanings of the key. The \f(CIindex\fP specifies which keysym in the list is desired, indicating the combination of modifier keys that are currently pressed. Therefore, the program must interpret the \f(CWstate\fP member of the \f(CWXKeyEvent\fP structure to determine the \f(CIindex\fP before calling this function. The exact mapping of modifier keys into the list of keysyms for each keycode is server-dependent beyond the fact that the first keysym corresponds to the keycode without modifier keys, and the second corresponds to the keycode with Shift pressed. .LP \f(CWXLookupKeysym()\fP simply calls \f(CWXKeycodeToKeysym()\fP, using arguments taken from the specified event structure. .SH Structures .Ps .ta 4.5n 1.9i typedef struct { int type; /* of event */ unsigned long serial; /* # of last request processed by server */ Bool send_event; /* true if this came from a SendEvent request */ Display *display; /* display the event was read from */ Window window; /* \&"event"\& window it is reported relative to */ Window root; /* root window that the event occured on */ Window subwindow; /* child window */ Time time; /* milliseconds */ int x, y; /* pointer x, y coordinates in event window */ int x_root, y_root; /* coordinates relative to root */ unsigned int state; /* key or button mask */ unsigned int keycode; /* detail */ Bool same_screen; /* same screen flag */ } XKeyEvent; .Pe .ne 6 .SH "See Also" \s-1\fIXChangeKeyboardMapping()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifiermap()\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeysym()\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XLookupString" "Xlib \- Keyboard" .ds ]W Xlib Reference Manual .SH "Name" .XX "XLookupString" .XX "strings:mapping key events to" .Na XLookupString \(en map a key event to ASCII string, keysym, and \f(CWComposeStatus\fP. .Nz .SH "Synopsis" .Sy int XLookupString(\^\f(CIevent_structure\f(CW, \f(CIbuffer_return\f(CW, \f(CIbytes_buffer\f(CW, \f(CIkeysym_return\f(CW, .br \f(CIstatus_in_out\f(CW\^) .As XKeyEvent *\f(CIevent_structure\f(CW\^; char *\f(CIbuffer_return\f(CW\^; int \f(CIbytes_buffer\f(CW\^; KeySym *\f(CIkeysym_return\f(CW\^; XComposeStatus *\f(CIstatus_in_out\f(CW\^; /* may not be implemented */ .Ae .SH "Arguments" .IP \f(CIevent_structure\fP 1i Specifies the key event to be used. .IP \f(CIbuffer_return\fP 1i Returns the resulting string (not \f(CWNULL\fR-terminated). Returned value of the function is the length of the string. .IP \f(CIbytes_buffer\fP 1i Specifies the length of the buffer. No more than \f(CIbytes_buffer\fP of translation are returned. .IP \f(CIkeysym_return\fP 1i If this argument is not \f(CWNULL\fP, it specifies the keysym ID computed from the event. .IP \f(CIstatus_in_out\fP 1i Specifies the \f(CWXComposeStatus\fP structure that contains compose key state information and that allows the compose key processing to take place. This can be \f(CWNULL\fP if the caller is not interested in seeing compose key sequences. Not implemented in X Consortium Xlib through Release 5. .SH Returns Length of string in \f(CIbuffer_return\fP argument. .SH Description \f(CWXLookupString()\fP gets an ASCII string and a keysym that are currently mapped to the keycode in a \f(CWKeyPress\fP or \f(CWKeyRelease\fP event, using the modifier bits in the key event to deal with shift, lock and control. The \f(CWXLookupString()\fP return value is the length of the translated string and the string's bytes are copied into \f(CIbuffer_return\fP. The length may be .ne 2 greater than 1 if the event's keycode translates into a keysym that was rebound with \f(CWXRebindKeysym()\fP. .LP Note that the string returned in \f(CIbuffer\fP is not \f(CWNULL\fP-\fPterminated\fP. If you need a \f(CWNULL\fP-terminated string, copy \f(CIbuffer\fP into another string as follows: .Ps len = XLookupString((XKeyEvent *)event, buffer, 10, nil, nil); if (len) (void) strncat (cmd_buf, buffer, len); .Pe The compose \f(CIstatus.in.out\fP is not implemented in any release of the X Consortium version of Xlib through Release 5. .LP In Release 4, \f(CWXLookupString()\fP implements the new concept of keyboard groups. Keyboard groups support having two complete sets of keysyms for a keyboard. Which set will be used can be toggled using a particular key. This is implemented by using the first two keysyms in the list for a key as one set, and the next two keysyms as the second set. For more information on keyboard groups, see Volume One, Appendix G, \fIRelease Notes\fR. .LP For more information on using \f(CWXLookupString()\fP in general, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "Structures" .Ps /* * Compose sequence status.in.out structure, used in calling XLookupString. */ typedef struct _XComposeStatus { char *compose_ptr; /* state table pointer */ int chars_matched; /* match state */ } XComposeStatus; typedef struct { int type; /* of event */ unsigned long serial; /* # of last request processed by server */ Bool send_event; /* true if this came from a SendEvent request */ Display *display; /* Display the event was read from */ Window window; /* \&"event"\& window it is reported relative to */ Window root; /* root window that the event occured on */ Window subwindow; /* child window */ Time time; /* milliseconds */ int x, y; /* pointer x, y coordinates in event window */ int x_root, y_root; /* coordinates relative to root */ unsigned int state; /* key or button mask */ unsigned int keycode; /* detail */ Bool same_screen; /* same screen flag */ } XKeyEvent; .Pe .Nd 10 .SH "See Also" \s-1\fIXChangeKeyboardMapping()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXNewModifiermap()\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeysym()\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XLowerWindow" "Xlib \- Window Manipulation" .ds ]W Xlib Reference Manual .SH "Name" .XX "XLowerWindow" .XX "windows:lowering" .Na XLowerWindow \(en lower a window in the stacking order. .Nz .SH "Synopsis" .Sy XLowerWindow\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window to be lowered. .SH Description \f(CWXLowerWindow()\fP lowers a window in the stacking order of its siblings so that it does not obscure any sibling windows. If the windows are regarded as overlapping sheets of paper stacked on a desk, then lowering a window is analogous to moving the sheet to the bottom of the stack, while leaving its x and y location on the desk constant. Lowering a mapped window will generate exposure events on any windows it formerly obscured. .LP If the \f(CWoverride_redirect\fP attribute of the window (see Chapter 4, \fIWindow Attributes\fR) is \f(CWFalse\fP and the window manager has selected \f(CWSubstructureRedirectMask\fP on the parent, then a \f(CWConfigureRequest\fP event is sent to the window manager, and no further processing is performed. Otherwise, the window is lowered to the bottom of the stack. .LP \f(CWLeaveNotify\fP events are sent to the lowered window if the pointer was inside it, and \f(CWEnterNotify\fP events are sent to the window which was immediately below the lowered window at the pointer position. .LP For more information, see Volume One, Chapter 16, \fIWindow Management\fR. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXCirculateSubwindows()\fP\s+1, \s-1\fIXCirculateSubwindowsDown()\fP\s+1, \s-1\fIXCirculateSubwindowsUp()\fP\s+1, \s-1\fIXConfigureWindow()\fP\s+1, \s-1\fIXMoveResizeWindow()\fP\s+1, \s-1\fIXMoveWindow()\fP\s+1, \s-1\fIXQueryTree()\fP\s+1, \s-1\fIXRaiseWindow()\fP\s+1, \s-1\fIXReparentWindow()\fP\s+1, \s-1\fIXResizeWindow()\fP\s+1, \s-1\fIXRestackWindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XMakeAssoc" "Xlib \- Association Tables" .ds ]W Xlib Reference Manual .SH "Name" .XX "XMakeAssoc" .XX "association tables:creating entries in" .Na XMakeAssoc \(en create an entry in an association table. .Nz .SH "Synopsis" .Sy XMakeAssoc\^(\^\f(CIdisplay\f(CW, \f(CItable\f(CW\^, \f(CIx_id\f(CW\^, \f(CIdata\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XAssocTable *\f(CItable\f(CW\^; XID \f(CIx_id\f(CW\^; char * \f(CIdata\f(CW\^; .Ae .sp -3p .SH "Arguments" .IP \f(CIdisplay\fP .87i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CItable\fP Specifies the association table in which an entry is to be made. .IP \f(CIx_id\fP Specifies the X resource ID. .IP \f(CIdata\fP Specifies the data to be associated with the X resource ID. .sp -2p .SH Description \f(CWXMakeAssoc()\fP inserts data into an \f(CWXAssocTable\fP keyed on an \f(CWXID\fP. Association tables allow you to easily associate data with resource ID's for later retrieval. Association tables are local, accessible only by this client. .LP This function is provided for compatibility with X Version 10. To use it you must include the file .I and link with the library \fI-loldX\fP. .LP Data is inserted into the table only once. Redundant inserts are meaningless and cause no problems. The queue in each association bucket is sorted from the lowest to highest \f(CWXID\fP. .LP For more information, see Volume One, Appendix B, \fIX10 Compatibility\fP. .sp -2p .SH Structure .ft CW .ps 9 .vs 11 .ta 4.5n 2i .nf typedef struct { \f(CWXAssoc\fP *buckets; /* pointer to first bucket in bucket array */ int size; /* table size (number of buckets) */ } \f(CWXAssocTable\fP; .sp -3p typedef struct _XAssoc { struct _XAssoc *next; /* next object in this bucket */ struct _XAssoc *prev; /* previous object in this bucket */ Display *display; /* display which owns the ID */ XID \f(CWx_id\fP; /* X Window System ID */ char *data; /* pointer to untyped memory */ } \f(CWXAssoc\fP; .fi .ft R .ps .vs .sp -2p .SH "See Also" \s-1\fIXCreateAssocTable()\fP\s+1, \s-1\fIXDeleteAssoc()\fP\s+1, \s-1\fIXDestroyAssocTable()\fP\s+1, \s-1\fIXLookUpAssoc()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XMapRaised" "Xlib \- Window Mapping" .ds ]W Xlib Reference Manual .SH "Name" .XX "XMapRaised" .XX "windows:raising" .Na XMapRaised \(en map a window on top of its siblings. .Nz .SH "Synopsis" .Sy XMapRaised\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .87i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the window ID of the window to be mapped and raised. .SH Description \f(CWXMapRaised()\fP marks a window as eligible to be displayed, and positions the window at the top of the stack of its siblings. It will actually be displayed if its ancestors are mapped and it is not obscured by unrelated windows. .XX "XMapWindow:and XMapRaised" \f(CWXMapRaised()\fP is similar to \f(CWXMapWindow()\fP, except it additionally raises the specified window to the top of the stack among its siblings. Mapping an already mapped window with \f(CWXMapRaised()\fP raises the window. See \f(CWXMapWindow()\fP for further details. .LP For more information, see Volume One, Chapter 16, \fIWindow Management\fR. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXMapSubwindows()\fP\s+1, \s-1\fIXMapWindow()\fP\s+1, \s-1\fIXUnmapSubwindows()\fP\s+1, \s-1\fIXUnmapWindow()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XMapSubwindows" "Xlib \- Window Mapping" .ds ]W Xlib Reference Manual .SH "Name" .XX "XMapSubwindows" .XX "windows:mapping subwindows of" .XX "subwindows:mapping" .Na XMapSubwindows \(en map all subwindows of window. .Nz .SH "Synopsis" .Sy XMapSubwindows\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .87i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the ID of the window whose subwindows are to be mapped. .SH Description \f(CWXMapSubwindows()\fP maps all subwindows of a window in top-to-bottom stacking order. \f(CWXMapSubwindows()\fP also generates an \f(CWExpose\fP event on each newly displayed window. This is much more efficient than mapping many windows one at a time, as much of the work need only be performed once for all of the windows rather than for each window. \f(CWXMapSubwindows()\fP is not recursive \- it does not map the subwindows of the subwindows. .LP For more information, see Volume One, Chapter 16, \fIWindow Management\fR. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXMapRaised()\fP\s+1, \s-1\fIXMapWindow()\fP\s+1, \s-1\fIXUnmapSubwindows()\fP\s+1, \s-1\fIXUnmapWindow()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XMapWindow" "Xlib \- Window Mapping" .ds ]W Xlib Reference Manual .SH "Name" .XX "XMapWindow" .XX "windows:mapping" .Na XMapWindow \(en map a window. .Nz .SH "Synopsis" .Sy XMapWindow\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .sp -4p .SH Arguments .IP \f(CIdisplay\f(CW .87i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\f(CW Specifies the ID of the window to be mapped. .SH Description \f(CWXMapWindow()\fP maps a window, making it eligible for display. Whether it becomes visible immediately depends on its stacking order among its siblings, the mapping status of its ancestors, and the placement of other visible windows. If all the ancestors are mapped, and it is not obscured by siblings higher in the stacking order, and it is not obscured by unrelated windows (children of ancestors), then the window and all of its mapped subwindows are displayed. .LP Mapping a window that has an unmapped ancestor does not display the window but marks it as eligible for display when its ancestors become mapped. Mapping an already mapped window has no effect (it does not raise the window). .LP If the window becomes viewable and no earlier contents for it are remembered (because of backing store), the X server tiles the window with its background. If the window's background is undefined, the existing screen contents are not altered, and the X server generates zero or more \f(CWExpose\fP events. If backing-store was maintained while the window was unmapped, no \f(CWExpose\fP events are generated. If backing-store will now be maintained, a full-window exposure is always generated. Otherwise, only visible regions may be reported. Similar tiling and exposure take place for any newly viewable inferiors. .LP Note that for a top-level window, the window manager is likely to intervene and delay the mapping of the window. The application must not draw until it has received an \f(CWExpose\fP event on the window. If the window is an \f(CWInputOutput\fP window, \f(CWXMapWindow()\fP generates \f(CWExpose\fP events on each opaque window that it causes to become displayed. The client should call \f(CWXSelectInput()\fP for exposure events, then map, and then process input events. The client's normal response to an \f(CWExpose\fP event should be to repaint the window. If you fail to wait for the \f(CWExpose\fP event before drawing, the drawing may not appear in the window. .sp -2p .SH "Errors" \f(CWBadWindow\fP .sp -2p .SH "See Also" \s-1\fIXMapRaised()\fP\s+1, \s-1\fIXMapSubwindows()\fP\s+1, \s-1\fIXUnmapSubwindows()\fP\s+1, \s-1\fIXUnmapWindow()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XMaskEvent" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XMaskEvent" .XX "event masks, removing matching" .Na XMaskEvent \(en remove the next event that matches mask. .Nz .SH "Synopsis" .Sy XMaskEvent\^(\^\f(CIdisplay\f(CW, \f(CIevent_mask\f(CW\^, \f(CIevent_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; long \f(CIevent_mask\f(CW\^; XEvent *\f(CIevent_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIevent_mask\fP 1i Specifies the event mask. See \f(CWXSelectInput()\fP for a complete list of the event mask symbols that can be ORed together. .IP \f(CIevent_return\fP 1i Returns the event removed from the event queue. .SH Description \f(CWXMaskEvent()\fP removes the next event in the queue which matches the passed mask. The event is copied into an \f(CWXEvent\fP supplied by the caller. Other events in the queue are not discarded. If no such event has been queued, \f(CWXMaskEvent()\fP flushes the request buffer and waits until one is received. Use \f(CWXCheckMaskEvent()\fP if you do not wish to wait. .LP \f(CWXMaskEvent()\fP cannot return \f(CWClientMessage\fP, \f(CWMappingNotify\fP, \f(CWSelectionClear\fP, \f(CWSelectionNotify\fP, or \f(CWSelectionRequest\fP events because these event types are by definition unmaskable. .SH "See Also" \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXQLength()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XMatchVisualInfo" "Xlib \- Visuals" .ds ]W Xlib Reference Manual .SH "Name" .XX "XMatchVisualInfo" .XX "visuals:returning visual information for" .Na XMatchVisualInfo \(en obtain the visual information that matches the desired depth and class. .Nz .SH "Synopsis" .Sy .nf Status XMatchVisualInfo\^(\^\f(CIdisplay\f(CW, \f(CIscreen\f(CW, \f(CIdepth\f(CW, \f(CIclass\f(CW, \f(CIvinfo_return\f(CW\^) .fi .As Display *\f(CIdisplay\f(CW\^; int \f(CIscreen\f(CW\^; int \f(CIdepth\f(CW\^; int \f(CIclass\f(CW\^; XVisualInfo *\f(CIvinfo_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .85i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIscreen\fP Specifies the screen. .IP \f(CIdepth\fP Specifies the desired depth of the visual. .IP \f(CIclass\fP Specifies the desired class of the visual, such as \f(CWPseudoColor\fP or \f(CWTrueColor\fP. .IP \f(CIvinfo_return\fP Returns the matched visual information. .SH Returns Zero on failure, non-zero on success. .SH Description \f(CWXMatchVisualInfo()\fP returns the visual information for a visual supported on the screen that matches the specified \f(CIdepth\fP and \f(CIclass\fP. Because multiple visuals that match the specified \f(CIdepth\fP and \f(CIclass\fP may be supported, the exact visual chosen is undefined. .LP If a visual is found, this function returns a non-zero value and the information on the visual is returned to \f(CIvinfo_return\fP. If a visual is not found, it returns zero. .LP For more information on visuals, see Volume One, Chapter 7, \fIColor\fR. .SH "Structures" .Ps typedef struct { Visual *visual; VisualID visualid; int screen; unsigned int depth; int class; unsigned long red_mask; unsigned long green_mask; unsigned long blue_mask; .ne 8 int colormap_size; int bits_per_rgb; } XVisualInfo; .XX "XVisualInfo structure" .XX "structures:XVisualInfo" .Pe .SH "See Also" \s-1\fIXDefaultVisual()\fP\s+1, \s-1\fIXGetVisualInfo()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XMaxCmapsOfScreen" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XMaxCmapsOfScreen, MaxCmapsOfScreen \(en get maximum number of installed colormaps supported by a screen. .XX "XMaxCmapsOfScreen" .Nz .\" .\" .SH "Synopsis" .Sy int XMaxCmapsOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIscreen\fP 1i Specifies the appropriate \f(CWScreen\fP structure. .\" .\" .SH Returns The maximum number of colormaps. .SH Description .XX "colormaps:returning maximum number of installed" \f(CWXMaxCmapsOfScreen()\fP returns the maximum number of installed colormaps supported by the specified screen. .LP .XX "MaxCmapsOfScreen macro" The C language macro \f(CWMaxCmapsOfScreen()\fP is equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXInstallColormap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XMaxRequestSize" "Xlib \- Drawing Primitives" .ds ]W Xlib Reference Manual .SH "Name" .Na XMaxRequestSize \(en get maximum request size supported by server. .XX "XMaxRequestSize" .Nz .\" .\" .SH "Synopsis" .Sy long XMaxRequestSize(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" .\" .SH Returns The maximum request size in 4-byte units. .SH Description .XX "requests:returning maximum size of" \f(CWXMaxRequestSize()\fP returns the maximum request size (in 4-byte units) supported by the server. Single protocol requests to the server can be no longer than this size. The protocol guarantees the size to be no smaller than 4096 units (16384 bytes). Xlib automatically breaks data up into multiple protocol requests as necessary for the following functions: \f(CWXDrawPoints()\fP, \f(CWXDrawRectangles()\fP, \f(CWXDrawSegments()\fP, \f(CWXFillArcs()\fP, \f(CWXFillRectangles()\fP, and \f(CWXPutImage()\fP. Xlib does not break up data for \f(CWXDrawArcs()\fP, \f(CWXDrawLines()\fP, or \f(CWXFillPolygon()\fP. .LP There is no macro \f(CWMaxRequestSize()\fP. .\" .\" .SH "See Also" \s-1\fIXDrawArcs()\fP\s+1, \s-1\fIXDrawLines()\fP\s+1, \s-1\fIXFillPolygon()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XMinCmapsOfScreen" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XMinCmapsOfScreen, MinCmapsOfScreen \(en get minimum number of installed colormaps supported by a screen. .XX "XMinCmapsOfScreen" .Nz .\" .\" .SH "Synopsis" .Sy int XMinCmapsOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIscreen\fP 1i Specifies the appropriate \f(CWScreen\fP structure. .\" .\" .SH Returns The minimum number of colormaps. .SH Description .XX "colormaps:returning maximum number of installed" \f(CWXMinCmapsOfScreen()\fP returns the minimum number of installed colormaps supported by the specified screen. .LP The C language macro \f(CWMinCmapsOfScreen()\fP is equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXInstallColormap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XMoveResizeWindow" "Xlib \- Window Manipulation" .ds ]W Xlib Reference Manual .SH "Name" .XX "XMoveResizeWindow" .XX "windows:changing size and position of" .Na XMoveResizeWindow \(en change the size and position of a window. .Nz .SH "Synopsis" .Sy XMoveResizeWindow\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .87i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the ID of the window to be reconfigured. .IP \f(CIx\fP .br .ns .IP \f(CIy\fP .sp -2 Specify the new x and y coordinates of the upper-left pixel of the window's border, relative to the window's parent. .IP \f(CIwidth\fP .br .ns .IP \f(CIheight\fP .sp -2 Specify the new width and height in pixels. These arguments define the interior size of the window. .SH Description \f(CWXMoveResizeWindow()\fP moves or resizes a window or both. \f(CWXMoveResizeWindow()\fP does not raise the window. Resizing a mapped window may lose its contents and generate an \f(CWExpose\fP event on that window depending on the \f(CWbit_gravity\fP attribute. Configuring a window may generate exposure events on windows that the window formerly obscured, depending on the new size and location parameters. .LP If the \f(CWoverride_redirect\fP attribute of the window is \f(CWFalse\fP (see Volume One, Chapter 4, \fIWindow Attributes\fR) and the window manager has selected \f(CWSubstructureRedirectMask\fP on the parent, then a \f(CWConfigureRequest\fP event is sent to the window manager, and no further processing is performed. .LP If a client has selected \f(CWStructureNotifyMask\fP on the window, then a \f(CWConfigureNotify\fP event is generated after the move and resize takes place, and the event will contain the final position and size of the window. This is only useful in the case of top-level windows, since the window manager may modify or prevent them being moved or resized. .SH "Errors" \f(CWBadValue\fP .br \f(CWBadWindow\fP .Nd 5 .SH "See Also" \s-1\fIXCirculateSubwindows()\fP\s+1, \s-1\fIXCirculateSubwindowsDown()\fP\s+1, \s-1\fIXCirculateSubwindowsUp()\fP\s+1, \s-1\fIXConfigureWindow()\fP\s+1, \s-1\fIXLowerWindow()\fP\s+1, \s-1\fIXMoveWindow()\fP\s+1, \s-1\fIXQueryTree()\fP\s+1, \s-1\fIXRaiseWindow()\fP\s+1, \s-1\fIXReparentWindow()\fP\s+1, \s-1\fIXResizeWindow()\fP\s+1, \s-1\fIXRestackWindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XMoveWindow" "Xlib \- Window Manipulation" .ds ]W Xlib Reference Manual .SH "Name" .XX "XMoveWindow" .XX "windows:moving" .Na XMoveWindow \(en move a window. .Nz .SH "Synopsis" .Sy XMoveWindow\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .87i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the ID of the window to be moved. .IP \f(CIx\fP .br .ns .IP \f(CIy\fP .sp -2 Specify the new x and y coordinates of the upper-left pixel of the window's border (or of the window itself, if it has no border), relative to the window's parent. .SH Description \f(CWXMoveWindow()\fP changes the position of the origin of the specified window relative to its parent. \f(CWXMoveWindow()\fP does not change the mapping state, size, or stacking order of the window, nor does it raise the window. Moving a mapped window will lose its contents if: .IP \(bu 3n Its \f(CWbackground_pixmap\fP attribute is \f(CWParentRelative\fP. .IP \(bu 3n The window is obscured by nonchildren and no backing store exists. .LP If the contents are lost, exposure events will be generated for the window and any mapped subwindows. Moving a mapped window will generate exposure events on any formerly obscured windows. .LP If the \f(CWoverride_redirect\fP attribute of the window is \f(CWFalse\fP (see Volume One, Chapter\ 4, \fIWindow Attributes\fR) and the window manager has selected \f(CWSubstructureRedirectMask\fP on the parent, then a \f(CWConfigureRequest\fP event is sent to the window manager, and no further processing is performed. .LP .XX "StructureNotifyMask:and moving windows" If a client has selected \f(CWStructureNotifyMask\fP on the window, then a \f(CWConfigureNotify\fP event is generated after the move takes place, and the event will contain the final position of the window. This is only useful in the case of top-level windows, since the window manager may modify or disallow moves. .SH "Errors" \f(CWBadWindow\fP .Nd 5 .SH "See Also" \s-1\fIXCirculateSubwindows()\fP\s+1, \s-1\fIXCirculateSubwindowsDown()\fP\s+1, \s-1\fIXCirculateSubwindowsUp()\fP\s+1, \s-1\fIXConfigureWindow()\fP\s+1, \s-1\fIXLowerWindow()\fP\s+1, \s-1\fIXMoveResizeWindow()\fP\s+1, \s-1\fIXQueryTree()\fP\s+1, \s-1\fIXRaiseWindow()\fP\s+1, \s-1\fIXReparentWindow()\fP\s+1, \s-1\fIXResizeWindow()\fP\s+1, \s-1\fIXRestackWindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XNewModifiermap" "Xlib \- Keyboard" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XNewModifiermap" .XX "keyboard modifier mapping structure:creating" XNewModifiermap \(en create a keyboard modifier mapping structure. .Nz .SH "Synopsis" .Sy XModifierKeymap *XNewModifiermap(\^\f(CImax_keys_per_mod\f(CW\^) .As int \f(CImax_keys_per_mod\f(CW\^; .Ae .SH "Arguments" .IP \f(CImax_keys_per_mod\fP .5i Specifies the maximum number of keycodes assigned to any of the modifiers in the map. .SH Returns The created modifier map structure. .SH Description .XX "XModifierKeymap structure" \f(CWXNewModifiermap()\fP allocates space for an \f(CWXModifierKeymap()\fP structure, sets its fields, and returns a pointer to the structure. .LP This function is used when more than one \f(CWXModifierKeymap()\fP structure is needed. \f(CImax_keys_per_mod\fP depends on the server and should be gotten from the \f(CWXModifierKeymap()\fP structure returned by \f(CWXGetModifierMapping()\fP. .LP For more information on keyboard preferences, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "Structures" .Ps typedef struct { int max_keypermod; /* server's max number of keys per modifier */ KeyCode *modifiermap; /* An 8 by \f(CImax_keypermod\fP array of the modifiers */ } XModifierKeymap; .Pe .SH "See Also" \s-1\fIXChangeKeyboardMapping()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeysym()\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XNextEvent" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XNextEvent" .Na XNextEvent \(en get the next event of any type or window. .XX "events:obtaining next" .Nz .SH "Synopsis" .Sy XNextEvent\^(\^\f(CIdisplay\f(CW, \f(CIevent_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XEvent *\f(CIevent_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIevent_return\fP 1i Returns the event removed from the event queue. .SH Description \f(CWXNextEvent()\fP removes an event from the head of the event queue and copies it into an \f(CWXEvent\fP structure supplied by the caller. If the event queue is empty, \f(CWXNextEvent()\fP flushes the request buffer and waits (blocks) until an event is received. Use \f(CWXCheckMaskEvent()\fP or \f(CWXCheckIfEvent()\fP if you do not want to wait. .LP For more information, see Volume One, Chapter 8, \fIEvents\fR. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XNextRequest" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XNextRequest, NextRequest \(en return serial number of next request. .XX "XNextRequest" .Nz .\" .\" .SH "Synopsis" .Sy unsigned long XNextRequest\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" .\" .SH Returns The serial number. .SH Description .XX "requests:getting full serial number of" \f(CWXNextRequest()\fP extracts the full serial number that Xlib will use for the next request. Serial numbers are maintained separately for each display connection. .LP .XX "NextRequest macro" The C language macro \f(CWNextRequest()\fP is equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXLastKnownRequestProcessed()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XNoOp" "Xlib \- HouseKeeping" .ds ]W Xlib Reference Manual .SH "Name" .XX "XNoOp" .Na XNoOp \(en send a NoOp to exercise connection with the server. .Nz .SH "Synopsis" .Sy XNoOp\^(\^\f(CIdisplay\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Description .XX "NoOperation request" \f(CWXNoOp()\fP sends a \f(CWNoOperation\fP request to the X server, thereby exercising the connection. This request can be used to measure the response time of the network connection. \f(CWXNoOp()\fP does not flush the request buffer. .SH "See Also" \s-1\fIXDefaultScreen()\fP\s+1, \s-1\fIXCloseDisplay()\fP\s+1, \s-1\fIXFree()\fP\s+1, \s-1\fIXOpenDisplay()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XOffsetRegion" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XOffsetRegion" .XX "regions:changing offsets of" .Na XOffsetRegion \(en change offset of a region. .Nz .SH "Synopsis" .Sy XOffsetRegion\^(\^\f(CIr\f(CW\^, \f(CIdx\f(CW\^, \f(CIdy\f(CW\^) .As Region \f(CIr\f(CW\^; int \f(CIdx\f(CW\^, \f(CIdy\f(CW\^; .Ae .SH "Arguments" .IP \f(CIr\fP .7i Specifies the region. .IP \f(CIdx\fP .br .ns .IP \f(CIdy\fP .sp -2 Specify the amount to move the specified region relative to the origin of all regions. .SH Description .XX "offsets:of regions, changing" \f(CWXOffsetRegion()\fP changes the offset of the region the specified amounts in the x and y directions. .LP Regions are located using an offset from a point (the \fIregion origin\fP) which is common to all regions. It is up to the application to interpret the location of the region relative to a drawable. If the region is to be used as a \f(CWclip_mask\fP by calling \f(CWXSetRegion()\fP, the upper-left corner of the region relative to the drawable used in the graphics request will be at \f(CW(xoffset + clip_x_origin, yoffset + clip_y_origin)\fP, where \f(CWxoffset\fP and \f(CWyoffset\fP are the offset of the region and \f(CWclip_x_origin\fP and \f(CWclip_y_origin\fP are components of the GC used in the graphics request. .SH "Structures" \f(CWRegion\fP is a pointer to an opaque structure type. .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXCreateRegion()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XOpenDev.man,v 1.5 94/06/04 17:32:31 rws Exp $ .ds xL Programming with Xlib .TH XOpenDevice 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XOpenDevice, XCloseDevice \- open or close an extension input device .SH SYNTAX \fB .nf XDevice *XOpenDevice\^(\^\fIdisplay\fP, \fIdevice_id\fP\^) Display *\fIdisplay\fP\^; XID \fIdevice_id\fP\^; XCloseDevice\^(\^\fIdisplay\fP, \fIdevice\fP\^) Display *\fIdisplay\fP\^; XDevice *\fIdevice\fP\^; .fi \fP .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device_id Specifies the id of the device to be opened .TP 12 .I device Specifies the device to be closed .SH DESCRIPTION The \fIXOpenDevice\fP request makes an input device accessible to a client through input extension protocol requests. If successful, it returns a pointer to an \fBXDevice\fP structure. .LP The \fIXCloseDevice\fP request makes an input device inaccessible to a client through input extension protocol requests. Before terminating, and client that has opened input devices through the input extension should close them via \fICloseDevice\fP. .LP When a client makes an \fIXCloseDevice\fP request, any active grabs that the client has on the device are released. Any event selections that the client has are deleted, as well as any passive grabs. If the requesting client is the last client accessing the device, the server may disable all access by X to the device. .LP \fIXOpenDevice\fP and \fIXCloseDevice\fP can generate a \fIBadDevice\fP error. .SH STRUCTURES The \fIXDevice\fP structure returned by \fIXOpenDevice\fP contains: .nf typedef struct { XID device_id; int num_classes; XInputClassInfo *classes; } XDevice; .fi .LP The classes field is a pointer to an array of XInputClassInfo structures. Each element of this array contains an event type base for a class of input supported by the specified device. The num_classes field indicates the number of elements in the classes array. .LP The \fIXInputClassInfo\fP structure contains: .LP .nf typedef struct { unsigned char input_class; unsigned char event_type_base; } XInputClassInfo; .fi .LP The input_class field identifies one class of input supported by the device. Defined types include \fIKeyClass\fP, \fIButtonClass\fP, \fIValuatorClass\fP, \fIProximityClass\fP, \fIFeedbackClass\fP, \fIFocusClass\fP, and \fIOtherClass\fP. The event_type_base identifies the event type of the first event in that class. .LP The information contained in the \fIXInputClassInfo\fP structure is used by macros to obtain the event classes that clients use in making \fIXSelectExtensionEvent\fP requests. Currently defined macros include \fIDeviceKeyPress\fP, \fIDeviceKeyRelease\fP, \fIDeviceButtonPress\fP, \fIDeviceButtonRelese\fP, \fIDeviceMotionNotify\fP, \fIDeviceFocusIn\fP, \fIDeviceFocusOut\fP, \fIProximityIn\fP, \fIProximityOut\fP, \fIDeviceStateNotify\fP, \fIDeviceMappiingNotify\fP, \fIChangeDeviceNotify\fP, \fIDevicePointerMotionHint\fP, \fIDeviceButton1Motion\fP, \fIDeviceButton2Motion\fP, \fIDeviceButton3Motion\fP, \fIDeviceButton4Motion\fP, \fIDeviceButton5Motion\fP, \fIDeviceButtonMotion\fP, \fIDeviceOwnerGrabButton\fP, \fIDeviceButtonPressGrab\fP, and \fINoExtensionEvent\fP. .LP To obtain the proper event class for a particular device, one of the above macros is invoked using the \fIXDevice\fP structure for that device. For example, .LP .nf DeviceKeyPress (*device, type, eventclass); .fi .LP returns the \fIDeviceKeyPress\fP event type and the eventclass for \fIDeviceKeyPress\fP events from the specified device. .LP This \fIeventclass\fP can then be used in an \fIXSelectExtensionEvent\fP request to ask the server to send \fIDeviceKeyPress\fP events from this device. When a selected event is received via \fIXNextEvent\fP, the \fItype\fP can be used for comparison with the type in the event. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist, or is the X keyboard or X pointer. This error may also occur if some other client has caused the specified device to become the X keyboard or X pointer device via the \fIXChangeKeyboardDevice\fP or \fIXChangePointerDevice\fP requests. .SH "SEE ALSO" .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XOpenDisplay" "Xlib \- HouseKeeping" .ds ]W Xlib Reference Manual .SH "Name" .XX "XOpenDisplay" .XX "displays:opening" .Na XOpenDisplay \(en connect a client program to an X server. .Nz .SH "Synopsis" .ta 4.5n 2.5i .na .ft CW Display *XOpenDisplay\^(\^\f(CIdisplay_name\f(CW\^) .As char *\f(CIdisplay_name\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay_name\fP 1.5i Specifies the display name, which determines the server to connect to and the communications domain to be used. See Description below. .SH Returns The display structure. .SH Description .XX "client:connecting to server" .XX "servers:connecting clients to" The \f(CWXOpenDisplay()\fP routine connects the client to the server controlling the hardware display through TCP or DECnet communication protocols, or through some local inter-process communication protocol. .LP On a POSIX-conformant system, if \f(CIdisplay_name\fP is \f(CWNULL\fP, the value defaults to the contents of the DISPLAY environment variable on POSIX-based systems. On non-UNIX-based systems, see that operating system's Xlib manual for the default \f(CIdisplay_name\fP. The encoding and interpretation of the display name is implementation-dependent. Strings in the Host Portable Character Encoding are supported; support for other characters is implementation-dependent. The \f(CIdisplay_name\fP or DISPLAY environment variable is a string that has the format \f(CIhostname\fP\^:\^\f(CIserver\fP\ or \f(CIhostname\fP\^:\^\f(CIserver\fP\^.\^\f(CIscreen\fR. For example, \f(CWfrog:0.2\fR would specify screen \f(CW2\fP of server \f(CW0\fP on the machine \f(CWfrog\fP. .LP .IP \f(CIhostname\fP 12 Specifies the name of the host machine on which the display is physically connected. You follow the hostname with either a single colon (:) or a double colon (::), which determines the communications domain to use. Any or all of the communication protocols can be used simultaneously on a server built to support them (but only one per client). .RS .IP \(bu 3n If \f(CIhostname\fP is a host machine name and a single colon (:) separates the hostname and display number, \f(CWXOpenDisplay()\fP connects to the server using TCP streams. If the hostname is not specified, Xlib uses what it believes is the fastest transport. .IP \(bu 3n If \f(CIhostname\fP is a host machine name and a double colon (::) separates the hostname and display number, \f(CWXOpenDisplay()\fP connects with the server using DECnet streams. To use DECnet, however, you must build all software for DECnet. .ne 2 A single X server can accept both TCP and DECnet connections if it has been built for DECnet. .IP \(bu 3n Note that support for use of the string "unix" in a display name is no longer part of the Xlib specification as of Release 4. .RE .IP \f(CIserver\fP 12 Specifies the number of the server on its host machine. This display number may be followed by a period (.). A single CPU can have more than one display; the displays are numbered starting from 0. .br .ne 6 .IP \f(CIscreen\fP 12 Specifies the number of the default screen on \f(CIserver\fP. Multiple screens can be connected to (controlled by) a single X server, but they are used as a single display by a single user. \f(CIscreen\fP merely sets an internal variable that is returned by the \f(CWDefaultScreen()\fP macro. If \f(CIscreen\fP is omitted, it defaults to 0. .LP If successful, \f(CWXOpenDisplay()\fP returns a pointer to a \f(CWDisplay\fP. .ne 2 This structure provides many of the specifications of the server and its screens. If \f(CWXOpenDisplay()\fP does not succeed, it returns \f(CWNULL\fP. .LP After a successful call to \f(CWXOpenDisplay()\fP, all of the screens on the server may be used by the application. The screen number specified in the \f(CIdisplay_name\fP argument serves only to specify the value that will be returned by the \f(CWDefaultScreen()\fP macro. After opening the display, you can use the \f(CWScreenCount()\fP macro to determine how many screens are available. Then you can reference each screen with integer values between 0 and the value returned by (\f(CWScreenCount()\fP -1). You can access elements of the \f(CWDisplay\fP and \f(CWScreen\fP structures only using the information macros and functions listed in Appendix C, \fIMacros\fR. .LP For more information, see Volume One, Chapter 2, \fIX Concepts\fP, and Chapter 3, \fIBasic Window Program\fR. .SH "See Also" \s-1\fIXDefaultScreen()\fP\s+1, \s-1\fIXCloseDisplay()\fP\s+1, \s-1\fIXFree()\fP\s+1, \s-1\fIXNoOp()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XOpenIM" "Xlib \- Input Methods" .ds ]W Xlib Reference Manual .XX "XOpenIM" .XX "input methods:opening" .SH Name .Na XOpenIM \(en open input method. .Nz .SH Synopsis .Sy XIM XOpenIM\^(\^\f(CIdisplay\fP\^, \f(CIdb\fP\^, \f(CIres_name\fP\^, \f(CIres_class\fP\^) .As Display *\f(CIdisplay\fP\^; XrmDatabase \f(CIdb\fP\^; char *\f(CIres_name\fP\^; char *\f(CIres_class\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIdb\fP 1i Specifies the resource database. .IP \f(CIres_name\fP 1i Specifies the full resource name of the application. .IP \f(CIres_class\fP 1i Specifies the full class name of the application. .SH Returns The input method ID. .SH Availability Release 5 and later. .SH Description \f(CWXOpenIM()\fR opens an input method. The current locale and modifiers are bound to the input method when it is opened. The locale associated with an input method cannot be changed dynamically. This implies the strings returned by \f(CWXmbLookupString()\fR or \f(CWXwcLookupString()\fR, for any input context affiliated with a given input method, will be encoded in the locale that was current at the time the input method was opened. .LP The specific input method to which this call will be routed is identified on the basis of the current locale. \f(CWXOpenIM()\fR will identify a default input method corresponding to the current locale. That default can be modified using \f(CWXSetLocaleModifiers()\fR with the input method ("im") modifier. .LP The db argument is the resource database to be used by the input method for looking up resources that are private to the input method. It is not intended that this database be used to look up values that can be set as IC values in an input context. If db is \f(CWNULL\fP, no data base is passed to the input method. .LP The \f(CIres_name\fP and \f(CIres_class\fP arguments specify the resource name and class of the application. They are intended to be used as prefixes by the input method when looking up resources that are common to all input contexts that may be created for this input method. The characters used for resource names and classes must be in the X portable character set. The resources looked up are not fully specified if \f(CIres_name\fP or \f(CIres_class\fP is \f(CWNULL\fP. .LP The \f(CIres_name\fP and \f(CIres_class\fP arguments are not assumed to exist beyond the call to \f(CWXOpenIM()\fR. The specified resource database is assumed to exist for the lifetime of the input method. .LP \f(CWXOpenIM()\fR returns \f(CWNULL\fP if no input method could be opened. .SH "See Also" \s-1\fIXCloseIM()\fP\s+1, \s-1\fIXGetIMValues()\fP\s+1, \s-1\fIXDisplayOfIM()\fP\s+1, \s-1\fIXLocaleOfIM()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XParseColor" "Xlib \- Color Cells" .ds ]W Xlib Reference Manual .SH "Name" .XX "XParseColor" .XX "device-independent color" .Na XParseColor \(en look up RGB values from ASCII color name or translate hexadecimal value. .Nz .SH "Synopsis" .Sy Status XParseColor\^(\^\f(CIdisplay\f(CW, \f(CIcolormap\f(CW\^, \^\f(CIspec\f(CW\^, \f(CIexact_def_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcolormap\f(CW\^; char *\f(CIspec\f(CW\^; XColor *\f(CIexact_def_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcolormap\fP 1i Specifies a colormap associated with the screen on which to look up the color. This argument is required, but is meaningful only with Xcms color specifications. .IP \f(CIspec\fP 1i Specifies the color string (see the "Description" section). Uppercase or lowercase does not matter. If the color name is not in the Host Portable Character Encoding, the result is implementation-dependent. .IP \f(CIexact_def_return\fP 1i Returns the RGB values corresponding to the specified color name or hexadecimal specification, and sets its \f(CWDoRed\fP, \f(CWDoGreen\fP, and \f(CWDoBlue\fP flags. .SH "Returns" Zero on failure, non-zero on success. .SH Description \f(CWXParseColor()\fP looks up the string name of a color with respect to the screen associated with the specified colormap. It returns the exact color value. It or hexadecimal values specified, or translating the hexadecimal code into separate RGB values. .LP \f(CWXParseColor()\fP takes a string specification of a color, typically from a user-specified command line or resource value, and returns the corresponding red, green, and blue values, suitable for a subsequent call to \f(CWXAllocColor\fP or \f(CWXStoreColor()\fP. \f(CIspec\fP can be given in several forms, and may be looked up in different ways depending on the form. .IP \(bu 3n Color name, such as "blue". This form is looked up in the server's RGB database, a sample of which is listed in Appendix D, \fIThe Server-side Color Database\fR. .IP \(bu 3n Xcms color name, such as TekHVC:0.0/100.0/0.0. This form is looked up in the client-side database for the screen associated with the specified colormap. This form is supported starting in Release 5. For more information on this form of color specification, see the \fIProgrammer's Supplement for Release 5\fR, or the Third Edition of Volume One. .Nd 8 .IP \(bu 3n Hexadecimal specification such as #3a7. This form consists of an initial sharp sign character followed by one of the following formats: .sp .ta 10n 27n .nf .ft CW .ps 8 .vs 10 #RGB \fR\s+2(one character per color)\fP\s-2 #RRGGBB \fR\s+2(two characters per color)\fP\s-2 #RRRGGGBBB \fR\s+2(three characters per color)\fP\s-2 #RRRRGGGGBBBB \fR\s+2(four characters per color)\fP\s-2 .sp .75 .ps .vs .fi .ft R where R, G, and B represent single hexadecimal digits (uppercase or lowercase). The hexadecimal strings must be \f(CWNULL\fP-terminated so that \f(CWXParseColor()\fP knows when it has reached the end. When fewer than 16 bits each are specified, they represent the most significant bits of the value. For example, \f(CW#3a7\fP is the same as \f(CW#3000a0007000\fP. The hexadecimal style is discouraged in Release 5 and later. .LP \f(CWStatus\fR is zero on failure, non-zero on success. This routine will fail if the initial character is a sharp sign but the string otherwise fails to fit one of the above formats, or if the initial character is not a sharp sign and the named color does not exist in the server's database. .LP For more information, see Volume One, Chapter 7, \fIColor\fR and in the Third Edition, the chapter on Device-Independent Color. .SH "Structures" .Ps typedef struct { unsigned long pixel; unsigned short red, green, blue; char flags; /* DoRed, DoGreen, DoBlue */ char pad; } XColor; .Pe .SH "Errors" .IP "\f(CWBadColor\fP" 1i Invalid colormap. .SH "See Also" \s-1\fIXBlackPixel()\fP\s+1, \s-1\fIXWhitePixel()\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXcmsAllocColor()\fP\s+1, \s-1\fIXAllocColorCells()\fP\s+1, \s-1\fIXAllocColorPlanes()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXcmsAllocNamedColor()\fP\s+1, \s-1\fIXFreeColors()\fP\s+1, \s-1\fIXLookupColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXcmsStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1, \s-1\fIXcmsStoreColors()\fP\s+1, \s-1\fIXStoreNamedColor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XParseGeometry" "Xlib \- Standard Geometry" .ds ]W Xlib Reference Manual .SH "Name" .XX "XParseGeometry" .Na XParseGeometry \(en generate position and size from standard window geometry string. .Nz .SH "Synopsis" .Sy int XParseGeometry\^(\^\f(CIparsestring\f(CW\^, \f(CIx_return\f(CW\^, \f(CIy_return\f(CW\^, \f(CIwidth_return\f(CW\^, \f(CIheight_return\f(CW\^) .As char *\f(CIparsestring\f(CW\^; int *\f(CIx_return\f(CW\^, *\f(CIy_return\f(CW\^; unsigned int *\f(CIwidth_return\f(CW\^, *\f(CIheight_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIparsestring\fP 1.2i Specifies the string you want to parse. .IP \f(CIx_return\fP .br .ns .IP \f(CIy_return\fP Return the x and y coordinates (offsets) from the string. .sp .IP \f(CIwidth_return\fP .br .ns .IP \f(CIheight_return\fP .sp -2 Return the width and height in pixels from the string. .sp .SH Returns A bit mask composed of the OR of the symbols \f(CWXValue\fP, \f(CWYValue\fP, \f(CWWidthValue\fP, \f(CWHeightValue\fP, \f(CWXNegative\fP, and/or \f(CWYNegative\fP. .SH Description .XX "windows:parsing standard geometry string" .XX "geometry:standard window strings" By convention, X applications provide a geometry command-line option to indicate window size and placement. \f(CWXParseGeometry()\fP makes it easy to conform to this standard because it allows you to parse the standard window geometry string. Specifically, this function lets you parse strings of the form: .LP .ti 4.5n \s9\f(CW=<\f(CIwidth_return\fP>x<\f(CIheight_return\fP>{+-}<\f(CIxoffset\fP>{+-}<\f(CIyoffset\fP>\fP\s0 .LP The items in this string map into the arguments associated with this function. (Items enclosed in <\^> are integers and items enclosed in {\^} are a set from which one item is allowed. Note that the brackets should not appear in the actual string.) If the string is not in the Host Portable Character Encoding, the result is implementation-dependent. .LP \f(CWXParseGeometry()\fP returns a bitmask that indicates which of the four values (\f(CIwidth_return\fP, \f(CIheight_return\fP, \f(CIxoffset\fP, and \f(CIyoffset\fP) were actually found in the string, and whether the \f(CIx\fP and \f(CIy\fP values are negative. The bits are represented by these constants: \f(CWXValue\fP, \f(CWYValue\fP, \f(CWWidthValue\fP, \f(CWHeightValue\fP, \f(CWXNegative\fP, and \f(CWYNegative\fP, and are defined in \fI\fR. For each value found, the corresponding argument is updated and the corresponding bitmask element set; for each value not found, the argument is left unchanged, and the bitmask element is not set. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .ne 4 .SH "See Also" \s-1\fIXGeometry\fP\s+1, \s-1\fIXTranslateCoordinates()\fP\s+1, \s-1\fIXWMGeometry\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XPeekEvent" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XPeekEvent" .XX "events:obtaining without removing from queue" .Na XPeekEvent \(en get an event without removing it from the queue. .Nz .SH "Synopsis" .Sy XPeekEvent\^(\^\f(CIdisplay\f(CW, \f(CIevent_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XEvent *\f(CIevent_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIreport_return\fP 1i Returns the event peeked from the input queue. .SH Description \f(CWXPeekEvent()\fP peeks at an input event from the head of the event queue and copies it into an \f(CWXEvent\fP supplied by the caller, without removing it from the input queue. If the queue is empty, \f(CWXPeekEvent()\fP flushes the request buffer and waits (blocks) until an event is received. If you do not want to wait, use the \f(CWQLength()\fP macro or \f(CWXQLength()\fP to determine if there are any events to peek at, or use \f(CWXCheckIfEvent()\fP. .XX "XEventsQueued" \&\f(CWXEventsQueued()\fP can perform the equivalent of either \f(CWQLength()\fP or \f(CWXPending()\fP and more. .LP For more information, see Volume One, Chapter 8, \fIEvents\fR. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XPeekIfEvent" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XPeekIfEvent" .XX "events:obtaining without removing from queue" .Na XPeekIfEvent \(en get an event matched by predicate procedure without removing it from the queue. .Nz .SH "Synopsis" .Sy XPeekIfEvent\^(\^\f(CIdisplay\f(CW, \f(CIevent_return\f(CW, \f(CIpredicate\f(CW, \f(CIarg\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XEvent *\f(CIevent_return\f(CW\^; Bool (\^*\f(CIpredicate\f(CW\^)\^(\^)\^; XPointer \f(CIarg\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIevent_return\fP 1i Returns a copy of the matched event. .IP \f(CIpredicate\fP 1i Specifies the procedure to be called to determine if each event that arrives in the queue is the desired one. .IP \f(CIarg\fP 1i Specifies the user-specified argument that will be passed to the predicate procedure. .SH Description .XX "predicate procedures:and events" \f(CWXPeekIfEvent()\fP returns an event only when the specified predicate procedure returns \f(CWTrue\fP for the event. The event is copied into \f(CIevent_return\fP but not removed from the queue. The specified predicate is called each time an event is added to the queue, with the arguments \&\f(CIdisplay\fP, \&\f(CIevent_return\fP, and \&\f(CIarg\fP. .LP \f(CWXPeekIfEvent()\fP flushes the request buffer if no matching events could be found on the queue, and then waits for the next matching event. .LP For more information, see Volume One, Chapter 8, \fIEvents\fR. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XPending" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XPending" .XX "events:pending" .Na XPending \(en return the number of pending events. .Nz .SH "Synopsis" .Sy int XPending\^(\^\f(CIdisplay\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Returns The number of events. .SH Description \f(CWXPending()\fP returns the number of events that have been received by Xlib from the server, but not yet removed from the queue. If there are no events on the queue, \f(CWXPending()\fP flushes the request buffer, and returns the number of events transferred to the input queue as a result of the flush. .LP The \f(CWQLength\fP macro or \f(CWXQLength()\fP returns the number of events on the queue, but without flushing the request buffer first. .LP For more information, see Volume One, Chapter 8, \fIEvents\fR. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XPlanesOfScreen" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XPlanesOfScreen, PlanesOfScreen \(en return the depth of a root window. .XX "XPlanesOfScreen" .Nz .\" .\" .SH "Synopsis" .Sy int XPlanesOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIscreen\fP 1i Specifies the appropriate \f(CWScreen\fP structure. .\" .\" .SH Returns The number of planes. .SH Description .XX "screens:depth of root window, returning" \f(CWXPlanesOfScreen()\fP returns the depth of the root window of the specified screen. .LP .XX "PlanesOfScreen macro" The C language macro \f(CWPlanesOfScreen()\fP is equivalent and slightly more efficient. .LP \f(CWXPlanesOfScreen()\fP and \f(CWXDisplayPlanes()\fP are equivalent except that they take different arguments. .\" .\" .SH "See Also" \s-1\fIXDisplayPlanes()\fP\s+1, \s-1\fIXDefaultDepth*()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XPointInRegion" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XPointInRegion" .XX "points:determining if in region" .XX "regions:determining if points are in" .Na XPointInRegion \(en determine if a point is inside a region. .Nz .SH "Synopsis" .Sy Bool XPointInRegion\^(\^\f(CIr\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^) .As Region \f(CIr\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; .Ae .SH "Arguments" .IP \f(CIr\fP 1i Specifies the region. .IP \f(CIx\fP 1i Specify the x and y coordinates of the point relative to the region's origin. .br .ns .IP \f(CIy\fP 1i .SH Returns \f(CWTrue\fP if the point is inside the region, else \f(CWFalse\fP. .SH Description \f(CWXPointInRegion()\fP returns \f(CWTrue\fP if the point \f(CIx\fP, \f(CIy\fP is contained in the region \f(CIr\fP. A point exactly on the boundary of the region is considered inside the region. .LP Regions are located using an offset from a point (the \fIregion origin\fP) which is common to all regions. It is up to the application to interpret the location of the region relative to a drawable. .LP For more information on regions, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" \f(CWRegion\fP is a pointer to an opaque structure type. .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXCreateRegion()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XPolygonRegion" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .Na XPolygonRegion \(en generate a region from points in a polygon. .Nz .XX "XPolygonRegion" .XX "regions:generating from points in a polygon" .SH "Synopsis" .Sy Region XPolygonRegion\^(\^\f(CIpoints\f(CW\^, \f(CIn\f(CW\^, \f(CIfill_rule\f(CW\^) .As XPoint \f(CIpoints[]\f(CW\^; int \f(CIn\f(CW\^; int \f(CIfill_rule\f(CW\^; .Ae .SH "Arguments" .IP \f(CIpoints\fP 1i Specifies a pointer to an array of points. .IP \f(CIn\fP 1i Specifies the number of points in the polygon. .IP \f(CIfill_rule\fP 1i Specifies whether areas overlapping an odd number of times should be part of the region (\f(CWWindingRule\fP) or not part of the region (\f(CWEvenOddRule\fP). See Volume One, Chapter 5, \fIThe Graphics Context\fP, for a description of the fill rule. .SH Returns The created region. .SH Description \f(CWXPolygonRegion()\fP creates a region defined by connecting the specified points, and returns a pointer to be used to refer to the region. .LP Regions are located relative to a point (the \fIregion origin\fP) which is common to all regions. In \f(CWXPolygonRegion()\fP, the coordinates specified in \f(CIpoints\fP are relative to the region origin. By specifying all points relative to the drawable in which they will be used, the region origin can be coincident with the drawable origin. It is up to the application whether to interpret the location of the region relative to a drawable or not. .LP If the region is to be used as a \f(CWclip_mask\fP by calling \f(CWXSetRegion()\fP, the upper-left corner of the region relative to the drawable used in the graphics request will be at \f(CW(xoffset + clip_x_origin, yoffset + clip_y_origin)\fP, where \f(CWxoffset\fP and \f(CWyoffset\fP are the offset of .hw origin the region (if any) and \f(CWclip_x_origin\fP and \f(CWclip_y_origin\fP are elements of the GC used in the graphics request. The \f(CIfill_rule\fP can be either of these values: .LP .XX "EvenOddRule" .XX "WindingRule" .IP "\f(CWEvenOddRule\fP" 1.5i Areas overlapping an odd number of times are \fInot\fR part of the region. .IP "\f(CWWindingRule\fP" Overlapping areas are always filled. .LP For more information on structures, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH Structures \f(CWRegion\fP is a pointer to an opaque structure type. .Nd 8 .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXCreateRegion()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XProtocol" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XProtocolRevision, XProtocolVersion, ProtocolRevision, ProtocolVersion \(en return protocol release or version. .XX "XProtocolRevision" .XX "XProtocolVersion" .Nz .\" .\" .SH "Synopsis" .Sy int XProtocolRevision\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .Sy int XProtocolVersion\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" .\" .SH Returns The revision or version number. .SH Description .XX "protocol revision number:returning" \f(CWXProtocolRevision()\fP returns the minor protocol revision number of the X server. \f(CWXProtocolVersion()\fP returns the major version number of the X protocol associated with the connected display. As of Release 4 and 5, the protocol revision level is zero, and the major version number is 11. .LP .XX "ProtocolRevision macro" .XX "ProtocolVersion macro" The C language macros \f(CWProtocolRevision()\fP and \f(CWProtocolVersion()\fP are equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXVendorRelease()\fP\s+1, \s-1\fIXServerVendor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XPutBackEvent" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XPutBackEvent" .XX "events:pushing back on input queue" .Na XPutBackEvent \(en push an event back on the input queue. .Nz .SH "Synopsis" .Sy XPutBackEvent\^(\^\f(CIdisplay\f(CW, \f(CIevent\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XEvent *\f(CIevent\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIevent\fP 1i Specifies a pointer to the event to be requeued. .SH Description \f(CWXPutBackEvent()\fP pushes an event back onto the head of the current display's input queue (so that it would become the one returned by the next \f(CWXNextEvent()\fP call). This can be useful if you have read an event and then decide that you'd rather deal with it later. There is no limit to how many times you can call \f(CWXPutBackEvent()\fP in succession. .LP For more information, see Volume One, Chapter 8, \fIEvents\fR. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XPutImage" "Xlib \- Images" .ds ]W Xlib Reference Manual .SH "Name" .XX "XPutImage" .XX "images:drawing on windows or pixmaps" .XX "windows:drawing images on" .XX "pixmaps:drawing images on" .Na XPutImage \(en draw an image on a window or pixmap. .Nz .SH "Synopsis" .Sy XPutImage\^(\^\f(CIdisplay\f(CW, \f(CId\f(CW\^, \f(CIgc\f(CW\^, \f(CIimage\f(CW\^, \f(CIsrc_x\f(CW, \f(CIsrc_y\f(CW, \f(CIdest_x\f(CW\^, \f(CIdest_y\f(CW\^, \f(CIwidth\f(CW\^, .ti +10n \f(CIheight\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CId\f(CW\^; GC \f(CIgc\f(CW\^; XImage *\f(CIimage\f(CW\^; int \f(CIsrc_x\f(CW\^, \f(CIsrc_y\f(CW\^; int \f(CIdest_x\f(CW\^, \f(CIdest_y\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CId\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIimage\fP 1i Specifies the image you want combined with the rectangle. .IP \f(CIsrc_x\fP 1i .br .ns .IP \f(CIsrc_y\fP 1i .sp -2 Specify the coordinates of the upper-left corner of the rectangle to be copied, relative to the origin of the image. .IP \f(CIdest_x\fP 1i .br .ns .IP \f(CIdest_y\fP 1i .sp -2 Specify the x and y coordinates, relative to the origin of the drawable, where the upper-left corner of the copied rectangle will be placed. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight\fP 1i .sp -2 Specify the width and height in pixels of the rectangular area to be copied. .As \0 .Ae .SH Description .XX "rectangles:drawing images on" \f(CWXPutImage()\fP draws a section of an image on a rectangle in a window or pixmap. The section of the image is defined by \f(CIsrc_x\fP, \f(CIsrc_y\fP, \f(CIwidth\fP, and \f(CIheight\fP. .LP There is no limit to the size of image that can be sent to the server using \f(CWXPutImage()\fP. \f(CWXPutImage()\fP automatically decomposes the call into multiple protocol requests to make sure that the maximum request size of the server is not exceeded. .LP \f(CWXPutImage()\fP uses these graphics context components: \f(CWfunction\fP, \f(CWplane_mask\fP, \f(CWsubwindow_mode\fP, \f(CWclip_x_origin\fP, \f(CWclip_y_origin\fP, and \f(CWclip_mask\fP. This function also uses these graphics context mode-dependent components: \f(CWforeground\fP and \f(CWbackground\fP. .LP .ne 4 If an \f(CWXYBitmap\fP format is used, then the depth of \f(CIimage\fP must be 1, otherwise a \f(CWBadMatch\fP error is generated. The \f(CWforeground\fP pixel in \f(CIgc\fP defines the source for bits set to one in the image, and the \f(CWbackground\fP pixel defines the source for the bits set to zero. .LP For \f(CWXYPixmap\fP and \f(CWZPixmap\fP format images, the depth of the image must match the depth of \f(CWdrawable\fP or a \f(CWBadMatch\fP error results. .br .ne 5 .SH "Structures" .Ps typedef struct _XImage { int width, height; /* size of image */ int xoffset; /* number of pixels offset in x direction */ int format; /* XYBitmap, XYPixmap, ZPixmap */ char *data; /* pointer to image data */ int byte_order; /* data byte order, LSBFirst, MSBFirst */ int bitmap_unit; /* quant. of scan line 8, 16, 32 */ int bitmap_bit_order; /* LSBFirst, MSBFirst */ int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */ int depth; /* depth of image */ int bytes_per_line; /* accelerator to next line */ int bits_per_pixel; /* bits per pixel (ZPixmap) */ char *obdata; /* hook for the object routines to hang on */ struct funcs { /* image manipulation routines */ struct _XImage *(*create_image)(); int (*destroy_image)(); unsigned long (*get_pixel)(); int (*put_pixel)(); struct _XImage *(*sub_image)(); int (*add_pixel)(); } f; } XImage; .Pe .SH "Errors" .IP "\f(CWBadDrawable\fP" .br .IP "\f(CWBadGC\fP" .br .IP "\f(CWBadMatch\fP" 1i See Description above. .br .IP "\f(CWBadValue\fP" .SH "See Also" \s-1\fIXImageByteOrder()\fP\s+1, \s-1\fIXAddPixel()\fP\s+1, \s-1\fIXCreateImage()\fP\s+1, \s-1\fIXDestroyImage()\fP\s+1, \s-1\fIXGetImage()\fP\s+1, \s-1\fIXGetPixel()\fP\s+1, \s-1\fIXGetSubImage()\fP\s+1, \s-1\fIXPutPixel()\fP\s+1, \s-1\fIXSubImage()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XPutPixel" "Xlib \- Images" .ds ]W Xlib Reference Manual .SH "Name" .XX "XPutPixel" .XX "pixels:setting values in an image" .XX "images:setting pixel values in" .Na XPutPixel \(en set a pixel value in an image. .Nz .SH "Synopsis" .Sy XPutPixel\^(\^\f(CIximage\f(CW, \f(CIx\f(CW, \f(CIy\f(CW, \f(CIpixel\f(CW\^) .As XImage *\f(CIximage\f(CW\^; int \f(CIx\f(CW\^; int \f(CIy\f(CW\^; unsigned long \f(CIpixel\f(CW\^; .Ae .SH "Arguments" .IP \f(CIximage\fP 1i Specifies a pointer to the image to be modified. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the pixel to be set, relative to the origin of the image. .IP \f(CIpixel\fP 1i Specifies the new pixel value. .SH Description \f(CWXPutPixel()\fP overwrites the pixel in the named image with the specified pixel value. The \f(CIx\fP and \f(CIy\fP coordinates are relative to the origin of the image. The input pixel value must be in same bit- and byte-order as the machine in which the client is running (that is, the Least Significant Byte (LSB) of the long is the LSB of the pixel). The x and y coordinates must be contained in the image. .SH "Structures" .Ps .ta 4.5n 2.25i typedef struct _XImage { int width, height; /* size of image */ int xoffset; /* number of pixels offset in x direction */ int format; /* XYBitmap, XYPixmap, ZPixmap */ char *data; /* pointer to image data */ int byte_order; /* data byte order, LSBFirst, MSBFirst */ int bitmap_unit; /* quant. of scan line 8, 16, 32 */ int bitmap_bit_order; /* LSBFirst, MSBFirst */ int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */ int depth; /* depth of image */ int bytes_per_line; /* accelerator to next line */ int bits_per_pixel; /* bits per pixel (ZPixmap) */ unsigned long red_mask; /* bits in z arrangment */ unsigned long green_mask; unsigned long blue_mask; char *obdata; /* hook for the object routines to hang on */ struct funcs { /* image manipulation routines */ struct _XImage *(*create_image)(); int (*destroy_image)(); unsigned long (*get_pixel)(); int (*put_pixel)(); struct _XImage *(*sub_image)(); int (*add_pixel)(); } f; } XImage; .XX "XImage structure" .XX "structures:XImage" .Pe .SH "See Also" \s-1\fIXImageByteOrder()\fP\s+1, \s-1\fIXAddPixel()\fP\s+1, \s-1\fIXCreateImage()\fP\s+1, \s-1\fIXDestroyImage()\fP\s+1, \s-1\fIXGetImage()\fP\s+1, \s-1\fIXGetPixel()\fP\s+1, \s-1\fIXGetSubImage()\fP\s+1, \s-1\fIXPutImage()\fP\s+1, \s-1\fIXSubImage()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XQLength" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XQLength, QLength \- return the number of events on the queue. .XX "XQLength" .Nz .\" .\" .SH "Synopsis" .Sy int XQLength\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" .\" .SH Returns The number of events on the queue. .SH Description .XX "queues:returning number of events on" \f(CWXQLength()\fP returns the number of events currently on the queue for the connected display. Note that there may be more events that have not yet been read into the queue (see \f(CWXEventsQueued()\fP). .LP .XX "QLength macro" The C language macro \f(CWQLength()\fP is equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XQueryBestSize" "Xlib \- Pixmaps and Tiles" .ds ]W Xlib Reference Manual .SH "Name" .XX "XQueryBestSize" .Na XQueryBestSize \(en obtain the "best" supported cursor, tile, or stipple size. .Nz .SH "Synopsis" .Sy Status XQueryBestSize\^(\^\f(CIdisplay\f(CW, \f(CIclass\f(CW, \f(CIwhich_screen\f(CW, \f(CIwidth\f(CW, .ti +10n \f(CIheight\f(CW, \f(CIwidth_return\f(CW, \f(CIheight_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int \f(CIclass\f(CW\^; Drawable \f(CIwhich_screen\f(CW\^; unsigned int \f(CIwidth\f(CW, \f(CIheight\f(CW\^; unsigned int *\f(CIwidth_return\f(CW, *\f(CIheight_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.5i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIclass\fP 1.5i Specifies the class that you are interested in. Pass one of these constants: \f(CWTileShape\fP, \f(CWCursorShape\fP, or \f(CWStippleShape\fP. .IP \f(CIwhich_screen\fP 1.5i Specifies a drawable ID that tells the server which screen you want the best size for. .IP \f(CIwidth\fP 1.5i .br .ns .IP \f(CIheight\fP 1.5i .sp -2 Specify the preferred width and height in pixels. .sp .IP \f(CIwidth_return\fP 1.5i .br .ns .IP \f(CIheight_return\fP 1.5i .sp -2 Return the closest supported width and height, in pixels, available for the object on the display hardware. .SH Returns Zero on failure, non-zero on success. .SH Description \f(CWXQueryBestSize()\fP returns the "fastest" or "closest" size to the specified size. For \f(CIclass\fP of \f(CWCursorShape\fP, this is the closest size that can be fully displayed on the screen. For \f(CWTileShape\fP and \f(CWStippleShape\fP, this is the closest size that can be tiled or stippled "fastest." .LP For \f(CWCursorShape\fP, the drawable indicates the desired screen. For \f(CWTileShape\fP and \f(CWStippleShape\fP, the drawable indicates the screen and possibly the visual class and depth (server-dependent). An \f(CWInputOnly\fP window cannot be used as the drawable for \f(CWTileShape\fP or \f(CWStippleShape\fP (else a \f(CWBadMatch\fP error occurs). .LP \f(CWXQueryBestSize()\fR returns non-zero if the call succeeded in getting a supported size (may be the same or different from the specified size), or zero if the call failed. .Nd 12 .SH "Errors" .IP "\f(CWBadDrawable\fP" .br .IP "\f(CWBadMatch\fP" 1i \f(CWInputOnly\fP drawable for \f(CIclass\fP \f(CWTileShape\fP or \f(CWStippleShape\fP. .br .IP "\f(CWBadValue\fP" 1i .br .ne 4 .SH "See Also" \s-1\fIXCreateBitmapFromData()\fP\s+1, \s-1\fIXCreatePixmap()\fP\s+1, \s-1\fIXCreatePixmapFromBitmapData()\fP\s+1, \s-1\fIXFreePixmap()\fP\s+1, \s-1\fIXQueryBestStipple()\fP\s+1, \s-1\fIXQueryBestTile()\fP\s+1, \s-1\fIXReadBitmapFile()\fP\s+1, \s-1\fIXSetTile()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1, \s-1\fIXWriteBitmapFile()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XQueryBestStipple" "Xlib \- Pixmaps and Tiles" .ds ]W Xlib Reference Manual .SH "Name" .XX "XQueryBestStipple" .XX "stipple:obtaining fasted supported shape" .Na XQueryBestStipple \(en obtain the fastest supported stipple shape. .Nz .SH "Synopsis" .Sy Status XQueryBestStipple\^(\^\f(CIdisplay\f(CW, \f(CIwhich_screen\f(CW, \f(CIwidth\f(CW, \f(CIheight\f(CW, .ti +10n \f(CIwidth_return\f(CW, \f(CIheight_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIwhich_screen\f(CW\^; unsigned int \f(CIwidth\f(CW, \f(CIheight\f(CW\^; unsigned int *\f(CIwidth_return\f(CW, *\f(CIheight_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.5i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIwhich_screen\fP 1.5i Specifies a drawable that tells the server which screen you want the best size for. .IP \f(CIwidth\fP 1.5i .br .ns .IP \f(CIheight\fP 1.5i .sp -2 Specify the preferred width and height in pixels. .sp .IP \f(CIwidth_return\fP 1.5i .br .ns .IP \f(CIheight_return\fP 1.5i .sp -2 Return the width and height, in pixels, of the stipple best supported by the display hardware. .sp .SH Returns Zero on failure, non-zero on success. .SH Description \f(CWXQueryBestStipple()\fP returns the closest stipple size that can be stippled fastest. The drawable indicates the screen and possibly the visual class and depth. An \f(CWInputOnly\fP window cannot be used as the drawable (else a \f(CWBadMatch\fP error occurs). .LP \f(CWXQueryBestStipple()\fR returns non-zero if the call succeeded in getting a supported size (may be the same or different from the specified size), or zero if the call failed. .LP For more information on stipples, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .SH "Errors" .IP "\f(CWBadDrawable\fP" .br .IP "\f(CWBadMatch\fP" 1i \f(CWInputOnly\fP window. .br .ne 4 .SH "See Also" \s-1\fIXCreateBitmapFromData()\fP\s+1, \s-1\fIXCreatePixmap()\fP\s+1, \s-1\fIXCreatePixmapFromBitmapData()\fP\s+1, \s-1\fIXFreePixmap()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXQueryBestTile()\fP\s+1, \s-1\fIXReadBitmapFile()\fP\s+1, \s-1\fIXSetTile()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1, \s-1\fIXWriteBitmapFile()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XQueryBestCursor" "Xlib \- Cursors" .ds ]W Xlib Reference Manual .SH "Name" .XX "XQueryBestCursor" .XX "cursors:getting closest supported size" .Na XQueryBestCursor \(en get the closest supported cursor sizes. .Nz .SH "Synopsis" .Sy Status XQueryBestCursor\^(\^\f(CIdisplay\f(CW, \f(CId\f(CW, \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^, .ti +10n \f(CIwidth_return\f(CW\^, \f(CIheight_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CId\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; unsigned int *\f(CIwidth_return\f(CW\^, *\f(CIheight_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.5i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CId\fP 1.5i Specifies a drawable that indicates which screen the cursor is to be used on. The best cursor may be different on different screens. .IP \f(CIwidth\fP 1.5i .br .ns .IP \f(CIheight\fP 1.5i .sp -2 Specify the preferred width and height, in pixels. .sp .IP \f(CIwidth_return\fP 1.5i .br .ns .IP \f(CIheight_return\fP 1.5i .sp -2 Returns the closest supported cursor dimensions, in pixels, on the display hardware. .SH Returns Zero on failure, non-zero on success. .SH Description \f(CWXQueryBestCursor()\fP returns the closest cursor dimensions actually supported by the display hardware to the dimensions you specify. .LP Call this function if you wish to use a cursor size other than 16 by 16. \f(CWXQueryBestCursor()\fP provides a way to find out what size cursors are actually possible on the display. Applications should be prepared to use smaller cursors on displays which cannot support large ones. .LP \f(CWXQueryBestCursor()\fR returns non-zero if the call succeeded in getting a supported size (which may be the same or different from the specified size), or zero if the call failed. .br .ne 4 .SH "Errors" \f(CWBadDrawable\fP .Nd 5 .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXCreateGlyphCursor()\fP\s+1, \s-1\fIXCreatePixmapCursor()\fP\s+1, \s-1\fIXDefineCursor()\fP\s+1, \s-1\fIXFreeCursor()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXRecolorCursor()\fP\s+1, \s-1\fIXUndefineCursor()\fP\s+1. .\"last line comment .TH XQueryBestS.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XQueryBestSize@XQueryBestA .sp .5 XQueryBestStipple@XQueryBestB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XQueryBestTile" "Xlib \- Pixmaps and Tiles" .ds ]W Xlib Reference Manual .SH "Name" .XX "XQueryBestTile" .XX "tiles:obtaining fastest supported shape" .Na XQueryBestTile \(en obtain the fastest supported fill tile shape. .Nz .SH "Synopsis" .Sy Status XQueryBestTile\^(\^\f(CIdisplay\f(CW, \f(CIwhich_screen\f(CW, \f(CIwidth\f(CW, \f(CIheight\f(CW, \f(CIwidth_return\f(CW, \f(CIheight_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CIwhich_screen\f(CW\^; unsigned int \f(CIwidth\f(CW, \f(CIheight\f(CW\^; unsigned int *\f(CIwidth_return\f(CW, *\f(CIheight_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.5i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIwhich_screen\fP 1.5i Specifies a drawable that tells the server which screen you want the best size for. .IP \f(CIwidth\fP 1.5i .br .ns .IP \f(CIheight\fP 1.5i .sp -2 Specify the preferred width and height in pixels. .sp .IP \f(CIwidth_return\fP 1.5i .br .ns .IP \f(CIheight_return\fP 1.5i .sp -2 Return the width and height, in pixels, of the tile best supported by the display hardware. .sp .SH Returns Zero on failure, non-zero on success. .SH Description \f(CWXQueryBestTile()\fP returns the closest size that can be tiled fastest. The drawable indicates the screen and possibly the visual class and depth. An \f(CWInputOnly\fP window cannot be used as the drawable. .LP \f(CWXQueryBestTile()\fR returns non-zero if the call succeeded in getting a supported size (may be the same or different from the specified size), or zero if the call failed. .LP For more information on tiles, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .SH "Errors" .IP "\f(CWBadDrawable\fP" .br .IP "\f(CWBadMatch\fP" 1i \f(CWInputOnly\fP drawable specified. .br .ne 4 .SH "See Also" \s-1\fIXCreateBitmapFromData()\fP\s+1, \s-1\fIXCreatePixmap()\fP\s+1, \s-1\fIXCreatePixmapFromBitmapData()\fP\s+1, \s-1\fIXFreePixmap()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXQueryBestStipple()\fP\s+1, \s-1\fIXReadBitmapFile()\fP\s+1, \s-1\fIXSetTile()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1, \s-1\fIXWriteBitmapFile()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XQueryColor" "Xlib \- Color Cells" .ds ]W Xlib Reference Manual .SH "Name" .XX "XQueryColor" .XX "color:RGB values;for colorcells" .XX "colorcells:RGB values" .Na XQueryColor \(en obtain the RGB values and flags for a specified colorcell. .Nz .SH "Synopsis" .Sy XQueryColor\^(\^\f(CIdisplay\f(CW, \f(CIcolormap\f(CW\^, \f(CIdef_in_out\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcolormap\f(CW\^; XColor *\f(CIdef_in_out\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcolormap\fP 1i Specifies the ID of the colormap from which RGB values will be retrieved. .IP \f(CIdef_in_out\fP 1i Specifies the pixel value and returns the RGB contents of that colorcell. .SH Description \f(CWXQueryColor()\fP returns the RGB values in colormap \f(CIcolormap\fP for the colorcell corresponding to the pixel value specified in the \f(CWpixel\fP member of the \f(CWXColor\fP structure \f(CWdef_in_out\fP. The RGB values are returned in the \f(CWred\fP, \f(CWgreen\fP, and \f(CWblue\fP members of that structure, and the \f(CWflags\fP member of that structure is set to \f(CW(DoRed DoGreen DoBlue)\fR. The values returned for an unallocated entry are undefined. .LP For more information, see Volume One, Chapter 7, \fIColor\fR. .SH "Structures" .Ps typedef struct { unsigned long pixel; unsigned short red, green, blue; char flags; /* DoRed, DoGreen, DoBlue */ char pad; } XColor; .Pe .SH "Errors" .IP "\f(CWBadColor\fP" 1i Invalid colormap. .IP "\f(CWBadValue\fP" 1i Pixel not valid index into \f(CIcolormap\fP. .SH "See Also" \s-1\fIXBlackPixel()\fP\s+1, \s-1\fIXWhitePixel()\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocColorCells()\fP\s+1, \s-1\fIXAllocColorPlanes()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXFreeColors()\fP\s+1, \s-1\fIXLookupColor()\fP\s+1, \s-1\fIXParseColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1, \s-1\fIXStoreNamedColor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XQueryColors" "Xlib \- Color Cells" .ds ]W Xlib Reference Manual .SH "Name" .XX "XQueryColors" .XX "color:RGB values;for array of colorcells" .XX "colorcells:RGB values" .Na XQueryColors \(en obtain RGB values for an array of colorcells. .Nz .SH "Synopsis" .Sy XQueryColors\^(\^\f(CIdisplay\f(CW, \f(CIcolormap\f(CW\^, \f(CIdefs_in_out\f(CW\^, \f(CIncolors\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcolormap\f(CW\^; XColor \f(CIdefs_in_out\f(CW[\f(CIncolors\f(CW]\^; int \f(CIncolors\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcolormap\fP 1i Specifies the ID of the colormap from which RGB values will be retrieved. .IP \f(CIdefs_in_out\fP 1i Specifies an array of \f(CWXColor\fP structures. In each one, \f(CWpixel\fP is set to indicate which colorcell in the colormap to return, and the RGB values in that colorcell are returned in \f(CWred\fP, \f(CWgreen\fP, and \f(CWblue\fP. .IP \f(CIncolors\fP 1i .\"Specifies the number of color definition structures. Specifies the number of \f(CWXColor\fP structures in the color definition array. .SH Description \f(CWXQueryColors()\fP is similar to \f(CWXQueryColor()\fP, but it returns an array of RGB values. It returns the RGB values in colormap \f(CIcolormap\fP for each colorcell corresponding to the pixel value specified in the \f(CWpixel\fP member of each \f(CWXColor\fP structure in the \f(CWcolorcell_def\fP array. The RGB values are returned in the \f(CWred\fP, \f(CWgreen\fP, and \f(CWblue\fP members of that same structure, and sets the \f(CWflags\fP member in each \f(CWXColor\fP structure to \f(CW(DoRed DoGreen DoBlue)\fR. .LP For more information, see Volume One, Chapter 7, \fIColor\fR. .SH "Structures" .Ps typedef struct { unsigned long pixel; unsigned short red, green, blue; char flags; /* DoRed, DoGreen, DoBlue */ char pad; } XColor; .Pe .SH "Errors" .IP "\f(CWBadColor\fP" 1i Invalid colormap. .br .IP "\f(CWBadValue\fP" 1i Pixel not valid index into \f(CIcolormap\fP. .LP Note: if more than one pixel value is in error, the one reported is arbitrary. .Nd 8 .SH "See Also" \s-1\fIXBlackPixel()\fP\s+1, \s-1\fIXWhitePixel()\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocColorCells()\fP\s+1, \s-1\fIXAllocColorPlanes()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXFreeColors()\fP\s+1, \s-1\fIXLookupColor()\fP\s+1, \s-1\fIXParseColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1, \s-1\fIXStoreNamedColor()\fP\s+1. .\"last line comment .TH XqueryColor.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XQueryColor@XQueryColoA .sp .5 XQueryColors@XQueryColoB .sp .5 .TE .KE .in .sp 1 .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XQueryDv.man,v 1.5 94/06/04 17:32:32 rws Exp $ .ds xL Programming with Xlib .TH XQueryDeviceState 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XQueryDeviceState \- query the state of an extension input device. .SH SYNTAX XQueryDeviceState\^(\^\fIdisplay\fP, \fIdevice\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device whose state is to be queried. .SH DESCRIPTION The \fIXQueryDeviceState\fP request queries the state of an input device. The current state of keys and buttons (up or down), and valuators (current value) on the device is reported by this request. Each key or button is represented by a bit in the \fIXDeviceState\fP structure that is returned. Valuators on the device report 0 if they are reporting relative information, and the current value if they are reporting absolute information. .LP \fIXQueryDeviceState\fP can generate a \fIBadDevice\fP error. .SH STRUCTURES The \fIXDeviceState\fP structure contains: .LP .nf typedef struct { XID device_id; int num_classes; XInputClass *data; } XDeviceState; .fi .LP The \fIXValuatorState\fP structure contains: .LP .nf typedef struct { unsigned char class; unsigned char length; unsigned char num_valuators; unsigned char mode; int *valuators; } XValuatorState; .fi .LP The \fIXKeyState\fP structure contains: .LP .nf typedef struct { unsigned char class; unsigned char length; short num_keys; char keys[32]; } XKeyState; .fi .LP The \fIXButtonState\fP structure contains: .LP .nf typedef struct { unsigned char class; unsigned char length; short num_buttons; char buttons[32]; } XButtonState; .fi .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if some other client has caused the specified device to become the X keyboard or X pointer device via the \fIXChangeKeyboardDevice\fP or \fIXChangePointerDevice\fP requests. .SH "SEE ALSO" .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XQueryExtension" "Xlib \- Extensions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XQueryExtension" .XX "extensions:obtaining information about" .Na XQueryExtension \(en get extension information. .Nz .SH "Synopsis" .Sy Bool XQueryExtension(\^\f(CIdisplay\f(CW, \f(CIname\f(CW, \f(CImajor_opcode_return\f(CW, \f(CIfirst_event_return\f(CW, \f(CIfirst_error_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; char *\f(CIname;\f(CW\^ int *\f(CImajor_opcode_return\f(CW\^; int *\f(CIfirst_event_return\f(CW\^; int *\f(CIfirst_error_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIname\fP 1i Specifies the name of the desired extension. Uppercase or lowercase is important. If the extension name is not in the Host Portable Character Encoding, the result is implementation-dependent. .IP \f(CImajor_opcode_return\fP 1i Returns the major opcode of the extension, for use in error handling routines. .IP \f(CIfirst_event_return\fP 1i Returns the code of the first custom event type created by the extension. .IP \f(CIfirst_error_return\fP 1i Returns the code of the first custom error defined by the extension. .SH Returns \f(CWTrue\fP if the extension is present, else \f(CWFalse\fP. .SH Description \f(CWXQueryExtension()\fP determines if the named extension is present, and returns \f(CWTrue\fP if it is. If so, the routines in the extension can be used just as if they were core Xlib requests, except that they may return new types of events or new error codes. The available extensions can be listed with \f(CWXListExtensions()\fP. .LP The \f(CImajor_opcode_return\fP for the extension is returned, if it has one. Otherwise, zero is returned. This opcode will appear in errors generated in the extension. .LP If the extension involves additional event types, the base event type code is returned in \f(CIfirst_event_return\fP. Otherwise, zero is returned in \f(CIfirst_event_return\fP. The format of the events is specific to the extension. .LP If the extension involves additional error codes, the base error code is returned in \f(CIfirst_error_return\fP. Otherwise, zero is returned. The format of additional data in the errors is specific to the extension. .LP See Volume One, Chapter 15, \fIOther Programming Techniques\fR, for more information on using extensions, and Volume One, Appendix C, \fIWriting Extensions to X\fR, for information on writing them. .br .ne 3 .SH "See Also" \s-1\fIXFreeExtensionList()\fP\s+1, \s-1\fIXListExtensions()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XQueryFont" "Xlib \- Fonts" .ds ]W Xlib Reference Manual .SH "Name" .XX "XQueryFont" .XX "fonts:returning information about" .Na XQueryFont \(en return information about a loaded font. .Nz .SH "Synopsis" .Sy XFontStruct *XQueryFont\^(\^\f(CIdisplay\f(CW, \f(CIfont_ID\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XID \f(CIfont_ID\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIfont_ID\fP 1i Specifies either the font ID or the graphics context ID. You can declare the data type for this argument as either \f(CWFont\fP or \f(CWGContext\fP (both X IDs). If \f(CWGContext\fP, the font in that GC will be queried. .SH Returns The font information structure. .SH Description .XX "XLoadFont:and XQueryFont" \f(CWXQueryFont()\fP returns a pointer to an \f(CWXFontStruct\fP structure containing information describing the specified font. This call is needed if you loaded the font with \f(CWXLoadFont()\fP, but need the font information to determine the extent of text. \f(CWXLoadQueryFont()\fP combines these two operations. \f(CWXQueryTextExtents()\fR is an alternative to avoid getting the complete font information, if you need the extents of only a few strings. .XX "XLoadQueryFont:and XQueryFont" .LP If the font hasn't been loaded (or the font ID passed is invalid), \f(CWXQueryFont()\fR returns \f(CWNULL\fR. .LP If \f(CIfont_ID\fP is declared as data type \f(CWGContext\fP (also a resource ID), this function queries the font specified by the font component of the GC specified by this ID. This is useful for getting information about the default font, whose ID is stored in the default GC. However, in this case the \f(CWGContext\fP ID will be the ID stored in the \f(CWfid\fP field of the returned \f(CWXFontStruct\fP, and you can't use that ID in \f(CWXSetFont()\fP or \f(CWXUnloadFont()\fP, since it is not itself the ID of the font. .LP Use \f(CWXFreeFont()\fP to free this data. .LP For more information on fonts, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Errors" .sp .5 \f(CWBadFont\fR .Nd 5 .SH "Structures" .Ps .ta 4.5n 2.18i typedef struct { XExtData *ext_data; /* hook for extension to hang data */ Font fid; /* font ID for this font */ unsigned direction; /* hint about direction font is painted */ unsigned min_char_or_byte2; /* first character */ unsigned max_char_or_byte2; /* last character */ unsigned min_byte1; /* first row that exists */ unsigned max_byte1; /* last row that exists */ Bool all_chars_exist; /* flag if all characters have non-zero size*/ unsigned default_char; /* char to print for undefined character */ int n_properties; /* how many properties there are */ XFontProp *properties; /* pointer to array of additional properties*/ XCharStruct min_bounds; /* minimum bounds over all existing char*/ XCharStruct max_bounds; /* maximum bounds over all existing char*/ XCharStruct *per_char; /* first_char to last_char information */ int ascent; /* logical extent above baseline for spacing */ int descent; /* logical descent below baseline for spacing */ } XFontStruct; .XX "XFontStruct structure" .XX "structures:XFontStruct" .Pe .ne 5 .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXFreeFont()\fP\s+1, \s-1\fIXFreeFontInfo()\fP\s+1, \s-1\fIXFreeFontNames()\fP\s+1, \s-1\fIXFreeFontPath()\fP\s+1, \s-1\fIXGetFontPath()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXListFonts()\fP\s+1, \s-1\fIXListFontsWithInfo()\fP\s+1, \s-1\fIXLoadFont()\fP\s+1, \s-1\fIXLoadQueryFont()\fP\s+1, \s-1\fIXSetFont()\fP\s+1, \s-1\fIXSetFontPath()\fP\s+1, \s-1\fIXUnloadFont()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XQueryKeymap" "Xlib \- Keyboard" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XQueryKeymap" .XX "keymaps:querying" XQueryKeymap \(en obtain a bit vector for the current state of the keyboard. .Nz .SH "Synopsis" .Sy XQueryKeymap\^(\^\f(CIdisplay\f(CW, \f(CIkeys_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; char \f(CIkeys_return\f(CW[32]\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIkeys_return\fP 1i Returns an array of bytes that identifies which keys are pressed down. Each bit represents one key of the keyboard. .SH Description \f(CWXQueryKeymap()\fP returns a bit vector for the logical state of the keyboard, where each bit set to 1 indicates that the corresponding key is currently pressed down. The vector is represented as 32 bytes. Byte \fIN\fR (from 0) contains the bits for keys \fI8N\fR to \fI8N+7\fP with the least significant bit in the byte representing key \fI8N\fR. Note that the logical state may lag the physical state if device event processing is frozen due to a grab. .SH "See Also" \s-1\fIXChangeKeyboardMapping()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifiermap()\fP\s+1, \s-1\fIXRebindKeysym()\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XQueryPointer" "Xlib \- Pointer" .ds ]W Xlib Reference Manual .SH "Name" .XX "XQueryPointer" .XX "pointers:obtaining current location" .Na XQueryPointer \(en get the current pointer location. .Nz .SH "Synopsis" .Sy Bool XQueryPointer\^(\^\f(CIdisplay\f(CW, \f(CIwindow\f(CW\^, \f(CIroot_return\f(CW\^, \f(CIchild_return\f(CW\^, \f(CIroot_x_return\f(CW\^, \f(CIroot_y_return\f(CW\^, \f(CIwin_x_return\f(CW\^, \f(CIwin_y_return\f(CW\^, \f(CImask_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIwindow\f(CW\^; Window *\f(CIroot_return\f(CW\^, *\f(CIchild_return\f(CW\^; int *\f(CIroot_x_return\f(CW\^, *\f(CIroot_y_return\f(CW\^; int *\f(CIwin_x_return\f(CW\^, *\f(CIwin_y_return\f(CW\^; unsigned int *\f(CImask_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.25i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIwindow\fP Specifies a window which indicates which screen the pointer position is returned for, and \f(CIchild_return\fP will be a child of this window if pointer is inside a child. .IP \f(CIroot_return\fP Returns the root window ID the pointer is currently on. .IP \f(CIchild_return\fP Returns the ID of the child of \f(CIw\fR the pointer is located in, or zero if it not in a child. .IP \f(CIroot_x_return\fP .br .ns .IP \f(CIroot_y_return\fP .sp -2 Return the x and y coordinates of the pointer relative to the root's origin. .sp .IP \f(CIwin_x_return\fP .br .ns .IP \f(CIwin_y_return\fP .sp -2 Return the x and y coordinates of the pointer relative to the origin of window \f(CIwindow\fP. .sp .IP \f(CImask_return\fP Returns the current state of the modifier keys and pointer buttons. This is a mask composed of the OR of any number of the following symbols: \f(CWShiftMask\fP, \f(CWLockMask\fP, \f(CWControlMask\fP, \f(CWMod1Mask\fP, \f(CWMod2Mask\fP, \f(CWMod3Mask\fP, \f(CWMod4Mask\fP, \f(CWMod5Mask\fP, \f(CWButton1\%Mask\fP, \f(CWButton2Mask\fP, \f(CWButton3Mask\fP, \f(CWButton4Mask\fP, \f(CWButton5\%Mask\fP. .SH Returns \f(CWTrue\fP if the pointer is on the same screen as the window argument, else \f(CWFalse\fP. .Nd 10 .SH Description \f(CWXQueryPointer()\fP gets the pointer coordinates relative to a window and relative to the root window, the \f(CIroot_return\fP window ID and the \f(CIchild_return\fP window ID (if any) the pointer is currently in, and the current state of modifier keys and buttons. .LP If \f(CWXQueryPointer()\fP returns \f(CWFalse\fP, then the pointer is not on the same screen as \f(CIwindow\fP, \f(CIchild_return\fP is \f(CWNone\fP, and \f(CIwin_x_return\fP and \f(CIwin_y_return\fP are zero. However, \f(CIroot_return\fP, \f(CIroot_x_return\fP, and \f(CIroot_y_return\fP are still valid. If \f(CWXQueryPointer()\fP returns \f(CWTrue\fP, then the pointer is on the same screen as \f(CIwindow\fP, and all return values are valid. .LP The logical state of the pointer buttons and modifier keys can lag behind their physical state if device event processing is frozen due to a grab. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXChangePointerControl()\fP\s+1, \s-1\fIXGetPointerControl()\fP\s+1, \s-1\fIXGetPointerMapping()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXSetPointerMapping()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1, \s-1\fIXWarpPointer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XQueryTextExtents" "Xlib \- Text" .ds ]W Xlib Reference Manual .SH "Name" .XX "XQueryTextExtents" .Na .XX "text:string and font metrics;querying server for" XQueryTextExtents \(en query the server for string and font metrics. .Nz .SH "Synopsis" .Sy XQueryTextExtents\^(\^\f(CIdisplay\f(CW, \f(CIfont_ID\f(CW, \f(CIstring\f(CW, \f(CInchars\f(CW, \f(CIdirection_return\f(CW, \f(CIfont_ascent_return\f(CW, \f(CIfont_descent_return\f(CW, \f(CIoverall_return\f(CW) .As Display *\f(CIdisplay\f(CW\^; XID \f(CIfont_ID\f(CW\^; char *\f(CIstring\f(CW\^; int \f(CInchars\f(CW\^; int *\f(CIdirection_return\f(CW\^; int *\f(CIfont_ascent_return\f(CW, *\f(CIfont_descent_return\f(CW\^; XCharStruct *\f(CIoverall_return\f(CW; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIfont_ID\fP 1i Specifies the appropriate font ID previously returned by \f(CWXLoadFont()\fP, or the \f(CWGContext\fP that specifies the font. .IP \f(CIstring\fP 1i Specifies the character string for which metrics are to be returned. .IP \f(CInchars\fP 1i Specifies the number of characters in \f(CIstring\fP. .IP \f(CIdirection_return\fP 1i Returns the direction the string would be drawn using the specified font. Either \f(CWFontLeftToRight\fP or \f(CWFontRightToLeft\fP. .IP \f(CIfont_ascent_return\fP 1i Returns the maximum ascent for the specified font. .IP \f(CIfont_descent_return\fP 1i Returns the maximum descent for the specified font. .IP \f(CIoverall_return\fP 1i Returns the overall characteristics of the string. These are the sum of the \f(CWwidth\fP measurements for .hw descent each character, the maximum \f(CWfont_ascent_return\fP and \f(CWfont_descent_return\fP, the minimum \f(CWlbearing\fP added to the width of all characters up to the character with the smallest \f(CWlbearing\fP, and the maximum \f(CWrbearing\fP added to the width of all characters up to the character with the largest \f(CWrbearing\fP. .SH Description \f(CWXQueryTextExtents()\fP returns the dimensions in pixels that specify the bounding box of the specified string of characters in the named font, and the maximum ascent and descent for the entire font. This function queries the server and, therefore, suffers the round trip overhead that is avoided by \f(CWXTextExtents()\fP, but \f(CWXQueryTextExtents()\fP does not require a filled \f(CWXFontInfo\fP structure stored on the client side. Therefore, this function would be used when memory is precious, or when just a small number of text width calculations are to be done. .LP The returned \f(CIfont_ascent_return\fP and \f(CIfont_descent_return\fP should usually be used to calculate the line spacing, while the \f(CWwidth\fP, \f(CWrbearing\fP, and \f(CWlbearing\fP members of \f(CIoverall_return\fP should be used for horizontal measures. The total height of the bounding rectangle, good for any string in this font, is \f(CIfont_ascent_return\fP \f(CW+\fP \f(CIfont_descent_return\fP. .LP .br .ne 2 \f(CIoverall_return.ascent\fP is the maximum of the ascent metrics of all characters in the string. The \f(CIoverall_return.descent\fP is the maximum of the descent metrics. The \f(CIoverall_return.width\fP is the sum of the character-width metrics of all characters in the string. .\" fix: THE FOLLOWING MAKES NO SENSE The \f(CIoverall_return.lbearing\fP is usually the lbearing of the first character in the string, and \f(CIoverall_return.rbearing\fP is the rbearing of the last character in the string plus the sum of the widths of all the characters up to but not including the last character. More technically, here is the X protocol definition: \fIFor each character in the string, let W be the sum of the character-width metrics of all characters preceding it in the string, let L be the lbearing metric of the character plus W, and let R be the rbearing metric of the character plus W. The \f(CWoverall_return.lbearing\fP is the minimum L of all characters in the string, and the \f(CWoverall_return.rbearing\fP is the maximum R.\fR .LP For more information on drawing text, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .LP .SH "Structures" .Ps typedef struct { short lbearing; /* origin to left edge of character */ short rbearing; /* origin to right edge of character */ short width; /* advance to next char's origin */ short ascent; /* baseline to top edge of character */ short descent; /* baseline to bottom edge of character */ unsigned short attributes; /* per char flags (not predefined) */ } XCharStruct; .Pe .vs .SH "Errors" \f(CWBadFont\fP .br \f(CWBadGC\fP .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawImageString16()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawString16()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXDrawText16()\fP\s+1, \s-1\fIXQueryTextExtents16()\fP\s+1, \s-1\fIXTextExtents()\fP\s+1, \s-1\fIXTextExtents16()\fP\s+1, \s-1\fIXTextWidth()\fP\s+1, \s-1\fIXTextWidth16()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XQueryTextExtents16" "Xlib \- Text" .ds ]W Xlib Reference Manual .SH "Name" .XX "XQueryTextExtents16" .XX "text:string and font metrics;querying server for" .Na XQueryTextExtents16 \(en query the server for string and font metrics of a 16-bit character string. .Nz .SH "Synopsis" .Sy XQueryTextExtents16\^(\^\f(CIdisplay\f(CW, \f(CIfont_ID\f(CW, \f(CIstring\f(CW, \f(CInchars\f(CW, \f(CIdirection_return\f(CW, \f(CIfont_ascent_return\f(CW, \f(CIdescent\f(CW, \f(CIoverall_return\\f(CW) .As Display *\f(CIdisplay\f(CW\^; XID \f(CIfont_ID\f(CW\^; XChar2b *\f(CIstring\f(CW\^; int \f(CInchars\f(CW\^; int *\f(CIdirection_return\f(CW\^; int *\f(CIfont_ascent_return\f(CW, *\f(CIfont_descent_return\f(CW\^; XCharStruct *\f(CIoverall_return\\f(CW; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIfont_ID\fP 1i Specifies the appropriate font ID previously returned by \f(CWXLoadFont()\fP, or the \f(CWGContext\fP that specifies the font. .IP \f(CIstring\fP 1i Specifies the character string for which metrics are to be returned. .IP \f(CInchars\fP 1i Specifies the number of characters in \f(CIstring\fP. .IP \f(CIdirection_return\fP 1i Returns the direction of painting in the specified font. Either \f(CWFontLefttoRight\fP or \f(CWFontRighttoLeft\fP. .IP \f(CIfont_ascent_return\fP 1i Returns the maximum ascent in pixels for the specified font. .IP \f(CIdescent\fP 1i Returns the maximum descent in pixels for the specified font. .IP \f(CIoverall_return\\fP 1i Returns the overall characteristics of the string. These are the sum of the \f(CWwidth\fP measurements for .hw descent each character, the maximum \f(CWfont_ascent_return\fP and \f(CWdescent\fP, the minimum \f(CWlbearing\fP added to the width of all characters up to the character with the smallest \&\f(CWlbearing\fP, and the maximum \f(CWrbearing\fP added to the width of all characters up to the character with the largest \&\f(CWrbearing\fP. .hw XText-Extents16 .SH Description \f(CWXQueryTextExtents16()\fP returns the dimensions in pixels that specify the bounding box of the specified string of characters in the named font, and the maximum ascent and descent for the entire font. This function queries the server and, therefore, suffers the round trip overhead that is avoided by \f(CWXTextExtents16()\fP, .ne 2 but \f(CWXQueryTextExtents()\fP does not require a filled \f(CWXFontInfo\fP structure. .LP The returned \f(CIfont_ascent_return\fP and \f(CIfont_descent_return\fP should be used to calculate the line spacing, while the \f(CWwidth\fP, \f(CWrbearing\fP and \f(CWlbearing\fP members of \f(CIoverall_return\fP should be used for horizontal measures. The total height of the bounding rectangle for any string in this font is \s-1\f(CIfont_ascent_return\fP \f(CW+\fP \f(CIfont_descent_return\fP\s+. .LP \f(CIoverall_return\.font_ascent_return\fP is the maximum of the ascent metrics of all characters in the string. The \f(CIoverall_return\.descent\fP is the maximum of the descent metrics. The \f(CIoverall_return\.width\fP is the sum of the character-width metrics of all characters in the string. The \f(CIoverall_return\.lbearing\fP is usually the lbearing of the first character in the string, and \f(CIoverall_return\.rbearing\fP is the rbearing of the last character in the string plus the sum of the widths of all the characters up to but not including the last character. More technically, here is the X protocol definition: \fIFor each character in the string, let W be the sum of the character-width metrics of all characters preceding it in the string, let L be the lbearing metric of the character plus W, and let R be the rbearing metric of the character plus W. The \f(CWoverall_return\.lbearing\fP is the minimum L of all characters in the string, and the \f(CWoverall_return\.rbearing\fP is the maximum R.\fR .LP For fonts defined with linear indexing rather than two-byte matrix indexing, the server interprets each \f(CWXChar2b\fP as a 16-bit number that has been transmitted with the most significant byte first. That is, byte one of the \f(CWXChar2b\fP is taken as the most significant byte. .LP If the font has no defined default character, then undefined characters in the string are taken to have all zero metrics. .SH "Structures" .Ps typedef struct { /* normal 16-bit characters are two bytes */ unsigned char byte1; unsigned char byte2; } XChar2b; .ta 4n 2.2i typedef struct { short lbearing; /* origin to left edge of character */ short rbearing; /* origin to right edge of character */ short width; /* advance to next char's origin */ short ascent; /* baseline to top edge of character */ short descent; /* baseline to bottom edge of character */ unsigned short attributes; /* per char flags (not predefined) */ } XCharStruct; .Pe .SH "Errors" \f(CWBadFont\fP .br \f(CWBadGC\fP .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawImageString16()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawString16()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXDrawText16()\fP\s+1, \s-1\fIXQueryTextExtents()\fP\s+1, \s-1\fIXTextExtents()\fP\s+1, \s-1\fIXTextExtents16()\fP\s+1, \s-1\fIXTextWidth()\fP\s+1, \s-1\fIXTextWidth16()\fP\s+1. .\"last line comment .TH XQueryTextE.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XQueryTextExtents@XQueryTextA .sp .5 XQueryTextExtents16@XQueryTextB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XQueryTree" "Xlib \- Window Manipulation" .ds ]W Xlib Reference Manual .SH "Name" .XX "XQueryTree" .Na XQueryTree \(en return a list of children, parent, and root. .Nz .SH "Synopsis" .Sy Status XQueryTree\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIroot_return\f(CW\^, \f(CIparent_return\f(CW\^, .br \f(CIchildren_return\f(CW\^, \f(CInchildren_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; Window *\f(CIroot_return\f(CW\^; Window *\f(CIparent_return\f(CW\^; Window **\f(CIchildren_return\f(CW\^; unsigned int *\f(CInchildren_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window to be queried. For this window, \f(CWXQueryTree()\fP will list its children, its root, its parent, and the number of children. .IP \f(CIroot_return\fP 1i Returns the root ID for the specified window. .IP \f(CIparent_return\fP 1i Returns the parent window of the specified window. .IP \f(CIchildren_return\fP 1i Returns the list of children associated with the specified window. .IP \f(CInchildren_return\fP 1i Returns the number of children associated with the specified window. .SH Returns Zero on failure, non-zero on success. .SH Description .XX "tree:querying" \f(CWXQueryTree()\fP uses its last four arguments to return the root ID, the parent ID, a pointer to a list of children and the number of children in that list, all for the specified window \f(CIw\fP. The \f(CIchildren_return\fP are listed in current stacking order, from bottommost (first) to topmost (last). \f(CWXQueryTree()\fP returns zero if it fails, non-zero if it succeeds. .LP You should deallocate the list of children with \f(CWXFree()\fP when it is no longer needed. .SH "Errors" \f(CWBadWindow\fP .Nd 5 .SH "See Also" \s-1\fIXCirculateSubwindows()\fP\s+1, \s-1\fIXCirculateSubwindowsDown()\fP\s+1, \s-1\fIXCirculateSubwindowsUp()\fP\s+1, \s-1\fIXConfigureWindow()\fP\s+1, \s-1\fIXLowerWindow()\fP\s+1, \s-1\fIXMoveResizeWindow()\fP\s+1, \s-1\fIXMoveWindow()\fP\s+1, \s-1\fIXRaiseWindow()\fP\s+1, \s-1\fIXReparentWindow()\fP\s+1, \s-1\fIXResizeWindow()\fP\s+1, \s-1\fIXRestackWindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XRaiseWindow" "Xlib \- Window Manipulation" .ds ]W Xlib Reference Manual .SH "Name" .XX "XRaiseWindow" .XX "windows:raising" .Na XRaiseWindow \(en raise a window to the top of the stacking order. .Nz .SH "Synopsis" .Sy XRaiseWindow\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window to be raised to the top of the stack. .SH Description \f(CWXRaiseWindow()\fP moves a window to the top of the stacking order among its siblings. If the windows are regarded as overlapping sheets of paper stacked on a desk, then raising a window is analogous to moving the sheet to the top of the stack, while leaving its x and y location on the desk constant. .LP Raising a mapped window may generate exposure events for that window and any mapped subwindows of that window that were formerly obscured. .LP If the \f(CWoverride_redirect\fP attribute of the window (see Volume One, Chapter 4, \fIWindow Attributes\fR) is \f(CWFalse\fP and the window manager has selected \f(CWSubstructure\%RedirectMask\fP on the parent, then a \f(CWConfigureRequest\fP event is sent to the window manager, and no further processing is performed. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXCirculateSubwindows()\fP\s+1, \s-1\fIXCirculateSubwindowsDown()\fP\s+1, \s-1\fIXCirculateSubwindowsUp()\fP\s+1, \s-1\fIXConfigureWindow()\fP\s+1, \s-1\fIXLowerWindow()\fP\s+1, \s-1\fIXMoveResizeWindow()\fP\s+1, \s-1\fIXMoveWindow()\fP\s+1, \s-1\fIXQueryTree()\fP\s+1, \s-1\fIXReparentWindow()\fP\s+1, \s-1\fIXResizeWindow()\fP\s+1, \s-1\fIXRestackWindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XReadBitmapFile" "Xlib \- Pixmaps and Tiles" .ds ]W Xlib Reference Manual .SH "Name" .XX "XReadBitmapFile" .XX "bitmaps:reading from disk" .Na XReadBitmapFile \(en read a bitmap from disk. .Nz .SH "Synopsis" .Sy int XReadBitmapFile(\^\f(CIdisplay\f(CW, \f(CId\f(CW, \f(CIfilename\f(CW, \f(CIwidth_return\f(CW, \f(CIheight_return\f(CW, .br \f(CIbitmap_return\f(CW, \f(CIx_hot_return\f(CW, \f(CIy_hot_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Drawable \f(CId\f(CW\^; char *\f(CIfilename\f(CW\^; unsigned int *\f(CIwidth_return\f(CW, *\f(CIheight_return\f(CW\^; Pixmap *\f(CIbitmap_return\f(CW\^; int *\f(CIx_hot_return\f(CW, *\f(CIy_hot_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.5i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CId\fP 1.5i Specifies the drawable. .IP \f(CIfilename\fP 1.5i Specifies the filename to use. The format of the filename is operating system specific. .IP \f(CIwidth_return\fP 1.5i .br .ns .IP \f(CIheight_return\fP 1.5i .sp -2 Return the dimensions in pixels of the bitmap that is read. .sp .IP \f(CIbitmap_return\fP 1.5i Returns the pixmap resource ID that is created. .IP \f(CIx_hot_return\fP 1.5i .br .ns .IP \f(CIy_hot_return\fP 1.5i .sp -2 Return the hotspot coordinates in the file (or \-1,\-1 if none present). .SH Returns \f(CWBitmapSuccess\fP on success. \f(CWBitmapOpenFailed\fP, \f(CWBitmapFileInvalid\fP, or \f(CWBitmapNoMemory\fP on failure. .SH Description \f(CWXReadBitmapFile()\fP reads in a file containing a description of a pixmap of depth 1 (a bitmap) in X Version 11 bitmap format. The file is parsed in the encoding of the current locale. The ability to read other than the standard format is implementation-dependent. .LP \f(CWXReadBitmapFile()\fP creates a pixmap of the appropriate size and reads the bitmap data from the file into the pixmap. The caller should free the pixmap using \f(CWXFreePixmap()\fP when finished with it. .LP If the file cannot be opened, \f(CWXReadBitmapFile()\fP returns \f(CWBitmapOpenFailed\fP. If the file can be opened but does not contain valid bitmap data, \f(CWXReadBitmapFile()\fP returns \f(CWBitmapFileInvalid\fP. .ne 6 If insufficient working storage is allocated, \f(CWXReadBitmapFile()\fP returns \f(CWBitmapNoMemory\fP. If the file is readable and valid, \f(CWXReadBitmapFile()\fP returns \f(CWBitmapSuccess\fP. .LP .br Here is an example X Version 11 bitmap file: .LP .ps 8 .vs 10 .ft CW .nf .ta 4.5n 2.75i #define name_width_return 16 #define name_height_return 16 #define name_x_hot_return 8 #define name_y_hot_return 8 static char name_bits[] = { 0xf8, 0x1f, 0xe3, 0xc7, 0xcf, 0xf3, 0x9f, 0xf9, 0xbf, 0xfd, 0x33, 0xcc, 0x7f, 0xfe, 0x7f, 0xfe, 0x7e, 0x7e, 0x7f, 0xfe, 0x37, 0xec, 0xbb, 0xdd, 0x9c, 0x39, 0xcf, 0xf3, 0xe3, 0xc7, 0xf8, 0x1f}; .fi .ft R .ps .vs .LP For more information, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Errors" \f(CWBadDrawable\fP .br \f(CWBadMatch\fP .SH "See Also" \s-1\fIXCreateBitmapFromData()\fP\s+1, \s-1\fIXCreatePixmap()\fP\s+1, \s-1\fIXCreatePixmapFromBitmapData()\fP\s+1, \s-1\fIXFreePixmap()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXQueryBestStipple()\fP\s+1, \s-1\fIXQueryBestTile()\fP\s+1, \s-1\fIXSetTile()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1, \s-1\fIXWriteBitmapFile()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XRebindKeysym" "Xlib \- Keyboard" .ds ]W Xlib Reference Manual .SH "Name" .XX "XRebindKeysym" .Na .XX "keysyms:rebinding to a string" XRebindKeysym \(en rebind a keysym to a string for client. .Nz .SH "Synopsis" .Sy XRebindKeysym(\^\f(CIdisplay\f(CW, \f(CIkeysym\f(CW, \f(CImod_list\f(CW, \f(CImod_count\f(CW, \f(CIstring\f(CW, .ti +10n \f(CInum_bytes\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; KeySym \f(CIkeysym\f(CW\^; KeySym *\f(CImod_list\f(CW\^; int \f(CImod_count\f(CW\^; unsigned char *\f(CIstring\f(CW\^; int \f(CInum_bytes\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIkeysym\fP 1i Specifies the keysym to be rebound. .IP \f(CImod_list\fP 1i Specifies a pointer to an array of keysyms that are being used as modifiers. .IP \f(CImod_count\fP 1i Specifies the number of modifiers in the modifier list. .IP \f(CIstring\fP 1i Specifies a pointer to the string that is to be copied and returned by \f(CWXLookupString()\fP in response to later events. .IP \f(CInum_bytes\fP 1i Specifies the length of the string. .SH Description \f(CWXRebindKeysym()\fP binds the \f(CIstring\fP to the specified \f(CIkeysym\fP, so that \f(CIstring\fP and \f(CIkeysym\fP are returned by \f(CWXLookukpString\fR when that key is pressed and the modifiers specified in \f(CImod_list\fP are also being held down. This function rebinds the meaning of a keysym for a client. It does not redefine the keycode in the server but merely provides an easy way for long strings to be attached to keys. No text conversions are performed; the client is responsible for supplying appropriately encoded strings. Note that you are allowed to rebind a keysym that may not exist. .LP See Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR, for a description of keysyms and keyboard mapping. .SH "See Also" \s-1\fIXChangeKeyboardMapping()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifiermap()\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XRecolorCursor" "Xlib \- Cursors" .ds ]W Xlib Reference Manual .SH "Name" .XX "XRecolorCursor" .XX "cursors:changing color of" .Na XRecolorCursor \(en change the color of a cursor. .Nz .SH "Synopsis" .Sy XRecolorCursor\^(\^\f(CIdisplay\f(CW, \f(CIcursor\f(CW\^, \f(CIforeground_color\f(CW\^, \f(CIbackground_color\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Cursor \f(CIcursor\f(CW\^; XColor *\f(CIforeground_color\f(CW\^, *\f(CIbackground_color\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcursor\fP 1i Specifies the cursor ID. .IP \f(CIforeground_color\fP 1i Specifies the red, green, and blue (RGB) values for the foreground. .IP \f(CIbackground_color\fP 1i Specifies the red, green, and blue (RGB) values for the background. .SH Description \f(CWXRecolorCursor()\fP applies a foreground and background color to a cursor. Cursors are normally created using a single plane pixmap, composed of 0's and 1's, with one pixel value assigned to 1's and another assigned to 0's. \f(CWXRecolorCursor()\fP changes these pixel values. If the cursor is being displayed on a screen, the change is visible immediately. On some servers, these color selections are read/write cells from the colormap, and can't be shared by applications. .SH "Structures" .Ps typedef struct { unsigned long pixel; unsigned short red, green, blue; char flags; /* DoRed, DoGreen, DoBlue */ char pad; } XColor; .Pe .SH "Errors" \f(CWBadCursor\fP .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXCreateGlyphCursor()\fP\s+1, \s-1\fIXCreatePixmapCursor()\fP\s+1, \s-1\fIXDefineCursor()\fP\s+1, \s-1\fIXFreeCursor()\fP\s+1, \s-1\fIXQueryBestCursor()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXUndefineCursor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XReconfigureWMWindow" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XReconfigureWMWindow" .XX "windows:reconfiguring" .Na XReconfigureWMWindow \(en request that a top-level window be reconfigured. .Nz .SH "Synopsis" .Sy Status XReconfigureWMWindow\^(\^\f(CIdisplay\fP\^,\f(CIw\fP\^,\f(CIscreen_number\fP\^,\f(CIvalue_mask\fP\^,\f(CIvalues\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; int \f(CIscreen_number\fP\^; unsigned int \f(CIvalue_mask\fP\^; XWindowChanges *\f(CIvalues\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/ReconfigWMWin 2.8 1993/05/28 13:31:46 stephen Exp $ .IP \f(CIw\fP 1i Specifies the window. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number on the host server. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/ReconfigWMWin 2.8 1993/05/28 13:31:46 stephen Exp $ .IP \f(CIvalue_mask\fP 1i Specifies which values are to be set using information in the values structure. This mask is the bitwise inclusive OR of the valid configure window values bits. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/ReconfigWMWin 2.8 1993/05/28 13:31:46 stephen Exp $ .IP \f(CIvalues\fP 1i Specifies a pointer to the \f(CWXWindowChanges\fR structure. .SH Returns Non-zero if the request or event is successfully sent; otherwise zero. .SH "Availability" Release 4 and later. .SH Description .LP \f(CWXReconfigureWMWindow()\fR issues a .XX "ConfigureWindow request" \f(CWConfigureWindow\fR request on the specified top-level window. If the stacking mode is changed and the request fails with a \f(CWBadMatch\fR error, the error event is trapped and a synthetic \f(CWConfigureRequest\fR event containing the same configuration parameters is sent to the root of the specified window. Window managers may elect to receive this event and treat it as a request to reconfigure the indicated window. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .Ps typedef struct { int x, y; int width, height; int border_width; Window sibling; int stack_mode; } XWindowChanges; .XX "XWindowChanges structure" .XX "structures:XWindowChanges" .Pe .Nd 10 .SH "Errors" \f(CWBadValue\fR .br \f(CWBadWindow\fR .SH "See Also" \s-1\fIXIconifyWindow()\fP\s+1, \s-1\fIXWithdrawWindow()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XRectInRegion" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XRectInRegion" .Na .XX "regions:determining if rectangles reside in" .XX "rectangles:and regions;residing in" XRectInRegion \(en determine if a rectangle resides in a region. .Nz .SH "Synopsis" .Sy int XRectInRegion\^(\^\f(CIr\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^, \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^) .As Region \f(CIr\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; .Ae .SH "Arguments" .IP \f(CIr\fP 1i Specifies the region. .IP \f(CIx\fP 1i .br .ns .IP \f(CIy\fP 1i .sp -2 Specify the x and y coordinates of the upper-left corner of the rectangle, relative to the region's origin. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight\fP 1i .sp -2 Specify the width and height in pixels of the rectangle. .sp .SH Returns \f(CWRectangleIn\fP, \f(CWRectangleOut\fP, or \f(CWRectanglePart\fP. .SH Description \f(CWXRectInRegion()\fP returns \f(CWRectangleIn\fP if the rectangle is completely contained in the region \f(CIr\fP, \f(CWRectangleOut\fP if it is completely outside, and \f(CWRectanglePart\fP if it is partially inside. .LP Regions are located using an offset from a point (the \fIregion origin\fP) which is common to all regions. It is up to the application to interpret the location of the region relative to a drawable. If the region is to be used as a \f(CWclip_mask\fP by calling \f(CWXSetRegion()\fP, the upper-left corner of region relative to the drawable used in the graphics request will be at \f(CW(xoffset + clip_x_origin, yoffset + clip_y_origin)\fP, where \f(CWxoffset\fP and \f(CWyoffset\fP are the offset of the region and \f(CWclip_x_origin\fP and \f(CWclip_y_origin\fP are the clip origin in the GC used. .LP For this function, the \f(CIx\fP and \f(CIy\fP arguments are interpreted relative to the region origin; no drawable is involved. .SH "Structures" \f(CWRegion\fP is a pointer to an opaque structure type. .Nd 5 .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXCreateRegion()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XRefreshKeyboardMapping" "Xlib \- Keyboard" .ds ]W Xlib Reference Manual .SH "Name" .XX "XRefreshKeyboardMapping" .XX "keyboard:refreshing keyboard mapping" .Na XRefreshKeyboardMapping \(en read keycode-keysym mapping from server into Xlib. .Nz .SH "Synopsis" .Sy XRefreshKeyboardMapping(\^\f(CImap_event\f(CW\^) .As XMappingEvent *\f(CImap_event\f(CW\^; .Ae .SH "Arguments" .IP \f(CImap_event\fP 1i Specifies the mapping event that triggered this call. .SH Description \f(CWXRefreshKeyboardMapping()\fP causes Xlib to update its knowledge of the mapping between keycodes and keysyms. This updates the application's knowledge of the keyboard. .LP .XX "MappingNotify event" .XX "events:MappingNotify" The application should call \f(CWXRefreshKeyboardMapping()\fP when a \f(CWMappingNotify\fP event occurs. \f(CWMappingNotify\fP events occur when some client has called \f(CWXChangeKeyboardMapping()\fP. .LP For more information, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH Structures .Ps typedef struct { int type; unsigned long serial; /* # of last request processed by server */ Bool send_event; /* true if this came from a SendEvent request */ Display *display; /* display the event was read from */ Window window; /* unused */ int request; /* one of MappingModifier, MappingKeyboard, */ /* MappingPointer */ int first_keycode; /* first keycode */ int count; /* defines range of change with first_keycode*/ } XMappingEvent; .XX "XMappingEvent structure" .XX "structures:XMappingEvent" .Pe .SH "See Also" \s-1\fIXChangeKeyboardMapping()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifierMap\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeysym()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XRemoveFromSaveSet" "Xlib \- Save Set" .ds ]W Xlib Reference Manual .SH "Name" .XX "XRemoveFromSaveSet" .XX "windows:removing from save-sets" .XX "save-set:removing windows from" .Na XRemoveFromSaveSet \(en remove a window from the client's save-set. .Nz .SH "Synopsis" .Sy XRemoveFromSaveSet\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window you want to remove from this client's save-set. This window must have been created by a client other than the client making this call. .SH Description \f(CWXRemoveFromSaveSet()\fP removes a window from the save-set of the calling application. .LP The save-set is a safety net for windows that have been reparented by the window manager, usually to provide a shadow or other background for each window. When the window manager dies unexpectedly, the windows in the save-set are reparented to their closest living ancestor, so that they remain alive. .LP This call is not necessary when a window is destroyed since destroyed windows are automatically removed from the save-set. Therefore, many window managers get away without ever calling \f(CWXRemoveFromSaveSet()\fP. See Volume One, Chapter 16, \fIWindow Management\fP, for more information about save-sets. .SH "Errors" .IP "\f(CWBadMatch\fP" 1i \f(CIw\fP not created by some other client. .br .IP "\f(CWBadWindow\fP" .SH "See Also" \s-1\fIXAddToSaveSet()\fP\s+1, \s-1\fIXChangeSaveSet()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XRemoveHost" "Xlib \- Host Access" .ds ]W Xlib Reference Manual .SH "Name" .XX "XRemoveHost" .XX "hosts:removing from access control lists" .XX "access control lists:removing hosts from" .Na XRemoveHost \(en remove a host from the access control list. .Nz .SH "Synopsis" .Sy XRemoveHost\^(\^\f(CIdisplay\f(CW, \f(CIhost\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XHostAddress *\f(CIhost\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIhost\fP 1i Specifies the network address of the machine to be removed. .SH Description \f(CWXRemoveHost()\fP removes the specified host from the access control list of the connected server. The server must be on the same host as the process that calls \f(CWXRemoveHost()\fP in order to change the access control list. .LP If you remove your own machine from the access control list, you can no longer connect to that server, and there is no way back from this call other than to log out, edit the access control file, and reset the server. The \f(CWaddress\fP data must be a valid address for the type of network in which the server operates, as specified in the \f(CWfamily\fP member. .LP For TCP/IP, the address should be in network byte order. For the DECnet family, the server performs no automatic swapping on the address bytes. A Phase IV address is two bytes long. The first byte contains the least significant eight bits of the node number. The second byte contains the most significant two bits of the node number in the least significant two bits of the byte, and the area in the most significant six bits of the byte. .LP For more information on access control lists, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "Structures" .Ps typedef struct { int family; /* for example Family Internet */ int length; /* length of address, in bytes */ char *address; /* pointer to where to find the bytes */ } XHostAddress; /* constants used for family member of XHostAddress */ .ta 4.5n 2.2i #define FamilyInternet 0 #define FamilyDECnet 1 #define FamilyChaos 2 .Pe .Nd 4 .SH "Errors" \f(CWBadAccess\fP .br \f(CWBadValue\fP .SH "See Also" \s-1\fIXAddHost()\fP\s+1, \s-1\fIXAddHosts()\fP\s+1, \s-1\fIXDisableAccessControl()\fP\s+1, \s-1\fIXEnableAccessControl()\fP\s+1, \s-1\fIXListHosts()\fP\s+1, \s-1\fIXRemoveHosts()\fP\s+1, \s-1\fIXSetAccessControl()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XRemoveHosts" "Xlib \- Host Access" .ds ]W Xlib Reference Manual .SH "Name" .XX "XRemoveHosts" .XX "hosts:removing from access control lists" .XX "access control lists:removing multiple hosts from" .Na XRemoveHosts \(en remove multiple hosts from the access control list. .Nz .SH "Synopsis" .Sy XRemoveHosts\^(\^\f(CIdisplay\f(CW, \f(CIhosts\f(CW, \f(CInum_hosts\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XHostAddress *\f(CIhosts\f(CW\^; int \f(CInum_hosts\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIhosts\fP 1i Specifies the list of hosts that are to be removed. .IP \f(CInum_hosts\fP 1i Specifies the number of hosts that are to be removed. .SH Description \f(CWXRemoveHosts()\fP removes each specified host from the access control list of the connected server. The server must be on the same host as the process that call \f(CWXRemoveHosts()\fP, in order to change the access control list. .LP If you remove your machine from the access control list, you can no longer connect to that server, and there is no way back from this call except to log out, edit the access control file, and reset the server. .LP The \f(CWaddress\fP data must be a valid address for the type of network in which the server operates, as specified in the \f(CWfamily\fP member. .LP For TCP/IP, the address should be in network byte order. For the DECnet family, the server performs no automatic swapping on the address bytes. A Phase IV address is two bytes long. The first byte contains the least significant eight bits of the node number. The second byte contains the most significant two bits of the node number in the least significant two bits of the byte, and the area in the most significant six bits of the byte. .LP For more information on access control lists, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "Structures" .Ps typedef struct { int family; /* for example Family Internet */ int length; /* length of address, in bytes */ char *address; /* pointer to where to find the bytes */ } XHostAddress; .XX "XHostAddress structure" .XX "structures:XHostAddress" /* constants used for family member of XHostAddress */ .ta 4.5n 2.2i #define FamilyInternet 0 #define FamilyDECnet 1 #define FamilyChaos 2 .Pe .ne 4 .SH "Errors" \f(CWBadAccess\fP .br \f(CWBadValue\fP .br .ne 4 .SH "See Also" \s-1\fIXAddHost()\fP\s+1, \s-1\fIXAddHosts()\fP\s+1, \s-1\fIXDisableAccessControl()\fP\s+1, \s-1\fIXEnableAccessControl()\fP\s+1, \s-1\fIXListHosts()\fP\s+1, \s-1\fIXRemoveHost()\fP\s+1, \s-1\fIXSetAccessControl()\fP\s+1. .\"last line comment .TH XRemoveHost.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XRemoveHost@XRemoveHosA .sp .5 XRemoveHosts@XRemoveHosB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XReparentWindow" "Xlib \- Window Manipulation" .ds ]W Xlib Reference Manual .SH "Name" .XX "XReparentWindow" .XX "windows:reparenting" .Na XReparentWindow \(en insert a window between another window and its parent. .Nz .SH "Synopsis" .Sy XReparentWindow\^(\^\f(CIdisplay\f(CW, \f(CIwin\f(CW\^, \f(CIparent\f(CW\^, \f(CIx\f(CW\^, \f(CIy\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIwin\f(CW\^; Window \f(CIparent\f(CW\^; int \f(CIx\f(CW\^, \f(CIy\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIwin\fP 1i Specifies the ID of the window to be reparented. .IP \f(CIparent\fP 1i Specifies the window ID of the new parent window. .IP \f(CIx\fP 1i Specify the coordinates of the window relative to the new parent. .sp -.5 .IP \f(CIy\fP 1i \0 .SH Description \f(CWXReparentWindow()\fP modifies the window hierarchy by placing window \f(CIwin\fP as a child of window \f(CIparent\fP. This function is usually used by a window manager to put a decoration window behind each application window. In the case of the window manager, the new parent window must first be created as a child of the root window. .LP If \f(CIwin\fP is mapped, an \f(CWXUnmapWindow()\fP request is performed on it automatically. \f(CIwin\fP is then removed from its current position in the hierarchy, and is inserted as a child of the specified parent. \f(CIwin\fP is placed on top in the stacking order with respect to siblings. .LP A \f(CWReparentNotify\fP event is then generated. The \f(CWoverride_redirect\fR member of the structure returned by this event is set to either \f(CWTrue\fR or \f(CWFalse.\fR Window manager clients normally should ignore this event if this member is set to \f(CWTrue\fR. .LP Finally, if the window was originally mapped, an \f(CWXMapWindow()\fP request is performed automatically. .LP Descendants of \f(CIwin\fR remain descendants of \f(CIwin\fR; they are not reparented to the old parent of \f(CIwin\fR. .LP Normal exposure processing on formerly obscured windows is performed. The server might not generate exposure events for regions from the initial unmap that are immediately obscured by the final map. The request fails if the new parent is not on the same screen as the old parent, or if the new parent is the window itself or an inferior of the window. .\" .br .\" .ne 9 .Nd 5 .SH "Errors" .IP "\f(CWBadMatch\fP" 1i \f(CIparent\fP not on same screen as old parent of \f(CIwin\fP. .sp .25 \f(CIwin\fP has a \f(CWParentRelative\fP background and \f(CIparent\fP is not the same depth as \f(CIwin\fP. .sp .25 \f(CIparent\fP is \f(CIwin\fP or an inferior of \f(CIwin\fP. .IP "\f(CWBadWindow\fP" \f(CIparent\fP is \f(CWInputOnly\fR and \f(CIwin\fP is not. .\" .ne 4 .SH "See Also" \s-1\fIXCirculateSubwindows()\fP\s+1, \s-1\fIXCirculateSubwindowsDown()\fP\s+1, \s-1\fIXCirculateSubwindowsUp()\fP\s+1, \s-1\fIXConfigureWindow()\fP\s+1, \s-1\fIXLowerWindow()\fP\s+1, \s-1\fIXMoveResizeWindow()\fP\s+1, \s-1\fIXMoveWindow()\fP\s+1, \s-1\fIXQueryTree()\fP\s+1, \s-1\fIXRaiseWindow()\fP\s+1, \s-1\fIXResizeWindow()\fP\s+1, \s-1\fIXRestackWindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XResetScreenSaver" "Xlib \- Screen Saver" .ds ]W Xlib Reference Manual .SH "Name" .XX "XResetScreenSaver" .XX "screen savers:resetting" .Na XResetScreenSaver \(en reset the screen saver. .Nz .SH "Synopsis" .Sy XResetScreenSaver\^(\^\f(CIdisplay\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Description \f(CWXResetScreenSaver()\fP redisplays the screen if the screen saver was activated. This may result in exposure events to all visible windows if the server cannot save the screen contents. If the screen is already active, nothing happens. .LP For more information on the screen saver, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "See Also" \s-1\fIXActivateScreenSaver()\fP\s+1, \s-1\fIXForceScreenSaver()\fP\s+1, \s-1\fIXGetScreenSaver()\fP\s+1, \s-1\fIXSetScreenSaver()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XResizeWindow" "Xlib \- Window Manipulation" .ds ]W Xlib Reference Manual .SH "Name" .XX "XResizeWindow" .XX "windows:resizing " .Na XResizeWindow \(en change a window's size. .Nz .SH "Synopsis" .Sy XResizeWindow\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; unsigned int \f(CIwidth\f(CW\^, \f(CIheight\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window to be resized. .IP \f(CIwidth\fP 1i Specify the new dimensions of the window in pixels. .sp -.5 .IP \f(CIheight\fP 1i .SH Description \f(CWXResizeWindow()\fP changes the inside dimensions of the window. The border is resized to match but its border width is not changed. \f(CWXResizeWindow()\fP does not raise the window, or change its origin. Changing the size of a mapped window may lose its contents and generate an \f(CWExpose\fP event, depending on the \f(CWbit_gravity\fP attribute (see Volume One, Chapter\ 4, \fIWindow Attributes\fR). If a mapped window is made smaller, exposure events will be generated on windows that it formerly obscured. .LP If the \f(CWoverride_redirect\fP attribute of the window is \f(CWFalse\fP and the window manager has selected \f(CWSubstructureRedirectMask\fP on the parent, then a \f(CWConfigureRequest\fP event is sent to the window manager, and no further processing is performed. .LP If the client has selected \f(CWStructureNotifyMask\fP on the window, then a \f(CWConfigureNotify\fP event is generated after the move takes place, and the event will contain the final size of the window. .SH "Errors" .IP "\&\f(CWBadValue\fP" 1i Either width or height is zero. .IP "\f(CWBadWindow\fP" .SH "See Also" \s-1\fIXCirculateSubwindows()\fP\s+1, \s-1\fIXCirculateSubwindowsDown()\fP\s+1, \s-1\fIXCirculateSubwindowsUp()\fP\s+1, \s-1\fIXConfigureWindow()\fP\s+1, \s-1\fIXLowerWindow()\fP\s+1, \s-1\fIXMoveResizeWindow()\fP\s+1, \s-1\fIXMoveWindow()\fP\s+1, \s-1\fIXQueryTree()\fP\s+1, \s-1\fIXRaiseWindow()\fP\s+1, \s-1\fIXReparentWindow()\fP\s+1, \s-1\fIXRestackWindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XResourceManagerString" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .XX "XResourceManagerString" .XX "resource properties:server, obtaining" .XX "servers:resource properties, obtaining" .SH Name .Na XResourceManagerString \(en return the RESOURCE_MANAGER property. .Nz .SH Synopsis .Sy char *XResourceManagerString\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .SH Returns The resource manager property string. .SH Description \f(CWXResourceManagerString()\fR returns the RESOURCE_MANAGER property from the root window of screen zero, which was returned when the connection was opened using \f(CWXOpenDisplay()\fR. The property is converted from type STRING to the current locale. The conversion is identical to that produced by \f(CWXmbTextPropertyToTextList()\fR for a singleton STRING property. The returned string is owned by Xlib, and should not be freed by the client. Note that the property value must be in a format that is acceptable to \f(CWXrmGetStringDatabase()\fR. If no property exists, \f(CWNULL\fP is returned. .SH "See Also" \s-1\fIXScreenResourceString()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XRestackWindows" "Xlib \- Window Manipulation" .ds ]W Xlib Reference Manual .SH "Name" .XX "XRestackWindows" .XX "windows:restacking" .Na XRestackWindows \(en change the stacking order of siblings. .Nz .SH "Synopsis" .Sy XRestackWindows\^(\^\f(CIdisplay\f(CW, \f(CIwindows\f(CW\^, \^\f(CInwindows\f(CW\^); .As Display *\f(CIdisplay\f(CW\^; Window \f(CIwindows\f(CW\^[]; int \f(CInwindows\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIwindows\fP 1i Specifies an array containing the windows to be restacked. All the windows must have a common parent. .IP \f(CInwindows\fP 1i Specifies the number of windows in the \f(CIwindows\fP array. .SH Description \f(CWXRestackWindows()\fP restacks the windows in the order specified, from top to bottom. The stacking order of the first window in the \f(CIwindows\fP array will be on top, and the other windows will be stacked underneath it in the order of the array. Note that you can exclude other siblings from the \f(CIwindows\fP array so that the top window in the array will not move relative to these other siblings. .LP For each window in the window array that is not a child of the specified window, a \&\f(CWBadMatch\fP error will be generated. If the \f(CWoverride_redirect\fP attribute of the window is \f(CWFalse\fP and the window manager has selected \f(CWSubstructureRedirectMask\fP on the parent, then \f(CWConfigureRequest\fP events are sent to the window manager for each window whose \f(CWoverride_redirect\fP is not set, and no further processing is performed. Otherwise, the windows will be restacked in top to bottom order. .SH "Errors" \&\f(CWBadMatch\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXCirculateSubwindows()\fP\s+1, \s-1\fIXCirculateSubwindowsDown()\fP\s+1, \s-1\fIXCirculateSubwindowsUp()\fP\s+1, \s-1\fIXConfigureWindow()\fP\s+1, \s-1\fIXLowerWindow()\fP\s+1, \s-1\fIXMoveResizeWindow()\fP\s+1, \s-1\fIXMoveWindow()\fP\s+1, \s-1\fIXQueryTree()\fP\s+1, \s-1\fIXRaiseWindow()\fP\s+1, \s-1\fIXReparentWindow()\fP\s+1, \s-1\fIXResizeWindow()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XRootWindow*" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XRootWindow, XRootWindowOfScreen, RootWindow, RootWindowOfScreen \(en return root window ID. .XX "XRootWindowOfScreen" .XX "XRootWindow" .Nz .\" .\" .SH "Synopsis" .Sy Window XRootWindow\^(\^\f(CIdisplay\fP\^, \^\f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; int \f(CIscreen_number\fP\^; .Ae .Sy Window XRootWindowOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number on the host server. .IP \f(CIscreen\fP 1i Specifies the appropriate \f(CWScreen\fP structure. .\" .\" .SH Returns The window ID. .SH Description .XX "root window:of screen, returning" .XX "screens:root window, returning" .XN "windows:root (see root window)" \f(CWXRootWindow()\fP and \f(CWXRootWindowOfScreen()\fP return the root window of the specified screen. The only difference between them is their arguments. These are useful as arguments of functions that need a drawable of a particular screen (such as \f(CWXCreatePixmap()\fP or \f(CWXCreateGC()\fP), and for creating top-level windows. .LP .XX "RootWindow macro" .XX "RootWindowOfScreen macro" The C language macros \f(CWRootWindow()\fP and \f(CWRootWindowOfScreen()\fP are equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXDefaultRootWindow*()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XRotateBuffers" "Xlib \- Cut Buffers" .ds ]W Xlib Reference Manual .SH "Name" .XX "XRotateBuffers" .XX "buffers:rotating" .Na XRotateBuffers \(en rotate the cut buffers. .Nz .SH "Synopsis" .Sy XRotateBuffers\^(\^\f(CIdisplay\f(CW, \f(CIrotate\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int \f(CIrotate\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIrotate\fP 1i Specifies how many positions to rotate the cut buffers. .SH Description \f(CWXRotateBuffers()\fP rotates the 8 cut buffers the amount specified by \f(CIrotate\fP. The contents of buffer 0 moves to buffer \f(CIrotate\fP, contents of buffer 1 moves to buffer (\f(CIrotate\fP+1) mod 8, contents of buffer 2 moves to buffer (\f(CIrotate\fP+2) mod 8, and so on. .LP This routine will not work if any of the buffers have not been stored into with \f(CWXStoreBuffer()\fP or \f(CWXStoreBytes()\fP. .LP This cut buffer numbering is global to the display. .LP See the description of cut buffers in Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "Errors" .IP "\f(CWBadMatch\fP" .SH "See Also" \s-1\fIXFetchBuffer()\fP\s+1, \s-1\fIXFetchBytes()\fP\s+1, \s-1\fIXStoreBuffer()\fP\s+1, \s-1\fIXStoreBytes()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XRotateWindowProperties" "Xlib \- Properties" .ds ]W Xlib Reference Manual .SH "Name" .XX "XRotateWindowProperties" .Na XRotateWindowProperties \(en rotate properties in the properties array. .sp -.15 .Nz .SH "Synopsis" .Sy XRotateWindowProperties\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIproperties\f(CW, \f(CInum_prop\f(CW, \f(CInpositions\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; Atom \f(CIproperties\f(CW\^[]\^; int \f(CInum_prop\f(CW\^; int \f(CInpositions\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window whose properties are to be rearranged. .IP \f(CIproperties\fP 1i Specifies the list of properties to be rotated. .IP \f(CInum_prop\fP 1i Specifies the length of the properties array. .IP \f(CInpositions\fP 1i Specifies the number of positions to rotate the property list. The sign controls the direction of rotation. .SH Description .XX "windows:rotating contents of an array of properties on" \f(CWXRotateWindowProperties()\fP rotates the contents of an array of properties on a window. If the property names in the \f(CIproperties\fP array are viewed as if they were numbered starting from 0 and if there are \f(CInum_prop\fP property names in the list, then the value associated with property name \fII\fR becomes the value associated with property name (\fII\fR + \f(CInpositions\fP) mod \f(CInum_prop\fP, for all \fII\fR from 0 to \f(CInum_prop\fP \- 1. Therefore, the sign of \f(CInpositions\fP controls the direction of rotation. The effect is to rotate the states by \f(CInpositions\fP places around the virtual ring of property names (right for positive \f(CInpositions\fP, left for negative \f(CInposition\fP). .LP If \f(CInpositions\fP mod \f(CInum_prop\fP is non-zero, a \f(CWPropertyNotify\fP event is generated for each property, in the order listed. .LP If a \f(CWBadAtom\fP, \f(CWBadMatch\fP, or \f(CWBadWindow\fP error is generated, no properties are changed. .SH "Errors" .IP "\f(CWBadAtom\fP" 1i Undefined atom in the property list. .IP "\f(CWBadMatch\fP" 1i An atom appears more that once in the list or no property with that name is defined for the window. .IP "\f(CWBadWindow\fP" 1i .Nd 6 .SH "See Also" \s-1\fIXChangeProperty()\fP\s+1, \s-1\fIXDeleteProperty()\fP\s+1, \s-1\fIXGetAtomName()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXGetWindowProperty()\fP\s+1, \s-1\fIXInternAtom()\fP\s+1, \s-1\fIXListProperties()\fP\s+1, \s-1\fIXSetStandardProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSaveContext" "Xlib \- Context Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSaveContext" .XX "context:saving" .Na XSaveContext \(en save a data value corresponding to a resource ID and context type (not graphics context). .Nz .SH "Synopsis" .Sy int XSaveContext(\^\f(CIdisplay\f(CW, \f(CIrid\f(CW, \f(CIcontext\f(CW, \f(CIdata\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XID \f(CIrid\f(CW\^; XContext \f(CIcontext\f(CW\^; caddr_t \f(CIdata\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIrid\fP 1i Specifies the ID of the resource with which the data is associated. .IP \f(CIcontext\fP 1i Specifies the context type to which the data corresponds. .IP \f(CIdata\fP 1i Specifies the data to be associated with the resource and context. .SH Returns \f(CWXCNOMEM\fP (a non-zero error code) if an error has occurred or zero (0) otherwise. .SH Description \f(CWXSaveContext()\fP saves \f(CIdata\fP to the context manager database, according to the specified resource and \f(CIcontext\fP ID. The context manager is used for associating data with windows within an application. The client must have called \f(CWXUniqueContext()\fP to get the \f(CIcontext\fP ID before calling this function. The meaning of the \f(CIdata\fP is indicated by the \f(CIcontext\fP ID, but is completely up to the client. .LP If an entry with the specified resource and \f(CIcontext\fP ID already exists, \f(CWXSaveContext()\fP writes over it with the specified data. .\" .\" .\"However, this has costs in time and space. .\"If you know the entry already exists, it is better to call .\"\f(CWXDeleteContext()\fP first. .LP The \f(CWXSaveContext()\fP function returns \f(CWXCNOMEM\fP (a non-zero error code) if an error has occurred and zero (0) otherwise. For more information, see the description of the context manager in Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH Structures .Ps typedef int XContext; .Pe .SH "See Also" \s-1\fIXDeleteContext()\fP\s+1, \s-1\fIXFindContext()\fP\s+1, \s-1\fIXUniqueContext()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XScreen" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XScreenCount, XScreenNumberOfScreen, XScreenOfDisplay, ScreenCount, ScreenNumberOfScreen, ScreenOfDisplay \(en get screen information. .XX "XScreenCount" .XX "XScreenNumberOfScreen" .XX "XScreenOfDisplay" .Nz .\" .\" .SH "Synopsis" .Sy int XScreenCount\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .Sy int XScreenNumberOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .Sy Screen *XScreenOfDisplay\^(\^\f(CIdisplay\fP, \f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; int \f(CIscreen_number\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIscreen\fP 1i Specifies the appropriate \f(CWScreen\fP structure. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number on the host server. .\" .\" .SH Returns The number of screens, a screen number, or a \f(CWScreen\fP structure. .SH Description .XX "screens:number of, returning" \f(CWXScreenCount()\fP returns the number of screens on the specified display. .XX "screens:numbers" \f(CWXScreenNumberOfScreen()\fP returns a screen number given a pointer to a \f(CWScreen\fP structure. .XX "screens:Screen structures, returning" \f(CWXScreenOfDisplay()\fP returns pointer to a \f(CWScreen\fP structure given the screen number. \f(CWXScreenNumberOfScreen()\fP and \f(CWXScreenOfDisplay()\fP are opposites. .LP .XX "ScreenCount macro" .XX "ScreenNumberOfScreen macro" .XX "ScreenOfDisplay macro" The C language macros \f(CWScreenCount()\fP, \f(CWScreenNumberOfScreen()\fP, and \f(CWScreenOfDisplay()\fP are equivalent and slightly more efficient. .\" .\" .SH "See Also" \s-1\fIXDefaultScreenOfDisplay()\fP\s+1, \s-1\fIXDefaultScreen*()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XScreenResourceString" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .XX "XScreenResourceString" .XX "servers:resource properties, obtaining" .XX "resource properties:server, obtaining" .SH Name .Na XScreenResourceString \(en return the SCREEN_RESOURCES property. .Nz .SH Synopsis .Sy char *XScreenResourceString\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .SH Arguments .IP \f(CIscreen\fP 1i Specifies the screen. .SH Returns The property data string. .SH Availability Release 5 and later. .SH Description \f(CWXScreenResourceString()\fR returns the SCREEN_RESOURCES property from the root window of the specified screen. The property is converted from type STRING to the current locale. The conversion is identical to that produced by \f(CWXmbTextPropertyToTextList()\fR for a singleton STRING property. Note that the property value must be in a format that is acceptable to \f(CWXrmGetStringDatabase()\fR. If no property exists, \f(CWNULL\fP is returned. The caller is responsible for freeing the returned string, using \f(CWXFree()\fR. .LP \f(CWXScreenResourceString()\fP reads the window property each time it is requested. This differs from the behavior of \f(CWXResourceManagerString()\fP which simply returns the value of the property as it was defined when the connection with the X server was established. .SH "See Also" \s-1\fIXResourceManagerString()\fP\s+1. .\"last line comment .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XSeBMap.man,v 1.5 94/06/04 17:32:34 rws Exp $ .ds xL Programming With Xlib .TH XSetDeviceButtonMapping 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XSetDeviceButtonMapping, XGetDeviceButtonMapping \- query or change device button mappings .SH SYNTAX int XSetDeviceButtonMapping\^(\^\fIdisplay\fP, \fIdevice\fP, \fImap\fP, \fInmap\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br unsigned char \fImap\fP\^[]\^; .br int \fInmap\fP\^; .sp int XGetDeviceButtonMapping\^(\^\fIdisplay\fP, \fIdevice\fP, \fImap_return\fP, \fInmap\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br unsigned char \fImap_return\fP\^[]\^; .br int \fInmap\fP\^; .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device whose button mapping is to be queried or changed. .TP 12 .I map Specifies the mapping list. .TP 12 .I map_return Returns the mapping list. .TP 12 .I nmap Specifies the number of items in the mapping list. .SH DESCRIPTION The \fIXSetDeviceButtonMapping\fP request sets the mapping of the specified device. If it succeeds, the X server generates a \fIDeviceMappingNotify\fP event, and \fIXSetDeviceButtonMapping\fP returns \fIMappingSuccess\fP. Element map[i] defines the logical button number for the physical button i+1. The length of the list must be the same as \fIXGetDeviceButtonMapping\fP would return, or a \fIBadValue\fP error results. A zero element disables a button, and elements are not restricted in value by the number of physical buttons. However, no two elements can have the same nonzero value, or a \fIBadValue\fP error results. If any of the buttons to be altered are logically in the down state, \fIXSetDeviceButtonMapping\fP returns \fIMappingBusy\fP, and the mapping is not changed. .LP \fIXSetDeviceButtonMapping\fP can generate \fIBadDevice\fP, \fIBadMatch\fP, and \fIBadValue\fP errors. .LP The \fIXGetDeviceButtonMapping\fP request returns the current mapping of the specified device. Buttons are numbered starting from one. \fIXGetDeviceButtonMapping\fP returns the number of physical buttons actually on the device. The nominal mapping for a device is map[i]=i+1. The nmap argument specifies the length of the array where the device mapping is returned, and only the first nmap elements are returned in map_return. .LP \fIXGetDeviceButtonMapping\fP can generate \fIBadDevice\fP or \fIBadMatch\fP errors. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if the specified device is the X keyboard or X pointer device. .TP 12 \fIBadMatch\fP This error may occur if an \fIXGetDeviceButtonMapping\fP or \fIXSetDeviceButtonMapping\fP request was made specifying a device that has no buttons. .TP 12 \fIBadValue\fP Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error. .SH "SEE ALSO" XChangeDeviceKeyboardControl(3X), .br XChangeDeviceKeyMapping(3X) .br XChangeDeviceModifierMapping(3X) .br .br \fI\*(xL\fP .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XSeDvFoc.man,v 1.5 94/06/04 17:32:36 rws Exp $ .ds xL Programming with Xlib .TH XSetDeviceFocus 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XSetDeviceFocus, XGetDeviceFocus \- control extension input device focus .SH SYNTAX XSetDeviceFocus\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fIfocus\fP\^, \fIrevert_to\fP\^, \fItime\fP\^) .br Display *\fIdisplay\fP\^; .br Display *\fIdevice\fP\^; .br Window \fIfocus\fP\^; .br int \fIrevert_to\fP\^; .br Time \fItime\fP\^; .sp XGetDeviceFocus\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fIfocus_return\fP\^, \fIrevert_to_return\fP, \fItime_return\fP\^) .br Display *\fIdisplay\fP\^; .br Display *\fIdevice\fP\^; .br Window *\fIfocus_return\fP\^; .br int *\fIrevert_to_return\fP\^; .br int *\fItime_return\fP\^; .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device whose focus is to be queried or changed. .TP 12 .I focus Specifies the window, \fIPointerRoot\fP, \fIFollowKeyboard\fP, or \fINone\fP. .TP 12 .I focus_return Returns the focus window, \fIPointerRoot\fP, \fIFollowKeyboard\fP, or \fINone\fP. .TP 12 .I revert_to Specifies where the input focus reverts to if the window becomes not viewable. You can pass \fIRevertToParent\fP, \fIRevertToPointerRoot\fP, \fIRevertToFollowKeyboard\fP, or \fIRevertToNone\fP. .TP 12 .I revert_to_return Returns the current focus state \fIRevertToParent\fP, \fIRevertToPointerRoot\fP, \fIRevertToFollowKeyboard\fP, or \fIRevertToNone\fP. .TP 12 .I time_return Returns the last_focus_time for the device. .TP 12 .I time Specifies the time. You can pass either a timestamp or \fICurrentTime\fP. .SH DESCRIPTION The \fIXSetDeviceFocus\fP request changes the focus of the specified device and its last-focus-change time. It has no effect if the specified time is earlier than the current last-focus-change time or is later than the current X server time. Otherwise, the last-focus-change time is set to the specified time \fICurrentTime\fP is replaced by the current X server time). \fIXSetDeviceFocus\fP causes the X server to generate \fIDeviceFocusIn\fP and \fIDeviceFocusOut\fP events. .LP Depending on the focus argument, the following occurs: .IP \(bu 5 If focus is \fINone\fP , all device events are discarded until a new focus window is set, and the revert_to argument is ignored. .IP \(bu 5 If focus is a window, it becomes the device's focus window. If a generated device event would normally be reported to this window or one of its inferiors, the event is reported as usual. Otherwise, the event is reported relative to the focus window. .IP \(bu 5 If focus is \fIPointerRoot\fP, the focus window is dynamically taken to be the root window of whatever screen the pointer is on at each event from the specified device. In this case, the revert_to argument is ignored. .IP \(bu 5 If focus is \fIFollowKeyboard\fP, the focus window is dynamically taken to be the window to which the X keyboard focus is set at each input event. .LP The specified focus window must be viewable at the time \fIXSetDeviceFocus\fP is called, or a \fIBadMatch\fP error results. If the focus window later becomes not viewable, the X server evaluates the revert_to argument to determine the new focus window as follows: .IP \(bu 5 If revert_to is \fIRevertToParent\fP, the focus reverts to the parent (or the closest viewable ancestor), and the new revert_to value is taken to be \fIRevertToNone\fP. .IP \(bu 5 If revert_to is \fIRevertToPointerRoot\fP, \fIRevertToFollowKeyboard\fP, or \fIRevertToNone\fP, the focus reverts to \fIPointerRoot\fP, \fIFollowKeyboard\fP, or \fINone\fP, respectively. .LP When the focus reverts, the X server generates \fIDeviceFocusIn\fP and \fIDeviceFocusOut\fP events, but the last-focus-change time is not affected. .LP Input extension devices are not required to support the ability to be focused. Attempting to set the focus of a device that does not support this request will result in a \fIBadMatch\fP error. Whether or not given device can support this request can be determined by the information returned by \fIXOpenDevice\fP. For those devices that support focus, \fIXOpenDevice\fP will return an \fIXInputClassInfo\fP structure with the input_class field equal to the constant \fIFocusClass\fP (defined in the file \fIXI.h\fP). .LP \fIXSetDeviceFocus\fP can generate \fIBadDevice\fP, \fIBadMatch\fP, \fIBadValue\fP, and \fIBadWindow\fP errors. .LP The \fIXGetDeviceFocus\fP request returns the focus window and the current focus state. .LP Not all input extension devices can be focused. Attempting to query the focus state of a device that can't be focused results in a \fIBadMatch\fP error. A device that can be focused returns information for input Class Focus when an \fIXOpenDevice\fP request is made. .LP \fIXGetDeviceFocus\fP can generate \fIBadDevice\fP, and \fIBadMatch\fP errors. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if the specified device is the X keyboard or X pointer device. .TP 12 \fIBadValue\fP Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error. .TP 12 \fIBadWindow\fP A value for a Window argument does not name a defined Window. .TP 12 \fIBadMatch\fP This error may occur if an \fIXGetDeviceFocus\fP or \fIXSetDeviceFocus\fP request was made specifying a device that the server implementation does not allow to be focused. .SH "SEE ALSO" .br \fI\*(xL\fP .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XSelExtEv.man,v 1.6 94/06/04 17:32:37 rws Exp $ .ds xL Programming with Xlib .TH XSelectExtensionEvent 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XSelectExtensionEvent, XGetSelectedExtensionEvents \- select extension events, get the list of currently selected extension events .SH SYNTAX XSelectExtensionEvent\^(\^\fIdisplay\fP, \fIw\fP\^, \fIevent_list\fP\^, \fIevent_count\fP\^) .br Display *\fIdisplay\fP\^; .br Window \fIw\fP\^; .br XEventClass *\fIevent_list\fP\^; .br int \fIevent_count\fP\^; .sp XGetSelectedExtensionEvents\^(\^\fIdisplay\fP, \fIw\fP\^, \fIthis_client_event_count_return\fP\^, .br \fIthis_client_event_list_return\fP\^, \fIall_clients_event_count_return\fP\^, \fIall_clients_event_list_return\fP\^) .br Display *\fIdisplay\fP\^; .br Window \fIw\fP\^; .br int \fIthis_client_event_count_return\fP\^; .br XEventClass *\fIthis_client_event_list_return\fP\^; .br int \fIall_clients_event_count_return\fP\^; .br XEventClass *\fIall_clients_event_list_return\fP\^; .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .ds Wi whose events you are interested in .TP 12 .I w Specifies the window \*(Wi. .TP 12 .I event_list Specifies the list of event classes that describe the events you are interested in. .TP 12 .I event_count Specifies the count of event classes in the event list. .TP 12 .I this_client_event_count_return Returns the count of event classes selected by this client. .TP 12 .I this_client_event_list_return Returns a pointer to the list of event classes selected by this client. .TP 12 .I all_clients_event_count_return Returns the count of event classes selected by all clients. .TP 12 .I all_clients_event_list_return Returns a pointer to the list of event classes selected by all clients. .SH DESCRIPTION The \fIXSelectExtensionEvent\fP request causes the X server to report the events associated with the specified list of event classes. Initially, X will not report any of these events. Events are reported relative to a window. If a window is not interested in a device event, it usually propagates to the closest ancestor that is interested, unless the do_not_propagate mask prohibits it. .LP Multiple clients can select for the same events on the same window with the following restrictions: .IP \(bu 5 Multiple clients can select events on the same window because their event masks are disjoint. When the X server generates an event, it reports it to all interested clients. .IP \(bu 5 Only one client at a time can select a \fIDeviceButtonPress\fP event with automatic passive grabbing enabled, which is associated with the event class \fIDeviceButtonPressGrab\fP. To receive \fIDeviceButtonPress\fP events without automatic passive grabbing, use event class \fIDeviceButtonPress\fP but do not specify event class \fIDeviceButtonPressGrab\fP. .LP The server reports the event to all interested clients. .LP Information contained in the \fIXDevice\fP structure returned by \fIXOpenDevice\fP is used by macros to obtain the event classes that clients use in making \fIXSelectExtensionEvent\fP requests. Currently defined macros include \fIDeviceKeyPress\fP, \fIDeviceKeyRelease\fP, \fIDeviceButtonPress\fP, \fIDeviceButtonRelese\fP, \fIDeviceMotionNotify\fP, \fIDeviceFocusIn\fP, \fIDeviceFocusOut\fP, \fIProximityIn\fP, \fIProximityOut\fP, \fIDeviceStateNotify\fP, \fIDeviceMappiingNotify\fP, \fIChangeDeviceNotify\fP, \fIDevicePointerMotionHint\fP, \fIDeviceButton1Motion\fP, \fIDeviceButton2Motion\fP, \fIDeviceButton3Motion\fP, \fIDeviceButton4Motion\fP, \fIDeviceButton5Motion\fP, \fIDeviceButtonMotion\fP, \fIDeviceOwnerGrabButton\fP, \fIDeviceButtonPressGrab\fP, and \fINoExtensionEvent\fP. .LP To obtain the proper event class for a particular device, one of the above macros is invoked using the \fIXDevice\fP structure for that device. For example, .LP .DS 0 .TA .5i .ta .5i DeviceKeyPress (*device, type, eventclass); .DE .LP returns the \fIDeviceKeyPress\fP event type and the eventclass for selecting \fIDeviceKeyPress\fP events from this device. .LP \fIXSelectExtensionEvent\fP can generate a \fIBadWindow\fP or \fIBadClass\fP error. The \fIXGetSelectedExtensionEvents\fP request reports the extension events selected by this client and all clients for the specified window. This request returns pointers to two \fIXEventClass\fP arrays. One lists the input extension events selected by this client from the specified window. The other lists the event classes selected by all clients from the specified window. You should use \fIXFree\fP to free these two arrays. .LP \fIXGetSelectedExtensionEvents\fP can generate a \fIBadWindow\fP error. .SH DIAGNOSTICS .TP 12 \fIBadWindow\fP A value for a Window argument does not name a defined Window. .TP 12 \fIBadClass\fP A value for an XEventClass argument is invalid. .SH "SEE ALSO" .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSelectInput" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSelectInput" .XX "event types:selecting for windows" .Na XSelectInput \(en select the event types to be sent to a window. .Nz .SH "Synopsis" .Sy XSelectInput\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIevent_mask\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; long \f(CIevent_mask\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window interested in the events. .IP \f(CIevent_mask\fP 1i Specifies the event mask. This mask is the bitwise OR of one or more of the valid event mask bits (see below). .SH Description .XX "windows:defining input events interested in" \f(CWXSelectInput()\fP defines which input events the window is interested in. If a window is not interested in a device event (button, key, motion, or border crossing), it propagates up to the closest ancestor unless otherwise specified in the \f(CWdo_not_propagate_mask\fP attribute. .LP The bits of the mask are defined in <\&\fIX11/X.h\fP> : .sp .8 .nf .mk .ta 3n 5n ButtonPressMask NoEventMask ButtonReleaseMask KeyPressMask EnterWindowMask KeyReleaseMask LeaveWindowMask ExposureMask PointerMotionMask VisibilityChangeMask PointerMotionHintMask StructureNotifyMask Button1MotionMask ResizeRedirectMask Button2MotionMask SubstructureNotifyMask Button3MotionMask SubstructureRedirectMask Button4MotionMask FocusChangeMask Button5MotionMask PropertyChangeMask ButtonMotionMask ColormapChangeMask KeymapStateMask OwnerGrabButtonMask .in 0 .fi .ft R .LP .sp .3 A call on \f(CWXSelectInput()\fP overrides any previous call on \f(CWXSelectInput()\fP for the same window from the same client but not for other clients. Multiple clients can select input on the same window; their \f(CWevent_mask\fP window attributes are disjoint. When an event is generated it will be reported to all interested clients. However, only one client at a time can select for each of \f(CWSubstructureRedirectMask\fP, \f(CWResizeRedirectMask\fP, and \f(CWButtonPress\fP. .LP If a window has both \f(CWButtonPressMask\fP and \f(CWButtonReleaseMask\fP selected, then a \f(CWButtonPress\fP event in that window will automatically grab the mouse until all buttons are released, with events sent to windows as described for \f(CWXGrabPointer()\fP. This ensures that a window will see the \f(CWButtonRelease\fP event .ne 2 corresponding to the \f(CWButtonPress\fP event, even though the mouse may have exited the window in the meantime. .LP If \f(CWPointerMotionMask\fP is selected, events will be sent independent of the state of the mouse buttons. If instead, one or more of \f(CWButton1MotionMask\fP, \f(CWButton2MotionMask\fP, \f(CWButton3MotionMask\fP, \f(CWButton4MotionMask\fP, or \f(CWButton5MotionMask\fP is selected, \f(CWMotionNotify\fP events will be generated only when one or more of the specified buttons is depressed. .LP \f(CWXCreateWindow()\fP and \f(CWXChangeWindowAttributes()\fP can also set the \f(CIevent_mask\fP attribute. .LP For more information, see Volume One, Chapter 8, \fIEvents\fR. .br .ne 4 .SH "Errors" .IP \f(CWBadValue\fP 1i Specified event mask invalid. .IP \f(CWBadWindow\fP .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSendEvent" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSendEvent" .XX "events:sending" .Na XSendEvent \(en send an event. .Nz .SH "Synopsis" .Sy Status XSendEvent\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIpropagate\f(CW\^, \f(CIevent_mask\f(CW\^, \f(CIevent_send\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; Bool \f(CIpropagate\f(CW\^; long \f(CIevent_mask\f(CW\^; XEvent *\f(CIevent_send\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window where you want to send the event. Pass the window resource ID, \f(CWPointerWindow\fP, or \f(CWInputFocus\fP. .IP \f(CIpropagate\fP 1i Specifies how the sent event should propagate depending on \f(CIevent_mask\fP. See description below. May be \f(CWTrue\fP or \f(CWFalse\fP. .IP \f(CIevent_mask\fP 1i Specifies the event mask. See \f(CWXSelectInput()\fP for a detailed list of the event masks. .IP \f(CIevent_send\fP 1i Specifies a pointer to the event to be sent. .SH Returns Zero on failure, non-zero on success. .SH Description \f(CWXSendEvent()\fP sends an event from one client to another (or conceivably to itself). This function is used for communication between clients using selections, for simulating user actions in demos, and for other purposes. .LP The specified event is sent to the window indicated by \f(CIw\fP regardless of active grabs. .LP If \f(CIw\fP is set to \f(CWPointerWindow\fP, the destination of the event will be the window that the pointer is in. If \f(CIw\fP is \f(CWInputFocus\fP is specified, then the destination is the focus window, regardless of pointer position. .LP If \f(CIpropagate\fP is \f(CWFalse\fP, then the event is sent to every client selecting on the window specified by \f(CIw\fP any of the event types in \f(CIevent_mask\fP. If \f(CIpropagate\fP is \f(CWTrue\fP and no clients have been selected on \f(CIw\fP any of the event types in \f(CIevent_mask\fP, then the event propagates like any other event. .LP The event code must be one of the core events, or one of the events defined by a loaded extension, so that the server can correctly byte swap the contents as necessary. The contents of the event are otherwise unaltered and unchecked by the server. .ne 2 The \f(CWsend_event\fP field is in every event type; if \f(CWTrue\fP it indicates that the event was sent with \f(CWXSendEvent()\fP. .LP .br .ne 3 .LP This function is often used in selection processing. For example, the owner of a selection should use \f(CWXSendEvent()\fR to send a \f(CWSelectionNotify\fR event to a requestor when a selection has been converted and stored as a property. See Volume One, Chapter 12, \fIInterclient Communication\fR for more information. .LP The status returned by \f(CWXSendEvent()\fR indicates whether or not the given \f(CWXEvent\fR structure was successfully converted into a wire event. This value is zero on failure, or non-zero on success. .SH "Errors" .IP "\f(CWBadValue\fP" 1i Specified event is not a valid core or extension event type, or event mask is invalid. .IP \f(CWBadWindow\fP .SH "Structures" See Appendix E, \fIEvent Reference\fR, for the contents of each event structure. .ps .vs .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XSExEvnt.man,v 1.5 94/06/04 17:32:33 rws Exp $ .ds xL Programming with Xlib .TH XSendExtensionEvent 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XSendExtensionEvent \- send input extension events to a client .SH SYNTAX Status XSendExtensionEvent\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fIdestination\fP\^, \fIpropagate\fP\^, \fIevent_count\fP\^, \fIevent_list\fP\^, \fIevent_send\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br Window \fIdestination\fP\^; .br Bool \fIpropagate\fP\^; .br int \fIevent_count\fP\^; .br XEventClass *\fIevent_list\fP\^; .br XEvent *\fIevent_send\fP\^; .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device from which the events are to be sent. .TP 12 .I destination Specifies the window the event is to be sent to. You can pass window id, \fIPointerWindow\fP, \ or \ \fIInputFocus\fP. .TP 12 .I propagate Specifies a Boolean value that is either True or False. .TP 12 .I event_count Specifies the count of XEventClasses in event_list. .TP 12 .I event_list Specifies the list of event selections to be used. .TP 12 .I event_send Specifies a pointer to the event that is to be sent. .TP 12 .SH DESCRIPTION The \fIXSendExtensionEvent\fP request identifies the destination window, determines which clients should receive the specified events, and ignores any active grabs. This request requires you to pass an event class list. For a discussion of the valid event class names, see \fIXOpenDevice(3X11)\fP. This request uses the w argument to identify the destination window as follows: .IP \(bu 5 If w is \fIPointerWindow\fP , the destination window is the window that contains the pointer. .IP \(bu 5 If w is \fIInputFocus\fP and if the focus window contains the pointer, the destination window is the window that contains the pointer; otherwise, the destination window is the focus window. .LP To determine which clients should receive the specified events, \fIXSendExtensionEvent\fP uses the propagate argument as follows: .IP \(bu 5 If event_list is the empty set, the event is sent to the client that created the destination window. If that client no longer exists, no event is sent. .IP \(bu 5 If propagate is \fIFalse\fP, the event is sent to every client selecting on destination any of the event types specified by the event_list array. .IP \(bu 5 If propagate is \fITrue\fP and no clients have selected on destination any of the events specified by the event_list array, the destination is replaced with the closest ancestor of destination for which some client has selected a type specified by the event-list array and for which no intervening window has that type in its do-not-propagate-mask. If no such window exists or if the window is an ancestor of the focus window and \fIInputFocus\fP was originally specified as the destination, the event is not sent to any clients. Otherwise, the event is reported to every client selecting on the final destination any of the events specified in the event_list array. .LP The event in the \fIXEvent\fP structure must be one of the events defined by the input extension (or a \fIBadValue\fP error results) so that the X server can correctly byte-swap the contents as necessary. The contents of the event are otherwise unaltered and unchecked by the X server except to force send_event to \fITrue\fP in the forwarded event and to set the serial number in the event correctly. .LP \fIXSendExtensionEvent\fP returns zero if the conversion to wire protocol format failed and returns nonzero otherwise. \fIXSendExtensionEvent\fP can generate \fIBadClass\fP, \fIBadDevice\fP, \fIBadValue\fP, and \fIBadWindow\fP errors. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if the specified device is the X keyboard or X pointer device. .TP 12 \fIBadValue\fP Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error. .TP 12 \fIBadWindow\fP A value for a Window argument does not name a defined Window. .SH "SEE ALSO" .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XServerVendor" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XServerVendor, ServerVendor \(en return the vendor of connected server. .XX "XServerVendor" .Nz .\" .\" .SH "Synopsis" .Sy char *XServerVendor\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" .\" .SH Returns The server vendor's string. .SH Description .XX "servers:providing ID of" \f(CWXServerVendor()\fP returns a pointer to a \f(CWNULL\fP-terminated string that provides some identification of the X server implementation. If the data returned by the server is in the Latin Portable Character Encoding, then the string is in the Host Portable Character Encoding. Otherwise, the contents of the string are implementation-dependent. .LP This function and \f(CWXVendorRelease()\fP make it possible to work around bugs in particular server implementations. .LP .XX "ServerVendor macro" The C language macro \f(CWServerVendor()\fP is equivalent and slightly more efficient. .LP Note also that in Release 5, the \f(CWXlibSpecificationRelease\fP symbol is defined (with the value 5) by Xlib. Before Release 5 this symbol was not defined. .\" .\" .SH "See Also" \s-1\fIXVendorRelease()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetAccessControl" "Xlib \- Host Access" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetAccessControl" .XX "access control:enabling and disabling" .Na XSetAccessControl \(en disable or enable access control. .Nz .SH "Synopsis" .Sy XSetAccessControl\^(\^\f(CIdisplay\f(CW, \f(CImode\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int \f(CImode\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CImode\fP 1i Specifies whether you want to enable or disable the access control. Pass one of these constants: \f(CWEnableAccess\fP or \f(CWDisableAccess\fP. .SH Description \f(CWXSetAccessControl()\fP specifies whether the server should check the host access list before allowing access to clients running on remote hosts. If the constant used is \f(CWDisableAccess\fR, clients from any host have access unchallenged. .LP This routine can only be called from a client running on the same host as the server. .LP For more information on access control lists, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "Errors" \f(CWBadAccess\fP .br \f(CWBadValue\fP .SH "See Also" \s-1\fIXAddHost()\fP\s+1, \s-1\fIXAddHosts()\fP\s+1, \s-1\fIXDisableAccessControl()\fP\s+1, \s-1\fIXEnableAccessControl()\fP\s+1, \s-1\fIXListHosts()\fP\s+1, \s-1\fIXRemoveHost()\fP\s+1, \s-1\fIXRemoveHosts()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetAfterFunction" "Xlib \- Error Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetAfterFunction" .XX "functions:calling after all Xlib functions" .XX "after functions" .Na XSetAfterFunction \(en set a function called after all Xlib functions. .Nz .SH "Synopsis" .Sy int (*XSetAfterFunction\^(\^\f(CIdisplay\f(CW, \f(CIprocedure\f(CW\^))() .As Display *\f(CIdisplay\f(CW\^; int (*\f(CIprocedure\f(CW)\^(); .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIprocedure\fP 1i Specifies the user-defined function to be called after each Xlib function. This function is called with one argument, the \f(CIdisplay\fP pointer. .SH Returns The previous after function. .SH Description All Xlib functions that generate protocol requests call what is known as an \fIafter function\fP after completing their work (the default after function does nothing). \f(CWXSetAfterFunction()\fP allows you to write a function to be called. \f(CWXSetAfterFunction()\fP returns the previous after function. .LP .XX "XSynchronize" \f(CWXSynchronize()\fR sets an after function to make sure that the input and request buffers are flushed after every Xlib routine. .LP For more information, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "See Also" \s-1\fIXDisplayName()\fP\s+1, \s-1\fIXGetErrorDatabaseText()\fP\s+1, \s-1\fIXGetErrorText()\fP\s+1, \s-1\fIXSetErrorHandler()\fP\s+1, \s-1\fIXSetIOErrorHandler()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetArcMode" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetArcMode" .XX "arc mode:setting in a graphics context" .Na XSetArcMode \(en set the arc mode in a graphics context. .Nz .SH "Synopsis" .Sy XSetArcMode\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIarc_mode\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIarc_mode\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIarc_mode\fP 1i Specifies the arc mode for the specified graphics context. Possible values are \f(CWArcChord\fP or \f(CWArcPieSlice\fP. .SH Description \f(CWXSetArcMode()\fP sets the \f(CIarc_mode\fP component of a GC, which controls filling in the \f(CWXFillArcs()\fP function. \f(CWArcChord\fP specifies that the area between the arc and a line segment joining the endpoints of the arc is filled. \f(CWArcPieSlice\fP specifies that the area filled is delimited by the arc and two line segments connecting the ends of the arc to the center point of the rectangle defining the arc. .Fs .Pf amp7.eps "" "" "" "" noscale .Fe "Effect of arc-mode constants for filling arcs" .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .br \f(CWBadValue\fP .Nd 10 .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetBackground" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetBackground" .XX "pixel values:setting background in a graphics context" .XX "background pixel values" .Na XSetBackground \(en set the background pixel value in a graphics context. .Nz .SH "Synopsis" .Sy XSetBackground\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIbackground\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; unsigned long \f(CIbackground\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIbackground\fP 1i Specifies the \f(CIbackground\fP component of the GC. .SH Description \f(CWXSetBackground()\fP sets the \f(CIbackground\fP pixel value component of a GC. Note that this is different from the \f(CWbackground\fP of a window, which can be set with either \f(CWXSetWindowBackground()\fP or \f(CWXSetWindowBackgroundPixmap()\fP. .LP The specified pixel value must be returned by \f(CWBlackPixel()\fP, \f(CWWhitePixel()\fP, or one of the routines that allocate colors. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetClassHint" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XSetClassHint" .XX "XA_WM_CLASS property" XSetClassHint \(en set the \f(CWXA_WM_CLASS\fP property of a window. .Nz .SH "Synopsis" .Sy XSetClassHint\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIclass_hints\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; XClassHint *\f(CIclass_hints\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window for which the class hint is to be set. .IP \f(CIclass_hints\fP 1i Specifies the \f(CWXClassHint\fP structure that is to be used. .SH Description \f(CWXSetClassHint()\fP sets the \f(CWXA_WM_CLASS\fP property for the specified window. The window manager may (or may not) read this property, and use it to get resource defaults that apply to the window manager's handling of this application. If the strings in \f(CWclass_hints\fP are not in the Host Portable Character Encoding, the result is implementation-dependent. .LP The \f(CWXClassHint\fP structure set contains \f(CWres_class\fP and \f(CWres_name\fP fields. The \f(CWres_name\fP field contains the application name, and the \f(CWres_class\fP field contains the application class. Note that the name set in this property may differ from the name set as WM_NAME. That is, WM_NAME specifies what should be displayed in the title bar and, therefore, can contain temporal information (for example, the name of a file currently in an editor's buffer). On the other hand, the name specified as part of WM_CLASS is the formal name of the application that should be used when retrieving the application's resources from the resource database. .LP .XX "XSetWMProperties:setting the XA_WM_CLASS property" .XX "XmbSetWMProperties" There are several more powerful functions that set \f(CWXA_WM_CLASS\fP. They include \f(CWXSetWMProperties()\fP, and (in R5) \f(CWXmbSetWMProperties()\fP. These functions read the RESOURCE_NAME environment variable if \f(CWres_name\fP is \f(CWNULL\fP, and they use \f(CWargv[0]\fP stripped of any directory prefixes if RESOURCE_NAME is not set. \f(CWXSetClassHint()\fP only uses the explicit value of \f(CWres_name\fP. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadWindow\fP .Nd 10 .SH Structures .Ps typedef struct { char *res_name; char *res_class; } XClassHint; .Pe .SH "See Also" \s-1\fIXAllocClassHint()\fP\s+1, \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetClipMask" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetClipMask" .Na XSetClipMask \(en set \f(CWpixmap\fP pixmap in a graphics context. .Nz .SH "Synopsis" .Sy XSetClipMask\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW, \f(CIpixmap\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; Pixmap \f(CIpixmap\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIpixmap\fP 1i Specifies a pixmap of depth 1 to be used as the clip mask. Pass the constant \f(CWNone\fP if no clipping is desired. .SH Description .XX "pixmaps, GC component, setting to a pixmap" \f(CWXSetClipMask()\fP sets the \f(CWpixmap\fP as the clip mask component of a GC. The clip mask filters which pixels in the destination are drawn. If \f(CWpixmap\fP is set to \&\f(CWNone\fP, the pixels are always drawn, regardless of the clip origin. Use \f(CWXSetClipRectangles()\fP to set clip mask to a set of rectangles, or \f(CWXSetRegion()\fP to set the clip mask to a region. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .br \f(CWBadPixmap\fP .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetClipOrigin" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetClipOrigin" .XX "clip origin of GC:setting" .Na XSetClipOrigin \(en set the clip origin in a graphics context. .Nz .SH "Synopsis" .Sy XSetClipOrigin\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIclip_x_origin\f(CW\^, \f(CIclip_y_origin\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIclip_x_origin\f(CW\^, \f(CIclip_y_origin\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.25i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP Specifies the graphics context. .IP \f(CIclip_x_origin\fP .br .ns .IP \f(CIclip_y_origin\fP .sp -2 Specify the coordinates of the clip origin (interpreted later relative to the window drawn into with this GC). .SH Description \f(CWXSetClipOrigin()\fP sets the \f(CIclip_x_origin\fP and \f(CIclip_y_origin\fP components of a GC. The clip origin controls the position of the \f(CWclip_mask\fP in the GC, which filters which pixels are drawn in the destination of a drawing request using this GC. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetClipRectangles" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XSetClipRectangles" XSetClipRectangles \(en change \f(CWclip_mask\fP in a graphics context to a list of rectangles. .Nz .SH "Synopsis" .Sy XSetClipRectangles\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIclip_x_origin\f(CW\^, .ti +10n \f(CIclip_y_origin\f(CW\^, \f(CIrectangles\f(CW\^, \f(CIn\f(CW\^, \f(CIordering\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIclip_x_origin\f(CW\^, \f(CIclip_y_origin\f(CW\^; XRectangle \f(CIrectangles\f(CW[]\^; int \f(CIn\f(CW\^; int \f(CIordering\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.25i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP Specifies the graphics context. .IP \f(CIclip_x_origin\fP .br .ns .IP \f(CIclip_y_origin\fP .sp -2 Specify the x and y coordinates of the clip origin (interpreted later relative to the window drawn into with this GC). .IP \f(CIrectangles\fP Specifies an array of rectangles. These are the rectangles you want drawing clipped to. .IP \f(CIn\fP Specifies the number of rectangles. .IP \f(CIordering\fP Specifies the ordering relations of the rectangles. Possible values are \f(CWUnsorted\fP, \f(CWYSorted\fP, \f(CWYXSorted\fP, or \f(CWYXBanded\fP. .SH Description .XX "clip_mask:GC component" \f(CWXSetClipRectangles()\fP changes the \f(CWclip_mask\fP component in the specified GC to the specified list of rectangles and sets the clip origin to \f(CWclip_x_origin\fP and \f(CWclip_y_origin\fP. The rectangle coordinates are interpreted relative to the clip origin. The output from drawing requests using that GC are henceforth clipped to remain contained within the rectangles. The rectangles should be nonintersecting, or the graphics results will be undefined. If the list of rectangles is empty, output is effectively disabled as all space is clipped in that GC. This is the opposite of a \f(CWclip_mask\fP of \f(CWNone\fP in \f(CWXCreateGC()\fP, \f(CWXChangeGC()\fP, or \f(CWXSetClipMask()\fP. .LP If known by the client, ordering relations on the rectangles can be specified with the \f(CIordering\fP argument. This may provide faster operation by the server. If an incorrect ordering is specified, the X server may generate a \f(CWBadMatch\fP error, but it is not required to do so. If no error is generated, the graphics results are undefined. \f(CWUnsorted\fP means the rectangles are in arbitrary order. \f(CWYSorted\fP means that the rectangles are nondecreasing in their y origin. \f(CWYXSorted\fP additionally constrains \f(CWYSorted\fP order in that all rectangles with an equal y origin are nondecreasing in their x origin. \f(CWYXBanded\fP additionally constrains \f(CWYXSorted\fP by requiring that, .ne 8 for every possible horizontal y scan line, all rectangles that include that scan line have identical y origins and y extents. .LP To cancel the effect of this command, so that there is no clipping, pass \f(CWNone\fP as the \f(CWclip_mask\fP in \f(CWXChangeGC()\fP or \f(CWXSetClipMask()\fP. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .SH Structures .Ps typedef struct { short x,y; unsigned short width, height; } XRectangle; .Pe .ne 5 .SH "Errors" .IP "\f(CWBadAlloc\fP" 1i .IP "\f(CWBadGC\fP" .IP "\f(CWBadMatch\fP" Incorrect \f(CIordering\fP (error message server-dependent). .IP "\f(CWBadValue\fP" .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetCloseDownMode" "Xlib \- Client Connections" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetCloseDownMode" .XX "close down mode" .Na XSetCloseDownMode \(en change the close down mode of a client. .Nz .SH "Synopsis" .Sy XSetCloseDownMode\^(\^\f(CIdisplay\f(CW, \f(CIclose_mode\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int \f(CIclose_mode\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIclose_mode\fP 1i Specifies the client close down mode you want. Pass one of these constants: \f(CWDestroyAll\fP, \f(CWRetainPermanent\fP, or \f(CWRetainTemporary\fP. .SH Description \f(CWXSetCloseDownMode()\fP defines what will happen to the client's resources at connection close. A connection between a client and the server starts in \f(CWDestroyAll\fP mode, and all resources associated with that connection will be freed when the client process .XX "RetainTemporary mode" .XX "RetainPermanent mode" dies. If the close down mode is \f(CWRetainTemporary\fP or \f(CWRetainPermanent\fP when the client dies, its resources .XX "XKillClient:and close down mode" live on until a call to \f(CWXKillClient()\fP. The \f(CIresource\fP argument of \f(CWXKillClient()\fP can be used to specify which client to kill, or it may be the constant \f(CWAllTemporary\fP, in which case \f(CWXKillClient()\fP kills all resources of all clients that have terminated in \f(CWRetainTemporary\fP mode. .LP One use of \f(CWRetainTemporary\fP or \f(CWRetainPermanent\fP might be to allow an application to recover from a failure of the network connection to the display server. After restarting, the application would need to be able to identify its own resources and reclaim control of them. .SH "Errors" \f(CWBadValue\fP .SH "See Also" \s-1\fIXKillClient()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetCommand" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetCommand" .XX "XA_WM_COMMAND property" .Na XSetCommand \(en set the \f(CWXA_WM_COMMAND\fP atom (command-line arguments). .Nz .SH "Synopsis" .Sy XSetCommand\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIargv\f(CW, \f(CIargc\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; char **\f(CIargv\f(CW\^; int \f(CIargc\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the ID of the window whose atom is to be set. .IP \f(CIargv\fP Specifies a pointer to the command and arguments used to start the application. .IP \f(CIargc\fP Specifies the number of arguments. .SH Description \f(CWXSetCommand()\fP is used by the application to set the \f(CWXA_WM_COMMAND\fP property for the window manager with the command and its arguments used to invoke the application. If the string is not in the Host Portable Character Encoding, the result is implementation-dependent. .LP \f(CWXSetCommand()\fP creates a zero-length property if \f(CWargc\fP is zero. .LP Use this command only if not calling \f(CWXSetStandardProperties()\fP or \f(CWXSetWMProperties()\fP. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetCommand()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1. .\"last line comment .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XSetDVal.man,v 1.6 94/06/04 17:32:38 rws Exp $ .ds xL Programming with Xlib .TH XSetDeviceValuators 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XSetDeviceValuators \- initialize the valuators on an extension input device .SH SYNTAX XSetDeviceValuators\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fIvaluators\fP\^, \fIfirst_valuator\fP\^, \fInum_valuators\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br int *\fIvaluators\fP\^; .br int \fIfirst_valuator\fP\^; .br int \fInum_valuators\fP\^; .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device whose valuators are to be initialized. .TP 12 .I valuators Specifies a pointer to an array of integer values to be used to initialize the device valuators. .TP 12 .I first_valuator Specifies the first valuator to be set. Valuators are numbered beginning with zero. .TP 12 .I num_valuators Specifies the number of valuators to be set. .SH DESCRIPTION The \fIXSetDeviceValuators\fP request sets the current values of the valuators of an input device. The valuators in the range first_valuator to (first_valuator + num_valuators) are set to the specified values. Valuators are numbered beginning with 0. Not all input devices support initialization of valuator values. If this request is made to a device that does not support valuators initialization, a \fIBadMatch\fP error will occur. .LP If the request succeeds, a status of Success is returned. If another client has the device grabbed, a status of AlreadyGrabbed is returned. .LP \fIXSetDeviceValuators\fP can generate a \fIBadLength\fP, \fIBadDevice\fP , \fIBadMatch\fP, or \fIBadValue\fP error. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. .TP 12 \fIBadMatch\fP This error may occur if an \fIXSetDeviceValuators\fP request is made specifying a device that has no valuators and reports no axes of motion, or if such a request is made specifying a device that does not support valuator initialization. .TP 12 \fIBadValue\fP An invalid first_valuator or num_valuators values was specified. .SH "SEE ALSO" .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetDashes" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetDashes" .XX "dashes:in a graphics context" .Na XSetDashes \(en set a pattern of line dashes in a graphics context. .Nz .SH "Synopsis" .Sy XSetDashes\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIdash_offset\f(CW\^, \f(CIdash_list\f(CW\^, \f(CIn\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIdash_offset\f(CW\^; char \f(CIdash_list\f(CW[]\^; int \f(CIn\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIdash_offset\fP 1i Specifies the phase of the pattern for the dashed line style. .IP \f(CIdash_list\fP 1i Specifies the dash list for the dashed line style. An odd-length list is equivalent to the same list concatenated with itself to produce an even-length list. .IP \f(CIn\fP 1i Specifies the length of the dash list argument. .SH Description \f(CWXSetDashes()\fP sets the \f(CWdashes\fP component of a GC. The initial and alternating elements of the \f(CIdash_list\fP argument are the dashes, the others are the gaps. All of the elements must be non-zero, with lengths measured in pixels. The \f(CIdash_offset\fP argument defines the phase of the pattern, specifying how many pixels into the \f(CIdash_list\fP the pattern should actually begin in the line drawn by the request. .LP \f(CIn\fP specifies the length of \f(CIdash_list\fP. An odd value for \f(CIn\fP is interpreted as specifying the \f(CIdash_list\fP concatenated with itself to produce twice as long a list. .LP Ideally, a dash length is measured along the slope of the line, but server implementors are only required to match this ideal for horizontal and vertical lines. Failing the ideal semantics, it is suggested that the length be measured along the major axis of the line. The major axis is defined as the x axis for lines drawn at an angle of between \-45 and +45 degrees or between 315 and 225 degrees from the x axis. For all other lines, the major axis is the y axis. .LP See Volume One, Chapter 5, \fIThe Graphics Context\fR, for further information. .SH "Errors" .IP "\f(CWBadAlloc\fP" 1i .IP "\f(CWBadGC\fP" .IP "\f(CWBadValue\fP" No values in \f(CIdash_list\fP. .sp .2 Element in \f(CIdash_list\fP is 0. .Nd 15 .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .Fs .Pf amp10.eps "" "" "" "" noscale .Fe "Effects of five different dash_list arrays" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetErrorHandler" "Xlib \- Error Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetErrorHandler" .Na .XX "error handlers:setting" XSetErrorHandler \(en set a fatal error event handler. .Nz .SH "Synopsis" .Sy int (*XSetErrorHandler\^(\^\f(CIhandler\f(CW\^))\^(\^) .As int (\f(CI* handler\f(CW)\^(Display *) .Ae .SH "Arguments" .IP \f(CIhandler\fP 1i The user-defined function to be called to handle error events. If a \f(CWNULL\fP pointer, reinvoke the default handler, which prints a message and exits. .SH Returns The previous nonfatal error handler. .SH Description The error handler function specified in \f(CIhandler\fP will be called by Xlib whenever an \f(CWXError\fP event is received. These are nonfatal conditions, such as unexpected values for arguments, or a failure in server memory allocation. It is acceptable for this procedure to return, though the default handler simply prints a message and exits. However, the error handler should NOT perform any operations (directly or indirectly) that generate protocol requests or that look for input events. .LP In Release 4 and Release 5, \f(CWXSetErrorHandler()\fP returns a pointer to the previous error handler. .LP The function is called with two arguments: the display variable and a pointer to the \f(CWXErrorEvent\fP structure. Here is a trivial example of a user-defined error handler: .sp .5 .ft CW .nf .in +4.5n .ps 9 .vs 11 int myhandler (display, myerr) Display *display; XErrorEvent *myerr; { char msg[80]; \f(CWXGetErrorText\fP(display, myerr->error_code, msg, 80); fprintf(stderr, \&"Error code %s\en"\&, msg); } .ps .vs .ft R .fi .in -4.5n .LP This is how the example routine would be used in \f(CWXSetErrorHandler()\fP: .LP .in +4.5n .ft CW .nf \s9\f(CWXSetErrorHandler\fP(myhandler);\s0 .fi .ft R .in -4.5n .LP Note that \f(CWXSetErrorHandler()\fP is one of the few routines that does not require a display argument. The routine that calls the error handler gets the display variable from the \f(CWXErrorEvent\fP structure. .LP The error handler is not called on \f(CWBadName\fR errors from \f(CWOpenFont\fR, \f(CWLookupColor\fR, and \f(CWAllocNamedColor\fR protocol requests, or on \f(CWBadFont\fR errors from a \f(CWQueryFont\fR protocol request. .ne 10 These errors are all indicated by \f(CWStatus\fP return value of zero in the corresponding Xlib routines, which must be caught and handled by the application. .LP Use \f(CWXIOErrorHandler\fP to provide a handler for I/O errors such as network failures or server host crashes. .LP In the \f(CWXErrorEvent\fR structure shown below, the \f(CWserial\fR member is the number of requests (starting from 1) sent over the network connection since it was opened. It is the number that was the value of the request sequence number immediately after the failing call was made. The \f(CWrequest_code\fR member is a protocol representation of the name of the procedure that failed and is defined in \fI\fR. .LP For more information, see Volume One, Chapter 3, \fIBasic Window Program\fR. .br .ne 10 .SH "Structures" .Ps typedef struct { int type Display *display; /* display the event was read from */ XID resourceid; /* resource ID */ unsigned long serial; /* serial number of failed request */ unsigned char error_code; /* error code of failed request */ unsigned char request_code; /* major opcode of failed request */ unsigned char minor_code; /* minor opcode of failed request */ } XErrorEvent; .XX "XErrorEvent structure" .XX "structures:XErrorEvent" .Pe .SH "See Also" \s-1\fIXDisplayName()\fP\s+1, \s-1\fIXGetErrorDatabaseText()\fP\s+1, \s-1\fIXGetErrorText()\fP\s+1, \s-1\fIXSetAfterFunction()\fP\s+1, \s-1\fIXSetIOErrorHandler()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetFillRule" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetFillRule" .XX "fill rule:setting in a graphics context" .Na XSetFillRule \(en set the fill rule in a graphics context. .Nz .SH "Synopsis" .Sy XSetFillRule\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIfill_rule\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIfill_rule\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIfill_rule\fP 1i Specifies the fill rule you want to set for the specified graphics context. Possible values are \f(CWEvenOddRule\fP or \f(CWWindingRule\fP. .SH Description .XX "fill_rule, GC component" \f(CWXSetFillRule()\fP sets the \f(CIfill_rule\fP component of a GC. The \f(CIfill_rule\fP member of the GC determines what pixels are drawn in \f(CWXFillPolygon()\fP requests. .XX "WindingRule" .XX "EvenOddRule" Simply put, \f(CWWindingRule\fP fills overlapping areas of the polygon, while \f(CWEvenOddRule\fP does not fill areas that overlap an odd number of times. Technically, \f(CWEvenOddRule\fP means that the point is drawn if an arbitrary ray drawn from the point would cross the path determined by the request an odd number of times. \f(CWWindingRule\fP indicates that a point is drawn if a point crosses an unequal number of clockwise and counterclockwise path segments, as seen from the point. .LP A clockwise-directed path segment is one which crosses the ray from left to right as observed from the point. A counterclockwise segment is one which crosses the ray from right to left as observed from the point. The case where a directed line segment is coincident with the ray is uninteresting because you can simply choose a different ray that is not coincident with a segment. .LP All calculations are performed on infinitely small points, so that if any point within a pixel is considered inside, the entire pixel is drawn. Pixels with centers exactly on boundaries are considered inside only if the filled area is to the right, except that on horizontal boundaries, the pixel is considered inside only if the filled area is below the pixel. .LP See Volume One, Chapter 5, \fIThe Graphics Context\fR, for more information. .SH "Errors" \f(CWBadAlloc\fR .br \f(CWBadGC\fP .br \f(CWBadValue\fP .br .ne 8 .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .Fs .Pf amp11.eps "" "" "" "" noscale .Fe "Effect of fill_rule constants for filling closed polygons" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetFillStyle" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetFillStyle" .XX "fill style:setting in a graphics context" .XX "fill_style, GC component" .Na XSetFillStyle \(en set the fill style in a graphics context. .Nz .SH "Synopsis" .Sy XSetFillStyle\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIfill_style\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIfill_style\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIfill_style\fP 1i Specifies the fill style for the specified graphics context. Possible values are \f(CWFillSolid\fP, \f(CWFillTiled\fP, \f(CWFillStippled\fP, or \f(CWFillOpaqueStippled\fP. .LP .Fs .Pf amp12.eps "" "" "" "" noscale .Fe "Effects of fill_style constants demonstrated on small pixmaps" .SH Description \f(CWXSetFillStyle()\fP sets the \f(CIfill_style\fP component of a GC. The \f(CIfill_style\fP defines the contents of the source for line, text, and fill requests. \f(CWFillSolid\fP indicates that the pixels represented by set bits in the source are drawn in the \f(CWforeground\fP pixel value, and unset bits in the source are not drawn. \f(CWFillTiled\fP uses the \f(CWtile\fP specified in the GC to determine the pixel values for set bits in the source. \f(CWFillOpaqueStippled\fP specifies that bits set in the \f(CWstipple\fP are drawn in the \f(CWforeground\fP pixel value and unset bits are drawn in the \f(CWbackground\fP. \f(CWFillStippled\fP draws bits .ne 8 set in the source and set in the stipple in the \f(CWforeground\fP color, and leaves unset bits alone. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .Nd 3 .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .br \f(CWBadValue\fP .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetFont" "Xlib \- Fonts" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetFont" .XX "fonts:setting in a graphics context" .Na XSetFont \(en set the current font in a graphics context. .Nz .SH "Synopsis" .Sy XSetFont\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIfont\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; Font \f(CIfont\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIfont\fP 1i Specifies the ID of the font to be used. .SH Description \f(CWXSetFont()\fP sets the \f(CIfont\fP in the GC. Text drawing requests using this GC will use this font only if the font is loaded. Otherwise, the text will not be drawn. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadFont\fP .br \f(CWBadGC\fP .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXFreeFont()\fP\s+1, \s-1\fIXFreeFontInfo()\fP\s+1, \s-1\fIXFreeFontNames()\fP\s+1, \s-1\fIXFreeFontPath()\fP\s+1, \s-1\fIXGetFontPath()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXListFonts()\fP\s+1, \s-1\fIXListFontsWithInfo()\fP\s+1, \s-1\fIXLoadFont()\fP\s+1, \s-1\fIXLoadQueryFont()\fP\s+1, \s-1\fIXQueryFont()\fP\s+1, \s-1\fIXSetFontPath()\fP\s+1, \s-1\fIXUnloadFont()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetFontPath" "Xlib \- Fonts" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetFontPath" .XX "font path:setting" .Na XSetFontPath \(en set the font search path. .Nz .SH "Synopsis" .Sy XSetFontPath\^(\^\f(CIdisplay\f(CW, \f(CIdirectories\f(CW\^, \f(CIndirs\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; char **\f(CIdirectories\f(CW\^; int \f(CIndirs\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdirectories\fP 1i Specifies the directory path used to look for the font. Setting the path to the empty list restores the default path defined for the X server. .IP \f(CIndirs\fP 1i Specifies the number of directories in the path. .SH Description \f(CWXSetFontPath()\fP defines the directory search path for font lookup for all clients. Therefore the user should construct a new directory search path carefully by adding to the old directory search path obtained by \f(CWXGetFontPath()\fP. Passing an invalid path can result in preventing the server from accessing any fonts. Also avoid restoring the default path, since some other client may have changed the path on purpose. .LP The interpretation of the strings is operating-system-dependent, but they are intended to specify directories to be searched in the order listed. Also, the contents of these strings are operating system specific and are not intended to be used by client applications. .LP An X server is permitted to cache font information internally, for example, it might cache an entire font from a file and not check on subsequent opens of that font to see if the underlying font file has changed. However, when the font path is changed the X server is guaranteed to flush all cached information about fonts for which there currently are no explicit resource IDs allocated. .LP The meaning of errors from this request is implementation-dependent. .SH "Errors" \f(CWBadValue\fP .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXFreeFont()\fP\s+1, \s-1\fIXFreeFontInfo()\fP\s+1, \s-1\fIXFreeFontNames()\fP\s+1, \s-1\fIXFreeFontPath()\fP\s+1, \s-1\fIXGetFontPath()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXListFonts()\fP\s+1, \s-1\fIXListFontsWithInfo()\fP\s+1, \s-1\fIXLoadFont()\fP\s+1, \s-1\fIXLoadQueryFont()\fP\s+1, \s-1\fIXQueryFont()\fP\s+1, \s-1\fIXSetFont()\fP\s+1, \s-1\fIXUnloadFont()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetForeground" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetForeground" .Na .XX "foreground pixel value:setting in a graphics context" XSetForeground \(en set the foreground pixel value in a graphics context. .Nz .SH "Synopsis" .Sy XSetForeground\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIforeground\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; unsigned long \f(CIforeground\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIforeground\fP 1i Specifies the foreground pixel value you want for the specified graphics context. .SH Description .XX "foreground, GC component" \f(CWXSetForeground()\fP sets the \f(CIforeground\fP component in a GC. This pixel value is used for set bits in the source according to the \f(CWfill_style\fP. This pixel value must be returned by \f(CWBlackPixel\fP, \f(CWWhitePixel()\fP, or a routine that allocates colors. .LP See Volume One, Chapter 5, \fIThe Graphics Context\fR, for more information on the GC. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH XSetFunction "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetFunction" .Na .XX "bitwise logical operation:setting in a graphics context" XSetFunction \(en set the bitwise logical operation in a graphics context. .Nz .SH "Synopsis" .Sy XSetFunction\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIfunction\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIfunction\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP Specifies the graphics context. .IP \f(CIfunction\fP Specifies the logical operation you want for the specified graphics context. See Description for the choices and their meanings. .SH Description \f(CWXSetFunction()\fP sets the logical operation applied between the source pixel values (generated by the drawing request) and existing destination pixel values (already in the window or pixmap) to generate the final destination pixel values in a drawing request (what is actually drawn to the window or pixmap). Of course, the \f(CWplane_mask\fP and \f(CWclip_mask\fP in the GC also affect this operation by preventing drawing to planes and pixels respectively. \f(CWGXcopy\fP, \f(CWGXinvert\fP, and \f(CWGXxor\fP are the only logical operations that are commonly used. .LP See Volume One, Chapter 5, \fIThe Graphics Context\fR, for more information about the logical function. .LP The \f(CIfunction\fP symbols and their logical definitions are: .sp .sp 1 .in .KS .TS tab(@), linesize(2); l l l lp7fCW lp7fCW l. Symbol@Value@Meaning .sp .5p .sp 3p GXclear@0x0@0 GXand@0x1@src AND dst GXandReverse@0x2@src AND (NOT dst) GXcopy@0x3@src GXandInverted@0x4@(NOT src) AND dst GXnoop@0x5@dst GXxor@0x6@src XOR dst GXor@0x7@src OR dst GXnor@0x8@(NOT src) AND (NOT dst) GXequiv@0x9@(NOT src) XOR dst GXinvert@0xa@(NOT dst) GXorReverse@0xb@src OR (NOT dst) .TE .KE .in .sp 1 .Nd 10 .sp 1 .in .KS .TS tab(@), linesize(2); l l l lp7fCW lp7fCW l. Symbol@Bit@Meaning .sp .5p .sp 3p GXcopyInverted@0xc@(NOT src) GXorInverted@0xd@(NOT src)OR dst GXnand@0xe@(NOT src) OR (NOT dst) GXset@0xf@1 .sp 5p .TE .KE .in .sp 1 .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .br \f(CWBadValue\fP .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetGraphicsExposures" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetGraphicsExposures" .XX "graphics_exposures, GC component" .Na XSetGraphicsExposures \(en set the \f(CWgraphics_exposures\fP component in a graphics context. .Nz .SH "Synopsis" .Sy XSetGraphicsExposures\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIgraphics_exposures\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; Bool \f(CIgraphics_exposures\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP Specifies the graphics context. .IP \f(CIgraphics_exposures\fP Specifies whether you want \f(CWGraphicsExpose\fP and \f(CWNoExpose\fP events when calling \f(CWXCopyArea()\fP and \f(CWXCopyPlane()\fP with this graphics context. .SH Description .hw graphics \f(CWXSetGraphicsExposure\fP sets the \f(CIgraphics_exposures\fP member of a GC. If \f(CIgraphics_exposures\fP is \f(CWTrue\fP, \f(CWGraphicsExpose\fP events will be generated when \f(CWXCopyArea()\fP and \f(CWXCopyPlane()\fP requests cannot be completely satisfied because a source region is obscured, and \f(CWNoExpose\fP events are generated when they can be completely satisfied. If \f(CIgraphics_exposures\fP is \f(CWFalse\fP, these events are not generated. .LP These events are not selected in the normal way with \f(CWXSelectInput()\fP. Setting the \f(CIgraphics_exposures\fP member of the GC used in the \f(CWCopyArea\fP or \f(CWCopyPlane\fP request is the only way to select these events. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .br \f(CWBadValue\fP .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetICFocus" "Xlib \- Input Contexts" .ds ]W Xlib Reference Manual .XX "XSetICFocus" .XX "input focus" .SH Name .Na XSetICFocus \(en set input context focus. .Nz .SH Synopsis .Sy void XSetICFocus\^(\^\f(CIic\fP\^) .As XIC \f(CIic\fP\^; .Ae .SH Arguments .IP \f(CIic\fP 1i Specifies the input context. .SH Availability Release 5 and later. .SH Description \f(CWXSetICFocus()\fR allows a client to notify an input method that the focus window attached to the specified input context has received keyboard focus. The input method should take action to provide appropriate feedback. .SH "See Also" \s-1\fIXCreateIC()\fP\s+1, \s-1\fIXSetICValues()\fP\s+1, \s-1\fIXmbResetIC()\fP\s+1, \s-1\fIXwcResetIC()\fP\s+1, \s-1\fIXUnsetICFocus()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetICValues" "Xlib \- Input Contexts" .ds ]W Xlib Reference Manual .XX "XSetICValues" .XX "input contexts:attributes" .XX "attributes:input context" .SH Name .Na XSetICValues \(en set input context attributes. .Nz .SH Synopsis .Sy char * XSetICValues\^(\^\f(CIic\fP\^, ...) .As XIC \f(CIic\fP\^; .Ae .SH Arguments .IP \f(CIic\fP 1i Specifies the input context. .ds Al \ to set or get XIC values .IP ... 1i Specifies the variable length argument list\*(Al. .SH Returns \f(CWNULL\fP if no error occurred; otherwise, the name of the first attribute that could not be set. .SH Availability Release 5 and later. .SH Description \f(CWXSetICValues()\fP sets the values of input context attributes. The first argument is the input context, and it is followed by a \f(CWNULL\fP-terminated variable-length argument list of attribute name/value pairs. The standard attributes and their types are listed in the tables below. .sp .50p \f(HI\s-1Input Context Attributes\s+1\fP .sp 6p .vs 11p .sp 1 .in 0 .KS .TS tab(@), linesize(2); lb lb lb lp7fCW lp7fCW l. Name@Type@Notes .sp 4p .sp 2p XNInputStyle@XIMStyle@T{ .na Required at IC creation; may not be changed. T} .sp 3p XNClientWindow@Window@T{ .na Must be set before IC use; may not be changed. T} .sp 3p XNFocusWindow@Window@Changes may cause geometry negotiation. .sp 3p XNResourceName@char * .sp 3p XNResourceClass@char * .sp 3p XNGeometryCallback@XIMCallback * .sp 3p XNFilterEvents@unsigned long@Read-only attribute; may not be set. .sp 3p XNPreeditAttributes@XVaNestedList@See sub-attributes below. .sp 3p XNStatusAttributes@XVaNestedList@See sub-attributes below. .sp 5p .TE .KE .in .sp 1 .sp .50p .ne 6 \f(HI\s-1Pre-edit and Status Area Sub-attributes\s+1\fP .sp 6p .sp 1 .in 0 .KS .TS H tab(@), linesize(2); lb lb lb lp7fCW lp7fCW lp10w(1.6i). Name@Type@Notes .sp 2p .sp 2p .Th XNArea@XRectangle * .sp 3p XNAreaNeeded@XRectangle * .sp 3p XNSpotLocation@XPoint *@T{ Required at IC creation for \f(CWXIMPreeditPosition\fP style. T} .sp 3p XNColormap@Colormap .sp 3p XNStdColormap@Atom .sp 3p XNForeground@unsigned long .sp 3p XNBackground@unsigned long .sp 3p XNBackgroundPixmap@Pixmap .sp 3p XNFontSet@XFontSet@T{ Required at IC creation; changes may cause geometry negotiation. T} .sp 3p XNLineSpacing@int@T{ Changes may cause geometry negotiation. T} .sp 3p XNCursor@Cursor .sp 3p XNPreeditStartCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} .sp 3p XNPreeditDoneCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} .sp 3p XNPreeditDrawCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} .sp 3p XNPreeditCaretCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} .sp 3p XNStatusStartCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fP style. T} .sp 3p XNStatusDoneCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fP style. T} .sp 3p XNStatusDrawCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fP style. T} .sp 5p .TE .KE .in .sp 1 .vs 12 .ig ++ .LP \f(HI\s-1Input Context Attributes\s+1\fP .sp 1 .in 0 .KS .TS h tab(@), linesize(2); l l l lfCW lfCW lw(2.125i). .sp 2p Name@Type@Notes .sp 2p .sp 2p .Th XNInputStyle@XIMStyle@T{ Required at IC creation; may not be changed. T} XNClientWindow@Window@T{ Must be set before IC use; may not be changed. T} XNFocusWindow@Window@T{ Changes may cause geometry negotiation. T} XNResourceName@char * XNResourceClass@char * XNGeometryCallback@XIMCallback * XNFilterEvents@unsigned long@T{ Read-only attribute; may not be set. T} XNPreeditAttributes@XVaNestedList@T{ See sub-attributes below. T} XNStatusAttributes@XVaNestedList@T{ See sub-attributes below. T} .sp 5p .TE .KE .in .sp 1 .LP .Nd 10 \f(HI\s-1Preedit and Status Area Sub-attributes\s+1\fP .sp 1 .in 0 .KS .TS tab(@), linesize(2); l l l lfCW lfCW lw(1.825i). .sp 2p Name@Type@Notes .sp 2p .sp 2p XNArea@XRectangle * XNAreaNeeded@XRectangle * XNSpotLocation@XPoint *@T{ Required at IC creation for XIMPreeditPosition style. T} XNColormap@Colormap XNStdColormap@Atom XNForeground@unsigned long XNBackground@unsigned long XNBackgroundPixmap@Pixmap XNFontSet@XFontSet@T{ Required at IC creation; changes may cause geometry negotiation. T} XNLineSpacing@int@T{ Changes may cause geometry negotiation. T} XNCursor@Cursor XNPreeditStartCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} XNPreeditDoneCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} XNPreeditDrawCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} XNPreeditCaretCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMPreeditCallbacks\fP style. T} XNStatusStartCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fP style. T} XNStatusDoneCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fP style. T} XNStatusDrawCallback@XIMCallback *@T{ Required at IC creation for \f(CWXIMStatusCallbacks\fP style. T} .sp 5p .TE .KE .in .sp 1 .++ In addition to the attribute names above, the special name \f(CWXNVaNestedList\fR indicates that the following argument is a \f(CWXVaNestedList\fP of attribute name/value pairs. When a nested list is encountered in an argument list, the contents of the nested list are processed as if they appeared in the original argument list at that point. .LP .Nd 10 \f(CWXSetICValues()\fR returns \f(CWNULL\fP if no error occurred; otherwise, it returns the name of the first attribute that could not be set. An attribute could be not set for any of the following reasons: .IP \(bu 3n A read-only attribute was set (for example, \f(CWXNFilterEvents\fR). .IP \(bu 3n The attribute name is not recognized. .IP \(bu 3n The input method encountered an input method implementation-dependent error. .LP Each value to be set must match the type of the attribute. .SH Errors .TP 1i \f(CWBadAtom\fR A value for an Atom argument does not name a defined Atom. .TP 1i \f(CWBadColor\fR A value for a Colormap argument does not name a defined Colormap. .TP 1i \f(CWBadCursor\fR A value for a Cursor argument does not name a defined Cursor. .Nd 10 .TP 1i \f(CWBadPixmap\fR A value for a Pixmap argument does not name a defined Pixmap. .TP 1i \f(CWBadWindow\fR A value for a Window argument does not name a defined Window. .SH "See Also" \s-1\fIXCreateIC()\fP\s+1, \s-1\fIXSetICFocus()\fP\s+1, \s-1\fIXmbResetIC()\fP\s+1, \s-1\fIXwcResetIC()\fP\s+1, \s-1\fIXGetICValues()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetIOErrorHandler" "Xlib \- Error Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetIOErrorHandler" .XX "event handlers:setting" .Na XSetIOErrorHandler \(en set a fatal error handler. .Nz .SH "Synopsis" .Sy int (*XSetIOErrorHandler\^(\^\f(CIhandler\f(CW\^))\^(\^) .As int (\f(CI* handler\f(CW)\^(Display *) .Ae .SH "Arguments" .IP \f(CIhandler\fP 1i Specifies user-defined fatal error handling routine. If \f(CWNULL\fP, reinvoke the default fatal error handler. .SH Description \f(CWXSetIOErrorHandler()\fP specifies a user-defined error handling routine for fatal errors. This error handler will be called by Xlib if any sort of system call error occurs, such as the connection to the server being lost. The called routine should not return. If the I/O error handler does return, the client process will exit. .LP If \f(CIhandler\fP is a \f(CWNULL\fP pointer, the default error handler is reinstated. The default I/O error handler prints an error message and exits. .LP In Release 4 and later, \f(CWXSetIOErrorHandler()\fP returns a pointer to the previous error handler. .LP For more information, see Volume One, Chapter 3, \fIBasic Window Program\fR. .SH "See Also" \s-1\fIXDisplayName()\fP\s+1, \s-1\fIXGetErrorDatabaseText()\fP\s+1, \s-1\fIXGetErrorText()\fP\s+1, \s-1\fIXSetAfterFunction()\fP\s+1, \s-1\fIXSetErrorHandler()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetIconName" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetIconName" .XX "icon names" .Na XSetIconName \(en set the name to be displayed in a window's icon. .Nz .SH "Synopsis" .Sy XSetIconName\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIicon_name\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; char *\f(CIicon_name\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window whose icon name is being set. .IP \f(CIicon_name\fP 1i Specifies the name to be displayed in the window's icon. The name should be a \f(CWNULL\fP-terminated string. This name is returned by any subsequent call to \f(CWXGetIconName()\fP. If the string is not in the Host Portable Character Encoding, the result is implementation-dependent. .SH Description .XX "XSetWMIconName" \f(CWXSetIconName()\fP is superseded by \f(CWXSetWMIconName()\fP in Release 4. .XX "XA_WM_ICON_NAME property" .LP \f(CWXSetIconName()\fP sets the \f(CWXA_WM_ICON_NAME\fP property for a window. This is usually set by an application for the window manager. The name should be short, since it is to be displayed in association with an icon. .LP .XX "SetStandardProperties" .XX "XSetWMProperties:setting the XA_WM_ICON_NAME property" \f(CWXSetStandardProperties()\fP (in Release 3) or \f(CWXSetWMProperties()\fP (in Release\ 4) also set this property. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetIconSizes" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetIconSizes" .XX "icon sizes" .XX "XA_WM_ICON_SIZE property" .Na XSetIconSizes \(en set the value of the \f(CWXA_WM_ICON_SIZE\fP property. .Nz .SH "Synopsis" .Sy XSetIconSizes\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIsize_list\f(CW, \f(CIcount\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; XIconSize *\f(CIsize_list\f(CW\^; int \f(CIcount\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window whose icon size property is to be set. Normally the root window. .IP \f(CIsize_list\fP 1i Specifies a pointer to the size list. .IP \f(CIcount\fP 1i Specifies the number of items in the size list. .SH Description \f(CWXSetIconSizes()\fP is normally used by a window manager to set the range of preferred icon sizes in the \f(CWXA_WM_ICON_SIZE\fP property of the root window. .LP Applications can then read the property with \f(CWXGetIconSizes()\fP. .SH "Structures" .Ps typedef struct { int min_width, min_height; int max_width, max_height; int width_inc, height_inc; } XIconSize; .XX "XIconSize structure" .XX "structures:XIconSize" .Pe .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXAllocIconSize()\fP\s+1, \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetInputFocus" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetInputFocus" .XX "keyboard:focus window, setting" .XX "keyboard focus window" .Na XSetInputFocus \(en set the keyboard focus window. .Nz .SH "Synopsis" .Sy XSetInputFocus\^(\^\f(CIdisplay\f(CW, \f(CIfocus\f(CW\^, \f(CIrevert_to\f(CW\^, \f(CItime\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIfocus\f(CW\^; int \f(CIrevert_to\f(CW\^; Time \f(CItime\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIfocus\fP Specifies the ID of the window you want to be the keyboard focus. Pass the window ID, \f(CWPointerRoot\fP, or \f(CWNone\fP. .IP \f(CIrevert_to\fP Specifies which window the keyboard focus reverts to if the focus window becomes not viewable. Pass one of these constants: \f(CWRevertToParent\fP, \f(CWRevertToPointerRoot\fP, or \f(CWRevertToNone\fP. Must not be a window ID. .IP \f(CItime\fP Specifies the time when the focus change should take place. Pass either a timestamp, expressed in milliseconds, or the constant \f(CWCurrentTime\fP. Also returns the time of the focus change when \f(CWCurrentTime\fP is specified. .SH Description \f(CWXSetInputFocus()\fP changes the keyboard focus and the last-focus-change time. The function has no effect if \f(CItime\fP is earlier than the current last-focus-change time or later than the current X server time. Otherwise, the last-focus-change time is set to the specified time, with \f(CWCurrentTime\fP replaced by the current X server time. .LP .XX "FocusIn event" .XX "FocusOut event" \f(CWXSetInputFocus()\fP generates \f(CWFocusIn\fP and \f(CWFocusOut\fP events if \f(CIfocus\fP is different from the current focus. .LP \f(CWXSetInputFocus()\fP executes as follows, depending on what value you assign to the \f(CIfocus\fP argument: .IP \(bu 3n If you assign \f(CWNone\fP, all keyboard events are discarded until you set a new focus window. In this case, \f(CIrevert_to\fP is ignored. .IP \(bu 3n If you assign a window ID, it becomes the main keyboard's focus window. If a generated keyboard event would normally be reported to this window or one of its inferiors, the event is reported normally; otherwise, the event is reported to the focus window. The specified focus window must be viewable at the time of the request (else a \f(CWBadMatch\fP error). If the focus window later becomes not viewable, the focus window will change to the \f(CIrevert_to\fP argument. .IP \(bu 3n If you assign \f(CWPointerRoot\fP, the focus window is dynamically taken to be the root window of whatever screen the pointer is on at each keyboard event. In this case, \f(CIrevert_to\fP is ignored. This is the default keyboard focus setting. .LP If the focus window later becomes not viewable, \f(CWXSetInputFocus()\fP evaluates the \f(CIrevert_to\fP argument to determine the new focus window: .IP \(bu 3n If you assign \f(CWRevertToParent\fP, the focus reverts to the parent (or the closest viewable ancestor) automatically with a new \f(CIrevert_to\fP argument of \f(CWRevertToName\fP. .IP \(bu 3n If you assign \f(CWRevertToPointerRoot\fP or \f(CWRevertToNone\fP, the focus reverts to that value automatically. \f(CWFocusIn\fP and \f(CWFocusOut\fP events are generated when the focus reverts, but the last focus change time is not affected. .SH "Errors" .IP "\f(CWBadMatch\fP" 1i \f(CIfocus\fP window not viewable when \f(CWXSetInputFocus()\fP called. .IP "\f(CWBadValue\fP" .IP "\f(CWBadWindow\fP" .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetLineAttributes" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetLineAttributes" .XX "line characteristics:setting in graphics context" .XX "graphics context:setting line characteristics in" .Na XSetLineAttributes \(en set the line drawing components in a graphics context. .Nz .SH "Synopsis" .Sy XSetLineAttributes\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIline_width\f(CW\^, \f(CIline_style\f(CW\^, .ti +10n \f(CIcap_style\f(CW\^, \f(CIjoin_style\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; unsigned int \f(CIline_width\f(CW\^; int \f(CIline_style\f(CW\^; int \f(CIcap_style\f(CW\^; int \f(CIjoin_style\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIline_width\fP 1i Specifies the line width in the specified graphics context. .IP \f(CIline_style\fP 1i Specifies the line style in the specified graphics context. Possible values are \f(CWLineSolid\fP, \f(CWLineOnOffDash\fP, or \f(CWLineDoubleDash\fP. .IP \f(CIcap_style\fP 1i Specifies the line and cap style in the specified graphics context. Possible values are \f(CWCapNotLast\fP, \f(CWCapButt\fP, \f(CWCapRound\fP, or \f(CWCapProjecting\fP. .IP \f(CIjoin_style\fP 1i Specifies the line-join style in the specified graphics context. Possible values are \f(CWJoinMiter\fP, \f(CWJoinRound\fP, or \f(CWJoinBevel\fP. If you specify \f(CWJoinMitre\fP, \f(CWJoinBevel\fP is used instead if the angle separating the two lines is less than 11 degrees. .SH Description .XX "line_width, GC component" .XX "line_style, GC component" .XX "cap_style, GC component" .XX "join_style, GC component" \f(CWXSetLineAttributes()\fP sets four types of line characteristics in the GC: \f(CIline_width\fP, \f(CIline_style\fP, \f(CIcap_style\fP, and \f(CIjoin_style\fP. .LP See the description of line and join styles in Volume One, Chapter 5, \fIThe Graphics Context\fP. See also \f(CWXSetDashes()\fP. .LP A \f(CIline_width\fP of zero (0) means to use the fastest algorithm for drawing a line of one pixel width. These lines may not meet properly with lines specified as width one or more. .br .ne 4 .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .br \f(CWBadValue\fP .br .ne 7 .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .br .Fs .Pf amp13.eps "" "" "" "" noscale .Fe "Effects of constants for line_style, cap_style and join_style" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetLocaleModifiers" "Xlib \- Locale Management" .ds ]W Xlib Reference Manual .XX "XSetLocaleModifiers" .XX "locale:modifiers, configuring" .SH Name .Na XSetLocaleModifiers \(en configure locale modifiers. .Nz .SH Synopsis .Sy char *XSetLocaleModifiers\^(\^\f(CImodifier_list\fP\^) .As char *\f(CImodifier_list\fP\^; .Ae .SH Arguments .IP \f(CImodifier_list\fP 1.35i Specifies the modifiers. .SH Returns The previous locale modifiers on success; \f(CWNULL\fP on failure. .SH Availability Release 5 and later. .SH Description \f(CWXSetLocaleModifiers()\fP sets or queries the X modifiers for the current locale setting. If the \f(CImodifier_list\fP argument is \f(CWNULL\fP, \f(CWXSetLocaleModifiers()\fP returns the current settings of the X modifiers without modifying them. Otherwise, the \f(CImodifier_list\fP argument is the empty string or a string of the form "{@\^\f(CIcategory\fP\^=\^\f(CIvalue\fP\^}", that is, having zero or more concatenated "@\f(CIcategory\fP\^=\^\f(CIvalue\fP\^" entries where \f(CIcategory\fP is a category name and \f(CIvalue\fP is the (possibly empty) setting for that category. The values are encoded in the current locale. Category names are restricted to the POSIX Portable Filename Character Set. .LP The local host X locale modifiers announcer (on POSIX-compliant systems, the XMODIFIERS environment variable) is appended to the \f(CImodifier_list\fP to provide default values on the local host. If a given category appears more than once in the list, the first setting in the list is used. If a given category is not included in the full modifier list, the category is set to an implementation-dependent default for the current locale. An empty value for a category explicitly specifies the implementation-dependent default. .LP If \f(CWXSetLocaleModifiers()\fP is successful, it returns a string of the current locale modifiers obtained from the \f(CImodifier_list\fP argument and the \f(CWXMODIFIERS\fP environment variable. This string is formatted so that it may be passed in a subsequent call to \f(CWXSetLocaleModifiers()\fP to restore the state of the X modifiers. When the current modifiers are queried with a \f(CWNULL\fP \f(CImodifier_list\fP argument, the returned string is also in this format. .LP If invalid values are given for one or more modifier categories supported by the locale, a \f(CWNULL\fP pointer is returned, and none of the current modifiers are changed. .LP At program startup the modifiers that are in effect are unspecified until the first successful call to set them. Whenever the locale is changed, the modifiers that are in effect become unspecified until the next successful call to set them. Clients should always call \f(CWXSetLocaleModifiers()\fR .ne 8 with a non-\f(CWNULL\fP \f(CImodifier_list\fP after setting the locale, before they call any locale-dependent Xlib routine. .LP The only standard modifier category currently defined is "im," which identifies the desired input method. The values for this category are not standardized. A single locale may use multiple input methods, switching input method under user control. The modifier may specify the initial input method in effect, or an ordered list of input methods. Multiple input methods may be specified in a single im value string in an implementation-dependent manner. .LP The returned modifiers string is owned by Xlib and should not be modified or freed by the client. It may be freed by Xlib after the current locale or modifiers is changed. Until freed, it will not be modified by Xlib. .SH "See Also" \s-1\fIXSupportsLocale()\fP\s+1. .\"last line comment .\" .\" Copyright ([\d,\s]*) by Hewlett-Packard Company, Ardent Computer, .\" .\" Permission to use, copy, modify, distribute, and sell this documentation .\" for any purpose and without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" Ardent, and Hewlett-Packard make no representations about the .\" suitability for any purpose of the information in this document. It is .\" provided \`\`as is'' without express or implied warranty. .\" .\" $XConsortium: XSetMode.man,v 1.6 94/06/04 17:32:39 rws Exp $ .ds xL Programming with Xlib .TH XSetDeviceMode 3X11 "Release 6" "X Version 11" "X FUNCTIONS" .SH NAME XSetDeviceMode \- change the mode of a device .SH SYNTAX XSetDeviceMode\^(\^\fIdisplay\fP, \fIdevice\fP\^, \fImode\fP\^) .br Display *\fIdisplay\fP\^; .br XDevice *\fIdevice\fP\^; .br int \fI_mode\fP\^; .SH ARGUMENTS .TP 12 .I display Specifies the connection to the X server. .TP 12 .I device Specifies the device whose mode is to be changed. .TP 12 .I mode Specifies the mode. You can pass \fIAbsolute\fP , or \fIRelative\fP. .SH DESCRIPTION The \fIXSetDeviceMode\fP request changes the mode of an input device that is capable of reporting either absolute positional information or relative motion information. Not all input devices are capable of reporting motion data, and not all are capable of changing modes from \fIAbsolute\fP to \fIRelative\fP. .LP \fIXSetDeviceMode\fP can generate a \fIBadDevice\fP or \fIBadMode\fP error. .SH DIAGNOSTICS .TP 12 \fIBadDevice\fP An invalid device was specified. The specified device does not exist or has not been opened by this client via \fIXOpenInputDevice\fP. This error may also occur if some other client has caused the specified device to become the X keyboard or X pointer device via the \fIXChangeKeyboardDevice\fP or \fIXChangePointerDevice\fP requests. .TP 12 \fIBadMatch\fP This error may occur if an \fIXSetDeviceMode\fP request is made specifying a device that has no valuators and reports no axes of motion. .TP 12 \fIBadMode\fP An invalid mode was specified. This error will also be returned if the specified device is not capable of supporting the \fIXSetDeviceMode\fP request. .SH "SEE ALSO" .br \fI\*(xL\fP .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetModifierMapping" "Xlib \- Keyboard" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetModifierMapping" .XX "modifiers:setting keycodes to be used as" .Na XSetModifierMapping \(en set keycodes to be used as modifiers (Shift, Control, etc.). .Nz .SH "Synopsis" .Sy int XSetModifierMapping(\^\f(CIdisplay\f(CW, \f(CImod_map\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; XModifierKeymap *\f(CImod_map\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CImod_map\fP Specifies the \f(CWXModifierKeymap()\fP structure containing the desired modifier key codes. .SH Returns \f(CWMappingSuccess\fP on success; \f(CWMappingFailed\fP or \f(CWMappingBusy\fP on failure. .SH Description .XX "keycodes:of modifiers" \f(CWXSetModifierMapping()\fP is one of two ways to specify the keycodes of the keys that are to be used as modifiers (like Shift, Control, etc.). \f(CWXSetModifierMapping()\fP specifies all the keycodes for all the modifiers at once. The other, easier, way is to use perhaps .XX "InsertModifiermapEntry" .XX "XDeleteModifiermapEntry" multiple calls to \f(CWXInsertModifiermapEntry()\fP and \f(CWXDeleteModifiermapEntry()\fP, which add or delete a single keycode for a single modifier key. \f(CWXSetModifierMapping()\fP does the work in a single call, but you need to manually set up the \f(CWXModifierKeymap()\fP structure pointed to by \f(CImod_map\fP. This manual set-up involves knowing how the \f(CWXModifierKeymap()\fP structure is defined and organized, as described in the next three paragraphs. .LP .XX "XModifierKeymap structure" .XX "structures:XModifierKeymap" The \f(CWXModifierKeymap()\fP structure for the \f(CImod_map\fP argument should be created using \f(CWXNewModifierMap\fP or \f(CWXGetModifierMapping()\fP. The \f(CWmax_keypermod\fP element of the structure specifies the maximum number of keycodes that can be mapped to each modifier. You define this number but there may be an upper limit on a particular server. .LP The \f(CWmodifiermap\fP element of the structure is an array of keycodes. There are eight by \f(CWmax_keypermod\fP keycodes in this array: eight because there are eight modifiers, and \f(CWmax_keypermod\fP because that is the number of keycodes that must be reserved for each modifier. .LP .XX "LockMapIndex keycode modifier" .XX "ControlMapIndex keycode modifier" .XX "ShiftMapIndex keycode modifier" .XX "Mod1MapIndex keycode modifier" .XX "Mod2MapIndex keycode modifier" .XX "Mod3MapIndex keycode modifier" .XX "Mod4MapIndex keycode modifier" .XX "Mod5MapIndex keycode modifier" The eight modifiers are represented by the constants \f(CWShiftMapIndex\fP, \f(CWLockMapIndex\fP, \f(CWControlMapIndex\fP, \f(CWMod1MapIndex\fP, \f(CWMod2MapIndex\fP, \f(CWMod3MapIndex\fP, \f(CWMod4\%Map\%Index\fP, and \f(CWMod5MapIndex\fP. These are not actually used as arguments, but they are convenient for referring to each row in the \f(CWmodifiermap\fP structure while filling it. The definitions of these constants are shown in the "Structures" section below. .LP Now you can interpret the \f(CWmodifiermap\fP array. For each modifier in a .hw keypermod given \f(CWmodifiermap\fP, the keycodes which correspond are from \f(CWmodifiermap[index * max_keypermod]\fR to \f(CWmodifiermap[((index + 1) * max_keyspermod) -1]\fP where \f(CWindex\fP is the appropriate modifier index definition (\f(CWShiftMapIndex\fP, \f(CWLockMapIndex\fP, etc.). You must set the \f(CWmod_map\fP array up properly before calling \f(CWXSetModifierMapping()\fP. Now you know why \f(CWXInsertModifiermapEntry\fP and \f(CWXDeleteModifiermapEntry()\fP were created! .LP Zero keycodes are ignored. No keycode may appear twice anywhere in the map (otherwise, a \f(CWBadValue\fP error is generated). In addition, all of the non-zero keycodes must be in the range specified by .ne 2 \f(CWmin_keycode\fP and \f(CWmax_keycode\fP in the \f(CWDisplay\fP structure (otherwise a \f(CWBadValue\fP error occurs). .LP A server can impose restrictions on how modifiers can be changed. For example, certain keys may not generate up transitions in hardware, certain keys may always auto-repeat and therefore be unsuitable for use as modifiers, or multiple modifier keys may not be supported. If a restriction is violated, then the status reply is \f(CWMappingFailed\fP, and none of the modifiers are changed. .LP .EL \f(CWXSetModifierMapping()\fP can also return \f(CWMapping\%Success\fP or \f(CWMappingBusy\fP. The server generates a \f(CWMappingNotify\fP event on a \f(CWMapping\%Success\fP status. If the new keycodes specified for a modifier differ from those currently defined and any (current or new) keys for that modifier are in the down state, then the status reply is \f(CWMappingBusy\fP, and none of the modifiers are changed. .LP A value of zero for \f(CWmodifiermap\fP indicates that no keys are valid as any modifier. .SH "Structures" .Ps typedef struct { int max_keypermod; /* server's max # of keys per modifier */ KeyCode *modifiermap; /* an 8 by max_keypermod array */ } XModifierKeymap; .XX "XModifierKeymap structure" .XX "structures:XModifierKeymap" /* Modifier name symbols. Used to build a SetModifierMapping request or to read a GetModifierMapping request. */ #define ShiftMapIndex 0 #define LockMapIndex 1 #define ControlMapIndex 2 #define Mod1MapIndex 3 #define Mod2MapIndex 4 #define Mod3MapIndex 5 #define Mod4MapIndex 6 #define Mod5MapIndex 7 .Pe .Nd 5 .SH "Errors" .IP "\f(CWBadAlloc\fP" 1i .IP "\f(CWBadValue\fP" 1i Keycode appears twice in the map. .sp .2 Keycode < \f(CIdisplay->\^\f(CWmin_keycode\fR or .br keycode > \f(CIdisplay->\^max_keycode\fP. .br .ne 7 .SH "See Also" \s-1\fIXChangeKeyboardMapping()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifiermap()\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeysym()\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXStringToKeysym()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetNormalHints" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetNormalHints" .XX "size hints:property, setting" .XX "windows:size hints property of, setting" .Na XSetNormalHints \(en set the size hints property of a window in normal state (not zoomed or iconified). .Nz .SH "Synopsis" .Sy void XSetNormalHints\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIhints\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; XSizeHints *\f(CIhints\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window ID. .IP \f(CIhints\fP 1i Specifies a pointer to the sizing hints for the window in its normal state. .SH Description .XX "XSetWMNormalHints:and XSetNormalHints" \f(CWXSetNormalHints()\fP has been superseded by \f(CWXSetWMNormalHints()\fP as of Release 4. .LP \f(CWXSetNormalHints()\fP .XX "XA_WM_NORMAL_HINTS property" sets the \f(CWXA_WM_NORMAL_HINTS\fP property for the specified window. Applications use \f(CWXSetNormalHints()\fP to inform the window manager of the size or position desirable for that window. In addition, an application wanting to move or resize itself should call \f(CWXSetNormalHints()\fP specifying its new desired location and size, in addition to making direct X calls to move or resize. This is because some window managers may redirect window configuration requests, but ignore the resulting events and pay attention to property changes instead. .LP To set size hints, an application must assign values to the appropriate elements in the hints structure, and also set the \f(CWflags\fP field of the structure to indicate which members have assigned values and the source of the assignment. These flags are listed in the Structures section below. .LP For more information on using hints, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Structures" .Ps typedef struct { long flags; /* which fields in structure are defined */ int x, y; int width, height; int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; .ne 12 int base_width, base_height; int win_gravity; } XSizeHints; /* new fields in R4 here */ #define USPosition (1L << 0) /* user specified x, y */ #define USSize (1L << 1) /* user specified width, height */ #define PPosition (1L << 2) /* program specified position */ #define PSize (1L << 3) /* program specified size */ #define PMinSize (1L << 4) /* program specified minimum size */ #define PMaxSize (1L << 5) /* program specified maximum size */ #define PResizeInc (1L << 6) /* program specified resize increments */ #define PAspect (1L << 7) /* program specified min/max aspect ratios */ #define PBaseSize (1L << 8) #define PWinGravity (1L << 9) #define PAllHints (PPosition PSize PMinSize PMaxSize PResizeInc PAspect) .Pe .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetPlaneMask" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetPlaneMask" .XX "plane masks:setting in a graphics context" .Na XSetPlaneMask \(en set the plane mask in a graphics context. .Nz .SH "Synopsis" .Sy XSetPlaneMask\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIplane_mask\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; unsigned long \f(CIplane_mask\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIplane_mask\fP 1i Specifies the plane mask. You can use the macro \f(CWAllPlanes()\fP if desired. .SH Description .XX "plane_mask:GC component" \f(CWXSetPlaneMask()\fP sets the \f(CWplane_mask\fP component of the specified GC. The \f(CWplane_mask\fP determines which planes of the destination drawable are affected by a graphics request. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetPointerMapping" "Xlib \- Pointer" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetPointerMapping" .XX "pointer button:mapping" .Na XSetPointerMapping \(en set the pointer button mapping. .Nz .SH "Synopsis" .Sy int XSetPointerMapping\^(\^\f(CIdisplay\f(CW, \f(CImap\f(CW, \f(CInmap\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; unsigned char \f(CImap\f(CW\^[]\^; int \f(CInmap\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CImap\fP 1i Specifies the mapping list. .IP \f(CInmap\fP 1i Specifies the number of items in the mapping list. .SH Returns \f(CWMappingSuccess\fP on success; \f(CWMappingBusy\fP on failure. .SH Description \f(CWXSetPointerMapping()\fP sets the mapping of the pointer buttons. Elements of the \f(CImap\fP list are indexed starting from 1. The length of the list \f(CInmap\fP must be the same as \f(CWXGetPointerMapping()\fP returns (you must call that first). The index is a physical button number, and the element of the list defines the effective button number. In other words, if \f(CWmap[2]\fP is set to \f(CW1\fP, when the second physical button is pressed, a \f(CWButtonPress\fP event will be generated if \f(CWButton1Mask\fP was selected but not if \f(CWButton2Mask\fP was selected. The \f(CWbutton\fP member in the event will read \f(CWButton1\fP. .LP No two elements can have the same non-zero value (else a \f(CWBadValue\fP error). A value of zero for an element of \f(CImap\fP disables a button, and values for elements are not restricted in value by the number of physical buttons. If any of the buttons to be altered are currently in the down state, the returned value is \f(CWMappingBusy\fP and the mapping is not changed. .LP This function returns either \f(CWMappingSuccess\fP or \f(CWMappingBusy\fP. \f(CWXSetPointerMapping()\fP generates a \f(CWMappingNotify\fP event when it returns \f(CWMappingSuccess\fP. .SH "Errors" .IP "\f(CWBadValue\fP" 1i Two elements of \f(CImap\f(CW[]\fR have same non-zero value. .sp .25 \f(CInmap\fP not equal to \f(CWXGetPointerMapping()\fP return value. .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXChangePointerControl()\fP\s+1, \s-1\fIXGetPointerControl()\fP\s+1, \s-1\fIXGetPointerMapping()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXQueryPointer()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1, \s-1\fIXWarpPointer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetRGBColormaps" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XSetRGBColormaps" .XX "XStandardColormap structure" .XX "structures:XStandardColormap" .XX "colormaps:RGB" .Na XSetRGBColormaps \(en set an \f(CWXStandardColormap\fR structure. .Nz .SH "Synopsis" .Sy void XSetRGBColormaps\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CIstd_colormap\fP\^, \ \f(CIcount\fP\^, \f(CIproperty\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XStandardColormap *\f(CIstd_colormap\fP\^; int \f(CIcount\fP\^; Atom \f(CIproperty\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/SetRGBCmp 2.6 1993/05/28 13:36:27 stephen Exp $ .IP \f(CIw\fP 1i Specifies the window. .IP \f(CIstd_colormap\fP 1i Specifies the \f(CWXStandardColormap\fR structure to be used. .ds Cn colormaps .IP \f(CIcount\fP 1i Specifies the number of \*(Cn. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/SetRGBCmp 2.6 1993/05/28 13:36:27 stephen Exp $ .IP \f(CIproperty\fP 1i Specifies the property name. .SH "Availability" Release 4 and later. .SH Description \f(CWXSetRGBColormaps()\fR replaces the RGB colormap definition in the specified property on the named window. If the property does not already exist, \f(CWXSetRGBColormaps()\fR sets the RGB colormap definition in the specified property on the window. The property is stored with a type of \f(CWRGB_COLOR_MAP\fP and a format of 32. Note that it is the caller's responsibility to honor the ICCCM restriction that only \f(CWRGB_DEFAULT_MAP\fP contain more than one definition. .LP To create a standard colormap, follow this procedure: .IP 1. 5 Open a new connection to the same server. .IP 2. 5 Grab the server. .IP 3. 5 See if \f(CIproperty\fP is on the property list of the root window for the display, using \f(CWXGetStandardColormap()\fR. If so, see if the \f(CIcolormap\fP field is non-zero. If it is, the colormap already exists. .IP 4. 5 If the desired property is not present, do the following: .RS .IP \(bu 3n Determine the color capabilities of the display. Choose a visual. .IP \(bu 3n Create a colormap (not required for \f(CWXA_RGB_DEFAULT_MAP\fP). .IP \(bu 3n Call \f(CWXAllocColorPlanes()\fP or \f(CWXAllocColorCells()\fP to allocate cells in the colormap. .IP \(bu 3n Call \f(CWXStoreColors()\fP to store appropriate color values in the colormap. .IP \(bu 3n Fill in the descriptive fields in the structure. .IP \(bu 3n Call \f(CWXSetRGBColormaps()\fP to set the property on the root window. .IP \(bu 3n Use \f(CWXSetCloseDownMode()\fR to make the resource permanent. .IP \(bu 3n Close the new connection to the server. .RE .Nd 3 .IP 5. 5 Ungrab the server. .IP 6. 5 \f(CWXSetRGBColormaps()\fP supersedes \f(CWXSetStandardColormap()\fP. .LP For more information, see Volume One, Chapter 7, \fIColor\fP. .SH "Structures" .Ps typedef struct { Colormap colormap; unsigned long red_max; unsigned long red_mult; unsigned long green_max; unsigned long green_mult; unsigned long blue_max; unsigned long blue_mult; .ne 6 unsigned long base_pixel; VisualID visualid; /* added by ICCCM version 1 */ XID killid; /* added by ICCCM version 1 */ } XStandardColormap; .Pe .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadAtom\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXAllocStandardColormap()\fP\s+1, \s-1\fIXGetRGBColormaps()\fP\s+1, \s-1\fIXVisualIDFromVisual()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetRegion" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetRegion" .XX "regions:setting" .XX "clip_mask, GC component" .Na XSetRegion \(en set \f(CWclip_mask\fP of the graphics context to the specified region. .Nz .SH "Synopsis" .Sy XSetRegion\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIr\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; Region \f(CIr\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP \f(CIr\fP 1i Specifies the region. .SH Description \f(CWXSetRegion()\fR sets the \f(CIclip_mask\fP component of a GC to the specified region. Thereafter, all drawing made with \f(CWgc\fR will be confined to the area of intersection of the region and the drawable. Once it is set in the GC, the region can be destroyed. .LP \f(CWXSetRegion\fR sets the clip origin of the GC to an implementation-dependent value. .LP For more information on regions, see Volume One, Chapter 5, \fIThe Graphics Context\fR, and Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" \f(CWRegion\fP is a pointer to an opaque structure type. .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXCreateRegion()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetScreenSaver" "Xlib \- Screen Saver" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetScreenSaver" .XX "screen savers:setting parameters of" .Na XSetScreenSaver \(en set the parameters of the screen saver. .Nz .SH "Synopsis" .Sy XSetScreenSaver\^(\^\f(CIdisplay\f(CW, \f(CItimeout\f(CW\^, \f(CIinterval\f(CW\^, \f(CIprefer_blanking\f(CW\^, .ti +10n \f(CIallow_exposures\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int \f(CItimeout\f(CW\^, \f(CIinterval\f(CW\^; int \f(CIprefer_blanking\f(CW\^; int \f(CIallow_exposures\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CItimeout\fP 1i Specifies the time of inactivity, in seconds, before the screen saver turns on. .IP \f(CIinterval\fP 1i Specifies the interval, in seconds, between screen saver invocations. This is for intermittent changes to the display, not blanking. .IP \f(CIprefer_blanking\fP 1i Specifies whether to enable screen blanking. Possible values are \f(CWDontPreferBlanking\fP, \f(CWPreferBlanking\fP, or \f(CWDefaultBlanking\fP. .IP \f(CIallow_exposures\fP 1i Specifies the current screen saver control values. Possible values are \f(CWDontAllowExposures\fP, \f(CWAllowExposures\fP, or \f(CWDefaultExposures\fP. .SH Description \f(CWXSetScreenSaver()\fP sets the parameters that control the screen saver. \f(CItimeout\fP and \f(CIinterval\fP are specified in seconds. A positive \f(CItimeout\fP enables the screen saver. A \f(CItimeout\fP of zero (\f(CW0\fP) disables the screen saver, while a timeout of \f(CW\-1\fP restores the default. An \f(CIinterval\fP of zero (\f(CW0\fP) disables the random pattern motion. If no input from devices (keyboard, mouse, etc.) is generated for the specified number of timeout seconds, the screen saver is activated. .LP For each screen, if blanking is preferred and the hardware supports video blanking, the screen will simply go blank. Otherwise, if either exposures are allowed or the screen can be regenerated without sending exposure events to clients, the screen is tiled with the root window background tile, with a random origin, each \f(CIinterval\fP seconds. Otherwise, the state of the screen does not change. All screen states are restored at the next input from a device. .LP If the server-dependent screen saver method supports periodic change, \f(CIinterval\fP serves as a hint about how long the change period should be, and a value of zero (\f(CW0\fP) hints that no periodic change should be made. Examples of ways to change the screen include scrambling the color map .ne 2 periodically, moving an icon image about the screen periodically, or tiling the screen with the root window background tile, randomly reoriginated periodically. .LP For more information on the screen saver, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH "Errors" .IP "\f(CWBadValue\fP" 1i \f(CItimeout\fP < \-1. .SH "See Also" \s-1\fIXActivateScreenSaver()\fP\s+1, \s-1\fIXForceScreenSaver()\fP\s+1, \s-1\fIXGetScreenSaver()\fP\s+1, \s-1\fIXResetScreenSaver()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetSelectionOwner" "Xlib \- Selections" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetSelectionOwner" .XX "selections:setting owner of" .Na XSetSelectionOwner \(en set the owner of a selection. .Nz .SH "Synopsis" .Sy XSetSelectionOwner\^(\^\f(CIdisplay\f(CW, \f(CIselection\f(CW\^, \f(CIowner\f(CW\^, \f(CItime\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Atom \f(CIselection\f(CW\^; Window \f(CIowner\f(CW\^; Time \f(CItime\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIselection\fP 1i Specifies the selection atom. Predefined atoms are \f(CWXA_PRIMARY\fP and \f(CWXA_SECONDARY\fP. .IP \f(CIowner\fP 1i Specifies the desired owner of the specified selection atom. This value is either a window ID or \f(CWNone\fP. .IP \f(CItime\fP 1i Specifies the time when the selection should take place. Pass either a timestamp, expressed in milliseconds, or the constant \f(CWCurrentTime\fP. .SH Description .XX "selection property:(see also selections)" \f(CWXSetSelectionOwner()\fP sets the \f(CWowner\fP and last-change time of a selection property. This should be called by an application that supports cutting and pasting between windows (or at least cutting), when the user has made a selection of any kind of text, graphics, or data. This makes the information available so that other applications can request the data from the new selection owner using \f(CWXConvertSelection()\fP, which generates a \f(CWSelectionRequest\fP event specifying the desired type and format of the data. Then the selection owner sends a \f(CWSelectionNotify\fP using \f(CWXSendEvent()\fP, which notes that the information is stored in the selection property in the desired format or indicates that it couldn't do the conversion to the desired type. .LP If \f(CIowner\fP is specified as \f(CWNone\fP, then this client is giving up ownership voluntarily. Otherwise, the new owner is the client executing the request. .LP If the new selection owner is not the same client as the old owner, and the new owner is a window, then the old owner is sent a \f(CWSelectionClear\fP event. This indicates to the old owner that the selection should be unhighlighted. .LP If the selection owner window is later destroyed, the owner of the selection automatically reverts to \f(CWNone\fP. .LP The value you pass to the \f(CItime\fP argument must be no earlier than the last-change time of the specified selection, and no later than the current time, or the selection is not affected. The new last-change time recorded is the specified time, with \f(CWCurrentTime\fP replaced by the current server time. .ne 2 If the X server reverts a selection owner to \f(CWNone\fP, the last-change time is not affected. .LP For more information on selections, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Errors" \f(CWBadAtom\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXConvertSelection()\fP\s+1, \s-1\fIXGetSelectionOwner()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetSizeHints" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetSizeHints" .XX "XA_WM_SIZE_HINTS property .Na XSetSizeHints \(en set the value of any property of type \f(CWXA_WM_SIZE_HINTS\fP. .Nz .SH "Synopsis" .Sy XSetSizeHints\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIhints\f(CW, \f(CIproperty\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; XSizeHints *\f(CIhints\f(CW\^; Atom \f(CIproperty\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window ID. .IP \f(CIhints\fP 1i Specifies a pointer to the size hints. .IP \f(CIproperty\fP 1i Specifies the property atom. .SH Description .XX "XSetWMSizeHints" \f(CWXSetSizeHints()\fP has been superseded by \f(CWXSetWMSizeHints()\fP as of Release 4. .LP \f(CWXSetSizeHints()\fP sets the named property on the specified window to the specified \f(CWXSizeHints\fP structure. This routine is useful if new properties of type \f(CWXA_WM_SIZE_HINTS\fP are defined. The predefined properties of that type have their own set and get functions, \f(CWXSetNormalHints()\fP and \f(CWXSetZoomHints()\fP (\f(CWXSetWMHints()\fP in Release 4 and later \- zoom hints are obsolete). .LP The \f(CWflags\fP member of \f(CWXSizeHints\fP must be set to the OR of the symbols representing each member to be set. .LP For more information on using hints, see Volume One, Chapter 12, \fIInterclient Communication\fR. .LP .SH "Structures" .Ps typedef struct { long flags; /* which fields in structure are defined */ int x, y; int width, height; int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; int base_width, base_height; int win_gravity; } XSizeHints; .ne 8 /* flags argument in size hints */ #define USPosition (1L << 0) /* user specified x, y */ #define USSize (1L << 1) /* user specified width, height */ #define PPosition (1L << 2) /* program specified position */ #define PSize (1L << 3) /* program specified size */ #define PMinSize (1L << 4) /* program specified minimum size */ #define PMaxSize (1L << 5) /* program specified maximum size */ #define PResizeInc (1L << 6) /* program specified resize increments */ #define PAspect (1L << 7) /* program specified min/max aspect ratios */ #define PBaseSize (1L << 8) #define PWinGravity (1L << 9) #define PAllHints (PPosition PSize PMinSize PMaxSize PResizeInc PAspect) .Pe .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadAtom\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetStandardColormap" "Xlib \- Colormaps" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetStandardColormap" .XX "colormaps:changing standard property" .Na XSetStandardColormap \(en change the standard colormap property. .Nz .SH "Synopsis" .Sy void XSetStandardColormap(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIcmap_info\f(CW, \f(CIproperty\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; XStandardColormap *\f(CIcmap_info\f(CW\^; Atom \f(CIproperty\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the ID of the window with which this colormap will be associated. .IP \f(CIcmap_info\fP Specifies the filled colormap information structure. .IP \f(CIproperty\fP Specifies the standard colormap property to set. The predefined standard colormaps are: \f(CWXA_RGB_BEST_MAP\fP, \f(CWXA_RGB_RED_MAP\fP, \f(CWXA_RGB_GREEN_\fP \f(CWMAP\fP, \f(CWXA_RGB_BLUE_MAP\fP, \f(CWXA_RGB_DEFAULT_MAP\fP, and \f(CWXA_RGB_\fP \f(CWGRAY_MAP\fP. .SH Description \f(CWXSetStandardColormap()\fP has been superseded by .XX "XSetRGBColormap" \f(CWXSetRGBColormap\fP as of Release\ 4. .LP \f(CWXSetStandardColormap()\fP defines a standard colormap property. .LP See description of standard colormaps in Volume One, Chapter 7, \fIColor\fR. .br .ne 5 .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadAtom\fP .br \f(CWBadDrawable\fP .br \f(CWBadWindow\fP .SH Structures .Ps typedef struct { Colormap colormap; /* ID of colormap made by XCreateColormap */ unsigned long red_max; unsigned long red_mult; unsigned long green_max; unsigned long green_mult; unsigned long blue_max; unsigned long blue_mult; unsigned long base_pixel; Visual ID visualid; XID killid; } XStandardColormap; /* new fields in R4 */ .Pe .SH "See Also" \s-1\fIXDefaultColormap()\fP\s+1, \s-1\fIXDisplayCells()\fP\s+1, \s-1\fIXCopyColormapAndFree()\fP\s+1, \s-1\fIXCreateColormap()\fP\s+1, \s-1\fIXFreeColormap()\fP\s+1, \s-1\fIXGetStandardColormap()\fP\s+1, \s-1\fIXInstallColormap()\fP\s+1, \s-1\fIXListInstalledColormaps()\fP\s+1, \s-1\fIXSetWindowColormap()\fP\s+1, \s-1\fIXUninstallColormap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetStandardProperties" "Xlib \- Properties" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetStandardProperties" .XX "window manager:properties;setting minimum set for" .Na XSetStandardProperties \(en set the minimum set of properties for the window manager. .Nz .SH "Synopsis" .Sy XSetStandardProperties\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIwindow_name\f(CW, \f(CIicon_name\f(CW, .ti +10n \f(CIicon_pixmap\f(CW, \f(CIargv\f(CW, \f(CIargc\f(CW, \f(CIhints\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; char *\f(CIwindow_name\f(CW\^; char *\f(CIicon_name\f(CW\^; Pixmap \f(CIicon_pixmap\f(CW\^; char **\f(CIargv\f(CW\^; int \f(CIargc\f(CW\^; XSizeHints *\f(CIhints\f(CW\^ .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window ID. .IP \f(CIwindow_name\fP 1i Specifies the name of the window. Should be a \f(CWNULL\fP-terminated string. .IP \f(CIicon_name\fP 1i Specifies the name to be displayed in the window's icon. Should be a \f(CWNULL\fP-terminated string. .IP \f(CIicon_pixmap\fP 1i Specifies the pixmap that is to be used for the icon, or \f(CWNone\fP. This pixmap must be of depth 1. .IP \f(CIargv\fP 1i Specifies a pointer to the command and arguments used to start the application. .IP \f(CIargc\fP 1i Specifies the number of arguments. .IP \f(CIhints\fP 1i Specifies a pointer to the size hints for the window in its normal state. .SH Description \f(CWXSetStandardProperties()\fP is superseded by .XX "XSetWMProperties:and XSetStandardProperties" \f(CWXSetWMProperties()\fP in Release 4. .LP \f(CWXSetStandardProperties()\fP sets in a single call the most essential properties for a quickie application. \f(CWXSetStandardProperties()\fP gives a window manager some information about your program's preferences; it probably will not be sufficient for complex \%programs. If the strings are not in the Host Portable Character Encoding, the result is implementation-dependent. .LP See Volume One, Chapter 12, \fIInterclient Communication\fP for a description of standard properties. .Nd 12 .SH "Structures" .Ps .ta 4.5n +1i 1.9i typedef struct { long flags; /* which fields in structure are defined */ int x, y; int width, height; int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; int base_width, base_height; int win_gravity; } XSizeHints; /* flags argument in size hints */ #define USPosition (1L << 0) /* user specified x, y */ #define USSize (1L << 1) /* user specified width, height */ #define PPosition (1L << 2) /* program specified position */ #define PSize (1L << 3) /* program specified size */ #define PMinSize (1L << 4) /* program specified minimum size */ #define PMaxSize (1L << 5) /* program specified maximum size */ #define PResizeInc (1L << 6) /* program specified resize increments */ #define PAspect (1L << 7) /* program specified min and max aspect ratios */ #define PBaseSize (1L << 8) #define PWinGravity (1L << 9) #define PAllHints (PPosition PSize PMinSize PMaxSize PResizeInc PAspect) .Pe .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXChangeProperty()\fP\s+1, \s-1\fIXDeleteProperty()\fP\s+1, \s-1\fIXGetAtomName()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXGetWindowProperty()\fP\s+1, \s-1\fIXInternAtom()\fP\s+1, \s-1\fIXListProperties()\fP\s+1, \s-1\fIXRotateWindowProperties()\fP\s+1. .\"last line comment .TH XSetStandar.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XSetStandardColormap@XSetStandaA .sp .5 XSetStandardProperties@XSetStandaB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetState" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetState" .Na XSetState \(en set the foreground, background, logical function, and plane mask in a graphics context. .Nz .SH "Synopsis" .Sy XSetState\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIforeground\f(CW\^, \f(CIbackground\f(CW\^, \f(CIfunction\f(CW\^, \f(CIplane_mask\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; unsigned long \f(CIforeground\f(CW\^, \f(CIbackground\f(CW\^; int \f(CIfunction\f(CW\^; unsigned long \f(CIplane_mask\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1.1i Specifies the graphics context. .IP \f(CIforeground\fP 1.1i Specifies the foreground for the specified graphics context. .IP \f(CIbackground\fP 1.1i Specifies the background for the specified graphics context. .IP \f(CIfunction\fP 1.1i Specifies the logical function for the specified graphics context. .IP \f(CIplane_mask\fP 1.1i Specifies the plane mask for the specified graphics context. .\" *** JIM: NEED MORE INFO FOR THIS. *** .SH Description .XX "foreground, GC component" .XX "background, GC component" .XX "function, GC component" .XX "plane_mask, GC component" \f(CWXSetState()\fP sets the \f(CWforeground\fP and \f(CWbackground\fP pixel values, the logical \f(CWfunction\fP, and the \f(CWplane_mask\fP in a GC. See \f(CWXSetForeground()\fP, \f(CWXSetBackground()\fP, \f(CWXSetFunction()\fP, and \f(CWXSetPlaneMask()\fP for what these members do and appropriate values. .LP See Volume One, Chapter 5, \fIThe Graphics Context\fR, for more information. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .br \f(CWBadValue\fP .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetStipple" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetStipple" .XX "stipple:setting in a graphics context" .Na XSetStipple \(en set the stipple in a graphics context. .Nz .SH "Synopsis" .Sy XSetStipple\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIstipple\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; Pixmap \f(CIstipple\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP Specifies the graphics context. .IP \f(CIstipple\fP Specifies the stipple for the specified graphics context. .SH Description .XX "stipple, GC component" \f(CWXSetStipple()\fP sets the \f(CWstipple\fP component of a GC. The \f(CIstipple\fP is a pixmap of depth one. It is laid out like a tile. Set bits in the stipple determine which pixels in an area are drawn in the \f(CWforeground\fP pixel value. Unset bits in the stipple determine which pixels are drawn in the \f(CWbackground\fP pixel value if the \f(CWfill_style\fP is \f(CWFill\%Opaque\%Stippled\fP. If \f(CWfill_style\fP is \f(CWFillStippled\fP, pixels overlain with unset bits in the stipple are not drawn. If \f(CWfill_style\fP is \f(CWFillTiled\fP or \f(CWFill\%Solid\fP, the stipple is not used. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .br \f(CWBadPixmap\fP .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetSubwindowMode" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetSubwindowMode" .XX "subwindow mode:setting" .Na XSetSubwindowMode \(en set the subwindow mode in a graphics context. .Nz .SH "Synopsis" .Sy XSetSubwindowMode\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIsubwindow_mode\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIsubwindow_mode\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP Specifies the graphics context. .IP \f(CIsubwindow_mode\fP Specifies the subwindow mode you want to set for the specified graphics context. Possible values are \f(CWClipByChildren\fP or \f(CWInclude\%Inferiors\fP. .SH Description .XX "subwindow_mode, GC component" \f(CWXSetSubwindowMode()\fP sets the \f(CWsubwindow_mode\fP component of a GC. \f(CWClipByChildren\fP means that graphics requests will be clipped by all viewable children. \f(CWIncludeInferiors\fP means draw through all subwindows. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .br \f(CWBadValue\fP .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetTSOrigin()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetTSOrigin" "Xlib \- Graphics Context" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetTSOrigin" .XX "tiles:setting origin in a graphics context" .XX "stipple:setting origin in a graphics context" .Na XSetTSOrigin \(en set the tile/stipple origin in a graphics context. .Nz .SH "Synopsis" .Sy XSetTSOrigin\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CIts_x_origin\f(CW\^, \f(CIts_y_origin\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; int \f(CIts_x_origin\f(CW\^, \f(CIts_y_origin\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.2i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP 1.2i Specifies the graphics context. .IP \f(CIts_x_origin\fP 1.2i Specify the x and y coordinates of the tile/stipple origin. .sp -.5 .IP \f(CIts_y_origin\fP 1.2i .SH Description .XX "ts_x_origin, GC component" .XX "ts_y_origin, GC component" \f(CWXSetTSOrigin()\fP sets the \f(CIts_x_origin\fP and \f(CIts_y_origin\fP components in a GC, which are measured relative to the origin of the drawable specified in the drawing request that uses the GC. This controls the placement of the tile or the stipple pattern that patterns an area. To tile or stipple a child so that the pattern matches the parent, you need to subtract the current position of the child window from \f(CIts_x_origin\fP and \f(CIts_y_origin\fP. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .SH "See Also" \s-1\fIXDefaultGC()\fP\s+1, \s-1\fIXChangeGC()\fP\s+1, \s-1\fIXCopyGC()\fP\s+1, \s-1\fIXCreateGC()\fP\s+1, \s-1\fIXFreeGC()\fP\s+1, \s-1\fIXGContextFromGC()\fP\s+1, \s-1\fIXSetArcMode()\fP\s+1, \s-1\fIXSetBackground()\fP\s+1, \s-1\fIXSetClipMask()\fP\s+1, \s-1\fIXSetClipOrigin()\fP\s+1, \s-1\fIXSetClipRectangles()\fP\s+1, \s-1\fIXSetDashes()\fP\s+1, \s-1\fIXSetFillRule()\fP\s+1, \s-1\fIXSetFillStyle()\fP\s+1, \s-1\fIXSetForeground()\fP\s+1, \s-1\fIXSetFunction()\fP\s+1, \s-1\fIXSetGraphicsExposures()\fP\s+1, \s-1\fIXSetLineAttributes()\fP\s+1, \s-1\fIXSetPlaneMask()\fP\s+1, \s-1\fIXSetState()\fP\s+1, \s-1\fIXSetStipple()\fP\s+1, \s-1\fIXSetSubwindowMode()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetTextProperty" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XSetTextProperty" .Na XSetTextProperty \(en set one of a window's text properties. .XX "text properties:setting" .XX "windows:text properties of, setting" .Nz .SH "Synopsis" .Sy void XSetTextProperty\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CItext_prop\fP\^, \ \f(CIproperty\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XTextProperty *\f(CItext_prop\fP\^; Atom \f(CIproperty\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/SetTextProp 2.6 1993/05/20 11:40:37 stephen Exp $ .IP \f(CIw\fP 1i Specifies the window. .IP \f(CItext_prop\fP 1i Specifies the \f(CWXTextProperty\fR structure to be used. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/SetTextProp 2.6 1993/05/20 11:40:37 stephen Exp $ .IP \f(CIproperty\fP 1i Specifies the property name. .SH "Availability" Release 4 and later. .SH Description \f(CWXSetTextProperty()\fR sets the specified property for the named window with the data, type, format, and number of items determined by the \f(CIvalue\fP field, the \f(CIencoding\fP field, the \f(CIformat\fP field, and the \f(CInitems\fP field, respectively, of the specified \f(CWXTextProperty\fR structure. .SH "Structures" .Ps typedef struct { unsigned char *value; /* same as Property routines */ Atom encoding; /* prop type */ int format; /* prop data format: 8, 16, or 32 */ unsigned long nitems; /* number of data items in value */ } XTextProperty; .Pe .SH "Errors" \f(CWBadAlloc\fR .br \f(CWBadAtom\fR .br \f(CWBadValue\fR .br \f(CWBadWindow\fR .SH "See Also" \s-1\fIXFreeStringList()\fP\s+1, \s-1\fIXGetTextProperty()\fP\s+1, \s-1\fIXStringListToTextProperty()\fP\s+1, \s-1\fIXTextPropertytoStringList()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetTile" "Xlib \- Pixmaps and Tiles" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetTile" .XX "fill tiles:setting" .Na XSetTile \(en set the fill tile in a graphics context. .Nz .SH "Synopsis" .Sy XSetTile\^(\^\f(CIdisplay\f(CW, \f(CIgc\f(CW\^, \f(CItile\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; GC \f(CIgc\f(CW\^; Pixmap \f(CItile\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIgc\fP Specifies the graphics context. .IP \f(CItile\fP Specifies the desired tile for the specified graphics context. .SH Description .XX "tile, GC component" \f(CWXSetTile()\fP sets the \f(CWtile\fP member of the GC. This member of the GC determines the pixmap used to tile areas. The tile must have the same depth as the destination drawable. This tile will only be used in drawing if the \f(CWfill_style\fP is \f(CIFillTiled\fP. .LP For more information, see Volume One, Chapter 5, \fIThe Graphics Context\fR. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadGC\fP .br \f(CWBadMatch\fP .br \f(CWBadPixmap\fP .SH "See Also" \s-1\fIXCreateBitmapFromData()\fP\s+1, \s-1\fIXCreatePixmap()\fP\s+1, \s-1\fIXCreatePixmapFromBitmapData()\fP\s+1, \s-1\fIXFreePixmap()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXQueryBestStipple()\fP\s+1, \s-1\fIXQueryBestTile()\fP\s+1, \s-1\fIXReadBitmapFile()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1, \s-1\fIXWriteBitmapFile()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetTransientForHint" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XSetTransientForHint" .XX "XA_WM_TRANSIENT_FOR property" XSetTransientForHint \(en set the \f(CWXA_WM_TRANSIENT_FOR\fP property for a window. .Nz .SH "Synopsis" .Sy XSetTransientForHint\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIprop_window\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; Window \f(CIprop_window\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window ID, normally of a dialog box popup. .IP \f(CIprop_window\fP 1i Specifies the window ID that the \f(CWXA_WM_TRANSIENT_FOR\fP property is to be set to. This is usually the main window of the application. .SH Description \f(CWXSetTransientForHint()\fP sets the \f(CWXA_WM_TRANSIENT_FOR\fP property of the specified window. This should be done when the window \f(CIw\fP is a temporary child (for example, a dialog box) and the main top-level window of its application is \f(CIprop_window\fP. Some window managers may use this information to unmap an application's dialog boxes (for example, when the main application window gets iconified). .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetWMClientMachine" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XSetWMClientMachine" .XX "XA_WM_CLIENT_MACHINE property" .Na XSetWMClientMachine \(en set a window's \f(CWXA_WM_CLIENT_MACHINE\fP property. .Nz .SH "Synopsis" .Sy void XSetWMClientMachine\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CItext_prop\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XTextProperty *\f(CItext_prop\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/SetWMClientMa 2.4 1993/05/28 13:37:41 stephen Exp $ .IP \f(CIw\fP 1i Specifies the window. .IP \f(CItext_prop\fP 1i Specifies the \f(CWXTextProperty\fR structure to be used. .SH "Availability" Release 4 and later. .SH Description .hw CLIENT \f(CWXSetWMClientMachine()\fR performs an \f(CWXSetTextProperty()\fR to set the \f(CWXA_WM_CLIENT_MACHINE\fP property of the specified window. This property should contain the name of the host machine on which this client is being run, as seen from the server. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .Ps typedef struct { unsigned char *value; /* same as Property routines */ Atom encoding; /* prop type */ int format; /* prop data format: 8, 16, or 32 */ unsigned long nitems; /* number of data items in value */ } XTextProperty; .Pe .SH "See Also" \s-1\fIXGetWMClientMachine()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetWMColormapWindows" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XSetWMColormapWindows" .XX "XA_WM_COLORMAP_WINDOWS property" .Na XSetWMColormapWindows \(en set a window's \f(CWXA_WM_COLORMAP_WINDOWS\fP property. .Nz .SH "Synopsis" .Sy Status XSetWMColormapWindows\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \ \f(CIcolormap_windows\fP\^, \f(CIcount\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; Window *\f(CIcolormap_windows\fP\^; int \f(CIcount\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/SetWMCmpWind 2.7 1993/05/28 13:37:44 stephen Exp $ .IP \f(CIw\fP 1i Specifies the window. .IP \f(CIcolormap_windows\fP 1i Specifies the list of windows. .ds Cn windows in the list .IP \f(CIcount\fP 1i Specifies the number of \*(Cn. .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description .LP \f(CWXSetWMColormapWindows()\fR sets the \f(CWXA_WM_COLORMAP_WINDOWS\fP property on the specified window to the list of windows specified by the \f(CIcolormap_windows\fP argument. The property is stored with a type of WINDOW and a format of 32. .hw WINDOWS .hw COLORMAP If it cannot intern the \f(CWXA_WM_COLORMAP_WINDOWS\fP atom, \f(CWXSetWMColormapWindows()\fR returns a zero status. Otherwise, it returns a non-zero status. .LP This property tells the window manager that subwindows of this application need to have their own colormaps installed. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Errors" \f(CWBadAlloc\fR .br \f(CWBadWindow\fR .SH "See Also" \s-1\fIXGetWMColormapWindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetWMHints" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetWMHints" .XX "window manager:properties; hints" .XX "hints property, setting (window manager)" .Na XSetWMHints \(en set a window manager hints property. .Nz .SH "Synopsis" .Sy XSetWMHints\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIwmhints\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; XWMHints *\f(CIwmhints\f(CW\^; .LP .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the ID for which window manager hints are to be set. .IP \f(CIwmhints\fP Specifies a pointer to the window manager hints. .SH Description \f(CWXSetWMHints()\fP sets the window manager hints that include icon information and location, the initial state of the window, and whether the application relies on the window manager to get keyboard input. .LP This function is unnecessary in Release 4 and later if you call \f(CWXSetWMProperties()\fP. .LP See Volume One, Chapter 12, \fIInterclient Communication\fR, for a description of each \f(CWXWMHints\fP structure member. .SH "Structures" .Ps .ta 4.5n 1.7i typedef struct { long flags; /* marks defined fields in structure */ Bool input; /* does application need window manager for * keyboard input */ int initial_state; /* see below */ Pixmap icon_pixmap; /* pixmap to be used as icon */ Window icon_window; /* window to be used as icon */ int icon_x, icon_y; /* initial position of icon */ Pixmap icon_mask; /* icon mask bitmap */ XID window_group; /* ID of related window group */ /* this structure may be extended in the future */ } XWMHints; /* definitions for the flags field: */ #define InputHint (1L << 0) #define StateHint (1L << 1) #define IconPixmapHint (1L << 2) #define IconWindowHint (1L << 3) #define IconPositionHint (1L << 4) #define IconMaskHint (1L << 5) #define WindowGroupHint (1L << 6) #define AllHints (InputHint StateHint IconPixmapHint IconWindowHint \e IconPositionHint IconMaskHint WindowGroupHint) /* definitions for the initial state flag: */ #define WithdrawnState 0 /* application would like to be unmapped */ #define NormalState 1 /* most applications want to start this way */ #define IconicState 3 /* application wants to start as an icon */ .Pe .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXAllocWMHints()\fP\s+1, \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1. \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetZoomHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetWMIconName" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XSetWMIconName" .XX "XA_WM_ICON_NAME property" .Na XSetWMIconName \(en set a window's \f(CWXA_WM_ICON_NAME\fP property. .Nz .SH "Synopsis" .Sy void XSetWMIconName\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CItext_prop\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XTextProperty *\f(CItext_prop\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window. .IP \f(CItext_prop\fP 1i Specifies the \f(CWXTextProperty\fR structure to be used. .SH "Availability" Release 4 and later. .SH Description \f(CWXSetWMIconName()\fR performs an \f(CWXSetTextProperty()\fR to set the \f(CWXA_WM_ICON_NAME\fP property of the specified window. .XX "XSetIconName" \f(CWXSetWMIconName()\fP supersedes \f(CWXSetIconName()\fP. .LP This is usually called by an application to set the property for the window manager. The name should be short, since it is to be displayed in association with an icon. .LP \f(CWXSetStandardProperties()\fP (in Release 3) or \f(CWXSetWMProperties()\fP (in Release\ 4 and later) also set this property. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .Ps typedef struct { unsigned char *value; /* same as Property routines */ Atom encoding; /* prop type */ int format; /* prop data format: 8, 16, or 32 */ unsigned long nitems; /* number of data items in value */ } XTextProperty; .XX "XTextProperty structure" .XX "structures:XTextProperty" .Pe .SH "See Also" \s-1\fIXGetWMIconName()\fP\s+1, \s-1\fIXGetWMName()\fP\s+1, \s-1\fIXSetWMName()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetWMName" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XSetWMName" .XX "XA_WM_NAME property" .Na XSetWMName \(en set a window's \f(CWXA_WM_NAME\fP property. .Nz .SH "Synopsis" .Sy void XSetWMName\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CItext_prop\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XTextProperty *\f(CItext_prop\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window. .IP \f(CItext_prop\fP 1i Specifies the \f(CWXTextProperty\fR structure to be used. .SH "Availability" Release 4 and later. .SH Description \f(CWXSetWMName()\fR performs a \f(CWXSetTextProperty()\fR to set the \f(CWXA_WM_NAME\fP property on the specified window. .XX "XSetWMProperties:setting the XA_WM_NAME property" \f(CWXSetWMName()\fP supersedes \f(CWXStoreName()\fP. This property can also be set with \f(CWXSetWMProperties()\fP. .LP \f(CWXSetWMName()\fP should be used by the application to communicate a string to the window manager. According to current conventions, this string should either: .IP \(bu 3n permit the user to identify one of a number of instances of the same client, or .IP \(bu 3n provide the user with noncritical state information. .LP Clients can assume that at least the beginning of this string is visible to the user. .LP The \f(CWXA_WM_CLASS\fP property, on the other hand, has two members which should be used to identify the application's instance and class name, for the lookup of resources. See \f(CWXSetClassHint()\fP for details. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .Ps typedef struct { unsigned char *value; /* same as Property routines */ Atom encoding; /* prop type */ int format; /* prop data format: 8, 16, or 32 */ unsigned long nitems; /* number of data items in value */ } XTextProperty; .XX "XTextProperty structure" .XX "structures:XTextProperty" .Pe .ne 8 .SH "See Also" \s-1\fIXGetWMIconName()\fP\s+1, \s-1\fIXGetWMName()\fP\s+1, \s-1\fIXSetWMIconName()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetWMNormalHints" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XSetWMNormalHints" .XX "XA_WM_NORMAL_HINTS property" .Na XSetWMNormalHints \(en set a window's \f(CWXA_WM_NORMAL_HINTS\fP property. .Nz .SH "Synopsis" .Sy void XSetWMNormalHints\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CIhints\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XSizeHints *\f(CIhints\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window. .IP \f(CIhints\fP 1i Specifies the size hints for the window in its normal state. .SH "Availability" Release 4 and later. .SH Description \f(CWXSetWMNormalHints()\fR sets the size hints in the \f(CWXA_WM_NORMAL_HINTS\fP property on the specified window. The property is stored with a type of WM_SIZE_HINTS and a format of 32. .XX "XSetNormalHints:and XSetWMNormalHints" \f(CWXSetWMNormalHints()\fP supersedes \f(CWXSetNormalHints()\fP. This property can also be set with \f(CWXSetWMProperties()\fP. .LP Applications use \f(CWXSetNormalHints()\fP to inform the window manager of the sizes desirable for that window. .LP To set size hints, an application must assign values to the appropriate elements in the hints structure, and also set the \f(CWflags\fP field of the structure to indicate which members have assigned values and the source of the assignment. These flags are listed in the Structures section below. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .Ps typedef struct { long flags; /* marks which fields in this structure */ /* are defined */ int x, y; /* obsolete for new window mgrs, but clients */ int width, height; /* should set so old wm's don't mess up */ int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; int base_width, base_height; /* added by ICCCM version 1 */ int win_gravity; /* added by ICCCM version 1 */ } XSizeHints; .XX "XSizeHints structure" .XX "structures:XSizeHints" .ta 4n +1.1i 2.1i #define USPosition (1L << 0) /* user specified x, y */ #define USSize (1L << 1) /* user specified width, height */ #define PPosition (1L << 2) /* program specified position */ #define PSize (1L << 3) /* program specified size */ #define PMinSize (1L << 4) /* program specified minimum size */ #define PMaxSize (1L << 5) /* program specified maximum size */ #define PResizeInc (1L << 6) /* program specified resize increments * / #define PAspect (1L << 7) /* program specified min/max aspect ratios */ #define PAllHints (PPosition PSize PMinSize PMaxSize PResizeInc PAspect) #define PBaseSize (1L << 8) /* program specified base * for incrementing */ #define PWinGravity (1L << 9) /* program specified window gravity */ .Pe .SH "Errors" \f(CWBadAlloc\fR .br \f(CWBadWindow\fR .SH "See Also" \s-1\fIXGetWMNormalHints()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1, \s-1\fIXSetWMSizeHints()\fP\s+1, \s-1\fIXGetWMSizeHints()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetWMProperties" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XSetWMProperties" .XX "window manager:properties;setting" .XX "windows:standard window manager properties, setting" .Na XSetWMProperties \(en set a window's standard window manager properties. .Nz .SH "Synopsis" .Sy void XSetWMProperties\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CIwindow_name\fP\^, \ \f(CIicon_name\fP\^, \f(CIargv\fP\^, \f(CIargc\fP\^, \f(CInormal_hints\fP\^, \f(CIwm_hints\fP\^, \ \f(CIclass_hints\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XTextProperty *\f(CIwindow_name\fP\^; XTextProperty *\f(CIicon_name\fP\^; char **\f(CIargv\fP\^; int \f(CIargc\fP\^; XSizeHints *\f(CInormal_hints\fP\^; XWMHints *\f(CIwm_hints\fP\^; XClassHint *\f(CIclass_hints\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/SetWMProps 2.7 1993/05/28 13:38:07 stephen Exp $ .IP \f(CIw\fP 1i Specifies the window. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/SetWMProps 2.7 1993/05/28 13:38:07 stephen Exp $ .IP \f(CIwindow_name\fP 1i Specifies the window name, which should be a \f(CWNULL\fP-terminated string. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/SetWMProps 2.7 1993/05/28 13:38:07 stephen Exp $ .IP \f(CIicon_name\fP 1i Specifies the icon name, which should be a \f(CWNULL\fP-terminated string. .IP \f(CIargv\fP 1i Specifies the application's argument list. .IP \f(CIargc\fP 1i Specifies the number of arguments. .IP \f(CInormal_hints\fP 1i Specifies the size hints for the window in its normal state. .IP \f(CIwm_hints\fP 1i Specifies the \f(CWXWMHints\fR structure to be used. .IP \f(CIclass_hints\fP 1i Specifies the \f(CWXClassHint\fR structure to be used. .SH "Availability" Release 4 and later. .SH Description \f(CWXSetWMProperties()\fR provides a single programming interface for setting the essential window properties that communicate with window and session managers. .XX "XSetStandardProperties" \f(CWXSetWMProperties()\fP supersedes \f(CWXSetStandardProperties()\fP. .LP If the \f(CWwindow_name\fP argument is non-null, \f(CWXSetWMProperties()\fR calls \f(CWXSetWMName()\fR, which, in turn, sets the WM_NAME property. If the \f(CIicon_name\fP argument is non-null, \f(CWXSetWMProperties()\fR calls \f(CWXSetWMIconName()\fR, which sets the WM_ICON_NAME property. If the \f(CIargv\fP argument is non-null, \f(CWXSetWMProperties()\fR calls \f(CWXSetCommand()\fR, which sets the WM_COMMAND property. Note that an \f(CIargc\fP of 0 is allowed to indicate a zero-length command. .ne 12 \f(CWXSetWMProperties()\fP stores the hostname of this machine using \f(CWXSetWMClientMachine()\fR. .LP If the \f(CInormal_hints\fP argument is non-null, \f(CWXSetWMProperties()\fR calls \f(CWXSetWMNormalHints()\fR, which sets the WM_NORMAL_HINTS property. If the \f(CIwm_hints\fP argument is non-null, \f(CWXSetWMProperties()\fR calls \f(CWXSetWMHints()\fR, which sets the WM_HINTS property. .LP If the \f(CIclass_hints\fP argument is non-null, \f(CWXSetWMProperties()\fR calls \f(CWXSetClassHint()\fR, which sets the WM_CLASS property. If the \f(CWres_name\fP member in the \f(CWXClassHint\fR structure is set to the null pointer and the RESOURCE_NAME environment variable is set, then value of the environment variable is substituted for \f(CWres_name\fP. If the \f(CWres_name\fP member is \f(CWNULL\fP, and if the environment variable is not set, and if \f(CIargv\fP and \f(CIargv[0]\fP are set, then the value of \f(CIargv[0]\fP, stripped of any directory prefixes, is substituted for \f(CWres_name\fP. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .Ps .ps -1 typedef struct { unsigned char *value; /* same as Property routines */ Atom encoding; /* prop type */ int format; /* prop data format: 8, 16, or 32 */ unsigned long nitems; /* number of data items in value */ } XTextProperty; .XX "XTextProperty structure" .XX "structures:XTextProperty" typedef struct { long flags; /* marks which fields in this structure */ /* are defined */ int x, y; /* obsolete for new window mgrs, but clients */ int width, height; /* should set so old wm's don't mess up */ int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; int base_width, base_height; /* added by ICCCM version 1 */ int win_gravity; /* added by ICCCM version 1 */ } XSizeHints; .XX "XSizeHints structure" .XX "structures:XSizeHints" /* flags argument in size hints */ #define USPosition (1L << 0) /* user specified x, y */ #define USSize (1L << 1) /* user specified width, height */ #define PPosition (1L << 2) /* program specified position */ #define PSize (1L << 3) /* program specified size */ #define PMinSize (1L << 4) /* program specified minimum size */ #define PMaxSize (1L << 5) /* program specified maximum size */ #define PResizeInc (1L << 6) /* program specified resize increments */ #define PAspect (1L << 7) /* program specified min/max aspect ratios */ #define PAllHints (PPosition PSize PMinSize PMaxSize PResizeInc PAspect) #define PBaseSize (1L << 8) /* program specified base for incrementing */ #define PWinGravity (1L << 9) /* program specified window gravity */ typedef struct { long flags; /* marks which fields in this structure */ /* are defined */ Bool input; /* does this application rely on the window */ /* manager to get keyboard input? */ int initial_state; /* see below */ Pixmap icon_pixmap; /* pixmap to be used as icon */ Window icon_window; /* window to be used as icon */ int icon_x, icon_y; /* initial position of icon */ Pixmap icon_mask; /* icon mask bitmap */ .ne 4 XID window_group; /* id of related window group */ /* this structure may be extended in the future */ } XWMHints; .XX "XWMHints structure" .XX "structures:XWMHints" .ta 4n +1.1i 2.1i #define InputHint (1L << 0) #define StateHint (1L << 1) #define IconPixmapHint (1L << 2) #define IconWindowHint (1L << 3) #define IconPositionHint (1L << 4) #define IconMaskHint (1L << 5) #define WindowGroupHint (1L << 6) #define AllHints (InputHint StateHint IconPixmapHint IconWindowHint\ IconPositionHint IconMaskHint WindowGroupHint) #define PBaseSize (1L << 8) /* program specified base for incrementing */ #define PWinGravity (1L << 9) /* program specified window gravity */ typedef struct { char *res_name; char *res_class; } XClassHint; .ps +1 .Pe .SH "Errors" \f(CWBadAlloc\fR .br \f(CWBadWindow\fR .SH "See Also" \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetCommand()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetWMIconName()\fP\s+1, \s-1\fIXGetWMName()\fP\s+1, \s-1\fIXGetWMNormalHints()\fP\s+1, \s-1\fIXSetWMClientMachine()\fP\s+1, \s-1\fIXSetWMColormapWindows()\fP\s+1, \s-1\fIXSetWMProtocols()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetWMProtocols" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XSetWMProtocols" .XX "XA_WM_PROTOCOLS property" .Na XSetWMProtocols \(en set a window's \f(CWXA_WM_PROTOCOLS\fP property. .Nz .SH "Synopsis" .Sy Status XSetWMProtocols\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CIprotocols\fP\^, \ \f(CIcount\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; Atom *\f(CIprotocols\fP\^; int \f(CIcount\fP\^; .Ae .sp -1 .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/SetWMProtocol 2.7 1993/05/28 13:38:10 stephen Exp $ .IP \f(CIw\fP 1i Specifies the window. .IP \f(CIprotocols\fP 1i Specifies the list of protocols. .ds Cn protocols in the list .IP \f(CIcount\fP 1i Specifies the number of \*(Cn. .sp -1 .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description \f(CWXSetWMProtocols()\fR sets the \f(CWXA_WM_PROTOCOLS\fP property on the specified window to the list of atoms specified by the protocols argument. The property is stored with a type of ATOM and a format of 32. If it cannot intern the \f(CWXA_WM_PROTOCOLS\fP atom, \f(CWXSetWMProtocols()\fR returns a zero status. Otherwise, it returns a non-zero status. .LP The list of standard protocols at present is as follows: .in +5n .IP WM_TAKE_FOCUS 1.75i Assignment of keyboard focus. .IP WM_SAVE_YOURSELF 1.75i Save client state warning. .IP WM_DELETE_WINDOW 1.75i Request to delete top-level window. .in -5n .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .sp -.5 .SH "Errors" \f(CWBadAlloc\fR .br \f(CWBadWindow\fR .sp -.5 .SH "See Also" \s-1\fIXGetWMProtocols()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetWMSizeHints" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XSetWMSizeHints" .XX "XA_WM_SIZE_HINTS property" .Na XSetWMSizeHints \(en set a window's \f(CWXA_WM_SIZE_HINTS\fP property. .Nz .SH "Synopsis" .Sy void XSetWMSizeHints\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CIhints\fP\^, \f(CIproperty\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; XSizeHints *\f(CIhints\fP\^; Atom \f(CIproperty\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/SetWMSizeHint 2.5 1993/05/28 13:38:14 stephen Exp $ .IP \f(CIw\fP 1i Specifies the window. .IP \f(CIhints\fP 1i Specifies the \f(CWXSizeHints\fR structure to be used. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/SetWMSizeHint 2.5 1993/05/28 13:38:14 stephen Exp $ .IP \f(CIproperty\fP 1i Specifies the property name. .SH "Availability" Release 4 and later. .SH Description \f(CWXSetWMSizeHints()\fR sets the size hints for the specified property on the named window. The property is stored with a type of \f(CWXA_WM_SIZE_HINTS\fP and a format of 32. To set a window's normal size hints, you can use the \f(CWXSetWMNormalHints()\fR function instead. \f(CWXSetWMSizeHints()\fP supersedes \f(CWXSetSizeHints()\fP. .LP This routine is useful if new properties of type \f(CWXA_WM_SIZE_HINTS\fP are defined. .LP The \f(CWflags\fP member of \f(CWXSizeHints\fP must be set to the OR of the symbols representing each member to be set. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .Ps typedef struct { long flags; /* marks which fields in this structure are */ /* defined as */ int x, y; /* obsolete for new window mgrs, but clients */ int width, height; /* should set so old wm's don't mess up */ int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; .ne 12 int base_width, base_height; /* added by ICCCM version 1 */ int win_gravity; /* added by ICCCM version 1 */ } XSizeHints; .ta 4n +1.1i 2.1i #define USPosition (1L << 0) /* user specified x, y */ #define USSize (1L << 1) /* user specified width, height */ #define PPosition (1L << 2) /* program specified position */ #define PSize (1L << 3) /* program specified size */ #define PMinSize (1L << 4) /* program specified minimum size */ #define PMaxSize (1L << 5) /* program specified maximum size */ #define PResizeInc (1L << 6) /* program specified resize increments * / #define PAspect (1L << 7) /* program specified min/max aspect ratios */ #define PAllHints (PPosition PSize PMinSize PMaxSize PResizeInc PAspect) #define PBaseSize (1L << 8) /* program specified base for incrementing */ #define PWinGravity (1L << 9) /* program specified window gravity */ .Pe .SH "Errors" \f(CWBadAlloc\fR .br \f(CWBadAtom\fR .br \f(CWBadWindow\fR .SH "See Also" \s-1\fIXAllocSizeHints()\fP\s+1, \s-1\fIXGetWMNormalHints()\fP\s+1, \s-1\fIXGetWMSizeHints()\fP\s+1, \s-1\fIXSetWMNormalHints()\fP\s+1. .\"last line comment .TH XSetWindowB.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XSetWindowBackground@XSetWindowD .sp .5 XSetWindowBackgroundPixmap@XSetWindowE .sp .5 XSetWindowBorder@XSetWindowF .sp .5 XSetWindowBorderPixmap@XSetWindowG .sp .5 XSetWindowBorderWidth@XSetWindowH .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetWindowColormap" "Xlib \- Window Attributes" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetWindowColormap" .XX "windows:colormap attribute" .XX "colormap attribute:setting for windows" .Na XSetWindowColormap \(en set the colormap attribute for a window. .Nz .SH "Synopsis" .Sy XSetWindowColormap\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIcolormap\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; Colormap \f(CIcolormap\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the ID of the window for which you want to set the colormap. .IP \f(CIcolormap\fP Specifies the colormap. .SH Description \f(CWXSetWindowColormap()\fP sets the \f(CWcolormap\fP attribute of the specified window. The colormap need not be installed to be set as an attribute. \f(CIcolormap\fP will be used to translate pixel values drawn into this window when \f(CIcolormap\fP is installed in the hardware, which will be taken care of by the window manager. .LP In Release 3, applications must install their own colormaps if they cannot use the default colormap. In Release 4 and later, they should never do so. .LP The colormap must have the same visual as the window. .SH "Errors" .IP "\f(CWBadColor\fP" 1i Invalid colormap. .IP "\f(CWBadMatch\fP" 1i .IP "\f(CWBadWindow\fP" 1i .SH "See Also" \s-1\fIXChangeWindowAttributes()\fP\s+1, \s-1\fIXGetGeometry()\fP\s+1, \s-1\fIXGetWindowAttributes()\fP\s+1, \s-1\fIXSetWindowBackground()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXSetWindowBorder()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1, \s-1\fIXSetWMColormapWindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetWindowBackground" "Xlib \- Window Attributes" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetWindowBackground" .XX "background window attributes" .XX "windows:background attributes" .Na XSetWindowBackground \(en set the background pixel value attribute of a window. .Nz .SH "Synopsis" .Sy XSetWindowBackground\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIbackground_pixel\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; unsigned long \f(CIbackground_pixel\f(CW\^; .SH "Arguments" .IP \f(CIdisplay\f(CW .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\f(CW Specifies the window ID. Must be an \f(CWInputOutput\fP window. .IP \f(CIbackground_pixel\f(CW Specifies which entry in the colormap is used as the background color. The constant \f(CWCopyFromParent\fP is NOT valid. .SH Description \f(CWXSetWindowBackground()\fP sets the \f(CWbackground\fP attribute of a window, setting the pixel value to be used to fill the background. This overrides any previous call to .XX "XSetWindowBackground" .XX "XSetWindowBackgroundPixmap:and XSetWindowBackground" \f(CWXSetWindowBackground\fP or \f(CWXSetWindowBackgroundPixmap()\fP on the same window. .LP \f(CWXSetWindowBackground()\fP does not change the current window contents immediately. The background is automatically repainted after \f(CWExpose\fP events. You can also redraw the background without \f(CWExpose\fP events by calling \f(CWXClearWindow()\fP immediately after. .LP For more information, see Volume One, Chapter 4, \fIWindow Attributes\fR. .SH "Errors" .IP "\f(CWBadMatch\fP" 1i Setting background of \f(CWInputOnly\fP window. .IP "\f(CWBadWindow\fP" 1i .SH "See Also" \s-1\fIXChangeWindowAttributes()\fP\s+1, \s-1\fIXGetGeometry()\fP\s+1, \s-1\fIXGetWindowAttributes()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXSetWindowBorder()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "\s-2XSetWindowBackgroundPixmap\s+2" "Xlib \- Pixmaps and Tiles" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetWindowBackgroundPixmap" .Na XSetWindowBackgroundPixmap \(en change the background tile attribute of a window. .Nz .SH "Synopsis" .Sy XSetWindowBackgroundPixmap\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIbackground_pixmap\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; Pixmap \f(CIbackground_pixmap\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the window ID. Must be an \f(CWInputOutput\fP class window. .IP \f(CIbackground_pixmap\fP Specifies a pixmap ID, \f(CWNone\fP or \f(CWParentRelative\fP, to be used as a background. .SH Description .XX "background_pixmap attribute" .XX "windows:background_pixmap attribute" \f(CWXSetWindowBackgroundPixmap()\fP sets the \f(CWbackground_pixmap\fP attribute of a \%window. This overrides any previous \f(CWbackground_pixel\fP or \f(CWbackground_pixmap\fP \%attribute .XX "XSetWindowBackgroundPixmap:and XSetWindowBackgroundPixmap" .XX "XSetWindowBackground:and XSetWindowBackgroundPixmap" .XX "XChangeWindowAttributes:and XSetWindowBackgroundPixmap" setting set with \f(CWXSetWindowBackgroundPixmap()\fP, \f(CWXSetWindowBackground()\fP, or \f(CWXChangeWindowAttributes()\fP. Drawing into the pixmap that was set as the background pixmap attribute has an undefined effect on the window background. The server may or may not make a copy of the pixmap. .LP If the background is set to a pixmap, the background is tiled with the pixmap. If the pixmap is not explicitly referenced again, it can be freed, since a copy is maintained in the server. The background of the window will not be redrawn with the new tile until the next \f(CWExpose\fP event or \f(CWXClearWindow()\fP call. .LP If the background is set to \f(CWNone\fP, the window background initially will be invisible and will share the bits of its parent, but only if the \f(CWbackground_pixel\fP attribute is not set. When anything is drawn by any client into the area enclosed by the window, the contents will remain until the area is explicitly cleared with \f(CWXClearWindow()\fP. The background is not automatically refreshed after exposure. .LP If the background is set to \f(CWParentRelative\fP, the parent's background is used, and the origin for tiling is the parent's origin (or the parent's parent if the parent's \f(CWbackground_pixmap\fP attribute is also \f(CWParentRelative\fP, and so on). The difference between setting \f(CWParentRelative\fP and explicitly setting the same pixmap as the parent is the origin of the tiling. The difference between \f(CWParentRelative\fP and \f(CWNone\fP is that for \f(CWParentRelative\fP the background is automatically repainted on exposure. .LP For \f(CWParentRelative\fP, the window must have the same depth as the parent, or a \f(CWBadMatch\fP error will occur. If the parent has background \f(CWNone\fP, then the window will also have background \f(CWNone\fP. The parent's background is re-examined each time the window background is required (when it needs to be redrawn due to mapping or exposure). The window's contents .ne 2 will be lost when the window is moved relative to its parent, and the contents will have to be redrawn. .LP Changing the \f(CWbackground_pixmap\fP attribute of the root window to \f(CWNone\fP or \f(CWParentRelative\fP restores the default. .LP \f(CWXSetWindowBackgroundPixmap()\fP can only be performed on an \f(CWInputOutput\fP window. A \f(CWBadMatch\fP error will result otherwise. .LP \f(CWXSetWindowBackground()\fP may be used if a solid color instead of a tile is desired. .LP For more information, see Volume One, Chapter 4, \fIWindow Attributes\fR. .SH "Errors" \f(CWBadMatch\fP .br \f(CWBadPixmap\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXCreateBitmapFromData()\fP\s+1, \s-1\fIXCreatePixmap()\fP\s+1, \s-1\fIXCreatePixmapFromBitmapData()\fP\s+1, \s-1\fIXFreePixmap()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXQueryBestStipple()\fP\s+1, \s-1\fIXQueryBestTile()\fP\s+1, \s-1\fIXReadBitmapFile()\fP\s+1, \s-1\fIXSetTile()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1, \s-1\fIXWriteBitmapFile()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetWindowBorder" "Xlib \- Window Attributes" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetWindowBorder" .XX "windows:borders;setting" .Na XSetWindowBorder \(en change a window border pixel value attribute and repaint the border. .Nz .SH "Synopsis" .Sy XSetWindowBorder\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIborder_pixel\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; unsigned long \f(CIborder_pixel\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP .88i Specifies the window ID. Must be an \f(CWInputOutput\fP window. .IP \f(CIborder_pixel\fP .88i Specifies the colormap entry with which the server will paint the border. .SH Description .XX "border_pixel attribute" \f(CWXSetWindowBorder()\fP sets the \f(CWborder_pixel\fP attribute of window \f(CIw\fP to a pixel value, and repaints the border. The border is also automatically repainted after \f(CWExpose\fP events. .LP Use \f(CWXSetWindowBorderPixmap()\fR to create a tiled border. On top-level windows, the window manager often resets the border, so applications should not depend on their settings. .LP For more information, see Volume One, Chapter 4, \fIWindow Attributes\fR. .SH "Errors" .IP "\f(CWBadMatch\fP" 1i Setting border of \f(CWInputOnly\fP window. .IP "\f(CWBadWindow\fP" 1i .SH "See Also" \s-1\fIXChangeWindowAttributes()\fP\s+1, \s-1\fIXGetGeometry()\fP\s+1, \s-1\fIXGetWindowAttributes()\fP\s+1, \s-1\fIXSetWindowBackground()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetWindowBorderPixmap" "Xlib \- Pixmaps and Tiles" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetWindowBorderPixmap" .Na XSetWindowBorderPixmap \(en change a window border tile attribute and repaint the border. .Nz .SH "Synopsis" .Sy XSetWindowBorderPixmap\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIborder_pixmap\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; Pixmap \f(CIborder_pixmap\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of an \f(CWInputOutput\fP window whose border is to be to a file. .IP \f(CIborder_pixmap\fP 1i Specifies any pixmap or \f(CWCopyFromParent\fP. .SH Description .XX "border_pixmap attribute" .XX "windows:borders:border_pixmap attribute" \f(CWXSetWindowBorderPixmap()\fP sets the \f(CWborder_pixmap\fP attribute of a window and repaints the border. The \f(CWborder_pixmap\fP can be freed immediately after the call if no further explicit references to it are to be made. If you specify \f(CWCopyFromParent\fP, a copy of the parent window's border pixmap is used. .LP This function can only be performed on an \f(CWInputOutput\fP window. On top-level windows, the window manager often resets the border, so applications should not depend on their settings. .SH "Errors" \f(CWBadMatch\fP .br \f(CWBadPixmap\fP .br \f(CWBadWindow\fP .SH "See Also" \s-1\fIXCreateBitmapFromData()\fP\s+1, \s-1\fIXCreatePixmap()\fP\s+1, \s-1\fIXCreatePixmapFromBitmapData()\fP\s+1, \s-1\fIXFreePixmap()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXQueryBestStipple()\fP\s+1, \s-1\fIXQueryBestTile()\fP\s+1, \s-1\fIXReadBitmapFile()\fP\s+1, \s-1\fIXSetTile()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXWriteBitmapFile()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetWindowBorderWidth" "Xlib \- Window Manipulation" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetWindowBorderWidth" .XX "windows:borders:changing width of" .XX "border width:changing" .Na XSetWindowBorderWidth \(en change the border width of a window. .Nz .SH "Synopsis" .Sy XSetWindowBorderWidth\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIwidth\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; unsigned int \f(CIwidth\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the ID of the window whose border is to be changed. .IP \f(CIwidth\fP Specifies the width of the window border. .SH Description \f(CWXSetWindowBorderWidth()\fP changes the border width of a window. This request is often used on top-level windows by the window manager as an indication of the current keyboard focus window, so other clients should not depend on the border width of top-level windows. .SH Errors .IP "\f(CWBadMatch\fP" 1i Setting border width of an \f(CWInputOnly\fP window. .IP "\f(CWBadWindow\fP" .SH "See Also" \s-1\fIXCirculateSubwindows()\fP\s+1, \s-1\fIXCirculateSubwindowsDown()\fP\s+1, \s-1\fIXCirculateSubwindowsUp()\fP\s+1, \s-1\fIXConfigureWindow()\fP\s+1, \s-1\fIXLowerWindow()\fP\s+1, \s-1\fIXMoveResizeWindow()\fP\s+1, \s-1\fIXMoveWindow()\fP\s+1, \s-1\fIXQueryTree()\fP\s+1, \s-1\fIXRaiseWindow()\fP\s+1, \s-1\fIXReparentWindow()\fP\s+1, \s-1\fIXResizeWindow()\fP\s+1, \s-1\fIXRestackWindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSetZoomHints" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSetZoomHints" .Na XSetZoomHints \(en set the size hints property of a zoomed window. .Nz .SH "Synopsis" .Sy XSetZoomHints\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW, \f(CIzhints\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; XSizeHints *\f(CIzhints\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP Specifies the ID of the window for which zoom hints are to be set. .IP \f(CIzhints\fP Specifies a pointer to the zoom hints. .SH Description .XX "zoom hints" .XX "windows:zoomed" .XX "XA_WM_ZOOM_HINTS property" \f(CWXSetZoomHints()\fP is no longer used as of Release 3. .LP \f(CWXSetZoomHints()\fP sets the \f(CWXA_WM_ZOOM_HINTS\fP property for an application's top-level window in its zoomed state. Many window managers think of windows in three states: iconified, normal, or zoomed, corresponding to small, medium, and large. Applications use \f(CWXSetZoomHints()\fP to inform the window manager of the size or position desirable for the zoomed window. .LP In addition, an application wanting to move or resize its zoomed window should call \f(CWXSetZoomHints()\fP specifying its new desired location and size, in addition to making direct X calls to move or resize. This is because some window managers may redirect window configuration requests, but ignore the resulting events and pay attention to property changes instead. .LP To set size hints, an application must assign values to the appropriate elements in the hints structure, and set the \f(CWflags\fP field of the structure to indicate which members have assigned values and the source of the assignment. These flags are listed in the Structures section below. .LP For more information on using hints, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Structures" .Ps .ta 4.5n +1i 2i typedef struct { long flags; /* marks defined fields in structure */ int x, y; int width, height; int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { .in +10n int x; /* numerator */ int y; /* denominator */ .in -10n .ta 4.5n +1i 2i } min_aspect, max_aspect; int base_width, base_height; int win_gravity; } XSizeHints; .ne 10 /* flags argument in size hints */ #define USPosition (1L << 0) /* user specified x, y */ #define USSize (1L << 1) /* user specified width, height */ #define PPosition (1L << 2) /* program specified position */ #define PSize (1L << 3) /* program specified size */ #define PMinSize (1L << 4) /* program specified minimum size */ #define PMaxSize (1L << 5) /* program specified maximum size */ #define PResizeInc (1L << 6) /* program specified resize increments */ #define PAspect (1L << 7) /* program specified min/max aspect ratios */ #define PAllHints (PPosition PSize PMinSize PMaxSize PResizeInc PAspect) #define PBaseSize (1L << 8) #define WinGravity (1L << a) .Pe .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadWindow\fP .br .ne 5 .SH "See Also" \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXGetZoomHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetIconSizes()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXStoreName()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XShrinkRegion" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XShrinkRegion" .XX "regions:reducing and expanding" .Na XShrinkRegion \(en reduce or expand the size of a region. .Nz .SH "Synopsis" .Sy XShrinkRegion\^(\^\f(CIr\f(CW\^, \f(CIdx\f(CW\^, \f(CIdy\f(CW\^) .As Region \f(CIr\f(CW\^; int \f(CIdx\f(CW\^, \f(CIdy\f(CW\^; .Ae .SH "Arguments" .IP \f(CIr\fP 1i Specifies the region. .IP \f(CIdx\fP 1i .br .ns .IP \f(CIdy\fP 1i .sp -2 Specify the amounts by which you want to shrink or expand the specified region. Positive values shrink the region while negative values expand the region. .SH Description \f(CWXShrinkRegion()\fP changes the width and/or height of the specified region. Positive values shrink the region; negative values expand the region. It is legal to expand the region in one dimension at the same time as shrinking it in the other dimension. The offset of the region is changed to keep the center of the resized region near its original position. .LP The exact amount of shrinkage for a given value for \f(CWdx\fP or \f(CWdy\fP is not specified by Xlib. .SH "Structures" \f(CWRegion\fP is a pointer to an opaque structure type. .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXCreateRegion()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XStoreBuffer" "Xlib \- Cut Buffers" .ds ]W Xlib Reference Manual .SH "Name" .XX "XStoreBuffer" .XX "cut buffers" .Na XStoreBuffer \(en store data in a cut buffer. .Nz .SH "Synopsis" .Sy XStoreBuffer\^(\^\f(CIdisplay\f(CW, \f(CIbytes\f(CW\^, \f(CInbytes\f(CW\^, \f(CIbuffer\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; char \^\f(CIbytes\f(CW[]\^; int \^\f(CInbytes\f(CW\^; int \f(CIbuffer\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .86i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIbytes\fP Specifies the string of bytes you want stored. The byte string is not necessarily ASCII or \f(CWNULL\fP-terminated. .IP \f(CInbytes\fP Specifies the number of bytes in the string. .IP \f(CIbuffer\fP Specifies the cut buffer in which to store the byte string. Must be in the range 0\^-\^7. .SH Description .XN "buffers:(see also cut buffers)" \f(CWXStoreBuffer()\fP stores the specified data into any one of the eight cut buffers. All eight buffers must be stored into before they can be circulated with \f(CWXRotateBuffers()\fP. The cut buffers are numbered 0 through 7. Use \f(CWXFetchBuffer()\fP to recover data from any cut buffer. .LP Note that selections are the preferred method of transferring data between applications. .LP For more information on cut buffers, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. For more information on selections, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadAtom\fP .SH "See Also" \s-1\fIXFetchBuffer()\fP\s+1, \s-1\fIXFetchBytes()\fP\s+1, \s-1\fIXRotateBuffers()\fP\s+1, \s-1\fIXStoreBytes()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XStoreBytes" "Xlib \- Cut Buffers" .ds ]W Xlib Reference Manual .SH "Name" .XX "XStoreBytes" .XX "cut buffers" .Na XStoreBytes \(en store data in cut buffer 0. .Nz .SH "Synopsis" .Sy XStoreBytes\^(\^\f(CIdisplay\f(CW, \f(CIbytes\f(CW\^, \f(CInbytes\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; char \^\f(CIbytes\f(CW[]\^; int \^\f(CInbytes\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIbytes\fP .88i Specifies the string of bytes to store. The byte string is not necessarily ASCII or \f(CWNULL\fP-terminated. .IP \f(CInbytes\fP .88i Specifies the number of bytes to store. .SH Description \f(CWXStoreBytes()\fP stores data in cut buffer 0, usually for reading by another client that already knows the meaning of the contents. Note that the cut buffer's contents need not be text, so null bytes are not special. .LP The cut buffer's contents may be retrieved later by any client calling \f(CWXFetchBytes()\fP. .LP Use \f(CWXStoreBuffer()\fP to store data in buffers 1-7. Note that selections are the preferred method of transferring data between applications. .LP For more information on cut buffers, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. For more information on selections, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Errors" \f(CWBadAlloc\fP .SH "See Also" \s-1\fIXFetchBuffer()\fP\s+1, \s-1\fIXFetchBytes()\fP\s+1, \s-1\fIXRotateBuffers()\fP\s+1, \s-1\fIXStoreBuffer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XStoreColor" "Xlib \- Color Cells" .ds ]W Xlib Reference Manual .SH "Name" .XX "XStoreColor" .Na XStoreColor \(en set or change the RGB values of a read/write colormap entry to the closest possible hardware color. .Nz .SH "Synopsis" .Sy XStoreColor\^(\^\f(CIdisplay\f(CW, \f(CIcmap\f(CW\^, \f(CIcolorcell_def\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcmap\f(CW\^; XColor *\f(CIcolorcell_def\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.25i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcmap\fP Specifies the colormap. .IP \f(CIcolorcell_def\fP Specifies a pixel value and the desired RGB values. .SH Description .hw colorcell .XX "color:storing" \f(CWXStoreColor()\fP changes the RGB values of a colormap entry specified by \f(CIcolorcell_def.pixel\fR to the closest values possible on the hardware. This pixel value must be a read/write cell and a valid index into \f(CIcmap\fP. \f(CWXStoreColor()\fP changes the red, green, and/or blue color components in the cell according to the \f(CWcolorcell_def.flags\fR member, which you set by ORing the constants \f(CWDoRed\fP, \f(CWDoGreen\fP, and/or \f(CWDoBlue\fP. .LP If the colormap is an installed map for its screen, the changes are visible immediately. .LP For more information, see Volume One, Chapter 7, \fIColor\fR. .SH "Structures" .Ps typedef struct { unsigned long pixel; unsigned short red, green, blue; char flags; /* DoRed, DoGreen, DoBlue */ char pad; } XColor; .Pe .SH "Errors" .IP "\f(CWBadAccess\fP" 1i A specified pixel is unallocated or read-only. .br .IP "\f(CWBadColor\fP" 1i Invalid colormap. .IP "\f(CWBadValue\fP" 1i \f(CIpixel\fP not valid index into \f(CIcmap\fP. .br .ne 5 .SH "See Also" \s-1\fIXBlackPixel()\fP\s+1, \s-1\fIXWhitePixel()\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocColorCells()\fP\s+1, \s-1\fIXAllocColorPlanes()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXFreeColors()\fP\s+1, \s-1\fIXLookupColor()\fP\s+1, \s-1\fIXParseColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1, \s-1\fIXStoreNamedColor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XStoreColors" "Xlib \- Color Cells" .ds ]W Xlib Reference Manual .SH "Name" .XX "XStoreColors" .XX "color:changing RGB values to closest hardware colors" .Na XStoreColors \(en set or change the RGB values of read/write colorcells to the closest possible hardware colors. .Nz .SH "Synopsis" .Sy XStoreColors\^(\^\f(CIdisplay\f(CW, \f(CIcolormap\f(CW\^, \f(CIcolor\f(CW\^, \f(CIncolors\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcolormap\f(CW\^; XColor \f(CIcolor\f(CW\^[\^\f(CIncolors\f(CW\^]\^; int \f(CIncolors\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcolormap\fP Specifies the colormap. .IP \f(CIcolor\fP Specifies an array of color definition structures. .IP \f(CIncolors\fP .\"Specifies the number of color definition structures. Specifies the number of \f(CWXColor\fP structures in \f(CIcolor\fP. .SH Description \f(CWXStoreColors()\fP changes the RGB values of each colormap entry specified by \f(CIcolor[].pixel\fR to the closest possible hardware colors. Each pixel value must be a read/write cell and a valid index into \f(CIcolormap\fP. \f(CWXStoreColors()\fP changes the red, green, and/or blue color components in each cell according to the \f(CWcolor[].flags\fR member, which you set by ORing the constants \f(CWDoRed\fP, \f(CWDoGreen\fP, and/or \f(CWDoBlue\fP. The specified pixels are changed if they are writable by any client, even if one or more pixels generates an error. .LP If the colormap is an installed map for its screen, the changes are visible immediately. For more information, see Volume One, Chapter 7, \fIColor\fR. .SH "Structures" .Ps typedef struct { unsigned long pixel; unsigned short red, green, blue; char flags; /* DoRed, DoGreen, DoBlue */ char pad; } XColor; .Pe .Nd 5 .SH "Errors" .IP "\f(CWBadAccess\fP" 1i A specified pixel is unallocated or read-only. .br .IP "\f(CWBadColor\fP" Invalid colormap. .IP "\f(CWBadValue\fP" 1i A specified pixel is not a valid entry into \f(CIcolormap\fP. .Nd 6 .SH "See Also" \s-1\fIXBlackPixel()\fP\s+1, \s-1\fIXWhitePixel()\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocColorCells()\fP\s+1, \s-1\fIXAllocColorPlanes()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXFreeColors()\fP\s+1, \s-1\fIXLookupColor()\fP\s+1, \s-1\fIXParseColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreNamedColor()\fP\s+1. .\"last line comment .TH XStoreColor.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XStoreColor@XStoreColoA .sp .5 XStoreColors@XStoreColoB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XStoreName" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XStoreName" .Na XStoreName \(en assign a name to a window for the window manager. .Nz .SH "Synopsis" .Sy XStoreName\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIwindow_name\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; char *\f(CIwindow_name\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window to which you want to assign a name. .IP \f(CIwindow_name\fP 1i Specifies the name of the window. The name should be a \f(CWNULL\fP-terminated string. If the string is not in the Host Portable Character Encoding, the result is implementation-dependent. This name is returned by any subsequent call to \f(CWXFetchName()\fP. .SH Description \f(CWXStoreName()\fP is superseded in Release 4 by \f(CWXSetWMName()\fP. .LP .XX "XA_WM_NAME property" \f(CWXStoreName()\fP sets the \f(CWXA_WM_NAME\fP property, which should be used by the application to communicate the following information to the window manager, according to current conventions: .IP \(bu 3n To permit the user to identify one of a number of instances of the same client. .IP \(bu 3n To provide the user with noncritical state information. .LP Clients can assume that at least the beginning of this string is visible to the user. .LP The \f(CWXA_WM_CLASS\fP property, on the other hand, has two members which should be used to identify the application's instance and class name, for the lookup of resources. See \f(CWXSetClassHint()\fP for details. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fR. .SH "Errors" \f(CWBadAlloc\fP .br \f(CWBadWindow\fP .Nd 5 .SH "See Also" \s-1\fIXFetchName()\fP\s+1, \s-1\fIXGetClassHint()\fP\s+1, \s-1\fIXGetIconName()\fP\s+1, \s-1\fIXGetIconSizes()\fP\s+1, \s-1\fIXGetNormalHints()\fP\s+1, \s-1\fIXGetSizeHints()\fP\s+1, \s-1\fIXGetTransientForHint()\fP\s+1, \s-1\fIXGetWMHints()\fP\s+1, \s-1\fIXSetClassHint()\fP\s+1, \s-1\fIXSetCommand()\fP\s+1, \s-1\fIXSetIconName()\fP\s+1, \s-1\fIXSetNormalHints()\fP\s+1, \s-1\fIXSetSizeHints()\fP\s+1, \s-1\fIXSetTransientForHint()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XStoreNamedColor" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual .SH "Name" .XX "XStoreNamedColor" .Na .XX "color:RGB values;setting by color name" XStoreNamedColor \(en set RGB values of a read/write colorcell by color name. .Nz .SH "Synopsis" .Sy XStoreNamedColor\^(\^\f(CIdisplay\f(CW, \f(CIcolormap\f(CW\^, \f(CIcolor\f(CW\^, \f(CIpixel\f(CW\^, \f(CIflags\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcolormap\f(CW\^; char *\^\f(CIcolor\f(CW\^; unsigned long \f(CIpixel\f(CW\^; int \f(CIflags\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP .88i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcolormap\fP Specifies the colormap. .IP \f(CIcolor\fP Specifies the color name string (for example, "red"). This cannot be in hex format (as used in \&\f(CWXParseColor()\fP). Uppercase or lowercase is not important. The string should be in ISO LATIN-1 encoding, which means that the first 128 character codes are ASCII, and the second 128 character codes are for special characters needed in western languages other than English. .IP \f(CIpixel\fP Specifies the entry in the colormap to store color in. .IP \f(CIflags\fP Specifies which red, green, and blue indexes are set. .SH Description \f(CWXStoreNamedColor()\fP looks up the named \f(CIcolor\fP in the database, with respect to the screen associated with \f(CIcolormap\fP, then stores the result in the read/write colorcell of \f(CIcolormap\fP specified by \f(CIpixel\fP. If the color name is not in the Host Portable Character Encoding, the result is implementation-dependent. Uppercase or lowercase in name does not matter. The \f(CIflags\fP argument, a bitwise OR of the constants \f(CWDoRed\fP, \f(CWDoGreen\fP, and \f(CWDoBlue\fP, determines which subfields within the pixel value in the cell are written. .LP For more information, see Volume One, Chapter 7, \fIColor\fR. .SH "Errors" .IP "\f(CWBadAccess\fP" 1i \f(CIpixel\fP is unallocated or read-only. .IP "\f(CWBadColor\fP" 1i Invalid colormap. .IP "\f(CWBadName\fP" 1i \f(CIcolor\fP is not in server's color database. .IP "\f(CWBadValue\fP" 1i \f(CIpixel\fP is not a valid index into \f(CIcolormap\fP. .Nd 10 .SH "See Also" \s-1\fIXDefaultColormap()\fP\s+1, \s-1\fIXDisplayCells()\fP\s+1, \s-1\fIXCopyColormapAndFree()\fP\s+1, \s-1\fIXCreateColormap()\fP\s+1, \s-1\fIXFreeColormap()\fP\s+1, \s-1\fIXGetStandardColormap()\fP\s+1, \s-1\fIXInstallColormap()\fP\s+1, \s-1\fIXListInstalledColormaps()\fP\s+1, \s-1\fIXSetStandardColormap()\fP\s+1, \s-1\fIXSetWindowColormap()\fP\s+1, \s-1\fIXUninstallColormap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "\s-2XStringListToTextProperty\s+2" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XStringListToTextProperty" .XX "string lists:setting to an XTextProperty structure" .Na XStringListToTextProperty \(en set the specified list of strings to an \f(CWXTextProperty\fR structure. .Nz .sp -2p .SH "Synopsis" .Sy Status XStringListToTextProperty\^(\^\f(CIlist\fP\^, \f(CIcount\fP\^, \ \f(CItext_prop_return\fP\^) .As char **\f(CIlist\fP\^; int \f(CIcount\fP\^; XTextProperty *\f(CItext_prop_return\fP\^; .Ae .sp -4p .SH "Arguments" .IP \f(CIlist\fP 1i Specifies a list of \f(CWNULL\fP-terminated character strings. .ds Cn strings .IP \f(CIcount\fP 1i Specifies the number of \*(Cn. .IP \f(CItext_prop_return\fP 1i Returns the \f(CWXTextProperty\fR structure. .sp -2p .SH Returns Zero on failure, non-zero on success. .sp -2p .SH "Availability" Release 4 and later. .SH Description \f(CWXStringListToTextProperty()\fR fills the specified \f(CWXTextProperty\fR structure so that it represents a property of type STRING (format 8) with a value representing the concatenation of the specified list of null-separated character strings. An extra byte containing \f(CWNULL\fP (which is not included in the \f(CWnitems\fP member) is stored at the end of the \f(CWvalue\fP field of \f(CWtext_prop\fP. The strings are assumed (without verification) to be in the STRING encoding. If memory is not available for the new value string, \f(CWXStringListToTextProperty()\fR does not set any fields in the \f(CWXTextProperty\fR structure and returns a zero status. Otherwise, it returns a non-zero status. \f(CWXFree()\fR frees the storage for the \f(CWvalue\fP field. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .sp -2p .SH "Structures" .Ps typedef struct { unsigned char *value; /* same as Property routines */ Atom encoding; /* prop type */ int format; /* prop data format: 8, 16, or 32 */ unsigned long nitems; /* number of data items in value */ } XTextProperty; .Pe .sp -4p .ne 3 .SH "See Also" \s-1\fIXSetTextProperty()\fP\s+1, \s-1\fIXGetTextProperty()\fP\s+1, \s-1\fIXTextPropertyToStringList()\fP\s+1, \s-1\fIXFreeStringList()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XStringToKeysym" "Xlib \- Keyboard" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XStringToKeysym" .XX "keysyms:converting name strings to XStringToKeysym \(en convert a keysym name string to a keysym. .Nz .SH "Synopsis" .Sy KeySym XStringToKeysym\^(\^\f(CIstring\f(CW\^) .As char *\f(CIstring\f(CW\^; .Ae .SH "Arguments" .IP \f(CIstring\fP 1i Specifies the name of the keysym that is to be converted. .SH Returns The keysym. .SH Description \f(CWXStringToKeysym()\fP translates the character string version of a keysym name ("Shift") to the matching keysym which is a constant (\&\f(CWXK_Shift\fP). Valid keysym names are listed in \fI\fR. If the keysym name is not in the Host Portable Character Encoding, the result is implementation-dependent. If the specified string does not match a valid keysym, \f(CWXStringToKeysym()\fP returns \f(CWNoSymbol\fP. .LP This string is not the string returned in the \&\f(CIbuffer\fP argument of \&\f(CWXLookupString()\fP, which can be set with \&\f(CWXRebindKeysym()\fP. If that string is used, \&\f(CWXStringToKeysym()\fP will return \&\f(CWNoSymbol\fP except by coincidence. .LP In Release 4, \f(CWXStringToKeysym()\fP can return keysyms that are not defined by the Xlib standard. Note that the set of keysyms that are available in this manner and the mechanisms by which Xlib obtains them is implementation-dependent. (In the MIT sample implementation, the resource file \fI/usr/lib/X11/XKeysymDB\fR is used starting in Release 4. The keysym name is used as the resource name, and the resource value is the keysym value in uppercase hexadecimal.) .LP For more information, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "See Also" \s-1\fIXChangeKeyboardMapping()\fP\s+1, \s-1\fIXDeleteModifiermapEntry()\fP\s+1, \s-1\fIXFreeModifiermap()\fP\s+1, \s-1\fIXGetKeyboardMapping()\fP\s+1, \s-1\fIXGetModifierMapping()\fP\s+1, \s-1\fIXInsertModifiermapEntry()\fP\s+1, \s-1\fIXKeycodeToKeysym()\fP\s+1, \s-1\fIXKeysymToKeycode()\fP\s+1, \s-1\fIXKeysymToString()\fP\s+1, \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXLookupString()\fP\s+1, \s-1\fIXNewModifierMap\fP\s+1, \s-1\fIXQueryKeymap()\fP\s+1, \s-1\fIXRebindKeysym()\fP\s+1, \s-1\fIXRefreshKeyboardMapping()\fP\s+1, \s-1\fIXSetModifierMapping()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSubImage" "Xlib \- Images" .ds ]W Xlib Reference Manual .SH Name .Na .XX "XSubImage" .XX "subimages:creating from part of an image" .XX "images:creating subimages from" XSubImage \(en create a subimage from part of an image. .Nz .SH "Synopsis" .Sy XImage *XSubImage\^(\^\f(CIximage\f(CW, \f(CIx\f(CW, \f(CIy\f(CW, \f(CIsubimage_width\f(CW, \f(CIsubimage_height\f(CW\^) .As XImage *\f(CIximage\f(CW\^; int \f(CIx\f(CW\^;\^y; unsigned int \f(CIsubimage_width\f(CW\^, \f(CIsubimage_height\f(CW\^; .Ae .SH "Arguments" .IP \f(CIximage\fP 1.6i Specifies a pointer to the image. .IP \f(CIx\fP .br .ns .IP \f(CIy\fP .sp -2 Specify the x and y coordinates in the existing image where the subimage will be extracted. .LP .IP \f(CIsubimage_width\fP 1.6i .br .ns .IP \f(CIsubimage_height\fP .sp -1.5 Specify the width and height (in pixels) of the new subimage. .SH Returns The created image. .SH Description \f(CWXSubImage()\fP creates a new image that is a subsection of an existing one. It allocates the memory necessary for the new \f(CWXImage\fP structure and returns a pointer to the new image. The data is copied from the source image, and the rectangle defined by \f(CIx\fP, \f(CIy\fP, \f(CIsubimage_width\fP, and \f(CIsubimage_height\fP must by contained in the image. .LP \f(CWXSubImage()\fP extracts a subimage from an image, while \f(CWXGetSubImage()\fP extracts an image from a drawable. .LP For more information on images, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "See Also" \s-1\fIXImageByteOrder()\fP\s+1, \s-1\fIXAddPixel()\fP\s+1, \s-1\fIXCreateImage()\fP\s+1, \s-1\fIXDestroyImage()\fP\s+1, \s-1\fIXGetImage()\fP\s+1, \s-1\fIXGetPixel()\fP\s+1, \s-1\fIXGetSubImage()\fP\s+1, \s-1\fIXPutImage()\fP\s+1, \s-1\fIXPutPixel()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSubtractRegion" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSubtractRegion" .XX "regions:subtracting one from another" .Na XSubtractRegion \(en subtract one region from another. .Nz .SH "Synopsis" .Sy XSubtractRegion\^(\^\f(CIsra\f(CW\^, \f(CIsrb\f(CW\^, \f(CIdr_return\f(CW\^) .As Region \f(CIsra\f(CW\^, \f(CIsrb\f(CW\^; Region \f(CIdr_return\fP; .Ae .SH "Arguments" .IP \f(CIsra\fP 1i .br .ns .IP \f(CIsrb\fP 1i .sp -2 Specify the two regions in which you want to perform the computation. .sp .IP \f(CIdr_return\fP 1i Returns the result of the computation. .SH Description \f(CWXSubtractRegion()\fP calculates the difference between the two regions specified (\f(CIsra\fP \- \f(CIsrb\fP) and puts the result in \f(CIdr_return\fP. .LP This function returns a region which contains all parts of \f(CIsra\fP that are not also in \f(CIsrb\fP. .LP For more information on regions, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" \f(CWRegion\fP is a pointer to an opaque structure type. .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXCreateRegion()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSupportsLocale" "Xlib \- Locale Management" .ds ]W Xlib Reference Manual .XX "XSupportsLocale" .XX "locale:support, determining" .SH Name .Na XSupportsLocale \(en determine locale support. .Nz .SH Synopsis .Sy Bool XSupportsLocale\^(\ ) .SH Returns \f(CWTrue\fP if supported, else \f(CWFalse\fP. .SH Availability Release 5 and later. .SH Description \f(CWXSupportsLocale()\fP returns \f(CWTrue\fP if Xlib functions are capable of operating under the current locale. If \f(CWXSupportsLocale()\fP returns \f(CWFalse\fP, the client should usually switch to a supported locale or exit. When the current locale is not supported, some Xlib routines will return the status \f(CWXLocaleNotSupported\fP, and others will silently operate in the default C locale. .SH "See Also" \s-1\fIXSetLocaleModifiers()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSync" "Xlib \- Output Buffer" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSync" .Na XSync \(en flush the request buffer and wait for all events and errors to be processed by the server. .Nz .SH "Synopsis" .Sy XSync\^(\^\f(CIdisplay\f(CW, \f(CIdiscard\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int \f(CIdiscard\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIdiscard\fP 1i Specifies whether \f(CWXSync()\fP discards all events on the input queue. This argument is either \f(CWTrue\fP or \f(CWFalse\fP. .SH Description \f(CWXSync()\fP flushes the request buffer, then waits until all events and errors resulting from previous calls have been received and processed by the X server. Events are placed on the input queue. The client's \f(CWXError\fP routine is called once for each error received. .LP If discard is \f(CWTrue\fP, \f(CWXSync()\fP discards all events on the input queue (including those events that were on the queue before \f(CWXSync()\fP was called). .LP \f(CWXSync()\fP is sometimes used with window manipulation functions (by the window manager) to wait for all resulting exposure events. Very few clients need to use this function. .SH "See Also" \s-1\fIXFlush()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XSynchronize" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XSynchronize" .XX "synchronization:enabling/disabling for debugging" .Na XSynchronize \(en enable or disable synchronization for debugging. .Nz .SH "Synopsis" .Sy int (*\f(CWXSynchronize(\f(CIdisplay, onoff\fP))()\fP .As Display *\f(CIdisplay\f(CW\^; Bool \f(CIonoff\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIonoff\fP 1i Specifies whether to enable or disable synchronization. You can pass \f(CWFalse\fP (normal asynchronous mode) or \f(CWTrue\fP (enable synchronization for debugging). .SH Returns The previous after function. .SH Description \f(CWXSynchronize()\fP turns on or off synchronous mode for debugging. If \f(CIonoff\fP is \f(CWTrue\fP, it turns on synchronous behavior; \f(CWFalse\fP resets the state to normal mode. .LP When events are synchronized, they are reported as they occur instead of at some later time, but server performance is many times slower. This can be useful for debugging complex event handling routines. Under UNIX, the same result can be achieved without hardcoding by setting the global variable \f(CW_Xdebug\fP to \f(CWTrue\fP from within a debugger. .LP \f(CWXSynchronize()\fP returns the previous after function. .LP For more information, see Volume One, Chapter 3, \fIBasic Window Program\fR. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXWindowEvent()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XTextExtents" "Xlib \- Text" .ds ]W Xlib Reference Manual .SH "Name" .XX "XTextExtents" .XX "text:string and font metrics;getting locally" .XX "font metrics:obtaining locally" .Na XTextExtents \(en get string and font metrics locally. .Nz .SH "Synopsis" .Sy XTextExtents\^(\^\f(CIfont_struct\f(CW\^, \f(CIstring\f(CW\^, \f(CInchars\f(CW\^, \f(CIdirection_return\f(CW, .ti +10n \f(CIfont_ascent_return\f(CW, \f(CIfont_descent_return\f(CW, \f(CIoverall_return\f(CW\^) .As XFontStruct *\f(CIfont_struct\f(CW\^; char *\f(CIstring\f(CW\^; int \f(CInchars\f(CW\^; int *\f(CIdirection_return\f(CW\^; int *\f(CIfont_ascent_return\f(CW, *\f(CIfont_descent_return\f(CW\^; XCharStruct *\f(CIoverall_return\f(CW\^; .LP .Ae .SH "Arguments" .IP \f(CIfont_struct\fP 1i Specifies a connection to an \f(CWXFontStruct\fP structure. .IP \f(CIstring\fP 1i Specifies the character string for which metrics are to be returned. .IP \f(CInchars\fP 1i Specifies the number of characters in the character string. .IP \f(CIdirection_return\fP 1i Returns the value of the direction element of the \f(CWXFontStruct\fP. Either \f(CWFontRightToLeft\fP or \f(CWFontLeftToRight\fP. .IP \f(CIfont_ascent_return\fP 1i Returns the font ascent element of the \f(CWXFontStruct\fP. This is the overall maximum ascent for the font. .IP \f(CIfont_descent_return\fP 1i Returns the font descent element of the \f(CWXFontStruct\fP. This is the overall maximum descent for the font. .IP \f(CIoverall_return\fP 1i .hw de-scent Returns the overall characteristics of the string. These are the sum of the \f(CWwidth\fP measurements for each character, the maximum \f(CWfont_ascent_return\fP and \f(CWfont_descent_return\fP, the minimum \f(CWlbearing\fP added to the width of all characters up to the character with the smallest \f(CWlbearing\fP, and the maximum \f(CWrbearing\fP added to the width of all characters up to the character with the largest \f(CWrbearing\fP. .SH Description \f(CWXTextExtents()\fP returns the dimensions in pixels that specify the bounding box of the specified string of characters in the named font, and the maximum ascent and descent for the entire font. This function performs the size computation locally and, thereby, avoids the roundtrip overhead of \f(CWXQueryTextExtents()\fP, but it requires a filled \f(CWXFontStruct\fP. .LP \f(CIfont_ascent_return\fP and \f(CIfont_descent_return\fP return information about the font, while \f(CIoverall_return\fP returns information about the given string. The returned \f(CIfont_ascent_return\fP and \f(CIfont_descent_return\fP should usually be used to calculate the line spacing, while the \f(CWwidth\fP, \f(CWrbearing\fP, and \f(CWlbearing\fP members of \f(CIoverall_return\fP should be used for horizontal measures. The total height of the bounding rectangle, good for any string in this font, is \s-1\f(CIfont_ascent_return\fP\^\f(CW+\fP\^\f(CIfont_descent_return\fP\s+1. .LP \f(CIoverall_return.ascent\fP is the maximum of the ascent metrics of all characters in the string. The \f(CIoverall_return.descent\fP is the maximum of the descent metrics. The \f(CIoverall_return.width\fP is the sum of the character-width metrics of all characters in the string. The \f(CIoverall_return.lbearing\fP is the \f(CWlbearing\fP of the character in the string with the smallest \f(CWlbearing\fP plus the width of all the characters up to but not including that character. The \f(CIoverall_return.rbearing\fP is the \f(CWrbearing\fP of the character in the string with the largest \f(CWrbearing\fP plus the width of all the characters up to but not including that character. If the font has no defined default character, undefined characters in the string are taken to have all zero metrics. .LP For more information on drawing text, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" .Ps .ta 4.5n 2.12i typedef struct { XExtData *ext_data; /* hook for extension to hang data */ Font fid; /* font ID for this font */ unsigned direction; /* hint about direction the font is painted */ unsigned min_char_or_byte2; /* first character */ unsigned max_char_or_byte2; /* last character */ unsigned min_byte1; /* first row that exists */ unsigned max_byte1; /* last row that exists */ Bool all_chars_exist; /* flag if all characters have non-zero size */ unsigned default_char; /* char to print for undefined character */ int n_properties; /* how many properties there are */ XFontProp *properties; /* pointer to array of additional properties */ XCharStruct min_bounds; /* minimum bounds over all existing char */ XCharStruct max_bounds; /* maximum bounds over all existing char */ XCharStruct *per_char; /* first_char to last_char information */ int ascent; /* logical extent above baseline for spacing */ int descent; /* logical descent below baseline for spacing */ } XFontStruct; typedef struct { short lbearing; /* origin to left edge of character */ short rbearing; /* origin to right edge of character */ short width; /* advance to next char's origin */ short ascent; /* baseline to top edge of character */ short descent; /* baseline to bottom edge of character */ unsigned short attributes; /* per char flags (not predefined) */ } XCharStruct; .Pe .ne 6 .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawImageString16()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawString16()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXDrawText16()\fP\s+1, \s-1\fIXQueryTextExtents()\fP\s+1, \s-1\fIXQueryTextExtents16()\fP\s+1, \s-1\fIXTextExtents16()\fP\s+1, \s-1\fIXTextWidth()\fP\s+1, \s-1\fIXTextWidth16()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XTextExtents16" "Xlib \- Text" .ds ]W Xlib Reference Manual .SH "Name" .XX "XTextExtents16" .XX "text:16-bit characters" .Na XTextExtents16 \(en get string and font metrics of a 16-bit character string, locally. .Nz .SH "Synopsis" .Sy XTextExtents16\^(\^\f(CIfont_struct\f(CW\^, \f(CIstring\f(CW\^, \f(CInchars\f(CW\^, \f(CIdirection_return\f(CW, \f(CIfont_ascent_return\f(CW, \f(CIfont_descent_return\f(CW, \f(CIoverall_return\f(CW\^) .As XFontStruct *\f(CIfont_struct\f(CW\^; XChar2b *\f(CIstring\f(CW\^; int \f(CInchars\f(CW\^; int *\f(CIdirection_return\f(CW\^; int *\f(CIfont_ascent_return\f(CW, *\f(CIfont_descent_return\f(CW\^; XCharStruct *\f(CIoverall_return\f(CW\^; .LP .Ae .SH "Arguments" .IP \f(CIfont_struct\fP 1i Specifies an \f(CWXFontStruct\fP structure. .IP \f(CIstring\fP 1i Specifies the character string made up of \f(CWXChar2b\fP structures. .IP \f(CInchars\fP 1i Specifies the number of characters in the character string. .IP \f(CIdirection_return\fP 1i Returns the value of the direction element of the \f(CWXFontStruct\fP. \f(CWFontRightToLeft\fP of \f(CWFontLeftToRight\fP. .IP \f(CIfont_ascent_return\fP 1i Returns the font ascent element of the \f(CWXFontStruct\fP. This is the overall maximum ascent for the font. .IP \f(CIfont_descent_return\fP 1i .hw de-scent Returns the font descent element of the \f(CWXFontStruct\fP. This is the overall maximum descent for the font. .IP \f(CIoverall_return\fP 1i Returns the overall characteristics of the string. These are the sum of the \f(CWwidth\fP measurements for each character, the maximum \f(CWfont_ascent_return\fP and \f(CWfont_descent_return\fP, the minimum \f(CWlbearing\fP added to the width of all characters up to the character with the smallest \f(CWlbearing\fP, and the maximum \f(CWrbearing\fP added to the width of all characters up to the character with the largest \f(CWrbearing\fP. .SH Description \f(CWXTextExtents16()\fP returns the dimensions in pixels that specify the bounding box of the specified string of characters in the named font, and the maximum ascent and descent for the entire font. This function performs the size computation locally and, thereby, avoids the roundtrip overhead of \f(CWXQueryTextExtents16()\fP, but it requires a filled \f(CWXFontStruct\fP. .LP \f(CIfont_ascent_return\fP and \f(CIfont_descent_return\fP return information about the font, while \f(CIoverall_return\fP returns information about the given string. The returned \f(CIfont_ascent_return\fP and \f(CIfont_descent_return\fP should usually be used to calculate the line spacing, while the \f(CWwidth\fP, \f(CWrbearing\fP, and \f(CWlbearing\fP members of \f(CIoverall_return\fP should be used for horizontal measures. The total height of the bounding rectangle, good for .hw descent any string in this font, is \s-1\f(CIfont_ascent_return\fP\^\f(CW+\fP\^\f(CIfont_descent_return\fP\s+1. .LP \f(CIoverall_return.ascent\fP is the maximum of the ascent metrics of all characters in the string. The \f(CIoverall_return.descent\fP is the maximum of the descent metrics. The \f(CIoverall_return.width\fP is the sum of the character-width metrics of all characters in the string. The \f(CIoverall_return.lbearing\fP is the \f(CWlbearing\fP of the character in the string with the smallest \f(CWlbearing\fP plus the width of all the characters up to but not including that character. The \f(CIoverall_return.rbearing\fP is the \f(CWrbearing\fP of the character in the string with the largest \f(CWrbearing\fP plus the width of all the characters up to but not including that character. .LP For fonts defined with linear indexing rather than 2-byte matrix indexing, each \f(CWXChar2b\fP structure is interpretd as a 16-bit number with byte1 as the most-significant byte. If the font has no defined default character, undefined characters in the string are taken to have all zero metrics. For more information on drawing text, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" .Ps .ta 4.5n 2.12i typedef struct { short lbearing; /* origin to left edge of character */ short rbearing; /* origin to right edge of character */ short width; /* advance to next char's origin */ short ascent; /* baseline to top edge of character */ short descent; /* baseline to bottom edge of character */ unsigned short attributes; /* per char flags (not predefined) */ } XCharStruct; .ne 10 typedef struct { XExtData *ext_data; /* hook for extension to hang data */ Font fid; /* font ID for this font */ unsigned direction; /* hint about direction the font is painted */ unsigned min_char_or_byte2; /* first character */ unsigned max_char_or_byte2; /* last character */ unsigned min_byte1; /* first row that exists */ unsigned max_byte1; /* last row that exists */ Bool all_chars_exist; /* flag if all characters have non-zero size*/ unsigned default_char; /* char to print for undefined character */ int n_properties; /* how many properties there are */ XFontProp *properties; /* pointer to array of additional properties*/ XCharStruct min_bounds; /* minimum bounds over all existing char*/ XCharStruct max_bounds; /* maximum bounds over all existing char*/ XCharStruct *per_char; /* first_char to last_char information */ int ascent; /* logical extent above baseline for spacing */ int descent; /* logical descent below baseline for spacing */ } XFontStruct; typedef struct { /* normal 16 bit characters are two bytes */ unsigned char byte1; unsigned char byte2; } XChar2b; .Pe .KS .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawImageString16()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawString16()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXDrawText16()\fP\s+1, \s-1\fIXQueryTextExtents()\fP\s+1, \s-1\fIXQueryTextExtents16()\fP\s+1, \s-1\fIXTextExtents()\fP\s+1, \s-1\fIXTextWidth()\fP\s+1, \s-1\fIXTextWidth16()\fP\s+1. .\"last line comment .TH XTextExtent.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XTextExtents@XTextExtenA .sp .5 XTextExtents16@XTextExtenB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "\s-2XTextPropertyToStringList\s+2" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XTextPropertyToStringList" .XX "XTextProperty structure:obtaining list of strings from" .XX "string lists:obtaining from an XTextProperty structure" .Na XTextPropertyToStringList \(en get a list of strings from a specified \f(CWXTextProperty\fP structure. .Nz .SH "Synopsis" .Sy Status XTextPropertyToStringList\^(\^\f(CItext_prop\fP\^, \f(CIlist_return\fP\^, \ \f(CIcount_return\fP\^) .As XTextProperty *\f(CItext_prop\fP\^; char ***\f(CIlist_return\fP\^; int *\f(CIcount_return\fP\^; .Ae .SH "Arguments" .IP \f(CItext_prop\fP 1.4i Specifies the \f(CWXTextProperty\fR structure to be used. .IP \f(CIlist_return\fP Returns a list of \f(CWNULL\fP-terminated character strings. .ds Cn strings .IP \f(CIcount_return\fP Returns the number of \*(Cn. .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description .LP \f(CWXTextPropertyToStringList()\fR returns a list of strings representing the null-separated elements of the specified \f(CWXTextProperty\fR structure. The data in \f(CWtext_prop\fP must be of type STRING and format 8. Multiple elements of the property (for example, the strings in a disjoint text selection) are separated by a \f(CWNULL\fP (encoding 0). The contents of the property are not \f(CWNULL\fP-terminated. If insufficient memory is available for the list and its elements, \f(CWXTextPropertyToStringList()\fR sets no return values and returns a zero status. Otherwise, it returns a non-zero status. To free the storage for the list and its contents, use \f(CWXFreeStringList()\fR. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .Ps typedef struct { unsigned char *value; /* same as Property routines */ Atom encoding; /* prop type */ int format; /* prop data format: 8, 16, or 32 */ unsigned long nitems; /* number of data items in value */ } XTextProperty; .Pe .sp -3p .SH "See Also" \s-1\fIXFreeStringList()\fP\s+1, \s-1\fIXGetTextProperty()\fP\s+1, \s-1\fIXSetTextProperty()\fP\s+1, \s-1\fIXStringListToTextProperty()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XTextWidth" "Xlib \- Text" .ds ]W Xlib Reference Manual .SH "Name" .XX "XTextWidth" .XX "text:width, obtaining" .Na XTextWidth \(en get the width in pixels of an 8-bit character string, locally. .Nz .SH "Synopsis" .Sy int XTextWidth\^(\^\f(CIfont_struct\f(CW\^, \f(CIstring\f(CW, \f(CIcount\f(CW\^) .As XFontStruct *\f(CIfont_struct\f(CW\^; char *\f(CIstring\f(CW\^; int \f(CIcount\f(CW\^; .Ae .SH "Arguments" .IP \f(CIfont_struct\fP 1i Specifies the font description structure of the font in which you want to draw the string. .IP \f(CIstring\fP 1i Specifies the character string whose width is to be returned. .IP \f(CIcount\fP 1i Specifies the character count in \f(CIstring\fP. .SH Returns The width in pixels. .SH Description \f(CWXTextWidth()\fP returns the width in pixels of the specified string using the specified font. This is the sum of the \f(CWXCharStruct.width\fR for each character in the string. This is also equivalent to the value of \f(CIoverall.width\fR returned by \f(CWXQueryTextExtents()\fP or \f(CWXTextExtents()\fP. The calculation is done assuming 8-bit font indexing. .LP For more information on drawing text, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" .Ps .ta 4.5n 2.12i typedef struct { XExtData *ext_data; /* hook for extension to hang data */ Font fid; /* font ID for this font */ unsigned direction; /* hint about direction the font is painted */ unsigned min_char_or_byte2; /* first character */ unsigned max_char_or_byte2; /* last character */ unsigned min_byte1; /* first row that exists */ unsigned max_byte1; /* last row that exists */ Bool all_chars_exist; /* flag if all characters have non-zero size*/ unsigned default_char; /* char to print for undefined character */ int n_properties; /* how many properties there are */ XFontProp *properties; /* pointer to array of additional properties*/ XCharStruct min_bounds; /* minimum bounds over all existing char*/ XCharStruct max_bounds; /* maximum bounds over all existing char*/ XCharStruct *per_char; /* first_char to last_char information */ .ne 8 int ascent; /* logical extent above baseline for spacing */ int descent; /* logical descent below baseline for spacing */ } XFontStruct; .XX "XFontStruct structure" .XX "structures:XFontStruct" .Pe .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawImageString16()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawString16()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXDrawText16()\fP\s+1, \s-1\fIXQueryTextExtents()\fP\s+1, \s-1\fIXQueryTextExtents16()\fP\s+1, \s-1\fIXTextExtents()\fP\s+1, \s-1\fIXTextExtents16()\fP\s+1, \s-1\fIXTextWidth16()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XTextWidth16" "Xlib \- Text" .ds ]W Xlib Reference Manual .SH "Name" .XX "XTextWidth16" .XX "text:16-bit characters" .Na XTextWidth16 \(en get the width in pixels of a 16-bit character string, locally. .Nz .SH "Synopsis" .Sy int XTextWidth16\^(\^\f(CIfont_struct\f(CW\^, \f(CIstring\f(CW, \f(CIcount\f(CW\^) .As XFontStruct *\f(CIfont_struct\f(CW\^; XChar2b *\f(CIstring\f(CW\^; int \f(CIcount\f(CW\^; .Ae .SH "Arguments" .IP \f(CIfont_struct\fP 1i Specifies the font description structure of the font in which you want to draw the string. .IP \f(CIstring\fP 1i Specifies a character string made up of \f(CWXChar2b\fP structures. .IP \f(CIcount\fP 1i Specifies the character count in \f(CIstring\fP. .SH Returns The width in pixels. .SH Description \f(CWXTextWidth16()\fP returns the width in pixels of the specified string using the specified font. This is the sum of the \f(CWXCharStruct.width\fR for each character in the string. This is also equivalent to the value of \f(CIoverall.width\fR returned by \f(CWXQueryTextExtents16()\fP or \f(CWXTextExtents16()\fP. .LP The calculation is done assuming 16-bit font indexing. .LP .EL For more information on drawing text, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" .Ps .ta 4.5n 2.15i typedef struct { XExtData *ext_data; /* hook for extension to hang data */ Font fid; /* font ID for this font */ unsigned direction; /* hint about direction the font is painted */ unsigned min_char_or_byte2; /* first character */ unsigned max_char_or_byte2; /* last character */ unsigned min_byte1; /* first row that exists */ unsigned max_byte1; /* last row that exists */ Bool all_chars_exist; /* flag if all characters have non-zero size */ unsigned default_char; /* char to print for undefined character */ int n_properties; /* how many properties there are */ XFontProp *properties; /* pointer to array of additional properties*/ XCharStruct min_bounds; /* minimum bounds over all existing char*/ XCharStruct max_bounds; /* maximum bounds over all existing char*/ XCharStruct *per_char; /* first_char to last_char information */ int ascent; /* logical extent above baseline for spacing */ int descent; /* logical descent below baseline for spacing */ } XFontStruct; .Pe .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawImageString16()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawString16()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXDrawText16()\fP\s+1, \s-1\fIXQueryTextExtents()\fP\s+1, \s-1\fIXQueryTextExtents16()\fP\s+1, \s-1\fIXTextExtents()\fP\s+1, \s-1\fIXTextExtents16()\fP\s+1, \s-1\fIXTextWidth()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XTranslateCoordinates" "Xlib \- Standard Geometry" .ds ]W Xlib Reference Manual .SH "Name" .XX "XTranslateCoordinates" .Na XTranslateCoordinates \(en change the coordinate system from one window to another. .Nz .SH "Synopsis" .Sy Bool XTranslateCoordinates\^(\^\f(CIdisplay\f(CW, \f(CIsrc_w\f(CW\^, \f(CIdest_w\f(CW\^, \f(CIsrc_x\f(CW\^, \f(CIsrc_y\f(CW\^, \f(CIdest_x_return\f(CW\^, \f(CIdest_y_return\f(CW\^, \f(CIchild_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIsrc_w\f(CW\^, \f(CIdest_w\f(CW\^; int \f(CIsrc_x\f(CW\^, \f(CIsrc_y\f(CW\^; int *\f(CIdest_x_return\f(CW\^, *\f(CIdest_y_return\f(CW\^; Window *\f(CIchild_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.25i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIsrc_w\fP Specifies the ID of the source window. .IP \f(CIdest_w\fP Specifies the ID of the frame of reference window. .IP \f(CIsrc_x\fP .br .ns .sp .5 .IP \f(CIsrc_y\fP .sp -2 Specify the x and y coordinates within the source window. .sp .IP \f(CIdest_x_return\fP .br .ns .IP \f(CIdest_y_return\fP .sp -2 Return the translated x and y coordinates within the frame of reference window. .sp .5 .IP \f(CIchild\fP If the point is contained in a mapped child of the destination window, then that child ID is returned in \f(CIchild\fP. .SH Returns \f(CWTrue\fP if the two windows are on the same screen, else \f(CWFalse\fP. .SH Description .XX "coordinates:translating" \f(CWXTranslateCoordinates()\fP translates coordinates from the frame of reference of one window to another. .LP \f(CWXTranslateCoordinates()\fP returns \f(CWFalse\fP and \f(CI*dest_x_return\fP and \f(CI*dest_y_return\fP are set to zero if \f(CIsrc_w\fP and \f(CIdest_w\fP are on different screens. In addition, if the coordinates are contained in a mapped child of \f(CIdest_w\fP, then that child is returned in the \f(CIchild_return\fP argument. When \f(CWsrc_w\fP and \f(CWframe_y\fP are on the same screen, \f(CWXTranslateCoordinates()\fP returns \f(CWTrue\fR, sets *\f(CIdest_x_return\fP and *\f(CIdest_y_return\fP to the location of the point relative to \f(CIdest_w\fP, and sets \f(CIchild_return\fP to \f(CWNone\fP. .LP This function should be avoided in most applications since it requires a roundtrip request to the server. Most applications benefit from the window-based coordinate system anyway and don't need global coordinates. Window managers often need to perform a coordinate transformation from the coordinate space of one window to another, or unambiguously determine which subwindow a coordinate lies in. \f(CWXTranslateCoordinates()\fP fulfills this need, while avoiding any race conditions by asking the server to perform this operation. .LP .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXGeometry\fP\s+1, \s-1\fIXParseGeometry()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XUndefineCursor" "Xlib \- Cursors" .ds ]W Xlib Reference Manual .SH "Name" .XX "XUndefineCursor" .XX "cursors:disassociating from windows" .Na XUndefineCursor \(en disassociate a cursor from a window. .Nz .SH "Synopsis" .Sy XUndefineCursor\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window whose cursor is to be undefined. .SH Description \f(CWXUndefineCursor()\fP sets the cursor attribute for a window to its parent's cursor, undoing the effect of a previous \f(CWXDefineCursor()\fP for this window. On the root window the default cursor is restored. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXCreateGlyphCursor()\fP\s+1, \s-1\fIXCreatePixmapCursor()\fP\s+1, \s-1\fIXDefineCursor()\fP\s+1, \s-1\fIXFreeCursor()\fP\s+1, \s-1\fIXQueryBestCursor()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXRecolorCursor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XUngrabButton" "Xlib \- Grabbing" .ds ]W Xlib Reference Manual .SH "Name" .XX "XUngrabButton" .XX "buttons:releasing from passive grabs" .Na XUngrabButton \(en release a button from a passive grab. .Nz .SH "Synopsis" .Sy XUngrabButton\^(\^\f(CIdisplay\f(CW, \f(CIbutton\f(CW\^, \f(CImodifiers\f(CW\^, \f(CIgrab_window\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; unsigned int \f(CIbutton\f(CW\^; unsigned int \f(CImodifiers\f(CW\^; Window \f(CIgrab_window\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIbutton\fP 1i Specifies the mouse button to be released from grab. Specify \&\f(CWButton1\fP, \&\f(CWButton2\fP, \&\f(CWButton3\fP, \&\f(CWButton4\fP, \&\f(CWButton5\fP, or the constant \f(CWAnyButton\fP, which is equivalent to issuing the ungrab request for all possible buttons. .IP \f(CImodifiers\fP 1i Specifies a set of keymasks. This is a bitwise OR of one or more of the following symbols: \f(CWShiftMask\fP, \f(CWLockMask\fP, \f(CWControlMask\fP, \f(CWMod1Mask\fP, \f(CWMod2Mask\fP, \f(CWMod3Mask\fP, \f(CWMod4Mask\fP, \f(CWMod5Mask\fP, or \f(CWAnyModifier\fP. \f(CWAnyModifier\fP is equivalent to issuing the ungrab button request for all possible modifier combinations (including no modifiers). .IP \f(CIgrab_window\fP 1i Specifies the ID of the window you want to release the button grab. .SH Description \f(CWXUngrabButton()\fP cancels the passive grab on a button/key combination on the specified window if it was grabbed by this client. A \f(CImodifiers\fP of \f(CWAnyModifier\fP is equivalent to issuing the ungrab request for all possible modifier combinations (including the combination of no modifiers). A \f(CIbutton\fP of \f(CWAnyButton\fP is equivalent to issuing the request for all possible buttons. This call has no effect on an active grab. .LP For more information, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "Errors" .IP "\f(CWBadWindow\fP" 1i .br .ns .IP "\f(CWBadValue\fP" .sp -1.5 Invalid \f(CIbutton\fP or \f(CImodifiers\fP mask. .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXGrabButton()\fP\s+1, \s-1\fIXGrabKey()\fP\s+1, \s-1\fIXGrabKeyboard()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXGrabServer()\fP\s+1, \s-1\fIXUngrabKey()\fP\s+1, \s-1\fIXUngrabKeyboard()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1, \s-1\fIXUngrabServer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XUngrabKey" "Xlib \- Grabbing" .ds ]W Xlib Reference Manual .SH "Name" .XX "XUngrabKey" .XX "keys:releasing from passive grabs" .Na XUngrabKey \(en release a key from a passive grab. .Nz .SH "Synopsis" .Sy XUngrabKey\^(\^\f(CIdisplay\f(CW, \f(CIkeycode\f(CW\^, \f(CImodifiers\f(CW\^, \f(CIgrab_window\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; int \f(CIkeycode\f(CW\^; unsigned int \f(CImodifiers\f(CW\^; Window \f(CIgrab_window\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIkeycode\fP 1i Specifies the keycode. This keycode maps to the specific key you want to ungrab. Pass either a keycode or \f(CWAnyKey\fP. .IP \f(CImodifiers\fP 1i Specifies a set of keymasks. This is a bitwise OR of one or more of the following symbols: \f(CWShiftMask\fP, \f(CWLockMask\fP, \f(CWControlMask\fP, \f(CWMod1Mask\fP, \f(CWMod2Mask\fP, \f(CWMod3Mask\fP, \f(CWMod4Mask\fP, \f(CWMod5Mask\fP, or \f(CWAnyModifier\fP. \f(CWAnyModifier\fP is equivalent to issuing the ungrab key request for all possible modifier combinations (including no modifiers). .IP \f(CIgrab_window\fP 1i Specifies the ID of the window for which you want to ungrab the specified keys. .SH Description \f(CWXUngrabKey()\fP cancels the passive grab on the key combination on the specified window if it was grabbed by this client. A \f(CImodifiers\fP of \f(CWAnyModifier\fP is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). A \f(CIkeycode\fP of \f(CWAnyKey\fP is equivalent to issuing the request for all possible nonmodifier key codes. This call has no effect on an active grab. .LP For more information, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "Errors" .IP "\f(CWBadWindow\fP" 1i .br .ns .IP "\f(CWBadValue\fP" .sp -1.5 Invalid \f(CIkeycode\fP or \f(CImodifiers\fP mask. .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXGrabButton()\fP\s+1, \s-1\fIXGrabKey()\fP\s+1, \s-1\fIXGrabKeyboard()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXGrabServer()\fP\s+1, \s-1\fIXUngrabButton()\fP\s+1, \s-1\fIXUngrabKeyboard()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1, \s-1\fIXUngrabServer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XUngrabKeyboard" "Xlib \- Grabbing" .ds ]W Xlib Reference Manual .SH "Name" .XX "XUngrabKeyboard" .XX "keyboard:releasing from active grabs" .Na XUngrabKeyboard \(en release the keyboard from an active grab. .Nz .SH "Synopsis" .Sy XUngrabKeyboard\^(\^\f(CIdisplay\f(CW, \f(CItime\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Time \f(CItime\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CItime\fP 1i Specifies the time. Pass either a timestamp, expressed in milliseconds, or the constant \f(CWCurrentTime\fP. If this time is earlier than the last-keyboard-grab time or later than the current server time, the keyboard will not be ungrabbed. .SH Description \f(CWXUngrabKeyboard()\fP releases any active grab on the keyboard by this client. It executes as follows: .IP \(bu 3n Releases the keyboard and any queued events if this client has it actively grabbed from either \f(CWXGrabKeyboard()\fP or \f(CWXGrabKey()\fP. .IP \(bu 3n Does not release the keyboard and any queued events if \f(CItime\fP is earlier than the last-keyboard-grab time or is later than the current X server time. .IP \(bu 3n Generates \f(CWFocusIn\fP and \f(CWFocusOut\fP events. .LP The X server automatically performs an \f(CWUngrabKeyboard\fP if the \f(CIgrab_window\fP (argument to \f(CWXGrabKey()\fP and \f(CWXGrabKeyboard()\fP) becomes unviewable. .LP For more information, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXGrabButton()\fP\s+1, \s-1\fIXGrabKey()\fP\s+1, \s-1\fIXGrabKeyboard()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXGrabServer()\fP\s+1, \s-1\fIXUngrabButton()\fP\s+1, \s-1\fIXUngrabKey()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1, \s-1\fIXUngrabServer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XUngrabPointer" "Xlib \- Pointer" .ds ]W Xlib Reference Manual .SH "Name" .XX "XUngrabPointer" .XX "pointers:releasing from active grabs" .Na XUngrabPointer \(en release the pointer from an active grab. .Nz .SH "Synopsis" .Sy XUngrabPointer\^(\^\f(CIdisplay\f(CW, \f(CItime\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Time \f(CItime\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CItime\fP 1i Specifies the time when the grab should take place. Pass either a timestamp, expressed in milliseconds, or the constant \f(CWCurrentTime\fP. If this time is earlier than the last-pointer-grab time or later than current server time, the pointer will not be grabbed. .SH Description \f(CWXUngrabPointer()\fP releases an active grab on the pointer by the calling client. It executes as follows: .IP \(bu 3n Releases the pointer and any queued events, if this client has actively grabbed the pointer from \f(CWXGrabPointer()\fP, \f(CWXGrabButton()\fP, or from a normal button press. .IP \(bu 3n Does not release the pointer if the specified time is earlier than the last-pointer-grab time or is later than the current X server time. .IP \(bu 3n Generates \f(CWEnterNotify\fP and \f(CWLeaveNotify\fP events. .LP The X server performs an \f(CWXUngrabPointer()\fP .hw confine automatically if the \f(CIevent_window\fP or \f(CIconfine_to\fP window (arguments of \f(CWXGrabButton()\fP and \f(CWXGrabPointer()\fP) becomes not viewable, or if the \f(CWconfine_to\fP window is moved completely outside the root window. .LP For more information, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXChangePointerControl()\fP\s+1, \s-1\fIXGetPointerControl()\fP\s+1, \s-1\fIXGetPointerMapping()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXQueryPointer()\fP\s+1, \s-1\fIXSetPointerMapping()\fP\s+1, \s-1\fIXWarpPointer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XUngrabServer" "Xlib \- Grabbing" .ds ]W Xlib Reference Manual .SH "Name" .XX "XUngrabServer" .XX "servers:releasing from grabs" .Na XUngrabServer \(en release the server from grab. .Nz .SH "Synopsis" .Sy XUngrabServer\^(\^\f(CIdisplay\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .SH Description \f(CWXUngrabServer()\fP releases the grabbed server, and begins execution of all the requests queued during the grab. \f(CWXUngrabServer()\fP is called automatically when a client closes its connection. .LP For more information, see Volume One, Chapter 9, \fIThe Keyboard and Pointer\fR. .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXGrabButton()\fP\s+1, \s-1\fIXGrabKey()\fP\s+1, \s-1\fIXGrabKeyboard()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXGrabServer()\fP\s+1, \s-1\fIXUngrabButton()\fP\s+1, \s-1\fIXUngrabKey()\fP\s+1, \s-1\fIXUngrabKeyboard()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XUninstallColormap" "Xlib \- Colormaps" .ds ]W Xlib Reference Manual .SH "Name" .XX "XUninstallColormap" .XX "colormaps:uninstalling" .Na XUninstallColormap \(en uninstall a colormap; install default if not already installed. .Nz .SH "Synopsis" .Sy XUninstallColormap\^(\^\f(CIdisplay\f(CW, \f(CIcolormap\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Colormap \f(CIcolormap\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIcolormap\fP 1i Specifies the colormap to be uninstalled. .SH Description If \f(CIcolormap\fP is an installed map for its screen, it is uninstalled. If the screen's default colormap is not installed, it is installed. .LP If \f(CIcolormap\fP is an installed map, a \f(CWColormapNotify\fP event is generated on every window having this colormap as an attribute. If a colormap is installed as a result of the uninstall, a \f(CWColormapNotify\fP event is generated on every window having that colormap as an attribute. .LP At any time, there is a subset of the installed colormaps, viewed as an ordered list, called the \fIrequired list\fP. The length of the required list is at most the \f(CWmin_maps\fP specified for each screen in the \f(CWDisplay\fP structure. When a colormap is installed with \f(CWXInstallColormap()\fP it is added to the head of the required list and the last colormap in the list is removed if necessary to keep the length of the list at \f(CWmin_maps\fP. When a colormap is uninstalled with \f(CWXUninstallColormap()\fP and it is in the required list, it is removed from the list. No other actions by the server or the client change the required list. It is important to realize that on all but high-performance workstations, \f(CWmin_maps\fP is likely to be one. .LP For more information on installing and uninstalling colormaps, see Volume One, Chapter 7, \fIColor\fR. .SH "Errors" .IP "\f(CWBadColor\fP" 1i Invalid colormap. .SH "See Also" \s-1\fIXDefaultColormap()\fP\s+1, \s-1\fIXDisplayCells()\fP\s+1, \s-1\fIXCopyColormapAndFree()\fP\s+1, \s-1\fIXCreateColormap()\fP\s+1, \s-1\fIXFreeColormap()\fP\s+1, \s-1\fIXGetStandardColormap()\fP\s+1, \s-1\fIXInstallColormap()\fP\s+1, \s-1\fIXListInstalledColormaps()\fP\s+1, \s-1\fIXSetStandardColormap()\fP\s+1, \s-1\fIXSetWindowColormap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XUnionRectWithRegion" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XUnionRectWithRegion" .XX "rectangles:and regions;adding to" .XX "regions:adding rectangles to" .Na XUnionRectWithRegion \(en add a rectangle to a region. .Nz .SH "Synopsis" .Sy XUnionRectWithRegion\^(\^\f(CIrectangle\fP, \f(CIsrc_region\fP, \f(CIdest_region_return\fP\^) .As XRectangle *\f(CIrectangle\fP\^; Region \f(CIsrc_region\fP\^; Region \f(CIdest_region_return\fP\^; .Ae .SH "Arguments" .IP \f(CIrectangle\fP 1i Specifies the rectangle to add to the region. .IP \f(CIsrc_region\fP 1i Specifies the source region to be used. .IP \f(CIdest_region_return\fP 1i Specifies the resulting region. May be the same as \f(CIsrc_region\fP. .SH Description \f(CWXUnionRectWithRegion()\fP computes the destination region from a union of the specified rectangle and the specified source region. The source and destination regions may be the same. .LP One common application of this function is to simplify the combining of the rectangles specified in contiguous \f(CWExpose\fP events into a \f(CWclip_mask\fP in the GC, thus restricting the redrawn areas to the exposed rectangles. Use \f(CWXUnionRectWithRegion()\fP to combine the rectangle in each \f(CWExpose\fP event into a region, then call \f(CWXSetRegion()\fP. \f(CWXSetRegion()\fP sets the \f(CWclip_mask\fP in a GC to the region. In this case, \f(CIsrc_region\fP and \f(CIdest_region_return\fP would be the same region. .LP If \f(CIsrc_region\fP and \f(CIdest_region_return\fP are not the same region, \f(CIsrc_region\fP is copied to \f(CIdest_region_return\fP before the rectangle is added to \f(CIdest_region_return\fP. .LP For more information on regions, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" .Ps typedef struct { short x, y; unsigned short width, height; } XRectangle; .XX "XRectangle structure" .XX "structures:XRectangle" .Pe .sp .5 \&\f(CWRegion\fP is a pointer to an opaque data type. .Nd 5 .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XUnionRegion" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XUnionRegion" .XX "regions:computing union of" .Na XUnionRegion \(en compute the union of two regions. .Nz .SH "Synopsis" .Sy XUnionRegion\^(\^\f(CIsra\f(CW\^, \f(CIsrb\f(CW\^, \f(CIdr_return\f(CW\^) .As Region \f(CIsra\f(CW\^, \f(CIsrb\f(CW\^; Region \f(CIdr_return\fP; .Ae .SH "Arguments" .IP \f(CIsra\fP 1i .br .ns .IP \f(CIsrb\fP 1i .sp -2 Specify the two regions in which you want to perform the computation. .sp .5 .IP \f(CIdr_return\fP 1i Returns the result of the computation. .SH Description \f(CWXUnionRegion()\fP computes the union of two regions and places the result in \f(CIdr_return\fP. The resulting region will contain all the area of both the source regions. .LP For more information on regions, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" \f(CWRegion\fP is a pointer to an opaque structure type. .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXCreateRegion()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXXorRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XUniqueContext" "Xlib \- Context Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XUniqueContext" .XX "context ID:creating" .Na XUniqueContext \(en create a new context ID (not graphics context). .Nz .SH "Synopsis" .Sy XContext XUniqueContext(\^) .SH Returns The context ID. .SH Description The context manager allows association of arbitrary data with a resource ID. This call creates a unique ID that can be used in subsequent calls to \f(CWXFindContext()\fP, \f(CWXDeleteContext()\fP, and \f(CWXSaveContext()\fP. .LP For more information on the context manager, see Volume One, Chapter 15, \fIOther Programming Techniques\fR. .SH Structures .Ps typedef int XContext; .Pe .SH "See Also" \s-1\fIXDeleteContext()\fP\s+1, \s-1\fIXFindContext()\fP\s+1, \s-1\fIXSaveContext()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XUnloadFont" "Xlib \- Fonts" .ds ]W Xlib Reference Manual .SH "Name" .XX "XUnloadFont" .XX "fonts:unloading" .Na XUnloadFont \(en unload a font. .Nz .SH "Synopsis" .Sy XUnloadFont\^(\^\f(CIdisplay\f(CW, \f(CIfont\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Font \f(CIfont\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIfont\fP 1i Specifies the ID of the font to be unloaded. .SH Description \f(CWXUnloadFont()\fP indicates to the server that this client no longer needs the specified font. The font may be unloaded on the X server if this is the last client that needs the font. In any case, the font should never again be referenced by this client because Xlib destroys the resource ID. .LP For more information on loading and unloading fonts, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Errors" \f(CWBadFont\fP .SH "See Also" \s-1\fIXCreateFontCursor()\fP\s+1, \s-1\fIXFreeFont()\fP\s+1, \s-1\fIXFreeFontInfo()\fP\s+1, \s-1\fIXFreeFontNames()\fP\s+1, \s-1\fIXFreeFontPath()\fP\s+1, \s-1\fIXGetFontPath()\fP\s+1, \s-1\fIXGetFontProperty()\fP\s+1, \s-1\fIXListFonts()\fP\s+1, \s-1\fIXListFontsWithInfo()\fP\s+1, \s-1\fIXLoadFont()\fP\s+1, \s-1\fIXLoadQueryFont()\fP\s+1, \s-1\fIXQueryFont()\fP\s+1, \s-1\fIXSetFont()\fP\s+1, \s-1\fIXSetFontPath()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XUnmapSubwindows" "Xlib \- Mapping" .ds ]W Xlib Reference Manual .SH "Name" .XX "XUnmapSubwindows" .XX "subwindows:unmapping" .XX "windows:unmapping subwindows of" .Na XUnmapSubwindows \(en unmap all subwindows of a given window. .Nz .SH "Synopsis" .Sy XUnmapSubwindows\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window whose subwindows are to be unmapped. .SH Description \f(CWXUnmapSubwindows()\fP performs an \f(CWXUnmapWindow()\fP on all mapped children of \f(CIw\fP, in bottom to top stacking order. (It does not unmap subwindows of subwindows.) .LP \f(CWXUnmapSubwindows()\fP also generates an \f(CWUnmapNotify\fP event on each subwindow and generates exposure events on formerly obscured windows. This function is much more efficient than unmapping many subwindows one at a time, since much of the work need only be performed once for all of the subwindows rather than for each subwindow. .LP For more information on window mapping, see Volume One, Chapter 2, \fIX Concepts\fP. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXMapRaised()\fP\s+1, \s-1\fIXMapSubwindows()\fP\s+1, \s-1\fIXMapWindow()\fP\s+1, \s-1\fIXUnmapWindow()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XUnmapWindow" "Xlib \- Mapping" .ds ]W Xlib Reference Manual .SH "Name" .XX "windows:unmapping" .XX "XUnmapWindow" .Na XUnmapWindow \(en unmap a window. .Nz .SH "Synopsis" .Sy XUnmapWindow\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the window ID. .SH Description \f(CWXUnmapWindow()\fP removes \f(CIw\fP and all its descendants from the screen (but does not unmap the descendents). If \f(CIw\fP is already unmapped, \f(CWXUnmapWindow()\fP has no effect. Otherwise, \f(CIw\fP is unmapped and an \f(CWUnmapNotify\fP event is generated. Normal exposure processing on formerly obscured windows is performed. .LP Descendants of \f(CIw\fP will not be visible until \f(CIw\fP is mapped again. In other words, the subwindows are still mapped, but are not visible because \f(CIw\fP is unmapped. Unmapping a window will generate exposure events on windows that were formerly obscured by \f(CIw\fP. .LP For more information on window mapping, see Volume One, Chapter 2, \fIX Concepts\fP. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXMapRaised()\fP\s+1, \s-1\fIXMapSubwindows()\fP\s+1, \s-1\fIXMapWindow()\fP\s+1, \s-1\fIXUnmapSubwindows()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XUnsetICFocus" "Xlib \- Input Contexts" .ds ]W Xlib Reference Manual .XX "XUnsetICFocus" .XX "input contexts:focus, setting and unsetting" .SH Name .Na XUnsetICFocus \(en unset input context focus. .Nz .SH Synopsis .Sy void XUnsetICFocus\^(\^\f(CIic\fP\^) .As XIC \f(CIic\fP\^; .Ae .SH Arguments .IP \f(CIic\fP 1i Specifies the input context. .SH Availability Release 5 and later. .SH Description \f(CWXUnsetICFocus()\fR allows a client to notify an input method that the specified input context has lost the keyboard focus and that no more input is expected on the focus window attached to that input context. The input method should take action to provide appropriate feedback. .SH "See Also" \s-1\fIXCreateIC()\fP\s+1, \s-1\fIXSetICValues()\fP\s+1, \s-1\fIXmbResetIC()\fP\s+1, \s-1\fIXwcResetIC()\fP\s+1, \s-1\fIXSetICFocus()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XVaCreateNestedList" "Xlib \- Input Methods" .ds ]W Xlib Reference Manual .XX "XVaCreateNestedList" .XX "nested variable argument lists" .XX "variable argument lists:nested" .SH Name .Na XVaCreateNestedList \(en allocate a nested variable argument list. .Nz .SH Synopsis .Sy .ti -10n XVaNestedList XVaCreateNestedList\^(\^\f(CIdummy\fP\^, ...) .As int \f(CIdummy\fP\^; .Ae .SH Arguments .IP \f(CIdummy\fP 1i Unused argument (required by ANSI C). .ds Al .IP ... 1i Specifies the variable length argument list\*(Al. .SH Returns The variable-length argument list. .SH Availability Release 5 and later. .SH Description \f(CWXVaCreateNestedList()\fP creates a nested argument list of type \f(CWXVaNestedList\fP. The first argument is an integer value which is unused but required because ANSI-C does not allow variable-length argument lists which do not have any "non-variable" arguments. This first argument is followed by a \f(CWNULL\fR-terminated variable-length argument list. Generally, the arguments will be input method or input context attribute name/value pairs. .LP Nested lists created in this way may be used in any of the input method and input context functions which require a variable-length argument list. Also, the \f(CWXNPreeditAttributes\fP and \f(CWXNStatusAttributes\fP input context attributes are of this type \f(CWXVaNestedList\fP. .LP \f(CWXVaCreateNestedList()\fR allocates memory and copies its arguments into a single list pointer which may be used as value for arguments requiring a list value. Any entries are copied as specified. Data passed by reference is not copied; the caller must ensure that data remains valid for the lifetime of the nested list. The list should be freed using \f(CWXFree()\fR when it is no longer needed. .SH "See Also" \s-1\fIXCreateIC()\fP\s+1, \s-1\fIXSetICValues()\fP\s+1, \s-1\fIXGetICValues()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XVendorRelease" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XVendorRelease, VendorRelease \(en return vendor release number. .XX "XVendorRelease" .Nz .\" .\" .SH "Synopsis" .Sy int XVendorRelease\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" .\" .SH Returns The vendor release number. .SH Description .XX "vendor release number" \f(CWXVendorRelease()\fP return a number related to a vendor's release of the X server. .LP .XX "VendorRelease macro" The C language macro \f(CWVendorRelease()\fP is equivalent and slightly more efficient. .LP .XX "XlibSpecificationRelease" Note also that in Release 5, the \f(CWXlibSpecificationRelease\fP symbol is defined (with the value 5) by Xlib. Before Release 5 this symbol was not defined. .\" .\" .SH "See Also" \s-1\fIXServerVendor()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XVisualIDFromVisual" "Xlib \- Color" .ds ]W Xlib Reference Manual .SH "Name" .Na XVisualIDFromVisual \(en returns the visual ID for the specified visual structure. .XX "XVisualIDFromVisual" .Nz .\" .\" .SH "Synopsis" .Sy VisualID XVisualIDFromVisual\^(\^\f(CIvisual\fP\^) .As Visual *\^\f(CIvisual\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIvisual\fP 1i Specifies the visual structure. .\" .\" .SH Returns The visual ID. .SH Description .XX "visual ID:returning" \f(CWXVisualIDFromVisual()\fP returns the visual ID for the specified visual structure. It simply extracts a field from the \f(CWXVisualInfo\fP structure. .LP The visual ID is occasionally useful in association with standard colormap structures and in matching or selecting visuals. .LP There is no macro called \f(CWVisualIDFromVisual()\fR. .\" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XWMGeometry" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XWMGeometry" .XX "windows:geometry information, obtaining" .Na XWMGeometry \(en obtain a window's geometry information. .Nz .SH "Synopsis" .Sy int XWMGeometry\^(\^\f(CIdisplay\fP\^, \f(CIscreen\fP\^, \f(CIuser_geom\fP\^, \ \f(CIdef_geom\fP\^, \f(CIbwidth_return\fP\^, \f(CIhints\fP\^, \f(CIx_return\fP\^, \f(CIy_return\fP\^, \f(CIwidth_return\fP\^, \f(CIheight_return\fP\^, \f(CIgravity_return\fP\^) .As Display *\f(CIdisplay\fP\^; int \f(CIscreen\fP\^; char *\f(CIuser_geom\fP\^; char *\f(CIdef_geom\fP\^; unsigned int \f(CIbwidth_return\fP\^; XSizeHints *\f(CIhints\fP\^; int *\f(CIx_return\fP\^, *\f(CIy_return\fP\^; int *\f(CIwidth\fP\^, *height_return\^; int *\f(CIgravity_return\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIscreen\fP 1i Specifies the screen. .IP \f(CIuser_geom\fP 1i Specifies the user-specified geometry or \f(CWNULL\fP. .IP \f(CIdef_geom\fP 1i Specifies the application's default geometry or \f(CWNULL\fP. .IP \f(CIbwidth\fP 1i Specifies the border width. .IP \f(CIhints\fP 1i Specifies the size hints for the window in its normal state. .IP \f(CIx_return\fP 1i .br .ns .IP \f(CIy_return\fP 1i Return the x and y offsets. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight_return\fP 1i Return the width and height determined. .IP \f(CIgravity_return\fP 1i Returns the window gravity. .SH "Availability" Release 4 and later. A mask \- see the "Description" section. .SH Description .XX "geometry:obtaining window information" .hw NORMAL \f(CWXWMGeometry\fR combines possibly incomplete or nonexistent geometry information (given in the format used by \f(CWXParseGeometry()\fR) specified by the user and by the calling program with complete program-supplied default size hints (usually the ones to be stored in \f(CWWM_NORMAL_HINTS\fP) and returns the position, size, and gravity (\f(CWNorthWestGravity\fR, \f(CWNorthEastGravity\fR, \f(CWSouthEastGravity\fR or \f(CWSouthWestGravity\fR) that describe the window. If the base size is not set in the \f(CWXSizeHints\fR structure, the minimum size is used if set. Otherwise, a base size of zero is assumed. If no minimum size is set in the hints structure, the base size is used. A mask (in the form returned by \f(CWXParseGeometry()\fR) that describes which values came from the user .ne 5 and whether or not the position coordinates are relative to the right and bottom edges is returned (which will have already been accounted for in the \f(CWx_return\fP and \f(CWy\fP values). .LP Note that invalid user geometry specifications can cause a width or height of zero to be returned. The caller may pass the address of the \f(CWwin_gravity\fP field of the \f(CIhints\fP argument as the \f(CIgravity_return\fP argument. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Structures" .Ps typedef struct { long flags; /* marks which fields in this structure are /* defined */ int x, y; /* obsolete for new window mgrs, but clients */ int width, height; /* should set so old wm's don't mess up */ int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; int base_width, base_height; /* added by ICCCM version 1 */ int win_gravity; /* added by ICCCM version 1 */ } XSizeHints .Pe .SH "See Also" \s-1\fIXChangeWindowAttributes()\fP\s+1, \s-1\fIXParseGeometry()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XWarpPointer" "Xlib \- Pointer" .ds ]W Xlib Reference Manual .SH "Name" .XX "pointers:moving to another point on the screen" .XX "XWarpPointer" .Na XWarpPointer \(en move the pointer to another point on the screen. .Nz .SH "Synopsis" .Sy XWarpPointer\^(\^\f(CIdisplay\f(CW, \f(CIsrc_w\f(CW\^, \f(CIdest_w\f(CW\^, \f(CIsrc_x\f(CW\^, \f(CIsrc_y\f(CW\^, \f(CIsrc_width\f(CW\^, \f(CIsrc_height\f(CW\^, \f(CIdest_x\f(CW\^, \f(CIdest_y\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIsrc_w\f(CW\^, \f(CIdest_w\f(CW\^; int \f(CIsrc_x\f(CW\^, \f(CIsrc_y\f(CW\^; unsigned int \f(CIsrc_width\f(CW\^, \f(CIsrc_height\f(CW\^; int \f(CIdest_x\f(CW\^, \f(CIdest_y\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIsrc_w\fP 1.1i Specifies the ID of the source window. You can also pass \f(CWNone\fP. .IP \f(CIdest_w\fP 1.1i Specifies the ID of the destination window. You can also pass \f(CWNone\fP. .IP \f(CIsrc_x\fP 1.1i .br .ns .IP \f(CIsrc_y\fP 1.1i .sp -2 Specify the x and y coordinates within the source window. These are used with \f(CIsrc_width\fP and \f(CIsrc_height\fP to determine the rectangle the pointer must be in in order to be moved. They are not the present pointer position. If \f(CIsrc_w\fP is \f(CWNone\fP, these coordinates are relative to the root window of \f(CIsrc_w\fP. .IP \f(CIsrc_width\fP 1.1i .br .ns .IP \f(CIsrc_height\fP 1.1i .sp -2 Specify the width and height in pixels of the source area. Used with \f(CIsrc_x\fP and \f(CIsrc_y\fP. .IP \f(CIdest_x\fP 1.1i .br .ns .IP \f(CIdest_y\fP 1.1i .sp -2 Specify the destination x and y coordinates within the destination window. If \f(CIdest_w\fP is \f(CWNone\fP, these coordinates are relative to the root window of \f(CIdest_w\fP. .SH Description \f(CWXWarpPointer()\fP moves the pointer suddenly from one point on the screen to another. .LP If \f(CIdest_w\fP is a window, \f(CWXWarpPointer()\fP moves the pointer to [\f(CIdest_x\fP, \f(CIdest_y\fP] relative to the destination window's origin. If \f(CIdest_w\fP is \f(CWNone\fP, \f(CWXWarpPointer()\fP moves the pointer according to the offsets [\f(CIdest_x\fP, \f(CIdest_y\fP] relative to the current position of the pointer. .LP If \f(CIsrc_w\fP is \f(CWNone\fP, the move is independent of the current cursor position (\f(CIdest_x\fP and \f(CIdest_y\fP use global coordinates). If the source window is not \f(CWNone\fP, the move only takes place if the pointer is currently contained in a visible portion of the rectangle of the source window (including its inferiors) specified by \f(CIsrc_x\fP, \f(CIsrc_y\fP, \f(CIsrc_width\fP and \f(CIsrc_height\fP. If \f(CIsrc_width\fP is zero (0), the pointer must be between .ne 5 \f(CIsrc_x\fP and the right edge of the window to be moved. .nd 2 If \f(CIsrc_height\fP is zero (0), the pointer must be between \f(CIsrc_y\fP and the bottom edge of the window to be moved. .LP \f(CWXWarpPointer()\fP cannot be used to move the pointer outside the \f(CWconfine_to\fP window of an active pointer grab. If such an attempt is made, the pointer is moved to the point on the border of the \f(CWconfine_to\fP window nearest the requested destination. .LP \f(CWXWarpPointer()\fP generates events as if the user had (instantaneously) moved the pointer. .LP This function should not be used unless absolutely necessary, and then only in tightly controlled, predictable situations. It has the potential to confuse the user. .SH "Errors" \f(CWBadWindow\fP .SH "See Also" \s-1\fIXChangeActivePointerGrab()\fP\s+1, \s-1\fIXChangePointerControl()\fP\s+1, \s-1\fIXGetPointerControl()\fP\s+1, \s-1\fIXGetPointerMapping()\fP\s+1, \s-1\fIXGrabPointer()\fP\s+1, \s-1\fIXQueryPointer()\fP\s+1, \s-1\fIXSetPointerMapping()\fP\s+1, \s-1\fIXUngrabPointer()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XWhitePixel*" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XWhitePixel, XWhitePixelOfScreen, WhitePixel, WhitePixelOfScreen \(en get the white pixel value. .XX "XWhitePixel" .XX "XWhitePixelOfScreen" .Nz .SH "Synopsis" .Sy unsigned long XWhitePixel\^(\^\f(CIdisplay\fP\^, \^\f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; int \f(CIscreen_number\fP\^; .Ae .Sy unsigned long XWhitePixelOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number on the server, as returned by \f(CWXDefaultScreen*()\fP or the \f(CWDefaultScreen()\fP macro. .IP \f(CIscreen\fP 1i Specifies the appropriate \f(CWScreen\fP structure, as returned by \f(CWXDefaultScreenOfDisplay()\fP or \f(CWXScreenOfDisplay()\fP, or the \f(CWDefaultScreenOfDisplay()\fP or \f(CWScreenOfDisplay()\fP macros. .SH Returns The pixel value. .SH Description .XX "pixel values:white" .XX "white pixel values" Each screen has a default colormap which has pixel values for white and white already allocated. These functions return the white pixel value. Note that this pixel value only represents white in a screen's default colormap. .LP \f(CWXWhitePixel()\fP and \f(CWXWhitePixelOfScreen()\fP are equivalent except that they require different arguments. One requires a pointer to a \f(CWScreen\fP structure, while the other requires a screen number. Unless you already have the pointer to a \f(CWScreen\fP structure in a variable, \f(CWXWhitePixel*()\fP is more convenient. .LP .XX "WhitePixel macro" .XX "WhitePixelOfScreen macro" The C language macros \f(CWWhitePixel()\fP and \f(CWWhitePixelOfScreen()\fP are equivalent and slightly more efficient. .SH "See Also" \s-1\fIXBlackPixel*()\fP\s+1, \s-1\fIXBlackPixelOfScreen()\fP\s+1, \s-1\fIXDefaultColormap*()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XWidth*OfScreen" "Xlib \- Macro Equivalents" .ds ]W Xlib Reference Manual .SH "Name" .Na XWidthOfScreen, XWidthMMOfScreen, WidthOfScreen, WidthMMOfScreen \(en get width of screen in pixels or millimeters .XX "XWidthOfScreen" .XX "XWidthMMOfScreen" .Nz .\" .\" .SH "Synopsis" .Sy int XWidthOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .Sy int XWidthMMOfScreen\^(\^\f(CIscreen\fP\^) .As Screen *\f(CIscreen\fP\^; .Ae .\" .\" .SH "Arguments" .IP \f(CIscreen\fP 1i Specifies the appropriate \f(CWScreen\fP structure. .\" .\" .SH Returns The width in pixels or millimeters. .SH Description .XX "screens:width" \f(CWXWidthOfScreen()\fP returns the width of the specified screen in pixels. \f(CWXWidthMMOfScreen()\fP returns the width of the specified screen in millimeters. .LP .XX "WidthOfScreen macro" .XX "WidthMMOfScreen macro" The C language macros \f(CWWidthOfScreen()\fP and \f(CWWidthMMOfScreen()\fP are equivalent and slightly more efficient. .LP These functions are equivalent to \f(CWXDisplayWidth*()\fP and \f(CWXDisplayWidthMM()\fP except that they take different arguments. .\" .\" .SH "See Also" \s-1\fIXDisplayHeight()\fP\s+1, \s-1\fIXDisplayHeightMM()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XWindowEvent" "Xlib \- Input Handling" .ds ]W Xlib Reference Manual .SH "Name" .XX "XWindowEvent" .XX "events:removing matching" .Na XWindowEvent \(en remove the next event that matches the specified mask and window. .Nz .SH "Synopsis" .Sy XWindowEvent\^(\^\f(CIdisplay\f(CW, \f(CIw\f(CW\^, \f(CIevent_mask\f(CW\^, \f(CIevent_return\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; Window \f(CIw\f(CW\^; long \f(CIevent_mask\f(CW\^; XEvent *\f(CIevent_return\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1i Specifies the ID of the window whose next matching event you want. .IP \f(CIevent_mask\fP 1i Specifies the event mask. See \f(CWXSelectInput()\fP for a complete list of event masks. .IP \f(CIevent_return\fP 1i Returns the event removed from the input queue. .SH Description \f(CWXWindowEvent()\fP removes the next event in the queue which matches both the passed window and the passed mask. The event is copied into an \f(CWXEvent\fP structure supplied by the caller. Other events in the queue are not discarded. If no such event has been queued, \f(CWXWindowEvent()\fP flushes the request buffer and waits until one is received. .LP \f(CWXWindowEvent()\fp cannot return \f(CWClientMessage\fP, \f(CWMappingNotify\fP, \f(CWSelectionClear\fP, \f(CWSelectionNotify\fP, or \f(CWSelectionRequest\fP events because these event types are by definition unmaskable. .SH "Structures" See individual event structures described in Volume One, Chapter 8, \fIEvents\fP, and Appendix\ F, \fIStructure Reference\fP, in this volume. .SH "See Also" \s-1\fIXQLength()\fP\s+1, \s-1\fIXAllowEvents()\fP\s+1, \s-1\fIXCheckIfEvent()\fP\s+1, \s-1\fIXCheckMaskEvent()\fP\s+1, \s-1\fIXCheckTypedEvent()\fP\s+1, \s-1\fIXCheckTypedWindowEvent()\fP\s+1, \s-1\fIXCheckWindowEvent()\fP\s+1, \s-1\fIXEventsQueued()\fP\s+1, \s-1\fIXGetInputFocus()\fP\s+1, \s-1\fIXGetMotionEvents()\fP\s+1, \s-1\fIXIfEvent()\fP\s+1, \s-1\fIXMaskEvent()\fP\s+1, \s-1\fIXNextEvent()\fP\s+1, \s-1\fIXPeekEvent()\fP\s+1, \s-1\fIXPeekIfEvent()\fP\s+1, \s-1\fIXPending()\fP\s+1, \s-1\fIXPutBackEvent()\fP\s+1, \s-1\fIXSelectInput()\fP\s+1, \s-1\fIXSendEvent()\fP\s+1, \s-1\fIXSetInputFocus()\fP\s+1, \s-1\fIXSynchronize()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XWithdrawWindow" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "windows:withdrawing" .XX "XWithdrawWindow" .Na XWithdrawWindow \(en request that a top-level window be withdrawn. .Nz .SH "Synopsis" .Sy Status XWithdrawWindow\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CIscreen_number\fP\^) .As Display *\f(CIdisplay\fP\^; Window \f(CIw\fP\^; int \f(CIscreen_number\fP\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .\" $Header: /work/X/Xlib/vol2.r5/allmanpages/RCS/WithdrawWind 2.5 1993/05/28 13:41:30 stephen Exp $ .IP \f(CIw\fP 1i Specifies the window. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number on the server. .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 4 and later. .SH Description .LP \f(CWXWithdrawWindow()\fR informs the window manager that the specified window and its icon should be unmapped. It unmaps the specified window and sends a synthetic \f(CWUnmapNotify\fR event to the root window of the specified screen. Window managers may elect to receive this message and may treat it as a request to change the window's state to withdrawn. When a window is in the withdrawn state, neither its normal nor its iconic representation is visible. \f(CWXWithdrawWindow()\fP returns a non-zero status if the \f(CWUnmapNotify\fR event is successfully sent; otherwise, it returns a zero status. .LP For more information, see Volume One, Chapter 12, \fIInterclient Communication\fP. .SH "Errors" \f(CWBadWindow\fR .SH "See Also" \s-1\fIXIconifyWindow()\fP\s+1, \s-1\fIXReconfigureWMWindow()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XWriteBitmapFile" "Xlib \- Pixmaps and Tiles" .ds ]W Xlib Reference Manual .SH "Name" .XX "XWriteBitmapFile" .XX "bitmaps:writing to files" .Na XWriteBitmapFile \(en write a bitmap to a file. .Nz .SH "Synopsis" .Sy int XWriteBitmapFile(\^\f(CIdisplay\f(CW, \f(CIfilename\f(CW, \f(CIbitmap\f(CW, \f(CIwidth\f(CW, \f(CIheight\f(CW, \f(CIx_hot\f(CW, \f(CIy_hot\f(CW\^) .As Display *\f(CIdisplay\f(CW\^; char *\f(CIfilename\f(CW\^; Pixmap \f(CIbitmap\f(CW\^; unsigned int \f(CIwidth\f(CW, \f(CIheight\f(CW\^; int \f(CIx_hot\f(CW, \f(CIy_hot\f(CW\^; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIfilename\fP 1i Specifies filename to use. Filename format is operating system specific. .IP \f(CIbitmap\fP 1i Specifies the bitmap to be written. .IP \f(CIwidth\fP 1i .br .ns .IP \f(CIheight\fP 1i .sp -2 Specify the width and height in pixels of the bitmap to be written. .sp .IP \f(CIx_hot\fP 1i .br .ns .IP \f(CIy_hot\fP 1i .sp -2 Specify where to place the hotspot coordinates (or \-1,\-1 if none present) in the file. .SH Returns \f(CWBitmapSuccess\fP on success. \f(CWBitmapOpenFailed\fP or \f(CWBitmapNoMemory\fP on failure. .SH Description \f(CWXWriteBitmapFile()\fP writes a bitmap to a file. The file is written out in X version 11 bitmap file format, shown below. The file is written in the encoding of the current locale. .LP If the file cannot be opened for writing, \f(CWXWriteBitmapFile()\fP returns \f(CWBitmapOpenFailed\fP. If insufficient memory is allocated \f(CWXWriteBitmapFile()\fP returns \f(CWBitmapNoMemory\fP. Otherwise, on no error, \f(CWXWriteBitmapFile()\fP returns \f(CWBitmapSuccess\fP. .LP If \f(CIx_hot\fP and \f(CIy_hot\fP are not \-1, \-1, then \f(CWXWriteBitmapFile()\fP writes them out as the hotspot coordinates for the bitmap. .LP The following is an example of the contents of a bitmap file created. The name used ("gray" in this example) is the portion of \f(CIfilename\fP after the last "/\^". .LP .ne 4 .ps 8 .vs 10 .ta 4.5n 9n .nf .ft CW #define gray_width 16 #define gray_height 16 #define gray_x_hot 8 #define gray_y_hot 8 static char gray_bits[] = { 0xf8, 0x1f, 0xe3, 0xc7, 0xcf, 0xf3, 0x9f, 0xf9, 0xbf, 0xfd, 0x33, 0xcc, 0x7f, 0xfe, 0x7f, 0xfe, 0x7e, 0x7e, 0x7f, 0xfe, 0x37, 0xec, 0xbb, 0xdd, 0x9c, 0x39, 0xcf, 0xf3, 0xe3, 0xc7, 0xf8, 0x1f}; .fi .ft R .ps .vs .LP For more information on bitmaps, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH Errors .IP "\f(CWBadAlloc\fP" 1i .IP "\f(CWBadDrawable\fP" 1i .IP "\f(CWBadMatch\fP" 1i The specified \f(CIwidth\fP and \f(CIheight\fP did not match dimensions of the specified \f(CIbitmap\fP. .SH "See Also" \s-1\fIXCreateBitmapFromData()\fP\s+1, \s-1\fIXCreatePixmap()\fP\s+1, \s-1\fIXCreatePixmapFromBitmapData()\fP\s+1, \s-1\fIXFreePixmap()\fP\s+1, \s-1\fIXQueryBestSize()\fP\s+1, \s-1\fIXQueryBestStipple()\fP\s+1, \s-1\fIXQueryBestTile()\fP\s+1, \s-1\fIXReadBitmapFile()\fP\s+1, \s-1\fIXSetTile()\fP\s+1, \s-1\fIXSetWindowBackgroundPixmap()\fP\s+1, \s-1\fIXSetWindowBorderPixmap()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XXorRegion" "Xlib \- Regions" .ds ]W Xlib Reference Manual .SH "Name" .XX "XXorRegion" .XX "regions:calculating difference between union and intersection of" .Na XXorRegion \(en calculate the difference between the union and intersection of two regions. .Nz .SH "Synopsis" .Sy XXorRegion\^(\^\f(CIsra\f(CW\^, \f(CIsrb\f(CW\^, \f(CIdr_return\f(CW\^) .As Region \f(CIsra\f(CW\^, \f(CIsrb\f(CW\^; Region \f(CIdr_return\fP; .Ae .SH "Arguments" .IP \f(CIsra\fP 1i .br .ns .IP \f(CIsrb\fP 1i .sp -2 Specify the two regions on which you want to perform the computation. .sp .IP \f(CIdr_return\fP 1i Returns the result of the computation. .SH Description \f(CWXXorRegion()\fP calculates the union minus the intersection of two regions, and places it in \f(CIdr_return\fP. Xor is short for "Exclusive OR", meaning that a pixel is included in \f(CIdr_return\fP if it is set in either \f(CIsra\fP or \f(CIsrb\fP but not in both. .LP For more information on regions, see Volume One, Chapter 6, \fIDrawing Graphics and Text\fR. .SH "Structures" \f(CWRegion\fP is a pointer to an opaque structure type. .SH "See Also" \s-1\fIXClipBox()\fP\s+1, \s-1\fIXCreateRegion()\fP\s+1, \s-1\fIXDestroyRegion()\fP\s+1, \s-1\fIXEmptyRegion()\fP\s+1, \s-1\fIXEqualRegion()\fP\s+1, \s-1\fIXIntersectRegion()\fP\s+1, \s-1\fIXOffsetRegion()\fP\s+1, \s-1\fIXPointInRegion()\fP\s+1, \s-1\fIXPolygonRegion()\fP\s+1, \s-1\fIXRectInRegion()\fP\s+1, \s-1\fIXSetRegion()\fP\s+1, \s-1\fIXShrinkRegion()\fP\s+1, \s-1\fIXSubtractRegion()\fP\s+1, \s-1\fIXUnionRectWithRegion()\fP\s+1, \s-1\fIXUnionRegion()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsAddColorSpace" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsAddColorSpace" .XX "color spaces:adding" .XN "device-independent color:(see also color spaces)" .XN "color:device independent (see device-independent color)" .SH "Name" .Na XcmsAddColorSpace \(en add a device-independent color space. .Nz .SH "Synopsis" .Sy Status XcmsAddColorSpace(\f(CIcolor_space\fP) .As XcmsColorSpace *\f(CIcolor_space\fP; .Ae .SH "Arguments" .IP \f(CIcolor_space\fP 1i Specifies the device-independent color space to add. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description .XN "XcmsColorSpace structure:(see also color spaces)" \f(CWXcmsAddColorSpace()\fR makes a device-independent color space (actually an \f(CWXcmsColorSpace\fR structure) accessible by the color management system. .XX "color spaces:unregistered" Because format values for unregistered color spaces are assigned at run-time, they should be treated as private to the client. If references to an unregistered color space must be made outside the client (for example, storing color specifications in a file using the unregistered color space), then reference should be made by color space prefix (see \f(CWXcmsFormatOfPrefix()\fR and \f(CWXcmsPrefixOfFormat()\fR). .LP If the \f(CWXcmsColorSpace\fR structure is already accessible in the color management system, \f(CWXcmsAddColorSpace()\fR returns \f(CWXcmsSuccess\fR. .LP Note that added \f(CWXcmsColorSpace\fR structures must be retained for reference by Xlib. .SH Structures Refer to the \f(CWXcmsColorSpace\fP reference page. .SH "See Also" \s-1\fIXcmsColorSpace()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsAddFunctionSet" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsAddFunctionSet" .XX "function sets, Color Characterization" .SH "Name" .Na XcmsAddFunctionSet \(en add a Color Characterization function set. .XX "Color Characterization function sets" .Nz .SH "Synopsis" .Sy Status XcmsAddFunctionSet(\f(CIfunction_set\fP) .As XcmsFunctionSet *\f(CIfunction_set\fP; .Ae .SH "Arguments" .IP \f(CIfunction_set\fP 1.5i Specifies the Color Characterization Function Set to add. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description .XX "color spaces:unregistered" \f(CWXcmsAddFunctionSet()\fR adds a Color Characterization Function Set to the color management system. If the function set contains device-dependent \f(CWXcmsColorSpace\fR structures not previously available in the color management system, \f(CWXcmsAddFunctionSet()\fR performs the internal registration necessary to make them accessible to the client. If an added \f(CWXcmsColorSpace\fR structure is for a device-dependent color space not registered with the X Consortium, because format values for unregistered color spaces are assigned at run-time they should be treated as private to the client. If references to an unregistered color space must be made outside the client (for example, storing color specifications in a file using the unregistered color space), then reference should be made by color space prefix (see \f(CWXcmsFormatOfPrefix()\fR and \f(CWXcmsPrefixOfFormat()\fR). .LP Additional function sets should be added before any calls to other Xlib routines are made. If not, the \f(CWXcmsPerScrnInfo\fR member of a previously created .\" CHANGED FROM: XXX .\"\f(CWXcmsCCC\fR .\"does not have the opportunity to initialize .\"with the added function set. \f(CWXcmsCCC\fR will not have been initialized with the added function set. .LP Note that added \f(CWXcmsFunctionSet\fR structures must be retained for reference by Xlib. .SH Structures Refer to the \f(CWXcmsFunctionSet\fP reference page. .SH "See Also" \s-1\fIXcmsFunctionSet()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsAllocColor" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsAllocColor" .XX "device-independent color:allocating" .SH Name .Na XcmsAllocColor \(en allocate a color specified in device-independent or device-dependent form. .Nz .SH Synopsis .Sy Status XcmsAllocColor\^(\^\f(CIdisplay\fP\^, \f(CIcolormap\fP\^, \f(CIcolor_in_out\fP\^, \f(CIresult_format\fP\^) .As Display *\f(CIdisplay\fP\^; Colormap \f(CIcolormap\fP\^; XcmsColor *\f(CIcolor_in_out\fP\^; XcmsColorFormat \f(CIresult_format\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIcolormap\fP 1i Specifies the colormap. .IP \f(CIcolor_in_out\fP 1i Specifies the color to allocate and returns the pixel and color that is actually used in the colormap. .IP \f(CIresult_format\fP 1i Specifies the desired color format for the returned color specification. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description .XX "XAllocColor" The \f(CWXcmsAllocColor()\fR function is similar to \f(CWXAllocColor()\fR except the color can be specified in any format supported by the color management system (e.g., CIEXYZ, CIELUV, RGB). The \f(CWXcmsAllocColor()\fR function ultimately calls \f(CWXAllocColor()\fR to allocate a read-only color cell (colormap entry) with the specified color. \f(CWXcmsAllocColor()\fR first converts the color specified to an RGB value and then passes this to \f(CWXAllocColor\fR. \f(CWXcmsAllocColor()\fR returns the pixel value of the color cell and the color specification actually allocated. This returned color specification is the result of converting the RGB value returned by \f(CWXAllocColor()\fR into the format specified by the \f(CIresult_format\fP argument. If there is no interest in a returned color specification, unnecessary computation can be bypassed if \f(CIresult_format\fP is set to \f(CWXcmsRGBFormat\fR. If this routine returns \f(CWXcmsFailure\fR, the \f(CIcolor_in_out\fP color specification is left unchanged. .Nd 5 .SH Structures The \f(CWXcmsColor\fP and \f(CWXcmsColorFormat\fP structures are shown on the \f(CWXcmsColor\fP reference page. .SH Errors .TP 1i \f(CWBadColor\fR The \f(CIcolormap\fP argument does not name a defined Colormap. .SH "See Also" \s-1\fIXcmsAllocNamedColor()\fP\s+1, \s-1\fIXcmsLookupColor()\fP\s+1, \s-1\fIXcmsQueryColor()\fP\s+1, \s-1\fIXcmsQueryColors()\fP\s+1, \s-1\fIXcmsStoreNamedColor\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsAllocNamedColor" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsAllocNamedColor" .XX "device-independent color:allocating" .XN "RGB values:(see color)" .SH Name .Na XcmsAllocNamedColor \(en allocate a color specified as a string. .Nz .SH Synopsis .Sy Status XcmsAllocNamedColor\^(\^\f(CIdisplay\fP\^, \f(CIcolormap\fP\^, \f(CIcolor_string\fP\^, .br \f(CIcolor_screen_return\fP\^, \f(CIcolor_exact_return\fP\^,\f(CIresult_format\fP\^) .As Display *\f(CIdisplay\fP\^; Colormap \f(CIcolormap\fP\^; char *\f(CIcolor_string\fP\^; XcmsColor *\f(CIcolor_screen_return\fP\^; XcmsColor *\f(CIcolor_exact_return\fP\^; XcmsColorFormat \f(CIresult_format\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIcolormap\fP 1i Specifies the colormap. .ds St \ whose color definition structure is to be returned .IP \f(CIcolor_string\fP 1i Specifies the color string\*(St. .IP \f(CIcolor_screen_return\fP 1i Returns the pixel value of the color cell and color specification that actually is stored for that cell. .IP \f(CIcolor_exact_return\fP 1i Returns the color specification parsed from the color string or parsed from the corresponding string found in a color name database. .IP \f(CIresult_format\fP 1i Specifies the desired color format for the returned color specification. .SH Returns Zero on failure, non-zero on success. .SH Description .XX "XAllocNamedColor:versus XcmsAllocNamedColor" The \f(CWXcmsAllocNamedColor()\fR function is similar to \f(CWXAllocNamedColor()\fR except the color specification returned can be specified to be in any format supported by the color management system. This function ultimately calls \f(CWXAllocColor()\fR to allocate a read-only color cell with the color specified by a color string. The color string is parsed into an \f(CWXcmsColor\fR structure, converted to an RGB value, then finally passed to \f(CWXAllocColor()\fR. .LP .Nd 10 The color string may contain a color name that appears in the client-side or X server's color database; or a numerical color specification for any color management supported color spaces such that the string conforms to the uniform syntax: .IP <\f(CIcolor_space\fP>:<\f(CIcolor_space_specific_encoding\fP> .LP For example: .\"start no ds .Ps RGB:\f(CIred\fP/\f(CIgreen\fP/\f(CIblue\fP RGBi:\f(CIR\fP/\f(CIG\fP/\f(CIB\fP CIEXYZ:\f(CIX\fP/\f(CIY\fP/\f(CIZ\fP CIEuvY:\f(CIu\fP/\f(CIv\fP/\f(CIY\fP CIExyY:\f(CIx\fP/\f(CIy\fP/\f(CIY\fP CIELab:\f(CIL\fP/\f(CIa\fP/\f(CIb\fP CIELuv:\f(CIL\fP/\f(CIu\fP/\f(CIv\fP TekHVC:\f(CIH\fP/\f(CIV\fP/\f(CIC\fP .Pe .\"end no ds .XX "RGB color spaces" .XX "color spaces:RGB" For the RGB color space, the \f(CIred\fP, \f(CIgreen\fP, and \f(CIblue\fP parameters are hexidecimal strings of one to four digits. For each of the other color spaces, each parameter is a floating-point number in standard string format. In each case, each number specifies a value for one of the parameters of the color space. Old-style RGB color strings beginning with a "#" remain supported for backwards compatibility. If the color name is not in the Host Portable Character Encoding the result is implementation-dependent. Color names are case-insensitive. .LP This function returns both the color specification as a result of parsing (exact specification) and the actual color specification stored (screen specification). This screen specification is the result of converting the RGB value returned by \f(CWXAllocColor()\fR into the format specified by \f(CIresult_format\fP. If there is no interest in a returned color specification, unnecessary computation can be bypassed if \f(CIresult_format\fP is set to \f(CWXcmsRGBFormat\fR. .SH Errors .TP 1i \f(CWBadColor\fR The \f(CIcolormap\fP argument does not name a defined Colormap. .SH Structures The \f(CWXcmsColor\fP and \f(CWXcmsColorFormat\fP structures are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsAllocColor()\fP\s+1, \s-1\fIXcmsLookupColor()\fP\s+1, \s-1\fIXcmsQueryColor()\fP\s+1, \s-1\fIXcmsQueryColors()\fP\s+1, \s-1\fIXcmsStoreColor()\fP\s+1, \s-1\fIXcmsStoreColors()\fP\s+1, \s-1\fIXcmsStoreNamedColor\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXLookupColor()\fP\s+1, \s-1\fIXParseColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsCCCOfColormap" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsCCCOfColormap" .XX "CCC:of colormap" .XX "colormaps:obtaining CCC of" .SH "Name" .Na XcmsCCCOfColormap \(en get the Color Conversion Context of a colormap. .Nz .\" .\" .SH "Synopsis" .Sy XcmsCCC XcmsCCCOfColormap(\f(CIdisplay\fP, \f(CIcolormap\fP) .As Display *\f(CIdisplay\fP; Colormap \f(CIcolormap\fP; .Ae .\" .\" .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIcolormap\fP 1i Specifies the colormap for which the CCC is to be returned. .\" .\" .SH Returns The Color Conversion Context. .SH "Availability" Release 5 and later. .\" .\" .SH Description \f(CWXcmsCCCOfColormap()\fR returns the CCC associated with the specified colormap. This CCC is used implicitly when the specified colormap is used as an argument to many Xcms device-independent color functions. \f(CWXcmsCCCOfColormap()\fP returns the CCC so that its contents can be modified and/or so it can be passed explicitly to color conversion functions that do not take a colormap argument (e.g., \f(CWXcmsConvertColors()\fP). .SH "See Also" \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsClientWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsConvertColors()\fP\s+1, \s-1\fIXcmsDefaultCCC()\fP\s+1, \s-1\fIXcmsDisplayOfCCC()\fP\s+1, \s-1\fIXcmsFreeCCC()\fP\s+1, \s-1\fIXcmsScreenNumberOfCCC()\fP\s+1, \s-1\fIXcmsScreenWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsSetCCCOfColormap()\fP\s+1, \s-1\fIXcmsSetCompressionProc()\fP\s+1, \s-1\fIXcmsSetWhiteAdjustProc()\fP\s+1, \s-1\fIXcmsSetWhitePoint()\fP\s+1, \s-1\fIXcmsVisualOfCCC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsCIELabQueryMax*" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .SH Name .Na XcmsCIELabQueryMaxC, XcmsCIELabQueryMaxL, XcmsCIELabQueryMaxLC, XcmsCIELabQueryMinL \(en obtain the bounds of the target screen's color gamut in terms of CIE L*a*b* coordinates. .Nz .SH Synopsis .Sy .\"If these functions get split into separate pages, put the following .\" XX index entry into each page .XX "CIE L*a*b* coordinates" .XX "XcmsCIELabQueryMaxC" Status XcmsCIELabQueryMaxC\^(\^\f(CIccc\fP\^, \f(CIhue_angle\fP\^, \f(CIL_star\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsFloat \f(CIhue_angle\fP\^; XcmsFloat \f(CIL_star\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .XX "XcmsCIELabQueryMaxL" .Sy Status XcmsCIELabQueryMaxL\^(\^\f(CIccc\fP\^, \f(CIhue_angle\fP\^, \f(CIchroma\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsFloat \f(CIhue_angle\fP\^; XcmsFloat \f(CIchroma\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .XX "XcmsCIELabQueryMaxLC" .Sy Status XcmsCIELabQueryMaxLC\^(\^\f(CIccc\fP\^, \f(CIhue_angle\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsFloat \f(CIhue_angle\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .XX "XcmsCIELabQueryMinL" .Sy Status XcmsCIELabQueryMinL\^(\^\f(CIccc\fP\^, \f(CIhue_angle\fP\^, \f(CIchroma\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsFloat \f(CIhue_angle\fP\^; XcmsFloat \f(CIchroma\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .SH Arguments .IP \f(CIccc\fP 1i Specifies the color conversion context. Note that the CCC's Client White Point and White Point Adjustment procedures are ignored. .ds Ch maximum lightness (MaxL) or minimum lightness (MinL) .IP \f(CIchroma\fP 1i Specifies the CIELAB psychometric chroma at which to find \*(Ch. .ds Lc maximum chroma (MaxC and MaxLC), maximum lightness (MaxL), \ or minimum lightness (MinL) .ds lCC hue angle and lightness (MaxC), hue angle and chroma (MaxL and MinL), \ or hue angle (MaxLC) .IP \f(CIcolor_return\fP 1i Returns the CIE L*a*b* coordinates of \*(Lc displayable by the screen for the given \*[lCC]. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. .ds Ha maximum chroma (MaxC and MaxLC), maximum lightness (MaxL), \ or minimum lightness (MinL) .Nd 10 .IP \f(CIhue_angle\fP 1i Specifies the CIELAB psychometric hue angle in degrees at which to find \*(Ha. .ds Ls maximum chroma (MaxC) .IP \f(CIL_star\fP 1i Specifies the lightness (L*) at which to find \*(Ls. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description .XX "Chroma:finding maximum Value for" \f(CWXcmsCIELabQueryMaxC()\fR finds the point of maximum chroma displayable by the screen at the given hue angle and lightness. .LP .XX "Lightness:finding maximum Value for" \f(CWXcmsCIELabQueryMaxL()\fP finds the point in CIELAB color space of maximum lightness (L*) displayable by the screen at the given hue angle and chroma. An \f(CWXcmsFailure\fP return value usually indicates that the given chroma is beyond maximum for the given hue angle. .LP .XX "Chroma:finding maximum Value for" \f(CWXcmsCIELabQueryMaxLC()\fP finds the point of maximum chroma displayable by the screen at the given hue angle. .LP .XX "Lightness:finding maximum Value for" \f(CWXcmsCIELabQueryMinL()\fP finds the point of minimum lightness (L*) displayable by the screen at the given hue angle and chroma. An \f(CWXcmsFailure\fP return value usually indicates that the given chroma is beyond maximum for the given hue angle. .LP All these functions return a point in CIE L*a*b* color space coordinates. .SH "See Also" \s-1\fIXcmsCIELuvQueryMaxC()\fP\s+1, \s-1\fIXcmsCIELuvQueryMaxL()\fP\s+1, \s-1\fIXcmsCIELuvQueryMaxLC()\fP\s+1, \s-1\fIXcmsCIELuvQueryMinL()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxC()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxL\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxLC\fP\s+1, \%\s-1\fIXcmsTekHVCQueryMinL\fP\s+1, \s-1\fIXcmsQueryBlack()\fP\s+1, \s-1\fIXcmsQueryBlue()\fP\s+1, \s-1\fIXcmsQueryGreen()\fP\s+1, \s-1\fIXcmsQueryRed()\fP\s+1, \s-1\fIXcmsQueryWhite()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsCIELuvQueryMax*" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .SH Name .Na .XX "CIE L*u*v* coordinates" XcmsCIELuvQueryMaxC, XcmsCIELuvQueryMaxL, XcmsCIELuvQueryMaxLC, XcmsCIELuvQueryMinL \(en obtain the bounds of the target screen's color gamut in terms of CIE L*u*v* coordinates. .Nz .SH Synopsis .Sy .XX "XcmsCIELuvQueryMaxC" Status XcmsCIELuvQueryMaxC\^(\^\f(CIccc\fP\^, \f(CIhue_angle\fP\^, \f(CIL_star\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsFloat \f(CIhue_angle\fP\^; XcmsFloat \f(CIL_star\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .XX "XcmsCIELuvQueryMaxL" .Sy Status XcmsCIELuvQueryMaxL\^(\^\f(CIccc\fP\^, \f(CIhue_angle\fP\^, \f(CIchroma\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsFloat \f(CIhue_angle\fP\^; XcmsFloat \f(CIchroma\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .XX "XcmsCIELuvQueryMaxLC" .Sy Status XcmsCIELuvQueryMaxLC\^(\^\f(CIccc\fP\^, \f(CIhue_angle\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsFloat \f(CIhue_angle\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .XX "XcmsCIELuvQueryMinL" .Sy Status XcmsCIELuvQueryMinL\^(\^\f(CIccc\fP\^, \f(CIhue_angle\fP\^, \f(CIchroma\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsFloat \f(CIhue_angle\fP\^; XcmsFloat \f(CIchroma\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .SH Arguments .IP \f(CIccc\fP 1i Specifies the color conversion context. Note that the CCC's Client White Point and White Point Adjustment procedures are ignored. .ds Ch maximum lightness (MaxL) or minimum lightness (MinL) .IP \f(CIchroma\fP 1i Specifies the CIELUV psychometric chroma at which to find \*(Ch. .ds Lc maximum chroma (MaxC and MaxLC), maximum lightness (MaxL), \ or minimum lightness (MinL) .ds lCC hue angle and lightness (MaxC), hue angle and chroma (MaxL and MinL), \ or hue angle (MaxLC) .IP \f(CIcolor_return\fP 1i Returns the CIE L*u*v* coordinates of \*(Lc displayable by the screen for the given \*[lCC]. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. .ds Ha maximum chroma (MaxC and MaxLC), maximum lightness (MaxL), \ or minimum lightness (MinL) .Nd 10 .IP \f(CIhue_angle\fP 1i Specifies the CIELUV psychometric hue angle in degrees at which to find \*(Ha. .ds Ls maximum chroma (MaxC) or maximum lightness (MaxL) .IP \f(CIL_star\fP 1i Specifies the lightness (L*) at which to find \*(Ls. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description .XX "Chroma:finding maximum Value for" \f(CWXcmsCIELuvQueryMaxC()\fP finds the point of maximum chroma displayable by the screen at the given hue angle and lightness. .LP .XX "Lightness:finding maximum Value for" \f(CWXcmsCIELuvQueryMaxL()\fP finds the point in CIE L*u*v* color space of maximum lightness (L*) displayable by the screen at the given hue angle and chroma. An \f(CWXcmsFailure\fP return value usually indicates that the given chroma is beyond maximum for the given hue angle. .LP .XX "Chroma:finding maximum Value for" \f(CWXcmsCIELuvQueryMaxLC()\fP finds the point of maximum chroma displayable by the screen at the given hue angle. .LP .XX "Lightness:finding maximum Value for" \f(CWXcmsCIELuvQueryMinL()\fP finds the point of minimum lightness (L*) displayable by the screen at the given hue angle and chroma. An \f(CWXcmsFailure\fP return value usually indicates that the given chroma is beyond maximum for the given hue angle. .LP All these functions return a point in CIE L*u*v* color space coordinates. .SH "See Also" \s-1\fIXcmsCIELabQueryMaxC()\fP\s+1, \s-1\fIXcmsCIELabQueryMaxL()\fP\s+1, \s-1\fIXcmsCIELabQueryMaxLC()\fP\s+1, \s-1\fIXcmsCIELabQueryMinL()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxC()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxL\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxLC\fP\s+1, \s-1\fIXcmsTekHVCQueryMinL\fP\s+1, \s-1\fIXcmsQueryBlack()\fP\s+1, \s-1\fIXcmsQueryBlue()\fP\s+1, \s-1\fIXcmsQueryGreen()\fP\s+1, \s-1\fIXcmsQueryRed()\fP\s+1, \s-1\fIXcmsQueryWhite()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "\s-1XcmsClientWhitePointOfCCC\s+1" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsClientWhitePointOfCCC" .SH "Name" .Na XcmsClientWhitePointOfCCC \(en return the client white point associated with the specified Color Conversion Context. .Nz .SH "Synopsis" .Sy XcmsColor *XcmsClientWhitePointOfCCC(\f(CIccc\fP) .As XcmsCCC \f(CIccc\fP; .Ae .Sy ClientWhitePointOfCCC(\f(CIccc\fP) .As XcmsCCC \f(CIccc\fP; .Ae .SH "Arguments" .IP \f(CIccc\fP 1i Specifies the color conversion context. .SH Returns The \f(CWXcmsColor\fP structure containing the white point. See the \f(CWXcmsColor\fP reference page. .SH Availability Release 5 and later. .SH Description .XX "Client White Point:returning" .LP \f(CWXcmsClientWhitePointOfCCC()\fP and the macro \f(CWClientWhitePointOfCCC\fP both return the Client White Point of the specified CCC. The Client White Point attribute of the CCC specifies the white point the client assumes to be associated with color specifications. If different from the Screen White Point, adjustments are specified by the CCC's white adjustment procedure. .SH "See Also" \s-1\fIXcmsCCCOfColormap()\fP\s+1, \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsConvertColors()\fP\s+1, \s-1\fIXcmsDefaultCCC()\fP\s+1, \s-1\fIXcmsDisplayOfCCC()\fP\s+1, \s-1\fIXcmsScreenNumberOfCCC()\fP\s+1, \s-1\fIXcmsScreenWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsSetCompressionProc()\fP\s+1, \s-1\fIXcmsSetWhiteAdjustProc()\fP\s+1, \s-1\fIXcmsSetWhitePoint()\fP\s+1, \s-1\fIXcmsVisualOfCCC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsColor" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsColor structure" .XN "color spaces:(see also XcmsColor structure)" .SH Name .Na XcmsColor \(en Xcms color structure. .Nz .SH Availability Release 5 and later. .SH Description The \f(CWXcmsColor\fR structure contains a union of substructures, each supporting a color space specific encoding. .hw XcmsColor .LP The \f(CWXcmsColorFormat\fP type is used to identify the color space associated with the values in the \f(CWXcmsColor\fP structure. It is also used as an argument to some Xcms functions to indicate the desired format of returned color specifications. .SH Structures The \f(CWXcmsColor\fR structure contains: .Ps typedef unsigned long XcmsColorFormat; /* Color Specification Format */ #define XcmsUndefinedFormat (XcmsColorFormat)0x00000000 #define XcmsCIEXYZFormat (XcmsColorFormat)0x00000001 #define XcmsCIEuvYFormat (XcmsColorFormat)0x00000002 #define XcmsCIExyYFormat (XcmsColorFormat)0x00000003 #define XcmsCIELabFormat (XcmsColorFormat)0x00000004 #define XcmsCIELuvFormat (XcmsColorFormat)0x00000005 #define XcmsTekHVCFormat (XcmsColorFormat)0x00000006 #define XcmsRGBFormat (XcmsColorFormat)0x80000000 #define XcmsRGBiFormat (XcmsColorFormat)0x80000001 typedef struct { union { XcmsRGB RGB; XcmsRGBi RGBi; XcmsCIEXYZ CIEXYZ; XcmsCIEuvY CIEuvY; XcmsCIExyY CIExyY; XcmsCIELab CIELab; XcmsCIELuv CIELuv; XcmsTekHVC TekHVC; XcmsPad Pad; } spec; XcmsColorFormat format; unsigned long pixel; } XcmsColor; /* Xcms Color Structure */ .ne 12 typedef double XcmsFloat; typedef struct { unsigned short red; /* 0x0000 to 0xffff */ unsigned short green; /* 0x0000 to 0xffff */ unsigned short blue; /* 0x0000 to 0xffff */ } XcmsRGB; /* RGB Device */ typedef struct { XcmsFloat red; /* 0.0 to 1.0 */ XcmsFloat green; /* 0.0 to 1.0 */ XcmsFloat blue; /* 0.0 to 1.0 */ } XcmsRGBi; /* RGB Intensity */ typedef struct { XcmsFloat X; XcmsFloat Y; /* 0.0 to 1.0 */ XcmsFloat Z; } XcmsCIEXYZ; /* CIE XYZ */ typedef struct { XcmsFloat u_prime; /* 0.0 to ~0.6 */ XcmsFloat v_prime; /* 0.0 to ~0.6 */ XcmsFloat Y; /* 0.0 to 1.0 */ } XcmsCIEuvY; /* CIE u'v'Y */ typedef struct { XcmsFloat x; /* 0.0 to ~.75 */ XcmsFloat y; /* 0.0 to ~.85 */ XcmsFloat Y; /* 0.0 to 1.0 */ } XcmsCIExyY; /* CIE xyY */ typedef struct { XcmsFloat L_star; /* 0.0 to 100.0 */ XcmsFloat a_star; XcmsFloat b_star; } XcmsCIELab; /* CIE L*a*b* */ typedef struct { XcmsFloat L_star; /* 0.0 to 100.0 */ XcmsFloat u_star; XcmsFloat v_star; } XcmsCIELuv; /* CIE L*u*v* */ typedef struct { XcmsFloat H; /* 0.0 to 360.0 */ XcmsFloat V; /* 0.0 to 100.0 */ XcmsFloat C; /* 0.0 to 100.0 */ } XcmsTekHVC; /* TekHVC */ .ne 12 typedef struct { XcmsFloat pad0; XcmsFloat pad1; XcmsFloat pad2; XcmsFloat pad3; } XcmsPad; /* padded to 4 floats for future or */ /* user-defined color space encodings */ /* that require more space than what */ /* 3 floats can provide */ .Pe .SH "See Also" \s-1\fIXcmsAllocColor()\fP\s+1, \s-1\fIXcmsAllocNamedColor()\fP\s+1, \s-1\fIXcmsConvertColors()\fP\s+1, \s-1\fIXcmsLookupColor()\fP\s+1, \s-1\fIXcmsQueryColor()\fP\s+1, \s-1\fIXcmsQueryColors()\fP\s+1, \s-1\fIXcmsStoreColor()\fP\s+1, \s-1\fIXcmsStoreColors()\fP\s+1, \s-1\fIXcmsStoreNamedColor\fP\s+1, \%\s-1\fIXcmsClientWhitePointOfCCC()\fP\s+1\fP, \s-1\fIXcmsSetWhitePoint()\fP\s+1, \s-1\fIXcmsScreenWhitePointOfCCC()\fP\s+1\fP, \s-1\fIXcmsCIELabQueryMaxC()\fP\s+1, \s-1\fIXcmsCIELabQueryMaxL()\fP\s+1, \s-1\fIXcmsCIELabQueryMaxLC()\fP\s+1, \s-1\fIXcmsCIELabQueryMinL()\fP\s+1, \s-1\fIXcmsCIELuvQueryMaxC()\fP\s+1, \s-1\fIXcmsCIELuvQueryMaxL()\fP\s+1, \s-1\fIXcmsCIELuvQueryMaxLC()\fP\s+1, \s-1\fIXcmsCIELuvQueryMinL()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxC()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxL\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxLC\fP\s+1, \%\s-1\fIXcmsTekHVCQueryMinL\fP\s+1, \s-1\fIXcmsQueryBlack()\fP\s+1, \s-1\fIXcmsQueryBlue()\fP\s+1, \s-1\fIXcmsQueryGreen()\fP\s+1, \s-1\fIXcmsQueryRed()\fP\s+1, \s-1\fIXcmsQueryWhite()\fP\s+1, \s-1\fIXcmsCompressionProc\fP\s+1, \s-1\fIXcmsWhiteAdjustProc\fP\s+1, \s-1\fIXcmsConversionProc\fP\s+1, \s-1\fIXcmsParseStringProc\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsColorSpace" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsColorSpace structure" .SH Name .Na .XX "color:encoding;(see also device-independent color)" .XX "color spaces:parsing color strings for" XcmsColorSpace \(en Xcms color space structure. .Nz .SH Availability Release 5 and later. .SH Description The \f(CWXcmsColorSpace\fR structure contain the information necessary to convert the encoding of color specifications to other color spaces, and to parse a color string encoded specifically for this color space. .LP The \f(CWprefix\fP member points to a string that identifies that a color strings encoding is for this particular color space. .IP <\f(CIcolor_space\fP>:<\f(CIcolor_space_specific_encoding\fP> .LP For example, the prefix "cieuvy:" for the color string "CIEuvY:0.119/0.545/0.254". Although the prefix in the color string may be entered in uppercase or lowercase, all characters of the prefix specified in the \f(CWXcmsColorSpace\fP must be in lowercase. .LP The \f(CWid\fP member is predefined if the color space is registered with the X Consortium; otherwise assigned at run-time (see \f(CWXcmsAddColorSpace()\fP). .LP The \f(CWparseString\fP member points to the color space specific string parsing function. .LP .XX "CIEXYZ:converting to and from" The \f(CWto_CIEXYZ\fP member is pointer to an array of functions that, when executed in sequence, will convert a \f(CWXcmsColor\fP structure encoded for this color space to the CIEXYZ encoding. .LP The \f(CWfrom_CIEXYZ\fP member is pointer to an array of functions that, when executed in sequence, will convert a \f(CWXcmsColor\fP structure encoded for CIEXYZ to this color space's encoding. .LP The \f(CWinverse_flag\fP member if set (i.e., 1) indicates that for each function in the \f(CWto_CIEXYZ\fP list, there is an inverse function in the \f(CWfrom_CIEXYZ\fP list. Note however that the corresponding order is reversed \- the inverse of the first function in \f(CWto_CIEXYZ\fP will be the last function in \f(CWfrom_CIEXYZ\fP. .SH Structures The \f(CWXcmsColorSpace\fR structure contains: .Ps typedef XcmsConversionProc *XcmsFuncListPtr; typedef struct _XcmsColorSpace { char *prefix; XcmsColorFormat id; XcmsParseStringProc parseString; XcmsFuncListPtr to_CIEXYZ; XcmsFuncListPtr from_CIEXYZ; int inverse_flag; } XcmsColorSpace; .Pe .SH "See Also" \s-1\fIXcmsAddColorSpace()\fP\s+1, \s-1\fIXcmsAddFunctionSet()\fP\s+1, \s-1\fIXcmsFunctionSet\fP\s+1, \s-1\fIXcmsConversionProc\fP\s+1, \s-1\fIXcmsParseStringProc\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsCompressionProc" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsCompressionProc" .SH "Name" .Na XcmsCompressionProc \(en interface definition for gamut compression procedure. .XX "compression procedures" .XX "gamut compression" .Nz .SH "Synopsis" .Sy typedef Status (*XcmsCompressionProc)(\f(CIccc\fP, \f(CIcolors_in_out\fP, \f(CIncolors\fP, \f(CIindex\fP, \f(CIcompression_flags_return\fP) .As XcmsCCC \f(CIccc\fP; XcmsColor \f(CIcolors_in_out[]\fP; unsigned int \f(CIncolors\fP; unsigned int \f(CIindex\fP; Bool \f(CIcompression_flags_return[]\fP; .Ae .SH "Arguments" .IP \f(CIccc\fP 1i Specifies the color conversion context. .IP \f(CIcolors_in_out\fP 1i Specifies an array of color specifications. Pixel members are ignored and remain unchanged upon return. .IP \f(CIncolors\fP 1i Specifies the number of \f(CWXcmsColor\fR structures in the color specification array. .IP \f(CIindex\fP 1i Specifies the index into the array of \f(CWXcmsColor\fR structures for the encountered color specification that lies outside the \f(CWScreen\fR's color gamut. Valid values are 0 (for the first element) to ncolors\(en1. .IP \f(CIcompression_flags_return\fP 1i Specifies an array of Boolean values (or \f(CWNULL\fP) for returned information that indicates if the color was compressed. For example, if this routine returns \f(CWXcmsSuccessWithCompression\fR, and \f(CWcompression_flags_\p return[3]\fP is \f(CWTrue\fR, this indicates that the fourth color specified in the color specification array was compressed. If you are not interested in knowing which color was compressed when the return value is \f(CWXcmsSuccessWithCompression\fR, then pass a \f(CW\f(CWNULL\fP\fR. Otherwise, allocate an array of Boolean values for each element in the color definition array and pass its address. .SH Returns Zero on failure, non-zero on success. .Nd 5 .SH Availability Release 5 and later. .Nd 10 .SH Description A gamut compression procedure maps a range of colors in a device-independent color space into a range of colors displayable on a physical device. .LP When implementing a gamut compression procedure, consider the following rules and assumptions: .IP \(bu 3n The gamut compression procedure can attempt to compress one or multiple specifications at a time. .IP \(bu 3n When called, elements 0 to index\(en1 in the array of color specification array can be assumed to fall within the screen's color gamut. In addition these color specifications are already in some device-dependent format (typically \f(CWXcmsRGBi\fR). If any modifications are made to these color specifications, they must upon return be in their initial device-dependent format. .IP \(bu 3n When called, the element in the color specification array specified by the index argument contains the color specification outside the screen's color gamut encountered by the calling routine. In addition this color specification can be assumed to be in \f(CWXcmsCIEXYZ\fR. Upon return, this color specification must be in \f(CWXcmsCIEXYZ\fR. .IP \(bu 3n When called, elements from index to ncolors\(en1 in the color specification array may or may not fall within the screen's color gamut. In addition these color specifications can be assumed to be in \f(CWXcmsCIEXYZ\fR. If any modifications are made to these color specifications, they must upon return be in \f(CWXcmsCIEXYZ\fR. .IP \(bu 3n .XX "Screen White Point" .XX "white point" The color specifications passed to the gamut compression procedure have already been adjusted to the Screen White Point. This means that at this point the color specification's white point is the Screen White Point. .IP \(bu 3n If the gamut compression procedure uses a device-independent color space not initially accessible for use in the color management system, use .XX "XcmsAddColorSpace" \f(CWXcmsAddColorSpace()\fR to insure that it is added. .SH "See Also" \s-1\fIXcmsCCCOfColormap()\fP\s+1, \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsClientWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsDefaultCCC()\fP\s+1, \s-1\fIXcmsSetCCCOfColormap()\fP\s+1, \s-1\fIXcmsSetCompressionProc()\fP\s+1, \s-1\fIXcmsSetWhiteAdjustProc()\fP\s+1, \s-1\fIXcmsSetWhitePoint()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsConversionProc" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsConversionProc" .SH "Name" .XX "color spaces:color conversion between" .XX "color:conversion;(see also device-independent color)" .Na XcmsConversionProc \(en interface definition for the procedure for color conversion between device-independent color spaces. .Nz .SH "Synopsis" For conversion between device-independent color spaces: .Sy typedef Status (*XcmsConversionProc)(\f(CIccc\fP, \f(CIwhite_point\fP, \f(CIcolors\fP, \f(CIncolors\fP) .As XcmsCCC \f(CIccc\fP; XcmsColor *\f(CIwhite_point[]\fP; XcmsColor \f(CIcolors[]\fP; unsigned int \f(CIncolors\fP; .Ae .LP For conversion between CIEXYZ and device-dependent color spaces: .LP .Sy typedef Status (*XcmsConversionProc)(\f(CIccc\fP, \f(CIcolors\fP, \f(CIncolors\fP, \f(CICIcompression_flags_return\fP) .As XcmsCCC \f(CIccc\fP; XcmsColor \f(CIcolors[]\fP; unsigned int \f(CIncolors\fP; Bool \f(CIcompression_flags_return[]\fP; .Ae .SH "Arguments" .IP \f(CIccc\fP 1i Specifies the color conversion context. .IP \f(CIwhite_point\fP 1i Specifies the white point associated with the color specifications. Pixel member is ignored and the color specification is left unchanged upon return. .IP \f(CIcolors\fP 1i Specifies an array of color specifications. Pixel members are ignored and remain unchanged upon return. .IP \f(CIncolors\fP 1i Specifies the number of \f(CWXcmsColor\fR structures in the color specification array. .IP \f(CIcompression_flags_return\fP 1i Specifies an array of Boolean values (or \f(CWNULL\fP) for returned information that indicates if the color was compressed. During conversion, when a color is found to out of gamut, this argument is passed in the gamut compression function call. For an example, refer to the source code for \f(CWXcmsCIEXYZToRGBi\fP. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .Nd 10 .SH Description An \f(CWXcmsConversionProc\fR procedure converts \f(CWXcmsColor\fP between device-independent color space encodings. .LP Procedures provided and accessible in Xlib for conversion between device-independent color spaces are: .IP \(bu 3n .XX "XcmsCIELabToCIEXYZ" .XX "XcmsCIELab:converting to XcmsCIELab" \f(CWXcmsCIELabToCIEXYZ\fR \(en Converts color specifications from \f(CWXcmsCIELab\fP to \f(CWXcmsCIELab\fP. .IP \(bu 3n .XX "XcmsCIELuvToCIEuvY" .XX "XcmsCIELuv:converting to XcmsCIEuvY" \f(CWXcmsCIELuvToCIEuvY\fR \(en Converts color specifications from \f(CWXcmsCIELuv\fP to \f(CWXcmsCIEuvY\fP. .IP \(bu 3n .XX "XcmsCIEXYZToCIELab" .XX "XcmsCIEXYZ:converting to XcmsCIELab" \f(CWXcmsCIEXYZToCIELab\fR \(en Converts color specifications from \f(CWXcmsCIEXYZ\fP to \f(CWXcmsCIELab\fP. .IP \(bu 3n .XX "XcmsCIEXYZToCIEuvY" .XX "XcmsCIEXYZ:converting to XcmsCIEuvY" \f(CWXcmsCIEXYZToCIEuvY\fR \(en Converts color specifications from \f(CWXcmsCIEXYZ\fP to \f(CWXcmsCIEuvY\fP. .IP \(bu 3n .XX "XcmsCIEXYZToCIExyY" .XX "XcmsCIEXYZ:converting to XcmsCIExyY" \f(CWXcmsCIEXYZToCIExyY\fR \(en Converts color specifications from \f(CWXcmsCIEXYZ\fP to \f(CWXcmsCIExyY\fP. .IP \(bu 3n .XX "XcmsCIEuvYToCIELuv" .XX "XcmsCIEuvY:converting to XcmsCIELuv" \f(CWXcmsCIEuvYToCIELuv\fR \(en Converts color specifications from \f(CWXcmsCIEuvY\fP to \f(CWXcmsCIELuv\fP. .IP \(bu 3n .XX "XcmsCIEuvYToCIEXYZ" .XX "XcmsCIEuvY:converting to XcmsCIEXYZ" \f(CWXcmsCIEuvYToCIEXYZ\fR \(en Converts color specifications from \f(CWXcmsCIEuvY\fP to \f(CWXcmsCIEXYZ\fP. .IP \(bu 3n .XX "XcmsCIEuvYToCIETekHVC" .XX "XcmsCIEuvY:converting to XcmsCIETekHVC" \f(CWXcmsCIEuvYToCIETekHVC\fR \(en Converts color specifications from \f(CWXcmsCIEuvY\fP to \f(CWXcmsCIETekHVC\fP. .IP \(bu 3n .XX "XcmsCIExyYToCIEXYZ" .XX "XcmsCIExyY:converting to XcmsCIEXYZ" \f(CWXcmsCIExyYToCIEXYZ\fR \(en Converts color specifications from \f(CWXcmsCIExyY\fP to \f(CWXcmsCIEXYZ\fP. .IP \(bu 3n .XX "XcmsTekHVCToCIEuvY" .XX "XcmsTekHVC:converting to XcmsCIEuvY" \f(CWXcmsTekHVCToCIEuvY\fR \(en Converts color specifications from \f(CWXcmsTekHVC\fP to \f(CWXcmsCIEuvY\fP. .LP .XX "CIEXYZ:and conversion between device\(enindependent color spaces" .XX "color spaces:device\(enindependent, conversion between CIEXYX" Procedures provided and accessible in Xlib for conversion between CIEXYZ and device\(endependent color spaces are: .IP \(bu 3n .XX "XcmsCIEXYZToRGBi" .XX "XcmsCIEXYZ:converting to XcmsRGBi" \f(CWXcmsCIEXYZToRGBi\fR \(en Converts color specifications from \f(CWXcmsCIEXYZ\fP to \f(CWXcmsRGBi\fP. .IP \(bu 3n .XX "XcmsRGBToRGBi" .XX "XcmsRGB:converting to XcmsRGBi" \f(CWXcmsRGBToRGBi\fR \(en Converts color specifications from \f(CWXcmsRGB\fP to \f(CWXcmsRGBi\fP. .IP \(bu 3n .XX "XcmsRGBiToCIEXYZ" .XX "XcmsRGBi:converting to XcmsCIEXYZ" \f(CWXcmsRGBiToCIEXYZ\fR \(en Converts color specifications from \f(CWXcmsRGBi\fP to \f(CWXcmsCIEXYZ\fP. .IP \(bu 3n .XX "XcmsRGBiToRGB" .XX "XcmsRGBi:converting to XcmsRGB" \f(CWXcmsRGBiToRGB\fR \(en Converts color specifications from \f(CWXcmsRGBi\fP to \f(CWXcmsRGB\fP. .Nd 5 .SH Structures The \f(CWXcmsColor\fP structure and \f(CWXcmsColorFormat\fP type are shown on the \f(CWXcmsColor\fP reference page. Refer also to the \f(CWXcmsColorSpace\fP reference page. .SH "See Also" \s-1\fIXcmsColorSpace\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsConvertColors" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsConvertColors" .XX "color:specification;converting CCC" .XX "CCC:color specifications, converting" .XX "XcmsColor structure:converting color specifications to other encodings" .SH Name .Na XcmsConvertColors \(en convert color specifications in XcmsColor structures to another color space specific encoding. .Nz .SH Synopsis .Sy Status XcmsConvertColors\^(\^\f(CIccc\fP\^, \f(CIcolors_in_out\fP\^, \f(CIncolors\fP\^, \f(CItarget_format\fP\^, .br \f(CIcompression_flags_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsColor \f(CIcolors_in_out\fP\^[\^]\^; unsigned int \f(CIncolors\fP\^; XcmsColorFormat \f(CItarget_format\fP\^; Bool \f(CIcompression_flags_return\fP\^[\^]\^; .Ae .SH Arguments .IP \f(CIccc\fP 1.1i Specifies the color conversion context. If conversion is between device-independent color spaces only (for example, TekHVC to CIELuv), the CCC is necessary only to specify the Client White Point. .IP \f(CIcolors_in_out\fP 1.1i Specifies an array of color specifications. Pixel members are ignored and remain unchanged upon return. .IP \f(CIncolors\fP 1.1i Specifies the number of \f(CWXcmsColor\fR structures in the color specification array. .IP \f(CItarget_format\fP 1.1i Specifies the target color specification format. .IP \f(CIcompression_flags_return\fP 1.1i Specifies an array of \f(CIncolors\fP \f(CWBoolean\fP values for returning compression status of each color conversion. If a non-\f(CWNULL\fP pointer is supplied, each element in the array is set to \f(CWTrue\fR if the corresponding color in the color specification array was compressed, and \f(CWFalse\fR otherwise. Pass \f(CWNULL\fP if the compression status is not useful. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description The \f(CWXcmsConvertColors()\fR function converts the color specifications in the specified array of \f(CWXcmsColor\fR structures from their current format (which may vary from element to element of the array) to a single target format using the specified CCC. If .XX "gamut compression" all the conversions succeed without gamut compression, .XX "XcmsSuccess" .XX "XcmsSuccessWithCompression" .XX "XcmsFailure" \f(CWXcmsConvertColors()\fP returns \f(CWXcmsSuccess\fP. If one or more of the conversions required gamut compression, the function returns \f(CWXcmsSuccessWithCompression\fP, and sets the appropriate flags in \f(CIcompression_flags_return\fP array. If any of the conversions fail, the function returns \f(CWXcmsFailure\fR and the contents of the color specification array are left unchanged. .Nd 10 .SH Structures The \f(CWXcmsColor\fR and \f(CWXcmsColorFormat\fP structures are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsCCCOfColormap()\fP\s+1, \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsClientWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsDefaultCCC()\fP\s+1, \s-1\fIXcmsScreenWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsSetCompressionProc()\fP\s+1, \s-1\fIXcmsSetWhiteAdjustProc()\fP\s+1, \s-1\fIXcmsSetWhitePoint()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsCreateCCC" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsCreateCCC" .XX "CCC:creating" .SH Name .Na XcmsCreateCCC \(en create a Color Conversion Context. .Nz .SH Synopsis .Sy XcmsCCC XcmsCreateCCC\^(\^\f(CIdisplay\fP, \f(CIscreen_number\fP\^, \f(CIvisual\fP\^, \f(CIclient_white_point\fP\^, \f(CIcompression_proc\fP\^, \f(CIcompression_client_data\fP\^, \f(CIwhite_adjust_proc\fP\^, \f(CIwhite_adjust_client_data\fP\^) .As Display *\f(CIdisplay\fP\^; int \f(CIscreen_number\fP\^; Visual *\f(CIvisual\fP\^; XcmsColor *\f(CIclient_white_point\fP\^; XcmsCompressionProc \f(CIcompression_proc\fP\^; XPointer \f(CIcompression_client_data\fP\^; XcmsWhiteAdjustProc \f(CIwhite_adjust_proc\fP\^; XPointer \f(CIwhite_adjust_client_data\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number on the host server. .IP \f(CIvisual\fP 1i Specifies the visual type. .IP \f(CIclient_white_point\fP 1i Specifies the Client White Point. If \f(CWNULL\fP, the Client White Point is to be assumed to be the same as the Screen White Point. Note that the pixel member is ignored. .IP \f(CIcompression_proc\fP 1i Specifies the gamut compression procedure that is to be applied when a color lies outside the screen's color gamut. If \f(CWNULL\fP and when functions using this CCC must convert a color specification to a device-dependent format and encounters a color that lies outside the screen's color gamut, that function will return \f(CWXcmsFailure\fP. .IP \f(CIcompression_client_data\fP 1i Specifies client data for use by the gamut compression procedure or \f(CWNULL\fP. .IP \f(CIwhite_adjust_proc\fP 1i Specifies the white adjustment procedure that is to be applied when the Client White Point differs from the Screen White Point. \f(CWNULL\fP indicates that no white point adjustment is desired. .IP \f(CIwhite_adjust_client_data\fP 1i Specifies client data for use with the white point adjustment procedure or \f(CWNULL\fP. .SH Returns The Color Conversion Context. .SH Availability Release 5 and later. .SH Description \f(CWXcmsCreateCCC()\fP creates a color conversion context for the specified display, screen, and visual. .SH "See Also" \s-1\fIXcmsCCCOfColormap()\fP\s+1, \s-1\fIXcmsClientWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsConvertColors()\fP\s+1, \s-1\fIXcmsDefaultCCC()\fP\s+1, \s-1\fIXcmsDisplayOfCCC()\fP\s+1, \s-1\fIXcmsFreeCCC()\fP\s+1, \s-1\fIXcmsScreenNumberOfCCC()\fP\s+1, \s-1\fIXcmsScreenWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsSetCCCOfColormap()\fP\s+1, \s-1\fIXcmsSetCompressionProc()\fP\s+1, \s-1\fIXcmsSetWhiteAdjustProc()\fP\s+1, \s-1\fIXcmsSetWhitePoint()\fP\s+1, \s-1\fIXcmsVisualOfCCC()\fP\s+1, \s-1\fIXcmsCompressionProc\fP\s+1, \s-1\fIXcmsWhiteAdjustProc\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsDefaultCCC" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsDefaultCCC" .XX "CCC:getting default for a screen" .XX "color:conversion;(see also CCC)" .XX "screens:getting default CCC for" .SH "Name" .Na XcmsDefaultCCC \(en get the default Color Conversion Context for a screen. .Nz .SH "Synopsis" .Sy XcmsCCC XcmsDefaultCCC(\f(CIdisplay\fP, \f(CIscreen_number\fP) .As Display *\f(CIdisplay\fP; int \f(CIscreen_number\fP; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1.25i Specifies the connection to the X server. .IP \f(CIscreen_number\fP 1.25i Specifies the screen number. .\" .\" .SH Returns The Color Conversion Context. .SH "Availability" Release 5 and later. .\" .\" .SH Description \f(CWXcmsDefaultCCC()\fR returns the default CCC for the specified screen. .LP .XX "CCC:default" .XX "CCC:per-screen" Xcms creates and associates a special CCC to each \f(CWScreen\fP before any other CCCs are created. This special per-Screen CCC is called a default CCC. At creation, per-Screen information like the device color characterization data (device profile) is obtained (refer to the ICCCM). Subsequent CCCs created for this \f(CWScreen\fP will use its device characterization data. In addition, CCC attributes (e.g., Client White Point) not explicitly specified in \f(CWXcmsCreateCCC()\fP default to the values in the Screen's default CCC. .\" .\" .SH "See Also" \s-1\fIXcmsCCCOfColormap()\fP\s+1, \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsClientWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsConvertColors()\fP\s+1, \s-1\fIXcmsDisplayOfCCC()\fP\s+1, \s-1\fIXcmsFreeCCC()\fP\s+1, \s-1\fIXcmsScreenNumberOfCCC()\fP\s+1, \s-1\fIXcmsScreenWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsSetCCCOfColormap()\fP\s+1, \s-1\fIXcmsSetCompressionProc()\fP\s+1, \s-1\fIXcmsSetWhiteAdjustProc()\fP\s+1, \s-1\fIXcmsSetWhitePoint()\fP\s+1, \s-1\fIXcmsVisualOfCCC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsDisplayOfCCC" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .SH "Name" .Na XcmsDisplayOfCCC, DisplayOfCCC \(en return the display associated with a Color Conversion Context (CCC). .Nz .SH "Synopsis" .Sy .XX "CCC:display associated with" .XX "XcmsDisplayOfCCC" .XX "DisplayOfCCC" Display *XcmsDisplayOfCCC(\f(CIccc\fP) .As XcmsCCC \f(CIccc\fP; .Ae .Sy DisplayOfCCC(\f(CIccc\fP) .As XcmsCCC \f(CIccc\fP; .Ae .SH "Arguments" .IP \f(CIccc\fP 1i Specifies the color conversion context. .SH Returns The display structure. .SH Availability Release 5 and later. .SH Description \f(CWXcms\f(CWDisplayOfCCC()\fP\fR and \f(CWDisplayOfCCC\fP both return the display associated with the specified CCC. .SH "See Also" \s-1\fIXcmsCCCOfColormap()\fP\s+1, \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsClientWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsConvertColors()\fP\s+1, \s-1\fIXcmsDefaultCCC()\fP\s+1, \s-1\fIXcmsDisplayOfCCC()\fP\s+1, \s-1\fIXcmsScreenNumberOfCCC()\fP\s+1, \s-1\fIXcmsScreenWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsSetCompressionProc()\fP\s+1, \s-1\fIXcmsSetWhiteAdjustProc()\fP\s+1, \s-1\fIXcmsSetWhitePoint()\fP\s+1, \s-1\fIXcmsVisualOfCCC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsFormatOfPrefix" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsFormatOfPrefix" .XX "color spaces:obtaining format ID of" .XX "prefix:color space, obtaining format ID of" .SH "Name" .Na XcmsFormatOfPrefix \(en obtain the format ID of the color space associated with a specified color string prefix. .Nz .SH "Synopsis" .Sy XcmsColorFormat XcmsFormatOfPrefix(\f(CIprefix\fP) .As char *\f(CIprefix\fP; .Ae .SH "Arguments" .IP \f(CIprefix\fP 1i Specifies the string containing the color space prefix. .SH Returns The color space format ID. .SH Availability Release 5 and later. .SH Description \f(CWXcmsFormatOfPrefix()\fR returns the format ID for the specified color space prefix. For example, \f(CWXcmsCIEXYZFormat\fP is returned for the prefix "CIEXYZ". Note that the prefix is case-insensitive. If the color space is not accessible in the color management system, \f(CWXcmsFormatOfPrefix()\fR .XX "XcmsUndefinedFormat" returns \f(CWXcmsUndefinedFormat\fR. .SH Structures The \f(CWXcmsColor\fP structure and \f(CWXcmsColorFormat\fP type are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsPrefixOfFormat()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsFreeCCC" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsFreeCCC" .XX "CCC:freeing" .SH "Name" .Na XcmsFreeCCC \(en free a Color Conversion Context (CCC). .Nz .SH "Synopsis" .Sy void XcmsFreeCCC(\f(CIccc\fP) .As XcmsCCC \f(CIccc\fP; .Ae .SH "Arguments" .IP \f(CIccc\fP 1i Specifies the color conversion context. .SH Availability Release 5 and later. .SH Description \f(CWXcmsFreeCCC()\fR frees the memory used for the specified CCC. Note that calls to free default CCCs or to free CCCs currently associated with colormaps are ignored. .SH "See Also" \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsCCCOfColormap()\fP\s+1, \s-1\fIXcmsDefaultCCC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsFunctionSet" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsFunctionSet structure" .SH Name .Na XcmsFunctionSet \(en Xcms Color Characterization Function Set structure. .Nz .SH Availability Release 5 and later. .SH Description .XX "color:conversion" .XX "CIEXYZ:converting encodings" .XX "RGB Intensity:converting encodings" .XX "RGB Device:converting encodings" .XX "encodings:converting;(see also device-independent color)" The \f(CWXcmsFunctionSet\fR structure contains the information necessary to convert the encoding of color specifications between CIEXYZ, RGB Intensity, and RGB Device encodings; and how to obtain and free Screen Color Characterization Data (also known as the device profile) necessary for color specification conversion. .LP The \f(CWDDColorSpaces\fP member points to an array of pointers to \f(CWXcmsColorSpace\fP structures for device-dependent color spaces \- the information necessary to convert the encoding of color specifications between CIEXYZ, RGB Intensity, and RGB Device encodings. .LP The \f(CWscreenInitProc\fP member identifies the function that obtains the device profile. .LP The \f(CWscreenFreeProc\fP member identifies the function that frees the function set specific device profile obtained with \f(CWscreenInitProc\fP. .SH Structures The \f(CWXcmsFunctionSet\fR structure contains: .Ps typedef struct _XcmsFunctionSet { XcmsColorSpace **DDColorSpaces; XcmsScreenInitProc screenInitProc; XcmsScreenFreeProc screenFreeProc; } XcmsFunctionSet; .Pe .SH "See Also" \s-1\fIXcmsAddFunctionSet()\fP\s+1, \s-1\fIXcmsColorSpace\fP\s+1, \s-1\fIXcmsScreenInitProc\fP\s+1, \s-1\fIXcmsScreenFreeProc\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsLookupColor" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsLookupColor" .XX "color:values, obtaining from a string" .SH Name .Na XcmsLookupColor \(en obtain color values from a string. .Nz .SH Synopsis .Sy Status XcmsLookupColor\^(\^\f(CIdisplay\fP, \f(CIcolormap\fP\^, \f(CIcolor_string\fP\^, .br \f(CIcolor_exact_return\fP\^, \f(CIcolor_screen_return\fP\^, \f(CIresult_format\fP\^) .As Display *\f(CIdisplay\fP\^; Colormap \f(CIcolormap\fP\^; char *\f(CIcolor_string\fP\^; XcmsColor *\f(CIcolor_exact_return\fP\^; XcmsColor *\f(CIcolor_screen_return\fP\^; XcmsColorFormat \f(CIresult_format\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIcolormap\fP 1i Specifies the colormap. .IP \f(CIcolor_string\fP 1i Specifies the color string. .IP \f(CIcolor_exact_return\fP 1i Returns the color specification parsed from the color string or parsed from the corresponding string found in a color name database. .IP \f(CIcolor_screen_return\fP 1i Returns the color that can be reproduced on the \f(CWScreen\fR. .IP \f(CIresult_format\fP 1i Specifies the desired color format for the returned color specifications. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description The \f(CWXcmsLookupColor()\fR function looks up the string name of a color with respect to the screen associated with the specified colormap, but does not store the color into any color cell in the color map. It returns both the exact color values and the closest values provided by the screen with respect to the visual type of the specified colormap. The values are returned in the format specified by \f(CIresult_format\fP. .LP .Nd 10 The color string may contain a color name that appears in the client-side or X server's color database; or a numerical color specification for any color management supported color spaces such that the string conforms to the uniform syntax: .IP <\f(CIcolor_space\fP>:<\f(CIcolor_space_specific_encoding\fP> .LP For example: .\"start no ds .Ps RGB:\f(CIred\fP/\f(CIgreen\fP/\f(CIblue\fP RGBi:\f(CIR\fP/\f(CIG\fP/\f(CIB\fP CIEXYZ:\f(CIX\fP/\f(CIY\fP/\f(CIZ\fP CIEuvY:\f(CIu\fP/\f(CIv\fP/\f(CIY\fP CIExyY:\f(CIx\fP/\f(CIy\fP/\f(CIY\fP CIELab:\f(CIL\fP/\f(CIa\fP/\f(CIb\fP CIELuv:\f(CIL\fP/\f(CIu\fP/\f(CIv\fP TekHVC:\f(CIH\fP/\f(CIV\fP/\f(CIC\fP .Pe .\"end no ds For the RGB color space, the \f(CIred\fP, \f(CIgreen\fP, and \f(CIblue\fP parameters are hexadecimal strings of one to four digits. For each of the other color spaces, each parameter is a floating-point number in standard string format. In each case, each number specifies a value for one of the parameters of the color space. Old-style RGB color strings beginning with a "#" remain supported for backwards compatibility. If the color name is not in the Host Portable Character Encoding the result is implementation-dependent. Color names are case-insensitive. .LP If \f(CIformat\fP is \f(CWXcmsUndefinedFormat\fR and the color string contains a numerical color specification, the specification is returned in the format used in that numerical color specification. If \f(CIformat\fP is \f(CWXcmsUndefinedFormat\fR and the color string contains a color name, the specification is returned in the format used in the color name database entry for that color name. .LP \f(CWXcmsLookupColor()\fR returns \f(CWXcmsSuccess\fR or \f(CWXcmsSuccessWithCompression\fR if the name is resolved, otherwise it returns \f(CWXcmsFailure\fR. If \f(CWXcmsSuccessWithCompression\fR is returned, then the color specification in \f(CIcolor_screen_return\fP is the result of gamut compression. .SH Structures The \f(CWXcmsColor\fP and \f(CWXcmsColorFormat\fP structures are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsAllocColor()\fP\s+1, \s-1\fIXcmsAllocNamedColor()\fP\s+1, \s-1\fIXcmsLookupColor()\fP\s+1, \s-1\fIXcmsQueryColor()\fP\s+1, \s-1\fIXcmsQueryColors()\fP\s+1, \s-1\fIXcmsStoreColor()\fP\s+1, \s-1\fIXcmsStoreColors()\fP\s+1, \s-1\fIXcmsStoreNamedColor\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXLookupColor()\fP\s+1, \s-1\fIXParseColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsParseStringProc" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsParseStringProc" .SH "Name" .Na XcmsParseStringProc \(en interface definition for color string parsing procedure. .Nz .SH "Synopsis" .Sy typedef int (*XcmsParseStringProc)(\f(CIcolor_string\fP, \f(CIcolor_return\fP) .As char *\f(CIcolor_string\fP; XcmsColor *\f(CIcolor_return\fP; .Ae .SH "Arguments" .IP \f(CIcolor_string\fP 1.5i Specifies the color string to parse. .IP \f(CIcolor_return\fP Returns the color specification in the color space's encoding. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description .XX "color strings:parsing into an XcmsColor structure" .XX "XcmsColor structure:parsing color strings into" \f(CWXcmsParseStringProc\fP is the type for a function whose pointer is placed in the \f(CWparseString\fP field of an \f(CWXcmsColorSpace\fP structure. This function parses a color string into an \f(CWXcmsColor\fP structure, returning non-zero if it succeeded and zero otherwise. .SH "See Also" \s-1\fIXcmsColorSpace\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsPrefixOfFormat" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsPrefixOfFormat" .XX "color spaces:obtaining color string prefixes associated with" .XX "color strings:obtaining prefixes associated with color spaces" .SH "Name" .Na XcmsPrefixOfFormat \(en obtain the color string prefix associated with the color space specified by a color format. .Nz .SH "Synopsis" .Sy char *XcmsPrefixOfFormat(\f(CIformat\fP) .As XcmsColorFormat \f(CIformat\fP; .Ae .SH "Arguments" .IP \f(CIformat\fP 1i Specifies the color specification format. .SH Returns The color string prefix. .SH Availability Release 5 and later. .SH Description \f(CWXcmsPrefixOfFormat()\fR returns the string prefix associated with the color specification encoding specified by format. Otherwise, if none is found, it returns \f(CWNULL\fP. Note that the returned string must be treated as read-only. .SH Structures The \f(CWXcmsColor\fP structure and \f(CWXcmsColorFormat\fP type are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsFormatOfPrefix()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsQueryBlack" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsQueryBlack" .XX "screen black" .SH Name .Na XcmsQueryBlack \(en obtain a color specification for screen black. .Nz .SH Synopsis .Sy Status XcmsQueryBlack\^(\^\f(CIccc\fP\^, \f(CItarget_format\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsColorFormat \f(CItarget_format\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .SH Arguments .IP \f(CIccc\fP 1i Specifies the color conversion context. Note that the CCC's Client White Point and White Point Adjustment procedures are ignored. .IP \f(CItarget_format\fP 1i Specifies the target color specification format. .ds Cs .IP \f(CIcolor_return\fP 1i Returns the color specification in the specified target format. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description The \f(CWXcmsQueryBlack()\fR function returns the color specification in the format specified by \f(CItarget_format\fP for screen black (i.e., zero intensity red, green, and blue on the target \f(CWScreen\fP). .SH Structures The \f(CWXcmsColor\fP and \f(CWXcmsColorFormat\fP structures are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsQueryBlue()\fP\s+1, \s-1\fIXcmsQueryGreen()\fP\s+1, \s-1\fIXcmsQueryRed()\fP\s+1, \s-1\fIXcmsQueryWhite()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsQueryBlue" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsQueryBlue" .XX "device-independent color" .XX "screen blue" .SH Name .Na XcmsQueryBlue \(en obtain a color specification for screen blue. .Nz .SH Synopsis .Sy Status XcmsQueryBlue\^(\^\f(CIccc\fP\^, \f(CItarget_format\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsColorFormat \f(CItarget_format\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .SH Arguments .IP \f(CIccc\fP 1i Specifies the color conversion context. Note that the CCC's Client White Point and White Point Adjustment procedures are ignored. .IP \f(CItarget_format\fP 1i Specifies the target color specification format. .ds Cs .IP \f(CIcolor_return\fP 1i Returns the color specification in the specified target format. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description The \f(CWXcmsQueryBlue()\fR function returns the color specification in the format specified by \f(CItarget_format\fP for screen blue (i.e., full intensity blue and zero intensity red and green on the target \f(CWScreen\fP). .SH Structures The \f(CWXcmsColor\fP and \f(CWXcmsColorFormat\fP structures are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsQueryBlack()\fP\s+1, \s-1\fIXcmsQueryGreen()\fP\s+1, \s-1\fIXcmsQueryRed()\fP\s+1, \s-1\fIXcmsQueryWhite()\fP\s+1. .\"last line comment .TH XcmsQueryBl.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XcmsQueryBlack@XcmsQueryBA .sp .5 XcmsQueryBlue@XcmsQueryBB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsQueryColor" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsQueryColor" .XX "colorcells:obtaining color specifications of" .SH Name .Na XcmsQueryColor \(en obtain the color specification of a specified colorcell. .Nz .SH Synopsis .Sy Status XcmsQueryColor\^(\^\f(CIdisplay\fP, \f(CIcolormap\fP\^, \f(CIcolor_in_out\fP\^, \f(CIresult_format\fP\^) .As Display *\f(CIdisplay\fP\^; Colormap \f(CIcolormap\fP\^; XcmsColor *\f(CIcolor_in_out\fP\^; XcmsColorFormat \f(CIresult_format\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIcolormap\fP 1i Specifies the colormap. .IP \f(CIcolor_in_out\fP 1i Specifies the pixel of the color cell to query, and returns the color specification stored for that color cell. .IP \f(CIresult_format\fP 1i Specifies the desired color format for the returned color specifications. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description \f(CWXcmsQueryColor()\fR obtains the RGB value for the colormap cell specified by the \f(CIpixel\fP field of the specified \f(CWXcmsColor\fR structure, and then converts the value to the target format specified by the \f(CIresult_format\fP argument. If the pixel is not a valid index into the specified colormap, a \f(CWBadValue\fR error results. .SH Errors .IP "\f(CWBadColor\fR" 1i The \f(CIcolormap\fP argument does not name a defined Colormap. .IP "\f(CWBadValue\fR" The specified pixel does not represent a valid color cell in the specified colormap. .SH Structures The \f(CWXcmsColor\fP structure and \f(CWXcmsColorFormat\fP type are shown on the \f(CWXcmsColor\fP reference page. .Nd 10 .SH "See Also" \s-1\fIXcmsAllocColor()\fP\s+1, \s-1\fIXcmsAllocNamedColor()\fP\s+1, \s-1\fIXcmsStoreColor()\fP\s+1, \s-1\fIXcmsStoreColors()\fP\s+1, \s-1\fIXcmsStoreNamedColor\fP\s+1, \s-1\fIXcmsQueryColors()\fP\s+1, \s-1\fIXcmsLookupColor()\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsQueryColors" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsQueryColors" .XX "colorcells:obtaining color specifications of" .SH Name .Na XcmsQueryColors \(en obtain the color specifications of the specified colorcells. .Nz .SH Synopsis .Sy Status XcmsQueryColors\^(\^\f(CIdisplay\fP, \f(CIcolormap\fP\^, \f(CIcolors_in_out\fP\^, \f(CIncolors\fP\^, .br \f(CIresult_format\fP\^) .As Display *\f(CIdisplay\fP\^; Colormap \f(CIcolormap\fP\^; XcmsColor *\f(CIcolors_in_out\fP\^[]\^; unsigned int \f(CIncolors\fP\^; XcmsColorFormat \f(CIresult_format\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIcolormap\fP 1i Specifies the colormap. .IP \f(CIcolors_in_out\fP 1i Specifies an array of \f(CWXcmsColor\fP structures, each pixel member indicating the color cell to query. The color specifications for the color cells are returned in these structures. .IP \f(CIncolors\fP 1i Specifies the number of \f(CWXcmsColor\fP structures in the \f(CIcolors_in_out\fP array. .IP \f(CIresult_format\fP 1i Specifies the desired color format for the returned color specifications. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description \f(CWXcmsQueryColors()\fP obtains the RGB values for the colors stored in the colormap cells specified by the \f(CIpixel\fP fields of the specified \f(CWXcmsColor\fP structures, and then converts the values to the target format specified by the \f(CIresult_format\fP argument. If a pixel is not a valid index into the specified colormap, a \f(CWBadValue\fP error results. If more than one pixel is in error, the one that gets reported is arbitrary. .SH Errors .TP 1i \f(CWBadColor\fR The \f(CIcolormap\fP argument does not name a defined Colormap. .TP 1i \f(CWBadValue\fR A specified pixel does not represent a valid color cell in the specified colormap. .Nd 10 .SH Structures The \f(CWXcmsColor\fP structure and \f(CWXcmsColorFormat\fP type are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsAllocColor()\fP\s+1, \s-1\fIXcmsAllocNamedColor()\fP\s+1, \s-1\fIXcmsStoreColor()\fP\s+1, \s-1\fIXcmsStoreColors()\fP\s+1, \s-1\fIXcmsStoreNamedColor\fP\s+1, \s-1\fIXcmsQueryColor()\fP\s+1, \s-1\fIXcmsLookupColor()\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1. .\"last line comment .TH XcmsQueryCo.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XcmsQueryColor@XcmsQueryCA .sp .5 XcmsQueryColors@XcmsQueryCB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsQueryGreen" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsQueryGreen" .XX "screen green" .SH Name .Na XcmsQueryGreen \(en obtain a color specification for screen green. .Nz .SH Synopsis .Sy Status XcmsQueryGreen\^(\^\f(CIccc\fP\^, \f(CItarget_format\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsColorFormat \f(CItarget_format\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .SH Arguments .IP \f(CIccc\fP 1i Specifies the color conversion context. Note that the CCC's Client White Point and White Point Adjustment procedures are ignored. .IP \f(CItarget_format\fP 1i Specifies the target color specification format. .ds Cs .IP \f(CIcolor_return\fP 1i Returns the color specification in the specified target format. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description The \f(CWXcmsQueryGreen()\fR function returns the color specification in the specified target format for full intensity green and zero intensity red and blue. The \f(CWXcmsQueryGreen()\fR function returns the color specification in the format specified by \f(CItarget_format\fP for screen green (i.e., full intensity green and zero intensity red and blue on the target \f(CWScreen\fP). .SH Structures The \f(CWXcmsColor\fP and \f(CWXcmsColorFormat\fP structures are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsQueryBlack()\fP\s+1, \s-1\fIXcmsQueryBlue()\fP\s+1, \s-1\fIXcmsQueryRed()\fP\s+1, \s-1\fIXcmsQueryWhite()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsQueryRed" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsQueryRed" .XX "screen red" .SH Name .Na XcmsQueryRed \(en obtain a color specification for screen red. .Nz .SH Synopsis .Sy Status XcmsQueryRed\^(\^\f(CIccc\fP\^, \f(CItarget_format\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsColorFormat \f(CItarget_format\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .SH Arguments .IP \f(CIccc\fP 1i Specifies the color conversion context. Note that the CCC's Client White Point and White Point Adjustment procedures are ignored. .IP \f(CItarget_format\fP 1i Specifies the target color specification format. .ds Cs .IP \f(CIcolor_return\fP 1i Returns the color specification in the specified target format. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description The \f(CWXcmsQueryRed()\fR function returns the color specification in the specified target format for full intensity red and zero intensity green and blue. The \f(CWXcmsQueryRed()\fR function returns the color specification in the format specified by \f(CItarget_format\fP for screen red\p (i.e., full intensity red and zero intensity green and blue on the target \f(CWScreen\fP). .SH Structures The \f(CWXcmsColor\fP and \f(CWXcmsColorFormat\fP structures are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsQueryBlack()\fP\s+1, \s-1\fIXcmsQueryBlue()\fP\s+1, \s-1\fIXcmsQueryGreen()\fP\s+1, \s-1\fIXcmsQueryWhite()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsQueryWhite" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsQueryWhite" .XX "screen white" .SH Name .Na XcmsQueryWhite \(en obtain a color specification for screen white. .Nz .SH Synopsis .Sy Status XcmsQueryWhite\^(\^\f(CIccc\fP\^, \f(CItarget_format\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsColorFormat \f(CItarget_format\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .SH Arguments .IP \f(CIccc\fP 1i Specifies the color conversion context. Note that the CCC's Client White Point and White Point Adjustment procedures are ignored. .IP \f(CItarget_format\fP 1i Specifies the target color specification format. .ds Cs .IP \f(CIcolor_return\fP 1i Returns the color specification in the specified target format. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description The \f(CWXcmsQueryWhite()\fR function returns the color specification in the specified target format for full intensity red, green, and blue. The \f(CWXcmsQueryWhite()\fR function returns the color specification in the format specified by \f(CItarget_format\fP for screen white (i.e., full intensity red, green, and blue on the target \f(CWScreen\fP). .SH Structures The \f(CWXcmsColor\fP and \f(CWXcmsColorFormat\fP structures are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsQueryBlack()\fP\s+1, \s-1\fIXcmsQueryBlue()\fP\s+1, \s-1\fIXcmsQueryGreen()\fP\s+1, \s-1\fIXcmsQueryRed()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsScreenFreeProc" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsScreenFreeProc" .XX "screens:freeing per-screen data" .XX "Function Set:freeing per-screen data" .SH "Name" .Na XcmsScreenFreeProc \(en interface definition for the Function Set routine that frees the per-screen data. .Nz .SH "Synopsis" .Sy typedef void (*XcmsScreenFreeProc)(\f(CIscreenData\fP) .As XPointer \f(CIscreenData\fP; .Ae .SH "Arguments" .IP \f(CIscreenData\fP 1i Specifies the data to be freed. .SH Availability Release 5 and later. .SH Description \f(CWXcmsScreenFreeProc\fP is the definition for a procedure to be called to free the Function Set specific \f(CWscreenData\fP field stored in an \f(CWXcmsPerScrnInfo\fR structure. .SH "See Also" \s-1\fIXcmsFunctionSet\fP\s+1, \s-1\fIXcmsScreenInitProc\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsScreenInitProc" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsScreenInitProc" .XX "screens:obtaining and initializing per-screen information" .SH "Name" .Na XcmsScreenInitProc \(en interface specification for the Function Set routine that obtains and \%initializes per-screen information. .Nz .SH "Synopsis" .Sy typedef Status (*XcmsScreenInitProc)(\f(CIdisplay\fP, \f(CIscreen_number\fP, \f(CIscreen_info\fP) .As Display *\f(CIdisplay\fP; int \f(CIscreen_number\fP; XcmsPerScrnInfo *\f(CIscreen_info\fP; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIscreen_number\fP 1i Specifies the appropriate screen number on the host server. .IP \f(CIscreen_info\fP 1i Specifies the \f(CWXcmsPerScrnInfo\fR structure, which contains the per-screen information. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description The screen initialization function in the \f(CWXcmsFunctionSet\fR structure fetches the Color Characterization Data (device profile) for the specified screen, typically off properties on the screen's root window; then it initializes the specified \f(CWXcmsPerScrnInfo\fR structure. .XX "device profile" .XX "Color Characterization Data" If successful, the procedure fills in the \f(CWXcmsPerScrnInfo\fR structure as follows: .IP \(bu 3n It sets the \f(CWscreenData\fP member to the address of the created device profile data structure (contents known only by the function set). .IP \(bu 3n It next sets the \f(CWscreenWhitePoint\fP member. .IP \(bu 3n It next sets the \f(CWfunctionSet\fP member to the address of the \f(CWXcmsFunctionSet\fR structure. .IP \(bu 3n It then sets the state member to \f(CWXcmsInitSuccess\fR and finally returns \f(CWXcmsSuccess\fR. .LP If unsuccessful, the procedure sets the state member to \f(CWXcmsInitFailure\fR and returns \f(CWXcmsFailure\fR. .Nd 10 .SH "Structures" The \f(CWXcmsPerScrnInfo\fR structure contains: .\" Start marker code here .Ps 0 typedef struct _XcmsPerScrnInfo { XcmsColor screenWhitePoint; XPointer functionSet; XPointer screenData; unsigned char state; char pad[3]; } XcmsPerScrnInfo; .Pe .LP The \f(CWscreenWhitePoint\fP member specifies the white point inherent to the screen. The \f(CWfunctionSet\fP member specifies the appropriate Function Set. The \f(CWscreenData\fP member specifies the device profile. The \f(CWstate\fP member is set to one of the following: .IP \(bu 3n \f(CWXcmsInitNone\fR indicates initialization has not been previously attempted. .IP \(bu 3n \f(CWXcmsInitFailure\fR indicates initialization has been previously attempted but failed. .IP \(bu 3n \f(CWXcmsInitSuccess\fR indicates initialization has been previously attempted and succeeded. .SH "See Also" \s-1\fIXcmsFunctionSet\fP\s+1, \s-1\fIXcmsScreenFreeProc\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsScreenNumberOfCCC" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsScreenNumberOfCCC" .XX "ScreenNumberOfCCC" .XX "screens:numbers" .XX "CCC:screen number associated with" .SH "Name" .Na XcmsScreenNumberOfCCC, ScreenNumberOfCCC \(en screen number associated with the specified Color Conversion Context (CCC). .Nz .SH "Synopsis" .Sy int XcmsScreenNumberOfCCC(\f(CIccc\fP) .As XcmsCCC \f(CIccc\fP; ScreenNumberOfCCC(\f(CIccc\fP) XcmsCCC \f(CIccc\fP; .Ae .SH "Arguments" .IP \f(CIccc\fP 1i Specifies the color conversion context. .SH Returns The screen number. .SH Availability Release 5 and later. .SH Description \f(CWXcms\f(CWScreenNumberOfCCC()\fR and \f(CWScreenNumberOfCCC\fP both return the number of the screen associated with the specified CCC. .SH "See Also" \s-1\fIXcmsCCCOfColormap()\fP\s+1, \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsClientWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsConvertColors()\fP\s+1, \s-1\fIXcmsDefaultCCC()\fP\s+1, \s-1\fIXcmsDisplayOfCCC()\fP\s+1, \s-1\fIXcmsScreenWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsSetCCCOfColormap()\fP\s+1, \s-1\fIXcmsSetCompressionProc()\fP\s+1, \s-1\fIXcmsSetWhiteAdjustProc()\fP\s+1, \s-1\fIXcmsSetWhitePoint()\fP\s+1, \s-1\fIXcmsVisualOfCCC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "\s-2XcmsScreenWhitePointOfCCC\s+2" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsScreenWhitePointOfCCC" .XX "ScreenWhitePointOfCCC" .XX "white point:obtaining" .SH "Name" .Na XcmsScreenWhitePointOfCCC, ScreenWhitePointOfCCC \(en obtain the white point of the screen associated with a specified Color Conversion Context. .Nz .SH "Synopsis" .Sy XcmsColor *XcmsScreenWhitePointOfCCC(\f(CIccc\fP) .As XcmsCCC \f(CIccc\fP; .Ae .Sy ScreenWhitePointOfCCC(\f(CIccc\fP) .As XcmsCCC \f(CIccc\fP; .Ae .SH "Arguments" .IP \f(CIccc\fP 1i Specifies the color conversion context. .SH Returns The white point in an \f(CWXcmsColor\fP structure. See the \f(CWXcmsColor\fR reference page. .SH Availability Release 5 and later. .SH Description \f(CWXcms\f(CWScreenWhitePointOfCCC()\fP\fR and \f(CWScreenWhitePointOfCCC\fP both return the white point of the screen associated with the specified CCC. The returned \f(CWXcmsColor\fP structure must be treated as read-only. .SH "See Also" \s-1\fIXcmsCCCOfColormap()\fP\s+1, \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsClientWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsConvertColors()\fP\s+1, \s-1\fIXcmsDefaultCCC()\fP\s+1, \s-1\fIXcmsDisplayOfCCC()\fP\s+1, \s-1\fIXcmsScreenNumberOfCCC()\fP\s+1, \s-1\fIXcmsSetCompressionProc()\fP\s+1, \s-1\fIXcmsSetWhiteAdjustProc()\fP\s+1, \s-1\fIXcmsSetWhitePoint()\fP\s+1, \s-1\fIXcmsVisualOfCCC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsSetCCCOfColormap" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsSetCCCOfColormap" .XX "CCC:changing" .XX "colormaps:changing CCC associated with" .SH "Name" .Na XcmsSetCCCOfColormap \(en change the Color Conversion Context (CCC) associated with a colormap. .Nz .SH "Synopsis" .Sy XcmsCCC XcmsSetCCCOfColormap(\f(CIdisplay\fP, \f(CIcolormap\fP, \f(CIccc\fP) .As Display *\f(CIdisplay\fP; Colormap \f(CIcolormap\fP; XcmsCCC \f(CIccc\fP; .Ae .SH "Arguments" .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIcolormap\fP 1i Specifies the colormap. .IP \f(CIccc\fP 1i Specifies the color conversion context. .SH Returns The previous Color Conversion Context. .SH Availability Release 5 and later. .SH Description \f(CWXcmsSetCCCOfColormap()\fR changes the CCC associated with the specified colormap. It returns the CCC previously associated with the colormap. .LP If the previous CCC is not used again in the application, it should be freed by calling \f(CWXcmsFreeCCC()\fR. .SH "See Also" \s-1\fIXcmsCCCOfColormap()\fP\s+1, \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsFreeCCC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsSetCompressionProc" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsSetCompressionProc" .XX "gamut compression" .XX "CCC:changing gamut compression procedure in" .SH "Name" .Na XcmsSetCompressionProc \(en change the gamut compression procedure in a specified Color Conversion Context. .Nz .SH "Synopsis" .Sy XcmsCompressionProc XcmsSetCompressionProc(\f(CIccc\fP, \f(CIcompression_proc\fP, .br \f(CIclient_data\fP) .As XcmsCCC \f(CIccc\fP; XcmsCompressionProc \f(CIcompression_proc\fP; XPointer \f(CIclient_data\fP; .Ae .SH "Arguments" .IP \f(CIccc\fP 1i Specifies the color conversion context. .IP \f(CIcompression_proc\fP 1i Specifies the gamut compression procedure to apply when a color lies outside the screen's color gamut. If \f(CWNULL\fP, when functions using this CCC must convert a color specification to a device-dependent format and they encounter a color that lies outside the screen's color gamut, the functions will return \f(CWXcmsFailure\fR. .ds Cd the gamut compression procedure .IP \f(CIclient_data\fP 1i Specifies client data for \*(Cd or \f(CWNULL\fP. .SH Returns The previous compression procedure. .SH Availability Release 5 and later. .SH Description \f(CWXcmsSetCompressionProc()\fR function sets the gamut compression procedure and client data in the specified CCC with the newly specified procedure and client data, and returns the old procedure. .LP .XX "CIE L*a*b* coordinates" Gamut compression procedures provided with Xlib and intended for use with \f(CWXcmsSetCompressionProc()\fR are: .IP \(bu 3n .XX "XcmsCIELabClipL" \f(CWXcmsCIELabClipL\fR \(en In CIELAB color space, reduces or increases the CIE metric lightness (L*) of the color specification until it is within the screen's color gamut. No client data is necessary. .IP \(bu 3n .XX "XcmsCIELabClipab" \f(CWXcmsCIELabClipab\fR \(en In CIELAB color space while maintaining Psychometric Hue Angle, reduces the Psychometric Chroma of the color specification until it is within the screen's color gamut. No client data is necessary. .IP \(bu 3n .XX "XcmsCIELabClipLab" \f(CWXcmsCIELabClipLab\fR \(en In CIELAB color space while maintaining Psychometric Hue Angle, replaces the color specification with the CIELAB coordinate that falls within the screen's color gamut and whose vector to .ne 8 the original coordinates is the shortest attainable. No client data is necessary. .IP \(bu 3n .XX "XcmsCIELuvClipL" \f(CWXcmsCIELuvClipL\fR \(en In CIELUV color space, reduces or increases the CIE metric lightness (L*) of the color specification until it is within the screen's color gamut. No client data is necessary. .IP \(bu 3n .XX "XcmsCIELuvClipuv" \f(CWXcmsCIELuvClipuv\fR \(en In CIELUV color space while maintaining Psychometric Hue Angle, reduces the Psychometric Chroma of the color specification until it is within the screen's color gamut. No client data is necessary. .IP \(bu 3n .XX "XcmsCIELuvClipLuv" \f(CWXcmsCIELuvClipLuv\fR \(en In CIELUV color space while maintaining Psychometric Hue Angle, replaces the color specification with the CIELuv coordinate that falls within the screen's color gamut and whose vector to the original coordinates is the shortest attainable. No client data is necessary. .IP \(bu 3n .XX "XcmsTekHVCClipV" \f(CWXcmsTekHVCClipV\fR \(en In TekHVC color space, reduces or increases the Value of the color specification until it is within the screen's color gamut. No client data is necessary. .IP \(bu 3n .XX "XcmsTekHVCClipC" \f(CWXcmsTekHVCClipC\fR \(en In TekHVC color space while maintaining Hue, reduces the Chroma of the color specification until it is within the screen's color gamut. No client data is necessary. .IP \(bu 3n .XX "XcmsTekHVCClipVC" \f(CWXcmsTekHVCClipVC\fR \(en In TekHVC color space while maintaining Hue, replaces the color specification with the TekHVC coordinate that falls within the screen's color gamut and whose vector to the original coordinates is the shortest attainable. No client data is necessary. .SH "See Also" \s-1\fIXcmsCCCOfColormap()\fP\s+1, \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsConvertColors()\fP\s+1, \s-1\fIXcmsDefaultCCC()\fP\s+1, \s-1\fIXcmsScreenNumberOfCCC()\fP\s+1, \s-1\fIXcmsScreenWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsSetWhiteAdjustProc()\fP\s+1, \s-1\fIXcmsSetWhitePoint()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsSetWhiteAdjustProc" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsSetWhiteAdjustProc" .SH Name .Na .XX "white point:changing" .XX "CCC:changing white point adjustment procedure" XcmsSetWhiteAdjustProc \(en change the white point adjustment procedure in a specified Color Conversion Context. .Nz .SH Synopsis .Sy XcmsWhiteAdjustProc XcmsSetWhiteAdjustProc\^(\^\f(CIccc\fP\^, \f(CIwhite_adjust_proc\fP\^, .br \f(CIclient_data\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsWhiteAdjustProc \f(CIwhite_adjust_proc\fP\^; XPointer \f(CIclient_data\fP\^; .Ae .SH Arguments .IP \f(CIccc\fP 1i Specifies the color conversion context. .ds Cd the white point adjustment procedure .IP \f(CIclient_data\fP 1i Specifies client data for \*(Cd or \f(CWNULL\fP. .ds Co new Client White Point .IP \f(CIwhite_adjust_proc\fP 1i Specifies the white point adjustment procedure. .SH Returns The previous white point adjust procedure. .SH Availability Release 5 and later. .SH Description \f(CWXcmsSetWhiteAdjustProc()\fR sets a new white point adjustment procedure and client data in the specified CCC, and returns the old procedure. .LP White adustment procedures provided with Xlib and intended for use with \f(CWXcmsSetWhiteAdjustProc()\fR are: .IP \(bu 3n \f(CWXcmsCIELabWhiteShiftColors\fR \(en Uses the CIELAB color space to shift the chromatic character of colors by the chromatic displacement between the initial and target white point. No client data is necessary. .IP \(bu 3n \f(CWXcmsCIELuvWhiteShiftColors\fR \(en Uses the CIELUV color space to shift the chromatic character of colors by the chromatic displacement between the initial and target white point. No client data is necessary. .IP \(bu 3n \f(CWXcmsTekHVCWhiteShiftColors\fR \(en Uses the TekHVC color space to shift the chromatic character of colors by the chromatic displacement between the initial and target white point. No client data is necessary. .Nd 10 .SH "See Also" \s-1\fIXcmsCCCOfColormap()\fP\s+1, \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsClientWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsConvertColors()\fP\s+1, \s-1\fIXcmsDefaultCCC()\fP\s+1, \s-1\fIXcmsScreenWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsSetCompressionProc()\fP\s+1, \s-1\fIXcmsSetWhitePoint()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsSetWhitePoint" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsSetWhitePoint" .XX "white point:setting" .XX "CCC:white point, setting" .SH Name .Na XcmsSetWhitePoint \(en set the Client White Point of a Color Conversion Context. .Nz .SH Synopsis .Sy Status XcmsSetWhitePoint\^(\^\f(CIccc\fP\^, \f(CIcolor\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsColor *\f(CIcolor\fP\^; .Ae .SH Arguments .IP \f(CIccc\fP 1i Specifies the color conversion context. .ds Co new Client White Point .IP \f(CIcolor\fP 1i Specifies the \*(Co. .Nd 10 .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description \f(CWXcmsSetWhitePoint()\fP changes the Client White Point in the specified CCC. Note that the pixel member is ignored and that the color specification is left unchanged upon return. The format for the new white point must be \f(CWXcmsCIEXYZFormat\fP, \f(CWXcmsCIEuvYFormat\fP, \f(CWXcmsCIExyYFormat\fP, or \f(CWXcmsUndefinedFormat\fP. If \f(CIcolor\fP is \f(CWNULL\fP, this function sets the format component of the CCC's Client White Point specification to \f(CWXcmsUndefinedFormat\fP, indicating that the Client White Point is assumed to be the same as the Screen White Point. .SH "See Also" \s-1\fIXcmsCCCOfColormap()\fP\s+1, \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsClientWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsConvertColors()\fP\s+1, \s-1\fIXcmsDefaultCCC()\fP\s+1, \s-1\fIXcmsScreenWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsSetCompressionProc()\fP\s+1, \s-1\fIXcmsSetWhiteAdjustProc()\fP\s+1. .\"last line comment .TH XcmsSetWhit.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XcmsSetWhiteAdjustProc@XcmsSetWhiA .sp .5 XcmsSetWhitePoint@XcmsSetWhiB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsStoreColor" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsStoreColor" .XX "color cell:setting color of" .SH Name .Na XcmsStoreColor \(en store a specified color into a read/write colormap cell. .Nz .SH Synopsis .Sy Status XcmsStoreColor\^(\^\f(CIdisplay\fP, \f(CIcolormap\fP\^, \f(CIcolor\fP\^) .As Display *\f(CIdisplay\fP\^; Colormap \f(CIcolormap\fP\^; XcmsColor *\f(CIcolor\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIcolormap\fP 1i Specifies the colormap. .IP \f(CIcolor\fP 1i Specifies the color cell and the color to store. Values specified in this \f(CWXcmsColor\fR structure remain unchanged upon return. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description \f(CWXcmsStoreColor()\fR converts the color specified in the \f(CWXcmsColor\fR structure into RGB values and then uses this RGB specification in an \f(CWXColor\fR structure, whose three flags (\f(CWDoRed\fP, \f(CWDoGreen\fR, and \f(CWDoBlue\fR) are set, in a call to \f(CWXStoreColor()\fR to change the color cell specified by the pixel member of the \f(CWXcmsColor\fR structure. This pixel value must be a valid index for the specified colormap, and the color cell specified by the pixel value must be a read/write cell. If the pixel value is not a valid index, a \f(CWBadValue\fR error results. If the color cell is unallocated or is allocated read-only, a \f(CWBadAccess\fR error results. If the colormap is an installed map for its screen, the changes are visible immediately. .LP Note that \f(CWXStoreColor()\fP does not return a \f(CWStatus\fP therefore this function's return status can only indicate if a color conversion was successful and the call to \f(CWXStoreColor()\fP was made. \f(CWXcmsStoreColor()\fP returns \f(CWXcmsSuccess\fP if it succeeded in converting the color specification and called \f(CWXStoreColor()\fP. It returns \f(CWXcmsSuccessWithCompression\fP if it converted the requested device-independent color to the device RGB color space with gamut compression and completed the call to \f(CWXStoreColor()\fP. It returns \f(CWXcmsFailure\fP if it could not convert the specified color at all. To obtain the actual color stored, use \f(CWXcmsQueryColor()\fR. Due to the screen's hardware limitations or gamut compression, the color stored in the colormap may not be identical to the color specified. .Nd 10 .SH Errors .TP 1i \f(CWBadAccess\fR The specified colormap cell was read-only. .TP 1i \f(CWBadColor\fR The \f(CIcolormap\fP argument does not name a defined colormap. .TP 1i \f(CWBadValue\fR The specified pixel does not represent a valid color cell in the specified colormap. .Nd 20 .SH Structures The \f(CWXcmsColor\fP structure and \f(CWXcmsColorFormat\fP type are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsAllocColor()\fP\s+1, \s-1\fIXcmsAllocNamedColor()\fP\s+1, \s-1\fIXcmsLookupColor()\fP\s+1, \s-1\fIXcmsQueryColor()\fP\s+1, \s-1\fIXcmsQueryColors()\fP\s+1, \s-1\fIXcmsStoreColors()\fP\s+1, \s-1\fIXcmsStoreNamedColor\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXLookupColor()\fP\s+1, \s-1\fIXParseColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsStoreColors" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsStoreColors" .XX "color cell:setting color of" .SH Name .Na XcmsStoreColors \(en store the specified colors in read/write colormap cells. .Nz .SH Synopsis .Sy Status XcmsStoreColors\^(\^\f(CIdisplay\fP, \f(CIcolormap\fP\^, \f(CIcolors\fP\^, \f(CIncolors\fP\^, .br \f(CIcompression_flags_return\fP\^) .As Display *\f(CIdisplay\fP\^; Colormap \f(CIcolormap\fP\^; XcmsColor \f(CIcolors\fP\^[\^]\^; int \f(CIncolors\fP\^; Bool \f(CIcompression_flags_return\fP\^[\^]\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIcolormap\fP 1i Specifies the colormap. .IP \f(CIcolors\fP 1i Specifies an array of \f(CWXcmsColor\fR structures, each specifying a color cell and the color to store in that cell. Values specified in the array remain unchanged upon return. .IP \f(CIncolors\fP 1i Specifies the number of \f(CWXcmsColor\fR structures in the color specification array. .IP \f(CIcompression_flags_return\fP 1i Specifies an array of \f(CIncolors\fP \f(CWBoolean\fP values for returning compression status. If a non-\f(CWNULL\fP pointer is supplied, each element of the array is set to \f(CWTrue\fR if the corresponding color was compressed, and \f(CWFalse\fR otherwise. Pass \f(CWNULL\fP if the compression status is not useful. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description The \f(CWXcmsStoreColors()\fR function converts the colors specified in the array of \f(CWXcmsColor\fR structures into RGB values and then uses these RGB specifications in an \f(CWXColor\fR structures, whose three flags (\f(CWDoRed\fP, \f(CWDoGreen\fR, and \f(CWDoBlue\fR) are set, in a call to \f(CWXStoreColors()\fR to change the color cells specified by the pixel member of the corresponding \f(CWXcmsColor\fR structure. Each pixel value must be a valid index for the specified colormap, and the color cell specified by each pixel value must be a read/write cell. If a pixel value is not a valid index, a \f(CWBadValue\fR error results. If a color cell is unallocated or is allocated read-only, a \f(CWBadAccess\fR error results. If more than one pixel is in error, the one that gets reported is arbitrary. If the colormap is an installed map for its screen, the changes are visible immediately. .LP \f(CWXcmsStoreColors()\fP returns \f(CWXcmsSuccess\fP if it succeeded in converting the color specificatons and called \f(CWXStoreColors()\fP. It returns \f(CWXcmsSuccessWithCompression\fP if one or more of the requested device-independent colors required gamut compression during conversion to the device RGB color space, and it returns \f(CWXcmsFailure\fP if it could not convert one or more of the specified colors at all. Note that \f(CWXStoreColors()\fR has no return value; therefore, a \f(CWXcmsSuccess\fR return value from this function indicates that conversions to RGB succeeded and the call to \f(CWXStoreColors()\fR was made. To obtain the actual colors stored, use \f(CWXcmsQueryColors()\fR. Due to the screen's hardware limitations or gamut compression, the colors stored in the colormap may not be identical to the colors specified. .SH Errors .TP 1i \f(CWBadAccess\fR A specified colormap cell was read-only. .TP 1i \f(CWBadColor\fR The \f(CIcolormap\fP argument does not name a defined Colormap. .TP 1i \f(CWBadValue\fR The specified pixel does not represent a valid color cell in the specified colormap. .SH Structures The \f(CWXcmsColor\fP and \f(CWXcmsColorFormat\fP structures are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsAllocColor()\fP\s+1, \s-1\fIXcmsAllocNamedColor()\fP\s+1, \s-1\fIXcmsLookupColor()\fP\s+1, \s-1\fIXcmsQueryColor()\fP\s+1, \s-1\fIXcmsQueryColors()\fP\s+1, \s-1\fIXcmsStoreColor()\fP\s+1, \s-1\fIXcmsStoreNamedColor\fP\s+1, \s-1\fIXAllocColor()\fP\s+1, \s-1\fIXAllocNamedColor()\fP\s+1, \s-1\fIXLookupColor()\fP\s+1, \s-1\fIXParseColor()\fP\s+1, \s-1\fIXQueryColor()\fP\s+1, \s-1\fIXQueryColors()\fP\s+1, \s-1\fIXStoreColor()\fP\s+1, \s-1\fIXStoreColors()\fP\s+1. .\"last line comment .TH XcmsStoreCo.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XcmsStoreColor@XcmsStoreCA .sp .5 XcmsStoreColors@XcmsStoreCB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsTekHVCQueryMaxC" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsTekHVCQueryMaxC" .XX "TekHVC:finding maximum Chroma for" .XX "Hue:finding maximum Chroma for" .XX "Value:finding maximum Chroma for" .SH Name .Na XcmsTekHVCQueryMaxC \(en find the maximum Chroma for a given TekHVC Hue and Value. .Nz .SH Synopsis .Sy Status XcmsTekHVCQueryMaxC\^(\^\f(CIccc\fP\^, \f(CIhue\fP\^, \f(CIvalue\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsFloat \f(CIhue\fP\^; XcmsFloat \f(CIvalue\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .SH Arguments .IP \f(CIccc\fP 1i Specifies the color conversion context. Note that the CCC's Client White Point and White Point Adjustment procedures are ignored. .IP \f(CIhue\fP 1i Specifies the Hue at which to find the maximum Chroma. .IP \f(CIvalue\fP 1i Specifies the Value at which to find the maximum Chroma. .IP \f(CIcolor_return\fP 1i Returns the maximum Chroma along with the actual Hue and Value. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description \f(CWXcmsTekHVCQueryMaxC()\fR determines the maximum displayable Chroma for a given Hue and Value. The maximum Chroma is returned in the \f(CIcolor_return\fP argument, along with the actual Hue and Value at which it occurs. Note that because of gamut compression or hardware limitations, the returned Hue and Value may differ from those specified by the \f(CIhue\fP and \f(CIvalue\fP arguments. .SH Structures The \f(CWXcmsColor\fP structure and \f(CWXcmsColorFormat\fP type are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsTekHVCQueryMaxV()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxVC()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxVSamples()\fP\s+1, \s-1\fIXcmsTekHVCQueryMinV()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsTekHVCQueryMaxV" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsTekHVCQueryMaxV" .XX "TekHVC:finding maximum Value for" .XX "Hue:finding maximum Value for" .XX "Chroma:finding maximum Value for" .SH Name .Na XcmsTekHVCQueryMaxV \(en find the maximum Value for a given TekHVC Hue and Chroma. .Nz .SH Synopsis .Sy Status XcmsTekHVCQueryMaxV\^(\^\f(CIccc\fP\^, \f(CIhue\fP\^, \f(CIchroma\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsFloat \f(CIhue\fP\^; XcmsFloat \f(CIchroma\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .SH Arguments .IP \f(CIccc\fP 1i Specifies the color conversion context. Note that the CCC's Client White Point and White Point Adjustment procedures are ignored. .IP \f(CIhue\fP 1i Specifies the Hue at which to find the maximum Value. .IP \f(CIchroma\fP 1i Specifies the chroma at which to find maximum Value. .IP \f(CIcolor_return\fP 1i Returns the maximum Value along with the Hue and Chroma. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description \f(CWXcmsTekHVCQueryMaxV()\fR determines the maximum displayable Value for a given Hue and Chroma. The maximum Value is returned in the \f(CIcolor_return\fP argument along with the actual Hue and Chroma at which it occurs. Note that because of gamut compression or hardware limitations, the returned Hue and Chroma may differ from those specified by the \f(CIhue\fP and \f(CIchroma\fP arguments. .SH Structures The \f(CWXcmsColor\fP structure and \f(CWXcmsColorFormat\fP type are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsTekHVCQueryMaxC()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxVC()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxVSamples()\fP\s+1, \s-1\fIXcmsTekHVCQueryMinV()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsTekHVCQueryMaxVC" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsTekHVCQueryMaxVC" .XX "Chroma:finding maximum Value for" .SH Name .Na XcmsTekHVCQueryMaxVC \(en find the maximum Chroma and the Value at which it occurs .br given a TekHVC Hue. .Nz .SH Synopsis .Sy Status XcmsTekHVCQueryMaxVC\^(\^\f(CIccc\fP\^, \f(CIhue\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsFloat \f(CIhue\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .SH Arguments .IP \f(CIccc\fP 1i Specifies the color conversion context. Note that the CCC's Client White Point and White Point Adjustment procedures are ignored. .IP \f(CIhue\fP 1i Specifies the Hue at which to find the maximum Chroma. .IP \f(CIcolor_return\fP 1i Returns the maximum Chroma, the Value at which that maximum Chroma is reached and actual Hue. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description \f(CWXcmsTekHVCQueryMaxVC()\fR determines the maximum displayable Chroma for a given Hue, and the Value at which that Chroma is reached. The Chroma and Value are returned in the \f(CIcolor_return\fP argument along with the actual Hue at which they occur. Note that because of gamut compression or hardware limitations, the returned Hue may differ from that specified by the \f(CIhue\fP argument. .SH Structures The \f(CWXcmsColor\fP structure and \f(CWXcmsColorFormat\fP type are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsTekHVCQueryMaxC()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxV()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxVSamples()\fP\s+1, \s-1\fIXcmsTekHVCQueryMinV()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "\s-3XcmsTekHVCQueryMaxVSamples\s+3" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsTekHVCQueryMaxVSamples" .XX "TekHVC:returning boundaries of" .SH Name .Na XcmsTekHVCQueryMaxVSamples \(en return the boundaries of the TekHVC gamut for a .br given Hue. .Nz .SH Synopsis .Sy Status XcmsTekHVCQueryMaxVSamples\^(\^\f(CIccc\fP\^, \f(CIhue\fP\^, \f(CIcolors_return\fP\^, \f(CInsamples\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsFloat \f(CIhue\fP\^; XcmsColor \f(CIcolors_return[]\fP\^; unsigned int \f(CInsamples\fP\^; .Ae .SH Arguments .IP \f(CIccc\fP 1i Specifies the color conversion context. Note that the CCC's Client White Point and White Point Adjustment procedures are ignored. .ds Hu in which to find the maximum Chroma (MaxC and MaxVC), \ maximum Value (MaxV), the maximum Chroma/Value samples (MaxVSamples), \ or the minimum Value (MinL) .IP \f(CIhue\fP 1i Specifies the Hue at which to find the maximum Chroma/Value samples. .IP \f(CIcolors_return\fP 1i Specifies an array of \f(CInsamples\fP \f(CWXcmsColor\fP structures into which the returned color specifications will be stored. .IP \f(CInsamples\fP 1i Specifies the number of samples. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description For the specified Hue, \f(CWXcmsTekHVCQueryMaxVSamples()\fP partitions the legal values of Chroma into \f(CInsamples\fP samples, and queries the maximum Value for the Hue and each Chroma sample. The resulting values are stored into the elements of the \f(CIcolors_return\fP array. This function can be used to plot the upper boundary of the TekHVC device gamut for a given Hue. .SH Structures The \f(CWXcmsColor\fP structure and \f(CWXcmsColorFormat\fP type are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsTekHVCQueryMaxC()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxV()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxVC()\fP\s+1, \s-1\fIXcmsTekHVCQueryMinV()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsTekHVCQueryMinV" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsTekHVCQueryMinV" .XX "TekHVC:coordinates, obtaining" .SH Name .Na XcmsTekHVCQueryMinV \(en find the minimum Value for a given TekHVC Hue and Chroma. .Nz .SH Synopsis .Sy Status XcmsTekHVCQueryMinV\^(\^\f(CIccc\fP\^, \f(CIhue\fP\^, \f(CIchroma\fP\^, \f(CIcolor_return\fP\^) .As XcmsCCC \f(CIccc\fP\^; XcmsFloat \f(CIhue\fP\^; XcmsFloat \f(CIchroma\fP\^; XcmsColor *\f(CIcolor_return\fP\^; .Ae .SH Arguments .IP \f(CIccc\fP 1i Specifies the color conversion context. Note that the CCC's Client White Point and White Point Adjustment procedures are ignored. .IP \f(CIhue\fP 1i Specifies the Hue at which to find the minimum Value. .IP \f(CIchroma\fP 1i Specifies the chroma at which to find the minimum Value. .IP \f(CIcolor_return\fP 1i Returns the minimum Value and the actual Hue and Chroma. The white point associated with the returned color specification is the Screen White Point. The value returned in the pixel member is undefined. .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description \f(CWXcmsTekHVCQueryMinV()\fR determines the minimum displayable Value for a given Hue and Chroma. The minimum Value is returned in the \f(CIcolor_return\fP argument along with the actual Hue and Chroma at which it occurs. Note that because of gamut compression or hardware limitations, the returned Hue and Chroma may differ from those specified by the \f(CIhue\fP and \f(CIchroma\fP arguments. .SH Structures The \f(CWXcmsColor\fP structure and \f(CWXcmsColorFormat\fP type are shown on the \f(CWXcmsColor\fP reference page. .SH "See Also" \s-1\fIXcmsTekHVCQueryMaxC()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxV()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxVC()\fP\s+1, \s-1\fIXcmsTekHVCQueryMaxVSamples()\fP\s+1. .\"last line comment .TH XcmsTekHVCQ.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XcmsTekHVCQueryMaxC@XcmsTekHVCA .sp .5 XcmsTekHVCQueryMaxV@XcmsTekHVCB .sp .5 XcmsTekHVCQueryMaxVC@XcmsTekHVCC .sp .5 XcmsTekHVCQueryMaxVSamples@XcmsTekHVCD .sp .5 XcmsTekHVCQueryMinV@XcmsTekHVCE .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsVisualOfCCC" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsVisualOfCCC" .XX "VisualOfCCC" .XX "visuals:associated with CCC" .XX "CCC:visual associated with" .SH "Name" .Na XcmsVisualOfCCC, VisualOfCCC \(en return the visual associated with a specified Color Conversion Context (CCC). .Nz .SH "Synopsis" .Sy Visual *XcmsVisualOfCCC(\f(CIccc\fP) .As XcmsCCC \f(CIccc\fP; .Ae .Sy VisualOfCCC(\f(CIccc\fP) .As XcmsCCC \f(CIccc\fP; .Ae .SH "Arguments" .IP \f(CIccc\fP 1i Specifies the color conversion context. .SH Returns The visual. .SH Availability Release 5 and later. .SH Description \f(CWXcms\f(CWVisualOfCCC()\fR and \f(CWVisualOfCCC\fP both return the visual associated with the specified CCC. .SH "See Also" \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsDefaultCCC()\fP\s+1, \s-1\fIXcmsClientWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsCCCOfColormap()\fP\s+1, \s-1\fIXcmsCreateCCC()\fP\s+1, \s-1\fIXcmsClientWhitePointOfCCC()\fP\s+1, \s-1\fIXcmsDefaultCCC()\fP\s+1, \s-1\fIXcmsDisplayOfCCC()\fP\s+1, \s-1\fIXcmsScreenNumberOfCCC()\fP\s+1, \s-1\fIXcmsScreenWhitePointOfCCC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XcmsWhiteAdjustProc" "Xlib \- Device-independent Color" .ds ]W Xlib Reference Manual .XX "XcmsWhiteAdjustProc" .XX "white point:adjustment procedure" .SH "Name" .Na XcmsWhiteAdjustProc \(en interface definition for the white point adjustment procedure. .Nz .SH "Synopsis" .Sy typedef Status (*XcmsWhiteAdjustProc)(\f(CIccc\fP, \f(CIinitial_white_point\fP, .br \f(CItarget_white_point\fP, \f(CItarget_format\fP, \f(CIcolors_in_out\fP, \f(CIncolors\fP, .br \f(CIcompression_flags_return\fP) .As XcmsCCC \f(CIccc\fP; XcmsColor *\f(CIinitial_white_point\fP; XcmsColor *\f(CItarget_white_point\fP; XcmsColorFormat \f(CItarget_format\fP; XcmsColor \f(CIcolors_in_out[]\fP; unsigned int \f(CIncolors\fP; Bool \f(CIcompression_flags_return[]\fP; .Ae .SH "Arguments" .IP \f(CIccc\fP 1i Specifies the color conversion context. .IP \f(CIinitial_white_point\fP 1i Specifies the initial white point. .IP \f(CItarget_white_point\fP 1i Specifies the target white point. .IP \f(CItarget_format\fP 1i Specifies the target color specification format. .IP \f(CIcolors_in_out\fP 1i Specifies an array of color specifications. Pixel members are ignored and remain unchanged upon return. .IP \f(CIncolors\fP 1i Specifies the number of \f(CWXcmsColor\fR structures in the color specification array. .IP \f(CIcompression_flags_return\fP 1i Specifies an array of Boolean values (or \f(CWNULL\fP) for returned information that indicates if the color was compressed. For example, if this routine returns \f(CWXcmsSuccessWithCompression\fR and \f(CWcompression_flags_\p return[3]\fP is \f(CWTrue\fR, this indicates that the fourth color specified in the color specification array was compressed. If the calling routine is not interested in knowing which color was compressed when the return value is \f(CWXcmsSuccessWithCompression\fR, it is allowed to pass a \f(CWNULL\fP for this argument. .Nd 10 .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .SH Description \f(CWXcmsWhiteAdjustProc\fR is a function that takes the color specifications, whose associated white point is \f(CIinitial_white_point\fP, .hw target and modifies them for the \f(CItarget_white_point\fP; returning the color specifications in the format specified by \f(CItarget_format\fP. .SH "See Also" \s-1\fIXcmsSetWhiteAdjustProc()\fP\s+1. .\"last line comment .TH XdbeAllocateBackBufferName 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeAllocateBackBufferName - allocates a DBE buffer. .SH SYNOPSIS #include XdbeBackBuffer XdbeAllocateBackBufferName( Display *dpy, Window window, XdbeSwapAction swap_action) .SH DESCRIPTION This function returns a drawable ID used to refer to the back buffer of the specified window. The swap_action is a hint to indicate the swap action that will likely be used in subsequent calls to .B XdbeSwapBuffers(). The actual swap action used in calls to .B XdbeSwapBuffers() does not have to be the same as the swap_action passed to this function, though clients are encouraged to provide accurate information whenever possible. .SH ERRORS .IP BadAlloc .IP BadIDChoice .IP BadMatch The specified window is not an InputOutput window or its visual does not support DBE. .IP BadValue An invalid swap action was specified. .IP BadWindow An invalid window was specified. .SH SEE ALSO DBE, .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .TH XdbeAllocateBackBufferName 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeAllocateBackBufferName - allocates a DBE buffer. .SH SYNOPSIS #include XdbeBackBuffer XdbeAllocateBackBufferName( Display *dpy, Window window, XdbeSwapAction swap_action) .SH DESCRIPTION This function returns a drawable ID used to refer to the back buffer of the specified window. The swap_action is a hint to indicate the swap action that will likely be used in subsequent calls to .B XdbeSwapBuffers(). The actual swap action used in calls to .B XdbeSwapBuffers() does not have to be the same as the swap_action passed to this function, though clients are encouraged to provide accurate information whenever possible. .SH ERRORS .IP BadAlloc .IP BadIDChoice .IP BadMatch The specified window is not an InputOutput window or its visual does not support DBE. .IP BadValue An invalid swap action was specified. .IP BadWindow An invalid window was specified. .SH SEE ALSO DBE, .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .TH DBE 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeBeginIdiom - marks the beginning of a DBE idiom sequence. .SH SYNOPSIS #include Status XdbeBeginIdiom( Display *dpy) .SH DESCRIPTION This function marks the beginning of an idiom sequence. .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .TH DBE 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeBeginIdiom - marks the beginning of a DBE idiom sequence. .SH SYNOPSIS #include Status XdbeBeginIdiom( Display *dpy) .SH DESCRIPTION This function marks the beginning of an idiom sequence. .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .TH XdbeDeallocateBackBufferName 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeDeallocateBackBufferName - frees a DBE buffer. .SH SYNOPSIS #include Status XdbeDeallocateBackBufferName( Display *dpy, XdbeBackBuffer buffer) .SH DESCRIPTION This function frees a drawable ID, buffer, that was obtained via .B XdbeAllocateBackBufferName(). The buffer must be a valid name for the back buffer of a window, or a protocol error results. .SH ERRORS .IP BadBuffer The specified buffer is not associated with a window. .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .TH XdbeDeallocateBackBufferName 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeDeallocateBackBufferName - frees a DBE buffer. .SH SYNOPSIS #include Status XdbeDeallocateBackBufferName( Display *dpy, XdbeBackBuffer buffer) .SH DESCRIPTION This function frees a drawable ID, buffer, that was obtained via .B XdbeAllocateBackBufferName(). The buffer must be a valid name for the back buffer of a window, or a protocol error results. .SH ERRORS .IP BadBuffer The specified buffer is not associated with a window. .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .TH XdbeEndIdiom 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeEndIdiom - marks the end of a DBE idiom sequence. .SH SYNOPSIS #include Status XdbeEndIdiom( Display *dpy) .SH DESCRIPTION This function marks the end of an idiom sequence. .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .TH XdbeEndIdiom 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeEndIdiom - marks the end of a DBE idiom sequence. .SH SYNOPSIS #include Status XdbeEndIdiom( Display *dpy) .SH DESCRIPTION This function marks the end of an idiom sequence. .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .TH XdbeFreeVisualInfo 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeFreeVisualInfo - frees information returned by .B XdbeGetVisualInfo(). .SH SYNOPSIS #include void XdbeFreeVisualInfo( XdbeScreenVisualInfo *visual_info) .SH DESCRIPTION This function frees the list of XdbeScreenVisualInfo returned by the function .B XdbeGetVisualInfo(). .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .TH XdbeFreeVisualInfo 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeFreeVisualInfo - frees information returned by .B XdbeGetVisualInfo(). .SH SYNOPSIS #include void XdbeFreeVisualInfo( XdbeScreenVisualInfo *visual_info) .SH DESCRIPTION This function frees the list of XdbeScreenVisualInfo returned by the function .B XdbeGetVisualInfo(). .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .TH XdbeGetBackBufferAttributes 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeGetBackBufferAttributes - returns attributes of a DBE buffer. .SH SYNOPSIS #include XdbeBackBufferAttributes *XdbeGetBackBufferAttributes( Display *dpy, XdbeBackBuffer buffer) .SH DESCRIPTION This function returns the attributes associated with the specified buffer. The .I XdbeBackBufferAttributes structure has the following fields: .RS Window window window that buffer belongs to .RE If buffer is not a valid .I XdbeBackBuffer, window returns None. The returned .I XdbeBackBufferAttributes structure can be freed with the Xlib function .B Xfree(). .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .TH XdbeGetBackBufferAttributes 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeGetBackBufferAttributes - returns attributes of a DBE buffer. .SH SYNOPSIS #include XdbeBackBufferAttributes *XdbeGetBackBufferAttributes( Display *dpy, XdbeBackBuffer buffer) .SH DESCRIPTION This function returns the attributes associated with the specified buffer. The .I XdbeBackBufferAttributes structure has the following fields: .RS Window window window that buffer belongs to .RE If buffer is not a valid .I XdbeBackBuffer, window returns None. The returned .I XdbeBackBufferAttributes structure can be freed with the Xlib function .B Xfree(). .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .TH XdbeGetVisualInfo 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeGetVisualInfo .SH SYNOPSIS #include XdbeScreenVisualInfo *XdbeGetVisualInfo( Display *dpy, Drawable *screen_specifiers, int *num_screens) .SH DESCRIPTION This function returns information about which visuals support double buffering. The argument .I num_screens specifies how many elements there are in the .I screen_specifiers list. Each drawable in .I screen_specifiers designates a screen for which the supported visuals are being requested. If .I num_screens is zero, information for all screens is requested. In this case, upon return from this function, .I num_screens will be set to the number of screens that were found. If an error occurs, this function returns NULL, else it returns a pointer to a list of .I XdbeScreenVisualInfo structures of length .I num_screens. The nth element in the returned list corresponds to the nth drawable in the .I screen_specifiers list, unless .I num_screens was passed in with the value zero, in which case the nth element in the returned list corresponds to the nth screen of the server, starting with screen zero. The .I XdbeScreenVisualInfo structure has the following fields: int count XdbeVisualInfo *visinfo .I count specifies the number of items in .I visinfo. .I visinfo specifies a list of visuals, depths, and performance hints for this screen. The .I XdbeVisualInfo structure has the following fields: VisualID visual int depth int perflevel .I visual specifies one visual ID that supports double-buffering. .I depth specifies the depth of the visual. .I perflevel is a performance hint. The only operation defined on a .I perflevel is comparison to a .I perflevel of another visual on the same screen. The visual having the higher .I perflevel is likely to have better double-buffering graphics performance than the visual having the lower .I perflevel. Nothing can be deduced from the following: the magnitude of the difference of two .I perflevels, a .I perflevel value in isolation, or comparing .I perflevels from different servers. .SH ERRORS .IP BadDrawable One or more values passed in .I screen_specifiers is not a valid drawable. .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .TH XdbeGetVisualInfo 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeGetVisualInfo .SH SYNOPSIS #include XdbeScreenVisualInfo *XdbeGetVisualInfo( Display *dpy, Drawable *screen_specifiers, int *num_screens) .SH DESCRIPTION This function returns information about which visuals support double buffering. The argument .I num_screens specifies how many elements there are in the .I screen_specifiers list. Each drawable in .I screen_specifiers designates a screen for which the supported visuals are being requested. If .I num_screens is zero, information for all screens is requested. In this case, upon return from this function, .I num_screens will be set to the number of screens that were found. If an error occurs, this function returns NULL, else it returns a pointer to a list of .I XdbeScreenVisualInfo structures of length .I num_screens. The nth element in the returned list corresponds to the nth drawable in the .I screen_specifiers list, unless .I num_screens was passed in with the value zero, in which case the nth element in the returned list corresponds to the nth screen of the server, starting with screen zero. The .I XdbeScreenVisualInfo structure has the following fields: int count XdbeVisualInfo *visinfo .I count specifies the number of items in .I visinfo. .I visinfo specifies a list of visuals, depths, and performance hints for this screen. The .I XdbeVisualInfo structure has the following fields: VisualID visual int depth int perflevel .I visual specifies one visual ID that supports double-buffering. .I depth specifies the depth of the visual. .I perflevel is a performance hint. The only operation defined on a .I perflevel is comparison to a .I perflevel of another visual on the same screen. The visual having the higher .I perflevel is likely to have better double-buffering graphics performance than the visual having the lower .I perflevel. Nothing can be deduced from the following: the magnitude of the difference of two .I perflevels, a .I perflevel value in isolation, or comparing .I perflevels from different servers. .SH ERRORS .IP BadDrawable One or more values passed in .I screen_specifiers is not a valid drawable. .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeQueryExtension(), .I XdbeSwapBuffers(). .TH XdbeQueryExtension 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeQueryExtension - returns the version of DBE supported by the server. .SH SYNOPSIS #include Status XdbeQueryExtension( Display *dpy, int *major_version_return, int *minor_version_return) .SH DESCRIPTION Sets .I major_version_return and .I minor_version_return to the major and minor DBE protocol version supported by the server. If the DBE library is compatible with the version returned by the server, this function returns non-zero. If .I dpy does not support the DBE extension, or if there was an error during communication with the server, or if the server and library protocol versions are incompatible, this function returns zero. No other Xdbe functions may be called before this function. If a client violates this rule, the effects of all subsequent Xdbe calls that it makes are undefined. .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeSwapBuffers(). .TH XdbeQueryExtension 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeQueryExtension - returns the version of DBE supported by the server. .SH SYNOPSIS #include Status XdbeQueryExtension( Display *dpy, int *major_version_return, int *minor_version_return) .SH DESCRIPTION Sets .I major_version_return and .I minor_version_return to the major and minor DBE protocol version supported by the server. If the DBE library is compatible with the version returned by the server, this function returns non-zero. If .I dpy does not support the DBE extension, or if there was an error during communication with the server, or if the server and library protocol versions are incompatible, this function returns zero. No other Xdbe functions may be called before this function. If a client violates this rule, the effects of all subsequent Xdbe calls that it makes are undefined. .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeSwapBuffers(). .TH XdbeSwapBuffers 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeSwapBuffers - swaps front and back DBE buffers. .SH SYNOPSIS #include Status XdbeSwapBuffers( Display *dpy, XdbeSwapInfo *swap_info, int num_windows) .SH DESCRIPTION This function swaps the front and back buffers for a list of windows. The argument .I num_windows specifies how many windows are to have their buffers swapped; it is the number of elements in the .I swap_info array. The argument .I swap_info specifies the information needed per window to do the swap. The .I XdbeSwapInfo structure has the following fields: Window swap_window XdbeSwapAction swap_action .I swap_window specifies the window for which to swap buffers. .I swap_action specifies the swap action to use for this .I swap_window. .I swap_action determines what will happen to the new back buffer of the .I swap_window it is paired with in the list in addition to making the old back buffer become visible. The defined actions are as follows: .IP XdbeUndefined The contents of the new back buffer become undefined. This may be the most efficient action since it allows the implementation to discard the contents of the buffer if it needs to. .IP XdbeBackground The unobscured region of the new back buffer will be tiled with the window background. The background action allows devices to use a fast clear capability during a swap. .IP XdbeUntouched The unobscured region of the new back buffer will be unmodified by the swap. .IP XdbeCopied The unobscured region of the new back buffer will be the contents of the old back buffer .SH ERRORS .IP BadMatch A non-double-buffered window was specififed or a window was specified twice. .IP BadWindow An invalid window was specified. .IP BadValue An invalid swap action was specified. .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(). .TH XdbeSwapBuffers 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 9.07 June 1995 .SH NAME XdbeSwapBuffers - swaps front and back DBE buffers. .SH SYNOPSIS #include Status XdbeSwapBuffers( Display *dpy, XdbeSwapInfo *swap_info, int num_windows) .SH DESCRIPTION This function swaps the front and back buffers for a list of windows. The argument .I num_windows specifies how many windows are to have their buffers swapped; it is the number of elements in the .I swap_info array. The argument .I swap_info specifies the information needed per window to do the swap. The .I XdbeSwapInfo structure has the following fields: Window swap_window XdbeSwapAction swap_action .I swap_window specifies the window for which to swap buffers. .I swap_action specifies the swap action to use for this .I swap_window. .I swap_action determines what will happen to the new back buffer of the .I swap_window it is paired with in the list in addition to making the old back buffer become visible. The defined actions are as follows: .IP XdbeUndefined The contents of the new back buffer become undefined. This may be the most efficient action since it allows the implementation to discard the contents of the buffer if it needs to. .IP XdbeBackground The unobscured region of the new back buffer will be tiled with the window background. The background action allows devices to use a fast clear capability during a swap. .IP XdbeUntouched The unobscured region of the new back buffer will be unmodified by the swap. .IP XdbeCopied The unobscured region of the new back buffer will be the contents of the old back buffer .SH ERRORS .IP BadMatch A non-double-buffered window was specififed or a window was specified twice. .IP BadWindow An invalid window was specified. .IP BadValue An invalid swap action was specified. .SH SEE ALSO DBE, .I XdbeAllocateBackBufferName(), .I XdbeBeginIdiom(), .I XdbeDeallocateBackBufferName(), .I XdbeEndIdiom(), .I XdbeFreeVisualInfo(), .I XdbeGetBackBufferAttributes(), .I XdbeGetVisualInfo(), .I XdbeQueryExtension(). ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmActivateProtocol 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmActivateProtocol\fP \- A VendorShell function that activates a protocol .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu void XmActivateProtocol (\fBshell, property, protocol\fI) .ta .5i 1.5i .nf Widget \fBshell\fI; Atom \fBproperty\fI; Atom \fBprotocol\fI; .sp \n(PDu void XmActivateWMProtocol (\fBshell, protocol\fI) Widget \fBshell\fI; Atom \fBprotocol\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmActivateProtocol\fP activates a protocol. It updates the handlers and the \fBproperty\fP if the \fBshell\fP is realized. It is sometimes useful to allow a protocol's state information (callback lists, and so on) to persist, even though the client may choose to temporarily resign from the interaction. This is supported by allowing a \fBprotocol\fP to be in one of two states: active or inactive. If the \fBprotocol\fP is active and the \fBshell\fP is realized, .ne 5 the \fBproperty\fP contains the \fBprotocol\fP \fIAtom\fP. If the \fBprotocol\fP is inactive, the \fIAtom\fP is not present in the \fBproperty\fP. .PP \fIXmActivateWMProtocol\fP is a convenience interface. It calls \fIXmActivateProtocol\fP with the property value set to the atom returned by interning \fIWM_PROTOCOLS\fP. .IP "\fBshell\fP" Specifies the widget with which the protocol property is associated. .IP "\fBproperty\fP" Specifies the protocol property. .IP "\fBprotocol\fP" Specifies the protocol \fIAtom\fP (or an \fIint\fP type cast to \fIAtom\fP). .PP For a complete definition of VendorShell and its associated resources, see \fIVendorShell(3X)\fP. .SH RELATED INFORMATION .na \fIVendorShell(3X)\fP, \fIXmActivateWMProtocol(3X)\fP and \fIXmInternAtom(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmActivateWMProtocol 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmActivateWMProtocol\fP \- A VendorShell convenience interface that activates a protocol .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu void XmActivateWMProtocol (\fBshell, protocol\fI) .ta .5i 1.5i .nf Widget \fBshell\fI; Atom \fBprotocol\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmActivateWMProtocol\fP is a convenience interface. It calls \fIXmActivateProtocol\fP with the property value set to the atom returned by interning \fIWM_PROTOCOLS\fP. .IP "\fBshell\fP" Specifies the widget with which the protocol property is associated. .IP "\fBprotocol\fP" Specifies the protocol \fIAtom\fP (or an \fIint\fP type cast to \fIAtom\fP). .PP For a complete definition of VendorShell and its associated resources, see \fIVendorShell(3X)\fP. .SH RELATED INFORMATION .na \fIVendorShell(3X)\fP, \fIXmActivateProtocol(3X)\fP, and \fIXmInternAtom(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmAddProtocolCallback 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmAddProtocolCallback\fP \- A VendorShell function that adds client callbacks for a protocol .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu void XmAddProtocolCallback (\fBshell, property, protocol, callback, closure\fI) .ta .5i 1.75i .nf Widget \fBshell\fI; Atom \fBproperty\fI; Atom \fBprotocol\fI; XtCallbackProc \fBcallback\fI; XtPointer \fBclosure\fI; .sp \n(PDu void XmAddWMProtocolCallback (\fBshell, protocol, callback, closure\fI) Widget \fBshell\fI; Atom \fBprotocol\fI; XtCallbackProc \fBcallback\fI; XtPointer \fBclosure\fI; .wH .fi .ne 10 .iE .sE .SH DESCRIPTION .fi \fIXmAddProtocolCallback\fP adds client callbacks for a protocol. It checks if the protocol is registered, and if it is not, calls \fIXmAddProtocols\fP. It then adds the callback to the internal list. These callbacks are called when the corresponding client message is received. .PP \fIXmAddWMProtocolCallback\fP is a convenience interface. It calls \fIXmAddProtocolCallback\fP with the property value set to the atom returned by interning \fIWM_PROTOCOLS\fP. .IP "\fBshell\fP" Specifies the widget with which the protocol property is associated. .IP "\fBproperty\fP" Specifies the protocol property. .IP "\fBprotocol\fP" Specifies the protocol \fIAtom\fP (or an \fIint\fP type cast to \fIAtom\fP). .IP "\fBcallback\fP" Specifies the procedure to call when a protocol message is received. .IP "\fBclosure\fP" Specifies the client data to be passed to the callback when it is invoked. .PP For a complete definition of VendorShell and its associated resources, see \fIVendorShell(3X)\fP. .SH RELATED INFORMATION .na \fIVendorShell(3X)\fP, \fIXmAddProtocols(3X)\fP, \fIXmAddWMProtocolCallback(3X)\fP, and \fIXmInternAtom(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmAddProtocols 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmAddProtocols\fP \- A VendorShell function that adds the protocols to the protocol manager and allocates the internal tables .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu void XmAddProtocols (\fBshell, property, protocols, num_protocols\fI) .ta .5i 1.5i .nf Widget \fBshell\fI; Atom \fBproperty\fI; Atom \fB* protocols\fI; Cardinal \fBnum_protocols\fI; .sp \n(PDu void XmAddWMProtocols (\fBshell, protocols, num_protocols\fI) .ta .5i 1.5i .nf Widget \fBshell\fI; Atom \fB* protocols\fI; Cardinal \fBnum_protocols\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmAddProtocols\fP adds the protocols to the protocol manager and allocates the internal tables. .PP .ne 6 \fIXmAddWMProtocols\fP is a convenience interface. It calls \fIXmAddProtocols\fP with the property value set to the atom returned by interning \fIWM_PROTOCOLS\fP. .IP "\fBshell\fP" Specifies the widget with which the protocol property is associated. .IP "\fBproperty\fP" Specifies the protocol property. .IP "\fBprotocols\fP" Specifies the protocol \fIAtoms\fP (or \fIint\fP types cast to \fIAtom\fP). .IP "\fBnum_protocols\fP" Specifies the number of elements in \fBprotocols\fP. .PP For a complete definition of VendorShell and its associated resources, see \fIVendorShell(3X)\fP. .SH RELATED INFORMATION .na \fIVendorShell(3X)\fP, \fIXmAddWMProtocols(3X)\fP, and \fIXmInternAtom(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmAddTabGroup 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmAddTabGroup\fP \- A function that adds a manager or a primitive widget to the list of tab groups .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmAddTabGroup (\fBtab_group\fI) .ta .5i 1.5i .nf Widget \fBtab_group\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi This function is obsolete and its behavior is replaced by setting \fIXmNnavigationType\fP to \fIXmEXCLUSIVE_TAB_GROUP\fP. When using the keyboard to traverse through a widget hierarchy, primitive or manager widgets are grouped together into what are known as \fItab groups\fP. Any manager or primitive widget can be a tab group. Within a tab group, move the focus to the next widget within the tab group by using the arrow keys. To move to another tab group, use \fIKNextField\fP or \fIKPrevField\fP. .PP Tab groups are ordinarily specified by the \fIXmNnavigationType\fP resource. \fIXmAddTabGroup\fP is called to control the order of traversal of tab groups. The widget specified .ne 10 by \fBtab_group\fP is appended to the list of tab groups to be traversed, and the widget's \fIXmNnavigationType\fP is set to \fIXmEXCLUSIVE_TAB_GROUP\fP. .IP "\fBtab_group\fP" Specifies the manager or primitive widget ID. .SH RELATED INFORMATION .na \fIXmManager(3X)\fP, \fIXmGetTabGroup(3X)\fP, \fIXmPrimitive(3X)\fP, and \fIXmRemoveTabGroup(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmAddWMProtocolCallback 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmAddWMProtocolCallback\fP \- A VendorShell convenience interface that adds client callbacks for a protocol .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu void XmAddWMProtocolCallback (\fBshell, protocol, callback, closure\fI) .ta .5i 1.75i .nf Widget \fBshell\fI; Atom \fBprotocol\fI; XtCallbackProc \fBcallback\fI; XtPointer \fBclosure\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmAddWMProtocolCallback\fP is a convenience interface. It calls \fIXmAddProtocolCallback\fP with the property value set to the atom returned by interning \fIWM_PROTOCOLS\fP. .IP "\fBshell\fP" Specifies the widget with which the protocol property is associated. .IP "\fBprotocol\fP" Specifies the protocol \fIAtom\fP (or an \fIint\fP type cast to \fIAtom\fP). .IP "\fBcallback\fP" Specifies the procedure to call when a protocol message is received. .IP "\fBclosure\fP" Specifies the client data to be passed to the callback when it is invoked. .PP For a complete definition of VendorShell and its associated resources, see \fIVendorShell(3X)\fP. .SH RELATED INFORMATION .na \fIVendorShell(3X)\fP, \fIXmAddProtocolCallback(3X)\fP, and \fIXmInternAtom(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmAddWMProtocols 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmAddWMProtocols\fP \- A VendorShell convenience interface that adds the protocols to the protocol manager and allocates the internal tables .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu void XmAddWMProtocols (\fBshell, protocols, num_protocols\fI) .ta .5i 1.5i .nf Widget \fBshell\fI; Atom \fB* protocols\fI; Cardinal \fBnum_protocols\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmAddWMProtocols\fP is a convenience interface. It calls \fIXmAddProtocols\fP with the property value set to the atom returned by interning \fIWM_PROTOCOLS\fP. .nL .ne 30 .IP "\fBshell\fP" Specifies the widget with which the protocol property is associated. .IP "\fBprotocols\fP" Specifies the protocol \fIAtoms\fP (or \fIint\fP types cast to \fIAtom\fP). .IP "\fBnum_protocols\fP" Specifies the number of elements in \fBprotocols\fP. .PP For a complete definition of VendorShell and its associated resources, see \fIVendorShell(3X)\fP. .SH RELATED INFORMATION .na \fIVendorShell(3X)\fP, \fIXmAddProtocols(3X)\fP, and \fIXmInternAtom(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmArrowButton 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmArrowButton\fP \- The ArrowButton widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi ArrowButton consists of a directional arrow surrounded by a border shadow. When it is selected, the shadow changes to give the appearance that the ArrowButton has been pressed in. When the ArrowButton is unselected, the shadow reverts to give the appearance that the ArrowButton is released, or out. .SS "Classes" ArrowButton inherits behavior and resources from \fICore\fP and \fIXmPrimitive\fP classes. .PP The class pointer is \fIxmArrowButtonWidgetClass\fP. .PP The class name is \fIXmArrowButton\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmArrowButton Resource Set Name Class Type Default Access _ XmNactivateCallback XmCCallback XtCallbackList NULL C XmNarmCallback XmCCallback XtCallbackList NULL C XmNarrowDirection XmCArrowDirection unsigned char XmARROW_UP CSG XmNdisarmCallback XmCCallback XtCallbackList NULL C XmNmultiClick XmCMultiClick unsigned char dynamic CSG .TE .KE .in .sp 1 .IP "\fIXmNactivateCallback\fP" Specifies a list of callbacks that is called when the ArrowButton is activated. To activate the button, press and release \fIBSelect\fP while the pointer is inside the ArrowButton widget. Activating the ArrowButton also disarms it. The reason sent by this callback is \fIXmCR_ACTIVATE\fP. .IP "\fIXmNarmCallback\fP" Specifies a list of callbacks that is called when the ArrowButton is armed. To arm this widget, press \fIBSelect\fP while the pointer is inside the ArrowButton. The reason sent by this callback is \fIXmCR_ARM\fP. .IP "\fIXmNarrowDirection\fP" Sets the arrow direction. The following are values for this resource: .wH .rS .TP \(bu \fIXmARROW_UP\fP. .TP \(bu \fIXmARROW_DOWN\fP. .TP \(bu \fIXmARROW_LEFT\fP. .TP \(bu \fIXmARROW_RIGHT\fP. .wH .rE .IP "\fIXmNdisarmCallback\fP" Specifies a list of callbacks that is called when the ArrowButton is disarmed. To disarm this widget, press and release \fIBSelect\fP while the pointer is inside the ArrowButton. The reason for this callback is \fIXmCR_DISARM\fP. .IP "\fIXmNmultiClick\fP" If a button click is followed by another button click within the time span specified by the display's multi-click time, and this resource is set to \fIXmMULTICLICK_DISCARD\fP, do not process the second click. If this resource is set to \fIXmMULTICLICK_KEEP\fP, process the event and increment \fBclick_count\fP in the callback structure. When the button is not in a menu, the default value is \fIXmMULTICLICK_KEEP\fP. .SS "Inherited Resources" ArrowButton inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPrimitive Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG .wH .tH XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.1i .nf typedef struct { int \fBreason\fI; XEvent \fB* event\fI; int \fBclick_count\fI; } XmArrowButtonCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBclick_count\fP" This value is valid only when the reason is \fIXmCR_ACTIVATE\fP. It contains the number of clicks in the last multiclick sequence if the \fIXmNmultiClick\fP resource is set to \fIXmMULTICLICK_KEEP\fP; otherwise it contains \fI1\fP. The activate callback is invoked for each click if \fIXmNmultiClick\fP is set to \fIXmMULTICLICK_KEEP\fP. .SS "Translations" XmArrowButton includes translations for XmPrimitive. Additional XmArrowButton translations are listed below. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BSelect Press: Arm() BSelect Click: Activate() Disarm() BSelect Release: Activate() Disarm() BSelect Press 2+: MultiArm() BSelect Release 2+: MultiActivate() .sp \n(PDu KSelect: ArmAndActivate() KHelp: Help() .wH .fi .iE .P .ne 4i .SS "Action Routines" The XmArrowButton action routines are described below: .IP "\fIActivate()\fP:" Draws the shadow in the unselected state. If the pointer is within the ArrowButton, calls the callbacks for \fIXmNactivateCallback\fP. .IP "\fIArm()\fP:" Draws the shadow in the selected state and calls the callbacks for \fIXmNarmCallback\fP. .nL .ne 8 .IP "\fIArmAndActivate()\fP:" Draws the shadow in the selected state and calls the callbacks for \fIXmNarmCallback\fP. Arranges for the shadow to be drawn in the unselected state and the callbacks for \fIXmNactivateCallback\fP and \fIXmNdisarmCallback\fP to be called, either immediately or at a later time. .IP "\fIDisarm()\fP:" Draws the shadow in the unselected state and calls the callbacks for \fIXmNdisarmCallback\fP. .IP "\fIHelp()\fP:" Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIMultiActivate()\fP:" If \fIXmNmultiClick\fP is \fIXmMULTICLICK_DISCARD\fP, this action does nothing. .P If \fIXmNmultiClick\fP is \fIXmMULTICLICK_KEEP\fP, this action does the following: Increments \fBclick_count\fP in the callback structure. Draws the shadow in the unselected state. If the pointer is within the ArrowButton, calls the callbacks for \fIXmNactivateCallback\fP. Calls the callbacks for \fIXmNdisarmCallback\fP. .IP "\fIMultiArm()\fP:" If \fIXmNmultiClick\fP is \fIXmMULTICLICK_DISCARD\fP, this action does nothing. If \fIXmNmultiClick\fP is \fIXmMULTICLICK_KEEP\fP, this action draws the shadow in the selected state and calls the callbacks for \fIXmNarmCallback\fP. .nL .ne 30 .SS "Additional Behavior" This widget has the additional behavior described below: .IP "\fI\fP:" Draws the ArrowButton shadow in its selected state if the pointer leaves and re-enters the window while BSelect is pressed. .IP "\fI\fP:" Draws the ArrowButton shadow in its unselected state if the pointer leaves the window while BSelect is pressed. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fICore(3X)\fP, \fIXmCreateArrowButton(3X)\fP, and \fIXmPrimitive(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmArrowButtonGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmArrowButtonGadget\fP \- The ArrowButtonGadget widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi ArrowButtonGadget consists of a directional arrow surrounded by a border shadow. When it is selected, the shadow changes to give the appearance that the ArrowButtonGadget has been pressed in. When it is unselected, the shadow reverts to give the appearance that the button is released, or out. .SS "Classes" ArrowButtonGadget inherits behavior and resources from \fIObject\fP, \fIRectObj\fP, and \fIXmGadget\fP classes. .PP The class pointer is \fIxmArrowButtonGadgetClass\fP. .PP The class name is \fIXmArrowButtonGadget\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. ArrowButtonGadget Resource Set Name Class Type Default Access _ XmNactivateCallback XmCCallback XtCallbackList NULL C XmNarmCallback XmCCallback XtCallbackList NULL C XmNarrowDirection XmCArrowDirection unsigned char XmARROW_UP CSG XmNdisarmCallback XmCCallback XtCallbackList NULL C XmNmultiClick XmCMultiClick unsigned char dynamic CSG .TE .KE .in .sp 1 .IP "\fIXmNactivateCallback\fP" Specifies a list of callbacks that is called when the ArrowButtonGadget is activated. To activate the button, press and release \fIBSelect\fP while the pointer is inside the ArrowButtonGadget. Activating the ArrowButtonGadget also disarms it. The reason sent by this callback is \fIXmCR_ACTIVATE\fP. .nL .ne 5 .IP "\fIXmNarmCallback\fP" Specifies a list of callbacks that is called when the ArrowButtonGadget is armed. To arm this widget, press \fIBSelect\fP while the pointer is inside the ArrowButtonGadget. The reason sent by this callback is \fIXmCR_ARM\fP. .IP "\fIXmNarrowDirection\fP" Sets the arrow direction. The values for this resource are: .wH .rS .TP \(bu \fIXmARROW_UP\fP. .TP \(bu \fIXmARROW_DOWN\fP. .TP \(bu \fIXmARROW_LEFT\fP. .TP \(bu \fIXmARROW_RIGHT\fP. .wH .rE .IP "\fIXmNdisarmCallback\fP" Specifies a list of callbacks that is called when the ArrowButtonGadget is disarmed. To disarm this widget, press and release \fIBSelect\fP while the pointer is inside the ArrowButtonGadget. The reason sent by this callback is \fIXmCR_DISARM\fP. .IP "\fIXmNmultiClick\fP" If a button click is followed by another button click within the time span specified by the display's multi-click time, and this resource is set to \fIXmMULTICLICK_DISCARD\fP, do not process the second click. If this resource is set to \fIXmMULTICLICK_KEEP\fP, process the event and increment \fBclick_count\fP in the callback structure. When the ArrowButtonGadget is not in a menu, the default value is \fIXmMULTICLICK_KEEP\fP. .SS "Inherited Resources" ArrowButtonGadget inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmGadget Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic G XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic G XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic G XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. RectObj Resource Set Name Class Type Default Access _ XmNancestorSensitive XmCSensitive Boolean dynamic G XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNheight XmCHeight Dimension dynamic CSG XmNsensitive XmCSensitive Boolean True CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Object Resource Set Name Class Type Default Access _ XmNdestroyCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.1i .nf typedef struct { int \fBreason\fI; XEvent \fB* event\fI; int \fBclick_count\fI; } XmArrowButtonCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBclick_count\fP" This value is valid only when the reason is \fIXmCR_ACTIVATE\fP. It contains the number of clicks in the last multiclick sequence if the \fIXmNmultiClick\fP resource is set to \fIXmMULTICLICK_KEEP\fP, otherwise it contains \fI1\fP. The activate callback is invoked for each click if \fIXmNmultiClick\fP is set to \fIXmMULTICLICK_KEEP\fP. .SS "Behavior" XmArrowButtonGadget includes behavior from XmGadget. Additional XmArrowButtonGadget behavior is described below: .IP "\fIBSelect\ Press\fP:" Draws the shadow in the selected state and calls the callbacks for \fIXmNarmCallback\fP. .IP "\fIBSelect\ Click\ or\ BSelectRelease\fP:" Draws the shadow in the unselected state. If the pointer is within the ArrowButtonGadget, calls the callbacks for \fIXmNactivateCallback\fP. Calls the callbacks for \fIXmNdisarmCallback\fP. .IP "\fIBSelect\ Press\ 2+\fP:" If \fIXmNmultiClick\fP is \fIXmMULTICLICK_DISCARD\fP, this action does nothing. If \fIXmNmultiClick\fP is \fIXmMULTICLICK_KEEP\fP, this action draws the shadow in the selected state and calls the callbacks for \fIXmNarmCallback\fP. .nL .ne 7 .IP "\fIBSelect\ Release\ 2+\fP:" If \fIXmNmultiClick\fP is \fIXmMULTICLICK_DISCARD\fP, this action does nothing. .P If \fIXmNmultiClick\fP is \fIXmMULTICLICK_KEEP\fP, this action does the following: Increments \fBclick_count\fP in the callback structure. Draws the shadow in the unselected state. If the pointer is within the ArrowButtonGadget, calls the callbacks for \fIXmNactivateCallback\fP. Calls the callbacks for \fIXmNdisarmCallback\fP. .IP "\fIKSelect\fP:" Draws the shadow in the selected state and calls the callbacks for \fIXmNarmCallback\fP. Arranges for the shadow to be drawn in the unselected state and the callbacks for \fIXmNactivateCallback\fP and \fIXmNdisarmCallback\fP to be called, either immediately or at a later time. .IP "\fIKHelp\fP:" Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this calls the help callbacks for the nearest ancestor that has them. .IP "\fI\fP:" Draws the ArrowButtonGadget shadow in its selected state if the pointer leaves and re-enters the gadget while BSelect is pressed. .IP "\fI\fP:" Draws the ArrowButtonGadget shadow in its unselected state if the pointer leaves the gadget while BSelect is pressed. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fIObject(3X)\fP, \fIRectObj(3X)\fP, \fIXmCreateArrowButtonGadget(3X)\fP, and \fIXmGadget(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmBulletinBoard 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmBulletinBoard\fP \- The BulletinBoard widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi BulletinBoard is a composite widget that provides simple geometry management for children widgets. It does not force positioning on its children, but can be set to reject geometry requests that result in overlapping children. BulletinBoard is the base widget for most dialog widgets and is also used as a general container widget. .PP Modal and modeless dialogs are implemented as collections of widgets that include a DialogShell, a BulletinBoard (or subclass) child of the shell, and various dialog components (buttons, labels, etc.) that are children of BulletinBoard. BulletinBoard defines callbacks useful for dialogs (focus, map, unmap), which are available for application use. If its parent is a DialogShell, BulletinBoard passes title and input mode (based on dialog style) information to the parent, which is responsible for appropriate communication with the window manager. .PP The default value for \fIXmNinitialFocus\fP is the value of \fIXmNdefaultButton\fP. .SS "Classes" BulletinBoard inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIConstraint\fP, and \fIXmManager\fP classes. .PP The class pointer is \fIxmBulletinBoardWidgetClass\fP. .PP The class name is \fIXmBulletinBoard\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmBulletinBoard Resource Set Name Class Type Default Access _ XmNallowOverlap XmCAllowOverlap Boolean True CSG XmNautoUnmanage XmCAutoUnmanage Boolean True CG XmNbuttonFontList XmCButtonFontList XmFontList dynamic CSG XmNcancelButton XmCWidget Widget NULL SG XmNdefaultButton XmCWidget Widget NULL SG XmNdefaultPosition XmCDefaultPosition Boolean True CSG XmNdialogStyle XmCDialogStyle unsigned char dynamic CSG XmNdialogTitle XmCDialogTitle XmString NULL CSG XmNfocusCallback XmCCallback XtCallbackList NULL C XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG XmNmapCallback XmCCallback XtCallbackList NULL C XmNmarginHeight XmCMarginHeight Dimension 10 CSG XmNmarginWidth XmCMarginWidth Dimension 10 CSG XmNnoResize XmCNoResize Boolean False CSG .wH .tH XmNresizePolicy XmCResizePolicy unsigned char XmRESIZE_ANY CSG XmNshadowType XmCShadowType unsigned char XmSHADOW_OUT CSG XmNtextFontList XmCTextFontList XmFontList dynamic CSG XmNtextTranslations XmCTranslations XtTranslations NULL C XmNunmapCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .IP "\fIXmNallowOverlap\fP" Controls the policy for overlapping children widgets. If True, BulletinBoard allows geometry requests that result in overlapping children. .IP "\fIXmNautoUnmanage\fP" Controls whether or not BulletinBoard is automatically unmanaged after a button is activated. If this resource is True on initialization and if the BulletinBoard's parent is a DialogShell, BulletinBoard adds a callback to button children (PushButtons, PushButtonGadgets, and DrawnButtons) that unmanages the BulletinBoard when a button is activated. If this resource is False on initialization or if the BulletinBoard's parent is not a DialogShell, the BulletinBoard is not automatically unmanaged. For BulletinBoard subclasses with Apply or Help buttons, activating those buttons does not automatically unmanage the BulletinBoard. .IP "\fIXmNbuttonFontList\fP" Specifies the font list used for BulletinBoard's button descendants. If this value is NULL at initialization, the font list is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard, VendorShell, or XmMenuShell widget class. If such an ancestor is found, the font list is initialized to the \fIXmNbuttonFontList\fP of the ancestor widget. If no such ancestor is found, the default is implementation dependent. Refer to \fIXmFontList(3X)\fP for more information on the creation and structure of a font list. .IP "\fIXmNcancelButton\fP" Specifies the widget ID of the \fICancel\fP button. BulletinBoard's subclasses, which define a \fICancel\fP button, set this resource. BulletinBoard does not directly provide any behavior for that button. .IP "\fIXmNdefaultButton\fP" Specifies the widget ID of the default button. Some BulletinBoard subclasses, which define a default button, set this resource. BulletinBoard defines translations and installs accelerators that activate that button when \fIKActivate\fP is pressed and the keyboard focus is not in another button. .IP "\fIXmNdefaultPosition\fP" Controls whether or not the BulletinBoard is automatically positioned by its parent. If True, and the parent of the BulletinBoard is a DialogShell, the BulletinBoard is centered within or around the parent of the DialogShell when the BulletinBoard is mapped and managed. If False, the BulletinBoard is not automatically positioned. .IP "\fIXmNdialogStyle\fP" Indicates the dialog style associated with the BulletinBoard. If the parent of the BulletinBoard is a DialogShell, the parent's \fIXmNmwmInputMode\fP is set according to the value of this resource. This resource can be set only if the BulletinBoard is unmanaged. Possible values for this resource include the following: .wH .rS .TP \(bu \fIXmDIALOG_SYSTEM_MODAL\fP \- used for dialogs that must be responded to before any other interaction in any application .TP \(bu \fIXmDIALOG_PRIMARY_APPLICATION_MODAL\fP \- used for dialogs that must be responded to before some other interactions in ancestors of the widget .nL .ne 15 .TP \(bu \fIXmDIALOG_APPLICATION_MODAL\fP \- used for dialogs that must be responded to before some other interactions in ancestors of the widget. This value is the same as \fIXmDIALOG_PRIMARY_APPLICATION_MODAL\fP, and remains for compatibility. .TP \(bu \fIXmDIALOG_FULL_APPLICATION_MODAL\fP \- used for dialogs that must be responded to before some other interactions in the same application .TP \(bu \fIXmDIALOG_MODELESS\fP \- used for dialogs that do not interrupt interaction of any application. This is the default when the parent of the BulletinBoard is a DialogShell. .TP \(bu \fIXmDIALOG_WORK_AREA\fP \- used for BulletinBoard widgets whose parents are not DialogShells. \fIXmNdialogStyle\fP is forced to have this value when the parent of the BulletinBoard is not a DialogShell. .wH .rE .IP "\fIXmNdialogTitle\fP" Specifies the dialog title. If this resource is not NULL, and the parent of the BulletinBoard is a subclass of WMShell, BulletinBoard sets the \fIXmNtitle\fP and \fIXmNtitleEncoding\fP of its parent. If the only character set in \fIXmNdialogTitle\fP is ISO8859-1, \fIXmNtitle\fP is set to the string of the title, and \fIXmNtitleEncoding\fP is set to \fISTRING\fP. If \fIXmNdialogTitle\fP contains character sets other than ISO8859-1, \fIXmNtitle\fP is set to the string of the title converted to a compound text string, and \fIXmNtitleEncoding\fP is set to \fICOMPOUND_TEXT\fP. .IP "\fIXmNfocusCallback\fP" Specifies the list of callbacks that is called when the BulletinBoard widget or one of its descendants accepts the input focus. The callback reason is \fIXmCR_FOCUS\fP. .nL .ne 15 .IP "\fIXmNlabelFontList\fP" Specifies the font list used for BulletinBoard's label descendants (Labels and LabelGadgets). If this value is NULL at initialization, the font list is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard, VendorShell, or XmMenuShell widget class. If such an ancestor is found, the font list is initialized to the \fIXmNlabelFontList\fP of the ancestor widget. If no such ancestor is found, the default is implementation dependent. Refer to \fIXmFontList(3X)\fP for more information on the creation and structure of a font list. .IP "\fIXmNmapCallback\fP" Specifies the list of callbacks that is called only when the parent of the BulletinBoard is a DialogShell; in which case, this callback list is invoked when the BulletinBoard widget is mapped. The callback reason is \fIXmCR_MAP\fP. DialogShells are usually mapped when the DialogShell is managed. .IP "\fIXmNmarginHeight\fP" Specifies the minimum spacing in pixels between the top or bottom edge of BulletinBoard and any child widget. .IP "\fIXmNmarginWidth\fP" Specifies the minimum spacing in pixels between the left or right edge of BulletinBoard and any child widget. .IP "\fIXmNnoResize\fP" Controls whether or not resize controls are included in the window manager frame around the BulletinBoard's parent. If set to True, the \fImwm\fP does not include resize controls in the window manager frame containing the parent of the BulletinBoard if the parent is a subclass of VendorShell. If set to False, the window manager frame does include resize controls. Other controls provided by \fImwm\fP can be included or excluded through the \fImwm\fP resources provided by VendorShell. .nL .ne 15 .IP "\fIXmNresizePolicy\fP" Controls the policy for resizing BulletinBoard widgets. Possible values include the following: .wH .rS .TP \(bu \fIXmRESIZE_NONE\fP \- fixed size .TP \(bu \fIXmRESIZE_ANY\fP \- shrink or grow as needed .TP \(bu \fIXmRESIZE_GROW\fP \- grow only .wH .rE .IP "\fIXmNshadowType\fP" Describes the shadow drawing style for BulletinBoard. This resource can have the following values: .TP \(bu \fIXmSHADOW_IN\fP \- draws the BulletinBoard shadow so that it appears inset. This means that the bottom shadow visuals and top shadow visuals are reversed. .TP \(bu \fIXmSHADOW_OUT\fP \- draws the BulletinBoard shadow so that it appears outset .TP \(bu \fIXmSHADOW_ETCHED_IN\fP \- draws the BulletinBoard shadow using a double line giving the effect of a line etched into the window, similar to the Separator widget .TP \(bu \fIXmSHADOW_ETCHED_OUT\fP \- draws the BulletinBoard shadow using a double line giving the effect of a line coming out of the window, similar to the Separator widget .nL .ne 25 .IP "\fIXmNtextFontList\fP" Specifies the font list used for BulletinBoard's Text and List descendants. If this value is NULL at initialization, the font list is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard or VendorShell widget class. If such an ancestor is found, the font list is initialized to the \fIXmNtextFontList\fP of the ancestor widget. If no such ancestor is found, the default is implementation dependent. Refer to \fIXmFontList(3X)\fP for more information on the creation and structure of a font list. .IP "\fIXmNtextTranslations\fP" Adds translations to any Text widget or Text widget subclass that is added as a child of BulletinBoard. .IP "\fIXmNunmapCallback\fP" Specifies the list of callbacks that is called only when the parent of the BulletinBoard is a DialogShell. In that case, this callback list is invoked when the BulletinBoard widget is unmapped. The callback reason is \fIXmCR_UNMAP\fP. DialogShells are usually unmapped when the DialogShell is unmanaged. .SS "Inherited Resources" BulletinBoard inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmManager Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget dynamic CSG XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension dynamic CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic N/A XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.1i .nf typedef struct { int \fBreason\fI; XEvent \fB* event\fI; } XmAnyCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .SS "Translations" XmBulletinBoard includes the translations from XmManager. .P .nL .ne 20 .SS "Additional Behavior" The XmBulletinBoard widget has the additional behavior described below: .IP "\fIMAny\ KCancel\fP:" Calls the activate callbacks for the cancel button if it is sensitive. If no cancel button exists and if the parent of the BulletinBoard is a manager, passes the event to the parent. .IP "\fIKActivate\fP:" Calls the activate callbacks for the button with the keyboard focus. If no button has the keyboard focus, calls the activate callbacks for the default button if it is sensitive. In a List widget or single-line Text widget, the List or Text action associated with \fIKActivate\fP is called before the BulletinBoard actions associated with \fIKActivate\fP. In a multi-line Text widget, any \fIKActivate\fP event except \fIKEnter\fP calls the Text action associated with \fIKActivate\fP, then the BulletinBoard actions associated with \fIKActivate\fP. If no button has the focus, no default button exists, and the parent of the BulletinBoard is a manager, passes the event to the parent. .IP "\fI\fP:" Calls the callbacks for \fIXmNfocusCallback\fP. When the focus policy is \fIXmPOINTER\fP, this happens when the pointer enters the window. When the focus policy is \fIXmEXPLICIT\fP, this happens when the user traverses to the widget. .IP "\fI\fP:" Calls the callbacks for \fIXmNmapCallback\fP. .IP "\fI\fP:" Calls the callbacks for \fIXmNunmapCallback\fP. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fIConstraint(3X)\fP, \fICore(3X)\fP, \fIXmCreateBulletinBoard(3X)\fP, \fIXmCreateBulletinBoardDialog(3X)\fP, \fIXmDialogShell(3X),\fP and \fIXmManager(3X).\fP .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCascadeButton 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCascadeButton\fP \- The CascadeButton widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi CascadeButton links two MenuPanes or a MenuBar to a MenuPane. .PP It is used in menu systems and must have a RowColumn parent with its \fIXmNrowColumnType\fP resource set to \fIXmMENU_BAR\fP, \fIXmMENU_POPUP\fP or \fIXmMENU_PULLDOWN\fP. .PP It is the only widget that can have a Pulldown MenuPane attached to it as a submenu. The submenu is displayed when this widget is activated within a MenuBar, a PopupMenu, or a PulldownMenu. Its visuals can include a label or pixmap and a cascading indicator when it is in a Popup or Pulldown MenuPane; or, it can include only a label or a pixmap when it is in a MenuBar. .PP The default behavior associated with a CascadeButton depends on the type of menu system in which it resides. By default, \fIBSelect\fP controls the behavior of the CascadeButton. In addition, \fIBMenu\fP controls the behavior of the CascadeButton if it resides in a Menu system. The actual mouse button used is determined by its RowColumn parent. .PP A CascadeButton's visuals differ from most other button gadgets. When the button becomes armed, its visuals change from a 2-D to a 3-D look, and it displays the submenu that has been attached to it. If no submenu is attached, it simply changes its visuals. .PP When a CascadeButton within a Pulldown or Popup MenuPane is armed as the result of the user moving the mouse pointer into the widget, it does not immediately display its submenu. Instead, it waits a short amount of time to see if the arming was temporary (that is, the user was simply passing through the widget), or whether the user really wanted the submenu posted. This time delay is configurable via \fIXmNmappingDelay\fP. .PP CascadeButton provides a single mechanism for activating the widget from the keyboard. This mechanism is referred to as a keyboard mnemonic. If a mnemonic has been specified for the widget, the user may activate the CascadeButton by simply typing the mnemonic while the CascadeButton is visible. If the CascadeButton is in a MenuBar and the MenuBar does not have the focus, the \fIMAlt\fP modifier must be pressed with the mnemonic. Mnemonics are typically used to interact with a menu via the keyboard interface. .PP If in a Pulldown or Popup MenuPane and there is a submenu attached, the \fIXmNmarginBottom\fP, \fIXmNmarginLeft\fP, \fIXmNmarginRight\fP, and \fIXmNmarginTop\fP resources may enlarge to accommodate \fIXmNcascadePixmap\fP. \fIXmNmarginWidth\fP defaults to 6 if this resource is in a MenuBar; otherwise, it takes Label's default, which is 2. .SS "Classes" CascadeButton inherits behavior and resources from \fICore\fP, \fIXmPrimitive\fP, and \fIXmLabel\fP classes. .PP The class pointer is \fIxmCascadeButtonWidgetClass\fP. .PP The class name is \fIXmCascadeButton\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmCascadeButton Resource Set Name Class Type Default Access _ XmNactivateCallback XmCCallback XtCallbackList NULL C XmNcascadePixmap XmCPixmap Pixmap dynamic CSG XmNcascadingCallback XmCCallback XtCallbackList NULL C XmNmappingDelay XmCMappingDelay int 180 ms CSG XmNsubMenuId XmCMenuWidget Widget NULL CSG .TE .KE .in .sp 1 .IP "\fIXmNactivateCallback\fP" Specifies the list of callbacks that is called when the user activates the CascadeButton widget, and there is no submenu attached to pop up. The activation occurs by releasing a mouse button or by typing the mnemonic associated with the widget. The specific mouse button depends on information in the RowColumn parent. The reason sent by the callback is \fIXmCR_ACTIVATE\fP. .IP "\fIXmNcascadePixmap\fP" Specifies the cascade pixmap displayed on one end of the widget when a CascadeButton is used within a Popup or Pulldown MenuPane and a submenu is attached. The Label class resources \fIXmNmarginBottom\fP, \fIXmNmarginLeft\fP, \fIXmNmarginRight\fP, and \fIXmNmarginTop\fP may be modified to ensure that room is left for the cascade pixmap. The default cascade pixmap is an arrow pointing to the side of the menu where the submenu will appear. .IP "\fIXmNcascadingCallback\fP" Specifies the list of callbacks that is called just prior to the mapping of the submenu associated with CascadeButton. The reason sent by the callback is \fIXmCR_CASCADING\fP. .IP "\fIXmNmappingDelay\fP" Specifies the amount of time, in milliseconds, between when a CascadeButton becomes armed and when it maps its submenu. This delay is used only when the widget is within a Popup or Pulldown MenuPane. The value must not be negative. .IP "\fIXmNsubMenuId\fP" Specifies the widget ID for the Pulldown MenuPane to be associated with this CascadeButton. The specified MenuPane is displayed when the CascadeButton becomes armed. The MenuPane must have been created with the appropriate parentage depending on the type of menu used. See \fIXmCreateMenuBar(3X)\fP, \fIXmCreatePulldownMenu(3X)\fP, and \fIXmCreatePopupMenu(3X)\fP for more information on the menu systems. .SS "Inherited Resources" CascadeButton inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmLabel Resource Set Name Class Type Default Access _ XmNaccelerator XmCAccelerator String NULL N/A XmNacceleratorText XmCAcceleratorText XmString NULL N/A XmNalignment XmCAlignment unsigned char dynamic CSG XmNfontList XmCFontList XmFontList dynamic CSG XmNlabelInsensitivePixmap XmCLabelInsensitivePixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelPixmap XmCLabelPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelString XmCXmString XmString dynamic CSG XmNlabelType XmCLabelType unsigned char XmSTRING CSG XmNmarginBottom XmCMarginBottom Dimension dynamic CSG XmNmarginHeight XmCMarginHeight Dimension 2 CSG XmNmarginLeft XmCMarginLeft Dimension 0 CSG XmNmarginRight XmCMarginRight Dimension dynamic CSG XmNmarginTop XmCMarginTop Dimension dynamic CSG XmNmarginWidth XmCMarginWidth Dimension dynamic CSG .wH .tH XmNmnemonic XmCMnemonic KeySym NULL CSG XmNmnemonicCharSet XmCMnemonicCharSet String XmFONTLIST_DEFAULT_TAG CSG XmNrecomputeSize XmCRecomputeSize Boolean True CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CSG .TE .KE .in .sp 1 .wH .in .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPrimitive Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNhighlightThickness XmCHighlightThickness Dimension 0 CSG .wH .tH XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean dynamic G XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.1i .nf typedef struct { int \fBreason\fI; \fIXEvent \fB* event\fI; } XmAnyCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback or is NULL if this callback was not triggered due to an \fIXEvent\fP. .SS "Translations" XmCascadeButton includes translations from Primitive. XmCascadeButton includes the menu traversal translations from XmLabel. These translations may not directly correspond to a translation table. .PP .ne 2i Note that altering translations in \fI#override\fP or \fI#augment\fP mode is undefined. .PP The translations for a CascadeButton in a MenuBar are listed below. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BSelect Press: MenuBarSelect() BSelect Release: DoSelect() KActivate: KeySelect() KSelect: KeySelect() KHelp: Help() MAny KCancel: CleanupMenuBar() .wH .fi .iE .PP The translations for a CascadeButton in a PullDown or Popup MenuPane are listed below. In a menu system, \fIBMenu\fP also performs the \fIBSelect\fP actions. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BSelect Press: StartDrag() BSelect Release: DoSelect() KActivate: KeySelect() KSelect: KeySelect() KHelp: Help() MAny KCancel: CleanupMenuBar() .wH .fi .iE .SS "Action Routines" The XmCascadeButton action routines are described below: .IP "\fICleanupMenuBar()\fP:" In a MenuBar, disarms the CascadeButton and the menu and, when the shell's keyboard focus policy is \fIXmEXPLICT\fP, restores keyboard focus to the widget that had the focus before the menu was entered. .P .ne 3.5i In a toplevel Pulldown MenuPane from a MenuBar, unposts the menu, disarms the MenuBar CascadeButton and the MenuBar, and, when the shell's keyboard focus policy is \fIXmEXPLICT\fP, restores keyboard focus to the widget that had the focus before the MenuBar was entered. In other Pulldown MenuPanes, unposts the menu. .P In a Popup MenuPane, unposts the menu and, when the shell's keyboard focus policy is \fIXmEXPLICT\fP, restores keyboard focus to the widget from which the menu was posted. .IP "\fIDoSelect()\fP:" Calls the callbacks in \fIXmNcascadingCallback\fP, posts the submenu attached to the CascadeButton and enables keyboard traversal within the menu. If the CascadeButton does not have a submenu attached, calls the callbacks in \fIXmNactivateCallback\fP, the CascadeButton is activated and all posted menus in the cascade are unposted. .IP "\fIHelp()\fP:" Unposts all menus in the menu hierarchy and, when the shell's keyboard focus policy is \fIXmEXPLICT\fP, restores keyboard focus to the widget that had the focus before the menu system was entered. Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIKeySelect()\fP:" Calls the callbacks in \fIXmNcascadingCallback\fP, and posts the submenu attached to the CascadeButton if keyboard traversal is enabled in the menu. If the CascadeButton does not have a submenu attached, calls the callbacks in \fIXmNactivateCallback\fP, the CascadeButton is activated and all posted menus in the cascade are unposted. .IP "\fIMenuBarSelect()\fP:" Unposts any menus posted by the parent menu. Arms both the CascadeButton and the MenuBar, posts the associated submenu, and enables mouse traversal. If the menu is already active, this event disables keyboard traversal for the menu and returns the menu to mouse traversal mode. .IP "\fIStartDrag()\fP:" Arms the CascadeButton, posts the associated submenu, and enables mouse traversal. If the menu is already active, this event disables keyboard traversal for the menu and returns the menu to mouse traversal mode. .nL .ne 5 .SS "Additional Behavior" Posting a submenu calls the \fIXmNcascadingCallback\fP callbacks. This widget has the additional behavior described below: .IP "\fI\fP:" If keyboard traversal is enabled does nothing. Otherwise, in a MenuBar that is armed, unposts any MenuPanes associated with another MenuBar entry, arms the CascadeButton, and posts the associated submenu. In other menus, arms the CascadeButton and posts the associated submenu after the delay specified by \fIXmNmappingDelay\fP. .IP "\fI\fP:" If keyboard traversal is enabled does nothing. Otherwise, in a MenuBar that is armed, disarms the CascadeButton if the submenu associated with the CascadeButton is not currently posted or if there is no submenu associated with the CascadeButton. .P In other menus, if the pointer moves anywhere except into a submenu associated with the CascadeButton, the CascadeButton is disarmed and its submenu is unposted. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fICore(3X)\fP, \fIXmCascadeButtonHighlight(3X)\fP, \fIXmCreateCascadeButton(3X),XmCreateMenuBar(3X)\fP, \fIXmCreatePulldownMenu(3X)\fP, \fIXmCreatePopupMenu(3X)\fP, \fIXmDisplay(3X)\fP, \fIXmLabel(3X)\fP, \fIXmPrimitive(3X)\fP, and \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCascadeButtonGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCascadeButtonGadget\fP \- The CascadeButtonGadget widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi CascadeButtonGadget links two MenuPanes, a MenuBar to a MenuPane, or an OptionMenu to a MenuPane. .PP It is used in menu systems and must have a RowColumn parent with its \fIXmNrowColumnType\fP resource set to \fIXmMENU_BAR\fP, \fIXmMENU_POPUP\fP, \fIXmMENU_PULLDOWN\fP, or \fIXmMENU_OPTION\fP. .PP It is the only gadget that can have a Pulldown MenuPane attached to it as a submenu. The submenu is displayed when this gadget is activated within a PopupMenu, a PulldownMenu, or an OptionMenu. Its visuals can include a label or pixmap and a cascading indicator when it is in a Popup or Pulldown MenuPane; or it can include only a label or a pixmap when it is in an OptionMenu. .PP The default behavior associated with a CascadeButtonGadget depends on the type of menu system in which it resides. By default, \fIBSelect\fP controls the behavior of the CascadeButtonGadget. In addition, \fIBMenu\fP controls the behavior of the CascadeButtonGadget if it resides in a Menu system. The actual mouse button used is determined by its RowColumn parent. .PP A CascadeButtonGadget's visuals differ from most other button gadgets. When the button becomes armed, its visuals change from a 2-D to a 3-D look, and it displays the submenu that has been attached to it. If no submenu is attached, it simply changes its visuals. .PP When a CascadeButtonGadget within a Pulldown or Popup MenuPane is armed as the result of the user moving the mouse pointer into the gadget, it does not immediately display its submenu. Instead, it waits a short time to see if the arming was temporary (that is, the user was simply passing through the gadget), or the user really wanted the submenu posted. This delay is configurable via \fIXmNmappingDelay\fP. .PP CascadeButtonGadget provides a single mechanism for activating the gadget from the keyboard. This mechanism is referred to as a keyboard mnemonic. If a mnemonic has been specified for the gadget, the user may activate it by simply typing the mnemonic while the CascadeButtonGadget is visible. If the CascadeButtonGadget is in a MenuBar and the MenuBar does not have the focus, the \fIMAlt\fP modifier must be pressed with the mnemonic. Mnemonics are typically used to interact with a menu via the keyboard. .PP If a CascadeButtonGadget is in a Pulldown or Popup MenuPane and there is a submenu attached, the \fIXmNmarginBottom\fP, \fIXmNmarginLeft\fP, \fIXmNmarginRight\fP, and \fIXmNmarginTop\fP resources may enlarge to accommodate \fIXmNcascadePixmap\fP. \fIXmNmarginWidth\fP defaults to 6 if this resource is in a MenuBar; otherwise, it takes LabelGadget's default, which is 2. .SS "Classes" CascadeButtonGadget inherits behavior and resources from \fIObject\fP, \fIRectObj\fP, \fIXmGadget\fP, and \fIXmLabelGadget\fP classes. .PP The class pointer is \fIxmCascadeButtonGadgetClass\fP. .PP The class name is \fIXmCascadeButtonGadget\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmCascadeButtonGadget Name Class Type Default Access _ XmNactivateCallback XmCCallback XtCallbackList NULL C XmNcascadePixmap XmCPixmap Pixmap dynamic CSG XmNcascadingCallback XmCCallback XtCallbackList NULL C XmNmappingDelay XmCMappingDelay int 180 ms CSG XmNsubMenuId XmCMenuWidget Widget NULL CSG .TE .KE .in .sp 1 .IP "\fIXmNactivateCallback\fP" Specifies the list of callbacks that is called when the user activates the CascadeButtonGadget, and there is no submenu attached to pop up. The activation occurs by releasing a mouse button or by typing the mnemonic associated with the gadget. The specific mouse button depends on information in the RowColumn parent. The reason sent by the callback is \fIXmCR_ACTIVATE\fP. .IP "\fIXmNcascadePixmap\fP" Specifies the cascade pixmap displayed on one end of the gadget when a CascadeButtonGadget is used within a Popup or Pulldown MenuPane and a submenu is attached. The LabelGadget class resources \fIXmNmarginBottom\fP, \fIXmNmarginLeft\fP, \fIXmNmarginRight\fP, and \fIXmNmarginTop\fP may be modified to ensure that room is left for the cascade pixmap. The default cascade pixmap in menus other than option menus is an arrow pointing to the side of the menu where the submenu will appear. The default for the CascadeButtonGadget in an option menu is \fIXmUNSPECIFIED_PIXMAP\fP. .IP "\fIXmNcascadingCallback" Specifies the list of callbacks that is called just prior to the mapping of the submenu associated with the CascadeButtonGadget. The reason sent by the callback is \fIXmCR_CASCADING\fP. .IP "\fIXmNmappingDelay\fP" Specifies the amount of time, in milliseconds, between when a CascadeButtonGadget becomes armed and when it maps its submenu. This delay is used only when the gadget is within a Popup or Pulldown MenuPane. The value must not be negative. .IP "\fIXmNsubMenuId\fP" Specifies the widget ID for the Pulldown MenuPane to be associated with this CascadeButtonGadget. The specified MenuPane is displayed when the CascadeButtonGadget becomes armed. The MenuPane must have been created with the appropriate parentage depending on the type of menu used. See \fIXmCreatePulldownMenu(3X)\fP, \fIXmCreatePopupMenu(3X)\fP, and \fIXmCreateOptionMenu(3X)\fP for more information on the menu systems. .SS "Inherited Resources" CascadeButtonGadget inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmLabelGadget Resource Set Name Class Type Default Access _ XmNaccelerator XmCAccelerator String NULL N/A XmNacceleratorText XmCAcceleratorText XmString NULL N/A XmNalignment XmCAlignment unsigned char dynamic CSG XmNfontList XmCFontList XmFontList dynamic CSG XmNlabelInsensitivePixmap XmCLabelInsensitivePixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelPixmap XmCLabelPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelString XmCXmString XmString dynamic CSG XmNlabelType XmCLabelType unsigned char XmSTRING CSG XmNmarginBottom XmCMarginBottom Dimension dynamic CSG XmNmarginHeight XmCMarginHeight Dimension 2 CSG XmNmarginLeft XmCMarginLeft Dimension 0 CSG XmNmarginRight XmCMarginRight Dimension dynamic CSG XmNmarginTop XmCMarginTop Dimension dynamic CSG XmNmarginWidth XmCMarginWidth Dimension dynamic CSG .wH .tH XmNmnemonic XmCMnemonic KeySym NULL CSG XmNmnemonicCharSet XmCMnemonicCharSet String dynamic CSG XmNrecomputeSize XmCRecomputeSize Boolean True CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CSG .TE .KE .in .sp 1 .wH .in .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmGadget Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic G XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic G XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightThickness XmCHighlightThickness Dimension 0 CSG XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic G XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. RectObj Resource Set Name Class Type Default Access _ XmNancestorSensitive XmCSensitive Boolean dynamic G XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNheight XmCHeight Dimension dynamic CSG XmNsensitive XmCSensitive Boolean True CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Object Resource Set Name Class Type Default Access _ XmNdestroyCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.1i .nf typedef struct { int \fBreason\fI; \fIXEvent \fB* event\fI; } XmAnyCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback or is NULL if this callback was not triggered by an \fIXEvent\fP. .SS "Behavior" XmCascadeButtonGadget includes behavior from XmGadget. XmCascadeButton includes the menu traversal behavior from XmLabel. Additional XmCascadeButtonGadget behavior is described below. In a menu system, \fIBMenu\fP also performs the \fIBSelect\fP actions. .IP "\fIBSelect\ Press\fP:" Unposts any menus posted by the parent menu. Arms the CascadeButtonGadget, posts the associated submenu, enables mouse traversal, and, in a MenuBar, arms the MenuBar. If the menu is already active, this event disables keyboard traversal for the menu and returns the menu to mouse traversal mode. .IP "\fIBSelect\ Release\fP:" Calls the callbacks in \fIXmNcascadingCallback\fP, posts the submenu attached to the CascadeButtonGadget and enables keyboard traversal within the menu. If the CascadeButtonGadget does not have a submenu attached, calls the callbacks in \fIXmNactivateCallback\fP, the CascadeButtonGadget is activated and all posted menus in the cascade are unposted. .IP "\fIKActivate\fP:" Calls the callbacks in \fIXmNcascadingCallback\fP, and posts the submenu attached to the CascadeButtonGadget if keyboard traversal is enabled in the menu. If the CascadeButtonGadget does not have a submenu attached, calls the callbacks in \fIXmNactivateCallback\fP, the CascadeButtonGadget is activated and all posted menus in the cascade are unposted. This action applies only to gadgets in MenuBars, PulldownMenus, and PopupMenus. For a CascadeButtonGadget in an OptionMenu, if the parent is a manager, this action passes the event to the parent. .IP "\fIKSelect\fP:" Calls the callbacks in \fIXmNcascadingCallback\fP, and posts the submenu attached to the CascadeButtonGadget if keyboard traversal is enabled in the menu. If the CascadeButtonGadget does not have a submenu attached, calls the callbacks in \fIXmNactivateCallback\fP, the CascadeButtonGadget is activated and all posted menus in the cascade are unposted. .IP "\fIKHelp\fP:" Unposts all menus in the menu hierarchy and, when the shell's keyboard focus policy is \fIXmEXPLICT\fP, restores keyboard focus to the widget that had the focus before the menu system was entered. Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIMAny\ KCancel\fP:" In a MenuBar, disarms the CascadeButtonGadget and the menu and, when the shell's keyboard focus policy is \fIXmEXPLICT\fP, restores keyboard focus to the widget that had the focus before the menu was entered. For a CascadeButtonGadget in an OptionMenu, if the parent is a manager, this action passes the event to the parent. .P In a toplevel Pulldown MenuPane from a MenuBar, unposts the menu, disarms the MenuBar CascadeButton and the MenuBar, and, when the shell's keyboard focus policy is \fIXmEXPLICT\fP, restores keyboard focus to the widget that had the focus before the MenuBar was entered. In other Pulldown MenuPanes, unposts the menu. .P In a Popup MenuPane, unposts the menu and restores keyboard focus to the widget from which the menu was posted. .IP "\fI\fP:" If keyboard traversal is enabled does nothing. Otherwise, in a MenuBar, unposts any MenuPanes associated with another MenuBar entry, arms the CascadeButtonGadget, and posts the associated submenu. In other menus, arms the CascadeButtonGadget and posts the associated submenu after the delay specified by \fIXmNmappingDelay\fP. .IP "\fI\fP:" If keyboard traversal is enabled does nothing. Otherwise, in a MenuBar, disarms the CascadeButtonGadget if the submenu associated with the CascadeButtonGadget is not currently posted or if there is no submenu associated with the CascadeButtonGadget. .P In other menus, if the pointer moves anywhere except into a submenu associated with the CascadeButtonGadget, the CascadeButtonGadget is disarmed and its submenu is unposted. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .nL .ne 8 .SH RELATED INFORMATION .na \fIObject(3X)\fP, \fIRectObj(3X)\fP, \fIXmCascadeButtonHighlight(3)\fP, \fIXmCreateCascadeButtonGadget(3X)\fP, \fIXmCreatePulldownMenu(3X)\fP, \fIXmCreatePopupMenu(3X)\fP, \fIXmCreateOptionMenu(3X)\fP, \fIXmDisplay(3X)\fP, \fIXmGadget(3X)\fP, \fIXmLabelGadget(3X)\fP, and \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCascadeButtonGadgetHighlight 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCascadeButtonGadgetHighlight\fP \- A CascadeButtonGadget function that sets the highlight state .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmCascadeButtonGadgetHighlight (\fBcascadeButtonGadget, highlight\fI) .ta .5i 1.5i .nf Widget \fBcascadeButtonGadget\fI; Boolean \fBhighlight\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCascadeButtonGadgetHighlight\fP either draws or erases the shadow highlight around the CascadeButtonGadget. .IP "\fBcascadeButtonGadget\fP" Specifies the CascadeButtonGadget to be highlighted or unhighlighted. .IP "\fBhighlight\fP" Specifies whether to highlight (True) or to unhighlight (False). .PP .ne 8 For a complete definition of CascadeButtonGadget and its associated resources, see \fIXmCascadeButtonGadget(3X)\fP. .SH RELATED INFORMATION .na \fIXmCascadeButton(3X)\fP, \fIXmCascadeButtonGadget(3X)\fP, and \fIXmCascadeButtonHighlight(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCascadeButtonHighlight 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCascadeButtonHighlight\fP \- A CascadeButton and CascadeButtonGadget function that sets the highlight state .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu void XmCascadeButtonHighlight (\fBcascadeButton, highlight\fI) .ta .5i 1.5i .nf Widget \fBcascadeButton\fI; Boolean \fBhighlight\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCascadeButtonHighlight\fP either draws or erases the shadow highlight around the CascadeButton or the CascadeButtonGadget. .IP "\fBcascadeButton\fP" Specifies the CascadeButton or CascadeButtonGadget to be highlighted or unhighlighted. .IP "\fBhighlight\fP" Specifies whether to highlight (True) or to unhighlight (False). .PP .ne 5 For a complete definition of CascadeButton or CascadeButtonGadget and their associated resources, see \fIXmCascadeButton(3X)\fP or \fIXmCascadeButtonGadget(3X)\fP. .SH RELATED INFORMATION .na \fIXmCascadeButton(3X)\fP, \fIXmCascadeButtonGadget(3X)\fP and \fIXmCascadeButtonGadgetHighlight(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmChangeColor 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmChangeColor\fP \- Recalculates all associated colors of a widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmChangeColor (\fBwidget, background\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Pixel \fBbackground\fI; .iE .sE .SH DESCRIPTION .fi \fIXmChangeColor\fP handles all color modifications for the specified widget when a new background pixel value is specified. The function recalculates the foreground, select, and shadow colors based on the new background color and sets the corresponding resources for the widget. If a color calculation procedure has been set by a call to \fIXmSetColorCalculation\fP, \fIXmChangeColor\fP uses that procedure to calculate the new colors. Otherwise, the routine uses a default procedure. .IP "\fBwidget\fP" Specifies the widget ID whose colors will be updated .IP "\fBpixel\fP" Specifies the background color pixel value .SH RELATED INFORMATION .na \fIXmGetColorCalculation(3X)\fP, \fIXmGetColors(3X)\fP, and \fIXmSetColorCalculation(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardCancelCopy 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardCancelCopy\fP \- A clipboard function that cancels a copy to the clipboard .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu int \fIXmClipboardCancelCopy\fI (\fBdisplay, window, item_id\fI) .ta .5i 1.5i .nf Display \fB* display\fI; Window \fBwindow\fI; long \fBitem_id\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardCancelCopy\fP cancels the copy to clipboard that is in progress and frees up temporary storage. When a copy is to be performed, \fIXmClipboardStartCopy\fP allocates temporary storage for the clipboard data. \fIXmClipboardCopy\fP copies the appropriate data into the the temporary storage. \fIXmClipboardEndCopy\fP copies the data to the clipboard structure and frees up the temporary storage structures. If \fIXmClipboardCancelCopy\fP is called, the \fIXmClipboardEndCopy\fP function does not have to be called. A call to \fIXmClipboardCancelCopy\fP is valid only after a call to \fIXmClipboardStartCopy\fP and before a call to \fIXmClipboardEndCopy\fP. .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each of the clipboard functions that it calls. .IP "\fBitem_id\fP" Specifies the number assigned to this data item. This number was returned by a previous call to \fIXmClipboardStartCopy\fP. .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .IP "\fIClipboardFail\fP" The function failed because \fIXmClipboardStartCopy\fP was not called or because the data item contains too many formats. .SH RELATED INFORMATION .na \fIXmClipboardCopy(3X)\fP, \fIXmClipboardEndCopy(3X)\fP, and \fIXmClipboardStartCopy(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardCopy 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardCopy\fP \- A clipboard function that copies a data item to temporary storage for later copying to clipboard .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu .ta 1i .nf int \fIXmClipboardCopy\fI (\fBdisplay, window, item_id, format_name, buffer, length, private_id, data_id\fI) .ta .5i 1.65i .nf Display \fB* display\fI; Window \fBwindow\fI; long \fBitem_id\fI; char \fB* format_name\fI; XtPointer \fBbuffer\fI; unsigned long \fBlength\fI; long \fBprivate_id\fI; long \fB* data_id\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardCopy\fP copies a data item to temporary storage. The data item is moved from temporary storage to the clipboard data structure when a call to \fIXmClipboardEndCopy\fP is made. Additional calls to \fIXmClipboardCopy\fP before a call to \fIXmClipboardEndCopy\fP add additional data item formats to the same data item or append data to an existing format. Formats are described in the \fBInter-Client Communication Conventions Manual\fP (ICCCM) as targets. .PP \fINOTE:\fP Do not call \fIXmClipboardCopy\fP before a call to \fIXmClipboardStartCopy\fP has been made. The latter function allocates temporary storage required by \fIXmClipboardCopy\fP. .PP If the \fBbuffer\fP argument is NULL, the data is considered to be passed by name. When data that has been passed by name is later requested by another application, the application that owns the data receives a callback with a request for the data. The application that owns the data must then transfer the data to the clipboard with the \fIXmClipboardCopyByName\fP function. When a data item that was passed by name is deleted from the clipboard, the application that owns the data receives a callback stating that the data is no longer needed. .PP For information on the callback function, see the callback argument description for \fIXmClipboardStartCopy\fP. .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each of the clipboard functions that it calls. .IP "\fBitem_id\fP" Specifies the number assigned to this data item. This number was returned by a previous call to \fIXmClipboardStartCopy\fP. .IP "\fBformat_name\fP" Specifies the name of the format in which the data item is stored on the clipboard. Format is known as target in the ICCCM. .IP "\fBbuffer\fP" Specifies the buffer from which the clipboard copies the data. .IP "\fBlength\fP" Specifies the length of the data being copied to the clipboard. .IP "\fBprivate_id\fP" Specifies the private data that the application wants to store with the data item. .IP "\fBdata_id\fP" Specifies an identifying number assigned to the data item that uniquely identifies the data item and the format. This argument is required only for data that is passed by name. .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .IP "\fIClipboardFail\fP" The function failed because \fIXmClipboardStartCopy\fP was not called or because the data item contains too many formats. .SH RELATED INFORMATION .na \fIXmClipboardCopyByName(3X)\fP, \fIXmClipboardEndCopy(3X)\fP, and \fIXmClipboardStartCopy(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardCopyByName 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardCopyByName\fP \- A clipboard function that copies a data item passed by name .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu .ta 1i .nf int \fIXmClipboardCopyByName\fI (\fBdisplay, window, data_id, buffer, length, private_id\fI) .ta .5i 1.5i .nf Display \fB* display\fI; Window \fBwindow\fI; long \fBdata_id\fI; XtPointer \fBbuffer\fI; unsigned long \fBlength\fI; long \fBprivate_id\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardCopyByName\fP copies the actual data for a data item that was previously passed by name to the clipboard. Data is considered to be passed by name when a call to \fIXmClipboardCopy\fP is made with a NULL buffer parameter. Additional calls to this function append new data to the existing data. .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each clipboard function it calls. .IP "\fBdata_id\fP" Specifies an identifying number assigned to the data item that uniquely identifies the data item and the format. This number was assigned by \fIXmClipboardCopy\fP to the data item. .IP "\fBbuffer\fP" Specifies the buffer from which the clipboard copies the data. .IP "\fBlength\fP" Specifies the number of bytes in the data item. .IP "\fBprivate_id\fP" Specifies the private data that the application wants to store with the data item. .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .SH RELATED INFORMATION .na \fIXmClipboardCopy(3X)\fP, \fIXmClipboardLock(3X)\fP, \fIXmClipboardStartCopy(3X)\fP, and \fIXmClipboardUnlock(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardEndCopy 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardEndCopy\fP \- A clipboard function that ends a copy to the clipboard .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu int \fIXmClipboardEndCopy\fI (\fBdisplay, window, item_id\fI) .ta .5i 1.5i .nf Display \fB* display\fI; Window \fBwindow\fI; long \fBitem_id\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardEndCopy\fP locks the clipboard from access by other applications, places data in the clipboard data structure, and unlocks the clipboard. Data items copied to the clipboard by \fIXmClipboardCopy\fP are not actually entered in the clipboard data structure until the call to \fIXmClipboardEndCopy\fP. .PP This function also frees up temporary storage that was allocated by \fIXmClipboardStartCopy\fP, which must be called before \fIXmClipboardEndCopy\fP. The latter function should not be called if \fIXmClipboardCancelCopy\fP has been called. .nL .ne 7 .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each clipboard function it calls. .IP "\fBitem_id\fP" Specifies the number assigned to this data item. This number was returned by a previous call to \fIXmClipboardStartCopy\fP. .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .IP "\fIClipboardFail\fP" The function failed because \fIXmClipboardStartCopy\fP was not called. .SH RELATED INFORMATION .na \fIXmClipboardCancelCopy(3X)\fP, \fIXmClipboardCopy(3X)\fP and \fIXmClipboardStartCopy(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardEndRetrieve 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardEndRetrieve\fP \- A clipboard function that ends a copy from the clipboard .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu int \fIXmClipboardEndRetrieve\fI (\fBdisplay, window\fI) .ta .5i 1.5i .nf Display \fB* display\fI; Window \fBwindow\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardEndRetrieve\fP suspends copying data incrementally from the clipboard. It tells the clipboard routines that the application is through copying an item from the clipboard. Until this function is called, data items can be retrieved incrementally from the clipboard by calling \fIXmClipboardRetrieve\fP. .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using .ne 3 \fIXtWindow\fP. The same application instance should pass the same window ID to each of the clipboard functions that it calls. .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .SH RELATED INFORMATION .na \fIXmClipboardRetrieve(3X)\fP, \fIXmClipboardStartCopy(3X)\fP, and \fIXmClipboardStartRetrieve(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardInquireCount 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardInquireCount\fP \- A clipboard function that returns the number of data item formats .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu .ta 1i .nf int \fIXmClipboardInquireCount\fI (\fBdisplay, window, count, max_format_name_length\fI) .ta .5i 1.5i .nf Display \fB* display\fI; Window \fBwindow\fI; int \fB* count\fI; unsigned long \fB* max_format_name_length\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardInquireCount\fP returns the number of data item formats available for the data item in the clipboard. This function also returns the maximum name-length for all formats in which the data item is stored. .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each of the clipboard functions that it calls. .IP "\fBcount\fP" Returns the number of data item formats available for the data item in the clipboard. If no formats are available, this argument equals zero. The count includes the formats that were passed by name. .IP "\fBmax_format_name_length\fP" Specifies the maximum length of all format names for the data item in the clipboard. .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .IP "\fIClipboardNoData\fP" The function could not find data on the clipboard corresponding to the format requested. This could occur because the clipboard is empty; there is data on the clipboard but not in the requested format; or the data in the requested format was passed by name and is no longer available. .SH RELATED INFORMATION .na \fIXmClipboardStartCopy(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardInquireFormat 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardInquireFormat\fP \- A clipboard function that returns a specified format name .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu .ta 1i .nf int \fIXmClipboardInquireFormat\fI (\fBdisplay, window, index, format_name_buf, buffer_len, copied_len\fI) .ta .5i 1.6i .nf Display \fB* display\fI; Window \fBwindow\fI; int \fBindex\fI; XtPointer \fBformat_name_buf\fI; unsigned long \fBbuffer_len\fI; unsigned long \fB* copied_len\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardInquireFormat\fP returns a specified format name for the data item in the clipboard. If the name must be truncated, the function returns a warning status. .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each of the clipboard functions that it calls. .IP "\fBindex\fP" Specifies which of the ordered format names to obtain. If this index is greater than the number of formats for the data item, this function returns a zero in the \fBcopied_len\fP argument. .IP "\fBformat_name_buf\fP" Specifies the buffer that receives the format name. .IP "\fBbuffer_len\fP" Specifies the number of bytes in the format name buffer. .IP "\fBcopied_len\fP" Specifies the number of bytes in the string copied to the buffer. If this argument equals zero, there is no \fBnth\fP format for the data item. .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .nL .ne 8 .IP "\fIClipboardTruncate\fP" The data returned is truncated because the user did not provide a buffer large enough to hold the data. .IP "\fIClipboardNoData\fP" The function could not find data on the clipboard corresponding to the format requested. This could occur because the clipboard is empty; there is data on the clipboard but not in the requested format; or the data in the requested format was passed by name and is no longer available. .SH RELATED INFORMATION .na \fIXmClipboardStartCopy(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardInquireLength 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardInquireLength\fP \- A clipboard function that returns the length of the stored data .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu int \fIXmClipboardInquireLength\fI (\fBdisplay, window, format_name, length\fI) .ta .5i 1.5i .nf Display \fB* display\fI; Window \fBwindow\fI; char \fB* format_name\fI; unsigned long \fB* length\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardInquireLength\fP returns the length of the data stored under a specified format name for the clipboard data item. If no data is found for the specified format, or if there is no item on the clipboard, this function returns a value of zero. .PP Any format passed by name is assumed to have the \fBlength\fP passed in a call to \fIXmClipboardCopy\fP, even though the data has not yet been transferred to the clipboard in that format. .nL .ne 7 .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each of the clipboard functions that it calls. .IP "\fBformat_name\fP" Specifies the name of the format for the data item. .IP "\fBlength\fP" Specifies the length of the next data item in the specified format. This argument equals zero if no data is found for the specified format, or if there is no item on the clipboard. .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .IP "\fIClipboardNoData\fP" The function could not find data on the clipboard corresponding to the format requested. This could occur because the clipboard is empty; there is data on the clipboard but not in the requested format; or the data in the requested format was passed by name and is no longer available. .SH RELATED INFORMATION .na \fIXmClipboardCopy(3X)\fP and \fIXmClipboardStartCopy(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardInquirePendingItems 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardInquirePendingItems\fP \- A clipboard function that returns a list of \fBdata_id/private_id\fP pairs .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu .ta 1i .nf int \fIXmClipboardInquirePendingItems\fI (\fBdisplay, window, format_name, item_list, count\fI) .ta .5i 2.25i .nf Display \fB* display\fI; Window \fBwindow\fI; char \fB* format_name\fI; XmClipboardPendingList \fB* item_list\fI; unsigned long \fB* count\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardInquirePendingItems\fP returns a list of \fBdata_id/private_id\fP pairs for the specified format name. A data item is considered pending if the application originally passed it by name, the application has not yet copied the data, and the item has not been deleted from the clipboard. The application is responsible for freeing the memory provided by this function to store the list. To free the memory, call \fIXtFree\fP. .PP This function is used by an application when exiting, to determine if the data that is passed by name should be sent to the clipboard. .nL .ne 7 .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each of the clipboard functions that it calls. .IP "\fBformat_name\fP" Specifies a string that contains the name of the format for which the list of data ID/private ID pairs is to be obtained. .IP "\fBitem_list\fP" Specifies the address of the array of data ID/private ID pairs for the specified format name. This argument is a type \fIXmClipboardPendingList\fP. The application is responsible for freeing the memory provided by this function for storing the list. .IP "\fBcount\fP" Specifies the number of items returned in the list. If there is no data for the specified format name, or if there is no item on the clipboard, this argument equals zero. .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .SH RELATED INFORMATION .na \fIXmClipboardStartCopy(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardLock 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardLock\fP \- A clipboard function that locks the clipboard .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu int \fIXmClipboardLock\fI (\fBdisplay, window\fI) .ta .5i 1.5i .nf Display \fB* display\fI; Window \fBwindow\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardLock\fP locks the clipboard from access by another application until \fIXmClipboardUnlock\fP is called. All clipboard functions lock and unlock the clipboard to prevent simultaneous access. This function allows the application to keep the clipboard data from changing between calls to \fIInquire\fP and other clipboard functions. The application does not need to lock the clipboard between calls to \fIXmClipboardStartCopy\fP and \fIXmClipboardEndCopy\fP or to \fIXmClipboardStartRetrieve\fP and \fIXmClipboardEndRetrieve\fP. .PP If the clipboard is already locked by another application, \fIXmClipboardLock\fP returns an error status. Multiple calls to this function by the same application increases the lock level. .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each of the clipboard functions that it calls. .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .SH RELATED INFORMATION .na \fIXmClipboardEndCopy(3X)\fP, \fIXmClipboardEndRetrieve(3X)\fP, \fIXmClipboardStartCopy(3X)\fP, \fIXmClipboardStartRetrieve(3X)\fP, and \fIXmClipboardUnlock(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardRegisterFormat 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardRegisterFormat\fP \- A clipboard function that registers a new format .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu int \fIXmClipboardRegisterFormat\fI (\fBdisplay, format_name, format_length\fI) .ta .5i 1.75i .nf Display \fB* display\fI; char \fB* format_name\fI; int \fBformat_length\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardRegisterFormat\fP registers a new format. Each format stored on the clipboard should have a length associated with it; this length must be known to the clipboard routines. Formats are known as targets in the \fBInter-Client Communication Conventions Manual\fP (ICCCM). All of the formats specified by the ICCCM conventions are preregistered. Any other format that the application wants to use must either be 8-bit data or be registered via this routine. Failure to register the length of the data results in incompatible applications across platforms having different byte-swapping orders. .nL .ne 9 .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBformat_name\fP" Specifies the string name for the new format (target). .IP "\fBformat_length\fP" Specifies the format length in bits (8, 16, or 32). .SH RETURN VALUE .IP "\fIClipboardBadFormat\fP" The \fBformat_name\fP must not be NULL, and the \fBformat_length\fP must be 8, 16, or 32. .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .IP "\fIClipboardFail\fP" The function failed because the format was already registered with this length. .SH RELATED INFORMATION .na \fIXmClipboardStartCopy(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardRetrieve 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardRetrieve\fP \- A clipboard function that retrieves a data item from the clipboard .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu .ta 1i .nf int \fIXmClipboardRetrieve\fI (\fBdisplay, window, format_name, buffer, length, num_bytes, private_id\fI) .ta .5i 1.65i .nf Display \fB* display\fI; Window \fBwindow\fI; char \fB* format_name\fI; XtPointer \fBbuffer\fI; unsigned long \fBlength\fI; unsigned long \fB* num_bytes\fI; long \fB* private_id\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardRetrieve\fP retrieves the current data item from clipboard storage. It returns a warning if the clipboard is locked; if there is no data on the clipboard; or if the data needs to be truncated because the buffer length is too short. .PP .ne 4 Between a call to \fIXmClipboardStartRetrieve\fP and a call to \fIXmClipboardEndRetrieve\fP, multiple calls to \fIXmClipboardRetrieve\fP with the same format name result in data being incrementally copied from the clipboard until the data in that format has all been copied. .PP The return value \fIClipboardTruncate\fP from calls to \fIXmClipboardRetrieve\fP indicates that more data remains to be copied in the given format. It is recommended that any calls to the \fIInquire\fP functions that the application needs to make to effect the copy from the clipboard be made between the call to \fIXmClipboardStartRetrieve\fP and the first call to \fIXmClipboardRetrieve\fP. That way, the application does not need to call \fIXmClipboardLock\fP and \fIXmClipboardUnlock\fP. .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each of the clipboard functions that it calls. .IP "\fBformat_name\fP" Specifies the name of a format in which the data is stored on the clipboard. .IP "\fBbuffer\fP" Specifies the buffer to which the application wants the clipboard to copy the data. .IP "\fBlength\fP" Specifies the length of the application buffer. .IP "\fBnum_bytes\fP" Specifies the number of bytes of data copied into the application buffer. .IP "\fBprivate_id\fP" Specifies the private data stored with the data item by the application that placed the data item on the clipboard. If the application did not store private data with the data item, this argument returns zero. .nL .ne 20 .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .IP "\fIClipboardTruncate\fP" The data returned is truncated because the user did not provide a buffer large enough to hold the data. .IP "\fIClipboardNoData\fP" The function could not find data on the clipboard corresponding to the format requested. This could occur because the clipboard is empty; there is data on the clipboard but not in the requested format; or the data in the requested format was passed by name and is no longer available. .SH RELATED INFORMATION .na \fIXmClipboardEndRetrieve(3X)\fP, \fIXmClipboardLock(3X)\fP, \fIXmClipboardStartCopy(3X)\fP, \fIXmClipboardStartRetrieve(3X)\fP, and \fIXmClipboardUnlock(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardStartCopy 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardStartCopy\fP \- A clipboard function that sets up a storage and data structure .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu .ta 1i .nf int \fIXmClipboardStartCopy\fI (\fBdisplay, window, clip_label, timestamp, widget, callback, item_id\fI) .ta .5i 1.5i .nf Display \fB* display\fI; Window \fBwindow\fI; XmString \fBclip_label\fI; Time \fBtimestamp\fI; Widget \fBwidget\fI; XmCutPasteProc \fBcallback\fI; long \fB* item_id\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardStartCopy\fP sets up storage and data structures to receive clipboard data. An application calls this function during a cut or copy operation. The data item that these structures receive then becomes the next data item in the clipboard. .PP Copying a large piece of data to the clipboard can take a long time. It is possible that, once copied, no application will ever request that data. The Motif Toolkit provides a mechanism so that an application does not need to actually pass data to the clipboard until the data has been requested by some application. .PP Instead, the application passes format and length information in \fIXmClipboardCopy\fP to the clipboard functions, along with a widget ID and a callback function address that is passed in \fIXmClipboardStartCopy\fP. The widget ID is needed for communications between the clipboard functions in the application that owns the data and the clipboard functions in the application that requests the data. .PP The callback functions are responsible for copying the actual data to the clipboard via \fIXmClipboardCopyByName\fP. The callback function is also called if the data item is removed from the clipboard, and the actual data is therefore no longer needed. .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each of the clipboard functions that it calls. .IP "\fBclip_label\fP" Specifies the label to be associated with the data item. This argument is used to identify the data item, for example, in a clipboard viewer. An example of a label is the name of the application that places the data in the clipboard. .IP "\fBtimestamp\fP" Specifies the time of the event that triggered the copy. A valid timestamp must be supplied; it is not sufficient to use \fICurrentTime\fP. .IP "\fBwidget\fP" Specifies the ID of the widget that receives messages requesting data previously passed by name. This argument must be present in order to pass data by name. Any valid widget ID in your application can be used for this purpose and all the message handling is taken care of by the cut and paste functions. .IP "\fBcallback\fP" Specifies the address of the callback function that is called when the clipboard needs data that was originally passed by name. This is also the callback to receive the \fIdelete\fP message for items that were originally passed by name. This argument must be present in order to pass data by name. .IP "\fBitem_id\fP" Specifies the number assigned to this data item. The application uses this number in calls to \fIXmClipboardCopy\fP, \fIXmClipboardEndCopy\fP, and \fIXmClipboardCancelCopy\fP. .PP For more information on passing data by name, see \fIXmClipboardCopy(3X)\fP and \fIXmClipboardCopyByName(3X)\fP. .PP The \fBwidget\fP and \fBcallback\fP arguments must be present in order to pass data by name. The callback format is as follows: .sS .iS .ta .25i 1.2i .nf void (*\fBcallback)\fI (\fBwidget, data_id, private, reason\fI) Widget \fBwidget\fI; int *\fBdata_id\fI; int *\fBprivate\fI; int *\fBreason\fI; .iE .sE .wH .fi .IP "\fBwidget\fP" Specifies the ID of the widget passed to this function. .IP "\fBdata_id\fP" Specifies the identifying number returned by \fIXmClipboardCopy\fP, which identifies the pass-by-name data. .IP "\fBprivate\fP" Specifies the private information passed to \fIXmClipboardCopy\fP. .IP "\fBreason\fP" Specifies the reason, which is either \fIXmCR_CLIPBOARD_DATA_DELETE\fP or \fIXmCR_CLIPBOARD_DATA_REQUEST\fP. .nL .ne 15 .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .SH RELATED INFORMATION .na \fIXmClipboardCancelCopy(3X)\fP, \fIXmClipboardCopy(3X)\fP, \fIXmClipboardCopyByName(3X)\fP, \fIXmClipboardEndCopy(3X)\fP, \fIXmClipboardEndRetrieve(3X)\fP, \fIXmClipboardInquireCount(3X)\fP, \fIXmClipboardInquireFormat(3X)\fP, \fIXmClipboardInquireLength(3X)\fP, \fIXmClipboardInquirePendingItems(3X)\fP, \fIXmClipboardLock(3X)\fP, \fIXmClipboardRegisterFormat(3X)\fP, \fIXmClipboardRetrieve(3X)\fP, \fIXmClipboardStartRetrieve(3X)\fP, \fIXmClipboardUndoCopy(3X)\fP, \fIXmClipboardUnlock(3X)\fP, and \fIXmClipboardWithdrawFormat(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardStartRetrieve 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardStartRetrieve\fP \- A clipboard function that starts a copy from the clipboard .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu int \fIXmClipboardStartRetrieve\fI (\fBdisplay, window, timestamp\fI) .ta .5i 1.5i .nf Display \fB* display\fI; Window \fBwindow\fI; Time \fBtimestamp\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardStartRetrieve\fP tells the clipboard routines that the application is ready to start copying an item from the clipboard. The clipboard is locked by this routine and stays locked until \fIXmClipboardEndRetrieve\fP is called. Between a call to \fIXmClipboardStartRetrieve\fP and a call to \fIXmClipboardEndRetrieve\fP, multiple calls to \fIXmClipboardRetrieve\fP with the same format name result in data being incrementally copied from the clipboard until the data in that format has all been copied. .PP The return value \fIClipboardTruncate\fP from calls to \fIXmClipboardRetrieve\fP indicates that more data remains to be copied in the given format. It is recommended that any calls to the \fIInquire\fP functions that the application needs to make to effect the copy from the clipboard be made between the call to \fIXmClipboardStartRetrieve\fP and the first call to \fIXmClipboardRetrieve\fP. That way, the application does not need to call \fIXmClipboardLock\fP and \fIXmClipboardUnlock\fP. .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each of the clipboard functions that it calls. .IP "\fBtimestamp\fP" Specifies the time of the event that triggered the copy. A valid timestamp must be supplied; it is not sufficient to use \fICurrentTime\fP. .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .nL .ne 10 .SH RELATED INFORMATION .na \fIXmClipboardEndRetrieve(3X)\fP, \fIXmClipboardInquireCount(3X)\fP, \fIXmClipboardInquireFormat(3X)\fP, \fIXmClipboardInquireLength(3X)\fP, \fIXmClipboardInquirePendingItems(3X)\fP, \fIXmClipboardLock(3X)\fP, \fIXmClipboardRetrieve(3X)\fP, \fIXmClipboardStartCopy(3X)\fP, and \fIXmClipboardUnlock(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardUndoCopy 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardUndoCopy\fP \- A clipboard function that deletes the last item placed on the clipboard .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu int \fIXmClipboardUndoCopy\fI (\fBdisplay, window\fI) .ta .5i 1.5i .nf Display \fB* display\fI; Window \fBwindow\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardUndoCopy\fP deletes the last item placed on the clipboard if the item was placed there by an application with the passed \fBdisplay\fP and \fBwindow\fP arguments. Any data item deleted from the clipboard by the original call to \fIXmClipboardCopy\fP is restored. If the \fBdisplay\fP or \fBwindow\fP IDs do not match the last copied item, no action is taken, and this function has no effect. .nL .ne 12 .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each clipboard function it calls. .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .SH RELATED INFORMATION .na \fIXmClipboardLock(3X)\fP and \fIXmClipboardStartCopy(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardUnlock 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardUnlock\fP \- A clipboard function that unlocks the clipboard .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu int \fIXmClipboardUnlock\fI (\fBdisplay, window, remove_all_locks\fI) .ta .5i 1.5i .nf Display \fB* display\fI; Window \fBwindow\fI; Boolean \fBremove_all_locks\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardUnlock\fP unlocks the clipboard, enabling it to be accessed by other applications. .PP If multiple calls to \fIXmClipboardLock\fP have occurred, the same number of calls to \fIXmClipboardUnlock\fP is necessary to unlock the clipboard, unless \fBremove_all_locks\fP is set to True. .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .nL .ne 4 .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each of the clipboard functions that it calls. .IP "\fBremove_all_locks\fP" When True, indicates that all nested locks should be removed. When False, indicates that only one level of lock should be removed. .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardFail\fP" The function failed because the clipboard was not locked or was locked by another application. .SH RELATED INFORMATION .na \fIXmClipboardCancelCopy(3X)\fP, \fIXmClipboardCopy(3X)\fP, \fIXmClipboardEndCopy(3X)\fP, \fIXmClipboardEndRetrieve(3X)\fP, \fIXmClipboardInquireCount(3X)\fP, \fIXmClipboardInquireFormat(3X)\fP, \fIXmClipboardInquireLength(3X)\fP, \fIXmClipboardInquirePendingItems(3X)\fP, \fIXmClipboardLock(3X)\fP, \fIXmClipboardRegisterFormat(3X)\fP, \fIXmClipboardRetrieve(3X)\fP, \fIXmClipboardStartCopy(3X)\fP, \fIXmClipboardStartRetrieve(3X)\fP, \fIXmClipboardUndoCopy(3X)\fP, and \fIXmClipboardWithdrawFormat(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmClipboardWithdrawFormat 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmClipboardWithdrawFormat\fP \- A clipboard function that indicates that the application no longer wants to supply a data item .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu int \fIXmClipboardWithdrawFormat\fI (\fBdisplay, window, data_id\fI) .ta .5i 1.5i .nf Display \fB* display\fI; Window \fBwindow\fI; long \fBdata_id\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmClipboardWithdrawFormat\fP indicates that the application no longer supplies a data item to the clipboard that the application had previously passed by name. .nL .ne 15 .IP "\fBdisplay\fP" Specifies a pointer to the \fIDisplay\fP structure that was returned in a previous call to \fIXOpenDisplay\fP or \fIXtDisplay\fP. .IP "\fBwindow\fP" Specifies a widget's window ID that relates the application window to the clipboard. The widget's window ID can be obtained by using \fIXtWindow\fP. The same application instance should pass the same window ID to each clipboard function it calls. .IP "\fBdata_id\fP" Specifies an identifying number assigned to the data item that uniquely identifies the data item and the format. This was assigned to the item when it was originally passed by \fIXmClipboardCopy\fP. .SH RETURN VALUE .IP "\fIClipboardSuccess\fP" The function is successful. .IP "\fIClipboardLocked\fP" The function failed because the clipboard was locked by another application. The application can continue to call the function again with the same parameters until the lock goes away. This gives the application the opportunity to ask if the user wants to keep trying or to give up on the operation. .SH RELATED INFORMATION .na \fIXmClipboardCopy(3X)\fP and \fIXmClipboardStartCopy(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCommand 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCommand\fP \- The Command widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi Command is a special-purpose composite widget for command entry that provides a built-in command-history mechanism. Command includes a command-line text-input field, a command-line prompt, and a command-history list region. .PP One additional \fIWorkArea\fP child may be added to the Command after creation. .PP Whenever a command is entered, it is automatically added to the end of the command-history list and made visible. This does not change the selected item in the list, if there is one. .PP Many of the new resources specified for Command are actually SelectionBox resources that have been renamed for clarity and ease of use. .nL .ne 10 .SS "Classes" Command inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIConstraint\fP, \fIXmManager\fP, \fIXmBulletinBoard\fP, and \fIXmSelectionBox\fP classes. .PP The class pointer is \fIxmCommandWidgetClass\fP. .PP The class name is \fIXmCommand\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmCommand Resource Set Name Class Type Default Access _ XmNcommand XmCTextString XmString "" CSG XmNcommandChangedCallback XmCCallback XtCallbackList NULL C XmNcommandEnteredCallback XmCCallback XtCallbackList NULL C XmNhistoryItems XmCItems XmStringTable NULL CSG XmNhistoryItemCount XmCItemCount int 0 CSG XmNhistoryMaxItems XmCMaxItems int 100 CSG XmNhistoryVisibleItemCount XmCVisibleItemCount int dynamic CSG XmNpromptString XmCPromptString XmString dynamic CSG .TE .KE .in .sp 1 .IP "\fIXmNcommand\fP" Contains the current command-line text. This is the \fIXmNtextString\fP resource in SelectionBox, renamed for Command. This resource can also be modified via \fIXmCommandSetValue\fP and \fIXmCommandAppendValue\fP functions. The command area is a Text widget. .IP "\fIXmNcommandChangedCallback\fP" Specifies the list of callbacks that is called when the value of the command changes. The callback reason is \fIXmCR_COMMAND_CHANGED\fP. This is equivalent to the \fIXmNvalueChangedCallback\fP of the Text widget, except that a pointer to an \fIXmCommandCallbackStructure\fP is passed, and the structure's \fBvalue\fP member contains the \fIXmString\fP. .nL .ne 8 .IP "\fIXmNcommandEnteredCallback\fP" Specifies the list of callbacks that is called when a command is entered in the Command. The callback reason is \fIXmCR_COMMAND_ENTERED\fP. A pointer to an \fIXmCommandCallback\fP structure is passed. .IP "\fIXmNhistoryItems\fP" Lists \fIXmString\fP items that make up the contents of the history list. This is the \fIXmNlistItems\fP resource in SelectionBox, renamed for Command. \fIXtGetValues\fP for this resource returns the list items themselves, not a copy of the list items. The application must not free the returned items. .IP "\fIXmNhistoryItemCount\fP" Specifies the number of \fIXmStrings\fP in \fIXmNhistoryItems\fP. This is the \fIXmNlistItemCount\fP resource in SelectionBox, renamed for Command. The value must not be negative. .IP "\fIXmNhistoryMaxItems\fP" Specifies the maximum number of items allowed in the history list. Once this number is reached, an existing list item must be removed before a new item can be added to the list. For each command entered, the first list item is removed from the list, so the new command can be added to the list. The value must be greater than 0. .IP "\fIXmNhistoryVisibleItemCount\fP" Specifies the number of items in the history list that should be visible at one time. In effect, it sets the height (in lines) of the history list window. This is the \fIXmNlistVisibleItemCount\fP resource in SelectionBox, renamed for Command. The value must be greater than 0. The default is dynamic based on the height of the list. .IP "\fIXmNpromptString\fP" Specifies a prompt for the command line. This is the \fIXmNselectionLabelString\fP resource in SelectionBox, renamed for Command. The default may vary depending on the value of the \fIXmNstringDirection\fP resource and the locale. In the C locale the default is ">". .SS "Inherited Resources" Command inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmSelectionBox Resource Set Name Class Type Default Access _ XmNapplyCallback XmCCallback XtCallbackList NULL N/A XmNapplyLabelString XmCApplyLabelString XmString dynamic N/A XmNcancelCallback XmCCallback XtCallbackList NULL N/A XmNcancelLabelString XmCCancelLabelString XmString dynamic N/A XmNchildPlacement XmCChildPlacement unsigned char XmPLACE_ABOVE_SELECTION CSG XmNdialogType XmCDialogType unsigned char XmDIALOG_COMMAND G XmNhelpLabelString XmCHelpLabelString XmString dynamic N/A XmNlistItemCount XmCItemCount int 0 CSG XmNlistItems XmCItems XmStringTable NULL CSG XmNlistLabelString XmCListLabelString XmString NULL N/A XmNlistVisibleItemCount XmCVisibleItemCount int dynamic CSG XmNminimizeButtons XmCMinimizeButtons Boolean False N/A XmNmustMatch XmCMustMatch Boolean False N/A XmNnoMatchCallback XmCCallback XtCallbackList NULL N/A .wH .tH XmNokCallback XmCCallback XtCallbackList NULL N/A XmNokLabelString XmCOkLabelString XmString dynamic N/A XmNselectionLabelString XmCSelectionLabelString XmString dynamic CSG XmNtextAccelerators XmCTextAccelerators XtAccelerators default C XmNtextColumns XmCColumns short dynamic CSG XmNtextString XmCTextString XmString "" CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmBulletinBoard Resource Set Name Class Type Default Access _ XmNallowOverlap XmCAllowOverlap Boolean True CSG XmNautoUnmanage XmCAutoUnmanage Boolean False N/A XmNbuttonFontList XmCButtonFontList XmFontList dynamic N/A XmNcancelButton XmCWidget Widget NULL N/A XmNdefaultButton XmCWidget Widget NULL N/A XmNdefaultPosition XmCDefaultPosition Boolean False CSG XmNdialogStyle XmCDialogStyle unsigned char dynamic CSG XmNdialogTitle XmCDialogTitle XmString NULL CSG XmNfocusCallback XmCCallback XtCallbackList NULL C XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG XmNmapCallback XmCCallback XtCallbackList NULL C XmNmarginHeight XmCMarginHeight Dimension 10 CSG XmNmarginWidth XmCMarginWidth Dimension 10 CSG XmNnoResize XmCNoResize Boolean False CSG .wH .tH XmNresizePolicy XmCResizePolicy unsigned char XmRESIZE_NONE CSG XmNshadowType XmCShadowType unsigned char XmSHADOW_OUT CSG XmNtextFontList XmCTextFontList XmFontList dynamic CSG XmNtextTranslations XmCTranslations XtTranslations NULL C XmNunmapCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmManager Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget dynamic CSG XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension dynamic CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic N/A XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" .P A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.1i .nf typedef struct { int \fBreason\fI; XEvent \fB* event\fI; XmString \fBvalue\fI; int \fBlength\fI; } XmCommandCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback .IP "\fBvalue\fP" Specifies the \fIXmString\fP in the CommandArea .IP "\fBlength\fP" Specifies the size of the command in \fIXmString\fP .SS "Translations" XmCommand inherits translations from XmSelectionBox. .SS "Accelerators" The \fIXmNtextAccelerators\fP from XmSelectionBox are added to the Text descendant of XmCommand. .SS "Action Routines" The XmCommand action routines are described below: .IP "\fISelectionBoxUpOrDown(0|1|2|3)\fP:" When called with a 0 argument, selects the previous item in the history list and replaces the text with that item. .P When called with a 1 argument, selects the next item in the history list and replaces the text with that item. .P When called with a 2 argument, selects the first item in the history list and replaces the text with that item. .P When called with a 3 argument, selects the last item in the history list and replaces the text with that item. .P Calls the callbacks for \fIXmNcommandChangedCallback\fP. .SS "Additional Behavior" The Command widget has the additional behavior described below: .IP "\fIMAny KCancel\fP:" If the parent of the Command is a manager, the event is passed to the parent. .IP "\fIKActivate\fP\ in\ Text:" Calls the Text widget's \fIXmNactivateCallback\fP callbacks. If the text is empty, this action then returns. Otherwise, if the history list has \fIXmNhistoryMaxItems\fP items, it removes the first item in the list. .ne 6 It adds the text to the history list as the last item, clears the text, and calls the \fIXmNcommandEnteredCallback\fP callbacks. .IP "\fI\fP\ in\ Text:" When any change is made to the text edit widget, this action calls the callbacks for \fIXmNcommandChangedCallback\fP. .IP "\fI\fP\ or\ \fI\fP\ in\ List:" Calls the List widget's \fIXmNdefaultActionCallback\fP callbacks. If the history list has \fIXmNhistoryMaxItems\fP items, this action removes the first item in the list. It adds the selected List item to the history list as the last item, clears the text, and calls the \fIXmNcommandEnteredCallback\fP callbacks. .IP "\fI\fP:" Calls the callbacks for \fIXmNfocusCallback\fP. .IP "\fI\fP:" When a Command that is the child of a DialogShell is mapped, this action calls the callbacks for \fIXmNmapCallback\fP. .IP "\fI\fP:" When a Command that is the child of a DialogShell is unmapped, this action calls the callbacks for \fIXmNunmapCallback\fP. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fIConstraint(3X)\fP, \fICore(3X)\fP, \fIXmBulletinBoard(3X)\fP, \fIXmCommandAppendValue(3X)\fP, \fIXmCommandError(3X)\fP, \fIXmCommandGetChild(3X)\fP, \fIXmCommandSetValue(3X)\fP, \fIXmCreateCommand(3X)\fP, \fIXmManager(3X)\fP, and \fIXmSelectionBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCommandAppendValue 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCommandAppendValue\fP \- A Command function that appends the passed XmString to the end of the string displayed in the command area of the widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmCommandAppendValue (\fBwidget, command\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString \fBcommand\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCommandAppendValue\fP appends the passed \fIXmString\fP to the end of the string displayed in the command area of the Command widget. .IP "\fBwidget\fP" Specifies the Command widget ID .IP "\fBcommand\fP" Specifies the passed \fIXmString\fP .PP For a complete definition of Command and its associated resources, see \fIXmCommand(3X)\fP. .SH RELATED INFORMATION .na \fIXmCommand(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCommandError 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCommandError\fP \- A Command function that displays an error message .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmCommandError (\fBwidget, error\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString \fBerror\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCommandError\fP displays an error message in the history area of the Command widget. The \fIXmString\fP error is displayed until the next command entered occurs. .IP "\fBwidget\fP" Specifies the Command widget ID .IP "\fBerror\fP" Specifies the passed \fIXmString\fP .PP For a complete definition of Command and its associated resources, see \fIXmCommand(3X)\fP. .SH RELATED INFORMATION .na \fIXmCommand(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCommandGetChild 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCommandGetChild\fP \- A Command function that is used to access a component .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCommandGetChild (\fBwidget, child\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; unsigned char \fBchild\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCommandGetChild\fP is used to access a component within a Command. The parameters given to the function are the Command widget and a value indicating which component to access. .IP "\fBwidget\fP" Specifies the Command widget ID. .IP "\fBchild\fP" Specifies a component within the Command. The following are legal values for this parameter: .TP \(bu \fIXmDIALOG_COMMAND_TEXT\fP .TP \(bu \fIXmDIALOG_PROMPT_LABEL\fP .TP \(bu \fIXmDIALOG_HISTORY_LIST\fP .TP \(bu \fIXmDIALOG_WORK_AREA\fP .PP For a complete definition of Command and its associated resources, see \fIXmCommand(3X)\fP. .SH RETURN VALUE Returns the widget ID of the specified Command component. An application should not assume that the returned widget will be of any particular class. .SH RELATED INFORMATION .na \fIXmCommand(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCommandSetValue 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCommandSetValue\fP \- A Command function that replaces a displayed string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmCommandSetValue (\fBwidget, command\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString \fBcommand\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCommandSetValue\fP replaces the string displayed in the command area of the Command widget with the passed \fIXmString\fP. .IP "\fBwidget\fP" Specifies the Command widget ID .IP "\fBcommand\fP" Specifies the passed \fIXmString\fP .PP For a complete definition of Command and its associated resources, see \fIXmCommand(3X)\fP. .SH RELATED INFORMATION .na \fIXmCommand(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmConvertUnits 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmConvertUnits\fP \- A function that converts a value in one unit type to another unit type .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf int XmConvertUnits (\fBwidget, orientation, from_unit_type, from_value, to_unit_type\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBorientation\fI; int \fBfrom_unit_type\fI; int \fBfrom_value\fI; int \fBto_unit_type\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmConvertUnits\fP converts the value and returns it as the return value from the function. .IP "\fBwidget\fP" Specifies the widget for which the data is to be converted .nL .ne 6 .IP "\fBorientation\fP" Specifies whether the converter uses the horizontal or vertical screen resolution when performing the conversions. \fBorientation\fP can have values of \fIXmHORIZONTAL\fP or \fIXmVERTICAL\fP. .IP "\fBfrom_unit_type\fP" Specifies the current unit type of the supplied value .IP "\fBfrom_value\fP" Specifies the value to be converted .IP "\fBto_unit_type\fP" Converts the value to the unit type specified .PP The parameters \fBfrom_unit_type\fP and \fBto_unit_type\fP can have the following values: .TP \(bu \fIXmPIXELS\fP \- all values provided to the widget are treated as normal pixel values. This is the default for the resource. .TP \(bu \fIXm100TH_MILLIMETERS\fP \- all values provided to the widget are treated as 1/100 millimeter. .TP \(bu \fIXm1000TH_INCHES\fP \- all values provided to the widget are treated as 1/1000 inch. .TP \(bu \fIXm100TH_POINTS\fP \- all values provided to the widget are treated as 1/100 point. A point is a unit typically used in text processing applications and is defined as 1/72 inch. .TP \(bu \fIXm100TH_FONT_UNITS\fP \- all values provided to the widget are treated as 1/100 of a font unit. A font unit has horizontal and vertical components. These are the values of the XmScreen resources \fIXmNhorizontalFontUnit\fP and \fIXmNverticalFontUnit\fP. .SH RETURN VALUE Returns the converted value. If a NULL widget, incorrect \fBorientation\fP, or incorrect \fBunit_type\fP is supplied as parameter data, 0 is returned. .SH RELATED INFORMATION .na \fIXmSetFontUnits(3X)\fP and \fIXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateArrowButton 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateArrowButton\fP \- The ArrowButton widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateArrowButton (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateArrowButton\fP creates an instance of an ArrowButton widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of ArrowButton and its associated resources, see \fIXmArrowButton(3X)\fP. .SH RETURN VALUE Returns the ArrowButton widget ID. .SH RELATED INFORMATION .na \fIXmArrowButton(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateArrowButtonGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateArrowButtonGadget\fP \- The ArrowButtonGadget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateArrowButtonGadget (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateArrowButtonGadget\fP creates an instance of an ArrowButtonGadget widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of ArrowButtonGadget and its associated resources, see \fIXmArrowButtonGadget(3X)\fP. .SH RETURN VALUE Returns the ArrowButtonGadget widget ID. .SH RELATED INFORMATION .na \fIXmArrowButtonGadget(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateBulletinBoard 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateBulletinBoard\fP \- The BulletinBoard widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateBulletinBoard (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateBulletinBoard\fP creates an instance of a BulletinBoard widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of BulletinBoard and its associated resources, see \fIXmBulletinBoard(3X)\fP. .SH RETURN VALUE Returns the BulletinBoard widget ID. .SH RELATED INFORMATION .na \fIXmBulletinBoard(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateBulletinBoardDialog 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateBulletinBoardDialog\fP \- The BulletinBoard BulletinBoardDialog convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateBulletinBoardDialog (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateBulletinBoardDialog\fP is a convenience creation function that creates a DialogShell and an unmanaged BulletinBoard child of the DialogShell. A BulletinBoardDialog is used for interactions not supported by the standard dialog set. This function does not automatically create any labels, buttons, or other dialog components. Such components should be added by the application after the BulletinBoardDialog is created. .PP Use \fIXtManageChild\fP to pop up the BulletinBoardDialog (passing the BulletinBoard as the widget parameter); use \fIXtUnmanageChild\fP to pop it down. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of BulletinBoard and its associated resources, see \fIXmBulletinBoard(3X)\fP. .SH RETURN VALUE Returns the BulletinBoard widget ID. .SH RELATED INFORMATION .na \fIXmBulletinBoard(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateCascadeButton 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateCascadeButton\fP \- The CascadeButton widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateCascadeButton (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateCascadeButton\fP creates an instance of a CascadeButton widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID. The parent must be a RowColumn widget. .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of CascadeButton and its associated resources, see \fIXmCascadeButton(3X)\fP. .SH RETURN VALUE Returns the CascadeButton widget ID. .SH RELATED INFORMATION .na \fIXmCascadeButton(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateCascadeButtonGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateCascadeButtonGadget\fP \- The CascadeButtonGadget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateCascadeButtonGadget (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateCascadeButtonGadget\fP creates an instance of a CascadeButtonGadget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID. The parent must be a RowColumn widget. .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of CascadeButtonGadget and its associated resources, see \fIXmCascadeButtonGadget(3X)\fP. .SH RETURN VALUE Returns the CascadeButtonGadget widget ID. .SH RELATED INFORMATION .na \fIXmCascadeButtonGadget(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateCommand 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateCommand\fP \- The Command widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateCommand (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateCommand\fP creates an instance of a Command widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of Command and its associated resources, see \fIXmCommand(3X)\fP. .SH RETURN VALUE Returns the Command widget ID. .SH RELATED INFORMATION .na \fIXmCommand(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateDialogShell 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateDialogShell\fP \- The DialogShell widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateDialogShell (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateDialogShell\fP creates an instance of a DialogShell widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP .ne 4 For a complete definition of DialogShell and its associated resources, see \fIXmDialogShell(3X)\fP. .SH RETURN VALUE Returns the DialogShell widget ID. .SH RELATED INFORMATION .na \fIXmDialogShell(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateDragIcon 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateDragIcon\fP \- A Drag and Drop function that creates a DragIcon widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateDragIcon (\fBwidget, name, arglist, argcount\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .iE .sE .SH DESCRIPTION .fi \fIXmCreateDragIcon\fP creates a DragIcon and returns the associated widget ID. .IP "\fBwidget\fP" Specifies the ID of the widget that the function uses to access default values for visual attributes of the DragIcon. This widget may be different than the actual parent of the DragIcon. .IP "\fBname\fP" Specifies the name of the DragIcon widget. .IP "\fBarglist\fP" Specifies the argument list. .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP). .PP For a complete definition of DragIcon and its associated resources, see \fIXmDragIcon(3X)\fP. .SH RETURN VALUE The function creates a DragIcon and returns the associated widget ID. .SH RELATED INFORMATION .na \fIXmDragContext(3X)\fP, \fIXmDragIcon(3X)\fP, and \fIXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateDrawingArea 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateDrawingArea\fP \- The DrawingArea widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateDrawingArea (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateDrawingArea\fP creates an instance of a DrawingArea widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of DrawingArea and its associated resources, see \fIXmDrawingArea(3X)\fP. .SH RETURN VALUE Returns the DrawingArea widget ID. .SH RELATED INFORMATION .na \fIXmDrawingArea(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateDrawnButton 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateDrawnButton\fP \- The DrawnButton widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateDrawnButton (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateDrawnButton\fP creates an instance of a DrawnButton widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of DrawnButton and its associated resources, see \fIXmDrawnButton(3X)\fP. .SH RETURN VALUE Returns the DrawnButton widget ID. .SH RELATED INFORMATION .na \fIXmDrawnButton(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateErrorDialog 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateErrorDialog\fP \- The MessageBox ErrorDialog convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateErrorDialog (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateErrorDialog\fP is a convenience creation function that creates a DialogShell and an unmanaged MessageBox child of the DialogShell. An ErrorDialog warns the user of an invalid or potentially dangerous condition. It includes a symbol, a message, and three buttons. The default symbol is an octagon with a diagonal slash. The default button labels are \fIOK\fP, \fICancel\fP, and \fIHelp\fP. .PP Use \fIXtManageChild\fP to pop up the ErrorDialog (passing the MessageBox as the widget parameter); use \fIXtUnmanageChild\fP to pop it down. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of MessageBox and its associated resources, see \fIXmMessageBox(3X)\fP. .SH RETURN VALUE Returns the MessageBox widget ID. .SH RELATED INFORMATION .na \fIXmMessageBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateFileSelectionBox 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateFileSelectionBox\fP \- The FileSelectionBox widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateFileSelectionBox (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateFileSelectionBox\fP creates an unmanaged FileSelectionBox. A FileSelectionBox is used to select a file and includes the following: .TP \(bu An editable text field for the directory mask .TP \(bu A scrolling list of file names .TP \(bu An editable text field for the selected file .TP \(bu Labels for the list and text fields .TP \(bu Four buttons .PP The default button labels are \fIOK\fP, \fIFilter\fP, \fICancel\fP, and \fIHelp\fP. Additional work area children may be added to the FileSelectionBox after creation. FileSelectionBox inherits the layout functionality provided by SelectionBox for any additional work area children. .PP If the parent of the FileSelectionBox is a DialogShell, use \fIXtManageChild\fP to pop up the FileSelectionDialog (passing the FileSelectionBox as the widget parameter); use \fIXtUnmanageChild\fP to pop it down. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of FileSelectionBox and its associated resources, see \fIXmFileSelectionBox(3X)\fP. .SH RETURN VALUE Returns the FileSelectionBox widget ID. .SH RELATED INFORMATION .na \fIXmFileSelectionBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateFileSelectionDialog 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateFileSelectionDialog\fP \- The FileSelectionBox FileSelectionDialog convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateFileSelectionDialog (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateFileSelectionDialog\fP is a convenience creation function that creates a DialogShell and an unmanaged FileSelectionBox child of the DialogShell. A FileSelectionDialog selects a file. It includes the following: .TP \(bu An editable text field for the directory mask .TP \(bu A scrolling list of filenames .TP \(bu An editable text field for the selected file .TP \(bu Labels for the list and text fields .TP \(bu Four buttons .PP .ne 6 The default button labels are: \fIOK\fP, \fIFilter\fP, \fICancel\fP, and \fIHelp\fP. One additional \fIWorkArea\fP child may be added to the FileSelectionBox after creation. .PP Use \fIXtManageChild\fP to pop up the FileSelectionDialog (passing the FileSelectionBox as the widget parameter); use \fIXtUnmanageChild\fP to pop it down. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of FileSelectionBox and its associated resources, see \fIXmFileSelectionBox(3X)\fP. .SH RETURN VALUE Returns the FileSelectionBox widget ID. .SH RELATED INFORMATION .na \fIXmFileSelectionBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateForm 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateForm\fP \- The Form widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateForm (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateForm\fP creates an instance of a Form widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of Form and its associated resources, see \fIXmForm(3X)\fP. .SH RETURN VALUE Returns the Form widget ID. .SH RELATED INFORMATION .na \fIXmForm(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateFormDialog 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateFormDialog\fP \- A Form FormDialog convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateFormDialog (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateFormDialog\fP is a convenience creation function that creates a DialogShell and an unmanaged Form child of the DialogShell. A FormDialog is used for interactions not supported by the standard dialog set. This function does not automatically create any labels, buttons, or other dialog components. Such components should be added by the application after the FormDialog is created. .PP Use \fIXtManageChild\fP to pop up the FormDialog (passing the Form as the widget parameter); use \fIXtUnmanageChild\fP to pop it down. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of Form and its associated resources, see \fIXmForm(3X)\fP. .SH RETURN VALUE Returns the Form widget ID. .SH RELATED INFORMATION .na \fIXmForm(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateFrame 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateFrame\fP \- The Frame widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateFrame (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateFrame\fP creates an instance of a Frame widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of Frame and its associated resources, see \fIXmFrame(3X)\fP. .SH RETURN VALUE Returns the Frame widget ID. .SH RELATED INFORMATION .na \fIXmFrame(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateInformationDialog 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateInformationDialog\fP \- The MessageBox InformationDialog convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateInformationDialog (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateInformationDialog\fP is a convenience creation function that creates a DialogShell and an unmanaged MessageBox child of the DialogShell. An InformationDialog gives the user information, such as the status of an action. It includes a symbol, a message, and three buttons. The default symbol is a lower case \fIi\fP. The default button labels are \fIOK\fP, \fICancel\fP, and \fIHelp\fP. .PP Use \fIXtManageChild\fP to pop up the InformationDialog (passing the MessageBox as the widget parameter); use \fIXtUnmanageChild\fP to pop it down. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of MessageBox and its associated resources, see \fIXmMessageBox(3X)\fP. .SH RETURN VALUE Returns the MessageBox widget ID. .SH RELATED INFORMATION .na \fIXmMessageBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateLabel 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateLabel\fP \- The Label widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateLabel (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateLabel\fP creates an instance of a Label widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of Label and its associated resources, see \fIXmLabel(3X)\fP. .SH RETURN VALUE Returns the Label widget ID. .SH RELATED INFORMATION .na \fIXmLabel(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateLabelGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateLabelGadget\fP \- The LabelGadget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateLabelGadget (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateLabelGadget\fP creates an instance of a LabelGadget widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of LabelGadget and its associated resources, see \fIXmLabelGadget(3X)\fP. .SH RETURN VALUE Returns the LabelGadget widget ID. .SH RELATED INFORMATION .na \fIXmLabelGadget(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmCreateList 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateList\fP \- The List widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateList (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateList\fP creates an instance of a List widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RETURN VALUE Returns the List widget ID. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateMainWindow 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateMainWindow\fP \- The MainWindow widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateMainWindow (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateMainWindow\fP creates an instance of a MainWindow widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of MainWindow and its associated resources, see \fIXmMainWindow(3X)\fP. .SH RETURN VALUE Returns the MainWindow widget ID. .SH RELATED INFORMATION .na \fIXmMainWindow(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateMenuBar 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateMenuBar\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateMenuBar (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateMenuBar\fP creates an instance of a RowColumn widget of type \fIXmMENU_BAR\fP and returns the associated widget ID.It is provided as a convenience function for creating RowColumn widgets configured to operate as a MenuBar and is not implemented as a separate widget class. .PP The MenuBar widget is generally used for building a Pulldown menu system. Typically, a MenuBar is created and placed along the top of the application window, and several CascadeButtons are inserted as the children. Each of the CascadeButtons has a Pulldown MenuPane associated with it. These Pulldown MenuPanes must have been created as children of the MenuBar. The user interacts with the MenuBar by using either the mouse or the keyboard. .PP The MenuBar displays a 3-D shadow along its border. The application controls the shadow attributes using the visual-related resources supported by \fIXmManager\fP. .PP The MenuBar widget is homogeneous in that it accepts only children that are a subclass of \fIXmCascadeButton\fP or \fIXmCascadeButtonGadget\fP. Attempting to insert a child of a different class results in a warning message. .PP If the MenuBar does not have enough room to fit all of its subwidgets on a single line, the MenuBar attempts to wrap the remaining entries onto additional lines if allowed by the geometry manager of the parent widget. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCascadeButton(3X)\fP, \fIXmCascadeButtonGadget(3X)\fP, \fIXmCreatePulldownMenu(3X)\fP, \fIXmCreateSimpleMenuBar(3X)\fP, \fIXmManager(3X)\fP, \fIXmRowColumn(3X)\fP, and \fIXmVaCreateSimpleMenuBar(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateMenuShell 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateMenuShell\fP \- The MenuShell widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateMenuShell (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateMenuShell\fP creates an instance of a MenuShell widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP .ne 4 For a complete definition of MenuShell and its associated resources, see \fIXmMenuShell(3X)\fP. .SH RETURN VALUE Returns the MenuShell widget ID. .SH RELATED INFORMATION .na \fIXmMenuShell(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateMessageBox 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateMessageBox\fP \- The MessageBox widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateMessageBox (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateMessageBox\fP creates an unmanaged MessageBox. A MessageBox is used for common interaction tasks, which include giving information, asking questions, and reporting errors. It includes an optional symbol, a message, and three buttons. .PP By default, there is no symbol. The default button labels are \fIOK\fP, \fICancel\fP, and \fIHelp\fP. .PP If the parent of the MessageBox is a DialogShell, use \fIXtManageChild\fP to pop up the MessageBox (passing the MessageBox as the widget parameter); use \fIXtUnmanageChild\fP to pop it down. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of MessageBox and its associated resources, see \fIXmMessageBox(3X)\fP. .SH RETURN VALUE Returns the MessageBox widget ID. .SH RELATED INFORMATION .na \fIXmMessageBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateMessageDialog 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateMessageDialog\fP \- The MessageBox MessageDialog convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateMessageDialog (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateMessageDialog\fP is a convenience creation function that creates a DialogShell and an unmanaged MessageBox child of the DialogShell. A MessageDialog is used for common interaction tasks, which include giving information, asking questions, and reporting errors. It includes a symbol, a message, and three buttons. By default, there is no symbol. The default button labels are \fIOK\fP, \fICancel\fP, and \fIHelp\fP. .PP Use \fIXtManageChild\fP to pop up the MessageDialog (passing the MessageBox as the widget parameter); use \fIXtUnmanageChild\fP to pop it down. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of MessageBox and its associated resources, see \fIXmMessageBox(3X)\fP. .SH RETURN VALUE Returns the MessageBox widget ID. .SH RELATED INFORMATION .na \fIXmMessageBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateOptionMenu 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateOptionMenu\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateOptionMenu (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateOptionMenu\fP creates an instance of a RowColumn widget of type \fIXmMENU_OPTION\fP and returns the associated widget ID. .PP It is provided as a convenience function for creating a RowColumn widget configured to operate as an OptionMenu and is not implemented as a separate widget class. .PP The OptionMenu widget is a specialized RowColumn manager composed of a label, a selection area, and a single Pulldown MenuPane. When an application creates an OptionMenu widget, it supplies the label string and the Pulldown MenuPane. In order to succeed, there must be a valid \fIXmNsubMenuId\fP resource set when calling this function. When the OptionMenu is created, the Pulldown MenuPane must have been created as a child of the OptionMenu's parent and must be specified. The LabelGadget and the selection area (a CascadeButtonGadget) are created by the OptionMenu. .PP The OptionMenu's Pulldown MenuPane must not contain any ToggleButtons or ToggleButtonGadgets. The results of including CascadeButtons or CascadeButtonGadgets in the OptionMenu's Pulldown MenuPane are undefined. .PP An OptionMenu is laid out with the label displayed on one side of the widget and the selection area on the other side when \fIXmNorientation\fP is XmHORIZONTAL. If the value is XmVERTICAL, the label is above the selection area. The selection area has a dual purpose; it displays the label of the last item selected from the associated Pulldown MenuPane, and it provides the means for posting the Pulldown MenuPane. .PP The OptionMenu typically does not display any 3-D visuals around itself or the internal LabelGadget. By default, the internal CascadeButtonGadget has a visible 3-D shadow. The application may change this by getting the CascadeButtonGadget ID using \fIXmOptionButtonGadget\fP, and then calling \fIXtSetValues\fP using the standard visual-related resources. .PP The Pulldown MenuPane is posted by moving the mouse pointer over the selection area and pressing a mouse button defined by OptionMenu's RowColumn parent. The Pulldown MenuPane is posted and positioned so that the last selected item is directly over the selection area. The mouse is then used to arm the desired menu item. When the mouse button is released, the armed menu item is selected and the label within the selection area is changed to match that of the selected item. By default, \fIBSelect\fP is used to interact with an OptionMenu. The default can be changed via the RowColumn resource \fIXmNmenuPost\fP. .PP The OptionMenu also operates by using the keyboard interface mechanism. If the application has established a mnemonic with the OptionMenu, typing Alt with the mnemonic causes the Pulldown MenuPane to be posted with traversal enabled. The standard traversal keys can then be used to move within the MenuPane. Selection can occur as the result of pressing the Return key or typing a mnemonic or accelerator for one of the menu items. .PP An application may use the \fIXmNmenuHistory\fP resource to indicate which item in the Pulldown MenuPane should be treated as the current choice and have its label displayed in the selection area. By default, the first item in the Pulldown MenuPane is used. .nL .ne 4 .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP The user can specify resources in a resource file for the automatically created widgets and gadgets of an OptionMenu. The following list identifies the names of these widgets (or gadgets) and the associated OptionMenu areas. .TP \(bu .TP \(bu Option Menu Label Gadget \- "OptionLabel" .TP \(bu Option Menu Cascade Button \- "OptionButton" .PP For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCascadeButtonGadget(3X)\fP, \fIXmCreatePulldownMenu(3X)\fP, \fIXmCreateSimpleOptionMenu(3X)\fP, \fIXmLabelGadget(3X)\fP, \fIXmOptionButtonGadget(3X)\fP, \fIXmOptionLabelGadget(3X)\fP, \fIXmRowColumn(3X)\fP, and \fIXmVaCreateSimpleOptionMenu(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreatePanedWindow 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreatePanedWindow\fP \- The PanedWindow widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreatePanedWindow (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreatePanedWindow\fP creates an instance of a PanedWindow widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of PanedWindow and its associated resources, see \fIXmPanedWindow(3X)\fP. .SH RETURN VALUE Returns the PanedWindow widget ID. .SH RELATED INFORMATION .na \fIXmPanedWindow(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreatePopupMenu 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreatePopupMenu\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreatePopupMenu (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreatePopupMenu\fP creates an instance of a RowColumn widget of type \fIXmMENU_POPUP\fP and returns the associated widget ID. When using this function to create the Popup MenuPane, a MenuShell widget is automatically created as the parent of the MenuPane. The parent of the MenuShell widget is the widget indicated by the \fBparent\fP parameter. .PP \fIXmCreatePopupMenu\fP is provided as a convenience function for creating RowColumn widgets configured to operate as Popup MenuPanes and is not implemented as a separate widget class. .PP The PopupMenu is used as the first MenuPane within a PopupMenu system; all other MenuPanes are of the Pulldown type. A Popup MenuPane displays a 3-D shadow, unless the feature is disabled by the application. The shadow appears around the edge of the MenuPane. .PP The Popup MenuPane must be created as the child of a MenuShell widget in order to function properly when it is incorporated into a menu. If the application uses this convenience function for creating a Popup MenuPane, the MenuShell is automatically created as the real parent of the MenuPane. If the application does not use this convenience function to create the RowColumn to function as a Popup MenuPane, it is the application's responsibility to create the MenuShell widget. .PP To access the PopupMenu, the application must first position the widget using the \fIXmMenuPosition\fP function and then manage it using \fIXtManageChild\fP. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP Popup MenuPanes support tear-off capabilities for tear-off menus through \fIXmRowColumn\fP resources. For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .P .SH RETURN VALUE Returns the RowColumn widget ID. .P .SH RELATED INFORMATION .na \fIXmCreateSimplePopupMenu(3X)\fP, \fIXmMenuPosition(3X)\fP, \fIXmMenuShell(3X)\fP, \fIXmRowColumn(3X)\fP, and \fIXmVaCreateSimplePopupMenu(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreatePromptDialog 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreatePromptDialog\fP \- The SelectionBox PromptDialog convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreatePromptDialog (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreatePromptDialog\fP is a convenience creation function that creates a DialogShell and an unmanaged SelectionBox child of the DialogShell. A PromptDialog prompts the user for text input. It includes a message, a text input region, and three managed buttons. The default button labels are \fIOK\fP, \fICancel\fP, and \fIHelp\fP. An additional button, with \fIApply\fP as the default label, is created unmanaged; it may be explicitly managed if needed. One additional \fIWorkArea\fP child may be added to the SelectionBox after creation. .PP \fIXmCreatePromptDialog\fP forces the value of the SelectionBox resource \fIXmNdialogType\fP to \fIXmDIALOG_PROMPT\fP. .PP Use \fIXtManageChild\fP to pop up the PromptDialog (passing the SelectionBox as the widget parameter); use \fIXtUnmanageChild\fP to pop it down. .nL .ne 4 .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of SelectionBox and its associated resources, see \fIXmSelectionBox(3X)\fP. .SH RETURN VALUE Returns the SelectionBox widget ID. .SH RELATED INFORMATION .na \fIXmSelectionBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreatePulldownMenu 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreatePulldownMenu\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreatePulldownMenu (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreatePulldownMenu\fP creates an instance of a RowColumn widget of type \fIXmMENU_PULLDOWN\fP and returns the associated widget ID. When using this function to create the Pulldown MenuPane, a MenuShell widget is automatically created as the parent of the MenuPane. If the widget specified by the \fBparent\fP parameter is a Popup or a Pulldown MenuPane, the MenuShell widget is created as a child of the \fBparent\fP's MenuShell; otherwise, it is created as a child of the specified \fBparent\fP widget. .PP \fIXmCreatePulldownMenu\fP is provided as a convenience function for creating RowColumn widgets configured to operate as Pulldown MenuPanes and is not implemented as a separate widget class. .PP A Pulldown MenuPane displays a 3-D shadow, unless the feature is disabled by the application. The shadow appears around the edge of the MenuPane. .PP A Pulldown MenuPane is used when creating submenus that are to be attached to a CascadeButton or a CascadeButtonGadget. This is the case for all MenuPanes that are part of a PulldownMenu system (a MenuBar), the MenuPane associated with an OptionMenu, and any MenuPanes that cascade from a Popup MenuPane. Pulldown MenuPanes that are to be associated with an OptionMenu must be created before the OptionMenu is created. .PP The Pulldown MenuPane must be attached to a CascadeButton or CascadeButtonGadget that resides in a MenuBar, a Popup MenuPane, a Pulldown MenuPane, or an OptionMenu. This is done by using the button resource \fIXmNsubMenuId\fP. .PP A MenuShell widget is required between the Pulldown MenuPane and its parent. If the application uses this convenience function for creating a Pulldown MenuPane, the MenuShell is automatically created as the real parent of the MenuPane; otherwise, it is the application's responsibility to create the MenuShell widget. .PP To function correctly when incorporated into a menu, the Pulldown MenuPane's hierarchy must be considered; this hierarchy depends on the type of menu system that is being built as follows: .TP \(bu If the Pulldown MenuPane is to be pulled down from a MenuBar, its \fBparent\fP must be the MenuBar. .TP \(bu If the Pulldown MenuPane is to be pulled down from a Popup or another Pulldown MenuPane, its \fBparent\fP must be that Popup or Pulldown MenuPane. .TP \(bu If the Pulldown MenuPane is to be pulled down from an OptionMenu, its \fBparent\fP must be the same as the OptionMenu parent. .TP "\fBparent\fP" \(bu Specifies the parent widget ID .TP "\fBname\fP" \(bu Specifies the name of the created widget .TP "\fBarglist\fP" \(bu Specifies the argument list .TP "\fBargcount\fP" \(bu Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP PullDown MenuPanes support tear-off capabilities for tear-off menus through \fIXmRowColumn\fP resources. For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCascadeButton(3X)\fP, \fIXmCascadeButtonGadget(3X)\fP, \fIXmCreateOptionMenu(3X)\fP, \fIXmCreatePopupMenu(3X)\fP, \fIXmCreateSimplePulldownMenu(3X)\fP, \fIXmMenuShell(3X)\fP, \fIXmRowColumn(3X)\fP, and \fIXmVaCreateSimplePulldownMenu(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreatePushButton 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreatePushButton\fP \- The PushButton widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreatePushButton (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreatePushButton\fP creates an instance of a PushButton widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of PushButton and its associated resources, see \fIXmPushButton(3X)\fP. .SH RETURN VALUE Returns the PushButton widget ID. .SH RELATED INFORMATION .na \fIXmPushButton(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreatePushButtonGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreatePushButtonGadget\fP \- The PushButtonGadget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreatePushButtonGadget (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreatePushButtonGadget\fP creates an instance of a PushButtonGadget widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of PushButtonGadget and its associated resources, see \fIXmPushButtonGadget(3X)\fP. .SH RETURN VALUE Returns the PushButtonGadget widget ID. .SH RELATED INFORMATION .na \fIXmPushButtonGadget(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateQuestionDialog 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateQuestionDialog\fP \- The MessageBox QuestionDialog convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateQuestionDialog (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateQuestionDialog\fP is a convenience creation function that creates a DialogShell and an unmanaged MessageBox child of the DialogShell. A QuestionDialog is used to get the answer to a question from the user. It includes a symbol, a message, and three buttons. The default symbol is a question mark. The default button labels are \fIOK\fP, \fICancel\fP, and \fIHelp\fP. .PP Use \fIXtManageChild\fP to pop up the QuestionDialog (passing the MessageBox as the widget parameter); use \fIXtUnmanageChild\fP to pop it down. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of MessageBox and its associated resources, see \fIXmMessageBox(3X)\fP. .SH RETURN VALUE Returns the MessageBox widget ID. .SH RELATED INFORMATION .na \fIXmMessageBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateRadioBox 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateRadioBox\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateRadioBox (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateRadioBox\fP creates an instance of a RowColumn widget of type \fIXmWORK_AREA\fP and returns the associated widget ID. Typically, this is a composite widget that contains multiple ToggleButtonGadgets. The RadioBox arbitrates and ensures that at most one ToggleButtonGadget is on at any time. .PP Unless the application supplies other values in the \fBarglist\fP, this function provides initial values for several RowColumn resources. It initializes \fIXmNpacking\fP to \fIXmPACK_COLUMN\fP, \fIXmNradioBehavior\fP to True, \fIXmNisHomogeneous\fP to True, and \fIXmNentryClass\fP to \fIxmToggleButtonGadgetClass\fP. .PP In a RadioBox the ToggleButton or ToggleButtonGadget resource \fIXmNindicatorType\fP defaults to \fIXmONE_OF_MANY\fP, and the ToggleButton or ToggleButtonGadget resource\fIXmNvisibleWhenOff\fP defaults to True. .PP This routine is provided as a convenience function for creating RowColumn widgets. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreateRowColumn(3X)\fP, \fIXmCreateSimpleCheckBox(3X)\fP, \fIXmCreateSimpleRadioBox(3X)\fP, \fIXmCreateWorkArea(3X)\fP, \fIXmRowColumn(3X)\fP, \fIXmVaCreateSimpleCheckBox(3X)\fP, and \fIXmVaCreateSimpleRadioBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateRowColumn 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateRowColumn\fP \- The RowColumn widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateRowColumn (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateRowColumn\fP creates an instance of a RowColumn widget and returns the associated widget ID. If \fIXmNrowColumnType\fP is not specified, then it is created with \fIXmWORK_AREA\fP, which is the default. .PP If this function is used to create a Popup Menu of type \fIXmMENU_POPUP\fP or a Pulldown Menu of type \fIXmMENU_PULLDOWN\fP, a MenuShell widget is not automatically created as the parent of the MenuPane. The application must first create the MenuShell by using either \fIXmCreateMenuShell\fP or the standard toolkit create function. .nL .ne 7 .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreateMenuBar(3X)\fP, \fIXmCreateMenuShell(3X)\fP, \fIXmCreateOptionMenu(3X)\fP, \fIXmCreatePopupMenu(3X)\fP, \fIXmCreatePulldownMenu(3X)\fP, \fIXmCreateRadioBox(3X)\fP, \fIXmCreateSimpleCheckBox(3X)\fP, \fIXmCreateSimpleMenuBar(3X)\fP, \fIXmCreateSimpleOptionMenu(3X)\fP, \fIXmCreateSimplePopupMenu(3X)\fP, \fIXmCreateSimplePulldownMenu(3X)\fP, \fIXmCreateSimpleRadioBox(3X)\fP, \fIXmCreateWorkArea(3X)\fP, \fIXmRowColumn(3X)\fP, \fIXmVaCreateSimpleCheckBox(3X)\fP, \fIXmVaCreateSimpleMenuBar(3X)\fP, \fIXmVaCreateSimpleOptionMenu(3X)\fP, \fIXmVaCreateSimplePopupMenu(3X)\fP, \fIXmVaCreateSimplePulldownMenu(3X)\fP, and \fIXmVaCreateSimpleRadioBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateScale 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateScale\fP \- The Scale widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateScale (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateScale\fP creates an instance of a Scale widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of Scale and its associated resources, see \fIXmScale(3X)\fP. .SH RETURN VALUE Returns the Scale widget ID. .SH RELATED INFORMATION .na \fIXmScale(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateScrollBar 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateScrollBar\fP \- The ScrollBar widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateScrollBar (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateScrollBar\fP creates an instance of a ScrollBar widget and returns the associated widget ID. .P .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of ScrollBar and its associated resources, see \fIXmScrollBar(3X)\fP. .SH RETURN VALUE Returns the ScrollBar widget ID. .SH RELATED INFORMATION .na \fIXmScrollBar(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmCreateScrolledList 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateScrolledList\fP \- The List ScrolledList convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateScrolledList (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateScrolledList\fP creates an instance of a List widget that is contained within a ScrolledWindow. All ScrolledWindow subarea widgets are automatically created by this function. The ID returned by this function is that of the List widget. Use this ID for all normal List operations, as well as those that are relevant for the ScrolledList widget. .PP All arguments to either the List or the ScrolledWindow widget can be specified at creation time using this function. Changes to initial position and size are sent only to the ScrolledWindow widget. Other resources are sent to the List or the ScrolledWindow widget as appropriate. .PP This function forces the following initial values for ScrolledWindow resources: .TP \(bu \fIXmNscrollingPolicy\fP is set to \fIXmAPPLICATION_DEFINED\fP. .TP \(bu \fIXmNvisualPolicy\fP is set to \fIXmVARIABLE\fP. .TP \(bu \fIXmNscrollBarDisplayPolicy\fP is set to \fIXmSTATIC\fP. (No initial value is forced for the List's \fIXmNscrollBarDisplayPolicy\fP.) .TP \(bu \fIXmNshadowThickness\fP is set to 0. .PP To obtain the ID of the ScrolledWindow widget associated with the ScrolledList, use the Xt Intrinsics \fIXtParent\fP function. The name of the ScrolledWindow created by this function is formed by concatenating the letters \fISW\fP onto the end of the \fBname\fP specified in the parameter list. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .P .SH RETURN VALUE Returns the List widget ID. .SH RELATED INFORMATION .na \fIXmList(3X)\fP and \fIXmScrolledWindow(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateScrolledText 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateScrolledText\fP \- The TextScrolledText convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateScrolledText (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateScrolledText\fP creates an instance of a Text widget that is contained within a ScrolledWindow. All ScrolledWindow subarea widgets are automatically created by this function. The ID returned by this function is that of the Text widget. Use this ID for all normal Text operations, as well as those that are relevant for the ScrolledText widget. .PP The Text widget defaults to single-line text edit; therefore, no ScrollBars are displayed. The Text resource \fIXmNeditMode\fP must be set to \fIXmMULTI_LINE_EDIT\fP to display the ScrollBars. The results of placing a Text widget inside a ScrolledWindow when the Text's \fIXmNeditMode\fP is \fIXmSINGLE_LINE_EDIT\fP are undefined. .PP .ne 5 All arguments to either the Text or the ScrolledWindow widget can be specified at creation time using this function. Changes to initial position and size are sent only to the ScrolledWindow widget. Other resources are sent to the Text or the ScrolledWindow widget as appropriate. .PP This function forces the following initial values for ScrolledWindow resources: .TP \(bu \fIXmNscrollingPolicy\fP is set to \fIXmAPPLICATION_DEFINED\fP. .TP \(bu \fIXmNvisualPolicy\fP is set to \fIXmVARIABLE\fP. .TP \(bu \fIXmNscrollBarDisplayPolicy\fP is set to \fIXmSTATIC\fP. .TP \(bu \fIXmNshadowThickness\fP is set to 0. .PP To obtain the ID of the ScrolledWindow widget associated with the ScrolledText, use the Xt Intrinsics \fIXtParent\fP function. The name of the ScrolledWindow created by this function is formed by concatenating the letters \fISW\fP onto the end of the \fBname\fP specified in the parameter list. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .P .ne 30 .SH RETURN VALUE Returns the Text widget ID. .SH RELATED INFORMATION .na \fIXmScrolledWindow(3X)\fP and \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateScrolledWindow 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateScrolledWindow\fP \- The ScrolledWindow widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateScrolledWindow (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateScrolledWindow\fP creates an instance of a ScrolledWindow widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of ScrolledWindow and its associated resources, see \fIXmScrolledWindow(3X)\fP. .SH RETURN VALUE Returns the ScrolledWindow widget ID. .SH RELATED INFORMATION .na \fIXmScrolledWindow(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateSelectionBox 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateSelectionBox\fP \- The SelectionBox widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateSelectionBox (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateSelectionBox\fP creates an unmanaged SelectionBox. A SelectionBox is used to get a selection from a list of alternatives from the user and includes the following: .TP \(bu A scrolling list of alternatives .TP \(bu An editable text field for the selected alternative .TP \(bu Labels for the list and text field .TP \(bu Three or four buttons .PP .ne 5 The default button labels are \fIOK\fP, \fICancel\fP, and \fIHelp\fP. By default an \fIApply\fP button is also created; if the parent of the SelectionBox is a DialogShell it is managed, and otherwise it is unmanaged. Additional work area children may be added to the SelectionBox after creation. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of SelectionBox and its associated resources, see \fIXmSelectionBox(3X)\fP. .P .SH RETURN VALUE Returns the SelectionBox widget ID. .SH RELATED INFORMATION .na \fIXmSelectionBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateSelectionDialog 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateSelectionDialog\fP \- The SelectionBox SelectionDialog convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateSelectionDialog (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateSelectionDialog\fP is a convenience creation function that creates a DialogShell and an unmanaged SelectionBox child of the DialogShell. A SelectionDialog offers the user a choice from a list of alternatives and gets a selection. It includes the following: .TP \(bu A scrolling list of alternatives .TP \(bu An editable text field for the selected alternative .TP \(bu Labels for the text field .TP \(bu Four buttons .PP The default button labels are \fIOK\fP, \fICancel\fP, \fIApply\fP, and \fIHelp\fP. One additional \fIWorkArea\fP child may be added to the SelectionBox after creation. .PP \fIXmCreateSelectionDialog\fP forces the value of the SelectionBox resource \fIXmNdialogType\fP to \fIXmDIALOG_SELECTION\fP. .PP Use \fIXtManageChild\fP to pop up the SelectionDialog (passing the SelectionBox as the widget parameter); use \fIXtUnmanageChild\fP to pop it down. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of SelectionBox and its associated resources, see \fIXmSelectionBox(3X)\fP. .SH RETURN VALUE Returns the SelectionBox widget ID. .SH RELATED INFORMATION .na \fIXmSelectionBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateSeparator 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateSeparator\fP \- The Separator widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateSeparator (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateSeparator\fP creates an instance of a Separator widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of Separator and its associated resources, see \fIXmSeparator(3X)\fP. .SH RETURN VALUE Returns the Separator widget ID. .SH RELATED INFORMATION .na \fIXmSeparator(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateSeparatorGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateSeparatorGadget\fP \- The SeparatorGadget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateSeparatorGadget (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateSeparatorGadget\fP creates an instance of a SeparatorGadget widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of SeparatorGadget and its associated resources, see \fIXmSeparatorGadget(3X)\fP. .SH RETURN VALUE Returns the SeparatorGadget widget ID. .SH RELATED INFORMATION .na \fIXmSeparatorGadget(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateSimpleCheckBox 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateSimpleCheckBox\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateSimpleCheckBox (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateSimpleCheckBox\fP creates an instance of a RowColumn widget of type \fIXmWORK_AREA\fP and returns the associated widget ID. .PP This routine creates a CheckBox and its ToggleButtonGadget children. A CheckBox is similar to a RadioBox, except that more than one button can be selected at a time. The name of each button is button_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of buttons in the menu. Buttons are named and created in the order in which they are specified in the RowColumn simple menu creation resources supplied in the argument list. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP A number of resources exist specifically for use with this and other simple menu creation routines. The only button type allowed in the \fIXmNbuttonType\fP resource is \fIXmCHECKBUTTON\fP. For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreateRadioBox(3X)\fP, \fIXmCreateRowColumn(3X)\fP, \fIXmCreateSimpleRadioBox(3X)\fP, \fIXmRowColumn(3X)\fP, \fIXmVaCreateSimpleCheckBox(3X)\fP, and \fIXmVaCreateSimpleRadioBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateSimpleMenuBar 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateSimpleMenuBar\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateSimpleMenuBar (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateSimpleMenuBar\fP creates an instance of a RowColumn widget of type \fIXmMENU_BAR\fP and returns the associated widget ID. .PP This routine creates a MenuBar and its CascadeButtonGadget children. The name of each button is button_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of buttons in the menu. Buttons are named and created in the order in which they are specified in the RowColumn simple menu creation resources supplied in the argument list. .P .ne 6 .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP A number of resources exist specifically for use with this and other simple menu creation routines. The only button type allowed in the \fIXmNbuttonType\fP resource is \fIXmCASCADEBUTTON\fP. For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreateMenuBar(3X)\fP, \fIXmCreateRowColumn(3X)\fP, \fIXmRowColumn(3X)\fP, and \fIXmVaCreateSimpleMenuBar(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateSimpleOptionMenu 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateSimpleOptionMenu\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateSimpleOptionMenu (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateSimpleOptionMenu\fP creates an instance of a RowColumn widget of type \fIXmMENU_OPTION\fP and returns the associated widget ID. .PP This routine creates an Option Menu and its submenu containing PushButtonGadget or CascadeButtonGadget children. The name of each button is button_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of buttons in the menu. The name of each separator is separator_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of separators in the menu. Buttons and separators are named and created in the order in which they are specified in the RowColumn simple menu creation resources supplied in the argument list. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP The user can specify resources in a resource file for the automatically created widgets and gadgets of an OptionMenu. The following list identifies the names of these widgets (or gadgets) and the associated OptionMenu areas. .TP \(bu .TP \(bu Option Menu Label Gadget \- "OptionLabel" .TP \(bu Option Menu Cascade Button \- "OptionButton" .PP A number of resources exist specifically for use with this and other simple menu creation routines. The only button types allowed in the \fIXmNbuttonType\fP resource are \fIXmPUSHBUTTON\fP, \fIXmCASCADEBUTTON\fP, \fIXmSEPARATOR\fP, and \fIXmDOUBLE_SEPARATOR\fP. For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreateOptionMenu(3X)\fP, \fIXmCreateRowColumn(3X)\fP, \fIXmRowColumn(3X)\fP, and \fIXmVaCreateSimpleOptionMenu(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateSimplePopupMenu 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateSimplePopupMenu\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateSimplePopupMenu (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateSimplePopupMenu\fP creates an instance of a RowColumn widget of type \fIXmMENU_POPUP\fP and returns the associated widget ID. .PP This routine creates a Popup MenuPane and its button children. The name of each button is button_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of buttons in the menu. The name of each separator is separator_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of separators in the menu. The name of each title is label_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of titles in the menu. Buttons, separators, and titles are named and created in the order in which they are specified in the RowColumn simple menu creation resources supplied in the argument list. .IP "\fBparent\fP" Specifies the widget ID of the parent of the MenuShell .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP A number of resources exist specifically for use with this and other simple menu creation routines. The only button types allowed in the \fIXmNbuttonType\fP resource are \fIXmCASCADEBUTTON\fP, \fIXmPUSHBUTTON\fP, \fIXmRADIOBUTTON\fP, \fIXmCHECKBUTTON\fP, \fIXmTITLE\fP, \fIXmSEPARATOR\fP, and \fIXmDOUBLE_SEPARATOR\fP. For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreatePopupMenu(3X)\fP, \fIXmCreateRowColumn(3X)\fP, \fIXmRowColumn(3X)\fP, and \fIXmVaCreateSimplePopupMenu(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateSimplePulldownMenu 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateSimplePulldownMenu\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateSimplePulldownMenu (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateSimplePulldownMenu\fP creates an instance of a RowColumn widget of type \fIXmMENU_PULLDOWN\fP and returns the associated widget ID. .PP This routine creates a Pulldown MenuPane and its button children. The name of each button is button_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of buttons in the menu. The name of each separator is separator_\fBn\fP, where \fBn\fP is an integer from 0 to .ne 8 one minus the number of separators in the menu. The name of each title is label_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of titles in the menu. Buttons, separators, and titles are named and created in the order in which they are specified in the RowColumn simple menu creation resources supplied in the argument list. .IP "\fBparent\fP" Specifies the widget ID of the parent of the MenuShell .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP A number of resources exist specifically for use with this and other simple menu creation routines. The only button types allowed in the \fIXmNbuttonType\fP resource are \fIXmCASCADEBUTTON\fP, \fIXmPUSHBUTTON\fP, \fIXmRADIOBUTTON\fP, \fIXmCHECKBUTTON\fP, \fIXmTITLE\fP, \fIXmSEPARATOR\fP, and \fIXmDOUBLE_SEPARATOR\fP. For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreatePulldownMenu(3X)\fP, \fIXmCreateRowColumn(3X)\fP, \fIXmRowColumn(3X)\fP, and \fIXmVaCreateSimplePulldownMenu(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateSimpleRadioBox 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateSimpleRadioBox\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateSimpleRadioBox (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateSimpleRadioBox\fP creates an instance of a RowColumn widget of type \fIXmWORK_AREA\fP and returns the associated widget ID. .PP This routine creates a Radio Box and its ToggleButtonGadget children. The name of each button is button_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of buttons in the menu. Buttons are named and created in the order in which they are specified in the RowColumn simple menu creation resources supplied in the argument list. .P .ne 6 .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP A number of resources exist specifically for use with this and other simple menu creation routines. The only button type allowed in the \fIXmNbuttonType\fP resource is \fIXmRADIOBUTTON\fP. For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreateRadioBox(3X)\fP, \fIXmCreateRowColumn(3X)\fP, \fIXmCreateSimpleCheckBox(3X)\fP, \fIXmRowColumn(3X)\fP, and \fIXmVaCreateSimpleRadioBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateTemplateDialog 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateTemplateDialog\fP \- A MessageBox TemplateDialog convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateTemplateDialog (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .iE .sE .SH DESCRIPTION .fi \fIXmCreateTemplateDialog\fP is a convenience creation function that creates a DialogShell and an unmanaged MessageBox child of the DialogShell. The MessageBox widget's \fIXmNdialogType\fP resource is set to \fIXmDIALOG_TEMPLATE\fP. By default, the TemplateDialog widget contains only the separator child. You can build a customized dialog by adding children to the TemplateDialog. .PP You can create the standard MessageBox pushbuttons, \fICancel\fP, \fIHelp\fP, and \fIOK\fP, by specifying the associated callback and label string resources. Setting \fIXmNsymbolPixmap\fP or \fIXmNmessageString\fP creates a symbol or message label. .PP Use \fIXtManageChild\fP to pop up the TemplateDialog (passing the MessageBox as the widget parameter); use \fIXtUnmanageChild\fP to pop it down. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of MessageBox and its associated resources, see \fIXmMessageBox(3X)\fP. .SH RETURN VALUE Returns the MessageBox widget ID. .SH RELATED INFORMATION .na \fIXmMessageBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateText 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateText\fP \- The Text widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateText (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateText\fP creates an instance of a Text widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE Returns the Text widget ID. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateTextField 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateTextField\fP \- The TextField widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateTextField (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateTextField\fP creates an instance of a TextField widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP .ne 5 For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RETURN VALUE Returns the TextField widget ID. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateToggleButton 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateToggleButton\fP \- The ToggleButton widget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateToggleButton (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateToggleButton\fP creates an instance of a ToggleButton widget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of ToggleButton and its associated resources, see \fIXmToggleButton(3X)\fP. .SH RETURN VALUE Returns the ToggleButton widget ID. .SH RELATED INFORMATION .na \fIXmToggleButton(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateToggleButtonGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateToggleButtonGadget\fP \- The ToggleButtonGadget creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateToggleButtonGadget (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateToggleButtonGadget\fP creates an instance of a ToggleButtonGadget and returns the associated widget ID. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of ToggleButtonGadget and its associated resources, see \fIXmToggleButtonGadget(3X)\fP. .SH RETURN VALUE Returns the ToggleButtonGadget widget ID. .SH RELATED INFORMATION .na \fIXmToggleButtonGadget(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateWarningDialog 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateWarningDialog\fP \- The MessageBox WarningDialog convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateWarningDialog (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateWarningDialog\fP is a convenience creation function that creates a DialogShell and an unmanaged MessageBox child of the DialogShell. A WarningDialog warns users of action consequences and gives them a choice of resolutions. It includes a symbol, a message, and three buttons. The default symbol is an exclamation point. The default button labels are \fIOK\fP, \fICancel\fP, and \fIHelp\fP. .PP Use \fIXtManageChild\fP to pop up the WarningDialog (passing the MessageBox as the widget parameter); use \fIXtUnmanageChild\fP to pop it down. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of MessageBox and its associated resources, see \fIXmMessageBox(3X)\fP. .SH RETURN VALUE Returns the MessageBox widget ID. .SH RELATED INFORMATION .na \fIXmMessageBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateWorkArea 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateWorkArea\fP \- A function that creates a RowColumn work area .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateWorkArea (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateWorkArea\fP creates an instance of a RowColumn widget and returns the associated widget ID. The widget is created with \fIXmNrowColumnType\fP set to \fIXmWORK_AREA\fP. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreateRadioBox(3X)\fP, \fIXmCreateSimpleCheckBox(3X)\fP, \fIXmCreateSimpleRadioBox(3X)\fP, \fIXmRowColumn(3X)\fP, \fIXmVaCreateSimpleCheckBox(3X)\fP, and \fIXmVaCreateSimpleRadioBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCreateWorkingDialog 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCreateWorkingDialog\fP \- The MessageBox WorkingDialog convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmCreateWorkingDialog (\fBparent, name, arglist, argcount\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCreateWorkingDialog\fP is a convenience creation function that creates a DialogShell and an unmanaged MessageBox child of the DialogShell. A WorkingDialog informs users that there is a time-consuming operation in progress and allows them to cancel the operation. It includes a symbol, a message, and three buttons. The default symbol is an hourglass. The default button labels are \fIOK\fP, \fICancel\fP, and \fIHelp\fP. .PP Use \fIXtManageChild\fP to pop up the WorkingDialog (passing the MessageBox as the widget parameter); use \fIXtUnmanageChild\fP to pop it down. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of MessageBox and its associated resources, see \fIXmMessageBox(3X)\fP. .SH RETURN VALUE Returns the MessageBox widget ID. .SH RELATED INFORMATION .na \fIXmMessageBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCvtCTToXmString 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCvtCTToXmString\fP \- A compound string function that converts compound text to a compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmString XmCvtCTToXmString (\fBtext\fI) .ta .5i 1.75i .nf char \fB* text\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCvtCTToXmString\fP converts a (char *) string in compound text format to a compound string. The application must call \fIXtAppInitialize\fP before calling this function. Conversion of compound text to compound strings is implementation dependent. .IP "\fBtext\fP" Specifies a string in compound text format to be converted to a compound string. .SH RETURN VALUE Returns a compound string derived from the compound text. The compound text is assumed to be NULL-terminated; NULLs within the compound text are handled correctly. The handling of HORIZONTAL TABULATION (HT) control characters within the compound text is undefined. The compound text format is described in the X Consortium Standard \fBCompound Text Encoding\fP. .SH RELATED INFORMATION .na \fIXmCvtXmStringToCT(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCvtStringToUnitType 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCvtStringToUnitType\fP \- A function that converts a string to a unit-type value .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmCvtStringToUnitType (\fBargs, num_args, from_val, to_val\fI) .ta .5i 1.5i .nf XrmValuePtr \fBargs\fI; Cardinal \fB* num_args\fI; XrmValue \fB* from_val\fI; XrmValue \fB* to_val\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCvtStringToUnitType\fP converts a string to a unit type. Refer to the man pages for \fIXmGadget\fP, \fIXmManager\fP, or \fIXmPrimitive\fP for a description of the valid unit types. Use of this function as a resource converter is obsolete. It has been replaced by a new resource converter that uses the RepType facility. .IP "\fBargs\fP" Specifies a list of additional \fIXrmValue\fP arguments to the converter if additional context is needed to perform the conversion. For example, the string-to-font converter needs the widget's screen and the string-to-pixel converter needs the widget's screen and color map. This argument is often NULL. .IP "\fBnum_args\fP" Specifies the number of additional \fIXrmValue\fP arguments. This argument is often zero. .IP "\fBfrom_val\fP" Specifies the value to convert .IP "\fBto_val\fP" Specifies the descriptor to use to return the converted value .SH RELATED INFORMATION .na \fIXmGadget(3X)\fP, \fIXmManager(3X)\fP, and \fIXmPrimitive(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmCvtXmStringToCT 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmCvtXmStringToCT\fP \- A compound string function that converts a compound string to compound text .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu char * XmCvtXmStringToCT (\fBstring\fI) .ta .5i 1.75i .nf XmString \fBstring\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmCvtXmStringToCT\fP converts a compound string to a (char *) string in compound text format. The application must call \fIXtAppInitialize\fP before calling this function. The converter uses the font list tag associated with a given compound string segment to select a compound text format for that segment. A registry defines a mapping between font list tags and compound text encoding formats. The converter uses the following algorithm for each compound string segment: .VL .IP If the compound string segment tag is mapped to \fIXmFONTLIST_DEFAULT_TAG\fP in the registry, the converter passes the text of the compound string segment to \fIXmbTextListToTextProperty\fP with an encoding style of \fIXCompoundTextStyle\fP and uses the resulting compound text for that segment. .IP If the compound string segment tag is mapped to an MIT registered charset in the registry, the converter creates the compound text for that segment using the charset (from the registry) and the text of the compound string segment as defined in the X Consortium Standard \*ECompound Text Encoding\fP. .IP If the compound string segment tag is mapped to a charset in the registry that is neither \fIXmFONTLIST_DEFAULT_TAG\fP nor an MIT registered charset, the converter creates the compound text for that segment using the charset (from the registry) and the text of the compound string segment as an "extended segment" with a variable number of octets per character. .IP If the compound string segment tag is not mapped in the registry, the result is implementation dependent. .IP "\fBstring\fP" Specifies a compound string to be converted to compound text. .SH RETURN VALUE Returns a (char *) string in compound text format. This format is described in the X Consortium Standard \*ECompound Text Encoding\fP. .SH RELATED INFORMATION .na \fIXmCvtCTToXmString(3X)\fP, \fIXmFontList(3X)\fP, \fIXmMapSegmentEncoding(3X)\fP, \fIXmRegisterSegmentEncoding(3X)\fP, and \fIXmString\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDeactivateProtocol 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDeactivateProtocol\fP \- A VendorShell function that deactivates a protocol without removing it .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu void XmDeactivateProtocol (\fBshell, property, protocol\fI) .ta .5i 1.5i .nf Widget \fBshell\fI; Atom \fBproperty\fI; Atom \fBprotocol\fI; .sp \n(PDu void XmDeactivateWMProtocol (\fBshell, protocol\fI) .ta .5i 1.5i .nf Widget \fBshell\fI; Atom \fBprotocol\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmDeactivateProtocol\fP deactivates a protocol without removing it. It updates the handlers and the \fBproperty\fP, if the \fBshell\fP is realized. It is sometimes useful to allow a protocol's state information (callback lists, etc.) to persist, even though the client may choose to temporarily resign from the interaction. The main use of this capability is to gray/ungray \fIf.send_msg\fP entries in the Mwm system menu. This is supported by allowing a \fBprotocol\fP to be in one of two states: active or inactive. If the \fBprotocol\fP is active and the \fBshell\fP is realized, the \fBproperty\fP contains the \fBprotocol\fP \fIAtom\fP. If the \fBprotocol\fP is inactive, the \fIAtom\fP is not present in the \fBproperty\fP. .nL .ne 7 .PP \fIXmDeactivateWMProtocol\fP is a convenience interface. It calls \fIXmDeactivateProtocol\fP with the property value set to the atom returned by interning \fIWM_PROTOCOLS\fP. .IP "\fBshell\fP" Specifies the widget with which the protocol property is associated .IP "\fBproperty\fP" Specifies the protocol property .IP "\fBprotocol\fP" Specifies the protocol atom (or an int type cast to Atom) .PP For a complete definition of VendorShell and its associated resources, see \fIVendorShell(3X)\fP. .SH RELATED INFORMATION .na \fImwm(1X)\fP, \fIVendorShell(3X)\fP, \fIXmDeactivateWMProtocol(3X)\fP, and \fIXmInternAtom(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDeactivateWMProtocol 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDeactivateWMProtocol\fP \- A VendorShell convenience interface that deactivates a protocol without removing it .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu void XmDeactivateWMProtocol (\fBshell, protocol\fI) .ta .5i 1.5i .nf Widget \fBshell\fI; Atom \fBprotocol\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmDeactivateWMProtocol\fP is a convenience interface. It calls \fIXmDeactivateProtocol\fP with the property value set to the atom returned by interning \fIWM_PROTOCOLS\fP. .IP "\fBshell\fP" Specifies the widget with which the protocol property is associated .IP "\fBprotocol\fP" Specifies the protocol atom (or an int type cast to Atom) .PP For a complete definition of VendorShell and its associated resources, see \fIVendorShell(3X)\fP. .SH RELATED INFORMATION .na \fIVendorShell(3X)\fP, \fIXmDeactivateProtocol(3X)\fP, and \fIXmInternAtom(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDestroyPixmap 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDestroyPixmap\fP \- A pixmap caching function that removes a pixmap from the pixmap cache .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmDestroyPixmap (\fBscreen, pixmap\fI) .ta .5i 1.5i .nf Screen \fB* screen\fI; Pixmap \fBpixmap\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmDestroyPixmap\fP removes pixmaps that are no longer used. Pixmaps are completely freed only when there is no further reference to them. .IP "\fBscreen\fP" Specifies the display screen for which the pixmap was requested .IP "\fBpixmap\fP" Specifies the pixmap to be destroyed .SH RETURN VALUE Returns True when successful; returns False if there is no matching screen and pixmap in the pixmap cache. .SH RELATED INFORMATION .na \fIXmInstallImage(3X)\fP, \fIXmUninstallImage(3X)\fP, and \fIXmGetPixmap(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDialogShell 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDialogShell\fP \- The DialogShell widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi Modal and modeless dialogs use DialogShell as the Shell parent. DialogShell widgets cannot be iconified. Instead, all secondary DialogShell widgets associated with an ApplicationShell widget are iconified and de-iconified as a group with the primary widget. .PP The client indirectly manipulates DialogShell via the convenience interfaces during creation, and it can directly manipulate its BulletinBoard-derived child. Much of the functionality of DialogShell assumes that its child is a BulletinBoard subclass, although it can potentially stand alone. .PP Setting \fIXmNheight\fP, \fIXmNwidth\fP, or \fIXmNborderWidth\fP for either a DialogShell or its managed child usually sets that resource to the same value in both the parent and the child. When an off-the-spot input method exists, the height and width of the shell may be greater than those of the managed child in order to accommodate the input method. In this case setting \fIXmNheight\fP or \fIXmNwidth\fP for the shell does not necessarily set that resource to the same value in the managed child, and setting \fIXmNheight\fP or \fIXmNwidth\fP for the child does not necessarily set that resource to the same value in the shell. .PP For the managed child of a DialogShell, regardless of the value of the shell's \fIXmNallowShellResize\fP, setting \fIXmNx\fP or \fIXmNy\fP sets the corresponding resource of the parent but does not change the child's position relative to the parent. \fIXtGetValues\fP for the child's \fIXmNx\fP or \fIXmNy\fP yields the value of the corresponding resource in the parent. The \fBx\fP and \fBy\fP coordinates of the child's upper left outside corner relative to the parent's upper left inside corner are both zero minus the value of \fIXmNborderWidth\fP. .PP Note that the \fBInter-Client Communication Conventions Manual\fP allows a window manager to change or control the border width of a reparented top-level window. .SS "Classes" DialogShell inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIShell\fP, \fIWMShell\fP, \fIVendorShell\fP, and \fITransientShell\fP classes. .PP The class pointer is \fIxmDialogShellWidgetClass\fP. .PP The class name is \fIXmDialogShell\fP. .SS "New Resources" DialogShell defines no new resources but overrides the \fIXmNdeleteResponse\fP resource in the \fIVendorShell\fP class. .SS "Inherited Resources" DialogShell inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .PP The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. TransientShell Resource Set Name Class Type Default Access _ XmNtransientFor XmCTransientFor Widget NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. VendorShell Resource Set Name Class Type Default Access _ XmNaudibleWarning XmCAudibleWarning unsigned char XmBELL CSG XmNbuttonFontList XmCButtonFontList XmFontList dynamic CSG XmNdefaultFontList XmCDefaultFontList XmFontList dynamic CG XmNdeleteResponse XmCDeleteResponse unsigned char XmUNMAP CSG XmNinputMethod XmCInputMethod String NULL CSG XmNkeyboardFocusPolicy XmCKeyboardFocusPolicy unsigned char XmEXPLICIT CSG XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG XmNmwmDecorations XmCMwmDecorations int -1 CSG XmNmwmFunctions XmCMwmFunctions int -1 CSG XmNmwmInputMode XmCMwmInputMode int -1 CSG XmNmwmMenu XmCMwmMenu String NULL CSG XmNpreeditType XmCPreeditType String dynamic CSG XmNshellUnitType XmCShellUnitType unsigned char XmPIXELS CSG XmNtextFontList XmCTextFontList XmFontList dynamic CSG XmNuseAsyncGeometry XmCUseAsyncGeometry Boolean False CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. WMShell Resource Set Name Class Type Default Access _ XmNbaseHeight XmCBaseHeight int XtUnspecifiedShellInt CSG XmNbaseWidth XmCBaseWidth int XtUnspecifiedShellInt CSG XmNheightInc XmCHeightInc int XtUnspecifiedShellInt CSG XmNiconMask XmCIconMask Pixmap NULL CSG XmNiconPixmap XmCIconPixmap Pixmap NULL CSG XmNiconWindow XmCIconWindow Window NULL CSG XmNiconX XmCIconX int \-1 CSG XmNiconY XmCIconY int \-1 CSG XmNinitialState XmCInitialState int NormalState CSG XmNinput XmCInput Boolean True CSG XmNmaxAspectX XmCMaxAspectX int XtUnspecifiedShellInt CSG XmNmaxAspectY XmCMaxAspectY int XtUnspecifiedShellInt CSG XmNmaxHeight XmCMaxHeight int XtUnspecifiedShellInt CSG XmNmaxWidth XmCMaxWidth int XtUnspecifiedShellInt CSG .wH .tH XmNminAspectX XmCMinAspectX int XtUnspecifiedShellInt CSG XmNminAspectY XmCMinAspectY int XtUnspecifiedShellInt CSG XmNminHeight XmCMinHeight int XtUnspecifiedShellInt CSG XmNminWidth XmCMinWidth int XtUnspecifiedShellInt CSG XmNtitle XmCTitle String dynamic CSG XmNtitleEncoding XmCTitleEncoding Atom dynamic CSG XmNtransient XmCTransient Boolean True CSG XmNwaitForWm XmCWaitForWm Boolean True CSG XmNwidthInc XmCWidthInc int XtUnspecifiedShellInt CSG XmNwindowGroup XmCWindowGroup Window dynamic CSG XmNwinGravity XmCWinGravity int dynamic CSG XmNwmTimeout XmCWmTimeout int 5000 ms CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Shell Resource Set Name Class Type Default Access _ XmNallowShellResize XmCAllowShellResize Boolean False CG XmNcreatePopupChildProc XmCCreatePopupChildProc XtCreatePopupChildProc NULL CSG XmNgeometry XmCGeometry String NULL CSG XmNoverrideRedirect XmCOverrideRedirect Boolean False CSG XmNpopdownCallback XmCCallback XtCallbackList NULL C XmNpopupCallback XmCCallback XtCallbackList NULL C XmNsaveUnder XmCSaveUnder Boolean True CSG XmNvisual XmCVisual Visual * CopyFromParent CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 1 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Translations" There are no translations for XmDialogShell. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fICore(3X)\fP, \fIShell(3X)\fP, \fITransientShell(3X)\fP, \fIWMShell(3X)\fP, \fIVendorShell(3X)\fP, and \fIXmCreateDialogShell(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDisplay 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDisplay\fP \- The Display widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi The XmDisplay object is used by the Motif widgets to store information that is specific to a display. It also allows the toolkit to access certain information on widget hierarchies that would otherwise be unavailable. Each client has one XmDisplay object for each display it accesses. .PP An XmDisplay object is automatically created when the application creates the first shell on a display (usually accomplished by a call to \fIXtAppInitialize\fP or \fIXtAppCreateShell\fP). It is not necessary to create an XmDisplay object by any other means. An application can use the function \fIXmGetXmDisplay\fP to obtain the widget ID of the XmDisplay object for a given display. .PP An application cannot supply initial values for XmDisplay resources as arguments to a call to any function that creates widgets. The application or user can supply initial values in a resource file. After creating the first shell on the display, the application can use \fIXmGetXmDisplay\fP to obtain the widget ID of the XmDisplay object and then call \fIXtSetValues\fP to set the XmDisplay resources. .PP XmDisplay resources specify the drag protocol style for a client participating in drag and drop transactions. There are two basic protocol types, preregister and dynamic. When a preregister protocol is used, the toolkit handles any communication between the initiator and receiver clients, and displays the appropriate drag-over and drag-under visual effects. A client registers its drop sites in advance and this information is stored in a property for each top-level window. When the drag pointer enters a top level window, the drop site information is read by the initiator. A dynamic protocol allows the source and destination clients to dynamically communicate drag and drop state information between each other, and to update their respective visuals accordingly. The toolkit provides drop site information as the pointer passes over any given drop site. In this mode, a receiver can supply a procedure to generate its own drag-under effects. .SS "Classes" Display inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIShell\fP, \fIWMShell\fP, \fIVendorShell\fP, \fITopLevelShell\fP, and \fIApplicationShell\fP classes. .PP The class pointer is \fIxmDisplayClass\fP. .PP The class name is \fIXmDisplay\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in an \fI.Xdefaults\fP file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in an \fI.Xdefaults\fP file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (\fIC\fP), set by using \fIXtSetValues\fP (\fIS\fP), retrieved by using \fIXtGetValues\fP (\fIG\fP), or is not applicable (\fIN/A\fP). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmDisplay Resource Set Name Class Type Default Access _ XmNdefaultVirtualBindings DefaultVirtualBindings String dynamic CG XmNdragInitiatorProtocolStyle XmCDragInitiatorProtocolStyle unsigned char XmDRAG_PREFER_RECEIVER CG XmNdragReceiverProtocolStyle XmCDragReceiverProtocolStyle unsigned char XmDRAG_PREFER_PREREGISTER CG defaultButtonEmphasis DefaultButtonEmphasis XtEnum "external_highlight" CG enableBtn1Transfer EnableBtn1Transfer Boolean False CG enableButtonTab EnableButtonTab Boolean False CG enableDragIcon EnableDragIcon Boolean False CG enableEtchedInMenu EnableEtchedInMenu Boolean False CG enableMultiKeyBindings EnableMultiKeyBindings Boolean False CG enableToggleColor EnableToggleColor Boolean False CG enableToggleVisual EnableToggleVisual Boolean False CG enableUnselectableDrag EnableUnselectableDrag Boolean True CG .TE .KE .in .sp 1 .P .IP "\fIXmNdefaultVirtualBindings\fP" Specifies the default virtual bindings for the display. Following is an example of a specification for the \fIdefaultVirtualBindings\fP resource in a resource file: .oS .ta 0.5i 2i 2.5i 3.75i .nf *defaultVirtualBindings: \e osfBackSpace : BackSpace \en\e osfInsert : InsertChar \en\e \&... osfDelete : DeleteChar .fi .oE .IP "\fIXmNdragInitiatorProtocolStyle\fP" Specifies the drag and drop protocol requirements or preference when the client is an initiator. The possible values are .IP "\fIXmDRAG_PREREGISTER\fP" As an initiator, this client does not use the dynamic protocol and can only arrange visual effects with receivers who provide preregistered information. .IP "\fIXmDRAG_DYNAMIC\fP" As an initiator, this client does not make use of any preregistered drop site information made available by other clients, and can only arrange visual effects with receivers who use the dynamic protocol. .IP "\fIXmDRAG_NONE\fP" Specifies that drag and drop is disabled for this client. .IP "\fIXmDRAG_DROP_ONLY\fP" As an initiator, this client does not use either the preregistered drop site information or the dynamic protocol. It supports dragging, and any time the cursor is over a client that supports drag and drop, valid feedback is provided. There are no other visual effects. .IP "\fIXmDRAG_PREFER_DYNAMIC\fP" As an initiator, this client can support both the preregister and dynamic protocols, but prefers to use dynamic protocols whenever possible in order to provide high-quality drag-under feedback. .IP "\fIXmDRAG_PREFER_PREREGISTER\fP" As an initiator, this client can support both the preregister and dynamic protocols, but prefers to use the preregister protocol whenever possible in order to accommodate performance needs or to provide consistent drag-over feedback. .IP "\fIXmDRAG_PREFER_RECEIVER\fP" Indicates that this client can support both preregister and dynamic protocols, but will defer to the preference of the receiver client. This value is valid only for the \fIXmNdragInitiatorProtocolStyle\fP resource, and is its default value. .IP "\fIXmNdragReceiverProtocolStyle\fP" Specifies the drag and drop protocol requirements or preference when this client is a receiver. The values are .IP "\fIXmDRAG_PREREGISTER\fP" As a receiver, this client preregisters drop site information and does not use the dynamic protocol. It can only arrange visual effects with initiators who make use of the preregistered information. .IP "\fIXmDRAG_DYNAMIC\fP" As a receiver, this client uses the dynamic protocol and does not preregister drop site information. It can only arrange visual effects with initiators who use the dynamic protocol. .IP "\fIXmDRAG_NONE\fP" Specifies that drag and drop is disabled for this client. .IP "\fIXmDRAG_DROP_ONLY\fP" As a receiver, this client neither uses the dynamic protocol nor preregisters drop site information. It supports dropping, and when dragging over this client, valid feedback is always provided, but there are no other visual effects. .IP "\fIXmDRAG_PREFER_DYNAMIC\fP" As a receiver, this client can support both the preregister and dynamic protocols, but prefers to use dynamic protocol whenever possible in order to provide high-quality drag-under feedback. .IP "\fIXmDRAG_PREFER_PREREGISTER\fP" As a receiver, this client can support both the preregister and dynamic protocols, but prefers to use the preregister protocol whenever possible in order to accommodate performance needs. .IP The actual protocol used between an initiator and a receiver is based on the protocol style of the receiver and initiator. The decision matrix is shown in the XmDisplay(3X) man page in the "OSF/Motif 1.2 Programmer's Reference Manual." .IP The value \fIXmDRAG_NONE\fP does not appear in the above matrix. When specified for either the initiator or receiver side, \fIXmDRAG_NONE\fP implies that drag and drop transactions are not supported. A value of \fIXmDRAG_DROP_ONLY\fP (Drop Only) results when an initiator and receiver cannot compromise protocol styles, that is, one client requires dynamic mode while the other can only support preregister mode, or if either explicitly has specified \fIXmDRAG_DROP_ONLY\fP. .IP "\fIdefaultButtonEmphasis\fP" This resource specifies whether to change the look of the PushButton widget and gadget that have the \fIXmNshowAsDefault\fP resource set. When the control is the default, the PushButton has an etched out button which is enclosed with another etched in border. When this resource is "internal_highlight", the location cursor appears in between the two etched borders to minimize the space required. When this resource is "external_highlight", the default PushButton draws the location cursor outside the second border. .IP "\fIenableBtn1Transfer\fP" When this resource is True, it specifies that the actions for selection and transfer are integrated on the Button1, and the extend selection actions are activated from Button2. This resource impacts the actions of the XmText, XmTextField, and XmList widgets. .IP "\fIenableButtonTab\fP" When this resource is True, it specifies whether to modify the action for the TAB key (KNextField and KPrevField) to move as an arrow key until the boundary of a tab group is reached. When at the boundary of the tab group, the KNextField and KPrevField actions will move to the next or previous tab group, respectively. This resource affects the actions of XmPushButtons, XmArrowButtons, and XmDrawnButtons. .IP "\fIenableDragIcon\fP" Specifies which set of icons be used for the system default cursors during drag and drop operations. When this resource is False, the standard Motif icons are used. When this resource is True, an alternate set of icons that human interface experts designed are used. This resource affects both the 16x16 icons and the 32x32 icons that are the system defaults for each of the XmScreen objects associated with this display. .IP "\fIenableEtchedInMenu\fP" Specifies the shadowing of the button widgets and gadgets in menus when the control is activated. When \fIenableEtchedInMenu\fP is True, the selected menu control is drawn with the shadow etched in; this shadow style is consistent with the selected appearance of other button widgets outside of menus. When \fIenableEtchedInMenu\fP is False, the selected menu control is drawn with the shadow etched out. This resource impacts the appearance of PushButtons, ToggleButtons, and CascadeButtons when they are children of an XmMenu. .IP "\fIenableMultiKeyBindings\fP" Specifies whether to modify the widget and gadget translations to support some MS-Windows common key bindings. When this resource is False, the default, the translations are not modified. When this resource is True, the following XtNbaseTranslations resources are merged into the resource database. When an application has specified a XtNbaseTranslations resource, it will have precedence over these definitions. .nf *XmArrowButton.baseTranslations: #override F1 : Help() cs : PrimitiveParentCancel() Escape : PrimitiveParentCancel() *XmBulletinBoard.baseTranslations: #override F1:ManagerGadgetHelp() cs : ManagerParentCancel() Escape : ManagerParentCancel() *XmCascadeButton.baseTranslations: #override F1:Help() cs : CleanupMenuBar() Escape : CleanupMenuBar() *XmDragContext.baseTranslations : #override F1:HelpDrag() cs : CancelDrag() Escape : CancelDrag() *XmDrawingArea.baseTranslations: #override F1 : DrawingAreaInput() ManagerGadgetHelp() cs : DrawingAreaInput() ManagerParentCancel() Escape : DrawingAreaInput() ManagerParentCancel() *XmDrawnButton.baseTranslations: #override F1:Help() cs : PrimitiveParentCancel() Escape : PrimitiveParentCancel() *XmFrame.baseTranslations: #override cs : ManagerParentCancel() Escape : ManagerParentCancel() *XmLabel.baseTranslations: #override F1:Help() cs : PrimitiveParentCancel() Escape : PrimitiveParentCancel() : *XmList.baseTranslations: #override F1:PrimitiveHelp() cs : ListKbdCancel() Escape : ListKbdCancel() *XmManager.baseTranslations: #override F1:ManagerGadgetHelp() cs : ManagerParentCancel() Escape : ManagerParentCancel() *XmPrimitive.baseTranslations: #override F1:PrimitiveHelp() cs : PrimitiveParentCancel() Escape : PrimitiveParentCancel() *XmPushButton.baseTranslations: #override F1:Help() cs : PrimitiveParentCancel() Escape : PrimitiveParentCancel() : *XmRowColumn.baseTranslations: #override F1:MenuHelp() cs : ManagerParentCancel() Escape : ManagerParentCancel() *XmSash.baseTranslations: #override F1:Help() cs : PrimitiveParentCancel() Escape : PrimitiveParentCancel() *XmScrollBar.baseTranslations: #override F1:PrimitiveHelp() cs : CancelDrag() Escape : CancelDrag() *XmScrolledWindow.baseTranslations: #override F1:ManagerGadgetHelp() cs : ManagerParentCancel() Escape : ManagerParentCancel() *XmTextField.baseTranslations: #override F1: Help() cs : process-cancel() Escape : process-cancel() cx : cut-clipboard() cc : copy-clipboard() cv : paste-clipboard() sDelete : cut-clipboard() cInsert : copy-clipboard() sInsert : paste-clipboard() *XmText.baseTranslations: #override F1: Help() cs : process-cancel() Escape : process-cancel() cx : cut-clipboard() cc : copy-clipboard() cv : paste-clipboard() sDelete : cut-clipboard() cInsert : copy-clipboard() sInsert : paste-clipboard() *XmToggleButton.baseTranslations: #override F1: Help() cs : PrimitiveParentCancel() Escape : PrimitiveParentCancel() : .fi .IP From the user's perspective, setting the \fIenableMultiKeyBindings\fP resource to True has the following affect: .wH .rS .TP \(bu use of F1 function key for accessing help .TP \(bu use both s and Escape for canceling an operation .TP \(bu disable drag from labels in XmLabel, XmPushButton, XmToggleButton, and XmScale widgets and gadgets .TP \(bu use both x and Delete to cut text .TP \(bu use both c and Insert to copy text .TP \(bu use both v and Insert to paste text .wH .rE .nL .ne 10 .IP "\fIenableToggleColor\fP" Specifies whether the fill color of the ToggleButton widget and gadget uses the background or the highlight color. When \fIenableToggleColor\fP is True, the fill color uses the highlight color. The highlight color makes it more obvious to the end user that the Toggle has been set. When \fIenableToggleColor\fP is False, the fill color uses the background color. This resource affects the appearance of all ToggleButton widgets and gadgets. .IP "\fIenableToggleVisual\fP" Specifies the visual appearance of the ToggleButton widget and gadgets. When this resource is True, the look specified by the ToggleButton's \fIXmNindicatorType\fP resource is as follows: .wH .rS .TP \(bu \fIXmONE_OF_MANY\fP - a shadowed circle .TP \(bu \fIXmN_OF_MANY\fP - a shadowed square with a check mark when set .wH .rE .nL .ne 6 .IP When this resource is False, the look specified by the ToggleButton's \fIXmNindicatorType\fP resource is as follows: .wH .rS .TP \(bu \fIXmONE_OF_MANY\fP - a shadowed diamond .TP \(bu \fIXmN_OF_MANY\fP - a shadowed square .wH .rE .nL .ne 6 .IP This resource affects the appearance of all ToggleButton widgets and gadgets. .IP "\fIenableUnselectableDrag\fP" Specifies whether the user can drag text that is not selectable such as the labels on buttons. The default is True so that the use can drag all text. When this resource is set to False, the text on Buttons, Labels, and Scales cannot be the source of a drag operation. .SS "Inherited Resources" All of the superclass resources inherited by XmDisplay are designated N/A (not applicable). .SH RELATED INFORMATION .na \fIApplicationShell(3X)\fP, \fIComposite(3X)\fP, \fICore(3X)\fP, \fITopLevelShell(3X)\fP, \fIVendorShell(3X)\fP, \fIWMShell(3X)\fP, \fIXmGetXmDisplay(3X)\fP, and \fIXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDragCancel 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDragCancel\fP \- A Drag and Drop function that terminates a drag transaction .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmDragCancel (\fBdragcontext\fI) .ta .5i 1.75i .nf Widget \fBdragcontext\fI; .iE .sE .SH DESCRIPTION .fi \fIXmDragCancel\fP terminates a drag operation and cancels any pending actions of the specified DragContext. This routine can only be called by the initiator client. .IP "\fBdragcontext\fP" Specifies the ID of the DragContext widget associated with the drag and drop transaction to be terminated .PP For a complete definition of DragContext and its associated resources, see \fIXmDragContext(3X)\fP. .SH RELATED INFORMATION .na \fIXmDragContext(3X)\fP and \fIXmDragStart(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1991, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1991 by Hewlett-Packard Company ...\" ** ...\" ** .TH XmDragContext 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDragContext\fP \- The DragContext widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi DragContexts are special widgets used in drag and drop transactions. A DragContext is implemented as a widget, but a client does not explicitly create a DragContext widget. Instead, a client initiates a drag and drop transaction by calling \fIXmDragStart\fP, and this routine initializes and returns a DragContext widget. There is a unique DragContext for each drag operation. The toolkit frees a DragContext when a transaction is complete; therefore, an application programmer should not explicitly destroy a DragContext. .PP Initiator and receiver clients both use DragContexts to track the state of a transaction. When the initiator and receiver of a transaction are in the same client, they share the same DragContext instance. If they are in different clients, there are two separate DragContexts. In this case, the initiator calls \fIXmDragStart\fP and the toolkit provides a DragContext for the receiver client. The only resources pertinent to the receiver are \fIXmNexportTargets\fP and \fIXmNnumExportTargets\fP. These can both be passed as arguments to the \fIXmDropSiteRetrieve\fP function to obtain information about the current drop site. .PP In general, in order to receive data, a drop site must share at least one target type and operation in common with a drag source. The DragContext resource, \fIXmNexportTargets\fP, identifies the selection targets for the drag source. These export targets are compared with the \fIXmNimportTargets\fP resource list specified by a drop site. The DragContext resource, \fIXmNdragOperations\fP, identifies the valid operations that can be applied to the source data by the initiator. The drop site counterpart resource is \fIXmNdropSiteOperations\fP, which indicates a drop site's supported operations. .PP A client uses DragIcon widgets to define the drag-over animation effects associated with a given drag and drop transaction. An initiator specifies a set of drag icons, selects a blending model, and sets foreground and background cursor colors with DragContext resources. .PP The type of drag-over visual used to represent a drag operation depends on the drag protocol style. In preregister mode, the server is grabbed, and either a cursor or a pixmap may be used as a drag-over visual. In dynamic mode, drag-over visuals must be implemented with the X cursor. If the resulting drag protocol style is Drop Only or None and the \fIXmNdragInitiatorProtocolStyle\fP is \fIXmDRAG_DYNAMIC\fP or \fIXmDRAG_PREFER_DYNAMIC\fP, then a dynamic visual style (cursor) is used. Otherwise, a preregister visual style is used. .SS "Classes" DragContext inherits behavior and resources from \fICore\fP. .PP The class pointer is \fIxmDragContextClass\fP. .PP The class name is \fIXmDragContext\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (\fIC\fP), set by using \fIXtSetValues\fP (\fIS\fP), retrieved by using \fIXtGetValues\fP (\fIG\fP), or is not applicable (\fIN/A\fP). .PP .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmDragContext Resource Set Name Class Type Default Access _ XmNblendModel XmCBlendModel unsigned char XmBLEND_ALL CG XmNclientData XmCClientData XtPointer NULL CSG XmNconvertProc XmCConvertProc XtConvertSelectionIncrProc NULL CSG XmNcursorBackground XmCCursorBackground Pixel dynamic CSG XmNcursorForeground XmCCursorForeground Pixel dynamic CSG XmNdragDropFinishCallback XmCCallback XtCallbackList NULL CSG XmNdragMotionCallback XmCCallback XtCallbackList NULL C XmNdragOperations XmCDragOperations unsigned char XmDROP_COPY | XmDROP_MOVE C XmNdropFinishCallback XmCCallback XtCallbackList NULL C XmNdropSiteEnterCallback XmCCallback XtCallbackList NULL C XmNdropSiteLeaveCallback XmCCallback XtCallbackList NULL C XmNdropStartCallback XmCCallback XtCallbackList NULL C XmNexportTargets XmCExportTargets Atom * NULL CSG XmNincremental XmCIncremental Boolean False CSG XmNinvalidCursorForeground XmCCursorForeground Pixel dynamic CSG XmNnoneCursorForeground XmCCursorForeground Pixel dynamic CSG XmNnumExportTargets XmCNumExportTargets Cardinal 0 CSG XmNoperationChangedCallback XmCCallback XtCallbackList NULL C XmNoperationCursorIcon XmCOperationCursorIcon Widget dynamic CSG XmNsourceCursorIcon XmCSourceCursorIcon Widget dynamic CSG XmNsourcePixmapIcon XmCSourcePixmapIcon Widget dynamic CSG XmNstateCursorIcon XmCStateCursorIcon Widget dynamic CSG XmNtopLevelEnterCallback XmCCallback XtCallbackList NULL C XmNtopLevelLeaveCallback XmCCallback XtCallbackList NULL C XmNvalidCursorForeground XmCCursorForeground Pixel dynamic CSG .TE .KE .in .sp 1 .PP .IP "\fIXmNblendModel\fP" Specifies which combination of DragIcons are blended to produce a drag-over visual. .IP "\fIXmBLEND_ALL\fP" Blends all three DragIcons - the source, state and operation icon. The icons are layered from top to bottom with the operation icon on top and the source icon on the bottom. The hotspot is derived from the state icon. .IP "\fIXmBLEND_STATE_SOURCE\fP" Blends the state and source icons only. The hotspot is derived from the state icon. .IP "\fIXmBLEND_JUST_SOURCE\fP" Specifies that only the source icon is used, which the initiator updates as required. .IP "\fIXmBLEND_NONE\fP" Specifies that no drag-over visual is generated. The client tracks the drop site status through callback routines and updates the drag-over visuals as necessary. .IP "\fIXmNclientData\fP" Specifies the client data to be passed to the \fIXmNconvertProc\fP when it is invoked. .IP "\fIXmNconvertProc\fP" Specifies a procedure of type \fIXtConvertSelectionIncrProc\fP that converts the source data to the format(s) requested by the receiver client. The \fBwidget\fP argument passed to this procedure is the DragContext widget. The selection atom passed is _MOTIF_DROP. If \fIXmNincremental\fP is False, the procedure should ignore the \fBmax_length\fP, \fBclient_data\fP, and \fBrequest_id\fP arguments and should handle the conversion atomically. Data returned by \fIXmNconvertProc\fP must be allocated using \fIXtMalloc\fP and will be freed automatically by the toolkit after the transfer. For additional information on selection conversion procedures, see \*EX Toolkit Intrinsics \- C Language Interface\fP. .IP "\fIXmNcursorBackground\fP" Specifies the background pixel value of the cursor. .IP "\fIXmNcursorForeground\fP" Specifies the foreground pixel value of the cursor when the state icon is not blended. This resource defaults to the foreground color of the widget passed to the \fIXmDragStart\fP function. .IP "\fIXmNdragDropFinishCallback\fP" Specifies the list of callbacks that are called when the transaction is completed. The type of the structure whose address is passed to this callback is \fIXmDragDropFinishCallbackStruct\fP. The reason sent by the callback is \fIXmCR_DRAG_DROP_FINISH\fP. .IP "\fIXmNdragMotionCallback\fP" Specifies the list of callbacks that are invoked when the pointer moves. The type of structure whose address is passed to this callback is \fIXmDragMotionCallbackStruct\fP. The reason sent by the callback is \fIXmCR_DRAG_MOTION\fP. .IP "\fIXmNdragOperations\fP" Specifies the set of valid operations associated with an initiator client for a drag transaction. This resource is a bit mask that is formed by combining one or more of the following values using a bitwise operation such as inclusive OR (|): \fIXmDROP_COPY\fP, \fIXmDROP_LINK\fP, \fIXmDROP_MOVE\fP. The value \fIXmDROP_NOOP\fP for this resource indicates that no operations are valid. For Text and TextField widgets, this resource is set to \fIXmDROP_COPY\fP | \fIXmDROP_MOVE\fP; for List widgets, it is set to \fIXmDROP_COPY\fP. .IP "\fIXmNdropFinishCallback\fP" Specifies the list of callbacks that are invoked when the drop is completed. The type of the structure whose address is passed to this callback is \fIXmDropFinishCallbackStruct\fP. The reason sent by the callback is \fIXmCR_DROP_FINISH\fP. .IP "\fIXmNdropSiteEnterCallback\fP" Specifies the list of callbacks that are invoked when the pointer enters a drop site. The type of the structure whose address is passed to this callback is \fIXmDropSiteEnterCallbackStruct\fP. The reason sent by the callback is \fIXmCR_DROP_SITE_ENTER\fP. .IP "\fIXmNdropSiteLeaveCallback\fP" Specifies the list of callbacks that are invoked when the pointer leaves a drop site. The type of the structure whose address is passed to this callback is \fIXmDropSiteLeaveCallbackStruct\fP. The reason sent by the callback is \fIXmCR_DROP_SITE_LEAVE\fP. .IP "\fIXmNdropStartCallback\fP" Specifies the list of callbacks that are invoked when a drop is initiated. The type of the structure whose address is passed to this callback is \fIXmDropStartCallbackStruct\fP. The reason sent by the callback is \fIXmCR_DROP_START\fP. .IP "\fIXmNexportTargets\fP" Specifies the list of target atoms associated with this source. This resource identifies the selection targets this source can be converted to. .IP "\fIXmNincremental\fP" Specifies a Boolean value that indicates whether the transfer on the initiator side uses the Xt incremental selection transfer mechanism described in \*EX Toolkit Intrinsics \- C Language Interface\fP. If the value is True, the initiator uses incremental transfer; if the value is False, the initiator uses atomic transfer. .IP "\fIXmNinvalidCursorForeground\fP" Specifies the foreground pixel value of the cursor when the state is invalid. This resource defaults to the value of the \fIXmNcursorForeground\fP resource. .IP "\fIXmNnoneCursorForeground\fP" Specifies the foreground pixel value of the cursor when the state is none. This resource defaults to the value of the \fIXmNcursorForeground\fP resource. .IP "\fIXmNnumExportTargets\fP" Specifies the number of entries in the list of export targets. .IP "\fIXmNoperationChangedCallback\fP" Specifies the list of callbacks that are invoked when the drag is started and when the user requests that a different operation be applied to the drop. The type of the structure whose address is passed to this callback is \fIXmOperationChangedCallbackStruct\fP. The reason sent by the callback is \fIXmCR_OPERATION_CHANGED\fP. .IP "\fIXmNoperationCursorIcon\fP" Specifies the cursor icon used to designate the type of operation performed by the drag transaction. If NULL, \fIXmScreen\fP resources provide default icons for copy, link, and move operations. .IP "\fIXmNsourceCursorIcon\fP" Specifies the cursor icon used to represent the source when a dynamic visual style is used. If NULL, the \fIXmNdefaultSourceCursorIcon\fP resource of \fIXmScreen\fP provides a default cursor icon. .IP "\fIXmNsourcePixmapIcon\fP" Specifies the pixmap icon used to represent the source when a preregister visual style is used. The icon is used in conjunction with the colormap of the widget passed to \fIXmDragStart\fP. If NULL, \fIXmNsourceCursorIcon\fP is used. .IP "\fIXmNstateCursorIcon\fP" Specifies the cursor icon used to designate the state of a drop site. If NULL, \fIXmScreen\fP resources provide default icons for a valid, invalid, and no drop site condition. .IP "\fIXmNtopLevelEnterCallback\fP" Specifies the list of callbacks that are called when the pointer enters a top-level window or root window (due to changing screens). The type of the structure whose address is passed to this callback is \fIXmTopLevelEnterCallbackStruct\fP. The reason sent by the callback is \fIXmCR_TOP_LEVEL_ENTER\fP. .IP "\fIXmNtopLevelLeaveCallback\fP" Specifies the list of callbacks that are called when the pointer leaves a top level window or the root window (due to changing screens). The type of the structure whose address is passed to this callback is \fIXmTopLevelLeaveCallbackStruct\fP. The reason sent by the callback is \fIXmCR_TOP_LEVEL_LEAVE\fP. .IP "\fIXmNvalidCursorForeground\fP" Specifies the foreground pixel value of the cursor designated as a valid cursor icon. .SS "Inherited Resources" DragContext inherits behavior and resources from the following superclass. For a complete description of each resource, refer to the \fICore\fP man page. .PP .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .PP .SS "Callback Information" Each of the DragContext callbacks has an associated callback structure. .PP .nL .PP A pointer to the following structure is passed to the \fIXmNdragDropFinishCallback\fP callback. .ne 10 .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent *\fBevent\fI; Time \fBtimeStamp\fI; }XmDragDropFinishCallbackStruct, *XmDragDropFinishCallback; .iE .sE .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBtimestamp\fP" Specifies the time at which either the drag or the drop was completed. .PP A pointer to the following structure is passed to callbacks for \fIXmNdragMotionCallback\fP. .nL .ne 10 .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent *\fBevent\fI; Time \fBtimeStamp\fI; unsigned char \fBoperation\fI; unsigned char \fBoperations\fI; unsigned char \fBdropSiteStatus\fI; Position \fBx\fI; Position \fBy\fI; }XmDragMotionCallbackStruct, *XmDragMotionCallback; .iE .sE .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBtimeStamp\fP" Specifies the timestamp of the logical event. .IP "\fBoperation\fP" Identifies an operation. .PP If the toolkit has just called a DropSite's \fIXmNdragProc\fP, the toolkit initializes \fBoperation\fP to the value of the \fBoperation\fP member of the \fIXmDragProcCallbackStruct\fP at the time the DropSite's \fIXmNdragProc\fP returns. .PP If the toolkit has not called an \fIXmNdragProc\fP and the pointer is within an active drop site, the toolkit initializes \fBoperation\fP by selecting an operation from the bitwise AND of the initial value of the \fBoperations\fP member and the value of the DropSite's \fIXmNdropSiteOperations\fP resource. The toolkit searches this set first for \fIXmDROP_MOVE\fP, then for \fIXmDROP_COPY\fP, then for \fIXmDROP_LINK\fP, and initializes \fBoperation\fP to the first operation it finds in the set. If the toolkit finds none of these operations in the set, it initializes \fBoperation\fP to \fIXmDROP_NOOP\fP. .PP If the toolkit has not called an \fIXmNdragProc\fP and the pointer is not within an active drop site, the toolkit initializes \fBoperation\fP by selecting an operation from the initial value of the \fBoperations\fP member. The toolkit searches this set first for \fIXmDROP_MOVE\fP, then for \fIXmDROP_COPY\fP, then for \fIXmDROP_LINK\fP, and initializes \fBoperation\fP to the first operation it finds in the set. If the toolkit finds none of these operations in the set, it initializes \fBoperation\fP to \fIXmDROP_NOOP\fP. .IP "\fBoperations\fP" Indicates the set of operations supported for the source data. .PP If the toolkit has just called a DropSite's \fIXmNdragProc\fP, the toolkit initializes \fBoperations\fP to the bitwise AND of the DropSite's \fIXmNdropOperations\fP and the value of the \fBoperations\fP member of the \fIXmDragProcCallbackStruct\fP at the time the DropSite's \fIXmNdragProc\fP returns. If the resulting set of operations is empty, the toolkit initializes \fBoperations\fP to \fIXmDROP_NOOP\fP. .PP If the toolkit has not called an \fIXmNdragProc\fP and the user does not select an operation (by pressing a modifier key), the toolkit initializes \fBoperations\fP to the value of the DragContext's \fIXmNdragOperations\fP resource. .PP If the toolkit has not called an \fIXmNdragProc\fP and the user does select an operation, the toolkit initializes \fBoperations\fP to the bitwise AND of the corresponding operation and the value of the DragContext's \fIXmNdragOperations\fP resource. If the resulting set of operations is empty, the toolkit initializes \fBoperations\fP to \fIXmDROP_NOOP\fP. .IP "\fBdropSiteStatus\fP" Indicates whether or not a drop site is valid. .PP If the toolkit has just called a DropSite's \fIXmNdragProc\fP, the toolkit initializes \fBdropSiteStatus\fP to the value of the \fBdropSiteStatus\fP member of the \fIXmDragProcCallbackStruct\fP at the time the DropSite's \fIXmNdragProc\fP returns. .PP If the toolkit has not called an \fIXmNdragProc\fP, it initializes \fBdropSiteStatus\fP as follows: the toolkit initializes \fBdropSiteStatus\fP to \fIXmNO_DROP_SITE\fP if the pointer is over an inactive drop site or is not over a drop site. The toolkit initializes \fBdropSiteStatus\fP to \fIXmDROP_SITE_VALID\fP if all the following conditions are met: .TP \(bu The pointer is over an active drop site. .TP \(bu The DragContext's \fIXmNexportTargets\fP and the DropSite's \fIXmNimportTargets\fP are compatible. .TP \(bu The initial value of the \fBoperation\fP member is not \fIXmDROP_NOOP\fP. Otherwise, the toolkit initializes \fBdropSiteStatus\fP to \fIXmDROP_SITE_INVALID\fP. .nL .PP A pointer to the following structure is passed for the \fIXmNdropFinishCallback\fP callback: .ne 10 .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent *\fBevent\fI; Time \fBtimeStamp\fI; unsigned char \fBoperation\fI; unsigned char \fBoperations\fI; unsigned char \fBdropSiteStatus\fI; unsigned char \fBdropAction\fI; unsigned char \fBcompletionStatus\fI; }XmDropFinishCallbackStruct, *XmDropFinishCallback; .iE .sE .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBtimeStamp\fP" Specifies the time at which the drop was completed. .IP "\fBoperation\fP" Identifies an operation. .PP If the pointer is over an active drop site when the drop begins, the toolkit initializes \fBoperation\fP to the value of the \fBoperation\fP member of the \fIXmDropProcCallbackStruct\fP at the time the DropSite's \fIXmNdropProc\fP returns. .PP If the pointer is not over an active drop site when the drop begins, the toolkit initializes \fBoperation\fP by selecting an operation from the initial value of the \fBoperations\fP member. The toolkit searches this set first for \fIXmDROP_MOVE\fP, then for \fIXmDROP_COPY\fP, then for \fIXmDROP_LINK\fP, and initializes \fBoperation\fP to the first operation it finds in the set. If it finds none of these operations in the set, it initializes \fBoperation\fP to \fIXmDROP_NOOP\fP. .IP "\fBoperations\fP" Indicates the set of operations supported for the source data. .PP If the pointer is over an active drop site when the drop begins, the toolkit initializes \fBoperations\fP to the bitwise AND of the DropSite's \fIXmNdropOperations\fP and the value of the \fBoperations\fP member of the \fIXmDropProcCallbackStruct\fP at the time the DropSite's \fIXmNdropProc\fP returns. If the resulting set of operations is empty, the toolkit initializes \fBoperations\fP to \fIXmDROP_NOOP\fP. .PP If the pointer is not over an active drop site when the drop begins and if the user does not select an operation (by pressing a modifier key), the toolkit initializes \fBoperations\fP to the value of the DragContext's \fIXmNdragOperations\fP resource. .PP If the pointer is not over an active drop site when the drop begins and if the user does select an operation, the toolkit initializes \fBoperations\fP to the bitwise AND of the corresponding operation and the value of the DragContext's \fIXmNdragOperations\fP resource. If the resulting set of operations is empty, the toolkit initializes \fBoperations\fP to \fIXmDROP_NOOP\fP. .IP "\fBdropSiteStatus\fP" Indicates whether or not a drop site is valid. .PP If the pointer is over an active drop site when the drop begins, the toolkit initializes \fBdropSiteStatus\fP to the value of the \fBdropSiteStatus\fP member of the \fIXmDropProcCallbackStruct\fP at the time the DropSite's \fIXmNdropProc\fP returns. .PP If the pointer is not over an active drop site when the drop begins, the toolkit initializes \fBdropSiteStatus\fP to \fIXmNO_DROP_SITE\fP. .IP "\fBdropAction\fP" Identifies the drop action. The values are: \fIXmDROP\fP, \fIXmDROP_CANCEL\fP, \fIXmDROP_HELP\fP, and \fIXmDROP_INTERRUPT\fP. The value \fIXmDROP_INTERRUPT\fP is currently unsupported; if specified, it will be interpreted as an \fIXmDROP_CANCEL\fP. .IP "\fBcompletionStatus\fP" An IN/OUT member that indicates the status of the drop action. After the last callback procedure has returned, the final value of this member determines what visual transition effects will be applied. There are two values: .IP "\fIXmDROP_SUCCESS\fP" The drop was successful. .IP "\fIXmDROP_FAILURE\fP" The drop was unsuccessful. .nL .PP A pointer to the following structure is passed to callbacks for \fIXmNdropSiteEnterCallback\fP: .ne 10 .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent *\fBevent\fI; Time \fBtimeStamp\fI; unsigned char \fBoperation\fI; unsigned char \fBoperations\fI; unsigned char \fBdropSiteStatus\fI; Position \fBx\fI; Position \fBy\fI; }XmDropSiteEnterCallbackStruct, *XmDropSiteEnterCallback; .iE .sE .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBtimestamp\fP" Specifies the time the crossing event occurred. .IP "\fBoperation\fP" Identifies an operation. .PP If the toolkit has just called a DropSite's \fIXmNdragProc\fP, the toolkit initializes \fBoperation\fP to the value of the \fBoperation\fP member of the \fIXmDragProcCallbackStruct\fP at the time the DropSite's \fIXmNdragProc\fP returns. .PP If the toolkit has not called an \fIXmNdragProc\fP, it initializes \fBoperation\fP by selecting an operation from the bitwise AND of the initial value of the \fBoperations\fP member and the value of the DropSite's \fIXmNdropSiteOperations\fP resource. The toolkit searches this set first for \fIXmDROP_MOVE\fP, then for \fIXmDROP_COPY\fP, then for \fIXmDROP_LINK\fP, and initializes \fBoperation\fP to the first operation it finds in the set. If the toolkit finds none of these operations in the set, it initializes \fBoperation\fP to \fIXmDROP_NOOP\fP. .IP "\fBoperations\fP" Indicates the set of operations supported for the source data. .PP If the toolkit has just called a DropSite's \fIXmNdragProc\fP, the toolkit initializes \fBoperations\fP to the bitwise AND of the DropSite's \fIXmNdropOperations\fP and the value of the \fBoperations\fP member of the \fIXmDragProcCallbackStruct\fP at the time the DropSite's \fIXmNdragProc\fP returns. If the resulting set of operations is empty, the toolkit initializes \fBoperations\fP to \fIXmDROP_NOOP\fP. .PP If the toolkit has not called an \fIXmNdragProc\fP and the user does not select an operation (by pressing a modifier key), the toolkit initializes \fBoperations\fP to the value of the DragContext's \fIXmNdragOperations\fP resource. .PP If the toolkit has not called an \fIXmNdragProc\fP and the user does select an operation, the toolkit initializes \fBoperations\fP to the bitwise AND of the corresponding operation and the value of the DragContext's \fIXmNdragOperations\fP resource. If the resulting set of operations is empty, the toolkit initializes \fBoperations\fP to \fIXmDROP_NOOP\fP. .IP "\fBdropSiteStatus\fP" Indicates whether or not a drop site is valid. .PP If the toolkit has just called a DropSite's \fIXmNdragProc\fP, the toolkit initializes \fBdropSiteStatus\fP to the value of the \fBdropSiteStatus\fP member of the \fIXmDragProcCallbackStruct\fP at the time the DropSite's \fIXmNdragProc\fP returns. .PP If the toolkit has not called an \fIXmNdragProc\fP, it initializes \fBdropSiteStatus\fP as follows: the toolkit initializes \fBdropSiteStatus\fP to \fIXmDROP_SITE_VALID\fP if the DragContext's \fIXmNexportTargets\fP and the DropSite's \fIXmNimportTargets\fP are compatible and if the initial value of the \fBoperation\fP member is not \fIXmDROP_NOOP\fP. Otherwise, the toolkit initializes \fBdropSiteStatus\fP to \fIXmDROP_SITE_INVALID\fP. .IP "\fBx\fP" Indicates the x-coordinate of the pointer in root window coordinates. .IP "\fBy\fP" Indicates the y-coordinate of the pointer in root window coordinates. .nL .PP A pointer to the following structure is passed to callbacks for \fIXmNdropSiteLeaveCallback\fP. .ne 10 .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent *\fBevent\fI; Time \fBtimeStamp\fI; }XmDropSiteLeaveCallbackStruct, *XmDropSiteLeaveCallback; .iE .sE .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBtimeStamp\fP" Specifies the timestamp of the logical event. .PP A pointer to the following structure is passed for the \fIXmNdropStartCallback\fP callback: .ne 10 .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent *\fBevent\fI; Time \fBtimeStamp\fI; unsigned char \fBoperation\fI; unsigned char \fBoperations\fI; unsigned char \fBdropSiteStatus\fI; unsigned char \fBdropAction\fI; Position \fBx\fI; Position \fBy\fI; }XmDropStartCallbackStruct, *XmDropStartCallback; .iE .sE .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBtimeStamp\fP" Specifies the time at which the drag was completed. .IP "\fBoperation\fP" Identifies an operation. .PP If the pointer is over an active drop site when the drop begins, the toolkit initializes \fBoperation\fP to the value of the \fBoperation\fP member of the \fIXmDropProcCallbackStruct\fP at the time the DropSite's \fIXmNdropProc\fP returns. .PP If the pointer is not over an active drop site when the drop begins, the toolkit initializes \fBoperation\fP by selecting an operation from the initial value of the \fBoperations\fP member. The toolkit searches this set first for \fIXmDROP_MOVE\fP, then for \fIXmDROP_COPY\fP, then for \fIXmDROP_LINK\fP, and initializes \fBoperation\fP to the first operation it finds in the set. If it finds none of these operations in the set, it initializes \fBoperation\fP to \fIXmDROP_NOOP\fP. .IP "\fBoperations\fP" Indicates the set of operations supported for the source data. .PP If the pointer is over an active drop site when the drop begins, the toolkit initializes \fBoperations\fP to the bitwise AND of the DropSite's \fIXmNdropOperations\fP and the value of the \fBoperations\fP member of the \fIXmDropProcCallbackStruct\fP at the time the DropSite's \fIXmNdropProc\fP returns. If the resulting set of operations is empty, the toolkit initializes \fBoperations\fP to \fIXmDROP_NOOP\fP. .PP If the pointer is not over an active drop site when the drop begins and if the user does not select an operation (by pressing a modifier key), the toolkit initializes \fBoperations\fP to the value of the DragContext's \fIXmNdragOperations\fP resource. .PP If the pointer is not over an active drop site when the drop begins and if the user does select an operation, the toolkit initializes \fBoperations\fP to the bitwise AND of the corresponding operation and the value of the DragContext's \fIXmNdragOperations\fP resource. If the resulting set of operations is empty, the toolkit initializes \fBoperations\fP to \fIXmDROP_NOOP\fP. .IP "\fBdropSiteStatus\fP" Indicates whether or not a drop site is valid. .PP If the pointer is over an active drop site when the drop begins, the toolkit initializes \fBdropSiteStatus\fP to the value of the \fBdropSiteStatus\fP member of the \fIXmDropProcCallbackStruct\fP at the time the DropSite's \fIXmNdropProc\fP returns. .PP If the pointer is not over an active drop site when the drop begins, the toolkit initializes \fBdropSiteStatus\fP to \fIXmNO_DROP_SITE\fP. .IP "\fBdropAction\fP" An IN/OUT member that identifies the drop action. The values are \fIXmDROP\fP, \fIXmDROP_CANCEL\fP, \fIXmDROP_HELP\fP, and \fIXmDROP_INTERRUPT\fP. The value of \fBdropAction\fP can be modified to change the action actually initiated. The value \fIXmDROP_INTERRUPT\fP is currently unsupported; if specified, it will be interpreted as a \fIXmDROP_CANCEL\fP. .IP "\fBx\fP" Indicates the x-coordinate of the pointer in root window coordinates. .IP "\fBy\fP" Indicates the y-coordinate of the pointer in root window coordinates. .nL .PP A pointer to the following structure is passed to the \fIXmNoperationChangedCallback\fP callback: .ne 10 .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent *\fBevent\fI; Time \fBtimeStamp\fI; unsigned char \fBoperation\fI; unsigned char \fBoperations\fI; unsigned char \fBdropSiteStatus\fI; }XmOperationChangedCallbackStruct, *XmOperationChangedCallback; .iE .sE .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBtimestamp\fP" Specifies the time at which the crossing event occurred. .IP "\fBoperation\fP" Identifies an operation. .PP If the toolkit has just called a DropSite's \fIXmNdragProc\fP, the toolkit initializes \fBoperation\fP to the value of the \fBoperation\fP member of the \fIXmDragProcCallbackStruct\fP at the time the DropSite's \fIXmNdragProc\fP returns. .PP If the toolkit has not called an \fIXmNdragProc\fP and the pointer is within an active drop site, the toolkit initializes \fBoperation\fP by selecting an operation from the bitwise AND of the initial value of the \fBoperations\fP member and the value of the DropSite's \fIXmNdropSiteOperations\fP resource. The toolkit searches this set first for \fIXmDROP_MOVE\fP, then for \fIXmDROP_COPY\fP, then for \fIXmDROP_LINK\fP, and initializes \fBoperation\fP to the first operation it finds in the set. If the toolkit finds none of these operations in the set, it initializes \fBoperation\fP to \fIXmDROP_NOOP\fP. .PP If the toolkit has not called an \fIXmNdragProc\fP and the pointer is not within an active drop site, the toolkit initializes \fBoperation\fP by selecting an operation from the initial value of the \fBoperations\fP member. The toolkit searches this set first for \fIXmDROP_MOVE\fP, then for \fIXmDROP_COPY\fP, then for \fIXmDROP_LINK\fP, and initializes \fBoperation\fP to the first operation it finds in the set. If the toolkit finds none of these operations in the set, it initializes \fBoperation\fP to \fIXmDROP_NOOP\fP. .IP "\fBoperations\fP" Indicates the set of operations supported for the source data. .PP If the toolkit has just called a DropSite's \fIXmNdragProc\fP, the toolkit initializes \fBoperations\fP to the bitwise AND of the DropSite's \fIXmNdropOperations\fP and the value of the \fBoperations\fP member of the \fIXmDragProcCallbackStruct\fP at the time the DropSite's \fIXmNdragProc\fP returns. If the resulting set of operations is empty, the toolkit initializes \fBoperations\fP to \fIXmDROP_NOOP\fP. .PP If the toolkit has not called an \fIXmNdragProc\fP and the user does not select an operation (by pressing a modifier key), the toolkit initializes \fBoperations\fP to the value of the DragContext's \fIXmNdragOperations\fP resource. .PP If the toolkit has not called an \fIXmNdragProc\fP and the user does select an operation, the toolkit initializes \fBoperations\fP to the bitwise AND of the corresponding operation and the value of the DragContext's \fIXmNdragOperations\fP resource. If the resulting set of operations is empty, the toolkit initializes \fBoperations\fP to \fIXmDROP_NOOP\fP. .IP "\fBdropSiteStatus\fP" Indicates whether or not a drop site is valid. .PP If the toolkit has just called a DropSite's \fIXmNdragProc\fP, the toolkit initializes \fBdropSiteStatus\fP to the value of the \fBdropSiteStatus\fP member of the \fIXmDragProcCallbackStruct\fP at the time the DropSite's \fIXmNdragProc\fP returns. .PP If the toolkit has not called an \fIXmNdragProc\fP, it initializes \fBdropSiteStatus\fP as follows: the toolkit initializes \fBdropSiteStatus\fP to \fIXmNO_DROP_SITE\fP if the pointer is over an inactive drop site or is not over a drop site. The toolkit initializes \fBdropSiteStatus\fP to \fIXmDROP_SITE_VALID\fP if all the following conditions are met: .TP \(bu The pointer is over an active drop site .TP \(bu The DragContext's \fIXmNexportTargets\fP and the DropSite's \fIXmNimportTargets\fP are compatible .TP \(bu The initial value of the \fBoperation\fP member is not \fIXmDROP_NOOP\fP Otherwise, the toolkit initializes \fBdropSiteStatus\fP to \fIXmDROP_SITE_INVALID\fP. .nL .PP A pointer to the following structure is passed to callbacks for \fIXmNtopLevelEnterCallback\fP: .ne 10 .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent *\fBevent\fI; Time \fBtimestamp\fI; Screen \fBscreen\fI; Window \fBwindow\fI; Position \fBx\fI; Position \fBy\fI; unsigned char \fBdragProtocolStyle\fI; }XmTopLevelEnterCallbackStruct, *XmTopLevelEnterCallback; .iE .sE .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBtimeStamp\fP" Specifies the timestamp of the logical event. .IP "\fBscreen\fP" Specifies the screen associated with the top-level window or root window being entered. .IP "\fBwindow\fP" Specifies the ID of the top-level window or root window being entered. .IP "\fBx\fP" Indicates the x-coordinate of the pointer in root window coordinates. .IP "\fBy\fP" Indicates the y-coordinate of the pointer in root window coordinates. .IP "\fBdragProtocolStyle\fP" Specifies the protocol style adopted by the initiator. The values are \fIXmDRAG_DROP_ONLY\fP, \fIXmDRAG_DYNAMIC\fP, \fIXmDRAG_NONE\fP, and \fIXmDRAG_PREREGISTER\fP. .nL .PP A pointer to the following structure is passed to callbacks for \fIXmNtopLevelLeaveCallback\fP: .ne 10 .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent *\fBevent\fI; Time \fBtimestamp\fI; Screen \fBscreen\fI; Window \fBwindow\fI; }XmTopLevelLeaveCallbackStruct, *XmTopLevelLeaveCallback; .iE .sE .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBtimeStamp\fP" Specifies the timestamp of the logical event. .IP "\fBscreen\fP" Specifies a screen associated with the top-level window or root window being left. .IP "\fBwindow\fP" Specifies the ID of the top-level window or root window being left. .PP .SS "Translations" The XmDragContext translations are listed below. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BDrag Motion: DragMotion() BDrag Release: FinishDrag() .sp \n(PDu KCancel: CancelDrag() KHelp: HelpDrag() .nL .wH .fi .iE .SS "Action Routines" The XmDragContext action routines are described below: .IP "\fICancelDrag()\fP:" Cancels the drag operation and frees the associated DragContext. .IP "\fIDragMotion()\fP:" Drags the selected data as the pointer is moved. .IP "\fIFinishDrag()\fP:" Finishes the drag operation and starts the drop operation. .IP "\fIHelpDrag()\fP:" Initiates a conditional drop that enables the receiver to provide help information to the user. The user can cancel or continue the drop operation in response to this information. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .PP .SH "RELATED INFORMATION" .na \fICore(3X)\fP, \fIXmDisplay(3X)\fP, \fIXmDragCancel(3X)\fP, \fIXmDragIcon(3X)\fP, \fIXmDragStart(3X)\fP, \fIXmDropSite(3X)\fP, \fIXmDropTransfer(3X)\fP, and \fIXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1991, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1991 by Hewlett-Packard Company ...\" ** ...\" ** .TH XmDragIcon 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDragIcon\fP \- The DragIcon widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi A DragIcon is a component of the visual used to represent the source data in a drag and drop transaction. During a drag operation, a real or simulated X cursor provides drag-over visuals consisting of a static portion that represents the object being dragged, and dynamic cues that provide visual feedback during the drag operation. The visual is attained by blending together various \fIXmDragIcons\fP specified in the \fIXmDragContext\fP associated with the drag operation. .PP The static portion of the drag-over visual is the graphic representation that identifies the drag source. For example, when a user drags several items within a list, a DragIcon depicting a list might be supplied as the visual. The \fIXmDragContext\fP resources, \fIXmNsourceCursorIcon\fP or \fIXmNsourcePixmapIcon\fP, specify a DragIcon to use for the static portion of the visual. .PP A drag-over visual incorporates dynamic cues in order to provide visual feedback in response to the user's actions. For instance, the drag-over visual might use different indicators to identify the type of operation (copy, link, or move) being performed. Dynamic cues could also alert the user that a drop site is valid or invalid as the pointer traverses the drop site. The \fIXmNoperationCursorIcon\fP and \fIXmNstateCursorIcon\fP resources of \fIXmDragContext\fP specify DragIcons for dynamic cues. .PP A drag-over visual typically consists of a source, operation and state DragIcon. The \fIXmNblendModel\fP resource of \fIXmDragContext\fP offers several options that determine which icons are blended to produce the drag-over visual. DragIcon resources control the relative position of the operation and state icons (if used). If a particular DragIcon is not specified, the toolkit uses the \fIXmScreen\fP default DragIcons. .PP An application initializes a DragIcon with the function \fIXmCreateDragIcon\fP or through entries in the resource database. If a pixmap and its mask (optional) are specified in the resource database, the toolkit converts the values in the X11 Bitmap file format and assigns values to the corresponding resources. .SS "Classes" DragIcon inherits behavior and a resource from \fIObject\fP. .PP The class pointer is \fIxmDragIconObjectClass\fP. .PP The class name is \fIXmDragIcon\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (\fIC\fP), set by using \fIXtSetValues\fP (\fIS\fP), retrieved by using \fIXtGetValues\fP (\fIG\fP), or is not applicable (\fIN/A\fP). .PP .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmDragIcon Resource Set Name Class Type Default Access _ XmNattachment XmCAttachment unsigned char XmATTACH_NORTH_WEST CSG XmNdepth XmCDepth int 1 CSG XmNheight XmCHeight Dimension 0 CSG XmNhotX XmCHot Position 0 CSG XmNhotY XmCHot Position 0 CSG XmNmask XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNoffsetX XmCOffset Position 0 CSG XmNoffsetY XmCOffset Position 0 CSG XmNpixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNwidth XmCWidth Dimension 0 CSG .TE .KE .in .sp 1 .PP .IP "\fIXmNattachment\fP" Specifies a relative location on the source icon for the attachment of the state or operation icon. The origin of the state and operation icons is aligned with the specified compass point on the source icon. The \fIXmNoffsetX\fP and \fIXmNoffsetY\fP resources can be used to further refine the icon positions. The possible values are .IP "\fIXmATTACH_NORTH_WEST\fP" Attaches the origin of the state or operation icon to the northwest point on the source icon. .IP "\fIXmATTACH_NORTH\fP" Attaches the origin of the state or operation icon to the north point on the source icon. .IP "\fIXmATTACH_NORTH_EAST\fP" Attaches the origin of the state or operation icon to the northeast point on the source icon. .IP "\fIXmATTACH_EAST\fP" Attaches the origin of the state or operation icon to the east point on the source icon. .IP "\fIXmATTACH_SOUTH_EAST\fP" Attaches the origin of the state or operation icon to the southeast point on the source icon. .IP "\fIXmATTACH_SOUTH\fP" Attaches the origin of the state or operation icon to the south point on the source icon. .IP "\fIXmATTACH_SOUTH_WEST\fP" Attaches the origin of the state or operation icon to the southwest point on the source icon. .IP "\fIXmATTACH_WEST\fP" Attaches the origin of the state or operation icon to the west point on the source icon. .IP "\fIXmATTACH_CENTER\fP" Attaches the origin of the state or operation icon to the center of the source icon. The \fIXmNoffsetX\fP and \fIXmNoffsetY\fP resources may be used to center the attached icon. .IP "\fIXmATTACH_HOT\fP" Attaches the hotspot coordinates of a state or operation DragIcon to an \fBx,y\fP position on the source icon. The \fBx,y\fP coordinate is taken from the event passed to the \fIXmDragStart\fP function, and made relative to the widget passed as an argument to the same function. .IP "\fIXmNdepth\fP" Specifies the depth of the pixmap. .IP "\fIXmNheight\fP" Specifies the height of the pixmap. .IP "\fIXmNhotX\fP" Specifies the x-coordinate of the hotspot of a cursor DragIcon in relation to the origin of the pixmap bounding box. .IP "\fIXmNhotY\fP" Specifies the y-coordinate of the hotspot of a cursor DragIcon in relation to the origin of the pixmap bounding box. .IP "\fIXmNmask\fP" Specifies a pixmap of depth one to use as the DragIcon mask pixmap. .IP "\fIXmNoffsetX\fP" Specifies a horizontal offset (in pixels) of the origin of the state or operation icon relative to the attachment point on the source icon. A positive offset value moves the origin to the right; a negative value moves the origin to the left. .IP "\fIXmNoffsetY\fP" Specifies a vertical offset (in pixels) of the origin of the state or operation icon relative to the attachment point on the source icon. A positive offset value moves the origin down; a negative value moves the origin up. .IP "\fIXmNpixmap\fP" Specifies a pixmap to use as the DragIcon pixmap. .IP "\fIXmNwidth\fP" Specifies the width of the pixmap. .SS "Inherited Resources" DragIcon inherits behavior and a resource from \fIObject\fP. For a complete description of this resource, refer to the \fIObject\fP man page. .PP .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Object Resource Set Name Class Type Default Access _ XmNdestroyCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .PP .SH "RELATED INFORMATION" .na \fIObject(3X)\fP, \fIXmCreateDragIcon(3X)\fP, \fIXmDisplay(3X)\fP, \fIXmDragContext(3X)\fP, \fIXmDropSite(3X)\fP, \fIXmDropTransfer(3X)\fP, and \fIXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDragStart 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDragStart\fP \- A Drag and Drop function that initiates a drag and drop transaction .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmDragStart (\fBwidget, event, arglist, argcount\fI) .ta .5i 2i .nf Widget \fBwidget\fI; XEvent *\fBevent\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .iE .sE .SH DESCRIPTION .fi \fIXmDragStart\fP initiates a drag operation. This routine returns the DragContext widget that it initializes for the associated drag transaction. The toolkit is responsible for freeing the DragContext when the drag and drop transaction is complete. .IP "\fBwidget\fP" Specifies the ID of the smallest widget and/or gadget that encloses the source elements selected for a drag operation. .IP "\fBevent\fP" Specifies the \fIXEvent\fP that triggered the drag operation. This event must be a ButtonPress event. .IP "\fBarglist\fP" Specifies the argument list. Any \fIXmDragContext\fP resources not specified in the argument list are obtained from the resource database or are set to their default values. .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of DragContext and its associated resources, see \fIXmDragContext(3X)\fP. .SH RETURN VALUE Returns the ID of the DragContext widget that controls this drag and drop transaction. .SH RELATED INFORMATION .na \fIXmDragCancel(3X)\fP and \fIXmDragContext(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmDrawingArea 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDrawingArea\fP \- The DrawingArea widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi DrawingArea is an empty widget that is easily adaptable to a variety of purposes. It does no drawing and defines no behavior except for invoking callbacks. Callbacks notify the application when graphics need to be drawn (exposure events or widget resize) and when the widget receives input from the keyboard or mouse. .PP Applications are responsible for defining appearance and behavior as needed in response to DrawingArea callbacks. .PP DrawingArea is also a composite widget and subclass of \fIXmManager\fP that supports minimal geometry management for multiple widget or gadget children. .SS "Classes" DrawingArea inherits behavior and resources from the \fICore\fP, \fIComposite\fP, \fIConstraint\fP, and \fIXmManager\fP classes. .PP .ne 3 The class pointer is \fIxmDrawingAreaWidgetClass\fP. .PP The class name is \fIXmDrawingArea\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmDrawingArea Resource Set Name Class Type Default Access _ XmNexposeCallback XmCCallback XtCallbackList NULL C XmNinputCallback XmCCallback XtCallbackList NULL C XmNmarginHeight XmCMarginHeight Dimension 10 CSG XmNmarginWidth XmCMarginWidth Dimension 10 CSG XmNresizeCallback XmCCallback XtCallbackList NULL C XmNresizePolicy XmCResizePolicy unsigned char XmRESIZE_ANY CSG .TE .KE .in .sp 1 .nL .ne 8 .IP "\fIXmNexposeCallback\fP" Specifies the list of callbacks that is called when DrawingArea receives an exposure event. The callback reason is \fIXmCR_EXPOSE\fP. The callback structure also includes the exposure event. .PP The default bit gravity for Manager windows is \fINorthWestGravity\fP. This may cause the \fIXmNexposeCallback\fP procedures not to be invoked when the DrawingArea window is made smaller. .IP "\fIXmNinputCallback\fP" Specifies the list of callbacks that is called when the DrawingArea receives a keyboard or mouse event (key or button, up or down). The callback reason is \fIXmCR_INPUT\fP. The callback structure also includes the input event. .IP "\fIXmNmarginHeight\fP" Specifies the minimum spacing in pixels between the top or bottom edge of DrawingArea and any child widget. .IP "\fIXmNmarginWidth\fP" Specifies the minimum spacing in pixels between the left or right edge of DrawingArea and any child widget. .IP "\fIXmNresizeCallback\fP" Specifies the list of callbacks that is called when the DrawingArea is resized. The callback reason is \fIXmCR_RESIZE\fP. .IP "\fIXmNresizePolicy\fP" Controls the policy for resizing DrawingArea widgets. Possible values include \fIXmRESIZE_NONE\fP (fixed size), \fIXmRESIZE_ANY\fP (shrink or grow as needed), and \fIXmRESIZE_GROW\fP (grow only). .SS "Inherited Resources" DrawingArea inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmManager Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget NULL CSG XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension 0 CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.1i .nf typedef struct { int \fBreason\fI; XEvent \fB* event\fI; Window \fBwindow\fI; } XmDrawingAreaCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. This is NULL for the \fIXmNresizeCallback\fP. .IP "\fBwindow\fP" Is set to the widget window .nL .ne 10 .SS "Translations" XmDrawingArea inherits translations from XmManager. Before calling the XmManager actions, all events in the inherited translations except \fI\fP, \fI\fP, \fI\fP, \fI\fP, and \fI\fP also call the \fIDrawingAreaInput()\fP action. .PP XmDrawingArea has the additional translations listed below. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf MAny BAny Press: DrawingAreaInput() MAny BAny Release: DrawingAreaInput() .sp \n(PDu MAny KAny Press: DrawingAreaInput() ManagerGadgetKeyInput() MAny KAny Release: DrawingAreaInput() .wH .fi .iE .SS "Action Routines" The XmDrawingArea action routines are described below: .IP "\fIDrawingAreaInput()\fP:" Unless the event takes place in a gadget, calls the callbacks for \fIXmNinputCallback\fP. .IP "\fIManagerGadgetKeyInput()\fP:" Causes the current gadget to process a keyboard event. .nL .ne 10 .SS "Additional Behavior" The XmDrawingArea widget has the additional behavior described below: .IP "\fI\fP:" Calls the callbacks for \fIXmNexposeCallback\fP. .IP "\fI\fP:" Calls the callbacks for \fIXmNresizeCallback\fP. .P .P .ne 2i .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fIConstraint(3X)\fP, \fICore(3X)\fP, \fIXmCreateDrawingArea(3X)\fP, and \fIXmManager(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmDrawnButton 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDrawnButton\fP \- The DrawnButton widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi The DrawnButton widget consists of an empty widget window surrounded by a shadow border. It provides the application developer with a graphics area that can have PushButton input semantics. .PP Callback types are defined for widget exposure and widget resize to allow the application to redraw or reposition its graphics. If the DrawnButton widget has a highlight and shadow thickness, the application should not draw in that area. To avoid drawing in the highlight and shadow area, create the graphics context with a clipping rectangle for drawing in the widget. The clipping rectangle should take into account the size of the widget's highlight thickness and shadow. .SS "Classes" DrawnButton inherits behavior and resources from \fICore\fP, \fIXmPrimitive\fP, and \fIXmLabel\fP Classes. .PP The class pointer is \fIxmDrawnButtonWidgetClass\fP. .PP The class name is \fIXmDrawnButton\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmDrawnButton Resource Set Name Class Type Default Access _ XmNactivateCallback XmCCallback XtCallbackList NULL C XmNarmCallback XmCCallback XtCallbackList NULL C XmNdisarmCallback XmCCallback XtCallbackList NULL C XmNexposeCallback XmCCallback XtCallbackList NULL C XmNmultiClick XmCMultiClick unsigned char dynamic CSG XmNpushButtonEnabled XmCPushButtonEnabled Boolean False CSG XmNresizeCallback XmCCallback XtCallbackList NULL C XmNshadowType XmCShadowType unsigned char XmSHADOW_ETCHED_IN CSG .TE .KE .in .sp 1 .IP "\fIXmNactivateCallback\fP" Specifies the list of callbacks that is called when the widget becomes selected. The reason sent by the callback is \fIXmCR_ACTIVATE\fP. .IP "\fIXmNarmCallback\fP" Specifies the list of callbacks that is called when the widget becomes armed. The reason sent by the callback is \fIXmCR_ARM\fP. .IP "\fIXmNdisarmCallback\fP" Specifies the list of callbacks that is called when the widget becomes disarmed. The reason sent by the callback is \fIXmCR_DISARM\fP. .nL .ne 6 .IP "\fIXmNexposeCallback\fP" Specifies the list of callbacks that is called when the widget receives an exposure event. The reason sent by the callback is \fIXmCR_EXPOSE\fP. .IP "\fIXmNmultiClick\fP" If a button click is followed by another button click within the time span specified by the display's multi-click time, and this resource is set to \fIXmMULTICLICK_DISCARD\fP, do not process the second click. If this resource is set to \fIXmMULTICLICK_KEEP\fP, process the event and increment \fBclick_count\fP in the callback structure. When the button is not in a menu, the default value is \fIXmMULTICLICK_KEEP\fP. .IP "\fIXmNpushButtonEnabled\fP" Enables or disables the three-dimensional shadow drawing as in PushButton. .IP "\fIXmNresizeCallback\fP" Specifies the list of callbacks that is called when the widget receives a resize event. The reason sent by the callback is \fIXmCR_RESIZE\fP. The event returned for this callback is NULL. .IP "\fIXmNshadowType\fP" Describes the drawing style for the DrawnButton. This resource can have the following values: .wH .rS .TP \(bu \fIXmSHADOW_IN\fP \- draws the DrawnButton so that the shadow appears inset. This means that the bottom shadow visuals and top shadow visuals are reversed. .TP \(bu \fIXmSHADOW_OUT\fP \- draws the DrawnButton so that the shadow appears outset. .nL .ne 30 .TP \(bu \fIXmSHADOW_ETCHED_IN\fP \- draws the DrawnButton using a double line. This gives the effect of a line etched into the window. The thickness of the double line is equal to the value of \fIXmNshadowThickness\fP. .TP \(bu \fIXmSHADOW_ETCHED_OUT\fP \- draws the DrawnButton using a double line. This gives the effect of a line coming out of the window. The thickness of the double line is equal to the value of \fIXmNshadowThickness\fP. .wH .rE .SS "Inherited Resources" DrawnButton inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmLabel Resource Set Name Class Type Default Access _ XmNaccelerator XmCAccelerator String NULL N/A XmNacceleratorText XmCAcceleratorText XmString NULL N/A XmNalignment XmCAlignment unsigned char dynamic CSG XmNfontList XmCFontList XmFontList dynamic CSG XmNlabelInsensitivePixmap XmCLabelInsensitivePixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelPixmap XmCLabelPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelString XmCXmString XmString "\e0" CSG XmNlabelType XmCLabelType unsigned char XmSTRING CSG XmNmarginBottom XmCMarginBottom Dimension 0 CSG XmNmarginHeight XmCMarginHeight Dimension 2 CSG XmNmarginLeft XmCMarginLeft Dimension 0 CSG XmNmarginRight XmCMarginRight Dimension 0 CSG XmNmarginTop XmCMarginTop Dimension 0 CSG XmNmarginWidth XmCMarginWidth Dimension 2 CSG .wH .tH XmNmnemonic XmCMnemonic KeySym NULL N/A XmNmnemonicCharSet XmCMnemonicCharSet String XmFONTLIST_DEFAULT_TAG N/A XmNrecomputeSize XmCRecomputeSize Boolean True CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CSG .TE .KE .in .sp 1 .wH .in .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPrimitive Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG .wH .tH XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.1i .nf typedef struct { int \fBreason\fI; XEvent \fB* event\fI; Window \fBwindow\fI; int \fBclick_count\fI; } XmDrawnButtonCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. This is NULL for \fIXmNresizeCallback\fP. .nL .ne 15 .IP "\fBwindow\fP" Is set to the window ID in which the event occurred. .IP "\fBclick_count\fP" Contains the number of clicks in the last multiclick sequence if the \fIXmNmultiClick\fP resource is set to \fIXmMULTICLICK_KEEP\fP, otherwise it contains \fI1\fP. The activate callback is invoked for each click if \fIXmNmultiClick\fP is set to \fIXmMULTICLICK_KEEP\fP. .SS "Translations" XmDrawnButton includes translations from Primitive. Additional XmDrawnButton translations are listed below. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BSelect Press: Arm() BSelect Click: Activate() Disarm() BSelect Release: Activate() Disarm() BSelect Press 2+: MultiArm() BSelect Release 2+: MultiActivate() KSelect: ArmAndActivate() KHelp: Help() .wH .fi .iE .nL .ne 30 .SS "Action Routines" The XmDrawnButton action routines are described below: .IP "\fIActivate()\fP:" If \fIXmNpushButtonEnabled\fP is True, redraws the shadow in the unselected state; otherwise, redraws the shadow according to \fIXmNshadowType\fP. ...\"Calls the \fIXmNexposeCallback\fP callbacks, then redraws the label. If the pointer is within the DrawnButton, calls the \fIXmNactivateCallback\fP callbacks. .IP "\fIArm()\fP:" If \fIXmNpushButtonEnabled\fP is True, redraws the shadow in the selected state; otherwise, redraws the shadow according to \fIXmNshadowType\fP. ...\"Calls the \fIXmNexposeCallback\fP callbacks, then redraws the label. Calls the callbacks for \fIXmNarmCallback\fP. .IP "\fIArmAndActivate()\fP:" If \fIXmNpushButtonEnabled\fP is True, redraws the shadow in the selected state; otherwise, redraws the shadow according to \fIXmNshadowType\fP. ...\"Calls the \fIXmNexposeCallback\fP callbacks, then redraws the label. Calls the callbacks for \fIXmNarmCallback\fP. .P Arranges for the following to happen, either immediately or at a later time: If \fIXmNpushButtonEnabled\fP is True, the shadow is redrawn in the unselected state; otherwise, the shadow is redrawn according to \fIXmNshadowType\fP. ...\"Calls the \fIXmNexposeCallback\fP callbacks, then redraws the label. The callbacks for \fIXmNactivateCallback\fP and \fIXmNdisarmCallback\fP are called. .IP "\fIDisarm()\fP:" Marks the DrawnButton as unselected and calls the callbacks for \fIXmNdisarmCallback\fP. .IP "\fIHelp()\fP:" Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIMultiActivate()\fP:" If \fIXmNmultiClick\fP is \fIXmMULTICLICK_DISCARD\fP, this action does nothing. .P If \fIXmNmultiClick\fP is \fIXmMULTICLICK_KEEP\fP, this action does the following: Increments \fBclick_count\fP in the callback structure. If \fIXmNpushButtonEnabled\fP is True, redraws the shadow in the unselected state; otherwise, redraws the shadow according to \fIXmNshadowType\fP. ...\"Calls the \fIXmNexposeCallback\fP callbacks, then redraws the label. If the pointer is within the DrawnButton, calls the \fIXmNactivateCallback\fP callbacks. Calls the callbacks for \fIXmNdisarmCallback\fP. .nL .ne 30 .IP "\fIMultiArm()\fP:" If \fIXmNmultiClick\fP is \fIXmMULTICLICK_DISCARD\fP, this action does nothing. .P If \fIXmNmultiClick\fP is \fIXmMULTICLICK_KEEP\fP, this action does the following: If \fIXmNpushButtonEnabled\fP is True, redraws the shadow in the selected state; otherwise, redraws the shadow according to \fIXmNshadowType\fP. ...\"Calls the \fIXmNexposeCallback\fP callbacks, then redraws the label. Calls the callbacks for \fIXmNarmCallback\fP. .SS "Additional Behavior" This widget has the additional behavior described below: .IP "\fI\fP:" Draws the shadow in its selected state if \fIXmNpushButtonEnabled\fP is True and if the cursor leaves and re-enters the window while \fIBSelect\fP is pressed. .IP "\fI\fP:" Draws the shadow in its unselected state if \fIXmNpushButtonEnabled\fP is True and if the cursor leaves the window while \fIBSelect\fP is pressed. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fICore(3X)\fP, \fIXmCreateDrawnButton\fP, \fIXmLabel(3X)\fP, \fIXmPrimitive(3X)\fP, \fIXmPushButton\fP, and \fIXmSeparator(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1991, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1991 by Hewlett-Packard Company ...\" ** ...\" ** .TH XmDropSite 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDropSite\fP \- The DropSite Registry .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi A client registers a widget or gadget as a drop site using the \fIXmDropSiteRegister\fP function. In addition, this routine defines the behavior and capabilities of a drop site by specifying appropriate resources. For example, the \fIXmNimportTargets\fP and \fIXmNnumImportTargets\fP resources identify respectively the selection target types and number of types supported by a drop site. The visual animation effects associated with a drop site are also described with DropSite resources. .PP Drop site animation effects that occur in response to the pointer entering a valid drop site are called drag-under effects. A receiver can select from several animation styles supplied by the toolkit or can provide customized animation effects. Drag-under effects supplied by the toolkit include border highlighting, shadow in/out drawing, and pixmap representation. .PP When a preregister drag protocol style is used, the toolkit generates drag-under visual effects based on the value of the \fIXmNanimationStyle\fP resource. In dynamic mode, if the drop site \fIXmNdragProc\fP resource is NULL, the toolkit also provides animation effects based on the \fIXmNanimationStyle\fP resource. Otherwise, if the \fIXmNdragProc\fP routine is specified, the receiver can either assume responsibility for animation effects (through the \fIXmNdragProc\fP routine) or rely on the toolkit to provide animation. .PP Drop sites may overlap. The initial stacking order corresponds to the order in which the drop sites were registered. When a drop site overlaps another drop site, the drag-under effects of the drop site underneath are clipped by the obscuring drop site(s). .PP The \fIXmDropSiteUpdate\fP routine sets resources for a widget that is registered as a drop site. \fIXmDropSiteRetrieve\fP gets drop site resource values previously specified for a registered widget. These routines are used instead of \fIXtSetValues\fP and \fIXtGetValues\fP. .SS "Classes" XmDropSite does not inherit from any widget class. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (\fIC\fP), set by using \fIXmDropSiteUpdate\fP (\fIS\fP), retrieved by using \fIXmDropSiteRetrieve\fP (\fIG\fP), or is not applicable (\fIN/A\fP). .PP .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmDropSite Resource Set Name Class Type Default Access _ XmNanimationMask XmCAnimationMask Pixmap XmUNSPECIFIED_PIXMAP CSG XmNanimationPixmap XmCAnimationPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNanimationPixmapDepth XmCAnimationPixmapDepth int 0 CSG XmNanimationStyle XmCAnimationStyle unsigned char XmDRAG_UNDER_HIGHLIGHT CSG XmNdragProc XmCDragProc XtCallbackProc NULL CSG XmNdropProc XmCDropProc XtCallbackProc NULL CSG XmNdropRectangles XmCDropRectangles XRectangle * dynamic CSG XmNdropSiteActivity XmCDropSiteActivity unsigned char XmDROP_SITE_ACTIVE CSG XmNdropSiteOperations XmCDropSiteOperations unsigned char XmDROP_MOVE | XmDROP_COPY CSG XmNdropSiteType XmCDropSiteType unsigned char XmDROP_SITE_SIMPLE CG XmNimportTargets XmCImportTargets Atom * NULL CSG XmNnumDropRectangles XmCNumDropRectangles Cardinal 1 CSG XmNnumImportTargets XmCNumImportTargets Cardinal 0 CSG .TE .KE .in .sp 1 .PP .IP "\fIXmNanimationMask\fP" Specifies a mask to use with the pixmap specified by \fIXmNanimationPixmap\fP when the animation style is \fIXmDRAG_UNDER_PIXMAP\fP. .IP "\fIXmNanimationPixmap\fP" Specifies a pixmap for drag-under animation when the animation style is \fIXmDRAG_UNDER_PIXMAP\fP. The pixmap is drawn with its origin at the upper left corner of the bounding box of the drop site. If the drop site window is larger than the animation pixmap, the portion of the window not covered by the pixmap will be tiled with the window's background color. .IP "\fIXmNanimationPixmapDepth\fP" Specifies the depth of the pixmap specified by the \fIXmNanimationPixmap\fP resource. When the depth is 1, the colors are taken from the foreground and background of the drop site widget. For any other value, drop site animation occurs only if the \fIXmNanimationPixmapDepth\fP matches the depth of the drop site window. Colors are derived from the current colormap. .IP "\fIXmNanimationStyle\fP" Specifies the drag-under animation style used when a drag enters a valid drop site. The possible values are .IP "\fIXmDRAG_UNDER_HIGHLIGHT\fP" The drop site uses highlighting effects. .IP "\fIXmDRAG_UNDER_SHADOW_OUT\fP" The drop site uses an outset shadow. .IP "\fIXmDRAG_UNDER_SHADOW_IN\fP" The drop site uses an inset shadow. .IP "\fIXmDRAG_UNDER_PIXMAP\fP" The drop site uses the pixmap specified by \fIXmNanimationPixmap\fP to indicate that it can receive the drop. .IP "\fIXmDRAG_UNDER_NONE\fP" The drop site does not use animation effects. A client using a dynamic protocol, may provide drag-under effects in its \fIXmNdragProc\fP routine. .IP "\fIXmNdragProc\fP" Specifies the procedure that is invoked when the drop site receives a crossing, motion, or operation changed message. This procedure is called only when a dynamic protocol is used. The type of structure whose address is passed to this procedure is \fIXmDragProcCallbackStruct\fP. The reason sent to the procedure is one of the following: .IP "\fIXmCR_DROP_SITE_ENTER_MESSAGE\fP" .IP "\fIXmCR_DROP_SITE_LEAVE_MESSAGE\fP" .IP "\fIXmCR_DRAG_MOTION_MESSAGE\fP" .IP "\fIXmCR_OPERATION_CHANGED_MESSAGE\fP" .PP The drag procedure may change the values of some members of the \fIXmDragProcCallbackStruct\fP passed to it. After the drag procedure returns, the toolkit uses the final values in initializing some members of the callback struct passed to the appropriate callbacks of the initiator (the DragContext's \fIXmNdropSiteEnterCallback\fP, \fIXmNdropSiteLeaveCallback\fP, \fIXmNdragMotionCallback\fP, or \fIXmNoperationChangedCallback\fP callbacks). .IP "\fIXmNdropProc\fP" Specifies the procedure that is invoked when a drop (excluding a cancel or interrupt action) occurs on a drop site regardless of the status of the drop site. The type of the structure whose address is passed to this procedure is \fIXmDropProcCallbackStruct\fP. The reason sent to the procedure is \fIXmCR_DROP_MESSAGE\fP. .PP The drop procedure may change the values of some members of the \fIXmDropProcCallbackStruct\fP passed to it. After the drop procedure returns, the toolkit uses the final values in initializing some members of the \fIXmDropStartCallbackStruct\fP passed to the initiator's drop start callbacks (the DragContext's \fIXmNdropStartCallback\fP callbacks). .IP "\fIXmNdropRectangles\fP" Specifies a list of rectangles that describe the shape of a drop site. The locations of the rectangles are relative to the origin of the enclosing object. When \fIXmNdropRectangles\fP is NULL, the drop site is assumed to be the sensitive area of the enclosing widget. If \fIXmNdropSiteType\fP is \fIXmDROP_SITE_COMPOSITE\fP, this resource cannot be specified by the application. .IP "\fIXmNdropSiteActivity\fP" Indicates whether a drop site is active or inactive. The values are \fIXmDROP_SITE_ACTIVE\fP and \fIXmDROP_SITE_INACTIVE\fP. An active drop site can receive a drop, whereas an inactive drop site is dormant. An inactive drop site is treated as if it was not a registered drop site and any drag-under visuals associated with entering or leaving the drop site do not occur. However, it is still used for clipping drag-under effects. .IP "\fIXmNdropSiteOperations\fP" Specifies the set of valid operations associated with a drop site. This resource is a bit mask that is formed by combining one or more of the following values using a bitwise operation such as inclusive OR (|): \fIXmDROP_COPY\fP, \fIXmDROP_LINK\fP, and \fIXmDROP_MOVE\fP. The value \fIXmDROP_NOOP\fP for this resource indicates that no operations are valid. .IP "\fIXmNdropSiteType\fP" Specifies the type of the drop site. The possible values are .IP "\fIXmDROP_SITE_SIMPLE\fP" The widget does not have any additional children that are registered as drop sites. .IP "\fIXmDROP_SITE_COMPOSITE\fP" The widget will have children that are registered as drop sites. .IP "\fIXmNimportTargets\fP" Specifies the list of target atoms that this drop site accepts. .IP "\fIXmNnumDropRectangles\fP" Specifies the number of rectangles in the \fIXmNdropRectangles\fP list. If the drop site type is \fIXmDROP_SITE_COMPOSITE\fP, this resource can not be specified by the application. .IP "\fIXmNnumImportTargets\fP" Specifies the number of atoms in the target atom list. .SS "Callback Information" A pointer to the following structure is passed to the \fIXmNdragProc\fP routine when the drop site receives crossing, motion, or operation changed messages. .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent *\fBevent\fI; Time \fBtimeStamp\fI; Widget \fBdragContext\fI; Position \fBx\fI; Position \fBy\fI; unsigned char \fBdropSiteStatus\fI; unsigned char \fBoperation\fI; unsigned char \fBoperations\fI; Boolean \fBanimate\fI; } XmDragProcCallbackStruct, *XmDragProcCallback; .iE .sE .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBtimeStamp\fP" Specifies the timestamp of the logical event. .IP "\fBdragContext\fP" Specifies the ID of the DragContext widget associated with the transaction. .IP "\fBx\fP" Indicates the x-coordinate of the pointer relative to the drop site. .IP "\fBy\fP" Indicates the y-coordinate of the pointer relative to the drop site. .IP "\fBdropSiteStatus\fP" An IN/OUT member that indicates whether or not a drop site is valid. .PP When the \fBreason\fP is \fIXmCR_DROP_SITE_ENTER_MESSAGE\fP or \fIXmCR_OPERATION_CHANGED_MESSAGE\fP, or when the reason is \fIXmCR_DRAG_MOTION_MESSAGE\fP or \fIXmCR_DROP_SITE_LEAVE_MESSAGE\fP and the pointer is not in the same drop site as on the previous invocation of the drag procedure, the toolkit initializes \fBdropSiteStatus\fP as follows: the toolkit initializes \fBdropSiteStatus\fP to \fIXmDROP_SITE_VALID\fP if the DragContext's \fIXmNexportTargets\fP and the DropSite's \fIXmNimportTargets\fP are compatible and if the initial value of the \fBoperation\fP member is not \fIXmDROP_NOOP\fP. Otherwise, the toolkit initializes \fBdropSiteStatus\fP to \fIXmDROP_SITE_INVALID\fP. .PP When the \fBreason\fP is \fIXmCR_DRAG_MOTION_MESSAGE\fP or \fIXmCR_DROP_SITE_LEAVE_MESSAGE\fP and the pointer is within the same drop site as on the previous invocation of the drag procedure, the toolkit initializes \fBdropSiteStatus\fP to the value of \fBdropSiteStatus\fP at the time the previous invocation of the drag procedure returns. .PP The drag procedure may change the value of this member. After the drag procedure returns, the toolkit uses the final value in initializing the \fBdropSiteStatus\fP member of the callback struct passed to the appropriate callbacks of the initiator. .IP "\fBoperation\fP" An IN/OUT member that identifies an operation. .PP The toolkit initializes \fBoperation\fP by selecting an operation from the bitwise AND of the initial value of the \fBoperations\fP member and the value of the DropSite's \fIXmNdropSiteOperations\fP resource. The toolkit searches this set first for \fIXmDROP_MOVE\fP, then for \fIXmDROP_COPY\fP, then for \fIXmDROP_LINK\fP, and initializes \fBoperation\fP to the first operation it finds in the set. If the toolkit finds none of these operations in the set, it initializes \fBoperation\fP to \fIXmDROP_NOOP\fP. .PP The drag procedure may change the value of this member. After the drag procedure returns, the toolkit uses the final value in initializing the \fBoperation\fP member of the callback struct passed to the appropriate callbacks of the initiator. .IP "\fBoperations\fP" An IN/OUT member that indicates the set of operations supported for the source data. .PP If the user does not select an operation (by pressing a modifier key), the toolkit initializes \fBoperations\fP to the value of the DragContext's \fIXmNdragOperations\fP resource. If the user does select an operation, the toolkit initializes \fBoperations\fP to the bitwise AND of the corresponding operation and the value of the DragContext's \fIXmNdragOperations\fP resource. If the resulting set of operations is empty, the toolkit initializes \fBoperations\fP to \fIXmDROP_NOOP\fP. .PP The drag procedure may change the value of this member. After the drag procedure returns, the toolkit uses the final value in initializing the \fBoperations\fP member of the callback struct passed to the appropriate callbacks of the initiator. .IP "\fBanimate\fP" An OUT member that indicates whether the toolkit or the receiver client provides drag-under effects for a valid drop site. If \fBanimate\fP is set to True, the toolkit provides drop site animation per the \fIXmNanimationStyle\fP resource value; if it is set to False, the receiver generates drag-under animation effects. .PP A pointer to the following structure is passed to the \fIXmNdropProc\fP routine when the drop site receives a drop message: .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent *\fBevent\fI; Time \fBtimeStamp\fI; Widget \fBdragContext\fI; Position \fBx\fI; Position \fBy\fI; unsigned char \fBdropSiteStatus\fI; unsigned char \fBoperation\fI; unsigned char \fBoperations\fI; unsigned char \fBdropAction\fI; } XmDropProcCallbackStruct, *XmDropProcCallback; .iE .sE .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Specifies the \fIXEvent\fP that triggered the callback. .IP "\fBtimeStamp\fP" Specifies the timestamp of the logical event. .IP "\fBdragContext\fP" Specifies the ID of the DragContext widget associated with the transaction. .IP "\fBx\fP" Indicates the x-coordinate of the pointer relative to the drop site. .IP "\fBy\fP" Indicates the y-coordinate of the pointer relative to the drop site. .IP "\fBdropSiteStatus\fP" An IN/OUT member that indicates whether or not a drop site is valid. .PP The toolkit initializes \fBdropSiteStatus\fP to \fIXmDROP_SITE_VALID\fP if the DragContext's \fIXmNexportTargets\fP and the DropSite's \fIXmNimportTargets\fP are compatible and if the initial value of the \fBoperation\fP member is not \fIXmDROP_NOOP\fP. Otherwise, the toolkit initializes \fBdropSiteStatus\fP to \fIXmDROP_SITE_INVALID\fP. .PP The drop procedure may change the value of this member. After the drop procedure returns, the toolkit uses the final value in initializing the \fBdropSiteStatus\fP member of the \fIXmDropStartCallbackStruct\fP passed to the initiator's drop start callbacks (the DragContext's \fIXmNdropStartCallback\fP callbacks). .IP "\fBoperation\fP" An IN/OUT member that identifies an operation. .PP The toolkit initializes \fBoperation\fP by selecting an operation from the bitwise AND of the initial value of the \fBoperations\fP member and the value of the DropSite's \fIXmNdropSiteOperations\fP resource. The toolkit searches this set first for \fIXmDROP_MOVE\fP, then for \fIXmDROP_COPY\fP, then for \fIXmDROP_LINK\fP, and initializes \fBoperation\fP to the first operation it finds in the set. If it finds none of these operations in the set, it initializes \fBoperation\fP to \fIXmDROP_NOOP\fP. .PP The drop procedure may change the value of this member. After the drop procedure returns, the toolkit uses the final value in initializing the \fBoperation\fP member of the \fIXmDropStartCallbackStruct\fP passed to the initiator's drop start callbacks (the DragContext's \fIXmNdropStartCallback\fP callbacks). .IP "\fBoperations\fP" An IN/OUT member that indicates the set of operations supported for the source data. .PP If the user does not select an operation (by pressing a modifier key), the toolkit initializes \fBoperations\fP to the value of the DragContext's \fIXmNdragOperations\fP resource. If the user does select an operation, the toolkit initializes \fBoperations\fP to the bitwise AND of the corresponding operation and the value of the DragContext's \fIXmNdragOperations\fP resource. If the resulting set of operations is empty, the toolkit initializes \fBoperations\fP to \fIXmDROP_NOOP\fP. .PP The drop procedure may change the value of this member. After the drop procedure returns, the toolkit uses the final value in initializing the \fBoperations\fP member of the \fIXmDropStartCallbackStruct\fP passed to the initiator's drop start callbacks (the DragContext's \fIXmNdropStartCallback\fP callbacks). .IP "\fBdropAction\fP" An IN/OUT member that identifies the action associated with the drop. The possible values are .IP "\fIXmDROP\fP" A drop was attempted. If the drop site is valid, drop transfer handling proceeds. .IP "\fIXmDROP_HELP\fP" The user has requested help on the drop site. .PP The drop procedure may change the value of this member. After the drop procedure returns, the toolkit uses the final value in initializing the \fBdropAction\fP member of the \fIXmDropStartCallbackStruct\fP passed to the initiator's drop start callbacks (the DragContext's \fIXmNdropStartCallback\fP callbacks). .SH "RELATED INFORMATION" .na \fIXmDragContext(3X)\fP, \fIXmDragIcon(3X)\fP, \fIXmDropSiteConfigureStackingOrder(3X)\fP, \fIXmDropSiteEndUpdate(3X)\fP, \fIXmDropSiteQueryStackingOrder(3)\fP, \fIXmDropSiteRegister(3X)\fP, \fIXmDropSiteStartUpdate(3X)\fP, \fIXmDropSiteUpdate(3X)\fP, \fIXmDropSiteUnregister(3X)\fP, \fIXmDropTransfer(3X)\fP, and \fIXmTargetsAreCompatible(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDropSiteConfigureStackingOrder 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDropSiteConfigureStackingOrder\fP \- A Drag and Drop function that reorders a stack of widgets that are registered drop sites .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmDropSiteConfigureStackingOrder (\fBwidget, sibling, stack_mode\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; Widget \fBsibling\fI; Cardinal \fBstack_mode\fI; .iE .sE .SH DESCRIPTION .fi \fIXmDropSiteConfigureStackingOrder\fP changes the stacking order of the drop site specified by \fBwidget\fP. The stacking order controls the manner in which drag-under effects are clipped by overlapping siblings, regardless of whether they are active. The stack mode is relative either to the entire stack, or to another drop site within the stack. The stack order can be modified only if the drop sites are siblings in both the widget and drop site hierarchy, and the widget parent of the drop sites is registered as a composite drop site. .IP "\fBwidget\fP" Specifies the drop site to be restacked. .IP "\fBsibling\fP" Specifies a sibling drop site for stacking operations. If specified, then \fBwidget\fP is restacked relative to this drop site's stack position. .IP "\fBstack_mode\fP" Specifies the new stack position for the specified widget. The values are \fIXmABOVE\fP and \fIXmBELOW\fP. If a sibling is specified, then \fBwidget\fP is restacked as follows: .IP "\fIXmABOVE\fP" The widget is placed just above the sibling. .IP "\fIXmBELOW\fP" The widget is placed just below the sibling. If the \fBsibling\fP parameter is not specified, then \fBwidget\fP is restacked as follows: .IP "\fIXmABOVE\fP" The widget is placed at the top of the stack. .IP "\fIXmBELOW\fP" The widget is placed at the bottom of the stack. .PP .LE .PP For a complete definition of DropSite and its associated resources, see \fIXmDropSite(3X)\fP. .SH RELATED INFORMATION .na \fIXmDropSite(3X)\fP, \fIXmDropSiteRetrieve(3X)\fP, and \fIXmDropSiteQueryStackingOrder(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDropSiteEndUpdate 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDropSiteEndUpdate\fP \- A Drag and Drop function that facilitates processing updates to multiple drop sites .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmDropSiteEndUpdate (\fBwidget\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; .iE .sE .SH DESCRIPTION .fi \fIXmDropSiteEndUpdate\fP is used in conjunction with \fIXmDropSiteStartUpdate\fP to process updates to multiple drop sites within the same hierarchy. \fIXmDropSiteStartUpdate\fP and \fIXmDropSiteEndUpdate\fP signal the beginning and the end respectively of a series of calls to \fIXmDropSiteUpdate\fP. Calls to \fIXmDropSiteStartUpdate\fP and \fIXmDropSiteEndUpdate\fP can be recursively stacked. Using these routines optimizes the processing of update information. .IP "\fBwidget\fP" Specifies the ID of any widget within a given hierarchy. The function uses this widget to identify the shell that contains the drop sites. .PP For a complete definition of DropSite and its associated resources, see \fIXmDropSite(3X)\fP. .SH RELATED INFORMATION .na \fIXmDropSiteStartUpdate(3X)\fP and \fIXmDropSiteUpdate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDropSiteQueryStackingOrder 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDropSiteQueryStackingOrder\fP \- A Drag and Drop function that returns the parent, a list of children, and the number of children for a specified widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Status XmDropSiteQueryStackingOrder (\fBwidget, parent_return, child_returns, num_child_returns\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; Widget *\fBparent_return\fI; Widget **\fBchild_returns\fI; Cardinal *\fBnum_child_returns\fI; .iE .sE .SH DESCRIPTION .fi \fIXmDropSiteQueryStackingOrder\fP obtains the parent, a list of children registered as drop sites, and the number of children registered as drop sites for a given widget. The children are listed in current stacking order, from bottom-most (first child) to the top-most (last child). This function allocates memory for the returned data that must be freed by calling \fIXtFree\fP. .IP "\fBwidget\fP" Specifies the widget ID. For this widget, you obtain the list of its children, its parent, and the number of children. .IP "\fBparent_return\fP" Returns the widget ID of the drop site parent of the specified widget. .IP "\fBchild_returns\fP" Returns a pointer to the list of drop site children associated with the specified widget. .IP "\fBnum_child_returns\fP" Returns the number of drop site children for the specified widget. .PP For a complete definition of DropSite and its associated resources, see \fIXmDropSite(3X)\fP. .SH RETURN VALUE Returns zero if the routine fails; returns a nonzero value if it succeeds. .SH RELATED INFORMATION .na \fIXmDropSite(3X)\fP and \fIXmDropSiteConfigureStackingOrder(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDropSiteRegister 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDropSiteRegister\fP \- A Drag and Drop function that identifies a drop site and assigns resources that specify its behavior .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmDropSiteRegister (\fBwidget, arglist, argcount\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .iE .sE .SH DESCRIPTION .fi \fIXmDropSiteRegister\fP identifies the specified widget or gadget as a drop site and sets resource values that define the drop site's behavior. The routine assigns default values to any resources that are not specified in the argument list. The toolkit generates a warning message if a drop site is registered with \fIXmNdropSiteActivity\fP set to \fIXmDROP_SITE_ACTIVE\fP and the \fIXmNdropProc\fP resource is NULL. .PP If the drop site is a descendant of a widget that is registered as a drop site, the \fIXmNdropSiteType\fP resource of the ancestor drop site must be specified as \fIXmDROP_SITE_COMPOSITE\fP. The ancestor must be registered before the descendant. The drop site is stacked above all other sibling drop sites already registered. .IP "\fBwidget\fP" Specifies the ID of the widget to be registered. .IP "\fBarglist\fP" Specifies the argument list. .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP). .PP For a complete definition of DropSite and its associated resources, see \fIXmDropSite(3X)\fP. .SH RELATED INFORMATION .na \fIXmDisplay(3X)\fP, \fIXmDropSite(3X)\fP, \fIXmDropSiteEndUpdate(3X)\fP, \fIXmDropSiteStartUpdate(3X)\fP, \fIXmDropSiteUpdate(3X)\fP, \fIXmDropSiteUnregister(3X)\fP, and \fIXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDropSiteRetrieve 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDropSiteRetrieve\fP \- A Drag and Drop function that retrieves resource values set on a drop site .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmDropSiteRetrieve (\fBwidget, arglist, argcount\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .iE .sE .SH DESCRIPTION .fi \fIXmDropSiteRetrieve\fP extracts values for the given resources from the drop site specified by \fBwidget\fP. An initiator can also obtain information about the current drop site by passing the associated DragContext widget as the \fBwidget\fP parameter to this routine. The initiator can retrieve all of the drop site resources except \fIXmNdragProc\fP and \fIXmNdropProc\fP using this method. .IP "\fBwidget\fP" Specifies the ID of the widget that encloses the drop site. .IP "\fBarglist\fP" Specifies the argument list. .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP). .PP For a complete definition of DropSite and its associated resources, see \fIXmDropSite(3X)\fP. .SH RELATED INFORMATION .na \fIXmDropSite(3X)\fP and \fIXmDropSiteUpdate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDropSiteStartUpdate 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDropSiteStartUpdate\fP \- A Drag and Drop function that facilitates processing updates to multiple drop sites .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmDropSiteStartUpdate (\fBwidget\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; .iE .sE .SH DESCRIPTION .fi \fIXmDropSiteStartUpdate\fP is used in conjunction with \fIXmDropSiteEndUpdate\fP to process updates to multiple drop sites within the same shell widget. \fIXmDropSiteStartUpdate\fP and \fIXmDropSiteEndUpdate\fP signal the beginning and the end respectively of a series of calls to \fIXmDropSiteUpdate\fP. Calls to \fIXmDropSiteStartUpdate\fP and \fIXmDropSiteEndUpdate\fP can be recursively stacked. Using these routines optimizes the processing of update information. .IP "\fBwidget\fP" Specifies the ID of any widget within a given hierarchy. The function uses this widget to identify the shell that contains the drop sites. .PP For a complete definition of DropSite and its associated resources, see \fIXmDropSite(3X)\fP. .SH RELATED INFORMATION .na \fIXmDropSite(3X)\fP, \fIXmDropSiteEndUpdate(3X)\fP, and \fIXmDropSiteUpdate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDropSiteUnregister 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDropSiteUnregister\fP \- A Drag and Drop function that frees drop site information .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmDropSiteUnregister (\fBwidget\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; .iE .sE .SH DESCRIPTION .fi \fIXmDropSiteUnregister\fP informs the toolkit that the specified widget is no longer a registered drop site. The function frees all associated drop site information. .IP "\fBwidget\fP" Specifies the ID of the widget, registered as a drop site, that is to be unregistered .PP For a complete definition of DropSite and its associated resources, see \fIXmDropSite(3X)\fP. .SH RELATED INFORMATION .na \fIXmDropSite(3X)\fP and \fIXmDropSiteRegister(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDropSiteUpdate 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDropSiteUpdate\fP \- A Drag and Drop function that sets resource values for a drop site .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmDropSiteUpdate (\fBwidget, arglist, argcount\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .iE .sE .SH DESCRIPTION .fi \fIXmDropSiteUpdate\fP modifies drop site resources associated with the specified widget. This routine updates the drop site resources specified in the \fBarglist\fP. .IP "\fBwidget\fP" Specifies the ID of the widget registered as a drop site .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of DropSite and its associated resources, see \fIXmDropSite(3X)\fP. .SH RELATED INFORMATION .na \fIXmDropSite(3X)\fP, \fIXmDropSiteEndUpdate(3X)\fP, \fIXmDropSiteRegister(3X)\fP, \fIXmDropSiteStartUpdate(3X)\fP, and \fIXmDropSiteUnregister(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1991, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1991 by Hewlett-Packard Company ...\" ** ...\" ** .TH XmDropTransfer 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDropTransfer\fP \- The DropTransfer widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi DropTransfer provides a set of resources that identifies the procedures and associated information required by the toolkit in order to process and complete a drop transaction. Clients should not explicitly create a DropTransfer widget. Instead, a client initiates a transfer by calling \fIXmDropTransferStart\fP, which initializes and returns a DropTransfer widget. If this function is called within an \fIXmNdropProc\fP callback, the actual transfers are initiated after the callback returns. Even if no data needs to be transferred, \fIXmDropTransferStart\fP needs to be called (typically with no arguments, or just setting \fIXmNtransferStatus\fP) to finish the drag and drop transaction. .PP The \fIXmNdropTransfers\fP resource specifies a transfer list that describes the requested target types for the source data. A transfer list is an array of \fIXmDropTransferEntryRec\fP structures, each of which identifies a target type. The transfer list is analogous to the MULTIPLE selections capability defined in the \*EInter-Client Communication Conventions Manual\fP (ICCCM). .PP The DropTransfer resource, \fIXmNtransferProc\fP, specifies a transfer procedure of type XtSelectionCallbackProc that delivers the requested selection data. This procedure operates in conjunction with the underlying Xt selection capabilities and is called for each target in the transfer list. Additional target types can be requested after a transfer is initiated by calling the \fIXmDropTransferAdd\fP function. .SS "Structures" An \fIXmDropTransferEntry\fP is a pointer to the following structure of type \fIXmDropTransferEntryRec\fP, which identifies a selection target associated with a given drop transaction: .sS .iS .ta .25i 1.25i .nf typedef struct { XtPointer \fBclient_data\fI; Atom \fBtarget\fI; } XmDropTransferEntryRec, *XmDropTransferEntry; .iE .sE .PP .IP "\fBclient_data\fP Specifies any additional information required by this selection target .IP "\fBtarget\fP Specifies a selection target associated with the drop operation .SS "Classes" DropTransfer inherits behavior and a resource from \fIObject\fP. .PP The class pointer is \fIxmDropTransferObjectClass\fP. .PP The class name is \fIXmDropTransfer\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (\fIC\fP), set by using \fIXtSetValues\fP (\fIS\fP), retrieved by using \fIXtGetValues\fP (\fIG\fP), or is not applicable (\fIN/A\fP). .PP .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmDropTransfer Resource Set Name Class Type Default Access _ XmNdropTransfers XmCDropTransfers XmDropTransferEntryRec * NULL CG XmNincremental XmCIncremental Boolean False CSG XmNnumDropTransfers XmCNumDropTransfers Cardinal 0 CSG XmNtransferProc XmCTransferProc XtSelectionCallbackProc NULL CSG XmNtransferStatus XmCTransferStatus unsigned char XmTRANSFER_SUCCESS CSG .TE .KE .in .sp 1 .PP .IP "\fIXmNdropTransfers\fP" Specifies the address of an array of drop transfer entry records. The drop transfer is complete when all the entries in the list have been processed. .IP "\fIXmNincremental\fP" Specifies a Boolean value that indicates whether the transfer on the receiver side uses the Xt incremental selection transfer mechanism described in \*EX Toolkit Intrinsics \- C Language Interface\fP. If the value is True, the receiver uses incremental transfer; if the value is False, the receiver uses atomic transfer. .IP "\fIXmNnumDropTransfers\fP" Specifies the number of entries in \fIXmNdropTransfers\fP. If this resource is set to 0 at any time, the transfer is considered complete. The value of \fIXmNtransferStatus\fP determines the completion handshaking process. .IP "\fIXmNtransferProc\fP" Specifies a procedure of type \fIXtSelectionCallbackProc\fP that delivers the requested selection values. The \fBwidget\fP argument passed to this procedure is the DropTransfer widget. The selection atom passed is _MOTIF_DROP. For additional information on selection callback procedures, see \*EX Toolkit Intrinsics \- C Language Interface\fP. .IP "\fIXmNtransferStatus\fP" Specifies the current status of the drop transfer. The client updates this value when the transfer ends and communicates the value to the initiator. The possible values are .IP "\fIXmTRANSFER_SUCCESS\fP The transfer succeeded. .IP "\fIXmTRANSFER_FAILURE\fP The transfer failed. .LE .SS "Inherited Resources" DropTransfer inherits behavior and a resource from \fIObject\fP. For a complete description of this resource, refer to the \fIObject\fP reference page. .PP .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Object Resource Set Name Class Type Default Access _ XmNdestroyCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .PP .SH "RELATED INFORMATION" .na \fIObject(3X)\fP, \fIXmDisplay(3X)\fP, \fIXmDragContext(3X)\fP, \fIXmDragIcon(3X)\fP, \fIXmDropSite(3X)\fP, \fIXmDropTransferAdd(3X)\fP, and \fIXmDropTransferStart(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDropTransferAdd 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDropTransferAdd\fP \- A Drag and Drop function that enables additional drop transfer entries to be processed after initiating a drop transfer .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmDropTransferAdd (\fBdrop_transfer, transfers, num_transfers\fI) .ta .5i 2.25i .nf Widget \fBdrop_transfer\fI; XmDropTransferEntryRec *\fBtransfers\fI; Cardinal \fBnum_transfers\fI; .iE .sE .SH DESCRIPTION .fi \fIXmDropTransferAdd\fP identifies a list of additional drop transfer entries to be processed after a drop transfer is started. .IP "\fBdrop_transfer\fP" Specifies the ID of the DropTransfer widget returned by \fIXmDropTransferStart\fP .IP "\fBtransfers\fP" Specifies the additional drop transfer entries that the receiver wants processed .IP "\fBnum_transfers\fP" Specifies the number of items in the \fBtransfers\fP array .PP For a complete definition of DropTransfer and its associated resources, see \fIXmDropTransfer(3X)\fP. .SH RELATED INFORMATION .na \fIXmDragContext(3X)\fP, \fIXmDropTransfer(3X)\fP, and \fIXmDropTransferStart(3X). .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmDropTransferStart 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmDropTransferStart\fP \- A Drag and Drop function that initiates a drop transfer .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmDropTransferStart (\fBwidget, arglist, argcount\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; ArgList \fBarglist\fI; Cardinal \fBargcount\fI; .iE .sE .SH DESCRIPTION .fi \fIXmDropTransferStart\fP initiates a drop transfer and uses the specified argument list to initialize an \fIXmDropTransfer\fP object. The DropTransfer object can be manipulated with \fIXtSetValues\fP and \fIXtGetValues\fP until the last call to the \fIXmNtransferProc\fP procedure is made. After that point, the result of using the widget pointer is undefined. The DropTransfer object is freed by the toolkit when a transfer is complete. .IP "\fBwidget\fP" Specifies the ID of the DragContext widget associated with the transaction .IP "\fBarglist\fP" Specifies the argument list .IP "\fBargcount\fP" Specifies the number of attribute/value pairs in the argument list (\fBarglist\fP) .PP For a complete definition of DropTransfer and its associated resources, see \fIXmDropTransfer(3X)\fP. .SH RETURN VALUE Returns the ID of the DropTransfer widget. .SH RELATED INFORMATION .na \fIXmDragContext(3X)\fP, \fIXmDropTransfer(3X)\fP, and \fIXmDropTransferAdd(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** .TH XmFileSelectionBox 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFileSelectionBox\fP \- The FileSelectionBox widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi FileSelectionBox traverses through directories, views the files and subdirectories in them, and then selects files. .PP A FileSelectionBox has the following main areas: .TP \(bu A text input field for displaying and editing a directory mask used to select the files to be displayed .TP \(bu An optional text input field for displaying and editing a filter mask used to select the files to be displayed. .TP \(bu A scrollable list of filenames .TP \(bu A scrollable list of subdirectories .TP \(bu A text input field for displaying and editing a filename .TP \(bu A group of PushButtons, labeled \fIOK\fP, \fIFilter\fP, \fICancel\fP, and \fIHelp\fP .PP Additional children may be added to the FileSelectionBox after creation. FileSelectionBox inherits the layout functionality provided by SelectionBox for any additional children. The list of filenames, the list of subdirectories, or both can be removed from the FileSelectionBox after creation by unmanaging the appropriate widgets and their labels. The list and label widgets are obtained by calling the .ne 5 function \fIXmFileSelectionBoxGetChild\fP. To remove either the directory list or the file list, unmanage the parent of the appropriate list widget and unmanage the corresponding label. .PP The user can specify resources in a resource file for the automatically created widgets and gadgets of FileSelectionBox. The following list identifies the names of these widgets (or gadgets) and the associated FileSelectionBox areas. .PP Filter Label \- "FilterLabel" .PP Filter Text \- "Text" .PP Directory List \- "DirList" .PP Directory List Label \- "Dir" .PP The directory mask is a string specifying the base directory to be examined and a search pattern. Ordinarily, the directory list displays the subdirectories of the base directory, as well as the base directory itself and its parent directory. The file list ordinarily displays all files and/or subdirectories in the base directory that match the search pattern. .PP Optionally, the search pattern mask and the base directory can be displayed in two separate text fields. This option is controlled by the \fIpathMode\fP resource. Having two text fields for the search pattern mask and the directory makes it easier for the end user to edit and understand these two separate concepts. Using this alternate display does not change the meaning of resources that control the content of these fields: XmNdirectory, XmNdirMask, and XmNpattern. .PP A procedure specified by the \fIXmNqualifySearchDataProc\fP resource extracts the base directory and search pattern from the directory mask. If the directory specification is empty, the current working directory is used. If the search pattern is empty, a pattern that matches all files is used. .PP An application can supply its own \fIXmNqualifySearchDataProc\fP as well as its own procedures to search for subdirectories and files. The default \fIXmNqualifySearchDataProc\fP works as follows: The directory mask is a pathname that can contain zero or more \fBwildcard\fP characters in its directory portion, its file portion, or both. The directory components of the directory mask up to, but not including, the first component with a wildcard character specify the directory to be searched, relative to the current working directory. The remaining components specify the search pattern. If the directory mask is empty or if its first component contains a wildcard character, the current working directory is searched. If no component of the directory mask contains a wildcard character, the entire directory mask is the directory specification, and all files in that directory are matched. .PP The user can select a new directory to examine by scrolling through the list of directories and selecting the desired directory or by editing the directory mask. Selecting a new directory from the directory list does not change the search pattern. A user can select a new search pattern by editing the directory mask or, when the FileSelectionBox has the optional \fIpathMode\fP XmPATH_MODE_RELATIVE display, the filter text field. Double clicking or pressing \fIKActivate\fP on a directory in the directory list initiates a search for files and subdirectories in the new directory, using the current search pattern. .PP The user can select a file by scrolling through the list of filenames and selecting the desired file or by entering the filename directly into the text edit area. Selecting a file from the list causes that filename to appear in the file selection text edit area. .PP The user may select a new file as many times as desired. The application is not notified until the user takes one of these actions: .TP \(bu Selects the \fIOK\fP PushButton .TP \(bu Presses \fIKActivate\fP while the selection text edit area has the keyboard focus. .TP \(bu Double clicks or presses \fIKActivate\fP on an item in the file list .PP FileSelectionBox initiates a directory and file search when any of the following occurs: .TP \(bu The FileSelectionBox is initialized .TP \(bu The function \fIXtSetValues\fP is used to change \fIXmNdirMask\fP, \fIXmNdirectory\fP, \fIXmNpattern\fP, or \fIXmNfileTypeMask\fP .TP \(bu The user activates the \fIFilter\fP PushButton .TP \(bu The user double clicks or presses \fIKActivate\fP on an item in the directory list .TP \(bu The application calls \fIXmFileSelectionDoSearch\fP .TP \(bu The user presses \fIKActivate\fP while the directory mask text edit area has the keyboard focus .PP When a file search is initiated, the FileSelectionBox takes the following actions: .TP \(bu Constructs an \fIXmFileSelectionBoxCallbackStruct\fP structure with values appropriate for the action that initiated the search .TP \(bu Calls the \fIXmNqualifySearchDataProc\fP with the callback structure as the data input argument .TP \(bu Sets \fIXmNdirectoryValid\fP and \fIXmNlistUpdated\fP to False .TP \(bu Calls the \fIXmNdirSearchProc\fP with the qualified data returned by the \fIXmNqualifySearchDataProc\fP .PP If \fIXmNdirectoryValid\fP is True, the FileSelectionBox takes these additional actions: .TP \(bu Sets \fIXmNlistUpdated\fP to False .TP \(bu Calls the \fIXmNfileSearchProc\fP with the qualified data returned by the \fIXmNqualifySearchDataProc\fP (and possibly modified by the \fIXmNdirSearchProc\fP) .TP \(bu If \fIXmNlistUpdated\fP is True and the file list is empty, displays the \fIXmNnoMatchString\fP in the file list and clears the selection text and \fIXmNdirSpec\fP .TP \(bu If \fIXmNlistUpdated\fP is True and the file list is not empty, sets the selection text and \fIXmNdirSpec\fP to the qualified \fBdir\fP returned by the \fIXmNqualifySearchDataProc\fP (and possibly modified by the \fIXmNdirSearchProc\fP) .TP \(bu Sets the directory mask text and \fIXmNdirMask\fP to the qualified \fBmask\fP returned by the \fIXmNqualifySearchDataProc\fP (and possibly modified by the \fIXmNdirSearchProc\fP) .TP \(bu Sets \fIXmNdirectory\fP to the qualified \fBdir\fP returned by the \fIXmNqualifySearchDataProc\fP (and possibly modified by the \fIXmNdirSearchProc\fP) .TP \(bu Sets \fIXmNpattern\fP to the qualified \fBpattern\fP returned by the \fIXmNqualifySearchDataProc\fP (and possibly modified by the \fIXmNdirSearchProc\fP) .SS "Classes" FileSelectionBox inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIConstraint\fP, \fIXmManager\fP, \fIXmBulletinBoard\fP, and \fIXmSelectionBox\fP. .PP The class pointer is \fIxmFileSelectionBoxWidgetClass\fP. .PP The class name is \fIXmFileSelectionBox\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmFileSelectionBox Resource Set Name Class Type Default Access _ XmNdirectory XmCDirectory XmString dynamic CSG XmNdirectoryValid XmCDirectoryValid Boolean dynamic SG XmNdirListItems XmCDirListItems XmStringTable dynamic SG XmNdirListItemCount XmCDirListItemCount int dynamic SG XmNdirListLabelString XmCDirListLabelString XmString dynamic CSG XmNdirMask XmCDirMask XmString dynamic CSG XmNdirSearchProc XmCDirSearchProc XmSearchProc default procedure CSG XmNdirSpec XmCDirSpec XmString dynamic CSG XmNfileListItems XmCItems XmStringTable dynamic SG XmNfileListItemCount XmCItemCount int dynamic SG XmNfileListLabelString XmCFileListLabelString XmString dynamic CSG XmNfileSearchProc XmCFileSearchProc XmSearchProc default procedure CSG XmNfileTypeMask XmCFileTypeMask unsigned char XmFILE_REGULAR CSG XmNfilterLabelString XmCFilterLabelString XmString dynamic CSG .wH .tH XmNlistUpdated XmCListUpdated Boolean dynamic SG XmNnoMatchString XmCNoMatchString XmString "\0[\0\0\0\0]\0" CSG XmNpattern XmCPattern XmString dynamic CSG XmNqualifySearchDataProc XmCQualifySearchDataProc XmQualifyProc default procedure CSG pathMode PathMode XmRPathMode XmPATH_MODE_FULL C fileFilterStyle FileFilterStyle XmRFileFilterStyle XmFILTER_NONE C dirTextLabelString DirTextLabelString XmString NULL C .TE .KE .in .sp 1 .IP "\fIXmNdirectory\fP" Specifies the base directory used in combination with \fIXmNpattern\fP in determining the files and directories to be displayed. The default value is determined by the \fIXmNqualifySearchDataProc\fP and depends on the initial values of \fIXmNdirMask\fP, \fIXmNdirectory\fP, and \fIXmNpattern\fP. If the default is NULL or empty, the current working directory is used. .IP "\fIXmNdirectoryValid\fP" Specifies an attribute that is set only by the directory search procedure. The value is set to True if the directory passed to the directory search procedure can actually be searched. If this value is False the file search procedure is not called, and \fIXmNdirMask\fP, \fIXmNdirectory\fP, and \fIXmNpattern\fP are not changed. .IP "\fIXmNdirListItems\fP" Specifies the items in the directory list. \fIXtGetValues\fP for this resource returns the list items themselves, not a copy of the list items. The application must not free the returned items. .IP "\fIXmNdirListItemCount\fP" Specifies the number of items in the directory list. The value must not be negative. .IP "\fIXmNdirListLabelString\fP" Specifies the label string of the directory list. The default for this resource depends on the locale. In the C locale the default is "Directories". .nL .ne 2i .IP "\fIXmNdirMask\fP" Specifies the directory mask used in determining the files and directories to be displayed. The default value is determined by the .ne 5 \fIXmNqualifySearchDataProc\fP and depends on the initial values of \fIXmNdirMask\fP, \fIXmNdirectory\fP, and \fIXmNpattern\fP. .IP "\fIXmNdirSearchProc\fP" Specifies a directory search procedure to replace the default directory-search procedure. FileSelectionBox's default directory-search procedure fulfills the needs of most applications. Because it is impossible to cover the requirements of all applications, you can replace the default search procedure. .IP The directory search procedure is called with two arguments: the FileSelectionBox widget and a pointer to an \fIXmFileSelectionBoxCallbackStruct\fP structure. The callback structure is generated by the \fIXmNqualifySearchDataProc\fP and contains all information required to conduct a directory search, including the directory mask and a qualified base directory and search pattern. .ne 4 Once called, it is up to the search routine to generate a new list of directories and update the FileSelectionBox widget by using \fIXtSetValues\fP. .IP The search procedure must set \fIXmNdirectoryValid\fP and \fIXmNlistUpdated\fP. If it generates a new list of directories, it must also set \fIXmNdirListItems\fP and \fIXmNdirListItemCount\fP. .IP If the search procedure cannot search the specified directory, it must warn the user and set \fIXmNdirectoryValid\fP and \fIXmNlistUpdated\fP to False, unless it prompts and subsequently obtains a valid directory. If the directory is valid but is the same as the current \fIXmNdirectory\fP, the search procedure must set \fIXmNdirectoryValid\fP to True, but it may elect not to generate a new list of directories. In this case is must set \fIXmNlistUpdated\fP to False. .IP If the search procedure generates a new list of directories, it must set \fIXmNdirListItems\fP to the new list of directories and \fIXmNdirListItemCount\fP to the number of items in the list. If there are no directories, it sets \fIXmNdirListItems\fP to NULL and \fIXmNdirListItemCount\fP to 0. In either case it must set \fIXmNdirectoryValid\fP and \fIXmNlistUpdated\fP to True. .IP In constructing the list of directories, the search procedure should consider the value of the resource \fIfileFilterStyle\fP and exclude directories the begin with `.' when this resource is set to XmFILTER_HIDDEN_FILES. .IP The search procedure ordinarily should not change the callback struct. But if the original directory is not valid, the search procedure may obtain a new directory from the user. In this case it should set the \fBdir\fP member of the callback struct to the new directory, call the \fIXmNqualifySearchDataProc\fP with the callback struct as the input argument, and copy the qualified data returned by the \fIXmNqualifySearchDataProc\fP into the callback struct. .IP "\fIXmNdirSpec\fP" Specifies the full file path specification. This is the \fIXmNtextString\fP resource in SelectionBox, renamed for FileSelectionBox. The default value is determined by the FileSelectionBox after conducting the initial directory and file search. .IP "\fIdirTextLabelString\fP" This resource takes effect when the \fIpathMode\fP is XmPATH_MODE_RELATIVE and is ignored when the \fIpathMode\fP is XmPATH_MODE_FULL. Specifies the label string of the directory text field. The default for this resource is NULL. .IP "\fIfileFilterStyle\fP" There are two possible values: .wH .rS .TP \(bu \fI0 / XmFILTER_NONE\fP - the default \fIXmNdirSearchProc\fP and \fIXmNfileSearchProc\fP do not filter any of the directories or files. .TP \(bu \fI1 / XmFILTER_HIDDEN_FILES\fP - the default \fIXmNdirSearchProc\fP and \fIXmNfileSearchProc\fP filter any file or directory that begins with `.'. There is one exception: the `..' directory is not filtered out of the directory search. .wH .rE .nL .ne 6 .IP "\fIXmNfileListItems\fP" Specifies the items in the file list. This is the \fIXmNlistItems\fP resource in SelectionBox, renamed for FileSelectionBox. \fIXtGetValues\fP for this resource returns the list items themselves, not a copy of the list items. The application must not free the returned items. .IP "\fIXmNfileListItemCount\fP" Specifies the number of items in the file list. This is the \fIXmNlistItemCount\fP resource in SelectionBox, renamed for FileSelectionBox. The value must not be negative. .IP "\fIXmNfileListLabelString\fP" Specifies the label string of the file list. This is the \fIXmNlistLabelString\fP resource in SelectionBox, renamed for FileSelectionBox. The default for this resource depends on the locale. In the C locale the default is "Files". .IP "\fIXmNfileSearchProc\fP" Specifies a file search procedure to replace the default file-search procedure. FileSelectionBox's default file-search procedure fulfills the needs of most applications. Because it is impossible to cover the requirements of all applications, you can replace the default search procedure. .IP The file search procedure is called with two arguments: the FileSelectionBox widget and a pointer to an \fIXmFileSelectionBoxCallbackStruct\fP structure. The callback structure is generated by the \fIXmNqualifySearchDataProc\fP (and possibly modified by the \fIXmNdirSearchProc\fP). It contains all information required to conduct a file search, including the directory mask and a qualified base directory and search pattern. .ne 4 Once called, it is up to the search routine to generate a new list of files and update the FileSelectionBox widget by using \fIXtSetValues\fP. .IP The search procedure must set \fIXmNlistUpdated\fP. If it generates a new list of files, it must also set \fIXmNfileListItems\fP and \fIXmNfileListItemCount\fP. .IP The search procedure is recommended always to generate a new list of files. If the \fBmask\fP member of the callback struct is the same as the \fBmask\fP member of the callback struct in the preceding call to the search procedure, the procedure may elect not to generate a new list of files. In this case it must set \fIXmNlistUpdated\fP to False. .IP If the search procedure generates a new list of files, it must set \fIXmNfileListItems\fP to the new list of files and \fIXmNfileListItemCount\fP to the number of items in the list. If there are no files, it sets \fIXmNfileListItems\fP to NULL and \fIXmNfileListItemCount\fP to 0. In either case it must set \fIXmNlistUpdated\fP to True. .IP In constructing the list of files, the search procedure should include only files of the types specified by the widget's \fIXmNfileTypeMask\fP. .IP In constructing the list of files, the search procedure should consider the value of the resource \fIfileFilterStyle\fP and exclude files the begin with `.' when this resource is set to XmFILTER_HIDDEN_FILES. .IP Setting \fIXmNdirSpec\fP is optional, but recommended. Set this attribute to the full file specification of the directory searched. The directory specification is displayed below the directory and file lists. .IP "\fIXmNfileTypeMask\fP" Specifies the type of files listed in the file list. Following are the possible values: .wH .rS .TP \(bu \fIXmFILE_REGULAR\fP restricts the file list to contain only regular files. .TP \(bu \fIXmFILE_DIRECTORY\fP restricts the file list to contain only directories. .TP \(bu \fIXmFILE_ANY_TYPE\fP allows the list to contain all file types including directories. .wH .rE .nL .ne 7 .IP "\fIXmNfilterLabelString\fP" Specifies the label string for the text entry field for the directory mask. When the resource \fIpathMode\fP is XmPATH_MODE_RELATIVE, this string labels the text field entry for the pattern. The default for this resource depends on the locale. In the C locale the default is "Filter". .IP "\fIXmNlistUpdated\fP" Specifies an attribute that is set only by the directory and file search procedures. Set to True if the search procedure updated the directory or file list. .IP "\fIXmNnoMatchString\fP" Specifies a string to be displayed in the file list if the list of files is empty. .IP "\fIpathMode\fI" This resource provides an alternate layout for the FileSelectionBox. It has two possible values: .wH .rS .TP \(bu \fI0 / XmPATH_MODE_FULL\fP - a single text field to display the XmNdirMask. .TP \(bu \fI1 / XmPATH_MODE_RELATIVE\fP - a text field to display the XmNdirectory and a text field to display the XmNpattern. .wH .rE .nL .ne 6 When the \fIpathMode\fP is XmPATH_MODE_RELATIVE, the resource \fIXmNfilterLabelString\fP applies to the text field for the \fIXmNpattern\fP, and the resource \fIdirTextLabelString\fP applies to the text field for the \fIXmNdirectory\fP. .IP "\fIXmNpattern\fP" Specifies the search pattern used in combination with \fIXmNdirectory\fP in determining the files and directories to be displayed. The default value is determined by the \fIXmNqualifySearchDataProc\fP and depends on the initial values of \fIXmNdirMask\fP, \fIXmNdirectory\fP, and \fIXmNpattern\fP. If the default is NULL or empty, a pattern that matches all files is used. .IP "\fIXmNqualifySearchDataProc\fP" Specifies a search data qualification procedure to replace the default data qualification procedure. FileSelectionBox's default data qualification procedure fulfills the needs of most applications. Because it is impossible to cover the requirements of all applications, you can replace the default procedure. .IP The data qualification procedure is called to generate a qualified directory mask, base directory, and search pattern for use by the directory and file search procedures. It is called with three arguments: the FileSelectionBox widget and pointers to two \fIXmFileSelectionBoxCallbackStruct\fP structures. The first callback struct contains the input data. The second callback struct contains the output data, to be filled in by the data qualification procedure. .IP .ne 5 If the input \fBdir\fP and \fBpattern\fP members are not NULL, the procedure must copy them to the corresponding members of the output callback struct. .IP .ne 6 If the input \fBdir\fP is NULL, the procedure constructs the output \fBdir\fP as follows: If the input \fBmask\fP member is NULL, the procedure uses the widget's \fIXmNdirectory\fP as the output \fBdir\fP; otherwise, it extracts the output \fBdir\fP from the input \fBmask\fP. If the resulting output \fBdir\fP is empty, the procedure uses the current working directory instead. .IP If the input \fBpattern\fP is NULL, the procedure constructs the output \fBpattern\fP as follows: If the input \fBmask\fP member is NULL, the procedure uses the widget's \fIXmNpattern\fP as the output \fBpattern\fP; otherwise, it extracts the output \fBpattern\fP from the input \fBmask\fP. If the resulting output \fBpattern\fP is empty, the procedure uses a pattern that matches all files instead. .IP The data qualification procedure constructs the output \fBmask\fP from the output \fBdir\fP and \fBpattern\fP. The procedure must ensure that the output \fBdir\fP, \fBpattern\fP, and \fBmask\fP are fully qualified. .IP If the input \fBvalue\fP member is not NULL, the procedure must copy it to the output \fBvalue\fP member; otherwise, the procedure must copy the widget's \fIXmNdirSpec\fP to the output \fBvalue\fP. .IP The data qualification procedure must calculate the lengths of the output \fBvalue\fP, \fBmask\fP, \fBdir\fP, and \fBpattern\fP members and must fill in the corresponding length members of the output callback struct. .IP The data qualification procedure must copy the input \fBreason\fP and \fBevent\fP members to the corresponding output members. .IP The values of the \fIXmNdirSearchProc\fP and \fIXmNfileSearchProc\fP are procedure pointers of type \fIXmSearchProc\fP, defined as follows: .sS .iS .sp \n(PDu void (* XmSearchProc) (\fBw, search_data\fI) .ta .5i 1.25i .nf Widget \fBw\fI; XtPointer \fBsearch_data\fI; .fi .iE .sE .IP "\fBw\fP The FileSelectionBox widget .IP "\fBsearch_data\fP Pointer to an \fIXmFileSelectionBoxCallbackStruct\fP containing information for conducting a search .IP .PP The value of the \fIXmNqualifySearchDataProc\fP resource is a procedure pointer of type \fIXmQualifyProc\fP, defined as follows: .sS .iS .sp \n(PDu void (* XmQualifyProc) (\fBw, input_data, output_data\fI) .ta .5i 1.25i .nf Widget \fBw\fI; XtPointer \fBinput_data\fI; XtPointer \fBoutput_data\fI; .fi .iE .sE .IP "\fBw\fP The FileSelectionBox widget .IP "\fBinput_data\fP Pointer to an \fIXmFileSelectionBoxCallbackStruct\fP containing input data to be qualified .IP "\fBoutput_data\fP" Pointer to an \fIXmFileSelectionBoxCallbackStruct\fP containing output data to be filled in by the qualification procedure. .SS "Inherited Resources" FileSelectionBox inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmSelectionBox Resource Set Name Class Type Default Access _ XmNapplyCallback XmCCallback XtCallbackList NULL C XmNapplyLabelString XmCApplyLabelString XmString dynamic CSG XmNcancelCallback XmCCallback XtCallbackList NULL C XmNcancelLabelString XmCCancelLabelString XmString dynamic CSG XmNchildPlacement XmCChildPlacement unsigned char XmPLACE_ABOVE_SELECTION CSG XmNdialogType XmCDialogType unsigned char XmDIALOG_FILE_SELECTION G XmNhelpLabelString XmCHelpLabelString XmString dynamic CSG XmNlistItemCount XmCItemCount int dynamic CSG XmNlistItems XmCItems XmStringTable dynamic CSG XmNlistLabelString XmCListLabelString XmString dynamic CSG XmNlistVisibleItemCount XmCVisibleItemCount int dynamic CSG XmNminimizeButtons XmCMinimizeButtons Boolean False CSG XmNmustMatch XmCMustMatch Boolean False CSG XmNnoMatchCallback XmCCallback XtCallbackList NULL C .wH .tH XmNokCallback XmCCallback XtCallbackList NULL C XmNokLabelString XmCOkLabelString XmString dynamic CSG XmNselectionLabelString XmCSelectionLabelString XmString dynamic CSG XmNtextAccelerators XmCTextAccelerators XtAccelerators default C XmNtextColumns XmCColumns short dynamic CSG XmNtextString XmCTextString XmString dynamic CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmBulletinBoard Resource Set Name Class Type Default Access _ XmNallowOverlap XmCAllowOverlap Boolean True CSG XmNautoUnmanage XmCAutoUnmanage Boolean False CG XmNbuttonFontList XmCButtonFontList XmFontList dynamic CSG XmNcancelButton XmCWidget Widget Cancel button SG XmNdefaultButton XmCWidget Widget OK button SG XmNdefaultPosition XmCDefaultPosition Boolean True CSG XmNdialogStyle XmCDialogStyle unsigned char dynamic CSG XmNdialogTitle XmCDialogTitle XmString NULL CSG XmNfocusCallback XmCCallback XtCallbackList NULL C XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG XmNmapCallback XmCCallback XtCallbackList NULL C XmNmarginHeight XmCMarginHeight Dimension 10 CSG XmNmarginWidth XmCMarginWidth Dimension 10 CSG XmNnoResize XmCNoResize Boolean False CSG .wH .tH XmNresizePolicy XmCResizePolicy unsigned char XmRESIZE_ANY CSG XmNshadowType XmCShadowType unsigned char XmSHADOW_OUT CSG XmNtextFontList XmCTextFontList XmFontList dynamic CSG XmNtextTranslations XmCTranslations XtTranslations NULL C XmNunmapCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmManager Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget dynamic CSG XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension dynamic CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic N/A XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.1i .nf typedef struct { int \fBreason\fI; \fIXEvent \fB* event\fI; \fIXmString \fBvalue\fI; \fIint \fBlength\fI; \fIXmString \fBmask\fI; \fIint \fBmask_length\fI; \fIXmString \fBdir\fI; \fIint \fBdir_length\fI; \fIXmString \fBpattern\fI; \fIint \fBpattern_length\fI; } XmFileSelectionBoxCallbackStruct; .iE .sE .IP "\fBreason\fP" Indicates why the callback was invoked .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback .IP "\fBvalue\fP" Specifies the current value of \fIXmNdirSpec\fP .IP "\fBlength\fP" Specifies the number of bytes in \fBvalue\fP .IP "\fBmask\fP" Specifies the current value of \fIXmNdirMask\fP .IP "\fBmask_length\fP" Specifies the number of bytes in \fBmask\fP .IP "\fBdir\fP" Specifies the current base directory .IP "\fBdir_length\fP" Specifies the number of bytes in \fBdir\fP .IP "\fBpattern\fP" Specifies the current search pattern .IP "\fBpattern_length\fP" Specifies the number of bytes in \fBpattern\fP .SS "Translations" XmFileSelectionBox inherits translations from XmSelectionBox. .SS "Accelerators" The \fIXmNtextAccelerators\fP from XmSelectionBox are added to the selection and directory mask (filter) Text descendants of XmFileSelectionBox. .SS "Action Routines" The XmFileSelectionBox action routines are described below: .IP "\fISelectionBoxUpOrDown(0|1|2|3)\fP:" If neither the selection text nor the directory mask (filter) text has the focus, this action does nothing. .IP .ne 3i If the selection text has the focus, the term \fBlist\fP in the following description refers to the file list, and the term \fBtext\fP refers to the selection text. If the directory mask text has the focus, \fBlist\fP refers to the directory list, and \fBtext\fP refers to the directory mask text. .IP When called with a 0 argument, selects the previous item in the list and replaces the text with that item. .IP When called with a 1 argument, selects the next item in the list and replaces the text with that item. .IP When called with a 2 argument, selects the first item in the list and replaces the text with that item. .IP When called with a 3 argument, selects the last item in the list and replaces the text with that item. .IP "\fISelectionBoxRestore()\fP:" If neither the selection text nor the directory mask (filter) text has the focus, this action does nothing. .IP If the selection text has the focus, replaces the selection text with the selected item in the file list. If no item in the file list is selected, clears the selection text. .IP If the directory mask text has the focus, replaces the directory mask text with a new directory mask constructed from the \fIXmNdirectory\fP and \fIXmNpattern\fP resources. .SS "Additional Behavior" The FileSelectionBox widget has the additional behavior described below: .IP "\fIMAny\ KCancel\fP:" Calls the activate callbacks for the cancel button if it is sensitive. If no cancel button exists and the parent of the FileSelectionBox is a manager, passes the event to the parent. .IP "\fI\fP\ in\ Selection\ Text:" Calls the selection text widget's \fIXmNactivateCallback\fP callbacks. If \fIXmNmustMatch\fP is True and the selection text does not match an item in the file list, calls the \fIXmNnoMatchCallback\fP callbacks with reason \fIXmCR_NO_MATCH\fP. Otherwise, calls the \fIXmNokCallback\fP callbacks with reason \fIXmCR_OK\fP. .nL .ne 5 .IP "\fI\fP\ in\ Directory\ Mask\ Text:" Calls the directory mask text widget's \fIXmNactivateCallback\fP callbacks. Initiates a directory and file search. Calls the \fIXmNapplyCallback\fP callbacks with reason \fIXmCR_APPLY\fP. .IP "\fI\fP\ or\ \fI\fP\ in\ Directory\ List:" Calls the directory list widget's \fIXmNdefaultActionCallback\fP callbacks. Initiates a directory and file search. Calls the \fIXmNapplyCallback\fP callbacks with reason \fIXmCR_APPLY\fP. .IP "\fI\fP\ or\ \fI\fP\ in\ File\ List:" Calls the file list widget's \fIXmNdefaultActionCallback\fP callbacks. Calls the \fIXmNokCallback\fP callbacks with reason \fIXmCR_OK\fP. .IP "\fI\fP\ or\ \fI\fP\ in\ Directory\ List:" Generates a new directory mask, using the selected list item as the directory and the pattern extracted from the current directory mask text as the search pattern. If the search pattern is empty, uses a pattern that matches all files in the directory. Replaces the directory mask text with the new directory mask. .IP "\fI\fP\ or\ \fI\fP\ in\ File\ List:" Replaces the selection text with the selected list item. .IP "\fI\fP in File List:" Drags the content of one or more selected list items using the drag and drop facility. If \fIBDrag\fP is pressed on an unselected item, drags only that item, excluding any other selected items. .IP The \fIXmNexportTargets\fP resource of the associated DragContext is set to target types of COMPOUND_TEXT and FILE_NAME. The \fIXmNclientData\fP resource is set to the index of the item in the list. .IP "\fI\fP in Directory List:" Drags the content of one or more selected list items using the drag and drop facility. If \fIBDrag\fP is pressed on an unselected item, drags only that item, excluding any other selected items. .IP The \fIXmNexportTargets\fP resource of the associated DragContext is set to target types of COMPOUND_TEXT and FILE_NAME. The \fIXmNclientData\fP resource is set to the index of the item in the list. .PP .IP "\fI\fP:" Initiates a directory and file search. Calls the \fIXmNapplyCallback\fP callbacks with reason \fIXmCR_APPLY\fP. .IP "\fI\fP:" If \fIXmNmustMatch\fP is True and the selection text does not match an item in the file list, calls the \fIXmNnoMatchCallback\fP callbacks with reason \fIXmCR_NO_MATCH\fP. Otherwise, calls the \fIXmNokCallback\fP callbacks with reason \fIXmCR_OK\fP. .P .ne 3i .IP "\fI\fP:" Calls the \fIXmNcancelCallback\fP callbacks with reason \fIXmCR_CANCEL\fP. .IP "\fI\fP:" Calls the \fIXmNhelpCallback\fP callbacks with reason \fIXmCR_HELP\fP. .nL .ne 5 .IP "\fI\fP:" If no button, list widget, or text widget has the keyboard focus: If \fIXmNmustMatch\fP is True and the selection text does not match an item in the file list, calls the \fIXmNnoMatchCallback\fP callbacks with reason \fIXmCR_NO_MATCH\fP. Otherwise, calls the \fIXmNokCallback\fP callbacks with reason \fIXmCR_OK\fP. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fIConstraint(3X)\fP, \fICore(3X)\fP, \fIXmBulletinBoard(3X)\fP, \fIXmCreateFileSelectionBox(3X)\fP, \fIXmCreateFileSelectionDialog(3X)\fP, \fIXmFileSelectionBoxGetChild(3X)\fP, \fIXmFileSelectionDoSearch(3X)\fP, \fIXmManager(3X)\fP, and \fIXmSelectionBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFileSelectionBoxGetChild 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFileSelectionBoxGetChild\fP \- A FileSelectionBox function used to access a component .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmFileSelectionBoxGetChild (\fBwidget, child\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; unsigned char \fBchild\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmFileSelectionBoxGetChild\fP is used to access a component within a FileSelectionBox. The parameters given to the function are the FileSelectionBox widget and a value indicating which component to access. .IP "\fBwidget\fP" Specifies the FileSelectionBox widget ID. .IP "\fBchild\fP" Specifies a component within the FileSelectionBox. The following are legal values for this parameter: .wH .rS .TP \(bu \fIXmDIALOG_APPLY_BUTTON\fP .TP \(bu \fIXmDIALOG_CANCEL_BUTTON\fP .TP \(bu \fIXmDIALOG_DEFAULT_BUTTON\fP .TP \(bu \fIXmDIALOG_DIR_LIST\fP .TP \(bu \fIXmDIALOG_DIR_LIST_LABEL\fP .TP \(bu \fIXmDIALOG_FILTER_LABEL\fP .TP \(bu \fIXmDIALOG_FILTER_TEXT\fP .TP \(bu \fIXmDIALOG_HELP_BUTTON\fP .TP \(bu \fIXmDIALOG_LIST\fP .TP \(bu \fIXmDIALOG_LIST_LABEL\fP .TP \(bu \fIXmDIALOG_OK_BUTTON\fP .TP \(bu \fIXmDIALOG_SELECTION_LABEL\fP .TP \(bu \fIXmDIALOG_SEPARATOR\fP .TP \(bu \fIXmDIALOG_TEXT\fP .TP \(bu \fIXmDIALOG_WORK_AREA\fP .wH .rE .PP For a complete definition of FileSelectionBox and its associated resources, see \fIXmFileSelectionBox(3X)\fP. .SH RETURN VALUE Returns the widget ID of the specified FileSelectionBox component. An application should not assume that the returned widget will be of any particular class. .SH RELATED INFORMATION .na \fIXmFileSelectionBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFileSelectionDoSearch 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFileSelectionDoSearch\fP \- A FileSelectionBox function that initiates a directory search .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmFileSelectionDoSearch (\fBwidget, dirmask\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString \fBdirmask\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmFileSelectionDoSearch\fP initiates a directory and file search in a FileSelectionBox widget. For a description of the actions that the FileSelectionBox takes when doing a search, see \fIXmFileSelectionBox(3X)\fP. .IP "\fBwidget\fP" Specifies the FileSelectionBox widget ID. .IP "\fBdirmask\fP" Specifies the directory mask used in determining the directories and files displayed in the FileSelectionBox lists. This value is used as the \fBmask\fP member of the input data \fIXmFileSelectionBoxCallbackStruct\fP structure passed to the FileSelectionBox's \fIXmNqualifySearchDataProc\fP. The \fBdir\fP and \fBpattern\fP members of that structure are NULL. .PP For a complete definition of FileSelectionBox and its associated resources, see \fIXmFileSelectionBox(3X)\fP. .SH RELATED INFORMATION .na \fIXmFileSelectionBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontList 3X "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontList\fP \- Data type for a font list .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi \fIXmFontList\fP is the data type for a font list. A font list consists of font list entries, each of which contains a font or a font set (a group of fonts) and is identified with a tag. The font list entry tag is optional; if NULL, the tag is set to \fIXmFONTLIST_DEFAULT_TAG\fP. The value of \fIXmFONTLIST_DEFAULT_TAG\fP is "XmFONTLIST_DEFAULT_TAG_STRING". .PP When a compound string is displayed, the font list element tag of the compound string segment is matched with a font list entry tag in the font list and the matching font list entry is used to display the compound string. A font list entry is chosen as follows: .TP \(bu The first font list entry whose tag matches the tag of the compound string segment is used. .TP \(bu If no match has been found and if the tag of the compound string segment is \fIXmFONTLIST_DEFAULT_TAG\fP, the first font list entry whose tag matches the tag that would result from creating an entry with \fIXmSTRING_DEFAULT_CHARSET\fP. For example, if creating an entry with \fIXmSTRING_DEFAULT_CHARSET\fP would result in the tag "ISO8859-1", the compound string segment tag \fIXmFONTLIST_DEFAULT_TAG\fP matches the font list entry tag "ISO8859-1". .TP \(bu If no match has been found and if the tag of the compound string segment matches the tag that would result from creating a segment with \fIXmSTRING_DEFAULT_CHARSET\fP, the first font list entry whose tag is \fIXmFONTLIST_DEFAULT_TAG\fP is used. .TP \(bu If no match has been found, the first entry in the font list is used. .PP The font list interface consists of the routines listed under "Related Information." .PP Font lists are specified in resource files using the following syntax: .PP \fBresource_spec\fP\fI:\fP \fBfont_entry\fP [ , \fBfont_entry\fP ]+ .PP The resource value string consists of one or more font list entries separated by commas. Each \fBfont_entry\fP identifies a font or font set, and an optional font list entry tag. A tag specified for a single font follows the font name and is separated by \fI=\fP ; otherwise, in a font set the tag is separated by a colon. The colon is required whether a tag is specified or not. A font entry uses the following syntax to specify a single font: .PP \fBfont_name\fP [ '=' \fBtag\fP ] .PP For example, this entry specifies a 10 point Times Italic font without a font list entry tag. .PP *fontList: -Adobe-Times-Medium-I-Normal--10* .PP A font entry containing a font set is similar except a semicolon separates multiple font names and the specification ends with a colon followed by an optional tag. .PP \fBfont_name\fP [ ';' \fBfont_name\fP ]+ ':' [ \fBtag\fP ] .PP A \fBfont_name\fP is an X Logical Font Description (XLFD) string and \fBtag\fP is any set of characters from ISO646IRV except space, comma, colon, equal sign and semicolon. An example of a font set entry is given below. It consists of three fonts (except for charsets), and an explicit font list entry tag. .PP .na *fontList : -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150;\\ .nL -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240;\\ .nL -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120:MY_TAG .ad .PP .SH RELATED INFORMATION .na \fIXmFontListAdd(3X)\fP, \fIXmFontListAppendEntry(3X)\fP, \fIXmFontListCopy(3X)\fP, \fIXmFontListCreate(3X)\fP, \fIXmFontListEntryCreate(3X)\fP, \fIXmFontListEntryFree(3X)\fP, \fIXmFontListEntryGetFont(3X)\fP, \fIXmFontListEntryGetTag(3X)\fP, \fIXmFontListEntryLoad(3X)\fP, \fIXmFontListFree(3X)\fP, \fIXmFontListFreeFontContext(3X)\fP, \fIXmFontListGetNextFont(3X)\fP, \fIXmFontListInitFontContext(3X)\fP, \fIXmFontListNextEntry(3X)\fP, \fIXmFontListRemoveEntry(3X)\fP, and \fIXmString(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListAdd 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListAdd\fP \- A font list function that creates a new font list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmFontList XmFontListAdd (\fBoldlist, font, charset\fI) .ta .5i 1.75i .nf XmFontList \fBoldlist\fI; XFontStruct \fB*font\fI; XmStringCharSet \fBcharset\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmFontListAdd\fP creates a new font list consisting of the contents of the \fBoldlist\fP and the new font-list element being added. This function deallocates the \fBoldlist\fP after extracting the required information; therefore, do not reference \fBoldlist\fP thereafter. .PP \fINote:\fP This function is obsolete and exists for compatibility with previous releases. It has been replaced by \fIXmFontListAppendEntry\fP. .IP "\fBoldlist\fP" Specifies a pointer to the font list to which an entry will be added. .IP "\fBfont\fP" Specifies a pointer to a font structure for which the new font list is generated. This is the structure returned by the XLib \fIXLoadQueryFont\fP function. .IP "\fBcharset\fP" Specifies the character set identifier for the font. This can be \fIXmSTRING_DEFAULT_CHARSET\fP, but this value does not comply with the AES, and it may be removed in future versions of Motif. If the value is \fIXmSTRING_DEFAULT_CHARSET\fP, the routine derives the character set from the current language environment. .SH RETURN VALUE Returns NULL if \fBoldlist\fP is NULL; returns \fBoldlist\fP if \fBfont\fP or \fBcharset\fP is NULL; otherwise, returns a new font list. .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP and \fIXmFontListAppendEntry(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListAppendEntry 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListAppendEntry\fP \- A font list function that appends an entry to a font list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmFontList XmFontListAppendEntry (\fBoldlist, entry\fI) .ta .5i 1.75i .nf XmFontList \fBoldlist\fI; XmFontListEntry \fBentry\fI; .iE .sE .SH DESCRIPTION .fi \fIXmFontListAppendEntry\fP creates a new font list that contains the contents of \fBoldlist\fP. This function copies the contents of the font list entry being added into this new font list. If \fBoldlist\fP is NULL, \fIXmFontListAppendEntry\fP creates a new font list containing only the single entry specified. .PP This function deallocates the original font list after extracting the required information. The caller must free the font list entry by using \fIXmFontListEntryFree\fP. .IP "\fBoldlist\fP" Specifies the font list to be added to .IP "\fBentry\fP" Specifies the font list entry to be added .SH RETURN VALUE If \fBentry\fP is NULL, returns \fBoldlist\fP; otherwise, returns a new font list. .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP, \fIXmFontListEntryCreate(3X)\fP, \fIXmFontListEntryFree(3X)\fP, \fIXmFontListEntryLoad(3X)\fP, \fIXmFontListFree(3X)\fP, and \fIXmFontListRemoveEntry(3X). .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListCopy 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListCopy\fP \- A font list function that copies a font list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmFontList XmFontListCopy (\fBfontlist\fI) .ta .5i 1.75i .nf XmFontList \fBfontlist\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmFontListCopy\fP creates a new font list consisting of the contents of the \fBfontlist\fP argument. .IP "\fBfontlist\fP" Specifies a font list to be copied .SH RETURN VALUE Returns NULL if \fBfontlist\fP is NULL; otherwise, returns a new font list. .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP and \fIXmFontListFree(3X). .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListCreate 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListCreate\fP \- A font list function that creates a font list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmFontList XmFontListCreate (\fBfont, charset\fI) .ta .5i 1.75i .nf XFontStruct \fB* font\fI; XmStringCharSet \fBcharset\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmFontListCreate\fP creates a new font list with a single element specified by the provided font and character set. It also allocates the space for the font list. .PP \fINote:\fP This function is obsolete and exists for compatibility with previous releases. It is replaced by \fIXmFontListAppendEntry\fP. .IP "\fBfont\fP" Specifies a pointer to a font structure for which the new font list is generated. This is the structure returned by the XLib \fIXLoadQueryFont\fP function. .nL .ne 15 .IP "\fBcharset\fP" Specifies the character set identifier for the font. This can be \fIXmSTRING_DEFAULT_CHARSET\fP, but this value does not comply with the AES, and it may be removed in future versions of Motif. If the value .ne 4 is \fIXmSTRING_DEFAULT_CHARSET\fP, the routine derives the character set from the current language environment. .SH RETURN VALUE Returns NULL if \fBfont\fP or \fBcharset\fP is NULL; otherwise, returns a new font list. .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP and \fIXmFontListAppendEntry(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListEntryCreate 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListEntryCreate\fP \- A font list function that creates a font list entry .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmFontListEntry XmFontListEntryCreate (\fBtag, type, font\fI) .ta .5i 1.5i .nf char *\fBtag\fI; XmFontType \fBtype\fI; XtPointer \fBfont\fI; .iE .sE .SH DESCRIPTION .fi \fIXmFontListEntryCreate\fP creates a font list entry that contains either a font or font set and is identified by a tag. .IP "\fBtag\fP" Specifies a NULL terminated string for the tag of the font list entry. The tag may be specified as \fIXmFONTLIST_DEFAULT_TAG\fP, which is used to identify the default font list element in a font list. .IP "\fBtype\fP" Specifies whether the \fBfont\fP argument is a font structure or a font set. Valid values are \fIXmFONT_IS_FONT\fP and \fIXmFONT_IS_FONTSET\fP. .IP "\fBfont\fP" Specifies either an \fIXFontSet\fP returned by \fIXCreateFontSet\fP or a pointer to an \fIXFontStruct\fP returned by \fIXLoadQueryFont\fP. .PP The toolkit does not copy the X Font structure specified by the \fBfont\fP argument. Therefore, an application programmer must not free \fIXFontStruct\fP or \fIXFontSet\fP until all font lists and/or font entries that reference it have been freed. .SH RETURN VALUE Returns a font list entry. .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP, \fIXmFontListAppendEntry(3X)\fP, \fIXmFontListEntryFree(3X)\fP, \fIXmFontListEntryGetFont(3X)\fP, \fIXmFontListEntryGetTag(3X)\fP, \fIXmFontListEntryLoad(3X)\fP, and \fIXmFontListRemoveEntry(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListEntryFree 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListEntryFree\fP \- A font list function that recovers memory used by a font list entry .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmFontListEntryFree (\fBentry\fI) .ta .5i 1.75i .nf XmFontListEntry *\fBentry\fI; .iE .sE .SH DESCRIPTION .fi \fIXmFontListEntryFree\fP recovers memory used by a font list entry. This routine does not free the \fIXFontSet\fP or \fIXFontStruct\fP associated with the font list entry. .IP "\fBentry\fP" Specifies the font list entry to be freed .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP, \fIXmFontListAppendEntry(3X)\fP, \fIXmFontListEntryCreate(3X)\fP, \fIXmFontListEntryLoad(3X)\fP, \fIXmFontListNextEntry(3X)\fP, and \fIXmFontListRemoveEntry(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListEntryGetFont 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListEntryGetFont\fP \- A font list function that retrieves font information from a font list entry .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XtPointer XmFontListEntryGetFont (\fBentry, type_return\fI) .ta .5i 1.75i .nf XmFontListEntry \fBentry\fI; XmFontType *\fBtype_return\fI; .iE .sE .SH DESCRIPTION .fi \fIXmFontListEntryGetFont\fP retrieves font information for a specified font list entry. If the font list entry contains a font, \fBtype_return\fP returns \fIXmFONT_IS_FONT\fP and the function returns a pointer to an \fIXFontStruct\fP. If the font list entry contains a font set, \fBtype_return\fP returns \fIXmFONT_IS_FONTSET\fP and the function returns the \fIXFontSet\fP. .IP "\fBentry\fP" Specifies the font list entry. .IP "\fBtype_return\fP" Specifies a pointer to the type of the font element for the current entry. Valid values are \fIXmFONT_IS_FONT\fP and \fIXmFONT_IS_FONTSET\fP. .PP The returned \fIXFontSet\fP or \fIXFontStruct\fP is not a copy of the toolkit data and must not be freed. .SH RETURN VALUE Returns an \fIXFontSet\fP or a pointer to an \fIXFontStruct\fP structure. .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP, \fIXmFontListEntryCreate(3X)\fP, \fIXmFontListEntryGetTag(3X)\fP \fIXmFontListEntryLoad(3X)\fP, and \fIXmFontListNextEntry(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListEntryGetTag 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListEntryGetTag\fP \- A font list function that retrieves the tag of a font list entry .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu char* XmFontListEntryGetTag (\fBentry\fI) .ta .5i 1.75i .nf XmFontListEntry \fBentry\fI; .iE .sE .SH DESCRIPTION .fi \fIXmFontListEntryGetTag\fP retrieves a copy of the tag of the specified font list entry. This routine allocates memory for the tag string that must be freed by the application. .IP "\fBentry\fP" Specifies the font list entry .SH RETURN VALUE Returns the tag for the font list entry. .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP, \fIXmFontListEntryCreate(3X)\fP, \fIXmFontListEntryGetFont(3X)\fP, \fIXmFontListEntryLoad(3X)\fP, and \fIXmFontListNextEntry(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListEntryLoad 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListEntryLoad\fP \- A font list function that loads a font or creates a font set and creates an accompanying font list entry .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmFontListEntry XmFontListEntryLoad (\fBdisplay, font_name, type, tag\fI) .ta .5i 1.5i .nf Display *\fBdisplay\fI; char *\fBfont_name\fI; XmFontType \fBtype\fI; char *\fBtag\fI; .iE .sE .SH DESCRIPTION .fi \fIXmFontListEntryLoad\fP loads a font or creates a font set based on the value of the \fBtype\fP argument. It creates and returns a font list entry that contains the font or font set and the specified tag. .PP If the value of \fBtype\fP is \fIXmFONT_IS_FONT\fP, the function uses the \fIXtCvtStringToFontStruct\fP routine to convert the value of \fBfont_name\fP to a font struct. If the value of \fBtype\fP is \fIXmFONT_IS_FONTSET\fP, the function uses the \fIXtCvtStringToFontSet\fP converter to create a font set in the current locale. \fIXmFontListEntryLoad\fP creates a font list entry that contains the font or font set derived from the converter. For more information about \fIXtCvtStringToFontStruct\fP and \fIXtCvtStringToFontSet\fP, see \*EX Toolkit Intrinsics \- C Language Interface.\fP .IP "\fBdisplay\fP" Specifies the display where the font list will be used. .IP "\fBfont_name\fP" Specifies an X Logical Font Description (XLFD) string, which is interpreted either as a font name or as a base font name list. A base font name list is a comma-separated and NULL-terminated string. .IP "\fBtype\fP" Specifies whether the \fBfont_name\fP argument refers to a font name or to a base font name list. Valid values are \fIXmFONT_IS_FONT\fP and \fIXmFONT_IS_FONTSET\fP. .IP "\fBtag\fP" Specifies the tag of the font list entry to be created. The tag may be specified as \fIXmFONTLIST_DEFAULT_TAG\fP. \fIXmFONTLIST_DEFAULT_TAG\fP is used to identify the default font list element in a font list when specified as part of a resource. .SH RETURN VALUE If the specified font is not found, or the specified font set can not be created, returns NULL; otherwise, returns a font list entry. .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP, \fIXmFontListAppendEntry(3X)\fP, \fIXmFontListEntryCreate(3X)\fP, \fIXmFontListEntryFree(3X)\fP, \fIXmFontListEntryGetFont(3X)\fP, \fIXmFontListEntryGetTag(3X)\fP, and \fIXmFontListRemoveEntry(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListFree 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListFree\fP \- A font list function that recovers memory used by a font list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmFontListFree (\fBlist\fI) .ta .5i 1.5i .nf XmFontList \fBlist\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmFontListFree\fP recovers memory used by a font list. This routine does not free the XFontSet or XFontStruct associated with the specified font list. .IP "\fBlist\fP" Specifies the font list to be freed .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP, \fIXmFontListAppendEntry(3X)\fP, \fIXmFontListCopy(3X)\fP, and \fIXmFontListRemoveEntry(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListFreeFontContext 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListFreeFontContext\fP \- A font list function that instructs the toolkit that the font list context is no longer needed .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmFontListFreeFontContext (\fBcontext\fI) .ta .5i 1.75i .nf XmFontContext \fBcontext\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmFontListFreeFontContext\fP instructs the toolkit that the context is no longer needed and will not be used without reinitialization. .IP "\fBcontext\fP" Specifies the font list context structure that was allocated by the \fIXmFontListInitFontContext\fP function .SH RELATED INFORMATION .na \fIXmFontListInitFontContext(3X)\fP and \fIXmFontListNextEntry(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListGetNextFont 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListGetNextFont\fP \- A font list function that allows applications to access the fonts and character sets in a font list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmFontListGetNextFont (\fBcontext, charset, font\fI) .ta .5i 1.75i .nf XmFontContext \fBcontext\fI; XmStringCharSet *\fBcharset\fI; XFontStruct **\fBfont\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmFontListGetNextFont\fP accesses the character set and font for the next entry of the font list. The application first uses the \fIXmFontListInitFontContext\fP routine to create a font list context. The application then calls \fIXmFontListGetNextFont\fP repeatedly with the same context. Each succeeding call accesses the next element of the font list. When finished, the application calls \fIXmFontListFreeFontContext\fP to free the allocated font list context. .PP This routine allocates memory for the character set string that must be freed by the application. .PP This function is obsolete and exists for compatibility with previous releases. It is replaced by \fIXmFontListNextEntry\fP. If \fIXmFontListGetNextFont\fP is passed a context that contains a font set entry, it will return the first font of the font set. The next call to the function will move to the next entry in the font list. .IP "\fBcontext\fP" Specifies the font list context .IP "\fBcharset\fP" Specifies a pointer to a character set string; the routine returns the character set for the current font list element .IP "\fBfont\fP" Specifies a pointer to a pointer to a font structure; the routine returns the font for the current font list element .SH RETURN VALUE Returns True if the returned values are valid; otherwise, returns False. .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP and \fIXmFontListNextEntry(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListInitFontContext 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListInitFontContext\fP \- A font list function that allows applications to access the entries in a font list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmFontListInitFontContext (\fBcontext, fontlist\fI) .ta .5i 1.75i .nf XmFontContext \fB*context\fI; XmFontList \fBfontlist\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmFontListInitFontContext\fP establishes a context to allow applications to access the contents of a font list. This context is used when reading the font list entry tag, font, or font set associated with each entry in the font list. A Boolean status is returned to indicate whether or not the font list is valid. .IP "\fBcontext\fP" Specifies a pointer to the allocated context .IP "\fBfontlist\fP" Specifies the font list .SH RETURN VALUE Returns True if the context was allocated; otherwise, returns False. .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP, \fIXmFontListFreeFontContext(3X)\fP, and \fIXmFontListNextEntry(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListNextEntry 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListNextEntry\fP \- A font list function that returns the next entry in a font list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmFontListEntry XmFontListNextEntry (\fBcontext\fI) .ta .5i 1.75i .nf XmFontContext \fBcontext\fI; .iE .sE .SH DESCRIPTION .fi \fIXmFontListNextEntry\fP returns the next entry in the font list. The application uses the \fIXmFontListInitFontContext\fP routine to create a font list context. The first call to \fIXmFontListNextEntry\fP sets the context to the first entry in the font list. The application then calls \fIXmFontListNextEntry\fP repeatedly with the same context. Each succeeding call accesses the next entry of the font list. When finished, the application calls \fIXmFontListFreeFontContext\fP to free the allocated font list context. .IP "\fBcontext\fP" Specifies the font list context .SH RETURN VALUE Returns NULL if the context does not refer to a valid entry or if it is at the end of the font list; otherwise, it returns a font list entry. .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP, \fIXmFontListEntryFree(3X)\fP, \fIXmFontListEntryGetFont(3X)\fP, \fIXmFontListEntryGetTag(3X)\fP, \fIXmFontListFreeFontContext(3X)\fP, and \fIXmFontListInitFontContext(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmFontListRemoveEntry 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFontListRemoveEntry\fP \- A font list function that removes a font list entry from a font list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmFontList XmFontListRemoveEntry (\fBoldlist, entry\fI) .ta .5i 1.75i .nf XmFontList \fBoldlist\fI; XmFontListEntry \fBentry\fI; .iE .sE .SH DESCRIPTION .fi \fIXmFontListRemoveEntry\fP creates a new font list that contains the contents of \fBoldlist\fP minus those entries specified in \fBentry\fP. The routine removes any entries from \fBoldlist\fP that match the components (tag, type font/font set) of the specified entry. The function deallocates the original font list after extracting the required information. The caller uses \fIXmFontListEntryFree\fP to recover memory allocated for the specified entry. This routine does not free the \fIXFontSet\fP or \fIXFontStruct\fP associated with the font list entry that is removed. .IP "\fBoldlist\fP" Specifies the font list .IP "\fBentry\fP" Specifies the font list entry to be removed .SH RETURN VALUE If \fBoldlist\fP is NULL, the function returns NULL. If \fBentry\fP is NULL or no entries are removed, the function returns \fBoldlist\fP. Otherwise, it returns a new font list. .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP, \fIXmFontListAppendEntry(3X)\fP, \fIXmFontListEntryCreate(3X)\fP, \fIXmFontListEntryFree(3X)\fP, \fIXmFontListEntryLoad(3X)\fP, and \fIXmFontListFree(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmForm 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmForm\fP \- The Form widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi Form is a container widget with no input semantics of its own. Constraints are placed on children of the Form to define attachments for each of the child's four sides. These attachments can be to the Form, to another child widget or gadget, to a relative position within the Form, or to the initial position of the child. The attachments determine the layout behavior of the Form when resizing occurs. .PP The default value for \fIXmNinitialFocus\fP is the value of \fIXmNdefaultButton\fP. .P Following are some important considerations in using a Form: .TP \(bu Every child must have an attachment on either the left or the right. If initialization or \fIXtSetValues\fP leaves a widget without such an attachment, the result depends upon the value of \fIXmNrubberPositioning\fP. .PP If \fIXmNrubberPositioning\fP is False, the child is given an \fIXmNleftAttachment\fP of \fIXmATTACH_FORM\fP and an \fIXmNleftOffset\fP equal to its current \fBx\fP value. .PP .ne 10 If \fIXmNrubberPositioning\fP is True, the child is given an \fIXmNleftAttachment\fP of \fIXmATTACH_POSITION\fP and an \fIXmNleftPosition\fP proportional to the current \fBx\fP value divided by the width of the Form. .PP In either case, if the child has not been previously given an \fBx\fP value, its \fBx\fP value is taken to be 0, which places the child at the left side of the Form. .TP \(bu If you want to create a child without any attachments, and then later (e.g., after creating and managing it, but before realizing it) give it a right attachment via \fIXtSetValues\fP, you must set its \fIXmNleftAttachment\fP to \fIXmATTACH_NONE\fP at the same time. .TP \(bu The \fIXmNresizable\fP resource controls only whether a geometry request by the child will be granted. It has no effect on whether the child's size can be changed because of changes in geometry of the Form or of other children. .TP \(bu Every child has a preferred width, based on geometry requests it makes (whether they are granted or not). .TP \(bu If a child has attachments on both the left and the right sides, its size is completely controlled by the Form. It can be shrunk below its preferred width or enlarged above it, if necessary, due to other constraints. In addition, the child's geometry requests to change its own width may be refused. .TP \(bu If a child has attachments on only its left or right side, it will always be at its preferred width (if resizable, otherwise at is current width). This may cause it to be clipped by the Form or by other children. .TP \(bu If a child's left (or right) attachment is set to \fIXmATTACH_SELF\fP, its corresponding left (or right) offset is forced to 0. The attachment is then changed to \fIXmATTACH_POSITION\fP, with a position that corresponds to \fBx\fP value of the child's left (or right) edge. To fix the position of a side at a specific \fBx\fP value use \fIXmATTACH_FORM\fP or \fIXmATTACH_OPPOSITE_FORM\fP with the \fBx\fP value as the left (or right) offset. .TP \(bu Unmapping a child has no effect on the Form except that the child is not mapped. .nL .ne 15 .TP \(bu Unmanaging a child unmaps it. If no other child is attached to it, or if all children attached to it and all children recursively attached to them are also all unmanaged, all of those children are treated as if they did not exist in determining the size of the Form. .TP \(bu When using \fIXtSetValues\fP to change the \fIXmNx\fP resource of a child, you must simultaneously set its left attachment to either \fIXmATTACH_SELF\fP or \fIXmATTACH_NONE\fP. Otherwise, the request is not granted. If \fIXmNresizable\fP is False, the request is granted only if the child's size can remain the same. .TP \(bu A left (or right) attachment of \fIXmATTACH_WIDGET\fP, where \fIXmNleftWidget\fP (or \fIXmNrightWidget\fP) is NULL, acts like an attachment of \fIXmATTACH_FORM\fP. .TP \(bu If an attachment is made to a widget that is not a child of the Form, but an ancestor of the widget is a child of the Form, the attachment is made to the ancestor. .PP All these considerations are true of top and bottom attachments as well, with top acting like left, bottom acting like right, \fBy\fP acting like \fBx\fP, and height acting like width. .SS "Classes" Form inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIConstraint\fP, \fIXmManager\fP, and \fIXmBulletinBoard\fP classes. .PP The class pointer is \fIxmFormWidgetClass\fP. .PP The class name is \fIXmForm\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in .ne 10 either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmForm Resource Set Name Class Type Default Access _ XmNfractionBase XmCMaxValue int 100 CSG XmNhorizontalSpacing XmCSpacing Dimension 0 CSG XmNrubberPositioning XmCRubberPositioning Boolean False CSG XmNverticalSpacing XmCSpacing Dimension 0 CSG .TE .KE .in .sp 1 .IP "\fIXmNfractionBase\fP" Specifies the denominator used in calculating the relative position of a child widget using \fIXmATTACH_POSITION\fP constraints. The value must not be 0. .PP If the value of a child's \fIXmNleftAttachment\fP (or \fIXmNrightAttachment\fP) is \fIXmATTACH_POSITION\fP, the position of the left (or right) side of the child is relative to the left side of the Form and is a fraction of the width of the Form. This fraction is the value of the child's \fIXmNleftPosition\fP (or \fIXmNrightPosition\fP) resource divided by the value of the Form's \fIXmNfractionBase\fP. .PP If the value of a child's \fIXmNtopAttachment\fP (or \fIXmNbottomAttachment\fP) is \fIXmATTACH_POSITION\fP, the position of the top (or bottom) side of the child is relative to the top side of the Form and is a fraction of the height of the Form. This fraction is the value of the child's \fIXmNtopPosition\fP (or \fIXmNbottomPosition\fP) resource divided by the value of the Form's \fIXmNfractionBase\fP. .nL .ne 15 .IP "\fIXmNhorizontalSpacing\fP" Specifies the offset for right and left attachments. This resource is only used if no offset resource is specified (when attaching to a widget), or if no margin resource is specified (when attaching to the Form). .IP "\fIXmNrubberPositioning\fP" Indicates the default near (left) and top attachments for a child of the Form. (\fINote:\fP Whether this resource actually applies to the left or right side of the child and its attachment may depend on the value of the \fIXmNstringDirection\fP resource.) .PP The default left attachment is applied whenever initialization or \fIXtSetValues\fP leaves the child without either a left or right attachment. The default top attachment is applied whenever initialization or \fIXtSetValues\fP leaves the child without either a top or bottom attachment. .P If this Boolean resource is set to False, \fIXmNleftAttachment\fP and \fIXmNtopAttachment\fP default to \fIXmATTACH_FORM\fP, \fIXmNleftOffset\fP defaults to the current \fBx\fP value of the left side of the child, and \fIXmNtopOffset\fP defaults to the current \fBy\fP value of the child. The effect is to position the child according to its absolute distance from the left or top side of the Form. .PP If this resource is set to True, \fIXmNleftAttachment\fP and \fIXmNtopAttachment\fP default to \fIXmATTACH_POSITION\fP, \fIXmNleftPosition\fP defaults to a value proportional to the current \fBx\fP value of the left side of the child divided by the width of the Form, and \fIXmNtopPosition\fP defaults to a value proportional to the current \fBy\fP value of the child divided by the height of the Form. The effect is to position the child relative to the left or top side of the Form and in proportion to the width or height of the Form. .IP "\fIXmNverticalSpacing\fP" Specifies the offset for top and bottom attachments. This resource is only used if no offset resource is specified (when attaching to a widget), or if no margin resource is specified (when attaching to the Form). .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmForm Constraint Resource Set Name Class Type Default Access _ XmNbottomAttachment XmCAttachment unsigned char XmATTACH_NONE CSG XmNbottomOffset XmCOffset int 0 CSG XmNbottomPosition XmCAttachment int 0 CSG XmNbottomWidget XmCWidget Widget NULL CSG XmNleftAttachment XmCAttachment unsigned char XmATTACH_NONE CSG XmNleftOffset XmCOffset int 0 CSG XmNleftPosition XmCAttachment int 0 CSG XmNleftWidget XmCWidget Widget NULL CSG XmNresizable XmCBoolean Boolean True CSG XmNrightAttachment XmCAttachment unsigned char XmATTACH_NONE CSG XmNrightOffset XmCOffset int 0 CSG XmNrightPosition XmCAttachment int 0 CSG XmNrightWidget XmCWidget Widget NULL CSG XmNtopAttachment XmCAttachment unsigned char XmATTACH_NONE CSG .wH .tH XmNtopOffset XmCOffset int 0 CSG XmNtopPosition XmCAttachment int 0 CSG XmNtopWidget XmCWidget Widget NULL CSG .TE .KE .in .sp 1 .wH .in .IP "\fIXmNbottomAttachment\fP" Specifies attachment of the bottom side of the child. It can have the following values: .wH .rS .TP \(bu \fIXmATTACH_NONE\fP \- Do not attach the bottom side of the child. .TP \(bu \fIXmATTACH_FORM\fP \- Attach the bottom side of the child to the bottom side of the Form. .TP \(bu \fIXmATTACH_OPPOSITE_FORM\fP \- Attach the bottom side of the child to the top side of the Form. \fIXmNbottomOffset\fP can be used to determine the visibility of the child. .TP \(bu \fIXmATTACH_WIDGET\fP \- Attach the bottom side of the child to the top side of the widget or gadget specified in the \fIXmNbottomWidget\fP resource. If \fIXmNbottomWidget\fP is NULL, \fIXmATTACH_WIDGET\fP is replaced by \fIXmATTACH_FORM\fP, and the child is attached to the bottom side of the Form. .TP \(bu \fIXmATTACH_OPPOSITE_WIDGET\fP \- Attach the bottom side of the child to the bottom side of the widget or gadget specified in the \fIXmNbottomWidget\fP resource. .nL .ne 20 .TP \(bu \fIXmATTACH_POSITION\fP \- Attach the bottom side of the child to a position that is relative to the top side of the Form and in proportion to the height of the Form. This position is determined by the \fIXmNbottomPosition\fP and \fIXmNfractionBase\fP resources. .TP \(bu \fIXmATTACH_SELF\fP \- Attach the bottom side of the child to a position that is proportional to the current \fBy\fP value of the bottom of the child divided by the height of the Form. This position is determined by the \fIXmNbottomPosition\fP and \fIXmNfractionBase\fP resources. .ne 4 \fIXmNbottomPosition\fP is set to a value proportional to the current \fBy\fP value of the bottom of the child divided by the height of the Form. .wH .rE .IP "\fIXmNbottomOffset\fP" Specifies the constant offset between the bottom side of the child and the object to which it is attached. The relationship established remains, regardless of any resizing operations that occur. When this resource is explicitly set, the value of \fIXmNverticalSpacing\fP is ignored. .IP "\fIXmNbottomPosition\fP" This resource is used to determine the position of the bottom side of the child when the child's \fIXmNbottomAttachment\fP is set to \fIXmATTACH_POSITION\fP. In this case the position of the bottom side of the child is relative to the top side of the Form and is a fraction of the height of the Form. This fraction is the value of the child's \fIXmNbottomPosition\fP resource divided by the value of the Form's \fIXmNfractionBase\fP. For example, if the child's \fIXmNbottomPosition\fP is 50, the Form's \fIXmNfractionBase\fP is 100, and the Form's height is 200, the position of the bottom side of the child is 100. .IP "\fIXmNbottomWidget\fP" Specifies the widget or gadget to which the bottom side of the child is attached. This resource is used if \fIXmNbottomAttachment\fP is set to either \fIXmATTACH_WIDGET\fP or \fIXmATTACH_OPPOSITE_WIDGET\fP. .PP A string-to-widget resource converter is automatically installed for use with this resource. With this converter, the widget that is to be the value of the resource must exist at the time the widget that has the resource is created. .nL .ne 15 .IP "\fIXmNleftAttachment\fP" Specifies attachment of the near (left) side of the child. (\fINote:\fP Whether this resource actually applies to the left or right side of the child and its attachment may depend on the value of the \fIXmNstringDirection\fP resource.) It can have the following values: .wH .rS .TP \(bu \fIXmATTACH_NONE\fP \- Do not attach the left side of the child. If \fIXmNrightAttachment\fP is also \fIXmATTACH_NONE\fP, this value is ignored and the child is given a default left attachment. .TP \(bu \fIXmATTACH_FORM\fP \- Attach the left side of the child to the left side of the Form. .TP \(bu \fIXmATTACH_OPPOSITE_FORM\fP \- Attach the left side of the child to the right side of the Form. \fIXmNleftOffset\fP can be used to determine the visibility of the child. .TP \(bu \fIXmATTACH_WIDGET\fP \- Attach the left side of the child to the right side of the widget or gadget specified in the \fIXmNleftWidget\fP resource. If \fIXmNleftWidget\fP is NULL, \fIXmATTACH_WIDGET\fP is replaced by \fIXmATTACH_FORM\fP, and the child is attached to the left side of the Form. .TP \(bu \fIXmATTACH_OPPOSITE_WIDGET\fP \- Attach the left side of the child to the left side of the widget or gadget specified in the \fIXmNleftWidget\fP resource. .TP \(bu \fIXmATTACH_POSITION\fP \- Attach the left side of the child to a position that is relative to the left side of the Form and in proportion to the width of the Form. This position is determined by the \fIXmNleftPosition\fP and \fIXmNfractionBase\fP resources. .TP \(bu \fIXmATTACH_SELF\fP \- Attach the left side of the child to a position that is proportional to the current \fBx\fP value of the left side of the child divided by the width of the Form. This position is determined by the \fIXmNleftPosition\fP and \fIXmNfractionBase\fP resources. .ne 6 \fIXmNleftPosition\fP is set to a value proportional to the current \fBx\fP value of the left side of the child divided by the width of the Form. .wH .rE .ne 15 .IP "\fIXmNleftOffset\fP" Specifies the constant offset between the near (left) side of the child and the object to which it is attached. (\fINote:\fP Whether this resource actually applies to the left or right side of the child and its attachment may depend on the value of the \fIXmNstringDirection\fP resource.) The relationship established remains, regardless of any resizing operations that occur. When this resource is explicitly set, the value of \fIXmNhorizontalSpacing\fP is ignored. .IP "\fIXmNleftPosition\fP" This resource is used to determine the position of the near (left) side of the child when the child's \fIXmNleftAttachment\fP is set to \fIXmATTACH_POSITION\fP. (\fINote:\fP Whether this resource actually applies to the left or right side of the child and its attachment may depend on the value of the \fIXmNstringDirection\fP resource.) .PP In this case the position of the left side of the child is relative to the left side of the Form and is a fraction of the width of the Form. This fraction is the value of the child's \fIXmNleftPosition\fP resource divided by the value of the Form's \fIXmNfractionBase\fP. For example, if the child's \fIXmNleftPosition\fP is 50, the Form's \fIXmNfractionBase\fP is 100, and the Form's width is 200, the position of the left side of the child is 100. .IP "\fIXmNleftWidget\fP" Specifies the widget or gadget to which the near (left) side of the child is attached. (\fINote:\fP Whether this resource actually applies to the left or right side of the child and its attachment may depend on the value of the \fIXmNstringDirection\fP resource.) This resource is used if \fIXmNleftAttachment\fP is set to either \fIXmATTACH_WIDGET\fP or \fIXmATTACH_OPPOSITE_WIDGET\fP. .PP A string-to-widget resource converter is automatically installed for use with this resource. With this converter, the widget that is to be the value of the resource must exist at the time the widget that has the resource is created. .nL .ne 4 .IP "\fIXmNresizable\fP" This Boolean resource specifies whether or not a child's request for a new size is (conditionally) granted by the Form. If this resource is set to True the request is granted if possible. If this resource is set to False the request is always refused. .PP If a child has both left and right attachments, its width is completely controlled by the Form, regardless of the value of the child's \fIXmNresizable\fP resource. If a child has a left or right attachment but not both, the child's \fIXmNwidth\fP is used in setting its width if the value of the child's \fIXmNresizable\fP resource is True. These conditions are also true for top and bottom attachments, with height acting like width. .IP "\fIXmNrightAttachment\fP" Specifies attachment of the far (right) side of the child. (\fINote:\fP Whether this resource actually applies to the left or right side of the child and its attachment may depend on the value of the \fIXmNstringDirection\fP resource.) It can have the following values: .wH .rS .TP \(bu \fIXmATTACH_NONE\fP \- Do not attach the right side of the child. .TP \(bu \fIXmATTACH_FORM\fP \- Attach the right side of the child to the right side of the Form. .TP \(bu \fIXmATTACH_OPPOSITE_FORM\fP \- Attach the right side of the child to the left side of the Form. \fIXmNrightOffset\fP can be used to determine the visibility of the child. .TP \(bu \fIXmATTACH_WIDGET\fP \- Attach the right side of the child to the left side of the widget or gadget specified in the \fIXmNrightWidget\fP resource. If \fIXmNrightWidget\fP is NULL, \fIXmATTACH_WIDGET\fP is replaced by \fIXmATTACH_FORM\fP, and the child is attached to the right side of the Form. .TP \(bu \fIXmATTACH_OPPOSITE_WIDGET\fP \- Attach the right side of the child to the right side of the widget or gadget specified in the \fIXmNrightWidget\fP resource. .nL .ne 4 .TP \(bu \fIXmATTACH_POSITION\fP \- Attach the right side of the child to a position that is relative to the left side of the Form and in proportion to the width of the Form. This position is determined by the \fIXmNrightPosition\fP and \fIXmNfractionBase\fP resources. .TP \(bu \fIXmATTACH_SELF\fP \- Attach the right side of the child to a position that is proportional to the current \fBx\fP value of the right side of the child divided by the width of the Form. This position is determined by the \fIXmNrightPosition\fP and \fIXmNfractionBase\fP resources. \fIXmNrightPosition\fP is set to a value proportional to the current \fBx\fP value of the right side of the child divided by the width of the Form. .wH .rE .IP "\fIXmNrightOffset\fP" Specifies the constant offset between the far (right) side of the child and the object to which it is attached. (\fINote:\fP Whether this resource actually applies to the left or right side of the child and its attachment may depend on the value of the \fIXmNstringDirection\fP resource.) The relationship established remains, regardless of any resizing operations that occur. When this resource is explicitly set, the value of \fIXmNhorizontalSpacing\fP is ignored. .IP "\fIXmNrightPosition\fP" This resource is used to determine the position of the far (right) side of the child when the child's \fIXmNrightAttachment\fP is set to \fIXmATTACH_POSITION\fP. (\fINote:\fP Whether this resource actually applies to the left or right side of the child and its attachment may depend on the value of the \fIXmNstringDirection\fP resource.) .PP In this case the position of the right side of the child is relative to the left side of the Form and is a fraction of the width of the Form. This fraction is the value of the child's \fIXmNrightPosition\fP resource divided by the value of the Form's \fIXmNfractionBase\fP. For example, if the child's \fIXmNrightPosition\fP is 50, the Form's \fIXmNfractionBase\fP is 100, and the Form's width is 200, the position of the right side of the child is 100. .nL .ne 5 .IP "\fIXmNrightWidget\fP" Specifies the widget or gadget to which the far (right) side of the child is attached. (\fINote:\fP Whether this resource actually applies to the left or right side of the child and its attachment may depend on the value of the \fIXmNstringDirection\fP resource.) This resource is used if \fIXmNrightAttachment\fP is set to either \fIXmATTACH_WIDGET\fP or \fIXmATTACH_OPPOSITE_WIDGET\fP. .PP A string-to-widget resource converter is automatically installed for use with this resource. With this converter, the widget that is to be the value of the resource must exist at the time the widget that has the resource is created. .IP "\fIXmNtopAttachment\fP" Specifies attachment of the top side of the child. It can have following values: .wH .rS .TP \(bu \fIXmATTACH_NONE\fP \- Do not attach the top side of the child. If \fIXmNbottomAttachment\fP is also \fIXmATTACH_NONE\fP, this value is ignored and the child is given a default top attachment. .TP \(bu \fIXmATTACH_FORM\fP \- Attach the top side of the child to the top side of the Form. .TP \(bu \fIXmATTACH_OPPOSITE_FORM\fP \- Attach the top side of the child to the bottom side of the Form. \fIXmNtopOffset\fP can be used to determine the visibility of the child. .TP \(bu \fIXmATTACH_WIDGET\fP \- Attach the top side of the child to the bottom side of the widget or gadget specified in the \fIXmNtopWidget\fP resource. If \fIXmNtopWidget\fP is NULL, \fIXmATTACH_WIDGET\fP is replaced by \fIXmATTACH_FORM\fP, and the child is attached to the top side of the Form. .TP \(bu \fIXmATTACH_OPPOSITE_WIDGET\fP \- Attach the top side of the child to the top side of the widget or gadget specified in the \fIXmNtopWidget\fP resource. .TP \(bu \fIXmATTACH_POSITION\fP \- Attach the top side of the child to a position that is relative to the top side of the Form and in proportion to the height of the Form. This position is determined by the \fIXmNtopPosition\fP and \fIXmNfractionBase\fP resources. .nL .ne 10 .TP \(bu \fIXmATTACH_SELF\fP \- Attach the top side of the child to a position that is proportional to the current \fBy\fP value of the child divided by the height of the Form. This position is determined by the \fIXmNtopPosition\fP and \fIXmNfractionBase\fP resources. \fIXmNtopPosition\fP is set to a value proportional to the current \fBy\fP value of the child divided by the height of the Form. .wH .rE .IP "\fIXmNtopOffset\fP" Specifies the constant offset between the top side of the child and the object to which it is attached. The relationship established remains, regardless of any resizing operations that occur. When this resource is explicitly set, the value of \fIXmNverticalSpacing\fP is ignored. .IP "\fIXmNtopPosition\fP" This resource is used to determine the position of the top side of the child when the child's \fIXmNtopAttachment\fP is set to \fIXmATTACH_POSITION\fP. In this case the position of the top side of the child is relative to the top side of the Form and is a fraction of the height of the Form. This fraction is the value of the child's \fIXmNtopPosition\fP resource divided by the value of the Form's \fIXmNfractionBase\fP. For example, if the child's \fIXmNtopPosition\fP is 50, the Form's \fIXmNfractionBase\fP is 100, and the Form's height is 200, the position of the top side of the child is 100. .IP "\fIXmNtopWidget\fP" Specifies the widget or gadget to which the top side of the child is attached. This resource is used if \fIXmNtopAttachment\fP is set to either \fIXmATTACH_WIDGET\fP or \fIXmATTACH_OPPOSITE_WIDGET\fP. .PP A string-to-widget resource converter is automatically installed for use with this resource. With this converter, the widget that is to be the value of the resource must exist at the time the widget that has the resource is created. .SS "Inherited Resources" Form inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmBulletinBoard Resource Set Name Class Type Default Access _ XmNallowOverlap XmCAllowOverlap Boolean True CSG XmNautoUnmanage XmCAutoUnmanage Boolean True CG XmNbuttonFontList XmCButtonFontList XmFontList dynamic CSG XmNcancelButton XmCWidget Widget NULL SG XmNdefaultButton XmCWidget Widget NULL SG XmNdefaultPosition XmCDefaultPosition Boolean True CSG XmNdialogStyle XmCDialogStyle unsigned char dynamic CSG XmNdialogTitle XmCDialogTitle XmString NULL CSG XmNfocusCallback XmCCallback XtCallbackList NULL C XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG XmNmapCallback XmCCallback XtCallbackList NULL C XmNmarginHeight XmCMarginHeight Dimension 0 CSG XmNmarginWidth XmCMarginWidth Dimension 0 CSG XmNnoResize XmCNoResize Boolean False CSG .wH .tH XmNresizePolicy XmCResizePolicy unsigned char XmRESIZE_ANY CSG XmNshadowType XmCShadowType unsigned char XmSHADOW_OUT CSG XmNtextFontList XmCTextFontList XmFontList dynamic CSG XmNtextTranslations XmCTranslations XtTranslations NULL C XmNunmapCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmManager Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget dynamic CSG XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension dynamic CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic N/A XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Translations" XmForm inherits translations from XmBulletinBoard. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fIConstraint(3X)\fP, \fICore(3X)\fP, \fIXmBulletinBoard(3X)\fP, \fIXmCreateForm\fP, \fIXmCreateFormDialog(3X)\fP, and \fIXmManager(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmFrame 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmFrame\fP \- The Frame widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi Frame is a very simple manager used to enclose a single work area child in a border drawn by Frame. It uses the Manager class resources for border drawing and performs geometry management so that its size always matches its child's outer size plus the Frame's margins and shadow thickness. .PP Frame is most often used to enclose other managers when the application developer desires the manager to have the same border appearance as the primitive widgets. Frame can also be used to enclose primitive widgets that do not support the same type of border drawing. This gives visual consistency when you develop applications using diverse widget sets. Constraint resources are used to designate a child as the Frame title, align its text, and control its vertical alignment in relation to Frame's top shadow. The title appears only at the top of the Frame. .PP If the Frame's parent is a Shell widget, \fIXmNshadowType\fP defaults to \fIXmSHADOW_OUT\fP, and Manager's resource \fIXmNshadowThickness\fP defaults to 1. .P If the Frame's parent is not a Shell widget, \fIXmNshadowType\fP defaults to \fIXmSHADOW_ETCHED_IN\fP, and Manager's resource \fIXmNshadowThickness\fP defaults to 2. .SS "Classes" Frame inherits behavior and resources from the \fICore\fP, \fIComposite\fP, \fIConstraint\fP, and \fIXmManager\fP classes. .PP The class pointer is \fIxmFrameWidgetClass\fP. .PP The class name is \fIXmFrame\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmFrame Resource Set Name Class Type Default Access _ XmNmarginWidth XmCMarginWidth Dimension 0 CSG XmNmarginHeight XmCMarginHeight Dimension 0 CSG XmNshadowType XmCShadowType unsigned char dynamic CSG .TE .KE .in .sp 1 .nL .ne 6 .IP "\fIXmNmarginWidth\fP" Specifies the padding space on the left and right sides between Frame's child and Frame's shadow drawing. .IP "\fIXmNmarginHeight\fP" Specifies the padding space on the top and bottom sides between Frame's child and Frame's shadow drawing. When a title is present, the top margin equals the value specified by this resource plus the distance (if any) that the title extends below the top shadow. .IP "\fIXmNshadowType\fP" Describes the drawing style for Frame. This resource can have the following values: .TP \(bu \fIXmSHADOW_IN\fP \- draws Frame so that it appears inset. This means that the bottom shadow visuals and top shadow visuals are reversed. .TP \(bu \fIXmSHADOW_OUT\fP \- draws Frame so that it appears outset. This is the default if Frame's parent is a Shell widget. .TP \(bu \fIXmSHADOW_ETCHED_IN\fP \- draws Frame using a double line giving the effect of a line etched into the window. The thickness of the double line is equal to the value of \fIXmNshadowThickness\fP. This is the default when Frame's parent is not a Shell widget. .TP \(bu \fIXmSHADOW_ETCHED_OUT\fP \- draws Frame using a double line giving the effect of a line coming out of the window. The thickness of the double line is equal to the value of \fIXmNshadowThickness\fP. .PP .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmFrame Constraint Resource Set Name Class Type Default Access _ XmNchildType XmCChildType unsigned char XmFRAME_WORKAREA_CHILD CSG XmNchildHorizontalAlignment XmCChildHorizontalAlignment unsigned char XmALIGNMENT_BEGINNING CSG XmNchildHorizontalSpacing XmCChildHorizontalSpacing Dimension dynamic CSG XmNchildVerticalAlignment XmCChildVerticalAlignment unsigned char XmALIGNMENT_CENTER CSG .TE .KE .in .sp 1 .wH .in .IP "\fIXmNchildType\fP" Specifies whether a child is a title or work area. Frame supports a single title and/or work area child. The possible values are: .TP \(bu \fIXmFRAME_TITLE_CHILD\fP .TP \(bu \fIXmFRAME_WORKAREA_CHILD\fP .TP \(bu \fIXmFRAME_GENERIC_CHILD\fP .PP The Frame geometry manager ignores any child of type \fIXmFRAME_GENERIC_CHILD\fP. .IP "\fIXmNchildHorizontalAlignment\fP" Specifies the alignment of the title. This resource has the following values: .TP \(bu \fIXmALIGNMENT_BEGINNING\fP .TP \(bu \fIXmALIGNMENT_CENTER\fP .TP \(bu \fIXmALIGNMENT_END\fP .PP See the description of \fIXmNalignment\fP in the \fIXmLabel\fP man page for an explanation of these values. .IP "\fIXmNchildHorizontalSpacing\fP" Specifies the minimum distance between either edge of the title text and the inner edge of the Frame shadow. Clipping of the title text occurs in order to maintain this spacing. The default value is the margin width of the Frame. .IP "\fIXmNchildVerticalAlignment\fP" Specifies the vertical alignment of the title text, or the title area in relation to the top shadow of the Frame. .TP \(bu \fIXmALIGNMENT_BASELINE_BOTTOM\fP \- causes the baseline of the title to align vertically with the top shadow of the Frame. In the case of a multi-line title, the baseline of the last line of text aligns vertically with the top shadow of the Frame. .TP \(bu \fIXmALIGNMENT_BASELINE_TOP\fP \- causes the baseline of the first line of the title to align vertically with the top shadow of the Frame. .TP \(bu \fIXmALIGNMENT_WIDGET_TOP\fP \- causes the top edge of the title area to align vertically with the top shadow of the Frame. .TP \(bu \fIXmALIGNMENT_CENTER\fP \- causes the center of the title area to align vertically with the top shadow of the Frame. .TP \(bu \fIXmALIGNMENT_WIDGET_BOTTOM\fP \- causes the bottom edge of the title area to align vertically with the top shadow of the Frame. .SS "Inherited Resources" Frame inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmManager Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget NULL CSG XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension dynamic CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Translations" XmFrame inherits translations from XmManager. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fIConstraint(3X)\fP, \fICore(3X)\fP, \fIXmCreateFrame(3X)\fP, and \fIXmManager(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGadget\fP \- The Gadget widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi Gadget is a widget class used as a supporting superclass for other gadget classes. It handles shadow-border drawing and highlighting, traversal activation and deactivation, and various callback lists needed by gadgets. .PP The color and pixmap resources defined by XmManager are directly used by gadgets. If \fIXtSetValues\fP is used to change one of the resources for a manager widget, all of the gadget children within the manager also change. .SS "Classes" Gadget inherits behavior and resources from \fIObject\fP and \fIRectObj\fP classes. .PP The class pointer is \fIxmGadgetClass\fP. .PP The class name is \fIXmGadget\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmGadget Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic G XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic G XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic G XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .nL .ne 8 .IP "\fIXmNbottomShadowColor\fP" Contains the color to use to draw the bottom and right sides of the border shadow. .IP "\fIXmNhelpCallback\fP" Specifies the list of callbacks that is called when the help key sequence is pressed. The reason sent by the callback is \fIXmCR_HELP\fP. .IP "\fIXmNhighlightColor\fP" Contains the color of the highlighting rectangle. .IP "\fIXmNhighlightOnEnter\fP" Specifies if the highlighting rectangle is drawn when the cursor moves into the widget. If the shell's focus policy is \fIXmEXPLICIT\fP, this resource is ignored, and the widget is highlighted when it has the focus. If the shell's focus policy is \fIXmPOINTER\fP and if this resource is True, the highlighting rectangle is drawn when the the cursor moves into the widget. If the shell's focus policy is \fIXmPOINTER\fP and if this resource is False, the highlighting rectangle is not drawn when the the cursor moves into the widget. The default is False. .IP "\fIXmNhighlightThickness\fP" Specifies the thickness of the highlighting rectangle. .IP "\fIXmNnavigationType\fP" Determines whether the widget is a tab group. .wH .rS .TP \(bu \fIXmNONE\fP indicates that the widget is not a tab group. .TP \(bu \fIXmTAB_GROUP\fP indicates that the widget is a tab group, unless another widget in the hierarchy has an \fIXmNnavigationType\fP of \fIXmEXCLUSIVE_TAB_GROUP\fP. .TP \(bu \fIXmSTICKY_TAB_GROUP\fP indicates that the widget is a tab group, even if another widget in the hierarchy has an \fIXmNnavigationType\fP of \fIXmEXCLUSIVE_TAB_GROUP\fP. .TP \(bu \fIXmEXCLUSIVE_TAB_GROUP\fP indicates that the widget is a tab group and that widgets in the hierarchy whose \fIXmNnavigationType\fP is \fIXmTAB_GROUP\fP are not tab groups. .PP When a parent widget has an \fIXmNnavigationType\fP of \fIXmEXCLUSIVE_TAB_GROUP\fP, traversal of non-tab-group widgets within the group is based on the order of those widgets in their parent's \fIXmNchildren\fP list. .PP When any widget in a hierarchy has an \fIXmNnavigationType\fP of \fIXmEXCLUSIVE_TAB_GROUP\fP, traversal of tab groups in the hierarchy proceeds to widgets in the order in which their \fIXmNnavigationType\fP resources were specified as \fIXmEXCLUSIVE_TAB_GROUP\fP or \fIXmSTICKY_TAB_GROUP\fP, whether by creating the widgets with that value, by calling \fIXtSetValues\fP, or by calling \fIXmAddTabGroup\fP. .wH .rE .nL .ne 8 .IP "\fIXmNshadowThickness\fP" Specifies the size of the drawn border shadow. .IP "\fIXmNtopShadowColor\fP" Contains the color to use to draw the top and left sides of the border shadow. .IP "\fIXmNtraversalOn\fP" Specifies traversal activation for this gadget. .IP "\fIXmNunitType\fP" Provides the basic support for resolution independence. It defines the type of units a widget uses with sizing and positioning resources. If the widget's parent is a subclass of \fIXmManager\fP and if the \fIXmNunitType\fP resource is not explicitly set, it defaults to the unit type of the parent widget. If the widget's parent is not a subclass of \fIXmManager\fP, the resource has a default unit type of \fIXmPIXELS\fP. .PP \fIXmNunitType\fP can have the following values: .wH .rS .TP \(bu \fIXmPIXELS\fP \- all values provided to the widget are treated as normal pixel values. .TP \(bu \fIXm100TH_MILLIMETERS\fP \- all values provided to the widget are treated as 1/100 millimeter. .TP \(bu \fIXm1000TH_INCHES\fP \- all values provided to the widget are treated as 1/1000 inch. .TP \(bu \fIXm100TH_POINTS\fP \- all values provided to the widget are treated as 1/100 point. A point is a unit used in text processing applications and is defined as 1/72 inch. .TP \(bu \fIXm100TH_FONT_UNITS\fP \- all values provided to the widget are treated as 1/100 of a font unit. A font unit has horizontal and vertical components. These are the values of the XmScreen resources \fIXmNhorizontalFontUnit\fP and \fIXmNverticalFontUnit\fP. .wH .rE .IP "\fIXmNuserData\fP" Allows the application to attach any necessary specific data to the gadget. This is an internally unused resource. .nL .ne 10 .SS "Inherited Resources" Gadget inherits the following resources from the named superclass. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. RectObj Resource Set Name Class Type Default Access _ XmNancestorSensitive XmCSensitive Boolean dynamic G XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNheight XmCHeight Dimension dynamic CSG XmNsensitive XmCSensitive Boolean True CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Object Resource Set Name Class Type Default Access _ XmNdestroyCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.50i .nf typedef struct { int \fBreason\fI; \fIXEvent \fB* event\fI; } XmAnyCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. For this callback, \fBreason\fP is set to \fIXmCR_HELP\fP. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .nL .ne 12 .SS "Behavior" Gadgets cannot have translations associated with them. Because of this, a Gadget's behavior is determined by the Manager widget into which the Gadget is placed. If focus is on a Gadget, events are passed to the Gadget by its Manager. .nL .ne 4 .SH RELATED INFORMATION .na \fIObject(3X)\fP, \fIRectObj(3X)\fP, \fIXmManager(3X)\fP, and \fIXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetAtomName 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetAtomName\fP \- A function that returns the string representation for an atom .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu String XmGetAtomName (\fBdisplay, atom\fI) .ta .5i 1.5i .nf Display \fB* display\fI; Atom \fBatom\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmGetAtomName\fP returns the string representation for an atom. It mirrors the \fIXlib\fP interfaces for atom management but provides client-side caching. When and where caching is provided in \fIXlib\fP, the routines will become pseudonyms for the \fIXlib\fP routines. .IP "\fBdisplay\fP" Specifies the connection to the X server .IP "\fBatom\fP" Specifies the atom for the property name you want returned .SH RETURN VALUE Returns a string. ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetColorCalculation 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetColorCalculation\fP \- A function to get the procedure used for default color calculation .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmColorProc XmGetColorCalculation () .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmGetColorCalculation\fP returns the procedure being used to calculate default colors. .PP For a description of \fIXmColorProc\fP, see \fIXmSetColorCalculation(3X)\fP. .SH RETURN VALUE Returns the procedure used for default color calculation. .SH RELATED INFORMATION .na \fIXmChangeColor(3X)\fP, \fIXmGetColors(3X)\fP, and \fIXmSetColorCalculation(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetColors 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetColors\fP \- A function that generates foreground, select, and shadow colors .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf void XmGetColors (\fBscreen, colormap, background, foreground, top_shadow, bottom_shadow, select\fI) .ta .5i 1.5i .nf Screen \fB* screen\fI; Colormap \fBcolormap\fI; Pixel \fBbackground\fI; Pixel \fB* foreground\fI; Pixel \fB* top_shadow\fI; Pixel \fB* bottom_shadow\fI; Pixel \fB* select\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmGetColors\fP takes a screen, a colormap, and a background pixel, and it returns pixel values for foreground, select, and shadow colors. .IP "\fBscreen\fP" Specifies the screen for which these colors should be allocated .IP "\fBcolormap\fP" Specifies the colormap from which these colors should be allocated .IP "\fBbackground\fP" Specifies the background on which the colors should be based .IP "\fBforeground\fP" Specifies a pointer to the returned foreground pixel value. If this argument is NULL no value is allocated or returned for this color. .IP "\fBtop_shadow\fP" Specifies a pointer to the returned top shadow pixel value. If this argument is NULL no value is allocated or returned for this color. .IP "\fBbottom_shadow\fP" Specifies a pointer to the returned bottom shadow pixel value. If this argument is NULL no value is allocated or returned for this color. .IP "\fBselect\fP" Specifies a pointer to the returned select pixel value. If this argument is NULL no value is allocated or returned for this color. .SH RELATED INFORMATION .na \fIXmChangeColor(3X)\fP, \fIXmGetColorCalculation(3X)\fP, and \fIXmSetColorCalculation(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetDestination 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetDestination\fP \- A function that returns the widget ID of the widget to be used as the current destination for quick paste and certain clipboard operations .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmGetDestination (\fBdisplay\fI) .ta .5i 1.5i .nf Display \fB*display\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmGetDestination\fP returns the widget that is the current destination on the specified display. The destination is generally the last editable widget on which a select, edit, insert, or paste operation was performed and is the destination for quick paste and certain clipboard functions. The destination is NULL if the application makes this call before any of the specified operations have been performed on an editable widget. .IP "\fBdisplay\fP" Specifies the display whose destination widget is to be queried .SH RETURN VALUE Returns the widget ID for the current destination or NULL if there is no current destination. .P ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetDragContext 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetDragContext\fP \- A Drag and Drop function that retrieves the DragContext widget ID associated with a timestamp .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmGetDragContext (\fBrefwidget, timestamp\fI) .ta .5i 1.75i .nf Widget \fBrefwidget\fI; Time \fBtimestamp\fI; .iE .sE .SH DESCRIPTION .fi \fIXmGetDragContext\fP returns the widget ID of the active DragContext associated with a given display and timestamp. A timestamp uniquely identifies which DragContext is active when more than one drag and drop transaction has been initiated on a display. If the specified timestamp matches a timestamp processed between the start and finish of a single drag and drop transaction, the function returns the corresponding DragContext ID. .IP "\fBrefwidget\fP" Specifies the ID of the widget that the routine uses to identify the intended display. The function returns the ID of the DragContext associated with the display value passed by this widget. .IP "\fBtimestamp\fP" Specifies a timestamp. .PP For a complete definition of DragContext and its associated resources, see \fIXmDragContext(3X)\fP. .SH RETURN VALUE Returns the ID of the DragContext widget that is active for the specified timestamp. Otherwise, returns NULL if no active DragContext is found. .SH RELATED INFORMATION .na \fIXmDragContext(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetFocusWidget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetFocusWidget\fP \- Returns the ID of the widget that has keyboard focus .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmGetFocusWidget (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .iE .sE .SH DESCRIPTION .fi \fIXmGetFocusWidget\fP examines the hierarchy that contains the specified widget and returns the ID of the widget that has keyboard focus. The function extracts the widget ID from the associated Shell widget; therefore the specified widget can be located anywhere in the hierarchy. .IP "\fBwidget\fP" Specifies a widget ID within a given hierarchy .SH RETURN VALUE Returns the ID of the widget with keyboard focus. If no child of the Shell has focus, the function returns NULL. .SH RELATED INFORMATION .na \fIXmProcessTraversal(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetMenuCursor 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetMenuCursor\fP \- A function that returns the cursor ID for the current menu cursor .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Cursor XmGetMenuCursor (\fBdisplay\fI) .ta .5i 1.5i .nf Display \fB* display\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmGetMenuCursor\fP queries the menu cursor currently being used by this client on the specified display and returns the cursor ID. .PP This function returns the menu cursor for the default screen of the display. \fIXmGetMenuCursor\fP is obsolete and exists for compatibility with previous releases. Instead of using this function, call \fIXtGetValues\fP for the XmScreen resource \fIXmNmenuCursor\fP. .IP "\fBdisplay\fP" Specifies the display whose menu cursor is to be queried .P .ne 12 .SH RETURN VALUE Returns the cursor ID for the current menu cursor or the value None if a cursor is not yet defined. A cursor will not be defined if the application makes this call before the client has created any menus on the specified display. .SH RELATED INFORMATION .na \fIXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Novell, Inc. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetPixmap 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetPixmap\fP \- A pixmap caching function that generates a pixmap, stores it in a pixmap cache, and returns the pixmap .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Pixmap XmGetPixmap (\fBscreen, image_name, foreground, background\fI) .ta .5i 1.5i .nf Screen *\fBscreen\fI; char *\fBimage_name\fI; Pixel \fBforeground\fI; Pixel \fBbackground\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmGetPixmap\fP uses the parameter data to perform a lookup in the pixmap cache to see if a pixmap has already been generated that matches the data. If one is found, a reference count is incremented and the pixmap is returned. Applications should use \fIXmDestroyPixmap\fP when the pixmap is no longer needed. .PP If a pixmap is not found, \fBimage_name\fP is used to perform a lookup in the image cache. If an image is found, it is used to generate the pixmap, which is then cached and returned. .PP If an image is not found, \fBimage_name\fP is used as a filename, and a search is made for either an xpm pixmap file or an \fIX10\fP or \fIX11\fP bitmap file. If it is found, the file is read, converted into an image, and cached in the image cache. The image is then used to generate a pixmap, which is cached and returned. .PP If \fBimage_name\fP has a leading slash (\fI/\fP), it specifies a full pathname, and \fIXmGetPixmap\fP opens the file as specified. Otherwise, \fBimage_name\fP specifies a filename. In this case, \fIXmGetPixmap\fP looks for the file along the following search paths, specified by \fIXMICONSEARCHPATH\fP or \fIXMICONBMSEARCHPATH\fP depending on the type of display, \fIXBMLANGPATH\fP and a default search path, which varies depending on whether or not the \fIXAPPLRESDIR\fP environment variable is set. The order of the search, is \fIXMICONSEARCHPATH\fP or \fIXMICONBMSEARCHPATH\fP first, \fIXBMLANGPATH\fP second, \fIXAPPLRESDIR\fP third, and finally the vendor default search path (see below), until either the file is found or the paths are all visited. .PP Both the environment variables \fIXMICONSEARCHPATH\fP and \fIXMICONBMSEARCHPATH\fP specify a search path for xpm pixmap and X bitmap files. \fIXmGetPixmap\fP uses \fIXMICONSEARCHPATH\fP on a color display and \fIXMICONBMSEARCHPATH\fP on a monolithic one. The type of the display is determined automatically through the use of Xm/ColorObj. So \fIXMICONSEARCHPATH\fP should consist of a path where locations of xpm files precede those of bitmap files, and \fIXMICONBMSEARCHPATH\fP should maintain a search path in favor of bitmap files. These two search paths are new in CDE Motif and will be in Motif 2.0. The \fIXBMLANGPATH\fP environment variable, which is here for backward compatibility with Motif 1.x, specifies a search path only for X bitmap files. All these variables can contain the substitution field %B, where the \fBimage_name\fP argument to \fIXmGetPixmap\fP is substituted for %B. They can also contain the substitution fields accepted by \fIXtResolvePathname\fP. The substitution field %T is always mapped to \fIbitmaps\fP, and %S is always mapped to NULL. .PP If neither \fIXMICONSEARCHPATH\fP (\fIXMICONBMSEARCHPATH\fP if monolithic) nor \fIXBMLANGPATH\fP is set but the environment variable \fIXAPPLRESDIR\fP is set, the following pathnames are searched: .iS .ta 1i .nf %B $XAPPLRESDIR/%L/bitmaps/%N/%B $XAPPLRESDIR/%l/bitmaps/%N/%B $XAPPLRESDIR/bitmaps/%N/%B $XAPPLRESDIR/%L/bitmaps/%B $XAPPLRESDIR/%l/bitmaps/%B $XAPPLRESDIR/bitmaps/%B $HOME/bitmaps/%B $HOME/%B /usr/lib/X11/%L/bitmaps/%N/%B /usr/lib/X11/%l/bitmaps/%N/%B /usr/lib/X11/bitmaps/%N/%B /usr/lib/X11/%L/bitmaps/%B /usr/lib/X11/%l/bitmaps/%B /usr/lib/X11/bitmaps/%B /usr/include/X11/bitmaps/%B .wH .fi .iE .PP If none of the above paths is set, the following pathnames are searched: .iS .ta 1i .nf %B $HOME/%L/bitmaps/%N/%B $HOME/%l/bitmaps/%N/%B $HOME/bitmaps/%N/%B $HOME/%L/bitmaps/%B $HOME/%l/bitmaps/%B $HOME/bitmaps/%B $HOME/%B /usr/lib/X11/%L/bitmaps/%N/%B /usr/lib/X11/%l/bitmaps/%N/%B /usr/lib/X11/bitmaps/%N/%B /usr/lib/X11/%L/bitmaps/%B /usr/lib/X11/%l/bitmaps/%B /usr/lib/X11/bitmaps/%B /usr/include/X11/bitmaps/%B .wH .fi .iE .PP These paths are defaults that vendors may change. For example, a vendor may use different directories for \fI/usr/lib/X11\fP and \fI/usr/include/X11\fP. .PP The following substitutions are used in these paths: .IP "\fI%B\fP" The image name, from the \fBimage_name\fP argument. .IP "\fI%N\fP" The class name of the application. .IP "\fI%L\fP" The display's language string. .IP "\fI%l\fP" The language component of the display's language string. .PP Parameter descriptions are listed below: .IP "\fBscreen\fP" Specifies the display screen on which the pixmap is to be drawn. The depth of the pixmap is the default depth for this screen. .IP "\fBimage_name\fP" Specifies the name of the image to be used to generate the pixmap .IP "\fBforeground\fP" Combines the image with the \fBforeground\fP color to create the pixmap if the image referenced is a bit-per-pixel image .IP "\fBbackground\fP" Combines the image with the \fBbackground\fP color to create the pixmap if the image referenced is a bit-per-pixel image .SH RETURN VALUE Returns a pixmap when successful; returns \fIXmUNSPECIFIED_PIXMAP\fP if the image corresponding to the \fBimage_name\fP cannot be found. .SH RELATED INFORMATION .na \fIXmDestroyPixmap(3X)\fP, \fIXmGetPixmapByDepth(3X)\fP, \fIXmInstallImage(3X)\fP, and \fIXmUninstallImage(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc. ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetPixmapByDepth 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetPixmapByDepth\fP \- A pixmap caching function that generates a pixmap, stores it in a pixmap cache, and returns the pixmap .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Pixmap XmGetPixmapByDepth (\fBscreen, image_name,foreground, background, depth\fI) .ta .5i 1.5i .nf Screen *\fBscreen\fI; char *\fBimage_name\fI; Pixel \fBforeground\fI; Pixel \fBbackground\fI; int \fBdepth\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmGetPixmapByDepth\fP uses the parameter data to perform a lookup in the pixmap cache to see if a pixmap has already been generated that matches the data. If one is found, a reference count is incremented and the pixmap is returned. Applications should use \fIXmDestroyPixmap\fP when the pixmap is no longer needed. .PP If a matching pixmap is not found, \fBimage_name\fP is used to perform a lookup in the image cache. If an image is found, it is used to generate the pixmap, which is then cached and returned. .PP If an image is not found, \fBimage_name\fP is used as a filename, and a search is made for either an xpm pixmap file or an \fIX10\fP or \fIX11\fP bitmap file. If it is found, the file is read, converted into an image, and cached in the image cache. The image is then used to generate a pixmap, which is cached and returned. .PP If \fBimage_name\fP has a leading slash (\fI/\fP), it specifies a full pathname, and \fIXmGetPixmapByDepth\fP opens the file as specified. Otherwise, \fBimage_name\fP specifies a filename. In this case, \fIXmGetPixmapByDepth\fP looks for the file along the following search paths, specified by \fIXMICONSEARCHPATH\fP or \fIXMICONBMSEARCHPATH\fP depending on the type of display, \fIXBMLANGPATH\fP and a default search path, which varies depending on whether or not the \fIXAPPLRESDIR\fP environment variable is set. The order of the search, is \fIXMICONSEARCHPATH\fP or \fIXMICONBMSEARCHPATH\fP first, \fIXBMLANGPATH\fP second, \fIXAPPLRESDIR\fP third, and finally the vendor default search path (see below), until either the file is found or the paths are all visited. .PP Both the environment variables \fIXMICONSEARCHPATH\fP and \fIXMICONBMSEARCHPATH\fP specify a search path for xpm pixmap and X bitmap files. \fIXmGetPixmapByDepth\fP uses \fIXMICONSEARCHPATH\fP on a color display and \fIXMICONBMSEARCHPATH\fP on a monolithic one. The type of the display is determined automatically through the use of Xm/ColorObj. So \fIXMICONSEARCHPATH\fP should consist of a path where locations of xpm files precede those of bitmap files, and \fIXMICONBMSEARCHPATH\fP should maintain a search path in favor of bitmap files. These two environment variables are new in CDE Motif and will be in Motif 2.0. The \fIXBMLANGPATH\fP environment variable, which is here for backward compatibility with Motif 1.x, specifies a search path only for X bitmap files. All these variables can contain the substitution field %B, where the \fBimage_name\fP argument to \fIXmGetPixmapByDepth\fP is substituted for %B. They can also contain the substitution fields accepted by \fIXtResolvePathname\fP. The substitution field %T is always mapped to \fIbitmaps\fP, and %S is always mapped to NULL. .PP If neither \fIXMICONSEARCHPATH\fP (\fIXMICONBMSEARCHPATH\fP if monolithic) nor \fIXBMLANGPATH\fP is set but the environment variable \fIXAPPLRESDIR\fP is set, the following pathnames are searched: .iS .ta 1i .nf %B $XAPPLRESDIR/%L/bitmaps/%N/%B $XAPPLRESDIR/%l/bitmaps/%N/%B $XAPPLRESDIR/bitmaps/%N/%B $XAPPLRESDIR/%L/bitmaps/%B $XAPPLRESDIR/%l/bitmaps/%B $XAPPLRESDIR/bitmaps/%B $HOME/bitmaps/%B $HOME/%B /usr/lib/X11/%L/bitmaps/%N/%B /usr/lib/X11/%l/bitmaps/%N/%B /usr/lib/X11/bitmaps/%N/%B /usr/lib/X11/%L/bitmaps/%B /usr/lib/X11/%l/bitmaps/%B /usr/lib/X11/bitmaps/%B /usr/include/X11/bitmaps/%B .wH .fi .iE .PP If none of the above paths is set, the following pathnames are searched: .iS .ta 1i .nf %B $HOME/%L/bitmaps/%N/%B $HOME/%l/bitmaps/%N/%B $HOME/bitmaps/%N/%B $HOME/%L/bitmaps/%B $HOME/%l/bitmaps/%B $HOME/bitmaps/%B $HOME/%B /usr/lib/X11/%L/bitmaps/%N/%B /usr/lib/X11/%l/bitmaps/%N/%B /usr/lib/X11/bitmaps/%N/%B /usr/lib/X11/%L/bitmaps/%B /usr/lib/X11/%l/bitmaps/%B /usr/lib/X11/bitmaps/%B /usr/include/X11/bitmaps/%B .wH .fi .iE .PP These paths are defaults that vendors may change. For example, a vendor may use different directories for \fI/usr/lib/X11\fP and \fI/usr/include/X11\fP. .PP The following substitutions are used in these paths: .IP "\fI%B\fP" The image name, from the \fBimage_name\fP argument .IP "\fI%N\fP" The class name of the application .IP "\fI%L\fP" The display's language string .IP "\fI%l\fP" The language component of the display's language string .PP Parameter descriptions are listed below: .IP "\fBscreen\fP" Specifies the display screen on which the pixmap is to be drawn .IP "\fBimage_name\fP" Specifies the name of the image to be used to generate the pixmap .IP "\fBforeground\fP" Combines the image with the \fBforeground\fP color to create the pixmap if the image referenced is a bit-per-pixel image .IP "\fBbackground\fP" Combines the image with the \fBbackground\fP color to create the pixmap if the image referenced is a bit-per-pixel image .IP "\fBdepth\fP" Specifies the depth of the pixmap .SH RETURN VALUE Returns a pixmap when successful; returns \fIXmUNSPECIFIED_PIXMAP\fP if the image corresponding to \fBimage_name\fP cannot be found. .SH RELATED INFORMATION .na \fIXmDestroyPixmap(3X)\fP, \fIXmInstallImage(3X)\fP, and \fIXmUninstallImage(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetPostedFromWidget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetPostedFromWidget\fP \- A RowColumn function that returns the widget from which a menu was posted .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmGetPostedFromWidget (\fBmenu\fI) .ta .5i 1.5i .nf Widget \fBmenu\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmGetPostedFromWidget\fP returns the widget from which a menu was posted. For torn-off menus, this function returns the widget from which the menu was originally torn. An application can use this routine during the activate callback to determine the context in which the menu callback should be interpreted. .IP "\fBmenu\fP" Specifies the widget ID of the menu .PP For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the widget ID of the widget from which the menu was posted. If the menu is a Popup Menu, the returned widget is the widget from which the menu was popped up. If the menu is a Pulldown Menu, the returned widget is the MenuBar or OptionMenu from which the widget was pulled down. .SH RELATED INFORMATION .na \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** .TH XmGetSecondaryResourceData 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetSecondaryResourceData\fP \- A function that provides access to secondary widget resource data .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Cardinal XmGetSecondaryResourceData (\fBwidget_class, secondary_data_return\fI) .ta .5i 2.5i .nf WidgetClass \fBwidget_class\fI; XmSecondaryResourceData **\fBsecondary_data_return\fI; .iE .sE .SH DESCRIPTION .fi Some Motif widget classes (such as Gadget, Text, and VendorShell) have resources that are not accessible via the functions \fIXtGetResourceList\fP and \fIXtGetConstraintResourceList\fP. In order to retrieve the descriptions of these resources, an application must use \fIXmGetSecondaryResourceData\fP. .PP When a widget class has such resources, this function provides descriptions of the resources in one or more data structures. \fIXmGetSecondaryResourceData\fP takes a widget class argument and returns the number of these data structures associated with the widget class. If the return value is greater than 0, the function allocates and fills an array of pointers to the corresponding data structures. It returns this array at the address that is the value of the \fBsecondary_data_return\fP argument. .PP The type \fIXmSecondaryResourceData\fP is a pointer to a structure with two members that are useful to an application: \fBresources\fP, of type \fIXtResourceList\fP, and \fBnum_resources\fP, of type \fICardinal\fP. The \fBresources\fP member is a list of the widget resources that are not accessible using Xt functions. The \fBnum_resources\fP member is the length of the \fBresources\fP list. .PP If the return value is greater than 0, \fIXmGetSecondaryResourceData\fP allocates memory that the application must free. Use \fIXtFree\fP to free the resource list in each structure (the value of the \fBresources\fP member), the structures themselves, and the array of pointers to the structures (the array whose address is \fBsecondary_data_return\fP). .IP "\fBwidget_class\fP" Specifies the widget class for which secondary resource data is to be retrieved. .IP "\fBsecondary_data_return\fP" Specifies a pointer to an array of \fIXmSecondaryResourceData\fP pointers to be returned by this function. If the widget class has no secondary resource data (i.e., if the value returned by the function is 0), the function returns no meaningful value for this argument. .SH RETURN VALUE Returns the number of secondary resource data structures associated with this widget class. .SH EXAMPLE The following example uses \fIXmGetSecondaryResourceData\fP to print the names of the secondary resources of the Motif Text widget and then frees the data allocated by the function: .oS XmSecondaryResourceData * block_array ; Cardinal num_blocks, i, j ; if (num_blocks = XmGetSecondaryResourceData (xmTextWidgetClass, &block_array)) { for (i = 0; i < num_blocks; i++) { for (j = 0 ; j < block_array[i]->num_resources; j++) { printf("%s\en", block_array[i]->resources[j].resource_name); } XtFree((char*)block_array[i]->resources); XtFree((char*)block_array[i]); } XtFree((char*)block_array); } .oE ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetTabGroup 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetTabGroup\fP \- Returns the widget ID of a tab group .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmGetTabGroup (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .iE .sE .SH DESCRIPTION .fi \fIXmGetTabGroup\fP returns the widget ID of the tab group that contains the specified widget. .IP "\fBwidget\fP" Specifies a widget ID within a tab group .SH RETURN VALUE Returns the widget ID of a tab group or shell, determined as follows: .TP \(bu If \fBwidget\fP is a tab group or shell, returns \fBwidget\fP .TP \(bu If neither \fBwidget\fP nor any ancestor up to the nearest shell is a tab group, returns the nearest ancestor of \fBwidget\fP that is a shell .TP \(bu Otherwise, returns the nearest ancestor of \fBwidget\fP that is a tab group .SH RELATED INFORMATION .na \fIXmAddTabGroup(3X)\fP, \fIXmManager(3X)\fP, and \fIXmPrimitive(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetTearOffControl 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetTearOffControl\fP \- A RowColumn function that obtains the widget ID for the tear-off control in a menu .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmGetTearOffControl (\fBmenu\fI) .ta .5i 1.5i .nf Widget \fBmenu\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmGetTearOffControl\fP provides the application with the means for obtaining the widget ID of the internally created tear-off control in a tear-off menu. .PP RowColumn creates a tear-off control for a PulldownMenu or PopupMenu when the \fIXmNtearOffModel\fP resource is initialized or set to \fIXmTEAR_OFF_ENABLED\fP. The tear-off control is a widget that appears as the first element in the menu. The user tears off the menu by means of mouse or keyboard events in the tear-off control. .PP The tear-off control has Separator-like behavior. Once the application has obtained the widget ID of the tear-off control, it can set resources to specify the appearance of the control. The application or user can also set these resources in a resource file by using the name of the control, which is "TearOffControl". For a list of the resources the application or user can set, see \fIXmRowColumn(3X)\fP. .IP "\fBmenu\fP" Specifies the widget ID of the RowColumn PulldownMenu or PopupMenu .PP For more information on tear-off menus and a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the widget ID for the tear-off control, or NULL if no tear-off control exists. An application should not assume that the returned widget will be of any particular class. .SH RELATED INFORMATION .na \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetVisibility 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetVisibility\fP \- A function that determines if a widget is visible .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmVisibility XmGetVisibility (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .iE .sE .SH DESCRIPTION .fi \fIXmGetVisibility\fP returns the visibility state of the specified widget. .IP "\fBwidget\fP" Specifies the ID of the widget .SH RETURN VALUE Returns one of the following values: .TP \(bu \fIXmVISIBILITY_UNOBSCURED\fP .TP \(bu \fIXmVISIBILITY_PARTIALLY_OBSCURED\fP .TP \(bu \fIXmVISIBILITY_FULLY_OBSCURED\fP .SH RELATED INFORMATION .na \fIXmIsTraversable(3X)\fP, \fIXmManager(3X)\fP, and \fIXmProcessTraversal(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetXmDisplay 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetXmDisplay\fP \- A Display function that returns the \fIXmDisplay\fP object ID for a specified display .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmGetXmDisplay (\fBdisplay\fI) .ta .5i 1.75i .nf Display *\fBdisplay\fI; .iE .sE .SH DESCRIPTION .fi \fIXmGetXmDisplay\fP returns the \fIXmDisplay\fP object ID associated with a display. The application can access Display resources by using \fIXtGetValues\fP. .IP "\fBdisplay\fP" Specifies the display for which the \fIXmDisplay\fP object ID is to be returned .PP For a complete definition of Display and its associated resources, see \fIXmDisplay(3X)\fP. .SH RETURN VALUE Returns the \fIXmDisplay\fP object ID for the specified display. .SH RELATED INFORMATION .na \fIXmDisplay(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmGetXmScreen 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmGetXmScreen\fP \- A Screen function that returns the \fIXmScreen\fP object ID for a specified screen .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmGetXmScreen (\fBscreen\fI) .ta .5i 1.75i .nf Screen *\fBscreen\fI; .iE .sE .SH DESCRIPTION .fi \fIXmGetXmScreen\fP returns the \fIXmScreen\fP object ID associated with a screen. The application can access and manipulate Screen resources by using \fIXtGetValues\fP and \fIXtSetValues\fP. .IP "\fBscreen\fP" Specifies the screen for which the \fIXmScreen\fP ID is to be returned .PP For a complete definition of Screen and its associated resources, see \fIXmScreen(3X)\fP. .SH RETURN VALUE Returns the \fIXmScreen\fP object ID. .SH RELATED INFORMATION .na \fIXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmInstallImage 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmInstallImage\fP \- A pixmap caching function that adds an image to the pixmap cache .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmInstallImage (\fBimage, image_name\fI) .ta .5i 1.5i .nf XImage \fB* image\fI; char \fB* image_name\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmInstallImage\fP stores an image in an image cache that can later be used to generate a pixmap. Part of the installation process is to extend the resource converter used to reference these images. The resource converter is given the image name so that the image can be referenced in a .Xdefaults file. Since an image can be referenced by a widget through its pixmap resources, it is up to the application to ensure that the image is installed before the widget is created. .IP "\fBimage\fP" Points to the image structure to be installed. The installation process does not make a local copy of the image. Therefore, the application should not destroy the image until it is uninstalled from the caching functions. .IP "\fBimage_name\fP" Specifies a string that the application uses to name the image. After installation, this name can be used in .Xdefaults for referencing the image. A local copy of the name is created by the image caching functions. .PP The image caching functions provide a set of eight preinstalled images. These names can be used within a \fI.Xdefaults\fP file for generating pixmaps for the resource for which they are provided. .PP .sp 1 .in 0 .KS .TS center; lB lB ll. Image Name Description _ background A tile of solid background 25_foreground A tile of 25% foreground, 75% background 50_foreground A tile of 50% foreground, 50% background 75_foreground A tile of 75% foreground, 25% background horizontal A tile of horizontal lines of the two colors vertical A tile of vertical lines of the two colors slant_right A tile of slanting lines of the two colors slant_left A tile of slanting lines of the two colors .TE .KE .in .sp 1 .SH RETURN VALUE Returns True when successful; returns False if NULL \fBimage\fP, NULL \fBimage_name\fP, or duplicate \fBimage_name\fP is used as a parameter value. .SH RELATED INFORMATION .na \fIXmUninstallImage(3X)\fP, \fIXmGetPixmap(3X)\fP, and \fIXmDestroyPixmap(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmInternAtom 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmInternAtom\fP \- A function that returns an atom for a given name .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu Atom XmInternAtom (\fBdisplay, name, only_if_exists\fI) .ta .5i 1.5i .nf Display \fB* display\fI; String \fBname\fI; Boolean \fBonly_if_exists\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmInternAtom\fP returns an atom for a given name. It mirrors the \fIXlib\fP interfaces for atom management, but provides client-side caching. When and where caching is provided in \fIXlib\fP, the routines will become pseudonyms for the \fIXlib\fP routines. .nL .ne 15 .IP "\fBdisplay\fP" Specifies the connection to the X server .IP "\fBname\fP" Specifies the name associated with the atom you want returned .IP "\fBonly_if_exists\fP" Specifies a Boolean value that indicates whether \fIXInternAtom\fP creates the atom .SH RETURN VALUE Returns an atom. ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmIsMotifWMRunning 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmIsMotifWMRunning\fP \- A function that determines whether the window manager is running .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmIsMotifWMRunning (\fBshell\fI) .ta .5i 1.5i .nf Widget \fBshell\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmIsMotifWMRunning\fP lets a user know whether the Motif Window Manager is running on a screen that contains a specific widget hierarchy. This function first sees whether the \fI_MOTIF_WM_INFO\fP property is present on the root window of the shell's screen. If it is, its window field is used to query for the presence of the specified window as a child of root. .IP "\fBshell\fP" Specifies the shell whose screen will be tested for \fImwm\fP's presence. .nL .ne 5 .SH RETURN VALUE Returns True if MWM is running. ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmIsTraversable 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmIsTraversable\fP \- A function that identifies whether a widget can be traversed .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmIsTraversable (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .iE .sE .SH DESCRIPTION .fi \fIXmIsTraversable\fP determines whether the specified widget is eligible to receive focus through keyboard traversal. In general, a widget is eligible to receive focus when all of the following conditions are true: .TP \(bu The widget and its ancestors are not being destroyed, are sensitive, and have a value of True for \fIXmNtraversalOn\fP. .TP \(bu The widget and its ancestors are realized, managed, and (except for gadgets) mapped. .TP \(bu Some part of the widget's rectangular area is unobscured by the widget's ancestors, or some part of the widget's rectangular area is inside the work window (but possibly outside the clip window) of a ScrolledWindow whose \fIXmNscrollingPolicy\fP is \fIXmAUTOMATIC\fP and whose \fIXmNtraverseObscuredCallback\fP is not NULL. .PP Some widgets may not be eligible to receive focus even if they meet all these conditions. For example, most managers cannot receive focus through keyboard traversal. Some widgets may be eligible to receive focus under particular conditions. For example, a DrawingArea is eligible to receive focus if it meets the conditions above and has no child whose \fIXmNtraversalOn\fP resource is True. .IP "\fBwidget\fP" Specifies the ID of the widget .SH RETURN VALUE Returns True if the widget is eligible to receive focus through keyboard traversal; otherwise, returns False. .SH RELATED INFORMATION .na \fIXmGetVisibility(3X)\fP and \fIXmProcessTraversal(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmLabel 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmLabel\fP \- The Label widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi Label is an instantiable widget and is also used as a superclass for other button widgets, such as PushButton and ToggleButton. The Label widget does not accept any button or key input, and the help callback is the only callback defined. Label also receives enter and leave events. .PP Label can contain either text or a pixmap. Label text is a compound string. Refer to the \fBOSF/Motif Programmer's Guide\fP for more information on compound strings. The text can be multilingual, multiline, and/or multifont. When a Label is insensitive, its text is stippled, or the user-supplied insensitive pixmap is displayed. .PP Label supports both accelerators and mnemonics primarily for use in Label subclass widgets that are contained in menus. Mnemonics are available in a menu system when the button is visible. Accelerators in a menu system are accessible even when the button is not visible. The Label widget displays the mnemonic by underlining the first matching character in the text string. The accelerator is displayed as a text string adjacent to the label text or pixmap. .PP Label consists of many margin fields surrounding the text or pixmap. These margin fields are resources that may be set by the user, but Label subclasses and Manager parents also modify some of these fields. They tend to modify the \fIXmNmarginLeft\fP, \fIXmNmarginRight\fP, \fIXmNmarginTop\fP, and \fIXmNmarginBottom\fP resources and leave the \fIXmNmarginWidth\fP and \fIXmNmarginHeight\fP resources as set by the application. .PP Label takes into account \fIXmNshadowThickness\fP in determining its layout but does not draw the shadow. That is, if \fIXmNshadowThickness\fP is greater than 0, Label leaves space for the shadow, but the shadow does not appear. .PP In a Label \fIXmNtraversalOn\fP and \fIXmNhighlightOnEnter\fP are forced to False inside Popup MenuPanes, Pulldown MenuPanes, and OptionMenus. Otherwise these resources default to False. .SS "Classes" Label inherits behavior and resources from \fICore\fP and \fIXmPrimitive\fP Classes. .PP The class pointer is \fIxmLabelWidgetClass\fP. .PP The class name is \fIXmLabel\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmLabel Resource Set Name Class Type Default Access _ XmNaccelerator XmCAccelerator String NULL CSG XmNacceleratorText XmCAcceleratorText XmString NULL CSG XmNalignment XmCAlignment unsigned char dynamic CSG XmNfontList XmCFontList XmFontList dynamic CSG XmNlabelInsensitivePixmap XmCLabelInsensitivePixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelPixmap XmCLabelPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelString XmCXmString XmString dynamic CSG XmNlabelType XmCLabelType unsigned char XmSTRING CSG XmNmarginBottom XmCMarginBottom Dimension 0 CSG XmNmarginHeight XmCMarginHeight Dimension 2 CSG XmNmarginLeft XmCMarginLeft Dimension 0 CSG XmNmarginRight XmCMarginRight Dimension 0 CSG XmNmarginTop XmCMarginTop Dimension 0 CSG XmNmarginWidth XmCMarginWidth Dimension 2 CSG .wH .tH XmNmnemonic XmCMnemonic KeySym NULL CSG XmNmnemonicCharSet XmCMnemonicCharSet String XmFONTLIST_DEFAULT_TAG CSG XmNrecomputeSize XmCRecomputeSize Boolean True CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CSG .TE .KE .in .sp 1 .wH .in .IP "\fIXmNaccelerator\fP" Sets the accelerator on a button widget in a menu, which activates a visible or invisible, but managed, button from the keyboard. This resource is a string that describes a set of modifiers and the key that may be used to select the button. The format of this string is identical to that used by the translations manager, with the exception that only a single event may be specified and only \fIKeyPress\fP events are allowed. .PP Accelerators for buttons are supported only for PushButtons and ToggleButtons in Pulldown and Popup MenuPanes. .IP "\fIXmNacceleratorText\fP" Specifies the text displayed for the accelerator. The text is displayed adjacent to the label string or pixmap. Accelerator text for buttons is displayed only for PushButtons and ToggleButtons in Pulldown and Popup Menus. .IP "\fIXmNalignment\fP" Specifies the label alignment for text or pixmap. .wH .rS .TP \(bu \fIXmALIGNMENT_BEGINNING\fP (left alignment) \- causes the left sides of the lines of text to be vertically aligned with the left edge of the widget window. For a pixmap, its left side is vertically aligned with the left edge of the widget window. .TP \(bu \fIXmALIGNMENT_CENTER\fP (center alignment) \- causes the centers of the lines of text to be vertically aligned .ne 5 in the center of the widget window. For a pixmap, its center is vertically aligned with the center of the widget window. .TP \(bu \fIXmALIGNMENT_END\fP (right alignment) \- causes the right sides of the lines of text to be vertically aligned with the right edge of the widget window. For a pixmap, its right side is vertically aligned with the right edge of the widget window. .wH .rE .PP The above descriptions for text are correct when \fIXmNstringDirection\fP is \fIXmSTRING_DIRECTION_L_TO_R\fP. When that resource is \fIXmSTRING_DIRECTION_R_TO_L\fP, the descriptions for \fIXmALIGNMENT_BEGINNING\fP and \fIXmALIGNMENT_END\fP are switched. .PP If the parent is a RowColumn whose \fIXmNisAligned\fP resource is True, \fIXmNalignment\fP is forced to the same value as the RowColumn's \fIXmNentryAlignment\fP if the RowColumn's \fIXmNrowColumnType\fP is \fIXmWORK_AREA\fP or if the widget is a subclass of XmLabel. Otherwise, the default is \fIXmALIGNMENT_CENTER\fP. .IP "\fIXmNfontList\fP" Specifies the font of the text used in the widget. If this value is NULL at initialization, the font list is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard, VendorShell, or XmMenuShell widget class. If such an ancestor is found, the font list is initialized to the \fIXmNbuttonFontList\fP (for button subclasses) or \fIXmNlabelFontList\fP of the ancestor widget. If no such ancestor is found, the default is implementation dependent. Refer to \fIXmFontList(3X)\fP for more information on the creation and structure of a font list. .IP "\fIXmNlabelInsensitivePixmap\fP" Specifies a pixmap used as the button face if \fIXmNlabelType\fP is \fIXmPIXMAP\fP and the button is insensitive. The default value, \fIXmUNSPECIFIED_PIXMAP\fP, displays an empty label. .IP "\fIXmNlabelPixmap\fP" Specifies the pixmap when \fIXmNlabelType\fP is \fIXmPIXMAP\fP. The default value, \fIXmUNSPECIFIED_PIXMAP\fP, displays an empty label. .IP "\fIXmNlabelString\fP" Specifies the compound string when the \fIXmNlabelType\fP is \fIXmSTRING\fP. If this value is NULL, it is initialized by converting the name of the widget to a compound string. Refer to \fIXmString(3X)\fP for more information on the creation and structure of compound strings. .IP "\fIXmNlabelType\fP" Specifies the label type. .wH .rS .TP \(bu \fIXmSTRING\fP \- displays text using \fIXmNlabelString\fP. .TP \(bu \fIXmPIXMAP\fP \- displays pixmap using \fIXmNlabelPixmap\fP or \fIXmNlabelInsensitivePixmap\fP. .wH .rE .IP "\fIXmNmarginBottom\fP" Specifies the amount of spacing between the bottom of the label text and the top of the bottom margin specified by \fIXmNmarginHeight\fP. This may be modified by Label's subclasses. For example, CascadeButton may increase this field to make room for the cascade pixmap. .IP "\fIXmNmarginHeight\fP" Specifies an equal amount of spacing above the margin defined by \fIXmNmarginTop\fP and below the margin defined by \fIXmNmarginBottom\fP. \fIXmNmarginHeight\fP specifies the amount of spacing between the top edge of the margin set by \fIXmNmarginTop\fP and the bottom edge of the top shadow, and the amount of spacing between the bottom edge of the margin specified by \fIXmNmarginBottom\fP and the top edge of the bottom shadow. .IP "\fIXmNmarginLeft\fP" Specifies the amount of spacing between the left edge of the label text and the right side of the left margin (specified by \fIXmNmarginWidth\fP). This may be modified by Label's subclasses. For example, ToggleButton may increase this field to make room for the toggle indicator and for spacing between the indicator and label. Whether this actually applies to the left or right side of the label may depend on the value of \fIXmNstringDirection\fP. .IP "\fIXmNmarginRight\fP" Specifies the amount of spacing between the right edge of the label text and the left side of the right margin (specified by \fIXmNmarginWidth\fP). This may be modified by Label's subclasses. For example, CascadeButton may increase this field to make room for the cascade pixmap. Whether this actually applies to the left or right side of the label may depend on the value of \fIXmNstringDirection\fP. .nL .ne 6 .IP "\fIXmNmarginTop\fP" Specifies the amount of spacing between the top of the label text and the bottom of the top margin specified by \fIXmNmarginHeight\fP. This may be modified by Label's subclasses. For example, CascadeButton may increase this field to make room for the cascade pixmap. .IP "\fIXmNmarginWidth\fP" Specifies an equal amount of spacing to the left of the margin defined by \fIXmNmarginLeft\fP and to the right of the margin defined by \fIXmNmarginRight\fP. \fIXmNmarginWidth\fP specifies the amount of spacing between the left edge of the margin set by \fIXmNmarginLeft\fP and the right edge of the left shadow, and the amount of spacing between the right edge of the margin specified by \fIXmNmarginRight\fP and the left edge of the right shadow. .IP "\fIXmNmnemonic\fP" Provides the user with an alternate means of activating a button. A button in a MenuBar, a Popup MenuPane, or a Pulldown MenuPane can have a mnemonic. .PP This resource contains a keysym as listed in the X11 keysym table. The first character in the label string that exactly matches the mnemonic in the character set specified in \fIXmNmnemonicCharSet\fP is underlined when the button is displayed. .PP When a mnemonic has been specified, the user activates the button by pressing the mnemonic key while the button is visible. If the button is a CascadeButton in a MenuBar and the MenuBar does not have the focus, the user must use the \fIMAlt\fP modifier while pressing the mnemonic. The user can activate the button by pressing either the shifted or the unshifted mnemonic key. .IP "\fIXmNmnemonicCharSet\fP" Specifies the character set of the mnemonic for the label. The default is \fIXmFONTLIST_DEFAULT_TAG\fP. .nL .ne 15 .IP "\fIXmNrecomputeSize\fP" Specifies a Boolean value that indicates whether the widget shrinks or expands to accommodate its contents (label string or pixmap) as a result of an \fIXtSetValues\fP resource value that would change the size of the widget. If True, the widget shrinks or expands to exactly fit the label string or pixmap. If False, the widget never attempts to change size on its own. .IP "\fIXmNstringDirection\fP" Specifies the direction in which the string is to be drawn. The following are the values: .TP \(bu \fIXmSTRING_DIRECTION_L_TO_R\fP \- left to right .TP \(bu \fIXmSTRING_DIRECTION_R_TO_L\fP \- right to left .PP The default for this resource is determined at creation time. If no value is specified for this resource and the widget's parent is a manager, the value is inherited from the parent; otherwise, it defaults to \fIXmSTRING_DIRECTION_L_TO_R\fP. .SS "Inherited Resources" Label inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPrimitive Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNhighlightThickness XmCHighlightThickness Dimension 0 CSG .wH .tH XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension 0 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean False CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Translations" .ne 15 XmLabel includes translations from Primitive. The XmLabel translations are listed below. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BDrag Press: ProcessDrag() .sp \n(PDu KHelp: Help() .wH .fi .iE The translations used by subclasses of XmLabel for menu traversal are listed below. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf KLeft: MenuTraverseLeft() KRight: MenuTraverseRight() KUp: MenuTraverseUp() KDown: MenuTraverseDown() MAny KCancel: MenuEscape() .wH .fi .iE .SS "Action Routines" The XmLabel action routines are described below: .IP "\fIHelp()\fP:" In a Popup or Pulldown MenuPane, unposts all menus in the menu hierarchy and, when the shell's keyboard focus policy is \fIXmEXPLICIT\fP, restores keyboard focus to the widget that had the focus before the menu system was entered. Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIMenuEscape()\fP:" In a MenuBar, disarms the CascadeButton and the menu and, when the shell's keyboard focus policy is \fIXmEXPLICIT\fP, restores keyboard focus to the widget that had the focus before the menu was entered. .nL .ne 15 .IP In a toplevel Pulldown MenuPane from a MenuBar, unposts the menu, disarms the MenuBar CascadeButton and the MenuBar, and, when the shell's keyboard focus policy is \fIXmEXPLICIT\fP, restores keyboard focus to the widget that had the focus before the MenuBar was entered. In other Pulldown MenuPanes, unposts the menu and moves the focus to its CascadeButton. .IP In a Popup MenuPane, unposts the menu and, when the shell's keyboard focus policy is \fIXmEXPLICIT\fP, restores keyboard focus to the widget from which the menu was posted. .IP "\fIMenuTraverseDown()\fP:" If the current menu item has a submenu and is in a MenuBar, then this action posts the submenu, disarms the current menu item, and arms the submenu's first traversable menu item. .IP If the current menu item is in a MenuPane, then this action disarms the current menu item and arms the item below it. This action wraps within the MenuPane. When the current menu item is at the MenuPane's bottom edge, then this action wraps to the topmost menu item in the column to the right, if one exists. When the current menu item is at the bottom, rightmost corner of the MenuPane, then this action wraps to the tear-off control, if present, or to the top, leftmost menu item. .IP "\fIMenuTraverseLeft()\fP:" When the current menu item is in a MenuBar, then this action disarms the current item and arms the MenuBar item to the left. This action wraps within the MenuBar. .IP In MenuPanes, if the current menu item is not at the left edge of a MenuPane, this action disarms the current item and arms the item to its left. If the current menu item is at the left edge of a submenu attached to a MenuBar item, then this action unposts the submenu and traverses to the MenuBar item to the left, wrapping if necessary. If that MenuBar item has a submenu, it posts the submenu and arms the first traversable item in the submenu. If the current menu item is at the left edge of a submenu not directly attached to a MenuBar item, then this action unposts the current submenu only. .IP In Popup or Torn-off MenuPanes, when the current menu item is at the left edge, this action wraps within the MenuPane. If the current menu item is at the left edge of the MenuPane and not in the top row, this action wraps to the rightmost menu item in the row above. If the current menu item is in the upper, leftmost corner, this action wraps to the tear-off control, if present, or else it wraps to the bottom, rightmost menu item in the MenuPane. .nL .ne 5 .IP "\fIMenuTraverseRight()\fP:" If the current menu item is in a MenuBar, then this action disarms the current item and arms the MenuBar item to the right. This action wraps within the MenuBar. .IP In MenuPanes, if the current menu item is a CascadeButton, then this action posts its associated submenu. If the current menu item is not a CascadeButton and is not at the right edge of a MenuPane, this action disarms the current item and arms the item to its right, wrapping if necessary. If the current menu item is not a CascadeButton and is at the right edge of a submenu that is a descendent of a MenuBar, then this action unposts all submenus and traverses to the MenuBar item to the right. If that MenuBar item has a submenu, it posts the submenu and arms the submenu's first traversable item. .IP In Popup or Torn-off menus, if the current menu item is not a CascadeButton and is at the right edge of a row (except the bottom row), this action wraps to the leftmost menu item in the row below. If the current menu item is not a CascadeButton and is in the bottom, rightmost corner of a Popup or Pulldown MenuPane, this action wraps to the tear-off control, if present, or else it wraps to the top, leftmost menu item of the MenuPane. .IP "\fIMenuTraverseUp()\fP:" When the current menu item is in a MenuPane, then this action disarms the current menu item and arms the item above it. This action wraps within the MenuPane. When the current menu item is at the MenuPane's top edge, then this action wraps to the bottommost menu item in the column to the left, if one exists. When the current menu item is at the top, leftmost corner of the MenuPane, then this action wraps to the tear-off control, if present, or to the bottom, rightmost menu item. .IP "\fIProcessDrag()\fP:" Drags the contents of a Label, identified by pressing \fIBDrag\fP. This action creates a DragContext object whose \fIXmNexportTargets\fP resource is set to "COMPOUND_TEXT" for a label type of \fIXmSTRING\fP; otherwise, "PIXMAP" if the label type is \fIXmPIXMAP\fP. This action is undefined for Labels used in a menu system. .IP This action is disabled if the XmDisplay's \fIenableUnselectableDrag\fP resource is True. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fICore(3X)\fP, \fIXmCreateLabel(3X)\fP, \fIXmDisplay(3X)\fP, \fIXmFontListAppendEntry(3X)\fP, \fIXmStringCreate(3X)\fP, \fIXmStringCreateLtoR(3X)\fP, and \fIXmPrimitive(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmLabelGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmLabelGadget\fP \- The LabelGadget widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi LabelGadget is an instantiable widget and is also used as a superclass for other button gadgets, such as PushButtonGadget and ToggleButtonGadget. .PP LabelGadget can contain either text or a pixmap. LabelGadget text is a compound string. Refer to the \fBOSF/Motif Programmer's Guide\fP for more information on compound strings. The text can be multilingual, multiline, and/or multifont. When a LabelGadget is insensitive, its text is stippled, or the user-supplied insensitive pixmap is displayed. .PP LabelGadget supports both accelerators and mnemonics primarily for use in LabelGadget subclass widgets that are contained in menus. Mnemonics are available in a menu system when the button is visible. Accelerators in a menu system are accessible even when the button is not visible. The LabelGadget displays the mnemonic by underlining the first matching character in the text string. The accelerator is displayed as a text string adjacent to the label text or pixmap. .PP LabelGadget consists of many margin fields surrounding the text or pixmap. These margin fields are resources that may be set by the user, but LabelGadget subclasses and Manager parents also modify some of these fields. They tend to modify the \fIXmNmarginLeft\fP, \fIXmNmarginRight\fP, \fIXmNmarginTop\fP, and \fIXmNmarginBottom\fP resources and leave the \fIXmNmarginWidth\fP and \fIXmNmarginHeight\fP resources as set by the application. .PP LabelGadget takes into account \fIXmNshadowThickness\fP in determining its layout but does not draw the shadow. That is, if \fIXmNshadowThickness\fP is greater than 0, LabelGadget leaves space for the shadow, but the shadow does not appear. .PP In a LabelGadget \fIXmNtraversalOn\fP and \fIXmNhighlightOnEnter\fP are forced to False inside Popup MenuPanes, Pulldown MenuPanes, and OptionMenus. Otherwise these resources default to False. .SS "Classes" LabelGadget inherits behavior and resources from \fIObject\fP, \fIRectObj\fP and \fIXmGadget\fP classes. .PP The class pointer is \fIxmLabelGadgetClass\fP. .PP The class name is \fIXmLabelGadget\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmLabelGadget Resource Set Name Class Type Default Access _ XmNaccelerator XmCAccelerator String NULL CSG XmNacceleratorText XmCAcceleratorText XmString NULL CSG XmNalignment XmCAlignment unsigned char dynamic CSG XmNfontList XmCFontList XmFontList dynamic CSG XmNlabelInsensitivePixmap XmCLabelInsensitivePixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelPixmap XmCLabelPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelString XmCXmString XmString dynamic CSG XmNlabelType XmCLabelType unsigned char XmSTRING CSG XmNmarginBottom XmCMarginBottom Dimension 0 CSG XmNmarginHeight XmCMarginHeight Dimension 2 CSG XmNmarginLeft XmCMarginLeft Dimension 0 CSG XmNmarginRight XmCMarginRight Dimension 0 CSG XmNmarginTop XmCMarginTop Dimension 0 CSG XmNmarginWidth XmCMarginWidth Dimension 2 CSG .wH .tH XmNmnemonic XmCMnemonic KeySym NULL CSG XmNmnemonicCharSet XmCMnemonicCharSet String dynamic CSG XmNrecomputeSize XmCRecomputeSize Boolean True CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CSG .TE .KE .in .sp 1 .wH .in .IP "\fIXmNaccelerator\fP" Sets the accelerator on a button widget in a menu, which activates a visible or invisible, but managed, button from the keyboard. This resource is a string that describes a set of modifiers and the key that may be used to select the button. The format of this string is identical to that used by the translations manager, with the exception that only a single event may be specified and only \fIKeyPress\fP events are allowed. .IP Accelerators for buttons are supported only for PushButtonGadgets and ToggleButtonGadgets in Pulldown and Popup menus. .IP "\fIXmNacceleratorText\fP" Specifies the text displayed for the accelerator. The text is displayed adjacent to the label string or pixmap. Accelerator text for buttons is displayed only for PushButtonGadgets and ToggleButtonGadgets in Pulldown and Popup Menus. .IP "\fIXmNalignment\fP" Specifies the label alignment for text or pixmap. .wH .rS .TP \(bu \fIXmALIGNMENT_BEGINNING\fP (left alignment) \- causes the left sides of the lines of text to be vertically aligned with the left edge of the gadget. For a pixmap, its left side is vertically aligned with the left edge of the gadget. .nL .ne 4 .TP \(bu \fIXmALIGNMENT_CENTER\fP (center alignment) \- causes the centers of the lines of text to be vertically aligned in the center of the gadget. For a pixmap, its center is vertically aligned with the center of the gadget. .TP \(bu \fIXmALIGNMENT_END\fP (right alignment) \- causes the right sides of the lines of text to be vertically aligned with the right edge of the gadget. For a pixmap, its right side is vertically aligned with the right edge of the gadget. .wH .rE .IP The above descriptions for text are correct when \fIXmNstringDirection\fP is \fIXmSTRING_DIRECTION_L_TO_R\fP; the descriptions for \fIXmALIGNMENT_BEGINNING\fP and \fIXmALIGNMENT_END\fP are switched when the resource is \fIXmSTRING_DIRECTION_R_TO_L\fP. .IP If the parent is a RowColumn whose \fIXmNisAligned\fP resource is True, \fIXmNalignment\fP is forced to the same value as the RowColumn's \fIXmNentryAlignment\fP if the RowColumn's \fIXmNrowColumnType\fP is \fIXmWORK_AREA\fP or if the gadget is a subclass of XmLabelGadget. Otherwise, the default is \fIXmALIGNMENT_CENTER\fP. .IP "\fIXmNfontList\fP" Specifies the font of the text used in the gadget. If this value is NULL at initialization, the font list is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard, VendorShell, or XmMenuShell widget class. If such an ancestor is found, the font list is initialized to the \fIXmNbuttonFontList\fP (for button gadget subclasses) or \fIXmNlabelFontList\fP of the ancestor widget. If no such ancestor is found, the default is implementation dependent. Refer to \fIXmFontList(3X)\fP for more information on the creation and structure of a font list. .IP "\fIXmNlabelInsensitivePixmap\fP" Specifies a pixmap used as the button face if \fIXmNlabelType\fP is \fIXmPIXMAP\fP and the button is insensitive. The default value, \fIXmUNSPECIFIED_PIXMAP\fP, displays an empty label. .IP "\fIXmNlabelPixmap\fP" Specifies the pixmap when \fIXmNlabelType\fP is \fIXmPIXMAP\fP. The default value, \fIXmUNSPECIFIED_PIXMAP\fP, displays an empty label. .IP "\fIXmNlabelString\fP" Specifies the compound string when \fIXmNlabelType\fP is \fIXmSTRING\fP. If this value is NULL, it is initialized by converting the name of the gadget to a compound string. Refer to \fIXmString(3X)\fP for more information on the creation and the structure of compound strings. .nL .ne 4 .IP "\fIXmNlabelType\fP" Specifies the label type. .TP \(bu \fIXmSTRING\fP - text displays \fIXmNlabelString\fP .TP \(bu \fIXmPIXMAP\fP - icon data in pixmap displays \fIXmNlabelPixmap\fP or \fIXmNlabelInsensitivePixmap\fP .IP "\fIXmNmarginBottom\fP" Specifies the amount of spacing between the bottom of the label text and the top of the bottom margin specified by \fIXmNmarginHeight\fP. This may be modified by LabelGadget's subclasses. For example, CascadeButtonGadget may increase this field to make room for the cascade pixmap. .IP "\fIXmNmarginHeight\fP" Specifies an equal amount of spacing above the margin defined by \fIXmNmarginTop\fP and below the margin defined by \fIXmNmarginBottom\fP. \fIXmNmarginHeight\fP specifies the amount of spacing between the top edge of the margin set by \fIXmNmarginTop\fP and the bottom edge of the top shadow, and the amount of spacing between the bottom edge of the margin specified by \fIXmNmarginBottom\fP and the top edge of the bottom shadow. .IP "\fIXmNmarginLeft\fP" Specifies the amount of spacing between the left edge of the label text and the right side of the left margin (specified by \fIXmNmarginWidth\fP). This may be modified by LabelGadget's subclasses. For example, ToggleButtonGadget may increase this field to make room for the toggle indicator and for spacing between the indicator and label. Whether this actually applies to the left or right side of the label may depend on the value of \fIXmNstringDirection\fP. .IP "\fIXmNmarginRight\fP" Specifies the amount of spacing between the right edge of the label text and the left side of the right margin (specified by \fIXmNmarginWidth\fP). This may be modified by LabelGadget's subclasses. For example, CascadeButtonGadget may increase this field to make room for the cascade pixmap. Whether this actually applies to the left or right side of the label may depend on the value of \fIXmNstringDirection\fP. .nL .ne 5 .IP "\fIXmNmarginTop\fP" Specifies the amount of spacing between the top of the label text and the bottom of the top margin specified by \fIXmNmarginHeight\fP. This may be modified by LabelGadget's subclasses. For example, CascadeButtonGadget may increase this field to make room for the cascade pixmap. .IP "\fIXmNmarginWidth\fP" Specifies an equal amount of spacing to the left of the margin defined by \fIXmNmarginLeft\fP and to the right of the margin defined by \fIXmNmarginRight\fP. \fIXmNmarginWidth\fP specifies the amount of spacing between the left edge of the margin set by \fIXmNmarginLeft\fP and the right edge of the left shadow, and the amount of spacing between the right edge of the margin specified by \fIXmNmarginRight\fP and the left edge of the right shadow. .IP "\fIXmNmnemonic\fP" Provides the user with an alternate means of activating a button. A button in a MenuBar, a Popup MenuPane, or a Pulldown MenuPane can have a mnemonic. .IP This resource contains a keysym as listed in the X11 keysym table. The first character in the label string that exactly matches the mnemonic in the character set specified in \fIXmNmnemonicCharSet\fP is underlined when the button is displayed. .IP When a mnemonic has been specified, the user activates the button by pressing the mnemonic key while the button is visible. If the button is a CascadeButtonGadget in a MenuBar and the MenuBar does not have the focus, the user must use the \fIMAlt\fP modifier while pressing the mnemonic. The user can activate the button by pressing either the shifted or the unshifted mnemonic key. .nL .ne 4 .IP "\fIXmNmnemonicCharSet\fP" Specifies the character set of the mnemonic for the label. The default is \fIXmFONTLIST_DEFAULT_TAG\fP. .nL .ne 12 .IP "\fIXmNrecomputeSize\fP" Specifies a Boolean value that indicates whether the gadget shrinks or expands to accommodate its contents (label string or pixmap) as a result of an \fIXtSetValues\fP resource value that would change the size of the gadget. If True, the gadget shrinks or expands to exactly fit the label string or pixmap. If False, the gadget never attempts to change size on its own. .IP "\fIXmNstringDirection\fP" Specifies the direction in which the string is to be drawn. The following are the values: .TP \(bu \fIXmSTRING_DIRECTION_L_TO_R\fP - left to right .TP \(bu \fIXmSTRING_DIRECTION_R_TO_L\fP - right to left .IP The default for this resource is determined at creation time. If no value is specified for this resource and the widget's parent is a manager, the value is inherited from the parent; otherwise, it defaults to \fIXmSTRING_DIRECTION_L_TO_R\fP. .SS "Inherited Resources" LabelGadget inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .IP .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmGadget Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic G XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic G XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightThickness XmCHighlightThickness Dimension 0 CSG XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension 0 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic G XmNtraversalOn XmCTraversalOn Boolean False CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. RectObj Resource Set Name Class Type Default Access _ XmNancestorSensitive XmCSensitive Boolean dynamic G XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNheight XmCHeight Dimension dynamic CSG XmNsensitive XmCSensitive Boolean True CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Object Resource Set Name Class Type Default Access _ XmNdestroyCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .SS "Behavior" XmLabelGadget includes behavior from XmGadget. Additional XmLabelGadget behavior is described below: .IP "\fIBDrag\ Press\fP:" Drags the contents of a LabelGadget, identified by pressing \fIBDrag\fP. This action creates a DragContext object whose \fIXmNexportTargets\fP resource is set to "COMPOUND_TEXT" for a label type of \fIXmSTRING\fP; otherwise, "PIXMAP" if the label type is \fIXmPIXMAP\fP. This action is undefined for LabelGadgets used in a menu system. .IP This action is disabled if the XmDisplay's \fIenableUnselectableDrag\fP resource is True. .IP "\fIKHelp\fP:" In a Popup or Pulldown MenuPane, unposts all menus in the menu hierarchy and, when the shell's keyboard focus policy is \fIXmEXPLICIT\fP, restores keyboard focus to the widget that had the focus before the menu system was entered. Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIMAny\ KCancel\fP:" In a MenuBar, disarms the CascadeButton and the menu and, when the shell's keyboard focus policy is \fIXmEXPLICIT\fP, restores keyboard focus to the widget that had the focus before the menu was entered. .IP In a toplevel Pulldown MenuPane from a MenuBar, unposts the menu, disarms the MenuBar CascadeButton and the MenuBar, and, when the shell's keyboard focus policy is \fIXmEXPLICIT\fP, restores keyboard focus to the widget that had the focus before the MenuBar was entered. In other Pulldown MenuPanes, unposts the menu. .IP In a Popup MenuPane, unposts the menu and, when the shell's keyboard focus policy is \fIXmEXPLICIT\fP, restores keyboard focus to the widget from which the menu was posted. .IP "\fIKDown\fP:" If the current menu item has a submenu and is in a MenuBar, then this action posts the submenu, disarms the current menu item, and arms the submenu's first traversable menu item. .IP If the current menu item is in a MenuPane, then this action disarms the current menu item and arms the item below it. This action wraps within the MenuPane. When the current menu item is at the MenuPane's bottom edge, then this action wraps to the topmost menu item in the column to the right, if one exists. When the current menu item is at the bottom, rightmost corner of the MenuPane, then this action wraps to the tear-off control, if present, or to the top, leftmost menu item. .IP "\fIKLeft\fP:" When the current menu item is in a MenuBar, then this action disarms the current item and arms the MenuBar item to the left. This action wraps within the MenuBar. .IP In MenuPanes, if the current menu item is not at the left edge of a MenuPane, this action disarms the current item and arms the item to its left. If the current menu item is at the left edge of a submenu attached to a MenuBar item, then this action unposts the submenu and traverses to the MenuBar item to the left, wrapping if necessary. If that MenuBar item has a submenu, it posts the submenu and arms the first traversable item in the submenu. If the current menu item is at the left edge of a submenu not directly attached to a MenuBar item, then this action unposts the current submenu only. .IP In Popup or Torn-off MenuPanes, when the current menu item is at the left edge, this action wraps within the MenuPane. If the current menu item is at the left edge of the MenuPane and not in the top row, this action wraps to the rightmost menu item in the row above. If the current menu item is in the upper, leftmost corner, this action wraps to the tear-off control, if present, or else it wraps to the bottom, rightmost menu item in the MenuPane. .IP "\fIKRight\fP:" If the current menu item is in a MenuBar, then this action disarms the current item and arms the MenuBar item to the right. This action wraps within the MenuBar. .IP In MenuPanes, if the current menu item is a CascadeButton, then this action posts its associated submenu. If the current menu item is not a CascadeButton and is not at the right edge of a MenuPane, this action disarms the current item and arms the item to its right, wrapping if necessary. If the current menu item is not a CascadeButton and is at the right edge of a submenu that is a descendent of a MenuBar, then this action unposts all submenus and traverses to the MenuBar item to the right. If that MenuBar item has a submenu, it posts the submenu and arms the submenu's first traversable item. .IP In Popup or Torn-off menus, if the current menu item is not a CascadeButton and is at the right edge of a row (except the bottom row), this action wraps to the leftmost menu item in the row below. If the current menu item is not a CascadeButton and is in the bottom, rightmost corner of a Popup or Pulldown MenuPane, this action wraps to the tear-off control, if present, or else it wraps to the top, leftmost menu item of the MenuPane. .IP "\fIKUp\fP:" When the current menu item is in a MenuPane, then this action disarms the current menu item and arms the item above it. This action wraps within the MenuPane. When the current menu item is at the MenuPane's top edge, then this action wraps to the bottommost menu item in the column to the left, if one exists. When the current menu item is at the top, leftmost corner of the MenuPane, then this action wraps to the tear-off control, if present, or to the bottom, rightmost menu item. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .nL .ne 10 .SH RELATED INFORMATION .na \fIObject(3X)\fP, \fIRectObj(3X)\fP, \fIXmCreateLabelGadget(3X)\fP, \fIXmDisplay(3X)\fP, \fIXmFontListCreate(3X)\fP, \fIXmStringCreate(3X)\fP, \fIXmStringCreateLtoR(3X)\fP, and \fIXmGadget(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmList 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmList\fP \- The List widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi List allows a user to select one or more items from a group of choices. Items are selected from the list in a variety of ways, using both the pointer and the keyboard. List operates on an array of compound strings that are defined by the application. Each compound string becomes an item in the List, with the first compound string becoming the item in position 1, the second becoming the item in position 2, and so on. .PP The size of the List is set by specifying the number of items that are visible. If the number of visible items is not specified, the height of the list controls the number of visible items. Each item assumes the height of the tallest element in the list. To create a list that allows the user to scroll easily through a large number of items, use the \fIXmCreateScrolledList\fP convenience function. .PP To select items, move the pointer or cursor to the desired item and press the \fIBSelect\fP mouse button or the key defined as \fIKSelect\fP. There are several styles of selection behavior, and they all highlight the selected item or items by displaying them in inverse colors. An appropriate callback is invoked to notify the application of the user's choice. The application then takes whatever action is required for the specified selection. When a List is insensitive, all of the list items are displayed in a stippled fill pattern. .SS "Selection" Each list has one of four selection models: .TP \(bu Single Select .TP \(bu Browse Select .TP \(bu Multiple Select .TP \(bu Extended Select .PP In Single Select and Browse Select, at most one item is selected at a time. In Single Select, pressing \fIBSelect\fP on an item toggles its selection state and deselects any other selected item. In Browse Select, pressing \fIBSelect\fP on an item selects it and deselects any other selected item; dragging \fIBSelect\fP moves the selection as the pointer is moved. Releasing \fIBSelect\fP on an item moves the location cursor to that item. .PP In Multiple Select, any number of items can be selected at a time. Pressing \fIBSelect\fP on an item toggles its selection state but does not deselect any other selected items. .PP In Extended Select, any number of items can be selected at a time, and the user can easily select ranges of items. Pressing \fIBSelect\fP on an item selects it and deselects any other selected item. Dragging \fIBSelect\fP or pressing or dragging \fIBExtend\fP following a \fIBSelect\fP action selects all items between the item under the pointer and the item on which \fIBSelect\fP was pressed. This action also deselects any other selected items outside that range. .PP Extended Select also allows the user to select and deselect discontiguous ranges of items. Pressing \fIBToggle\fP on an item toggles its selection state but does not deselect any other selected items. Dragging \fIBToggle\fP or pressing or dragging \fIBExtend\fP following a \fIBToggle\fP action sets the selection state of all items between the item under the pointer and the item on which \fIBToggle\fP was pressed to the state of the item on which \fIBToggle\fP was pressed. This action does not deselect any other selected items outside that range. .PP All selection operations available from the mouse are also available from the keyboard. List has two keyboard selection modes, Normal Mode and Add Mode. In Normal Mode, navigation operations and \fIKSelect\fP select the item at the location cursor and deselect any other selected items. In Add Mode, navigation operations have no effect on selection, and \fIKSelect\fP toggles the selection state of the item at the location cursor without deselecting any other selected items, except in Single Select. .PP Single and Multiple Select use Add Mode, and Browse Select uses Normal Mode. .PP Extended Select can use either mode; the user changes modes by pressing \fIKAddMode\fP. In Extended Select Normal Mode, pressing \fIKSelect\fP has the same effect as pressing \fIBSelect\fP; \fIKExtend\fP and shifted navigation have the same effect as pressing \fIBExtend\fP following a \fIBSelect\fP action. In Extended Select Add Mode, pressing \fIKSelect\fP has the same effect as pressing \fIBToggle\fP; \fIKExtend\fP and shifted navigation have the same effect as pressing \fIBExtend\fP following a \fIBToggle\fP action. .PP Normal Mode is indicated by a solid location cursor, and Add Mode is indicated by a dashed location cursor. .SS "Classes" List inherits behavior and resources from \fICore\fP and \fIXmPrimitive\fP classes. .PP The class pointer is \fIxmListWidgetClass\fP. .PP The class name is \fIXmList\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmList Resource Set Name Class Type Default Access _ XmNautomaticSelection XmCAutomaticSelection Boolean False CSG XmNbrowseSelectionCallback XmCCallback XtCallbackList NULL C XmNdefaultActionCallback XmCCallback XtCallbackList NULL C XmNdoubleClickInterval XmCDoubleClickInterval int dynamic CSG XmNextendedSelectionCallback XmCCallback XtCallbackList NULL C XmNfontList XmCFontList XmFontList dynamic CSG XmNitemCount XmCItemCount int 0 CSG XmNitems XmCItems XmStringTable NULL CSG XmNlistMarginHeight XmCListMarginHeight Dimension 0 CSG XmNlistMarginWidth XmCListMarginWidth Dimension 0 CSG XmNlistSizePolicy XmCListSizePolicy unsigned char XmVARIABLE CG XmNlistSpacing XmCListSpacing Dimension 0 CSG XmNmultipleSelectionCallback XmCCallback XtCallbackList NULL C XmNscrollBarDisplayPolicy XmCScrollBarDisplayPolicy unsigned char XmAS_NEEDED CSG .wH .tH XmNselectedItemCount XmCSelectedItemCount int 0 CSG XmNselectedItems XmCSelectedItems XmStringTable NULL CSG XmNselectionPolicy XmCSelectionPolicy unsigned char XmBROWSE_SELECT CSG XmNsingleSelectionCallback XmCCallback XtCallbackList NULL C XmNstringDirection XmCStringDirection XmStringDirection dynamic CSG XmNtopItemPosition XmCTopItemPosition int 1 CSG XmNvisibleItemCount XmCVisibleItemCount int dynamic CSG .TE .KE .in .sp 1 .IP "\fIXmNautomaticSelection\fP" Invokes \fIXmNbrowseSelectionCallback\fP or \fIXmNextendedSelectionCallback\fP when BSelect is pressed and the items that are shown as selected change if the value is True and the selection mode is either \fIXmBROWSE_SELECT\fP or \fIXmEXTENDED_SELECT\fP respectively. If False, no selection callbacks are invoked until the user releases the mouse button. See the Behavior section for further details on the interaction of this resource with the selection modes. .IP "\fIXmNbrowseSelectionCallback\fP" Specifies a list of callbacks that is called when an item is selected in the browse selection mode. The reason is \fIXmCR_BROWSE_SELECT\fP. .IP "\fIXmNdefaultActionCallback\fP" Specifies a list of callbacks that is called when an item is double clicked or \fIKActivate\fP is pressed. The reason is \fIXmCR_DEFAULT_ACTION\fP. .nL .ne 12 .IP "\fIXmNdoubleClickInterval\fP" If a button click is followed by another button click within the time span specified by this resource (in milliseconds), the button clicks are considered a double-click action, rather than two single-click actions. The value must not be negative. The default value is the display's multi-click time. .IP "\fIXmNextendedSelectionCallback\fP" Specifies a list of callbacks that is called when items are selected using the extended selection mode. The reason is \fIXmCR_EXTENDED_SELECT\fP. .IP "\fIXmNfontList\fP" Specifies the font list associated with the list items. This is used in conjunction with the \fIXmNvisibleItemCount\fP resource to determine the height of the List widget. If this value is NULL at initialization, the font list is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard or VendorShell widget class. If such an ancestor is found, the font list is initialized to the \fIXmNtextFontList\fP of the ancestor widget. If no such ancestor is found, the default is implementation dependent. Refer to \fIXmFontList(3X)\fP for more information on a font list structure. .IP "\fIXmNitemCount\fP" Specifies the total number of items. The value must be the number of items in \fIXmNitems\fP and must not be negative. It is automatically updated by the list whenever an item is added to or deleted from the list. .IP "\fIXmNitems\fP" Points to an array of compound strings that are to be displayed as the list items. Refer to \fIXmString(3X)\fP for more information on the creation and structure of compound strings. \fIXtGetValues\fP for this resource returns the list items themselves, not a copy of the list items. The application must not free the returned items. .IP "\fIXmNlistMarginHeight\fP" Specifies the height of the margin between the list border and the items. .nL .ne 11 .IP "\fIXmNlistMarginWidth\fP" Specifies the width of the margin between the list border and the items. .nL .ne 10 .IP "\fIXmNlistSizePolicy\fP" Controls the reaction of the List when an item grows horizontally beyond the current size of the list work area. If the value is \fIXmCONSTANT\fP, the list viewing area does not grow, and a horizontal ScrollBar is added for a ScrolledList. If this resource is set to \fIXmVARIABLE\fP, the List grows \pto match the size of the longest item, and no horizontal ScrollBar appears. .IP When the value of this resource is \fIXmRESIZE_IF_POSSIBLE\fP, the List attempts to grow or shrink to match the width of the widest item. If it cannot grow to match the widest size, a horizontal ScrollBar is added for a ScrolledList if the longest item is wider than the list viewing area. .nL .ne 3 .IP The size policy must be set at the time the List widget is created. It cannot be changed at a later time through \fIXtSetValues\fP. .IP "\fIXmNlistSpacing\fP" Specifies the spacing between list items. This spacing increases by the value of the \fIXmNhighlightThickness\fP resource in Primitive. .IP "\fIXmNmultipleSelectionCallback\fP" Specifies a list of callbacks that is called when an item is selected in multiple selection mode. The reason is \fIXmCR_MULTIPLE_SELECT\fP. .nL .ne 8 .IP "\fIXmNscrollBarDisplayPolicy\fP" Controls the display of vertical ScrollBars in a ScrolledList. When the value of this resource is \fIXmAS_NEEDED\fP, a vertical ScrollBar is displayed only when the number of items in the List exceeds the number of Visible items. When the value is \fIXmSTATIC\fP, a vertical ScrollBar is always displayed. .IP "\fIXmNselectedItemCount\fP" Specifies the number of strings in the selected items list. The value must be the number of items in \fIXmNselectedItems\fP and must not be negative. .nL .ne 15 .IP "\fIXmNselectedItems\fP" Points to an array of compound strings that represents the list items that are currently selected, either by the user or by the application. \fIXtGetValues\fP for this resource returns the list items themselves, not a copy of the list items. The application must not free the returned items. .IP Setting \fIXmNselectedItems\fP selects those list items that exactly match items in the given \fIXmNselectedItems\fP list. There may be additional items in \fIXmNselectedItems\fP that do not match items in the list. These items remain until \fIXmNselectedItems\fP is updated. If \fIXmNitems\fP is changed such that the list now contains items matching previously unmatched items in \fIXmNselectedItems\fP, those new items will also appear selected. .IP Any user interaction with the list that causes at least one item to be selected or deselected and any call to \fIXmListDeselectAllItems\fP, \fIXmListDeselectAllItems\fP, \fIXmListDeselectPos\fP, \fIXmListSelectItem\fP, \fIXmListSelectPos\fP, or \fIXmListUpdateSelectedList\fP cause \fIXmNselectedItems\fP to be updated immediately to exactly reflect the visual state of the list. Calls to any other \fIXmList\fP functions do not affect \fIXmNselectedItems\fP. .IP "\fIXmNselectionPolicy\fP" Defines the interpretation of the selection action. This can be one of the following: .wH .rS .TP \(bu \fIXmSINGLE_SELECT\fP \- allows only single selections .TP \(bu \fIXmMULTIPLE_SELECT\fP \- allows multiple selections .TP \(bu \fIXmEXTENDED_SELECT\fP \- allows extended selections .TP \(bu \fIXmBROWSE_SELECT\fP" \- allows "drag and browse" functionality .wH .rE .IP "\fIXmNsingleSelectionCallback\fP" Specifies a list of callbacks that is called when an item is selected in single selection mode. The reason is \fIXmCR_SINGLE_SELECT\fP. .nL .ne 9 .IP "\fIXmNstringDirection\fP" Specifies the initial direction to draw the string. The values are \fIXmSTRING_DIRECTION_L_TO_R\fP and \fIXmSTRING_DIRECTION_R_TO_L\fP. The value of this resource is determined at creation time. If the widget's parent is a manager, this value is inherited from the widget's parent, otherwise it is set to \fIXmSTRING_DIRECTION_L_TO_R\fP. .IP "\fIXmNtopItemPosition\fP" Specifies the position of the item that is the first visible item in the list. Setting this resource is equivalent to calling the \fIXmListSetPos\fP function. The position of the first item in the list is 1; the position of the second item is 2; and so on. A position of 0 specifies the last item in the list. The value must not be negative. .IP "\fIXmNvisibleItemCount\fP" Specifies the number of items that can fit in the visible space of the list work area. The List uses this value to determine its height. The value must be greater than 0. .SS "Inherited Resources" List inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPrimitive Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG .wH .tH XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" List defines a new callback structure. The application must first look at the reason field and use only the structure members that are valid for that particular reason, because not all fields are relevant for every possible reason. The callback structure is defined as follows: .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent *\fBevent\fI; XmString \fBitem\fI; int \fBitem_length\fI; int \fBitem_position\fI; XmString *\fBselected_items\fI; int \fBselected_item_count\fI; int *\fBselected_item_positions\fI; char \fBselection_type\fI; } XmListCallbackStruct; .iE .sE .nL .ne 10 .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. It can be NULL. .IP "\fBitem\fP" Is the last item selected at the time of the \fBevent\fP that caused the callback. \fBitem\fP points to a temporary storage space that is reused after the callback is finished. Therefore, if an application needs to save the item, it should copy the item into its own data space. .IP "\fBitem_length\fP" Is the length in bytes of \fBitem\fP. .IP "\fBitem_position\fP" Is the position of \fBitem\fP in the List's \fIXmNitems\fP array. .IP "\fBselected_items\fP" Is a list of items selected at the time of the \fBevent\fP that caused the callback. \fBselected_items\fP points to a temporary storage space that is reused after the callback is finished. Therefore, if an application needs to save the selected list, it should copy the list into its own data space. .IP "\fBselected_item_count\fP" Is the number of items in the \fBselected_items\fP list. This number must be non-negative. .IP "\fBselected_item_positions\fP" Is an array of integers, one for each selected item, representing the position of each selected item in the List's \fIXmNitems\fP array. \fBselected_item_positions\fP points to a temporary storage space that is reused after the callback is finished. Therefore, if an application needs to save this array, it should copy the array into its own data space. .IP "\fBselection_type\fP" Indicates that the most recent extended selection was the initial selection (\fIXmINITIAL\fP), a modification of an existing selection (\fIXmMODIFICATION\fP), or an additional noncontiguous selection (\fIXmADDITION\fP). .IP .ne 25 The following table describes the reasons for which the individual callback structure fields are valid: .IP .sp 1 .in 0 .KS .TS center; cb cb lb li. Reason;Valid Fields = .sp .2 XmCR_SINGLE_SELECT reason, event, item, item_length, item_position XmCR_DEFAULT_ACTION T{ reason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions T} XmCR_BROWSE_SELECT reason, event, item, item_length, item_position XmCR_MULTIPLE_SELECT T{ reason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions T} XmCR_EXTENDED_SELECT T{ reason, event, item, item_length, item_position, selected_items, selected_item_count, selected_item_positions, selection_type T} .sp .2 .TE .KE .in .sp 1 .SS "Translations" XmList includes translations from Primitive. The XmList translations are listed below. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BSelect Press: ListBeginSelect() BSelect Motion: ListButtonMotion() BSelect Release: ListEndSelect() .sp \n(PDu BExtend Press: ListBeginExtend() BExtend Motion: ListButtonMotion() BExtend Release: ListEndExtend() .sp \n(PDu BToggle Press: ListBeginToggle() BToggle Motion: ListButtonMotion() BToggle Release: ListEndToggle() BDrag Press: ListProcessDrag() .sp \n(PDu .nL .ne 7 KUp: ListPrevItem() MShift KUp: ListExtendPrevItem() .sp \n(PDu KDown: ListNextItem() MShift KDown: ListExtendNextItem() .sp \n(PDu KLeft: ListLeftChar() MCtrl KLeft: ListLeftPage() .sp \n(PDu KRight: ListRightChar() MCtrl KRight: ListRightPage() .sp \n(PDu KPageUp: ListPrevPage() KPageDown: ListNextPage() KPageLeft: ListLeftPage() KPageRight: ListRightPage() .sp \n(PDu KBeginLine: ListBeginLine() KEndLine: ListEndLine() .sp \n(PDu KBeginData: ListBeginData() MShift KBeginData: ListBeginDataExtend() .sp \n(PDu KEndData: ListEndData() MShift KEndData: ListEndDataExtend() .sp \n(PDu KAddMode: ListAddMode() .sp \n(PDu KActivate: ListKbdActivate() .sp \n(PDu KCopy Press: ListCopyToClipboard() KSelect Press: ListKbdBeginSelect() KSelect Release: ListKbdEndSelect() .sp \n(PDu KExtend Press: ListKbdBeginExtend() KExtend Release: ListKbdEndExtend() .sp \n(PDu MAny KCancel: ListKbdCancel() KSelectAll: ListKbdSelectAll() KDeselectAll: ListKbdDeSelectAll() .sp \n(PDu KHelp: PrimitiveHelp() KNextField PrimitiveNextTabGroup() KPrevField PrimitivePrevTabGroup() .wH .fi .iE .PP The translations for the button events are modified when the XmDisplay's \fIenableBtn1Transfer\fP resource is True. This option allows the actions for selection and transfer to be integrated on Button1 so that the actions for extending the selection can be bound to Button2. The actions for Button1 that are defined above still apply when the Button1 press occurs over text that is not selected. The following actions apply when the Button1 press occurs over text that is selected: .PP .iS .ta 1.5i .nf BSelect Press: ListProcessDrag() resulting in copy .sp \n(PDu BExtend Press: ListProcessDrag() resulting in move BExtend Click: ListBeginExtend(), ListEndExtend() .sp \n(PDu BToggle Press: ListProcessDrag() resulting in copy .sp \n(PDu BDrag Press: ListBeginExtend() BDrag Motion: ListButtonMotion() BDrag Release: ListEndExtend() .wH .fi .iE .SS "Action Routines" The XmList action routines are described below. The current selection is always shown with inverted colors. .IP "\fIListAddMode()\fP:" Toggles the state of Add Mode for keyboard selection. .IP "\fIListBeginData()\fP:" Moves the location cursor to the first item in the list. In Normal Mode, this also deselects any current selection, selects the first item in the list, and calls the appropriate selection callbacks (\fIXmNbrowseSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmBROWSE_SELECT\fP, \fIXmNextendedSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP). .IP "\fIListBeginDataExtend()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmMULTIPLE_SELECT\fP or \fIXmEXTENDED_SELECT\fP, moves the location cursor to the first item in the list. .IP If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done. Changes the selection state of the first item and all items between it and the current anchor point to the state of the item at the current anchor point. Calls the \fIXmNextendedSelectionCallback\fP callbacks. .IP "\fIListBeginExtend()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done. Changes the selection state of the item under the pointer and all items between it and the current anchor point to the state of the .ne 4 item at the current anchor point. If \fIXmNautomaticSelection\fP is set to True, calls the \fIXmNextendedSelectionCallback\fP callbacks. .IP "\fIListBeginLine()\fP:" Moves the horizontal scroll region to the beginning of the line. .IP "\fIListBeginSelect()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmSINGLE_SELECT\fP, deselects any current selection and toggles the selection state of the item under the pointer. .IP If the \fIXmNselectionPolicy\fP is set to \fIXmBROWSE_SELECT\fP, deselects any current selection and selects the item under the pointer. If \fIXmNautomaticSelection\fP is set to True, calls the \fIXmNbrowseSelectionCallback\fP callbacks. .IP If the \fIXmNselectionPolicy\fP is set to \fIXmMULTIPLE_SELECT\fP, toggles the selection state of the item under the pointer. Any previous selections remain. .IP If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, deselects any current selection, selects the item under the pointer, and sets the current anchor at that item. If \fIXmNautomaticSelection\fP is set to True, calls the \fIXmNextendedSelectionCallback\fP callbacks. .IP "\fIListBeginToggle()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, does the following: Moves the current anchor to the item under the pointer without changing the current selection. If the item is unselected, it is selected; if the item is selected, it is unselected. If \fIXmNautomaticSelection\fP is set to True, calls the \fIXmNextendedSelectionCallback\fP callbacks. .IP "\fIListButtonMotion()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmBROWSE_SELECT\fP, deselects any current selection and selects the item under the pointer. If \fIXmNautomaticSelection\fP is set to True and the pointer has entered a new list item, calls the \fIXmNbrowseSelectionCallback\fP callbacks. .IP .ne 4 If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, does the following: If an extended selection is being made and an extended selection has previously been made from the current anchor point, restores the selection state of the items in that range to their state before the previous extended selection was done. Changes the selection state of the item under the pointer and all items between it and the current anchor point to the state of the item at the current anchor point. If \fIXmNautomaticSelection\fP is set to True and the pointer has entered a new list item, calls the \fIXmNextendedSelectionCallback\fP callbacks. .IP If the pointer leaves a scrolled list, this action scrolls the list in the direction of the pointer motion. .IP "\fIListCopyToClipboard()\fP" Copies the content of the selected items to the clipboard as a single compound string with each item separated by a newline. .IP "\fIListEndData()\fP:" Moves the location cursor to the last item in the list. In Normal Mode, this also deselects any current selection, selects the last item in the list, and calls the appropriate selection callbacks (\fIXmNbrowseSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmBROWSE_SELECT\fP, \fIXmNextendedSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP). .IP "\fIListEndDataExtend()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmMULTIPLE_SELECT\fP or \fIXmEXTENDED_SELECT\fP, moves the location cursor to the last item in the list. .IP If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done. Changes the selection state of the last item and all items between it and the current anchor point to the state of the item at the current anchor point. Calls the \fIXmNextendedSelectionCallback\fP callbacks. .nL .ne 5 .IP "\fIListEndExtend()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, moves the location cursor to the last item selected or deselected and, if \fIXmNautomaticSelection\fP is set to False, calls the \fIXmNextendedSelectionCallback\fP callbacks. .IP "\fIListEndLine()\fP:" Moves the horizontal scroll region to the end of the line. .IP "\fIListEndSelect()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmSINGLE_SELECT\fP or \fIXmMULTIPLE_SELECT\fP, moves the location cursor to the last item selected or deselected and calls the appropriate selection callbacks (\fIXmNsingleSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmSINGLE_SELECT\fP, \fIXmNmultipleSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmMULTIPLE_SELECT\fP). .IP If the \fIXmNselectionPolicy\fP is set to \fIXmBROWSE_SELECT\fP or \fIXmEXTENDED_SELECT\fP, moves the location cursor to the last item selected or deselected and, if \fIXmNautomaticSelection\fP is set to False, calls the appropriate selection callbacks (\fIXmNbrowseSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmBROWSE_SELECT\fP, \fIXmNextendedSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP). .IP "\fIListEndToggle()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, moves the location cursor to the last item selected or deselected and, if \fIXmNautomaticSelection\fP is set to False, calls the \fIXmNextendedSelectionCallback\fP callbacks. .IP "\fIListExtendNextItem()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done. Moves the location cursor to the next item and changes the selection state of the item and all .ne 4 items between it and the current anchor point to the state of the item at the current anchor point. Calls the \fIXmNextendedSelectionCallback\fP callbacks. .IP "\fIListExtendPrevItem()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done. Moves the location cursor to the previous item and changes the selection state of the item and all items between it and the current anchor point to the state of the item at the current anchor point. Calls the \fIXmNextendedSelectionCallback\fP callbacks. .IP "\fIListScrollCursorVertically(\fBpercentage\fI)\fP:" Scrolls the line containing the insertion cursor vertically to an intermediate position in the visible window based on an input percentage. A value of 0 indicates the top of the window; a value of 100, the bottom of the window. If this action is called with no argument, the line containing the insertion cursor is scrolled vertically to a new position designated by the \fBy\fP event passed to the routine. .IP "\fIListKbdActivate()\fP:" Calls the callbacks for \fIXmNdefaultActionCallback\fP. If the List's parent is a manager, this action passes the event to the parent. .IP "\fIListKbdBeginExtend()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, does the following: If an extended selection has been made from the current anchor point, restores the selection state of the items in that range to their state before the extended selection was done. Changes the selection state of the item at the location cursor and all items between it and the current anchor point to the state of the item at the current anchor point. If \fIXmNautomaticSelection\fP is set to True, calls the \fIXmNextendedSelectionCallback\fP callbacks. .IP "\fIListKbdBeginSelect()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmSINGLE_SELECT\fP, deselects any current selection and toggles the state of the item at the location cursor. .IP If the \fIXmNselectionPolicy\fP is set to \fIXmBROWSE_SELECT\fP, deselects any current selection and selects the item at the location cursor. If \fIXmNautomaticSelection\fP is set to True, calls the \fIXmNbrowseSelectionCallback\fP callbacks. .IP If the \fIXmNselectionPolicy\fP is set to \fIXmMULTIPLE_SELECT\fP, toggles the selection state of the item at the location cursor. Any previous selections remain. .IP .ne 9 If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, moves the current anchor to the item at the location cursor. In Normal Mode, deselects any current selection and selects the item at the location cursor. In Add Mode, toggles the selection state of the item at the location cursor and leaves the current selection unchanged. If \fIXmNautomaticSelection\fP is set to True, calls the \fIXmNextendedSelectionCallback\fP callbacks. .IP "\fIListKbdCancel()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP and an extended selection is being made from the current anchor point, cancels the new selection and restores the selection state of the items in that range to their state before the extended selection was done. If \fIXmNautomaticSelection\fP is set to True, calls the \fIXmNextendedSelectionCallback\fP callbacks, otherwise, and if the parent is a manager, passes the event to the parent. .IP "\fIListKbdDeSelectAll()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmSINGLE_SELECT\fP, \fIXmMULTIPLE_SELECT\fP, or \fIXmEXTENDED_SELECT\fP in Add Mode, deselects all items in the list. If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP in Normal Mode, deselects all items in the list (except the item at the location cursor if the shell's \fIXmNkeyboardFocusPolicy\fP is \fIXmEXPLICIT\fP). Calls the appropriate selection callbacks (\fIXmNsingleSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmSINGLE_SELECT\fP, \fIXmNmultipleSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmMULTIPLE_SELECT\fP, \fIXmNextendedSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP). .IP "\fIListKbdEndExtend()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP and if \fIXmNautomaticSelection\fP is set to False, calls the \fIXmNextendedSelectionCallback\fP callbacks. .nL .ne 9 .IP "\fIListKbdEndSelect()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmSINGLE_SELECT\fP or \fIXmMULTIPLE_SELECT\fP or if \fIXmNautomaticSelection\fP is set to False, calls the appropriate selection callbacks (\fIXmNsingleSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmSINGLE_SELECT\fP, \fIXmNbrowseSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmBROWSE_SELECT\fP, \fIXmNmultipleSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmMULTIPLE_SELECT\fP, \fIXmNextendedSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP). .IP "\fIListKbdSelectAll()\fP:" If the \fIXmNselectionPolicy\fP is set to \fIXmSINGLE_SELECT\fP or \fIXmBROWSE_SELECT\fP, selects the item at the location cursor. If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP or \fIXmMULTIPLE_SELECT\fP, selects all items in the list. Calls the appropriate selection callbacks (\fIXmNsingleSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmSINGLE_SELECT\fP, \fIXmNbrowseSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmBROWSE_SELECT\fP, \fIXmNmultipleSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmMULTIPLE_SELECT\fP, \fIXmNextendedSelectionCallback\fP when \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP). .IP "\fIListLeftChar()\fP:" Scrolls the list one character to the left. .IP "\fIListLeftPage()\fP:" Scrolls the list one page to the left. .IP "\fIListNextItem()\fP:" Moves the location cursor to the next item in the list. .IP If the \fIXmNselectionPolicy\fP is set to \fIXmBROWSE_SELECT\fP, this action also selects the next item, deselects any current selection, and calls the \fIXmNbrowseSelectionCallback\fP callbacks. .IP .ne 8 If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, this action in Normal Mode also selects the next item, deselects any current selection, moves the current anchor to the next item, and calls the \fIXmNextendedSelectionCallback\fP callbacks. In Add Mode this action does not affect the selection or the anchor. .IP "\fIListNextPage()\fP:" Scrolls the list to the next page, moving the location cursor to a new item. .IP If the \fIXmNselectionPolicy\fP is set to \fIXmBROWSE_SELECT\fP, this action also selects the new item, deselects any current selection, and calls the \fIXmNbrowseSelectionCallback\fP callbacks. .IP If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, this action in Normal Mode also selects the new item, deselects any current selection, moves the current anchor to the new item, and calls the \fIXmNextendedSelectionCallback\fP callbacks. In Add Mode this action does not affect the selection or the anchor. .IP "\fIListPrevItem()\fP:" Moves the location cursor to the previous item in the list. .IP If the \fIXmNselectionPolicy\fP is set to \fIXmBROWSE_SELECT\fP, this action also selects the previous item, deselects any current selection, and calls the \fIXmNbrowseSelectionCallback\fP callbacks. .IP If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, this action in Normal Mode also selects the previous item, deselects any current selection, moves the current anchor to the previous item, and calls the \fIXmNextendedSelectionCallback\fP callbacks. In Add Mode this action does not affect the selection or the anchor. .nL .ne 8 .IP "\fIListPrevPage()\fP:" Scrolls the list to the previous page, moving the location cursor to a new item. .IP If the \fIXmNselectionPolicy\fP is set to \fIXmBROWSE_SELECT\fP, this action also selects the new item, deselects any current selection, and calls the \fIXmNbrowseSelectionCallback\fP callbacks. .IP If the \fIXmNselectionPolicy\fP is set to \fIXmEXTENDED_SELECT\fP, this action in Normal Mode also selects the new item, deselects any current selection, moves the current anchor to the new item, and calls the \fIXmNextendedSelectionCallback\fP callbacks. In Add Mode this action does not affect the selection or the anchor. .IP "\fIListProcessDrag()\fP:" Drags the content of a one or more selected list items. Each item is separated by a newline. This action creates a DragContext object whose \fIXmNexportTargets\fP resource is set to "COMPOUND_TEXT" and the \fIXmNclientData\fP resource is set to the index of the item in the list. If \fIBDrag\fP is pressed on an unselected item, drags only that item, excluding any other selected items. .IP "\fIListRightChar()\fP:" Scrolls the list one character to the right. .IP "\fIListRightPage()\fP:" Scrolls the list one page to the right. .IP "\fIPrimitiveHelp()\fP:" Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIPrimitiveNextTabGroup()\fP:" Moves the focus to the first item contained within the next tab group. If the current tab group is the last entry in the tab group list, it wraps to the beginning of the tab group list. .IP "\fIPrimitivePrevTabGroup()\fP:" Moves the focus to the first item contained within the previous tab group. If the beginning of the tab group list is reached, it wraps to the end of the tab group list. .ne 10 .SS "Additional Behavior" The List widget has the additional behavior described below: .IP "\fI\fP" If a button click is followed by another button click within the time span specified by the display's multi-click time, the List interprets that as a double click and calls the callbacks for \fIXmNdefaultActionCallback\fP. The item's colors invert to indicate that it is selected. The \fIXmNdoubleClickInterval\fP resource can be used to specify a time span that overrides the display's multi-click time. .IP "\fI\fP:" If the focus policy is Explicit, sets the focus and draw the location cursor. .IP "\fI\fP:" If the focus policy is Explicit, removes the focus and erase the location cursor. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fICore(3X)\fP, \fIXmCreateList(3X)\fP, \fIXmCreateScrolledList(3X)\fP, \fIXmFontListAppendEntry(3X)\fP, \fIXmListAddItem(3X)\fP, \fIXmListAddItems(3X)\fP, \fIXmListAddItemUnselected(3X)\fP, \fIXmListAddItemsUnselected(3X)\fP, \fIXmListDeleteAllItems(3X)\fP, \fIXmListDeleteItem(3X)\fP, \fIXmListDeleteItems(3X)\fP, \fIXmListDeleteItemsPos(3X)\fP, \fIXmListDeletePos(3X)\fP, \fIXmListDeletePositions(3X)\fP, \fIXmListDeselectAllItems(3X)\fP, \fIXmListDeselectItem(3X)\fP, \fIXmListDeselectPos(3X)\fP, \fIXmListGetKbdItemPos \fIXmListGetMatchPos(3X)\fP, \fIXmListGetSelectedPos(3X)\fP, \fIXmListItemExists(3X)\fP, \fIXmListItemPos(3X)\fP, \fIXmListPosToBounds(3X)\fP, \fIXmListReplaceItems(3X)\fP, \fIXmListReplaceItemsPos(3X)\fP, \fIXmListReplaceItemsPositions(3X)\fP, \fIXmListReplaceItemsPosUnselected(3X)\fP, \fIXmListReplaceItemsUnselected(3X)\fP, \fIXmListSelectItem(3X)\fP, \fIXmListSelectPos(3X)\fP, \fIXmListSetAddMode(3X)\fP, \fIXmListSetBottomItem(3X)\fP, \fIXmListSetBottomPos(3X)\fP, \fIXmListSetHorizPos(3X)\fP, \fIXmListSetItem(3X)\fP, \fIXmListSetKbdItemPos(3X)\fP, \fIXmListSetPos(3X)\fP, \fIXmListUpdateSelectedList(3X)\fP, \fIXmListYToPos(3X)\fP, \fIXmPrimitive(3X)\fP and \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListAddItem 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListAddItem\fP \- A List function that adds an item to the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListAddItem (\fBwidget, item, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString \fBitem\fI; int \fBposition\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListAddItem\fP adds an item to the list at the given position. When the item is inserted into the list, it is compared with the current \fIXmNselectedItems\fP list. If the new item matches an item on the selected list, it appears selected. .IP "\fBwidget\fP" Specifies the ID of the List to which an item is added. .IP "\fBitem\fP" Specifies the item to be added to the list. .IP "\fBposition\fP" Specifies the position of the new item in the list. A value of 1 makes the new item the first item in the list; a value of 2 makes it the second item; and so on. A value of 0 makes the new item the last item in the list. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListAddItemUnselected 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListAddItemUnselected\fP \- A List function that adds an item to the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListAddItemUnselected (\fBwidget, item, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString \fBitem\fI; int \fBposition\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListAddItemUnselected\fP adds an item to the list at the given position. The item does not appear selected, even if it matches an item in the current \fIXmNselectedItems\fP list. .nL .ne 5 .IP "\fBwidget\fP" Specifies the ID of the List from whose list an item is added. .IP "\fBitem\fP" Specifies the item to be added to the list. .IP "\fBposition\fP" Specifies the position of the new item in the list. A value of 1 makes the new item the first item in the list; a value of 2 makes it the second item; and so on. A value of 0 makes the new item the last item in the list. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListAddItems 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListAddItems\fP \- A List function that adds items to the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListAddItems (\fBwidget, items, item_count, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString *\fBitems\fI; int \fBitem_count\fI; int \fBposition\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListAddItems\fP adds the specified items to the list at the given position. The first \fBitem_count\fP items of the \fBitems\fP array are added to the list. When the items are inserted into the list, they are compared with the current \fIXmNselectedItems\fP list. If any of the new items matches an item on the selected list, it appears selected. .IP "\fBwidget\fP" Specifies the ID of the List to which an item is added. .IP "\fBitems\fP" Specifies a pointer to the items to be added to the list. .ne 5 .IP "\fBitem_count\fP" Specifies the number of items in \fBitems\fP. This number must be non-negative. .IP "\fBposition\fP" Specifies the position of the first new item in the list. A value of 1 makes the first new item the first item in the list; a value of 2 makes it the second item; and so on. A value of 0 makes the first new item follow the last item in the list. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListAddItemsUnselected 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListAddItemsUnselected\fP \- A List function that adds items to a list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListAddItemsUnselected (\fBwidget, items, item_count, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString *\fBitems\fI; int \fBitem_count\fI; int \fBposition\fI; .iE .sE .SH DESCRIPTION .fi \fIXmListAddItemsUnselected\fP adds the specified items to the list at the given position. The inserted items remain unselected, even if they currently appear in the \fIXmNselectedItems\fP list. .IP "\fBwidget\fP" Specifies the ID of the List widget to add items to. .IP "\fBitems\fP" Specifies a pointer to the items to be added to the list. .IP "\fBitem_count\fP" Specifies the number of elements in \fBitems\fP. This number must be non-negative. .IP "\fBposition\fP" Specifies the position of the first new item in the list. A value of 1 makes the first new item the first item in the list; a value of 2 makes it the second item; and so on. A value of 0 makes the first new item follow the last item of the list. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListDeleteAllItems 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListDeleteAllItems\fP \- A List function that deletes all items from the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListDeleteAllItems (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListDeleteAllItems\fP deletes all items from the list. .IP "\fBwidget\fP" Specifies the ID of the List from whose list the items are deleted .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListDeleteItem 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListDeleteItem\fP \- A List function that deletes an item from the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListDeleteItem (\fBwidget, item\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString \fBitem\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListDeleteItem\fP deletes the first item in the list that matches \fBitem\fP. A warning message appears if the item does not exist. .IP "\fBwidget\fP" Specifies the ID of the List from whose list an item is deleted .IP "\fBitem\fP" Specifies the text of the item to be deleted from the list .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListDeleteItems 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListDeleteItems\fP \- A List function that deletes items from the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListDeleteItems (\fBwidget, items, item_count\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString *\fBitems\fI; int \fBitem_count\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListDeleteItems\fP deletes the specified items from the list. For each element of \fBitems\fP, the first item in the list that matches that element is deleted. A warning message appears if any of the items do not exist. .IP "\fBwidget\fP" Specifies the ID of the List from whose list an item is deleted .IP "\fBitems\fP" Specifies a pointer to items to be deleted from the list .IP "\fBitem_count\fP" Specifies the number of elements in \fBitems\fP This number must be non-negative. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListDeleteItemsPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListDeleteItemsPos\fP \- A List function that deletes items from the list starting at the given position .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListDeleteItemsPos (\fBwidget, item_count, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBitem_count\fI; int \fBposition\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListDeleteItemsPos\fP deletes the specified number of items from the list starting at the specified position. .IP "\fBwidget\fP" Specifies the ID of the List from whose list an item is deleted. .IP "\fBitem_count\fP" Specifies the number of items to be deleted. This number must be non-negative. .IP "\fBposition\fP" Specifies the position in the list of the first item to be deleted. A value of 1 indicates that the first deleted item is the first item in the list; a value of 2 indicates that it is the second item; and so on. ...\" A value of 0 indicates that the first deleted item is the last item in ...\" the list. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListDeletePos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListDeletePos\fP \- A List function that deletes an item from a list at a specified position .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListDeletePos (\fBwidget, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBposition\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListDeletePos\fP deletes an item at a specified position. A warning message appears if the position does not exist. .IP "\fBwidget\fP" Specifies the ID of the List from which an item is to be deleted. .IP "\fBposition\fP" Specifies the position of the item to be deleted. A value of 1 indicates that the first item in the list is deleted; a value of 2 indicates that the second item is deleted; and so on. A value of 0 indicates that the last item in the list is deleted. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListDeletePositions 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListDeletePositions\fP \- A List function that deletes items from a list based on an array of positions .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListDeletePositions (\fBwidget, position_list, position_count\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int *\fBposition_list\fI; int \fBposition_count\fI; .iE .sE .SH DESCRIPTION .fi \fIXmListDeletePositions\fP deletes noncontiguous items from a list. The function deletes all items whose corresponding positions appear in the \fBposition_list\fP array. A warning message is displayed if a specified position is invalid; that is, the value is 0, a negative integer, or a number greater than the number of items in the list. .IP "\fBwidget\fP" Specifies the ID of the List widget .IP "\fBposition_list\fP" Specifies an array of the item positions to be deleted. The position of the first item in the list is 1; the position of the second item is 2; and so on. .IP "\fBposition_count\fP" Specifies the number of elements in the \fBposition_list\fP. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListDeselectAllItems 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListDeselectAllItems\fP \- A List function that unhighlights and removes all items from the selected list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListDeselectAllItems (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListDeselectAllItems\fP unhighlights and removes all items from the selected list. .IP "\fBwidget\fP" Specifies the ID of the List widget from whose list all selected items are deselected .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListDeselectItem 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListDeselectItem\fP \- A List function that deselects the specified item from the selected list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListDeselectItem (\fBwidget, item\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString \fBitem\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListDeselectItem\fP unhighlights and removes from the selected list the first item in the list that matches \fBitem\fP. .IP "\fBwidget\fP" Specifies the ID of the List from whose list an item is deselected .IP "\fBitem\fP" Specifies the item to be deselected from the list .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListDeselectPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListDeselectPos\fP \- A List function that deselects an item at a specified position in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListDeselectPos (\fBwidget, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBposition\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListDeselectPos\fP unhighlights the item at the specified position and deletes it from the list of selected items. .IP "\fBwidget\fP" Specifies the ID of the List widget .IP "\fBposition\fP" Specifies the position of the item to be deselected. A value of 1 indicates that the first item in the list is deselected; a value of 2 indicates that the second item is deselected; and so on. A value of 0 indicates that the last item in the list is deselected. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListGetKbdItemPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListGetKbdItemPos\fP \- A List function that returns the position of the item at the location cursor .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int XmListGetKbdItemPos (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .iE .sE .SH DESCRIPTION .fi \fIXmListGetKbdItemPos\fP returns the position of the list item at the location cursor. .IP "\fBwidget\fP" Specifies the ID of the List widget .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RETURN VALUE Returns the position of the current keyboard item. A value of 1 indicates that the location cursor is at the first item of the list; a value of 2 indicates that it is at the second item; and so on. A value of 0 indicates the List widget is empty. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListGetMatchPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListGetMatchPos\fP \- A List function that returns all instances of an item in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmListGetMatchPos (\fBwidget, item, position_list, position_count\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString \fBitem\fI; int **\fBposition_list\fI; int *\fBposition_count\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListGetMatchPos\fP is a Boolean function that returns an array of positions where a specified item is found in a List. .nL .ne 5 .IP "\fBwidget\fP" Specifies the ID of the List widget. .IP "\fBitem\fP" Specifies the item to search for. .IP "\fBposition_list\fP" Returns an array of positions at which the item occurs in the List. The position of the first item in the list is 1; the position of the second item is 2; and so on. When the return value is TRUE, \fIXmListGetMatchPos\fP allocates memory for this array. The caller is responsible for freeing this memory. .IP "\fBposition_count\fP" Returns the number of elements in the \fBposition_list\fP. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RETURN VALUE Returns TRUE if the specified item is present in the list, and FALSE if it is not. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListGetSelectedPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListGetSelectedPos\fP \- A List function that returns the position of every selected item in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmListGetSelectedPos (\fBwidget, position_list, position_count\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int **\fBposition_list\fI; int *\fBposition_count\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListGetSelectedPos\fP is a Boolean function that returns an array of the positions of the selected items in a List. .IP "\fBwidget\fP" Specifies the ID of the List widget. .IP "\fBposition_list\fP" Returns an array of the positions of the selected items in the List. The position of the first item in the list is 1; the position of the second item is 2; and so on. When the return value is TRUE, \fIXmListGetSelectedPos\fP allocates memory for this array. The caller is responsible for freeing this memory. .IP "\fBposition_count\fP" Returns the number of elements in the \fBposition_list\fP. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RETURN VALUE Returns TRUE if the list has any selected items, and FALSE if it does not. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListItemExists 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListItemExists\fP \- A List function that checks if a specified item is in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmListItemExists (\fBwidget, item\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString \fBitem\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListItemExists\fP is a Boolean function that checks if a specified item is present in the list. .IP "\fBwidget\fP" Specifies the ID of the List widget .IP "\fBitem\fP" Specifies the item whose presence is checked .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RETURN VALUE Returns True if the specified item is present in the list. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListItemPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListItemPos\fP \- A List function that returns the position of an item in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int XmListItemPos (\fBwidget, item\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString \fBitem\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListItemPos\fP returns the position of the first instance of the specified item in a List. .IP "\fBwidget\fP" Specifies the ID of the List widget .IP "\fBitem\fP" Specifies the item whose position is returned .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .P .ne 10 .SH RETURN VALUE Returns the position in the list of the first instance of the specified item. The position of the first item in the list is 1; the position of the second item is 2; and so on. This function returns 0 if the item is not found. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListPosSelected 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListPosSelected\fP \- A List function that determines if the list item at a specified position is selected .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmListPosSelected (\fBwidget, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBposition\fI; .iE .sE .SH DESCRIPTION .fi \fIXmPosSelected\fP determines if the list item at the specified position is selected or not. .IP "\fBwidget\fP" Specifies the ID of the List widget .IP "\fBposition\fP" Specifies the position of the list item. A value of 1 indicates the first item in the list; a value of 2 indicates the second item; and so on. A value of 0 specifies the last item in the list. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RETURN VALUE Returns True if the list item is selected; otherwise, returns False if the item is not selected or the specified position is invalid. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListPosToBounds 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListPosToBounds\fP \- A List function that returns the bounding box of an item at a specified position in a list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmListPosToBounds (\fBwidget, position, x, y, width, height\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBposition\fI; Position *\fBx\fI; Position *\fBy\fI; Dimension *\fBwidth\fI; Dimension *\fBheight\fI; .iE .sE .SH DESCRIPTION .fi \fIXmListPosToBounds\fP returns the coordinates of an item within a list and the dimensions of its bounding box. The function returns the associated x and y coordinates of the upper left corner of the bounding box relative to the upper left corner of the List widget, as well as the width and the height of the box. The caller can pass a NULL value for the \fBx\fP, \fBy\fP, \fBwidth\fP, or \fBheight\fP parameters to indicate that the return value for that parameter is not requested. .IP "\fBwidget\fP" Specifies the ID of the List widget. .IP "\fBposition\fP" Specifies the position of the specified item. A value of 1 indicates the first item in the list; a value of 2 indicates the second item; and so on. A value of 0 specifies the last item in the list. .IP "\fBx\fP" Specifies a pointer to the returned x coordinate of the item. .IP "\fBy\fP" Specifies the pointer to the returned y coordinate of the item. .IP "\fBwidth\fP" Specifies the pointer to the returned width of the item. .IP "\fBheight\fP" Specifies the pointer to the returned height of the item. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RETURN VALUE If the item at the specified position is not visible, returns False, and the returned values (if any) are undefined. Otherwise, returns True. .SH RELATED INFORMATION .na \fIXmList(3X)\fP and \fIXmListYToPos(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListReplaceItems 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListReplaceItems\fP \- A List function that replaces the specified elements in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListReplaceItems (\fBwidget, old_items, item_count, new_items\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString *\fBold_items\fI; int \fBitem_count\fI; XmString *\fBnew_items\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListReplaceItems\fP replaces each specified item of the list with a corresponding new item. When the items are inserted into the list, they are compared with the current \fIXmNselectedItems\fP list. If any of the new items matches an item on the selected list, it appears selected. .IP "\fBwidget\fP" Specifies the ID of the List widget .IP "\fBold_items\fP" Specifies the items to be replaced .IP "\fBitem_count\fP" Specifies the number of items in \fBold_items\fP and \fBnew_items\fP This number must be non-negative. .IP "\fBnew_items\fP" Specifies the replacement items .PP Every occurrence of each element of \fBold_items\fP is replaced with the corresponding element from \fBnew_items\fP. That is, the first element of \fBold_items\fP is replaced with the first element of \fBnew_items\fP. The second element of \fBold_items\fP is replaced with the second element of \fBnew_items\fP, and so on until \fBitem_count\fP is reached. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListReplaceItemsPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListReplaceItemsPos\fP \- A List function that replaces the specified elements in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListReplaceItemsPos (\fBwidget, new_items, item_count, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString *\fBnew_items\fI; int \fBitem_count\fI; int \fBposition\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListReplaceItemsPos\fP replaces the specified number of items of the List with new items, starting at the specified position in the List. When the items are inserted into the list, they are compared with the current \fIXmNselectedItems\fP list. If any of the new items matches an item on the selected list, it appears selected. .IP "\fBwidget\fP" Specifies the ID of the List widget. .IP "\fBnew_items\fP" Specifies the replacement items. .IP "\fBitem_count\fP" Specifies the number of items in \fBnew_items\fP and the number of items in the list to replace. This number must be non-negative. .IP "\fBposition\fP" Specifies the position of the first item in the list to be replaced. A value of 1 indicates that the first item replaced is the first item in the list; a value of 2 indicates that it is the second item; and so on. ...\" A value of 0 indicates that the first item replaced is the last item in ...\" the list. .PP Beginning with the item specified in \fBposition\fP, \fBitem_count\fP items in the list are replaced with the corresponding elements from \fBnew_items\fP. That is, the item at \fBposition\fP is replaced with the first element of \fBnew_items\fP; the item after \fBposition\fP is replaced with the second element of \fBnew_items\fP; and so on, until \fBitem_count\fP is reached. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListReplaceItemsPosUnselected 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListReplaceItemsPosUnselected\fP \- A List function that replaces items in a list without selecting the replacement items .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListReplaceItemsPosUnselected (\fBwidget, new_items, item_count, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString *\fBnew_items\fI; int \fBitem_count\fI; int \fBposition\fI; .iE .sE .SH DESCRIPTION .fi \fIXmListReplaceItemsPosUnselected\fP replaces the specified number of items in the list with new items, starting at the given position. The replacement items remain unselected, even if they currently appear in the \fIXmNselectedItems\fP list. .IP "\fBwidget\fP" Specifies the ID of the List widget to replace items in. .IP "\fBnew_items\fP" Specifies a pointer to the replacement items. .IP "\fBitem_count\fP" Specifies the number of elements in \fBnew_items\fP and the number of items in the list to replace. This number must be non-negative. .IP "\fBposition\fP" Specifies the position of the first item in the list to be replaced. A value of 1 indicates that the first item replaced is the first item in the list; a value of 2 indicates that it is the second item; and so on. .PP Beginning with the item specified in \fBposition\fP, \fBitem_count\fP items in the list are replaced with the corresponding elements from \fBnew_items\fP. That is, the item at \fBposition\fP is replaced with the first element of \fBnew_items\fP; the item after \fBposition\fP is replaced with the second element of \fBnew_items\fP; and so on, until \fBitem_count\fP is reached. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListReplaceItemsUnselected 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListReplaceItemsUnselected\fP \- A List function that replaces items in a list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListReplaceItemsUnselected (\fBwidget, old_items, item_count, new_items\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString *\fBold_items\fI; int \fBitem_count\fI; XmString *\fBnew_items\fI; .iE .sE .SH DESCRIPTION .fi \fIXmListReplaceItemsUnselected\fP replaces each specified item in the list with a corresponding new item. The replacement items remain unselected, even if they currently appear in the \fIXmNselectedItems\fP list. .IP "\fBwidget\fP" Specifies the ID of the List widget to replace items in. .IP "\fBold_items\fP" Specifies a pointer to the list items to be replaced. .IP "\fBitem_count\fP" Specifies the number of elements in \fBold_items\fP and \fBnew_items\fP. This number must be non-negative. .IP "\fBnew_items\fP" Specifies a pointer to the replacement items. Every occurrence of each element of \fBold_items\fP is replaced with the corresponding element from \fBnew_items\fP. That is, the first element of \fBold_items\fP is replaced with the first element of \fBnew_items\fP. The second element of \fBold_items\fP is replaced with the second element of \fBnew_items\fP, and so on until \fBitem_count\fP is reached. If an element in \fBold_items\fP does not exist in the list, the corresponding entry in \fBnew_items\fP is skipped. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListReplacePositions 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListReplacePositions\fP \- A List function that replaces items in a list based on position .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListReplacePositions (\fBwidget, position_list, item_list, item_count\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int *\fBposition_list\fI; XmString *\fBitem_list\fI; int \fBitem_count; .iE .sE .SH DESCRIPTION .fi \fIXmListReplacePositions\fP replaces noncontiguous items in a list. The item at each position specified in \fBposition_list\fP is replaced with the corresponding entry in \fBitem_list\fP. When the items are inserted into the list, they are compared with the current \fIXmNselectedItems\fP list. Any of the new items that match items on the selected list appears selected. A warning message is displayed if a specified position is invalid; that is, the value is 0, a negative integer, or a number greater than the number of items in the list. .IP "\fBwidget\fP" Specifies the ID of the List widget. .IP "\fBposition_list\fP" Specifies an array of the positions of items to be replaced. The position of the first item in the list is 1; the position of the second item is 2; and so on. .IP "\fBitem_list\fP" Specifies an array of the replacement items. .IP "\fBitem_count\fP" Specifies the number of elements in \fBposition_list\fP and \fBitem_list\fP. This number must be non-negative. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListSelectItem 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListSelectItem\fP \- A List function that selects an item in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListSelectItem (\fBwidget, item, notify\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString \fBitem\fI; Boolean \fBnotify\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListSelectItem\fP highlights and adds to the selected list the first item in the list that matches \fBitem\fP. .IP "\fBwidget\fP" Specifies the ID of the List widget from whose list an item is selected .IP "\fBitem\fP" Specifies the item to be selected in the List widget .IP "\fBnotify\fP" Specifies a Boolean value that when True invokes the selection callback for the current mode. From an application interface view, calling this function with \fBnotify\fP True is indistinguishable from a user-initiated selection action. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListSelectPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListSelectPos\fP \- A List function that selects an item at a specified position in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListSelectPos (\fBwidget, position, notify\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBposition\fI; Boolean \fBnotify\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListSelectPos\fP highlights a List item at the specified position and adds it to the list of selected items. .IP "\fBwidget\fP" Specifies the ID of the List widget. .IP "\fBposition\fP" Specifies the position of the item to be selected. A value of 1 indicates that the first item in the list is selected; a value of 2 indicates that the second item is selected; and so on. A value of 0 indicates that the last item in the list is selected. .IP "\fBnotify\fP" .ne 6 Specifies a Boolean value that when True invokes the selection callback for the current mode. From an application interface view, calling this function with \fBnotify\fP True is indistinguishable from a user-initiated selection action. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListSetAddMode 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListSetAddMode\fP \- A List function that sets add mode in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListSetAddMode (\fBwidget, state\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Boolean \fBstate\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListSetAddMode\fP allows applications control over Add Mode in the extended selection model. .IP "\fBwidget\fP" Specifies the ID of the List widget .IP "\fBstate\fP" Specifies whether to activate or deactivate Add Mode. If \fBstate\fP is True, Add Mode is activated. If \fBstate\fP is False, Add Mode is deactivated. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListSetBottomItem 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListSetBottomItem\fP \- A List function that makes an existing item the last visible item in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListSetBottomItem (\fBwidget, item\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString \fBitem\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListSetBottomItem\fP makes the first item in the list that matches \fBitem\fP the last visible item in the list. .IP "\fBwidget\fP" Specifies the ID of the List widget from whose list an item is made the last visible .IP "\fBitem\fP" Specifies the item .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListSetBottomPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListSetBottomPos\fP \- A List function that makes a specified item the last visible item in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListSetBottomPos (\fBwidget, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBposition\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListSetBottomPos\fP makes the item at the specified position the last visible item in the List. .IP "\fBwidget\fP" Specifies the ID of the List widget. .IP "\fBposition\fP" Specifies the position of the item to be made the last visible item in the list. A value of 1 indicates that the first item in the list is the last visible item; a value of 2 indicates that the second item is the last visible item; and so on. A value of 0 indicates that the last item in the list is the last visible item. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListSetHorizPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListSetHorizPos\fP \- A List function that scrolls to the specified position in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListSetHorizPos (\fBwidget, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBposition\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListSetHorizPos\fP sets the \fIXmNvalue\fP resource of the horizontal ScrollBar to the specified position and updates the visible portion of the list with the new value if the List widget's \fIXmNlistSizePolicy\fP is set to \fIXmCONSTANT\fP or \fIXmRESIZE_IF_POSSIBLE\fP and the horizontal ScrollBar is currently visible. This is equivalent to moving the horizontal ScrollBar to the specified position. .IP "\fBwidget\fP" Specifies the ID of the List widget .IP "\fBposition\fP" Specifies the horizontal position .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListSetItem 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListSetItem\fP \- A List function that makes an existing item the first visible item in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListSetItem (\fBwidget, item\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmString \fBitem\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListSetItem\fP makes the first item in the list that matches \fBitem\fP the first visible item in the list. .IP "\fBwidget\fP" Specifies the ID of the List widget from whose list an item is made the first visible .IP "\fBitem\fP" Specifies the item .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListSetKbdItemPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListSetKbdItemPos\fP \- A List function that sets the location cursor at a specified position .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmListSetKbdItemPos (\fBwidget, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBposition\fI; .iE .sE .SH DESCRIPTION .fi \fIXmListSetKbdItemPos\fP sets the location cursor at the item specified by \fBposition\fP. This function does not determine if the item at the specified position is selected or not. .IP "\fBwidget\fP" Specifies the ID of the List widget. .IP "\fBposition\fP" Specifies the position of the item at which the location cursor is set. A value of 1 indicates the first item in the list; a value of 2 indicates the second item; and so on. A value of 0 sets the location cursor at the last item in the list. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RETURN VALUE Returns False if no item exists at the specified position or if the list is empty; otherwise, returns True. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListSetPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListSetPos\fP \- A List function that makes the item at the given position the first visible position in the list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListSetPos (\fBwidget, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBposition\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmListSetPos\fP makes the item at the given position the first visible position in the List. .IP "\fBwidget\fP" Specifies the ID of the List widget. .IP "\fBposition\fP" Specifies the position of the item to be made the first visible item in the list. A value of 1 indicates that the first item in the list is the first visible item; a value of 2 indicates that the second item is the first visible item; and so on. A value of 0 indicates that the last item in the list is the first visible item. .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListUpdateSelectedList 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListUpdateSelectedList\fP \- A List function that updates the \fIXmNselectedItems\fP resource .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmListUpdateSelectedList (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .iE .sE .SH DESCRIPTION .fi \fIXmListUpdateSelectedList\fP frees the contents of the current \fIXmNselectedItems\fP list. The routine traverses the \fIXmNitems\fP list and adds each currently selected item to the \fIXmNselectedItems\fP list. For each selected item, there is a corresponding entry in the updated \fIXmNselectedItems\fP list. .IP "\fBwidget\fP" Specifies the ID of the List widget to update .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RELATED INFORMATION .na \fIXmList(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmListYToPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmListYToPos\fP \- A List function that returns the position of the item at a specified y coordinate .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int XmListYToPos (\fBwidget, y\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Position \fBy\fI; .iE .sE .SH DESCRIPTION .fi \fIXmListYToPos\fP returns the position of the item at the given y coordinate within the list. .IP "\fBwidget\fP" Specifies the ID of the List widget .IP "\fBy\fP" Specifies the y coordinate in the list's coordinate system .PP For a complete definition of List and its associated resources, see \fIXmList(3X)\fP. .SH RETURN VALUE Returns the position of the item at the specified y coordinate. A value of 1 indicates the first item in the list; a value of 2 indicates the second item; and so on. A value of 0 indicates that no item exists at the specified y coordinate. .SH RELATED INFORMATION .na \fIXmList(3X)\fP and \fIXmListPosToBounds(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmMainWindow 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmMainWindow\fP \- The MainWindow widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi MainWindow provides a standard layout for the primary window of an application. This layout includes a MenuBar, a CommandWindow, a work region, a MessageWindow, and ScrollBars. Any or all of these areas are optional. The work region and ScrollBars in the MainWindow behave identically to the work region and ScrollBars in the ScrolledWindow widget. The user can think of the MainWindow as an extended ScrolledWindow with an optional MenuBar and optional CommandWindow and MessageWindow. .PP In a fully-loaded MainWindow, the MenuBar spans the top of the window horizontally. The CommandWindow spans the MainWindow horizontally just below the MenuBar, and the work region lies below the CommandWindow. The MessageWindow is is below the work region. Any space remaining below the MessageWindow is managed in a manner identical to ScrolledWindow. The behavior of ScrolledWindow can be controlled by the ScrolledWindow resources. To create a MainWindow, first create the work region elements, a MenuBar, a CommandWindow, a MessageWindow, a horizontal ScrollBar, and a vertical ScrollBar widget, and then call \fIXmMainWindowSetAreas\fP with those widget IDs. .PP MainWindow can also create three Separator widgets that provide a visual separation of MainWindow's four components. The user can specify resources in a resource file for the automatically created gadgets that contain the MainWindow separators. The name of the first separator gadget is "Separator1"; the second is "Separator2"; and the third is "Separator3". .SS "Classes" MainWindow inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIConstraint\fP, \fIXmManager\fP, and \fIScrolledWindow\fP classes. .PP The class pointer is \fIxmMainWindowWidgetClass\fP. .PP The class name is \fIXmMainWindow\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .nL .ne 2i .P .wH .in -.5i .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmMainWindow Resource Set Name Class Type Default Access _ XmNcommandWindow XmCCommandWindow Widget NULL CSG XmNcommandWindowLocation XmCCommandWindowLocation unsigned char ABOVE (SeeDesc.) CG XmNmainWindowMarginHeight XmCMainWindowMarginHeight Dimension 0 CSG XmNmainWindowMarginWidth XmCMainWindowMarginWidth Dimension 0 CSG XmNmenuBar XmCMenuBar Widget NULL CSG XmNmessageWindow XmCMessageWindow Widget NULL CSG XmNshowSeparator XmCShowSeparator Boolean False CSG .TE .KE .in .sp 1 .wH .in .IP "\fIXmNcommandWindow\fP" Specifies the widget to be laid out as the CommandWindow. This widget must have been previously created and managed as a child of MainWindow. .IP "\fIXmNcommandWindowLocation\fP" Controls the position of the command window. \fIXmCOMMAND_ABOVE_WORKSPACE\fP locates the command window between the menu bar and the work window. \fIXmCOMMAND_BELOW_WORKSPACE\fP locates the command window between the work window and the message window. .nL .ne 10 .IP "\fIXmNmainWindowMarginHeight\fP" Specifies the margin height on the top and bottom of MainWindow. This resource overrides any setting of the ScrolledWindow resource \fIXmNscrolledWindowMarginHeight\fP. .IP "\fIXmNmainWindowMarginWidth\fP" Specifies the margin width on the right and left sides of MainWindow. This resource overrides any setting of the ScrolledWindow resource \fIXmNscrolledWindowMarginWidth\fP. .IP "\fIXmNmenuBar\fP" Specifies the widget to be laid out as the MenuBar. This widget must have been previously created and managed as a child of MainWindow. .IP "\fIXmNmessageWindow\fP" Specifies the widget to be laid out as the MessageWindow. This widget must have been previously created and managed as a child of MainWindow. The MessageWindow is positioned at the bottom of the MainWindow. If this value is NULL, no message window is included in the MainWindow. .IP "\fIXmNshowSeparator\fP" Displays separators between the components of the MainWindow when set to True. If set to False, no separators are displayed. .SS "Inherited Resources" MainWindow inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmScrolledWindow Resource Set Name Class Type Default Access _ XmNclipWindow XmCClipWindow Widget dynamic G XmNhorizontalScrollBar XmCHorizontalScrollBar Widget dynamic CSG XmNscrollBarDisplayPolicy XmCScrollBarDisplayPolicy unsigned char dynamic CSG XmNscrollBarPlacement XmCScrollBarPlacement unsigned char XmBOTTOM_RIGHT CSG XmNscrolledWindowMarginHeight XmCScrolledWindowMarginHeight Dimension 0 N/A XmNscrolledWindowMarginWidth XmCScrolledWindowMarginWidth Dimension 0 N/A XmNscrollingPolicy XmCScrollingPolicy unsigned char XmAPPLICATION_DEFINED CG XmNspacing XmCSpacing Dimension 4 CSG XmNtraverseObscuredCallback XmCCallback XtCallbackList NULL CSG XmNverticalScrollBar XmCVerticalScrollBar Widget dynamic CSG XmNvisualPolicy XmCVisualPolicy unsigned char dynamic G XmNworkWindow XmCWorkWindow Widget NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmManager Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget NULL CSG XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension 0 CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Translations" MainWindow inherits translations from ScrolledWindow. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fIConstraint(3X)\fP, \fICore(3X)\fP, \fIXmCreateMainWindow(3X)\fP, \fIXmMainWindowSep1(3X)\fP, \fIXmMainWindowSep2(3X)\fP, \fIXmMainWindowSep3(3X)\fP, \fIXmMainWindowSetAreas(3X)\fP, \fIXmManager(3X)\fP, and \fIXmScrolledWindow(3X)\fP .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmMainWindowSep1 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmMainWindowSep1\fP \- A MainWindow function that returns the widget ID of the first Separator widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmMainWindowSep1 (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .ne 15 .iE .sE .SH DESCRIPTION .fi \fIXmMainWindowSep1\fP returns the widget ID of the first Separator widget in the MainWindow. The first Separator widget is located between the MenuBar and the Command widget. This Separator is visible only when \fIXmNshowSeparator\fP is True. .IP "\fBwidget\fP" Specifies the MainWindow widget ID .PP For a complete definition of MainWindow and its associated resources, see \fIXmMainWindow(3X)\fP. .SH RETURN VALUE Returns the widget ID of the first Separator. .SH RELATED INFORMATION .na \fIXmMainWindow(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmMainWindowSep2 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmMainWindowSep2\fP \- A MainWindow function that returns the widget ID of the second Separator widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmMainWindowSep2 (\fBwidget\fI) .ta .5i 2.25i .nf Widget \fBwidget\fI; .wH .fi .ne 15 .iE .sE .SH DESCRIPTION .fi \fIXmMainWindowSep2\fP returns the widget ID of the second Separator widget in the MainWindow. The second Separator widget is located between the Command widget and the ScrolledWindow. This Separator is visible only when \fIXmNshowSeparator\fP is True. .P .IP "\fBwidget\fP" Specifies the MainWindow widget ID .PP For a complete definition of MainWindow and its associated resources, see \fIXmMainWindow(3X)\fP. .SH RETURN VALUE Returns the widget ID of the second Separator. .SH RELATED INFORMATION .na \fIXmMainWindow(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmMainWindowSep3 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmMainWindowSep3\fP \- A MainWindow function that returns the widget ID of the third Separator widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmMainWindowSep3 (\fBwidget\fI) .ta .5i 2.25i .nf Widget \fBwidget\fI; .wH .fi .ne 15 .iE .sE .SH DESCRIPTION .fi \fIXmMainWindowSep3\fP returns the widget ID of the third Separator widget in the MainWindow. The third Separator widget is located between the message window and the widget above it. This Separator is visible only when \fIXmNshowSeparator\fP is True. .IP "\fBwidget\fP" Specifies the MainWindow widget ID .PP For a complete definition of MainWindow and its associated resources, see \fIXmMainWindow(3X)\fP. .SH RETURN VALUE Returns the widget ID of the third Separator. .SH RELATED INFORMATION .na \fIXmMainWindow(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmMainWindowSetAreas 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmMainWindowSetAreas\fP \- A MainWindow function that identifies manageable children for each area .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf void XmMainWindowSetAreas (\fBwidget, menu_bar, command_window, horizontal_scrollbar, vertical_scrollbar, work_region\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Widget \fBmenu_bar\fI; Widget \fBcommand_window\fI; Widget \fBhorizontal_scrollbar\fI; Widget \fBvertical_scrollbar\fI; Widget \fBwork_region\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmMainWindowSetAreas\fP identifies which of the valid children for each area (such as the MenuBar and work region) are to be actively managed by MainWindow. This function also sets up or adds the MenuBar, work window, command window, and ScrollBar widgets to the application's main window widget. .PP Each area is optional; therefore, the user can pass NULL to one or more of the following arguments. The window manager provides the title bar. .IP "\fBwidget\fP" Specifies the MainWindow widget ID. .IP "\fBmenu_bar\fP" Specifies the widget ID for the MenuBar to be associated with the MainWindow widget. Set this ID only after creating an instance of the MainWindow widget. The attribute name associated with this argument is \fIXmNmenuBar\fP. .IP "\fBcommand_window\fP" Specifies the widget ID for the command window to be associated with the MainWindow widget. Set this ID only after creating an instance of the MainWindow widget. The attribute name associated with this argument is \fIXmNcommandWindow\fP. .IP "\fBhorizontal_scrollbar\fP" Specifies the ScrollBar widget ID for the horizontal ScrollBar to be associated with the MainWindow widget. Set this ID only after creating an instance of the MainWindow widget. The attribute name associated with this argument is \fIXmNhorizontalScrollBar\fP. .IP "\fBvertical_scrollbar\fP" Specifies the ScrollBar widget ID for the vertical ScrollBar to be associated with the MainWindow widget. Set this ID only after creating an instance of the MainWindow widget. The attribute name associated with this argument is \fIXmNverticalScrollBar\fP. .IP "\fBwork_region\fP" Specifies the widget ID for the work window to be associated with the MainWindow widget. Set this ID only after creating an instance of the MainWindow widget. The attribute name associated with this argument is \fIXmNworkWindow\fP. .PP For a complete definition of MainWindow and its associated resources, see \fIXmMainWindow(3X)\fP. .SH RELATED INFORMATION .na \fIXmMainWindow(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmManager 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmManager\fP \- The Manager widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi Manager is a widget class used as a supporting superclass for other widget classes. It supports the visual resources, graphics contexts, and traversal resources necessary for the graphics and traversal mechanisms. .nL .ne 12 .SS "Classes" Manager inherits behavior and resources from \fICore\fP, \fIComposite\fP, and \fIConstraint\fP classes. .PP The class pointer is \fIxmManagerWidgetClass\fP. .PP The class name is \fIXmManager\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmManager Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget NULL CSG XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension 0 CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .nL .ne 6 .IP "\fIXmNbottomShadowColor\fP" Specifies the color to use to draw the bottom and right sides of the border shadow. This color is used if the \fIXmNbottomShadowPixmap\fP resource is NULL. .IP "\fIXmNbottomShadowPixmap\fP" Specifies the pixmap to use to draw the bottom and right sides of the border shadow. .IP "\fIXmNforeground\fP" Specifies the foreground drawing color used by manager widgets. .IP "\fIXmNhelpCallback\fP" Specifies the list of callbacks that are called when the help key sequence is pressed. The reason sent by this callback is \fIXmCR_HELP\fP. .IP "\fIXmNhighlightColor\fP" Specifies the color of the highlighting rectangle. This color is used if the highlight pixmap resource is \fIXmUNSPECIFIED_PIXMAP\fP. .IP "\fIXmNhighlightPixmap\fP" Specifies the pixmap used to draw the highlighting rectangle. .IP "\fIXmNinitialFocus\fP" Specifies the ID of a widget descendant of the manager. The widget must meet these conditions: .TP \(bu The widget must be either a tab group or a non-tab-group widget that can receive keyboard focus. For the definition of a tab group, see the description of the Manager, Primitive, and Gadget \fIXmNnavigationType\fP resources. In general a widget can receive keyboard focus when it is a primitive, a gadget, or a manager (such as a DrawingArea with no traversable children) that acts as a primitive. .TP \(bu The widget must not be a descendant of a tab group that is itself a descendant of the manager. That is, the widget cannot be contained within a tab group that is nested inside the manager. .TP \(bu The widget and its ancestors must have a value of True for their \fIXmNtraversalOn\fP resources. .IP If the widget does not meet these conditions, \fIXmNinitialFocus\fP is treated as if the value were NULL. .IP This resource is meaningful only when the nearest shell ancestor's \fIXmNkeyboardFocusPolicy\fP is \fIXmEXPLICIT\fP. It is used to determine which widget receives focus in these situations: .TP \(bu When the manager is the child of a shell and the shell hierarchy receives focus for the first time .TP \(bu When focus is inside the shell hierarchy, the manager is a composite tab group, and the user traverses to the manager via the keyboard .IP Focus is then determined as follows: .TP \(bu If \fIXmNinitialFocus\fP is a traversable non-tab-group widget, that widget receives focus. .TP \(bu If \fIXmNinitialFocus\fP is a traversable tab group, that tab group receives focus. If that tab group is a composite with descendant tab groups or traversable non-tab-group widgets, these procedures are used recursively to assign focus to a descendant of that tab group. .TP \(bu If \fIXmNinitialFocus\fP is NULL, the first traversable non-tab-group widget that is not contained within a nested tab group receives focus. .TP \(bu If \fIXmNinitialFocus\fP is NULL and no traversable non-tab-group widget exists, the first traversable tab group that is not contained within a nested tab group receives focus. If that tab group is a composite with descendant tab groups or traversable non-tab-group widgets, these procedures are used recursively to assign focus to a descendant of that tab group. .IP If a shell hierarchy regains focus after losing it, focus returns to the widget that had the focus at the time it left the hierarchy. .IP The use of \fIXmNinitialFocus\fP is undefined if the manager is a MenuBar, PulldownMenu, PopupMenu, or OptionMenu. .IP "\fIXmNnavigationType\fP" Determines whether the widget is a tab group. .wH .rS .TP \(bu \fIXmNONE\fP indicates that the widget is not a tab group. .TP \(bu \fIXmTAB_GROUP\fP indicates that the widget is a tab group, unless another widget in the hierarchy has an \fIXmNnavigationType\fP of \fIXmEXCLUSIVE_TAB_GROUP\fP. .TP \(bu \fIXmSTICKY_TAB_GROUP\fP indicates that the widget is a tab group, even if another widget in the hierarchy has an \fIXmNnavigationType\fP of \fIXmEXCLUSIVE_TAB_GROUP\fP. .TP \(bu \fIXmEXCLUSIVE_TAB_GROUP\fP indicates that the widget is a tab group and that widgets in the hierarchy whose \fIXmNnavigationType\fP is \fIXmTAB_GROUP\fP are not tab groups. .IP When a parent widget has an \fIXmNnavigationType\fP of \fIXmEXCLUSIVE_TAB_GROUP\fP, traversal of non-tab-group widgets within the group is based on the order of those widgets in their parent's \fIXmNchildren\fP list. .IP When any widget in a hierarchy has an \fIXmNnavigationType\fP of \fIXmEXCLUSIVE_TAB_GROUP\fP, traversal of tab groups in the hierarchy proceeds to widgets in the order in which their \fIXmNnavigationType\fP resources were specified as \fIXmEXCLUSIVE_TAB_GROUP\fP or \fIXmSTICKY_TAB_GROUP\fP, whether by creating the widgets with that value, by calling \fIXtSetValues\fP, or by calling \fIXmAddTabGroup\fP. .wH .rE .IP "\fIXmNshadowThickness\fP" Specifies the thickness of the drawn border shadow. \fIXmBulletinBoard\fP and its descendants set this value dynamically. If the widget is a top level window, this value is set to 1. If it is not a top level window, this value is set to 0. .IP "\fIXmNstringDirection\fP" Specifies the initial direction to draw strings. The values are \fIXmSTRING_DIRECTION_L_TO_R\fP and \fIXmSTRING_DIRECTION_R_TO_L\fP. The value of this resource is determined at creation time. If the widget's parent is a manager, this value is inherited from the widget's parent, otherwise it is set to \fIXmSTRING_DIRECTION_L_TO_R\fP. .IP "\fIXmNtopShadowColor\fP" Specifies the color to use to draw the top and left sides of the border shadow. This color is used if the \fIXmNtopShadowPixmap\fP resource is NULL. .IP "\fIXmNtopShadowPixmap\fP" Specifies the pixmap to use to draw the top and left sides of the border shadow. .IP "\fIXmNtraversalOn\fP" Specifies whether traversal is activated for this widget. .IP "\fIXmNunitType\fP" Provides the basic support for resolution independence. It defines the type of units a widget uses with sizing and positioning resources. If the widget's parent is a subclass of \fIXmManager\fP and if the \fIXmNunitType\fP resource is not explicitly set, it defaults to the unit type of the parent widget. If the widget's parent is not a subclass of \fIXmManager\fP, the resource has a default unit type of \fIXmPIXELS\fP. .IP \fIXmNunitType\fP can have the following values: .wH .rS .TP \(bu \fIXmPIXELS\fP \- all values provided to the widget are treated as normal pixel values. .nL .ne 8 .TP \(bu \fIXm100TH_MILLIMETERS\fP \- all values provided to the widget are treated as 1/100 millimeter. .TP \(bu \fIXm1000TH_INCHES\fP \- all values provided to the widget are treated as 1/1000 inch. .TP \(bu \fIXm100TH_POINTS\fP \- all values provided to the widget are treated as 1/100 point. A point is a unit used in text processing applications and is defined as 1/72 inch. .TP \(bu \fIXm100TH_FONT_UNITS\fP \- all values provided to the widget are treated as 1/100 of a font unit. A font unit has horizontal and vertical components. These are the values of the XmScreen resources \fIXmNhorizontalFontUnit\fP and \fIXmNverticalFontUnit\fP. .IP "\fIXmNuserData\fP" Allows the application to attach any necessary specific data to the widget. This is an internally unused resource. .SS "Dynamic Color Defaults" The foreground, background, top shadow, bottom shadow, and highlight color resources are dynamically defaulted. If no color data is specified, the colors are automatically generated. On a single-plane system, a black and white color scheme is generated. Otherwise, four colors are generated, which display the correct shading for the 3-D visuals. If the background is the only color specified for a widget, the top shadow and bottom shadow colors are generated to give the 3-D appearance. Foreground and highlight colors are generated to provide sufficient contrast with the background color. .IP Colors are generated only at creation. Resetting the background through \fIXtSetValues\fP does not regenerate the other colors. \fIXmChangeColor\fP can be used to recalculate all associated colors based on a new background color. .SS "Inherited Resources" Manager inherits the following resources from the named superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.50i .nf typedef struct { int \fBreason\fI; \fIXEvent \fB* event\fI; } XmAnyCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. For this callback, \fBreason\fP is set to \fIXmCR_HELP\fP. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .SS "Translations" The following set of translations are used by Manager widgets that have Gadget children. Since Gadgets cannot have translations associated with them, it is the responsibility of the Manager widget to intercept the events of interest and pass them to any Gadget child with focus. These events are ignored if no Gadget child has the focus. Some of these translations may be affected by the XmDisplay's \fIenableMultiKeyBindings\fP resource: see XmDisplay(3X). These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BAny Motion: ManagerGadgetButtonMotion() BSelect Press: ManagerGadgetArm() BSelect Click: ManagerGadgetActivate() BSelect Release: ManagerGadgetActivate() BSelect Press 2+: ManagerGadgetMultiArm() BSelect Release 2+: ManagerGadgetMultiActivate() BDrag Press: ManagerGadgetDrag() .sp \n(PDu KSelect: ManagerGadgetSelect() KActivate: ManagerParentActivate() .sp \n(PDu KCancel: ManagerParentCancel() .sp \n(PDu KPrevField: ManagerGadgetPrevTabGroup() KNextField: ManagerGadgetNextTabGroup() .sp \n(PDu KUp: ManagerGadgetTraverseUp() KDown: ManagerGadgetTraverseDown() KLeft: ManagerGadgetTraverseLeft() KRight: ManagerGadgetTraverseRight() .sp \n(PDu KBeginLine: ManagerGadgetTraverseHome() .sp \n(PDu KHelp: ManagerGadgetHelp() .sp \n(PDu KAny: ManagerGadgetKeyInput() .wH .fi .iE .SS "Action Routines" The XmManager action routines are described below: .IP "\fIManagerGadgetActivate()\fP:" Causes the current gadget to be activated. .IP "\fIManagerGadgetArm()\fP:" Causes the current gadget to be armed. .IP "\fIManagerGadgetButtonMotion()\fP:" Causes the current gadget to process a mouse motion event. .IP "\fIManagerGadgetDrag()\fP:" Drags the contents of a gadget label, identified by pressing \fIBDrag\fP. This action creates a DragContext object whose \fIXmNexportTargets\fP resource is set to "COMPOUND_TEXT" for a label type of \fIXmSTRING\fP; otherwise, "PIXMAP" if the label type is \fIXmPIXMAP\fP. This action is undefined for gadgets used in a menu system. .IP "\fIManagerGadgetHelp()\fP:" Calls the callbacks for the current gadget's \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIManagerGadgetKeyInput()\fP:" Causes the current gadget to process a keyboard event. .IP "\fIManagerGadgetMultiActivate()\fP:" Causes the current gadget to process a multiple mouse click. .IP "\fIManagerGadgetMultiArm()\fP:" Causes the current gadget to process a multiple mouse button press. .nL .ne 6 .IP "\fIManagerGadgetNextTabGroup()\fP:" This action depends on the value of the XmDisplay resource \fIenableButtonTab\fP. .IP When \fIenableButtonTab\fP is False (the default), this action traverses to the first item in the next tab group. If the current tab group is the last entry in the tab group list, it wraps to the beginning of the tab group list. .IP When \fIenableButtonTab\fP is True, this action will move to the next item within the current tab group unless it is the last item in the tab group. When the item is the last in the group, the action traverses to the first item in the next tab group. The \fIenableButtonTab\fP behavior applies only to XmPushButton, XmArrow, and XmDrawnButton. .IP "\fIManagerGadgetPrevTabGroup()\fP:" This action depends on the value of the XmDisplay resource \fIenableButtonTab\fP. .IP When \fIenableButtonTab\fP is False (the default), this action traverses to the first item in the previous tab group. If the beginning of the tab group list is reached, it wraps to the end of the tab group list. .IP When \fIenableButtonTab\fP is True, this action will move to the previous item within the current tab group unless it is the first item in the tab group. When the item is the first in the group, the action traverses to the first item in the previous tab group. The \fIenableButtonTab\fP behavior applies only to XmPushButton, XmArrow, and XmDrawnButton. .IP "\fIManagerGadgetSelect()\fP:" Causes the current gadget to be armed and activated. .IP "\fIManagerGadgetTraverseDown()\fP:" Traverses to the next item below the current gadget in the current tab group, wrapping if necessary. .IP "\fIManagerGadgetTraverseHome()\fP:" Traverses to the first widget or gadget in the current tab group. .IP "\fIManagerGadgetTraverseLeft()\fP:" Traverses to the next item to the left of the current gadget in the current tab group, wrapping if necessary. .IP "\fIManagerGadgetTraverseNext()\fP:" Traverses to the next item in the current tab group, wrapping if necessary. .IP "\fIManagerGadgetTraversePrev()\fP:" Traverses to the previous item in the current tab group, wrapping if necessary. .IP "\fIManagerGadgetTraverseRight()\fP:" Traverses to the next item to the right of the current gadget in the current tab group, wrapping if necessary. .IP "\fIManagerGadgetTraverseUp()\fP:" Traverses to the next item above the current gadget in the current tab group, wrapping if necessary. .IP "\fIManagerParentActivate()\fP: If the parent is a manager, passes the \fIKActivate\fP event received by the current widget/gadget to its parent. .IP "\fIManagerParentCancel()\fP:" If the parent is a manager, passes the \fIKCancel\fP event received by the current widget/gadget to its parent. .ne 10 .SS "Additional Behavior" This widget has the additional behavior described below: .IP "\fI\fP:" If the shell's keyboard focus policy is \fIXmEXPLICIT\fP and the event occurs in a gadget, causes the gadget to be highlighted and to take the focus. .IP "\fI\fP:" If the shell's keyboard focus policy is \fIXmEXPLICIT\fP and the event occurs in a gadget, causes the gadget to be unhighlighted and to lose the focus. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fIConstraint(3X)\fP, \fICore(3X)\fP, \fIXmChangeColor(3X)\fP, \fIXmDisplay(3X)\fP, \fIXmGadget(3X)\fP, and \fIXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmMapSegmentEncoding 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmMapSegmentEncoding\fP \- A compound string function that returns the compound text encoding format associated with the specified font list tag .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu char * XmMapSegmentEncoding (\fBfontlist_tag\fI) .ta .5i 1.75i .nf char *\fBfontlist_tag\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmMapSegmentEncoding\fP searches the segment encoding registry for an entry that matches the specified font list tag and returns a copy of the associated compound text encoding format. The application is responsible for freeing the storage associated with the returned data by calling \fIXtFree\fP. .IP "\fBfontlist_tag\fP" Specifies the compound string font list tag .SH RETURN VALUE Returns a copy of the associated compound text encoding format if the font list tag is found in the registry; otherwise, returns NULL. .SH RELATED INFORMATION .na \fIXmCvtXmStringToCT(3X)\fP, \fIXmFontList(3X)\fP, \fIXmRegisterSegmentEncoding(3X)\fP, and \fIXmString(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmMenuPosition 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmMenuPosition\fP \- A RowColumn function that positions a Popup MenuPane .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmMenuPosition (\fBmenu, event\fI) .ta .5i 2i .nf Widget \fBmenu\fI; XButtonPressedEvent \fB* event\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmMenuPosition\fP positions a Popup MenuPane using the information in the specified event. Unless an application is positioning the MenuPane itself, it must first invoke this function before managing the PopupMenu. The \fBx_root\fP and \fBy_root\fP values in the specified event are used to determine the menu position. .IP "\fBmenu\fP" Specifies the PopupMenu to be positioned .IP "\fBevent\fP" Specifies the event passed to the action procedure which manages the PopupMenu .PP .ne 3 For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RELATED INFORMATION .na \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmMenuShell 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmMenuShell\fP \- The MenuShell widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi The MenuShell widget is a custom OverrideShell widget. An OverrideShell widget bypasses \fImwm\fP when displaying itself. It is designed specifically to contain Popup or Pulldown MenuPanes. .PP Most application writers never encounter this widget if they use the menu-system convenience functions, \fIXmCreatePopupMenu\fP or \fIXmCreatePulldown Menu\fP, to create a Popup or Pulldown MenuPane. The convenience functions automatically create a MenuShell widget as the parent of the MenuPane. However, if the convenience functions are not used, the application programmer must create the required MenuShell. In this case, it is important to note that the parent of the MenuShell depends on the type of menu system being built. .nL .ne 15 .TP \(bu If the MenuShell is for the top-level Popup MenuPane, the MenuShell's parent must be the widget from which the Popup MenuPane is popped up. .TP \(bu If the MenuShell is for a MenuPane that is pulled down from a Popup or another Pulldown MenuPane, the MenuShell's parent must be the Popup or Pulldown MenuPane. .TP \(bu If the MenuShell is for a MenuPane that is pulled down from a MenuBar, the MenuShell's parent must be the MenuBar. .TP \(bu If the MenuShell is for a Pulldown MenuPane in an OptionMenu, the MenuShell's parent must be the OptionMenu's parent. .PP Setting \fIXmNheight\fP, \fIXmNwidth\fP, or \fIXmNborderWidth\fP for either a MenuShell or its child sets that resource to the same value in both the parent and the child. An application should always specify these resources for the child, not the parent. .PP For the managed child of a MenuShell, regardless of the value of the shell's \fIXmNallowShellResize\fP, setting \fIXmNx\fP or \fIXmNy\fP sets the corresponding resource of the parent but does not change the child's position relative to the parent. \fIXtGetValues\fP for the child's \fIXmNx\fP or \fIXmNy\fP yields the value of the corresponding resource in the parent. The \fBx\fP and \fBy\fP coordinates of the child's upper left outside corner relative to the parent's upper left inside corner are both zero minus the value of \fIXmNborderWidth\fP. .SS "Classes" MenuShell inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIShell\fP, and \fIOverrideShell\fP classes. .PP The class pointer is \fIxmMenuShellWidgetClass\fP. .PP The class name is \fIXmMenuShell\fP. .SS "New Resources" MenuShell overrides the \fIXmNallowShellResize\fP resource in Shell. The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmMenuShell Resource Set Name Class Type Default Access _ XmNbuttonFontList XmCButtonFontList XmFontList dynamic CSG XmNdefaultFontList XmCDefaultFontList XmFontList dynamic CG XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG .TE .KE .in .sp 1 .IP "\fIXmNbuttonFontList\fP" Specifies the font list used for MenuShell's button descendants. If this value is NULL at initialization and if the value of \fIXmNdefaultFontList\fP is not NULL, \fIXmNbuttonFontList\fP is initialized to the value of \fIXmNdefaultFontList\fP. If the value of \fIXmNdefaultFontList\fP is NULL, \fIXmNbuttonFontList\fP is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard, VendorShell, or XmMenuShell widget class. If such an ancestor is found, \fIXmNbuttonFontList\fP is initialized to the \fIXmNbuttonFontList\fP of the ancestor widget. If no such ancestor is found, the default is implementation dependent. .IP "\fIXmNdefaultFontList\fP" Specifies a default font list for MenuShell's descendants. This resource is obsolete and exists for compatibility with earlier releases. It has been replaced by \fIXmNbuttonFontList\fP and \fIXmNlabelFontList\fP. .IP "\fIXmNlabelFontList\fP" Specifies the font list used for MenuShell's label descendants (Labels and LabelGadgets). If this value is NULL at initialization and if the value of \fIXmNdefaultFontList\fP is not NULL, \fIXmNlabelFontList\fP is initialized to the value of \fIXmNdefaultFontList\fP. If the value of \fIXmNdefaultFontList\fP is NULL, \fIXmNlabelFontList\fP is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard, VendorShell, or XmMenuShell widget class. If such an ancestor is found, \fIXmNlabelFontList\fP is initialized to the \fIXmNlabelFontList\fP of the ancestor widget. If no such ancestor is found, the default is implementation dependent. .SS "Inherited Resources" MenuShell inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. The following tables define a set of widget resources used by the programmer to specify data. The programmer can set the resource values for these inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Shell Resource Set Name Class Type Default Access _ XmNallowShellResize XmCAllowShellResize Boolean True G XmNcreatePopupChildProc XmCCreatePopupChildProc XtCreatePopupChildProc NULL CSG XmNgeometry XmCGeometry String NULL CSG XmNoverrideRedirect XmCOverrideRedirect Boolean True CSG XmNpopdownCallback XmCCallback XtCallbackList NULL C XmNpopupCallback XmCCallback XtCallbackList NULL C XmNsaveUnder XmCSaveUnder Boolean True CSG XmNvisual XmCVisual Visual * CopyFromParent CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 1 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Translations" The XmMenuShell translations are listed below. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BSelect Press: ClearTraversal() BSelect Release: MenuShellPopdownDone() .wH .fi .iE .SS "Action Routines" The XmMenuShell action routines are described below: .IP "\fIClearTraversal()\fP:" Disables keyboard traversal for the menu, enables mouse traversal, and unposts any menus posted by this menu. .nL .ne 6 .IP "\fIMenuShellPopdownDone()\fP:" Unposts the menu hierarchy and, when the shell's keyboard focus policy is \fIXmEXPLICIT\fP, restores focus to the widget that had the focus before the menu system was entered. .IP "\fIMenuShellPopdownOne()\fP:" In a toplevel Pulldown MenuPane from a MenuBar, unposts the menu, disarms the MenuBar CascadeButton and the MenuBar, and, when the shell's keyboard focus policy is \fIXmEXPLICT\fP, restores keyboard focus to the widget that had the focus before the MenuBar was entered. In other Pulldown MenuPanes, unposts the menu. .P In a Popup MenuPane, unposts the menu, and, when the shell's keyboard focus policy is \fIXmEXPLICT\fP, restores keyboard focus to the widget from which the menu was posted. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fICore(3X)\fP, \fIOverrideShell(3X)\fP, \fIShell(3X)\fP, \fIXmCreateMenuShell(3X)\fP, \fIXmCreatePopupMenu(3X)\fP, \fIXmCreatePulldown(3X)\fP, and \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmMessageBox 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmMessageBox\fP \- The MessageBox widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi MessageBox is a dialog class used for creating simple message dialogs. Convenience dialogs based on MessageBox are provided for several common interaction tasks, which include giving information, asking questions, and reporting errors. .PP A MessageBox dialog is typically transient in nature, displayed for the duration of a single interaction. MessageBox is a subclass of XmBulletinBoard and depends on it for much of its general dialog behavior. .PP The default value for \fIXmNinitialFocus\fP is the value of \fIXmNdefaultButton\fP. .PP A typical MessageBox contains a message symbol, a message, and up to three standard default PushButtons: \fIOK, Cancel\fP, and \fIHelp\fP. It is laid out with the symbol and message on top and the PushButtons on the bottom. The help button is positioned to the side of the other push buttons. You can localize the default symbols and button labels for MessageBox convenience dialogs. .PP The user can specify resources in a resource file for the gadgets created automatically that contain the MessageBox symbol pixmap and separator. The gadget names are "Symbol" and "Separator". .PP A MessageBox can also be customized by creating and managing new children that are added to the MessageBox children created automatically by the convenience dialogs. In the case of TemplateDialog, only the separator child is created by default. If the callback, string, or pixmap symbol resources are specified, the appropriate child will be created. .PP Additional children are laid out in the following manner: .TP \(bu The first MenuBar child is placed at the top of the window. .TP \(bu All \fIXmPushButton\fP widgets or gadgets, and their subclasses are placed after the \fIOK\fP button in the order of their creation. .TP \(bu A child that is not in the above categories is placed above the row of buttons. If a message label exists, the child is placed below the label. If a message pixmap exists, but a message label is absent, the child is placed on the same row as the pixmap. The child behaves as a work area and grows or shrinks to fill the space above the row of buttons. The layout of multiple work area children is undefined. .PP .ne 15 At initialization, MessageBox looks for the following bitmap files: .wH .rS .TP \(bu xm_error .TP \(bu xm_information .TP \(bu xm_question .TP \(bu xm_working .TP \(bu xm_warning .wH .rE .PP See \fIXmGetPixmap(3X)\fP for a list of the paths that are searched for these files. .SS "Classes" MessageBox inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIConstraint\fP, \fIXmManager\fP, and \fIXmBulletinBoard\fP. .PP The class pointer is \fIxmMessageBoxWidgetClass\fP. .PP The class name is \fIXmMessageBox\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmMessageBox Resource Set Name Class Type Default Access _ XmNcancelCallback XmCCallback XtCallbackList NULL C XmNcancelLabelString XmCCancelLabelString XmString dynamic CSG XmNdefaultButtonType XmCDefaultButtonType unsigned char XmDIALOG_OK_BUTTON CSG XmNdialogType XmCDialogType unsigned char XmDIALOG_MESSAGE CSG XmNhelpLabelString XmCHelpLabelString XmString dynamic CSG XmNmessageAlignment XmCAlignment unsigned char XmALIGNMENT_BEGINNING CSG XmNmessageString XmCMessageString XmString "" CSG XmNminimizeButtons XmCMinimizeButtons Boolean False CSG XmNokCallback XmCCallback XtCallbackList NULL C XmNokLabelString XmCOkLabelString XmString dynamic CSG XmNsymbolPixmap XmCPixmap Pixmap dynamic CSG .TE .KE .in .sp 1 .nL .ne 20 .IP "\fIXmNcancelCallback\fP" Specifies the list of callbacks that is called when the user clicks on the cancel button. The reason sent by the callback is \fIXmCR_CANCEL\fP. .IP "\fIXmNcancelLabelString\fP" Specifies the string label for the cancel button. The default for this resource depends on the locale. In the C locale the default is "Cancel". .IP "\fIXmNdefaultButtonType\fP" Specifies the default PushButton. A value of \fIXmDIALOG_NONE\fP means that there should be no default PushButton. The following are valid types: .wH .rS .TP \(bu \fIXmDIALOG_CANCEL_BUTTON\fP .TP \(bu \fIXmDIALOG_OK_BUTTON\fP .TP \(bu \fIXmDIALOG_HELP_BUTTON\fP .TP \(bu \fIXmDIALOG_NONE\fP .wH .rE .IP "\fIXmNdialogType\fP" Specifies the type of MessageBox dialog, which determines the default message symbol. The following are the possible values for this resource: .wH .rS .TP \(bu \fIXmDIALOG_ERROR\fP \- indicates an ErrorDialog .TP \(bu \fIXmDIALOG_INFORMATION\fP \- indicates an InformationDialog .TP \(bu \fIXmDIALOG_MESSAGE\fP \- indicates a MessageDialog. This is the default MessageBox dialog type. It does not have an associated message symbol. .TP \(bu \fIXmDIALOG_QUESTION\fP \- indicates a QuestionDialog .TP \(bu \fIXmDIALOG_TEMPLATE\fP \- indicates a TemplateDialog. The TemplateDialog contains only a separator child. It does not have an associated message symbol. .TP \(bu \fIXmDIALOG_WARNING\fP \- indicates a WarningDialog .TP \(bu \fIXmDIALOG_WORKING\fP \- indicates a WorkingDialog .wH .rE .PP If this resource is changed via \fIXtSetValues\fP, the symbol bitmap is modified to the new \fIXmNdialogType\fP bitmap unless \fIXmNsymbolPixmap\fP is also being set in the call to \fIXtSetValues\fP. If the dialog type does not have an associated message symbol, then no bitmap will be displayed. .nL .IP "\fIXmNhelpLabelString\fP" Specifies the string label for the help button. The default for this resource depends on the locale. In the C locale the default is "Help". .nL .ne 12 .IP "\fIXmNmessageAlignment\fP" Controls the alignment of the message Label. Possible values include the following: .wH .rS .TP \(bu \fIXmALIGNMENT_BEGINNING\fP \- the default .TP \(bu \fIXmALIGNMENT_CENTER\fP .TP \(bu \fIXmALIGNMENT_END\fP .wH .rE .IP "\fIXmNmessageString\fP" Specifies the string to be used as the message. .IP "\fIXmNminimizeButtons\fP" Sets the buttons to the width of the widest button and height of the tallest button if False. If True, button width and height are set to the preferred size of each button. .IP "\fIXmNokCallback\fP" Specifies the list of callbacks that is called when the user clicks on the OK button. The reason sent by the callback is \fIXmCR_OK\fP. .IP "\fIXmNokLabelString\fP" Specifies the string label for the OK button. The default for this resource depends on the locale. In the C locale the default is "OK". .IP "\fIXmNsymbolPixmap\fP" Specifies the pixmap label to be used as the message symbol. .SS "Inherited Resources" MessageBox inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmBulletinBoard Resource Set Name Class Type Default Access _ XmNallowOverlap XmCAllowOverlap Boolean True CSG XmNautoUnmanage XmCAutoUnmanage Boolean True CG XmNbuttonFontList XmCButtonFontList XmFontList dynamic CSG XmNcancelButton XmCWidget Widget Cancel button SG XmNdefaultButton XmCWidget Widget dynamic SG XmNdefaultPosition XmCDefaultPosition Boolean True CSG XmNdialogStyle XmCDialogStyle unsigned char dynamic CSG XmNdialogTitle XmCDialogTitle XmString NULL CSG XmNfocusCallback XmCCallback XtCallbackList NULL C XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG XmNmapCallback XmCCallback XtCallbackList NULL C XmNmarginHeight XmCMarginHeight Dimension 10 CSG XmNmarginWidth XmCMarginWidth Dimension 10 CSG XmNnoResize XmCNoResize Boolean False CSG .wH .tH XmNresizePolicy XmCResizePolicy unsigned char XmRESIZE_ANY CSG XmNshadowType XmCShadowType unsigned char XmSHADOW_OUT CSG XmNtextFontList XmCTextFontList XmFontList dynamic CSG XmNtextTranslations XmCTranslations XtTranslations NULL C XmNunmapCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmManager Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget dynamic CSG XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension dynamic CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic N/A XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.50i .nf typedef struct { int \fBreason\fI; \fIXEvent \fB* event\fI; } XmAnyCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback .SS "Translations" .ne 20 XmMessageBox includes the translations from XmManager. .SS "Additional Behavior" The XmMessageBox widget has the additional behavior described below: .IP "\fIMAny\ KCancel\fP:" Calls the activate callbacks for the cancel button if it is sensitive. .IP "\fIKActivate\fP:" Calls the activate callbacks for the button with the keyboard focus. If no button has the keyboard focus, calls the activate callbacks for the default button if it is sensitive. .IP "\fI\fP:" Calls the callbacks for \fIXmNokCallback\fP. .IP "\fI\fP:" Calls the callbacks for \fIXmNcancelCallback\fP. .IP "\fI\fP:" Calls the callbacks for \fIXmNhelpCallback\fP. .IP "\fI\fP:" Calls the callbacks for \fIXmNfocusCallback\fP. .IP "\fI\fP:" Calls the callbacks for \fIXmNmapCallback\fP if the parent is a DialogShell. .IP "\fI\fP:" Calls the callbacks for \fIXmNunmapCallback\fP if the parent is a DialogShell. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .nL .ne 20 .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fIConstraint(3X)\fP, \fICore(3X)\fP, \fIXmBulletinBoard(3X)\fP, \fIXmCreateErrorDialog(3X)\fP, \fIXmCreateInformationDialog(3X)\fP, \fIXmCreateMessageBox(3X)\fP, \fIXmCreateMessageDialog(3X)\fP, \fIXmCreateQuestionDialog(3X)\fP, \fIXmCreateTemplateDialog(3X)\fP, \fIXmCreateWarningDialog(3X)\fP, \fIXmCreateWorkingDialog(3X)\fP, \fIXmManager(3X)\fP, and \fIXmMessageBoxGetChild(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmMessageBoxGetChild 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmMessageBoxGetChild\fP \- A MessageBox function that is used to access a component .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmMessageBoxGetChild (\fBwidget, child\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; unsigned char \fBchild\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmMessageBoxGetChild\fP is used to access a component within a MessageBox. The parameters given to the function are the MessageBox widget and a value indicating which component to access. .IP "\fBwidget\fP" Specifies the MessageBox widget ID. .IP "\fBchild\fP" Specifies a component within the MessageBox. The following are legal values for this parameter: .wH .rS .TP \(bu \fIXmDIALOG_CANCEL_BUTTON\fP .TP \(bu \fIXmDIALOG_DEFAULT_BUTTON\fP .TP \(bu \fIXmDIALOG_HELP_BUTTON\fP .TP \(bu \fIXmDIALOG_MESSAGE_LABEL\fP .TP \(bu \fIXmDIALOG_OK_BUTTON\fP .TP \(bu \fIXmDIALOG_SEPARATOR\fP .TP \(bu \fIXmDIALOG_SYMBOL_LABEL\fP .wH .rE .PP For a complete definition of MessageBox and its associated resources, see \fIXmMessageBox(3X)\fP. .SH RETURN VALUE Returns the widget ID of the specified MessageBox component. An application should not assume that the returned widget will be of any particular class. .SH RELATED INFORMATION .na \fIXmMessageBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmOptionButtonGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmOptionButtonGadget\fP \- A RowColumn function that obtains the widget ID for the CascadeButtonGadget in an OptionMenu .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmOptionButtonGadget (\fBoption_menu\fI) .ta .5i 1.5i .nf Widget \fBoption_menu\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmOptionButtonGadget\fP provides the application with the means for obtaining the widget ID for the internally created CascadeButtonGadget. Once the application has obtained the widget ID, it can adjust the visuals for the CascadeButtonGadget, if desired. .PP When an application creates an instance of the OptionMenu widget, the widget creates two internal gadgets. One is a LabelGadget that is used to display RowColumn's \fIXmNlabelString\fP resource. The other is a CascadeButtonGadget that displays the current selection and provides the means for posting the OptionMenu's submenu. .PP The user can specify resources in a resource file for the automatically created widgets and gadgets of an OptionMenu. The following list identifies the names of these widgets (or gadgets) and the associated OptionMenu areas. .TP \(bu .TP \(bu Option Menu Label Gadget \- "OptionLabel" .TP \(bu Option Menu Cascade Button \- "OptionButton" .IP "\fBoption_menu\fP" Specifies the OptionMenu widget ID .PP For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the widget ID for the internal button. .SH RELATED INFORMATION .na \fIXmCreateOptionMenu(3X)\fP, \fIXmCascadeButtonGadget(3X)\fP, \fIXmOptionLabelGadget(3X)\fP, and \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmOptionLabelGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmOptionLabelGadget\fP \- A RowColumn function that obtains the widget ID for the LabelGadget in an OptionMenu .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmOptionLabelGadget (\fBoption_menu\fI) .ta .5i 1.5i .nf Widget \fBoption_menu\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmOptionLabelGadget\fP provides the application with the means for obtaining the widget ID for the internally created LabelGadget. Once the application has obtained the widget ID, it can adjust the visuals for the LabelGadget, if desired. .PP When an application creates an instance of the OptionMenu widget, the widget creates two internal gadgets. One is a LabelGadget that is used to display RowColumn's \fIXmNlabelString\fP resource. The other is a CascadeButtonGadget that displays the current selection and provides the means for posting the OptionMenu's submenu. .PP The user can specify resources in a resource file for the automatically created widgets and gadgets of an OptionMenu. The following list identifies the names of these widgets (or gadgets) and the associated OptionMenu areas. .TP \(bu .TP \(bu Option Menu Label Gadget \- "OptionLabel" .TP \(bu Option Menu Cascade Button \- "OptionButton" .IP "\fBoption_menu\fP" Specifies the OptionMenu widget ID .PP For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the widget ID for the internal label. .SH RELATED INFORMATION .na \fIXmCreateOptionMenu(3X)\fP, \fIXmLabelGadget(3X)\fP, \fIXmOptionButtonGadget(3X)\fP, and \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1988 by Massachusetts Institute of Technology ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmPanedWindow 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmPanedWindow\fP \- The PanedWindow widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi PanedWindow is a composite widget that lays out children in a vertically tiled format. Children appear in top-to-bottom fashion, with the first child inserted appearing at the top of the PanedWindow and the last child inserted appearing at the bottom. The PanedWindow grows to match the width of its widest child and all other children are forced to this width. The height of the PanedWindow is equal to the sum of the heights of all its children, the spacing between them, and the size of the top and bottom margins. .PP The user can also adjust the size of the panes. To facilitate this adjustment, a pane control sash is created for most children. The sash appears as a square box positioned on the bottom of the pane that it controls. The user can adjust the size of a pane by using the mouse or keyboard. .PP The PanedWindow is also a constraint widget, which means that it creates and manages a set of constraints for each child. You can specify a minimum and maximum size for each pane. The PanedWindow does not allow a pane to be resized below its minimum size or beyond its maximum size. Also, when the minimum size of a pane is equal to its maximum size, no control sash is presented for that pane or for the lowest pane. .PP The default \fIXmNinsertPosition\fP procedure for PanedWindow causes sashes to be inserted at the end of the list of children and causes non-sash widgets to be inserted after other non-sash children but before any sashes. .PP All panes and sashes in a PanedWindow must be tab groups. When a pane is inserted as a child of the PanedWindow, if the pane's \fIXmNnavigationType\fP is not \fIXmEXCLUSIVE_TAB_GROUP\fP, PanedWindow sets it to \fIXmSTICKY_TAB_GROUP\fP. .SS "Classes" PanedWindow inherits behavior and resources from the \fICore\fP, \fIComposite\fP, \fIConstraint\fP, and \fIXmManager\fP classes. .PP The class pointer is \fIxmPanedWindowWidgetClass\fP. .PP The class name is \fIXmPanedWindow\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPanedWindow Resource Set Name Class Type Default Access _ XmNmarginHeight XmCMarginHeight Dimension 3 CSG XmNmarginWidth XmCMarginWidth Dimension 3 CSG XmNrefigureMode XmCBoolean Boolean True CSG XmNsashHeight XmCSashHeight Dimension 10 CSG XmNsashIndent XmCSashIndent Position -10 CSG XmNsashShadowThickness XmCShadowThickness Dimension dynamic CSG XmNsashWidth XmCSashWidth Dimension 10 CSG XmNseparatorOn XmCSeparatorOn Boolean True CSG XmNspacing XmCSpacing Dimension 8 CSG .TE .KE .in .sp 1 .IP "\fIXmNmarginHeight\fP" Specifies the distance between the top and bottom edges of the PanedWindow and its children. .IP "\fIXmNmarginWidth\fP" Specifies the distance between the left and right edges of the PanedWindow and its children. .IP "\fIXmNrefigureMode\fP" Determines whether the panes' positions are recomputed and repositioned when programmatic changes are being made to the PanedWindow. Setting this resource to True resets the children to their appropriate positions. .IP "\fIXmNsashHeight\fP" Specifies the height of the sash. .IP "\fIXmNsashIndent\fP" Specifies the horizontal placement of the sash along each pane. A positive value causes the sash to be offset from the near (left) side of the PanedWindow, and a negative value causes the sash to be offset from the far (right) side of the PanedWindow. If the offset is greater than the width of the PanedWindow minus the width of the sash, the sash is placed flush against the near side of the PanedWindow. .PP Whether the placement actually corresponds to the left or right side of the PanedWindow may depend on the value of the \fIXmNstringDirection\fP resource. .IP "\fIXmNsashShadowThickness\fP" Specifies the thickness of the shadows of the sashes. .IP "\fIXmNsashWidth\fP" Specifies the width of the sash. .IP "\fIXmNseparatorOn\fP" Determines whether a separator is created between each of the panes. Setting this resource to True creates a Separator at the midpoint between each of the panes. .IP "\fIXmNspacing\fP" Specifies the distance between each child pane. .ne 1.75i .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPanedWindow Constraint Resource Set Name Class Type Default Access _ XmNallowResize XmCBoolean Boolean False CSG XmNpaneMaximum XmCPaneMaximum Dimension 1000 CSG XmNpaneMinimum XmCPaneMinimum Dimension 1 CSG XmNpositionIndex XmCPositionIndex short XmLAST_POSITION CSG XmNskipAdjust XmCBoolean Boolean False CSG .TE .KE .in .sp 1 .IP "\fIXmNallowResize\fP" Allows an application to specify whether the PanedWindow should allow a pane to request to be resized. This flag has an effect only after the PanedWindow and its children have been realized. If this flag is set to True, the PanedWindow tries to honor requests to alter the height of the pane. If False, it always denies pane requests to resize. .IP "\fIXmNpaneMaximum\fP" Allows an application to specify the maximum size to which a pane may be resized. This value must be greater than the specified minimum. .IP "\fIXmNpaneMinimum\fP" Allows an application to specify the minimum size to which a pane may be resized. This value must be greater than 0. .IP "\fIXmNpositionIndex\fP" Specifies the position of the widget in its parent's list of children (the list of pane children, not including sashes). The value is an integer that is no less than zero and no greater than the number of children in the list at the time the value is specified. A value of zero means that the child is placed at the beginning of the list. The value can also be specified as \fIXmLAST_POSITION\fP (the default), which means that the child is placed at the end of the list. Any other value is ignored. \fIXtGetValues\fP returns the position of the widget in its parent's child list at the time of the call to \fIXtGetValues\fP. .PP When a widget is inserted into its parent's child list, the positions of any existing children that are greater than or equal to the specified widget's \fIXmNpositionIndex\fP are increased by one. The effect of a call to \fIXtSetValues\fP for \fIXmNpositionIndex\fP is to remove the specified widget from its parent's child list, decrease by one the positions of any existing children that are greater than the specified widget's former position in the list, and then insert the specified widget into its parent's child list as described in the preceding sentence. .IP "\fIXmNskipAdjust\fP" When set to True, this Boolean resource allows an application to specify that the PanedWindow should not automatically resize this pane. .SS "Inherited Resources" PanedWindow inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmManager Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget NULL CSG XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc default procedure CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .SS "Translations" XmPanedWindow inherits translations from XmManager. .PP The translations for sashes within the PanedWindow are listed below. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BSelect Press: SashAction(Start) BSelect Motion: SashAction(Move) BSelect Release: SashAction(Commit) .sp \n(PDu BDrag Press: SashAction(Start) BDrag Motion: SashAction(Move) BDrag Release: SashAction(Commit) .sp \n(PDu KUp: SashAction(Key,DefaultIncr,Up) MCtrl KUp: SashAction(Key,LargeIncr,Up) .sp \n(PDu KDown: SashAction(Key,DefaultIncr,Down) MCtrl KDown: SashAction(Key,LargeIncr,Down) .sp \n(PDu KNextField: NextTabGroup() KPrevField: PrevTabGroup() .sp \n(PDu KHelp: Help() .wH .fi .iE .SS "Action Routines" The XmPanedWindow action routines are described below: .IP "\fIHelp()\fP:" Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fINextTabGroup()\fP:" Moves the keyboard focus to the next tab group. By default each pane and sash is a tab group. .IP "\fIPrevTabGroup()\fP:" Moves the keyboard focus to the previous tab group. By default each pane and sash is a tab group. .IP "\fISashAction(\fBaction\fI)\fP\ or\ \fISashAction(Key,\fBincrement\fI,\fBdirection\fI)\fP:" The \fIStart\fP action activates the interactive placement of the pane's borders. The \fIMove\fP action causes the sash to track the position of the pointer. If one of the panes reaches its minimum or maximum size, adjustment continues with the next adjustable pane. The \fICommit\fP action ends sash motion. .P When sash action is caused by a keyboard event, the sash with the keyboard focus is moved according to the \fBincrement\fP and \fBdirection\fP specified. \fIDefaultIncr\fP adjusts the sash by one line. \fILargeIncr\fP adjusts the sash by one view region. The \fBdirection\fP is specified as either \fIUp\fP or \fIDown\fP. .P Note that the SashAction action routine is not a direct action routine of the XmPanedWindow, but rather an action of the Sash control created by the XmPanedWindow. .SS "Additional Behavior" This widget has the additional behavior described below: .IP "\fI\fP:" Moves the keyboard focus to the sash and highlights it. .IP "\fI\fP:" Unsets the keyboard focus in the sash and unhighlights it. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fIConstraint(3X)\fP, \fICore(3X)\fP, \fIXmCreatePanedWindow(3X)\fP, and \fIXmManager(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmPrimitive 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmPrimitive\fP \- The Primitive widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi Primitive is a widget class used as a supporting superclass for other widget classes. It handles border drawing and highlighting, traversal activation and deactivation, and various callback lists needed by Primitive widgets. .SS "Classes" Primitive inherits behavior and resources from \fICore\fP class. .PP The class pointer is \fIxmPrimitiveWidgetClass\fP. .PP The class name is \fIXmPrimitive\fP. .nL .ne 12 .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPrimitive Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG .wH .tH XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .nL .ne 3 .IP "\fIXmNbottomShadowColor\fP" Specifies the color to use to draw the bottom and right sides of the border shadow. This color is used if the \fIXmNtopShadowPixmap\fP resource is unspecified. .IP "\fIXmNbottomShadowPixmap\fP" Specifies the pixmap to use to draw the bottom and right sides of the border shadow. .IP "\fIXmNforeground\fP" Specifies the foreground drawing color used by Primitive widgets. .IP "\fIXmNhelpCallback\fP" Specifies the list of callbacks that is called when the help key is pressed. The reason sent by the callback is \fIXmCR_HELP\fP. .IP "\fIXmNhighlightColor\fP" Specifies the color of the highlighting rectangle. This color is used if the highlight pixmap resource is \fIXmUNSPECIFIED_PIXMAP\fP. .IP "\fIXmNhighlightOnEnter\fP" Specifies if the highlighting rectangle is drawn when the cursor moves into the widget. If the shell's focus policy is \fIXmEXPLICIT\fP, this resource is ignored, and the widget is highlighted when it has the focus. If the shell's focus policy is \fIXmPOINTER\fP and if this resource is True, the highlighting rectangle is drawn when the the cursor moves into the widget. If the shell's focus policy is \fIXmPOINTER\fP and if this resource is False, the highlighting rectangle is not drawn when the the cursor moves into the widget. The default is False. .IP "\fIXmNhighlightPixmap\fP" Specifies the pixmap used to draw the highlighting rectangle. .IP "\fIXmNhighlightThickness\fP" Specifies the thickness of the highlighting rectangle. .IP "\fIXmNnavigationType\fP" Determines whether the widget is a tab group. .wH .rS .TP \(bu \fIXmNONE\fP indicates that the widget is not a tab group. .TP \(bu \fIXmTAB_GROUP\fP indicates that the widget is a tab group, unless another widget in the hierarchy has an \fIXmNnavigationType\fP of \fIXmEXCLUSIVE_TAB_GROUP\fP. .TP \(bu \fIXmSTICKY_TAB_GROUP\fP indicates that the widget is a tab group, even if another widget in the hierarchy has an \fIXmNnavigationType\fP of \fIXmEXCLUSIVE_TAB_GROUP\fP. .TP \(bu \fIXmEXCLUSIVE_TAB_GROUP\fP indicates that the widget is a tab group and that widgets in the hierarchy whose \fIXmNnavigationType\fP is \fIXmTAB_GROUP\fP are not tab groups. .IP When a parent widget has an \fIXmNnavigationType\fP of \fIXmEXCLUSIVE_TAB_GROUP\fP, traversal of non-tab-group widgets within the group is based on the order of those widgets in their parent's \fIXmNchildren\fP list. .IP When any widget in a hierarchy has an \fIXmNnavigationType\fP of \fIXmEXCLUSIVE_TAB_GROUP\fP, traversal of tab groups in the hierarchy proceeds to widgets in the order in which their \fIXmNnavigationType\fP resources were specified as \fIXmEXCLUSIVE_TAB_GROUP\fP or \fIXmSTICKY_TAB_GROUP\fP, whether by creating the widgets with that value, by calling \fIXtSetValues\fP, or by calling \fIXmAddTabGroup\fP. .wH .rE .IP "\fIXmNshadowThickness\fP" Specifies the size of the drawn border shadow. .IP "\fIXmNtopShadowColor\fP" Specifies the color to use to draw the top and left sides of the border shadow. This color is used if the \fIXmNtopShadowPixmap\fP resource is unspecified. .IP "\fIXmNtopShadowPixmap\fP" Specifies the pixmap to use to draw the top and left sides of the border shadow. .IP "\fIXmNtraversalOn\fP" Specifies if traversal is activated for this widget. In CascadeButton and CascadeButtonGadget, this resource is forced to TRUE unless the parent is an OptionMenu. .IP "\fIXmNunitType\fP" Provides the basic support for resolution independence. It defines the type of units a widget uses with sizing and positioning resources. If the widget's parent is a subclass of \fIXmManager\fP and if the \fIXmNunitType\fP resource is not explicitly set, it defaults to the unit type of the parent widget. If the widget's parent is not a subclass of \fIXmManager\fP, the resource has a default unit type of \fIXmPIXELS\fP. .IP \fIXmNunitType\fP can have the following values: .wH .rS .TP \(bu \fIXmPIXELS\fP \- all values provided to the widget are treated as normal pixel values. .TP \(bu \fIXm100TH_MILLIMETERS\fP \- all values provided to the widget are treated as 1/100 millimeter. .TP \(bu \fIXm1000TH_INCHES\fP \- all values provided to the widget are treated as 1/1000 inch. .TP \(bu \fIXm100TH_POINTS\fP \- all values provided to the widget are treated as 1/100 point. A point is a unit used in text processing applications and is defined as 1/72 inch. .TP \(bu \fIXm100TH_FONT_UNITS\fP \- all values provided to the widget are treated as 1/100 of a font unit. A font unit has horizontal and vertical components. These are the values of the XmScreen resources \fIXmNhorizontalFontUnit\fP and \fIXmNverticalFontUnit\fP. .IP "\fIXmNuserData\fP" Allows the application to attach any necessary specific data to the widget. It is an internally unused resource. .SS "Dynamic Color Defaults" The foreground, background, top shadow, bottom shadow, and highlight color resources are dynamically defaulted. If no color data is specified, the colors are automatically generated. On a single-plane system, a black and white color scheme is generated. Otherwise, four colors are generated, which display the correct shading for the 3-D visuals. If the background is the only color specified for a widget, the top shadow and bottom shadow colors are generated to give the 3-D appearance. Foreground and highlight colors are generated to provide sufficient contrast with the background color. .IP Colors are generated only at creation. Resetting the background through \fIXtSetValues\fP does not regenerate the other colors. \fIXmChangeColor\fP can be used to recalculate all associated colors based on a new background color. .SS "Inherited Resources" Primitive inherits behavior and resources from the following superclass. For a complete description of each resource, refer to the man page for that superclass. .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.50i .nf typedef struct { int \fBreason\fI; \fIXEvent \fB* event\fI; } XmAnyCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. For this callback, \fBreason\fP is set to \fIXmCR_HELP\fP. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .SS "Translations" The XmPrimitive translations are listed below. Some of these translations may be affected by the XmDisplay's \fIenableMultiKeyBindings\fP resource: see XmDisplay(3X). These translations may not directly correspond to a translation table. .IP Note that for buttons in menus, altering translations in \fI#override\fP or \fI#augment\fP mode is undefined. .iS .ta 1.5i .nf KUp: PrimitiveTraverseUp() KDown: PrimitiveTraverseDown() KLeft: PrimitiveTraverseLeft() KRight: PrimitiveTraverseRight() .sp \n(PDu KBeginLine: PrimitiveTraverseHome() .sp \n(PDu KNextField: PrimitiveNextTabGroup() KPrevField: PrimitivePrevTabGroup() .sp \n(PDu KActivate: PrimitiveParentActivate() KCancel: PrimitiveParentCancel() .sp \n(PDu KHelp: PrimitiveHelp() .wH .fi .iE .SS "Action Routines" The XmPrimitive action routines are described below: .IP "\fIPrimitiveHelp()\fP:" Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIPrimitiveNextTabGroup()\fP:" This action depends on the value of the XmDisplay resource \fIenableButtonTab\fP. .IP When \fIenableButtonTab\fP is False (the default), this action traverses to the first item in the next tab group. If the current tab group is the last entry in the tab group list, it wraps to the beginning of the tab group list. .IP When \fIenableButtonTab\fP is True, this action will move to the next item within the current tab group unless it is the last item in the tab group. When the item is the last in the group, the action traverses to the first item in the next tab group. The \fIenableButtonTab\fP behavior applies only to XmPushButton, XmArrow, and XmDrawnButton. .IP "\fIPrimitiveParentActivate()\fP:" If the parent is a manager, passes the \fIKActivate\fP event received by the widget to the parent. .IP "\fIPrimitiveParentCancel()\fP:" If the parent is a manager, Passes the \fIKCancel\fP event received by the widget to the parent. .IP "\fIPrimitivePrevTabGroup()\fP:" This action depends on the value of the XmDisplay resource \fIenableButtonTab\fP. .IP When \fIenableButtonTab\fP is False (the default), this action traverses to the first item in the previous tab group. If the beginning of the tab group list is reached, it wraps to the end of the tab group list. .IP When \fIenableButtonTab\fP is True, this action will move to the previous item within the current tab group unless it is the first item in the tab group. When the item is the first in the group, the action traverses to the first item in the previous tab group. The \fIenableButtonTab\fP behavior applies only to XmPushButton, XmArrow, and XmDrawnButton. .IP "\fIPrimitiveTraverseDown()\fP:" Traverses to the next item below the current widget in the current tab group, wrapping if necessary. .IP "\fIPrimitiveTraverseHome()\fP:" Traverses to the first widget or gadget in the current tab group. .IP "\fIPrimitiveTraverseLeft()\fP:" Traverses to the next item to the left of the current widget in the current tab group, wrapping if necessary. .IP "\fIPrimitiveTraverseNext()\fP:" Traverses to the next item in the current tab group, wrapping if necessary. .IP "\fIPrimitiveTraversePrev()\fP:" Traverses to the previous item in the current tab group, wrapping if necessary. .nL .ne 10 .IP "\fIPrimitiveTraverseRight()\fP:" Traverses to the next item to the right of the current gadget in the current tab group, wrapping if necessary. .nL .ne 3 .IP "\fIPrimitiveTraverseUp()\fP:" Traverses to the next item above the current gadget in the current tab group, wrapping if necessary. .SS "Additional Behavior" This widget has the additional behavior described below: .IP "\fI\fP:" If the shell's keyboard focus policy is \fIXmEXPLICIT\fP, highlights the widget and gives it the focus. .IP "\fI\fP:" If the shell's keyboard focus policy is \fIXmEXPLICIT\fP, unhighlights the widget and removes the focus. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fICore(3X)\fP, \fIXmChangeColor(3X)\fP, \fIXmDisplay(3X)\fP, and \fIXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmProcessTraversal 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmProcessTraversal\fP \- A function that determines which component receives keyboard events when a widget has the focus .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmProcessTraversal (\fBwidget, direction\fI) .ta .5i 2i .nf Widget \fBwidget\fI; XmTraversalDirection \fBdirection\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmProcessTraversal\fP determines which component of a hierarchy receives keyboard events when the hierarchy that contains the given widget has keyboard focus. Using \fIXmProcessTraversal\fP to traverse to MenuBars, Pulldown MenuPanes, or Popup MenuPanes is not supported. .IP "\fBwidget\fP" Specifies the widget ID of the widget whose hierarchy is to be traversed. The hierarchy is only traversed up to the top of the shell. If that shell does not currently have the focus, any changes to the element with focus within that shell will not occur until the next time the shell recieves focus. .IP "\fBdirection\fP" Specifies the direction of traversal .PP .ne 5 The \fBdirection\fP parameter can have the following values, which cause the routine to take the corresponding actions: .TP \(bu \fIXmTRAVERSE_CURRENT\fP \- Finds the hierarchy and the tab group that contain \fBwidget\fP. If this tab group is not the active tab group, makes it the active tab group. If \fBwidget\fP is an item in the active tab group, makes it the active item. If \fBwidget\fP is the active tab group, makes the first traversable item in the tab group the active item. .TP \(bu \fIXmTRAVERSE_DOWN\fP \- Finds the hierarchy that contains \fBwidget\fP. Finds the active item in the active tab group and makes the item below it the active item. If there is no item below, wraps. .TP \(bu \fIXmTRAVERSE_HOME\fP \- Finds the hierarchy that contains \fBwidget\fP. Finds the active item in the active tab group and makes the first traversable item in the tab group the active item. .TP \(bu \fIXmTRAVERSE_LEFT\fP \- Finds the hierarchy that contains \fBwidget\fP. Finds the active item in the active tab group and makes the item to the left the active item. If there is no item to the left, wraps. .TP \(bu \fIXmTRAVERSE_NEXT\fP \- Finds the hierarchy that contains \fBwidget\fP. Finds the active item in the active tab group and makes the next item in child order the active item. .TP \(bu \fIXmTRAVERSE_NEXT_TAB_GROUP\fP \- Finds the hierarchy that contains \fBwidget\fP. Finds the active tab group (if any) and makes the next tab group the active tab group in the hierarchy. .TP \(bu \fIXmTRAVERSE_PREV\fP \- Finds the hierarchy that contains \fBwidget\fP. Finds the active item in the active tab group and makes the previous item in child order the active item. .TP \(bu \fIXmTRAVERSE_PREV_TAB_GROUP\fP \- Finds the hierarchy that contains \fBwidget\fP. Finds the active tab group (if any) and makes the previous tab group the active tab group in the hierarchy. .TP \(bu \fIXmTRAVERSE_RIGHT\fP \- Finds the hierarchy that contains \fBwidget\fP. Finds the active item in the active tab group and makes the item to the right the active item. If there is no item to the right, wraps. .TP \(bu \fIXmTRAVERSE_UP\fP \- Finds the hierarchy that contains \fBwidget\fP. Finds the active item in the active tab group and makes the item above it the active item. If there is no item above, wraps. .SS CAUTIONS .TP \(bu \fIXmProcessTraversal\fP will not allow traversal to a widget in a different shell. .TP \(bu \fIXmProcessTraversal\fP will only allow traversal to widgets that are currently mapped. .TP \(bu You cannot call \fIXmProcessTraversal\fP from inside a focusCallback routine (or you will get a segmentation fault). .SH RETURN VALUE Returns True if the setting succeeded. Returns False if the keyboard focus policy is not \fIXmEXPLICIT\fP, if there are no traversable items, or if the call to the routine has invalid parameters. .SH RELATED INFORMATION .na \fIXmGetVisibility(3X)\fP and \fIXmIsTraversable(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmPushButton 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmPushButton\fP \- The PushButton widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi PushButton issues commands within an application. It consists of a text label or pixmap surrounded by a border shadow. When a PushButton is selected, the shadow changes to give the appearance that it has been pressed in. When a PushButton is unselected, the shadow changes to give the appearance that it is out. .PP The default behavior associated with a PushButton in a menu depends on the type of menu system in which it resides. By default, \fIBSelect\fP controls the behavior of the PushButton. In addition, \fIBMenu\fP controls the behavior of the PushButton if it resides in a Menu system. The actual mouse button used is determined by its RowColumn parent. .PP Thickness for a second shadow, used when the PushButton is the default button, may be specified by using the \fIXmNshowAsDefault\fP resource. If it has a non-zero value, the Label's resources \fIXmNmarginLeft\fP, \fIXmNmarginRight\fP, \fIXmNmarginTop\fP, and \fIXmNmarginBottom\fP may be modified to accommodate the second shadow. .PP If an initial value is specified for \fIXmNarmPixmap\fP but not for \fIXmNlabelPixmap\fP, the \fIXmNarmPixmap\fP value is used for \fIXmNlabelPixmap\fP. .SS "Classes" PushButton inherits behavior and resources from \fICore\fP, \fIXmPrimitive\fP, and \fIXmLabel\fP Classes. .PP The class pointer is \fIxmPushButtonWidgetClass\fP. .PP The class name is \fIXmPushButton\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPushButton Resource Set Name Class Type Default Access _ XmNactivateCallback XmCCallback XtCallbackList NULL C XmNarmCallback XmCCallback XtCallbackList NULL C XmNarmColor XmCArmColor Pixel dynamic CSG XmNarmPixmap XmCArmPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNdefaultButtonShadowThickness XmCDefaultButtonShadowThickness Dimension dynamic CSG XmNdisarmCallback XmCCallback XtCallbackList NULL C XmNfillOnArm XmCFillOnArm Boolean True CSG XmNmultiClick XmCMultiClick unsigned char dynamic CSG XmNshowAsDefault XmCShowAsDefault Dimension 0 CSG .TE .KE .in .sp 1 .wH .in .IP "\fIXmNactivateCallback\fP" Specifies the list of callbacks that is called when PushButton is activated. PushButton is activated when the user presses and releases the active mouse button while the pointer is inside that widget. Activating the PushButton also disarms it. For this callback the reason is \fIXmCR_ACTIVATE\fP. .IP "\fIXmNarmCallback\fP" Specifies the list of callbacks that is called when PushButton is armed. PushButton is armed when the user presses the active mouse button while the pointer is inside that widget. For this callback the reason is \fIXmCR_ARM\fP. .nL .ne 3 .IP "\fIXmNarmColor\fP" Specifies the color with which to fill the armed button. \fIXmNfillOnArm\fP must be set to True for this resource to have an effect. The default for a color display is a color between the background and the bottom shadow color. For a monochrome display, the default is set to the foreground color, and any text in the label appears in the background color when the button is armed. .IP "\fIXmNarmPixmap\fP" Specifies the pixmap to be used as the button face if \fIXmNlabelType\fP is \fIXmPIXMAP\fP and PushButton is armed. This resource is disabled when the PushButton is in a menu. .IP "\fIXmNdefaultButtonShadowThickness\fP" This resource specifies the width of the default button indicator shadow. If this resource is zero, the width of the shadow comes from the value of the \fIXmNshowAsDefault\fP resource. If this resource is greater than zero, the \fIXmNshowAsDefault\fP resource is only used to specify whether this button is the default. The default value is the initial value of \fIXmNshowAsDefault\fP. .IP "\fIXmNdisarmCallback\fP" Specifies the list of callbacks that is called when PushButton is disarmed. PushButton is disarmed when the user presses and releases the active mouse button while the pointer is inside that widget. For this callback, the reason is \fIXmCR_DISARM\fP. .IP "\fIXmNfillOnArm\fP" Forces the PushButton to fill the background of the button with the color specified by \fIXmNarmColor\fP when the button is armed and when this resource is set to True. If False, only the top and bottom shadow colors are switched. When the PushButton is in a menu, this resource is ignored and assumed to be False. .IP "\fIXmNmultiClick\fP" If a button click is followed by another button click within the time span specified by the display's multi-click time, and this resource is set to \fIXmMULTICLICK_DISCARD\fP, do not process the second click. If this resource is set to \fIXmMULTICLICK_KEEP\fP, process the event and increment \fBclick_count\fP in the callback structure. When the button is in a menu, the default is \fIXmMULTICLICK_DISCARD\fP; otherwise, for a button not in a menu, \fIXmMULTICLICK_KEEP\fP is the default value. .IP "\fIXmNshowAsDefault\fP" If \fIXmNdefaultButtonShadowThickness\fP is greater than zero, a value greater than zero in this resource specifies to mark this button as the default button. If \fIXmNdefaultButtonShadowThickness\fP is zero, a value greater than zero in this resource specifies to mark this button as the default button with the shadow thickness specified by this resource. The space between the shadow and the default shadow is equal to the sum of both shadows. The default value is zero. .IP When the XmDisplay resource \fIdefaultButtonEmphasis\fP is "external_highlight" (the default), the PushButton draws the location cursor outside of the outer shadow. When this resource is "internal_highlight", the highlight is drawn between the inner and outer shadows. .IP When the \fIXmNshowAsDefault\fP value is not zero, the Label resources \fIXmNmarginLeft\fP, \fIXmNmarginRight\fP, \fIXmNmarginTop\fP, and \fIXmNmarginBottom\fP may be modified to accommodate the second shadow. This resource is disabled when the PushButton is in a menu. .SS "Inherited Resources" PushButton inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmLabel Resource Set Name Class Type Default Access _ XmNaccelerator XmCAccelerator String NULL CSG XmNacceleratorText XmCAcceleratorText XmString NULL CSG XmNalignment XmCAlignment unsigned char dynamic CSG XmNfontList XmCFontList XmFontList dynamic CSG XmNlabelInsensitivePixmap XmCLabelInsensitivePixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelPixmap XmCLabelPixmap Pixmap dynamic CSG XmNlabelString XmCXmString XmString dynamic CSG XmNlabelType XmCLabelType unsigned char XmSTRING CSG XmNmarginBottom XmCMarginBottom Dimension dynamic CSG XmNmarginHeight XmCMarginHeight Dimension 2 CSG XmNmarginLeft XmCMarginLeft Dimension dynamic CSG XmNmarginRight XmCMarginRight Dimension dynamic CSG XmNmarginTop XmCMarginTop Dimension dynamic CSG XmNmarginWidth XmCMarginWidth Dimension 2 CSG .wH .tH XmNmnemonic XmCMnemonic KeySym NULL CSG XmNmnemonicCharSet XmCMnemonicCharSet String XmFONTLIST_DEFAULT_TAG CSG XmNrecomputeSize XmCRecomputeSize Boolean True CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CSG .TE .KE .in .sp 1 .wH .in .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPrimitive Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG .wH .tH XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.1i .nf typedef struct { int \fBreason\fI; XEvent \fB* event\fI; int \fBclick_count\fI; } XmPushButtonCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBclick_count\fP" This value is valid only when the reason is \fIXmCR_ACTIVATE\fP. It contains the number of clicks in the last multiclick sequence if the \fIXmNmultiClick\fP resource is set to \fIXmMULTICLICK_KEEP\fP, otherwise it contains \fI1\fP. The activate callback is invoked for each click if \fIXmNmultiClick\fP is set to \fIXmMULTICLICK_KEEP\fP. .SS "Translations" XmPushButton includes translations from Primitive. .PP Note that altering translations in \fI#override\fP or \fI#augment\fP mode is undefined. .PP Additional XmPushButton translations for XmPushButtons not in a menu system are listed below. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BDrag Press: ProcessDrag() .sp \n(PDu BSelect Press: Arm() BSelect Click: Activate() Disarm() BSelect Release: Activate() Disarm() BSelect Press 2+: MultiArm() BSelect Release 2+: MultiActivate() Disarm() KSelect: ArmAndActivate() KHelp: Help() .wH .fi .iE .PP XmPushButton inherits menu traversal translations from XmLabel. Additional XmPushButton translations for PushButtons in a menu system are listed below. In a menu system, \fIBMenu\fP also performs the \fIBSelect\fP actions. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BSelect Press: BtnDown() BSelect Release: BtnUp() KActivate: ArmAndActivate() KSelect: ArmAndActivate() MAny KCancel: MenuShellPopdownOne() .wH .fi .iE .SS "Action Routines" The XmPushButton action routines are described below: .IP "\fIActivate()\fP:" This action draws the shadow in the unarmed state. If the button is not in a menu and if \fIXmNfillOnArm\fP is set to True, the background color reverts to the unarmed color. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNlabelPixmap\fP is used for the button face. If the pointer is still within the button, this action calls the callbacks for \fIXmNactivateCallback\fP. .IP "\fIArm()\fP:" This action arms the PushButton. It draws the shadow in the armed state. If the button is not in a menu and if \fIXmNfillOnArm\fP is set to True, it fills the button with the color specified by \fIXmNarmColor\fP. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNarmPixmap\fP is used for the button face. It calls the \fIXmNarmCallback\fP callbacks. .IP "\fIArmAndActivate()\fP:" In a menu, does the following: Unposts all menus in the menu hierarchy. Unless the button is already armed, calls the \fIXmNarmCallback\fP callbacks. Calls the \fIXmNactivateCallback\fP and \fIXmNdisarmCallback\fP callbacks. .IP Outside a menu, does the following: Draws the shadow in the armed state and, if \fIXmNfillOnArm\fP is set to True, fills the button with the color specified by \fIXmNarmColor\fP. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNarmPixmap\fP is used for the button face. Calls the \fIXmNarmCallback\fP callbacks. .IP Outside a menu, this action also arranges for the following to happen, either immediately or at a later time: The shadow is drawn in the unarmed state and, if \fIXmNfillOnArm\fP is set to True, the background color reverts to the unarmed color. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNlabelPixmap\fP is used for the button face. The \fIXmNactivateCallback\fP and \fIXmNdisarmCallback\fP callbacks are called. .IP "\fIBtnDown()\fP:" This action unposts any menus posted by the PushButton's parent menu, disables keyboard traversal for the menu, and enables mouse traversal for the menu. It draws the shadow in the armed state and, unless the button is already armed, calls the \fIXmNarmCallback\fP callbacks. .nL .ne 5 .IP "\fIBtnUp()\fP:" This action unposts all menus in the menu hierarchy and activates the PushButton. It calls the \fIXmNactivateCallback\fP callbacks and then the \fIXmNdisarmCallback\fP callbacks. .IP "\fIDisarm()\fP:" Calls the callbacks for \fIXmNdisarmCallback\fP. .IP "\fIHelp()\fP:" In a Pulldown or Popup MenuPane, unposts all menus in the menu hierarchy and, when the shell's keyboard focus policy is \fIXmEXPLICT\fP, restores keyboard focus to the widget that had the focus before the menu system was entered. Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIMenuShellPopdownOne()\fP:" In a toplevel Pulldown MenuPane from a MenuBar, unposts the menu, disarms the MenuBar CascadeButton and the MenuBar, and, when the shell's keyboard focus policy is \fIXmEXPLICT\fP, restores keyboard focus to the widget that had the focus before the MenuBar was entered. In other Pulldown MenuPanes, unposts the menu. .IP In a Popup MenuPane, unposts the menu and restores keyboard focus to the widget from which the menu was posted. .IP "\fIMultiActivate()\fP:" If \fIXmNmultiClick\fP is \fIXmMULTICLICK_DISCARD\fP, this action does nothing. .IP If \fIXmNmultiClick\fP is \fIXmMULTICLICK_KEEP\fP, this action does the following: Increments \fBclick_count\fP in the callback structure. Draws the shadow in the unarmed state. If the button is not in a menu and if \fIXmNfillOnArm\fP is set to True, the background color reverts to the unarmed color. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNlabelPixmap\fP is used for the button face. If the pointer is within the PushButton, calls the callbacks for \fIXmNactivateCallback\fP. Calls the callbacks for \fIXmNdisarmCallback\fP. .IP "\fIMultiArm()\fP:" If \fIXmNmultiClick\fP is \fIXmMULTICLICK_DISCARD\fP, this action does nothing. .IP If \fIXmNmultiClick\fP is \fIXmMULTICLICK_KEEP\fP, this action does the following: Draws the shadow in the armed state. If the button is not in a menu and if \fIXmNfillOnArm\fP is set to True, fills the button with the color specified by \fIXmNarmColor\fP. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNarmPixmap\fP is used for the button face. Calls the \fIXmNarmCallback\fP callbacks. .IP "\fIProcessDrag()\fP:" Drags the contents of a PushButton label, identified by pressing \fIBDrag\fP. This action creates a DragContext object whose \fIXmNexportTargets\fP resource is set to "COMPOUND_TEXT" for a label type of \fIXmSTRING\fP; otherwise, "PIXMAP" if the label type is \fIXmPIXMAP\fP. This action is undefined for PushButtons used in a menu system. .IP This action is disabled if the XmDisplay's \fIenableUnselectableDrag\fP resource is True. .SS "Additional Behavior" This widget has the additional behavior described below: .IP "\fI\fP:" In a menu, if keyboard traversal is enabled, this action does nothing. Otherwise, it draws the shadow in the armed state and calls the \fIXmNarmCallback\fP callbacks. .IP If the PushButton is not in a menu and the cursor leaves and then reenters the PushButton's window while the button is pressed, this action draws the shadow in the armed state. If \fIXmNfillOnArm\fP is set to True, it also fills the button with the color specified by \fIXmNarmColor\fP. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNarmPixmap\fP is used for the button face. .IP "\fI\fP:" In a menu, if keyboard traversal is enabled, this action does nothing. Otherwise, it draws the shadow in the unarmed state and calls the \fIXmNdisarmCallback\fP callbacks. .IP If the PushButton is not in a menu and the cursor leaves the PushButton's window while the button is pressed, this action draws the shadow in the unarmed state. If \fIXmNfillOnArm\fP is set to True, the background color reverts to the unarmed color. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNlabelPixmap\fP is used for the button face. .ne 8 .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fICore(3X)\fP, \fIXmCreatePushButton(3X)\fP, \fIXmDisplay(3X)\fP, \fIXmLabel(3X)\fP, \fIXmPrimitive(3X)\fP, and \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmPushButtonGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmPushButtonGadget\fP \- The PushButtonGadget widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi PushButtonGadget issues commands within an application. It consists of a text label or pixmap surrounded by a border shadow. When PushButtonGadget is selected, the shadow changes to give the appearance that the PushButtonGadget has been pressed in. When PushButtonGadget is unselected, the shadow changes to give the appearance that the PushButtonGadget is out. .PP The default behavior associated with a PushButtonGadget in a menu depends on the type of menu system in which it resides. By default, \fIBSelect\fP controls the behavior of the PushButtonGadget. In addition, \fIBMenu\fP controls the behavior of the PushButtonGadget if it resides in a Menu system. The actual mouse button used is determined by its RowColumn parent. .PP Thickness for a second shadow may be specified by using the \fIXmNshowAsDefault\fP resource. If it has a non-zero value, the Label's resources \fIXmNmarginLeft\fP, \fIXmNmarginRight\fP, \fIXmNmarginTop\fP, and \fIXmNmarginBottom\fP may be modified to accommodate the second shadow. .PP If an initial value is specified for \fIXmNarmPixmap\fP but not for \fIXmNlabelPixmap\fP, the \fIXmNarmPixmap\fP value is used for \fIXmNlabelPixmap\fP. .SS "Classes" PushButtonGadget inherits behavior and resources from \fIObject\fP, \fIRectObj\fP, \fIXmGadget\fP and \fIXmLabelGadget\fP classes. .PP The class pointer is \fIxmPushButtonGadgetClass\fP. .PP The class name is \fIXmPushButtonGadget\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPushButtonGadget Name Class Type Default Access _ XmNactivateCallback XmCCallback XtCallbackList NULL C XmNarmCallback XmCCallback XtCallbackList NULL C XmNarmColor XmCArmColor Pixel dynamic CSG XmNarmPixmap XmCArmPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNdefaultButtonShadowThickness XmCDefaultButtonShadowThickness Dimension dynamic CSG XmNdisarmCallback XmCCallback XtCallbackList NULL C XmNfillOnArm XmCFillOnArm Boolean True CSG XmNmultiClick XmCMultiClick unsigned char dynamic CSG XmNshowAsDefault XmCShowAsDefault Dimension 0 CSG .TE .KE .in .sp 1 .wH .in .IP "\fIXmNactivateCallback\fP" Specifies the list of callbacks that is called when the PushButtonGadget is activated. It is activated when the user presses and releases the active mouse button while the pointer is inside the PushButtonGadget. Activating PushButtonGadget also disarms it. For this callback the reason is \fIXmCR_ACTIVATE\fP. .IP "\fIXmNarmCallback\fP" Specifies the list of callbacks that is called when PushButtonGadget is armed. It is armed when the user presses the active mouse button while the pointer is inside the PushButtonGadget. For this callback the reason is \fIXmCR_ARM\fP. .IP "\fIXmNarmColor\fP" Specifies the color with which to fill the armed button. \fIXmNfillOnArm\fP must be set to True for this resource to have an effect. The default for a color display is a color between the background and the bottom shadow color. For a monochrome display, the default is set to the foreground color, and any text in the label appears in the background color when the button is armed. .IP "\fIXmNarmPixmap\fP" Specifies the pixmap to be used as the button face if \fIXmNlabeltype\fP is \fIXmPIXMAP\fP and PushButtonGadget is armed. This resource is disabled when the PushButtonGadget is in a menu. .IP "\fIXmNdefaultButtonShadowThickness\fP" This resource specifies the width of the default button indicator shadow. If this resource is zero, the width of the shadow comes from the value of the \fIXmNshowAsDefault\fP resource. If this resource is greater than zero, the \fIXmNshowAsDefault\fP resource is only used to specify whether this button is the default. The default value is the initial value of \fIXmNshowAsDefault\fP. .IP "\fIXmNdisarmCallback\fP" Specifies the list of callbacks that is called when the PushButtonGadget is disarmed. PushButtonGadget is disarmed when the user presses and releases the active mouse button while the pointer is inside that gadget. For this callback, the reason is \fIXmCR_DISARM\fP. .IP "\fIXmNfillOnArm\fP" Forces the PushButtonGadget to fill the background of the button with the color specified by \fIXmNarmColor\fP when the button is armed and when this resource is set to True. If False, only the top and bottom shadow colors are switched. When the PushButtonGadget is in a menu, this resource is ignored and assumed to be False. .IP "\fIXmNmultiClick\fP" If a button click is followed by another button click within the time span specified by the display's multi-click time, and this resource is set to \fIXmMULTICLICK_DISCARD\fP, do not process the second click. If this resource is set to \fIXmMULTICLICK_KEEP\fP, process the event and increment \fBclick_count\fP in the callback structure. When the button is in a menu, the default is \fIXmMULTICLICK_DISCARD\fP; otherwise, for a button not in a menu \fIXmMULTICLICK_KEEP\fP is the default value. .IP "\fIXmNshowAsDefault\fP" If \fIXmNdefaultButtonShadowThickness\fP is greater than zero, a value greater than zero in this resource specifies to mark this button as the default button. If \fIXmNdefaultButtonShadowThickness\fP is zero, a value greater than zero in this resource specifies to mark this button as the default button with the shadow thickness specified by this resource. The space between the shadow and the default shadow is equal to the sum of both shadows. The default value is zero. .IP When the XmDisplay resource \fIedfaultButtonEmphasis\fP is "external_highlight" (the default), the PushButtonGadget draws the location cursor outside of the outer shadow. When this resource is "internal_highlight", the highlight is drawn between the inner and outer shadows. .IP When the \fIXmNshowAsDefault\fP value is not zero, the Label resources \fIXmNmarginLeft\fP, \fIXmNmarginRight\fP, \fIXmNmarginTop\fP, and \fIXmNmarginBottom\fP may be modified to accommodate the second shadow. This resource is disabled when the PushButton is in a menu. .SS "Inherited Resources" PushButtonGadget inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmLabelGadget Resource Set Name Class Type Default Access _ XmNaccelerator XmCAccelerator String NULL CSG XmNacceleratorText XmCAcceleratorText XmString NULL CSG XmNalignment XmCAlignment unsigned char dynamic CSG XmNfontList XmCFontList XmFontList dynamic CSG XmNlabelInsensitivePixmap XmCLabelInsensitivePixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelPixmap XmCLabelPixmap Pixmap dynamic CSG XmNlabelString XmCXmString XmString dynamic CSG XmNlabelType XmCLabelType unsigned char XmSTRING CSG XmNmarginBottom XmCMarginBottom Dimension dynamic CSG XmNmarginHeight XmCMarginHeight Dimension 2 CSG XmNmarginLeft XmCMarginLeft Dimension dynamic CSG XmNmarginRight XmCMarginRight Dimension dynamic CSG XmNmarginTop XmCMarginTop Dimension dynamic CSG XmNmarginWidth XmCMarginWidth Dimension 2 CSG .wH .tH XmNmnemonic XmCMnemonic KeySym NULL CSG XmNmnemonicCharSet XmCMnemonicCharSet String dynamic CSG XmNrecomputeSize XmCRecomputeSize Boolean True CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CSG .TE .KE .in .sp 1 .wH .in .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmGadget Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic G XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic G XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic G XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. RectObj Resource Set Name Class Type Default Access _ XmNancestorSensitive XmCSensitive Boolean dynamic G XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNheight XmCHeight Dimension dynamic CSG XmNsensitive XmCSensitive Boolean True CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Object Resource Set Name Class Type Default Access _ XmNdestroyCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.1i .nf typedef struct { int \fBreason\fI; XEvent \fB* event\fI; int \fBclick_count\fI; } XmPushButtonCallbackStruct; .fi .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBclick_count\fP" This value is valid only when the reason is \fIXmCR_ACTIVATE\fP. It contains the number of clicks in the last multiclick sequence if the \fIXmNmultiClick\fP resource is set to \fIXmMULTICLICK_KEEP\fP, otherwise it contains \fI1\fP. The activate callback is invoked for each click if \fIXmNmultiClick\fP is set to \fIXmMULTICLICK_KEEP\fP. .SS "Behavior" XmPushButtonGadget includes behavior from XmGadget. XmPushButtonGadget includes menu traversal behavior from XmLabelGadget. Additional behavior for XmPushButtonGadget is described below: .IP "\fIBDrag\ Press\fP:" Drags the contents of a PushButtonGadget label, identified by pressing \fIBDrag\fP. This action creates a DragContext object whose \fIXmNexportTargets\fP resource is set to "COMPOUND_TEXT" for a label type of \fIXmSTRING\fP; otherwise, "PIXMAP" if the label type is \fIXmPIXMAP\fP. This action is undefined for PushButtonGadgets used in a menu system. .IP This action is disabled if the XmDisplay's \fIenableUnselectableDrag\fP resource is True. .IP "\fIBSelect\ Press\fP:" This action arms the PushButtonGadget. .IP In a menu, this action unposts any menus posted by the PushButtonGadget's parent menu, disables keyboard traversal for the menu, and enables mouse traversal for the menu. It draws the shadow in the armed state. Unless the button is already armed, it calls the \fIXmNarmCallback\fP callbacks. .IP If the button is not in a menu, this action draws the shadow in the armed state. If \fIXmNfillOnArm\fP is set to True, it fills the button with the color specified by \fIXmNarmColor\fP. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNarmPixmap\fP is used for the button face. It calls the \fIXmNarmCallback\fP callbacks. .IP "\fIBSelect\ Press\ 2+\fP:" If \fIXmNmultiClick\fP is \fIXmMULTICLICK_DISCARD\fP, this action does nothing. .PI If \fIXmNmultiClick\fP is \fIXmMULTICLICK_KEEP\fP, this action does the following: Draws the shadow in the armed state. If the button is not in a menu and if \fIXmNfillOnArm\fP is set to True, fills the button with the color specified by \fIXmNarmColor\fP. .ne 6 If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNarmPixmap\fP is used for the button face. Calls the \fIXmNarmCallback\fP callbacks. .IP "\fIBSelect\ Click\ or\ BSelect\ Release\fP:" In a menu, this action unposts all menus in the menu hierarchy and activates the PushButtonGadget. It calls the \fIXmNactivateCallback\fP callbacks and then the \fIXmNdisarmCallback\fP callbacks. .IP If the PushButtonGadget is not in a menu, this action draws the shadow in the unarmed state. If \fIXmNfillOnArm\fP is set to True, the background color reverts to the unarmed color. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNlabelPixmap\fP is used for the button face. If the pointer is still within the button, this action calls the callbacks for \fIXmNactivateCallback\fP. Calls the callbacks for \fIXmNdisarmCallback\fP. .IP "\fIBSelect\ Release\ 2+\fP:" If \fIXmNmultiClick\fP is \fIXmMULTICLICK_DISCARD\fP, this action does nothing. .IP If \fIXmNmultiClick\fP is \fIXmMULTICLICK_KEEP\fP, this action does the following: Increments \fBclick_count\fP in the callback structure. Draws the shadow in the unarmed state. If the button is not in a menu and if \fIXmNfillOnArm\fP is set to True, the background color reverts to the unarmed color. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNlabelPixmap\fP is used for the button face. If the pointer is within the PushButtonGadget, calls the callbacks for \fIXmNactivateCallback\fP. Calls the callbacks for \fIXmNdisarmCallback\fP. .IP "\fIKActivate\fP:" In a menu, does the following: unposts all menus in the menu hierarchy; unless the button is already armed, calls the \fIXmNarmCallback\fP callbacks; and calls the \fIXmNactivateCallback\fP and \fIXmNdisarmCallback\fP callbacks. Outside a menu, \fIKActivate\fP has no effect. For PushButtonGadgets outside of a menu, if the parent is a manager, this action passes the event to the parent. .IP "\fIKSelect\fP:" In a menu, does the following: Unposts all menus in the menu hierarchy. Unless the button is already armed, calls the \fIXmNarmCallback\fP callbacks. Calls the \fIXmNactivateCallback\fP and \fIXmNdisarmCallback\fP callbacks. .IP Outside a menu, does the following: Draws the shadow in the armed state and, if \fIXmNfillOnArm\fP is set to True, fills the button with the color specified by \fIXmNarmColor\fP. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNarmPixmap\fP is used for the button face. Calls the \fIXmNarmCallback\fP callbacks. .IP Outside a menu, this action also arranges for the following to happen, either immediately or at a later time: The shadow is drawn in the unarmed state and, if \fIXmNfillOnArm\fP is set to True, the background color reverts to the unarmed color. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNlabelPixmap\fP is used for the button face. The \fIXmNactivateCallback\fP and \fIXmNdisarmCallback\fP callbacks are called. .IP "\fIKHelp\fP:" In a Pulldown or Popup MenuPane, unposts all menus in the menu hierarchy and restores keyboard focus to the widget that had the focus before the menu system was entered. Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIMAny\ KCancel\fP:" In a toplevel Pulldown MenuPane from a MenuBar, unposts the menu, disarms the MenuBar CascadeButton and the MenuBar, and restores keyboard focus to the widget that had the focus before the MenuBar was entered. In other Pulldown MenuPanes, unposts the menu. .IP In a Popup MenuPane, unposts the menu and restores keyboard focus to the widget from which the menu was posted. For a PushButtonGadget outside of a menu, if the parent is a manger, this action passes the event to the parent. .IP "\fI\fP:" In a menu, if keyboard traversal is enabled, this action does nothing. Otherwise, it draws the shadow in the armed state and calls the \fIXmNarmCallback\fP callbacks. .IP If the PushButtonGadget is not in a menu and the cursor leaves and then reenters the PushButtonGadget while the button is pressed, this action draws the shadow in the armed state. If \fIXmNfillOnArm\fP is set to True, it also fills the button with the color specified by \fIXmNarmColor\fP. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNarmPixmap\fP is used for the button face. .IP "\fI\fP:" In a menu, if keyboard traversal is enabled, this action does nothing. Otherwise, it draws the shadow in the unarmed state and calls the \fIXmNdisarmCallback\fP callbacks. .IP If the PushButtonGadget is not in a menu and the cursor leaves the PushButtonGadget while the button is pressed, this action draws the shadow in the unarmed state. If \fIXmNfillOnArm\fP is set to True, the background color reverts to the unarmed color. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNlabelPixmap\fP is used for the button face. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fIObject(3X)\fP, \fIRectObj(3X)\fP, \fIXmCreatePushButtonGadget(3X)\fP, \fIXmDisplay(3X)\fP, \fIXmGadget(3X)\fP, \fIXmLabelGadget(3X)\fP, and \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmRegisterSegmentEncoding 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRegisterSegmentEncoding\fP \- A compound string function that registers a compound text encoding format for a specified font list element tag .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu char * XmRegisterSegmentEncoding (\fBfontlist_tag, ct_encoding\fI) .ta .5i 1.25i .nf char *\fBfontlist_tag\fI; char *\fBct_encoding\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmRegisterSegmentEncoding\fP registers a compound text encoding format with the specified font list element tag. The \fIXmCvtXmStringToCT\fP function uses this registry to map the font list tags of compound string segments to compound text encoding formats. Registering a font list tag that already exists in the registry overwrites the original entry. You can unregister a font list tag by passing a NULL value for the \fBct_encoding\fP parameter. .IP "\fBfontlist_tag\fP" Specifies the font list element tag to be registered. The tag must be a NULL-terminated ISO8859-1 string. .IP "\fBct_encoding\fP" Specifies the compound text character set to be used for segments with the font list tag. The value must be a NULL-terminated ISO8859-1 string. A value of \fIXmFONTLIST_DEFAULT_TAG\fP maps the specified font list tag to the code set of the locale. .SH RETURN VALUE Returns NULL for a new font list tag or the old \fBct_encoding\fP value for an already registered font list tag. The application is responsible for freeing the storage associated with the returned data (if any) by calling \fIXtFree\fP. .SH RELATED INFORMATION .na \fIXmCvtXmStringToCT(3X)\fP, \fIXmFontList(3X)\fP, \fIXmMapSegmentEncoding(3X)\fP, and \fIXmString(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmRemoveProtocolCallback 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRemoveProtocolCallback\fP \- A VendorShell function that removes a callback from the internal list .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu void XmRemoveProtocolCallback (\fBshell, property, protocol, callback, closure\fI) .ta .5i 1.75i .nf Widget \fBshell\fI; Atom \fBproperty\fI; Atom \fBprotocol\fI; XtCallbackProc \fBcallback\fI; XtPointer \fBclosure\fI; .sp \n(PDu void XmRemoveWMProtocolCallback (\fBshell, protocol, callback, closure\fI) Widget \fBshell\fI; Atom \fBprotocol\fI; XtCallbackProc \fBcallback\fI; XtPointer \fBclosure\fI; .wH .fi .ne 8 .iE .sE .SH DESCRIPTION .fi \fIXmRemoveProtocolCallback\fP removes a callback from the internal list. .PP \fIXmRemoveWMProtocolCallback\fP is a convenience interface. It calls \fIXmRemoveProtocolCallback\fP with the property value set to the atom returned by interning \fIWM_PROTOCOLS\fP. .IP "\fBshell\fP" Specifies the widget with which the protocol property is associated .IP "\fBproperty\fP" Specifies the protocol property .IP "\fBprotocol\fP" Specifies the protocol atom (or an int cast to Atom) .IP "\fBcallback\fP" Specifies the procedure to call when a protocol message is received .IP "\fBclosure\fP" Specifies the client data to be passed to the callback when it is invoked .PP For a complete definition of VendorShell and its associated resources, see \fIVendorShell(3X)\fP. .SH RELATED INFORMATION .na \fIVendorShell(3X)\fP, \fIXmInternAtom(3X)\fP, and \fIXmRemoveWMProtocolCallback(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmRemoveProtocols 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRemoveProtocols\fP \- A VendorShell function that removes the protocols from the protocol manager and deallocates the internal tables .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu void XmRemoveProtocols (\fBshell, property, protocols, num_protocols\fI) .ta .5i 1.5i .nf Widget \fBshell\fI; Atom \fBproperty\fI; Atom \fB* protocols\fI; Cardinal \fBnum_protocols\fI; .sp \n(PDu void XmRemoveWMProtocols (\fBshell, protocols, num_protocols\fI) Widget \fBshell\fI; Atom \fB * protocols\fI; Cardinal \fBnum_protocols\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmRemoveProtocols\fP removes the protocols from the protocol manager and deallocates the internal tables. If any of the protocols are active, it will update the handlers and update the property if \fBshell\fP is realized. .PP \fIXmRemoveWMProtocols\fP is a convenience interface. It calls \fIXmRemoveProtocols\fP with the property value set to the atom returned by interning \fIWM_PROTOCOLS\fP. .IP "\fBshell\fP" Specifies the widget with which the protocol property is associated .IP "\fBproperty\fP" Specifies the protocol property .IP "\fBprotocols\fP" Specifies the protocol atoms (or ints cast to Atom) .IP "\fBnum_protocols\fP" Specifies the number of elements in protocols .PP For a complete definition of VendorShell and its associated resources, see \fIVendorShell(3X)\fP. .SH RELATED INFORMATION .na \fIVendorShell(3X)\fP, \fIXmInternAtom(3X)\fP, and \fIXmRemoveWMProtocols(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmRemoveTabGroup 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRemoveTabGroup\fP \- A function that removes a tab group .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmRemoveTabGroup (\fBtab_group\fI) .ta .5i 1.5i .nf Widget \fBtab_group\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi This function is obsolete and its behavior is replaced by setting \fIXmNnavigationType\fP to \fIXmNONE\fP. \fIXmRemoveTabGroup\fP removes a widget from the list of tab groups associated with a particular widget hierarchy and sets the widget's \fIXmNnavigationType\fP to \fIXmNONE\fP. .IP "\fBtab_group\fP" Specifies the widget ID .SH RELATED INFORMATION .na \fIXmAddTabGroup(3X)\fP, \fIXmManager(3X)\fP, and \fIXmPrimitive(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmRemoveWMProtocolCallback 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRemoveWMProtocolCallback\fP \- A VendorShell convenience interface that removes a callback from the internal list .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu void XmRemoveWMProtocolCallback (\fBshell, protocol, callback, closure\fI) .ta .5i 1.75i .nf Widget \fBshell\fI; Atom \fBprotocol\fI; XtCallbackProc \fBcallback\fI; XtPointer \fBclosure\fI; .wH .fi .ne 9 .iE .sE .SH DESCRIPTION .fi \fIXmRemoveWMProtocolCallback\fP is a convenience interface. It calls \fIXmRemoveProtocolCallback\fP with the property value set to the atom returned by interning \fIWM_PROTOCOLS\fP. .IP "\fBshell\fP" Specifies the widget with which the protocol property is associated .IP "\fBprotocol\fP" Specifies the protocol atom (or an int type cast to Atom) .IP "\fBcallback\fP" Specifies the procedure to call when a protocol message is received .IP "\fBclosure\fP" Specifies the client data to be passed to the callback when it is invoked .PP For a complete definition of VendorShell and its associated resources, see \fIVendorShell(3X)\fP. .SH RELATED INFORMATION .na \fIVendorShell(3X)\fP, \fIXmInternAtom(3X)\fP, and \fIXmRemoveProtocolCallback(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmRemoveWMProtocols 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRemoveWMProtocols\fP \- A VendorShell convenience interface that removes the protocols from the protocol manager and deallocates the internal tables .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu void XmRemoveWMProtocols (\fBshell, protocols, num_protocols\fI) .ta .5i 1.5i .nf Widget \fBshell\fI; Atom \fB* protocols\fI; Cardinal \fBnum_protocols\fI; .wH .fi .ne 9 .iE .sE .SH DESCRIPTION .fi \fIXmRemoveWMProtocols\fP is a convenience interface. It calls \fIXmRemoveProtocols\fP with the property value set to the atom returned by interning \fIWM_PROTOCOLS\fP. .IP "\fBshell\fP" Specifies the widget with which the protocol property is associated .IP "\fBprotocols\fP" Specifies the protocol atoms (or ints cast to Atom) .IP "\fBnum_protocols\fP" Specifies the number of elements in protocols .PP For a complete definition of VendorShell and its associated resources, see \fIVendorShell(3X)\fP. .SH RELATED INFORMATION .na \fIVendorShell(3X)\fP, \fIXmInternAtom(3X)\fP, and \fIXmRemoveProtocols(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmRepTypeAddReverse 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRepTypeAddReverse\fP \- A representation type manager function that installs the reverse converter for a previously registered representation type .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmRepTypeAddReverse (\fBrep_type_id\fI) .ta .5i 1.5i .nf XmRepTypeId \fBrep_type_id\fI; .iE .sE .SH DESCRIPTION .fi \fIXmRepTypeAddReverse\fP installs the reverse converter for a previously registered representation type. The reverse converter takes a numerical representation type value and returns its corresponding string value. Certain applications may require this capability to obtain a string value to display on a screen or to build a resource file. .PP The \fBvalues\fP argument of the \fIXmRepTypeRegister\fP function can be used to register representation types with nonconsecutive values or with duplicate names for the same value. If the list of numerical values for a representation type contains duplicate values, the reverse converter uses the first name in the \fBvalue_names\fP list that matches the specified numeric value. For example, if a \fBvalue_names\fP array has \fIcancel\fP, \fIproceed\fP, and \fIabort\fP, and the corresponding \fBvalues\fP array contains 0, 1, and 0, the reverse converter will return \fIcancel\fP instead of \fIabort\fP for an input value of 0. .IP "\fBrep_type_id\fP" Specifies the identification number of the representation type .SH RELATED INFORMATION .na \fIXmRepTypeGetId(3X)\fP and \fIXmRepTypeRegister(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmRepTypeGetId 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRepTypeGetId\fP \- A representation type manager function that retrieves the identification number of a representation type .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmRepTypeId XmRepTypeGetId (\fBrep_type\fI) .ta .5i 1.5i .nf String \fBrep_type\fI; .iE .sE .SH DESCRIPTION .fi \fIXmRepTypeGetId\fP searches the registration list for the specified representation type and returns the associated identification number. .IP "\fBrep_type\fP" Specifies the representation type for which an identification number is requested .SH RETURN VALUE Returns the identification number of the specified representation type. If the representation type is not registered, the function returns \fIXmREP_TYPE_INVALID\fP. .SH RELATED INFORMATION .na \fIXmRepTypeGetRegistered(3X)\fP and \fIXmRepTypeRegister(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmRepTypeGetNameList 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRepTypeGetNameList\fP \- A representation type manager function that generates a list of values for a representation type .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu String * XmRepTypeGetNameList (\fBrep_type_id, use_uppercase_format\fI) .ta .5i 1.75i .nf XmRepTypeId \fBrep_type_id\fI; Boolean \fBuse_uppercase_format\fI; .iE .sE .SH DESCRIPTION .fi \fIXmRepTypeGetNameList\fP generates a null-terminated list of the value names associated with the specified representation type. Each value name is a null-terminated string. This routine allocates memory for the returned data. The application must free this memory using \fIXtFree\fP. .IP "\fBrep_type_id\fP" Specifies the identification number of the representation type. .IP "\fBuse_uppercase_format\fP" Specifies a Boolean value that controls the format of the name list. If True, each value name is in uppercase characters prefixed by "Xm"; if False, the names are in lowercase characters. .SH RETURN VALUE Returns a pointer to an array of the value names. .SH RELATED INFORMATION .na \fIXmRepTypeGetId(3X)\fP, \fIXmRepTypeGetRegistered(3X)\fP, and \fIXmRepTypeRegister(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmRepTypeGetRecord 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRepTypeGetRecord\fP \- A representation type manager function that returns information about a representation type .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmRepTypeEntry XmRepTypeGetRecord (\fBrep_type_id\fI) .ta .5i 1.5i .nf XmRepTypeId \fBrep_type_id\fI; .iE .sE .SH DESCRIPTION .fi \fIXmRepTypeGetRecord\fP retrieves information about a particular representation type that is registered with the representation type manager. This routine allocates memory for the returned data. The application must free this memory using \fIXtFree\fP. .IP "\fBrep_type_id\fP" The identification number of the representation type .PP The representation type entry structure contains the following information: .nL .ne 10 .sS .iS .ta .25i 1.5i .nf typedef struct { String \fBrep_type_name\fI; String *\fBvalue_names\fI; unsigned char *\fBvalues\fI; unsigned char \fBnum_values\fI; Boolean \fBreverse_installed\fI; XmRepTypeId \fBrep_type_id\fI; } XmRepTypeEntryRec, *XmRepTypeEntry ; .iE .sE .IP "\fBrep_type_name\fP" The name of the representation type .IP "\fBvalue_names\fP" An array of representation type value names .IP "\fBvalues\fP" An array of representation type numerical values .IP "\fBnum_values\fP" The number of values associated with the representation type .IP "\fBreverse_installed\fP" A flag that indicates whether or not the reverse converter is installed .IP "\fBrep_type_id\fP" The identification number of the representation type .SH RETURN VALUE Returns a pointer to the representation type entry structure that describes the representation type. .SH RELATED INFORMATION .na \fIXmRepTypeGetId(3X)\fP, \fIXmRepTypeGetRegistered(3X)\fP, and \fIXmRepTypeRegister(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmRepTypeGetRegistered 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRepTypeGetRegistered\fP \- A representation type manager function that returns a copy of the registration list .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmRepTypeList XmRepTypeGetRegistered () .iE .sE .SH DESCRIPTION .fi \fIXmRepTypeGetRegistered\fP retrieves information about all representation types that are registered with the representation type manager. The registration list is an array of structures, each of which contains information for a representation type entry. The end of the registration list is marked with a representation type entry whose \fBrep_type_name\fP field has a NULL pointer. This routine allocates memory for the returned data. The application must free this memory using \fIXtFree\fP. .PP The representation type entry structure contains the following information: .ne 10 .sS .iS .ta .25i 1.5i .nf typedef struct { String \fBrep_type_name\fI; String *\fBvalue_names\fI; unsigned char *\fBvalues\fI; unsigned char \fBnum_values\fI; Boolean \fBreverse_installed\fI; XmRepTypeId \fBrep_type_id\fI; } XmRepTypeEntryRec, *XmRepTypeList ; .iE .sE .IP "\fBrep_type_name\fP" The name of the representation type .IP "\fBvalue_names\fP" An array of representation type value names .IP "\fBvalues\fP" An array of representation type numerical values .IP "\fBnum_values\fP" The number of values associated with the representation type .IP "\fBreverse_installed\fP" A flag that indicates whether or not the reverse converter is installed .IP "\fBrep_type_id\fP" The identification number of the representation type .SH RETURN VALUE Returns a pointer to the registration list of representation types. .SH RELATED INFORMATION .na \fIXmRepTypeRegister(3X)\fP and \fIXmRepTypeGetRecord(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** .TH XmRepTypeInstallTearOffModelConverter 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRepTypeInstallTearOffModelConverter\fP \- A representation type manager function that installs the resource converter for \fIXmNtearOffModel\fP. .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmRepTypeInstallTearOffModelConverter () .iE .sE .SH DESCRIPTION .fi \fIXmRepTypeInstallTearOffModelConverter\fP installs the resource converter that allows values for the \fIXmNtearOffModel\fP resource to be specified in resource default files. .SH RELATED INFORMATION .na \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmRepTypeRegister 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRepTypeRegister\fP \- A representation type manager function that registers a representation type resource .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmRepTypeId XmRepTypeRegister (\fBrep_type, value_names, values, num_values\fI) .ta .5i 1.75i .nf String \fBrep_type\fI; String *\fBvalue_names\fI; unsigned char *\fBvalues\fI; unsigned char \fBnum_values\fI; .iE .sE .SH DESCRIPTION .fi \fIXmRepTypeRegister\fP registers a representation type resource with the representation type manager. All features of the representation type management facility become available for the specified representation type. The function installs a forward type converter to convert string values to numerical representation type values. .PP When the \fBvalues\fP argument is NULL, consecutive numerical values are assumed. The order of the strings in the \fBvalue_names\fP array determines the numerical values for the resource. For example, the first value name is 0; the second value name is 1; and so on. .PP If it is non-NULL, the \fBvalues\fP argument can be used to assign values to representation types that have nonconsecutive values or have duplicate names for the same value. Representation types registered in this manner will consume additional storage and will be slightly slower than representation types with consecutive values. .PP A representation type can only be registered once; if the same representation type name is registered more than once, the behavior is undefined. .PP The function \fIXmRepTypeAddReverse\fP installs a reverse converter for a registered representation type. The reverse converter takes a representation type numerical value and returns the corresponding string value. If the list of numerical values for a representation type contains duplicate values, the reverse converter uses the first name in the \fBvalue_names\fP list that matches the specified numeric value. For example, if a \fBvalue_names\fP array has \fIcancel\fP, \fIproceed\fP, and \fIabort\fP, and the corresponding \fBvalues\fP array contains 0, 1, and 0, the reverse converter will return \fIcancel\fP instead of \fIabort\fP for an input value of 0. .IP "\fBrep_type\fP" Specifies the representation type name. .IP "\fBvalue_names\fP" Specifies a pointer to an array of value names associated with the representation type. A value name is specified in lowercase characters without an "Xm" prefix. Words within a name are separated with underscores. .IP "\fBvalues\fP" Specifies a pointer to an array of values associated with the representation type. A value in this array is associated with the value name in the corresponding position of the \fBvalue_names\fP array. .IP "\fBnum_values\fP" Specifies the number of entries in the \fBvalue_names\fP and \fBvalues\fP arrays. .SH RETURN VALUE Returns the identification number for the specified representation type. .SH RELATED INFORMATION .na \fIXmRepTypeAddReverse(3X)\fP, \fIXmRepTypeGetId(3X)\fP, \fIXmRepTypeGetNameList(3X)\fP, \fIXmRepTypeGetRecord(3X)\fP, \fIXmRepTypeGetRegistered(3X)\fP, and \fIXmRepTypeValidValue(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmRepTypeValidValue 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRepTypeValidValue\fP \- A representation type manager function that tests the validity of a numerical value of a representation type resource .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmRepTypeValidValue (\fBrep_type_id, test_value, enable_default_warning\fI) .ta .5i 1.75i .nf XmRepTypeId \fBrep_type_id\fI; unsigned char \fBtest_value\fI; Widget \fBenable_default_warning\fI; .iE .sE .SH DESCRIPTION .fi \fIXmRepTypeValidValue\fP tests the validity of a numerical value for a given representation type resource. The function generates a default warning message if the value is invalid and the \fBenable_default_warning\fP argument is non-NULL. .IP "\fBrep_type_id\fP" Specifies the identification number of the representation type. .IP "\fBtest_value\fP" Specifies the numerical value to test. .IP "\fBenable_default_warning\fP" Specifies the ID of the widget that contains a default warning message. If this parameter is NULL, no default warning message is generated and the application must provide its own error handling. .SH RETURN VALUE Returns True if the specified value is valid; otherwise, returns False. .SH RELATED INFORMATION .na \fIXmRepTypeGetId(3X)\fP and \fIXmRepTypeRegister(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmResolveAllPartOffsets 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmResolveAllPartOffsets\fP \- A function that allows writing of upward-compatible applications and widgets .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmResolveAllPartOffsets (\fBwidget_class, offset, constraint_offset\fI) .ta .5i 1.5i .nf WidgetClass \fBwidget_class\fI; XmOffsetPtr \fB* offset\fI; XmOffsetPtr \fB* constraint_offset\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi The use of offset records requires two extra global variables per widget class. The variables consist of pointers to arrays of offsets into the widget record and constraint record for each part of the widget structure. The \fIXmResolveAllPartOffsets\fP function allocates the offset records needed by an application to guarantee upward-compatible access to widget instance and constraint records by applications and widgets. These offset records are used by the widget to access all of the widget's variables. A widget needs to take the following steps: .TP \(bu Instead of creating a resource list, the widget creates an offset resource list. To help you accomplish this, use the \fIXmPartResource\fP structure and the \fIXmPartOffset\fP macro. The \fIXmPartResource\fP data structure looks just like a resource list, but instead of having one integer for its offset, it has two shorts. This is put into the class record as if it were a normal resource list. Instead of using \fIXtOffset\fP for the offset, the widget uses \fIXmPartOffset\fP. .PP If the widget is a subclass of the Constraint class and it defines additional constraint resources, create an offset resource list for the constraint part as well. Instead of using \fIXtOffset\fP for the offset, the widget uses \fIXmConstraintPartOffset\fP in the constraint resource list. .oS .ta 0.25i 0.5i .nf XmPartResource resources[] = { { BarNxyz, BarCXyz, XmRBoolean, sizeof(Boolean), XmPartOffset(Bar,xyz), XmRImmediate, (XtPointer)False } }; .sp .5 XmPartResource constraints[] = { { BarNmaxWidth, BarNMaxWidth, XmRDimension, sizeof(Dimension), XmConstraintPartOffset(Bar,max_width), XmRImmediate, (XtPointer)100 } }; .oE .TP \(bu Instead of putting the widget size in the class record, the widget puts the widget part size in the same field. If the widget is a subclass of the Constraint class, instead of putting the widget constraint record size in the class record, the widget puts the widget constraint part size in the same field. .TP \(bu Instead of putting \fIXtVersion\fP in the class record, the widget puts \fIXtVersionDontCheck\fP in the class record. .TP \(bu Define a variable, of type \fIXmOffsetPtr\fP, to point to the offset record. If the widget is a subclass of the Constraint class, define a variable of type XmOffsetPtr to point to the constraint offset record. These can be part of the widget's class record or separate global variables. .TP \(bu In class initialization, the widget calls \fIXmResolveAllPartOffsets\fP, passing it pointers to the class record, the address of the offset record, and the address of the constraint offset record. If the widget not is a subclass of the Constraint class, it should pass NULL as the address of the constraint offset record. This does several things: .PP Adds the superclass (which, by definition, has already been initialized) size field to the part size field .PP If the widget is a subclass of the Constraint class, adds the superclass constraint size field to the constraint size field .PP Allocates an array based upon the number of superclasses .PP If the widget is a subclass of the constraint class, allocates an array for the constraint offset record .PP Fills in the offsets of all the widget parts and constraint parts with the appropriate values, determined by examining the size fields of all superclass records .PP Uses the part offset array to modify the offset entries in the resource list to be real offsets, in place .TP \(bu The widget defines a constant which will be the index to its part structure in the offsets array. The value should be 1 greater than the index of the widget's superclass. Constants defined for all Xm widgets can be found in \fIXmP.h\fP. .oS \&#define BarIndex (XmBulletinBIndex + 1) .oE .nL .ne 10 .TP \(bu Instead of accessing fields directly, the widget must always go through the offset table. The \fIXmField\fP and \fIXmConstraintField\fP macros help you access these fields. Because the \fIXmPartOffset\fP, \fIXmConstraintPartOffset\fP, \fIXmField\fP, and \fIXmConstraintField\fP macros concatenate things together, you must ensure that there is no space after the part argument. For example, the following macros do not work because of the space after the part (Label) argument: .oS XmField(w, offset, Label , text, char *) XmPartOffset(Label , text). .oE Therefore, you must not have any spaces after the part (Label) argument, as illustrated here: .oS XmField(w, offset, Label, text, char *) .oE .ne 10 You can define macros for each field to make this easier. Assume an integer field \fBxyz\fP: .oS .ta 0.25i .nf \&#define BarXyz(w) (*(int *)(((char *) w) + \e offset[BarIndex] + XtOffset(BarPart,xyz))) .oE .PP For constraint field \fBmax_width\fP: .oS .ta 0.25i .nf \&#define BarMaxWidth(w) \e XmConstraintField(w,constraint_offsets,Bar,max_width,Dimension) .oE .PP The parameters for \fIXmResolveAllPartOffsets\fP are defined below: .IP "\fBwidget_class\fP" Specifies the widget class pointer for the created widget .IP "\fBoffset\fP" Returns the offset record .IP "\fBconstraint_offset\fP" Returns the constraint offset record .SH "RELATED INFORMATION" .na \fIXmResolvePartOffsets(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmResolvePartOffsets 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmResolvePartOffsets\fP \- A function that allows writing of upward-compatible applications and widgets .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmResolvePartOffsets (\fBwidget_class, offset\fI) .ta .5i 1.5i .nf WidgetClass \fBwidget_class\fI; XmOffsetPtr \fB* offset\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi The use of offset records requires one extra global variable per widget class. The variable consists of a pointer to an array of offsets into the widget record for each part of the widget structure. The \fIXmResolvePartOffsets\fP function allocates the offset records needed by an application to guarantee upward-compatible access to widget instance records by applications and widgets. These offset records are used by the widget to access all of the widget's variables. A widget needs to take the following steps: .TP \(bu Instead of creating a resource list, the widget creates an offset resource list. To help you accomplish this, use the \fIXmPartResource\fP structure and the \fIXmPartOffset\fP macro. The \fIXmPartResource\fP data structure looks just like a resource list, but instead of having one integer for its offset, it has two shorts. This is put into the class record as if it were a normal resource list. Instead of using \fIXtOffset\fP for the offset, the widget uses \fIXmPartOffset\fP. .oS XmPartResource resources[] = { { BarNxyz, BarCXyz, XmRBoolean, sizeof(Boolean), XmPartOffset(Bar,xyz), XmRImmediate, (XtPointer)False } }; .oE .TP \(bu Instead of putting the widget size in the class record, the widget puts the widget part size in the same field. .TP \(bu Instead of putting \fIXtVersion\fP in the class record, the widget puts \fIXtVersionDontCheck\fP in the class record. .TP \(bu The widget defines a variable, of type \fIXmOffsetPtr\fP, to point to the offset record. This can be part of the widget's class record or a separate global variable. .TP \(bu In class initialization, the widget calls \fIXmResolvePartOffsets\fP, passing it a pointer to contain the address of the offset record and the class record. This does several things: .PP Adds the superclass (which, by definition, has already been initialized) size field to the part size field .PP Allocates an array based upon the number of superclasses .PP Fills in the offsets of all the widget parts with the appropriate values, determined by examining the size fields of all superclass records .PP Uses the part offset array to modify the offset entries in the resource list to be real offsets, in place .TP \(bu The widget defines a constant which will be the index to its part structure in the offsets array. The value should be 1 greater than the index of the widget's superclass. Constants defined for all Xm widgets can be found in \fIXmP.h\fP. .oS \&#define BarIndex (XmBulletinBIndex + 1) .oE .TP \(bu Instead of accessing fields directly, the widget must always go through the offset table. The \fIXmField\fP macro helps you access these fields. Because the \fIXmPartOffset\fP and \fIXmField\fP macros concatenate things together, you must .ne 4 ensure that there is no space after the part argument. For example, the following macros do not work because of the space after the part (Label) argument: .oS XmField(w, offset, Label , text, char *) XmPartOffset(Label , text) .oE Therefore, you must not have any spaces after the part (Label) argument, as illustrated here: .oS XmField(w, offset, Label, text, char *) .oE You can define macros for each field to make this easier. Assume an integer field \fBxyz\fP: .oS .ta 0.25i .nf \&#define BarXyz(w) (*(int *)(((char *) w) + \e offset[BarIndex] + XtOffset(BarPart,xyz))) .oE .PP The parameters for \fIXmResolvePartOffsets\fP are defined below: .IP "\fBwidget_class\fP" Specifies the widget class pointer for the created widget. .IP "\fBoffset\fP" Returns the offset record. .SH "RELATED INFORMATION" .na \fIXmResolveAllPartOffsets(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmRowColumn 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmRowColumn\fP \- The RowColumn widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi The RowColumn widget is a general purpose RowColumn manager capable of containing any widget type as a child. In general, it requires no special knowledge about how its children function and provides nothing beyond support for several different layout styles. However, it can be configured as a menu, in which case, it expects only certain children, and it configures to a particular layout. The menus supported are: MenuBar, Pulldown or Popup MenuPanes, and OptionMenu. .nL .ne 9 .PP The type of layout performed is controlled by how the application has set the various layout resources. It can be configured to lay out its children in either rows or columns. In addition, the application can specify how the children are laid out, as follows: .TP \(bu the children are packed tightly together into either rows or columns .TP \(bu each child is placed in an identically sized box (producing a symmetrical look) .TP \(bu a specific layout (the current \fBx\fP and \fBy\fP positions of the children control their location) .PP In addition, the application has control over both the spacing that occurs between each row and column and the margin spacing present between the edges of the RowColumn widget and any children that are placed against it. .PP In a MenuBar, Pulldown MenuPane, or Popup MenuPane the default for the \fIXmNshadowThickness\fP resource is 2. In an OptionMenu or a WorkArea (such as a RadioBox or CheckBox) this resource is not applicable and its use is undefined. If an application wishes to place a 3-D shadow around an OptionMenu or WorkArea, it can create the RowColumn as a child of a Frame widget. .PP In a MenuBar, Pulldown MenuPane, or Popup MenuPane the \fIXmNnavigationType\fP resource is not applicable and its use is undefined. In a WorkArea the default for \fIXmNnavigationType\fP is \fIXmTAB_GROUP\fP. In an OptionMenu the default for \fIXmNnavigationType\fP is \fIXmNONE\fP. .PP In a MenuBar, Pulldown MenuPane, or Popup MenuPane the \fIXmNtraversalOn\fP resource is not applicable and its use is undefined. In an OptionMenu or WorkArea the default for \fIXmNtraversalOn\fP is True. .PP If the parent of the RowColumn is a MenuShell, the \fIXmNmappedWhenManaged\fP resource is forced to False when the widget is realized. .PP The user can specify resources in a resource file for the automatically created widgets and gadgets of an OptionMenu. The following list identifies the names of these widgets (or gadgets) and the associated OptionMenu areas. .TP \(bu Option Menu Label Gadget \- "OptionLabel" .TP \(bu Option Menu Cascade Button \- "OptionButton" .SS "Tear-off Menus" Pulldown and Popup MenuPanes support tear-off menus, which enable the user to retain a MenuPane on the display to facilitate subsequent menu selections. A MenuPane that can be torn-off is identified by a tear-off button that spans the width of the MenuPane and displays a dashed line. A torn-off MenuPane contains a window manager system menu icon and a title bar. The window title displays the label of the cascade button that initiated the action when the label type is \fIXmSTRING\fP. If the label contains a pixmap the window title is empty. A tear-off menu from a Popup MenuPane also displays an empty title. .PP The user can tear-off a MenuPane using the mouse or keyboard. Clicking \fIBSelect\fP or pressing \fIKActivate\fP (or \fIKSelect\fP) on the tear-off button, tears off the MenuPane at the current position. Pressing \fIBDrag\fP on the tear-off button tears off the MenuPane, and allows the user to drag the torn-off menu to a new position designated by releasing the mouse button. Tearing off a MenuPane unposts the current active menu. Only one tear-off copy for each MenuPane is allowed. Subsequent tear-off actions of a torn MenuPane unpost the existing copy first. .PP The name of the tear-off button of a torn-off menu pane is "TearOffControl". The name can be used to set resources in a resource file. An application can also obtain the tear-off button itself using \fIXmGetTearOffControl\fP and then set resource values by calling \fIXtSetValues\fP. .PP The tear-off button has Separator-like behavior. Its appearance can be specified using the following tear-off button resources: \fIXmNbackground\fP, \fIXmNbackgroundPixmap\fP,\fIXmNbottomShadowColor\fP, \fIXmNforeground\fP, \fIXmNheight\fP, \fIXmNmargin\fP, \fIXmNseparatorType\fP, \fIXmNshadowThickness\fP, and \fIXmNtopShadowColor\fP. Refer to the \fIXmSeparator\fP man page for a complete description of each of these resources. .PP RowColumn resources that affect tear-off menu behavior are \fIXmNtearOffModel\fP, \fIXmNtearOffMenuActivateCallback\fP, and \fIXmNtearOffMenuDeactivateCallback\fP. .PP By default, menus do not tear off; tear off functionality may be enabled by setting the \fIXmNtearOffModel\fP resource to \fIXmTEAR_OFF_ENABLED\fP. There is no resource converter pre-registered for \fIXmNtearOffModel\fP. To allow tear-off functionality to be enabled through the resource database call the function \fIXmRepTypeInstallTearOffModelConverter\fP. .PP Tear-off menu focus policy follows standard window manager policy. It is recommended that the following \fImwm\fP resources are set to True: \fIstartupKeyFocus\fP and \fIautoKeyFocus\fP. .nL .ne 10 .SS "Classes" RowColumn inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIConstraint\fP, and \fIXmManager\fP classes. .PP The class pointer is \fIxmRowColumnWidgetClass\fP. .PP The class name is \fIXmRowColumn\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmRowColumn Resource Set Name Class Type Default Access _ XmNadjustLast XmCAdjustLast Boolean True CSG XmNadjustMargin XmCAdjustMargin Boolean True CSG XmNentryAlignment XmCAlignment unsigned char XmALIGNMENT_BEGINNING CSG XmNentryBorder XmCEntryBorder Dimension 0 CSG XmNentryCallback XmCCallback XtCallbackList NULL C XmNentryClass XmCEntryClass WidgetClass dynamic CSG XmNentryVerticalAlignment XmCVerticalAlignment unsigned char XmALIGNMENT_CENTER CSG XmNisAligned XmCIsAligned Boolean True CSG XmNisHomogeneous XmCIsHomogeneous Boolean dynamic CG XmNlabelString XmCXmString XmString NULL C XmNmapCallback XmCCallback XtCallbackList NULL C XmNmarginHeight XmCMarginHeight Dimension dynamic CSG XmNmarginWidth XmCMarginWidth Dimension dynamic CSG XmNmenuAccelerator XmCAccelerators String dynamic CSG .wH .tH XmNmenuHelpWidget XmCMenuWidget Widget NULL CSG XmNmenuHistory XmCMenuWidget Widget NULL CSG XmNmenuPost XmCMenuPost String NULL CSG XmNmnemonic XmCMnemonic KeySym NULL CSG XmNmnemonicCharSet XmCMnemonicCharSet String XmFONTLIST_DEFAULT_TAG CSG XmNnumColumns XmCNumColumns short 1 CSG XmNorientation XmCOrientation unsigned char dynamic CSG XmNpacking XmCPacking unsigned char dynamic CSG XmNpopupEnabled XmCPopupEnabled Boolean True CSG ...\"XmNpostFromCount XmCPostFromCount int 0 CSG ...\"XmNpostFromList XmCPostFromList WidgetList NULL CSG XmNradioAlwaysOne XmCRadioAlwaysOne Boolean True CSG XmNradioBehavior XmCRadioBehavior Boolean False CSG XmNresizeHeight XmCResizeHeight Boolean True CSG XmNresizeWidth XmCResizeWidth Boolean True CSG XmNrowColumnType XmCRowColumnType unsigned char XmWORK_AREA CG .wH .tH XmNspacing XmCSpacing Dimension dynamic CSG XmNsubMenuId XmCMenuWidget Widget NULL CSG XmNtearOffMenuActivateCallback XmCCallback XtCallbackList NULL C XmNtearOffMenuDeactivateCallback XmCCallback XtCallbackList NULL C XmNtearOffModel XmCTearOffModel unsigned char XmTEAR_OFF_DISABLED CSG XmNunmapCallback XmCCallback XtCallbackList NULL C XmNwhichButton XmCWhichButton unsigned int dynamic CSG .TE .KE .in .sp 1 .IP "\fIXmNadjustLast\fP" Extends the last row of children to the bottom edge of RowColumn (when \fIXmNorientation\fP is \fIXmHORIZONTAL\fP) or extends the last column to the right edge of RowColumn (when \fIXmNorientation\fP is \fIXmVERTICAL\fP). This feature is disabled by setting \fIXmNadjustLast\fP to False. .IP "\fIXmNadjustMargin\fP" Specifies whether the inner minor margins of all items contained within the RowColumn widget are forced to the same value. The inner minor margin corresponds to the \fIXmNmarginLeft\fP, \fIXmNmarginRight\fP, \fIXmNmarginTop\fP, and \fIXmNmarginBottom\fP resources supported by \fIXmLabel\fP and \fIXmLabelGadget\fP. .IP A horizontal orientation causes \fIXmNmarginTop\fP and \fIXmNmarginBottom\fP for all items in a particular row to be forced to the same value; the value is the largest margin specified for one of the Label items. .IP A vertical orientation causes \fIXmNmarginLeft\fP and \fIXmNmarginRight\fP for all items in a particular column to be forced to the same value; the value is the largest margin specified for one of the Label items. .nL .ne 6 .IP This keeps all text within each row or column lined up with all other text in its row or column. If the \fIXmNrowColumnType\fP is either \fIXmMENU_POPUP\fP or \fIXmMENU_PULLDOWN\fP and this resource is True, only button children have their margins adjusted. .nL .ne 9 .IP "\fIXmNentryAlignment\fP" Specifies the alignment type for children that are subclasses of \fIXmLabel\fP or \fIXmLabelGadget\fP when \fIXmNisAligned\fP is enabled. The following are textual alignment types: .IP \fIXmALIGNMENT_BEGINNING\fP \- the default .IP \fIXmALIGNMENT_CENTER\fP .IP \fIXmALIGNMENT_END\fP .IP See the description of \fIXmNalignment\fP in the \fIXmLabel(3X)\fP man page for an explanation of these actions. .IP "\fIXmNentryBorder\fP" Imposes a uniform border width upon all RowColumn's children. The default value is 0, which disables the feature. .IP "\fIXmNentryCallback\fP" Disables the \fIXmNactivateCallback\fP and \fIXmNvalueChangedCallback\fP callbacks for all CascadeButton, DrawnButton, PushButton, and ToggleButton widgets and gadgets contained within the RowColumn widget. If the application supplies this resource, the \fIXmNactivateCallback\fP and \fIXmNvalueChangedCallback\fP callbacks are then revectored to the \fIXmNentryCallback\fP callbacks. This allows an application to supply a single callback routine for handling all items contained in a RowColumn widget. The callback reason is \fIXmCR_ACTIVATE\fP. If the application does not supply this resource, the \fIXmNactivateCallback\fP and \fIXmNvalueChangedCallback\fP callbacks for each item in the RowColumn widget work as normal. .IP The application must supply this resource when this widget is created. Changing this resource using the \fIXtSetValues\fP is not supported. .nL .ne 8 .IP "\fIXmNentryClass\fP" Specifies the only widget class that can be added to the RowColumn widget; this resource is meaningful only when the \fIXmNisHomogeneous\fP resource is set to True. Both widget and gadget variants of the specified class may be added to the widget. .IP When \fIXmCreateRadioBox\fP is called or when \fIXmNrowColumnType\fP is set to \fIXmWORK_AREA\fP and \fIXmNradioBehavior\fP is True, the default value of \fIXmNentryClass\fP is \fIxmToggleButtonGadgetClass\fP. When \fIXmNrowColumnType\fP is set to \fIXmMENU_BAR\fP, the value of \fIXmNentryClass\fP is forced to \fIxmCascadeButtonWidgetClass\fP. .IP "\fIXmNentryVerticalAlignment\fP" Specifies the type of vertical alignment for children that are subclasses of \fIXmLabel\fP, \fIXmLabelGadget, and \fIXmText\fP. This resource is invalid if \fIXmNorientation\fP is \fIXmVERTICAL\fP and \fIXmNpacking\fP is \fIXmPACK_TIGHT\fP because this layout preserves variable heights among the children. The vertical alignment types include: .TP \(bu \fIXmALIGNMENT_BASELINE_BOTTOM\fP \- causes the bottom baseline of all children in a row to be aligned. This resource is applicable only when all children in a row contain textual data. .TP \(bu \fIXmALIGNMENT_BASELINE_TOP\fP \- causes the top baseline of all children in a row to be aligned. This resource is applicable only when all children in a row contain textual data. .TP \(bu \fIXmALIGNMENT_CONTENTS_BOTTOM\fP \- causes the bottom of the contents (text or pixmap) of all children in a row to be aligned. .TP \(bu \fIXmALIGNMENT_CENTER\fP \- causes the center of all children in a row to be aligned. .TP \(bu \fIXmALIGNMENT_CONTENTS_TOP\fP \- causes the top of the contents (text or pixmap) of all children in a row to be aligned. .IP "\fIXmNisAligned\fP" Specifies text alignment for each item within the RowColumn widget; this applies only to items that are subclasses of \fIXmLabel\fP or \fIXmLabelGadget\fP. However, if the item is a Label widget or gadget and its parent is either a Popup MenuPane or a Pulldown MenuPane, alignment is not performed; the Label is treated as the title within the MenuPane, and the alignment set by the application is not overridden. \fIXmNentryAlignment\fP controls the type of textual alignment. .IP "\fIXmNisHomogeneous\fP" Indicates whether the RowColumn widget should enforce exact homogeneity among the items it contains; if True, only the widgets that are of the class indicated by \fIXmNentryClass\fP are allowed as children of the RowColumn widget. This is most often used when creating a MenuBar. Attempting to insert a child that is not a member of the specified class generates a warning message. .IP In a MenuBar the value of \fIXmNisHomogeneous\fP is forced to True. In an OptionMenu the value is forced to False. When \fIXmCreateRadioBox\fP is called the default value is True. Otherwise, the default value is False. .nL .ne 7 .IP "\fIXmNlabelString\fP" Points to a text string, which displays the label to one side of the selection area when \fIXmNrowColumnType\fP is set to \fIXmMENU_OPTION\fP. This resource is not meaningful for all other RowColumn types. If the application wishes to change the label after creation, it must get the LabelGadget ID (\fIXmOptionLabelGadget\fP) and call \fIXtSetValues\fP on the LabelGadget directly. The default value is no label. .IP "\fIXmNmapCallback\fP" Specifies a widget-specific callback function that is invoked when the window associated with the RowColumn widget is about to be mapped. The callback reason is \fIXmCR_MAP\fP. .IP "\fIXmNmarginHeight\fP" Specifies the amount of blank space between the top edge of the RowColumn widget and the first item in each column, and the bottom edge of the RowColumn widget and the last item in each column. The default value is 0 for Pulldown and Popup MenuPanes, and 3 pixels for other RowColumn types. .IP "\fIXmNmarginWidth\fP" Specifies the amount of blank space between the left edge of the RowColumn widget and the first item in each row, and the right edge of the RowColumn widget and the last item in each row. The default value is 0 for Pulldown and Popup MenuPanes, and 3 pixels for other RowColumn types. .IP "\fIXmNmenuAccelerator\fP" This resource is useful only when the RowColumn widget has been configured to operate as a Popup MenuPane or a MenuBar. The format of this resource is similar to the left side specification of a translation string, with the limitation that it must specify a key event. For a Popup MenuPane, when the accelerator is typed by the user, the Popup MenuPane is posted. For a MenuBar, when the accelerator is typed by the user, the first item in the MenuBar is highlighted, and traversal is enabled in the MenuBar. The default for a Popup MenuPane is \fIKMenu\fP. The default for a MenuBar is \fIKMenuBar\fP. The accelerator can be disabled by setting the \fIXmNpopupEnabled\fP resource to False. .IP "\fIXmNmenuHelpWidget\fP" Specifies the widget ID for the CascadeButton, which is treated as the Help widget if \fIXmNrowColumnType\fP is set to \fIXmMENU_BAR\fP. The MenuBar always places the Help widget at the bottom right corner (in a lef to right environment) of the MenuBar. If the RowColumn widget is any type other than \fIXmMENU_BAR\fP, this resource is not meaningful. .IP "\fIXmNmenuHistory\fP" Specifies the widget ID of the last menu entry to be activated. It is also useful for specifying the current selection for an OptionMenu. If \fIXmNrowColumnType\fP is set to \fIXmMENU_OPTION\fP, the specified menu item is positioned under the cursor when the menu is displayed. .IP If the RowColumn widget has the \fIXmNradioBehavior\fP resource set to True, the widget field associated with this resource contains the widget ID of the last ToggleButton or ToggleButtonGadget to change from unselected to selected. The default value is the widget ID of the first child in the widget. .IP "\fIXmNmenuPost\fP" Specifies an X event description indicating a button event that posts a menu system. The default for \fIXmMENU_POPUP\fP is \fIBMenu Press\fP. The default for \fIXmMENU_OPTION\fP, \fIXmMENU_BAR\fP, and \fIXmWORK_AREA\fP is \fIBSelect Press\fP. The \fIXmNmenuPost\fP resource for pulldowns should be consistent with that of top-level parent menu (although the event type is ignored). Setting this resource to \fIBDrag Press\fP will conflict with drag and drop operations, which use \fIBDrag Press\fP as a default button binding. .IP "\fIXmNmnemonic\fP" This resource is useful only when \fIXmNrowColumnType\fP is set to \fIXmMENU_OPTION\fP. Specifies a keysym for a key that, when pressed by the user along with the \fIMAlt\fP modifier, posts the associated Pulldown MenuPane. The first character in the OptionMenu label string that exactly matches the mnemonic in the character set specified in \fIXmNmnemonicCharSet\fP is underlined. The user can post the menu by pressing either the shifted or the unshifted mnemonic key. The default is no mnemonic. .IP "\fIXmNmnemonicCharSet\fP" Specifies the character set of the mnemonic for an OptionMenu. The default is \fIXmFONTLIST_DEFAULT_TAG\fP. If the RowColumn widget is any type other than \fIXmMENU_OPTION\fP, this resource is not meaningful. .nL .ne 6 .IP "\fIXmNnumColumns\fP" Specifies the number of minor dimension extensions that are made to accommodate the entries; this attribute is meaningful only when \fIXmNpacking\fP is set to \fIXmPACK_COLUMN\fP. .IP For vertically oriented RowColumn widgets, this attribute indicates how many columns are built; the number of entries per column is adjusted to maintain this number of columns, if possible. .IP For horizontally oriented RowColumn widgets, this attribute indicates how many rows are built. .IP The default value is 1. In an OptionMenu the value is forced to 1. The value must be greater than 0. .IP "\fIXmNorientation\fP" Determines whether RowColumn layouts are row-major or column-major. In a column-major layout, the children of the RowColumn are laid out in columns top to bottom within the widget. In a row-major layout the children of the RowColumn are laid out in rows. \fIXmVERTICAL\fP resource value selects a column-major layout. \fIXmHORIZONTAL\fP resource value selects a row-major layout. .IP When creating a MenuBar or an OptionMenu, the default is \fIXmHORIZONTAL\fP. Otherwise, the default value is \fIXmVERTICAL\fP. The results of specifying a value of \fIXmVERTICAL\fP for a MenuBar are undefined. .IP "\fIXmNpacking\fP" Specifies how to pack the items contained within a RowColumn widget. This can be set to \fIXmPACK_TIGHT, XmPACK_COLUMN\fP or \fIXmPACK_NONE\fP. When a RowColumn widget packs the items it contains, it determines its major dimension using the value of the \fIXmNorientation\fP resource. .nL .ne 9 .IP \fIXmPACK_TIGHT\fP indicates that given the current major dimension (for example, vertical if \fIXmNorientation\fP is \fIXmVERTICAL\fP), entries are placed one after the other until the RowColumn widget must wrap. RowColumn wraps when there is no room left for a complete child in that dimension. Wrapping occurs by beginning a new row or column in the next available space. Wrapping continues, as often as necessary, until all of the children are laid out. In the vertical dimension (columns), boxes are set to the same width; in the horizontal dimension (rows), boxes are set to the same depth. Each entry's position in the major dimension is left unaltered (for example, \fIXmNy\fP is left unchanged when \fIXmNorientation\fP is \fIXmVERTICAL\fP); its position in the minor dimension is set to the same value as the greatest entry in that particular row or column. The position in the minor dimension of any particular row or column is independent of all other rows or columns. .IP \fIXmPACK_COLUMN\fP indicates that all entries are placed in identically sized boxes. The box is based on the largest height and width values of all the children widgets. The value of the \fIXmNnumColumns\fP resource determines how many boxes are placed in the major dimension, before extending in the minor dimension. .IP \fIXmPACK_NONE\fP indicates that no packing is performed. The x and y attributes of each entry are left alone, and the RowColumn widget attempts to become large enough to enclose all entries. .IP When \fIXmCreateRadioBox\fP is called or when \fIXmNrowColumnType\fP is set to \fIXmWORK_AREA\fP and \fIXmNradioBehavior\fP is True, the default value of \fIXmNpacking\fP is \fIXmPACK_COLUMN\fP. In an OptionMenu the value is initialized to \fIXmPACK_TIGHT\fP. Otherwise, the value defaults to \fIXmPACK_TIGHT\fP. .nL .ne 12 .IP "\fIXmNpopupEnabled\fP" Allows the menu system to enable keyboard input (accelerators and mnemonics) defined for the Popup MenuPane and any of its submenus. The Popup MenuPane needs to be informed whenever its accessibility to the user changes because posting of the Popup MenuPane is controlled by the application. The default value of this resource is True (keyboard input \- accelerators and mnemonics \- defined for the Popup MenuPane and any of its submenus is enabled). ...\" .IP "\fIXmNpostFromCount\fP" ...\" This resource is useful only when \fIXmNrowColumnType\fP is ...\" set to \fIXmMENU_POPUP\fP or \fIXmMENU_PULLDOWN\fP. ...\" Specifies the number of widgets in the \fIXmNpostFromList\fP resource. ...\" .IP "\fIXmNpostFromList\fP" ...\" This resource is useful only when \fIXmNrowColumnType\fP is ...\" set to \fIXmMENU_POPUP\fP or \fIXmMENU_PULLDOWN\fP. ...\" Specifies a list of the widgets from which the MenuPane is to be ...\" accessible. ...\" If the menu is a Popup MenuPane and this resource is NULL, the menu is ...\" accessible from its parent. ...\" If the menu is a Pulldown MenuPane and this resource is NULL, the menu ...\" is accessible from the appropriate CascadeButton widget or gadget. ...\" The default is NULL. .IP "\fIXmNradioAlwaysOne\fP" If True, forces the active ToggleButton or ToggleButtonGadget to be automatically selected after having been unselected (if no other toggle was activated). If False, the active toggle may be unselected. The default value is True. This resource is important only when \fIXmNradioBehavior\fP is True. .IP The application can always add and subtract toggles from RowColumn regardless of the selected/unselected state of the toggle. The application can also manage and unmanage toggle children of RowColumn at any time regardless of state. Therefore, the application can sometimes create a RowColumn that has \fIXmNradioAlwaysOne\fP set to True and none of the toggle children selected. The result is undefined if the value of this resource is True and the application sets more than one ToggleButton at a time. .IP "\fIXmNradioBehavior\fP" Specifies a Boolean value that when True, indicates that the RowColumn widget should enforce a RadioBox-type behavior on all of its children that are ToggleButtons or ToggleButtonGadgets. .IP When the value of this resource is True, \fIXmNindicatorType\fP defaults to \fIXmONE_OF_MANY\fP for ToggleButton and ToggleButtonGadget children. .nL .ne 9 .IP RadioBox behavior dictates that when one toggle is selected and the user selects another toggle, the first toggle is unselected automatically. The RowColumn usually does not enforce this behavior if the application, rather than the user, changes the state of a toggle. The RowColumn does enforce this behavior if a toggle child is selected using \fIXmToggleButtonSetState\fP or \fIXmToggleButtonGadgetSetState\fP with a \fBnotify\fP argument of True. .IP When \fIXmCreateRadioBox\fP is called the default value of \fIXmNradioBehavior\fP is True. Otherwise, the default value is False. .IP "\fIXmNresizeHeight\fP" Requests a new height if necessary, when set to True. When set to False, the widget does not request a new height regardless of any changes to the widget or its children. .nL .ne 7 .IP "\fIXmNresizeWidth\fP" Requests a new width if necessary, when set to True. When set to False, the widget does not request a new width regardless of any changes to the widget or its children. .IP "\fIXmNrowColumnType\fP" Specifies the type of RowColumn widget to be created. It is a non-standard resource that cannot be changed after it is set. If an application uses any of the convenience routines, except \fIXmCreateRowColumn\fP, this resource is automatically forced to the appropriate value by the convenience routine. If an application uses the Xt Intrinsics API to create its RowColumn widgets, it must specify this resource itself. The set of possible settings for this resource are: .IP \fIXmWORK_AREA\fP \- the default .IP \fIXmMENU_BAR\fP .IP \fIXmMENU_PULLDOWN\fP .IP \fIXmMENU_POPUP\fP .IP \fIXmMENU_OPTION\fP .nL .ne 4 .IP This resource cannot be changed after the RowColumn widget is created. Any changes attempted through \fIXtSetValues\fP are ignored. .IP The value of this resource is used to determine the value of a number of other resources. The descriptions of RowColumn resources explain this when it is the case. The resource \fIXmNnavigationType\fP, inherited from \fIXmManager\fP, is changed to \fIXmNONE\fP if \fIXmNrowColumnType\fP is \fIXmMENU_OPTION\fP. .nL .ne 6 .IP "\fIXmNspacing\fP" Specifies the horizontal and vertical spacing between items contained within the RowColumn widget. The default value is 3 pixels for \fIXmOPTION_MENU\fP and \fIXmWORK_AREA\fP and 0 for other RowColumn types. .IP "\fIXmNsubMenuId\fP" Specifies the widget ID for the Pulldown MenuPane to be associated with an OptionMenu. This resource is useful only when \fIXmNrowColumnType\fP is set to \fIXmMENU_OPTION\fP. The default value is NULL. .IP "\fIXmNtearOffMenuActivateCallback\fP" Specifies the callback list that notifies the application when the tear-off MenuPane is about to be activated. It precedes the tear-off's map callback. .IP Use this resource when your application has shared MenuPanes and when the torn-off menu can have two or more parents that can have opposing sensitivity states for the same menu item. This resource enables the application to track whether a menu item is sensitive or insensitive and to set the state to the original parent's menu item state when the torn-off menu is reposted. The application can use \fIXmGetPostedFromWidget\fP to determine from which parent the menu was torn. The callback reason is \fIXmCR_TEAR_OFF_ACTIVATE\fP. The default is NULL. .IP "\fIXmNtearOffMenuDeactivateCallback\fP" Specifies the callback list that notifies the application when the tear-off MenuPane is about to be deactivated. It follows the tear-off's unmap callback. .IP Use this resource when your application has shared MenuPanes and when the torn-off menu can have two or more parents that can have opposing sensitivity states for the same menu item. This resource enables the application to track whether a menu item is sensitive or insensitive and to set the state to the original parent's menu item state when the torn-off menu is reposted. The application can use \fIXmGetPostedFromWidget\fP to determine from which parent the menu was torn. The callback reason is \fIXmCR_TEAR_OFF_DEACTIVATE\fP. The default is NULL. .IP "\fIXmNtearOffModel\fP" Indicates whether tear-off functionality is enabled or disabled when \fIXmNrowColumnType\fP is set to \fIXmMENU_PULLDOWN\fP or \fIXmMENU_POPUP\fP. The values are: \fIXmTEAR_OFF_ENABLED\fP or \fIXmTEAR_OFF_DISABLED\fP (default value). This resource is invalid for type \fIXmMENU_OPTION\fP; however, it does affect any pulldown submenus within an OptionMenu. The function \fIXmRepTypeInstallTearOffModelConverter\fP installs a resource converter for this resource. .IP "\fIXmNunmapCallback\fP" Specifies a list of callbacks that is called after the window associated with the RowColumn widget has been unmapped. The callback reason is \fIXmCR_UNMAP\fP. The default value is NULL. .IP "\fIXmNwhichButton\fP" This resource is obsolete; it has been replaced by \fIXmNmenuPost\fP and is present for compatibility with older releases of 1/Motif. .IP .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmRowColumn Constraint Resource Set Name Class Type Default Access _ XmNpositionIndex XmCPositionIndex short XmLAST_POSITION CSG .TE .KE .in .sp 1 .IP "\fIXmNpositionIndex\fP" Specifies the position of the widget in its parent's list of children (the value of the \fIXmNchildren\fP resource). The value is an integer that is no less than zero and no greater than the number of children in the list at the time the value is specified. A value of zero means that the child is placed at the beginning of the list. The value can also be specified as \fIXmLAST_POSITION\fP (the default), which means that the child is placed at the end of the list. Any other value is ignored. \fIXtGetValues\fP returns the position of the widget in its parent's child list at the time of the call to \fIXtGetValues\fP. .IP When a widget is inserted into its parent's child list, the positions of any existing children that are greater than or equal to the specified widget's \fIXmNpositionIndex\fP are increased by one. The effect of a call to \fIXtSetValues\fP for \fIXmNpositionIndex\fP is to remove the specified widget from its parent's child list, decrease by one the positions of any existing children that are greater than the specified widget's former position in the list, and then insert the specified widget into its parent's child list as described in the preceding sentence. .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Simple Menu Creation Resource Set Name Class Type Default Access _ XmNbuttonAccelerators XmCButtonAccelerators StringTable NULL C XmNbuttonAcceleratorText XmCButtonAcceleratorText XmStringTable NULL C XmNbuttonCount XmCButtonCount int 0 C XmNbuttonMnemonicCharSets XmCButtonMnemonicCharSets XmStringCharSetTable NULL C XmNbuttonMnemonics XmCButtonMnemonics XmKeySymTable NULL C XmNbuttons XmCButtons XmStringTable NULL C XmNbuttonSet XmCButtonSet int \-1 C XmNbuttonType XmCButtonType XmButtonTypeTable NULL C XmNoptionLabel XmCOptionLabel XmString NULL C XmNoptionMnemonic XmCOptionMnemonic KeySym NULL C XmNpostFromButton XmCPostFromButton int \-1 C XmNsimpleCallback XmCCallback XtCallbackProc NULL C .TE .KE .in .sp 1 .wH .in .IP "\fIXmNbuttonAccelerators\fP" This resource is for use with the simple menu creation routines. It specifies a list of accelerators for the buttons created. The list contains one element for each button, separator, and title created. .nL .ne 6 .IP "\fIXmNbuttonAcceleratorText\fP" This resource is for use with the simple menu creation routines. It specifies a list of compound strings to display for the accelerators for the buttons created. The list contains one element for each button, separator, and title created. .IP "\fIXmNbuttonCount\fP" This resource is for use with the simple menu creation routines. It specifies the total number of menu buttons, separators, and titles to create. The value must not be negative. .IP "\fIXmNbuttonMnemonicCharSets\fP" This resource is for use with the simple menu creation routines. It specifies a list of character sets with which button mnemonics are to be displayed. The list contains one element for each button, separator, and title created. The default is determined dynamically depending on the locale of the widget. .IP "\fIXmNbuttonMnemonics\fP" This resource is for use with the simple menu creation routines. It specifies a list of mnemonics for the buttons created. The list contains one element for each button, separator, and title created. .IP "\fIXmNbuttons\fP" This resource is for use with the simple menu creation routines. It specifies a list of compound strings to use as labels for the buttons created. The list contains one element for each button, separator, and title created. .IP "\fIXmNbuttonSet\fP" This resource is for use with the simple menu creation routines. It specifies which button of a RadioBox or OptionMenu Pulldown submenu is initially set. The value is an integer \fBn\fP indicating the \fBn\fPth ToggleButtonGadget specified for a RadioBox or the \fBn\fPth PushButtonGadget specified for an OptionMenu Pulldown submenu. The first button specified is number 0. The value must not be negative. .nL .ne 4 .IP "\fIXmNbuttonType\fP" This resource is for use with the simple menu creation routines. It specifies a list of button types associated with the buttons to be created. The list contains one element for each button, separator, and title created. If this resource is not specified, each button in a MenuBar is a CascadeButtonGadget, each button in a RadioBox or CheckBox is a ToggleButtonGadget, and each button in any other type of RowColumn widget is a PushButtonGadget. Each button type is of type \fIXmButtonType\fP, an enumeration with the following possible values: .IP \fIXmCASCADEBUTTON\fP \- Specifies a CascadeButtonGadget for a MenuBar, Popup MenuPane, or Pulldown MenuPane. .IP \fIXmCHECKBUTTON\fP \- Specifies a ToggleButtonGadget for a CheckBox, Popup MenuPane, or Pulldown MenuPane. .IP \fIXmDOUBLE_SEPARATOR\fP \- Specifies a SeparatorGadget for a Popup MenuPane, Pulldown MenuPane, or OptionMenu Pulldown submenu. The separator type is \fIXmDOUBLE_LINE\fP. .IP \fIXmPUSHBUTTON\fP \- Specifies a PushButtonGadget for a Popup MenuPane, Pulldown MenuPane, or OptionMenu Pulldown submenu. .IP \fIXmRADIOBUTTON\fP \- Specifies a ToggleButtonGadget for a RadioBox, Popup MenuPane, or Pulldown MenuPane. .IP \fIXmSEPARATOR\fP \- Specifies a SeparatorGadget for a Popup MenuPane, Pulldown MenuPane, or OptionMenu Pulldown submenu. .IP \fIXmTITLE\fP \- Specifies a LabelGadget used as a title for a Popup MenuPane or Pulldown MenuPane. .IP "\fIXmNoptionLabel\fP" This resource is for use with the simple menu creation routines. It specifies a compound string for the label string to be used on the left side of an OptionMenu. .nL .ne 8 .IP "\fIXmNoptionMnemonic\fP" This resource is for use with the simple menu creation routines. It specifies a keysym for a key that, when pressed by the user along with the \fIMAlt\fP modifier, posts the associated Pulldown MenuPane for an OptionMenu. .IP "\fIXmNpostFromButton\fP" This resource is for use with the simple menu creation routines. For a Pulldown MenuPane, it specifies the button in the parent to which the submenu is attached. The menu is then posted from this button. The value is an integer \fBn\fP indicating the \fBn\fPth CascadeButton or CascadeButtonGadget specified for the parent of the Pulldown MenuPane. The first button specified is number 0. The value must not be negative. .IP "\fIXmNsimpleCallback\fP" This resource is for use with the simple menu creation routines. It specifies a callback procedure to be called when a button is activated or when its value changes. This callback function is added to each button after creation. For a CascadeButtonGadget or a PushButtonGadget, the callback is added as the button's \fIXmNactivateCallback\fP, and it is called when the button is activated. For a ToggleButtonGadget, the callback is added as the button's \fIXmNvalueChangedCallback\fP, and it is called when the button's value changes. The button number is passed in the \fBclient_data\fP field. .SS "Inherited Resources" RowColumn inherits behavior and resources from the following named superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmManager Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget NULL CSG XmNnavigationType XmCNavigationType XmNavigationType dynamic CSG XmNshadowThickness XmCShadowThickness Dimension dynamic CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean dynamic CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc default procedure CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.1i .nf typedef struct { int \fBreason\fI; XEvent \fB* event\fI; Widget \fBwidget\fI; char \fB* data\fI; char \fB* callbackstruct\fI; } XmRowColumnCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback .IP The following fields apply only when the callback reason is \fIXmCR_ACTIVATE\fP; for all other callback reasons, these fields are set to NULL. The \fIXmCR_ACTIVATE\fP callback reason is generated only when the application has supplied an entry callback, which overrides any activation callbacks registered with the individual RowColumn items. .IP "\fBwidget\fP" Is set to the widget ID of the RowColumn item that has been activated .IP "\fBdata\fP" Contains the client-data value supplied by the application when the RowColumn item's activation callback was registered .IP "\fBcallbackstruct\fP" Points to the callback structure generated by the RowColumn item's activation callback .SS "Translations" XmRowColumn translations depend on the value of the \fIXmNrowColumnType\fP resource. .PP If \fIXmNrowColumnType\fP is set to \fIXmWORK_AREA\fP, XmRowColumn inherits translations from XmManager. .PP If \fIXmNrowColumnType\fP is set to \fIXmMENU_OPTION\fP, XmRowColumn inherits traversal, KActivate, and KCancel translations from XmManager and has the additional translations listed below. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BSelect Press: MenuBtnDown() BSelect Release: MenuBtnUp() KSelect: ManagerGadgetSelect() KHelp: Help() .wH .fi .iE .PP The translations for XmRowColumn if \fIXmNrowColumnType\fP is set to \fIXmMENU_BAR\fP \fIXmMENU_PULLDOWN\fP, or \fIXmMENU_POPUP\fP are listed below. In a Popup menu system, \fIBMenu\fP also performs the \fIBSelect\fP actions. When the value of the XmDisplay resource \fIenableMenuInCascade\fP is True, \fIBMenu\fP also performs the \fIBSelect\fP actions in all types of menu systems. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BSelect Press: MenuBtnDown() BSelect Release: MenuBtnUp() KActivate: ManagerGadgetSelect() KSelect: ManagerGadgetSelect() MAny KCancel: MenuGadgetEscape() KHelp: Help() KLeft: MenuGadgetTraverseLeft() KRight: MenuGadgetTraverseRight() KUp: MenuGadgetTraverseUp() KDown: MenuGadgetTraverseDown() .wH .fi .iE .SS "Action Routines" The XmRowColumn action routines are described below: .IP "\fIHelp()\fP:" Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIManagerGadgetSelect()\fP:" When a gadget child of the menu has the focus, invokes the gadget child's behavior associated with \fIKSelect\fP. This generally has the effect of unposting the menu hierarchy and arming and activating the gadget, except that for a CascadeButtonGadget with a submenu, it posts the submenu. .IP "\fIMenuBtnDown()\fP:" When a gadget child of the menu has the focus, invokes the gadget child's behavior associated with \fIBSelect Press\fP. This generally has the effect of unposting any menus posted by the parent menu, enabling mouse traversal in the menu, and arming the gadget. For a CascadeButtonGadget with a submenu, it also posts the associated submenu. .nL .ne 9 .IP "\fIMenuBtnUp()\fP:" When a gadget child of the menu has the focus, invokes the gadget child's behavior associated with \fIBSelect Release\fP. This generally has the effect of unposting the menu hierarchy and activating the gadget, .ne 4 except that for a CascadeButtonGadget with a submenu, it posts the submenu and enables keyboard traversal in the menu. .IP "\fIMenuGadgetEscape()\fP:" In a toplevel Pulldown MenuPane from a MenuBar, unposts the menu, disarms the MenuBar CascadeButton and the MenuBar, and, when the shell's keyboard focus policy is \fIXmEXPLICIT\fP, restores keyboard focus to the widget that had the focus before the MenuBar was entered. In other Pulldown MenuPanes, unposts the menu. .IP In a Popup MenuPane, unposts the menu and, when the shell's keyboard focus policy is \fIXmEXPLICIT\fP, restores keyboard focus to the widget from which the menu was posted. In a TearOff MenuPane that has no submenus posted, dismisses the menu; otherwise, if one or more submenus are posted, unposts the last menu pane. .IP "\fIMenuGadgetTraverseDown()\fP:" If the current menu item has a submenu and is in a MenuBar, then this action posts the submenu, disarms the current menu item, and arms the submenu's first traversable menu item. .IP If the current menu item is in a MenuPane, then this action disarms the current menu item and arms the item below it. This action wraps within the MenuPane. When the current menu item is at the MenuPane's bottom edge, then this action wraps to the topmost menu item in the column to the right, if one exists. When the current menu item is at the bottom, rightmost corner of the MenuPane, then this action wraps to the tear-off control, if present, or to the top, leftmost menu item. .IP "\fIMenuGadgetTraverseLeft()\fP:" When the current menu item is in a MenuBar, then this action disarms the current item and arms the MenuBar item to the left. This action wraps within the MenuBar. .IP In MenuPanes, if the current menu item is not at the left edge of a MenuPane, this action disarms the current item and arms the item to its left. If the current menu item is at the left edge of a submenu attached to a MenuBar item, then this action unposts the submenu and traverses to the MenuBar item to the left, wrapping if necessary. If that MenuBar item has a submenu, it posts the submenu and arms the first traversable item in the submenu. If the current menu item is at the left edge of a submenu not directly attached to a MenuBar item, then this action unposts the current submenu only. .IP In Popup or Torn-off MenuPanes, when the current menu item is at the left edge, this action wraps within the MenuPane. If the current menu item is at the left edge of the MenuPane and not in the top row, this action wraps to the rightmost menu item in the row above. If the current menu item is in the upper, leftmost corner, this action wraps to the tear-off control, if present, or else it wraps to the bottom, rightmost menu item in the MenuPane. .nL .ne 8 .IP "\fIMenuGadgetTraverseRight()\fP:" If the current menu item is in a MenuBar, then this action disarms the current item and arms the MenuBar item to the right. This action wraps within the MenuBar. .IP In MenuPanes, if the current menu item is a CascadeButton, then this action posts its associated submenu. If the current menu item is not a CascadeButton and is not at the right edge of a MenuPane, this action disarms the current item and arms the item to its right, wrapping if necessary. If the current menu item is not a CascadeButton and is at the right edge of a submenu that is a descendent of a MenuBar, then this action unposts all submenus and traverses to the MenuBar item to the right. If that MenuBar item has a submenu, it posts the submenu and arms the submenu's first traversable item. .IP In Popup or Torn-off menus, if the current menu item is not a CascadeButton and is at the right edge of a row (except the bottom row), this action wraps to the leftmost menu item in the row below. If the current menu item is not a CascadeButton and is in the bottom, rightmost corner of a Popup or Pulldown MenuPane, this action wraps to the tear-off control, if present, or else it wraps to the top, leftmost menu item of the MenuPane. .IP "\fIMenuGadgetTraverseUp()\fP:" When the current menu item is in a MenuPane, then this action disarms the current menu item and arms the item above it. This action wraps within the MenuPane. When the current menu item is at the MenuPane's top edge, then this action wraps to the bottommost menu item in the column to the left, if one exists. When the current menu item is at the top, leftmost corner of the MenuPane, then this action wraps to the tear-off control, if present, or to the bottom, rightmost menu item. .SS "Related Behavior" The following menu functions are available. .IP "\fIKMenuBar\fP:" In any non-popup descendant of a MenuBar's parent, excluding the MenuBar itself, this action enables keyboard traversal and moves keyboard focus to the first item in the MenuBar. In the MenuBar or any menu cascaded from it, this action unposts the menu hierarchy and, when the shell's keyboard focus policy is \fIXmEXPLICIT\fP, restores focus to the widget that had the focus when the menu system was entered. .IP "\fIKMenu\fP:" Pops up the menu associated with the control that has the keyboard focus. Enables keyboard traversal in the menu. In the Popup menu system or any menu cascaded from it, this action unposts the menu hierarchy and, when the shell's keyboard focus policy is \fIXmEXPLICIT\fP, restores focus to the widget that had the focus when the menu system was entered. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fIConstraint(3X)\fP, \fICore(3X)\fP, \fIXmCreateMenuBar(3X)\fP, \fIXmCreateOptionMenu(3X)\fP, \fIXmCreatePopupMenu(3X)\fP, \fIXmCreatePulldownMenu(3X)\fP, \fIXmCreateRadioBox(3X)\fP, \fIXmCreateRowColumn(3X)\fP, \fIXmCreateSimpleCheckBox(3X)\fP, \fIXmCreateSimpleMenuBar(3X)\fP, \fIXmCreateSimpleOptionMenu(3X)\fP, \fIXmCreateSimplePopupMenu(3X)\fP, \fIXmCreateSimplePulldownMenu(3X)\fP, \fIXmCreateSimpleRadioBox(3X)\fP, \fIXmCreateWorkArea(3X)\fP, \fIXmDisplay(3X)\fP, \fIXmGetMenuCursor(3X)\fP, \fIXmGetPostedFromWidget(3X)\fP, \fIXmGetTearOffControl\fP, \fIXmLabel(3X)\fP, \fIXmManager(3X)\fP, \fIXmMenuPosition(3X)\fP, \fIXmOptionButtonGadget(3X)\fP, \fIXmOptionLabelGadget(3X)\fP, \fIXmRepTypeInstallTearOffModelConverter\fP, \fIXmSetMenuCursor(3X)\fP, \fIXmUpdateDisplay(3X)\fP, \fIXmVaCreateSimpleCheckBox(3X)\fP, \fIXmVaCreateSimpleMenuBar(3X)\fP, \fIXmVaCreateSimpleOptionMenu(3X)\fP, \fIXmVaCreateSimplePopupMenu(3X)\fP, \fIXmVaCreateSimplePulldownMenu(3X)\fP, and \fIXmVaCreateSimpleRadioBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmScale 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmScale\fP \- The Scale widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi Scale is used by an application to indicate a value from within a range of values, and it allows the user to input or modify a value from the same range. .PP A Scale has an elongated rectangular region similar to a ScrollBar. A slider inside this region indicates the current value along the Scale. The user can also modify the Scale's value by moving the slider within the rectangular region of the Scale. A Scale can also include a label set located outside the Scale region. These can indicate the relative value at various positions along the scale. .PP A Scale can be either input/output or output only. An input/output Scale's value can be set by the application and also modified by the user with the slider. An output-only Scale is used strictly as an indicator of the current value of something and cannot be modified interactively by the user. The \fICore\fP resource \fIXmNsensitive\fP specifies whether the user can interactively modify the Scale's value. Alternately, the resource \fIslidingMode\fP can be set to provide an output only Scale. The gauge has a different look from the Scale so that the end user can distinguish an output only Scale from an input/output Scale. The gauge does not display the slider control, and uses color inside the rectangular region to indicate the current value. .PP The user can specify resources in a resource file for the automatically created gadget that contains the title of the Scale widget. The name of the gadget is "Title". .SS "Classes" Scale inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIConstraint\fP, and \fIXmManager\fP classes. .PP The class pointer is \fIxmScaleWidgetClass\fP. .PP The class name is \fIXmScale\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmScale Resource Set Name Class Type Default Access _ XmNdecimalPoints XmCDecimalPoints short 0 CSG XmNdragCallback XmCCallback XtCallbackList NULL C XmNfontList XmCFontList XmFontList dynamic CSG XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG XmNmaximum XmCMaximum int 100 CSG XmNminimum XmCMinimum int 0 CSG XmNorientation XmCOrientation unsigned char XmVERTICAL CSG XmNprocessingDirection XmCProcessingDirection unsigned char dynamic CSG XmNscaleHeight XmCScaleHeight Dimension 0 CSG XmNscaleMultiple XmCScaleMultiple int dynamic CSG XmNscaleWidth XmCScaleWidth Dimension 0 CSG XmNshowValue XmCShowValue Boolean False CSG slidingMode SlidingMode XtEnum "slider" C .wH .tH XmNtitleString XmCTitleString XmString NULL CSG XmNvalue XmCValue int dynamic CSG XmNvalueChangedCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .IP "\fIXmNdecimalPoints\fP" Specifies the number of decimal points to shift the slider value when displaying it. For example, a slider value of 2,350 and an \fIXmdecimalPoints\fP value of 2 results in a display value of 23.50. The value must not be negative. .IP "\fIXmNdragCallback\fP" Specifies the list of callbacks that is called when the slider position changes as the slider is being dragged. The reason sent by the callback is \fIXmCR_DRAG\fP. .IP "\fIXmNfontList\fP" Specifies the font list to use for the title text string specified by \fIXmNtitleString\fP, and the label displayed when \fIXmNshowValue\fP is True. If this value is NULL at initialization, the font list is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard, VendorShell, or XmMenuShell widget class. If such an ancestor is found, the font list is initialized to the \fIXmNlabelFontList\fP of the ancestor widget. If no such ancestor is found, the default is implementation dependent. Refer to \fIXmFontList(3X)\fP for more information on the creation and structure of a font list. .IP "\fIXmNhighlightOnEnter\fP" Specifies whether the highlighting rectangle is drawn when the cursor moves into the widget. If the shell's focus policy is \fIXmEXPLICIT\fP, this resource is ignored, and the widget is highlighted when it has the focus. If the shell's focus policy .ne 10 is \fIXmPOINTER\fP and if this resource is True, the highlighting rectangle is drawn when the the cursor moves into the widget. If the shell's focus policy is \fIXmPOINTER\fP and if this resource is False, the highlighting rectangle is not drawn when the the cursor moves into the widget. The default is False. .IP "\fIXmNhighlightThickness\fP" Specifies the size of the slider's border drawing rectangle used for enter window and traversal highlight drawing. .IP "\fIXmNmaximum\fP" Specifies the slider's maximum value. \fIXmNmaximum\fP must be greater than \fIXmNminimum\fP. .IP "\fIXmNminimum\fP" Specifies the slider's minimum value. \fIXmNmaximum\fP must be greater than \fIXmNminimum\fP. .IP "\fIXmNorientation\fP" Displays Scale vertically or horizontally. This resource can have values of \fIXmVERTICAL and XmHORIZONTAL\fP. .IP "\fIXmNprocessingDirection\fP" Specifies whether the value for \fIXmNmaximum\fP is on the right or left side of \fIXmNminimum\fP for horizontal Scales or above or below \fIXmNminimum\fP for vertical Scales. This resource can have values of \fIXmMAX_ON_TOP, XmMAX_ON_BOTTOM,XmMAX_ON_LEFT\fP, and \fIXmMAX_ON_RIGHT\fP. If the XmScale is oriented vertically, the default value is \fIXmMAX_ON_TOP\fP. If the XmScale is oriented horizontally, the default value may depend on the value of the \fIXmNstringDirection\fP resource. .IP "\fIXmNscaleHeight\fP" Specifies the height of the slider area. The value should be in the specified unit type (the default is pixels). If no value is specified a default height is computed. .IP "\fIXmNscaleMultiple\fP" Specifies the amount to move the slider when the user takes an action that moves the slider by a multiple increment. The default is (\fIXmNmaximum\fP \- \fIXmNminimum\fP) divided by 10, with a minimum of 1. .IP "\fIXmNscaleWidth\fP" Specifies the width of the slider area. The value should be in the specified unit type (the default is pixels). If no value is specified a default width is computed. .nL .ne 6 .IP "\fIXmNshowValue\fP" Specifies whether a label for the current slider value should be displayed next to the slider. If the value is True, the current slider value is displayed. .IP "\fIslidingMode\fP" Specifies a read-only look for the XmScale. When \fIslidingMode\fP is "thermometer", the slider control on the XmScale is not displayed. The color of the XmScale indicates the current value. When \fIslidingMode\fP is "slider" the look of the XmScale widget is not changed. .IP "\fIXmNtitleString\fP" Specifies the title text string to appear in the Scale widget window. .IP "\fIXmNvalue\fP" Specifies the slider's current position along the scale, between \fIXmNminimum\fP and \fIXmNmaximum\fP. The value is constrained to be within these inclusive bounds. The initial value of this resource is the larger of 0 and \fIXmNminimum\fP. .IP "\fIXmNvalueChangedCallback\fP" Specifies the list of callbacks that is called when the value of the slider has changed. The reason sent by the callback is \fIXmCR_VALUE_CHANGED\fP. .SS "Inherited Resources" Scale inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmManager Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget NULL CSG XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.1i .nf typedef struct { int \fBreason\fI; XEvent \fB* event\fI; int \fBvalue\fI; } XmScaleCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback .IP "\fBvalue\fP" Is the new slider value .SS "Behavior" XmScale behavior is described below: .IP "\fIBSelect\ Press\fP\ or\ \fIBDrag\ Press\fP:" (in region between an end of the Scale and the slider): Moves the slider by one multiple increment in the direction of the end of the Scale and calls the \fIXmNvalueChangedCallback\fP callbacks. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_RIGHT\fP or \fIXmMAX_ON_BOTTOM\fP, movement toward the right or bottom increments the Scale value, and movement toward the left or top decrements the Scale value. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_LEFT\fP or \fIXmMAX_ON_TOP\fP, movement toward the right or bottom decrements the Scale value, and movement toward the left or top increments the Scale value. If the button is held down longer than a delay period, the slider is moved again by the same increment and the same callbacks are called. .IP (in slider): Activates the interactive dragging of the slider. .IP "\fIBSelect\ Motion\fP\ or\ \fIBDrag\ Motion\fP:" If the button press occurs within the slider, the subsequent motion events move the slider to the position of the pointer and call the callbacks for \fIXmNdragCallback\fP. .IP "\fIBSelect\ Release\fP\ or\ \fIBDrag\ Release\fP:" If the button press occurs within the slider and the slider position is changed, the callbacks for \fIXmNvalueChangedCallback\fP are called. .IP "\fIMCtrl\ BSelect\ Press\fP:" \fI(in region between an end of the Scale and the slider)\fP: Moves the slider to that end of the Scale and calls the \fIXmNvalueChangedCallback\fP callbacks. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_RIGHT\fP or \fIXmMAX_ON_BOTTOM\fP, movement toward the right or bottom increments the Scale value, and movement toward the left or top decrements the Scale value. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_LEFT\fP or \fIXmMAX_ON_TOP\fP, movement toward the right or bottom decrements the Scale value, and movement toward the left or top increments the Scale value. .IP "\fIKUp\fP:" For vertical Scales, moves the slider up one increment and calls the \fIXmNvalueChangedCallback\fP callbacks. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_TOP\fP, movement toward the top increments the Scale value. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_BOTTOM\fP, movement toward the top decrements the Scale value. .IP "\fIKDown\fP:" For vertical Scales, moves the slider down one increment and calls the \fIXmNvalueChangedCallback\fP callbacks. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_BOTTOM\fP, movement toward the bottom increments the Scale value. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_TOP\fP, movement toward the bottom decrements the Scale value. .IP "\fIKLeft\fP:" For horizontal Scales, moves the slider one increment to the left and calls the \fIXmNvalueChangedCallback\fP callbacks. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_LEFT\fP, movement toward the left increments the Scale value. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_RIGHT\fP, movement toward the left decrements the Scale value. .IP "\fIKRight\fP:" For horizontal Scales, moves the slider one increment to the right and calls the \fIXmNvalueChangedCallback\fP callbacks. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_RIGHT\fP, movement toward the right increments the Scale value. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_LEFT\fP, movement toward the right decrements the Scale value. .IP "\fIMCtrl\ KUp\fP\ or\ \fIKPageUp\fP:" For vertical Scales, moves the slider up one multiple increment and calls the \fIXmNvalueChangedCallback\fP callbacks. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_TOP\fP, movement toward the top increments the Scale value. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_BOTTOM\fP, movement toward the top decrements the Scale value. .IP "\fIMCtrl\ KDown\fP\ or\ \fIKPageDown\fP:" For vertical Scales, moves the slider down one multiple increment and calls the \fIXmNvalueChangedCallback\fP callbacks. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_BOTTOM\fP, movement toward the bottom increments the Scale value. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_TOP\fP, movement toward the bottom decrements the Scale value. .IP "\fIMCtrl\ KLeft\fP\ or\ \fIKPageLeft\fP:" For horizontal Scales, moves the slider one multiple increment to the left and calls the \fIXmNvalueChangedCallback\fP callbacks. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_LEFT\fP, movement toward the left increments the Scale value. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_RIGHT\fP, movement toward the left decrements the Scale value. .IP "\fIMCtrl\ KRight\fP\ or\ \fIKPageRight\fP:" For horizontal Scales, moves the slider one multiple increment to the right and calls the \fIXmNvalueChangedCallback\fP callbacks. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_RIGHT\fP, movement toward the right increments the Scale value. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_LEFT\fP, movement toward the right decrements the Scale value. .IP "\fIKBeginLine\fP\ or\ \fIKBeginData\fP:" Moves the slider to the minimum value and calls the \fIXmNvalueChangedCallback\fP callbacks. .IP "\fIKEndLine\fP\ or\ \fIKEndData\fP:" Moves the slider to the maximum value and calls the \fIXmNvalueChangedCallback\fP callbacks. .IP "\fIKNextField\fP:" Traverses to the first item in the next tab group. If the current tab group is the last entry in the tab group list, it wraps to the beginning of the tab group list. .IP "\fIKPrevField\fP:" Traverses to the first item in the previous tab group. If the beginning of the tab group list is reached, it wraps to the end of the tab group list. .IP "\fIKHelp\fP:" Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fIConstraint(3X)\fP, \fICore(3X)\fP, \fIXmCreateScale(3X)\fP, \fIXmManager(3X)\fP, \fIXmScaleGetValue(3X)\fP, and \fIXmScaleSetValue(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmScaleGetValue 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmScaleGetValue\fP \- A Scale function that returns the current slider position .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmScaleGetValue (\fBwidget, value_return\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fB* value_return\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmScaleGetValue\fP returns the current slider position value displayed in the scale. .IP "\fBwidget\fP" Specifies the Scale widget ID .IP "\fBvalue_return\fP" Returns the current slider position value .PP For a complete definition of Scale and its associated resources, see \fIXmScale(3X)\fP. .SH RELATED INFORMATION .na \fIXmScale(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmScaleSetValue 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmScaleSetValue\fP \- A Scale function that sets a slider value .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmScaleSetValue (\fBwidget, value\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBvalue\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmScaleSetValue\fP sets the slider \fBvalue\fP within the Scale widget. .IP "\fBwidget\fP" Specifies the Scale widget ID. .IP "\fBvalue\fP" Specifies the slider position along the scale. This sets the \fIXmNvalue\fP resource. .PP For a complete definition of Scale and its associated resources, see \fIXmScale(3X)\fP. .SH RELATED INFORMATION .na \fIXmScale(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmScreen 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmScreen\fP \- The Screen widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi The XmScreen object is used by Motif widgets to store information that is specific to a screen. It also allows the toolkit to store certain information on widget hierarchies that would otherwise be unavailable. Each client has one XmScreen object for each screen that it accesses. .PP An XmScreen object is automatically created when the application creates the first shell on a screen (usually accomplished by a call to \fIXtAppInitialize\fP or \fIXtAppCreateShell\fP). It is not necessary to create an XmScreen object by any other means. An application can use the function \fIXmGetXmScreen\fP to obtain the widget ID of the XmScreen object for a given screen. .PP An application cannot supply initial values for XmScreen resources as arguments to a call to any function that creates widgets. The application or user can supply initial values in a resource file. After creating the first shell on the screen, the application can use \fIXmGetXmScreen\fP to obtain the widget ID of the XmScreen object and then call \fIXtSetValues\fP to set the XmScreen resources. .SS "Classes" Screen inherits behavior and resources from \fICore\fP. .PP The class pointer is \fIxmScreenClass\fP. .PP The class name is \fIXmScreen\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in an \fI\&.Xdefaults\fP file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in an \fI\&.Xdefaults\fP file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmScreen Resource Set Name Class Type Default Access _ XmNdarkThreshold XmCDarkThreshold int dynamic C XmNdefaultCopyCursorIcon XmCDefaultCopyCursorIcon Widget NULL CSG XmNdefaultInvalidCursorIcon XmCDefaultInvalidCursorIcon Widget NULL CSG XmNdefaultLinkCursorIcon XmCDefaultLinkCursorIcon Widget NULL CSG XmNdefaultMoveCursorIcon XmCDefaultMoveCursorIcon Widget NULL CSG XmNdefaultNoneCursorIcon XmCDefaultNoneCursorIcon Widget NULL CSG XmNdefaultSourceCursorIcon XmCDefaultSourceCursorIcon Widget NULL CSG XmNdefaultValidCursorIcon XmCDefaultValidCursorIcon Widget NULL CSG XmNfont XmCFont XFontStruct * NULL CSG XmNforegroundThreshold XmCForegroundThreshold int dynamic C XmNhorizontalFontUnit XmCHorizontalFontUnit int dynamic CSG XmNlightThreshold XmCLightThreshold int dynamic C XmNmenuCursor XmCCursor String arrow C XmNmoveOpaque XmCMoveOpaque Boolean False CSG XmNunpostBehavior XmCUnpostBehavior unsigned char XmUNPOST_AND_REPLAY CSG XmNverticalFontUnit XmCVerticalFontUnit int dynamic CSG .TE .KE .in .sp 1 .IP "\fIXmNdarkThreshold\fP" An integer between 0 and 100, inclusive, that specifies a level of perceived brightness for a color. If the perceived brightness of the background color is below this level, Motif treats the background as "dark" when computing default shadow and select colors. If this resource is specified for a particular screen, it applies to widgets created on that screen; otherwise it applies to widgets created on all screens. The default value is implementation specific. .IP Specifies the DragIcon used during a drag operation when the operation is a copy and no other pixmap is specified by the application. If NULL, a system default icon is used. The system default icon is determined by the XmDisplay resource \fIenableDragIcon\fP. .IP "\fIXmNdefaultInvalidCursorIcon\fP" Specifies the DragIcon used to indicate that the cursor is over an invalid drop site during a drag operation when no other pixmap symbol is specified by the application. If NULL, a system default icon is used. The system default icon is determined by the XmDisplay resource \fIenableDragIcon\fP. .IP "\fIXmNdefaultLinkCursorIcon\fP" Specifies the DragIcon used during a drag operation when the operation is a link and no other pixmap is specified by the application. If NULL, a system default icon is used. The system default icon is determined by the XmDisplay resource \fIenableDragIcon\fP. .IP "\fIXmNdefaultMoveCursorIcon\fP" Specifies the DragIcon used during a drag operation when the operation is a move and no other pixmap is specified by the application. If NULL, a system default icon is used. The system default icon is determined by the XmDisplay resource \fIenableDragIcon\fP. .IP "\fIXmNdefaultNoneCursorIcon\fP" Specifies the DragIcon used to indicate that the cursor is not over a drop site during a drag operation when no other pixmap is specified by the application. If NULL, a system default icon is used. The system default icon is determined by the XmDisplay resource \fIenableDragIcon\fP. .IP "\fIXmNdefaultSourceCursorIcon\fP" Specifies the depth-1 pixmap used as a cursor when an \fIXmNsourceCursorIcon\fP is not provided by the DragContext, or it is not usable. If NULL, a system default icon is used. The system default icon is determined by the XmDisplay resource \fIenableDragIcon\fP. .IP "\fIXmNdefaultValidCursorIcon\fP" Specifies the DragIcon used to indicate that the cursor is over a valid drop site during a drag operation when no other pixmap is specified by the application. If NULL, a system default icon is used. The system default icon is determined by the XmDisplay resource \fIenableDragIcon\fP. .IP "\fIXmNfont\fP" Specifies a font for use in computing values for \fIXmNhorizontalFontUnit\fP and \fIXmNverticalFontUnit\fP. When an application is initialized, this resource can be supplied in a resource file or through the standard command line options \fI\-fn\fP, \fI\-font\fP, and \fI\-xrm\fP. .IP "\fIXmNforegroundThreshold\fP" An integer between 0 and 100, inclusive, that specifies a level of perceived brightness for a color. If the perceived brightness of the background color is equal to or below this level, Motif treats the background as "dark" when computing the default foreground and highlight colors. If the perceived brightness of the background color is above this level, Motif treats the background as "light" when computing the default foreground and highlight colors. When the background is "dark", the default foreground and highlight is white; when the background is "light", the default foreground and highlight is black. If this resource is specified for a particular screen, it applies to widgets created on that screen; otherwise, it applies to widgets created on all screens. The default value is implementation specific. .IP "\fIXmNhorizontalFontUnit\fP" Specifies the horizontal component of the font units used by \fIXmConvertUnits\fP, and is used to interpret the values of geometry resources when the \fIXmNshellUnitType\fP resource of VendorShell or the \fIXmNunitType\fP resource of Gadget, Manager, or Primitive has the value \fIXm100TH_FONT_UNITS\fP. If no initial value is supplied for this resource, the default is computed from the font specified in \fIXmNfont\fP. If no initial value is supplied for this resource or for \fIXmNfont\fP, the default is 10. .IP If a call to \fIXtSetValues\fP specifies a value for \fIXmNhorizontalFontUnit\fP, this resource is set to that value. If a call to \fIXtSetValues\fP specifies a value for \fIXmNfont\fP but not for \fIXmNhorizontalFontUnit\fP, this resource is set to a value computed from the new \fIXmNfont\fP. .IP A horizontal font unit is derived from a font as follows: .TP \(bu If the font has an \fIAVERAGE_WIDTH\fP property, the horizontal font unit is the \fIAVERAGE_WIDTH\fP property divided by 10. .TP \(bu If the font has no \fIAVERAGE_WIDTH\fP property but has a \fIQUAD_WIDTH\fP property, the horizontal font unit is the \fIQUAD_WIDTH\fP property. .TP \(bu If the font has no \fIAVERAGE_WIDTH\fP or \fIQUAD_WIDTH\fP property, the horizontal font unit is the sum of the font structure's \fBmin_bounds.width\fP and \fBmax_bounds.width\fP divided by 2.3. .IP "\fIXmNlightThreshold\fP" An integer between 0 and 100, inclusive, that specifies a level of perceived brightness for a color. If the perceived brightness of the background color is above this level, Motif treats the background as "light" when computing default shadow and select colors. If this resource is specified for a particular screen, it applies to widgets created on that screen; otherwise, it applies to widgets created on all screens. The default value is implementation specific. .IP "\fIXmNmenuCursor\fP" Sets a variable that controls the cursor used whenever this application posts a menu. This resource can be specified only once at application startup time, either by placing it within a defaults file or by using the \fI\-xrm\fP command line argument. For example .iS myProg \-xrm "*menuCursor: arrow" .iE .ne 7 .IP The menu cursor can also be selected in the program through the function \fIXmSetMenuCursor\fP. The following is a list of acceptable cursor names. If the application does not specify a cursor or if an invalid name is supplied, the default cursor (an arrow pointing up and to the right) is used. .IP .sp 1 .in 0 .KS .TS center, tab (@); lb lb lb lb. X_cursor@dotbox@man@sizing arrow@double_arrow@middlebutton@spider based_arrow_down@draft_large@mouse@spraycan based_arrow_up@draft_small@pencil@star boat@draped_box@pirate@target bogosity@exchange@plus@tcross bottom_left_corner@fleur@question_arrow@top_left_arrow bottom_right_corner@gobbler@right_ptr@top_left_corner bottom_side@gumby@right_side@top_right_corner bottom_tee@hand1@right_tee@top_side box_spiral@hand2@rightbutton@top_tee center_ptr@heart@rtl_logo@trek circle@icon@sailboat@ul_angle clock@iron_cross@sb_down_arrow@umbrella coffee_mug@left_ptr@sb_h_double_arrow@ur_angle cross@left_side@sb_left_arrow@watch cross_reverse@left_tee@sb_right_arrow@xterm crosshair@leftbutton@sb_up_arrow@ diamond_cross@ll_angle@sb_v_double_arrow@ dot@lr_angle@shuttle@ .TE .KE .in .sp 1 .IP "\fIXmNmoveOpaque\fP" Specifies whether an interactive operation that moves a window, such as tearing off and dragging a tear-off menu or moving a window in MWM, displays an outline of the window or a representation of the window itself during the move. If the value is True, the operation displays a representation of the window during the move. If the value is False, the operation displays an outline of the window. .IP "\fIXmNunpostBehavior\fP" Specifies the behavior of an active menu posted in traversal mode when a subsequent menu button selection is made outside the posted menu. When the value is \fIXmUNPOST_AND_REPLAY\fP, the resource unposts the menu hierarchy and causes the server to replay the event to the window in which the pointer is located. When the value is \fIXmUNPOST\fP, the resource unposts the hierarchy without replaying the event. .IP "\fIXmNverticalFontUnit\fP" Specifies the vertical component of the font units used by \fIXmConvertUnits\fP and used to interpret the values of geometry resources when the \fIXmNshellUnitType\fP resource of VendorShell or the \fIXmNunitType\fP resource of Gadget, Manager, or Primitive has the value \fIXm100TH_FONT_UNITS\fP. If no initial value is supplied for this resource, the default is computed from the font specified in \fIXmNfont\fP. If no initial value is supplied for this resource or for \fIXmNfont\fP, the default is 10. .IP If a call to \fIXtSetValues\fP specifies a value for \fIXmNverticalFontUnit\fP, this resource is set to that value. If a call to \fIXtSetValues\fP specifies a value for \fIXmNfont\fP but not for \fIXmNverticalFontUnit\fP, this resource is set to a value computed from the new \fIXmNfont\fP. .IP A vertical font unit is derived from a font as follows: .TP \(bu If the font has a \fIPIXEL_SIZE\fP property, the vertical font unit is the \fIPIXEL_SIZE\fP property divided by 1.8. .TP \(bu If the font has no \fIPIXEL_SIZE\fP property but has \fIPOINT_SIZE\fP and \fIRESOLUTION_Y\fP properties, the vertical font unit is the product of the \fIPOINT_SIZE\fP and \fIRESOLUTION_Y\fP properties divided by 1400. .TP \(bu If the font has no \fIPIXEL_SIZE\fP, \fIPOINT_SIZE\fP, or \fIRESOLUTION_Y\fP properties, the vertical font unit is the sum of the font structure's \fBmax_bounds.ascent\fP and \fBmax_bounds.descent\fP divided by 2.2. .SS "Inherited Resources" All of the superclass resources inherited by XmScreen are designated N/A (not applicable). .SH RELATED INFORMATION .na \fICore(3X)\fP, \fIXmDisplay(3X)\fP, and \fIXmGetXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmScrollBar 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmScrollBar\fP \- The ScrollBar widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi The ScrollBar widget allows the user to view data that is too large to be displayed all at once. ScrollBars are usually located inside a ScrolledWindow and adjacent to the widget that contains the data to be viewed. When the user interacts with the ScrollBar, the data within the other widget scrolls. .PP A ScrollBar consists of two arrows placed at each end of a rectangle. The rectangle is called the scroll region. A smaller rectangle, called the slider, is placed within the scroll region. The data is scrolled by clicking either arrow, selecting on the scroll region, or dragging the slider. When an arrow is selected, the slider within the scroll region is moved in the direction of the arrow by an amount supplied by the application. If the mouse button is held down, the slider continues to move at a constant rate. .PP The ratio of the slider size to the scroll region size typically corresponds to the relationship between the size of the visible data and the total size of the data. For example, if 10 percent of the data is visible, the slider typically occupies 10 percent of the scroll region. This provides the user with a visual clue to the size of the invisible data. .SS "Classes" ScrollBar inherits behavior and resources from the \fICore\fP and \fIXmPrimitive\fP classes. .PP The class pointer is \fIxmScrollBarWidgetClass\fP. .PP The class name is \fIXmScrollBar\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmScrollBar Resource Set Name Class Type Default Access _ XmNdecrementCallback XmCCallback XtCallbackList NULL C XmNdragCallback XmCCallback XtCallbackList NULL C XmNincrement XmCIncrement int 1 CSG XmNincrementCallback XmCCallback XtCallbackList NULL C XmNinitialDelay XmCInitialDelay int 250 ms CSG XmNmaximum XmCMaximum int dynamic CSG XmNminimum XmCMinimum int 0 CSG XmNorientation XmCOrientation unsigned char XmVERTICAL CSG XmNpageDecrementCallback XmCCallback XtCallbackList NULL C XmNpageIncrement XmCPageIncrement int 10 CSG XmNpageIncrementCallback XmCCallback XtCallbackList NULL C XmNprocessingDirection XmCProcessingDirection unsigned char dynamic CSG XmNrepeatDelay XmCRepeatDelay int 50 ms CSG XmNshowArrows XmCShowArrows Boolean True CSG .wH .tH XmNsliderSize XmCSliderSize int dynamic CSG XmNtoBottomCallback XmCCallback XtCallbackList NULL C XmNtoTopCallback XmCCallback XtCallbackList NULL C XmNtroughColor XmCTroughColor Pixel dynamic CSG XmNvalue XmCValue int dynamic CSG XmNvalueChangedCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .IP "\fIXmNdecrementCallback\fP" Specifies the list of callbacks that is called when the user takes an action that moves the ScrollBar by one increment and the value decreases. The reason passed to the callback is \fIXmCR_DECREMENT\fP. .IP "\fIXmNdragCallback\fP" Specifies the list of callbacks that is called on each incremental change of position when the slider is being dragged. The reason sent by the callback is \fIXmCR_DRAG\fP. .IP "\fIXmNincrement\fP" Specifies the amount by which the value increases or decreases when the user takes an action that moves the slider by one increment. The actual change in value is the lesser of \fIXmNincrement\fP and (previous \fIXmNvalue\fP\ \- \fIXmNminimum\fP) when the slider moves to the end of the ScrollBar with the minimum value, and the lesser of\fIXmNincrement\fP and (\fIXmNmaximum\fP\- \fIXmNsliderSize\fP\ \- previous \fIXmNvalue\fP) when the slider moves to the end of the ScrollBar with the maximum value. The value of this resource must be greater than 0. .nL .ne 6 .IP "\fIXmNincrementCallback\fP" Specifies the list of callbacks that is called when the user takes an action that moves the ScrollBar by one increment and the value increases. The reason passed to the callback is \fIXmCR_INCREMENT\fP. .IP "\fIXmNinitialDelay\fP" Specifies the amount of time in milliseconds to wait before starting continuous slider movement while a button is pressed in an arrow or the scroll region. The value of this resource must be greater than 0. .IP "\fIXmNmaximum\fP" Specifies the slider's maximum value. ScrollBars contained within ScrolledWindows have a maximum equal to the size of ScrollBar (that is, the height if it is vertical, or the width if it is horizontal). \fIXmNmaximum\fP must be greater than \fIXmNminimum\fP. .IP "\fIXmNminimum\fP" Specifies the slider's minimum value. \fIXmNmaximum\fP must be greater than \fIXmNminimum\fP. .IP "\fIXmNorientation\fP" Specifies whether the ScrollBar is displayed vertically or horizontally. This resource can have values of \fIXmVERTICAL\fP and \fIXmHORIZONTAL\fP. .IP "\fIXmNpageDecrementCallback\fP" Specifies the list of callbacks that is called when the user takes an action that moves the ScrollBar by one page increment and the value decreases. The reason passed to the callback is \fIXmCR_PAGE_DECREMENT\fP. .IP "\fIXmNpageIncrement\fP" Specifies the amount by which the value increases or decreases when the user takes an action that moves the slider by one page increment. The actual change in value is the lesser of \fIXmNpageIncrement\fP and (previous \fIXmNvalue\fP\ \- \fIXmNminimum\fP) when the slider moves to the end of the ScrollBar with the minimum value, and the lesser of \fIXmNpageIncrement\fP and (\fIXmNmaximum\fP\- \fIXmNsliderSize\fP\ \- previous \fIXmNvalue\fP) when the slider moves to the end of the ScrollBar with the maximum value. The value of this resource must be greater than 0. .nL .ne 10 .IP "\fIXmNpageIncrementCallback\fP" Specifies the list of callbacks that is called when the user takes an action that moves the ScrollBar by one page increment and the value increases. The reason passed to the callback is \fIXmCR_PAGE_INCREMENT\fP. .IP "\fIXmNprocessingDirection\fP" Specifies whether the value for \fIXmNmaximum\fP should be on the right or left side of \fIXmNminimum\fP for horizontal ScrollBars or above or below \fIXmNminimum\fP for vertical ScrollBars. This resource can have values of \fIXmMAX_ON_TOP, XmMAX_ON_BOTTOM,XmMAX_ON_LEFT\fP, and \fIXmMAX_ON_RIGHT\fP. If the XmScrollBar is oriented vertically, the default value is \fIXmMAX_ON_BOTTOM\fP. If the XmScrollBar is oriented horizontally, the default value may depend on the value of the \fIXmNstringDirection\fP resource. .IP "\fIXmNrepeatDelay\fP" Specifies the amount of time in milliseconds to wait between subsequent slider movements after the \fIXmNinitialDelay\fP has been processed. The value of this resource must be greater than 0. .IP "\fIXmNshowArrows\fP" Specifies whether the arrows are displayed. .IP "\fIXmNsliderSize\fP" Specifies the length of the slider between the values of 1 and (\fIXmNmaximum\fP\ \- \fIXmNminimum\fP). The value is constrained to be within these inclusive bounds. The default value is (\fIXmNmaximum\fP\ \- \fIXmNminimum\fP) divided by 10, with a minimum of 1. .nL .ne 15 .IP "\fIXmNtoBottomCallback\fP" Specifies the list of callbacks that is called when the user takes an action that moves the slider to the end of the ScrollBar with the maximum value. The reason passed to the callback is \fIXmCR_TO_BOTTOM\fP. .ne 10 .IP "\fIXmNtoTopCallback\fP" Specifies the list of callbacks that is called when the user takes an action that moves the slider to the end of the ScrollBar with the minimum value. The reason passed to the callback is \fIXmCR_TO_TOP\fP. .IP "\fIXmNtroughColor\fP" Specifies the color of the slider trough. .IP "\fIXmNvalue\fP" Specifies the slider's position, between \fIXmNminimum\fP and (\fIXmNmaximum\fP\ \- \fIXmNsliderSize\fP). The value is constrained to be within these inclusive bounds. The initial value of this resource is the larger of 0 and \fIXmNminimum\fP. .IP "\fIXmNvalueChangedCallback\fP" Specifies the list of callbacks that is called when the slider is released after being dragged. These callbacks are also called in place of \fIXmNincrementCallback\fP, \fIXmNdecrementCallback\fP, \fIXmNpageIncrementCallback\fP, \fIXmNpageDecrementCallback\fP, \fIXmNtoTopCallback\fP, or \fIXmNtoBottomCallback\fP when one of these callback lists would normally be called but the value of the corresponding resource is NULL. The reason passed to the callback is \fIXmCR_VALUE_CHANGED\fP. .SS "Inherited Resources" ScrollBar inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPrimitive Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNhighlightThickness XmCHighlightThickness Dimension dynamic CSG .wH .tH XmNnavigationType XmCNavigationType XmNavigationType XmSTICKY_TAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean dynamic CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.1i .nf typedef struct { int \fBreason\fI; XEvent \fB* event\fI; int \fBvalue\fI; int \fBpixel\fI; } XmScrollBarCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBvalue\fP" Contains the new slider location value. .IP "\fBpixel\fP" Is used only for \fIXmNtoTopCallback\fP and \fIXmNtoBottomCallback\fP. For horizontal ScrollBars, it contains the \fBx\fP coordinate of where the mouse button selection occurred. For vertical ScrollBars, it contains the \fBy\fP coordinate. .SS "Translations" XmScrollBar includes translations from Primitive. The XmScrollBar translations are listed below. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BSelect Press: Select() BSelect Release: Release() BSelect Press Moved: Moved() .sp \n(PDu BDrag Press: Select() BDrag Release: Release() BDrag Press Moved: Moved() .sp \n(PDu MCtrl BSelect Press: TopOrBottom() MCtrl BSelect Release: Release() .sp \n(PDu KUp: IncrementUpOrLeft(0) MCtrl KUp: PageUpOrLeft(0) .sp \n(PDu KDown: IncrementDownOrRight(0) MCtrl KDown: PageDownOrRight(0) .sp \n(PDu KLeft: IncrementUpOrLeft(1) MCtrl KLeft: PageUpOrLeft(1) .sp \n(PDu KRight: IncrementDownOrRight(1) MCtrl KRight: PageDownOrRight(1) .sp \n(PDu KPageUp: PageUpOrLeft(0) KPageDown: PageDownOrRight(0) KPageLeft: PageUpOrLeft(1) KPageRight: PageDownOrRight(1) .sp \n(PDu KBeginLine: TopOrBottom() KEndLine: TopOrBottom() .sp \n(PDu KBeginData: TopOrBottom() KEndData: TopOrBottom() .sp \n(PDu KNextField: PrimitiveNextTabGroup() KPrevField: PrimitivePrevTabGroup() .sp \n(PDu KActivate: PrimitiveParentActivate() KCancel: CancelDrag() .sp \n(PDu KHelp: PrimitiveHelp() .iE .wH .fi .SS "Action Routines" The ScrollBar action routines are described below: .IP "\fICancelDrag()\fP:" If the key press occurs during scrolling, cancels the scroll and returns the slider to its previous location in the scrollbar, otherwise, and if the parent is a manager, it passes the event to the parent. .IP "\fIIncrementDownOrRight(0|1)\fP:" With an argument of 0, moves the slider down by one increment. With an argument of 1, moves the slider right by one increment. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_RIGHT\fP or \fIXmMAX_ON_BOTTOM\fP, movement toward the right or bottom calls the callbacks for \fIXmNincrementCallback\fP. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_LEFT\fP or \fIXmMAX_ON_TOP\fP, movement toward the right or bottom calls the callbacks for \fIXmNdecrementCallback\fP. The \fIXmNvalueChangedCallback\fP is called if the \fIXmNincrementCallback\fP or \fIXmNdecrementCallback\fP is NULL. .IP "\fIIncrementUpOrLeft(0|1)\fP:" With an argument of 0, moves the slider up by one increment. With an argument of 1, moves the slider left by one increment. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_RIGHT\fP or \fIXmMAX_ON_BOTTOM\fP, movement to the left or top calls the callbacks for \fIXmNdecrementCallback\fP. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_LEFT\fP or \fIXmMAX_ON_TOP\fP, movement to the left or top calls the callbacks for \fIXmNincrementCallback\fP. The \fIXmNvalueChangedCallback\fP is called if the \fIXmNincrementCallback\fP or \fIXmNdecrementCallback\fP is NULL. .IP "\fIMoved()\fP:" If the button press occurs within the slider, the subsequent motion events move the slider to the position of the pointer and call the callbacks for \fIXmNdragCallback\fP. .IP "\fIPageDownOrRight(0|1)\fP:" With an argument of 0, moves the slider down by one page increment. With an argument of 1, moves the slider right by one page increment. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_RIGHT\fP or \fIXmMAX_ON_BOTTOM\fP, movement toward the right or bottom calls the callbacks for \fIXmNpageIncrementCallback\fP. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_LEFT\fP or \fIXmMAX_ON_TOP\fP, movement toward the right or bottom calls the callbacks for \fIXmNpageDecrementCallback\fP. The \fIXmNvalueChangedCallback\fP is called if the \fIXmNpageIncrementCallback\fP or \fIXmNpageDecrementCallback\fP is NULL. .IP "\fIPageUpOrLeft(0|1)\fP:" With an argument of 0, moves the slider up by one page increment. With an argument of 1, moves the slider left by one page increment. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_RIGHT\fP or \fIXmMAX_ON_BOTTOM\fP, movement to the left or top calls the callbacks for \fIXmNpageDecrementCallback\fP. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_LEFT\fP or \fIXmMAX_ON_TOP\fP, movement to the left or top calls the callbacks for \fIXmNpageIncrementCallback\fP. The \fIXmNvalueChangedCallback\fP is called if the \fIXmNpageIncrementCallback\fP or \fIXmNpageDecrementCallback\fP is NULL. .IP "\fIPrimitiveHelp()\fP:" Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIPrimitiveNextTabGroup()\fP:" Traverses to the first item in the next tab group. If the current tab group is the last entry in the tab group list, it wraps to the beginning of the tab group list. .IP "\fIPrimitiveParentActivate()\fP:" If the parent is a manager, passes the event to the parent. .IP "\fIPrimitivePrevTabGroup()\fP:" Traverses to the first item in the previous tab group. If the beginning of the tab group list is reached, it wraps to the end of the tab group list. .nL .ne 5 .IP "\fIRelease()\fP:" If the button press occurs within the slider and the slider position is changed, the callbacks for \fIXmNvalueChangedCallback\fP are called. .IP "\fISelect()\fP:" \fI(in arrow)\fP: Moves the slider by one increment in the direction of the arrow. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_RIGHT\fP or \fIXmMAX_ON_BOTTOM\fP, movement toward the right or bottom calls the callbacks for \fIXmNincrementCallback\fP, and movement to the left or top calls the callbacks for \fIXmNdecrementCallback\fP. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_LEFT\fP or \fIXmMAX_ON_TOP\fP, movement toward the right or bottom calls the callbacks for \fIXmNdecrementCallback\fP, and movement to the left or top calls the callbacks for \fIXmNincrementCallback\fP. The \fIXmNvalueChangedCallback\fP is called if the \fIXmNincrementCallback\fP or \fIXmNdecrementCallback\fP is NULL. .P \fI(in scroll region between an arrow and the slider)\fP: Moves the slider by one page increment in the direction of the arrow. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_RIGHT\fP or \fIXmMAX_ON_BOTTOM\fP, movement toward the right or bottom calls the callbacks for \fIXmNpageIncrementCallback\fP, and movement to the left or top calls the callbacks for \fIXmNpageDecrementCallback\fP. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_LEFT\fP or \fIXmMAX_ON_TOP\fP, movement toward the right or bottom calls the callbacks for \fIXmNpageDecrementCallback\fP, and movement to the left or top calls the callbacks for \fIXmNpageIncrementCallback\fP. The \fIXmNvalueChangedCallback\fP is called if the \fIXmNpageIncrementCallback\fP or \fIXmNpageDecrementCallback\fP is NULL. .P \fI(in slider)\fP: Activates the interactive dragging of the slider. .P If the button is held down in either the arrows or the scroll region longer than the \fIXmNinitialDelay\fP resource, the slider is moved again by the same increment and the same callbacks are called. .ne 5 After the initial delay has been used, the time delay changes to the time defined by the resource \fIXmNrepeatDelay\fP. .IP "\fITopOrBottom()\fP:" \fIMCtrl BSelect Press\fP in an arrow or in the scroll region between an arrow and the slider moves the slider as far as possible in the direction of the arrow. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_RIGHT\fP or \fIXmMAX_ON_BOTTOM\fP, movement toward the right or bottom calls the callbacks for \fIXmNtoBottomCallback\fP, and movement to the left or top calls the callbacks for \fIXmNtoTopCallback\fP. If \fIXmNprocessingDirection\fP is \fIXmMAX_ON_LEFT\fP or \fIXmMAX_ON_TOP\fP, movement toward the right or bottom calls the callbacks for \fIXmNtoTopCallback\fP, and movement to the left or top calls the callbacks for \fIXmNtoBottomCallback\fP. The \fIXmNvalueChangedCallback\fP is called if the \fIXmNtoTopCallback\fP or \fIXmNtoBottomCallback\fP is NULL. Pressing \fIKBeginLine\fP or \fIKBeginData\fP moves the slider to the minimum value and invokes the \fIXmNtoTopCallback\fP. Pressing \fIKEndLine\fP or \fIKEndData\fP moves the slider to the maximum value and invokes the \fIXmNtoBottomCallback\fP. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fICore(3X)\fP, \fIXmCreateScrollBar(3X)\fP, \fIXmPrimitive(3X)\fP, \fIXmScrollBarGetValues(3X)\fP, and \fIXmScrollBarSetValues(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmScrollBarGetValues 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmScrollBarGetValues\fP \- A ScrollBar function that returns the ScrollBar's increment values .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf void \fIXmScrollBarGetValues\fI (\fBwidget, value_return, slider_size_return, increment_return, page_increment_return\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; int \fB* value_return\fI; int \fB* slider_size_return\fI; int \fB* increment_return\fI; int \fB* page_increment_return\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmScrollBarGetValues\fP returns the the ScrollBar's increment values. The scroll region is overlaid with a slider bar that is adjusted in size and position using the main ScrollBar or set slider function attributes. .nL .ne 6 .IP "\fBwidget\fP" Specifies the ScrollBar widget ID. .IP "\fBvalue_return\fP" Returns the ScrollBar's slider position between the \fIXmNminimum\fP and \fIXmNmaximum\fP resources. .IP "\fBslider_size_return\fP" Returns the size of the slider as a value between zero and the absolute value of \fIXmNmaximum\fP minus \fIXmNminimum\fP. The size of the slider varies, depending on how much of the slider scroll area it represents. .IP "\fBincrement_return\fP" Returns the amount of increment and decrement. .IP "\fBpage_increment_return\fP" Returns the amount of page increment and decrement. .PP For a complete definition of ScrollBar and its associated resources, see \fIXmScrollBar(3X)\fP. .SH RETURN VALUE Returns the ScrollBar's increment values. .SH RELATED INFORMATION .na \fIXmScrollBar(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmScrollBarSetValues 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmScrollBarSetValues\fP \- A ScrollBar function that changes ScrollBar's increment values and the slider's size and position .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf void \fIXmScrollBarSetValues\fI (\fBwidget, value, slider_size, increment, page_increment, notify\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBvalue\fI; int \fBslider_size\fI; int \fBincrement\fI; int \fBpage_increment\fI; Boolean \fBnotify\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmSetScrollBarValues\fP changes the ScrollBar's increment values and the slider's size and position. The scroll region is overlaid with a slider bar that is adjusted in size and position using the main ScrollBar or set slider function attributes. .IP "\fBwidget\fP" Specifies the ScrollBar widget ID. .IP "\fBvalue\fP" Specifies the ScrollBar's slider position between \fIXmNminimum\fP and \fIXmNmaximum\fP. The resource name associated with this argument is \fIXmNvalue\fP. .IP "\fBslider_size\fP" Specifies the size of the slider as a value between zero and the absolute value of \fIXmNmaximum\fP minus \fIXmNminimum\fP. The size of the slider varies, depending on how much of the slider scroll area it represents. This sets the \fIXmNsliderSize\fP resource associated with ScrollBar. .IP "\fBincrement\fP" Specifies the amount of button increment and decrement. If this argument is not zero, the ScrollBar widget automatically adjusts the slider when an increment or decrement action occurs. This sets the \fIXmNincrement\fP resource associated with ScrollBar. .IP "\fBpage_increment\fP" Specifies the amount of page increment and decrement. If this argument is not zero, the ScrollBar widget automatically adjusts the slider when an increment or decrement action occurs. This sets the \fIXmNpageIncrement\fP resource associated with ScrollBar. .IP "\fBnotify\fP" Specifies a Boolean value that when True, indicates a change in the ScrollBar value and also specifies that the ScrollBar widget automatically activates the \fIXmNvalueChangedCallback\fP with the recent change. If False, specifies any change that has occurred in the ScrollBar's value, but \fIXmNvalueChangedCallback\fP is not activated. .PP For a complete definition of ScrollBar and its associated resources, see \fIXmScrollBar(3X)\fP. .SH RELATED INFORMATION .na \fIXmScrollBar(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmScrollVisible 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmScrollVisible\fP \- A ScrolledWindow function that makes an invisible descendant of a ScrolledWindow work area visible .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmScrollVisible (\fBscrollw_widget, widget, left_right_margin, top_bottom_margin\fI) .ta .5i 1.75i .nf Widget \fBscrollw_widget\fI; Widget \fBwidget\fI; Dimension \fBleft_right_margin\fI; Dimension \fBtop_bottom_margin\fI; .iE .sE .SH DESCRIPTION .fi \fIXmScrollVisible\fP makes an obscured or partially obscured widget or gadget descendant of a ScrolledWindow work area visible. The function repositions the work area and sets the specified margins between the widget and the nearest viewport boundary. The widget's location relative to the viewport determines whether one or both of the margins must be adjusted. This function requires that the \fIXmNscrollingPolicy\fP of the ScrolledWindow widget be set to \fIXmAUTOMATIC\fP. .IP "\fBscrollw_widget\fP" Specifies the ID of the ScrolledWindow widget whose work area window contains an obscured descendant. .IP "\fBwidget\fP" Specifies the ID of the widget to be made visible. .IP "\fBleft_right_margin\fP" Specifies the margin to establish between the left or right edge of the widget and the associated edge of the viewport. This margin is established only if the widget must be moved horizontally to make it visible. .IP "\fBtop_bottom_margin\fP" Specifies the margin to establish between the top or bottom edge of the widget and the associated edge of the viewport. This margin is established only if the widget must be moved vertically to make it visible. .PP For a complete definition of ScrolledWindow and its associated resources, see \fIXmScrolledWindow(3X)\*. .SH RELATED INFORMATION .na \fIXmScrolledWindow(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmScrolledWindow 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmScrolledWindow\fP \- The ScrolledWindow widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi The ScrolledWindow widget combines one or two ScrollBar widgets and a viewing area to implement a visible window onto some other (usually larger) data display. The visible part of the window can be scrolled through the larger display by the use of ScrollBars. .PP To use ScrolledWindow, an application first creates a ScrolledWindow widget, any needed ScrollBar widgets, and a widget capable of displaying any desired data as the work area of ScrolledWindow. ScrolledWindow positions the work area widget and displays the ScrollBars if so requested. When the user performs some action on the ScrollBar, the application is notified through the normal ScrollBar callback interface. .PP ScrolledWindow can be configured to operate automatically so that it performs all scrolling and display actions with no need for application program involvement. It can also be configured to provide a minimal support framework in which the application is responsible for processing all user input and making all visual changes to the displayed data in response to that input. .PP When ScrolledWindow is performing automatic scrolling it creates a clipping window and automatically creates the scroll bars. Conceptually, this window becomes the viewport through which the user examines the larger underlying data area. The application simply creates the desired data, then makes that data the work area of the ScrolledWindow. When the user moves the slider to change the displayed data, the workspace is moved under the viewing area so that a new portion of the data becomes visible. .PP Sometimes it is impractical for an application to create a large data space and simply display it through a small clipping window. For example, in a text editor, creating a single data area that consisted of a large file would involve an undesirable amount of overhead. The application needs to use a ScrolledWindow (a small viewport onto some larger data), but needs to be notified when the user scrolled the viewport so it could bring in more data from storage and update the display area. For these cases the ScrolledWindow can be configured so that it provides only visual layout support. No clipping window is created, and the application must maintain the data displayed in the work area, as well as respond to user input on the ScrollBars. .PP The user can specify resources in a resource file for the automatically created widgets that contain the horizontal and vertical scrollbars of the ScrolledWindow widget. The names of these widgets are "HorScrollBar" and "VertScrollBar", and remain consistent whether created by \fIXmCreateScrolledList\fP, \fIXmCreateScrolledText\fP or \fIXmCreateScrolledWindow\fP. .SS "Classes" ScrolledWindow inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIConstraint\fP, and \fIXmManager\fP Classes. .PP The class pointer is \fIxmScrolledWindowWidgetClass\fP. .PP The class name is \fIXmScrolledWindow\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmScrolledWindow Resource Set Name Class Type Default Access _ XmNclipWindow XmCClipWindow Widget dynamic G XmNhorizontalScrollBar XmCHorizontalScrollBar Widget dynamic CSG XmNscrollBarDisplayPolicy XmCScrollBarDisplayPolicy unsigned char dynamic CSG XmNscrollBarPlacement XmCScrollBarPlacement unsigned char XmBOTTOM_RIGHT CSG XmNscrolledWindowMarginHeight XmCScrolledWindowMarginHeight Dimension 0 CSG XmNscrolledWindowMarginWidth XmCScrolledWindowMarginWidth Dimension 0 CSG XmNscrollingPolicy XmCScrollingPolicy unsigned char XmAPPLICATION_DEFINED CG XmNspacing XmCSpacing Dimension 4 CSG XmNtraverseObscuredCallback XmCCallback XtCallbackList NULL CSG XmNverticalScrollBar XmCVerticalScrollBar Widget dynamic CSG XmNvisualPolicy XmCVisualPolicy unsigned char dynamic G XmNworkWindow XmCWorkWindow Widget NULL CSG .TE .KE .in .sp 1 .IP "\fIXmNclipWindow\fP" Specifies the widget ID of the clipping area. This is automatically created by ScrolledWindow when the \fIXmNvisualPolicy\fP resource is set to \fIXmCONSTANT\fP and can only be read by the application. Any attempt to set this resource to a new value causes a warning message to be printed by the scrolled window. If the \fIXmNvisualPolicy\fP resource is set to \fIXmVARIABLE\fP, this resource is set to NULL, and no clipping window is created. .IP "\fIXmNhorizontalScrollBar\fP" Specifies the widget ID of the horizontal ScrollBar. This is automatically created by ScrolledWindow when the \fIXmNscrollingPolicy\fP is initialized to \fIXmAUTOMATIC\fP; otherwise, the default is NULL. .IP "\fIXmNscrollBarDisplayPolicy\fP" Controls the automatic placement of the ScrollBars. If it is set to \fIXmAS_NEEDED\fP and if \fIXmNscrollingPolicy\fP is set to \fIXmAUTOMATIC\fP, ScrollBars are displayed only if the workspace exceeds the clip area in one or both dimensions. A resource value of \fIXmSTATIC\fP causes the ScrolledWindow to display the ScrollBars whenever they are managed, regardless of the relationship between the clip window and the work area. This resource must be \fIXmSTATIC\fP when \fIXmNscrollingPolicy\fP is \fIXmAPPLICATION_DEFINED\fP. The default is \fIXmAS_NEEDED\fP when \fIXmNscrollingPolicy\fP is \fIXmAUTOMATIC\fP, and \fIXmSTATIC\fP otherwise. .IP "\fIXmNscrollBarPlacement\fP" Specifies the positioning of the ScrollBars in relation to the work window. The following are the values: .wH .rS .TP \(bu \fIXmTOP_LEFT\fP \- The horizontal ScrollBar is placed above the work window; the vertical ScrollBar to the left. .TP \(bu \fIXmBOTTOM_LEFT\fP \- The horizontal ScrollBar is placed below the work window; the vertical ScrollBar to the left. .TP \(bu \fIXmTOP_RIGHT\fP \- The horizontal ScrollBar is placed above the work window; the vertical ScrollBar to the right. .TP \(bu \fIXmBOTTOM_RIGHT\fP \- The horizontal ScrollBar is placed below the work window; the vertical ScrollBar to the right. .wH .rE .PP The default value may depend on the value of the \fIXmNstringDirection\fP resource. .nL .ne 5 .IP "\fIXmNscrolledWindowMarginHeight\fP" Specifies the margin height on the top and bottom of the ScrolledWindow. .IP "\fIXmNscrolledWindowMarginWidth\fP" Specifies the margin width on the right and left sides of the ScrolledWindow. .IP "\fIXmNscrollingPolicy\fP" Performs automatic scrolling of the work area with no application interaction. If the value of this resource is \fIXmAUTOMATIC\fP, ScrolledWindow automatically creates the ScrollBars; attaches callbacks to the ScrollBars; sets the visual policy to \fIXmCONSTANT\fP; and automatically moves the work area through the clip window in response to any user interaction with the ScrollBars. An application can also add its own callbacks to the ScrollBars. This allows the application to be notified of a scroll event without having to perform any layout procedures. .PP \fINOTE\fP: Since the ScrolledWindow adds callbacks to the ScrollBars, an application should not perform an \fIXtRemoveAllCallbacks\fP on any of the ScrollBar widgets. .PP When \fIXmNscrollingPolicy\fP is set to \fIXmAPPLICATION_DEFINED\fP, the application is responsible for all aspects of scrolling. The ScrollBars must be created by the application, and it is responsible for performing any visual changes in the work area in response to user input. .PP This resource must be set to the desired policy at the time the ScrolledWindow is created. It cannot be changed through \fISetValues\fP. .IP "\fIXmNspacing\fP" Specifies the distance that separates the ScrollBars from the work window. .IP "\fIXmNtraverseObscuredCallback\fP" Specifies a list of callbacks that is called when traversing to a widget or gadget that is obscured due to its position in the work area relative to the location of the ScrolledWindow viewport. This resource is valid only when \fIXmNscrollingPolicy\fP is \fIXmAUTOMATIC\fP. If this resource is NULL, an obscured widget cannot be traversed to. The callback reason is \fIXmCR_OBSCURED_TRAVERSAL\fP. .IP "\fIXmNverticalScrollBar\fP" Specifies the widget ID of the vertical ScrollBar. This is automatically created by ScrolledWindow when the \fIXmNscrollingPolicy\fP is initialized to \fIXmAUTOMATIC\fP; otherwise, the default is NULL. .nL .ne 6 .IP "\fIXmNvisualPolicy\fP" Grows the ScrolledWindow to match the size of the work area, or it can be used as a static viewport onto a larger data space. If the visual policy is \fIXmVARIABLE\fP, the ScrolledWindow forces the ScrollBar display policy to \fIXmSTATIC\fP and allow the work area to grow or shrink at any time and adjusts its layout to accommodate the new size. When the policy is \fIXmCONSTANT\fP, the work area grows or shrinks as requested, but a clipping window forces the size of the visible portion to remain constant. The only time the viewing area can grow is in response to a resize from the ScrolledWindow's parent. The default is \fIXmCONSTANT\fP when \fIXmNscrollingPolicy\fP is \fIXmAUTOMATIC\fP, and \fIXmVARIABLE\fP otherwise. .PP \fINOTE\fP: This resource must be set to the desired policy at the time the ScrolledWindow is created. It cannot be changed through \fISetValues\fP. .IP "\fIXmNworkWindow\fP" Specifies the widget ID of the viewing area. .SS "Inherited Resources" ScrolledWindow inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .ne 3i .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmManager Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget NULL CSG XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension dynamic CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" The application must use the ScrollBar callbacks to be notified of user input. .PP ScrolledWindow defines a callback structure for use with \fIXmNtraverseObscuredCallback\fP callbacks. The \fIXmNtraverseObscuredCallback\fP resource provides a mechanism for traversal to obscured widgets (or gadgets) due to their position in the work area of a ScrolledWindow. The \fIXmNtraverseObscuredCallback\fP routine has responsibility for adjusting the position of the work area such that the specified traversal destination widget is positioned within the viewport of the ScrolledWindow. A NULL \fIXmNtraverseObscuredCallback\fP resource causes obscured widgets within the ScrolledWindow to be non-traversable. .PP Traversal to an obscured widget or gadget requires these conditions to be met: the widget or gadget can be obscured only due to its position in the work area of a ScrolledWindow relative to the viewport; the viewport of the associated ScrolledWindow is fully visible, or can be made so by virtue of ancestral \fIXmNtraverseObscuredCallback\fP routines; and the \fIXmNtraverseObscuredCallback\fP resource must be non-NULL. .PP When ScrolledWindow widgets are nested, the \fIXmNtraverseObscuredCallback\fP routine for each ScrolledWindow that obscures the traversal destination is called in ascending order within the given hierarchy. .PP A pointer to the following structure is passed to callbacks for \fIXmNtraverseObscuredCallback\fP. .sS .iS .ta .25i 1.75i .nf typedef struct .ne 4 { int \fBreason\fI; XEvent *\fBevent\fI: Widget \fBtraversal_destination\fI; XmTraversalDirection \fBdirection\fI; } XmTraverseObscuredCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .IP "\fBtraversal_destination\fP" Specifies the widget or gadget to traverse to, which will be a descendant of the work window. .IP "\fBdirection\fP" Specifies the direction of traversal. See the description of the \fBdirection\fP parameter in the \fIXmProcessTraversal\fP man page for an explanation of the valid values. .SS "Translations" XmScrolledWindow includes the translations from XmManager. .SS "Additional Behavior" .ne 6i This widget has the additional behavior described below: .IP "\fIKPageUp\fP:" If \fIXmNscrollingPolicy\fP is \fIXmAUTOMATIC\fP, scrolls the window up the height of the viewport. The distance scrolled may be reduced to provide some overlap. The actual distance scrolled depends on the \fIXmNpageIncrement\fP resource of the vertical ScrollBar. .nL .ne 8 .IP "\fIKPageDown\fP:" If \fIXmNscrollingPolicy\fP is \fIXmAUTOMATIC\fP, scrolls the window down the height of the viewport. The distance scrolled may be reduced to provide some overlap. The actual distance scrolled depends on the \fIXmNpageIncrement\fP resource of the vertical ScrollBar. .IP "\fIKPageLeft\fP:" If \fIXmNscrollingPolicy\fP is \fIXmAUTOMATIC\fP, scrolls the window left the width of the viewport. The distance scrolled may be reduced to provide some overlap. The actual distance scrolled depends on the \fIXmNpageIncrement\fP resource of the horizontal ScrollBar. .IP "\fIKPageRight\fP:" If \fIXmNscrollingPolicy\fP is \fIXmAUTOMATIC\fP, scrolls the window right the width of the viewport. The distance scrolled may be reduced to provide some overlap. The actual distance scrolled depends on the \fIXmNpageIncrement\fP resource of the horizontal ScrollBar. .IP "\fIKBeginLine\fP:" If \fIXmNscrollingPolicy\fP is \fIXmAUTOMATIC\fP, scrolls the window horizontally to the edge corresponding to the horizontal ScrollBar's minimum value. .IP "\fIKEndLine\fP:" If \fIXmNscrollingPolicy\fP is \fIXmAUTOMATIC\fP, scrolls the window horizontally to the edge corresponding to the horizontal ScrollBar's maximum value. .P .ne 6i .IP "\fIKBeginData\fP:" If \fIXmNscrollingPolicy\fP is \fIXmAUTOMATIC\fP, scrolls the window vertically to the edge corresponding to the vertical ScrollBar's minimum value. .IP "\fIKEndData\fP:" If \fIXmNscrollingPolicy\fP is \fIXmAUTOMATIC\fP, scrolls the window vertically to the edge corresponding to the vertical ScrollBar's maximum value. .PP Certain applications will want to replace the page bindings with ones that are specific to the content of the scrolled area. .cS .SS "Geometry Management" ScrolledWindow makes extensive use of the \fIXtQueryGeometry\fP functionality to facilitate geometry communication between application levels. In the \fIXmAPPLICATION_DEFINED\fP scrolling policy, the WorkWindow's query procedure is called by the ScrolledWindow whenever the ScrolledWindow is going to change its size. The widget calculates the largest possible workspace area and passes this size to the WorkWindow widget's query procedure. The query procedure can then examine this new size and determine if any changes, such as managing or unmanaging a ScrollBar, are necessary. The query procedure performs whatever actions it needs and then returns to the ScrolledWindow. The ScrolledWindow then examines the ScrollBars to see which (if any) are managed, allocates a portion of the visible space for them, and resizes the WorkWindow to fit in the rest of the space. .PP When the scrolling policy is \fIXmCONSTANT\fP, the ScrolledWindow can be queried to return the optimal size for a given dimension. The optimal size is defined to be the size that just encloses the WorkWindow. By using this mechanism, an application can size the ScrolledWindow so that it needs to display a ScrollBar only for one dimension. When the ScrolledWindow's query procedure is called via \fIXtQueryGeometry\fP, the request is examined to see if the width or height has been specified. If so, the routine uses the given dimension as the basis for its calculations. It determines the minimum value for the other dimension that just encloses the WorkWindow, fills in the appropriate elements in the reply structure, and returns to the calling program. Occasionally, using the specified width or height and the other minimum dimension results in neither ScrollBar appearing. When this happens, the query procedure sets both the width and height fields, indicating that in this situation the ideal size causes a change in both dimensions. If the calling application sets both the width and height fields, the ScrolledWindow determines the minimum size for both dimensions and return those values in the reply structure. .cE .nL .ne 10 .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fIConstraint(3X)\fP, \fICore(3X)\fP, \fIXmCreateScrolledWindow(3X)\fP, \fIXmManager(3X)\fP, \fIXmProcessTraversal(3X)\fP, \fIXmScrollBar(3X)\fP, \fIXmScrollVisible(3X)\fP, and \fIXmScrolledWindowSetAreas(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmScrolledWindowSetAreas 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmScrolledWindowSetAreas\fP \- A ScrolledWindow function that adds or changes a window work region and a horizontal or vertical ScrollBar widget to the ScrolledWindow widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf void XmScrolledWindowSetAreas (\fBwidget, horizontal_scrollbar, vertical_scrollbar, work_region\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Widget \fBhorizontal_scrollbar\fI; Widget \fBvertical_scrollbar\fI; Widget \fBwork_region\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmScrolledWindowSetAreas\fP adds or changes a window work region and a horizontal or vertical ScrollBar widget to the ScrolledWindow widget for the application. Each widget is optional and may be passed as NULL. .nL .ne 10 .IP "\fBwidget\fP" Specifies the ScrolledWindow widget ID. .IP "\fBhorizontal_scrollbar\fP" Specifies the ScrollBar widget ID for the horizontal ScrollBar to be associated with the ScrolledWindow widget. Set this ID only after creating an instance of the ScrolledWindow widget. The resource name associated with this argument is \fIXmNhorizontalScrollBar\fP. .IP "\fBvertical_scrollbar\fP" Specifies the ScrollBar widget ID for the vertical ScrollBar to be associated with the ScrolledWindow widget. Set this ID only after creating an instance of the ScrolledWindow widget. The resource name associated with this argument is \fIXmNverticalScrollBar\fP. .IP "\fBwork_region\fP" Specifies the widget ID for the work window to be associated with the ScrolledWindow widget. Set this ID only after creating an instance of the ScrolledWindow widget. The attribute name associated with this argument is \fIXmNworkWindow\fP. .PP For a complete definition of ScrolledWindow and its associated resources, see \fIXmScrolledWindow(3X)\fP. .SH RELATED INFORMATION .na \fIXmScrolledWindow(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmSelectionBox 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmSelectionBox\fP \- The SelectionBox widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi SelectionBox is a general dialog widget that allows the user to select one item from a list. By default a SelectionBox includes the following: .TP \(bu A scrolling list of alternatives .TP \(bu An editable text field for the selected alternative .TP \(bu Labels for the list and text field .TP \(bu Three or four buttons .PP The default button labels are \fIOK\fP, \fICancel\fP, and \fIHelp\fP. By default an \fIApply\fP button is also created; if the parent of the SelectionBox is a DialogShell it is managed, and otherwise it is unmanaged. Additional children may be added to the SelectionBox after creation. The first child is used as a work area. The value of \fIXmNchildPlacement\fP determines if the work area is placed above or below the Text area, or above or below the List area. Additional children are laid out in the following manner: .TP \(bu Menubar \- The first menu bar child is placed at the top of the window. .TP \(bu Buttons \- All \fIXmPushButton\fP widgets or gadgets, and their subclasses are placed after the \fIOK\fP button in the order of their creation. .TP \(bu The layout of additional children which are not in the above categories is undefined. .PP The user can select an item in two ways: by scrolling through the list and selecting the desired item or by entering the item name directly into the text edit area. Selecting an item from the list causes that item name to appear in the selection text edit area. .PP The user may select a new item as many times as desired. The item is not actually selected until the user presses the \fIOK\fP PushButton. .PP The default value for the \fIXmBulletinBoard\fP resource \fIXmNcancelButton\fP is the Cancel button unless \fIXmNdialogType\fP is \fIXmDIALOG_COMMAND\fP, when the default is NULL. The default value for the \fIXmBulletinBoard\fP resource \fIXmNdefaultButton\fP is the OK button unless \fIXmNdialogType\fP is \fIXmDIALOG_COMMAND\fP, when the default is NULL. .PP For SelectionBox and its subclasses, the default value for \fIXmNinitialFocus\fP is the text edit area. .PP The user can specify resources in a resource file for the automatically created widgets and gadgets of SelectionBox. The following list identifies the names of these widgets (or gadgets) and the associated SelectionBox areas. .TP \(bu List Items Label \- "Items" .TP \(bu List Items \- "ItemsList" .TP \(bu Selection Label \- "Selection" .TP \(bu Selection Text \- "Text" .TP \(bu Selection Separator \- "Separator" .SS "Classes" SelectionBox inherits behavior and resources from \fICore\fP, \fIComposite\fP, \fIConstraint\fP, \fIXmManager\fP, and \fIXmBulletinBoard\fP Classes. .PP The class pointer is \fIxmSelectionBoxWidgetClass\fP. .PP The class name is \fIXmSelectionBox\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmSelectionBox Resource Set Name Class Type Default Access _ XmNapplyCallback XmCCallback XtCallbackList NULL C XmNapplyLabelString XmCApplyLabelString XmString dynamic CSG XmNcancelCallback XmCCallback XtCallbackList NULL C XmNcancelLabelString XmCCancelLabelString XmString dynamic CSG XmNchildPlacement XmCChildPlacement unsigned char XmPLACE_ABOVE_SELECTION CSG XmNdialogType XmCDialogType unsigned char dynamic CG XmNhelpLabelString XmCHelpLabelString XmString dynamic CSG XmNlistItemCount XmCItemCount int 0 CSG XmNlistItems XmCItems XmStringTable NULL CSG XmNlistLabelString XmCListLabelString XmString dynamic CSG XmNlistVisibleItemCount XmCVisibleItemCount int dynamic CSG XmNminimizeButtons XmCMinimizeButtons Boolean False CSG XmNmustMatch XmCMustMatch Boolean False CSG XmNnoMatchCallback XmCCallback XtCallbackList NULL C .wH .tH XmNokCallback XmCCallback XtCallbackList NULL C XmNokLabelString XmCOkLabelString XmString dynamic CSG XmNselectionLabelString XmCSelectionLabelString XmString dynamic CSG XmNtextAccelerators XmCTextAccelerators XtAccelerators default C XmNtextColumns XmCColumns short dynamic CSG XmNtextString XmCTextString XmString "" CSG .TE .KE .in .sp 1 .IP "\fIXmNapplyCallback\fP" Specifies the list of callbacks called when the user activates the \fIApply\fP button. The callback reason is \fIXmCR_APPLY\fP. .IP "\fIXmNapplyLabelString\fP" Specifies the string label for the \fIApply\fP button. The default for this resource depends on the locale. In the C locale the default is "Apply". .IP "\fIXmNcancelCallback\fP" Specifies the list of callbacks called when the user activates the \fICancel\fP button. The callback reason is \fIXmCR_CANCEL\fP. .IP "\fIXmNcancelLabelString\fP" Specifies the string label for the \fICancel\fP button. The default for this resource depends on the locale. In the C locale the default is "Cancel". .IP "\fIXmNchildPlacement\fP" Specifies the placement of the work area child. The possible values are: .TP \(bu \fIXmPLACE_ABOVE_SELECTION\fP \- places the work area child above the Text area .TP \(bu \fIXmPLACE_BELOW_SELECTION\fP \- places the work area child below the Text area .TP \(bu \fIXmPLACE_TOP\fP \- places the work area child above the List area, and below a menubar, if one is present .IP "\fIXmNdialogType\fP" Determines the set of SelectionBox children widgets that are created and managed at initialization. The following are possible values: .wH .rS .TP \(bu \fIXmDIALOG_PROMPT\fP \- all standard children except the list and list label are created, and all except the \fIApply\fP button are managed .TP \(bu \fIXmDIALOG_COMMAND\fP \- only the list, the selection label, and the text field are created and managed .TP \(bu \fIXmDIALOG_SELECTION\fP \- all standard children are created and managed .TP \(bu \fIXmDIALOG_FILE_SELECTION\fP \- all standard children are created and managed .TP \(bu \fIXmDIALOG_WORK_AREA\fP \- all standard children are created, and all except the \fIApply\fP button are managed .wH .rE .PP If the parent of the SelectionBox is a DialogShell, the default is \fIXmDIALOG_SELECTION\fP; otherwise, the default is \fIXmDIALOG_WORK_AREA\fP. \fIXmCreatePromptDialog\fP and \fIXmCreateSelectionDialog\fP set and append this resource to the creation \fBarglist\fP supplied by the application. This resource cannot be modified after creation. .IP "\fIXmNhelpLabelString\fP" Specifies the string label for the \fIHelp\fP button. The default for this resource depends on the locale. In the C locale the default is "Help". .IP "\fIXmNlistItems\fP" Specifies the items in the SelectionBox list. \fIXtGetValues\fP for this resource returns the list items themselves, not a copy of the list items. The application must not free the returned items. .IP "\fIXmNlistItemCount\fP" Specifies the number of items in the SelectionBox list. The value must not be negative. .IP "\fIXmNlistLabelString\fP" Specifies the string label to appear above the SelectionBox list containing the selection items. The default for this resource depends on the locale. In the C locale the default is "Items" unless \fIXmNdialogType\fP is \fIXmDIALOG_PROMPT\fP; in that case the default is NULL. .IP "\fIXmNlistVisibleItemCount\fP" Specifies the number of items displayed in the SelectionBox list. The value must be greater than 0 unless \fIXmNdialogType\fP is \fIXmDIALOG_PROMPT\fP; in that case the value is always 0. The default is dynamic based on the height of the list. .IP "\fIXmNminimizeButtons\fP" Sets the buttons to the width of the widest button and height of the tallest button if False. If True, button width and height are not modified. .IP "\fIXmNmustMatch\fP" Specifies whether the selection widget should check if the user's selection in the text edit field has an exact match in the SelectionBox list when the \fIOK\fP button is activated. If the selection does not have an exact match, and \fIXmNmustMatch\fP is True, the \fIXmNnoMatchCallback\fP callbacks are called. If the selection does have an exact match or if \fIXmNmustMatch\fP is False, \fIXmNokCallback\fP callbacks are called. .IP "\fIXmNnoMatchCallback\fP" Specifies the list of callbacks called when the user makes a selection from the text edit field that does not have an exact match with any of the items in the list box. The callback reason is \fIXmCR_NO_MATCH\fP. Callbacks in this list are called only if \fIXmNmustMatch\fP is true. .IP "\fIXmNokCallback\fP" Specifies the list of callbacks called when the user activates the \fIOK\fP button. The callback reason is \fIXmCR_OK\fP. If the selection text does not match a list item, and \fIXmNmustMatch\fP is True, the \fIXmNnoMatchCallback\fP callbacks are called instead. .IP "\fIXmNokLabelString\fP" Specifies the string label for the \fIOK\fP button. The default for this resource depends on the locale. In the C locale the default is "OK". .IP "\fIXmNselectionLabelString\fP" Specifies the string label for the selection text edit field. The default for this resource depends on the locale. In the C locale the default is "Selection". .IP "\fIXmNtextAccelerators\fP" Specifies translations added to the Text widget child of the SelectionBox. The default includes bindings for the up and down keys for auto selection of list items. This resource is ignored if \fIXmNaccelerators\fP is initialized to a nondefault value. .IP "\fIXmNtextColumns\fP" Specifies the number of columns in the Text widget. The value must be greater than 0. .IP "\fIXmNtextString\fP" Specifies the text in the text edit selection field. .SS "Inherited Resources" SelectionBox inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmBulletinBoard Resource Set Name Class Type Default Access _ XmNallowOverlap XmCAllowOverlap Boolean True CSG XmNautoUnmanage XmCAutoUnmanage Boolean True CG XmNbuttonFontList XmCButtonFontList XmFontList dynamic CSG XmNcancelButton XmCWidget Widget dynamic SG XmNdefaultButton XmCWidget Widget dynamic SG XmNdefaultPosition XmCDefaultPosition Boolean True CSG XmNdialogStyle XmCDialogStyle unsigned char dynamic CSG XmNdialogTitle XmCDialogTitle XmString NULL CSG XmNfocusCallback XmCCallback XtCallbackList NULL C XmNlabelFontList XmCLabelFontList XmFontList dynamic CSG XmNmapCallback XmCCallback XtCallbackList NULL C XmNmarginHeight XmCMarginHeight Dimension 10 CSG XmNmarginWidth XmCMarginWidth Dimension 10 CSG XmNnoResize XmCNoResize Boolean False CSG .wH .tH XmNresizePolicy XmCResizePolicy unsigned char XmRESIZE_ANY CSG XmNshadowType XmCShadowType unsigned char XmSHADOW_OUT CSG XmNtextFontList XmCTextFontList XmFontList dynamic CSG XmNtextTranslations XmCTranslations XtTranslations NULL C XmNunmapCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmManager Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNinitialFocus XmCInitialFocus Widget dynamic CSG XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension dynamic CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Composite Resource Set Name Class Type Default Access _ XmNchildren XmCReadOnly WidgetList NULL G XmNinsertPosition XmCInsertPosition XtOrderProc NULL CSG XmNnumChildren XmCReadOnly Cardinal 0 G .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic N/A XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.50i .nf typedef struct { int \fBreason\fI; XEvent \fB* event\fI; XmString \fBvalue\fI; int \fBlength\fI; } XmSelectionBoxCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback .IP "\fBvalue\fP" Indicates the \fIXmString\fP value selected by the user from the SelectionBox list or entered into the SelectionBox text field .IP "\fBlength\fP" Indicates the size in bytes of the \fIXmString\fP value .SS "Translations" .ne 3i XmSelectionBox inherits translations from XmBulletinBoard. .SS "Accelerators" The \fIXmNtextAccelerators\fP are added to the Text descendant of XmSelectionBox. The default accelerators are listed below. These accelerators may not directly correspond to a translation table. .iS .ta 1.5i .nf KUp: SelectionBoxUpOrDown(0) KDown: SelectionBoxUpOrDown(1) KBeginData: SelectionBoxUpOrDown(2) KEndData: SelectionBoxUpOrDown(3) KRestore: SelectionBoxRestore() .wH .fi .iE .SS "Action Routines" The XmSelectionBox action routines are described below: .IP "\fISelectionBoxUpOrDown(0|1|2|3)\fP:" When called with a 0 argument, selects the previous item in the list and replaces the text with that item. .P When called with a 1 argument, selects the next item in the list and replaces the text with that item. .P When called with a 2 argument, selects the first item in the list and replaces the text with that item. .P When called with a 3 argument, selects the last item in the list and replaces the text with that item. .IP "\fISelectionBoxRestore()\fP:" Replaces the text value with the list selection. If no item in the list is selected, clears the text. .P .ne 3i .SS "Additional Behavior" The SelectionBox widget has the additional behavior described below: .IP "\fIMAny\ KCancel\fP:" Calls the activate callbacks for the cancel button if it is sensitive. If no cancel button exists and the parent of the SelectionBox is a manager, passes the event to the parent. .IP "\fIKActivate\fP:" Calls the activate callbacks for the button with the keyboard focus. If no button has the keyboard focus, calls the activate callbacks for the default button if it is sensitive. In a List widget or single-line Text widget, the List or Text action associated with \fIKActivate\fP is called before the SelectionBox actions associated with \fIKActivate\fP. In a multi-line Text widget, any \fIKActivate\fP event except \fIKEnter\fP calls the Text action associated with \fIKActivate\fP, then the SelectionBox actions associated with \fIKActivate\fP. If no button has the focus, no default button exists, and the parent of the SelectionBox is a manager, passes the event to the parent. .IP "\fI\fP:" If \fIXmNmustMatch\fP is True and the text does not match an item in the file list, calls the \fIXmNnoMatchCallback\fP callbacks with reason \fIXmCR_NO_MATCH\fP. Otherwise, calls the \fIXmNokCallback\fP callbacks with reason \fIXmCR_OK\fP. .IP "\fI\fP:" Calls the \fIXmNapplyCallback\fP callbacks with reason \fIXmCR_APPLY\fP. .IP "\fI\fP:" Calls the \fIXmNcancelCallback\fP callbacks with reason \fIXmCR_CANCEL\fP. .IP "\fI\fP:" Calls the \fIXmNhelpCallback\fP callbacks with reason \fIXmCR_HELP\fP. .IP "\fI\fP:" Calls the callbacks for \fIXmNmapCallback\fP if the SelectionBox is a child of a Dialog shell. .IP "\fI\fP:" Calls the callbacks for \fIXmNunmapCallback\fP if the SelectionBox is the child of a DialogShell. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fIComposite(3X)\fP, \fIConstraint(3X)\fP, \fICore(3X)\fP, \fIXmBulletinBoard(3X)\fP, \fIXmCreateSelectionBox(3X)\fP, \fIXmCreateSelectionDialog(3X)\fP, \fIXmCreatePromptDialog(3X)\fP, \fIXmManager(3X)\fP, and \fIXmSelectionBoxGetChild(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmSelectionBoxGetChild 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmSelectionBoxGetChild\fP \- A SelectionBox function that is used to access a component .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmSelectionBoxGetChild (\fBwidget, child\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; unsigned char \fBchild\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmSelectionBoxGetChild\fP is used to access a component within a SelectionBox. The parameters given to the function are the SelectionBox widget and a value indicating which component to access. .IP "\fBwidget\fP" Specifies the SelectionBox widget ID. .IP "\fBchild\fP" Specifies a component within the SelectionBox. The following are legal values for this parameter: .wH .rS .TP \(bu \fIXmDIALOG_APPLY_BUTTON\fP .TP \(bu \fIXmDIALOG_CANCEL_BUTTON\fP .TP \(bu \fIXmDIALOG_DEFAULT_BUTTON\fP .TP \(bu \fIXmDIALOG_HELP_BUTTON\fP .TP \(bu \fIXmDIALOG_LIST\fP .TP \(bu \fIXmDIALOG_LIST_LABEL\fP .TP \(bu \fIXmDIALOG_OK_BUTTON\fP .TP \(bu \fIXmDIALOG_SELECTION_LABEL\fP .TP \(bu \fIXmDIALOG_SEPARATOR\fP .TP \(bu \fIXmDIALOG_TEXT\fP .TP \(bu \fIXmDIALOG_WORK_AREA\fP .wH .rE .PP For a complete definition of SelectionBox and its associated resources, see \fIXmSelectionBox(3X)\fP. .SH RETURN VALUE Returns the widget ID of the specified SelectionBox component. An application should not assume that the returned widget will be of any particular class. .SH RELATED INFORMATION .na \fIXmSelectionBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** .TH XmSeparator 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmSeparator\fP \- The Separator widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi Separator is a primitive widget that separates items in a display. Several different line drawing styles are provided, as well as horizontal or vertical orientation. .PP The Separator line drawing is automatically centered within the height of the widget for a horizontal orientation and centered within the width of the widget for a vertical orientation. An \fIXtSetValues\fP with a new \fIXmNseparatorType\fP resizes the widget to its minimal height (for horizontal orientation) or its minimal width (for vertical orientation) unless height or width is explicitly set in the \fIXtSetValues\fP call. .PP Separator does not draw shadows around the separator. The Primitive resource \fIXmNshadowThickness\fP is used for the Separator's thickness when \fIXmNseparatorType\fP is \fIXmSHADOW_ETCHED_IN\fP, \fIXmSHADOW_ETCHED_IN_DASH\fP, \fIXmSHADOW_ETCHED_OUT\fP, or \fIXmSHADOW_ETCHED_OUT_DASH\fP. .PP Separator does not highlight and allows no traversing. The primitive resource \fIXmNtraversalOn\fP is forced to False. .PP The \fIXmNseparatorType\fP of \fIXmNO_LINE\fP provides an escape to the application programmer who needs a different style of drawing. A pixmap the height of the widget can be created and used as the background pixmap by building an argument list using the \fIXmNbackgroundPixmap\fP argument type as defined by \fICore\fP. Whenever the widget is redrawn, its background is displayed containing the desired separator drawing. .SS "Classes" Separator inherits behavior and resources from \fICore\fP and \fIXmPrimitive\fP Classes. .PP The class pointer is \fIxmSeparatorWidgetClass\fP. .PP The class name is \fIXmSeparator\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmSeparator Resource Set Name Class Type Default Access _ XmNmargin XmCMargin Dimension 0 CSG XmNorientation XmCOrientation unsigned char XmHORIZONTAL CSG XmNseparatorType XmCSeparatorType unsigned char XmSHADOW_ETCHED_IN CSG .TE .KE .in .sp 1 .IP "\fIXmNmargin\fP" For horizontal orientation, specifies the space on the left and right sides between the border of the Separator and the line drawn. For vertical orientation, specifies the space on the top and bottom between the border of the Separator and the line drawn. .IP "\fIXmNorientation\fP" Displays Separator vertically or horizontally. This resource can have values of \fIXmVERTICAL\fP and \fIXmHORIZONTAL\fP. .IP "\fIXmNseparatorType\fP" Specifies the type of line drawing to be done in the Separator widget. .wH .rS .TP \(bu \fIXmSINGLE_LINE\fP \- single line. .TP \(bu \fIXmDOUBLE_LINE\fP \- double line. .TP \(bu \fIXmSINGLE_DASHED_LINE\fP \- single-dashed line. .TP \(bu \fIXmDOUBLE_DASHED_LINE\fP \- double-dashed line. .TP \(bu \fIXmNO_LINE\fP \- no line. .nL .ne 15 .TP \(bu \fIXmSHADOW_ETCHED_IN\fP \- a line whose shadows give the effect of a line etched into the window. The thickness of the line is equal to the value of \fIXmNshadowThickness\fP. For horizontal orientation, the top shadow is drawn in \fIXmNtopShadowColor\fP and the bottom shadow is drawn in \fIXmNbottomShadowColor\fP. For vertical orientation, the left edge is drawn in \fIXmNtopShadowColor\fP and the right edge is drawn in \fIXmNbottomShadowColor\fP. .TP \(bu \fIXmSHADOW_ETCHED_OUT\fP \- a line whose shadows give the effect of an etched line coming out of the window. The thickness of the line is equal to the value of \fIXmNshadowThickness\fP. For horizontal orientation, the top shadow is drawn in \fIXmNbottomShadowColor\fP and the bottom shadow is drawn in \fIXmNtopShadowColor\fP. For vertical orientation, the left edge is drawn in \fIXmNbottomShadowColor\fP and the right edge is drawn in \fIXmNtopShadowColor\fP. .TP \(bu \fIXmSHADOW_ETCHED_IN_DASH\fP \- identical to \fIXmSHADOW_ETCHED_IN\fP except a series of lines creates a dashed line. .TP \(bu \fIXmSHADOW_ETCHED_OUT_DASH\fP \- identical to \fIXmSHADOW_ETCHED_OUT\fP except a series of lines creates a dashed line. .wH .rE .SS "Inherited Resources" Separator inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPrimitive Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNhighlightThickness XmCHighlightThickness Dimension 0 CSG .wH .tH XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean False G XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Translations" There are no translations for XmSeparator. .SH RELATED INFORMATION .na \fICore(3X)\fP, \fIXmCreateSeparator(3X)\fP, and \fIXmPrimitive(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmSeparatorGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmSeparatorGadget\fP \- The SeparatorGadget widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi SeparatorGadget separates items in a display. Several line drawing styles are provided, as well as horizontal or vertical orientation. .PP Lines drawn within the SeparatorGadget are automatically centered within the height of the gadget for a horizontal orientation and centered within the width of the gadget for a vertical orientation. An \fIXtSetValues\fP with a new \fIXmNseparatorType\fP resizes the widget to its minimal height (for horizontal orientation) or its minimal width (for vertical orientation) unless height or width is explicitly set in the \fIXtSetValues\fP call. .PP SeparatorGadget does not draw shadows around the separator. The Gadget resource \fIXmNshadowThickness\fP is used for the SeparatorGadget's thickness when \fIXmNseparatorType\fP is \fIXmSHADOW_ETCHED_IN\fP, \fIXmSHADOW_ETCHED_IN_DASH\fP, \fIXmSHADOW_ETCHED_OUT\fP, or \fIXmSHADOW_ETCHED_OUT_DASH\fP. .PP SeparatorGadget does not highlight and allows no traversing. The Gadget resource \fIXmNtraversalOn\fP is forced to False. .SS "Classes" SeparatorGadget inherits behavior and resources from \fIObject\fP, \fIRectObj\fP, and \fIXmGadget\fP Classes. .PP The class pointer is \fIxmSeparatorGadgetClass\fP. .PP The class name is \fIXmSeparatorGadget\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmSeparatorGadget Resource Set Name Class Type Default Access _ XmNmargin XmCMargin Dimension 0 CSG XmNorientation XmCOrientation unsigned char XmHORIZONTAL CSG XmNseparatorType XmCSeparatorType unsigned char XmSHADOW_ETCHED_IN CSG .TE .KE .in .sp 1 .IP "\fIXmNmargin\fP" For horizontal orientation, specifies the space on the left and right sides between the border of SeparatorGadget and the line drawn. For vertical .ne 8 orientation, specifies the space on the top and bottom between the border of SeparatorGadget and the line drawn. .IP "\fIXmNorientation\fP" Specifies whether SeparatorGadget is displayed vertically or horizontally. This resource can have values of \fIXmVERTICAL\fP and \fIXmHORIZONTAL\fP. .IP "\fIXmNseparatorType\fP" Specifies the type of line drawing to be done in the Separator widget. .wH .rS .TP \(bu \fIXmSINGLE_LINE\fP \- single line. .TP \(bu \fIXmDOUBLE_LINE\fP \- double line. .TP \(bu \fIXmSINGLE_DASHED_LINE\fP \- single-dashed line. .TP \(bu \fIXmDOUBLE_DASHED_LINE\fP \- double-dashed line. .TP \(bu \fIXmNO_LINE\fP \- no line. .TP \(bu \fIXmSHADOW_ETCHED_IN\fP \- a line whose shadows give the effect of a line etched into the window. The thickness of the line is equal to the value of \fIXmNshadowThickness\fP. For horizontal orientation, the top shadow is drawn in \fIXmNtopShadowColor\fP and the bottom shadow is drawn in \fIXmNbottomShadowColor\fP. For vertical orientation, the left edge is drawn in \fIXmNtopShadowColor\fP and the right edge is drawn in \fIXmNbottomShadowColor\fP. .TP \(bu \fIXmSHADOW_ETCHED_OUT\fP \- a line whose shadows give the effect of an etched line coming out of the window. The thickness of the line is equal to the value of \fIXmNshadowThickness\fP. For horizontal orientation, the top shadow is drawn in \fIXmNbottomShadowColor\fP and the bottom shadow is drawn in \fIXmNtopShadowColor\fP. For vertical orientation, the left edge is drawn in \fIXmNbottomShadowColor\fP and the right edge is drawn in \fIXmNtopShadowColor\fP. .TP \(bu \fIXmSHADOW_ETCHED_IN_DASH\fP \- identical to \fIXmSHADOW_ETCHED_IN\fP except a series of lines creates a dashed line. .TP \(bu \fIXmSHADOW_ETCHED_OUT_DASH\fP \- identical to \fIXmSHADOW_ETCHED_OUT\fP except a series of lines creates a dashed line. .wH .rE .SS "Inherited Resources" SeparatorGadget inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmGadget Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic G XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic G XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightThickness XmCHighlightThickness Dimension 0 CSG XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic G XmNtraversalOn XmCTraversalOn Boolean False G XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. RectObj Resource Set Name Class Type Default Access _ XmNancestorSensitive XmCSensitive Boolean dynamic G XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNheight XmCHeight Dimension dynamic CSG XmNsensitive XmCSensitive Boolean True CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Object Resource Set Name Class Type Default Access _ XmNdestroyCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .SS "Behavior" XmSeparatorGadget has no behavior. .SH RELATED INFORMATION .na \fIObject(3X)\fP, \fIRectObject(3X)\fP, \fIXmCreateSeparatorGadget(3X)\fP, and \fIXmGadget(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmSetColorCalculation 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmSetColorCalculation\fP \- A function to set the procedure used for default color calculation .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmColorProc XmSetColorCalculation (\fBcolor_proc\fI) .ta .5i 1.5i .nf XmColorProc \fBcolor_proc\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmSetColorCalculation\fP sets the procedure to calculate default colors. This procedure is used to calculate the foreground, top shadow, bottom shadow, and select colors on the basis of a given background color. If called with an argument of NULL, it restores the default procedure used to calculate colors. .IP "\fBcolor_proc\fP" Specifies the procedure to use for color calculation. .PP Following is a description of the \fIXmColorProc\fP type used by \fIXmSetColorCalculation\fP: .PP .ne 2i .sS .iS void (*\fBcolor_proc\fI) (\fBbackground_color, foreground_color, select_color, top_shadow_color, bottom_shadow_color\fI) .ta 0.5i 1.5i .nf XColor \fB*background_color\fI; XColor \fB*foreground_color\fI; XColor \fB*select_color\fI; XColor \fB*top_shadow_color\fI; XColor \fB*bottom_shadow_color\fI; .wH .fi .iE .sE .PP Specifies the procedure used to calculate default colors. The procedure is passed a pointer to an \fIXColor\fP structure representing the background color. The \fBpixel\fP, \fBred\fP, \fBgreen\fP, and \fBblue\fP members of this structure are filled in with values that are valid for the current colormap. .PP The procedure is passed pointers to \fIXColor\fP structures representing the foreground, select, top shadow, and bottom shadow colors to be calculated. The procedure calculates and fills in the \fBred\fP, \fBgreen\fP, and \fBblue\fP members of these structures. The procedure should not allocate color cells for any of these colors. .IP "\fBbackground_color\fP" Specifies the background color. .IP "\fBforeground_color\fP" Specifies the foreground color to be calculated. .IP "\fBselect_color\fP" Specifies the select color to be calculated. .IP "\fBtop_shadow_color\fP" Specifies the top shadow color to be calculated. .IP "\fBbottom_shadow_color\fP" Specifies the bottom shadow color to be calculated. .SH RETURN VALUE Returns the color calculation procedure that was used at the time this routine was called. .SH RELATED INFORMATION .na \fIXmChangeColor(3X)\fP, \fIXmGetColors(3X)\fP, and \fIXmGetColorCalculation(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmSetFontUnit 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmSetFontUnit\fP \- A function that sets the font unit value for a display .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmSetFontUnit (\fBdisplay, font_unit_value\fI) .ta .5i 1.5i .nf Display \fB* display\fI; int \fBfont_unit_value\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmSetFontUnit\fP provides an external function to initialize font unit values. Applications may want to specify resolution-independent data based on a global font size. See the \fIXmNunitType\fP resource description in the manual pages for \fIXmGadget\fP, \fIXmManager\fP, and \fIXmPrimitive\fP for more information on resolution independence. .PP This function sets the font units for all screens on the display. \fIXmSetFontUnit\fP is obsolete and exists for compatibility with previous releases. Instead of using this function, provide initial values or call \fIXtSetValues\fP for the XmScreen resources \fIXmNhorizontalFontUnit\fP and \fIXmNverticalFontUnit\fP. .nL .ne 12 .IP "\fBdisplay\fP" Defines the display for which this font unit value is to be applied. .IP "\fBfont_unit_value\fP" Specifies the value to be used for both horizontal and vertical font units in the conversion calculations. .SH RELATED INFORMATION .na \fIXmConvertUnits(3X)\fP, \fIXmSetFontUnits(3X)\fP, \fIXmGadget(3X)\fP, \fIXmManager(3X)\fP, \fIXmPrimitive(3X)\fP, and \fIXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmSetFontUnits 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmSetFontUnits\fP \- A function that sets the font unit value for a display .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmSetFontUnits (\fBdisplay, h_value, v_value\fI) .ta .5i 1.5i .nf Display \fB* display\fI; int \fBh_value\fI; int \fBv_value\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmSetFontUnits\fP provides an external function to initialize font unit values. Applications may want to specify resolution-independent data based on a global font size. This function must be called before any widgets with resolution-independent data are created. See the \fIXmNunitType\fP resource description in the manual pages for \fIXmGadget\fP, \fIXmManager\fP, and \fIXmPrimitive\fP for more information on resolution independence. .PP This function sets the font units for all screens on the display. \fIXmSetFontUnits\fP is obsolete and exists for compatibility with previous releases. Instead of using this function, provide initial values or call \fIXtSetValues\fP for the XmScreen resources \fIXmNhorizontalFontUnit\fP and \fIXmNverticalFontUnit\fP. .nL .ne 12 .IP "\fBdisplay\fP" Defines the display for which this font unit value is to be applied. .IP "\fBh_value\fP" Specifies the value to be used for horizontal units in the conversion calculations. .IP "\fBh_value\fP" Specifies the value to be used for vertical units in the conversion calculations. .SH RELATED INFORMATION .na \fIXmConvertUnits(3X)\fP, \fIXmSetFontUnit(3X)\fP, \fIXmGadget(3X)\fP, \fIXmManager(3X)\fP, \fIXmPrimitive(3X)\fP, and \fIXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmSetMenuCursor 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmSetMenuCursor\fP \- A function that modifies the menu cursor for a client .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmSetMenuCursor (\fBdisplay, cursorId\fI) .ta .5i 1.5i .nf Display \fB* display\fI; Cursor \fBcursorId\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmSetMenuCursor\fP programmatically modifies the menu cursor for a client; after the cursor has been created by the client, this function registers the cursor with the menu system. After calling this function, the specified cursor is displayed whenever this client displays a Motif menu on the indicated display. The client can then specify different cursors on different displays. .PP This function sets the menu cursor for all screens on the display. \fIXmSetMenuCursor\fP is obsolete and exists for compatibility with previous releases. Instead of using this function, provide initial values or call \fIXtSetValues\fP for the XmScreen resource \fIXmNmenuCursor\fP. .IP "\fBdisplay\fP" Specifies the display to which the cursor is to be associated .IP "\fBcursorId\fP" Specifies the \fIX\fP cursor ID .SH RELATED INFORMATION .na \fIXmScreen(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmSetProtocolHooks 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmSetProtocolHooks\fP \- A VendorShell function that allows pre and post actions to be executed when a protocol message is received from MWM .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu .ta 1i .nf void XmSetProtocolHooks (\fBshell, property, protocol, prehook, pre_closure, posthook, post_closure\fI) .ta .5i 2i .nf Widget \fBshell\fI; Atom \fBproperty\fI; Atom \fBprotocol\fI; XtCallbackProc \fBprehook\fI; XtPointer \fBpre_closure\fI; XtCallbackProc \fBposthook\fI; XtPointer \fBpost_closure\fI; .sp \n(PDu .ta 1i .nf void XmSetWMProtocolHooks (\fBshell, protocol, prehook, pre_closure, posthook, post_closure\fI) .ta .5i 2i .nf Widget \fBshell\fI; Atom \fBprotocol\fI; XtCallbackProc \fBprehook\fI; XtPointer \fBpre_closure\fI; XtCallbackProc \fBposthook\fI; XtPointer \fBpost_closure\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmSetProtocolHooks\fP is used by shells that want to have pre and post actions executed when a protocol message is received from MWM. Since there is no guaranteed ordering in execution of event handlers or callback lists, this allows the shell to control the flow while leaving the protocol manager structures opaque. .PP \fIXmSetWMProtocolHooks\fP is a convenience interface. It calls \fIXmSetProtocolHooks\fP with the property value set to the atom returned by interning \fIWM_PROTOCOLS\fP. .IP "\fBshell\fP" Specifies the widget with which the protocol property is associated .IP "\fBproperty\fP" Specifies the protocol property .IP "\fBprotocol\fP" Specifies the protocol atom (or an int cast to Atom) .IP "\fBprehook\fP" Specifies the procedure to call before calling entries on the client callback-list .IP "\fBpre_closure\fP" Specifies the client data to be passed to the prehook when it is invoked .IP "\fBposthook\fP" Specifies the procedure to call after calling entries on the client callback-list .IP "\fBpost_closure\fP" Specifies the client data to be passed to the posthook when it is invoked .PP For a complete definition of VendorShell and its associated resources, see \fIVendorShell(3X)\fP. .SH RELATED INFORMATION .na \fIVendorShell(3X)\fP, \fIXmInternAtom(3X)\fP, and \fIXmSetWMProtocolHooks(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmSetWMProtocolHooks 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmSetWMProtocolHooks\fP \- A VendorShell convenience interface that allows pre and post actions to be executed when a protocol message is received from the window manager .SH SYNOPSIS .nf .sS .iS \&#include \&#include .sp \n(PDu void XmSetWMProtocolHooks (\fBshell, protocol, prehook, pre_closure, posthook, post_closure\fI) .ta .5i 1.75i .nf Widget \fBshell\fI; Atom \fBprotocol\fI; XtCallbackProc \fBprehook\fI; XtPointer \fBpre_closure\fI; XtCallbackProc \fBposthook\fI; XtPointer \fBpost_closure\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmSetWMProtocolHooks\fP is a convenience interface. It calls \fIXmSetProtocolHooks\fP with the property value set to the atom returned by interning \fIWM_PROTOCOLS\fP. .IP "\fBshell\fP" Specifies the widget with which the protocol property is associated .IP "\fBprotocol\fP" Specifies the protocol atom (or an int cast to Atom) .IP "\fBprehook\fP" Specifies the procedure to call before calling entries on the client callback-list .IP "\fBpre_closure\fP" Specifies the client data to be passed to the prehook when it is invoked .IP "\fBposthook\fP" Specifies the procedure to call after calling entries on the client callback-list .IP "\fBpost_closure\fP" Specifies the client data to be passed to the posthook when it is invoked .PP For a complete definition of VendorShell and its associated resources, see \fIVendorShell(3X)\fP. .SH RELATED INFORMATION .na \fIVendorShell(3X)\fP, \fIXmInternAtom(3X)\fP, and \fIXmSetProtocolHooks(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmString 3X "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmString\fP \- Data type for a compound string .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi \fIXmString\fP is the data type for a compound string. Compound strings include one or more segments, each of which may contain a font list element tag, string direction, and text component. When a compound string is displayed, the font list element tag and the direction are used to determine how to display the text. Whenever a font list element tag is set to \fIXmFONTLIST_DEFAULT_TAG\fP the text is handled as a locale text segment. .PP Calling \fIXtGetValues\fP for a resource whose type is XmString yields a copy of the compound string resource value. The application is responsible for using \fIXmStringFree\fP to free the memory allocated for the copy. .PP Refer to the \fIXmFontList\fP man page for a description of the algorithm that associates the font list element tag of a compound string segment with a font list entry in a font list. .PP The compound string interface consists of the routines listed under "Related Information." .SH RELATED INFORMATION .na \fIXmStringBaseline(3X)\fP, \fIXmStringByteCompare(3X)\fP, \fIXmStringCompare(3X)\fP, \fIXmStringConcat(3X)\fP, \fIXmStringCopy(3X)\fP, \fIXmStringCreate(3X)\fP, \fIXmStringCreateLtoR(3X)\fP, \fIXmStringCreateLocalized(3X)\fP, \fIXmStringCreateSimple(3X)\fP, \fIXmStringDirection(3X)\fP, \fIXmStringDirectionCreate(3X)\fP, \fIXmStringDraw(3X)\fP, \fIXmStringDrawImage(3X)\fP, \fIXmStringDrawUnderline(3X)\fP, \fIXmStringEmpty(3X)\fP, \fIXmStringExtent(3X)\fP, \fIXmStringFree(3X)\fP, \fIXmStringFreeContext(3X)\fP, \fIXmStringGetLtoR(3X)\fP, \fIXmStringGetNextComponent(3X)\fP, \fIXmStringGetNextSegment(3X)\fP, \fIXmStringHasSubstring(3X)\fP, \fIXmStringHeight(3X)\fP, \fIXmStringInitContext(3X)\fP, \fIXmStringLength(3X)\fP, \fIXmStringLineCount(3X)\fP, \fIXmStringNConcat(3X)\fP, \fIXmStringNCopy(3X)\fP, \fIXmStringPeekNextComponent(3X)\fP, \fIXmStringSegmentCreate(3X)\fP, \fIXmStringSeparatorCreate(3X)\fP, \fIXmStringTable(3X)\fP, and \fIXmStringWidth(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringBaseline 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringBaseline\fP \- A compound string function that returns the number of pixels between the top of the character box and the baseline of the first line of text .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Dimension XmStringBaseline (\fBfontlist, string\fI) .ta .5i 1.5i .nf XmFontList \fBfontlist\fI; XmString \fBstring\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringBaseline\fP returns the number of pixels between the top of the character box and the baseline of the first line of text in the provided compound string. .PP .IP "\fBfontlist\fP" Specifies the font list .IP "\fBstring\fP" Specifies the string .SH RETURN VALUE Returns the number of pixels between the top of the character box and the baseline of the first line of text. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringByteCompare 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringByteCompare\fP \- A compound string function that indicates the results of a byte-by-byte comparison .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmStringByteCompare (\fBs1, s2\fI) .ta .5i 1.5i .nf XmString \fBs1\fI; XmString \fBs2\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringByteCompare\fP returns a Boolean indicating the results of a byte-by-byte comparison of two compound strings. .PP In general, if two compound strings are created with the same (char *) string using \fIXmStringCreateLocalized\fP in the same language environment, the compound strings compare as equal. If two compound strings are created with the same (char *) string and the same font list element tag set other than \fIXmFONTLIST_DEFAULT_TAG\fP using \fIXmStringCreate\fP, the strings compare as equal. .PP In some cases, once a compound string is put into a widget, that string is converted into an internal form to allow faster processing. Part of the conversion process strips out unnecessary or redundant information. If an application then does an \fIXtGetValues\fP to retrieve a compound string from a widget (specifically, Label and all of its subclasses), it is not guaranteed that the compound string returned is byte-for-byte the same as the string given to the widget originally. .IP "\fBs1\fP" Specifies a compound string to be compared with \fBs2\fP .IP "\fBs2\fP" Specifies a compound string to be compared with \fBs1\fP .SH RETURN VALUE Returns True if two compound strings are identical byte-by-byte. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP and \fIXmStringCreateLocalized(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringCompare 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringCompare\fP \- A compound string function that compares two strings .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmStringCompare (\fBs1, s2\fI) .ta .5i 1.5i .nf XmString \fBs1\fI; XmString \fBs2\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringCompare\fP returns a Boolean value indicating the results of a semantically equivalent comparison of two compound strings. .PP Semantically equivalent means that the strings have the same text components, font list element tags, directions, and separators. In general, if two compound strings are created with the same (char *) string using \fIXmStringCreateLocalized\fP in the same language environment, the compound strings compare as equal. If two compound strings are created with the same (char *) string and the same font list element tag other than \fIXmFONTLIST_DEFAULT_TAG\fP using \fIXmStringCreate\fP, the strings compare as equal. .IP "\fBs1\fP" Specifies a compound string to be compared with \fBs2\fP .IP "\fBs2\fP" Specifies a compound string to be compared with \fBs1\fP .SH RETURN VALUE Returns True if two compound strings are equivalent. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP and \fIXmStringCreateLocalized(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringConcat 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringConcat\fP \- A compound string function that appends one string to another .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmString XmStringConcat (\fBs1, s2\fI) .ta .5i 1.5i .nf XmString \fBs1\fI; XmString \fBs2\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringConcat\fP copies \fBs2\fP to the end of \fBs1\fP and returns a copy of the resulting compound string. The original strings are preserved. The space for the resulting compound string is allocated within the function. After using this function, free this space by calling \fIXmStringFree\fP. .IP "\fBs1\fP" Specifies the compound string to which a copy of \fBs2\fP is appended .IP "\fBs2\fP" Specifies the compound string that is appended to the end of \fBs1\fP .SH RETURN VALUE Returns a new compound string. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP and \fIXmStringFree(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringCopy 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringCopy\fP \- A compound string function that makes a copy of a string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmString XmStringCopy (\fBs1\fI) .ta .5i 1.5i .nf XmString \fBs1\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringCopy\fP makes a copy of a compound string. The space for the resulting compound string is allocated within the function. The application is responsible for managing the allocated space. The memory can be recovered by calling \fIXmStringFree\fP. .IP "\fBs1\fP" Specifies the compound string to be copied .SH RETURN VALUE Returns a new compound string. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP and \fIXmStringFree(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringCreate 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringCreate\fP \- A compound string function that creates a compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmString XmStringCreate (\fBtext, tag\fI) .ta .5i 1.5i .nf char *\fBtext\fI; char *\fBtag\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringCreate\fP creates a compound string with two components: text and a font list element tag. .IP "\fBtext\fP" Specifies a null-terminated string to be used as the text component of the compound string. .IP "\fBtag\fP" Specifies the font list element tag to be associated with the given text. The value \fIXmFONTLIST_DEFAULT_TAG\fP identifies a locale text segment. .SH RETURN VALUE Returns a new compound string. .SH RELATED INFORMATION .na \fIXmFontList(3X)\fP, \fIXmFontListAdd(3X)\fP, \fIXmFontListAppendEntry(3X)\fP, \fIXmFontListCopy(3X)\fP, \fIXmFontListCreate(3X)\fP, \fIXmFontListEntryCreate(3X)\fP, \fIXmFontListEntryFree(3X)\fP, \fIXmFontListEntryGetFont(3X)\fP, \fIXmFontListEntryGetTag(3X)\fP, \fIXmFontListEntryLoad(3X)\fP, \fIXmFontListFree(3X)\fP, \fIXmFontListFreeFontContext(3X)\fP, \fIXmFontListGetNextFont(3X)\fP, \fIXmFontListInitFontContext(3X)\fP, \fIXmFontListNextEntry(3X)\fP, \fIXmFontListRemoveEntry(3X)\fP, \fIXmString(3X)\fP, \fIXmStringBaseline(3X)\fP, \fIXmStringByteCompare(3X)\fP, \fIXmStringCompare(3X)\fP, \fIXmStringConcat(3X)\fP, \fIXmStringCopy(3X)\fP, \fIXmStringCreateLocalized(3X)\fP, \fIXmStringCreateLtoR(3X)\fP, \fIXmStringCreateSimple(3X)\fP, \fIXmStringDirection(3X)\fP, \fIXmStringDirectionCreate(3X)\fP, \fIXmStringDraw(3X)\fP, \fIXmStringDrawImage(3X)\fP, \fIXmStringDrawUnderline(3X)\fP, \fIXmStringEmpty(3X)\fP, \fIXmStringExtent(3X)\fP, \fIXmStringFree(3X)\fP, \fIXmStringFreeContext(3X)\fP, \fIXmStringGetLtoR(3X)\fP, \fIXmStringGetNextComponent(3X)\fP, \fIXmStringGetNextSegment(3X)\fP, \fIXmStringHasSubstring(3X)\fP, \fIXmStringHeight(3X)\fP, \fIXmStringInitContext(3X)\fP, \fIXmStringLength(3X)\fP, \fIXmStringLineCount(3X)\fP, \fIXmStringNConcat(3X)\fP, \fIXmStringNCopy(3X)\fP, \fIXmStringPeekNextComponent(3X)\fP, \fIXmStringSegmentCreate(3X)\fP, \fIXmStringSeparatorCreate(3X)\fP, \fIXmStringTable(3X)\fP, and \fIXmStringWidth(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringCreateLocalized 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringCreateLocalized\fP \- A compound string function that creates a compound string in the current locale .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmString XmStringCreateLocalized (\fBtext\fI) .ta .5i 1i .nf char *\fBtext\fI; .iE .sE .SH DESCRIPTION .fi \fIXmStringCreateLocalized\fP creates a compound string containing the specified text and assigns \fIXmFONTLIST_DEFAULT_TAG\fP as the font list entry tag. An identical compound string would result from the function \fIXmStringCreate\fP called with \fIXmFONTLIST_DEFAULT_TAG\fP explicitly as the font list entry tag. .IP "\fBtext\fP" Specifies a null-terminated string of text encoded in the current locale to be used as the text component of the compound string .SH RETURN VALUE Returns a new compound string. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringCreateLtoR 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringCreateLtoR\fP \- A compound string function that creates a compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmString XmStringCreateLtoR (\fBtext, tag\fI) .ta .5i 1.25i .nf char *\fBtext\fI; char *\fBtag\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringCreateLtoR\fP creates a compound string with two components: text and a font list element tag. This function imposes the semantic of scanning for \fI\en\fP characters in the text. When one is found, the text up to that point is put into a segment followed by a separator component. No final separator component is appended to the end of the compound string. The direction defaults to left-to-right. This function assumes that the encoding is single octet rather than double octet per character of text. .IP "\fBtext\fP" Specifies a null-terminated string to be used as the text component of the compound string. .nL .ne 6 .IP "\fBtag\fP" Specifies the font list element tag to be associated with the given text. The value \fIXmFONTLIST_DEFAULT_TAG\fP identifies a locale text segment. .SH RETURN VALUE Returns a new compound string. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringCreateSimple 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringCreateSimple\fP \- A compound string function that creates a compound string in the language environment of a widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmString XmStringCreateSimple (\fBtext\fI) .ta .5i 1.25i .nf char \fB* text\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringCreateSimple\fP creates a compound string with two components: text and a character set. It derives the character set from the current language environment. .PP The routine attempts to derive a character set from the value of the LANG environment variable. If this does not result in a valid character set, the routine uses a vendor-specific default. If the vendor has not specified a different value, this default is ISO8859-1. .PP NOTE: This routine is obsolete and exists for compatibility with previous releases. It has been replaced by \fIXmStringCreateLocalized\fP. .IP "\fBtext\fP" Specifies a null-terminated string to be used as the text component of the compound string. .SH RETURN VALUE Returns a new compound string. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP and \fIXmStringCreateLocalized(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringDirection 3X "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringDirection\fP \- Data type for the direction of display in a string .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi \fIXmStringDirection\fP is the data type for specifying the direction in which the system displays characters of a string, or characters of a segment of a compound string. This is an enumeration with two possible values: .IP "\fIXmSTRING_DIRECTION_L_TO_R\fP" Specifies left to right display .IP "\fIXmSTRING_DIRECTION_R_TO_L\fP" Specifies right to left display .SH RELATED INFORMATION .na \fIXmString(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringDirectionCreate 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringDirectionCreate\fP \- A compound string function that creates a compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmString XmStringDirectionCreate (\fBdirection\fI) .ta .5i 1.75i .nf XmStringDirection \fBdirection\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringDirectionCreate\fP creates a compound string with a single component, a direction with the given value. .IP "\fBdirection\fP" Specifies the value of the directional component .SH RETURN VALUE Returns a new compound string. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringDraw 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringDraw\fP \- A compound string function that draws a compound string in an X window .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf void XmStringDraw (\fBd, w, fontlist, string, gc, x, y, width, alignment, layout_direction, clip\fI) .ta .5i 1.5i .nf Display \fB* d\fI; Window \fBw\fI; XmFontList \fBfontlist\fI; XmString \fBstring\fI; GC \fBgc\fI; Position \fBx\fI; Position \fBy\fI; Dimension \fBwidth\fI; unsigned char \fBalignment\fI; unsigned char \fBlayout_direction\fI; XRectangle \fB* clip\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringDraw\fP draws a compound string in an X Window. If a compound string segment uses a font list entry that defines a font set, the graphic context passed to this routine will have the GC font member left in an undefined state. The underlying \fIXmbStringDraw\fP function called by this routine modifies the font id field of the GC passed into it and does not attempt to restore the font id to the incoming value. If the compound string segment is not drawn using a font set, the graphic context must contain a valid font member. Graphic contexts created by \fIXtGetGC\fP are not valid for this routine; instead, use \fIXtAllocateGC\fP to create a graphic context. .IP "\fBd\fP" Specifies the display. .IP "\fBw\fP" Specifies the window. .IP "\fBfontlist\fP" Specifies the font list. .IP "\fBstring\fP" Specifies the string. .IP "\fBgc\fP" Specifies the graphics context to use. .IP "\fBx\fP" Specifies a coordinate of the rectangle that will contain the displayed compound string. .IP "\fBy\fP" Specifies a coordinate of the rectangle that will contain the displayed compound string. .IP "\fBwidth\fP" Specifies the width of the rectangle that will contain the displayed compound string. .IP "\fBalignment\fP" Specifies how the string will be aligned within the specified rectangle. It is either \fIXmALIGNMENT_BEGINNING\fP, \fIXmALIGNMENT_CENTER\fP, or \fIXmALIGNMENT_END\fP. .IP "\fBlayout_direction\fP" Controls the direction in which the segments of the compound string will be laid out. It also determines the meaning of the \fBalignment\fP parameter. .IP "\fBclip\fP" Allows the application to restrict the area into which the compound string will be drawn. If NULL, no clipping will be done. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringDrawImage 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringDrawImage\fP \- A compound string function that draws a compound string in an X Window and creates an image .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf void XmStringDrawImage (\fBd, w, fontlist, string, gc, x, y, width, alignment, layout_direction, clip\fI) .ta .5i 1.5i .nf Display \fB* d\fI; Window \fBw\fI; XmFontList \fBfontlist\fI; XmString \fBstring\fI; GC \fBgc\fI; Position \fBx\fI; Position \fBy\fI; Dimension \fBwidth\fI; unsigned char \fBalignment\fI; unsigned char \fBlayout_direction\fI; XRectangle \fB* clip\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringDrawImage\fP draws a compound string in an X Window and paints both the foreground and background bits of each character. If a compound string segment uses a font list entry that defines a font set, the graphic context passed to this routine will have the GC font member left in an undefined state. The underlying \fIXmbStringDraw\fP function called by this routine modifies the font id field of the GC passed into it and does not attempt to restore the font id to the incoming value. If the compound string segment is not drawn using a font set, the graphic context must contain a valid font member. Graphic contexts created by \fIXtGetGC\fP are not accepted by this routine; instead, use \fIXtAllocateGC\fP to create a graphic context. .IP "\fBd\fP" Specifies the display. .IP "\fBw\fP" Specifies the window. .IP "\fBfontlist\fP" Specifies the font list. .IP "\fBstring\fP" Specifies the string. .IP "\fBgc\fP" Specifies the graphics context to use. .IP "\fBx\fP" Specifies a coordinate of the rectangle that will contain the displayed compound string. .IP "\fBy\fP" Specifies a coordinate of the rectangle that will contain the displayed compound string. .IP "\fBwidth\fP" Specifies the width of the rectangle that will contain the displayed compound string. .IP "\fBalignment\fP" Specifies how the string will be aligned within the specified rectangle. It is either \fIXmALIGNMENT_BEGINNING\fP, \fIXmALIGNMENT_CENTER\fP, or \fIXmALIGNMENT_END\fP. .IP "\fBlayout_direction\fP" Controls the direction in which the segments of the compound string will be laid out. It also determines the meaning of the \fBalignment\fP parameter. .IP "\fBclip\fP" Allows the application to restrict the area into which the compound string will be drawn. If NULL, no clipping will be done. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringDrawUnderline 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringDrawUnderline\fP \- A compound string function that underlines a string drawn in an X Window .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf void XmStringDrawUnderline (\fBd, w, fontlist, string, gc, x, y, width, alignment, layout_direction, clip, underline\fI) .ta .5i 1.5i .nf Display \fB* d\fI; Window \fBw\fI; XmFontList \fBfontlist\fI; XmString \fBstring\fI; GC \fBgc\fI; Position \fBx\fI; Position \fBy\fI; Dimension \fBwidth\fI; unsigned char \fBalignment\fI; unsigned char \fBlayout_direction\fI; XRectangle \fB* clip\fI; XmString \fBunderline\fI; .wH .fi .ne 10 .iE .sE .SH DESCRIPTION .fi \fIXmStringDrawUnderline\fP draws a compound string in an X Window. If the substring identified by \fBunderline\fP can be matched in \fBstring\fP, the substring will be underlined. Once a match has occurred, no further matches or underlining will be done. .PP If a compound string segment uses a font list entry that defines a font set, the graphic context passed to this routine will have the GC font member left in an undefined state. The underlying \fIXmbStringDraw\fP function called by this routine modifies the font id field of the GC passed into it and does not attempt to restore the font id to the incoming value. If the compound string segment is not drawn using a font set, the graphic context must contain a valid font member. Graphic contexts created by \fIXtGetGC\fP are not accepted by this routine; instead, use \fIXtAllocateGC\fP to create a graphic context. .IP "\fBd\fP" Specifies the display. .IP "\fBw\fP" Specifies the window. .IP "\fBfontlist\fP" Specifies the font list. .IP "\fBstring\fP" Specifies the string. .IP "\fBgc\fP" Specifies the graphics context to use. .IP "\fBx\fP" Specifies a coordinate of the rectangle that will contain the displayed compound string. .IP "\fBy\fP" Specifies a coordinate of the rectangle that will contain the displayed compound string. .IP "\fBwidth\fP" Specifies the width of the rectangle that will contain the displayed compound string. .IP "\fBalignment\fP" Specifies how the string will be aligned within the specified rectangle. It is one of \fIXmALIGNMENT_BEGINNING\fP, \fIXmALIGNMENT_CENTER\fP, or \fIXmALIGNMENT_END\fP. .nL .ne 20 .IP "\fBlayout_direction\fP" Controls the direction in which the segments of the compound string will be laid out. It also determines the meaning of the \fBalignment\fP parameter. .IP "\fBclip\fP" Allows the application to restrict the area into which the compound string will be drawn. If NULL, no clipping will be done. .IP "\fBunderline\fP" Specifies the substring to be underlined. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringEmpty 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringEmpty\fP \- A compound string function that provides information on the existence of non-zero length text components .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmStringEmpty (\fBs1\fI) .ta .5i 1.5i .nf XmString \fBs1\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringEmpty\fP returns a Boolean value indicating whether any non-zero length text components exist in the provided compound string. It returns True if there are no text segments in the string. If this routine is passed NULL as the string, it returns True. .IP "\fBs1\fP" Specifies the compound string .P .ne 10 .SH RETURN VALUE Returns True if there are no text segments in the string. If this routine is passed NULL as the string, it returns True. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringExtent 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringExtent\fP \- A compound string function that determines the size of the smallest rectangle that will enclose the compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmStringExtent (\fBfontlist, string, width, height\fI) .ta .5i 1.5i .nf XmFontList \fBfontlist\fI; XmString \fBstring\fI; Dimension \fB*width\fI; Dimension \fB*height\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringExtent\fP determines the width and height, in pixels, of the smallest rectangle that will enclose the provided compound string. .PP .IP "\fBfontlist\fP" Specifies the font list .IP "\fBstring\fP" Specifies the string .IP "\fBwidth\fP" Specifies a pointer to the width of the rectangle .IP "\fBheight\fP" Specifies a pointer to the height of the rectangle .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringFree 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringFree\fP \- A compound string function that recovers memory .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmStringFree (\fBstring\fI) .ta .5i 1.5i .nf XmString \fBstring\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringFree\fP recovers memory used by a compound string. .IP "\fBstring\fP" Specifies the compound string to be freed .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringFreeContext 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringFreeContext\fP \- A compound string function that instructs the toolkit that the context is no longer needed .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmStringFreeContext (\fBcontext\fI) .ta .5i 1.75i .nf XmStringContext \fBcontext\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringFreeContext\fP instructs the toolkit that the context is no longer needed and will not be used without reinitialization. .IP "\fBcontext\fP" Specifies the string context structure that was allocated by the \fIXmStringInitContext\fP function .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP and \fIXmStringInitContext(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringGetLtoR 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringGetLtoR\fP \- A compound string function that searches for a text segment in the input compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmStringGetLtoR (\fBstring, tag, text\fI) .ta .5i 1.5i .nf XmString \fBstring\fI; XmStringCharSet \fBtag\fI; char **\fBtext\fI; .wH .fi .ne 30 .iE .sE .SH DESCRIPTION .fi \fIXmStringGetLtoR\fP searches for a text segment in the input compound string that matches the given font list element tag. .IP "\fBstring\fP" Specifies the compound string. .IP "\fBtag\fP" Specifies the font list element tag associated with the text. A value of \fIXmFONTLIST_DEFAULT_TAG\fP identifies a locale text segment. .IP "\fBtext\fP" Specifies a pointer to a null terminated string. .SH RETURN VALUE Returns True if the matching text segment can be found. On return, \fBtext\fP will have a null terminated octet sequence containing the matched segment. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringGetNextComponent 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringGetNextComponent\fP \- A compound string function that returns the type and value of the next component in a compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf XmStringComponentType XmStringGetNextComponent (\fBcontext, text, tag, direction, unknown_tag, unknown_length, unknown_value\fI) .ta .5i 2.5i .nf XmStringContext \fBcontext\fI; char **\fBtext\fI; XmStringCharSet *\fBtag\fI; XmStringDirection *\fBdirection\fI; XmStringComponentType *\fBunknown_tag\fI; unsigned short *\fBunknown_length\fI; unsigned char **\fBunknown_value\fI; .wH .fi .ne 10 .iE .sE .SH DESCRIPTION .fi \fIXmStringGetNextComponent\fP returns the type and value of the next component in the compound string identified by \fBcontext\fP. It is a low-level component function. Components are returned one at a time. On return, only some output parameters will be valid; which ones can be determined by examining the return status. In the case of \fBtext\fP, \fBtag\fP, and \fBdirection\fP components, only one output parameter is valid. If the return status indicates an unknown component was encountered, the font list element tag, length, and value are returned. This function allocates the space necessary to hold returned values; freeing this space is the caller's responsibility. .IP "\fBcontext\fP" Specifies the string context structure which was allocated by the \fIXmStringInitContext\fP function. .IP "\fBtext\fP" Specifies a pointer to a null terminated string. .IP "\fBtag\fP" Specifies a pointer to the font list element tag associated with the text. The value \fIXmFONTLIST_DEFAULT_TAG\fP identifies a locale text segment. .IP "\fBdirection\fP" Specifies a pointer to the direction of the text. .IP "\fBunknown_tag\fP" Specifies a pointer to the tag of an unknown component. .IP "\fBunknown_length\fP" Specifies a pointer to the length of an unknown component. .IP "\fBunknown_value\fP" Specifies a pointer to the value of an unknown component. .P .ne 25 .SH RETURN VALUE Returns the type of component found. Following are the possible values: .wH .rS .TP \(bu \fIXmSTRING_COMPONENT_CHARSET\fP .PP This component is obsolete and remains for compatibility with previous releases. It has been replaced by \fIXmSTRING_COMPONENT_FONTLIST_ELEMENT_TAG\fP. .TP \(bu \fIXmSTRING_COMPONENT_FONTLIST_ELEMENT_TAG\fP .TP \(bu \fIXmSTRING_COMPONENT_LOCALE_TEXT\fP .TP \(bu \fIXmSTRING_COMPONENT_TAG\fP .TP \(bu \fIXmSTRING_COMPONENT_TEXT\fP .TP \(bu \fIXmSTRING_COMPONENT_DIRECTION\fP .TP \(bu \fIXmSTRING_COMPONENT_SEPARATOR\fP .TP \(bu \fIXmSTRING_COMPONENT_END\fP .TP \(bu \fIXmSTRING_COMPONENT_UNKNOWN\fP .wH .rE .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP and \fIXmStringInitContext(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringGetNextSegment 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringGetNextSegment\fP \- A compound string function that fetches the octets in the next segment of a compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf Boolean XmStringGetNextSegment (\fBcontext, text, tag, direction, separator\fI) .ta .5i 2i .nf XmStringContext \fBcontext\fI; char **\fBtext\fI; XmStringCharSet *\fBtag\fI; XmStringDirection *\fBdirection\fI; Boolean *\fBseparator\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringGetNextSegment\fP fetches the octets in the next segment; repeated calls fetch sequential segments. The \fBtext\fP, \fBtag\fP, and \fBdirection\fP of the fetched segment are returned each time. A Boolean status is returned to indicate whether a valid segment was successfully parsed. .nL .ne 7 .IP "\fBcontext\fP" Specifies the string context structure which was allocated by the \fIXmStringInitContext\fP function. .IP "\fBtext\fP" Specifies a pointer to a null terminated string. .IP "\fBtag\fP" Specifies a pointer to the font list element tag associated with the text. .IP "\fBdirection\fP" Specifies a pointer to the direction of the text. .IP "\fBseparator\fP" Specifies whether the next component of the compound string is a separator. .SH RETURN VALUE Returns True if a valid segment is found. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP and \fIXmStringInitContext(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringHasSubstring 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringHasSubstring\fP \- A compound string function that indicates whether one compound string is contained within another .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmStringHasSubstring (\fBstring, substring\fI) .ta .5i 1.5i .nf XmString \fBstring\fI; XmString \fBsubstring\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringHasSubstring\fP indicates whether or not one compound string is contained within another. .IP "\fBstring\fP" Specifies the compound string to be searched .IP "\fBsubstring\fP" Specifies the compound string to be searched for .nL .ne 10 .SH RETURN VALUE Returns True if \fBsubstring\fP has a single segment and if its text is completely contained within any single segment of \fBstring\fP; otherwise, returns False. If two compound strings created using \fIXmStringCreateLocalized\fP in the same language environment satisfy this condition, the function returns True. If two compound strings created with the same character set using \fIXmStringCreate\fP satisfy this condition, the function returns True. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP and \fIXmStringCreateLocalized(3X). .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringHeight 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringHeight\fP \- A compound string function that returns the line height of the given compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Dimension XmStringHeight (\fBfontlist, string\fI) .ta .5i 1.5i .nf XmFontList \fBfontlist\fI; XmString \fBstring\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringHeight\fP returns the height, in pixels, of the sum of all the line heights of the given compound string. Separator components delimit lines. .PP .IP "\fBfontlist\fP" Specifies the font list .IP "\fBstring\fP" Specifies the string .SH RETURN VALUE Returns the height of the specified string. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringInitContext 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringInitContext\fP \- A compound string function that allows applications to read out the content segment by segment .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmStringInitContext (\fBcontext, string\fI) .ta .5i 1.75i .nf XmStringContext \fB* context\fI; XmString \fBstring\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringInitContext\fP maintains a context to allow applications to read out the contents of a compound string segment by segment. This function establishes the context for this read out. This context is used when reading subsequent segments out of the string. A Boolean status is returned to indicate if the input string could be parsed. .IP "\fBcontext\fP" Specifies a pointer to the allocated context .IP "\fBstring\fP" Specifies the string. .SH RETURN VALUE Returns True if the context was allocated .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringLength 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringLength\fP \- A compound string function that obtains the length of a compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int XmStringLength (\fBs1\fI) .ta .5i 1.5i .nf XmString \fBs1\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringLength\fP obtains the length of a compound string. It returns the number of bytes in \fBs1\fP including all tags, direction indicators, and separators. If the compound string has an invalid structure, zero is returned. .IP "\fBs1\fP" Specifies the compound string .SH RETURN VALUE Returns the length of the compound string. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringLineCount 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringLineCount\fP \- A compound string function that returns the number of separators plus one in the provided compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int XmStringLineCount (\fBstring\fI) .ta .5i 1.5i .nf XmString \fBstring\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringLineCount\fP returns the number of separators plus one in the provided compound string. In effect, it counts the lines of text. .IP "\fBstring\fP" Specifies the string. .SH RETURN VALUE Returns the number of lines in the compound string .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringNConcat 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringNConcat\fP \- A compound string function that appends a specified number of bytes to a compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmString XmStringNConcat (\fBs1, s2, num_bytes\fI) .ta .5i 1.5i .nf XmString \fBs1\fI; XmString \fBs2\fI; int \fBnum_bytes\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringNConcat\fP appends a specified number of bytes from \fBs2\fP to the end of \fBs1\fP, including tags, directional indicators, and separators. It then returns the resulting compound string. The original strings are preserved. The space for the resulting compound string is allocated within the function. The application is responsible for managing the allocated space. The memory can be recovered by calling \fIXmStringFree\fP. .nL .ne 7 .IP "\fBs1\fP" Specifies the compound string to which a copy of \fBs2\fP is appended. .IP "\fBs2\fP" Specifies the compound string that is appended to the end of \fBs1\fP. .IP "\fBnum_bytes\fP" Specifies the number of bytes of \fBs2\fP to append to \fBs1\fP. If this value is less than the length of \fBs2\fP, as many bytes as possible, but possibly fewer than this value, will be appended to \fBs1\fP such that the resulting string is still a valid compound string. .SH RETURN VALUE Returns a new compound string. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP and \fIXmStringFree(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringNCopy 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringNCopy\fP \- A compound string function that creates a copy of a compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmString XmStringNCopy (\fBs1, num_bytes\fI) .ta .5i 1.5i .nf XmString \fBs1\fI; int \fBnum_bytes\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringNCopy\fP creates a copy of \fBs1\fP that contains a specified number of bytes, including tags, directional indicators, and separators. It then returns the resulting compound string. The original strings are preserved. The space for the resulting compound string is allocated within the function. The application is responsible for managing the allocated space. The memory can be recovered by calling \fIXmStringFree\fP. .P .nL .ne 20 .IP "\fBs1\fP" Specifies the compound string. .IP "\fBnum_bytes\fP" Specifies the number of bytes of \fBs1\fP to copy. If this value is less than the length of \fBs1\fP, as many bytes as possible, but possibly fewer than this value, will be appended to \fBs1\fP such that the resulting string is still a valid compound string. .SH RETURN VALUE Returns a new compound string. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP and \fIXmStringFree(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringPeekNextComponent 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringPeekNextComponent\fP \- A compound string function that returns the component type of the next component fetched .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmStringComponentType XmStringPeekNextComponent (\fBcontext\fI) .ta .5i 1.75i .nf XmStringContext \fBcontext\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringPeekNextComponent\fP examines the next component that would be fetched by \fIXmStringGetNextComponent\fP and returns the component type. .IP "\fBcontext\fP" Specifies the string context structure that was allocated by the \fIXmStringInitContext\fP function .SH RETURN VALUE Returns the type of component found. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP, \fIXmStringGetNextComponent(3X)\fP, and \fIXmStringInitContext(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringSegmentCreate 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringSegmentCreate\fP \- A compound string function that creates a compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmString XmStringSegmentCreate (\fBtext, tag, direction, separator\fI) .ta .5i 1.75i .nf char \fB* text\fI; char *\fBtag\fI; XmStringDirection \fBdirection\fI; Boolean \fBseparator\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringSegmentCreate\fP is a high-level function that assembles a compound string consisting of a font list element tag, a direction component, a text component, and an optional separator component. .nL .ne 10 .IP "\fBtext\fP" Specifies a null-terminated string to be used as the text component of the compound string. .IP "\fBtag\fP" Specifies the font list element tag to be associated with the text. The value \fIXmFONTLIST_DEFAULT_TAG\fP identifies a locale text segment. .IP "\fBdirection\fP" Specifies the direction of the text. .IP "\fBseparator\fP" Specifies separator addition. If False, the compound string does not have a separator at the end. If True, a separator immediately follows the text component. .SH RETURN VALUE Returns a new compound string. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringSeparatorCreate 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringSeparatorCreate\fP \- A compound string function that creates a compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmString XmStringSeparatorCreate () .iE .sE .SH DESCRIPTION .fi \fIXmStringSeparatorCreate\fP creates a compound string with a single component, a separator. .P .SH RETURN VALUE Returns a new compound string. .P .nL .ne 15 .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringTable 3X "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringTable\fP \- Data type for an array of compound strings .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi \fIXmStringTable\fP is the data type for an array of compound strings (objects of type \fIXmString\fP). .SH RELATED INFORMATION .na \fIXmString(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmStringWidth 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmStringWidth\fP \- A compound string function that returns the width of the longest sequence of text components in a compound string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Dimension XmStringWidth (\fBfontlist, string\fI) .ta .5i 1.5i .nf XmFontList \fBfontlist\fI; XmString \fBstring\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmStringWidth\fP returns the width, in pixels, of the longest sequence of text components in the provided compound string. Separator components are used to delimit sequences of text components. .PP .IP "\fBfontlist\fP" Specifies the font list .IP "\fBstring\fP" Specifies the string .SH RETURN VALUE Returns the width of the compound string. .SH RELATED INFORMATION .na \fIXmStringCreate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTargetsAreCompatible 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTargetsAreCompatible\fP \- A function that tests whether the target types match between a drop site and source object .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTargetsAreCompatible (\fBdisplay, export_targets, num_export_targets, import_targets, num_import_targets\fI) .ta .5i 1.5i .nf Display *\fBdisplay\fI; Atom *\fBexport_targets\fI; Cardinal \fBnum_export_targets\fI; Atom *\fBimport_targets\fI; Cardinal \fBnum_import_targets\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTargetsAreCompatible\fP determines whether the import targets of the destination match any of the export targets of a source. If there is at least one target in common, the function returns True. .IP "\fBdisplay\fP" Specifies the display connection. .IP "\fBexport_targets\fP" Specifies the list of target atoms associated with the source object. This resource identifies the selection targets the source can convert to. .IP "\fBnum_export_targets\fP" Specifies the number of entries in the list of export targets. .IP "\fBimport_targets\fP" Specifies the list of targets to be checked against the \fIXmNexportTargets\fP of the source associated with the specified DragContext .IP "\fBnum_import_targets\fP" Specifies the number of entries in the \fBimport_targets\fP list. .SH RETURN VALUE Returns a Boolean value that indicates whether the destination targets are compatible with the source targets. If there is at least one target in common, the routine returns True; otherwise, returns False. .SH RELATED INFORMATION .na \fIXmDragContext(3X)\fP and \fIXmDropSite(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmText 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmText\fP \- The Text widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi Text provides a single-line and multiline text editor for customizing both user and programmatic interfaces. It can be used for single-line string entry, forms entry with verification procedures, and full-window editing. It provides an application with a consistent editing system for textual data. The screen's textual data adjusts to the application writer's needs. .PP Text provides separate callback lists to verify movement of the insert cursor, modification of the text, and changes in input focus. Each of these callbacks provides the verification function with the widget instance, the event that caused the callback, and a data structure specific to the verification type. From this information the function can verify if the application considers this to be a legitimate state change and can signal the widget whether to continue with the action. .PP The user interface tailors a new set of translations. The default translations provide key bindings for insert cursor movement, deletion, insertion, and selection of text. .PP .ne 5 Text allows the user to select regions of text. Selection is based on the model specified in the \fBInter-Client Communication Conventions Manual\fP (ICCCM). Text supports primary and secondary selection. .SS "Mouse Selection" The Text widget allows text to be edited, inserted, and selected. The user can cut, copy, and paste text using the clipboard, primary transfer, or secondary transfer. Text also provides a Drag and Drop facility that enables the user to copy or move data within Text or to a different widget. When keyboard focus policy is set to EXPLICIT, the widget that receives focus is the destination widget. In POINTER mode, any keyboard or mouse operation (except secondary selection) in an editable widget establishes that widget as the destination. .PP If a destination widget becomes insensitive or uneditable, it forfeits its destination status. In EXPLICIT mode, when a widget becomes insensitive, the focus moves to another widget. If that widget is editable, it becomes the destination widget; otherwise, there is no destination widget. The text of any insensitive Text widget is stippled, indicating its state to the user. .PP The insertion cursor, displayed as an I-beam, shows where input is inserted. Input is inserted just before the insertion cursor. .PP .SS "Classes" Text inherits behavior and resources from \fICore\fP and \fIPrimitive\fP classes. .PP The class pointer is \fIxmTextWidgetClass\fP. .PP The class name is \fIXmText\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .PP .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmText Resource Set Name Class Type Default Access _ XmNactivateCallback XmCCallback XtCallbackList NULL C XmNautoShowCursorPosition XmCAutoShowCursorPosition Boolean True CSG XmNcursorPosition XmCCursorPosition XmTextPosition 0 CSG XmNeditable XmCEditable Boolean True CSG XmNeditMode XmCEditMode int XmSINGLE_LINE_EDIT CSG XmNfocusCallback XmCCallback XtCallbackList NULL C XmNgainPrimaryCallback XmCCallback XtCallbackList NULL C XmNlosePrimaryCallback XmCCallback XtCallbackList NULL C XmNlosingFocusCallback XmCCallback XtCallbackList NULL C XmNmarginHeight XmCMarginHeight Dimension 5 CSG XmNmarginWidth XmCMarginWidth Dimension 5 CSG XmNmaxLength XmCMaxLength int largest integer CSG XmNmodifyVerifyCallback XmCCallback XtCallbackList NULL C XmNmodifyVerifyCallbackWcs XmCCallback XtCallbackList NULL C XmNmotionVerifyCallback XmCCallback XtCallbackList NULL C XmNsource XmCSource XmTextSource Default source CSG XmNtopCharacter XmCTextPosition XmTextPosition 0 CSG XmNvalue XmCValue String "" CSG XmNvalueChangedCallback XmCCallback XtCallbackList NULL C XmNvalueWcs XmCvalueWcs wchar_t * (wchar_t *)"" CSG* XmNverifyBell XmCVerifyBell Boolean dynamic CSG .TE .KE .in .sp 1 .PP * This resource cannot be set in a resource file. .IP "\fIXmNactivateCallback\fP" Specifies the list of callbacks that is called when the user invokes an event that calls the \fIActivate()\fP function. The type of the structure whose address is passed to this callback is \fIXmAnyCallbackStruct\fP. The reason sent by the callback is \fIXmCR_ACTIVATE\fP. .IP "\fIXmNautoShowCursorPosition\fP" Ensures that the visible text contains the insert cursor when set to True. If the insert cursor changes, the contents of Text may scroll in order to bring the insertion point into the window. .IP "\fIXmNcursorPosition\fP" Indicates the position in the text where the current insert cursor is to be located. Position is determined by the number of characters from the beginning of the text. The first character position is 0. .nL .ne 10 .IP "\fIXmNeditable\fP" Indicates that the user can edit the text string when set to True. Prohibits the user from editing the text when set to False. .ne 12 .IP "\fIXmNeditMode\fP" Specifies the set of keyboard bindings used in Text. The default keyboard bindings (\fIXmSINGLE_LINE_EDIT\fP) provides the set of key bindings to be used in editing single-line text. The multiline bindings (\fIXmMULTI_LINE_EDIT\fP) provides the set of key bindings to be used in editing multiline text. .IP The results of placing a Text widget inside a ScrolledWindow when the Text's \fIXmNeditMode\fP is \fIXmSINGLE_LINE_EDIT\fP are undefined. .IP "\fIXmNfocusCallback\fP" Specifies the list of callbacks called when Text accepts input focus. The type of the structure whose address is passed to this callback is \fIXmAnyCallbackStruct\fP. The reason sent by the callback is \fIXmCR_FOCUS\fP. .IP "\fIXmNgainPrimaryCallback\fP" Specifies the list of callbacks called when an event causes the Text widget to gain ownership of the primary selection. The reason sent by the callback is \fIXmCR_GAIN_PRIMARY\fP. .IP "\fIXmNlosePrimaryCallback\fP" Specifies the list of callbacks called when an event causes the Text widget to lose ownership of the primary selection. The reason sent by the callback is \fIXmCR_LOSE_PRIMARY\fP. .nL .ne 7 .IP "\fIXmNlosingFocusCallback\fP" Specifies the list of callbacks called before Text loses input focus. The type of the structure whose address is passed to this callback is \fIXmTextVerifyCallbackStruct\fP. The reason sent by the callback is \fIXmCR_LOSING_FOCUS\fP. .IP "\fIXmNmarginHeight\fP" Specifies the distance between the top edge of the widget window and the text, and between the bottom edge of the widget window and the text. .nL .ne 6 .IP "\fIXmNmarginWidth\fP" Specifies the distance between the left edge of the widget window and the text, and between the right edge of the widget window and the text. .IP "\fIXmNmaxLength\fP" Specifies the maximum length of the text string that can be entered into text from the keyboard. This value must be non-negative. Strings that are entered using the \fIXmNvalue\fP resource or the \fIXmTextSetString\fP function ignore this resource. .IP "\fIXmNmodifyVerifyCallback\fP" Specifies the list of callbacks called before text is deleted from or inserted into Text. The type of the structure whose address is passed to this callback is \fIXmTextVerifyCallbackStruct\fP. The reason sent by the callback is \fIXmCR_MODIFYING_TEXT_VALUE\fP. When multiple Text widgets share the same source, only the widget that initiates the source change will generate the \fIXmNmodifyVerifyCallback\fP. .IP If both \fIXmNmodifyVerifyCallback\fP and \fIXmNmodifyVerifyCallbackWcs\fP are registered callback lists, the procedure(s) in the \fIXmNmodifyVerifyCallback\fP list are always executed first; and the resulting data, which may have been modified, is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callback routines. .IP "\fIXmNmodifyVerifyCallbackWcs\fP" Specifies the list of callbacks called before text is deleted from or inserted into Text. The type of the structure whose address is passed to this callback is \fIXmTextVerifyCallbackStructWcs\fP. The reason sent by the callback is \fIXmCR_MODIFYING_TEXT_VALUE\fP. When multiple Text widgets share the same source, only the widget that initiates the source change will generate the \fIXmNmodifyVerifyCallbackWcs\fP. .IP If both \fIXmNmodifyVerifyCallback\fP and \fIXmNmodifyVerifyCallbackWcs\fP are registered callback lists, the procedure(s) in the \fIXmNmodifyVerifyCallback\fP list are always executed first; and the resulting data, which may have been modified, is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callback routines. .IP "\fIXmNmotionVerifyCallback\fP" Specifies the list of callbacks called before the insert cursor is moved to a new position. The type of the structure whose address is passed to this callback is \fIXmTextVerifyCallbackStruct\fP. The reason sent by the callback is \fIXmCR_MOVING_INSERT_CURSOR\fP. It is possible for more than one \fIXmNmotionVerifyCallback\fPs to be generated from a single action. .IP "\fIXmNsource\fP" Specifies the source with which the widget displays text. If no source is specified, the widget creates a default string source. This resource can be used to share text sources between Text widgets. .IP "\fIXmNtopCharacter\fP" Displays the position of text at the top of the window. Position is determined by the number of characters from the beginning of the text. The first character position is 0. .IP If the \fIXmNeditMode\fP is \fIXmMULTI_LINE_EDIT\fP, the line of text that contains the top character is displayed at the top of the widget without shifting the text left or right. \fIXtGetValues\fP for \fIXmNtopCharacter\fP returns the position of the first character in the line that is displayed at the top of the widget. .IP "\fIXmNvalue\fP" Specifies the string value of the Text widget as a \fIchar*\fP data value. \fIXmNvalue\fP and \fIXmNvalueWcs\fP are both defined, the value of \fIXmNvalueWcs\fP supersedes that of \fIXmNvalue\fP. \fIXtGetValues\fP returns a copy of the value of the internal buffer and \fIXtSetValues\fP copies the string values into the internal buffer. .IP "\fIXmNvalueChangedCallback\fP" Specifies the list of callbacks called after text is deleted from or inserted into Text. The type of the structure whose address is passed to this callback is \fIXmAnyCallbackStruct\fP. The reason sent by the callback is \fIXmCR_VALUE_CHANGED\fP. When multiple Text widgets share the same source, only the widget that initiates the source change will generate the \fIXmNvalueChangedCallback\fP. This callback represents a change in the source in the Text, not in the Text widget. The \fIXmNvalueChangedCallback\fP should occur only in pairs with a \fIXmNmodifyVerifyCallback\fP, assuming that the \fBdoit\fP flag in the callback structure of the \fIXmNmodifyVerifyCallback\fP is not set to False. .IP "\fIXmNvalueWcs\fP" Specifies the string value of the Text widget as a \fIwchar_t*\fP data value. This resource cannot be specified in a resource file. .IP If \fIXmNvalue\fP and \fIXmNvalueWcs\fP are both defined, the value of \fIXmNvalueWcs\fP supersedes that of \fIXmNvalue\fP. \fIXtGetValues\fP returns a copy of the value of the internal buffer encoded as a wide character string. \fIXtSetValues\fP copies the value of the wide character string into the internal buffer. .IP "\fIXmNverifyBell\fP" Specifies whether the bell should sound when the verification returns without continuing the action. The default depends on the value of the ancestor VendorShell's \fIXmNaudibleWarning\fP resource. .IP .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmText Input Resource Set Name Class Type Default Access _ XmNpendingDelete XmCPendingDelete Boolean True CSG XmNselectionArray XmCSelectionArray XtPointer default array CSG XmNselectionArrayCount XmCSelectionArrayCount int 4 CSG XmNselectThreshold XmCSelectThreshold int 5 CSG .TE .KE .in .sp 1 .IP "\fIXmNpendingDelete\fP" Indicates that pending delete mode is on when the Boolean value is True. Pending deletion is defined as deletion of the selected text when an insertion is made. .nL .ne 25 .IP "\fIXmNselectionArray\fP" Defines the actions for multiple mouse clicks. The value of the resource is an array of \fIXmTextScanType\fP elements. \fIXmTextScanType\fP is an enumeration indicating possible actions. Each mouse click performed within half a second of the previous mouse click increments the index into this array and performs the defined action for that index. The possible actions in the order they occur in the default array are: .wH .rS .TP \(bu \fIXmSELECT_POSITION\fP \- resets the insert cursor position .TP \(bu \fIXmSELECT_WORD\fP \- selects a word .TP \(bu \fIXmSELECT_LINE\fP \- selects a line of text .TP \(bu \fIXmSELECT_ALL\fP \- selects all of the text .wH .rE .IP "\fIXmNselectionArrayCount\fP" Indicates the number of elements in the \fIXmNselectionArray\fP resource. The value must not be negative. .IP "\fIXmNselectThreshold\fP" Specifies the number of pixels of motion that is required to select the next character when selection is performed using the click-drag mode of selection. The value must not be negative. .IP .ne 5i .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmText Output Resource Set Name Class Type Default Access _ XmNblinkRate XmCBlinkRate int 500 CSG XmNcolumns XmCColumns short dynamic CSG XmNcursorPositionVisible XmCCursorPositionVisible Boolean True CSG XmNfontList XmCFontList XmFontList dynamic CSG XmNresizeHeight XmCResizeHeight Boolean False CSG XmNresizeWidth XmCResizeWidth Boolean False CSG XmNrows XmCRows short dynamic CSG XmNwordWrap XmCWordWrap Boolean False CSG .TE .KE .in .sp 1 .IP "\fIXmNblinkRate\fP" Specifies the blink rate of the text cursor in milliseconds. The time indicated in the blink rate relates to the time the cursor is visible and the time the cursor is invisible (that is, the time it takes to blink .ne 5 the insertion cursor on and off is twice the blink rate). The cursor does not blink when the blink rate is set to zero. The value must not be negative. .IP "\fIXmNcolumns\fP" Specifies the initial width of the text window as an integer number of characters. The width equals the number of characters specified by this resource multiplied by the maximum character width of the associated font. For proportionate fonts, the actual number of characters that fit on a given line may be greater than the value specified. The value must be greater than 0. The default value depends on the value of the \fIXmNwidth\fP resource. If no width is specified the default is 20. .IP "\fIXmNcursorPositionVisible\fP" Indicates that the insert cursor position is marked by a blinking text cursor when the Boolean value is True. .IP "\fIXmNfontList\fP" Specifies the font list to be used for Text. If this value is NULL at initialization, the font list is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard or VendorShell widget class. If such an ancestor is found, the font list is initialized to the \fIXmNtextFontList\fP of the ancestor widget. If no such ancestor is found, the default is implementation dependent. .IP Text searches the font list for the first occurrence of a font set that has a \fIXmFONTLIST_DEFAULT_TAG\fP. If a default element is not found, the first font set in the font list is used. If the list contains no font sets, the first font in the font list will be used. Refer to \fIXmFontList(3X)\fP for more information on a font list structure. .IP "\fIXmNresizeHeight\fP" Indicates that Text attempts to resize its height to accommodate all the text contained in the widget when the Boolean value is True. If the Boolean value is set to True, the text is always displayed starting from the first position in the source, even if instructed otherwise. This attribute is ignored when the application uses a ScrolledText widget and when \fIXmNscrollVertical\fP is True. .IP "\fIXmNresizeWidth\fP" Indicates that Text attempts to resize its width to accommodate all the text contained in the widget when the Boolean value is True. This attribute is ignored if \fIXmNwordWrap\fP is True. .IP "\fIXmNrows\fP" Specifies the initial height of the text window measured in character heights. This attribute is ignored if the text widget resource \fIXmNeditMode\fP is \fIXmSINGLE_LINE_EDIT\fP. The value must be greater than 0. The default value depends on the value of the \fIXmNheight\fP resource. If no height is specified the default is 1. .IP "\fIXmNwordWrap\fP" Indicates that lines are to be broken at word breaks (that is, the text does not go off the right edge of the window) when the Boolean value is True. Words are defined as a sequence of characters separated by white space. White space is defined as a space, tab, or newline. This attribute is ignored if the text widget resource \fIXmNeditMode\fP is \fIXmSINGLE_LINE_EDIT\fP. .IP The following resources are used only when text is created in a ScrolledWindow. See the man page for \fIXmCreateScrolledText\fP. .IP .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmText ScrolledText Resource Set Name Class Type Default Access _ XmNscrollHorizontal XmCScroll Boolean True CG XmNscrollLeftSide XmCScrollSide Boolean dynamic CG XmNscrollTopSide XmCScrollSide Boolean False CG XmNscrollVertical XmCScroll Boolean True CG .TE .KE .in .sp 1 .nL .ne 20 .IP "\fIXmNscrollHorizontal\fP" Adds a ScrollBar that allows the user to scroll horizontally through text when the Boolean value is True. This resource is forced to False when the Text widget is placed in a ScrolledWindow with \fIXmNscrollingPolicy\fP set to \fIXmAUTOMATIC\fP. .IP "\fIXmNscrollLeftSide\fP" .ne 15 Indicates that the vertical ScrollBar should be placed on the left side of the scrolled text window when the Boolean value is True. This attribute is ignored if \fIXmNscrollVertical\fP is False or the Text resource \fIXmNeditMode\fP is \fIXmSINGLE_LINE_EDIT\fP. The default value may depend on the value of the \fIXmNstringDirection\fP resource. .IP "\fIXmNscrollTopSide\fP" Indicates that the horizontal ScrollBar should be placed on the top side of the scrolled text window when the Boolean value is True. .IP "\fIXmNscrollVertical\fP" Adds a ScrollBar that allows the user to scroll vertically through text when the Boolean value is True. This attribute is ignored if the Text resource \fIXmNeditMode\fP is \fIXmSINGLE_LINE_EDIT\fP. This resource is forced to False when the Text widget is placed in a ScrolledWindow with \fIXmNscrollingPolicy\fP set to \fIXmAUTOMATIC\fP. .SS "Inherited Resources" Text inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .IP .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPrimitive Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG .wH .tH XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .PP .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .nL .ne 10 .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent \fB* event\fI; } XmAnyCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback .IP The Text widget defines a new callback structure for use with verification callbacks. Note that not all fields are relevant for every callback reason. The application must first look at the \fBreason\fP field and use only the structure members that are valid for the particular reason. The values \fBstartPos\fP, \fBendPos\fP, and \fBtext\fP in the callback structure \fIXmTextVerifyCallbackStruct\fP may be modified upon receiving the callback, and these changes will be reflected as the change made to the source of the Text widget. (For example, all keystrokes can be converted to spaces or NULL characters when a password is entered into a Text widget.) The application programmer should not overwrite the \fBtext\fP field, but should attach data to that pointer. .IP A pointer to the following structure is passed to callbacks for \fIXmNlosingFocusCallback\fP, \fIXmNmodifyVerifyCallback\fP, and \fIXmNmotionVerifyCallback\fP. .sS .iS .ta .25i 1.5i .nf typedef struct .ne 4 { int \fBreason\fI; XEvent \fB* event\fI; Boolean \fBdoit\fI; XmTextPosition \fBcurrInsert, newInsert\fI; XmTextPosition \fBstartPos, endPos\fI; XmTextBlock \fBtext\fI; } XmTextVerifyCallbackStruct, *XmTextVerifyPtr; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. It can be NULL. For example, changes made to the Text widget programmatically do not have an event that can be passed to the associated callback. .IP "\fBdoit\fP" Indicates whether the action that invoked the callback is performed. Setting \fBdoit\fP to False negates the action. .IP "\fBcurrInsert\fP" Indicates the current position of the insert cursor. .IP "\fBnewInsert\fP" Indicates the position at which the user attempts to position the insert cursor. .IP "\fBstartPos\fP" Indicates the starting position of the text to modify. If the callback is not a modify verification callback, this value is the same as \fBcurrInsert\fP. .IP "\fBendPos\fP" Indicates the ending position of the text to modify. If no text is replaced or deleted, the value is the same as \fBstartPos\fP. If the callback is not a modify verification callback, this value is the same as \fBcurrInsert\fP. .IP "\fBtext\fP" Points to a structure of type \fIXmTextBlockRec\fP. This structure holds the textual information to be inserted. .sS .iS .ta .25i 1.5i .nf typedef struct { char *\fBptr\fI; int \fBlength\fI; XmTextFormat \fBformat\fI; } XmTextBlockRec, *XmTextBlock; .iE .sE .wH .fi .IP "\fBptr\fP" .ne 15 The text to be inserted. \fBptr\fP points to a temporary storage space that is reused after the callback is finished. Therefore, if an application needs to save the text to be inserted, it should copy the text into its own data space. .IP "\fBlength\fP" Specifies the length of the text to be inserted. .IP "\fBformat\fP" Specifies the format of the text, either \fIXmFMT_8_BIT\fP or \fIXmFMT_16_BIT\fP. .IP A pointer to the following structure is passed to callbacks for \fIXmNmodifyVerifyCallbackWcs\fP. .sS .iS .ta .25i 1.5i .nf typedef struct .ne 4 { int \fBreason\fI; XEvent *\fBevent\fI; Boolean \fBdoit\fI; XmTextPosition \fBcurrInsert, newInsert\fI; XmTextPosition \fBstartPos, endPos\fI; XmTextBlockWcs \fBtext\fI; } XmTextVerifyCallbackStructWcs, *XmTextVerifyPtrWcs; .iE .sE .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. It can be NULL. For example, changes made to the Text widget programmatically do not have an event that can be passed to the associated callback. .IP "\fBdoit\fP" Indicates whether the action that invoked the callback is performed. Setting \fBdoit\fP to False negates the action. .IP "\fBcurrInsert\fP" Indicates the current position of the insert cursor. .IP "\fBnewInsert\fP" Indicates the position at which the user attempts to position the insert cursor. .IP "\fBstartPos\fP" Indicates the starting position of the text to modify. If the callback is not a modify verification callback, this value is the same as \fBcurrInsert\fP. .IP "\fBendPos\fP" Indicates the ending position of the text to modify. If no text is replaced or deleted, the value is the same as \fBstartPos\fP. If the callback is not a modify verification callback, this value is the same as \fBcurrInsert\fP. .IP "\fBtext\fP" Points to a structure of type \fIXmTextBlockRecWcs\fP. This structure holds the textual information to be inserted. .sS .iS .ta .25i 1.5i .nf typedef struct { wchar_t *\fBwcsptr\fI; int \fBlength\fI; } XmTextBlockRecWcs, *XmTextBlockWcs; .iE .sE .wH .fi .IP "\fBwcsptr\fP" .ne 15 Points to the wide character text to be inserted. .IP "\fBlength\fP" Specifies the number of characters to be inserted. .IP The following table describes the reasons why the individual verification callback structure fields are valid: .P .wH .in -.75i .sp 1 .in 0 .KS .TS center; lb lb lb li. Reason;Valid Fields .sp .2 _ .sp .2 XmCR_LOSING_FOCUS T{ reason, event, doit, currInsert, newInsert, startPos, endPos T} XmCR_MODIFYING_TEXT_VALUE T{ reason, event, doit, currInsert, newInsert, startPos, endPos, text T} XmCR_MOVING_INSERT_CURSOR T{ reason, event, doit, currInsert, newInsert T} .sp .2 .TE .KE .in .sp 1 .wH .in .SS "Translations" XmText includes translations from XmPrimitive. The XmText translations are listed below. These translations may not directly correspond to a translation table. The actions represent the effective behavior of the associated events, and they may differ in a right-to-left language environment. .iS .ta 1.5i .nf BSelect Press: grab-focus() BSelect Motion: extend-adjust() BSelect Release: extend-end() .sp \n(PDu BExtend Press: extend-start() BExtend Motion: extend-adjust() BExtend Release: extend-end() .sp \n(PDu BToggle Press: move-destination() .sp \n(PDu BDrag Press: process-bdrag() BDrag Motion: secondary-adjust() BDrag Release: copy-to() .sp \n(PDu MCtrl BDrag Press: process-bdrag() MCtrl BDrag Motion: secondary-adjust() MCtrl BDrag Release: copy-to() .sp \n(PDu MAlt BDrag Press: process-bdrag() MAlt BDrag Motion: secondary-adjust() MAlt BDrag Release: copy-to() MShift BDrag Press: process-bdrag() MShift BDrag Motion: secondary-adjust() MShift BDrag Release: move-to() MAlt MCtrl BDrag Release: copy-to() MAlt MShift BDrag Release: move-to() .sp \n(PDu KUp: process-up() MShift KUp: process-shift-up() MCtrl KUp: backward-paragraph() MShift MCtrl KUp: backward-paragraph(extend) .sp \n(PDu KDown: process-down() MShift KDown: process-shift-down() MCtrl KDown: forward-paragraph() MShift MCtrl KDown: forward-paragraph(extend) .sp \n(PDu KLeft: backward-character() MShift KLeft: key-select(left) MCtrl KLeft: backward-word() MShift MCtrl KLeft: backward-word(extend) .sp \n(PDu KRight: forward-character() MShift KRight: key-select(right) MCtrl KRight: forward-word() MShift MCtrl KRight: forward-word(extend) .sp \n(PDu KPageUp: previous-page() MShift KPageUp: previous-page(extend) .sp \n(PDu .ne 6 KPageDown: next-page() MShift KPageDown: next-page(extend) .sp \n(PDu KPageLeft: page-left() KPageRight: page-right() .sp \n(PDu KBeginLine: beginning-of-line() MShift KBeginLine: beginning-of-line(extend) .sp \n(PDu KEndLine: end-of-line() MShift KEndLine: end-of-line(extend) .sp \n(PDu KBeginData: beginning-of-file() MShift KBeginData: beginning-of-file(extend) .sp \n(PDu KEndData: end-of-file() MShift KEndData: end-of-file(extend) .sp \n(PDu KTab: process-tab() KNextField: next-tab-group() KPrevField: prev-tab-group() .sp \n(PDu KEnter: process-return() KActivate: activate() .sp \n(PDu KDelete: delete-next-character() KBackSpace: delete-previous-character() .sp \n(PDu KAddMode: toggle-add-mode() .sp \n(PDu KSpace: self-insert() MShift KSpace: self-insert() KSelect: set-anchor() KExtend: key-select() MAny KCancel: process-cancel() KClear: clear-selection() KSelectAll: select-all() KDeselectAll: deselect-all() .sp \n(PDu .ne 5 KCut: cut-clipboard() KCopy: copy-clipboard() KPaste: paste-clipboard() .sp \n(PDu KPrimaryCut: cut-primary() KPrimaryCopy: copy-primary() KPrimaryPaste: copy-primary() .sp \n(PDu KHelp: Help() .sp \n(PDu KAny: self-insert() .wH .fi .iE .PP The translations for the button events are modified when the XmDisplay's \fIenableBtn1Transfer\fP resource is True. This option allows the actions for selection and transfer to be integrated on Button1 so that the actions for extending the selection can be bound to Button2. The actions for Button1 that are defined above still apply when the Button1 press occurs over text that is not selected. The following actions apply when the Button1 press occurs over text that is selected: .PP .iS .ta 1.5i .nf BSelect Press: process-bdrag() resulting in copy .sp \n(PDu BExtend Press: process-bdrag() resulting in move BExtend Click: extend-start(), extend-end() .sp \n(PDu BToggle Press: process-bdrag() resulting in copy .sp \n(PDu BDrag Press: extend-start() BDrag Motion: extend-adjust() BDrag Release: extend-end() .wH .fi .iE .SS "Action Routines" The XmText action routines are described below: .IP "\fIactivate()\fP:" Calls the callbacks for \fIXmNactivateCallback\fP. If the parent is a manager, passes the event to the parent. .IP "\fIbackward-character()\fP:" Moves the insertion cursor one character to the left. For other effects, see the description of navigation operations in the "Keyboard Selection" section. This action may have different behavior in a right-to-left language environment. .nL .ne 25 .IP "\fIbackward-paragraph(\fBextend\fI)\fP:" If \fIXmNeditMode\fP is \fIXmMULTI_LINE_EDIT\fP and this action is called with no argument, moves the insertion cursor to the first non-whitespace character following the first previous blank line or beginning of the text. If the insertion cursor is already at the beginning of a paragraph, moves the insertion cursor to the beginning of the previous paragraph. For other effects, see the description of navigation operations in the "Keyboard Selection" section. .IP If \fIXmNeditMode\fP is \fIXmMULTI_LINE_EDIT\fP and this action is called with an argument of \fIextend\fP, moves the insertion cursor as in the case of no argument and extends the current selection. For other effects, see the description of shifted navigation operations in the "Keyboard Selection" section. .IP "\fIbackward-word(\fBextend\fI)\fP:" If this action is called with no argument, moves the insertion cursor to the first non-whitespace character after the first whitespace character to the left or after the beginning of the line. If the insertion cursor is already at the beginning of a word, moves the insertion cursor to the beginning of the previous word. For other effects, see the description of navigation operations in the "Keyboard Selection" section. This action may have different behavior in a locale other than the C locale. .IP .ne 10 If called with an argument of \fIextend\fP, moves the insertion cursor as in the case of no argument and extends the current selection. For other effects, see the description of shifted navigation operations in the "Keyboard Selection" section. .IP "\fIbeep()\fP:" Causes the terminal to beep. .IP "\fIbeginning-of-file(\fBextend\fI)\fP:" If this action is called with no argument, moves the insertion cursor to the beginning of the text. For other effects, see the description of navigation operations in the "Keyboard Selection" section. .IP If called with an argument of \fIextend\fP, moves the insertion cursor as in the case of no argument and extends the current selection. For other effects, see the description of shifted navigation operations in the "Keyboard Selection" section. .IP "\fIbeginning-of-line(\fBextend\fI)\fP:" If this action is called with no argument, moves the insertion cursor to the beginning of the line. For other effects, see the description of navigation operations in the "Keyboard Selection" section. .IP If called with an argument of \fIextend\fP, moves the insertion cursor as in the case of no argument and extends the current selection. For other effects, see the description of shifted navigation operations in the "Keyboard Selection" section. .IP "\fIclear-selection()\fP:" Clears the current selection by replacing each character except \fI\fP with a \fI\fP character. .IP "\fIcopy-clipboard()\fP:" Copies the current selection to the clipboard. .IP "\fIcopy-primary()\fP:" Copies the primary selection to just before the insertion cursor. .IP "\fIcopy-to()\fP:" If a secondary selection exists, copies the secondary selection to just before the insertion cursor. If no secondary selection exists, copies the primary selection to the pointer location. .IP "\fIcut-clipboard()\fP:" Cuts the current selection to the clipboard. .IP "\fIcut-primary()\fP:" Cuts the primary selection to just before the insertion cursor. .IP "\fIdelete-next-character()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise deletes the character following the insertion cursor. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise deletes the character following the insertion cursor. This may impact the selection. .IP "\fIdelete-next-word()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise deletes the characters following the insertion cursor to the next space, tab or end of line character. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise deletes the characters following the insertion cursor to the next space, tab or end of line character. This may impact the selection. This action may have different behavior in a locale other than the C locale. .IP "\fIdelete-previous-character()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise deletes the character of text immediately preceding the insertion cursor. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise deletes the character of text immediately preceding the insertion cursor. This may impact the selection. .IP "\fIdelete-previous-word()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise deletes the characters preceding the insertion cursor to the next space, tab or beginning of the line character. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise deletes the characters preceding the insertion cursor to the next space, tab or beginning of line character.. This may impact the selection. This action may have different behavior in a locale other than the C locale. .IP "\fIdelete-selection()\fP:" Deletes the current selection. .IP "\fIdelete-to-end-of-line()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise deletes the characters following the insertion cursor to the next end of line character. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise deletes the characters following the insertion cursor to the next end of line character. This may impact the selection. .IP "\fIdelete-to-start-of-line()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise deletes the characters preceding the insertion cursor to the previous beginning of line character. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise deletes the characters preceding the insertion cursor to the previous beginning of line character. This may impact the selection. .IP "\fIdeselect-all()\fP:" Deselects the current selection. .IP "\fIend-of-file(\fBextend\fI)\fP:" If this action is called with no argument, moves the insertion cursor to the end of the text. For other effects, see the description of navigation operations in the "Keyboard Selection" section. .IP If called with an argument of \fIextend\fP, moves the insertion cursor as in the case of no argument and extends the current selection. For other effects, see the description of shifted navigation operations in the "Keyboard Selection" section. .IP "\fIend-of-line(\fBextend\fI)\fP:" If this action is called with no argument, moves the insertion cursor to the end of the line. For other effects, see the description of navigation operations in the "Keyboard Selection" section. If called with an argument of \fIextend\fP, moves the insertion cursor as in the case of no argument and extends the current selection. For other effects, see the description of shifted navigation operations in the "Keyboard Selection" section. .IP "\fIextend-adjust()\fP:" Selects text from the anchor to the pointer position and deselects text outside that range. Moving the pointer over several lines selects text from the anchor to the end of each line the pointer moves over and up to the pointer position on the current line. .IP "\fIextend-end()\fP:" Moves the insertion cursor to the position of the pointer. .IP "\fIextend-start()\fP:" Adjusts the anchor using the balance-beam method. Selects text from the anchor to the pointer position and deselects text outside that range. .IP "\fIforward-character()\fP:" Moves the insertion cursor one character to the right. For other effects, see the description of navigation operations in the "Keyboard Selection" section. This action may have different behavior in a right-to-left language environment. .IP "\fIforward-paragraph(\fBextend\fI)\fP:" If \fIXmNeditMode\fP is \fIXmMULTI_LINE_EDIT\fP, and this action is called with no argument, moves the insertion cursor to the first non-whitespace character following the next blank line. If the insertion cursor is already at the beginning of a paragraph, moves the insertion cursor to the beginning of the next paragraph. For other effects, see the description of navigation operations in the "Keyboard Selection" section. .IP If \fIXmNeditMode\fP is \fIXmMULTI_LINE_EDIT\fP and this action is called with an argument of \fIextend\fP, moves the insertion cursor as in the case of no argument and extends the current selection. For other effects, see the description of shifted navigation operations in the "Keyboard Selection" section. .nL .ne 9 .IP "\fIforward-word(\fBextend\fI)\fP:" If this action is called with no argument, moves the insertion cursor to the first whitespace character or end of line following the next non-whitespace character. If the insertion cursor is already at the end of a word, moves the insertion cursor to the end of the next word. For other effects, see the description of navigation operations in the "Keyboard Selection" section. This action may have different behavior in a locale other than the C locale. .IP If called with an argument of \fIextend\fP, moves the insertion cursor as in the case of no argument and extends the current selection. For other effects, see the description of shifted navigation operations in the "Keyboard Selection" section. .IP "\fIgrab-focus()\fP:" This key binding performs the action defined in the \fIXmNselectionArray\fP, depending on the number of multiple mouse clicks. The default selection array ordering is one click to move the insertion cursor to the pointer position, two clicks to select a word, three clicks to select a line of text, and four clicks to select all text. A single click also deselects any selected text and sets the anchor at the pointer position. This action may have different behavior in a locale other than the C locale. .IP "\fIHelp()\fP:" Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIinsert-string(\fBstring\fI)\fP:" If \fIXmNpendingDelete\fP is True and the cursor is not disjoint from the current selection, deletes the entire selection. Inserts \fBstring\fP before the insertion cursor. .IP "\fIkey-select(\fBdirection\fI)\fP:" If called with an argument of \fIright\fP, moves the insertion cursor one character to the right and extends the current selection. If called with an argument of \fIleft\fP, moves the insertion cursor one character to the left and extends the current selection. If called with no argument, extends the current selection. For other effects, see the description of shifted navigation operations and \fIKExtend\fP" in the "Keyboard Selection" section. .IP "\fIkill-next-character()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise kills the character following the insertion cursor and stores the character in the cut buffer. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise kills the character following the insertion cursor and stores the character in the cut buffer. This may impact the selection. .IP "\fIkill-next-word()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise kills the characters following the insertion cursor to the next space, tab or end of line character, and stores the characters in the cut buffer. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise kills the characters following the insertion cursor to the next space, tab or end of line character, and stores the characters in the cut buffer. This may impact the selection. This action may have different behavior in a locale other than the C locale. .IP "\fIkill-previous-character()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise kills the character immediately preceding the insertion cursor and stores the character in the cut buffer. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise kills the character immediately preceding the insertion cursor and stores the character in the cut buffer. This may impact the selection. .IP "\fIkill-previous-word()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise kills the characters preceding the insertion cursor up to the next space, tab or beginning of line character, and stores the characters in the cut buffer. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise kills the characters preceding the insertion cursor up to the next space, tab or beginning of line character, and stores the characters in the cut buffer. This may impact the selection. This action may have different behavior in a locale other than the C locale. .IP "\fIkill-selection()\fP:" Kills the currently selected text and stores the text in the cut buffer. .IP "\fIkill-to-end-of-line()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise kills the characters following the insertion cursor to the next end of line character and stores the characters in the cut buffer. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise kills the characters following the insertion cursor to the next end of line character and stores the characters in the cut buffer. This may impact the selection. .IP "\fIkill-to-start-of-line()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise kills the characters preceding the insertion cursor to the next beginning of line character and stores the characters in the cut buffer. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise kills the characters preceding the insertion cursor to the next beginning of line character and stores the characters in the cut buffer. This may impact the selection. .nL .ne 7 .IP "\fImove-destination()\fP:" Moves the insertion cursor to the pointer position without changing any existing current selection. If there is no current selection, sets the widget as the destination widget. .IP "\fImove-to()\fP:" If a secondary selection exists, cuts the secondary selection to the insertion cursor. If no secondary selection exists, cuts the primary selection to the pointer location. .IP "\fInewline()\fP:" If \fIXmNpendingDelete\fP is True and the cursor is not disjoint from the current selection, deletes the entire selection. Inserts a newline before the insertion cursor. .IP "\fInewline-and-backup()\fP:" If \fIXmNpendingDelete\fP is True and the cursor is not disjoint from the current selection, deletes the entire selection. Inserts a newline just before the insertion cursor and repositions the insertion cursor to the end of the line before the newline. .IP "\fInewline-and-indent()\fP:" If \fIXmNpendingDelete\fP is True and the cursor is not disjoint from the current selection, deletes the entire selection. Inserts a newline and then the same number of whitespace characters as at the beginning of the previous line. .IP "\fInext-line()\fP:" Moves the insertion cursor to the next line. For other effects, see the description of navigation operations in the "Keyboard Selection" section. .IP "\fInext-page(\fBextend\fI)\fP:" If this action is called with no argument, moves the insertion cursor forward one page. For other effects, see the description of navigation operations in the "Keyboard Selection" section. .IP If called with an argument of \fIextend\fP, moves the insertion cursor as in the case of no argument and extends the current selection. For other effects, see the description of shifted navigation operations in the "Keyboard Selection" section. .IP "\fInext-tab-group()\fP:" Traverses to the next tab group. .nL .ne 8 .IP "\fIpage-left()\fP:" Scrolls the viewing window left one page of text. .IP "\fIpage-right()\fP:" Scrolls the viewing window right one page of text. .IP "\fIpaste-clipboard()\fP:" Pastes the contents of the clipboard before the insertion cursor. .IP "\fIprev-tab-group()\fP:" Traverses to the previous tab group. .IP "\fIprevious-line()\fP:" Moves the insertion cursor to the previous line. For other effects, see the description of navigation operations in the "Keyboard Selection" section. .IP "\fIprevious-page(\fBextend\fI)\fP:" If this action is called with no argument, moves the insertion cursor back one page. For other effects, see the description of navigation operations in the "Keyboard Selection" section. .IP If called with an argument of \fIextend\fP, moves the insertion cursor as in the case of no argument and extends the current selection. For other effects, see the description of shifted navigation operations in the "Keyboard Selection" section. .IP "\fIprocess-bdrag()\fP" The result of this action is determined by several factors: position of the location cursor, movement of the location cursor, and the interval between a \fIBDrag\fP press and release. .IP This action copies the current selection to the insertion cursor if text is selected, the location cursor is disjoint from the current selection, and no motion is detected within a given time interval. .IP It performs a secondary selection and copies the selection to the position where the text was last edited if the cursor is disjoint from a current selection (if one exists), the time interval is exceeded, and movement of the location cursor is detected. .IP The action drags the current selection if the location cursor is positioned on the selection, the time interval is exceeded, and movement of the location cursor is detected. This action creates a DragContext object whose \fIXmNexportTargets\fP resource value includes target types of COMPOUND_TEXT, STRING, and TEXT. .IP "\fIprocess-cancel()\fP:" Cancels the current \fIextend-adjust()\fP, \fIsecondary-adjust()\fP or \fIprocess-bdrag()\fP operation and leaves the selection state as it was before the operation, otherwise, and if the parent is a manager, passes the event to the parent. .IP "\fIprocess-down()\fP:" If \fIXmNeditMode\fP is \fIXmSINGLE_LINE_EDIT\fP and \fIXmNnavigationType\fP is \fIXmNONE\fP, traverses to the widget below the current one in the tab group. .IP If \fIXmNeditMode\fP is \fIXmMULTI_LINE_EDIT\fP, moves the insertion cursor down one line. For other effects, see the description of navigation operations in the "Keyboard Selection" section. .nL .ne 8 .IP "\fIprocess-home()\fP:" Moves the insertion cursor to the beginning of the line. For other effects, see the description of navigation operations in the "Keyboard Selection" section. .IP "\fIprocess-return()\fP:" If \fIXmNeditMode\fP is \fIXmSINGLE_LINE_EDIT\fP, calls the callbacks for \fIXmNactivateCallback\fP, and if the parent is a manager, passes the event to the parent. If \fIXmNeditMode\fP is \fIXmMULTI_LINE_EDIT\fP, inserts a newline. .IP "\fIprocess-shift-down()\fP:" If \fIXmNeditMode\fP is \fIXmMULTI_LINE_EDIT\fP, moves the insertion cursor down one line. For other effects, see the description of navigation operations in the "Keyboard Selection" section. .IP "\fIprocess-shift-up()\fP:" If \fIXmNeditMode\fP is \fIXmMULTI_LINE_EDIT\fP, moves the insertion cursor up one line. For other effects, see the description of navigation operations in the "Keyboard Selection" section. .IP "\fIprocess-tab()\fP:" If \fIXmNeditMode\fP is \fIXmSINGLE_LINE_EDIT\fP, traverses to the next tab group. If \fIXmNeditMode\fP is \fIXmMULTI_LINE_EDIT\fP, inserts a tab. .IP "\fIprocess-up()\fP:" If \fIXmNeditMode\fP is \fIXmSINGLE_LINE_EDIT\fP and \fIXmNnavigationType\fP is \fIXmNONE\fP, traverses to the widget above the current one in the tab group. .IP If \fIXmNeditMode\fP is \fIXmMULTI_LINE_EDIT\fP, moves the insertion cursor up one line. For other effects, see the description of navigation operations in the "Keyboard Selection" section. .IP "\fIredraw-display()\fP:" Redraws the contents of the text window. .IP "\fIscroll-cursor-vertically(\fBpercentage\fI)\fP:" Scrolls the line containing the insertion cursor vertically to an intermediate position in the visible window based on an input percentage. A value of 0 indicates the top of the window; a value of 100, the bottom of the window. If this action is called with no argument, the line containing the insertion cursor is scrolled vertically to a new position designated by the \fBy\fP position of the event passed to the routine. .IP "\fIscroll-one-line-down()\fP:" Scrolls the text area down one line. .IP "\fIscroll-one-line-up()\fP:" Scrolls the text area up one line. .IP "\fIsecondary-adjust()\fP:" Extends the secondary selection to the pointer position. .IP "\fIsecondary-notify()\fP:" Copies the secondary selection to the insertion cursor of the destination widget. .IP "\fIsecondary-start()\fP:" Marks the beginning of a secondary selection. .IP "\fIselect-adjust()\fP:" Extends the current selection. The amount of text selected depends on the number of mouse clicks, as specified by the \fIXmNselectionArray\fP resource. .IP "\fIselect-all()\fP:" Selects all text. .IP "\fIselect-end()\fP:" Extends the current selection. The amount of text selected depends on the number of mouse clicks, as specified by the \fIXmNselectionArray\fP resource. .IP "\fIselect-start()\fP:" Marks the beginning of a new selection region. .IP "\fIself-insert()\fP:" If \fIXmNpendingDelete\fP is True and the cursor is not disjoint from the current selection, deletes the entire selection. Inserts the character associated with the key pressed at the insertion cursor. .IP "\fIset-anchor()\fP:" Resets the anchor point for extended selections. Resets the destination of secondary selection actions. .nL .ne 8 .IP "\fIset-insertion-point()\fP:" Sets the insertion position. .IP "\fIset-selection-hint()\fP:" Sets the text source and location of the current selection. .IP "\fItoggle-add-mode()\fP:" Toggles the state of Add Mode. .IP "\fItoggle-overstrike()\fP:" Toggles the state of the text insertion mode. By default, characters typed into the Text widget are inserted at the position of the insertion cursor. In overstrike mode, characters entered into the Text widget replace the characters that directly follow the insertion cursor. In overstrike mode, when the end of a line is reached, characters are appended to the end of the line. .IP "\fItraverse-home()\fP:" Traverses to the first widget in the tab group. .IP "\fItraverse-next()\fP:" Traverses to the next widget in the tab group. .IP "\fItraverse-prev()\fP:" Traverses to the previous widget in the tab group. .IP "\fIunkill()\fP:" Restores last killed text to the position of the insertion cursor. .SS "Additional Behavior" This widget has the additional behavior described below: .IP "\fI\fP:" Draws the insertion cursor as solid and starts blinking the cursor. .IP "\fI\fP:" Displays the insertion cursor as a stippled I-beam unless it is the destination widget. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. The following table lists the Text-specific bindings of virtual keys to actual key event descriptions in 1/Motif: .PP .sp 1 .in 0 .KS .TS tab(@) center; cb s lb | lb. Virtual Key Bindings _ Virtual Key@Actual Key Events = KActivate@CtrlReturn @osfActivate _ KExtend@Ctrl Shiftspace @ShiftosfSelect _ KNextField@CtrlTab _ KSelect@Ctrlspace @osfSelect _ .TE .KE .in .sp 1 For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fICore(3X)\fP, \fIXmCreateScrolledText(3X)\fP, \fIXmCreateText(3X)\fP, \fIXmDisplay(3X)\fP, \fIXmFontList(3X)\fP, \fIXmFontListAppendEntry(3X)\fP, \fIXmPrimitive(3X)\fP, \fIXmTextClearSelection(3X)\fP, \fIXmTextCopy(3X)\fP, \fIXmTextCut(3X)\fP, \fIXmTextEnableRedisplay(3X)\fP, \fIXmTextDisableRedisplay(3X)\fP, \fIXmTextField(3X)\fP, \fIXmTextFindString(3X)\fP, \fIXmTextFindStringWcs(3X)\fP, \fIXmTextGetBaseline(3X)\fP, \fIXmTextGetEditable(3X)\fP, \fIXmTextGetInsertionPosition(3X)\fP, \fIXmTextGetLastPosition(3X)\fP, \fIXmTextGetMaxLength(3X)\fP, \fIXmTextGetSelection(3X)\fP, \fIXmTextGetSelectionWcs(3X)\fP, \fIXmTextGetSelectionPosition(3X)\fP, \fIXmTextGetSource(3X)\fP, \fIXmTextGetString(3X)\fP, \fIXmTextGetStringWcs(3X)\fP, \fIXmTextGetSubstring(3X)\fP, \fIXmTextGetSubstringWcs(3X)\fP, \fIXmTextGetTopCharacter(3X)\fP, \fIXmTextInsert(3X)\fP, \fIXmTextInsertWcs(3X)\fP, \fIXmTextPaste(3X)\fP, \fIXmTextPosToXY(3X)\fP, \fIXmTextPosition(3X)\fP, \fIXmTextRemove(3X)\fP, \fIXmTextReplace(3X)\fP, \fIXmTextReplaceWcs(3X)\fP, \fIXmTextScroll(3X)\fP, \fIXmTextSetAddMode(3X)\fP, \fIXmTextSetEditable(3X)\fP, \fIXmTextSetHighlight(3X)\fP, \fIXmTextSetInsertionPosition(3X)\fP, \fIXmTextSetMaxLength(3X)\fP, \fIXmTextSetSelection(3X)\fP, \fIXmTextSetSource(3X)\fP, \fIXmTextSetString(3X)\fP, \fIXmTextSetStringWcs(3X)\fP, \fIXmTextSetTopCharacter(3X)\fP, \fIXmTextShowPosition(3X)\fP, and \fIXmTextXYToPos(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextClearSelection 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextClearSelection\fP \- A Text function that clears the primary selection .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextClearSelection (\fBwidget, time\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Time \fBtime\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextClearSelection\fP clears the primary selection in the Text widget. .IP "\fBwidget\fP" Specifies the Text widget ID. .IP "\fBtime\fP" Specifies the server time at which the selection value is desired. This should be the time of the event which triggered this request. One source of a valid time stamp is the function \fIXtLastTimestampProcessed()\fP. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextCopy 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextCopy\fP \- A Text function that copies the primary selection to the clipboard .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextCopy (\fBwidget, time\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Time \fBtime\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextCopy\fP copies the primary selected text to the clipboard. .IP "\fBwidget\fP" Specifies the Text widget ID. .IP "\fBtime\fP" Specifies the server time at which the selection value is to be modified. This should be the time of the event which triggered this request. One source of a valid time stamp is the function \fIXtLastTimestampProcessed()\fP. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE This function returns False if the primary selection is NULL, if the \fBwidget\fP doesn't own the primary selection, or if the function is unable to gain ownership of the clipboard selection. Otherwise, it returns True. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextCut 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextCut\fP \- A Text function that copies the primary selection to the clipboard and deletes the selected text .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextCut (\fBwidget, time\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Time \fBtime\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextCut\fP copies the primary selected text to the clipboard and then deletes the primary selected text. This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. .P .IP "\fBwidget\fP" Specifies the Text widget ID. .IP "\fBtime\fP" Specifies the server time at which the selection value is to be modified. This should be the time of the event which triggered this request. One source of a valid time stamp is the function \fIXtLastTimestampProcessed()\fP. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE This function returns False if the primary selection is NULL, if the \fBwidget\fP doesn't own the primary selection, or if the function is unable to gain ownership of the clipboard selection. Otherwise, it returns True. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextDisableRedisplay 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextDisableRedisplay\fP \- A Text function that temporarily prevents visual update of the Text widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextDisableRedisplay (\fBwidget\fI) .ta .5i 1.7i .nf Widget \fBwidget\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTextDisableRedisplay\fP prevents redisplay of the specified Text widget even though its visual attributes have been modified. The visual appearance of the widget remains unchanged until \fIXmTextEnableRedisplay\fP is called. This allows an application to make multiple changes to the widget without causing intermediate visual updates. .IP "\fBwidget\fP" Specifies the Text widget ID .SH RELATED INFORMATION .na \fIXmTextEnableRedisplay(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextEnableRedisplay 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextEnableRedisplay\fP \- A Text function that forces the visual update of a Text widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextEnableRedisplay (\fBwidget\fI) .ta .5i 1.7i .nf Widget \fBwidget\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTextEnableRedisplay\fP is used in conjunction with \fIXmTextDisableRedisplay\fP, which suppresses visual update of the Text widget. When \fIXmTextEnableRedisplay\fP is called, it determines if any visual attributes have been set or modified for the specified widget since \fIXmTextDisableRedisplay\fP was called. If so, it forces the widget to update its visual display for all of the intervening changes. Any subsequent changes that affect visual appearance cause the widget to update its visual display. .IP "\fBwidget\fP" Specifies the Text widget ID .SH RELATED INFORMATION .na \fIXmTextDisableRedisplay(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextField 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextField\fP \- The TextField class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi TextField widget provides a single line text editor for customizing both user and programmatic interfaces. It is used for single-line string entry, and forms entry with verification procedures. It provides an application with a consistent editing system for textual data. .PP TextField widget provides separate callback lists to verify movement of the insert cursor, modification of the text, and changes in input focus. Each of these callbacks provides the verification function with the widget instance, the event that caused the callback, and a data structure specific to the verification type. From this information the function can verify if the application considers this to be a legitimate state change and can signal the widget whether to continue with the action. .PP The user interface tailors a new set of actions. The key bindings have been added for insert cursor movement, deletion, insertion, and selection of text. .PP TextField allows the user to select regions of text. Selection is based on the model specified in the \fBInter-Client Communication Conventions Manual\fP (ICCCM). TextField supports primary and secondary selection. .SS "Classes" TextField widget inherits behavior and resources from \fICore\fP and \fIPrimitive\fP classes. .wH .rS .PP The class pointer is \fIxmTextFieldWidgetClass\fP. .PP The class name is \fIXmTextField\fP. .wH .rE .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lower case or upper case, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmTextFieldResource Set Name Class Type Default Access _ XmNactivateCallback XmCCallback XtCallbackList NULL C XmNblinkRate XmCBlinkRate int 500 CSG XmNcolumns XmCColumns short dynamic CSG XmNcursorPosition XmCCursorPosition XmTextPosition 0 CSG XmNcursorPositionVisible XmCCursorPositionVisible Boolean True CSG XmNeditable XmCEditable Boolean True CSG XmNfocusCallback XmCCallback XtCallbackList NULL C XmNfontList XmCFontList XmFontList dynamic CSG XmNgainPrimaryCallback XmCCallback XtCallbackList NULL C XmNlosePrimaryCallback XmCCallback XtCallbackList NULL C XmNlosingFocusCallback XmCCallback XtCallbackList NULL C XmNmarginHeight XmCMarginHeight Dimension 5 CSG XmNmarginWidth XmCMarginWidth Dimension 5 CSG XmNmaxLength XmCMaxLength int largest integer CSG XmNmodifyVerifyCallback XmCCallback XtCallbackList NULL C XmNmodifyVerifyCallbackWcs XmCCallback XtCallbackList NULL C XmNmotionVerifyCallback XmCCallback XtCallbackList NULL C XmNpendingDelete XmCPendingDelete Boolean True CSG XmNresizeWidth XmCResizeWidth Boolean False CSG XmNselectionArray XmCSelectionArray XtPointer default array CSG XmNselectionArrayCount XmCSelectionArrayCount int 3 CSG XmNselectThreshold XmCSelectThreshold int 5 CSG XmNvalue XmCValue String "" CSG XmNvalueChangedCallback XmCCallback XtCallbackList NULL C XmNvalueWcs XmCValueWcs wchar_t * (wchar_t *)"" CSG* XmNverifyBell XmCVerifyBell Boolean dynamic CSG .TE .KE .in .sp 1 * This resource cannot be specified in a resource file. .IP "\fIXmNactivateCallback\fP" Specifies the list of callbacks that is called when the user invokes an event that calls the \fIActivate()\fP function. The type of the structure whose address is passed to this callback is \fIXmAnyCallbackStruct\fP. The reason sent by the callback is \fIXmCR_ACTIVATE\fP. .IP "\fIXmNblinkRate\fP" Specifies the blink rate of the text cursor in milliseconds. The time indicated in the blink rate relates to the length of time the cursor is visible and the time the cursor is invisible (i.e., the time it will take to blink the insertion cursor on and off will be 2 times the blink rate). The cursor will not blink when the blink rate is set to zero. The value must not be negative. .nL .ne 6 .IP "\fIXmNcolumns\fP" Specifies the initial width of the text window as an integer number of characters. The width equals the number of characters specified by this resource multiplied by the maximum character width of the associated font. For proportionate fonts, the actual number of characters that fit on a given line may be greater than the value specified. The value must be greater than 0. The default value depends on the value of the \fIXmNwidth\fP resource. If no width is specified the default is 20. .IP "\fIXmNcursorPosition\fP" Indicates the position in the text where the current insert cursor is to be located. Position is determined by the number of characters from the beginning of the text. .IP "\fIXmNcursorPositionVisible\fP" Indicates that the insert cursor position is marked by a blinking text cursor when the Boolean is True. .IP "\fIXmNeditable\fP" Indicates that the user can edit the text string when set to True. A false value will prohibit the user from editing the text. .IP "\fIXmNfocusCallback\fP" Specifies the list of callbacks called when TextField accepts input focus. The type of the structure whose address is passed to this callback is \fIXmAnyCallbackStruct\fP. The reason sent by the callback is \fIXmCR_FOCUS\fP. .IP "\fIXmNfontList\fP" Specifies the font list to be used for TextField. If this value is NULL at initialization, it is initialized by looking up the parent hierarchy of the widget for an ancestor that is a subclass of the XmBulletinBoard or VendorShell widget class. If such an ancestor is found, the font list is initialized to the \fIXmNtextFontList\fP of the ancestor widget. If no such ancestor is found, the default is implementation dependent. Refer to \fIXmFontList(3X)\fP for more information on a font list structure. .PP TextField searches the font list for the first occurrence of a font set that has a \fIXmFONTLIST_DEFAULT_TAG\fP. If a default element is not found, the first font set in the font list is used. If the list contains no font sets, the first font in the font list is used. .IP "\fIXmNgainPrimaryCallback\fP" Specifies the list of callbacks that are called when the user invokes an event that cause the text widget to gain ownership of the primary selection. The callback reason for this callback is \fIXmCR_GAIN_PRIMARY\fP. .IP "\fIXmNlosePrimaryCallback\fP" Specifies the list of callbacks that are called when the user invokes an event that cause the text widget to lose ownership of the primary selection. The callback reason for this callback is \fIXmCR_LOSE_PRIMARY\fP. .nL .ne 12 .IP "\fIXmNlosingFocusCallback\fP" Specifies the list of callbacks that is called before TextField widget loses input focus. The type of the structure whose address is passed to this callback is \fIXmTextVerifyCallbackStruct\fP. The reason sent by the callback is \fIXmCR_LOSING_FOCUS\fP. .IP "\fIXmNmarginHeight\fP" Specifies the distance between the top edge of the widget window and the text, and the bottom edge of the widget window and the text. .IP "\fIXmNmarginWidth\fP" Specifies the distance between the left edge of the widget window and the text, and the right edge of the widget window and the text. .IP "\fIXmNmaxLength\fP" Specifies the maximum length of the text string that can be entered into text from the keyboard. This value must be non-negative. Strings that are entered using the \fIXmNvalue\fP resource or the \fIXmTextFieldSetString\fP function ignore this resource. .IP "\fIXmNmodifyVerifyCallback\fP" Specifies the list of callbacks that is called before text is deleted from or inserted into TextField. The type of the structure whose address is passed to this callback is \fIXmTextVerifyCallbackStruct\fP. The reason sent by the callback is \fIXmCR_MODIFYING_TEXT_VALUE\fP. When multiple TextField widgets share the same source, only the widget that initiates the source change will generate the \fIXmNmodifyVerifyCallback\fP. .PP If both \fIXmNmodifyVerifyCallback\fP and \fIXmNmodifyVerifyCallbackWcs\fP are registered callback lists, the procedure(s) in the \fIXmNmodifyVerifyCallback\fP list are always executed first; and the resulting data, which may have been modified, is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callback routines. .IP "\fIXmNmodifyVerifyCallbackWcs\fP" Specifies the list of callbacks called before text is deleted from or inserted into Text. The type of the structure whose address is passed to this callback is \fIXmTextVerifyCallbackStructWcs\fP. The reason sent by the callback is \fIXmCR_MODIFYING_TEXT_VALUE\fP. When multiple TextField widgets share the same source, only the widget that initiates the source change will generate the \fIXmNmodifyVerifyCallbackWcs\fP. .PP If both \fIXmNmodifyVerifyCallback\fP and \fIXmNmodifyVerifyCallbackWcs\fP are registered callback lists, the procedure(s) in the \fIXmNmodifyVerifyCallback\fP list are always executed first; and the resulting data, which may have been modified, is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callback routines. .IP "\fIXmNmotionVerifyCallback\fP" Specifies the list of callbacks that is called before the insert cursor is moved to a new position. The type of the structure whose address is passed to this callback is \fIXmTextVerifyCallbackStruct\fP. The reason sent by the callback is \fIXmCR_MOVING_INSERT_CURSOR\fP. It is possible more than one \fIXmNmotionVerifyCallback\fPs to be generated from a single action. .IP "\fIXmNpendingDelete\fP" Indicates that pending delete mode is on when the Boolean is True. Pending deletion is defined as deletion of the selected text when an insertion is made. .IP "\fIXmNresizeWidth\fP" Indicates that TextField widget will attempt to resize its width to accommodate all the text contained in the widget when Boolean is True. .nL .ne 18 .IP "\fIXmNselectionArray\fP" Defines the actions for multiple-mouse clicks. Each mouse click performed within a half of a second of the previous mouse click will increment the index into this array and perform the defined action for that index. The possible actions are: .wH .rS .TP \(bu \fIXmSELECT_POSITION\fP \- resets the insert cursor position. .TP \(bu \fIXmSELECT_WORD\fP \- selects a word. .TP \(bu \fIXmSELECT_LINE\fP \- selects a line of text. .wH .rE .IP "\fIXmNselectionArrayCount\fP" Specifies the number of actions that are defined in the \fIXmNselectionArray\fP resource. The value must not be negative. .IP "\fIXmNselectThreshold\fP" Specifies the number of pixels of motion that is required to select the next character when selection is performed using the click-drag mode of selection. The value must not be negative. .IP "\fIXmNvalue\fP" Specifies the string value of the TextField widget as a \fIchar*\fP data value. If \fIXmNvalue\fP and \fIXmNvalueWcs\fP are both defined, the value of \fIXmNvalueWcs\fP supersedes that of \fIXmNvalue\fP. \fIXtGetValues\fP returns a copy of the value of the internal buffer and \fIXtSetValues\fP copies the string values into the internal buffer. .IP "\fIXmNvalueChangedCallback\fP" Specifies the list of callbacks that is called after text is deleted from or inserted into TextField. The type of the structure whose address is passed to this callback is \fIXmAnyCallbackStruct\fP. The reason sent by the callback is \fIXmCR_VALUE_CHANGED\fP. When multiple TextField widgets share the same source, only the widget that initiates the source change will generate the \fIXmNvalueChangedCallback\fP. This callback represents a change in the source in the TextField, not in the TextField widget. The \fIXmNvalueChangedCallback\fP should occur only in pairs with a \fIXmNmodifyVerifyCallback\fP, assuming that the \fBdoit\fP flag in the callback structure of the \fIXmNmodifyVerifyCallback\fP is not set to False. .IP "\fIXmNvalueWcs\fP" Specifies the string value of the TextField widget as a \fIwchar_t*\fP data value. This resource cannot be specified in a resource file. .PP If \fIXmNvalue\fP and \fIXmNvalueWcs\fP are both defined, the value of \fIXmNvalueWcs\fP supersedes that of \fIXmNvalue\fP. \fIXtGetValues\fP returns a copy of the value of the internal buffer encoded as a wide character string. \fIXtSetValues\fP copies the value of the wide character string into the internal buffer. .IP "\fIXmNverifyBell\fP" Specifies whether a bell will sound when an action is reversed during a verification callback. The default depends on the value of the ancestor VendorShell's \fIXmNaudibleWarning\fP resource. .SS "Inherited Resources" TextField widget inherits behavior and resources from the following superclasses. For a complete description of these resources, refer to the man page for that superclass. .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPrimitive Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG .wH .tH XmNnavigationType XmCNavigationType XmNavigationType XmTAB_GROUP CSG XmNshadowThickness XmCShadowThickness Dimension 2 CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent \fB* event\fI; } XmAnyCallbackStruct; .iE .sE .wH .fi .wH .rS .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. .wH .rE .PP The TextField widget defines a new callback structure for use with verification callbacks. Note that not all of the fields are relevant for every callback reason. The application must first look at the \fBreason\fP field and use only the structure members that are valid for the particular reason. The values \fBstartPos\fP, \fBendPos\fP, and \fBtext\fP in the callback structure \fIXmTextVerifyCallbackStruct\fP may be modified upon receiving the callback, and these changes will be reflected as the change made to the source of the TextField widget. (For example, all keystrokes can be converted to spaces or NULL characters when a password is entered into a TextField widget.) The application programmer should not overwrite the \fBtext\fP field, but should attach data to that pointer. .PP A pointer to the following structure is passed to the callbacks for \fIXmNlosingFocusCallback\fP, \fIXmNmodifyVerifyCallback\fP, and \fIXmNmotionVerifyCallback\fP. .nL .ne 15 .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent *\fBevent\fI; Boolean \fBdoit\fI; XmTextPosition \fBcurrInsert, newInsert\fI; XmTextPosition \fBstartPos, endPos\fI; XmTextBlock \fBtext\fI; } XmTextVerifyCallbackStruct, *XmTextVerifyPtr; .iE .sE .wH .fi .wH .rS .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. It can be NULL. For example, changes made to the Text widget programmatically do not have an event that can be passed to the associated callback. .IP "\fBdoit\fP" Indicates whether that action that invoked the callback will be performed. Setting \fBdoit\fP to False negates the action. .IP "\fBcurrInsert\fP" Indicates the current position of the insert cursor. .IP "\fBnewInsert\fP" Indicates the position at which the user attempts to position the insert cursor. .IP "\fBstartPos\fP" Indicates the starting position of the text to modify. If the callback is not a modify verification callback, this value is the same as \fBcurrInsert\fP. .IP "\fBendPos\fP" Indicates the ending position of the text to modify. If no text is replaced or deleted, then the value is the same as \fBstartPos\fP. If the callback is not a modify verification callback, this value is the same as \fBcurrInsert\fP. .IP "\fBtext\fP" Points to a structure of type \fIXmTextBlockRec\fP. This structure holds the textual information to be inserted. .wH .rE .sS .iS .ta .25i 1.5i .nf typedef struct { char *\fBptr\fI; int \fBlength\fI; XmTextFormat \fBformat\fI } XmTextBlockRec, *XmTextBlock; .iE .sE .wH .fi .nL .ne 10 .wH .rS .IP "\fBptr\fP" Is the text to be inserted. \fBptr\fP points to a temporary storage space that is reused after the callback is finished. Therefore, if an application needs to save the text to be inserted, it should copy the text into its own data space. .IP "\fBlength\fP" Specifies the length of the text to be inserted. .IP "\fBformat\fP" Specifies the format of the text, either \fIXmFMT_8_BIT\fP or \fIXmFMT_16_BIT\fP. .PP A pointer to the following structure is passed to callbacks for \fIXmNmodifyVerifyCallbackWcs\fP. .sS .iS .ta .25i 1.5i .nf typedef struct { int \fBreason\fI; XEvent *\fBevent\fI; Boolean \fBdoit\fI; XmTextPosition \fBcurrInsert, newInsert\fI; XmTextPosition \fBstartPos, endPos\fI; XmWcsTextBlock \fBtext\fI; } XmTextVerifyCallbackStructWcs, *XmTextVerifyPtrWcs; .iE .sE .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked. .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback. It can be NULL. For example, changes made to the Text widget programmatically do not have an event that can be passed to the associated callback. .IP "\fBdoit\fP" Indicates whether the action that invoked the callback is performed. Setting \fBdoit\fP to False negates the action. .IP "\fBcurrInsert\fP" Indicates the current position of the insert cursor. .IP "\fBnewInsert\fP" Indicates the position at which the user attempts to position the insert cursor. .IP "\fBstartPos\fP" Indicates the starting position of the text to modify. If the callback is not a modify verification callback, this value is the same as \fBcurrInsert\fP. .IP "\fBendPos\fP" Indicates the ending position of the text to modify. If no text is replaced or deleted, the value is the same as \fBstartPos\fP. If the callback is not a modify verification callback, this value is the same as \fBcurrInsert\fP. .IP "\fBtext\fP" Points to a structure of type \fIXmTextBlockRecWcs\fP. This structure holds the textual information to be inserted. .sS .iS .ta .25i 1.5i .nf typedef struct { wchar_t *\fBwcsptr\fI; int \fBlength\fI; } XmTextBlockRecWcs, *XmTextBlockWcs; .iE .sE .wH .fi .IP "\fBwcsptr\fP" .ne 15 Points to the wide character text to be inserted. .IP "\fBlength\fP" Specifies the number of characters to be inserted. .PP The following table describes the reasons for which the individual verification callback structure fields are valid: .P .sp 1 .in 0 .KS .TS center; cb cb lfB lfH . Reason Valid Fields .sp .2 _ .sp .2 XmCR_LOSING_FOCUS T{ \fBreason, event, doit\fP T} XmCR_MODIFYING_TEXT_VALUE T{ \fBreason, event, doit, currInsert, newInsert, startPos, endPos, text\fP T} XmCR_MOVING_INSERT_CURSOR T{ \fBreason, event, doit, currInsert, newInsert\fP T} .sp .2 .TE .KE .in .sp 1 .SS "Translations" XmTextField includes translations from XmPrimitive. The XmTextField translations are listed below. These translations may not directly correspond to a translation table. The actions represent the effective behavior of the associated events, and they may differ in a right-to-left language environment. .iS .ta 1.5i .nf BSelect Press: grab-focus() BSelect Motion: extend-adjust() BSelect Release: extend-end() .sp \n(PDu BExtend Press: extend-start() BExtend Motion: extend-adjust() BExtend Release: extend-end() .sp \n(PDu BToggle Press: move-destination() .sp \n(PDu BDrag Press: process-bdrag() BDrag Motion: secondary-adjust() BDrag Release: copy-to() .sp \n(PDu MCtrl BDrag Press: process-bdrag() MCtrl BDrag Motion: secondary-adjust() MCtrl BDrag Release: copy-to() .sp \n(PDu MShift BDrag Press: process-bdrag() MShift BDrag Motion: secondary-adjust() MShift BDrag Release: move-to() .sp \n(PDu MAlt BDrag Press: process-bdrag() MAlt BDrag Motion: secondary-adjust() MAlt BDrag Release: copy-to() MAlt MCtrl BDrag Release: copy-to() MAlt MShift BDrag Release: move-to() .sp \n(PDu KUp: traverse-prev() .sp \n(PDu KDown: traverse-next() .sp \n(PDu KLeft: backward-character() MShift KLeft: key-select(left) MCtrl KLeft: backward-word() MShift MCtrl KLeft: backward-word(extend) .sp \n(PDu KRight: forward-character() MShift KRight: key-select(right) MCtrl KRight: forward-word() MShift MCtrl KRight: forward-word(extend) .sp \n(PDu KPageLeft: page-left() KPageRight: page-right() .sp \n(PDu KBeginLine: beginning-of-line() MShift KBeginLine: beginning-of-line(extend) .sp \n(PDu KEndLine: end-of-line() MShift KEndLine: end-of-line(extend) .sp \n(PDu KNextField: next-tab-group() KPrevField: prev-tab-group() .sp \n(PDu KActivate: activate() .sp \n(PDu KDelete: delete-next-character() KBackSpace: delete-previous-character() .sp \n(PDu KAddMode: toggle-add-mode() .sp \n(PDu KSpace: self-insert() MShift KSpace: self-insert() KSelect: set-anchor() KExtend: key-select() MAny KCancel: process-cancel() KClear: clear-selection() KSelectAll: select-all() KDeselectAll: deselect-all() .sp \n(PDu KCut: cut-clipboard() KCopy: copy-clipboard() KPaste: paste-clipboard() .sp \n(PDu KPrimaryCut: cut-primary() KPrimaryCopy: copy-primary() KPrimaryPaste: copy-primary() .sp \n(PDu KHelp: Help() .sp \n(PDu KAny: self-insert() .wH .fi .iE .SS "Action Routines" The XmText action routines are described below: .IP "\fIactivate()\fP:" Calls the callbacks for \fIXmNactivateCallback\fP. If the parent is a manager, passes the event to the parent. .IP "\fIbackward-character()\fP:" Moves the insertion cursor one character to the left. For other effects, see the description of navigation operations in the "Keyboard Selection" section in \fIXmText(3X)\fP. This action may have different behavior in a right-to-left language environment. .IP "\fIbackward-word(\fBextend\fI)\fP:" If this action is called with no argument, moves the insertion cursor to the first non-whitespace character after the first whitespace character to the left or after the beginning of the line. If the insertion cursor is already at the beginning of a word, moves the insertion cursor to the beginning of the previous word. For other effects, see the description of navigation operations in the "Keyboard Selection" section in \fIXmText(3X)\fP. This action may have different behavior in a locale other than the C locale. .PP If called with an argument of \fIextend\fP, moves the insertion cursor as in the case of no argument and extends the current selection. For other effects, see the description of shifted navigation operations in the "Keyboard Selection" section in \fIXmText(3X)\fP. .IP "\fIbeginning-of-line(\fBextend\fI)\fP:" If this action is called with no argument, moves the insertion cursor to the beginning of the line. For other effects, see the description of navigation operations in the "Keyboard Selection" section in \fIXmText(3X)\fP. .P If called with an argument of \fIextend\fP, moves the insertion cursor as in the case of no argument and extends the current selection. For other effects, see the description of shifted navigation operations in the "Keyboard Selection" section in \fIXmText(3X)\fP. .IP "\fIclear-selection()\fP:" Clears the current selection by replacing each character except \fI\fP with a \fI\fP character. .IP "\fIcopy-clipboard()\fP:" Copies the current selection to the clipboard. .IP "\fIcopy-primary()\fP:" Copies the primary selection to just before the insertion cursor. .IP "\fIcopy-to()\fP:" If a secondary selection exists, copies the secondary selection to just before the insertion cursor. If no secondary selection exists, copies the primary selection to the pointer location. .IP "\fIcut-clipboard()\fP:" Cuts the current selection to the clipboard. .IP "\fIcut-primary()\fP:" Cuts the primary selection to just before the insertion cursor. .IP "\fIdelete-next-character()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise deletes the character following the insertion cursor. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise deletes the character following the insertion cursor. This may impact the selection. .IP "\fIdelete-next-word()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise deletes the characters following the insertion cursor to the next space, tab or end of line character. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise deletes the characters following the insertion cursor to the next space, tab or end of line character. This may impact the selection. This action may have different behavior in a locale other than the C locale. .IP "\fIdelete-previous-character()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise deletes the character of text immediately preceding the insertion cursor. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise deletes the character of text immediately preceding the insertion cursor. This may impact the selection. .IP "\fIdelete-previous-word()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise deletes the characters preceding the insertion cursor to the next space, tab or beginning of the line character. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise deletes the characters preceding the insertion cursor to the next space, tab or beginning of line character.. This may impact the selection. This action may have different behavior in a locale other than the C locale. .IP "\fIdelete-selection()\fP:" Deletes the current selection. .IP "\fIdelete-to-end-of-line()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise deletes the characters following the insertion cursor to the next end of line character. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise deletes the characters following the insertion cursor to the next end of line character. This may impact the selection. .IP "\fIdelete-to-start-of-line()\fP:" In normal mode if there is a non-null selection, deletes the selection, otherwise deletes the characters preceding the insertion cursor to the previous beginning of line character. In add mode if there is a non-null selection, the cursor is not disjoint from the selection and \fIXmNpendingDelete\fP is set to True, deletes the selection, otherwise deletes the characters preceding the insertion cursor to the previous beginning of line character. This may impact the selection. .IP "\fIdeselect-all()\fP:" Deselects the current selection. .IP "\fIend-of-line(\fBextend\fI)\fP:" If this action is called with no argument, moves the insertion cursor to the end of the line. For other effects, see the description of navigation operations in the "Keyboard Selection" section in \fIXmText(3X)\fP. If called with an argument of \fIextend\fP, moves the insertion cursor as in the case of no argument and extends the current selection. For other effects, see the description of shifted navigation operations in the "Keyboard Selection" section in \fIXmText(3X)\fP. .IP "\fIextend-adjust()\fP:" Selects text from the anchor to the pointer position and deselects text outside that range. .IP "\fIextend-end()\fP:" Moves the insertion cursor to the position of the pointer. .IP "\fIextend-start()\fP:" Adjusts the anchor using the balance-beam method. Selects text from the anchor to the pointer position and deselects text outside that range. .IP "\fIforward-character()\fP:" Moves the insertion cursor one character to the right. For other effects, see the description of navigation operations in the "Keyboard Selection" section in \fIXmText(3X)\fP. This action may have different behavior in a right-to-left language environment. .IP "\fIforward-word(\fBextend\fI)\fP:" If this action is called with no argument, moves the insertion cursor to the first whitespace character or end of line following the next non-whitespace character. If the insertion cursor is already at the end of a word, moves the insertion cursor to the end of the next word. For other effects, see the description of navigation operations in the "Keyboard Selection" section in \fIXmText(3X)\fP. This action may have different behavior in a locale other than the C locale. .P If called with an argument of \fIextend\fP, moves the insertion cursor as in the case of no argument and extends the current selection. For other effects, see the description of shifted navigation operations in the "Keyboard Selection" section in \fIXmText(3X)\fP. .IP "\fIgrab-focus()\fP:" This key binding performs the action defined in the \fIXmNselectionArray\fP, depending on the number of multiple mouse clicks. The default selection array ordering is one click to move the insertion cursor to the pointer position, two clicks to select a word, three clicks to select a line of text, and four clicks to select all text. A single click also deselects any selected text and sets the anchor at the pointer position. This action may have different behavior in a locale other than the C locale. .IP "\fIHelp()\fP:" Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIkey-select(\fBdirection\fI)\fP:" If called with an argument of \fIright\fP, moves the insertion cursor one character to the right and extends the current selection. If called with an argument of \fIleft\fP, moves the insertion cursor one character to the left and extends the current selection. If called with no argument, extends the current selection. For other effects, see the description of shifted navigation operations and \fIKExtend\fP" in the "Keyboard Selection" section in \fIXmText(3X)\fP. .IP "\fImove-destination()\fP:" Moves the insertion cursor to the pointer position without changing any existing current selection. If there is no current selection, sets the widget as the destination widget. .IP "\fImove-to()\fP:" If a secondary selection exists, cuts the secondary selection to just before the insertion cursor. If no secondary selection exists, cuts the primary selection to the pointer location. .IP "\fInext-tab-group()\fP:" Traverses to the next tab group. .nL .ne 8 .IP "\fIpage-left()\fP:" Scrolls the viewing window left one page of text. .IP "\fIpage-right()\fP:" Scrolls the viewing window right one page of text. .IP "\fIpaste-clipboard()\fP:" Pastes the contents of the clipboard before the insertion cursor. .IP "\fIprev-tab-group()\fP:" Traverses to the previous tab group. .IP "\fIprocess-bdrag()\fP" The result of this action is determined by several factors: position of the location cursor, movement of the location cursor, and the interval between a \fIBDrag\fP press and release. .PP This action copies the current selection to the insertion cursor if text is selected, the location cursor is disjoint from the selection, and no motion is detected within a given time interval. .PP It performs a secondary selection and copies the selection to the position where the text was last edited if the cursor is disjoint from a current selection (if one exists), the time interval is exceeded, and movement of the location cursor is detected. .PP The action drags the current selection if the location cursor is positioned on the selection, the time interval is exceeded, and movement of the location cursor is detected. This action creates a DragContext object whose \fIXmNexportTargets\fP resource value includes target types of COMPOUND_TEXT, STRING, and TEXT. .IP "\fIprocess-cancel()\fP:" Cancels the current \fIextend-adjust()\fP, \fIsecondary-adjust()\fP or \fIprocess-bdrag\fP operation and leaves the selection state as it was before the operation, otherwise, and the parent is a manager, it passes the event to the parent. .IP "\fIsecondary-adjust()\fP:" Extends the secondary selection to the pointer position. .IP "\fIsecondary-start()\fP:" Marks the beginning of a secondary selection. .IP "\fIselect-all()\fP:" Selects all text. .IP "\fIself-insert()\fP:" If \fIXmNpendingDelete\fP is True and the cursor is not disjoint from the current selection, deletes the entire selection. Inserts the character associated with the key pressed before the insertion cursor. .IP "\fIset-anchor()\fP:" Resets the anchor point for extended selections. Resets the destination of secondary selection actions. .IP "\fItoggle-add-mode()\fP:" Toggles the state of Add Mode. .IP "\fItoggle-overstrike()\fP:" Toggles the state of the text insertion mode. By default, characters typed into the TextField widget are inserted before the position of the insertion cursor. In overstrike mode, characters entered into the TextField widget replace the characters that directly follow the insertion cursor. In overstrike mode, when the end of a line is reached, characters are appended to the end of the line. .IP "\fItraverse-home()\fP:" Traverses to the first widget in the tab group. .IP "\fItraverse-next()\fP:" Traverses to the next widget in the tab group. .IP "\fItraverse-prev()\fP:" Traverses to the previous widget in the tab group. .SS "Additional Behavior" This widget has the additional behavior described below: .IP "\fI\fP:" Draws the insertion cursor as solid and starts blinking the cursor. .IP "\fI\fP:" Displays the insertion cursor as a stippled I-beam unless it is the destination widget. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. The following table lists the TextField-specific bindings of virtual keys to actual key event descriptions in 1/Motif: .PP .sp 1 .in 0 .KS .TS center; cb s lb | lb. Virtual Key Bindings _ Virtual Key@Actual Key Events = KExtend@Ctrl Shiftspace @ShiftosfSelect _ KSelect@Ctrlspace @osfSelect .TE .KE .in .sp 1 .P For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .SH RELATED INFORMATION .na \fICore(3X)\fP, \fIXmCreateTextField(3X)\fP, \fIXmFontList(3X)\fP, \fIXmFontListAppendEntry(3X)\fP, \fIXmPrimitive(3X)\fP, \fIXmTextFieldClearSelection(3X)\fP, \fIXmTextFieldCopy(3X)\fP, \fIXmTextFieldCut(3X)\fP, \fIXmTextFieldGetBaseline(3X)\fP, \fIXmTextFieldGetEditable(3X)\fP, \fIXmTextFieldGetInsertionPosition(3X)\fP, \fIXmTextFieldGetLastPosition(3X)\fP, \fIXmTextFieldGetMaxLength(3X)\fP, \fIXmTextFieldGetSelection(3X)\fP, \fIXmTextFieldGetSelectionPosition(3X)\fP, fIXmTextFieldGetSelectionWcs(3X)\fP, \fIXmTextFieldGetString(3X)\fP, \fIXmTextFieldGetStringWcs(3X)\fP, \fIXmTextFieldGetSubstring(3X)\fP, \fIXmTextFieldGetSubstringWcs(3X)\fP, \fIXmTextFieldInsert(3X)\fP, \fIXmTextFieldInsertWcs(3X)\fP, \fIXmTextFieldPaste(3X)\fP, \fIXmTextFieldPosToXY(3X)\fP, \fIXmTextFieldRemove(3X)\fP, \fIXmTextFieldReplace(3X)\fP, \fIXmTextFieldReplaceWcs(3X)\fP, \fIXmTextFieldSetAddMode(3X)\fP, \fIXmTextFieldSetEditable(3X)\fP, \fIXmTextFieldSetHighlight(3X)\fP, \fIXmTextFieldSetInsertionPosition(3X)\fP, \fIXmTextFieldSetMaxLength(3X)\fP, \fIXmTextFieldSetSelection(3X)\fP, \fIXmTextFieldSetString(3X)\fP, \fIXmTextFieldSetStringWcs(3X)\fP, \fIXmTextFieldShowPosition(3X)\fP, and \fIXmTextFieldXYToPos(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldClearSelection 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldClearSelection\fP \- A TextField function that clears the primary selection .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextFieldClearSelection (\fBwidget, time\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Time \fBtime\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldClearSelection\fP clears the primary selection in the TextField widget. .IP "\fBwidget\fP" Specifies the TextField widget ID. .IP "\fBtime\fP" Specifies the time at which the selection value is desired. This should be the time of the event which triggered this request. .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldCopy 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldCopy\fP \- A TextField function that copies the primary selection to the clipboard .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextFieldCopy (\fBwidget, time\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Time \fBtime\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldCopy\fP copies the primary selected text to the clipboard. .IP "\fBwidget\fP" Specifies the TextField widget ID. .IP "\fBtime\fP" Specifies the time at which the selection value is to be modified. This should be the time of the event which triggered this request. .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .nL .ne 10 .SH RETURN VALUE This function returns False if the primary selection is NULL, if the \fBwidget\fP doesn't own the primary selection, or if the function is unable to gain ownership of the clipboard selection. Otherwise, it returns True. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldCut 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldCut\fP \- A TextField function that copies the primary selection to the clipboard and deletes the selected text .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextFieldCut (\fBwidget, time\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Time \fBtime\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldCut\fP copies the primary selected text to the clipboard and then deletes the primary selected text. This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. .IP "\fBwidget\fP" Specifies the TextField widget ID. .IP "\fBtime\fP" Specifies the time at which the selection value is to be modified. This should be the time of the event which triggered this request. .PP .ne 5 For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RETURN VALUE This function returns False if the primary selection is NULL, if the \fBwidget\fP doesn't own the primary selection, or if the function is unable to gain ownership of the clipboard selection. Otherwise, it returns True. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldGetBaseline 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldGetBaseline\fP \- A TextField function that accesses the\fBx\fP position of the first baseline .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int XmTextFieldGetBaseline (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldGetBaseline\fP accesses the \fBx\fP position of the first baseline in the TextField widget, relative to the \fBx\fP position of the top of the widget. .IP "\fBwidget\fP" Specifies the TextField widget ID .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .nL .ne 15 .SH RETURN VALUE Returns an integer value that indicates the \fBx\fP position of the first baseline in the TextField widget. The calculation takes into account the margin height, shadow thickness, highlight thickness, and font ascent of the first font in the fontlist. In this calculation the \fBx\fP position of the top of the widget is 0. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldGetEditable 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldGetEditable\fP \- A TextField function that accesses the edit permission state .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextFieldGetEditable (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldGetEditable\fP accesses the edit permission state of the TextField widget. .IP "\fBwidget\fP" Specifies the TextField widget ID .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .nL .ne 10 .SH RETURN VALUE Returns a Boolean value that indicates the state of the \fIXmNeditable\fP resource. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldGetInsertionPosition 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldGetInsertionPosition\fP \- A TextField function that accesses the position of the insertion cursor .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmTextPosition XmTextFieldGetInsertionPosition (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldGetInsertionPosition\fP accesses the insertion cursor position of the TextField widget. .IP "\fBwidget\fP" Specifies the TextField widget ID .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .nL .ne 10 .SH RETURN VALUE Returns an XmTextPosition value that indicates the state of the \fIXmNcursorPosition\fP resource. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldGetLastPosition 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldGetLastPosition\fP \- A TextField function that accesses the position of the last text character .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmTextPosition XmTextFieldGetLastPosition (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldGetLastPosition\fP accesses the position of the last character in the text buffer of the TextField widget. .IP "\fBwidget\fP" Specifies the TextField widget ID .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .nL .ne 12 .SH RETURN VALUE Returns an XmTextPosition value that indicates the position of the last character in the text buffer. This is an integer number of characters from the beginning of the buffer. The first character position is 0. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldGetMaxLength 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldGetMaxLength\fP \- A TextField function that accesses the value of the current maximum allowable length of a text string entered from the keyboard .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int XmTextFieldGetMaxLength (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldGetMaxLength\fP accesses the value of the current maximum allowable length of the text string in the TextField widget entered from the keyboard. The maximum allowable length prevents the user from entering a text string larger than this limit. .IP "\fBwidget\fP" Specifies the TextField widget ID .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .nL .ne 10 .SH RETURN VALUE Returns the integer value that indicates the string's maximum allowable length that can be entered from the keyboard. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldGetSelection 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldGetSelection\fP \- A TextField function that retrieves the value of the primary selection .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu char * XmTextFieldGetSelection (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldGetSelection\fP retrieves the value of the primary selection. It returns a NULL pointer if no text is selected in the widget. The application is responsible for freeing the storage associated with the string by calling \fIXtFree\fP. .IP "\fBwidget\fP" Specifies the TextField widget ID .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .nL .ne 10 .SH RETURN VALUE Returns a character pointer to the string that is associated with the primary selection. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP and \fIXmTextFieldGetSelectionWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldGetSelectionPosition 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldGetSelectionPosition\fP \- A TextField function that accesses the position of the primary selection .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextFieldGetSelectionPosition (\fBwidget, left, right\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmTextPosition \fB*left\fI; .wH .fi XmTextPosition \fB*right\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldGetSelectionPosition\fP accesses the left and right position of the primary selection in the text buffer of the TextField widget. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBleft\fP" Specifies the pointer in which the position of the left boundary of the primary selection is returned. This is an integer number of characters from the beginning of the buffer. The first character position is 0. .IP "\fBright\fP" Specifies the pointer in which the position of the right boundary of the primary selection is returned. This is an integer number of characters from the beginning of the buffer. The first character position is 0. .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RETURN VALUE This function returns True if the widget owns the primary selection; otherwise, it returns False. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldGetSelectionWcs 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldGetSelectionWcs\fP \- A TextField function that retrieves the value of a wide character encoded primary selection .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu wchar_t * XmTextFieldGetSelectionWcs (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldGetSelectionWcs\fP retrieves the value of the primary selection, encoded in a wide character format. It returns a NULL pointer if no text is selected in the widget. The application is responsible for freeing the storage associated with the wide character buffer by calling \fIXtFree\fP. .IP "\fBwidget\fP" Specifies the TextField widget ID .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RETURN VALUE Returns the wide character string that is associated with the primary selection in the TextField widget. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP and \fIXmTextFieldGetSelection(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldGetString 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldGetString\fP \- A TextField function that accesses the string value .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu char * XmTextFieldGetString (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldGetString\fP accesses the string value of the TextField widget. The application is responsible for freeing the storage associated with the string by calling \fIXtFree\fP. .IP "\fBwidget\fP" Specifies the TextField widget ID .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .nL .ne 10 .SH RETURN VALUE Returns a character pointer to the string value of the TextField widget. Returns an empty string if the length of the TextField widget's string is 0. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP and \fIXmTextFieldGetStringWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldGetStringWcs 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldGetStringWcs\fP \- A TextField function that retrieves a copy of the wide character string value of a TextField widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu wchar_t * XmTextFieldGetStringWcs (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldGetStringWcs\fP retrieves a copy of the wide character string value of the TextField widget. The application is responsible for freeing the storage associated with the string by calling \fIXtFree\fP. .IP "\fBwidget\fP" Specifies the TextField widget ID .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RETURN VALUE Returns the wide character string value of the TextField widget. The function returns an empty string if the length of the TextField widget's string is 0. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP and \fIXmTextFieldGetString(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldGetSubstring 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldGetSubstring\fP \- A TextField function that retrieves a copy of a portion of the internal text buffer .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int XmTextFieldGetSubstring (\fBwidget, start, num_chars, buffer_size, buffer\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; XmTextPosition \fBstart\fI; int \fBnum_chars\fI; int \fBbuffer_size\fI; char *\fBbuffer\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldGetSubstring\fP retrieves a copy of a portion of the internal text buffer of a TextField widget. The function copies a specified number of characters from a given start position in the internal text buffer into a buffer provided by the application. A NULL terminator is placed at the end of the copied data. .PP The size of the required buffer depends on the maximum number of bytes per character (\fIMB_CUR_MAX\fP) for the current locale. \fIMB_CUR_MAX\fP is a macro defined in \fBstdlib.h\fP. The buffer should be large enough to contain the substring to be copied and a NULL terminator. Use the following equation to calculate the size of buffer the application should provide: .PP \fBbuffer_size\fP = (\fBnum_chars\fP * \fIMB_CUR_MAX\fP) + 1 .IP "\fBwidget\fP" Specifies the TextField widget ID. .IP "\fBstart\fP" Specifies the beginning character position from which the data will be retrieved. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .IP "\fBnum_chars\fP" Specifies the number of characters to be copied into the provided buffer. .IP "\fBbuffer_size\fP" Specifies the size of the supplied buffer in bytes. This size should account for a NULL terminator. .IP "\fBbuffer\fP" Specifies the character buffer into which the internal text buffer will be copied. .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RETURN VALUE .IP "\fIXmCOPY_SUCCEEDED\fP" The function was successful. .IP "\fIXmCOPY_FAILED\fP" The function failed because it was unable to copy the specified number of characters into the buffer provided. The buffer size may be insufficient. The contents of \fBbuffer\fP are undefined. .IP "\fIXmCOPY_TRUNCATED\fP" The requested number of characters extended beyond the internal buffer. The function copied characters between \fBstart\fP and the end of the widget's buffer and terminated the string with a NULL terminator; fewer than \fBnum_chars\fP characters were copied. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP and \fIXmTextFieldGetSubstringWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldGetSubstringWcs 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldGetSubstringWcs\fP \- A TextField function that retrieves a a portion of a wide character internal text buffer .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int XmTextFieldGetSubstringWcs (\fBwidget, start, num_chars, buffer_size, buffer\fI) .ta .5i 1.7i .nf Widget \fBwidget\fI; XmTextPosition \fBstart\fI; int \fBnum_chars\fI; int \fBbuffer_size\fI; wchar_t *\fBbuffer\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldGetSubstringWcs\fP retrieves a copy of a portion of the internal text buffer of a TextField widget that is stored in a wide character format. The function copies a specified number of characters from a given start position in the internal text buffer into a buffer provided by the application. A NULL terminator is placed at the end of the copied data. .IP "\fBwidget\fP" Specifies the TextField widget ID. .IP "\fBstart\fP" Specifies the beginning character position from which the data will be retrieved. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .IP "\fBnum_chars\fP" Specifies the number of \fIwchar_t\fP characters to be copied into the provided buffer. .IP "\fBbuffer_size\fP" Specifies the size of the supplied buffer as a number of \fIwchar_t\fP storage locations. The minimum size is \fBnum_chars\fP + 1. .IP "\fBbuffer\fP" Specifies the wide character buffer into which the internal text buffer will be copied. .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RETURN VALUE .IP "\fIXmCOPY_SUCCEEDED\fP" The function was successful. .IP "\fIXmCOPY_FAILED\fP" The function failed because it was unable to copy the specified number of characters into the buffer provided. The buffer size may be insufficient. The contents of \fBbuffer\fP are undefined. .IP "\fIXmCOPY_TRUNCATED\fP" The requested number of characters extended beyond the internal buffer. The function copied characters to the end of the buffer and terminated the string with a NULL terminator; fewer than \fBnum_chars\fP characters were copied. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP and \fIXmTextFieldGetSubstring(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldInsert 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldInsert\fP \- A TextField function that inserts a character string into a text string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextFieldInsert (\fBwidget, position, value\fI) .ta .5i 1.7i .nf Widget \fBwidget\fI; XmTextPosition \fBposition\fI; char \fB* value\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldInsert\fP inserts a character string into the text string in the TextField widget. The character positions begin at zero and are numbered sequentially from the beginning of the text. For example, to insert a string after the fourth character, the \fBposition\fP parameter must be 4. .PP This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBposition\fP" Specifies the position in the text string where the character string is to be inserted .IP "\fBvalue\fP" Specifies the character string value to be added to the text widget .PP .ne 4 For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP and \fIXmTextFieldInsertWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldInsertWcs 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldInsertWcs\fP \- A TextField function that inserts a wide character string into a TextField widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextFieldInsertWcs (\fBwidget, position, wcstring\fI) .ta .5i 2i .nf Widget \fBwidget\fI; XmTextPosition \fBposition\fI; wchar_t *\fBwcstring\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldInsertWcs\fP inserts a wide character string into the TextField widget at a specified location. The character positions begin at zero and are numbered sequentially from the beginning of the text. For example, to insert a string after the fourth character, the \fBposition\fP parameter must be 4. .PP This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBposition\fP" Specifies the position in the text string where the new character string is to be inserted .IP "\fBwcstring\fP" Specifies the wide character string value to be added to the TextField widget .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP and \fIXmTextFieldInsert(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldPaste 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldPaste\fP \- A TextField function that inserts the clipboard selection .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextFieldPaste (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldPaste\fP inserts the clipboard selection at the insertion cursor of the destination widget. If \fIXmNpendingDelete\fP is True and the insertion cursor is inside the current selection, the clipboard selection replaces the selected text. .PP This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. .IP "\fBwidget\fP" Specifies the TextField widget ID. .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .nL .ne 10 .SH RETURN VALUE This function returns False if the \fBwidget\fP doesn't own the primary selection. Otherwise, it returns True. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldPosToXY 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldPosToXY\fP \- A TextField function that accesses the x and y position of a character position .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextFieldPosToXY (\fBwidget, position, x, y\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmTextPosition \fBposition\fI; Position \fB*x\fI; Position \fB*y\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldPosToXY\fP accesses the x and y position, relative to the upper left corner of the TextField widget, of a given character position in the text buffer. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBposition\fP" Specifies the character position in the text for which the x and y position is accessed. This is an integer number of characters from the beginning of the buffer. The first character position is 0. .nL .ne 10 .IP "\fBx\fP" Specifies the pointer in which the x position, relative to the upper left corner of the widget, is returned. This value is meaningful only if the function returns True. .IP "\fBy\fP" Specifies the pointer in which the y position, relative to the upper left corner of the widget, is returned. This value is meaningful only if the function returns True. .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RETURN VALUE This function returns True if the character position is displayed in the TextField widget; otherwise, it returns False, and no \fBx\fP or \fBy\fP value is returned. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldRemove 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldRemove\fP \- A TextField function that deletes the primary selection .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextFieldRemove (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldRemove\fP deletes the primary selected text. If there is a selection, this routine also calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. .IP "\fBwidget\fP" Specifies the TextField widget ID. .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .nL .ne 10 .SH RETURN VALUE This function returns False if the primary selection is NULL or if the \fBwidget\fP doesn't own the primary selection. Otherwise, it returns True. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldReplace 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldReplace\fP \- A TextField function that replaces part of a text string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextFieldReplace (\fBwidget, from_pos, to_pos, value\fI) .ta .5i 1.7i .nf Widget \fBwidget\fI; XmTextPosition \fBfrom_pos\fI; XmTextPosition \fBto_pos\fI; char \fB* value\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldReplace\fP replaces part of the text string in the TextField widget. The character positions begin at zero and are numbered sequentially from the beginning of the text. .PP An example text replacement would be to replace the second and third characters in the text string. To accomplish this, the parameter \fBfrom_pos\fP must be 1 and \fBto_pos\fP must be 3. To insert a string after the fourth character, both parameters, \fBfrom_pos\fP and \fBto_pos\fP, must be 4. .PP This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBfrom_pos\fP" Specifies the start position of the text to be replaced .IP "\fBto_pos\fP" Specifies the end position of the text to be replaced .IP "\fBvalue\fP" Specifies the character string value to be added to the text widget .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. \fIXmTextFieldReplaceWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldReplaceWcs 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldReplaceWcs\fP \- A TextField function that replaces part of a wide character string in a TextField widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextFieldReplaceWcs (\fBwidget, from_pos, to_pos, wcstring\fI) .ta .5i 1.7i .nf Widget \fBwidget\fI; XmTextPosition \fBfrom_pos\fI; XmTextPosition \fBto_pos\fI; wchar_t *\fBwcstring\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldReplaceWcs\fP replaces part of the wide character string in the TextField widget. The character positions begin at zero and are numbered sequentially from the beginning of the text. .PP An example text replacement would be to replace the second and third characters in the text string. To accomplish this, the parameter \fBfrom_pos\fP must be 1 and \fBto_pos\fP must be 3. To insert a string after the fourth character, both parameters, \fBfrom_pos\fP and \fBto_pos\fP, must be 4. .PP This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBfrom_pos\fP" Specifies the start position of the text to be replaced .IP "\fBto_pos\fP" Specifies the end position of the text to be replaced .IP "\fBwcstring\fP" Specifies the wide character string value to be added to the TextField widget .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP and \fIXmTextFieldReplace(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldSetAddMode 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldSetAddMode\fP \- A TextField function that sets the state of Add Mode .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextFieldSetAddMode (\fBwidget, state\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Boolean \fBstate\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldSetAddMode\fP controls whether or not the TextField widget is in Add Mode. When the widget is in Add Mode, the insert cursor can be moved without disturbing the primary selection. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBstate\fP" Specifies whether or not the widget is in Add Mode. A value of True turns on Add Mode; a value of False turns off Add Mode. .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldSetEditable 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldSetEditable\fP \- A TextField function that sets the edit permission .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextFieldSetEditable (\fBwidget, editable\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Boolean \fBeditable\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldSetEditable\fP sets the edit permission state of the TextField widget. When set to True, the text string can be edited. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBeditable\fP" Specifies a Boolean value that when True allows text string edits .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldSetHighlight 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldSetHighlight\fP \- A TextField function that highlights text .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextFieldSetHighlight (\fBwidget, left, right, mode\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmTextPosition \fBleft\fI; XmTextPosition \fBright\fI; XmHighlightMode \fBmode\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldSetHighlight\fP highlights text between the two specified character positions. The \fBmode\fP parameter determines the type of highlighting. Highlighting text merely changes the visual appearance of the text; it does not set the selection. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBleft\fP" Specifies the position of the left boundary of text to be highlighted. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .IP "\fBright\fP" Specifies the position of the right boundary of text to be highlighted. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .IP "\fBmode\fP" Specifies the type of highlighting to be done. A value of \fIXmHIGHLIGHT_NORMAL\fP removes highlighting. A value of \fIXmHIGHLIGHT_SELECTED\fP highlights the test using reverse video. A value of \fIXmHIGHLIGHT_SECONDARY_SELECTED\fP highlights the text using underlining. .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldSetInsertionPosition 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldSetInsertionPosition\fP \- A TextField function that sets the position of the insertion cursor .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextFieldSetInsertionPosition (\fBwidget, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmTextPosition \fBposition\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldSetInsertionPosition\fP sets the insertion cursor position of the TextField widget. This routine also calls the widget's \fIXmNmotionVerifyCallback\fP callbacks if the insertion cursor position changes. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBposition\fP" Specifies the position of the insert cursor. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .PP .ne 12 For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldSetMaxLength 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldSetMaxLength\fP \- A TextField function that sets the value of the current maximum allowable length of a text string entered from the keyboard .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextFieldSetMaxLength (\fBwidget, max_length\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBmax_length\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldSetMaxLength\fP sets the value of the current maximum allowable length of the text string in the TextField widget. The maximum allowable length prevents the user from entering a text string from the keyboard that is larger than this limit. Strings that are entered using the \fIXmNvalue\fP (or \fIXmNvalueWcs\fP) resource, or the \fIXmTextFieldSetString\fP (or \fIXmTextFieldSetStringWcs\fP) function ignore this resource. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBmax_length\fP" Specifies the maximum allowable length of the text string .PP .ne 3 For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP, \fIXmTextFieldSetString(3X)\fP, and \fIXmTextFieldSetStringWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldSetSelection 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldSetSelection\fP \- A TextField function that sets the primary selection of the text .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextFieldSetSelection (\fBwidget, first, last, time\fI) .ta .5i 1.7i .nf Widget \fBwidget\fI; XmTextPosition \fBfirst\fI; XmTextPosition \fBlast\fI; Time \fBtime\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldSetSelection\fP sets the primary selection of the text in the widget. It also sets the insertion cursor position to the last position of the selection and calls the widget's \fIXmNmotionVerifyCallback\fP callbacks. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBfirst\fP" Marks the first character position of the text to be selected .IP "\fBlast\fP" Marks the last position of the text to be selected .IP "\fBtime\fP" Specifies the time at which the selection value is desired. This should be the same as the time of the event that triggered this request. .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldSetString 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldSetString\fP \- A TextField function that sets the string value .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextFieldSetString (\fBwidget, value\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; char \fB* value\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldSetString\fP sets the string value of the TextField widget. This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. It also sets the insertion cursor position to the beginning of the string and calls the widget's \fIXmNmotionVerifyCallback\fP callbacks. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBvalue\fP" Specifies the character pointer to the string value and places the string into the text edit window .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .nL .ne 8 .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP and \fIXmTextFieldSetStringWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldSetStringWcs 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldSetStringWcs\fP \- A TextField function that sets a wide character string value .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextFieldSetStringWcs (\fBwidget, wcstring\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; wchar_t *\fBwcstring\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldSetStringWcs\fP sets the wide character string value of the TextField widget. This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. It also sets the insertion cursor position to the beginning of the string and calls the widget's \fIXmNmotionVerifyCallback\fP callbacks. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBwcstring\fP" Specifies the wide character string value and places the string into the text edit window .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP and \fIXmTextFieldSetString(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldShowPosition 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldShowPosition\fP \- A TextField function that forces text at a given position to be displayed .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextFieldShowPosition (\fBwidget, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmTextPosition \fBposition\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldShowPosition\fP forces text at the specified position to be displayed. If the \fIXmNautoShowCursorPosition\fP resource is True, the application should also set the insert cursor to this position. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBposition\fP" Specifies the character position to be displayed. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .PP For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .nL .ne 4 .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFieldXYToPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFieldXYToPos\fP \- A TextField function that accesses the character position nearest an x and y position .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmTextPosition XmTextFieldXYToPos (\fBwidget, x, y\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Position \fBx\fI; Position \fBy\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextFieldXYToPos\fP accesses the character position nearest to the specified x and y position, relative to the upper left corner of the TextField widget. .IP "\fBwidget\fP" Specifies the TextField widget ID .IP "\fBx\fP" Specifies the x position, relative to the upper left corner of the widget. .IP "\fBy\fP" Specifies the y position, relative to the upper left corner of the widget. .PP .ne 4 For a complete definition of TextField and its associated resources, see \fIXmTextField(3X)\fP. .SH RETURN VALUE Returns the character position in the text nearest the x and y position specified. This is an integer number of characters from the beginning of the buffer. The first character position is 0. .SH RELATED INFORMATION .na \fIXmTextField(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFindString 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFindString\fP \- A Text function that finds the beginning position of a text string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextFindString (\fBwidget, start, string, direction, position\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; XmTextPosition \fBstart\fI; char *\fBstring\fI; XmTextDirection \fBdirection\fI; XmTextPosition *\fBposition\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTextFindString\fP locates the beginning position of a specified text string. This routine searches forward or backward for the first occurrence of the string starting from the given start position. .ig ++ \" apparently the code doesn't do this If a match is not found, the search wraps to the beginning of the buffer (to the end, when \fBdirection\fP is \fIXmTEXT_BACKWARD\fP) and continues to the initial start position. .++ If it finds a match, the function returns the position of the first character of the string in \fBposition\fP. .IP "\fBwidget\fP" Specifies the Text widget ID. .IP "\fBstart\fP" Specifies the character position from which the search proceeds. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .IP "\fBstring\fP" Specifies the search string. .IP "\fBdirection\fP" Indicates the search direction. It is relative to the primary direction of the text. The possible values are .IP "\fIXmTEXT_FORWARD\fP" The search proceeds toward the end of the text buffer. .IP "\fIXmTEXT_BACKWARD\fP" The search proceeds toward the beginning of the text buffer. .IP "\fBposition\fP" Specifies the pointer in which the first character position of the string match is returned. This is an integer number of characters from the beginning of the buffer. The first character position is 0. If the function returns False, this value is undefined. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE Returns True if a string match is found; otherwise, returns False. .SH RELATED INFORMATION .na \fIXmText(3X)\fP and \fIXmTextFindStringWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextFindStringWcs 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextFindStringWcs\fP \- A Text function that finds the beginning position of a wide character text string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextFindStringWcs (\fBwidget, start, wcstring, direction, position\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; XmTextPosition \fBstart\fI; wchar_t *\fBwcstring\fI; XmTextDirection \fBdirection\fI; XmTextPosition *\fBposition\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTextFindStringWcs\fP locates the beginning position of a specified wide character text string. This routine searches forward or backward for the first occurrence of the string, starting from the given start position. .ig ++ \" apparently the code doesn't do this If a match is not found, the search wraps to the beginning of the buffer (or to the end when \fBdirection\fP is \fIXmTEXT_BACKWARD\fP) and continues to the initial start position. .++ If a match is found, the function returns the position of the first character of the string in \fBposition\fP. .IP "\fBwidget\fP" Specifies the Text widget ID. .IP "\fBstart\fP" Specifies the character position from which the search proceeds. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .IP "\fBwcstring\fP" Specifies the wide character search string. .IP "\fBdirection\fP" Indicates the search direction. It is relative to the primary direction of the text. The possible values are .IP "\fIXmTEXT_FORWARD\fP" The search proceeds toward the end of the buffer. .IP "\fIXmTEXT_BACKWARD\fP" The search proceeds toward the beginning of the buffer. .IP "\fBposition\fP" Specifies the pointer in which the first character position of the string match is returned. This is an integer number of characters from the beginning of the buffer. The first character position is 0. If the function returns False, this value is undefined. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE Returns True if a string match is found; otherwise, returns False. .SH RELATED INFORMATION .na \fIXmText(3X)\fP and \fIXmTextFindString(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextGetBaseline 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextGetBaseline\fP \- A Text function that accesses the\fBx\fP position of the first baseline .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int XmTextGetBaseline (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextGetBaseline\fP accesses the \fBx\fP position of the first baseline in the Text widget, relative to the \fBx\fP position of the top of the widget. .IP "\fBwidget\fP" Specifies the Text widget ID .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .P .ne 10 .SH RETURN VALUE Returns an integer value that indicates the \fBx\fP position of the first baseline in the Text widget. The calculation takes into account the margin height, shadow thickness, highlight thickness, and font ascent of the first font in the fontlist. In this calculation the \fBx\fP position of the top of the widget is 0. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextGetEditable 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextGetEditable\fP \- A Text function that accesses the edit permission state .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextGetEditable (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextGetEditable\fP accesses the edit permission state of the Text widget. .IP "\fBwidget\fP" Specifies the Text widget ID .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE Returns a Boolean value that indicates the state of the \fIXmNeditable\fP resource. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextGetInsertionPosition 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextGetInsertionPosition\fP \- A Text function that accesses the position of the insert cursor .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmTextPosition XmTextGetInsertionPosition (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextGetInsertionPosition\fP accesses the insertion cursor position of the Text widget. .IP "\fBwidget\fP" Specifies the Text widget ID .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .P .ne 6 .SH RETURN VALUE Returns an XmTextPosition value that indicates the state of the \fIXmNcursorPosition\fP resource. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextGetLastPosition 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextGetLastPosition\fP \- A Text function that accesses the last position in the text .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmTextPosition XmTextGetLastPosition (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextGetLastPosition\fP accesses the last position in the text buffer of the Text widget. This is an integer number of characters from the beginning of the buffer, and represents the position following which text that is added to the end of the buffer is placed. The first character position is 0. The last character position is equal to the number of characters in the text buffer. .IP "\fBwidget\fP" Specifies the Text widget ID .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .P .ne 8 .SH RETURN VALUE Returns an XmTextPosition value that indicates the last position in the text buffer. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextGetMaxLength 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextGetMaxLength\fP \- A Text function that accesses the value of the current maximum allowable length of a text string entered from the keyboard .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int XmTextGetMaxLength (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextGetMaxLength\fP accesses the value of the current maximum allowable length of the text string in the Text widget entered from the keyboard. The maximum allowable length prevents the user from entering a text string larger than this limit. .IP "\fBwidget\fP" Specifies the Text widget ID .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE Returns the integer value that indicates the string's maximum allowable length that can be entered from the keyboard. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextGetSelection 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextGetSelection\fP \- A Text function that retrieves the value of the primary selection .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu char * XmTextGetSelection (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextGetSelection\fP retrieves the value of the primary selection. It returns a NULL pointer if no text is selected in the widget. The application is responsible for freeing the storage associated with the string by calling \fIXtFree\fP. .nL .ne 5 .IP "\fBwidget\fP" Specifies the Text widget ID .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE Returns a character pointer to the string that is associated with the primary selection. .SH RELATED INFORMATION .na \fIXmText(3X)\fP and \fIXmTextGetSelectionWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextGetSelectionPosition 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextGetSelectionPosition\fP \- A Text function that accesses the position of the primary selection .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextGetSelectionPosition (\fBwidget, left, right\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmTextPosition \fB*left\fI; .wH .fi XmTextPosition \fB*right\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTextGetSelectionPosition\fP accesses the left and right position of the primary selection in the text buffer of the Text widget. .P .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBleft\fP" Specifies the pointer in which the position of the left boundary of the primary selection is returned. This is an integer number of characters from the beginning of the buffer. The first character position is 0. .nL .ne 10 .IP "\fBright\fP" Specifies the pointer in which the position of the right boundary of the primary selection is returned. This is an integer number of characters from the beginning of the buffer. The first character position is 0. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE This function returns True if the widget owns the primary selection; otherwise, it returns False. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextGetSelectionWcs 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextGetSelectionWcs\fP \- A Text function that retrieves the value of a wide character encoded primary selection .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu wchar_t * XmTextGetSelectionWcs (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextGetSelectionWcs\fP retrieves the value of the primary selection that is encoded in a wide character format. It returns a NULL pointer if no text is selected in the widget. The application is responsible for freeing the storage associated with the wide character buffer by calling \fIXtFree\fP. .IP "\fBwidget\fP" Specifies the Text widget ID .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE Returns the wide character string that is associated with the primary selection in the Text widget. .SH RELATED INFORMATION .na \fIXmText(3X)\fP and \fIXmTextGetSelection(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextGetSource 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextGetSource\fP \- A Text function that accesses the source of the widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmTextSource XmTextGetSource (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextGetSource\fP accesses the source of the Text widget. Text widgets can share sources of text so that editing in one widget is reflected in another. This function accesses the source of one widget so that it can be made the source of another widget, using the function \fIXmTextSetSource(3X)\fP. .PP Setting a new text source destroys the old text source if no other Text widgets are using that source. To replace a text source but keep it for later use, create an unmanaged Text widget and set its source to the text source you want to keep. .IP "\fBwidget\fP" Specifies the Text widget ID .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE Returns an XmTextSource value that represents the source of the Text widget. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextGetString 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextGetString\fP \- A Text function that accesses the string value .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu char * XmTextGetString (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextGetString\fP accesses the string value of the Text widget. The application is responsible for freeing the storage associated with the string by calling \fIXtFree\fP. .IP "\fBwidget\fP" Specifies the Text widget ID .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE Returns a character pointer to the string value of the text widget. Returns an empty string if the length of the Text widget's string is 0. .SH RELATED INFORMATION .na \fIXmText(3X)\fP and \fIXmTextGetStringWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextGetStringWcs 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextGetStringWcs\fP \- A Text function that retrieves a copy of the wide character string value of a Text widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu wchar_t * XmTextGetStringWcs (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextGetStringWcs\fP retrieves a copy of the wide character string value of the Text widget. The application is responsible for freeing the storage associated with the string by calling \fIXtFree\fP. .IP "\fBwidget\fP" Specifies the Text widget ID .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE Returns the wide character string value of the Text widget. The function returns an empty string if the length of the Text widget's string is 0. .SH RELATED INFORMATION .na \fIXmText(3X)\fP and \fIXmTextGetString(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextGetSubstring 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextGetSubstring\fP \- A Text function that retrieves a copy of a portion of the internal text buffer .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int XmTextGetSubstring (\fBwidget, start, num_chars, buffer_size, buffer\fI) .ta .5i 1.7i .nf Widget \fBwidget\fI; XmTextPosition \fBstart\fI; int \fBnum_chars\fI; int \fBbuffer_size\fI; char *\fBbuffer\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTextGetSubstring\fP retrieves a copy of a portion of the internal text buffer of a Text widget. The function copies a specified number of characters from a given start position in the internal text buffer into a buffer provided by the application. A NULL terminator is placed at the end of the copied data. .PP The size of the required buffer depends on the maximum number of bytes per character (\fIMB_CUR_MAX\fP) for the current locale. \fIMB_CUR_MAX\fP is a macro defined in \fIstdlib.h\fP. The buffer should be large enough to contain the substring to be copied and a NULL terminator. Use the following equation to calculate the size of buffer the application should provide: .PP \fBbuffer_size\fP = (\fBnum_chars\fP * \fIMB_CUR_MAX\fP) + 1 .IP "\fBwidget\fP" Specifies the Text widget ID. .IP "\fBstart\fP" Specifies the beginning character position from which the data will be retrieved. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .IP "\fBnum_chars\fP" Specifies the number of characters to be copied into the provided buffer. .IP "\fBbuffer_size\fP" Specifies the size of the supplied buffer in bytes. This size should account for a NULL terminator. .IP "\fBbuffer\fP" Specifies the character buffer into which the internal text buffer will be copied. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE .IP "\fIXmCOPY_SUCCEEDED\fP" The function was successful. .IP "\fIXmCOPY_FAILED\fP" The function failed because it was unable to copy the specified number of characters into the buffer provided. The buffer size may be insufficient. The contents of \fBbuffer\fP are undefined. .IP "\fIXmCOPY_TRUNCATED\fP" The requested number of characters extended beyond the internal buffer. The function copied characters between \fBstart\fP and the end of the widget's buffer and terminated the string with a NULL terminator; fewer than \fBnum_chars\fP characters were copied. .SH RELATED INFORMATION .na \fIXmText(3X)\fP and \fIXmTextGetSubstringWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextGetSubstringWcs 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextGetSubstringWcs\fP \- A Text function that retrieves a portion of a wide character internal text buffer .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu int XmTextGetSubstringWcs (\fBwidget, start, num_chars, buffer_size, buffer\fI) .ta .5i 1.7i .nf Widget \fBwidget\fI; XmTextPosition \fBstart\fI; int \fBnum_chars\fI; int \fBbuffer_size\fI; wchar_t *\fBbuffer\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTextGetSubstringWcs\fP retrieves a copy of a portion of the internal text buffer of a Text widget that is stored in a wide character format. The function copies a specified number of characters from a given start position in the internal text buffer into a buffer provided by the application. A NULL terminator is placed at the end of the copied data. .IP "\fBwidget\fP" Specifies the Text widget ID. .IP "\fBstart\fP" Specifies the beginning character position from which the data will be retrieved. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .IP "\fBnum_chars\fP" Specifies the number of \fIwchar_t\fP characters to be copied into the provided buffer. .IP "\fBbuffer_size\fP" Specifies the size of the supplied buffer as a number of \fIwchar_t\fP storage locations. The minimum size is \fBnum_chars\fP + 1. .IP "\fBbuffer\fP" Specifies the wide character buffer into which the internal text buffer will be copied. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE .IP "\fIXmCOPY_SUCCEEDED\fP" The function was successful. .IP "\fIXmCOPY_FAILED\fP" The function failed because it was unable to copy the specified number of characters into the buffer provided. The buffer size may be insufficient. The contents of \fBbuffer\fP are undefined. .IP "\fIXmCOPY_TRUNCATED\fP" The requested number of characters extended beyond the internal buffer. The function copied characters between \fBstart\fP and the end of the widget's buffer and terminated the string with a NULL terminator; fewer than \fBnum_chars\fP characters were copied. .SH RELATED INFORMATION .na \fIXmText(3X)\fP and \fIXmTextGetSubstring(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextGetTopCharacter 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextGetTopCharacter\fP \- A Text function that accesses the position of the first character displayed .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmTextPosition XmTextGetTopCharacter (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextGetTopCharacter\fP accesses the position of the text at the top of the Text widget. .IP "\fBwidget\fP" Specifies the Text widget ID .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .P .ne 10 .SH RETURN VALUE Returns an XmTextPosition value that indicates the state of the \fIXmNtopCharacter\fP resource. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextInsert 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextInsert\fP \- A Text function that inserts a character string into a text string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextInsert(\fBwidget, position, value\fI) .ta .5i 2i .nf Widget \fBwidget\fI; XmTextPosition \fBposition\fI; char \fB* value\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextInsert\fP inserts a character string into the text string in the Text widget. The character positions begin at zero and are numbered sequentially from the beginning of the text. For example, to insert a string after the fourth character, the parameter \fBposition\fP must be 4. .PP This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. .IP "\fBwidget\fP" Specifies the Text widget ID. .IP "\fBposition\fP" Specifies the position in the text string where the character string is to be inserted. .IP "\fBvalue\fP" Specifies the character string value to be added to the text widget. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP and \fIXmTextInsertWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextInsertWcs 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextInsertWcs\fP \- A Text function that inserts a wide character string into a Text widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextInsertWcs (\fBwidget, position, wcstring\fI) .ta .5i 2i .nf Widget \fBwidget\fI; XmTextPosition \fBposition\fI; wchar_t *\fBwcstring\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextInsertWcs\fP inserts a wide character string into the Text widget at a specified location. The character positions begin at zero and are numbered sequentially from the beginning of the text. For example, to insert a string after the fourth character, the \fBposition\fP parameter must be 4. .PP This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBposition\fP" Specifies the position in the text string where the new character string is to be inserted .IP "\fBwcstring\fP" Specifies the wide character string value to be added to the Text widget .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP and \fIXmTextInsert(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextPaste 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextPaste\fP \- A Text function that inserts the clipboard selection .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextPaste (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextPaste\fP inserts the clipboard selection at the insertion cursor of the destination widget. If \fIXmNpendingDelete\fP is True and the insertion cursor is inside the current selection, the clipboard selection replaces the selected text. .PP This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. .IP "\fBwidget\fP" Specifies the Text widget ID. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE This function returns False if the \fBwidget\fP doesn't own the primary selection. Otherwise, it returns True. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextPosToXY 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextPosToXY\fP \- A Text function that accesses the x and y position of a character position .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextPosToXY (\fBwidget, position, x, y\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmTextPosition \fBposition\fI; Position \fB*x\fI; Position \fB*y\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextPosToXY\fP accesses the x and y position, relative to the upper left corner of the Text widget, of a given character position in the text buffer. .P .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBposition\fP" Specifies the character position in the text for which the x and y position is accessed. This is an integer number of characters from the beginning of the buffer. The first character position is 0. .IP "\fBx\fP" Specifies the pointer in which the x position, relative to the upper left corner of the widget, is returned. This value is meaningful only if the function returns True. .IP "\fBy\fP" Specifies the pointer in which the y position, relative to the upper left corner of the widget, is returned. This value is meaningful only if the function returns True. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE This function returns True if the character position is displayed in the Text widget; otherwise, it returns False, and no \fBx\fP or \fBy\fP value is returned. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextPosition 3X "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextPosition\fP \- Data type for a character position within a text string .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi \fIXmTextPosition\fP is the data type for a character position within a text string. The text position is an integer representing the number of characters from the beginning of the string. The first character position in the string is 0. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextRemove 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextRemove\fP \- A Text function that deletes the primary selection .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmTextRemove (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextRemove\fP deletes the primary selected text. If there is a selection, this routine also calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. .IP "\fBwidget\fP" Specifies the Text widget ID. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE This function returns False if the primary selection is NULL or if the \fBwidget\fP doesn't own the primary selection. Otherwise, it returns True. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextReplace 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextReplace\fP \- A Text function that replaces part of a text string .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextReplace (\fBwidget, from_pos, to_pos, value\fI) .ta .5i 1.7i .nf Widget \fBwidget\fI; XmTextPosition \fBfrom_pos\fI; XmTextPosition \fBto_pos\fI; char \fB* value\fI; .ne 12 .iE .sE .SH DESCRIPTION .fi \fIXmTextReplace\fP replaces part of the text string in the Text widget. The character positions begin at zero and are numbered sequentially from the beginning of the text. .nL .ne 5 .PP An example text replacement would be to replace the second and third characters in the text string. To accomplish this, the parameter \fBfrom_pos\fP must be 1 and \fBto_pos\fP must be 3. To insert a string after the fourth character, both parameters, \fBfrom_pos\fP and \fBto_pos\fP, must be 4. .PP .ne 20 This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. .P .nL .ne 5 .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBfrom_pos\fP" Specifies the start position of the text to be replaced .IP "\fBto_pos\fP" Specifies the end position of the text to be replaced .IP "\fBvalue\fP" Specifies the character string value to be added to the text widget .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP and \fIXmTextReplaceWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextReplaceWcs 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextReplaceWcs\fP \- A Text function that replaces part of a wide character string in a Text widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextReplaceWcs (\fBwidget, from_pos, to_pos, wcstring\fI) .ta .5i 1.7i .nf Widget \fBwidget\fI; XmTextPosition \fBfrom_pos\fI; XmTextPosition \fBto_pos\fI; wchar_t *\fBwcstring\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTextReplaceWcs\fP replaces part of the wide character string in the Text widget. The character positions begin at zero and are numbered sequentially from the beginning of the text. .PP An example text replacement would be to replace the second and third characters in the text string. To accomplish this, the \fBfrom_pos\fP parameter must be 1 and the \fBto_pos\fP parameter must be 3. To insert a string after the fourth character, both the \fBfrom_pos\fP and \fBto_pos\fP parameters must be 4. .PP This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBfrom_pos\fP" Specifies the start position of the text to be replaced .IP "\fBto_pos\fP" Specifies the end position of the text to be replaced .IP "\fBwcstring\fP" Specifies the wide character string value to be added to the Text widget .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP and \fIXmTextReplace(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextScroll 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextScroll\fP \- A Text function that scrolls text .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextScroll (\fBwidget, lines\fI) .ta .5i 1.7i .nf Widget \fBwidget\fI; int \fBlines\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextScroll\fP scrolls text in a Text widget. .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBlines\fP" Specifies the number of lines of text to scroll. A positive value causes text to scroll upward; a negative value causes text to scroll downward. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextSetAddMode 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextSetAddMode\fP \- A Text function that sets the state of Add Mode .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextSetAddMode (\fBwidget, state\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Boolean \fBstate\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextSetAddMode\fP controls whether or not the Text widget is in Add Mode. When the widget is in Add Mode, the insert cursor can be moved without disturbing the primary selection. .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBstate\fP" Specifies whether or not the widget is in Add Mode. A value of True turns on Add Mode; a value of False turns off Add Mode. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextSetEditable 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextSetEditable\fP \- A Text function that sets the edit permission .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextSetEditable (\fBwidget, editable\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Boolean \fBeditable\fI; .wH .fi .ne 12 .iE .sE .SH DESCRIPTION .fi \fIXmTextSetEditable\fP sets the edit permission state of the Text widget. When set to True, the text string can be edited. .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBeditable\fP" Specifies a Boolean value that when True allows text string edits .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextSetHighlight 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextSetHighlight\fP \- A Text function that highlights text .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextSetHighlight (\fBwidget, left, right, mode\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmTextPosition \fBleft\fI; XmTextPosition \fBright\fI; XmHighlightMode \fBmode\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextSetHighlight\fP highlights text between the two specified character positions. The \fBmode\fP parameter determines the type of highlighting. Highlighting text merely changes the visual appearance of the text; it does not set the selection. .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBleft\fP" Specifies the position of the left boundary of text to be highlighted. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .IP "\fBright\fP" Specifies the position of the right boundary of text to be highlighted. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .IP "\fBmode\fP" Specifies the type of highlighting to be done. A value of \fIXmHIGHLIGHT_NORMAL\fP removes highlighting. A value of \fIXmHIGHLIGHT_SELECTED\fP highlights the text using reverse video. A value of \fIXmHIGHLIGHT_SECONDARY_SELECTED\fP highlights the text using underlining. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextSetInsertionPosition 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextSetInsertionPosition\fP \- A Text function that sets the position of the insert cursor .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextSetInsertionPosition (\fBwidget, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmTextPosition \fBposition\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextSetInsertionPosition\fP sets the insertion cursor position of the Text widget. This routine also calls the widget's \fIXmNmotionVerifyCallback\fP callbacks if the insertion cursor position changes. .P .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBposition\fP" Specifies the position of the insertion cursor. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextSetMaxLength 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextSetMaxLength\fP \- A Text function that sets the value of the current maximum allowable length of a text string entered from the keyboard .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextSetMaxLength (\fBwidget, max_length\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; int \fBmax_length\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextSetMaxLength\fP sets the value of the current maximum allowable length of the text string in the Text widget. The maximum allowable length prevents the user from entering a text string from the keyboard that is larger than this limit. Strings that are entered using the \fIXmNvalue\fP (or \fIXmNvalueWcs\fP) resource, or the \fIXmTextSetString\fP (or \fIXmTextSetStringWcs\fP) function ignore this resource. .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBmax_length\fP" Specifies the maximum allowable length of the text string .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP, \fIXmTextSetString(3X)\fP, and \fIXmTextSetStringWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextSetSelection 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextSetSelection\fP \- A Text function that sets the primary selection of the text .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextSetSelection (\fBwidget, first, last, time\fI) .ta .5i 1.7i .nf Widget \fBwidget\fI; XmTextPosition \fBfirst\fI; XmTextPosition \fBlast\fI; Time \fBtime\fI; .wH .fi .ne 10 .iE .sE .SH DESCRIPTION .fi \fIXmTextSetSelection\fP sets the primary selection of the text in the widget. It also sets the insertion cursor position to the last position of the selection and calls the widget's \fIXmNmotionVerifyCallback\fP callbacks. .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBfirst\fP" Marks the first character position of the text to be selected .IP "\fBlast\fP" Marks the last position of the text to be selected .IP "\fBtime\fP" Specifies the time at which the selection value is desired. This should be the same as the time of the event that triggered this request. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextSetSource 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextSetSource\fP \- A Text function that sets the source of the widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextSetSource (\fBwidget, source, top_character, cursor_position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmTextSource \fBsource\fI; XmTextPosition \fBtop_character\fI; XmTextPosition \fBcursor_position\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextSetSource\fP sets the source of the Text widget. Text widgets can share sources of text so that editing in one widget is reflected in another. This function sets the source of one widget so that it can share the source of another widget. .PP Setting a new text source destroys the old text source if no other Text widgets are using that source. To replace a text source but keep it for later use, create an unmanaged Text widget and set its source to the text source you want to keep. .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBsource\fP" Specifies the source with which the widget displays text. This can be a value returned by the \fIXmTextGetSource(3X)\fP function. If no source is specified, the widget creates a default string source. .IP "\fBtop_character\fP" Specifies the position in the text to display at the top of the widget. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .IP "\fBcursor_position\fP" Specifies the position in the text at which the insert cursor is located. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextSetString 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextSetString\fP \- A Text function that sets the string value .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextSetString (\fBwidget, value\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; char \fB* value\fI; .wH .fi .ne 12 .iE .sE .SH DESCRIPTION .fi \fIXmTextSetString\fP sets the string value of the Text widget. This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. It also sets the insertion cursor position to the beginning of the string and calls the widget's \fIXmNmotionVerifyCallback\fP callbacks. .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBvalue\fP" Specifies the character pointer to the string value and places the string into the text edit window .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP and \fIXmTextSetStringWcs(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextSetStringWcs 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextSetStringWcs\fP \- A Text function that sets a wide character string value .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextSetStringWcs (\fBwidget, wcstring\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; wchar_t *\fBwcstring\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTextSetStringWcs\fP sets the wide character string value of the Text widget. This routine calls the widget's \fIXmNvalueChangedCallback\fP and verification callbacks, either \fIXmNmodifyVerifyCallback\fP or \fIXmNmodifyVerifyCallbackWcs\fP, or both. If both verification callback lists are registered, the procedures of the \fIXmNmodifyVerifyCallback\fP list are executed first and the resulting data is passed to the \fIXmNmodifyVerifyCallbackWcs\fP callbacks. It also sets the insertion cursor position to the beginning of the string and calls the widget's \fIXmNmotionVerifyCallback\fP callbacks. .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBvalue\fP" Specifies the wide character string value and places the string into the text edit window. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP and \fIXmTextSetString(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextSetTopCharacter 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextSetTopCharacter\fP \- A Text function that sets the position of the first character displayed .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextSetTopCharacter (\fBwidget, top_character\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmTextPosition \fBtop_character\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextSetTopCharacter\fP sets the position of the text at the top of the Text widget. If the \fIXmNeditMode\fP is \fIXmMULTI_LINE_EDIT\fP, the line of text that contains \fBtop_character\fP is displayed at the top of the widget without shifting the text left or right. .P .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBtop_character\fP" Specifies the position in the text to display at the top of the widget. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextShowPosition 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextShowPosition\fP \- A Text function that forces text at a given position to be displayed .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTextShowPosition (\fBwidget, position\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XmTextPosition \fBposition\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextShowPosition\fP forces text at the specified position to be displayed. If the \fIXmNautoShowCursorPosition\fP resource is True, the application should also set the insert cursor to this position. .P .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBposition\fP" Specifies the character position to be displayed. This is an integer number of characters from the beginning of the text buffer. The first character position is 0. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTextXYToPos 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTextXYToPos\fP \- A Text function that accesses the character position nearest an x and y position .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu XmTextPosition XmTextXYToPos (\fBwidget, x, y\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Position \fBx\fI; Position \fBy\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTextXYToPos\fP accesses the character position nearest to the specified x and y position, relative to the upper left corner of the Text widget. .P .IP "\fBwidget\fP" Specifies the Text widget ID .IP "\fBx\fP" Specifies the x position, relative to the upper left corner of the widget. .IP "\fBy\fP" Specifies the y position, relative to the upper left corner of the widget. .PP For a complete definition of Text and its associated resources, see \fIXmText(3X)\fP. .SH RETURN VALUE Returns the character position in the text nearest the x and y position specified. This is an integer number of characters from the beginning of the buffer. The first character position is 0. .SH RELATED INFORMATION .na \fIXmText(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmToggleButton 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmToggleButton\fP \- The ToggleButton widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi ToggleButton sets nontransitory state data within an application. Usually this widget consists of an indicator (square or diamond or circle) with either text or a pixmap on one side of it. However, it can also consist of just text or a pixmap without the indicator. .PP The toggle graphics display a \fI1-of-many\fP or \fIN-of-many\fP selection state. When a toggle indicator is displayed, a square with or without a check mark indicator shows an \fIN-of-many\fP selection state and a diamond or a circle indicator shows a \fI1-of-many\fP selection state. .PP ToggleButton implies a selected or unselected state. In the case of a label and an indicator, an empty indicator (square or diamond or circle shaped) indicates that ToggleButton is unselected, and a filled indicator shows that it is selected. The indicator may be filled with a check mark or the highlight color. In the case of a pixmap toggle, different pixmaps are used to display the selected/unselected states. .PP .ne 10 The default behavior associated with a ToggleButton in a menu depends on the type of menu system in which it resides. By default, \fIBSelect\fP controls the behavior of the ToggleButton. In addition, \fIBMenu\fP controls the behavior of the ToggleButton if it resides in a Menu system. The actual mouse button used is determined by its RowColumn parent. .PP To accommodate the toggle indicator when created, Label's resource \fIXmNmarginLeft\fP may be increased. .SS "Classes" ToggleButton inherits behavior and resources from \fICore\fP, \fIXmPrimitive\fP, and \fIXmLabel\fP Classes. .PP The class pointer is \fIxmToggleButtonWidgetClass\fP. .PP The class name is \fIXmToggleButton\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmToggleButton Resource Set Name Class Type Default Access _ XmNarmCallback XmCArmCallback XtCallbackList NULL C XmNdisarmCallback XmCDisarmCallback XtCallbackList NULL C XmNfillOnSelect XmCFillOnSelect Boolean dynamic CSG XmNindicatorOn XmCIndicatorOn Boolean True CSG XmNindicatorSize XmCIndicatorSize Dimension dynamic CSG XmNindicatorType XmCIndicatorType unsigned char dynamic CSG XmNselectColor XmCSelectColor Pixel dynamic CSG XmNselectInsensitivePixmap XmCSelectInsensitivePixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNselectPixmap XmCSelectPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNset XmCSet Boolean False CSG XmNspacing XmCSpacing Dimension 4 CSG XmNvalueChangedCallback XmCValueChangedCallback XtCallbackList NULL C XmNvisibleWhenOff XmCVisibleWhenOff Boolean dynamic CSG .TE .KE .in .sp 1 .wH .in .IP "\fIXmNarmCallback\fP" Specifies the list of callbacks called when the ToggleButton is armed. To arm this widget, press the active mouse button while the pointer is inside the ToggleButton. For this callback, the reason is \fIXmCR_ARM\fP. .IP "\fIXmNdisarmCallback\fP" Specifies the list of callbacks called when ToggleButton is disarmed. To disarm this widget, press and release the active mouse button while the pointer is inside the ToggleButton. This widget is also disarmed when the user moves out of the widget and releases the mouse button when the pointer is outside the widget. For this callback, the reason is \fIXmCR_DISARM\fP. .IP "\fIXmNfillOnSelect\fP" Fills the indicator with the color specified in \fIXmNselectColor\fP and switches the top and bottom shadow colors when set to True. Otherwise, it switches only the top and bottom shadow colors. The default is set to the value of \fIXmNindicatorOn\fP. When \fIXmNindicatorOn\fP is False, and \fIXmNfillOnSelect\fP is set explicitly to True, the background is filled with the color specified by \fIXmNselectColor\fP. .IP "\fIXmNindicatorOn\fP" Specifies that a toggle indicator is drawn to one side of the toggle text or pixmap when set to True. When set to False, no space is allocated for the indicator, and it is not displayed. If \fIXmNindicatorOn\fP is True, the indicator shadows are switched when the button is selected or unselected, but, any shadows around the entire widget are not switched. However, if \fIXmNindicatorOn\fP is False, any shadows around the entire widget are switched when the toggle is selected or unselected. .IP "\fIXmNindicatorSize\fP" Sets the size of the indicator. If no value is specified, the size of the indicator is based on the size of the label string or pixmap. If the label string or pixmap changes, the size of the indicator is recomputed based on the size of the label string or pixmap. Once a value has been specified for \fIXmNindicatorSize\fP, the indicator has that size, regardless of the size of the label string or pixmap, until a new value is specified. .IP "\fIXmNindicatorType\fP" Specifies if the indicator is a \fI1-of\fP or \fIN-of\fP indicator. For the \fI1-of\fP indicator, the value is \fIXmONE_OF_MANY\fP. For the \fIN-of\fP indicator, the value is \fIXmN_OF_MANY\fP. .IP The look of the ToggleButton visual is controlled by the XmDisplay resource \fIenableToggleVisual\fP. The \fIenableToggleVisual\fP resource defaults to False with the following ToggleButton visuals: .wH .rS .TP \(bu \fIXmONE_OF_MANY\fP - a shadowed diamond .TP \(bu \fIXmN_OF_MANY\fP - a shadowed square .wH .rE .nL .ne 6 .IP When \fIenableToggleVisual\fP is True, the ToggleButton visuals are: .wH .rS .TP \(bu \fIXmONE_OF_MANY\fP - a shadowed circle .TP \(bu \fIXmN_OF_MANY\fP - a shadowed square with a check mark when set .wH .rE .nL .ne 6 .IP This resource specifies only the visuals and does not enforce the behavior. When the ToggleButton is in a RadioBox, the default is \fIXmONE_OF_MANY\fP; otherwise, the default is \fIXmN_OF_MANY\fP. .IP "\fIXmNselectColor\fP" Allows the application to specify what color fills the center of the indicator when it is set. If this color is the same as either the top or the bottom shadow color of the indicator, a one-pixel-wide margin is left between the shadows and the fill; otherwise, it is filled completely. This resource's default for a color display depends on the value of the XmDisplay resource \fIenableToggleColor\fP. If \fIenableToggleColor\fP is False (the default), then is a color between the background and the bottom shadow color is chosen. When \fIenableToggleColor\fP is True, then the select color is the highlight color for the widget. For a monochrome display, the select color is set to the foreground color. To set the background of the button to \fIXmNselectColor\fP when \fIXmNindicatorOn\fP is False, the value of \fIXmNfillOnSelect\fP must be explicitly set to True. .IP "\fIXmNselectInsensitivePixmap\fP" Specifies a pixmap used as the button face when the ToggleButton is selected and the button is insensitive if the Label resource \fIXmNlabelType\fP is set to \fIXmPIXMAP\fP. If the ToggleButton is unselected and the button is insensitive, the pixmap in \fIXmNlabelInsensitivePixmap\fP is used as the button face. If no value is specified for \fIXmNlabelInsensitivePixmap\fP, that resource is set to the value specified for \fIXmNselectInsensitivePixmap\fP. .IP "\fIXmNselectPixmap\fP" Specifies the pixmap to be used as the button face if \fIXmNlabelType\fP is \fIXmPIXMAP\fP and the ToggleButton is selected. When the ToggleButton is unselected, the pixmap specified in Label's \fIXmNlabelPixmap\fP is used. If no value is specified for \fIXmNlabelPixmap\fP, that resource is set to the value specified for \fIXmNselectPixmap\fP. .IP "\fIXmNset\fP" Represents the state of the ToggleButton. A value of false indicates that the ToggleButton is not set. A value of true indicates that the ToggleButton is set. Setting this resource sets the state of the ToggleButton. .IP "\fIXmNspacing\fP" Specifies the amount of spacing between the toggle indicator and the toggle label (text or pixmap). .IP "\fIXmNvalueChangedCallback\fP" Specifies the list of callbacks called when the ToggleButton value is changed. To change the value, press and release the active mouse button while the pointer is inside the ToggleButton. This action also causes this widget to be disarmed. For this callback, the reason is \fIXmCR_VALUE_CHANGED\fP. .IP "\fIXmNvisibleWhenOff\fP" Indicates that the toggle indicator is visible in the unselected state when the Boolean value is True. When the ToggleButton is in a menu, the default value is False. When the ToggleButton is in a RadioBox, the default value is True. .SS "Inherited Resources" ToggleButton inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmLabel Resource Set Name Class Type Default Access _ XmNaccelerator XmCAccelerator String NULL CSG XmNacceleratorText XmCAcceleratorText XmString NULL CSG XmNalignment XmCAlignment unsigned char dynamic CSG XmNfontList XmCFontList XmFontList dynamic CSG XmNlabelInsensitivePixmap XmCLabelInsensitivePixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelPixmap XmCLabelPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelString XmCXmString XmString dynamic CSG XmNlabelType XmCLabelType unsigned char XmSTRING CSG XmNmarginBottom XmCMarginBottom Dimension dynamic CSG XmNmarginHeight XmCMarginHeight Dimension 2 CSG XmNmarginLeft XmCMarginLeft Dimension dynamic CSG XmNmarginRight XmCMarginRight Dimension 0 CSG XmNmarginTop XmCMarginTop Dimension dynamic CSG XmNmarginWidth XmCMarginWidth Dimension 2 CSG .wH .tH XmNmnemonic XmCMnemonic KeySym NULL CSG XmNmnemonicCharSet XmCMnemonicCharSet String XmFONTLIST_DEFAULT_TAG CSG XmNrecomputeSize XmCRecomputeSize Boolean True CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CSG .TE .KE .in .sp 1 .wH .in .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmPrimitive Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNforeground XmCForeground Pixel dynamic CSG XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic CSG XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG .wH .tH XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension dynamic CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Core Resource Set Name Class Type Default Access _ XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG XmNancestorSensitive XmCSensitive Boolean dynamic G XmNbackground XmCBackground Pixel dynamic CSG XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNcolormap XmCColormap Colormap dynamic CG XmNdepth XmCDepth int dynamic CG XmNdestroyCallback XmCCallback XtCallbackList NULL C XmNheight XmCHeight Dimension dynamic CSG XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG XmNscreen XmCScreen Screen * dynamic CG .wH .tH XmNsensitive XmCSensitive Boolean True CSG XmNtranslations XmCTranslations XtTranslations dynamic CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .wH .in .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.50i .nf typedef struct { int \fBreason\fI; \fIXEvent \fB* event\fI; \fIint \fBset\fI; } XmToggleButtonCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback .IP "\fBset\fP" Reflects the ToggleButton's current state when the callback occurred, either True (selected) or False (unselected) .SS "Translations" .ne 12 XmToggleButton includes translations from Primitive. Additional XmToggleButton translations for buttons not in a menu system are listed below. These translations may not directly correspond to a translation table. .PP Note that altering translations in \fI#override\fP or \fI#augment\fP mode is undefined. .iS .ta 1.5i .nf BDragPress: ProcessDrag() BSelect Press: Arm() BSelect Release: Select() Disarm() KHelp: Help() KSelect: ArmAndActivate() .wH .fi .iE .PP XmToggleButton inherits menu traversal translations from XmLabel. Additional XmToggleButton translations for ToggleButtons in a menu system are listed below. In a menu system, \fIBMenu\fP also performs the \fIBSelect\fP actions. These translations may not directly correspond to a translation table. .iS .ta 1.5i .nf BSelect Press: BtnDown() BSelect Release: BtnUp() KHelp: Help() KActivate: ArmAndActivate() KSelect: ArmAndActivate() MAny KCancel: MenuShellPopdownOne() .wH .fi .iE .P .SS "Action Routines" The XmToggleButton action routines are described below: .IP "\fIArm()\fP:" If the button was previously unset, this action does the following: If \fIXmNindicatorOn\fP is True, it draws the indicator shadow so that the indicator looks pressed; if \fIXmNfillOnSelect\fP is True, it fills the indicator with the color specified by \fIXmNselectColor\fP. If \fIXmNindicatorOn\fP is False, it draws the button shadow so that the button looks pressed. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNselectPixmap\fP is used as the button face. Calls the \fIXmNarmCallback\fP callbacks. .ne 8 .IP If the button was previously set, this action does the following: If both \fIXmNindicatorOn\fP and \fIXmNvisibleWhenOff\fP are True, it draws the indicator shadow so that the indicator looks raised; if \fIXmNfillOnSelect\fP is True, it fills the indicator with the background color. If \fIXmNindicatorOn\fP is False, it draws the button shadow so that the button looks raised. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNlabelPixmap\fP is used as the button face. Calls the \fIXmNarmCallback\fP callbacks. .IP "\fIArmAndActivate()\fP:" If the ToggleButton was previously set, unsets it; if the ToggleButton was previously unset, sets it. .IP In a menu, does the following: Unposts all menus in the menu hierarchy. Unless the button is already armed, calls the \fIXmNarmCallback\fP callbacks. Calls the \fIXmNvalueChangedCallback\fP and \fIXmNdisarmCallback\fP callbacks. .IP Outside a menu, if the button was previously unset, this action does the following: If \fIXmNindicatorOn\fP is True, it draws the indicator shadow so that the indicator looks pressed; if \fIXmNfillOnSelect\fP is True, it fills the indicator with the color specified by \fIXmNselectColor\fP. If \fIXmNindicatorOn\fP is False, it draws the button shadow so that the button looks pressed. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNselectPixmap\fP is used as the button face. Calls the \fIXmNarmCallback\fP, \fIXmNvalueChangedCallback\fP, and \fIXmNdisarmCallback\fP callbacks. .IP Outside a menu, if the button was previously set, this action does the following: If both \fIXmNindicatorOn\fP and \fIXmNvisibleWhenOff\fP are True, it draws the indicator shadow so that the indicator looks raised; if \fIXmNfillOnSelect\fP is True, it fills the indicator with the background color. If \fIXmNindicatorOn\fP is False, it draws the button shadow so that the button looks raised. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNlabelPixmap\fP is used as the button face. Calls the \fIXmNarmCallback\fP, \fIXmNvalueChangedCallback\fP, and \fIXmNdisarmCallback\fP callbacks. .IP "\fIBtnDown()\fP:" This action unposts any menus posted by the ToggleButton's parent menu, disables keyboard traversal for the menu, and enables mouse traversal for the menu. It draws the shadow in the armed state and, unless the button is already armed, calls the \fIXmNarmCallback\fP callbacks. .IP "\fIBtnUp()\fP:" This action unposts all menus in the menu hierarchy. If the ToggleButton was previously set, unsets it; if the ToggleButton was previously unset, sets it. It calls the \fIXmNvalueChangedCallback\fP callbacks and then the \fIXmNdisarmCallback\fP callbacks. .IP "\fIDisarm()\fP:" Calls the callbacks for \fIXmNdisarmCallback\fP. .P .IP "\fIHelp()\fP:" In a Pulldown or Popup MenuPane, unposts all menus in the menu hierarchy and restores keyboard focus to the widget that had the focus before the menu system was entered. Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\fIMenuShellPopdownOne()\fP:" In a toplevel Pulldown MenuPane from a MenuBar, unposts the menu, disarms the MenuBar CascadeButton and the MenuBar, and restores keyboard focus to the widget that had the focus before the MenuBar was entered. In other Pulldown MenuPanes, unposts the menu. .IP In a Popup MenuPane, unposts the menu and restores keyboard focus to the widget from which the menu was posted. .IP "\fIProcessDrag()\fP:" Drags the contents of a ToggleButton label, identified by pressing \fIBDrag\fP. This action creates a DragContext object whose \fIXmNexportTargets\fP resource is set to "COMPOUND_TEXT" for a label type of \fIXmSTRING\fP; otherwise, "PIXMAP" if the label type is \fIXmPIXMAP\fP. This action is undefined for ToggleButtons used in a menu system. .IP This action is disabled if the XmDisplay's \fIenableUnselectableDrag\fP resource is True. .nL .ne 6 .IP "\fISelect()\fP:" If the pointer is within the button, takes the following actions: If the button was previously unset, sets it; if the button was previously set, unsets it. Calls the \fIXmNvalueChangedCallback\fP callbacks. .SS "Additional Behavior" This widget has the additional behavior described below: .IP "\fI\fP:" In a menu, if keyboard traversal is enabled, this action does nothing. Otherwise, it draws the shadow in the armed state and calls the \fIXmNarmCallback\fP callbacks. .IP If the ToggleButton is not in a menu and the cursor leaves and then reenters the ToggleButton's window while the button is pressed, this action restores the button's armed appearance. .P .IP "\fI\fP:" In a menu, if keyboard traversal is enabled, this action does nothing. Otherwise, it draws the shadow in the unarmed state and calls the \fIXmNdisarmCallback\fP callbacks. .IP If the ToggleButton is not in a menu and the cursor leaves the ToggleButton's window while the button is pressed, this action restores the button's unarmed appearance. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .nL .ne 15 .SH RELATED INFORMATION .na \fICore(3X)\fP, \fIXmCreateRadioBox(3X)\fP, \fIXmCreateToggleButton(3X)\fP, \fIXmDisplay(3x)\fP, \fIXmLabel(3X)\fP, \fIXmPrimitive(3X)\fP, \fIXmRowColumn(3X)\fP, \fIXmToggleButtonGetState(3X)\fP, and \fIXmToggleButtonSetState(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmToggleButtonGadget 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmToggleButtonGadget\fP \- The ToggleButtonGadget widget class .SH SYNOPSIS .nf .sS .iS \&#include .iE .sE .SH DESCRIPTION .fi ToggleButtonGadget sets nontransitory state data within an application. Usually this gadget consists of an indicator (square or diamond or circle) with either text or a pixmap on one side of it. However, it can also consist of just text or a pixmap without the indicator. .PP The toggle graphics display a \fI1-of-many\fP or \fIN-of-many\fP selection state. When a toggle indicator is displayed, a square with or without a check mark indicator shows an \fIN-of-many\fP selection state and a diamond or a circle indicator shows a \fI1-of-many\fP selection state. .PP ToggleButtonGadget implies a selected or unselected state. In the case of a label and an indicator, an empty indicator (square or diamond or circle shaped) indicates that ToggleButtonGadget is unselected, and a filled indicator shows that it is selected. The indicator may be filled with a check mark or the highlight color. In the case of a pixmap toggle, different pixmaps are used to display the selected/unselected states. .PP .ne 7 The default behavior associated with a ToggleButtonGadget in a menu depends on the type of menu system in which it resides. By default, \fIBSelect\fP controls the behavior of the ToggleButtonGadget. In addition, \fIBMenu\fP controls the behavior of the ToggleButtonGadget if it resides in a Menu system. The actual mouse button used is determined by its RowColumn parent. .PP To accommodate the toggle indicator when created, Label's resource \fIXmNmarginLeft\fP may be increased. .SS "Classes" ToggleButtonGadget inherits behavior and resources from \fIObject\fP, \fIRectObj\fP, \fIXmGadget\fP and \fIXmLabelGadget\fP classes. .PP The class pointer is \fIxmToggleButtonGadgetClass\fP. .PP The class name is \fIXmToggleButtonGadget\fP. .SS "New Resources" The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the \fIXmN\fP or \fIXmC\fP prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the \fIXm\fP prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the access column indicate if the given resource can be set at creation time (C), set by using \fIXtSetValues\fP (S), retrieved by using \fIXtGetValues\fP (G), or is not applicable (N/A). .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmToggleButtonGadget Resource Set Name Class Type Default Access _ XmNarmCallback XmCArmCallback XtCallbackList NULL C XmNdisarmCallback XmCDisarmCallback XtCallbackList NULL C XmNfillOnSelect XmCFillOnSelect Boolean dynamic CSG XmNindicatorOn XmCIndicatorOn Boolean True CSG XmNindicatorSize XmCIndicatorSize Dimension dynamic CSG XmNindicatorType XmCIndicatorType unsigned char dynamic CSG XmNselectColor XmCSelectColor Pixel dynamic CSG XmNselectInsensitivePixmap XmCSelectInsensitivePixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNselectPixmap XmCSelectPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNset XmCSet Boolean False CSG XmNspacing XmCSpacing Dimension 4 CSG XmNvalueChangedCallback XmCValueChangedCallback XtCallbackList NULL C XmNvisibleWhenOff XmCVisibleWhenOff Boolean dynamic CSG .TE .KE .in .sp 1 .nL .ne 10 .IP "\fIXmNarmCallback\fP" Specifies a list of callbacks that is called when the ToggleButtonGadget is armed. To arm this gadget, press the active mouse button while the pointer is inside the ToggleButtonGadget. For this callback, the reason is \fIXmCR_ARM\fP. .IP "\fIXmNdisarmCallback\fP" Specifies a list of callbacks called when ToggleButtonGadget is disarmed. To disarm this gadget, press and release the active mouse button while the pointer is inside the ToggleButtonGadget. The gadget is also disarmed when the user moves out of the gadget and releases the mouse button when the pointer is outside the gadget. For this callback, the reason is \fIXmCR_DISARM\fP. .IP "\fIXmNfillOnSelect\fP" Fills the indicator with the color specified in \fIXmNselectColor\fP and switches the top and bottom shadow colors when set to True. Otherwise, it switches only the top and bottom shadow colors. The default is set to the value of \fIXmNindicatorOn\fP. When \fIXmNindicatorOn\fP is False, and \fIXmNfillOnSelect\fP is set explicitly to True, the background is filled with the color specified by \fIXmNselectColor\fP. .IP "\fIXmNindicatorOn\fP" Specifies that a toggle indicator is drawn to one side of the toggle text or pixmap when set to True. When set to False, no space is allocated for the indicator, and it is not displayed. If \fIXmNindicatorOn\fP is True, the indicator shadows are switched when the button is selected or unselected, but any shadows around the entire gadget are not switched. However, if \fIXmNindicatorOn\fP is False, any shadows around the entire gadget are switched when the toggle is selected or unselected. .IP "\fIXmNindicatorSize\fP" Sets the size of the indicator. If no value is specified, the size of the indicator is based on the size of the label string or pixmap. If the label string or pixmap changes, the size of the indicator is recomputed based on the size of the label string or pixmap. Once a value has been specified for \fIXmNindicatorSize\fP, the indicator has that size, regardless of the size of the label string or pixmap, until a new value is specified. .IP "\fIXmNindicatorType\fP" Specifies if the indicator is a \fI1-of\fP or an \fIN-of\fP indicator. For the \fI1-of\fP indicator, the value is \fIXmONE_OF_MANY\fP. For the \fIN-of\fP indicator, the value is \fIXmN_OF_MANY\fP. .IP The look of the ToggleButtonGadget visual is controlled by the XmDisplay resource \fIenableToggleVisual\fP. The \fIenableToggleVisual\fP resource defaults to False with the following ToggleButtonGadget visuals: .wH .rS .TP \(bu \fIXmONE_OF_MANY\fP - a shadowed diamond .TP \(bu \fIXmN_OF_MANY\fP - a shadowed square .wH .rE .nL .ne 6 .IP When \fIenableToggleVisual\fP is True, the ToggleButtonGadget visuals are: .wH .rS .TP \(bu \fIXmONE_OF_MANY\fP - a shadowed circle .TP \(bu \fIXmN_OF_MANY\fP - a shadowed square with a check mark when set .wH .rE .nL .ne 6 .IP This resource specifies only the visuals and does not enforce the behavior. When the ToggleButtonGadget is in a RadioBox, the default is \fIXmONE_OF_MANY\fP; otherwise, the default is \fIXmN_OF_MANY\fP. .IP "\fIXmNselectColor\fP" Allows the application to specify what color fills the center of the square or diamond-shaped indicator when it is set. If this color is the same as either the top or the bottom shadow color of the indicator, a one-pixel-wide margin is left between the shadows and the fill; otherwise, it is filled completely. This resource's default for a color display depends on the value of the XmDisplay resource \fIenableToggleColor\fP. If \fIenableToggleColor\fP is False (the default), then is a color between the background and the bottom shadow color is chosen. When \fIenableToggleColor\fP is True, then the select color is the highlight color for the gadget. For a monochrome display, the default is set to the foreground color. To set the background of the button to \fIXmNselectColor\fP when \fIXmNindicatorOn\fP is False, the value of \fIXmNfillOnSelect\fP must be explicitly set to True. .IP "\fIXmNselectInsensitivePixmap\fP" Specifies a pixmap used as the button face when the ToggleButtonGadget is selected and the button is insensitive if the LabelGadget resource \fIXmNlabelType\fP is \fIXmPIXMAP\fP. If the ToggleButtonGadget is unselected and the button is insensitive, the pixmap in \fIXmNlabelInsensitivePixmap\fP is used as the button face. If no value is specified for \fIXmNlabelInsensitivePixmap\fP, that resource is set to the value specified for \fIXmNselectInsensitivePixmap\fP. .IP "\fIXmNselectPixmap\fP" Specifies the pixmap to be used as the button face if \fIXmNlabelType\fP is \fIXmPIXMAP\fP and the ToggleButtonGadget is selected. When the ToggleButtonGadget is unselected, the pixmap specified in LabelGadget's \fIXmNlabelPixmap\fP is used. If no value is specified for \fIXmNlabelPixmap\fP, that resource is set to the value specified for \fIXmNselectPixmap\fP. .IP "\fIXmNset\fP" Represents the state of the ToggleButton. A value of false indicates that the ToggleButton is not set. A value of true indicates that the ToggleButton is set. Setting this resource sets the state of the ToggleButton. .IP "\fIXmNspacing\fP" Specifies the amount of spacing between the toggle indicator and the toggle label (text or pixmap). .nL .ne 6 .IP "\fIXmNvalueChangedCallback\fP" Specifies a list of callbacks called when the ToggleButtonGadget value is changed. To change the value, press and release the active mouse button while the pointer is inside the ToggleButtonGadget. This action also causes the gadget to be disarmed. For this callback, the reason is \fIXmCR_VALUE_CHANGED\fP. .IP "\fIXmNvisibleWhenOff\fP" Indicates that the toggle indicator is visible in the unselected state when the Boolean value is True. When the ToggleButtonGadget is in a menu, the default value is False. When the ToggleButtonGadget is in a RadioBox, the default value is True. .nL .ne 6 .SS "Inherited Resources" ToggleButtonGadget inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. .P .wH .in 0 .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmLabelGadget Resource Set Name Class Type Default Access _ XmNaccelerator XmCAccelerator String NULL CSG XmNacceleratorText XmCAcceleratorText XmString NULL CSG XmNalignment XmCAlignment unsigned char dynamic CSG XmNfontList XmCFontList XmFontList dynamic CSG XmNlabelInsensitivePixmap XmCLabelInsensitivePixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelPixmap XmCLabelPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG XmNlabelString XmCXmString XmString dynamic CSG XmNlabelType XmCLabelType unsigned char XmSTRING CSG XmNmarginBottom XmCMarginBottom Dimension dynamic CSG XmNmarginHeight XmCMarginHeight Dimension 2 CSG XmNmarginLeft XmCMarginLeft Dimension dynamic CSG XmNmarginRight XmCMarginRight Dimension 0 CSG XmNmarginTop XmCMarginTop Dimension dynamic CSG XmNmarginWidth XmCMarginWidth Dimension 2 CSG .wH .tH XmNmnemonic XmCMnemonic KeySym NULL CSG XmNmnemonicCharSet XmCMnemonicCharSet String dynamic CSG XmNrecomputeSize XmCRecomputeSize Boolean True CSG XmNstringDirection XmCStringDirection XmStringDirection dynamic CSG .TE .KE .in .sp 1 .wH .in .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. XmGadget Resource Set Name Class Type Default Access _ XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic G XmNhelpCallback XmCCallback XtCallbackList NULL C XmNhighlightColor XmCHighlightColor Pixel dynamic G XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG XmNhighlightThickness XmCHighlightThickness Dimension 2 CSG XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG XmNshadowThickness XmCShadowThickness Dimension dynamic CSG XmNtopShadowColor XmCTopShadowColor Pixel dynamic G XmNtraversalOn XmCTraversalOn Boolean True CSG XmNunitType XmCUnitType unsigned char dynamic CSG XmNuserData XmCUserData XtPointer NULL CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. RectObj Resource Set Name Class Type Default Access _ XmNancestorSensitive XmCSensitive Boolean dynamic G XmNborderWidth XmCBorderWidth Dimension 0 CSG XmNheight XmCHeight Dimension dynamic CSG XmNsensitive XmCSensitive Boolean True CSG XmNwidth XmCWidth Dimension dynamic CSG XmNx XmCPosition Position 0 CSG XmNy XmCPosition Position 0 CSG .TE .KE .in .sp 1 .P .sp 1 .in 0 .KS .TS center; cBp7 ssss lBp6 lBp6 lBp6 lBp6 lBp6 lp6 lp6 lp6 lp6 lp6. Object Resource Set Name Class Type Default Access _ XmNdestroyCallback XmCCallback XtCallbackList NULL C .TE .KE .in .sp 1 .SS "Callback Information" A pointer to the following structure is passed to each callback: .sS .iS .ta .25i 1.50i .nf typedef struct { int \fBreason\fI; \fIXEvent \fB* event\fI; \fIint \fBset\fI; } XmToggleButtonCallbackStruct; .iE .sE .wH .fi .IP "\fBreason\fP" Indicates why the callback was invoked .IP "\fBevent\fP" Points to the \fIXEvent\fP that triggered the callback .IP "\fBset\fP" Reflects the ToggleButtonGadget's current state when the callback occurred, either True (selected) or False (unselected) .SS "Behavior" XmToggleButtonGadget includes behavior from XmGadget. XmToggleButtonGadget includes menu traversal behavior from XmLabelGadget. Additional XmToggleButtonGadget behavior is described below: .IP "\fIBDrag\ Press\fP:" Drags the contents of a ToggleButtonGadget label, identified by pressing \fIBDrag\fP. This action creates a DragContext object whose \fIXmNexportTargets\fP resource is set to "COMPOUND_TEXT" for a label type of \fIXmSTRING\fP; otherwise, "PIXMAP" if the label type is \fIXmPIXMAP\fP. This action is undefined for ToggleButtonGadgets used in a menu system. .IP This action is disabled if the XmDisplay's \fIenableUnselectableDrag\fP resource is True. .IP "\fIBSelect\ Press\fP:" In a menu, this action unposts any menus posted by the ToggleButtonGadget's parent menu, disables keyboard traversal for the menu, and enables mouse traversal for the menu. It draws the shadow in the armed state and, unless the button is already armed, calls the \fIXmNarmCallback\fP callbacks. .IP Outside a menu, if the button was previously unset, this action does the following: If \fIXmNindicatorOn\fP is True, it draws the indicator shadow so that the indicator looks pressed; if \fIXmNfillOnSelect\fP is True, it fills the indicator with the color specified by \fIXmNselectColor\fP. If \fIXmNindicatorOn\fP is False, it draws the button shadow so that the button looks pressed. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNselectPixmap\fP is used as the button face. Calls the \fIXmNarmCallback\fP callbacks. .IP Outside a menu, if the button was previously set, this action does the following: If both \fIXmNindicatorOn\fP and \fIXmNvisibleWhenOff\fP are True, it draws the indicator shadow so that the indicator looks raised; if \fIXmNfillOnSelect\fP is True, it fills the indicator with the background color. If \fIXmNindicatorOn\fP is False, it draws the button shadow so that the button looks raised. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNlabelPixmap\fP is used as the button face. Calls the \fIXmNarmCallback\fP callbacks. .IP "\fIBSelect\ Release\fP:" In a menu, this action does the following: It unposts all menus in the menu hierarchy. If the ToggleButtonGadget was previously set, unsets it; if the ToggleButtonGadget was previously unset, sets it. It calls the \fIXmNvalueChangedCallback\fP callbacks and then the \fIXmNdisarmCallback\fP callbacks. .IP If the button is outside a menu and the pointer is within the button, this action does the following: If the button was previously unset, sets it; if the button was previously set, unsets it. Calls the \fIXmNvalueChangedCallback\fP callbacks. .IP If the button is outside a menu, calls the \fIXmNdisarmCallback\fP callbacks. .IP "\fIKHelp\fP:" In a Pulldown or Popup MenuPane, unposts all menus in the menu hierarchy and, when the shell's keyboard focus policy is \fIXmEXPLICT\fP, restores keyboard focus to the widget that had the focus before the menu system was entered. Calls the callbacks for \fIXmNhelpCallback\fP if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them. .IP "\*KActivate\fP:" In a menu, does the following: unposts all menus in the menu hierarchy; unless the button is already armed, calls the \fIXmNarmCallback\fP callbacks; and calls the \fIXmNvalueChangedCallback\fP and \fIXmNdisarmCallback\fP callbacks. Outside a menu, if the parent is a manager, passes the event to the parent. .IP "\fIKSelect\fP:" If the ToggleButtonGadget was previously set, unsets it; if the ToggleButtonGadget was previously unset, sets it. .IP In a menu, does the following: Unposts all menus in the menu hierarchy. Unless the button is already armed, calls the \fIXmNarmCallback\fP callbacks. Calls the \fIXmNvalueChangedCallback\fP and \fIXmNdisarmCallback\fP callbacks. .IP Outside a menu, if the button was previously unset, this action does the following: If \fIXmNindicatorOn\fP is True, it draws the indicator shadow so that the indicator looks pressed; if \fIXmNfillOnSelect\fP is True, it fills the indicator with the color specified by \fIXmNselectColor\fP. If \fIXmNindicatorOn\fP is False, it draws the button shadow so that the button looks pressed. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNselectPixmap\fP is used as the button face. Calls the \fIXmNarmCallback\fP, \fIXmNvalueChangedCallback\fP, \fIXmNdisarmCallback\fP callbacks. .IP Outside a menu, if the button was previously set, this action does the following: If both \fIXmNindicatorOn\fP and \fIXmNvisibleWhenOff\fP are True, it draws the indicator shadow so that the indicator looks raised; if \fIXmNfillOnSelect\fP is True, it fills the indicator with the background color. If \fIXmNindicatorOn\fP is False, it draws the button shadow so that the button looks raised. If \fIXmNlabelType\fP is \fIXmPIXMAP\fP, the \fIXmNlabelPixmap\fP is used as the button face. Calls the \fIXmNarmCallback\fP, \fIXmNvalueChangedCallback\fP, and \fIXmNdisarmCallback\fP callbacks. .nL .ne 10 .IP "\fIMAny\ KCancel\fP:" In a toplevel Pulldown MenuPane from a MenuBar, unposts the menu, disarms the MenuBar CascadeButton and the MenuBar, and, when the shell's keyboard focus policy is \fIXmEXPLICT\fP, restores keyboard focus to the widget that had the focus before the MenuBar was entered. In other Pulldown MenuPanes, unposts the menu. Outside a menu, if the parent is a manager, this action passes the event to the parent. .IP In a Popup MenuPane, unposts the menu and restores keyboard focus to the widget from which the menu was posted. .IP "\fI\fP:" In a menu, if keyboard traversal is enabled, this action does nothing. Otherwise, it draws the shadow in the armed state and calls the \fIXmNarmCallback\fP callbacks. .IP If the ToggleButtonGadget is not in a menu and the cursor leaves and then reenters the ToggleButtonGadget while the button is pressed, this action restores the button's armed appearance. .IP "\fI\fP:" In a menu, if keyboard traversal is enabled, this action does nothing. Otherwise, it draws the shadow in the unarmed state and calls the \fIXmNdisarmCallback\fP callbacks. .IP If the ToggleButtonGadget is not in a menu and the cursor leaves the ToggleButtonGadget while the button is pressed, this action restores the button's unarmed appearance. .SS "Virtual Bindings" The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see \fIVirtualBindings(3X)\fP. .ne 10 .nL .ne 10 .SH RELATED INFORMATION .na \fIObject(3X)\fP, \fIRectObj(3X)\fP, \fIXmCreateRadioBox(3X)\fP, \fIXmCreateToggleButtonGadget(3X)\fP, \fIXmDisplay(3X)\fP, \fIXmGadget(3X)\fP, \fIXmLabelGadget(3X)\fP, \fIXmRowColumn(3X)\fP, \fIXmToggleButtonGadgetGetState(3X)\fP, and \fIXmToggleButtonGadgetSetState(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmToggleButtonGadgetGetState 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmToggleButtonGadgetGetState\fP \- A ToggleButtonGadget function that obtains the state of a ToggleButtonGadget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmToggleButtonGadgetGetState (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmToggleButtonGadgetGetState\fP obtains the state of a ToggleButtonGadget. .IP "\fBwidget\fP" Specifies the ToggleButtonGadget ID .PP For a complete definition of ToggleButtonGadget and its associated resources, see \fIXmToggleButtonGadget(3X)\fP. .SH RETURN VALUE Returns True if the button is selected and False if the button is unselected. .SH RELATED INFORMATION .na \fIXmToggleButtonGadget(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmToggleButtonGadgetSetState 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmToggleButtonGadgetSetState\fP \- A ToggleButtonGadget function that sets or changes the current state .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmToggleButtonGadgetSetState (\fBwidget, state, notify\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Boolean \fBstate\fI; Boolean \fBnotify\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmToggleButtonGadgetSetState\fP sets or changes the ToggleButtonGadget's current state. .IP "\fBwidget\fP" Specifies the ToggleButtonGadget widget ID. .IP "\fBstate\fP" Specifies a Boolean value that indicates whether the ToggleButtonGadget state is selected or unselected. If True, the button state is selected; if False, the button state is unselected. .nL .ne 10 .IP "\fBnotify\fP" Indicates whether \fIXmNvalueChangedCallback\fP is called; it can be either True or False. The \fIXmNvalueChangedCallback\fP is only called when this function changes the state of the ToggleButtonGadget. When this argument is True and the ToggleButtonGadget is a child of a RowColumn widget whose \fIXmNradioBehavior\fP is True, setting the ToggleButtonGadget causes other ToggleButton and ToggleButtonGadget children of the RowColumn to be unselected. .PP For a complete definition of ToggleButtonGadget and its associated resources, see \fIXmToggleButtonGadget(3X)\fP. .SH RELATED INFORMATION .na \fIXmToggleButtonGadget(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmToggleButtonGetState 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmToggleButtonGetState\fP \- A ToggleButton function that obtains the state of a ToggleButton .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmToggleButtonGetState (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmToggleButtonGetState\fP obtains the state of a ToggleButton. .IP "\fBwidget\fP" Specifies the ToggleButton widget ID .PP For a complete definition of ToggleButton and its associated resources, see \fIXmToggleButton(3X)\fP. .SH RETURN VALUE Returns True if the button is selected and False if the button is unselected. .SH RELATED INFORMATION .na \fIXmToggleButton(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmToggleButtonSetState 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmToggleButtonSetState\fP \- A ToggleButton function that sets or changes the current state .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmToggleButtonSetState (\fBwidget, state, notify\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Boolean \fBstate\fI; Boolean \fBnotify\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmToggleButtonSetState\fP sets or changes the ToggleButton's current state. .IP "\fBwidget\fP" Specifies the ToggleButton widget ID. .IP "\fBstate\fP" Specifies a Boolean value that indicates whether the ToggleButton state is selected or unselected. If True, the button state is selected; if False, the button state is unselected. .nL .ne 20 .IP "\fBnotify\fP" Indicates whether \fIXmNvalueChangedCallback\fP is called; it can be either True or False. The \fIXmNvalueChangedCallback\fP is only called when this function changes the state of the ToggleButton. When this argument is True and the ToggleButton is a child of a RowColumn widget whose \fIXmNradioBehavior\fP is True, setting the ToggleButton causes other ToggleButton and ToggleButtonGadget children of the RowColumn to be unselected. .PP For a complete definition of ToggleButton and its associated resources, see \fIXmToggleButton(3X)\fP. .SH RELATED INFORMATION .na \fIXmToggleButton(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTrackingEvent 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTrackingEvent\fP \- A Toolkit function that provides a modal interaction .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmTrackingEvent (\fBwidget, cursor, confine_to, event_return\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Cursor \fBcursor\fI; Boolean \fBconfine_to\fI; XEvent *\fBevent_return\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTrackingEvent\fP provides a modal interface for selection of a component. It is intended to support context help. The function grabs the pointer and discards succeeding events until \fIBSelect\fP is released or a key is pressed and then released. The function then returns the widget or gadget that contains the pointer when \fIBSelect\fP is released or a key is released. .PP .IP "\fBwidget\fP" Specifies the widget ID of a widget to use as the basis of the modal interaction. That is, the widget within which the interaction must occur, usually a top level shell. .IP "\fBcursor\fP" Specifies the cursor to be used for the pointer during the interaction. This is a standard X cursor name. .IP "\fBconfine_to\fP" Specifies whether or not the cursor should be confined to \fBwidget\fP. .IP "\fBevent_return\fP" Returns the ButtonRelease or KeyRelease event that causes the function to return. .SH RETURN VALUE Returns the widget or gadget that contains the pointer when \fIBSelect\fP is released or a key is released. If no widget or gadget contains the pointer, the function returns NULL. .SH RELATED INFORMATION .na \fIXmTrackingLocate(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTrackingLocate 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTrackingLocate\fP \- A Toolkit function that provides a modal interaction .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmTrackingLocate (\fBwidget, cursor, confine_to\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; Cursor \fBcursor\fI; Boolean \fBconfine_to\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmTrackingLocate\fP provides a modal interface for selection of a component. It is intended to support context help. The function grabs the pointer and discards succeeding events until \fIBSelect\fP is released or a key is pressed and then released. The function then returns the widget or gadget that contains the pointer when \fIBSelect\fP is released or a key is released. .PP This function is obsolete and exists for compatibility with previous releases. It has been replaced by \fIXmTrackingEvent\fP. .P .IP "\fBwidget\fP" Specifies the widget ID of a widget to use as the basis of the modal interaction. That is, the widget within which the interaction must occur, usually a top level shell. .nL .ne 15 .IP "\fBcursor\fP" Specifies the cursor to be used for the pointer during the interaction. This is a standard X cursor name. .IP "\fBconfine_to\fP" Specifies whether or not the cursor should be confined to \fBwidget\fP .SH RETURN VALUE .PP Returns the widget or gadget that contains the pointer when \fIBSelect\fP is released or a key is released. If no widget or gadget contains the pointer, the function returns NULL. .SH RELATED INFORMATION .na \fIXmTrackingEvent(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmTranslateKey 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmTranslateKey\fP \- The default keycode-to-keysym translator .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu void XmTranslateKey (\fBdisplay, keycode, modifiers, modifiers_return, keysym_return\fI) .ta .5i 1.5i .nf Display *\fBdisplay\fI; KeyCode \fBkeycode\fI; Modifiers \fBmodifiers\fI; Modifiers *\fBmodifiers_return\fI; KeySym *\fBkeysym_return\fI; .iE .sE .SH DESCRIPTION .fi \fIXmTranslateKey\fP is the default \fIXtKeyProc\fP translation procedure for Motif applications. The function takes a keycode and modifiers and returns the corresponding keysym. .PP \fIXmTranslateKey\fP serves two main purposes: new translators with expanded functionality can call it to get the default Motif keycode-to-keysym translation in addition to whatever they add, and so that the default translator can be reinstalled. This function enables keysyms defined by the Motif virtual bindings to be used when an application requires its own XtKeyProc to be installed. .IP "\fBdisplay\fP" Specifies the display that the keycode is from .IP "\fBkeycode\fP" Specifies the keycode to translate .IP "\fBmodifiers\fP" Specifies the modifier keys to be applied to the keycode .IP "\fBmodifiers_return\fP" Specifies a mask of the modifier keys actually used to generate the keysym (an AND of \fBmodifiers\fP and any default modifiers applied by the currently registered translator) .IP "\fBkeysym_return\fP" Specifies a pointer to the resulting keysym .SH RELATED INFORMATION .na \fIVirtualBindings(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmUninstallImage 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmUninstallImage\fP \- A pixmap caching function that removes an image from the image cache .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmUninstallImage (\fBimage\fI) .ta .5i 1.5i .nf XImage \fB* image\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmUninstallImage\fP removes an image from the image cache. .IP "\fBimage\fP" Points to the image structure given to the \fIXmInstallImage()\fP routine .SH RETURN VALUE Returns True when successful; returns False if the \fBimage\fP is NULL, or if it cannot be found to be uninstalled. .SH RELATED INFORMATION .na \fIXmInstallImage(3X)\fP, \fIXmGetPixmap(3X)\fP, and \fIXmDestroyPixmap(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmUpdateDisplay 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmUpdateDisplay\fP \- A function that processes all pending exposure events immediately .SH SYNOPSIS .nf .sS .iS void XmUpdateDisplay\fI (\fBwidget\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmUpdateDisplay\fP provides the application with a mechanism for forcing all pending exposure events to be removed from the input queue and processed immediately. When a user selects a button within a MenuPane, the MenuPanes are unposted and then any activation callbacks registered by the application are invoked. If one of the callbacks performs a time-consuming action, the portion of the application window that was covered by the MenuPanes will not have been redrawn; normal exposure processing does not occur until all of the callbacks have been invoked. If the application writer suspects that a callback will take a long time, then the callback may choose to invoke \fIXmUpdateDisplay\fP before starting its time-consuming operation. This function is also useful any time a transient window, such as a dialog box, is unposted; callbacks are invoked before normal exposure processing can occur. .IP "\fBwidget\fP" Specifies any widget or gadget. ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmVaCreateSimpleCheckBox 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmVaCreateSimpleCheckBox\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmVaCreateSimpleCheckBox (\fBparent, name, callback, arg...\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; XtCallbackProc \fBcallback\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmVaCreateSimpleCheckBox\fP creates an instance of a RowColumn widget of type \fIXmWORK_AREA\fP and returns the associated widget ID. This routine uses the ANSI C variable-length argument list (varargs) calling convention. .PP This routine creates a CheckBox and its ToggleButtonGadget children. A CheckBox is similar to a RadioBox, except that more than one button can be selected at a time. The name of each button is button_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of buttons in the menu. Buttons are named and created in the order in which they are specified in the variable portion of the argument list. .IP "\fBparent\fP" Specifies the parent widget ID. .IP "\fBname\fP" Specifies the name of the created widget. .IP "\fBcallback\fP" Specifies a callback procedure to be called when a button's value changes. This callback function is added to each button after creation as the button's \fIXmNvalueChangedCallback\fP. The callback function is called when a button's value changes, and the button number is returned in the \fBclient_data\fP field. .PP The variable portion of the argument list consists of groups of arguments. The first argument in each group is a constant or a string and determines which arguments follow in that group. The last argument in the list must be NULL. Following are the possible first arguments in each group of varargs: .IP "\fIXmVaCHECKBUTTON\fP" This is followed by four additional arguments. The set specifies one button in the CheckBox and some of its resource values. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBlabel\fP" The label string, of type XmString. .IP "\fBmnemonic\fP" The mnemonic, of type KeySym. This is ignored in this release. .IP "\fBaccelerator\fP" The accelerator, of type String. This is ignored in this release. .IP "\fBaccelerator_text\fP" The accelerator text, of type XmString. This is ignored in this release. .wH .rE .IP "\fBresource_name\fP" This is followed by one additional argument, the value of the resource, of type XtArgVal. The pair specifies a resource and its value for the RowColumn widget. .IP "\fIXtVaTypedArg\fP" This is followed by four additional arguments. The set specifies a resource and its value for the RowColumn widget. A resource type conversion is performed if necessary. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBname\fP" The resource name, of type String. .IP "\fBtype\fP" The type of the resource value supplied, of type String. .IP "\fBvalue\fP" The resource value (or a pointer to the resource value, depending on the type and size of the value), of type XtArgVal. .IP "\fBsize\fP" The size of the resource value in bytes, of type int. .wH .rE .IP "\fIXtVaNestedList\fP" This is followed by one additional argument of type XtVarArgsList. This argument is a nested list of varargs returned by \fIXtVaCreateArgsList\fP. .PP For more information on variable-length argument lists, see the X Toolkit Intrinsics documentation. .PP A number of resources exist specifically for use with this and other simple menu creation routines. For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreateRadioBox(3X)\fP, \fIXmCreateRowColumn(3X)\fP, \fIXmCreateSimpleCheckBox(3X)\fP, \fIXmCreateSimpleRadioBox(3X)\fP, \fIXmRowColumn(3X)\fP, and \fIXmVaCreateSimpleRadioBox(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmVaCreateSimpleMenuBar 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmVaCreateSimpleMenuBar\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmVaCreateSimpleMenuBar (\fBparent, name, arg...\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; .iE .sE .SH DESCRIPTION .fi \fIXmVaCreateSimpleMenuBar\fP creates an instance of a RowColumn widget of type \fIXmMENU_BAR\fP and returns the associated widget ID. This routine uses the ANSI C variable-length argument list (varargs) calling convention. .PP This routine creates a MenuBar and its CascadeButtonGadget children. The name of each button is button_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of buttons in the menu. Buttons are named and created in the order in which they are specified in the variable portion of the argument list. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .PP The variable portion of the argument list consists of groups of arguments. The first argument in each group is a constant or a string and determines which arguments follow in that group. The last argument in the list must be NULL. Following are the possible first arguments in each group of varargs: .IP "\fIXmVaCASCADEBUTTON\fP" This is followed by two additional arguments. The set specifies one button in the MenuBar and some of its resource values. Following are the additional two arguments, in this order: .wH .rS .75i .IP "\fBlabel\fP" The label string, of type XmString. .IP "\fBmnemonic\fP" The mnemonic, of type KeySym. .wH .rE .IP "\fBresource_name\fP" This is followed by one additional argument, the value of the resource, of type XtArgVal. The pair specifies a resource and its value for the RowColumn widget. .IP "\fIXtVaTypedArg\fP" This is followed by four additional arguments. The set specifies a resource and its value for the RowColumn widget. A resource type conversion is performed if necessary. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBname\fP" The resource name, of type String. .IP "\fBtype\fP" The type of the resource value supplied, of type String. .IP "\fBvalue\fP" The resource value (or a pointer to the resource value, depending on the type and size of the value), of type XtArgVal. .IP "\fBsize\fP" The size of the resource value in bytes, of type int. .wH .rE .IP "\fIXtVaNestedList\fP" This is followed by one additional argument of type XtVarArgsList. This argument is a nested list of varargs returned by \fIXtVaCreateArgsList\fP. .PP For more information on variable-length argument lists, see the X Toolkit Intrinsics documentation. .PP A number of resources exist specifically for use with this and other simple menu creation routines. For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreateMenuBar(3X)\fP, \fIXmCreateRowColumn(3X)\fP, \fIXmCreateSimpleMenuBar(3X)\fP, and \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmVaCreateSimpleOptionMenu 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmVaCreateSimpleOptionMenu\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf Widget XmVaCreateSimpleOptionMenu (\fBparent, name, option_label, option_mnemonic, button_set, callback, arg...\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; XmString \fBoption_label\fI; KeySym \fBoption_mnemonic\fI; int \fBbutton_set\fI; XtCallbackProc \fBcallback\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmVaCreateSimpleOptionMenu\fP creates an instance of a RowColumn widget of type \fIXmMENU_OPTION\fP and returns the associated widget ID. This routine uses the ANSI C variable-length argument list (varargs) calling convention. .PP This routine creates an OptionMenu and its Pulldown submenu containing PushButtonGadget or CascadeButtonGadget children. The name of each button is button_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of buttons in the menu. The name of each separator is separator_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of separators in the menu. Buttons and separators are named and created in the order in which they are specified in the variable portion of the argument list. .IP "\fBparent\fP" Specifies the parent widget ID .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBoption_label\fP" Specifies the label string to be used on the left side of the OptionMenu. .IP "\fBoption_mnemonic\fP" Specifies a keysym for a key that, when pressed by the user, posts the associated Pulldown MenuPane. .IP "\fBbutton_set\fP" Specifies which PushButtonGadget is initially set. The value is the integer \fBn\fP that corresponds to the \fBn\fPth PushButtonGadget specified in the variable portion of the argument list. Only a PushButtonGadget can be set, and only PushButtonGadgets are counted in determining the integer \fBn\fP. The first PushButtonGadget is number 0. .IP "\fBcallback\fP" Specifies a callback procedure to be called when a button is activated. This callback function is added to each button after creation as the button's \fIXmNactivateCallback\fP. The callback function is called when a button is activated, and the button number is returned in the \fBclient_data\fP field. .PP The variable portion of the argument list consists of groups of arguments. The first argument in each group is a constant or a string and determines which arguments follow in that group. The last argument in the list must be NULL. Following are the possible first arguments in each group of varargs: .IP "\fIXmVaPUSHBUTTON\fP" This is followed by four additional arguments. The set specifies one button in the OptionMenu's Pulldown submenu and some of its resource values. The button created is a PushButtonGadget. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBlabel\fP" The label string, of type XmString. .IP "\fBmnemonic\fP" The mnemonic, of type KeySym. .IP "\fBaccelerator\fP" The accelerator, of type String. .IP "\fBaccelerator_text\fP" The accelerator text, of type XmString. .wH .rE .IP "\fIXmVaSEPARATOR\fP" This is followed by no additional arguments. It specifies one separator in the OptionMenu's Pulldown submenu. .IP "\fIXmVaDOUBLE_SEPARATOR\fP" This is followed by no additional arguments. It specifies one separator in the OptionMenu's Pulldown submenu. The separator type is \fIXmDOUBLE_LINE\fP. .IP "\fBresource_name\fP" This is followed by one additional argument, the value of the resource, of type XtArgVal. The pair specifies a resource and its value for the Pulldown submenu. .IP "\fIXtVaTypedArg\fP" This is followed by four additional arguments. The set specifies a resource and its value for the Pulldown submenu. A resource type conversion is performed if necessary. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBname\fP" The resource name, of type String. .IP "\fBtype\fP" The type of the resource value supplied, of type String. .IP "\fBvalue\fP" The resource value (or a pointer to the resource value, depending on the type and size of the value), of type XtArgVal. .IP "\fBsize\fP" The size of the resource value in bytes, of type int. .wH .rE .IP "\fIXtVaNestedList\fP" This is followed by one additional argument of type XtVarArgsList. This argument is a nested list of varargs returned by \fIXtVaCreateArgsList\fP. .PP The user can specify resources in a resource file for the automatically created widgets and gadgets of an OptionMenu. The following list identifies the names of these widgets (or gadgets) and the associated OptionMenu areas. .TP \(bu .TP \(bu Option Menu Label Gadget \- "OptionLabel" .TP \(bu Option Menu Cascade Button \- "OptionButton" .PP For more information on variable-length argument lists, see the X Toolkit Intrinsics documentation. .PP A number of resources exist specifically for use with this and other simple menu creation routines. For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreateOptionMenu(3X)\fP, \fIXmCreateRowColumn(3X)\fP, \fIXmCreateSimpleOptionMenu(3X)\fP, and \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmVaCreateSimplePopupMenu 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmVaCreateSimplePopupMenu\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Widget XmVaCreateSimplePopupMenu (\fBparent, name, callback, arg...\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; XtCallbackProc \fBcallback\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmVaCreateSimplePopupMenu\fP creates an instance of a RowColumn widget of type \fIXmMENU_POPUP\fP and returns the associated widget ID. This routine uses the ANSI C variable-length argument list (varargs) calling convention. .PP This routine creates a Popup MenuPane and its button children. The name of each button is button_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of buttons in the menu. The name of each separator is separator_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of separators in the menu. The name of each title is label_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of titles in the menu. Buttons, separators, and titles are named and created in the order in which they are specified in the variable portion of the argument list. .IP "\fBparent\fP" Specifies the widget ID of the parent of the MenuShell .IP "\fBname\fP" Specifies the name of the created widget .IP "\fBcallback\fP" Specifies a callback procedure to be called when a button is activated or when its value changes. This callback function is added to each button after creation. For a CascadeButtonGadget or a PushButtonGadget, the callback is added as the button's \fIXmNactivateCallback\fP, and it is called when the button is activated. For a ToggleButtonGadget, the callback is added as the button's \fIXmNvalueChangedCallback\fP, and it is called when the button's value changes. The button number is returned in the \fBclient_data\fP field. .PP The variable portion of the argument list consists of groups of arguments. The first argument in each group is a constant or a string and determines which arguments follow in that group. The last argument in the list must be NULL. Following are the possible first arguments in each group of varargs: .IP "\fIXmVaCASCADEBUTTON\fP" This is followed by two additional arguments. The set specifies one button in the PopupMenu and some of its resource values. The button created is a CascadeButtonGadget. Following are the additional two arguments, in this order: .wH .rS .75i .IP "\fBlabel\fP" The label string, of type XmString. .IP "\fBmnemonic\fP" The mnemonic, of type KeySym. .wH .rE .IP "\fIXmVaPUSHBUTTON\fP" This is followed by four additional arguments. The set specifies one button in the PopupMenu and some of its resource values. The button created is a PushButtonGadget. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBlabel\fP" The label string, of type XmString. .IP "\fBmnemonic\fP" The mnemonic, of type KeySym. .IP "\fBaccelerator\fP" The accelerator, of type String. .IP "\fBaccelerator_text\fP" The accelerator text, of type XmString. .wH .rE .IP "\fIXmVaRADIOBUTTON\fP" This is followed by four additional arguments. The set specifies one button in the PopupMenu and some of its resource values. The button created is a ToggleButtonGadget. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBlabel\fP" The label string, of type XmString. .IP "\fBmnemonic\fP" The mnemonic, of type KeySym. .IP "\fBaccelerator\fP" The accelerator, of type String. .IP "\fBaccelerator_text\fP" The accelerator text, of type XmString. .wH .rE .IP "\fIXmVaCHECKBUTTON\fP" This is followed by four additional arguments. The set specifies one button in the PopupMenu and some of its resource values. The button created is a ToggleButtonGadget. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBlabel\fP" The label string, of type XmString. .IP "\fBmnemonic\fP" The mnemonic, of type KeySym. .IP "\fBaccelerator\fP" The accelerator, of type String. .IP "\fBaccelerator_text\fP" The accelerator text, of type XmString. .wH .rE .nL .ne 8 .IP "\fIXmVaTITLE\fP" This is followed by one additional argument. The pair specifies a title LabelGadget in the PopupMenu. Following is the additional argument: .wH .rS .75i .IP "\fBtitle\fP" The title string, of type XmString. .wH .rE .IP "\fIXmVaSEPARATOR\fP" This is followed by no additional arguments. It specifies one separator in the PopupMenu. .IP "\fIXmVaDOUBLE_SEPARATOR\fP" This is followed by no additional arguments. It specifies one separator in the PopupMenu. The separator type is \fIXmDOUBLE_LINE\fP. .IP "\fBresource_name\fP" This is followed by one additional argument, the value of the resource, of type XtArgVal. The pair specifies a resource and its value for the RowColumn widget. .IP "\fIXtVaTypedArg\fP" This is followed by four additional arguments. The set specifies a resource and its value for the RowColumn widget. A resource type conversion is performed if necessary. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBname\fP" The resource name, of type String. .IP "\fBtype\fP" The type of the resource value supplied, of type String. .IP "\fBvalue\fP" The resource value (or a pointer to the resource value, depending on the type and size of the value), of type XtArgVal. .IP "\fBsize\fP" The size of the resource value in bytes, of type int. .wH .rE .IP "\fIXtVaNestedList\fP" This is followed by one additional argument of type XtVarArgsList. This argument is a nested list of varargs returned by \fIXtVaCreateArgsList\fP. .PP .ne 6 For more information on variable-length argument lists, see the X Toolkit Intrinsics documentation. .PP A number of resources exist specifically for use with this and other simple menu creation routines. For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreatePopupMenu(3X)\fP, \fIXmCreateRowColumn(3X)\fP, \fIXmCreateSimplePopupMenu(3X)\fP, and \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmVaCreateSimplePulldownMenu 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmVaCreateSimplePulldownMenu\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf Widget XmVaCreateSimplePulldownMenu (\fBparent, name, post_from_button, callback, arg...\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; int \fBpost_from_button\fI; XtCallbackProc \fBcallback\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmVaCreateSimplePulldownMenu\fP creates an instance of a RowColumn widget of type \fIXmMENU_PULLDOWN\fP and returns the associated widget ID. This routine uses the ANSI C variable-length argument list (varargs) calling convention. .PP This routine creates a Pulldown MenuPane and its button children. The name of each button is button_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of buttons in the menu. The name of each separator is separator_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of separators in the menu. The name of each title is label_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of titles in the menu. Buttons, separators, and titles are named and created in the order in which they are specified in the variable portion of the argument list. .PP This routine also attaches the PulldownMenu to a CascadeButton or CascadeButtonGadget in the parent. The PulldownMenu is then posted from this button. .IP "\fBparent\fP" Specifies the widget ID of the parent of the MenuShell. .IP "\fBname\fP" Specifies the name of the created widget. .IP "\fBpost_from_button\fP" Specifies the CascadeButton or CascadeButtonGadget in the parent to which the Pulldown MenuPane is attached. The value is the integer \fBn\fP that corresponds to the \fBn\fPth CascadeButton or CascadeButtonGadget specified for the parent of the Pulldown MenuPane. A Pulldown MenuPane can be attached only to a CascadeButton or CascadeButtonGadget, and only CascadeButtons and CascadeButtonGadgets are counted in determining the integer \fBn\fP. The first CascadeButton or CascadeButtonGadget is number 0. .IP "\fBcallback\fP" Specifies a callback procedure to be called when a button is activated or when its value changes. This callback function is added to each button after creation. For a CascadeButtonGadget or a PushButtonGadget, the callback is added as the button's \fIXmNactivateCallback\fP, and it is called when the button is activated. For a ToggleButtonGadget, the callback is added as the button's \fIXmNvalueChangedCallback\fP, and it is called when the button's value changes. The button number is returned in the \fBclient_data\fP field. .PP The variable portion of the argument list consists of groups of arguments. The first argument in each group is a constant or a string and determines which arguments follow in that group. The last argument in the list must be NULL. Following are the possible first arguments in each group of varargs: .IP "\fIXmVaCASCADEBUTTON\fP" This is followed by two additional arguments. The set specifies one button in the PulldownMenu and some of its resource values. The button created is a CascadeButtonGadget. Following are the additional two arguments, in this order: .wH .rS .75i .IP "\fBlabel\fP" The label string, of type XmString. .IP "\fBmnemonic\fP" The mnemonic, of type KeySym. .wH .rE .IP "\fIXmVaPUSHBUTTON\fP" This is followed by four additional arguments. The set specifies one button in the PulldownMenu and some of its resource values. The button created is a PushButtonGadget. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBlabel\fP" The label string, of type XmString. .IP "\fBmnemonic\fP" The mnemonic, of type KeySym. .IP "\fBaccelerator\fP" The accelerator, of type String. .IP "\fBaccelerator_text\fP" The accelerator text, of type XmString. .wH .rE .IP "\fIXmVaRADIOBUTTON\fP" This is followed by four additional arguments. The set specifies one button in the PulldownMenu and some of its resource values. The button created is a ToggleButtonGadget. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBlabel\fP" The label string, of type XmString. .IP "\fBmnemonic\fP" The mnemonic, of type KeySym. .IP "\fBaccelerator\fP" The accelerator, of type String. .IP "\fBaccelerator_text\fP" The accelerator text, of type XmString. .wH .rE .nL .ne 10 .IP "\fIXmVaCHECKBUTTON\fP" This is followed by four additional arguments. The set specifies one button in the PulldownMenu and some of its resource values. The button created is a ToggleButtonGadget. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBlabel\fP" The label string, of type XmString. .IP "\fBmnemonic\fP" The mnemonic, of type KeySym. .IP "\fBaccelerator\fP" The accelerator, of type String. .IP "\fBaccelerator_text\fP" The accelerator text, of type XmString. .wH .rE .IP "\fIXmVaTITLE\fP" This is followed by one additional argument. The pair specifies a title LabelGadget in the PulldownMenu. Following is the additional argument: .wH .rS .75i .IP "\fBtitle\fP" The title string, of type XmString. .wH .rE .IP "\fIXmVaSEPARATOR\fP" This is followed by no additional arguments. It specifies one separator in the PulldownMenu. .IP "\fIXmVaDOUBLE_SEPARATOR\fP" This is followed by no additional arguments. It specifies one separator in the PulldownMenu. The separator type is \fIXmDOUBLE_LINE\fP. .IP "\fBresource_name\fP" This is followed by one additional argument, the value of the resource, of type XtArgVal. The pair specifies a resource and its value for the RowColumn widget. .nL .ne 25 .IP "\fIXtVaTypedArg\fP" This is followed by four additional arguments. The set specifies a resource and its value for the RowColumn widget. A resource type conversion is performed if necessary. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBname\fP" The resource name, of type String. .IP "\fBtype\fP" The type of the resource value supplied, of type String. .IP "\fBvalue\fP" The resource value (or a pointer to the resource value, depending on the type and size of the value), of type XtArgVal. .IP "\fBsize\fP" The size of the resource value in bytes, of type int. .wH .rE .IP "\fIXtVaNestedList\fP" This is followed by one additional argument of type XtVarArgsList. This argument is a nested list of varargs returned by \fIXtVaCreateArgsList\fP. .PP For more information on variable-length argument lists, see the X Toolkit Intrinsics documentation. .PP A number of resources exist specifically for use with this and other simple menu creation routines. For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .P .nL .ne 40 .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreatePulldownMenu(3X)\fP, \fIXmCreateRowColumn(3X)\fP, \fIXmCreateSimplePulldownMenu\fP, and \fIXmRowColumn(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmVaCreateSimpleRadioBox 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmVaCreateSimpleRadioBox\fP \- A RowColumn widget convenience creation function .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu .ta 1i .nf Widget XmVaCreateSimpleRadioBox (\fBparent, name, button_set, callback, arg...\fI) .ta .5i 1.5i .nf Widget \fBparent\fI; String \fBname\fI; int \fBbutton_set\fI; XtCallbackProc \fBcallback\fI; .wH .fi .iE .sE .SH DESCRIPTION .fi \fIXmVaCreateSimpleRadioBox\fP creates an instance of a RowColumn widget of type \fIXmWORK_AREA\fP and returns the associated widget ID. This routine uses the ANSI C variable-length argument list (varargs) calling convention. .PP This routine creates a RadioBox and its ToggleButtonGadget children. The name of each button is button_\fBn\fP, where \fBn\fP is an integer from 0 to one minus the number of buttons in the menu. .IP "\fBparent\fP" Specifies the parent widget ID. .IP "\fBname\fP" Specifies the name of the created widget. .IP "\fBbutton_set\fP" Specifies which button is initially set. The value is the integer \fBn\fP in the button name button_\fBn\fP. .IP "\fBcallback\fP" Specifies a callback procedure to be called when a button's value changes. This callback function is added to each button after creation as the button's \fIXmNvalueChangedCallback\fP. The callback function is called when a button's value changes, and the button number is returned in the \fBclient_data\fP field. .PP The variable portion of the argument list consists of groups of arguments. The first argument in each group is a constant or a string and determines which arguments follow in that group. The last argument in the list must be NULL. Following are the possible first arguments in each group of varargs: .IP "\fIXmVaRADIOBUTTON\fP" This is followed by four additional arguments. The set specifies one button in the RadioBox and some of its resource values. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBlabel\fP" The label string, of type XmString. .IP "\fBmnemonic\fP" The mnemonic, of type KeySym. This is ignored in this release. .IP "\fBaccelerator\fP" The accelerator, of type String. This is ignored in this release. .IP "\fBaccelerator_text\fP" The accelerator text, of type XmString. This is ignored in this release. .wH .rE .IP "\fBresource_name\fP" This is followed by one additional argument, the value of the resource, of type XtArgVal. The pair specifies a resource and its value for the RowColumn widget. .IP "\fIXtVaTypedArg\fP" This is followed by four additional arguments. The set specifies a resource and its value for the RowColumn widget. A resource type conversion is performed if necessary. Following are the additional four arguments, in this order: .wH .rS .75i .IP "\fBname\fP" The resource name, of type String. .IP "\fBtype\fP" The type of the resource value supplied, of type String. .IP "\fBvalue\fP" The resource value (or a pointer to the resource value, depending on the type and size of the value), of type XtArgVal. .IP "\fBsize\fP" The size of the resource value in bytes, of type int. .wH .rE .IP "\fIXtVaNestedList\fP" This is followed by one additional argument of type XtVarArgsList. This argument is a nested list of varargs returned by \fIXtVaCreateArgsList\fP. .PP For more information on variable-length argument lists, see the X Toolkit Intrinsics documentation. .PP A number of resources exist specifically for use with this and other simple menu creation routines. For a complete definition of RowColumn and its associated resources, see \fIXmRowColumn(3X)\fP. .SH RETURN VALUE Returns the RowColumn widget ID. .SH RELATED INFORMATION .na \fIXmCreateRadioBox(3X)\fP, \fIXmCreateRowColumn(3X)\fP, \fIXmCreateSimpleCheckBox(3X)\fP, \fIXmCreateSimpleRadioBox(3X)\fP, \fIXmRowColumn(3X)\fP, and \fIXmVaCreateSimpleCheckBox(3X)\fP, .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmWidgetGetBaselines 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmWidgetGetBaselines\fP \- Retrieves baseline information for a widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmWidgetGetBaselines (\fBwidget, baselines, line_count\fI) .ta .5i 1.75i .nf Widget \fBwidget\fI; Dimension **\fBbaselines\fI; int *\fBline_count\fI; .iE .sE .SH DESCRIPTION .fi \fIXmWidgetGetBaselines\fP returns an array that contains one or more baseline values associated with the specified widget. The baseline of any given line of text is a vertical offset in pixels from the origin of the widget's bounding box to the given baseline. This routine allocates memory for the returned data. The application must free this memory using \fIXtFree\fP. .IP "\fBwidget\fP" Specifies the ID of the widget for which baseline values are requested .IP "\fBbaselines\fP" Returns an array that contains the value of each baseline of text in the widget .IP "\fBline_count\fP" Returns the number of lines in the widget .SH RETURN VALUE Returns a Boolean value that indicates whether the widget contains a baseline. If True, the function returns a value for each baseline of text. If False, the function was unable to return a baseline value. .SH RELATED INFORMATION .na \fIXmWidgetGetDisplayRect(3X)\fP. .ad ...\" ** (c) Copyright 1993, 1994 Hewlett-Packard Company ...\" ** (c) Copyright 1993, 1994 International Business Machines Corp. ...\" ** (c) Copyright 1993, 1994 Sun Microsystems, Inc. ...\" ** (c) Copyright 1993, 1994 Novell, Inc ...\" ** ...\" ** ...\" ** ...\" ** (c) Copyright 1989, 1990, 1992 by Open Software Foundation, Inc. ...\" ** All Rights Reserved. ...\" ** ...\" ** (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company ...\" ** ...\" ** (c) Copyright 1987, 1988 by Digital Equipment Corporation, ...\" ** Maynard, MA. All Rights Reserved. ...\" ** ...\" ** .TH XmWidgetGetDisplayRect 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W Motif Release 1.2: May 1992 .SH NAME \fIXmWidgetGetDisplayRect\fP \- Retrieves display rectangle information for a widget .SH SYNOPSIS .nf .sS .iS \&#include .sp \n(PDu Boolean XmWidgetGetDisplayRect (\fBwidget, displayrect\fI) .ta .5i 1.5i .nf Widget \fBwidget\fI; XRectangle *\fBdisplayrect\fI; .iE .sE .SH DESCRIPTION .fi \fIXmWidgetGetDisplayRect\fP returns the width, height and the x and y coordinates of the upper left corner of the display rectangle of the specified widget. The display rectangle is the smallest rectangle that encloses either a string or a pixmap. .PP If the widget contains a string, the return values specify the x and y coordinates of the upper left corner of the display rectangle relative to the origin of the widget and the width and height in pixels. .PP In the case of a pixmap, the return values specify the x and y coordinates of the upper left corner of the pixmap relative to the origin, and the width and height of the pixmap in pixels. .IP "\fBwidget\fP" Specifies the widget ID .IP "\fBdisplayrect\fP" Specifies a pointer to an XRectangle structure in which the x and y coordinates, width and height of the display rectangle are returned .SH RETURN VALUE Returns True if the specified widget has an associated display rectangle; otherwise, returns False. .SH RELATED INFORMATION .na \fIXmWidgetGetBaselines(3X)\fP. .ad .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XmbDrawImageString" "\s-1Xlib \- Internationalized Text Output\s+1" .ds ]W Xlib Reference Manual .XX "XmbDrawImageString" .XX "text:multi-byte, drawing" .SH Name .Na XmbDrawImageString \(en draw internationalized multi-byte image text. .Nz .SH Synopsis .Sy void XmbDrawImageString\^(\^\f(CIdisplay\fP\^, \f(CIdrawable\fP\^, \f(CIfont_set\fP\^, \f(CIgc\fP\^, \f(CIx\fP\^, \f(CIy\fP\^, \f(CIstring\fP\^, \f(CInum_bytes\fP\^) .As Display *\f(CIdisplay\fP\^; Drawable \f(CIdrawable\fP\^; XFontSet \f(CIfont_set\fP\^; GC \f(CIgc\fP\^; int \f(CIx\fP\^, \f(CIy\fP\^; char *\f(CIstring\fP\^; int \f(CInum_bytes\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIfont_set\fP 1i Specifies the font set. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP "\f(CIx\fP, \f(CIy\fP" 1i Specifies the starting position and baseline of the text, relative to the origin of the specified drawable. .IP \f(CIstring\fP 1i Specifies the character string. .IP \f(CInum_bytes\fP 1i Specifies the number of bytes in the string argument. .SH Availability Release 5 and later. .SH Description \f(CWXmbDrawImageString()\fR fills a destination rectangle with the background pixel defined in the GC and then paints the specified multi-byte text with the foreground pixel. The filled rectangle is the rectangle returned to \f(CIoverall_logical_return\fP by \f(CWXmbTextExtents()\fR for the same text and \f(CWXFontSet\fR. .LP When the \f(CWXFontSet\fR has missing charsets, each unavailable character is drawn with the default string returned by \f(CWXCreateFontSet()\fR. The behavior for an invalid codepoint is undefined. .LP \f(CWXmbDrawImageString()\fP draws with fonts from the font set rather than the font of the GC. For this reason, it may modify the font value of the GC. Except for the font, it uses the same GC components as its pre-X11R5 analog \f(CWXDrawImageString()\fP. .Nd 8 .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXmbDrawString()\fP\s+1, \s-1\fIXmbDrawText()\fP\s+1, \s-1\fIXwcDrawImageString()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XmbDrawString" "\s-1Xlib \- Internationalized Text Output\s+1" .ds ]W Xlib Reference Manual .XX "XmbDrawString" .XX "multi-byte text:drawing" .XX "text:multi-byte, drawing" .SH Name .Na XmbDrawString \(en draw internationalized multi-byte text. .Nz .SH Synopsis .Sy void XmbDrawString\^(\^\f(CIdisplay\fP\^, \f(CIdrawable\fP\^, \f(CIfont_set\fP\^, \f(CIgc\fP\^, \f(CIx\fP\^, \f(CIy\fP\^, \f(CIstring\fP\^, \f(CInum_bytes\fP\^) .As Display *\f(CIdisplay\fP\^; Drawable \f(CIdrawable\fP\^; XFontSet \f(CIfont_set\fP\^; GC \f(CIgc\fP\^; int \f(CIx\fP\^, \f(CIy\fP\^; char *\f(CIstring\fP\^; int \f(CInum_bytes\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIfont_set\fP 1i Specifies the font set. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP "\f(CIx\fP, \f(CIy\fP" 1i Specifies the starting position and baseline of the text, relative to the origin of the specified drawable. .IP \f(CIstring\fP 1i Specifies the character string. .IP \f(CInum_bytes\fP 1i Specifies the number of bytes in the string argument. .SH Availability Release 5 and later. .SH Description \f(CWXmbDrawString()\fR draws the specified multi-byte text with the foreground pixel. When the \f(CWXFontSet\fR has missing charsets, each unavailable character is drawn with the default string returned by \f(CWXCreateFontSet()\fR. The behavior for an invalid codepoint is undefined. .LP \f(CWXmbDrawString()\fP draws with fonts from the font set rather than the font of the GC. For this reason, it may modify the font value of the GC. Except for the font, it uses the same GC components as its pre-X11R5 analog \f(CWXDrawString()\fP. .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXmbDrawImageString()\fP\s+1, \s-1\fIXmbDrawText()\fP\s+1, \s-1\fIXwcDrawString()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XmbDrawText" "Xlib \- Internationalized Text" .ds ]W Xlib Reference Manual .XX "XmbDrawText" .XX "multi-byte text:drawing" .XX "text:multi-byte, drawing" .SH Name .Na XmbDrawText \(en draw internationalized multi-byte text using multiple font sets. .Nz .SH Synopsis .Sy void XmbDrawText\^(\^\f(CIdisplay\fP\^, \f(CIdrawable\fP\^, \f(CIgc\fP\^, \f(CIx\fP\^, \f(CIy\fP\^, \f(CIitems\fP\^, \f(CInitems\fP\^) .As Display *\f(CIdisplay\fP\; Drawable \f(CIdrawable\fP\^; GC \f(CIgc\fP\^; int \f(CIx\fP\^, \f(CIy\fP\^; XmbTextItem *\f(CIitems\fP\^; int \f(CInitems\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP "\f(CIx\fP, \f(CIy\fP" 1i Specifies the starting position and baseline of the text, relative to the origin of the specified drawable. .IP \f(CIitems\fP 1i Specifies an array of text items. .IP \f(CInitems\fP 1i Specifies the number of text items in the array. .SH Description \f(CWXmbDrawText()\fR allows complex spacing and font set shifts between internationalized multi-byte text strings. Each text item is processed in turn, with the origin of a text element advanced in the primary draw direction by the escapement of the previous text item. A text item delta specifies an additional escapement of the text item drawing origin in the primary draw direction. A \f(CIfont_set\fP member other than \f(CWNone\fR in an item causes the font set to be used for this and subsequent text items in the \f(CIitems\fP list. Leading text items with \f(CIfont_set\fP member set to \f(CWNone\fR will not be drawn. .LP \f(CWXmbDrawText()\fR does not perform any context-dependent rendering between text segments. Clients may compute the drawing metrics by passing each text segment to \f(CWXmbTextExtents()\fR or \f(CWXmbTextPerCharExtents()\fR. When the \f(CWXFontSet\fR has missing charsets, each unavailable character is drawn with the default string returned by \f(CWXCreateFontSet()\fR. The behavior for an invalid codepoint is undefined. .LP \f(CWXmbDrawText()\fP draws with fonts from the font sets of the \f(CIitems\fP list rather than the font of the GC. For this reason, it may modify the font value of the GC. Except for the font, it uses the same GC components as its pre-X11R5 analog \f(CWXDrawText()\fP. .Nd 15 .SH Structures The \f(CWXmbTextItem\fR structure contains: .Ps .ta 2.5i typedef struct { char *chars; /* pointer to string */ int nchars; /* number of characters */ int delta; /* pixel delta between strings */ XFontSet font_set; /* fonts, None means don't change */ } XmbTextItem; .Pe .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXmbDrawImageString()\fP\s+1, \s-1\fIXmbDrawString()\fP\s+1, \s-1\fIXwcDrawText()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XmbLookupString" "Xlib \- Internationalized Text Input" .ds ]W Xlib Reference Manual .XX "XmbLookupString" .XX "input methods:obtaining from multi-byte" .XX "multi-byte input:obtaining" .SH Name .Na XmbLookupString \(en obtain composed multi-byte input from an input method. .Nz .SH Synopsis .Sy int XmbLookupString\^(\^\f(CIic\fP\^, \f(CIevent\fP\^, \f(CIbuffer_return\fP\^, \f(CIbytes_buffer\fP\^, \f(CIkeysym_return\fP\^, \f(CIstatus_return\fP\^) .As XIC \f(CIic\fP\^; XKeyPressedEvent *\f(CIevent\fP; char *\f(CIbuffer_return\fP\^; int \f(CIbytes_buffer\fP\^; KeySym *\f(CIkeysym_return\fP\^; Status *\f(CIstatus_return\fP\^; .Ae .SH Arguments .IP \f(CIic\fP 12n Specifies the input context. .ds Ev keypress event to be used .IP \f(CIevent\fP 12n Specifies the \*(Ev. .IP \f(CIbuffer_return\fP 12n Returns a multibyte string (if any) from the input method. .IP \f(CIbytes_buffer\fP 12n Specifies the number of bytes in the return buffer. .IP \f(CIkeysym_return\fP 12n Returns the KeySym computed from the event if this argument is not \f(CWNULL\fP. .IP \f(CIstatus_return\fP 12n Returns a value indicating what kind of data is returned. .SH Returns Number of characters in the string in \f(CIbytes_buffer\fP. .SH Availability Release 5 and later. .SH Description \f(CWXmbLookupString()\fP passes a \f(CWKeyPress\fP event to an input context, returns composed text in the encoding of the locale of the input context if any is ready, and may return a keysym corresponding to the \f(CWKeyPress\fP event as well. .LP There are several possible results of a call to \f(CWXmbLookupString()\fP, and a client should check the value returned in the \f(CIstatus_return\fP argument to determine which has occurred. The possible values are: .LP .IP \f(CWXBufferOverflow\fR 10n The input string to be returned is too large for the supplied \f(CIbuffer_return\fP. The required size in bytes is returned as the value of the function, and the contents of \f(CIbuffer_return\fP and \f(CIkeysym_return\fP are not modified. The client should re-call the function with the same event and a buffer of adequate size in order to obtain the string. .IP \f(CWXLookupNone\fR 10n No consistent input has been composed so far. The contents of \f(CIbuffer_return\fP and \f(CIkeysym_return\fP are not modified, and the function returns zero. .Nd 15 .hw buffer .IP \f(CWXLookupChars\fR 10n Some input characters have been composed. They are placed in the \f(CIbuffer_return\fP argument, and the string length is returned as the value of the function. The string is encoded in the locale bound to the input context. The contents of the \f(CIkeysym_return\fP argument is not modified. .IP \f(CWXLookupKeySym\fR 10n A KeySym has been returned instead of a string and is returned in \f(CIkeysym_return\fP. The contents of the \f(CIbuffer_return\fP argument is not modified, and the function returns zero. .IP \f(CWXLookupBoth\fR 10n Both a KeySym and a string are returned; \f(CWXLookupChars\fR and \f(CWXLookupKeySym\fR occur simultaneously. .LP When \f(CWXmbLookupString()\fP returns a string, the return value of the function is the length in bytes of that string. The returned string is a multi-byte string in the encoding of the locale of the input context. If that encoding is state-dependent, the string begins in the initial state of the encoding. .LP When both a keysym and a string are returned, the string does not necessarily correspond to the keysym. An application that is not interested in return keysyms can pass a \f(CWNULL\fP \f(CIkeysym_return\fP. .LP Note that only \f(CWKeyPress\fP events should be passed to \f(CWXmbLookupString()\fP. When \f(CWKeyRelease\fP events are passed, the resulting behavior is undefined. It does not make any difference if the input context passed as an argument to \f(CWXmbLookupString()\fR is the one currently in possession of the focus or not. Input may have been composed within an input context before it lost the focus, and that input may be returned on subsequent calls to \f(CWXmbLookupString()\fR even though it no longer has any more keyboard focus. .SH "See Also" \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXwcLookupString()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XmbResetIC" "Xlib \- Input Contexts" .ds ]W Xlib Reference Manual .XX "XmbResetIC" .XX "input contexts:resetting" .SH Name .Na XmbResetIC \(en reset the state of an input context. .Nz .SH Synopsis .Sy char * XmbResetIC\^(\^\f(CIic\fP\^) .As XIC \f(CIic\fP\^; .Ae .SH Arguments .IP \f(CIic\fP 1i Specifies the input context. .SH Returns .SH Availability Release 5 and later. Implementation-dependent (see the "Description" section). .SH Description \f(CWXmbResetIC()\fP resets an input context to its initial state. Any input pending on that context is deleted. The input method is required to clear the Preedit area, if any, and update the Status area accordingly. Calling this function does not change the input context focus. .LP The return value of \f(CWXmbResetIC()\fP is implementation-dependent. If there was input pending on the input context, \f(CWXmbResetIC()\fP may return composed multi-byte text in the encoding of the locale of the input context, or it may return \f(CWNULL\fP. If any string is returned, the client is responsible for freeing it by calling \f(CWXFree()\fP. .SH "See Also" \s-1\fIXCreateIC()\fP\s+1, \s-1\fIXSetICFocus()\fP\s+1, \s-1\fIXSetICValues()\fP\s+1, \s-1\fIXwcResetIC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XmbSetWMProperties" "Xlib \- Internationalized Text" .ds ]W Xlib Reference Manual .XX "XmbSetWMProperties" .XX "properties, window manager" .XX "window manager, properties" .SH Name .Na XmbSetWMProperties \(en set window manager properties using internationalized encoding. .Nz .SH Synopsis .Sy void XmbSetWMProperties\^(\^\f(CIdisplay\fP\^, \f(CIw\fP\^, \f(CIwindow_name\fP\^, \f(CIicon_name\fP\^, \f(CIargv\fP\^, \f(CIargc\fP\^, .br \f(CInormal_hints\fP\^, \f(CIwm_hints\fP\^, \f(CIclass_hints\fP\^) .As Display *\f(CIdisplay\fP\^; .br Window \f(CIw\fP\^; .br char *\f(CIwindow_name\fP\^; .br char *\f(CIicon_name\fP\^; .br char *\f(CIargv\fP\^[]; .br int \f(CIargc\fP\^; .br XSizeHints *\f(CInormal_hints\fP\^; .br XWMHints *\f(CIwm_hints\fP\^; .br XClassHint *\f(CIclass_hints\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1.09i Specifies a connection to an X server; returned from \f(CWXOpenDisplay()\fP. .IP \f(CIw\fP 1.09i Specifies the window. Should be a top-level window. .IP \f(CIwindow_name\fP 1.09i Specifies the window name, which should be a \f(CWNULL\fP-terminated string. .IP \f(CIicon_name\fP 1.09i Specifies the icon name, which should be a \f(CWNULL\fP-terminated string. .IP \f(CIargv\fP 1.09i Specifies the application's argument list. .IP \f(CIargc\fP 1.09i Specifies the number of arguments. .IP \f(CIhints\fP 1.09i Specifies the size hints for the window in its normal state. .IP \f(CIwm_hints\fP 1.09i Specifies the \f(CWXWMHints\fP structure to be used. .IP \f(CIclass_hints\fP 1.09i Specifies the \f(CWXClassHint\fP structure to be used. .SH Availability Release 5 and later. .SH Description \f(CWXmbSetWMProperties()\fP stores the standard set of window manager properties, with text properties in standard encodings for internationalized text communication. The standard window manager properties for a given window are WM_NAME, WM_ICON_NAME, WM_HINTS, WM_NORMAL_HINTS, WM_CLASS, WM_COMMAND, WM_CLIENT_MACHINE, and WM_LOCALE_NAME. .LP If the \f(CIwindow_name\fP argument is non-\f(CWNULL\fP, \f(CWXmbSetWMProperties()\fP sets the WM_NAME property. If the \f(CIicon_name\fP argument is non-\f(CWNULL\fP, \f(CWXmbSetWMProperties()\fP sets the WM_ICON_NAME property. The \f(CIwindow_name\fP and \f(CIicon_name\fP arguments are \f(CWNULL\fP-terminated strings in the encoding of the current locale. If the arguments can be fully converted to the \f(CWXA_STRING\fP encoding, the properties are created with type \f(CWXA_STRING\fP: otherwise, the arguments are converted to Compound Text, and the properties are created with type COMPOUND_TEXT. .LP If the \f(CInormal_hints\fP argument is non-\f(CWNULL\fP, \f(CWXmbSetWMProperties()\fP calls \f(CWXSetWMNormalHints()\fP, which sets the WM_NORMAL_HINTS property. If the \f(CIwm_hints\fP argument is non-\f(CWNULL\fP, \f(CWXmbSetWMProperties()\fP calls \f(CWXSetWMHints()\fP, which sets the WM_HINTS property. .LP If the \f(CIargv\fP argument is non-\f(CWNULL\fP, \f(CWXmbSetWMProperties()\fP sets the WM_COMMAND property from \f(CIargv\fP and \f(CIargc\fP. Note that an argc of 0 indicates a zero-length command. .LP The hostname of this machine is stored using \f(CWXSetWMClientMachine()\fP. .LP If the \f(CIclass_hints\fP argument is non-\f(CWNULL\fP, \f(CWXmbSetWMProperties()\fP sets the WM_CLASS property. If the \f(CWres_name\fP member in the \f(CWXClassHint\fP structure is set to the \f(CWNULL\fP pointer and the RESOURCE_NAME environment variable is set, the value of the environment variable is substituted for res_name. If the \f(CWres_name\fP member is \f(CWNULL\fP, the environment variable is not set, and \f(CIargv\fP and \f(CIargv[0]\fP are set, then the value of \f(CIargv[0]\fP, stripped of any directory prefixes, is substituted for \f(CWres_name\fP. .LP It is assumed that the supplied \f(CWclass_hints.res_name\fP and \f(CWargv\fP, the RESOURCE_NAME environment variable, and the hostname of this machine are in the encoding of the locale announced for the LC_CTYPE category. (On POSIX-compliant systems, the LC_CTYPE, else LANG environment variable). .hw COMMAND The corresponding WM_CLASS, WM_COMMAND, and WM_CLIENT_MACHINE properties are typed according to the local host locale announcer. No encoding conversion is performed prior to storage in the properties. .LP For clients that need to process the property text in a locale, \f(CWXmbSetWMProperties()\fP sets the WM_LOCALE_NAME property to be the name of the current locale. The name is assumed to be in the Host Portable Character Encoding, and is converted to STRING for storage in the property. .SH "Structures" .Ps typedef struct { long flags; /* marks which fields in this structure */ /* are defined */ int x, y; /* obsolete for new window mgrs, but clients */ int width, height; /* should set so old wm's don't mess up */ int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; int base_width, base_height; /* added by ICCCM version 1 */ int win_gravity; /* added by ICCCM version 1 */ } XSizeHints; /* flags argument in size hints */ #define USPosition (1L << 0) /* user specified x, y */ #define USSize (1L << 1) /* user specified width, height */ #define PPosition (1L << 2) /* program specified position */ #define PSize (1L << 3) /* program specified size */ #define PMinSize (1L << 4) /* program specified minimum size */ #define PMaxSize (1L << 5) /* program specified maximum size */ #define PResizeInc (1L << 6) /* program specified resize increments */ #define PAspect (1L << 7) /* program specified min/max aspect ratios */ #define PAllHints (PPosition PSize PMinSize PMaxSize PResizeInc PAspect) typedef struct { long flags; /* marks which fields in this structure */ /* are defined */ Bool input; /* does this application rely on the window */ /* manager to get keyboard input? */ int initial_state; /* see below */ Pixmap icon_pixmap; /* pixmap to be used as icon */ Window icon_window; /* window to be used as icon */ int icon_x, icon_y; /* initial position of icon */ Pixmap icon_mask; /* icon mask bitmap */ .ne 4 XID window_group; /* id of related window group */ /* this structure may be extended in the future */ } XWMHints; .ta 4n +1.1i 2.1i #define USPosition (1L << 0) /* user specified x, y */ #define USSize (1L << 1) /* user specified width, height */ #define PPosition (1L << 2) /* program specified position */ #define PSize (1L << 3) /* program specified size */ #define PMinSize (1L << 4) /* program specified minimum size */ #define PMaxSize (1L << 5) /* program specified maximum size */ #define PResizeInc (1L << 6) /* program specified resize increments * / #define PAspect (1L << 7) /* program specified min/max aspect ratios */ #define PAllHints (PPosition PSize PMinSize PMaxSize PResizeInc PAspect) #define PBaseSize (1L << 8) /* program specified base for incrementing */ #define PWinGravity (1L << 9) /* program specified window gravity */ typedef struct { char *res_name; char *res_class; } XClassHint; .Pe .Nd 15 .SH "Errors" \f(CWBadAlloc\fR .br \f(CWBadWindow\fR .SH "See Also" \s-1\fIXSetWMClientMachine()\fP\s+1, \s-1\fIXSetWMColormapWindows()\fP\s+1, \s-1\fIXSetWMHints()\fP\s+1, \s-1\fIXSetWMNormalHints()\fP\s+1, \s-1\fIXSetWMProperties()\fP\s+1, \s-1\fIXSetWMProtocols()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XmbTextEscapement" "Xlib \- Internationalized Text" .ds ]W Xlib Reference Manual .XX "XmbTextEscapement" .XX "text:escapement, obtaining" .SH Name .Na XmbTextEscapement \(en obtain the width of internationalized multi-byte text. .Nz .SH Synopsis .Sy int XmbTextEscapement\^(\^\f(CIfont_set\fP\^, \f(CIstring\fP\^, \f(CInum_bytes\fP\^) .As XFontSet \f(CIfont_set\fP\^; char *\f(CIstring\fP\^; int \f(CInum_bytes\fP\^; .Ae .SH Arguments .IP \f(CIfont_set\fP 1i Specifies the font set. .IP \f(CIstring\fP 1i Specifies the character string. .IP \f(CInum_bytes\fP 1i Specifies the number of bytes in the string argument. .SH Returns Escapement in pixels. .SH Availability Release 5 and later. .SH Description \f(CWXmbTextEscapement()\fR returns the escapement in pixels of the specified multi-byte string using the fonts loaded for the specified font set. The escapement is the distance in pixels in the primary draw direction from the drawing origin to the origin of the next character to be drawn, assuming that the rendering of the next character is not dependent on the supplied string. .LP The escapement is always positive, regardless of the character-rendering order. .SH "See Also" \s-1\fIXmbTextExtents()\fP\s+1, \s-1\fIXmbTextPerCharExtents()\fP\s+1, \s-1\fIXwcTextEscapement()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XmbTextExtents" "Xlib \- Internationalized Text" .ds ]W Xlib Reference Manual .XX "XmbTextExtents" .XX "text:events, computing" .SH Name .Na XmbTextExtents \(en compute the extents of internationalized multi-byte text. .Nz .SH Synopsis .Sy int XmbTextExtents\^(\^\f(CIfont_set\fP\^, \f(CIstring\fP\^, \f(CInum_bytes\fP\^, \f(CIoverall_ink_return\fP\^, .br \f(CIoverall_logical_return\fP\^) .As XFontSet \f(CIfont_set\fP\^; char *\f(CIstring\fP\^; int \f(CInum_bytes\fP\^; XRectangle *\f(CIoverall_ink_return\fP\^; XRectangle *\f(CIoverall_logical_return\fP\^; .Ae .SH Arguments .IP \f(CIfont_set\fP 1i Specifies the font set. .IP \f(CIstring\fP 1i Specifies the character string. .IP \f(CInum_bytes\fP 1i Specifies the number of bytes in the string argument. .ds Ov dimensions .IP \f(CIoverall_ink_return\fP 1i Returns the overall ink \*(Ov. .IP \f(CIoverall_logical_return\fP 1i Returns the overall logical \*(Ov. .SH Returns Escapement in pixels. .SH Availability Release 5 and later. .SH Description \f(CWXmbTextExtents()\fR sets the components of the specified \f(CIoverall_ink_return\fP and \f(CIoverall_logical_return\fP arguments to the overall bounding box of the string's image, and the overall logical bounding box of the string's image plus inter-line and inter-character spacing. It returns the value returned by \f(CWXmbTextEscapement()\fR. The returned metrics are relative to the drawing origin of the string, using the fonts loaded for the specified font set. .LP If the \f(CIoverall_ink_return\fP argument is non-\f(CWNULL\fP, it is set to the bounding box of the string's character ink. Note that the \f(CIoverall_ink_return\fP for a non-descending hor\%izontally drawn Latin character is conventionally entirely above the baseline, that is,\p \f(CIoverall_ink_return.height\fP <= \f(CI-overall_ink_return.y\fP. The \f(CIoverall_ink_return\fP for a nonkerned character is entirely at and to the right of the origin, that is, \f(CIoverall_ink_return.x\fP >= 0. A character consisting of a single pixel at the origin would have \f(CIoverall_ink_return\fP fields \f(CIy\fP = 0, \f(CIx\fP = 0, \f(CIwidth\fP = 1, and \f(CIheight\fP = 1. .Nd 10 .LP If the \f(CIoverall_logical_return\fP argument is non-\f(CWNULL\fP, it is set to the bounding box which provides minimum spacing to other graphical features for the string. Other graphical features, for example, a border surrounding the text, should not intersect this rectangle. .LP When the \f(CWXFontSet\fR has missing charsets, metrics for each unavailable character are taken from the default string returned by \f(CWXCreateFontSet()\fR so that the metrics represent the text as it will actually be drawn. The behavior for an invalid codepoint is undefined. .SH "Structures" .Ps typedef struct { short x, y; unsigned short width, height; } XRectangle; .Pe .SH "See Also" \s-1\fIXmbTextEscapement()\fP\s+1, \s-1\fIXmbTextPerCharExtents()\fP\s+1, \s-1\fIXwcTextExtents()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XmbTextListToTextProperty" "Xlib \- Text Encoding Conversions" .ds ]W Xlib Reference Manual .XX "XmbTextListToTextProperty" .XX "text lists:converting to text properties" .XX "text properties:converting to text lists" .SH Name .Na XmbTextListToTextProperty \(en convert an internationalized multi-byte text list to a text property structure. .Nz .SH Synopsis .Sy int XmbTextListToTextProperty\^(\^\f(CIdisplay\fP\^, \f(CIlist\fP\^, \f(CIcount\fP\^, \f(CIstyle\fP\^, \f(CItext_prop_return\fP\^) .As Display *\f(CIdisplay\fP\^; char **\f(CIlist\fP\^; int \f(CIcount\fP\^; XICCEncodingStyle \f(CIstyle\fP\^; XTextProperty *\f(CItext_prop_return\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIlist\fP 1i Specifies an array of \f(CWNULL\fP-terminated multi-byte strings. .IP \f(CIcount\fP 1i Specifies the number of strings specified. .IP \f(CIstyle\fP 1i Specifies the manner in which the property is encoded. .IP \f(CItext_prop_return\fP 1i Returns the \f(CWXTextProperty\fR structure. .SH Returns \f(CWSuccess\fR on success. \f(CWXNoMemory\fR or \f(CWXLocaleNotSupported\fR on failure. .SH Availability Release 5 and later. .SH Description \f(CWXmbTextListToTextProperty()\fR sets the specified \f(CWXTextProperty\fR value to a set of null-separated elements representing the concatenation of the specified list of \f(CWNULL\fP-terminated text strings. A final terminating null is stored at the end of the \f(CIvalue\fP field of \f(CItext_prop_return\fP but is not included in the \f(CInitems\fP field. .LP \f(CWXmbTextListToTextProperty()\fR sets the encoding field of \f(CItext_prop_return\fP to an Atom (for the specified display), which names the encoding specified by \f(CIstyle\fR, and converts the specified text list to this encoding for storage in the value field of \f(CItext_prop_return\fP. If the style \f(CWXStringStyle\fR or \f(CWXCompoundTextStyle\fR is specified, this encoding is STRING or COMPOUND_TEXT, respectively. If the style \f(CWXTextStyle\fR is specified, this encoding is the encoding of the current locale. If the style \f(CWXStdICCTextStyle\fR is specified, this encoding is STRING if the text is fully convertible to STRING, otherwise it is COMPOUND_TEXT. .LP If insufficient memory is available for the new value string, \f(CWXmbTextListToTextProperty()\fR returns \f(CWXNoMemory\fR. If the current locale is not supported, it returns \f(CWXLocaleNotSupported\fR. In both of these error cases, it does not set \f(CItext_prop_return\fP. \f(CWXmbTextListToTextProperty()\fP will not return \f(CWXLocaleNotSupported\fP if \f(CWXSupportsLocale()\fP has returned \f(CWTrue\fP for the current locale. .LP If the supplied text is not fully convertible to the specified encoding, \f(CWXmbTextListToTextProperty()\fR returns the number of unconvertible characters. Each unconvertible character is converted to an implementation-defined and encoding-specific default string. If the text is fully convertible, \f(CWXmbTextListToTextProperty()\fR returns \f(CWSuccess\fR. Note that full convertibility to all styles except \f(CWXStringStyle\fR is guaranteed. If the supplied text contains bytes that are not valid characters in the encoding of the locale ("invalid codepoints"), the result is undefined. .LP \f(CWXmbTextListToTextProperty()\fP allocates memory for the \f(CIvalue\fP field of the \f(CWXTextProperty\fP. The client is responsible for freeing this memory by calling \f(CWXFree()\fP. .SH Structures The \f(CWXTextProperty\fR structure contains: .Ps .ta 1.9i typedef struct { unsigned char *value; /* property data */ Atom encoding; /* type of property */ int format; /* 8, 16, or 32 */ unsigned long items; /* number of items in value */ } XTextProperty; .Pe The \f(CWXICCEncodingStyle\fP structure contains: .Ps .TA 1.9i .ta 1.9i typedef enum { XStringStyle, /* STRING */ XCompoundTextStyle, /* COMPOUND_TEXT */ XTextStyle, /* text in owner's encoding (current locale) */ XStdICCTextStyle /* STRING, else COMPOUND_TEXT */ } XICCEncodingStyle; .Pe The possible return values of this function are as follows: .sp 1 .in 0 .KS .TS tab(@); lw(.5i) lw(2i) lw(2.5i). \f(CW#define@XNoMemory@ \- 1 #define@XLocaleNotSupported@ \- 2 #define@XConverterNotFound@ \- 3\fR .TE .KE .in .sp 1 .SH "See Also" \s-1\fIXSetTextProperty()\fP\s+1, \s-1\fIXStringListToTextProperty()\fP\s+1, \s-1\fIXwcTextListToTextProperty()\fP\s+1, \s-1\fIXmbTextPropertyToTextList()\fP\s+1, \s-1\fIXwcTextPropertyToTextList()\fP\s+1, \s-1\fIXwcFreeStringList()\fP\s+1, \s-1\fIXDefaultString()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XmbTextPerCharExtents" "Xlib \- Internationalized Text" .ds ]W Xlib Reference Manual .XX "XmbTextPerCharExtents" .XX "text:strings, obtaining information for" .SH Name .Na XmbTextPerCharExtents \(en obtain per-character measurements of an internationalized multi-byte text string. .Nz .SH Synopsis .Sy Status XmbTextPerCharExtents\^(\^\f(CIfont_set\fP\^, \f(CIstring\fP\^, \f(CInum_bytes\fP\^, \f(CIink_array_return\fP\^, \f(CIlogical_array_return\fP\^, \f(CIarray_size\fP\^, \f(CInum_chars_return\fP\^, \f(CIoverall_ink_return\fP\^, \f(CIoverall_logical_return\fP\^) .As XFontSet \f(CIfont_set\fP\^; char *\f(CIstring\fP\^; int \f(CInum_bytes\fP\^; XRectangle *\f(CIink_array_return\fP\^; XRectangle *\f(CIlogical_array_return\fP\^; int \f(CIarray_size\fP\^; int *\f(CInum_chars_return\fP\^; XRectangle *\f(CIoverall_ink_return\fP\^; XRectangle *\f(CIoverall_logical_return\fP\^; .Ae .hw logical .SH Arguments .IP \f(CIfont_set\fP 1i Specifies the font set. .IP \f(CIstring\fP 1i Specifies the character string. .IP \f(CInum_bytes\fP 1i Specifies the number of bytes in the string argument. .IP \f(CIink_array_return\fP 1i Returns the ink dimensions for each character. .IP \f(CIlogical_array_return\fP 1i Returns the logical dimensions for each character. .IP \f(CIarray_size\fP 1i Specifies the size of \s-1\f(CIink_array_return\fP\s+1 and \s-1\f(CIlogical_array_return\fP\s+1. Note that the caller must pass in arrays of this size. .IP \f(CInum_chars_return\fP 1i Returns the number characters in the string argument. .ds Ov extents of the entire string .IP \f(CIoverall_ink_return\fP 1i Returns the overall ink \*(Ov. .IP \f(CIoverall_logical_return\fP 1i Returns the overall logical \*(Ov. .SH Returns Zero on failure, non-zero on success. .Nd 15 .SH Availability Release 5 and later. .hw logical .hw overall .SH Description \f(CWXmbTextPerCharExtents()\fR returns the text dimensions of each character of the specified text, using the fonts loaded for the specified font set. Each element of \f(CIink_array_return\fP and \f(CIlogical_array_return\fP is set to the corresponding character's drawn metrics, relative to the drawing origin of the string. The .ne 6 number of elements of \f(CIink_array_return\fP and \f(CIlogical_array_return\fP that have been set is returned in \f(CInum_chars_return\fP. .LP Each element of \f(CIink_array_return\fP is set to the bounding box of the corresponding character's drawn foreground color. Each element of \f(CIlogical_array_return\fP is set to the bounding box which provides minimum spacing to other graphical features for the corresponding character. Other graphical features should not intersect any of the \f(CIlogical_array_return\fP rectangles. .LP Note that an \f(CWXRectangle\fR represents the effective drawing dimensions of the character, regardless of the number of font glyphs that are used to draw the character, or the direction in which the character is drawn. If multiple characters map to a single character glyph, the dimensions of all the \f(CWXRectangles\fR of those characters are the same. .LP When the \f(CWXFontSet\fR has missing charsets, metrics for each unavailable character are taken from the default string returned by \f(CWXCreateFontSet()\fR, so that the metrics represent the text as it will actually be drawn. The behavior for an invalid codepoint is undefined. .LP If the \f(CIarray_size\fP is too small for the number of characters in the supplied text, the function returns zero and \f(CInum_chars_return\fP is set to the number of rectangles required. Otherwise, it returns a non-zero value. .LP If the \f(CIoverall_ink_return\fP or \f(CIoverall_logical_return\fP argument is non-\f(CWNULL\fP, \f(CWXmbTextPerCharExtents()\fR returns the maximum extent of the string's metrics to \f(CIoverall_ink_return\fP or \f(CIoverall_logical_return\fP, as is done by \f(CWXmbTextExtents()\fR. .SH "Structures" .Ps typedef struct { short x, y; unsigned short width, height; } XRectangle; .Pe .SH "See Also" \s-1\fIXmbTextEscapement()\fP\s+1, \s-1\fIXmbTextExtents()\fP\s+1, \s-1\fIXwcTextPerCharExtents()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XmbTextPropertyToTextList" "Xlib \- Text Encoding Conversions" .ds ]W Xlib Reference Manual .XX "XmbTextPropertyToTextList" .XX "text properties:converting to multi-byte string lists" .SH Name .Na XmbTextPropertyToTextList \(en convert an internationalized text property to a list of multi-byte strings. .Nz .SH Synopsis .Sy int XmbTextPropertyToTextList\^(\^\f(CIdisplay\fP\^, \f(CItext_prop\fP\^, \f(CIlist_return\fP\^, \f(CIcount_return\fP\^) .As Display *\f(CIdisplay\fP\^; XTextProperty *\f(CItext_prop\fP\^; char ***\f(CIlist_return\fP\^; int *\f(CIcount_return\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CItext_prop\fP 1i Specifies the \f(CWXTextProperty\fR structure to be used. .IP \f(CIlist_return\fP 1i Returns a list of \f(CWNULL\fP-terminated character strings. .ds Cn strings .IP \f(CIcount_return\fP 1i Returns the number of \*(Cn. .SH Returns \f(CWSuccess\fR on success. \f(CWXNoMemory\fR, \f(CWXLocaleNotSupported\fR, or \f(CWXConverterNotFound\fR on failure. .SH Availability Release 5 and later. .SH Description \f(CWXmbTextPropertyToTextList()\fR returns a list of multi-byte text strings encoded in the current locale representing the \f(CWNULL\fP-separated elements of the specified \f(CWXTextProperty\fR structure. The data in \f(CItext_prop\fP must be format 8. .LP Multiple elements of the property (for example, the strings in a disjoint text selection) are separated by a null byte. The contents of the property are not required to be \f(CWNULL\fP-terminated; any terminating null should not be included in \f(CItext_prop.nitems\fP. .LP If insufficient memory is available for the list and its elements, \f(CWXmbTextPropertyToTextList()\fR returns \f(CWXNoMemory\fR. If the current locale is not supported, it returns \f(CWXLocaleNotSupported\fR. If the encoding field of \f(CItext_prop\fP is not convertible to the encoding of the current locale, it returns \f(CWXConverterNotFound\fR. For supported locales, existence of a converter from COMPOUND_TEXT, STRING, or the encoding of the current locale is guaranteed although .ne 9 the actual text may contain unconvertible characters. Conversion of other encodings is implementation-dependent. In all of these error cases, the function does not set any return values. .LP Otherwise, \f(CWXmbTextPropertyToTextList()\fR returns the list of \f(CWNULL\fP-terminated text strings to \f(CIlist_return\fP, and the number of text strings to \f(CIcount_return\fP. .LP If the \f(CIvalue\fR field of \f(CItext_prop\fP is not fully convertible to the encoding of the current locale, the function returns the number of unconvertible characters. Each unconvertible character is converted to a string in the current locale that is specific to the current locale. To obtain the value of this string, use \f(CWXDefaultString()\fR. If all characters are convertible, \f(CWXmbTextPropertyToTextList()\fR returns \f(CWSuccess\fR. If the text property contains "invalid codepoints" or bytes that are not valid characters in the encoding of the property, the result is undefined. .LP To free the storage for the list and its contents returned by \f(CWXmbTextPropertyToTextList()\fR, use \f(CWXFreeStringList()\fR. .SH Structures The \f(CWXTextProperty\fR structure contains: .Ps .TA .5i 2.5i .ta .5i 2.5i typedef struct { unsigned char *value; /* property data */ Atom encoding; /* type of property */ int format; /* 8, 16, or 32 */ unsigned long nitems; /* number of items in value */ } XTextProperty; .Pe The possible return values of this function are as follows: .sp 1 .in 0 .KS .TS tab(@); lw(.5i) lw(2i) lw(2.5i). \f(CW#define@XNoMemory@ \- 1 #define@XLocaleNotSupported@ \- 2 #define@XConverterNotFound@ \- 3\fR .TE .KE .in .sp 1 .SH "See Also" \s-1\fIXSetTextProperty()\fP\s+1, \s-1\fIXStringListToTextProperty()\fP\s+1, \s-1\fIXDefaultString()\fP\s+1, \s-1\fIXmbTextListToTextProperty()\fP\s+1, \s-1\fIXwcFreeStringList()\fP\s+1, \s-1\fIXwcTextListToTextProperty()\fP\s+1, \s-1\fIXwcTextPropertyToTextList()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "Xpermalloc" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "Xpermalloc" .XX "memory:allocating permanently" .Na Xpermalloc \(en allocate memory never to be freed. .Nz .SH "Synopsis" .Sy char *Xpermalloc\^(\^\f(CIsize\fP\^) .As unsigned int \f(CIsize\fP\^; .SH "Arguments" .IP \f(CIsize\fP 1i Specifies the size in bytes of the space to be allocated. This specification is rounded to the nearest 4-byte boundary. .SH Returns A pointer to the allocated memory. .SH Description \f(CWXpermalloc()\fP allocates some memory that will not be freed until the process exits. \f(CWXperm\%alloc\fP is used by some toolkits for permanently allocated storage and allows some performance and space savings over the completely general memory allocator. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmClassToString" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmClassToString" .XX "quarks:converting to strings" .XX "strings:converting from quarks" .Na XrmClassToString \(en convert a quark to a string. .Nz .SH "Synopsis" .Sy #define XrmClassToString(class) XrmQuarkToString(class) .in char *XrmQuarkToString\^(\^\f(CIquark\fP\^) .As XrmQuark \f(CIquark\fP\^; .Ae .SH "Arguments" .IP \f(CIquark\fP 1i Specifies the quark for which the equivalent string is desired. .SH Returns The string. .SH Description .XX "XrmQuarkToString:and XrmClassToString" \f(CWXrmClassToString\fP is an alias for \f(CWXrmQuarkToString()\fP. It returns the string for which the specified quark is serving as a shorthand symbol. The quark was earlier set to represent the string by \f(CWXrmStringToQuark()\fP or \f(CWXrmStringToClass()\fP. The string pointed to by the return value must not be modified or freed, because that string is in the data structure used by the resource manager for assigning quarks. If no string exists for that quark, \f(CWXrmClassToString\fP returns \f(CWNULL\fP. .LP Since the resource manager needs to make many comparisons of strings when it gets data from the database, it is more efficient to convert these strings into quarks, and to compare quarks instead. Since quarks are represented by integers, comparing quarks is trivial. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" .Ps typedef int XrmQuark; .Pe .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmCombineDatabase" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .Na XrmCombineDatabase \(en combine the contents of two resource databases. .XX "XrmCombineDatabase" .XX "resource databases:combining contents of" .XN "databases:resource (see resource databases)" .Nz .\" .\" .SH "Synopsis" .Sy void XrmCombineDatabase(\f(CIsource_db\fP, \f(CItarget_db\fP, \f(CIoverride\fP) .As XrmDatabase \f(CIsource_db\fP; XrmDatabase *\f(CItarget_db\fP; Bool \f(CIoverride\fP; .Ae .\" .\" .SH "Arguments" .IP \f(CIsource_db\fP 1i Specifies the resource database that is to be merged into the target database. .IP \f(CItarget_db\fP 1i Specifies the address of the resource database with which the resource file is to be combined. .IP \f(CIoverride\fP 1i Specifies whether resources from \f(CIsource_db\fP should override matching resources in \f(CItarget_db\fP. .\" .\" .SH "Availability" Release 5 and later. .\" .\" .SH Description \f(CWXrmCombineDatabase()\fP merges the contents of one database into another. If the same resource specifier is used for an entry in both databases, the entry in \f(CIsource_db\fP will replace the entry in \f(CItarget_db\fP if \f(CIoverride\fP is \f(CWTrue\fP; otherwise, the entry in from \f(CIsource_db\fP is discarded. .LP If \f(CItarget_db\fP points to a \f(CWNULL\fP database, \f(CWXrmCombineDatabase()\fP simply stores \f(CIsource_db\fP at the location pointed to by \f(CItarget_db\fP. Otherwise, \f(CIsource_db\fP is destroyed by the merge, and the database pointed to by \f(CItarget_db\fP is not destroyed. .LP The database entries are merged without changing values or types, regardless of the locales of the databases. The locale of the target database is not modified. .\" .\" .SH "See Also" \s-1\fIXrmCombineFileDatabase()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmCombineFileDatabase" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .Na XrmCombineFileDatabase \(en combine the contents of a resource file and a resource database. .XX "XrmCombineFileDatabase" .XX "resource databases:combining with resource files" .XX "resource files:combining with resource databases" .XN "files:resource (see resource files)" .Nz .\" .\" .SH "Synopsis" .Sy Status XrmCombineFileDatabase(\f(CIfilename\fP, \f(CItarget_db\fP, \f(CIoverride\fP) .As char *\f(CIfilename\fP; XrmDatabase *\f(CItarget_db\fP; Bool \f(CIoverride\fP; .Ae .\" .\" .SH "Arguments" .IP \f(CIfilename\fP 1i Specifies the name of the resource file. .IP \f(CItarget_db\fP 1i Specifies the address of the resource database with which the resource file is to be combined. .IP \f(CIoverride\fP 1i Specifies whether resources from the file should override matching resources in the database. .\" .\" .SH Returns Zero on failure, non-zero on success. .SH "Availability" Release 5 and later. .\" .\" .SH Description \f(CWXrmCombineFileDatabase()\fP merges the contents of a resource file into a database. If the same resource specifier is used for an entry in both the file and the database, the entry in the file will replace the entry in the database if \f(CIoverride\fP is \f(CWTrue\fP; otherwise, the entry in the file is discarded. .LP If \f(CItarget_db\fP points to a \f(CWNULL\fP database, \f(CWXrmCombineFileDatabase()\fP creates a new database, reads the file into it and stores this new database at the location pointed to by\p \f(CItarget_db\fP. Otherwise, the database pointed to by \f(CItarget_db\fP is not destroyed by the merge. .LP If the file cannot be read a zero status is returned; otherwise a non-zero status is returned. .LP The file is parsed in the current locale. The database entries are merged without changing values or types, regardless of the locale of the database, and the locale of the target database is not modified. .\" .\" .SH "See Also" \s-1\fIXrmCombineDatabase()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmDestroyDatabase" "Xlib \- Window Manager Hints" .ds ]W Xlib Reference Manual\"R4 .SH "Name" .XX "XrmDestroyDatabase" .XX "resource databases:destroying" .XX "databases:(see also resource databases)" .Na XrmDestroyDatabase \(en destroy a resource database. .Nz .SH "Synopsis" .Sy void XrmDestroyDatabase\^(\^\f(CIdatabase\fP\^) .As XrmDatabase \f(CIdatabase\fP\^; .Ae .SH "Arguments" .IP \f(CIdatabase\fP 1i Specifies the resource database. .SH "Availability" Release 4 and later. .SH Description \f(CWXrmDestroyDatabase()\fP destroys a resource database and frees its allocated memory. The destroyed resource database should not be referenced again. If \f(CIdatabase\fP is \f(CWNULL\fP, \f(CWXrmDestroyDatabase()\fR returns immediately. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fP. .SH "See Also" \s-1\fIXrmMergeDatabases()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmEnumerateDatabase" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .XX "XrmEnumerateDatabase" .XX "resource databases:enumerating entries" .SH Name .Na XrmEnumerateDatabase \(en enumerate resource database entries. .Nz .SH Synopsis .Sy Bool XrmEnumerateDatabase\^(\^\f(CIdatabase\fP, \f(CIname_prefix\fP, \f(CIclass_prefix\fP, \f(CImode\fP, .br \f(CIproc\fP, \f(CIarg\fP\^) .As XrmDatabase \f(CIdatabase\fP\^; XrmNameList \f(CIname_prefix\fP\^; XrmClassList \f(CIclass_prefix\fP\^; int \f(CImode\fP\^; Bool (\^*\f(CIproc\fP\^)\^(\^)\^; XPointer \f(CIarg\fP\^; .Ae .SH Arguments .IP \f(CIdatabase\fP 1i Specifies the resource database. .IP \f(CIname_prefix\fP 1i Specifies the resource name prefix. .IP \f(CIclass_prefix\fP 1i Specifies the resource class prefix. .IP \f(CImode\fP 1i Specifies the number of levels to enumerate. .IP \f(CIproc\fP 1i Specifies the procedure that is to be called for each matching entry. .IP \f(CIarg\fP 1i Specifies the user-supplied argument that will be passed to the procedure. .SH Returns \f(CWTrue\fP or \f(CWFalse\fP, as returned by \f(CIproc\fP. .SH Availability Release 5 and later. .SH Description \f(CWXrmEnumerateDatabase()\fR calls the specified procedure for each resource in the database that would match some completion of the given name/class resource prefix. The order in which resources are found is implementation-dependent. If \f(CImode\fR is \f(CWXrmEnumOneLevel\fR, then a resource must match the given name/class prefix with just a single name and class appended. If \f(CImode\fR is \f(CWXrmEnumAllLevels\fR, the resource must match the given name/class prefix with one or more names and classes appended. If the procedure returns \f(CWTrue\fR, the enumeration terminates and the function returns \f(CWTrue\fR. If the procedure always returns \f(CWFalse\fR, all matching resources are enumerated and the function returns \f(CWFalse\fR. .LP .Nd 5 The procedure is called with the following arguments: .LP .\" Start marker code here .DS 0 .TA .5i 3i .ta .5i 3i (*\f(CIproc\fP\^)(\^\f(CIdatabase\fP, \f(CIbindings\fP, \f(CIquarks\fP, \f(CItype\fP, \f(CIvalue\fP, \f(CIarg\fP\^) \f(CWXrmDatabase()\fP *\f(CIdatabase\fP\^; XrmBindingList \f(CIbindings\fP\^; XrmQuarkList \f(CIquarks\fP\^; XrmRepresentation *\f(CItype\fP\^; XrmValue *\f(CIvalue\fP\^; XPointer \f(CIclosure\fP\^; .DE .\" End marker code here .LP The bindings and quarks lists are terminated by \f(CWNULLQUARK\fR. Note that pointers to the database and type are passed, but these values should not be modified. .SH Structures The legal values for the \f(CImode\fP argument are: .sp 1 .in 0 #define \f(CWXrmEnumAllLevels\fR 0 .sp .5 #define \f(CWXrmEnumOneLevel\fR 1 .in .sp 1 .SH "See Also" \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmGetDatabase" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .XX "XrmGetDatabase" .XX "resource databases:retrieving" .SH Name .Na XrmGetDatabase \(en retrieve the resource database associated with a display. .Nz .SH Synopsis .Sy XrmDatabase XrmGetDatabase\^(\^\f(CIdisplay\fP\^) .As Display *\f(CIdisplay\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .SH Returns The database. .SH Availability Release 5 and later. .SH Description \f(CWXrmGetDatabase()\fR returns the database associated with the specified display. It returns \f(CWNULL\fP if a database has not yet been set with \f(CWXrmSetDatabase()\fR. .SH "See Also" \s-1\fIXrmSetDatabase()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmGetFileDatabase" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmGetFileDatabase" .XX "resource databases:retrieving from a file" .Na XrmGetFileDatabase \(en retrieve a database from a file. .Nz .SH "Synopsis" .Sy XrmDatabase XrmGetFileDatabase\^(\^\f(CIfilename\fP\^) .As char *\f(CIfilename\fP\^; .Ae .SH "Arguments" .IP \f(CIfilename\fP 1i Specifies the resource database filename. .SH Returns The database. .Nd 5 .SH Description \f(CWXrmGetFileDatabase()\fP opens the specified file, creates a new resource database, and loads the database with the data read in from the file. The return value of the function is as a pointer to the created database. .LP The specified file must contain lines in the format accepted by \f(CWXrmPutLineResource()\fP. The file is parsed in the current locale and the database is created in the current locale. If \f(CWXrmGetFileDatabase()\fP cannot open the specified file, it returns \f(CWNULL\fP. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" \f(CWXrmDatabase\fP is a pointer to an opaque data type. .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .de Su \" if $1 = +, this gives a superscript; $1 = - gives a subscript. . \" If 3 args, $2=regular text; $3=super/subscripted text w/pre-space . \" If 2 args, $1=super/subscripted text with post-space .if "\\$1"+" \{\ . if \\n(.$=3 \\$2\v'-3p'\s-3\h'2p'\\$3\v'3p'\s0 . if \\n(.$=2 \v'-3p'\s-3\\$2\v'3p'\s0\h'2p'\} .if "\\$1"-" \{\ . if \\n(.$=3 \\$2\v'3p'\s-3\h'2p'\\$3\v'-3p'\s0 . if \\n(.$=2 \v'3p'\s-3\\$2\v'-3p'\s0\h'2p'\} .. .RH "XrmGetResource" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmGetResource" .Na XrmGetResource \(en get a resource from name and class as strings. .Nz .SH "Synopsis" .Sy Bool XrmGetResource\^(\^\f(CIdatabase\fP, \f(CIstr_name\fP, \f(CIstr_class\fP, \f(CIstr_type_return\fP, .br \f(CIvalue_return\fP\^) .As XrmDatabase \f(CIdatabase\fP\^; char *\f(CIstr_name\fP\^; char *\f(CIstr_class\fP\^; char **\f(CIstr_type_return\fP\^; XrmValue *\f(CIvalue_return\fP\^; .Ae .SH "Arguments" .IP \f(CIdatabase\fP 1i Specifies the database that is to be used. .IP \f(CIstr_name\fP 1i Specifies the fully qualified name of the value being retrieved. .IP \f(CIstr_class\fP 1i Specifies the fully qualified class of the value being retrieved. .IP \f(CIstr_type_return\fP 1i Returns a pointer to the representation type of the destination. In this function, the representation type is represented as a string, not as an \f(CWXrmRepresentation\fP. .IP \f(CIvalue_return\fP 1i Returns the value in the database. Do not modify or free this data. .SH Returns \f(CWTrue\fP if the resource was found, else \f(CWFalse\fP. .SH Description .XX "resources:retrieving from a database" .XX "databases:retrieving a resource from" \f(CWXrmGetResource()\fP retrieves a resource from the specified database. It takes a fully qualified name/class pair, a destination resource representation, and the address of a value (size/address pair). The value and returned type point into database memory; therefore, you must not modify the data. .LP The database only frees or overwrites entries on \f(CWXrmPutResource()\fP, \f(CWXrmQPutResource()\fP, or \f(CWXrmMergeDatabases()\fP. A client that is not storing new values into the database or is not merging the database should be safe using the address passed back at any time until it exits. If a resource was found, \f(CWXrmGetResource()\fP returns \f(CWTrue\fP; otherwise it returns \f(CWFalse\fP. .LP Most applications and toolkits do not make random probes into a resource database to fetch resources. The X toolkit access pattern for a resource database is quite stylized. A series of from 1 to 20 probes are made with only the last name/class differing in each probe. \f(CWXrmGetResource()\fP uses at worst a .Su + 2 \fIn\fR algorithm, where \fIn\fP is the length of the name/class list. This can be improved upon by the application programmer by prefetching a list of database levels that might match the first part of a name/class list. .SH "Structures" \f(CWXrmDatabase\fP is a pointer to an opaque data type. .Ps typedef struct { unsigned int size; XPointer addr; } XrmValue; .Pe .ne 8 .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmGetStringDatabase" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmGetStringDatabase" .XX "databases:creating from a string" .Na XrmGetStringDatabase \(en create a database from a string. .Nz .SH "Synopsis" .Sy XrmDatabase XrmGetStringDatabase\^(\^\f(CIdata\fP\^) .As char *\f(CIdata\fP\^; .Ae .SH "Arguments" .IP \f(CIdata\fP 1i Specifies the database contents using a string. .SH Returns The created database. .SH Description \f(CWXrmGetStringDatabase()\fP creates a new database and stores in it the resources specified in \f(CIdata\fP. The return value is subsequently used to refer to the created database. \f(CWXrmGetStringDatabase()\fP is similar to \f(CWXrmGetFileDatabase()\fP, except that it reads the information out of a string instead of a file. Each line in the string is separated by a new line character in the format accepted by \f(CWXrmPutLineResource()\fP. The string is parsed in the current locale and the database is created in the current locale. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" \f(CWXrmDatabase\fP is a pointer to an opaque data type. .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmInitialize" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmInitialize" .Na XrmInitialize \(en initialize the resource manager. .XX "resource manager:initializing" .Nz .SH "Synopsis" .Sy void XrmInitialize\^(\ ); .SH Description \f(CWXrmInitialize()\fP initializes the resource manager, and should be called once before using any other resource manager functions. It just creates a representation type of "String" for values defined as strings. This representation type is used by \f(CWXrmPutStringResource()\fP and \f(CWXrmQPutStringResource()\fP, which require a value as a string. See \f(CWXrmQPutResource()\fP for a description of representation types. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmLocaleOfDatabase" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .XX "XrmLocaleOfDatabase" .XX "locale:resource database, returning" .XX "resource databases:returning locale of" .SH Name .Na XrmLocaleOfDatabase \(en return the locale of a resource database. .Nz .SH Synopsis .Sy char *XrmLocaleOfDatabase\^(\^\f(CIdatabase\fP\^) .As XrmDatabase \f(CIdatabase\fP\^; .Ae .SH Arguments .IP \f(CIdatabase\fP 1i Specifies the database that is to be used. .SH Returns The locale string. .SH Availability Release 5 and later. .SH Description \f(CWXrmLocaleOfDatabase()\fR returns the name of the locale bound to the specified database, as a \f(CWNULL\fP-terminated string. The returned locale name string is owned by Xlib and should not be modified or freed by the client. Xlib is not permitted to free the string until the database is destroyed. Until the string is freed, it will not be modified by Xlib. .SH "See Also" \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmDestroyDatabase()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmMergeDatabases" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmMergeDatabases" .XX "databases:merging" .Na XrmMergeDatabases \(en merge the contents of one database into another. .Nz .SH "Synopsis" .Sy void XrmMergeDatabases(\^\f(CIsource_db\f(CW, \f(CItarget_db\f(CW\^) .As XrmDatabase \f(CIsource_db\f(CW, *\f(CItarget_db\f(CW\^; .Ae .SH "Arguments" .IP \f(CIsource_db\fP 1i Specifies the resource database to be merged into the existing database. .IP \f(CItarget_db\fP 1i Specifies a pointer to the resource database into which the \f(CIsource_db\fP database will be merged. .SH Description \f(CWXrmMergeDatabases()\fP merges \f(CIsource_db\fP into \f(CItarget_db\fP. This procedure is used to combine databases, for example, an application specific database of defaults and a database of user preferences. If the same specifier is used for an entry in both databases, the entry in the \f(CIsource_db\fP will replace the entry in the \f(CItarget_db\fP (that is, it overrides\p \f(CItarget_db\fP). If \f(CItarget_db\fP is \f(CWNULL\fP, \f(CWXrmMergeDatabases()\fP simply stores \f(CIsource_db\fP in it. Otherwise, \f(CIsource_db\fP is destroyed by the merge, but the database pointed to by \f(CItarget_db\fP is not destroyed. The database entries are merged without changing values or types, regardless of the locales of the databases. The locale of the target database is not modified. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH Structures \f(CWXrmDatabase\fP is a pointer to an opaque data type. .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmNameToString" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .Na .XX "XrmNameToString" .XX "quarks:converting to strings" .XX "strings:converting from quarks" XrmNameToString \(en convert a quark to a string. .Nz .SH "Synopsis" .Sy #define XrmNameToString(name) XrmQuarkToString(name) .in char *XrmQuarkToString\^(\^\f(CIquark\fP\^) .As XrmQuark \f(CIquark\fP\^; .Ae .SH "Arguments" .IP \f(CIquark\fP 1i Specifies the quark for which the equivalent string is desired. .SH Returns The string. .SH Description .XX "XrmQuarkToString:and XrmNameToString" \f(CWXrmNameToString\fP is an alias for \f(CWXrmQuarkToString()\fP. It returns the string for which the specified quark is serving as a shorthand symbol. The quark was determined earlier using \f(CWXrmStringToQuark\fP or \f(CWXrmStringToName()\fP. The string pointed to by the return value must not be modified or freed, because that string is in the data structure used by the resource manager for assigning quarks. If no string exists for that quark, \f(CWXrmNameToString\fP returns \f(CWNULL\fP. .LP Since the resource manager needs to make many comparisons of strings when it gets data from the database, it is more efficient to convert these strings into quarks, and to compare quarks instead. Since quarks are represented by integers, comparing quarks is trivial. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" .Ps typedef int XrmQuark; .Pe .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmParseCommand" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmParseCommand" .Na XrmParseCommand \(en load a resource database from command-line arguments. .Nz .SH "Synopsis" .Sy void XrmParseCommand\^(\^\f(CIdatabase\fP\^, \^\f(CItable\fP\^, \^\f(CItable_count\fP\^, \^\f(CIname\fP\^, \^\f(CIargc_in_out\fP\^, \^\f(CIargv_in_out\fP\^) .As XrmDatabase *\f(CIdatabase\fP\^; XrmOptionDescList \f(CItable\fP\^; int \f(CItable_count\fP\^; char *\f(CIname\fP\^; int *\f(CIargc_in_out\fP\^; char **\f(CIargv_in_out\fP\^; .Ae .SH "Arguments" .IP \f(CIdatabase\fP 1i Specifies a pointer to the resource database. If \f(CIdatabase\fP contains \f(CWNULL\fP, a new resource database is created and a pointer to it is returned in \f(CIdatabase\fP. If a database is created, it is created in the current locale. .IP \f(CItable\fP 1i Specifies table of command-line arguments to be parsed. .IP \f(CItable_count\fP 1i Specifies the number of entries in the table. .IP \f(CIname\fP 1i Specifies the application name. .IP \f(CIargc_in_out\fP 1i Before the call, specifies the number of arguments. After the call, returns the number of arguments not parsed. .IP \f(CIargv_in_out\fP 1i Before the call, specifies a pointer to the command-line arguments. After the call, returns a pointer to a string containing the command-line arguments that could not be parsed. .SH Description \f(CWXrmParseCommand()\fP parses an (\f(CIargc_in_out\fP, \f(CIargv_in_out\fP) pair according to the specified option table, loads recognized options into the specified database with the type "String" and modifies the (\f(CIargc_in_out\fP, \f(CIargv_in_out\fP) pair to remove all recognized options. .LP The specified table is used to parse the command line. Recognized entries in the table are removed from \f(CIargv_in_out\fP, and entries are made in the specified resource database. The table entries contain information on the option string, the option name, which style of option and a value to provide if the option kind is \f(CWXrmoptionNoArg\fP. See the example table below. The option names are compared byte-for-byte to arguments in \f(CIargv\fP, independent of any locale. The resource values given in the table are stored in the resource database without modification. All resource database entries are created using a "String" representation type. .LP \f(CIargc_in_out\fP specifies the number of arguments in \f(CIargv_in_out\fP and is set to the remaining number of arguments that were not parsed. \f(CIname\fP should be the name of your application for use in building the database entry. \f(CIname\fP is prepended to the \f(CWspecifier\fP in the option table before storing the specification. No separating (binding) character is inserted. The table must contain either a dot (.) or an asterisk (*) as the first character in each \f(CWspecifier\fP entry. The \f(CWspecifier\fP entry can contain multiple components. If the name arguments and the specifiers are not in the Host Portable Character Encoding, the result is implementation-dependent. .LP The following is a typical options table: .LP .\"ta 1.05i 2.9i 4.35i .nf .ft CW .ps 8 .vs 10 static XrmOptionDescRec opTable[\ \ ] = { {\&"\&-background\&"\&, \&"\&*background\&"\&, XrmoptionSepArg, (XPointer) NULL}, {\&"\&-bd\&"\&, \&"\&*borderColor\&"\&, XrmoptionSepArg, (XPointer) NULL}, {\&"\&-bg\&"\&, \&"\&*background\&"\&, XrmoptionSepArg, (XPointer) NULL}, {\&"\&-borderwidth\&"\&, \&"\&*TopLevelShell.borderWidth\&"\&, XrmoptionSepArg, (XPointer) NULL}, {\&"\&-bordercolor\&"\&, \&"\&*borderColor\&"\&, XrmoptionSepArg, (XPointer) NULL}, {\&"\&-bw\&"\&, \&"\&*TopLevelShell.borderWidth\&"\&, XrmoptionSepArg, (XPointer) NULL}, {\&"\&-display\&"\&, \&"\&.display\&"\&, XrmoptionSepArg, (XPointer) NULL}, {\&"\&-fg\&"\&, \&"\&*foreground\&"\&, XrmoptionSepArg, (XPointer) NULL}, {\&"\&-fn\&"\&, \&"\&*font\&"\&, XrmoptionSepArg, (XPointer) NULL}, {\&"\&-font\&"\&, \&"\&*font\&"\&, XrmoptionSepArg, (XPointer) NULL}, {\&"\&-foreground\&"\&, \&"\&*foreground\&"\&, XrmoptionSepArg, (XPointer) NULL}, {\&"\&-geometry\&"\&, \&"\&.TopLevelShell.geometry\&"\&, XrmoptionSepArg, (XPointer) NULL}, {\&"\&-iconic\&"\&, \&"\&.TopLevelShell.iconic\&"\&, XrmoptionNoArg, (XPointer) \&"\&on\&"\&}, {\&"\&-name\&"\&, \&"\&.name\&"\&, XrmoptionSepArg, (XPointer) NULL}, {\&"\&-reverse\&"\&, \&"\&*reverseVideo\&"\&, XrmoptionNoArg, (XPointer) \&"\&on\&"\&}, {\&"\&-rv\&"\&, \&"\&*reverseVideo\&"\&, XrmoptionNoArg, (XPointer) \&"\&on\&"\&}, {\&"\&-synchronous\&"\&, \&"\&.synchronous\&"\&, XrmoptionNoArg, (XPointer) \&"\&on\&"\&}, {\&"\&-title\&"\&, \&"\&.TopLevelShell.title\&"\&, XrmoptionSepArg, (XPointer) NULL}, {\&"\&-xrm\&"\&, NULL, XrmoptionResArg, (XPointer) NULL}, }; .fi .ps .vs .ft R .LP In this table, if the \fI-background\fP (or \fI-bg\fP) option is used to set background colors, the stored resource specifier will match all resources of attribute background. .hw -borderwidth If the \fI-borderwidth\fP option is used, the stored resource specifier applies only to border width attributes of class \f(CWTopLevelShell\fP (that is, outermost windows, including pop-up windows). If the \fI-title\fP option is used to set a window name, only the topmost application windows receive the resource. .LP When parsing the command line, any unique unambiguous abbreviation for an option name in the table is considered a match for the option. Note that uppercase and lowercase matter. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" \f(CWXrmDatabase\fP is a pointer to an opaque data type. .Ps .ta 4.5n 1.85i typedef enum { XrmoptionNoArg, /* value is specified in OptionDescRec.value */ XrmoptionIsArg, /* value is the option string itself */ XrmoptionStickyArg, /* value is chars immediately following option */ XrmoptionSepArg, /* value is next argument in argv */ XrmoptionResArg, /* resource and value in next argument in argv */ XrmoptionSkipArg, /* ignore this option and next argument in argv */ XrmoptionSkipLine, /* ignore this option and the rest of argv */ XrmoptionSkipNArgs /* new in R4: ignore this option, skip */ /* number specified in next argument */ } XrmOptionKind; .ne 6 typedef struct { char *option; /* option specification string in argv */ char *resourceName; /* binding & resource name (w/out application name) */ XrmOptionKind argKind; /* which style of option it is */ XPointer value; /* value to provide if XrmoptionNoArg */ } XrmOptionDescRec, *XrmOptionDescList; .Pe .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmPermStringToQuark" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmPermStringToQuark" .XX "quarks:representing strings" .Na XrmPermStringToQuark \(en allocate quark for permanently allocated string. .Nz .SH "Synopsis" .Sy XrmQuark XrmPermStringToQuark\^(\^\f(CIstring\fP\^) .As char *\f(CIstring\fP\^; .Ae .SH "Arguments" .IP \f(CIstring\fP 1i Specifies the string for which a quark is to be allocated. .SH Returns The quark. .SH Description \f(CWXrmPermStringToQuark\fP returns a quark which uniquely represents a string. If the string is not in the Host Portable Character Encoding the conversion is implementation-dependent. .XX "XrmStringToQuark:versus XrmPermStringToQuark" \f(CWXrmPermStringToQuark\fP is just like \f(CWXrmStringToQuark\fP except that Xlib is permitted to assume the string argument is permanently allocated, and hence that the string can be used as the value to be returned by \f(CWXrmQuarkToString\fP. .LP If you do not want to use permanently allocated storage, use \f(CWXrmStringToQuark\fP. .SH "Structures" \f(CWXrmDatabase\fP is a pointer to an opaque data type. .SH "See Also" \fIXrmDestroyDatabase\fP, \fIXrmGetResource\fR, \fIXrmGetStringDatabase\fR, \fIXrmInitialize\fR, \fIXrmMergeDatabases\fR, \fIXrmParseCommand\fR, \fIXrmPutFileDatabase\fR, \fIXrmPutLineResource\fR, \fIXrmPutResource\fR, \fIXrmPutStringResource\fR, \fIXrmQGetResource\fR, \fIXrmQGetSearchList\fR, \fIXrmQGetSearchResource\fR, \fIXrmQPutResource\fR, \fIXrmQPutStringResource\fR, \fIXrmQuarkToString\fR, \fIXrmStringToBindingQuarkList\fR, \fIXrmStringToQuarkList\fR, \fIXrmStringToQuark\fR, \fIXrmUniqueQuark\fR. .ad b .hy 14 .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmPutFileDatabase" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmPutFileDatabase" .XX "resource databases:storing in a file" .Na XrmPutFileDatabase \(en store a resource database in a file. .Nz .SH "Synopsis" .Sy void XrmPutFileDatabase\^(\^\f(CIdatabase\fP, \f(CIstored_db\fP\^) .As XrmDatabase \f(CIdatabase\fP\^; char *\f(CIstored_db\fP\^; .Ae .SH "Arguments" .IP \f(CIdatabase\fP 1i Specifies the resource database that is to be saved. .IP \f(CIstored_db\fP 1i Specifies the filename for the stored database. .SH Description \f(CWXrmPutFileDatabase()\fP stores a copy of the specified database in the specified file. The file is a text file that contains lines in the format that is accepted by \f(CWXrmPutLineResource()\fP. The file is written in the locale of the database. Entries containing resource names that are not in the Host Portable Character Encoding, or containing values that are not in the encoding of the database locale, are written in an implementation-dependent manner. The order in which entries are written is implementation-dependent. Entries with representation types other than "String" are ignored. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" \f(CWXrmDatabase\fP is a pointer to an opaque data type. .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmPutLineResource" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmPutLineResource" .XX "resource specifications:adding to resource databases" .XX "resource databases:adding resource specifications to" .Na XrmPutLineResource \(en add a resource specification to a resource database. .Nz .SH "Synopsis" .Sy void XrmPutLineResource\^(\^\f(CIdatabase\fP, \f(CIline\fP\^) .As XrmDatabase *\f(CIdatabase\fP\^; char *\f(CIline\fP\^; .Ae .SH "Arguments" .IP \f(CIdatabase\fP 1i Specifies a pointer to the resource database. If \f(CIdatabase\fP contains \f(CWNULL\fP, a new resource database is created and a pointer to it is returned in \f(CIdatabase\fP. If a database is created, it is created in the current locale. .IP \f(CIline\fP 1i Specifies the resource name (possibly with multiple components) and value pair as a single string, in the format \f(CIresource\fP\f(CW:\fP\f(CIvalue\fP. .SH Description \f(CWXrmPutLineResource()\fP adds a single resource entry to the specified database. The line string is parsed in the locale of the database. If the resource name is not in the Host Portable Character Encoding the result is implementation-dependent. Note that comment lines are not stored. .LP .XX "XrmPutStringResource:versus XrmPutLineResource" \f(CWXrmPutLineResource()\fP is similar to \f(CWXrmPutStringResource()\fP, except that instead of having separate string arguments for the resource and its value, \f(CWXrmPutLineResource()\fP takes a single string argument (\f(CIline\fP) which consists of the resource name, a colon, then the value. Since the value is a string, it is stored into the database with representation type \f(CWString\fP. .LP Any whitespace before or after the name or colon in the \f(CIline\fP argument is ignored. The value is terminated by a new-line or a \f(CWNULL\fP character. The value may contain embedded new-line characters represented by the "\^\e" and "n" two-character pair (not the single "\^\e\^n" character), which are converted into a single linefeed character. In addition, the value may run over onto the next line; this is indicated by a "\^\e" character at the end of each line to be continued. .LP Null-terminated strings without a new line are also permitted. \f(CWXrmPutResource()\fP, \f(CWXrmQPutResource()\fP, \f(CWXrmPutStringResource()\fP, \f(CWXrmQPutStringResource()\fP and \f(CWXrmPutLineResource()\fP all store data into a database. See \f(CWXrmQPutResource()\fP for the most complete description of this process. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" \f(CWXrmDatabase\fP is a pointer to an opaque data type. .Nd 9 .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmPutResource" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmPutResource" .XX "resource databases:storing resource specifications in" .XX "resource specifications:storing in resource databases" .Na XrmPutResource \(en store a resource specification into a resource database. .Nz .SH "Synopsis" .Sy void XrmPutResource\^(\^\f(CIdatabase\fP, \f(CIspecifier\fP, \f(CItype\fP, \f(CIvalue\fP\^) .As XrmDatabase *\f(CIdatabase\fP\^; char *\f(CIspecifier\fP\^; char *\f(CItype\fP\^; XrmValue *\f(CIvalue\fP\^; .Ae .SH "Arguments" .IP \f(CIdatabase\fP 1i Specifies a pointer to the resource database. If database contains \f(CWNULL\fP, a new resource database is created and a pointer to it is returned in \f(CIdatabase\fP. If a database is created, it is created in the current locale. .IP \f(CIspecifier\fP 1i Specifies a complete or partial specification of the resource. .IP \f(CItype\fP 1i Specifies the type of the resource. .IP \f(CIvalue\fP 1i Specifies the value of the resource. .SH Description \f(CWXrmPutResource()\fP is one of several functions which store data into a database. .LP \f(CWXrmPutResource()\fP first converts \f(CIspecifier\fP into a binding list and a quark list by calling \f(CWXrmStringToBindingQuarkList()\fP, and converts \f(CItype\fP into an \f(CWXrmRepresentation\fP by calling \f(CWXrmStringToRepresentation\fP. Finally, it puts the data into the database. If the specifier and type are not in the Host Portable Character encoding, the result is implementation-dependent. The value is stored in the database without modification. .LP \f(CWXrmPutResource()\fP, \f(CWXrmQPutResource()\fP, \f(CWXrmPutStringResource()\fP, \f(CWXrmQPutStringResource()\fP and \f(CWXrmPutLineResource()\fP all store data into a database. See the description of \f(CWXrmQPutResource()\fP for the most complete description of this process. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" \f(CWXrmDatabase\fP is a pointer to an opaque data type. .Ps typedef struct { unsigned int size; XPointer addr; } XrmValue, *XrmValuePtr; .Pe .ne 9 .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmPutStringResource" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmPutStringResource" .XX "resource specifications:adding" .Na XrmPutStringResource \(en add a resource specification with separate resource name and value. .Nz .SH "Synopsis" .Sy void XrmPutStringResource\^(\^\f(CIdatabase\fP, \f(CIspecifier\fP, \f(CIvalue\fP\^) .As XrmDatabase *\f(CIdatabase\fP\^; char *\f(CIspecifier\fP\^; char *\f(CIvalue\fP\^; .Ae .SH "Arguments" .IP \f(CIdatabase\fP 1i Specifies a pointer to the resource database. If \f(CIdatabase\fP contains \f(CWNULL\fP, a new resource database is created and a pointer to it is returned in \f(CIdatabase\fP. .IP \f(CIspecifier\fP 1i Specifies the resource, as a string. .IP \f(CIvalue\fP 1i Specifies the value of the resource, as a string. .SH Description \f(CWXrmPutStringResource()\fP adds a resource specification with the specified resource and value to the specified database. The \f(CIspecifier\fP string may contain both names and classes, bound with either loose (*) or tight (.) bindings. See the description of \f(CWXrmGetResource()\fP for more information about bindings. .LP The representation type used in the database is \f(CWString\fP. If the specifier is not in the Host Portable Character Encoding, the result is implementation-dependent. The value is stored in the database without modification. .LP \f(CWXrmPutResource()\fP, \f(CWXrmQPutResource()\fP, \f(CWXrmPutStringResource()\fP, \f(CWXrmQPutStringResource()\fP and \f(CWXrmPutLineResource()\fP all store data into a database. See \f(CWXrmQPutResource()\fP for the most complete description of this process. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" \f(CWXrmDatabase\fP is a pointer to an opaque data type. .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmQGetResource" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmQGetResource" .XX "resources:obtaining using name and class as quarks" .Na XrmQGetResource \(en get a resource value using name and class as quarks. .Nz .SH "Synopsis" .Sy Bool XrmQGetResource\^(\^\f(CIdatabase\fP, \f(CIquark_name\fP, \f(CIquark_class\fP, \f(CIquark_type_ .br return\fP, \f(CIvalue_return\fP\^) .As \f(CWXrmDatabase\fP \f(CIdatabase\fP\^; \f(CWXrmNameList\fP \f(CIquark_name\fP\^; \f(CWXrmClassList\fP \f(CIquark_class\fP\^; \f(CWXrmRepresentation\fP *\f(CIquark_type_return\fP\^; \f(CWXrmValue\fP *\f(CIvalue_return\fP\^; .Ae .SH "Arguments" .IP \f(CIdatabase\fP 1i Specifies the database that is to be used. .IP \f(CIquark_name\fP 1i Specifies the fully qualified name of the value being retrieved (as a list of quarks). .IP \f(CIquark_class\fP 1i Specifies the fully qualified class of the value being retrieved (as a list of quarks). .IP \f(CIquark_type_return\fP 1i Returns a pointer to the representation type of the value. In this function, the representation type is represented as a quark. .IP \f(CIvalue_return\fP 1i Returns a pointer to the value in the database. Do not modify or free this data. .SH Returns \f(CWTrue\fP if the resource was found, else \f(CWFalse\fP. .SH Description \f(CWXrmQGetResource()\fP retrieves a resource from the specified database. It takes fully qualified name and class strings, and returns the representation and value of the matching resource. The value returned points into database memory; you must not modify that data. If a resource was found, \f(CWXrmQGetResource()\fP returns \f(CWTrue\fP. Otherwise, it returns \f(CWFalse\fP. .LP Currently, the database only frees or overwrites entries when new data is stored with \f(CWXrmMergeDatabases()\fP, or \f(CWXrmPutResource()\fP and related routines. A client that avoids these functions should be safe using the address passed back at any time until it exits. .LP .XX "XrmGetResource:versus XrmQGetResource" \f(CWXrmQGetResource()\fP is very similar to \f(CWXrmGetResource()\fP, except that in \f(CWXrmGetResource()\fP, the equivalent arguments to \f(CIquark_name\fP, \f(CIquark_class\fP, and \f(CIquark_type_return\fP arguments are strings instead of quarks. .LP See \f(CWXrmGetResource()\fP for a full description of how data is looked up in the database. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .br .ne 8 .SH "Structures" \f(CWXrmDatabase\fP is a pointer to an opaque data type. .Ps .ta 4.5n 2.75i typedef XrmQuarkList XrmNameList; typedef XrmQuarkList XrmClassList; typedef XrmQuark XrmRepresentation; typedef struct { unsigned int size; XPointer addr; } XrmValue, *XrmValuePtr; .Pe .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .de Su \" if $1 = +, this gives a superscript; $1 = - gives a subscript. . \" If 3 args, $2=regular text; $3=super/subscripted text w/pre-space . \" If 2 args, $1=super/subscripted text with post-space .if "\\$1"+" \{\ . if \\n(.$=3 \\$2\v'-3p'\s-3\h'2p'\\$3\v'3p'\s0 . if \\n(.$=2 \v'-3p'\s-3\\$2\v'3p'\s0\h'2p'\} .if "\\$1"-" \{\ . if \\n(.$=3 \\$2\v'3p'\s-3\h'2p'\\$3\v'-3p'\s0 . if \\n(.$=2 \v'3p'\s-3\\$2\v'-3p'\s0\h'2p'\} .. .RH "XrmQGetSearchList" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmQGetSearchList" .XX "databases:searching .Na XrmQGetSearchList \(en return a list of database levels. .Nz .SH "Synopsis" .Sy Bool XrmQGetSearchList\^(\^\f(CIdatabase\fP, \f(CInames\fP, \f(CIclasses\fP, .ti +10n \f(CIlist_return\fP, \f(CIlist_length\fP\^) .As XrmDatabase \f(CIdatabase\fP\^; XrmNameList \f(CInames\fP\^; XrmClassList \f(CIclasses\fP\^; XrmSearchList \f(CIlist_return\fP\^; int \f(CIlist_length\fP\^; .Ae .SH "Arguments" .IP \f(CIdatabase\fP 1i Specifies the database to be searched. .IP \f(CInames\fP 1i Specifies a list of resource names. .IP \f(CIclasses\fP 1i Specifies a list of resource classes. .IP \f(CIlist_return\fP 1i Returns a search list for further use. The caller must allocate sufficient space for the list before calling \f(CWXrmQGetSearchList()\fP. .IP \f(CIlist_length\fP 1i Specifies the number of entries (not the byte size) allocated for \f(CIlist_return\fP. .SH Returns \f(CWTrue\fP if \f(CIlist_return\fP was large enough for the search list, else \f(CWFalse\fP. .SH Description \f(CWXrmQGetSearchList()\fP is a tool for searching the database more efficiently. It is used in combination with \f(CWXrmQGetSearchResource()\fP. Often, one searches the database for many similar resources which differ only in their final component (e.g., \f(CWxmh.toc.foreground\fR, \f(CWxmh.toc.background\fR, etc). Rather than looking for each resource in its entirety, \f(CWXrmGetSearchList\fP searches the database for the common part of the resource name, returning a whole list of items in the database that match it. This list is called the \fIsearch list\fP. This search list is then used by \f(CWXrmQGetSearchList()\fP, which searches for the last components one at a time. In this way, the common work of searching for similar resources is done only once, and the specific part of the search is done on the much shorter search list. .LP \f(CWXrmQGetSearchList()\fP takes a list of names and classes and returns a list of database levels where a match might occur. The returned list is in best-to-worst order and uses the same algorithm as \f(CWXrmGetResource()\fP for determining precedence. If \f(CIlist_return\fP was large enough for the search list, \f(CWXrmQGetSearchList()\fP returns \f(CWTrue\fP. Otherwise, it returns \f(CWFalse\fP. .LP The size of the search list that must be allocated by the caller is dependent upon the number of levels and wildcards in the resource specifiers that are stored in the database. The worst case length is .Su + 3 \fIn\fR , where \fIn\fR is the number of name or class components in \f(CInames\fP or \f(CIclasses\fP. .LP Only the common prefix of a resource name should be specified in the name and class list to \f(CWXrmQGetSearchList()\fP. In the example above, the common prefix would be \f(CWxmh.toc\fR. However, note that \f(CWXrmQGetSearchResource()\fP requires that \f(CIname\fP represent a single component only. .ne 2 Therefore, the common prefix must be all but the last component of the name and class. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" \f(CWXrmDatabase\fP is a pointer to an opaque data type. .Ps typedef XrmQuarkList XrmNameList; typedef XrmQuarkList XrmClassList; typedef XrmQuark XrmRepresentation; .Pe XrmSearchList\fR is a pointer to an opaque data type. .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmQGetSearchResource" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmQGetSearchResource" .XX "resources:searching prepared list for" .XX "databases:searching" .Na XrmQGetSearchResource \(en search prepared list for a given resource. .Nz .SH "Synopsis" .Sy Bool XrmQGetSearchResource\^(\^\f(CIlist\fP, \f(CIname\fP, \f(CIclass\fP, \f(CItype_return\fP, .ti +10n \f(CIvalue_return\fP\^) .As XrmSearchList \f(CIlist\fP\^; XrmName \f(CIname\fP\^; XrmClass \f(CIclass\fP\^; XrmRepresentation *\f(CItype_return\fP\^; XrmValue *\f(CIvalue_return\fP\^; .Ae .SH "Arguments" .IP \f(CIlist\fP 1i Specifies the search list returned by \f(CWXrmQGetSearchList()\fP. .IP \f(CIname\fP 1i Specifies the resource name. .IP \f(CIclass\fP 1i Specifies the resource class. .IP \f(CItype_return\fP 1i Returns the data representation type. .IP \f(CIvalue_return\fP 1i Returns the value from the database. .SH Returns \f(CWTrue\fP if the resource was found, else \f(CWFalse\fP. .SH Description \f(CWXrmQGetSearchResource()\fP is a tool for searching the database more efficiently. It is used in combination with \f(CWXrmQGetSearchList()\fP. Often, one searches the database for many similar resources which differ only in their final component (e.g., \f(CWxmh.toc.foreground\fR, \f(CWxmh.toc.background\fR, etc). Rather than looking for each resource in its entirety, \f(CWXrmQGetSearchList()\fP searches the database for the common part of the resource name, returning a whole list of items in the database that match it. This list is called the \fIsearch list\fP. \f(CWXrmQGetSearchResource()\fP searches the search list for the resource that is fully identified by \f(CIname\fP and \f(CIclass\fP. The search stops with the first match. \f(CWXrmQGetSearchResource()\fP returns \f(CWTrue\fP if the resource was found; otherwise, it returns \f(CWFalse\fP. .LP A call to \f(CWXrmQGetSearchList()\fP with a name and class list containing all but the last component of a resource name followed by a call to \f(CWXrmQGetSearchResource()\fP with the last component name and class returns the same database entry as \f(CWXrmQGetResource()\fP or \f(CWXrmQGetResource()\fP would with the fully qualified name and class. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .br .ne 9 .SH "Structures" \f(CWXrmDatabase\fP is a pointer to an opaque data type. .Ps typedef XrmQuark XrmName; typedef XrmQuark XrmClass; typedef XrmQuark XrmRepresentation; typedef struct { unsigned int size; XPointer addr; } XrmValue, *XrmValuePtr; .Pe \f(CWXrmSearchList\fR is a pointer to an opaque data type. .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmQPutResource" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmQPutResource" .XX "resource specifications:storing in resource databases using quarks" .Na XrmQPutResource \(en store a resource specification into a database using quarks. .Nz .SH "Synopsis" .ft CW .ta 4.5n 2.4i .nf void XrmQPutResource\^(\^\f(CIdatabase\fP, \f(CIbindings\fP, \f(CIquarks\fP, \f(CItype\fP, \f(CIvalue\fP\^) .As XrmDatabase *\f(CIdatabase\fP\^; XrmBindingList \f(CIbindings\fP\^; XrmQuarkList \f(CIquarks\fP\^; XrmRepresentation \f(CItype\fP\^; XrmValue *\f(CIvalue\fP\^; .fi .SH "Arguments" .IP \f(CIdatabase\fP .88i Specifies a pointer to the resource database. If database contains \f(CWNULL\fP, a new resource database is created and a pointer to it is returned in \f(CIdatabase\fP. If a database is created, it is created in the current locale. .IP \f(CIbindings\fP Specifies a list of bindings for binding together the \f(CIquarks\fP argument. .IP \f(CIquarks\fP Specifies the complete or partial name or class list of the resource to be stored. .IP \f(CItype\fP Specifies the type of the resource. .IP \f(CIvalue\fP Specifies the value of the resource. .SH Description \f(CWXrmQPutResource()\fP stores a resource specification into the database. If a resource entry with the identical bindings and quarks already exists in the database, the previous value is replaced by the new specified value. The value is stored in the database without modification. .LP \f(CIdatabase\fP can be a previously defined database, as returned by \f(CWXrmGetStringDatabase()\fP, \f(CWXrmGetFileDatabase()\fP, or from \f(CWXrmMergeDatabases()\fP. If \f(CIdatabase\fP is \f(CWNULL\fP, a new database is created and a pointer to it returned in \f(CIdatabase\fP. .LP \f(CIbindings\fP and \f(CIquarks\fP together specify where the value should be stored in the database. See \f(CWXrmStringToBindingQuarkList()\fP for a brief description of binding and quark lists. See \f(CWXrmGetResource()\fP for a description of the resource manager naming conventions and lookup rules. .LP .EL \f(CItype\fP is the representation type of \f(CIvalue\fP. This provides a way to distinguish between different representations of the same information. Representation types are user-defined character strings describing the way the data is represented. For example, a color may be specified by a color name ("red"), or be coded in a hexadecimal string ("#4f6c84") (if it is to be used as an argument to \f(CWXParseColor()\fP.) The representation type would distinguish between these two. Representation types are created from simple character strings by using the macro \f(CWXrmStringToRepresentation\fP. The type \f(CWXrmRepresentation\fP is actually the same type as \f(CWXrmQuark\fP, since it is an ID for a string. The representation is stored along with the value in the database, and is returned when the database is accessed. .LP \f(CIvalue\fP specifies the value of the resource, specified as an \f(CWXrmValue\fP. .LP \f(CWXrmGetResource()\fP contains the complete description of how data is accessed from the database, and so provides a good perspective on how it is stored. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" \f(CWXrmDatabase\fP is a pointer to an opaque data type. .Ps .ta 4.5n 1.8i typedef enum { XrmBindTightly, XrmBindLoosely } XrmBinding, *XrmBindingList; typedef int XrmQuark, *XrmQuarkList; typedef XrmQuarkList XrmNameList; typedef XrmQuark XrmRepresentation; typedef struct { unsigned int size; XPointer addr; } XrmValue, *XrmValuePtr; .pe .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmQPutStringResource" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmQPutStringResource" .XX "resource specifications:adding to resource databases using quarks" .Na XrmQPutStringResource \(en add a resource specification to a database using a quark resource name and string value. .Nz .SH "Synopsis" .Sy void XrmQPutStringResource\^(\^\f(CIdatabase\fP, \f(CIbindings\fP, \f(CIquarks\fP, \f(CIvalue\fP\^) .As XrmDatabase *\f(CIdatabase\fP\^; XrmBindingList \f(CIbindings\fP\^; XrmQuarkList \f(CIquarks\fP\^; char *\f(CIvalue\fP\^; .Ae .SH "Arguments" .IP \f(CIdatabase\fP .88i Specifies a pointer to the resource database. If database contains \f(CWNULL\fP, a new resource database is created and a pointer to it is returned in \f(CIdatabase\fP. If a database is created, it is created in the current locale. .IP \f(CIbindings\fP Specifies a list of bindings for binding together the \f(CIquarks\fP argument. .IP \f(CIquarks\fP Specifies the complete or partial name or class list of the resource to be stored. .IP \f(CIvalue\fP Specifies the value of the resource as a string. .SH Description \f(CWXrmQPutStringResource()\fP stores a resource specification into the specified database. .LP \f(CWXrmQPutStringResource()\fP is a cross between \f(CWXrmQPutResource()\fP and \f(CWXrmPutStringResource()\fP. Like \f(CWXrmQPutResource()\fP, it specifies the resource by \f(CIquarks\fP and \f(CIbindings\fP, two lists that together make a name/class list with loose and tight bindings. Like \f(CWXrmPutStringResource()\fP, it specifies the value to be stored as a string, that value is converted into an \f(CWXrmValue\fP, and the default representation type \f(CWString\fP is used. The value is stored in the database without modification. .LP \f(CWXrmPutResource()\fP, \f(CWXrmQPutResource()\fP, \f(CWXrmPutStringResource()\fP, \f(CWXrmQPutStringResource()\fP and \f(CWXrmPutLineResource()\fP all store data into a database. See \f(CWXrmQPutResource()\fP for the most complete description of this process. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" \f(CWXrmDatabase\fP is a pointer to an opaque data type. .Ps .ta 4.5n 2.75i typedef enum { XrmBindTightly, XrmBindLoosely } XrmBinding, *XrmBindingList; .sp .5 typedef int XrmQuark, *XrmQuarkList; .Pe .Nd 10 .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmQuarkToString" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmQuarkToString" .XX "quarks:converting to strings" .XX "strings:converting quarks to" .Na XrmQuarkToString \(en convert a quark to a string. .Nz .SH "Synopsis" .Sy char *XrmQuarkToString\^(\^\f(CIquark\fP\^) .As XrmQuark \f(CIquark\fP\^; .Ae .SH "Arguments" .IP \f(CIquark\fP 1i Specifies the quark for which the equivalent string is desired. .SH Returns The string. .SH Description \f(CWXrmQuarkToString()\fP returns the string for which the specified quark is serving as a shorthand symbol. The quark was earlier set to represent the string by \f(CWXrmStringToQuark()\fP. The string pointed to by the return value must not be modified or freed, because that string is in the data structure used by the resource manager for assigning quarks. If no string exists for that quark, \f(CWXrmQuarkToString()\fP returns \f(CWNULL\fP. .LP Since the resource manager needs to make many comparisons of strings when it gets data from the database, it is more efficient to convert these strings into quarks, and to compare quarks instead. Since quarks are represented by integers, comparing quarks is trivial. .LP The three \f(CW#define\fR statements in the Structures section provide an extra level of abstraction. They define macros so that names, classes and representations can also be represented as quarks. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" .Ps typedef int XrmQuark; /* macro definitions from */ #define XrmNameToString(name) XrmQuarkToString(name) #define XrmClassToString(class) XrmQuarkToString(class) #define XrmRepresentationToString(type) XrmQuarkToString(type) .Pe .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmRepresentationToString" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmRepresentationToString" .XX "quarks:converting to strings" .XX "strings:converting from quarks" .Na XrmRepresentationToString \(en convert a quark to a string. .Nz .SH "Synopsis" .Sy #define XrmRepresentationToString(type) XrmQuarkToString(type) .sp .in 0 char *XrmQuarkToString\^(\^\f(CIquark\fP\^) .As XrmQuark \f(CIquark\fP\^; .Ae .SH "Arguments" .IP \f(CIquark\fP 1i Specifies the quark for which the equivalent string is desired. .SH Returns The string. .SH Description .XX "XrmQuarkToString:and XrmRepresentationToString" \f(CWXrmRepresentationToString\fP is an alias for \f(CWXrmQuarkToString()\fP. It returns the string for which the specified quark is serving as a shorthand symbol. The quark was returned earlier by \f(CWXrmStringToQuark\fP or \f(CWXrmStringToRepresentation()\fP. The string pointed to by the return value must not be modified or freed, because that string is in the data structure used by the resource manager for assigning quarks. If no string exists for that quark, \f(CWXrmRepresentationToString\fP returns \f(CWNULL\fP. .LP Since the resource manager needs to make many comparisons of strings when it gets data from the database, it is more efficient to convert these strings into quarks, and to compare quarks instead. Since quarks are represented by integers, comparing quarks is trivial. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" .Ps typedef int XrmQuark; .Pe .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmSetDatabase" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .XX "XrmSetDatabase" .XX "resource databases:and displays" .SH Name .Na XrmSetDatabase \(en associate a resource database with a display. .Nz .SH Synopsis .Sy void XrmSetDatabase\^(\^\f(CIdisplay\fP\^, \f(CIdatabase\fP\^) .As Display *\f(CIdisplay\fP\^; XrmDatabase \f(CIdatabase\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIdatabase\fP 1i Specifies the resource database. .SH Availability Release 5 and later. .SH Description \f(CWXrmSetDatabase()\fR associates the specified resource database (or \f(CWNULL\fP) with the specified display. The database previously associated with the display (if any) is not destroyed. A client or toolkit may find this function convenient for retaining a database once it is constructed. .SH "See Also" \s-1\fIXrmGetDatabase()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "\s-1XrmStringToBindingQuarkList\s0" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmStringToBindingQuarkList" .XX "resource specifications:converting to binding and quark lists" .Na XrmStringToBindingQuarkList \(en convert a key string to a binding list and a quark list. .Nz .SH "Synopsis" .Sy XrmStringToBindingQuarkList\^(\^\f(CIstring\fP, \f(CIbindings_return\fP, \ \f(CIquarks_return\fP\^) .As char *\f(CIstring\fP\^; XrmBindingList \f(CIbindings_return\fP\^; XrmQuarkList \f(CIquarks_return\fP\^; .Ae .SH "Arguments" .IP \f(CIstring\fP 1i Specifies the string for which the list of quarks and list of bindings_return are to be generated. Must be \f(CWNULL\fP-terminated. .IP \f(CIbindings_return\fP 1i Returns the binding list. The caller must allocate sufficient space for the binding list before the call. .IP \f(CIquarks_return\fP 1i Returns the list of quarks. The caller must allocate sufficient space for the quarks list before the call. .SH Description \f(CWXrmStringToBindingQuarkList()\fP converts a resource specification string into two lists \- one of quarks and one of bindings. Component names in the list are separated by a dot (.) indicating a tight binding or an asterisk (*) indicating a loose binding. If the string does not start with dot or asterisk, a dot (".") is assumed. .LP A tight binding means that the quarks on either side of the binding are consecutive in the key. A loose binding, on the other hand, is a wildcard that can match any number of unspecified components in between the two quarks separated by the binding. Tight and loose bindings are used in the match rules, which compare multicomponent strings to find matches and determine the best match. See \f(CWXrmGetResource()\fP for a full description of lookup rules. .LP For example, \f(CW*a.b*c\fR becomes: .sp .5 .in +8n .sp 1 .in 0 .KS .TS tab(@); l l l lfCW. quarks@bindings .sp .5 a@XrmBindLoosely b@XrmBindTightly c@XrmBindLoosely .TE .KE .in .sp 1 .in -8n .sp For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .Nd 10 .SH "Structures" .Ps .ta 4.5n 2.75i typedef int XrmQuark, *XrmQuarkList; typedef enum ( XrmBindLoosely, XrmBindTightly ) XrmBinding, *XrmBindingList; .Pe .ne 9 .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmStringToQuark" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .Na XrmStringToQuark, XrmStringToName, XrmStringToClass, XrmStringToRepresentation \(en convert a string to a quark. .Nz .SH "Synopsis" .Sy XrmQuark XrmStringToQuark\^(\^\f(CIstring\fP\^) .As char *\f(CIstring\fP\^; .sp #define XrmStringToName(string) XrmStringToQuark(string) #define XrmStringToClass(string) XrmStringToQuark(string) #define XrmStringToRepresentation(string) XrmStringToQuark(string) .Ae .SH "Arguments" .IP \f(CIstring\fP 1i Specifies the string for which a quark is to be allocated. .SH Returns The quark. .SH Description \f(CWXrmStringToQuark()\fP returns a quark that will represent the specified string. If the string is not in the Host Portable Character Encoding, the conversion is implementation-dependent. Since \f(CIstring\fP is copied, it may be freed. \f(CWXrmQuarkToString()\fP performs the inverse function. .LP A quark is an integer representation of a string. Since the resource manager needs to make many comparisons of strings when it gets data from the database, it is more efficient to convert these strings into quarks, and to compare quarks instead. Since quarks are presently represented by integers, comparing quarks is trivial. .LP The macros \f(CWXrmStringToName()\fP, \f(CWXrmStringToClass()\fP, and \f(CWXrmStringToRepresentation()\fP provide alternate names for \f(CWXrmStringToQuark()\fP. They help document when a name, class, or representation (as opposed to some other type of string) is being converted into a quark. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" .Ps typedef int XrmQuark; .Pe .SH "See Also" \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmStringToQuarkList" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmStringToQuarkList" .XX "key strings:converting to quark lists" .Na XrmStringToQuarkList \(en convert a key string to a quark list. .Nz .SH "Synopsis" .Sy void XrmStringToQuarkList\^(\^\f(CIstring\fP, \f(CIquarks_return\fP\^) .As char *\f(CIstring\fP\^; XrmQuarkList \f(CIquarks_return\fP\^; .Ae .SH "Arguments" .IP \f(CIstring\fP 1i Specifies the string for which a list of quarks is to be generated. Must be \f(CWNULL\fP-terminated. The components may be separated by the dot (.) character (tight binding) or the asterisk (*) character (loose binding). .IP \f(CIquarks_return\fP 1i Returns the list of quarks. .SH Description \f(CWXrmStringToQuarkList()\fP converts \f(CIstring\fP (generally a fully qualified name/class string) to a list of quarks. If the string is not in the Host Portable Character Encoding, the conversion is implementation-dependent. Components of the string may be separated by a tight binding (the "." character) or a loose binding ("*"). .XX "XrmStringToBindingQuarkList" Use \f(CWXrmStringToBindingQuarkList()\fP for lists which contain both tight and loose bindings. See \f(CWXrmGetResource()\fP for a description of tight and loose binding. .LP Each component of the string is individually converted into a quark. See \f(CWXrmStringToQuark()\fP for information about quarks and converting strings to quarks. \f(CIquarks_return\fP is a \f(CWNULL\fP-terminated list of quarks. .LP For example, \f(CWxmh.toc.command.background\fR is converted into a list of four quarks: the quarks for \f(CWxmh\fR, \f(CWtoc\fR, \f(CWcommand\fR, and \f(CWbackground\fR, in that order. A \f(CWNULLQUARK\fP is appended to the end of the list. .LP Note that \f(CWXrmStringToNameList\fP and \f(CWXrmStringToClassList\fP are macros that perform exactly the same function as \f(CWXrmStringToQuarkList()\fP. These may be used in cases where they clarify the code. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" .Ps .ta 4.5n 2.75i typedef int XrmQuark *XrmQuarkList; #define XrmStringToNameList(str, name) XrmStringToQuarkList((str), (name)) #define XrmStringToClassList(str,class) XrmStringToQuarkList((str), (class)) .Pe .ne 9 .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1, .hw XrmStringToRepresen-tation \s-1\fIXrmStringToRepresentation\fP\s+1, \s-1\fIXrmUniqueQuark()\fP\s+1. .\"last line comment .TH XrmStringTo.3X "" "" "" "" .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XrmStringToBindingQuarkList@XrmStringTA .sp .5 XrmStringToQuark@XrmStringTB .sp .5 XrmStringToQuarkList@XrmStringTC .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XrmUniqueQuark" "Xlib \- Resource Manager" .ds ]W Xlib Reference Manual .SH "Name" .XX "XrmUniqueQuark" .XX "quarks:allocating new" .Na XrmUniqueQuark \(en allocate a new quark. .Nz .SH "Synopsis" .Sy XrmQuark XrmUniqueQuark\^(\ ) .SH Returns The quark. .SH Description \f(CWXrmUniqueQuark()\fP allocates a quark that is guaranteed not to represent any existing string. For most applications, \f(CWXrmStringToQuark()\fP is more useful, as it binds a quark to a string. However, on some occasions, you may want to allocate a quark that has no string equivalent. .LP .XX "quarks:about" The shorthand name for a string is called a \fIquark\fP and is the type \f(CWXrmQuark\fP. Quarks are used to improve performance of the resource manager, which must make many string comparisons. Quarks are presently represented as integers. Simple comparisons of quarks can be performed rather than lengthy string comparisons. .LP A quark is to a string what an atom is to a property name in the server, but its use is entirely local to your application. .LP For more information, see Volume One, Chapter 13, \fIManaging User Preferences\fR. .SH "Structures" .Ps \s9typedef int XrmQuark;\s0 .Pe .SH "See Also" \s-1\fIXrmDestroyDatabase()\fP\s+1, \s-1\fIXrmGetFileDatabase()\fP\s+1, \s-1\fIXrmGetResource()\fP\s+1, \s-1\fIXrmGetStringDatabase()\fP\s+1, \s-1\fIXrmInitialize()\fP\s+1, \s-1\fIXrmMergeDatabases()\fP\s+1, \s-1\fIXrmParseCommand()\fP\s+1, \s-1\fIXrmPutFileDatabase()\fP\s+1, \s-1\fIXrmPutLineResource()\fP\s+1, \s-1\fIXrmPutResource()\fP\s+1, \s-1\fIXrmPutStringResource()\fP\s+1, \s-1\fIXrmQGetResource()\fP\s+1, \s-1\fIXrmQGetSearchList()\fP\s+1, \s-1\fIXrmQGetSearchResource()\fP\s+1, \s-1\fIXrmQPutResource()\fP\s+1, \s-1\fIXrmQPutStringResource()\fP\s+1, \s-1\fIXrmQuarkToString()\fP\s+1, \s-1\fIXrmStringToBindingQuarkList()\fP\s+1, \s-1\fIXrmStringToQuarkList()\fP\s+1, \s-1\fIXrmStringToQuark()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAcceptFocusProc" "Xt \- Widget Method Prototypes" .SH "Name" .Na XtAcceptFocusProc \- interface definition for the \f(CWaccept_focus()\fP method. .Nz .XX "XtAcceptFocusProc" .SH "Synopsis" .Sy typedef Boolean (*XtAcceptFocusProc)(Widget, Time*); .As Widget \f(CIwidget\fP; Time *\f(CItime\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget to take the focus. .IP \f(CItime\fP 1i Specifies the time of the event that causes the parent to offer focus to the child. .SS "Returns" \f(CWTrue\fP if the widget took the focus, \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtAcceptFocusProc\fP is the type of the Core \f(CWaccept_focus()\fP method. See \f(CWaccept_focus\fP(4) for more information. .\" .SH "See Also" .na \s-1\fIaccept_focus\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtActionHookProc" "Xt \- Translations and Actions" .SH "Name" .Na XtActionHookProc \- interface definition for action hook procedure. .Nz .XS "XtActionHookProc" .SH "Synopsis" .Sy typedef void (*XtActionHookProc)(Widget, XtPointer, String, XEvent*, \ String*, Cardinal*); .As Widget \f(CIw\fP; XtPointer \f(CIclient_data\fP; String \f(CIaction_name\fP; XEvent* \f(CIevent\fP; String* \f(CIparams\fP; Cardinal* \f(CInum_params\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget whose action is about to be dispatched. .IP \f(CIclient_data\fP 1i Specifies data that was registered with this procedure in a call to \f(CWXtAppAddActionHook()\fR. .IP \f(CIaction_name\fP 1i Specifies the name of the action to be dispatched. .IP \f(CIevent\fP 1i Specifies the event argument that will be passed to the action routine. .IP \f(CIparams\fP 1i Specifies the action parameters that will be passed to the action routine. .IP \f(CInum_params\fP 1i Specifies the number of elements in \f(CIparams\fP. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" An \f(CWXtActionHookProc\fP registered with \f(CWXtAppAddActionHook()\fP will be called just before any action procedure is invoked by the Translation Manager. \f(CIclient_data\fP is whatever data was registered with the action hook procedure in the call to \f(CWXtAppAddActionHook()\fP. \f(CIaction_name\fP is the name of the action procedure that is about to be invoked. It is the name the action procedure was registered with, and can be used in a call to \f(CWXtCallActionProc()\fP. The \f(CIw\fP, \f(CIevent\fP, \f(CIparams\fP, and \f(CInum_params\fP arguments are the arguments that will be passed directly to the action procedure. .LP Action hooks should not modify any of the data pointed to by the arguments other than the \f(CIclient_data\fR argument. .\" .SH "Usage" One use of an \f(CWXtActionHookProc\fP is to record the arguments passed to each action so that user actions are recorded for later playback using \f(CWXtCallActionProc()\fP. This is one way to implement keyboard macros. .SH "See Also" .LP .na \s-1\fIXtAppAddActionHook\fR\s+1\*(s1, \s-1\fIXtCallActionProc\fR\s+1\*(s1, \s-1\fIXtRemoveActionHook\fR\s+1\*(s1, .br \s-1\fIXtActionProc\fR\s+1\*(s2. .ad .XE "XtActionHookProc" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtActionProc" "Xt \- Translations and Actions" .SH "Name" .Na XtActionProc \- interface definition for action procedure. .Nz .XS "actions table: XtActionProc" .XS "XtActionProc" .SH "Synopsis" .Sy .hw Cardinal typedef void (*XtActionProc)(Widget, XEvent *, String *, Cardinal *); .As Widget \f(CIw\fP; XEvent *\f(CIevent\fP; String *\f(CIparams\fP; Cardinal *\f(CInum_params\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget in which the event occurred that caused the action to be called. .IP \f(CIevent\fP 1i Specifies the event that caused the action to be called. If the action is called after a sequence of events, then the last event in the sequence is used. .IP \f(CIparams\fP 1i Specifies an array of strings that were specified in the translation table as comma-separated arguments to the action. .IP \f(CInum_params\fP 1i Specifies the number of strings in \f(CIparams\fP. .\" .SH "Description" An \f(CWXtActionProc\fP is an action procedure. Action procedures are given names in an \f(CWXtActionList\fP and that array of name/procedure pairs is then registered with the Translation Manager either through a call to \f(CWXtAppAddActions()\fP or by statically initializing the \f(CWactions\fP field of the Core widget record. The translation table of a widget binds event sequences into a sequence of action procedures, and the Translation Manager automatically invokes the action procedures when the specified event sequences occur. .LP The \f(CIparams\fP argument is an array of strings that the action may use. These strings are the comma-separated arguments specified in the translation table. An action procedure may use or ignore them, and may invoke a resource converter to convert strings to convert each of the strings to some other desired type. .LP Action procedures should not assume that the widget in which they are invoked is realized; an accelerator can cause an action procedure to be called for a widget that does not yet have a window. .\" .SH "Usage" As an application programmer, you can often customize the behavior of a widget either by adding callback functions to one of the lists defined by the widget, or by writing and registering custom action procedures and invoking them from the widget's translation table. Callbacks are the simpler approach and are usually sufficient. Action procedures are usually used when you need to directly bind particular user events to particular actions\(enfor example, when the widget does not provide a callback that is invoked in response to the event type that you are interested in. If you wanted to pop up a menu when the mouse entered a widget, or draw a box when the user clicked and dragged the mouse, for example, you would probably use action procedures. Note that action procedures are not registered with a \f(CIclient_data\fP argument as callbacks are, and so application-level action procedures may have to depend on global data. Widget-level action procedures can usually get all the data they need from their widget argument. .LP Note that it is usually a widget's action procedures that invoke the functions registered on that widget's callback lists. .LP Many action routines are intentionally written not to depend on the detailed information inside any particular type of event, so that the user may use the translation table to invoke the action in response to different types of events. For example, it is useful for an action routine normally triggered by a pointer click to work when called in response to a key instead. Such an action should not depend on the event structure fields unique to button events. If your action does depend on the details of a particular event type, you must cast the \f(CIevent\fP argument to a pointer to an event structure of the appropriate type. .LP When you write a widget or an application, you should document each of the action procedures that users may invoke from a translation table, and document any arguments each action expects, and also the event types that the action can be safely called on. Also, if an action procedure invokes the procedures on a callback list without checking that the widget is realized, the callback documentation must note that the widget may not yet be realized. .LP In many action procedures, the last two arguments are unused. When you don't use the last two arguments, be sure to place the \fIlint\fP comment \f(CW/*ARGSUSED*/\fP just before the action procedure definition. To conform to ANSI-C standards, all four arguments of an action should be declared, even if the trailing arguments are not used. .LP The Intrinsics reserve all action names and parameters starting with the characters "Xt" for future standard enhancements. Users, applications, and widgets should not declare action names or pass parameters starting with these characters except to invoke specified built-in Intrinsics functions. .\" .SH "Example" The following two action procedures are from the Xaw Command widget: .Ps static void Highlight(w,event,params,num_params) Widget w; XEvent *event; String *params; Cardinal *num_params; { CommandWidget cbw = (CommandWidget)w; if ( *num_params == (Cardinal) 0) cbw->command.highlighted = HighlightWhenUnset; else { if ( *num_params != (Cardinal) 1) XtWarning("Too many parameters passed to highlight action table."); switch (params[0][0]) { case 'A': case 'a': cbw->command.highlighted = HighlightAlways; break; default: cbw->command.highlighted = HighlightWhenUnset; break; } } if (XtIsRealized(w)) PaintCommandWidget(w, HighlightRegion(cbw), TRUE); } /* ARGSUSED */ static void Notify(w,event,params,num_params) Widget w; XEvent *event; String *params; /* unused */ Cardinal *num_params; /* unused */ { CommandWidget cbw = (CommandWidget)w; /* check to be sure state is still Set so that user can cancel the action (e.g., by moving outside the window, in the default bindings. */ if (cbw->command.set) XtCallCallbackList(w, cbw->command.callbacks, NULL); } .Pe .\" .SH "Structures" The \f(CWXtActionsRec\fP structure and the \f(CWXtActionList\fP type are defined as follows: .Ps typedef struct _XtActionsRec{ String string; XtActionProc proc; } XtActionsRec; typedef struct _XtActionsRec *XtActionList; .Pe .\" .SH "See Also" .na \s-1\fIXtAppAddActions\fR\s+1\*(s1. .ad .XE "XtActionProc" .XS "actions table: XtActionProc" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAddActions" "Xt \- Translations and Actions" .SH "Name" .Na XtAddActions \- register an action table with the Translation Manager. .XS "XtAddActions" .Nz .SH "Synopsis" .Sy void XtAddActions(\f(CIactions\fP, \f(CInum_actions\fP) .As XtActionList \f(CIactions\fP; Cardinal \f(CInum_actions\fP; .Ae .SS "Inputs" .IP \f(CIactions\fP 1i Specifies the action table to register. .IP \f(CInum_actions\fP 1i Specifies the number of entries in this action table. .\" .\" .SH "Availability" Superseded by \f(CWXtAppAddActions()\fP. .\" .SH "Description" \f(CWXtAddActions()\fP registers \f(CIactions\fP, an array of \f(CInum_actions\fP\ \f(CWXtActionsRec\fP structures with the Translation Manager. Each element of the array contains an action name and an action procedure pointer. When a named action is invoked through a translation table, the procedure to be called is looked up in the action tables that have been registered. .\" .SH "Usage" \f(CWXtAddActions()\fP has been superseded by \f(CWXtAppAddActions()\fP, which performs the same function on a per-application context basis. \f(CWXtAddActions()\fP now calls \f(CWXtAppAddActions()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtAddActions()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppAddActions()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppAddActions()\fP for more information about how to use actions. .SH "See Also" .na \s-1\fIXtAppAddActions\fR\s+1\*(s1, .br \s-1\fIXtActionProc\fR\s+1\*(s2. .ad .XE "XtAddActions" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAddCallback" "Xt \- Callbacks" .SH "Name" .Na XtAddCallback \- add a callback procedure to a named callback list. .XS "callbacks: adding; to callback resource" .XS "registering, callbacks" .XS "callbacks, XtAddCallback" .XS "XtAddCallback" .Nz .SH "Synopsis" .Sy void XtAddCallback(\f(CIobject\fP, \f(CIcallback_name\fP, \f(CIcallback\fP, \f(CIclient_data\fP) .As Widget \f(CIobject\fP; String \f(CIcallback_name\fP; XtCallbackProc \f(CIcallback\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object which owns the callback list; may be of class Object or any subclass thereof. .IP \f(CIcallback_name\fP 1i Specifies the resource name of the callback list to which the procedure is to be added. .IP \f(CIcallback\fP 1i Specifies the procedure to be added. .IP \f(CIclient_data\fP 1i Specifies data to be passed to \f(CIcallback\fP when it is invoked, or \f(CWNULL\fP. .\" .SH "Description" \f(CWXtAddCallback()\fP adds the procedure \f(CIcallback\fP and the data \f(CIclient_data\fP to the callback list named by \f(CIcallback_name\fP in the widget or object \f(CIobject\fP. If the procedure already appears on the list, with the same or with different data, it will be added to the list again, and when the callback list is invoked, the procedure will be called as many times as it has been added. .LP The \f(CIcallback\fP procedure must be of type \f(CWXtCallbackProc\fP. This procedure type expects three arguments and does not return anything. The arguments are the widget or object that caused the callback to be invoked, the untyped data (\f(CIclient_data\fP) that was registered with the procedure, and another untyped argument, \f(CIcall_data\fP which generally points to a structure which contains data particular to the callback list and object class. See \f(CWXtCallbackProc(2)\fP. .\" .SH "Usage" The order that callback procedures are invoked in is, unfortunately, not specified by the Xt Intrinsics. If you have several operations that must be executed in a particular order, you should not register them as separate callbacks. Instead you should register a single callback that invokes each of the operations sequentially. .LP If you want to register several callback procedures at the same time, you can use \f(CWXtAddCallbacks()\fP. Callbacks can also be set on a callback list by specifying a \f(CWXtCallbackList\fP as a resource when the widget is created. A callback list should not be set with \f(CWXtSetValues()\fP once a widget is created, however, because this replaces the entire list of procedures rather than simply adding new procedures to the list. The Intrinsics do not define a String-to-XtCallbackList converter, but if you write one and use it in your application, then you can also specify callbacks from a resource file. Finally, note that callback lists in a widget are compiled into an internal form by the Intrinsics, so attempting to examine a callback list with \f(CWXtGetValues()\fP will not work. .\" .SH "Background" Generally speaking, a widget expecting to interact with an application will declare one or more callback lists as resources; the application adds functions to these callback lists, which will be invoked whenever the predefined callback conditions are met. Callback lists have resource names, so that the application can add and remove functions to a callback list by name. .LP Callbacks are not necessarily invoked in response to any event; a widget can call the specified routines at any arbitrary point in its code, whenever it wants to provide a "hook" for application interaction. For example, all widgets provide an \f(CWXtNdestroyCallback\fP resource to allow applications to interpose a routine to be executed when the widget is destroyed. .LP Widgets can define additional callback lists as they see fit. For example, the Athena Command widget defines the \f(CWXtNcallback\fP callback list to notify clients when the widget has been activated (by the user clicking on it with the pointer). (This is actually a poor choice of names. It should have been given a more specific name, such as \f(CWXtNnotifyCallback\fP.) .LP Callbacks differ from actions in the way that the registered function is invoked. For callbacks, the trigger is an abstract occurrence defined by the widget, which may or may not be event-related. The routines on a widget's callback lists are invoked by the widget code, using a call to \f(CWXtCallCallbacks()\fP. Actions, on the other hand, are invoked directly by Xt, as the result of an event combination specified by the translations mechanism. .SH "See Also" .na \s-1\fIXtAddCallbacks\fR\s+1\*(s1, \s-1\fIXtCallCallbacks\fR\s+1\*(s1, \s-1\fIXtRemoveAllCallbacks\fR\s+1\*(s1, \s-1\fIXtRemoveCallback\fR\s+1\*(s1, \s-1\fIXtRemoveCallbacks\fR\s+1\*(s1, .br \s-1\fIXtCallbackProc\fR\s+1\*(s2. .ad .XE "callbacks: adding; to callback resource" .XE "registering, callbacks" .XE "callbacks, XtAddCallback" .XE "XtAddCallback" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAddCallbacks" "Xt \- Callbacks" .SH "Name" .Na XtAddCallbacks \- add an array of callback procedures to a named callback list. .XS "callbacks: adding; to callback list" .XS "registering: callbacks" .XS "XtAddCallbacks" .Nz .SH "Synopsis" .Sy void XtAddCallbacks(\f(CIobject\fP, \f(CIcallback_name, \fP\f(CIcallbacks\fP) .As Widget \f(CIobject\fP; String \f(CIcallback_name\fP; XtCallbackList \f(CIcallbacks\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object which owns the callback list; may be of class Object or any subclass thereof. .IP \f(CIcallback_name\fP 1i Specifies the resource name of the callback list to which the procedures are to be added. .IP \f(CIcallbacks\fP 1i Specifies a \f(CWNULL\fP-terminated array of callback procedures and corresponding client data. .SH "Description" \f(CWXtAddCallbacks()\fP adds the procedure/data pairs specified in \f(CIcallbacks\fP to the callback list named \f(CIcallback_name\fP in the widget or object \f(CIobject\fP. Each element of \f(CIcallbacks\fP is a structure of type \f(CWXtCallbackRec\fP and contains a pointer to a callback procedure and the data to be registered with and passed to that procedure. Because \f(CWXtAddCallbacks()\fP does not have an argument that specifies the length of this array, the last element of the array must contain \f(CWNULL\fP in both of its fields. .LP A procedure may appear multiple times in the \f(CIcallbacks\fP array, and may be added to a callback list more than once, with different or even with the same data. When the callback list is invoked, each procedure will be called as many times as it appears on the list. .LP Each procedure to be added to the callback list must be of type \f(CWXtCallbackProc\fP. This procedure type expects three arguments and does not return anything. The arguments are the widget or object that caused the callback to be invoked, the untyped data that was registered with the procedure, and another untyped argument, \f(CIcall_data\fP which generally points to a structure which contains data particular to the callback list and object class. See \f(CWXtCallbackProc(2)\fP. .\" .SH "Usage" The order that callback procedures are invoked in is, unfortunately, not specified by the Xt Intrinsics. If you have several operations that must be executed in a particular order, you should not register them as separate callbacks. Instead you should register a single callback that invokes each of the operations sequentially. .LP If you want to register only a single callback procedure, \f(CWXtAddCallback()\fP is easier to use. You may find this function easier even if you are registering several functions, because it does not require you to declare and initialize an array of \f(CWXtCallbackRec\fP. .LP Callbacks can also be set on a callback list by specifying a \f(CWXtCallbackList\fP as a resource when the widget is created. A callback list should not be set with \f(CWXtSetValues()\fP once a widget is created, however, because this replaces the entire list of procedures rather than simply adding new procedures to the list. The Intrinsics do not define a String-to-XtCallbackList converter, but if you write one and use it in your application, then you can also specify callbacks from a resource file. Finally, note that callback lists in a widget are compiled into an internal form by the Intrinsics, so attempting to examine a callback list with \f(CWXtGetValues()\fP will not work. .\" .SH "Background" Generally speaking, a widget expecting to interact with an application will declare one or more callback lists as resources; the application adds functions to these callback lists, which will be invoked whenever the predefined callback conditions are met. Callback lists have resource names, so that the application can add and remove functions to a callback list by name. .LP Callbacks are not necessarily invoked in response to any event; a widget can call the specified routines at any arbitrary point in its code, whenever it wants to provide a "hook" for application interaction. For example, all widgets provide an \f(CWXtNdestroyCallback\fP resource to allow applications to interpose a routine to be executed when the widget is destroyed. .LP Widgets can define additional callback lists as they see fit. For example, the Athena Command widget defines the \f(CWXtNcallback\fP callback list to notify clients when the widget has been activated (by the user clicking on it with the pointer). (This is actually a poor choice of names. It should have been given a more specific name, such as \f(CWXtNnotifyCallback\fP.) .LP Callbacks differ from actions in the way that the registered function is invoked. For callbacks, the trigger is an abstract occurrence defined by the widget, which may or may not be event-related. The routines on a widget's callback lists are invoked by the widget code, using a call to \f(CWXtCallCallbacks()\fP. Actions, on the other hand, are invoked directly by Xt, as the result of an event combination specified by the translations mechanism. .SH "Example" When calling \f(CWXtAddCallbacks()\fP, you will generally use a statically initialized array like the following: .Ps XtCallbackRec button_callback_list[] = { {dispatch_function, (XtPointer) 1}, {dispatch_function, (XtPointer) 2}, {do_something_else, NULL}, {(XtCallbackProc) NULL, (XtPointer) NULL}, }; .Pe .\" .SH "Structures" .Ps typedef struct _XtCallbackRec { XtCallbackProc callback; XtPointer closure; } XtCallbackRec, *XtCallbackList; .Pe .SH "See Also" .na \s-1\fIXtAddCallback\fR\s+1\*(s1, \s-1\fIXtCallCallbacks\fR\s+1\*(s1, \s-1\fIXtRemoveAllCallbacks\fR\s+1\*(s1, \s-1\fIXtRemoveCallback\fR\s+1\*(s1, \s-1\fIXtRemoveCallbacks\fR\s+1\*(s1, .br \s-1\fIXtCallbackProc\fR\s+1\*(s2. .ad .XE "callbacks: adding; to callback list" .XE "registering: callbacks" .XE "XtAddCallbacks" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtAddCallba 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtAddCallback@XtAddCallbA .sp .5 XtAddCallbacks@XtAddCallbB .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAddConverter" "Xt \- Resource Management" .SH "Name" .Na XtAddConverter \- register an "old-style" resource converter. .XX "converters, registering" .XX "XtAddConverter" .XX "registering, converters" .Nz .SH "Synopsis" .Sy void XtAddConverter(\f(CIfrom_type\fP, \f(CIto_type\fP, \f(CIconverter\fP, \f(CIconvert_args\fP, \f(CInum_args\fP) .As String \f(CIfrom_type\fP; String \f(CIto_type\fP; XtConverter \f(CIconverter\fP; XtConvertArgList \f(CIconvert_args\fP; Cardinal \f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIfrom_type\fP 1i Specifies the resource name of the datatype that the converter converts from. .IP \f(CIto_type\fP 1i Specifies the resource name of the datatype that the converter converts to. .IP \f(CIconverter\fP 1i Specifies the converter procedure. See \f(CWXtConverter\fP(2). .IP \f(CIconvert_args\fP 1i Specifies how to obtain any additional arguments needed for the conversion. .IP \f(CInum_args\fP 1i Specifies the number elements in \f(CIconvert_args\fP. .\" .\" .SH "Availability" Superseded by \f(CWXtAppAddConverter()\fP. .\" .SH "Description" \f(CWXtAddConverter()\fP registers \f(CIconverter\fP as a procedure to convert data of resource type \f(CIfrom_type\fP to resource type \f(CIto_type\fP. The \f(CIconvert_args\fP array is registered with the converter, and will be used to obtain arguments to pass to the converter each time it is invoked. .\" .SH "Usage" \f(CWXtAddConverter()\fP has been superseded by \f(CWXtAppAddConverter()\fP, which allows the registration of converter functions on a per-application context basis. \f(CWXtAddConverter()\fP now calls \f(CWXtAppAddConverter()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtAddConverter()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppAddConverter()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppAddConverter()\fP for more information about converters and the \f(CWXtConvertArgList\fP data type. .LP \f(CWXtAddConverter()\fP and \f(CWXtAppAddConverter()\fP register "old-style" converters which are still in common use, but are not as flexible as the (incompatible) "new-style" converters added in Release 4. If you must register an existing old-style converter, use \f(CWXtAppAddConverter()\fP, but if you are writing a converter of your own, consider using a new-style converter. See \f(CWXtAppSetTypeConverter()\fP. .Nd 4 .SH "See Also" .na \s-1\fIXtAppAddConverter\fR\s+1\*(s1, \s-1\fIXtAppSetTypeConverter\fR\s+1\*(s1, \s-1\fIXtSetTypeConverter\fR\s+1\*(s1, .br \s-1\fIXtConverter\fR\s+1\*(s2, \s-1\fIXtTypeConverter\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAddEventHandler" "Xt \- Event Handling" .SH "Name" .Na XtAddEventHandler \- register a procedure to be called when specified events occur on a widget. .XS "event handlers, registering" .XS "event handlers, XtAddEventHandler" .XS "registering, event handlers" .XS "XtAddEventHandler" .Nz .SH "Synopsis" .Sy void XtAddEventHandler(\f(CIw\fP, \f(CIevent_mask\fP, \f(CInonmaskable\fP, \f(CIproc\fP, \f(CIclient_data\fP) .As Widget \f(CIw\fP; EventMask \f(CIevent_mask\fP; Boolean \f(CInonmaskable\fP; XtEventHandler \f(CIproc\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. .IP \f(CIevent_mask\fP 1i Specifies the event type that will trigger the handler. .IP \f(CInonmaskable\fP 1i Specifies whether this procedure should be called on nonmaskable event types. .IP \f(CIproc\fP 1i Specifies the handler procedure. .IP \f(CIclient_data\fP 1i Specifies additional data to be passed to the event handler. .\" .SH "Description" \f(CWXtAddEventHandler()\fR registers the procedure \f(CIproc\fP and the data \f(CIclient_data\fP with the Intrinsics event dispatching mechanism. When an event of one of the types set in \f(CIevent_mask\fP occurs on the window of the widget \f(CIw\fP, \f(CIproc\fP will be invoked and \f(CIclient_data\fP passed as one of its arguments. If the window of the widget is not already receiving events of the specified types, \f(CWXtAddEventHandler()\fP calls \f(CWXSelectInput()\fP to ensure that they will be delivered. Additionally, if the handler is registered with the \f(CInonmaskable\fP argument \f(CWTrue\fP, then it will also be invoked when any of the nonmaskable event types occur. These events are \f(CWGraphicsExpose\fR, \f(CWNoExpose\fR, \f(CWSelectionClear\fR, \f(CWSelectionRequest\fR, \f(CWSelectionNotify\fR, \f(CWClientMessage\fR, and \f(CWMappingNotify\fR. Ordinarily, nonmaskable events are of interest only to the Intrinsics. .LP If the specified procedure/data pair has already been registered for this widget, then the \f(CIevent_mask\fP argument augments the event mask already registered for the handler, and the procedure will only be called once for any particular event. The same procedure may be registered multiple times with different values of \f(CIclient_data\fP, and each instance will be treated as a separate handler. .LP See \f(CWXtEventHandler\fP(2) for an explanation of how to write an event handler procedure. .\" .SH "Usage" Neither applications nor widgets often need to use event handlers. Using action procedures and translation tables provides a more flexible way to respond to input events. .LP .Nd 5 The Intrinsics do not specify the order in which event handlers will be called when an event arrives. As of Release 4, however, the function \f(CWXtInsertEventHandler()\fP will register an event handler that will be called before or after all \fIpreviously\fP registered handlers. .LP An event handler can be removed with \f(CWXtRemoveEventHandler()\fP. .\" .SH "Structures" Each of the event mask symbols listed in the table below set a single bit in an event mask. The \f(CIevent_mask\fP argument is formed by combining these symbols with the bitwise OR operator (\^\fB \fR\^). Note that the nonmaskable event types do not appear in this table and cannot be requested in an event mask. .sp 1 .in 0 .KS .TS linesize(2),tab(@); lp7fCW lp7fCW lp7fCW. .sp 2p NoEventMask@Button1MotionMask@StructureNotifyMask@ KeyPressMask@Button2MotionMask@ResizeRedirectMask@ KeyReleaseMask@Button3MotionMask@SubstructureNotifyMask@ ButtonPressMask@Button4MotionMask@SubstructureRedirectMask@ ButtonReleaseMask@Button5MotionMask@FocusChangeMask@ EnterWindowMask@ButtonMotionMask@PropertyChangeMask@ LeaveWindowMask@KeymapStateMask@ColormapChangeMask@ PointerMotionMask@ExposureMask@OwnerGrabButtonMask@ PointerMotionHintMask@VisibilityChangeMask@ .sp 5p .TE .KE .in .sp 1 See \*(z3, for more information on event types and masks. .SH "See Also" .na \s-1\fIXtAddRawEventHandler\fR\s+1\*(s1, \s-1\fIXtInsertEventHandler\fR\s+1\*(s1, \s-1\fIXtRemoveEventHandler\fR\s+1\*(s1, .br \s-1\fIXtEventHandler\fR\s+1\*(s2. .ad .XE "event handlers, registering" .XE "event handlers, XtAddEventHandler" .XE "registering, event handlers" .XE "XtAddEventHandler" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAddExposureToRegion" "Xt \- Event Handling" .Na XtAddExposureToRegion \- merge \f(CWExpose\fR and \f(CWGraphicsExpose\fR events into a region. .XX "expose: Expose events" .XX "GraphicsExpose event" .XX "regions" .XN "events: (see also expose)" .XX "expose: exposure; XtAddExposureToRegion" .XX "XtAddExposureToRegion" .Nz .SH "Synopsis" .Sy void XtAddExposureToRegion(\f(CIevent\fP, \f(CIregion\fP) .As XEvent *\f(CIevent\fP; Region \f(CIregion\fP; .Ae .SS "Inputs" .IP \f(CIevent\fP 1i Specifies a pointer to a \f(CWExpose\fR or \f(CWGraphicsExpose\fR event. .IP \f(CIregion\fP 1i Specifies a region to be added to. .SS "Outputs" .IP \f(CIregion\fP 1i Returns the specified region merged with the rectangle of the expose event. .SH "Description" \f(CWXtAddExposureToRegion()\fR computes the union of the exposed rectangle specified by \f(CIevent\fP and the region specified by \f(CIregion\fP and stores the results back into \f(CIregion\fP. If the \f(CIevent\fP argument is not an \f(CWExpose\fR or \f(CWGraphicsExpose\fR event, \f(CWXtAddExposureToRegion()\fR returns without an error and without modifying \f(CIregion\fP. .\" .SH "Usage" This is a utility function that allows the caller to merge expose events into a region that can be processed all at once instead of as a series of individual rectangles. It is used by the Intrinsics exposure compression mechanism, and could be of use within event handlers, action procedures, or a widget's \f(CWexpose()\fP method. .\" .SH "Structures" \f(CWRegion\fP is a pointer to an opaque type. .SH "See Also" .na \s-1\fIexpose\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAddGrab" "Xt \- Pop Ups" .SH "Name" .Na XtAddGrab \- constrain or redirect user input to a modal widget. .XS "widgets: modal widget; XtAddGrab" .XS "grabs, XtAddGrab" .XS "XtAddGrab" .Nz .SH "Synopsis" .Sy void XtAddGrab(\f(CIw\fP, \f(CIexclusive\fP, \f(CIspring_loaded\fP) .As Widget \f(CIw\fP; Boolean \f(CIexclusive\fP; Boolean \f(CIspring_loaded\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that is to be made modal. Must be of class Core or any subclass thereof. .IP \f(CIexclusive\fP 1i Specifies whether user events should be dispatched exclusively to this widget or also to modal parent widgets. .IP \f(CIspring_loaded\fP 1i Specifies whether this widget was popped up because the user pressed a pointer button. .SH "Description" \f(CWXtAddGrab()\fR makes a widget \fImodal\fP. When a modal widget exists, \f(CWXtDispatchEvent()\fP will not deliver events that occur outside of the modal widget (unless, perhaps, they occur in the modal widget's modal parent) or will redirect events that occur outside of the modal widget to the modal widget. .LP A modal popup dialog box may itself have popup children, and a popup menu may have submenus that popup. A modal widget and all of its descendants are referred to as the \fImodal cascade\fP. If the \f(CIexclusive\fP argument to \f(CWXtAddGrab()\fP is \f(CWTrue\fP, then events should be delivered only to the specified widget, not to any previous widgets in the modal cascade. If it is \f(CWFalse\fP, then events will be delivered to the specified widget and any ancestors in the modal cascade until one is found that has \f(CIexclusive\fP\ \f(CWTrue\fP. .LP Some popups (menus, for example) popup when the user presses a mouse button, and must pop down when the user releases that button, even if it is released outside of the popup. This sort of popup should call \f(CWXtAddGrab()\fP with the \f(CIspring_loaded\fP argument set to \f(CWTrue\fP. \f(CWXtDispatchEvent()\fP will dispatch key and button events to a spring-loaded popup regardless of where those events occur in the application. Note that if \f(CIspring_loaded\fP is \f(CWTrue\fP, then \f(CIexclusive\fP must also be \f(CWTrue\fP. .\" .SH "Usage" You do not often need to call \f(CWXtAddGrab()\fP explicitly. \f(CWXtPopup()\fP will pop up a dialog box and call \f(CWXtAddGrab()\fP appropriately, and the predefined callback procedures \f(CWXtCallbackExclusive()\fP, \f(CWXtCallbackNone()\fP, and \f(CWXtCallbackNonexclusive()\fP will do the same and are suitable for registering on widget callback lists. The predefined action named \f(CWXtMenuPopup\fP will pop up a spring-loaded widget and can be called directly from a translation table. .LP If you call \f(CWXtAddGrab()\fP then you should call \f(CWXtRemoveGrab()\fP when you are done with your modal widget. .LP Note that \f(CWXtAddGrab()\fP does not issue an X button or key grab as \f(CWXtGrabButton()\fP and \f(CWXtGrabKey()\fP do (although there is a button grab implicitly made while any mouse button is held down over a popup menu, for example). Its name refers to the fact that it uses event remapping to simulate the effect of a grab without locking out input to other applications running on the same display. .\" .SH "Background" Modal widgets are widgets that, except for the input directed to them, lock out user input to the application. .LP When a modal menu or modal dialog box is popped up using \f(CWXtPopup()\fP, user events (keyboard and pointer events) that occur outside the modal widget should be delivered to the modal widget or ignored. In no case will user events be delivered to a widget outside the modal widget. .LP Menus can pop up submenus, and dialog boxes can pop up further dialog boxes, to create a popup cascade. In this case, user events may be delivered to one of several modal widgets in the cascade. .LP Display-related events should be delivered outside the modal cascade so that exposure events and the like keep the application's display up-to-date. Any event that occurs within the cascade is delivered as usual. The user events delivered to the most recent spring-loaded shell in the cascade when they occur outside the cascade are called remap events and are \f(CWKeyPress\fP, \f(CWKeyRelease\fP, \f(CWButtonPress\fP, and \f(CWButtonRelease\fP. The user events ignored when they occur outside the cascade are \f(CWMotionNotify\fP and \f(CWEnterNotify\fP. All other events are delivered normally. In particular, note that this is one way in which widgets can receive \f(CWLeaveNotify\fP events without first receiving \f(CWEnterNotify\fP events; they should be prepared to deal with this, typically by ignoring any unmatched \f(CWLeaveNotify\fP events. .LP \f(CWXtAddGrab()\fP appends the widget to the modal cascade and checks that \f(CIexclusive\fP is \f(CWTrue\fP if \f(CIspring_loaded\fP is \f(CWTrue\fP. If this condition is not met, \f(CWXtAddGrab()\fP generates a warning message. .LP The modal cascade is used by \f(CWXtDispatchEvent()\fP when it tries to dispatch a user event. When at least one modal widget is in the widget cascade, \f(CWXtDispatchEvent()\fP first determines if the event should be delivered. It starts at the most recent cascade entry and follows the cascade up to and including the most recent cascade entry added with the \f(CIexclusive\fP parameter \f(CWTrue\fP. .LP This subset of the modal cascade along with all descendants of these widgets comprise the active subset. User events that occur outside the widgets in this subset are ignored or remapped. Modal menus with submenus generally add a submenu widget to the cascade with \f(CIexclusive\fP \f(CWFalse\fP. Modal dialog boxes that need to restrict user input to the most deeply nested dialog box add a subdialog widget to the cascade with \f(CIexclusive\fP \f(CWTrue\fP. User events that occur within the active subset are delivered to the appropriate widget, which is usually a child or further descendant of the modal widget. .LP Regardless of where in the application they occur, remap events are always delivered to the most recent widget in the active subset of the cascade registered with \f(CIspring_loaded\fP \f(CWTrue\fP, if any such widget exists. If the event occurred in the active subset of the cascade but outside the spring-loaded widget, it is delivered normally before being delivered also to the spring-loaded widget. Regardless of where it is dispatched, the Intrinsics do not modify the contents of the event. .SH "See Also" .na \s-1\fIXtCallbackExclusive\fR\s+1\*(s1, \s-1\fIXtCallbackNone\fR\s+1\*(s1, \s-1\fIXtCallbackNonexclusive\fR\s+1\*(s1, \s-1\fIXtCallbackPopdown\fR\s+1\*(s1, \s-1\fIXtCreatePopupShell\fR\s+1\*(s1, \s-1\fIXtDispatchEvent\fR\s+1\*(s1, \s-1\fIXtMenuPopup\fR\s+1\*(s1, \s-1\fIXtPopdown\fR\s+1\*(s1, \s-1\fIXtPopup\fR\s+1\*(s1, \s-1\fIXtRemoveGrab\fR\s+1\*(s1. .ad .XE "widgets: modal widget; XtAddGrab" .XE "grabs, XtAddGrab" .XE "XtAddGrab" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAddInput" "Xt \- Event Handling" .SH "Name" .Na XtAddInput \- register a procedure to be called when there is activity on a file descriptor. .XS "XtAddInput" .Nz .SH "Synopsis" .Sy XtInputId XtAddInput(\f(CIsource\fP, \f(CIcondition\fP, \f(CIproc\fP, \f(CIclient_data\fP) .As int \f(CIsource\fP; XtPointer \f(CIcondition\fP; XtInputCallbackProc \f(CIproc\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIsource\fP 1i Specifies the file descriptor (on a \s-1POSIX\s+1-based system) to monitor. .IP \f(CIcondition\fP 1i Specifies a mask that indicates a read, write, or exception condition or some operating-system-dependent condition. .IP \f(CIproc\fP 1i Specifies the procedure that is to be called when \f(CIcondition\fP occurs on \f(CIsource\fP. .IP \f(CIclient_data\fP 1i Specifies data to be passed to \f(CIproc\fP when it is invoked. .SS "Returns" A handle of type \f(CWXtInputId\fP that can be passed to \f(CWXtRemoveInput()\fP to unregister this input procedure. .\" .\" .SH "Availability" Superseded by \f(CWXtAppAddInput()\fP. .\" .SH "Description" \f(CWXtAddInput()\fP registers a file descriptor \f(CIsource\fP to be monitored by \f(CWXtAppNextEvent()\fP and a procedure \f(CIproc\fP to be called with data \f(CIclient_data\fP when the condition (such as "input ready" or "error") \f(CIcondition\fP arises. .LP On a \s-1POSIX\s+1-based system, the supported values for \f(CIcondition\fP are \f(CWXtInputReadMask\fR, \f(CWXtInputWriteMask\fR, or \f(CWXtInputExceptMask\fR. These values cannot be ORed together. .\" .SH "Usage" \f(CWXtAddInput()\fP has been superseded by \f(CWXtAppAddInput()\fP, which performs the same function on a per-application context basis. \f(CWXtAddInput()\fP now calls \f(CWXtAppAddInput()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtAddInput()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppAddInput()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppAddInput()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtAppAddInput\fR\s+1\*(s1, \s-1\fIXtRemoveInput\fR\s+1\*(s1, .br \s-1\fIXtInputCallbackProc\fR\s+1\*(s2. .ad .XE "XtAddInput" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAddRawEventHandler" "Xt \- Event Handling" .SH "Name" .Na XtAddRawEventHandler \- register an event handler without selecting for the event. .XS "registering: raw event handler" .XS "raw event handlers" .XS "event handlers: raw; registering" .XS "event handlers, XtAddRawEventHandler" .XS "XtAddRawEventHandler" .Nz .SH "Synopsis" .Sy .hw "client-_data" void XtAddRawEventHandler(\f(CIw\fP, \f(CIevent_mask\fP, \f(CInonmaskable\fP, \f(CIproc\fP, \f(CIclient_data\fP) .As Widget \f(CIw\fP; EventMask \f(CIevent_mask\fP; Boolean \f(CInonmaskable\fP; XtEventHandler \f(CIproc\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. .IP \f(CIevent_mask\fP 1i Specifies the event type that will trigger the handler. .IP \f(CInonmaskable\fP 1i Specifies whether this procedure should be called on nonmaskable event types. .IP \f(CIproc\fP 1i Specifies the handler procedure. .IP \f(CIclient_data\fP 1i Specifies additional data to be passed to the event handler. .\" .SH "Description" \f(CWXtAddRawEventHandler()\fP registers the procedure \f(CIproc\fP and the data \f(CIclient_data\fP with the Intrinsics event dispatching mechanism. When an event of one of the types set in \f(CIevent_mask\fP occurs on the window of the widget \f(CIw\fP, \f(CIproc\fP will be invoked and \f(CIclient_data\fP passed as one of its arguments. Additionally, if the handler is registered with the \f(CInonmaskable\fP argument \f(CWTrue\fP, then it will also be invoked when any of the nonmaskable event types occur. These events are \f(CWGraphicsExpose\fR, \f(CWNoExpose\fR, \f(CWSelectionClear\fR, \f(CWSelectionRequest\fR, \f(CWSelectionNotify\fR, \f(CWClientMessage\fR, and \f(CWMappingNotify\fR. Ordinarily, nonmaskable events are of interest only to the Intrinsics. .LP \f(CWXtAddRawEventHandler()\fR is similar to \f(CWXtAddEventHandler()\fR except that it never causes an \f(CWXSelectInput()\fR call to be made for its events. The event mask in \f(CWXtAddRawEventHandler()\fP indicates which events the handler will be called in response to, but only when these events are selected elsewhere. .LP If the specified procedure/data pair has already been registered for this widget, then the \f(CIevent_mask\fP argument augments the event mask already registered for the handler, and the procedure will only be called once for any particular event. The same procedure may be registered multiple times with different values of \f(CIclient_data\fP, and each instance will be treated as a separate handler. .LP See \f(CWXtEventHandler\fP(2) for an explanation of how to write an event handler procedure. .\" .SH "Usage" You rarely need to register a raw event handler. XtAddEventHandler is sufficient in most cases. In particular, you do not need to use raw event handlers to avoid redundant calls to \f(CWXSelectInput()\fP. The .ne 4 Intrinsics keep track of the event mask of each widget and calls \f(CWXSelectInput()\fP only when necessary. .LP The Intrinsics do not specify the order in which event handlers will be called when an event arrives. As of Release 4, however, the function \f(CWXtInsertRawEventHandler()\fP will register a raw event handler that will be called before or after all \fIpreviously\fP registered handlers. .LP Raw event handlers are removed with a call to \f(CWXtRemoveRawEventHandler()\fP. .\" .SH "Structures" Each of the event types listed in the table below set a single bit in an event mask. The \f(CIevent_mask\fP argument is formed by combining these symbols with the bitwise OR operator (\^\fB \fR\^). .XX "OR operator" .XX "bitwise OR, combining mask symbols" Note that the nonmaskable event types do not appear in this table and cannot be requested in an event mask. .sp 1 .in 0 .KS .TS linesize(2),tab(@); lp7fCW lp7fCW lp7fCW. .sp 2p NoEventMask@Button1MotionMask@StructureNotifyMask@ KeyPressMask@Button2MotionMask@ResizeRedirectMask@ KeyReleaseMask@Button3MotionMask@SubstructureNotifyMask@ ButtonPressMask@Button4MotionMask@SubstructureRedirectMask@ ButtonReleaseMask@Button5MotionMask@FocusChangeMask@ EnterWindowMask@ButtonMotionMask@PropertyChangeMask@ LeaveWindowMask@KeymapStateMask@ColormapChangeMask@ PointerMotionMask@ExposureMask@OwnerGrabButtonMask@ PointerMotionHintMask@VisibilityChangeMask@ .sp 5p .TE .KE .in .sp 1 See \*(z3, for more information on event types and masks. .SH "See Also" .na .br \s-1\fIXtAddEventHandler\fR\s+1\*(s1, \s-1\fIXtInsertRawEventHandler\fR\s+1\*(s1, \s-1\fIXtRemoveRawEventHandler\fR\s+1\*(s1, .br \s-1\fIXtEventHandler\fR\s+1\*(s2. .ad .XE "registering: raw event handler" .XE "raw event handlers" .XE "event handlers: raw; registering" .XE "event handlers, XtAddRawEventHandler" .XE "XtAddRawEventHandler" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAddTimeOut" "Xt \- Event Handling" .SH "Name" .Na XtAddTimeOut \- register a procedure to be called when a specified time elapses. .XX "XtAddTimeOut" .Nz .SH "Synopsis" .Sy XtIntervalId XtAddTimeOut(\f(CIinterval\fP, \f(CIproc\fP, \f(CIclient_data\fP) .As unsigned long \f(CIinterval\fP; XtTimerCallbackProc \f(CIproc\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIinterval\fP 1i Specifies the time interval in milliseconds. .IP \f(CIproc\fP 1i Specifies the procedure to be called when the time expires. .IP \f(CIclient_data\fP 1i Specifies data to be passed to \f(CIproc\fP when it is called. .SS "Returns" A handle of type \f(CWXtIntervalId\fP that can be used to unregister the timeout procedure with \f(CWXtRemoveTimeOut()\fP. .\" .SH "Availability" Superseded by \f(CWXtAppAddTimeOut()\fP. .\" .SH "Description" \f(CWXtAddTimeOut()\fP registers a procedure \f(CIproc\fP, to be called by \f(CWXtAppNextEvent()\fP with \f(CIclient_data\fP after \f(CIinterval\fP milliseconds elapse. The procedure is called once and automatically unregistered; it will not be called repeatedly every \f(CIinterval\fP milliseconds. .\" .SH "Usage" \f(CWXtAddTimeOut()\fP has been superseded by \f(CWXtAppAddTimeOut()\fP, which performs the same function on a per-application context basis. \f(CWXtAddTimeOut()\fP now calls \f(CWXtAppAddTimeOut()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtAddTimeOut()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppAddTimeOut()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppAddTimeOut()\fP for more information. .SH "See Also" .na .\"Section 1.4, "Events," .br \s-1\fIXtAppAddTimeOut\fR\s+1\*(s1, \s-1\fIXtAppNextEvent\fR\s+1\*(s1, \s-1\fIXtRemoveTimeOut\fR\s+1\*(s1, .br \s-1\fIXtTimerCallbackProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAddWorkProc" "Xt \- Event Handling" .SH "Name" .Na XtAddWorkProc \- register a procedure to be called when the event loop is idle. .XX "XtAddWorkProc" .Nz .SH "Synopsis" .Sy XtWorkProcId XtAddWorkProc(\f(CIproc\fP, \f(CIclient_data\fP) .As XtWorkProc \f(CIproc\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIproc\fP 1i Specifies the procedure to be called when the application is idle. .IP \f(CIclient_data\fP 1i Specifies data to be passed to \f(CIproc\fP when it is called. .SS "Returns" A handle of type \f(CWXtWorkProcId\fP that can be passed to \f(CWXtRemoveWorkProc()\fP to unregister the work procedure. .\" .SH "Availability" Superseded by \f(CWXtAppAddWorkProc()\fP. .\" .SH "Description" \f(CWXtAddWorkProc()\fP registers the procedure \f(CIproc\fP and the data \f(CIclient_data\fP to be called by \f(CWXtAppNextEvent()\fP when there are no pending input events and it would otherwise block. .\" .SH "Usage" \f(CWXtAddWorkProc()\fP has been superseded by \f(CWXtAppAddWorkProc()\fP, which performs the same function on a per-application context basis. \f(CWXtAddWorkProc()\fP now calls \f(CWXtAppAddWorkProc()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtAddWorkProc()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppAddWorkProc()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppAddWorkProc()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtAppAddWorkProc\fR\s+1\*(s1, \s-1\fIXtRemoveWorkProc\fR\s+1\*(s1, .br \s-1\fIXtWorkProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAllocateGC" "Xt \- Graphics Context" .SH "Name" .XS "XtAllocateGC" .XS "graphics contexts, obtaining" .XS "graphics contexts, sharable and modifiable" .XN "GCs (see graphics contexts)" .XN "graphics contexts: (see also XtAllocateGC)" .Na XtAllocateGC \- obtain a sharable GC with modifiable fields. .Nz .SH "Synopsis" .Sy GC XtAllocateGC(\f(CIobject\fP, \f(CIdepth\fP, \f(CIvalue_mask\fP, \f(CIvalues\fP, \f(CIdynamic_mask\fP, \f(CIdont_care_mask\fP) .As Widget \f(CIobject\fP; Cardinal \f(CIdepth\fP; XtGCMask \f(CIvalue_mask\fP; XGCValues *\f(CIvalues\fP; XtGCMask \f(CIdynamic_mask\fP; XtGCMask \f(CIdont_care_mask\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies an object; may be of class Object or any subclass thereof. .IP \f(CIdepth\fP 1i Specifies the depth for which the returned GC is valid, or 0. .IP \f(CIvalue_mask\fP 1i Specifies the fields of the GC which must have fixed values. .IP \f(CIvalues\fP 1i Specifies the values for the fields in \f(CIvalue_mask\fP. .IP \f(CIdynamic_mask\fP 1i Specifies fields of the GC which may be modified. .IP \f(CIdont_care_mask\fP 1i Specifies fields of the GC which will never be used. .SS "Returns" A GC with fields as specified in \f(CIvalue_mask\fP and \f(CIvalues\fP. .\" .SH "Availability" Release 5 and later. .\" .SH "Description" \f(CWXtAllocateGC()\fP returns a sharable GC with values as specified in \f(CIvalues\fP for each field set in \f(CIvalue_mask\fP. The GC is valid for the screen of the specified object (the screen of the nearest widget ancestor if the specified object is not itself a widget) and for drawable depth \f(CIdepth\fP. If \f(CIdepth\fP is 0, the depth is taken from the \f(CWXtNdepth\fP resource of the object (or from its nearest widget ancestor). The \f(CIdynamic_mask\fP and \f(CIdont_care_mask\fP arguments specify more information about the intended usage of the GC which influences how the GC may be shared. These arguments are explained below. .LP When returned, the GC may already be in use by other widgets, and it may be passed to other widgets in the future. For this reason, none of the fields specified in \f(CIvalue_mask\fP should ever be modified. The \f(CIdynamic_mask\fP argument specifies fields of the GC that may be modified by the widget. Because this is a shared GC, other widgets may also modify those fields, and a widget cannot rely on them to remain unchanged. For this reason, these fields must be explicitly set prior to every use. .LP The \f(CIdont_care_mask\fP argument specifies fields of the GC that the widget does not care about (i.e., fields that will never be used by any of the graphic functions called with this GC). The returned GC may have any values for these fields. .LP GC fields that are not specified in \f(CIvalue_mask\fP, \f(CIdynamic_mask\fP, or \f(CIdont_care_mask\fP will always have their default values in the returned GC. If a field is specified in both \f(CIvalue_mask\fP, and in \f(CIdynamic_mask\fP, then the field is modifiable, but will also be initialized to the appropriate value specified in \f(CIvalues\fP. If a field is set in \f(CIdont_care_mask\fP and is also set in one of the other masks, the \f(CIdont_care_mask\fP is ignored for that field. .\" .SH "Usage" \f(CWXtAllocateGC()\fP is a generalization of \f(CWXtGetGC()\fP. Calling \f(CWXtAllocateGC()\fP with \f(CIdepth\fP, \f(CIdynamic_mask\fP, and \f(CIdont_care_mask\fP all 0 is equivalent to calling \f(CWXtGetGC()\fP with the remaining arguments. .LP There are several common situations in which a modifiable GC is necessary. If you are drawing complex text with \f(CWXDrawText()\fP, the font field of your GC will be automatically changed to each of the font values in your text description. Also, if you use clip masks to protect or speed up drawing in a widget's expose method, you will need to modify the clipping fields of the GC. Using \f(CWXtAllocateGC()\fP with a \f(CIdynamic_mask\fP argument means that you can share a GC, with other instances of the same widget at least, instead of allocating a private GC with \f(CWXCreateGC()\fP. .LP Furthermore, specifying a \f(CIdont_care_mask\fP when allocating a shared GC can make that GC much more sharable. For example, if a widget draws text with \f(CWXDrawString()\fP only, then it is only interested in the font and foreground fields of a GC. If it allocates its GC and specifies that it doesn't care about the background field, then it can share its GC with another widget that uses the same font and foreground, but draws with \f(CWXDrawImageString()\fP and so \fIdoes\fP care about the background field. This kind of sharing is not possible with \f(CWXtGetGC()\fP. .LP Note that \f(CWXtAllocateGC()\fP is new in Release 5. If you use it in a widget, you will lose portability to Release 4. If you have a Release 4 widget that uses a private GC, you may be able to add conditional compilation directives to make it use the more efficient \f(CWXtAllocateGC()\fP when compiled with X11R5. .LP When done with a GC obtained with \f(CWXtAllocateGC()\fP, it should be freed with \f(CWXtReleaseGC()\fP. .\" .SH "Structures" The \f(CWXtGCMask\fP type is simply an unsigned long: .Ps \s-1typedef unsigned long XtGCMask; /* Mask of values that are used by widget*/\s+1 .Pe .Nd 10 Each of the symbols in the table below sets a single bit in an \f(CWXtGCMask\fP. The \f(CIvalue_mask\fP, \f(CIdynamic_mask\fP, and \f(CIdont_care_mask\fP arguments are formed by combining these symbols with the bitwise OR operator (\^\fB \fP\^): .sp 1 .in 0 .KS .TS linesize(2),tab(@); lp6fCW lp6fCW lp6fCW. .sp 2p GCArcMode@GCFillRule@GCLineWidth GCBackground@GCFillStyle@GCPlaneMask GCCapStyle@GCFont@GCStipple GCClipMask@GCForeground@GCSubwindowMode GCClipXOrigin@GCFunction@GCTile GCClipYOrigin@GCGraphicsExposures@GCTileStipXOrigin GCDashList@GCJoinStyle@GCTileStipYOrigin GCDashOffset@GCLineStyle .sp 5p .TE .KE .in .sp 1 The \f(CWXGCValues\fP structure has one field for each of the GC fields: .Ps .ps 8 .vs 10 .ta +4.5n +2i typedef struct { int function; /* logical operation */ unsigned long plane_mask; /* plane mask */ unsigned long foreground; /* foreground pixel */ unsigned long background; /* background pixel */ int line_width; /* line width */ int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */ int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */ int join_style; /* JoinMiter, JoinRound, JoinBevel */ int fill_style; /* FillSolid, FillTiled, FillStippled, FillOpaqueStippled */ int fill_rule; /* EvenOddRule, WindingRule */ int arc_mode; /* ArcChord, ArcPieSlice */ Pixmap tile; /* tile pixmap for tiling operations */ Pixmap stipple; /* stipple 1 plane pixmap for stippling */ int ts_x_origin; /* offset for tile or int ts_y_origin; * stipple operations */ Font font; /* default text font for text operations */ int subwindow_mode; /* ClipByChildren, IncludeInferiors */ Bool graphics_exposures; /* should exposures be generated? */ int clip_x_origin; /* origin for clipping */ int clip_y_origin; Pixmap clip_mask; /* bitmap clipping; other calls for rects */ int dash_offset; /* patterned/dashed line information */ char dashes; } XGCValues; .ps .vs .Pe .\" .SH "See Also" .na \s-1\fIXtGetGC\fR\s+1\*(s1, \s-1\fIXtReleaseGC\fR\s+1\*(s1. .ad .XE "graphics contexts, obtaining" .XE "graphics contexts, sharable and modifiable" .XE "XtAllocateGC" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAlmostProc" "Xt \- Widget Method Prototypes" .hw values .SH "Name" .Na XtAlmostProc \- interface definition for the \f(CWset_values_almost()\fP method. .Nz .XX "XtAlmostProc" .SH "Synopsis" .Sy typedef void (*XtAlmostProc)(Widget, Widget, XtWidgetGeometry *, .br XtWidgetGeometry *); .As Widget old; Widget set; XtWidgetGeometry *request; XtWidgetGeometry *reply; .Ae .SS "Inputs" .IP \f(CIold\fP 1i Specifies a copy of the object as it was before the \f(CWXtSetValues()\fR call. .IP \f(CIset\fP 1i Specifies the object instance record as modified by the various \f(CWset_values()\fP methods. .IP \f(CIrequest\fP 1i Specifies the original geometry request that was sent to the geometry manager that returned \f(CWXtGeometryAlmost\fR. .IP \f(CIreply\fP 1i Specifies the compromise geometry that was returned by the geometry manager that returned \f(CWXtGeometryAlmost\fR. .\" .SH "Description" \f(CWXtAlmostProc\fP is the type of the core \f(CWset_values_almost()\fP method. See \f(CWset_values_almost\fP(4) for more information. .\" .SH "See Also" .na \s-1\fIset_values_almost\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppAddActionHook" "Xt \- Translations and Actions" .SH "Name" .XX "XtAppAddActionHook" .Na XtAppAddActionHook \- register a procedure to be called before any action is invoked. .Nz .SH "Synopsis" .Sy XtActionHookId XtAppAddActionHook(\f(CIapp\fP, \f(CIproc\fP, \f(CIclient_data\fP) .As XtAppContext \f(CIapp\fP; XtActionHookProc \f(CIproc\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIapp\fP 1i Specifies the application context. .IP \f(CIproc\fP 1i Specifies the action hook procedure. .IP \f(CIclient_data\fP 1i Specifies data to be passed to the procedure. .SS "Returns" A handle of type \f(CWXtActionHookId\fP that can be passed to \f(CWXtRemoveActionHook()\fP to unregister the action hook procedure. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtAppAddActionHook()\fR registers a procedure \f(CIproc\fP to be called by the translation manager with data \f(CIclient_data\fP just before any action procedure is dispatched in the application context \f(CIapp\fP. Any number of action hook procedure/data pairs may be registered in an application context, and they will be called in reverse order of registration (i.e., the most recently registered will be the first called). .LP See \f(CWXtActionHookProc\fP(2) for an explanation of how to write an action hook procedure. .\" .SH "Usage" Action hooks can be used to record user actions for later playback using \f(CWXtCallActionProc()\fP. This is one way to implement keyboard macros. .LP An action hook procedure can be unregistered with \f(CWXtRemoveActionHook()\fP. .\" .SH "Structures" \f(CWXtActionHookId\fP is an opaque type. .\" .SH "See Also" .na \s-1\fIXtRemoveActionHook\fR\s+1\*(s1, .br \s-1\fIXtActionHookProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppAddActions" "Xt \- Translations and Actions" .SH "Name" .Na XtAppAddActions \- register an action table with the Translation Manager. .XS "actions table, adding" .XS "actions table, registering with Translation Manager" .XN "actions table: (see also actions)" .XN "registering, actions (see actions)" .XN "translations: (see also actions)" .XS "XtAppAddActions" .Nz .SH "Synopsis" .Sy void XtAppAddActions(\f(CIapp_context\fP, \f(CIactions\fP, \f(CInum_actions\fP) .As XtAppContext \f(CIapp_context\fP; XtActionList \f(CIactions\fP; Cardinal \f(CInum_actions\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CIactions\fP 1i Specifies the action table to register. .IP \f(CInum_args\fP 1i Specifies the number of entries in this action table. .\" .\" .SH "Description" \f(CWXtAppAddActions()\fP registers \f(CIactions\fP, an array of \f(CInum_actions\fP\ \f(CWXtActionsRec\fP structures with the Translation Manager for the application context \f(CIapp_context\fP. Each element of the array contains an action name and an action procedure pointer. When a named action is invoked through a translation table, the procedure to be called is looked up in the action tables that have been registered. .LP If more than one action is registered with the same name, the most recently registered action is used. If duplicate actions exist in an action table, the first is used. \f(CWXtAppAddActions()\fP registers actions globally to an application context. This is in contrast to actions placed in the Core widget class part \f(CWactions\fP field which are defined locally to a widget class only. .LP See \f(CWXtActionProc\fP(2) for an explanation of how to write an action procedure. .\" .SH "Usage" Note that there is no way to unregister actions. Registering an new definition for an action name will simply make the old definition inaccessible. .LP Action procedures should not assume that the widget in which they are invoked is realized; an accelerator can cause an action to be called for a widget that does not yet have a window. .LP You should never need to call \f(CWXtAppAddActions()\fP when writing a widget. Widget's actions are registered locally to the widget through the Core class part \f(CWactions\fP field. .\" .SH "Background" The translation manager provides an interface to specify and manage the mapping of X event sequences into procedure calls, for example, calling procedure \f(CWYes()\fP when the `Y' key is pressed. .LP The translation manager uses two kinds of tables to perform translations: .Ls b .IP \(bu 3n Action tables, which specify the mapping of externally available procedure name strings to the corresponding procedure. .IP \(bu 3n A translation table, which specifies the mapping of event sequences to procedure name strings. .LP The translation manager uses a simple algorithm to resolve the name of a procedure specified in a translation table into the actual procedure specified in an action table. When the widget is realized, the translation manager performs a search for the name in the following tables, in order: .IP \(bu 3n The widget's class and all superclass action tables, in subclass-to-superclass order. .IP \(bu 3n The parent's class and all superclass action tables, in subclass-to-superclass order, then on up the ancestor tree. .IP \(bu 3n The action tables registered with \f(CWXtAppAddActions()\fP and \f(CWXtAddActions()\fP from the most recently added table to the oldest table. .LP As soon as it finds a name, the translation manager stops the search. If it cannot find a name, the translation manager generates a warning message. .LP The Intrinsics reserve all action names and parameters starting with the characters "Xt" for future standard enhancements. Users, applications, and widgets should not declare action names or pass parameters starting with these characters except to invoke specified built-in Intrinsics functions. .LP .\" .SH "Example" An action table is generally declared as a statically initialized array. By convention, the name of an action and the C function name are identical except that the function name begins with an uppercase letter: .Ps static XtActionsRec global_actions[] = { {"confirm", Confirm}, {"quit", Quit}, }; .Pe .LP This action table could be registered with the following command: .Ps XtAppAddActions(app, global_actions, XtNumber(global_action)); .Pe .\" .SH "Structures" The \f(CWXtActionsRec\fP structure and the \f(CWXtActionList\fP type are defined as follows: .Ps typedef struct _XtActionsRec{ String string; XtActionProc proc; } XtActionsRec; typedef struct _XtActionsRec *XtActionList; .Pe .\" .SH "See Also" .na \s-1\fIXtActionProc\fR\s+1\*(s2. .ad .XE "actions table, adding" .XE "actions table, registering with Translation Manager" .XE "XtAppAddActions" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtAppAddAct 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtAppAddActionHook@XtAppAddAcA .sp .5 XtAppAddActions@XtAppAddAcB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppAddConverter" "Xt \- Resource Management" .SH "Name" .Na XtAppAddConverter \- register an "old-style" resource converter. .XS "converters: old-style, registering" .XS "XtAppAddConverter" .XS "registering, converters" .Nz .SH "Synopsis" .Sy .hw converter void XtAppAddConverter(\f(CIapp_context\fP, \f(CIfrom_type\fP, \f(CIto_type\fP, \f(CIconverter\fP, \f(CIconvert_args\fP, \f(CInum_args\fP) .As XtAppContext \f(CIapp_context\fP; String \f(CIfrom_type\fP; String \f(CIto_type\fP; XtConverter \f(CIconverter\fP; XtConvertArgList \f(CIconvert_args\fP; Cardinal \f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1.2i Specifies the application context. .IP \f(CIfrom_type\fP Specifies the source type of the resource to be converted. .IP \f(CIto_type\fP Specifies the destination type to which the resource is to be converted. .IP \f(CIconverter\fP Specifies the converter procedure. See \f(CWXtConverter\fP(2). .IP \f(CIconvert_args\fP Specifies how to obtain additional arguments needed for the conversion; if no arguments are provided, this should be \f(CWNULL\fR. See the Structures section below for a detailed description of the format of \f(CIconvert_args\fR. .IP \f(CInum_args\fP Specifies the number of additional arguments to the converter or zero. .\" .\" .SH "Description" \f(CWXtAppAddConverter()\fP registers \f(CIconverter\fP in application context \f(CIapp_context\fP as a procedure to convert data of resource type \f(CIfrom_type\fP to resource type \f(CIto_type\fP. .LP Each element of \f(CIconvert_args\fP is an \f(CWXtConvertArgRec\fP. It is not the argument actually passed to the converter procedure, but specifies how to obtain an \f(CWXrmValue\fP argument which will be passed to the converter. The "Background" section below explains the \f(CWXtConvertArgRec\fP structure in detail. .LP See \f(CWXtConverter\fP(2) for an explanation of how to write an "old-style" converter. .\" .SH "Usage" \f(CWXtAppAddConverter()\fP registers an "old-style" converter. This kind of converter is still in common use, but are not as flexible as the (incompatible) "new-style" converter added in Release 4. If you must register an existing old-style converter, use \f(CWXtAppAddConverter()\fP, but if you are writing a converter of your own, consider using a new-style converter. See \f(CWXtAppSetTypeConverter()\fP. .LP If you write a widget that has a resource which is of some enumerated type, you should write a converter routine which will convert between the symbolic names of each value and the values themselves. This converter should then be registered in your widget's \f(CWclass_initialize()\fP method. .LP If you are writing a programming library or an application that defines non-standard types, it may be useful to provide string converters for those types. This allows resources of that type to be specified from a resource file. An application that supported user-configurable popup menus, for example, might include a String-to-Menu converter. .LP Some converters need additional arguments, such as a screen or colormap in order to correctly perform the conversion. These converters are registered with an \f(CWXtConvertArgList\fP. Generally the author of the converter will also define a static array of \f(CWXtConvertArgRec\fP to be registered with the converter. There are also two \f(CWXtConvertArgList\fPs predefined by the Intrinsics: \f(CWscreenConvertArg\fR passes the widget's screen field to the converter in \f(CWargs[0]\fR, and \f(CWcolorConvertArgs\fR passes the widget's screen field to the converter in \f(CWargs[0]\fR and the widget's colormap field in \f(CWargs[1]\fR. .LP The Intrinsics define a number of standard converters which do not need to be registered. See \f(CWXtConvertAndStore()\fP for a list of these predefined converters. There are also a number of other useful converters defined in the Xmu library which do need to be registered explicitly. See \f(CWXmuCvtStringToMisc\fP(6). .\" .SH "Example" You can register the String-to-Widget converter from the Xmu library with the following: .Ps static XtConvertArgRec parentCvtArg[] = { {XtBaseOffset, (XtPointer)XtOffset(Widget, core.parent), sizeof(Widget)} }; XtAppAddConverter(app, XtRString, XtRWidget, XmuCvtStringToWidget, parentCvtArg, XtNumber(parentCvtArg)); .Pe .\" .SH "Background" For the few type converters that need additional arguments, the Intrinsics conversion mechanism provides a method of specifying how these arguments should be computed. Before a converter is called, each element of the \f(CWXtConvertArgList\fP is interpreted to determine the sizes and values of the arguments. These computed arguments are passed to the converter as an array of \f(CWXrmValue\fP. The enumerated type \f(CWXtAddressMode\fP and the structure \f(CWXtConvertArgRec\fP specify how each argument is derived. .LP .Ps .TA .5i 2.5i .ta .5i 2.5i typedef enum { /* address mode parameter representation */ XtAddress, /* address */ XtBaseOffset, /* offset */ XtImmediate, /* constant */ XtResourceString, /* resource name string */ XtResourceQuark, /* resource name quark */ XtWidgetBaseOffset, /* offset */ XtProcedureArg /* procedure to call */ } XtAddressMode; typedef struct { XtAddressMode address_mode; XtPointer address_id; Cardinal size; } XtConvertArgRec, *XtConvertArgList; .Pe .LP .XX XtConvertArgRec The \f(CWsize\fP field of an \f(CWXtConvertArgRec\fP specifies the length of the data in bytes. The \f(CWaddress_mode\fP field specifies how the \f(CWaddress_id\fP field should be interpreted. The possible values of \f(CWXtAddressMode\fP have the following meanings: .XX XtAddressMode .IP \f(CWXtAddress\fP .XX "XtAddress" causes \f(CWaddress_id\fP to be interpreted as the address of the data. .IP \f(CWXtBaseOffset\fP .XX "XtBaseOffset" causes \f(CWaddress_id\fP to be interpreted as the offset from the widget base. .IP \f(CWXtImmediate\fP .XX "XtImmediate" causes \f(CWaddress_id\fP to be interpreted as a constant. .IP \f(CWXtResourceString\fP .XX "XtResourceString" causes \f(CWaddress_id\fP to be interpreted as the name of a resource that is to be converted into an offset from the widget base. .IP \f(CWXtResourceQuark\fP .XX "XtResourceQuark" causes \f(CWaddress_id\fP to be interpreted as the result of an \f(CWXrmStringToQuark()\fP conversion on the name of a resource, which is to be converted into an offset from the widget base. .IP \f(CWXtWidgetBaseOffset\fP .XX "XtWidgetBaseOffset" is similar to \f(CWXtBaseOffset\fP except that it searches for the closest windowed ancestor if the object is not of a subclass of Core. .IP \f(CWXtProcedureArg\fP .XX "XtProcedureArg" specifies that \f(CWaddress_id\fP is a pointer to a procedure of type \f(CWXtConvertArgProc\fP to be invoked to return the conversion argument. See \f(CWXtConvertArgProc\fP(2) for an explanation of how to write a procedure of this type. .XX "XtConvertArgProc, used in an XtConvertArgRec" .\" .\" .SH "Structures" The \f(CWXtConvertArgRec\fP structure and the related \f(CWXtAddressMode\fP type are shown in the "Background" section above. .\" .SH "See Also" .na \s-1\fIXtAppSetTypeConverter\fR\s+1\*(s1, \s-1\fIXtCallConverter\fR\s+1\*(s1, \s-1\fIXtConvertandStore\fR\s+1, \s-1\fIXtDirectConvert\fR\s+1\*(s1, \s-1\fIXtSetTypeConverter\fR\s+1\*(s1, .br \s-1\fIXtConverter\fR\s+1\*(s2, \s-1\fIXtTypeConverter\fR\s+1\*(s2, \s-1\fIXtConvertArgProc\fR\s+1\*(s2, .br \s-1\fIXmuCvtStringToMisc\fR\s+1\*(s6. .ad .XE "converters: old-style, registering" .XE "XtAppAddConverter" .XE "registering, converters" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppAddInput" "Xt \- Event Handling" .SH "Name" .Na XtAppAddInput \- register a procedure to be called when there is activity on a file descriptor. .XS "files: file input; registering file" .XS "files: file input; XtAppAddInput" .XS "alternate input sources, registering" .XS "XtAppAddInput" .Nz .SH "Synopsis" .Sy XtInputId XtAppAddInput(\f(CIapp_context\fP, \f(CIsource\fP, \f(CIcondition\fP, \f(CIproc\fP, \f(CIclient_data\fP) .As XtAppContext \f(CIapp_context\fP; int \f(CIsource\fP; XtPointer \f(CIcondition\fP; XtInputCallbackProc \f(CIproc\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CIsource\fP 1i Specifies the file descriptor (on a \s-1POSIX\s+1-based system) to monitor. .IP \f(CIcondition\fP 1i Specifies a mask that indicates a read, write, or exception condition or some operating-system-dependent condition. .IP \f(CIproc\fP 1i Specifies the procedure that is to be called when \f(CIcondition\fP occurs on \f(CIsource\fP. .IP \f(CIclient_data\fP 1i Specifies data to be passed to \f(CIproc\fP when it is invoked. .SS "Returns" A handle of type \f(CWXtInputId\fP that can be passed to \f(CWXtRemoveInput()\fP to unregister this input procedure. .\" .\" .\" .SH "Description" \f(CWXtAddInput()\fP registers a file descriptor \f(CIsource\fP to be monitored by \f(CWXtAppNextEvent()\fP and a procedure \f(CIproc\fP to be called with data \f(CIclient_data\fP when the condition (such as "input ready" or "error") \f(CIcondition\fP arises. .LP On a \s-1POSIX\s+1-based system, the supported values for \f(CIcondition\fP are \f(CWXtInputReadMask\fR, \f(CWXtInputWriteMask\fR, or \f(CWXtInputExceptMask\fR. These values cannot be ORed together. On non-\s-1POSIX\s+1 systems, the types of \f(CIsource\fP and \f(CIcondition\fP will be operating-system dependent. .LP See \f(CWXtInputCallbackProc\fP(2) for an explanation of how to write an input callback. .LP See the \s-1POSIX\s+1 \f(CWselect()\fP system call for more information on the possible file descriptor conditions that can be selected for. .\" .SH "Usage" \f(CWXtAppAddInput()\fP allows an Xt application to receive non-X based events through the same event loop that delivers X events. File descriptors in \s-1POSIX\s+1 are a very general mechanism, and \f(CWXtAppAddInput()\fP can be used to receive notification when the user types a command to stdin, when a child process closes a pipe, or when there is data available on an RPC socket, for example. .LP An input callback can be unregistered by calling \f(CWXtRemoveInput()\fP and passing the \f(CWXtInputId\fP returned by this function. .LP Note that when reading from a socket, you should be careful not to close the end of the socket that is waiting before exiting \f(CWXtAppMainLoop()\fP. If you do this, you will get an infinite loop, in which the callback is called repeatedly, while the Intrinsics wait for an EOF to be read. .\" .SH "Structures" The \f(CWXtInputId\fP type is defined as follows: .Ps typedef unsigned long XtInputId; .Pe .\" .SH "See Also" .na \s-1\fIXtRemoveInput\fR\s+1\*(s1, .br \s-1\fIXtInputCallbackProc\fR\s+1\*(s2. .ad .XE "files: file input; registering file" .XE "files: file input; XtAppAddInput" .XE "alternate input sources, registering" .XE "XtAppAddInput" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppAddTimeOut" "Xt \- Event Handling" .Na XtAppAddTimeOut \- register a procedure to be called when a specified time elapses. .XX "timeouts, invoking procedure after timeout" .XX "timeouts, XtAppAddTimeOut" .XX "XtAppAddTimeOut" .Nz .SH "Synopsis" .Sy XtIntervalId XtAppAddTimeOut(\f(CIapp_context\fP, \f(CIinterval\fP, \f(CIproc\fP, \f(CIclient_data\fP) .As XtAppContext \f(CIapp_context\fP; unsigned long \f(CIinterval\fP; XtTimerCallbackProc \f(CIproc\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context in which the timer is to be set. .IP \f(CIinterval\fP 1i Specifies the time interval in milliseconds. .IP \f(CIproc\fP 1i Specifies the procedure that is to be called when the time expires. See \f(CWXtTimerCallbackProc\fP(2). .IP \f(CIclient_data\fP 1i Specifies data to be passed to \f(CIproc\fP when it is called. .SS "Returns" A handle of type \f(CWXtIntervalId\fP that can be used to unregister the timeout procedure with \f(CWXtRemoveTimeOut()\fP. .\" .\" .SH "Description" \f(CWXtAppAddTimeOut()\fP registers, in application context \f(CIapp_context\fP, a procedure \f(CIproc\fP, to be called by \f(CWXtAppNextEvent()\fP with \f(CIclient_data\fP after \f(CIinterval\fP milliseconds elapse. The procedure is called once and automatically unregistered; it will not be called repeatedly every \f(CIinterval\fP milliseconds. .LP See \f(CWXtTimerCallbackProc\fP(2) for an explanation of how to write a timer callback. .\" .SH "Usage" Timer callbacks are automatically unregistered after they are triggered. To have a callback called at a regular interval, call \f(CWXtAppAddTimeOut()\fP again from within the timer callback. .LP A timer callback can be explicitly unregistered before it is invoked by calling \f(CWXtRemoveTimeOut()\fP with the \f(CWXtIntervalId\fP returned by this function. .\" .SH "Structures" The \f(CWXtIntervalId\fP type is defined as follows: .Ps typedef unsigned long XtIntervalId; .Pe .\" .SH "See Also" .na .br \s-1\fIXtAppNextEvent\fR\s+1\*(s1, \s-1\fIXtRemoveTimeOut\fR\s+1\*(s1, .br \s-1\fIXtTimerCallbackProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppAddWorkProc" "Xt \- Event Handling" .Na XtAppAddWorkProc \- register a procedure to be called when the event loop is idle. .Nz .XX "registering: work procedure" .XX "work procedures, XtAppAddWorkProc" .XX "work procedures, registering" .XX "background processing, XtAppAddWorkProc" .XX "XtAppAddWorkProc" .SH "Synopsis" .Sy XtWorkProcId XtAppAddWorkProc(\f(CIapp_context\fP, \f(CIproc\fP, \f(CIclient_data\fP) .As XtAppContext \f(CIapp_context\fP; XtWorkProc \f(CIproc\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CIproc\fP 1i Specifies the procedure that is to be called when the application is idle. .IP \f(CIclient_data\fP 1i Specifies data to be passed to \f(CIproc\fP when it is called. .SS "Returns" A handle of type \f(CWXtWorkProcId\fP that can be passed to \f(CWXtRemoveWorkProc()\fP to unregister the work procedure. .\" .SH "Description" \f(CWXtAddWorkProc()\fP registers the procedure \f(CIproc\fP and the data \f(CIclient_data\fP to be called by \f(CWXtAppNextEvent()\fP or \f(CWXtAppProcessEvent()\fP when there are no pending input events and it would otherwise block. Multiple work procedures can be registered, and the most recently added one is always the one that is called. However, if a work procedure itself adds another work procedure, the newly added one has lower priority than the current one. .LP A work procedure returns a \f(CWBoolean\fP. If it returns \f(CWTrue\fP, it will automatically be unregistered and will not be called again. If it returns \f(CWFalse\fP it will be called the next time the application is idle. See \f(CWXtWorkProc\fP(2) for more information. .\" .SH "Usage" \f(CWXtAppAddWorkProc()\fP implements a limited form of background processing. Most applications spend most of their time waiting for input; to do useful work during this idle time, you can register a work procedure that will run when the application is idle. .LP A work procedure must return quickly or the application will not be able to promptly respond to user events. If a large task needs to be done in the background, the work procedure should periodically save its state and return \f(CWFalse\fP. Work procedures should not be used to do frivolous work in the background. In a multi-tasking system, an idle application should generally actually be idle, and not steal CPU time from other processes. .LP A work procedure can be explicitly removed by calling \f(CWXtRemoveWorkProc()\fP with the \f(CWXtWorkProcId\fP returned by this function. .\" .SH "Structures" The \f(CWXtWorkProcId\fP type is defined as follows: .Ps typedef unsigned long XtWorkProcId; .Pe .\" .Nd 4 .SH "See Also" .na \s-1\fIXtAppNextEvent\fR\s+1\*(s1, \s-1\fIXtAppProcessEvent\fR\s+1\*(s1, \s-1\fIXtRemoveWorkProc\fR\s+1\*(s1, .br \s-1\fIXtWorkProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppCreateShell" "Xt \- Initialization" .SH "Name" .Na XtAppCreateShell \- create a shell widget at the root of a widget tree. .XS "widgets: creating; independent widget trees" .XN "widgets: creating; (see also XtAppCreateShell)" .XS "XtAppCreateShell" .LP .Nz .SH "Synopsis" .Sy Widget XtAppCreateShell(\f(CIapplication_name\fP, \f(CIapplication_class\fP, \f(CIwidget_class\fP, \f(CIdisplay\fP, \f(CIargs\fP, \f(CInum_args\fP) .As String \f(CIapplication_name\fP; String \f(CIapplication_class\fP; WidgetClass \f(CIwidget_class\fP; Display *\f(CIdisplay\fP; ArgList \f(CIargs\fP; Cardinal \f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIapplication_name\fP 1i Specifies the resource name of the shell widget, or \f(CWNULL\fP. .IP \f(CIapplication_class\fP 1i Specifies the resource class to be used for the shell widget if it is of \f(CWapplicationShellWidgetClass\fP or a subclass thereof. .IP \f(CIwidget_class\fP 1i Specifies the widget class of the created widget. (normally \f(CWapplicationShellWidgetClass\fP). .IP \f(CIdisplay\fP 1i Specifies the display on which the shell is to be created. .IP \f(CIargs\fP 1i Specifies the argument list to override other resource specifications. .IP \f(CInum_args\fP 1i Specifies the number of arguments in the argument list. .\" .SH "Description" \f(CWXtAppCreateShell()\fP creates a shell widget of class \f(CIwidget_class\fP on display \f(CIdisplay\fP. The created widget has no parent\-it is at the root of a widget tree and at the top of the resource name hierarchy. The resource name of the widget is either \f(CIapplication_name\fP, or, if that is \f(CWNULL\fP, the name that was passed to \f(CWXtDisplayInitialize()\fP or \f(CWXtOpenDisplay()\fP when the display was initialized. The resource class of the widget is either \f(CIapplication_class\fP, if the \f(CWwidget_class\fP is \f(CWapplicationShellWidgetClass\fP or a subclass, or the normal class name of the widget otherwise. The widget is created on the screen specified by the \f(CWXtNscreen\fP resource or on the default screen of \f(CIdisplay\fP if no such resource is found. .LP In X11R4, the \f(CWXtNscreen\fP and other resources are all obtained from \f(CIargs\fP and from the database of \f(CIdisplay\fP. In X11R5, however, there is a resource database for each screen of a display, and the resources for the created shell widget are obtained somewhat differently: the argument list \f(CIargs\fP is first scanned for a resource named \f(CWXtNscreen\fP, and if none is found, the database of the default screen of \f(CIdisplay\fP is searched for this resource. If the\p \f(CWXtNscreen\fP resource is found the database from the specified screen is used for all the remaining resources of the widget. If the \f(CWXtNscreen\fP resource is not found, the database of the default screen continues to be used. In either case, the resources in \f(CIargs\fP override values in the database. .\" .SH "Usage" Most applications can simply use \f(CWXtAppInitialize()\fP which initializes the toolkit, creates an application context, opens a display, and then calls \f(CWXtAppCreateShell()\fP to create a shell on that display. .LP An application that wishes to have multiple toplevel windows on the same screen (a mail reader and a mail composer, for example) should generally use \f(CWXtCreatePopupShell()\fP to create additional shells within the widget tree and resource hierarchy of the original shell. Creating multiple root shells with different names is generally not a good idea because then your application will have resources specified under several different hierarchies. It is sometimes useful to create multiple root shells with the \fIsame\fP name, however, if your application is capable of creating multiple instances of itself. Each of these instances will find the same resources in the same database and will appear to be "clones" of each other. .LP To create shells on multiple displays, open each display with \f(CWXtOpenDisplay()\fP and use the resulting \f(CWDisplay *\fP in a call to \f(CWXtAppCreateShell()\fP. If all displays are initialized in the same application context, then all events will be correctly handled by \f(CWXtAppMainLoop()\fP. .LP \f(CWXtAppCreateShell()\fP can also be used to create toplevel shells on multiple screens. Note that prior to X11R5, however, it is not possible to maintain separate resource databases for each screen. .LP The specified widget class for the new shell widget should almost always be \f(CWapplicationShellWidgetClass\fP or some subclass. .LP \f(CWXtVaAppCreateShell()\fP behaves identically to \f(CWXtAppCreateShell()\fP, but takes a \f(CWNULL\fP-terminated variable-length argument list of resource name/resource value pairs rather than an array of \f(CWArg\fP. .\" .SH "See Also" .na \s-1\fIXtAppInitialize\fR\s+1\*(s1, \s-1\fIXtCreatePopupShell\fR\s+1\*(s1, .hw DisplayInitialize \s-1\fIXtDisplayInitialize\fR\s+1\*(s1, \s-1\fIXtOpenDisplay\fR\s+1\*(s1, .br \s-1\fIXtVaAppCreateShell\fR\s+1\*(s1. .ad .XE "widgets: creating; independent widget trees" .XE "XtAppCreateShell" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppError" "Xt \- Error Handling" .SH "Name" .Na XtAppError \- call the low-level error handler. .XX "errors: fatal error procedure; calling low-level" .XN "fatal error (see error)" .XN "errors: (see also XtAppError)" .XX "XtAppError" .XX "error handling, XtAppError" .Nz .SH "Synopsis" .Sy void XtAppError(\f(CIapp_context\fP, \f(CImessage\fP) .As XtAppContext \f(CIapp_context\fP; String \f(CImessage\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CImessage\fP 1i Specifies the error message to be reported. .SS "Returns" \f(CWXtAppError()\fP terminates the application and does not return. .\" .\" .SH "Description" \f(CWXtAppError()\fP passes its arguments to the installed low-level error handler. On \s-1POSIX\s+1 systems, the default handler is \f(CW_XtDefaultError()\fP. It prints the message to the stderr stream and calls \f(CWexit()\fP. .\" .SH "Usage" To report non-fatal error messages or warnings without exiting, use \f(CWXtAppWarning()\fP or \f(CWXtAppWarningMsg()\fP. To change the low-level error handler, use \f(CWXtAppSetErrorHandler()\fP. .LP \f(CWXtAppError()\fP calls the "low-level" error handler. It is better to use \f(CWXtAppErrorMsg()\fP which calls the "high-level" error handler. The high-level handler looks up the error message in a resource database and so allows for customization and internationalization of error messages. .LP Although the Intrinsics interface allows separate error and warning handlers for each application context, most implementations will support only a single set of handlers. When a new handler is installed, it will be used in all application contexts. .\" .SH "See Also" .na \s-1\fIXtAppErrorMsg\fR\s+1\*(s1, \s-1\fIXtAppSetErrorHandler\fR\s+1\*(s1, \s-1\fIXtAppSetErrorMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppWarning\fR\s+1\*(s1, \s-1\fIXtAppWarningMsg\fR\s+1\*(s1, .br \s-1\fIXtErrorHandler\fR\s+1\*(s2. \s-1\fIXtErrorMsgHandler\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppErrorMsg" "Xt \- Error Handling" .SH "Name" .Na XtAppErrorMsg \- call the high-level fatal error handler. .XS "errors: fatal error procedure; calling high-level" .XS "error handling: calling fatal error handler" .XN "errors: (see also XtAppErrorMsg)" .XN "error handling: (see also XtAppErrorMsg)" .XS "XtAppErrorMsg" .Nz .XS "error handling, XtAppErrorMsg" .SH "Synopsis" .Sy void XtAppErrorMsg(\f(CIapp_context\fP, \f(CIname\fP, \f(CItype\fP, \f(CIclass\fP, \f(CIdefault\fP, \ \f(CIparams\fP, \f(CInum_params\fP) .As XtAppContext \f(CIapp_context\fP; String \f(CIname\fP; String \f(CItype\fP; String \f(CIclass\fP; String \f(CIdefault\fP; String *\f(CIparams\fP; Cardinal *\f(CInum_params\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CIname\fP 1i Specifies the general kind of error. .IP \f(CItype\fP 1i Specifies the detailed name of the error. .IP \f(CIclass\fP 1i Specifies the resource class of the error. .IP \f(CIdefault\fP 1i Specifies the default message to use if no message is found in the database. .IP \f(CIparams\fP 1i Specifies an array of values to be inserted into the message. .IP \f(CInum_params\fP 1i Specifies the number of elements in \f(CIparams\fP. .SS "Returns" \f(CWXtAppErrorMsg()\fP terminates the application and does not return. .\" .SH "Description" \f(CWXtAppErrorMsg()\fP passes all of its arguments except \f(CIapp_context\fP to the installed high-level error handler. The default high-level error handler is \f(CW_XtDefaultErrorMsg()\fP. It calls \f(CWXtAppGetErrorDatabaseText()\fP to lookup an error message of the specified \f(CIname\fP, \f(CItype\fP, and \f(CIclass\fP in the error database. If no such message is found, \f(CWXtAppGetErrorDatabaseText()\fP returns the specified \f(CIdefault\fP message. In either case, \f(CW_XtDefaultErrorMsg()\fP does a \f(CWprintf\fP-style substitution of \f(CIparams\fP into the message, and passes the resulting text to the low-level error handler by calling \f(CWXtError()\fP. .LP See \f(CWXtAppGetErrorDatabaseText()\fP for details on how messages are looked up in the error database. .\" .SH "Usage" To report non-fatal error messages or warnings without exiting, use \f(CWXtAppWarningMsg()\fP. To change the high-level error handler, use \f(CWXtAppSetErrorMsgHandler()\fP. .LP Note that the \f(CInum_params\fP argument to this function is a \f(CWCardinal *\fP, not a \f(CWCardinal\fP. .LP Although the Intrinsics interface allows separate error and warning handlers for each application context, most implementations will support only a single set of handlers. When a new handler is installed, it will be used in all application contexts. .\" .SH "Example" The following code is from the Intrinsics internal function \f(CW_XtCreateWidget()\fP: .Ps String params[2]; Cardinal num_params = 2; params[0] = name; params[1] = XtName(parent); XtAppErrorMsg(XtWidgetToApplicationContext(parent), "nonWidget", XtNxtCreateWidget, XtCXtToolkitError, "attempt to add non-widget child to parent which supports only widgets", params, &num_params); .Pe .\" .SH "See Also" .na \s-1\fIXtAppError\fR\s+1\*(s1, \s-1\fIXtAppSetErrorHandler\fR\s+1\*(s1, \s-1\fIXtAppSetErrorMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppWarning\fR\s+1\*(s1, \s-1\fIXtAppWarningMsg\fR\s+1\*(s1, .br \s-1\fIXtErrorMsgHandler\fR\s+1\*(s2. .ad .XE "errors: fatal error procedure; calling high-level" .XE "error handling: calling fatal error handler" .XE "XtAppErrorMsg" .XE "error handling, XtAppErrorMsg" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppGetErrorDatabase" "Xt \- Error Handling" .SH "Name" .Na XtAppGetErrorDatabase \- obtain the default error database. .XX "error handling: error resource database; obtaining" .XX "error handling: error resource database; XtAppGetErrorDatabase" .XX "XtAppGetErrorDatabase" .Nz .XX "error handling, XtAppGetErrorDatabase" .SH "Synopsis" .Sy XrmDatabase *XtAppGetErrorDatabase(\^\f(CIapp_context\fP\^) .As XtAppContext \f(CIapp_context\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .SS "Returns" The address of an \f(CWXrmDatabase\fP. .SH "Description" \f(CWXtAppGetErrorDatabase()\fP returns the address of the \f(CWXrmDatabase\fP error message database used by the default high-level error and warning handlers for \f(CIapp_context\fP. This database may be empty until \f(CWXtAppGetErrorDatabaseText()\fP is called for the first time. .LP While the X Toolkit specification permits individual error databases for each application context, most implementations will only support a single database. In the MIT implementation, the error database file is \fI/usr/lib/X11/XtErrorDB\fP. .\" .SH "Usage" You should never need to call this function if you simply want to report error and warning messages through the standard handlers. .LP Because the Intrinsics do not support the customization and internationalization of error messages very well, some applications may want to override values in the default database with their own customized messages. The default database can be obtained for this purpose by making a single dummy call to \f(CWXtAppGetErrorDatabaseText()\fP and then calling \f(CWXtAppGetErrorDatabase()\fP. .SH "See Also" .na \s-1\fIXtAppErrorMsg\fR\s+1\*(s1, \s-1\fIXtAppGetErrorDatabaseText\fR\s+1\*(s1, \s-1\fIXtAppWarningMsg\fR\s+1\*(s1, .br \s-1\fIXtErrorMsgHandler\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppGetErrorDatabaseText" "Xt \- Error Handling" .SH "Name" .Na XtAppGetErrorDatabaseText \- get the text of a named message from the error database. .XS "error database" .XS "error handling: error resource database; XtAppGetErrorDatabaseText" .XS "XtAppGetErrorDatabaseText" .Nz .XS "error handling, XtAppGetErrorDatabaseText" .SH "Synopsis" .Sy void XtAppGetErrorDatabaseText(\f(CIapp_context\fP, \f(CIname\fP, \f(CItype\fP, \f(CIclass\fP, \f(CIdefault\fP, \f(CIbuffer_return\fP, \f(CInbytes\fP, \f(CIdatabase\fP) .As XtAppContext \f(CIapp_context\fP; String \f(CIname\fP, \f(CItype\fP, \f(CIclass\fP; String \f(CIdefault\fP; String \f(CIbuffer_return\fP; int \f(CInbytes\fP; XrmDatabase \f(CIdatabase\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CIname\fP 1i Specifies the name or general kind of the message. .IP \f(CItype\fP 1i Specifies the type or detailed name of the message. .IP \f(CIclass\fP 1i Specifies the resource class of the error message. .IP \f(CIdefault\fP 1i Specifies the default message to use if an error database entry is not found. .IP \f(CInbytes\fP 1i Specifies the size of \f(CIbuffer_return\fP in bytes. .IP \f(CIdatabase\fP 1i Specifies the database to be used, or \f(CWNULL\fP if the application's database is to be used. .SS "Outputs" .IP \f(CIbuffer_return\fP 1i Specifies the buffer into which the error message is to be returned. .\" .SH "Description" \f(CWXtAppGetErrorDatabaseText()\fP looks up the message named by \f(CIname\fP, \f(CItype\fP, and \f(CIclass\fP in \f(CIdatabase\fP or in the database returned by \f(CWXtAppGetErrorDatabase()\fP for \f(CIapp_context\fP if \f(CIdatabase\fP is \f(CWNULL\fP. If such a message is found, it is stored into \f(CIbuffer_return\fP, otherwise the message in \f(CIdefault\fP is stored into \f(CIbuffer_return\fP. .LP The resource name of the message is formed by concatenating \f(CIname\fP and \f(CItype\fP with a single "." between them. The resource class of the message is \f(CIclass\fP if it already contains a ".", or otherwise is formed by concatenating \f(CIclass\fP with itself with a single "." between the strings. .\" .SH "Usage" You should not need to call \f(CWXtAppGetErrorDatabaseText()\fP unless you are writing a customized high-level error or warning handler. .LP Because the Intrinsics do not support the customization and internationalization of error messages very well, some applications may want to read a customized error database (found with \f(CWXtResolvePathname()\fP or named by an application resource, for example) and provide customized error and warning handlers that call \f(CWXtAppGetErrorDatabaseText()\fP specifying this custom database explicitly. .LP While the X Toolkit specification permits individual error databases for each application context, most implementations will only support a single database. In the MIT implementation, the error database file is \fI/usr/lib/X11/XtErrorDB\fP. .SH "See Also" .na \s-1\fIXtAppGetErrorDatabase\fR\s+1\*(s1, .br \s-1\fIXtErrorMsgHandler\fR\s+1\*(s2. .ad .XE "error database" .XE "error handling: error resource database; XtAppGetErrorDatabaseText" .XE "XtAppGetErrorDatabaseText" .XE "error handling, XtAppGetErrorDatabaseText" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtAppGetErr 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtAppGetErrorDatabase@XtAppGetErA .sp .3 XtAppGetErrorDatabaseText@XtAppGetErB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppGetSelectionTimeout" "Xt \- Selections" .SH "Name" .Na XtAppGetSelectionTimeout \- get the current Intrinsics selection timeout value. .XN "selections: timeout; (see also timeouts)" .XX "timeouts: selection timeout value" .XX "timeouts, XtAppGetSelectionTimeout" .XX "XtAppSelectionTimeout" .Nz .SH "Synopsis" .Sy unsigned long XtAppGetSelectionTimeout(\f(CIapp_context\fP) .As XtAppContext \f(CIapp_context\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .SS "Returns" The selection timeout interval for the application context. .\" .SH "Description" \f(CWXtAppGetSelectionTimeout()\fP returns the current selection timeout value for the specified application context, in milliseconds. The selection timeout is the time within which the two communicating applications must respond to one another. The initial timeout value is set by the \f(CWselectionTimeout\fP application resource, which defaults to 5000 milliseconds (5 seconds). .\" .SH "Usage" A new timeout value can be set by a call to \f(CWXtAppSetSelectionTimeout()\fP. You should rarely need to query or set this value. In particular, an application generally should not change this value except under the explicit request of the user. .SH "See Also" .na \s-1\fIXtAppSetSelectionTimeout\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppInitialize" "Xt \- Initialization" .SH "Name" .XX "XtAppInitialize" .Na XtAppInitialize \- initialize the X Toolkit internals, create an application context, open and initialize a display, and create the initial application shell instance. .Nz .SH "Synopsis" .\"------------------------------------------------------------ .Sy Widget XtAppInitialize(\f(CIapp_context_return\fP, \f(CIapplication_class\fP, \f(CIoptions\fP, \f(CInum_options\fP, \f(CIargc_in_out\fP, \f(CIargv_in_out\fP, \f(CIfallback_resources\fP, \f(CIargs\fP, \f(CInum_args\fP) .As XtAppContext *\f(CIapp_context_return\fP; String \f(CIapplication_class\fP; XrmOptionDescList \f(CIoptions\fP; Cardinal \f(CInum_options\fP; int *\f(CIargc_in_out\fP; /* was type Cardinal * in R4 */ String *\f(CIargv_in_out\fP; String *\f(CIfallback_resources\fP; ArgList \f(CIargs\fP; Cardinal \f(CInum_args\fP; .Ae .SS "Inputs" .\"------------------------------------------------------------ .IP \f(CIapplication_class\fP 1.5i Specifies the class name of the application. .IP \f(CIoptions\fP 1.5i Specifies an array of \f(CWXrmOptionDescRec\fP which describe how to parse the command line. .IP \f(CInum_options\fP 1.5i Specifies the number of elements in \f(CIoptions\fP. .IP \f(CIargc_in_out\fP 1.5i Specifies the address of the number of command line arguments. This argument is of type \f(CWint *\fP in Release 5 and of type \f(CWCardinal *\fP in Release 4. .IP \f(CIargv_in_out\fP 1.5i Specifies the array of command line arguments. .IP \f(CIfallback_resources\fP 1.5i Specifies a \f(CWNULL\fP-terminated array of resource specification strings to be used if the application class resource file cannot be opened or read, or \f(CWNULL\fR if no fallback resources are desired. .IP \f(CIargs\fP 1.5i Specifies an argument list to override any other resource specifications for the created shell widget. .IP \f(CInum_args\fP 1.5i Specifies the number of elements in \f(CIargs\fR. .SS "Outputs" .\"------------------------------------------------------------ .IP \f(CIapp_context_return\fP 1.5i Returns the newly created application context, if non-\f(CWNULL\fP. .IP \f(CIargc_in_out\fP 1.5i Returns the number of command line arguments remaining after the command line is parsed by \f(CWXtDisplayInitialize()\fP. .IP \f(CIargv_in_out\fP 1.5i Returns the command line as modified by \f(CWXtDisplayInitialize()\fP. .SS "Returns" .\"------------------------------------------------------------ A toplevel shell widget of class \f(CWapplicationShellWidgetClass\fP. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" .\"------------------------------------------------------------ \f(CWXtAppInitialize()\fP is a convenience procedure that most applications will use to initialize themselves. It does the following: .IP \(bu 3n Calls \f(CWXtToolkitInitialize()\fP to do Intrinsics internal initialization. .IP \(bu 3n Calls \f(CWXtCreateApplicationContext()\fP to create an application context for the application. If \f(CIapp_context_return\fP is non-\f(CWNULL\fP, the newly created application context is stored at the address it points to. .IP \(bu 3n Calls \f(CWXtAppSetFallbackResources()\fP passing the application context and \f(CIfallback_resources\fP, unless that argument is \f(CWNULL\fP. .IP \(bu 3n Calls \f(CWXtOpenDisplay()\fP passing the application context, \f(CIapplication_class\fP, \f(CIoptions\fP, \f(CInum_options\fP, \f(CIargc_in_out\fP, and \f(CIargv_in_out\fP. \f(CWXtOpenDisplay()\fP determines the display name and the application name from the command line or environment variables, opens a connection to the display, and calls \f(CWXtDisplayInitialize()\fP to parse the command line and build the resource database. The command line as modified by \f(CWXtDisplayInitialize()\fP is returned in \f(CIargc_in_out\fP and \f(CWargv_in_out\fP. See the "Background" section below for more details on all of these steps. .IP \(bu 3n Calls \f(CWXtAppCreateShell()\fP to create an applicationShellWidgetClass shell, passing \f(CIargs\fP and \f(CInum_args\fP to override any resources found in the database. .LP If the display cannot be opened, an error message is issued and \f(CWXtAppInitialize()\fR terminates the application. .\" .SH "Usage" .\"------------------------------------------------------------ Most applications can \f(CWXtAppInitialize()\fP to initialize themselves. Most programmers will not need to understand the details of initialization described in the "Background" section below. Applications that open multiple displays or create multiple application contexts will have to use the lower-level initialization functions explicitly. .LP Most applications can have all their command-line options automatically parsed by declaring an \f(CWXrmOptionDescList\fP and passing it to \f(CWXtAppInitialize()\fP which will convert values on the command line into values in the resource database which can then be retrieved into a structure with \f(CWXtGetApplicationResources()\fP. This is a good idea, because if your application supports customization through application resources (which it should if there is anything to customize) then customization through the command line comes essentially for free. .LP If all your command line options are parsed this way, then \f(CWXtAppInitialize()\fP should remove everything except \f(CIargv\f(CW[0]\fR from the command line and should set \f(CIargc\fP to 1. If this is not the case when \f(CWXtAppInitialize()\fP returns, then the user has requested an unrecognized option. If you parse some command line options manually, you should parse them after calling \f(CWXtAppInitialize()\fP. .LP The "Background" section below explains how to declare an \f(CWXrmOptionDescList\fP and the example below shows the one used by \fIviewres\fP. .LP The \f(CIfallback_resources\fP argument is an array of strings, each string equivalent to a line in a resource file. If your application relies on an app-defaults file, you can use fallback resources as a backup to be used in case the app-defaults file is installed incorrectly or otherwise cannot be found. If the application needs many resources to function properly, your fallback resources might simply set a label widget to display an error message which informs the user that the app-defaults file could not be found. The example below shows a simple fallback resource list. .LP In Release 4, the \f(CIargc_in_out\fP argument is of type \f(CWCardinal *\fP, and in Release 5, this argument is of type \f(CWint *\fP. This is a minor incompatibility that may result warnings from ANSI-C compilers when porting from one release to another. The example below shows a way around this problem. .LP \f(CWXtVaAppInitialize()\fP performs the same function as \f(CWXtAppInitialize()\fP, but accepts a \f(CWNULL\fP-terminated variable-length argument list of resource name/resource value pairs instead of an \f(CIArgList\fP. .\" .SH "Example" .\"------------------------------------------------------------ The following initialization code is adapted from the X11R5 \fIviewres\fP application. .Ps static XrmOptionDescRec Options[] = { { "-top", "*topObject", XrmoptionSepArg, (XPointer) NULL }, { "-variable", "*showVariable", XrmoptionNoArg, (XPointer) "on" }, { "-vertical", "*Tree.Gravity", XrmoptionNoArg, (XPointer) "north" } }; static char *fallback_resources[] = { "*allowShellResize: true", "*Porthole.top: ChainTop", "*Porthole.left: ChainLeft", "*Porthole.bottom: ChainBottom", "*Porthole.right: ChainRight", "*Porthole.resizable: on", (char *) NULL }; main (argc, argv) int argc; char **argv; { Widget toplevel; XtAppContext app_con; toplevel = XtAppInitialize(&app_con, "Viewres", Options, XtNumber (Options), #if XtSpecificationRelease > 4 &argc, #else (Cardinal *)&argc, #endif argv, fallback_resources, (ArgList) NULL, (Cardinal) 0); if (argc != 1) display_usage_message(); . . . } .Pe .\" .SH "Background" .\"------------------------------------------------------------ Initializing an application is a complex process. It involves determining the display to be opened, determining the name of the application, setting the locale of the application, determining the screen on which to create the shell widget, parsing the command line, and building the resource database. Each of these tasks is described in detail below. Some of the details have changed between Release 4 and Release 5. Release 5 is described below. .\" .SS "Determining Which Display to Open" \f(CWXtAppInitialize()\fP calls \f(CWXtOpenDisplay()\fP with \f(CWNULL\fP for its \f(CIdisplay_name\fP argument. \f(CWXtOpenDisplay()\fP determines which display to open by first checking the command line (note that the command line has not been parsed at this point) for a \fI\-display\fP command line option, and if that is not found, using the value of the DISPLAY environment variable (on POSIX systems). The name is used in a call to \f(CWXOpenDisplay()\fP. .\" .SS "Determining the Application Name" .\"------------------------------------------------------------ \f(CWXtOpenDisplay()\fP also determines the name of the application. It checks for the name in the following four locations and uses the first one it finds: .IP \(bu 3n the value of the \fI\-name\fP command line option. .IP \(bu 3n the value of its \f(CIapplication_name\fP argument. Note that \f(CWXtAppInitialize()\fP always passes \f(CWNULL\fP for this value. .IP \(bu 3n the value of the RESOURCE_NAME environment variable. .IP \(bu 3n the first word on the command line, \f(CIargv\f(CW[0]\fR, stripped of any leading directories. .LP If the name is not found in any of these sources, "main" is used. This name is passed to \f(CWXtDisplayInitialize()\fP to be used in building the resource database, and will later be used by \f(CWXtAppCreateShell()\fP to name the application's toplevel shell widget. .\" .SS "Establishing the Application's Locale" .\"------------------------------------------------------------ \f(CWXtDisplayInitialize()\fP determines an application's "language string" by searching for the \fI\-xnlLanguage\fP command line option, an \fI\-xrm\fP command line option that sets the \f(CWxnlLanguage\fP resource, or a value for the \f(CWxnlLanguage\fP option in the user's personal resource database (i.e., the resources set on the display with \fIxrdb\fP, or the resources in the \fI.Xdefaults\fP file.) .LP In Release 5, if a language procedure has been registered (see \f(CWXtSetLanguageProc()\fP) then the language string is passed to this language procedure. The language procedure localizes the application, usually by calling \f(CWsetlocale()\fP, and returns a string which becomes the new value of the application's language string. If a language procedure has not been set, and in Release 4, the LANG environment variable is used for the language string if no command line argument or resource value is found. .LP In either Release 4 and Release 5, the language string is associated with the display and used in future calls to \f(CWXtResolvePathname()\fP so that file customized for a particular language can be found. See \f(CWXtDisplayInitialize()\fP and \f(CWXtSetLanguageProc()\fP for more detail on this process. .\" .SS "Parsing the Command Line" .\"------------------------------------------------------------ \f(CWXtDisplayInitialize()\fP parses the application command line by merging \f(CIoptions\fP into the standard Xt command line options table and calling \f(CWXrmParseCommand()\fP. Each element in \f(CIoptions\fP and the Xt options table is a \f(CWXrmOptionDescRec\fP structure (shown in the "Structures" section below) which describes how to parse a single command line argument. The fields of this structure are as follows: .IP \f(CWoption\fP 5 The string to be searched for on the command line. As with standard command-line options, Xt will automatically accept any unique abbreviation of the option specified here. For example, the option \fI\-pixmapWidthInPixels\fP will be recognized if typed on the command line as \fI\-pixmapW\fP. However, if you wanted the option \fI\-pw\fP to set the same resource, then you would need another entry, since \fIpw\fP is not the leading string of \f(CWpixmapWidthInPixels\fP. .IP \f(CWspecifier\fP 5 The resource specification. This string must identify a widget resource or an application resource, but not provide a value. Since it has the same form as allowed in the resource databases, it may apply to a single widget or to many widgets. If it applies to no widgets, no error message will be issued. .IP \f(CWargKind\fP 5 The argument style. This field is of type \f(CWXrmOptionKind\fP which describes how the option is to be interpreted. These constants are described below. .IP \f(CWvalue\fP 5 If \f(CWargKind\fP is \f(CWXrmOptionNoArg\fP, this field specifies the resource value (a string) to be inserted into the database. If \f(CWargKind\fP is \f(CWXrmOptionSkipNArgs\fP, this field specifies the number of arguments to skip (you'll need to use a cast to set this field to an integer). For other values of \f(CWargKind\fP, this field is not used. .LP .Nd 10 The possible values for \f(CWXrmOptionKind\fP and their meanings are as follows: .IP \f(CWXrmoptionNoArg\fP 5 Take the value in the \f(CWvalue\fP field of the options table. For example, this is used for Boolean fields, where the option might be \fI\-debug\fP and the default value \f(CWFalse\fP. .IP \f(CWXrmoptionIsArg\fP 5 The flag itself is the value without any additional information. For example, if the option were \fI\-on\fP, the value would be "on." This constant is infrequently used, because the desired value such as "on" is usually not descriptive enough when used as an option (\fI\-on\fP). .IP \f(CWXrmoptionStickyArg\fP 5 The value is the characters immediately following the option with no white space intervening. This is the style of arguments for some POSIX utilities such as \fIuucico\fR where \fI\-sventure\fR means to call system \fIventure\fR. .IP \f(CWXrmoptionSepArg\fP 5 The next item after the white space after this flag is the value. For example, \fI\-fg blue\fR would indicate that \fIblue\fP is the value for the resource specified by \fI\-fg\fR. .IP \f(CWXrmoptionResArg\fP 5 The resource name and its value are the next argument in \f(CIargv\fP after the white space after this flag. For example, the flag might be .in +5n .sp .2 \f(CW-res basecalc*background:white\fR; .sp .2 .in -5n then the resource name/value pair would be used as is. This form is rarely used because it is equivalent to \fI\-xrm\fP, and because the C shell requires that special characters such as * be quoted. .IP \f(CWXrmoptionSkipArg\fP 5 Ignore this option and the next argument in \f(CIargv\fP. .IP \f(CWXrmoptionSkipNArgs\fP 5 Ignore this option and the next \f(CWXrmOptionDescRec.value\fP options .IP \f(CWXrmoptionSkipLine\fP 5 Ignore this option and the rest of \f(CIargv\fP. .LP The standard command line options parsed by \f(CWXtDisplayInitialize()\fP are shown in the table below. .sp 1 .in 0 .KS .TS H tab(@),linesize(2); l l l l lp7fI lp6fCW lp7 lp7. Option@Resource@Value@Sets .sp 2p .sp 2p .Th \-background@*background@Next argument@Background color. \-bd@*borderColor@Next argument@Border color. \-bg@*background@Next argument@Background color. \-bordercolor@*borderColor@Next argument@Color of border. \-borderwidth@.borderWidth@Next argument@Width of border in pixels. \-bw@.borderWidth@Next argument@Width of border in pixels. \-display@.display@Next argument@Server to use. \-fg@*foreground@Next argument@Foreground color. \-fn@*font@Next argument@Font name. \-font@*font@Next argument@Font name. \-foreground@*foreground@Next argument@Foreground color. \-geometry@.geometry@Next argument@Size and position. \-iconic@.iconic@\(odon\(cd@Start as an icon. \-name@.name@Next argument@Name of application. \-reverse@*reverseVideo@\(odon\(cd@Reverse video. \-rv@*reverseVideo@\(odon\(cd@Reverse video. +rv@*reverseVideo@\(odoff\(cd@No reverse video. \-selectionTimeout@.selectionTimeout@Null@Selection timeout. \-synchronous@.synchronous@\(odon\(cd@Synchronous debug mode. +synchronous@.synchronous@\(odoff\(cd@Synchronous debug mode. \-title@.title@Next argument@Title of application. \-xnlLanguage@.xnlLanguage@Next argument@Language. \-xrm@\s+1\fRValue of argument\fP\s-1@Next argument@Depends on argument. .sp 5p .TE .KE .in .sp 1 .\" .SS "Building the Resource Database" .\"------------------------------------------------------------ \f(CWXtDisplayInitialize()\fP builds the application's resource database by merging in resources from a number of sources. The merges are all done to augment rather than override, so if a resource from one of these sources conflicts with a resource in the database, the conflicting value is ignored. The sources are: .IP \(bu 3n The application command line, parsed as described above. .IP \(bu 3n The file named by the XENVIRONMENT environment variable, or, if that does not exist, the file \fI.Xdefaults-\fP in the user's home directory, where \fI\fP is the name of the machine on which the application is running. .IP \(bu 3n The per-screen resources, stored in the SCREEN_RESOURCES property on the root window of the screen, and returned by the function \f(CWXScreenResourceString()\fP .IP \(bu 3n The per-display resources stored in the RESOURCE_MANAGER property on the root window of the default screen of the display, and obtained with \f(CWXResourceManagerString()\fP. These resources are set by the user with \fIxrdb\fP. If no RESOURCE_MANAGER property exists, the contents of the \fI.Xdefaults\fP file in the user's home directory is used instead. .IP \(bu 3n The user's application-specific resource file, which is found with \f(CWXtResolvePathname()\fP and the path specified in the XUSERFILESEARCHPATH environment variable. If this environment variable is not defined, an implementation-defined default path is used. This default path will be relative to the directory specified in the XAPPLRESDIR environment variable, if it exists, or the user's home directory otherwise. .IP \(bu 3n The application class-specific resource file (the "app-defaults" file), which is found with \f(CWXtResolvePathname()\fP. .LP For more details on the precise algorithm used by the Intrinsics to build the database, see \f(CWXtDisplayInitialize()\fP. .\" .SS "Determining the Screen" .\"------------------------------------------------------------ In Release 5, \f(CWXtAppCreateShell()\fP checks its \f(CIargs\fP argument for the \f(CWXtNscreen\fP resource. If that is not found, it looks for the resource in the database of the default screen of the display. If no screen is found, the default screen of the display is used. If a value for the screen resource is found, the shell widget is created on the specified screen, and the database for that screen of the display is obtained with \f(CWXtScreenDatabase()\fP and used for all the remaining resources of the widget. Note that this database will have to be built using the steps described above. .LP In Release 4, only the default screen of a display has a resource database, and widget resources come from that database regardless of the which screen the shell widget is created on. .\" .SH "Structures" .\"------------------------------------------------------------ An \f(CWXrmOptionDescList\fP describes how to parse command line resources. Prior to Release 5, the \f(CWvalue\fP field of the \f(CWXrmOptionDescRec\fP structure was of type \f(CWcaddr_t\fP. It was changed in Release 5 for portability reasons. .Ps .ps 8 typedef enum { XrmoptionNoArg, /* Value is specified in OptionDescRec.value */ XrmoptionIsArg, /* Value is the option string itself */ XrmoptionStickyArg, /* Value is characters immediately following option */ XrmoptionSepArg, /* Value is next argument in argv */ XrmoptionResArg, /* Resource and value in next argument in argv */ XrmoptionSkipArg, /* Ignore this option and the next argument in argv */ XrmoptionSkipLine, /* Ignore this option and the rest of argv */ XrmoptionSkipNArgs /* Ignore this option and the next OptionDescRes.value arguments in argv */ } XrmOptionKind; typedef struct { char *option; /* Option abbreviation in argv */ char *specifier; /* Resource specifier */ XrmOptionKind argKind; /* Which style of option it is */ XPointer value; /* Value to provide if XrmoptionNoArg */ } XrmOptionDescRec, *XrmOptionDescList; .Pe .ps 10 An \f(CWArgList\fP is an array of resource name/resource value pairs: .Ps typedef struct { String name; XtArgVal value; } Arg, *ArgList; .Pe .\" .SH "See Also" .na \s-1\fIXtAppCreateShell\fR\s+1\*(s1, \s-1\fIXtAppSetFallbackResources\fR\s+1\*(s1, \s-1\fIXtCreateApplicationContext\fR\s+1\*(s1, \s-1\fIXtDisplayInitialize\fR\s+1\*(s1, \s-1\fIXtOpenDisplay\fR\s+1\*(s1, \s-1\fIXtResolvePathname\fR\s+1\*(s1, \s-1\fIXtScreenDatabase\fR\s+1\*(s1, \s-1\fIXtSetLanguageProc\fR\s+1\*(s1, \s-1\fIXtToolkitInitialize\fR\s+1\*(s1, \s-1\fIXtVaAppInitialize\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppMainLoop" "Xt \- Event Handling" .SH "Name" .Na XtAppMainLoop \- continuously process events. .XX "process input, XtAppMainLoop" .XX "main loop, XtAppMainLoop" .XX "XtAppMainLoop" .Nz .SH "Synopsis" .Sy void XtAppMainLoop(\f(CIapp_context\fP) .As XtAppContext \f(CIapp_context\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context that identifies the application. .SS "Returns" \f(CWXtAppMainLoop()\fP enters an infinite loop and never returns. .SH "Description" \f(CWXtAppMainLoop()\fP enters an infinite loop which calls \f(CWXtAppNextEvent()\fP to wait for an events on all displays in \f(CIapp_context\fP and \f(CWXtDispatchEvent()\fP to dispatch that event to the appropriate code. .SH "Usage" Most applications will call \f(CWXtAppNextEvent()\fP as the last line of their \f(CWmain()\fP procedure. Some applications may provide their own versions of this loop, however. A custom event loop might test an application-dependent global flag or other termination condition before looping back and calling \f(CWXtAppNextEvent()\fR. If the number of top-level widgets drops to zero, the application may be able to exit safely, for example. .LP Applications that use multiple application contexts or that use internal event loops will have to build their own event loop. .SH "Background" \f(CWXtAppNextEvent()\fP looks for X events in the input queue, and also handles timer events (see \f(CWXtAppAddTimeOut()\fP) and events from alternate input sources (see \f(CWXtAppAddInput()\fP). If none of these events are pending and a work procedure (see \f(CWXtAppAddWorkProc()\fP) is registered, \f(CWXtAppNextEvent()\fP invokes that work procedure to do background processing, otherwise it blocks waiting for an event. Note that \f(CWXtAppNextEvent()\fP dispatches timer and input events directly, but returns any X events that occur. Within \f(CWXtAppMainLoop()\fP, these X events are always passed to \f(CWXtDispatchEvent()\fP. .LP \f(CWXtDispatchEvent()\fP dispatches an event to the appropriate event handlers (see \f(CWXtAddEventHandler()\fP). Note that the translation manager registers an event handler, and that events that are dispatched to the translation manager will be further dispatched through the translations-to-actions mechanism. .\" .SH "Example" \f(CWXtAppMainLoop()\fP is implemented as follows: .Ps void XtAppMainLoop(app) XtAppContext app; { XEvent event; for (;;) { XtAppNextEvent(app, &event); XtDispatchEvent(&event); } } .Pe .\" .SH "See Also" .na \s-1\fIXtAddEventHandler\fR\s+1\*(s1, \s-1\fIXtAppAddInput\fR\s+1\*(s1, \s-1\fIXtAppAddTimeOut\fR\s+1\*(s1, \s-1\fIXtAppAddWorkProc\fR\s+1\*(s1, \s-1\fIXtAppNextEvent\fR\s+1\*(s1, \s-1\fIXtAppProcessEvent\fR\s+1\*(s1, \s-1\fIXtDispatchEvent\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppNextEvent" "Xt \- Event Handling" .SH "Name" .Na XtAppNextEvent \- dispatch timer and alternate input event and return the next X event. .XX "events, returning next event" .XX "events, XtAppNextEvent" .XX "input: queue; XtAppNextEvent" .XX "XtAppNextEvent" .Nz .SH "Synopsis" .Sy void XtAppNextEvent(\f(CIapp_context\fP, \f(CIevent_return\fP) .As XtAppContext \f(CIapp_context\fP; XEvent *\f(CIevent_return\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1.2i Specifies the application context. .SS "Outputs" .IP \f(CIevent_return\fP 1.2i Returns the dequeued event structure. .\" .SH "Description" If there is an X event pending on any of the Displays in \f(CIapp_context\fP, \f(CWXtAppNextEvent()\fP returns that event in \f(CIevent_return\fP. Otherwise, it flushes the X output buffer of each Display, and if there is a background work procedure registered (see \f(CWXtAppAddWorkProc()\fP), \f(CWXtAppNextEvent()\fP calls it and starts over by checking for pending events. If there are no pending events and no work procedures, \f(CWXtAppNextEvent()\fP blocks while waiting for input on any of the Display connections, activity on any of the alternate input sources registered with \f(CWXtAppAddInput()\fP, or the expiration of any timers registered with \f(CWXtAppAddTimeOut()\fP. .LP If there is activity on an alternate input source or if a timeout interval elapses, \f(CWXtAppNextEvent()\fP calls the callback that was registered with the input source or with the timer. If an X event occurs, \f(CWXtAppNextEvent()\fP removes that event from the queue and returns it in \f(CIevent_return\fP. .\" .SH "Usage" Programs rarely need this much control over the event dispatching mechanism. Most programs use \f(CWXtAppMainLoop()\fR. If you want to process a single X, input, or timer event, consider \f(CWXtAppProcessEvent()\fP. .SH "See Also" .na \s-1\fIXtAppAddInput\fR\s+1\*(s1, \s-1\fIXtAppAddTimeOut\fR\s+1\*(s1, \s-1\fIXtAppAddWorkProc\fR\s+1\*(s1, \s-1\fIXtAppMainLoop\fR\s+1\*(s1, \s-1\fIXtAppPeekEvent\fR\s+1\*(s1, \s-1\fIXtAppPending\fR\s+1\*(s1, \s-1\fIXtAppProcessEvent\fR\s+1\*(s1, \s-1\fIXtDispatchEvent\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppPeekEvent" "Xt \- Event Handling" .SH "Name" .Na XtAppPeekEvent \- return, but do not remove the event at the head of an application's input queue; block if no events are available. .XS "input: queue; examining head" .XS "input: queue; XtAppPeekEvent" .XS "XtAppPeekEvent" .Nz .SH "Synopsis" .Sy Boolean XtAppPeekEvent(\f(CIapp_context\fP, \f(CIevent_return\fP) .As XtAppContext \f(CIapp_context\fP; XEvent *\f(CIevent_return\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .SS "Outputs" .IP \f(CIevent_return\fP 1i Returns the event from the head of the queue, if that event is an X event. .SS "Returns" \f(CWTrue\fP if the event at the head of the queue is an X event; \f(CWFalse\fP if it is a timer event or an alternate input source event. .\" .SH "Description" If there are X events pending on any of the displays in \f(CWapp_context\fP, \f(CWXtAppPeekEvent()\fP copies the event from the head of the application event queue into \f(CWevent_return\fP (without removing the event from the queue) and returns \f(CWTrue\fP. If there are no events, it flushes the output buffers of each display and checks again. If there are still no pending X events on any of the displays, but there are timer or alternate input events ready, \f(CWXtAppPeekEvent()\fP returns \f(CWFalse\fP. .LP If there are no events of any kind, \f(CWXtAppPeekEvent()\fP blocks until one occurs, and then if it is an X event, copies the event (without removing it from the queue) and returns \f(CWTrue\fP or returns \f(CWFalse\fP otherwise. Note that \f(CWXtAppPeekEvent()\fP never calls background work procedures registered with \f(CWXtAppAddWorkProc()\fP . .\" .SH "Usage" Programs rarely need this much control over the event dispatching mechanism. Most programs use \f(CWXtAppMainLoop()\fR. .LP If you want to get X events \fIand\fP remove them from the input queue, consider \f(CWXtAppNextEvent()\fP. This function also dispatches timer and alternate input events. .LP If you want to check for input events without blocking, use \f(CWXtAppPending()\fP. This function returns a value that indicates which types of events are pending for an application context, or 0 if no events are pending. .\" .SH "See Also" .na \s-1\fIXtAppMainLoop\fR\s+1\*(s1, \s-1\fIXtAppNextEvent\fR\s+1\*(s1, \s-1\fIXtAppPending\fR\s+1\*(s1. .ad .XE "input: queue; examining head" .XE "input: queue; XtAppPeekEvent" .XE "XtAppPeekEvent" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppPending" "Xt \- Event Handling" .SH "Name" .Na XtAppPending \- determine whether any events are in an application's input queue. .XX "events, XtAppPending" .XX "input: queue; XtAppPending" .XX "input: queue; determining events" .XX "XtAppPending" .Nz .SH "Synopsis" .Sy XtInputMask XtAppPending(\f(CIapp_context\fP) .As XtAppContext \f(CIapp_context\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .SS "Returns" An \f(CWXtInputMask\fP which indicates what kind of events, if any, are pending on \f(CIapp_context\fP. .\" .SH "Description" \f(CWXtAppPending()\fR returns a nonzero value if there are pending events from the X server, timer, or other input sources. .LP The return value is a bit mask that is the OR of \f(CWXtIMXEvent\fR (an X event), \f(CWXtIMTimer\fR (a timer event\-see \f(CWXtAppAddTimeOut()\fP), and \f(CWXtIMAlternateInput\fR (an alternate input event\-see \f(CWXtAppAddInput()\fP). As a convenience, the symbolic name \f(CWXtIMAll\fP is defined as the bitwise inclusive OR of all event types. If no events are pending, \f(CWXtAppPending()\fR flushes the output buffers of each display in the application context and returns zero. This call is the Intrinsics equivalent to the Xlib call \f(CWXPending()\fP. .LP \f(CWXtAppPending()\fP never blocks. .\" .SH "Usage" Programs rarely need this much control over the event dispatching mechanism. Most programs use \f(CWXtAppMainLoop()\fP. .\" .SH "Structures" The \f(CWXtInputMask\fP type and its possible values are defined as follows: .Ps typedef unsigned long XtInputMask; #define XtIMXEvent 1 #define XtIMTimer 2 #define XtIMAlternateInput 4 #define XtIMAll (XtIMXEvent XtIMTimer XtIMAlternateInput) .Pe .\" .SH "See Also" .na \s-1\fIXtAppAddInput\fR\s+1\*(s1, \s-1\fIXtAppAddTimeOut\fR\s+1\*(s1, \s-1\fIXtAppMainLoop\fR\s+1\*(s1, \s-1\fIXtAppNextEvent\fR\s+1\*(s1, \s-1\fIXtAppPeekEvent\fR\s+1\*(s1, \s-1\fIXtAppProcessEvent\fR\s+1\*(s1, \s-1\fIXtDispatchEvent\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppProcessEvent" "Xt \- Event Handling" .SH "Name" .Na XtAppProcessEvent \- get and process one input event of a specified type. .XX "events: event processing" .XX "events: event processing; XtAppProcessEvent" .XX "XtAppProcessEvent" .Nz .SH "Synopsis" .Sy void XtAppProcessEvent(\f(CIapp_context\fP, \f(CImask\fP) .As XtAppContext \f(CIapp_context\fP; XtInputMask \f(CImask\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context for which to process events. .IP \f(CImask\fP 1i Specifies what types of events to process. .\" .SH "Description" \f(CWXtAppProcessEvent()\fP processes one X event, alternate input source event or timer event in \f(CWapp_context\fP. The \f(CImask\fP argument specifies which types of events are to be processed; it is the bitwise inclusive OR (\^\fB \fP\^) of any of the values \f(CWXtIMXEvent\fP, \f(CWXtIMTimer\fP, or \f(CWXtIMAlternateInput\fP, or the value \f(CWXtIMAll\fP which specifies all three event types. .LP If there is no event or input of the appropriate type to process, if there is a background work procedure registered (see \f(CWXtAppAddWorkProc()\fP) \f(CWXtAppProcessEvent()\fP calls that procedure and checks again for input from all specified sources. If there are no pending events and no work procedures registered, \f(CWXtAppProcessEvent()\fP blocks until an event of one of the specified types occurs. .LP If X events are specified in \f(CImask\fP, and no events are immediately available, \f(CWXtAppProcessEvent()\fP flushes the output buffer of each of the Displays in \f(CWapp_context\fP. If there is more than one of the requested types of input available, it is undefined which will be processed. .LP \f(CWXtAppProcessEvent()\fP handles timer and alternate input events by calling the callback procedures registered for those events (see \f(CWXtAppAddTimeOut()\fP and \f(CWXtAppAddInput()\fP). It handles X events by passing them to \f(CWXtDispatchEvent()\fP. \f(CWXtDispatchEvent()\fP handles an event by passing it to the appropriate event handlers (see \f(CWXtAddEventHandler()\fP) or to the Translation Manager (which is itself an event handler). .\" .SH "Usage" Programs rarely need this much control over the event dispatching mechanism. Most programs use \f(CWXtAppMainLoop()\fR. .\" .SH "Structures" The \f(CWXtInputMask\fP type and its possible values are defined as follows: .Ps typedef unsigned long XtInputMask; #define XtIMXEvent 1 #define XtIMTimer 2 #define XtIMAlternateInput 4 #define XtIMAll (XtIMXEvent XtIMTimer XtIMAlternateInput) .Pe .\" .SH "See Also" .na \s-1\fIXtAppAddInput\fR\s+1\*(s1, \s-1\fIXtAppAddTimeOut\fR\s+1\*(s1, \s-1\fIXtAppAddWorkProc\fR\s+1\*(s1, \s-1\fIXtAppMainLoop\fR\s+1\*(s1, \s-1\fIXtAppNextEvent\fR\s+1\*(s1, \s-1\fIXtAppPeekEvent\fR\s+1\*(s1, \s-1\fIXtAppPending\fR\s+1\*(s1, \s-1\fIXtDispatchEvent\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppReleaseCacheRefs" "Xt \- Resource Management" .SH "Name" .XX "XtAppReleaseCacheRefs" .Na XtAppReleaseCacheRefs \- decrement the reference counts for cached resources obtained from \f(CWXtCallConverter()\fR. .Nz .SH "Synopsis" .Sy void XtAppReleaseCacheRefs(\f(CIapp\fP, \f(CIrefs\fP) .As XtAppContext \f(CIapp\fP; XtCacheRef *\f(CIrefs\fP; .Ae .SS "Inputs" .IP \f(CIapp\fP 1i Specifies the application context. .IP \f(CIrefs\fP 1i Specifies a \f(CWNULL\fP-terminated array of cache references to be decremented. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtAppReleaseCacheRefs()\fR decrements the reference count for each \f(CWXtCacheRef\fP in the \f(CWNULL\fP-terminated array \f(CIrefs\fP. If any reference count reaches zero, the destructor registered with \f(CWXtSetTypeConverter()\fP for that resource type, if any, will be called and the resource removed from the conversion cache. .LP An \f(CWXtCacheRef\fP is a handle to a cached resource value. It is obtained in a call to \f(CWXtCallConverter()\fP. .\" .SH "Usage" Applications and widgets should very rarely need to call this function. The Intrinsics provide two predefined callbacks which can be registered with an \f(CWXtCacheRef\fP or an array of \f(CWXtCacheRef\fP on the destroy callback of a widget or object to automatically call \f(CWXtAppReleaseCacheRefs()\fP when the resources are no longer needed. See \f(CWXtCallbackReleaseCacheRef()\fP and \f(CWXtCallbackReleaseCacheRefList()\fP. .LP Additionally, the function \f(CWXtConvertAndStore()\fP which is a higher-level interface to resource converters than \f(CWXtCallConverter()\fP is passed a widget or object and automatically registers \f(CWXtCallbackReleaseCacheRef()\fP on the object's destroy callback if needed. \f(CWXtCreateWidget()\fP may also register such callbacks. .\" .SH "Structures" \f(CWXtCacheRef\fP is an opaque type. .\" .SH "See Also" .na \s-1\fIXtCallbackReleaseCacheRef\fR\s+1\*(s1, \s-1\fIXtCallbackReleaseCacheRefList\fR\s+1\*(s1, \s-1\fIXtCallConverter\fR\s+1\*(s1, \s-1\fIXtConvertAndStore\fR\s+1\*(s1, \s-1\fIXtSetTypeConverter\fR\s+1\*(s1, .br \s-1\fIXtDestructor\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppSetErrorHandler" "Xt \- Error Handling" .SH "Name" .Na XtAppSetErrorHandler \- set the low-level error handler procedure. .XX "errors: fatal error procedure; registering" .XX "registering, fatal error handlers" .XN "error handling: (see also XtAppSetErrorHandler)" .XN "errors: (see also XtAppSetErrorHandler)" .XX "XtAppSetErrorHandler" .Nz .XX "error handling, XtAppSetErrorHandler" .SH "Synopsis" .Sy XtErrorHandler XtAppSetErrorHandler(\f(CIapp_context\fP, \f(CIhandler\fP) .As XtAppContext \f(CIapp_context\fP; XtErrorHandler \f(CIhandler\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CIhandler\fP 1i Specifies the new fatal error procedure, which should not return. .SS "Returns" A pointer to the previously installed low-level error handler. .\" .SH "Description" \f(CWXtAppSetErrorHandler()\fP registers the procedure \f(CIhandler\fP in \f(CIapp_context\fP as the procedure to be invoked by \f(CWXtAppError()\fP. It returns a pointer to the previously installed low-level fatal error handler. \f(CIhandler\fP must terminate the application; if it returns the subsequent behavior of the Intrinsics is undefined. .LP The default low-level error handler provided by the Intrinsics is \f(CW_XtDefaultError()\fR. .XX _XtDefaultError On \s-1POSIX\s+1-based systems, it prints the message to standard error and terminates the application. .\" .SH "Usage" Note that application-context-specific error handling is not implemented on many systems. Most implementations will have just one set of error handlers. If they are set for different application contexts, the one performed last will prevail. .\" .SH "See Also" .na \s-1\fIXtAppError\fR\s+1\*(s1, \s-1\fIXtAppErrorMsg\fR\s+1\*(s1, \s-1\fIXtAppSetErrorMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppWarning\fR\s+1\*(s1, \s-1\fIXtAppWarningMsg\fR\s+1\*(s1, .br \s-1\fIXtErrorHandler\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppSetErrorMsgHandler" "Xt \- Error Handling" .SH "Name" .Na XtAppSetErrorMsgHandler \- set the high-level error handler. .XN "error handling: (see also XtAppSetErrorMsgHandler)" .XN "errors: (see also XtAppSetErrorMsgHandler)" .XX "XtAppSetErrorMsgHandler" .XX "errors: fatal error procedure; registering" .XX "registering, fatal error handlers" .XX "XtAppSetErrorMsgHandler" .Nz .XX "error handling, XtAppSetErrorMsgHandler" .SH "Synopsis" .Sy XtErrorMsgHandler XtAppSetErrorMsgHandler(\f(CIapp_context\fP, \f(CImsg_handler\fP) .As XtAppContext \f(CIapp_context\fP; XtErrorMsgHandler \f(CImsg_handler\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CImsg_handler\fP 1i Specifies the new high-level fatal error message handling procedure, which should not return. .SS "Returns" A pointer to the previously installed high-level error handler. .\" .SH "Description" \f(CWXtAppSetErrorMsgHandler()\fP registers the procedure \f(CImsg_handler\fP in \f(CIapp_context\fP as the procedure to be invoked by \f(CWXtAppErrorMsg()\fP. It returns a pointer to the previously installed high-level error handler. .LP The default high-level fatal error handler provided by the Intrinsics is named \f(CW_XtDefaultErrorMsg()\fR. .XX _XtDefaultErrorMsg It looks up a message in the error resource database (see \f(CWXtAppGetErrorDatabaseText()\fP), substitutes the supplied parameters into the message, and calls \f(CWXtError()\fR. See \f(CWXtErrorMsgHandler\fP(2) for an explanation of how to write a customized high-level error handler. .LP \f(CImsg_handler\fP should generally invoke the low-level error handler to display the message and exit. Fatal error message handlers should not return. If one does, subsequent X Toolkit behavior is undefined. .\" .SH "Usage" Note that application-context-specific error handling is not implemented on many systems. Most implementations will have just one set of error handlers. If they are set for different application contexts, the one performed last will prevail. .SH "See Also" .na \s-1\fIXtAppError\fR\s+1\*(s1, \s-1\fIXtAppErrorMsg\fR\s+1\*(s1, \s-1\fIXtAppGetErrorDatabaseText\fR\s+1\*(s1, \s-1\fIXtAppSetErrorHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppWarning\fR\s+1\*(s1, \s-1\fIXtAppWarningMsg\fR\s+1\*(s1, .br \s-1\fIXtErrorHandler\fR\s+1\*(s2, \s-1\fIXtErrorMsgHandler\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtAppSetErr 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtAppSetErrorHandler@XtAppSetErA .sp .5 XtAppSetErrorMsgHandler@XtAppSetErB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppSetFallbackResources" "Xt \- Resource Management" .SH "Name" .XX "XtAppSetFallbackResources" .Na XtAppSetFallbackResources \- specify a default set of resource values. .Nz .SH "Synopsis" .Sy void XtAppSetFallbackResources(\f(CIapp_context\fP, \f(CIspecification_list\fP) .As XtAppContext \f(CIapp_context\fP; String *\f(CIspecification_list\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context in which the fallback resources will be used. .IP \f(CIspecification_list\fP 1i Specifies a \f(CWNULL\fR-terminated array of resource specifications to pre-load the database, or \f(CWNULL\fR. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtAppSetFallbackResources()\fR registers \f(CIspecification_list\fP as a default set of resource values that will be used in \f(CIapp_context\fP to initialize the resource database if the application-specific class resource file (i.e., the \f(CIapp-defaults\fP file) cannot be found. .LP \f(CIspecification_list\fP is an array of strings, each string a single resource specification in resource file format. If \f(CWXtDisplayInitialize()\fR is not able to find or read an application-specific class resource file then the resource database for the display will be initialized with the values most recently registered with \f(CWXtAppSetFallbackResources()\fP. .LP \f(CWXtAppSetFallbackResources()\fR is not required to copy \f(CIspecification_list\fR; the caller must ensure that the contents of the list and of the strings addressed by the list remain valid until all displays are initialized, or until \f(CWXtAppSetFallbackResources()\fR is called again. Passing \f(CWNULL\fR for \f(CIspecification_list\fR removes any previous fallback resource specification for the application context. .\" .SH "Usage" \f(CWXtAppInitialize()\fP provides an argument for specifying the fallback resources, so few applications need to call \f(CWXtAppSetFallbackResources()\fP directly. Note that \f(CWXtAppSetFallbackResources()\fP should be called before \f(CWXtOpenDisplay()\fP or \f(CWXtDisplayInitialize()\fP if they are to take effect for that display. .LP The intended use of fallback resources is to provide a minimal number of resources that make the application usable (or at least terminate with helpful diagnostic messages) when some problem exists in finding and loading the application-defaults file. .LP .SH "See Also" .na \s-1\fIXtAppInitialize\fR\s+1\*(s1, \s-1\fIXtDisplayInitialize\fR\s+1\*(s1, \s-1\fIXtOpenDisplay\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppSetSelectionTimeout" "Xt \- Selections" .SH "Name" .Na XtAppSetSelectionTimeout \- set the Intrinsics selection timeout value. .XN "selections: timeout; (see also timeouts)" .XX "timeouts: selection timeout value" .XX "timeouts, XtAppSetSelectionTimeout" .XX "XtAppSetSelectionTimeout" .XX "Intrinsics, selection timeout" .XX "XtAppSetSelectionTimeout" .Nz .SH "Synopsis" .Sy void XtAppSetSelectionTimeout(\f(CIapp_context\fP, \f(CItimeout\fP) .As XtAppContext \f(CIapp_context\fP; unsigned long \f(CItimeout\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CItimeout\fP 1i Specifies the selection timeout in milliseconds. .SH "Description" \f(CWXtAppSetSelectionTimeout()\fP sets the Intrinsics selection timeout value for the specified application context. The selection timeout is the time within which two communicating applications must respond to one another. The initial timeout value is set by the \f(CWselectionTimeout\fP application resource, which has a default value of 5000 milliseconds (5 seconds). .SH "Usage" The current timeout value can be retrieved by a call to \f(CWXtAppGetSelectionTimeout()\fP. You should rarely need to query or set this value. In particular, an application generally should not change this value except under the explicit request of the user. .\" .SH "See Also" .na \s-1\fIXtAppGetSelectionTimeout\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppSetTypeConverter" "Xt \- Resource Management" .SH "Name" .XX "XtAppSetTypeConverter" .Na XtAppSetTypeConverter \- register a "new-style" type converter in a single application context. .Nz .SH "Synopsis" .Sy void XtAppSetTypeConverter(\f(CIapp_context\fP, \f(CIfrom_type\fP, \f(CIto_type\fP, \f(CIconverter\fP,\p \f(CIconvert_args\fP, \f(CInum_args\fP, \f(CIcache_type\fP, \f(CIdestructor\fP) .As XtAppContext \f(CIapp_context\fP; String \f(CIfrom_type\fP; String \f(CIto_type\fP; XtTypeConverter \f(CIconverter\fP; XtConvertArgList \f(CIconvert_args\fP; Cardinal \f(CInum_args\fP; XtCacheType \f(CIcache_type\fP; XtDestructor \f(CIdestructor\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CIfrom_type\fP 1i Specifies the source type. .IP \f(CIto_type\fP 1i Specifies the destination type. .IP \f(CIconverter\fP 1i Specifies the resource type converter procedure. .IP \f(CIconvert_args\fP 1i Specifies additional conversion arguments, or \f(CWNULL\fR. .IP \f(CInum_args\fP 1i Specifies the count of additional conversion arguments, or zero. .IP \f(CIcache_type\fP 1i Specifies whether or not resources produced by this converter are sharable or display-specific and when they should be freed. .IP \f(CIdestructor\fP 1i Specifies a destroy procedure for resources produced by this conversion, or \f(CWNULL\fR if no additional action is required, to deallocate resources produced by converter. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtAppSetTypeConverter()\fR registers \f(CIconverter\fP in \f(CIapp_context\fP as a procedure to convert data of resource type \f(CIfrom_type\fP to resource type \f(CIto_type\fP. .LP Each element of \f(CIconvert_args\fP is an \f(CWXtConvertArgRec\fP. It is not the argument actually passed to the converter procedure, but specifies how to obtain an \f(CWXrmValue\fP argument which will be passed to the converter. The "Background" section below explains the \f(CWXtConvertArgRec\fP structure in detail. .LP Converted resource values returned by \f(CIconverter\fP will automatically be cached according to the argument \f(CIcache_type\fP, which can be \f(CWXtCacheNone\fP, \f(CWXtCacheAll\fP, or \f(CWXtCacheByDisplay\fP. The meanings of these types are described in the "Background" section below. In addition, the qualifier .ne 10 \f(CWXtCacheRefCount\fP can be ORed with any of these values and specifies that references to cached values produced by this converter should be counted, and if the count ever drops to zero, the value should be removed from the cache, and the procedure \f(CIdestructor\fP should be called to free any memory or resources associated with that value. .LP If the same \f(CIfrom_type\fR and \f(CIto_type\fR are specified in multiple calls to \f(CWXtAppSetTypeConverter()\fP, the most recent overrides the previous ones. .LP See \f(CWXtTypeConverter\fP(2) for an explanation of how to write a "new-style" converter. See \f(CWXtDestuctor\fP(2) for an explanation of how to write a destructor procedure. See \f(CWXtCallConverter()\fP for an explanation of how reference counting of cached values is performed. .\" .SH "Usage" \f(CWXtAppSetTypeConverter()\fP registers a resource converter of a type added to the Intrinsics in Release 4. If you need to register an "old-style" converter which was written before Release 4, use \f(CWXtAppAddConverter()\fP. .LP \f(CWXtSetTypeConverter()\fP is identical to \f(CWXtAppSetTypeConverter()\fP except that it registers the converter in all application contexts, including application contexts that are created in the future. .LP If you write a widget that has a resource which is of some enumerated type, you should write a converter routine which will convert between the symbolic names of each value and the values themselves. This converter should then be registered in your widget's \f(CWclass_initialize()\fP method. .LP If you are writing a programming library or an application that defines non-standard types, it may be useful to provide string converters for those types. This allows resources of that type to be specified from a resource file. An application that supported user-configurable popup menus, for example, might include a String-to-Menu converter. .LP Some converters need additional arguments, such as a screen or colormap in order to correctly perform the conversion. These converters are registered with an \f(CWXtConvertArgList\fP. Generally the author of the converter will also define a static array of \f(CWXtConvertArgRec\fP to be registered with the converter. There are also two \f(CWXtConvertArgList\fPs predefined by the Intrinsics: \f(CWscreenConvertArg\fR passes the widget's \f(CWscreen\fP field to the converter in \f(CWargs[0]\fR, and \f(CWcolorConvertArgs\fR passes the widget's \f(CWscreen\fP field to the converter in \f(CWargs[0]\fR and the widget's \f(CWcolormap\fP field in \f(CWargs[1]\fR. .LP The Intrinsics define a number of standard converters which do not need to be registered. See \f(CWXtConvertAndStore()\fP for a list of these predefined converters. There are also a number of other useful converters defined in the Xmu library which do need to be registered explicitly. See \f(CWXmuCvtStringToMisc\fP(6). .\" .SH "Example" You can register the XmuCvtStringToColorCursor from the Xmu library with the following: .Ps static XtConvertArgRec colorCursorConvertArgs[] = { {XtWidgetBaseOffset, (XtPointer) XtOffsetOf(WidgetRec, core.screen), sizeof(Screen *)}, {XtResourceString, (XtPointer) XtNpointerColor,sizeof(Pixel)}, {XtResourceString, (XtPointer) XtNpointerColorBackground, sizeof(Pixel)}, {XtWidgetBaseOffset, (XtPointer) XtOffsetOf(WidgetRec,core.colormap), sizeof(Colormap)} }; XtSetTypeConverter(XtRString, XtRColorCursor, XmuCvtStringToColorCursor, colorCursorConvertArgs, XtNumber(colorCursorConvertArgs), XtCacheByDisplay, NULL); .Pe .\" .SH "Background" .\" .SS "Specifying Arguments to a Converter" .\"------------------------------------------------------------ For the few type converters that need additional arguments, the Intrinsics conversion mechanism provides a method of specifying how these arguments should be computed. Before a converter is called, each element of the \f(CWXtConvertArgList\fP is interpreted to determine the sizes and values of the arguments. These computed arguments are passed to the converter as an array of \f(CWXrmValue\fP. The enumerated type \f(CWXtAddressMode\fP and the structure \f(CWXtConvertArgRec\fP specify how each argument is derived. .LP .Ps .TA .5i 2.5i .ta .5i 2.5i typedef enum { /* address mode parameter representation */ XtAddress, /* address */ XtBaseOffset, /* offset */ XtImmediate, /* constant */ XtResourceString, /* resource name string */ XtResourceQuark, /* resource name quark */ XtWidgetBaseOffset, /* offset */ XtProcedureArg /* procedure to call */ } XtAddressMode; typedef struct { XtAddressMode address_mode; XtPointer address_id; Cardinal size; } XtConvertArgRec, *XtConvertArgList; .Pe .LP .XX XtConvertArgRec The \f(CWsize\fP field of an \f(CWXtConvertArgRec\fP specifies the length of the data in bytes. The \f(CWaddress_mode\fP field specifies how the \f(CWaddress_id\fP field should be interpreted. The possible values of \f(CWXtAddressMode\fP have the following meanings: .XX XtAddressMode .IP \f(CWXtAddress\fP .XX "XtAddress" causes \f(CWaddress_id\fP to be interpreted as the address of the data. .IP \f(CWXtBaseOffset\fP .XX "XtBaseOffset" causes \f(CWaddress_id\fP to be interpreted as the offset from the widget base. .IP \f(CWXtImmediate\fP .XX "XtImmediate" causes \f(CWaddress_id\fP to be interpreted as a constant. .Nd 5 .IP \f(CWXtResourceString\fP .XX "XtResourceString" causes \f(CWaddress_id\fP to be interpreted as the name of a resource that is to be converted into an offset from the widget base. .IP \f(CWXtResourceQuark\fP .XX "XtResourceQuark" causes \f(CWaddress_id\fP to be interpreted as the result of an \f(CWXrmStringToQuark()\fP conversion on the name of a resource, which is to be converted into an offset from the widget base. .IP \f(CWXtWidgetBaseOffset\fP .XX "XtWidgetBaseOffset" is similar to \f(CWXtBaseOffset\fP except that it searches for the closest windowed ancestor if the object is not of a subclass of Core. .IP \f(CWXtProcedureArg\fP .XX "XtProcedureArg" specifies that \f(CWaddress_id\fP is a pointer to a procedure of type \f(CWXtConvertArgProc\fP to be invoked to return the conversion argument. See \f(CWXtConvertArgProc\fP(2) for an explanation of how to write a procedure of this type. .XX "XtConvertArgProc, used in an XtConvertArgRec" .\" .SS "Caching Converted Values" .\"------------------------------------------------------------ The possible values for the \f(CIcache_type\fP argument are as follows: .IP \f(CWXtCacheNone\fP .XX "XtCacheNone" Specifies that the results of a previous conversion may not be reused to satisfy any other resource requests; the specified converter will be called each time the converted value is required. .IP \f(CWXtCacheAll\fP .XX "XtCacheAll" Specifies that the results of a previous conversion should be reused for any resource request that depends upon the same source value and conversion arguments. .IP \f(CWXtCacheByDisplay\fP .XX "XtCacheByDisplay" Specifies that the results of a previous conversion should be used as for \f(CWXtCacheAll\fP but that the value should be removed from the cache and the destructor, if any, should be called, when \f(CWXtCloseDisplay()\fP is called for the display connection associated with the converted value. .LP The qualifier \f(CWXtCacheRefCount\fP .XX "XtCacheRefCount" may be ORed with any of the above values. If \f(CWXtCacheRefCount\fP is specified, calls to \f(CWXtCreateWidget()\fP, \f(CWXtCreateManagedWidget()\fP, \f(CWXtGetApplicationResources()\fP and \f(CWXtGetSubresources()\fP that use the converted value will be counted. When a widget using the converted value is destroyed, the count is decremented, and if the count reaches zero, the destructor procedure \f(CIdestructor\fP will be called and the converted value will be removed from the conversion cache. .\" .SH "Structures" The \f(CWXtConvertArgRec\fP structure and the related \f(CWXtAddressMode\fP type are shown in the "Background" section above. The \f(CWXtCacheType\fP type and its legal values are defined as follows: .Nd 5 .Ps typedef int XtCacheType; #define XtCacheNone 0x001 #define XtCacheAll 0x002 #define XtCacheByDisplay 0x003 #define XtCacheRefCount 0x100 .Pe .\" .SH "See Also" .na \s-1\fIXtAppReleaseCacheRefs\fR\s+1\*(s1, \s-1\fIXtCallbackReleaseCacheRef\fR\s+1\*(s1, \s-1\fIXtCallbackReleaseCacheRefList\fR\s+1\*(s1, \s-1\fIXtCallConverter\fR\s+1\*(s1, \s-1\fIXtConvertAndStore\fR\s+1\*(s1, \s-1\fIXtSetTypeConverter\fR\s+1\*(s1, .br \s-1\fIXtConvertArgProc\fP\s+1\*(s2, \s-1\fIXtDestructor\fR\s+1\*(s2, \s-1\fIXtTypeConverter\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppSetWarningHandler" "Xt \- Error Handling" .SH "Name" .Na XtAppSetWarningHandler \- set the low-level warning handler. .XN "error handling: (see also XtAppSetWarningHandler" .XX "errors: nonfatal error procedure; registering" .XX "registering, nonfatal error handlers" .XX "XtAppSetWarningHandler" .Nz .SH "Synopsis" .Sy XtErrorHandler XtAppSetWarningHandler(\f(CIapp_context\fP, \f(CIhandler\fP) .As XtAppContext \f(CIapp_context\fP; XtErrorHandler \f(CIhandler\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CIhandler\fP 1i Specifies the new nonfatal error procedure. .SS "Returns" A pointer to the previously installed low-level error handler. .\" .SH "Description" \f(CWXtAppSetWarningHandler()\fP registers the procedure \f(CIhandler\fP in \f(CIapp_context\fP as the procedure to be invoked by \f(CWXtAppWarning()\fP. It returns a pointer to the previously installed low-level warning handler. .LP The default low-level warning handler provided by the Intrinsics is \f(CW_XtDefaultWarning()\fR. .XX _XtDefaultWarning On \s-1POSIX\s+1-based systems, it prints the message to standard error and returns to the caller. .\" .SH "Usage" Note that application-context-specific error and warning handling is not implemented on many systems. Most implementations will have just one set of error handlers. If they are set for different application contexts, the one performed last will prevail. .\" .SH "See Also" .na \s-1\fIXtAppError\fR\s+1\*(s1, \s-1\fIXtAppErrorMsg\fR\s+1\*(s1, \s-1\fIXtAppSetErrorHandler\fR\s+1\*(s1, \s-1\fIXtAppSetErrorMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppWarning\fR\s+1\*(s1, \s-1\fIXtAppWarningMsg\fR\s+1\*(s1, .br \s-1\fIXtErrorHandler\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppSetWarningMsgHandler" "Xt \- Error Handling" .SH "Name" .hw conditions .Na XtAppSetWarningMsgHandler \- set the high-level warning handler. .XN "errors: (see also XtAppSetWarningMsgHandler)" .XN "error handling: (see also XtAppSetWarningMsgHandler)" .XX "errors: nonfatal error procedure; registering" .XX "nonfatal error, registering method" .XX "registering, nonfatal error handlers" .XX "XtAppSetWarningMsgHandler" .Nz .SH "Synopsis" .Sy XtErrorMsgHandler XtAppSetWarningMsgHandler(\f(CIapp_context\fP, \f(CImsg_handler\fP) .As XtAppContext \f(CIapp_context\fP; XtErrorMsgHandler \f(CImsg_handler\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CImsg_handler\fP 1i Specifies the new high-level warning handler. .SS "Returns" A pointer to the previously installed high-level warning handler. .\" .SH "Description" \f(CWXtAppSetWarningMsgHandler()\fP registers the procedure \f(CImsg_handler\fP in \f(CIapp_context\fP as the procedure to be invoked by \f(CWXtAppWarningMsg()\fP. It returns a pointer to the previously installed high-level warning handler. .LP The default high-level warning handler provided by the Intrinsics is named \f(CW_XtDefaultWarningMsg()\fR. .XX _XtDefaultWarningMsg It looks up a message in the error resource database (see \f(CWXtAppGetErrorDatabaseText()\fP), substitutes the supplied parameters into the message, and calls \f(CWXtWarning()\fR. See \f(CWXtWarningMsgHandler\fP(2) for an explanation of how to write a customized high-level warning handler. .LP \f(CImsg_handler\fP should generally invoke the low-level warning handler to display the message. .\" .SH "Usage" Note that application-context-specific error and warning handling is not implemented on many systems. Most implementations will have just one set of error handlers. If they are set for different application contexts, the one performed last will prevail. .\" .SH "See Also" .na \s-1\fIXtAppError\fR\s+1\*(s1, \s-1\fIXtAppErrorMsg\fR\s+1\*(s1, \s-1\fIXtAppGetErrorDatabaseText\fR\s+1\*(s1, \s-1\fIXtAppSetErrorHandler\fR\s+1\*(s1, \s-1\fIXtAppSetErrorMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningHandler\fR\s+1\*(s1, \s-1\fIXtAppWarning\fR\s+1\*(s1, \s-1\fIXtAppWarningMsg\fR\s+1\*(s1, .br \s-1\fIXtErrorHandler\fR\s+1\*(s2, \s-1\fIXtErrorMsgHandler\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtAppSetWar 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtAppSetWarningHandler@XtAppSetWaA .sp .5 XtAppSetWarningMsgHandler@XtAppSetWaB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppWarning" "Xt \- Error Handling" .SH "Name" .Na XtAppWarning \- call the low-level warning handler. .XN "errors: (see also XtAppWarning)" .XX "errors: nonfatal error procedure; calling" .XN "nonfatal error: (see also errors)" .XX "XtAppWarning" .Nz .SH "Synopsis" .Sy void XtAppWarning(\f(CIapp_context\fP, \f(CImessage\fP) .As XtAppContext \f(CIapp_context\fP; String \f(CImessage\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CImessage\fP 1i Specifies the warning message that is to be reported. .\" .SH "Description" \f(CWXtAppWarning()\fP passes its arguments to the installed low-level warning handler. On \s-1POSIX\s+1 systems, the default handler is \f(CW_XtDefaultWarning()\fP. It prints the message to the stderr stream and returns. .\" .SH "Usage" To report fatal error messages and exit, use \f(CWXtAppError()\fP or \f(CWXtAppErrorMsg()\fP. To change the low-level warning handler, use \f(CWXtAppSetWarningHandler()\fP. .LP \f(CWXtAppWarning()\fP calls the "low-level" warning handler. It is better to use \f(CWXtAppWarningMsg()\fP which calls the "high-level" warning handler. The high-level handler looks up the warning message in a resource database and so allows for customization and internationalization of warning messages. .LP Although the Intrinsics interface allows separate error and warning handlers for each application context, most implementations will support only a single set of handlers. When a new handler is installed, it will be used in all application contexts. .SH "See Also" .na \s-1\fIXtAppError\fR\s+1\*(s1, \s-1\fIXtAppErrorMsg\fR\s+1\*(s1, \s-1\fIXtAppSetErrorHandler\fR\s+1\*(s1, \s-1\fIXtAppSetErrorMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppWarningMsg\fR\s+1\*(s1, .br \s-1\fIXtErrorHandler\fR\s+1\*(s2, \s-1\fIXtErrorMsgHandler\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAppWarningMsg" "Xt \- Error Handling" .SH "Name" .Na XtAppWarningMsg \- call the high-level warning handler. .XS "warning handler, calling high-level" .XN "warning handler: (see also XtAppWarningMsg)" .XS "XtAppWarningMsg" .Nz .SH "Synopsis" .Sy void XtAppWarningMsg(\f(CIapp_context\fP, \f(CIname\fP, \f(CItype\fP, \f(CIclass \fP, \f(CIdefault\fP, \f(CIparams\fP, \f(CInum_params\fP) .As XtAppContext \f(CIapp_context\fP; String \f(CIname\fP; String \f(CItype\fP; String \f(CIclass\fP; String \f(CIdefault\fP; String *\f(CIparams\fP; Cardinal *\f(CInum_params\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CIname\fP 1i Specifies the general kind of error. .IP \f(CItype\fP 1i Specifies the detailed name of the error. .IP \f(CIclass\fP 1i Specifies the resource class. .IP \f(CIdefault\fP 1i Specifies the default message to use if no message is found in the database. .IP \f(CIparams\fP 1i Specifies an array of values to be inserted into the message. .IP \f(CInum_params\fP 1i Specifies the number of elements in \f(CIparams\fP. .\" .SH "Description" \f(CWXtAppWarningMsg()\fP passes all of its arguments except \f(CIapp_context\fP to the installed high-level warning handler. The default high-level warning handler is \f(CW_XtDefaultWarningMsg()\fP. It calls \f(CWXtAppGetErrorDatabaseText()\fP to lookup a message of the specified \f(CIname\fP, \f(CItype\fP, and \f(CIclass\fP in the error database. If no such message is found, \f(CWXtAppGetErrorDatabaseText()\fP returns the specified \f(CIdefault\fP message. In either case, \f(CW_XtDefaultWarningMsg()\fP does a \f(CWprintf\fP-style substitution of \f(CIparams\fP into the message, and passes the resulting text to the low-level warning handler by calling \f(CWXtWarning()\fP. .LP See \f(CWXtAppGetErrorDatabaseText()\fP for details on how messages are looked up in the error database. .\" .SH "Usage" To report fatal error messages and exit, use \f(CWXtAppErrorMsg()\fP. To change the high-level warning handler, use \f(CWXtAppSetWarningMsgHandler()\fP. .LP Note that the \f(CInum_params\fP argument to this function is a \f(CWCardinal *\fP, not a \f(CWCardinal\fP. .LP Although the Intrinsics interface allows separate error and warning handlers for each application context, most implementations will support only a single set of handlers. When a new handler is installed, it will be used in all application contexts. .\" .Nd 4 .SH "Example" The following code is from \f(CWXtDisplayStringConversionWarning()\fP: .Ps String params[2]; Cardinal num_params = 2; params[0] = (String)from; params[1] = (String)toType; XtAppWarningMsg(XtDisplayToApplicationContext(dpy), XtNconversionError, "string", XtCXtToolkitError, "Cannot convert string to type %s", params, &num_params); .Pe .\" .SH "See Also" .na \s-1\fIXtAppError\fR\s+1\*(s1, \s-1\fIXtAppErrorMsg\fR\s+1\*(s1, \s-1\fIXtAppSetErrorHandler\fR\s+1\*(s1, \s-1\fIXtAppSetErrorMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppWarning\fR\s+1\*(s1, .br \s-1\fIXtErrorHandler\fR\s+1\*(s2, \s-1\fIXtErrorMsgHandler\fR\s+1\*(s2. .ad .XE "warning handler, calling high-level" .XE "XtAppWarningMsg" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtAppWarnin 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtAppWarning@XtAppWarniA .sp .5 XtAppWarningMsg@XtAppWarniB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtArgsFunc" "Xt \- Widget Method Prototypes" .SH "Name" .Na XtArgsFunc \- interface definition for the \f(CWset_values_hook()\fP method. .Nz .XX "XtArgsFunc" .SH "Synopsis" .Sy typedef Boolean (*XtArgsFunc)(Widget, ArgList, Cardinal *); .As Widget \f(CIwidget\fP; ArgList \f(CIargs\fP; Cardinal *\f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIwidget\fP 1i Specifies the widget which is having its resources set. .IP \f(CIargs\fP 1i Specifies the argument list passed to \f(CWXtSetValues()\fP. .IP \f(CInum_args\fP 1i Specifies a pointer to the number of elements in \f(CIargs\fP. .SS "Returns" \f(CWTrue\fP if the widget should be drawn; \f(CWFalse\fP otherwise. .\" .SH "Availability" Obsolete in Release 4 and later. .\" .SH "Description" \f(CWXtArgsFunc\fP is the type of the Core \f(CWset_values_hook()\fP method. It is obsolete in Release 4 and later because the \f(CIargs\fP and \f(CInum_args\fP arguments are now passed directly to the \f(CWset_value()\fP method. See \f(CWset_values_hook\fP(4) for more information. .\" .SH "See Also" .na \s-1\fIset_values_hook\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtArgsProc" "Xt \- Widget Method Prototypes" .SH "Name" .hw values .Na XtArgsProc \- interface definition for the \f(CWinitialize_hook()\fR and \f(CWget_values_hook()\fP methods. .Nz .XX "XtArgsProc" .SH "Synopsis" .Sy typedef void (*XtArgsProc)(Widget, ArgList, Cardinal *); .As Widget \f(CIwidget\fP; ArgList \f(CIargs\fP; Cardinal *\f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIwidget\fP 1i Specifies the widget that is being initialized or passed to \f(CWXtGetValues()\fP. .IP \f(CIargs\fP 1i Specifies the argument list that was passed to \f(CWXtCreateWidget()\fP or \f(CWXtGetValues()\fP. .IP \f(CInum_args\fP 1i Specifies a pointer to the number of elements in \f(CIargs\fP. .\" .SH "Description" \f(CWXtArgsProc\fP is the type of the Core \f(CWinitialize_hook()\fP method and the Core and Constraint \f(CWget_values_hook()\fP methods. The \f(CWinitialize_hook()\fP method is obsolete in Release 4 and later because the \f(CIargs\fP and \f(CInum_args\fP arguments are now passed directly to the \f(CWinitialize()\fP method. See the reference pages for these methods in Section 4 for more information. .\" .SH "See Also" .na \s-1\fIget_values_hook\fR\s+1\*(s4, \s-1\fIConstraint get_values_hook\fR\s+1\*(s4, \s-1\fIinitialize_hook\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtAugmentTranslations" "Xt \- Translations and Actions" .SH "Name" .Na XtAugmentTranslations \- nondestructively merge new translations with widget's existing ones. .XS "widgets, merging translations" .XS "translations: merging; widget translations" .XS "translations, XtAugmentTranslations" .XS "XtAugmentTranslations" .Nz .SH "Synopsis" .Sy void XtAugmentTranslations(\f(CIw\fP, \f(CItranslations\fP) .As Widget \f(CIw\fP; XtTranslations \f(CItranslations\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1.2i Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof. .IP \f(CItranslations\fP 1.2i Specifies the compiled translation table to merge in. .SH "Description" \f(CWXtAugmentTranslations()\fR merges a compiled translation table \f(CItranslations\fP into a widget's internal compiled translation table, ignoring any new translations that conflict with existing translations. The table \f(CItranslations\fP is not altered by this process. Any "#replace", "#augment", or "#override" directives in \f(CItranslations\fP are ignored by this function. .\" .SH "Usage" Use \f(CWXtParseTranslationTable()\fP to convert a string representation of a translation table to the \f(CWXtTranslations\fP compiled form. .LP To merge translations into a widget and replace existing translations where there are conflicts, use \f(CWXtOverrideTranslations()\fP. To completely replace a widget's translation table, use \f(CWXtSetValues()\fP to set a compiled translation table on the widget's \f(CWXtNtranslations\fP resource. To remove all of a widget's translations, use \f(CWXtUninstallTranslations()\fP. .LP Translation tables can also be specified in string from a resource file. By default, specifying a value for the \f(CWtranslations\fP resource will completely replace the existing translations. If the string form of the translation table begins with the directives "#augment" or "#override", however, then the specified translations will be merged with the widget's existing translations, and new translations that conflict with existing translations will be ignored or will override the existing translations, respectively. .\" .SH "See Also" .na \s-1\fIXtOverrideTranslations\fR\s+1\*(s1, \s-1\fIXtParseTranslationTable\fR\s+1\*(s1, \s-1\fIXtUninstallTranslations\fR\s+1\*(s1. .ad .XE "widgets, merging translations" .XE "translations: merging; widget translations" .XE "translations, XtAugmentTranslations" .XE "XtAugmentTranslations" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtBuildEventMask" "Xt \- Event Handling" .SH "Name" .Na XtBuildEventMask \- retrieve a widget's event mask. .XS "widgets, retrieving event mask" .XS "events: event masks; XtBuildEventMask" .XS "XtBuildEventMask" .Nz .SH "Synopsis" .Sy EventMask XtBuildEventMask(\f(CIw\fP) .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. Must be of class Core or any subclass thereof. .SS "Returns" An event mask with a bit set for each event type the widget is receiving. .SH "Description" \f(CWXtBuildEventMask()\fR returns a widget's event mask. The mask reflects the events the widget is currently selecting. (If the widget is unrealized, then the mask reflects the events the widget will select when it is realized.) This event mask is the logical OR of all event masks selected by adding event handlers and event translations (including accelerators). It is updated whenever event handlers or translations are installed or removed for the specified widget. .\" .SH "Structures" The \f(CWevent_mask\fP is formed by combining the event mask symbols listed in the table below using the bitwise OR operator (\^\fB \fR\^). Each mask symbol sets a bit in the \f(CWevent_mask\fP. .sp 1 .in 0 .KS .TS linesize(2),tab(@); lp7fCW lp7fCW lp7fCW. .sp 2p NoEventMask@Button1MotionMask@StructureNotifyMask@ KeyPressMask@Button2MotionMask@ResizeRedirectMask@ KeyReleaseMask@Button3MotionMask@SubstructureNotifyMask@ ButtonPressMask@Button4MotionMask@SubstructureRedirectMask@ ButtonReleaseMask@Button5MotionMask@FocusChangeMask@ EnterWindowMask@ButtonMotionMask@PropertyChangeMask@ LeaveWindowMask@KeymapStateMask@ColormapChangeMask@ PointerMotionMask@ExposureMask@OwnerGrabButtonMask@ PointerMotionHintMask@VisibilityChangeMask@ .sp 5p .TE .KE .in .sp 1 .\" .SH "See Also" \s-1\fIXtAddEventHandler\fR\s+1\*(s1, \s-1\fIXtAddRawEventHandler\fR\s+1\*(s1, \s-1\fIXtRealizeWidget\fR\s+1\*(s1. .ad .XE "widgets, retrieving event mask" .XE "events: event masks; XtBuildEventMask" .XE "XtBuildEventMask" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCallAcceptFocus" "Xt \- Keyboard Handling" .SH "Name" .Na XtCallAcceptFocus \- offer the input focus to a child widget. .XX "widgets, accept_focus method" .XX "XtCallAcceptFocus" .Nz .SH "Synopsis" .Sy Boolean XtCallAcceptFocus(\f(CIw\fP, \f(CItime\fP) .As Widget \f(CIw\fP; Time *\f(CItime\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget; must be of class Core or any subclass thereof. .IP \f(CItime\fP 1i Specifies the X time of the event that is causing the accept focus. .SS "Returns" \f(CWTrue\fP if \f(CIw\fP took the input focus; \f(CWFalse\fP if \f(CIw\fP did not take the input focus. .SH "Description" \f(CWXtCallAcceptFocus()\fR calls the specified widget's Core class \f(CWaccept_focus()\fR method, passing it the specified widget and time, and \f(CITrue\fP if the widget took the input focus, or \f(CIFalse\fP otherwise. If the \f(CWaccept_focus()\fR method is \f(CWNULL\fR, \f(CWXtCallAcceptFocus()\fR returns \f(CWFalse\fP. .\" .SH "Usage" Generally, only widgets should call \f(CWXtCallAcceptFocus()\fP, and generally only on their descendants. .LP Note that calling a widget's \f(CWaccept_focus()\fP method does not automatically assign the input focus, and does not mean that the widget will necessarily take the input focus. The \f(CWaccept_focus()\fP method must decide whether or not to take the focus and then take it with \f(CWXSetInputFocus()\fP or \f(CWXtSetKeyboardFocus()\fP. .\" .SH "Background" Widgets that need the input focus can call \f(CWXSetInputFocus()\fP explicitly, pursuant to the restrictions of the \fIInter-Client Communications Convention Manual\fP. To allow outside agents, such as the parent, to cause a widget to take the input focus, every widget exports an \f(CWaccept_focus()\fP method. The widget returns a value indicating whether it actually took the focus or not, so that the parent can give the focus to another widget. Widgets that need to know when they lose the input focus must use the Xlib focus notification mechanism explicitly (typically by specifying translations for \f(CWFocusIn\fP and \f(CWFocusOut\fP events). Widget classes that never want the input focus should set the \f(CWaccept_focus()\fP method to \f(CWNULL\fP. .SH "See Also" .na \s-1\fIXtSetKeyboardFocus\fR\s+1\*(s1, .br \s-1\fIaccept_focus\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCallActionProc" "Xt \- Translations and Actions" .SH "Name" .XX "XtCallActionProc" .Na XtCallActionProc \- explicitly invoke a named action procedure. .Nz .SH "Synopsis" .Sy void XtCallActionProc(\f(CIwidget\fP, \f(CIaction\fP, \f(CIevent\fP, \f(CIparams\fP, \f(CInum_params\fP) .As Widget \f(CIwidget\fP; String \f(CIaction\fP; XEvent *\f(CIevent\fP; String *\f(CIparams\fP; Cardinal \f(CInum_params\fP; .Ae .SS "Inputs" .IP \f(CIwidget\fP 1i Specifies the widget in which the action is to be invoked; must be of class Core or any subclass thereof. .IP \f(CIaction\fP 1i Specifies the name of the action routine. .IP \f(CIevent\fP 1i Specifies the event to pass to the action procedure. .IP \f(CIparams\fP 1i Specifies parameters to pass to the action procedure. .IP \f(CInum_params\fP 1i Specifies the number of elements in the \f(CIparams\fP array. .SH "Description" \f(CWXtCallActionProc()\fP looks up the action procedure named \f(CIaction\fP and invokes it, passing \f(CIwidget\fP, \f(CIevent\fP, \f(CIparams\fP, and \f(CInum_params\fP as arguments. Before calling the named action, \f(CWXtCallActionProc()\fP invokes any action hook procedures that have been registered with \f(CWXtAppAddActionHook()\fP. .LP It is the responsibility of the caller to ensure that the contents of the \f(CIevent\fP, \f(CIparams\fP, and \f(CInum_params\fP arguments are appropriate for the specified action routine and, if necessary, that the specified widget is realized and/or sensitive. If the named action routine cannot be found, \f(CWXtCallActionProc()\fR generates a warning message and returns. .LP When searching for the action procedure, \f(CWXtCallActionProc()\fP looks in the following places: .IP \(bu 3n The widget's class and all superclass action tables, in subclass-to-superclass order. .IP \(bu 3n The parent's class and all superclass action tables, in subclass-to-superclass order, then on up the ancestor tree. .IP \(bu 3n The action tables registered with \f(CWXtAppAddActions()\fP and \f(CWXtAddActions()\fP from the most recently added table to the oldest table. .LP .\" .SH "See Also" .na \s-1\fIXtAppAddActionHook\fR\s+1\*(s1, \s-1\fIXtRemoveActionHook\fR\s+1\*(s1, .br \s-1\fIXtActionHookProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCallCallbackList" "Xt \- Callbacks" .SH "Name" .XX "XtCallCallbackList" .Na XtCallCallbackList \- execute the procedures in a callback list, specifying the callback list by address. .Nz .SH "Synopsis" .Sy void XtCallCallbackList(\f(CIobject\fP, \f(CIcallbacks\fP, \f(CIcall_data\fP) .As Widget \f(CIobject\fP; XtCallbackList \f(CIcallbacks\fP; XtPointer \f(CIcall_data\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object which contains the callback list; may be of class Object or any subclass thereof. .IP \f(CIcallbacks\fP 1i Specifies the callback list to be invoked. .IP \f(CIcall_data\fP 1i Specifies data to pass to each of the callback procedures in the list as their \f(CIcall_data\fP arguments. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtCallCallbackList()\fP calls the procedures on the \f(CIcallbacks\fP callback list. It invokes each procedure with \f(CIobject\fP as the first argument, the data registered with the procedure as the second argument and \f(CIcall_data\fP as the third argument. .LP \f(CIcallbacks\fP must be of type \f(CWXtCallbackList\fP, and must be a widget or object resource of resource type \f(CWXtRCallback\fP. .\" .SH "Usage" \f(CWXtCallCallbackList()\fP should only be called by widgets and objects; applications will never need to call it. .LP \f(CWXtCallCallbacks()\fP calls the procedures on a callback list specified by name. \f(CWXtCallCallbackList()\fP is generally a little faster because it does not have to look up the callback list by name. .LP The \f(CIcall_data\fP argument is untyped value. The caller must be sure to pass correctly initialized data of the type expected by callbacks registered on the specified callback list. This type may be an \f(CWint\fP, or some other type that fits in 32 bits, but is often a pointer to a structure. .LP Widgets maintain \f(CWXtCallbackList\fPs in a compiled internal form, for this reason, you cannot call \f(CWXtCallCallbackList()\fP on a statically initialized array of \f(CWXtCallbackRec\fP or any other \f(CWXtCallbackList\fP that is not a widget or object resource. .SH "See Also" .na \s-1\fIXtAddCallback\fR\s+1\*(s1, \s-1\fIXtCallCallbacks\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCallCallbacks" "Xt \- Callbacks" .SH "Name" .Na XtCallCallbacks \- execute the procedures on a widget's named callback list. .XX "callbacks: callback list; executive methods" .XN "widgets: callback list (see callbacks)" .XX "callbacks: callback list; XtCallCallbacks" .XX "XtCallCallbacks" .Nz .SH "Synopsis" .Sy void XtCallCallbacks(\f(CIobject\fP, \f(CIcallback_name\fP, \f(CIcall_data\fP) .As Widget \f(CIobject\fP; String \f(CIcallback_name\fP; XtPointer \f(CIcall_data\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object; may be of class Object or any subclass thereof. .IP \f(CIcallback_name\fP 1i Specifies the resource name of the callback list to be executed. .IP \f(CIcall_data\fP 1i Specifies the value to pass to each callback procedure as its third argument. .\" .SH "Description" \f(CWXtCallCallbacks()\fP calls the procedures registered on the callback list named by \f(CIcallback_name\fP on the widget or object \f(CIobject\fP. It invokes each procedure with \f(CIobject\fP as the first argument, the data registered with each procedure as the second argument, and \f(CIcall_data\fP as the third argument. .SH "Usage" \f(CWXtCallCallbacks()\fP should only be called by widgets and objects; applications will never need to call it. .LP \f(CWXtCallCallbackList()\fP calls the procedures on a callback list specified directly as an \f(CWXtCallbackList\fP. This is generally a little faster because it does not have to look up the callback list by name. .LP The \f(CIcall_data\fP argument is untyped value. The caller must be sure to pass correctly initialized data of the type expected by callbacks registered on the specified callback list. This type may be an \f(CWint\fP, or some other type that fits in 32 bits, but is often a pointer to a structure. .SH "See Also" .na \s-1\fIXtAddCallback\fR\s+1\*(s1, \s-1\fIXtCallCallbackList\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtCallCallb 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtCallCallbackList@XtCallCallA .sp .5 XtCallCallbacks@XtCallCallB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCallConverter" "Xt \- Resource Management" .SH "Name" .Na XtCallConverter \- explicitly invoke a "new-style" resource converter and cache result. .XX "XtCallConverter" .Nz .SH "Synopsis" .Sy Boolean XtCallConverter(\f(CIdisplay\fP, \f(CIconverter\fP, \f(CIargs\fP, \ \f(CInum_args\fP, \f(CIfrom\fP, \f(CIto_in_out\fP, \f(CIcache_ref_return\fP) .As Display* \f(CIdisplay\fP; XtTypeConverter \f(CIconverter\fP; XrmValuePtr \f(CIargs\fP; Cardinal \f(CInum_args\fP; XrmValuePtr \f(CIfrom\fP; XrmValuePtr \f(CIto_in_out\fP; XtCacheRef *\f(CIcache_ref_return\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the display with which the conversion is to be associated. .IP \f(CIconverter\fP 1i Specifies the new-style conversion procedure to be called. .IP \f(CIargs\fP 1i Specifies the additional conversion arguments needed to perform the conversion, or \f(CWNULL\fR. .IP \f(CInum_args\fP 1i Specifies the number of additional arguments. .IP \f(CIfrom\fP 1i Specifies the source value to be converted. .IP \f(CIto_in_out\fP 1i Specifies the address at which the converted value is to be stored, and the number of bytes allocated at that address. .SS "Outputs" .IP \f(CIto_in_out\fP 1i Returns (in the \f(CWsize\fP field) the actual size of the converted value. .IP \f(CIcache_ref_return\fP 1i Returns a conversion cache ID if the converter was registered with reference counting. \f(CWNULL\fP may be passed for this argument if the caller is not interested in reference counting of cached conversion values. .SS "Returns" \f(CWTrue\fP if the conversion was performed successfully, \f(CWFalse\fP otherwise. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtCallConverter()\fP converts the value \f(CWfrom\fP as appropriate for the conversion procedure \f(CWconverter\fP by looking a converted value up in the cache, or by invoking the converter with the \f(CIdisplay\fP, \f(CIargs\fP, \f(CInum_args\fP, \f(CIfrom\fP, and \f(CIto_in_out\fP arguments. .LP \f(CIto_in_out\f(CW->addr\fR should contain the address at which the converted value is to be stored, and \f(CIto_in_out\f(CW->size\fR should contain the number of bytes allocated at that address. .LP See the "Background" section below for more details. .\" .SH "Usage" \f(CWXtConvertAndStore()\fP is a higher level interface to resource conversion, and is easier to use in most cases. .LP You do not often need, in applications or widgets, to convert between resource types directly. Generally you can rely on the Intrinsics resource management code to perform all necessary conversions for you. When writing a resource converter, however, you may find that you need to invoke another converter. .LP If \f(CWXtCallConverter()\fP returns an \f(CWXtCacheRef\fP value you must store it and decrement the reference count (with \f(CWXtAppReleaseCacheRefs()\fP) when you no longer need the converted value. The easiest way to do this is to register the predefined callback \f(CWXtCallbackReleaseCacheRef()\fP on the destroy callback of the widget or object that is using the converted value. .\" .SH "Background" \f(CWXtCallConverter()\fR looks up the specified type converter in the application context associated with the display. If the converter was not registered or was registered with cache type \f(CWXtCacheAll\fR or \f(CWXtCacheByDisplay\fR, \f(CWXtCallConverter()\fR looks in the conversion cache to see whether this conversion procedure has been called with the specified arguments. If so, \f(CWXtCallConverter()\fR checks the success status of the prior call. If the conversion failed, \f(CWXtCallConverter()\fR returns \f(CWFalse\fR immediately; otherwise it checks the size specified in the \f(CIto_in_out\fP argument. .LP If this size is greater than or equal to the size stored in the cache, \f(CWXtCallConverter()\fP: .IP \(bu 3n Copies the information stored in the cache to the location specified by the \f(CIto_in_out\fP argument. .IP \(bu 3n Stores the cache size in \f(CWto_in_out->size\fP. .IP \(bu 3n Returns \f(CWTrue\fR. .LP .RE If the size specified in the \f(CIto_in_out\fP argument is smaller than the size stored in the cache, \f(CWXtCallConverter()\fR copies the cache size into \f(CWto->size\fR and returns \f(CWFalse\fR. If the converter was registered with cache type \f(CWXtCacheNone\fR or if no value was found in the conversion cache, \f(CWXtCallConverter()\fR calls the converter and, if it was not registered with cache type \f(CWXtCacheNone\fR, enters the result in the cache. \f(CWXtCallConverter()\fR then returns what the converter returned. .LP \f(CIcache_ref_return\fR specifies storage allocated by the caller in which an opaque value will be stored. If the type converter has been registered with the \f(CWXtCacheRefCount\fR modifier and if the value returned in \f(CIcache_ref_return\fR is non-\f(CWNULL\fR, then the caller should store the \f(CIcache_ref_return\fR value in order to decrement the reference count when the converted value is no longer required. \f(CIcache_ref_return\fR should be specified as \f(CWNULL\fR if the caller is unwilling or unable to store the value. .Nd 10 .SH "Structures" .Ps typedef struct { unsigned int size; XPointer addr; } XrmValue, *XrmValuePtr; .Pe .SH "See Also" .na \s-1\fIXtCallbackReleaseCacheRef\fR\s+1\*(s1, \s-1\fIXtConvertAndStore\fR\s+1\*(s1, \s-1\fIXtSetTypeConverter\fR\s+1\*(s1, .br \s-1\fIXtTypeConverter\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCallbackNone" "Xt \- Pop Ups" .SH "Name" .Na XtCallbackNone \- callback function to pop up a widget. .XX "callbacks: callback list; popping up widget" .XN "widgets: callback list (see callbacks)" .XX "callbacks: callback list; XtCallbackNone" .XX "XtCallbackNone" .Nz .SH "Synopsis" .Sy void XtCallbackNone(\f(CIw\fP, \f(CIclient_data\fP, \f(CIcall_data\fP) .As Widget \f(CIw\fP; XtPointer \f(CIclient_data\fP; XtPointer \f(CIcall_data\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. .IP \f(CIclient_data\fP 1i Specifies the popup shell. .IP \f(CIcall_data\fP 1i Specifies the callback data, which is not used by this procedure. .SH "Description" \f(CWXtCallbackNone()\fP calls \f(CWXtPopup()\fP on the widget passed in the \f(CIclient_data\fP argument with \f(CIgrab_mode\fP set to \f(CWXtGrabNone\fP. Then it calls \f(CWXtSetSensitive()\fP on \f(CIw\fP to make that widget insensitive. .LP \f(CWXtCallbackNone()\fP is a convenience procedure designed to be registered on a widget's callback list (which is why it has a third, unused argument). The widget to be popped up should be registered as \f(CIclient_data\fP for the callback. The reason that this callback makes its invoking widget insensitive is so that the user cannot request to popup the shell again while it is already up. .\" .SH "Usage" To popup a shell with an exclusive grab or with no grab at all, you can use \f(CWXtCallbackExclusive()\fP or \f(CWXtCallbackNone()\fP. To popdown a shell from a callback, use \f(CWXtCallbackPopdown()\fP. .LP Note that this function does not attempt to place the popup shell at any particular location, and for that reason may not be appropriate in many circumstances. .LP It is also possible to pop up a shell with the \f(CWXtMenuPopup\fP action. .\" .SH "Example" To arrange for the shell \f(CWpshell\fP to be popped up when the user clicks on the button widget \f(CWbutton\fP, you would use code like the following: .Ps XtAddCallback(button,XtNcallback,XtCallbackNone,pshell); .Pe A companion example is presented on the \f(CWXtCallbackPopdown()\fR reference page. .SH "See Also" .na \s-1\fIXtCallbackExclusive\fR\s+1\*(s1, \s-1\fIXtCallbackNonexclusive\fR\s+1\*(s1, \s-1\fIXtCallbackPopdown\fR\s+1\*(s1, \s-1\fIXtMenuPopdown\fR\s+1\*(s1, \s-1\fIXtMenuPopup\fR\s+1\*(s1, \s-1\fIXtPopdown\fR\s+1\*(s1, \s-1\fIXtPopup\fR\s+1\*(s1, \s-1\fIXtSetSensitive\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCallbackNonexclusive" "Xt \- Pop Ups" .SH "Name" .Na XtCallbackNonexclusive \- callback function to pop up a widget. .Nz .XX "callbacks: callback list; popping up widget" .XN "widgets: callback list (see callbacks)" .XX "callbacks: callback list; XtCallbackNonexclusive" .XX "XtCallbackNonexclusive" .SH "Synopsis" .Sy void XtCallbackNonexclusive(\f(CIw\fP, \f(CIclient_data\fP, \f(CIcall_data\fP) .As Widget \f(CIw\fP; XtPointer \f(CIclient_data\fP; XtPointer \f(CIcall_data\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. .IP \f(CIclient_data\fP 1i Specifies the popup shell. .IP \f(CIcall_data\fP 1i Specifies the callback data, which is not used by this procedure. .SH "Description" \f(CWXtCallbackNonexclusive()\fP calls \f(CWXtPopup()\fP on the widget passed in the \f(CIclient_data\fP argument with \f(CIgrab_mode\fP set to \f(CWXtGrabNonexclusive\fP. Then it calls \f(CWXtSetSensitive()\fP on \f(CIw\fP to make that widget insensitive. .LP \f(CWXtCallbackNonexclusive()\fP is a convenience procedure designed to be registered on a widget's callback list (which is why it has a third, unused argument). The widget to be popped up should be registered as \f(CIclient_data\fP for the callback. The reason that this callback makes its invoking widget insensitive is so that the user cannot request to popup the shell again while it is already up. .\" .SH "Usage" To popup a shell with a non-exclusive grab or with no grab at all, you can use \f(CWXtCallbackNonexlusive()\fP or \f(CWXtCallbackNone()\fP. To popdown a shell from a callback, use \f(CWXtCallbackPopdown()\fP. .LP Note that this function does not attempt to place the popup shell at any particular location, and for that reason may not be appropriate in many circumstances. .LP It is also possible to pop up a shell with the \f(CWXtMenuPopup\fP action. .\" .SH "Example" To arrange for the shell \f(CWpshell\fP to be popped up when the user clicks on the button widget \f(CWbutton\fP, you would use code like the following: .Ps XtAddCallback(button,XtNcallback,XtCallbackNonexclusive,pshell); .Pe A companion example is presented on the \f(CWXtCallbackPopdown()\fR reference page. .SH "See Also" .na \s-1\fIXtCallbackNone\fR\s+1\*(s1, \s-1\fIXtCallbackExclusive\fR\s+1\*(s1, \s-1\fIXtCallbackPopdown\fR\s+1\*(s1, \s-1\fIXtMenuPopdown\fR\s+1\*(s1, \s-1\fIXtMenuPopup\fR\s+1\*(s1, \s-1\fIXtPopdown\fR\s+1\*(s1, \s-1\fIXtPopup\fR\s+1\*(s1, \s-1\fIXtSetSensitive\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCallbackPopdown" "Xt \- Pop Ups" .SH "Name" .Na XtCallbackPopdown \- callback function to popdown a widget. .XS "callbacks: callback list; popping down widget" .XN "widgets: callback list (see callbacks)" .XS "callbacks: callback list; XtCallbackPopdown" .XS "XtCallbackPopdown" .Nz .SH "Synopsis" .Sy void XtCallbackPopdown(\f(CIw\fP, \f(CIclient_data\fP, \f(CIcall_data\fP) .As Widget \f(CIw\fP; XtPointer \f(CIclient_data\fP; XtPointer \f(CIcall_data\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. .IP \f(CIclient_data\fP 1i Specifies a pointer to an \f(CWXtPopdownID\fR structure. .IP \f(CIcall_data\fP 1i Specifies the callback data, which is not used by this procedure. .SH "Description" \f(CWXtCallbackPopdown()\fP casts is \f(CIclient_data\fP argument to an \f(CWXtPopdownIDRec *\fP, calls XtPopdown on the widget in the \f(CWshell_widget\fP field, and then resensitizes the widget in the \f(CWenable_widget\fP field by calling \f(CWXtSetSensitive()\fP. .LP \f(CWXtCallbackPopdown()\fP is a convenience procedure designed to be registered on a widget's callback list (which is why it has third, unused argument) and used on a shell widget popped up with \f(CWXtCallbackExclusive()\fP, \f(CWXtCallbackNone()\fP, or \f(CWXtCallbackNonexclusive()\fP. The widget to be popped down and the widget that was desensitized when the shell was popped up should be stored into the \f(CWXtPopdownID\fP structure that is registered with \f(CWXtCallbackPopdown()\fP. .\" .SH "Usage" It is also possible to pop down a shell with the \f(CWXtMenuPopdown\fP action. .\" .SH "Example" The following code registers \f(CWXtCallbackPopdown()\fP to popdown the widget \f(CWpshell\fP when the button \f(CWok\fP is pressed. It assumes that \f(CWpshell\fP was popped up by \f(CWXtCallbackExclusive()\fP registered on the widget \f(CWbutton\fP. .Ps XtPopdownIDRec pop_rec; pop_rec.shell_widget = pshell; pop_rec.enable_widget = button; XtAddCallback(ok, XtNcallback, XtCallbackPopdown, &pop_rec); .Pe .\" .SH "Structures" \f(CWXtCallbackPopdown()\fP expects a \f(CWXtPopdownID\fP as its \f(CIclient_data\fP argument. .Ps typedef struct { Widget shell_widget; Widget enable_widget; } XtPopdownIDRec, *XtPopdownID; .Pe .\" .SH "See Also" .na \s-1\fIXtCallbackExclusive\fR\s+1\*(s1, \s-1\fIXtCallbackNone\fR\s+1\*(s1, \s-1\fIXtCallbackNonexclusive\fR\s+1\*(s1, \s-1\fIXtMenuPopup\fR\s+1\*(s1, \s-1\fIXtMenuPopdown\fR\s+1\*(s1, \s-1\fIXtPopdown\fR\s+1\*(s1, \s-1\fIXtPopup\fR\s+1\*(s1, \s-1\fIXtSetSensitive\fR\s+1\*(s1. .ad .XE "callbacks: callback list; popping down widget" .XE "callbacks: callback list; XtCallbackPopdown" .XE "XtCallbackPopdown" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCallbackProc" "Xt \- Callbacks" .SH "Name" .Na XtCallbackProc \- interface definition for callback procedure. .Nz .XS "callbacks, procedure" .XS "callbacks: (see also XtCallbackProc)" .XS "XtCallbackProc" .SH "Synopsis" .Sy typedef void (*XtCallbackProc)(Widget, XtPointer, XtPointer); .As Widget \f(CIw\fP\^; XtPointer \f(CIclient_data\fP; XtPointer \f(CIcall_data\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget for which the callback is registered. .IP \f(CIclient_data\fP 1i Specifies the data that was registered with this callback. .IP \f(CIcall_data\fP 1i Specifies data passed by the widget; its type is defined by the particular callback list of the particular widget class. .\" .SH "Description" \f(CWXtCallbackProc\fP is the type of all procedures registered on callback lists with \f(CWXtAddCallback()\fP or \f(CWXtAddCallbacks()\fP. A callback procedure is called when a widget calls \f(CWXtCallCallbacks()\fP or \f(CWXtCallCallbackList()\fP to invoke all the procedures that have been registered on one of its callback lists. Most callback lists are invoked from an action procedure in response to an event or series of events, as when an Xaw Command widget is clicked on, or when an Xaw Scrollbar widget is scrolled. .LP An \f(CWXtCallbackProc\fP takes three arguments: .IP "\(bu" 3 The first argument is the widget that triggered the callback: the widget for which the callback procedure was registered. You would use the value of this argument in your callback function if you registered the same function as a callback for two different widgets, and if you wanted to distinguish in the callback which widget called it, or you would use it if the purpose of the callback were to perform some operation on the widget itself. .IP "\(bu" 3 The second argument, \f(CIclient_data\fP, is whatever value was passed as the last argument of \f(CWXtAddCallback()\fP. \f(CIclient_data\fP provides a way for the client registering the callback also to register data that the callback procedure will need. This may be data of any type, cast to an \f(CWXtPointer\fP when registered, and cast back to the desired type within the callback procedure. Generally, callback procedures should be passed whatever data they are to operate on as their \f(CIclient_data\fP; if this is not done, the callback procedure will have to rely on global variables. .IP "\(bu" 3 The third argument, \f(CIcall_data\fP, is data supplied by the widget. The argument is of type \f(CWXtPointer\fP, but the actual type of the data depends on the particular widget class, and the callback list of that widget. Some widgets pass no data in this argument, others pass a single scalar type, and others pass a pointer to a structure of some type. The Xaw Command widget doesn't provide any \f(CIcall_data\fP, but the Xaw Scroll widget, for example, passes back the current position of the scrollbar. The documentation for the widget will specify the contents of this argument if it is used. The \f(CIcall_data\fP argument may not contain all the relevant information that a callback procedure might need. Callback procedures .ne 2 can also use \f(CWXtGetValues()\fP or other functions to obtain more information about the state of the widget. .LP See the "Background" section below for more information about registering callback procedures and about callback lists. .\" .SH "Usage" Almost every application will define and register a number of callback procedures. Once you have created the widgets that make up your application's interface and called \f(CWXtAppMainLoop()\fP, it is the callback procedures that you have registered that do all the processing for your application. .LP Action procedures and event handlers are other ways of having a procedure invoked when certain events occur, but are both lower level and far less commonly used than callback procedures. See \f(CWXtAppAddActions()\fP and \f(CWXtAddEventHandler()\fP. .LP You can also register procedures to be called when the application is idle, when a timeout expires, or when there is input available from a source other than the X server. This is done with \f(CWXtAppAddWorkProc()\fP, \f(CWXtAppAddTimeOut()\fP, and \f(CWXtAppAddInput()\fP. The procedures registered are similar in concept to callback procedures, but are not of type \f(CWXtCallbackProc\fP. .LP Note that not all callbacks are called in response to user events. The \f(CWXtNdestroyCallback\fP list of all widgets and objects is invoked when an object is destoyed, for example, and the \f(CWXtNpopupCallback\fP list of Shell widgets is called just before the shell widget is popped up, whether or not a user event directly triggered the popup. .LP If any of the arguments are unused in your callback procedure, use the \f(CW/* ARGSUSED */\fP comment to avoid warnings from \fIlint\fP. For ANSI-C type checking, you should declare your callbacks with all three arguments even if some are unused. Note that you can use procedures that are not of type \f(CWXtCallbackProc\fP (such as \f(CWXtUnmanageChild()\fP, for example) if you cast those procedures to type \f(CWXtCallbackProc\fP when you register them. .\" .SH "Example" The following callback procedure is from the \fIeditres\fP client: .Ps /* ARGSUSED */ void PannerCallback(w, closure, report_ptr) Widget w; XtPointer closure, report_ptr; { Arg args[2]; XawPannerReport *report = (XawPannerReport *) report_ptr; if (global_tree_info == NULL) return; XtSetArg (args[0], XtNx, -report->slider_x); XtSetArg (args[1], XtNy, -report->slider_y); .Nd 10 XtSetValues(global_tree_info->tree_widget, args, TWO); } .Pe It is registered by \fIeditres\fP on the \f(CWXtNreportCallback\fP list of the widget \f(CWpanner\fP, and is registered with another widget, \f(CWporthole\fP as \f(CIclient_data\fP. .Ps \s-2XtAddCallback(panner, XtNreportCallback, PannerCallback, (XtPointer) porthole);\s+2 .Pe .\" .SH "Background" Whenever a client wants to pass a callback list as an argument in an \f(CWXtCreateWidget()\fP, \f(CWXtSetValues()\fP, or \f(CWXtGetValues()\fP call, it should specify the address of a \f(CWNULL\fP-terminated array of type \f(CWXtCallbackList\fP. .LP When a callback procedure, or list of callback procedures, is passed as a resource argument, Xt constructs an internal data structure for the callback list. Subsequently, callback lists cannot be queried. Because Xt doesn't support a string-to-callback resource converter, callbacks cannot be specified in resource files. The internal form can only be accessed by the Intrinsics functions \f(CWXtAddCallback()\fR, \f(CWXtAddCallbacks()\fR, \f(CWXtRemoveCallback()\fR, \f(CWXtRemoveCallbacks()\fR, \f(CWXtCallCallbacks()\fR, \f(CWXtCallCallbackList()\fP, and \f(CWXtHasCallbacks()\fP. Furthermore, since callback lists are handled specially by the Intrinsics, widget procedures should not allocate memory for callback lists passed as resources. Unlike other resources, a widget's \f(CWinitialize()\fR method should not attempt to make copies of resources of type \f(CWXtRCallback\fR. .LP For the Intrinsics to find and correctly handle callback lists, they must be declared with a resource type of \f(CWXtRCallback\fR. The internal representation of a callback list is implementation-dependent; widgets may make no assumptions about the value stored in this resource if it is non-\f(CWNULL\fR. Except to compare the value to \f(CWNULL\fR (which is equivalent to \f(CWXtCallbackHasNone\fR returned by \f(CWXtHasCallbacks()\fP), access to callback list resources must be made through other Intrinsics procedures. .SH "Structures" The \f(CWXtCallbackRec\fP structure and the \f(CWXtCallbackList\fP types are defined as follows: .XX "XtCallbackList" .XX "XtCallbackRec" .Ps typedef struct _XtCallbackRec { XtCallbackProc callback; XtPointer closure; } XtCallbackRec, *XtCallbackList; .Pe .\" .SH "See Also" .na \s-1\fIXtAddCallback\fR\s+1\*(s1, \s-1\fIXtAddCallbacks\fR\s+1\*(s1, \s-1\fIXtCallCallbacks\fR\s+1\*(s1, \s-1\fIXtHasCallbacks\fR\s+1\*(s1, \s-1\fIXtRemoveCallback\fR\s+1\*(s1, \s-1\fIXtRemoveCallbacks\fR\s+1\*(s1. .ad .XE "callbacks, procedure" .XE "callbacks: (see also XtCallbackProc)" .XE "XtCallbackProc" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCallbackExclusive" "Xt \- Pop Ups" .SH "Name" .Na XtCallbackExclusive \- callback function to pop up a widget. .XN "widgets: callback list (see callbacks)" .XS "callbacks: callback list; popping up widget" .XS "callbacks: callback list; XtCallbackExclusive" .XS "XtCallbackExclusive" .Nz .SH "Synopsis" .Sy void XtCallbackExclusive(\f(CIw\fP, \f(CIclient_data\fP, \f(CIcall_data\fP) .As Widget \f(CIw\fP; XtPointer \f(CIclient_data\fP; XtPointer \f(CIcall_data\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. .IP \f(CIclient_data\fP 1i Specifies the popup shell. .IP \f(CIcall_data\fP 1i Specifies the callback data, which is not used by this procedure. .SH "Description" \f(CWXtCallbackExclusive()\fP calls \f(CWXtPopup()\fP on the widget passed in the \f(CIclient_data\fP argument with \f(CIgrab_mode\fP set to \f(CWXtGrabExclusive\fP. Then it calls \f(CWXtSetSensitive()\fP on \f(CIw\fP to make that widget insensitive. .LP \f(CWXtCallbackExclusive()\fP is a convenience procedure designed to be registered on a widget's callback list (which is why it has a third, unused argument). The widget to be popped up should be registered as \f(CIclient_data\fP for the callback. The reason that this callback makes its invoking widget insensitive is so that the user cannot request to popup the shell again while it is already up. .\" .SH "Usage" To popup a shell with a non-exclusive grab or with no grab at all, you can use \f(CWXtCallbackNonexclusive()\fP or \f(CWXtCallbackNone()\fP. To popdown a shell from a callback, use \f(CWXtCallbackPopdown()\fP. .LP Note that this function does not attempt to place the popup shell at any particular location, and for that reason may not be appropriate in many circumstances. .LP It is also possible to pop up a shell with the \f(CWXtMenuPopup\fP action. .\" .SH "Example" To arrange for the shell \f(CWpshell\fP to be popped up when the user clicks on the button widget \f(CWbutton\fP, you would use code like the following: .Ps XtAddCallback(button,XtNcallback,XtCallbackExclusive,pshell); .Pe A companion example is presented on the \f(CWXtCallbackPopdown()\fR reference page. .SH "See Also" .na \s-1\fIXtCallbackNone\fR\s+1\*(s1, \s-1\fIXtCallbackNonexclusive\fR\s+1\*(s1, \s-1\fIXtCallbackPopdown\fR\s+1\*(s1, \s-1\fIXtMenuPopdown\fR\s+1\*(s1, \s-1\fIXtMenuPopup\fR\s+1\*(s1, \s-1\fIXtPopdown\fR\s+1\*(s1, \s-1\fIXtPopup\fR\s+1\*(s1, \s-1\fIXtSetSensitive\fR\s+1\*(s1. .ad .XE "callbacks: callback list; popping up widget" .XE "callbacks: callback list; XtCallbackExclusive" .XE "XtCallbackExclusive" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCallbackReleaseCacheRef" "Xt \- Resource Management" .SH "Name" .XS "XtCallbackReleaseCacheRef" .Na XtCallbackReleaseCacheRef \- callback function to release a cached resource value. .Nz .SH "Synopsis" .Sy void XtCallbackReleaseCacheRef(\f(CIobject\fP, \f(CIclient_data\fP, \f(CIcall_data\fP) .As Widget \f(CIobject\fP; XtPointer \f(CIclient_data\fP; XtPointer \f(CIcall_data\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object with which the resource is associated. .IP \f(CIclient_data\fP 1i Specifies the conversion cache entry to be released. .IP \f(CIcall_data\fP 1i Is ignored. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtCallbackReleaseCacheRef()\fP casts its \f(CIclient_data\fP argument to an \f(CWXtCacheRef\fP, places it in a \f(CWNULL\fP-terminated array of \f(CWXtCacheRef\fP and passes this array to \f(CWXtAppReleaseCacheRefs()\fP. \f(CWXtAppReleaseCacheRefs()\fP decrements the reference count on the specified object in the resource conversion cache, and if the count reaches zero it removes the object from the cache and calls the appropriate destructor procedures. .LP \f(CWXtCallbackReleaseCacheRef()\fP is a convenience procedure designed to be registered on the destroy callback list of a widget or object (which is why it has third, unused argument). .\" .SH "Usage" \f(CWXtCacheRef\fP values are returned from calls to \f(CWXtCallConverter()\fP. The higher-level converter function \f(CWXtConvertAndStore()\fP performs the conversion and automatically registers this function on the object's destroy callback list if necessary. .LP To release an array of \f(CWXtCacheRef\fP, you can use \f(CWXtCallbackReleaseCacheRefList()\fP. .\" .SH "Structures" \f(CWXtCacheRef\fP is an opaque type. .\" .SH "See Also" .na \s-1\fIXtAppReleaseCacheRefs\fR\s+1\*(s1, \s-1\fIXtCallbackReleaseCacheRefList\fR\s+1\*(s1, \s-1\fIXtCallConverter\fR\s+1\*(s1, \s-1\fIXtConvertAndStore\fR\s+1\*(s1. .ad .\"last line comment .XE "XtCallbackReleaseCacheRef" .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCallbackReleaseCacheRefList" "Xt \- Resource Management" .SH "Name" .XX "XtCallbackReleaseCacheRefList" .na XtCallbackReleaseCacheRefList \- callback function to release a list of cached values. .Nz .SH "Synopsis" .Sy void XtCallbackReleaseCacheRefList(\f(CIobject\fP, \f(CIclient_data\fP, \f(CIcall_data\fP) .As Widget \f(CIobject\fP; XtPointer \f(CIclient_data\fP; XtPointer \f(CIcall_data\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object with which the resources are associated. .IP \f(CIclient_data\fP 1i Specifies the conversion cache entries to be released. .IP \f(CIcall_data\fP 1i Is ignored. .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtCallbackReleaseCacheRefList()\fP casts its \f(CIclient_data\fP argument to a \f(CWNULL\fP-terminated array of \f(CWXtCacheRef\fP and passes this array to \f(CWXtAppReleaseCacheRefs()\fP. \f(CWXtAppReleaseCacheRefs()\fP decrements the reference count on the specified objects in the resource conversion cache, and if the count reaches zero on any of them it removes the object from the cache and calls the appropriate destructor procedures. .LP \f(CWXtCallbackReleaseCacheReList()\fP is a convenience procedure designed to be registered on the destroy callback list of a widget or object (which is why it has third, unused argument). .\" .SH "Usage" \f(CWXtCacheRef\fP values are returned from calls to \f(CWXtCallConverter()\fP. The higher-level converter function \f(CWXtConvertAndStore()\fP performs the conversion and automatically registers \f(CWXtCallbackReleaseCacheRef()\fP on the object's destroy callback list if necessary. .LP To release a single \f(CWXtCacheRef\fP, you can use \f(CWXtCallbackReleaseCacheRef()\fP. .\" .SH "Structures" \f(CWXtCacheRef\fP is an opaque type. .\" .SH "See Also" .na \s-1\fIXtAppReleaseCacheRefs\fR\s+1\*(s1, \s-1\fIXtCallbackReleaseCacheRef\fR\s+1\*(s1, \s-1\fIXtCallConverter\fR\s+1\*(s1, \s-1\fIXtConvertAndStore\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtCallbackN 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtCallbackNone@XtCallbackA .sp .5 XtCallbackNonexclusive@XtCallbackB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtCallbackP 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtCallbackPopdown@XtCallbackC .sp .5 XtCallbackProc@XtCallbackD .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtCallbackR 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtCallbackReleaseCacheRef@XtCallbackF .sp .5 XtCallbackReleaseCacheRefList@XtCallbackG .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCalloc" "Xt \- Memory Allocation" .SH "Name" .Na XtCalloc \- allocate memory for an array and initialize its bytes to zero. .XX "array, allocating" .XX "array, XtCalloc" .XX "XtCalloc" .Nz .SH "Synopsis" .Sy char *XtCalloc(\f(CInum\fP, \f(CIsize\fP); .As Cardinal \f(CInum\fP; Cardinal \f(CIsize\fP; .Ae .SS "Inputs" .IP \f(CInum\fP 1i Specifies the number of array elements to allocate. .IP \f(CIsize\fP 1i Specifies the size of an array element in bytes. .SS "Returns" A pointer to allocated memory. .SH "Description" \f(CWXtCalloc()\fR allocates memory for an array of \f(CInum\fP elements each of \f(CIsize\fP bytes and initializes each allocated byte to zero. If there is insufficient memory, \f(CWXtCalloc()\fR terminates by calling \f(CWXtErrorMsg()\fR. .\" .SH "Usage" Note that in most cases, you will have to cast the return value of \f(CWXtCalloc()\fP to the type appropriate for the array elements you are allocating. .LP \f(CWXtNew()\fR and \f(CWXtNewString()\fR provide slightly higher-level approaches to memory allocation. .LP The function \f(CWXtCalloc()\fR is implemented by the Toolkit independently of the particular environment, so programs ported to a system not supporting \f(CWcalloc\fR will still work. .SH "See Also" .na \s-1\fIXtErrorMsg\fR\s+1\*(s1, \s-1\fIXtFree\fR\s+1\*(s1, \s-1\fIXtMalloc\fR\s+1\*(s1, \s-1\fIXtNew\fR\s+1\*(s1, \s-1\fIXtNewString\fR\s+1\*(s1, \s-1\fIXtRealloc\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCancelConvertSelectionProc" "Xt \- Selections" .SH "Name" .Na XtCancelConvertSelectionProc \- interface definition for procedure to cancel incremental selection transfer. .Nz .XS "XtCancelConvertSelectionProc" .SH "Synopsis" .Sy typedef void (*XtCancelConvertSelectionProc)(Widget, Atom*, Atom*, .br XtRequestId*, XtPointer); .As Widget \f(CIw\fP; Atom *\f(CIselection\fP; Atom *\f(CItarget\fP; XtRequestId *\f(CIrequest_id\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIw\fR 1i Specifies the widget that owns the selection. .IP \f(CIselection\fP 1i Specifies the atom that names the selection being transferred. .IP \f(CItarget\fP 1i Specifies the target type to which the conversion was done. .IP \f(CIrequest_id\fP 1i Specifies an opaque identification for a specific request. .IP \f(CIclient_data\fP 1i Specifies the value passed in by the widget when it took ownership of the selection. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" This procedure is registered in a call to \f(CWXtOwnSelectionIncremental()\fP, and is called by the Intrinsics to abort an incremental transfer when (as determined by the selection timeout or other mechanism) any remaining segments of the selection no longer need to be transferred. Upon receiving this callback, the selection request is considered complete and the owner should free the memory and any other resources that have been allocated for the transfer. .LP The \f(CIw\fP, \f(CIselection\fP, and \f(CIclient_data\fP arguments are those passed in the call to \f(CWXtOwnSelectionIncremental()\fP. The \f(CItarget\fP and \f(CIrequest_id\fP arguments are the selection target type specified by the selection requestor, and the unique ID assigned to this transfer by the Intrinsics. Both will have been passed to a previous call to the \f(CWXtConvertSelectionIncrProc\fP also registered with \f(CWXtOwnSelectionIncremental()\fP. .\" .SH "See Also" .na \s-1\fIXtGetSelectionValueIncremental\fR\s+1\*(s1, \s-1\fIXtGetSelectionValuesIncremental\fR\s+1\*(s1, \s-1\fIXtGetSelectionTimeout\fR\s+1\*(s1, \s-1\fIXtOwnSelectionIncremental\fR\s+1\*(s1, \s-1\fIXtSetSelectionTimeout\fR\s+1\*(s1, .br \s-1\fIXtConvertSelectionIncrProc\fR\s+1\*(s2, \s-1\fIXtLoseSelectionIncrProc\fR\s+1\*(s2, \s-1\fIXtSelectionDoneIncrProc\fR\s+1\*(s2. .ad .XE "XtCancelConvertSelectionProc" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCaseProc" "Xt \- Keyboard Handling" .SH "Name" .Na XtCaseProc \- interface definition for procedure to convert the case of keysyms. .Nz .XS "keysyms, converting case" .XS "keysyms, XtCaseProc" .XS "XtCaseProc" .SH "Synopsis" .Sy typedef void (*XtCaseProc) (Display*, KeySym, KeySym *, KeySym *); .As Display *\f(CIdisplay\fP KeySym \f(CIkeysym\fP; KeySym *\f(CIlower_return\fP; KeySym *\f(CIupper_return\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1.2i Provides the display connection for which the conversion is required. .IP \f(CIkeysym\fP 1.2i Specifies the keysym to convert. .SS "Outputs" .IP \f(CIlower_return\fP 1.2i Returns the lowercase equivalent for \f(CIkeysym\fP. .IP \f(CIupper_return\fP 1.2i Returns the uppercase equivalent for \f(CIkeysym\fP. .\" .SH "Description" An \f(CWXtCaseProc\fP is a case converter procedure registered with \f(CWXtRegisterCaseConverter()\fP, and invoked by \f(CWXtConvertCase()\fP and by the Translation Manager in order to obtain the uppercase and lowercase versions of a keysym. It should store the upper and lower case versions of \f(CWkeysym\fP at the addresses specified by \f(CIlower_return\fP and \f(CIupper_return\fP. If there is no case distinction, it should store \f(CWkeysym\fP at both locations. .\" .SH "Usage" You should only need to write a case converter procedure if you are working with non-standard keysyms. .\" .SH "Example" The default case converter from the R4 Intrinsics is as follows: .Ps /* ARGSUSED */ void _XtConvertCase(dpy, sym, lower, upper) Display *dpy; KeySym sym; KeySym *lower; KeySym *upper; { *lower = sym; *upper = sym; switch(sym >> 8) { case 0: if ((sym >= XK_A) && (sym <= XK_Z)) *lower += (XK_a - XK_A); else if ((sym >= XK_a) && (sym <= XK_z)) *upper -= (XK_a - XK_A); else if ((sym >= XK_Agrave) && (sym <= XK_Odiaeresis)) *lower += (XK_agrave - XK_Agrave); else if ((sym >= XK_agrave) && (sym <= XK_odiaeresis)) *upper -= (XK_agrave - XK_Agrave); else if ((sym >= XK_Ooblique) && (sym <= XK_Thorn)) *lower += (XK_oslash - XK_Ooblique); else if ((sym >= XK_oslash) && (sym <= XK_thorn)) *upper -= (XK_oslash - XK_Ooblique); break; default: /* XXX do all other sets */ break; } } .Pe .\" .SH "See Also" .na \s-1\fIXtConvertCase\fR\s+1\*(s1, \s-1\fIXtGetKeysymTable\fR\s+1\*(s1, \s-1\fIXtKeysymToKeycodeList\fR\s+1\*(s1, \s-1\fIXtRegisterCaseConverter\fR\s+1\*(s1, \s-1\fIXtSetKeyTranslator\fR\s+1\*(s1, \s-1\fIXtTranslateKeycode\fR\s+1\*(s1. .ad .XE "keysyms, converting case" .XE "keysyms, XtCaseProc" .XE "XtCaseProc" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCheckSubclass" "Xt \- Object Information" .SH "Name" .Na XtCheckSubclass \- verify an object's class, if compiled with DEBUG defined. .XX "widgets: class; verifying (XtCheckSubclass)" .XX "XtCheckSubclass" .Nz .SH "Synopsis" .Sy void XtCheckSubclass(\f(CIobject\fP, \f(CIobject_class\fP, \f(CImessage\fP) .As Widget \f(CIobject\fP; WidgetClass \f(CIobject_class\fP; String \f(CImessage\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1.2i Specifies the object; may be of class Object or any subclass thereof. .IP \f(CIobject_class\fP Specifies the widget class to test against; may be objectClass or any subclass thereof. .IP \f(CImessage\fP Specifies the message to be displayed if \f(CIobject\fP is not a subclass of \f(CIobject_class\fR. .\" .SH "Description" \f(CWXtCheckSubclass()\fR checks that \f(CIobject\fP is of class \f(CIobject_class\fP or a subclass. If it is not, \f(CWXtCheckSubclass()\fP calls \f(CWXtErrorMsg()\fP passing \f(CImessage\fP as the default message to be displayed. \f(CWXtErrorMsg()\fP displays the message and terminates the application. .LP \f(CWXtCheckSubclass()\fP is implemented as a macro which only performs the check if compiled with the symbol DEBUG defined (i.e., if the C compiler is invoked with the flag\p \-DDEBUG). .\" .SH "Usage" \f(CWXtCheckSubclass()\fP is intended for use similar to the POSIX \f(CWassert()\fP macro while developing and debugging a widget or an application. It should be used in all application and widget-internal functions that might inadvertently be passed an object of the wrong type. Public functions exported by a widget should always check a widget's class (not just when DEBUG is defined) using \f(CWXtIsSubclass()\fP or a related function because even if a widget is bug-free, an application programmer may still pass an object of the wrong type to the widget. .\" .SH "See Also" .na \s-1\fIXtClass\fR\s+1\*(s1, \s-1\fIXtIsSubclass\fR\s+1\*(s1, \s-1\fIXtSuperclass\fR\s+1\*(s1, .br \s-1\fICore\fR\s+1\*(s3. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtClass" "Xt \- Object Information" .SH "Name" .Na XtClass \- obtain a widget's class. .XX "widgets: class; obtaining (XtClass)" .XX "XtClass" .Nz .SH "Synopsis" .Sy WidgetClass XtClass(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object; may be of class Object or any subclass thereof. .SS "Returns" A pointer to the class structure for \f(CIobject\fP. .SH "Description" \f(CWXtClass()\fR returns a pointer to the specified object's class structure. .LP \f(CWXtClass()\fP is implemented as a function when called from application code, but is replaced by a more efficient macro when called from widget code including the file \fI\fP. .SH "See Also" .na \s-1\fIXtCheckSubclass\fR\s+1\*(s1, \s-1\fIXtIsSubclass\fR\s+1\*(s1, \s-1\fIXtSuperclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCloseDisplay" "Xt \- Initialization" .SH "Name" .Na XtCloseDisplay \- close a display and remove it from an application context. .XX "display, closing" .XX "display, XtCloseDisplay" .XX "XtCloseDisplay" .Nz .SH "Synopsis" .Sy void XtCloseDisplay(\f(CIdisplay\fP) .As Display *\f(CIdisplay\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the display. .SH "Description" \f(CWXtCloseDisplay()\fR calls \f(CWXCloseDisplay()\fP to close \f(CIdisplay\fP as soon as it is safe to do so. If called from within an event dispatch (for example, a callback procedure), \f(CWXtCloseDisplay()\fR does not close the display until the dispatch is complete. .LP The closed display is removed from its application context. Any converted resources associated with that display which are cached with an \f(CWXtCacheType\fP of \f(CWXtCacheByDisplay\fP are removed from the conversion cache and have their destructors, if any, called. .\" .SH "Usage" Note that applications need only call \f(CWXtCloseDisplay()\fR if they are to continue executing after closing the display; otherwise, they should call \f(CWXtDestroyApplicationContext()\fR or just exit. .SH "See Also" .na \s-1\fIXtAppInitialize\fR\s+1\*(s1, \s-1\fIXtDestroyApplicationContext\fR\s+1\*(s1, \s-1\fIXtOpenDisplay\fR\s+1\*(s1, \s-1\fIXtSetTypeConverter\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtConfigureWidget" "Xt \- Geometry Management" .SH "Name" .Na XtConfigureWidget \- move and/or resize widget. .XS "widgets, moving/resizing" .XS "widgets: moving/resizing; XtConfigureWidget" .XS "XtConfigureWidget" .Nz .SH "Synopsis" .Sy void XtConfigureWidget(\f(CIw\fP, \f(CIx\fP, \f(CIy\fP, \f(CIwidth\fP, \f(CIheight\fP, \f(CIborder_width\fP) .As Widget \f(CIw\fP; Position \f(CIx\fP; Position \f(CIy\fP; Dimension \f(CIwidth\fP; Dimension \f(CIheight\fP; Dimension \f(CIborder_width\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget; must be of class RectObj or any subclass thereof. .IP "\f(CIx\fP, \f(CIy\fP" 1i Specify the widget's new x and y coordinates. .IP "\f(CIwidth\fP, \f(CIheight\fP, \f(CIborder_width\fP" 1i Specify the widget's new dimensions. .\" .SH "Description" \f(CWXtConfigureWidget()\fR sets the size and position of a widget. If the new size and position are the same as the widget's current values, it returns immediately. Otherwise \f(CWXtConfigureWidget()\fR writes the new \f(CIx\fR, \f(CIy\fR, \f(CIwidth\fR, \f(CIheight\fR, and \f(CIborder_width\fR values into instance fields of the object and, if the object is a widget and is realized, calls \f(CWXConfigureWindow()\fR on the widget's window. .LP If either the new width or the new height is different from its old value, \f(CWXtConfigureWidget()\fR calls the widget's \f(CWresize()\fP method to notify it of the size change. .\" .SH "Usage" \f(CWXtConfigureWidget()\fP should be used only by a parent widget on one of its children widget. If you want to set a widget size or position from an application, use \f(CWXtSetValues()\fP to set the \f(CWXtNx\fP, \f(CWXtNy\fP, \f(CWXtNwidth\fP, and \f(CWXtNheight\fP resources. If widget wants to change its own size or location, it must use \f(CWXtMakeGeometryRequest()\fP. .LP \f(CWXtResizeWidget()\fP and \f(CWXtMoveWidget()\fP are similar to \f(CWXtConfigureWidget()\fP but are simpler for the cases when you need only to resize or only to move a widget. .\" .SH "See Also" .na \s-1\fIXtMakeGeometryRequest\fR\s+1\*(s1, \s-1\fIXtMakeResizeRequest\fR\s+1\*(s1, \s-1\fIXtMoveWidget\fR\s+1\*(s1, \s-1\fIXtResizeWidget\fR\s+1\*(s1. .ad .XE "widgets, moving/resizing" .XE "widgets: moving/resizing; XtConfigureWidget" .XE "XtConfigureWidget" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtConvert" "Xt \- Resource Management" .SH "Name" .Na XtConvert \- convert resource type. .XS "resources: type conversion; XtConvert" .XS "XtConvert" .LP .sp .Nz .SH "Synopsis" .Sy void XtConvert(\f(CIobject\fP, \f(CIfrom_type\fP, \f(CIfrom\fP, \f(CIto_type\fP, \f(CIto_return\fP) .As Widget \f(CIobject\fP; String \f(CIfrom_type\fP; XrmValuePtr \f(CIfrom\fP; String \f(CIto_type\fP; XrmValuePtr \f(CIto_return\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object to use for additional arguments (if any are needed); may be of class Object or any subclass thereof. .IP \f(CIfrom_type\fP 1i Specifies the source type. .IP \f(CIfrom\fP 1i Specifies the value to be converted. .IP \f(CIto_type\fP 1i Specifies the destination type. .SS "Outputs" .IP \f(CIto_return\fP 1i Returns the address and the size of the converted value. .\" .SH "Availability" Superseded by \f(CWXtConvertAndStore()\fP. .\" .SH "Description" \f(CWXtConvert()\fR looks up the appropriate resource converter registered to convert \f(CIfrom_type\fP to \f(CIto_type\fP, computes any additional arguments required by that converter (see \f(CWXtSetTypeConverter()\fP for an explanation of how these arguments are computed) and then calls \f(CWXtDirectConvert()\fP or \f(CWXtCallConverter()\fP depending on whether the converter procedure is an "old-style" or a "new-style" converter. .LP If the conversion is successful, \f(CIto_return\f(CW->addr\fR will be non-\f(CWNULL\fP. The data at this address must be copied immediately by the caller, because it may be in static storage owned by the type converter procedure. .\" .SH "Usage" As of Release 4, \f(CWXtConvert()\fP is superseded by the more general function \f(CWXtConvertAndStore()\fP. .LP You do not often need, in applications or widgets, to convert between resource types directly. Generally you can rely on the Intrinsics resource management code to perform all necessary conversions for you. When writing a resource converter, however, you may find that you need to invoke another converter. .\" .Nd 10 .SH "Structures" .Ps typedef struct { unsigned int size; XPointer addr; } XrmValue, *XrmValuePtr; .Pe .Nd 3 .SH "See Also" .na \s-1\fIXtConvertAndStore\fR\s+1\*(s1. .ad .XE "resources: type conversion; XtConvert" .XE "XtConvert" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtConvertAndStore" "Xt \- Resource Management" .SH "Name" .XS "XtConvertAndStore" .Na XtConvertAndStore \- look up and call a resource converter, copying the resulting value. .Nz .SH "Synopsis" .Sy Boolean XtConvertAndStore(\f(CIobject\fP, \f(CIfrom_type\fP, \f(CIfrom\fP, \f(CIto_type\fP, \f(CIto_in_out\fP) .As Widget \f(CIobject\fP; String \f(CIfrom_type\fP; XrmValuePtr \f(CIfrom\fP; String \f(CIto_type\fP; XrmValuePtr \f(CIto_in_out\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object to use for additional arguments, if any are needed, and the destroy callback list; may be of class Object or any subclass thereof. .IP \f(CIfrom_type\fP 1i Specifies the source type. .IP \f(CIfrom\fP 1i Specifies the value to be converted. .IP \f(CIto_type\fP 1i Specifies the destination type. .IP \f(CIto_in_out\fP 1i Specifies the address at which the converted value is to be stored, or \f(CWNULL\fP, and the number of bytes allocated for the value at that address. .SS "Outputs" .IP \f(CIto_in_out\fP 1i Returns the address at which the converted value was stored, and the actual number of bytes occupied by that value. .SS "Returns" \f(CWTrue\fP if the conversion was successful; \f(CWFalse\fP otherwise. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtConvertAndStore()\fR looks up the type converter registered to convert \f(CIfrom_type\fR to \f(CIto_type\fR, computes any additional arguments needed (see \f(CWXtSetTypeConverter()\fP for an explanation of how these arguments are computed), and then calls \f(CWXtCallConverter()\fR (or \f(CWXtDirectConvert()\fR for old-style converters) with the \f(CIfrom\fR and \f(CIto_in_out\fR arguments. .LP When converting from a string, \f(CIfrom_type\fP should be \f(CWXtRString\fP, \f(CIfrom->addr\fP should be the address of the first character of the string (a \f(CWchar *\fP, not a \f(CWchar **\fP), and \f(CIfrom->size\fP should be the length of the string plus one. .LP Generally, the caller will initialize the \f(CIto_in_out\fR argument to specify the location at which the converted value will be stored and the number of bytes of memory allocated at that location. The \f(CIto_in_out\fP argument is passed directly to the converter which stores the data at the requested location and modifies the \f(CWsize\fP field to the actual size of the converted data. .LP If instead \f(CIto_in_out\f(CW->addr\fR is \f(CWNULL\fP on entry to \f(CWXtConvertAndStore()\fP, it will be replaced with a pointer to private storage which contains the converted value. As in the previous case, the size of the converted value will be returned in \f(CIto_in_out\f(CW->size\fR. A value returned in this way is stored in memory that is static to the converter, and the caller is expected to copy it immediately and must not modify it in any way. .LP \f(CWXtCallConverter()\fP returns \f(CWTrue\fP if the conversion succeeds, and returns \f(CWFalse\fP otherwise. .LP \f(CWXtConvertAndStore()\fR adds \f(CWXtCallbackReleaseCacheRef()\fR to the \f(CWdestroyCallback\fR list of the specified widget or object if the conversion returns an \f(CWXtCacheRef\fR value. This will automatically decrement the reference count on the cached value of the resource when the object no longer needs it. The resulting resource should not be referenced after the object has been destroyed. .\" .rs .sp -.5 .SH "Usage" You do not often need, in applications or widgets, to convert between resource types directly. Generally you can rely on the Intrinsics resource management code to perform all necessary conversions for you. When writing a resource converter, however, you may find that you need to invoke another converter. .LP The Intrinsics define a number of pre-registered converters, most of them between \f(CWString\fP and other common Xt types. The table below describes these predefined converters. The Xmu library also contains a number of useful converters, which are not pre-registered. See \f(CWXmuCvtStringToMisc\fP(6). .LP .sp -.5 .sp 1 .in 0 .KS .TS H linesize(2), tab(@); lfCI lfCI l lp6fCW lp6fCW lp7w(2.73i). from_type@to_type@Description .sp 2p .sp 2p .Th XtRString@XtRAcceleratorTable@T{ Compiles a string accelerator table into internal accelerator table format. T} @XtRAtom@T{ Converts a string to an Atom with XInternAtom(). T} @XtRBoolean@T{ Converts strings \(odtrue,\(cd \(odfalse,\(cd \(odyes,\(cd \(odno,\(cd \(odon,\(cd \(odoff\(cd to corresponding Boolean value (case insensitive). T} @XtRBool@Same as for \f(CWXtRBoolean\fP. @XtRCursor@T{ Given a standard X cursor name, returns a cursor ID. T} @XtRDimension@T{ Converts a width or height value to a \f(CWDimension\fP. T} @XtRDisplay@T{ Given a display name, opens the display and returns a \f(CWDisplay\fP structure. T} @XtRFile@T{ Given a filename, opens the file and returns the file descriptor. T} @XtRFloat@Converts a numeric string to floating point. @XtRFont@T{ Given a font name, loads the font and returns the font ID. The value \f(CWXtDefaultFont\fP will return the default font for the screen. T} @XtRFontSet@T{ Converts a list of base font names to an XFontSet. See XCreateFontSet() for information on the syntax of the font name list. The value \f(CWXtDefaultFontSet\fP will be converted to the default XFontSet for the screen. T} @XtRFontStruct@T{ Given a font name, loads the font and returns a pointer to the \f(CWXFontStruct\fP containing font metrics. \f(CWXtDefaultFont\fP returns the default font for the screen. T} @XtRInt@Converts a numeric string to an integer. @XtRInitialState@T{ Converts the strings "NormalState" and "IconicState" to the corresponding enum values \f(CWNormalState\fP and \f(CWIconicState\fP. T} @XtRPixel@T{ Converts a color name string (e.g., \(odred\(cd or \(od#FF0000\(cd) into the pixel value that will produce the closest color possible on the hardware. See Appendix C, \fISpecifying Fonts and Colors\fP, for information on legal values. The values \f(CWXtDefaultBackground\fP and \f(CWXtDefaultForeground\fP are always guaranteed to exist, and to contrast, on any server. T} @XtRPosition@T{ Same as for XtRShort. T} @XtRShort@Converts a numeric string to a short integer. @XtRTranslationTable@T{ Compiles string translation table into internal translation table format. T} @XtRUnsignedChar@Converts a string to an unsigned char. @XtRVisual@T{ Converts the strings "StaticGray", "StaticColor", "TrueColor", "GrayScale", "PseudoColor", and "DirectColor" to the corresponding visual type. T} XtRColor@XtRPixel@T{ Converts an \f(CWXColor\fP structure to a pixel value. T} XtRPixel@XtRColor@T{ Converts a pixel value to an \f(CWXColor\fP structure. T} XtRInt@XtRBoolean@Converts an \f(CWint\fP to a \f(CWBoolean\fP. @XtRBool@Converts an \f(CWint\fP to a \f(CWBool\fP. @XtRColor@Converts an \f(CWint\fP to an \f(CWXColor\fP. @XtRDimension@Converts an \f(CWint\fP to a \f(CWDimension\fP. @XtRFloat@Converts an \f(CWint\fP to a \f(CWfloat\fP. @XtRFont@Converts an \f(CWint\fP to a \f(CWFont\fP. @XtRPixel@Converts an \f(CWint\fP to a pixel value. @XtRPixmap@Converts an \f(CWint\fP to a \f(CWPixmap\fP. @XtRPosition@Converts an \f(CWint\fP to a \f(CWPosition\fP. @XtRShort@Converts an \f(CWint\fP to a \f(CWshort\fP. @XtRUnsignedChar@Converts an \f(CWint\fP to an \f(CWunsigned char\fP. .sp 5p .TE .KE .in .sp 1 .\" .rs .sp -.5 .SH "Structures" .Ps typedef struct { unsigned int size; XPointer addr; } XrmValue, *XrmValuePtr; .Pe .rs .sp -.5 .SH "See Also" .na \s-1\fIXtAppSetTypeConverter\fR\s+1\*(s1, \s-1\fIXtCallbackReleaseCacheRef\fR\s+1\*(s1, \s-1\fIXtCallConverter\fR\s+1\*(s1, \s-1\fIXtDirectConvert\fR\s+1\*(s1, \s-1\fIXtSetTypeConverter\fR\s+1\*(s1. .ad .\"last line comment .XE "XtConvertAndStore" .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtConvertArgProc" "Xt \- Resource Management" .SH "Name" .Na XtConvertArgProc \- interface definition for procedure to obtain an argument for a resource converter. .Nz .XS "XtConvertArgProc" .SH "Synopsis" .Sy typedef void (*XtConvertArgProc)(Widget, Cardinal *, XrmValue *); .As Widget \f(CIobject\fP; Cardinal *\f(CIsize\fP; XrmValue *\f(CIvalue_return\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1.2i Specifies the object for which the resource is being converted, or \f(CWNULL\fP if the converter was invoked by \f(CWXtCallConverter()\fR or \f(CWXtDirectConvert()\fR. May be of class Object or any subclass thereof. .IP \f(CIsize\fP 1.2i Specifies a pointer to the \f(CWsize\fP field from the \f(CWXtConvertArgRec\fR structure. .SS "Outputs" .IP \f(CIvalue_return\fP 1.2i Returns the address and size of the argument. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" A procedure of type \f(CWXtConvertArgProc\fP gets an argument needed when calling a resource converter. It is registered in the \f(CWaddress_id\fP field of an \f(CWXtConvertArgRec\fP structure with the \f(CWaddress_mode\fP field \f(CWXtProcedureArg\fP. This \f(CWXtConvertArgRec\fP structure must be part of an \f(CWXtConvertArgList\fP array which is registered with a converter procedure with \f(CWXtAppSetTypeConverter()\fP, \f(CWXtSetTypeConverter()\fP, or \f(CWXtAppAddConverter()\fP. .LP When invoked, the \f(CWXtConvertArgProc\fR procedure must derive its argument value (generally from the specified \f(CIobject\fP) and store the address and size of the value in the \f(CWXrmValue\fP structure pointed to by its \f(CIvalue_return\fP argument. The \f(CIsize\fP argument is not assigned any meaning by the Intrinsics, and can be used like \f(CIclient_data\fP to a callback procedure, if desired. .LP To permit re-entry, \f(CWXtConvertArgProc\fR should return the address of storage whose lifetime is no shorter than the lifetime of \f(CIobject\fR. If \f(CIobject\fP is \f(CWNULL\fR, the lifetime of the conversion argument must be no shorter than the lifetime of the resource with which the conversion argument is associated. The Intrinsics do not guarantee to copy this storage, but they do guarantee not to reference it if the resource is removed from the conversion cache. .LP If the \f(CWXtConvertArgProc\fP modifies the resource database, the changes affect any in-progress widget creation or \f(CWXtGetApplicationResources()\fP or \f(CWXtGetSubresources()\fP calls in an implementation-defined manner. Insertion of new entries into the database and modification of existing entries is allowed, however, and will not directly cause an error. .LP See \f(CWXtAppSetTypeConverter()\fP for an explanation of how to declare an \f(CWXtConvertArgList\fP which will invoke an \f(CWXtConvertArgProc\fP. .\" .SH "Example" The \f(CWXtConvertArgProc\fP used by the Intrinsics String-to-Cursor converter is shown below, along with the \f(CWXtConvertArgList\fP that registers it. It looks up the \f(CWDisplay *\fP of the specified widget, and places its address (a \f(CWDisplay **\fP) in \f(CIvalue->addr\fP. (Note that \f(CWDisplayOfScreen()\fP is a macro, so the ampersand before it is legal.) .Ps /*ARGSUSED*/ static void FetchDisplayArg(widget, size, value) Widget widget; Cardinal *size; XrmValue* value; { if (widget == NULL) XtErrorMsg("missingWidget", "fetchDisplayArg", XtCXtToolkitError, "FetchDisplayArg called without a widget to reference", (String*)NULL, (Cardinal*)NULL); /* can't return any useful Display and caller will de-ref NULL, so aborting is the only useful option */ value->size = sizeof(Display*); value->addr = (XPointer)&DisplayOfScreen(XtScreenOfObject(widget)); } static XtConvertArgRec Const displayConvertArg[] = { {XtProcedureArg, (XtPointer)FetchDisplayArg, 0}, }; .Pe The String-to-Cursor converter could now be registered with a call like the following. Given the \f(CWdisplayConvertArg\fP array defined above, that converter would be invoked with \f(CWargs[0].addr\fP, the address of the Display pointer that the converter should use. .Ps XtSetTypeConverter(XtQString, XtQCursor, CvtStringToCursor, displayConvertArg, XtNumber(displayConvertArg), XtCacheByDisplay, FreeCursor); .Pe .\" .SH "See Also" .na \s-1\fIXtAppSetTypeConverter\fR\s+1\*(s1, \s-1\fIXtAppAddConverter\fR\s+1\*(s1, \s-1\fIXtSetTypeConverter\fR\s+1\*(s1, .br \s-1\fIXtTypeConverter\fR\s+1\*(s2. .ad .XE "XtConvertArgProc" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtConvertCase" "Xt \- Keyboard Handling" .SH "Name" .Na XtConvertCase \- determine uppercase and lowercase versions of a keysym. .XX "keysyms, determining case" .XX "keysyms, XtConvertCase" .XX "XtConvertCase" .Nz .SH "Synopsis" .Sy void XtConvertCase(\f(CIdisplay\fP, \f(CIkeysym\fP, \f(CIlower_return\fP, \f(CIupper_return\fP) .As Display *\f(CIdisplay\fP; KeySym \f(CIkeysym\fP; KeySym *\f(CIlower_return\fP; KeySym *\f(CIupper_return\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1.2i Specifies the display that the keysym came from. .IP \f(CIkeysym\fP Specifies the keysym to convert. .SS "Outputs" .IP \f(CIlower_return\fP 1.2i Returns the lowercase equivalent of the keysym. .IP \f(CIupper_return\fP Returns the uppercase equivalent of the keysym. .\" .SH "Description" \f(CWXtConvertCase()\fP calls the case converter procedure most recently registered for a range of keysyms that includes \f(CIkeysym\fP to obtain uppercase and lowercase versions of the supplied keysym. .\" .SH "Usage" You will probably never need to call this function unless you are writing a customized keycode-to-keysym translator. The Translation Manager uses case converters as part of its keycode-to-keysym translation process. .LP You can register a case converter for a range of keysyms with \f(CWXtRegisterCaseConverter()\fP. .SH "See Also" .na \s-1\fIXtRegisterCaseConverter\fR\s+1\*(s1, \s-1\fIXtSetKeyTranslator\fR\s+1\*(s1, \s-1\fIXtTranslateKey\fR\s+1\*(s1, \s-1\fIXtTranslateKeycode\fR\s+1\*(s1, .br \s-1\fIXtCaseProc\fR\s+1\*(s2, \s-1\fIXtKeyProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtConvertSelectionIncrProc" "Xt \- Selections" .SH "Name" .Na XtConvertSelectionIncrProc \- interface definition for a procedure to return selection data incrementally. .Nz .XS "XtConvertSelectionIncrProc" .SH "Synopsis" .Sy typedef Boolean (*XtConvertSelectionIncrProc)(Widget, Atom*, Atom*, Atom*, XtPointer*, unsigned long*, int*, unsigned long*, XtPointer, .br XtRequestId*); .As Widget \f(CIw\fP; Atom *\f(CIselection\fP; Atom *\f(CItarget\fP; Atom *\f(CItype_return\fP; XtPointer *\f(CIvalue_return\fP; unsigned long *\f(CIlength_return\fP; int *\f(CIformat_return\fP; unsigned long *\f(CImax_length\fP; XtPointer \f(CIclient_data\fP; XtRequestId *\f(CIrequest_id\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1.2i Specifies the widget which currently owns this selection. .IP \f(CIselection\fP 1.2i Specifies the atom that names the selection requested (usually \s-1\f(CWXA_PRIMARY\fP\s0 or \s-1\f(CWXA_SECONDARY\fP\s0). .IP \f(CItarget\fP 1.2i Specifies the type of information requested about selection (\s-1FILENAME\s0, \s-1TEXT\s0, or \s-1\f(CWXA_WINDOW\fP\s0, for example). .IP \f(CImax_length\fP 1.2i Specifies the maximum number of bytes which may be transferred at any one time. .IP \f(CIclient_data\fP 1.2i Specifies the data registered with this procedure in the call to \f(CWXtOwnSelectionIncremental()\fP. .IP \f(CIrequest_id\fP 1.2i Identifies the transfer request (multiple concurrent requests are possible) for which data is to be returned. .\" .SS "Outputs" .IP \f(CItype_return\fP 1.2i Returns the property type of the converted value of the selection. (Both \s-1FILENAME\s0 and \s-1TEXT\s0 might have property type \s-1\f(CWXA_STRING\fP\s0, for example.) .IP \f(CIvalue_return\fP 1.2i Returns the address of the converted value of the selection. The selection owner is responsible for allocating this storage. .IP \f(CIlength_return\fP 1.2i Returns the length of the value in \f(CIvalue_return\fP, in units as specified by \f(CIformat_return\fP. .IP \f(CIformat_return\fP 1.2i Returns the size in bits of each of the \f(CIlength_return\fP elements of \f(CIvalue_return\fP. Must be 8, 16, or 32; this information allows the X server to byte-swap the data if necessary. .SS "Returns" \f(CWTrue\fP if the conversion is successful; \f(CWFalse\fP otherwise. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" An \f(CWXtConvertSelectionIncrProc\fP is registered in a call to \f(CWXtOwnSelectionIncremental()\fP. This procedure is called repeatedly by the Intrinsics selection mechanism to get pieces of the selection value. .LP On the first call with a particular \f(CIrequest_id\fP, an \f(CWXtConvertSelectionIncrProc\fP should determine whether it will be able to convert the selection to the requested target type. If not, it should return \f(CWFalse\fP immediately. Otherwise, it should allocate memory (of not more than \f(CImax_length\fP bytes) and place the first "chunk" or increment of the converted selection value in it. Then it should set \f(CIvalue_return\fP to the address of this allocated memory, and set \f(CItype_return\fP, \f(CIlength_return\fP, and \f(CIformat_return\fP as appropriate and return True. .LP On subsequent calls with the same \f(CIrequest_id\fP, an \f(CWXtConvertSelectionIncrProc()\fP should return the converted subsequent chunks of the selection value, again setting all the return arguments and returning \f(CWTrue\fP. It may reuse the previously allocated block of memory. .LP When an \f(CWXtConvertSelectionIncrProc\fP is called after it has transferred the last of the selection data, it should store a non-\f(CWNULL\fP value in \f(CIvalue_return\fP and zero in \f(CIlength_return\fP to indicate that the entire selection has been delivered. After returning this final segment, the \f(CIrequest_id\fP may be re-used by the Intrinsics to begin a new transfer. .LP If an \f(CWXtSelectionDoneIncrProc\fP proc was registered with the \f(CWXtConvertSelectionIncrProc\fP, then that procedure is responsible for freeing any memory allocated for a transfer when that transfer completes. If no \f(CWXtSelectionDoneIncrProc\fP is registered, the Intrinsics will automatically call \f(CWXtFree()\fP on the final value returned. If an incremental transfer is aborted before it completes, the \f(CWXtCancelConvertSelectionProc\fP is responsible for freeing any memory allocated for that transfer. .LP Each \f(CWXtConvertSelectionProc\fR should respond to target value \f(CWTARGETS\fR by returning a value containing the list of the targets they are prepared to convert their selection into. The list of targets should be an array of interned Atoms, and \f(CWreturn_type\fR should be \f(CWXA_ATOM\fR. .LP An \f(CWXtConvertSelectionIncrProc\fP will not be called with a \f(CItarget\fP of MULTIPLE or TIMESTAMP (see Section 2.6.2 of the \fIInter-Client Communications Conventions Manual\fP, Appendix L in Volume Zero). The Intrinsics automatically break a MULTIPLE request into a series of calls to the procedure, and automatically respond to a TIMESTAMP request using the time passed to \f(CWXtOwnSelectionIncremental()\fP. .LP See \f(CWXtConvertSelectionProc\fP(2) for more information on handling requests for the selection value. .\" .Nd 5 .SH "Usage" An \f(CWXtConvertSelectionIncrProc\fP must be prepared to handle multiple concurrent transfer requests; i.e., it cannot assume that it will be called repeatedly with a single \f(CIrequest_id\fP until that transfer is complete, and then be called with a new \f(CIrequest_id\fP. For this reason, it must remember how far along in each transfer it is for each \f(CIrequest_id\fP. The Xlib Context Manager (see \f(CWXSaveContext()\fP) can be useful for this purpose. .SH "See Also" .na \s-1\fIXtGetSelectionValueIncremental\fR\s+1\*(s1, \s-1\fIXtGetSelectionValuesIncremental\fR\s+1\*(s1, .hw XtOwnSelection-Incremental \s-1\fIXtOwnSelectionIncremental\fR\s+1\*(s1, .br \s-1\fIXtCancelConvertSelectionProc\fR\s+1\*(s2, \s-1\fIXtConvertSelectionProc\fR\s+1\*(s2, \s-1\fIXtLoseSelectionIncrProc\fR\s+1\*(s2, \s-1\fIXtSelectionDoneIncrProc\fR\s+1\*(s2. .ad .XE "XtConvertSelectionIncrProc" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtConvertSelectionProc" "Xt \- Selections" .SH "Name" .Na XtConvertSelectionProc \- interface definition for a procedure to return requested selection data. .Nz .XS "XtConvertSelectionProc" .XS "selections: data; XtConvertSelectionProc" .SH "Synopsis" .Sy typedef Boolean (*XtConvertSelectionProc)(Widget, Atom *, Atom *, Atom *, XtPointer *, unsigned long *, int *); .As Widget \f(CIw\fP; Atom *\f(CIselection\fP; Atom *\f(CItarget\fP; Atom *\f(CItype_return\fP; XtPointer *\f(CIvalue_return\fP; unsigned long *\f(CIlength_return\fP; int *\f(CIformat_return\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1.2i Specifies the widget that currently owns the selection. .IP \f(CIselection\fP Specifies the atom that describes the selection requested (usually \s-1\f(CWXA_PRIMARY\fP\s0 or \s-1\f(CWXA_SECONDARY\fP\s0). .IP \f(CItarget\fP Specifies the type of information requested about the selection (\s-1FILENAME\s0, \s-1TEXT\s0, or \s-1\f(CWXA_WINDOW\fP\s0, for example). .SS "Outputs" .IP \f(CItype_return\fP 1.2i Returns the property type of the converted value of the selection. (Both \s-1FILENAME\s0 and \s-1TEXT\s0 might have property type \s-1\f(CWXA_STRING\fP\s0, for example.) .IP \f(CIvalue_return\fP 1.2i Returns the address of the converted value of the selection. The selection owner is responsible for allocating this storage. .IP \f(CIlength_return\fP 1.2i Returns the length of the value in \f(CIvalue_return\fP, in units as specified by \f(CIformat_return\fP. .IP \f(CIformat_return\fP 1.2i Returns the size in bits of each of the \f(CIlength_return\fP elements of \f(CIvalue_return\fP. Must be 8, 16, or 32; this information allows the X server to byte-swap the data if necessary. .SS "Returns" \f(CWTrue\fP if the conversion is successful; \f(CWFalse\fP otherwise. .\" .SH "Description" An \f(CWXtConvertSelectionProc\fP is registered in a call to \f(CWXtOwnSelection()\fP when a client requests to become the owner of a selection. It is called when the value of the selection is requested. .LP If an \f(CWXtConvertSelectionProc\fP cannot convert the selection data to the requested \f(CItarget\fP type, it should return \f(CWFalse\fP. Otherwise, it should convert the value, allocating memory for it if necessary. It should store the type of the converted data (which is generally not the same as \f(CItarget\fP) in \f(CItype_return\fP, store the address of the converted value in \f(CIvalue_return\fP, .ne 2 store the number of blocks of converted data in \f(CIlength_return\fP, store the size of each of those blocks of converted data in \f(CIformat_return\fP, and return \f(CWTrue\fP. .LP If an \f(CWXtSelectionDoneProc\fP was registered with the \f(CWXtConvertSelectionProc\fP, then this procedure will be called when the requestor has copied the converted data, and should free any memory allocated for that data. If no \f(CWXtSelectionDoneProc\fP was registered, then the Intrinsics will automatically free the returned value by calling \f(CWXtFree()\fP. .LP Each \f(CWXtConvertSelectionProc\fR should respond to target value \f(CWTARGETS\fR by returning a value containing the list of the targets they are prepared to convert their selection into. The list of targets should be an array of interned Atoms, and \f(CItype_return\fP should be \f(CWXA_ATOM\fR. .LP An \f(CWXtConvertSelectionProc\fP will not be called with a \f(CItarget\fP of MULTIPLE or TIME\p STAMP (see Section 2.6.2 of the \fIInter-Client Communications Conventions Manual\fP, Appendix L in Volume Zero). The Intrinsics automatically break a MULTIPLE request into a series of calls to the procedure, and automatically respond to a TIMESTAMP request using the time passed to \f(CWXtOwnSelection()\fP. .\" .SH "Usage" Most widgets that display data of any sort should make that data selectable by the user, and should call \f(CWXtOwnSelection()\fP with an \f(CWXtConvertSelectionProc\fP when data is selected by the user. .LP Although it is usually widgets that handle selections, there are times when an application might want to export selected data. A calculator program might have a menu item labeled "Cut", for example, which would call \f(CWXtOwnSelection()\fP to make the currently displayed value available for pasting. (It would probably also have a "Paste" command that would call \f(CWXtGetSelectionValue()\fP to obtain the currently selected value and use it, if it is a number.) .LP An \f(CWXtConvertSelectionProc\fP transfers the selection value in a single block, and relies on the Intrinsics to break that block up and reassemble it as necessary if it is larger than the maximum size for a single transfer to the X server. This procedure and the \f(CWXtOwnSelection()\fP function that registers it are part of the Intrinsics atomic selection transfer mechanism. In Release 4 and later, the Intrinsics also support an incremental transfer mechanism which allows the selection owner to return the selection value a piece at a time. If there is a large amount of selected data, the incremental interface means that it does not have to be copied all at once\-on systems with limited memory, this can be important. Also, some selections, such as disjoint pieces of text in a text widget, are more naturally transferred in separate pieces. See \f(CWXtOwnSelectionIncremental\fP(1) and \f(CWXtConvertSelectionIncrProc\fP(2) for more information. .LP The Xmu function \f(CWXmuConvertStandardSelection()\fP converts the selection to the following standard targets: CLASS, CLIENT_WINDOW, DECNET_ADDRESS, HOSTNAME, IP_ADDRESS, NAME, OWNER_OS, TARGETS, TIMESTAMP, and USER. It is used in the example shown below. See Section 2.6.5 of the \fIInter-Client Communications Conventions Manual\fP for the meaning of these standard targets. See \f(CWXmuConvertStandardSelection\fP(6) for more information. .LP When working with selections, you will have to work with Atoms. Many standard Atoms are defined in <\fIX11/Xatom.h\fP>. Those that are not (for example, \f(CWTARGETS\fR) may be interned explicitly as Atoms by calling the Xlib function \f(CWXInternAtom()\fR. The Xmu library provides an alternate function, \f(CWXmuInternAtom()\fP, which caches Atoms on the client side. Additionally, the header \fI\fP defines a number of macros, such as \f(CWXA_TARGETS(dpy)\fP, which call \f(CWXmuInternAtom()\fP and take a Display pointer as their single argument. .\" .SH "Example" The example \f(CWXtConvertSelectionProc\fP below is from the client \f(CIxclipboard\fP. It can be easily adapted for use by most widgets and applications. Note the use of predefined Atoms and the Xmu Atom macros. \f(CWXmuConvertStandardSelection()\fP is used to convert to the standard target types, and also (when the target is TARGETS) to return a list of those standard types that it supports. This list is then augmented with the types supported explicitly by the procedure. .XX "selections: converting; standard selections" .XX "selections: converting; example" .XX "Xmu library: XmuConvertStandardSelection" .Ps \s-2#include #include #include static Boolean ConvertSelection(w, selection, target, type, value, length, format) Widget w; Atom *selection, *target, *type; XtPointer *value; unsigned long *length; int *format; { Display* d = XtDisplay(w); XSelectionRequestEvent* req = XtGetSelectionRequest(w, *selection, (XtRequestId)NULL); if (*target == XA_TARGETS(d)) { Atom* targetP; Atom* std_targets; unsigned long std_length; XmuConvertStandardSelection(w, req->time, selection, target, type, (caddr_t*)&std_targets, &std_length, format); *value = XtMalloc(sizeof(Atom)*(std_length + 5)); targetP = *(Atom**)value; *targetP++ = XA_STRING; *targetP++ = XA_TEXT(d); *targetP++ = XA_LENGTH(d); *targetP++ = XA_LIST_LENGTH(d); *targetP++ = XA_CHARACTER_POSITION(d); *length = std_length + (targetP - (*(Atom **) value)); bcopy((char*)std_targets, (char*)targetP, sizeof(Atom)*std_length); XtFree((char*)std_targets); *type = XA_ATOM; *format = 32; return True; } if (*target == XA_LIST_LENGTH(d) *target == XA_LENGTH(d)) { long * temp; temp = (long *) XtMalloc(sizeof(long)); if (*target == XA_LIST_LENGTH(d)) *temp = 1L; else /* *target == XA_LENGTH(d) */ *temp = (long) TextLength (text); *value = (caddr_t) temp; *type = XA_INTEGER; *length = 1L; *format = 32; return True; } if (*target == XA_CHARACTER_POSITION(d)) { long * temp; temp = (long *) XtMalloc(2 * sizeof(long)); temp[0] = (long) 0; temp[1] = TextLength (text); *value = (caddr_t) temp; *type = XA_SPAN(d); *length = 2L; *format = 32; return True; } if (*target == XA_STRING *target == XA_TEXT(d) *target == XA_COMPOUND_TEXT(d)) { extern char *_XawTextGetSTRING(); if (*target == XA_COMPOUND_TEXT(d)) *type = *target; else *type = XA_STRING; *length = TextLength (text); *value = _XawTextGetSTRING((TextWidget) text, 0, *length); *format = 8; return True; } if (XmuConvertStandardSelection(w, req->time, selection, target, type, (caddr_t *)value, length, format)) return True; return False; }\s+2 .Pe .XE "XtConvertSelectionProc" .XE "selections: data; XtConvertSelectionProc" .SH "See Also" .na \s-1\fIXtGetSelectionValue\fR\s+1\*(s1, \s-1\fIXtOwnSelection\fR\s+1\*(s1, .br \s-1\fIXtConvertSelectionIncrProc\fR\s+1\*(s2, \s-1\fIXtSelectionDoneProc\fR\s+1\*(s2, .br \s-1\fIXmuConvertStandardSelection\fR\s+1\*(s6. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtConvertSe 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtConvertSelectionIncrProc@XtConvertSA .sp .5 XtConvertSelectionProc@XtConvertSB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCreateApplicationContext" "Xt \- Application Contexts" .SH "Name" .Na XtCreateApplicationContext \- create an application context. .XS "application contexts, creating" .XS "XtCreateApplicationContext" .Nz .SH "Synopsis" .Sy XtAppContext XtCreateApplicationContext() .As .Ae .\".SS "Inputs" .SH "Description" \f(CWXtCreateApplicationContext()\fP creates and returns an application context, which is an opaque type. Every application must have at least one application context. .\" .SH "Usage" \f(CWXtAppInitialize()\fP calls \f(CWXtCreateApplicationContext()\fP as part of its initialization sequence, so you should not often need to use this function. .LP The superseded routines that use an implicit context (like \f(CWXtMainLoop()\fP and \f(CWXtAddTimeOut()\fP) depend on a default context created by \f(CWXtInitialize()\fP. You cannot use these routines if you initialize a specific application context. .\" .SH "See Also" .na \s-1\fIXtAppInitialize\fR\s+1\*(s1. .ad .XE "application contexts, creating" .XE "XtCreateApplicationContext" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCreateApplicationShell" "Xt \- Initialization" .SH "Name" .Na XtCreateApplicationShell \- create an additional top-level widget. .XX "widgets: creating; additional top-level" .XN "widgets: creating; (see also XtCreateApplicationShell)" .XX "XtCreateApplicationShell" .LP .Nz .SH "Synopsis" .Sy Widget XtCreateApplicationShell(\f(CIapplication_name\fP, \f(CIwidget_class\fP, \f(CIargs\fP, \f(CInum_args\fP) .As String \f(CIapplication_name\fP; /*unused*/ WidgetClass \f(CIwidget_class\fP; ArgList \f(CIargs\fP; Cardinal \f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIapplication_name\fP 1i This argument is unused. .IP \f(CIwidget_class\fP 1i Specifies the widget class for the shell widget to be created. .IP \f(CIargs\fP 1i Specifies an argument list to override any other resource specifications. .IP \f(CInum_args\fP 1i Specifies the number of elements in \f(CIargs\fP. .SS "Returns" A newly created shell widget of class \f(CIwidget_class\fP. .\" .SH "Availability" Superseded by \f(CWXtAppCreateShell()\fP. .\" .SH "Description" \f(CWXtCreateApplicationShell()\fP creates and returns a shell widget of class \f(CIwidget_class\fP. The created widget has no parent\-it is at the root of a widget tree and at the top of the resource name hierarchy. .LP \f(CWXtCreateApplicationShell()\fP creates the widget by calling \f(CWXtAppCreateShell()\fP passing a \f(CWNULL\fP \f(CIapplication_name\fP, the \f(CIapplication_class\fP that was passed to \f(CWXtInitialize()\fP, the display that was opened by \f(CWXtInitialize()\fP and the \f(CIwidget_class\fP, \f(CIargs\fP, and \f(CInum_args\fP arguments. .\" .SH "Usage" \f(CWXtCreateApplicationShell()\fP has been superseded by \f(CWXtAppCreateShell()\fP, which is substantially more flexible. You can continue to use \f(CWXtCreateApplicationShell()\fP only if you initialize your application with \f(CWXtInitialize()\fP. We recommend that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppCreateShell()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppCreateShell()\fP for more information. .SH "See Also" .na \s-1\fIXtAppCreateShell\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtCreateApp 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtCreateApplicationContext@XtCreateApA .sp .5 XtCreateApplicationShell@XtCreateApB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCreateManagedWidget" "Xt \- Widget Lifecycle" .SH "Name" .Na XtCreateManagedWidget \- create and manage a child widget. .XX "widgets: child widget; creating/managing" .XN "widgets: creating; (see also XtCreateMgdWidget)" .XX "XtCreateManagedWidget" .SH "Synopsis" .Sy Widget XtCreateManagedWidget(\f(CIname\fP, \f(CIwidget_class\fP, \f(CIparent\fP, \f(CIargs\fP, \f(CInum_args\fP) .As String \f(CIname\fP; WidgetClass \f(CIwidget_class\fP; Widget \f(CIparent\fP; ArgList \f(CIargs\fP; Cardinal \f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIname\fP 1.2i Specifies the resource name for the created widget. .IP \f(CIwidget_class\fP Specifies the widget class pointer for the created widget; must be rectObjClass or any subclass. .IP \f(CIparent\fP Specifies the parent widget; must be of class Composite or any subclass thereof. .IP \f(CIargs\fP Specifies the argument list to override the resource defaults. .IP \f(CInum_args\fP Specifies the number of arguments in the argument list. .SS "Returns" The newly created and managed child widget. .\" .SH "Description" \f(CWXtCreateManagedWidget()\fP creates a widget by passing all of its arguments to \f(CWXtCreateWidget()\fP, and then calling \f(CWXtManageChild()\fP on the resulting widget. It returns the created and managed widget. .\" .SH "Usage" You can use \f(CWXtVaCreateManagedWidget()\fP to do the same thing, except that resource names and values are passed in a variable length argument list, rather than an \f(CWArgList\fP. .LP If you are creating a number of children of an already realized parent, it is more efficient to create them and then manage them all in a single call to \f(CWXtManageChildren()\fP. .\" .SH "See Also" .na \s-1\fIXtCreateWidget\fR\s+1\*(s1, \s-1\fIXtManageChild\fR\s+1\*(s1, \s-1\fIXtManageChildren\fR\s+1\*(s1, \s-1\fIXtVaCreateManagedWidget\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCreatePopupChildProc" "Xt \- Pop Ups" .SH "Name" .Na XtCreatePopupChildProc \- interface definition for an \f(CWXtNcreatePopupChildProc\fP .br procedure. .Nz .XX "XtCreatePopupChildProc" .SH "Synopsis" .Sy typedef void (*XtCreatePopupChildProc)(Widget); .As Widget \f(CIshell\fP; .Ae .SS "Inputs" .IP \f(CIshell\fP 1i Specifies the shell which is being popped up. .\" .SH "Description" An \f(CWXtCreatePopupChildProc\fP is registered as the value of the \f(CWXtNcreatePopupChildProc\fP resource of a shell widget. It will be called by \f(CWXtPopup()\fP just before the shell is popped up, and is intended to provide an opportunity for the application to create the popup child of the shell. See \f(CWXtPopup\fP(1) and \f(CWShell\fP(3) for more information. .SH "Usage" None of the standard MIT clients make use of the \f(CWXtNcreatePopupChildProc\fP resource, and most applications will probably find it simpler to either create both popup shell and popup child in advance, or to delay creation of both until just before \f(CWXtPopup()\fP is called. Note that \f(CWXtPopup()\fP also calls the procedures on a shell's \f(CWXtNpopupCallback\fP list, and a callback on this list can be used for the same purpose as an \f(CWXtNcreatePopupChildProc\fP. .LP Note that an \f(CWXtNcreatePopupChildProc\fP procedure is not a widget class method. It could be considered an "instance method" rather than a "class method." In this way it is similar to the \f(CWXtNinsertPosition\fP procedure of the Composite widget class. .\" .SH "See Also" .na \s-1\fIXtPopup\fR\s+1\*(s1, .br \s-1\fIShell\fR\s+1\*(s3. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCreatePopupShell" "Xt \- Pop Ups" .SH "Name" .Na XtCreatePopupShell \- create a popup shell widget. .XS "popups: creating" .XN "popups: (see also XtCreatePopupShell)" .Nz .XS "XtCreatePopupShell" .SH "Synopsis" .Sy Widget XtCreatePopupShell(\f(CIname\fP, \f(CIwidget_class\fP, \f(CIparent\fP, \f(CIargs\fP, \f(CInum_args\fP) .As String \f(CIname\fP; WidgetClass \f(CIwidget_class\fP; Widget \f(CIparent\fP; ArgList \f(CIargs\fP; Cardinal \f(CInum_args\fP; .Ae .SS "Inputs" .ds Sh shell .IP \f(CIname\fP 1.2i Specifies the resource name for the created shell widget. .IP \f(CIwidget_class\fP Specifies the widget class pointer for the created shell widget; must be shellClass or any subclass. .IP \f(CIparent\fP Specifies the parent widget; must be of class Core or any subclass thereof. .IP \f(CIargs\fP Specifies the argument list to override the resource defaults. .IP \f(CInum_args\fP Specifies the number of arguments in the argument list. .SS "Returns" A widget of class \f(CIwidget_class\fP created as a popup child of \f(CIparent\fP. .\" .SH "Description" \f(CWXtCreatePopupShell()\fP checks that \f(CIwidget_class\fP is a subclass of Shell, and, if it is, creates a widget of that class. The widget is not stored in the \f(CWchildren\fP array (maintained by Composite widgets), but rather in the \f(CWpopup_list\fP array (which all widgets have). .LP The screen resource for this widget is determined by first scanning \f(CIargs\fP for the \f(CWXtNscreen\fP resource. If it is not found, the resource database associated with the parent's screen is queried. If both queries fail, the parent's screen is used. Once the screen is determined, the resource database associated with that screen is used to retrieve all remaining resources for the widget not specified in \f(CIargs\fP. .\" .SH "Usage" All shell widgets other than those created by \f(CWXtAppInitialize()\fP and \f(CWXtAppCreateShell()\fP must be created with \f(CWXtCreatePopupShell()\fP. Popup shells can be a child of any widget, not just Composite widgets. Remember that shell widgets can only have a single child, which will generally be the layout widget that arranges whatever grandchildren widgets are to appear in the popup. .LP Creating and realizing a popup shell widget is not enough to make it visible. To make a shell pop up, use \f(CWXtPopup()\fP or one of the predefined callback procedures or menu actions that call this function. To make it popdown, call \f(CWXtPopdown()\fP. .LP Rather than initializing an \f(CWArgList\fP to pass to \f(CWXtCreatePopupShell()\fP, you can call \f(CWXtVaCreatePopupShell()\fP which accepts a \f(CWNULL\fP-terminated variable length argument list of resource names and resource values. .\" .SH "See Also" .na \s-1\fIXtCallbackExclusive\fR\s+1\*(s1, \s-1\fIXtMenuPopup\fR\s+1\*(s1, \s-1\fIXtPopdown\fR\s+1\*(s1, \s-1\fIXtPopup\fR\s+1\*(s1, \s-1\fIXtVaCreatePopupShell\fR\s+1\*(s1. .ad .XE "popups: creating" .XE "XtCreatePopupShell" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtConvertSe 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtCreatePopupChildProc@XtCreatePoA .sp .5 XtCreatePopupShell@XtCreatePoB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCreateWidget" "Xt \- Widget Lifecycle" .SH "Name" .Na XtCreateWidget \- create an instance of a widget. .XS "widgets, creating" .XN "widgets: creating; (see also XtCreateWidget)" .Nz .XS "XtCreateWidget" .SH "Synopsis" .Sy Widget XtCreateWidget(\f(CIname\fP, \f(CIobject_class\fP, \f(CIparent\fP, \f(CIargs\fP, \f(CInum_args\fP) .As String \f(CIname\fP; WidgetClass \f(CIobject_class\fP; Widget \f(CIparent\fP; ArgList \f(CIargs\fP; Cardinal \f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIname\fP 1i Specifies the resource name for the created object. .IP \f(CIobject_class\fP 1i Specifies the widget class pointer for the created widget; may be objectClass or any subclass. .IP \f(CIparent\fP 1i Specifies the parent widget; may be of class objectClass or any subclass thereof. .IP \f(CIargs\fP 1i Specifies the argument list to override the resource defaults. .IP \f(CInum_args\fP 1i Specifies the number of arguments in the argument list. .SS "Returns" An child widget or object of \f(CIparent\fP of class \f(CIobject_class\fP. .\" .SH "Description" \f(CWXtCreateWidget()\fR creates a new instance of class \f(CIobject_class\fP named \f(CIname\fP, as a child of \f(CIparent\fP. The resource name/resource value pairs in \f(CIargs\fP are used to set resources in the widget and override resources from the resource database. The details of the widget creation procedure are explained in the "Algorithm" section below. .\" .SH "Usage" A created widget will not be visible until it is managed. You can manage a child widget with \f(CWXtManageChild()\fP, and you can combine the call to \f(CWXtCreateWidget()\fP and \f(CWXtManageChild()\fP by calling \f(CWXtCreateManagedWidget()\fP. Note that you cannot manage direct subclasses of Object. .LP A created and managed widget will not be visible unless it has been realized (i.e., had an X window created). You realize a widget by calling \f(CWXtRealizeWidget()\fP, which realizes the specified widget and all of its children. If you create a child of a realized widget, the child is automatically realized. You will generally call \f(CWXtRealizeWidget()\fP once in an application, just before entering your main event loop. .LP Rather than initialize an \f(CWArgList\fP and pass it to \f(CWXtCreateWidget()\fP, you can call \f(CWXtVaCreateWidget()\fP or \f(CWXtVaCreateManagedWidget()\fP which both accept a \f(CWNULL\fP-terminated variable length argument list of resource names and resource values. .LP To create a popup widget, you must use \f(CWXtCreatePopupShell()\fP rather than \f(CWXtCreateWidget()\fP. .LP You may give your widgets any \f(CIname\fP you want, and may give multiple widgets the same name. If two sibling widgets have the same name, however, they will get the same resources from the resource database, and it is undefined which will be returned by a call to \f(CWXtNameToWidget()\fP. .LP \f(CWXtCreateWidget()\fP allows you to create child widgets of non-Composite widgets. If you do this, the child widget will not appear on any \f(CWchildren\fP list in the parent and will not be automatically realized when its parent is realized or destroyed when its parent is destroyed. The only time you should do this is when writing a non-Composite widget that explicitly creates and manages its own children. .\" .SH "Algorithm" \f(CWXtCreateWidget()\fP does the following when creating a widget or an object: .IP \(bu 3n Checks to see if the \f(CWclass_initialize()\fP method has been called for this class and for all superclasses and, if not, calls those necessary in a superclass-to-subclass order. .IP \(bu 3n If the specified class is not \f(CWcoreWidgetClass\fP or a subclass thereof, and the parent's class is a subclass of \f(CWcompositeWidgetClass\fP and either no extension record in the parent's composite class part extension field exists with the \f(CWrecord_type\fP \f(CWNULLQUARK\fP or the \f(CWaccepts_objects\fP field in the extension record is \f(CWFalse\fP, \f(CWXtCreateWidget()\fP issues a fatal error. .IP \(bu 3n Allocates memory for the widget instance. .IP \(bu 3n If the parent is a member of the class \f(CWconstraintWidgetClass\fP, allocates memory for the parent's constraints and stores the address of this memory into the \f(CWconstraints\fP field. .IP \(bu 3n Initializes the Core nonresource data fields (for example, \f(CWparent\fP and \f(CWvisible\fP). .IP \(bu 3n Initializes the resource fields (for example, \f(CWbackground_pixel\fP) by using the \f(CWCoreClassPart\fP resource lists specified for this class and all superclasses. .IP \(bu 3n If the parent is a member of the class \f(CWconstraintWidgetClass\fP, initializes the resource fields of the constraints record by using the \f(CWConstraintClassPart\fP resource lists specified for the parent's class and all superclasses up to \f(CWconstraintWidgetClass\fP. .IP \(bu 3n Calls the \f(CWinitialize()\fP methods for the widget in superclass-to-subclass order. .IP \(bu 3n If the parent is a member of the class \f(CWcompositeWidgetClass\fP, puts the widget into its parent's children list by calling its parent's \f(CWinsert_child()\fP method. .IP \(bu 3n If the parent is a member of the class \f(CWconstraintWidgetClass\fP, calls the \f(CWConstraintClassPart\fP \f(CWinitialize()\fP methods, in superclass-to-subclass order. .LP \f(CWXtCreateWidget()\fP converts and caches resources in a way equivalent to \f(CWXtConvertAndStore()\fP when initializing the object instance. Because there is extra memory overhead required to implement reference counting, clients may distinguish those objects that are never destroyed before the application exits from those that may be destroyed and whose resources should be deallocated. .LP To specify whether reference counting is to be enabled for the resources of a particular object when the object is created, the client can specify a value for the \f(CWBoolean\fP resource \f(CWXtNinitialResourcesPersistent\fP, .XX "XtNinitialResourcesPersistent" class \f(CWXtCInitialResourcesPersistent.\fP .LP When \f(CWXtCreateWidget()\fP is called, if this resource is not specified as \f(CWFalse\fP in either the arglist or the resource database, then the resources referenced by this object are not reference-counted, regardless of how the type converter may have been registered. The effective default value is \f(CWTrue\fP; thus clients that expect to destroy one or more objects and want resources deallocated must explicitly specify \f(CWFalse\fP for \f(CWXtNinitialResourcesPersistent\fP .LP The resources are still freed and destructors called when \f(CWXtCloseDisplay()\fP is called if the conversion was registered as \f(CWXtCacheByDisplay\fP. .\" .SH "See Also" .na \s-1\fIXtCreateManagedWidget\fR\s+1\*(s1, \s-1\fIXtVaCreateWidget\fR\s+1\*(s1, \s-1\fIXtVaCreateManagedWidget\fR\s+1\*(s1. .ad .XE "widgets, creating" .XE "XtCreateWidget" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtCreateWindow" "Xt \- Window Manipulation" .SH "Name" .Na XtCreateWindow \- create widget's window. .XS "widgets: creating; window" .XS "window, creating" .Nz .XS "XtCreateWindow" .SH "Synopsis" .Sy .hw attributes void XtCreateWindow(\f(CIw\fP, \f(CIwindow_class\fP, \f(CIvisual\fP, \f(CIvalue_mask\fP, \f(CIattributes\fP) .As Widget \f(CIw\fP; unsigned int \f(CIwindow_class\fP; Visual *\f(CIvisual\fP; XtValueMask \f(CIvalue_mask\fP; XSetWindowAttributes *\f(CIattributes\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1.2i Specifies the widget that is to have a window created; must be of class Core or a subclass thereof. .IP \f(CIwindow_class\fP 1.2i Specifies the Xlib window class (\f(CWInputOutput\fR, \f(CWInputOnly\fR, or \f(CWCopyFromParent\fR). .IP \f(CIvisual\fP 1.2i Specifies the Xlib visual type (usually \f(CWCopyFromParent\fR). .IP \f(CIvalue_mask\fP 1.2i Specifies which attribute fields to use. .IP \f(CIattributes\fP 1.2i Specifies the window attributes to use in the \f(CWXCreateWindow()\fR call. .SH "Description" \f(CWXtCreateWindow()\fP copies the \f(CWdepth\fP, \f(CWscreen\fP, \f(CWx\fP, \f(CWy\fP, \f(CWwidth\fP, \f(CWheight\fP and \f(CWborder_width\fP fields of the core part of the specified widget into the \f(CIattributes\fP structure. Then it passes \f(CIattributes\fP and an appropriately modified \f(CIvalue_mask\fP along with the widget's display, the widget's parent's window, \f(CIwindow_class\fP, and \f(CIvisual\fP to the Xlib function \f(CWXCreateWindow()\fP. It stores the newly created \f(CWWindow\fP in the widget's core part \f(CWwindow\fP field. .\" .SH "Usage" This is a convenience function intended for use in the \f(CWrealize()\fP method of widgets. It should never be called by an application. .\" .SH "Structures" The \f(CWXSetWindowAttributes\fP structure is as follows: .Ps .ta 4n 2.28i .ps 8 .vs 10 typedef struct { Pixmap background_pixmap; /* background or None or ParentRelative * / unsigned long background_pixel; /* background pixel */ Pixmap border_pixmap; /* border of the window */ unsigned long border_pixel; /* border pixel value */ int bit_gravity; /* one of bit gravity values */ int win_gravity; /* one of the window gravity values */ int backing_store; /* NotUseful, WhenMapped, Always */ unsigned long backing_planes; /* planes to be preserved if possible */ unsigned long backing_pixel; /* value to use in restoring planes */ Bool save_under; /* should bits under be saved (popups) */ long event_mask; /* set of events that should be saved */ long do_not_propagate_mask; /* set of events that should not propagate */ Bool override_redirect; /* boolean value for override-redirect */ Colormap colormap; /* colormap to be associated with window */ Cursor cursor; /* cursor to be displayed (or None) */ } XSetWindowAttributes; /* Definitions for valuemask argument. These control which fields in * XSetWindowAttributes structure should be used. */ #define CWBackPixmap (1L<<0) #define CWBackPixel (1L<<1) #define CWBorderPixmap (1L<<2) #define CWBorderPixel (1L<<3) #define CWBitGravity (1L<<4) #define CWWinGravity (1L<<5) #define CWBackingStore (1L<<6) #define CWBackingPlanes (1L<<7) #define CWBackingPixel (1L<<8) #define CWOverrideRedirect (1L<<9) #define CWSaveUnder (1L<<10) #define CWEventMask (1L<<11) #define CWDontPropagate (1L<<12) #define CWColormap (1L<<13) #define CWCursor (1L<<14) .ps .vs .Pe .SH "See Also" .na \s-1\fIrealize\fR\s+1\*(s4. .ad .XE "widgets: creating; window" .XE "window, creating" .XE "XtCreateWindow" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtDatabase" "Xt \- Resource Management" .SH "Name" .Na XtDatabase \- obtain the resource database for a display. .XX "resources: database; obtaining" .XX "database: obtaining for display" .XN "database: (see also XtDatabase)" .Nz .XX "XtDatabase" .SH "Synopsis" .Sy XrmDatabase XtDatabase(\f(CIdisplay\fP) .As Display *\f(CIdisplay\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the display for which the resource database should be returned. .SS "Returns" The database for the specified display, or \f(CWNULL\fP. .SH "Description" In Release 4 and previous releases, \f(CWXtDatabase()\fP returns the resource database built by \f(CWXtDisplayInitialize()\fP for the display. In Release 5, which supports a resource database for each screen, \f(CWXtDatabase()\fP returns the resource database built by \f(CWXtDisplayInitialize()\fP for the default screen of the display. .LP In Release 4 and previous releases, the results are undefined if \f(CIdisplay\fP has not been initialized by \f(CWXtDisplayInitialize()\fP. In Release 5, \f(CWXtDatabase()\fP returns \f(CWNULL\fP if no database has been set for the display. .SH "Usage" In Release 5, the function \f(CWXtScreenDatabase()\fP returns the resource associated with a specified screen. .LP You should rarely need to obtain the database of a display or screen. \f(CWXtGetApplicationResources()\fP and related functions provide a more manageable approach to obtaining resource values. .\" .SH "Structures" \f(CWXrmDatabase\fP is an opaque data type. .SH "See Also" .na \s-1\fIXtAppInitialize\fR\s+1\*(s1, \s-1\fIXtDisplayInitialize\fR\s+1\*(s1, \s-1\fIXtScreenDatabase\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtDestroyApplicationContext" "Xt \- Application Contexts" .SH "Name" .Na XtDestroyApplicationContext \- destroy an application context and close its displays. .XX "application contexts, destroying and closing displays" .\".XX "application contexts, XtDestroyApplicationContextzzz" .Nz .XX "XtDestroyApplicationContext" .SH "Synopsis" .Sy void XtDestroyApplicationContext(\f(CIapp_context\fP) .As XtAppContext \f(CIapp_context\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .SH "Description" \f(CWXtDestroyApplicationContext()\fR destroys the specified application context and closes any display connections in it as soon as it is safe to do so. If called from within an event handler or a callback procedure, \f(CWXtDestroyApplicationContext()\fR does not destroy the application context until the dispatch is complete. .SH "Usage" X Toolkit applications need not call \f(CWXtDestroyApplicationContext()\fR unless they use multiple application contexts and want to destroy one. Most applications can exit using the standard method for their operating system (typically, by calling \f(CWexit\fR for \s-1POSIX\s+1-based systems). The quickest way to make the windows disappear while exiting is to call \f(CWXtUnmapWidget()\fR on each top-level shell widget. The X Toolkit has no resources beyond those in the program image, and the X server will free its resources when its connection to the application is broken. .SH "See Also" .na \s-1\fIXtCreateApplicationContext\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtDestroyGC" "Xt \- Graphics Context" .SH "Name" .Na XtDestroyGC \- Release 2 compatible function to free read-only GCs. .XX "graphics contexts, freeing" .XX "graphics contexts, destroying" .XN "graphics contexts: (see also XtDestroyGC)" '.Nz .XX "XtDestroyGC" .SH "Synopsis" .Sy void XtDestroyGC(w, \f(CIgc\fP) .As Widget \f(CIw\fP; GC \f(CIgc\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies any object on the display for which the GC was created. .IP \f(CIgc\fP 1i Specifies the GC to be deallocated. .SH "Availability" \f(CWXtDestroyGC()\fP is superseded by \f(CWXtReleaseGC()\fP. .SH "Description" \f(CWXtDestroyGC()\fP deallocates a shared (read-only) Graphics Context. References to sharable GCs are counted, and a free request is generated to the server when the last user of a given GC destroys it. .LP Note that some earlier versions of \f(CWXtDestroyGC()\fP had only a \f(CIgc\fP argument. Therefore, this function is not very portable. In addition, \f(CWXtDestroyGC()\fP is only guaranteed to work properly if there is exactly one open display in the application. .SH "Usage" You should never use this function. Programs running under Release 3 and later should be converted to use \f(CWXtReleaseGC()\fR. .SH "See Also" .na \s-1\fIXtAllocateGC\fR\s+1\*(s1, \s-1\fIXtGetGC\fR\s+1\*(s1, \s-1\fIXtReleaseGC\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtDestroyWidget" "Xt \- Widget Lifecycle" .SH "Name" .Na XtDestroyWidget \- destroy a widget instance. .XS "widgets, destroying" .XS "widgets: destroying" .Nz .XS "XtDestroyWidget" .SH "Synopsis" .Sy void XtDestroyWidget(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object to be destroyed; may be of class Object or any subclass thereof. .\" .SH "Description" \f(CWXtDestroyWidget()\fP destroys \f(CIobject\fP and all of its normal and popup descendants. It frees all resources associated with that widget and its descendants, and calls the Xlib function \f(CWXDestroyWindow()\fP to destroy the windows (if any) of the affected objects. The details this procedure are explained in the "Algorithm" section below. .\" .SH "Usage" Most applications simply exit, causing widgets to be destroyed automatically. Applications that create and destroy widgets dynamically should call \f(CWXtDestroyWidget()\fP. .LP \f(CWXtDestroyWidget()\fP can be used by widgets that need to destroy themselves. It can be called at any time, including from a callback routine of the widget being destroyed. .LP When an application needs to perform additional processing during the destruction of a widget, it should register a callback procedure on the \f(CWXtNdestroyCallback\fP list of the widget. .LP Applications that use multiple displays and want to destroy all the widgets on one of them can simply call \f(CWXtCloseDisplay()\fP. Applications that use multiple application contexts and want to destroy all the widgets in one of them can call \f(CWXtDestroyApplicationContext()\fP. A widget's windows can be destroyed without destroying the widget data structures by calling \f(CWXtUnrealizeWidget()\fP. .\" .SH "Algorithm" Widget destruction occurs in two phases to prevent dangling references to destroyed widgets. .LP In phase 1, \f(CWXtDestroyWidget()\fP performs the following: .IP \(bu 3n If the \f(CWbeing_destroyed\fP field of the widget is \f(CWTrue\fP, it returns immediately. .IP \(bu 3n Recursively descends the widget tree and sets the \f(CWbeing_destroyed\fP field to \f(CWTrue\fP for the widget and all normal and popup children. .IP \(bu 3n Adds the widget to a list of widgets (the destroy list) that should be destroyed when it is safe to do so. .LP Entries on the destroy list satisfy the invariant that if w2 occurs after w1 on the destroy list, then w2 is not a descendent, either normal or popup, of w1. .LP Phase 2 occurs when all procedures that should execute as a result of the current event have been called, including all procedures registered with the event and translation managers, that is, when the current invocation of \f(CWXtDispatchEvent()\fP is about to return, or immediately if not in \f(CWXtDispatchEvent()\fP. .LP In phase 2, \f(CWXtDestroyWidget()\fP performs the following on each entry in the destroy list in the order specified: .IP \(bu 3n Calls the destroy callback procedures registered on the widget and all normal and popup descendants in postorder (it calls child callbacks before parent callbacks). .IP \(bu 3n If the widget is not a popup child and the widget's parent is a subclass of \f(CWcompositeWidgetClass\fP, and if the parent is not being destroyed, it calls \f(CWXtUnmanageChild()\fP on the widget and then calls the widget's parent's delete_child procedure (see Section 3.3). .IP \(bu 3n If the widget is not a popup child and the widget's parent is a subclass of \f(CWconstraintWidgetClass\fP, it calls the \f(CWConstraintClassPart\fP destroy procedure for the parent, then for the parent's superclass, until finally it calls the \f(CWConstraintClassPart\fP destroy procedure for \f(CWconstraintWidgetClass\fP. .IP \(bu 3n Calls the destroy procedures for the widget and all normal and popup descendants in postorder. For each such widget, it calls the \f(CWCoreClassPart\fP destroy procedure declared in the widget class, then the destroy procedure declared in its superclass, until finally it calls the destroy procedure declared in the Object class record. .IP \(bu 3n Calls \f(CWXDestroyWindow()\fP if the specified widget is realized (that is, has an X window). The server recursively destroys all normal descendant windows. .IP \(bu 3n Recursively descends the tree and destroys the windows for all realized popup descendants, deallocates all popup descendants, constraint records, callback lists, and if the widget's class is a subclass of \f(CWcompositeWidgetClass\fP, children. .LP \f(CWXtCreateWidget()\fP and \f(CWXtConvertAndStore()\fP automatically register \f(CWXtCallbackReleaseCacheRef()\fP as a destroy callback on all widgets that use reference-counted resources from the conversion cache. In this way, destroying a widget also invokes the appropriate resource destructors when the reference count of a converted resource reaches 0. .SH "See Also" .na \s-1\fIXtCloseDisplay\fR\s+1\*(s1, \s-1\fIXtDestroyApplicationContext\fR\s+1\*(s1, \s-1\fIXtUnrealizeWidget\fR\s+1\*(s1. .ad .XE "widgets, destroying" .XE "widgets: destroying" .XE "XtDestroyWidget" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtDestructor" "Xt \- Resource Management" .SH "Name" .Na XtDestructor \- interface definition for procedure to destroy cached resource data returned by a new-style resource converter. .Nz .XS "XtDestructor" .SH "Synopsis" .Sy typedef void (*XtDestructor) (XtAppContext, XrmValue *, XtPointer, .br XrmValue *, Cardinal *); .As XtAppContext \f(CIapp\fP; XrmValue *\f(CIto\fP; XtPointer \f(CIconverter_data\fP; XrmValue *\f(CIargs\fP; Cardinal *\f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIapp\fP 1i Specifies in application context in which the resource is being freed. .IP \f(CIto\fP 1i Specifies the address and size of the cached resource value produced by the type converter. .IP \f(CIconverter_data\fP 1i Specifies the \f(CIconverter_data\fP returned by the type converter. .IP \f(CIargs\fP 1i Specifies the additional converter arguments as passed to the type converter when the conversion was performed. .IP \f(CInum_args\fP 1i Specifies the number of additional converter arguments. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" An \f(CWXtDestructor\fP is optionally registered with an \f(CWXtTypeConverter\fP new-style resource converter in a call to \f(CWXtAppSetTypeConverter()\fP or \f(CWXtSetTypeConverter()\fP. It is called when a resource returned by that converter is freed from the cache. The Intrinsics automatically free the memory occupied by the resource value (i.e., the memory pointed to by \f(CIto\f(CW->addr\fR), so the destructor should not do this but must deallocate the resource itself if it is a shared resource (such as an open file, or a Pixmap owned by the X server) and free any associated memory (if the resource value is a pointer type, for example, the Intrinsics will only free the memory that holds the pointer, not the structure pointed to by the pointer). .LP The \f(CIconverter_data\fP argument is data returned by the type converter in its \f(CIconverter_data\fP argument. This data may be of any type, cast to an \f(CWXtPointer\fP by the converter, and cast back to the original type by the destructor procedure. It serves a similar purpose to \f(CIclient_data\fP arguments to callback and other procedures, and can be used to identify other memory that must be freed, X resources that must be deallocated, and so on. .LP The \f(CIargs\fP and \f(CInum_args\fP arguments are the additional arguments passed to the resource converter when the conversion was performed. These values are also part of the resource cache, and can be used by the destructor to figure out what must be freed. The destructor should not free the \f(CIargs\fP array; the Intrinsics will free it automatically. .LP See \f(CWXtAppSetTypeConverter\fP(1) for more information on resource conversion and caching. See \f(CWXtTypeConverter\fP(2) for more information on the responsibilities of a resource converter procedure. .\" .SH "Example" The following procedure is the \f(CWXtDestructor\fP registered with the Intrinsics String-to-Pixel converter. It deallocates the \f(CWPixel\fP, which is an X server resource. Note that it does not free the memory that the cursor is stored in. The \f(CIconverter_data\fP argument (called \f(CWclosure\fP here) is used to indicate whether this \f(CWPixel\fP should be freed, or whether it is permanently allocated. See \f(CWXtTypeConverter\fP(2) for the converter procedure which accompanies this destructor. .Ps \s-2/* ARGSUSED */ static void FreePixel(app, toVal, closure, args, num_args) XtAppContext app; XrmValuePtr toVal; XtPointer closure; XrmValuePtr args; Cardinal *num_args; { Screen *screen; Colormap colormap; if (*num_args != 2) { XtAppWarningMsg(app, XtNwrongParameters,"freePixel",XtCXtToolkitError, "Freeing a pixel requires screen and colormap arguments", (String *)NULL, (Cardinal *)NULL); return; } screen = *((Screen **) args[0].addr); colormap = *((Colormap *) args[1].addr); if (closure) { XFreeColors( DisplayOfScreen(screen), colormap, (unsigned long*)toVal->addr, 1, (unsigned long)0); } }\s+2 .Pe .\" .SH "Structures" The \f(CWXrmValue\fP structure is defined as follows: .Ps typedef struct { unsigned int size; XPointer addr; } XrmValue, *XrmValuePtr; .Pe .\" .SH "See Also" .na \s-1\fIXtAppSetTypeConverter\fR\s+1\*(s1, \s-1\fIXtSetTypeConverter\fR\s+1\*(s1, .br \s-1\fIXtTypeConverter\fR\s+1\*(s2. .ad .XE "XtDestructor" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtDirectConvert" "Xt \- Resource Management" .SH "Name" .Na XtDirectConvert \- explicitly invoke an "old-style" resource converter and cache result. .XX "resources: resource conversion; XtDirectConvert" .XX "XtDirectConvert" .SH "Synopsis" .Sy void XtDirectConvert(\f(CIconverter\fP, \f(CIargs\fP, \f(CInum_args\fP, \f(CIfrom\fP, \f(CIto_return\fP) .As XtConverter \f(CIconverter\fP; XrmValuePtr \f(CIargs\fP; Cardinal \f(CInum_args\fP; XrmValuePtr \f(CIfrom\fP; XrmValuePtr \f(CIto_return\fP; .Ae .SS "Inputs" .IP \f(CIconverter\fP 1i Specifies the "old-style" conversion procedure to be called. .IP \f(CIargs\fP 1i Specifies the argument list that contains the additional arguments needed to perform the conversion (often \f(CWNULL\fR). .IP \f(CInum_args\fP 1i Specifies the number of additional arguments (often zero). .IP \f(CIfrom\fP 1i Specifies the value to be converted. .SS "Outputs" .IP \f(CIto_return\fP 1i Returns the converted value. .\" .SH "Description" \f(CWXtDirectConvert()\fP looks in the converter cache to see if the named conversion procedure has previously been called with the specified arguments. If so, it sets the cached resource address and size in \f(CIto_return\fP and returns. If no cached value is found, it sets \f(CIto_return\f(CW->addr\fR to \f(CWNULL\fP and \f(CIto_return\f(CW->size\fR to zero and calls \f(CIconverter\fP with its remaining arguments. The results of the conversion are stored in the cache and returned in \f(CIto_return\fP. .LP If the conversion is successful, \f(CIto_return\f(CW->addr\fR will be non-\f(CWNULL\fP. The data at this address must be copied immediately by the caller, because it may be in static storage owned by the type converter procedure. .\" .SH "Usage" \f(CWXtDirectConvert()\fP invokes an "old-style" converter of type \f(CWXtConverter\fP. In Release 4, more flexible (and incompatible) "new-style" converters of type \f(CWXtTypeConverter\fP were added. Old-style converters are still in use, and if you have to invoke one explicitly, you must use \f(CWXtDirectConvert()\fP. If you are writing your own converter, you should use the new style. .LP \f(CWXtConvertAndStore()\fP provides a higher level interface to resource conversion, and is easier to use in most cases. It works with both old-style and new-style converters. .LP You do not often need, in applications or widgets, to convert between resource types directly. Generally you can rely on the Intrinsics resource management code to perform all necessary conversions for you. When writing a resource converter, however, you may find that you need to invoke another converter. .\" .SH "Structures" .Ps typedef struct { unsigned int size; XPointer addr; } XrmValue, *XrmValuePtr; .Pe .SH "See Also" .na \s-1\fIXtAppAddConverter\fR\s+1\*(s1, \s-1\fIXtCallConverter\fR\s+1\*(s1, \s-1\fIXtConvertAndStore\fR\s+1\*(s1, \s-1\fIXtSetTypeConverter\fR\s+1\*(s1, .br \s-1\fIXtConverter\fR\s+1\*(s2, \s-1\fIXtTypeConverter\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtDisownSelection" "Xt \- Selections" .SH "Name" .Na XtDisownSelection \- indicate that selection data is no longer available. .XX "selections: data; XtDisownSelection" .XX "XtDisownSelection" .SH "Synopsis" .Sy void XtDisownSelection(\f(CIw\fP, \f(CIselection\fP, \f(CItime\fP) .As Widget \f(CIw\fP; Atom \f(CIselection\fP; Time \f(CItime\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget relinquishing selection ownership. .IP \f(CIselection\fP 1i Specifies which selection the widget is giving up (usually \f(CWXA_PRIMARY\fR or \f(CWXA_SECONDARY\fP). .IP \f(CItime\fP 1i Specifies the timestamp that indicates when the request to relinquish selection ownership was initiated. .\" .SH "Description" \f(CWXtDisownSelection()\fP informs the Intrinsics selection mechanism that the specified widget is to lose ownership of the specified selection as of the specified time. If the widget does not currently own the selection, either because it lost the selection or because it never had the selection to begin with, \f(CWXtDisownSelection()\fP does nothing. .LP After a widget has called \f(CWXtDisownSelection()\fP, its \f(CWXtConvertProc\fP is not called even if a request arrives later with a timestamp during the period that this widget owned the selection. However, its \f(CWXtDoneProc\fP will be called if a conversion that started before the call to \f(CWXtDisownSelection()\fP finishes after the call to \f(CWXtDisownSelection()\fP. See \f(CWXtOwnSelection()\fP for more information. .SH "Usage" Usually, a selection owner maintains ownership indefinitely until some other client requests ownership, at which time the Intrinsics selection mechanism informs the previous owner that it has lost ownership of the selection. However, in response to some user actions (for example, when a user deletes the information selected), the application may with to explicitly inform the Intrinsics that it no longer is to be the selection owner by calling \f(CWXtDisownSelection()\fP. .LP When the selection changes hands because another client has claimed it (rather than as a result of a call to \f(CWXtDisownSelection()\fP), the Intrinsics inform the application that it has lost the selection ownership by calling its \f(CWXtLoseSelectionProc\fR. .SH "See Also" .na \s-1\fIXtGetSelectionValue\fR\s+1\*(s1, \s-1\fIXtOwnSelection\fR\s+1\*(s1, .br \s-1\fIXtConvertProc\fR\s+1\*(s2, \s-1\fIXtDoneProc\fR\s+1\*(s2, \s-1\fIXtLoseSelectionProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtDispatchEvent" "Xt \- Event Handling" .SH "Name" .Na XtDispatchEvent \- dispatch an event to registered event handlers. .XX "events, dispatching handlers" .XX "event handlers, dispatching" .XN "event handlers: (see also XtDispatchEvent)" .Nz .XX "XtDispatchEvent" .SH "Synopsis" .Sy Boolean XtDispatchEvent(\f(CIevent\fP) .As XEvent *\f(CIevent\fP; .Ae .SS "Inputs" .IP \f(CIevent\fP 1i Specifies a pointer to the event structure to be dispatched to the appropriate event handlers. .SS "Returns" \f(CWTrue\fP if the event was dispatched to one or more event filters or event handlers. \f(CWFalse\fP if no handler could be found. .\" .SH "Description" \f(CWXtDispatchEvent()\fR sends events to Xlib event filters (new in Release 5) and to handler functions previously registered with \f(CWXtAddEventHandler()\fR. Since the entire translation manager is an event handler, \f(CWXtDispatchEvent()\fP results in action functions being called if a translation matches the event being dispatched. \f(CWXtDispatchEvent()\fR calls the appropriate handler functions and passes them the widget, the event, and client-specific data. See the "Background" section below for details on how events are dispatched. .LP If no handlers for the event are registered, the event is ignored. If there are multiple handlers registered for an event, the order in which handlers are called is undefined. (But see \f(CWXtInsertEventHandler()\fP.) .LP \f(CWXtDispatchEvent()\fR returns \f(CWTrue\fP if it dispatched the event to some filter (in Release 5) or handler and \f(CWFalse\fP if it found no handler to dispatch the event to. .LP \f(CWXtDispatchEvent()\fR records the timestamp of the last event dispatched which contains a timestamp (see \f(CWXtLastTimestampProcessed()\fR) and also is responsible for implementing the grab semantics of \f(CWXtAddGrab()\fR. .\" .SH "Usage" In most applications, \f(CWXtAppMainLoop()\fR is used to dispatch events transparently. \f(CWXtAppProcessEvent()\fP can also be used to get and dispatch a single event. \f(CWXtAddEventHandler()\fR and \f(CWXtInsertEventHandler()\fR are used to register event handlers. .LP The most common use of \f(CWXtDispatchEvent()\fR is to dispatch events acquired with \f(CWXtAppNextEvent()\fR. However, it also can be used to dispatch user-constructed events. .\" .SH "Background" In Release 5, the function \f(CWXFilterEvent()\fP was added to Xlib to support event filtering for international input methods. The Release 5 Intrinsics support internationalized input by calling \f(CWXFilterEvent()\fP from within \f(CWXtDispatchEvent()\fP. Note that there is no public Xlib interface for registering an event filter. .LP In Release 5, \f(CWXtDispatchEvent()\fP behaves as follows. .LP \f(CWXtDispatchEvent()\fP first calls \f(CWXFilterEvent()\fP with the \f(CIevent\fP and the window of the widget to which the Intrinsics intend to dispatch the event (the subsections below explain how \f(CWXtDispatchEvent()\fP decides which widget to dispatch to), or the event window if the Intrinsics would not dispatch the event to any handlers. If \f(CWXFilterEvent()\fP returns \f(CWTrue\fP and the event activated a server grab as identified by a previous call to \f(CWXtGrabKey()\fP or \f(CWXtGrabButton()\fP, \f(CWXtDispatchEvent()\fPcalls \f(CWXtUngrabKeyboard()\fP or \f(CWXtUngrabPointer()\fP with the timestamp from the event and immediately returns \f(CWTrue\fP. If \f(CWXFilterEvent()\fP returns \f(CWTrue\fP and a grab was not activated, \f(CWXtDispatchEvent()\fP just immediately returns \f(CWTrue\fP. .LP Otherwise, if \f(CWXFilterEvent()\fP returns \f(CWFalse\fP, \f(CWXtDispatchEvent()\fP sends the event to the event handler functions that have been previously registered with the dispatch routine. \f(CWXtDispatchEvent()\fP returns \f(CWTrue\fP if \f(CWXFilterEvent()\fP returned \f(CWTrue\fP, or if the event was dispatched to some handler, and returns \f(CWFalse\fP if it found no handler to which to dispatch the event. \f(CWXtDispatchEvent()\fP records the last timestamp in any event that contains a timestamp (see \f(CWXtLastTimestampProcessed()\fP), regardless of whether it was filtered or dispatched. .LP If a modal cascade is active with \f(CIspring_loaded\fP \f(CWTrue\fP, and if the event is a remap event as defined by \f(CWXtAddGrab()\fP, \f(CWXtDispatchEvent()\fP may dispatch the event a second time. If it does so, \f(CWXtDispatchEvent()\fP will call \f(CWXFilterEvent()\fP again with the window of the spring-loaded widget prior to the second dispatch and if \f(CWXFilterEvent()\fP returns \f(CWTrue\fP, the second dispatch will not be performed. .\" .SS "Dispatching Events to a Modal Cascade" .\"------------------------------------------------------------ \f(CWXtAddGrab()\fP (which is called by \f(CWXtPopup()\fP) adds a widget to the \fImodal cascade\fP. When there is a modal cascade, events that occur outside of the cascade must not be delivered, or must be remapped to one of the widgets in the cascade. \f(CWXtDispatchEvent()\fP does this as follows. .LP When at least one modal widget is in the widget cascade, \f(CWXtDispatchEvent()\fP first determines if the event should be delivered. It starts at the most recent cascade entry and follows the cascade up to and including the most recent cascade entry added with the \f(CIexclusive\fP parameter \f(CWTrue\fP. .LP This subset of the modal cascade along with all descendants of these widgets comprise the active subset. User events that occur outside the widgets in this subset are ignored or remapped. User events that occur within the active subset are delivered to the appropriate widget, which is usually a child or further descendant of the modal widget. .LP Regardless of where in the application they occur, remap events (events of type \f(CWKeyPress\fP, \f(CWKeyRelease\fP, \f(CWButtonPress\fP and \f(CWButtonRelease\fP) are always delivered to the most recent widget in the active subset of the cascade registered with \f(CIspring_loaded\fP \f(CWTrue\fP, if any such widget exists. If the event occurred in the active subset of the cascade but outside the spring-loaded widget, it is delivered normally before being delivered also to the spring-loaded widget. Regardless of where it is dispatched, the Intrinsics do not modify the contents of the event. .\" .SS "Dispatching Events with Redirected Keyboard Focus" .\"------------------------------------------------------------ \f(CWXtSetKeyboardFocus()\fP causes \f(CWXtDispatchEvent()\fP to remap keyboard events occurring within the specified subtree and dispatch them to the specified descendant widget or to an ancestor. If the descendant's class is not a subclass of Core, the descendant is replaced by its closest windowed ancestor. .LP When there is no modal cascade, keyboard events can be dispatched to a widget in one of four ways. Assume the server delivered the event to the window for widget E (because of X input focus, key or keyboard grabs, or pointer position). .IP \(bu 3n If neither E nor any of E's ancestors have redirected the keyboard focus, or if the event activated a grab for E as specified by a call to \f(CWXtGrabKey()\fP with any value of \f(CIowner_events\fP, or if the keyboard is actively grabbed by E with \f(CIowner_events\fP \f(CWFalse\fP via \f(CWXtGrabKeyboard()\fP or \f(CWXtGrabKey()\fP on a previous key press, the event is dispatched to E. .IP \(bu 3n Beginning with the ancestor of E closest to the root that has redirected the keyboard focus or E if no such ancestor exists, if the target of that focus redirection has in turn redirected the keyboard focus, recursively follow this focus chain to find a widget F that has not redirected focus. .RS .IP \- 3 If E is the final focus target widget F or a descendant of F, the event is dispatched to E. .IP \- 3 If E is not F, an ancestor of F, or a descendant of F, and the event activated a grab for E as specified by a call to \f(CWXtGrabKey()\fP for E, \f(CWXtUngrabKeyboard()\fP is called. .IP \- 3 If E is an ancestor of F, and the event is a key press, and either .RS .IP + 3 E has grabbed the key with \f(CWXtGrabKey()\fP and \f(CIowner_events\fP \f(CWFalse\fP, or .IP + 3 E has grabbed the key with \f(CWXtGrabKey()\fP and \f(CIowner_events\fP \f(CWTrue\fP, and the coordinates of the event are outside the rectangle specified by E's geometry, .RE then the event is dispatched to E. .IP \- 3 Otherwise, define A as the closest common ancestor of E and F: .RS .IP + 3 If there is an active keyboard grab for any widget via either \f(CWXtGrabKeyboard()\fP or \f(CWXtGrabKey()\fP on a previous key press, or if no widget between F and A (noninclusive) has grabbed the key and modifier combination with \f(CWXtGrabKey()\fP and any value of \f(CIowner_events\fP, the event is dispatched to F. .IP + 3 Else, the event is dispatched to the ancestor of F closest to A that has grabbed the key and modifier combination with \f(CWXtGrabKey()\fP. .RE .RE .LP When there is a modal cascade, if the final destination widget as identified above is in the active subset of the cascade, the event is dispatched; otherwise the event is remapped to a spring-loaded shell or discarded. Regardless of where it is dispatched, the Intrinsics do not modify the contents of the event. .LP When \f(CIsubtree\fP or one of its descendants acquires the X input focus or the pointer moves into the subtree such that keyboard events would now be delivered to the subtree, a \f(CWFocusIn\fP event is generated for the descendant if focus change events have been selected by the descendant. Similarly, when \f(CIsubtree\fP loses the X input focus or the keyboard focus for one of its ancestors, a \f(CWFocusOut\fP event is generated for descendant if focus change events have been selected by the descendant. .\" .SH "See Also" .na \s-1\fIXtAddEventHandler\fR\s+1\*(s1, \s-1\fIXtAddGrab\fR\s+1\*(s1, \s-1\fIXtAppMainLoop\fR\s+1\*(s1, \s-1\fIXtInsertEventHandler\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtDisplay" "Xt \- Object Information" .SH "Name" .Na XtDisplay \- return the X Display pointer for the specified widget. .XX "display: pointer; returning for widget" .XX "widgets: display pointer" .Nz .XX "XtDisplay" .SH "Synopsis" .Sy Display *XtDisplay(\f(CIw\fP) .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget; must be of class Core or any subclass thereof. .SS "Returns" The Display of the specified widget. .SH "Description" \f(CWXtDisplay()\fR returns the display pointer for the specified widget. .SH "Usage" \f(CWXtDisplay()\fP is implemented as a function when called from application code, but is replaced by a more efficient macro when called from widget code that includes the file \fI\fP. .LP Use \f(CWXtDisplayOfObject()\fP to return the display of a widget or the nearest widget ancestor of a non-widget object. .\" .SH "See Also" .na \s-1\fIXtDisplayOfObject\fR\s+1\*(s1, \s-1\fIXtScreen\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtDisplayInitialize" "Xt \- Application Contexts" .SH "Name" .Na XtDisplayInitialize \- initialize a display and add it to an application context. .XS "display, initializing" .XS "application contexts, adding display" .XN "display: (see also XtDisplayInitialize)" .Nz .XS "XtDisplayInitialize" .SH "Synopsis" .Sy void XtDisplayInitialize(\f(CIapp_context\fP, \f(CIdisplay\fP, \f(CIapplication_name\fP, \f(CIapplication_class\fP, \f(CIoptions\fP, \f(CInum_options\fP, \f(CIargc\fP, \f(CIargv\fP) .As XtAppContext \f(CIapp_context\fP; Display *\f(CIdisplay\fP; String \f(CIapplication_name\fP; String \f(CIapplication_class\fP; XrmOptionDescRec *\f(CIoptions\fP; Cardinal \f(CInum_options\fP; int *\f(CIargc\fP; /* was Cardinal * in Release 4 */ String *\f(CIargv\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CIdisplay\fP 1i Specifies the display. Note that a display can be in at most one application context. .IP \f(CIapplication_name\fP 1i Specifies the name of the application instance. .IP \f(CIapplication_class\fP 1i Specifies the class name of this application. This name is usually the generic name for all instances of this application. .IP \f(CIoptions\fP 1i Specifies how to parse the command line for any application-specific resources. The \f(CIoptions\fP argument is passed as a parameter to \f(CWXrmParseCommand()\fR. .IP \f(CInum_options\fP 1i Specifies the number of entries in the options list. .IP \f(CIargc\fP 1i Specifies a pointer to the number of command line arguments. In Release 4 and previously, this argument was of type \f(CWCardinal *\fP. In Release 5 it is an \f(CWint *\fP. .IP \f(CIargv\fP 1i Specifies the command line arguments. .SS "Outputs" .IP \f(CIargc\fP 1i Returns the number of command line arguments remaining after the command line is parsed. .IP \f(CIargv\fP 1i Returns a modified command line containing only the application name and any arguments that were not recognized as standard Xt options or options specified in \f(CIoptions\fP. .\" .SH "Description" In Release 5, \f(CWXtDisplayInitialize()\fP first retrieves the language string to be used for the specified display and calls the language procedure (if any was registered) with that language string. In all releases, \f(CWXtDisplayInitialize()\fR parses the command line using the Xlib \f(CWXrmParseCommand()\fP function, builds the resource database, and performs other per-display initialization. See \f(CWXtAppInitialize()\fP for information on how the language string is handled and how the command line is parsed. See the "Background" section below for detail on how the resource database is built. .LP If the synchronize resource is \f(CWTrue\fR, \f(CWXtDisplayInitialize()\fR calls the Xlib \f(CWXSynchronize()\fR function to put Xlib into synchronous mode for this display connection and any others currently open in the application context. .LP In Release 5, \f(CWXtDisplayInitialize()\fP calls \f(CWXrmSetDatabase()\fP to associate the resource database of the default screen with the display. .\" .SH "Usage" \f(CWXtDisplayInitialize()\fP does not actually open a display connection. \f(CWXtOpenDisplay()\fP opens a display and then calls \f(CWXtDisplayInitialize()\fP. Most applications need not use either of these functions; they can use \f(CWXtAppInitialize()\fP instead. .LP In Release 4, the \f(CIargc\fP argument is of type \f(CWCardinal *\fP, and in Release 5, this argument is of type \f(CWint *\fP. This is a minor incompatibility that may result warnings from ANSI-C compilers when porting from one release to another. .LP After \f(CWXtDisplayInitialize()\fP has been called, \f(CIargc\fP and \f(CIargv\fP contain only those arguments that were not in the standard option table or in the table specified by the \f(CIoptions\fP argument. If the modified \f(CIargc\fP is not zero, most applications simply print out the modified \f(CIargv\fP along with a message listing the allowable options. .\" .SH "Background" The algorithm for building the resource database has changed significantly between Release 4 and Release 5, with the introduction of per-screen databases, internationalization and the \f(CWcustomization\fP resource. The process followed by \f(CWXtDisplayInitialize()\fP in Release 5 is described below. .LP \f(CWXtDisplayInitialize()\fP first determines the language string to be used for the specified display and then creates resource databases as needed for each screen of the display by combining the following sources in order, with the entries in the first named source having highest precedence: .IP \(bu 3n Application command line (\f(CWargv\fP). .IP \(bu 3n Per-host user environment resource file on the local host. .IP \(bu 3n Per-screen resource specifications from the server. .IP \(bu 3n Per-display resource specifications from the server or from .br the user preference file on the local host. .IP \(bu 3n Application-specific user resource file on the local host. .IP \(bu 3n Application-specific class resource file on the local host. .LP .Nd 5 When the resource database for a particular screen on the display is needed (either internally, or when \f(CWXtScreenDatabase()\fP is called), \f(CWXtDisplayInitialize()\fP creates the resource database for the screen in the following manner: .IP \(bu 3n A temporary database, the "server resource database", is created from the string returned by \f(CWXResourceManagerString()\fP or, if \f(CWXResourceManagerString()\fP returns \f(CWNULL\fP, the contents of a resource file in the user's home directory. On POSIX-based systems, the usual name for this user preference resource file is \f(CW$HOME/\fI.Xdefaults\fR. .XX ".Xdefaults" .IP \(bu 3n If a language procedure has been set, \f(CWXtDisplayInitialize()\fP first searches the command line for the option "\-xnlLanguage", or for a \-xrm option that specifies the xnlLanguage/XnlLanguage resource. If such a resource is found, the value is assumed to be entirely in XPCS, the X Portable Character Set. If neither option is specified on the command line, \f(CWXtDisplayInitialize()\fP queries the server resource database (which is assumed to be entirely in XPCS) for the resource \fIname\fP\f(CW.xnlLanguage\fP, class \fIClass\fP\f(CW.XnlLanguage\fP where \fIname\fP .XX "xnlLanguage" and \fIClass\fP are the \f(CIapplication_name\fP and \f(CIapplication_class\fP specified to \f(CWXtDisplayInitialize()\fP. The language procedure is then invoked with the resource value if found, else the empty string. The string returned from the language procedure is saved for all future references in the Intrinsics that require the per-display language string. .IP \(bu 3n The screen resource database is initialized by parsing the command line. (See \f(CWXtAppInitialize()\fP for information on how the command line is parsed.) .IP \(bu 3n If a language procedure has not been set, The initial database is then queried for the resource \fIname\fP\f(CW.xnlLanguage\fP, class \fIClass\fP\f(CW.XnlLanguage\fP as specified above. If this database query fails, the server resource database is queried; if this query also fails, the language is determined from the environment; on POSIX-based systems, this is done by retrieving the value of the \f(CWLANG\fP environment variable. If no language string is found, the empty string is used. This language string is saved for all future references in the Intrinsics that require the per-display language string. .IP \(bu 3n After determining the language string, the user's environment resource file is then merged into the initial resource database if the file exists. This file is user-, host-, and process-specific and is expected to contain user preferences that are to override those specifications in the per-display and per-screen resources. On POSIX-based systems, the user's environment resource file name is specified by the value of the \f(CWXENVIRONMENT\fP environment variable. If this environment variable does not exist, the user's home directory is searched for a file named \f(CW.Xdefaults-\fP\fIhost\fP , where \fIhost\fP is the host name of the machine on which the application is running. .IP \(bu 3n The per-screen resource specifications are then merged into the screen resource database, if they exist. These specifications are the string returned by \f(CWXScreenResourceString()\fP for the respective screen and are owned entirely by the user. .IP \(bu 3n Next, the server resource database created earlier is merged into the screen resource database. The server property, and corresponding user preference file, are owned and constructed entirely by the user. .IP \(bu 3n The application-specific user resource file from the local host is then merged into the screen resource database. This file is owned by the application and typically stores user customizations in a directory owned by the user. Its name is found by calling \f(CWXrmSetDatabase()\fP with the current screen resource database, after preserving the original display-associated database, then calling \f(CWXtResolvePathname()\fP with the parameters (\f(CIdisplay\fP, \f(CWNULL\fP, \f(CWNULL\fP, \f(CWNULL\fP, \f(CIpath\fP, \f(CWNULL\fP, 0, \f(CWNULL\fP) where \f(CIpath\fP is defined in an operating-system-specific way. On POSIX-based systems, \f(CIpath\fP is defined to be the value of the environment variable \f(CWXUSERFILESEARCHPATH\fP if this is defined. If \f(CWXUSERFILESEARCHPATH\fP is not defined, an implementation-dependent default value is used. This default value is constrained in the following manner: .RS .IP \- 3 If the environment variable \f(CWXAPPLRESDIR\fP is not defined, the default \f(CWXUSERFILESEARCHPATH\fP must contain at least six entries. These entries must contain .XX "XUSERFILESEARCHPATH" .XX "XAPPLRESDIR" $HOME as the directory prefix, plus the following substitutions: .RS .IP 1. 3 %C, %N, %L or %C, %N, %l, %t, %c .IP 2. 3 %C, %N, %l .IP 3. 3 %C, %N .IP 4. 3 %N, %L or %N, %l, %t, %c .IP 5. 3 %N, %l .IP 6. 3 %N .LP The order of these six entries within the path must be as given above. The order and use of substitutions within a given entry is implementation dependent. .RE .IP \- 3 If \f(CWXAPPLRESDIR\fP is defined, the default \f(CWXUSERFILESEARCHPATH\fP must contain at least seven entries. These entries must contain the following directory prefixes and substitutions: .RS .IP 1. 3 $XAPPLRESDIR with %C, %N, %L or %C, %N, %l, %t, %c .IP 2. 3 $XAPPLRESDIR with %C, %N, %l .IP 3. 3 $XAPPLRESDIR with %C, %N .IP 4. 3 $XAPPLRESDIR with %N, %L or %N, %l, %t, %c .IP 5. 3 $XAPPLRESDIR with %N, %l .IP 6. 3 $XAPPLRESDIR with %N .IP 7. 3 $HOME with %N .LP The order of these seven entries within the path must be as given above. The order and use of substitutions within a given entry is implementation dependent. .RE .RE .IP \(bu 3n Lastly, the application-specific class resource file from the local host is merged into the screen resource database. This file is owned by the application and is usually placed in a system directory (\fI/usr/lib/X11/app-defaults\fP in most implementations) when the application is installed. It may contain site-wide customizations specified by the system manager. The name of the application class resource file is found by calling \f(CWXtResolvePathname()\fP with the parameters (\f(CIdisplay\fP, "app-defaults", \f(CWNULL\fP, \f(CWNULL\fP, \f(CWNULL\fP, \f(CWNULL\fP, 0, \f(CWNULL\fP). This call will look in the default system directory, or in the directories specified by \f(CWXFILESEARCHPATH\fP environment variable. See \f(CWXtResolvePathname()\fP for details on how this variable is used. .LP This file, the application class "app-defaults" file, should be provided by the developer of the application and may be required for the application to function properly. A simple application that wants to be assured of having a minimal set of resources in the absence of its class resource file can declare fallback resource specifications with \f(CWXtAppSetFallbackResources()\fP. .LP Note that the customization substitution string is retrieved dynamically by \f(CWXtResolvePathname()\fP so that the resolved file name of the application class resource file can be affected by any of the earlier sources for the screen resource database, even though the contents of the class resource file have lowest precedence. .\" .SH "Structures" The \f(CWXrmOptionDescRec\fP structure is as follows. See \f(CWXtAppInitialize()\fP for information on how it is used. .Ps .ta 4n 1.9i typedef enum { /* Value is ... */ XrmoptionNoArg, /* specified in OptionDescRec.value */ XrmoptionIsArg, /* the option string itself */ XrmoptionStickyArg, /* characters immediately following option */ XrmoptionSepArg, /* next argument in argv */ XrmoptionResArg, /* next argument is input to XrmPutLineResource */ /* Ignore this option and ... */ XrmoptionSkipArg, /* the next argument in argv */ XrmoptionSkipNArgs, /* Ignore this option and ... */ /* the next value arguments in argv */ XrmoptionSkipLine /* the rest of argv */ } XrmOptionKind; .sp .5 typedef struct { char *option; /* Option name in argv */ char *specifier; /* Resource name (without application name) */ XrmOptionKind argKind; /* Which style of option it is */ caddr_t value; /* Value to provide if XrmoptionNoArg */ } XrmOptionDescRec, *XrmOptionDescList; .Pe .SH "See Also" .na \s-1\fIXtAppCreateShell\fR\s+1\*(s1, \s-1\fIXtAppInitialize\fR\s+1\*(s1, \s-1\fIXtCreateApplicationContext\fR\s+1\*(s1, \s-1\fIXtDatabase\fR\s+1\*(s1, \s-1\fIXtOpenDisplay\fR\s+1\*(s1, \s-1\fIXtResolvePathname\fR\s+1\*(s1. .ad .XE "display, initializing" .XE "application contexts, adding display" .XE "XtDisplayInitialize" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtDisplayOfObject" "Xt \- Object Information" .SH "Name" .XX "XtDisplayOfObject" .Na XtDisplayOfObject \- return the display pointer for the nearest ancestor of object that is of class Core. .Nz .SH "Synopsis" .Sy Display *XtDisplayOfObject(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object; may be of class Object or any subclass thereof. .SS "Returns" The display of \f(CIobject\fP or of its nearest widget ancestor. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtDisplayOfObject()\fR is identical in function to \f(CWXtDisplay()\fR if the \f(CIobject\fP is a widget; otherwise \f(CWXtDisplayOfObject()\fR returns the display pointer for the nearest ancestor of \f(CIobject\fP that is of class Core. .SH "Usage" If you are working with windowed objects, use \f(CWXtDisplay()\fP rather than \f(CWXtDisplayOfObject()\fP. \f(CWXtDisplay()\fP may be implemented as an efficient macro for widget code that includes the file \fI\fP. .SH "See Also" .na \s-1\fIXtScreenOfObject\fR\s+1\*(s1, \s-1\fIXtWindowOfObject\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "\s-2XtDisplayStringConversionWarning\s0" "Xt \- Resource Management" .ds cn \w'XtDisplayStringConversionWarning \- 'u .SH "Name" .XX "XtDisplayStringConversionWarning" .Na XtDisplayStringConversionWarning \- issue a warning message during conversion of string resource values. .Nz .SH "Synopsis" .Sy void XtDisplayStringConversionWarning(\f(CIdisplay\fP, \f(CIfrom_value\fP, \f(CIto_type\fP) .As Display *\f(CIdisplay\fP; String \f(CIfrom_value\fP, \f(CIto_type\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the display connection with which the conversion is associated. .IP \f(CIfrom_value\fP 1i Specifies the string that could not be converted. .IP \f(CIto_type\fP 1i Specifies the target representation type requested. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtDisplayStringConversionWarning()\fR issues a warning message using \f(CWXtAppWarningMsg()\fR with \f(CIname\fP set to \f(CWconversionError\fP, \f(CItype\fP set to \f(CWstring\fP, \f(CIclass\fP set to \f(CWXtToolkitError\fP and the \f(CIdefault\fP message string set to: .br .sp .in .25i \f(CWCannot convert\fP \f(CIfrom_value\fP \f(CWto type\fP \f(CIto_type\fP .br .in -.25i .\" .SH "Usage" This function is intended for use within "new-style" string resource converters. To issue other types of warning or error messages, the type converter should use \f(CWXtAppWarningMsg()\fR or \f(CWXtAppErrorMsg()\fR directly. .LP \f(CWXtDisplayStringConversionWarning()\fP supersedes \f(CWXtStringConversionWarning()\fP which does not take a \f(CWDisplay *\fP argument and can therefore be used in "old-style" converters. .\" .SH "See Also" .na \s-1\fIXtAppErrorMsg\fR\s+1\*(s1, \s-1\fIXtAppWarningMsg\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtDisplayToApplicationContext" "Xt \- Application Context" .SH "Name" .XX "XtDisplayToApplicationContext" .Na XtDisplayToApplicationContext \- retrieve the application context associated with a Display. .Nz .SH "Synopsis" .Sy XtAppContext XtDisplayToApplicationContext( \f(CIdisplay\fP ) .As Display *\f(CIdisplay\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies an open and initialized display connection. .SS "Returns" The application context of \f(CIdisplay\fP. .SH "Description" \f(CWXtDisplayToApplicationContext()\fR returns the application context in which the specified display was initialized. If the display has not been initialized with \f(CWXtDisplayInitialize()\fP (which is called by \f(CWXtOpenDisplay()\fP and \f(CWXtAppInitialize()\fP), an error message is issued. .SH "See Also" .na \s-1\fIXtCreateApplicationContext\fR\s+1\*(s1, \s-1\fIXtDisplayInitialize\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtError" "Xt \- Error Handling" .SH "Name" .Na XtError \- call the low-level fatal error handler. .Nz .XX "XtError" .SH "Synopsis" .Sy void XtError(\f(CImessage\fP) .As String \f(CImessage\fP; .Ae .SS "Inputs" .IP \f(CImessage\fP 1i Specifies the message to be reported. .SS "Returns" \f(CWXtError()\fP terminates the application and does not return. .\" .SH "Availability" \f(CWXtError()\fP has been superseded by \f(CWXtAppError()\fP. .\" .SH "Description" \f(CWXtError()\fP passes its arguments to the installed low-level error handler. On \s-1POSIX\s+1 systems, the default handler is \f(CW_XtDefaultError()\fP. It prints the message to the stderr stream and calls \f(CWexit()\fP. .\" .SH "Usage" \f(CWXtError()\fP has been superseded by \f(CWXtAppError()\fP, which performs the same function on a per-application context basis. \f(CWXtError()\fP now calls \f(CWXtAppError()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtError()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppError()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppError()\fP for more information. .LP \f(CWXtError()\fP calls the "low-level" error handler. It is better to use \f(CWXtAppErrorMsg()\fP which calls the "high-level" error handler. The high-level handler looks up the error message in a resource database and so allows for customization and internationalization of error messages. .\" .SH "See Also" .na \s-1\fIXtErrorMsg\fR\s+1\*(s1, \s-1\fIXtSetErrorHandler\fR\s+1\*(s1, \s-1\fIXtSetWarningMsg\fR\s+1\*(s1, \s-1\fIXtWarning\fR\s+1\*(s1, \s-1\fIXtWarningMsg\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtErrorHandler" "Xt \- Error Handling" .SH "Name" .Na XtErrorHandler \- interface definition for low-level error and warning handler procedures. .Nz .XX "error handling: method" .XN "error handling: (see also XtErrorHandler)" .XN "errors: (see also XtErrorHandler)" .XX "XtErrorHandler" .SH "Synopsis" .Sy typedef void (*XtErrorHandler)(String); .As String \f(CImessage\fP; .Ae .SS "Inputs" .IP \f(CImessage\fP 1i Specifies the error message. .\" .SH "Description" An \f(CWXtErrorHandler\fP is registered as an error or warning handler with \f(CWXtAppSetErrorHandler()\fP or \f(CWXtAppSetWarningHandler()\fP. It is invoked by \f(CWXtAppError()\fP or \f(CWXtAppError()\fP. The error handler should display the specified string in some appropriate fashion. Some applications may wish to log errors to a file as well. Error handlers should exit; warning handlers should return. .LP See \f(CWXtErrorMsgHandler\fP(2) for a description of the high-level error and warning handler procedure. .\" .SH "Example" The Intrinsics default error and warning handlers are shown below. The \f(CWXTERROR_PREFIX\fP and \f(CWXTWARNING_PREFIX\fP symbols are by default the empty string in the MIT implementation, but may be configured when the Intrinsics are compiled. .Ps void _XtDefaultError(message) String message; { extern void exit(); (void)fprintf(stderr, "%sError: %s\n", XTERROR_PREFIX, message); exit(1); } void _XtDefaultWarning(message) String message; { if (message && *message) (void)fprintf(stderr, "%sWarning: %s\n", XTWARNING_PREFIX, message); return; } .Pe .SH "See Also" .na \s-1\fIXtAppError\fR\s+1\*(s1, \s-1\fIXtAppSetErrorHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningHandler\fR\s+1\*(s1, \s-1\fIXtAppWarning\fR\s+1\*(s1, .br \s-1\fIXtErrorMsgHandler\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtErrorMsg" "Xt \- Error Handling" .SH "Name" .Na XtErrorMsg \- call the high-level fatal error handler. .XS "XtErrorMsg" .Nz .SH "Synopsis" .Sy void XtErrorMsg(\f(CIname\fP, \f(CItype\fP, \f(CIclass\fP, \f(CIdefault\fP, \f(CIparams\fP, \f(CInum_params\fP) .As String \f(CIname\fP; String \f(CItype\fP; String \f(CIclass\fP; String \f(CIdefault\fP; String *\f(CIparams\fP; Cardinal *\f(CInum_params\fP; .Ae .SS "Inputs" .IP \f(CIname\fP 1i Specifies the general kind of error. .IP \f(CItype\fP 1i Specifies the detailed name of the error. .IP \f(CIclass\fP 1i Specifies the resource class of the error. .IP \f(CIdefault\fP 1i Specifies the default message to use if no message is found in the database. .IP \f(CIparams\fP 1i Specifies an array of values to be inserted into the message. .IP \f(CInum_params\fP 1i Specifies the number of elements in \f(CIparams\fP. .SS "Returns" \f(CWXtErrorMsg()\fP terminates the application and does not return. .\" .SH "Availability" \f(CWXtErrorMsg()\fP has been superseded by \f(CWXtAppErrorMsg()\fP. .\" .SH "Description" \f(CWXtErrorMsg()\fP passes all of its arguments to the installed high-level error handler. The default high-level error handler is \f(CW_XtDefaultErrorMsg()\fP. It calls \f(CWXtAppGetErrorDatabaseText()\fP to lookup an error message of the specified \f(CIname\fP, \f(CItype\fP, and \f(CIclass\fP in the error database. If no such message is found, \f(CWXtAppGetErrorDatabaseText()\fP returns the specified \f(CIdefault\fP message. In either case, \f(CW_XtDefaultErrorMsg()\fP does a \f(CWprintf\fP-style substitution of \f(CIparams\fP into the message, and passes the resulting text to the low-level error handler by calling \f(CWXtError()\fP. .\" .SH "Usage" \f(CWXtErrorMsg()\fP has been superseded by \f(CWXtAppErrorMsg()\fP, which performs the same function on a per-application context basis. \f(CWXtErrorMsg()\fP now calls \f(CWXtAppErrorMsg()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtErrorMsg()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppErrorMsg()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppErrorMsg()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtAppErrorMsg\fR\s+1\*(s1, \s-1\fIXtAppWarningMsg\fR\s+1\*(s1. .ad .XE "XtErrorMsg" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtErrorMsgHandler" "Xt \- Error Handling" .SH "Name" .Na XtErrorMsgHandler \- interface definition for high-level error and warning handler procedures. .Nz .XS "error handling: procedure" .XN "error handling: (see also XtErrorMsgHandler)" .XN "errors: (see also XtErrorMsgHandler)" .XS "XtErrorMsgHandler" .SH "Synopsis" .Sy typedef void (*XtErrorMsgHandler)(String, String, String, String, String *, Cardinal *); .As String \f(CIname\fP; String \f(CItype\fP; String \f(CIclass\fP; String \f(CIdefaultp\fP; String *\f(CIparams\fP; Cardinal *\f(CInum_params\fP; .Ae .SS "Inputs" .IP \f(CIname\fP 1i Specifies the name that is concatenated with the specified type to form the resource name of the error message. .IP \f(CItype\fP 1i Specifies the type that is concatenated with the name to form the resource name of the error message. .IP \f(CIclass\fP 1i Specifies the resource class of the error message. .IP \f(CIdefaultp\fP 1i Specifies the default message to use if no error database entry is found. .IP \f(CIparams\fP 1i Specifies a pointer to a list of values to be substituted in the message. .IP \f(CInum_params\fP 1i Specifies the number of values in the parameter list. .\" .SH "Description" An \f(CWXtErrorMsgHandler\fP is registered as a high-level error or warning handler with \f(CWXtAppSetErrorMsgHandler()\fP or \f(CWXtAppSetWarningMsgHandler()\fP. It is invoked by \f(CWXtAppErrorMsg()\fP or \f(CWXtAppWarningMsg()\fP. .LP An \f(CWXtErrorMsgHandler\fP should look up an error message of the specified \f(CIname\fP, \f(CItype\fP, and \f(CIclass\fP in an error database of some sort, and display the message it finds, or use the supplied default \f(CIdefaultp\fP. Whether a message is found in a database or the default message is used, the specified \f(CIparams\fP should be substituted into the message using standard \f(CWprintf()\fP substitutions before it is displayed. .\" .SH "Usage" A custom high-level error or warning handler may find it useful to use \f(CWXtAppGetErrorDatabase()\fP or \f(CWXtAppGetErrorDatabaseText()\fP. This latter function looks up an error message in a standard X resource database by concatenating the \f(CIname\fP and \f(CItype\fP arguments into the resource name of the message and using \f(CWclass\fP as the resource class of the message. See \f(CWXtAppGetErrorDatabaseText\fP(1) for more details. .LP A high-level error or warning handler should generally display the message it builds by calling the corresponding low-level handler with \f(CWXtAppError()\fP or \f(CWXtAppWarning()\fP. This allows customization at two independent levels of abstraction. .LP Usually, the \f(CIname\fP argument will describe the general kind of error, such as \f(CWinvalidParameters\fR or \f(CWinvalidWindow\fR, and the \f(CItype\fP argument provides extra information about the error, such as the name of the function in which the error was detected. .LP Note that application-context-specific error handling is not implemented in MIT release, though the \f(CWXtApp\fP version of all the error handling routines are present. Most implementation will support only a single set of error handlers for all application contexts, and if a new handler is registered in one app context, it will take effect in all contexts. .\" .SH "Example" The example below shows the Intrinsics default error message handler: .Ps \s-2void _XtDefaultErrorMsg (name,type,class,defaultp,params,num_params) String name,type,class,defaultp; String* params; Cardinal* num_params; { char buffer[1000], message[1000]; XtGetErrorDatabaseText(name,type,class,defaultp, buffer, 1000); /*need better solution here, perhaps use lower level printf primitives? */ if (params == NULL num_params == NULL *num_params == 0) XtError(buffer); else { int i = *num_params; String par[10]; if (i > 10) i = 10; bcopy( (char*)params, (char*)par, i * sizeof(String) ); bzero( &par[i], (10-i) * sizeof(String) ); (void) sprintf(message, buffer, par[0], par[1], par[2], par[3], par[4], par[5], par[6], par[7], par[8], par[9]); XtError(message); if (i != *num_params) XtWarning( "some arguments in previous message were lost" ); } }\s-2 .Pe .SH "See Also" .na \s-1\fIXtAppErrorMsg\fR\s+1\*(s1, \s-1\fIXtAppSetErrorMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppWarningMsg\fR\s+1\*(s1, .br \s-1\fIXtErrorHandler\fR\s+1\*(s2. .ad .XE "error handling: procedure" .XE "XtErrorMsgHandler" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtEventHandler" "Xt \- Event Handling" .SH "Name" .Na XtEventHandler \- interface definition for event handler procedure. .Nz .XS "event handlers: procedure" .XN "event handlers: (see also XtEventHandler)" .XS "XtEventHandler" .XS "input, input events method" .SH "Synopsis" .Sy typedef void (*XtEventHandler)(Widget, XtPointer, XEvent *, Boolean *); .As Widget \f(CIw\fP; XtPointer \f(CIclient_data\fP; XEvent *\f(CIevent\fP; Boolean *\f(CIcontinue_to_dispatch_return\fP .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget for which the handler was registered. .IP \f(CIclient_data\fP 1i Specifies data registered with this event handler. .IP \f(CIevent\fP 1i Specifies the event that triggered this call. .SS "Outputs" .IP \f(CIcontinue_to_dispatch_return\fR 1i Returns a Boolean indicating whether to call the remaining event handlers that are registered for the current event. .\" .SH "Description" An \f(CWXtEventHandler\fP is registered with \f(CWXtAddEventHandler()\fP, \f(CWXtAddRawEventHandler()\fP, \f(CWXtInsertEventHandler()\fP, or \f(CWXtInsertRawEventHandler()\fP. It is called when one of the events that it was registered to handle occurs on the widget it was registered for. .LP An \f(CWXtEventHandler\fP should do whatever processing is necessary for the widget or application to handle the event \f(CIevent\fP that occurred on widget \f(CIw\fP. The \f(CIclient_data\fP argument can be arbitrary data registered with the event handler procedure. It is cast to an \f(CWXtPointer\fP when registered and should be cast back to the appropriate type within the event handler. .LP The \f(CIcontinue_to_dispatch_return\fP is the address of a \f(CWBoolean\fP variable which is intialized to \f(CWTrue\fP by the Intrinsics before the event handler is called. If a handler sets this variable to \f(CWFalse\fP, then no more handlers will be dispatched for the event. Doing this may lead to portability problems because implementations of the Intrinsics are allowed to add event handlers for any widget at any time. If you prevent these potential "invisible" event handlers from receiving events, the Intrinsics are not guaranteed to behave as expected. .\" .SH "Usage" Most widgets and applications do not need to use event handlers explicitly. Instead they can use translation tables and action procedures. .\" .SH "Example" The procedure below is an event handler from the \fIxmag\fP client. It is a special handler that follows the location of the mouse while it is dragged with the button down and a pointer grab is in effect. When the button is released, it magnifies a new area of the screen, releases the pointer grab, and calls \f(CWXtRemoveEventHandler()\fP on itself. .Ps \s-2/* * ResizeEH() -- Event Handler for resize of selection box. */ static void ResizeEH(w, closure, event, continue_to_dispatch) /* ARGSUSED */ Widget w; XtPointer closure; XEvent *event; Boolean *continue_to_dispatch; { hlPtr data = (hlPtr)closure; switch (event->type) { case MotionNotify: data->x = event->xmotion.x_root; data->y = event->xmotion.y_root; break; case ButtonRelease: GetImageAndAttributes(FindWindow(event->xmotion.x_root, event->xmotion.y_root), min(data->homeX,event->xbutton.x_root), min(data->homeY,event->xbutton.y_root), abs(data->homeX - event->xbutton.x_root), abs(data->homeY - event->xbutton.y_root), data); if (data->newScale) PopupNewScale(data); else SWSetImage(data->scaleInstance, data->image); XtUngrabPointer(w, CurrentTime); XtRemoveEventHandler(w, PointerMotionMask ButtonReleaseMask, True, ResizeEH, (XtPointer)data); data->selectMode = done; break; } }\s+2 .Pe This event handler is registered with the following code, invoked when the user presses mouse button 2. .Ps XtAddEventHandler(w, PointerMotionMask ButtonReleaseMask, True, ResizeEH, (XtPointer)data); .Pe .XX "event handlers: adding" .SH "See Also" .na \s-1\fIXtAddEventHandler\fR\s+1\*(s1, \s-1\fIXtAddRawEventHandler\fR\s+1\*(s1, \s-1\fIXtAppAddActions\fR\s+1\*(s1, \s-1\fIXtRemoveEventHandler\fR\s+1\*(s1, \s-1\fIXtRemoveRawEventHandler\fR\s+1\*(s1. .ad .XE "event handlers: procedure" .XE "XtEventHandler" .XE "input, input events method" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtExposeProc" "Xt \- Widget Method Prototypes" .SH "Name" .Na XtExposeProc \- interface definition for the Core \f(CWexpose()\fP method. .Nz .XX "XtExposeProc" .SH "Synopsis" .Sy typedef void (*XtExposeProc)(Widget, XEvent *, Region); .As Widget \f(CIwidget\fP; XEvent *\f(CIevent\fP; Region \f(CIregion\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget instance requiring redisplay. .IP \f(CIevent\fP 1i Specifies the exposure event, which specifies the rectangle that requires redisplay. .IP \f(CIregion\fP 1i Specifies the union of all rectangles in this exposure sequence. .\" .SH "Description" \f(CWXtExposeProc\fP is the type of the Core (and RectObj) \f(CWexpose()\fP method. See \f(CWexpose\fP(4) for more information. .\" .SH "See Also" .na \s-1\fIexpose\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtFilePredicate" "Xt \- File Searching" .SH "Name" .Na XtFilePredicate \- interface definition for a filename evaluation procedure. .Nz .XS "XtFilePredicate" .SH "Synopsis" .Sy typedef Boolean (*XtFilePredicate)(String); .As String \f(CIfilename\fP; .Ae .SS "Inputs" .IP \f(CIfilename\fP 1i Specifies a potential filename. .SS "Returns" \f(CWTrue\fP if \f(CIfilename\fP is acceptable; \f(CWFalse\fP otherwise. .\" .SH "Description" An \f(CWXtFilePredicate\fP is specified in calls to \f(CWXtResolvePathname()\fP and \f(CWXtFindFile()\fP, and is called to judge filenames found by those procedures. If the string is appropriate for the intended use (if it names a readable file, for example) then the \f(CWXtFilePredicate\fP should return \f(CWTrue\fP; otherwise it should return \f(CWFalse\fP. .SH "Example" The default predicate used by \f(CWXtResolvePathname()\fP and \f(CWXtFindFile()\fP simply tests that the specified filename exists, is readable, and is not a directory. This default procedure is shown below. Note that it attempts to handle some operating system dependencies. .Ps static Boolean TestFile(path) String path; { #ifdef VMS return TRUE; /* Who knows what to do here? */ #else struct stat status; return (access(path, R_OK) == 0 && /* exists and is readable */ stat(path, &status) == 0 && /* get the status */ #ifndef X_NOT_POSIX S_ISDIR(status.st_mode) == 0); /* not a directory */ #else (status.st_mode & S_IFDIR) == 0); /* not a directory */ #endif /* X_NOT_POSIX else */ #endif /* VMS */ } .Pe .SH "See Also" .na \s-1\fIXtFindFile\fR\s+1\*(s1, \s-1\fIXtResolvePathname\fR\s+1\*(s1. .ad .XE "XtFilePredicate" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtFindFile" "Xt \- File Searching" .SH "Name" .XX "XtFindFile" .XX "files, searching for" .XX "searching for files (see XtFindFile)" .Na XtFindFile \- search for a file using substitutions in a path. .Nz .SH "Synopsis" .Sy String XtFindFile(\f(CIpath\fP, \f(CIsubstitutions\fP, \f(CInum_substitutions\fP, \f(CIpredicate\fP) .As String \f(CIpath\fP; Substitution \f(CIsubstitutions\fP; Cardinal \f(CInum_substitutions\fP; XtFilePredicate \f(CIpredicate\fP; .Ae .SS "Inputs" .IP \f(CIpath\fP 1i Specifies a path of file names including substitution characters. .IP \f(CIsubstitutions\fP 1i Specifies a list of substitutions to make into the path. .IP \f(CInum_substitutions\fP 1i Specifies the number of substitutions passed in. .IP \f(CIpredicate\fP 1i Specifies a procedure called to judge each potential file name, or \f(CWNULL\fR. .SS "Returns" A filename, or \f(CWNULL\fP if no file was found. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtFindFile()\fP performs the substitutions specified by \f(CIsubstitutions\fP on each colon-separated element of \f(CIpath\fP in turn, and passes the resulting string to \f(CIpredicate\fP. If \f(CIpredicate\fP returns \f(CITrue\fP, \f(CWXtFindFile()\fP returns the string. If \f(CIpredicate\fP never returns \f(CWTrue\fP, \f(CWXtFindFile()\fP returns \f(CWNULL\fP. .LP Each element in \f(CIsubstitutions\fP is a structure that contains a character and a string. If any element in \f(CIpath\fP contains a percent sign followed by a character that appears in \f(CIsubstitutions\fP, then that two-character sequence will be replaced by the corresponding string in \f(CIsubstitutions\fP. The "Background" section below provides more details about the substitution process. .LP If \f(CIpredicate\fP is \f(CWNULL\fP, then an internal predicate is used that returns \f(CWTrue\fP if the string is the name of a readable file (and is not a directory), and returns \f(CWFalse\fP otherwise. See \f(CWXtFilePredicate\fP(2) for more details on how to write a file predicate procedure. .LP The caller must free the returned string with \f(CWXtFree()\fP when it is no longer needed. .\" .SH "Usage" \f(CWXtFindFile()\fP is intended as a way to find a file that depends on variables such as the current setting of the locale, or the number of bitplanes available on a screen. Most applications can use the higher-level function \f(CWXtResolvePathname()\fP which provides a number of standard substitutions and a default path. .LP The default predicate procedure is sufficient for most uses. An application that wanted to find a directory rather than a file, for example, would have to specify a custom predicate, as would an application that wanted to verify that a file was readable and that the contents of the file were reasonable would also have to provide a custom predicate procedure. .\" .SH "Background" There are two substitution sequences that are treated specially: .IP \(bu 3n The character sequence \fI%:\fR (percent colon) specifies an embedded colon that is not a delimiter; the sequence is replaced by a single colon. .IP \(bu 3n The character sequence \fI%%\fR (percent percent) specifies a percent character that does not introduce a substitution; the sequence is replaced by a single percent character. .LP A substitution string entry of \f(CWNULL\fR is equivalent to a pointer to an empty string. .LP If the operating system does not interpret multiple embedded name separators in the path (i.e., "/\^" in POSIX) the same way as a single separator, \f(CWXtFindFile()\fR will collapse multiple separators into a single one after performing all string substitutions. Except for collapsing embedded separators, the contents of the string substitutions are not interpreted by \f(CWXtFindFile()\fR and may therefore contain any operating-system-dependent characters, including additional name separators. .\" .SH "Structures" The \f(CWSubstitution\fP type is defined as follows: .XX "SubstitutionRec structure" .XX "types, SubstitutionRec" .Ps typedef struct { char match; String substitution; } SubstitutionRec, *Substitution; .Pe .Nd 4 .SH "See Also" .na \s-1\fIXtResolvePathname\fR\s+1\*(s1, .br \s-1\fIXtFilePredicate\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtFree" "Xt \- Memory Allocation" .SH "Name" .Na XtFree \- free allocated memory. .XN "freeing storage block (see storage block)" .XX "storage, freeing (XtFree)" .Nz .XX "XtFree" .SH "Synopsis" .Sy void XtFree(\f(CIptr\fP); .As char *\f(CIptr\fP; .Ae .SS "Inputs" .IP \f(CIptr\fP 1i Specifies the address of the allocated memory to be freed. .\" .SH "Description" \f(CWXtFree()\fR frees a block of memory previously allocated by \f(CWXtMalloc()\fR, \f(CWXtRealloc()\fP, \f(CWXtCalloc()\fR, \f(CWXtNew()\fP or \f(CWXtNewString()\fP so that it can be reused by the system. .LP If \f(CIptr\fR is \f(CWNULL\fR, \f(CWXtFree()\fR returns immediately. .\" .SH "Usage" The \f(CIptr\fP argument is of type \f(CWchar *\fP. In many cases, you will have to cast the data you are freeing to this type in order to avoid warning messages from your compiler. .LP A number of Xt functions return strings or other values that must be freed with \f(CWXtFree()\fP when the caller will no longer need them. You should be sure to check the documentation of any function that returns a value to find out who "owns" the memory and who is expected to free it. .LP Calling the Toolkit's \f(CWXtMalloc()\fR and \f(CWXtFree()\fR is more portable and provides better error checking than calling system-specific \f(CWmalloc\fR and \f(CWfree\fR. You should not use \f(CWXtFree()\fP on memory that was allocated with \f(CWmalloc()\fP or other non-Xt memory allocation routines. .\" .SH "See Also" .na \s-1\fIXtCalloc\fR\s+1\*(s1, \s-1\fIXtMalloc\fR\s+1\*(s1, \s-1\fIXtNew\fR\s+1\*(s1, \s-1\fIXtNewString\fR\s+1\*(s1, \s-1\fIXtRealloc\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGeometryHandler" "Xt \- Widget Method Prototypes" .SH "Name" .hw methods .Na XtGeometryHandler \- interface definition for \f(CWgeometry_manager()\fP, .br \f(CWquery_geometry()\fP, and \f(CWroot_geometry_manager()\fP methods. .Nz .XX "XtGeometryHandler" .SH "Synopsis" .Sy typedef XtGeometryResult (*XtGeometryHandler)(Widget,XtWidgetGeometry *, .br XtWidgetGeometry *); .br .As Widget \f(CIw\fP; XtWidgetGeometry *\f(CIrequest\fP; XtWidgetGeometry *\f(CIgeometry_return\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. .IP \f(CIrequest\fP 1i Specifies the requested geometry. .SS "Outputs" .IP \f(CIgeometry_return\fP 1i Specifies the reply geometry. .SS "Returns" A response to the request: \f(CWXtGeometryYes\fP, \f(CWXtGeometryNo\fP or \f(CWXtGeometryAlmost\fP. .\" .SH "Description" \f(CWXtGeometryHandler()\fP is the type of the Composite \f(CWgeometry_manager()\fP method, the Core and RectObj \f(CWquery_geometry()\fP method, and the Shell \f(CWroot_geometry_manager()\fP method. See the reference pages for those methods in Section 4 for more information. .\" .SH "See Also" .na \s-1\fIgeometry_manager\fR\s+1\*(s4, \s-1\fIquery_geometry\fR\s+1\*(s4, \s-1\fIroot_geometry_manager\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetActionKeysym" "Xt \- Translations and Actions" .XX "XtGetActionKeysym" .XX "actions:getting keysyms" .XX "keysyms:in action procedures" .SH "Name" .Na XtGetActionKeysym \- retrieve the keysym and modifiers that matched the final event specification in the translation table entry. .Nz .SH "Synopsis" .Sy KeySym XtGetActionKeysym(\f(CIevent\fP, \f(CImodifiers_return\fP) .As XEvent *\f(CIevent\fP; Modifiers *\f(CImodifiers_return\fP; .Ae .SS "Inputs" .IP \f(CIevent\fP .75i Specifies the event pointer passed to the action procedure by the Intrinsics. .SS "Outputs" .IP \f(CImodifiers_return\fP .75i Returns the modifier state actually used to generate the returned keysym. You may pass \f(CWNULL\fP if you are not interested in the modifiers. .SS "Returns" The keysym of the final event specification in the translation table entry that dispatched the current action, or \f(CWNoSymbol\fP. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtGetActionKeysym()\fR returns the keysym of the final event specification in the translation table entry that invoked the current action, provided that: .IP \(bu 3n \f(CWXtGetActionKeysym()\fR is called after an action procedure has been invoked by the Intrinsics and before that action procedure returns, .IP \(bu 3n the event pointer has the same value as the event pointer passed to that action routine, and .IP \(bu 3n the event is a \f(CWKeyPress\fR or a \f(CWKeyRelease\fR. .LP \f(CWXtGetActionKeysym()\fP also returns the modifiers actually used to generate this keysym if \f(CImodifiers_return\fR is non-\f(CWNULL\fR. .LP If \f(CWXtGetActionKeysym()\fP is not called from an action procedure, or if \f(CWevent\fP does not match the event that invoked the action, but if the event is a \f(CWKeyPress\fR or \f(CWKeyRelease\fR, then \f(CWXtGetActionKeysym()\fR calls \f(CWXtTranslateKeycode()\fR and returns the results. .LP If the event is not a \f(CWKeyPress\fR or \f(CWKeyRelease\fR, then \f(CWXtGetActionKeysym()\fR returns \f(CWNoSymbol\fR and does not examine \f(CImodifiers_return\fR. .LP Note that if an action procedure which was invoked by the Intrinsics invokes a subsequent action procedure (and so on) via \f(CWXtCallActionProc()\fR, the nested action procedure may also call \f(CWXtGetActionKeysym()\fR to retrieve the Intrinsics' keysym and modifiers. .\" .Nd 5 .SH "Usage" You should only call \f(CWXtGetActionKeysym()\fP from within an action procedure. When an action procedure is invoked on a \f(CWKeyPress\fP or \f(CWKeyRelease\fP event, it often has a need to retrieve the keysym and modifiers corresponding to the event that caused it to be invoked. In order to avoid repeating the processing that was just performed by the Intrinsics to match the translation entry, the keysym and modifiers are stored for the duration of the action procedure and can be obtained with this function. .\" .SH "Structures" A \f(CWKeySym\fP is an X server resource: .Ps typedef XID KeySym; .Pe The \f(CWModifiers\fP type and its possible values are as follows: .Ps typedef unsigned int Modifiers; #define ShiftMask (1<<0) #define LockMask (1<<1) #define ControlMask (1<<2) #define Mod1Mask (1<<3) #define Mod2Mask (1<<4) #define Mod3Mask (1<<5) #define Mod4Mask (1<<6) #define Mod5Mask (1<<7) .Pe .\" .SH "See Also" .na \s-1\fIXtActionProc\fR\s+1\*(s1, \s-1\fIXtAppAddActions\fR\s+1\*(s1, \s-1\fIXtTranslateKeycode\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetActionList" "Xt \- Translations and Actions" .XX "XtGetActionList" .XX "actions table, retrieving from a widget class" .SH "Name" .Na XtGetActionList \- get the action table of a widget class. .Nz .SH "Synopsis" .Sy void XtGetActionList(\f(CIwidget_class\fP, \f(CIactions_return\fP, \f(CInum_actions_return\fP) .As WidgetClass \f(CIwidget_class\fP; XtActionList *\f(CIactions_return\fP; Cardinal *\f(CInum_actions_return\fP; .Ae .SS "Inputs" .IP \f(CIwidget_class\fP 1.75i Specifies the widget class whose action table is to be returned; must be coreWidgetClass or any subclass. .SS "Outputs" .IP \f(CIactions_return\fP 1.75i Returns the action table of the widget class. .IP \f(CInum_actions_return\fP 1.75i Returns the number of elements in the action table. .\" .SH "Availability" Release 5 and later. .\" .SH "Description" \f(CWXtGetActionList\fP returns the action table defined by \f(CIwidget_class\fP in \f(CIactions_return\fP. This table does not include actions defined by the superclasses. .LP If \f(CIwidget_class\fP is not initialized, or is not \f(CWcoreWidgetClass\fP or a subclass thereof, or if the class does not define any actions, \f(CWNULL\fP will be returned in \f(CIactions_return\fP and zero will be returned in \f(CInum_actions_return\fP. If a non-\f(CWNULL\fP action table is returned, the application is responsible for freeing the table using \f(CWXtFree()\fP when it is no longer needed. .\" .SH "Structures" The \f(CWXtActionsRec\fP structure and the \f(CWXtActionList\fP type are defined as follows: .Ps typedef struct _XtActionsRec{ String string; XtActionProc proc; } XtActionsRec; typedef struct _XtActionsRec *XtActionList; .Pe .\" .SH "See Also" .na \s-1\fIXtActionProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtConvertSe 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtGetActionKeysym@XtGetActioA .sp .5 XtGetActionList@XtGetActioB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetApplicationNameAndClass" "Xt \- Application Contexts" .SH "Name" .XX "XtGetApplicationNameAndClass" .Na XtGetApplicationNameAndClass \- return the application name and class as passed to \f(CWXtDisplayInitialize()\fR for a particular Display. .Nz .SH "Synopsis" .Sy void XtGetApplicationNameAndClass(\f(CIdisplay\fP, \f(CIname_return\fP, \f(CIclass_return\fP) .As Display \f(CI*\fPdisplay; String \f(CI*\fPname_return; String \f(CI*\fPclass_return; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies an open display connection that has been initialized with \f(CWXtDisplayInitialize()\fR. .SS "Outputs" .IP \f(CIname_return\fP 1i Returns the application name. .IP \f(CIclass_return\fP 1i Returns the application class. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtGetApplicationNameAndClass()\fR returns the application name and class passed to \f(CWXtDisplayInitialize()\fR for the specified display. If the display was never initialized or has been closed, the result is undefined. The returned strings are owned by the Intrinsics and must not be modified or freed by the caller. .SH "See Also" .na \s-1\fIXtDisplayInitialize\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetApplicationResources" "Xt \- Resource Management" .SH "Name" .Na XtGetApplicationResources \- set application variables from the resource database. .Nz .XS "XtGetApplicationResources" .XX "resources:setting application values" .XX "resources:application resources" .XX "application resources" .SH "Synopsis" .Sy void XtGetApplicationResources(\f(CIobject\fP, \f(CIbase\fP, \f(CIresources\fP, \f(CInum_resources\fP, \f(CIargs\fP, \f(CInum_args\fP) .As Widget \f(CIobject\fP; XtPointer \f(CIbase\fP; XtResourceList \f(CIresources\fP; Cardinal \f(CInum_resources\fP; ArgList \f(CIargs\fP; Cardinal \f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object that identifies the resource database to search; may be of class Object or any subclass. .IP \f(CIbase\fP 1i Specifies the base address of the structure into which the resource values will be written. .IP \f(CIresources\fP 1i Specifies the application's resource list. .IP \f(CInum_resources\fP 1i Specifies the number of resources in the resource list. .IP \f(CIargs\fP 1i Specifies the argument list to override other resource specifications, or \f(CWNULL\fP. .IP \f(CInum_args\fP 1i Specifies the number of arguments in the argument list. .SS "Outputs" .IP \f(CIbase\fP 1i Returns the resource values from the argument list, the resource database, or the resource list defaults. .\" .SH "Description" \f(CWXtGetApplicationResources()\fP retrieves resource settings that apply to an overall application, rather than to a particular widget. For each resource in \f(CIresources\fP, \f(CWXtGetApplicationResource()\fP sets a value in the structure pointed to by \f(CIbase\fP. This value comes from the argument list \f(CIargs\fP, or if no value for the resource is found in the argument list, from the resource database associated with \f(CIobject\fP, or if no value is found in the database, from the \f(CIdefault_addr\fP field of the resource itself. Once the value is determined, it is copied into the structure at \f(CIbase\fP using the \f(CWresource_offset\fP and \f(CWresource_size\fP fields of the resource. .LP The search of the database is done using the \f(CWresource_name\fP and \f(CWresource_class\fP fields of the resource. Resources are searched for at the level in the resource name hierarchy at which \f(CWobject\fP's resources are found, i.e., application resources are set in a resource database in the same way as the specified object's resources are set. .LP \f(CWXtGetApplicationResources()\fR may overwrite the specified resource list with an equivalent representation in an internal format that optimizes access time if the list is used repeatedly. The resource list must be allocated in writable storage and the caller must not modify the list contents after the call if the same list is to be used again. Any per-display resources fetched by \f(CWXtGetApplicationResources()\fR will not be freed from the resource cache until the display is closed. .LP The use of each of the fields in the \f(CWXtResource\fP structure is explained in detail in the "Background" section below. .\" .SH "Usage" Any application that has any configurability should define application resources as an alternative to command line options and configuration files. To do this, you declare a structure that contains a field for each of the resource values you want to look up in the database. Then you statically initialize an array of \f(CWXtResource\fP structures which describe the name, class, type and default of each resource, and also specify the size of the resource value and the location within your structure at which it should be stored. Next you call \f(CWXtGetApplicationResources()\fP with the address of your structure and your application resource list, and possibly an argument list of values to override the database. When \f(CWXtGetApplicationResources()\fP returns, your structure will be initialized with values from the argument list, the resource database, or from the resource list defaults. The "Example" section below shows an example of this process, and the "Background" section explains each of the fields of an \f(CWXtResource\fP structure in more detail. .LP Usually, you will pass a the shell widget returned by \f(CWXtAppInitialize()\fP as \f(CIobject\fP. This will make \f(CWXtGetApplicationResources()\fP look up resources of the form \fIapplication_name\fP.\fIresource_name\fP. You may use any other widget or object, but this will make \f(CWXtGetApplicationResources()\fP look up resources that are deeper in the hierarchy, resources that appear to be resources of the specified widget. .\" .SH "Example" Here is a short program that declares and initializes an application resource list and uses it to get the value of some application resources. .Ps #include #include /* * fields to be filled in from resources */ typedef struct { Pixel highlight_color; XFontStruct *bold_font; Boolean palette_on_left; } application_variable_rec; static XtResource resources[] = { {"highlightColor", XtCForeground, XtRPixel, sizeof(Pixel), XtOffsetOf(application_variable_rec, highlight_color), XtRString, XtDefaultForeground }, {"boldFont", XtCFont, XtRFontStruct, sizeof(XFontStruct *), XtOffsetOf(application_variable_rec, bold_font), XtRString, XtDefaultFont }, {"paletteOnLeft", "PaletteOnLeft", XtRBoolean, sizeof(Boolean), XtOffsetOf(application_variable_rec, palette_on_left), XtRImmediate, True } }; main(argc, argv) int argc; char **argv; { XtAppContext app_context; Widget toplevel; application_variable_rec app_vars; toplevel = XtAppInitialize(&app_context, "XDraw", NULL, 0, &argc, argv, NULL, NULL, 0); XtGetApplicationResources(toplevel, /* widget */ &app_vars, /* base address */ resources, /* resource list */ XtNumber(resources), /* how many */ NULL, 0); /* ArgList */ . . . } .Pe If the application name is "xdraw", then the application resources can be set with lines like the following in a resource file: .Ps xdraw.highlightColor: blue xdraw.boldFont: *-helvetica-bold-r-*-*-*-180-* xdraw.paletteOnLeft: False .Pe .\" .SH "Background" To use \f(CWXtGetApplicationResources()\fP, you must initialize an array of \f(CWXtResource\fP structures which describe the resources you want to obtain. The \f(CWXtResource\fP structure is shown in the "Structures" section below. The fields of this structure are used as follows: .\" .IP \f(CWresource_name\fP .25i This field specifies the name of the resource, i.e., the name that must appear in a resource file to set this resource. By convention, the first letter of a resource name is lowercase, and any subsequent words are capitalized and concatenated without a hyphen or underscore\-"background" and "backgroundPixmap", for example. If you define a symbolic constant for the resource name, it should be the same as the resource name, with a prefix, which should end with an `N'\-XtNbackground or XmNbackgroundPixmap, for example. It is also convention that the field in which this resource's value will be stored has the same name as the resource, using all lowercase letters, and underscores to separate words--\f(CWbackground\fP and \f(CWbackground_pixmap\fP, for example. Resource names beginning with "xt" are reserved by the Intrinsics. .\" .IP \f(CWresource_class\fP .25i This field specifies the class name of the resource. If a number of resources have the same class, you can specify a value for all those resources with a single line in a resource file. The "normalFont" and "boldFont" resources might both be of class "Font", for example. Class names conventionally begin with capital letters, and, as with resource names, subsequent words are capitalized and underscores are not used. Symbolic names for class names are conventionally spelled the same way as the class name with a prefix which ends with `C'--XtCFont, for example. If there is no general category to use for a resource's class, the class should be the same as the resource name, but capitalized. Class names beginning with "Xt" are reserved by the Intrinsics. .\" .IP \f(CWresource_type\fP .25i This field is a string that identifies the type of the resource. By convention, it is spelled the same way as the type of the field that this resource will set, but begins with a capital letter. Symbolic names for resource types are spelled the same as the type name, but begin with a prefix which end with `R'--XtRInt and XmRFontList, for example. The Intrinsics predefine a number of types which are shown in the table below. Type names are used to identify which resource converter should be used to convert a string value from the resource database into the appropriate type. If one of your fields is not of one of the standard types listed below, use a type of your own, but be aware that you will have to write and register a converter procedure if you want to get values for that field from the resource database. .\" .IP \f(CWresource_size\fP .25i This field specifies the size in bytes of the field in your structure that this resource will set. Use the \f(CWsizeof()\fP operator to compute this value. .\" .IP \f(CWresource_offset\fP .25i This field specifies the offset of this resource's field from the beginning of the structure. This value is added to the \f(CIbase\fP argument passed to \f(CWXtGetApplicationResources()\fP in order to determine where the resource value is to be stored. This field plus the \f(CWresource_size\fP field provide enough information to correctly store the resource value. Use the \f(CWXtOffsetOf()\fP macro to determine the offset of a field in a structure. .\" .IP \f(CWdefault_type\fP .25i This is a string which specifies the type of the default value in the \f(CWdefault_addr\fP field. It is the same sort of type as the \f(CWresource_type\fP field explained above. The type of the default does not have to be the same as the type of resource. If they do not match, an appropriate resource converter will be invoked to convert the default value when it is required. In addition to the types listed in the table below, and any types of your own definition, there are two special values that can be set in this field. If \f(CWdefault_type\fP is\p \f(CWXtRImmediate\fP, then \f(CWdefault_addr\fP is interpreted as the resource value itself, rather than a pointer to the value. This is useful for resources that are integers, Booleans, or other scalar types. If \f(CWdefault_type\fP is \f(CWXtRCallProc\fP, then \f(CWdefault_addr\fP is pointer to a procedure of type \f(CWXtResourceDefaultProc\fP which is responsible for storing the default value in the correct location. See \f(CWXtResourceDefaultProc\fP(2) for details on the responsibilities of such a procedure. .\" .IP \f(CWdefault_addr\fP .25i This field specifies a pointer to the default value of the resource, which must be of the type identified by \f(CWdefault_type\fP. This field is interpreted differently for types\p \f(CWXtRImmediate\fP and \f(CWXtRCallProc\fP, as explained above. Also, if \f(CWdefault_type\fP is \f(CWXtRString\fP, then \f(CWdefault_addr\fP is the string itself, not the address of the string (i.e., it is a \f(CWchar *\fP, not a \f(CWchar **\fP). .LP The Intrinsics define symbolic names for a number of strings which represent commonly used types. These symbolic names and the types they represent are shown in the table below. .sp 1 .in 0 .KS .TS linesize(2),tab(@); l l l l lp6fCW lp6fCW lp6fCW lp6fCW. Resource Type@C Type@Resource Type@C Type .sp 2p XtRAcceleratorTable@XtAccelerators@XtRInitialState@int XtRAtom@Atom@XtRInt@int XtRBitmap@Pixmap, depth=1@XtRLongBoolean@long XtRBoolean@Boolean@XtRObject@Object XtRBool@Bool@XtRPixel@Pixel XtRCallback@XtCallbackList@XtRPixmap@Pixmap XtRCardinal@Cardinal@XtRPointer@XtPointer XtRColor@XColor@XtRPosition@Position XtRColormap@Colormap@XtRScreen@Screen* XtRCursor@Cursor@XtRShort@short XtRDimension@Dimension@XtRString@String XtRDisplay@Display*@XtRStringArray@String* XtREnum@XtEnum@XtRStringTable@String* XtRFile@FILE*@XtRTranslationTable@XtTranslations XtRFloat@float@XtRUnsignedChar@unsigned char XtRFont@Font@XtRVisual@Visual* XtRFontSet@XFontSet@XtRWidget@Widget XtRFontStruct@XFontStruct*@XtRWidgetClass@WidgetClass XtRFunction@(*)()@XtRWidgetList@WidgetList XtRGeometry@char*@XtRWindow@Window .sp 5p .TE .KE .in .sp 1 .\" .SH "Structures" \f(CWXtResource\fR is defined as follows: .Ps typedef struct _XtResource { String resource_name; /* Resource name */ String resource_class; /* Resource class */ String resource_type; /* Representation type desired */ Cardinal resource_size; /* Size in bytes of representation */ Cardinal resource_offset;/* Offset from base to put resource value */ .bp String default_type; /* Representation type of specified default */ XtPointer default_addr; /* Address of resource default value */ } XtResource, *XtResourceList; .Pe The \f(CWArgList\fP type is defined as follows: .Ps typedef struct { String name; XtArgVal value; } Arg, *ArgList; .Pe .SH "See Also" .na \s-1\fIXtGetSubresources\fR\s+1\*(s1, \s-1\fIXtOffsetOf\fR\s+1\*(s1. .ad .XE "XtGetApplicationResources" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtGetApplic 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtGetApplicationNameAndClass@XtGetAppliA .sp .5 XtGetApplicationResources@XtGetAppliB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetConstraintResourceList" "Xt \- Resource Management" .SH "Name" .XX "XtGetConstraintResourceList" .XX "constraint resources:XtGetConstraintResourceList" .XX "constraint resources:getting resource list" .XX "resources:getting constraint resource list" .Na XtGetConstraintResourceList \- get the constraint resource list structure for a particular widget class. .Nz .SH "Synopsis" .Sy void XtGetConstraintResourceList(\f(CIobject_class\fP, \f(CIresources_return\fP, \f(CInum_resources_return\fP) .As WidgetClass \f(CIobject_class\fP; XtResourceList *\f(CIresources_return\fP; Cardinal *\f(CInum_resources_return\fP; .Ae .SS "Inputs" .IP \f(CIobject_class\fP 1.5i Specifies the object class to be queried; may be of class objectClass or any subclass thereof. .SS "Outputs" .IP \f(CIresources_return\fP 1.5i Returns the constraint resource list. .IP \f(CInum_resources_return\fP 1.5i Returns the number of entries in the constraint resource list. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtGetConstraintResources()\fP returns the resource list of the constraintClassPart of the widget class \f(CIobject_class\fP. If it is called before the widget class is initialized, the resource list as specified in the widget class record will be returned. If it is called after the widget class has been initialized, the merged resource list for the class and all constraint superclasses is returned. If the specified \f(CIobject_class\fR is not a subclass of \f(CWconstraintWidgetClass\fR, \f(CI*resources_return\fP is set to \f(CWNULL\fR and *\f(CInum_resources_return\fR is set to zero. The list returned by \f(CWXtGetConstraintResourceList()\fR should be freed using \f(CWXtFree()\fR when it is no longer needed. .\" .SH "Usage" Most applications will never need to query a widget class for the resources it supports. This function is intended to support interface builders and applications like \fIeditres\fP which allow the use to view the available resources and set them interactively. .LP To get the normal resources of a widget rather than the constraint resources, use \f(CWXtGetResourceList()\fP. .SH "See Also" .na \s-1\fIXtGetResourceList\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetErrorDatabase" "Xt \- Error Handling" .SH "Name" .Na XtGetErrorDatabase \- obtain the error database. .XX "XtGetErrorDatabase" .SH "Synopsis" .Sy XrmDatabase *XtGetErrorDatabase() .\".As .Ae .SS "Inputs" none .SS "Returns" The address of an \f(CWXrmDatabase\fP. .\" .SH "Availability" \f(CWXtGetErrorDatabase()\fP has been superseded by \f(CWXtAppGetErrorDatabase()\fP. .\" .SH "Description" \f(CWXtGetErrorDatabase()\fP returns the address of the error database used by high-level error and warning handlers. This database may be empty until \f(CWXtGetErrorDatabaseText()\fP is called for the first time. .\" .SH "Usage" \f(CWXtGetErrorDatabase()\fP has been superseded by \f(CWXtAppGetErrorDatabase()\fP, which performs the same function on a per-application context basis. \f(CWXtGetErrorDatabase()\fP now calls \f(CWXtAppGetErrorDatabase()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtGetErrorDatabase()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppGetErrorDatabase()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppGetErrorDatabase()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtAppGetErrorDatabase\fR\s+1\*(s1, \s-1\fIXtAppGetErrorDatabaseText\fR\s+1\*(s1, \s-1\fIXtGetErrorDatabaseText\fR\s+1\*(s1, .br \s-1\fIXtErrorMsgHandler\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetErrorDatabaseText" "Xt \- Error Handling" .SH "Name" .Na XtGetErrorDatabaseText \- get the text of a named message from the error database. .Nz .SH "Synopsis" .Sy .hw buffer_return void XtGetErrorDatabaseText(\f(CIname\fP, \f(CItype\fP, \f(CIclass\fP, \f(CIdefault\fP, \f(CIbuffer_return\fP, \f(CInbytes\fP) .As String \f(CIname\fP, \f(CItype\fP, \f(CIclass\fP; String \f(CIdefault\fP; String \f(CIbuffer_return\fP; int \f(CInbytes\fP; .Ae .SS "Inputs" .IP \f(CIname\fP 1i Specifies the name or general kind of the message. .IP \f(CItype\fP 1i Specifies the type or detailed name of the message. .IP \f(CIclass\fP 1i Specifies the resource class of the error message. .IP \f(CIdefault\fP 1i Specifies the default message to use if an error database entry is not found. .IP \f(CInbytes\fP 1i Specifies the size of \f(CIbuffer_return\fP in bytes. .SS "Outputs" .IP \f(CIbuffer_return\fP 1i Specifies the buffer into which the error message is to be returned. .\" .SH "Availability" \f(CWXtGetErrorDatabaseText()\fP has been superseded by \f(CWXtAppGetErrorDatabaseText()\fP. .\" .SH "Description" \f(CWXtGetErrorDatabaseText()\fP looks up the message named by \f(CIname\fP, \f(CItype\fP, and \f(CIclass\fP in the database returned by \f(CWXtGetErrorDatabase()\fP. If such a message is found, it is stored into \f(CIbuffer_return\fP, otherwise the message in \f(CIdefault\fP is stored into \f(CIbuffer_return\fP. .LP The resource name of the message is formed by concatenating \f(CIname\fP and \f(CItype\fP with a single "." between them. The resource class of the message is \f(CIclass\fP if it already contains a ".", or otherwise is formed by concatenating \f(CIclass\fP with itself with a single "." between the strings. .\" .SH "Usage" \f(CWXtGetErrorDatabaseText()\fP has been superseded by \f(CWXtAppGetErrorDatabaseText()\fP, which performs the same function on a per-application context basis. \f(CWXtGetErrorDatabaseText()\fP now calls \f(CWXtAppGetErrorDatabaseText()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtGetErrorDatabaseText()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppGetErrorDatabaseText()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppGetErrorDatabaseText()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtAppGetErrorDatabase\fR\s+1\*(s1, \s-1\fIXtAppGetErrorDatabaseText\fR\s+1\*(s1, .br \s-1\fIXtErrorMsgHandler\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtGetErrorD 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtGetErrorDatabase@XtGetErrorA .sp .5 XtGetErrorDatabaseText@XtGetErrorB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetGC" "Xt \- Graphics Context" .SH "Name" .Na XtGetGC \- obtain a read-only, sharable GC. .XN "GCs (see graphics contexts)" .XS "graphics contexts, obtaining" .XS "graphics contexts, sharable" .XN "graphics contexts: (see also XtGetGC)" .Nz .XS "XtGetGC" .SH "Synopsis" .Sy GC XtGetGC(\f(CIobject\fP, \f(CIvalue_mask\fP, \f(CIvalues\fP) .As Widget \f(CIobject\fP; XtGCMask \f(CIvalue_mask\fP; XGCValues *\f(CIvalues\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object with which the GC is to be associated; may be of class Object or any subclass thereof. .IP \f(CIvalue_mask\fP 1i Specifies which fields of the GC are to be filled in with widget data. .IP \f(CIvalues\fP 1i Specifies the actual values for this GC. .SS "Returns" A read-only GC with fields as specified in \f(CIvalue_mask\fP and \f(CIvalues\fP. .SH "Description" \f(CWXtGetGC()\fP returns a sharable, read-only GC with values as specified in \f(CIvalues\fP for each bit set in \f(CIvalue_mask\fP. The GC is valid for the screen and depth of \f(CIobject\fP, or the nearest widget ancestor if \f(CIobject\fP is not a subclass of Core. .LP \f(CWXtGetGC()\fR shares only GCs in which all values in the GC are the same. In particular, it does not use the \f(CIvalue_mask\fR provided to determine which fields of the GC a widget considers relevant. \f(CIvalue_mask\fR is used only to tell the server which fields should be filled in with widget data and which it should fill in with default values. .SH "Usage" The Intrinsics provide a mechanism whereby widgets can share a graphics context (GC), reducing the number of GCs created and thereby improving server performance. The mechanism is a simple caching scheme, and all GCs obtained by means of this mechanism must be treated as read-only. .LP If a GC with modifiable fields is needed, in Release 4 or previous releases the Xlib \f(CWXCreateGC()\fR function must be used. In Release 5, \f(CWXtAllocateGC()\fP allows a widget to allocate a shared GC with modifiable fields. .LP Generally only widgets will need to allocate GCs, though some applications may also want to do so. When done with a shared GC, free it with \f(CWXtReleaseGC()\fP. .\" .SH "Structures" The \f(CWXtGCMask\fP type is defined as follows: .Ps \s-1typedef unsigned long XtGCMask; /* Mask of values that are used by widget*/\s+1 .Pe .Nd 10 Each of the symbols in the table below sets a single bit in an \f(CWXtGCMask\fP. The \f(CIvalue_mask\fP, argument is formed by combining these symbols with the bitwise OR operator (\^\fB \fP\^): .sp 1 .in 0 .KS .TS linesize(2),tab(@); lp6fCW lp6fCW lp6fCW. .sp 2p GCArcMode@GCFillRule@GCLineWidth GCBackground@GCFillStyle@GCPlaneMask GCCapStyle@GCFont@GCStipple GCClipMask@GCForeground@GCSubwindowMode GCClipXOrigin@GCFunction@GCTile GCClipYOrigin@GCGraphicsExposures@GCTileStipXOrigin GCDashList@GCJoinStyle@GCTileStipYOrigin GCDashOffset@GCLineStyle@ .sp 5p .TE .KE .in .sp 1 The \f(CWXGCValues\fP structure contains the GC fields: .Ps .ps 8 .vs 10 .ta +4.5n +2i typedef struct { int function; /* logical operation */ unsigned long plane_mask; /* plane mask */ unsigned long foreground; /* foreground pixel */ unsigned long background; /* background pixel */ int line_width; /* line width */ int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */ int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */ int join_style; /* JoinMiter, JoinRound, JoinBevel */ int fill_style; /* FillSolid, FillTiled, FillStippled, FillOpaqueStippled */ int fill_rule; /* EvenOddRule, WindingRule */ int arc_mode; /* ArcChord, ArcPieSlice */ Pixmap tile; /* tile pixmap for tiling operations */ Pixmap stipple; /* stipple 1 plane pixmap for stippling */ int ts_x_origin; /* offset for tile or int ts_y_origin; * stipple operations */ Font font; /* default text font for text operations */ int subwindow_mode; /* ClipByChildren, IncludeInferiors */ Bool graphics_exposures; /* should exposures be generated? */ int clip_x_origin; /* origin for clipping */ int clip_y_origin; Pixmap clip_mask; /* bitmap clipping; other calls for rects */ int dash_offset; /* patterned/dashed line information */ char dashes; } XGCValues; .ps .vs .Pe .SH "See Also" .na \s-1\fIXtAllocateGC\fR\s+1\*(s1, \s-1\fIXtReleaseGC\fR\s+1\*(s1. .ad .XE "graphics contexts, obtaining" .XE "graphics contexts, sharable" .XE "XtGetGC" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetKeysymTable" "Xt \- Keyboard Handling" .SH "Name" .XX "XtGetKeysymTable" .Na XtGetKeysymTable \- return a pointer to the keycode-to-keysym mapping table of a display. .Nz .SH "Synopsis" .Sy KeySym *XtGetKeysymTable(\f(CIdisplay\fP, \f(CImin_keycode_return\fP, .br \f(CIkeysyms_per_keycode_return\fP) .As Display *\f(CIdisplay\fP; KeyCode *\f(CImin_keycode_return\fP; int *\f(CIkeysyms_per_keycode_return\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the display whose table is required. .SS "Outputs" .IP \f(CImin_keycode_return\fP 1i Returns the minimum keycode valid for the display. .IP \f(CIkeysyms_per_keycode_return\fR 1i Returns the number of keysyms stored for each keycode. .SS "Returns" The keycode-to-keysym table for \f(CIdisplay\fP. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtGetKeysymTable()\fR returns a pointer to the Intrinsics' copy of the X server's keycode-to-keysym table, which must not be modified by the application. This table is simply an array of \f(CWKeySym\fP. The number of keysyms associated with each keycode is returned in \f(CIkeysyms_per_keycode_return\fR. The first keysyms in the table are for the keycode returned in \f(CImin_keycode_return\fP. The keysyms for a keycode \f(CIk\fP begin at index: .Ps \f(CIk\fP - \f(CImin_keycode_return\fP) * \f(CIkeysyms_per_keycode_return\fP .Pe Any entries in the table that have no keysyms associated with them contain the value \f(CWNoSymbol\fR. .\" .SH "Usage" The Intrinsics maintains a table internally to map keycodes to keysyms for each open display. The Translation Manager uses this table, and custom keycode-to-keysym translator procedures (see \f(CWXtSetKeyTranslator()\fP) and other clients may also need to use it. Most applications and widgets will never need to use this function. .LP You should not cache this keysym table but should call \f(CWXtGetKeysymTable()\fR each time the value is needed, because the table may change at any time. .\" .SH "See Also" .na \s-1\fIXtConvertCase\fR\s+1\*(s1, \s-1\fIXtKeysymToKeycodeList\fR\s+1\*(s1, \s-1\fIXtRegisterCaseConverter\fR\s+1\*(s1, \s-1\fIXtSetKeyTranslator\fR\s+1\*(s1, \s-1\fIXtTranslateKeycode\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetMultiClickTime" "Xt \- Mouse Handling" .SH "Name" .XX "XtGetMultiClickTime" .XX "multi-click time, setting" .Na XtGetMultiClickTime \- read the multi-click time. .Nz .SH "Synopsis" .Sy int XtGetMultiClickTime(\f(CIdisplay\fP) .As Display *\f(CIdisplay\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the display connection. .SS "Returns" The multi-click time for \f(CIdisplay\fP, in milliseconds. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtGetMultiClickTime()\fR returns the time in milliseconds that the translation manager uses to determine if multiple events are to be interpreted as a repeated event for purposes of matching a translation entry containing a repeat count. .LP Translation table entries may specify actions that are taken when two or more identical events occur consecutively, separated by a short time interval called the multi-click time. The multi-click time value can be specified as an application resource with name \f(CWmultiClickTime\fP and class \f(CWMultiClickTime\fP and can also be modified dynamically by the application (see \f(CWXtSetMultiClickTime()\fP). The multi-click time is unique for each Display and is retrieved from the resource database by \f(CWXtDisplayInitialize()\fR. If no value is specified, the initial value is 200 milliseconds. .SH "See Also" .na \s-1\fIXtSetMultiClickTime\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetResourceList" "Xt \- Resource Management" .SH "Name" .Na XtGetResourceList \- get the resource list of a widget class. .Nz .XS "XtGetResourceList" .XX "resources:getting resource list" .XX "resources:XtGetResourceList" .SH "Synopsis" .Sy void XtGetResourceList(\f(CIobject_class\fP, \f(CIresources_return\fP, \f(CInum_resources_return\fP); .As WidgetClass \f(CIobject_class\fP; XtResourceList *\f(CIresources_return\fP; Cardinal *\f(CInum_resources_return\fP; .Ae .SS "Inputs" .IP \f(CIobject_class\fP Specifies the object class to be queried; may be objectClass or any subclass. .SS "Outputs" .IP \f(CIresources_return\fP Returns the resource list. .IP \f(CInum_resources_return\fP Returns the number of entries in the resource list. .SH "Description" \f(CWXtGetResourceList()\fR returns the corePart resource list of the specified widget or object class. If it is called before the widget class is initialized it returns the resource list as specified in the widget class record. If it is called after the widget class has been initialized, it returns a merged resource list that includes the resources for all superclasses. The list returned by \f(CWXtGetResourceList()\fR should be freed using \f(CWXtFree()\fR when it is no longer needed. .\" .SH "Usage" Most applications will never need to query the a widget class for the resources it supports. This function is intended to support interface builders and applications like \fIeditres\fP which allow the use to view the available resources and set them interactively. .LP To get the constraint resources of a widget class, use \f(CWXtGetConstraintResourceList()\fP. .\" .SH "Structures" \f(CWXtResource\fR is defined as follows: .Ps typedef struct _XtResource { String resource_name; /* Resource name */ String resource_class; /* Resource class */ String resource_type; /* Representation type desired */ Cardinal resource_size; /* Size in bytes of representation */ Cardinal resource_offset;/* Offset from base to put resource value */ String default_type; /* Representation type of specified default */ XtPointer default_addr; /* Address of resource default value */ } XtResource, *XtResourceList; .Pe .SH "See Also" .na \s-1\fIXtGetConstraintResourceList\fR\s+1\*(s1. .ad .XE "XtGetResourceList" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetSelectionRequest" "Xt \- Selections" .SH "Name" .XX "XtGetSelectionRequest" .Na XtGetSelectionRequest \- retrieve the \f(CWSelectionRequest\fR event that triggered a \f(CWXtConvertSelectionProc\fR. .Nz .SH "Synopsis" .Sy XSelectionRequestEvent *XtGetSelectionRequest(\f(CIw\fP, \f(CIselection\fP, \f(CIrequest_id\fP) .As Widget \f(CIw\fP; Atom \f(CIselection\fP; XtRequestId \f(CIrequest_id\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget which currently owns this selection. .IP \f(CIselection\fP 1i Specifies the selection being processed. .IP \f(CIrequest_id\fP 1i Specifies the requestor ID in the case of incremental selections, or \f(CWNULL\fR in the case of atomic transfers. .SS "Returns" A pointer to a \f(CWSelectionRequest\fP event structure. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtGetSelectionRequest()\fR may only be called from within an \f(CWXtConvertSelectionProc\fR and returns a pointer to the \f(CWSelectionRequest\fR event which caused the procedure to be invoked. \f(CIrequest_id\fR specifies a unique ID for the individual request in the case that multiple incremental transfers are outstanding. For atomic transfers, \f(CIrequest_id\fR must be specified as \f(CWNULL\fR. If no \f(CWSelectionRequest\fR event is being processed for the specified widget, selection and ID, \f(CWXtGetSelectionRequest()\fR returns \f(CWNULL\fR. .SH "Usage" An \f(CWXtConvertSelectionProc\fP is not passed the event that triggered it, but it needs the timestamp of this event in order to comply with the ICCCM. \f(CWXtGetSelectionRequest()\fP was added in Release 4 as a work-around to this problem. .SH "See Also" .na \s-1\fIXtGetSelectionValue\fR\s+1\*(s1, \s-1\fIXtGetSelectionValueIncremental\fR\s+1\*(s1, \s-1\fIXtOwnSelection\fR\s+1\*(s1, .br \s-1\fIXtConvertSelectionProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetSelectionTimeout" "Xt \- Selections" .SH "Name" .Na XtGetSelectionTimeout \- get the current Intrinsics selection timeout value. .XX "XtGetSelectionTimeout" .Nz .SH "Synopsis" .Sy unsigned long XtGetSelectionTimeout() .As .Ae .SS "Inputs" none .SS "Returns" The selection timeout value. .\" .SH "Availability" \f(CWXtGetSelectionTimeout()\fP has been superseded by \f(CWXtAppGetSelectionTimeout()\fP. .\" .SH "Description" \f(CWXtGetSelectionTimeout()\fP returns the current selection timeout value, in milliseconds. The selection timeout is the time within which the two communicating applications must respond to one another. The initial timeout value is set by the \f(CWselectionTimeout\fP application resource, which defaults to 5000 milliseconds (5 seconds). .SH "Usage" \f(CWXtGetSelectionTimeout()\fP has been superseded by \f(CWXtAppGetSelectionTimeout()\fP, which performs the same function on a per-application context basis. \f(CWXtGetSelectionTimeout()\fP now calls \f(CWXtAppGetSelectionTimeout()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtGetSelectionTimeout()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppGetSelectionTimeout()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppGetSelectionTimeout()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtAppGetSelectionTimeout\fR\s+1\*(s1, \s-1\fIXtAppSetSelectionTimeout\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetSelectionValue" "Xt \- Selections" .SH "Name" .Na XtGetSelectionValue \- request the value of a selection. .XX "selections: selection data; obtaining" .XN "selections: data; (see also XtGetSelectionValue)" .Nz .XX "XtGetSelectionValue" .SH "Synopsis" .Sy .hw client_data void XtGetSelectionValue(\f(CIw\fP, \f(CIselection\fP, \f(CItarget\fP, \f(CIcallback\fP, \f(CIclient_data\fP, \f(CItime\fP) .As Widget \f(CIw\fP; Atom \f(CIselection\fP; Atom \f(CItarget\fP; XtSelectionCallbackProc \f(CIcallback\fP; XtPointer \f(CIclient_data\fP; Time \f(CItime\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that is making the request. Must be of class Core or any subclass thereof. .IP \f(CIselection\fP 1i .hw "XA-_SECONDARY" Specifies the particular selection desired (usually \s-1\f(CWXA_PRIMARY\fP\s0 .hw XA_SECONDARY or \s-1\f(CWXA_SECONDARY\fP\s0). .IP \f(CItarget\fP 1i Specifies the type of information about the selection that is being requested. .IP \f(CIcallback\fP 1i Specifies the callback procedure to be called when the selection value has been obtained. Note that this is how the selection value is communicated back to the client. .IP \f(CIclient_data\fP 1i Specifies an argument to be passed to \f(CIcallback\fP when it is called. .IP \f(CItime\fP 1i Specifies the timestamp that indicates when the selection is desired. This should be the timestamp of the event that triggered this request; the value \f(CWCurrentTime\fR is not acceptable. .\" .SH "Description" \f(CWXtGetSelectionValue()\fR initiates an ICCCM-compliant request to the owner of the selection identified by \f(CIselection\fP to convert that selection to the type identified by \f(CItarget\fP, and registers \f(CIcallback\fP as the procedure to be called (with \f(CIclient_data\fP as one of its arguments) when the converted value is ready. .LP \f(CIcallback\fR will be called some time after \f(CWXtGetSelectionValue()\fR is called. It may be called before or after \f(CWXtGetSelectionValue()\fR returns. If there is no owner for the selection or if the owner could not convert to the requested type, \f(CIcallback\fP will be called with a value of \f(CWNULL\fP and length zero. .LP If multiple calls to the server are required to get all the data, this will be transparent to the widget; the Intrinsics perform all the necessary fragmentation and reassembly of the selection. .LP See \f(CWXtSelectionCallbackProc\fP(2) for information on how to write a callback appropriate to register with this function. .\" .SH "Usage" Because of the asynchronous nature of interclient communication, it is not possible to call a function that returns the value of the selection immediately. When you need the value of the selection, to paste it into a widget, for example, you must call \f(CWXtGetSelectionValue()\fP and supply a callback which will be called at some later time. It is in this callback that you can actually perform your paste. .LP To determine the target types that the selection owner will be willing to return, intern the string "TARGETS" using \f(CWXInternAtom()\fP, and send the corresponding Atom as \f(CItarget\fR.\fP .LP To (atomically) request that a selection value be converted to several target types, use \f(CWXtGetSelectionValues()\fP. .\" .SH "See Also" .na \s-1\fIXtGetSelectionValues\fR\s+1\*(s1, \s-1\fIXtGetSelectionValueIncremental\fR\s+1\*(s1, \s-1\fIXtOwnSelection\fR\s+1\*(s1, .br \s-1\fIXtSelectionCallbackProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetSelectionValueIncremental" "Xt \- Selections" .SH "Name" .XX "XtGetSelectionValueIncremental" .Na XtGetSelectionValueIncremental \- obtain the selection value using incremental transfers. .Nz .SH "Synopsis" .Sy void XtGetSelectionValueIncremental(\f(CIw\fP, \f(CIselection\fP, \f(CItarget\fP, \f(CIcallback\fP, .br \f(CIclient_data\fP, \f(CItime\fP) .As Widget \f(CIw\fP; Atom \f(CIselection\fP; Atom \f(CItarget\fP; XtSelectionCallbackProc \f(CIcallback\fP; XtPointer \f(CIclient_data\fP; Time \f(CItime\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that is making the request. Must be of class Core or any subclass thereof. .IP \f(CIselection\fP 1i Specifies the particular selection desired (usually \s-1\f(CWXA_PRIMARY\fP\s0 or \s-1\f(CWXA_SECONDARY\fP\s0). .IP \f(CItarget\fP 1i Specifies the type of the information that is needed about the selection. .IP \f(CIcallback\fP 1i Specifies the callback procedure that is to be called to receive each data segment. .IP \f(CIclient_data\fP 1i Specifies client-specific data that is to be passed to the specified callback procedure when it is invoked. .IP \f(CItime\fP 1i Specifies the timestamp that indicates when the selection request was initiated. This should be the timestamp of the event which triggered this request; the value \f(CWCurrentTime\fR is not acceptable. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtGetSelectionValueIncremental()\fP initiates an ICCCM-compliant request to the owner of the selection identified by \f(CIselection\fP to convert the selected value to the type identified by \f(CItarget\fP, and registers \f(CIcallback\fP with the Intrinsics incremental selection interface as the procedure to call when segments of the requested value are delivered. .LP \f(CIcallback\fR will be called some time after \f(CWXtGetSelectionValue()\fR is called. It may be called before or after \f(CWXtGetSelectionValue()\fR returns. It will be called once for each segment of the selection value, and a final time with a non-\f(CWNULL\fP value (which must be freed) and a zero length. This final call is simply an indication that the transfer is complete. .LP If the transfer times out or is otherwise aborted before it completes, \f(CWcallback\fP will be called with \f(CItype\fP pointing to the atom \f(CWXT_CONVERT_FAIL\fP. In this case, the requestor must decide whether to abort the entire transfer or to proceed with the partially transferred selection. .LP If there is no owner for the selection or if the owner could not convert to the requested type, \f(CIcallback\fP will be called with a value of \f(CWNULL\fP and length zero. .LP See \f(CWXtSelectionCallbackProc\fP(2) for more information on how to write a callback appropriate to register with this function. .\" .SH "Usage" Because of the asynchronous nature of interclient communication, it is not possible to call a function that returns the value of the selection immediately. When you need the value of the selection, to paste it into a widget, for example, you must request the value of the selection and supply a callback which will be called at some later time. It is in this callback that you can actually perform your paste. .LP Most applications and widgets can use \f(CWXtGetSelectionValue()\fP which will call the specified callback exactly once with the value. Some selection \fIowners\fP will find it more natural to supply the selection value in an incremental fashion, delivering one piece at a time. This could be the case when the selection is large disjoint pieces of text in a text editor widget, for example. The selection \fIrequestor\fP may request selections incrementally, but is never required to do so\-the Intrinsics will coalesce an incrementally transferred value if the requestor requests it through the atomic \f(CWXtGetSelectionValue()\fP interface. .LP In some cases, however, it may be more natural to receive selection values through the incremental interface. Note that there is information in the boundaries of each segment that is transferred incrementally. This information is lost if the selection is coalesced into a single value. .LP See \f(CWXtGetSelectionValue()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtGetSelectionValue\fR\s+1\*(s1, \s-1\fIXtGetSelectionValuesIncremental\fR\s+1\*(s1, \s-1\fIXtOwnSelectionIncremental\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetSelectionValues" "Xt \- Selections" .SH "Name" .Na XtGetSelectionValues \- obtain selection data in multiple formats. .XS "selections: data; obtaining" .XN "selections: data; (see also XtGetSelectionValues)" .XS "XtGetSelectionValues" .SH "Synopsis" .Sy .hw callback void XtGetSelectionValues(\f(CIw\fP, \f(CIselection\fP, \f(CItargets\fP, \f(CIcount\fP, \f(CIcallback\fP, .br \f(CIclient_data\fP, \f(CItime\fP) .As Widget \f(CIw\fP; Atom \f(CIselection\fP; Atom *\f(CItargets\fP; int \f(CIcount\fP; XtSelectionCallbackProc \f(CIcallback\fP; XtPointer *\f(CIclient_data\fP; \f(CWTime \f(CItime\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that is making the request. Must be of class core or any subclass thereof. .hw "XA-_SECONDARY" .IP \f(CIselection\fP 1i Specifies the particular selection desired (usually \s-1\f(CWXA_PRIMARY\fP\s+1 .hw \s-1XA_SECONDARY\s+1 or \s-1\f(CWXA_SECONDARY\fP\s+1). .IP \f(CItargets\fP 1i Specifies the types of information about the selection that are being requested. .IP \f(CIcount\fP 1i Specifies the length of the \f(CItargets\fP and \f(CIclient_data\fR arrays. .IP \f(CIcallback\fP 1i Specifies the callback procedure to be called with each selection value obtained. Note that this is how the selection values are communicated back to the client. .IP \f(CIclient_data\fP 1i Specifies an array of client data (one for each target type) each element of which will be passed to \f(CIcallback\fP when it is called for the corresponding element of \f(CItargets\fP. .IP \f(CItime\fP 1i Specifies the timestamp that indicates when the selection value is desired. This should be the timestamp of the event that triggered this request; the value \f(CWCurrentTime\fR is not acceptable. .\" .SH "Description" \f(CWXtGetSelectionValues()\fR is similar to \f(CWXtGetSelectionValue()\fR except that it takes an array of target types and an array of client data and requests the current value of the selection converted to each of the targets. The callback is called once for each element of \f(CItargets\fP, and is passed the corresponding element of \f(CIclient_data\fP. The effect is as if each target were specified in a separate call to \f(CWXtGetSelectionValue()\fR, except that \f(CWXtGetSelectionValues()\fR guarantees that all the conversions will use the same selection value because the ownership of the selection cannot change in the middle of the list, as could happen when calling \f(CWXtGetSelectionValue()\fR repeatedly. .LP See \f(CWXtGetSelectionValue()\fP for more information. .SH "See Also" .na \s-1\fIXtGetSelectionValue\fR\s+1\*(s1, \s-1\fIXtGetSelectionValueIncremental\fR\s+1\*(s1, \s-1\fIXtGetSelectionValuesIncremental\fR\s+1\*(s1, .br \s-1\fIXtSelectionCallbackProc\fR\s+1\*(s2. .ad .XE "selections: data; obtaining" .XE "XtGetSelectionValues" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetSelectionValuesIncremental" "Xt \- Selections" .SH "Name" .XX "XtGetSelectionValuesIncremental" .Na XtGetSelectionValuesIncremental \- obtain multiple selection values using incremental transfers. .Nz .SH "Synopsis" .Sy void XtGetSelectionValuesIncremental(\f(CIw\fP, \f(CIselection\fP, \f(CItargets\fP, \f(CIcount\fP,\p \f(CIcallback\fP, \f(CIclient_data\fP, \f(CItime\fP) .As Widget \f(CIw\fP; Atom \f(CIselection\fP; Atom *\f(CItargets\fP; int \f(CIcount\fP; XtSelectionCallbackProc \f(CIcallback\fP; XtPointer *\f(CIclient_data\fP; Time \f(CItime\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that is making the request. .IP \f(CIselection\fP 1i Specifies the particular selection desired (usually \s-1\f(CWXA_PRIMARY\fP\s+1 or \s-1\f(CWXA_SECONDARY\fP\s+1). .IP \f(CItargets\fP 1i Specifies the types of information about the selection that are being requested. .IP \f(CIcount\fP 1i Specifies the length of the \f(CItargets\fP and \f(CIclient_data\fR arrays. .IP \f(CIcallback\fP 1i Specifies the callback procedure that is to be called to receive each selection value. .IP \f(CIclient_data\fP 1i Specifies an array of client data (one for each target type) each element of which will be passed to \f(CIcallback\fP when it is called for the corresponding element of \f(CItargets\fP. .IP \f(CItime\fP 1i Specifies the timestamp that indicates when the selection request was initiated. This should be the timestamp of the event which triggered this request; the value \f(CWCurrentTime\fR is not acceptable. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtGetSelectionValuesIncremental()\fR is similar to \f(CWXtGetSelectionValueIncremental()\fR except that it takes an array of target types and an array of client data and requests the current value of the selection be converted to each of the targets. The effect is as if each target were specified in a separate call to \f(CWXtGetSelectionValueIncremental()\fR, except that \f(CWXtGetSelectionValuesIncremental()\fR guarantees that all the conversions will use the same selection value because the ownership of the selection cannot change in the middle of the list, as could happen when calling \f(CWXtGetSelectionValueIncremental()\fR repeatedly. .LP Note that the callback procedure passed to \f(CWXtGetSelectionValuesIncremental()\fP must be prepared to receive a segment of data for any of the requested values. It is not guaranteed that all segments for one target will be delivered before any segments for the next target are delivered. .LP See \f(CWXtGetSelectionValueIncremental()\fP for more information. .SH "See Also" .na \s-1\fIXtGetSelectionValue\fR\s+1\*(s1, \s-1\fIXtGetSelectionValueIncremental\fR\s+1\*(s1, \s-1\fIXtGetSelectionValues\fR\s+1\*(s1, .br \s-1\fIXtSelectionCallbackProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtGetSelect 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtGetSelectionRequest@XtGetSelecA .sp .5 XtGetSelectionTimeout@XtGetSelecB .sp XtGetSelectionValue@XtGetSelecC .sp .5 XtGetSelectionValueIncremental@XtGetSelecD .sp .5 XtGetSelectionValues@XtGetSelecE .sp .5 XtGetSelectionValuesIncremental@XtGetSelecF .sp .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetSubresources" "Xt \- Resource Management" .SH "Name" .Na XtGetSubresources \- get subpart values from the resource database. .XS "resources: resource list; updating" .XN "resources: resource list; updating" .Nz .XS "XtGetSubresources" .SH "Synopsis" .Sy void XtGetSubresources(\f(CIobject\fP, \f(CIbase\fP, \f(CIsubpart_name\fP, \f(CIsubpart_class\fP, \f(CIresources\fP, \f(CInum_resources\fP, \f(CIargs\fP, \f(CInum_args\fP) .As Widget \f(CIobject\fP; XtPointer \f(CIbase\fP; String \f(CIsubpart_name\fP; String \f(CIsubpart_class\fP; XtResourceList \f(CIresources\fP; Cardinal \f(CInum_resources\fP; ArgList \f(CIargs\fP; Cardinal \f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object used to qualify the subpart resource name and class; may be of class Object or any subclass thereof. .IP \f(CIbase\fP 1i Specifies the base address of the subpart data structure into which the resource values will be written. .IP \f(CIsubpart_name\fP 1i Specifies the resource name of the subpart. .IP \f(CIsubpart_class\fP 1i Specifies the resource class name of the subpart. .IP \f(CIresources\fP 1i Specifies the resource list for the subpart. .IP \f(CInum_resources\fP 1i Specifies the number of resources in the resource list. .IP \f(CIargs\fP 1i Specifies the argument list to override any other resource specifications. .IP \f(CInum_args\fP 1i Specifies the number of arguments in the argument list. .SS "Outputs" .IP \f(CIbase\fP 1i Returns the resource values from the argument list, the resource database, or the resource list defaults. .\" .SH "Description" \f(CWXtGetSubresources()\fP is similar to \f(CWXtGetApplicationResources()\fP. It retrieves resource values for "subparts" of a widget or object that are not themselves widgets or objects. For each resource in \f(CIresources\fP, \f(CWXtGetSubresources()\fP sets a value in the structure pointed to by \f(CIbase\fP. This value comes from the argument list \f(CIargs\fP, or if no value for the resource is found in the argument list, from the resource database associated with \f(CIobject\fP, or if no value is found in the database, from the \f(CIdefault_addr\fP field of the resource itself. Once the value is determined, it is copied into the structure at \f(CIbase\fP using the \f(CWresource_offset\fP and \f(CWresource_size\fP fields of the resource. .LP The database is searched for resources that appear beneath the specified object in the name hierarchy\-subpart resources should be specified in a database as if as if the subpart were a child \f(CIobject\fP, with name \f(CIsubpart_name\fP and class \f(CIsubpart_class\fP. .LP \f(CWXtGetSubresources()\fR may overwrite the specified resource list with an equivalent representation in an internal format that optimizes access time if the list is used repeatedly. The resource list must be allocated in writable storage and the caller must not modify the list contents after the call if the same list is to be used again. Any per-display resources fetched by \f(CWXtGetSubresources()\fR will not be freed from the resource cache until the display is closed. .LP See \f(CWXtGetApplicationResources()\fP for an explanation and example of how to create a resource list. .\" .SH "Usage" Using subparts in a widget or object can be a useful way to modularize that object. The Release 3 Athena Text widget, for example, had subparts for its data source and data sink. In Release 4 and later, however, it is often easier to use non-widget objects instead of subparts. The Athena Text widget now uses this approach. .LP If you use subpart resources, the user will see the subpart hierarchy and will automatically be able to set subpart resources from a resource file. To allow the user to set and query subpart resources using the standard C \f(CWXtSetValues()\fP/\f(CWXtGetValues()\fP interface, however, your widget's \f(CWset_values()\fP (or \f(CWset_values_hook()\fP prior to Release 4) method must call \f(CWXtSetSubvalues()\fP and your \f(CWget_values_hook()\fP method must call \f(CWXtGetSubvalues()\fP. An alternative is to provide public functions with your widget to set and query subpart values. .LP Note that \f(CWXtGetSubresources()\fP differs from \f(CWXtGetApplicationResources()\fP in that it looks for resources in a named "subpart" of \f(CIobject\fP, rather than resources that appear at the same level in the hierarchy as \f(CIobject\fP's own resources. .LP You can use \f(CWXtVaGetSubresources()\fP to get subpart resource values using a variable length argument list rather than a single \f(CWArgList\fP argument. .\" .Nd 5 .SH "Structures" \f(CWXtResource\fR is defined as follows: .Ps .ps 8 typedef struct _XtResource { String resource_name; /* Resource name */ String resource_class; /* Resource class */ String resource_type; /* Representation type desired */ Cardinal resource_size; /* Size in bytes of representation */ Cardinal resource_offset;/* Offset from base to put resource value */ String default_type; /* Representation type of specified default */ XtPointer default_addr; /* Address of resource default value */ } XtResource, XtResourceList; .ps 0 .Pe .Nd 5 An \f(CWArg\fR is defined as follows: .Ps typedef struct { String name; XtArgVal value; } Arg, *ArgList; .Pe .SH "See Also" .na \s-1\fIXtGetApplicationResources\fR\s+1\*(s1, \s-1\fIXtGetSubvalues\fR\s+1\*(s1, \s-1\fIXtSetSubvalues\fR\s+1\*(s1, \s-1\fIXtVaGetSubresources\fR\s+1\*(s1, .br \s-1\fIget_values_hook\fR\s+1\*(s4, \s-1\fIset_values\fR\s+1\*(s4. .ad .XE "resources: resource list; updating" .XE "XtGetSubresources" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetSubvalues" "Xt \- Resource Management" .SH "Name" .Na XtGetSubvalues \- copy resource values from a subpart data structure to an argument list. .XS "resources: obtaining subpart values" .XS "subpart resources: obtaining values" .XS "XtGetSubvalues" .Nz .SH "Synopsis" .Sy void XtGetSubvalues(\f(CIbase\fP, \f(CIresources\fP, \f(CInum_resources\fP, \f(CIargs\fP, \f(CInum_args\fP) .As XtPointer \f(CIbase\fP; XtResourceList \f(CIresources\fP; Cardinal \f(CInum_resources\fP; ArgList \f(CIargs\fP; Cardinal \f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIbase\fP 1i Specifies the base address of the subpart data structure for which the resources should be retrieved. .IP \f(CIresources\fP 1i Specifies the subpart resource list. .IP \f(CInum_resources\fP 1i Specifies the number of resources in the resource list. .IP \f(CIargs\fP 1i Specifies an array of name/address pairs that contain the resource names and the addresses into which the resource values are to be stored. .IP \f(CInum_args\fP 1i Specifies the number of arguments in the argument list. .\" .SH "Description" For each argument in \f(CIargs\fP, \f(CWXtGetSubvalues()\fR uses the argument \f(CWname\fP field to look up the resource in \f(CIresources\fP, and uses the information in that resource structure to copy the resource value from the subpart structure pointed to by \f(CIbase\fP to the location specified by the argument \f(CWvalue\fP field. .LP If the argument list contains a resource name that is not found in the \f(CIresources\fP, the memory pointed to by the argument \f(CIvalue\fP field will not be modified. .LP The \f(CWvalue\fP field of each element in \f(CIargs\fP must contain the address into which to store the corresponding resource value. It is the caller's responsibility ensure that there is enough memory at the given location for the requested resource, and to free this memory if it was dynamically allocated. .LP See \f(CWXtGetApplicationResources()\fP for a description of the various fields of a \f(CWXtResource\fP structure and an example of initializing an \f(CWXtResourceList\fP. .\" .SH "Usage" \f(CWXtGetSubvalues()\fP is normally called in the \f(CWget_values_hook()\fP method of a widget with a subpart in order to get the values of requested subpart resources that cannot be automatically fetched by the widget. See \f(CWXtSetSubvalues()\fP for more information. .LP Note that an application cannot call \f(CWXtGetSubvalues()\fP for a widget because it does not have access to a widget's subpart resource list. .LP To set a widget's subpart resource values, see \f(CWXtSetSubvalues()\fR. .LP See \f(CWXtGetSubresources()\fP for more explanation of subpart resources. .LP To get subpart resource values using a variable-length argument list rather than a single \f(CWArgList\fP array, use \f(CWXtVaGetSubvalues()\fP. .\" .SH "Structures" \f(CWXtResource\fR is defined as follows: .Ps .ps 8 typedef struct _XtResource { String resource_name; /* Resource name */ String resource_class; /* Resource class */ String resource_type; /* Representation type desired */ Cardinal resource_size; /* Size in bytes of representation */ Cardinal resource_offset;/* Offset from base to put resource value */ String default_type; /* Representation type of specified default */ XtPointer default_addr; /* Address of resource default value */ } XtResource, XtResourceList; .ps 0 .Pe See \f(CWXtGetApplicationResources()\fP for an explanation of the fields of this structure. .LP An \f(CWArg\fR is defined as follows: .Ps typedef struct { String name; XtArgVal value; } Arg, *ArgList; .Pe .\" .SH "See Also" .na \s-1\fIXtGetSubresources\fR\s+1\*(s1, \s-1\fIXtVaGetSubvalues\fR\s+1\*(s1, .br \s-1\fIget_values_hook\fR\s+1\*(s4. .ad .\"last line comment .XE "resources: obtaining subpart values" .XE "subpart resources: obtaining values" .XE "XtGetSubvalues" .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGetValues" "Xt \- Resource Management" .SH "Name" .Na XtGetValues \- query widget resource values. .XS "resources: querying; XtGetValues" .Nz .XS "XtGetValues" .SH "Synopsis" .Sy void XtGetValues(\f(CIobject\fP, \f(CIargs\fP, \f(CInum_args\fP) .As Widget \f(CIobject\fP; ArgList \f(CIargs\fP; Cardinal \f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object whose resource values are to be returned; may be of class Object or any subclass thereof. .IP \f(CIargs\fP 1i Specifies the argument list of name/address pairs that contain the resource names and the addresses into which the resource values are to be stored. .IP \f(CInum_args\fP 1i Specifies the number of arguments in the argument list. .\" .SH "Description" \f(CWXtGetValues()\fR retrieves the current values of one or more resources associated with a widget instance. Each element in \f(CIargs\fP is an \f(CWArg\fP structure which contains the resource name in the \f(CWname\fP field, and a pointer to the location at which the resource is to be stored in the \f(CIvalue\fP field. It is the caller's responsibility to ensure that the \f(CWvalue\fP field points to a value of the correct type. If the \f(CWvalue\fP field points to allocated memory, the caller is also responsible for freeing that memory. .LP If \f(CIargs\fP contains a resource name that is not found in any of the resource lists searched, the value at the corresponding address is not modified. .LP Many widget resource values are simply copied from the widget to the specified address. When the resource is a pointer type (such as a string or pointer to a structure) some widgets will make a copy of the pointed to value and store the address of this copy at the specified address. If a copy is made, the caller is responsible for freeing the value when done with it. If no copy is made, then the returned value points to memory owned by the widget, and the caller must not modify or free this value in any way. None of the Intrinsics defined classes copy values in this way, nor do widgets in the Athena Widget set. See the documentation for the particular resource of the particular widget you are using to determine if a copy is made. .LP If a resource value which is a pointer type is returned without being copied, then the returned value may not remain valid indefinitely. The Intrinsics specify lifetimes for the following resources: The \f(CWXtNchildren\fP resource of Composite widgets and any callback list resource are only valid until some operation (such as \f(CWXtCreateWidget()\fP or \f(CWXtAddCallback()\fP) modifies the resource. The \f(CWXtNtranslations\fP and \f(CWXtNaccelerators\fP Core resources remain valid at least until the widget is destroyed. The \f(CWXtNscreen\fP Core resource remains valid until the Display is closed. See the documentation for the particular resource of the particular widget you are using to determine its lifetime. .LP The "Background" section below explains in detail how \f(CWXtGetValues()\fP finds the requested resource values. .\" .SH "Usage" Generally you will use the \f(CWXtSetArg()\fP macro to initialize the \f(CWArgList\fP passed to this function. You can also use \f(CWXtVaGetValues()\fP pass it a variable-length argument list instead of an \f(CWArgList\fP array. The "Example" section below shows an example use of this function. .LP Note that some widgets provide public functions to query the value of commonly used resources. These functions are generally faster, and it is usually better specified whether or not the caller must free the returned value. .LP You can \fIset\fP a widget's resources with \f(CWXtSetValues()\fP or \f(CWXtVaSetValues()\fP. .\" .SH "Example" You can use \f(CWXtGetValues()\fP as follows to get widget resources: .Ps Arg args[10]; int i; String label; Dimension margin; Pixel color; /* set up an argument list */ i = 0; XtSetArg(args[i], XtNlabel, &label); i++; XtSetArg(args[i], XtNmargin, &margin); i++; XtSetArg(args[i], XtNforeground, &color); i++; /* query the values */ XtGetValues(s, args, i); /* label, margin, and color now contain the requested values */ printf("Widget's label is %s; margin is %d.\n", label, margin); printf("Widget's label is %s; margin is %d.\n", label, margin); /* In some widget sets we'd have to free label now. */ /* XtFree(label); */ .Pe .\" .SH "Background" \f(CWXtGetValues()\fP looks for resources named in \f(CIargs\fP using the following procedure: .IP \(bu 3n It searches the normal resource lists for the object, starting with the resources of the Object class and proceeding down the subclass chain to the class of the object. .IP \(bu 3n If the object's parent is a subclass of constraintWidgetClass, it searches the constraint resource lists of the parent, starting at constraintWidgetClass and proceeding down the subclass chain to the constraint resources of the parent's class. .LP Once all the resources have been fetched from the widget's normal and constraint resources list, \f(CWXtGetValues()\fP calls the widget's \f(CWget_values_hook()\fP methods. .XX "get_values_hook" \f(CWget_values_hook()\fP procedures can be used to return subpart resource values or constraint subpart resource values through the \f(CWXtGetValues()\fP interface (see \f(CWXtGetSubvalues()\fP) and may modify the data stored at the location addressed by the \f(CWvalue\fP field of the argument. This means that a \f(CWget_values_hook()\fP may be used to make copies of data (such as strings) whose resource representation is a pointer. The \f(CWget_values_hook()\fP methods are called as follows: .IP \(bu 3n If any \f(CWget_values_hook()\fP methods in the object's class or superclass records are non-\f(CWNULL\fP, they are called in superclass-to-subclass order. .IP \(bu 3n If the object's parent is a subclass of constraintWidgetClass, and if any of the parent's class or superclass records have declared \f(CWConstraintClassExtension\fP records in the Constraint class part \f(CWextension\fP field with a record type of \f(CW\s-1NULLQUARK\s+1\fP and if the \f(CWget_values_hook()\fP field in the extension record is non-\f(CWNULL\fP, then \f(CWXtGetValues()\fP calls these \f(CWget_values_hook()\fP procedures in superclass-to-subclass order. .LP .\" .SH "Structures" An \f(CWArg\fR is defined as follows: .Ps typedef struct { String name; XtArgVal value; } Arg, *ArgList; .Pe .SH "See Also" .na \s-1\fIXtSetArg\fR\s+1\*(s1, \s-1\fIXtSetValues\fR\s+1\*(s1, \s-1\fIXtVaGetValues\fR\s+1\*(s1, \s-1\fIXtVaSetValues\fR\s+1\*(s1, .br \s-1\fIget_values_hook\fR\s+1\*(s4. .ad .XE "resources: querying; XtGetValues" .XE "XtGetValues" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGrabButton" "Xt \- Mouse Handling" .SH "Name" .XS "XtGrabButton" .Na XtGrabButton \- passively grab a single pointer button. .Nz .SH "Synopsis" .Sy void XtGrabButton(\f(CIwidget\fP, \f(CIbutton\fP, \f(CImodifiers\fP, \f(CIowner_events\fP, \f(CIevent_mask\fP, \f(CIpointer_mode\fP, \f(CIkeyboard_mode\fP, \f(CIconfine_to\fP, \f(CIcursor\fP) .As Widget \f(CIwidget\fP; int \f(CIbutton\fP; Modifiers \f(CImodifiers\fP; Boolean \f(CIowner_events\fP; unsigned int \f(CIevent_mask\fP; int \f(CIpointer_mode\fP, \f(CIkeyboard_mode\fP; Window \f(CIconfine_to\fP; Cursor \f(CIcursor\fP; .Ae .SS "Inputs" .IP \f(CIwidget\fP 1i Specifies the widget in whose window the button is to be grabbed. Must be of class Core or any subclass thereof. .IP \f(CIbutton\fP 1i Specifies the mouse button which is to be grabbed. .IP \f(CImodifiers\fP 1i Specifies the modifiers that must be down to trigger the grab. .IP \f(CIowner_events\fP 1i Specifies whether pointer events generated during the grab are reported normally within the application (\f(CWTrue\fP) or only to the specified widget (\f(CWFalse\fP). .IP \f(CIevent_mask\fP 1i Specifies the event mask to take effect during the grab. .IP \f(CIpointer_mode\fP 1i Controls processing of pointer events during the grab. Either \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .IP \f(CIkeyboard_mode\fP 1i Controls processing of keyboard events during the grab. Either \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .IP \f(CIconfine_to\fP 1i Specifies the ID of the window to confine the pointer, or \f(CWNone\fP. .IP \f(CIcursor\fP 1i Specifies the cursor to be displayed during the grab, or \f(CWNone\fP. .\" .SH "Description" \f(CWXtGrabButton()\fR calls \f(CWXGrabButton()\fR to establish a passive button grab. It specifies the widget's window as the \f(CIgrab_window\fP, and passes its remaining arguments directly to \f(CWXGrabButton()\fR. If the widget is not realized, the call to \f(CWXGrabButton()\fR will be performed when the widget is realized and its window becomes mapped. If the widget is unrealized and later realized again, the call to \f(CWXGrabButton()\fP will be performed again. .LP The \f(CIbutton\fP argument may be \f(CWButton1\fP, \f(CWButton2\fP, \f(CWButton3\fP, \f(CWButton4\fP, \f(CWButton5\fP, or \f(CWAnyButton\fP. The constant \f(CWAnyButton\fP is equivalent to issuing the grab request for all possible buttons. The button symbols cannot be ORed together. .LP The \f(CImodifiers\fP argument is a bitwise OR of one or more of the following symbols: \f(CWShiftMask\fP, \f(CWLockMask\fP, \f(CWControlMask\fP, \f(CWMod1Mask\fP, \f(CWMod2Mask\fP, \f(CWMod3Mask\fP, \f(CWMod4Mask\fP, \f(CWMod5Mask\fP, or \f(CW AnyModifier\fP. \f(CWAnyModifier\fP is equivalent to issuing the grab key request for all possible modifier combinations (including no modifiers). .LP See \f(CWXtGrabPointer()\fP for an explanation of the \f(CIowner_events\fP, \f(CIevent_mask\fP, \f(CIpointer_mode\fP, \f(CIkeyboard_mode\fP, \f(CIconfine_to\fP, and \f(CIcursor\fP arguments. .LP See the "Background" section below for a description of event handling when a passive button grab is triggered. .\" .SH "Usage" When you passively grab a button/modifiers combination, all events that occur when that button and those modifiers are down will be delivered to the window you specify or to your application, regardless of the location of the pointer. Button grabs can be used by applications like \fIxmag\fP and window managers which need to use the pointer to indicate a point on or a region of the screen, regardless of the applications that are under the pointer. .LP You should rarely need to use this function. An automatic grab takes place between a \f(CWButtonPress\fP event and the corresponding \f(CWButtonRelease\fP event, so this call is not necessary in some of the most common situations. It may be necessary for some styles of menus, however. .LP Note that \f(CWXtAddGrab()\fP and spring-loaded popups perform a similar function, but without issuing any X server grabs. .LP To cancel a passive button grab, use \f(CWXtUngrabButton()\fP. .\" .SH "Background" After making this call, if \f(CWXtDispatchEvent()\fP is called with a \f(CWButtonPress\fP event matching the specified \f(CIbutton\fP and \f(CImodifiers\fP (which may be \f(CWAnyButton\fP or \f(CWAnyModifier\fP, respectively) for the widget's window, the Intrinsics will undo the grab by calling \f(CWXtUngrabPointer()\fP with the timestamp from the \f(CWButtonPress\fP event if either of the following conditions is true: .IP \(bu 3n There is a modal cascade and the widget is not in the active subset of the cascade and the pointer was not previously grabbed, or .IP \(bu 3n \f(CWXFilterEvent()\fP returns \f(CWTrue\fP. .LP Otherwise, after making this call, the pointer will be actively grabbed (as for \f(CWXtGrabPointer()\fP), the last-pointer-grab time will be set to the time at which the button was pressed (as transmitted in the \f(CWButtonPress\fP event), and the \f(CWButtonPress\fP event will be reported if all of the following conditions are true: .IP \(bu 3n The pointer is not grabbed, and the specified button is logically pressed when the specified modifier keys are logically down, and no other buttons or modifier keys are logically down. .IP \(bu 3n The \f(CIgrab_window\fP contains the pointer. .IP \(bu 3n The \f(CIconfine_to\fP window (if any) is viewable. .IP \(bu 3n A passive grab on the same button/key combination does not exist on any ancestor of \f(CIgrab_window.\fP .LP The active grab is terminated automatically when the logical state of the pointer has all buttons released (independent of the state of the logical modifier keys). .LP Note that the logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen. .LP This request overrides all previous grabs by the same client on the same button/key combinations on the same window. A modifiers of \f(CWAnyModifier\fP is equivalent to issuing the grab request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned \f(CWKeyCodes\fP. A button of \f(CWAnyButton\fP is equivalent to issuing the request for all possible buttons. Otherwise, it is not required that the specified button currently be assigned to a physical button. .LP If some other client has already issued a \f(CWXGrabButton()\fP with the same button/key combination on the same window, a \f(CWBadAccess\fP error results. When using \f(CWAnyModifier\fP or \f(CWAnyButton\fP, the request fails completely, and a \f(CWBadAccess\fP error results (no grabs are established) if there is a conflicting grab for any combination. \f(CWXGrabButton()\fP has no effect on an active grab. .SH "See Also" .na \s-1\fIXtAddGrab\fR\s+1\*(s1, \s-1\fIXtGrabKey\fR\s+1\*(s1, \s-1\fIXtGrabKeyboard\fR\s+1\*(s1, \s-1\fIXtGrabPointer\fR\s+1\*(s1, \s-1\fIXtRegisterGrabAction\fR\s+1\*(s1, \s-1\fIXtUngrabButton\fR\s+1\*(s1, \s-1\fIXtUngrabKey\fR\s+1\*(s1, \s-1\fIXtUngrabKeyboard\fR\s+1\*(s1, \s-1\fIXtUngrabPointer\fR\s+1\*(s1. .ad .\"last line comment .XE "XtGrabButton" .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGrabKey" "Xt \- Keyboard Handling" .SH "Name" .XS "XtGrabKey" .Na XtGrabKey \- passively grab a single key of the keyboard. .Nz .hw keyboard .SH "Synopsis" .Sy void XtGrabKey(\f(CIwidget\fP, \f(CIkeycode\fP, \f(CImodifiers\fP, \f(CIowner_events\fP, \f(CIpointer_mode\fP, .br \f(CIkeyboard_mode\fP) .As Widget \f(CIwidget\fP; KeyCode \f(CIkeycode\fP; Modifiers \f(CImodifiers\fP; Boolean \f(CIowner_events\fP; int \f(CIpointer_mode\fP, \f(CIkeyboard_mode\fP; .Ae .SS "Inputs" .ft R .IP \f(CIwidget\fP 1i Specifies the widget in whose window the key is to be grabbed. Must be of class Core or any subclass thereof. .IP \f(CIkeycode\fP 1i Specifies the keycode to be grabbed. It may be a modifier key. Specifying \f(CWAnyKey\fP is equivalent to issuing the request for all key codes. .IP \f(CImodifiers\fP 1i Specifies a set of modifiers that must be down to trigger the grab. .IP \f(CIowner_events\fP 1i Specifies whether events generated during the grab are reported normally within the application (\f(CWTrue\fP) or only to the specified widget (\f(CWFalse\fP). .IP \f(CIpointer_mode\fP 1i Controls processing of pointer events during the grab. Either \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .IP \f(CIkeyboard_mode\fP 1i Controls processing of keyboard events during the grab. Either \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .\" .SH "Description" \f(CWXtGrabKey()\fR calls \f(CWXGrabKey()\fR to establish a passive grab on the key specified by \f(CIkeycode\fP. It specifies the widget's window as the \f(CIgrab_window\fP and passes its remaining arguments unmodified. If the widget is not realized, the call to \f(CWXGrabKey()\fR will be performed when the widget is realized and its window becomes mapped. If the widget is unrealized and later realized again, the call to \f(CWXGrabKey()\fP will be performed again. .LP The \f(CImodifiers\fP argument is a bitwise OR of one or more of the following symbols: \f(CWShiftMask\fP, \f(CWLockMask\fP, \f(CWControl Mask\fP, \f(CWMod1Mask\fP, \f(CWMod2Mask\fP, \f(CWMod3Mask\fP, \f(CWMod4Mask\fP, \f(CWMod5Mask\fP, or \f(CW AnyModifier\fP. \f(CWAnyModifier\fP is equivalent to issuing the grab key request for all possible modifier combinations (including no modifiers). .LP See \f(CWXtGrabKeyboard()\fP for a description of the \f(CIowner_events\fP, \f(CIpointer_mode\fP, and \f(CIkeyboard_mode\fP arguments. .LP See the "Description" section below for details of event processing when an passive key grab is triggered. .\" .SH "Usage" When you passively grab a key/modifiers combination, all events that occur when that button and those modifiers are down will be delivered to your widget's window or to your application, regardless of the location of the pointer. Key grabs can be used by applications like window managers that want to define keyboard "hot keys" that invoke a particular function regardless of which application is currently in use. .LP Most applications will never need to issue a grab. \f(CWXtAddGrab()\fP (called by \f(CWXtPopup()\fP) can be used to implement modal popups inside an application, and \f(CWXtSetKeyboardFocus()\fP can be used to redirect keyboard focus within an application. Neither function actually issues a grab, and so does not interrupt event processing by other clients. .LP To cancel a passive key grab, use \f(CWXtUngrabKey()\fP. .\" .SH "Background" After this call, if \f(CWXtDispatchEvent()\fP is called with a \f(CWKeyPress\fP event matching the specified \f(CIkeycode\fP and \f(CImodifiers\fP (which may be \f(CWAnyKey\fP or \f(CWAnyModifier\fP, respectively) for the widget's window, the Intrinsics will undo the grab by calling \f(CWXtUngrabKeyboard()\fP with the timestamp from the \f(CWKeyPress\fP event if either of the following conditions is true: .IP \(bu 3n There is a modal cascade and the widget is not in the active subset of the cascade and the keyboard was not previously grabbed, or .IP \(bu 3n \f(CWXFilterEvent()\fP returns \f(CWTrue\fP. .LP Otherwise, after this call, the keyboard will be actively grabbed (as for \f(CWXGrabKeyboard()\fP), the last-keyboard-grab time will be set to the time at which the key was pressed (as transmitted in the \f(CWKeyPress\fP event), and the \f(CWKeyPress\fP event will be reported if all of the following conditions are true: .IP \(bu 3n The keyboard is not grabbed and the specified key (which can itself be a modifier key) is logically pressed when the specified modifier keys are logically down, and no other modifier keys are logically down. .IP \(bu 3n Either the \f(CIgrab_window\fP is an ancestor of (or is) the focus window, or the \f(CIgrab_window\fP is a descendant of the focus window and contains the pointer. .IP \(bu 3n A passive grab on the same key combination does not exist on any ancestor of \f(CIgrab_window.\fP .LP The active grab is terminated automatically when the logical state of the keyboard has the specified key released (independent of the logical state of the modifier keys). .LP Note that the logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen. .LP A \f(CImodifiers\fP argument of \f(CWAnyModifier\fP is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned \f(CWKeyCodes\fP. A \f(CIkeycode\fP argument of \f(CWAnyKey\fP is equivalent to issuing the request for all possible \f(CWKeyCodes\fP. Otherwise, the specified keycode must be .ne 2 in the range specified by \f(CWmin_keycode\fP and \f(CWmax_keycode\fP in the connection setup, or a \f(CWBadValue\fP error results. .LP If some other client has issued a \f(CWXGrabKey()\fP with the same key combination on the same window, a \f(CWBadAccess\fP error results. When using \f(CWAnyModifier\fP or \f(CWAnyKey\fP, the request fails completely, and a \f(CWBadAccess\fP error results (no grabs are established) if there is a conflicting grab for any combination. .LP \f(CWXGrabKey()\fP can generate \f(CWBadAccess\fP, \f(CWBadValue\fP, and \f(CWBadWindow\fP errors. .\" .SH "See Also" .na \s-1\fIXtAddGrab\fR\s+1\*(s1, \s-1\fIXtGrabButton\fR\s+1\*(s1, \s-1\fIXtGrabKeyboard\fR\s+1\*(s1, \s-1\fIXtGrabPointer\fR\s+1\*(s1, \s-1\fIXtRegisterGrabAction\fR\s+1\*(s1, \s-1\fIXtSetKeyboardFocus\fR\s+1\*(s1, \s-1\fIXtUngrabButton\fR\s+1\*(s1, \s-1\fIXtUngrabKey\fR\s+1\*(s1, \s-1\fIXtUngrabKeyboard\fR\s+1\*(s1, \s-1\fIXtUngrabPointer\fR\s+1\*(s1. .ad .\"last line comment .XE "XtGrabKey" .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGrabKeyboard" "Xt \- Keyboard Handling" .SH "Name" .XX "XtGrabKeyboard" .Na XtGrabKeyboard \- actively grab the keyboard. .Nz .SH "Synopsis" .Sy int XtGrabKeyboard(\f(CIwidget\fP, \f(CIowner_events\fP, \f(CIpointer_mode\fP, \f(CIkeyboard_mode\fP, \f(CItime\fP) .As Widget \f(CIwidget\fP; Boolean \f(CIowner_events\fP; int \f(CIpointer_mode\fP, \f(CIkeyboard_mode\fP; Time \f(CItime\fP; .Ae .SS "Inputs" .IP \f(CIwidget\fP 1i Specifies the widget for whose window the keyboard is to be grabbed. Must be of class Core or any subclass thereof. .IP \f(CIowner_events\fP 1i Specifies whether the pointer events are to be reported normally within this application (pass \f(CWTrue\fR) or only to the grab window (pass \f(CWFalse\fR). .IP \f(CIpointer_mode\fP 1i Controls processing of pointer events during the grab. Either \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .IP \f(CIkeyboard_mode\fP 1i Controls processing of keyboard events during the grab. Either \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .IP \f(CItime\fP 1i Specifies the time when the grab should take place. Pass either a timestamp (from an event) or the constant \f(CWCurrentTime\fP. .\" .SH "Description" If the specified widget is realized \f(CWXtGrabKeyboard()\fR calls \f(CWXGrabKeyboard()\fR specifying the widget's window as the \f(CIgrab_window\fP, passing its remaining argument unmodified, and returning whatever \f(CWXGrabKeyboard()\fP returns. If the widget is not realized, \f(CWXGrabKeyboard()\fR immediately returns \f(CWGrabNotViewable\fR. No future automatic ungrab is implied by \f(CWXtGrabKeyboard()\fR. .LP See the "Background" section below for a description of the arguments and an explanation of event processing during an active keyboard grab. .\" .SH "Usage" When the keyboard is grabbed, all key events are delivered to the widget you specify or to your application, regardless of the location of the pointer. There are not many occasions when this is a reasonable thing to do, because it locks out input to other applications. \fIxterm\fP grabs the keyboard to implement secure mode. .LP Most applications will never need to issue a grab. \f(CWXtAddGrab()\fP (called by \f(CWXtPopup()\fP) can be used to implement modal popups inside an application, and \f(CWXtSetKeyboardFocus()\fP can be used to redirect keyboard focus within an application. Neither function actually issues a grab, and so does not interrupt event processing by other clients. .LP To cancel an active keyboard grab, use \f(CWXtUngrabKeyboard()\fP. .\" .SH "Background" The \f(CWXGrabKeyboard()\fP function actively grabs control of the keyboard and generates \f(CWFocusIn\fP and \f(CWFocusOut\fP events. Further key events are reported only to the grabbing client. \f(CWXGrabKeyboard()\fP overrides any active keyboard grab by this client. If \f(CIowner_events\fP is \f(CWFalse\fP, all generated key events are reported with respect to \f(CIgrab_window.\fP If \f(CIowner_events\fP is \f(CWTrue\fP and if a generated key event would normally be reported to this client, it is reported normally; otherwise, the event is reported with respect to the \f(CIgrab_window.\fP Both \f(CWKeyPress\fP and \f(CWKeyRelease\fP events are always reported, independent of any event selection made by the client. .LP If the \f(CIkeyboard_mode\fP argument is \f(CWGrabModeAsync\fP, keyboard event processing continues as usual. If the keyboard is currently frozen by this client, then processing of keyboard events is resumed. If the \f(CIkeyboard_mode\fP argument is \f(CWGrabModeSync\fP, the state of the keyboard (as seen by client applications) appears to freeze, and the X server generates no further keyboard events until the grabbing client issues a releasing \f(CWXAllowEvents()\fP call or until the keyboard grab is released. Actual keyboard changes are not lost while the keyboard is frozen; they are simply queued in the server for later processing. .LP If \f(CIpointer_mode\fP is \f(CWGrabModeAsync\fP, pointer event processing is unaffected by activation of the grab. If \f(CIpointer_mode\fP is \f(CWGrabModeSync\fP, the state of the pointer (as seen by client applications) appears to freeze, and the X server generates no further pointer events until the grabbing client issues a releasing \f(CWXAllowEvents()\fP call or until the keyboard grab is released. Actual pointer changes are not lost while the pointer is frozen; they are simply queued in the server for later processing. .LP If the keyboard is actively grabbed by some other client, \f(CWXGrabKeyboard()\fP fails and returns \f(CWAlreadyGrabbed\fP. If \f(CIgrab_window\fP is not viewable, it fails and returns \f(CWGrabNotViewable\fP. If the keyboard is frozen by an active grab of another client, it fails and returns \f(CWGrabFrozen\fP. If the specified time is earlier than the last-keyboard-grab time or later than the current X server time, it fails and returns \f(CWGrabInvalidTime\fP. Otherwise, the last-keyboard-grab time is set to the specified time (\f(CWCurrentTime\fP is replaced by the current X server time). .LP \f(CWXGrabKeyboard()\fP can generate \f(CWBadValue\fP and \f(CWBadWindow\fP errors. .\" .SH "See Also" .na \s-1\fIXtAddGrab\fR\s+1\*(s1, \s-1\fIXtGrabButton\fR\s+1\*(s1, \s-1\fIXtGrabKey\fR\s+1\*(s1, \s-1\fIXtGrabPointer\fR\s+1\*(s1, \s-1\fIXtRegisterGrabAction\fR\s+1\*(s1, \s-1\fIXtUngrabButton\fR\s+1\*(s1, \s-1\fIXtUngrabKey\fR\s+1\*(s1, \s-1\fIXtUngrabKeyboard\fR\s+1\*(s1, \s-1\fIXtUngrabPointer\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtGrabPointer" "Xt \- Mouse Handling" .SH "Name" .XX "XtGrabPointer" .Na XtGrabPointer \- actively grab the pointer. .Nz .SH "Synopsis" .Sy int XtGrabPointer(\f(CIwidget\fP, \f(CIowner_events\fP, \f(CIevent_mask\fP, \f(CIpointer_mode\fP, \f(CIkeyboard_mode\fP, .br \f(CIconfine_to\fP, \f(CIcursor\fP, \f(CItime\fP) .As Widget \f(CIwidget\fP; Boolean \f(CIowner_events\fP; unsigned int \f(CIevent_mask\fP; int \f(CIpointer_mode\fP, \f(CIkeyboard_mode\fP; Window \f(CIconfine_to\fP; Cursor \f(CIcursor\fP; Time \f(CItime\fP; .Ae .SS "Inputs" .IP \f(CIwidget\fP 1i Specifies the widget for whose window the pointer is to be grabbed. Must be of class Core or any subclass thereof. .IP \f(CIowner_events\fP 1i Specifies whether the pointer events are to be reported normally within this application (pass \f(CWTrue\fR) or only to the grab window (pass \f(CWFalse\fR). .IP \f(CIevent_mask\fP 1i Specifies the event mask to take effect during the grab. .IP \f(CIpointer_mode\fP 1i Controls processing of pointer events during the grab. Either \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .IP \f(CIkeyboard_mode\fP 1i Controls processing of keyboard events during the grab. Either \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .IP \f(CIconfine_to\fP 1i Specifies the ID of the window to confine the pointer, or \f(CWNone\fP. .IP \f(CIcursor\fP 1i Specifies the cursor to be displayed during the grab, or \f(CWNone\fP. .IP \f(CItime\fP 1i Specifies the time when the grab request took place. Pass either a timestamp (from an event), or the constant \f(CWCurrentTime\fP. .SS "Returns" \f(CWGrabSuccess\fP or one of the error values described below. .\" .SH "Description" If the specified widget is realized, \f(CWXtGrabPointer()\fR establishes an active pointer grab by calling \f(CWXGrabPointer()\fR with the widget's window as the grab window and passing the remaining arguments unmodified. It returns the value returned by \f(CWXGrabPointer()\fP. If the widget is not realized, \f(CWXGrabPointer()\fR immediately returns \f(CWGrabNotViewable\fR. No future automatic ungrab is implied by \f(CWXtGrabPointer()\fR. .LP See the "Background" section below for a description of the arguments and an explanation of event processing during an active pointer grab. .\" .SH "Usage" When the pointer is grabbed, all pointer events will be delivered to the widget you specify or to the rest of your application, regardless of the location of the pointer. Pointer grabs can be used by applications like \fIxmag\fP and window managers which need to use the pointer to indicate a point on or a region of the screen, regardless of the applications that are under the pointer. .LP Most applications never need to grab the pointer. Note that \f(CWXtAddGrab()\fP does not actually grab anything. .LP To cancel an active pointer grab, use \f(CWXtUngrabPointer()\fP. .\" .SH "Background" \f(CWXGrabPointer()\fP actively grabs control of the pointer and returns \f(CWGrabSuccess\fP if the grab was successful. Further pointer events are reported only to the grabbing client. \f(CWXGrabPointer()\fP overrides any active pointer grab by this client. If \f(CIowner_events\fP is \f(CWFalse\fP, all generated pointer events are reported with respect to \f(CIgrab_window\fP and are reported only if selected by \f(CIevent_mask.\fP If \f(CIowner_events\fP is \f(CWTrue\fP and if a generated pointer event would normally be reported to this client, it is reported as usual. Otherwise, the event is reported with respect to the \f(CIgrab_window\fP and is reported only if selected by \f(CIevent_mask.\fP For either value of \f(CIowner_events\fP, unreported events are discarded. .LP If the \f(CIpointer_mode\fP is \f(CWGrabModeAsync\fP, pointer event processing continues as usual. If the pointer is currently frozen by this client, the processing of events for the pointer is resumed. If the \f(CIpointer_mode\fP is \f(CWGrabModeSync\fP, the state of the pointer, as seen by client applications, appears to freeze, and the X server generates no further pointer events until the grabbing client calls \f(CWXAllowEvents()\fP or until the pointer grab is released. Actual pointer changes are not lost while the pointer is frozen; they are simply queued in the server for later processing. .LP If the \f(CIkeyboard_mode\fP is \f(CWGrabModeAsync\fP, keyboard event processing is unaffected by activation of the grab. If the \f(CIkeyboard_mode\fP is \f(CWGrabModeSync\fP, the state of the keyboard, as seen by client applications, appears to freeze, and the X server generates no further keyboard events until the grabbing client calls \f(CWXAllowEvents()\fP or until the pointer grab is released. Actual keyboard changes are not lost while the pointer is frozen; they are simply queued in the server for later processing. .LP If \f(CIcursor\fP is specified, it is displayed regardless of what window the pointer is in. If \f(CWNone\fP is specified, the normal cursor for that window is displayed when the pointer is in \f(CIgrab_window\fP or one of its subwindows; otherwise, the cursor for \f(CIgrab_window\fP is displayed. .LP If a \f(CIconfine_to\fP window is specified, the pointer is restricted to stay contained in that window. The \f(CIconfine_to\fP window need have no relationship to the \f(CIgrab_window.\fP If the pointer is not initially in the \f(CIconfine_to\fP window, it is warped automatically to the closest edge just before the grab activates and enter/leave events are generated as usual. If the \f(CIconfine_to\fP window is subsequently reconfigured, the pointer is warped automatically, as necessary, to keep it contained in the window. .LP The \f(CItime\fP argument allows you to avoid certain circumstances that come up if applications take a long time to respond or if there are long network delays. Consider a situation where you have two applications, both of which normally grab the pointer when clicked on. If both applications specify the timestamp from the event, the second application may wake up faster and successfully grab the pointer before the first application. The first application then will get an indication that the other application grabbed the pointer before its request was processed. .LP \f(CWXGrabPointer()\fP generates \f(CWEnterNotify\fP and \f(CWLeaveNotify\fP events. .LP Either if \f(CIgrab_window\fP or \f(CIconfine_to\fP window is not viewable or if the \f(CIconfine_to\fP window lies completely outside the boundaries of the root window, \f(CWXGrabPointer()\fP fails and returns \f(CWGrabNotViewable\fP. If the pointer is actively grabbed by some other client, it fails and returns \f(CWAlreadyGrabbed\fP. If the pointer is frozen by an active grab of another client, it fails and returns \f(CWGrabFrozen\fP. If the specified time is earlier than the last-pointer-grab time or later than the current X server time, it fails and returns \f(CWGrabInvalidTime\fP. Otherwise, the last-pointer-grab time is set to the specified time (\f(CWCurrentTime\fP is replaced by the current X server time). .LP \f(CWXGrabPointer()\fP can generate \f(CWBadCursor\fP, \f(CWBadValue\fP, and \f(CWBadWindow\fP errors. .\" .SH "Structures" Each of the event types listed in the table below set a single bit in an event mask. The \f(CIevent_mask\fP argument is formed by combining these symbols with the bitwise OR operator (\^\fB \fR\^). Note that the nonmaskable event types do not appear in this table and cannot be requested in an event mask. .sp 1 .in 0 .KS .TS linesize(2),tab(@); lp7fCW lp7fCW lp7fCW. .sp 2p NoEventMask@Button1MotionMask@StructureNotifyMask KeyPressMask@Button2MotionMask@ResizeRedirectMask KeyReleaseMask@Button3MotionMask@SubstructureNotifyMask ButtonPressMask@Button4MotionMask@SubstructureRedirectMask ButtonReleaseMask@Button5MotionMask@FocusChangeMask EnterWindowMask@ButtonMotionMask@PropertyChangeMask LeaveWindowMask@KeymapStateMask@ColormapChangeMask PointerMotionMask@ExposureMask@OwnerGrabButtonMask PointerMotionHintMask@VisibilityChangeMask .sp 5p .TE .KE .in .sp 1 .SH "See Also" .na \s-1\fIXtAddGrab\fR\s+1\*(s1, \s-1\fIXtGrabButton\fR\s+1\*(s1, \s-1\fIXtGrabKey\fR\s+1\*(s1, \s-1\fIXtGrabKeyboard\fR\s+1\*(s1, \s-1\fIXtRegisterGrabAction\fR\s+1\*(s1, \s-1\fIXtUngrabButton\fR\s+1\*(s1, \s-1\fIXtUngrabKey\fR\s+1\*(s1, \s-1\fIXtUngrabKeyboard\fR\s+1\*(s1, \s-1\fIXtUngrabPointer\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtHasCallbacks" "Xt \- Callbacks" .SH "Name" .Na XtHasCallbacks \- determine the status of a widget's callback list. .XX "callbacks: callback list; determining status" .XN "widgets: callback list (see callbacks)" .XX "callbacks: callback list; XtHasCallbacks" .XX "XtHasCallbacks" .Nz .SH "Synopsis" .Sy \f(CWXtCallbackStatus XtHasCallbacks(\f(CIobject\fP, \f(CIcallback_name\fP) .As Widget \f(CIobject\fP; String \f(CIcallback_name\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1.2i Specifies the object; may be of class Object or any subclass thereof. .IP \f(CIcallback_name\fP Specifies the callback list to be checked. .SS "Returns" An \f(CWXtCallbackStatus\fP value. .SH "Description" \f(CWXtHasCallbacks()\fR checks the widget for a resource named \f(CIcallback_name\fR. If the resource does not exist or is not of type \f(CWXtRCallback\fR, \f(CWXtHasCallbacks()\fR returns \f(CWXtCallbackNoList\fR. If the callback list exists but is empty, it returns \f(CWXtCallbackHasNone\fR. If the callback list contains at least one callback procedure, it returns \f(CWXtCallbackHasSome\fR. .SH "Structures" .Ps .ta 4.5n 2.5i typedef enum { XtCallbackNoList, XtCallbackHasNone, XtCallbackHasSome } XtCallbackStatus; .Pe .SH "See Also" .na .\"Section 1.3, "Application Interface," .br \s-1\fIXtAddCallbacks\fR\s+1\*(s1, \s-1\fIXtCallCallbacks\fR\s+1\*(s1, \s-1\fIXtCallCallbackList\fR\s+1\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtInitProc" "Xt \- Widget Method Prototypes" .SH "Name" .Na XtInitProc \- interface definition for the \f(CWinitialize()\fP methods. .Nz .XX "XtInitProc" .SH "Synopsis" .Sy typedef void (*XtInitProc)(Widget, Widget, ArgList, Cardinal *); .As Widget \f(CIrequest\fP; Widget \f(CIinit\fP; ArgList \f(CIargs\fP; Cardinal *\f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIrequest\fP 1i Specifies the widget with resource values as requested by the argument list, the resource database, and the widget defaults, before any initialization. .IP \f(CIinit\fP 1i Specifies a widget with resource and nonresource values modified by calls to the widget's superclasses'\f(CWinitialize()\fP methods. .IP \f(CIargs\fP 1i Specifies the argument list passed to \f(CWXtCreateWidget()\fP. .IP \f(CInum_args\fP 1i Specifies the number of arguments in \f(CIargs\fP. .\" .SH "Description" \f(CWXtInitProc\fP is the type of the Core and Object \f(CWinitialize()\fP method and the Constraint \f(CWinitialize()\fP method. See the \f(CWinitialize()\fP reference pages in Section 4. .\" .SH "See Also" .na \s-1\fIinitialize\fR\s+1\*(s4, \s-1\fIConstraint initialize\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtInitialize" "Xt \- Initialization" .SH "Name" .Na XtInitialize \- initialize toolkit and display. .Nz .XS "toolkits, XtInitialize" .XS "XtInitialize" .SH "Synopsis" .Sy Widget XtInitialize(\f(CIshell_name\fP, \f(CIapplication_class\fP, \f(CIoptions\fP, \f(CInum_options\fP, \f(CIargc\fP, \f(CIargv\fP) .As String \f(CIshell_name\fP; /* unused */ String \f(CIapplication_class\fP; XrmOptionDescRec \f(CIoptions\fP[]; Cardinal \f(CInum_options\fP; Cardinal *\f(CIargc\fP; char *\f(CIargv\fP[]; .Ae .SS "Inputs" .IP \f(CIshell_name\fP 1i This parameter is ignored; you can specify \f(CWNULL\fP. .IP \f(CIapplication_class\fP 1i Specifies the class name of this application. .IP \f(CIoptions\fP 1i Specifies how to parse the command line for any application-specific resources. The options argument is passed as a parameter to \f(CWXtDisplayInitialize()\fR. .IP \f(CInum_options\fP 1i Specifies the number of entries in options list. .IP \f(CIargc\fP 1i Specifies a pointer to the number of command line parameters. .IP \f(CIargv\fP 1i Specifies the command line parameters. .SS "Outputs" .IP \f(CIargc\fP 1i Returns the number of command line arguments remaining after the command line is parsed with \f(CWXtDisplayInitialize()\fP .IP \f(CIargv\fP 1i Returns the command line as modified by \f(CWXtDisplayInitialize()\fP. .SS "Returns" A toplevel applicationShell widget. .\" .SH "Availability" \f(CWXtInitialize()\fP has been superseded by \f(CWXtAppInitialize()\fP. .\" .SH "Description" \f(CWXtInitialize()\fP is a convenience function for initializing an Xt application. It calls \f(CWXtToolkitInitialize()\fP to initialize the toolkit internals, creates a default application context for use by other superseded functions, calls \f(CWXtOpenDisplay()\fP with \f(CIdisplay_string\fP \f(CWNULL\fP and \f(CIapplication_name\fP \f(CWNULL\fP, and finally calls \f(CWXtAppCreateShell()\fP with \f(CIapplication_name\fP \f(CWNULL\fP and returns the created shell. The semantics of calling \f(CWXtInitialize()\fP more than once are undefined. .\" .Nd 5 .SH "Usage" \f(CWXtInitialize()\fP has been superseded in Release 4 by \f(CWXtAppInitialize()\fP, which is a more general initialization function which supports multiple application contexts and fallback resources, among other things. There are a number of Xt functions that have been superseded by "XtApp" versions that take an application context as an argument. If you want to use these superseded functions, you must initialize your application with \f(CWXtInitialize()\fP which creates the default application context that these functions all use. .LP If you do not want to use multiple application contexts, multiple displays, or fallback resources, you can continue to use \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppInitialize()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtAppCreateShell\fR\s+1\*(s1, \s-1\fIXtAppInitialize\fR\s+1\*(s1, \s-1\fIXtOpenDisplay\fR\s+1\*(s1, \s-1\fIXtToolkitInitialize\fR\s+1\*(s1. .ad .XE "toolkits, XtInitialize" .XE "XtInitialize" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtInitializeWidgetClass" "Xt \- Initialization" .SH "Name" .XX "XtInitializeWidgetClass" .Na XtInitializeWidgetClass \- initialize a widget class without creating any widgets. .Nz .SH "Synopsis" .Sy void XtInitializeWidgetClass(\f(CIobject_class\fP) .As WidgetClass \f(CIobject_class\fP; .Ae .\" .SS "Inputs" .IP \f(CIobject_class\fP 1.25i Specifies the object class to initialize; may be of class objectClass or any subclass thereof. .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtInitializeWidgetClass()\fP initializes a widget class in the same way that XtCreateWidget does, but without creating any widgets. It checks the \f(CWclass_inited\fP field of the specified class and all its superclasses, in superclass-to-subclass order, and if that field is \f(CWFalse\fP for any class, it calls the \f(CWclass_initialize()\fP and \f(CWclass_part_initialize()\fP methods for the class and all of its superclasses. Finally, the \f(CWclass_inited\fP field of the specified class is set to nonzero. .LP If the specified widget class is already initialized, \f(CWXtInitializeWidgetClass()\fR returns immediately. .\" .SH "Usage" A widget class is automatically initialized when the first instance of a widget is created; few applications will need to use this function. .LP If a class initialization procedure registers type converters, those type converters are not available until the first object of the class or subclass is created or until \f(CWXtInitializeWidgetClass()\fR is called. This function was added in Release 4 so that the \f(CWXtVaTypedArg\fP feature of \f(CWXtVaCreateWidget()\fP can be used to convert a resource value while creating the first instance of a particular widget class. .SH "See Also" .na \s-1\fIXtVaCreateWidget\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtInitializ 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtInitialize@XtInitialiA .sp .5 XtInitializeWidgetClass@XtInitialiB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtInputCallbackProc" "Xt \- Event Handling" .SH "Name" .Na XtInputCallbackProc \- interface definition for procedure to handle file, pipe, or socket activity. .Nz .XS "XtInputCallbackProc" .XN "files: file events; (see XtInputCallbackProc)" .SH "Synopsis" .Sy .nf typedef void (*XtInputCallbackProc)(XtPointer, int *, XtInputId *); .fi .As XtPointer \f(CIclient_data\fP; int *\f(CIsource\fP; XtInputId *\f(CIid\fP; .Ae .SS "Inputs" .IP \f(CIclient_data\fP 1i Specifies the data that was registered with this procedure in \f(CWXtAppAddInput()\fR. .IP \f(CIsource\fP 1i Specifies the file descriptor (on POSIX systems) that generated the event. .IP \f(CIid\fP 1i Specifies the ID that was returned when this procedure was registered with \f(CWXtAppAddInput()\fR call. .\" .SH "Description" An \f(CWXtInputCallbackProc\fP is registered with \f(CWXtAppAddInput()\fP. It is called when there is activity of the specified type (read, write, or error) on a specified file descriptor (which can be a file, pipe, or socket). .LP An \f(CWXtInputCallbackProc\fP should do whatever is necessary to handle the activity on the alternate event source. If EOF is read on the descriptor, the procedure can un-register itself by passing its \f(CIid\fP argument to \f(CWXtRemoveInput()\fP. .SH "Usage" An \f(CWXtInputCallbackProc\fP is inherently operating-system-dependent and will have to be ported when the widget or application is ported to a new operating system. On non-POSIX systems, the \f(CIsource\fP argument is some OS-dependent identifier of an input source. .\" .SH "Example" The procedure below is an \f(CWXtInputCallbackProc\fP from the \f(CWxconsole\fP client (which is new in X11R5). Note that it reads input with the POSIX \f(CWread()\fP system call, and that it closes the file descriptor and removes the input source if it reaches EOF or gets an error on the input source. .Ps static void inputReady (w, source, id) XtPointer w; int *source; XtInputId *id; { char buffer[1025]; int n; n = read (*source, buffer, sizeof (buffer) - 1); if (n <= 0) { fclose (input); XtRemoveInput (*id); } Notify (); buffer[n] = '\0'; if (app_resources.stripNonprint) { stripNonprint (buffer); n = strlen (buffer); } TextAppend ((Widget) text, buffer, n); } .Pe This procedure is registered with the following call: .Ps input_id = XtAddInput (fileno (input), (XtPointer) XtInputReadMask, inputReady, (XtPointer) text); .Pe .\" .SH "See Also" .na \s-1\fIXtAppAddInput\fR\s+1\*(s1, \s-1\fIXtRemoveInput\fR\s+1\*(s1. .ad .XE "XtInputCallbackProc" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtInsertEventHandler" "Xt \- Event Handling" .SH "Name" .XS "XtInsertEventHandler" .Na XtInsertEventHandler \- register an event handler procedure that receives events before or after all previously registered event handlers. .Nz .SH "Synopsis" .Sy .ti -10n void XtInsertEventHandler(\f(CIw\fP, \f(CIevent_mask\fP, \f(CInonmaskable\fP, \f(CIproc\fP, \f(CIclient_data\fP, \f(CIposition\fP) .As Widget \f(CIw\fP; EventMask \f(CIevent_mask\fP; Boolean \f(CInonmaskable\fP; XtEventHandler \f(CIproc\fP; XtPointer \f(CIclient_data\fP; XtListPosition \f(CIposition\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget for which this event handler is being registered. Must be of class core or any subclass thereof. .IP \f(CIevent_mask\fP 1i Specifies the event mask for which to call this procedure. .IP \f(CInonmaskable\fP 1i Specifies whether this procedure should be called on nonmaskable events .IP \f(CIproc\fP 1i Specifies the procedure that is to be called. .IP \f(CIclient_data\fP 1i Specifies additional data to be passed to the client's event handler. .IP \f(CIposition\fP 1i Specifies when the event handler is to be called relative to other previously registered handlers. .\" .SH "Availability" Release 4 and later. .\" .SH "Description \f(CWXtInsertEventHandler()\fR registers the procedure \f(CIproc\fP and the data \f(CIclient_data\fP with the Intrinsics event dispatching mechanism. When an event of one of the types set in \f(CIevent_mask\fP occurs on the window of the widget \f(CIw\fP, \f(CIproc\fP will be invoked and \f(CIclient_data\fP passed as one of its arguments. .LP The argument \f(CIposition\fP specifies where in the list of event handlers \f(CIproc\fP should be inserted. If it is \f(CWXtListHead\fP, \f(CIproc\fP will be inserted at the beginning of the list and will be called before all previously registered handlers. If it is \f(CWXtListTail\fP, \f(CIproc\fP will be inserted at the end of the list and will be called after all previously registered handlers. .LP If the procedure is already registered with the same \f(CIclient_data\fP, the specified \f(CIevent_mask\fP augments the existing mask, and the procedure is repositioned in the list according to \f(CIposition\fP. .LP \f(CWXtInsertEventHandler()\fR is identical to \f(CWXtAddEventHandler()\fR with the additional \f(CIposition\fP argument. See \f(CWXtAddEventHandler()\fP for more information. .LP See \f(CWXtEventHandler\fP(2) for an explanation of how to write an event handler procedure. .\" .SH "Usage" Neither applications nor widgets often need to use event handlers. Using action procedures and translation tables provides a more flexible way to respond to input events. .\" .SH "Structures" The \f(CWXtListPosition\fP type is as follows. .Ps typedef enum { XtListHead, XtListTail } XtListPosition; .Pe See \f(CWXtAddEventHandler()\fP for a list of bits that can be set in the \f(CIevent_mask\fP argument. .\" .SH "See Also" .na \s-1\fIXtAddEventHandler\fR\s+1\*(s1, \s-1\fIXtAddRawEventHandler\fR\s+1\*(s1, \s-1\fIXtInsertRawEventHandler\fR\s+1\*(s1, \s-1\fIXtRemoveEventHandler\fR\s+1\*(s1, \s-1\fIXtRemoveRawEventHandler\fR\s+1\*(s1. .ad .\"last line comment .XE "XtInsertEventHandler" .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtInsertRawEventHandler" "Xt \- Event Handling" .SH "Name" .XS "XtInsertRawEventHandler" .Na XtInsertRawEventHandler \- register an event handler procedure that receives events before or after all previously registered event handlers, without selecting for the events. .Nz .SH "Synopsis" .Sy void XtInsertRawEventHandler(\f(CIw\fP, \f(CIevent_mask\fP, \f(CInonmaskable\fP, \f(CIproc\fP, \f(CIclient_data\fP, \f(CIposition\fP) .As Widget \f(CIw\fP; EventMask \f(CIevent_mask\fP; Boolean \f(CInonmaskable\fP; XtEventHandler \f(CIproc\fP; XtPointer \f(CIclient_data\fP; XtListPosition \f(CIposition\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. .IP \f(CIevent_mask\fP 1i Specifies the event mask for which to call this procedure. .IP \f(CInonmaskable\fP 1i Specifies a Boolean value that indicates whether this procedure should be called on nonmaskable events .IP \f(CIproc\fP 1i Specifies the procedure that is to be registered. .IP \f(CIclient_data\fP 1i Specifies additional data to be passed to the client's event handler. .IP \f(CIposition\fP 1i Specifies when the event handler is to be called relative to other previously registered handlers. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtInsertRawEventHandler()\fR registers the procedure \f(CIproc\fP and the data \f(CIclient_data\fP with the Intrinsics event dispatching mechanism. When an event of one of the types set in \f(CIevent_mask\fP occurs on the window of the widget \f(CIw\fP, \f(CIproc\fP will be invoked and \f(CIclient_data\fP passed as one of its arguments. \f(CWXtInsertRawEventHandler()\fP never calls \f(CWXSelectInput()\fP to request to receive the events in \f(CIevent_mask\fP. .LP The argument \f(CIposition\fP specifies where in the list of event handlers \f(CIproc\fP should be inserted. If it is \f(CWXtListHead\fP, \f(CIproc\fP will be inserted at the beginning of the list and will be called before all previously registered handlers. If it is \f(CWXtListTail\fP, \f(CIproc\fP will be inserted at the end of the list and will be called after all previously registered handlers. .LP If the procedure is already registered with the same \f(CIclient_data\fP, the specified \f(CIevent_mask\fP augments the existing mask, and the procedure is repositioned in the list according to \f(CIposition\fP. .LP \f(CWXtInsertRawEventHandler()\fR is identical to \f(CWXtAddRawEventHandler()\fR with the additional \f(CIposition\fP argument. See \f(CWXtAddRawEventHandler()\fP for more information. .LP See \f(CWXtEventHandler\fP(2) for an explanation of how to write an event handler procedure. .\" .SH "Usage" Neither applications nor widgets often need to use event handlers. Using action procedures and translation tables provides a more flexible way to respond to input events. .\" .SH "Structures" The \f(CWXtListPosition\fP type is as follows. .Ps typedef enum { XtListHead, XtListTail } XtListPosition; .Pe See \f(CWXtAddEventHandler()\fP for a list of bits that can be set in the \f(CIevent_mask\fP argument. .\" .SH "See Also" .na \s-1\fIXtAddEventHandler\fR\s+1\*(s1, \s-1\fIXtAddRawEventHandler\fR\s+1\*(s1, \s-1\fIXtBuildEventMask\fR\s+1\*(s1, \s-1\fIXtInsertEventHandler\fR\s+1\*(s1, \s-1\fIXtRemoveEventHandler\fR\s+1\*(s1, \s-1\fIXtRemoveRawEventHandler\fR\s+1\*(s1. .ad .\"last line comment .XE "XtInsertRawEventHandler" .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtInstallAccelerators" "Xt \- Translations and Actions" .SH "Name" .Na XtInstallAccelerators \- install a widget's accelerators on another widget. .XN "widgets, installing accelerators (see accelerators)" .XS "accelerators, installing" .XN "accelerators: (see also XtInstallAccelerators)" .Nz .XS "XtInstallAccelerators" .SH "Synopsis" .Sy void XtInstallAccelerators(\f(CIdestination\fP, \f(CIsource\fP) .As Widget \f(CIdestination\fP; Widget \f(CIsource\fP; .Ae .SS "Inputs" .IP \f(CIdestination\fP 1i Specifies the widget in which events specified in the accelerator table will be detected. Must be of class Core or any subclass thereof. .IP \f(CIsource\fP 1i Specifies the widget whose actions will be invoked when events occur in \f(CIdestination\fP. Must be of class Core or any subclass thereof. .\" .SH "Description" \f(CWXtInstallAccelerators()\fP merges the accelerator table of \f(CIsource\fP into the translation table of \f(CWdestination\fP. After this call, events in the \f(CIdestination\fP widget will trigger actions in the \f(CIsource\fP widget. .LP If the \f(CWdisplay_accelerator()\fP method of \f(CIsource\fP is non-\f(CWNULL\fP, \f(CWXtInstallAccelerators()\fP calls it with \f(CIsource\fP and a canonical representation of the accelerator table that was installed. This method is a hook that is intended to allow a widget to dynamically modify its appearance (a menu button might display the key sequence that will invoke it, for example) when an accelerator is installed. .\" .SH "Usage" It is often convenient to be able to bind events in one widget to actions in another. In particular, it is often useful to be able to invoke menu actions from the keyboard. The Intrinsics provide a facility, called accelerators, that let you accomplish this. An accelerator table is a translation table that binds events in the destination widget to actions in the source widget. The accelerator table can be installed on one or more destination widgets. When an event sequence in \f(CIdestination\fP would cause an accelerator action to be invoked, and if the source widget is sensitive, the actions are executed as though triggered by the same event sequence in \f(CIsource\fP. The event is passed to the action procedure without modification. The action procedures used within accelerators must assume neither that the source widget is realized, nor that any fields of the event are in reference to the source widget's window if the widget is realized. .LP Every widget includes an \f(CWXtNaccelerators\fP resource, which is defined by the Core widget class. The actual value of this resource can be hardcoded by the application or set in a resource file, just like any other resource. .LP In order for the \f(CWXtNaccelerators\fP resource to actually be used, however, the application must call \f(CWXtInstallAccelerators()\fP (or \f(CWXtInstallAllAccelerators()\fP). This call takes two arguments. The \f(CIdestination\fP widget is the widget whose translation table will be augmented with the accelerator table from the \f(CIsource\fP widget. .LP It is difficult to remember which of the two widgets in this call is which. If you want to install a keyboard accelerator so that a keystroke in a text widget invokes an action in a menu button, then the menu button is the source, and the text widget is the destination. You must set the accelerator table in the \f(CWXtNaccelerators\fP resource of the menu button, and then install those accelerators on the text widget. .LP If you are programming with the Motif widget set, you will generally not be able to use accelerators as described here. Motif provides a different (and incompatible) style of accelerators for use with menus; see Volume 6, \fIMotif Programming Manual\fP for more information. .\" .SH "Example" Assume an application whose top-level shell widget is named \f(CWtopLevel\fP, and which contains a Command widget instance named \f(CWquit\fP. Further assume that the \f(CWquit\fP widget has the following \f(CWXtNaccelerators\fP resource defined for it: .Ps *quit.accelerators: \n\ q: notify() .Pe .Nd 2 The call: .Ps XtInstallAccelerators (topLevel, quit); .Pe would allow a "q" typed in the application's top-level window to invoke the \f(CWquit\fP widget's \f(CWnotify\fP action. The \f(CWnotify\fP action invokes the callback list of the button, and assuming that a quit callback was registered, causes the application to terminate. .\" .SH "See Also" .na \s-1\fIXtInstallAllAccelerators\fR\s+1\*(s1, .br \s-1\fIdisplay_accelerator\fR\s+1\*(s4. .ad .XE "accelerators, installing" .XE "XtInstallAccelerators" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtInstallAllAccelerators" "Xt \- Translations and Actions" .SH "Name" .Na XtInstallAllAccelerators \- install all accelerators from a widget and its descendants onto a destination widget. .XN "widgets, installing accelerators (see accelerators)" .XX "accelerators, installing" .Nz .XX "XtInstallAllAccelerators" .SH "Synopsis" .Sy void XtInstallAllAccelerators(\f(CIdestination\fP, \f(CIsource\fP) .As Widget \f(CIdestination\fP; Widget \f(CIsource\fP; .Ae .SS "Inputs" .IP \f(CIdestination\fP 1i Specifies the widget in which events specified in the accelerator tables will be detected. Must be of class Core or any subclass thereof. .IP \f(CIsource\fP 1i Specifies the root widget of the widget tree from which the actions of any descendant widget can be invoked when events occur in \f(CIdestination\fP. Must be of class Core or any subclass thereof. .\" .SH "Description" \f(CWXtInstallAllAccelerators()\fR is a convenience function for installing all accelerators from a widget and all its descendants onto a single destination widget. It recursively traverses the widget tree rooted at \f(CIsource\fR and installs the accelerator resource values of each widget onto \f(CIdestination\fR. It also calls the \f(CWdisplay_accelerator()\fP method of each widget in the \f(CIsource\fP tree that has one. .\" .SH "Usage" A common use for \f(CWXtInstallAllAccelerators()\fP is to install the accelerators for all the buttons of a menu or an entire menu bar onto a single destination widget. The \f(CWXtNaccelerator\fP resource of each button would be specified when the button was created or would come from the resource database, and the single call to \f(CWXtInstallAllAccelerators()\fP would make all those accelerators available in a widget. .LP Note that if you want to provide keyboard shortcuts for a menu system from within two different text widgets, you will have to call \f(CWXtInstallAllAccelerators()\fP twice. .LP Also note that if a widget is not interested in events of a certain type, then those events will propagate up the widget hierarchy to the first ancestor widget that is interested. If your interface contains a composite widget that contains only button and other widgets that are not interested in keyboard input, then you can install a set of keyboard accelerators on the composite widget, and they will be invoked when keyboard events occur anywhere within that widget. .\" .SH "See Also" .na \s-1\fIXtInstallAccelerators\fR\s+1\*(s1, .br \s-1\fIdisplay_accelerator\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsApplicationShell" "Xt \- Object Information" .SH "Name" .Na XtIsApplicationShell \- test whether a widget is a subclass of the ApplicationShell widget class. .Nz .XX "XtIsApplicationShell" .SH "Synopsis" .Sy Boolean XtIsApplicationShell(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1.1i Specifies the object whose class is to be checked; may be of class Object or any subclass thereof. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is of class applicationShell or a subclass thereof; \f(CWFalse\fP otherwise. .SH "Description" \f(CWXtIsApplicationShell()\fR tests whether \f(CIobject\fP is a subclass of the ApplicationShell widget class. It may be defined as a macro or a function, and is equivalent to, but may be faster than, calling \f(CWXtIsSubclass()\fP for this class. .\" .SH "See Also" .na \s-1\fIXtIsSubclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsComposite" "Xt \- Object Information" .SH "Name" .Na XtIsComposite \- test whether a widget is a subclass of the Composite widget class. .XX "widgets: class; XtIsComposite" .XX "composite widgets: subclass; XtIsComposite" .Nz .XX "XtIsComposite" .SH "Synopsis" .Sy Boolean XtIsComposite(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the widget whose class is to be tested; may be of class Object or any subclass thereof. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is of class Composite or a subclass thereof; \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtIsComposite()\fR tests whether \f(CIobject\fP is a subclass of the Composite widget class. It may be defined as a macro or a function, and is equivalent to, but may be faster than, calling \f(CWXtIsSubclass()\fP for this class. .\" .SH "See Also" .na \s-1\fIXtIsSubclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsConstraint" "Xt \- Object Information" .SH "Name" .Na XtIsConstraint \- test whether a widget is a subclass of the Constraint widget class. .XX "widgets: class; XtIsConstraint" .XX "constraint widgets: XtIsConstraint" .Nz .XX "XtIsConstraint" .SH "Synopsis" .Sy Boolean XtIsConstraint(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the widget whose class is to be tested; may be of class Object or any subclass thereof. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is of class Constraint or a subclass thereof; \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtIsConstraint()\fR tests whether \f(CIobject\fP is a subclass of the Constraint widget class. It may be defined as a macro or a function, and is equivalent to, but may be faster than, calling \f(CWXtIsSubclass()\fP for this class. .\" .SH "See Also" .na \s-1\fIXtIsSubclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsManaged" "Xt \- Object Information" .SH "Name" .Na XtIsManaged \- determine whether a widget is managed by its parent. .XX "widgets, management" .XX "widgets: management; XtIsManaged" .Nz .XX "XtIsManaged" .SH "Synopsis" .Sy Boolean XtIsManaged(\f(CIobject\fP) .As Widget \f(CIobject\fP\^; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object whose state is to be tested; may be of class Object or any subclass thereof. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is managed, \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtIsManaged()\fR returns \f(CWTrue\fP if the specified object is of class RectObj and is currently managed or \f(CWFalse\fP if it is not. .SH "See Also" .na \s-1\fIXtManageChild\fR\s+1\*(s1, \s-1\fIXtManageChildren\fR\s+1\*(s1, \s-1\fIXtUnManageChild\fR\s+1\*(s1, \s-1\fIXtUnmanageChildren\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsObject" "Xt \- Object Information" .SH "Name" .Na XtIsObject \- test whether a widget is a subclass of the Object widget class. .Nz .XX "XtIsObject" .SH "Synopsis" .Sy Boolean XtIsObject(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1.1i Specifies the object whose class is to be checked; may be of Object Class or any subclass thereof. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is of class Object or a subclass thereof; \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtIsObject()\fR tests whether \f(CIobject\fP is a subclass of the Object widget class. It may be defined as a macro or a function, and is equivalent to, but may be faster than, calling \f(CWXtIsSubclass()\fP for this class. .\" .SH "See Also" .na \s-1\fIXtIsSubclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsOverrideShell" "Xt \- Object Information" .SH "Name" .Na XtIsOverrideShell \- test whether a widget is a subclass of the OverrideShell widget class. .Nz .XX "XtIsOverrideShell" .SH "Synopsis" .Sy Boolean XtIsOverrideShell(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1.1i Specifies the object whose class is to be checked; may be of class Object or any subclass thereof. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is of class OverrideShell or a subclass thereof; \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtIsOverrideShell()\fR tests whether \f(CIobject\fP is a subclass of the OverrideShell widget class. It may be defined as a macro or a function, and is equivalent to, but may be faster than, calling \f(CWXtIsSubclass()\fP for this class. .\" .SH "See Also" .na \s-1\fIXtIsSubclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsRealized" "Xt \- Object Information" .SH "Name" .Na XtIsRealized \- determine whether a widget has been realized. .XX "widgets: realizing; XtIsRealized" .Nz .XX "XtIsRealized" .SH "Synopsis" .Sy Boolean XtIsRealized(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object whose state is to be tested; may be of class Object or any subclass thereof. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is realized; \f(CWFalse\fP otherwise. .SH "Description" \f(CWXtIsRealized()\fR returns \f(CWTrue\fP if the specified object (or its nearest widget ancestor) has been realized, and \f(CWFalse\fP otherwise. A widget is realized if it has a nonzero X window ID. .\" .SH "Usage" \f(CWXtIsRealized()\fP is implemented as a function when called from application code, but is replaced by a more efficient macro when called from widget code that includes the file \fI\fP. .LP Some widget methods (for example, \f(CWset_values()\fR) might wish to operate differently depending on whether the widget has been realized. In particular, no Xlib calls can refer to a widget's window until the widget is realized. .\" .SH "See Also" .na \s-1\fIXtWindow\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsRectObj" "Xt \- Object Information" .SH "Name" .Na XtIsRectObj \- test whether a widget is a subclass of the RectObj widget class. .Nz .XX "XtIsRectObj" .SH "Synopsis" .Sy Boolean XtIsRectObj(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1.1i Specifies the object whose class is to be checked; may be of class Object or any subclass thereof. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is of class RectObj or a subclass thereof; \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtIsRectObj()\fR tests whether \f(CIobject\fP is a subclass of the RectObj widget class. It may be defined as a macro or a function, and is equivalent to, but may be faster than, calling \f(CWXtIsSubclass()\fP for this class. .\" .SH "See Also" .na \s-1\fIXtIsSubclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsSensitive" "Xt \- Object Information" .SH "Name" .Na XtIsSensitive \- check the current sensitivity state of a widget. .XX "sensitivity: checking state; XtIsSensitive" .Nz .XX "XtIsSensitive" .SH "Synopsis" .Sy Boolean XtIsSensitive(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object whose state is to be tested; may be of class Object or any subclass thereof. .SS "Returns" \f(CWTrue\fP if the widget is sensitive; \f(CWFalse\fP otherwise. .SH "Description" \f(CWXtIsSensitive()\fR returns \f(CWTrue\fP if \f(CIobject\fP is a subclass of RectObj and both its \f(CWsensitive\fR and \f(CWancestor_sensitive\fR fields are \f(CWTrue\fP. Otherwise, it returns \f(CWFalse\fP. .\" .SH "Usage" An insensitive widget will not have user events dispatched to it, and may display itself specially (grayed out, for example) to indicate this condition. .LP A widget's sensitivity is often checked by its parent. For example the parent may wish to determine whether it should should pass the keyboard focus to the child, or it may choose to make itself insensitive if all of its children become insensitive. .\" .SH "See Also" .na \s-1\fIXtSetSensitive\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsShell" "Xt \- Object Information" .SH "Name" .Na XtIsShell \- test whether a widget is a subclass of the Shell widget class. .XX "widgets: class; XtIsShell" .XX "Shell widget: XtIsShell" .Nz .XX "XtIsShell" .SH "Synopsis" .Sy Boolean XtIsShell(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object whose class is to be tested; may be of class Object or any subclass thereof. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is of class Shell or a subclass thereof; \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtIsShell()\fR tests whether \f(CIobject\fP is a subclass of the Shell widget class. It may be defined as a macro or a function, and is equivalent to, but may be faster than, calling \f(CWXtIsSubclass()\fP for this class. .\" .SH "See Also" .na \s-1\fIXtIsSubclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsSubclass" "Xt \- Object Information" .SH "Name" .Na XtIsSubclass \- determine whether a widget is a subclass of a class. .XX "widgets: class; determining subclass (XtIsSubclass)" .XX "widgets: class; XtIsSubclass" .XX "widgets: subclass" .Nz .XX "XtIsSubclass" .SH "Synopsis" .Sy Boolean XtIsSubclass(\f(CIobject\fP, \f(CIobject_class\fP) .As Widget \f(CIobject\fP; WidgetClass \f(CIobject_class\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1.1i Specifies the object instance whose class is to be checked; may be of class Object or any subclass thereof. .IP \f(CIobject_class\fP Specifies the widget class to test against; may be objectClass or any subclass. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is of class \f(CIobject_class\fP or any subclass of it; \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtIsSubclass()\fP returns \f(CWTrue\fP if the specified object is of the specified class, or is a subclass (any number of classes removed) of it. Otherwise it returns \f(CWFalse\fP. .\" .SH "Usage" Composite widgets that restrict the type of widgets they will accept as children can use \f(CWXtIsSubclass()\fR to find out whether a widget belongs to the desired widget class. .LP Public routines that require a widget of a particular class can use \f(CWXtIsSubclass()\fP to verify that the object they are passed is of the correct type. \f(CWXtCheckSubclass()\fP does the same thing, but is a macro that is only compiled when the symbol DEBUG is defined by the compiler. .LP To test whether a given widget is a subclass of an Intrinsics-defined class, the Intrinsics define convenience functions equivalent to \f(CWXtIsSubclass()\fR for each of the built-in classes. These functions are shown in the table below: .sp 1 .in 0 .KS .TS linesize(2), tab(@); lfCWp7 lfCWp7. .sp 2p \f(CWXtIsObject()\fR@\f(CWXtIsOverrideShell()\fR \f(CWXtIsRectObj()\fR@\f(CWXtIsWMShell()\fR \f(CWXtIsWidget()\fR@\f(CWXtIsVendorShell()\fR \f(CWXtIsComposite()\fR@\f(CWXtIsTransientShell()\fR \f(CWXtIsConstraint()\fR@\f(CWXtIsTopLevelShell()\fR \f(CWXtIsShell()\fR@\f(CWXtIsApplicationShell()\fR .sp 5p .TE .KE .in .sp 1 .LP These functions may be defined as macros, and may be faster than calling \f(CWXtIsSubclass()\fR directly for the built-in classes. .ft R .SH "See Also" .na \s-1\fIXtCheckSubclass\fR\s+1\*(s1, \s-1\fIXtClass\fR\s+1\*(s1, \s-1\fIXtIs*\fR\s+1\*(s1, \s-1\fIXtSuperclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsTopLevelShell" "Xt \- Object Information" .SH "Name" .Na XtIsTopLevelShell \- test whether a widget is a subclass of the TopLevelShell widget class. .Nz .XX "XtIsTopLevelShell" .SH "Synopsis" .Sy Boolean XtIsTopLevelShell(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1.1i Specifies the object whose class is to be checked; may be of class Object or any subclass thereof. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is of class TopLevelShell or a subclass thereof; \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtIsTopLevelShell()\fR tests whether \f(CIobject\fP is a subclass of the TopLevelShell widget class. It may be defined as a macro or a function, and is equivalent to, but may be faster than, calling \f(CWXtIsSubclass()\fP for this class. .\" .SH "See Also" .na \s-1\fIXtIsSubclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsTransientShell" "Xt \- Object Information" .SH "Name" .Na XtIsTransientShell \- test whether a widget is a subclass of the TransientShell widget class. .Nz .XX "XtIsTransientShell" .SH "Synopsis" .Sy Boolean XtIsTransientShell(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1.1i Specifies the object whose class is to be checked; may be of Object class or any subclass thereof. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is of class TransientShell or a subclass thereof; \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtIsTransientShell()\fR tests whether \f(CIobject\fP is a subclass of the TransientShell widget class. It may be defined as a macro or a function, and is equivalent to, but may be faster than, calling \f(CWXtIsSubclass()\fP for this class. .\" .SH "See Also" .na \s-1\fIXtIsSubclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsVendorShell" "Xt \- Object Information" .SH "Name" .Na XtIsVendorShell \- test whether a widget is a subclass of the VendorShell widget class. .Nz .XX "XtIsVendorShell" .SH "Synopsis" .Sy Boolean XtIsVendorShell(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1.1i Specifies the object whose class is to be checked; may be of class Object or any subclass thereof. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is of class VendorShell or a subclass thereof; \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtIsVendorShell()\fR tests whether \f(CIobject\fP is a subclass of the VendorShell widget class. It may be defined as a macro or a function, and is equivalent to, but may be faster than, calling \f(CWXtIsSubclass()\fP for this class. .\" .SH "See Also" .na \s-1\fIXtIsSubclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsWMShell" "Xt \- Object Information" .SH "Name" .Na XtIsWMShell \- test whether a widget is a subclass of the WMShell widget class. .Nz .XX "XtIsWMShell" .SH "Synopsis" .Sy Boolean XtIsWMShell(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1.1i Specifies the object whose class is to be checked; may be of class Object or any subclass thereof. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is of class WMShell or a subclass thereof; \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtIsWMShell()\fR tests whether \f(CIobject\fP is a subclass of the WMShell widget class. It may be defined as a macro or a function, and is equivalent to, but may be faster than, calling \f(CWXtIsSubclass()\fP for this class. .\" .SH "See Also" .na \s-1\fIXtIsSubclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtIsWidget" "Xt \- Object Information" .SH "Name" .Na XtIsWidget \- test whether a widget is a subclass of the Core widget class. .Nz .XX "XtIsWidget" .SH "Synopsis" .Sy Boolean XtIsWidget(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1.1i Specifies the object whose class is to be checked; may be of class Object or any subclass thereof. .SS "Returns" \f(CWTrue\fP if \f(CIobject\fP is of class Core or a subclass thereof; \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtIsWidget()\fR tests whether \f(CIobject\fP is a subclass of the Core widget class. It may be defined as a macro or a function, and is equivalent to, but may be faster than, calling \f(CWXtIsSubclass()\fP for this class. .\" .SH "See Also" .na \s-1\fIXtIsSubclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtKeyProc" "Xt \- Keyboard Handling" .SH "Name" .Na XtKeyProc \- interface definition for keycode-to-keysym translation procedure. .Nz .XS "key translation, XtKeyProc" .XS "XtKeyProc" .SH "Synopsis" .Sy typedef void (*XtKeyProc)(Display *, KeyCode, Modifiers, Modifiers *, KeySym *); .As Display *\f(CIdisplay\fP; KeyCode \f(CIkeycode\fP; Modifiers \f(CImodifiers\fP; Modifiers *\f(CImodifiers_return\fP; KeySym *\f(CIkeysym_return\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the display that the keycode is from. .IP \f(CIkeycode\fP 1i Specifies the keycode that is to be translated. .IP \f(CImodifiers\fP 1i Specifies the mask that indicates what modifier keys (Shift, Meta, Control, etc.) are pressed. .SS "Outputs" .IP \f(CImodifiers_return\fP 1i Returns a mask that specifies the modifier keys that the function examined in making the conversion. .IP \f(CIkeysym_return\fP Returns the resulting keysym. .\" .SH "Description" An \f(CWXtKeyProc\fP is registered in a call to \f(CWXtSetKeyTranslator()\fP and is invoked explicitly by a call to \f(CWXtTranslateKeycode()\fP and automatically by the Translation Manager in order to convert incoming keycodes to keysyms. .LP An \f(CWXtKeyProc\fP must convert the \f(CIkeycode\fP and \f(CImodifiers\fP into a keysym and return that keysym in \f(CIkeysym_return\fP. It should return the modifiers that it considers in its translation in \f(CImodifiers_return\fP. The value returned in this argument will be a constant for any given \f(CWXtKeyProc\fP. .LP An \f(CWXtKeyProc\fP must be implemented so that multiple calls with the same \f(CIdisplay\fP, \f(CIkeycode\fP, and \f(CImodifiers\fP arguments will return the same result until either a new case converter (an \f(CWXtCaseProc\fP) is registered or a MappingNotify event is received. .\" .SH "Usage" \f(CWXtTranslateKey()\fP is the default \f(CWXtKeyProc\fP. It should be sufficient for all applications except those that use non-standard keysyms. .LP When writing an \f(CWXtKeyProc\fP, you will probably need to call \f(CWXtConvertCase()\fP, and \f(CWXtGetKeysymTable()\fP. You may also want to invoke \f(CWXtTranslateKey()\fP directly to translate the standard keysyms. .\" .SH "See Also" .na \s-1\fIXtConvertCase\fR\s+1\*(s1, \s-1\fIXtGetKeysymTable\fR\s+1\*(s1, \s-1\fIXtKeysymToKeycodeList\fR\s+1\*(s1, \s-1\fIXtRegisterCaseConverter\fR\s+1\*(s1, \s-1\fIXtSetKeyTranslator\fR\s+1\*(s1, \s-1\fIXtTranslateKey\fR\s+1\*(s1, \s-1\fIXtTranslateKeycode\fR\s+1\*(s1. .ad .XE "key translation, XtKeyProc" .XE "XtKeyProc" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtKeysymToKeycodeList" "Xt \- Keyboard Handling" .SH "Name" .XX "XtKeysymToKeycodeList" .Na XtKeysymToKeycodeList \- return the list of keycodes that map to a particular keysym in the keyboard mapping table maintained by the Intrinsics. .Nz .SH "Synopsis" .Sy void XtKeysymToKeycodeList(\f(CIdisplay\fP, \f(CIkeysym\fP, \f(CIkeycodes_return\fP, .br \f(CIkeycount_return\fP) .As Display *\f(CIdisplay\fP; KeySym \f(CIkeysym\fP; KeyCode **\f(CIkeycodes_return\fP; Cardinal *\f(CIkeycount_return\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1.25i Specifies the display whose table is required. .IP \f(CIkeysym\fP 1.25i Specifies the keysym for which to search. .SS "Outputs" .IP \f(CIkeycodes_return\fP 1.25i Returns a list of keycodes that have keysyms associated with them or \f(CWNULL\fR if \f(CIkeycount_return\fR is 0. .IP \f(CIkeycount_return\fP 1.25i Returns the number of keycodes in the keycodes list. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtKeysymToKeycodeList()\fR returns all the keycodes that have the requested keysym in their entry in the keyboard mapping table associated with \f(CIdisplay\fP. If no keycodes map to the specified keysym, *\f(CIkeycount_return\fR is 0 and *\f(CIkeycodes_return\fR is \f(CWNULL\fR. .LP The caller should free the storage pointed to by \f(CIkeycodes_return\fR using \f(CWXtFree()\fR when it is no longer useful. .\" .SH "Usage" The Translation Manager automatically converts between keycodes and keysyms. Most applications will never have to use this function or its related functions. .LP If you needs to examine the keycode-to-keysym table for a particular keycode, you can obtain the current table with \f(CWXtGetKeysymTable()\fR. .SH "See Also" .na \s-1\fIXtConvertCase\fR\s+1\*(s1, \s-1\fIXtGetKeysymTable\fR\s+1\*(s1, \s-1\fIXtRegisterCaseConverter\fR\s+1\*(s1, \s-1\fIXtSetKeyTranslator\fR\s+1\*(s1, \s-1\fIXtTranslateKeycode\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtLanguageProc" "Xt \- Locale Management" .XX "XtLanguageProc" .XX "language procedures:prototype" .SH "Name" .Na XtLanguageProc \- interface definition for a procedure to set the locale and return the language string. .Nz .SH "Synopsis" .Sy typedef String (*XtLanguageProc)(Display*, String, XtPointer); .As Display *\f(CIdisplay\fP; String \f(CIlanguage\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIlanguage\fP Specifies the initial language string obtained from the command line or server per-display resources, or \f(CWNULL\fP if no language specification is found. .IP \f(CIclient_data\fP Specifies data registered with this function in the call to \f(CWXtSetLanguageProc()\fP. .SS "Returns" The language string for the display. .\" .SH Availability Release 5 and later. .\" .SH "Description" An \f(CWXtLanguageProc\fP and its \f(CIclient_data\fP argument are registered with a call to \f(CWXtSetLanguageProc()\fP. It is invoked by \f(CWXtDisplayInitialize()\fP with the initial value of the language string or NULL. .LP A language procedure is passed the language string, if any, from the application command line or per-display resources, and should use that string to localize the application appropriately. Setting the locale usually involves calling \f(CWsetlocale()\fP, \f(CWXSupportsLocale()\fP, and \f(CWXSetLocaleModifiers()\fP, but applications that use other localization schemes may need to do different or additional initialization in this procedure. .LP An \f(CWXtLanguageProc\fP returns a string which will be set as the language string of the display by \f(CWXtDisplayInitialize()\fP, and will be used in future calls to \f(CWXtResolvePathname()\fP to find localized files. The returned string may be different than the \f(CIlanguage\fP argument. If \f(CIlanguage\fP is \f(CWNULL\fP, for example, a language procedure might determine the locale from an environment variable and return that value. If the language procedure calls \f(CWsetlocale()\fP, then the return value of this function is an appropriate return value for the function. The Intrinsics will make a private copy of this string. .\" .SH "Usage" All internationalized programs should call \f(CWXtSetLanguageProc()\fP before calling \f(CWXtAppInitialize()\fP, but most can simply use the default language procedure (pass \f(CWNULL\fP for the \f(CIproc\fP argument). The default procedure should be sufficient for all applications that use only ANSI-C and X-based internationalization schemes. .\" .SH "Example" The following is the Intrinsics default language procedure: .Ps /*ARGSUSED*/ static String _XtDefaultLanguageProc(dpy, xnl, closure) Display *dpy; /* unused */ String xnl; XtPointer closure; /* unused */ { if (! setlocale(LC_ALL, xnl)) XtWarning("locale not supported by C library, locale unchanged"); if (! XSupportsLocale()) { XtWarning("locale not supported by Xlib, locale set to C"); setlocale(LC_ALL, "C"); } if (! XSetLocaleModifiers("")) XtWarning("X locale modifiers not supported, using default"); return setlocale(LC_ALL, NULL); /* re-query in case overwritten */ } .Pe .\" .SH "See Also" .na \s-1\fIXtDisplayInitialize\fR\s+1\*(s1, \s-1\fIXtSetLanguageProc\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtLastTimestampProcessed" "Xt \- Event Handling" .SH "Name" .XX "XtLastTimestampProcessed" .Na XtLastTimestampProcessed \- retrieve the timestamp from the most recent event handled by \f(CWXtDispatchEvent()\fR that contains a timestamp. .Nz .SH "Synopsis" .Sy Time XtLastTimestampProcessed(\f(CIdisplay\fP) .As Display *\f(CIdisplay\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies an open display connection. .SS "Returns" The timestamp of the most recently processed event that contains an event, or zero. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtLastTimestampProcessed()\fP returns the timestamp of the most recently processed event that contains a timestamp. If no \f(CWKeyPress\fR, \f(CWKeyRelease\fR, \f(CWButtonPress\fR, \f(CWButtonRelease\fR, \f(CWMotionNotify\fR, \f(CWEnterNotify\fR, \f(CWLeaveNotify\fR, \f(CWPropertyNotify\fR or \f(CWSelectionClear\fR event has yet been passed to \f(CWXtDispatchEvent()\fR for the specified display, \f(CWXtLastTimestampProcessed()\fR returns zero. .\" .SH "Usage" The Intrinsics selection handling routines take arguments of type \f(CWTime\fP. For ICCCM compliance, these arguments must be the timestamp of the event that triggered the request\-the special value \f(CWCurrentTime\fP is not acceptable. \f(CWXtLastTimestampProcessed()\fP is a convenience function added in Release 4 to make it easy to obtain an appropriate timestamp, even from within a callback which is not passed an event. The function \f(CWXtGetSelectionRequest()\fP serves a similar purpose for \f(CWXtSelectionCallback\fP procedures. .\" .SH "See Also" .na \s-1\fIXtDispatchEvent\fR\s+1\*(s1, \s-1\fIXtGetSelectionRequest\fR\s+1\*(s1, \s-1\fIXtGetSelectionValue\fR\s+1\*(s1, \s-1\fIXtOwnSelection\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtLoseSelectionIncrProc" "Xt \- Selections" .SH "Name" .Na XtLoseSelectionIncrProc \- interface definition for a procedure called when the selection owner loses ownership. .Nz .XS "XtLoseSelectionIncrProc" .XX "XtLoseSelectionIncrProc" .SH "Synopsis" .Sy typedef void (*XtLoseSelectionIncrProc)(Widget, Atom*, XtPointer); .As Widget \f(CIw\fP; Atom *\f(CIselection\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that has lost the selection ownership. .IP \f(CIselection\fP 1i Specifies the atom that names the selection. .IP \f(CIclient_data\fP 1i Specifies the value passed in by the widget when it took ownership of the selection. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" An \f(CWXtLoseSelectionIncrProc\fP is optionally registered in a call to \f(CWXtOwnSelectionIncremental()\fP, and is called by the Intrinsics to inform the selection owner that the selection has been claimed by another widget or another client. This procedure is not called if the selection owner relinquishes selection ownership by calling \f(CWXtDisownSelection()\fP. It should do whatever is appropriate for the widget or application upon losing the ownership of the selection. .LP Note that this procedure is not a request to the widget to relinquish selection ownership; it is called after the widget has already lost the selection. .\" .SH "Usage" Most selection owners will want to display selected data specially highlighted, and so will need to be informed when they lose the selection so that they can unhighlight that data. .LP An \f(CWXtLoseSelectionIncrProc\fP is used in the Intrinsics incremental selection transfer mechanism. An \f(CWXtLoseSelectionProc\fP is a similar procedure used by the more convenient atomic transfer mechanism. An \f(CWXtLoseSelectionProc\fP does not have a \f(CIclient_data\fP argument. .SH "See Also" .na \s-1\fIXtGetSelectionValueIncremental\fR\s+1\*(s1, \s-1\fIXtGetSelectionValuesIncremental\fR\s+1\*(s1, \s-1\fIXtOwnSelectionIncremental\fR\s+1\*(s1, .br \s-1\fIXtCancelConvertSelectionProc\fR\s+1\*(s2, \s-1\fIXtConvertSelectionIncrProc\fR\s+1\*(s2, \s-1\fIXtLoseSelectionProc\fR\s+1\*(s2, \s-1\fIXtSelectionDoneIncrProc\fR\s+1\*(s2. .ad .XE "XtLoseSelectionIncrProc" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtLoseSelectionProc" "Xt \- Selections" .SH "Name" .Na XtLoseSelectionProc \- interface definition for procedure to notify the selection owner it has lost selection ownership. .Nz .XS "XtLoseSelectionProc" .XN "selections: method; (see also XtLoseSelectionProc)" .SH "Synopsis" .Sy typedef void (*XtLoseSelectionProc)(Widget, Atom *); .As Widget \f(CIw\fP; Atom *\f(CIselection\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that has lost selection ownership. .IP \f(CIselection\fP 1i Specifies the atom that names the selection. .\" .SH "Description" An \f(CWXtLoseSelectionProc\fP is optionally registered in a call to \f(CWXtOwnSelection()\fP and is called by the Intrinsics when the widget it was registered with loses the selection because another widget or client has claimed the selection. It is not called when the selection owner relinquishes selection ownership with \f(CWXtDisownSelection()\fP. This procedure should take whatever action is appropriate for the widget or application when it loses selection ownership. .LP Note that this procedure is not a request to the widget to relinquish selection ownership; it is called after the widget has already lost the selection. .\" .SH "Usage" Most selection owners (widgets or applications) will want to display selected data highlighted in some way, and so will need to be informed when they lose the selection so that they can unhighlight that data. .LP An \f(CWXtLoseSelectionIncrProc\fP is a similar procedure type used by the Intrinsics incremental selection transfer mechanism. It takes an additional \f(CIclient_data\fP argument. .\" .SH "Example" The \f(CWXtLoseSelectionProc\fP below is from the \fIxcalc\fP client. It simply unhighlights the value currently shown in the calculator display. .Ps /* * called when xcalc loses ownership of the selection. */ /*ARGSUSED*/ void lose(w, selection) Widget w; Atom *selection; { XawToggleUnsetCurrent(LCD); } .Pe .\" .Nd 10 .SH "See Also" .na \s-1\fIXtDisownSelection\fR\s+1\*(s1, \s-1\fIXtGetSelectionValue\fR\s+1\*(s1, \s-1\fIXtGetSelectionValueIncremental\fR\s+1\*(s1, \s-1\fIXtOwnSelection\fR\s+1\*(s1, .ad .br \s-1\fIXtLoseSelectionIncrProc\fR\s+1\*(s2. .XE "XtLoseSelectionProc" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtLoseSelec 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtLoseSelectionIncrProc@XtLoseSeleA .sp .5 XtLoseSelectionProc@XtLoseSeleB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtMainLoop" "Xt \- Event Handling" .SH "Name" .Na XtMainLoop \- continuously process events. .Nz .XX "XtMainLoop" .SH "Synopsis" .Sy void XtMainLoop() .As .Ae .SS "Inputs" none .SS "Returns" \f(CWXtMainLoop()\fP enters an infinite loop and never returns. .\" .SH "Availability" \f(CWXtMainLoop()\fP has been superseded by \f(CWXtAppMainLoop()\fP. .\" .SH "Description" \f(CWXtMainLoop()\fP enters an infinite loop which calls \f(CWXtNextEvent()\fP to wait for events on all displays in \f(CIapp_context\fP and \f(CWXtDispatchEvent()\fP to dispatch events. .\" .SH "Usage" \f(CWXtMainLoop()\fP has been superseded by \f(CWXtAppMainLoop()\fP, which performs the same function on a per-application context basis. \f(CWXtMainLoop()\fP now calls \f(CWXtAppMainLoop()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtMainLoop()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppMainLoop()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppMainLoop()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtAppMainLoop\fR\s+1\*(s1, \s-1\fIXtAppNextEvent\fR\s+1\*(s1, \s-1\fIXtDispatchEvent\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtMakeGeometryRequest" "Xt \- Geometry Management" .SH "Name" .Na XtMakeGeometryRequest \- request parent to change child's geometry. .XS "geometry management, changes" .XS "geometry management: changing (XtMakeGeometryRequest)" .Nz .XS "XtMakeGeometryRequest" .SH "Synopsis" .Sy XtGeometryResult XtMakeGeometryRequest(\f(CIw\fP, \f(CIrequest\fP, \f(CIcompromise_return\fP) .As Widget \f(CIw\fP; XtWidgetGeometry *\f(CIrequest\fP; XtWidgetGeometry *\f(CIcompromise_return\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the child widget that is making the request. Must be of class RectObj or any subclass thereof. .IP \f(CIrequest\fP 1i Specifies the desired widget geometry (size, position, border width, and stacking order). .SS "Outputs" .IP \f(CIcompromise_return\fP 1i Returns a compromise geometry when the function returns \f(CWXtGeometryAlmost\fP. May be \f(CWNULL\fR if the requesting widget is not interested in handling \f(CWXtGeometryAlmost\fR. .SS "Returns" A response to the request: \f(CWXtGeometryYes\fP, \f(CWXtGeometryNo\fP or \f(CWXtGeometryAlmost\fP. .\" .SH "Description" \f(CWXtMakeGeometryRequest()\fP requests the parent of \f(CIw\fP to change \f(CIw\fP's geometry to that specified in \f(CIrequest\fP. The \f(CWrequest_mode\fP field of \f(CIrequest\fP specifies which elements of its geometry the object is asking to have changed, and the remaining fields of this structure specify the values for each of those elements. If a bit is not set in \f(CIrequest_mode\fP, then \f(CWXtMakeGeometryRequest()\fP may change that element of the geometry in its effort to satisfy the requested changes. .LP There are three possible return values from this function, with the following meanings: .IP \f(CWXtGeometryYes\fP .25i The request was granted and has been performed (unless \f(CWrequest_mode\fP contained the \f(CWXtCWQueryOnly\fP bit). The object's internal core geometry fields have been updated and, if it is realized, the window has been correctly configured for the new geometry. The contents of \f(CIcompromise_return\fP are undefined. \f(CIw\fP's \f(CWresize()\fP method may or may not have been called. \f(CWXtMakeGeometryRequest()\fP does not call that method, but some parent widgets will call it in the process of satisfying the geometry request. The object should assume that it has not been called and perform any necessary resize calculations. .IP \f(CWXtGeometryNo\fP .25i The request was denied. The contents of \f(CIcompromise_return\fP are undefined. .Nd 5 .IP \f(CWXtGeometryAlmost\fP .25i The request could not be satisfied exactly, but the object's parent has proposed a compromise geometry in \f(CIcompromise_return\fP. If these compromise values are immediately used in another call to \f(CWXtMakeGeometryRequest()\fP the request is guaranteed to succeed. .LP See the "Background" section below for a detailed listing of the steps followed by \f(CWXtMakeGeometryRequest()\fP. .\" .SH "Usage" \f(CWXtMakeGeometryRequest()\fP should only be used in widget code by widgets which would like to change their own size. This is the only way that a widget is allowed to change its own size. .LP Applications that want to set a widget size should use \f(CWXtSetValues()\fP on the various geometry resources of a widget. .LP A widget that wants to change the geometry of one of its children should use \f(CWXtConfigureWidget()\fP, \f(CWXtMoveWidget()\fP or \f(CWXtResizeWidget()\fP. .\" .SH "Background" \f(CWXtMakeGeometryRequest()\fR performs the following tasks: .IP \(bu 3n If the widget is unmanaged or the widget's parent is not realized, it makes the changes to the widget's preferred geometry and returns \f(CWXtGeometryYes\fR. .IP \(bu 3n If the parent is not a subclass of \f(CWcompositeWidgetClass\fR .hw geometry or the parent's \f(CWgeometry_manager()\fR method (the function pointed to by the \f(CWgeometry_manager()\fP field in the widget class record) is \f(CWNULL\fR, it issues an error. .IP \(bu 3n If the widget's \f(CWbeing_destroyed\fR field is \f(CWTrue\fP, it returns \f(CWXtGeometryNo\fR. .IP \(bu 3n If the widget \f(CWx\fR, \f(CWy\fR, \f(CWwidth\fR, \f(CWheight\fR, and \f(CWborder_width\fR fields are already equal to the requested values, it returns \f(CWXtGeometryYes;\fR otherwise, it calls the parent's \f(CWgeometry_manager()\fR method with the given parameters. .IP \(bu 3n If the parent's geometry manager returns \f(CWXtGeometryYes\fR, if \f(CWXtCWQueryOnly\fR is not set in \f(CWrequest_mode\fR (see Structures below for details), and if the widget is realized, then \f(CWXtMakeGeometryRequest()\fR calls the Xlib \f(CWXConfigureWindow()\fR function to adjust the widget's window (setting its size, location, and stacking order as appropriate). .IP \(bu 3n If the geometry manager returns \f(CWXtGeometryDone\fR, the change has been approved and actually has been done. In this case, \f(CWXtMakeGeometryRequest()\fR does no configuring and returns \f(CWXtGeometryYes\fR. \f(CWXtMakeGeometryRequest()\fR never returns \f(CWXtGeometryDone\fR. .IP \(bu 3n Otherwise, \f(CWXtMakeGeometryRequest()\fR returns the resulting value from the parent's geometry manager. .LP Children of non-Composite widgets are always unmanaged; thus, \f(CWXtMakeGeometryRequest()\fR always returns \f(CWXtGeometryYes\fR when called by a child of a non-Composite widget. .\" .SH "Structures" The return codes from geometry managers are: .XX "XtGeometryResult" .Ps .ta 4.5n 2i typedef enum _XtGeometryResult { XtGeometryYes, /* Request accepted */ XtGeometryNo, /* Request denied */ XtGeometryAlmost,/* Request denied but willing to take reply */ XtGeometryDone /* never returned by XtMakeGeometryRequest() */ } XtGeometryResult; .Pe The \f(CWXtWidgetGeometry\fR structure is similar to but not identical to the corresponding Xlib structure: .XX "XtGeometryMask" .Ps .ta 4.5n 2i typedef unsigned long XtGeometryMask; .sp .5 typedef struct { XtGeometryMask request_mode; Position x, y; Dimension width, height; Dimension border_width; Widget sibling; int stack_mode; } XtWidgetGeometry; .Pe .LP \f(CWXtMakeGeometryRequest()\fR, like the Xlib \f(CWXConfigureWindow()\fR function, uses \f(CWrequest_mode\fR to determine which fields in the \f(CWXtWidgetGeometry\fR structure you want to specify. The \f(CWrequest_mode\fR definitions are from <\fIX11/X.h\fP>: .Ps .ta .75i 2i #define CWX (1<<0) #define CWY (1<<1) #define CWWidth (1<<2) #define CWHeight (1<<3) #define CWBorderWidth (1<<4) #define CWSibling (1<<5) #define CWStackMode (1<<6) .Pe The Xt Intrinsics also support the following value: .Ps .ta .75i 2i #define XtCWQueryOnly (1<<7) .Pe \f(CWXtCWQueryOnly\fR indicates that the corresponding geometry request is only a query as to what would happen if this geometry request were made and that no widgets should actually be changed. .LP .Nd 5 The \f(CWstack_mode\fR definitions are from <\fIX11/X.h\fP>: .Ps .ta .75i 2i #define Above 0 #define Below 1 #define TopIf 2 #define BottomIf 3 #define Opposite 4 .Pe The Intrinsics also support the following value: .Ps .ta .75i 2i #define XtSMDontChange 5 .Pe \f(CWXtSMDontChange\fR indicates that the widget wants its current stacking order preserved. For precise definitions of \f(CWAbove\fR, \f(CWBelow\fR, \f(CWTopIf\fR, \f(CWBottomIf\fR, and \f(CWOpposite\fR, see the reference page for \f(CWXConfigureWindow()\fP in \*(V2. .SH "See Also" .na \s-1\fIXtConfigureWidget\fR\s+1\*(s1, \s-1\fIXtMakeResizeRequest\fR\s+1\*(s1, \s-1\fIXtMoveWidget\fR\s+1\*(s1, \s-1\fIXtResizeWidget\fR\s+1\*(s1, .br \s-1\fIgeometry_manager\fR\s+1\*(s4. .ad .XE "geometry management, changes" .XE "geometry management: changing (XtMakeGeometryRequest)" .XE "XtMakeGeometryRequest" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtMakeResizeRequest" "Xt \- Geometry Management" .SH "Name" .Na XtMakeResizeRequest \- request parent to change child's size. .XX "widgets: resizing; XtMakeResizeRequest" .Nz .XX "XtMakeResizeRequest" .SH "Synopsis" .Sy XtGeometryResult XtMakeResizeRequest(\f(CIw\fP, \f(CIwidth\fP, \f(CIheight\fP, \f(CIwidth_return\fP, \f(CIheight_return\fP) .As Widget \f(CIw\fP; Dimension \f(CIwidth\fP, \f(CIheight\fP; Dimension *\f(CIwidth_return\fP, *\f(CIheight_return\fP .Ae .SS "Inputs" .IP \f(CIw\fP 1.2i Specifies the child widget making the request. .IP "\f(CIwidth\fP, \f(CIheight\fP" 1.2i Specify the desired widget width and height. .SS "Outputs" .IP "\f(CIwidth_return\fP, \f(CIheight_return\fP" 1.2i Return a compromise size when the function returns \f(CWXtGeometryAlmost\fP. May be \f(CWNULL\fP if the widget is not interested in compromises. .SS "Returns" A response to the request: \f(CWXtGeometryYes\fP, \f(CWXtGeometryNo\fP or \f(CWXtGeometryAlmost\fP. .\" .SH "Description" \f(CWXtMakeResizeRequest()\fR is a simplified version of \f(CWXtMakeGeometryRequest()\fR that a child can use to ask its parent to change its size. It creates an \f(CWXtWidgetGeometry\fR structure, specifies \f(CIwidth\fP, and \f(CIheight\fP, sets \f(CWrequest_mode\fP to \f(CW(CWWidth CWHeight)\fP, and passes it to \f(CWXtMakeGeometryRequest()\fP. Note that the geometry manager is free to modify any of the other window attributes (position or stacking order) to satisfy the resize request. .LP The return values are as for \f(CWXtMakeGeometryRequest()\fP. If the return value is \f(CWXtGeometryAlmost\fR, \f(CIwidth_return\fR and \f(CIheight_return\fR contain a compromise width and height. If these are acceptable, the widget should immediately make another \f(CWXtMakeResizeRequest()\fR and request that the compromise width and height be applied. .LP See \f(CWXtMakeGeometryRequest()\fP for more information. .\" .SH "Usage" \f(CWXtMakeResizeRequest()\fP should only be used in widget code by widgets which would like to change their own size. Applications that want to set a widget size should use \f(CWXtSetValues()\fP on the \f(CWXtNwidth\fP and \f(CWXtNheight\fP resources of the widget. A widget that wants to change the size of one of its children should use \f(CWXtResizeWidget()\fP. .\" .SH "See Also" .na \s-1\fIXtConfigureWidget\fR\s+1\*(s1, \s-1\fIXtMakeGeometryRequest\fR\s+1\*(s1, \s-1\fIXtMoveWidget\fR\s+1\*(s1, \s-1\fIXtResizeWidget\fR\s+1\*(s1, .br \s-1\fIgeometry_manager\fR\s+1\*(s4. .br .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtMalloc" "Xt \- Memory Allocation" .SH "Name" .Na XtMalloc \- allocate memory. .XX "storage: allocating; XtMalloc" .Nz .XX "XtMalloc" .SH "Synopsis" .Sy char *XtMalloc(\f(CIsize\fP); .As Cardinal\f(CIsize\fP; .Ae .SS "Inputs" .IP \f(CIsize\fP 1i Specifies the number of bytes of memory to allocate. .SS "Returns" A pointer to allocated memory. .\" .SH "Description" \f(CWXtMalloc()\fR allocates and returns a block of \f(CIsize\fP bytes of memory. If there is insufficient memory to allocate the new block, \f(CWXtMalloc()\fR terminates by calling \f(CWXtErrorMsg()\fR. .LP \f(CWXtMalloc()\fR makes no guarantee about the contents of the memory when it is allocated. .SH "Usage" In most cases, you will have to cast the return value of \f(CWXtMalloc()\fP to an appropriate pointer type. .LP \f(CWXtNew()\fR and \f(CWXtNewString()\fR provide slightly higher-level approaches to memory allocation. .LP Memory allocated with \f(CWXtMalloc()\fP must be deallocated with \f(CWXtFree()\fP. The function \f(CWXtMalloc()\fR is implemented by the Toolkit independently of the particular environment, so programs ported to a system not supporting \f(CWmalloc\fR will still work. .SH "See Also" .na \s-1\fIXtCalloc\fR\s+1\*(s1, \s-1\fIXtErrorMsg\fR\s+1\*(s1, \s-1\fIXtFree\fR\s+1\*(s1, \s-1\fIXtNew\fR\s+1\*(s1, \s-1\fIXtNewString\fR\s+1\*(s1, \s-1\fIXtRealloc\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtManageChild" "Xt \- Widget Lifecycle" .SH "Name" .Na XtManageChild \- bring a widget under its parent's geometry management. .XN "widgets: management; (see also XtManageChild)" .XX "widgets, adding to parent list" .Nz .XX "XtManageChild" .SH "Synopsis" .Sy void XtManageChild(\f(CIw\fP) .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the child widget to be managed; Must be of class RectObj or any subclass thereof. .\" .SH "Description" \f(CWXtManageChild()\fR brings a child widget under the geometry management of its parent. All widgets (except shell widgets) must be managed in order to be visible. Managing a widget will generally make it visible, unless its \f(CWXtNmappedWhenManaged\fP resource is \f(CWFalse\fP. .LP \f(CWXtManageChild()\fR constructs a \f(CWWidgetList\fR of length one and calls \f(CWXtManageChildren()\fR. See \f(CWXtManageChildren()\fP for more information. .\" .SH "Usage" Calls to \f(CWXtCreateWidget()\fP and \f(CWXtManageChild()\fP can be combined into a single call to \f(CWXtCreateManagedWidget()\fP or \f(CWXtVaCreateManagedWidget()\fP. .LP If you are going to manage multiple children of the same managed and realized parent, it is more efficient to place those children widget into an array and call \f(CWXtManageChildren()\fP just once, as this results in only a single call to the parent's \f(CWchange_managed()\fP method. If you are creating widgets before the widget tree has been realized, however, managing them one at a time is fine. .LP A widget can be unmanaged by calling \f(CWXtUnmanageChild()\fP. .SH "See Also" .na \s-1\fIXtCreateManagedWidget\fR\s+1\*(s1, \s-1\fIXtIsManaged\fR\s+1\*(s1, \s-1\fIXtManageChildren\fR\s+1\*(s1, \s-1\fIXtSetMappedWhenManaged\fR\s+1\*(s1, \s-1\fIXtUnmanageChild\fR\s+1\*(s1, \s-1\fIXtUnmanageChildren\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtManageChildren" "Xt \- Widget Lifecycle" .SH "Name" .Na XtManageChildren \- bring an array of widgets under their parent's geometry management. .XN "widgets: management; (see also XtManageChildren)" .XS "widgets, adding to parent list" .Nz .XS "XtManageChildren" .SH "Synopsis" .Sy .sp .As void XtManageChildren(\f(CIchildren\fP, \f(CInum_children\fP) WidgetList \f(CIchildren\fP; Cardinal \f(CInum_children\fP; .Ae .SS "Inputs" .IP \f(CIchildren\fP 1.2i Specifies an array of child widgets. The widgets must all be siblings and must be of class RectObj or any subclass thereof. .IP \f(CInum_children\fP Specifies the number of children in the array. .\" .SH "Description" \f(CWXtManageChildren()\fR brings a list of widgets created with \f(CWXtCreateWidget()\fP under the geometry management of their parent. All widgets (except shell widgets) must be managed in order to be visible. Managing a widget will generally make it visible, unless its\p \f(CWXtNmappedWhenManaged\fP resource is \f(CWFalse\fP. .LP The "Algorithm" section below details the procedure followed by \f(CWXtManageChildren()\fP. .\" .SH "Usage" To manage a single widget, you can use \f(CWXtManageChild()\fP. To unmanage widgets, use \f(CWXtUnmanageChild()\fP and \f(CWXtUnmanageChildren()\fP. .LP If you are going to manage multiple children of the same managed and realized parent, it is more efficient to place those children widget into an array and call \f(CWXtManageChildren()\fP just once than it is to manage them individually. The former technique results in only a single call to the parent's \f(CWchange_managed()\fP method. If you are creating widgets before the widget tree has been realized, however, managing them one at a time is fine. .\" .SH "Algorithm" \f(CWXtManageChildren()\fP performs the following: .IP \(bu 3n Issues an error if the children do not all have the same parent or if the parent is not a subclass of \f(CWcompositeWidgetClass\fP. .IP \(bu 3n Returns immediately if the common parent is being destroyed; otherwise, for each unique child on the list, \f(CWXtManageChildren()\fP ignores the child if it already is managed or is being destroyed, and marks it otherwise. .IP \(bu 3n If the parent is realized \f(CWXtManageChildren()\fP does the following: .RS .IP \- 3 Calls the \f(CWchange_managed()\fP method of the widgets' parent. .IP \- 3 Calls \f(CWXtRealizeWidget()\fP on each marked child that is unrealized. .IP \- 3 Maps each marked child that has its \f(CWXtNmappedWhenManaged\fP resource \f(CWTrue\fP. .RE .LP .Nd 5 The management of children is independent of the creation and ordering of the children. There is no special list of managed children; the layout routine of the parent should loop through the list of all children and simply ignore those that are not managed (see \f(CWXtIsManaged()\fP). .\" .SH "Structures" .Ps typedef Widget *WidgetList; .Pe .\" .SH "See Also" \s-1\fIXtCreateManagedWidget\fR\s+1\*(s1, \s-1\fIXtIsManaged\fR\s+1\*(s1, \s-1\fIXtManageChild\fR\s+1\*(s1, \s-1\fIXtMoveWidget\fR\s+1\*(s1, \s-1\fIXtRealizeWidget\fR\s+1\*(s1, \s-1\fIXtSetMappedWhenManaged\fR\s+1\*(s1, \s-1\fIXtUnmanageChild\fR\s+1\*(s1, \s-1\fIXtUnmanageChildren\fR\s+1\*(s1. .ad .XE "widgets, adding to parent list" .XE "XtManageChildren" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtManageChi 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtManageChild@XtManageChA .sp .5 XtManageChildren@XtManageChB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtMapWidget" "Xt \- Widget Lifecycle" .SH "Name" .Na XtMapWidget \- map a widget to its display. .XX "widgets: mapping; to display" .XX "mapping: XtMapWidget" .Nz .XX "XtMapWidget" .SH "Synopsis" .Sy XtMapWidget(\f(CIw\fP) .As Widget \f(CIw\fP\^; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget to be mapped. Must be of class Core or any subclass thereof. .\" .SH "Description" \f(CWXtMapWidget()\fR explicitly maps a widget's window, causing it to become visible. A widget must be realized before it can be mapped. .SH "Usage" A widget should be managed before it is mapped; otherwise the window may not appear at the correct location or size. .LP If a widget's Core \f(CWXtNmappedWhenManaged\fP resource is set to \f(CWTrue\fP, the widget is automatically mapped when it is managed. This is the case for most widgets. Widgets with this resource \f(CWFalse\fP must be mapped explicitly with \f(CWXtMapWidget()\fR. .LP To explicitly unmap a widget without unmanaging it, use \f(CWXtUnmapWidget()\fP. .LP The \f(CWXtNmappedWhenManaged\fP resource can also be set (and the widget mapped and unmapped) with \f(CWXtSetMappedWhenManaged()\fP. .SH "See Also" .na \s-1\fIXtSetMappedWhenManaged\fR\s+1\*(s1, \s-1\fIXtUnmapWidget\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtMenuPopdown" "Xt \- Pop Ups" .SH "Name" .XX "XtMenuPopdown" .Na XtMenuPopdown \- built-in action for popping down a widget. .Nz .XX "menus: XtMenuPopdown" .XX "widgets: popping down (XtMenupopdown)" .XX "XtMenuPopdown" .SH "Synopsis (Translation Table)" .Sy \f(CI\fP: XtMenuPopdown([\f(CIshell\fP]) .As .Ae .SS "Inputs" .IP \f(CIshell\fP 1i An optional argument which specifies the name of the shell to pop down. .\" .SH "Availability" This action is named \f(CWMenuPopdown\fP prior to Release 4. .\" .SH "Description" \f(CWXtMenuPopdown\fP is a predefined action procedure which does not have a corresponding public C routine. It can only be invoked from a translation table. If passed an argument, that argument is interpreted as a shell name, and \f(CWXtMenuPopdown\fP tries to find the named shell by looking up the widget tree starting at the parent of the widget in which it is invoked. If it finds a shell with the specified name in the popup children of that parent, it pops down the shell by calling \f(CWXtPopdown()\fP; otherwise, it moves up the parent chain as needed. If \f(CWXtMenuPopdown\fR gets to the application top-level shell widget and cannot find a matching shell, it generates a warning and returns immediately. If \f(CWXtMenuPopdown\fP is called with no argument, it calls \f(CWXtPopdown()\fP on the widget for which the translation is specified. .\" .SH "Usage" Note that \f(CWXtMenuPopdown\fP is an action procedure; you cannot call it from C code. .LP The action name \f(CWMenuPopdown\fP is a synonym for \f(CWXtMenuPopdown\fP. Either action can be used to pop down menus or other popup shells. .LP Popup shells can also be popped down by calling \f(CWXtPopdown()\fP explicitly, or by using the predefined callback procedure \f(CWXtCallbackPopdown()\fP. .LP The action \f(CWXtMenuPopup\fP can be used to pop up a spring-loaded popup from a translation table. .\" .SH "See Also" \s-1\fIXtCallbackPopdown\fR\s+1\*(s1, \s-1\fIXtMenuPopup\fR\s+1\*(s1, \s-1\fIXtPopDown\fR\s+1\*(s1, \s-1\fIXtPopup\fR\s+1\*(s1, \s-1\fIXtPopupSpringLoaded\fR\s+1\*(s1. .na .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtMenuPopup" "Xt \- Pop Ups" .SH "Name" .XS "XtMenuPopup" .Na XtMenuPopup \- built-in action for popping up a widget. .Nz .XS "menus: XtMenuPopup" .XS "widgets: popping up" .SH "Synopsis (Translation Table)" .Sy \f(CI\fP: XtMenuPopup(\f(CIshell_name\fP) .SS "Inputs" .IP \f(CIshell_name\fP 1i Specifies the name of the widget shell to pop up. .\" .SH "Availability" This action is named \f(CWMenuPopup\fP prior to Release 4. .\" .ad b .SH "Description" \f(CWXtMenuPopdown\fP is a predefined action procedure which does not have a corresponding public C routine. It can only be invoked from a translation table. .LP \f(CWXtMenuPopup\fP tries to find the named shell by searching the widget tree starting at the widget in which it is invoked. If it finds a shell with the specified name in the popup children of that widget, it pops up the shell with the appropriate parameters. Otherwise, it moves up the parent chain to find a popup child with the specified name. If \f(CWXtMenuPopup\fP gets to the application top-level shell widget and has not found a matching shell, it generates a warning and returns immediately. .LP If \f(CWXtMenuPopup\fP is invoked on \f(CWButtonPress\fP, it calls \f(CWXtPopupSpringLoaded()\fP on the specified shell widget. If \f(CWXtMenuPopup\fP is invoked on \f(CWKeyPress\fP or \f(CWEnterWindow\fP, it calls \f(CWXtPopup()\fP on the specified shell widget with \f(CIgrab_kind\fP set to \f(CWXtGrabNonexclusive\fP. Otherwise, the translation manager generates a warning message and ignores the action. .LP \f(CWXtMenuPopup\fP is specially registered with the translation manager as an action that will invoke a grab. This registration is done by calling \f(CWXtRegisterGrabAction()\fP specifying \f(CIowner_events\fP \f(CWTrue\fP, \f(CIevent_mask\fP \f(CWButtonPressMask\fP \fB \fP \f(CWButtonReleaseMask\fP, and \f(CIpointer_mode\fP and \f(CIkeyboard_mode\fP \f(CWGrabModeAsync\fP. .\" .SH "Usage" Note that \f(CWXtMenuPopup\fP is an action procedure; you cannot call it from C code. .LP \f(CWMenuPopup\fP is a synonym for \f(CWXtMenuPopup\fP. .LP Popup shells can also be popped up explicitly using \f(CWXtPopup()\fP, \f(CWXtPopupSpringLoaded()\fP or one of the predefined popup callback procedures (see \f(CWXtCallbackExclusive()\fP). .LP The action \f(CWXtMenuPopdown\fP can be used to pop down a shell widget from a translation table. .SH "See Also" \s-1\fIXtMenuPopdown\fR\s+1\*(s1, \s-1\fIXtPopDown\fR\s+1\*(s1, \s-1\fIXtPopup\fR\s+1\*(s1, \s-1\fIXtPopupSpringLoaded\fR\s+1\*(s1, \s-1\fIXtRegisterGrabAction\fR\s+1\*(s1. .na .ad .XE "menus: XtMenuPopup" .XE "widgets: popping up" .XE "XtMenuPopup" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtMergeArgLists" "Xt \- Argument Lists" .SH "Name" .Na XtMergeArgLists \- merge two \f(CWArgList\fR arrays. .XX "arguments: argument lists; merging ArgList" .XN "ArgList (see arguments)" .XX "arguments: argument lists; XtMergeArgLists" .Nz .XX "XtMergeArgLists" .SH "Synopsis" .Sy ArgList XtMergeArgLists(\f(CIargs1\fP, \f(CInum_args1\fP, \f(CIargs2\fP, \f(CInum_args2\fP) .As ArgList \f(CIargs1\fP; Cardinal \f(CInum_args1\fP; ArgList \f(CIargs2\fP; Cardinal \f(CInum_args2\fP; .Ae .SS "Inputs" .IP \f(CIargs1\fP 1i Specifies the first \f(CWArgList\fR. .IP \f(CInum_args1\fP 1i Specifies the number of arguments in the first argument list. .IP \f(CIargs2\fP 1i Specifies the second \f(CWArgList\fR. .IP \f(CInum_args2\fP 1i Specifies the number of arguments in the second argument list. .SS "Returns" An allocated \f(CWArgList\fP that contains both \f(CIargs1\fP and \f(CIargs2\fP. .SH "Description" \f(CWXtMergeArgLists()\fR allocates a new \f(CWArgList\fR large enough to hold \f(CIargs1\fP and \f(CIargs2\fP and copies both into it. It does not check for duplicate entries. .LP When the new \f(CWArgList\fP is no longer needed, the application program should free it with \f(CWXtFree()\fR. .SH "Structures" \f(CWArg\fR is defined as follows: .Ps typedef struct { String name; XtArgVal value; } Arg, *ArgList; .Pe .SH "See Also" .na \s-1\fIXtFree\fR\s+1\*(s1, \s-1\fIXtSetArg\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtMoveWidget" "Xt \- Geometry Management" .SH "Name" .Na XtMoveWidget \- move a widget within its parent. .XX "widgets: moving (XtMoveWidget)" .Nz .XX "XtMoveWidget" .SH "Synopsis" .Sy void XtMoveWidget(\f(CIw\fP, \f(CIx\fP, \f(CIy\fP) .As Widget \f(CIw\fP; Position \f(CIx\fP; Position \f(CIy\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget to be moved; must be of class RectObj or any subclass thereof. .IP "\f(CIx\fP, \f(CIy\fP" 1i Specify the new widget x and y coordinates. .\" .SH "Description" \f(CWXtMoveWidget()\fR returns immediately if the specified geometry fields for the widget are the same as the current values. Otherwise, \f(CWXtMoveWidget()\fR writes the new \f(CIx\fP and \f(CIy\fP values into the widget and, if the widget is realized, issues an Xlib \f(CWXMoveWindow()\fR call on the widget's window. .\" .SH "Usage" \f(CWXtMoveWidget()\fP should only be used in widget code when a parent widget wants to move one of its children. If an application wants to move a widget, it should set the \f(CWXtNx\fP and \f(CWXtNy\fP resources on the widget. If a widget wants to move itself, it must request that change of its parent by calling \f(CWXtMakeGeometryRequest()\fP. .LP To move and resize a child widget, use \f(CWXtConfigureWidget()\fR. To simply resize a child widget, use \f(CWXtResizeWidget()\fP. .LP .SH "See Also" .na \s-1\fIXtConfigureWidget\fR\s+1\*(s1, \s-1\fIXtMakeGeometryRequest\fR\s+1\*(s1, \s-1\fIXtResizeWidget\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtName" "Xt \- Object Information" .SH "Name" .XX "XtName" .Na XtName \- return a pointer to the instance name of the specified object. .Nz .SH "Synopsis" .Sy String XtName(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object whose name is desired; may be of class Object or any subclass thereof. .SS "Returns" The resource name of \f(CIobject\fP. .SH "Description" \f(CWXtName()\fR returns a pointer to the instance name of the specified object. The storage is owned by the Intrinsics and must not be modified or freed. The name is not qualified by the names of any of the object's ancestors. .SH "See Also" .na \s-1\fIXtNameToWidget\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtNameToWidget" "Xt \- Object Information" .SH "Name" .Na XtNameToWidget \- find a named widget. .XX "widgets: translating; XtNameToWidget" .Nz .SH "Synopsis" .Sy Widget XtNameToWidget(\f(CIreference\fP, \f(CInames\fP); .As Widget \f(CIreference\fP; String \f(CInames\fP; .Ae .SS "Inputs" .IP \f(CIreference\fP 1i Specifies the widget from which the search is to start. Must be of class Core or any subclass. .IP \f(CInames\fP 1i Specifies the partially qualified name of the desired widget. .SS "Returns" A child of \f(CIreference\fP that matches \f(CInames\fP. .\" .SH "Description" \f(CWXtNameToWidget()\fR returns a descendant of the \f(CIreference\fR widget whose name matches the specified \f(CInames\fR. The \f(CInames\fP argument specifies a simple object name or a series of simple object name components separated by periods or asterisks. Asterisks have the same meaning to this function as they do in a resource file. .LP The "Algorithm" section below explains the procedure \f(CWXtNameToWidget()\fP uses to find the named child. .\" .SH "Usage" If you want to look up an immediate child of a widget, simply pass the widget and the child's unqualified name. If you need to lookup a descendant, you can provide a fully qualified name to that descendant, or if you don't know the full name, or if you don't even know how many levels removed that descendant is, you can use an asterisk before the name. .LP Note that if there is more than one child with the specified name, it is undefined which will be returned. .LP You can use \f(CWXtNameToWidget()\fP to hide the details of a user interface and for modular programming. If module A creates an interface which contains a text widget, and module B need to get the contents of the text widget, module A could export the text widget in a global variable, or instead, it could simply define the name of the text widget as part of the module definition. Then module B, or any other module could look up that widget with \f(CWXtNameToWidget()\fP when it is needed. Because \f(CWXtNameToWidget()\fP supports wildcarding, module A can freely change the details of the widget hierarchy it creates as long as the name of the text widget remains unique. .\" .Nd 10 .SH "Algorithm" \f(CWXtNameToWidget()\fR returns the descendant with the shortest name that matches the specification according to the following rules (where child is either a popup child or a normal child if the widget is a subclass of Composite): .IP \(bu 3n Enumerate the object subtree rooted at \f(CIreference\fR widget in breadth-first order, qualifying the name of each object with the names of all its ancestors up to but not including \f(CIreference\fR. The ordering between children of a common parent is not defined. .IP \(bu 3n Return the first object in the enumeration that matches the specified names, where each component of \f(CInames\fR matches exactly the corresponding component of the qualified object name and an asterisk matches any series of components, including none. .IP \(bu 3n If no match is found, return \f(CWNULL\fR. .LP Since breadth-first traversal is specified, the descendant with the shortest matching name (i.e., the fewest number of components), if any, will always be returned. However, since the order of enumeration of children is undefined and since the Intrinsics do not require that all children of a widget have unique names, \f(CWXtNameToWidget()\fR may return any child that matches if there are multiple objects in the subtree with the same name(s). Consecutive separators (periods or asterisks) that contain at least one asterisk are treated as a single asterisk. Consecutive periods are treated as a single period. .SH "See Also" .na \s-1\fIXtCreateWidget\fR\s+1\*(s1, \s-1\fIXtName\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtNew" "Xt \- Memory Allocation" .SH "Name" .Na XtNew \- allocate storage for one instance of a data type. .XX "storage: allocating; XtNew" .XX "XtNew" .Nz .SH "Synopsis" .Sy \f(CItype\fP *XtNew(\f(CItype\fP) .As .Ae .SS "Inputs" .IP \f(CItype\fP 1i Specifies a data type. Note that this is not a variable. .SS "Returns" A pointer to sufficient allocated memory to store a variable of type \f(CWtype\fP. .\" .SH "Description" \f(CWXtNew()\fR is a macro used to allocate storage for one instance of the data type \f(CWtype\fP. It is called with the datatype (a type, not a variable) and returns a pointer to enough allocated memory to hold that type. The return value is correctly cast to \f(CItype\f(CW *\fR. .LP If there is insufficient memory, \f(CWXtNew()\fP calls \f(CWXtErrorMsg()\fR to display an error message and terminate the application. .SH "Usage" Memory allocated with \f(CWXtNew()\fP must be deallocated with \f(CWXtFree()\fP. .LP To allocate memory and copy an a string, use \f(CWXtNewString()\fR. .\" .SH "Example" \f(CWXtNew()\fP can be used as follows: .Ps typedef struct _node { int value; struct _node next; } Node; Node *n = XtNew(Node); .Pe .SH "Background" \f(CWXtNew()\fP is simply the following macro: .Ps #define XtNew(type) ((type *) XtMalloc((unsigned) sizeof(type))) .Pe .SH "See Also" .na \s-1\fIXtMalloc\fR\s+1\*(s1, \s-1\fIXtNewString\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtNewString" "Xt \- Memory Allocation" .SH "Name" .Na XtNewString \- copy an instance of a string. .XX "strings: copying (XtNewString)" .XX "XtNewString" .Nz .SH "Synopsis" .Sy String XtNewString(\f(CIstring\fP) .As String \f(CIstring\fP; .Ae .SS "Inputs" .IP \f(CIstring\fP 1i Specifies a \f(CWNULL\fP-terminated string. .SS "Returns" A copy of \f(CIstring\fP in allocated memory. .\" .SH "Description" \f(CWXtNewString()\fR allocates enough memory to hold a copy of the specified string and copies the string into that memory. If there is insufficient memory to allocate the new block, \f(CWXtNewString()\fR prints an error message and terminates the application by calling \f(CWXtErrorMsg()\fR. .\" .SH "Usage" Memory allocated with \f(CWXtNewString()\fP must be deallocated with \f(CWXtFree()\fP. .LP To simply allocate a specified amount of memory, use \f(CWXtMalloc()\fP. To allocate enough memory for one instance of a specified type, use \f(CWXtNew()\fP. .\" .SH "Example" You might use \f(CWXtNewString()\fP in a situation like this: .Ps String name = XtNewString(XtName(w)); .Pe \f(CWXtName()\fP returns a string that may not be modified. If you copy it, however, you can do anything you like with it, as long as you remember to free it when you are done with it. .\" .SH "Background" \f(CWXtNewString()\fR is defined as the following macro: .Ps #define XtNewString(str) \ #define XtNewString(str) \ ((str) != NULL ? (strcpy(XtMalloc((unsigned)strlen(str) + 1), str)) : NULL) .Pe .SH "See Also" .na \s-1\fIXtMalloc\fR\s+1\*(s1, \s-1\fIXtFree\fR\s+1\*(s1, \s-1\fIXtNew\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtNextEvent" "Xt \- Event Handling" .SH "Name" .Na XtNextEvent \- return next event from input queue. .XX "events: returning next event" .Nz .XX "XtNextEvent" .SH "Synopsis" .Sy void XtNextEvent(\f(CIevent_return\fP) .As XEvent *\f(CIevent_return\fP; .Ae .SS "Inputs" None. .SS "Outputs" .IP \f(CIevent_return\fP 1.2i Returns the dequeued event structure. .\" .SH "Availability" \f(CWXtNextEvent()\fP has been superseded by \f(CWXtAppNextEvent()\fP. .\" .SH "Description" \f(CWXtNextEvent()\fP returns the next event on the input queue. If no events are pending, it flushes the output buffer and blocks. It also dispatches timer and alternate input callbacks and calls any work procedures that have been registered with \f(CWXtAddWorkProc()\fP. .\" .SH "Usage" \f(CWXtNextEvent()\fP has been superseded by \f(CWXtAppNextEvent()\fP, which performs the same function on a per-application context basis. \f(CWXtNextEvent()\fP now calls \f(CWXtAppNextEvent()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtNextEvent()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppNextEvent()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppNextEvent()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtAppNextEvent\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtNumber" "Xt \- Argument Lists" .SH "Name" .Na XtNumber \- determine the number of elements in a fixed-size array. .XX "array: determining number of elements" .XN "array: (see also XtNumber)" .Nz .XX "XtNumber" .SH "Synopsis" .Sy Cardinal XtNumber(\f(CIarray\fP) .As .Ae .SS "Inputs" .IP \f(CIarray\fP 1i Specifies a fixed-size array of arbitrary type. .SS "Returns" The number of elements in \f(CIarray\fP. .\" .SH "Description" \f(CWXtNumber()\fR returns the number of elements in the specified argument list, resource list, or other fixed-size array. It works only for objects which have been statically initialized or declared with a fixed number of elements, i.e., arrays whose total size is known at compile time. .\" .SH "Usage" You should use \f(CWXtNumber()\fP whenever you are passing a static array to a function or storing an static array in a structure that also expects the number of elements in the array. This way, if you change the number of element in the array, the correct number of elements will automatically be compiled in. .\" .SH "Background" \f(CWXtNumber()\fP is a macro defined as follows: .Ps #define XtNumber(arr) ((Cardinal) (sizeof(arr) / sizeof(arr[0]))) .Pe .\" .SH "See Also" .na \s-1\fIXtOffset\fR\s+1\*(s1, \s-1\fIXtOffsetOf\fR\s+1\*(s1, \s-1\fIXtSetArg\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtOffset" "Xt \- Utilities" .SH "Name" .Na XtOffset \- determine the byte offset of a field within a structure pointer type. .XS "structure, determining field's byte offset" .XN "structure: (see also XtOffset)" .Nz .XS "XtOffset" .SH "Synopsis" .Sy Cardinal XtOffset(\f(CIpointer_type\fP, \f(CIfield_name\fP) .As .Ae .SS "Inputs" .IP \f(CIpointer_type\fP 1.1i Specifies a type that is declared as a pointer to the structure. .IP \f(CIfield_name\fP Specifies the name of the field in the structure pointed to by \f(CIpointer_type\fP. .SS "Returns" The offset in bytes of the named field from the beginning of the structure type pointed to by \f(CIpointer_type\fP. .\" .SH "Description" \f(CWXtOffset()\fR is a macro that computes the offset of a named field in a structure, given the field name and a type which points to the structure. .\" .SH "Usage" \f(CWXtOffset()\fP has been superseded by \f(CWXtOffsetOf()\fP which takes the structure type itself rather than a pointer to the structure, and is defined in a more portable way. .LP \f(CWXtOffset()\fR is usually used to determine the location of an variable within a structure when initializing a resource list. It is used by widget writers, and anyone who needs to fetch application resources with \f(CWXtGetApplicationResources()\fP. Resource fields are defined in terms of offsets from a base address from the beginning of a widget. Thus, a resource value can be kept up to date by the Resource Manager without any knowledge of the instance structure of the widget; it uses just a relative byte offset. .\" .SH "Background" \f(CWXtOffset()\fR is a macro defined as follows for most architectures: .Ps #define XtOffset(p_type,field) \ ((Cardinal) (((char *) (&(((p_type)NULL)->field))) - ((char *) NULL))) .Pe .SH "See Also" .na \s-1\fIXtOffsetOf\fR\s+1\*(s1. .ad .XE "structure, determining field's byte offset" .XE "XtOffset" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtOffsetOf" "Xt \- Utilities" .SH "Name" .XX "XtOffsetOf macro" .Na XtOffsetOf \- determine the byte offset of a field within a structure type. .Nz .SH "Synopsis" .Sy Cardinal XtOffsetOf(\f(CIstructure_type\fP, \f(CIfield_name\fP) .As .Ae .SS "Inputs" .IP \f(CIstructure_type\fP 1i Specifies a type that is declared as a structure. .IP \f(CIfield_name\fP 1i Specifies the name of a field of the structure. .SS "Returns" The offset in bytes of the specified field from the beginning of the specified structure. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtOffsetOf()\fR is a macro that expands to a constant expression that gives the offset in bytes to the specified structure member from the beginning of the structure. .SH "Usage" \f(CWXtOffset()\fR is usually used to determine the location of an variable within a structure when initializing a resource list. It is used by widget writers, and anyone who needs to fetch application resources with \f(CWXtGetApplicationResources()\fP. Resource fields are defined in terms of offsets from a base address from the beginning of a widget. Thus, a resource value can be kept up to date by the Resource Manager without any knowledge of the instance structure of the widget; it uses just a relative byte offset. .LP \f(CWXtOffsetOf()\fP is slightly more portable than \f(CWXtOffset()\fP which performs the same function but takes a pointer type rather than a structure type. .\" .SH "Example" \f(CWXtOffsetOf()\fP is used to declare a resource list for the Athena Label widget: .Ps #define offset(field) XtOffsetOf(LabelRec, field) static XtResource resources[] = { {XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel), offset(label.foreground), XtRString, XtDefaultForeground}, {XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct *), offset(label.font),XtRString, XtDefaultFont}, . . .Pe .\" .Nd 10 .SH "Background" \f(CWXtOffsetOf()\fP is defined in terms of \f(CWXtOffset()\fP on many systems: .Ps #ifdef offsetof #define XtOffsetOf(s_type,field) offsetof(s_type,field) #else #define XtOffsetOf(s_type,field) XtOffset(s_type*,field) #endif .Pe .SH "See Also" .na \s-1\fIXtOffset\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtOpenDisplay" "Xt \- Application Contexts" .SH "Name" .Na XtOpenDisplay \- open, initialize, and add a display to an application context. .XS "display: adding; XtOpenDisplay" .Nz .XS "XtOpenDisplay" .SH "Synopsis" .Sy Display *XtOpenDisplay(\f(CIapp_context\fP, \f(CIdisplay_name\fP, \f(CIapplication_name\fP, \f(CIapplication_class\fP, \f(CIoptions\fP, \f(CInum_options\fP, \f(CIargc\fP, \f(CIargv\fP) .As XtAppContext \f(CIapp_context\fP; String \f(CIdisplay_name\fP; String \f(CIapplication_name\fP; String \f(CIapplication_class\fP; XrmOptionDescRec *\f(CIoptions\fP; Cardinal \f(CInum_options\fP; int *\f(CIargc\fP; /* was Cardinal * in Release 4 */ String *\f(CIargv\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context. .IP \f(CIdisplay_name\fP 1i Specifies the name of the display to be opened and initialized, or \f(CWNULL\fP. .IP \f(CIapplication_name\fP 1i Specifies the name of the application instance, or \f(CWNULL\fP. .IP \f(CIapplication_class\fP 1i Specifies the class name of this application, which is usually the generic name for all instances of this application. .IP \f(CIoptions\fP 1i Specifies how to parse the command line for any application-specific resources. .IP \f(CInum_options\fP 1i Specifies the number of entries in the options array. .IP \f(CIargc\fP 1i Specifies a pointer to the number of command line parameters. In Release 4 and previously, this argument was of type \f(CWCardinal *\fP. In Release 5 it is an \f(CWint *\fP. .IP \f(CIargv\fP 1i Specifies the command line parameters. .SS "Outputs" .IP \f(CIargc\fP 1i Returns the number of command line arguments remaining after the command line is parsed. .IP \f(CIargv\fP 1i Returns a modified command line containing only the application name and any arguments that were not recognized as standard Xt options or options specified in \f(CIoptions\fP. .SS "Returns" A pointer to the opened and initialized \f(CWDisplay\fP structure. .\" .SH "Description" \f(CWXtOpenDisplay()\fR opens and initializes a display, and adds it to the specified application context. Note that a display can be in at most one application context. .LP \f(CWXtOpenDisplay()\fR calls \f(CWXOpenDisplay()\fR with the name of the display to open. If \f(CIdisplay_name\fP is \f(CWNULL\fP, \f(CWXtOpenDisplay()\fR uses the current value of the \fI\-display\fP option specified in \f(CIargv\fP or if no display is specified in \f(CIargv\fP, it uses the user's default display (on \s-1POSIX\s0-based systems, this is the value of the DISPLAY environment variable). .LP If the display is successfully opened, \f(CWXtOpenDisplay()\fP parses the command line, builds the resource database and does other per-display initialization by calling \f(CWXtDisplayInitialize()\fR and passing it the application context, the opened display, the application name, and the remaining arguments. The application name is the value of the \fI\-name\fP option if it is specified in \f(CIargv\fP, or the value of the \f(CIapplication_name\fP argument, if it is non-\f(CWNULL\fP, or the value of the RESOURCE_NAME environment variable if it is set, or the name used to invoke the program. On implementations that conform to ANSI-C Hosted Environment support, this is \f(CIargv\f(CW[0]\fR less any directory and file type components; that is, the final component of \f(CIargv\f(CW[0]\fR, if specified. If \f(CIargv\f(CW[0]\fR does not exist or is the empty string, the application name is "main". See \f(CWXtDisplayInitialize()\fP and \f(CWXtAppInitialize()\fP for more information on initializing the display. In particular, see \f(CWXtAppInitialize()\fP for an explanation of how to initialize and array of \f(CWXrmOptionDescRec\fP in order to specify command line options to be parsed. .LP \f(CWXtOpenDisplay()\fR returns the newly opened display or \f(CWNULL\fP if it failed. .\" .SH "Usage" Most applications open only one display. For these applications, it is easiest to simply call \f(CWXtAppInitialize()\fP which will automatically open and initialize a display. Applications that want to use additional displays will usually open and initialize them with \f(CWXtOpenDisplay()\fP. If a display is already open, it can be initialized and added to an application context, thereby making it known to the Intrinsics, by calling \f(CWXtDisplayInitialize()\fP. .LP In Release 4, the \f(CIargc\fP argument is of type \f(CWCardinal *\fP, and in Release 5, this argument is of type \f(CWint *\fP. This is a minor incompatibility that may result warnings from ANSI-C compilers when porting from one release to another. .LP After \f(CWXtDisplayInitialize()\fP has been called, \f(CIargc\fP and \f(CIargv\fP contain only those arguments that were not in the standard option table or in the table specified by the \f(CIoptions\fP argument. If the modified \f(CIargc\fP is not zero, most applications simply print out the modified \f(CIargv\fP along with a message listing the allowable options. .\" .SH "Structures" The \f(CWXrmOptionDescRec\fP structure is as follows. See \f(CWXtAppInitialize()\fP for information on how it is used. .Ps .ps 8 .ta 4n 1.9i typedef enum { /* Value is ... */ XrmoptionNoArg, /* specified in OptionDescRec.value */ XrmoptionIsArg, /* the option string itself */ XrmoptionStickyArg, /* characters immediately following option */ XrmoptionSepArg, /* next argument in argv */ XrmoptionResArg, /* next argument is input to XrmPutLineResource */ /* Ignore this option and ... */ XrmoptionSkipArg, /* the next argument in argv */ XrmoptionSkipNArgs, /* Ignore this option and ... */ /* the next value arguments in argv */ XrmoptionSkipLine /* the rest of argv */ } XrmOptionKind; .sp .5 typedef struct { char *option; /* Option name in argv */ char *specifier; /* Resource name (without application name) */ XrmOptionKind argKind; /* Which style of option it is */ caddr_t value; /* Value to provide if XrmoptionNoArg */ } XrmOptionDescRec, *XrmOptionDescList; .ps .Pe .SH "See Also" .na \s-1\fIXtAppInitialize\fR\s+1\*(s1, \s-1\fIXtDisplayInitialize\fR\s+1\*(s1. .ad .XE "display: adding; XtOpenDisplay" .XE "XtOpenDisplay" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtOrderProc" "Xt \- Geometry Management" .SH "Name" .Na XtOrderProc \- interface definition for an \f(CWXtNinsertPosition\fP procedure. .Nz .XX "XtOrderProc prototype procedure" .XX "insert_position" .SH "Synopsis" .Sy typedef Cardinal (*XtOrderProc)(Widget); .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. .SH "Description" An \f(CWXtOrderProc\fP is registered as the value of the \f(CWXtNinsertPosition\fP resource of a composite widget, and is called by some subclasses of Composite to determine the position in the Composite \f(CWchildren\fP array at which a newly created child should be inserted. .LP An \f(CWXtOrderProc\fP should return the position in the array at which \f(CIw\fP should be inserted. A return value of zero means that it should be the first widget in the array, a return value of one means that there should be one widget before it in the array, and so on. A return value equal to the \f(CWXtNnumChildren\fP resource indicates that the widget should be placed at the end of the array, which is the default if no \f(CWXtOrderProc\fP is registered. .\" .SH "Usage" Note that for many composite widgets, the position of a child in the \f(CWchildren\fP array has nothing to do with its position on the screen. The \f(CWXtNinsertPosition\fP resource will only be interesting if the widget does not provide any other method of positioning its children. .LP The Composite class \f(CWinsert_child()\fP method calls the \f(CWXtOrderProc\fP, if any, registered on the \f(CWXtNinsertPosition\fP resource. Most composite subclasses inherit or call this procedure explicitly and will therefore do the same. .LP Note that the \f(CWXtNinsertPosition\fP procedure is not a method of the widget class. It could be considered an "instance method" rather than a "class method." In this way it is similar to the procedure that can be registered on the \f(CWXtNcreatePopupChildProc\fP resource of a shell widget. .\" .SH "Example" None of the standard MIT clients make use of the \f(CWXtNinsertPosition\fP resource. An example of where an \f(CWXtOrderProc\fP might be useful is an application that dynamically creates a number of button widgets (to represent mail folders or newsgroups, perhaps) and places them in a simple Xaw Box widget. Since these buttons will differ from user to user, and can be inserted and deleted during a session, it would be logical to place them in alphabetical order. An \f(CWXtOrderProc\fP could do this by using \f(CWXtGetValues()\fP to get the current list of widget children, and then comparing the name (using \f(CWXtName()\fP) of the specified widget against the names of all the existing widgets. .\" .SH "See Also" .na \s-1\fIComposite\fR\s+1\*(s3, .br \s-1\fIdelete_child\fR\s+1\*(s4, \s-1\fIinsert_child\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtOverrideTranslations" "Xt \- Translations and Actions" .SH "Name" .Na XtOverrideTranslations \- merge new translations, overriding a widget's existing ones. .XX "translations, merging" .XX "translations, overriding" .XN "translations, XtOverrideTranslations" .Nz .XX "XtOverrideTranslations" .SH "Synopsis" .Sy void XtOverrideTranslations(\f(CIw\fP, \f(CItranslations\fP) .As Widget \f(CIw\fP; XtTranslations \f(CItranslations\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1.1i Specifies the widget into which the new translations are to be merged. Must be of class Core or any subclass thereof. .IP \f(CItranslations\fP Specifies the compiled translation table to merge in. .SH "Description" \f(CWXtOverrideTranslations()\fR merges a compiled translation table \f(CItranslations\fP into a widget's internal compiled translation table, replacing any existing translations that conflict with the new translations. The table \f(CItranslations\fP is not altered by this process. Any "#replace", "#augment", or "#override" directives in \f(CItranslations\fP are ignored by this function. .\" .SH "Usage" Use \f(CWXtParseTranslationTable()\fP to convert a string representation of a translation table to the \f(CWXtTranslations\fP compiled form. .LP To merge translations into a widget without overriding existing translations where there are conflicts, use \f(CWXtAugmentTranslations()\fP. To completely replace a widget's translation table, use \f(CWXtSetValues()\fP to set a compiled translation table on the widget's\p \f(CWXtNtranslations\fP resource. To remove all of a widget's translations, use \f(CWXtUninstallTranslations()\fP. .LP Translation tables can also be specified in string from a resource file. By default, specifying a value for the \f(CWtranslations\fP resource will completely replace the existing translations. If the string form of the translation table begins with the directives "#augment" or "#override", however, then the specified translations will be merged with the widget's existing translations, and new translations that conflict with existing translations will be ignored or will override the existing translations, respectively. .\" .SH "See Also" \s-1\fIXtAugmentTranslations\fR\s+1\*(s1, \s-1\fIXtParseTranslationTable\fR\s+1\*(s1, \s-1\fIXtUninstallTranslations\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtOwnSelection" "Xt \- Selections" .SH "Name" .Na XtOwnSelection \- make selection data available to other clients. .XN "selections: data; XtOwnSelection" .Nz .XS "XtOwnSelection" .SH "Synopsis" .Sy Boolean XtOwnSelection(\f(CIw\fP, \f(CIselection\fP, \f(CItime\fP, \f(CIconvert_proc\fP, \f(CIlose_proc\fP, \f(CIdone_proc\fP) .As Widget \f(CIw\fP; Atom \f(CIselection\fP; Time \f(CItime\fP; XtConvertSelectionProc \f(CIconvert_proc\fP; XtLoseSelectionProc \f(CIlose_proc\fP; XtSelectionDoneProc \f(CIdone_proc\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that wishes to become the owner. .IP \f(CIselection\fP 1i Specifies an atom that describes the type of the selection .hw PRIMARY (usually \f(CWXA_PRI\%MARY\fP, or \f(CWXA_SECONDARY\fP). .IP \f(CItime\fP 1i Specifies the time when selection ownership should commence. This should be the timestamp of the event that triggered ownership. The value \f(CWCurrentTime\fR is not acceptable. .IP \f(CIconvert_proc\fP 1i Specifies the procedure to call whenever someone requests the current value of the selection. .IP \f(CIlose_proc\fP 1i Specifies the procedure to call when the widget loses selection ownership, or \f(CWNULL\fR if the owner is not interested in being called back. .IP \f(CIdone_proc\fP 1i Specifies the procedure to call after a transfer completes, or \f(CWNULL\fR if the owner is not interested in being called back. .SS "Returns" \f(CWTrue\fP if the widget successfully became the selection owner; \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtOwnSelection()\fP tells the Intrinsics that as of time \f(CItime\fP widget \f(CIw\fP has data it would like to make available to other clients through the selection named by \f(CIselection\fP. It registers three procedures with the Intrinsics atomic data transfer mechanism: \f(CIconvert_proc\fP will be called when a client requests the selection; it must convert the selection data to the requested type. \f(CIlose_proc\fP, if non-\f(CWNULL\fP, will be called when another widget or another client asserts ownership of the selection. (It will not be called if the widget relinquishes ownership by calling \f(CWXtDisownSelection()\fP or if the widget fails to gain ownership in the first place.) \f(CIdone_proc\fP, if non-\f(CWNULL\fP will be called after the requesting client has received the data converted by \f(CIconvert_proc\fP. .LP \f(CWXtOwnSelection()\fR returns \f(CWTrue\fP if the widget has successfully become the owner and \f(CWFalse\fP otherwise. The widget may fail to become the owner if some other widget has asserted ownership after this widget, as indicated by \f(CItime\fR. Widgets can lose selection ownership either because another client more recently .ne 2 asserted ownership of the selection, or because the widget voluntarily gave up ownership of the selection with \f(CWXtDisownSelection()\fP. .LP If \f(CIdone_proc\fP is \f(CWNULL\fP, then \f(CWconvert_proc\fP must allocate memory for the transfer with one of the Intrinsics memory allocation routines, so that the Intrinsics can automatically free it. If a non-\f(CWNULL\fP \f(CIdone_proc\fP is specified, it is the responsibility of this procedure to free any memory allocated by the \f(CIconvert_proc\fP. .LP See \f(CWXtConvertSelectionProc\fP(2), \f(CWXtLoseSelectionProc\fP(2), and \f(CWXtSelectionDoneProc\fP(2), for information on how to write the procedures that are passed to this function. .\" .SH "Usage" Note that \f(CWXtOwnSelection()\fP simply informs the Intrinsics that a widget would like to own the selection. It is \f(CIconvert_proc\fP that must do the real work of transferring the selected data. .LP Selection ownership is not restricted to widgets; an application can export data as well. The widget argument to \f(CWXtOwnSelection()\fP serves mainly as a handle to be passed to the various procedures. You can use any widget, but it will make the most sense to use the widget that contains the data you will be exporting. .LP \f(CWXA_PRIMARY\fP and \f(CWXA_SECONDARY\fP are symbolic names for predefined atoms. They are defined in \fI\fP. You can export data over a custom selection, but if you do, only clients that know the selection name will be able to request the data. .LP \f(CWXtLastTimestampProcessed()\fP is a convenient way to obtain a timestamp suitable for use as the \f(CItime\fP argument. .\" .SH "See Also" .na \s-1\fIXtDisownSelection\fR\s+1\*(s1, \s-1\fIXtGetSelectionValue\fR\s+1\*(s1, .br \s-1\fIXtConvertSelectionProc\fR\s+1\*(s2, \s-1\fIXtLoseSelectionProc\fR\s+1\*(s2, \s-1\fIXtSelectionDoneProc\fR\s+1\*(s2. .ad .XE "XtOwnSelection" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtOwnSelectionIncremental" "Xt \- Selections" .SH "Name" .XS "XtOwnSelectionIncremental" .Na XtOwnSelectionIncremental \- make selection data available to other clients using the incremental transfer interface. .Nz .SH "Synopsis" .Sy Boolean XtOwnSelectionIncremental(\f(CIw\fP, \f(CIselection\fP, \f(CItime\fP, \f(CIconvert_callback\fP, \f(CIlose_callback\fP, \f(CIdone_callback\fP, \f(CIcancel_callback\fP, \f(CIclient_data\fP) .As Widget \f(CIw\fP; Atom \f(CIselection\fP; Time \f(CItime\fP; XtConvertSelectionIncrProc \f(CIconvert_callback\fP; XtLoseSelectionIncrProc \f(CIlose_callback\fP; XtSelectionDoneIncrProc \f(CIdone_callback\fP; XtCancelConvertSelectionProc \f(CIcancel_callback\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1.25i Specifies the widget that wishes to become the owner. .IP \f(CIselection\fP 1.25i Specifies an atom that names the selection (usually, \f(CW\s-1XA_PRIMARY\s0\fP or \f(CW\s-1XA_SECONDARY\s0\fP). .IP \f(CItime\fP 1.25i Specifies the timestamp that indicates when the selection ownership should commence. This should be the timestamp of the event that triggered ownership; the value \f(CWCurrentTime\fR is not acceptable. .IP \f(CIconvert_callback\fP 1.25i Specifies the procedure that is to be called whenever the current value of the selection is requested. .IP \f(CIlose_callback\fP 1.25i Specifies the procedure that is to be called when the widget loses selection ownership or \f(CWNULL\fR if the owner is not interested in being notified. .IP \f(CIdone_callback\fP 1.25i Specifies the procedure that is called after the requestor has received the entire selection or \f(CWNULL\fR if the owner is not interested in being notified. .IP \f(CIcancel_callback\fP 1.25i Specifies the procedure that is to be called when a selection request aborts because a timeout expires, or \f(CWNULL\fR if the owner is not interested in being notified. .IP \f(CIclient_data\fP 1.25i Specifies the argument that is to be passed to each of the callback procedures when they are called. .SS "Returns" \f(CWTrue\fP if the widget successfully became the selection owner; \f(CWFalse\fP otherwise. .\" .SH "Availability" Release 4 and later. .\" .Nd 4 .SH "Description" \f(CWXtOwnSelection()\fP tells the Intrinsics that as of time \f(CItime\fP widget \f(CIw\fP has data it would like to make available to other clients through the selection named by \f(CIselection\fP. It registers four procedures with the Intrinsics incremental data transfer mechanism and \f(CIclient_data\fP to be passed to each of these procedures. .LP \f(CIconvert_callback\fP will be called when a client requests the value of the selection. It will be called repeatedly to obtain segments of the selected value until it returns a non-\f(CWNULL\fP value of zero length. Note that this callback must be able to handle multiple transfer requests at various stages of completion. See \f(CWXtConvertSelectionIncrProc\fP(2) for more information. .LP \f(CIlose_callback\fP will be called, if non-\f(CWNULL\fP, when another widget or another client asserts ownership of the selection. (It will not be called if the widget relinquishes ownership by calling \f(CWXtDisownSelection()\fP or if the widget fails to gain ownership in the first place.) See \f(CWXtLoseSelectionIncrProc\fP(2) for more information. .LP \f(CIdone_callback\fP will be called, if non-\f(CWNULL\fP, when all segments of a selection have been transferred. See \f(CWXtSelectionDoneIncrProc\fP(2) for more information. .LP \f(CIcancel_callback\fP will be called, if non-\f(CWNULL\fP, if a selection request is aborted because a timeout expires. See \f(CWXtCancelConvertSelctionProc\fP(2) for more information. .LP \f(CWXtOwnSelectionIncremental()\fP returns \f(CWTrue\fR if the specified widget successfully becomes the selection owner or \f(CWFalse\fR otherwise. The widget may fail to become the owner if some other widget has asserted ownership after this widget, as indicated by \f(CItime\fR. .LP If \f(CIdone_callback\fP is \f(CWNULL\fP, then \f(CWconvert_callback\fP must allocate memory for the transfer with one of the Intrinsics memory allocation routines, so that the Intrinsics can automatically free it. If a non-\f(CWNULL\fP \f(CIdone_callback\fP is specified, it is the responsibility of this procedure or the \f(CIcancel_callback\fP to free any memory allocated by the \f(CIconvert_callback\fP. After a selection transfer has started, only one of the \f(CIdone_callback\fR or \f(CIcancel_callback\fR procedures will be invoked to indicate completion or termination of the transfer. .LP The \f(CIlose_callback\fR does not indicate completion of any in-progress transfers; it will be invoked at the time a \f(CWSelectionClear\fR event is dispatched regardless of any active transfers, which are still expected to continue. .LP A widget that becomes the selection owner using \f(CWXtOwnSelectionIncremental()\fR may use \f(CWXtDisownSelection()\fP to relinquish selection ownership. .\" .SH "Usage" Note that \f(CWXtOwnSelection()\fP simply informs the Intrinsics that a widget would like to own the selection. It is \f(CIconvert_proc\fP that must do the real work of transferring the selected data. .LP Most selection data can be transferred using the Intrinsics simpler atomic transfer mechanism; see \f(CWXtOwnSelection()\fP. For some widgets, however, an incremental transfer may be more convenient. A text widget that supports disjoint selections of text, for example, may prefer to export each contiguous segment individually rather than copying them all into one large block. Note that the Intrinsics will automatically break up and reassemble blocks of data if they are too big for transfer using the .ne 2 underlying X protocol; large data size is therefore not necessarily a reason for using incremental transfers. .LP Selection ownership is not restricted to widgets; an application can export data as well. The widget argument to \f(CWXtOwnSelectionIncremental()\fP serves mainly as a handle to be passed to the various procedures. You can use any widget, but it will make the most sense to use the widget that contains the data you will be exporting. .LP \f(CWXA_PRIMARY\fP and \f(CWXA_SECONDARY\fP are symbolic names for predefined atoms. They are defined in \fI\fP. You can export data over a custom selection, but if you do, only clients that know the selection name will be able to request the data. .LP \f(CWXtLastTimestampProcessed()\fP is a convenient way to obtain a timestamp suitable for use as the \f(CItime\fP argument. .\" .SH "See Also" .na \s-1\fIXtAppGetSelectionTimeout\fR\s+1\*(s1, \s-1\fIXtAppSetSelectionTimeout\fR\s+1\*(s1, \s-1\fIXtDisownSelection\fR\s+1\*(s1, \s-1\fIXtGetSelectionValue\fR\s+1\*(s1, \s-1\fIXtOwnSelection\fR\s+1\*(s1, .br \s-1\fIXtCancelConvertSelectionProc\fR\s+1\*(s2, \s-1\fIXtConvertSelectionIncrProc\fR\s+1\*(s2, \s-1\fIXtLoseSelectionIncrProc\fR\s+1\*(s2, \s-1\fIXtSelectionDoneIncrProc\fR\s+1\*(s2. .ad .\"last line comment .XE "XtOwnSelectionIncremental" .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtOwnSelect 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtOwnSelection@XtOwnSelecA .sp .5 XtOwnSelectionIncremental@XtOwnSelecB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtParent" "Xt \- Object Information" .SH "Name" .Na XtParent \- return the parent of the specified widget. .XX "widgets: parent widget (XtParent)" .Nz .XX "XtParent" .SH "Synopsis" .Sy Widget XtParent(\f(CIw\fP) .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget whose parent is to be returned. May be of class Object or any subclass thereof. .SS "Returns" The parent of \f(CIw\fP. .SH "Description" \f(CWXtParent()\fR returns the parent widget of the specified object. .SH "Usage" \f(CWXtParent()\fP is implemented as a function when called from application code, but is replaced by a more efficient macro when called from widget code including the file \fI\fP. .LP If \f(CWXtParent()\fP is called on a toplevel shell widget which has no parent (such as those created by \f(CWXtAppInitialize()\fP or \f(CWXtAppCreateShell()\fP, for example) it returns \f(CWNULL\fP. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtParseAcceleratorTable" "Xt \- Translations and Actions" .SH "Name" .Na XtParseAcceleratorTable \- compile an accelerator table into its internal representation. .XX "accelerators, compiling accelerator table" .Nz .XX "XtParseAcceleratorTable" .SH "Synopsis" .Sy XtAccelerators XtParseAcceleratorTable(\f(CItable\fP) .As String \f(CItable\fP; .Ae .SS "Inputs" .IP \f(CItable\fP 1i Specifies the accelerator table to compile. .SS "Returns" The compiled form of \f(CItable\fP. .\" .SH "Description" \f(CWXtParseAcceleratorTable()\fR compiles the accelerator table into its opaque internal representation. This compiled table can be used to set the \f(CWXtNaccelerators\fP resource of a widget. .LP The syntax of the string form of an accelerator table is the same as that of a translation table, and is described in Appendix F. The interpretation of the \f(CW#augment\fR and \f(CW#override\fR directives is different in accelerator tables than in translation tables, however. This directive, if specified, applies to what will happen when the accelerator is installed; that is, whether or not the accelerator translations will override the translations in the destination widget. The default is \f(CW#augment\fP, which means that the accelerator translations have lower priority than the destination translations. The \f(CW#replace\fR directive is ignored for accelerator tables. .\" .SH "Usage" An accelerator binds an event sequence in one widget to actions in another. Accelerators are set as a resource of a widget but do not take effect until they are "installed" on a destination widget. See \f(CWXtInstallAccelerators()\fP. .LP When an accelerator table is specified in a resource file, it is automatically parsed by one of Xt's converters, and \f(CWXtParseAcceleratorTable()\fP is not used. .LP Another way to parse an accelerator table is to use the \f(CWXtVaTypedArg\fP feature at \f(CWXtVaCreateWidget()\fP or \f(CWXtVaSetValues()\fP and specify the string form directly. This will invoke the appropriate resource converter to compile the table. .\" .SH "See Also" .na \s-1\fIXtInstallAccelerators\fR\s+1\*(s1, \s-1\fIXtInstallAllAccelerators\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtParseTranslationTable" "Xt \- Translations and Actions" .SH "Name" .Na XtParseTranslationTable \- compile a translation table into its internal representation. .XS "translations: compiling; table" .XS "translations: compiling; XtParseTranslationTable" .Nz .XS "XtParseTranslationTable" .SH "Synopsis" .Sy XtTranslations XtParseTranslationTable(\f(CItable\fP) .As String \f(CItable\fP; .Ae .SS "Inputs" .IP \f(CItable\fP 1i Specifies the translation table to compile. .SS "Returns" The compiled form of \f(CItable\fP. .\" .SH "Description" \f(CWXtParseTranslationTable()\fR compiles \f(CItable\fR into its opaque internal representation of type \f(CWXtTranslations\fR. This compiled form can then be set as the value of a widget's \f(CWXtNtranslations\fP resource, or merged with a widget's existing translation table with \f(CWXtAugmentTranslations()\fP or \f(CWXtOverrideTranslations()\fP. .LP The syntax of the string representation of a translation table is documented in Appendix F. .LP If an empty translation table is required for any purpose, one can be obtained by calling \f(CWXtParseTranslationTable()\fR and passing an empty string. .\" .SH "Usage" This function is generally only needed by application writers. When writing a widget, you specify a default translation table as a string, which the Intrinsics automatically parse. .LP You only need to use this function when you want to set translation values from C code; translation tables specified in resource files are automatically compiled by a resource converter. .LP It is also possible to set a translation table with the \f(CWXtVaTypedArg\fP feature of \f(CWXtVaCreateWidget()\fP and \f(CWXtVaSetValues()\fP. This allows you to specify the translation table in string form, and have the appropriate resource converter automatically invoked to compile it. .LP The string \f(CItable\fP passed to \f(CWXtParseTranslationTable\fR can be freed after the call if there are no more explicit references to it. .\" .SH "See Also" .na \s-1\fIXtAugmentTranslations\fR\s+1\*(s1, \s-1\fIXtOverrideTranslations\fR\s+1\*(s1, \s-1\fIXtUninstallTranslations\fR\s+1\*(s1. .ad .XE "translations: compiling; table" .XE "translations: compiling; XtParseTranslationTable" .XE "XtParseTranslationTable" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtPeekEvent" "Xt \- Event Handling" .SH "Name" .Na XtPeekEvent \- return, but do not remove the event at the head of an application's input queue. .XX "input: queue; examining head" .XX "input: queue; XtPeekEvent" .Nz .XX "XtPeekEvent" .SH "Synopsis" .Sy Boolean XtPeekEvent(\f(CIevent_return\fP) .As XEvent *\f(CIevent_return\fP; .Ae .SS "Inputs" .IP \f(CIevent_return\fP 1.2i Returns the event information from the head event structure in the queue. .SS "Returns" \f(CWTrue\fP if the event at the head of the queue is an X event; \f(CWFalse\fP if it is a timer event or an alternate input source event. .\" .SH "Availability" \f(CWXtPeekEvent()\fP has been superseded by \f(CWXtAppPeekEvent()\fP. .\" .SH "Description" \f(CWXtPeekEvent()\fR returns a copy of the X event at the head of the input queue, without removing it from the queue. If there is an X event, it returns \f(CWTrue\fP. If there are no X events pending, but there are timer or alternate events, \f(CWXtPeekEvent()\fP returns \f(CWFalse\fP. If there are no events pending, \f(CWXtPeekEvent()\fP blocks. .\" .SH "Usage" \f(CWXtPeekEvent()\fP has been superseded by \f(CWXtAppPeekEvent()\fP, which performs the same function on a per-application context basis. \f(CWXtPeekEvent()\fP now calls \f(CWXtAppPeekEvent()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtPeekEvent()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppPeekEvent()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppPeekEvent()\fP for more information. .LP Programs rarely need this much control over the event dispatching mechanism. Most programs use \f(CWXtAppMainLoop()\fR. .\" .SH "See Also" .na \s-1\fIXtAppMainLoop\fR\s+1\*(s1, \s-1\fIXtAppPeekEvent\fR\s+1\*(s1, \s-1\fIXtAppPending\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtPending" "Xt \- Event Handling" .SH "Name" .Na XtPending \- determine if there are any events in an application's input queue. .XX "events, XtAppPending" .XX "input: queue; XtAppPending" .XX "input: queue; determining events" .Nz .XX "XtPending" .SH "Synopsis" .Sy XtInputMask XtPending() .As .Ae .SS "Inputs" None. .SS "Returns" An \f(CWXtInputMask\fP which indicates what kind of events, if any, are pending on \f(CIapp_context\fP. .\" .SH "Availability" \f(CWXtPending()\fP has been superseded by \f(CWXtAppPending()\fP. .\" .SH "Description" \f(CWXtAppPending()\fR returns a nonzero value if there are pending events from the X server, timer, or other input sources. .LP The return value is a bit mask that is the OR of \f(CWXtIMXEvent\fR (an X event), \f(CWXtIMTimer\fR (a timer event\-see \f(CWXtAppAddTimeOut()\fP), and \f(CWXtIMAlternateInput\fR (an alternate input event\-see \f(CWXtAppAddInput()\fP). .\" .SH "Usage" \f(CWXtPending()\fP has been superseded by \f(CWXtAppPending()\fP, which performs the same function on a per-application context basis. \f(CWXtPending()\fP now calls \f(CWXtAppPending()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtPending()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppPending()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppPending()\fP for more information. .LP Programs rarely need this much control over the event dispatching mechanism. Most programs use \f(CWXtAppMainLoop()\fR. .SH "See Also" .na \s-1\fIXtAppMainLoop\fR\s+1\*(s1, \s-1\fIXtAppPeekEvent\fR\s+1\*(s1, \s-1\fIXtAppPending\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtPopdown" "Xt \- Pop Ups" .SH "Name" .Na XtPopdown \- unmap a popup shell. .XX "popups, unmapping" .XX "mapping: XtPopdown" .Nz .XX "XtPopdown" .SH "Synopsis" .Sy void XtPopdown(\f(CIpopup_shell\fP) .As Widget \f(CIpopup_shell\fP; .Ae .SS "Inputs" .IP \f(CIpopup_shell\fP 1i Specifies the widget shell to pop down. .SH "Description" \f(CWXtPopdown()\fP pops down a popup shell and calls the functions registered on the shell's\p \f(CWXtNpopdownCallback\fP list. The "Algorithm" section below explains the details of this process. .\" .SH "Usage" The Intrinsics also provide other convenience routines to pop down a popup shell. To perform a pop down from a callback list, register the function \f(CWXtCallbackPopdown()\fR. To do so from a translation table, use the action \f(CWXtMenuPopdown\fP. .LP Popup shell widgets can be created with \f(CWXtCreatePopupShell()\fR, and can be popped up with \f(CWXtPopup()\fP or \f(CWXtPopupSpringLoaded()\fP, or with one of the built-in callback functions (\f(CWXtCallbackExclusive()\fP, \f(CWXtCallbackNonexclusive()\fP, or \f(CWXtCallbackNone()\fP), or with the built-in action \f(CWXtMenuPopup\fP. .\" .SH "Algorithm" \f(CWXtPopdown()\fP performs the following: .IP \(bu 3n Calls \f(CWXtCheckSubclass()\fP to ensure \f(CIpopup_shell\fP's class is a subclass of \f(CWshellWidgetClass\fP. .IP \(bu 3n Checks that the \f(CWpopped_up\fP field of \f(CIpopup_shell\fP is \f(CWTrue\fP; otherwise, it returns immediately. .IP \(bu 3n Unmaps \f(CIpopup_shell\fP's window and, if \f(CWoverride_redirect\fP is \f(CWFalse\fP, sends a synthetic \f(CWUnmapNotify\fP event as specified by the \fIInter-Client Communications Conventions Manual\fP. .IP \(bu 3n If \f(CIpopup_shell\fP's \f(CWgrab_kind\fP is either \f(CWXtGrabNonexclusive\fP or \f(CWXtGrabExclusive\fP, it calls \f(CWXtRemoveGrab()\fP. .IP \(bu 3n Sets \f(CIpopup_shell\fP's \f(CWpopped_up\fP field to \f(CWFalse\fP. .IP \(bu 3n Calls the callback procedures on the shell's \f(CWpopdown_callback\fP list, specifying a pointer to the value of the shell's \f(CWgrab_kind\fP field as the \f(CIcall_data\fP argument. .LP .SH "See Also" .na \s-1\fIXtCallbackPopdown\fR\s+1\*(s1, \s-1\fIXtCreatePopupShell\fR\s+1\*(s1, \s-1\fIXtMenuPopdown\fR\s+1\*(s1, \s-1\fIXtPopup\fR\s+1\*(s1, \s-1\fIXtPopupSpringLoaded\fR\s+1\*(s1, \s-1\fIXtRemoveGrab\fR\s+1\*(s1. .\".ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtPopup" "Xt \- Pop Ups" .SH "Name" .Na XtPopup \- map a popup shell. .XS "popups, mapping" .XS "mapping: XtPopup" .Nz .XS "XtPopup" .SH "Synopsis" .Sy void XtPopup(\f(CIpopup_shell\fP, \f(CIgrab_kind\fP) .As Widget \f(CIpopup_shell\fP; XtGrabKind \f(CIgrab_kind\fP; .Ae .SS "Inputs" .IP \f(CIpopup_shell\fP 1i Specifies a shell widget returned by \f(CWXtCreatePopupShell()\fR. .IP \f(CIgrab_kind\fP 1i Specifies how user events should be constrained. (Can be one of \f(CWXtGrabNone\fP, \f(CWXtGrabNonexclusive\fP, \f(CWXtGrabExclusive\fP.) .\" .SH "Description" \f(CWXtPopup()\fP calls the functions registered on the shell's \f(CWXtNpopupCallback\fP list and pops up the shell widget (and its managed child). The "Algorithm" section below explains this process in more detail. .LP If \f(CIgrab_kind\fP is \f(CWXtGrabNone\fP, the resulting popup is "modeless", and does not lock out input events to the rest of the application. If it is \f(CWXtGrabNonexclusive\fP, then the resulting popup is "modal" and locks out input to the main application window, but not to other modal popups that are currently popped up. If it is \f(CWXtGrabExclusive\fP, then the resulting popup is modal and locks out input to the main application window and all previous popup windows. For more details on \f(CWXtGrabNonexclusive\fP and \f(CWXtGrabExclusive\fP, see \f(CWXtAddGrab()\fP. .\" .SH "Usage" By default, \f(CWXtPopup()\fR maps its window to the upper-left corner of the display. You will generally want to position the shell by setting its \f(CWXtNx\fP and \f(CWXtNy\fP resources before calling \f(CWXtPopup()\fR. .LP The Intrinsics also provide convenience routines to popup a shell. To perform a pop up from a callback list, register one of the functions \f(CWXtCallbackNone()\fR, \f(CWXtCallbackNonexclusive()\fR, or \f(CWXtCallbackExclusive()\fR. To do so from a translation table, use the \f(CWXtMenuPopup\fP action. .LP Widgets can be popped down with \f(CWXtPopdown()\fR, the \f(CWXtCallbackPopdown()\fP callback function, or the \f(CWXtMenuPopdown\fP action. .LP If you are using the Motif widget set, you will generally never need to call \f(CWXtPopup()\fP or \f(CWXtPopdown()\fP. The Motif XmDialogShell widget automatically pops up when its child is managed, and pops down when its child is unmanaged. .\" .SH "Algorithm" The \f(CWXtPopup()\fP function performs the following: .IP \(bu 3n Calls \f(CWXtCheckSubclass()\fP to ensure \f(CIpopup_shell\fP's class is a subclass of \f(CWshellWidgetClass\fP. .IP \(bu 3n Raises the window and returns if the shell's \f(CWpopped_up\fP field is already \f(CWTrue\fP. .IP \(bu 3n Calls the callback procedures on the shell's \f(CWXtNpopupCallback\fP list, specifying a pointer to the value of \f(CIgrab_kind\fP as the \f(CIcall_data\fP argument. .IP \(bu 3n Sets the shell \f(CWpopped_up\fP field to \f(CWTrue\fP, the shell \f(CWspring_loaded\fP field to \f(CWFalse\fP, and the shell \f(CWgrab_kind\fP field from \f(CIgrab_kind\fP. .IP \(bu 3n If the shell's \f(CWXtNcreatePopupChildProc\fP resource is non-\f(CWNULL\fP, \f(CWXtPopup()\fP calls the specified procedure with \f(CIpopup_shell\fP as the parameter. .IP \(bu 3n If \f(CIgrab_kind\fP is either \f(CWXtGrabNonexclusive\fP or \f(CWXtGrabExclusive\fP, it calls: .Ps XtAddGrab(\f(CIpopup_shell\fP, (\f(CIgrab_kind\fP == XtGrabExclusive), False) .Pe .IP \(bu 3n Calls \f(CWXtRealizeWidget()\fP with \f(CIpopup_shell\fP specified. .IP \(bu 3n Calls \f(CWXMapRaised()\fP with the window of \f(CIpopup_shell\fP. .LP .\" .SH "Structures" The \f(CWXtGrabKind\fP type is defined as follows: .Ps typedef enum {XtGrabNone, XtGrabNonexclusive, XtGrabExclusive} XtGrabKind; .Pe .\" .SH "See Also" .na \s-1\fIXtAddGrab\fR\s+1\*(s1, \s-1\fIXtCallbackExclusive\fR\s+1\*(s1, \s-1\fIXtCallbackNone\fR\s+1\*(s1, \s-1\fIXtCallbackNonexclusive\fR\s+1\*(s1, \s-1\fIXtCallbackPopdown\fR\s+1\*(s1, \s-1\fIXtCreatePopupShell\fR\s+1\*(s1, \s-1\fIXtMenuPopdown\fR\s+1\*(s1, \s-1\fIXtMenuPopup\fR\s+1\*(s1, \s-1\fIXtPopdown\fR\s+1\*(s1, \s-1\fIXtPopupSpringLoaded\fR\s+1\*(s1. .ad .XE "popups, mapping" .XE "mapping: XtPopup" .XE "XtPopup" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtPopupSpringLoaded" "Xt \- Pop Ups" .SH "Name" .XX "XtPopupSpringLoaded" .Na XtPopupSpringLoaded \- map a spring-loaded popup from within an application. .Nz .SH "Synopsis" .Sy void XtPopupSpringLoaded(\f(CIpopup_shell\fP) .As Widget \f(CIpopup_shell\fP; .Ae .SS "Inputs" .IP \f(CIpopup_shell\fP 1i Specifies the shell widget to be popped up. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtPopupSpringLoaded()\fP calls the functions registered on the specified shell's\p \f(CWXtNpopupCallback\fP callback list and pops the shell up, making it a spring-loaded shell. A spring-loaded shell is one that is popped up in response to a button press and will pop down when the button is released. Spring-loaded shells have events dispatched to them specially to ensure that they receive the button up event, even if it occurs in another window. See \f(CWXtAddGrab()\fP for more details. .LP \f(CWXtPopupSpringLoaded()\fR performs exactly like \f(CWXtPopup()\fR, except that \f(CWXtPopupSpringLoaded()\fP does the following: .IP \(bu 3n Sets the shell \f(CIspring_loaded\fR field to \f(CWTrue\fR. .IP \(bu 3n Always calls \f(CWXtAddGrab()\fR with \f(CIexclusive\fP set to \f(CWTrue\fR and \f(CIspring_loaded\fP set to \f(CWTrue\fR. .LP See \f(CWXtPopup()\fP for details. .\" .SH "Usage" You can also pop up spring loaded shells by using the \f(CWXtMenuPopup\fP action in a translation table. This predefined action calls \f(CWXtPopupSpringLoaded()\fP. .LP Any pop up shell can be popped down with \f(CWXtPopdown()\fP, the \f(CWXtCallbackPopdown()\fP callback function, or with the \f(CWXtMenuPopdown\fP action. .LP \f(CWXtPopupSpringLoaded()\fP was added in Release 4, and prior to this release, the only way to pop up a spring loaded shell was to use the \f(CWMenuPopup\fP action (which has now been renamed \f(CWXtMenuPopup\fP). .\" .SH "See Also" .na \s-1\fIXtAddGrab\fR\s+1\*(s1, \s-1\fIXtCreatePopupShell\fR\s+1\*(s1, \s-1\fIXtMenuPopdown\fR\s+1\*(s1, \s-1\fIXtMenuPopup\fR\s+1\*(s1, \s-1\fIXtPopdown\fR\s+1\*(s1, \s-1\fIXtPopup\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtProc" "Xt \- Widget Method Prototypes" .SH "Name" .Na XtProc \- interface definition for the \f(CWclass_initialize()\fP method. .Nz .XX "XtProc" .SH "Synopsis" .Sy typedef void (*XtProc)(void); .As .Ae .\" .SH "Description" \f(CWXtProc\fP is the type of the Core, RectObj, and Object \f(CWclass_initialize()\fP method. See \f(CWclass_initialize\fP(4) for more information. .\" .SH "See Also" .na \s-1\fIclass_initialize\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtProcessEvent" "Xt \- Event Handling" .SH "Name" .Na XtProcessEvent \- get and process one input event of a specified type. .XX "events: processing one event; XtProcessEvent" .Nz .XX "XtProcessEvent" .SH "Synopsis" .Sy void XtProcessEvent(\f(CImask\fP) .As XtInputMask \f(CImask\fP; .Ae .SS "Inputs" .IP \f(CImask\fP 1i Specifies what types of events to process. .\" .SH "Availability" \f(CWXtProcessEvent()\fP has been superseded by \f(CWXtAppProcessEvent()\fP. .\" .SH "Description" \f(CWXtProcessEvent()\fP processes one X event, alternate input source event or timer event. The \f(CImask\fP argument specifies which types of events are to be processed; it is the bitwise inclusive OR (\^\fB \fP\^) of any of the values \f(CWXtIMXEvent\fP, \f(CWXtIMTimer\fP, or \f(CWXtIMAlternateInput\fP, or the value \f(CWXtIMAll\fP which specifies all three event types. \f(CWXtProcessEvent()\fP calls any registered background work procedures if there are no events available, and blocks if there are no events and no work procedures. .\" .SH "Usage" \f(CWXtProcessEvent()\fP has been superseded by \f(CWXtAppProcessEvent()\fP, which performs the same function on a per-application context basis. \f(CWXtProcessEvent()\fP now calls\p \f(CWXtAppProcessEvent()\fP passing the default application context created by\p \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can\p continue to use \f(CWXtProcessEvent()\fP if you initialize your application with\p \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppProcessEvent()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppProcessEvent()\fP for more information. .LP Programs rarely need this much control over the event dispatching mechanism. Most programs use \f(CWXtAppMainLoop()\fR. .SH "See Also" .na \s-1\fIXtAppMainLoop\fR\s+1\*(s1, \s-1\fIXtAppPeekEvent\fR\s+1\*(s1, \s-1\fIXtAppPending\fR\s+1\*(s1, \s-1\fIXtAppProcessEvent\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtQueryGeometry" "Xt \- Geometry Management" .SH "Name" .Na XtQueryGeometry \- query a child widget's preferred geometry. .XS "geometry management: querying; XtQueryGeometry" .XN "widgets, geometry (see geometry management)" .Nz .XS "XtQueryGeometry" .SH "Synopsis" .Sy XtGeometryResult XtQueryGeometry(\f(CIw\fP, \f(CIintended\fP, \f(CIpreferred_return\fP) .As Widget \f(CIw\fP\^; XtWidgetGeometry \f(CI*intended\fP; XtWidgetGeometry \f(CI*preferred_return\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget whose geometry preferences are being queried. .IP \f(CIintended\fP 1i Specifies any changes the parent plans to make to the child's geometry, or \f(CWNULL\fR. .IP \f(CIpreferred_return\fP 1i Returns the child widget's preferred geometry. .SS "Returns" A response to the request: \f(CWXtGeometryYes\fP, \f(CWXtGeometryNo\fP, or \f(CWXtGeometryAlmost\fP. .\" .SH "Description" \f(CWXtQueryGeometry()\fP invokes a widget's \f(CWquery_geometry()\fP method to determine its preferred (or at least its current) geometry. Some parents may want to ask their children what their ideal geometry would be if they were not constrained at all. Others, when about to set some aspect of the geometry (such as width), may query the child to determine what its preferred geometry would be given this new constraint. For example, a label widget that supported word-wrapping might want a larger height if its width was being made smaller. .LP The \f(CIintended\fP structure specifies the geometry values that the parent plans to set. The \f(CIgeometry_return\fP structure returns the child's preferred geometry. Each argument has a flags field in which bits are set to indicate which of the geometry fields the respective widgets have set. The return value of the function may be one of the following values: .IP \f(CWXtGeometryYes\fP .25i The proposed change is acceptable to the child without modifications. This means that the proposed changes are exactly what the child would prefer. .IP \f(CWXtGeometryAlmost\fP .25i The child does not agree entirely with the proposed change. At least one field in \f(CIpreferred_return\fP with a bit set in \f(CIpreferred_return\f(CW->request_mode\fR is different from the corresponding field in \f(CIrequest\fP, or a bit was set in \f(CIpreferred_return\f(CW->request_mode\fR that was not set in the request. The parent can use or ignore the returned values in \f(CIpreferred_return\fP. .IP \f(CWXtGeometryNo\fP .25i The child would prefer that no changes were made to its current geometry. The parent can respect or ignore this response. .LP .Nd 5 If the child widget does not have a \f(CWquery_geometry()\fP method, \f(CWXtQueryGeometry()\fP fills \f(CWpreferred_return\fP with the widget's current geometry, sets \f(CIpreferred_return\f(CW->request_mode\fR to zero, and returns \f(CWXtGeometryYes\fP. .LP If the \f(CIintended\fP argument is \f(CWNULL\fP, \f(CWXtQueryGeometry()\fP replaces it with a pointer to an \f(CWXtWidgetGeometry\fP structure with a \f(CWrequest_mode\fP field of zero before calling the \f(CWquery_geometry()\fP method. .LP After calling a child's \f(CWquery_geometry()\fP method, \f(CWXtQueryGeometry()\fP sets all fields in \f(CIpreferred_return\fP that do not have bits set in \f(CIpreferred_return\f(CW->request_mode\fR to the widget's current geometry values. \f(CWXtQueryGeometry()\fP clears all bits in \f(CIpreferred_return\f(CW->request_mode\fR before calling the \f(CWquery_geometry()\fP method, and does not modify the bits set by the child. .LP See the "Background" section below for more information. See \f(CWquery_geometry()\fP(4) for more information on how a widget's \f(CWquery_geometry()\fP method should behave. .\" .SH "Usage" Only widgets should ever need to use \f(CWXtQueryGeometry()\fP, and then should only call it for their children. It is usually used when a composite widget is trying to layout its children, for example, when the \f(CWchanged_managed()\fP method is called. .LP Many widgets can simply examine their children's \f(CWcore.width\fP and \f(CWcore.height\fP fields and use those while calculating layout. Widgets are supposed to set these fields to their desired geometry within their \f(CWinitialize()\fP and \f(CWset_values()\fP methods. Since these are the only geometry fields that many parents care about, this technique is often sufficient. If a widget is re-laying out its children from its \f(CWresize()\fP method, however, it may make more sense to use \f(CWXtQueryGeometry()\fP. If a widget has been given a size that is too small, then its children may also be smaller than they prefer. In this case, the children's current sizes are not their preferred sizes, and they must be asked how large they would like to be. .LP Note that on return from \f(CWXtQueryGeometry()\fP, \f(CWpreferred_return\fP always contains the preferred or current geometry (which the widget sets to its preferred geometry when it initializes itself) of the widget. This means that a parent that is willing to respect its child's layout wishes can call \f(CWXtQueryGeometry()\fP and use the contents of \f(CIpreferred_return\fP whatever the return value of the function is. If a parent wants to query a preferred size without proposing any particular changes, it can pass \f(CWNULL\fP for \f(CIintended\fP. .LP If a parent is not willing to respond to return values of either \f(CWXtGeometryAlmost\fP or \f(CWXtGeometryNo\fP need not bother to call \f(CWXtQueryGeometry()\fP; it can just make the geometry changes that it plans to make. .LP The cases described in the above two paragraphs are widgets that always respect or never respect their children's preferences. Neither case takes advantage of the full power of this geometry querying scheme. The most common interesting use of \f(CWXtQueryGeometry()\fP, is when a parent wants to constrain the width or height of a child, and would like to know the child's preferred size in the other dimension. A menubar laid out in a Form widget, for example, will probably be laid out across the top and have its width constrained to be equal to the width of the form. If the form becomes too small to display all the items in the menu bar, the menubar might want to wrap onto a second line. In this case, the parent would set the width in \f(CIintended\fP, and use the height returned in \f(CIpreferred_return\fP, regardless of the return value of the function. Note that in this case the parent is ignoring any return values of \f(CWXtGeometryNo\fP\-it must constrain the width of the menubar even if the child would prefer that the width not be constrained. Many widgets are not as sophisticated as this hypothetical menu bar widget, and cannot to adjust their layout when they find that only one dimension is constrained. Even these children will return a preferred size however, and the form can use the preferred height and ignore the preferred width. The Athena Box widget is an example of a widget that modifies its layout when it finds that it is constrained in one dimension. .LP Note that if \f(CWXtQueryGeometry()\fP returns \f(CWXtGeometryYes\fP, the parent can simply proceed with the geometry changes it indicated in \f(CWintended\fP without examining the contents of \f(CWpreferred_return\fP. In practice, however, this return value is uncommon, and it may not be worth writing special case code to handle it. In the examples given above, the parent never even needs to check the return value of the function. .\" .SH "Example" Only three widgets in the Athena widget set call \f(CWXtQueryGeometry()\fP, and none of the Intrinsics widgets call it. The following code is from the Athena Viewport widget. .Ps if (!w->viewport.allowvert) { intended->height = *clip_height; intended->request_mode = CWHeight; } if (!w->viewport.allowhoriz) { intended->width = *clip_width; intended->request_mode = CWWidth; } if ( query ) { if ( (w->viewport.allowvert w->viewport.allowhoriz) ) { XtQueryGeometry( child, intended, &preferred ); if ( !(intended->request_mode & CWWidth) ) if ( preferred.request_mode & CWWidth ) intended->width = preferred.width; else intended->width = child->core.width; if ( !(intended->request_mode & CWHeight) ) if ( preferred.request_mode & CWHeight ) intended->height = preferred.height; else intended->height = child->core.height; } } .Pe .\" .Nd 10 .SH "Background" If \f(CWXtQueryGeometry()\fR is called from within a \f(CWgeometry_manager()\fP procedure for the widget that issued \f(CWXtMakeGeometryRequest()\fR or \f(CWXtMakeResizeRequest()\fR, the results are not guaranteed to be consistent with the requested changes. The change request passed to the geometry manager takes precedence over the preferred geometry. .LP The \f(CWquery_geometry()\fP procedure may assume that no \f(CWXtMakeResizeRequest()\fR or \f(CWXtMakeGeometryRequest()\fR is in progress for the specified widget; that is, it is not required to construct a reply consistent with the requested geometry if such a request were actually outstanding. .LP .\" .SH "Structures" The possible return values of \f(CWXtQueryGeometry()\fP are defined as follows: .XX "XtGeometryResult" .Ps .ta 4.5n 2i typedef enum { XtGeometryYes, /* Request accepted */ XtGeometryNo, /* Request denied */ XtGeometryAlmost,/* Request denied but willing to take reply */ XtGeometryDone /* never returned by XtQueryGeometry() */ } XtGeometryResult; .Pe The \f(CWXtWidgetGeometry\fR structure is similar to but not identical to the corresponding Xlib structure: .XX "XtGeometryMask" .Ps .ta 4.5n 2i typedef unsigned long XtGeometryMask; .sp .5 typedef struct { XtGeometryMask request_mode; Position x, y; Dimension width, height; Dimension border_width; Widget sibling; int stack_mode; } XtWidgetGeometry; .Pe \f(CWXtQueryGeometry()\fP, like the Xlib \f(CWXConfigureWindow()\fR function, uses \f(CWrequest_mode\fR to determine which fields in the \f(CWXtWidgetGeometry\fR structure you that the parent and the child have set. The \f(CWrequest_mode\fR definitions are from <\fIX11/X.h\fP>: .Ps .ta .75i 2i #define CWX (1<<0) #define CWY (1<<1) #define CWWidth (1<<2) #define CWHeight (1<<3) .Nd 4 #define CWBorderWidth (1<<4) #define CWSibling (1<<5) #define CWStackMode (1<<6) .Pe .LP The \f(CWstack_mode\fR definitions are from <\fIX11/X.h\fP>: .Ps .ta .75i 2i #define Above 0 #define Below 1 #define TopIf 2 .Nd 4 #define BottomIf 3 #define Opposite 4 .Pe The Intrinsics also support the following value: .Ps .ta .75i 2i #define XtSMDontChange 5 .Pe For precise definitions of \f(CWAbove\fR, \f(CWBelow\fR, \f(CWTopIf\fR, \f(CWBottomIf\fR, and \f(CWOpposite\fR, see the reference page for \f(CWXConfigureWindow()\fP in \*(V2. \f(CWXtSMDontChange\fR indicates that the widget wants its current stacking order preserved. .SH "See Also" .na \s-1\fIXtMakeGeometryRequest\fR\s+1\*(s1, .br \s-1\fIquery_geometry\fR\s+1\*(s4. .ad .XE "geometry management: querying; XtQueryGeometry" .XE "XtQueryGeometry" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtRealizeProc" "Xt \- Widget Method Prototypes" .SH "Name" .Na XtRealizeProc \- interface definition for the \f(CWrealize()\fP method. .Nz .XX "XtRealizeProc" .SH "Synopsis" .Sy typedef void (*XtRealizeProc)(Widget, XtValueMask, XSetWindowAttributes *); .As Widget \f(CIw\fP; XtValueMask \f(CIvalue_mask\fP; XSetWindowAttributes *\f(CIattributes\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. .IP \f(CIvalue_mask\fP 1i Specifies which fields in the \f(CIattributes\fR structure to use. .IP \f(CIattributes\fP 1i Specifies the window attributes to use in the \f(CWXCreateWindow()\fR call. .\" .SH "Description" \f(CWXtRealizeProc\fP is the type of the Core \f(CWrealize()\fP method. See \f(CWrealize\fP(4) for more information. .\" .SH "See Also" .na \s-1\fIrealize\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtRealizeWidget" "Xt \- Widget Lifecycle" .SH "Name" .Na XtRealizeWidget \- realize a widget instance. .XS "widgets: realizing; XtRealizeWidget" .Nz .XS "XtRealizeWidget" .SH "Synopsis" .Sy void XtRealizeWidget(\f(CIw\fP) .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget to be realized. Must be of class Core or any subclass thereof. .\" .SH "Description" \f(CWXtRealizeWidget()\fR creates windows for the specified widget and all of its descendants. If the specified widget is already realized, \f(CWXtRealizeWidget()\fR simply returns. When a widget is first created, no X window is created along with it. Realizing a widget is the term for creating this window, and no widget can appear on the screen until it is realized. The reason widget creation and window creation are handled separately is one of efficiency: when an interface is first created, there is an initial process of negotiating geometry and assigning a layout to each widget. If the widgets had windows at this point, the geometry negotiation would require many \f(CWXConfigureWindow()\fP calls to the X server, which would significantly slow down application startup time. .LP The "Algorithm" section below describes the procedure followed by \f(CWXtRealizeWidget()\fP. .\" .SH "Usage" Most applications will call \f(CWXtRealizeWidget()\fR once just prior to calling \f(CWXtAppMainLoop()\fR to process events. The argument to \f(CWXtRealizeWidget()\fP is usually the top-level widget returned from \f(CWXtAppInitialize()\fP. If more widgets are subsequently created, they do not need to be realized because when a widget is created as the child of a realized widget, it is automatically realized. Popup shells are also automatically realized, if necessary, when they are popped up. .LP You can test whether a widget is realized with \f(CWXtIsRealized()\fP. Until a widget is realized, certain functions will not operate as expected. \f(CWXtWindow()\fP, for example will not return a valid window if called with an unrealized widget. .LP You can unrealize a widget (destroy its window) but leave the widget structure intact with \f(CWXtUnrealizeWidget()\fP. .\" .SH "Algorithm" If the widget is already realized, \f(CWXtRealizeWidget()\fP simply returns. Otherwise it performs the following: .IP \(bu 3n Binds all action names in the widget's translation table to procedures. .IP \(bu 3n Makes a postorder traversal of the widget tree rooted at the specified widget and calls each non-\f(CWNULL\fP \f(CWchange_managed()\fP method of all composite widgets that have one or more managed children. .IP \(bu 3n Constructs an \f(CWXSetWindowAttributes\fP structure filled in with information derived from the Core widget fields and calls the \f(CWrealize()\fP method for the widget, which adds any widget-specific attributes and creates the X window. .IP \(bu 3n If the widget is not a subclass of compositeWidgetClass, \f(CWXtRealizeWidget()\fP returns; otherwise it continues and performs the following: .RS .IP \- 3 Descends recursively to each of the widget's managed children and calls the \f(CWrealize()\fP methods. Primitive widgets that instantiate children are responsible for realizing those children themselves. .IP \- 3 Maps all of the managed children windows that have \f(CWmapped_when_managed\fP \f(CWTrue\fP. If a widget is managed but \f(CWmapped_when_managed\fP is \f(CWFalse\fP, the widget is allocated visual space but is not displayed. .RE .LP If the widget is a top-level shell widget (that is, it has no parent), and \f(CWmapped_when_managed\fP is \f(CWTrue\fP, \f(CWXtRealizeWidget()\fP maps the widget window. .LP \f(CWXtCreateWidget()\fP, \f(CWXtVaCreateWidget()\fP, \f(CWXtRealizeWidget()\fP, \f(CWXtManageChildren()\fP, \f(CWXtUnmanageChildren()\fP, \f(CWXtUnrealizeWidget()\fP, \f(CWXtSetMappedWhenManaged()\fP, and \f(CWXtDestroyWidget()\fP maintain the following invariants: .IP \(bu 3n If a composite widget is realized, then all its managed children are realized. .IP \(bu 3n If a composite widget is realized, then all its managed children that have \f(CWmapped_when_managed\fP \f(CWTrue\fP are mapped. .LP All Intrinsics functions and all widget routines should accept either realized or unrealized widgets. When calling the \f(CWrealize()\fP or \f(CWchange_managed()\fP methods for children of a composite widget, \f(CWXtRealizeWidget()\fP calls the procedures in reverse order of appearance in the CompositePart \f(CWchildren\fP list. By default, this ordering of the realize procedures will result in the stacking order of any newly created subwindows being top-to-bottom in the order of appearance on the list, and the most recently created child will be at the bottom. .\" .SH "See Also" .na \s-1\fIXtIsRealized\fR\s+1\*(s1, \s-1\fIXtUnrealizeWidget\fR\s+1\*(s1, .br \s-1\fIrealize\fR\s+1\*(s4. .ad .XE "widgets: realizing; XtRealizeWidget" .XE "XtRealizeWidget" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtRealloc" "Xt \- Memory Allocation" .SH "Name" .Na XtRealloc \- change the size of an allocated block of storage. .XX "storage: resizing (XtRealloc)" .Nz .XX "XtRealloc" .SH "Synopsis" .Sy char *XtRealloc(\f(CIptr\fP, \f(CInum\fP); .As char *\f(CIptr\fP; Cardinal \f(CInum\fP; .Ae .SS "Inputs" .IP \f(CIptr\fP 1i Specifies a pointer to memory allocated with \f(CWXtMalloc()\fP, \f(CWXtCalloc()\fP, or \f(CWXtRealloc()\fP, or \f(CWNULL\fP. .IP \f(CInum\fP 1i Specifies the new number of bytes of memory desired in the block. .SS "Returns" A pointer to allocated memory. .\" .SH "Description" \f(CWXtRealloc()\fP changes the size of the block of allocated memory pointed to by \f(CIptr\fP to be at least \f(CInum\fP bytes large. In order to make this size change, it may have to allocate a new block of memory and copy the contents of the old block (or as much as will fit) into the new block. If it allocates a new block of memory, it frees the old block. In either case, it returns a pointer to a block of memory which is of the requested size. If there is insufficient memory to allocate the new block, \f(CWXtRealloc()\fR terminates by calling \f(CWXtErrorMsg()\fR. .LP If \f(CIptr\fR is \f(CWNULL\fR, \f(CWXtRealloc()\fR simply calls \f(CWXtMalloc()\fR to allocate a block of memory of the requested size. .\" .SH "Usage" Note that \f(CWXtRealloc()\fP may move the contents of your allocated memory to a new location; the return value may or may not be the same as \f(CIptr\fP. Not all memory can be safely reallocated. If there are multiple pointers to a block of memory scattered through out an application (such as pointers to a widget record), then reallocating that memory is not safe, because all pointers to it cannot be updated. Other memory (such as the array of children maintained privately by the Composite widget class) can be safely updated because there should be only one pointer to it in the application (in this case the pointer is the \f(CWcomposite.children\fP field of the widget). These cautions are no different than those required with the standard \f(CWrealloc()\fP function. .LP In most cases, you will have to cast the return value of \f(CWXtRealloc()\fP to an appropriate pointer type. .LP Note that because \f(CWXtRealloc()\fP behaves like \f(CWXtMalloc()\fP when passed a \f(CWNULL\fP pointer, (something that \f(CWrealloc()\fP does not do), you don't have to write special case code to allocate the first chunk of memory with \f(CWXtMalloc()\fP and subsequent chunks with \f(CWXtRealloc()\fP; you can simply use \f(CWXtRealloc()\fP everywhere. .LP .Nd 10 Memory allocated with \f(CWXtRealloc()\fP must be deallocated with \f(CWXtFree()\fP. The function \f(CWXtRealloc()\fR is implemented by the Toolkit independently of the particular environment, so programs ported to a system not supporting \f(CWmalloc\fR will still work. .SH "See Also" .na \s-1\fIXtCalloc\fR\s+1\*(s1, \s-1\fIXtFree\fR\s+1\*(s1, \s-1\fIXtMalloc\fR\s+1\*(s1, \s-1\fIXtNew\fR\s+1\*(s1, \s-1\fIXtNewString\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtRegisterCaseConverter" "Xt \- Keyboard Handling" .SH "Name" .Na XtRegisterCaseConverter \- register a case converter. .XX "converters: registering; case converter" .XX "case converter, XtRegisterCaseConverter" .XX "XtRegisterCaseConverter" .XX "registering, converters" .Nz .SH "Synopsis" .Sy void XtRegisterCaseConverter(\f(CIdisplay\fP, \f(CIproc\fP, \f(CIstart\fP, \f(CIstop\fP) .As Display *\f(CIdisplay\fP; XtCaseProc \f(CIproc\fP; KeySym \f(CIstart\fP; KeySym \f(CIstop\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the display from which the key events are to come. .IP \f(CIproc\fP 1i Specifies the \f(CWXtCaseProc\fR that is to do the conversions. .IP \f(CIstart\fP 1i Specifies the first keysym for which this converter is valid. .IP \f(CIstop\fP 1i Specifies the last keysym for which this converter is valid. .SH "Description" \f(CWXtRegisterCaseConverter()\fR registers \f(CIproc\fP with the Intrinsics as a procedure to be called in order to determine the correct uppercase and lowercase versions of any keysyms between \f(CIstart\fP and \f(CIstop\fP inclusive. The registered converter overrides any previous converters registered in that range. .LP See \f(CWXtCaseProc\fP(2) for a description of how to write a case converter procedure. .\" .SH "Usage" The Translation Manager uses case converters as part of its keycode-to-keysym translation process. The default converter understands case conversion for all keysyms defined in the X11 protocol. You will probably never need to register a case converter unless you are working with non-standard keysyms. .LP The only way to remove a converter is to register a new one, perhaps an "identity" converter which performs no conversion at all. .LP The registered case converters are invoked by the translation manager, and can also be explicitly called with the function \f(CWXtConvertCase()\fP. .\" .SH "Structures" .Ps typedef XID KeySym; .Pe .SH "See Also" .na \s-1\fIXtConvertCase\fR\s+1\*(s1, \s-1\fIXtGetKeysymTable\fR\s+1\*(s1, \s-1\fIXtKeysymToKeycodeList\fR\s+1\*(s1, \s-1\fIXtSetKeyTranslator\fR\s+1\*(s1, \s-1\fIXtTranslateKeycode\fR\s+1\*(s1, .br \s-1\fIXtCaseProc\fR\s+1\*(s2, \s-1\fIXtKeyProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtRegisterGrabAction" "Xt \- Translations and Actions" .SH "Name" .XS "XtRegisterGrabAction" .Na XtRegisterGrabAction \- register an action procedure as one that needs a passive grab to function properly. .Nz .SH "Synopsis" .Sy void XtRegisterGrabAction(\f(CIaction_proc\fP, \f(CIowner_events\fP, \f(CIevent_mask\fP, \f(CIpointer_mode\fP, \f(CIkeyboard_mode\fP) .As XtActionProc \f(CIaction_proc\fP; Boolean \f(CIowner_events\fP; unsigned int \f(CIevent_mask\fP; int \f(CIpointer_mode\fP, \f(CIkeyboard_mode\fP; .Ae .SS "Inputs" .IP \f(CIaction_proc\fP 1i Specifies the action procedure that requires a passive grab. .IP \f(CIowner_events\fP 1i Specifies whether pointer events generated during the grab are reported normally within the application (\f(CWTrue\fP) or only to the widget that invokes the action (\f(CWFalse\fP). .IP \f(CIevent_mask\fP 1i Specifies the event mask to take effect during the grab. .IP \f(CIpointer_mode\fP 1i Controls processing of pointer events during the grab. Either \f(CWGrabModeSync\fR or \f(CWGrabModeAsync\fR. .IP \f(CIkeyboard_mode\fP 1i Controls processing of keyboard events during the grab. Either \f(CWGrabModeSync\fP or \f(CWGrabModeAsync\fP. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtRegisterGrabAction()\fP registers \f(CIaction_proc\fP as an action procedure that needs to have a passive grab in order for it to work properly. When this action appears in a translation table, the Intrinsics will automatically perform the appropriate passive key or button grab, depending on the event sequence that invokes the action. The \f(CIowner_events\fP, \f(CIevent_mask\fP, \f(CIpointer_mode\fP, and \f(CIkeyboard_mode\fP arguments are passed to \f(CWXtGrabKey()\fP or \f(CWXtGrabButton()\fP when the passive grab is made. .LP See the "Background" section below for full details. See \f(CWXtGrabKey()\fP and \f(CWXtGrabButton()\fP for more information about passive grabs. .\" .SH "Usage" When you passively grab a button/modifiers or key/modifiers combination, all events that occur when that button or key and those modifiers are down will be delivered to the widget you specify or to your application, regardless of the location of the pointer. .LP Very few action procedures need a grab to function properly. Note that a button grab is always automatically invoked between a button down and the corresponding button up event, so that a text widget, for example, that wanted to scroll its text when the user dragged the mouse out of the window could do so without registering the action procedure with this function. .LP Grabs are required by some kinds of popup menus, and \f(CWXtRegisterGrabAction()\fP is used by the predefined action \f(CWXtMenuPopup\fP. .\" .SH "Background" \f(CWXtRegisterGrabAction()\fR adds the specified \f(CIaction_proc\fR to a list known to the translation manager. When a widget is realized, or when the translations of a realized widget or the accelerators installed on a realized widget are modified, its translation table and any installed accelerators are scanned for action procs on this list. .LP If any are invoked on \f(CWButtonPress\fR or \f(CWKeyPress\fR events as the only or final event in a sequence, the Intrinsics will call \f(CWXtGrabButton()\fR or \f(CWXtGrabKey()\fR for the widget with every button or keycode that maps to the event detail field, passing the specified \f(CIowner_events\fR, \f(CIevent_mask\fR, \f(CIpointer_mode\fR, and \f(CIkeyboard_mode\fR. .IP \(bu 3n For \f(CWButtonPress\fR events, the modifiers specified in the grab are determined directly from the translation specification, and \f(CIconfine_to\fR and \f(CIcursor\fP are specified as \f(CWNone\fR. .Nd 10 .IP \(bu 3n For \f(CWKeyPress\fR events: .RS .IP + If the translation table entry specifies colon (:) in the modifier list, the modifiers are determined by calling the key translator procedure registered for the display and by calling \f(CWXtGrabKey()\fR for every combination of standard modifiers that map the keycode to the specified event detail keysym, and ORing any modifiers specified in the translation table entry, and \f(CIevent_mask\fR is ignored. .IP + If the translation table entry does not specify colon in the modifier list, the modifiers specified in the grab are those specified in the translation table entry only. .in 0 .RE .LP For both \f(CWButtonPress\fR and \f(CWKeyPress\fR events, "don't care modifiers" are ignored unless the translation entry explicitly specifies "Any" in the modifiers field. .LP If the specified \f(CIaction_proc\fR is already registered for the calling process, the new values replace the previously specified values for any widgets that are realized following the call, but existing grabs are not altered on currently-realized widgets. .LP When translations or installed accelerators are modified for a realized widget, any previous key or button grabs that were registered as a result of the old bindings are released, provided that the old bindings do not appear in the new bindings and are not explicitly grabbed by the client with \f(CWXtGrabKey()\fR or \f(CWXtGrabButton()\fR. .SH "See Also" .na \s-1\fIXtAddActions\fR\s+1\*(s1, \s-1\fIXtAppAddActionHook\fR\s+1\*(s1, \s-1\fIXtAppAddActions\fR\s+1\*(s1, \s-1\fIXtCallActionProc\fR\s+1\*(s1, \s-1\fIXtGetActionKeysym\fR\s+1\*(s1, \s-1\fIXtRemoveActionHook\fR\s+1\*(s1. .ad .\"last line comment .XE "XtRegisterGrabAction" .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtReleaseGC" "Xt \- Memory Allocation" .SH "Name" .Na XtReleaseGC \- deallocate a shared GC when it is no longer needed. .XN "GCs (see graphics contexts) .XX "graphics contexts, deallocating" .XN "graphics contexts: (see also XtReleaseGC)" .Nz .XX "XtReleaseGC" .SH "Synopsis" .Sy void XtReleaseGC(\f(CIobject\fP, \f(CIgc\fP) .As Widget \f(CIobject\fP; GC \f(CIgc\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies any object on the display for which the GC was created; may be of class Object or any subclass thereof. .IP \f(CIgc\fP 1i Specifies the GC to be deallocated. .SH "Description" \f(CWXtReleaseGC()\fP deallocates a shared GC allocated with \f(CWXtGetGC()\fR or \f(CWXtAllocateGC()\fP. The Intrinsics maintain a reference count on all shared GCs and call \f(CWXFreeGC()\fP when the last user of a GC releases it. .SH "See Also" .na \s-1\fIXtAllocateGC\fR\s+1\*(s1, \s-1\fIXtGetGC\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtRemoveActionHook" "Xt \- Translations and Actions" .SH "Name" .XX "XtRemoveActionHook" .Na XtRemoveActionHook \- unregister an action hook procedure. .Nz .SH "Synopsis" .Sy void XtRemoveActionHook(\f(CIid\fP) .As XtActionHookId \f(CIid\fP; .Ae .SS "Inputs" .IP \f(CIid\fP 1i Identifies the action hook to be removed. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtRemoveActionHook()\fR removes the specified action hook procedure from the list in which it was registered. The \f(CIid\fP argument is the value returned by \f(CWXtAppAddActionHook()\fP when the action hook procedure was registered. .\" .SH "Structures" \f(CWXtActionHookId\fP is an opaque type. .\" .SH "See Also" .na \s-1\fIXtAppAddActionHook\fR\s+1\*(s1, .br \s-1\fIXtActionHookProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtRemoveAllCallbacks" "Xt \- Callbacks" .SH "Name" .XS "removing, callbacks" .XX "XtRemoveAllCallbacks" .Na XtRemoveAllCallbacks \- delete all procedures from a callback list. .Nz .SH "Synopsis" .Sy void XtRemoveAllCallbacks(\f(CIobject\fP, \f(CIcallback_name\fP) .As Widget \f(CIobject\fP; String \f(CIcallback_name\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1.2i Specifies the object whose callbacks are to be deleted; may be of class Object or any subclass thereof. .IP \f(CIcallback_name\fP Specifies the name of the callback list from which procedures are to be removed. .SH "Description" \f(CWXtRemoveAllCallbacks()\fR removes all callback procedures registered on the callback list named by \f(CIcallback_name\fP in the object \f(CIobject\fP. It also frees all memory allocated by the Intrinsics for that callback list. .\" .SH "Usage" This is a dangerous function to call, because callbacks that you are unaware of may have been registered on any list of your object. Simply creating a widget may cause special resource converter destructor procedures to be registered on the widget's destroy callback, for example. If you use a convenience routine that creates both a dialog shell and the dialog child widget, as a further example, that convenience routine may register a destroy callback on the child so that the shell will be automatically destroyed if the child is destroyed. .LP In general, you should use \f(CWXtRemoveCallback()\fP to remove specified procedure/data pairs that you have registered on a list. You can also use \f(CWXtRemoveCallbacks()\fP to remove an array of procedure/data pairs. .\" .SH "See Also" .na \s-1\fIXtAddCallback\fR\s+1\*(s1, \s-1\fIXtAddCallbacks\fR\s+1\*(s1, \s-1\fIXtCallCallbacks\fR\s+1\*(s1, \s-1\fIXtRemoveCallback\fR\s+1\*(s1, \s-1\fIXtRemoveCallbacks\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtRemoveCallback" "Xt \- Callbacks" .SH "Name" .Na XtRemoveCallback \- remove a callback from a callback list. .XX "callbacks: callback list; deleting method" .XN "widgets: callback list (see callbacks)" .XX "callbacks: callback list; XtRemoveCallback" .XX "XtRemoveCallback" .Nz .SH "Synopsis" .Sy void XtRemoveCallback(\f(CIobject\fP, \f(CIcallback_name\fP, \f(CIcallback\fP, \f(CIclient_data\fP) .As Widget \f(CIobject\fP; String \f(CIcallback_name\fP; XtCallbackProc \f(CIcallback\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object; may be of class Object or any subclass thereof. .IP \f(CIcallback_name\fP 1i Specifies the name of the callback list from which the callback is to be removed. .IP \f(CIcallback\fP 1i Specifies the callback procedure which is to be removed. .IP \f(CIclient_data\fP 1i Specifies the data which was registered with the specified procedure. .\" .SH "Description" \f(CWXtRemoveCallback()\fR removes the \f(CIcallback\fP/\f(CIclient_data\fP pair from the callback list named by \f(CIcallback_name\fP of the object \f(CIobject\fP. If there is no entry in the specified callback list that matches both \f(CIcallback\fP and \f(CIclient_data\fP, \f(CWXtRemoveCallback()\fP returns without generating a warning message. .\" .SH "Usage" Note that there is no way to remove all calls to a specified procedure from a callback list. To remove a procedure from a callback list, you must specify the \f(CIclient_data\fP it was registered with. .LP If you want to remove several procedure/data pairs from a callback list at the same time, use \f(CWXtRemoveCallbacks()\fP. .\" .SH "See Also" .na \s-1\fIXtAddCallback\fR\s+1\*(s1, \s-1\fIXtAddCallbacks\fR\s+1\*(s1, \s-1\fIXtCallCallbacks\fR\s+1\*(s1, \s-1\fIXtRemoveAllCallbacks\fR\s+1\*(s1, \s-1\fIXtRemoveCallbacks\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtRemoveCallbacks" "Xt \- Callbacks" .SH "Name" .Na XtRemoveCallbacks \- remove a list of callbacks from a callback list. .XX "callbacks: callback list; deleting method" .XN "widgets: callback list (see callbacks)" .XX "callbacks: callback list; XtRemoveCallbacks" .XX "XtRemoveCallbacks" .Nz .SH "Synopsis" .Sy void XtRemoveCallbacks(\f(CIobject\fP, \f(CIcallback_name\fP, \f(CIcallbacks\fP) .fi .As Widget \f(CIobject\fP; String \f(CIcallback_name\fP; XtCallbackList \f(CIcallbacks\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object; may be of class Object or any subclass thereof. .IP \f(CIcallback_name\fP 1i Specifies the callback list from which the callbacks are to be removed. .IP \f(CIcallbacks\fP 1i Specifies a \f(CWNULL\fP-terminated array of procedure/data pairs to be removed from the callback list. .\" .SH "Description" \f(CWXtRemoveCallbacks()\fR removes each of the procedure/data pairs in \f(CIcallbacks\fP from the callback list named by \f(CIcallback_name\fP of object \f(CIobject\fP. .LP Each callback is removed only if it exactly matches a procedure/data pair registered on the callback list. If a procedure/data pair in the \f(CIcallbacks\fP array does not match a pair on the callback list, \f(CWXtRemoveCallbacks()\fP does nothing with that array element and does not generate a warning message. .LP Because there is not an argument that specifies the number of elements in the \f(CIcallbacks\fP array, the last element of this array should be a \f(CWXtCallbackRec\fP structure with \f(CWNULL\fP in both fields. .\" .SH "Usage" Because \f(CWXtRemoveCallbacks()\fP requires the caller to allocate and initialize an array of procedure/data pairs, it may often be easier to simply call \f(CWXtRemoveCallback()\fP repeatedly. The exception is when a statically initialized array is used to both add and remove callbacks. .\" .SH "Structures" .Ps typedef struct _XtCallbackRec { XtCallbackProc callback; XtPointer closure; } XtCallbackRec, *XtCallbackList; .Pe .SH "See Also" .na \s-1\fIXtAddCallback\fR\s+1\*(s1, \s-1\fIXtAddCallbacks\fR\s+1\*(s1, \s-1\fIXtCallCallbacks\fR\s+1\*(s1, \s-1\fIXtRemoveAllCallbacks\fR\s+1\*(s1, \s-1\fIXtRemoveCallback\fR\s+1\*(s1. .ad .XE "removing, callbacks" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtRemoveCal 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtRemoveCallback@XtRemoveCaA .sp .5 XtRemoveCallbacks@XtRemoveCaB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtRemoveEventHandler" "Xt \- Event Handling" .SH "Name" .Na XtRemoveEventHandler \- remove an event handler, or change the conditions under which it is called. .XS "event handlers: removing" .XS "event handlers, XtRemoveEventHandler" .Nz .XS "XtRemoveEventHandler" .SH "Synopsis" .Sy void XtRemoveEventHandler(\f(CIw\fP, \f(CIevent_mask\fP, \f(CInonmaskable\fP, \f(CIproc\fP, \f(CIclient_data\fP) .As Widget \f(CIw\fP; EventMask \f(CIevent_mask\fP; Boolean \f(CInonmaskable\fP; XtEventHandler \f(CIproc\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget for which this handler is registered. Must be of class Core or any subclass thereof. .IP \f(CIevent_mask\fP 1i Specifies the events for which to unregister this handler. .IP \f(CInonmaskable\fP 1i Specifies whether this handler should be unregistered for nonmaskable events. .IP \f(CIproc\fP 1i Specifies the handler procedure. .IP \f(CIclient_data\fP 1i Specifies the client data with which the procedure was registered. .\" .SH "Description" \f(CWXtRemoveEventHandler()\fR stops the \f(CIproc\fP/\f(CIclient_data\fP event handler pair registered with \f(CWXtAddEventHandler()\fP or \f(CWXtInsertEventHandler()\fP from being called from widget \f(CIw\fP in response to the events specified in \f(CIevent_mask\fP. In addition, if \f(CInonmaskable\fP is \f(CWTrue\fP, then the handler will no longer be called in response to the nonmaskable events: \f(CWGraphicsExpose\fP, \f(CWNoExpose\fR, \f(CWSelectionClear\fR, \f(CWSelectionRequest\fR, \f(CWSelectionNotify\fR, \f(CWClientMessage\fR, and \f(CWMappingNotify\fR. .LP A handler is removed only if both the procedure \f(CIproc\fR and \f(CIclient_data\fR match a previously registered handler/data pair. If a handler to be removed fails to match a procedure, or if it has been registered with a different value of \f(CIclient_data\fR, \f(CWXtRemoveEventHandler()\fR returns without reporting an error. .LP \f(CWXtRemoveEventHandler()\fP accepts the special value \f(CWXtAllEvents\fP in the \f(CIevent_handler\fP argument as a signal that the event handler should no longer be called in response to any maskable events. This value should not be combined with other event mask bits, and should not be used to select events in other functions. .LP If the widget is realized, and no other handler requires events of any of the specified types, \f(CWXtRemoveEventHandler()\fR calls \f(CWXSelectInput()\fR, as necessary to prevent the widget from receiving further events of those types. .\" .SH "Usage" Note that \f(CWXtRemoveEventHandler()\fP does not necessarily \fIremove\fP an event handler; rather, it modifies the conditions for which it is called. To prevent an event handler from being called at all, call .ne 2 \f(CWXtRemoveEventHandler()\fR with an \f(CIevent_mask\fR of \f(CWXtAllEvents\fR and with \f(CInonmaskable\fP\ \f(CWTrue\fP. .LP To remove or change the event mask for a "raw" event handler registered with \f(CWXtAddRawEventHandler()\fP or \f(CWXtInsertRawEventHandler()\fP, use \f(CWXtRemoveRawEventHandler()\fP. .\" .SH "Structures" Each of the event types listed in the table below set a single bit in an event mask. The \f(CIevent_mask\fP argument is formed by combining these symbols with the bitwise OR operator (\^\fB \fR\^). Note that the nonmaskable event types do not appear in this table and cannot be requested in an event mask. .sp 1 .in 0 .KS .TS linesize(2),tab(@); lfCWp7 lfCWp7 lfCWp7. .sp 2p NoEventMask@Button1MotionMask@StructureNotifyMask@ KeyPressMask@Button2MotionMask@ResizeRedirectMask@ KeyReleaseMask@Button3MotionMask@SubstructureNotifyMask@ ButtonPressMask@Button4MotionMask@SubstructureRedirectMask@ ButtonReleaseMask@Button5MotionMask@FocusChangeMask@ EnterWindowMask@ButtonMotionMask@PropertyChangeMask@ LeaveWindowMask@KeymapStateMask@ColormapChangeMask@ PointerMotionMask@ExposureMask@OwnerGrabButtonMask@ PointerMotionHintMask@VisibilityChangeMask@ .sp 5p .TE .KE .in .sp 1 See \*(z3, for more information on event types and masks. .LP In addition to these standard X event masks, the Intrinsics define a special value for use by this function: .Ps /* XtAllEvents is valid only for XtRemoveEventHandler and * XtRemoveRawEventHandler; don't use it to select events! */ #define XtAllEvents ((EventMask) -1L) .Pe .\" .SH "See Also" .na \s-1\fIXtAddEventHandler\fR\s+1\*(s1, \s-1\fIXtInsertEventHandler\fR\s+1\*(s1, \s-1\fIXtRemoveRawEventHandler\fR\s+1\*(s1, .br \s-1\fIXtEventHandler\fR\s+1\*(s2. .ad .XE "event handlers: removing" .XE "event handlers, XtRemoveEventHandler" .XE "XtRemoveEventHandler" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtRemoveGrab" "Xt \- Pop Ups" .SH "Name" .Na XtRemoveGrab \- redirect user input from modal widget back to normal destination. .XX "widgets: modal widget; XtRemoveGrab" .XX "grabs, XtRemoveGrab" .XX "removing, grabs" .XX "XtRemoveGrab" .Nz .SH "Synopsis" .Sy void XtRemoveGrab(\f(CIw\fP) .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget to remove from the modal cascade. .SH "Description" \f(CWXtRemoveGrab()\fR removes the specified widget from the modal cascade, along with any widgets which were more recently added to the cascade. It issues a warning if the specified widget is not in the modal cascade. .LP See \f(CWXtAddGrab()\fP for more information about the modal cascade, and how events are dispatched to it. .\" .SH "Usage" The modal cascade is the set of modal widgets currently popped up. If there is a modal cascade, \f(CWXtDispatchEvent()\fP does not deliver events to the rest of the application; instead it ignores those events or delivers them to a widget in the modal cascade. .LP To add a widget to the modal cascade, use \f(CWXtAddGrab()\fP. Note that this function does not actually issue a grab; it simulates one by changing the way events are dispatched. .LP Most applications will never need to call \f(CWXtAddGrab()\fP or \f(CWXtRemoveGrab()\fP. The functions \f(CWXtPopup()\fP, \f(CWXtPopupSpringLoaded()\fP, and \f(CWXtPopdown()\fP do so automatically. .\" .SH "See Also" .na \s-1\fIXtAddGrab\fR\s+1\*(s1, \s-1\fIXtDispatchEvent\fR\s+1\*(s1, \s-1\fIXtPopdown\fR\s+1\*(s1, \s-1\fIXtPopup\fR\s+1\*(s1, \s-1\fIXtPopupSpringLoaded\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtRemoveInput" "Xt \- Event Handling" .SH "Name" .Na XtRemoveInput \- unregister an alternate input source callback. .XX "events, cancelling source" .XX "events: input events; XtRemoveInput" .XX "removing, input" .Nz .XX "XtRemoveInput" .SH "Synopsis" .Sy void XtRemoveInput(\f(CIid\fP) .As XtInputId \f(CIid\fP; .Ae .SS "Inputs" .IP \f(CIid\fP 1i Identifies the input source and callback procedure. .\" .SH "Description" \f(CWXtRemoveInput()\fR causes the Intrinsics to stop calling a callback procedure registered with \f(CWXtAppAddInput()\fP. The \f(CIid\fP argument is a handle returned by the call to \f(CWXtAppAddInput()\fP which registered the input callback. If there are not any other callbacks registered for the same input source, the Intrinsics stop monitoring that source. .SH "Usage" Alternate input events (on POSIX systems) usually signal that there is data available to be read on a file descriptor, which is often a pipe or socket. See \f(CWXtAppAddInput()\fP for more information. .\" .SH "Structures" The \f(CWXtInputId\fP type is defined as follows: .Ps typedef unsigned long XtInputId; .Pe .\" .SH "See Also" .na \s-1\fIXtAppAddInput\fR\s+1\*(s1, .br \s-1\fIXtInputCallbackProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtRemoveRawEventHandler" "Xt \- Event Handling" .SH "Name" .Na XtRemoveRawEventHandler \- remove a raw event handler, or change the conditions under which it is called. .XS "event handlers: raw; removing" .XS "event handlers, XtRemoveRawEventHandler" .XS "removing, raw event handlers" .Nz .XS "XtRemoveRawEventHandler" .SH "Synopsis" .Sy void XtRemoveRawEventHandler(\f(CIw\fP, \f(CIevent_mask\fP, \f(CInonmaskable\fP, \f(CIproc\fP, \f(CIclient_data\fP) .As Widget \f(CIw\fP; EventMask \f(CIevent_mask\fP; Boolean \f(CInonmaskable\fP; XtEventHandler \f(CIproc\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget for which this handler is registered. Must be of class Core or any subclass thereof. .IP \f(CIevent_mask\fP 1i Specifies the events for which to unregister this handler. .IP \f(CInonmaskable\fP 1i Specifies whether this handler should be unregistered for nonmaskable events. .IP \f(CIproc\fP 1i Specifies the handler procedure. .IP \f(CIclient_data\fP 1i Specifies the client data with which the procedure was registered. .\" .SH "Description" \f(CWXtRemoveRawEventHandler()\fR stops the \f(CIproc\fP/\f(CIclient_data\fP event handler pair registered with \f(CWXtAddRawEventHandler()\fP or \f(CWXtInsertRawEventHandler()\fP from being called from widget \f(CIw\fP in response to the events specified in \f(CIevent_mask\fP. In addition, if \f(CInonmaskable\fP is \f(CWTrue\fP, then the handler will no longer be called in response to the nonmaskable events: \f(CWGraphicsExpose\fP, \f(CWNoExpose\fR, \f(CWSelectionClear\fR, \f(CWSelectionRequest\fR, \f(CWSelectionNotify\fR, \f(CWClientMessage\fR, and \f(CWMappingNotify\fR. .LP A handler is removed only if both the procedure \f(CIproc\fR and \f(CIclient_data\fR match a previously registered handler/data pair. If a handler to be removed fails to match a procedure, or if it has been registered with a different value of \f(CIclient_data\fR, \f(CWXtRemoveRawEventHandler()\fR returns without reporting an error. .LP \f(CWXtRemoveRawEventHandler()\fP accepts the special value \f(CWXtAllEvents\fP in the \f(CIevent_handler\fP argument as a signal that the event handler should no longer be called in response to any maskable events. This value should not be combined with other event mask bits, and should not be used to select events in other functions. .LP Because the procedure is a raw event handler, this function does not affect the widget's event mask and never calls \f(CWXSelectInput()\fR. .\" .SH "Usage" Note that \f(CWXtRemoveRawEventHandler()\fP does not necessarily \fIremove\fP an event handler; rather, it modifies the conditions for which it is called. To prevent an event handler from being called at all, call \f(CWXtRemoveRawEventHandler()\fR with an \f(CIevent_mask\fR of \f(CWXtAllEvents\fR and with \f(CInonmaskable\fP\ \f(CWTrue\fP. .LP To remove or change the event mask for a event handler registered with \f(CWXtAddEventHandler()\fP or \f(CWXtInsertEventHandler()\fP, use \f(CWXtRemoveEventHandler()\fP. .\" .SH "Structures" Each of the event types listed in the table below set a single bit in an event mask. The \f(CIevent_mask\fP argument is formed by combining these symbols with the bitwise OR operator (\^\fB \fR\^). Note that the nonmaskable event types do not appear in this table and cannot be requested in an event mask. .sp 1 .in 0 .KS .TS linesize(2),tab(@); lp7fCW lp7fCW lp7fCW. .sp 2p NoEventMask@Button1MotionMask@StructureNotifyMask@ KeyPressMask@Button2MotionMask@ResizeRedirectMask@ KeyReleaseMask@Button3MotionMask@SubstructureNotifyMask@ ButtonPressMask@Button4MotionMask@SubstructureRedirectMask@ ButtonReleaseMask@Button5MotionMask@FocusChangeMask@ EnterWindowMask@ButtonMotionMask@PropertyChangeMask@ LeaveWindowMask@KeymapStateMask@ColormapChangeMask@ PointerMotionMask@ExposureMask@OwnerGrabButtonMask@ PointerMotionHintMask@VisibilityChangeMask@ .sp 5p .TE .KE .in .sp 1 See \*(z3, for more information on event types and masks. .LP In addition to these standard X event masks, the Intrinsics define a special value for use by this function: .Ps /* XtAllEvents is valid only for XtRemoveEventHandler and * XtRemoveRawEventHandler; don't use it to select events! */ #define XtAllEvents ((EventMask) -1L) .Pe .\" .SH "See Also" \s-1\fIXtAddRawEventHandler\fR\s+1\*(s1, \s-1\fIXtInsertRawEventHandler\fR\s+1\*(s1, \s-1\fIXtRemoveEventHandler\fR\s+1\*(s1, .br \s-1\fIXtEventHandler\fR\s+1\*(s2. .ad .XE "event handlers: raw; removing" .XE "event handlers, XtRemoveRawEventHandler" .XE "XtRemoveRawEventHandler" .XE "removing, raw event handlers" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .RH "XtRemoveTimeOut" "Xt \- Event Handling" .SH "Name" .Na XtRemoveTimeOut \- unregister a timeout procedure. .XX "timeouts, XtRemoveTimeOut" .Nz .XX "XtRemoveTimeOut" .XX "removing, timeouts" .SH "Synopsis" .Sy void XtRemoveTimeOut(\f(CIid\fP) .As XtIntervalId \f(CIid\fP; .Ae .SS "Inputs" .IP \f(CIid\fP 1i Identifies the timeout interval and the timeout callback to be removed. .\" .SH "Description" \f(CWXtRemoveTimeOut()\fR unregisters the timeout callback identified by \f(CIid\fP. \f(CIid\fR is the handle returned by the call to \f(CWXtAppAddTimeOut()\fR that registered the timeout interval and the procedure. .\" .SH "Usage" Note that timeouts are automatically removed once they expire and the callback has been called; therefore, you often do not need to call \f(CWXtRemoveTimeOut()\fP. On the other hand, if you need user input within a specified amount of time, for example, then you should register a timeout callback, and if the input arrives before the timeout callback is called, then you should remove the timeout callback so that it isn't called when the application is not expecting it. .\" .SH "Structures" The \f(CWXtIntervalId\fP structure is defined as follows: .Ps typedef unsigned long XtIntervalId; .Pe .\" .SH "See Also" .na \s-1\fIXtAppAddTimeOut\fR\s+1\*(s1, .br \s-1\fIXtTimerCallbackProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtRemoveWorkProc" "Xt \- Event Handling" .SH "Name" .Na XtRemoveWorkProc \- unregister a work procedure. .XX "work procedures, XtRemoveWorkProc" .XX "work procedures, removing" .Nz .XX "XtRemoveWorkProc" .SH "Synopsis" .Sy void XtRemoveWorkProc(\f(CIid\fP) .As XtWorkProcId \f(CIid\fP; .Ae .SS "Inputs" .IP \f(CIid\fP 1i Identifies the work procedure to unregister. .SH "Description" \f(CWXtRemoveWorkProc()\fR explicitly removes the specified background work procedure. The \f(CIid\fP argument is the handle returned by \f(CWXtAppAddWorkProc()\fP when the procedure was registered. .SH "Usage" Note that a work procedure is removed automatically if it returns \f(CWTrue\fR. In many cases, therefore, you do not have to call \f(CWXtRemoveWorkProc()\fP. .\" .SH "Structures" The \f(CWXtWorkProcId\fP type is defined as follows: .Ps typedef unsigned long XtWorkProcId; .Pe .\" .SH "See Also" .na \s-1\fIXtAppAddWorkProc\fR\s+1\*(s1, .br \s-1\fIXtWorkProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtResizeWidget" "Xt \- Geometry Management" .SH "Name" .Na XtResizeWidget \- resize a child widget. .XX "widgets: resizing; XtResizeWidget" .Nz .XX "XtResizeWidget" .SH "Synopsis" .Sy void XtResizeWidget(\f(CIw\fP, \f(CIwidth\fP, \f(CIheight\fP, \f(CIborder_width\fP) .As Widget \f(CIw\fP; Dimension \f(CIwidth\fP; Dimension \f(CIheight\fP; Dimension \f(CIborder_width\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget to be resized. Must be of class RectObj or any subclass thereof. .IP "\f(CIwidth\fP, \f(CIheight\fP, \f(CIborder_width\fP" 1i Specify the new widget size and border width. .\" .SH "Description" \f(CWXtResizeWidget()\fR changes the width, height, and border width of \f(CIw\fP as specified. It stores the new values into the widget record, and if the widget is realized, calls \f(CWXConfigureWindow()\fP to change the size of the widget's window. Whether or not the widget is realized, \f(CWXtResizeWidget()\fP calls the widget's \f(CWresize()\fP method to notify it of the size changes. .LP If the specified size is equal to the current size, \f(CWXtResizeWidget()\fP returns immediately without calling \f(CWXConfigureWindow()\fP or the \f(CWresize()\fP method. .LP See \f(CWresize()\fP(4) for information about the responsibilities of the \f(CWresize()\fP method. .\" .SH "Usage" \f(CWXtResizeWidget()\fP should only be used by a parent widget to change the size of its children. If an application wishes to change the size of a widget, it should set the \f(CWXtNwidth\fP and \f(CWXtNheight\fP (and possibly the \f(CWXtNborderWidth\fP) resources of the widget. If a widget would like to resize itself, it must \fIrequest\fP a new size with \f(CWXtMakeGeometryRequest()\fP or \f(CWXtMakeResizeRequest()\fP. .LP To move a child widget, use \f(CWXtMoveWidget()\fP. To move and resize a widget in the same call, use \f(CWXtConfigureWidget()\fP. .\" .SH "See Also" .na \s-1\fIXtConfigureWidget\fR\s+1\*(s1, \s-1\fIXtMakeGeometryRequest\fR\s+1\*(s1, \s-1\fIXtMakeResizeRequest\fR\s+1\*(s1, \s-1\fIXtMoveWidget\fR\s+1\*(s1, \s-1\fIXtResizeWindow\fR\s+1\*(s1, .br \s-1\fIresize\fR\s+1\*(s4. \.ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtResizeWindow" "Xt \- Window Manipulation" .SH "Name" .Na XtResizeWindow \- resize a widget's window. .XX "widgets: resizing; XtResizeWindow" .XX "widgets: resizing; per core dimensions" .Nz .XX "XtResizeWindow" .SH "Synopsis" .Sy void XtResizeWindow(\f(CIw\fP) .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. Must be of class Core or any subclass thereof. .SH "Description" \f(CWXtResizeWindow()\fR calls the Xlib function \f(CWXConfigureWindow()\fR to make the window of the specified widget match its Core \f(CWwidth\fR, \f(CWheight\fR, and \f(CWborder_width\fR fields. \f(CWXtResizeWindow()\fP does not call the widget's \f(CWresize()\fP method. .LP The call to \f(CWXConfigureWindow()\fR is done unconditionally because there is no way to tell (without a server query) whether the widget's window already has the specified size. .\" .SH "Usage" You should rarely need to call \f(CWXtResizeWindow()\fP, and should only call it from widget code. Usually, a widget will call \f(CWXtResizeWidget()\fP to set size values in the widget's fields and call \f(CWXConfigureWindow()\fP. .LP You only need to use \f(CWXtResizeWindow()\fP when a widget's core size fields have gotten out of sync with the window's actual size (this will not happen if you follow standard geometry management procedures) and want to force the widget's window to match the size specified in the widget's fields. In this case, \f(CWXtResizeWindow()\fP will not work, because it assumes that the widget's fields and the window size are in sync and would decide that \f(CWXConfigureWindow()\fP does not need to be called. .\" .SH "See Also" .na \s-1\fIXtResizeWidget\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtResolvePathname" "Xt \- File Searching" .SH "Name" .XS "XtResolvePathname" .Na XtResolvePathname \- search for a file using standard substitutions in a path list. .Nz .SH "Synopsis" .Sy String XtResolvePathname(\f(CIdisplay\fP, \f(CItype\fP, \f(CIfilename\fP, \f(CIsuffix\fP, \f(CIpath\fP, .br \f(CIsubstitutions\fP, \f(CInum_substitutions\fP, \f(CIpredicate\fP) .As Display *\f(CIdisplay\fP; String \f(CItype\fP, \f(CIfilename\fP, \f(CIsuffix\fP, \f(CIpath\fP; Substitution \f(CIsubstitutions\fP; Cardinal \f(CInum_substitutions\fP; XtFilePredicate \f(CIpredicate\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the display. .IP \f(CItype\fP 1i Specifies the type of the file to find, or \f(CWNULL\fP; substituted for %T. .IP \f(CIfilename\fP 1i Specifies the base name of the file to find, or \f(CWNULL\fP; substituted for %N. .IP \f(CIsuffix\fP 1i Specifies the suffix of the file to find, or \f(CWNULL\fP; substituted for %S. .IP \f(CIpath\fP 1i Specifies the list of file specifications to test, or \f(CWNULL\fR. .IP \f(CIsubstitutions\fP 1i Specifies a list of additional substitutions to make into the path, or \f(CWNULL\fR. .IP \f(CInum_substitutions\fP 1i Specifies the number of entries in \f(CIsubstitutions\fP. .IP \f(CIpredicate\fP 1i Specifies a procedure called to test each potential file name, or \f(CWNULL\fR. .SS "Returns" A filename, or \f(CWNULL\fP if no appropriate file was found. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtResolvePathname()\fP is used to find a file (often a resource file) which has a name, and is installed in a directory, that depends on the language in use by the application, the type of the file, the class name of the application, and, in Release 5, the value of the \f(CWcustomization\fP resource. .LP \f(CWXtResolvePathname()\fP performs a number of standard substitutions, and any extra substitutions specified in \f(CIsubstitutions\fP, on each colon-separated element of \f(CIpath\fP in turn, and passes the resulting string to \f(CIpredicate\fP. If \f(CIpredicate\fP returns \f(CWTrue\fP, \f(CWXtResolvePathname()\fP returns the string. If \f(CIpredicate\fP does not return \f(CWTrue\fP for any of the elements in \f(CIpath\fP, \f(CWXtResolvePathname()\fP returns \f(CWNULL\fP. .LP It is the responsibility of the caller to free the returned string using \f(CWXtFree()\fR when it is no longer needed. .LP If \f(CIpredicate\fP is \f(CWNULL\fP, then an internal predicate is used that returns \f(CWTrue\fP if the string is the name of a readable file (and is not a directory), and returns \f(CWFalse\fP otherwise. See \f(CWXtFilePredicate\fP(2) for more details on how to write a customized file predicate procedure. .LP If any element in \f(CIpath\fP contains a percent sign followed by one of the standard characters N, T, S, C, L, l, t, or c, then that two-character sequence is replaced with one of the standard substitutions described below. If a percent sign is followed by a substitution character specified in \f(CIsubstitutions\fP, then that non-standard substitution will be performed. See the "Background" section below for more information on non-standard substitutions. The standard substitutions are as follows: .IP %T .3i The value of the \f(CItype\fP argument. This is the general category of file, such as "app-defaults," "bitmap," or "help." If \f(CItype\fP is \f(CWNULL\fP, the empty string is used. .IP %N .3i The value of the \f(CIfilename\fP argument, or the application's class name if \f(CIfilename\fP is \f(CWNULL\fP. (The application's class name is passed to \f(CWXtAppInitialize()\fP or \f(CWXtDisplayInitialize()\fP and is associated with the display). .IP %S .3i The value of the \f(CIsuffix\fP argument. For app-defaults file, this should be \f(CWNULL\fP. For bitmap files, however, it might be ".bm". If \f(CIsuffix\fP is \f(CWNULL\fP, the empty string is used. .IP %C .3i The value of the \f(CWcustomization\fP resource in the database associated with \f(CIdisplay\fP. The user may set this resource to a value such as "\-color" to indicate that files (resource files, bitmaps, etc.) appropriate for a color screen should be found, or to "\-mono" if they are using a monochrome screen. If this resource is not specified, the empty string is used for the substitution. This substitution is performed only in Release 5 and later releases. .IP %L .3i The value of the language string associated with the display. This is the value of the \f(CWxnlLanguage\fP resource in Release 4, and in Release 5 and later, it is the value of this resource or the value returned by the language procedure, if any is registered. (See \f(CWXtSetLanguageProc()\fP and \f(CWXtDisplayInitialize()\fP for more information.) In Release 5, if the \f(CWxnlLanguage\fP resource is not set, the language procedure will usually return the value of the LANG environment variable. .IP %l .3i The "language part" of the language string of the display. .IP %t .3i The "territory part" of the language string of the display. .IP %c .3i The "codeset part" of the language string of the display. .LP These substitutions are performed on the elements of \f(CIpath\fP, or if \f(CIpath\fP is \f(CWNULL\fP, on the path specified in the XFILESEARCHPATH environment variable. If this variable is not defined, a default path is used. .LP See the "Background" section below for an explanation of the default path, the various parts of the language string, and of non-standard substitutions. .\" .SH "Usage" The Intrinsics use \f(CWXtResolvePathname()\fP to find an application's app-defaults file (see \f(CWXtAppInitialize()\fP). If your application reads other files which contain bitmaps, help text, or other information that may need to be customized depending on the .hw customization user's \f(CWcustomization\fP resource or preferred language, .ne 2 you should use \f(CWXtResolvePathname()\fP to find the file. This greatly aids the portability and customizability of your application. .LP A disadvantage of this approach is that it requires your files to be installed in locations removed from the application itself. Still, files have to be installed somewhere, and \f(CWXtResolvePathname()\fP provides some standardization for this installation process. .LP Note that you can pass \f(CWNULL\fP for many of the arguments to this function. The return value of the function is a filename, not an opened file. .LP If you are not interested in any of the standard substitutions, or the default path, you can use \f(CWXtFindFile()\fP to search for a file. This is a lower-level function than most applications will want to use. \f(CWXtResolvePathname()\fP calls \f(CWXtFindFile()\fP itself. .\" .SH "Example" To find the app-defaults file for an application, you can simply use XtResolvePathname as\p follows: .Ps filename = XtResolvePathname(dpy, "app-defaults", NULL, NULL, NULL, NULL, 0, NULL); .Pe If your application needs to read a help file which you plan to install in \fI/usr/lib/X11/help\fP (\fI/usr/lib/X11/\fP will be part of the default path on most implementations) with the same name as the application class, and with the suffix, ".txt", you could use \f(CWXtResolvePathname()\fP as follows: .Ps filename = XtResolvePathname(dpy, "help", NULL, ".txt", NULL, NULL, 0, NULL); .Pe If your application needs to read a number of bitmap files, you should probably not install them directly in \fI/usr/lib/X11/bitmaps\fP because their names may conflict with bitmaps used by other applications. You could find them from a subdirectory of this directory as follows: .Ps sprintf(basename, "%s/%s", application_class, bitmap_name); bitmap_file = XtResolvePathname(dpy, "bitmaps", basename, ".bm", NULL, NULL, 0, NULL); .Pe .\" .SH "Background" This section explains the default path used by \f(CWXtResolvePathname()\fP, the various parts of the language string, and how to specify non-standard substitutions. .SS "The Default Path" If the \f(CIpath\fP argument is \f(CWNULL\fP, the value of the \s-1XFILESEARCHPATH\s+1 .XX "XFILESEARCHPATH" environment variable will be used. If \s-1XFILESEARCHPATH\s+1 is not defined, an implementation-specific default path will be used which contains at least 6 entries. These entries must contain the following substitutions: .IP 1. 3 %C, %N, %S, %T, %L or %C, %N, %S, %T, %l, %t, %c .IP 2. 3 %C, %N, %S, %T, %l .IP 3. 3 %C, %N, %S, %T .IP 4. 3 %N, %S, %T, %L or %N, %S, %T, %l, %t, %c .IP 5. 3 %N, %S, %T, %l .IP 6. 3 %N, %S, %T .LP The order of these six entries within the path must be as given above. The order and use of substitutions within a given entry is implementation dependent. If the path begins with a colon, it will be preceded by %N%S. If the path includes two adjacent colons, %N%S will be inserted between them. .LP A suggested value for the default path on POSIX-based systems is: .Ps .in +3n .ft I \s+1/usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:\ /usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:\ /usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S\s-1 .ft R .in -3n .Pe Using this example, if the user has specified a language, it will be used as a subdirectory of /usr/lib/X11 that will be searched for other files. If the desired file is not found there, the lookup will be tried again using just the language part of the specification. If the file is not there, it will be looked for in /usr/lib/X11. The \f(CItype\fP parameter is used as a subdirectory of the language directory or of /usr/lib/X11, and \f(CIsuffix\fP is appended to the file name. .\" .SS "The Language String" In Release 4, the language string was of the following form: .DS .in +5n \s+1\fIlanguage\fP[\^_\fIterritory\fP][.\fIcodeset\fP]\s-1 .in -5n .DE In Release 5, the format of the language string is specified to be implementation defined, and it may have a "language part" a "territory" part and a "codeset part". In practice, the Release 4 format is still a common one, with a language string like "en_GB.iso8859-1" meaning English, as spoken in Great Britain, encoded in the ISO8859-1 encoding (Latin-1). .\" .SS "Non-standard Substitutions" You can have \f(CWXtResolvePathname()\fP introduce additional substitutions into the specified path by passing an array of \f(CWSubstitutionRec\fP structures. Each element in \f(CIsubstitutions\fP is a structure that contains a character and a string. If any element in \f(CIpath\fP contains a percent sign followed by a character that appears in \f(CIsubstitutions\fP, then that two character sequence will be replaced by the corresponding string in \f(CIsubstitutions\fP. .LP There are two substitution sequences that are treated specially: .IP \(bu 3n The character sequence \fI%:\fR (percent colon) specifies an embedded colon that is not a delimiter; the sequence is replaced by a single colon. .IP \(bu 3n The character sequence \fI%%\fR (percent percent) specifies a percent character that does not introduce a substitution; the sequence is replaced by a single percent character. .LP A substitution string entry of \f(CWNULL\fR is equivalent to a pointer to an empty string. .LP If the operating system does not interpret multiple embedded name separators in the path (i.e., "/" in POSIX) the same way as a single separator, \f(CWXtResolvePathname()\fR will collapse multiple separators into a single one after performing all string substitutions. Except for collapsing embedded separators, the contents of the string substitutions are not interpreted by \f(CWXtResolvePathname()\fR and may therefore contain any operating-system-dependent characters, including additional name separators. .\" .SH "Structures" The \f(CWSubstitution\fP type is defined as follows: .XX "SubstitutionRec structure" .XX "types, SubstitutionRec" .Ps typedef struct { char match; String substitution; } SubstitutionRec, *Substitution; .Pe .\" .SH "See Also" .na \s-1\fIXtAppInitialize\fR\s+1\*(s1, \s-1\fIXtDisplayInitialize\fR\s+1\*(s1, \s-1\fIXtFindFile\fR\s+1\*(s1, \s-1\fIXtSetLanguageProc\fR\s+1\*(s1, .br \s-1\fIXtFilePredicate\fR\s+1\*(s2. .ad .\"last line comment .XE "XtResolvePathname" .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtResourceDefaultProc" "Xt \- Resource Management" .SH "Name" .Na XtResourceDefaultProc \- interface definition for procedure called to obtain a resource default value. .Nz .XS "XtResourceDefaultProc" .SH "Synopsis" .Sy typedef void (*XtResourceDefaultProc)(Widget, int, XrmValue *) .As Widget \f(CIw\fP\^; int \f(CIoffset\fP\^; XrmValue *\f(CIvalue_return\fP\^; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget whose resource is to be obtained. .IP \f(CIoffset\fP 1i Specifies the offset of the field in the widget record. .SS "Outputs" .IP \f(CIvalue_return\fP Returns the address of the default resource value. .SH "Description" An \f(CWXtResourceDefaultProc\fP is registered in an \f(CWXtResource\fP structure of an \f(CWXtResourceList\fP array by specifying the special value \f(CWXtRCallProc\fP for the \f(CWdefault_type\fP field, and specifying the procedure in the \f(CWdefault_addr\fP field. It is called by the Intrinsics when the default value of that resource is required. .LP An \f(CWXtResourceDefaultProc\fP should determine the default value of the resource, convert it to the correct type if necessary, and store the address of the value at \f(CIvalue_return\f(CW->addr\fR. It need not store the size of this value because the resource manager already knows the size of the resource. .LP See \f(CWXtGetApplicationResources\fP(1) for more information on the fields of the \f(CWXtResource\fP structure and an example of how to declare one. .\" .SH "Usage" An \f(CWXtResourceDefaultProc\fP is passed the offset of the resource field in the widget or object \f(CIw\fP as its \f(CIoffset\fP argument. It should not use this argument to set the resource value directly in the object. It can use it to identify which resource value is desired, if the same procedure is used to obtain default values for more than one resource. It can also be used to obtain the same resource value from some other already initialized widget of the same class, as is shown in the example below. .\" .SH "Example" The default value for the \f(CWXtNdepth\fP resource of the Core widget class should be whatever value the widget's parent has. To implement this, the \f(CWXtNdepth\fP resource is declared with an \f(CWXtResourceDefaultProc\fP as follows: .Ps {XtNdepth, XtCDepth, XtRInt,sizeof(int), XtOffsetOf(CoreRec,core.depth), XtRCallProc, (XtPointer)_XtCopyFromParent}, .Pe The \f(CW_XtCopyFromParent()\fP \f(CWXtResourceDefaultProc\fP is defined by the Intrinsics as follows. Note how the resource value is returned and how the \f(CIoffset\fP argument is used. .Ps void _XtCopyFromParent(widget, offset, value) Widget widget; int offset; XrmValue *value; { if (widget->core.parent == NULL) { XtAppWarningMsg(XtWidgetToApplicationContext(widget), "invalidParent","xtCopyFromParent", XtCXtToolkitError, "CopyFromParent must have non-NULL parent", (String *)NULL, (Cardinal *)NULL); value->addr = NULL; return; } value->addr = (XPointer)(((char *)widget->core.parent) + offset); } .Pe .\" .SH "See Also" .na \s-1\fIXtGetApplicationResources\fR\s+1\*(s1, \s-1\fIXtGetSubresources\fR\s+1\*(s1. .ad .XE "XtResourceDefaultProc" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtScreen" "Xt \- Object Information" .SH "Name" .Na XtScreen \- return the screen pointer for the specified widget. .XX "widgets: returning screen pointer (XtScreen)" .Nz .XX "XtScreen" .SH "Synopsis" .Sy Screen *XtScreen(\f(CIw\fP) .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget; must be of class Core or any subclass thereof. .SS "Returns" The screen pointer for \f(CIw\fP. .\" .SH "Description" \f(CWXtScreen()\fR returns a pointer to the \f(CWScreen\fP structure of the screen the specified widget is on. .\" .SH "Usage" \f(CWXtScreen()\fP is implemented as a function when called from application code, but is replaced by a more efficient macro when called from widget code including the file \fI\fP. .LP Use \f(CWXtScreenOfObject()\fP to return the display of a widget or the nearest widget ancestor of a non-widget object. .\" .SH "See Also" \s-1\fIXtDisplay\fR\s+1\*(s1, \s-1\fIXtScreenOfObject\fR\s+1\*(s1, \s-1\fIXtWindow\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtScreenDatabase" "Xt \- Resource Management" .SH "Name" .Na XtScreenDatabase \- obtain the resource database for a screen. .XX "XtScreenDatabase" .XX "resources: database of screen; obtaining" .XX "database: of screen" .Nz .\" .SH "Synopsis" .Sy XrmDatabase XtScreenDatabase(\f(CIscreen\fP) .As Screen *\f(CIscreen\fP; .Ae .\" .SS "Inputs" .IP \f(CIscreen\fP 1i Specifies the screen for which the database should be obtained. .SS "Returns" The resource database of \f(CIscreen\fP. .\" .SH "Availability" Release 5 and later. .\" .SH "Description" \f(CWXtScreenDatabase()\fP returns the fully merged resource database for the specified screen. If that database has not already been built (by \f(CWXtDisplayInitialize()\fP, for example), \f(CWXtScreenDatabase()\fP builds it. If the specified screen does not belong to a display initialized by \f(CWXtDisplayInitialize()\fP, the results are undefined. .LP See \f(CWXtDisplayInitialize()\fP for a description of how a resource database is built for a screen. .\" .SH "Usage" \f(CWXtDatabase()\fP returns the database associated with the default screen of a display. Prior to Release 5, this database was used for all screens of a display. .LP You should rarely need to use the database of a screen or display directly. \f(CWXtGetApplicationResources()\fP and related functions provide a more manageable approach to obtaining resource values. .\" .SH "Structures" \f(CWXrmDatabase\fP is an opaque data type. .\" .SH "See Also" .na \s-1\fIXtAppInitialize\fR\s+1\*(s1, \s-1\fIXtDatabase\fR\s+1\*(s1, \s-1\fIXtDisplayInitialize\fR\s+1\*(s1, \s-1\fIXtGetApplicationResources\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtScreenOfObject" "Xt \- Object Information" .SH "Name" .XX "XtScreenOfObject" .Na XtScreenOfObject \- return the screen pointer of a non-widget object. .Nz .SH "Synopsis" .Sy Screen *XtScreenOfObject(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object; may be of class Object or any subclass thereof. .SS "Returns" The screen of \f(CIobject\fP, or if its nearest widget ancestor. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtScreenOfObject()\fR is identical in function to \f(CWXtScreen()\fR if the object is a widget; otherwise \f(CWXtScreenOfObject()\fR returns the screen pointer for the nearest ancestor of object that is of class Core. .SH "Usage" If you are working with windowed objects, use \f(CWXtScreen()\fP rather than \f(CWXtScreenOfObject()\fP. \f(CWXtScreen()\fP may be implemented as an efficient macro for widget code that includes the file \fI\fP. .SH "See Also" .na \s-1\fIXtDisplayOfObject\fR\s+1\*(s1, \s-1\fIXtScreen\fR\s+1\*(s1, \s-1\fIXtWindowOfObject\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSelectionCallbackProc" "Xt \- Selections" .SH "Name" .Na XtSelectionCallbackProc \- interface definition for procedure called when requested selection data is ready. .Nz .XS "selections: data; method" .XN "selections: data; (see also XtSelectionCallbackProc)" .XS "XtSelectionCallbackProc" .SH "Synopsis" .Sy typedef void (*XtSelectionCallbackProc)(Widget, XtPointer, Atom *, Atom *, XtPointer, unsigned long *, int *); .As Widget \f(CIw\fP; XtPointer \f(CIclient_data\fP; Atom *\f(CIselection\fP; Atom *\f(CItype\fP; XtPointer \f(CIvalue\fP; unsigned long *\f(CIlength\fP; int *\f(CIformat\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that requested the selection value. .IP \f(CIclient_data\fP 1i Specifies data registered with this procedure when the selection value was requested. .IP \f(CIselection\fP 1i Specifies the selection that was requested (usually \s-1\f(CWXA_PRIMARY\fP\s+1 or \s-1\f(CWXA_SECONDARY\fP\s+1). .IP \f(CItype\fP 1i Specifies the representation type of the selection value (for example, \s-1\f(CWXA_STRING\fP\s0). .IP \f(CIvalue\fP 1i Specifies a pointer to the selection value. .IP \f(CIlength\fP 1i Specifies the number of elements in value. .IP \f(CIformat\fP 1i Specifies the size in bits of the data elements of value. .\" .SH "Description" An \f(CWXtSelectionCallbackProc\fP is registered in a call to \f(CWXtGetSelectionValue()\fP, \f(CWXtGetSelectionValues()\fP, \f(CWXtGetSelectionValueIncremental()\fP, or \f(CWXtGetSelectionValuesIncremental()\fP. Because interclient communication is asynchronous, these functions cannot return the selection value directly, and instead register an \f(CWXtSelectionCallbackProc\fP to be called when the selection owner has converted and transferred the requested data. .LP The \f(CIw\fP, \f(CIclient_data\fP, and \f(CIselection\fP arguments are the same as those passed when the selection value was requested. The type argument is a pointer to an Atom that identifies the type of the returned data. This is generally not the same as the Atom that was passed as the requested \f(CItarget\fP type. If the target was the Atom FILENAME, for example, the \f(CItype\fP of the returned value will probably be \f(CWXA_STRING\fP. If the selection owner does not respond within the Intrinsics timeout interval, the Intrinsics call this callback with the special value \f(CWXT_CONVERT_FAIL\fP in \f(CItype\fP. Note that \f(CWXT_CONVERT_FAIL\fP is not actually an Atom, and does not need to be interned. An \f(CWXtSelectionCallbackProc\fP should test its \f(CItype\fP argument to verify that the type of the data is as expected, or is at least something it can handle. .LP The \f(CIvalue\fP argument is a pointer to the selection value. It is an array of \f(CIlength\fP elements, each element \f(CIformat\fP bits long, and should be interpreted as indicated by the \f(CItype\fP argument. \f(CIformat\fP will be one of 8, 16, or 32. The requesting client owns the storage allocated for the selection value and is responsible for freeing it by calling \f(CWXtFree()\fR when it is done with it. If there is no owner for the specified selection, or that owner cannot convert the selected data to the requested type, then this callback is called with \f(CIvalue\fP \f(CWNULL\fP and \f(CIlength\fP zero. .LP If an \f(CWXtSelectionCallbackProc\fP is registered with \f(CWXtGetSelectionValue()\fP, then it will only be called once, with the complete selection value converted to the single requested target type. If it is registered with \f(CWXtGetSelectionValues()\fP, it will be called once for each target type that is specified in that call. Each call will pass the entire selected values. These two functions are part of the Intrinsics atomic selection transfer mechanism, and will only call their \f(CWXtSelectionCallbackProc\fP once to deliver a selection value. If the selection value is larger than will fit in a single X protocol request, the Intrinsics transparently handle breaking up the value and reassembling it after transfer. .LP If an \f(CWXtSelectionCallbackProc\fP is registered with \f(CWXtGetSelectionValueIncremental()\fP or \f(CWXtGetSelectionValuesIncremental()\fP, then it will be called at least twice for each selection value it delivers. These two functions are part of the Intrinsics incremental selection transfer mechanism, and call their \f(CWXtSelectionCalbackProc\fP to deliver the selection value piece by piece. When the last chunk of a selection value has been transferred, the callback is called a final time with \f(CWlength\fP zero, and a non-\f(CWNULL\fP \f(CIvalue\fP, which is a special signal that the transfer is complete. The callback must free this non-\f(CWNULL\fP value, even though the \f(CIlength\fP argument is zero. .\" .SH "Usage" Note that the \f(CIselection\fP, \f(CItype\fP, \f(CIlength\fP, and \f(CIformat\fP arguments to this callback are pointers to their values rather than the values themselves. This is unusual in a procedure of this type, and you should be sure to dereference them correctly. Note that you should not modify the values pointed to by these arguments. .LP An \f(CWXtSelectionCallbackProc\fP can generally simply test \f(CItype\fP to see if it is one of the possible values that it knows how to handle. If \f(CI*type\fP is \f(CWXT_CONVERT_FAIL\fP, or some unrecognized type, the callback can just return silently, or may notify the user that the selection failed by calling \f(CWXBell()\fP, for example. It should do the same if called with zero \f(CIlength\fP and a \f(CWNULL\fP \f(CIvalue\fP. .LP When working with selections, you will have to work with Atoms. Many standard Atoms are predefined in <\fIX11/Xatom.h\fP>, and have symbolic names beginning with \f(CWXA_\fP. Atoms that are not defined in this file (\f(CWTARGETS\fR, for example) may be interned explicitly as Atoms by calling the Xlib function \f(CWXInternAtom()\fR. The Xmu library provides an alternate function, \f(CWXmuInternAtom()\fP which caches Atoms on the client side. Additionally, the header \fI\fP defines a number of macros, such as \f(CWXA_TARGETS(dpy)\fP, which call \f(CWXmuInternAtom()\fP and take a Display pointer as their single argument. .\" .SH "Example" The following \f(CWXtSelectionCallbackProc\fP is modified from the X11R5 \f(CIbitmap\fP client. .Ps /* ARGSUSED */ void SelectionCallback(w, cldat, selection, type, value, length, format) Widget w; XtPointer cldat; Atom *selection, *type; XtPointer value; unsigned long *length; int *format; { BitmapWidget BW = (BitmapWidget) w; Pixmap *pixmap; if ((*length != 0) && (value != NULL)) { switch (*type) { case XA_BITMAP: case XA_PIXMAP: DestroyBitmapImage(&BW->bitmap.storage); pixmap = (Pixmap *) value; BW->bitmap.storage = GetImage(BW, *pixmap); XFree((char *)pixmap); break; } } BW->bitmap.selection.limbo = FALSE; } .Pe This \f(CWXtSelectionCallbackProc\fP procedure is registered by the procedure below, also modified from the X11R5 \fIbitmap\fP client. Note that this procedure will optionally enter a local event loop so that it appears to block. If called with \f(CIwait\fP \f(CWTrue\fP, then it will not return until the selection value has been transferred. .Ps void BWRequestSelection(w, btime, wait) Widget w; Time btime; Boolean wait; { BitmapWidget BW = (BitmapWidget) w; XtGetSelectionValue(w, XA_PRIMARY, XA_PIXMAP, SelectionCallback, NULL, btime); BW->bitmap.selection.limbo = TRUE; if (wait) while (BW->bitmap.selection.limbo) { XEvent event; XtNextEvent(&event); XtDispatchEvent(&event); } } .Pe .\" .SH "See Also" .na \s-1\fIXtDisownSelection\fR\s+1\*(s1, \s-1\fIXtGetSelectionValue\fR\s+1\*(s1, \s-1\fIXtGetSelectionValueIncremental\fR\s+1\*(s1, \s-1\fIXtGetSelectionValues\fR\s+1\*(s1, \s-1\fIXtGetSelectionValuesIncremental\fR\s+1\*(s1, \s-1\fIXtOwnSelection\fR\s+1\*(s1, \s-1\fIXtOwnSelectionIncremental\fR\s+1\*(s1. .ad .XE "selections: data; method" .XE "XtSelectionCallbackProc" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSelectionDoneIncrProc" "Xt \- Selections" .SH "Name" .Na XtSelectionDoneIncrProc \- interface definition for procedure called when an incremental selection transfer completes. .Nz .XS "XtSelectionDoneIncrProc" .SH "Synopsis" .Sy typedef void (*XtSelectionDoneIncrProc)(Widget, Atom *, Atom *, .br XtRequestId *, XtPointer); .As Widget \f(CIw\fP; Atom *\f(CIselection\fP; Atom *\f(CItarget\fP; XtRequestId *\f(CIrequest_id\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that owns the selection. .IP \f(CIselection\fP 1i Specifies the atom that names the selection being transferred. .IP \f(CItarget\fP 1i Specifies the target type to which the conversion was done. .IP \f(CIrequest_id\fP 1i Identifies the specific conversion request that completed. .IP \f(CIclient_data\fP 1i Specifies data registered with this procedure when the widget took ownership of the selection. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" An \f(CWXtSelectionDoneIncrProc\fP is optionally registered in a call to \f(CWXtOwnSelectionIncremental()\fP, and is called by the Intrinsics after the requestor has retrieved the final (zero-length) segment of the incremental transfer to indicate that the entire transfer is complete. The \f(CIw\fP, \f(CIselection\fP, and \f(CIclient_data\fP arguments are those passed to \f(CWXtOwnSelectionIncremental()\fP. The \f(CItarget\fP and \f(CIrequest_id\fP arguments are those that were passed to the \f(CWXtConvertSelectionIncrProc\fP registered with this procedure. .LP An \f(CWXtSelectionDoneIncrProc\fP should free any memory that was allocated for the transfer of the selection value. If no procedure is specified, the Intrinsics will automatically free (using \f(CWXtFree()\fP) the last value returned by the \f(CWXtConvertSelectionIncrProc\fP. If a single buffer is used to transfer all the chunks of the selection, this automatic freeing by the Intrinsics should be sufficient. If separate buffers are used or other memory or resources are allocated to transfer the selection value, an \f(CWXtSelectionDoneIncrProc\fP should be provided to free them. .SH "Usage" It is usually more convenient to use the Intrinsics atomic selection transfer mechanism which transfers the selection value in a single chunk. See \f(CWXtOwnSelection\fP(1) and \f(CWXtSelectionDoneProc\fP for more information. .\" .SH "See Also" .na \s-1\fIXtGetSelectionValueIncremental\fR\s+1\*(s1, \s-1\fIXtGetSelectionValuesIncremental\fR\s+1\*(s1, \s-1\fIXtOwnSelection\fR\s+1\*(s1, \s-1\fIXtOwnSelectionIncremental\fR\s+1\*(s1, .br \s-1\fIXtCancelConvertSelectionProc\fR\s+1\*(s2, \s-1\fIXtConvertSelectionIncrProc\fR\s+1\*(s2, \s-1\fIXtLoseSelectionIncrProc\fR\s+1\*(s2, \s-1\fIXtSelectionDoneProc\fR\s+1\*(s2. .ad .XE "XtSelectionDoneIncrProc" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSelectionDoneProc" "Xt \- Selections" .SH "Name" .Na XtSelectionDoneProc \- interface definition for procedure called after selection transfer is completed. .Nz .XX "XtSelectionDoneProc" .XN "selections: method; (see also XtSelectionDoneProc)" .XX "data, data transfer completion method" .SH "Synopsis" .Sy typedef void (*XtSelectionDoneProc)(Widget, Atom *, Atom *); .As Widget \f(CIw\fP; Atom *\f(CIselection\fP; Atom *\f(CItarget\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that owns the converted selection. .IP \f(CIselection\fP 1i Specifies the atom that names the selection that was transferred. .IP \f(CItarget\fP 1i Specifies the target type to which the conversion was done. .\" .SH "Description" An \f(CWXtSelectionDoneProc\fP is optionally registered in a call to \f(CWXtOwnSelection()\fP, and is called by the Intrinsics after the corresponding \f(CWXtConvertSelectionProc\fP has been called and the data it returns is transferred to the requestor. .LP An \f(CWXtSelectionDoneProc\fP should free the memory returned by the \f(CWXtConvertSelectionProc\fP and any other memory or resources allocated by that procedure to convert the selection value. If no \f(CWXtSelectionDoneProc\fP is registered with \f(CWXtOwnSelection()\fP, then the Intrinsics will automatically free the memory returned by the \f(CWXtConvertSelectionProc\fP by calling \f(CWXtFree()\fP. .\" .SH "Usage" Most \f(CWXtConvertSelectionProc\fP procedures will allocate a single block of memory with \f(CWXtMalloc()\fP and can simply rely on the Intrinsics to free that block with \f(CWXtFree()\fP. In this case, there is no need for an \f(CWXtSelectionDoneProc\fP. .LP Note that an \f(CWXtSelectionDoneProc\fP is not passed a \f(CIclient_data\fP argument, nor is it passed a pointer to the memory that was returned by the \f(CWXtConvertSelectionProc\fP. In a widget, the widget structure can point to the memory that must be freed, but in an application, you will probably have to rely on a global variable, as in the example below. .LP The \f(CWXtSelectionDoneProc\fP and \f(CWXtOwnSelection()\fP are part of the Intrinsics atomic selection transfer mechanism. For some selection values, it may be more convenient to transfer the selection value in pieces. This can be done with the incremental transfer mechanism; see \f(CWXtOwnSelectionIncremental\fP(1). .\" .Nd 10 .SH "Example" The \fIxcalc\fP client uses a static character string to store the selection value. Because this is not allocated memory, it should not be freed, so \fIxcalc\fP provides a \f(CWXtSelectionDoneProc\fP which simply sets the static buffer to contain the empty string: .Ps static char selstr[LCD_STR_LEN]; /* storage for selections from the LCD */ /*ARGSUSED*/ void done(w, selection, target) Widget w; Atom *selection; Atom *target; { selstr[0] = '\0'; } .Pe This \f(CWXtSelectionDoneProc\fP is registered with this call: .Ps XtOwnSelection(LCD, XA_PRIMARY, time, convert, lose, done); .Pe .\" .SH "See Also" .na \s-1\fIXtDisownSelection\fR\s+1\*(s1, \s-1\fIXtGetSelectionValue\fR\s+1\*(s1, \s-1\fIXtGetSelectionValues\fR\s+1\*(s1, \s-1\fIXtOwnSelection\fR\s+1\*(s1, \s-1\fIXtOwnSelectionIncremental\fR\s+1\*(s1, .br \s-1\fIXtConvertSelectionProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtSelection 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtSelectionCallbackProc@XtSelectioA .sp .5 XtSelectionDoneIncrProc@XtSelectioB .sp .5 XtSelectionDoneProc@XtSelectioC .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetArg" "Xt \- Argument Lists" .hw "widget" .SH "Name" .Na XtSetArg \- set a resource name and value in an argument list. .XS "arguments: argument lists; constructing" .Nz .XS "XtSetArg" .SH "Synopsis" .Sy void XtSetArg(\f(CIarg\fP, \f(CIresource_name, \fP\f(CIvalue\fP) .As Arg arg; String \f(CIresource_name\fP; XtArgVal \f(CIvalue\fP; .Ae .SS "Inputs" .IP \f(CIarg\fP 1i Specifies the \f(CWArg\fP structure to set. .IP \f(CIresource_name\fP 1i Specifies the name of the resource. .IP \f(CIvalue\fP 1i Specifies the value of the resource, or its address. .\" .SH "Description" \f(CWXtSetArg()\fP sets \f(CIarg\f(CW.name\fR to \f(CIresource_name\fP, and sets \f(CIarg\f(CW.value\fR to \f(CIvalue\fP. If the size of the resource is less than or equal to the size of an \f(CWXtArgVal\fP, the resource value is stored directly in \f(CIvalue\fP; otherwise, a pointer to it is stored in \f(CIvalue\fP. .LP \f(CWXtSetArg()\fP is implemented as the following macro: .Ps #define XtSetArg(arg, n, d) \ ((void)( (arg).name = (n), (arg).value = (XtArgVal)(d) )) .Pe Because this macro evaluates \f(CIarg\fP twice, you must not use an expression with autoincrement, autodecrement or other side effects for this argument. .\" .SH "Usage" Many Intrinsics functions need to be passed pairs of resource names and values in an ArgList to set or override resource values. \f(CWXtSetArg()\fP is used to set or dynamically change values in an \f(CWArg\fP structure or \f(CWArgList\fP array. .LP Note that in Release 4, a number of functions beginning with the prefix \f(CWXtVa\fP were added to the Intrinsics. These functions accept a \f(CWNULL\fP-terminated variable-length argument list instead of a single \f(CWArgList\fP array. Often these forms of the functions are easier to use. .\" .SH "Example" \f(CWXtSetArg()\fR is usually used in a highly stylized manner to minimize the probability of making a mistake; for example: .Ps .ta 3i Arg args[20]; int n; .sp .5 n = 0; XtSetArg(args[n], XtNheight, 100); n++; XtSetArg(args[n], XtNwidth, 200); n++; XtSetValues(widget, args, n); .Pe .Nd 2 Incrementing the array index on the same line means that resource settings can be easily read, inserted, deleted or commented out on a line-by-line basis. If you use this approach, be careful when using \f(CWXtSetArg()\fP inside an \f(CWif\fP statement\-don't forget to use curly braces to include the increment statement. .LP Alternatively, an application can statically declare the argument list: .LP .Ps static Args args[] = { {XtNheight, (XtArgVal) 100}, {XtNwidth, (XtArgVal) 200}, }; XtSetValues(Widget, args, XtNumber(args)); .Pe .\" .SH "Structures" The \f(CWArg\fR and \f(CWArgList\fP types are defined as follows: .Ps .ta 4.5n 2i typedef struct { String name; XtArgVal value; } Arg, *ArgList; .Pe .LP The definition of \f(CWXtArgVal\fP differs depending on architecture\-its purpose is precisely to make code portable between architectures with different word sizes. .LP .SH "See Also" .na \s-1\fIXtMergeArgLists\fR\s+1\*(s1, \s-1\fIXtNumber\fR\s+1\*(s1. .ad .XE "arguments: argument lists; constructing" .XE "XtSetArg" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetErrorHandler" "Xt \- Error Handling" .SH "Name" .Na XtSetErrorHandler \- set the low-level error handler procedure. .Nz .XX "XtSetErrorHandler" .SH "Synopsis" .Sy void XtSetErrorHandler(\f(CIhandler\fP) .As XtErrorHandler \f(CIhandler\fP; .Ae .SS "Inputs" .IP \f(CIhandler\fP 1i Specifies the new low-level fatal error procedure, which should not return. .\" .SH "Availability" \f(CWXtSetErrorHandler()\fP has been superseded by \f(CWXtAppSetErrorHandler()\fP. .\" .SH "Description" \f(CWXtSetErrorHandler()\fP registers the procedure \f(CIhandler\fP as the procedure to be invoked by \f(CWXtError()\fP. It should display the string it is passed and then must terminate the application; if it returns the subsequent behavior of the Intrinsics is undefined. .\" .SH "Usage" \f(CWXtSetErrorHandler()\fP has been superseded by \f(CWXtAppSetErrorHandler()\fP, which performs the same function on a per-application context basis. \f(CWXtSetErrorHandler()\fP now calls \f(CWXtAppSetErrorHandler()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtSetErrorHandler()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppSetErrorHandler()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppSetErrorHandler()\fP for more information. .SH "See Also" .na \s-1\fIXtAppSetErrorHandler\fR\s+1\*(s1, \s-1\fIXtAppSetErrorMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningHandler\fR\s+1\*(s1, .br \s-1\fIXtErrorHandler\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .RH "XtSetErrorMsgHandler" "Xt \- Error Handling" .SH "Name" .Na XtSetErrorMsgHandler \- set the high-level error handler procedure. .Nz .XX "XtSetErrorMsgHandler" .SH "Synopsis" .Sy void XtSetErrorMsgHandler(\f(CImsg_handler\fP) .As XtErrorMsgHandler \f(CImsg_handler\fP; .Ae .SS "Inputs" .IP \f(CImsg_handler\fP 1.25i Specifies the new high-level fatal error procedure, which should not return. .\" .SH "Availability" \f(CWXtSetErrorMsgHandler()\fP has been superseded by \f(CWXtAppSetErrorMsgHandler()\fP. .\" .SH "Description" \f(CWXtSetErrorMsgHandler()\fP registers the procedure \f(CImsg_handler\fP as the procedure to be invoked by \f(CWXtErrorMsg()\fP. .\" .SH "Usage" \f(CWXtSetErrorMsgHandler()\fP has been superseded by \f(CWXtAppSetErrorMsgHandler()\fP, which performs the same function on a per-application context basis. \f(CWXtSetErrorMsgHandler()\fP now calls \f(CWXtAppSetErrorMsgHandler()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtSetErrorMsgHandler()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppSetErrorMsgHandler()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppSetErrorMsgHandler()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtAppSetErrorHandler\fR\s+1\*(s1, \s-1\fIXtAppSetErrorMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningMsgHandler\fR\s+1\*(s1, .br \s-1\fIXtErrorMsgHandler\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetKeyTranslator" "Xt \- Keyboard Handling" .SH "Name" .Na XtSetKeyTranslator \- register a key translator. .XX "key translation, registering" .XX "key translation, XtSetKeyTranslator" .Nz .XX "XtSetKeyTranslator" .SH "Synopsis" .Sy void XtSetKeyTranslator(\f(CIdisplay\fP, \f(CIproc\fP) .As Display *\f(CIdisplay\fP; XtKeyProc \f(CIproc\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the display from which to translate the events. .IP \f(CIproc\fP 1i Specifies the procedure that is to perform key translations. .\" .SH "Description" \f(CWXtSetKeyTranslator()\fR registers the specified procedure as the current key translator. The default translator is \f(CWXtTranslateKey()\fR, an \f(CWXtKeyProc\fR that uses the Shift, Lock, and group modifiers with the interpretations defined by the X11 protocol. \f(CWXtTranslateKey()\fR is provided so that new translators can call it to get default keycode-to-keysym translations and so that the default translator can be reinstalled. .LP See \f(CWXtKeyProc\fP(2) for an explanation of the responsibilities of a key translator procedure. .\" .SH "Usage" The key translator procedure is called by the Translation Manager to convert incoming keycodes and modifier bits to keysyms. The only reason you would have to write and install your own key translator procedure is if you were working with non-standard keysyms. .LP The only way to remove a translator is to register a new one. For example, the default key translator (\f(CWXtTranslateKey()\fP) can be explicitly reinstalled. .SH "See Also" .na \s-1\fIXtConvertCase\fR\s+1\*(s1, \s-1\fIXtGetKeysymTable\fR\s+1\*(s1, \s-1\fIXtKeysymToKeycodeList\fR\s+1\*(s1, \s-1\fIXtRegisterCaseConverter\fR\s+1\*(s1, \s-1\fIXtTranslateKeycode\fR\s+1\*(s1, \s-1\fIXtTranslateKey\fR\s+1\*(s1, .br \s-1\fIXtKeyProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetKeyboardFocus" "Xt \- Keyboard Handling" .SH "Name" .Na XtSetKeyboardFocus \- redirect keyboard input to a widget. .XS "keyboard: keyboard focus; redirecting input" .XN "keyboard: keyboard focus; (see also XtSetKeyboardFocus)" .Nz .XS "XtSetKeyboardFocus" .SH "Synopsis" .Sy void XtSetKeyboardFocus(\f(CIsubtree\fP\, \f(CIdescendant\fP) .As Widget \f(CIsubtree\fP, \f(CIdescendant\fP; .Ae .SS "Inputs" .IP \f(CIsubtree\fP 1i Specifies the widget to be considered the root of the subtree for which the keyboard focus is to be set. Must be of class Core or any subclass thereof. .IP \f(CIdescendant\fP 1i Specifies a normal (non-popup) descendant of \f(CIsubtree\fR to which keyboard events are to be redirected, or \f(CWNone\fR. May be of class Object or any subclass thereof. .\" .SH "Description" \f(CWXtSetKeyboardFocus()\fR causes \f(CWXtDispatchEvent()\fR to remap keyboard events that occur within the widget hierarchy rooted at \f(CIsubtree\fP and to dispatch them to \f(CIdescendant\fP. If \f(CIdescendant\fR is not a subclass of Core, it is replaced by its closest windowed ancestor. If \f(CIdescendant\fP is \f(CWNone\fP, keyboard events within \f(CIsubtree\fP will be dispatched normally. .LP When \f(CIsubtree\fP or one of its descendants acquires the X keyboard focus, or the pointer moves into the subtree such that keyboard events would now be delivered to \f(CIsubtree\fP, a \f(CWFocusIn\fR event is generated for \f(CIdescendant\fP if \f(CWFocusChange\fR events have been selected by \f(CIdescendant\fP. Similarly, when \f(CIsubtree\fP loses the X keyboard focus or the keyboard focus for one of its ancestors, a \f(CWFocusOut\fR event is generated for \f(CIdescendant\fP if \f(CWFocusChange\fR events have been selected by \f(CIdescendant\fP. .LP For more details on how events are dispatched after a call to \f(CWXtSetKeyboardFocus()\fP, see \f(CWXtDispatchEvent()\fP. .\" .SH "Usage" \f(CWXtSetKeyboardFocus()\fP does not call the Xlib function \f(CWXSetInputFocus()\fP; it simply causes the Intrinsics to dispatch events differently. For most applications, this approach is preferred over the more heavy-handed Xlib function. .\" .SH "Example" If a dialog box contains a Label widget, some Button widgets, and a single Text widget for input, it is good style to allow the user to enter text into the dialog when the mouse is anywhere over the dialog, not only when the mouse is over the Text widget itself. This can be arranged with code like the following: .Ps Widget shell, box, text, prompt, ok_button, cancel_button; XtPopup(shell, XtGrabExclusive); XtSetKeyboardFocus(box, text); .Pe After this call to \f(CWXtSetKeyboardFocus()\fP, whenever the dialog box gets the X input focus (for example, when the mouse moves into it) all keyboard events will be redirected at the text widget. .\" .SH "See Also" .na \s-1\fIXtAddGrab\fR\s+1\*(s1, \s-1\fIXtDispatchEvent\fR\s+1\*(s1. .ad .XE "keyboard: keyboard focus; redirecting input" .XE "XtSetKeyboardFocus" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetLanguageProc" "Xt \- Locale Management" .XX "XtSetLanguageProc" .XX "language procedures:setting" .SH "Name" .Na XtSetLanguageProc \- register the language procedure called to set the locale. .Nz .SH "Synopsis" .Sy XtLanguageProc XtSetLanguageProc(\f(CIapp_context\fP, \f(CIproc\fP, \f(CIclient_data\fP) .As XtAppContext \f(CIapp_context\fP; XtLanguageProc \f(CIproc\fP; XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIapp_context\fP 1i Specifies the application context in which the language procedure is to be used, or \f(CWNULL\fR. .IP \f(CIproc\fP 1i Specifies the language procedure. .IP \f(CIclient_data\fP 1i Specifies additional data to be passed to the language procedure when it is called. .SS "Returns" The previously registered language procedure. .\" .SH "Availability" Release 5 and later. .\" .SH "Description" \f(CWXtSetLanguageProc()\fP registers \f(CIproc\fP as the language procedure that will be called (with \f(CIclient_data\fP) from \f(CWXtDisplayInitialize()\fP for all subsequent displays initialized in the application context \f(CIapp_context\fP. The language procedure is called by \f(CWXtDisplayInitialize()\fP (in Release 5) in order to determine the language string and perform whatever localization is required by an internationalized application. .LP If \f(CIapp_context\fP is \f(CWNULL\fR, the specified language procedure is registered in all application contexts created by the calling process, including any future application contexts that may be created. If \f(CIproc\fP is \f(CWNULL\fR a default language procedure is registered. .LP \f(CWXtSetLanguageProc()\fP returns the previously registered language procedure. If a language procedure has not yet been registered, the return value is unspecified but if it is used in a subsequent call to \f(CWXtSetLanguageProc()\fP, it will cause the default language procedure to be registered. .LP Note that the "default" language procedure is not registered by default; you must call \f(CWXtSetLanguageProc()\fP with a \f(CWproc\fP of \f(CWNULL\fP to register this default procedure. If \f(CWXtSetLanguageProc()\fP is never called, \f(CWXtDisplayInitialize()\fP determines the language string by the same procedure it used prior to Release 5. See \f(CWXtDisplayInitialize()\fP for more information. .LP See the "Background" section below for a description of the default language procedure. See \f(CWXtLanguageProc\fP(2) for an explanation of how to write a language procedure. .\" .Nd 5 .SH "Usage" Most internationalized applications should call \f(CWXtSetLanguageProc()\fP directly before calling \f(CWXtAppInitialize()\fP. The default language procedure should be adequate for applications that use only the internationalization facilities provided by ANSI-C and Xlib. .\" .SH "Example" A client wishing to use this default procedure to establish locale can do so as in following example: .Ps Widget top; XtSetLanguageProc(NULL, NULL, NULL); top = XtAppInitialize( ... ); .Pe .\" .SH "Background" The default language procedure does the following: .IP \(bu 3n Sets the locale according to the environment. On ANSI C-based systems this is done by calling \f(CWsetlocale(LC_ALL, \f(CIlanguage\fP)\fR. If an error is encountered a warning message is issued with \f(CWXtWarning()\fP, where \f(CIlanguage\fP is the language string determined by \f(CWXtDisplayInitialize()\fP and passed to the default language procedure. .IP \(bu 3n Calls \f(CWXSupportsLocale()\fP to verify that the current locale is supported. If the locale is not supported, a warning message is issued with \f(CWXtWarning()\fP and the locale is set to "C." .IP \(bu 3n Calls \f(CWXSetLocaleModifiers()\fP specifying the empty string. .IP \(bu 3n Returns the value of the current locale. On ANSI-C-based systems this is the return value from a final call to \f(CWsetlocale(LC_ALL, NULL)\fP. .LP .SH "See Also" .na \s-1\fIXtDisplayInitialize\fR\s+1\*(s1, .br \s-1\fIXtLanguageProc\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetMappedWhenManaged" "Xt \- Resource Management" .SH "Name" .Na XtSetMappedWhenManaged \- set the value of a widget's \f(CWXtNmappedWhenManaged\fP resource and map or unmap the window. .XX "widgets: mapping; changing map_when_managed field" .XX "widgets: mapping; XtSetMappedWhenManaged" .XN "mapping: (see also widgets, mapping)" .Nz .XX "XtSetMappedWhenManaged" .SH "Synopsis" .Sy void XtSetMappedWhenManaged(\f(CIw\fP, \f(CImap_when_managed\fP) .As Widget \f(CIw\fP; Boolean \f(CImap_when_managed\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. Must be of class Core or any subclass thereof. .IP \f(CImap_when_managed\fP 1i Specifies the new value of the \f(CWmap_when_managed\fR field. .\" .SH "Description" If \f(CIw\fP is realized and managed and if \f(CImap_when_managed\fR is set to \f(CWTrue\fP, \f(CWXtSetMappedWhenManaged()\fR maps the widget's window. If the widget is realized and managed and if the new value of \f(CImap_when_managed\fR is set to \f(CWFalse\fP, \f(CWXtSetMappedWhenManaged()\fP unmaps the widget's window. In both cases, \f(CWXtSetMappedWhenManaged()\fP sets the value of the widget's \f(CWXtNmappedWhenManaged\fP resource as specified by the \f(CImap_when_managed\fP argument. .LP \f(CWXtSetMappedWhenManaged()\fR is a convenience function that is equivalent to (but slightly faster than) calling \f(CWXtSetValues()\fR to set the new value for the \f(CWXtNmappedWhenManaged\fR resource, and then mapping or unmapping the widget as appropriate. .\" .SH "Usage" A widget is normally mapped when it is managed, which is usually the desired behavior. This behavior can be overridden by setting the \f(CWXtNmappedWhenManaged\fR resource for the widget to \f(CWFalse\fP, and then calling \f(CWXtSetMappedWhenManaged()\fP to map and unmap the widget or by calling \f(CWXtMapWidget()\fP and \f(CWXtUnmapWidget()\fP explicitly. .LP A widget that is managed but unmapped will have screen space allocated for it, but will not appear in that space. A widget that is unmanaged will not have screen space allocated for it, and if mapped will likely appear in an undesirable place. .\" .SH "See Also" .na \s-1\fIXtManageChild\fR\s+1\*(s1, \s-1\fIXtMapWidget\fR\s+1\*(s1, \s-1\fIXtUnmapWidget\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetMultiClickTime" "Xt \- Mouse Handling" .SH "Name" .XX "XtSetMultiClickTime" .Na XtSetMultiClickTime \- set the multi-click time. .Nz .SH "Synopsis" .Sy void XtSetMultiClickTime(\f(CIdisplay\fP, \f(CItime\fP) .As Display *\f(CIdisplay\fP; int \f(CItime\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the display connection. .IP \f(CItime\fP 1i Specifies the multi-click time in milliseconds. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtSetMultiClickTime()\fR sets the time interval used by the translation manager to determine when multiple events are interpreted as a repeated event. When a repeat count is specified in a translation entry the time interval between arrival of each pair of repeated events (e.g., between two \f(CWButtonPress\fR events) must be less than the multi-click time in order for the translation actions to be taken. .\" .SH "Usage" The value of the multi-click time must remain completely under the user's control. An application should not set it except when directed to by the user. It is acceptable to set this value when the user specifies the new time in a "Preferences" configuration dialog box created by the application, for example, and it is also acceptable to set the multi-click time from a value saved in a user preferences file. .LP The initial multi-click time value can be specified as an application resource with name \f(CWmultiClickTime\fP and class \f(CWMultiClickTime\fP. The multi-click time is unique for each Display and is retrieved from the resource database by \f(CWXtDisplayInitialize()\fR. If no value is specified, the default initial value is 200 milliseconds. .SH "See Also" .na \s-1\fIXtGetMultiClickTime\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .RH "XtSetSelectionTimeout" "Xt \- Selections" .SH "Name" .Na XtSetSelectionTimeout \- set the Intrinsics selection timeout value. .XX "selections, timeout" .XX "timeouts, XtSetSelectionTimeout" .XX "XtSetSelectionTimeout" .Nz .SH "Synopsis" .Sy void XtSetSelectionTimeout(\f(CItimeout\fP) .As unsigned long \f(CItimeout\fP; .Ae .SS "Inputs" .IP \f(CItimeout\fP 1i Specifies the selection timeout in milliseconds. .\" .SH "Availability" \f(CWXtSetSelectionTimeout()\fP has been superseded by \f(CWXtAppSetSelectionTimeout()\fP. .SH "Description" \f(CWXtSetSelectionTimeout()\fP sets the Intrinsics selection timeout value. The selection timeout is the time within which two communicating applications must respond to one another. The initial timeout value is set by the \f(CWselectionTimeout\fP application resource, which has a default value of 5000 milliseconds (5 seconds). .\" .SH "Usage" \f(CWXtSetSelectionTimeout()\fP has been superseded by \f(CWXtAppSetSelectionTimeout()\fP, which performs the same function on a per-application context basis. \f(CWXtSetSelectionTimeout()\fP now calls \f(CWXtAppSetSelectionTimeout()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtSetSelectionTimeout()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppSetSelectionTimeout()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppSetSelectionTimeout()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtAppGetSelectionTimeout\fR\s+1\*(s1, \s-1\fIXtAppSetSelectionTimeout\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetSensitive" "Xt \- Resource Management" .SH "Name" .Na XtSetSensitive \- set the sensitivity state of a widget. .XN "widgets, sensitivity (see sensitivity)" .XX "sensitivity: setting state; XtSetSensitive" .Nz .XX "XtSetSensitive" .SH "Synopsis" .Sy void XtSetSensitive(\f(CIw\fP, \f(CIsensitive\fP) .As Widget \f(CIw\fP; Boolean \f(CIsensitive\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. .IP \f(CIsensitive\fP 1i Specifies whether the widget should receive keyboard, pointer, and focus events. .\" .SH "Description" \f(CWXtSetSensitive()\fP sets the sensitivity state of \f(CIw\fP. If \f(CIsensitive\fP is \f(CWFalse\fP, then \f(CIw\fP and all of its descendants will become insensitive and will not have any \f(CWKeyPress\fR, \f(CWKeyRelease\fR, \f(CWButtonPress\fR, \f(CWButtonRelease\fR, \f(CWMotionNotify\fR, \f(CWEnterNotify\fR, \f(CWLeaveNotify\fR, \f(CWFocusIn\fR, or \f(CWFocusOut\fR events dispatched to them. If \f(CIsensitive\fP is \f(CWTrue\fP, and if \f(CIw\fP's\p \f(CWXtNancestorSensitive\fP resource is also \f(CWTrue\fP, then \f(CIw\fP and its children will be made sensitive again, except for any children that have explicitly been made insensitive by calling \f(CWXtSetSensitive()\fP or by setting their \f(CWXtNsensitive\fP resource. .LP See the "Background" section below for more details on the algorithm followed by \f(CWXtSetSensitive()\fP and on how the sensitivity of a widget affects the sensitivity of its descendants. .\" .SH "Usage" Many widgets will display themselves differently when they are insensitive. A common approach is to draw themselves through a stipple mask so that they appear grayed-out. \f(CWXtSetSensitive()\fP uses \f(CWXtSetValues()\fP when it sets the \f(CWXtNsensitive\fP and \f(CWXtNancestorSensitive\fP resources, so widgets can check for changes to these resources in their \f(CWset_values()\fP method and take the appropriate action. .LP In an application, it is good style to make any widget insensitive if it does not currently make sense for the user to select it. A menu item labeled "Delete Selected Items", for example, should be insensitive if there are not any currently selected items. A button that pops up a modal dialog box should be made insensitive while that dialog box is popped up, so that the user cannot attempt to pop it up again. .LP You can test the sensitivity state of a widget by calling \f(CWXtIsSensitive()\fP. .LP Note that you can also set the sensitivity of a widget by setting the \f(CWXtNsensitive\fP resource directly. It is better to use XtSetSensitive because this handles composite widgets correctly. If you want a non-composite widget to be insensitive when it is created, you can specify \f(CWFalse\fP for \f(CWXtNsensitive\fP from a resource file or an argument list. You can query the value of the \f(CWXtNancestorSensitive\fP resource, but you should never set it. .LP Popup shells will have their \f(CWXtNancestorSensitive\fP resource set to \f(CWFalse\fP if their parent was insensitive when they were created. Since \f(CWXtSetSensitive()\fP on the parent will not modify the resource in the popup child, you should either be sure that you only create popup shells as children of sensitive widgets, or that you include a line like the following in your app-defaults file: .Ps *TransientShell.ancestorSensitive: True .Pe .\" .SH "Background" Widget sensitivity is controlled by the \f(CWsensitive\fP and \f(CWancestor_sensitive\fP fields in the Core instance record. \f(CWXtNsensitive\fP and \f(CWXtNancestorSensitive\fP are the resource names for these fields. A widget can be insensitive because its \f(CWsensitive\fP field is \f(CWFalse\fR or because one of its ancestors is insensitive. A widget can, but does not need to, distinguish these two cases visually. .LP \f(CWXtSetSensitive()\fR first calls \f(CWXtSetValues()\fR on the current widget to set the\p \f(CWXtNsensitive\fP resource to the value specified by \f(CIsensitive\fP. If \f(CIsensitive\fR is \f(CWFalse\fR and the widget is a subclass of Composite, \f(CWXtSetSensitive()\fR recursively propagates the new value down the children tree by calling \f(CWXtSetValues()\fR on each child to set \f(CWancestor_sensitive\fR to \f(CWFalse\fR. If \f(CIsensitive\fR is \f(CWTrue\fR and the widget is a subclass of Composite and the widget's \f(CWancestor_sensitive\fR field is \f(CWTrue\fR, then \f(CWXtSetSensitive()\fR sets the \f(CWancestor_sensitive\fR of each child to \f(CWTrue\fR and then recursively calls \f(CWXtSetValues()\fR on each normal descendant that is now sensitive to set \f(CWancestor_sensitive\fP to \f(CWTrue\fR. .LP \f(CWXtSetSensitive()\fR ensures that if a parent has either \f(CWsensitive\fP or \f(CWancestor_sensitive\fR set to \f(CWFalse\fP, then all children have \f(CWancestor_sensitive\fR set to \f(CWFalse\fP. .\" .SH "See Also" .na \s-1\fIXtGetValues\fR\s+1\*(s1, \s-1\fIXtIsSensitive\fR\s+1\*(s1, \s-1\fIXtSetValues\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetSubvalues" "Xt \- Resource Management" .SH "Name" .Na XtSetSubvalues \- copy resource settings from an \f(CWArgList\fP to a subpart resource structure. .Nz .XS "resources: resource list; copying" .XN "resources: resource list; copying" .XS "XtSetSubvalues" .SH "Synopsis" .Sy void XtSetSubvalues(\f(CIbase\fP, \f(CIresources\fP, \f(CInum_resources\fP, \f(CIargs\fP, \f(CInum_args\fP) .As XtPointer \f(CIbase\fP; XtResourceList \f(CIresources\fP; Cardinal \f(CInum_resources\fP; ArgList \f(CIargs\fP; Cardinal \f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIbase\fP 1i Specifies the base address of the subpart data structure into which the resources should be written. .IP \f(CIresources\fP 1i Specifies the subpart resource list. .IP \f(CInum_resources\fP 1i Specifies the number of resources in the resource list. .IP \f(CIargs\fP 1i Specifies an argument list of name/value pairs that contain the resource settings to be copied into the subpart data structure. .IP \f(CInum_args\fP 1i Specifies the number of arguments in the argument list. .\" .SH "Description" \f(CWXtSetSubvalues()\fR copies the values of named resources from \f(CIargs\fP into the structure pointed to by \f(CIbase\fP. The resource list \f(CIresources\fP specifies the size of each resource in this structure, and its offset from \f(CIbase\fP. The name of each resource in \f(CIargs\fP is looked up in this resource list, and the resource's specified size and offset are used to copy the resource value into the subpart structure. If the name of a resource in \f(CIargs\fP does not match any of the resources described by \f(CIresources\fP, then that resource name/value pair in \f(CIargs\fP is silently ignored. .LP See \f(CWXtGetApplicationResources()\fP for a description of the various fields of a \f(CWXtResource\fP structure and an example of initializing an \f(CWXtResourceList\fP. .\" .SH "Usage" If a widget has subpart resources, it can fetch initial values for those resources from the resource database by calling \f(CWXtGetSubresources()\fP from its \f(CWinitialize()\fP method and passing the user's argument list to override values from the database. In the resource file, the subpart will have a name, and the subpart resources will be specified under that name in the resource hierarchy. Most widgets will want to allow the user to set the values of subpart resources from application code as well. One way to do this is to call \f(CWXtSetSubvalues()\fP from within the widget's \f(CWset_values()\fP method, passing the subpart resource list and the user's argument list. (Prior to Release 4, you had to use the \f(CWset_values_hook()\fP method for this purpose.) With this approach, subpart resources seem just like normal widget resources to the user; both types of resources can be set by calling \f(CWXtSetValues()\fP. Another approach is to provide a special function .ne 2 (which will use \f(CWXtSetSubvalues()\fP) to set values of your subpart. This approach emphasizes that the subpart is a distinct component of the widget. .LP Note that a more flexible alternative to subparts is to use non-widget objects which the user can create as children of your widget. This way the user has a handle on the "subparts" and can manipulate them directly. .LP To get the values of named resources from a subpart, use \f(CWXtGetSubvalues()\fP. .LP To set resource values in a subpart structure using a \f(CWNULL\fP-terminated variable-length argument list instead of an \f(CWArgList\fP, use \f(CWXtVaSetSubvalues()\fP. .\" .SH "Structures" \f(CWXtResource\fR is defined as follows: .Ps .ps 8 typedef struct _XtResource { String resource_name; /* Resource name */ String resource_class; /* Resource class */ String resource_type; /* Representation type desired */ Cardinal resource_size; /* Size in bytes of representation */ Cardinal resource_offset;/* Offset from base to put resource value */ String default_type; /* Representation type of specified default */ XtPointer default_addr; /* Address of resource default value */ } XtResource, *XtResourceList; .ps .Pe See \f(CWXtGetApplicationResources()\fP for an explanation of the fields of this structure. .LP \f(CWArg\fR are defined as follows: .Ps .ta 4.5n 2i typedef struct { String name; XtArgVal value; } Arg, *ArgList; .Pe .SH "See Also" .na \s-1\fIXtGetApplicationResources\fR\s+1\*(s1, \s-1\fIXtGetSubresources\fR\s+1\*(s1, \s-1\fIXtGetSubvalues\fR\s+1\*(s1, .br \s-1\fIset_values\fR\s+1\*(s4. .ad .XE "resources: resource list; copying" .XE "XtSetSubvalues" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetTypeConverter" "Xt \- Resource Management" .SH "Name" .XX "XtSetTypeConverter" .Na XtSetTypeConverter \- register a "new-style" type converter for all application contexts in a process. .Nz .SH "Synopsis" .Sy void XtSetTypeConverter(\f(CIfrom_type\fP, \f(CIto_type\fP, \f(CIconverter\fP, \f(CIconvert_args\fP, \f(CInum_args\fP, \f(CIcache_type\fP, \f(CIdestructor\fP) .As String \f(CIfrom_type\fP, \f(CIto_type\fP; XtTypeConverter \f(CIconverter\fP; XtConvertArgList \f(CIconvert_args\fP; Cardinal \f(CInum_args\fP; XtCacheType \f(CIcache_type\fP; XtDestructor \f(CIdestructor\fP; .Ae .SS "Inputs" .IP \f(CIfrom_type\fP 1i Specifies the source type. .IP \f(CIto_type\fP 1i Specifies the destination type. .IP \f(CIconverter\fP 1i Specifies the resource type converter procedure. .IP \f(CIconvert_args\fP 1i Specifies additional conversion arguments, or \f(CWNULL\fR. .IP \f(CInum_args\fP 1i Specifies the count of additional conversion arguments, or zero. .IP \f(CIcache_type\fP 1i Specifies whether or not resources produced by this converter are sharable or display-specific and when they should be freed. .IP \f(CIdestructor\fP 1i Specifies a destroy procedure for resources produced by this conversion, or \f(CWNULL\fR if no additional action is required to deallocate resources produced by converter. .\" .SH "Description" \f(CWXtSetTypeConverter()\fR registers \f(CIconverter\fP in all application contexts as a "new-style" resource converter to convert data of resource type \f(CIfrom_type\fP to resource type \f(CIto_type\fP. The \f(CIconvert_args\fP array describes a list of additional arguments that will be computed and passed to the converter when it is invoked. \f(CIcache_type\fP specifies how converted values should be cached, and \f(CIdestructor\fP optionally specifies a procedure to be called to free up resources when a cached value is no longer needed. .LP \f(CWXtSetTypeConverter()\fP is identical to \f(CWXtAppSetTypeConverter()\fP except that it registers the converter in all current application contexts, and all future application contexts. (In particular, note that \f(CWXtAppSetTypeConverter()\fP does not supersede \f(CWXtSetTypeConverter()\fP as is the case with many other \f(CWXtApp\fP functions.) For more information about the arguments and usage of this function, see \f(CWXtAppSetTypeConverter()\fP. .\" .Nd 10 .SH "Structures" The \f(CWXtConvertArgRec\fP structure is defined as follows: .Ps .TA .5i 2.5i .ta .5i 2.5i typedef enum { /* address mode parameter representation */ XtAddress, /* address */ XtBaseOffset, /* offset */ XtImmediate, /* constant */ XtResourceString, /* resource name string */ XtResourceQuark, /* resource name quark */ XtWidgetBaseOffset, /* offset */ XtProcedureArg /* procedure to call */ } XtAddressMode; typedef struct { XtAddressMode address_mode; XtPointer address_id; Cardinal size; } XtConvertArgRec, *XtConvertArgList; .Pe The \f(CWXtCacheType\fP and its legal values are defined as follows: .Ps typedef int XtCacheType; #define XtCacheNone 0x001 #define XtCacheAll 0x002 #define XtCacheByDisplay 0x003 #define XtCacheRefCount 0x100 .Pe See \f(CWXtAppSetTypeConverter()\fP for an explanation of each of the fields and values of these types. .SH "See Also" .na \s-1\fIXtAppSetTypeConverter\fR\s+1\*(s1, \s-1\fIXtCallConverter\fR\s+1\*(s1, \s-1\fIXtConvertAndStore\fR\s+1\*(s1, .br \s-1\fIXtDestructor\fR\s+1\*(s2, \s-1\fIXtTypeConverter\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetValues" "Xt \- Resource Management" .SH "Name" .Na XtSetValues \- set widget resources from an argument list. .XS "resources: copying; XtSetValues" .XN "set_values method: (see also XtSetValues)" .Nz .XS "XtSetValues" .SH "Synopsis" .Sy void XtSetValues(\f(CIobject\fP, \f(CIargs\fP, \f(CInum_args\fP) .As Widget \f(CIobject\fP; ArgList \f(CIargs\fP; Cardinal \f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object whose resources are to be modified; may be of class Object or any subclass thereof. .IP \f(CIargs\fP 1i Specifies an array of name/value pairs that name the resources to be set and specify their new values. .IP \f(CInum_args\fP 1i Specifies the number of elements in \f(CIargs\fP. .\" .SH "Description" \f(CWXtSetValues()\fR sets the resources of \f(CIobject\fP named in \f(CIargs\fP to the values specified in \f(CIargs\fP. Once these values are copied from \f(CIargs\fP into the widget, the widget's \f(CWset_values()\fP methods are called which gives the widget an opportunity to check the new values for consistency, update private widget fields to reflect the new state of the resources, or even to undo some of the changes. The "Background" section below explains the details of this\p process. .\" .SH "Usage" \f(CWXtSetValues()\fP is the primary way for a user to modify widget resources of a widget once that widget has been created. See \f(CWXtSetArg()\fP for information on setting resource names and values into an \f(CWArgList\fP. .LP To set resources specified in a \f(CWNULL\fP-terminated variable-length argument list rather than an \f(CWArgList\fP, use \f(CWXtVaSetValues()\fP. This is often a more convenient function to use because it does not require you to initialize an \f(CWArgList\fP array. .LP Note that not all widget resources may be set with \f(CWXtSetValues()\fP. Some may only be set when a widget is created, and others should be treated as read-only resources. The documentation for the particular widget should indicate which resources are not settable with \f(CWXtSetValues()\fP. .LP To query the values of named resources, use \f(CWXtGetValues()\fP or \f(CWXtVaGetValues()\fP. .\" .SH "Example" You can use \f(CWXtSetValues()\fP as follows to set widget resources: .Ps Arg args[10]; int i; XFontStruct *bold_font; Pixel bright_red; /* * set up an argument list, assuming we've already obtained * the font and the color from somewhere else. */ i = 0; XtSetArg(args[i], XtNlabel, "Quit"); i++; XtSetArg(args[i], XtNfont, bold_font); i++; XtSetArg(args[i], XtNforeground, bright_red); i++; /* set the values */ XtSetValues(s, args, i); .Pe .\" .SH "Background" \f(CWXtSetValues()\fP starts with the resources specified for the Object class fields and proceeds down the subclass chain to the object. At each stage, it replaces the \f(CIobject\fP resource fields with any values specified in the argument list. \f(CWXtSetValues()\fP then calls the \f(CWset_values()\fP methods for the object in superclass-to-subclass order. If the object has any non-NULL \f(CWset_values_hook()\fP methods, these are called immediately after the corresponding \f(CWset_values()\fP method. This procedure permits subclasses to set subpart data via \f(CWXtSetValues()\fP. (Note, though, that as of Release 4, this can be done directly from the \f(CWset_values()\fP method.) .LP If the class of the object's parent is a subclass of \f(CWconstraintWidgetClass\fP, \f(CWXtSetValues()\fP also updates the object's constraints. It starts with the constraint resources specified for \f(CWconstraintWidgetClass\fP and proceeds down the subclass chain to the parent's class. At each stage, it replaces the constraint resource fields with any values specified in the argument list. It then calls the constraint \f(CWset_values()\fP methods from \f(CWconstraintWidgetClass\fP down to the parent's class. The constraint \f(CWset_values()\fP methods are called with widget arguments, as for all \f(CWset_values()\fP methods, not just the constraint records, so that they can make adjustments to the desired values based on full information about the widget. Any arguments specified that do not match a resource list entry are silently ignored. .LP If the object is of a subclass of RectObj, \f(CWXtSetValues()\fP determines if a geometry request is needed by comparing the old object to the new object. If any geometry changes are required, \f(CWXtSetValues()\fP restores the original geometry and makes the request on behalf of the widget. If the geometry manager returns \f(CWXtGeometryYes\fP, \f(CWXtSetValues()\fP calls the object's \f(CWresize()\fP method. If the geometry manager returns \f(CWXtGeometryDone\fP, \f(CWXtSetValues()\fP continues, as the object's resize procedure should have been called by the geometry manager. If the geometry manager returns \f(CWXtGeometryNo\fP, \f(CWXtSetValues()\fP ignores the geometry request and continues. If the geometry manager returns \f(CWXtGeometryAlmost\fP, \f(CWXtSetValues()\fP calls the \f(CWset_values_almost()\fP method, which determines what should be done. \f(CWXtSetValues()\fP then repeats this process, deciding once more whether the geometry manager should be called. .LP Finally, if any of the \f(CWset_values()\fP methods returned \f(CWTrue\fP, and the widget is realized, \f(CWXtSetValues()\fP causes the widget's expose procedure to be invoked by calling \f(CWXClearArea()\fP on the widget's window. .\" .SH "Structures" \f(CWArg\fR is defined as follows: .Ps .ta 4.5n 2i typedef struct { String name; XtArgVal value; } Arg, *ArgList; .Pe .SH "See Also" .na \s-1\fIXtGetValues\fR\s+1\*(s1, \s-1\fIXtSetArg\fR\s+1\*(s1, \s-1\fIXtVaGetValues\fR\s+1\*(s1, \s-1\fIXtVaSetValues\fR\s+1\*(s1, .br \s-1\fIset_values\fR\s+1\*(s4, \s-1\fIset_values_almost\fR\s+1\*(s4, \s-1\fIset_values_hook\fR\s+1\*(s4. .ad .XE "resources: copying; XtSetValues" .XE "XtSetValues" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetValuesFunc" "Xt \- Widget Method Prototypes" .SH "Name" .Na XtSetValuesFunc \- interface definition for the \f(CWset_values()\fP methods. .Nz .XX "XtSetValuesFunc" .SH "Synopsis" .Sy typedef Boolean (*XtSetValuesFunc)(Widget, Widget, Widget, ArgList, .br Cardinal *); .As Widget \f(CIcurrent\fP; Widget \f(CIrequest\fP; Widget \f(CIset\fP; ArgList \f(CIargs\fP; Cardinal *\f(CInum-args\fP; .Ae .SS "Inputs" .IP \f(CIcurrent\fP 1i Specifies a copy of the widget as it was before the \f(CWXtSetValues()\fR call. .IP \f(CIrequest\fP 1i Specifies a copy of the widget with all values changed as asked for by the \f(CWXtSetValues()\fR call before any class \f(CWset_values()\fR procedures have been called. .IP \f(CIset\fP 1i Specifies the widget as modified by all previous called \f(CWset_values()\fP procedures. .IP \f(CIargs\fP 1i Specifies the argument list passed to \f(CWXtSetValues()\fR. .IP \f(CInum_args\fR 1i Specifies the number of arguments in the argument list. .SS "Returns" \f(CWTrue\fP if the widget should be redrawn, \f(CWFalse\fP otherwise. .\" .SH "Description" \f(CWXtSetValuesFunc\fP is the type of the Object, RectObj, and Core \f(CWset_values()\fP method, and of the Constraint \f(CWset_values()\fP method. See those reference pages in Section 4 for more information. .\" .SH "See Also" .na \s-1\fIset_values\fR\s+1\*(s4, \s-1\fIConstraint set_values\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtManageChi 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtSetValues@XtSetValueA .sp .5 XtSetValuesFunc@XtSetValueB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetWMColormapWindows" "Xt \- Properties" .SH "Name" .XX "XtSetWMColormapWindows" .Na XtSetWMColormapWindows \- set \s-1WM_COLORMAP_WINDOWS\s+1 property to inform window manager of custom colormaps. .Nz .SH "Synopsis" .Sy void XtSetWMColormapWindows(\f(CIwidget\fP, \f(CIlist\fP, \f(CIcount\fP) .As Widget \f(CIwidget\fP; Widget* \f(CIlist\fP; Cardinal \f(CIcount\fP; .Ae .SS "Inputs" .IP \f(CIwidget\fP 1i Specifies the widget on whose window the \s-1WM_COLORMAP_WINDOWS\s+1 property will be stored. Must be of class Core or any subclass thereof. .IP \f(CIlist\fP 1i Specifies a list of widgets whose windows are to be listed in the \s-1WM_COLORMAP_WINDOWS\s+1 property. .IP \f(CIcount\fP 1i Specifies the number of widgets in list. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtSetWMColormapWindows()\fR returns immediately if \f(CIwidget\fP is not realized or if \f(CIcount\fP is 0. Otherwise, \f(CWXtSetWMColormapWindows()\fR constructs an ordered list of windows by examining each widget in the list in turn and: .IP \(bu 3n Ignoring the widget if it is not realized or .IP \(bu 3n Adding the widget's window to the window list if the widget is realized and if its colormap resource differs from the colormap resources of all widgets whose windows are already on the window list. .LP Finally, \f(CWXtSetWMColormapWindows()\fR stores the resulting window list in the \s-1WM_COLORMAP_WINDOWS\s+1 property on the specified widget's window. This tells the window manager which windows have a custom colormap, so that the window manager can install these colormaps at the appropriate time. .LP See section 4.1.8 of the \fIInter-Client Communications Conventions Manual\fP for details on the meaning of the \s-1WM_COLORMAP_WINDOWS\s+1 property. .\" .SH "Usage" Only applications that make sophisticated use of color and use multiple colormaps will ever need to call this function. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetWarningHandler" "Xt \- Error Handling" .SH "Name" .Na XtSetWarningHandler \- set the low-level warning handler procedure. .Nz .XX "XtSetWarningHandler" .SH "Synopsis" .Sy void XtSetWarningHandler(\f(CIhandler\fP) .As XtErrorHandler \f(CIhandler\fP; .Ae .SS "Inputs" .IP \f(CIhandler\fP 1i Specifies the new low-level warning procedure. .\" .SH "Availability" \f(CWXtSetWarningHandler()\fP has been superseded by \f(CWXtAppSetWarningHandler()\fP. .\" .SH "Description" \f(CWXtSetWarningHandler()\fP registers the procedure \f(CIhandler\fP as the procedure to be invoked by \f(CWXtWarning()\fP. It should display the string it is passed and return. .\" .SH "Usage" \f(CWXtSetWarningHandler()\fP has been superseded by \f(CWXtAppSetWarningHandler()\fP, which performs the same function on a per-application context basis. \f(CWXtSetWarningHandler()\fP now calls \f(CWXtAppSetWarningHandler()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtSetWarningHandler()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppSetWarningHandler()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppSetWarningHandler()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtAppSetErrorHandler\fR\s+1\*(s1, \s-1\fIXtAppSetErrorMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppWarning\fR\s+1\*(s1, .br \s-1\fIXtErrorHandler\fR\s+1\*(s2, \s-1\fIXtErrorMsgHandler\fR\s+1\*(s2. .ad .\"for a description of the parameters .\"passed to the error handler. .\"performs an analogous function for fatal errors. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSetWarningMsgHandler" "Xt \- Error Handling" .SH "Name" .Na XtSetWarningMsgHandler \- set the high-level warning handler procedure. .Nz .XX "XtSetWarningMsgHandler" .SH "Synopsis" .Sy void XtSetWarningMsgHandler(\f(CImsg_handler\fP) .As XtErrorMsgHandler \f(CImsg_handler\fP; .Ae .SS "Inputs" .IP \f(CImsg_handler\fP 1i Specifies the new high-level nonfatal error procedure. .\" .SH "Availability" \f(CWXtSetWarningMsgHandler()\fP has been superseded by \f(CWXtAppSetWarningMsgHandler()\fP. .\" .SH "Description" \f(CWXtSetWarningMsgHandler()\fP registers the procedure \f(CImsg_handler\fP as the procedure to be invoked by \f(CWXtWarningMsg()\fP. .\" .SH "Usage" \f(CWXtSetWarningMsgHandler()\fP has been superseded by \f(CWXtAppSetWarningMsgHandler()\fP, which performs the same function on a per-application context basis. \f(CWXtSetWarningMsgHandler()\fP now calls \f(CWXtAppSetWarningMsgHandler()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtSetWarningMsgHandler()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppSetWarningMsgHandler()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppSetWarningMsgHandler()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtAppSetErrorHandler\fR\s+1\*(s1, \s-1\fIXtAppSetErrorMsgHandler\fR\s+1\*(s1, \s-1\fIXtAppSetWarningHandler\fR\s+1\*(s1, \s-1\fIXtAppWarningMsg\fR\s+1\*(s1, .br \s-1\fIXtErrorMsgHandler\fR\s+1\*(s2. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtSetWarnin 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtSetWarningHandler@XtSetWarniA .sp .5 XtSetWarningMsgHandler@XtSetWarniB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtStringConversionWarning" "Xt \- Error Handling" .SH "Name" .Na XtStringConversionWarning \- emit boilerplate string conversion error message. .XX "errors: string conversion error message" .XX "strings: error message (XtStringConversionWarning)" .XX "XtStringConversionWarning" .SH "Synopsis" .Sy void XtStringConversionWarning(\f(CIsrc\fP, \f(CIdst_type\fP) .As String \f(CIsrc\fP, \f(CIdst_type\fP; .Ae .SS "Inputs" .IP \f(CIsrc\fP 1i Specifies the string that could not be converted. .IP \f(CIdst_type\fP 1i Specifies the name of the type to which the string could not be converted. .SH "Description" \f(CWXtStringConversionWarning()\fR is a convenience routine for use in old-style resource converters that convert from strings. It issues a warning message with the name \f(CWconversionError\fP, type \f(CWstring\fP, class \f(CWXtToolkitError\fP, and default message string: .Ps "Cannot convert \f(CIsrc\fP to type \f(CIdst_type\fR" .Pe It can be used by a conversion routine to announce a nonfatal conversion error. .SH "Usage" New-style resource converters should call \f(CWXtDisplayStringConversionWarning()\fP instead of \f(CWXtStringConversionWarning()\fP to display their conversion warning messages. These functions display similar messages and differ only in that \f(CWXtDisplayStringConversionWarning()\fP is passed a display pointer as its first argument. .LP Old-style converters are not passed a display pointer, and so must use the old function \f(CWXtStringConversionWarning()\fP which does not require one. .SH "See Also" .na \s-1\fIXtDisplayStringConversionWarning\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtStringProc" "Xt \- Widget Method Prototypes" .SH "Name" .Na XtStringProc \- interface definition for the \f(CWdisplay_accelerator()\fP method. .Nz .XX "XtStringProc" .SH "Synopsis" .Sy typedef void (*XtStringProc)(Widget, String) .As Widget \f(CIw\fP; String \f(CIstring\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the source widget that supplied the accelerators. .IP \f(CIstring\fP 1i Provides the string representation of the accelerators currently registered for the widget. .\" .SH "Description" \f(CWXtStringProc\fP is the type of the Core \f(CWdisplay_accelerator()\fP method. See \f(CWdisplay_accelerator\fP(4) for more information. .\" .SH "See Also" .na \s-1\fIdisplay_accelerator\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtSuperclass" "Xt \- Object Information" .SH "Name" .Na XtSuperclass \- obtain a widget's superclass. .XX "widgets: superclass; XtSuperclass" .Nz .XX "XtSuperclass" .SH "Synopsis" .Sy WidgetClass XtSuperclass(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object whose superclass is to be returned; may be of class Object or any subclass thereof. .SS "Returns" The superclass of \f(CIobject\fP. .\" .SH "Description" \f(CWXtSuperclass()\fR returns a pointer to the class structure of the widget's superclass. .SH "Usage" \f(CWXtSuperclass()\fP is implemented as a function when called from application code, but is replaced by a more efficient macro when called from widget code that includes the file \fI\fP. .\" .SH "See Also" .na \s-1\fIXtCheckSubclass\fR\s+1\*(s1, \s-1\fIXtClass\fR\s+1\*(s1, \s-1\fIXtIsSubclass\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtTimerCallbackProc" "Xt \- Event Handling" .SH "Name" .Na XtTimerCallbackProc \- interface definition for procedure invoked when timeouts expire. .Nz .XX "timeouts, callback method" .XX "callbacks: (see also XtTimerCallbackProc)" .XX "timeouts, XtTimerCallbackProc" .XX "XtTimerCallbackProc" .SH "Synopsis" .Sy typedef void (*XtTimerCallbackProc)(XtPointer, XtIntervalId *); .As XtPointer \f(CIclient_data\fP; XtIntervalId *\f(CIid\fP; .Ae .SS "Inputs" .IP \f(CIclient_data\fP 1i Specifies the data that was registered with this procedure. .IP \f(CIid\fP 1i Specifies the ID returned when this procedure was registered. .\" .SH "Description" An \f(CWXtTimerCallbackProc\fR is registered in a call to \f(CWXtAppAddTimeOut()\fP, and is invoked when the specified number of milliseconds elapse. The \f(CIclient_data\fP argument is data registered with the procedure in the call to \f(CWXtAppAddTimeOut()\fP, and the \f(CIid\fP argument is the value returned by that function. .LP A timer callback is called once, and then is automatically removed. If you want a callback to be called repeatedly, re-register the callback each time it is called, .\" .SH "Example" The following \f(CWXtTimerCallbackProc\fP is from the \fIxmh\fP program. It re-registers itself so that it will be called repeatedly. Note that it uses its \f(CIclient_data\fP argument to supply the application context so that it can re-register itself. .Ps /*ARGSUSED*/ static void NeedToCheckScans(client_data, id) XtPointer client_data; XtIntervalId *id; /* unused */ { int i; if (!subProcessRunning) { DEBUG("[magic toc check ...") for (i = 0; i < numScrns; i++) { if (scrnList[i]->toc) TocRecheckValidity(scrnList[i]->toc); if (scrnList[i]->msg) TocRecheckValidity(MsgGetToc(scrnList[i]->msg)); } DEBUG(" done]\n") } (void) XtAppAddTimeOut((XtAppContext)client_data, (unsigned long) app_resources.rescan_interval, NeedToCheckScans, client_data); } .Pe .bp This procedure is initially registered with the following code: .Ps if (app_resources.rescan_interval > 0) { app_resources.rescan_interval *= 60000; (void) XtAppAddTimeOut(appCtx, (unsigned long) app_resources.rescan_interval, NeedToCheckScans, (XtPointer)appCtx); } .Pe .\" .SH "See Also" .na \s-1\fIXtAppAddTimeOut\fR\s+1\*(s1, \s-1\fIXtRemoveTimeOut\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtToolkitInitialize" "Xt \- Application Contexts" .SH "Name" .Na XtToolkitInitialize \- initialize the X Toolkit internals. .XX "initialization, XtToolkitInitialize" .Nz .XX "XtToolkitInitialize" .SH "Synopsis" .Sy void XtToolkitInitialize() .As .Ae .\".SS "Inputs" .SH "Description" \f(CWXtToolkitInitialize()\fR initializes internal Toolkit data structures. It does not set up an application context or open a display. .LP \f(CWXtAppInitialize()\fR calls \f(CWXtToolkitInitialize()\fR in the course of its initialization. Programs too sophisticated to use \f(CWXtAppInitialize()\fR (such as those that create multiple application contexts) may want to call \f(CWXtToolkitInitialize()\fR explicitly. .LP The semantics of calling \f(CWXtToolkitInitialize()\fR more than once are undefined. .SH "See Also" .na .\"Section 1.1, "Widget Lifecycle," .\".br \s-1\fIXtAppInitialize\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtTranslateCoords" "Xt \- Window Manipulation" .SH "Name" .Na XtTranslateCoords \- translate an x-y coordinate pair from widget coordinates to root coordinates. .XX "widgets: translating; XtTranslateCoords" .Nz .XX "XtTranslateCoords" .SH "Synopsis" .Sy void XtTranslateCoords(\f(CIw\fP, \f(CIx\fP, \f(CIy\fP, \f(CIroot_x_return\fP, \f(CIroot_y_return\fP) .As Widget \f(CIw\fP; Position \f(CIx\fP, \f(CIy\fP; Position *\f(CIroot_x_return\fP, *\f(CIroot_y_return\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. .IP "\f(CIx\fP, \f(CIy\fP" 1i Specify x and y coordinates, relative to \f(CIw\fP. .SS "Outputs" .IP "\f(CIroot_x_return\fP, \f(CIroot_y_return\fP" 1i Return the same x and y coordinates, relative to the root window. .\" .SH "Description" \f(CWXtTranslateCoords()\fR transforms the widget-relative coordinates \f(CIx\fP and \f(CIy\fP into coordinates relative to the root window, and returns these transformed coordinates in \f(CIroot_x_return\fP and \f(CIroot_y_return\fP. .LP \f(CWXtTranslateCoords()\fR is similar to the Xlib \f(CWXTranslateCoordinates()\fR function, which also translates window-relative coordinates to display-relative coordinates. But \f(CWXtTranslateCoords()\fR does not usually generate a server request because most of the time the required information is already in the widget's data structures. .\" .SH "Usage" \f(CWXtTranslateCoords()\fP is useful in popping up a popup shell, since it must be explicitly moved from its default location at the upper-left corner of the screen. A typical approach is to pop up dialogs centered over the main application window. .\" .SH "See Also" .na \s-1\fICore\fR\s+1\*(s3. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtTranslateKey" "Xt \- Keyboard Handling" .SH "Name" .Na XtTranslateKey \- the default keycode-to-keysym translator. .XS "keycodes: translating; keycode-to-keysym" .XS "keycodes: translating; XtTranslateKey" .Nz .XS "XtTranslateKey" .SH "Synopsis" .Sy void XtTranslateKey(\f(CIdisplay\fP, \f(CIkeycode\fP, \f(CImodifiers\fP, .br \f(CImodifiers_return\fP, \f(CIkeysym_return\fP) .As Display *\f(CIdisplay\fP; KeyCode \f(CIkeycode\fP; Modifiers \f(CImodifiers\fP; Modifiers *\f(CImodifiers_return\fP; KeySym *\f(CIkeysym_return\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the display that the keycode is from. .IP \f(CIkeycode\fP 1i Specifies the keycode to translate. .IP \f(CImodifiers\fP 1i Specifies the modifiers to be applied to the keycode. .SS "Outputs" .IP \f(CImodifiers_return\fP 1i Returns the modifiers examined by the key translator. .IP \f(CIkeysym_return\fP 1i Returns the resulting keysym. .SH "Description" \f(CWXtTranslateKey()\fP is the default \f(CWXtKeyProc\fP used by the Translation Manager. It takes a keycode and returns the corresponding keysym, recognizing Shift, Lock, and group modifiers. It handles all the keysyms defined by the X Protocol. .LP \f(CWXtTranslateKey()\fP is provided for two main reasons: so that new translators with expanded functionality can call it to get default keycode-to-keysym translations in addition to whatever they add, and so that the default translator can be reinstalled. .LP See \f(CWXtKeyProc\fP(2) for more information on the behavior of this and all key translator procedures. .\" .SH "Usage" The Translation Manager invokes the currently registered key translator procedure to convert incoming keycodes to keysyms. Only clients that need to work with non-standard keysyms should need to register alternate key translator procedures. .LP \f(CWXtTranslateKey()\fP can be invoked directly, or the currently registered key translator can be invoked by calling \f(CWXtTranslateKeycode()\fP. A new translator can be registered by calling \f(CWXtSetKeyTranslator()\fP. There is no way to remove a translator; to reinstall the default behavior, call \f(CWXtSetKeyTranslator()\fP with \f(CWXtTranslateKey()\fP as the \f(CIproc\fP argument. .\" .Nd 5 .SH "Structures" The \f(CWKeyCode\fP and \f(CWKeySym\fP types are defined as follows: .Ps typedef unsigned char KeyCode; typedef XID KeySym; .Pe The \f(CWModifiers\fP type and its legal values are defined as follows: .Ps typedef unsigned int Modifiers; #define ShiftMask (1<<0) #define LockMask (1<<1) #define ControlMask (1<<2) #define Mod1Mask (1<<3) #define Mod2Mask (1<<4) #define Mod3Mask (1<<5) #define Mod4Mask (1<<6) #define Mod5Mask (1<<7) .Pe .SH "See Also" .na \s-1\fIXtRegisterCaseConverter\fR\s+1\*(s1, \s-1\fIXtSetKeyTranslator\fR\s+1\*(s1, \s-1\fIXtTranslateKeycode\fR\s+1\*(s1, .br \s-1\fIXtKeyProc\fR\s+1\*(s2. .ad .XE "keycodes: translating; keycode-to-keysym" .XE "keycodes: translating; XtTranslateKey" .XE "XtTranslateKey" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtTranslateKeycode" "Xt \- Keyboard Handling" .SH "Name" .Na XtTranslateKeycode \- invoke the currently registered keycode-to-keysym translator. .XS "keycodes: translating; keycode-to-keysym" .XS "keycodes: translating; XtTranslateKeycode" .Nz .XS "XtTranslateKeycode" .SH "Synopsis" .Sy void XtTranslateKeycode(\f(CIdisplay\fP, \f(CIkeycode\fP, \f(CImodifiers\fP, \f(CImodifiers_return\fP, \f(CIkeysym_return\fP) .As Display *\f(CIdisplay\fP; KeyCode \f(CIkeycode\fP; Modifiers \f(CImodifiers\fP; Modifiers *\f(CImodifiers_return\fP; KeySym *\f(CIkeysym_return\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the display that the keycode is from. .IP \f(CIkeycode\fP 1i Specifies the keycode to translate. .IP \f(CImodifiers\fP 1i Specifies the modifiers to be applied to the keycode. .SS "Outputs" .IP \f(CImodifiers_return\fP 1i Returns a mask that indicates the modifiers actually used to generate the keysym. .IP \f(CIkeysym_return\fP 1i Returns the resulting keysym. .SH "Description" \f(CWXtTranslateKeycode()\fR converts a keycode plus modifiers into a keysym. It invokes the currently registered keycode-to-keysym translator (\f(CWXtTranslateKey()\fP by default) and passes its arguments directly to that converter. .LP See \f(CWXtTranslateKey()\fP for a description of the default translator. See \f(CWXtKeyProc\fP(2) for more details on the operation of a keycode-to-keysym translator procedure. .\" .SH "Usage" The Translation Manager invokes the currently registered key translator procedure to convert incoming keycodes to keysyms. Only clients that need to work with non-standard keysyms should need to register alternate key translator procedures. .LP The default key translator, \f(CWXtTranslateKey()\fP, can also be invoked directly. A new translator can be registered by calling \f(CWXtSetKeyTranslator()\fP. .\" .SH "Structures" The \f(CWKeyCode\fP and \f(CWKeySym\fP types are defined as follows: .Ps typedef unsigned char KeyCode; typedef XID KeySym; .Pe The \f(CWModifiers\fP type and its legal values are defined as follows: .Ps typedef unsigned int Modifiers; #define ShiftMask (1<<0) #define LockMask (1<<1) #define ControlMask (1<<2) #define Mod1Mask (1<<3) #define Mod2Mask (1<<4) #define Mod3Mask (1<<5) #define Mod4Mask (1<<6) #define Mod5Mask (1<<7) .Pe .\" .SH "See Also" .na \s-1\fIXtRegisterCaseConverter\fR\s+1\*(s1, \s-1\fIXtSetKeyTranslator\fR\s+1\*(s1, \s-1\fIXtTranslateKey\fR\s+1\*(s1, .br \s-1\fIXtKeyProc\fR\s+1\*(s2. .ad .XE "keycodes: translating; keycode-to-keysym" .XE "keycodes: translating; XtTranslateKeycode" .XE "XtTranslateKeycode" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtTranslate 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtTranslateCoords@XtTranslatA .sp .5 XtTranslateKey@XtTranslatB .sp .5 XtTranslateKeycode@XtTranslatC .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtTypeConverter" "Xt \- Resource Management" .SH "Name" .Na XtTypeConverter \- interface definition for a new-style resource converter. .Nz .XS "XtTypeConverter" .XS "resources: resource conversion; XtTypeConverter" .SH "Synopsis" .Sy typedef Boolean (*XtTypeConverter)(Display *, XrmValue *, Cardinal *, .br XrmValue *, XrmValue *, XtPointer *); .As Display *\f(CIdisplay\fP; XrmValue *\f(CIargs\fP; Cardinal *\f(CInum_args\fP; XrmValue *\f(CIfrom\fP; XrmValue *\f(CIto_in_out\fP; XtPointer *\f(CIconverter_data\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the Display connection with which this conversion is associated. .IP \f(CIargs\fP 1i Specifies a list of additional \f(CWXrmValue\fR arguments to the converter, or \f(CWNULL\fR. .IP \f(CInum_args\fP 1i Specifies the number of arguments in \f(CIargs\fP. .IP \f(CIfrom\fP 1i Specifies the address and size of the value to convert. .IP \f(CIto_in_out\fP 1i Specifies the address at which the converted value is to be stored, or \f(CWNULL\fP, and the number of bytes allocated for the value at that address. .SS "Outputs" .IP \f(CIto_in_out\fP 1i Returns the address at which the converted value was stored, and the actual number of bytes occupied by that value. .IP \f(CIconverter_data\fP 1i Returns arbitrary data which will be passed to the destructor procedure, if any, associated with this converter when the converted resource is freed from the resource cache. .SS "Returns" \f(CWTrue\fP if the conversion was successful; \f(CWFalse\fP otherwise. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" An \f(CWXtTypeConverter\fP is a "new-style" resource converter registered with \f(CWXtAppSetTypeConverter()\fP or \f(CWXtSetTypeConverter()\fP. It is invoked by the Intrinsics to convert resource values between the types for which it is registered, or can be invoked explicitly with \f(CWXtConvertAndStore()\fP or \f(CWXtCallConverter()\fP. .LP An \f(CWXtTypeConverter\fP should convert the value pointed to by \f(CIfrom\f(CW->addr\fR (which is \f(CIfrom\f(CW->size\fR bytes long) into the appropriate type and store the converted value at \f(CIto_in_out\f(CW->addr\fR. If this pointer is \f(CWNULL\fR, the converter should store the converted value in its own storage and place the size and address of this storage into \f(CIto_in_out\fP. This memory remains under the ownership of the converter and must not be modified by the caller. The type converter is permitted to use static storage for this purpose and therefore the caller must immediately copy the data upon return from the converter. .LP If \f(CIto_in_out\f(CW->addr\fR is not \f(CWNULL\fR, the converter must check the \f(CWsize\fP field to insure that sufficient space has been allocated before storing the converted value. .IP \(bu 3n If insufficient space is specified, the converter should update the \f(CWsize\fP field to indicate number of bytes required and should return \f(CWFalse\fR without modifying the data pointed to by the \f(CWaddr\fP field. .IP \(bu If sufficient space was allocated by the caller, the converter should store the converted value at the location pointed to by the \f(CIaddr\fP field and set the \f(CWsize\fP field to the number of bytes actually occupied by the converted value. .LP For converted values of type \f(CWXtRString\fR, the size should include the \f(CWNULL\fR-terminating byte, if any. .LP The converter may return any value it wishes in \f(CIconverter_data\fR; this data is similar to the \f(CIclient_data\fP argument to a callback and will be passed to the destructor, if any, associated with this converter when the resource value is freed by the Intrinsics. See \f(CWXtDestructor\fP(2) for more information. .LP The \f(CIargs\fP argument is an array of values (such as a Screen pointer or Colormap ID) that the converter may need to perform the conversion. The contents and interpretation of this array are determined by the \f(CWXtConvertArgList\fP array supplied when the converter is registered. The Intrinsics use the \f(CWXtConvertArgList\fP to compute an array of \f(CWXrmValue\fP to pass to the converter each time it is invoked. An \f(CWXtTypeConverter\fP that expects values in its \f(CWargs\fP argument must be registered with a suitable \f(CWXtConvertArgList\fP or it will not work correctly. See \f(CWXtAppSetTypeConverter()\fP for information on declaring \f(CWXtConvertArgList\fP arrays. .LP The \f(CIdisplay\fR argument to an \f(CWXtTypeConverter\fP may be used by some converters in the conversion process, and is also needed to obtain the application context (with the function \f(CWXtDisplayToApplicationContext()\fR) in order to report warning messages. Note that one of the primary differences between "new-style" and "old-style" converters is that new-style converters have this \f(CIdisplay\fP argument. .LP An \f(CWXtTypeConverter\fP should return \f(CWTrue\fP if the conversion was successful and return \f(CWFalse\fP otherwise. If the conversion cannot be performed due to an improper source value, a warning message should be issued with \f(CWXtAppWarningMsg()\fP or \f(CWXtDisplayStringConversionWarning()\fP. .\" .SH "Usage" Note that the \f(CInum_args\fP argument is a pointer to the number of elements in \f(CIargs\fP, and not the number of arguments itself. Be sure to dereference this argument correctly before using it. .LP An \f(CWXtTypeConverter\fP must check both the \f(CWaddr\fP and \f(CWsize\fP fields of its \f(CIto_in_out\fP argument, and be prepared to return the converted value in different ways depending on the values in these fields. To encapsulate all the requirements for returning a converted value, the standard converters defined by the Intrinsics all call a macro named \f(CWdone()\fP which is passed the .ne 6 converted value and returns it in the correct way depending on the \f(CIto_in_out\fP argument. This \f(CWdone()\fP macro is shown in the example below. .LP All type converters should define some set of values for which they are guaranteed to succeed, so that these values can be used as widget and application resource defaults. For some string converters, this may mean defining a string value which will be handled specially by the converter. It is useful if you give this string a symbolic name. The special constants \f(CWXtDefaultFont\fP, \f(CWXtDefaultForeground\fP, and \f(CWXtDefaultBackground\fP are strings of this type which are specially recognized by their converters. .LP If you write a widget that has a resource which is of some enumerated type, you should write a converter routine which will convert between the symbolic names of each value and the values themselves. This converter should then be registered in your widget's \f(CWclass_initialize()\fP method. .LP If you are writing a programming library or an application that defines non-standard types, it may be useful to provide string converters for those types. This allows resources of that type to be specified from a resource file. An application that supported user-configurable popup menus, for example, might include a String-to-Menu converter. .LP If your converter needs additional arguments to perform the conversion, you should declare and export the \f(CWXtConvertArgList\fP array to be registered with the converter, or at least document the array that must be registered. Since the wrong arguments will likely cause your converter to dump core, you should consider defining the argument list part of the process of writing the converter. Note that there are also two \f(CWXtConvertArgList\fPs predefined by the Intrinsics: \f(CWscreenConvertArg\fR passes the widget's \f(CWscreen\fP field to the converter in \f(CWargs[0]\fR, and \f(CWcolorConvertArgs\fR passes the widget's \f(CWscreen\fP field to the converter in \f(CWargs[0]\fR and the widget's \f(CWcolormap\fP field in \f(CWargs[1]\fR. .LP A type converter may invoke other converters to aid with its conversion. When converting complex types, this is a good idea because it allows differing source types that convert into a common intermediate type to make maximum use of the type converter cache. .LP The Intrinsics define a number of standard converters which do not need to be registered. See \f(CWXtConvertAndStore()\fP for a list of these predefined converters. There are also a number of other useful converters defined in the Xmu library which do need to be registered explicitly. See \f(CWXmuCvtStringToMisc\fP(6). .\" .SH "Example" The \f(CWdone()\fP macro below is from the X11R5 Intrinsics. It is used to return a converted resource value correctly depending on the \f(CIto_in_out\fP argument (which is here given the name \f(CWtoVal\fP). Note that the \f(CItype\fP argument is used to declare a static variable to store the value in when \f(CIto_in_out\fP (or \f(CWtoVal\fP) does not provide a location to store it. .Ps #define done(type, value) \ { \ if (toVal->addr != NULL) { \ if (toVal->size < sizeof(type)) { \ toVal->size = sizeof(type); \ return False; \ } \ *(type*)(toVal->addr) = (value); \ } \ else { \ static type static_val; \ static_val = (value); \ toVal->addr = (XPointer)&static_val; \ } \ toVal->size = sizeof(type); \ return True; \ } .Pe An \f(CWXtTypeConverter\fP from the X11R5 Intrinsics to convert between a string and a \f(CWPixel\fP is shown below, along with the \f(CWXtConvertArgList\fP that it must be registered with. Note how it checks \f(CInum_args\fP and then determines the screen and colormap from its \f(CIargs\fP argument. Also note that it tests for two special values: the strings with symbolic names \f(CWXtDefaultForeground\fP and \f(CWXtDefaultBackground\fP. It is guaranteed to successfully convert these values. The \f(CWpd\fP variable is an Intrinsics internal structure, and \f(CWpd->rv\fP indicates whether or not the \f(CWreverseVideo\fP application resource is specified in the resource database. .LP This converter returns a \f(CWBoolean\fP in its \f(CIconverter_data\fP argument (called \f(CWclosure_ret\fP here) which indicates to the resource destructor whether or not it should deallocate the color. The pixels associated with \f(CWXtDefaultForeground\fP and XtDefaultBackground are never deallocated. See \f(CWXtDestructor\fP(2) for the destructor procedure that accompanies this converter. .LP Finally, note that this converter uses the \f(CWdone\fP macro five times, which is inefficient because it expands to a large macro. With some simple reorganization, it need only be called once. .Ps \s-2XtConvertArgRec Const colorConvertArgs[] = { {XtWidgetBaseOffset, (XtPointer)XtOffsetOf(WidgetRec, core.screen), sizeof(Screen *)}, {XtWidgetBaseOffset, (XtPointer)XtOffsetOf(WidgetRec, core.colormap), sizeof(Colormap)} }; Boolean XtCvtStringToPixel(dpy, args, num_args, fromVal, toVal, closure_ret) Display* dpy; XrmValuePtr args; Cardinal *num_args; XrmValuePtr fromVal; XrmValuePtr toVal; XtPointer *closure_ret; { String str = (String)fromVal->addr; XColor screenColor; XColor exactColor; Screen *screen; XtPerDisplay pd = _XtGetPerDisplay(dpy); Colormap colormap; Status status; String params[1]; Cardinal num_params=1; if (*num_args != 2) { XtAppWarningMsg(pd->appContext, XtNwrongParameters, "cvtStringToPixel", XtCXtToolkitError, "String to pixel conversion needs screen and colormap arguments", (String *)NULL, (Cardinal *)NULL); return False; } screen = *((Screen **) args[0].addr); colormap = *((Colormap *) args[1].addr); if (CompareISOLatin1(str, XtDefaultBackground) == 0) { *closure_ret = False; if (pd->rv) done(Pixel, BlackPixelOfScreen(screen)) else done(Pixel, WhitePixelOfScreen(screen)); } if (CompareISOLatin1(str, XtDefaultForeground) == 0) { *closure_ret = False; if (pd->rv) done(Pixel, WhitePixelOfScreen(screen)) else done(Pixel, BlackPixelOfScreen(screen)); } status = XAllocNamedColor(DisplayOfScreen(screen), colormap, (char*)str, &screenColor, &exactColor); if (status == 0) { String msg, type; params[0] = str; /* Server returns a specific error code but Xlib discards it. Ugh */ if (XLookupColor(DisplayOfScreen(screen), colormap, (char*)str, &exactColor, &screenColor)) { type = "noColormap"; msg = "Cannot allocate colormap entry for \e"%s\e""; } else { type = "badValue"; msg = "Color name \e"%s\e" is not defined"; } XtAppWarningMsg(pd->appContext, type, "cvtStringToPixel", XtCXtToolkitError, msg, params, &num_params); *closure_ret = False; return False; } else { *closure_ret = (char*)True; done(Pixel, screenColor.pixel); } }\s+2 .Pe .\" .SH "Structures" The \f(CWXrmValue\fP structure is defined as follows: .Ps typedef struct { unsigned int size; XPointer addr; } XrmValue, *XrmValuePtr; .Pe .\" .SH "See Also" .na \s-1\fIXtAppSetTypeConverter\fR\s+1\*(s1, \s-1\fIXtCallConverter\fR\s+1\*(s1, \s-1\fIXtConvertAndStore\fR\s+1\*(s1, \s-1\fIXtDisplayStringConversionWarning\fR\s+1\*(s1, \s-1\fIXtSetTypeConverter\fR\s+1\*(s1, .br \s-1\fIXmuCvtStringToMisc\fR\s+1\*(s6. .ad .XE "XtTypeConverter" .XE "resources: resource conversion; XtTypeConverter" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtUngrabButton" "Xt \- Mouse Handling" .SH "Name" .XX "XtUngrabButton" .Na XtUngrabButton \- cancel a passive button grab. .Nz .SH "Synopsis" .Sy void XtUngrabButton(\f(CIwidget\fP, \f(CIbutton\fP, \f(CImodifiers\fP) .As Widget \f(CIwidget\fP; unsigned int \f(CIbutton\fP; Modifiers \f(CImodifiers\fP; .Ae .SS "Inputs" .IP \f(CIwidget\fP 1i Specifies the widget in whose window the button was grabbed. .IP \f(CIbutton\fP 1i Specifies the mouse button to be ungrabbed. .IP \f(CImodifiers\fP 1i Specifies the modifier keys to be ungrabbed. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtUngrabButton()\fP cancels a passive grab of the specified button/modifiers combination. If \f(CIw\fP is realized, \f(CWXtUngrabButton()\fR calls \f(CWXUngrabButton()\fR specifying the widget's window as the ungrab window, and passing the remaining arguments unmodified. If the widget is not realized, \f(CWXtUngrabButton()\fR removes the deferred \f(CWXtGrabButton()\fR request, if any, for the specified widget, button, and modifiers. .LP The \f(CIbutton\fP argument is one of \f(CWButton1\fP, \f(CWButton2\fP, \f(CWButton3\fP, \f(CWButton4\fP, \f(CWButton5\fP, or the constant \f(CWAnyButton\fP, which is equivalent to issuing the ungrab request for all possible buttons. .LP The \f(CImodifiers\fP argument is a bitwise OR of one or more of the following symbols: \f(CWShiftMask\fP, \f(CWLockMask\fP, \f(CWControlMask\fP, \f(CWMod1Mask\fP, \f(CWMod2Mask\fP, \f(CWMod3Mask\fP, \f(CWMod4Mask\fP, \f(CWMod5Mask\fP. The special value \f(CWAnyModifier\fP is also allowed; using it is equivalent to issuing the ungrab button request for all possible modifier combinations (including no modifiers). .LP \f(CWXtUngrabButton()\fP has no effect on an active grab. .LP See \f(CWXtGrabButton()\fP for more information on passive button grabs. .\" .SH "Usage" You should rarely need to use passive button grabs. An automatic grab takes place between a ButtonPress event and the corresponding ButtonRelease event, so an explicit grab is not necessary in some of the most common situations. It may be necessary for some styles of menus, however. .LP Note that \f(CWXtAddGrab()\fP and spring-loaded popups can be used in place of passive grabs in many circumstances. These do not actually issue any X server grabs. .\" .Nd 5 .SH "Structures" The \f(CWModifiers\fP type is defined as follows: .Ps typedef unsigned int Modifiers; .Pe .\" .SH "See Also" .na \s-1\fIXtAddGrab\fR\s+1\*(s1, \s-1\fIXtGrabButton\fR\s+1\*(s1, \s-1\fIXtGrabKey\fR\s+1\*(s1, \s-1\fIXtGrabKeyboard\fR\s+1\*(s1, \s-1\fIXtGrabPointer\fR\s+1\*(s1, \s-1\fIXtUngrabKey\fR\s+1\*(s1, \s-1\fIXtUngrabKeyboard\fR\s+1\*(s1, \s-1\fIXtUngrabPointer\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtUngrabKey" "Xt \- Keyboard Handling" .SH "Name" .XX "XtUngrabKey" .Na XtUngrabKey \- cancel a passive key grab. .Nz .SH "Synopsis" .Sy void XtUngrabKey(\f(CIwidget\fP, \f(CIkeycode\fP\f(CI, modifiers\fP) .As Widget \f(CIwidget\fP; KeyCode \f(CIkeycode\fP; Modifiers \f(CImodifiers\fP; .Ae .SS "Inputs" .IP \f(CIwidget\fP 1i Specifies the widget in whose window the key was grabbed. .IP \f(CIkeycode\fP 1i Specifies the keycode to be ungrabbed. .IP \f(CImodifiers\fP 1i Specifies the modifiers to be ungrabbed. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtUngrabKey()\fP cancels a passive grab on the specified keycode/modifiers combination for widget \f(CIw\fP. If \f(CIw\fP is realized, \f(CWXtUngrabKey()\fR calls \f(CWXUngrabKey()\fR specifying the widget's window as the ungrab window and passing the remaining argument unmodified. If the widget is not realized \f(CWXtUngrabKey()\fR removes the deferred \f(CWXtGrabKey()\fR request, if any, for the specified widget, keycode and modifiers. .LP The \f(CIkeycode\fP argument is the keycode of the key you want to ungrab, or the special value \f(CWAnyKey\fP which is equivalent to issuing the request for all possible nonmodifier key codes. .LP The \f(CImodifiers\fP argument is a bitwise OR of one or more of the following symbols: \f(CWShiftMask\fP, \f(CWLockMask\fP, \f(CWControlMask\fP, \f(CWMod1Mask\fP, \f(CWMod2Mask\fP, \f(CWMod3Mask\fP, \f(CWMod4Mask\fP, \f(CWMod5Mask\fP. The special value \f(CWAnyModifier\fP is also allowed; using it is equivalent to issuing the ungrab button request for all possible modifier combinations (including no modifiers). .LP \f(CWXtUngrabKey()\fP has no effect on an active grab. .LP See \f(CWXtGrabKey()\fP for more details on passive key grabs. .\" .SH "Usage" Most applications will never need to issue a passive grab. \f(CWXtAddGrab()\fP (called by \f(CWXtPopup()\fP) can be used to implement modal popups inside an application, and \f(CWXtSetKeyboardFocus()\fP can be used to redirect keyboard focus within an application. Neither function actually issues a grab, and so does not interrupt event processing by other clients. .\" .SH "Structures" The \f(CWModifiers\fP and \f(CWKeyCode\fP types are defined as follows: .Ps typedef unsigned int Modifiers; typedef unsigned char KeyCode; .Pe .\" .SH "See Also" .na \s-1\fIXtAddGrab\fR\s+1\*(s1, \s-1\fIXtGrabButton\fR\s+1\*(s1, \s-1\fIXtGrabKey\fR\s+1\*(s1, \s-1\fIXtGrabKeyboard\fR\s+1\*(s1, \s-1\fIXtGrabPointer\fR\s+1\*(s1, \s-1\fIXtSetKeyboardFocus\fR\s+1\*(s1, \s-1\fIXtUngrabButton\fR\s+1\*(s1, \s-1\fIXtUngrabKeyboard\fR\s+1\*(s1, \s-1\fIXtUngrabPointer\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtUngrabKeyboard" "Xt \- Keyboard Handling" .SH "Name" .XX "XtUngrabKeyboard" .Na XtUngrabKeyboard \- release an active keyboard grab. .Nz .SH "Synopsis" .Sy void XtUngrabKeyboard(\f(CIwidget\fP, \f(CItime\fP) .As Widget \f(CIwidget\fP; Time \f(CItime\fP; .Ae .SS "Inputs" .IP \f(CIwidget\fP 1i Specifies the widget which has the active keyboard grab. .IP \f(CItime\fP 1i Specifies the time when the grab should end. \f(CWCurrentTime\fP is acceptable. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtUngrabKeyboard()\fR releases an active keyboard grab by calling \f(CWXUngrabKeyboard()\fR, passing the display of \f(CIwidget\fP and \f(CItime\fP. .LP The \f(CItime\fP argument may be a timestamp or the constant \f(CWCurrentTime\fP. If the specified time is earlier than the last-keyboard-grab time or later than the current server time the keyboard will not be ungrabbed. .LP See \f(CWXtGrabKeyboard()\fP for more information about grabbing the keyboard. .\" .SH "Usage" Most applications will never need to issue a grab. \f(CWXtAddGrab()\fP (called by \f(CWXtPopup()\fP) can be used to implement modal popups inside an application, and \f(CWXtSetKeyboardFocus()\fP can be used to redirect keyboard focus within an application. Neither function actually issues a grab, and so does not interrupt event processing by other clients. .\" .SH "See Also" .na \s-1\fIXtAddGrab\fR\s+1\*(s1, \s-1\fIXtGrabButton\fR\s+1\*(s1, \s-1\fIXtGrabKey\fR\s+1\*(s1, \s-1\fIXtGrabKeyboard\fR\s+1\*(s1, \s-1\fIXtGrabPointer\fR\s+1\*(s1, \s-1\fIXtSetKeyboardFocus\fR\s+1\*(s1, \s-1\fIXtUngrabButton\fR\s+1\*(s1, \s-1\fIXtUngrabKey\fR\s+1\*(s1, \s-1\fIXtUngrabPointer\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtUngrabKey 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtUngrabKey@XtUngrabKeA .sp .5 XtUngrabKeyboard@XtUngrabKeB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtUngrabPointer" "Xt \- Mouse Handling" .SH "Name" .XX "XtUngrabPointer" .Na XtUngrabPointer \- release an active pointer grab. .Nz .SH "Synopsis" .Sy void XtUngrabPointer(\f(CIwidget\fP, \f(CItime\fP) .As Widget \f(CIwidget\fP; Time \f(CItime\fP; .Ae .SS "Inputs" .IP \f(CIwidget\fP 1i Specifies the widget which has the active pointer grab. .IP \f(CItime\fP 1i Specifies the time at which the grab should end. \f(CWCurrentTime\fP is acceptable. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtUngrabPointer()\fR releases an active pointer grab by calling \f(CWXUngrabPointer()\fR with the display of \f(CIw\fP and \f(CItime\fP. .LP The \f(CItime\fP argument may be a timestamp or the constant \f(CWCurrentTime\fP. If this time is earlier than the last-keyboard-grab time or later than the current server time the keyboard will not be ungrabbed. .LP See \f(CWXtGrabPointer()\fP for more information on active pointer grabs. .\" .SH "Usage" Most applications will never have to issue a pointer grab. Note that the pointer is automatically grabbed between every button down event and the corresponding button up event; this covers the case for which pointer grabs are most commonly needed. .\" .SH "See Also" .na \s-1\fIXtGrabButton\fR\s+1\*(s1, \s-1\fIXtGrabKey\fR\s+1\*(s1, \s-1\fIXtGrabKeyboard\fR\s+1\*(s1, \s-1\fIXtGrabPointer\fR\s+1\*(s1, \s-1\fIXtSetKeyboardFocus\fR\s+1\*(s1, \s-1\fIXtUngrabButton\fR\s+1\*(s1, \s-1\fIXtUngrabKey\fR\s+1\*(s1, \s-1\fIXtUngrabKeyboard\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtUninstallTranslations" "Xt \- Translations and Actions" .SH "Name" .Na XtUninstallTranslations \- remove all existing translations from a widget. .XX "translations, removing" .XX "translations, XtUninstallTranslations" .Nz .XX "XtUninstallTranslations" .SH "Synopsis" .Sy void XtUninstallTranslations(\f(CIw\fP) .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget from which the translations are to be removed. .\" .SH "Description" \f(CWXtUninstallTranslations()\fR removes a widget's translation table. .\" .SH "Usage" Many widgets will not function correctly without their translations. A widget without translations will not respond to keyboard or mouse events, unless it explicitly registers an event handler for these events. .LP You can completely replace a widget's translations by setting a new translation table on the \f(CWXtNtranslations\fP resource of the widget. You can merge new translations with existing translations with \f(CWXtAugmentTranslations()\fP and \f(CWXtOverrideTranslations()\fP. .\" .SH "See Also" .na \s-1\fIXtAugmentTranslations\fR\s+1\*(s1, \s-1\fIXtOverrideTranslations\fR\s+1\*(s1, \s-1\fIXtParseTranslationTable\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtUnmanageChild" "Xt \- Geometry Management" .SH "Name" .Na XtUnmanageChild \- remove a widget from its parent's managed list. .XX "widgets: removing" .Nz .XX "XtUnmanageChild" .SH "Synopsis" .Sy void XtUnmanageChild(\f(CIw\fP) .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the child widget to be unmanaged; must be of class RectObj or any subclass thereof. .\" .SH "Description" \f(CWXtUnmanageChild()\fP unmaps the specified widget and removes it from its parent's geometry management. The widget will disappear from the screen, and (depending on its parent) may no longer have screen space allocated for it. .LP \f(CWXtUnmanageChild()\fP simply calls \f(CWXtUnmanageChildren()\fP. See that function for more information about the procedure for unmanaging a widget. .\" .SH "Usage" Unmanaging a widget is the usual method for temporarily making it invisible. It can be re-managed with \f(CWXtManageChild()\fP. .LP You can unmap a widget, but leave it under geometry management by calling \f(CWXtUnmapWidget()\fP. You can destroy a widget's window without destroying the widget by calling \f(CWXtUnrealizeWidget()\fP. You can destroy a widget completely with \f(CWXtDestroyWidget()\fP. .LP If you will be unmanaging several sibling widgets, it is more efficient to call \f(CWXtUnmanageChildren()\fP because this only generates a single call to the parent's \f(CWchange_managed()\fP method. It is often more convenient to simply call \f(CWXtUnmanageChild()\fP several times, however. .\" .SH "See Also" .na \s-1\fIXtIsManaged\fR\s+1\*(s1, \s-1\fIXtManageChild\fR\s+1\*(s1, \s-1\fIXtManageChildren\fR\s+1\*(s1, \s-1\fIXtUnmanageChildren\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtUnmanageChildren" "Xt \- Geometry Management" .SH "Name" .Na XtUnmanageChildren \- remove a list of children from a parent widget's managed list. .XX "widgets: removing" .Nz .XX "XtUnmanageChildren" .SH "Synopsis" .Sy void XtUnmanageChildren(\f(CIchildren\fP, \f(CInum_children\fP) .As WidgetList \f(CIchildren\fP; Cardinal \f(CInum_children\fP; .Ae .SS "Inputs" .IP \f(CIchildren\fP 1.1i Specifies an array of child widgets. Each child must be of class RectObj or any subclass thereof. .IP \f(CInum_children\fP Specifies the number of elements in \f(CIchildren\fP. .\" .SH "Description" \f(CWXtUnmanageChildren()\fR unmaps the specified widgets and removes them from their parent's geometry management. The widgets will disappear from the screen, and (depending on its parent) may no longer have screen space allocated for them. .LP Each of the widgets in the \f(CIchildren\fP array must have the same parent. .LP See the "Algorithm" section below for full details of the widget unmanagement procedure. .\" .SH "Usage" Unmanaging widgets is the usual method for temporarily making them invisible. They can be re-managed with \f(CWXtManageChildren()\fP. .LP You can unmap a widget, but leave it under geometry management by calling \f(CWXtUnmapWidget()\fP. You can destroy a widget's window without destroying the widget by calling \f(CWXtUnrealizeWidget()\fP. You can destroy a widget completely with \f(CWXtDestroyWidget()\fP. .LP If you are only going to unmanage a single widget, it is more convenient to call \f(CWXtUnmanageChild()\fP. It is often more convenient to call \f(CWXtUnmanageChild()\fP several times than it is to declare and initialize an array of widgets to pass to \f(CWXtUnmanageChildren()\fP. Calling \f(CWXtUnmanageChildren()\fP is more efficient, however, because it only calls the parent's \f(CWchange_managed()\fP method once. .\" .SH "Algorithm" \f(CWXtUnmanageChildren()\fP performs the following: .IP \(bu 3n Issues an error if the children do not all have the same parent or if the parent is not a subclass of \f(CWcompositeWidgetClass\fP. .IP \(bu 3n Returns immediately if the common parent is being destroyed; otherwise, for each unique child on the list, \f(CWXtUnmanageChildren()\fP performs the following: .RS .IP \- 3 Ignores the child if it already is unmanaged or is being destroyed. .IP \- 3 Otherwise, if the child is realized, it makes it nonvisible by unmapping it. .RE .IP \(bu 3n Calls the \f(CWchange_managed()\fP method of the widgets' parent if the parent is realized. .LP .\" .SH "Structures" The \f(CWWidgetList\fP type is simply an array of widgets: .Ps typedef Widget *WidgetList;\fR .Pe .SH "See Also" .na \s-1\fIXtDestroyWidget\fR\s+1\*(s1, \s-1\fIXtIsManaged\fR\s+1\*(s1, \s-1\fIXtManageChild\fR\s+1\*(s1, \s-1\fIXtManageChildren\fR\s+1\*(s1, \s-1\fIXtUnmanageChild\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH XtUnmanageC 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp XtUnmanageChild@XtUnmanageA .sp .5 XtUnmanageChildren@XtUnmanageB .sp .5 .TE .KE .in .sp 1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtUnmapWidget" "Xt \- Widget Lifecycle" .SH "Name" .Na XtUnmapWidget \- unmap a widget explicitly. .XX "widgets: unmapping" .Nz .XX "XtUnmapWidget" .SH "Synopsis" .Sy XtUnmapWidget(\f(CIw\fP) .As Widget \f(CIw\fP\^; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget to be unmapped; must be of class core or any subclass thereof. .\" .SH "Description" \f(CWXtUnmapWidget()\fR unmaps a widget's window from its display, causing it to become invisible. The widget remains under the geometry management of its parent, and will continue to have screen space allocated for it. .\" .SH "Usage" Most widgets are automatically mapped when they are managed, as controlled by the\p \f(CWXtNmappedWhenManaged\fP resource. Widgets that are not mapped automatically can be mapped and unmapped explicitly with \f(CWXtMapWidget()\fR and \f(CWXtUnmapWidget()\fP. .LP Unmanaging a widget, rather than unmapping it, is the usual method for temporarily removing a widget from the display. .SH "See Also" .na \s-1\fIXtMapWidget\fR\s+1\*(s1, \s-1\fIXtSetMappedWhenManaged\fR\s+1\*(s1, \s-1\fIXtUnmanageChild\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtUnrealizeWidget" "Xt \- Widget Lifecycle" .SH "Name" .Na XtUnrealizeWidget \- destroy the windows associated with a widget and its descendants. .XX "widgets: windows; destroying (XtUnrealizeWidget)" .Nz .XX "XtUnrealizeWidget" .SH "Synopsis" .Sy void XtUnrealizeWidget(\f(CIw\fP) .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. Must be of class Core or any subclass thereof. .SH "Description" \f(CWXtUnrealizeWidget()\fR unmanages the specified widget and destroys the windows associated with the widget and all of its non-popup descendants. .LP The "Algorithm" section below explains the details of this process. .\" .SH "Usage" .LP Note that this call simply destroys the windows associated with the widgets. The widget instances themselves remain intact. To recreate the windows at a later time, call \f(CWXtRealizeWidget()\fR again. Compare this to \f(CWXtDestroyWidget()\fP, which destroys the widgets themselves. .LP Unmanaging a widget is the usual method for temporarily removing it from the screen. Unrealizing a widget frees up resources on the X server, and may be a better choice for widgets that are only infrequently visible. .\" .SH "Algorithm" If the widget is currently unrealized, \f(CWXtUnrealizeWidget()\fR simply returns; otherwise, it performs the following: .IP \(bu 3n Unmanages the widget if the widget is managed. .IP \(bu 3n Makes a post-order (child to parent) traversal of the widget tree rooted at the specified widget and, for each widget that has declared a callback list named \f(CWunrealizeCallback\fP, executes the procedures on the \f(CWXtNunrealizeCallback\fR list. .IP \(bu 3n Destroys the widget's window and any subwindows by calling \f(CWXDestroyWindow()\fR on the specified widget's window. .LP Any events that are either in the queue or that arrive following a call to \f(CWXtUnrealizeWidget()\fR will be dispatched as if the window(s) of the unrealized widget(s) had never existed. .SH "See Also" .na \s-1\fIXtDestroyWidget\fR\s+1\*(s1, \s-1\fIXtRealizeWidget\fR\s+1\*(s1, \s-1\fIXtUnmanageWidget\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtVaAppCreateShell" "Xt \- Initialization" .SH "Name" .XX "XtVaAppCreateShell" .Na XtVaAppCreateShell \- create a top-level widget that is the root of a widget tree, using varargs argument style. .Nz .SH "Synopsis" .Sy Widget XtVaAppCreateShell(\f(CIapplication_name\fP, \f(CIapplication_class\fP, \f(CIwidget_class\fP, \f(CIdisplay\fP, ..., \f(CWNULL\fP) .As String \f(CIapplication_name\fP; String \f(CIapplication_class\fP; WidgetClass \f(CIwidget_class\fP; Display *\f(CIdisplay\fP; .Ae .SS "Inputs" .IP \f(CIapplication_name\fP 1i Specifies the resource name of the shell widget. .IP \f(CIapplication_class\fP 1i Specifies the class name of this application. .IP \f(CIwidget_class\fP 1i Specifies the widget class for the top-level widget. .IP \f(CIdisplay\fP 1i Specifies the display. .IP "...,\ \s-1\f(CWNULL\fP\s0" 1i A \f(CWNULL\fP-terminated variable-length list of resource name/value pairs to override any other resource specifications. .SS "Returns" A toplevel shell widget of the specified class. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtVaAppCreateShell()\fR creates a top-level shell widget that is the root of a widget tree and a resource name hierarchy (i.e. a widget that has no parent). It is identical to \f(CWXtAppCreateShell()\fR except that the \f(CIargs\fP array of resource names and values and the \f(CInum_args\fP argument of that function are replaced with a \f(CWNULL\fP-terminated variable-length argument list. .LP See \f(CWXtAppCreateShell()\fP for more information on this function. See \f(CWXtVaSetValues()\fP for more information on using variable-length argument lists to specify resources. .SH "Usage" Most applications create secondary top-level shells with \f(CWXtCreatePopupShell()\fP which creates a widget in the same resource hierarchy as the rest of the application. Most applications can use \f(CWXtAppInitialize()\fP or \f(CWXtVaAppInitialize()\fP to initialize the toolkit and create their first shell. .Nd 4 .SH "See Also" .na \s-1\fIXtAppCreateShell\fR\s+1\*(s1, \s-1\fIXtAppInitialize\fR\s+1\*(s1, \s-1\fIXtCreatePopupShell\fR\s+1\*(s1, \s-1\fIXtVaAppInitialize\fR\s+1\*(s1, \s-1\fIXtVaSetValues\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtVaAppInitialize" "Xt \- Initialization" .SH "Name" .XX "XtVaAppInitialize" .Na XtVaAppInitialize \- initialize the X Toolkit internals, using varargs argument style. .Nz .SH "Synopsis" .Sy Widget XtVaAppInitialize(\f(CIapp_context_return\fP, \f(CIapplication_class\fP, \f(CIoptions\fP, \f(CInum_options\fP, \f(CIargc_in_out\fP, \f(CIargv_in_out\fP, \f(CIfallback_resources\fP, ..., \f(CWNULL\fP) .As XtAppContext *\f(CIapp_context_return\fP; String \f(CIapplication_class\fP; XrmOptionDescList \f(CIoptions\fP; Cardinal \f(CInum_options\fP; int *\f(CIargc_in_out\fP; /* was type Cardinal * in Release 4 */ String *\f(CIargv_in_out\fP; String *\f(CIfallback_resources\fP; .Ae .SS "Inputs" .IP \f(CIapplication_class\fP 1.5i Specifies the class name of the application. .IP \f(CIoptions\fP 1.5i Specifies the command line options table. .IP \f(CInum_options\fP 1.5i Specifies the number of entries in options. .IP \f(CIargc_in_out\fP 1.5i Specifies a pointer to the number of command line arguments. This argument was a \f(CWCardinal *\fP in Release 4, and is an \f(CWint *\fP in Release 5. .IP \f(CIargv_in_out\fP 1.5i Specifies the command line arguments array. .IP \f(CIfallback_resources\fP 1.5i Specifies resource values to be used if the application class resource file cannot be opened, or \f(CWNULL\fR. .IP "...,\ \s-1\f(CWNULL\fP\s0" 1.5i A \f(CWNULL\fP-terminated variable-length list of resource name/value pairs to override any other resource specifications for the created shell. .SS "Outputs" .IP \f(CIapp_context_return\fP 1.5i Returns the application context, if non-\f(CWNULL\fR. .SS "Returns" A toplevel shell widget of class \f(CWapplicationShellWidgetClass\fP. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtVaAppInitialize()\fP initializes the Toolkit internals, creates an application context, opens and initializes a display, and creates the initial application shell. It is identical to \f(CWXtAppInitialize()\fP except that the \f(CIargs\fP array of resource names and values and the \f(CInum_args\fP argument of that function are replaced with a \f(CWNULL\fP-terminated variable-length argument list. .LP See \f(CWXtAppInitialize()\fP for more information on this function. See \f(CWXtVaSetValues()\fP for more information on using variable-length argument lists to specify resources. .\" .SH "See Also" .na \s-1\fIXtAppInitialize\fR\s+1\*(s1, \s-1\fIXtVaSetValues\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtVaCreateArgsList" "Xt \- Resource Management" .SH "Name" .XX "XtVaCreateArgsList" .Na XtVaCreateArgsList \- create a varargs list for use with the \f(CWXtVaNestedList\fR symbol. .SH "Synopsis" .Sy XtVarArgsList XtVaCreateArgsList(\f(CIunused\fP, ..., \f(CWNULL\fP) .As XtPointer \f(CIunused\fP; .Ae .SS "Inputs" .IP \f(CIunused\fP 1i This argument is not currently used and must be specified as \f(CWNULL\fP. .IP "...,\ \s-1\f(CWNULL\fP\s0" 1i A \f(CWNULL\fP-terminated variable-length list of resource name/value pairs. .SS "Returns" An \f(CWXtVarArgsList\fP which can be used in future calls to other \f(CWXtVa\fP functions. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtVaCreateArgsList()\fR allocates, copies its arguments into, and returns a pointer to a structure that can be used in future calls to \f(CWXtVa\fP functions using the special symbol \f(CWXtVaNestedList\fP. When this symbol appears in place of a resource name in a variable-length argument list, the next value is interpreted not as a resource value itself, but as a nested argument list of resource name/resource value pairs. .LP When an \f(CWXtVarArgsList\fP is created, any entries in the list of type \f(CWXtVaTypedArg\fR are copied as specified without applying conversions; they will be converted when the list is actually used. Pointer types (including strings) passed to \f(CWXtVaCreateArgsList()\fP are not copied; the caller must ensure that the data remains valid for the lifetime of the created \f(CWXtVarArgsList\fP. .LP When no longer needed, the returned list should be freed using \f(CWXtFree()\fR. .LP See \f(CWXtVaSetValues()\fP for full details on the use of variable length argument lists. .\" .SH "Usage" Nested lists can be useful with the \f(CWXtVa\fP functions in the same circumstances that statically initialized \f(CWArgList\fPs are useful to the non-\f(CWXtVa\fP functions: when there are a set of resources that will be applied to more than one widget. The example below presents one such case. .\" .SH "Example" You might want to use nested argument lists to define a set of related resources that will be applied to multiple widgets: .Ps XFontStruct *normal_font, *bold_font; XtVarArgsList caution_resources; Widget box, commit, abort; caution_resources = XtVaCreateArgsList(NULL, XtNFont, bold_font, XtVaTypedArg, XtNforeground, XtRString, "red", 4, XtNborderWidth, 4, NULL); commit = XtVaCreateWidget("commit", buttonWidgetClass, box, XtNlabel, "Commit All Changes", XtVaNestedList, caution_resources, NULL); abort = XtVaCreateWidget("abort", buttonWidgetClass, box, XtNlabel, "Abort Transaction", XtVaNestedList, caution_resources, NULL); /* free the list since I'm not going to use it again */ XtFree(caution_resources); .Pe .\" .SH "Structures" The \f(CWXtVarArgsList\fP type is defined as follows: .Ps typedef XtPointer XtVarArgsList; .Pe .SH "See Also" .na \s-1\fIXtVaSetValues\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtVaCreateManagedWidget" "Xt \- Widget Lifecycle" .SH "Name" .XX "XtVaCreateManagedWidget" .Na XtVaCreateManagedWidget \- create and manage a widget, specifying resources with a varargs list. .Nz .SH "Synopsis" .Sy Widget XtVaCreateManagedWidget(\f(CIname\fP, \f(CIwidget_class\fP, \f(CIparent\fP, ..., \f(CWNULL\fP) .As String \f(CIname\fP; WidgetClass \f(CIwidget_class\fP; Widget \f(CIparent\fP; .Ae .SS "Inputs" .IP \f(CIname\fP 1i Specifies the resource name for the created widget. .IP \f(CIwidget_class\fP 1i Specifies the widget class pointer for the created widget. Must be rectObjClass or any subclass. .IP \f(CIparent\fP 1i Specifies the parent widget. Must be of class Composite or any subclass thereof. .IP "...,\ \s-1\f(CWNULL\fP\s0" 1i A \f(CWNULL\fP-terminated variable-length list of resource name/value pairs to override any other resource specifications. .SS "Returns" The created and managed widget. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtVaCreateManagedWidget()\fR creates a widget or object named \f(CIname\fP, of class \f(CIwidget_class\fP, as a child of \f(CIparent\fP, and with resource values as specified in the remaining arguments. It is identical to \f(CWXtCreateManagedWidget()\fP except that the \f(CIargs\fP array of resource names and values and the \f(CInum_args\fP argument of that function are replaced with a \f(CWNULL\fP-terminated variable-length argument list. .LP See \f(CWXtCreateManagedWidget()\fP for more information on this function. See \f(CWXtVaSetValues()\fP for more information on using variable-length argument lists to specify resources. .SH "See Also" .na \s-1\fIXtCreateWidget\fR\s+1\*(s1, \s-1\fIXtCreateManagedWidget\fR\s+1\*(s1, \s-1\fIXtManageChild\fR\s+1\*(s1, \s-1\fIXtVaCreateWidget\fR\s+1\*(s1, \s-1\fIXtVaSetValues\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtVaCreatePopupShell" "Xt \- Pop Ups" .SH "Name" .XX "XtVaCreatePopupShell" .Na XtVaCreatePopupShell \- create a popup shell, specifying resources with a varargs list. .Nz .SH "Synopsis" .Sy Widget XtVaCreatePopupShell(\f(CIname\fP, \f(CIwidget_class\fP, \f(CIparent\fP, ..., \f(CWNULL\fP) .As String \f(CIname\fP; WidgetClass \f(CIwidget_class\fP; Widget \f(CIparent\fP; .Ae .SS "Inputs" .IP \f(CIname\fP 1i Specifies the resource name for the created shell widget. .IP \f(CIwidget_class\fP 1i Specifies the widget class pointer for the created shell widget. .IP \f(CIparent\fP 1i Specifies the parent widget. Must be of class Core or any subclass thereof. .IP "...,\ \s-1\f(CWNULL\fP\s0" 1i A \f(CWNULL\fP-terminated variable-length list of resource name/value pairs to override any other resource specifications. .SS "Returns" A shell widget of the specified class. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtVaCreatePopupShell()\fR creates and returns a shell widget of class \f(CIwidget_class\fP and named \f(CIname\fP, as a popup child of \f(CIparent\fP. It is identical to \f(CWXtCreatePopupShell()\fP except that the \f(CIargs\fP array of resource names and values and the \f(CInum_args\fP argument of that function are replaced with a \f(CWNULL\fP-terminated variable-length argument list. .LP See \f(CWXtCreatePopupShell()\fP for more information on this function. See \f(CWXtVaSetValues()\fP for more information on using variable-length argument lists to specify resources. .\" .SH "See Also" .na \s-1\fIXtCreatePopupShell\fR\s+1\*(s1, \s-1\fIXtVaSetValues\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtVaCreateWidget" "Xt \- Widget Lifecycle" .SH "Name" .XX "XtVaCreateWidget" .Na XtVaCreateWidget \- create a widget, specifying resources with a varargs list. .Nz .SH "Synopsis" .Sy Widget XtVaCreateWidget(\f(CIname\fP, \f(CIobject_class\fP, \f(CIparent\fP, ..., \f(CWNULL\fP) .As String \f(CIname\fP; WidgetClass \f(CIobject_class\fP; Widget \f(CIparent\fP; .Ae .SS "Inputs" .IP \f(CIname\fP 1i Specifies the resource name for the created widget. .IP \f(CIobject_class\fP 1i Specifies the widget class pointer for the created object; may be objectClass or any subclass. .IP \f(CIparent\fP 1i Specifies the parent widget. May be of class Object or any subclass thereof. .IP "...,\ \s-1\f(CWNULL\fP\s0" 1i A \f(CWNULL\fP-terminated variable-length list of resource name/value pairs to override any other resource specifications. .SS "Returns" A widget of the specified class. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtVaCreateWidget()\fP creates and returns a widget or object of class \f(CIwidget_class\fP with name \f(CIname\fP, as a child of \f(CIparent\fP. It is identical to \f(CWXtCreateWidget()\fP except that the \f(CIargs\fP array of resource names and values and the \f(CInum_args\fP argument of that function are replaced with a \f(CWNULL\fP-terminated variable-length argument list. .LP See \f(CWXtCreateWidget()\fP for more information on this function. See \f(CWXtVaSetValues()\fP for more information on using variable-length argument lists to specify resources. .SH "See Also" .na \s-1\fIXtCreateManagedWidget\fR\s+1\*(s1, \s-1\fIXtCreateWidget\fR\s+1\*(s1, \s-1\fIXtVaCreateManagedWidget\fR\s+1\*(s1, \s-1\fIXtVaSetValues\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtVaGetApplicationResources" "Xt \- Resource Management" .SH "Name" .XX "XtVaGetApplicationResources" .Na XtVaGetApplicationResources \- retrieve resources for the overall application using varargs argument style. .Nz .SH "Synopsis" .Sy void XtVaGetApplicationResources(\f(CIobject\fP, \f(CIbase\fP, \f(CIresources\fP, \f(CInum_resources\fP, ..., \f(CWNULL\fP) .As Widget \f(CIobject\fP; XtPointer \f(CIbase\fP; XtResourceList \f(CIresources\fP; Cardinal \f(CInum_resources\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object that identifies the resource database to search (the database is that associated with the display for this object); may be of class Object or any subclass thereof. .IP \f(CIbase\fP 1i Specifies the address of structure into which the resources will be written. .IP \f(CIresources\fP 1i Specifies the resource list for the subpart. .IP \f(CInum_resources\fP 1i Specifies the number of resources in the resource list. .IP "...,\ \s-1\f(CWNULL\fP\s0" 1i A \f(CWNULL\fP-terminated variable-length list of resource name/value pairs to override any other resource specifications. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtVaGetApplicationResources()\fR obtains values for the resources described by \f(CIresources\fP, from the variable-length argument list, the resource database, or from the default values associated with each resource, and stores these values into the structure pointed to by base. It is identical to \f(CWXtGetApplicationResources()\fP except that the \f(CIargs\fP array of resource names and values and the \f(CInum_args\fP argument of that function are replaced with a \f(CWNULL\fP-terminated variable-length argument list. .LP See \f(CWXtGetApplicationResources()\fP for more information on this function. See \f(CWXtVaSetValues()\fP for more information on using variable-length argument lists to specify resources. .SH "See Also" .na \s-1\fIXtGetApplicationResources\fR\s+1\*(s1, \s-1\fIXtVaGetSubresources\fR\s+1\*(s1, \s-1\fIXtVaSetValues\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtVaGetSubresources" "Xt \- Resource Management" .SH "Name" .XX "XtVaGetSubresources" .Na XtVaGetSubresources \- fetch resources for widget subparts, using varargs argument style. .Nz .SH "Synopsis" .Sy void XtVaGetSubresources(\f(CIobject\fP, \f(CIbase\fP, \f(CIname\fP, \f(CIclass\fP, \f(CIresources\fP, \f(CInum_resources\fP, ..., \f(CWNULL\fP) .As Widget \f(CIobject\fP; XtPointer \f(CIbase\fP; String \f(CIname\fP; String \f(CIclass\fP; XtResourceList \f(CIresources\fP; Cardinal \f(CInum_resources\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object used to qualify the subpart resource name and class; may be of class Object or any subclass thereof. .IP \f(CIbase\fP 1i Specifies the base address of the subpart data structure into which the resources will be written. .IP \f(CIname\fP 1i Specifies the name of the subpart. .IP \f(CIclass\fP 1i Specifies the class of the subpart. .IP \f(CIresources\fP 1i Specifies the resource list for the subpart. .IP \f(CInum_resources\fP 1i Specifies the number of resources in the resource list. .IP "...,\ \s-1\f(CWNULL\fP\s0" 1i A \f(CWNULL\fP-terminated variable-length list of resource name/value pairs to override any other resource specifications. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtVaGetSubresources()\fR gets values for each of the resources described in \f(CIresources\fP from the variable length argument list, the resource database, or the default values associated with each resource, and stores these values into the structure pointed to by base. It is identical to \f(CWXtGetSubresources()\fP except that the \f(CIargs\fP array of resource names and values and the \f(CInum_args\fP argument of that function are replaced with a \f(CWNULL\fP-terminated variable-length argument list. .LP See \f(CWXtGetSubresources()\fP for more information on this function. See \f(CWXtVaSetValues()\fP for more information on using variable-length argument lists to specify resources. See \f(CWXtGetApplicationResources()\fP for a description of how to declare an \f(CWXtResourceList\fP. .SH "See Also" .na \s-1\fIXtGetApplicationResources\fR\s+1\*(s1, \s-1\fIXtGetSubresources\fR\s+1\*(s1, \s-1\fIXtVaSetValues\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtVaGetSubvalues" "Xt \- Resource Management" .SH "Name" .XX "XtVaGetSubvalues" .Na XtVaGetSubvalues \- retrieve the current values of subpart resources, using varargs argument style. .Nz .SH "Synopsis" .Sy void XtVaGetSubvalues(\f(CIbase\fP, \f(CIresources\fP, \f(CInum_resources\fP, ..., \f(CWNULL\fP) .As XtPointer \f(CIbase\fP; XtResourceList \f(CIresources\fP; Cardinal \f(CInum_resources\fP; .Ae .SS "Inputs" .IP \f(CIbase\fP 1i Specifies the base address of the subpart data structure for which the resources should be retrieved. .IP \f(CIresources\fP 1i Specifies the subpart resource list. .IP \f(CInum_resources\fP 1i Specifies the number of resources in the resource list. .IP "...,\ \s-1\f(CWNULL\fP\s0" 1i A \f(CWNULL\fP-terminated variable-length list of resource names and the addresses at which the values of those resources are to be stored. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtVaGetSubvalues()\fP obtains the values of the resources named in the variable-length argument list (and described in the resource list \f(CIresources\fP) from the subpart structure pointed to by \f(CIbase\fP, and stores those values at the addresses specified in the variable length argument list. Note that the special symbol \f(CWXtVaTypedArg\fR is not supported by \f(CWXtVaGetSubvalues()\fR. If \f(CWXtVaTypedArg\fR is specified in the list, a warning message is issued and the entry is then ignored. .LP \f(CWXtVaGetSubvalues()\fP is identical to \f(CWXtGetSubvalues()\fP except that the \f(CIargs\fP array of resource names and values and the \f(CInum_args\fP argument of that function are replaced with a \f(CWNULL\fP-terminated variable-length argument list. .LP See \f(CWXtGetSubvalues()\fP for more information on this function. See \f(CWXtVaSetValues()\fP for more information on using variable-length argument lists to specify resources. See \f(CWXtGetApplicationResources()\fP for information on how to declare an \f(CWXtResourceList\fP. .SH "See Also" .na \s-1\fIXtGetApplicationResources\fR\s+1\*(s1, \s-1\fIXtGetSubvalues\fR\s+1\*(s1, \s-1\fIXtVaSetValues\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtVaGetValues" "Xt \- Resource Management" .SH "Name" .XX "XtVaGetValues" .Na XtVaGetValues \- retrieve the current values of widget resources, using varargs argument style. .Nz .SH "Synopsis" .Sy void XtVaGetValues(\f(CIobject\fP, ..., \f(CWNULL\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object whose resource values are to be returned; may be of class Object or any subclass thereof. .IP "...,\ \s-1\f(CWNULL\fP\s0" 1i A \f(CWNULL\fP-terminated variable-length list of resource names and the addresses at which the values of those resources are to be stored. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtVaGetValues()\fR gets the values of the resources named in the variable length argument list from the specified widget or object and stores those values at the addresses specified in the argument list. It is the caller's responsibility to ensure that sufficient storage is allocated. If \f(CWXtVaTypedArg\fR is specified, the following type argument field specifies the representation desired by the caller and the following size argument specifies the number of bytes allocated to store the result of the conversion. If the size is insufficient, a warning message is issued and the list entry is skipped. .LP \f(CWXtVaGetValues()\fP is identical to \f(CWXtGetValues()\fP except that the \f(CIargs\fP array of resource names and values and the \f(CInum_args\fP argument of that function are replaced with a \f(CWNULL\fP-\pterminated variable-length argument list. .LP See \f(CWXtGetValues()\fP for more information on this function. See \f(CWXtVaSetValues()\fP for more information on using variable-length argument lists to specify resources. .SH "Example" You can use \f(CWXtVaGetValues()\fP as follows: .Ps Pixel color; XFontStruct *font; String label; Widget w; XtVaGetValues(w, XtNforeground, &color, XtNfont, &font, XtNlabel &label, NULL); .Pe .Nd 5 .SH "See Also" .na \s-1\fIXtGetValues\fR\s+1\*(s1, \s-1\fIXtSetValues\fR\s+1\*(s1, \s-1\fIXtVaSetValues\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtVaSetSubvalues" "Xt \- Resource Management" .SH "Name" .XX "XtVaSetSubvalues" .Na XtVaSetSubvalues \- set the current values of subpart resources, using varargs argument style. .Nz .SH "Synopsis" .Sy void XtVaSetSubvalues(\f(CIbase\fP, \f(CIresources\fP, \f(CInum_resources\fP, ..., \f(CWNULL\fP) .As XtPointer \f(CIbase\fP; XtResourceList \f(CIresources\fP; Cardinal \f(CInum_resources\fP; .Ae .SS "Inputs" .IP \f(CIbase\fP 1i Specifies the base address of the subpart data structure into which the resources should be written. .IP \f(CIresources\fP 1i Specifies the subpart resource list. .IP \f(CInum_resources\fP 1i Specifies the number of resources in the resource list. .IP "...,\ \s-1\f(CWNULL\fP\s0" 1i A \f(CWNULL\fP-terminated variable-length list of resource name/value pairs to override any other resource specifications. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtVaSetSubvalues()\fR sets the resources named in the variable length argument list to the values specified in the same list. The values are copied into the structure pointed to by \f(CIbase\fP at the offset specified by the resource descriptions in \f(CIresources\fP. Note that the special resource name \f(CWXtVaTypedArg\fR is not supported by \f(CWXtVaSetSubvalues()\fR. If \f(CWXtVaTypedArg\fR is specified in the list, a warning message is issued and the entry is then ignored. .LP \f(CWXtVaSetSubvalues()\fP is identical to \f(CWXtSetSubvalues()\fP except that the \f(CIargs\fP array of resource names and values and the \f(CInum_args\fP argument of that function are replaced with a \f(CWNULL\fP-terminated variable-length argument list. .LP See \f(CWXtSetSubvalues()\fP for more information on this function. See \f(CWXtVaSetValues()\fP for more information on using variable-length argument lists to specify resources. See \f(CWXtGetApplicationResources()\fP for a description of how to declare an \f(CWXtResourceList\fP. .SH "See Also" .na \s-1\fIXtGetApplicationResources\fR\s+1\*(s1, \s-1\fIXtSetSubvalues\fR\s+1\*(s1, \s-1\fIXtVaSetValues\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtVaSetValues" "Xt \- Resource Management" .SH "Name" .XX "XtVaSetValues" .Na XtVaSetValues \- set resource values for a widget, using varargs argument style. .Nz .SH "Synopsis" .Sy void XtVaSetValues(\f(CIobject\fP, ..., NULL) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object whose resources are to be modified; may be of class Object or any subclass thereof. .IP "...,\ \s-1\f(CWNULL\fP\s0" 1i A \f(CWNULL\fP-terminated variable-length list of resource name/value pairs to override any other resource specifications. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtVaSetValues()\fR sets the resources of \f(CIobject\fP named in the variable-length argument list to the values specified in the same list. It is identical to \f(CWXtSetValues()\fP except that the \f(CIargs\fP array of resource names and values and the \f(CInum_args\fP argument of that function are replaced with a \f(CWNULL\fP-terminated variable-length argument list. .LP The "Background" section below explains how to specify resource names and values in a variable-length argument list. See \f(CWXtSetValues()\fP for more information on setting widget resources. .\" .SH "Usage" Using variable-length argument lists is usually much more convenient than passing an \f(CWArgList\fP which must be declared and initialized. Note that the varargs interface is less efficient than the \f(CWArgList\fP interface, because each varargs function converts its argument list into an \f(CWArgList\fP and calls the corresponding \f(CWArgList\fP function. Unless you are setting or querying resources repeatedly, however, this overhead is not generally significant. .LP Variable-length argument lists cannot be type-checked by the compiler, and so using \f(CWXtVaSetValues()\fP and other varargs functions can be a source of bugs. Be sure to end all of your argument lists with \f(CWNULL\fP, and be sure that the type of each argument is as expected. If you specify only a single name/value pair per line, it will be easy to delete or comment out resources, and to insert new resources at an acceptable place. .\" .SH "Example" You can use \f(CWXtVaSetValues()\fP as in the following example: .Ps XtVaSetValues(w, XtNlabel, "Enter a value:", XtNjustify, XtJustifyRight, XtVaTypedArg, XtNforeground, XtRString, "red", 4, NULL); .Pe .\" .SH "Background" This function and the other \f(CWXtVa\fP functions have resource names and values specified in a \f(CWNULL\fP-terminated variable-length argument list, rather than an \f(CWArgList\fP array. Generally, the argument list to these functions will consist of resource names (of type \f(CWString\fP) followed by resource values (these are of type \f(CWXtArgVal\fP, but because varargs lists cannot be type-checked, you do not have to cast your values). There are two special symbols which can be used in place of a resource name, however. Each symbol modifies the interpretation of the following arguments. .IP \f(CWXtVaNestedList\fP .25i If you specify a resource name of \f(CWXtVaNestedList\fP, the following argument will be interpreted as an \f(CWXtVarArgsList\fP value, as returned by \f(CWXtVaCreateArgsList()\fP. The resource names and values on this nested list will be treated exactly as if they were specified at the current point in the original list. Nested lists may contain other nested lists, to any depth of nesting. .IP \f(CWXtVaTypedArg\fP .25i If you specify a resource name of \f(CWXtVaTypedArg\fP, then the following four arguments will be interpreted specially as instructions to invoke a resource converter and set a resource to the result of the conversion. The first following argument is the name of the resource to be set, and must be of type \f(CWString\fP. The second following argument is also a \f(CWString\fP, the resource type of the following value. This type, plus the type of the named resource identify the resource converter to be invoked. This argument is usually \f(CWXtRString\fP, or one of the other \f(CWXtR\fP types predefined by the Intrinsics. The third following argument is the value to be converted. It is of the type specified by the previous argument, usually a \f(CWString\fP. If the type is not \f(CWXtRString\fP, then if the value fits in an \f(CWXtArgVal\fP, it is passed directly in the argument list, otherwise a pointer to the value is passed. Finally, the forth following argument is the size in bytes of the type. If the type is \f(CWXtRString\fP, however, then type should be the length of the string plus one, not \f(CWsizeof(String)\fP. .LP The example above show a use of the \f(CWXtVaTypedArg\fP value. See \f(CWXtVaCreateArgsList()\fP for an example of \f(CWXtVaNestedList\fP. .\" .SH "See Also" .na \s-1\fIXtSetValues\fR\s+1\*(s1, \s-1\fIXtVaCreateArgsList\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtWarning" "Xt \- Error Handling" .SH "Name" .Na XtWarning \- call the low-level warning handler. .Nz .XX "XtWarning" .SH "Synopsis" .Sy void XtWarning(\f(CImessage\fP) .As String \f(CImessage\fP; .Ae .SS "Inputs" .IP \f(CImessage\fP 1i Specifies the nonfatal error message to be reported. .\" .SH "Availability" \f(CWXtWarning()\fP has been superseded by \f(CWXtAppWarning()\fP. .\" .SH "Description" \f(CWXtWarning()\fP passes its argument to the installed low-level warning handler. On \s-1POSIX\s+1 systems, the default handler is \f(CW_XtDefaultWarning()\fP. It prints the message to the stderr stream and returns. .\" .SH "Usage" \f(CWXtWarning()\fP has been superseded by \f(CWXtAppWarning()\fP, which performs the same function on a per-application context basis. \f(CWXtWarning()\fP now calls \f(CWXtAppWarning()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtWarning()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppWarning()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppWarning()\fP for more information. .LP \f(CWXtWarning()\fP calls the "low-level" warning handler. It is better to use \f(CWXtAppWarningMsg()\fP which calls the "high-level" warning handler. The high-level handler looks up the warning message in a resource database and so allows for customization and internationalization of error messages. .\" .SH "See Also" .na \s-1\fIXtAppWarning\fR\s+1\*(s1, \s-1\fIXtAppWarningMsg\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtWarningMsg" "Xt \- Error Handling" .SH "Name" .Na XtWarningMsg \- call the high-level warning handler. .XX "warning handler, calling high-level" .XN "warning handler: (see also XtWarningMsg)" .XX "XtWarningMsg" .Nz .SH "Synopsis" .Sy void XtWarningMsg(\f(CIname\fP, \f(CItype\fP, \f(CIclass\fP, \f(CIdefault\fP, \f(CIparams\fP, \f(CInum_params\fP) .As String \f(CIname\fP; String \f(CItype\fP; String \f(CIclass\fP; String \f(CIdefault\fP; String *\f(CIparams\fP; Cardinal *\f(CInum_params\fP; .Ae .SS "Inputs" .IP \f(CIname\fP 1i Specifies the general kind of error. .IP \f(CItype\fP 1i Specifies the detailed name of the error. .IP \f(CIclass\fP 1i Specifies the resource class of the error. .IP \f(CIdefault\fP 1i Specifies the default message to use if no message is found in the database. .IP \f(CIparams\fP 1i Specifies an array of values to be inserted into the message. .IP \f(CInum_params\fP 1i Specifies the number of elements in \f(CIparams\fP. .\" .SH "Availability" \f(CWXtWarningMsg()\fP has been superseded by \f(CWXtAppWarningMsg()\fP. .\" .SH "Description" \f(CWXtWarningMsg()\fP passes all of its arguments to the installed high-level warning handler. The default high-level warning handler is \f(CW_XtDefaultWarningMsg()\fP. It calls \f(CWXtAppGetErrorDatabaseText()\fP to lookup an error message of the specified \f(CIname\fP, \f(CItype\fP, and \f(CIclass\fP in the error database. If no such message is found, \f(CWXtAppGetErrorDatabaseText()\fP returns the specified \f(CIdefault\fP message. In either case, \f(CW_XtDefaultWarningMsg()\fP does a \f(CWprintf\fP-style substitution of \f(CIparams\fP into the message, and passes the resulting text to the low-level warning handler by calling \f(CWXtWarning()\fP. .\" .SH "Usage" \f(CWXtWarningMsg()\fP has been superseded by \f(CWXtAppWarningMsg()\fP, which performs the same function on a per-application context basis. \f(CWXtWarningMsg()\fP now calls \f(CWXtAppWarningMsg()\fP passing the default application context created by \f(CWXtInitialize()\fP. Very few programs need multiple application contexts, and you can continue to use \f(CWXtWarningMsg()\fP if you initialize your application with \f(CWXtInitialize()\fP. We recommend, however, that you use \f(CWXtAppInitialize()\fP, \f(CWXtAppWarningMsg()\fP, and the other \f(CWXtApp*()\fP application context specific functions. .LP See \f(CWXtAppWarningMsg()\fP for more information. .\" .SH "See Also" .na \s-1\fIXtAppErrorMsg\fR\s+1\*(s1, \s-1\fIXtAppWarningMsg\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtWidgetClassProc" "Xt \- Widget Method Prototypes" .SH "Name" .Na XtWidgetClassProc \- interface definition for the \f(CWclass_part_initialize()\fP method. .Nz .XX "XtWidgetClassProc" .SH "Synopsis" .Sy typedef void (*XtWidgetClassProc)(WidgetClass); .As WidgetClass \f(CIclass\fP; .Ae .SS "Inputs" .IP \f(CIclass\fP 1i Specifies a pointer to the widget class structure. .\" .SH "Description" \f(CWXtWidgetClassProc\fP is the type of the Object, RectObj, and Core \f(CWclass_part_initialize()\fP method. See \f(CWclass_part_initialize\fP(4) for more information. .\" .SH "See Also" .na \s-1\fIclass_part_initialize\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtWidgetProc" "Xt \- Widget Method Prototypes" .SH "Name" .Na XtWidgetProc \- interface definition for many common widget methods. .Nz .XX "XtWidgetProc" .SH "Synopsis" .Sy typedef void (*XtWidgetProc)(Widget); .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. .\" .SH "Description" \f(CWXtWidgetProc\fP is the type of the Object, RectObj, and Core \f(CWdestroy()\fP method, the Constraint \f(CWdestroy()\fP method, the RectObj and Core \f(CWresize()\fP method, and the Composite \f(CWchange_managed()\fP, \f(CWinsert_child()\fP, and \f(CWdelete_child()\fP methods. See the reference pages in Section 4 for more information. .\" .SH "See Also" .na \s-1\fIchange_managed\fR\s+1\*(s4, \s-1\fIdelete_child\fR\s+1\*(s4, \s-1\fIdestroy\fR\s+1\*(s4, \s-1\fIConstraint destroy\fR\s+1\*(s4, \s-1\fIinsert_child\fR\s+1\*(s4, \s-1\fIresize\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtWidgetToApplicationContext" "Xt \- Application Contexts" .SH "Name" .Na XtWidgetToApplicationContext \- get the application context for a given widget. .XX "widgets: XtWidgetToApplicationContext" .Nz .XX "XtWidgetToApplicationContext" .SH "Synopsis" .Sy XtAppContext XtWidgetToApplicationContext(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object for which you want the application context; may be of class Object or any subclass thereof. .SS "Returns" The application context of \f(CIobject\fP. .\" .SH "Description" \f(CWXtWidgetToApplicationContext()\fR returns the application context in which the specified widget or object was created. .\" .SH "Usage" This function is useful when an application context argument is required in widget code. .\" .SH "See Also" .na \s-1\fIXtCreateApplicationContext\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtWindow" "Xt \- Object Information" .SH "Name" .Na XtWindow \- return the window of the specified widget. .XX "widgets: windows; returning (XtWindow)" .Nz .XX "XtWindow" .SH "Synopsis" .Sy Window XtWindow(\f(CIw\fP) .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. Must be of class Core or any subclass thereof. .SS "Returns" The window of \f(CIw\fP. .\" .SH "Description" \f(CWXtWindow()\fR returns the window of the specified widget. Note that the window is obtained from the Core \f(CWwindow\fR field, which may be \f(CWNULL\fR if the widget has not yet been realized. .\" .SH "Usage" \f(CWXtWindow()\fP is implemented as a function when called from application code, but is replaced by a more efficient macro when called from widget code that includes the file \fI\fP. .LP Use \f(CWXtWindowOfObject()\fP to return the window of a widget or the nearest widget ancestor of a non-widget object. .\" .SH "See Also" .na \s-1\fIXtDisplay\fR\s+1\*(s1, \s-1\fIXtScreen\fR\s+1\*(s1, \s-1\fIXtWindowOfObject\fR\s+1\*(s1, \s-1\fIXtWindowToWidget\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtWindowOfObject" "Xt \- Object Information" .SH "Name" .XX "XtWindowOfObject" .Na XtWindowOfObject \- return the window for the nearest ancestor of object that is of class Core. .Nz .SH "Synopsis" .Sy Window XtWindowOfObject(\f(CIobject\fP) .As Widget \f(CIobject\fP; .Ae .SS "Inputs" .IP \f(CIobject\fP 1i Specifies the object; may be of class Object or any subclass thereof. .SS "Returns" The window of \f(CIobject\fP or of its nearest widget ancestor. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" \f(CWXtWindowOfObject()\fR is identical in function to \f(CWXtWindow()\fR if \f(CIobject\fP is a widget; otherwise \f(CWXtWindowOfObject()\fR returns the window for the nearest ancestor of \f(CIobject\fP that is of class Core or any subclass thereof. .SH "Usage" If you are working with windowed objects, use \f(CWXtWindow()\fP rather than \f(CWXtWindowOfObject()\fP. \f(CWXtWindow()\fP may be implemented as an efficient macro for widget code that includes the file \fI\fP. .\" .SH "See Also" .na \s-1\fIXtDisplayOfObject\fR\s+1\*(s1, \s-1\fIXtScreenOfObject\fR\s+1\*(s1, \s-1\fIXtWindow\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtWindowToWidget" "Xt \- Object Information" .SH "Name" .Na XtWindowToWidget \- translate a window and display pointer into a widget ID. .XX "widgets: translating; XtWindowToWidget" .Nz .XX "XtWindowToWidget" .SH "Synopsis" .Sy Widget XtWindowToWidget(\f(CIdisplay\fP, \f(CIwindow\fP) .As Display *\f(CIdisplay\fP; Window \f(CIwindow\fP; .Ae .SS "Inputs" .IP \f(CIdisplay\fP 1i Specifies the display on which the window is defined. .IP \f(CIwindow\fP 1i Specifies the window for which you want the widget. .SS "Returns" The widget that created \f(CIwindow\fP on \f(CIdisplay\fP, or \f(CWNULL\fP. .\" .SH "Description" \f(CWXtWindowToWidget()\fR takes a display pointer and a window and returns the associated widget ID. The widget must be within the same application as the caller. .LP If the specified display and window do not match any widget created by the application, \f(CWXtWindowToWidget()\fR returns \f(CWNULL\fP. .\" .SH "Usage" This function can be useful to convert the window of an \f(CWXEvent\fP structure into the corresponding widget. If you use the standard Intrinsics event dispatching mechanisms, however, this should not ever be necessary. .\" .SH "See Also" .na \s-1\fIXtNameToWidget\fR\s+1\*(s1, \s-1\fIXtWindow\fR\s+1\*(s1. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "XtWorkProc" "Xt \- Event Handling" .SH "Name" .Na XtWorkProc \- interface definition for procedure called when the event loop is idle. .Nz .XS "XtWorkProc" .XS "background processing" .SH "Synopsis" .Sy typedef Boolean (*XtWorkProc)(XtPointer); .As XtPointer \f(CIclient_data\fP; .Ae .SS "Inputs" .IP \f(CIclient_data\fP 1i Specifies data registered with this procedure. .SS "Returns" \f(CWTrue\fP if the procedure should not be called again; \f(CWFalse\fP otherwise. .SH "Description" An \f(CWXtWorkProc\fP is registered with \f(CWXtAppAddWorkProc()\fP and is called by \f(CWXtAppMainLoop()\fP and \f(CWXtAppProcessEvent()\fP if there are no events pending and the application would otherwise block. .LP The \f(CIclient_data\fP argument is data of any type registered in the call to \f(CWXtAppAddWorkProc()\fP. It is generally cast to an \f(CWXtPointer\fP when registered and cast back to the appropriate type within the \f(CWXtWorkProc\fP. An \f(CWXtWorkProc\fP must get all of its context from this argument or from global variables. .LP An \f(CWXtWorkProc\fP should perform a single short task and return. If it does not return quickly then events that arrive while it is running will not be handled immediately, and the response time seen by the user will suffer. If a work procedure has a lot of processing to do, it should perform a piece of it, save its state in static variables, and return \f(CWFalse\fP. When an \f(CWXtWorkProc\fP returns \f(CWFalse\fP, the Intrinsics will call it again the next time the event loop is idle, and it can resume its processing where it left off. When it completes all of its processing, it should return \f(CWTrue\fP, and the Intrinsics will automatically un-register it, so that it will not be called again. .SH "Usage" One possible use of work procedures is to create the widgets in dialog boxes which are not needed immediately when an application starts up. This will save start up time for the main application window, and will probably also mean that the dialog boxes will be fully created by the time the user requests that one is popped up. .LP You can register multiple work procedures, and they will be performed one at a time. The most recent work procedure added has the highest priority. Therefore, for example, if you want to create ten popup widgets during idle time, you might add ten work procedures. The pop up that you expect to need first should be created by the last work procedure registered. See the example below for an alternate approach, however. .LP You can explicitly remove a work procedure with \f(CWXtRemoveWorkProc()\fP. .\" .SH "Example" The first procedure below is an \f(CWXtWorkProc\fP that creates several dialog widgets. Note that it returns after creating each dialog. If the dialogs are needed before they are created by this procedure, they will have to be created explicitly as shown in the second procedure below. The only standard client in X11R5 that uses work procedures is \fIxfontsel\fP which performs sophisticated scheduling of all the background work of parsing the names of all the fonts available from the server. .Ps Widget file_dialog = NULL; Widget print_dialog = NULL; Widget confirm_dialog = NULL; Boolean CreateDialogsInBackground(client_data) XtPointer client_data; { Widget toplevel = (Widget) client_data; static int num = 0; num++; switch(num) { case 1: if (file_dialog == NULL) file_dialog = CreateFileDialog(toplevel); return False; case 2: if (print_dialog == NULL) print_dialog = CreatePrintDialog(toplevel); return False; case 3: if (confirm_dialog == NULL) confirm_dialog = CreateConfirmDialog(toplevel); return True; } return True; } void DoFileDialog(toplevel) Widget toplevel; { if (file_dialog == NULL) file_dialog = CreateFileDialog(toplevel); XtPopup(file_dialog, XtGrabExclusive); } .Pe This work procedure could be registered with a call like the following: .Ps toplevel = XtAppInitialize(...); BuildInterface(toplevel); XtRealizeWidget(toplevel); XtAppAddWorkProcedure(app_context, CreateDialogsInBackground, (XtPointer) toplevel); XtAppMainLoop(app_context); .Pe .LP .XX "popups: creating; in work procedure" .XX "work procedures: creating pop up in" .\" .SH "See Also" .na \s-1\fIXtAppAddWorkProc\fR\s+1\*(s1, \s-1\fIXtRemoveWorkProc\fR\s+1\*(s1. .ad .XE "XtWorkProc" .XE "background processing" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XwcDrawImageString" "Xlib \- Internationalized Text Output" .ds ]W Xlib Reference Manual .XX "XwcDrawImageString" .XX "text:wide-character, drawing" .SH Name .Na XwcDrawImageString \(en draw internationalized wide-character image text. .Nz .SH Synopsis .Sy void XwcDrawImageString\^(\^\f(CIdisplay\fP\^, \f(CIdrawable\fP\^, \f(CIfont_set\fP\^, \f(CIgc\fP\^, \f(CIx\fP\^, \f(CIy\fP\^, \f(CIstring\fP\^, \f(CInum_wchars\fP\^) .As Display *\f(CIdisplay\fP\^; Drawable \f(CIdrawable\fP\^; XFontSet \f(CIfont_set\fP\^; GC \f(CIgc\fP\^; int \f(CIx\fP\^, \f(CIy\fP\^; wchar_t *\f(CIstring\fP\^; int \f(CInum_wchars\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIfont_set\fP 1i Specifies the font set. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP "\f(CIx\fP, \f(CIy\fP" 1i Specifies the starting position and baseline of the text, relative to the origin of the specified drawable. .IP \f(CIstring\fP 1i Specifies the character string. .IP \f(CInum_wchars\fP 1i Specifies the number of characters in the string argument. .SH Availability Release 5 and later. .SH Description \f(CWXwcDrawImageString()\fR fills a destination rectangle with the background pixel defined in the GC and then paints the specified wide-character text with the foreground pixel. The filled rectangle is the rectangle returned to \f(CIoverall_logical_return\fP by \f(CWXmbTextExtents()\fR or \f(CWXwcTextExtents()\fR for the same text and \f(CWXFontSet\fR. .LP When the \f(CWXFontSet\fR has missing charsets, each unavailable character is drawn with the default string returned by \f(CWXCreateFontSet()\fR. The behavior for an invalid codepoint is undefined. .LP \f(CWXwcDrawImageString()\fP draws with fonts from the font set rather than the font of the GC. For this reason, it may modify the font value of the GC. Except for the font, it uses the same GC components as its pre-X11R5 analog \f(CWXDrawImageString()\fP. .Nd 6 .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXwcDrawString()\fP\s+1, \s-1\fIXwcDrawText()\fP\s+1, \s-1\fIXmbDrawImageString()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XwcDrawString" "Xlib \- Internationalized Text" .ds ]W Xlib Reference Manual .XX "XwcDrawString" .XX "text:wide-character, drawing" .SH Name .Na XwcDrawString \(en draw internationalized wide-character text. .Nz .SH Synopsis .Sy void XwcDrawString\^(\^\f(CIdisplay\fP\^, \f(CIdrawable\fP\^, \f(CIfont_set\fP\^, \f(CIgc\fP\^, \f(CIx\fP\^, \f(CIy\fP\^, \f(CIstring\fP\^, \f(CInum_wchars\fP\^) .As Display *\f(CIdisplay\fP\^; Drawable \f(CIdrawable\fP\^; XFontSet \f(CIfont_set\fP\^; GC \f(CIgc\fP\^; int \f(CIx\fP\^, \f(CIy\fP\^; wchar_t *\f(CIstring\fP\^; int \f(CInum_wchars\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIfont_set\fP 1i Specifies the font set. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP "\f(CIx\fP, \f(CIy\fP" 1i Specifies the starting position and baseline of the text, relative to the origin of the specified drawable. .IP \f(CIstring\fP 1i Specifies the character string. .IP \f(CInum_wchars\fP 1i Specifies the number of characters in the string argument. .SH Availability Release 5 and later. .SH Description \f(CWXwcDrawString()\fR draws the specified wide-character text with the foreground pixel. When the \f(CWXFontSet\fR has missing charsets, each unavailable character is drawn with the default string returned by \f(CWXCreateFontSet()\fR. The behavior for an invalid codepoint is undefined. .LP \f(CWXwcDrawString()\fP draws with fonts from the font set rather than the font of the GC. For this reason, it may modify the font value of the GC. Except for the font, it uses the same GC components as its pre-X11R5 analog \f(CWXDrawString()\fP. .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXwcDrawImageString()\fP\s+1, \s-1\fIXwcDrawText()\fP\s+1, \s-1\fIXmbDrawString()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XwcDrawText" "Xlib \- Internationalized Text Output" .ds ]W Xlib Reference Manual .XX "XwcDrawText" .XX "text:wide-character, drawing" .SH Name .Na XwcDrawText \(en draw internationalized wide-character text using multiple font sets. .Nz .SH Synopsis .Sy void XwcDrawText\^(\^\f(CIdisplay\fP\^, \f(CIdrawable\fP\^, \f(CIgc\fP\^, \f(CIx\fP\^, \f(CIy\fP\^, \f(CIitems\fP\^, \f(CInitems\fP\^) .As Display *\f(CIdisplay\fP\^; Drawable \f(CIdrawable\fP\^; GC \f(CIgc\fP\^; int \f(CIx\fP\^, \f(CIy\fP\^; XwcTextItem *\f(CIitems\fP\^; int \f(CInitems\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIdrawable\fP 1i Specifies the drawable. .IP \f(CIgc\fP 1i Specifies the graphics context. .IP "\f(CIx\fP, \f(CIy\fP" 1i Specifies the starting position and baseline of the text, relative to the origin of the specified drawable. .IP \f(CIitems\fP 1i Specifies an array of text items. .IP \f(CInitems\fP 1i Specifies the number of text items in the array. .SH Availability Release 5 and later. .SH Description \f(CWXwcDrawText()\fR allows complex spacing and font set shifts between wide-character text strings. Each text item is processed in turn, with the origin of a text element advanced in the primary draw direction by the escapement of the previous text item. A text item delta specifies an additional escapement of the text item drawing origin in the primary draw direction. A \f(CIfont_set\fP member other than \f(CWNone\fR in an item causes the font set to be used for this and subsequent text items in the \f(CIitems\fP list. Leading text items with \f(CIfont_set\fP member set to \f(CWNone\fR will not be drawn. .LP \f(CWXwcDrawText()\fR does not perform any context-dependent rendering between text segments. Clients may compute the drawing metrics by passing each text segment to \f(CWXwcTextExtents()\fR or \f(CWXmbTextPerCharExtents()\fR. When the \f(CWXFontSet\fR has missing charsets, each unavailable character is drawn with the default string returned by \f(CWXCreateFontSet()\fR. The behavior for an invalid codepoint is undefined. .LP .Nd 5 \f(CWXwcDrawText()\fP draws with fonts from the font sets of the \f(CIitems\fP list rather than the font of the GC. For this reason, it may modify the font value of the GC. Except for the font, it uses the same GC components as its pre-X11R5 analog \f(CWXDrawText()\fP. .Nd 20 .SH "Structures" The \f(CWXwcTextItem\fR structure contains: .Ps .TA .5i 2.5i .ta .5i 2.5i typedef struct { wchar_t *chars; /* pointer to wide char string */ int nchars; /* number of wide characters */ int delta; /* pixel delta between strings */ XFontSet font_set; /* fonts, None means don't change */ } XwcTextItem; .Pe .SH "See Also" \s-1\fIXDrawImageString()\fP\s+1, \s-1\fIXDrawString()\fP\s+1, \s-1\fIXDrawText()\fP\s+1, \s-1\fIXwcDrawImageString()\fP\s+1, \s-1\fIXwcDrawString()\fP\s+1, \s-1\fIXmbDrawText()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XwcFreeStringList" "Xlib \- Text Encoding Conversions" .ds ]W Xlib Reference Manual .XX "XwcFreeStringList" .XX "text lists:converting to text properties" .XX "text properties:converting to text lists" .SH Name .Na XwcFreeStringList \(en free memory allocated by \f(CWXwcTextPropertyToTextList\fR. .Nz .SH Synopsis .Sy void XwcFreeStringList\^(\^\f(CIlist\fP\^) .As wchar_t **\f(CIlist\fP\^; .Ae .SH Arguments .IP \f(CIlist\fP 1i Specifies the list of strings to be freed. .SH Availability Release 5 and later. .SH Description \f(CWXwcFreeStringList()\fR frees the string list and component strings allocated by \f(CWXwcTextPropertyToTextList()\fR. .SH "See Also" \s-1\fIXwcTextPropertyToTextList()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XwcLookupString" "Xlib \- Internationalized Text Input" .ds ]W Xlib Reference Manual .XX "XwcLookupString" .XX "wide-character input:obtaining" .XX "input methods:obtaining from wide-character input" .SH Name .Na XwcLookupString \(en obtain composed wide-character input from an input method. .Nz .SH Synopsis .Sy int XwcLookupString\^(\^\f(CIic\fP\^, \f(CIevent\fP\^, \f(CIbuffer_return\fP\^, \f(CIbytes_buffer\fP\^, .br \f(CIkeysym_return\fP\^, \f(CIstatus_return\fP\^) .As XIC \f(CIic\fP\^; XKeyPressedEvent *\f(CIevent\fP\^; wchar_t *\f(CIbuffer_return\fP\^; int \f(CIwchars_buffer\fP\^; KeySym *\f(CIkeysym_return\fP\^; Status *\f(CIstatus_return\fP\^; .Ae .SH Arguments .IP \f(CIic\fP 1.35i Specifies the input context. .ds Ev keypress event to be used .IP \f(CIevent\fP Specifies the \*(Ev. .IP \f(CIbuffer_return\fP Returns a wide-character string (if any) from the input method. .IP \f(CIwchars_buffer\fP Specifies the number of wide-characters in return buffer. .IP \f(CIkeysym_return\fP Returns the KeySym computed from the event if this argument is not \f(CWNULL\fP. .IP \f(CIstatus_return\fP Returns a value indicating what kind of data is returned. .SH Returns The length, in wide characters, of the string returned in \f(CIbuffer_return\fP, if any. .SH Availability Release 5 and later. .SH Description \f(CWXwcLookupString()\fP passes a \f(CWKeyPress\fP event to an input context, returns composed text in the encoding of the locale of the input context if any is ready, and may return a keysym corresponding to the \f(CWKeyPress\fP event as well. .LP There are several possible results of a call to \f(CWXwcLookupString()\fP, and a client should check the value returned in the \f(CIstatus_return\fP argument to determine which has occured. The possible values are: .IP \f(CWXBufferOverflow\fR 10n The input string to be returned is too large for the supplied \f(CIbuffer_return\fP. The required size in wide characters is returned as the value of the function, and the contents of \f(CIbuffer_return\fP and \f(CIkeysym_return\fP are not modified. The client should re-call the function with the same event and a buffer of adequate size in order to obtain the string. .IP \f(CWXLookupNone\fR 10n No consistent input has been composed so far. The contents of \f(CIbuffer_return\fP and \f(CIkeysym_return\fP are not modified, and the function returns zero. .Nd 15 .IP \f(CWXLookupChars\fR 10n .nh Some input characters have been composed. They are placed in the \f(CIbuffer_return\fP argument, and the string length in wide characters is returned as the value of the function. The string is encoded in the locale bound to the input context. The contents of the \f(CIkeysym_return\fP argument is not modified. .hy 14 .IP \f(CWXLookupKeySym\fR 10n A KeySym has been returned instead of a string and is returned in \f(CIkeysym_return\fP. The contents of the \f(CIbuffer_return\fP argument is not modified, and the function returns zero. .IP \f(CWXLookupBoth\fR 10n Both a KeySym and a string are returned; \f(CWXLookupChars\fR and \f(CWXLookupKeySym\fR occur simultaneously. .LP When \f(CWXwcLookupString()\fP returns a string, the return value of the function is the length, in wide characters, of that string. The returned string is a wide-character string in the encoding of the locale of the input context. If that encoding is state-dependent, the string begins in the initial state of the encoding. .LP When both a keysym and a string are returned, the string does not necessarily correspond to the keysym. An application that is not interested in return keysyms can pass a \f(CWNULL\fP \f(CIkeysym_return\fP .LP Note that only \f(CWKeyPress\fP events should be passed to \f(CWXwcLookupString()\fP. When \f(CWKeyRelease\fP events are passed, the resulting behavior is undefined. It does not make any difference if the input context passed as an argument to \f(CWXmbLookupString()\fR and \f(CWXwcLookupString()\fR is the one currently in possession of the focus or not. Input may have been composed within an input context before it lost the focus, and that input may be returned on subsequent calls to \f(CWXmbLookupString()\fR or \f(CWXwcLookupString()\fR, even though it no longer has any more keyboard focus. .SH "See Also" \s-1\fIXLookupKeysym()\fP\s+1, \s-1\fIXmbLookupString()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XwcResetIC" "Xlib \- Input Contexts" .ds ]W Xlib Reference Manual .XX "XwcResetIC" .XX "input contexts:resetting" .SH Name .Na XwcResetIC \(en reset the state of an input context. .Nz .SH Synopsis .Sy wchar_t * XwcResetIC\^(\^\f(CIic\fP\^) .As XIC \f(CIic\fP\^; .Ae .SH Arguments .IP \f(CIic\fP 1i Specifies the input context. .SH Availability Release 5 and later. Implementation-dependent \- see the "Description" section. .SH Description \f(CWXwcResetIC()\fP resets an input context to its initial state. Any input pending on that context is deleted. The input method is required to clear the Preedit area, if any, and update the Status area accordingly. Calling this function does not change the input context focus. .LP The return value of \f(CWXwcResetIC()\fP is implementation-dependent. If there was input pending on the input context, \f(CWXwcResetIC()\fP may return composed wide-character text in the encoding of the locale of the input context, or it may return \f(CWNULL\fP. If any string is returned, the client is responsible for freeing it by calling \f(CWXFree()\fP. .SH "See Also" \s-1\fIXCreateIC()\fP\s+1, \s-1\fIXSetICFocus()\fP\s+1, \s-1\fIXSetICValues()\fP\s+1, \s-1\fIXmbResetIC()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XwcTextEscapement" "Xlib \- Internationalized Text" .ds ]W Xlib Reference Manual .XX "XwcTextEscapement" .XX "text:escapement, obtaining" .SH Name .Na XwcTextEscapement \(en obtain the width of internationalized wide-character text. .Nz .SH Synopsis .Sy int XwcTextEscapement\^(\^\f(CIfont_set\fP\^, \f(CIstring\fP\^, \f(CInum_wchars\fP\^) .As XFontSet \f(CIfont_set\fP\^; wchar_t *\f(CIstring\fP\^; int \f(CInum_wchars\fP\^; .Ae .SH Arguments .IP \f(CIfont_set\fP 1i Specifies the font set. .IP \f(CIstring\fP 1i Specifies the character string. .IP \f(CInum_wchars\fP 1i Specifies the number of characters in the string argument. .SH Returns The escapement in pixels. .SH Availability Release 5 and later. .SH Description \f(CWXwcTextEscapement()\fR returns the escapement in pixels of the specified wide-character string using the fonts loaded for the specified font set. The escapement is the distance in pixels in the primary draw direction from the drawing origin to the origin of the next character to be drawn, assuming that the rendering of the next character is not dependent on the supplied string. .LP The escapement is always positive, regardless of the character-rendering order. .SH "See Also" \s-1\fIXwcTextExtents()\fP\s+1, \s-1\fIXwcTextPerCharExtents()\fP\s+1, \s-1\fIXmbTextEscapement()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XwcTextExtents" "Xlib \- Internationalized Text Output" .ds ]W Xlib Reference Manual .XX "XwcTextExtents" .XX "text:events, computing" .SH Name .Na XwcTextExtents \(en compute the extents of internationalized wide-character text. .Nz .SH Synopsis .Sy int XwcTextExtents\^(\^\f(CIfont_set\fP\^, \f(CIstring\fP\^, \f(CInum_wchars\fP\^, \f(CIoverall_ink_return\fP\^, .br \f(CIoverall_logical_return\fP\^) .As XFontSet \f(CIfont_set\fP\^; wchar_t *\f(CIstring\fP\^; int \f(CInum_wchars\fP\^; XRectangle *\f(CIoverall_ink_return\fP\^; XRectangle *\f(CIoverall_logical_return\fP\^; .Ae .SH Arguments .IP \f(CIfont_set\fP 1i Specifies the font set. .IP \f(CIstring\fP 1i Specifies the character string. .IP \f(CInum_wchars\fP 1i Specifies the number of characters in the string argument. .ds Ov dimensions .IP \f(CIoverall_ink_return\fP 1i Returns the overall ink \*(Ov. .IP \f(CIoverall_logical_return\fP 1i Returns the overall logical \*(Ov. .SH Returns The escapement in pixels. .SH Availability Release 5 and later. .SH Description \f(CWXwcTextExtents()\fR sets the components of the specified \f(CIoverall_ink_return\fP and \f(CIoverall_logical_return\fP arguments to the overall bounding box of the string's image, and the overall logical bounding box of the string's image plus inter-line and inter-character spacing. It returns the value returned by \f(CWXwcTextEscapement()\fR. The returned metrics are relative to the drawing origin of the string, using the fonts loaded for the specified font set. .LP .nh If the \f(CIoverall_ink_return\fP argument is non-\f(CWNULL\fP, it is set to the bounding box of the string's character ink. Note that the \f(CIoverall_ink_return\fP for a non-descending horizontally drawn Latin character is conventionally entirely above the baseline,\p that is, \f(CIoverall_ink_return.height\fP <= \f(CI-overall_ink_return.y\fP. The \f(CIoverall_ink_return\fP for a nonkerned character is entirely at and to the right of the origin, that is, \f(CIoverall_ink_return.x\fP >= 0. A character consisting of a single pixel at the origin would have \f(CIoverall_ink_return\fP fields \f(CIy\fP = 0, \f(CIx\fP = 0, \f(CIwidth\fP = 1, and \f(CIheight\fP = 1. .hy 14 .LP .ne 6 If the \f(CIoverall_logical_return\fP argument is non-\f(CWNULL\fP, it is set to the bounding box which provides minimum spacing to other graphical features for the string. Other graphical features, for example, a border surrounding the text, should not intersect this rectangle. .LP When the \f(CWXFontSet\fR has missing charsets, metrics for each unavailable character are taken from the default string returned by \f(CWXCreateFontSet()\fR so that the metrics represent the text as it will actually be drawn. The behavior for an invalid codepoint is undefined. .SH "Structures" .Ps typedef struct { short x, y; unsigned short width, height; } XRectangle; .Pe .SH "See Also" \s-1\fIXwcTextEscapement()\fP\s+1, \s-1\fIXwcTextPerCharExtents()\fP\s+1, \s-1\fIXmbTextExtents()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "\s-2XwcTextListToTextProperty\s+2" "Xlib \- Text Encoding Conversions" .ds ]W Xlib Reference Manual .XX "XwcTextListToTextProperty" .XX "text lists:converting to text properties" .SH Name .Na XwcTextListToTextProperty \(en convert an internationalized wide-character text list to a text property structure. .Nz .SH Synopsis .Sy int XwcTextListToTextProperty\^(\^\f(CIdisplay\fP\^, \f(CIlist\fP\^, \f(CIcount\fP\^, \f(CIstyle\fP\^, \f(CItext_prop_return\fP\^) .As Display *\f(CIdisplay\fP\^; wchar_t **\f(CIlist\fP\^; int \f(CIcount\fP\^; XICCEncodingStyle \f(CIstyle\fP\^; XTextProperty *\f(CItext_prop_return\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CIlist\fP 1i Specifies an array of \f(CWNULL\fR-terminated wide-character strings. .IP \f(CIcount\fP 1i Specifies the number of strings specified. .IP \f(CIstyle\fP 1i Specifies the manner in which the property is encoded. .IP \f(CItext_prop_return\fP 1i Returns the \f(CWXTextProperty\fR structure. .SH Returns \f(CWSuccess\fR on success; The number of unconvertible characters, \f(CWXLocaleNotSupported\fR, or \f(CWXNoMemory\fR on failure. .SH Availability Release 5 and later. .SH Description \f(CWXwcTextListToTextProperty()\fR sets the specified \f(CWXTextProperty\fR value to a set of null-separated elements representing the concatenation of the specified list of \f(CWNULL\fP-terminated text strings. A final terminating null is stored at the end of the \f(CIvalue\fP field of \f(CItext_prop_return\fP but is not included in the \f(CInitems\fP field. .LP \f(CWXwcTextListToTextProperty()\fR sets the encoding field of \f(CItext_prop_return\fP to an Atom (for the specified display), which names the encoding specified by \f(CIstyle\fR, and converts the specified text list to this encoding for storage in the value field of \f(CItext_prop_return\fP. If the style \f(CWXStringStyle\fR or \f(CWXCompoundTextStyle\fR is specified, this encoding is STRING or COMPOUND_TEXT, respectively. If the style \f(CWXTextStyle\fR is specified, this encoding is the encoding of the current locale. If the style \f(CWXStdICCTextStyle\fR is specified, .ne 2 this encoding is STRING if the text is fully convertible to STRING, otherwise it is COMPOUND_TEXT. .LP If insufficient memory is available for the new value string, \f(CWXwcTextListToTextProperty()\fR returns \f(CWXNoMemory\fR. If the current locale is not supported, it returns \f(CWXLocaleNotSupported\fR. In both of these error cases, it does not set \f(CItext_prop_return\fP. \f(CWXmbTextListToTextProperty()\fP will not return \f(CWXLocaleNotSupported\fP if \f(CWXSupportsLocale()\fP has returned \f(CWTrue\fP for the current locale. .LP To determine if the functions are guaranteed not to return \f(CWXLocaleNotSupported\fR, use \f(CWXSupportsLocale()\fR. .LP If the supplied text is not fully convertible to the specified encoding, \f(CWXwcTextListToTextProperty()\fR returns the number of unconvertible characters. Each unconvertible character is converted to an implementation-defined and encoding-specific default string. If the text is fully convertible, \f(CWXwcTextListToTextProperty()\fR returns \f(CWSuccess\fR. Note that full convertibility to all styles except \f(CWXStringStyle\fR is guaranteed. If the supplied text contains bytes that are not valid characters in the encoding of the locale ("invalid codepoints"), the result is undefined. .LP \f(CWXwcTextListToTextProperty()\fP allocates memory for the \f(CIvalue\fP field of the \f(CWXTextProperty\fP. The client is responsible for freeing this memory by calling \f(CWXFree()\fP. .SH Structures The \f(CWXTextProperty\fR structure contains: .Ps .TA 1.9i .ta 1.9i typedef struct { unsigned char *value; /* property data */ Atom encoding; /* type of property */ int format; /* 8, 16, or 32 */ unsigned long nitems; /* number of items in value */ } XTextProperty; .Pe The \f(CWXICCEncodingStyle\fP type has the following values: .Ps .TA 1.9i .ta 1.9i typedef enum { XStringStyle, /* STRING */ XCompoundTextStyle, /* COMPOUND_TEXT */ XTextStyle, /* text in owner's encoding (current locale) */ XStdICCTextStyle /* STRING, else COMPOUND_TEXT */ } XICCEncodingStyle; .Pe The possible return values of this function are as follows: .sp 1 .in 0 .KS .TS tab(@); lw(.5i) lw(2i) lw(2.5i). \f(CW#define@XNoMemory@ \- 1 #define@XLocaleNotSupported@ \- 2 #define@XConverterNotFound@ \- 3 #define@XConverterNotFound@ \- 3\fR \fR .TE .KE .in .sp 1 .ne 6 .SH "See Also" \s-1\fIXSetTextProperty()\fP\s+1, \s-1\fIXStringListToTextProperty()\fP\s+1, \s-1\fIXDefaultString()\fP\s+1, \s-1\fIXmbTextListToTextProperty()\fP\s+1, \s-1\fIXmbTextPropertyToTextList()\fP\s+1, \s-1\fIXwcTextPropertyToTextList()\fP\s+1, \s-1\fIXwcFreeStringList()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XwcTextPerCharExtents" "Xlib \- Internationalized Text" .ds ]W Xlib Reference Manual .XX "XwcTextPerCharExtents" .XX "text:strings, obtaining information for" .SH Name .Na XwcTextPerCharExtents \(en obtain per-character measurements of an internationalized wide-character text string. .Nz .SH Synopsis .Sy Status XwcTextPerCharExtents\^(\^\f(CIfont_set\fP\^, \f(CIstring\fP\^, \f(CInum_wchars\fP\^, \f(CIink_array_return\fP\^, \f(CIlogical_array_return\fP\^, \f(CIarray_size\fP\^, \f(CInum_chars_return\fP\^, \f(CIoverall_ink_return\fP\^, \f(CWoverall_logical_return\fP\^) .As XFontSet \f(CIfont_set\fP\^; wchar_t *\f(CIstring\fP\^; int \f(CInum_wchars\fP\^; XRectangle *\f(CIink_array_return\fP\^; XRectangle *\f(CIlogical_array_return\fP; int \f(CIarray_size\fP\^; int *\f(CInum_chars_return\fP\^; XRectangle *\f(CIoverall_ink_return\fP\^; XRectangle *\f(CIoverall_logical_return\fP\^; .Ae .sp -1 .SH Arguments .IP \f(CIfont_set\fP 1i Specifies the font set. .IP \f(CIstring\fP 1i Specifies the character string. .IP \f(CInum_wchars\fP 1i Specifies the number of characters in the string argument. .IP \f(CIink_array_return\fP 1i Returns the ink dimensions for each character. .IP \f(CIlogical_array_return\fP 1i Returns the logical dimensions for each character. .IP \f(CIarray_size\fP 1i Specifies the size of \f(CIink_array_return\fP and the size of .hw logical \f(CIlogical_array_return\fP. The caller must pass in arrays of this size. .IP \f(CInum_chars_return\fP 1i Returns the number characters in the string argument. .ds Ov extents of the entire string .IP \f(CIoverall_ink_return\fP 1i Returns the overall ink \*(Ov. .IP \f(CIoverall_logical_return\fP 1i Returns the overall logical \*(Ov. .sp -1 .SH Returns Zero on failure, non-zero on success. .SH Availability Release 5 and later. .Nd 12 .SH Description \f(CWXwcTextPerCharExtents()\fR returns the text dimensions of each character of the specified text, using the fonts loaded for the specified font set. Each element of \f(CIink_array_return\fP and \f(CIlogical_array_return\fP is set to the corresponding character's drawn metrics, relative to the drawing origin of the string. The number .ne 6 of elements of \f(CIink_array_return\fP and \f(CIlogical_array_return\fP that have been set is returned in \f(CInum_chars_return\fP. .LP Each element of \f(CIink_array_return\fP is set to the bounding box of the corresponding character's drawn foreground color. Each element of \f(CIlogical_array_return\fP is set to the bounding box which provides minimum spacing to other graphical features for the corresponding character. Other graphical features should not intersect any of the \f(CIlogical_array_return\fP rectangles. .LP Note that an \f(CWXRectangle\fR represents the effective drawing dimensions of the character, regardless of the number of font glyphs that are used to draw the character, or the direction in which the character is drawn. If multiple characters map to a single character glyph, the dimensions of all the \f(CWXRectangles\fR of those characters are the same. .LP When the \f(CWXFontSet\fR has missing charsets, metrics for each unavailable character are taken from the default string returned by \f(CWXCreateFontSet()\fR, so that the metrics represent the text as it will actually be drawn. The behavior for an invalid codepoint is undefined. .LP If the \f(CIarray_size\fP is too small for the number of characters in the supplied text, the function returns zero and \f(CInum_chars_return\fP is set to the number of rectangles required. Otherwise, it returns a non-zero value. .LP If the \f(CIoverall_ink_return\fP or \f(CIoverall_logical_return\fP argument is non-\f(CWNULL\fP, \f(CWXwcTextPerCharExtents()\fR returns the maximum extent of the string's metrics to \f(CIoverall_ink_return\fP or \f(CIoverall_logical_return\fP, as is done by \f(CWXwcTextExtents()\fR. .SH "Structures" .Ps typedef struct { short x, y; unsigned short width, height; } XRectangle; .Pe .SH "See Also" \s-1\fIXwcTextEscapement()\fP\s+1, \s-1\fIXwcTextExtents()\fP\s+1, \s-1\fIXmbTextPerCharExtents()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V Last changed: 4/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .RH "XwcTextPropertyToTextList" "Xlib \- Text Encoding Conversions" .ds ]W Xlib Reference Manual .XX "XwcTextPropertyToTextList" .XX "text properties:converting to text lists" .XX "text lists:converting from text properties" .SH Name .Na XwcTextPropertyToTextList \(en convert an internationalized text property to a list of wide-\p character strings. .Nz .SH Synopsis .Sy int XwcTextPropertyToTextList\^(\^\f(CIdisplay\fP\^, \f(CItext_prop\fP\^, \f(CIlist_return\fP\^, \f(CIcount_return\fP\^) .As Display *\f(CIdisplay\fP\^; XTextProperty *\f(CItext_prop\fP\^; wchar_t ***\f(CIlist_return\fP\^; int *\f(CIcount_return\fP\^; .Ae .SH Arguments .IP \f(CIdisplay\fP 1i Specifies the connection to the X server. .IP \f(CItext_prop\fP 1i Specifies the \f(CWXTextProperty\fR structure to be used. .IP \f(CIlist_return\fP 1i Returns a list of \f(CWNULL\fP-terminated character strings. .ds Cn strings .IP \f(CIcount_return\fP 1i Returns the number of \*(Cn. .SH Returns \f(CWSuccess\fR on success. \f(CWXNoMemory\fR, \f(CWXLocaleNotSupported\fR, or \f(CWXConverterNotFound\fR on failure. The number of unconvertible characters on partial success. .SH Availability Release 5 and later. .SH Description \f(CWXwcTextPropertyToTextList()\fR return a list of wide-character text strings encoded in the current locale representing the null-separated elements of the specified \f(CWXTextProperty\fR structure. The data in \f(CItext_prop\fP must be format 8. .LP Multiple elements of the property (for example, the strings in a disjoint text selection) are separated by a null byte. The contents of the property are not required to be \f(CWNULL\fP-terminated; any terminating null should not be included in \f(CItext_prop.nitems\fP. .LP If insufficient memory is available for the list and its elements, \f(CWXwcTextPropertyToTextList()\fR returns \f(CWXNoMemory\fR. If the current locale is not supported, it returns \f(CWXLocaleNotSupported\fR. If the encoding field of \f(CItext_prop\fP is not convertible to the encoding of the current locale, it returns \f(CWXConverterNotFound\fR. For supported locales, existence of a converter from COMPOUND_TEXT, STRING, or the encoding of the current locale is guaranteed .ne 5 although the actual text may contain unconvertible characters. Conversion of other encodings is implementation-dependent. .ne 2 In all of these error cases, the function does not set any return values. .LP Otherwise, \f(CWXwcTextPropertyToTextList()\fR returns the list of \f(CWNULL\fP-terminated text strings to \f(CIlist_return\fP, and the number of text strings to \f(CIcount_return\fP. .LP If the value field of \f(CItext_prop\fP is not fully convertible to the encoding of the current locale, the functions return the number of unconvertible characters. Each unconvertible character is converted to a string in the current locale that is specific to the current locale. To obtain the value of this string, use \f(CWXDefaultString()\fR. If all characters are convertible, \f(CWXwcTextPropertyToTextList()\fR returns \f(CWSuccess\fR. If the text property contains "invalid codepoints" or bytes that are not valid characters in the encoding of the property, the result is undefined. .SH Structures The \f(CWXTextProperty\fR structure contains: .Ps .TA .5i 2.5i .ta .5i 2.5i typedef struct { unsigned char *value; /* property data */ Atom encoding; /* type of property */ int format; /* 8, 16, or 32 */ unsigned long nitems; /* number of items in value */ } XTextProperty; .Pe The possible return values of this function are as follows: .sp 1 .in 0 .KS .TS tab(@); lw(.5i) lw(2i) lw(2.5i). \f(CW#define@XNoMemory@ \- 1 #define@XLocaleNotSupported@ \- 2 #define@XConverterNotFound@ \- 3\fR .TE .KE .in .sp 1 .SH "See Also" \s-1\fIXSetTextProperty()\fP\s+1, \s-1\fIXStringListToTextProperty()\fP\s+1, \s-1\fIXDefaultString()\fP\s+1, \s-1\fIXmbTextListToTextProperty()\fP\s+1, \s-1\fIXmbTextPropertyToTextList()\fP\s+1, \s-1\fIXwcFreeStringList()\fP\s+1, \s-1\fIXwcTextListToTextProperty()\fP\s+1. .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "_XEditResCheckMessages" "Xmu \- Editres Protocol" .XB "_XEditResCheckMessages" "XEditResCheckMessages" .XX "event handlers:for Editres protocol" .XX "Editres protocol:event handler for" .SH "Name" .Na .Nz .\" .\" .SH "Synopsis" .Ps \s-1#include XtAddEventHandler(\f(CIshell\fP, (EventMask) 0, True, _XEditResCheckMessages, NULL);\s+1 .Pe .\" .\" .SS "Inputs" .IP \f(CIshell\fP 1i Specifies the shell widget that is to participate in the Editres protocol. .\" .\" .SH "Availability" Release 5 and later. .\" .\" .SH "Description" \f(CW_XEditResCheckMessages\fP, though misleadingly named, is a public function in the Xmu library. It is an event handler, which, when registered on a shell widget, allows that shell widget to participate in the Editres protocol. Shell widgets that are subclasses of the Athena VendorShell widget have this event handler registered automatically. When registering this event handler with \f(CWXtAddEventHandler()\fP, pass an event mask of 0, specify that nonmaskable events should be handled by passing \f(CWTrue\fP as the third argument, and pass \f(CWNULL\fP client data as the last argument. .\" .\"last line comment .\"$Header: ldcvt.3c,v 72.5 94/09/06 15:04:08 ssa Exp $ .TA l .TH ldcvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _ldecvt(\|), _ldecvt_r(\|), _ldfcvt(\|), _ldfcvt_r(\|), _ldgcvt(\|) \- convert long-double floating-point number to string .SH SYNOPSIS .nf .C "#include " .PP .C "char\0*_ldecvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldecvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldfcvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldfcvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldgcvt(long_double\0value,\0int\0ndigit,\0char\0*buf);" .SH DESCRIPTION .TP 15 .C _ldecvt() converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero; otherwise it is zero. .TP .C _ldecvt_r() is identical to .CR _ldecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldfcvt() is identical to .CR _ldecvt() , except that the correct digit has been rounded for printf .C %Lf (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C _ldfcvt_r() is identical to .CR _ldfcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldgcvt() Convert the .I value to a null-terminated string in the array pointed to by .I buf and return .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character are included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C" is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH RETURN VALUE .C NaN is returned for Not-a-Number, and .C \(+-INFINITY is returned for Infinity. .SH WARNINGS The values returned by .C _ldecvt() and .C _ldfcvt() point to a single static-data array whose content is overwritten by each call. .PP .C _ldecvt() and .C _ldfcvt() are unsafe in multi-thread applications. .C _ldecvt_r() and .C _ldfcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR _ldecvt() , .CR _ldfcvt() , and .C _ldgcvt() were developed by HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the radix character. .SS International Code Set Support Single-byte character code sets are supported. .\" .\" index@\f4ldecvt()\fP, (\f4_ldecvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldfcvt()\fP, (\f4_ldfcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldgcvt()\fP, (\f4_ldgcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1 \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@convert long double floating-point number to string@@@\f3ldcvt(3C)\f1 .\" index@long double floating-point number to string, convert@@@\f3ldcvt(3C)\f1 .\" index@floating-point number to string, convert long double@@@\f3ldcvt(3C)\f1 .\" index@number to string, convert long double floating-point@@@\f3ldcvt(3C)\f1 .\" index@string, convert long double floating-point number to@@@\f3ldcvt(3C)\f1 .\" .\" toc@\f3ldcvt(3C)\f1:\0\0\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1@@@convert long double floating-point number to string .\" toc@\f4ldecvt()\fP (\f4_ldecvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldfcvt()\fP (\f4_ldfcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldgcvt()\fP (\f4_ldgcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldecvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldfcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldgcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" .\" links@ldcvt.3c _ldecvt.3c .\" links@ldcvt.3c _ldecvt_r.3c .\" links@ldcvt.3c _ldfcvt.3c .\" links@ldcvt.3c _ldfcvt_r.3c .\" links@ldcvt.3c _ldgcvt.3c .\" links@ldcvt.3c _ldgcvt_r.3c .\" links@ldcvt.3c ldecvt.3c .\" links@ldcvt.3c ldecvt_r.3c .\" links@ldcvt.3c ldfcvt.3c .\" links@ldcvt.3c ldfcvt_r.3c .\" links@ldcvt.3c ldgcvt.3c .\" links@ldcvt.3c ldgcvt_r.3c .\"$Header: ldcvt.3c,v 72.5 94/09/06 15:04:08 ssa Exp $ .TA l .TH ldcvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _ldecvt(\|), _ldecvt_r(\|), _ldfcvt(\|), _ldfcvt_r(\|), _ldgcvt(\|) \- convert long-double floating-point number to string .SH SYNOPSIS .nf .C "#include " .PP .C "char\0*_ldecvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldecvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldfcvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldfcvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldgcvt(long_double\0value,\0int\0ndigit,\0char\0*buf);" .SH DESCRIPTION .TP 15 .C _ldecvt() converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero; otherwise it is zero. .TP .C _ldecvt_r() is identical to .CR _ldecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldfcvt() is identical to .CR _ldecvt() , except that the correct digit has been rounded for printf .C %Lf (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C _ldfcvt_r() is identical to .CR _ldfcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldgcvt() Convert the .I value to a null-terminated string in the array pointed to by .I buf and return .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character are included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C" is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH RETURN VALUE .C NaN is returned for Not-a-Number, and .C \(+-INFINITY is returned for Infinity. .SH WARNINGS The values returned by .C _ldecvt() and .C _ldfcvt() point to a single static-data array whose content is overwritten by each call. .PP .C _ldecvt() and .C _ldfcvt() are unsafe in multi-thread applications. .C _ldecvt_r() and .C _ldfcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR _ldecvt() , .CR _ldfcvt() , and .C _ldgcvt() were developed by HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the radix character. .SS International Code Set Support Single-byte character code sets are supported. .\" .\" index@\f4ldecvt()\fP, (\f4_ldecvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldfcvt()\fP, (\f4_ldfcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldgcvt()\fP, (\f4_ldgcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1 \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@convert long double floating-point number to string@@@\f3ldcvt(3C)\f1 .\" index@long double floating-point number to string, convert@@@\f3ldcvt(3C)\f1 .\" index@floating-point number to string, convert long double@@@\f3ldcvt(3C)\f1 .\" index@number to string, convert long double floating-point@@@\f3ldcvt(3C)\f1 .\" index@string, convert long double floating-point number to@@@\f3ldcvt(3C)\f1 .\" .\" toc@\f3ldcvt(3C)\f1:\0\0\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1@@@convert long double floating-point number to string .\" toc@\f4ldecvt()\fP (\f4_ldecvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldfcvt()\fP (\f4_ldfcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldgcvt()\fP (\f4_ldgcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldecvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldfcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldgcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" .\" links@ldcvt.3c _ldecvt.3c .\" links@ldcvt.3c _ldecvt_r.3c .\" links@ldcvt.3c _ldfcvt.3c .\" links@ldcvt.3c _ldfcvt_r.3c .\" links@ldcvt.3c _ldgcvt.3c .\" links@ldcvt.3c _ldgcvt_r.3c .\" links@ldcvt.3c ldecvt.3c .\" links@ldcvt.3c ldecvt_r.3c .\" links@ldcvt.3c ldfcvt.3c .\" links@ldcvt.3c ldfcvt_r.3c .\" links@ldcvt.3c ldgcvt.3c .\" links@ldcvt.3c ldgcvt_r.3c .\"$Header: ldcvt.3c,v 72.5 94/09/06 15:04:08 ssa Exp $ .TA l .TH ldcvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _ldecvt(\|), _ldecvt_r(\|), _ldfcvt(\|), _ldfcvt_r(\|), _ldgcvt(\|) \- convert long-double floating-point number to string .SH SYNOPSIS .nf .C "#include " .PP .C "char\0*_ldecvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldecvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldfcvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldfcvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldgcvt(long_double\0value,\0int\0ndigit,\0char\0*buf);" .SH DESCRIPTION .TP 15 .C _ldecvt() converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero; otherwise it is zero. .TP .C _ldecvt_r() is identical to .CR _ldecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldfcvt() is identical to .CR _ldecvt() , except that the correct digit has been rounded for printf .C %Lf (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C _ldfcvt_r() is identical to .CR _ldfcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldgcvt() Convert the .I value to a null-terminated string in the array pointed to by .I buf and return .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character are included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C" is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH RETURN VALUE .C NaN is returned for Not-a-Number, and .C \(+-INFINITY is returned for Infinity. .SH WARNINGS The values returned by .C _ldecvt() and .C _ldfcvt() point to a single static-data array whose content is overwritten by each call. .PP .C _ldecvt() and .C _ldfcvt() are unsafe in multi-thread applications. .C _ldecvt_r() and .C _ldfcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR _ldecvt() , .CR _ldfcvt() , and .C _ldgcvt() were developed by HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the radix character. .SS International Code Set Support Single-byte character code sets are supported. .\" .\" index@\f4ldecvt()\fP, (\f4_ldecvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldfcvt()\fP, (\f4_ldfcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldgcvt()\fP, (\f4_ldgcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1 \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@convert long double floating-point number to string@@@\f3ldcvt(3C)\f1 .\" index@long double floating-point number to string, convert@@@\f3ldcvt(3C)\f1 .\" index@floating-point number to string, convert long double@@@\f3ldcvt(3C)\f1 .\" index@number to string, convert long double floating-point@@@\f3ldcvt(3C)\f1 .\" index@string, convert long double floating-point number to@@@\f3ldcvt(3C)\f1 .\" .\" toc@\f3ldcvt(3C)\f1:\0\0\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1@@@convert long double floating-point number to string .\" toc@\f4ldecvt()\fP (\f4_ldecvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldfcvt()\fP (\f4_ldfcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldgcvt()\fP (\f4_ldgcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldecvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldfcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldgcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" .\" links@ldcvt.3c _ldecvt.3c .\" links@ldcvt.3c _ldecvt_r.3c .\" links@ldcvt.3c _ldfcvt.3c .\" links@ldcvt.3c _ldfcvt_r.3c .\" links@ldcvt.3c _ldgcvt.3c .\" links@ldcvt.3c _ldgcvt_r.3c .\" links@ldcvt.3c ldecvt.3c .\" links@ldcvt.3c ldecvt_r.3c .\" links@ldcvt.3c ldfcvt.3c .\" links@ldcvt.3c ldfcvt_r.3c .\" links@ldcvt.3c ldgcvt.3c .\" links@ldcvt.3c ldgcvt_r.3c .\"$Header: ldcvt.3c,v 72.5 94/09/06 15:04:08 ssa Exp $ .TA l .TH ldcvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _ldecvt(\|), _ldecvt_r(\|), _ldfcvt(\|), _ldfcvt_r(\|), _ldgcvt(\|) \- convert long-double floating-point number to string .SH SYNOPSIS .nf .C "#include " .PP .C "char\0*_ldecvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldecvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldfcvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldfcvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldgcvt(long_double\0value,\0int\0ndigit,\0char\0*buf);" .SH DESCRIPTION .TP 15 .C _ldecvt() converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero; otherwise it is zero. .TP .C _ldecvt_r() is identical to .CR _ldecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldfcvt() is identical to .CR _ldecvt() , except that the correct digit has been rounded for printf .C %Lf (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C _ldfcvt_r() is identical to .CR _ldfcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldgcvt() Convert the .I value to a null-terminated string in the array pointed to by .I buf and return .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character are included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C" is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH RETURN VALUE .C NaN is returned for Not-a-Number, and .C \(+-INFINITY is returned for Infinity. .SH WARNINGS The values returned by .C _ldecvt() and .C _ldfcvt() point to a single static-data array whose content is overwritten by each call. .PP .C _ldecvt() and .C _ldfcvt() are unsafe in multi-thread applications. .C _ldecvt_r() and .C _ldfcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR _ldecvt() , .CR _ldfcvt() , and .C _ldgcvt() were developed by HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the radix character. .SS International Code Set Support Single-byte character code sets are supported. .\" .\" index@\f4ldecvt()\fP, (\f4_ldecvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldfcvt()\fP, (\f4_ldfcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldgcvt()\fP, (\f4_ldgcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1 \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@convert long double floating-point number to string@@@\f3ldcvt(3C)\f1 .\" index@long double floating-point number to string, convert@@@\f3ldcvt(3C)\f1 .\" index@floating-point number to string, convert long double@@@\f3ldcvt(3C)\f1 .\" index@number to string, convert long double floating-point@@@\f3ldcvt(3C)\f1 .\" index@string, convert long double floating-point number to@@@\f3ldcvt(3C)\f1 .\" .\" toc@\f3ldcvt(3C)\f1:\0\0\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1@@@convert long double floating-point number to string .\" toc@\f4ldecvt()\fP (\f4_ldecvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldfcvt()\fP (\f4_ldfcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldgcvt()\fP (\f4_ldgcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldecvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldfcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldgcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" .\" links@ldcvt.3c _ldecvt.3c .\" links@ldcvt.3c _ldecvt_r.3c .\" links@ldcvt.3c _ldfcvt.3c .\" links@ldcvt.3c _ldfcvt_r.3c .\" links@ldcvt.3c _ldgcvt.3c .\" links@ldcvt.3c _ldgcvt_r.3c .\" links@ldcvt.3c ldecvt.3c .\" links@ldcvt.3c ldecvt_r.3c .\" links@ldcvt.3c ldfcvt.3c .\" links@ldcvt.3c ldfcvt_r.3c .\" links@ldcvt.3c ldgcvt.3c .\" links@ldcvt.3c ldgcvt_r.3c .\"$Header: ldcvt.3c,v 72.5 94/09/06 15:04:08 ssa Exp $ .TA l .TH ldcvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _ldecvt(\|), _ldecvt_r(\|), _ldfcvt(\|), _ldfcvt_r(\|), _ldgcvt(\|) \- convert long-double floating-point number to string .SH SYNOPSIS .nf .C "#include " .PP .C "char\0*_ldecvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldecvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldfcvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldfcvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldgcvt(long_double\0value,\0int\0ndigit,\0char\0*buf);" .SH DESCRIPTION .TP 15 .C _ldecvt() converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero; otherwise it is zero. .TP .C _ldecvt_r() is identical to .CR _ldecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldfcvt() is identical to .CR _ldecvt() , except that the correct digit has been rounded for printf .C %Lf (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C _ldfcvt_r() is identical to .CR _ldfcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldgcvt() Convert the .I value to a null-terminated string in the array pointed to by .I buf and return .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character are included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C" is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH RETURN VALUE .C NaN is returned for Not-a-Number, and .C \(+-INFINITY is returned for Infinity. .SH WARNINGS The values returned by .C _ldecvt() and .C _ldfcvt() point to a single static-data array whose content is overwritten by each call. .PP .C _ldecvt() and .C _ldfcvt() are unsafe in multi-thread applications. .C _ldecvt_r() and .C _ldfcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR _ldecvt() , .CR _ldfcvt() , and .C _ldgcvt() were developed by HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the radix character. .SS International Code Set Support Single-byte character code sets are supported. .\" .\" index@\f4ldecvt()\fP, (\f4_ldecvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldfcvt()\fP, (\f4_ldfcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldgcvt()\fP, (\f4_ldgcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1 \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@convert long double floating-point number to string@@@\f3ldcvt(3C)\f1 .\" index@long double floating-point number to string, convert@@@\f3ldcvt(3C)\f1 .\" index@floating-point number to string, convert long double@@@\f3ldcvt(3C)\f1 .\" index@number to string, convert long double floating-point@@@\f3ldcvt(3C)\f1 .\" index@string, convert long double floating-point number to@@@\f3ldcvt(3C)\f1 .\" .\" toc@\f3ldcvt(3C)\f1:\0\0\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1@@@convert long double floating-point number to string .\" toc@\f4ldecvt()\fP (\f4_ldecvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldfcvt()\fP (\f4_ldfcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldgcvt()\fP (\f4_ldgcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldecvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldfcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldgcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" .\" links@ldcvt.3c _ldecvt.3c .\" links@ldcvt.3c _ldecvt_r.3c .\" links@ldcvt.3c _ldfcvt.3c .\" links@ldcvt.3c _ldfcvt_r.3c .\" links@ldcvt.3c _ldgcvt.3c .\" links@ldcvt.3c _ldgcvt_r.3c .\" links@ldcvt.3c ldecvt.3c .\" links@ldcvt.3c ldecvt_r.3c .\" links@ldcvt.3c ldfcvt.3c .\" links@ldcvt.3c ldfcvt_r.3c .\" links@ldcvt.3c ldgcvt.3c .\" links@ldcvt.3c ldgcvt_r.3c .\"$Header: ldcvt.3c,v 72.5 94/09/06 15:04:08 ssa Exp $ .TA l .TH ldcvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _ldecvt(\|), _ldecvt_r(\|), _ldfcvt(\|), _ldfcvt_r(\|), _ldgcvt(\|) \- convert long-double floating-point number to string .SH SYNOPSIS .nf .C "#include " .PP .C "char\0*_ldecvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldecvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldfcvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldfcvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldgcvt(long_double\0value,\0int\0ndigit,\0char\0*buf);" .SH DESCRIPTION .TP 15 .C _ldecvt() converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero; otherwise it is zero. .TP .C _ldecvt_r() is identical to .CR _ldecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldfcvt() is identical to .CR _ldecvt() , except that the correct digit has been rounded for printf .C %Lf (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C _ldfcvt_r() is identical to .CR _ldfcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldgcvt() Convert the .I value to a null-terminated string in the array pointed to by .I buf and return .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character are included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C" is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH RETURN VALUE .C NaN is returned for Not-a-Number, and .C \(+-INFINITY is returned for Infinity. .SH WARNINGS The values returned by .C _ldecvt() and .C _ldfcvt() point to a single static-data array whose content is overwritten by each call. .PP .C _ldecvt() and .C _ldfcvt() are unsafe in multi-thread applications. .C _ldecvt_r() and .C _ldfcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR _ldecvt() , .CR _ldfcvt() , and .C _ldgcvt() were developed by HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the radix character. .SS International Code Set Support Single-byte character code sets are supported. .\" .\" index@\f4ldecvt()\fP, (\f4_ldecvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldfcvt()\fP, (\f4_ldfcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldgcvt()\fP, (\f4_ldgcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1 \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@convert long double floating-point number to string@@@\f3ldcvt(3C)\f1 .\" index@long double floating-point number to string, convert@@@\f3ldcvt(3C)\f1 .\" index@floating-point number to string, convert long double@@@\f3ldcvt(3C)\f1 .\" index@number to string, convert long double floating-point@@@\f3ldcvt(3C)\f1 .\" index@string, convert long double floating-point number to@@@\f3ldcvt(3C)\f1 .\" .\" toc@\f3ldcvt(3C)\f1:\0\0\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1@@@convert long double floating-point number to string .\" toc@\f4ldecvt()\fP (\f4_ldecvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldfcvt()\fP (\f4_ldfcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldgcvt()\fP (\f4_ldgcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldecvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldfcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldgcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" .\" links@ldcvt.3c _ldecvt.3c .\" links@ldcvt.3c _ldecvt_r.3c .\" links@ldcvt.3c _ldfcvt.3c .\" links@ldcvt.3c _ldfcvt_r.3c .\" links@ldcvt.3c _ldgcvt.3c .\" links@ldcvt.3c _ldgcvt_r.3c .\" links@ldcvt.3c ldecvt.3c .\" links@ldcvt.3c ldecvt_r.3c .\" links@ldcvt.3c ldfcvt.3c .\" links@ldcvt.3c ldfcvt_r.3c .\" links@ldcvt.3c ldgcvt.3c .\" links@ldcvt.3c ldgcvt_r.3c .\" $Header: setjmp.3c,v 72.5 94/11/15 09:56:14 ssa Exp $ .TA s .TH setjmp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setjmp(\|), longjmp(\|), sigsetjmp(\|), siglongjmp(\|) \- non-local goto .SH SYNOPSIS .C "#include " .PP .C "int setjmp(jmp_buf env);" .PP .C "void longjmp(jmp_buf env, int val);" .PP .C "int _setjmp(jmp_buf env);" .PP .C "void _longjmp(jmp_buf env, int val);" .PP .C "int sigsetjmp(sigjmp_buf env, int savemask);" .PP .C "void siglongjmp(sigjmp_buf env, int val);" .SH DESCRIPTION .C setjmp() and .C longjmp() are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. They exist in three variant forms: .CR setjmp() and .CR longjmp() ; .CR _setjmp() and .CR _longjmp() ; .CR sigsetjmp() and .CR siglongjmp() . Unless indicated otherwise, references to .C setjmp() and .C longjmp() apply to all three versions. .RS .TP 18 .C setjmp() saves its stack environment in .I env (whose type, .CR jmp_buf , is defined in the .RC < setjmp.h > header file) for later use by .CR longjmp() . It returns the value .CR 0 . .TP .C longjmp() restores the environment saved by the last call of .C setjmp() with the corresponding .I env argument. After .C longjmp() is completed, program execution continues as if the corresponding call of .C setjmp() (which must not itself have returned in the interim) had just returned the value .IR val . .C longjmp() cannot cause .C setjmp() to return the value .CR 0 . If .C longjmp() is invoked with a second argument of .CR 0 , .C setjmp() returns .CR 1 . All accessible data values are valid as of the time .C longjmp() is called. .RE .PP Upon the return from a .C setjmp() call caused by a .CR longjmp() , the values of any non-static local variables belonging to the routine from which .C setjmp() was called are undefined. Code which depends on such values is not guaranteed to be portable. .SS Variant Forms The following functions behave the same as .C setjmp() and .C longjmp() except in the handling of the process' signal mask (see .IR sigaction (2) and .IR sigvector (2)). This distinction is only significant for programs which use .CR sigaction() , .CR sigprocmask() , .CR sigvector() , .CR sigblock() , and/or .CR sigsetmask() . .RS .TP 18 .C setjmp() .PD 0 .TP .C longjmp() These always save and restore the signal mask. .PD .TP .C _setjmp() .PD 0 .TP .C _longjmp() These never manipulate the signal mask. .PD .TP .C sigsetjmp() Saves the signal mask if and only if .I savemask is non-zero. .TP .C siglongjmp() Restores the signal mask if and only if it is saved by .CR sigsetjmp() . .SS Programming Considerations If a .C longjmp() is executed and the environment in which the .C setjmp() is executed no longer exists, errors can occur. The conditions under which the environment of the .C setjmp() no longer exists include exiting the procedure that contains the .C setjmp() call, and exiting an inner block with temporary storage (such as a block with declarations in C or a .C with statement in Pascal). This condition might not be detectable, in which case the .C longjmp() occurs and, if the environment no longer exists, the contents of the temporary storage of an inner block are unpredictable. This condition might also cause unexpected process termination. If the procedure has been exited the results are unpredictable. .PP Passing .C longjmp() a pointer to a buffer not created by .CR setjmp() , passing .C _longjmp() a pointer to a buffer not created by either .C setjmp() or .CR _setjmp() , passing .C siglongjmp() a pointer to a buffer not created by .C sigsetjmp() or passing any of these three functions a buffer that has been modified by the user, can cause all the problems listed above, and more. .PP Some implementations of Pascal support a ``try/recover'' mechanism, which also creates stack marker information. If a .C longjmp() operation occurs in a scope which is nested inside a try/recover, and the corresponding .C setjmp() is not inside the scope of the try/recover, the recover block will not be executed and the currently active recover block will become the one enclosing the .CR setjmp() , if one exists. .SH WARNINGS A call to .C longjmp() to leave the guaranteed stack space reserved by .C sigspace() might remove the guarantee that the ordinary execution of the program will not extend into the guaranteed space. It might also cause the program to forever lose its ability to automatically increase the stack size, and the program might then be limited to the guaranteed space. .PP The result of using .C setjmp() within an expression can be unpredictable. .PP If .C longjmp() is called even though .I env was never primed by a call to .CR setjmp() , or when the last such call was in a function that has since returned, total chaos is guaranteed. .SH AUTHOR .C setjmp() was developed by AT&T and HP. .SH SEE ALSO sigaction(2), sigblock(2), signal(5), sigprocmask(2), sigsetmask(2), sigspace(2), sigsuspend(2), sigvector(2). .SH STANDARDS CONFORMANCE .CR setjmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR longjmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR siglongjmp() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigsetjmp() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4_setjmp()\fP \- save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4_longjmp()\fP \- restore stack environment after non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4sigsetjmp()\fP \- save signal mask if savemask is non-zero@@@\f3setjmp(3C)\f1 .\" index@\f4setjmp()\fP \- save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4longjmp()\fP \- restore stack environment after non-local goto@@@\f3setjmp(3C)\f1 .\" index@save/restore stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@restore/save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@non-local goto, save/restore stack environment for@@@\f3setjmp(3C)\f1 .\" index@goto, save/restore stack environment for non-local@@@\f3setjmp(3C)\f1 .\" index@stack environment, save/restore for non-local goto@@@\f3setjmp(3C)\f1 .\" index@environment, save/restore stack for non-local goto@@@\f3setjmp(3C)\f1 .\" .\" toc@\f3setjmp(3S)\f1:\0\0\f4setjmp()\fP, \f4longjmp()\fP@@@save/restore stack environment for non-local goto .\" toc@\f4longjmp()\fP:\0\0restore stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" toc@\f4sigsetjmp()\fP:\0\0save signal mask if savemask is non-zero@@@see \f3setjmp(3C)\f1 .\" toc@\f4_longjmp()\fP:\0\0restore stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" toc@\f4_setjmp()\fP:\0\0save stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" .\" links@setjmp.3c longjmp.3c .\" links@setjmp.3c sigsetjmp.3c .\" links@setjmp.3c siglongjmp.3c .\" links@setjmp.3c _longjmp.3c .\" links@setjmp.3c _setjmp.3c .\" .\" fileset_database@setjmp.3c PROGRAMING-MAN .\" $Header: matherr.3m,v 78.1 96/02/13 15:57:56 ssa Exp $ .\" name of actual manpage file for IC8 is matherr.3m .\" link statements reversed at end of manpage -- ajasper feb 13 1996 .TA m .TH _matherr 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _matherr(\|) \- error-handling function (TO BE WITHDRAWN) .SH SYNOPSIS .C "#include " .PP .C "int _matherr(struct exception *x)" .br .C "{" .br .C " /* your math error handling here */" .br .C "}" .SH DESCRIPTION .CR _matherr() is invoked by some functions in the math library when errors are detected. Programmers can define their own procedures for handling errors by including a function named .CR _matherr() in their programs. .CR _matherr() must be of the form described above. When an error occurs, a pointer to the exception structure .I x is passed to the user-supplied .CR _matherr() function. This structure, which is declared in the .RC < math.h > header file and allocated on the stack by one of the math library internal routines, is as follows: .nf .IP .CR "struct exception {" .CR " int type;" .CR " char *name;" .CR " double arg1, arg2, retval;" .CR }; .fi .RE .PP The element .CR type is an integer describing the type of error that has occurred, from the following list of constants (defined in the header file): .RS .TP 15 .CR DOMAIN argument domain error .PD 0 .TP .CR SING argument singularity .TP .CR OVERFLOW overflow range error .TP .CR UNDERFLOW underflow range error .RE .PD .PP The element .CR name points to a string containing the name of the function that incurred the error. The variables .CR arg1 and .CR arg2 are the arguments with which the function was invoked. .CR retval is set to the default value that will be returned by the function unless the user's .CR _matherr() sets it to a different value. If there is only one argument, .CR arg1 is set to it, and .CR arg2 is undefined. .PP If the user's .CR _matherr() function returns non-zero, no error message is printed, and .CR errno is not set. .PP If .CR _matherr() is not supplied by the user, the default error-handling procedures (described in the man pages for the math functions) are invoked upon error, and the program continues. .PP When .CR _matherr() is called from a .CR float type math function (for example, .CR expf() or .CR logf() ), the argument(s) and default return value .RC ( arg1 , .CR arg2 , and .CR retval ) are converted to .CR double . If an argument is a NaN, it is converted to a .CR double NaN, without trapping, even if it is a signaling NaN. If a user-supplied .CR _matherr() function modifies .CR retval , the value is converted to .CR float when .CR _matherr() returns. If that conversion fails, then a signal is generated. Therefore, it is the responsibility of the user-supplied .CR _matherr() to select values for .CR retval that can be successfully converted to .CR float . .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .PP The .CR matherr() and .CR _matherr() functions are obsolete and will not be supported at the next release of HP-UX. The .CR matherr() function is not required by any version of XPG nor by ANSI C, and has not been part of any standard since SVID2. In the HP-UX math library, the SVID2 .CR matherr() function has been renamed to .CR _matherr() , and no error messages are printed to the standard error output. .CR _matherr() is provided in .CR libm.a in order to assist in supporting old programs. Executables that use the old .CR matherr() or .CR _matherr() will continue to run indefinitely, even on future releases of HP-UX. .PP However, if you intend to recompile or relink any of your current programs that use .CR matherr() or .CR _matherr() on a future release of HP\-UX, you should be aware that any function called .CR matherr() or .CR _matherr() will no longer be called in case of library errors. .PP If you want to intercept math library calls that experience argument errors, you should consider writing wrapper routines that intervene between the original caller and the math library. Such a wrapper could check the value of .CR errno after the math library function returns, and if appropriate, invoke your special error handler. .SH EXAMPLE .RS .sp .nf .ift .ft 4 .ift .ps +1 #include .ift .sp .5v .ifn .sp int _matherr(x) register struct exception *x; { switch (x->type) { case DOMAIN: /* change sqrt to return sqrt(-arg1), not 0 */ if (!strcmp(x->name, "sqrt")) { x->retval = sqrt(-x->arg1); return (0); /* set errno */ } else if (!strcmp(x->name, "sqrtf")) { x->retval = sqrtf(-x->arg1); return (0); /* set errno */ } case SING: /* all other domain or sing errors, print message and abort */ fprintf(stderr, "domain error in %s\en", x->name); abort( ); } return (0); /* all other errors, execute default procedure */ } .ift .ft .ift .ps .fi .RE .SH STANDARDS CONFORMANCE .CR matherr() ": SVID2" .\" .\" index@\f4_matherr()\f1 \- math library error-handling function@@@\f3_matherr(3M)\f1 .\" index@\f1math: math library error-handling function@@@\f3_matherr(3M)\f1 .\" index@\f1math library error-handling function@@@\f3_matherr(3M)\f1 .\" index@\f1error-handling function, math library@@@\f3_matherr(3M)\f1 .\" .\" toc@\f3_matherr(3M)\f1:\0\0\f4_matherr()\f1@@@error-handling function .\" .\" links@matherr.3m _matherr.3m .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getutx.3c,v 76.4 95/09/12 12:01:34 ssa Exp $ .TA g .TH getutx 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutxent(\|), getutxid(\|), getutxline(\|), pututxline(\|), setutxent(\|), endutxent(\|) \- access utmpx file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmpx *getutxent(void);" .PP .C "struct utmpx *getutxid(const struct utmpx *id);" .nf .PP .C "struct utmpx *getutxline(const struct utmpx *line);" .PP .C "struct utmpx *_pututxline(const struct utmpx *utmpx);" .PP .C "void pututxline(const struct utmpx *utmpx);" .PP .C "void setutxent(void);" .PP .C "void endutxent(void);" .PP .fi .SH DESCRIPTION .CR getutxent() , .CR getutxid() , and .C getutxline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmpx { char ut_user[24]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct __exit_status { short __e_termination; /* Process termination status */ short __e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ struct timeval { time_t tv_sec; /* seconds */ long tv_usec; /* and microseconds */ } ut_tv; /* time entry was made */ char ut_host[64]; /* host name, if remote; NOT SUPPORTED */ unsigned long ut_addr; /* Internet addr of host, if remote */ char ut_reserved2[12] ; /* Reserved for future use */ }; .ps .ft .fi .RE .TP 20 .C getutxent() Reads in the next entry from a .CR utmpx -like file. If the file is not already open, .C getutxent() opens it. If it reaches the end of the file, .C getutxent() fails. .TP .C getutxid() Searches forward from the current point in the .I utmpx file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutxid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutxid() fails. .TP .C getutxline() Searches forward from the current point in the .I utmpx file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutxline() fails. .TP .C pututxline() Writes out the supplied .C utmpx structure into the .I utmpx file, translates the supplied .C utmpx structure into a .C utmp structure and writes it to a .I utmp file. .C pututxline() uses .C getutxid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getutx() routines before calling .CR pututxline() . If the search as already been made, .C pututxline() does not repeat it. If .C pututxline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututxline() Performs the same actions as .CR pututxline() , except that it returns a value useful for error checking. .TP .C setutxent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutxent() Closes the currently open file. .TP .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutxid() or .CR getutxline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutxline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutxline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututxline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutxent() , .CR getutxid() , or .C getutxline() if the user has just modified those contents and passed the pointer back to .CR pututxline() . .PP .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmpx)" . .PP .C _pututxline() behaves the same as .CR pututxline() , except that it returns a pointer to a static location containing the most current utmpx entry if the .C _pututxline() call succeeds. The contents of this structure are identical to the contents of the supplied .C utmpx structure if successful. If .C _pututline() fails upon writing to .C utmpx , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmpx file and fails in writing to the .C utmp file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmpx file and the .C utmp file may not be in sync due to the above behavior. .C pututxline() and .C _pututxline() are only guaranteed to have written to the .C utmpx file upon successful completion. .SH FILES .PP .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututline(3), utmpname(3). .SH STANDARDS CONFORMANCE .CR endutxent() ": XPG4.2" .PP .CR getutxent() ": XPG4.2" .PP .CR getutxid() ": XPG4.2" .PP .CR getutxline() ": XPG4.2" .PP .CR pututxline() ": XPG4.2" .PP .CR setutxent() ": XPG4.2" .PP .\" .\" index@\f4getutxent()\f1 \- get pointer to next entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4_pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4setutxent()\f1 \- reset input stream to beginning of \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4endutxent()\f1 \- close currently open \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@access \f4utmpx()\f1 or \f4wtmp()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4utmpx()\f1 or \f4wtmp()\f1 file, access@@@\f3getutx(3C)\f1 .\" index@file: access \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" .\" toc@\f3getutx(3C)\f1:\0\0\f4getutxent()\f1, \f4getutxid()\f1, \f4getutxline()\f1, \f4pututxline()\f1, \f4setutxent()\f1,\n\f4endutxent()\f1@@@access utmpx file entry .\" toc@\f4getutxent()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxid()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4_pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4setutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4endutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f1utmpx file entry@@@see \f3getutx(3C)\f1 .\" .\" links@getutx.3c getutxent.3c .\" links@getutx.3c getutxid.3c .\" links@getutx.3c getutxline.3c .\" links@getutx.3c pututxline.3c .\" links@getutx.3c _pututxline.3c .\" links@getutx.3c setutxent.3c .\" links@getutx.3c endutxent.3c .\" $Header: setjmp.3c,v 72.5 94/11/15 09:56:14 ssa Exp $ .TA s .TH setjmp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setjmp(\|), longjmp(\|), sigsetjmp(\|), siglongjmp(\|) \- non-local goto .SH SYNOPSIS .C "#include " .PP .C "int setjmp(jmp_buf env);" .PP .C "void longjmp(jmp_buf env, int val);" .PP .C "int _setjmp(jmp_buf env);" .PP .C "void _longjmp(jmp_buf env, int val);" .PP .C "int sigsetjmp(sigjmp_buf env, int savemask);" .PP .C "void siglongjmp(sigjmp_buf env, int val);" .SH DESCRIPTION .C setjmp() and .C longjmp() are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. They exist in three variant forms: .CR setjmp() and .CR longjmp() ; .CR _setjmp() and .CR _longjmp() ; .CR sigsetjmp() and .CR siglongjmp() . Unless indicated otherwise, references to .C setjmp() and .C longjmp() apply to all three versions. .RS .TP 18 .C setjmp() saves its stack environment in .I env (whose type, .CR jmp_buf , is defined in the .RC < setjmp.h > header file) for later use by .CR longjmp() . It returns the value .CR 0 . .TP .C longjmp() restores the environment saved by the last call of .C setjmp() with the corresponding .I env argument. After .C longjmp() is completed, program execution continues as if the corresponding call of .C setjmp() (which must not itself have returned in the interim) had just returned the value .IR val . .C longjmp() cannot cause .C setjmp() to return the value .CR 0 . If .C longjmp() is invoked with a second argument of .CR 0 , .C setjmp() returns .CR 1 . All accessible data values are valid as of the time .C longjmp() is called. .RE .PP Upon the return from a .C setjmp() call caused by a .CR longjmp() , the values of any non-static local variables belonging to the routine from which .C setjmp() was called are undefined. Code which depends on such values is not guaranteed to be portable. .SS Variant Forms The following functions behave the same as .C setjmp() and .C longjmp() except in the handling of the process' signal mask (see .IR sigaction (2) and .IR sigvector (2)). This distinction is only significant for programs which use .CR sigaction() , .CR sigprocmask() , .CR sigvector() , .CR sigblock() , and/or .CR sigsetmask() . .RS .TP 18 .C setjmp() .PD 0 .TP .C longjmp() These always save and restore the signal mask. .PD .TP .C _setjmp() .PD 0 .TP .C _longjmp() These never manipulate the signal mask. .PD .TP .C sigsetjmp() Saves the signal mask if and only if .I savemask is non-zero. .TP .C siglongjmp() Restores the signal mask if and only if it is saved by .CR sigsetjmp() . .SS Programming Considerations If a .C longjmp() is executed and the environment in which the .C setjmp() is executed no longer exists, errors can occur. The conditions under which the environment of the .C setjmp() no longer exists include exiting the procedure that contains the .C setjmp() call, and exiting an inner block with temporary storage (such as a block with declarations in C or a .C with statement in Pascal). This condition might not be detectable, in which case the .C longjmp() occurs and, if the environment no longer exists, the contents of the temporary storage of an inner block are unpredictable. This condition might also cause unexpected process termination. If the procedure has been exited the results are unpredictable. .PP Passing .C longjmp() a pointer to a buffer not created by .CR setjmp() , passing .C _longjmp() a pointer to a buffer not created by either .C setjmp() or .CR _setjmp() , passing .C siglongjmp() a pointer to a buffer not created by .C sigsetjmp() or passing any of these three functions a buffer that has been modified by the user, can cause all the problems listed above, and more. .PP Some implementations of Pascal support a ``try/recover'' mechanism, which also creates stack marker information. If a .C longjmp() operation occurs in a scope which is nested inside a try/recover, and the corresponding .C setjmp() is not inside the scope of the try/recover, the recover block will not be executed and the currently active recover block will become the one enclosing the .CR setjmp() , if one exists. .SH WARNINGS A call to .C longjmp() to leave the guaranteed stack space reserved by .C sigspace() might remove the guarantee that the ordinary execution of the program will not extend into the guaranteed space. It might also cause the program to forever lose its ability to automatically increase the stack size, and the program might then be limited to the guaranteed space. .PP The result of using .C setjmp() within an expression can be unpredictable. .PP If .C longjmp() is called even though .I env was never primed by a call to .CR setjmp() , or when the last such call was in a function that has since returned, total chaos is guaranteed. .SH AUTHOR .C setjmp() was developed by AT&T and HP. .SH SEE ALSO sigaction(2), sigblock(2), signal(5), sigprocmask(2), sigsetmask(2), sigspace(2), sigsuspend(2), sigvector(2). .SH STANDARDS CONFORMANCE .CR setjmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR longjmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR siglongjmp() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigsetjmp() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4_setjmp()\fP \- save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4_longjmp()\fP \- restore stack environment after non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4sigsetjmp()\fP \- save signal mask if savemask is non-zero@@@\f3setjmp(3C)\f1 .\" index@\f4setjmp()\fP \- save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4longjmp()\fP \- restore stack environment after non-local goto@@@\f3setjmp(3C)\f1 .\" index@save/restore stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@restore/save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@non-local goto, save/restore stack environment for@@@\f3setjmp(3C)\f1 .\" index@goto, save/restore stack environment for non-local@@@\f3setjmp(3C)\f1 .\" index@stack environment, save/restore for non-local goto@@@\f3setjmp(3C)\f1 .\" index@environment, save/restore stack for non-local goto@@@\f3setjmp(3C)\f1 .\" .\" toc@\f3setjmp(3S)\f1:\0\0\f4setjmp()\fP, \f4longjmp()\fP@@@save/restore stack environment for non-local goto .\" toc@\f4longjmp()\fP:\0\0restore stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" toc@\f4sigsetjmp()\fP:\0\0save signal mask if savemask is non-zero@@@see \f3setjmp(3C)\f1 .\" toc@\f4_longjmp()\fP:\0\0restore stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" toc@\f4_setjmp()\fP:\0\0save stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" .\" links@setjmp.3c longjmp.3c .\" links@setjmp.3c sigsetjmp.3c .\" links@setjmp.3c siglongjmp.3c .\" links@setjmp.3c _longjmp.3c .\" links@setjmp.3c _setjmp.3c .\" .\" fileset_database@setjmp.3c PROGRAMING-MAN .\" $Header: conv.3c,v 72.7 94/11/28 08:25:12 ssa Exp $ .TA c .TH conv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME toupper(\|), tolower(\|), _toupper(\|), _tolower(\|), toascii(\|) \- translate characters .SH SYNOPSIS .C "#include " .PP .C "int toupper(int c);" .PP .C "int tolower(int c);" .PP .C "int _toupper(int c);" .PP .C "int _tolower(int c);" .PP .C "int toascii(int c);" .SH DESCRIPTION .C toupper() and .C tolower() have as domain the range of .IR getc (3S): the integers from \(mi1 through 255. If the argument of .C toupper() represents a lower-case letter, the result is the corresponding upper-case letter. If the argument of .C tolower() represents an upper-case letter, the result is the corresponding lower-case letter. All other arguments in the domain are returned unchanged. Arguments outside the domain cause undefined results. .PP The macros .C _toupper() and .C _tolower() are identical to .C toupper() and .CR tolower() , respectively. .PP .C toascii() yields its argument with all bits that are not part of a standard 7-bit .SM ASCII character cleared; it is intended for compatibility with other systems. .SH WARNING .C toascii() is supplied both as a library function and as a macro defined in the .RC < ctype.h > header. Normally, the macro version is used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI C mode, enclose the function name in parenthesis or take its address. The following examples use the library function for .CR toascii() : .nf .IP .C #include .C #undef toascii \h'.4i'... .C main() .C { \h'.5i'... .C " c1 = toascii(c);" \h'.5i'... .C } .PP or .IP .C #include \h'.4i'... .C main() .C { .C " int (*conv_func)();" \h'.5i'... .C " c1 = (toascii)(c);" \h'.5i'... .C " conv_func = toascii;" \h'.5i'... .C } .fi .PP The following example use the library function for .CR toupper() : .nf .IP .C #include .C #undef toupper \h'.4i'... .C main() .C { \h'.5i'... char *c; *c=toupper ((unsigned char*) c); \h'.5i'... .C } .PP .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the translations to be done. .SS International Code Set Support Single-byte character code sets are supported. .SH AUTHOR .CR conv() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), getc(3S), setlocale(3C), lang(5). .SH STANDARDS CONFORMANCE .CR _tolower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR _toupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR toascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR tolower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR toupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4conv()\f1, \- translate characters@@@\f3conv(3C)\f1 .\" index@\f4toupper()\fP, \f2_toupper\f1, \- translate characters to upper-case@@@\f3conv(3C)\f1 .\" index@\f4tolower()\fP, \f2_tolower\f1 \- translate characters to lower-case@@@\f3conv(3C)\f1 .\" index@\f4toascii()\fP \- translate characters to 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1translate characters to upper-case, lower-case, or 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1characters, translate to upper-case, lower-case, or 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1upper-case, translate characters to@@@\f3conv(3C)\f1 .\" index@\f1lower-case, translate characters to@@@\f3conv(3C)\f1 .\" index@\s-1ASCII\s+1, 7-bit, translate characters to@@@\f3conv(3C)\f1 .\" .\" toc@\f3conv(3C)\f1:\0\0\f4toupper()\fP, \f4tolower()\fP, \f2_toupper\f1, \f2_tolower\f1, \f4toascii()\fP@@@translate characters .\" .\" toc@\f4toupper()\fP, \f2_toupper\f1:\0\0translate characters@@@see \f3conv(3C)\f1 .\" toc@\f4tolower()\fP, \f2_tolower\f1:\0\0translate characters@@@see \f3conv(3C)\f1 .\" toc@\f4toascii()\fP:\0\0translate characters@@@see \f3conv(3C)\f1 .\" .\" links@conv.3c toupper.3c .\" links@conv.3c tolower.3c .\" links@conv.3c _toupper.3c .\" links@conv.3c _tolower.3c .\" links@conv.3c toascii.3c .\" .\" fileset_database@conv.3c PROGRAMING-MAN .\" $Header: conv.3c,v 72.7 94/11/28 08:25:12 ssa Exp $ .TA c .TH conv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME toupper(\|), tolower(\|), _toupper(\|), _tolower(\|), toascii(\|) \- translate characters .SH SYNOPSIS .C "#include " .PP .C "int toupper(int c);" .PP .C "int tolower(int c);" .PP .C "int _toupper(int c);" .PP .C "int _tolower(int c);" .PP .C "int toascii(int c);" .SH DESCRIPTION .C toupper() and .C tolower() have as domain the range of .IR getc (3S): the integers from \(mi1 through 255. If the argument of .C toupper() represents a lower-case letter, the result is the corresponding upper-case letter. If the argument of .C tolower() represents an upper-case letter, the result is the corresponding lower-case letter. All other arguments in the domain are returned unchanged. Arguments outside the domain cause undefined results. .PP The macros .C _toupper() and .C _tolower() are identical to .C toupper() and .CR tolower() , respectively. .PP .C toascii() yields its argument with all bits that are not part of a standard 7-bit .SM ASCII character cleared; it is intended for compatibility with other systems. .SH WARNING .C toascii() is supplied both as a library function and as a macro defined in the .RC < ctype.h > header. Normally, the macro version is used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI C mode, enclose the function name in parenthesis or take its address. The following examples use the library function for .CR toascii() : .nf .IP .C #include .C #undef toascii \h'.4i'... .C main() .C { \h'.5i'... .C " c1 = toascii(c);" \h'.5i'... .C } .PP or .IP .C #include \h'.4i'... .C main() .C { .C " int (*conv_func)();" \h'.5i'... .C " c1 = (toascii)(c);" \h'.5i'... .C " conv_func = toascii;" \h'.5i'... .C } .fi .PP The following example use the library function for .CR toupper() : .nf .IP .C #include .C #undef toupper \h'.4i'... .C main() .C { \h'.5i'... char *c; *c=toupper ((unsigned char*) c); \h'.5i'... .C } .PP .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the translations to be done. .SS International Code Set Support Single-byte character code sets are supported. .SH AUTHOR .CR conv() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), getc(3S), setlocale(3C), lang(5). .SH STANDARDS CONFORMANCE .CR _tolower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR _toupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR toascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR tolower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR toupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4conv()\f1, \- translate characters@@@\f3conv(3C)\f1 .\" index@\f4toupper()\fP, \f2_toupper\f1, \- translate characters to upper-case@@@\f3conv(3C)\f1 .\" index@\f4tolower()\fP, \f2_tolower\f1 \- translate characters to lower-case@@@\f3conv(3C)\f1 .\" index@\f4toascii()\fP \- translate characters to 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1translate characters to upper-case, lower-case, or 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1characters, translate to upper-case, lower-case, or 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1upper-case, translate characters to@@@\f3conv(3C)\f1 .\" index@\f1lower-case, translate characters to@@@\f3conv(3C)\f1 .\" index@\s-1ASCII\s+1, 7-bit, translate characters to@@@\f3conv(3C)\f1 .\" .\" toc@\f3conv(3C)\f1:\0\0\f4toupper()\fP, \f4tolower()\fP, \f2_toupper\f1, \f2_tolower\f1, \f4toascii()\fP@@@translate characters .\" .\" toc@\f4toupper()\fP, \f2_toupper\f1:\0\0translate characters@@@see \f3conv(3C)\f1 .\" toc@\f4tolower()\fP, \f2_tolower\f1:\0\0translate characters@@@see \f3conv(3C)\f1 .\" toc@\f4toascii()\fP:\0\0translate characters@@@see \f3conv(3C)\f1 .\" .\" links@conv.3c toupper.3c .\" links@conv.3c tolower.3c .\" links@conv.3c _toupper.3c .\" links@conv.3c _tolower.3c .\" links@conv.3c toascii.3c .\" .\" fileset_database@conv.3c PROGRAMING-MAN .\" $Header: a64l.3c,v 72.5 94/11/14 11:59:22 ssa Exp $ .TA a .TH a64l 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME a64l(\|), l64a(\|), l64a_r(\|) \- convert between long integer and base-64 ASCII string .SH SYNOPSIS .C "#include " .PP .C "long int a64l(const char *s);" .PP .C "char *l64a(long int l);" .PP .C "int l64a_r(long int l, char *buffer, int buflen);" .SH DESCRIPTION These functions are used to maintain numbers stored in .I base-64 .SM ASCII characters. This is a notation by which long integers can be represented by up to six characters; each character represents a "digit" in a radix-64 notation. .PP The characters used to represent "digits" are .C . for 0, .C / for 1, .C 0 through .C 9 for 2\-11, .C A through .C Z for 12\-37, and .C a through .C z for 38\-63. .PP The leftmost character is the least significant digit. For example, .RS 15 .if n a0 = (38 x 64^0) + (2 x 64^1) = 166 .if t a0 = (38 x 64\u\s-20\s+2\d) + (2 x 64\u\s-21\s+2\d) = 166 .RE .PP .C a64l() takes a pointer to a null-terminated base-64 representation and returns a corresponding .C long value. If the string pointed to by .I s contains more than six characters, .C a64l() uses the first six. .PP .C l64a() takes a .C long argument and returns a pointer to the corresponding base-64 representation. If the argument is 0, .C l64a() returns a pointer to a null string. .SS Reentrant Interfaces .C l64a_r() passes the result string back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .SH WARNINGS The value returned by .C l64a() is a pointer into a static buffer, the contents of which are overwritten by each call. Thus, .C l64a() is unsafe in multi-thread applications. .C l64a_r() is MT-Safe and should be used instead. .SH STANDARDS CONFORMANCE .CR a64l() ": SVID2, SVID3" .PP .CR l64a() ": SVID2, SVID3" .\" .\" index@\f4a64l()\f1 \- convert base-64 value to long integer \s-1ASCII\s+1 string@@@\f3a64l(3C)\f1 .\" index@\f4l64a()\f1 \- convert long integer to base-64 value \s-1ASCII\s+1 string@@@\f3a64l(3C)\f1 .\" index@\f4l64a_r()\f1 \- convert between long integer and base-64 \s-1ASCII\s+1 string@@@\f3a64l(3C)\f1 .\" index@convert between long integer and base-64 \s-1ASCII\s+1 string@@@\f3a64l(3C)\f1 .\" index@\s-1ASCII\s+1 string, convert between long integer and base-64@@@\f3a64l(3C)\f1 .\" index@string, convert between long integer and base-64 \s-1ASCII\s+1@@@\f3a64l(3C)\f1 .\" index@long integer to base-64 \s-1ASCII\s+1 string, convert@@@\f3a64l(3C)\f1 .\" index@integer to base-64 \s-1ASCII\s+1 string, convert long@@@\f3a64l(3C)\f1 .\" index@base-64 \s-1ASCII\s+1 string, convert long integer to@@@\f3a64l(3C)\f1 .\" .\" toc@\f3a64l(3C)\f1:\0\0\f4a64l()\f1, \f4l64a()\f1, \f4l64a_r()\f1@@@convert between long integer and base-64 \s-1ASCII\s+1 string .\" toc@\f2l64a\f1:\0\0convert between long integer and base-64 \s-1ASCII\s+1 string@@@see \f3a64l(3C)\f1 .\" toc@\f2l64a_r\f1:\0\0convert between long integer and base-64 \s-1ASCII\s+1 string@@@see \f3a64l(3X)\f1 .\" .\" links@a64l.3c l64a.3c .\" links@a64l.3c l64a_r.3c .\" .\" fileset_database@a64l.3c PROGRAMING-MAN .\" $Header: abort.3c,v 72.4 94/11/14 11:59:39 ssa Exp $ .TA a .TH abort 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME abort(\|) \- generate a software abort fault .SH SYNOPSIS .C "#include " .PP .C "void abort(void);" .SH DESCRIPTION .C abort() first closes all open files, streams, directory streams, and message catalogue descriptors, if possible, then causes the signal .C SIGABRT to be sent to the calling process. This may cause a core dump to be generated (see .IR signal (2)). .PP If the signal .C SIGABRT is caught, the handling function is executed. If the handling function returns, the action for .C SIGABRT is then reset to .CR IG_DFL , and the signal .C SIGABRT is sent again to the process to ensure that it terminates. .SH RETURN VALUE .C abort() does not return. .SH ERRORS No errors are defined. .SH APPLICATION USAGE .C SIGABRT is not intended to be caught. .SH DIAGNOSTICS If .C SIGABRT is neither caught nor ignored, and the current directory is writable, a core dump is produced and the message .C "abort - core dumped" is written by the shell. .SH SEE ALSO adb(1), exit(2), kill(2), signal(2). signal(5). .SH STANDARDS CONFORMANCE .CR abort() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4abort()\fP \- generate an \s-1IOT\s+1 fault@@@\f3abort(3C)\f1 .\" index@generate an \s-1IOT\s+1 fault@@@\f3abort(3C)\f1 .\" index@\s-1IOT\s+1 fault, generate an@@@\f3abort(3C)\f1 .\" index@fault, generate an \s-1IOT\s+1@@@\f3abort(3C)\f1 .\" .\" toc@\f3abort(3C)\f1:\0\0\f4abort()\fP@@@generate a software abort fault .\" .\" fileset_database@abort.3c PROGRAMING-MAN .\" $Header: abs.3c,v 72.4 94/11/14 11:59:52 ssa Exp $ .TA a .TH abs 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME abs(\|), labs(\|) \- return integer absolute value .SH SYNOPSIS .C "#include " .PP .C "int abs(int i);" .PP .C "long int labs(long int i);" .SH DESCRIPTION .C abs() returns the absolute value of its integer operand. .PP .C labs() is similar to .CR abs() , except that the argument and the returned value each have type long int. .PP The largest negative integer returns itself. .SH WARNINGS In two's-complement representation, the absolute value of the negative integer with largest magnitude is undefined. Some implementations trap this error, but others simply ignore it. .SH SEE ALSO floor(3M). .SH STANDARDS CONFORMANCE .CR abs() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR labs() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4abs()\f1, \f4labs()\f1 \- return integer absolute value@@@\f3abs(3C)\f1 .\" index@\f4labs()\f1 \- return long integer absolute value@@@\f3abs(3C)\f1 .\" index@return integer absolute value@@@\f3abs(3C)\f1 .\" index@integer absolute value, return@@@\f3abs(3C)\f1 .\" index@absolute value, return integer@@@\f3abs(3C)\f1 .\" index@value, return integer absolute@@@\f3abs(3C)\f1 .\" .\" toc@\f3abs(3C)\f1:\0\0\f4abs()\f1, \f4abs()\f1@@@return integer absolute value .\" .\" links@abs.3c labs.3c .\" .\" fileset_database@abs.3c PROGRAMING-MAN .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "accept_focus" "Xt \- Intrinsics Methods" .SH "Name" .Na accept_focus \- Core class method for accepting or rejecting the keyboard focus. .Nz .XX "keyboard: keyboard focus" .XX "accept_focus method" .XX "methods, accept_focus" .XN "keyboard: keyboard focus; (see also accept_focus)" .SH "Synopsis" .Sy typedef Boolean (*XtAcceptFocusProc)(Widget, Time *); .As Widget \f(CIw\fP; Time *\f(CItime\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget. .IP \f(CItime\fP 1i Specifies the X time of the event causing the parent to offer focus to the child. .SS "Returns" \f(CWTrue\fP if the child actually took the focus; \f(CWFalse\fP otherwise. .\" .SH "Description" The \f(CWaccept_focus()\fP method is registered on the \f(CWaccept_focus\fP field of the Core class part structure and is invoked by \f(CWXtCallAcceptFocus()\fP when a parent widget wants to offer keyboard focus to a widget. If the widget wants the keyboard focus, it should take it with the Xlib function \f(CWXSetInputFocus()\fP and return \f(CWTrue\fP. If the widget does not currently want the focus, it should return \f(CWFalse\fP. .LP The ICCCM requires that a widget use \f(CWParent\fP for the \f(CIrevert_to\fP argument to \f(CWXSetInputFocus()\fP. .LP The \f(CWaccept_focus()\fP method is not chained. If a widget class does not define an \f(CWaccept_focus()\fP method, it can use \f(CWXtInheritAcceptFocus\fP to inherit the method from its superclass. If the widget never wants the focus, it should have an \f(CWaccept_focus\fP field of \f(CWNULL\fP. .\" .SH "Usage" Note that this method is an invitation to take the focus, not notification that focus has changed, and not a command to take the focus. .LP A widget that needs to know when it loses the focus can specify translations or event handlers for \f(CWFocusIn\fP and \f(CWFocusOut\fP events. .LP None of the Intrinsics or Xaw widget classes define an \f(CWaccept_focus()\fP method, and none of them ever call \f(CWXtCallAcceptFocus()\fP. .LP An application that wants to direct keyboard events to a particular widget should use \f(CWXtSetKeyboardFocus()\fP. .\" .SH "See Also" .na \s-1\fIXtCallAcceptFocus\fR\s+1\*(s1, \s-1\fIXtSetKeyboardFocus\fR\s+1\*(s1. .ad .\"last line comment .\" $Header: strtoacl.3c,v 78.1 95/12/20 11:16:24 ssa Exp $ .TA s .TH strtoacl 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strtoacl(\|), strtoacl_r(\|), strtoaclpatt(\|), strtoaclpatt_r(\|), aclentrystart[\|] \- convert string form to access control list (\s-1ACL\s0) structure .SH SYNOPSIS .C "#include " .PP .C "int strtoacl(" .nf .PD 0 .IP .C "const char *string," .C "int nentries," .C "int maxentries," .C "struct acl_entry *acl," .C "uid_t fuid," .C "gid_t fgid);" .PD .PP .C "int strtoacl_r(" .nf .PD 0 .IP .C "const char *string," .C "int nentries," .C "int maxentries," .C "struct acl_entry *acl," .C "uid_t fuid," .C "gid_t fgid," .C "char *entrystart[]);" .PD .PP .C "int strtoaclpatt(" .PD 0 .IP .C "const char *string," .C "int maxentries," .C "struct acl_entry_patt *acl);" .PD .PP .C "int strtoaclpatt_r(" .PD 0 .IP .C "const char *string," .C "int maxentries," .C "struct acl_entry_patt *acl" .C "char *entrystart[]);" .PD .fi .SH DESCRIPTION .CR strtoacl() converts an access control list from exact symbolic (string) representation to structure form. It parses the input string and verifies its validity. Optionally it applies the entries in the string as a series of changes to an existing ACL. .PP .CR strtoaclpatt() converts an access control list pattern from symbolic (string) representation to structure form. It parses the input string and verifies its validity. .PP The external array .CR aclentrystart[] , only valid until the next call of either routine, is useful for error reporting. See ERRORS below. .PP The ``operator'' and ``short'' symbolic forms of ACLs and ACL patterns (described in .IR acl (5)) are acceptable as input strings. If the first non-whitespace character in .I string is .CR ( , the ACL or ACL pattern in .I string must be in short form. Otherwise operator form is assumed. .PP .CR strtoacl() takes a pointer to the string to be converted, and a pointer to the first element of an array of ACL entries .RC ( acl[] ) initially containing the indicated number .RI ( nentries ) of valid entries (zero or more). This array can grow to the indicated number of entries .RI ( maxentries ). .CR strtoacl() also takes file user ID .RI ( fuid ) and group ID .RI ( fgid ) values to substitute for .CR "@" characters in .I string and returns the resulting number of entries in .CR acl[] . .PP Redundant entries (identical user ID and group ID values after processing .CR "@" characters) are combined, so that .CR acl[] contains unique entries in the order encountered. If a new entry is mentioned, it is added to the end of the .CR acl array. .SS strtoaclpatt(\|) .CR strtoaclpatt() differs from .CR strtoacl() because it processes an ACL pattern instead of an ACL. Since modification of an existing initial ACL is not useful, it is not supported. .PP Entries with matching user and group ID values are not combined. Each entry input yields one entry in the returned array. .PP The .CR "@" character for user and group IDs (see .IR acl (5)) is converted to special values (\c .CR ACL_FILEOWNER or .CR ACL_FILEGROUP , respectively, defined in .RC < acllib.h >), not to specific user or group names provided by the caller. Thus, .CR strtoaclpatt() need not be called to reparse the ACL pattern for each file, but the caller must handle the special values when comparing an ACL pattern to an ACL. .PP Wildcard user names, group names, and mode values are supported, as are absent mode parts; see .IR acl (5). .PP .CR strtoaclpatt() returns a different structure than .CR strtoacl() . The .I acl_entry_patt structure contains .I onmode and .I offmode masks rather than a single .I mode value. .PP In operator form input, operators have a different effect on .CR strtoaclpatt() : .RS .TP 5 .CR = Sets bits in both the .I onmode and .I offmode fields appropriately, replacing existing bits in the entry, including any set by earlier operators. .TP .CR + Sets bits in .I onmode and clears the same bits in .IR offmode . .TP .CR \- Sets bits in .I offmode and clears the same bits in .IR onmode . .RE .IP In short form input, the mode is treated like the .CR = operator in operator form. .PP For both routines, a non-specific user or group ID of .CR % is converted to .CR ACL_NSUSER or .CR ACL_NSGROUP , respectively. For .CR strtoaclpatt() only, a wildcard user or group ID of .CR * is converted to .CR ACL_ANYUSER or .CR ACL_ANYGROUP , respectively. The values are defined in .RC < acllib.h >. .PP Entries can appear in .I string in any order. .I string can contain redundant entries, and in operator form only, redundant .CR + and .CR \- operators for ACL entry mode modifications (in exact form) or mode bit inclusions/exclusions (in patterns). Entries or modifications are applied left to right. .SS Suggested Use To build a new ACL (ACL pattern) array using .CR strtoacl() .RC ( strtoaclpatt() ), define .CR acl[] with as many entries as desired. Pass it to .CR strtoacl() .RC ( strtoaclpatt() ) with .I nentries set to zero .RC ( strtoacl() only) and .I maxentries set to the number of elements in .CR acl[] . .PP To have .CR strtoacl() modify a file's existing ACL, define .CR acl[] with the maximum possible number of entries .RC ( NACLENTRIES ; see .RC < sys/acl.h >). Call .CR getacl() (see .IR getacl (2)) to read the file's ACL and .CR stat() (see .IR stat (2)) to get the file's owner and group IDs. Then pass the current number of entries, the current ACL, and the ID values to .CR strtoacl() with .I maxentries set to .CR NACLENTRIES . .PP If .CR strtoacl() succeeds, the resulting ACL can be passed safely to .CR setacl() (see .IR setacl (2)) because all redundancies (if any) have been resolved. However, note that since neither .CR strtoacl() nor .CR strtoaclpatt() validate user and group ID values, if the values are not acceptable to the system, .CR setacl() fails. .SS Performance Trick Normally .CR strtoacl() replaces user and group names of .CR "@" with specific user and group ID values, and also combines redundant entries. Therefore, calling .CR stat() and .CR strtoacl() for each of a series of files to which an ACL is being applied is simplest, although time consuming. .PP If .I string contains no .CR "@" character, or if the caller merely wants to compare one ACL against another (and will handle the special case itself), it is sufficient to call .CR strtoacl() once, and pointless to call .CR stat() for each file. To determine this, call .CR strtoacl() the first time with .I fuid set to .CR ACL_FILEOWNER and .I fgid set to .CR ACL_FILEGROUP . Repeated calls with file-specific .I fuid and .I fgid values are needed only if the special values of .I fuid and .I fgid appear in .CR acl[] and the caller needs an exact ACL to set on each file; see EXAMPLES below. .PP If .CR "@" appears in .I string and .CR acl[] will be used later for a call to .CR setacl() , it is necessary to call .CR strtoacl() again to reparse the ACL string for each file. It is possible that not all redundant entries were combined the first time because the .CR "@" names were not resolved to specific IDs. This also complicates comparisons between two ACLs. Furthermore, the caller cannot do the combining later because operator information from operator form input might be lost. .SS Reentrant Interfaces .CR strtoacl_r() and .CR strtoaclpatt_r() require an extra parameter, .IR entrystart , which is used for error reporting. .I entrystart is used in the same way as .CR strtoacl() and .CR strtoaclpatt() use the global array .CR aclentrystart[] . .PP A size of .CR NACLENTRIES + 1 is recommended for the array .IR entrystart . .SH RETURN VALUE If .CR strtoacl() .RC ( strtoaclpatt() ) succeeds, it returns the number of entries in the resulting ACL (ACL pattern), always equal to or greater than .I nentries (zero). .PP .CR strtoaclpatt() also sets values in global array .CR aclentrystart[] to point to the start of each pattern entry it parsed in .IR string , in some cases including leading or trailing whitespace. It only sets a number of pointers equal to its return value plus one (never more than .CR NACLENTRIES + 1). The last valid element points to the null character at the end of .IR string . After calling .CR strtoaclpatt() , an entry pattern's corresponding input string can be used by the caller for error reporting by (temporarily) putting a null at the start of the next entry pattern in .IR string . .SH ERRORS If an error occurs, .CR strtoacl() and .CR strtoaclpatt() return a negative value and the content of .CR acl is undefined (was probably altered). To help with error reporting in this case, .CR aclentrystart[0] and .CR aclentrystart[1] are set to point to the start of the current and next entries, respectively, being parsed when the error occurred. If the current entry does not start with .CR ( , .CR aclentrystart[1] points to the next null character or comma at or after .CR aclentrystart[0] . Otherwise, it points to the next null, or to the character following the next .CR ) . .PP The following values are returned in case of error: .RS .TP 5 \-1 Syntax error: entry doesn't start with .CR ( as expected in short form. .TP \-2 Syntax error: entry doesn't end with .CR ) as expected in short form. .TP \-3 Syntax error: user name is not terminated by a dot. .TP \-4 .RC ( strtoacl() only) Syntax error: group name is not terminated by an operator in operator-form input or a comma in short-form input. .TP \-5 Syntax error: user name is null. .TP \-6 Syntax error: group name is null. .TP \-7 Invalid user name (not found in .CR /etc/passwd file and not a valid number). .TP \-8 Invalid group name (not found in .CR /etc/group file and not a valid number). .TP \-9 Syntax error: invalid mode character, other than .CR 0 ".." 7 , .CR r , .CR w , .CR x , .CR - (allowed in short form only), .CR * (allowed in patterns only), .CR , (to end an entry in operator form), or .CR ) (to end an entry in short form). Or, .CR 0 ".." 7 or .CR * is followed by other mode characters. .TP \-10 The resulting ACL would have more than .I maxentries entries. .RE .SH EXAMPLES The following code fragment converts an ACL from a string to an array of entries using an .I fuid of 103 for the file's owner and .I fgid of 45 for the file's group. .nf .IP .CR #include .IP .CR int nentries; .CR struct acl_entry acl [NACLENTRIES]; .IP .CR "if ((nentries = strtoacl (string, 0, NACLENTRIES, acl, 103, 45)) < 0)" .CR " error (...);" .fi .PP The following code gets the ACL, .IR fuid , and .I fgid for file .CR ../myfile , modifies the ACL using a description string, and changes the ACL on file .CR ../myfile2 to be the new version. .nf .IP .CR #include .CR #include .CR #include .IP .CR "struct stat statbuf;" .CR "int nentries;" .CR "struct acl_entry acl [NACLENTRIES];" .IP .ift .ft 4 .ifn .ft 3 .ps +1 if (stat ("../myfile", & statbuf) < 0) .ft .ps .CR " error (...);" .IP .ift .ft 4 .ifn .ft 3 .ps +1 if ((nentries = getacl ("../myfile", NACLENTRIES, acl)) < 0) .ft .ps .CR " error (...);" .IP .CR "if ((nentries = strtoacl (string, nentries, NACLENTRIES, acl, .CR " statbuf.st_uid, statbuf.st_gid)) < 0)" .CR { .CR " error (...);" .CR } .IP .ift .ft 4 .ifn .ft 3 .ps +1 if (setacl ("../myfile2", nentries, acl) < 0) .ft .ps .CR " error (...);" .fi .PP The following code fragment calls .CR strtoacl() with special values of .I fuid and .IR fgid , then checks to see if they show up in .CR acl[] . .nf .IP .CR #include .IP .CR "int perfile = 0; /* need to stat() and reparse per file? */" .CR "int entry;" .IP .CR "if ((nentries = strtoacl (string, 0, NACLENTRIES, acl," .CR " ACL_FILEOWNER, ACL_FILEGROUP)) < 0)" .CR { .CR " error (...);" .CR } .IP .CR "for (entry = 0; entry < nentries; entry++)" .CR { .CR " if ((acl [entry] . uid == ACL_FILEOWNER)" .CR " || (acl [entry] . gid == ACL_FILEGROUP))" .CR " {" .CR " perfile = 1;" .CR " break;" .CR " }" .CR } .fi .PP The following code fragment converts an ACL pattern from a string to an array of pattern entries. .nf .IP .CR #include .IP .CR "int nentries;" .CR "struct acl_entry_patt acl [NACLENTRIES];" .IP .CR "if ((nentries = strtoaclpatt (string, NACLENTRIES, acl)) < 0)" .CR " error (...);" .fi .PP The following code fragment inside a .CR for loop checks an entry pattern .RC ( p* , .CR onmask , and .CR offmask variable names) against an entry in a file's ACL .RC ( a* variable names) using the file's user and group IDs .RC ( f* variable names). .nf .IP .CR include .CR "if (((puid == ACL_FILEOWNER) && (fuid != auid))" .CR " || ((puid != ACL_ANYUSER) && (puid != auid)))" .CR { .CR " continue;" .CR } .IP .CR "if (((pgid == ACL_FILEGROUP) && (fgid != agid))" .CR " || ((pgid != ACL_ANYGROUP) && (pgid != agid)))" .CR { .CR " continue;" .CR } .IP .CR "if (((( amode) & MODEMASK & onmask ) != onmask)" .CR " || (((~ amode) & MODEMASK & offmask) != offmask))" .CR { .CR " continue;" .CR } .fi .SH WARNINGS .CR strtoacl() and .CR strtoaclpatt() are unsafe in multi-thread applications. .CR strtoacl_r() and .CR strtoaclpatt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR strtoacl() and .CR strtoaclpatt() were developed by HP. .SH FILES .CR /etc/passwd .br .CR /etc/group .SH SEE ALSO getacl(2), setacl(2), acltostr(3C), cpacl(3C), chownacl(3C), setaclentry(3C), acl(5). .\" .\" index@\f4strtoacl()\f1 \- convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@\f4strtoaclpatt()\f1 \- convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@\f4aclentrystart()\f1 \- convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@access control list (ACL) structure, convert string to@@@\f3strtoacl(3C)\f1 .\" index@string, convert to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" .\" toc@\f3strtoacl(3C)\f1:\0\0\f4strtoacl()\f1, \f4strtoaclpatt()\f1@@@convert string to access control list (ACL) structure .\" toc@\f4strtoaclpatt()\f1: convert string to access control list (ACL) structure@@@see \f3strtoacl(3C)\f1 .\" toc@\f4aclentrystart()\f1: convert string to access control list (ACL) structure@@@see \f3strtoacl(3C)\f1 .\" .\" links@strtoacl.3c strtoacl_r.3c .\" links@strtoacl.3c strtoaclpat.3c .\" links@strtoacl.3c aclentrysta.3c .\" $Header: acltostr.3c,v 72.4 94/08/24 22:39:18 ssa Exp $ .TA a .TH acltostr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acltostr(\|), acltostr_r(\|) \- convert access control list (ACL) structure to string form .SH SYNOPSIS .C "#include " .PP .C "char *acltostr(int nentries, const struct acl_entry acl[], int form);" .PP .C "int acltostr_r(" .nf .PD 0 .IP .C "int nentries," .C "const struct acl_entry acl[]," .C "int form," .C "char *strbuf," .C "int length);" .PD .SS Remarks: To ensure continued conformance with emerging industry standards, features described in this manual entry are likely to change in a future release. .SH DESCRIPTION .CR acltostr() converts an access control list from structure form to string representation. .CR acltostr() takes a pointer to the first element of an array of .SM ACL entries .RC ( acl ), containing the indicated number .RI ( nentries ) of valid entries (zero or more), and the output form desired .RC ( FORM_SHORT or .CR FORM_LONG ). It returns a pointer to a static string (overwritten by the next call), which is a symbolic representation of the .SM ACL, ending in a null character. The output forms are described in .IR acl (5). In long form, the string returned contains newline characters. .PP A user .SM ID of .CR ACL_NSUSER and a group .SM ID of .CR ACL_NSGROUP are both represented by .CR % . As with the .CR ls command (see .IR ls (1)), if an entry contains any other user .SM ID or group .SM ID value not listed in .CR /etc/passwd or .CR /etc/group , .CR acltostr() returns a string equivalent of the .SM ID number instead. .PP Just as in routines that manage the .CR /etc/passwd file, .CR acltostr() truncates user and group names to eight characters. .PP Note: .CR acltostr() is complementary in function to .CR strtoacl() . .SS Reentrant Interfaces .CR acltostr_r() expects to be passed two extra parameters: .RS .TP 10 .I strbuf a pointer to a string buffer to store the converted string .TP .I length the length of .I strbuf .RE .PP A length of 512 is recommended. .SH RETURN VALUE If .CR acltostr() succeeds, it returns a pointer to a null-terminated string. If .I nentries is zero or less, the string is of zero length. If .I nentries is greater than .CR NACLENTRIES (defined in .RC < sys/acl.h >), or if .I form is an invalid value, the call returns (char \(**) .SM NULL. .PP If .CR acltostr_r() succeeds, it returns 0. If it fails, it returns -1 and sets .CR errno . If .I nentries is zero or less, the string is of zero length. .SH ERRORS .RS .TP 12 .SM [EINVAL] .I strbuf equals to .CR NULL , or .I nentries is greater than .CR NACLENTRIES (defined in .RC < sys/acl.h ">), or" .I form is not one of the valid forms, or .I length of .I strbuf is too short. .TP .SM [ERANGE] .I length is less than or equal zero. .SH EXAMPLES The following code fragment reads the .SM ACL on file .CR /users/ggd/test and prints its short-form representation. .RS .PP .nf .ift .ft 4 .ifn .ft 3 .ps +1 #include #include int nentries; struct acl_entry acl [NACLENTRIES]; if ((nentries = getacl ("/users/ggd/test", NACLENTRIES, acl)) < 0) error (...); fputs (acltostr (nentries, acl, FORM_SHORT), stdout); .ft .ps .fi .RE .SH WARNINGS The value returned by .CR acltostr() is a pointer into a static buffer, the contents of which are overwritten by each call. Thus, .CR acltostr() is not safe in multi-thread applications. .CR acltostr_r() is MT-Safe and should be used instead. .SH AUTHOR .CR acltostr() was developed by HP. .SH FILES .CR /etc/passwd .br .CR /etc/group .SH SEE ALSO getacl(2), setacl(2), cpacl(3C), chownacl(3C), setaclentry(3C), strtoacl(3C), acl(5). .\" .\" index@\f4acltostr()\fP \- convert access control list (\s-1ACL\s+1) structure to string form@@@\f3acltostr(3C)\f1 .\" index@convert access control list (\s-1ACL\s+1) structure to string form@@@\f3acltostr(3C)\f1 .\" index@access control list (\s-1ACL\s+1) structure, convert to string form@@@\f3acltostr(3C)\f1 .\" index@string form, convert access control list (\s-1ACL\s+1) structure to@@@\f3acltostr(3C)\f1 .\" .\" toc@\f3acltostr(3C)\f1:\0\0\f4acltostr()\fP@@@convert access control list (\s-1ACL\s+1) structure to string form .\" .\" links@acltostr.3c acltostr_r.3c .\" $Header: acltostr.3c,v 72.4 94/08/24 22:39:18 ssa Exp $ .TA a .TH acltostr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acltostr(\|), acltostr_r(\|) \- convert access control list (ACL) structure to string form .SH SYNOPSIS .C "#include " .PP .C "char *acltostr(int nentries, const struct acl_entry acl[], int form);" .PP .C "int acltostr_r(" .nf .PD 0 .IP .C "int nentries," .C "const struct acl_entry acl[]," .C "int form," .C "char *strbuf," .C "int length);" .PD .SS Remarks: To ensure continued conformance with emerging industry standards, features described in this manual entry are likely to change in a future release. .SH DESCRIPTION .CR acltostr() converts an access control list from structure form to string representation. .CR acltostr() takes a pointer to the first element of an array of .SM ACL entries .RC ( acl ), containing the indicated number .RI ( nentries ) of valid entries (zero or more), and the output form desired .RC ( FORM_SHORT or .CR FORM_LONG ). It returns a pointer to a static string (overwritten by the next call), which is a symbolic representation of the .SM ACL, ending in a null character. The output forms are described in .IR acl (5). In long form, the string returned contains newline characters. .PP A user .SM ID of .CR ACL_NSUSER and a group .SM ID of .CR ACL_NSGROUP are both represented by .CR % . As with the .CR ls command (see .IR ls (1)), if an entry contains any other user .SM ID or group .SM ID value not listed in .CR /etc/passwd or .CR /etc/group , .CR acltostr() returns a string equivalent of the .SM ID number instead. .PP Just as in routines that manage the .CR /etc/passwd file, .CR acltostr() truncates user and group names to eight characters. .PP Note: .CR acltostr() is complementary in function to .CR strtoacl() . .SS Reentrant Interfaces .CR acltostr_r() expects to be passed two extra parameters: .RS .TP 10 .I strbuf a pointer to a string buffer to store the converted string .TP .I length the length of .I strbuf .RE .PP A length of 512 is recommended. .SH RETURN VALUE If .CR acltostr() succeeds, it returns a pointer to a null-terminated string. If .I nentries is zero or less, the string is of zero length. If .I nentries is greater than .CR NACLENTRIES (defined in .RC < sys/acl.h >), or if .I form is an invalid value, the call returns (char \(**) .SM NULL. .PP If .CR acltostr_r() succeeds, it returns 0. If it fails, it returns -1 and sets .CR errno . If .I nentries is zero or less, the string is of zero length. .SH ERRORS .RS .TP 12 .SM [EINVAL] .I strbuf equals to .CR NULL , or .I nentries is greater than .CR NACLENTRIES (defined in .RC < sys/acl.h ">), or" .I form is not one of the valid forms, or .I length of .I strbuf is too short. .TP .SM [ERANGE] .I length is less than or equal zero. .SH EXAMPLES The following code fragment reads the .SM ACL on file .CR /users/ggd/test and prints its short-form representation. .RS .PP .nf .ift .ft 4 .ifn .ft 3 .ps +1 #include #include int nentries; struct acl_entry acl [NACLENTRIES]; if ((nentries = getacl ("/users/ggd/test", NACLENTRIES, acl)) < 0) error (...); fputs (acltostr (nentries, acl, FORM_SHORT), stdout); .ft .ps .fi .RE .SH WARNINGS The value returned by .CR acltostr() is a pointer into a static buffer, the contents of which are overwritten by each call. Thus, .CR acltostr() is not safe in multi-thread applications. .CR acltostr_r() is MT-Safe and should be used instead. .SH AUTHOR .CR acltostr() was developed by HP. .SH FILES .CR /etc/passwd .br .CR /etc/group .SH SEE ALSO getacl(2), setacl(2), cpacl(3C), chownacl(3C), setaclentry(3C), strtoacl(3C), acl(5). .\" .\" index@\f4acltostr()\fP \- convert access control list (\s-1ACL\s+1) structure to string form@@@\f3acltostr(3C)\f1 .\" index@convert access control list (\s-1ACL\s+1) structure to string form@@@\f3acltostr(3C)\f1 .\" index@access control list (\s-1ACL\s+1) structure, convert to string form@@@\f3acltostr(3C)\f1 .\" index@string form, convert access control list (\s-1ACL\s+1) structure to@@@\f3acltostr(3C)\f1 .\" .\" toc@\f3acltostr(3C)\f1:\0\0\f4acltostr()\fP@@@convert access control list (\s-1ACL\s+1) structure to string form .\" .\" links@acltostr.3c acltostr_r.3c .\" $Header: acos.3m,v 78.1 96/02/13 09:22:34 ssa Exp $ .TA a .TH acos 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acos(\|), acosf(\|) \- arccosine functions .SH SYNOPSIS .C "#include " .PP .C "double acos(double x);" .PP .C "float acosf(float x);" .SH DESCRIPTION .CR acos() returns the arccosine of .I x .ift in the range 0 to \(*p. .ifn in the range 0 to pi. .PP .CR acosf() is a .CR float version of .CR acos() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR acosf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is NaN, .CR acos() returns NaN. .PP If the magnitude of .I x is greater than one, .CR acos() returns zero and sets .CR errno to [EDOM]. .SH ERRORS If .CR acos() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] The magnitude of .I x is greater than one. .RE .SH DEPENDENCIES Millicode versions of the .CR acos() function are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO acosd(3M), sin(3M), cos(3M), tan(3M), asin(3M), atan(3M), atan2(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR acos() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4acos()\f1 \- arccosine function@@@\f3acos(3M)\f1 .\" index@\f4acosf()\f1 \- arccosine function (float)@@@\f3acos(3M)\f1 .\" index@\f1math: arccosine functions@@@\f3acos(3M)\f1 .\" index@\f1trigonometric arccosine functions@@@\f3acos(3M)\f1 .\" index@\f1arccosine functions@@@\f3acos(3M)\f1 .\" .\" toc@\f3acos(3M)\f1:\0\0\f4acos()\f1, \f4acosf()\f1@@@arccosine functions .\" toc@\f4acosf()\f1:\0\0arccosine function (float)@@@see \f3acos(3M)\f1 .\" .\" links@acos.3m acosf.3m .\" .\" fileset_database@acos.3m PROGRAMING-MAN .\" $Header: acosd.3m,v 78.1 96/02/13 09:28:25 ssa Exp $ .TA a .TH acosd 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acosd(\|), acosdf(\|) \- degree-valued arccosine functions .SH SYNOPSIS .C "#include " .PP .C "double acosd(double x);" .PP .C "float acosdf(float x);" .SH DESCRIPTION .CR acosd() is a degree-valued version of the .CR acos() function. It returns the arccosine of .I x in the range 0 to 180. .PP .CR acosdf() is a .CR float version of .CR acosd() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR acosd() and .CR acosdf() are not specified by any standard, but .CR acosdf() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is NaN, .CR acosd() returns NaN. .PP If the magnitude of .I x is greater than one, .CR acosd() returns zero and sets .CR errno to [EDOM]. .SH ERRORS If .CR acosd() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] The magnitude of .I x is greater than one. .RE .SH SEE ALSO acos(3M), sind(3M), cosd(3M), tand(3M), asind(3M), atand(3M), atan2d(3M), isinf(3M), isnan(3M). .\" index@\f4acosd()\f1 \- arccosine function (degrees)@@@\f3acosd(3M)\f1 .\" index@\f4acosdf()\f1 \- arccosine function (float, degrees)@@@\f3acosd(3M)\f1 .\" index@\f1math: arccosine functions (degrees)@@@\f3acosd(3M)\f1 .\" index@\f1degree-valued arccosine functions@@@\f3acosd(3M)\f1 .\" index@\f1trigonometric arccosine functions (degrees)@@@\f3acosd(3M)\f1 .\" index@\f1arccosine functions (degrees)@@@\f3acosd(3M)\f1 .\" .\" toc@\f3acosd(3M)\f1:\0\0\f4acosd()\f1, \f4acosdf()\f1@@@degree-valued arccosine functions .\" toc@\f4acosdf()\f1:\0\0arccosine function (float, degrees)@@@see \f3acosd(3M)\f1 .\" .\" links@acosd.3m acosdf.3m .\" .\" fileset_database@acosd.3m PROGRAMING-MAN .\" $Header: acosd.3m,v 78.1 96/02/13 09:28:25 ssa Exp $ .TA a .TH acosd 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acosd(\|), acosdf(\|) \- degree-valued arccosine functions .SH SYNOPSIS .C "#include " .PP .C "double acosd(double x);" .PP .C "float acosdf(float x);" .SH DESCRIPTION .CR acosd() is a degree-valued version of the .CR acos() function. It returns the arccosine of .I x in the range 0 to 180. .PP .CR acosdf() is a .CR float version of .CR acosd() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR acosd() and .CR acosdf() are not specified by any standard, but .CR acosdf() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is NaN, .CR acosd() returns NaN. .PP If the magnitude of .I x is greater than one, .CR acosd() returns zero and sets .CR errno to [EDOM]. .SH ERRORS If .CR acosd() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] The magnitude of .I x is greater than one. .RE .SH SEE ALSO acos(3M), sind(3M), cosd(3M), tand(3M), asind(3M), atand(3M), atan2d(3M), isinf(3M), isnan(3M). .\" index@\f4acosd()\f1 \- arccosine function (degrees)@@@\f3acosd(3M)\f1 .\" index@\f4acosdf()\f1 \- arccosine function (float, degrees)@@@\f3acosd(3M)\f1 .\" index@\f1math: arccosine functions (degrees)@@@\f3acosd(3M)\f1 .\" index@\f1degree-valued arccosine functions@@@\f3acosd(3M)\f1 .\" index@\f1trigonometric arccosine functions (degrees)@@@\f3acosd(3M)\f1 .\" index@\f1arccosine functions (degrees)@@@\f3acosd(3M)\f1 .\" .\" toc@\f3acosd(3M)\f1:\0\0\f4acosd()\f1, \f4acosdf()\f1@@@degree-valued arccosine functions .\" toc@\f4acosdf()\f1:\0\0arccosine function (float, degrees)@@@see \f3acosd(3M)\f1 .\" .\" links@acosd.3m acosdf.3m .\" .\" fileset_database@acosd.3m PROGRAMING-MAN .\" $Header: acos.3m,v 78.1 96/02/13 09:22:34 ssa Exp $ .TA a .TH acos 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acos(\|), acosf(\|) \- arccosine functions .SH SYNOPSIS .C "#include " .PP .C "double acos(double x);" .PP .C "float acosf(float x);" .SH DESCRIPTION .CR acos() returns the arccosine of .I x .ift in the range 0 to \(*p. .ifn in the range 0 to pi. .PP .CR acosf() is a .CR float version of .CR acos() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR acosf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is NaN, .CR acos() returns NaN. .PP If the magnitude of .I x is greater than one, .CR acos() returns zero and sets .CR errno to [EDOM]. .SH ERRORS If .CR acos() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] The magnitude of .I x is greater than one. .RE .SH DEPENDENCIES Millicode versions of the .CR acos() function are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO acosd(3M), sin(3M), cos(3M), tan(3M), asin(3M), atan(3M), atan2(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR acos() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4acos()\f1 \- arccosine function@@@\f3acos(3M)\f1 .\" index@\f4acosf()\f1 \- arccosine function (float)@@@\f3acos(3M)\f1 .\" index@\f1math: arccosine functions@@@\f3acos(3M)\f1 .\" index@\f1trigonometric arccosine functions@@@\f3acos(3M)\f1 .\" index@\f1arccosine functions@@@\f3acos(3M)\f1 .\" .\" toc@\f3acos(3M)\f1:\0\0\f4acos()\f1, \f4acosf()\f1@@@arccosine functions .\" toc@\f4acosf()\f1:\0\0arccosine function (float)@@@see \f3acos(3M)\f1 .\" .\" links@acos.3m acosf.3m .\" .\" fileset_database@acos.3m PROGRAMING-MAN .\" $Header: acosh.3m,v 78.1 96/02/13 09:33:39 ssa Exp $ .TA a .TH acosh 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acosh(\|) \- inverse hyperbolic cosine function .SH SYNOPSIS .C "#include " .PP .C "double acosh(double x);" .SH DESCRIPTION The .CR acosh() function computes the inverse hyperbolic cosine of its argument. .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE .PP If .I x is +INFINITY, .CR acosh() returns +INFINITY. .PP If .I x is NaN, .CR acosh() returns NaN. .PP If .I x < 1.0, .CR acosh() returns NaN and sets .CR errno to [EDOM]. .SH ERRORS If .CR acosh() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] .I x is less than 1.0. .RE .SH SEE ALSO cosh(3M), asinh(3M), atanh(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR acosh() ": SVID3, XPG4.2" .\" index@\f4acosh()\f1 \- inverse hyperbolic cosine function@@@\f3acosh(3M)\f1 .\" index@math: inverse hyperbolic cosine function@@@\f3acosh(3M)\f1 .\" index@inverse hyperbolic cosine function@@@\f3acosh(3M)\f1 .\" index@hyperbolic cosine function, inverse@@@\f3acosh(3M)\f1 .\" index@cosine function, inverse hyperbolic@@@\f3acosh(3M)\f1 .\" .\" toc@\f3acosh(3M)\f1:\0\0\f4acosh()\f1@@@inverse hyperbolic cosine function .\" $Header: add_wch.3x,v 76.2 95/07/31 11:12:51 ssa Exp $ .TA a .TH add_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME add_wch, mvadd_wch, mvwadd_wch, wadd_wch \(em add a complex character and rendition to a window .SH SYNOPSIS .C "#include " .P .C "int add_wch(cchar_t *const \f2wch\fP);" .P .C "int wadd_wch(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "int mvadd_wch(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .P .C "int mvwadd_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .SH DESCRIPTION These functions add information to the current or specified window at the current or specified position, and then advance the cursor. These functions perform wrapping. These functions perform special-character processing. .RS .TP 3 .C \(bu If \f2wch\f1 refers to a spacing character, then any previous character at that location is removed, a new character specified by \f2wch\f1 is placed at that location with rendition specified by \f2wch\fP; then the cursor advances to the next spacing character on the screen. .TP .C \(bu If \f2wch\f1 refers to a non-spacing character, all previous characters at that location are preserved, the non-spacing characters of \f2wch\f1 are added to the spacing complex character, and the rendition specified by \f2wch\f1 is ignored. .RE .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Rendition of Characters Placed into a Window\f1 in curses_intro, addch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4add_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f4mvadd_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f4mvwadd_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f4wadd_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f1add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f1character and rendition to a window, add a complex@@@\f3add_wch(3X)\f1 .\" index@\f1complex character and rendition, add to a window@@@\f3add_wch(3X)\f1 .\" .\" toc@\f3add_wch(3X)\f1:\0\0\f4add_wch()\f1, \f4mvadd_wch()\f1, \f4mvwadd_wch()\f1, \n\f4wadd_ch()\f1@@@add a complex character and rendition to a window .\" toc@\f4mvadd_wch()\f1: add a complex character and rendition to a window@@@see \f3add_wch(3X)\f1 .\" toc@\f4mvwadd_wch()\f1: add a complex character and rendition to a window@@@see \f3add_wch(3X)\f1 .\" toc@\f4wadd_wch()\f1: add a complex character and rendition to a window@@@see \f3add_wch(3X)\f1 .\" .\" links@add_wch.3x mvadd_wch.3x .\" links@add_wch.3x mvwadd_wch.3x .\" links@add_wch.3x wadd_wch.3x .\" .\" fileset_database@add_wch.3x CURS-ENG-A-MAN .\" $Header: add_wchnstr.3x,v 76.2 95/07/31 11:15:08 ssa Exp $ .TA a .TH add_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME add_wchnstr, add_wchstr, mvadd_wchnstr, mvadd_wchstr, mvwadd_wchnstr, mvwadd_wchstr, wadd_wchnstr, wadd_wchstr \(em add an array of complex characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int add_wchnstr(cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int add_wchstr(cchar_t *const \f2wchstr\fP);" .P .C "int wadd_wchnstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int wadd_wchstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvadd_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int mvadd_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvwadd_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP," .br .C " int \f2n\fP);" .P .C "int mvwadd_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .SH DESCRIPTION These functions write the array of \f3cchar_t\f1 specified by \f2wchstr\f1 into the current or specified window starting at the current or specified cursor position. .P These functions do not advance the cursor. The results are unspecified if \f2wchstr\f1 contains any special characters. .P The functions end successfully on encountering a null \f3cchar_t\f1. The functions also end successfully when they fill the current line. If a character cannot completely fit at the end of the current line, those columns are filled with the background character and rendition. .P The .CR add_wchnstr() , .CR mvadd_wchnstr() , .CR mvwadd_wchnstr() and .CR wadd_wchnstr() functions end successfully after writing \f2n\f1 \f3cchar_t\fPs (or the entire array of \f3cchar_t\fPs, if \f2n\f1 is \(mi1). .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3add_wchnstr(3X)\f1:\0\0\f4add_wchstr()\f1, \f4mvadd_wchnstr()\f1, \f4mvadd_wchstr()\f1, \f4mvwadd_wchnstr()\f1,\n\f4mvwadd_wchstr\f1, \f4wadd_wchnstr\f1, \n\f4wadd_wchstr\f1@@@add an array of complex characters and renditions to a window .\" toc@\f4add_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" .\" index@\f4add_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4add_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1an array of complex characters and renditions to a window, add@@@\f3add_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, add an array of, to a window@@@\f3add_wchnstr(3X)\f1 .\" .\" links@add_wchnstr.3x add_wchstr.3x .\" links@add_wchnstr.3x mvadd_wchnstr.3x .\" links@add_wchnstr.3x mvadd_wchstr.3x .\" links@add_wchnstr.3x mvwadd_wchnstr.3x .\" links@add_wchnstr.3x mvwadd_wchstr.3x .\" links@add_wchnstr.3x wadd_wchnstr.3x .\" links@add_wchnstr.3x wadd_wchstr.3x .\" .\" fileset_database@add_wchnstr.3x CURS-ENG-A-MAN .\" $Header: add_wchnstr.3x,v 76.2 95/07/31 11:15:08 ssa Exp $ .TA a .TH add_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME add_wchnstr, add_wchstr, mvadd_wchnstr, mvadd_wchstr, mvwadd_wchnstr, mvwadd_wchstr, wadd_wchnstr, wadd_wchstr \(em add an array of complex characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int add_wchnstr(cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int add_wchstr(cchar_t *const \f2wchstr\fP);" .P .C "int wadd_wchnstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int wadd_wchstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvadd_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int mvadd_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvwadd_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP," .br .C " int \f2n\fP);" .P .C "int mvwadd_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .SH DESCRIPTION These functions write the array of \f3cchar_t\f1 specified by \f2wchstr\f1 into the current or specified window starting at the current or specified cursor position. .P These functions do not advance the cursor. The results are unspecified if \f2wchstr\f1 contains any special characters. .P The functions end successfully on encountering a null \f3cchar_t\f1. The functions also end successfully when they fill the current line. If a character cannot completely fit at the end of the current line, those columns are filled with the background character and rendition. .P The .CR add_wchnstr() , .CR mvadd_wchnstr() , .CR mvwadd_wchnstr() and .CR wadd_wchnstr() functions end successfully after writing \f2n\f1 \f3cchar_t\fPs (or the entire array of \f3cchar_t\fPs, if \f2n\f1 is \(mi1). .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3add_wchnstr(3X)\f1:\0\0\f4add_wchstr()\f1, \f4mvadd_wchnstr()\f1, \f4mvadd_wchstr()\f1, \f4mvwadd_wchnstr()\f1,\n\f4mvwadd_wchstr\f1, \f4wadd_wchnstr\f1, \n\f4wadd_wchstr\f1@@@add an array of complex characters and renditions to a window .\" toc@\f4add_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" .\" index@\f4add_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4add_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1an array of complex characters and renditions to a window, add@@@\f3add_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, add an array of, to a window@@@\f3add_wchnstr(3X)\f1 .\" .\" links@add_wchnstr.3x add_wchstr.3x .\" links@add_wchnstr.3x mvadd_wchnstr.3x .\" links@add_wchnstr.3x mvadd_wchstr.3x .\" links@add_wchnstr.3x mvwadd_wchnstr.3x .\" links@add_wchnstr.3x mvwadd_wchstr.3x .\" links@add_wchnstr.3x wadd_wchnstr.3x .\" links@add_wchnstr.3x wadd_wchstr.3x .\" .\" fileset_database@add_wchnstr.3x CURS-ENG-A-MAN .\" $Header: addch.3x,v 76.2 95/07/28 16:16:36 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addch, mvaddch, mvwaddch, waddch \(em add a single-byte character and rendition to a window and advance the cursor .SH SYNOPSIS .C "#include " .P .C "int addch(const chtype \f2ch\fP);" .P .C "int mvaddch(int \f2y\fP, int \f2x\fP, const chtype \f2ch\fP);" .P .C "int mvwaddch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, const chtype \f2ch\fP);" .P .C "int waddch(WINDOW *\f2win\fP, const chtype \f2ch\fP);" .SH DESCRIPTION The .CR addch() , .CR mvaddch() , .CR mvwaddch() and .CR waddch() functions place \f2ch\f1 into the current or specified window at the current or specified position, and then advance the window's cursor position. These functions perform wrapping. These functions perform special-character processing. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" \f3Rendition of Characters Placed into a Window\f1 in curses_intro, add_wch(), attroff(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The entry is rewritten for clarity. Also the type of argument \f2ch\f1 is changed from \f3chtype\f1 to \f3const chtype\f1. .\" .\" toc@\f3addch(3X)\f1:\0\0\f4addch()\f1, \f4mvaddch()\f1, \f4mvwaddch()\f1, \f4waddch\f1\n@@@add a single-byte character and rendition to a window and advance the cursor .\" toc@\f4mvaddch()\f1: add a single-byte character and rendition to a window and advance the cursor@@@see \f3addch(3X)\f1 .\" toc@\f4mvwaddch()\f1: add a single-byte character and rendition to a window and advance the cursor@@@see \f3addch(3X)\f1 .\" toc@\f4waddch()\f1: add a single-byte character and rendition to a window and advance the cursor@@@see \f3addch(3X)\f1 .\" .\" index@\f4addch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f4mvaddch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f4mvwaddch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f4waddch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f1add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f1single-byte character and rendition, add, to a window and advance the cursor@@@\f3addch(3X)\f1 .\" .\" links@addch.3x mvaddch.3x .\" links@addch.3x mvwaddch.3x .\" links@addch.3x waddch.3x .\" .\" fileset_database@addch.3x CURS-ENG-A-MAN .\" $Header: addchnstr.3x,v 76.2 95/07/31 11:17:15 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addchnstr, mvaddchnstr, mvwaddchnstr, waddchnstr \(em add length limited string of single-byte characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int addchnstr(chtype *const \f2chstr\fP, int \f2n\fP);" .P .C "int mvaddchnstr(int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP, int \f2n\fP);" .P .C "int mvwaddchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP," .br .C " int \f2n\fP);" .P .C "int waddchnstr(WINDOW *\f2win\fP, chtype *const \f2chstr\fP, int \f2n\fP);" .SH DESCRIPTION These functions overlay the contents of the current or specified window, starting at the current or specified position, with the contents of the array pointed to by .I chstr until a null .B chtype is encountered in the array pointed to by .I chstr . .P These functions do not change the cursor position. These functions do not perform special-character processing. These functions do not perform wrapping. .P These functions copy at most \f2n\f1 items, but no more than will fit on the line. If \f2n\f1\ is \(mi1 then the whole string is copied, to the maximum number that fit on the line. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" addch(), add_wch(), add_wchstr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addchnstr(3X)\f1:\0\0\f4mvaddchnstr()\f1, \f4mvwaddchnstr()\f1, \f4waddchnstr()\f1\n@@@add length limited string of single-byte characters and renditions to a window .\" toc@\f4mvaddchnstr()\f1: add length limited string of single-byte characters and renditions to a window\n@@@see \f3addchnstr(3X)\f1 .\" toc@\f4mvwaddchnstr()\f1: add length limited string of single-byte characters and renditions to a window\n@@@see \f3addchnstr(3X)\f1 .\" toc@\f4waddchnstr()\f1: add length limited string of single-byte characters and renditions to a window\n@@@see \f3addchnstr(3X)\f1 .\" .\" index@\f4addchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window@@@\f3addchnstr(3X)\f1 .\" index@\f4mvaddchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window\n@@@\f3addchnstr(3X)\f1 .\" index@\f4mvwaddchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window\n@@@\f3addchnstr(3X)\f1 .\" index@\f4waddchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window@@@\f3addchnstr(3X)\f1 .\" index@\f1add length limited string of single-byte characters and renditions to a window@@@\f3addchnstr(3X)\f1 .\" index@\f1length limited string of single-byte characters and renditions to a window, add@@@\f3addchnstr(3X)\f1 .\" index@\f1single-byte characters and renditions to a window, add length limited string of@@@\f3addchnstr(3X)\f1 .\" .\" links@addchnstr.3x mvaddchnstr.3x .\" links@addchnstr.3x mvwaddchnstr.3x .\" links@addchnstr.3x waddchnstr.3x .\" .\" fileset_database@addchnstr.3x CURS-ENG-A-MAN .\" $Header: addchstr.3x,v 76.2 95/07/31 11:19:11 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addchstr 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addchstr, mvaddchstr, mvwaddchstr, waddchstr \(em add string of single-byte characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int addchstr(chtype *const \f2chstr\fP);" .P .C "int mvaddchstr(int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP);" .P .C "int mvwaddchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP);" .P .C "int waddchstr(WINDOW *\f2win\fP, chtype *const \f2chstr\fP);" .SH DESCRIPTION These functions overlay the contents of the current or specified window, starting at the current or specified position, with the contents of the array pointed to by .I chstr until a null .CR chtype is encountered in the array pointed to by .IR chstr . .P These functions do not change the cursor position. These functions do not perform special-character processing. These functions do not perform wrapping. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" addch(), addchnstr(), add_wch(), add_wchstr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addchstr(3X)\f1:\0\0\f4mvaddchstr()\f1, \f4mvwaddchstr()\f1, \f4waddchstr()\f1\n@@@add string of single-byte characters and renditions to a window .\" toc@\f4mvaddchstr()\f1: add string of single-byte characters and renditions to a window@@@see \f3addchstr(3X)\f1 .\" toc@\f4mvwaddchstr()\f1: add string of single-byte characters and renditions to a window@@@see \f3addchstr(3X)\f1 .\" toc@\f4waddchstr()\f1: add string of single-byte characters and renditions to a window@@@see \f3addchstr(3X)\f1 .\" .\" index@\f4addchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f4mvaddchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f4mvwaddchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f4waddchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f1add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f1string of single-byte characters and renditions to a window, add@@@\f3addchstr(3X)\f1 .\" index@\f1single-byte characters and renditions to a window, add string of@@@\f3addchstr(3X)\f1 .\" .\" links@addchstr.3x mvaddchstr.3x .\" links@addchstr.3x mvwaddchstr.3x .\" links@addchstr.3x waddchstr.3x .\" .\" fileset_database@addchstr.3x CURS-ENG-A-MAN .\" $Header: exportent.3n,v 74.1 95/01/25 16:26:52 ssa Exp $ .TA e .TH exportent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME exportent(\|), getexportent(\|), setexportent(\|), addexportent(\|), remexportent(\|), endexportent(\|), getexportopt(\|) \- access exported file system information .SH SYNOPSIS .nf .C #include .C #include .PP .C "FILE *setexportent();" .PP .C "struct exportent *getexportent(FILE *fildep);" .PP .C "int addexportent(FILE *filep, char *dirname, char *options);" .PP .C "int remexportent(FILE *filep, char *dirname);" .PP .C "char *getexportopt(struct exportent *xent, char *opt);" .PP .C "void endexportent(FILE *filep);" .fi .SH DESCRIPTION These routines access the exported filesystem information in .CR /etc/xtab . .ift .TP 22 .ifn .TP 10 .C setexportent() Open the export information file and return a file pointer to use with .CR getexportent() , .CR addexportent() , .CR remexportent() , and .CR endexportent() . Returns .SM NULL if the file is locked or if an error is encountered in opening the file. .TP .C getexportent() Read the next line from .I filep and return a pointer to an object with the following structure containing the broken-out fields of a line in file .CR /etc/xtab . The fields have meanings described in .IR exports (4). .nf .IP .ift .ft 4 .ifn .ft 3 #define ACCESS_OPT "access" /* machines that can mount fs */ #define ROOT_OPT "root" /* machines with root access to fs */ #define RO_OPT "ro" /* export read-only */ #define ANON_OPT "anon" /* uid for anonymous requests */ #define ASYNC_OPT "async" /* all mounts will be aynchronous */ .ift .sp .5v .ifn .sp 1v struct exportent { char *xent_dirname; /* directory (or file) to export */ char *xent_options; /* options, as above */ }; .ft .fi .IP .C getexportent() returns .SM NULL if it encounters end of file. .TP .C addexportent() Add the .I exportent to the end of the open file .IR filep . It returns 0 if successful and \(mi1 on failure. .TP .C remexportent() Remove the indicated entry from the list. Returns 0 on success and \(mi1 on failure. .TP .C getexportopt() Scans the .C xent_options field of the .C exportent structure for a substring that matches .IR opt . Returns the string value of .IR opt , or .SM NULL if the option is not found. .TP .C endexportent() Close the file. .SH RETURN VALUE .CR setexportent() , .CR getexportent() , and .C getexportopt() return a .SM NULL pointer on .SM EOF or error. .PP .C addexportent() and .C remexportent() return \(mi1 if they fail. .SH WARNINGS The returned .C exportent structure points to static information that is overwritten in each call. .SH AUTHOR .CR exportent , .CR getexportent() , .CR setexportent() , .CR addexportent() , .CR remexportent() , .CR endexportent() , and .C getexportopt() were developed by Sun Microsystems, Inc. .SH FILES .C /etc/exports .C /etc/xtab .SH SEE ALSO exportfs(1M), exports(4). .\" .\" toc@\f3exportent(3N)\f1:\0\0\f4exportent(\|)\f1, \f4getexportent(\|)\f1, \f4setexportent(\|)\f1, \f4addexportent(\|)\f1, \f4remexportent(\|)\f1,\n\f4endexportent(\|)\f1, \f4getexportopt(\|)\f1@@@access exported file system information .\" toc@\f4getexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4setexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4addexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4remexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4endexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4getexportopt(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" .\" index@\f4exportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4getexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4setexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4addexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4remexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4endexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4getexportopt(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@access exported file system information@@@\f3exportent(3N)\f1 .\" index@exported file system information, access@@@\f3exportent(3N)\f1 .\" index@file system information, access exported@@@\f3exportent(3N)\f1 .\" index@information, access exported file system@@@\f3exportent(3N)\f1 .\" .\" links@exportent.3n getexporten.3n .\" links@exportent.3n setexporten.3n .\" links@exportent.3n addexporten.3n .\" links@exportent.3n remexporten.3n .\" links@exportent.3n endexporten.3n .\" links@exportent.3n getexportop.3n .\" .\" fileset_database@exportent.3n PROGRAMING-MAN .\" $Header: getmntent.3x,v 76.1 95/07/05 17:29:38 ssa Exp $ .TA g .TH getmntent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getmntent(\|), getmntent_r(\|), setmntent(\|), addmntent(\|), endmntent(\|), hasmntopt(\|) \- get file system descriptor file entry .SH SYNOPSIS .C "#include " .PP .C "\s-1FILE\s0 \(**setmntent(const char \(**path, char \(**type);" .PP .C "struct mntent \(**getmntent(\s-1FILE\s0 \(**stream);" .PP .C "int getmntent_r(" .nf .PD 0 .IP .C "\s-1FILE\s0 *stream," .C "struct mntent *result," .C "char *buffer," .C "int buflen);" .PD .PP .C "int addmntent(\s-1FILE\s0 \(**stream, struct mntent \(**mnt);" .PP .C "char \(**hasmntopt(struct mntent \(**mnt, const char \(**opt);" .PP .C "int endmntent(\s-1FILE\s0 \(**stream);" .SH DESCRIPTION These routines replace the obsolete .C getfsent() routines (see .IR getfsent (3X)) for accessing the file system description file .CR /etc/fstab . They are also used to access the mounted file system description file .CR /etc/mnttab . .TP 20 .C setmntent() Opens a file system description file and returns a file pointer which can then be used with .CR getmntent() , .CR addmntent() , or .CR endmntent() . The .I type argument is the same as in .IR fopen (3C). .TP .C getmntent() Reads the next line from .I stream and returns a pointer to an object with the following structure containing the broken-out fields of a line in the file-system description file, .RC < mntent.h >. The fields have meanings described in .IR fstab (4). .nf .IP .C struct mntent { .C " char *mnt_fsname; /* file system name */" .C " char *mnt_dir; /* file system path prefix */" .C " char *mnt_type; /* hfs, nfs, swap, or xx */" .C " char *mnt_opts; /* ro, suid, etc. */" .C " int mnt_freq; /* dump frequency, in days */" .C " int mnt_passno; /* pass number on parallel fsck */" .C " long mnt_time; /* When file system was mounted; */" .C " /* see mnttab(4). */" .C " /* (0 for NFS) */" .C }; .ft .ps .fi .IP .TP .C getmntent_r() Uses three extra parameters to provide results equivalent to those produced by .CR getmntent() . The extra parameters are: .PD 0 .IP 1. The address of a .C "struct mntent" where the result will be stored. .IP 2. A buffer to store character strings to which fields in the .C "struct mntent" will point. .IP 3. The length of the user-supplied buffer. A buffer length of 1025 is recommended. .PD .TP .C addmntent() Adds the .C mntent structure .I mnt to the end of the open file .IR stream . Note that .I stream must be opened for writing. .TP .C hasmntopt() Scans the .C mnt_opts field of the .C mntent structure .I mnt for a substring that matches .IR opt . It returns the address of the substring if a match is found; .C 0 otherwise. .TP .C endmntent() Closes the file. .PP The following definitions are provided in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNT_CHECKLIST "/etc/fstab" #define MNT_MNTTAB "/etc/mnttab" #define MNTMAXSTR 128 /* Max size string in mntent */ #define MNTTYPE_HFS "hfs" /* HFS file system */ #define MNTTYPE_CDFS "hfs" /* CD-ROM file system */ #define MNTTYPE_NFS "nfs" /* Network file system */ #define MNTTYPE_SWAP "swap" /* Swap device */ #define MNTTYPE_SWAPFS "swapfs" /* File system swap */ #define MNTTYPE_IGNORE "ignore" /* Ignore this entry */ #define MNTOPT_DEFAULTS "defaults" /* Use all default options */ #define MNTOPT_RO "ro" /* Read only */ #define MNTOPT_RW "rw" /* Read/write */ #define MNTOPT_SUID "suid" /* Set uid allowed */ #define MNTOPT_NOSUID "nosuid" /* No set uid allowed */ #define MNTOPT_QUOTA "quota" /* Enable disk quotas */ #define MNTOPT_NOQUOTA "noquota" /* Disable disk quotas */ .ft .ps .fi .RE .PP The following definition is provided for device swap in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_END "end" /* swap after end of file system, Series 300/400/700 only */ .ft .ps .fi .RE .PP The following definitions are provided for file system swap in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_MIN "min" /* minimum file system swap */ #define MNTOPT_LIM "lim" /* maximum file system swap */ #define MNTOPT_RES "res" /* reserve space for file system */ #define MNTOPT_PRI "pri" /* file system swap priority */ .ft .ps .RE .PP .SH NETWORKING FEATURES .SS NFS The following definitions are provided in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_BG "bg" /* Retry mount in background */ #define MNTOPT_FG "fg" /* Retry mount in foreground */ #define MNTOPT_RETRY "retry" /* Number of retries allowed */ #define MNTOPT_RSIZE "rsize" /* Read buffer size in bytes */ #define MNTOPT_WSIZE "wsize" /* Write buffer size in bytes*/ #define MNTOPT_TIMEO "timeo" /* Timeout in 1/10 seconds */ #define MNTOPT_RETRANS "retrans" /* Number of retransmissions */ #define MNTOPT_PORT "port" /* Server's IP NFS port */ #define MNTOPT_SOFT "soft" /* Soft mount */ #define MNTOPT_HARD "hard" /* Hard mount */ #define MNTOPT_INTR "intr" /* Interruptable hard mounts */ #define MNTOPT_NOINTR "nointr" /* Uninterruptable hard mounts*/ #define MNTOPT_DEVS "devs" /* Device file access allowed */ #define MNTOPT_NODEVS "nodevs" /* No device file access allowed */ .ft .ps .fi .TE .SH RETURN VALUE .TP 20 .C setmntent() Returns a null pointer on error. .TP .C getmntent() Returns a null pointer on error or EOF. Otherwise, .C getmntent() returns a pointer to a mntent structure. Some of the fields comprising a mntent structure are optional in .C /etc/fstab and .CR /etc/mnttab . In the supplied structure, such missing character pointer fields are set to NULL and missing integer fields are set to \(mi1 for .C mnt_freq and .C mnt_passno. If the integer field for .C mnt_time is missing, it is set to 0. .TP .C getmntent_r() Returns a .C -1 on error or EOF, or if the supplied buffer is of insufficient length. If the operation is successful, .C 0 is returned. .TP .C addmntent() Returns .C 1 on error. .TP .C endmntent() Returns .CR 1 . .SH WARNINGS The return value for .C getmntent() points to static information that is overwritten in each call. Thus, .C getmntent() is unsafe for multi-thread applications. .C getmntent_r() is MT-Safe and should be used instead. .SH AUTHOR .CR addmntent() , .CR endmntent() , .CR getmntent() , .CR hasmntopt() , and .C setmntent() were developed by The University of California, Berkeley, Sun Microsystems, Inc., and HP. .SH FILES .C /etc/fstab .br .C /etc/mnttab .SH SEE ALSO fstab(4), getfsent(3X), mnttab(4). .\" .\" index@\f4getmntent()\f1 \- get a file system description file entry@@@\f3getmntent(3X)\f1 .\" index@\f4setmntent()\f1 \- open a file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4addmntent()\f1 \- add entry to open file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4endmntent()\f1 \- close file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4hasmntopt()\f1 \- search mount option field in file system description file@@@\f3getmntent(3X)\f1 .\" index@file system description file entry@@@\f3getmntent(3X)\f1 .\" index@file entry get file system description@@@\f3getmntent(3X)\f1 .\" index@get file system description file@@@\f3getmntent(3X)\f1 .\" .\" toc@\f3getmntent(3X)\f1:\0\0\f4getmntent()\f1, \f4getmntent_r()\f1, \f4setmntent()\f1, \f4addmntent()\f1, \f4endmntent()\f1, \n\f4hasmntopt()\f1@@@get file system descriptor file entry .\" toc@\f4setmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4addmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4endmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4hasmntopt()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" .\" links@getmntent.3x getmntent_r.3x .\" links@getmntent.3x setmntent.3x .\" links@getmntent.3x addmntent.3x .\" links@getmntent.3x endmntent.3x .\" links@getmntent.3x hasmntopt.3x .\ .\" fileset_database@getmntent.3x PROGRAMING-MAN .\" $Header: addnstr.3x,v 76.2 95/07/31 11:20:19 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnstr, addstr, mvaddnstr, mvaddstr, mvwaddnstr, mvwaddstr waddnstr, waddstr \(em add a string of multi-byte characters without rendition to a window and advance cursor .SH SYNOPSIS .C "#include " .P .C "int addnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int addstr(char *const \f2str\fP);" .P .C "int mvaddnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvaddstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwaddnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwaddstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int waddnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int waddstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions write the characters of the string \f2str\f1 on the current or specified window starting at the current or specified position using the background rendition. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions are similar to calling .CR mbstowcs() on \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .P The .CR addnstr() , .CR mvaddnstr() , .CR mvwaddnstr() and .CR waddnstr() functions use at most \f2n\f1 bytes from \f2str\f1. These functions add the entire string when \f2n\f1 is \(mi1. These functions are similar to calling .CR mbstowcs() on the first \f2n\f1 bytes of \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" addnwstr(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .P In X/Open Curses, Issue 3, the .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions were described in the .CR addstr() entry. In X/Open Curses, Issue 4, the type of the \f2str\f1 argument defined for these functions is changed from \f3char\ *\f1 to \f3char\ *const\fP, and the .BR DESCRIPTION is changed to indicate that the functions will handle multi-byte sequences correctly. .\" toc@\f3addnstr(3X)\f1:\0\0\f4addstr()\f1, \f4mvaddnstr()\f1, \f4mvaddstr()\f1, \f4mvwaddnstr()\f1, \f4mvwaddstr()\f1, \f4waddnstr()\f1, \n\f4waddstr()\f1@@@add a string of multi-byte characters without rendition to a window and advance cursor .\" toc@\f4addstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" .\" index@\f4addnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4addstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1add a string of multi-byte characters without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1multi-byte characters, add a string of, without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" .\" links@addnstr.3x addstr.3x .\" links@addnstr.3x mvaddnstr.3x .\" links@addnstr.3x mvaddstr.3x .\" links@addnstr.3x mvwaddstr.3x .\" links@addnstr.3x mvwaddnstr.3x .\" links@addnstr.3x waddstr.3x .\" links@addnstr.3x waddnstr.3x .\" .\" fileset_database@addnstr.3x CURS-ENG-A-MAN .\" $Header: addnwstr.3x,v 76.2 95/07/28 16:19:15 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnwstr, addwstr, mvaddnwstr, mvaddwstr, mvwaddnwstr, mvwaddwstr, waddnwstr, waddwstr \(em add a wide-character string to a window and advance the cursor .SH SYNOPSIS .C "#include " .P .C "int addnwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int addwstr(wchar_t *const \f2wstr\fP);" .P .C "int mvaddnwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvaddwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwaddnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwaddwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int waddnwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int waddwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions write the characters of the wide character string \f2wstr\f1 on the current or specified window at that window's current or specified cursor position. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The effect is similar to building a \f3cchar_t\f1 from the \f3wchar_t\f1 and the background rendition and calling .CR wadd_wch() once for each \f3wchar_t\f1 character in the string. The cursor movement specified by the .I mv functions occurs only once at the start of the operation. .P The .CR addnwstr() , .CR mvaddnwstr() , .CR mvwaddnwstr() and .CR waddnwstr() functions write at most \f2n\f1 wide characters. If \f2n\f1 is \(mi1, then the entire string will be added. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" add_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addnwstr(3X)\f1:\0\0\f4addnwstr()\f1, \f4addwstr()\f1, \f4mvaddnwstr()\f1, \f4mvaddwstr()\f1, \f4mvwaddnwstr()\f1, \f4mvwaddwstr()\f1, \n\f4waddnwstr()\f1, \f4waddwstr()\f1@@@add a wide-character string to a window and advance the cursor .\" toc@\f4addwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" .\" index@\f4addnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4addwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f1add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" .\" links@addnwstr.3x addwstr.3x .\" links@addnwstr.3x mvaddnwstr.3x .\" links@addnwstr.3x mvaddwstr.3x .\" links@addnwstr.3x mvwaddnwstr.3x .\" links@addnwstr.3x mvwaddwstr.3x .\" links@addnwstr.3x waddnwstr.3x .\" links@addnwstr.3x waddwstr.3x .\" .\" fileset_database@addnwstr.3x CURS-ENG-A-MAN .\" $Header: addsev.3c,v 72.2 94/07/07 13:22:29 ssa Exp $ .TA a .TH addsev 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addsev() \- define additional severities for formatting routines .SH SYNOPSIS .C "#include " .PP .C "int addsev(int sev, const char *sev_string);" .SH DESCRIPTION The .CR addsev() routine allows the user to define additional severities to be used by formatting routines (see .IR pfmt (3C) and .IR vpfmt (3C)) in the standard message format. .I sev is the severity level. It must be between 5 and 255 inclusively. .I sev_string is a character string to be associated for this severity level. If the severity component of the .I flags parameter of the formatting routines matches .IR sev , .I sev_string is printed as the severity string. .PP The .CR addsev() routine may be called multiple times to set up a list of associations. If .I sev is already set, .I sev_string overwrites the previous string. If .I sev_string is NULL, the association is removed from the list. .PP .CR addsev() assumes that .I sev_string has already been translated into a locale-specific string using the current locale. .SH RETURN VALUE If successful, .CR addsev() returns zero. Otherwise, it returns .CR \(mi1 . .SH EXAMPLE .nf .IP .C #define MM_USER 10 .C "addsev(MM_USER, ""MY_NOTE"");" .C pfmt(stdout, MM_USER|MM_GET,"my_appl_cat:1:The file is writable"); .fi .PP This example writes the following message to standard output: .nf .IP .C MY_NOTE: The file is writable .fi .SH SEE ALSO pfmt(3C), vpfmt(3C). .SH STANDARDS COMPLIANCE .CR addsev() ": SVID3" .\" .\" index@\f4addsev()\f1 \- define additional severities@@@\f3addsev(3C)\f1 .\" index@\f1define additional severities@@@\f3addsev(3C)\f1 .\" index@\f1additional severities, define@@@\f3addsev(3C)\f1 .\" index@\f1severities, define additional@@@\f3addsev(3C)\f1 .\" .\" toc@\f3addsev(3C)\f1:\0\0\f4addsev()\f1@@@define additional severities\f1 .\" $Header: addnstr.3x,v 76.2 95/07/31 11:20:19 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnstr, addstr, mvaddnstr, mvaddstr, mvwaddnstr, mvwaddstr waddnstr, waddstr \(em add a string of multi-byte characters without rendition to a window and advance cursor .SH SYNOPSIS .C "#include " .P .C "int addnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int addstr(char *const \f2str\fP);" .P .C "int mvaddnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvaddstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwaddnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwaddstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int waddnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int waddstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions write the characters of the string \f2str\f1 on the current or specified window starting at the current or specified position using the background rendition. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions are similar to calling .CR mbstowcs() on \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .P The .CR addnstr() , .CR mvaddnstr() , .CR mvwaddnstr() and .CR waddnstr() functions use at most \f2n\f1 bytes from \f2str\f1. These functions add the entire string when \f2n\f1 is \(mi1. These functions are similar to calling .CR mbstowcs() on the first \f2n\f1 bytes of \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" addnwstr(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .P In X/Open Curses, Issue 3, the .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions were described in the .CR addstr() entry. In X/Open Curses, Issue 4, the type of the \f2str\f1 argument defined for these functions is changed from \f3char\ *\f1 to \f3char\ *const\fP, and the .BR DESCRIPTION is changed to indicate that the functions will handle multi-byte sequences correctly. .\" toc@\f3addnstr(3X)\f1:\0\0\f4addstr()\f1, \f4mvaddnstr()\f1, \f4mvaddstr()\f1, \f4mvwaddnstr()\f1, \f4mvwaddstr()\f1, \f4waddnstr()\f1, \n\f4waddstr()\f1@@@add a string of multi-byte characters without rendition to a window and advance cursor .\" toc@\f4addstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" .\" index@\f4addnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4addstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1add a string of multi-byte characters without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1multi-byte characters, add a string of, without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" .\" links@addnstr.3x addstr.3x .\" links@addnstr.3x mvaddnstr.3x .\" links@addnstr.3x mvaddstr.3x .\" links@addnstr.3x mvwaddstr.3x .\" links@addnstr.3x mvwaddnstr.3x .\" links@addnstr.3x waddstr.3x .\" links@addnstr.3x waddnstr.3x .\" .\" fileset_database@addnstr.3x CURS-ENG-A-MAN .\" $Header: addnwstr.3x,v 76.2 95/07/28 16:19:15 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnwstr, addwstr, mvaddnwstr, mvaddwstr, mvwaddnwstr, mvwaddwstr, waddnwstr, waddwstr \(em add a wide-character string to a window and advance the cursor .SH SYNOPSIS .C "#include " .P .C "int addnwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int addwstr(wchar_t *const \f2wstr\fP);" .P .C "int mvaddnwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvaddwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwaddnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwaddwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int waddnwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int waddwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions write the characters of the wide character string \f2wstr\f1 on the current or specified window at that window's current or specified cursor position. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The effect is similar to building a \f3cchar_t\f1 from the \f3wchar_t\f1 and the background rendition and calling .CR wadd_wch() once for each \f3wchar_t\f1 character in the string. The cursor movement specified by the .I mv functions occurs only once at the start of the operation. .P The .CR addnwstr() , .CR mvaddnwstr() , .CR mvwaddnwstr() and .CR waddnwstr() functions write at most \f2n\f1 wide characters. If \f2n\f1 is \(mi1, then the entire string will be added. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" add_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addnwstr(3X)\f1:\0\0\f4addnwstr()\f1, \f4addwstr()\f1, \f4mvaddnwstr()\f1, \f4mvaddwstr()\f1, \f4mvwaddnwstr()\f1, \f4mvwaddwstr()\f1, \n\f4waddnwstr()\f1, \f4waddwstr()\f1@@@add a wide-character string to a window and advance the cursor .\" toc@\f4addwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" .\" index@\f4addnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4addwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f1add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" .\" links@addnwstr.3x addwstr.3x .\" links@addnwstr.3x mvaddnwstr.3x .\" links@addnwstr.3x mvaddwstr.3x .\" links@addnwstr.3x mvwaddnwstr.3x .\" links@addnwstr.3x mvwaddwstr.3x .\" links@addnwstr.3x waddnwstr.3x .\" links@addnwstr.3x waddwstr.3x .\" .\" fileset_database@addnwstr.3x CURS-ENG-A-MAN .\" $Header: regexp.3x,v 72.5 94/11/15 09:56:02 ssa Exp $ .TA r .TH regexp 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compile(\|), step(\|), advance(\|) \- regular expression compile and match routines .SH SYNOPSIS .C #define INIT .I "declarations" .br .C #define GETC() .I "getc statements" .br .C #define PEEKC() .I "peekc statements" .br .C #define UNGETC(c) .I "ungetc statements" .br .C #define RETURN(pointer) .I "return statements" .br .C #define ERROR(val) .I "error statements" .PP .C "#include " .PP .C "char *compile(" .nf .PD 0 .IP .C "const char *instring," .C "char *expbuf," .C "const char *endbuf," .C "int eof" .PP .C ");" .PD .fi .PP .C "int step(const char *string, const char *expbuf);" .PP .C "int advance(const char *string, const char *expbuf);" .PP .C "extern char *loc1, *loc2, *locs;" .PP .C "extern int circf, sed, nbra;" .SS Remarks Features documented in this manual entry are obsolescent and may be removed in a future .SM HP-UX release. Use of .IR regcomp (3C) functions instead is recommended. .SH DESCRIPTION These functions are general-purpose regular expression matching routines to be used in programs that perform Basic Regular Expression (see .IR regexp (5)) matching. These functions are defined in .RC < regexp.h >. .PP The functions .C step() and .C advance() do pattern matching given a character string and a compiled regular expression as input. .C compile() takes a Basic Regular Expression as input and produces a compiled expression that can be used with .C step() and .CR advance() . .PP The interface to this file is unpleasantly complex. Programs that include this file must have the following five macros declared before the .C #include statement. These macros are used by the .C compile() routine. .TP 15 .C GETC() Return the value of the next byte in the regular expression pattern. Successive calls to .C GETC() should return successive bytes of the regular expression. .TP .C PEEKC() Return the next byte in the regular expression. Successive calls to .C PEEKC() should return the same byte (which should also be the next byte returned by .CR GETC() . .TP .CI UNGETC( c ) Cause the argument .I c to be returned by the next call to .C GETC() (and .CR PEEKC() ). No more than one byte of pushback is ever needed, and this byte is guaranteed to be the last byte read by .CR GETC() . The value of the macro .CI UNGETC( c ) is always ignored. .TP .CI RETURN( pointer ) This macro is used on normal exit of the .C compile() routine. The value of the argument .I pointer is a pointer to the character after the last character of the compiled regular expression. This is useful to programs that must manage memory allocation. .TP .CI ERROR( val ) This is the abnormal return from the .C compile() routine. The argument .I val is an error number (see table below for meanings). This call should never return. .RS .RS .PD 0 .TP 8 .B Error .B Meaning .TP 11 Range endpoint too large. .TP 16 Bad number. .TP 25 ``\f3\e\f2digit\f1'' out of range. .TP 36 Illegal or missing delimiter. .TP 41 No remembered search string. .TP 42 .C \e( \e) imbalance. .TP 43 Too many .CR \e( . .TP 44 More than 2 numbers given in .CR \e{\0\e} . .TP 45 .C } expected after .CR \e . .TP 46 First number exceeds second in .CR \e{\0\e} . .TP 49 .C [ ] imbalance. .TP 50 Regular expression overflow. .RE .RE .PD .PP The syntax of the .C compile() routine is as follows: .IP .CI compile( instring , .CI expbuf , .CI endbuf , .CI eof ) .PP The first parameter .I instring is never used explicitly by the .C compile() routine, but is useful for programs that pass down different pointers to input characters. It is sometimes used in the .C INIT declaration (see below). Programs that call functions to input characters or have characters in an external array can pass down a value of .C ((char *) 0) for this parameter. .PP The next parameter .I expbuf is a character pointer. It points to the location where the compiled regular expression will be placed. .PP The parameter .I endbuf is one more than the highest address where the compiled regular expression can be placed. If the compiled expression cannot fit in .RI ( endbuf \|\(mi\| expbuf ) bytes, a call to .C ERROR(50) is made. .PP The parameter .I eof is the character which marks the end of the regular expression. For example, in .IR ed (1), this character is usually a .CR / . .PP Each program that includes this file must have a .C #define statement for .CR INIT . This definition is placed right after the declaration for the function .C compile() and the opening curly brace .CR { . It is used for dependent declarations and initializations. Most often it is used to set a register variable to point to the beginning of the regular expression so that this register variable can be used in the declarations for .CR GETC() , .CR PEEKC() , and .CR UNGETC() . Otherwise it can be used to declare external variables that might be used by .CR GETC() , .CR PEEKC() , and .CR UNGETC() . See the example below of the declarations taken from .IR grep (1). .PP .C step() also performs actual regular expression matching in this file. The call to .I step is as follows: .IP .CI step( string , .CI expbuf ) .PP The first parameter to .C step() is a pointer to a string of characters to be checked for a match. This string should be null-terminated. .PP The second parameter .I expbuf is the compiled regular expression that was obtained by a call to .CR compile() . .PP .C step() returns non-zero if the given string matches the regular expression, and zero if the expressions do not match. If there is a match, two external character pointers are set as a side effect to the call to .CR step() . The variable set in .C step() is .CR loc1 . This is a pointer to the first character that matched the regular expression. The variable .CR loc2 , which is set by the function .CR advance() , points to the character after the last character that matches the regular expression. Thus, if the regular expression matches the entire line, .C loc1 points to the first character of .I string and .C loc2 points to the null at the end of .IR string . .PP .C step() uses the external variable .CR circf() , which is set by .C compile() if the regular expression begins with .CR ^ . If this is set, .C step() tries to match the regular expression to the beginning of the string only. If more than one regular expression is to be compiled before the first is executed, the value of .I circf should be saved for each compiled expression and .I circf should be set to that saved value before each call to .CR step() . .PP .C advance() is called from .C step() with the same arguments as .CR step() . The purpose of .C step() is to step through the .I string argument and call .C advance() until .C advance() returns non-zero, which indicates a match, or until the end of .I string is reached. To constrain .I string to beginning-of-line in all cases, .C step() need not be called; simply call .CR advance() . .PP When .C advance() encounters a .C * or .C \e{\|\e} sequence in the regular expression, it advances its pointer to the string to be matched as far as possible and recursively calls itself, trying to match the rest of the string to the rest of the regular expression. As long as there is no match, .I advance backs up along the string until it finds a match or reaches the point in the string that initially matched the .C * or .CR \e{\|\e} . It is sometimes desirable to stop this backing up before the initial point in the string is reached. If the external character pointer .C locs is equal to the point in the string at sometime during the backing up process, .C advance() breaks out of the loop that backs up and returns zero. This is used by .IR ed (1) and .IR sed (1) for substitutions done globally (not just the first occurrence, but the whole line) so, for example, expressions such as .C s/y*//g do not loop forever. .PP The additional external variables .C sed and .C nbra are used for special purposes. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions. .PP The .C LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, and the characters matched by character class expressions in regular expressions. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following is an example of how the regular expression macros and calls look from .IR grep (1): .nf .IP .C "#define INIT register char *sp = instring;" .C "#define GETC() (*sp++)" .C "#define PEEKC() (*sp)" .C "#define UNGETC(c) (--sp)" .C "#define RETURN(c) return;" .C "#define ERROR(c) regerr()" .IP .C "#include " \h'.5i'.\|.\|. .C "(void) compile(*argv, expbuf, &expbuf[ESIZE], '\e0');" \h'.5i'.\|.\|. .C "if (step(linebuf, expbuf))" .C " succeed();" .fi .SH AUTHOR .CR regexp() was developed by OSF and HP. .SH SEE ALSO grep(1), regcomp(3C), setlocale(3C), regexp(5). .SH STANDARDS CONFORMANCE .CR advance() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR compile() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc1 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc2 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR locs ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR step() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4compile()\f1 \- regular expression compile routine@@@\f3regexp(3X)\f1 .\" index@\f4step()\f1 \- regular expression string comparison routine@@@\f3regexp(3X)\f1 .\" index@\f4advance()\f1 \- regular expression substring comparison routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1expression, regular, compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1compile and match routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1comparison routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1match routines for regular expressions@@@\f3regexp(3X)\f1 .\" .\" toc@\f3regexp(3X)\f1:\0\0\f4compile()\f1, \f4step()\f1, \f4advance()\f1@@@regular expression compile and match routines .\" toc@\f4compile()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4step()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4advance()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" .\" links@regexp.3x compile.3x .\" links@regexp.3x step.3x .\" links@regexp.3x advance.3x .\" links@regexp.3x INIT.3x .\" links@regexp.3x GETC.3x .\" links@regexp.3x PEEKC.3x .\" links@regexp.3x UNGETC.3x .\" links@regexp.3x RETURN.3x .\" links@regexp.3x ERROR.3x .\" .\" fileset_database@regexp.3x PROGRAMING-MAN .\" $Header: malloc.3c,v 72.6 94/11/15 09:55:17 ssa Exp $ .TA m .TH malloc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME malloc(), free(), realloc(), calloc(), valloc(), mallopt(), mallinfo(), memorymap(), alloca() \- main memory allocator .SH SYNOPSIS .C "#include " .PP .C "void *malloc(size_t size);" .PP .C "void *calloc(size_t nelem, size_t elsize);" .PP .C "void *realloc(void *ptr, size_t size);" .PP .C "void *valloc(size_t size);" .PP .C "void free(void *ptr);" .PP .C "void memorymap(int show_stats);" .PP .C " " .PP .C "#include " .PP .C "void *alloca(size_t size);" .SH SYSTEM V SYNOPSIS .C "#include " .PP .C "char *malloc(unsigned size);" .PP .C "void free(char *ptr);" .PP .C "char *realloc(char *ptr, unsigned size);" .PP .C "char *calloc(unsigned nelem, unsigned elsize);" .PP .C "int mallopt(int cmd, int value);" .PP .C "struct mallinfo mallinfo(void);" .SS Remarks The functionality in the old .IR malloc (3X) package has been incorporated into .IR malloc (3C). The library .RC ( /usr/lib/libmalloc.a ) corresponding to the .CR -lmalloc linker option is now an empty library. Makefiles that reference this library will continue to work. Applications that used the .IR malloc (3X) package should still work properly with the new .IR malloc (3C) package. If the old versions must be used, they are provided in files .CR /usr/old/libmalloc3x.a and .CR /usr/old/libmalloc3c.o for Release 8.07 only. .SH DESCRIPTION The functions described in this manual entry provide a simple, general purpose memory allocation package: .RS .TP 17 .C malloc() Allocates space for a block of at least .I size bytes, but does not initialize the space. .TP .C calloc() Allocates space for an array of .I nelem elements, each of size .I elsize bytes, and initializes the space to zeros. Actual amount of space allocated will be at least .I nelem * elsize bytes. .TP .C realloc() Changes the size of the block pointed to by .I ptr to .I size bytes and returns a pointer to the (possibly moved) block. Existing contents are unchanged up to the lesser of the new and old sizes. If .I ptr is a NULL pointer, .CR realloc() behaves like .CR malloc() for the specified size. If .I size is zero and .I ptr is not a NULL pointer, the object it points to is freed and NULL is returned. .TP .C valloc() Allocates space for a block of at least .I size bytes starting on a boundary aligned to a multiple of the value returned by .IR sysconf(__SC_PAGESIZE) . This space is uninitialized. .TP .C free() Deallocates the space pointed to by .I ptr (a pointer to a block previously allocated by .CR malloc() , .CR realloc() , or .CR calloc() ) and makes the space available for further allocation. If .I ptr is a NULL pointer, no action occurs. .TP .C mallopt() Provides for control over the allocation algorithm and other options in the .IR malloc (3C) package. The available values for .I cmd are: .RS .RS .TP 15 .C M_MXFAST Set .IR maxfast to .IR value . The algorithm allocates all blocks below the size of .IR maxfast in large groups, then doles them out very quickly. The default value for .IR maxfast is zero. .TP .C M_NLBLKS Set .IR numlblks to .IR value . The above mentioned ``large groups'' each contain .I numlblks blocks. .I numlblks must be greater than 1. The default value for .I numlblks is .CR 100 . .TP .C M_GRAIN Set .I grain to .IR value . The sizes of all blocks smaller than .I maxfast are considered to be rounded up to the nearest multiple of .IR grain . .I grain must be greater than zero. The default value of .I grain is the smallest number of bytes that can accommodate alignment of any data type. .I value is rounded up to a multiple of the default when .I grain is set. .TP .C M_KEEP Preserve data in a freed block until the next .CR malloc() , .CR realloc() , or .CR calloc() . This option is provided only for compatibility with the old version of .CR malloc() and is not recommended. .TP .C M_BLOCK Block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option is provided for those who need to write signal handlers that allocate memory. When set, the .IR malloc (3C) routines can be called from within signal handlers (they become re-entrant). Default action is .I not to block all blockable signals. .TP .C M_UBLOCK Do not block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option cancels signal blocking initiated by the .CR M_BLOCK option. .RE .RE .IP These values are defined in the .CR header file. .IP .CR mallopt() can be called repeatedly, but must not be called after the first small block is allocated (unless .I cmd is set to .CR M_BLOCK or .CR M_UBLOCK ). .TP .C mallinfo() Provides instrumentation describing space usage, but cannot be called until the first small block is allocated. It returns the structure: .nf .IP .C "struct mallinfo {" .C " int arena; /* total space in arena */" .C " int ordblks; /* number of ordinary blocks */" .C " int smblks; /* number of small blocks */" .C " int hblkhd; /* space in holding block headers */" .C " int hblks; /* number of holding blocks */" .C " int usmblks /* space in small blocks in use */" .C " int fsmblks /* space in free small blocks */" .C " int uordblks; /* space in ordinary blocks in use */" .C " int fordblks; /* space in free ordinary blocks */" .C " int keepcost; /* space penalty if keep option is used */" .C } .fi .IP This structure is defined in the .CR header file. .RE .PP Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. .RS .TP 17 .C memorymap() Can be used to display the contents of the memory allocator. A list of addresses and block descriptions is written (using .CR printf() ) to standard output. If the value of the .I show_stats parameter is 1, statistics concerning number of blocks and sizes used will also be written. If the value is zero, only the memory map will be written. .IP The addresses and sizes displayed by .CR memorymap() may not correspond to those requested by an application. The size of a block (as viewed by the allocator) includes header information and padding to properly align the block. The address is also offset by a certain amount to accommodate the header information. .TP .C alloca() Allocates space from the stack of the caller for a block of at least .I size bytes, but does not initialize the space. The space is automatically freed when the calling routine exits. .IP Memory returned by .CR alloca() is not related to memory allocated by other memory allocation functions. Behavior of addresses returned by .CR alloca() as parameters to other memory functions is undefined. .IP The implementation of this routine is system dependent and its use is discouraged. .RE .SH RETURN VALUE Upon successful completion, .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. Otherwise, they return a NULL pointer. If .CR realloc() returns a NULL pointer, the memory pointed to by the original pointer is left intact. .PP .CR mallopt() returns zero for success and nonzero for failure. .SH DIAGNOSTICS .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a NULL pointer if there is no available memory, or if the memory managed by .CR malloc() has been detectably corrupted. This memory may become corrupted if data is stored outside the bounds of a block, or if an invalid pointer (a pointer not generated by .CR malloc() , .CR realloc() , or .CR calloc() ) is passed as an argument to .CR free() or .CR realloc() . .PP If .CR mallopt() is called after any allocation of a small block and .I cmd is not set to .CR M_BLOCK or .CR M_UBLOCK , or if .I cmd or .I value is invalid, nonzero is returned. Otherwise, it returns zero. .SH ERRORS .RS .TP 17 [ENOMEM] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to ENOMEM and return a NULL pointer when an out-of-memory condition arises. .TP [EINVAL] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to EINVAL and return a NULL pointer when the memory being managed by .CR malloc() has been detectably corrupted. .SH WARNINGS .CR malloc() functions use .CR brk() and .CR sbrk() (see .IR brk (2)) to increase the address space of a process. Therefore, an application program that uses .CR brk() or .CR sbrk() must not use them to decrease the address space, because this confuses the .CR malloc() functions. .PP .CR free() and .CR realloc() do not check their pointer argument for validity. .PP If .CR free() or .CR realloc() is passed a pointer that was not the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() , or if space assigned by an allocation function is overrun, loss of data, a memory fault, bus error, or an infinite loop may occur at that time or during any subsequent call to .CR malloc() , .CR realloc() , .CR calloc() , .CR valloc() , or .CR free() . .PP The following actions are not supported and cause undesirable effects: .RS .TP 3 \(bu Attempting to .CR free() or .CR realloc() a pointer not generated as the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() . .RE .PP The following actions are strongly discouraged and may be unsupported in a future implementation of .CR malloc() : .RS .TP 3 \(bu attempting to .CR free() the same block twice, .TP \(bu depending on unmodified contents of a block after it has been freed. .RE .PP Undocumented features of earlier memory allocators have not been duplicated. .SH COMPATIBILITY The only external difference between the old .IR malloc (3X) allocator and the .IR malloc (3C) allocator is that the old allocator would return a NULL pointer for a request of zero bytes. The .IR malloc (3C) allocator returns a valid memory address. This is not a concern for most applications. .ift .br .ift .ne 4 .PP Although the current implementation of .IR malloc (3C) allows for freeing a block twice and does not corrupt the contents of a block after it is freed (until the next call to .CR realloc() , .CR calloc() , .CR malloc() , or .CR valloc() ), support for these features may be discontinued in a future implementation of .IR malloc (3C) and should not be used. .SH SEE ALSO brk(2), errno(2). .SH STANDARDS CONFORMANCE .CR malloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR calloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR free() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mallinfo() ": SVID2, XPG2" .PP .CR mallopt() ": SVID2, SVID3, XPG2" .PP .CR realloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4malloc()\f1 \- allocate block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4free()\f1 \- release allocated block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4realloc()\f1 \- change size of allocated memory block@@@\f3malloc(3C)\f1 .\" index@\f4calloc()\f1 \- allocate memory for array@@@\f3malloc(3C)\f1 .\" index@\f4mallopt()\f1 \- control memory space allocation@@@\f3malloc(3C)\f1 .\" index@\f4mallinfo()\f1 \- display memory space usage@@@\f3malloc(3C)\f1 .\" index@\f4memorymap()\f1 \- display contents of memory allocator@@@\f3malloc(3C)\f1 .\" index@\f4alloca()\f1 \- allocate space from the stack@@@\f3malloc(3C)\f1 .\" index@\f4valloc()\f1 \- allocate space on boundary aligned to sysconf value@@@\f3malloc(3C)\f1 .\" index@\f1main memory allocator@@@\f3malloc(3C)\f1 .\" index@\f1memory allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1main memory space usage, display@@@\f3malloc(3C)\f1 .\" index@\f1main memory space allocation, control@@@\f3malloc(3C)\f1 .\" .\" toc@\f3malloc(3C)\f1:\0\0\f4alloca()\f1, \f4calloc()\f1, \f4free()\f1, \f4mallinfo()\f1,\n\f4malloc()\f1, \f4mallopt()\f1, \f4memorymap()\f1, \f4realloc()\f1, \f4valloc()\f1@@@main memory allocator\f1 .\" .\" toc@\f4free()\f1:\0\0release allocated block of main memory@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4realloc()\f1:\0\0change size of allocated memory block@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4calloc()\f1:\0\0allocate memory for array@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4valloc()\f1:\0\0allocate space on boundary aligned to sysconf value@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallopt()\f1:\0\0control memory space allocation@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallinfo()\f1:\0\0display memory space usage@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4memorymap()\f1:\0\0display contents of memory allocator@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4alloca()\f1:\0\0allocate space from the stack@@@\f1see \f3malloc(3C)\f1 .\" .\" links@malloc.3c free.3c .\" links@malloc.3c realloc.3c .\" links@malloc.3c calloc.3c .\" links@malloc.3c valloc.3c .\" links@malloc.3c mallopt.3c .\" links@malloc.3c mallinfo.3c .\" links@malloc.3c memorymap.3c .\" links@malloc.3c alloca.3c .\" $Header: almanac.3x,v 72.3 93/01/14 14:44:50 ssa Exp $ .TA a .TH almanac 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME almanac(\|) \- return numeric date information in MPE format .SH SYNOPSIS .nf .C "void almanac(" .PD 0 .IP .C "unsigned short int date," .C "unsigned short int err[2]," .C "short int *pyear," .C "short int *pmonth," .C "short int *pday," .C "short int *pweekday" .PP .C ); .PD .fi .SH DESCRIPTION .C almanac() returns numeric date information for a date in the packed date format returned by the .C calendar() routine (see .IR calendar (3X)). The returned information is: .IP year of the century .br month of the year .br day of the month .br day of the week .PP The arguments to .C almanac() are used as follows: .TP 15 .I date An unsigned short containing the date about which information is to be returned. The year of the century is packed into bits 0 through 6, and the day of the year is packed into bits 7 through 15. The packed date format is: .sp .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|0#6#\|7#15 \&#_#_#_#_ #Year of Century##Day of Year# \&#_#_#_#_ .TE .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .TP 10 Error # Meaning .TP .C \0\01 No parameters are present in which to return values: pday, pmonth, pyear, and pweek all point to zero. .PD 0 .TP .C \0\02 Day of the year is out of range. .TP .C \0\03 Year of the century is out of range. .RE .PD .TP 15 .I pyear A pointer to a short in which the year of the century is returned. .TP .I pmonth A pointer to a short in which the month of the year is returned (for example, January is represented by .C 1 and December is represented by .CR 12 ). .TP .I pday A pointer to a short in which the day of the month is returned. .TP .I pweekday A pointer to a short in which the weekday is returned. Note that .C 1 is returned for Sunday and .C 7 for Saturday. .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Refer to .IR hpnls (5) for information about Native Language Support routines used in C programs in the .SM HP-UX NLS environment. .SH AUTHOR .C almanac() was developed by HP. .SH SEE ALSO calendar(3X), nlfmtdate(3X), ctime(3C), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4almanac()\fP \- return numeric date information in \s-1MPE\s+1 format@@@\f3almanac(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: return numeric date information in \s-1MPE\s+1 format@@@\f3almanac(3X)\f1 .\" .\" toc@\f3almanac(3X)\f1:\0\0\f4almanac()\fP@@@return numeric date information in \s-1MPE\s+1 format .\" .\" fileset_database@almanac.3x PROGRAMING-MAN .\" $Header: scandir.3c,v 72.3 93/01/14 14:51:05 ssa Exp $ .TA s .TH scandir 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scandir(\|), alphasort(\|) \- scan a directory .SH SYNOPSIS .C "#include " .P .C "int scandir(" .nf .PD 0 .IP .C "const char *dirname," .C "struct dirent **namelist," .C "int (*select)(const struct dirent * const *)," .C "int (*compar)(" .RS .IP .C "const struct dirent * const *," .C "const struct dirent * const *" .RE .IP .C ")" .P .C ");" .PD .P .C "int alphasort(" .PD 0 .IP .C "const struct dirent * const *d1," .C "const struct dirent * const *d2" .P .C ");" .PD .fi .SH DESCRIPTION .C scandir() reads the directory .I dirname and builds an array of pointers to directory entries using .C malloc() (see .IR malloc (3C)). It returns the number of entries in the array and a pointer to the array through .IR namelist . .PP The .I select parameter is a pointer to a user-supplied subroutine which is called by .C scandir() to select which entries are to be included in the array. The select routine is passed a pointer to a directory entry and should return a non-zero value if the directory entry is to be included in the array. If .I select is null, then all the directory entries will be included. .PP The .I compar parameter is a pointer to a user-supplied subroutine which is passed to .IR qsort (3C) to sort the completed array. If this pointer is null, the array is not sorted. .C alphasort() is a routine which can be used for the .I compar parameter to sort the array alphabetically. .PP The memory allocated for the array can be deallocated with .C free() (see .IR malloc (3C)) by freeing each pointer in the array and the array itself. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by .CR alphasort() . See .IR hpnls (5) for a description of supported collation features. .PP The .C LC_CTYPE category determines the interpretation of bytes in the file name portion of directory entries as single- and/or multi-byte characters by the .C alphasort() function. .PP Results are undefined if the locales specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .SS International Code Set Support Single- and multi-byte character code sets are supported for .CR alphasort() . .SH RETURN VALUE .C scandir() returns \-1 if the directory cannot be opened for reading or if .CR malloc() cannot allocate enough memory to hold all the data structures. .SH EXAMPLE The example program below scans the .C /tmp directory. It does not exclude any entries since .I select is .SM NULL. The contents of .C namelist are sorted by .CR alphasort() . It prints out how many entries are in .C /tmp and the sorted entries of the .C /tmp directory. The memory used by .C scandir() is returned using .CR free() . .RS .PP .nf .ift .ft 4 .ifn .ft 3 .ps +1 #include #include #include extern int scandir(); extern int alphasort(); main() { int num_entries, i; struct dirent **namelist, **list; if ((num_entries = scandir("/tmp", &namelist, NULL, alphasort)) < 0) { fprintf(stderr, "Unexpected error\en"); exit(1); } printf("Number of entries is %d\en", num_entries); if (num_entries) { printf("Entries are:"); for (i=0, list=namelist; id_name); free(\(**list); \(**list++; } free(namelist); printf("\en"); } printf("\en"); exit(0); } .ps .ft .fi .RE .SH SEE ALSO directory(3C), malloc(3C), qsort(3C), string(3C), dirent(5), hpnls(5). .\" .\" index@\f4scandir()\fP \- scan a directory@@@\f3scandir(3C)\f1 .\" index@directory: scan a directory@@@\f3scandir(3C)\f1 .\" index@scan a directory@@@\f3scandir(3C)\f1 .\" index@directory, scan a@@@\f3scandir(3C)\f1 .\" index@\f4alphasort()\fP \- sort a directory pointer array@@@\f3scandir(3C)\f1 .\" index@sort a directory pointer array@@@\f3scandir(3C)\f1 .\" index@directory pointer array, sort a@@@\f3scandir(3C)\f1 .\" index@pointer array, sort a directory@@@\f3scandir(3C)\f1 .\" index@array, sort a directory pointer@@@\f3scandir(3C)\f1 .\" .\" toc@\f3scandir(3C)\f1:\0\0\f4scandir()\fP, \f4alphasort()\fP@@@scan a directory .\" toc@\f4alphasort()\fP \- sort a directory pointer array@@@see \f3scandir(3C)\f1 .\" .\" links@scandir.3c alphasort.3c .\" .\" fileset_database@scandir.3c PROGRAMING-MAN .\" $Header: ctime.3c,v 76.1 95/07/05 17:27:14 ssa Exp $ .TA c .TH ctime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctime(\|), ctime_r(\|), localtime(\|), localtime_r(\|), gmtime(\|), gmtime_r(\|), mktime(\|), difftime(\|), asctime(\|), asctime_r(\|), timezone(\|), daylight(\|), tzname(\|), tzset(\|) \- convert date and time to string .SH SYNOPSIS .nf .C "#include " .PP .C "char *asctime(const struct tm *timeptr);" .PP .C "int asctime_r(const struct tm *timeptr, char *buffer, int buflen);" .PP .C "char *ctime(const time_t *timer);" .PP .C "int ctime_r(const time_t *timer, char *buffer, int buflen);" .PP .C "double difftime(time_t time1, time_t time0);" .PP .C "struct tm *gmtime(const time_t *timer);" .PP .C "int gmtime_r(const time_t *timer, struct tm *result);" .PP .C "struct tm *localtime(const time_t *timer);" .PP .C "int localtime_r(const time_t *timer, struct tm *result);" .PP .C "time_t mktime(struct tm *timeptr);" .PP .C "extern long timezone;" .PP .C "extern int daylight;" .PP .C "extern char *tzname[2];" .PP .C "void tzset(void);" .fi .SH DESCRIPTION .TP 18 .C asctime() Convert the broken-down time contained in the structure pointed to by .I timeptr and return a pointer to a 26-character string in the form: .RS .IP .C "Sun Sep 16 01:03:52 1973\en\e0" .RE .IP All the fields have constant width. .TP .C asctime_r() is identical to .CR asctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C ctime() Convert the calendar time pointed to by .IR timer , representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: .RS .IP .C asctime(localtime(timer)) .RE .TP .C ctime_r() is identical to .CR ctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C gmtime() Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. .C gmtime() returns a pointer to the .C tm structure described below. .TP .C gmtime_r() is identical to .CR gmtime() , except that .C gmtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C localtime() Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA\c), according to the contents of the TZ environment variable (see Environment Variables below). .C localtime() returns a pointer to the .C tm structure described below. .TP .C localtime_r() is identical to .CR localtime() , except that .C localtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C difftime() Return the difference in seconds between two calendar times: .IR "time1 \(mi time0" . .TP .C mktime() Convert the broken-down time (expressed as local time) in the structure pointed to by .I timeptr into a calendar time value with the same encoding as that of the values returned by .IR time (2). The original values of the .C tm_wday and .C tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below. .IP A positive or zero value for .C tm_isdst causes .C mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for .C tm_isdst causes .C mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time. .IP Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of .C tm_mday is not set until .C tm_mon and .C tm_year are determined. .C mktime() returns the specified calendar time encoded as a value of type .CR time_t . .IP If the calendar time cannot be represented, the function returns the value .RC ( time_t )\|\(em\|1 and sets .C errno to .CR ERANGE . Note the value .RC ( time_t )\|\(em\|1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and .C errno to reliably detect an error condition. .TP .C tzset() Sets the values of the external variables .IR timezone , .IR daylight , and .I tzname according to the contents of the .C TZ environment variable (independent of any time value). The functions .CR localtime() , .CR mktime() , .CR ctime() , .CR asctime() , and .C strftime() (see .IR strftime (3C)) call .C tzset() and use the values returned in the external variables described below for their operations. .C tzset() can also be called directly by the user. .PP The .RC < time.h > header file contains declarations of all relevant functions and externals. It also contains the .C tm structure, which includes the following members: .RS .PP .nf .ift .ft 4 .ps +1 int tm_sec; /* seconds after the minute - [0,61] */ int tm_min; /* minutes after the hour - [0,59] */ int tm_hour; /* hours - [0,23] */ int tm_mday; /* day of month - [1,31] */ int tm_mon; /* month of year - [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday - [0,6] */ int tm_yday; /* days since January 1 - [0,365] */ int tm_isdst; /* daylight savings time flag */ .ift .ft .ps .fi .PP The value of .C tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available. .RE .PP The external variable .C timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), .C timezone is 5\(**60\(**60). The external variable .C daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable .C tzname[2] contains the local standard and local summer time zone abbreviations as specified by the .C TZ environment variable. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .SS Environment Variables The .C tzset() function uses the contents of .C TZ to set the values of the external variables .CR timezone , .C daylight , and .CR tzname . .C TZ also determines the time zone name substituted for the .C %Z and .C %z directives and the time zone adjustments performed by .CR localtime() , .CR mktime() , and .CR ctime() . Two methods for specifying a time zone within .C TZ are described in .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH "RETURN VALUE" .PP For .C asctime_r() and .C ctime_r(), if the buffer is of insufficient length, -1 is returned. For .C asctime_r(), ctime_r(), gmtime_r(), and .C localtime_r(), if the operation is successful, 0 is returned. .SH WARNINGS The return values for .CR asctime() , .CR ctime() , .CR gmtime() , and .CR localtime() point to static data whose contents is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() are MT-Safe and should be used instead. .PP Users of .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .PP The range of .C tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by .IR time (2) and passed as the .I timer argument does not include accumulated leap seconds. The .C tm structure generated by .C localtime() and .C gmtime() will never reflect any leap seconds. Upon successful completion, .C mktime() forces the value of the .C tm_sec component to the range [0,59]. .PP .CR ctime() , .CR ctime_r() , .CR asctime() , and .CR asctime_r() are considered obsolescent and may be removed in a future release. Use of .IR strftime (3C) is recommended instead. .SH AUTHOR .C ctime() was developed by AT&T and HP. .SH SEE ALSO time(2), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR ctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR asctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR daylight ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR difftime() ": AES, SVID3, XPG4, ANSI C" .PP .CR gmtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR localtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mktime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR timezone ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR tzname ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tzset() ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4asctime()\fP, \f4asctime_r()\f1 \- convert \f3tm\f1 structure date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4ctime()\fP, \f4ctime_r()\f1 \- convert \f4clock()\fP date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4daylight()\fP \- Daylight Savings Time flag@@@\f3ctime(3C)\f1 .\" index@\f4gmtime()\fP, \f4gmtime_r()\fP \- convert date and time to Greenwich Mean Time@@@\f3ctime(3C)\f1 .\" index@\f4localtime()\fP, \f4localtime_r()\fP \- convert date and time to local timezone@@@\f3ctime(3C)\f1 .\" index@\f4timezone()\fP \- difference between \s-1UCT\s+1 and local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzname()\fP \- name of local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzset()\fP \- initialize \f4timezone()\fP, \f4daylight()\fP, and \f4tzname()\fP using \s-1TZ\s+1 variable@@@\f3ctime(3C)\f1 .\" index@\f4mktime()\fP \- convert time into calendar time value@@@\f3ctime(3C)\f1 .\" index@\f4difftime()\fP \- difference between two calendar time values@@@\f3ctime(3C)\f1 .\" index@convert date and time to string@@@\f3ctime(3C)\f1 .\" index@string, convert date and time to@@@\f3ctime(3C)\f1 .\" index@date and time, convert to string@@@\f3ctime(3C)\f1 .\" index@time and date, convert to string@@@\f3ctime(3C)\f1 .\" .\" toc@\f3ctime(3C)\f1:\0\0\f4ctime()\fP, \f4ctime_r()\fP, \f4localtime()\fP, \f4localtime_r()\fP, \f4difftime()\f1, \f4 mktime()\f1, \n\f4gmtime()\fP, \f4gmtime_r()\fP,\f4asctime()\fP, \f4asctime_r()\fP, \f4timezone()\fP, \f4daylight()\fP, \f4tzname()\fP,\n\f4tzset()\f1@@@convert date and time to string .\" toc@\f4ctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4ctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4timezone()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4daylight()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzname()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzset()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4difftime()\fP:\0\0difference between calendar times@@@see \f3ctime(3C)\f1 .\" toc@\f4mktime()\fP:\0\0create calendar time value@@@see \f3ctime(3C)\f1 .\" .\" links@ctime.3c ctime_r.3c .\" links@ctime.3c localtime.3c .\" links@ctime.3c localtime_r.3c .\" links@ctime.3c gmtime.3c .\" links@ctime.3c gmtime_r.3c .\" links@ctime.3c asctime.3c .\" links@ctime.3c asctime_r.3c .\" links@ctime.3c timezone.3c .\" links@ctime.3c daylight.3c .\" links@ctime.3c tzname.3c .\" links@ctime.3c tzset.3c .\" links@ctime.3c difftime.3c .\" links@ctime.3c mktime.3c .\" .\" fileset_database@ctime.3c PROGRAMING-MAN .\" $Header: ctime.3c,v 76.1 95/07/05 17:27:14 ssa Exp $ .TA c .TH ctime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctime(\|), ctime_r(\|), localtime(\|), localtime_r(\|), gmtime(\|), gmtime_r(\|), mktime(\|), difftime(\|), asctime(\|), asctime_r(\|), timezone(\|), daylight(\|), tzname(\|), tzset(\|) \- convert date and time to string .SH SYNOPSIS .nf .C "#include " .PP .C "char *asctime(const struct tm *timeptr);" .PP .C "int asctime_r(const struct tm *timeptr, char *buffer, int buflen);" .PP .C "char *ctime(const time_t *timer);" .PP .C "int ctime_r(const time_t *timer, char *buffer, int buflen);" .PP .C "double difftime(time_t time1, time_t time0);" .PP .C "struct tm *gmtime(const time_t *timer);" .PP .C "int gmtime_r(const time_t *timer, struct tm *result);" .PP .C "struct tm *localtime(const time_t *timer);" .PP .C "int localtime_r(const time_t *timer, struct tm *result);" .PP .C "time_t mktime(struct tm *timeptr);" .PP .C "extern long timezone;" .PP .C "extern int daylight;" .PP .C "extern char *tzname[2];" .PP .C "void tzset(void);" .fi .SH DESCRIPTION .TP 18 .C asctime() Convert the broken-down time contained in the structure pointed to by .I timeptr and return a pointer to a 26-character string in the form: .RS .IP .C "Sun Sep 16 01:03:52 1973\en\e0" .RE .IP All the fields have constant width. .TP .C asctime_r() is identical to .CR asctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C ctime() Convert the calendar time pointed to by .IR timer , representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: .RS .IP .C asctime(localtime(timer)) .RE .TP .C ctime_r() is identical to .CR ctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C gmtime() Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. .C gmtime() returns a pointer to the .C tm structure described below. .TP .C gmtime_r() is identical to .CR gmtime() , except that .C gmtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C localtime() Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA\c), according to the contents of the TZ environment variable (see Environment Variables below). .C localtime() returns a pointer to the .C tm structure described below. .TP .C localtime_r() is identical to .CR localtime() , except that .C localtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C difftime() Return the difference in seconds between two calendar times: .IR "time1 \(mi time0" . .TP .C mktime() Convert the broken-down time (expressed as local time) in the structure pointed to by .I timeptr into a calendar time value with the same encoding as that of the values returned by .IR time (2). The original values of the .C tm_wday and .C tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below. .IP A positive or zero value for .C tm_isdst causes .C mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for .C tm_isdst causes .C mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time. .IP Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of .C tm_mday is not set until .C tm_mon and .C tm_year are determined. .C mktime() returns the specified calendar time encoded as a value of type .CR time_t . .IP If the calendar time cannot be represented, the function returns the value .RC ( time_t )\|\(em\|1 and sets .C errno to .CR ERANGE . Note the value .RC ( time_t )\|\(em\|1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and .C errno to reliably detect an error condition. .TP .C tzset() Sets the values of the external variables .IR timezone , .IR daylight , and .I tzname according to the contents of the .C TZ environment variable (independent of any time value). The functions .CR localtime() , .CR mktime() , .CR ctime() , .CR asctime() , and .C strftime() (see .IR strftime (3C)) call .C tzset() and use the values returned in the external variables described below for their operations. .C tzset() can also be called directly by the user. .PP The .RC < time.h > header file contains declarations of all relevant functions and externals. It also contains the .C tm structure, which includes the following members: .RS .PP .nf .ift .ft 4 .ps +1 int tm_sec; /* seconds after the minute - [0,61] */ int tm_min; /* minutes after the hour - [0,59] */ int tm_hour; /* hours - [0,23] */ int tm_mday; /* day of month - [1,31] */ int tm_mon; /* month of year - [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday - [0,6] */ int tm_yday; /* days since January 1 - [0,365] */ int tm_isdst; /* daylight savings time flag */ .ift .ft .ps .fi .PP The value of .C tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available. .RE .PP The external variable .C timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), .C timezone is 5\(**60\(**60). The external variable .C daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable .C tzname[2] contains the local standard and local summer time zone abbreviations as specified by the .C TZ environment variable. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .SS Environment Variables The .C tzset() function uses the contents of .C TZ to set the values of the external variables .CR timezone , .C daylight , and .CR tzname . .C TZ also determines the time zone name substituted for the .C %Z and .C %z directives and the time zone adjustments performed by .CR localtime() , .CR mktime() , and .CR ctime() . Two methods for specifying a time zone within .C TZ are described in .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH "RETURN VALUE" .PP For .C asctime_r() and .C ctime_r(), if the buffer is of insufficient length, -1 is returned. For .C asctime_r(), ctime_r(), gmtime_r(), and .C localtime_r(), if the operation is successful, 0 is returned. .SH WARNINGS The return values for .CR asctime() , .CR ctime() , .CR gmtime() , and .CR localtime() point to static data whose contents is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() are MT-Safe and should be used instead. .PP Users of .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .PP The range of .C tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by .IR time (2) and passed as the .I timer argument does not include accumulated leap seconds. The .C tm structure generated by .C localtime() and .C gmtime() will never reflect any leap seconds. Upon successful completion, .C mktime() forces the value of the .C tm_sec component to the range [0,59]. .PP .CR ctime() , .CR ctime_r() , .CR asctime() , and .CR asctime_r() are considered obsolescent and may be removed in a future release. Use of .IR strftime (3C) is recommended instead. .SH AUTHOR .C ctime() was developed by AT&T and HP. .SH SEE ALSO time(2), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR ctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR asctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR daylight ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR difftime() ": AES, SVID3, XPG4, ANSI C" .PP .CR gmtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR localtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mktime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR timezone ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR tzname ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tzset() ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4asctime()\fP, \f4asctime_r()\f1 \- convert \f3tm\f1 structure date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4ctime()\fP, \f4ctime_r()\f1 \- convert \f4clock()\fP date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4daylight()\fP \- Daylight Savings Time flag@@@\f3ctime(3C)\f1 .\" index@\f4gmtime()\fP, \f4gmtime_r()\fP \- convert date and time to Greenwich Mean Time@@@\f3ctime(3C)\f1 .\" index@\f4localtime()\fP, \f4localtime_r()\fP \- convert date and time to local timezone@@@\f3ctime(3C)\f1 .\" index@\f4timezone()\fP \- difference between \s-1UCT\s+1 and local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzname()\fP \- name of local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzset()\fP \- initialize \f4timezone()\fP, \f4daylight()\fP, and \f4tzname()\fP using \s-1TZ\s+1 variable@@@\f3ctime(3C)\f1 .\" index@\f4mktime()\fP \- convert time into calendar time value@@@\f3ctime(3C)\f1 .\" index@\f4difftime()\fP \- difference between two calendar time values@@@\f3ctime(3C)\f1 .\" index@convert date and time to string@@@\f3ctime(3C)\f1 .\" index@string, convert date and time to@@@\f3ctime(3C)\f1 .\" index@date and time, convert to string@@@\f3ctime(3C)\f1 .\" index@time and date, convert to string@@@\f3ctime(3C)\f1 .\" .\" toc@\f3ctime(3C)\f1:\0\0\f4ctime()\fP, \f4ctime_r()\fP, \f4localtime()\fP, \f4localtime_r()\fP, \f4difftime()\f1, \f4 mktime()\f1, \n\f4gmtime()\fP, \f4gmtime_r()\fP,\f4asctime()\fP, \f4asctime_r()\fP, \f4timezone()\fP, \f4daylight()\fP, \f4tzname()\fP,\n\f4tzset()\f1@@@convert date and time to string .\" toc@\f4ctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4ctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4timezone()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4daylight()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzname()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzset()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4difftime()\fP:\0\0difference between calendar times@@@see \f3ctime(3C)\f1 .\" toc@\f4mktime()\fP:\0\0create calendar time value@@@see \f3ctime(3C)\f1 .\" .\" links@ctime.3c ctime_r.3c .\" links@ctime.3c localtime.3c .\" links@ctime.3c localtime_r.3c .\" links@ctime.3c gmtime.3c .\" links@ctime.3c gmtime_r.3c .\" links@ctime.3c asctime.3c .\" links@ctime.3c asctime_r.3c .\" links@ctime.3c timezone.3c .\" links@ctime.3c daylight.3c .\" links@ctime.3c tzname.3c .\" links@ctime.3c tzset.3c .\" links@ctime.3c difftime.3c .\" links@ctime.3c mktime.3c .\" .\" fileset_database@ctime.3c PROGRAMING-MAN .\" $Header: asin.3m,v 78.1 96/02/13 09:39:00 ssa Exp $ .TA a .TH asin 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME asin(\|), asinf(\|) \- arcsine functions .SH SYNOPSIS .C "#include " .PP .C "double asin(double x);" .PP .C "float asinf(float x);" .SH DESCRIPTION .CR asin() returns the arcsine of .I x .ift in the range \(mi\(*p/2 to \(*p/2. .ifn in the range \(mipi/2 to pi/2. .PP .CR asinf() is a .CR float version of .CR asin() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR asinf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is NaN, .CR asin() returns NaN. .PP If the magnitude of .I x is greater than one, .CR asin() returns zero and sets .CR errno to [EDOM]. .SH ERRORS If .CR asin() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] The magnitude of .I x is greater than one. .RE .SH DEPENDENCIES Millicode versions of the .CR asin() function are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO asind(3M), sin(3M), cos(3M), tan(3M), acos(3M), atan(3M), atan2(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR asin() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4asin()\f1 \- arcsine function@@@\f3asin(3M)\f1 .\" index@\f4asinf()\f1 \- arcsine function (float)@@@\f3asin(3M)\f1 .\" index@\f1math: arcsine functions@@@\f3asin(3M)\f1 .\" index@\f1trigonometric arcsine functions@@@\f3asin(3M)\f1 .\" index@\f1arcsine functions@@@\f3asin(3M)\f1 .\" .\" toc@\f3asin(3M)\f1:\0\0\f4asin()\f1, \f4asinf()\f1@@@arcsine functions .\" toc@\f4asinf()\f1:\0\0arcsine function (float)@@@see \f3asin(3M)\f1 .\" .\" links@asin.3m asinf.3m .\" .\" fileset_database@asin.3m PROGRAMING-MAN .\" $Header: asind.3m,v 78.1 96/02/13 09:47:04 ssa Exp $ .TA a .TH asind 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME asind(\|), asindf(\|) \- degree-valued arcsine functions .SH SYNOPSIS .C "#include " .PP .C "double asind(double x);" .PP .C "float asindf(float x);" .SH DESCRIPTION .CR asind() is a degree-valued version of the .CR asin() function. It returns the arcsine of .I x in the range \(mi90 to 90. .PP .CR asindf() is a .CR float version of .CR asind() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR asind() and .CR asindf() are not specified by any standard, but .CR asindf() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is NaN, .CR asind() returns NaN. .PP If the magnitude of .I x is greater than one, .CR asind() returns zero and sets .CR errno to [EDOM]. .SH ERRORS If .CR asind() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] The magnitude of .I x is greater than one. .RE .SH SEE ALSO asin(3M), sind(3M), cosd(3M), tand(3M), acosd(3M), atand(3M), atan2d(3M), isinf(3M), isnan(3M). .\" index@\f4asind()\f1 \- arcsine function (degrees)@@@\f3asind(3M)\f1 .\" index@\f4asindf()\f1 \- arcsine function (float, degrees)@@@\f3asind(3M)\f1 .\" index@\f1math: arcsine functions (degrees)@@@\f3asind(3M)\f1 .\" index@\f1degree-valued arcsine functions@@@\f3asind(3M)\f1 .\" index@\f1trigonometric arcsine functions (degrees)@@@\f3asind(3M)\f1 .\" index@\f1arcsine functions (degrees)@@@\f3asind(3M)\f1 .\" .\" toc@\f3asind(3M)\f1:\0\0\f4asind()\f1, \f4asindf()\f1@@@degree-valued arcsine functions .\" toc@\f4asindf()\f1:\0\0arcsine function (float, degrees)@@@see \f3asind(3M)\f1 .\" .\" links@asind.3m asindf.3m .\" .\" fileset_database@asind.3m PROGRAMING-MAN .\" $Header: asind.3m,v 78.1 96/02/13 09:47:04 ssa Exp $ .TA a .TH asind 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME asind(\|), asindf(\|) \- degree-valued arcsine functions .SH SYNOPSIS .C "#include " .PP .C "double asind(double x);" .PP .C "float asindf(float x);" .SH DESCRIPTION .CR asind() is a degree-valued version of the .CR asin() function. It returns the arcsine of .I x in the range \(mi90 to 90. .PP .CR asindf() is a .CR float version of .CR asind() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR asind() and .CR asindf() are not specified by any standard, but .CR asindf() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is NaN, .CR asind() returns NaN. .PP If the magnitude of .I x is greater than one, .CR asind() returns zero and sets .CR errno to [EDOM]. .SH ERRORS If .CR asind() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] The magnitude of .I x is greater than one. .RE .SH SEE ALSO asin(3M), sind(3M), cosd(3M), tand(3M), acosd(3M), atand(3M), atan2d(3M), isinf(3M), isnan(3M). .\" index@\f4asind()\f1 \- arcsine function (degrees)@@@\f3asind(3M)\f1 .\" index@\f4asindf()\f1 \- arcsine function (float, degrees)@@@\f3asind(3M)\f1 .\" index@\f1math: arcsine functions (degrees)@@@\f3asind(3M)\f1 .\" index@\f1degree-valued arcsine functions@@@\f3asind(3M)\f1 .\" index@\f1trigonometric arcsine functions (degrees)@@@\f3asind(3M)\f1 .\" index@\f1arcsine functions (degrees)@@@\f3asind(3M)\f1 .\" .\" toc@\f3asind(3M)\f1:\0\0\f4asind()\f1, \f4asindf()\f1@@@degree-valued arcsine functions .\" toc@\f4asindf()\f1:\0\0arcsine function (float, degrees)@@@see \f3asind(3M)\f1 .\" .\" links@asind.3m asindf.3m .\" .\" fileset_database@asind.3m PROGRAMING-MAN .\" $Header: asin.3m,v 78.1 96/02/13 09:39:00 ssa Exp $ .TA a .TH asin 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME asin(\|), asinf(\|) \- arcsine functions .SH SYNOPSIS .C "#include " .PP .C "double asin(double x);" .PP .C "float asinf(float x);" .SH DESCRIPTION .CR asin() returns the arcsine of .I x .ift in the range \(mi\(*p/2 to \(*p/2. .ifn in the range \(mipi/2 to pi/2. .PP .CR asinf() is a .CR float version of .CR asin() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR asinf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is NaN, .CR asin() returns NaN. .PP If the magnitude of .I x is greater than one, .CR asin() returns zero and sets .CR errno to [EDOM]. .SH ERRORS If .CR asin() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] The magnitude of .I x is greater than one. .RE .SH DEPENDENCIES Millicode versions of the .CR asin() function are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO asind(3M), sin(3M), cos(3M), tan(3M), acos(3M), atan(3M), atan2(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR asin() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4asin()\f1 \- arcsine function@@@\f3asin(3M)\f1 .\" index@\f4asinf()\f1 \- arcsine function (float)@@@\f3asin(3M)\f1 .\" index@\f1math: arcsine functions@@@\f3asin(3M)\f1 .\" index@\f1trigonometric arcsine functions@@@\f3asin(3M)\f1 .\" index@\f1arcsine functions@@@\f3asin(3M)\f1 .\" .\" toc@\f3asin(3M)\f1:\0\0\f4asin()\f1, \f4asinf()\f1@@@arcsine functions .\" toc@\f4asinf()\f1:\0\0arcsine function (float)@@@see \f3asin(3M)\f1 .\" .\" links@asin.3m asinf.3m .\" .\" fileset_database@asin.3m PROGRAMING-MAN .\" $Header: asinh.3m,v 78.1 96/02/13 09:48:57 ssa Exp $ .TA a .TH asinh 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME asinh(\|) \- inverse hyperbolic sine function .SH SYNOPSIS .C "#include " .PP .C "double asinh(double x);" .SH DESCRIPTION The .CR asinh() function computes the inverse hyperbolic sine of its argument. .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE .PP If .I x is .ift \(+-INFINITY, .ifn +\-INFINITY, .CR asinh() returns .ift \(+-INFINITY respectively. .ifn +\-INFINITY respectively. .PP If .I x is NaN, .CR asinh() returns NaN. .SH ERRORS No errors are defined. .RE .SH SEE ALSO sinh(3M), acosh(3M), atanh(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR asinh() ": SVID3, XPG4.2" .\" index@\f4asinh()\f1 \- inverse hyperbolic sine function@@@\f3asinh(3M)\f1 .\" index@math: inverse hyperbolic sine function@@@\f3asinh(3M)\f1 .\" index@inverse hyperbolic sine function@@@\f3asinh(3M)\f1 .\" index@hyperbolic sine function, inverse@@@\f3asinh(3M)\f1 .\" index@sine function, inverse hyperbolic@@@\f3asinh(3M)\f1 .\" .\" toc@\f3asinh(3M)\f1:\0\0\f4asinh()\f1@@@inverse hyperbolic sine function .\" $Header: assert.3x,v 72.5 94/11/14 12:04:17 ssa Exp $ .TA a .TH assert 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME assert(\|) \- verify program assertion .SH SYNOPSIS .C "#include " .PP .C "void assert(int expression);" .SH DESCRIPTION .PP This macro is useful for putting diagnostics into programs. When it is executed, if .I expression is false (zero), .C assert() prints: .IP .C "Assertion failed: \f2expression\fP, file \f2xyz\fP, line \f2nnn\fP" .PP on the standard error output and aborts. In the error message, .I xyz is the name of the source file and .I nnn the source line number of the .C assert() statement. .PP Compiling with the preprocessor option .C \-DNDEBUG (see .IR cpp (1)), or with the preprocessor control statement .C "\#define NDEBUG" ahead of the .C "#include " statement, stops assertions from being compiled into the program. .SH WARNINGS The expression argument used by .C assert() in compatibility mode cannot contain string literals or double quotes without escapes. .SH SEE ALSO cpp(1), abort(3C). .SH STANDARDS CONFORMANCE .CR assert() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4assert()\f1 \- verify program assertion@@@\f3assert(3X)\f1 .\" index@\f1verify program assertion@@@\f3assert(3X)\f1 .\" index@\f1program assertion, verify@@@\f3assert(3X)\f1 .\" index@\f1assertion, verify program@@@\f3assert(3X)\f1 .\" .\" toc@\f3assert(3X)\f1:\0\0\f4assert()\f1@@@verify program assertion .\" .\" fileset_database@assert.3x PROGRAMING-MAN .\" $Header: atan.3m,v 78.1 96/02/13 09:49:28 ssa Exp $ .TA a .TH atan 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME atan(\|), atanf(\|) \- arctangent functions .SH SYNOPSIS .C "#include " .PP .C "double atan(double x);" .PP .C "float atanf(float x);" .SH DESCRIPTION .CR atan() returns the arctangent of .I x .ift in the range \(mi\(*p/2 to \(*p/2. .ifn in the range \(mipi/2 to pi/2. .PP .CR atanf() is a .CR float version of .CR atan() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR atanf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR atan() .ift returns \(+-\(*p/2 respectively. .ifn returns +\-pi/2 respectively. .PP If .I x is NaN, .CR atan() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR atan() returns zero. .SH ERRORS No errors are defined. .SH DEPENDENCIES Millicode versions of the .CR atan() function are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO atand(3M), sin(3M), cos(3M), tan(3M), asin(3M), acos(3M), atan2(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR atan() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4atan()\f1 \- arctangent function@@@\f3atan(3M)\f1 .\" index@\f4atanf()\f1 \- arctangent function (float)@@@\f3atan(3M)\f1 .\" index@\f1math: arctangent functions@@@\f3atan(3M)\f1 .\" index@\f1trigonometric arctangent functions@@@\f3atan(3M)\f1 .\" index@\f1arctangent functions@@@\f3atan(3M)\f1 .\" .\" toc@\f3atan(3M)\f1:\0\0\f4atan()\f1, \f4atanf()\f1@@@arctangent functions .\" toc@\f4atanf()\f1:\0\0arctangent function (float)@@@see \f3atan(3M)\f1 .\" .\" links@atan.3m atanf.3m .\" $Header: atan2.3m,v 78.1 96/02/13 09:49:57 ssa Exp $ .TA a .TH atan2 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME atan2(\|), atan2f(\|) \- arctangent-and-quadrant functions .SH SYNOPSIS .C "#include " .PP .C "double atan2(double y, double x);" .PP .C "float atan2f(float y, float x);" .SH DESCRIPTION .CR atan2() returns the arctangent of .IR y / x , .ift in the range \(mi\(*p to \(*p, .ifn in the range \(mipi to pi, using the signs of both arguments to determine the quadrant of the return value. .PP .CR atan2f() is a .CR float version of .CR atan2() ; it takes .CR float arguments and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float arguments to .CR double , and the function returns incorrect results. .PP .CR atan2f() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I y and .I x are +INFINITY, .CR atan2() returns .ift \(*p/4. .ifn pi/4. .PP If .I y is +INFINITY and .I x is \(miINFINITY, .CR atan2() returns .ift 3\(**\(*p/4. .ifn 3\(**pi/4. .PP If .I y is \(miINFINITY and .I x is +INFINITY, .CR atan2() returns .ift \(mi\(*p/4. .ifn \(mipi/4. .PP If .I y and .I x are \(miINFINITY, .CR atan2() returns .ift \(mi3\(**\(*p/4. .ifn \(mi3\(**pi/4. .PP If .I y is zero and .I x is a positive number, .CR atan2() returns zero. .PP If .I y is zero and .I x is a negative number, .CR atan2() returns .ift \(*p. .ifn pi. .PP If .I y is \(mizero and .I x is a negative number, .CR atan2() returns .ift \(mi\(*p. .ifn \(mipi. .PP If .I y is a positive number and .I x is zero, .CR atan2() returns .ift \(*p/2. .ifn pi/2. .PP If .I y is a negative number and .I x is zero, .CR atan2() returns .ift \(mi\(*p/2. .ifn \(mipi/2. .PP If .IR y / x would overflow, .CR atan2() returns .ift \(+-\(*p/2. .ifn +\-pi/2. .ift The result will be \(*p/2 if .ifn The result will be pi/2 if .I y .ift is a positive number and \(mi\(*p/2 if .ifn is a positive number and \(mipi/2 if .I y is a negative number. .PP If .IR y / x after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR atan2() returns .ift \(+-\(*p or zero. .ifn +\-pi or zero. The result is zero if .I x .ift is a positive number, \(*p if .ifn is a positive number, pi if .I x is a negative number and .I y .ift is a positive number, and \(mi\(*p if .ifn is a positive number, and \(mipi if .I x and .I y are both negative numbers. .PP If both .I x and .I y are zero, .CR atan2() returns NaN. .PP If .I x or .I y is NaN, .CR atan2() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR atan2() returns zero. .SH ERRORS No errors are defined. .SH DEPENDENCIES Millicode versions of the .CR atan2() function are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO atan2d(3M), sin(3M), cos(3M), tan(3M), asin(3M), acos(3M), atan(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR atan2() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4atan2()\f1 \- arctangent-and-quadrant function@@@\f3atan2(3M)\f1 .\" index@\f4atan2f()\f1 \- arctangent-and-quadrant function (float)@@@\f3atan2(3M)\f1 .\" index@\f1math: arctangent-and-quadrant functions@@@\f3atan2(3M)\f1 .\" index@\f1trigonometric arctangent-and-quadrant functions@@@\f3atan2(3M)\f1 .\" index@\f1arctangent-and-quadrant functions@@@\f3atan2(3M)\f1 .\" .\" toc@\f3atan2(3M)\f1:\0\0\f4atan2()\f1, \f4atan2f()\f1@@@arctangent-and-quadrant functions .\" toc@\f4atan2f()\f1:\0\0arctangent-and-quadrant function (float)@@@see \f3atan2(3M)\f1 .\" .\" links@atan2.3m atan2f.3m .\" .\" fileset_database@atan2.3m PROGRAMING-MAN .\" $Header: atan2d.3m,v 78.1 96/02/13 09:50:27 ssa Exp $ .TA a .TH atan2d 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME atan2d(\|), atan2df(\|) \- degree-valued arctangent-and-quadrant functions .SH SYNOPSIS .C "#include " .PP .C "double atan2d(double y, double x);" .PP .C "float atan2df(float y, float x);" .SH DESCRIPTION .CR atan2d() is a degree-valued version of the .CR atan2() function. It returns the arctangent of .IR y / x , in the range \(mi180 to 180, using the signs of both arguments to determine the quadrant of the return value. .PP .CR atan2df() is a .CR float version of .CR atan2d() ; it takes .CR float arguments and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float arguments to .CR double , and the function returns incorrect results. .PP .CR atan2d() and .CR atan2df() are not specified by any standard, but .CR atan2df() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I y and .I x are +INFINITY, .CR atan2d() returns 45. .PP If .I y is +INFINITY and .I x is \(miINFINITY, .CR atan2d() returns 135. .PP If .I y is \(miINFINITY and .I x is +INFINITY, .CR atan2d() returns \(mi45. .PP If .I y and .I x are \(miINFINITY, .CR atan2d() returns \(mi135. .PP If .I y is zero and .I x is a positive number, .CR atan2d() returns zero. .PP If .I y is zero and .I x is a negative number, .CR atan2d() returns 180. .PP If .I y is \(mizero and .I x is a negative number, .CR atan2d() returns \(mi180. .PP If .I y is a positive number and .I x is zero, .CR atan2d() returns 90. .PP If .I y is a negative number and .I x is zero, .CR atan2d() returns \(mi90. .PP If .IR y / x would overflow, .CR atan2d() .ift returns \(+-90. .ifn returns +\-90. The result will be 90 if .I y is a positive number and \(mi90 if .I y is a negative number. .PP If .IR y / x after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR atan2d() .ift returns \(+-180 .ifn returns +\-180 or zero. The result will be zero if .I x is a positive number, 180 if .I x is a negative number and .I y is a positive number, and \(mi180 if .I x and .I y are both negative numbers. .PP If both .I x and .I y are zero, .CR atan2d() returns NaN. .PP If .I x or .I y is NaN, .CR atan2d() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR atan2d() returns zero. .SH ERRORS No errors are defined. .SH SEE ALSO atan2(3M), sind(3M), cosd(3M), tand(3M), asind(3M), acosd(3M), atand(3M), isinf(3M), isnan(3M), values(5). .\" index@\f4atan2d()\f1 \- arctangent-and-quadrant function (degrees)@@@\f3atan2d(3M)\f1 .\" index@\f4atan2df()\f1 \- arctangent-and-quadrant function (float, degrees)@@@\f3atan2d(3M)\f1 .\" index@\f1math: arctangent-and-quadrant functions (degrees)@@@\f3atan2d(3M)\f1 .\" index@\f1degree-valued arctangent-and-quadrant functions@@@\f3atan2d(3M)\f1 .\" index@\f1trigonometric arctangent-and-quadrant functions (degrees)@@@\f3atan2d(3M)\f1 .\" index@\f1arctangent-and-quadrant functions (degrees)@@@\f3atan2d(3M)\f1 .\" .\" toc@\f3atan2d(3M)\f1:\0\0\f4atan2d()\f1, \f4atan2df()\f1@@@degree-valued arctangent-and-quadrant functions .\" toc@\f4atan2df()\f1:\0\0arctangent-and-quadrant function (float, degrees)@@@see \f3atan2d(3M)\f1 .\" .\" links@atan2d.3m atan2df.3m .\" .\" fileset_database@atan2d.3m PROGRAMING-MAN .\" $Header: atan2d.3m,v 78.1 96/02/13 09:50:27 ssa Exp $ .TA a .TH atan2d 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME atan2d(\|), atan2df(\|) \- degree-valued arctangent-and-quadrant functions .SH SYNOPSIS .C "#include " .PP .C "double atan2d(double y, double x);" .PP .C "float atan2df(float y, float x);" .SH DESCRIPTION .CR atan2d() is a degree-valued version of the .CR atan2() function. It returns the arctangent of .IR y / x , in the range \(mi180 to 180, using the signs of both arguments to determine the quadrant of the return value. .PP .CR atan2df() is a .CR float version of .CR atan2d() ; it takes .CR float arguments and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float arguments to .CR double , and the function returns incorrect results. .PP .CR atan2d() and .CR atan2df() are not specified by any standard, but .CR atan2df() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I y and .I x are +INFINITY, .CR atan2d() returns 45. .PP If .I y is +INFINITY and .I x is \(miINFINITY, .CR atan2d() returns 135. .PP If .I y is \(miINFINITY and .I x is +INFINITY, .CR atan2d() returns \(mi45. .PP If .I y and .I x are \(miINFINITY, .CR atan2d() returns \(mi135. .PP If .I y is zero and .I x is a positive number, .CR atan2d() returns zero. .PP If .I y is zero and .I x is a negative number, .CR atan2d() returns 180. .PP If .I y is \(mizero and .I x is a negative number, .CR atan2d() returns \(mi180. .PP If .I y is a positive number and .I x is zero, .CR atan2d() returns 90. .PP If .I y is a negative number and .I x is zero, .CR atan2d() returns \(mi90. .PP If .IR y / x would overflow, .CR atan2d() .ift returns \(+-90. .ifn returns +\-90. The result will be 90 if .I y is a positive number and \(mi90 if .I y is a negative number. .PP If .IR y / x after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR atan2d() .ift returns \(+-180 .ifn returns +\-180 or zero. The result will be zero if .I x is a positive number, 180 if .I x is a negative number and .I y is a positive number, and \(mi180 if .I x and .I y are both negative numbers. .PP If both .I x and .I y are zero, .CR atan2d() returns NaN. .PP If .I x or .I y is NaN, .CR atan2d() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR atan2d() returns zero. .SH ERRORS No errors are defined. .SH SEE ALSO atan2(3M), sind(3M), cosd(3M), tand(3M), asind(3M), acosd(3M), atand(3M), isinf(3M), isnan(3M), values(5). .\" index@\f4atan2d()\f1 \- arctangent-and-quadrant function (degrees)@@@\f3atan2d(3M)\f1 .\" index@\f4atan2df()\f1 \- arctangent-and-quadrant function (float, degrees)@@@\f3atan2d(3M)\f1 .\" index@\f1math: arctangent-and-quadrant functions (degrees)@@@\f3atan2d(3M)\f1 .\" index@\f1degree-valued arctangent-and-quadrant functions@@@\f3atan2d(3M)\f1 .\" index@\f1trigonometric arctangent-and-quadrant functions (degrees)@@@\f3atan2d(3M)\f1 .\" index@\f1arctangent-and-quadrant functions (degrees)@@@\f3atan2d(3M)\f1 .\" .\" toc@\f3atan2d(3M)\f1:\0\0\f4atan2d()\f1, \f4atan2df()\f1@@@degree-valued arctangent-and-quadrant functions .\" toc@\f4atan2df()\f1:\0\0arctangent-and-quadrant function (float, degrees)@@@see \f3atan2d(3M)\f1 .\" .\" links@atan2d.3m atan2df.3m .\" .\" fileset_database@atan2d.3m PROGRAMING-MAN .\" $Header: atan2.3m,v 78.1 96/02/13 09:49:57 ssa Exp $ .TA a .TH atan2 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME atan2(\|), atan2f(\|) \- arctangent-and-quadrant functions .SH SYNOPSIS .C "#include " .PP .C "double atan2(double y, double x);" .PP .C "float atan2f(float y, float x);" .SH DESCRIPTION .CR atan2() returns the arctangent of .IR y / x , .ift in the range \(mi\(*p to \(*p, .ifn in the range \(mipi to pi, using the signs of both arguments to determine the quadrant of the return value. .PP .CR atan2f() is a .CR float version of .CR atan2() ; it takes .CR float arguments and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float arguments to .CR double , and the function returns incorrect results. .PP .CR atan2f() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I y and .I x are +INFINITY, .CR atan2() returns .ift \(*p/4. .ifn pi/4. .PP If .I y is +INFINITY and .I x is \(miINFINITY, .CR atan2() returns .ift 3\(**\(*p/4. .ifn 3\(**pi/4. .PP If .I y is \(miINFINITY and .I x is +INFINITY, .CR atan2() returns .ift \(mi\(*p/4. .ifn \(mipi/4. .PP If .I y and .I x are \(miINFINITY, .CR atan2() returns .ift \(mi3\(**\(*p/4. .ifn \(mi3\(**pi/4. .PP If .I y is zero and .I x is a positive number, .CR atan2() returns zero. .PP If .I y is zero and .I x is a negative number, .CR atan2() returns .ift \(*p. .ifn pi. .PP If .I y is \(mizero and .I x is a negative number, .CR atan2() returns .ift \(mi\(*p. .ifn \(mipi. .PP If .I y is a positive number and .I x is zero, .CR atan2() returns .ift \(*p/2. .ifn pi/2. .PP If .I y is a negative number and .I x is zero, .CR atan2() returns .ift \(mi\(*p/2. .ifn \(mipi/2. .PP If .IR y / x would overflow, .CR atan2() returns .ift \(+-\(*p/2. .ifn +\-pi/2. .ift The result will be \(*p/2 if .ifn The result will be pi/2 if .I y .ift is a positive number and \(mi\(*p/2 if .ifn is a positive number and \(mipi/2 if .I y is a negative number. .PP If .IR y / x after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR atan2() returns .ift \(+-\(*p or zero. .ifn +\-pi or zero. The result is zero if .I x .ift is a positive number, \(*p if .ifn is a positive number, pi if .I x is a negative number and .I y .ift is a positive number, and \(mi\(*p if .ifn is a positive number, and \(mipi if .I x and .I y are both negative numbers. .PP If both .I x and .I y are zero, .CR atan2() returns NaN. .PP If .I x or .I y is NaN, .CR atan2() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR atan2() returns zero. .SH ERRORS No errors are defined. .SH DEPENDENCIES Millicode versions of the .CR atan2() function are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO atan2d(3M), sin(3M), cos(3M), tan(3M), asin(3M), acos(3M), atan(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR atan2() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4atan2()\f1 \- arctangent-and-quadrant function@@@\f3atan2(3M)\f1 .\" index@\f4atan2f()\f1 \- arctangent-and-quadrant function (float)@@@\f3atan2(3M)\f1 .\" index@\f1math: arctangent-and-quadrant functions@@@\f3atan2(3M)\f1 .\" index@\f1trigonometric arctangent-and-quadrant functions@@@\f3atan2(3M)\f1 .\" index@\f1arctangent-and-quadrant functions@@@\f3atan2(3M)\f1 .\" .\" toc@\f3atan2(3M)\f1:\0\0\f4atan2()\f1, \f4atan2f()\f1@@@arctangent-and-quadrant functions .\" toc@\f4atan2f()\f1:\0\0arctangent-and-quadrant function (float)@@@see \f3atan2(3M)\f1 .\" .\" links@atan2.3m atan2f.3m .\" .\" fileset_database@atan2.3m PROGRAMING-MAN .\" $Header: atand.3m,v 78.1 96/02/13 09:50:49 ssa Exp $ .TA a .TH atand 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME atand(\|), atandf(\|) \- degree-valued arctangent functions .SH SYNOPSIS .CR "#include " .PP .CR "double atand(double x);" .PP .CR "float atandf(float x);" .SH DESCRIPTION .CR atand() is a degree-valued version of the .CR atan() function. It returns the arctangent of .I x in the range \(mi90 to 90. .PP .CR atandf() is a .CR float version of .CR atand() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR atand() and .CR atandf() are not specified by any standard, but .CR atandf() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is .ift \(+-INFINITY, .ifn +\-INFINITY, .CR atand() .ift returns \(+-90 respectively. .ifn returns +\-90 respectively. .PP If .I x is NaN, .CR atand() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR atand() returns zero. .SH ERRORS No errors are defined. .SH SEE ALSO atan(3M), sind(3M), cosd(3M), tand(3M), asind(3M), acosd(3M), atan2d(3M), isinf(3M), isnan(3M), values(5). .\" index@\f4atand()\f1 \- arctangent function (degrees)@@@\f3atand(3M)\f1 .\" index@\f4atandf()\f1 \- arctangent function (float, degrees)@@@\f3atand(3M)\f1 .\" index@\f1math: arctangent functions (degrees)@@@\f3atand(3M)\f1 .\" index@\f1degree-valued arctangent functions@@@\f3atand(3M)\f1 .\" index@\f1trigonometric arctangent functions (degrees)@@@\f3atand(3M)\f1 .\" index@\f1arctangent functions (degrees)@@@\f3atand(3M)\f1 .\" .\" toc@\f3atand(3M)\f1:\0\0\f4atand()\f1, \f4atandf()\f1@@@degree-valued arctangent functions .\" toc@\f4atandf()\f1:\0\0arctangent function (float, degrees)@@@see \f3atand(3M)\f1 .\" .\" links@atand.3m atandf.3m .\" $Header: atand.3m,v 78.1 96/02/13 09:50:49 ssa Exp $ .TA a .TH atand 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME atand(\|), atandf(\|) \- degree-valued arctangent functions .SH SYNOPSIS .CR "#include " .PP .CR "double atand(double x);" .PP .CR "float atandf(float x);" .SH DESCRIPTION .CR atand() is a degree-valued version of the .CR atan() function. It returns the arctangent of .I x in the range \(mi90 to 90. .PP .CR atandf() is a .CR float version of .CR atand() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR atand() and .CR atandf() are not specified by any standard, but .CR atandf() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is .ift \(+-INFINITY, .ifn +\-INFINITY, .CR atand() .ift returns \(+-90 respectively. .ifn returns +\-90 respectively. .PP If .I x is NaN, .CR atand() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR atand() returns zero. .SH ERRORS No errors are defined. .SH SEE ALSO atan(3M), sind(3M), cosd(3M), tand(3M), asind(3M), acosd(3M), atan2d(3M), isinf(3M), isnan(3M), values(5). .\" index@\f4atand()\f1 \- arctangent function (degrees)@@@\f3atand(3M)\f1 .\" index@\f4atandf()\f1 \- arctangent function (float, degrees)@@@\f3atand(3M)\f1 .\" index@\f1math: arctangent functions (degrees)@@@\f3atand(3M)\f1 .\" index@\f1degree-valued arctangent functions@@@\f3atand(3M)\f1 .\" index@\f1trigonometric arctangent functions (degrees)@@@\f3atand(3M)\f1 .\" index@\f1arctangent functions (degrees)@@@\f3atand(3M)\f1 .\" .\" toc@\f3atand(3M)\f1:\0\0\f4atand()\f1, \f4atandf()\f1@@@degree-valued arctangent functions .\" toc@\f4atandf()\f1:\0\0arctangent function (float, degrees)@@@see \f3atand(3M)\f1 .\" .\" links@atand.3m atandf.3m .\" $Header: atan.3m,v 78.1 96/02/13 09:49:28 ssa Exp $ .TA a .TH atan 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME atan(\|), atanf(\|) \- arctangent functions .SH SYNOPSIS .C "#include " .PP .C "double atan(double x);" .PP .C "float atanf(float x);" .SH DESCRIPTION .CR atan() returns the arctangent of .I x .ift in the range \(mi\(*p/2 to \(*p/2. .ifn in the range \(mipi/2 to pi/2. .PP .CR atanf() is a .CR float version of .CR atan() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR atanf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR atan() .ift returns \(+-\(*p/2 respectively. .ifn returns +\-pi/2 respectively. .PP If .I x is NaN, .CR atan() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR atan() returns zero. .SH ERRORS No errors are defined. .SH DEPENDENCIES Millicode versions of the .CR atan() function are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO atand(3M), sin(3M), cos(3M), tan(3M), asin(3M), acos(3M), atan2(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR atan() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4atan()\f1 \- arctangent function@@@\f3atan(3M)\f1 .\" index@\f4atanf()\f1 \- arctangent function (float)@@@\f3atan(3M)\f1 .\" index@\f1math: arctangent functions@@@\f3atan(3M)\f1 .\" index@\f1trigonometric arctangent functions@@@\f3atan(3M)\f1 .\" index@\f1arctangent functions@@@\f3atan(3M)\f1 .\" .\" toc@\f3atan(3M)\f1:\0\0\f4atan()\f1, \f4atanf()\f1@@@arctangent functions .\" toc@\f4atanf()\f1:\0\0arctangent function (float)@@@see \f3atan(3M)\f1 .\" .\" links@atan.3m atanf.3m .\" $Header: atanh.3m,v 78.1 96/02/13 09:51:15 ssa Exp $ .TA a .TH atanh 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME atanh(\|) \- inverse hyperbolic tangent function .SH SYNOPSIS .C "#include " .PP .C "double atanh(double x);" .SH DESCRIPTION The .CR atanh() function computes the inverse hyperbolic tangent of its argument. .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE .PP If .I x is NaN, .CR atanh() returns NaN. .PP If .RI | x | > 1.0, .CR atanh() returns NaN and sets .CR errno to [EDOM]. .PP If .RI | x | = 1.0, .CR atanh() returns .ift .CR \(+-HUGE_VAL .ifn .CR +\-HUGE_VAL (according to the sign of .IR x ) and sets .CR errno to [ERANGE]. .SH ERRORS If .CR atanh() fails, .CR errno is set to one of the following values. .RS .TP 20 [EDOM] .I x has an absolute value greater than 1.0. .TP 20 [ERANGE] .I x has an absolute value equal to 1.0. .RE .SH SEE ALSO tanh(3M), asinh(3M), acosh(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR atanh() ": SVID3, XPG4.2" .\" index@\f4atanh()\f1 \- inverse hyperbolic tangent function@@@\f3atanh(3M)\f1 .\" index@math: inverse hyperbolic tangent function@@@\f3atanh(3M)\f1 .\" index@inverse hyperbolic tangent function@@@\f3atanh(3M)\f1 .\" index@hyperbolic tangent function, inverse@@@\f3atanh(3M)\f1 .\" index@tangent function, inverse hyperbolic@@@\f3atanh(3M)\f1 .\" .\" toc@\f3atanh(3M)\f1:\0\0\f4atanh()\f1@@@inverse hyperbolic tangent function ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH atfork 3 "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Latfork\*O(\|)" .SH NAME .PP \*Latfork\*O \- Arranges for fork cleanup handling .SH SYNOPSIS .sS \*L#include \*O .PP \*Lvoid atfork .nL void (*\*Vuser_state\*L, .nL void (*\*Vpre_fork)(\|)\*L, .nL void (*\*Vparent_fork)(\|)\*L, .nL void (*\*Vchild_fork)(\|)\*L); .sE .br .ne 1.5i .SH "PARAMETERS" .VL 6m .LI "\*Vuser_state\*O" Pointer to the user state that is passed to each routine. .LI "\*Vpre_fork\*O" Routine to be called before performing the fork. .LI "\*Vparent_fork\*O" Routine to be called in the parent after the fork. .LI "\*Vchild_fork\*O" Routine to be called in the child after the fork. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Latfork(\|)\*O routine allows you to register three routines to be executed at different times relative to a fork. The different times and/or places are as follows: .nL Just prior to the fork in the parent process. .nL Just after the fork in the parent process. .nL Just after the fork in the created (child) process. .PP Use these routines to clean up just prior to \*Lfork\*O(\|), to set up after \*Lfork\*O(\|), and to perform locking relative to \*Lfork\*O(\|). You are allowed to provide one parameter to be used in conjunction with all the routines. This parameter must be \*Vuser_state\*O. .br .ne 1.5i .SH "RETURN VALUES" .PP The \*Latfork\*O(\|) routine does not return a value. Instead, an exception is raised if there is insufficient table space to record the handler addresses. .br .ne .8i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lfork(2)\*O. .ad b .\" $Header: strtod.3c,v 72.6 94/11/30 15:47:58 ssa Exp $ .TA s .TH strtod 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strtod, atof \- convert string to double-precision number .SH SYNOPSIS .C "#include " .PP .C "double strtod(const char *str, char **ptr);" .PP .C "double atof(const char *str);" .SH DESCRIPTION .C strtod() returns, as a double-precision floating-point number, the value represented by the character string pointed to by .IR str . The string is scanned (leading white-space characters as defined by .C isspace() in .IR ctype (3C) are ignored) up to the first unrecognized character. If no conversion can take place, zero is returned. .PP .C strtod() recognizes characters in the following sequence: .RS .TP 5 1. An optional string of ``white-space'' characters which are ignored, .PD 0 .TP 2. An optional sign, .TP 3. A string of digits optionally containing a radix character, .TP 4. An optional .C e or .C E followed by an optional sign or space, followed by an integer. .PD .RE .PP The radix character is determined by the loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C", is used (see .IR lang (5)). The default environment specifies a period (.) as the radix character. .PP If the value of .I ptr is not .CR "(char **)NULL , the variable to which it points is set to point at the character after the last number, if any, that was recognized. If no number can be formed, .I \(**ptr is set to .IR str , and zero is returned. .PP .CI atof( str ) is equivalent to .CI "strtod (" str ", (char **)NULL)\f1." .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the value of the radix character within the currently loaded .SM NLS environment. .SH RETURN VALUE If the correct value would cause overflow, .C +HUGE_VAL or .C -HUGE_VAL is returned (according to the sign of the value), and .C errno is set to .SM ERANGE. .PP If the correct value would cause underflow, zero is returned and .C errno is set to .SM ERANGE. .SH AUTHOR .C strtod() was developed by AT&T and HP. .SH SEE ALSO ctype(3C), setlocale(3C), scanf(3S), strtol(3C), hpnls(5), lang(5). .SH STANDARDS CONFORMANCE .CR strtod() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR atof() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4strtod()\fP \- convert string to double-precision number@@@\f3strtod(3C)\f1 .\" index@\f4atof()\fP \- convert string to double-precision number@@@\f3strtod(3C)\f1 .\" index@convert string to double-precision number@@@\f3strtod(3C)\f1 .\" index@string to double-precision number, convert@@@\f3strtod(3C)\f1 .\" index@double-precision number, convert string to@@@\f3strtod(3C)\f1 .\" index@number, convert string to double-precision@@@\f3strtod(3C)\f1 .\" .\" toc@\f3strtod(3C)\f1:\0\0\f4strtod()\fP, \f4atof()\f1@@@convert string to double-precision number .\" toc@\f4atof()\fP:\0\0convert string to double-precision number@@@see \f3strtod(3C)\f1 .\" .\" links@strtod.3c atof.3c .\" links@strtod.3c nl_strtod.3c .\" links@strtod.3c nl_atof.3c .\" $Header: strtol.3c,v 72.5 94/11/15 09:56:32 ssa Exp $ .TA s .TH strtol 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strtol(\|), atol(\|), atoi(\|), strtoul(\|) \- convert string to integer .SH SYNOPSIS .C "#include " .PP .C "long strtol(const char *str, char **ptr, int base);" .PP .C "long atol(const char *str);" .PP .C "int atoi(const char *str);" .PP .C "unsigned long strtoul(const char *str, char **ptr, int base);" .SH DESCRIPTION .C strtol() .RC ( strtoul() ) converts the character string pointed to by .I str to .C long int .RC ( "unsigned long int" ) representation. The string is scanned up to the first character inconsistent with the base. Leading ``white-space'' characters (as defined by .C isspace() in .IR ctype (3C)) are ignored. If no conversion can take place, zero is returned. .PP If .I base is greater than or equal to 2 and less than or equal to 36, it is used as the base for conversion. After an optional leading sign, leading zeros are ignored, and .C 0x or .C 0X is ignored if .I base is 16. .PP If .I base is zero, the string itself determines the base as follows: After an optional leading sign, a leading zero indicates octal conversion; a leading .C 0x or .C 0X hexadecimal conversion. Otherwise, decimal conversion is used. .PP If the value of .I ptr is not .CR "(char **)NULL" , a pointer to the character terminating the scan is returned in the location pointed to by .IR ptr . If no integer can be formed, the location pointed to by .I ptr is set to .IR str , and zero is returned. .PP .CI atol ( str ) is equivalent to .CI "strtol(" str ", (char **)NULL, 10)\f1." .PP .CI atoi( str ) is equivalent to .CI "int strtol(" str ", (char **)NULL, 10)\f1." .SH RETURN VALUE Upon successful completion, all functions return the converted value, if any. If the correct value would cause overflow, .C strtol() returns .C LONG_MAX or .C LONG_MIN (according to the sign of the value), and sets .C errno to .SM ERANGE; .C strtoul() returns .C ULONG_MAX and sets .C errno to .SM ERANGE. Overflow conditions are ignored by .C atol() and .CR atoi() . .PP For all other errors, zero is returned and .C errno is set to indicate the error. .SH ERRORS .C strtol() and .C strtoul() fail and .C errno is set if any of the following conditions are encountered: .RS .TP 15 .SM [EINVAL] The value of .I base is not supported. .TP .SM [ERANGE] The value to be returned would have caused overflow. .RE .SH AUTHOR .CR strtol() , .CR atoi() , and .CR atol() , were developed by OSF and HP. .SH SEE ALSO ctype(3C), strtod(3C), scanf(3S). .SH STANDARDS CONFORMANCE .CR strtol() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR atoi() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR atol() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtoul() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4strtol()\fP \(mi convert string to long integer@@@\f3strtol(3C)\f1 .\" index@\f4atol()\fP \(mi convert string to long integer@@@\f3strtol(3C)\f1 .\" index@\f4atoi()\fP \(mi convert string to long integer@@@\f3strtol(3C)\f1 .\" index@\f1string to long integer, convert@@@\f3strtol(3C)\f1 .\" index@\f1integer, convert string to long@@@\f3strtol(3C)\f1 .\" .\" toc@\f3strtol(3C)\f:\0\0\f4strtol()\f1, \f4atol()\f1, \f4atoi()\f1@@@convert string to integer .\" toc@\f4atol()\f1:\0\0convert string to integer@@@\f1see \f3strtol(3C)\f1 .\" toc@\f4atoi()\f1:\0\0convert string to integer@@@\f1see \f3strtol(3C)\f1 .\" .\" links@strtol.3c atol.3c .\" links@strtol.3c atoi.3c .\" links@strtol.3c strtoul.3c .\" .\" fileset_database@strtol.3c PROGRAMING-MAN .\" $Header: strtol.3c,v 72.5 94/11/15 09:56:32 ssa Exp $ .TA s .TH strtol 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strtol(\|), atol(\|), atoi(\|), strtoul(\|) \- convert string to integer .SH SYNOPSIS .C "#include " .PP .C "long strtol(const char *str, char **ptr, int base);" .PP .C "long atol(const char *str);" .PP .C "int atoi(const char *str);" .PP .C "unsigned long strtoul(const char *str, char **ptr, int base);" .SH DESCRIPTION .C strtol() .RC ( strtoul() ) converts the character string pointed to by .I str to .C long int .RC ( "unsigned long int" ) representation. The string is scanned up to the first character inconsistent with the base. Leading ``white-space'' characters (as defined by .C isspace() in .IR ctype (3C)) are ignored. If no conversion can take place, zero is returned. .PP If .I base is greater than or equal to 2 and less than or equal to 36, it is used as the base for conversion. After an optional leading sign, leading zeros are ignored, and .C 0x or .C 0X is ignored if .I base is 16. .PP If .I base is zero, the string itself determines the base as follows: After an optional leading sign, a leading zero indicates octal conversion; a leading .C 0x or .C 0X hexadecimal conversion. Otherwise, decimal conversion is used. .PP If the value of .I ptr is not .CR "(char **)NULL" , a pointer to the character terminating the scan is returned in the location pointed to by .IR ptr . If no integer can be formed, the location pointed to by .I ptr is set to .IR str , and zero is returned. .PP .CI atol ( str ) is equivalent to .CI "strtol(" str ", (char **)NULL, 10)\f1." .PP .CI atoi( str ) is equivalent to .CI "int strtol(" str ", (char **)NULL, 10)\f1." .SH RETURN VALUE Upon successful completion, all functions return the converted value, if any. If the correct value would cause overflow, .C strtol() returns .C LONG_MAX or .C LONG_MIN (according to the sign of the value), and sets .C errno to .SM ERANGE; .C strtoul() returns .C ULONG_MAX and sets .C errno to .SM ERANGE. Overflow conditions are ignored by .C atol() and .CR atoi() . .PP For all other errors, zero is returned and .C errno is set to indicate the error. .SH ERRORS .C strtol() and .C strtoul() fail and .C errno is set if any of the following conditions are encountered: .RS .TP 15 .SM [EINVAL] The value of .I base is not supported. .TP .SM [ERANGE] The value to be returned would have caused overflow. .RE .SH AUTHOR .CR strtol() , .CR atoi() , and .CR atol() , were developed by OSF and HP. .SH SEE ALSO ctype(3C), strtod(3C), scanf(3S). .SH STANDARDS CONFORMANCE .CR strtol() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR atoi() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR atol() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtoul() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4strtol()\fP \(mi convert string to long integer@@@\f3strtol(3C)\f1 .\" index@\f4atol()\fP \(mi convert string to long integer@@@\f3strtol(3C)\f1 .\" index@\f4atoi()\fP \(mi convert string to long integer@@@\f3strtol(3C)\f1 .\" index@\f1string to long integer, convert@@@\f3strtol(3C)\f1 .\" index@\f1integer, convert string to long@@@\f3strtol(3C)\f1 .\" .\" toc@\f3strtol(3C)\f:\0\0\f4strtol()\f1, \f4atol()\f1, \f4atoi()\f1@@@convert string to integer .\" toc@\f4atol()\f1:\0\0convert string to integer@@@\f1see \f3strtol(3C)\f1 .\" toc@\f4atoi()\f1:\0\0convert string to integer@@@\f1see \f3strtol(3C)\f1 .\" .\" links@strtol.3c atol.3c .\" links@strtol.3c atoi.3c .\" links@strtol.3c strtoul.3c .\" .\" fileset_database@strtol.3c PROGRAMING-MAN .\" $Header: attr_get.3x,v 76.2 95/07/31 11:21:27 ssa Exp $ .TA a .de Fn .C \\$1() .. .de Hd .BR <\\$1> .. .TH attr_get 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attr_get, attr_off, attr_on, attr_set, color_set, wattr_get, wattr_off, wattr_on, wattr_set, wcolor_set \(em window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attr_get(attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int attr_off(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_on(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_set(attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int color_set(short \f2color\fP);" .P .C "int wattr_get(WINDOW *\f2win\fP, attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wattr_off(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_on(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_set(WINDOW *\f2win\fP, attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wcolor_set(WINDOW *\f2win\fP, short \f2color\fP);" .SH DESCRIPTION These functions manipulate the attributes and color of the window rendition of the current or specified window. .P The .Fn attr_get and .Fn wattr_get functions obtain the current rendition of a window. .P The .Fn attr_off and .Fn wattr_off functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_on and .Fn wattr_on functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_set and .Fn wattr_set functions set the window rendition of the current or specified window to \f2attrs\f1 and \f2color\f1. .P The .Fn color_set and .Fn wcolor_set functions set the window color of the current or specified window to color. .P The \f2opts\f1 argument is reswerved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" These functions always return OK. .SH ERRORS No errors are defined. .SH "SEE ALSO" attroff(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3attr_get(3X)\f1:\0\0\f4attr_off()\f1, \f4attr_on()\f1, \f4attr_set()\f1, \f4color_set()\f1, \f4wattr_get()\f1, \f4wattr_off()\f1, \n\f4wattr_on()\f1, \f4wattr_set()\f1, \f4wcolor_set()\f1@@@window attribute control functions .\" toc@\f4attr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_get()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4color_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wcolor_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" .\" index@\f4attr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4color_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wcolor_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1attribute, for window, control functions@@@\f3attr_get(3X)\f1 .\" index@\f1control functions for window attribute@@@\f3attr_get(3X)\f1 .\" .\" links@attr_get.3x attr_set.3x .\" links@attr_get.3x attr_off.3x .\" links@attr_get.3x attr_on.3x .\" links@attr_get.3x wattr_set.3x .\" links@attr_get.3x wattr_get.3x .\" links@attr_get.3x wattr_off.3x .\" links@attr_get.3x wattr_on.3x .\" links@attr_get.3x color_set.3x .\" links@attr_get.3x wcolor_set.3x .\" .\" fileset_database@attr_get.3x CURS-ENG-A-MAN .\" $Header: attr_get.3x,v 76.2 95/07/31 11:21:27 ssa Exp $ .TA a .de Fn .C \\$1() .. .de Hd .BR <\\$1> .. .TH attr_get 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attr_get, attr_off, attr_on, attr_set, color_set, wattr_get, wattr_off, wattr_on, wattr_set, wcolor_set \(em window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attr_get(attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int attr_off(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_on(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_set(attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int color_set(short \f2color\fP);" .P .C "int wattr_get(WINDOW *\f2win\fP, attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wattr_off(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_on(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_set(WINDOW *\f2win\fP, attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wcolor_set(WINDOW *\f2win\fP, short \f2color\fP);" .SH DESCRIPTION These functions manipulate the attributes and color of the window rendition of the current or specified window. .P The .Fn attr_get and .Fn wattr_get functions obtain the current rendition of a window. .P The .Fn attr_off and .Fn wattr_off functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_on and .Fn wattr_on functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_set and .Fn wattr_set functions set the window rendition of the current or specified window to \f2attrs\f1 and \f2color\f1. .P The .Fn color_set and .Fn wcolor_set functions set the window color of the current or specified window to color. .P The \f2opts\f1 argument is reswerved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" These functions always return OK. .SH ERRORS No errors are defined. .SH "SEE ALSO" attroff(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3attr_get(3X)\f1:\0\0\f4attr_off()\f1, \f4attr_on()\f1, \f4attr_set()\f1, \f4color_set()\f1, \f4wattr_get()\f1, \f4wattr_off()\f1, \n\f4wattr_on()\f1, \f4wattr_set()\f1, \f4wcolor_set()\f1@@@window attribute control functions .\" toc@\f4attr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_get()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4color_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wcolor_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" .\" index@\f4attr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4color_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wcolor_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1attribute, for window, control functions@@@\f3attr_get(3X)\f1 .\" index@\f1control functions for window attribute@@@\f3attr_get(3X)\f1 .\" .\" links@attr_get.3x attr_set.3x .\" links@attr_get.3x attr_off.3x .\" links@attr_get.3x attr_on.3x .\" links@attr_get.3x wattr_set.3x .\" links@attr_get.3x wattr_get.3x .\" links@attr_get.3x wattr_off.3x .\" links@attr_get.3x wattr_on.3x .\" links@attr_get.3x color_set.3x .\" links@attr_get.3x wcolor_set.3x .\" .\" fileset_database@attr_get.3x CURS-ENG-A-MAN .\" $Header: attr_get.3x,v 76.2 95/07/31 11:21:27 ssa Exp $ .TA a .de Fn .C \\$1() .. .de Hd .BR <\\$1> .. .TH attr_get 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attr_get, attr_off, attr_on, attr_set, color_set, wattr_get, wattr_off, wattr_on, wattr_set, wcolor_set \(em window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attr_get(attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int attr_off(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_on(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_set(attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int color_set(short \f2color\fP);" .P .C "int wattr_get(WINDOW *\f2win\fP, attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wattr_off(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_on(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_set(WINDOW *\f2win\fP, attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wcolor_set(WINDOW *\f2win\fP, short \f2color\fP);" .SH DESCRIPTION These functions manipulate the attributes and color of the window rendition of the current or specified window. .P The .Fn attr_get and .Fn wattr_get functions obtain the current rendition of a window. .P The .Fn attr_off and .Fn wattr_off functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_on and .Fn wattr_on functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_set and .Fn wattr_set functions set the window rendition of the current or specified window to \f2attrs\f1 and \f2color\f1. .P The .Fn color_set and .Fn wcolor_set functions set the window color of the current or specified window to color. .P The \f2opts\f1 argument is reswerved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" These functions always return OK. .SH ERRORS No errors are defined. .SH "SEE ALSO" attroff(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3attr_get(3X)\f1:\0\0\f4attr_off()\f1, \f4attr_on()\f1, \f4attr_set()\f1, \f4color_set()\f1, \f4wattr_get()\f1, \f4wattr_off()\f1, \n\f4wattr_on()\f1, \f4wattr_set()\f1, \f4wcolor_set()\f1@@@window attribute control functions .\" toc@\f4attr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_get()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4color_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wcolor_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" .\" index@\f4attr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4color_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wcolor_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1attribute, for window, control functions@@@\f3attr_get(3X)\f1 .\" index@\f1control functions for window attribute@@@\f3attr_get(3X)\f1 .\" .\" links@attr_get.3x attr_set.3x .\" links@attr_get.3x attr_off.3x .\" links@attr_get.3x attr_on.3x .\" links@attr_get.3x wattr_set.3x .\" links@attr_get.3x wattr_get.3x .\" links@attr_get.3x wattr_off.3x .\" links@attr_get.3x wattr_on.3x .\" links@attr_get.3x color_set.3x .\" links@attr_get.3x wcolor_set.3x .\" .\" fileset_database@attr_get.3x CURS-ENG-A-MAN .\" $Header: attr_get.3x,v 76.2 95/07/31 11:21:27 ssa Exp $ .TA a .de Fn .C \\$1() .. .de Hd .BR <\\$1> .. .TH attr_get 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attr_get, attr_off, attr_on, attr_set, color_set, wattr_get, wattr_off, wattr_on, wattr_set, wcolor_set \(em window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attr_get(attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int attr_off(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_on(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_set(attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int color_set(short \f2color\fP);" .P .C "int wattr_get(WINDOW *\f2win\fP, attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wattr_off(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_on(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_set(WINDOW *\f2win\fP, attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wcolor_set(WINDOW *\f2win\fP, short \f2color\fP);" .SH DESCRIPTION These functions manipulate the attributes and color of the window rendition of the current or specified window. .P The .Fn attr_get and .Fn wattr_get functions obtain the current rendition of a window. .P The .Fn attr_off and .Fn wattr_off functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_on and .Fn wattr_on functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_set and .Fn wattr_set functions set the window rendition of the current or specified window to \f2attrs\f1 and \f2color\f1. .P The .Fn color_set and .Fn wcolor_set functions set the window color of the current or specified window to color. .P The \f2opts\f1 argument is reswerved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" These functions always return OK. .SH ERRORS No errors are defined. .SH "SEE ALSO" attroff(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3attr_get(3X)\f1:\0\0\f4attr_off()\f1, \f4attr_on()\f1, \f4attr_set()\f1, \f4color_set()\f1, \f4wattr_get()\f1, \f4wattr_off()\f1, \n\f4wattr_on()\f1, \f4wattr_set()\f1, \f4wcolor_set()\f1@@@window attribute control functions .\" toc@\f4attr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_get()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4color_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wcolor_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" .\" index@\f4attr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4color_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wcolor_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1attribute, for window, control functions@@@\f3attr_get(3X)\f1 .\" index@\f1control functions for window attribute@@@\f3attr_get(3X)\f1 .\" .\" links@attr_get.3x attr_set.3x .\" links@attr_get.3x attr_off.3x .\" links@attr_get.3x attr_on.3x .\" links@attr_get.3x wattr_set.3x .\" links@attr_get.3x wattr_get.3x .\" links@attr_get.3x wattr_off.3x .\" links@attr_get.3x wattr_on.3x .\" links@attr_get.3x color_set.3x .\" links@attr_get.3x wcolor_set.3x .\" .\" fileset_database@attr_get.3x CURS-ENG-A-MAN .\" $Header: attroff.3x,v 76.2 95/07/31 11:26:00 ssa Exp $ .TA a .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH attroff 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attroff, attron, attrset, wattroff, wattron, wattrset \(em restricted window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attroff(int \f2attrs\fP);" .P .C "int attron(int \f2attrs\fP);" .P .C "int attrset(int \f2attrs\fP);" .P .C "int wattroff(WINDOW *\f2win\fP, int \f2attrs\fP);" .P .C "int wattron(WINDOW *\f2win\fP, int \f2attrs\fP);" .P .C "int wattrset(WINDOW *\f2win\fP, int \f2attrs\fP);" .SH DESCRIPTION These functions manipulate the window attributes of the current or specified window. .P The .Fn attroff and .Fn wattroff functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attron and .Fn wattron functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attrset and .Fn wattrset functions set the background attributes of the current or specified window to \f2attrs\f1. .P It is unspecified whether these functions can be used to manipulate attributes other than .CR A_BLINK , .CR A_BOLD , .CR A_DIM , .CR A_REVERSE , .CR A_STANDOUT and .CR A_UNDERLINE . .SH "RETURN VALUE" These functions always return either .CR OK or .CR 1 . .SH ERRORS No errors are defined. .SH "SEE ALSO" attr_get(), standend(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" This entry is rewritten for clarity. The .BR DESCRIPTION is updated to specify that it is undefined whether these functions can be used to manipulate attributes beyond those defined in X/Open Curses, Issue 3. The .CR standend() , .CR standout() , .Fn wstandend and .Fn wstandout functions are moved to the .Fn standend entry. .\" toc@\f3attroff(3X)\f1:\0\0\f4attron()\f1, \f4attrset()\f1, \f4wattroff()\f1, \f4wattron()\f1, \f4wattrset()\f1\n@@@restricted window attribute control functions .\" toc@\f4attron()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4attrset()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattroff()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattron()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattrset()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" .\" index@\f4attroff()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4attron()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4attrset()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattroff()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattron()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattrset()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f1restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f1window attribute control functions, restricted@@@\f3attroff(3X)\f1 .\" index@\f1control functions, restricted window attribute@@@\f3attroff(3X)\f1 .\" .\" links@attroff.3x attron.3x .\" links@attroff.3x attrset.3x .\" links@attroff.3x wattron.3x .\" links@attroff.3x wattroff.3x .\" links@attroff.3x wattrset.3x .\" .\" fileset_database@attroff.3x CURS-ENG-A-MAN .\" $Header: attroff.3x,v 76.2 95/07/31 11:26:00 ssa Exp $ .TA a .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH attroff 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attroff, attron, attrset, wattroff, wattron, wattrset \(em restricted window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attroff(int \f2attrs\fP);" .P .C "int attron(int \f2attrs\fP);" .P .C "int attrset(int \f2attrs\fP);" .P .C "int wattroff(WINDOW *\f2win\fP, int \f2attrs\fP);" .P .C "int wattron(WINDOW *\f2win\fP, int \f2attrs\fP);" .P .C "int wattrset(WINDOW *\f2win\fP, int \f2attrs\fP);" .SH DESCRIPTION These functions manipulate the window attributes of the current or specified window. .P The .Fn attroff and .Fn wattroff functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attron and .Fn wattron functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attrset and .Fn wattrset functions set the background attributes of the current or specified window to \f2attrs\f1. .P It is unspecified whether these functions can be used to manipulate attributes other than .CR A_BLINK , .CR A_BOLD , .CR A_DIM , .CR A_REVERSE , .CR A_STANDOUT and .CR A_UNDERLINE . .SH "RETURN VALUE" These functions always return either .CR OK or .CR 1 . .SH ERRORS No errors are defined. .SH "SEE ALSO" attr_get(), standend(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" This entry is rewritten for clarity. The .BR DESCRIPTION is updated to specify that it is undefined whether these functions can be used to manipulate attributes beyond those defined in X/Open Curses, Issue 3. The .CR standend() , .CR standout() , .Fn wstandend and .Fn wstandout functions are moved to the .Fn standend entry. .\" toc@\f3attroff(3X)\f1:\0\0\f4attron()\f1, \f4attrset()\f1, \f4wattroff()\f1, \f4wattron()\f1, \f4wattrset()\f1\n@@@restricted window attribute control functions .\" toc@\f4attron()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4attrset()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattroff()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattron()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattrset()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" .\" index@\f4attroff()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4attron()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4attrset()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattroff()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattron()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattrset()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f1restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f1window attribute control functions, restricted@@@\f3attroff(3X)\f1 .\" index@\f1control functions, restricted window attribute@@@\f3attroff(3X)\f1 .\" .\" links@attroff.3x attron.3x .\" links@attroff.3x attrset.3x .\" links@attroff.3x wattron.3x .\" links@attroff.3x wattroff.3x .\" links@attroff.3x wattrset.3x .\" .\" fileset_database@attroff.3x CURS-ENG-A-MAN .\" $Header: attroff.3x,v 76.2 95/07/31 11:26:00 ssa Exp $ .TA a .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH attroff 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attroff, attron, attrset, wattroff, wattron, wattrset \(em restricted window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attroff(int \f2attrs\fP);" .P .C "int attron(int \f2attrs\fP);" .P .C "int attrset(int \f2attrs\fP);" .P .C "int wattroff(WINDOW *\f2win\fP, int \f2attrs\fP);" .P .C "int wattron(WINDOW *\f2win\fP, int \f2attrs\fP);" .P .C "int wattrset(WINDOW *\f2win\fP, int \f2attrs\fP);" .SH DESCRIPTION These functions manipulate the window attributes of the current or specified window. .P The .Fn attroff and .Fn wattroff functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attron and .Fn wattron functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attrset and .Fn wattrset functions set the background attributes of the current or specified window to \f2attrs\f1. .P It is unspecified whether these functions can be used to manipulate attributes other than .CR A_BLINK , .CR A_BOLD , .CR A_DIM , .CR A_REVERSE , .CR A_STANDOUT and .CR A_UNDERLINE . .SH "RETURN VALUE" These functions always return either .CR OK or .CR 1 . .SH ERRORS No errors are defined. .SH "SEE ALSO" attr_get(), standend(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" This entry is rewritten for clarity. The .BR DESCRIPTION is updated to specify that it is undefined whether these functions can be used to manipulate attributes beyond those defined in X/Open Curses, Issue 3. The .CR standend() , .CR standout() , .Fn wstandend and .Fn wstandout functions are moved to the .Fn standend entry. .\" toc@\f3attroff(3X)\f1:\0\0\f4attron()\f1, \f4attrset()\f1, \f4wattroff()\f1, \f4wattron()\f1, \f4wattrset()\f1\n@@@restricted window attribute control functions .\" toc@\f4attron()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4attrset()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattroff()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattron()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattrset()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" .\" index@\f4attroff()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4attron()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4attrset()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattroff()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattron()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattrset()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f1restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f1window attribute control functions, restricted@@@\f3attroff(3X)\f1 .\" index@\f1control functions, restricted window attribute@@@\f3attroff(3X)\f1 .\" .\" links@attroff.3x attron.3x .\" links@attroff.3x attrset.3x .\" links@attroff.3x wattron.3x .\" links@attroff.3x wattroff.3x .\" links@attroff.3x wattrset.3x .\" .\" fileset_database@attroff.3x CURS-ENG-A-MAN ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" .rm zA .rm zZ .TH audit_intro 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "enh,10234,R1.1,new manpage." .SH NAME .PP \*Laudit_intro\*O - Introduction to the DCE Audit API runtime. .SH "DESCRIPTION" .PP This introduction gives general information about the DCE Audit Application Programming Interface (API) and an overview of the following parts of the DCE Audit API runtime: .iX "API overview" .iX "Application Programming Interface" .iX "DCE Audit Application Programming Interface" .iX "Audit" "Application Programming Interface" .ad l .ML .LI Runtime services .LI Environment variables .LI Data types and structures .LI Permissions required .LE .ad b .SS "Runtime Services" .PP The following is an alphabetical list of the Audit API routines. .iX "routines" "Audit API support" With each routine name is its description. The types of application program that will most likely call the routine are enclosed in parentheses. .PP .VL 4m .LI "\*Ldce_aud_close()\*O" Closes an audit trail (client/server applications, audit trail analysis and examination tools). .LI "\*Ldce_aud_commit()\*O" Performs the audit action(s) (client/server applications). .LI "\*Ldce_aud_discard()\*O" Discards an audit record which releases the memory (client/server applications, audit trail analysis and examination tools). .LI "\*Ldce_aud_free_ev_info()\*O" Frees the memory allocated for an event information structure returned from calling the dce_aud_get_ev_info() function (audit trail analysis and examination tools). .LI "\*Ldce_aud_free_header()\*O" Frees the memory allocated to a designated audit record header structure (audit trail analysis and examination tools). .LI "\*Ldce_aud_get_ev_info()\*O" Gets the event-specific information of a specified audit record (audit trail analysis and examination tools). .LI "\*Ldce_aud_get_header()\*O" Gets the header of a specified audit record (audit trail analysis and examination tools). .LI "\*Ldce_aud_length()\*O" Gets the length of a specified audit record (client/server applications, audit trail analysis and examination tools). .LI "\*Ldce_aud_next()\*O" Reads the next audit record from a specified audit trail into a buffer (audit trail analysis and examination tools). .LI "\*Ldce_aud_open()\*O" Opens a specified audit trail for read or write (client/server applications, audit trail analysis and examination tools). .LI "\*Ldce_aud_print()\*O" Formats an audit record into a human-readable form (audit trail analysis and examination tools). .LI "\*Ldce_aud_put_ev_info()\*O" Adds event-specific information to a specified audit record buffer (client/server applications). .LI "\*Ldce_aud_set_trail_size_limit()\*O" Sets a limit to the audit trail size (client/server applications). .LI "\*Ldce_aud_start()\*O" Determines whether a specified event should be audited given the client's binding information and the event outcome. If the event should be audited or if it is not yet known whether the event should be audited because the event outcome is still unknown, memory for the audit record descriptor is allocated and the address of this memory is returned to the caller (client/server applications). .LI "\*Ldce_aud_start_with_name()\*O" Determines whether a specified event should be audited given the client/server name and the event outcome. If the event should be audited or if it is not yet known whether the event should be audited because the event outcome is still unknown, memory for the audit record descriptor is allocated and the address of this memory is returned to the caller (client/server applications). .LI "\*Ldce_aud_start_with_pac()\*O" Determines whether a specified event should be audited given the client's Privilege Attribute Certificate (PAC) and the event outcome. If the event should be audited or if it is not yet known whether the event should be audited because the event outcome is still unknown, memory for the audit record descriptor is allocated and the address of this memory is returned to the caller (client/server applications). .LI "\*Ldce_aud_start_with_server_binding()\*O" Determines whether a specified event should be audited given the server's binding information and the event outcome. If the event should be audited or if it is not yet known whether the event should be audited because the event outcome is still unknown, memory for the audit record descriptor is allocated and the address of this memory is returned to the caller (client/server applications). .zA "enh,11884,R1.1,new API." .LI "\*Ldce_aud_start_with_uuid()\*O" Determines whether a specified event should be audited given the client/server UUID and the event outcome. If the event must be audited, or if the outcome of the event is not yet known, the memory for the audit record descriptor is allocated and the address of this structure is returned to the caller (client/server applications). .zZ "enh,11884,R1.1,new API." .LE .SS "Audit Data Types" .PP The following subsections list the data types and structures used by applications to perform auditing and to analyze audit trails. .VL 2m .LI "\*LEvent-Specific Information\*O" The Audit APIs allow applications to include event-specific information in audit records. Event-specific information must be represented as information items using the following data type. .iS typedef struct { unsigned16 format; union { idl_small_int small_int; idl_short_int short_int; idl_long_int long_int; idl_hyper_int hyper_int; idl_usmall_int usmall_int; idl_ushort_int ushort_int; idl_ulong_int ulong_int; idl_uhyper_int uhyper_int; idl_short_float short_float; idl_long_float long_float; idl_boolean boolean; uuid_t uuid; utc_t utc; sec_acl_t * acl; idl_byte * byte_string; idl_char * char_string; } data; } dce_aud_ev_info_t; .iE .iX "Audit event information types" .PP The \*Lformat\*O field of the above data structure defines formatting information that is used to determine the type of the data referenced by the \*Ldata\*O field. The following table shows possible values of the \*Lformat\*O field, their corresponding data types, and their sizes. .PP ...\" .TB "Event Data Format Specifiers \(em intro(3)" .TS center box tab(@); cb s s lb | lb | lb lb | lb | l. Event Data Format Specifiers \(em intro(3) _ Specifier@Data Type@Size _ aud_c_evt_info_small_int@idl_small_int@1 byte aud_c_evt_info_short_int@idl_short_int@2 bytes aud_c_evt_info_long_int@idl_long_int@4 bytes aud_c_evt_info_hyper_int@idl_hyper_int@8 bytes aud_c_evt_info_usmall_int@idl_usmall_int@1 bytes aud_c_evt_info_ushort_int@idl_ushort_int@2 bytes aud_c_evt_info_ulong_int@idl_ulong_int@4 bytes aud_c_evt_info_uhyper_int@idl_uhyper_int@8 bytes aud_c_evt_info_short_float@idl_short_float@4 bytes aud_c_evt_info_long_float@idl_long_float@8 bytes aud_c_evt_info_boolean@idl_boolean@1 byte aud_c_evt_info_uuid@uuid_t@16 bytes aud_c_evt_info_utc@utc_t@16 bytes aud_c_evt_info_acl@sec_acl_t *@variable size aud_c_evt_info_byte_string@idl_byte *@variable size aud_c_evt_info_char_string@idl_char *@variable size .TE .PP Byte strings and character strings are terminated with a 0 (zero) byte. New data types can be added to this list if they are used frequently. Servers could use the pickling service of the IDL compiler to encode complex data types into byte strings that are to be included in an audit record. .LI "\*LAudit Record Header Data Structure\*O" The following data structure is used to store header information obtained from an audit record. This structure is normally only used by audit trail analysis and examination tools. That is, it is hidden from client/server applications. .iS typedef struct { unsigned32 format; uuid_t server; unsigned32 event; unsigned16 outcome; unsigned16 authz_st; uuid_t client; uuid_t cell; unsigned16 num_groups; utc_t time; char *addr; uuid_t *groups; } dce_aud_hdr_t; .iE .VL 8m .LI "\*Lformat\*O" Contains the version number of the tail format of the event used for the event-specific information. With this format version number, the audit analysis tools can accommodate changes in the formats of the event-specific information. For example, the event-specific information of an event may initially be defined to be a 32-bit integer, and later changed to a character string. Format version 0 (zero) is assigned to the initial format for each event. .LI "\*Lserver\*O" Contains the UUID of the server that generates the audit record. .LI "\*Levent\*O" Contains the event number. .LI "\*Loutcome\*O" Indicates whether the event failed or succeeded. If the event failed, the reason for the failure is given. .LI "\*Lauthz_st\*O" Indicates how the client is authorized: by a name or by a DCE Privilege Attribute Certificate (PAC). .LI "\*Lclient\*O" Contains the UUID of the client. .LI "\*Lcell\*O" Contains the UUID of the client's cell. .LI "\*Lnum_groups\*O" Contains the number of local group privileges the client used for access. .LI "\*Lgroups\*O" Contains the UUIDs of the local group privileges that are used by the client for the access. By default, the group information is not be included in the header (num_groups is set to 0 in this case), to minimize the size of the audit records. If the group information is deemed as important, it can be included. .P Information about foreign groups (global groups that do not belong to the same cell where the client is registered) is not included in this version of audit header but may be included in later versions when global groups are supported. .LI "\*Ltime\*O" Contains a timestamp of \*Lutc_t\*O type that records the time when the server committed the audit record (that is, after providing the event information through audit API function calls). Recording this time, rather than recording the time when the audit record is appended to an audit trail, will better maintain the sequence of events. The implementation of the audit subsystem may involve communication between the server and a remote audit daemon, incurring indefinite delays by network problems or intruders. The inaccuracy in the \*Lutc_t\*O timestamp may be useful for correlating events. When searching for events in an audit trail that occur within a time interval, if the results of the comparisons between the time of an event and the interval's starting and ending times is \*Lmaybe\*O (because of inaccuracies), then the event should be returned. .LI "\*Laddr\*O" Records the client's address (port address of the caller). Port addresses are not authenticated. A caller can provide a fraudulent port address to a DCE server. However, if this unauthenticated port address is deemed to be useful information, a DCE server can record this information using this field. .LE .PP The identity of the server cell is not recorded in the header, because of the assumption that all audit records in an audit trail are for servers within a single cell, and implicitly, the server cell is the local cell. .LI "\*LAudit Record Descriptor\*O" An opaque data type, \*Ldce_aud_rec_t\*O, is used to represent an audit record descriptor. An audit record descriptor may be created, manipulated, or disposed of by the following functions: The functions \*Ldce_aud_start()\*O, \*Ldce_aud_start_with_pac()\*O, \*Ldce_aud_start_with_name()\*O, \*Ldce_aud_start_with_server_binding()\*O, and \*Ldce_aud_next()\*O return a record descriptor. The function \*Ldce_aud_put_ev_info()\*O adds event information to an audit record through a record descriptor. The functions \*Ldce_aud_get_header()\*O, \*Ldce_aud_get_ev_info()\*O, and \*Ldce_aud_length()\*O get the event and record information through a record descriptor. The function \*Ldce_aud_commit()\*O commits an audit record through its descriptor. The function \*Ldce_aud_discard()\*O disposes of a record descriptor. The function \*Ldce_aud_discard()\*O is necessary only after reading the record (that is, after invoking \*Ldce_aud_next()\*O. .LI "\*LAudit Trail Descriptor\*O" An opaque data type, \*Ldce_aud_trail_t\*O, is used to represent an audit trail descriptor. The \*Ldce_aud_open()\*O function opens an audit trail and returns a trail descriptor; \*Ldce_aud_next()\*O obtains an audit record from this descriptor; and \*Ldce_aud_commit()\*O commits an audit record from and to an opened audit trail through this descriptor. The \*Ldce_aud_close()\*O function disposes of this descriptor. .LE .SS "Environment Variables" .PP The Audit API routines use the following environment variables: .VL 2.0i .LI "DCEAUDITOFF" If this environment variable is defined at the time the application is started, auditing is turned off. .LI "DCEAUDITFILTERON" If this environment variable is defined, filtering is enabled. .LI "DCEAUDITTRAILSIZE" Sets the limit of the audit trail size. This variable overrides the limit set by the \*Ldce_aud_set_trail_size_limit()\*O function. .LE .SS "Permissions Required" .PP To use an Audit daemon's audit record logging service, you need the log (\*Ll\*O) permission to the Audit daemon. .br .ne .75i .SH "RELATED INFORMATION" .PP .ad l Books: \*VOSF DCE Administration Reference\*O, \*VOSF DCE Application Development Guide\*O. .ad b .br .ne .75i .SH "RELATED INFORMATION" .PP .ad l Books: \*VOSF DCE Administration Reference\*O, \*VOSF DCE Application Development Guide\*O. .ad b .zZ "enh,10234,R1.1,new manpage." .\" $Header: secure_rpc.3c,v 74.1 95/05/10 21:12:12 ssa Exp $ .TA s .TH secure_rpc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME secure_rpc(), authdes_create(), authdes_getucred(), get_myaddress(), getnetname(), host2netname(), key_decryptsession(), key_encryptsession(), key_gendes(), key_setsecret(), netname2host(), netname2user(), user2netname() \- library routines for secure remote procedure calls .SH DESCRIPTION .LP .C RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .LP .C RPC allows various authentication flavors. The .B authdes_getucred() and .B authdes_create() routines implement the .B DES authentication flavor. See .BR rpc_clnt_auth (3C) for routines relating to the .B AUTH_NONE and .B AUTH_UNIX authentication types. .IP Note: Both the client and server should have their keys in the .BR publickey (5) database. Also, the keyserver daemon .BR keyserv (1M) must be running on both the client and server hosts for the .B DES authentication system to work. .SS Routines .LP The following routines require that the header .BR be included. .PP The .B AUTH data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "AUTH *" .C "authdes_create(netname, window, syncaddr, deskeyp)" .C "char *netname;" .C "unsigned window;" .C "struct sockaddr_in *syncaddr;" .C "des_block *deskeyp;" .fi .IP .B authdes_create() is an interface to the .B RPC secure authentication system, known as .B DES authentication. .IP Used on the client side, .B authdes_create() returns an authentication handle that enables the use of the secure authentication system. The first parameter .I netname is the network name of the owner of the server process. This field usually represents a .I host derived from the utility routine .BR host2netname() , but could also represent a user name using .BR user2netname() . The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third parameter .I syncaddr is optional. If it is .B NULL, then the authentication system will assume that the local clock is always in sync with the server's clock, and will not attempt to synchronize with the server. If an address is supplied then the system will use it for consulting the remote time service whenever resynchronization is required. This parameter is usually the address of the .B RPC server itself. The final parameter .I deskeyp is also optional. If it is .B NULL, then the authentication system will generate a random .B DES key to be used for the encryption of credentials. If .I deskeyp is supplied then it is used instead. .PP .nf .C "int" .C "authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)" .C "struct authdes_cred *adc;" .C "short *uidp, *gidp, *gidlenp;" .C "int *gidlistp;" .fi .IP .BR authdes_getucred() , is a .B DES authentication routine used by the server for converting a .B DES credential, which is operating system independent, into a .B UNIX credential. .I uidp points to the user .B ID of the user associated with .IR adc ; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. .br .ne 5 .IP This routine differs from the utility routine .B netname2user() in that .B authdes_getucred() pulls its information from a cache, and does not have to do a .B NIS name service lookup every time it is called to get its information. Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "void" .C "get_myaddress(addr)" .C "struct sockaddr_in *addr;" .fi .IP Return the machine's .B IP address in .IR addr. The port number is always set to .BR htons(PMAPPORT) . .PP .nf .C "int" .C "getnetname(netname)" .C "char netname[MAXNETNAMELEN];" .fi .IP Return the unique, operating-system independent netname of the caller in the fixed-length array .IR netname . Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "int" .C "host2netname(netname, host, domain)" .C "char netname[MAXNETNAMELEN];" .C "char *host;" .C "char *domain;" .fi .IP Convert from a domain-specific hostname to an operating-system independent netname. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . This routine should be used if the owner of the server process is the machine that is, the user with effective user .B ID zero. Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2host() . .PP .nf .C "int" .C "key_decryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP An interface routine to the keyserver daemon, which is associated with .B RPC's secure authentication system ( .B DES authentication). User programs rarely need to call it, or its associated routines .BR key_encryptsession() , .B key_gendes() and .BR key_setsecret() . System commands such as .B login and the .B RPC library are the main clients of these four routines. .IP .B key_decryptsession() takes the netname of a server and a .B DES key, and decrypts the key by using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_encryptsession() . .PP .nf .C "int" .C "key_encryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It takes the netname of the server and a .B DES key, and encrypts it using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_decryptsession() . .PP .nf .C "int" .C "key_gendes(deskeyp)" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It is used to ask the keyserver for a secure conversation key. Choosing one at random is usually not good enough, because the common ways of choosing random numbers, such as using the current time, are very easy to guess. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "key_setsecret(keyp)" .C "char *keyp;" .fi .IP A keyserver interface routine. It is used to set the secret key for the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "netname2host(netname, host, hostlen)" .C "char *netname;" .C "char *host;" .C "int hostlen;" .fi .IP Convert an operating-system independent netname to a domain-specific hostname. .I hostlen specifies the size of the array pointed to by .I host. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR host2netname() . .PP .nf .C "int" .C "netname2user(netname, uidp, gidp, gidlenp, gidlistp)" .C "char *netname;" .C "int *uidp, *gidp, *gidlenp, *gidlistp;" .fi .IP Convert an operating-system independent netname to a domain-specific user .B ID. .I uidp points to the user .B ID of the user; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR user2netname() . .PP .nf .C "int" .C "user2netname(netname, uid, domain)" .C "char netname[MAXNETNAMELEN];" .C "int uid;" .C "char *domain;" .fi .IP Convert a domain-specific username to an operating-system independent netname. .I uid is the user .B ID of the owner of the server process. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2user() . .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR login (1), .BR chkey (1), .BR rpc (3C), .BR rpc_clnt_auth (3C), .BR publickey (4), .BR keyserv (1M), .BR newkey (1M) .\" toc@\f3secure_rpc(3C)\f1:\0\0\f4authdes_create()\fP, \f4authdes_getucred()\fP, \f4get_myaddress()\fP, \n\f4getnetaddress()\fP, \f4getnetname()\fP, \f4host2netname()\fP, \n\f4key_decryptsession()\fP, \f4key_encryptsession()\fP, \f4key_gendes()\fP, \n\f4key_setsecret()\fP, \f4netname2host()\fP, \f4netname2user()\fP, \n\f4user2netname()\fP@@@library routines for secure remote procedure calls .\" toc@\f4secure_rpc()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_create()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_getucred()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4get_myaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4host2netname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_decryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_encryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_gendes()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_setsecret()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2host()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2user()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4user2netname()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" index@library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4secure_rpc()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_create()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_getucred()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4get_myaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4host2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_decryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_encryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_gendes()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_setsecret()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2host()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2user()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4user2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" links@secure_rpc.3c authdes_create.3c .\" links@secure_rpc.3c authdes_getucred.3c .\" links@secure_rpc.3c get_myaddress.3c .\" links@secure_rpc.3c getnetaddress.3c .\" links@secure_rpc.3c getnetname.3c .\" links@secure_rpc.3c host2netname.3c .\" links@secure_rpc.3c key_decryptsession.3c .\" links@secure_rpc.3c key_encryptsession.3c .\" links@secure_rpc.3c key_gendes.3c .\" links@secure_rpc.3c key_setsecret.3c .\" links@secure_rpc.3c netname2host.3c .\" links@secure_rpc.3c netname2user.3c .\" links@secure_rpc.3c user2netname.3c .\" $Header: secure_rpc.3c,v 74.1 95/05/10 21:12:12 ssa Exp $ .TA s .TH secure_rpc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME secure_rpc(), authdes_create(), authdes_getucred(), get_myaddress(), getnetname(), host2netname(), key_decryptsession(), key_encryptsession(), key_gendes(), key_setsecret(), netname2host(), netname2user(), user2netname() \- library routines for secure remote procedure calls .SH DESCRIPTION .LP .C RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .LP .C RPC allows various authentication flavors. The .B authdes_getucred() and .B authdes_create() routines implement the .B DES authentication flavor. See .BR rpc_clnt_auth (3C) for routines relating to the .B AUTH_NONE and .B AUTH_UNIX authentication types. .IP Note: Both the client and server should have their keys in the .BR publickey (5) database. Also, the keyserver daemon .BR keyserv (1M) must be running on both the client and server hosts for the .B DES authentication system to work. .SS Routines .LP The following routines require that the header .BR be included. .PP The .B AUTH data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "AUTH *" .C "authdes_create(netname, window, syncaddr, deskeyp)" .C "char *netname;" .C "unsigned window;" .C "struct sockaddr_in *syncaddr;" .C "des_block *deskeyp;" .fi .IP .B authdes_create() is an interface to the .B RPC secure authentication system, known as .B DES authentication. .IP Used on the client side, .B authdes_create() returns an authentication handle that enables the use of the secure authentication system. The first parameter .I netname is the network name of the owner of the server process. This field usually represents a .I host derived from the utility routine .BR host2netname() , but could also represent a user name using .BR user2netname() . The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third parameter .I syncaddr is optional. If it is .B NULL, then the authentication system will assume that the local clock is always in sync with the server's clock, and will not attempt to synchronize with the server. If an address is supplied then the system will use it for consulting the remote time service whenever resynchronization is required. This parameter is usually the address of the .B RPC server itself. The final parameter .I deskeyp is also optional. If it is .B NULL, then the authentication system will generate a random .B DES key to be used for the encryption of credentials. If .I deskeyp is supplied then it is used instead. .PP .nf .C "int" .C "authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)" .C "struct authdes_cred *adc;" .C "short *uidp, *gidp, *gidlenp;" .C "int *gidlistp;" .fi .IP .BR authdes_getucred() , is a .B DES authentication routine used by the server for converting a .B DES credential, which is operating system independent, into a .B UNIX credential. .I uidp points to the user .B ID of the user associated with .IR adc ; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. .br .ne 5 .IP This routine differs from the utility routine .B netname2user() in that .B authdes_getucred() pulls its information from a cache, and does not have to do a .B NIS name service lookup every time it is called to get its information. Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "void" .C "get_myaddress(addr)" .C "struct sockaddr_in *addr;" .fi .IP Return the machine's .B IP address in .IR addr. The port number is always set to .BR htons(PMAPPORT) . .PP .nf .C "int" .C "getnetname(netname)" .C "char netname[MAXNETNAMELEN];" .fi .IP Return the unique, operating-system independent netname of the caller in the fixed-length array .IR netname . Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "int" .C "host2netname(netname, host, domain)" .C "char netname[MAXNETNAMELEN];" .C "char *host;" .C "char *domain;" .fi .IP Convert from a domain-specific hostname to an operating-system independent netname. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . This routine should be used if the owner of the server process is the machine that is, the user with effective user .B ID zero. Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2host() . .PP .nf .C "int" .C "key_decryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP An interface routine to the keyserver daemon, which is associated with .B RPC's secure authentication system ( .B DES authentication). User programs rarely need to call it, or its associated routines .BR key_encryptsession() , .B key_gendes() and .BR key_setsecret() . System commands such as .B login and the .B RPC library are the main clients of these four routines. .IP .B key_decryptsession() takes the netname of a server and a .B DES key, and decrypts the key by using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_encryptsession() . .PP .nf .C "int" .C "key_encryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It takes the netname of the server and a .B DES key, and encrypts it using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_decryptsession() . .PP .nf .C "int" .C "key_gendes(deskeyp)" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It is used to ask the keyserver for a secure conversation key. Choosing one at random is usually not good enough, because the common ways of choosing random numbers, such as using the current time, are very easy to guess. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "key_setsecret(keyp)" .C "char *keyp;" .fi .IP A keyserver interface routine. It is used to set the secret key for the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "netname2host(netname, host, hostlen)" .C "char *netname;" .C "char *host;" .C "int hostlen;" .fi .IP Convert an operating-system independent netname to a domain-specific hostname. .I hostlen specifies the size of the array pointed to by .I host. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR host2netname() . .PP .nf .C "int" .C "netname2user(netname, uidp, gidp, gidlenp, gidlistp)" .C "char *netname;" .C "int *uidp, *gidp, *gidlenp, *gidlistp;" .fi .IP Convert an operating-system independent netname to a domain-specific user .B ID. .I uidp points to the user .B ID of the user; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR user2netname() . .PP .nf .C "int" .C "user2netname(netname, uid, domain)" .C "char netname[MAXNETNAMELEN];" .C "int uid;" .C "char *domain;" .fi .IP Convert a domain-specific username to an operating-system independent netname. .I uid is the user .B ID of the owner of the server process. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2user() . .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR login (1), .BR chkey (1), .BR rpc (3C), .BR rpc_clnt_auth (3C), .BR publickey (4), .BR keyserv (1M), .BR newkey (1M) .\" toc@\f3secure_rpc(3C)\f1:\0\0\f4authdes_create()\fP, \f4authdes_getucred()\fP, \f4get_myaddress()\fP, \n\f4getnetaddress()\fP, \f4getnetname()\fP, \f4host2netname()\fP, \n\f4key_decryptsession()\fP, \f4key_encryptsession()\fP, \f4key_gendes()\fP, \n\f4key_setsecret()\fP, \f4netname2host()\fP, \f4netname2user()\fP, \n\f4user2netname()\fP@@@library routines for secure remote procedure calls .\" toc@\f4secure_rpc()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_create()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_getucred()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4get_myaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4host2netname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_decryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_encryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_gendes()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_setsecret()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2host()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2user()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4user2netname()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" index@library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4secure_rpc()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_create()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_getucred()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4get_myaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4host2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_decryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_encryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_gendes()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_setsecret()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2host()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2user()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4user2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" links@secure_rpc.3c authdes_create.3c .\" links@secure_rpc.3c authdes_getucred.3c .\" links@secure_rpc.3c get_myaddress.3c .\" links@secure_rpc.3c getnetaddress.3c .\" links@secure_rpc.3c getnetname.3c .\" links@secure_rpc.3c host2netname.3c .\" links@secure_rpc.3c key_decryptsession.3c .\" links@secure_rpc.3c key_encryptsession.3c .\" links@secure_rpc.3c key_gendes.3c .\" links@secure_rpc.3c key_setsecret.3c .\" links@secure_rpc.3c netname2host.3c .\" links@secure_rpc.3c netname2user.3c .\" links@secure_rpc.3c user2netname.3c .\" $Header: basename.3c,v 72.3 94/10/17 16:27:52 ssa Exp $ .TA b .TH basename 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME basename(\|), dirname(\|) \- extract components of a path name .SH SYNOPSIS .C "#include " .PP .C "char *basename(char *path);" .PP .C "char *dirname(char *path);" .SH DESCRIPTION .C basename() takes the path name pointed to by .I path and returns a pointer to the final component of the path name, deleting any trailing '/' characters. If the string consists entirely of '/' characters, .C basename() returns a pointer to the string "/". If .I path is a null pointer or points to the empty string, .C basename() returns a pointer to the string ".". .PP .C dirname() takes the path name pointed to by .I path and returns a pointer to a string that is a path name of the parent directory of that file. If .I path is a null pointer, points to the empty string, or does not contain a '/' character, then .C dirname() returns a pointer to the string ".". .SH RETURN VALUE .C basename() returns a pointer to the final component of .IR path . .PP .C dirname() returns a pointer to a string that is the parent directory of .IR path . .SH EXAMPLES The following code fragment calls .C basename() and .CR dirname() . .nf .IP .C #include .IP .C char *path="/usr/local/bin/foo"; .C char *base, dir; .IP .C base=basename(path); .C dir=dirname(path); .fi .SH WARNINGS The return value points to static data whose content is overwritten by each call. .SH AUTHOR .C basename() and .C dirname() were developed by HP. .SH SEE ALSO basename(1). .SH STANDARDS CONFORMANCE .nf .CR basename() ": XPG4.2 .CR dirname() ": XPG4.2 .fi .\" .\" toc@\f3basename(3C)\f1:\0\0\f4basename()\f1, \f4dirname()\f1@@@extract components of a path name .\" toc@\f4dirname()\f1:\0\0return path name of parent directory@@@\f1see \f3basename(3C)\f1 .\" .\" index@\f4basename()\f1 \- return final component of path name@@@\f3basename(3C)\f1 .\" index@\f4dirname()\f1 \- return path name of parent directory@@@\f3basename(3C)\f1 .\" index@\f1path name of parent directory@@@\f3basename(3C)\f1 .\" index@\f1path name component@@@\f3basename(3C)\f1 .\" .\" links@basename.3c dirname.3c .\" .\" fileset_database@basename.3c PROGRAMING-MAN .\" $Header: baudrate.3x,v 76.2 95/07/31 11:27:34 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH baudrate 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME baudrate \(em get terminal baud rate .SH SYNOPSIS .C "#include " .P .C "int baudrate(void);" .SH DESCRIPTION The .Fn baudrate function extracts the output speed of the terminal in bits per second. .SH "RETURN VALUE" The .Fn baudrate function returns the output speed of the terminal. .SH ERRORS No errors are defined. .SH "SEE ALSO" tcgetattr() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The argument list is explicitly declared as \f3void\f1. .\" .\" index@\f4baudrate()\f1 \- get terminal baud rate@@@\f3baudrate(3X)\f1 .\" index@\f1get terminal baud rate@@@\f3baudrate(3X)\f1 .\" index@\f1terminal baud rate, get@@@\f3baudrate(3X)\f1 .\" index@\f1baud rate, get terminal@@@\f3baudrate(3X)\f1 .\" .\" toc@\f3baudrate(3X)\f1:\0\0\f4baudrate\f1@@@get terminal baud rate .\" .\" fileset_database@baudrate.3x CURS-ENG-A-MAN .\" $Header: memory.3c,v 74.1 95/03/23 17:24:13 ssa Exp $ .TA m .TH memory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME memccpy(\|), memchr(\|), memcmp(\|), memcpy(\|), memmove(\|), memset(\|), bcopy(\|), bcmp(\|), bzero(\|), ffs(\|) \- memory operations .SH SYNOPSIS .C "#include " .PP .C "void *memccpy(void *s1, const void *s2, int c, size_t n);" .PP .C "void *memchr(const void *s, int c, size_t n);" .PP .C "int memcmp(const void *s1, const void *s2, size_t n);" .PP .C "void *memcpy(void *s1, const void *s2, size_t n);" .PP .C "void *memmove(void *s1, const void *s2, size_t n);" .PP .C "void *memset(void *s, int c, size_t n);" .PP .C "#include " .PP .C "int bcmp(const void *s1, const void *s2, size_t n);" .PP .C "void bcopy(const void *s1, void *s2, size_t n);" .PP .C "void bzero(char *s, int n);" .PP .C "int ffs(int i);" .SS Remarks: .CR bcmp() , .CR bcopy() , .CR bzero() , .CR ffs() , and .RC < strings.h > are provided solely for portability of .SM BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .CR memcmp() , .CR memmove() , and .CR memset() , respectively. .C ffs() has no portable equivalent. .SH DESCRIPTION These functions operate as efficiently as possible on memory areas (arrays of bytes bounded by a count, not terminated by a null byte). They do not check for the overflow of any receiving memory area. .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RC < string.h > header file. .TP 15 .C memccpy() Copy bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 , stopping after the first occurrence of byte .I c has been copied, or after .I n bytes have been copied, whichever comes first. If copying takes place between objects that overlap, the behavior is undefined. .C memccpy() returns a pointer to the bvyte after the copy of .I c in .IR s1 , or a .SM NULL pointer if .I c was not found in the first .I n bytes of .IR s2 . .TP .C memchr() Locate the first occurrence of .I c (converted to an .CR "unsigned char" ) in the initial .I n bytes (each interpreted as .CR "unsigned char" ) of the object pointed to by .IR s . .C memchr() returns a pointer to the located byte, or a .SM NULL pointer if the byte does not occur in the object. .TP .C memcmp() Compare the first .I n bytes of the object pointed to by .I s1 to the first .I n bytes of the object pointed to by .IR s2 . .C memcmp() returns an integer greater than, equal to, or less than zero, according to whether the object pointed to by .I s1 is greater than, equal to, or less than the object pointed to by .IR s2 . The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes (both interpreted as .CR "unsigned char" ) that differ in the objects being compared. .TP .C memcpy() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . If copying takes place between objects that overlap, the behavior is undefined. .C memcpy() returns the value of .IR s1 . .TP .C memmove() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . Copying takes place as if the .I n bytes from the object pointed to by .I s2 are first copied into a temporary array of .I n bytes that does not overlap the objects pointed to by .I s1 and .IR s2 , and then the .I n bytes from the temporary array are copied into the object pointed to by .IR s1 . .C memmove() returns the value of .IR s1 . .TP .C memset() Copy the value of .I c (converted to an .CR "unsigned char" ) into each of the first .I n bytes of the object pointed to by .IR s . .C memset() returns the value of .IR s . .TP .C bcopy() copies .I n bytes from the area pointed to by .I s1 to the area pointed to by .IR s2 . .TP .C bcmp() Compare the first .I n bytes of the area pointed to by .I s1 with the area pointed to by .IR s2 . .C bcmp() returns zero if they are identical; non-zero otherwise. Both areas are assumed to be .I n bytes in length. .TP .C bzero() Clear .I n bytes in the area pointed to by .I s by setting them to zero. .TP .C ffs() Find the first bit set (beginning with the least significant bit) and return the index of that bit. Bits are numbered starting at one. A return value of 0 indicates that .I i is zero. .SS International Code Set Support These functions support only single-byte byte code sets. .SH WARNINGS The functions defined in .RC < string.h > were previously defined in .RC < memory.h >. .SH FILES .C /usr/include/string.h .SH SEE ALSO string(3C) .SH STANDARDS CONFORMANCE .CR memccpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR memchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memmove() ": AES, SVID3, XPG4, ANSI C" .PP .CR memset() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4memcpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memccpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memchr()\f1 \- find first occurrence of byte in memory area@@@\f3memory(3C)\f1 .\" index@\f4memcmp()\f1 \- compare byte with memory contents@@@\f3memory(3C)\f1 .\" index@\f4memmove()\f1 \- move memory contents@@@\f3memory(3C)\f1 .\" index@\f4memset()\f1 \- set area in memory to contain a specified byte@@@\f3memory(3C)\f1 .\" index@\f4bcopy()\f1 \- \s-1BSD\s+1 memory copy@@@\f3memory(3C)\f1 .\" index@\f4bcmp()\f1 \- \s-1BSD\s+1 memory compare@@@\f3memory(3C)\f1 .\" index@\f4bzero()\f1 \- \s-1BSD\s+1 memory clear@@@\f3memory(3C)\f1 .\" index@\f4ffs()\f1 \- \s-1BSD\s+1 find first set bit@@@\f3memory(3C)\f1 .\" index@\f1memory operations \- copy, compare, test for contents, or set contents to value@@@\f3memory(3C)\f1 .\" index@\f1copy memory to another area@@@\f3memory(3C)\f1 .\" index@\f1test contents of memory area@@@\f3memory(3C)\f1 .\" index@\f1compare contents of memory with byte@@@\f3memory(3C)\f1 .\" index@\f1preset contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1set contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1byte, set contents of memory area to specified@@@\f3memory(3C)\f1 .\" index@\f1byte, compare memory contents with specified@@@\f3memory(3C)\f1 .\" index@\f1byte, find location of in memory@@@\f3memory(3C)\f1 .\" index@\f1location of byte in memory, find@@@\f3memory(3C)\f1 .\" .\" toc@\f3memory(3C)\f1:\0\0\f4memccpy()\f1, \f4memchr()\f1, \f4memcmp()\f1, \f4memcpy()\f1, \f4memset()\f1, \n\f4bcopy()\f1, \f4bcmp()\f1, \f4bzero()\f1, \f4ffs()\f1@@@memory operations .\" toc@\f4memccpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memchr()\f1:\0\0memory operations, locate first character@@@see \f3memory(3C)\f1 .\" toc@\f4memcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memcpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memmove()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memset()\f1:\0\0memory operations, set memory@@@see \f3memory(3C)\f1 .\" toc@\f4bcopy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bzero()\f1:\0\0memory operations, clear bytes@@@see \f3memory(3C)\f1 .\" toc@\f4ffs()\f1:\0\0memory operations, find first bit set@@@see \f3memory(3C)\f1 .\" .\" links@memory.3c memccpy.3c .\" links@memory.3c memchr.3c .\" links@memory.3c memcmp.3c .\" links@memory.3c memcpy.3c .\" links@memory.3c memmove.3c .\" links@memory.3c memset.3c .\" links@memory.3c bcopy.3c .\" links@memory.3c bcmp.3c .\" links@memory.3c bzero.3c .\" links@memory.3c ffs.3c .\" .\" $Header: memory.3c,v 74.1 95/03/23 17:24:13 ssa Exp $ .TA m .TH memory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME memccpy(\|), memchr(\|), memcmp(\|), memcpy(\|), memmove(\|), memset(\|), bcopy(\|), bcmp(\|), bzero(\|), ffs(\|) \- memory operations .SH SYNOPSIS .C "#include " .PP .C "void *memccpy(void *s1, const void *s2, int c, size_t n);" .PP .C "void *memchr(const void *s, int c, size_t n);" .PP .C "int memcmp(const void *s1, const void *s2, size_t n);" .PP .C "void *memcpy(void *s1, const void *s2, size_t n);" .PP .C "void *memmove(void *s1, const void *s2, size_t n);" .PP .C "void *memset(void *s, int c, size_t n);" .PP .C "#include " .PP .C "int bcmp(const void *s1, const void *s2, size_t n);" .PP .C "void bcopy(const void *s1, void *s2, size_t n);" .PP .C "void bzero(char *s, int n);" .PP .C "int ffs(int i);" .SS Remarks: .CR bcmp() , .CR bcopy() , .CR bzero() , .CR ffs() , and .RC < strings.h > are provided solely for portability of .SM BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .CR memcmp() , .CR memmove() , and .CR memset() , respectively. .C ffs() has no portable equivalent. .SH DESCRIPTION These functions operate as efficiently as possible on memory areas (arrays of bytes bounded by a count, not terminated by a null byte). They do not check for the overflow of any receiving memory area. .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RC < string.h > header file. .TP 15 .C memccpy() Copy bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 , stopping after the first occurrence of byte .I c has been copied, or after .I n bytes have been copied, whichever comes first. If copying takes place between objects that overlap, the behavior is undefined. .C memccpy() returns a pointer to the bvyte after the copy of .I c in .IR s1 , or a .SM NULL pointer if .I c was not found in the first .I n bytes of .IR s2 . .TP .C memchr() Locate the first occurrence of .I c (converted to an .CR "unsigned char" ) in the initial .I n bytes (each interpreted as .CR "unsigned char" ) of the object pointed to by .IR s . .C memchr() returns a pointer to the located byte, or a .SM NULL pointer if the byte does not occur in the object. .TP .C memcmp() Compare the first .I n bytes of the object pointed to by .I s1 to the first .I n bytes of the object pointed to by .IR s2 . .C memcmp() returns an integer greater than, equal to, or less than zero, according to whether the object pointed to by .I s1 is greater than, equal to, or less than the object pointed to by .IR s2 . The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes (both interpreted as .CR "unsigned char" ) that differ in the objects being compared. .TP .C memcpy() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . If copying takes place between objects that overlap, the behavior is undefined. .C memcpy() returns the value of .IR s1 . .TP .C memmove() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . Copying takes place as if the .I n bytes from the object pointed to by .I s2 are first copied into a temporary array of .I n bytes that does not overlap the objects pointed to by .I s1 and .IR s2 , and then the .I n bytes from the temporary array are copied into the object pointed to by .IR s1 . .C memmove() returns the value of .IR s1 . .TP .C memset() Copy the value of .I c (converted to an .CR "unsigned char" ) into each of the first .I n bytes of the object pointed to by .IR s . .C memset() returns the value of .IR s . .TP .C bcopy() copies .I n bytes from the area pointed to by .I s1 to the area pointed to by .IR s2 . .TP .C bcmp() Compare the first .I n bytes of the area pointed to by .I s1 with the area pointed to by .IR s2 . .C bcmp() returns zero if they are identical; non-zero otherwise. Both areas are assumed to be .I n bytes in length. .TP .C bzero() Clear .I n bytes in the area pointed to by .I s by setting them to zero. .TP .C ffs() Find the first bit set (beginning with the least significant bit) and return the index of that bit. Bits are numbered starting at one. A return value of 0 indicates that .I i is zero. .SS International Code Set Support These functions support only single-byte byte code sets. .SH WARNINGS The functions defined in .RC < string.h > were previously defined in .RC < memory.h >. .SH FILES .C /usr/include/string.h .SH SEE ALSO string(3C) .SH STANDARDS CONFORMANCE .CR memccpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR memchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memmove() ": AES, SVID3, XPG4, ANSI C" .PP .CR memset() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4memcpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memccpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memchr()\f1 \- find first occurrence of byte in memory area@@@\f3memory(3C)\f1 .\" index@\f4memcmp()\f1 \- compare byte with memory contents@@@\f3memory(3C)\f1 .\" index@\f4memmove()\f1 \- move memory contents@@@\f3memory(3C)\f1 .\" index@\f4memset()\f1 \- set area in memory to contain a specified byte@@@\f3memory(3C)\f1 .\" index@\f4bcopy()\f1 \- \s-1BSD\s+1 memory copy@@@\f3memory(3C)\f1 .\" index@\f4bcmp()\f1 \- \s-1BSD\s+1 memory compare@@@\f3memory(3C)\f1 .\" index@\f4bzero()\f1 \- \s-1BSD\s+1 memory clear@@@\f3memory(3C)\f1 .\" index@\f4ffs()\f1 \- \s-1BSD\s+1 find first set bit@@@\f3memory(3C)\f1 .\" index@\f1memory operations \- copy, compare, test for contents, or set contents to value@@@\f3memory(3C)\f1 .\" index@\f1copy memory to another area@@@\f3memory(3C)\f1 .\" index@\f1test contents of memory area@@@\f3memory(3C)\f1 .\" index@\f1compare contents of memory with byte@@@\f3memory(3C)\f1 .\" index@\f1preset contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1set contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1byte, set contents of memory area to specified@@@\f3memory(3C)\f1 .\" index@\f1byte, compare memory contents with specified@@@\f3memory(3C)\f1 .\" index@\f1byte, find location of in memory@@@\f3memory(3C)\f1 .\" index@\f1location of byte in memory, find@@@\f3memory(3C)\f1 .\" .\" toc@\f3memory(3C)\f1:\0\0\f4memccpy()\f1, \f4memchr()\f1, \f4memcmp()\f1, \f4memcpy()\f1, \f4memset()\f1, \n\f4bcopy()\f1, \f4bcmp()\f1, \f4bzero()\f1, \f4ffs()\f1@@@memory operations .\" toc@\f4memccpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memchr()\f1:\0\0memory operations, locate first character@@@see \f3memory(3C)\f1 .\" toc@\f4memcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memcpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memmove()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memset()\f1:\0\0memory operations, set memory@@@see \f3memory(3C)\f1 .\" toc@\f4bcopy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bzero()\f1:\0\0memory operations, clear bytes@@@see \f3memory(3C)\f1 .\" toc@\f4ffs()\f1:\0\0memory operations, find first bit set@@@see \f3memory(3C)\f1 .\" .\" links@memory.3c memccpy.3c .\" links@memory.3c memchr.3c .\" links@memory.3c memcmp.3c .\" links@memory.3c memcpy.3c .\" links@memory.3c memmove.3c .\" links@memory.3c memset.3c .\" links@memory.3c bcopy.3c .\" links@memory.3c bcmp.3c .\" links@memory.3c bzero.3c .\" links@memory.3c ffs.3c .\" .\" $Header: beep.3x,v 76.2 95/07/31 11:28:52 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH beep 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME beep \(em audible signal .SH SYNOPSIS .C "#include " .P .C "int beep(void);" .SH DESCRIPTION The .Fn beep function alerts the user. It sounds the audible alarm on the terminal, or if that is not possible, it flashes the screen (visible bell). If neither signal is possible, nothing happens. .SH "RETURN VALUE" The .Fn beep function always returns OK. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Nearly all terminals have an audible alarm, but only some can flash the screen. .SH "SEE ALSO" flash(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The argument list is explicitly declared as \f3void\f1. The .B "RETURN VALUE" section is changed to indicate that the function always returns OK. The .Fn flash function is moved to its own entry. .\" .\" index@\f4beep()\f1 \- audible signal@@@\f3beep(3X)\f1 .\" index@\f1audible signal@@@\f3beep(3X)\f1 .\" index@\f1signal, audible@@@\f3beep(3X)\f1 .\" .\" toc@\f3beep(3X)\f1:\0\0\f4beep\f1@@@audible signal .\" .\" fileset_database@beep.3x CURS-ENG-A-MAN .\" $Header: bigcrypt.3c,v 72.2 94/09/15 15:22:02 ssa Exp $ .TA b .TH bigcrypt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bigcrypt \- generate hashing encryption on large strings .SH SYNOPSIS .nf .C "#include " .C "#include " .PP .C "char *bigcrypt(char *key, char *salt);" .PP .SH DESCRIPTION .PP .CR bigcrypt() acts like .CR crypt (3), but handles much larger strings. .CR bigcrypt takes the segments of cleartext and encrypts them individually, at first using the salt passed in, and then using the first two characters of the previous encrypted segment as the salt for the next segment. This avoids duplicated ciphertext chunks when the password characters are repeated, so that the encryption of a segment involves the encryption of all the previous segments. .PP Each chipertext segment is concatenated, with the salt at the beginning, to form the entire encrypted string. .SH AUTHOR .CR bigcrypt was developed by SecureWare Inc. .SH SEE ALSO crypt(3). .\" .\" toc .\" toc@\f3bigcrypt(3C)\f1:\0\0\@@@generate hashing encryption on large strings .\" index@\f1generate hashing encryption on large strings@@@\f3bigcrypt(3C)\f1 .\" index@\f1hashing encryption on large strings, generate@@@\f3bigcrypt(3C)\f1 .\" index@\f1encryption on large strings, generate hashing@@@\f3bigcrypt(3C)\f1 .\" index@\f1large strings, generate hashing encryption on@@@\f3bigcrypt(3C)\f1 .\" .\" $Header: bindresvpor.3n,v 72.6 94/06/29 14:13:17 ssa Exp $ .TA b .TH bindresvport 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bindresvport() \- bind socket to privileged IP port .SH SYNOPSIS .C #include .br .C #include .PP .C "int bindresvport(int sd, struct sockaddr_in *sin);" .SH DESCRIPTION The .CR bindresvport() function binds a socket descriptor to a privileged IP port; that is, a port number in the range 0 to 1023. .PP .I sd is a socket descriptor that was previously defined by a successful call to .CR socket() (see .IR socket (2)). .PP Upon successful completion of .CR bindresvport() , the .I sin_port field in the .CR struct pointed to by .I sin contains the number of the privileged port bound to the .I sd socket. Due to the need to protect the port numbers used by various networking commands, .CR bindresvport() only returns a port number within a smaller subrange in the range of 0 to 1023. .PP Only superuser can bind to a privileged port. .SH RETURN VALUE .CR bindresvport() returns the following values: .RS .TP .PD 0 .CR \00 Successful completion. .TP .CR -1 Failure. .CR errno is set to indicate the error. .PD .SH ERRORS If .CR bindresvport() fails, .CR errno is set to one of the following values: .RS .TP 22 [EACCES] The requested address is protected, and the current user has inadequate permission to access it. .TP [EADDRINUSE] The specified address is already in use. .TP [EADDRNOTAVAIL] The specified address is bad or not available from the local machine. .TP [EAFNOSUPPORT] Requested address does not match the address family of this socket. .TP [EBADF] .I sd is not a valid descriptor. .TP [EINVAL] The socket is already bound to an address, or the socket has been shut down. .TP [ENOBUFS] Insufficient buffer memory is available. .TP [ENOTSOCK] .I sd is not a socket. .TP [EOPNOTSUPP] The socket whose descriptor is .I sd is of a type that does not support address binding. .TP [EPFNOSUPPORT] The value specified in the .I sin_family field of the .I sockaddr_in struct was not .CR AF_INET . .SH AUTHOR .CR bindresvport() was developed by Sun Microsystems, Inc. .SH SEE ALSO bind(2), socket(2). .\" .\" index@\f4bindresvport()\fP \- bind a socket to a privileged IP port@@@\f3bindresvport(3N)\f1 .\" index@bind a socket to a privileged IP port@@@\f3bindresvport(3N)\f1 .\" index@socket, bind to a privileged IP port@@@\f3bindresvport(3N)\f1 .\" index@IP port, bind socket to a privileged@@@\f3bindresvport(3N)\f1 .\" index@privileged IP port, bind socket to a@@@\f3bindresvport(3N)\f1 .\" index@port, IP, bind socket to a privileged@@@\f3bindresvport(3N)\f1 .\" .\" toc@\f3bindresvport(3N)\f1:\0\0\f4bindresvport()\fP@@@bind a socket to a privileged IP port .\" $Header: bkgd.3x,v 76.2 95/07/31 17:03:01 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH bkgd 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bkgd, bkgdset, getbkgd, wbkgd, wbkgdset \(em set or get background character and rendition using a single-byte character .SH SYNOPSIS .C "#include " .P .C "int bkgd(chtype \f2ch\fP);" .P .C "void bkgdset(chtype \f2ch\fP);" .P .C "chtype getbkgd(WINDOW *\f2win\fP);" .P .C "int wbkgd(WINDOW *\f2win\fP, chtype \f2ch\fP);" .P .C "void wbkgdset(WINDOW *\f2win\fP, chtype \f2ch\fP);" .SH DESCRIPTION The .Fn bkgdset and .Fn wbkgdset functions set the background property of the current or specified window based on the information in \f2ch\f1. If \f2ch\f1 refers to a multi-column character, the results are undefined. .P The .Fn bkgd and .Fn wbkgd functions set the background property of the current or specified window and then apply this setting to every character position in that window: .RS .TP 3 .C \(bu The rendition of every character on the screen is changed to the new background rendition. .TP .C \(bu Wherever the former background character appears, it is changed to the new background character. .RE .P The .Fn getbkgd function extracts the specified window's background character and rendition. .SH "RETURN VALUE" Upon successful completion, .Fn bkgd and .Fn wbkgd return OK. Otherwise, they return ERR. .P The .Fn bkgdset and .Fn wbkgdset functions do not return a value. .P Upon successful completion, .Fn getbkgd returns the specified window's background character and rendition. Otherwise, it returns (\f3chtype\fP)ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" \f3Rendition\f1 in curses_intro, . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3bkgd(3X)\f1:\0\0\f4bkgd()\f1, \f4bkgdset()\f1, \f4getbkgd()\f1, \f4wbkgd()\f1, \f4wbkgdset()\f1\n@@@set or get background character and rendition using a single-byte character .\" toc@\f4bkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4bkgdset()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4getbkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4wbkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4wbkgdset()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" .\" index@\f4bkgd()\f1 \- set or get background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1set or get background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1get or set background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1single-byte character, set or get background character or rendition, using@@@\f3bkgd(3X)\f1 .\" .\" links@bkgd.3x bkgdset.3x .\" links@bkgd.3x getbkgd.3x .\" links@bkgd.3x wbkgd.3x .\" links@bkgd.3x wbkgdset.3x .\" .\" fileset_database@bkgd.3x CURS-ENG-A-MAN .\" $Header: bkgd.3x,v 76.2 95/07/31 17:03:01 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH bkgd 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bkgd, bkgdset, getbkgd, wbkgd, wbkgdset \(em set or get background character and rendition using a single-byte character .SH SYNOPSIS .C "#include " .P .C "int bkgd(chtype \f2ch\fP);" .P .C "void bkgdset(chtype \f2ch\fP);" .P .C "chtype getbkgd(WINDOW *\f2win\fP);" .P .C "int wbkgd(WINDOW *\f2win\fP, chtype \f2ch\fP);" .P .C "void wbkgdset(WINDOW *\f2win\fP, chtype \f2ch\fP);" .SH DESCRIPTION The .Fn bkgdset and .Fn wbkgdset functions set the background property of the current or specified window based on the information in \f2ch\f1. If \f2ch\f1 refers to a multi-column character, the results are undefined. .P The .Fn bkgd and .Fn wbkgd functions set the background property of the current or specified window and then apply this setting to every character position in that window: .RS .TP 3 .C \(bu The rendition of every character on the screen is changed to the new background rendition. .TP .C \(bu Wherever the former background character appears, it is changed to the new background character. .RE .P The .Fn getbkgd function extracts the specified window's background character and rendition. .SH "RETURN VALUE" Upon successful completion, .Fn bkgd and .Fn wbkgd return OK. Otherwise, they return ERR. .P The .Fn bkgdset and .Fn wbkgdset functions do not return a value. .P Upon successful completion, .Fn getbkgd returns the specified window's background character and rendition. Otherwise, it returns (\f3chtype\fP)ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" \f3Rendition\f1 in curses_intro, . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3bkgd(3X)\f1:\0\0\f4bkgd()\f1, \f4bkgdset()\f1, \f4getbkgd()\f1, \f4wbkgd()\f1, \f4wbkgdset()\f1\n@@@set or get background character and rendition using a single-byte character .\" toc@\f4bkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4bkgdset()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4getbkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4wbkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4wbkgdset()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" .\" index@\f4bkgd()\f1 \- set or get background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1set or get background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1get or set background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1single-byte character, set or get background character or rendition, using@@@\f3bkgd(3X)\f1 .\" .\" links@bkgd.3x bkgdset.3x .\" links@bkgd.3x getbkgd.3x .\" links@bkgd.3x wbkgd.3x .\" links@bkgd.3x wbkgdset.3x .\" .\" fileset_database@bkgd.3x CURS-ENG-A-MAN .\" $Header: bkgrnd.3x,v 76.2 95/07/31 17:05:26 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH bkgrnd 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bkgrnd, bkgrndset, getbkgrnd, wbkgrnd, wbkgrndset, wgetbkgrnd \(em set or get background character and rendition using a complex character .SH SYNOPSIS .C "#include " .P .C "int bkgrnd(cchar_t *const \f2wch\fP);" .P .C "void bkgrndset(cchar_t *const \f2wch\fP);" .P .C "int getbkgrnd(cchar_t *\f2wch\fP);" .P .C "int wbkgrnd(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "void wbkgrndset(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "int wgetbkgrnd(WINDOW *\f2win\fP, cchar_t *\f2wch\fP);" .SH DESCRIPTION The .Fn bkgrndset and .Fn wbkgrndset functions set the background property of the current or specified window based on the information in \f2wch\f1. .P The .Fn bkgrnd and .Fn wbkgrnd functions set the background property of the current or specified window and then apply this setting to every character position in that window: .RS .TP 3 .C \(bu The rendition of every character on the screen is changed to the new background rendition. .TP .C \(bu Wherever the former background character appears, it is changed to the new background character. .RE .P If \f2wch\f1 refers to a non-spacing complex character for .CR bkgrnd() , .CR bkgrndset() , .Fn wbkgrnd and .CR wbkgrndset() , then \f2wch\f1 is added to the existing spacing complex character that is the background character. If \f2wch\f1 refers to a multi-column character, the results are unspecified. .P The .Fn getbkgrnd and .Fn wgetbkgrnd functions store, into the area pointed to by \f2wch\fP, the value of the window's background character and rendition. .SH "RETURN VALUE" The .Fn bkgrndset and .Fn wbkgrndset functions do not return a value. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Rendition\f1 in curses_intro, .Hd curses.h .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3bkgrnd(3X)\f1:\0\0\f4bkgrnd()\f1, \f4bkgrndset()\f1, \f4getbkgrnd()\f1, \f4wbkgrnd()\f1, \f4wbkgrndset()\f1, \f4wgetbkgrnd()\f1\n@@@set or get background character and rendition using a complex character .\" toc@\f4bkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4bkgrndset()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4getbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wbkgrndset()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wgetbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" index@\f1set or get background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1get or set background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1complex character, set or get background character and rendition using@@@\f3bkgrnd(3X)\f1 .\" index@\f4bkgrnd()\f1 \- set or get background character and rendition using omplex character@@@\f3bkgrnd(3X)\f1 .\" .\" links@bkgrnd.3x bkgrndset.3x .\" links@bkgrnd.3x getbkgrnd.3x .\" links@bkgrnd.3x wbkgrnd.3x .\" links@bkgrnd.3x wbkgrndset.3x .\" links@bkgrnd.3x wgetbkgrnd.3x .\" .\" fileset_database@bkgrnd.3x CURS-ENG-A-MAN .\" $Header: bkgrnd.3x,v 76.2 95/07/31 17:05:26 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH bkgrnd 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bkgrnd, bkgrndset, getbkgrnd, wbkgrnd, wbkgrndset, wgetbkgrnd \(em set or get background character and rendition using a complex character .SH SYNOPSIS .C "#include " .P .C "int bkgrnd(cchar_t *const \f2wch\fP);" .P .C "void bkgrndset(cchar_t *const \f2wch\fP);" .P .C "int getbkgrnd(cchar_t *\f2wch\fP);" .P .C "int wbkgrnd(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "void wbkgrndset(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "int wgetbkgrnd(WINDOW *\f2win\fP, cchar_t *\f2wch\fP);" .SH DESCRIPTION The .Fn bkgrndset and .Fn wbkgrndset functions set the background property of the current or specified window based on the information in \f2wch\f1. .P The .Fn bkgrnd and .Fn wbkgrnd functions set the background property of the current or specified window and then apply this setting to every character position in that window: .RS .TP 3 .C \(bu The rendition of every character on the screen is changed to the new background rendition. .TP .C \(bu Wherever the former background character appears, it is changed to the new background character. .RE .P If \f2wch\f1 refers to a non-spacing complex character for .CR bkgrnd() , .CR bkgrndset() , .Fn wbkgrnd and .CR wbkgrndset() , then \f2wch\f1 is added to the existing spacing complex character that is the background character. If \f2wch\f1 refers to a multi-column character, the results are unspecified. .P The .Fn getbkgrnd and .Fn wgetbkgrnd functions store, into the area pointed to by \f2wch\fP, the value of the window's background character and rendition. .SH "RETURN VALUE" The .Fn bkgrndset and .Fn wbkgrndset functions do not return a value. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Rendition\f1 in curses_intro, .Hd curses.h .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3bkgrnd(3X)\f1:\0\0\f4bkgrnd()\f1, \f4bkgrndset()\f1, \f4getbkgrnd()\f1, \f4wbkgrnd()\f1, \f4wbkgrndset()\f1, \f4wgetbkgrnd()\f1\n@@@set or get background character and rendition using a complex character .\" toc@\f4bkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4bkgrndset()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4getbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wbkgrndset()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wgetbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" index@\f1set or get background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1get or set background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1complex character, set or get background character and rendition using@@@\f3bkgrnd(3X)\f1 .\" index@\f4bkgrnd()\f1 \- set or get background character and rendition using omplex character@@@\f3bkgrnd(3X)\f1 .\" .\" links@bkgrnd.3x bkgrndset.3x .\" links@bkgrnd.3x getbkgrnd.3x .\" links@bkgrnd.3x wbkgrnd.3x .\" links@bkgrnd.3x wbkgrndset.3x .\" links@bkgrnd.3x wgetbkgrnd.3x .\" .\" fileset_database@bkgrnd.3x CURS-ENG-A-MAN .\" $Header: blmode.3c,v 74.1 95/03/23 17:44:35 ssa Exp $ .TA b .TH blmode 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not implemented on 700 .SH NAME blopen(\|), blclose(\|), blread(\|), blget(\|), blset(\|) \- terminal block-mode library interface .SH SYNOPSIS .C "#include " .PP .C "int blopen(int fildes);" .PP .C "int blclose(int bfdes);" .PP .C "int blread(int bfdes, char *buf, size_t nbyte);" .PP .C "int blget(int bfdes, struct blmodeio *arg);" .PP .C "int blset(int bfdes, const struct blmodeio *arg);" .SH DESCRIPTION .PP This terminal library interface allows support of block-mode transfers with .SM HP terminals. Block mode only affects input processing. Therefore, data is written with the standard .C write() interface (see .IR write (2)). .PP In character mode, the terminal sends each character to the system as it is typed. However, in block mode, data is buffered and possibly edited locally in the terminal memory as it is typed, then sent as a block of data when the .B [Enter] key is pressed on the terminal. During block-mode data transmissions, the incoming data is not echoed by the interface and no special character processing is performed, other than recognizing a data block terminator character. For subsequent character mode transmissions, the existing termio state (see .IR termio (7)) continues to determine echo and character processing. .PP Block-mode protocol has two component parts: block-mode handshake and block-mode transmission. .SS Block-Mode Handshake At the beginning of a read, a .I trigger character is sent to the terminal to notify it that the system wants a block of data (the .I trigger character, if defined, is sent at the beginning of all reads, whether in character- or block-mode. It is necessary for block-mode reads to work correctly). .PP After receiving the .I trigger character, and when the user has typed all the data into the terminal's memory and pressed the .B [Enter] key, the terminal sends an .I alert character to the system to notify it that the terminal has a block of data to send. .PP The system might then send user-definable cursor-positioning or other data sequences to the terminal, such as for cursor-home or lock-keyboard. .PP The system then sends a second .I trigger character to the terminal. In response, the terminal transmits the data block as described in the Block-Mode Transmission section. .SS Block-Mode Transmission The second part of the block-mode protocol is the block-mode transmission. After the block-mode handshake has successfully completed, the terminal transmits the data block to the system. During this transmission of data, the incoming data is not echoed by the system and no special character processing is performed, other than recognizing the data block termination character. It is possible to bypass the block-mode handshake and have the block-mode transmission occur after only the first .I trigger character is sent, see .C CB_BMTRANS below. .PP It is possible to intermix both character-mode and block-mode data transmissions. If .C CB_BMTRANS (see below) is set, all transfers are block-mode transfers. When .C CB_BMTRANS is not set, character mode transmissions are processed as described in .IR termio (7). In this case, if an .I alert character is received anywhere in the input data, the transmission mode is automatically switched to block mode for a single transmission. Any data received before the .I alert is discarded. The .I alert character can be escaped with a backslash .RC ( \e ) character. .SS \s-1XON/XOFF\s0 Flow Control To prevent data loss, .SM XON/XOFF flow control should be used between the system and the terminal. The .SM IXOFF bit (see .IR termio (7)) should be set and the terminal strapped appropriately. If flow control is not used, it is possible for incoming data to overflow and be lost. (Note: some older terminals do not support .SM XON/XOFF flow control.) .SS Read Requests Read requests that receive data from block-mode transmissions do not return until the transmission is complete (the terminal has transmitted all characters). If the read is satisfied by byte count or if a data transmission error occurs, all subsequent data is discarded until the transmission is complete. The read waits until a terminator character is seen, or until a time interval specified by the system has passed that is longer than necessary for the number of characters specified. .PP The data-block-terminator character is included in the data returned to the user, and is included in the byte count. If the number of bytes transferred by the terminal in a block-mode transfer exceeds the number of bytes requested by the user, the read returns the requested number of bytes and the remaining bytes are discarded. The user can determine if data was discarded by checking the last character of the returned data. If the last character is not the terminator character, then more data was received than was requested and data was discarded. .PP The .SM EIO error can be caused by several events, including errors in transmission, framing, parity, break, and overrun, or if the internal timer expires. The internal timer starts when the second trigger character is sent by the computer, and ends when the terminating character is received by the computer. The length of this timer is determined by the number of bytes requested in the read and the current baud rate, plus an additional ten seconds. .SS User Control of Handshaking If desired, the application program can provide its own handshake mechanism in response to the .I alert character by selecting the .C OWNTERM mode (see .C CB_OWNTERM below). With this mode selected, the driver completes a read request when the .I alert character is received. No data is discarded before the .IR alert , and the .I alert is returned in the data read. The .I alert character may be escaped with a backslash .RC ( \e ) character. The second .I trigger is sent when the application issues the next read. .SS blmode Control Calls First, the standard .C open() call to a tty device must be made to obtain a file descriptor for the subsequent block-mode control calls (an .C open() is done automatically by the system for .C stdin on the terminal). .RS .TP .C int bfdes; .TP .C bfdes = blopen (int fildes) A call to .C blopen() must be made before any block-mode access is allowed on the specified file descriptor. .C blopen() initializes the block-mode parameters as described below. The return value from .C blopen() is a block-mode file descriptor that must be passed to all subsequent block-mode control calls. .TP .C int blclose (int bfdes) A call to .C blclose() must be issued before the standard .C close() to ensure proper closure of the device (see .IR close (2)). Otherwise unpredictable results can occur. The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blread (int bfdes, char *buf, size_t nbyte)" The .C blread() routine has the same parameters as the .C read() sytem call (see .IR read (2)). At the beginning of a read, the .C cb_trig1c character (if defined) is sent to the device. If .C CB_BMTRANS is not set, and no .C cb_alertc character is received, the read data is processed according to .IR termio (7). If .C CB_BMTRANS is set, or if a non-escaped .C cb_alertc character is received, echo is turned off for the duration of the transfer, and no further special character processing is done other than that required for the termination character. The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blget (int bfdes, struct blmodeio *arg)" A call to .C blget() returns the current values of the .C blmodeio structure (see below). The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blset (int bfdes, const struct blmodeio *arg)" A call to .C blset() sets the block-mode values from the structure whose address is .IR arg . The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .RE .SS blmode Structure The two block-mode control calls, .C blget() and .CR blset() , use the following structure, defined in .RC < sys/blmodeio.h >: .nf .IP .C "#define NBREPLY 64" .C "struct blmodeio {" .C " unsigned long cb_flags; /* Modes */" .C " unsigned char cb_trig1c; /* First trigger */" .C " unsigned char cb_trig2c; /* Second trigger */" .C " unsigned char cb_alertc; /* Alert character */" .C " unsigned char cb_termc; /* Terminating char */" .C " unsigned char cb_replen; /* cb_reply length */" .C " char cb_reply[NBREPLY]; /* optional reply */" .C }; .fi .PP The .C cb_flags field controls the basic block-mode protocol: .nf .IP .CR "CB_BMTRANS 0000001 " "Enable mandatory block-mode transmission." .CR "CB_OWNTERM 0000002 " "Enable user control of handshake." .fi .PP If .C CB_BMTRANS is set, all transmissions are processed as block-mode transmissions. The block-mode handshake is not required and data read is processed as block-mode transfer data. The block-mode handshake can still be invoked by receipt of an .I alert character as the first character seen. A .C blread() issued with the .C CB_BMTRANS bit set causes any existing input buffer data to be flushed. .PP If .C CB_BMTRANS is not set, and if the .I alert character is defined and is detected anywhere in the input stream, the input buffer is flushed and the block-mode handshake is invoked. The system then sends the .C cb_trig2c character to the terminal, and a block-mode transfer follows. The .I alert character can be escaped by preceding it with a backslash .RC ( \e ). .PP If .C CB_OWNTERM is set, reads are terminated upon receipt of a non-escaped .I alert character. No input buffer flushing is performed, and the .I alert character is returned in the data read. This allows application code to perform its own block-mode handshaking. If the bit is clear, a non-escaped .I alert character causes normal block-mode handshaking to be used. .PP The initial .C cb_flags value is all-bits-cleared. .RE .PP There are several special characters (both input and output) that are used with block mode. These characters and the initial values for these characters are described below. Any of these characters can be undefined by setting its value to 0377. .TP 15 .C cb_trig1c (default .SM DC1\c ) is the initial .I trigger character sent to the terminal at the beginning of a read request. .TP .C cb_trig2c (default .SM DC1\c ) is the secondary .I trigger character sent to the terminal after the .I alert character has been seen. .TP .C cb_alertc (default .SM DC2\c ) is the .I alert character sent by the terminal in response to the first .I trigger character. It signifies that the terminal is ready to send the data block. The .I alert character can be escaped by preceding it with a backslash ("\\"). .TP .C cb_termc (default .SM RS\c ) is sent by the terminal after the block-mode transfer has completed. It signifies the end of the data block to the computer. .PP The .C cb_replen field specifies the length in bytes of the .C cb_reply field. If set to zero, the .C cb_reply string is not used. The .C cb_replen field is initially set to zero. .PP The .C cb_reply array contains a string to be sent out after receipt of the .I alert character, but before the second .I trigger character is sent by the computer. Any character can be included in the reply string. The number of characters sent is specified by .CR cb_replen . The initial value of all characters in the .C cb_reply array is .SM NULL. .RE .SH RETURNS If an error occurs, all calls return a value of \(mi1 and .C errno is set to indicate the error. If no error is detected, .C blread() returns the number of characters read. All other calls return 0 upon successful completion. .PP During a read, it is possible for the user's buffer to be altered, even if an error value is returned. The data in the user's buffer should be ignored as it is not complete. The following errors can be returned by the library calls indicated: .SS blopen() .RS .TP 15 .SM [ENOTTY] The file descriptor specified is not related to a terminal device. .RE .SS blclose() .RS .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blread() .RS .TP 15 .SM [EDEADLK] A resource deadlock would occur as a result of this operation (see .IR lockf (2)). .PP .TP 15 .SM [EFAULT] .C buf points outside the allocated address space. The reliable detection of this error is implementation dependent. .TP 15 .SM [EINTR] A signal was caught during the .C read system call. .PP .TP 15 .SM [EIO] An I/O error occured during block-mode data transmissions. .PP .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blget() .RS .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blset() .RS .TP 15 .SM [EINVAL] An illegal value was specified in the structure passed to the system. .PP .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .SH WARNINGS Once .C blopen has been called with a file descriptor and returned successfully, that file descriptor should not subsequently be used as a parameter to the following system calls: .CR close() , .CR dup() , .CR dup2() , .CR fcntl() , .CR ioctl() , .CR read() , or .CR select() until a .C blclose is called with the same file descriptor as its parameter. Additionally, .CR scanf() , .CR fscanf() , .CR getc() , .CR getchar() , .CR fgetc() , and .C fgetw() should not be called for a stream associated with a file descriptor that has been used in a .C blopen() call but has not been used in a .C blclose() call. These functions call .CR read() , and calling these routines results in unpredictable behavior. .SH AUTHOR .CR blopen() , .CR blclose() , .CR blread() , .CR blget() , and .CR blset() were developed by HP. .SH SEE ALSO termio(7). .\" index@\f4blmode()\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blopen(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blclose(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blread(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blget(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blset(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@block-mode terminal \s-1I/O\s+1 library interface@@@\f3blmode(3C)\f1 .\" index@terminal \s-1I/O\s+1, block-mode library interface for@@@\f3blmode(3C)\f1 .\" index@terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" .\" toc@\f3blmode(3C)\f1:\0\0\f4blmode()\fP@@@terminal block-mode library interface .\" toc@\f4blopen(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blclose(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blread(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blget(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blset(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" .\" links@blmode.3c blopen.3c .\" links@blmode.3c blclose.3c .\" links@blmode.3c blread.3c .\" links@blmode.3c blget.3c .\" links@blmode.3c blset.3c .\" $Header: blmode.3c,v 74.1 95/03/23 17:44:35 ssa Exp $ .TA b .TH blmode 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not implemented on 700 .SH NAME blopen(\|), blclose(\|), blread(\|), blget(\|), blset(\|) \- terminal block-mode library interface .SH SYNOPSIS .C "#include " .PP .C "int blopen(int fildes);" .PP .C "int blclose(int bfdes);" .PP .C "int blread(int bfdes, char *buf, size_t nbyte);" .PP .C "int blget(int bfdes, struct blmodeio *arg);" .PP .C "int blset(int bfdes, const struct blmodeio *arg);" .SH DESCRIPTION .PP This terminal library interface allows support of block-mode transfers with .SM HP terminals. Block mode only affects input processing. Therefore, data is written with the standard .C write() interface (see .IR write (2)). .PP In character mode, the terminal sends each character to the system as it is typed. However, in block mode, data is buffered and possibly edited locally in the terminal memory as it is typed, then sent as a block of data when the .B [Enter] key is pressed on the terminal. During block-mode data transmissions, the incoming data is not echoed by the interface and no special character processing is performed, other than recognizing a data block terminator character. For subsequent character mode transmissions, the existing termio state (see .IR termio (7)) continues to determine echo and character processing. .PP Block-mode protocol has two component parts: block-mode handshake and block-mode transmission. .SS Block-Mode Handshake At the beginning of a read, a .I trigger character is sent to the terminal to notify it that the system wants a block of data (the .I trigger character, if defined, is sent at the beginning of all reads, whether in character- or block-mode. It is necessary for block-mode reads to work correctly). .PP After receiving the .I trigger character, and when the user has typed all the data into the terminal's memory and pressed the .B [Enter] key, the terminal sends an .I alert character to the system to notify it that the terminal has a block of data to send. .PP The system might then send user-definable cursor-positioning or other data sequences to the terminal, such as for cursor-home or lock-keyboard. .PP The system then sends a second .I trigger character to the terminal. In response, the terminal transmits the data block as described in the Block-Mode Transmission section. .SS Block-Mode Transmission The second part of the block-mode protocol is the block-mode transmission. After the block-mode handshake has successfully completed, the terminal transmits the data block to the system. During this transmission of data, the incoming data is not echoed by the system and no special character processing is performed, other than recognizing the data block termination character. It is possible to bypass the block-mode handshake and have the block-mode transmission occur after only the first .I trigger character is sent, see .C CB_BMTRANS below. .PP It is possible to intermix both character-mode and block-mode data transmissions. If .C CB_BMTRANS (see below) is set, all transfers are block-mode transfers. When .C CB_BMTRANS is not set, character mode transmissions are processed as described in .IR termio (7). In this case, if an .I alert character is received anywhere in the input data, the transmission mode is automatically switched to block mode for a single transmission. Any data received before the .I alert is discarded. The .I alert character can be escaped with a backslash .RC ( \e ) character. .SS \s-1XON/XOFF\s0 Flow Control To prevent data loss, .SM XON/XOFF flow control should be used between the system and the terminal. The .SM IXOFF bit (see .IR termio (7)) should be set and the terminal strapped appropriately. If flow control is not used, it is possible for incoming data to overflow and be lost. (Note: some older terminals do not support .SM XON/XOFF flow control.) .SS Read Requests Read requests that receive data from block-mode transmissions do not return until the transmission is complete (the terminal has transmitted all characters). If the read is satisfied by byte count or if a data transmission error occurs, all subsequent data is discarded until the transmission is complete. The read waits until a terminator character is seen, or until a time interval specified by the system has passed that is longer than necessary for the number of characters specified. .PP The data-block-terminator character is included in the data returned to the user, and is included in the byte count. If the number of bytes transferred by the terminal in a block-mode transfer exceeds the number of bytes requested by the user, the read returns the requested number of bytes and the remaining bytes are discarded. The user can determine if data was discarded by checking the last character of the returned data. If the last character is not the terminator character, then more data was received than was requested and data was discarded. .PP The .SM EIO error can be caused by several events, including errors in transmission, framing, parity, break, and overrun, or if the internal timer expires. The internal timer starts when the second trigger character is sent by the computer, and ends when the terminating character is received by the computer. The length of this timer is determined by the number of bytes requested in the read and the current baud rate, plus an additional ten seconds. .SS User Control of Handshaking If desired, the application program can provide its own handshake mechanism in response to the .I alert character by selecting the .C OWNTERM mode (see .C CB_OWNTERM below). With this mode selected, the driver completes a read request when the .I alert character is received. No data is discarded before the .IR alert , and the .I alert is returned in the data read. The .I alert character may be escaped with a backslash .RC ( \e ) character. The second .I trigger is sent when the application issues the next read. .SS blmode Control Calls First, the standard .C open() call to a tty device must be made to obtain a file descriptor for the subsequent block-mode control calls (an .C open() is done automatically by the system for .C stdin on the terminal). .RS .TP .C int bfdes; .TP .C bfdes = blopen (int fildes) A call to .C blopen() must be made before any block-mode access is allowed on the specified file descriptor. .C blopen() initializes the block-mode parameters as described below. The return value from .C blopen() is a block-mode file descriptor that must be passed to all subsequent block-mode control calls. .TP .C int blclose (int bfdes) A call to .C blclose() must be issued before the standard .C close() to ensure proper closure of the device (see .IR close (2)). Otherwise unpredictable results can occur. The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blread (int bfdes, char *buf, size_t nbyte)" The .C blread() routine has the same parameters as the .C read() sytem call (see .IR read (2)). At the beginning of a read, the .C cb_trig1c character (if defined) is sent to the device. If .C CB_BMTRANS is not set, and no .C cb_alertc character is received, the read data is processed according to .IR termio (7). If .C CB_BMTRANS is set, or if a non-escaped .C cb_alertc character is received, echo is turned off for the duration of the transfer, and no further special character processing is done other than that required for the termination character. The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blget (int bfdes, struct blmodeio *arg)" A call to .C blget() returns the current values of the .C blmodeio structure (see below). The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blset (int bfdes, const struct blmodeio *arg)" A call to .C blset() sets the block-mode values from the structure whose address is .IR arg . The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .RE .SS blmode Structure The two block-mode control calls, .C blget() and .CR blset() , use the following structure, defined in .RC < sys/blmodeio.h >: .nf .IP .C "#define NBREPLY 64" .C "struct blmodeio {" .C " unsigned long cb_flags; /* Modes */" .C " unsigned char cb_trig1c; /* First trigger */" .C " unsigned char cb_trig2c; /* Second trigger */" .C " unsigned char cb_alertc; /* Alert character */" .C " unsigned char cb_termc; /* Terminating char */" .C " unsigned char cb_replen; /* cb_reply length */" .C " char cb_reply[NBREPLY]; /* optional reply */" .C }; .fi .PP The .C cb_flags field controls the basic block-mode protocol: .nf .IP .CR "CB_BMTRANS 0000001 " "Enable mandatory block-mode transmission." .CR "CB_OWNTERM 0000002 " "Enable user control of handshake." .fi .PP If .C CB_BMTRANS is set, all transmissions are processed as block-mode transmissions. The block-mode handshake is not required and data read is processed as block-mode transfer data. The block-mode handshake can still be invoked by receipt of an .I alert character as the first character seen. A .C blread() issued with the .C CB_BMTRANS bit set causes any existing input buffer data to be flushed. .PP If .C CB_BMTRANS is not set, and if the .I alert character is defined and is detected anywhere in the input stream, the input buffer is flushed and the block-mode handshake is invoked. The system then sends the .C cb_trig2c character to the terminal, and a block-mode transfer follows. The .I alert character can be escaped by preceding it with a backslash .RC ( \e ). .PP If .C CB_OWNTERM is set, reads are terminated upon receipt of a non-escaped .I alert character. No input buffer flushing is performed, and the .I alert character is returned in the data read. This allows application code to perform its own block-mode handshaking. If the bit is clear, a non-escaped .I alert character causes normal block-mode handshaking to be used. .PP The initial .C cb_flags value is all-bits-cleared. .RE .PP There are several special characters (both input and output) that are used with block mode. These characters and the initial values for these characters are described below. Any of these characters can be undefined by setting its value to 0377. .TP 15 .C cb_trig1c (default .SM DC1\c ) is the initial .I trigger character sent to the terminal at the beginning of a read request. .TP .C cb_trig2c (default .SM DC1\c ) is the secondary .I trigger character sent to the terminal after the .I alert character has been seen. .TP .C cb_alertc (default .SM DC2\c ) is the .I alert character sent by the terminal in response to the first .I trigger character. It signifies that the terminal is ready to send the data block. The .I alert character can be escaped by preceding it with a backslash ("\\"). .TP .C cb_termc (default .SM RS\c ) is sent by the terminal after the block-mode transfer has completed. It signifies the end of the data block to the computer. .PP The .C cb_replen field specifies the length in bytes of the .C cb_reply field. If set to zero, the .C cb_reply string is not used. The .C cb_replen field is initially set to zero. .PP The .C cb_reply array contains a string to be sent out after receipt of the .I alert character, but before the second .I trigger character is sent by the computer. Any character can be included in the reply string. The number of characters sent is specified by .CR cb_replen . The initial value of all characters in the .C cb_reply array is .SM NULL. .RE .SH RETURNS If an error occurs, all calls return a value of \(mi1 and .C errno is set to indicate the error. If no error is detected, .C blread() returns the number of characters read. All other calls return 0 upon successful completion. .PP During a read, it is possible for the user's buffer to be altered, even if an error value is returned. The data in the user's buffer should be ignored as it is not complete. The following errors can be returned by the library calls indicated: .SS blopen() .RS .TP 15 .SM [ENOTTY] The file descriptor specified is not related to a terminal device. .RE .SS blclose() .RS .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blread() .RS .TP 15 .SM [EDEADLK] A resource deadlock would occur as a result of this operation (see .IR lockf (2)). .PP .TP 15 .SM [EFAULT] .C buf points outside the allocated address space. The reliable detection of this error is implementation dependent. .TP 15 .SM [EINTR] A signal was caught during the .C read system call. .PP .TP 15 .SM [EIO] An I/O error occured during block-mode data transmissions. .PP .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blget() .RS .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blset() .RS .TP 15 .SM [EINVAL] An illegal value was specified in the structure passed to the system. .PP .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .SH WARNINGS Once .C blopen has been called with a file descriptor and returned successfully, that file descriptor should not subsequently be used as a parameter to the following system calls: .CR close() , .CR dup() , .CR dup2() , .CR fcntl() , .CR ioctl() , .CR read() , or .CR select() until a .C blclose is called with the same file descriptor as its parameter. Additionally, .CR scanf() , .CR fscanf() , .CR getc() , .CR getchar() , .CR fgetc() , and .C fgetw() should not be called for a stream associated with a file descriptor that has been used in a .C blopen() call but has not been used in a .C blclose() call. These functions call .CR read() , and calling these routines results in unpredictable behavior. .SH AUTHOR .CR blopen() , .CR blclose() , .CR blread() , .CR blget() , and .CR blset() were developed by HP. .SH SEE ALSO termio(7). .\" index@\f4blmode()\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blopen(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blclose(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blread(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blget(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blset(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@block-mode terminal \s-1I/O\s+1 library interface@@@\f3blmode(3C)\f1 .\" index@terminal \s-1I/O\s+1, block-mode library interface for@@@\f3blmode(3C)\f1 .\" index@terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" .\" toc@\f3blmode(3C)\f1:\0\0\f4blmode()\fP@@@terminal block-mode library interface .\" toc@\f4blopen(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blclose(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blread(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blget(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blset(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" .\" links@blmode.3c blopen.3c .\" links@blmode.3c blclose.3c .\" links@blmode.3c blread.3c .\" links@blmode.3c blget.3c .\" links@blmode.3c blset.3c .\" $Header: blmode.3c,v 74.1 95/03/23 17:44:35 ssa Exp $ .TA b .TH blmode 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not implemented on 700 .SH NAME blopen(\|), blclose(\|), blread(\|), blget(\|), blset(\|) \- terminal block-mode library interface .SH SYNOPSIS .C "#include " .PP .C "int blopen(int fildes);" .PP .C "int blclose(int bfdes);" .PP .C "int blread(int bfdes, char *buf, size_t nbyte);" .PP .C "int blget(int bfdes, struct blmodeio *arg);" .PP .C "int blset(int bfdes, const struct blmodeio *arg);" .SH DESCRIPTION .PP This terminal library interface allows support of block-mode transfers with .SM HP terminals. Block mode only affects input processing. Therefore, data is written with the standard .C write() interface (see .IR write (2)). .PP In character mode, the terminal sends each character to the system as it is typed. However, in block mode, data is buffered and possibly edited locally in the terminal memory as it is typed, then sent as a block of data when the .B [Enter] key is pressed on the terminal. During block-mode data transmissions, the incoming data is not echoed by the interface and no special character processing is performed, other than recognizing a data block terminator character. For subsequent character mode transmissions, the existing termio state (see .IR termio (7)) continues to determine echo and character processing. .PP Block-mode protocol has two component parts: block-mode handshake and block-mode transmission. .SS Block-Mode Handshake At the beginning of a read, a .I trigger character is sent to the terminal to notify it that the system wants a block of data (the .I trigger character, if defined, is sent at the beginning of all reads, whether in character- or block-mode. It is necessary for block-mode reads to work correctly). .PP After receiving the .I trigger character, and when the user has typed all the data into the terminal's memory and pressed the .B [Enter] key, the terminal sends an .I alert character to the system to notify it that the terminal has a block of data to send. .PP The system might then send user-definable cursor-positioning or other data sequences to the terminal, such as for cursor-home or lock-keyboard. .PP The system then sends a second .I trigger character to the terminal. In response, the terminal transmits the data block as described in the Block-Mode Transmission section. .SS Block-Mode Transmission The second part of the block-mode protocol is the block-mode transmission. After the block-mode handshake has successfully completed, the terminal transmits the data block to the system. During this transmission of data, the incoming data is not echoed by the system and no special character processing is performed, other than recognizing the data block termination character. It is possible to bypass the block-mode handshake and have the block-mode transmission occur after only the first .I trigger character is sent, see .C CB_BMTRANS below. .PP It is possible to intermix both character-mode and block-mode data transmissions. If .C CB_BMTRANS (see below) is set, all transfers are block-mode transfers. When .C CB_BMTRANS is not set, character mode transmissions are processed as described in .IR termio (7). In this case, if an .I alert character is received anywhere in the input data, the transmission mode is automatically switched to block mode for a single transmission. Any data received before the .I alert is discarded. The .I alert character can be escaped with a backslash .RC ( \e ) character. .SS \s-1XON/XOFF\s0 Flow Control To prevent data loss, .SM XON/XOFF flow control should be used between the system and the terminal. The .SM IXOFF bit (see .IR termio (7)) should be set and the terminal strapped appropriately. If flow control is not used, it is possible for incoming data to overflow and be lost. (Note: some older terminals do not support .SM XON/XOFF flow control.) .SS Read Requests Read requests that receive data from block-mode transmissions do not return until the transmission is complete (the terminal has transmitted all characters). If the read is satisfied by byte count or if a data transmission error occurs, all subsequent data is discarded until the transmission is complete. The read waits until a terminator character is seen, or until a time interval specified by the system has passed that is longer than necessary for the number of characters specified. .PP The data-block-terminator character is included in the data returned to the user, and is included in the byte count. If the number of bytes transferred by the terminal in a block-mode transfer exceeds the number of bytes requested by the user, the read returns the requested number of bytes and the remaining bytes are discarded. The user can determine if data was discarded by checking the last character of the returned data. If the last character is not the terminator character, then more data was received than was requested and data was discarded. .PP The .SM EIO error can be caused by several events, including errors in transmission, framing, parity, break, and overrun, or if the internal timer expires. The internal timer starts when the second trigger character is sent by the computer, and ends when the terminating character is received by the computer. The length of this timer is determined by the number of bytes requested in the read and the current baud rate, plus an additional ten seconds. .SS User Control of Handshaking If desired, the application program can provide its own handshake mechanism in response to the .I alert character by selecting the .C OWNTERM mode (see .C CB_OWNTERM below). With this mode selected, the driver completes a read request when the .I alert character is received. No data is discarded before the .IR alert , and the .I alert is returned in the data read. The .I alert character may be escaped with a backslash .RC ( \e ) character. The second .I trigger is sent when the application issues the next read. .SS blmode Control Calls First, the standard .C open() call to a tty device must be made to obtain a file descriptor for the subsequent block-mode control calls (an .C open() is done automatically by the system for .C stdin on the terminal). .RS .TP .C int bfdes; .TP .C bfdes = blopen (int fildes) A call to .C blopen() must be made before any block-mode access is allowed on the specified file descriptor. .C blopen() initializes the block-mode parameters as described below. The return value from .C blopen() is a block-mode file descriptor that must be passed to all subsequent block-mode control calls. .TP .C int blclose (int bfdes) A call to .C blclose() must be issued before the standard .C close() to ensure proper closure of the device (see .IR close (2)). Otherwise unpredictable results can occur. The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blread (int bfdes, char *buf, size_t nbyte)" The .C blread() routine has the same parameters as the .C read() sytem call (see .IR read (2)). At the beginning of a read, the .C cb_trig1c character (if defined) is sent to the device. If .C CB_BMTRANS is not set, and no .C cb_alertc character is received, the read data is processed according to .IR termio (7). If .C CB_BMTRANS is set, or if a non-escaped .C cb_alertc character is received, echo is turned off for the duration of the transfer, and no further special character processing is done other than that required for the termination character. The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blget (int bfdes, struct blmodeio *arg)" A call to .C blget() returns the current values of the .C blmodeio structure (see below). The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blset (int bfdes, const struct blmodeio *arg)" A call to .C blset() sets the block-mode values from the structure whose address is .IR arg . The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .RE .SS blmode Structure The two block-mode control calls, .C blget() and .CR blset() , use the following structure, defined in .RC < sys/blmodeio.h >: .nf .IP .C "#define NBREPLY 64" .C "struct blmodeio {" .C " unsigned long cb_flags; /* Modes */" .C " unsigned char cb_trig1c; /* First trigger */" .C " unsigned char cb_trig2c; /* Second trigger */" .C " unsigned char cb_alertc; /* Alert character */" .C " unsigned char cb_termc; /* Terminating char */" .C " unsigned char cb_replen; /* cb_reply length */" .C " char cb_reply[NBREPLY]; /* optional reply */" .C }; .fi .PP The .C cb_flags field controls the basic block-mode protocol: .nf .IP .CR "CB_BMTRANS 0000001 " "Enable mandatory block-mode transmission." .CR "CB_OWNTERM 0000002 " "Enable user control of handshake." .fi .PP If .C CB_BMTRANS is set, all transmissions are processed as block-mode transmissions. The block-mode handshake is not required and data read is processed as block-mode transfer data. The block-mode handshake can still be invoked by receipt of an .I alert character as the first character seen. A .C blread() issued with the .C CB_BMTRANS bit set causes any existing input buffer data to be flushed. .PP If .C CB_BMTRANS is not set, and if the .I alert character is defined and is detected anywhere in the input stream, the input buffer is flushed and the block-mode handshake is invoked. The system then sends the .C cb_trig2c character to the terminal, and a block-mode transfer follows. The .I alert character can be escaped by preceding it with a backslash .RC ( \e ). .PP If .C CB_OWNTERM is set, reads are terminated upon receipt of a non-escaped .I alert character. No input buffer flushing is performed, and the .I alert character is returned in the data read. This allows application code to perform its own block-mode handshaking. If the bit is clear, a non-escaped .I alert character causes normal block-mode handshaking to be used. .PP The initial .C cb_flags value is all-bits-cleared. .RE .PP There are several special characters (both input and output) that are used with block mode. These characters and the initial values for these characters are described below. Any of these characters can be undefined by setting its value to 0377. .TP 15 .C cb_trig1c (default .SM DC1\c ) is the initial .I trigger character sent to the terminal at the beginning of a read request. .TP .C cb_trig2c (default .SM DC1\c ) is the secondary .I trigger character sent to the terminal after the .I alert character has been seen. .TP .C cb_alertc (default .SM DC2\c ) is the .I alert character sent by the terminal in response to the first .I trigger character. It signifies that the terminal is ready to send the data block. The .I alert character can be escaped by preceding it with a backslash ("\\"). .TP .C cb_termc (default .SM RS\c ) is sent by the terminal after the block-mode transfer has completed. It signifies the end of the data block to the computer. .PP The .C cb_replen field specifies the length in bytes of the .C cb_reply field. If set to zero, the .C cb_reply string is not used. The .C cb_replen field is initially set to zero. .PP The .C cb_reply array contains a string to be sent out after receipt of the .I alert character, but before the second .I trigger character is sent by the computer. Any character can be included in the reply string. The number of characters sent is specified by .CR cb_replen . The initial value of all characters in the .C cb_reply array is .SM NULL. .RE .SH RETURNS If an error occurs, all calls return a value of \(mi1 and .C errno is set to indicate the error. If no error is detected, .C blread() returns the number of characters read. All other calls return 0 upon successful completion. .PP During a read, it is possible for the user's buffer to be altered, even if an error value is returned. The data in the user's buffer should be ignored as it is not complete. The following errors can be returned by the library calls indicated: .SS blopen() .RS .TP 15 .SM [ENOTTY] The file descriptor specified is not related to a terminal device. .RE .SS blclose() .RS .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blread() .RS .TP 15 .SM [EDEADLK] A resource deadlock would occur as a result of this operation (see .IR lockf (2)). .PP .TP 15 .SM [EFAULT] .C buf points outside the allocated address space. The reliable detection of this error is implementation dependent. .TP 15 .SM [EINTR] A signal was caught during the .C read system call. .PP .TP 15 .SM [EIO] An I/O error occured during block-mode data transmissions. .PP .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blget() .RS .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blset() .RS .TP 15 .SM [EINVAL] An illegal value was specified in the structure passed to the system. .PP .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .SH WARNINGS Once .C blopen has been called with a file descriptor and returned successfully, that file descriptor should not subsequently be used as a parameter to the following system calls: .CR close() , .CR dup() , .CR dup2() , .CR fcntl() , .CR ioctl() , .CR read() , or .CR select() until a .C blclose is called with the same file descriptor as its parameter. Additionally, .CR scanf() , .CR fscanf() , .CR getc() , .CR getchar() , .CR fgetc() , and .C fgetw() should not be called for a stream associated with a file descriptor that has been used in a .C blopen() call but has not been used in a .C blclose() call. These functions call .CR read() , and calling these routines results in unpredictable behavior. .SH AUTHOR .CR blopen() , .CR blclose() , .CR blread() , .CR blget() , and .CR blset() were developed by HP. .SH SEE ALSO termio(7). .\" index@\f4blmode()\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blopen(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blclose(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blread(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blget(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blset(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@block-mode terminal \s-1I/O\s+1 library interface@@@\f3blmode(3C)\f1 .\" index@terminal \s-1I/O\s+1, block-mode library interface for@@@\f3blmode(3C)\f1 .\" index@terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" .\" toc@\f3blmode(3C)\f1:\0\0\f4blmode()\fP@@@terminal block-mode library interface .\" toc@\f4blopen(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blclose(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blread(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blget(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blset(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" .\" links@blmode.3c blopen.3c .\" links@blmode.3c blclose.3c .\" links@blmode.3c blread.3c .\" links@blmode.3c blget.3c .\" links@blmode.3c blset.3c .\" $Header: blmode.3c,v 74.1 95/03/23 17:44:35 ssa Exp $ .TA b .TH blmode 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not implemented on 700 .SH NAME blopen(\|), blclose(\|), blread(\|), blget(\|), blset(\|) \- terminal block-mode library interface .SH SYNOPSIS .C "#include " .PP .C "int blopen(int fildes);" .PP .C "int blclose(int bfdes);" .PP .C "int blread(int bfdes, char *buf, size_t nbyte);" .PP .C "int blget(int bfdes, struct blmodeio *arg);" .PP .C "int blset(int bfdes, const struct blmodeio *arg);" .SH DESCRIPTION .PP This terminal library interface allows support of block-mode transfers with .SM HP terminals. Block mode only affects input processing. Therefore, data is written with the standard .C write() interface (see .IR write (2)). .PP In character mode, the terminal sends each character to the system as it is typed. However, in block mode, data is buffered and possibly edited locally in the terminal memory as it is typed, then sent as a block of data when the .B [Enter] key is pressed on the terminal. During block-mode data transmissions, the incoming data is not echoed by the interface and no special character processing is performed, other than recognizing a data block terminator character. For subsequent character mode transmissions, the existing termio state (see .IR termio (7)) continues to determine echo and character processing. .PP Block-mode protocol has two component parts: block-mode handshake and block-mode transmission. .SS Block-Mode Handshake At the beginning of a read, a .I trigger character is sent to the terminal to notify it that the system wants a block of data (the .I trigger character, if defined, is sent at the beginning of all reads, whether in character- or block-mode. It is necessary for block-mode reads to work correctly). .PP After receiving the .I trigger character, and when the user has typed all the data into the terminal's memory and pressed the .B [Enter] key, the terminal sends an .I alert character to the system to notify it that the terminal has a block of data to send. .PP The system might then send user-definable cursor-positioning or other data sequences to the terminal, such as for cursor-home or lock-keyboard. .PP The system then sends a second .I trigger character to the terminal. In response, the terminal transmits the data block as described in the Block-Mode Transmission section. .SS Block-Mode Transmission The second part of the block-mode protocol is the block-mode transmission. After the block-mode handshake has successfully completed, the terminal transmits the data block to the system. During this transmission of data, the incoming data is not echoed by the system and no special character processing is performed, other than recognizing the data block termination character. It is possible to bypass the block-mode handshake and have the block-mode transmission occur after only the first .I trigger character is sent, see .C CB_BMTRANS below. .PP It is possible to intermix both character-mode and block-mode data transmissions. If .C CB_BMTRANS (see below) is set, all transfers are block-mode transfers. When .C CB_BMTRANS is not set, character mode transmissions are processed as described in .IR termio (7). In this case, if an .I alert character is received anywhere in the input data, the transmission mode is automatically switched to block mode for a single transmission. Any data received before the .I alert is discarded. The .I alert character can be escaped with a backslash .RC ( \e ) character. .SS \s-1XON/XOFF\s0 Flow Control To prevent data loss, .SM XON/XOFF flow control should be used between the system and the terminal. The .SM IXOFF bit (see .IR termio (7)) should be set and the terminal strapped appropriately. If flow control is not used, it is possible for incoming data to overflow and be lost. (Note: some older terminals do not support .SM XON/XOFF flow control.) .SS Read Requests Read requests that receive data from block-mode transmissions do not return until the transmission is complete (the terminal has transmitted all characters). If the read is satisfied by byte count or if a data transmission error occurs, all subsequent data is discarded until the transmission is complete. The read waits until a terminator character is seen, or until a time interval specified by the system has passed that is longer than necessary for the number of characters specified. .PP The data-block-terminator character is included in the data returned to the user, and is included in the byte count. If the number of bytes transferred by the terminal in a block-mode transfer exceeds the number of bytes requested by the user, the read returns the requested number of bytes and the remaining bytes are discarded. The user can determine if data was discarded by checking the last character of the returned data. If the last character is not the terminator character, then more data was received than was requested and data was discarded. .PP The .SM EIO error can be caused by several events, including errors in transmission, framing, parity, break, and overrun, or if the internal timer expires. The internal timer starts when the second trigger character is sent by the computer, and ends when the terminating character is received by the computer. The length of this timer is determined by the number of bytes requested in the read and the current baud rate, plus an additional ten seconds. .SS User Control of Handshaking If desired, the application program can provide its own handshake mechanism in response to the .I alert character by selecting the .C OWNTERM mode (see .C CB_OWNTERM below). With this mode selected, the driver completes a read request when the .I alert character is received. No data is discarded before the .IR alert , and the .I alert is returned in the data read. The .I alert character may be escaped with a backslash .RC ( \e ) character. The second .I trigger is sent when the application issues the next read. .SS blmode Control Calls First, the standard .C open() call to a tty device must be made to obtain a file descriptor for the subsequent block-mode control calls (an .C open() is done automatically by the system for .C stdin on the terminal). .RS .TP .C int bfdes; .TP .C bfdes = blopen (int fildes) A call to .C blopen() must be made before any block-mode access is allowed on the specified file descriptor. .C blopen() initializes the block-mode parameters as described below. The return value from .C blopen() is a block-mode file descriptor that must be passed to all subsequent block-mode control calls. .TP .C int blclose (int bfdes) A call to .C blclose() must be issued before the standard .C close() to ensure proper closure of the device (see .IR close (2)). Otherwise unpredictable results can occur. The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blread (int bfdes, char *buf, size_t nbyte)" The .C blread() routine has the same parameters as the .C read() sytem call (see .IR read (2)). At the beginning of a read, the .C cb_trig1c character (if defined) is sent to the device. If .C CB_BMTRANS is not set, and no .C cb_alertc character is received, the read data is processed according to .IR termio (7). If .C CB_BMTRANS is set, or if a non-escaped .C cb_alertc character is received, echo is turned off for the duration of the transfer, and no further special character processing is done other than that required for the termination character. The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blget (int bfdes, struct blmodeio *arg)" A call to .C blget() returns the current values of the .C blmodeio structure (see below). The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blset (int bfdes, const struct blmodeio *arg)" A call to .C blset() sets the block-mode values from the structure whose address is .IR arg . The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .RE .SS blmode Structure The two block-mode control calls, .C blget() and .CR blset() , use the following structure, defined in .RC < sys/blmodeio.h >: .nf .IP .C "#define NBREPLY 64" .C "struct blmodeio {" .C " unsigned long cb_flags; /* Modes */" .C " unsigned char cb_trig1c; /* First trigger */" .C " unsigned char cb_trig2c; /* Second trigger */" .C " unsigned char cb_alertc; /* Alert character */" .C " unsigned char cb_termc; /* Terminating char */" .C " unsigned char cb_replen; /* cb_reply length */" .C " char cb_reply[NBREPLY]; /* optional reply */" .C }; .fi .PP The .C cb_flags field controls the basic block-mode protocol: .nf .IP .CR "CB_BMTRANS 0000001 " "Enable mandatory block-mode transmission." .CR "CB_OWNTERM 0000002 " "Enable user control of handshake." .fi .PP If .C CB_BMTRANS is set, all transmissions are processed as block-mode transmissions. The block-mode handshake is not required and data read is processed as block-mode transfer data. The block-mode handshake can still be invoked by receipt of an .I alert character as the first character seen. A .C blread() issued with the .C CB_BMTRANS bit set causes any existing input buffer data to be flushed. .PP If .C CB_BMTRANS is not set, and if the .I alert character is defined and is detected anywhere in the input stream, the input buffer is flushed and the block-mode handshake is invoked. The system then sends the .C cb_trig2c character to the terminal, and a block-mode transfer follows. The .I alert character can be escaped by preceding it with a backslash .RC ( \e ). .PP If .C CB_OWNTERM is set, reads are terminated upon receipt of a non-escaped .I alert character. No input buffer flushing is performed, and the .I alert character is returned in the data read. This allows application code to perform its own block-mode handshaking. If the bit is clear, a non-escaped .I alert character causes normal block-mode handshaking to be used. .PP The initial .C cb_flags value is all-bits-cleared. .RE .PP There are several special characters (both input and output) that are used with block mode. These characters and the initial values for these characters are described below. Any of these characters can be undefined by setting its value to 0377. .TP 15 .C cb_trig1c (default .SM DC1\c ) is the initial .I trigger character sent to the terminal at the beginning of a read request. .TP .C cb_trig2c (default .SM DC1\c ) is the secondary .I trigger character sent to the terminal after the .I alert character has been seen. .TP .C cb_alertc (default .SM DC2\c ) is the .I alert character sent by the terminal in response to the first .I trigger character. It signifies that the terminal is ready to send the data block. The .I alert character can be escaped by preceding it with a backslash ("\\"). .TP .C cb_termc (default .SM RS\c ) is sent by the terminal after the block-mode transfer has completed. It signifies the end of the data block to the computer. .PP The .C cb_replen field specifies the length in bytes of the .C cb_reply field. If set to zero, the .C cb_reply string is not used. The .C cb_replen field is initially set to zero. .PP The .C cb_reply array contains a string to be sent out after receipt of the .I alert character, but before the second .I trigger character is sent by the computer. Any character can be included in the reply string. The number of characters sent is specified by .CR cb_replen . The initial value of all characters in the .C cb_reply array is .SM NULL. .RE .SH RETURNS If an error occurs, all calls return a value of \(mi1 and .C errno is set to indicate the error. If no error is detected, .C blread() returns the number of characters read. All other calls return 0 upon successful completion. .PP During a read, it is possible for the user's buffer to be altered, even if an error value is returned. The data in the user's buffer should be ignored as it is not complete. The following errors can be returned by the library calls indicated: .SS blopen() .RS .TP 15 .SM [ENOTTY] The file descriptor specified is not related to a terminal device. .RE .SS blclose() .RS .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blread() .RS .TP 15 .SM [EDEADLK] A resource deadlock would occur as a result of this operation (see .IR lockf (2)). .PP .TP 15 .SM [EFAULT] .C buf points outside the allocated address space. The reliable detection of this error is implementation dependent. .TP 15 .SM [EINTR] A signal was caught during the .C read system call. .PP .TP 15 .SM [EIO] An I/O error occured during block-mode data transmissions. .PP .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blget() .RS .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blset() .RS .TP 15 .SM [EINVAL] An illegal value was specified in the structure passed to the system. .PP .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .SH WARNINGS Once .C blopen has been called with a file descriptor and returned successfully, that file descriptor should not subsequently be used as a parameter to the following system calls: .CR close() , .CR dup() , .CR dup2() , .CR fcntl() , .CR ioctl() , .CR read() , or .CR select() until a .C blclose is called with the same file descriptor as its parameter. Additionally, .CR scanf() , .CR fscanf() , .CR getc() , .CR getchar() , .CR fgetc() , and .C fgetw() should not be called for a stream associated with a file descriptor that has been used in a .C blopen() call but has not been used in a .C blclose() call. These functions call .CR read() , and calling these routines results in unpredictable behavior. .SH AUTHOR .CR blopen() , .CR blclose() , .CR blread() , .CR blget() , and .CR blset() were developed by HP. .SH SEE ALSO termio(7). .\" index@\f4blmode()\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blopen(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blclose(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blread(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blget(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blset(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@block-mode terminal \s-1I/O\s+1 library interface@@@\f3blmode(3C)\f1 .\" index@terminal \s-1I/O\s+1, block-mode library interface for@@@\f3blmode(3C)\f1 .\" index@terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" .\" toc@\f3blmode(3C)\f1:\0\0\f4blmode()\fP@@@terminal block-mode library interface .\" toc@\f4blopen(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blclose(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blread(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blget(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blset(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" .\" links@blmode.3c blopen.3c .\" links@blmode.3c blclose.3c .\" links@blmode.3c blread.3c .\" links@blmode.3c blget.3c .\" links@blmode.3c blset.3c .\" $Header: blmode.3c,v 74.1 95/03/23 17:44:35 ssa Exp $ .TA b .TH blmode 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not implemented on 700 .SH NAME blopen(\|), blclose(\|), blread(\|), blget(\|), blset(\|) \- terminal block-mode library interface .SH SYNOPSIS .C "#include " .PP .C "int blopen(int fildes);" .PP .C "int blclose(int bfdes);" .PP .C "int blread(int bfdes, char *buf, size_t nbyte);" .PP .C "int blget(int bfdes, struct blmodeio *arg);" .PP .C "int blset(int bfdes, const struct blmodeio *arg);" .SH DESCRIPTION .PP This terminal library interface allows support of block-mode transfers with .SM HP terminals. Block mode only affects input processing. Therefore, data is written with the standard .C write() interface (see .IR write (2)). .PP In character mode, the terminal sends each character to the system as it is typed. However, in block mode, data is buffered and possibly edited locally in the terminal memory as it is typed, then sent as a block of data when the .B [Enter] key is pressed on the terminal. During block-mode data transmissions, the incoming data is not echoed by the interface and no special character processing is performed, other than recognizing a data block terminator character. For subsequent character mode transmissions, the existing termio state (see .IR termio (7)) continues to determine echo and character processing. .PP Block-mode protocol has two component parts: block-mode handshake and block-mode transmission. .SS Block-Mode Handshake At the beginning of a read, a .I trigger character is sent to the terminal to notify it that the system wants a block of data (the .I trigger character, if defined, is sent at the beginning of all reads, whether in character- or block-mode. It is necessary for block-mode reads to work correctly). .PP After receiving the .I trigger character, and when the user has typed all the data into the terminal's memory and pressed the .B [Enter] key, the terminal sends an .I alert character to the system to notify it that the terminal has a block of data to send. .PP The system might then send user-definable cursor-positioning or other data sequences to the terminal, such as for cursor-home or lock-keyboard. .PP The system then sends a second .I trigger character to the terminal. In response, the terminal transmits the data block as described in the Block-Mode Transmission section. .SS Block-Mode Transmission The second part of the block-mode protocol is the block-mode transmission. After the block-mode handshake has successfully completed, the terminal transmits the data block to the system. During this transmission of data, the incoming data is not echoed by the system and no special character processing is performed, other than recognizing the data block termination character. It is possible to bypass the block-mode handshake and have the block-mode transmission occur after only the first .I trigger character is sent, see .C CB_BMTRANS below. .PP It is possible to intermix both character-mode and block-mode data transmissions. If .C CB_BMTRANS (see below) is set, all transfers are block-mode transfers. When .C CB_BMTRANS is not set, character mode transmissions are processed as described in .IR termio (7). In this case, if an .I alert character is received anywhere in the input data, the transmission mode is automatically switched to block mode for a single transmission. Any data received before the .I alert is discarded. The .I alert character can be escaped with a backslash .RC ( \e ) character. .SS \s-1XON/XOFF\s0 Flow Control To prevent data loss, .SM XON/XOFF flow control should be used between the system and the terminal. The .SM IXOFF bit (see .IR termio (7)) should be set and the terminal strapped appropriately. If flow control is not used, it is possible for incoming data to overflow and be lost. (Note: some older terminals do not support .SM XON/XOFF flow control.) .SS Read Requests Read requests that receive data from block-mode transmissions do not return until the transmission is complete (the terminal has transmitted all characters). If the read is satisfied by byte count or if a data transmission error occurs, all subsequent data is discarded until the transmission is complete. The read waits until a terminator character is seen, or until a time interval specified by the system has passed that is longer than necessary for the number of characters specified. .PP The data-block-terminator character is included in the data returned to the user, and is included in the byte count. If the number of bytes transferred by the terminal in a block-mode transfer exceeds the number of bytes requested by the user, the read returns the requested number of bytes and the remaining bytes are discarded. The user can determine if data was discarded by checking the last character of the returned data. If the last character is not the terminator character, then more data was received than was requested and data was discarded. .PP The .SM EIO error can be caused by several events, including errors in transmission, framing, parity, break, and overrun, or if the internal timer expires. The internal timer starts when the second trigger character is sent by the computer, and ends when the terminating character is received by the computer. The length of this timer is determined by the number of bytes requested in the read and the current baud rate, plus an additional ten seconds. .SS User Control of Handshaking If desired, the application program can provide its own handshake mechanism in response to the .I alert character by selecting the .C OWNTERM mode (see .C CB_OWNTERM below). With this mode selected, the driver completes a read request when the .I alert character is received. No data is discarded before the .IR alert , and the .I alert is returned in the data read. The .I alert character may be escaped with a backslash .RC ( \e ) character. The second .I trigger is sent when the application issues the next read. .SS blmode Control Calls First, the standard .C open() call to a tty device must be made to obtain a file descriptor for the subsequent block-mode control calls (an .C open() is done automatically by the system for .C stdin on the terminal). .RS .TP .C int bfdes; .TP .C bfdes = blopen (int fildes) A call to .C blopen() must be made before any block-mode access is allowed on the specified file descriptor. .C blopen() initializes the block-mode parameters as described below. The return value from .C blopen() is a block-mode file descriptor that must be passed to all subsequent block-mode control calls. .TP .C int blclose (int bfdes) A call to .C blclose() must be issued before the standard .C close() to ensure proper closure of the device (see .IR close (2)). Otherwise unpredictable results can occur. The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blread (int bfdes, char *buf, size_t nbyte)" The .C blread() routine has the same parameters as the .C read() sytem call (see .IR read (2)). At the beginning of a read, the .C cb_trig1c character (if defined) is sent to the device. If .C CB_BMTRANS is not set, and no .C cb_alertc character is received, the read data is processed according to .IR termio (7). If .C CB_BMTRANS is set, or if a non-escaped .C cb_alertc character is received, echo is turned off for the duration of the transfer, and no further special character processing is done other than that required for the termination character. The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blget (int bfdes, struct blmodeio *arg)" A call to .C blget() returns the current values of the .C blmodeio structure (see below). The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blset (int bfdes, const struct blmodeio *arg)" A call to .C blset() sets the block-mode values from the structure whose address is .IR arg . The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .RE .SS blmode Structure The two block-mode control calls, .C blget() and .CR blset() , use the following structure, defined in .RC < sys/blmodeio.h >: .nf .IP .C "#define NBREPLY 64" .C "struct blmodeio {" .C " unsigned long cb_flags; /* Modes */" .C " unsigned char cb_trig1c; /* First trigger */" .C " unsigned char cb_trig2c; /* Second trigger */" .C " unsigned char cb_alertc; /* Alert character */" .C " unsigned char cb_termc; /* Terminating char */" .C " unsigned char cb_replen; /* cb_reply length */" .C " char cb_reply[NBREPLY]; /* optional reply */" .C }; .fi .PP The .C cb_flags field controls the basic block-mode protocol: .nf .IP .CR "CB_BMTRANS 0000001 " "Enable mandatory block-mode transmission." .CR "CB_OWNTERM 0000002 " "Enable user control of handshake." .fi .PP If .C CB_BMTRANS is set, all transmissions are processed as block-mode transmissions. The block-mode handshake is not required and data read is processed as block-mode transfer data. The block-mode handshake can still be invoked by receipt of an .I alert character as the first character seen. A .C blread() issued with the .C CB_BMTRANS bit set causes any existing input buffer data to be flushed. .PP If .C CB_BMTRANS is not set, and if the .I alert character is defined and is detected anywhere in the input stream, the input buffer is flushed and the block-mode handshake is invoked. The system then sends the .C cb_trig2c character to the terminal, and a block-mode transfer follows. The .I alert character can be escaped by preceding it with a backslash .RC ( \e ). .PP If .C CB_OWNTERM is set, reads are terminated upon receipt of a non-escaped .I alert character. No input buffer flushing is performed, and the .I alert character is returned in the data read. This allows application code to perform its own block-mode handshaking. If the bit is clear, a non-escaped .I alert character causes normal block-mode handshaking to be used. .PP The initial .C cb_flags value is all-bits-cleared. .RE .PP There are several special characters (both input and output) that are used with block mode. These characters and the initial values for these characters are described below. Any of these characters can be undefined by setting its value to 0377. .TP 15 .C cb_trig1c (default .SM DC1\c ) is the initial .I trigger character sent to the terminal at the beginning of a read request. .TP .C cb_trig2c (default .SM DC1\c ) is the secondary .I trigger character sent to the terminal after the .I alert character has been seen. .TP .C cb_alertc (default .SM DC2\c ) is the .I alert character sent by the terminal in response to the first .I trigger character. It signifies that the terminal is ready to send the data block. The .I alert character can be escaped by preceding it with a backslash ("\\"). .TP .C cb_termc (default .SM RS\c ) is sent by the terminal after the block-mode transfer has completed. It signifies the end of the data block to the computer. .PP The .C cb_replen field specifies the length in bytes of the .C cb_reply field. If set to zero, the .C cb_reply string is not used. The .C cb_replen field is initially set to zero. .PP The .C cb_reply array contains a string to be sent out after receipt of the .I alert character, but before the second .I trigger character is sent by the computer. Any character can be included in the reply string. The number of characters sent is specified by .CR cb_replen . The initial value of all characters in the .C cb_reply array is .SM NULL. .RE .SH RETURNS If an error occurs, all calls return a value of \(mi1 and .C errno is set to indicate the error. If no error is detected, .C blread() returns the number of characters read. All other calls return 0 upon successful completion. .PP During a read, it is possible for the user's buffer to be altered, even if an error value is returned. The data in the user's buffer should be ignored as it is not complete. The following errors can be returned by the library calls indicated: .SS blopen() .RS .TP 15 .SM [ENOTTY] The file descriptor specified is not related to a terminal device. .RE .SS blclose() .RS .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blread() .RS .TP 15 .SM [EDEADLK] A resource deadlock would occur as a result of this operation (see .IR lockf (2)). .PP .TP 15 .SM [EFAULT] .C buf points outside the allocated address space. The reliable detection of this error is implementation dependent. .TP 15 .SM [EINTR] A signal was caught during the .C read system call. .PP .TP 15 .SM [EIO] An I/O error occured during block-mode data transmissions. .PP .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blget() .RS .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blset() .RS .TP 15 .SM [EINVAL] An illegal value was specified in the structure passed to the system. .PP .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .SH WARNINGS Once .C blopen has been called with a file descriptor and returned successfully, that file descriptor should not subsequently be used as a parameter to the following system calls: .CR close() , .CR dup() , .CR dup2() , .CR fcntl() , .CR ioctl() , .CR read() , or .CR select() until a .C blclose is called with the same file descriptor as its parameter. Additionally, .CR scanf() , .CR fscanf() , .CR getc() , .CR getchar() , .CR fgetc() , and .C fgetw() should not be called for a stream associated with a file descriptor that has been used in a .C blopen() call but has not been used in a .C blclose() call. These functions call .CR read() , and calling these routines results in unpredictable behavior. .SH AUTHOR .CR blopen() , .CR blclose() , .CR blread() , .CR blget() , and .CR blset() were developed by HP. .SH SEE ALSO termio(7). .\" index@\f4blmode()\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blopen(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blclose(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blread(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blget(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blset(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@block-mode terminal \s-1I/O\s+1 library interface@@@\f3blmode(3C)\f1 .\" index@terminal \s-1I/O\s+1, block-mode library interface for@@@\f3blmode(3C)\f1 .\" index@terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" .\" toc@\f3blmode(3C)\f1:\0\0\f4blmode()\fP@@@terminal block-mode library interface .\" toc@\f4blopen(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blclose(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blread(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blget(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blset(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" .\" links@blmode.3c blopen.3c .\" links@blmode.3c blclose.3c .\" links@blmode.3c blread.3c .\" links@blmode.3c blget.3c .\" links@blmode.3c blset.3c .\" $Header: blmode.3c,v 74.1 95/03/23 17:44:35 ssa Exp $ .TA b .TH blmode 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not implemented on 700 .SH NAME blopen(\|), blclose(\|), blread(\|), blget(\|), blset(\|) \- terminal block-mode library interface .SH SYNOPSIS .C "#include " .PP .C "int blopen(int fildes);" .PP .C "int blclose(int bfdes);" .PP .C "int blread(int bfdes, char *buf, size_t nbyte);" .PP .C "int blget(int bfdes, struct blmodeio *arg);" .PP .C "int blset(int bfdes, const struct blmodeio *arg);" .SH DESCRIPTION .PP This terminal library interface allows support of block-mode transfers with .SM HP terminals. Block mode only affects input processing. Therefore, data is written with the standard .C write() interface (see .IR write (2)). .PP In character mode, the terminal sends each character to the system as it is typed. However, in block mode, data is buffered and possibly edited locally in the terminal memory as it is typed, then sent as a block of data when the .B [Enter] key is pressed on the terminal. During block-mode data transmissions, the incoming data is not echoed by the interface and no special character processing is performed, other than recognizing a data block terminator character. For subsequent character mode transmissions, the existing termio state (see .IR termio (7)) continues to determine echo and character processing. .PP Block-mode protocol has two component parts: block-mode handshake and block-mode transmission. .SS Block-Mode Handshake At the beginning of a read, a .I trigger character is sent to the terminal to notify it that the system wants a block of data (the .I trigger character, if defined, is sent at the beginning of all reads, whether in character- or block-mode. It is necessary for block-mode reads to work correctly). .PP After receiving the .I trigger character, and when the user has typed all the data into the terminal's memory and pressed the .B [Enter] key, the terminal sends an .I alert character to the system to notify it that the terminal has a block of data to send. .PP The system might then send user-definable cursor-positioning or other data sequences to the terminal, such as for cursor-home or lock-keyboard. .PP The system then sends a second .I trigger character to the terminal. In response, the terminal transmits the data block as described in the Block-Mode Transmission section. .SS Block-Mode Transmission The second part of the block-mode protocol is the block-mode transmission. After the block-mode handshake has successfully completed, the terminal transmits the data block to the system. During this transmission of data, the incoming data is not echoed by the system and no special character processing is performed, other than recognizing the data block termination character. It is possible to bypass the block-mode handshake and have the block-mode transmission occur after only the first .I trigger character is sent, see .C CB_BMTRANS below. .PP It is possible to intermix both character-mode and block-mode data transmissions. If .C CB_BMTRANS (see below) is set, all transfers are block-mode transfers. When .C CB_BMTRANS is not set, character mode transmissions are processed as described in .IR termio (7). In this case, if an .I alert character is received anywhere in the input data, the transmission mode is automatically switched to block mode for a single transmission. Any data received before the .I alert is discarded. The .I alert character can be escaped with a backslash .RC ( \e ) character. .SS \s-1XON/XOFF\s0 Flow Control To prevent data loss, .SM XON/XOFF flow control should be used between the system and the terminal. The .SM IXOFF bit (see .IR termio (7)) should be set and the terminal strapped appropriately. If flow control is not used, it is possible for incoming data to overflow and be lost. (Note: some older terminals do not support .SM XON/XOFF flow control.) .SS Read Requests Read requests that receive data from block-mode transmissions do not return until the transmission is complete (the terminal has transmitted all characters). If the read is satisfied by byte count or if a data transmission error occurs, all subsequent data is discarded until the transmission is complete. The read waits until a terminator character is seen, or until a time interval specified by the system has passed that is longer than necessary for the number of characters specified. .PP The data-block-terminator character is included in the data returned to the user, and is included in the byte count. If the number of bytes transferred by the terminal in a block-mode transfer exceeds the number of bytes requested by the user, the read returns the requested number of bytes and the remaining bytes are discarded. The user can determine if data was discarded by checking the last character of the returned data. If the last character is not the terminator character, then more data was received than was requested and data was discarded. .PP The .SM EIO error can be caused by several events, including errors in transmission, framing, parity, break, and overrun, or if the internal timer expires. The internal timer starts when the second trigger character is sent by the computer, and ends when the terminating character is received by the computer. The length of this timer is determined by the number of bytes requested in the read and the current baud rate, plus an additional ten seconds. .SS User Control of Handshaking If desired, the application program can provide its own handshake mechanism in response to the .I alert character by selecting the .C OWNTERM mode (see .C CB_OWNTERM below). With this mode selected, the driver completes a read request when the .I alert character is received. No data is discarded before the .IR alert , and the .I alert is returned in the data read. The .I alert character may be escaped with a backslash .RC ( \e ) character. The second .I trigger is sent when the application issues the next read. .SS blmode Control Calls First, the standard .C open() call to a tty device must be made to obtain a file descriptor for the subsequent block-mode control calls (an .C open() is done automatically by the system for .C stdin on the terminal). .RS .TP .C int bfdes; .TP .C bfdes = blopen (int fildes) A call to .C blopen() must be made before any block-mode access is allowed on the specified file descriptor. .C blopen() initializes the block-mode parameters as described below. The return value from .C blopen() is a block-mode file descriptor that must be passed to all subsequent block-mode control calls. .TP .C int blclose (int bfdes) A call to .C blclose() must be issued before the standard .C close() to ensure proper closure of the device (see .IR close (2)). Otherwise unpredictable results can occur. The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blread (int bfdes, char *buf, size_t nbyte)" The .C blread() routine has the same parameters as the .C read() sytem call (see .IR read (2)). At the beginning of a read, the .C cb_trig1c character (if defined) is sent to the device. If .C CB_BMTRANS is not set, and no .C cb_alertc character is received, the read data is processed according to .IR termio (7). If .C CB_BMTRANS is set, or if a non-escaped .C cb_alertc character is received, echo is turned off for the duration of the transfer, and no further special character processing is done other than that required for the termination character. The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blget (int bfdes, struct blmodeio *arg)" A call to .C blget() returns the current values of the .C blmodeio structure (see below). The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .TP .C "int blset (int bfdes, const struct blmodeio *arg)" A call to .C blset() sets the block-mode values from the structure whose address is .IR arg . The argument .I bfdes is the file descriptor returned from a previous .C blopen() system call. .RE .SS blmode Structure The two block-mode control calls, .C blget() and .CR blset() , use the following structure, defined in .RC < sys/blmodeio.h >: .nf .IP .C "#define NBREPLY 64" .C "struct blmodeio {" .C " unsigned long cb_flags; /* Modes */" .C " unsigned char cb_trig1c; /* First trigger */" .C " unsigned char cb_trig2c; /* Second trigger */" .C " unsigned char cb_alertc; /* Alert character */" .C " unsigned char cb_termc; /* Terminating char */" .C " unsigned char cb_replen; /* cb_reply length */" .C " char cb_reply[NBREPLY]; /* optional reply */" .C }; .fi .PP The .C cb_flags field controls the basic block-mode protocol: .nf .IP .CR "CB_BMTRANS 0000001 " "Enable mandatory block-mode transmission." .CR "CB_OWNTERM 0000002 " "Enable user control of handshake." .fi .PP If .C CB_BMTRANS is set, all transmissions are processed as block-mode transmissions. The block-mode handshake is not required and data read is processed as block-mode transfer data. The block-mode handshake can still be invoked by receipt of an .I alert character as the first character seen. A .C blread() issued with the .C CB_BMTRANS bit set causes any existing input buffer data to be flushed. .PP If .C CB_BMTRANS is not set, and if the .I alert character is defined and is detected anywhere in the input stream, the input buffer is flushed and the block-mode handshake is invoked. The system then sends the .C cb_trig2c character to the terminal, and a block-mode transfer follows. The .I alert character can be escaped by preceding it with a backslash .RC ( \e ). .PP If .C CB_OWNTERM is set, reads are terminated upon receipt of a non-escaped .I alert character. No input buffer flushing is performed, and the .I alert character is returned in the data read. This allows application code to perform its own block-mode handshaking. If the bit is clear, a non-escaped .I alert character causes normal block-mode handshaking to be used. .PP The initial .C cb_flags value is all-bits-cleared. .RE .PP There are several special characters (both input and output) that are used with block mode. These characters and the initial values for these characters are described below. Any of these characters can be undefined by setting its value to 0377. .TP 15 .C cb_trig1c (default .SM DC1\c ) is the initial .I trigger character sent to the terminal at the beginning of a read request. .TP .C cb_trig2c (default .SM DC1\c ) is the secondary .I trigger character sent to the terminal after the .I alert character has been seen. .TP .C cb_alertc (default .SM DC2\c ) is the .I alert character sent by the terminal in response to the first .I trigger character. It signifies that the terminal is ready to send the data block. The .I alert character can be escaped by preceding it with a backslash ("\\"). .TP .C cb_termc (default .SM RS\c ) is sent by the terminal after the block-mode transfer has completed. It signifies the end of the data block to the computer. .PP The .C cb_replen field specifies the length in bytes of the .C cb_reply field. If set to zero, the .C cb_reply string is not used. The .C cb_replen field is initially set to zero. .PP The .C cb_reply array contains a string to be sent out after receipt of the .I alert character, but before the second .I trigger character is sent by the computer. Any character can be included in the reply string. The number of characters sent is specified by .CR cb_replen . The initial value of all characters in the .C cb_reply array is .SM NULL. .RE .SH RETURNS If an error occurs, all calls return a value of \(mi1 and .C errno is set to indicate the error. If no error is detected, .C blread() returns the number of characters read. All other calls return 0 upon successful completion. .PP During a read, it is possible for the user's buffer to be altered, even if an error value is returned. The data in the user's buffer should be ignored as it is not complete. The following errors can be returned by the library calls indicated: .SS blopen() .RS .TP 15 .SM [ENOTTY] The file descriptor specified is not related to a terminal device. .RE .SS blclose() .RS .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blread() .RS .TP 15 .SM [EDEADLK] A resource deadlock would occur as a result of this operation (see .IR lockf (2)). .PP .TP 15 .SM [EFAULT] .C buf points outside the allocated address space. The reliable detection of this error is implementation dependent. .TP 15 .SM [EINTR] A signal was caught during the .C read system call. .PP .TP 15 .SM [EIO] An I/O error occured during block-mode data transmissions. .PP .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blget() .RS .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .RE .SS blset() .RS .TP 15 .SM [EINVAL] An illegal value was specified in the structure passed to the system. .PP .TP 15 .SM [ENOTTY] No previous .C blopen has been issued for the specified file descriptor. .SH WARNINGS Once .C blopen has been called with a file descriptor and returned successfully, that file descriptor should not subsequently be used as a parameter to the following system calls: .CR close() , .CR dup() , .CR dup2() , .CR fcntl() , .CR ioctl() , .CR read() , or .CR select() until a .C blclose is called with the same file descriptor as its parameter. Additionally, .CR scanf() , .CR fscanf() , .CR getc() , .CR getchar() , .CR fgetc() , and .C fgetw() should not be called for a stream associated with a file descriptor that has been used in a .C blopen() call but has not been used in a .C blclose() call. These functions call .CR read() , and calling these routines results in unpredictable behavior. .SH AUTHOR .CR blopen() , .CR blclose() , .CR blread() , .CR blget() , and .CR blset() were developed by HP. .SH SEE ALSO termio(7). .\" index@\f4blmode()\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blopen(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blclose(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blread(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blget(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@\f4blset(\|)\fP \- terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" index@block-mode terminal \s-1I/O\s+1 library interface@@@\f3blmode(3C)\f1 .\" index@terminal \s-1I/O\s+1, block-mode library interface for@@@\f3blmode(3C)\f1 .\" index@terminal block-mode library interface@@@\f3blmode(3C)\f1 .\" .\" toc@\f3blmode(3C)\f1:\0\0\f4blmode()\fP@@@terminal block-mode library interface .\" toc@\f4blopen(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blclose(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blread(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blget(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" toc@\f4blset(\|)\fP \- terminal block-mode library interface@@@see \f3blmode(3C)\f1 .\" .\" links@blmode.3c blopen.3c .\" links@blmode.3c blclose.3c .\" links@blmode.3c blread.3c .\" links@blmode.3c blget.3c .\" links@blmode.3c blset.3c .\" $Header: border.3x,v 76.2 95/07/31 17:06:39 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH border 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME border, wborder \(em draw borders from single-byte characters and renditions .SH SYNOPSIS .C "#include " .P .C "int border(chtype \f2ls\fP, chtype \f2rs\fP, chtype \f2ts\fP, chtype \f2bs\fP, chtype \f2tl\fP," .br .C " chtype \f2tr\fP, chtype \f2bl\fP, chtype \f2br\fP);" .P .C "int wborder(WINDOW *\f2win\fP, chtype \f2ls\fP, chtype \f2rs\fP, chtype \f2ts\fP, chtype \f2bs\fP," .br .C " chtype \f2tl\fP, chtype \f2tr\fP, chtype \f2bl\fP, chtype \f2br\fP);" .SH DESCRIPTION The .Fn border and .Fn wborder functions draw a border around the edges of the current or specified window. These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The arguments in the left-hand column of the following table contain single-byte characters with renditions, which have the following uses in drawing the border: .PP .TS box center tab(@); cb cb cb cb cb cb li l l. Argument@@Default Name@Usage@Value _ ls@Starting-column side@ACS_VLINE rs@Ending-column side@ACS_VLINE ts@First-line side@ACS_HLINE bs@Last-line side@ACS_HLINE tl@Corner of the first line and the starting column@ACS_ULCORNER tr@Corner of the first line and the ending column@ACS_URCORNER bl@Corner of the last line and the starting column@ACS_BLCORNER br@Corner of the last line and the ending column@ACS_BRCORNER .TE .PP If the value of any argument in the left-hand column is 0, then the default value in the right-hand column is used. If the value of any argument in the left-hand column is a multi-column character, the results are undefined. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" border_set(), box (), hline(), .Hd curses.h .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3border(3X)\f1:\0\0\f4wborder()\f1@@@draw borders from single-byte characters and renditions .\" toc@\f4wborder()\f1: draw borders from single-byte characters and renditions@@@see \f3border(3X)\f1 .\" index@\f1draw borders from single-byte characters and renditions@@@\f3border(3X)\f1 .\" index@\f4border()\f1 \- draw borders from single-byte characters and renditions@@@\f3border(3X)\f1 .\" index@\f1borders, draw from single-byte characters and renditions@@@\f3border(3X)\f1 .\" index@\f1single-byte characters and renditions, draw borders@@@\f3border(3X)\f1 .\" .\" links@border.3x wborder.3x .\" .\" fileset_database@border.3x CURS-ENG-A-MAN .\" $Header: border_set.3x,v 76.2 95/07/31 17:08:12 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH border_set 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME border_set, wborder_set \(em draw borders from complex characters and renditions .SH SYNOPSIS .C "#include " .P .C "int border_set(cchar_t *const \f2ls\fP, cchar_t *const \f2rs\fP, cchar_t *const \f2ts\fP," .br .C " cchar_t *const \f2bs\fP, cchar_t *const \f2tl\fP, cchar_t *const \f2tr\fP," .br .C " cchar_t *const \f2bl\fP, cchar_t *const \f2br\fP);" .PP .C "int wborder_set(WINDOW *\f2win\fP, cchar_t *const \f2ls\fP, cchar_t *const \f2rs\fP," .br .C " cchar_t *const \f2ts\fP, cchar_t *const \f2bs\fP, " .br .C " cchar_t *const \f2tl\fP, cchar_t *const \f2tr\fP, " .br .C " cchar_t *const \f2bl\fP, cchar_t *const \f2br\fP);" .SH DESCRIPTION The .Fn border_set and .Fn wborder_set functions draw a border around the edges of the current or specified window. These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The arguments in the left-hand column of the following table contain spacing complex characters with renditions, which have the following uses in drawing the border: .PP .TS box center tab(@); cb cb cb cb cb cb li l l. Argument@@Default Name@Usage@Value _ ls@Starting-column side@WACS_VLINE rs@Ending-column side@WACS_VLINE ts@First-line side@WACS_HLINE bs@Last-line side@WACS_HLINE tl@Corner of the first line and the starting column@WACS_ULCORNER tr@Corner of the first line and the ending column@WACS_URCORNER bl@Corner of the last line and the starting column@WACS_BLCORNER br@Corner of the last line and the ending column@WACS_BRCORNER .TE .PP If the value of any argument in the left-hand column is a null pointer, then the default value in the right-hand column is used. If the value of any argument in the left-hand column is a multi-column character, the results are undefined. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" box_set(), hline_set(), .Hd curses.h .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3border_set(3X)\f1:\0\0\f4wborder_set()\f1@@@draw borders from complex characters and renditions .\" toc@\f4wborder_set()\f1: draw borders from complex characters and renditions@@@see \f3border_set(3X)\f1 .\" .\" index@\f4border_set()\f1 \- draw borders from complex characters and renditions@@@\f3border_set(3X)\f1 .\" index@\f1draw borders from complex characters and renditions@@@\f3border_set(3X)\f1 .\" index@\f1borders, draw from complex characters and renditions@@@\f3border_set(3X)\f1 .\" index@\f1complex characters and renditions, draw borders@@@\f3border_set(3X)\f1 .\" .\" links@border_set.3x wborder_set.3x .\" .\" fileset_database@border_set.3x CURS-ENG-A-MAN .\" $Header: box.3x,v 76.2 95/07/31 17:09:18 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH box 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME box \(em draw borders from single-byte characters and renditions .SH SYNOPSIS .C "#include " .P .C "int box(WINDOW *\f2win\fP, chtype \f2verch\fP, chtype \f2horch\fP);" .SH DESCRIPTION The .Fn box function draws a border around the edges of the specified window. This function does not advance the cursor position. This function does not perform special character processing. This function does not perform wrapping. .P The function \f4box\fP(\f2win\fP, \f2verch\fP, \f2horch\fP) has an effect equivalent to: .P .\" unknown macro .Cs I \f4wborder\f1(\f2win\fP, \f2verch\fP, \f2verch\fP, \f2horch\fP, \f2horch\fP, 0, 0, 0, 0); .\" unknown macro .Ce .SH "RETURN VALUE" Upon successful completion, .Fn box returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" border(), box_set(), hline(), .Hd curses.h .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .B DESCRIPTION is changed to describe this function in terms of a call to the .Fn wborder function. .\" .\" index@\f4box()\f1 \- draw borders from single-byte characters and renditions@@@\f3box(3X)\f1 .\" index@\f1draw borders from single-byte characters and renditions@@@\f3box(3X)\f1 .\" index@\f1borders, draw from single-byte characters and renditions@@@\f3box(3X)\f1 .\" index@\f1single-byte characters and renditions, draw borders@@@\f3box(3X)\f1 .\" .\" toc@\f3box(3X)\f1:\0\0\f4box\f1@@@draw borders from single-byte characters and renditions .\" .\" fileset_database@box.3x CURS-ENG-A-MAN .\" $Header: box_set.3x,v 76.2 95/07/31 17:10:25 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH box_set 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME box_set \(em draw borders from complex characters and renditions .SH SYNOPSIS .C "#include " .P .C "int box_set(WINDOW *\f2win\fP, cchar_t *const \f2verch\fP, cchar_t *const \f2horch\fP);" .SH DESCRIPTION The .Fn box_set function draws a border around the edges of the specified window. This function does not advance the cursor position. This function does not perform special character processing. This function does not perform wrapping. .P The function \f4box_set\f1(\f2win\f1, \f2verch\f1, \f2horch\f1) has an effect equivalent to: .P .\" unknown macro .Cs I \f4wborder_set\f1(\f2win\fP, \f2verch\fP, \f2verch\fP, \f2horch\fP, \f2horch\fP, NULL, NULL, NULL, NULL); .\" unknown macro .Ce .SH "RETURN VALUE" Upon successful completion, this function returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" border_set(), hline_set(), .Hd curses.h .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4box_set()\f1 \- draw borders from complex characters and renditions@@@\f3box_set(3X)\f1 .\" index@\f1draw borders from complex characters and renditions@@@\f3box_set(3X)\f1 .\" index@\f1complex characters and renditions, draw borders from@@@\f3box_set(3X)\f1 .\" index@\f1borders, draw from complex characters and renditions@@@\f3box_set(3X)\f1 .\" .\" toc@\f3box_set(3X)\f1:\0\0\f4box_set\f1@@@draw borders from complex characters and renditions .\" .\" fileset_database@box_set.3x CURS-ENG-A-MAN .\" $Header: bsearch.3c,v 72.4 94/11/14 13:03:29 ssa Exp $ .TA b .TH bsearch 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bsearch(\|) \- binary search a sorted table .SH SYNOPSIS .C "#include " .PP .C "void *bsearch(" .PD 0 .nf .IP .C "const void *key," .C "const void *base," .C "size_t nel," .C "size_t size," .C "int (*compar)(const void *, const void *) .PP .C ");" .PD .fi .SH DESCRIPTION .C bsearch() is a binary search routine generalized from Knuth (6.2.1) Algorithm B. It returns a pointer into a table indicating where a datum may be found. The table must be previously sorted in increasing order according to a provided comparison function. .I key points to a datum instance to be sought in the table. .I base points to the element at the base of the table. .I nel is the number of elements in the table. .I size is the size of each element in the table. .I compar is the name of the comparison function, which is called with two arguments that point to the elements being compared. The function must return an integer less than, equal to, or greater than zero indicating that the first argument is to be considered less than, equal to, or greater than the second. .SH NOTES The pointers to the key and the element at the base of the table should be of type pointer-to-element, and cast to type pointer-to-void. .PP The comparison function need not compare every byte, so arbitrary data can be contained in the elements in addition to the values being compared. .PP Although declared as type pointer-to-void, the value returned should be cast into type pointer-to-element. .SH RETURN VALUE A .SM NULL pointer is returned if the key cannot be found in the table. .SH EXAMPLES The example below searches a table containing pointers to nodes consisting of a string and its length. The table is ordered alphabetically on the string in the node pointed to by each entry. .PP This code fragment reads in strings and either finds the corresponding node and prints out the string and its length, or prints an error message. .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 #include #define TABSIZE 1000 struct node { /* these are stored in the table */ char *string; int length; }; struct node table[TABSIZE]; /* table to be searched */ . . . { struct node *node_ptr, node; int node_compare( ); /* routine to compare 2 nodes */ char str_space[20]; /* space to read string into */ . . . node.string = str_space; while (scanf("%s", node.string) != \s-1EOF\s+1) { node_ptr = (struct node *)bsearch((void *)(&node), (void *)table, \s-1TABSIZE\s+1, sizeof(struct node), node_compare); if (node_ptr != \s-1NULL\s+1) { (void)printf("string = %20s, length = %d\en", node_ptr->string, node_ptr->length); } else { (void)printf("not found: %s\en", node.string); } } } /* This routine compares two nodes based on an alphabetical ordering of the string field. */ int node_compare(node1, node2) struct node *node1, *node2; { return strcmp(node1->string, node2->string); } .ft .ps .fi .RE .SH WARNINGS If the table being searched contains two or more entries that match the selection criteria, a random entry is returned by .C bsearch() as determined by the search algorithm. .SH SEE ALSO hsearch(3C), lsearch(3C), qsort(3C), tsearch(3C). .SH STANDARDS CONFORMANCE .CR bsearch() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4bsearch()\fP \- binary search routine for sorted tables@@@\f3bsearch(3C)\f1 .\" index@binary search routine for sorted tables@@@\f3bsearch(3C)\f1 .\" index@routine for sorted tables, binary search@@@\f3bsearch(3C)\f1 .\" index@search routine, binary, for sorted tables@@@\f3bsearch(3C)\f1 .\" index@sorted tables, binary search routine for@@@\f3bsearch(3C)\f1 .\" index@tables, binary search routine for sorted@@@\f3bsearch(3C)\f1 .\" .\" toc@\f3bsearch(3C)\f1:\0\0\f4bsearch()\fP@@@binary search a sorted table .\" .\" fileset_database@bsearch.3c PROGRAMING-MAN .\" $Header: nl_tools_16.3x,v 72.2 94/11/30 15:24:00 ssa Exp $ .TA n .TH nl_tools_16 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl_tools_16: ADVANCE(), byte_status(), BYTE_STATUS(), CHARADV(), CHARAT(), c_colwidth(), C_COLWIDTH(), firstof2(), FIRSTof2(), secof2(), SECof2(), WCHAR(), WCHARADV() \- tools to process 16-bit characters .SH SYNOPSIS .C "#include " .PP .C "int firstof2(int c);" .PP .C "int secof2(int c);" .PP .C "int byte_status(int c, int laststatus);" .PP .C int c_colwidth(int c); .PP .C "int FIRSTof2(int c);" .PP .C "int SECof2(int c);" .PP .C "int BYTE_STATUS(int c, int laststatus);" .PP .C "int C_COLWIDTH(int c);" .PP .C "int CHARAT(const char *p);" .PP .C "int ADVANCE(const char *p);" .PP .C "int CHARADV(const char *p);" .PP .C "int WCHAR(wchar_t wc, char *p);" .PP .C "int WCHARADV(wchar_t wc, char *p);" .PP .C "void PCHAR(int c, char *p);" .PP .C "void PCHARADV(int c, char *p);" .SS Remarks All interfaces listed above whose names begin with a capital letter are implemented as macros; the others are functions. .PP These macros and functions are obsolete. See WARNINGS. .SH DESCRIPTION The following macros and functions perform their operations based upon the loaded NLS environment (see .IR setlocale (3C)). .TP 20 .CR FIRSTof2() Takes a byte and returns a nonzero value if it can be the first byte of a two-byte character according to the NLS environment loaded, and zero if it cannot. .TP .CR SECof2() Takes a byte and returns a nonzero value if it can be the second byte of a two-byte character according to the loaded NLS environment, and zero if it cannot. .TP .CR BYTE_STATUS() Returns one of the following values based on the value of the current byte in .I c and the status of the previous byte interpreted in .I laststatus as returned by the last call to .CR BYTE_STATUS() . These are the status values as defined in .CR : .RS .RS .TP 15 .CR ONEBYTE Single-byte character .PD 0 .TP .CR SECOF2 Second byte of two-byte character .TP .CR FIRSTOF2 First byte of two-byte character .RE .RE .PD .IP To validate a two-byte character, both the first and second bytes must be valid. If the value of .I laststatus is .CR FIRSTOF2 but .CR SECof2( c ) returns false, .CI BYTE_STATUS( c , \ laststatus ) returns .CR ONEBYTE . .TP .CR C_COLWIDTH() Takes a byte which is assumed to be either a one-byte character or the first byte of a two-byte character, and returns the number of columns the character would occupy on a terminal display. .IP For the macros .CR BYTE_STATUS() , .CR C_COLWIDTH() , .CR FIRSTof2() , and .CR SEC0of2() , results are undefined for values of .I c less than \(mi1 (EOF) or greater than 255. .TP .CR CHARAT() Takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case, .CR CHARAT() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p . .TP .CR ADVANCE() Advances its pointer argument by the byte width of the character it is pointing at (either one or two bytes). .TP .CR CHARADV() Combines the functions of .CR CHARAT() and .CR ADVANCE() in a single macro. It takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case .CR CHARADV() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p , and advances .I p beyond the last byte of the character. .TP .CR WCHAR() Converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p . .CR WCHAR() returns the .CR wchar_t value .IR wc . .TP .CR WCHARADV() Combines the functions of .CR WCHAR() and .CR ADVANCE() in a single macro. It converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p , then advances .I p past the last byte. .CR WCHARADV() returns the .CR wchar_t value .IR wc . .TP .CR firstof2() .PD 0 .TP .CR secof2() .TP .CR byte_status() .TP .CR c_colwidth() .PD Subroutine versions of the corresponding macros. These functions can be called from languages other than C. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of single and/or multibyte characters. .SH WARNINGS The HP proprietary functions and macros described in this manual entry are .BR OBSOLETE . They are not portable to other vendor's systems, and will not be provided in future HP-UX releases. .PP For maximum portability, use the routines documented in the .IR multibyte (3C) manual entry for multibyte character processing. .PP Other macros listed in this manual entry cannot be used as the first argument to .CR WCHAR() or .CR WCHARADV() . For example, .IP .C "*t++ = *f++" .PP cannot be replaced by .IP .C "WCHARADV(CHARADV (f),t)" .PP Instead, use a method such as .IP .CR "int c; " ...\& " c = CHARADV (f)," .CR "WCHARADV (c,t)" .PP .CR WCHAR() and .CR WCHARADV() may produce a "null effect" warning from .IR lint (1) if not used as part of another expression or as part of a statement. This does not affect the functionality of either macro. .PP Note that .CR WCHAR() and .CR WCHARADV() are not "replace_char" macros. They do not prevent the second byte of a two-byte character from being left dangling if .CR WCHAR() or .CR WCHARADV() overwrite the first byte of the two-byte character with a single-byte character. .PP .CR CHARAT() , .CR ADVANCE() , and .CR CHARADV() do not examine the byte following the location pointed to by the argument to verify its validity as a .CR SECof2 byte. .SH AUTHOR .CR nl_tools_16() was developed by HP. .SH SEE ALSO setlocale(3C), multibyte(3C), wconv(3X), wctype(3X), hpnls(5). .\" .\" index@\f4ADVANCE()\f1 \- advance pointer to next 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARADV()\f1 \- get character and advance pointer to next character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARAT()\f1 \- get value of 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHAR()\f1, \- put 8- or 16-bit character in memory@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHARADV()\f1, \- put character in memory and advance pointer@@@\f3nl_tools_16(3X)\f1 .\" index@\f4byte_status()\f1, \f4BYTE_STATUS()\f1 \- test for valid 1- or 2-byte character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4firstof2()\f1, \f4FIRSTof2()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4secof2()\f1, \f4SECof2()\f1 \- test for valid second byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f1characters, tools to process 16-bit@@@\f3nl_tools_16(3X)\f1 .\" index@\f1process 16-bit characters, tools to@@@\f3nl_tools_16(3X)\f1 .\" index@\f1sixteen-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f116-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f1tools to process 16-bit characters@@@\f3nl_tools_16(3X)\f1 .\" .\" links@nl_tools_16.3x ADVANCE.3x .\" links@nl_tools_16.3x BYTE_STATUS.3x .\" links@nl_tools_16.3x CHARADV.3x .\" links@nl_tools_16.3x CHARAT.3x .\" links@nl_tools_16.3x FIRSTof2.3x .\" links@nl_tools_16.3x SECof2.3x .\" links@nl_tools_16.3x WCHAR.3x .\" links@nl_tools_16.3x WCHARADV.3x .\" links@nl_tools_16.3x byte_status.3x .\" links@nl_tools_16.3x c_colwidth.3x .\" links@nl_tools_16.3x firstof2.3x .\" links@nl_tools_16.3x secof2.3x .\" .\" toc@\f3nl_tools_16(3X)\f1:\0\0\f4ADVANCE()\f1, \f4byte_status()\f1, \f4BYTE_STATUS()\f1, \f4CHARADV()\f1,\n\f4CHARAT()\f1, \f4C_COLWIDTH()\f1, \f4c_colwidth()\f1, \f4firstof2()\f1, \f4FIRSTof2()\f1,\n\f4secof2()\f1, \f4SECof2()\f1, \f4WCHAR()\f1, \f4WCHARADV()\f1@@@tools to process 16-bit characters .\" toc@\f4ADVANCE()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4byte_status()\f1, \f4BYTE_STATUS()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARAT()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4firstof2()\f1, \f4FIRSTof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4secof2()\f1, \f4SECof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHAR()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" $Header: byteorder.3n,v 78.1 96/03/15 15:46:29 ssa Exp $ .TA b .TH byteorder 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME htonl(\|), htons(\|), ntohl(\|), ntohs(\|) \- convert values between host and network byte order .SH SYNOPSIS .nf .PP .C #include .PP .C _XOPEN_SOURCE_EXTENDED only .C #include .PP .C "unsigned long htonl(unsigned long hostlong);" .PP .C "unsigned short htons(unsigned short hostshort);" .PP .C "unsigned long ntohl(unsigned long netlong);" .PP .C "unsigned short ntohs(unsigned short netshort);" .fi .SH DESCRIPTION These routines convert 16- and 32-bit quantities between network byte order and host byte order. On HP-UX systems, network and host byte orders are identical, so these routines are defined as null macros in the include file .RC < netinet/in.h >. If _XOPEN_SOURCE_EXTENDED is defined then these routines are defined in the include file .RC < arpa/inet.h>. .PP These routines are most often used in conjunction with Internet addresses and ports as returned by .C gethostent() and .C getservent() (see .IR gethostent (3N) and .IR getservent (3N)). Use these routines to write portable programs. .SH AUTHOR .C byteorder() was developed by the University of California, Berkeley. .SH SEE ALSO gethostent(3N), getservent(3N). .SH STANDARDS CONFORMANCE .CR byteorder() ": XPG4" .\" .\" index@\f4htonl()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4htons()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4ntohl()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4ntohs()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1values, convert between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1host and network byte order, convert values between@@@\f3byteorder(3N)\f1 .\" index@\f1network and host byte order, convert values between@@@\f3byteorder(3N)\f1 .\" index@\f1byte order, network and host, convert values between@@@\f3byteorder(3N)\f1 .\" .\" toc@\f3byteorder(3N)\f1:\0\0\f4htonl()\f1, \f4htons()\f1, \f4ntohl()\f1, \f4ntohs()\f1@@@convert values between host and network byte order .\" toc@\f4htonl()\f1, \f4htons()\f1:\0\0convert values from host to network byte order@@@see \f3byteorder(3N)\f1 .\" toc@\f4ntohl()\f1, \f4ntohs()\f1:\0\0convert values from network to host byte order@@@see \f3byteorder(3N)\f1 .\" .\" links@byteorder.3n htonl.3n .\" links@byteorder.3n htons.3n .\" links@byteorder.3n ntohl.3n .\" links@byteorder.3n ntohs.3n .\" $Header: memory.3c,v 74.1 95/03/23 17:24:13 ssa Exp $ .TA m .TH memory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME memccpy(\|), memchr(\|), memcmp(\|), memcpy(\|), memmove(\|), memset(\|), bcopy(\|), bcmp(\|), bzero(\|), ffs(\|) \- memory operations .SH SYNOPSIS .C "#include " .PP .C "void *memccpy(void *s1, const void *s2, int c, size_t n);" .PP .C "void *memchr(const void *s, int c, size_t n);" .PP .C "int memcmp(const void *s1, const void *s2, size_t n);" .PP .C "void *memcpy(void *s1, const void *s2, size_t n);" .PP .C "void *memmove(void *s1, const void *s2, size_t n);" .PP .C "void *memset(void *s, int c, size_t n);" .PP .C "#include " .PP .C "int bcmp(const void *s1, const void *s2, size_t n);" .PP .C "void bcopy(const void *s1, void *s2, size_t n);" .PP .C "void bzero(char *s, int n);" .PP .C "int ffs(int i);" .SS Remarks: .CR bcmp() , .CR bcopy() , .CR bzero() , .CR ffs() , and .RC < strings.h > are provided solely for portability of .SM BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .CR memcmp() , .CR memmove() , and .CR memset() , respectively. .C ffs() has no portable equivalent. .SH DESCRIPTION These functions operate as efficiently as possible on memory areas (arrays of bytes bounded by a count, not terminated by a null byte). They do not check for the overflow of any receiving memory area. .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RC < string.h > header file. .TP 15 .C memccpy() Copy bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 , stopping after the first occurrence of byte .I c has been copied, or after .I n bytes have been copied, whichever comes first. If copying takes place between objects that overlap, the behavior is undefined. .C memccpy() returns a pointer to the bvyte after the copy of .I c in .IR s1 , or a .SM NULL pointer if .I c was not found in the first .I n bytes of .IR s2 . .TP .C memchr() Locate the first occurrence of .I c (converted to an .CR "unsigned char" ) in the initial .I n bytes (each interpreted as .CR "unsigned char" ) of the object pointed to by .IR s . .C memchr() returns a pointer to the located byte, or a .SM NULL pointer if the byte does not occur in the object. .TP .C memcmp() Compare the first .I n bytes of the object pointed to by .I s1 to the first .I n bytes of the object pointed to by .IR s2 . .C memcmp() returns an integer greater than, equal to, or less than zero, according to whether the object pointed to by .I s1 is greater than, equal to, or less than the object pointed to by .IR s2 . The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes (both interpreted as .CR "unsigned char" ) that differ in the objects being compared. .TP .C memcpy() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . If copying takes place between objects that overlap, the behavior is undefined. .C memcpy() returns the value of .IR s1 . .TP .C memmove() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . Copying takes place as if the .I n bytes from the object pointed to by .I s2 are first copied into a temporary array of .I n bytes that does not overlap the objects pointed to by .I s1 and .IR s2 , and then the .I n bytes from the temporary array are copied into the object pointed to by .IR s1 . .C memmove() returns the value of .IR s1 . .TP .C memset() Copy the value of .I c (converted to an .CR "unsigned char" ) into each of the first .I n bytes of the object pointed to by .IR s . .C memset() returns the value of .IR s . .TP .C bcopy() copies .I n bytes from the area pointed to by .I s1 to the area pointed to by .IR s2 . .TP .C bcmp() Compare the first .I n bytes of the area pointed to by .I s1 with the area pointed to by .IR s2 . .C bcmp() returns zero if they are identical; non-zero otherwise. Both areas are assumed to be .I n bytes in length. .TP .C bzero() Clear .I n bytes in the area pointed to by .I s by setting them to zero. .TP .C ffs() Find the first bit set (beginning with the least significant bit) and return the index of that bit. Bits are numbered starting at one. A return value of 0 indicates that .I i is zero. .SS International Code Set Support These functions support only single-byte byte code sets. .SH WARNINGS The functions defined in .RC < string.h > were previously defined in .RC < memory.h >. .SH FILES .C /usr/include/string.h .SH SEE ALSO string(3C) .SH STANDARDS CONFORMANCE .CR memccpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR memchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memmove() ": AES, SVID3, XPG4, ANSI C" .PP .CR memset() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4memcpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memccpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memchr()\f1 \- find first occurrence of byte in memory area@@@\f3memory(3C)\f1 .\" index@\f4memcmp()\f1 \- compare byte with memory contents@@@\f3memory(3C)\f1 .\" index@\f4memmove()\f1 \- move memory contents@@@\f3memory(3C)\f1 .\" index@\f4memset()\f1 \- set area in memory to contain a specified byte@@@\f3memory(3C)\f1 .\" index@\f4bcopy()\f1 \- \s-1BSD\s+1 memory copy@@@\f3memory(3C)\f1 .\" index@\f4bcmp()\f1 \- \s-1BSD\s+1 memory compare@@@\f3memory(3C)\f1 .\" index@\f4bzero()\f1 \- \s-1BSD\s+1 memory clear@@@\f3memory(3C)\f1 .\" index@\f4ffs()\f1 \- \s-1BSD\s+1 find first set bit@@@\f3memory(3C)\f1 .\" index@\f1memory operations \- copy, compare, test for contents, or set contents to value@@@\f3memory(3C)\f1 .\" index@\f1copy memory to another area@@@\f3memory(3C)\f1 .\" index@\f1test contents of memory area@@@\f3memory(3C)\f1 .\" index@\f1compare contents of memory with byte@@@\f3memory(3C)\f1 .\" index@\f1preset contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1set contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1byte, set contents of memory area to specified@@@\f3memory(3C)\f1 .\" index@\f1byte, compare memory contents with specified@@@\f3memory(3C)\f1 .\" index@\f1byte, find location of in memory@@@\f3memory(3C)\f1 .\" index@\f1location of byte in memory, find@@@\f3memory(3C)\f1 .\" .\" toc@\f3memory(3C)\f1:\0\0\f4memccpy()\f1, \f4memchr()\f1, \f4memcmp()\f1, \f4memcpy()\f1, \f4memset()\f1, \n\f4bcopy()\f1, \f4bcmp()\f1, \f4bzero()\f1, \f4ffs()\f1@@@memory operations .\" toc@\f4memccpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memchr()\f1:\0\0memory operations, locate first character@@@see \f3memory(3C)\f1 .\" toc@\f4memcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memcpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memmove()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memset()\f1:\0\0memory operations, set memory@@@see \f3memory(3C)\f1 .\" toc@\f4bcopy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bzero()\f1:\0\0memory operations, clear bytes@@@see \f3memory(3C)\f1 .\" toc@\f4ffs()\f1:\0\0memory operations, find first bit set@@@see \f3memory(3C)\f1 .\" .\" links@memory.3c memccpy.3c .\" links@memory.3c memchr.3c .\" links@memory.3c memcmp.3c .\" links@memory.3c memcpy.3c .\" links@memory.3c memmove.3c .\" links@memory.3c memset.3c .\" links@memory.3c bcopy.3c .\" links@memory.3c bcmp.3c .\" links@memory.3c bzero.3c .\" links@memory.3c ffs.3c .\" .\" $Header: nl_tools_16.3x,v 72.2 94/11/30 15:24:00 ssa Exp $ .TA n .TH nl_tools_16 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl_tools_16: ADVANCE(), byte_status(), BYTE_STATUS(), CHARADV(), CHARAT(), c_colwidth(), C_COLWIDTH(), firstof2(), FIRSTof2(), secof2(), SECof2(), WCHAR(), WCHARADV() \- tools to process 16-bit characters .SH SYNOPSIS .C "#include " .PP .C "int firstof2(int c);" .PP .C "int secof2(int c);" .PP .C "int byte_status(int c, int laststatus);" .PP .C int c_colwidth(int c); .PP .C "int FIRSTof2(int c);" .PP .C "int SECof2(int c);" .PP .C "int BYTE_STATUS(int c, int laststatus);" .PP .C "int C_COLWIDTH(int c);" .PP .C "int CHARAT(const char *p);" .PP .C "int ADVANCE(const char *p);" .PP .C "int CHARADV(const char *p);" .PP .C "int WCHAR(wchar_t wc, char *p);" .PP .C "int WCHARADV(wchar_t wc, char *p);" .PP .C "void PCHAR(int c, char *p);" .PP .C "void PCHARADV(int c, char *p);" .SS Remarks All interfaces listed above whose names begin with a capital letter are implemented as macros; the others are functions. .PP These macros and functions are obsolete. See WARNINGS. .SH DESCRIPTION The following macros and functions perform their operations based upon the loaded NLS environment (see .IR setlocale (3C)). .TP 20 .CR FIRSTof2() Takes a byte and returns a nonzero value if it can be the first byte of a two-byte character according to the NLS environment loaded, and zero if it cannot. .TP .CR SECof2() Takes a byte and returns a nonzero value if it can be the second byte of a two-byte character according to the loaded NLS environment, and zero if it cannot. .TP .CR BYTE_STATUS() Returns one of the following values based on the value of the current byte in .I c and the status of the previous byte interpreted in .I laststatus as returned by the last call to .CR BYTE_STATUS() . These are the status values as defined in .CR : .RS .RS .TP 15 .CR ONEBYTE Single-byte character .PD 0 .TP .CR SECOF2 Second byte of two-byte character .TP .CR FIRSTOF2 First byte of two-byte character .RE .RE .PD .IP To validate a two-byte character, both the first and second bytes must be valid. If the value of .I laststatus is .CR FIRSTOF2 but .CR SECof2( c ) returns false, .CI BYTE_STATUS( c , \ laststatus ) returns .CR ONEBYTE . .TP .CR C_COLWIDTH() Takes a byte which is assumed to be either a one-byte character or the first byte of a two-byte character, and returns the number of columns the character would occupy on a terminal display. .IP For the macros .CR BYTE_STATUS() , .CR C_COLWIDTH() , .CR FIRSTof2() , and .CR SEC0of2() , results are undefined for values of .I c less than \(mi1 (EOF) or greater than 255. .TP .CR CHARAT() Takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case, .CR CHARAT() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p . .TP .CR ADVANCE() Advances its pointer argument by the byte width of the character it is pointing at (either one or two bytes). .TP .CR CHARADV() Combines the functions of .CR CHARAT() and .CR ADVANCE() in a single macro. It takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case .CR CHARADV() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p , and advances .I p beyond the last byte of the character. .TP .CR WCHAR() Converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p . .CR WCHAR() returns the .CR wchar_t value .IR wc . .TP .CR WCHARADV() Combines the functions of .CR WCHAR() and .CR ADVANCE() in a single macro. It converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p , then advances .I p past the last byte. .CR WCHARADV() returns the .CR wchar_t value .IR wc . .TP .CR firstof2() .PD 0 .TP .CR secof2() .TP .CR byte_status() .TP .CR c_colwidth() .PD Subroutine versions of the corresponding macros. These functions can be called from languages other than C. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of single and/or multibyte characters. .SH WARNINGS The HP proprietary functions and macros described in this manual entry are .BR OBSOLETE . They are not portable to other vendor's systems, and will not be provided in future HP-UX releases. .PP For maximum portability, use the routines documented in the .IR multibyte (3C) manual entry for multibyte character processing. .PP Other macros listed in this manual entry cannot be used as the first argument to .CR WCHAR() or .CR WCHARADV() . For example, .IP .C "*t++ = *f++" .PP cannot be replaced by .IP .C "WCHARADV(CHARADV (f),t)" .PP Instead, use a method such as .IP .CR "int c; " ...\& " c = CHARADV (f)," .CR "WCHARADV (c,t)" .PP .CR WCHAR() and .CR WCHARADV() may produce a "null effect" warning from .IR lint (1) if not used as part of another expression or as part of a statement. This does not affect the functionality of either macro. .PP Note that .CR WCHAR() and .CR WCHARADV() are not "replace_char" macros. They do not prevent the second byte of a two-byte character from being left dangling if .CR WCHAR() or .CR WCHARADV() overwrite the first byte of the two-byte character with a single-byte character. .PP .CR CHARAT() , .CR ADVANCE() , and .CR CHARADV() do not examine the byte following the location pointed to by the argument to verify its validity as a .CR SECof2 byte. .SH AUTHOR .CR nl_tools_16() was developed by HP. .SH SEE ALSO setlocale(3C), multibyte(3C), wconv(3X), wctype(3X), hpnls(5). .\" .\" index@\f4ADVANCE()\f1 \- advance pointer to next 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARADV()\f1 \- get character and advance pointer to next character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARAT()\f1 \- get value of 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHAR()\f1, \- put 8- or 16-bit character in memory@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHARADV()\f1, \- put character in memory and advance pointer@@@\f3nl_tools_16(3X)\f1 .\" index@\f4byte_status()\f1, \f4BYTE_STATUS()\f1 \- test for valid 1- or 2-byte character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4firstof2()\f1, \f4FIRSTof2()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4secof2()\f1, \f4SECof2()\f1 \- test for valid second byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f1characters, tools to process 16-bit@@@\f3nl_tools_16(3X)\f1 .\" index@\f1process 16-bit characters, tools to@@@\f3nl_tools_16(3X)\f1 .\" index@\f1sixteen-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f116-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f1tools to process 16-bit characters@@@\f3nl_tools_16(3X)\f1 .\" .\" links@nl_tools_16.3x ADVANCE.3x .\" links@nl_tools_16.3x BYTE_STATUS.3x .\" links@nl_tools_16.3x CHARADV.3x .\" links@nl_tools_16.3x CHARAT.3x .\" links@nl_tools_16.3x FIRSTof2.3x .\" links@nl_tools_16.3x SECof2.3x .\" links@nl_tools_16.3x WCHAR.3x .\" links@nl_tools_16.3x WCHARADV.3x .\" links@nl_tools_16.3x byte_status.3x .\" links@nl_tools_16.3x c_colwidth.3x .\" links@nl_tools_16.3x firstof2.3x .\" links@nl_tools_16.3x secof2.3x .\" .\" toc@\f3nl_tools_16(3X)\f1:\0\0\f4ADVANCE()\f1, \f4byte_status()\f1, \f4BYTE_STATUS()\f1, \f4CHARADV()\f1,\n\f4CHARAT()\f1, \f4C_COLWIDTH()\f1, \f4c_colwidth()\f1, \f4firstof2()\f1, \f4FIRSTof2()\f1,\n\f4secof2()\f1, \f4SECof2()\f1, \f4WCHAR()\f1, \f4WCHARADV()\f1@@@tools to process 16-bit characters .\" toc@\f4ADVANCE()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4byte_status()\f1, \f4BYTE_STATUS()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARAT()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4firstof2()\f1, \f4FIRSTof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4secof2()\f1, \f4SECof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHAR()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" $Header: hypot.3m,v 78.1 96/02/13 11:58:58 ssa Exp $ .TA h .TH hypot 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hypot(\|), cabs(\|) \- Euclidean distance function, complex absolute value .SH SYNOPSIS .C "#include " .PP .C "double hypot(double x, double y);" .PP .C "double cabs(struct {double x, y;} z);" .SH DESCRIPTION .CR hypot() and .CR cabs() return .CI sqrt( x * x\c .CI + y * y )\c , taking precautions against unwarranted overflows. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x or .I y is NaN, .CR hypot() and .CR cabs() return NaN. .PP If the correct value would overflow, .CR hypot() and .CR cabs() return .CR HUGE_VAL . .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR hypot() and .CR cabs() return zero. .SH ERRORS No errors are defined. .SH SEE ALSO sqrt(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR hypot() ": SVID3, XPG4.2" .\" .\" index@\f4hypot()\fP \- Euclidean distance function@@@\f3hypot(3M)\f1 .\" index@\f4cabs()\fP \- complex absolute value function@@@\f3hypot(3M)\f1 .\" index@math: Euclidean distance (hypotenuse) function@@@\f3hypot(3M)\f1 .\" index@math: complex absolute value function@@@\f3hypot(3M)\f1 .\" index@Euclidean distance (hypotenuse) function@@@\f3hypot(3M)\f1 .\" index@distance function, Euclidean (hypotenuse)@@@\f3hypot(3M)\f1 .\" index@complex absolute value function@@@\f3hypot(3M)\f1 .\" index@absolute value function, complex@@@\f3hypot(3M)\f1 .\" index@hypotenuse of a right triangle@@@\f3hypot(3M)\f1 .\" index@right triangle, hypotenuse of a@@@\f3hypot(3M)\f1 .\" index@triangle, right, hypotenuse of a@@@\f3hypot(3M)\f1 .\" .\" toc@\f3hypot(3M)\f1:\0\0\f4hypot()\fP, \f4cabs()\fP@@@Euclidean distance, complex absolute value function .\" toc@\f4cabs()\fP \- complex absolute value function@@@see \f3hypot(3M)\f1 .\" .\" links@hypot.3m cabs.3m .\" .\" fileset_database@hypot.3m PROGRAMING-MAN .\" $Header: calendar.3x,v 72.3 93/01/14 14:44:55 ssa Exp $ .TA c .TH calendar 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME calendar(\|) \- return the MPE calendar date .SH SYNOPSIS .C "#include " .PP .C "unsigned short calendar(void);" .SH DESCRIPTION This routine returns the calendar date in the format: .nf .sp .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|0#6#\|7#15 \&#_#_#_#_ #Year of Century##Day of Year# \&#_#_#_#_ .TE .SH RETURN VALUE An unsigned short integer containing the calendar format. .SH WARNINGS This routine is provided for compatibility with MPE, another HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described on .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C calendar() was developed by HP. .SH SEE ALSO portnls(5). .\" index@\f4calendar()\fP \- return \s-1MPE\s+1 calendar date@@@\f3calendar(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: return \s-1MPE\s+1 calendar date@@@\f3calendar(3X)\f1 .\" .\" toc@\f3calendar(3X)\f1:\0\0\f4calendar()\fP@@@return the \s-1MPE\s+1 calendar date .\" .\" fileset_database@calendar.3x PROGRAMING-MAN .\" $Header: malloc.3c,v 72.6 94/11/15 09:55:17 ssa Exp $ .TA m .TH malloc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME malloc(), free(), realloc(), calloc(), valloc(), mallopt(), mallinfo(), memorymap(), alloca() \- main memory allocator .SH SYNOPSIS .C "#include " .PP .C "void *malloc(size_t size);" .PP .C "void *calloc(size_t nelem, size_t elsize);" .PP .C "void *realloc(void *ptr, size_t size);" .PP .C "void *valloc(size_t size);" .PP .C "void free(void *ptr);" .PP .C "void memorymap(int show_stats);" .PP .C " " .PP .C "#include " .PP .C "void *alloca(size_t size);" .SH SYSTEM V SYNOPSIS .C "#include " .PP .C "char *malloc(unsigned size);" .PP .C "void free(char *ptr);" .PP .C "char *realloc(char *ptr, unsigned size);" .PP .C "char *calloc(unsigned nelem, unsigned elsize);" .PP .C "int mallopt(int cmd, int value);" .PP .C "struct mallinfo mallinfo(void);" .SS Remarks The functionality in the old .IR malloc (3X) package has been incorporated into .IR malloc (3C). The library .RC ( /usr/lib/libmalloc.a ) corresponding to the .CR -lmalloc linker option is now an empty library. Makefiles that reference this library will continue to work. Applications that used the .IR malloc (3X) package should still work properly with the new .IR malloc (3C) package. If the old versions must be used, they are provided in files .CR /usr/old/libmalloc3x.a and .CR /usr/old/libmalloc3c.o for Release 8.07 only. .SH DESCRIPTION The functions described in this manual entry provide a simple, general purpose memory allocation package: .RS .TP 17 .C malloc() Allocates space for a block of at least .I size bytes, but does not initialize the space. .TP .C calloc() Allocates space for an array of .I nelem elements, each of size .I elsize bytes, and initializes the space to zeros. Actual amount of space allocated will be at least .I nelem * elsize bytes. .TP .C realloc() Changes the size of the block pointed to by .I ptr to .I size bytes and returns a pointer to the (possibly moved) block. Existing contents are unchanged up to the lesser of the new and old sizes. If .I ptr is a NULL pointer, .CR realloc() behaves like .CR malloc() for the specified size. If .I size is zero and .I ptr is not a NULL pointer, the object it points to is freed and NULL is returned. .TP .C valloc() Allocates space for a block of at least .I size bytes starting on a boundary aligned to a multiple of the value returned by .IR sysconf(__SC_PAGESIZE) . This space is uninitialized. .TP .C free() Deallocates the space pointed to by .I ptr (a pointer to a block previously allocated by .CR malloc() , .CR realloc() , or .CR calloc() ) and makes the space available for further allocation. If .I ptr is a NULL pointer, no action occurs. .TP .C mallopt() Provides for control over the allocation algorithm and other options in the .IR malloc (3C) package. The available values for .I cmd are: .RS .RS .TP 15 .C M_MXFAST Set .IR maxfast to .IR value . The algorithm allocates all blocks below the size of .IR maxfast in large groups, then doles them out very quickly. The default value for .IR maxfast is zero. .TP .C M_NLBLKS Set .IR numlblks to .IR value . The above mentioned ``large groups'' each contain .I numlblks blocks. .I numlblks must be greater than 1. The default value for .I numlblks is .CR 100 . .TP .C M_GRAIN Set .I grain to .IR value . The sizes of all blocks smaller than .I maxfast are considered to be rounded up to the nearest multiple of .IR grain . .I grain must be greater than zero. The default value of .I grain is the smallest number of bytes that can accommodate alignment of any data type. .I value is rounded up to a multiple of the default when .I grain is set. .TP .C M_KEEP Preserve data in a freed block until the next .CR malloc() , .CR realloc() , or .CR calloc() . This option is provided only for compatibility with the old version of .CR malloc() and is not recommended. .TP .C M_BLOCK Block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option is provided for those who need to write signal handlers that allocate memory. When set, the .IR malloc (3C) routines can be called from within signal handlers (they become re-entrant). Default action is .I not to block all blockable signals. .TP .C M_UBLOCK Do not block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option cancels signal blocking initiated by the .CR M_BLOCK option. .RE .RE .IP These values are defined in the .CR header file. .IP .CR mallopt() can be called repeatedly, but must not be called after the first small block is allocated (unless .I cmd is set to .CR M_BLOCK or .CR M_UBLOCK ). .TP .C mallinfo() Provides instrumentation describing space usage, but cannot be called until the first small block is allocated. It returns the structure: .nf .IP .C "struct mallinfo {" .C " int arena; /* total space in arena */" .C " int ordblks; /* number of ordinary blocks */" .C " int smblks; /* number of small blocks */" .C " int hblkhd; /* space in holding block headers */" .C " int hblks; /* number of holding blocks */" .C " int usmblks /* space in small blocks in use */" .C " int fsmblks /* space in free small blocks */" .C " int uordblks; /* space in ordinary blocks in use */" .C " int fordblks; /* space in free ordinary blocks */" .C " int keepcost; /* space penalty if keep option is used */" .C } .fi .IP This structure is defined in the .CR header file. .RE .PP Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. .RS .TP 17 .C memorymap() Can be used to display the contents of the memory allocator. A list of addresses and block descriptions is written (using .CR printf() ) to standard output. If the value of the .I show_stats parameter is 1, statistics concerning number of blocks and sizes used will also be written. If the value is zero, only the memory map will be written. .IP The addresses and sizes displayed by .CR memorymap() may not correspond to those requested by an application. The size of a block (as viewed by the allocator) includes header information and padding to properly align the block. The address is also offset by a certain amount to accommodate the header information. .TP .C alloca() Allocates space from the stack of the caller for a block of at least .I size bytes, but does not initialize the space. The space is automatically freed when the calling routine exits. .IP Memory returned by .CR alloca() is not related to memory allocated by other memory allocation functions. Behavior of addresses returned by .CR alloca() as parameters to other memory functions is undefined. .IP The implementation of this routine is system dependent and its use is discouraged. .RE .SH RETURN VALUE Upon successful completion, .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. Otherwise, they return a NULL pointer. If .CR realloc() returns a NULL pointer, the memory pointed to by the original pointer is left intact. .PP .CR mallopt() returns zero for success and nonzero for failure. .SH DIAGNOSTICS .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a NULL pointer if there is no available memory, or if the memory managed by .CR malloc() has been detectably corrupted. This memory may become corrupted if data is stored outside the bounds of a block, or if an invalid pointer (a pointer not generated by .CR malloc() , .CR realloc() , or .CR calloc() ) is passed as an argument to .CR free() or .CR realloc() . .PP If .CR mallopt() is called after any allocation of a small block and .I cmd is not set to .CR M_BLOCK or .CR M_UBLOCK , or if .I cmd or .I value is invalid, nonzero is returned. Otherwise, it returns zero. .SH ERRORS .RS .TP 17 [ENOMEM] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to ENOMEM and return a NULL pointer when an out-of-memory condition arises. .TP [EINVAL] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to EINVAL and return a NULL pointer when the memory being managed by .CR malloc() has been detectably corrupted. .SH WARNINGS .CR malloc() functions use .CR brk() and .CR sbrk() (see .IR brk (2)) to increase the address space of a process. Therefore, an application program that uses .CR brk() or .CR sbrk() must not use them to decrease the address space, because this confuses the .CR malloc() functions. .PP .CR free() and .CR realloc() do not check their pointer argument for validity. .PP If .CR free() or .CR realloc() is passed a pointer that was not the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() , or if space assigned by an allocation function is overrun, loss of data, a memory fault, bus error, or an infinite loop may occur at that time or during any subsequent call to .CR malloc() , .CR realloc() , .CR calloc() , .CR valloc() , or .CR free() . .PP The following actions are not supported and cause undesirable effects: .RS .TP 3 \(bu Attempting to .CR free() or .CR realloc() a pointer not generated as the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() . .RE .PP The following actions are strongly discouraged and may be unsupported in a future implementation of .CR malloc() : .RS .TP 3 \(bu attempting to .CR free() the same block twice, .TP \(bu depending on unmodified contents of a block after it has been freed. .RE .PP Undocumented features of earlier memory allocators have not been duplicated. .SH COMPATIBILITY The only external difference between the old .IR malloc (3X) allocator and the .IR malloc (3C) allocator is that the old allocator would return a NULL pointer for a request of zero bytes. The .IR malloc (3C) allocator returns a valid memory address. This is not a concern for most applications. .ift .br .ift .ne 4 .PP Although the current implementation of .IR malloc (3C) allows for freeing a block twice and does not corrupt the contents of a block after it is freed (until the next call to .CR realloc() , .CR calloc() , .CR malloc() , or .CR valloc() ), support for these features may be discontinued in a future implementation of .IR malloc (3C) and should not be used. .SH SEE ALSO brk(2), errno(2). .SH STANDARDS CONFORMANCE .CR malloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR calloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR free() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mallinfo() ": SVID2, XPG2" .PP .CR mallopt() ": SVID2, SVID3, XPG2" .PP .CR realloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4malloc()\f1 \- allocate block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4free()\f1 \- release allocated block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4realloc()\f1 \- change size of allocated memory block@@@\f3malloc(3C)\f1 .\" index@\f4calloc()\f1 \- allocate memory for array@@@\f3malloc(3C)\f1 .\" index@\f4mallopt()\f1 \- control memory space allocation@@@\f3malloc(3C)\f1 .\" index@\f4mallinfo()\f1 \- display memory space usage@@@\f3malloc(3C)\f1 .\" index@\f4memorymap()\f1 \- display contents of memory allocator@@@\f3malloc(3C)\f1 .\" index@\f4alloca()\f1 \- allocate space from the stack@@@\f3malloc(3C)\f1 .\" index@\f4valloc()\f1 \- allocate space on boundary aligned to sysconf value@@@\f3malloc(3C)\f1 .\" index@\f1main memory allocator@@@\f3malloc(3C)\f1 .\" index@\f1memory allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1main memory space usage, display@@@\f3malloc(3C)\f1 .\" index@\f1main memory space allocation, control@@@\f3malloc(3C)\f1 .\" .\" toc@\f3malloc(3C)\f1:\0\0\f4alloca()\f1, \f4calloc()\f1, \f4free()\f1, \f4mallinfo()\f1,\n\f4malloc()\f1, \f4mallopt()\f1, \f4memorymap()\f1, \f4realloc()\f1, \f4valloc()\f1@@@main memory allocator\f1 .\" .\" toc@\f4free()\f1:\0\0release allocated block of main memory@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4realloc()\f1:\0\0change size of allocated memory block@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4calloc()\f1:\0\0allocate memory for array@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4valloc()\f1:\0\0allocate space on boundary aligned to sysconf value@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallopt()\f1:\0\0control memory space allocation@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallinfo()\f1:\0\0display memory space usage@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4memorymap()\f1:\0\0display contents of memory allocator@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4alloca()\f1:\0\0allocate space from the stack@@@\f1see \f3malloc(3C)\f1 .\" .\" links@malloc.3c free.3c .\" links@malloc.3c realloc.3c .\" links@malloc.3c calloc.3c .\" links@malloc.3c valloc.3c .\" links@malloc.3c mallopt.3c .\" links@malloc.3c mallinfo.3c .\" links@malloc.3c memorymap.3c .\" links@malloc.3c alloca.3c .\" $Header: can_change_color.3x,v 76.3 95/10/05 14:12:23 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH can_change_color 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME can_change_color, color_content, has_colors, init_color, init_pair, start_color, pair_content \(em color manipulation functions .SH SYNOPSIS .C "#include " .P .C "bool can_change_color(void);" .P .C "int color_content(short \f2color\fP, short *\f2red\fP, short *\f2green\fP, short *\f2blue\fP);" .P .C "int COLOR_PAIR(int \f2n\fP);" .P .C "bool has_colors(void);" .P .C "int init_color(short \f2color\fP, short \f2red\fP, short \f2green\fP, short \f2blue\fP);" .P .C "int init_pair(short \f2pair\fP, short \f2f\fP, short \f2b\fP);" .P .C "int pair_content(short \f2pair\fP, short *\f2f\fP, short *\f2b\fP);" .P .C "int PAIR_NUMBER(int \f2value\fP);" .P .C "int start_color(void);" .P .C "extern int COLOR_PAIRS;" .P .C "extern int COLORS;" .SH DESCRIPTION These functions manipulate colour on terminals that support colour. .SS "Querying Capabilities" The .Fn has_colors function indicates whether the terminal is a colour terminal. The .Fn can_change_color function indicates whether the terminal is a colour terminal on which colours can be redefined. .SS "Initialisation" The .Fn start_color function must be called in order to enable use of colours and before any colour manipulation function is called. The function initialises eight basic colours (black, blue, green, cyan, red, magenta, yellow, and white) that can be specified by the colour macros (such as COLOR_BLACK) defined in .CR . (See \f3Colour-related Macros\f1 in \f3\f1.) The initial appearance of these eight colours is not specified. .P The function also initialises two global external variables: .RS .TP 3 .C \(bu COLORS defines the number of colours that the terminal supports. (See .B "Colour Identification" below.) If COLORS is 0, the terminal does not support redefinition of colours (and .Fn can_change_colour will return FALSE). .TP .C \(bu COLOR_PAIRS defines the maximum number of colour-pairs that the terminal supports. (See .B "User-Defined Colour Pairs" below.) .RE .P The .Fn start_color function also restores the colours on the terminal to terminal-specific initial values. The initial background colour is assumed to be black for all terminals. .SS "Colour Identification" The .Fn init_color function redefines colour number \f2color\fP, on terminals that support the redefinition of colours, to have the red, green, and blue intensity components specified by \f2red\fP, \f2green\fP, and \f2blue\fP, respectively. Calling .Fn init_color also changes all occurrences of the specified colour on the screen to the new definition. .P The .Fn color_content function identifies the intensity components of colour number \f2color\f1. It stores the red, green, and blue intensity components of this colour in the addresses pointed to by \f2red\fP, \f2green\fP, and \f2blue\fP, respectively. .P For both functions, the .I color argument must be in the range from 0 to and including COLORS\|\(mi\|1. Valid intensity values range from 0 (no intensity component) up to and including 1000 (maximum intensity in that component). .SS "User-Defined Colour Pairs" Calling .Fn init_pair defines or redefines colour-pair number \f2pair\f1 to have foreground colour \f2f\f1 and background colour \f2b\f1. Calling .Fn init_pair changes any characters that were displayed in the colour pair's old definition to the new definition and refreshes the screen. .P After defining the colour pair, the macro COLOR_PAIR(\f2n\fP) returns the value of colour pair \f2n\f1. This value is the colour attribute as it would be extracted from a .CR chtype . Conversely, the macro PAIR_NUMBER(\f2value\fP) returns the colour pair number associated with the colour attribute \f2value\f1. .P The .Fn pair_content function retrieves the component colours of a colour-pair number \f2pair\f1. It stores the foreground and background colour numbers in the variables pointed to by \f2f\f1 and \f2b\fP, respectively. .P With .Fn init_pair and .Fn pair_content , the value of \f2pair\f1 must be in a range from 0 to and including COLOR_PAIRS\|\(mi\|1. (There may be an implementation-specific lower limit on the valid value of \f2pair\fP, but any such limit is at least 63.) Valid values for \f2f\f1 and \f2b\f1 are the range from 0 to and including COLORS\|\(mi\|1. .SH "RETURN VALUE" The .Fn has_colors function returns TRUE if the terminal can manipulate colors; otherwise, it returns FALSE. .P The .Fn can_change_color function returns TRUE if the terminal supports colors and can change their definitions; otherwise, it returns FALSE. .P Upon successful completion, the other functions return OK; otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" To use these functions, .Fn start_color must be called, usually right after .CR initscr() . .P The .Fn can_change_color and .Fn has_colors functions facilitate writing terminal-independent programs. For example, a programmer can use them to decide whether to use colour or some other video attribute. .P On color terminals, a typical value of COLORS is 8 and the macros such as COLOR_BLACK return a value within the range from 0 to and including 7. However, applications cannot rely on this to be true. .SH "SEE ALSO" attroff(), delscreen(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3can_change_color(3X)\f1:\0\0\f4can_change_color()\f1, \f4color_content()\f1, \f4has_colors()\f1, \f4init_color()\f1, \n\f4init_pair()\f1, \f4start_color()\f1, \f4pair_content()\f1@@@color manipulation functions .\" toc@\f4color_content()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4has_colors()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4init_colors()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4init_pair()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4start_color()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4pair_content()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" .\" index@\f4can_change_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4color_content()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4has_colors()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4init_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4init_pair()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4start_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4pair_content()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f1color manipulation functions@@@\f3can_change_color(3X)\f1 .\" .\" links@can_change_color.3x color_content.3x .\" links@can_change_color.3x has_colors.3x .\" links@can_change_color.3x init_color.3x .\" links@can_change_color.3x init_pair.3x .\" links@can_change_color.3x start_color.3x .\" links@can_change_color.3x pair_content.3x .\" .\" fileset_database@can_change_color.3x CURS-ENG-A-MAN .\" $Header: catopen.3c,v 72.6 94/11/14 13:04:49 ssa Exp $ .TA c .TH catopen 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME catopen(\|), catclose(\|) \- open and close a message catalog for reading .SH SYNOPSIS .C "#include " .PP .C "nl_catd catopen(const char *name, int oflag);" .PP .C "int catclose(nl_catd catd);" .SH DESCRIPTION The .CR catopen() function opens a message catalog and returns a catalog descriptor. The .CR name specifies the name of the message catalog being opened. A .CR name containing a slash .RC ( / ) specifies a path name for the message catalog. Otherwise, the environment variable .CR NLSPATH is used (see .IR environ (5)). If .CR NLSPATH specifies more than one path, .CR catopen() returns the catalog descriptor for the first path on which it is able to successfully open the specified message catalog. If .CR NLSPATH does not exist in the environment, or if a message catalog cannot be opened for any .CR NLSPATH -specified path, .CR catopen() uses a system-wide default path. The default is affected by .CR LC_MESSAGES if the value of .CR oflag is .CR NL_CAT_LOCALE . If the value of .CR oflag is zero, the default is affected by the environment variable .CR LANG . See .IR environ (5) for details. .PP A message catalog descriptor remains valid in a process until the process closes it, or until a successful call to one of the .CR exec() functions. A change in the setting of the .CR LC_MESSAGES category may invalidate existing open catalogs. .PP If a file descriptor is used to implement message catalog descriptors, the .CR FD_CLOEXEC flag will be set. .PP If .CR oflag is zero, the .CR LANG environment variable is used to locate the catalog. If .CR oflag is .CR NL_CAT_LOCALE , the .CR LC_MESSAGES category is used to locate the message catalog only if a successful call to .CR setlocale() has been made prior to the call to .CR catopen() . The result of setting .CR oflag to any other value is undefined. .PP The .CR catclose() function closes the message catalog .CR catd , a message catalog descriptor returned from an earlier successful call to .CR catopen() . .SH RETURN VALUE Upon success, .CR catopen() returns a message catalog descriptor. Otherwise, .CR catopen() returns a value of .RI ( nl_catd )\|\(mi\|1 and sets .CR errno to indicate the error. .PP Upon success, .CR catclose() returns zero. Otherwise, .CR catclose() returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS .CR catopen() fails without opening a message catalog, and sets .CR errno for the last path attempted under any of the following conditions: .RS .TP 23 [EACCES] A component of the path prefix denies search permission, or read permission is denied for the named file. .TP [EMFILE] The maximum number of file descriptors allowed are currently open. .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENFILE] The system file table is full. .TP [ENOENT] The named catalog does not exist or the path is null. .TP [ENOTDIR] A component of the path prefix is not a directory. .\" .TP .\" .SM [EINVAL] .\" The .\" .I name .\" argument contains .\" .CR %N . .RE .PP .CR catgets() can be used to provide default messages when called following a failed .CR catopen() (see .IR catgets (3C)). .CR catgets() returns its .CR def_str parameter if it is passed an invalid catalog descriptor. .PP .CR catclose() fails if the following is true: .RS .TP 23 [EBADF] .CR catd is not a valid open message catalog descriptor. .RE .SH WARNINGS When using .CR NLSPATH , .CR catopen() does not provide a default value for .CR LANG . .\" .CR LC_MESSAGES . .SH AUTHOR .CR catopen() and .CR catclose() were developed by HP. .SH FILES .TP 30 .CR /usr/include/nl_types.h .TP .CR /usr/lib/nls/msg Message catalog default path for core HP-UX products only. .SH SEE ALSO catgets(3C), setlocale(3C), environ(5). .SH STANDARDS CONFORMANCE .CR catopen() ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR catclose() ": AES, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4catopen()\f1 \- open NLS message catalog for reading@@@\f3catopen(3C)\f1 .\" index@\f4catclose()\f1 \- close NLS message catalog for reading@@@\f3catopen(3C)\f1 .\" index@\f1open or close NLS message catalog for reading@@@\f3catopen(3C)\f1 .\" index@\f1close or open NLS message catalog for reading@@@\f3catopen(3C)\f1 .\" index@\f1message catalog for reading, close or open NLS@@@\f3catopen(3C)\f1 .\" index@\f1catalog for reading, close or open NLS message@@@\f3catopen(3C)\f1 .\" index@\f1NLS message catalog, open or close for reading@@@\f3catopen(3C)\f1 .\" index@\f1NLS, open or close message catalog for reading@@@\f3catopen(3C)\f1 .\" .\" toc@\f3catopen(3C)\f1:\0\0\f4catopen()\f1, \f4catclose()\f1@@@open or close NLS message catalog for reading\f1 .\" toc@\f4catclose()\f1:\0\0close NLS message catalog for reading@@@\f1see \f3catopen(3C)\f1 .\" .\" links@catopen.3c catclose.3c .\" $Header: catgets.3c,v 72.5 94/11/14 13:04:32 ssa Exp $ .TA c .TH catgets 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME catgets(\|) \- get a program message .SH SYNOPSIS .C "#include " .PP .C "char *catgets(" .PD 0 .nf .IP .C "nl_catd catd," .C "int set_num," .C "int msg_num," .C "const char *def_str" .PP .C ");" .PD .fi .SH DESCRIPTION The .CR catgets() function reads message .CR msg_num in set .CR set_num from the message catalog identified by .CR catd , a catalog descriptor returned from a previous call to .CR catopen() (see .IR catopen (3C)). If the call fails, .CR def_str points to a default message string returned by .CR catgets() . .PP A message longer than .CR NL_TEXTMAX bytes is truncated. The returned message string is always terminated with a null byte. .CR NL_TEXTMAX is defined in .RC < limits.h >. .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE If the call is successful, .CR catgets() returns a pointer to an internal buffer area containing the null-terminated message string. If the call is unsuccessful, .CR catgets() returns a pointer to .CR def_str . .SH ERRORS .CR catgets() fails and sets .CR errno under any of the following conditions: .RS .TP 12 .SM [EBADF] .CR catd is not a valid catalog descriptor. .TP .SM [EINTR] A signal was caught during the .IR read (2) system call. .TP .SM [EINVAL] The message catalog identified by .CR catd is corrupted. .TP .SM [ENOMSG] The message identified by .CR set_num or .CR msg_num is not in the message catalog. .TP .SM [ERANGE] A message longer than .CR NL_TEXTMAX bytes was truncated. .RE .SH WARNINGS The .CR catgets() function returns a pointer to a static area that is overwritten on each call. .SH AUTHOR .CR catgets() was developed by HP. .SH FILES .CR /usr/include/nl_types.h .SH SEE ALSO dumpmsg(1), gencat(1), catclose(3C), catopen(3C). .SH STANDARDS CONFORMANCE .CR catgets() ": AES, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4catgets()\f1 \- get an \s-1NLS\s+1 program message@@@\f3catgets(3C)\f1 .\" index@\f1get, \s-1NLS\s+1 program message@@@\f3catgets(3C)\f1 .\" index@\f1\s-1NLS\s+1, get an \s-1NLS\s+1 program message@@@\f3catgets(3C)\f1 .\" index@\f1program message, get an \s-1NLS\s+1@@@\f3catgets(3C)\f1 .\" index@\f1message, \s-1NLS\s+1 program, get an@@@\f3catgets(3C)\f1 .\" .\" toc@\f3catgets(3C)\f1:\0\0\f4catgets()\f1@@@get a program message\f1 .\" .\" $Header: catopen.3c,v 72.6 94/11/14 13:04:49 ssa Exp $ .TA c .TH catopen 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME catopen(\|), catclose(\|) \- open and close a message catalog for reading .SH SYNOPSIS .C "#include " .PP .C "nl_catd catopen(const char *name, int oflag);" .PP .C "int catclose(nl_catd catd);" .SH DESCRIPTION The .CR catopen() function opens a message catalog and returns a catalog descriptor. The .CR name specifies the name of the message catalog being opened. A .CR name containing a slash .RC ( / ) specifies a path name for the message catalog. Otherwise, the environment variable .CR NLSPATH is used (see .IR environ (5)). If .CR NLSPATH specifies more than one path, .CR catopen() returns the catalog descriptor for the first path on which it is able to successfully open the specified message catalog. If .CR NLSPATH does not exist in the environment, or if a message catalog cannot be opened for any .CR NLSPATH -specified path, .CR catopen() uses a system-wide default path. The default is affected by .CR LC_MESSAGES if the value of .CR oflag is .CR NL_CAT_LOCALE . If the value of .CR oflag is zero, the default is affected by the environment variable .CR LANG . See .IR environ (5) for details. .PP A message catalog descriptor remains valid in a process until the process closes it, or until a successful call to one of the .CR exec() functions. A change in the setting of the .CR LC_MESSAGES category may invalidate existing open catalogs. .PP If a file descriptor is used to implement message catalog descriptors, the .CR FD_CLOEXEC flag will be set. .PP If .CR oflag is zero, the .CR LANG environment variable is used to locate the catalog. If .CR oflag is .CR NL_CAT_LOCALE , the .CR LC_MESSAGES category is used to locate the message catalog only if a successful call to .CR setlocale() has been made prior to the call to .CR catopen() . The result of setting .CR oflag to any other value is undefined. .PP The .CR catclose() function closes the message catalog .CR catd , a message catalog descriptor returned from an earlier successful call to .CR catopen() . .SH RETURN VALUE Upon success, .CR catopen() returns a message catalog descriptor. Otherwise, .CR catopen() returns a value of .RI ( nl_catd )\|\(mi\|1 and sets .CR errno to indicate the error. .PP Upon success, .CR catclose() returns zero. Otherwise, .CR catclose() returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS .CR catopen() fails without opening a message catalog, and sets .CR errno for the last path attempted under any of the following conditions: .RS .TP 23 [EACCES] A component of the path prefix denies search permission, or read permission is denied for the named file. .TP [EMFILE] The maximum number of file descriptors allowed are currently open. .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENFILE] The system file table is full. .TP [ENOENT] The named catalog does not exist or the path is null. .TP [ENOTDIR] A component of the path prefix is not a directory. .\" .TP .\" .SM [EINVAL] .\" The .\" .I name .\" argument contains .\" .CR %N . .RE .PP .CR catgets() can be used to provide default messages when called following a failed .CR catopen() (see .IR catgets (3C)). .CR catgets() returns its .CR def_str parameter if it is passed an invalid catalog descriptor. .PP .CR catclose() fails if the following is true: .RS .TP 23 [EBADF] .CR catd is not a valid open message catalog descriptor. .RE .SH WARNINGS When using .CR NLSPATH , .CR catopen() does not provide a default value for .CR LANG . .\" .CR LC_MESSAGES . .SH AUTHOR .CR catopen() and .CR catclose() were developed by HP. .SH FILES .TP 30 .CR /usr/include/nl_types.h .TP .CR /usr/lib/nls/msg Message catalog default path for core HP-UX products only. .SH SEE ALSO catgets(3C), setlocale(3C), environ(5). .SH STANDARDS CONFORMANCE .CR catopen() ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR catclose() ": AES, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4catopen()\f1 \- open NLS message catalog for reading@@@\f3catopen(3C)\f1 .\" index@\f4catclose()\f1 \- close NLS message catalog for reading@@@\f3catopen(3C)\f1 .\" index@\f1open or close NLS message catalog for reading@@@\f3catopen(3C)\f1 .\" index@\f1close or open NLS message catalog for reading@@@\f3catopen(3C)\f1 .\" index@\f1message catalog for reading, close or open NLS@@@\f3catopen(3C)\f1 .\" index@\f1catalog for reading, close or open NLS message@@@\f3catopen(3C)\f1 .\" index@\f1NLS message catalog, open or close for reading@@@\f3catopen(3C)\f1 .\" index@\f1NLS, open or close message catalog for reading@@@\f3catopen(3C)\f1 .\" .\" toc@\f3catopen(3C)\f1:\0\0\f4catopen()\f1, \f4catclose()\f1@@@open or close NLS message catalog for reading\f1 .\" toc@\f4catclose()\f1:\0\0close NLS message catalog for reading@@@\f1see \f3catopen(3C)\f1 .\" .\" links@catopen.3c catclose.3c .\" $Header: cbreak.3x,v 76.2 95/07/31 17:13:10 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH cbreak 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cbreak, nocbreak, noraw, raw \(em input mode control functions .SH SYNOPSIS .C "#include " .P .C "int cbreak(void);" .P .C "int nocbreak(void);" .P .C "int noraw(void);" .P .C "int raw(void);" .SH DESCRIPTION The .Fn cbreak function sets the input mode for the current terminal to \f2cbreak\f1 mode and overrides a call to .CR raw() . .P The .Fn nocbreak function sets the input mode for the current terminal to Cooked Mode without changing the state of ISIG and IXON. .P The .Fn noraw function sets the input mode for the current terminal to Cooked Mode and sets the ISIG and IXON flags. .P The .Fn raw function sets the input mode for the current terminal to Raw Mode. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" If the application is not certain what the input mode of the process was at the time it called .Fn initscr , it should use these functions to specify the desired input mode. .SH "SEE ALSO" \f3Input Mode\f1 in curses_intro, , .br \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Chapter 9, \f3General Terminal Interface\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn raw and .Fn noraw functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The argument list for all these functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3cbreak(3X)\f1:\0\0\f4cbreak()\f1, \f4nocbreak()\f1, \f4noraw()\f1, \f4raw()\f1@@@input mode control functions .\" toc@\f4nocbreak()\f1: input mode control functions@@@see \f3cbreak(3X)\f1 .\" toc@\f4raw()\f1: input mode control functions@@@see \f3cbreak(3X)\f1 .\" toc@\f4noraw()\f1: input mode control functions@@@see \f3cbreak(3X)\f1 .\" .\" index@\f4cbreak()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f4nocbreak()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f4raw()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f4noraw()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f1input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f1control functions, input mode@@@\f3cbreak(3X)\f1 .\" index@\f1functions, for input mode control@@@\f3cbreak(3X)\f1 .\" .\" links@cbreak.3x nocbreak.3x .\" links@cbreak.3x noraw.3x .\" links@cbreak.3x raw.3x .\" .\" fileset_database@cbreak.3x CURS-ENG-A-MAN .\" $Header: cbrt.3m,v 78.1 96/02/13 09:51:50 ssa Exp $ .TA c .TH cbrt 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cbrt(\|), cbrtf(\|) \- cube root functions .SH SYNOPSIS .C "#include " .PP .C "double cbrt(double x);" .PP .C "float cbrtf(float x);" .SH DESCRIPTION .CR cbrt() returns the cube root of .IR x . .PP .CR cbrtf() is a .CR float version of .CR cbrt() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR cbrtf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR cbrt() .ift returns \(+-INFINITY. .ifn returns +\-INFINITY. .PP If .I x is NaN, .CR cbrt() returns NaN. .SH ERRORS No errors are defined. .SH SEE ALSO exp(3M), log(3M), pow(3M), sqrt(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR cbrt() ": SVID3, XPG4.2" .\" .\" index@\f4cbrt()\f1, \f4cbrtf()\f1 \- cube root functions@@@\f3cbrt(3M)\f1 .\" index@\f4cbrtf()\f1, \f4cbrt()\f1 \- cube root functions@@@\f3cbrt(3M)\f1 .\" index@\f1math: cube root functions@@@\f3cbrt(3M)\f1 .\" index@\f1cube root functions@@@\f3cbrt(3M)\f1 .\" .\" toc@\f3cbrt(3M)\f1:\0\0\f4cbrt()\f1, \f4cbrtf()\f1@@@cube root functions .\" toc@\f4cbrtf()\f1:\0\0cube root function (float version)@@@see \f3cbrt(3M)\f1 .\" .\" links@cbrt.3m cbrtf.3m .\" .\" fileset_database@cbrt.3m PROGRAMING-MAN .\" $Header: cbrt.3m,v 78.1 96/02/13 09:51:50 ssa Exp $ .TA c .TH cbrt 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cbrt(\|), cbrtf(\|) \- cube root functions .SH SYNOPSIS .C "#include " .PP .C "double cbrt(double x);" .PP .C "float cbrtf(float x);" .SH DESCRIPTION .CR cbrt() returns the cube root of .IR x . .PP .CR cbrtf() is a .CR float version of .CR cbrt() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR cbrtf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR cbrt() .ift returns \(+-INFINITY. .ifn returns +\-INFINITY. .PP If .I x is NaN, .CR cbrt() returns NaN. .SH ERRORS No errors are defined. .SH SEE ALSO exp(3M), log(3M), pow(3M), sqrt(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR cbrt() ": SVID3, XPG4.2" .\" .\" index@\f4cbrt()\f1, \f4cbrtf()\f1 \- cube root functions@@@\f3cbrt(3M)\f1 .\" index@\f4cbrtf()\f1, \f4cbrt()\f1 \- cube root functions@@@\f3cbrt(3M)\f1 .\" index@\f1math: cube root functions@@@\f3cbrt(3M)\f1 .\" index@\f1cube root functions@@@\f3cbrt(3M)\f1 .\" .\" toc@\f3cbrt(3M)\f1:\0\0\f4cbrt()\f1, \f4cbrtf()\f1@@@cube root functions .\" toc@\f4cbrtf()\f1:\0\0cube root function (float version)@@@see \f3cbrt(3M)\f1 .\" .\" links@cbrt.3m cbrtf.3m .\" .\" fileset_database@cbrt.3m PROGRAMING-MAN .\" $Header: ceil.3m,v 78.1 96/02/13 09:52:25 ssa Exp $ .TA c .TH ceil 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ceil(\|) \- ceiling function .SH SYNOPSIS .C "#include " .PP .C "double ceil(double x);" .SH DESCRIPTION .CR ceil() returns the smallest integer (represented as a double-precision number) not less than .IR x . .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is .ift \(+-INFINITY or \(+-zero, .ifn +\-INFINITY or +\-zero, .CR ceil() returns .IR x . .PP If .I x is NaN, .CR ceil() returns NaN. .PP If the correct value would overflow, .CR ceil() returns .CR HUGE_VAL and sets .CR errno to [ERANGE]. .SH ERRORS If .CR ceil() fails, .CR errno is set to the following value. .RS .TP 20 [ERANGE] The correct value would overflow. .RE .SH SEE ALSO floor(3M), fmod(3M), fabs(3M), rint(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR ceil() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4ceil()\fP \- ceiling function@@@\f3ceil(3M)\f1 .\" index@math: ceiling function@@@\f3ceil(3M)\f1 .\" index@ceiling function@@@\f3ceil(3M)\f1 .\" .\" toc@\f3ceil(3M)\f1:\0\0\f4ceil()\fP@@@ceiling function .\" .\" .\" fileset_database@ceil.3m PROGRAMING-MAN .\" $Header: cfspeed.3c,v 72.4 94/11/14 13:05:47 ssa Exp $ .TA c .TH cfspeed 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cfgetospeed(\|), cfsetospeed(\|), cfgetispeed(\|), cfsetispeed(\|) \- tty baud rate functions .SH SYNOPSIS .C "#include " .PP .C "speed_t cfgetospeed(const struct termios *termios_p);" .PP .C "int cfsetospeed(struct termios *termios_p, speed_t speed);" .PP .C "speed_t cfgetispeed(const struct termios *termios_p);" .PP .C "int cfsetispeed(struct termios *termios_p, speed_t speed);" .SH DESCRIPTION These functions set and get the input and output speed codes in the .I termios structure referenced by .IR termios_p . The .I termios structure contains these speed codes representing input and output baud rates as well as other terminal related parameters. Setting the parameters on a terminal file does not become effective until .C tcsetattr() is successfully called. .RS .TP 20 .C cfgetospeed() returns the output speed code from the .I termios structure referenced by .IR termios_p . .TP .C cfsetospeed() sets the output speed code in the .I termios structure referenced by .I termios_p to .IR speed . The speed code for a baud rate of zero, .CR B0 , is used to terminate the connection. If .C B0 is specified, the modem control lines are no longer asserted, which normally disconnects the line. .TP .C cfgetispeed() returns the input speed code from the .I termios structure referenced by .IR termios_p . .TP .C cfsetispeed() sets the input speed code in the .I termios structure referenced by .I termios_p to .IR speed . .RE .SH RETURN VALUE .C cfgetospeed() returns the output speed code from the .I termios structure referenced by .IR termios_p . .PP .C cfgetispeed() returns the input speed code from the .I termios structure referenced by .IR termios_p . .PP .C cfsetispeed() and .C cfsetospeed() return zero upon successful completion. Otherwise, they return \-1 and set .C errno to indicate the error. .SH ERRORS .C cfsetispeed() and .C cfsetospeed() fail when the following condition is encountered: .RS .TP 15 .SM [EINVAL] The value of .I speed is outside the range of possible speed codes as specified in .RC < termios.h >. .RE .SH WARNINGS .C cfsetispeed() and .C cfsetospeed() can be used to set speed codes in the .I termios structure that are not supported by the terminal hardware. .SH SEE ALSO tcattribute(3C), termio(7). .SH STANDARDS CONFORMANCE .CR cfgetispeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfgetospeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfsetispeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfsetospeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4cfgetispeed()\fP \- get tty input baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfgetospeed()\fP \- get tty output baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfsetispeed()\fP \- set tty input baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfsetospeed()\fP \- set tty output baud rate@@@\f3cfspeed(3C)\f1 .\" index@get or set tty baud rate@@@\f3cfspeed(3C)\f1 .\" index@set or get tty baud rate@@@\f3cfspeed(3C)\f1 .\" index@tty baud rate, set or get@@@\f3cfspeed(3C)\f1 .\" index@baud rate, tty, set or get@@@\f3cfspeed(3C)\f1 .\" .\" toc@\f3cfspeed(3C)\f1:\0\0\f4cfgetospeed()\fP, \f4cfsetospeed()\fP, \f4cfgetispeed()\fP, \f4cfsetispeed()\fP@@@tty baud rate functions .\" toc@\f4cfgetispeed()\fP: get tty intput baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfgetospeed()\fP: get tty output baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfsetispeed()\fP: set tty intput baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfsetospeed()\fP: set tty output baud rate@@@see \f3cfspeed(3C)\f1 .\" .\" links@cfspeed.3c cfgetispeed.3c .\" links@cfspeed.3c cfgetospeed.3c .\" links@cfspeed.3c cfsetispeed.3c .\" links@cfspeed.3c cfsetospeed.3c .\" .\" fileset_database@cfspeed.3c PROGRAMING-MAN .\" $Header: cfspeed.3c,v 72.4 94/11/14 13:05:47 ssa Exp $ .TA c .TH cfspeed 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cfgetospeed(\|), cfsetospeed(\|), cfgetispeed(\|), cfsetispeed(\|) \- tty baud rate functions .SH SYNOPSIS .C "#include " .PP .C "speed_t cfgetospeed(const struct termios *termios_p);" .PP .C "int cfsetospeed(struct termios *termios_p, speed_t speed);" .PP .C "speed_t cfgetispeed(const struct termios *termios_p);" .PP .C "int cfsetispeed(struct termios *termios_p, speed_t speed);" .SH DESCRIPTION These functions set and get the input and output speed codes in the .I termios structure referenced by .IR termios_p . The .I termios structure contains these speed codes representing input and output baud rates as well as other terminal related parameters. Setting the parameters on a terminal file does not become effective until .C tcsetattr() is successfully called. .RS .TP 20 .C cfgetospeed() returns the output speed code from the .I termios structure referenced by .IR termios_p . .TP .C cfsetospeed() sets the output speed code in the .I termios structure referenced by .I termios_p to .IR speed . The speed code for a baud rate of zero, .CR B0 , is used to terminate the connection. If .C B0 is specified, the modem control lines are no longer asserted, which normally disconnects the line. .TP .C cfgetispeed() returns the input speed code from the .I termios structure referenced by .IR termios_p . .TP .C cfsetispeed() sets the input speed code in the .I termios structure referenced by .I termios_p to .IR speed . .RE .SH RETURN VALUE .C cfgetospeed() returns the output speed code from the .I termios structure referenced by .IR termios_p . .PP .C cfgetispeed() returns the input speed code from the .I termios structure referenced by .IR termios_p . .PP .C cfsetispeed() and .C cfsetospeed() return zero upon successful completion. Otherwise, they return \-1 and set .C errno to indicate the error. .SH ERRORS .C cfsetispeed() and .C cfsetospeed() fail when the following condition is encountered: .RS .TP 15 .SM [EINVAL] The value of .I speed is outside the range of possible speed codes as specified in .RC < termios.h >. .RE .SH WARNINGS .C cfsetispeed() and .C cfsetospeed() can be used to set speed codes in the .I termios structure that are not supported by the terminal hardware. .SH SEE ALSO tcattribute(3C), termio(7). .SH STANDARDS CONFORMANCE .CR cfgetispeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfgetospeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfsetispeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfsetospeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4cfgetispeed()\fP \- get tty input baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfgetospeed()\fP \- get tty output baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfsetispeed()\fP \- set tty input baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfsetospeed()\fP \- set tty output baud rate@@@\f3cfspeed(3C)\f1 .\" index@get or set tty baud rate@@@\f3cfspeed(3C)\f1 .\" index@set or get tty baud rate@@@\f3cfspeed(3C)\f1 .\" index@tty baud rate, set or get@@@\f3cfspeed(3C)\f1 .\" index@baud rate, tty, set or get@@@\f3cfspeed(3C)\f1 .\" .\" toc@\f3cfspeed(3C)\f1:\0\0\f4cfgetospeed()\fP, \f4cfsetospeed()\fP, \f4cfgetispeed()\fP, \f4cfsetispeed()\fP@@@tty baud rate functions .\" toc@\f4cfgetispeed()\fP: get tty intput baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfgetospeed()\fP: get tty output baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfsetispeed()\fP: set tty intput baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfsetospeed()\fP: set tty output baud rate@@@see \f3cfspeed(3C)\f1 .\" .\" links@cfspeed.3c cfgetispeed.3c .\" links@cfspeed.3c cfgetospeed.3c .\" links@cfspeed.3c cfsetispeed.3c .\" links@cfspeed.3c cfsetospeed.3c .\" .\" fileset_database@cfspeed.3c PROGRAMING-MAN .\" $Header: cfspeed.3c,v 72.4 94/11/14 13:05:47 ssa Exp $ .TA c .TH cfspeed 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cfgetospeed(\|), cfsetospeed(\|), cfgetispeed(\|), cfsetispeed(\|) \- tty baud rate functions .SH SYNOPSIS .C "#include " .PP .C "speed_t cfgetospeed(const struct termios *termios_p);" .PP .C "int cfsetospeed(struct termios *termios_p, speed_t speed);" .PP .C "speed_t cfgetispeed(const struct termios *termios_p);" .PP .C "int cfsetispeed(struct termios *termios_p, speed_t speed);" .SH DESCRIPTION These functions set and get the input and output speed codes in the .I termios structure referenced by .IR termios_p . The .I termios structure contains these speed codes representing input and output baud rates as well as other terminal related parameters. Setting the parameters on a terminal file does not become effective until .C tcsetattr() is successfully called. .RS .TP 20 .C cfgetospeed() returns the output speed code from the .I termios structure referenced by .IR termios_p . .TP .C cfsetospeed() sets the output speed code in the .I termios structure referenced by .I termios_p to .IR speed . The speed code for a baud rate of zero, .CR B0 , is used to terminate the connection. If .C B0 is specified, the modem control lines are no longer asserted, which normally disconnects the line. .TP .C cfgetispeed() returns the input speed code from the .I termios structure referenced by .IR termios_p . .TP .C cfsetispeed() sets the input speed code in the .I termios structure referenced by .I termios_p to .IR speed . .RE .SH RETURN VALUE .C cfgetospeed() returns the output speed code from the .I termios structure referenced by .IR termios_p . .PP .C cfgetispeed() returns the input speed code from the .I termios structure referenced by .IR termios_p . .PP .C cfsetispeed() and .C cfsetospeed() return zero upon successful completion. Otherwise, they return \-1 and set .C errno to indicate the error. .SH ERRORS .C cfsetispeed() and .C cfsetospeed() fail when the following condition is encountered: .RS .TP 15 .SM [EINVAL] The value of .I speed is outside the range of possible speed codes as specified in .RC < termios.h >. .RE .SH WARNINGS .C cfsetispeed() and .C cfsetospeed() can be used to set speed codes in the .I termios structure that are not supported by the terminal hardware. .SH SEE ALSO tcattribute(3C), termio(7). .SH STANDARDS CONFORMANCE .CR cfgetispeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfgetospeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfsetispeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfsetospeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4cfgetispeed()\fP \- get tty input baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfgetospeed()\fP \- get tty output baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfsetispeed()\fP \- set tty input baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfsetospeed()\fP \- set tty output baud rate@@@\f3cfspeed(3C)\f1 .\" index@get or set tty baud rate@@@\f3cfspeed(3C)\f1 .\" index@set or get tty baud rate@@@\f3cfspeed(3C)\f1 .\" index@tty baud rate, set or get@@@\f3cfspeed(3C)\f1 .\" index@baud rate, tty, set or get@@@\f3cfspeed(3C)\f1 .\" .\" toc@\f3cfspeed(3C)\f1:\0\0\f4cfgetospeed()\fP, \f4cfsetospeed()\fP, \f4cfgetispeed()\fP, \f4cfsetispeed()\fP@@@tty baud rate functions .\" toc@\f4cfgetispeed()\fP: get tty intput baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfgetospeed()\fP: get tty output baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfsetispeed()\fP: set tty intput baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfsetospeed()\fP: set tty output baud rate@@@see \f3cfspeed(3C)\f1 .\" .\" links@cfspeed.3c cfgetispeed.3c .\" links@cfspeed.3c cfgetospeed.3c .\" links@cfspeed.3c cfsetispeed.3c .\" links@cfspeed.3c cfsetospeed.3c .\" .\" fileset_database@cfspeed.3c PROGRAMING-MAN .\" $Header: cfspeed.3c,v 72.4 94/11/14 13:05:47 ssa Exp $ .TA c .TH cfspeed 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cfgetospeed(\|), cfsetospeed(\|), cfgetispeed(\|), cfsetispeed(\|) \- tty baud rate functions .SH SYNOPSIS .C "#include " .PP .C "speed_t cfgetospeed(const struct termios *termios_p);" .PP .C "int cfsetospeed(struct termios *termios_p, speed_t speed);" .PP .C "speed_t cfgetispeed(const struct termios *termios_p);" .PP .C "int cfsetispeed(struct termios *termios_p, speed_t speed);" .SH DESCRIPTION These functions set and get the input and output speed codes in the .I termios structure referenced by .IR termios_p . The .I termios structure contains these speed codes representing input and output baud rates as well as other terminal related parameters. Setting the parameters on a terminal file does not become effective until .C tcsetattr() is successfully called. .RS .TP 20 .C cfgetospeed() returns the output speed code from the .I termios structure referenced by .IR termios_p . .TP .C cfsetospeed() sets the output speed code in the .I termios structure referenced by .I termios_p to .IR speed . The speed code for a baud rate of zero, .CR B0 , is used to terminate the connection. If .C B0 is specified, the modem control lines are no longer asserted, which normally disconnects the line. .TP .C cfgetispeed() returns the input speed code from the .I termios structure referenced by .IR termios_p . .TP .C cfsetispeed() sets the input speed code in the .I termios structure referenced by .I termios_p to .IR speed . .RE .SH RETURN VALUE .C cfgetospeed() returns the output speed code from the .I termios structure referenced by .IR termios_p . .PP .C cfgetispeed() returns the input speed code from the .I termios structure referenced by .IR termios_p . .PP .C cfsetispeed() and .C cfsetospeed() return zero upon successful completion. Otherwise, they return \-1 and set .C errno to indicate the error. .SH ERRORS .C cfsetispeed() and .C cfsetospeed() fail when the following condition is encountered: .RS .TP 15 .SM [EINVAL] The value of .I speed is outside the range of possible speed codes as specified in .RC < termios.h >. .RE .SH WARNINGS .C cfsetispeed() and .C cfsetospeed() can be used to set speed codes in the .I termios structure that are not supported by the terminal hardware. .SH SEE ALSO tcattribute(3C), termio(7). .SH STANDARDS CONFORMANCE .CR cfgetispeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfgetospeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfsetispeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfsetospeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4cfgetispeed()\fP \- get tty input baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfgetospeed()\fP \- get tty output baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfsetispeed()\fP \- set tty input baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfsetospeed()\fP \- set tty output baud rate@@@\f3cfspeed(3C)\f1 .\" index@get or set tty baud rate@@@\f3cfspeed(3C)\f1 .\" index@set or get tty baud rate@@@\f3cfspeed(3C)\f1 .\" index@tty baud rate, set or get@@@\f3cfspeed(3C)\f1 .\" index@baud rate, tty, set or get@@@\f3cfspeed(3C)\f1 .\" .\" toc@\f3cfspeed(3C)\f1:\0\0\f4cfgetospeed()\fP, \f4cfsetospeed()\fP, \f4cfgetispeed()\fP, \f4cfsetispeed()\fP@@@tty baud rate functions .\" toc@\f4cfgetispeed()\fP: get tty intput baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfgetospeed()\fP: get tty output baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfsetispeed()\fP: set tty intput baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfsetospeed()\fP: set tty output baud rate@@@see \f3cfspeed(3C)\f1 .\" .\" links@cfspeed.3c cfgetispeed.3c .\" links@cfspeed.3c cfgetospeed.3c .\" links@cfspeed.3c cfsetispeed.3c .\" links@cfspeed.3c cfsetospeed.3c .\" .\" fileset_database@cfspeed.3c PROGRAMING-MAN .\" $Header: cfspeed.3c,v 72.4 94/11/14 13:05:47 ssa Exp $ .TA c .TH cfspeed 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cfgetospeed(\|), cfsetospeed(\|), cfgetispeed(\|), cfsetispeed(\|) \- tty baud rate functions .SH SYNOPSIS .C "#include " .PP .C "speed_t cfgetospeed(const struct termios *termios_p);" .PP .C "int cfsetospeed(struct termios *termios_p, speed_t speed);" .PP .C "speed_t cfgetispeed(const struct termios *termios_p);" .PP .C "int cfsetispeed(struct termios *termios_p, speed_t speed);" .SH DESCRIPTION These functions set and get the input and output speed codes in the .I termios structure referenced by .IR termios_p . The .I termios structure contains these speed codes representing input and output baud rates as well as other terminal related parameters. Setting the parameters on a terminal file does not become effective until .C tcsetattr() is successfully called. .RS .TP 20 .C cfgetospeed() returns the output speed code from the .I termios structure referenced by .IR termios_p . .TP .C cfsetospeed() sets the output speed code in the .I termios structure referenced by .I termios_p to .IR speed . The speed code for a baud rate of zero, .CR B0 , is used to terminate the connection. If .C B0 is specified, the modem control lines are no longer asserted, which normally disconnects the line. .TP .C cfgetispeed() returns the input speed code from the .I termios structure referenced by .IR termios_p . .TP .C cfsetispeed() sets the input speed code in the .I termios structure referenced by .I termios_p to .IR speed . .RE .SH RETURN VALUE .C cfgetospeed() returns the output speed code from the .I termios structure referenced by .IR termios_p . .PP .C cfgetispeed() returns the input speed code from the .I termios structure referenced by .IR termios_p . .PP .C cfsetispeed() and .C cfsetospeed() return zero upon successful completion. Otherwise, they return \-1 and set .C errno to indicate the error. .SH ERRORS .C cfsetispeed() and .C cfsetospeed() fail when the following condition is encountered: .RS .TP 15 .SM [EINVAL] The value of .I speed is outside the range of possible speed codes as specified in .RC < termios.h >. .RE .SH WARNINGS .C cfsetispeed() and .C cfsetospeed() can be used to set speed codes in the .I termios structure that are not supported by the terminal hardware. .SH SEE ALSO tcattribute(3C), termio(7). .SH STANDARDS CONFORMANCE .CR cfgetispeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfgetospeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfsetispeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR cfsetospeed() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4cfgetispeed()\fP \- get tty input baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfgetospeed()\fP \- get tty output baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfsetispeed()\fP \- set tty input baud rate@@@\f3cfspeed(3C)\f1 .\" index@\f4cfsetospeed()\fP \- set tty output baud rate@@@\f3cfspeed(3C)\f1 .\" index@get or set tty baud rate@@@\f3cfspeed(3C)\f1 .\" index@set or get tty baud rate@@@\f3cfspeed(3C)\f1 .\" index@tty baud rate, set or get@@@\f3cfspeed(3C)\f1 .\" index@baud rate, tty, set or get@@@\f3cfspeed(3C)\f1 .\" .\" toc@\f3cfspeed(3C)\f1:\0\0\f4cfgetospeed()\fP, \f4cfsetospeed()\fP, \f4cfgetispeed()\fP, \f4cfsetispeed()\fP@@@tty baud rate functions .\" toc@\f4cfgetispeed()\fP: get tty intput baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfgetospeed()\fP: get tty output baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfsetispeed()\fP: set tty intput baud rate@@@see \f3cfspeed(3C)\f1 .\" toc@\f4cfsetospeed()\fP: set tty output baud rate@@@see \f3cfspeed(3C)\f1 .\" .\" links@cfspeed.3c cfgetispeed.3c .\" links@cfspeed.3c cfgetospeed.3c .\" links@cfspeed.3c cfsetispeed.3c .\" links@cfspeed.3c cfsetospeed.3c .\" .\" fileset_database@cfspeed.3c PROGRAMING-MAN .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "change_managed" "Xt \- Intrinsics Methods" .SH "Name" .Na change_managed \- Composite class method to respond to a change in a list of managed\p widgets. .Nz .XX "change_managed method" .XX "methods, change_managed" .SH "Synopsis" .Sy typedef void (*XtWidgetProc)(Widget); .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that has had children managed or unmanaged. .\" .SH "Description" The \f(CWchange_managed()\fP method is registered on the \f(CWchange_managed\fP field of the Composite class part structure, and is invoked when a child or children are managed or unmanaged with \f(CWXtManageChild()\fP, \f(CWXtManageChildren()\fP, \f(CWXtUnmanageChild()\fP, or \f(CWXtUnmanageChildren()\fP. .LP When a child is managed or unmananged, it generally means that the layout of all the children of the widget should be redone. Note that this method does not have an argument which specifies which children have had their managed state changed. \f(CWchange_managed()\fP should loop through all of the children in its \f(CWchildren\fP array, using \f(CWXtIsManaged()\fP to determine which are managed and should therefore be included in the layout calculations. .LP The \f(CWchange_managed()\fP method is not chained. A widget class that does not define a \f(CWchange_managed()\fP method can inherit this method from its superclass by specifying \f(CWXtInheritChangeManaged\fP in its Composite \f(CWchange_managed()\fP class field. .\" .SH "Usage" Many \f(CWchange_managed()\fP methods simply call a general layout routine which may also be called from other places in the widget such as the \f(CWresize()\fP method. .\" .SH "Example" The following procedure is the \f(CWchange_managed()\fP method for the Xaw Form widget. Note how it loops through all of its children, setting constraint fields for those that are managed, and then calls a layout routine (which is a class method of the Form widget in this case) to recalculate the layout of all children. It makes no attempt to determine which children have been managed or unmanaged. .Ps .ps 8 static void ChangeManaged(w) Widget w; { FormWidget fw = (FormWidget)w; FormConstraints form; WidgetList children, childP; int num_children = fw->composite.num_children; Widget child; /* * Reset virtual width and height for all children. */ for (children = childP = fw->composite.children ; childP - children < num_children; childP++) { child = *childP; if (XtIsManaged(child)) { form = (FormConstraints)child->core.constraints; /* * If the size is one (1) then we must not change the virtual sizes, as * they contain useful information. If someone actually wants a widget * of width or height one (1) in a form widget he will lose, can't win * them all. * * Chris D. Peterson 2/9/89. */ if ( child->core.width != 1) form->form.virtual_width = (int) child->core.width; if ( child->core.height != 1) form->form.virtual_height = (int) child->core.height; } } (*((FormWidgetClass)w->core.widget_class)->form_class.layout) ((FormWidget) w, w->core.width, w->core.height, TRUE); } .ps .Pe .SH "See Also" .na .br \s-1\fIComposite\fR\s+1\*(s3, \s-1\fIConstraint\fR\s+1\*(s3. .ad .\"last line comment .\" $Header: chgat.3x,v 76.2 95/07/31 17:23:18 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH chgat 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chgat, mvchgat, mvwchgat, wchgat \(em change renditions of characters in a window .SH SYNOPSIS .C "#include " .P .C "int chgat(int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP, void *const \f2opts\fP);" .P .C "int mvchgat(int \f2y\fP, int \f2x\fP, int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP," .br .C " void *const \f2opts\fP);" .P .C "int mvwchgat(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, int \f2n\fP, attr_t \f2attr\fP," .br .C " short \f2color\fP, void *const \f2opts\fP);" .P .C "int wchgat(WINDOW *\f2win\fP, int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP," .br .C " void *const \f2opts\fP);" .SH DESCRIPTION These functions change the renditions of the next \f2n\f1 characters in the current or specified window (or of the remaining characters on the line, if \f2n\f1 is \(mi1), starting at the current or specified cursor position. The attributes and colors are specified by \f2attr\f1 and \f2color\f1 as for .CR setcchar() . .P These functions do not update the cursor. These functions do not perform wrapping. .P A value of \f2n\f1 that is greater than the remaining characters on a line is not an error. .P The \f2opts\f1 argument is reserved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" setcchar(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3chgat(3X)\f1:\0\0\f4chgat()\f1, \f4mvchgat()\f1, \f4mvwchgat()\f1, \f4wchgat()\f1@@@change renditions of characters in a window .\" toc@\f4mvchgat()\f1: change renditions of characters in a window@@@see \f3chgat(3X)\f1 .\" toc@\f4mvwchgat()\f1: change renditions of characters in a window@@@see \f3chgat(3X)\f1 .\" toc@\f4wchgat()\f1: change renditions of characters in a window@@@see \f3chgat(3X)\f1 .\" .\" index@\f4chgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f4mvchgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f4mvwchgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f4wchgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f1change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f1renditions of characters in a window, change@@@\f3chgat(3X)\f1 .\" index@\f1window, change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f1characters, renditions of, change in a window@@@\f3chgat(3X)\f1 .\" .\" links@chgat.3x mvchgat.3x .\" links@chgat.3x mvwchgat.3x .\" links@chgat.3x wchgat.3x .\" .\" fileset_database@chgat.3x CURS-ENG-A-MAN .\" $Header: chownacl.3c,v 72.3 93/01/14 14:45:31 ssa Exp $ .TA c .TH chownacl 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chownacl(\|) \- change owner and/or group represented in a file's access control list (ACL) .SH SYNOPSIS .C "#include " .PP .PD 0 .nf .C "void chownacl(" .IP .C "int nentries," .C "const struct acl_entry *acl," .C "uid_t olduid," .C "gid_t oldgid," .C "uid_t newuid," .C "gid_t newgid" .PP .C ");" .PD .fi .SS Remarks: To ensure continued conformance with emerging industry standards, features described in this manual entry are likely to change in a future release. .SH DESCRIPTION This routine alters an access control list .SM (ACL) to reflect the change in a file's owner or group .SM ID when an old file is copied to a new file and the .SM ACL is also copied. .C chownacl() transfers ownership (that is, it modifies base .SM ACL entries) in a manner similar to .C chown() (see .IR chown (2)). The algorithm is described below and also in .IR acl (5). .PP The .I nentries parameter is the current number of .SM ACL entries in the .C acl[] array (zero or more; a negative value is treated as zero). The .I olduid and .I oldgid values are the user and group .SM ID\s0s of the original file's owner, typically the .C st_uid and .C st_gid values from .C stat() (see .IR stat (2)). The .I newuid and .I newgid values are the user and group .SM ID\s0s of the new file's owner, typically the return values from .C geteuid() and .C getegid() (see .IR geteuid (2) and .IR getegid (2)). .PP If an .SM ACL entry in .CR acl[] has a .I uid of .I olduid and a .I gid of .C ACL_NSGROUP (that is, an owner base .SM ACL entry), .C chownacl() changes .I uid to .I newuid (with exceptions \(mi see below). If an entry has a .I uid of .C ACL_NSUSER and a .I gid of .I oldgid (that is, a group base .SM ACL entry), .C chownacl() changes .I gid to .IR newgid . In either case, only the last matching .SM ACL entry is altered; a valid .SM ACL can have only one of each type. .PP As with .IR chown (2), if the new user or group already has an .SM ACL entry (that is, a .I uid of .I newuid and a .I gid of .CR ACL_NSGROUP , or a .I uid of .C ACL_NSUSER and a .I gid of .IR newgid ), .C chownacl() does not change the old user or group base .SM ACL entry; both the old and new .SM ACL entries are preserved. .PP As a special case, if .I olduid .RI ( oldgid ) is equal to .I newuid .RI ( newgid ), .C chownacl() does not search .C acl[] for an old user (group) base .SM ACL entry to change. Calling it with both .I olduid equal to .I newuid and .I oldgid equal to .I newgid causes .C chownacl() to do nothing. .SS Suggested Use This routine is useful in a program that creates a new or replacement copy of a file whose original was (or possibly was) owned by a different user or group, and that copies the old file's .SM ACL to the new file. Copying another user's and/or group's file is equivalent to having the original file's owner and/or group copy and then transfer a file to a new owner and/or group using .CR chown() . This routine is not needed for merely changing a file's ownership; .C chown() modifies the .SM ACL appropriately in that case. .PP If a program also copies file miscellaneous mode bits from an old file to a new one, it must use .C chmod() (see .IR chmod (2)). However, since .C chmod() deletes optional .SM ACL entries, it must be called before .C setacl() (see .IR setacl (2)). Furthermore, to avoid leaving a new file temporarily unprotected, the .C chmod() call should set only the file miscellanous mode bits, with all access permission mode bits set to zero (that is, mask the mode with 07000). The .C cpacl() library call encapsulates this operation, and handles remote files appropriately too. .SH EXAMPLES The following code fragment gets .C stat() information and the .SM ACL from .CR oldfile , transfers ownership of .C newfile to the caller, and sets the revised .SM ACL to .CR newfile . .RS .PP .nf .ift .ft 4 .ps +1 #include #include #include int nentries; struct acl_entry acl [NACLENTRIES]; struct stat statbuf; if (stat ("oldfile", & statbuf) < 0) error (...); if ((nentries = getacl ("oldfile", NACLENTRIES, acl)) < 0) error (...); chownacl (nentries, acl, statbuf.st_uid, statbuf.st_gid, geteuid(), getegid()); if (setacl ("newfile", nentries, acl)) error (...); .ift .ft .ps .fi .RE .SH AUTHOR .C chownacl() was developed by HP. .SH SEE ALSO chown(2), getacl(2), getegid(2), geteuid(2), setacl(2), stat(2), acltostr(3C), cpacl(3C), setaclentry(3C), strtoacl(3C), acl(5). .\" index@\f4chownacl()\fP \- change owner and/or group in access control list (\s-1ACL\s+1)@@@\f3chownacl(3C)\f1 .\" index@change owner and/or group in access control list (\s-1ACL\s+1)@@@\f3chownacl(3C)\f1 .\" index@owner and/or group, change in access control list (\s-1ACL\s+1)@@@\f3chownacl(3C)\f1 .\" index@group and/or owner, change in access control list (\s-1ACL\s+1)@@@\f3chownacl(3C)\f1 .\" index@access control list (\s-1ACL\s+1), change owner and/or group in@@@\f3chownacl(3C)\f1 .\" toc@\f3chownacl(3C)\f1:\0\0\f4chownacl()\fP@@@change owner and/or group in access control list (\s-1ACL\s+1) .\" .\" fileset_database@chownacl.3c PROGRAMING-MAN .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "class_initialize" "Xt \- Intrinsics Methods" .SH "Name" .Na class_initialize \- Object class method for one-time class initialization. .Nz .XS "methods, class_initialize" .XS "class: class_initialize method" .SH "Synopsis" .Sy typedef void (*XtProc)(void); .As .Ae .SH "Description" The \f(CWclass_initialize()\fP method is registered on the \f(CWclass_initialize\fP field of the Object, RectObj, or Core class structures, and is called exactly once by the Intrinsics before any instances of the class are created. .LP The \f(CWclass_initialize()\fP method takes no arguments and returns no value. It performs initialization that should be done once for this class and all its subclasses, such as registering type converters and interning atoms and quarks. Compare this with the \f(CWclass_part_initialize()\fP method which is called once for its class and also for every subclass, and is responsible for initializing fields in the class part structure. .LP The \f(CWclass_initialize()\fP method is not chained and cannot be inherited. If a widget class does not need any one-time initialization, it should specify \f(CWNULL\fP in its \f(CWclass_initialize\fP field. .LP The fact that this method is not chained means that when a given widget class, C, is initialized, only the \f(CWclass_initialize()\fP method for that class is called--the methods for the superclasses B and A are not called during the initialization of C. If the \f(CWclass_initialize()\fP method were chained, then the method for widget class A would be invoked whenever a subclass, such as B or C, were initialized. Since the method is intended for one-time global initializations, this would be inappropriate. Although this method is not chained, the Intrinsics ensure that the superclasses of a class will be initialized before the class itself. So, in fact, the \f(CWclass_initialize()\fP methods for classes A and B are guaranteed to have been called before the \f(CWclass_initialize()\fP method for C is called. .LP See the "Background" section below for more information on when this method is called. .\" .SH "Usage" The \f(CWclass_initialize()\fP performs one-time, global initializations for the class. It should not initialize the fields of the class structure--that is the job of the \f(CWclass_part_initialize()\fP method, which is a chained method, and is invoked for class and all of its subclasses. \f(CWclass_initialize()\fP and \f(CWclass_part_initialize()\fP perform initialization of the widget class. It is the \f(CWinitialize()\fP method that initializes the \fIinstance\fP structure of the widget--it is invoked whenever a widget instance is created. .\" .SH "Example" The following procedure is the \f(CWclass_initialize()\fP method of the Xaw Form widget. Note that it registers two resource converters, and interns quarks (in global variables) for use by the String-to-EdgeType converter. .Nd 10 .Ps .ps 8 static void ClassInitialize() { static XtConvertArgRec parentCvtArgs[] = { {XtBaseOffset, (XtPointer)XtOffsetOf(WidgetRec, core.parent), sizeof(Widget)} }; XawInitializeWidgetSet(); XtQChainLeft = XrmPermStringToQuark("chainleft"); XtQChainRight = XrmPermStringToQuark("chainright"); XtQChainTop = XrmPermStringToQuark("chaintop"); XtQChainBottom = XrmPermStringToQuark("chainbottom"); XtQRubber = XrmPermStringToQuark("rubber"); XtAddConverter( XtRString, XtREdgeType, _CvtStringToEdgeType, NULL, 0 ); XtSetTypeConverter (XtRString, XtRWidget, XmuNewCvtStringToWidget, parentCvtArgs, XtNumber(parentCvtArgs), XtCacheNone, NULL); } .ps .Pe .\" .SH "Background" All widget classes, whether they have a \f(CWclass_initialize()\fP method or not, must start with their \f(CWclass_inited\fP field \f(CWFalse\fR. .LP The first time a widget of a class is created, \f(CWXtCreateWidget()\fR ensures that the widget class and all superclasses are initialized, in superclass-to-subclass order, by checking each \f(CWclass_inited\fP field. If this field is \f(CWFalse\fR, \f(CWXtCreateWidget()\fR calls the \f(CWclass_initialize()\fP and the \f(CWclass_part_initialize()\fP methods for the class and all its superclasses. The Intrinsics then set the \f(CWclass_inited\fP field to a nonzero value. After the one-time initialization, a class structure is constant. This initialization process can also be performed explicitly, without creating a widget, by calling \f(CWXtInitializeWidgetClass()\fP. .XN "Core widget: (see also methods)" .SH "See Also" .na \s-1\fIXtInitializeWidgetClass\fR\s+1\*(s1, .br \s-1\fICore\fR\s+1\*(s3, .br \s-1\fIclass_part_initialize\fR\s+1\*(s4, \s-1\fIinitialize\fR\s+1\*(s4. .ad .XE "methods, class_initialize" .XE "class: class_initialize method" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "class_part_initialize" "Xt \- Intrinsics Methods" .SH "Name" .Na class_part_initialize \- Object class method to initialize class part structure fields. .Nz .XX "class: class_part_initialize method" .XX "methods, class_part_initialize" .SH "Synopsis" .Sy typedef void (*XtWidgetClassProc)(WidgetClass); .As WidgetClass \f(CIsubclass\fP; .Ae .SS "Inputs" .IP \f(CIsubclass\fP 1i Specifies the pointer to a widget class structure. It is the class that registered this method or a subclass thereof. .\" .SH "Description" The \f(CWclass_part_initialize()\fP method is registered on the \f(CWclass_part_initialize\fP field of the Object, RectObj, or Core class structure, and is called to dynamically initialize any fields in the class part structure of its widget class. .LP During class initialization, the \f(CWclass_part_initialize()\fP method for the class and for all its super\%classes is called in superclass-to-subclass order on the class record. These procedures do any dynamic initializations necessary to their class's part of the record, including resolution of any inherited methods defined in the class. For example, if a widget class \fIC\fP has super\%classes Core, Composite, \fIA\fP, and \fIB\fP, then the class record for \fIC\fP is passed first to Core's \f(CWclass_part_initialize()\fP method. This resolves any inherited Core methods and compiles the textual representations of the resource list and action table that are defined in the Core class part. Next, the Composite's \f(CWclass_part_initialize()\fP is called to initialize the Composite part of \fIC\fP's class record. Finally, the \f(CWclass_part_initialize()\fP procedures for \fIA\fP, \fIB\fP, and \fIC\fP (in order) are called. All these methods will be called again if subclass \fID\fP of class \fIC\fP is initialized, this time to initialize the various parts of \fID\fP's class structure. .LP The \f(CWclass_part_initialize()\fP method is chained in superclass-to-subclass order and cannot be inherited. Classes that do not define any new class fields or that need no extra processing for them can set their \f(CWclass_part_initialize\fP field to be \f(CWNULL\fP. .LP See the "Background" section below for more details on when class initialization is performed. .\" .SH "Usage" The \f(CWsubclass\fP argument to a \f(CWclass_part_initialize()\fP procedure may be the widget class itself, or any subclass of it. You should cast it to a pointer to your widget class and use that pointer to access the fields of the class part structure that your class defines. If you need to access the superclass, use the \f(CWsuperclass\fP field in the Object, RectObj, or Core class part. This is shown in the example below. .LP The most common usage of the \f(CWclass_part_initialize()\fP method is to handle inheritance of class methods and other fields. If you define a class with a method or other field that can be inherited, you should define a special value that the writer of the subclass can use to inherit the field (use the constant \f(CW_XtInherit\fP cast to the appropriate type, as shown in the example below) and provide a \f(CWclass_part_initialize()\fP method which checks the inheritable field for this special value and overwrites it .ne 2 with the contents of the superclass's field. .\" .SH "Example" The following procedure is the \f(CWclass_part_initialize()\fP method for the Xaw Form widget class. Note how it determines the immediate superclass and handles the inheritance of the Form \f(CWlayout()\fP class method. .LP Note that it does not initialize the Core, Composite, or Constraint class part fields, nor does it make any assumptions about its \f(CWWidgetClass\fP argument except that it is a subclass of Form. Also note that when this method is called for the Form widget class itself, the variable \f(CWsuper\fP will be set to the superclass of Form, which cannot correctly be cast to \f(CWFormWidgetClass\fP. This is a bug, but will never cause problems, because the Form class itself will never have to inherit any fields. .LP Note that the identifier \f(CWclass\fP is a reserved word in C++, and your code will be more portable if you avoid using it as an argument name in C code. .Ps static void ClassPartInitialize(class) WidgetClass class; { register FormWidgetClass c = (FormWidgetClass)class; register FormWidgetClass super = (FormWidgetClass) c->core_class.superclass; if (c->form_class.layout == XtInheritLayout) c->form_class.layout = super->form_class.layout; } .Pe The constant \f(CWXtInheritLayout\fP is defined as follows (in \fI\fP): .Ps #define XtInheritLayout ((Boolean (*)())_XtInherit) .Pe .\" .SH "Background" All widget classes, whether or not they have class and class part initialization procedures, must start with their \f(CWclass_inited\fP field \f(CWFalse\fR. .LP The first time a widget of a class is created, \f(CWXtCreateWidget()\fR ensures that the widget class and all super\%classes are initialized, in superclass-to-subclass order, by checking each \f(CWclass_inited\fP field. If this field is \f(CWFalse\fR, \f(CWXtCreateWidget()\fR calls the \f(CWclass_initialize()\fP and the \f(CWclass_part_initialize()\fP methods for the class and all its super\%classes. The Intrinsics then set the \f(CWclass_inited\fP field to a nonzero value. After the one-time initialization, a class structure is constant. This initialization can also be performed explicitly, without creating a widget, by calling \f(CWXtInitializeWidgetClass()\fP. .\" .SH "See Also" .na .br \s-1\fIXtInitializeWidgetClass\fR\s+1\*(s1, .br \s-1\fICore\fR\s+1\*(s3, .br \s-1\fIclass_initialize\fR\s+1\*(s4, \s-1\fIinitialize\fR\s+1\*(s4. .ad .\"last line comment .\" $Header: clear.3x,v 76.2 95/07/31 17:24:33 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH clear 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clear, erase, wclear, werase \(em clear a window .SH SYNOPSIS .C "#include " .P .C "int clear(void);" .P .C "int erase(void);" .P .C "int wclear(WINDOW *\f2win\fP);" .P .C "int werase(WINDOW *\f2win\fP);" .SH DESCRIPTION The .CR clear() , .CR erase() , .Fn wclear and .Fn werase functions clear every position in the current or specified window. .P The .Fn clear and .Fn wclear functions also achieve the same effect as calling .Fn clearok , so that the window is cleared completely on the next call to .Fn wrefresh for the window and is redrawn in its entirety. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" clearok(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn erase and .Fn werase functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The argument list for the .Fn clear and .Fn erase functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3clear(3X)\f1:\0\0\f4clear()\f1, \f4erase()\f1, \f4wclear()\f1, \f4werase()\f1@@@clear a window .\" toc@\f4erase()\f1: clear a window@@@see \f3clear(3X)\f1 .\" toc@\f4werase()\f1: clear a window@@@see \f3clear(3X)\f1 .\" toc@\f4wclear()\f1: clear a window@@@see \f3clear(3X)\f1 .\" .\" index@\f4clear()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f4wclear()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f4erase()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f4werase()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f1clear a window@@@\f3clear(3X)\f1 .\" index@\f1window, clear@@@\f3clear(3X)\f1 .\" .\" links@clear.3x wclear.3x .\" links@clear.3x erase.3x .\" links@clear.3x werase.3x .\" .\" fileset_database@clear.3x CURS-ENG-A-MAN .\" $Header: clearenv.3c,v 72.4 94/11/14 13:08:11 ssa Exp $ .TA c .TH clearenv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clearenv \- clear the process environment .SH SYNOPSIS .C "#include " .PP .C "int clearenv(void);" .SH DESCRIPTION .C clearenv() clears the process environment. No environment variables are defined immediately after a call to .CR clearenv() . .PP .C clearenv() modifies the value of the pointer .IR environ . This means that copies of that pointer are invalid after a call to .CR clearenv() . .SH RETURN VALUE Upon successful completion, .C clearenv() returns zero; otherwise, it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C clearenv() fails if the following condition is encountered: .RS .TP 15 .SM [ENOMEM] Failed to free or reallocate memory for the process environment. .RE .SH SEE ALSO environ(5), getenv(3C), putenv(3C), . .SH STANDARDS CONFORMANCE .CR clearenv() ": AES" .\" .\" toc@\f3clearenv(3C)\f1:\0\0\f4clearenv\f1@@@clear the process environment .\" .\" index@\f4clearenv\f1 \- clear the process environment@@@\f3clearenv(3C)\f1 .\" index@clear the process environment@@@\f3clearenv(3C)\f1 .\" index@process environment, clear the@@@\f3clearenv(3C)\f1 .\" index@environment, clear the process@@@\f3clearenv(3C)\f1 .\" .\" fileset_database@clearenv.3c PROGRAMING-MAN .\" $Header: ferror.3s,v 72.5 94/11/14 15:28:20 ssa Exp $ .TA f .TH ferror 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ferror(\|), ferror_unlocked(\|), feof(\|), feof_unlocked(\|), clearerr(\|), clearerr_unlocked(\|) \- stream status inquiries .SH SYNOPSIS .C "#include " .PP .C "int ferror(FILE *stream);" .PP .C "int ferror_unlocked(FILE *stream);" .PP .C "int feof(FILE *stream);" .PP .C "int feof_unlocked(FILE *stream);" .PP .C "void clearerr(FILE *stream);" .PP .C "void clearerr_unlocked(FILE *stream);" .SH DESCRIPTION .TP 15 .CR ferror() Returns non-zero when an .SM I/O error has previously occurred reading from or writing to the named .IR stream , otherwise zero. Unless cleared by .CR clearerr() , or unless the specific .I stdio routine so indicates, the error indication lasts until the stream is closed. .TP .CR feof() Returns non-zero when .SM EOF has previously been detected reading the named input .IR stream , otherwise zero. .TP .CR clearerr() Resets the error indicator and .SM EOF indicator on the named .I stream to zero. .PP .CR ferror_unlocked() , " feof_unlocked()" , and .CR clearerr_unlocked() are identical to .CR ferror() , " feof()" , and .CR clearerr() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH WARNINGS All these routines are implemented both as library functions and as macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function, either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI-C mode, enclose the function name in parentheses or use the function address. The following example illustrates each of these methods : .nf .IP .CR "#include " .CR "#undef ferror" .CR " ..." .CR "main()" .CR "{" .CR " int (*find_error()) ();" .CR " ..." .CR " return_val=ferror(fd);" .CR " ..." .CR " return_val=(feof)(fd1);" .CR " ..." .CR " find_error = feof;" .CR }; .fi .SS Reentrant Interfaces If .CR _REENTRANT is defined before including .RC < stdio.h >, the locked versions of the library functions for .CR ferror() , " feof()" , and .CR clearerr() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR ferror() , " feof()" , and .CR clearerr() . .br .ne 12v .SH SEE ALSO open(2), flockfile(3S), fopen(3S). .SH STANDARDS CONFORMANCE .CR ferror() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR clearerr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR feof() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f2ferror\f1 \- check for \s-1I/O\s+1 error on stream@@@\f3ferror(3S)\f1 .\" index@\f2feof\f1 \- check for end-of-file error on stream@@@\f3ferror(3S)\f1 .\" index@\f2clearerr\f1 \- clear \s-1I/O\s+1 error on stream@@@\f3ferror(3S)\f1 .\" index@stream status inquiries@@@\f3ferror(3S)\f1 .\" index@status inquiries, stream@@@\f3ferror(3S)\f1 .\" .\" toc@\f3ferror(3S)\f1:\0\0\f2ferror\f1, \f2feof\f1, \f2clearerr\f1@@@stream status inquiries .\" toc@\f2feof\f1:\0\0stream status inquiries@@@see \f3ferror(3S)\f1 .\" toc@\f2clearerr\f1:\0\0stream status inquiries@@@see \f3ferror(3S)\f1 .\" .\" links@ferror.3s ferror_unlo.3s .\" links@ferror.3s feof.3s .\" links@ferror.3s feof_unlock.3s .\" links@ferror.3s clearerr.3s .\" links@ferror.3s clearerr_un.3s .\" $Header: ferror.3s,v 72.5 94/11/14 15:28:20 ssa Exp $ .TA f .TH ferror 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ferror(\|), ferror_unlocked(\|), feof(\|), feof_unlocked(\|), clearerr(\|), clearerr_unlocked(\|) \- stream status inquiries .SH SYNOPSIS .C "#include " .PP .C "int ferror(FILE *stream);" .PP .C "int ferror_unlocked(FILE *stream);" .PP .C "int feof(FILE *stream);" .PP .C "int feof_unlocked(FILE *stream);" .PP .C "void clearerr(FILE *stream);" .PP .C "void clearerr_unlocked(FILE *stream);" .SH DESCRIPTION .TP 15 .CR ferror() Returns non-zero when an .SM I/O error has previously occurred reading from or writing to the named .IR stream , otherwise zero. Unless cleared by .CR clearerr() , or unless the specific .I stdio routine so indicates, the error indication lasts until the stream is closed. .TP .CR feof() Returns non-zero when .SM EOF has previously been detected reading the named input .IR stream , otherwise zero. .TP .CR clearerr() Resets the error indicator and .SM EOF indicator on the named .I stream to zero. .PP .CR ferror_unlocked() , " feof_unlocked()" , and .CR clearerr_unlocked() are identical to .CR ferror() , " feof()" , and .CR clearerr() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH WARNINGS All these routines are implemented both as library functions and as macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function, either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI-C mode, enclose the function name in parentheses or use the function address. The following example illustrates each of these methods : .nf .IP .CR "#include " .CR "#undef ferror" .CR " ..." .CR "main()" .CR "{" .CR " int (*find_error()) ();" .CR " ..." .CR " return_val=ferror(fd);" .CR " ..." .CR " return_val=(feof)(fd1);" .CR " ..." .CR " find_error = feof;" .CR }; .fi .SS Reentrant Interfaces If .CR _REENTRANT is defined before including .RC < stdio.h >, the locked versions of the library functions for .CR ferror() , " feof()" , and .CR clearerr() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR ferror() , " feof()" , and .CR clearerr() . .br .ne 12v .SH SEE ALSO open(2), flockfile(3S), fopen(3S). .SH STANDARDS CONFORMANCE .CR ferror() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR clearerr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR feof() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f2ferror\f1 \- check for \s-1I/O\s+1 error on stream@@@\f3ferror(3S)\f1 .\" index@\f2feof\f1 \- check for end-of-file error on stream@@@\f3ferror(3S)\f1 .\" index@\f2clearerr\f1 \- clear \s-1I/O\s+1 error on stream@@@\f3ferror(3S)\f1 .\" index@stream status inquiries@@@\f3ferror(3S)\f1 .\" index@status inquiries, stream@@@\f3ferror(3S)\f1 .\" .\" toc@\f3ferror(3S)\f1:\0\0\f2ferror\f1, \f2feof\f1, \f2clearerr\f1@@@stream status inquiries .\" toc@\f2feof\f1:\0\0stream status inquiries@@@see \f3ferror(3S)\f1 .\" toc@\f2clearerr\f1:\0\0stream status inquiries@@@see \f3ferror(3S)\f1 .\" .\" links@ferror.3s ferror_unlo.3s .\" links@ferror.3s feof.3s .\" links@ferror.3s feof_unlock.3s .\" links@ferror.3s clearerr.3s .\" links@ferror.3s clearerr_un.3s .\" $Header: clearok.3x,v 76.2 95/07/31 17:25:47 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH clearok 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clearok, idlok, leaveok, scrollok, setscrreg, wsetscrreg \(em terminal output control functions .SH SYNOPSIS .C "#include " .P .C "int clearok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int idlok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int leaveok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int scrollok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int setscrreg(int \f2top\fP, int \f2bot\fP);" .P .C "int wsetscrreg(WINDOW *\f2win\fP, int \f2top\fP, int \f2bot\fP);" .SH DESCRIPTION These functions set options that deal with output within Curses. .P The .Fn clearok function assigns the value of .I bf to an internal flag in the specified window that governs clearing of the screen during a refresh. If, during a refresh operation on the specified window, the flag in .I curscr is TRUE or the flag in the specified window is TRUE, then the implementation clears the screen, redraws it in its entirety, and sets the flag to FALSE in .I curscr and in the specified window. The initial state is unspecified. .P The .Fn idlok function specifies whether the implementation may use the hardware insert-line, delete-line, and scroll features of terminals so equipped. If \f2bf\f1 is TRUE, use of these features is enabled. If \f2bf\f1 is FALSE, use of these features is disabled and lines are instead redrawn as required. The initial state is FALSE. .P The .Fn leaveok function controls the cursor position after a refresh operation. If \f2bf\f1 is TRUE, refresh operations on the specified window may leave the terminal's cursor at an arbitrary position. If \f2bf\f1 is FALSE, then at the end of any refresh operation, the terminal's cursor is positioned at the cursor position contained in the specified window. The initial state is FALSE. .P The .Fn scrollok function controls the use of scrolling. If \f2bf\f1 is TRUE, then scrolling is enabled for the specified window, with the consequences discussed in \f3Truncation, Wrapping and Scrolling\f1 in curses_intro. If \f2bf\f1 is FALSE, scrolling is disabled for the specified window. The initial state is FALSE. .P The .Fn setscrreg and .Fn wsetscrreg functions define a software scrolling region in the current or specified window. The \f2top\f1 and \f2bot\f1 arguments are the line numbers of the first and last line defining the scrolling region. (Line 0 is the top line of the window.) If this option and .Fn scrollok are enabled, an attempt to move off the last line of the margin causes all lines in the scrolling region to scroll one line in the direction of the first line. Only characters in the window are scrolled. If a software scrolling region is set and .Fn scrollok is not enabled, an attempt to move off the last line of the margin does not reposition any lines in the scrolling region. .SH "RETURN VALUE" Upon successful completion, .Fn setscrreg and .Fn wsetscrreg return OK. Otherwise, they return ERR. .P The other functions always return OK. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The only reason to enable the .Fn idlok feature is to use scrolling to achieve the visual effect of motion of a partial window, such as for a screen editor. In other cases, the feature can be visually annoying. .P The .Fn leaveok option provides greater efficiency for applications that do not use the cursor. .SH "SEE ALSO" clear(), delscreen(), doupdate(), scrl(), . .SS "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .CR idlok() , .CR leaveok() , .CR scrollok() , .Fn setscrreq and .Fn wsetscrreq functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The .B DESCRIPTION of .Fn clearok is updated to indicate that clearing of a screen applies if the flag is TRUE in either \f2curscr\f1 or the specified window. .P The .B "RETURN VALUE" is changed to indicate that the .CR clearok() , .Fn leaveok and .Fn scrollok functions always return OK. .\" .\" toc@\f3clearok(3X)\f1:\0\0\f4clearok()\f1, \f4idleok()\f1, \f4leaveok()\f1, \f4scrollok()\f1, \f4setscrreg()\f1, \f4wsetscrreg()\f1\n@@@terminal output control functions .\" toc@\f4idleok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4leaveok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4scrollok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4setscrreg()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4wsetscrreg()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" index@\f4clearok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4idleok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4leaveok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4scrollok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4setscrreg()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4wsetscrreg()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f1terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f1output, terminal, control functions@@@\f3clearok(3X)\f1 .\" index@\f1control functions, terminal output@@@\f3clearok(3X)\f1 .\" .\" links@clearok.3x idleok.3x .\" links@clearok.3x leaveok.3x .\" links@clearok.3x scrollok.3x .\" links@clearok.3x setscrreg.3x .\" links@clearok.3x wsetscrreg.3x .\" .\" fileset_database@clearok.3x CURS-ENG-A-MAN .\" $Header: clock.3c,v 76.1 95/06/20 14:43:52 ssa Exp $ .TA c .TH clock 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clock(\|) \- report \s-1CPU\s0 time used .SH SYNOPSIS .C "#include " .PP .C "clock_t clock(void);" .SH DESCRIPTION .C clock() returns the amount of .SM CPU time (in microseconds) used since the first call to .CR clock() . The time reported is the sum of the user and system times of the calling process and its terminated child processes for which it has executed .C wait() , .C system() or .C pclose() (see .IR wait (2) , .IR system (3S) and .IR popen(3S)). To determine the time in seconds, the value returned by .C clock() should be divided by the value of the macro .CR CLOCKS_PER_SEC . .PP The resolution of the clock varies, depending on the hardware and on software configuration. .PP If the processor time used is not available or its value cannot be represented, the function returns the value .RC ( clock_t )\|\(mi\|1. .SH WARNINGS The value returned by .C clock() is defined in microseconds for compatibility with systems that have .SM CPU clocks with much higher resolution. Because of this, the value returned wraps around after accumulating only 4295 seconds of .SM CPU time (about 72 minutes). .SH DEPENDENCIES The default clock resolution is 10 milliseconds. .SH SEE ALSO times(2), wait(2), system(3S). .SH STANDARDS CONFORMANCE .CR clock() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4clock()\fP \- report \s-1CPU\s+1 time used@@@\f3clock(3C)\f1 .\" index@report \s-1CPU\s+1 time used@@@\f3clock(3C)\f1 .\" index@\s-1CPU\s+1 time used, report@@@\f3clock(3C)\f1 .\" index@time used, report \s-1CPU\s+1@@@\f3clock(3C)\f1 .\" .\" toc@\f3clock(3C)\f1:\0\0\f4clock()\fP@@@report \s-1CPU\s+1 time used .\" .\" fileset_database@clock.3c PROGRAMING-MAN .\" $Header: clock.3x,v 72.3 93/01/14 14:45:06 ssa Exp $ .TA c .TH clock 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clock(\|) \- return the \s-1MPE\s0 clock value .SH SYNOPSIS .C "#include " .PP .C "unsigned int clock(void);" .SH DESCRIPTION This routine returns the clock value in the MPE format. .SH RETURN VALUE .PP .C clock() returns an unsigned int in the format: .PP .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|0#7#\|8#15 \&#_#_#_#_ #Hour of Day##Minute of Hour# \&#_#_#_#_ .TE .sp .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|16#23#\|24#31 \&#_#_#_#_ #Seconds##Tenths of Seconds# \&#_#_#_#_ .TE .SH WARNINGS This routine is provided for compatibility with the .SM HP MPE operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described in .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C clock() was developed by HP. .SH SEE ALSO nlconvclock(3X), nlfmtclock(3X), portnls(5). .\" index@\f4clock()\fP \- return the \s-1MPE\s+1 clock value@@@\f3clock(3X)\f1 .\" index@\s-1MPE\s+1 clock value, return the@@@\f3clock(3X)\f1 .\" index@clock value, \s-1MPE\s+1, return the@@@\f3clock(3X)\f1 .\" .\" toc@\f3clock(3X)\f1:\0\0\f4clock()\fP@@@return the \s-1MPE\s+1 clock value .\" .\" fileset_database@clock.3x PROGRAMING-MAN .\" $Header: directory.3c,v 76.1 95/07/05 17:28:05 ssa Exp $ .TA d .TH directory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME opendir(\|), readdir(\|), readdir_r(\|), telldir(\|), seekdir(\|), rewinddir(\|), closedir(\|) \- directory operations .SH SYNOPSIS .C "#include " .PP .C "DIR *opendir(const char *dirname);" .PP .C "struct dirent *readdir(DIR *dirp);" .PP .C "int readdir_r(DIR *dirp, struct dirent *result);" .PP .C "long int telldir(DIR *dirp);" .PP .C "void seekdir(DIR *dirp, long int loc);" .PP .C "void rewinddir(DIR *dirp);" .PP .C "int closedir(DIR *dirp);" .SH DESCRIPTION This library package provides functions that allow programs to read directory entries without having to know the actual directory format associated with the file system. Because these functions allow programs to be used portably on file systems with different directory formats, this is the recommended way to read directory entries. .TP 15 .CR opendir() opens the directory .I dirname and associates a directory stream with it. .CR opendir() returns a pointer used to identify the directory stream in subsequent operations. .CR opendir() uses .IR malloc (3C) to allocate memory. .TP .CR readdir() returns a pointer to the next directory entry. It returns a .SM NULL pointer upon reaching the end of the directory or detecting an invalid .CR seekdir() operation. See .IR dirent (5) for a description of the fields available in a directory entry. .TP .CR readdir_r() expects to be passed the address of a .CR "struct dirent" and will store the result at the supplied location. .TP .CR telldir() returns the current location (encoded) associated with the directory stream to which .IR dirp refers. .TP .CR seekdir() sets the position of the next .CR readdir() operation on the directory stream to which .IR dirp refers. The .IR loc argument is a location within the directory stream obtained from .CR telldir() . The position of the directory stream is restored to where it was when .CR telldir() returned that .I loc value. Values returned by .CR telldir() are valid only while the .CR DIR pointer from which they are derived remains open. If the directory stream is closed and then reopened, the .CR telldir() value might be invalid. .TP .CR rewinddir() resets the position of the directory stream to which .IR dirp refers to the beginning of the directory. It also causes the directory stream to refer to the current state of the corresponding directory, as a call to .CR opendir() would have done. .TP .CR closedir() closes the named directory stream, then frees the structure associated with the .CR DIR pointer. .SH RETURN VALUE .TP 15 .CR opendir() , upon successful completion, returns a pointer to an object of type .CR DIR referring to an open directory stream. Otherwise, it returns a .SM NULL pointer and sets the global variable .CR errno to indicate the error. .TP .CR readdir() , upon successful completion, returns a pointer to an object of type .CR struct dirent describing a directory entry. Upon reaching the end of the directory, .CR readdir() returns a .SM NULL pointer and does not change the value of .CR errno . Otherwise, it returns a .SM NULL pointer and sets .CR errno to indicate the error. .TP .CR readdir_r() , upon successful completion, returns a 0. Upon reaching the end of directory or encountering an error, it returns a -1 and sets .CR errno to indicate the error. .TP .CR telldir() , upon successful completion, returns a long value indicating the current position in the directory. Otherwise it returns .CR \-1 and sets .CR errno to indicate the error. .TP .CR seekdir() does not return any value, but if an error is encountered, .CR errno is set to indicate the error. .TP .CR closedir() , upon successful completion, returns a value of .CR 0 . Otherwise, it returns a value of .CR \-1 and sets .CR errno to indicate the error. .SH ERRORS .CR opendir() fails if any of the following conditions are encountered: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of .IR dirname , or read permission is denied for .IR dirname . .TP .SM [EFAULT] .I dirname points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the path name. .TP .SM [EMFILE] Too many open file descriptors are currently open for the calling process. .TP .SM [ENAMETOOLONG] A component of .IR dirname exceeds .CR PATH_MAX bytes, or the entire length of .IR dirname exceeds .CR PATH_MAX \(mi 1 bytes while .CR _POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] Too many open file descriptors are currently open on the system. .TP .SM [ENOENT] A component of .I dirname does not exist. .TP .SM [ENOMEM] .CR malloc() failed to provide sufficient memory to process the directory. .TP .SM [ENOTDIR] A component of .I dirname is not a directory. .TP .SM [ENOENT] The .IR dirname argument points to an empty string. .RE .PP .CR readdir() " or " readdir_r() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] The directory stream to which .IR dirp refers is not located at a valid directory entry. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR telldir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR seekdir() might fail if the following condition is encountered: .RS .TP 20 .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR closedir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP 20 .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR rewinddir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .SH EXAMPLES The following code searches the current directory for an entry .IR name : .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 DIR *dirp; struct dirent *dp; dirp = opendir("."); while ((dp = readdir(dirp)) != NULL) { if (strcmp(dp->d_name, name) == 0) { (void) closedir(dirp); return FOUND; } } (void) closedir(dirp); return NOT_FOUND; .ft .ps .fi .RE .SH WARNINGS .CR readdir() and .CR getdirentries() (see .IR getdirentries (2) are the only ways to access remote .SM NFS directories. Attempting to read a remote directory via .SM NFS by using .CR read() returns .CR \-1 and sets .CR errno to .SM EISDIR (see .IR read (2)). .PP .CR readdir() is unsafe in multi-thread applications. .CR readdir_r() is MT-Safe and should be used instead. Users of .CR readdir_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH APPLICATION USAGE The header file required for these functions and the type of the return value from .CR readdir() has been changed for compatibility with System V Release 3 and the .IR "X/Open Portability Guide" . See .IR ndir (5) for a description of the header file .RC < ndir.h >, which is provided to allow existing .SM HP-UX applications to compile unmodified. .PP New applications should use the .RC < dirent.h > header file for portability to System V and X/Open systems. .SH AUTHOR .CR directory was developed by AT&T, HP, and the University of California, Berkeley. .SH SEE ALSO close(2), getdirentries(2), lseek(2), open(2), read(2), dir(4), dirent(5), ndir(5). .SH STANDARDS CONFORMANCE .CR closedir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR opendir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR readdir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR rewinddir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR seekdir() ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR telldir() ": AES, XPG2, XPG3, XPG4" .\" .\" index@\f4opendir()\f1 \- open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f4readdir()\f1 \- get pointer to current entry in open directory@@@\f3directory(3C)\f1 .\" index@\f4telldir()\f1 \- get current location of named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4seekdir()\f1 \- set position of next \f4readdir()\f1 operation on named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4rewinddir()\f1 \- reset position of named \f2directory stream\f1 to beginning of directory@@@\f3directory(3C)\f1 .\" index@\f4closedir()\f1 \- close a currently open directory@@@\f3directory(3C)\f1 .\" index@open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f2directory stream\f1, directory and associated, open for access@@@\f3directory(3C)\f1 .\" index@open, access, or close a directory@@@\f3directory(3C)\f1 .\" index@close, access, or open a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@directory: access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" .\" toc@\f3directory(3C)\f1:\0\0\f4directory()\f1, \f4opendir()\f1, \f4readdir()\f1, \f4telldir()\f1, \f4seekdir()\f1, \f4rewinddir()\f1,\n\f4closedir()\f1@@@directory operations .\" toc@\f4opendir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4readdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4telldir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4seekdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4rewinddir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4closedir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" .\" links@directory.3c opendir.3c .\" links@directory.3c readdir.3c .\" links@directory.3c readdir_r.3c .\" links@directory.3c telldir.3c .\" links@directory.3c seekdir.3c .\" links@directory.3c rewinddir.3c .\" links@directory.3c closedir.3c .\" $Header: syslog.3c,v 76.1 95/07/05 17:52:44 ssa Exp $ .TA s .TH syslog 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME syslog(\|), openlog(\|), closelog(\|), setlogmask(\|) \- control system log .SH SYNOPSIS .C "#include " .PP .C "void syslog(int priority, const char *message, ...);" .PP .C "void openlog(const char *ident, int logopt, int facility);" .PP .C "void closelog(void);" .PP .C "int setlogmask(int maskpri);" .SS Remarks The ANSI C "\c .CR ", ...\$\c" " construct denotes a variable length argument list whose optional [or required] \" EDITOR: make this line fit the specific page members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION .TP 15 .C syslog() writes a message onto the system log maintained by .CR syslogd (see .IR syslogd (1M)). The message is tagged with .IR priority . The .I message is similar to a .IR printf (3S) format string except that .CR %m is replaced by the error message associated with the current value of .CR errno . A trailing newline is added if needed. .IP This message is read by .CR syslogd and written to the system console, log files, selected users' terminals, or forwarded to .CR syslogd on another host as appropriate. .IP .I priority is encoded as the logical OR of a .I level and a .IR facility . The .I level signifies the urgency of the message, and .I facility signifies the subsystem generating the message. .I facility can be encoded explicitly in .IR priority , or a default .I facility can be set with .CR openlog() (see below). .IP .I level is selected from an ordered list: .RS .RS .TP 20 .C LOG_EMERG A panic condition. This is normally broadcast to all users. .TP .C LOG_ALERT A condition that should be corrected immediately, such as a corrupted system database. .TP .C LOG_CRIT Critical conditions, such as hard device errors. .TP .C LOG_ERR Errors. .TP .C LOG_WARNING Warning messages. .TP .C LOG_NOTICE Conditions that are not error conditions, but should possibly be handled specially. .TP .C LOG_INFO Informational messages. .TP .C LOG_DEBUG Messages that contain information normally of use only when debugging a program. .RE .RE .IP .CR syslog() does not log a message that does not have a .I level set. .IP If .CR syslog() cannot pass the message to .CR syslogd , it attempts to write the message on .CR /dev/console if the .CR LOG_CONS option is set (see below). .TP .C openlog() can be called to initialize the log file, if special processing is needed. .I ident is a string that precedes every message. .I logopt is a mask of bits, logically OR'ed together, indicating logging options. The values for .I logopt are: .RS .RS .TP 20 .C LOG_PID Log the process ID with each message; useful for identifying instantiations of daemons. .TP .C LOG_CONS Force writing messages to the console if unable to send it to .CR syslogd . This option is safe to use in daemon processes that have no controlling terminal because .CR syslog() forks before opening the console. .TP .C LOG_NDELAY Open the connection to .CR syslogd immediately. Normally, the open is delayed until the first message is logged. This is useful for programs that need to manage the order in which file descriptors are allocated. .TP .C LOG_NOWAIT Do not wait for children forked to log messages on the console. This option should be used by processes that enable notification of child termination via .CR SIGCLD , because .CR syslog() might otherwise block, waiting for a child whose exit status has already been collected. .RE .RE .IP .I facility encodes a default facility to be assigned to all messages written subsequently by .CR syslog() with no explicit facility encoded. .IP .RS .RS .TP 20 .C LOG_KERN Messages generated by the kernel. These cannot be generated by any user processes. .TP .C LOG_USER Messages generated by random user processes. This is the default facility identifier if none is specified. .TP .C LOG_MAIL The mail system. .TP .C LOG_DAEMON System daemons, such as .IR inetd (1M), .IR ftpd (1M), etc. .TP .C LOG_AUTH The authorization system: .IR login (1), .IR su (1), .IR getty (1M), etc. .TP .C LOG_LPR The line printer spooling system: .IR lp (1), .IR lpsched (1M), etc. .TP .C LOG_LOCAL0 Reserved for local use. Similarly for .CR LOG_LOCAL1 through .CR LOG_LOCAL7 . .RE .RE .TP .C closelog() closes the log file. .TP .C setlogmask() sets the log priority mask to .I maskpri and returns the previous mask. Calls to .CR syslog() with a priority not set in .I maskpri are rejected. The mask for an individual priority .I pri is calculated by the macro .CI LOG_MASK( pri )\c ; the mask for all priorities up to and including .I toppri is given by the macro .CR LOG_UPTO\c .RI ( toppri ). By default, all priorities are logged. .SH ERRORS .CR syslog fails if any of the following conditions are encountered: .RS .TP 15 [EAGAIN] The named pipe .CR /dev/log is blocked for writing. .TP [ENOENT] The named pipe .CR /dev/log bold) could not be opened successfully. .SH EXAMPLES .CR who logs a message regarding some sort of unexpected and serious error: .IP .C "syslog(LOG_ALERT, ""who: internal error 23"");" .PP .CR ftpd uses .CR openlog() to arrange to log its process ID, to log to the console if necessary, and to log in the name of the .I daemon facility: .IP .C "openlog(""ftpd"", LOG_PID|LOG_CONS, LOG_DAEMON);" .PP Arrange to log messages only at levels .CR LOG_ERR and lower: .IP .C setlogmask(LOG_UPTO(LOG_ERR)); .PP Typical usage of .CR syslog() to log a connection: .IP .C "syslog(LOG_INFO,\ ""Connection\ from\ host\ %d"",\ CallingHost);" .PP If the facility has not been set with .CR openlog() , it defaults to .CR LOG_USER . .PP Explicitly set the facility for this message: .IP .C "syslog(LOG_INFO|LOG_LOCAL2,\ ""foobar\ error:\ %m"");" .SH WARNINGS A call to .CR syslog() has no effect unless the syslog daemon .RI ( syslogd (1M)) is running. .CR openlog() does not copy and store the .I ident string internally; it stores only a character pointer. Therefore it is the responsibility of the programmer to make sure that the .I ident argument points to the correct string until the log file is closed. .SH AUTHOR .CR syslog() was developed by the University of California, Berkeley. .SH SEE ALSO logger(1), syslogd(1M). .\" .\" index@\f4syslog()\f1 \- write message onto system log file@@@\f3syslog(3C)\f1 .\" index@\f4openlog()\f1 \- initialize system log file@@@\f3syslog(3C)\f1 .\" index@\f4closelog()\f1 \- close system log file@@@\f3syslog(3C)\f1 .\" index@\f4setlogmask()\f1 \- set system log file priority mask@@@\f3syslog(3C)\f1 .\" index@control system log@@@\f3syslog(3C)\f1 .\" index@system log, control@@@\f3syslog(3C)\f1 .\" index@log, system, control@@@\f3syslog(3C)\f1 .\" .\" toc@\f3syslog(3C)\f1:\0\0\f4syslog()\f1, \f4openlog()\f1, \f4closelog()\f1, \f4setlogmask()\fP@@@control system log .\" toc@\f4openlog()\f1:\0\0control system log@@@see \f3syslog(3C)\f1 .\" toc@\f4closelog()\f1:\0\0control system log@@@see \f3syslog(3C)\f1 .\" toc@\f4setlogmask()\f1:\0\0control system log@@@see \f3syslog(3C)\f1 .\" .\" links@syslog.3c openlog.3c .\" links@syslog.3c closelog.3c .\" links@syslog.3c setlogmask.3c .\" .\" fileset_database@syslog.3c PROGRAMING-MAN .\" $Header: clrtobot.3x,v 76.2 95/07/31 17:27:49 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH clrtobot 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clrtobot, wclrtobot \(em clear from cursor to end of window .SH SYNOPSIS .C "#include " .P .C "int clrtobot(void);" .P .C "int wclrtobot(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn clrtobot and .Fn wclrtobot functions erase all lines following the cursor in the current or specified window, and erase the current line from the cursor to the end of the line, inclusive. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn clrtobot function is explicitly declared as \f3void\f1. .\" .\" toc@\f3clrtobot(3X)\f1:\0\0\f4clrtobot()\f1, \f4wclrtobot()\f1@@@clear from cursor to end of window .\" toc@\f4wclrtobot()\f1: clear from cursor to end of window@@@see \f3clrtobot(3X)\f1 .\" .\" index@\f4clrtobot()\f1 \- clear from cursor to end of window@@@\f3clrtobot(3X)\f1 .\" index@\f4wclrtobot()\f1 \- clear from cursor to end of window@@@\f3clrtobot(3X)\f1 .\" index@\f1clear from cursor to end of window@@@\f3clrtobot(3X)\f1 .\" index@\f1cursor to end of window, clear@@@\f3clrtobot(3X)\f1 .\" index@\f1window, clear from cursor to end of window@@@\f3clrtobot(3X)\f1 .\" .\" links@clrtobot.3x wclrtobot.3x .\" .\" fileset_database@clrtobot.3x CURS-ENG-A-MAN .\" $Header: clrtoeol.3x,v 76.2 95/07/31 17:29:24 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH clrtoeol 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clrtoeol, wclrtoeol \(em clear from cursor to end of line .SH SYNOPSIS .C "#include " .P .C "int clrtoeol(void);" .P .C "int wclrtoeol(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn clrtoeol and .Fn wclrtoeol functions erase the current line from the cursor to the end of the line, inclusive, in the current or specified window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn clrtoeol function is explicitly declared as \f3void\f1. .\" .\" toc@\f3clrtoeol(3X)\f1:\0\0\f4clrtoeol()\f1, \f4wclrtoeol()\f1@@@clear from cursor to end of line .\" toc@\f4wclrtoeol()\f1: clear from cursor to end of line@@@see \f3clrtoeol(3X)\f1 .\" .\" index@\f4clrtoeol()\f1 \- clear from cursor to end of line@@@\f3clrtoeol(3X)\f1 .\" index@\f4wclrtoeol()\f1 \- clear from cursor to end of line@@@\f3clrtoeol(3X)\f1 .\" index@\f1clear from cursor to end of line@@@\f3clrtoeol(3X)\f1 .\" index@\f1cursor, clear from it to end of line@@@\f3clrtoeol(3X)\f1 .\" index@\f1end of line, clear from cursor to end of line@@@\f3clrtoeol(3X)\f1 .\" .\" links@clrtoeol.3x wclrtoeol.3x .\" .\" fileset_database@clrtoeol.3x CURS-ENG-A-MAN .\" $Header: can_change_color.3x,v 76.3 95/10/05 14:12:23 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH can_change_color 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME can_change_color, color_content, has_colors, init_color, init_pair, start_color, pair_content \(em color manipulation functions .SH SYNOPSIS .C "#include " .P .C "bool can_change_color(void);" .P .C "int color_content(short \f2color\fP, short *\f2red\fP, short *\f2green\fP, short *\f2blue\fP);" .P .C "int COLOR_PAIR(int \f2n\fP);" .P .C "bool has_colors(void);" .P .C "int init_color(short \f2color\fP, short \f2red\fP, short \f2green\fP, short \f2blue\fP);" .P .C "int init_pair(short \f2pair\fP, short \f2f\fP, short \f2b\fP);" .P .C "int pair_content(short \f2pair\fP, short *\f2f\fP, short *\f2b\fP);" .P .C "int PAIR_NUMBER(int \f2value\fP);" .P .C "int start_color(void);" .P .C "extern int COLOR_PAIRS;" .P .C "extern int COLORS;" .SH DESCRIPTION These functions manipulate colour on terminals that support colour. .SS "Querying Capabilities" The .Fn has_colors function indicates whether the terminal is a colour terminal. The .Fn can_change_color function indicates whether the terminal is a colour terminal on which colours can be redefined. .SS "Initialisation" The .Fn start_color function must be called in order to enable use of colours and before any colour manipulation function is called. The function initialises eight basic colours (black, blue, green, cyan, red, magenta, yellow, and white) that can be specified by the colour macros (such as COLOR_BLACK) defined in .CR . (See \f3Colour-related Macros\f1 in \f3\f1.) The initial appearance of these eight colours is not specified. .P The function also initialises two global external variables: .RS .TP 3 .C \(bu COLORS defines the number of colours that the terminal supports. (See .B "Colour Identification" below.) If COLORS is 0, the terminal does not support redefinition of colours (and .Fn can_change_colour will return FALSE). .TP .C \(bu COLOR_PAIRS defines the maximum number of colour-pairs that the terminal supports. (See .B "User-Defined Colour Pairs" below.) .RE .P The .Fn start_color function also restores the colours on the terminal to terminal-specific initial values. The initial background colour is assumed to be black for all terminals. .SS "Colour Identification" The .Fn init_color function redefines colour number \f2color\fP, on terminals that support the redefinition of colours, to have the red, green, and blue intensity components specified by \f2red\fP, \f2green\fP, and \f2blue\fP, respectively. Calling .Fn init_color also changes all occurrences of the specified colour on the screen to the new definition. .P The .Fn color_content function identifies the intensity components of colour number \f2color\f1. It stores the red, green, and blue intensity components of this colour in the addresses pointed to by \f2red\fP, \f2green\fP, and \f2blue\fP, respectively. .P For both functions, the .I color argument must be in the range from 0 to and including COLORS\|\(mi\|1. Valid intensity values range from 0 (no intensity component) up to and including 1000 (maximum intensity in that component). .SS "User-Defined Colour Pairs" Calling .Fn init_pair defines or redefines colour-pair number \f2pair\f1 to have foreground colour \f2f\f1 and background colour \f2b\f1. Calling .Fn init_pair changes any characters that were displayed in the colour pair's old definition to the new definition and refreshes the screen. .P After defining the colour pair, the macro COLOR_PAIR(\f2n\fP) returns the value of colour pair \f2n\f1. This value is the colour attribute as it would be extracted from a .CR chtype . Conversely, the macro PAIR_NUMBER(\f2value\fP) returns the colour pair number associated with the colour attribute \f2value\f1. .P The .Fn pair_content function retrieves the component colours of a colour-pair number \f2pair\f1. It stores the foreground and background colour numbers in the variables pointed to by \f2f\f1 and \f2b\fP, respectively. .P With .Fn init_pair and .Fn pair_content , the value of \f2pair\f1 must be in a range from 0 to and including COLOR_PAIRS\|\(mi\|1. (There may be an implementation-specific lower limit on the valid value of \f2pair\fP, but any such limit is at least 63.) Valid values for \f2f\f1 and \f2b\f1 are the range from 0 to and including COLORS\|\(mi\|1. .SH "RETURN VALUE" The .Fn has_colors function returns TRUE if the terminal can manipulate colors; otherwise, it returns FALSE. .P The .Fn can_change_color function returns TRUE if the terminal supports colors and can change their definitions; otherwise, it returns FALSE. .P Upon successful completion, the other functions return OK; otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" To use these functions, .Fn start_color must be called, usually right after .CR initscr() . .P The .Fn can_change_color and .Fn has_colors functions facilitate writing terminal-independent programs. For example, a programmer can use them to decide whether to use colour or some other video attribute. .P On color terminals, a typical value of COLORS is 8 and the macros such as COLOR_BLACK return a value within the range from 0 to and including 7. However, applications cannot rely on this to be true. .SH "SEE ALSO" attroff(), delscreen(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3can_change_color(3X)\f1:\0\0\f4can_change_color()\f1, \f4color_content()\f1, \f4has_colors()\f1, \f4init_color()\f1, \n\f4init_pair()\f1, \f4start_color()\f1, \f4pair_content()\f1@@@color manipulation functions .\" toc@\f4color_content()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4has_colors()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4init_colors()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4init_pair()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4start_color()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4pair_content()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" .\" index@\f4can_change_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4color_content()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4has_colors()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4init_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4init_pair()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4start_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4pair_content()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f1color manipulation functions@@@\f3can_change_color(3X)\f1 .\" .\" links@can_change_color.3x color_content.3x .\" links@can_change_color.3x has_colors.3x .\" links@can_change_color.3x init_color.3x .\" links@can_change_color.3x init_pair.3x .\" links@can_change_color.3x start_color.3x .\" links@can_change_color.3x pair_content.3x .\" .\" fileset_database@can_change_color.3x CURS-ENG-A-MAN .\" $Header: attr_get.3x,v 76.2 95/07/31 11:21:27 ssa Exp $ .TA a .de Fn .C \\$1() .. .de Hd .BR <\\$1> .. .TH attr_get 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attr_get, attr_off, attr_on, attr_set, color_set, wattr_get, wattr_off, wattr_on, wattr_set, wcolor_set \(em window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attr_get(attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int attr_off(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_on(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_set(attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int color_set(short \f2color\fP);" .P .C "int wattr_get(WINDOW *\f2win\fP, attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wattr_off(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_on(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_set(WINDOW *\f2win\fP, attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wcolor_set(WINDOW *\f2win\fP, short \f2color\fP);" .SH DESCRIPTION These functions manipulate the attributes and color of the window rendition of the current or specified window. .P The .Fn attr_get and .Fn wattr_get functions obtain the current rendition of a window. .P The .Fn attr_off and .Fn wattr_off functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_on and .Fn wattr_on functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_set and .Fn wattr_set functions set the window rendition of the current or specified window to \f2attrs\f1 and \f2color\f1. .P The .Fn color_set and .Fn wcolor_set functions set the window color of the current or specified window to color. .P The \f2opts\f1 argument is reswerved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" These functions always return OK. .SH ERRORS No errors are defined. .SH "SEE ALSO" attroff(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3attr_get(3X)\f1:\0\0\f4attr_off()\f1, \f4attr_on()\f1, \f4attr_set()\f1, \f4color_set()\f1, \f4wattr_get()\f1, \f4wattr_off()\f1, \n\f4wattr_on()\f1, \f4wattr_set()\f1, \f4wcolor_set()\f1@@@window attribute control functions .\" toc@\f4attr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_get()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4color_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wcolor_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" .\" index@\f4attr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4color_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wcolor_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1attribute, for window, control functions@@@\f3attr_get(3X)\f1 .\" index@\f1control functions for window attribute@@@\f3attr_get(3X)\f1 .\" .\" links@attr_get.3x attr_set.3x .\" links@attr_get.3x attr_off.3x .\" links@attr_get.3x attr_on.3x .\" links@attr_get.3x wattr_set.3x .\" links@attr_get.3x wattr_get.3x .\" links@attr_get.3x wattr_off.3x .\" links@attr_get.3x wattr_on.3x .\" links@attr_get.3x color_set.3x .\" links@attr_get.3x wcolor_set.3x .\" .\" fileset_database@attr_get.3x CURS-ENG-A-MAN .\" $Header: cols.3x,v 76.2 95/07/31 17:30:41 ssa Exp $ .TA C .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH COLS 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME COLS \(em number of columns on terminal screen .SH SYNOPSIS .C "#include " .P .C "extern int COLS;" .SH DESCRIPTION The external variable .I COLS indicates the number of columns on the terminal screen. .SH "SEE ALSO" initscr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4COLS\f1 \- number of columns on terminal screen@@@\f3COLS(3X)\f1 .\" index@\f1number of columns on terminal screen@@@\f3COLS(3X)\f1 .\" index@\f1terminal screen, number of columns@@@\f3COLS(3X)\f1 .\" index@\f1screen, number of columns@@@\f3COLS(3X)\f1 .\" index@\f1columns, number of, on terminal screen@@@\f3COLS(3X)\f1 .\" .\" toc@\f3COLS(3X)\f1:\0\0\f4COLS\f1@@@number of columns on terminal screen .\" .\" fileset_database@COLS.3x CURS-ENG-A-MAN .\" $Header: regexp.3x,v 72.5 94/11/15 09:56:02 ssa Exp $ .TA r .TH regexp 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compile(\|), step(\|), advance(\|) \- regular expression compile and match routines .SH SYNOPSIS .C #define INIT .I "declarations" .br .C #define GETC() .I "getc statements" .br .C #define PEEKC() .I "peekc statements" .br .C #define UNGETC(c) .I "ungetc statements" .br .C #define RETURN(pointer) .I "return statements" .br .C #define ERROR(val) .I "error statements" .PP .C "#include " .PP .C "char *compile(" .nf .PD 0 .IP .C "const char *instring," .C "char *expbuf," .C "const char *endbuf," .C "int eof" .PP .C ");" .PD .fi .PP .C "int step(const char *string, const char *expbuf);" .PP .C "int advance(const char *string, const char *expbuf);" .PP .C "extern char *loc1, *loc2, *locs;" .PP .C "extern int circf, sed, nbra;" .SS Remarks Features documented in this manual entry are obsolescent and may be removed in a future .SM HP-UX release. Use of .IR regcomp (3C) functions instead is recommended. .SH DESCRIPTION These functions are general-purpose regular expression matching routines to be used in programs that perform Basic Regular Expression (see .IR regexp (5)) matching. These functions are defined in .RC < regexp.h >. .PP The functions .C step() and .C advance() do pattern matching given a character string and a compiled regular expression as input. .C compile() takes a Basic Regular Expression as input and produces a compiled expression that can be used with .C step() and .CR advance() . .PP The interface to this file is unpleasantly complex. Programs that include this file must have the following five macros declared before the .C #include statement. These macros are used by the .C compile() routine. .TP 15 .C GETC() Return the value of the next byte in the regular expression pattern. Successive calls to .C GETC() should return successive bytes of the regular expression. .TP .C PEEKC() Return the next byte in the regular expression. Successive calls to .C PEEKC() should return the same byte (which should also be the next byte returned by .CR GETC() . .TP .CI UNGETC( c ) Cause the argument .I c to be returned by the next call to .C GETC() (and .CR PEEKC() ). No more than one byte of pushback is ever needed, and this byte is guaranteed to be the last byte read by .CR GETC() . The value of the macro .CI UNGETC( c ) is always ignored. .TP .CI RETURN( pointer ) This macro is used on normal exit of the .C compile() routine. The value of the argument .I pointer is a pointer to the character after the last character of the compiled regular expression. This is useful to programs that must manage memory allocation. .TP .CI ERROR( val ) This is the abnormal return from the .C compile() routine. The argument .I val is an error number (see table below for meanings). This call should never return. .RS .RS .PD 0 .TP 8 .B Error .B Meaning .TP 11 Range endpoint too large. .TP 16 Bad number. .TP 25 ``\f3\e\f2digit\f1'' out of range. .TP 36 Illegal or missing delimiter. .TP 41 No remembered search string. .TP 42 .C \e( \e) imbalance. .TP 43 Too many .CR \e( . .TP 44 More than 2 numbers given in .CR \e{\0\e} . .TP 45 .C } expected after .CR \e . .TP 46 First number exceeds second in .CR \e{\0\e} . .TP 49 .C [ ] imbalance. .TP 50 Regular expression overflow. .RE .RE .PD .PP The syntax of the .C compile() routine is as follows: .IP .CI compile( instring , .CI expbuf , .CI endbuf , .CI eof ) .PP The first parameter .I instring is never used explicitly by the .C compile() routine, but is useful for programs that pass down different pointers to input characters. It is sometimes used in the .C INIT declaration (see below). Programs that call functions to input characters or have characters in an external array can pass down a value of .C ((char *) 0) for this parameter. .PP The next parameter .I expbuf is a character pointer. It points to the location where the compiled regular expression will be placed. .PP The parameter .I endbuf is one more than the highest address where the compiled regular expression can be placed. If the compiled expression cannot fit in .RI ( endbuf \|\(mi\| expbuf ) bytes, a call to .C ERROR(50) is made. .PP The parameter .I eof is the character which marks the end of the regular expression. For example, in .IR ed (1), this character is usually a .CR / . .PP Each program that includes this file must have a .C #define statement for .CR INIT . This definition is placed right after the declaration for the function .C compile() and the opening curly brace .CR { . It is used for dependent declarations and initializations. Most often it is used to set a register variable to point to the beginning of the regular expression so that this register variable can be used in the declarations for .CR GETC() , .CR PEEKC() , and .CR UNGETC() . Otherwise it can be used to declare external variables that might be used by .CR GETC() , .CR PEEKC() , and .CR UNGETC() . See the example below of the declarations taken from .IR grep (1). .PP .C step() also performs actual regular expression matching in this file. The call to .I step is as follows: .IP .CI step( string , .CI expbuf ) .PP The first parameter to .C step() is a pointer to a string of characters to be checked for a match. This string should be null-terminated. .PP The second parameter .I expbuf is the compiled regular expression that was obtained by a call to .CR compile() . .PP .C step() returns non-zero if the given string matches the regular expression, and zero if the expressions do not match. If there is a match, two external character pointers are set as a side effect to the call to .CR step() . The variable set in .C step() is .CR loc1 . This is a pointer to the first character that matched the regular expression. The variable .CR loc2 , which is set by the function .CR advance() , points to the character after the last character that matches the regular expression. Thus, if the regular expression matches the entire line, .C loc1 points to the first character of .I string and .C loc2 points to the null at the end of .IR string . .PP .C step() uses the external variable .CR circf() , which is set by .C compile() if the regular expression begins with .CR ^ . If this is set, .C step() tries to match the regular expression to the beginning of the string only. If more than one regular expression is to be compiled before the first is executed, the value of .I circf should be saved for each compiled expression and .I circf should be set to that saved value before each call to .CR step() . .PP .C advance() is called from .C step() with the same arguments as .CR step() . The purpose of .C step() is to step through the .I string argument and call .C advance() until .C advance() returns non-zero, which indicates a match, or until the end of .I string is reached. To constrain .I string to beginning-of-line in all cases, .C step() need not be called; simply call .CR advance() . .PP When .C advance() encounters a .C * or .C \e{\|\e} sequence in the regular expression, it advances its pointer to the string to be matched as far as possible and recursively calls itself, trying to match the rest of the string to the rest of the regular expression. As long as there is no match, .I advance backs up along the string until it finds a match or reaches the point in the string that initially matched the .C * or .CR \e{\|\e} . It is sometimes desirable to stop this backing up before the initial point in the string is reached. If the external character pointer .C locs is equal to the point in the string at sometime during the backing up process, .C advance() breaks out of the loop that backs up and returns zero. This is used by .IR ed (1) and .IR sed (1) for substitutions done globally (not just the first occurrence, but the whole line) so, for example, expressions such as .C s/y*//g do not loop forever. .PP The additional external variables .C sed and .C nbra are used for special purposes. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions. .PP The .C LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, and the characters matched by character class expressions in regular expressions. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following is an example of how the regular expression macros and calls look from .IR grep (1): .nf .IP .C "#define INIT register char *sp = instring;" .C "#define GETC() (*sp++)" .C "#define PEEKC() (*sp)" .C "#define UNGETC(c) (--sp)" .C "#define RETURN(c) return;" .C "#define ERROR(c) regerr()" .IP .C "#include " \h'.5i'.\|.\|. .C "(void) compile(*argv, expbuf, &expbuf[ESIZE], '\e0');" \h'.5i'.\|.\|. .C "if (step(linebuf, expbuf))" .C " succeed();" .fi .SH AUTHOR .CR regexp() was developed by OSF and HP. .SH SEE ALSO grep(1), regcomp(3C), setlocale(3C), regexp(5). .SH STANDARDS CONFORMANCE .CR advance() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR compile() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc1 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc2 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR locs ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR step() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4compile()\f1 \- regular expression compile routine@@@\f3regexp(3X)\f1 .\" index@\f4step()\f1 \- regular expression string comparison routine@@@\f3regexp(3X)\f1 .\" index@\f4advance()\f1 \- regular expression substring comparison routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1expression, regular, compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1compile and match routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1comparison routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1match routines for regular expressions@@@\f3regexp(3X)\f1 .\" .\" toc@\f3regexp(3X)\f1:\0\0\f4compile()\f1, \f4step()\f1, \f4advance()\f1@@@regular expression compile and match routines .\" toc@\f4compile()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4step()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4advance()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" .\" links@regexp.3x compile.3x .\" links@regexp.3x step.3x .\" links@regexp.3x advance.3x .\" links@regexp.3x INIT.3x .\" links@regexp.3x GETC.3x .\" links@regexp.3x PEEKC.3x .\" links@regexp.3x UNGETC.3x .\" links@regexp.3x RETURN.3x .\" links@regexp.3x ERROR.3x .\" .\" fileset_database@regexp.3x PROGRAMING-MAN .\" $Header: confstr.3c,v 72.4 94/11/14 13:10:38 ssa Exp $ .TA c .TH confstr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME confstr(\|) \- get string-valued configuration values .SH SYNOPSIS .C "#include " .PP .C "size_t confstr(int name, char *buf, size_t len);" .SH DESCRIPTION .C confstr() provides a method for applications to get configuration-defined string values. Its use and purpose are similar to .C sysconf() (see .IR sysconf (2)) function, except that it is used where string values rather than numeric values are returned. .PP The .I name parameter can take on the following .I name values, which are defined in .RC < unistd.h >. .RS .TP 15 .C _CS_PATH A default value for the .C PATH environment variable which can be used to locate commands in Section 1 of the .SM .I HP-UX .I Reference and utilities defined in the .SM POSIX.2 standard that are currently implemented in the .SM HP-UX operating system. .RE .PP If .I len is not zero, and if .I name is known and has a configuration-defined value, .C confstr() copies that value into the .IR len -byte buffer pointed to by .IR buf . If the string to be returned is longer than .I len bytes, including the terminating null, .C confstr() truncates the string to .IR len \|\-\|1 bytes and null-terminates the result. The application can detect that the string was truncated by comparing the value returned by .C confstr() with .IR len . .PP If .I len is zero and .I buf is .SM NULL, .C confstr() returns the integer value as defined below, but does not return a string. If .I len is zero but .I buf is not .SM NULL, the result is unspecified. .SH RETURN VALUE If .I name is invalid, .C confstr() returns zero and sets .C errno to .SM EINVAL. .PP If .I name does not have a configuration-defined value, .C confstr() returns 1 and returns a null string in .IR buf . .PP If .I name has a configuration-defined value, .C confstr() returns the size of buffer that would be needed to hold the entire configuration-defined value. If this return value is less than .IR len , the string returned in .I buf has been truncated. .SH FILES .C /usr/include/unistd.h .SH EXAMPLES The following code fragment calls .C confstr() to determine the correct buffer size for .CR _CS_PATH , allocates space for this buffer, then gets the configuration value for .CR _CS_PATH . .nf .IP .C #include .C #include .IP .C size_t bufsize; .C char *buffer; .IP .C bufsize=confstr(_CS_PATH,NULL,(size_t)0); .C buffer=(char *)malloc(bufsize); .C confstr(_CS_PATH,buffer,bufsize); .fi .SH AUTHOR .C confstr() was developed by HP. .SH SEE ALSO getconf(1), errno(2), sysconf(2), pathconf(2), fpathconf(2), malloc(3C). .SH STANDARDS CONFORMANCE .CR confstr() ": XPG4, POSIX.2" .\" .\" index@\f4confstr()\fP \- get string-valued configuration values@@@\f3confstr(3C)\f1 .\" index@string-valued configuration values, get@@@\f3confstr(3C)\f1 .\" index@configuration values, get string-valued@@@\f3confstr(3C)\f1 .\" index@values, get string-valued configuration@@@\f3confstr(3C)\f1 .\" .\" toc@\f3confstr(3C)\f1:\0\0\f4confstr()\fP@@@get string-valued configuration values .\" .\" fileset_database@confstr.3c PROGRAMING-MAN .\" $Header: conv.3c,v 72.7 94/11/28 08:25:12 ssa Exp $ .TA c .TH conv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME toupper(\|), tolower(\|), _toupper(\|), _tolower(\|), toascii(\|) \- translate characters .SH SYNOPSIS .C "#include " .PP .C "int toupper(int c);" .PP .C "int tolower(int c);" .PP .C "int _toupper(int c);" .PP .C "int _tolower(int c);" .PP .C "int toascii(int c);" .SH DESCRIPTION .C toupper() and .C tolower() have as domain the range of .IR getc (3S): the integers from \(mi1 through 255. If the argument of .C toupper() represents a lower-case letter, the result is the corresponding upper-case letter. If the argument of .C tolower() represents an upper-case letter, the result is the corresponding lower-case letter. All other arguments in the domain are returned unchanged. Arguments outside the domain cause undefined results. .PP The macros .C _toupper() and .C _tolower() are identical to .C toupper() and .CR tolower() , respectively. .PP .C toascii() yields its argument with all bits that are not part of a standard 7-bit .SM ASCII character cleared; it is intended for compatibility with other systems. .SH WARNING .C toascii() is supplied both as a library function and as a macro defined in the .RC < ctype.h > header. Normally, the macro version is used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI C mode, enclose the function name in parenthesis or take its address. The following examples use the library function for .CR toascii() : .nf .IP .C #include .C #undef toascii \h'.4i'... .C main() .C { \h'.5i'... .C " c1 = toascii(c);" \h'.5i'... .C } .PP or .IP .C #include \h'.4i'... .C main() .C { .C " int (*conv_func)();" \h'.5i'... .C " c1 = (toascii)(c);" \h'.5i'... .C " conv_func = toascii;" \h'.5i'... .C } .fi .PP The following example use the library function for .CR toupper() : .nf .IP .C #include .C #undef toupper \h'.4i'... .C main() .C { \h'.5i'... char *c; *c=toupper ((unsigned char*) c); \h'.5i'... .C } .PP .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the translations to be done. .SS International Code Set Support Single-byte character code sets are supported. .SH AUTHOR .CR conv() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), getc(3S), setlocale(3C), lang(5). .SH STANDARDS CONFORMANCE .CR _tolower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR _toupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR toascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR tolower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR toupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4conv()\f1, \- translate characters@@@\f3conv(3C)\f1 .\" index@\f4toupper()\fP, \f2_toupper\f1, \- translate characters to upper-case@@@\f3conv(3C)\f1 .\" index@\f4tolower()\fP, \f2_tolower\f1 \- translate characters to lower-case@@@\f3conv(3C)\f1 .\" index@\f4toascii()\fP \- translate characters to 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1translate characters to upper-case, lower-case, or 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1characters, translate to upper-case, lower-case, or 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1upper-case, translate characters to@@@\f3conv(3C)\f1 .\" index@\f1lower-case, translate characters to@@@\f3conv(3C)\f1 .\" index@\s-1ASCII\s+1, 7-bit, translate characters to@@@\f3conv(3C)\f1 .\" .\" toc@\f3conv(3C)\f1:\0\0\f4toupper()\fP, \f4tolower()\fP, \f2_toupper\f1, \f2_tolower\f1, \f4toascii()\fP@@@translate characters .\" .\" toc@\f4toupper()\fP, \f2_toupper\f1:\0\0translate characters@@@see \f3conv(3C)\f1 .\" toc@\f4tolower()\fP, \f2_tolower\f1:\0\0translate characters@@@see \f3conv(3C)\f1 .\" toc@\f4toascii()\fP:\0\0translate characters@@@see \f3conv(3C)\f1 .\" .\" links@conv.3c toupper.3c .\" links@conv.3c tolower.3c .\" links@conv.3c _toupper.3c .\" links@conv.3c _tolower.3c .\" links@conv.3c toascii.3c .\" .\" fileset_database@conv.3c PROGRAMING-MAN .\" $Header: getdvagent.3,v 72.3 94/07/05 17:58:22 ssa Exp $ .TA g .TH getdvagent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getdvagent, getdvagnam, setdvagent, enddvagent, putdvagnam, copydvagent \- manipulate device assignment database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct dev_asg \(**getdvagent(\|);" .PP .CR "struct dev_asg \(**getdvagnam(const char \(**name);" .PP .CR "void setdvagent(\|);" .PP .CR "void enddvagent(\|);" .PP .CR "int putdvagnam(const char \(**name, struct dev_asg \(**dv);" .PP .CR "struct dev_asg \(**copydvagent(struct dev_asg \(**dv);" .fi .SH DESCRIPTION .IR getdvagent , .IR getdvagnam , and .I copydvagent each return a pointer to an object with the following structure containing the broken-out fields of an entry in the Device Assignment database. Each database entry is returned as a .I dev_asg structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v struct dev_field { char *fd_name; /* external name */ char **fd_devs; /* device list */ mask_t fd_type[1]; /* tape, printer, terminal */ char **fd_users; /* authorized user list */ }; .IP /* Device Assignment Database entry */ .IP #define \s-1AUTH_DEV_TYPE\s0 "device type" #define \s-1AUTH_DEV_PRINTER\s0 0 #define \s-1AUTH_DEV_TERMINAL\s0 1 #define \s-1AUTH_DEV_TAPE\s0 2 #define \s-1AUTH_DEV_REMOTE\s0 3 #define \s-1AUTH_MAX_DEV_TYPE\s0 3 #define \s-1AUTH_DEV_TYPE_SIZE\s0 (\s-1WORD_OF_BIT\s0 (\s-1AUTH_MAX_DEV_TY PE\s0) + 1) .IP /* this structure tells which of the corresponding fields * in dev_field are valid (filled). */ struct dev_flag { unsigned short fg_name : 1, fg_devs : 1, fg_type : 1, fg_users : 1, ; }; .IP struct dev_asg { struct dev_field ufld; struct dev_flag uflg; struct dev_field sfld; struct dev_flag sflg; }; .fi .PP The Device Assignment database stores device characteristics that are related to user authorizations and synonyms. On systems supporting network connections, the Device Assignment database stores information about hosts initiating connections. .PP Each entry contains a .IR name , which is a cross reference to the terminal control database, and a list of .IR devices , each of which is a pathname corresponding to that device. This list allows the device assignment software of the trusted system to invalidate all references to a device when re-assigning it. The list is a table of character string pointers, whose last entry is a .SM .B NULL pointer. .PP .I fd_users is a pointer to a null-terminated table of character string pointers referring to user allowed access. .PP For trusted system versions supporting network connections, the device name can be a 12 character host name, where the first 8 characters are the .SM ASCII hex address of the device, and the last 4 characters are .SM ASCII zeroes. For example, a host with Internet address 129.75.0.3 has device name 814b00030000. The trailing four zeroes are for compatibility with ports on terminal concentrators. The SAM API's supports conversion of host name to device name. Thus, sensitivity level ranges and user authorization lists can be enforced on hosts as well as on directly connected terminals. .PP When .I getdvagent is first called, it returns a pointer to the first device assignment entry. Thereafter, it returns a pointer to the next entry, so successive calls can be used to search the database. .I getdvagnam searches from the beginning of the database until an entry with a device name matching .I name is found, and returns a pointer to that entry. If an end of file or an error is encountered on reading, these functions return a .SM .B NULL pointer. .I copydvagent copies a device assignment structure and the fields to which it refers to a newly-allocated data area. Since .IR getdvagent , .IR getdvagnam , and .I putdvagent re-use a static structure when accessing the database, the values of any entry must be saved if these routines are used again. The .I dev_asg structure returned by .I copydvagent can be freed using .I free (see .IR malloc (3C) or .IR malloc (3X)). .PP A call to .I setdvagent has the effect of setting the device assignment database back to the first entry, to allow repeated searches of the database. .I enddvagent frees all memory and closes all files used to support these routines. .PP .I putdvagnam rewrites or adds an entry to the database. If there is an entry whose .I fd_name field matches the .I name argument, that entry is replaced with the contents of the .I dv structure. Otherwise, that entry is added to the database. .SH RETURN VALUE .IR getdvagent and .IR getdvagnam return a pointer to a static structure on success, or a .SM .B NULL pointer on failure. This static structure is overwritten by .IR getdvagent , .IR getdvagnam , and .IR putdvagnam . .PP .I putdvagnam returns 1 on success, or 0 on failure. .PP .I copydvagent returns a pointer to the newly-allocated structure on success, or a .SM .B NULL pointer if there was a memory allocation error. .SH "WARNINGS" The structure returned by this routine contains .I pointers to character strings and lists rather than being self-contained. .I copydvagent must be used instead of structure assignments to save a returned structure. .PP The value returned by .I getdvagent and .I getdvagnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using .I copydvagent and supply the modified buffer to .IR putdvagent . .SH NOTES Programs using this routine must be compiled with .BR \-lsec . .SH AUTHOR SecureWare Inc. .SH FILES .TP 40 .CR /tcb/files/devassign Device assignment database .PD .SH SEE ALSO authcap(4). .\" .\" index@\f4getdvagent\f1 \- return pointer for device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f1getdvagnam\f1 \- return success or failure information@@@\f3getdvagent(3)\f1 .\" index@\f4setdvagent\f1 \- set device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f4enddvagent\f1 \- free memory and close file@@@\f3getdvagent(3)\f1 .\" index@\f4putdvagnam\f1 \- add or rewrite device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f4copydvagent\f1 \- copy device assignment structure@@@\f3getdvagent(3)\f1 .\" index@\f1manipulate device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f1device assignment database entry, manipulate@@@\f3getdvagent(3)\f1 .\" index@\f1assignment database entry, manipulate device@@@\f3getdvagent(3)\f1 .\" index@\f1database entry, manipulate device assignment@@@\f3getdvagent(3)\f1 .\" .\" .\" toc@\f3getdvagent(3)\f1:\0\0\f4getdvagent\f1, \f4getdvagnam\f1, \f4setdvagent\f1, \f4enddvagent\f1, \f4putdvagnam\f1, \n\f4copydvagent\f1@@@manipulate device assignment database entry for a trusted system .\" toc@\f4getdvagent\f1:\0\0return pointer for device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4getdvagnam\f1:\0\0return success or failure information@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4setdvagent\f1:\0\0set device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4enddvagent\f1:\0\0free memory and closes file@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4putdvagnam\f1:\0\0add or rewrite device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4copydvagent\f1:\0\0copy device assignment structure@@@\f1see \f3getdvagent(3)\f1 .\" .\" .\" links@getdvagent.3 getdvagnam.3 .\" links@getdvagent.3 setdvagent.3 .\" links@getdvagent.3 enddvagent.3 .\" links@getdvagent.3 putdvagnam.3 .\" links@getdvagent.3 copydvagent.3 .\" .\" fileset_database@getdvagent.3 UX-CORE-MAN .\" $Header: copysign.3m,v 78.1 96/02/13 09:58:49 ssa Exp $ .TA c .TH copysign 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME copysign(\|), copysignf(\|) \- copysign functions .SH SYNOPSIS .C "#include " .PP .C "double copysign(double x, double y);" .PP .C "float copysignf(float x, float y);" .SH DESCRIPTION The .CR copysign() function is recommended by the IEEE-754 standard for floating-point arithmetic. .PP .CR copysign() returns .I x with its sign changed to the sign of .IR y . .PP .CR copysignf() is a .CR float version of .CR copysign() ; it takes .CR float arguments and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float arguments to .CR double , and the function returns incorrect results. .PP .CR copysignf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH SEE ALSO fpclassify(3M), remainder(3M), scalb(3M). .\" .\" index@\f4copysign()\f1, \f4copysignf()\f1 \- copysign functions@@@\f3copysign(3M)\f1 .\" index@\f4copysignf()\f1, \f4copysign()\f1 \- copysign functions@@@\f3copysign(3M)\f1 .\" index@\f1math: copysign functions@@@\f3copysign(3M)\f1 .\" index@\f1copysign functions@@@\f3copysign(3M)\f1 .\" .\" toc@\f3copysign(3M)\f1:\0\0\f4copysign()\f1, \f4copysignf()\f1@@@copysign functions .\" toc@\f4copysignf()\f1, \f4copysign()\f1:\0\0copysign functions@@@see \f3copysign(3M)\f1 .\" .\" links@copysign.3m copysignf.3m .\" .\" fileset_database@copysign.3m PROGRAMING-MAN .\" $Header: copysign.3m,v 78.1 96/02/13 09:58:49 ssa Exp $ .TA c .TH copysign 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME copysign(\|), copysignf(\|) \- copysign functions .SH SYNOPSIS .C "#include " .PP .C "double copysign(double x, double y);" .PP .C "float copysignf(float x, float y);" .SH DESCRIPTION The .CR copysign() function is recommended by the IEEE-754 standard for floating-point arithmetic. .PP .CR copysign() returns .I x with its sign changed to the sign of .IR y . .PP .CR copysignf() is a .CR float version of .CR copysign() ; it takes .CR float arguments and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float arguments to .CR double , and the function returns incorrect results. .PP .CR copysignf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH SEE ALSO fpclassify(3M), remainder(3M), scalb(3M). .\" .\" index@\f4copysign()\f1, \f4copysignf()\f1 \- copysign functions@@@\f3copysign(3M)\f1 .\" index@\f4copysignf()\f1, \f4copysign()\f1 \- copysign functions@@@\f3copysign(3M)\f1 .\" index@\f1math: copysign functions@@@\f3copysign(3M)\f1 .\" index@\f1copysign functions@@@\f3copysign(3M)\f1 .\" .\" toc@\f3copysign(3M)\f1:\0\0\f4copysign()\f1, \f4copysignf()\f1@@@copysign functions .\" toc@\f4copysignf()\f1, \f4copysign()\f1:\0\0copysign functions@@@see \f3copysign(3M)\f1 .\" .\" links@copysign.3m copysignf.3m .\" .\" fileset_database@copysign.3m PROGRAMING-MAN .\" $Header: copywin.3x,v 76.2 95/07/31 17:32:20 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH copywin 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME copywin \(em copy a region of a window .SH SYNOPSIS .C "#include " .P .C "int copywin(WINDOW * const \f2srcwin\fP, WINDOW *\f2dstwin\fP, int \f2sminrow\fP," .br .C " int \f2smincol\fP, int \f2dminrow\fP, int \f2dmincol\fP, int \f2dmaxrow\fP, " .br .C " int \f2dmaxcol\fP, int \f2overlay\fP);" .SH DESCRIPTION The .Fn copywin function provides a finer granularity of control over the .Fn overlay and .Fn overwrite functions. As in the .CR prefresh() function, a rectangle is specified in the destination window, (\f2dminrow\f1, \f2dmincol\f1) and (\f2dmaxrow\f1, \f2dmaxcol\f1), and the upper-left-corner coordinates of the source window, (\f2sminrow\f1, \f2smincol\f1). If \f2overlay\f1 is TRUE, then copying is non-destructive, as in .CR overlay() . If \f2overlay\f1 is FALSE, then copying is destructive, as in .CR overwrite() . .SH "RETURN VALUE" Upon successful completion, .Fn copywin returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" newpad(), overlay(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4copywin()\f1 \- copy a region of window@@@\f3copywin(3X)\f1 .\" index@\f1copy a region of window@@@\f3copywin(3X)\f1 .\" index@\f1a region of window, copy@@@\f3copywin(3X)\f1 .\" index@\f1window, copy a region of window@@@\f3copywin(3X)\f1 .\" .\" toc@\f3copywin(3X)\f1:\0\0\f4copywin()\f1@@@copy a region of window .\" .\" fileset_database@copywin.3x CURS-ENG-A-MAN .\" $Header: cos.3m,v 78.1 96/02/13 10:13:16 ssa Exp $ .TA c .TH cos 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cos(\|), cosf(\|) \- cosine functions .SH SYNOPSIS .C "#include " .PP .C "double cos(double x);" .PP .C "float cosf(float x);" .SH DESCRIPTION .CR cos() returns the cosine of .I x .RI ( x specified in radians). .PP .CR cos() may lose accuracy when .I x is far from zero. .PP .CR cosf() is a .CR float version of .CR cos() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR cosf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x .ift is NaN or \(+-INFINITY, .ifn is NaN or +\-INFINITY, .CR cos() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR cos() returns zero. .SH ERRORS No errors are defined. .SH DEPENDENCIES Millicode versions of the .CR cos() and .CR cosf() functions are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO cosd(3M), sin(3M), tan(3M), asin(3M), acos(3M), atan(3M), atan2(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR cos() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4cos()\f1 \- cosine function@@@\f3cos(3M)\f1 .\" index@\f4cosf()\f1 \- cosine function (float)@@@\f3cos(3M)\f1 .\" index@\f1cosine functions@@@\f3cos(3M)\f1 .\" index@\f1math: cosine functions@@@\f3cos(3M)\f1 .\" index@\f1trigonometric cosine functions@@@\f3cos(3M)\f1 .\" .\" toc@\f3cos(3M)\f1:\0\0\f4cos()\f1, \f4cosf()\f1@@@cosine functions .\" toc@\f4cosf()\f1:\0\0cosine function (float)@@@see \f3cos(3M)\f1 .\" .\" links@cos.3m cosf.3m .\" .\" fileset_database@cos.3m PROGRAMING-MAN .\" $Header: cosd.3m,v 78.1 96/02/13 10:18:53 ssa Exp $ .TA c .TH cosd 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cosd(\|), cosdf(\|) \- degree-valued cosine functions .SH SYNOPSIS .C "#include " .PP .C "double cosd(double x);" .PP .C "float cosdf(float x);" .SH DESCRIPTION .CR cosd() is a degree-valued version of the .CR cos() function. It returns the cosine of .I x .RI ( x specified in degrees). .PP .CR cosd() may lose accuracy when .I x is far from zero. .PP .CR cosdf() is a .CR float version of .CR cosd() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR cosd() and .CR cosdf() are not specified by any standard, but .CR cosdf() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x .ift is NaN or \(+-INFINITY, .ifn is NaN or +\-INFINITY, .CR cosd() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR cosd() returns zero. .SH ERRORS No errors are defined. .SH SEE ALSO cos(3M), sind(3M), tand(3M), asind(3M), acosd(3M), atand(3M), atan2d(3M), isinf(3M), isnan(3M), values(5). .\" index@\f4cosd()\f1 \- cosine function (degrees)@@@\f3cosd(3M)\f1 .\" index@\f4cosdf()\f1 \- cosine function (float, degrees)@@@\f3cosd(3M)\f1 .\" index@\f1cosine trigonometric function (degrees)@@@\f3cosd(3M)\f1 .\" index@\f1math: cosine functions (degrees)@@@\f3cosd(3M)\f1 .\" index@\f1degree-valued cosine functions@@@\f3cosd(3M)\f1 .\" index@\f1trigonometric cosine functions (degrees)@@@\f3cosd(3M)\f1 .\" .\" toc@\f3cosd(3M)\f1:\0\0\f4cosd()\f1, \f4cosdf()\f1@@@degree-valued cosine functions .\" toc@\f4cosdf()\f1:\0\0cosine function (float, degrees)@@@see \f3cosd(3M)\f1 .\" .\" links@cosd.3m cosdf.3m .\" .\" fileset_database@cosd.3m PROGRAMING-MAN .\" $Header: cosd.3m,v 78.1 96/02/13 10:18:53 ssa Exp $ .TA c .TH cosd 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cosd(\|), cosdf(\|) \- degree-valued cosine functions .SH SYNOPSIS .C "#include " .PP .C "double cosd(double x);" .PP .C "float cosdf(float x);" .SH DESCRIPTION .CR cosd() is a degree-valued version of the .CR cos() function. It returns the cosine of .I x .RI ( x specified in degrees). .PP .CR cosd() may lose accuracy when .I x is far from zero. .PP .CR cosdf() is a .CR float version of .CR cosd() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR cosd() and .CR cosdf() are not specified by any standard, but .CR cosdf() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x .ift is NaN or \(+-INFINITY, .ifn is NaN or +\-INFINITY, .CR cosd() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR cosd() returns zero. .SH ERRORS No errors are defined. .SH SEE ALSO cos(3M), sind(3M), tand(3M), asind(3M), acosd(3M), atand(3M), atan2d(3M), isinf(3M), isnan(3M), values(5). .\" index@\f4cosd()\f1 \- cosine function (degrees)@@@\f3cosd(3M)\f1 .\" index@\f4cosdf()\f1 \- cosine function (float, degrees)@@@\f3cosd(3M)\f1 .\" index@\f1cosine trigonometric function (degrees)@@@\f3cosd(3M)\f1 .\" index@\f1math: cosine functions (degrees)@@@\f3cosd(3M)\f1 .\" index@\f1degree-valued cosine functions@@@\f3cosd(3M)\f1 .\" index@\f1trigonometric cosine functions (degrees)@@@\f3cosd(3M)\f1 .\" .\" toc@\f3cosd(3M)\f1:\0\0\f4cosd()\f1, \f4cosdf()\f1@@@degree-valued cosine functions .\" toc@\f4cosdf()\f1:\0\0cosine function (float, degrees)@@@see \f3cosd(3M)\f1 .\" .\" links@cosd.3m cosdf.3m .\" .\" fileset_database@cosd.3m PROGRAMING-MAN .\" $Header: cos.3m,v 78.1 96/02/13 10:13:16 ssa Exp $ .TA c .TH cos 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cos(\|), cosf(\|) \- cosine functions .SH SYNOPSIS .C "#include " .PP .C "double cos(double x);" .PP .C "float cosf(float x);" .SH DESCRIPTION .CR cos() returns the cosine of .I x .RI ( x specified in radians). .PP .CR cos() may lose accuracy when .I x is far from zero. .PP .CR cosf() is a .CR float version of .CR cos() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR cosf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x .ift is NaN or \(+-INFINITY, .ifn is NaN or +\-INFINITY, .CR cos() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR cos() returns zero. .SH ERRORS No errors are defined. .SH DEPENDENCIES Millicode versions of the .CR cos() and .CR cosf() functions are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO cosd(3M), sin(3M), tan(3M), asin(3M), acos(3M), atan(3M), atan2(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR cos() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4cos()\f1 \- cosine function@@@\f3cos(3M)\f1 .\" index@\f4cosf()\f1 \- cosine function (float)@@@\f3cos(3M)\f1 .\" index@\f1cosine functions@@@\f3cos(3M)\f1 .\" index@\f1math: cosine functions@@@\f3cos(3M)\f1 .\" index@\f1trigonometric cosine functions@@@\f3cos(3M)\f1 .\" .\" toc@\f3cos(3M)\f1:\0\0\f4cos()\f1, \f4cosf()\f1@@@cosine functions .\" toc@\f4cosf()\f1:\0\0cosine function (float)@@@see \f3cos(3M)\f1 .\" .\" links@cos.3m cosf.3m .\" .\" fileset_database@cos.3m PROGRAMING-MAN .\" $Header: cosh.3m,v 78.1 96/02/13 10:24:22 ssa Exp $ .TA c .TH cosh 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cosh(\|), coshf(\|) \- hyperbolic cosine functions .SH SYNOPSIS .C "#include " .PP .C "double cosh(double x);" .PP .C "float coshf(float x);" .SH DESCRIPTION The .CR cosh() function returns the hyperbolic cosine of its argument. .PP .CR coshf() is a .CR float version of .CR cosh() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR coshf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR cosh() returns +INFINITY. .PP If .I x is NaN, .CR cosh() returns NaN. .PP If the correct value would overflow, .CR cosh() returns .CR HUGE_VAL and sets .CR errno to [ERANGE]. .SH ERRORS If .CR cosh() fails, .CR errno is set to the following value. .RS .TP 20 [ERANGE] The correct value would overflow. .RE .SH SEE ALSO sinh(3M), tanh(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR cosh() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4cosh()\f1, \f4coshf()\f1 \- hyperbolic cosine functions@@@\f3cosh(3M)\f1 .\" index@\f4coshf()\f1, \f4cosh()\f1 \- hyperbolic cosine functions@@@\f3cosh(3M)\f1 .\" index@\f1math: hyperbolic cosine functions@@@\f3cosh(3M)\f1 .\" index@\f1hyperbolic cosine functions@@@\f3cosh(3M)\f1 .\" index@\f1cosine functions, hyperbolic@@@\f3cosh(3M)\f1 .\" .\" toc@\f3cosh(3M)\f1:\0\0\f4cosh()\f1, coshf()\f1@@@hyperbolic cosine functions\f1 .\" toc@\f4coshf()\f1:\0\0hyperbolic cosine function (float version)@@@see \f3cosh(3M)\f1 .\" .\" links@cosh.3m coshf.3m .\" .\" fileset_database@cosh.3m PROGRAMING-MAN .\" $Header: cosh.3m,v 78.1 96/02/13 10:24:22 ssa Exp $ .TA c .TH cosh 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cosh(\|), coshf(\|) \- hyperbolic cosine functions .SH SYNOPSIS .C "#include " .PP .C "double cosh(double x);" .PP .C "float coshf(float x);" .SH DESCRIPTION The .CR cosh() function returns the hyperbolic cosine of its argument. .PP .CR coshf() is a .CR float version of .CR cosh() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR coshf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR cosh() returns +INFINITY. .PP If .I x is NaN, .CR cosh() returns NaN. .PP If the correct value would overflow, .CR cosh() returns .CR HUGE_VAL and sets .CR errno to [ERANGE]. .SH ERRORS If .CR cosh() fails, .CR errno is set to the following value. .RS .TP 20 [ERANGE] The correct value would overflow. .RE .SH SEE ALSO sinh(3M), tanh(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR cosh() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4cosh()\f1, \f4coshf()\f1 \- hyperbolic cosine functions@@@\f3cosh(3M)\f1 .\" index@\f4coshf()\f1, \f4cosh()\f1 \- hyperbolic cosine functions@@@\f3cosh(3M)\f1 .\" index@\f1math: hyperbolic cosine functions@@@\f3cosh(3M)\f1 .\" index@\f1hyperbolic cosine functions@@@\f3cosh(3M)\f1 .\" index@\f1cosine functions, hyperbolic@@@\f3cosh(3M)\f1 .\" .\" toc@\f3cosh(3M)\f1:\0\0\f4cosh()\f1, coshf()\f1@@@hyperbolic cosine functions\f1 .\" toc@\f4coshf()\f1:\0\0hyperbolic cosine function (float version)@@@see \f3cosh(3M)\f1 .\" .\" links@cosh.3m coshf.3m .\" .\" fileset_database@cosh.3m PROGRAMING-MAN .\" $Header: cpacl.3c,v 72.3 93/01/14 14:45:24 ssa Exp $ .TA c .TH cpacl 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cpacl(\|), fcpacl(\|) \- copy the access control list (ACL) and mode bits from one file to another .SH SYNOPSIS .C "#include " .PP .C "int cpacl(" .PD 0 .nf .IP .C "const char *fromfile," .C "const char *tofile," .C "mode_t frommode," .C "uid_t fromuid," .C "gid_t fromgid," .C "uid_t touid," .C "gid_t togid" .PP .C ");" .PD .PP .PD 0 .C "int fcpacl(" .IP .C "int fromfd," .C "int tofd," .C "mode_t frommode," .C "uid_t fromuid," .C "gid_t fromgid," .C "uid_t touid," .C "gid_t togid" .PP .C ");" .PD .fi .SS Remarks: To ensure continued conformance with emerging industry standards, features described in this manual entry are likely to change in a future release. .SH DESCRIPTION Both .C cpacl() and .C fcpacl() copy the access control list and mode bits (that is, file access permission bits and miscellaneous mode bits; see .IR chmod (2)) from one file to another, and transfer ownership much like .IR chown (2). .C cpacl() and .C fcpacl() take the following parameters: .RS .TP 3 \(bu Path names .RI ( fromfile and .IR tofile ) or open file descriptors .RI ( fromfd and .IR tofd ). .TP \(bu A mode value .RI ( frommode , typically the .C st_mode value returned by .C stat() \(mi see .IR stat (2)) containing file miscellaneous mode bits which are always copied, and file access permission bits which are copied instead of the access control list if either file is remote. .TP \(bu User .SM ID and group .SM ID of the file .RI ( fromuid , .I touid and .IR fromgid , .IR togid ) for transferring ownership. (Typically .I fromuid and .IR fromgid are the .C st_uid and .C st_gid values returned by .CR stat() , and .IR touid and .IR togid are the return values from .C geteuid() and .C getegid() \(mi see .IR geteuid (2) and .IR getegid (2).) .RE .PP When both files are local, the .C cpacl() routines copy the access control list and call .C chownacl() (see .IR chownacl (3C)) to transfer ownership from the .I fromfile to the .IR tofile , if necessary. .PP .C cpacl() .RC ( fcpacl() ) handles remote copying (via .SM NFS) after recognizing failures of .C getacl() .RC ( fgetacl() ) or .C setacl() .RC ( fsetacl() ) (see .IR setacl (2)). When copying the mode from .I fromfile .RI ( fromfd ) to .I tofile .RI ( tofd ), .C cpacl() copies the entire .I frommode (that is, the file miscellaneous mode bits and the file access permission bits) to .I tofile .RI ( tofd ) using .CR chmod() .RC ( fchmod() ). Some of the miscellaneous mode bits can be turned off; see .IR chmod (2). .PP .C cpacl() .RC ( fcpacl ) can copy an access control list from .I fromfile .RI ( fromfd ) to .I tofile .RI ( tofd ) without transferring ownership, but ensuring error checking and handling of remote files. This is done by passing .I fromuid equal to .I touid and .I fromgid equal to .I togid (that is, four zeros). For remote files, .IR fromuid , .IR touid , .IR fromgid , and .I togid are ignored. .SH RETURN VALUE If successful, .C cpacl() and .C fcpacl() return zero. If an error occurs, they set .C errno to indicate the cause of failure and return a negative value, as follows: .TP \(mi-1 Unable to perform .C getacl() .RC ( fgetacl() ) on a local .I fromfile .RI ( fromfd ). .TP \(mi-2 Unable to perform .C chmod() .RC ( fchmod() ) on .I tofile .RI ( tofd ) to set its file miscellaneous mode bits. .C cpacl() .RC ( fcpacl() ) attempts this regardless of whether a file is local or remote, as long as .I fromfile .RI ( fromfd ) is local. .TP \(mi-3 Unable to perform .C setacl() .RC ( fsetacl() ) on a local .I tofile .RI ( tofd ). As a consequence, the file's optional .SM ACL entries are deleted, its file access permission bits are zeroed, and its miscellaneous mode bits might be altered. .TP \(mi-4 Unable to perform .C chmod() .RC ( fchmod() ) on .I tofile .RI ( tofd ) to set its mode. As a consequence, if .I fromfile .RI ( fromfd ) is local, .IR tofile 's .RI ( tofd 's) optional .SM ACL entries are deleted, its access permission bits are zeroed, and its file miscellaneous mode bits might be altered, regardless of whether the file is local or remote. .SH EXAMPLES The following code fragment gets .I stat information on .C oldfile and copies its file miscellaneous bits and access control list to .C newfile owned by the caller. If either file is remote, only the .C st_mode on .C oldfile is copied. .nf .IP .C #include .C #include .IP .C struct stat statbuf; .IP .C if (stat ("oldfile", & statbuf) < 0) .C error (...); .IP .C if (cpacl ("oldfile", "newfile", statbuf.st_mode, .C statbuf.st_uid, statbuf.st_gid, geteuid(), getegid()) < 0) .C { .C error (...); .C } .fi .SH AUTHOR .C cpacl() and .C fcpacl() were developed by .SM HP. .SH SEE ALSO chown(2), getacl(2), getegid(2), geteuid(2), setacl(2), stat(2). acltostr(3C), chownacl(3C), setentry(3C), strtoacl(3C), acl(5). .\" index@\f4fcpacl()\fP \- copy access control list (\s-1ACL\s+1) to another file@@@\f3cpacl(3C)\f1 .\" index@\f4cpacl()\fP \- copy access control list (\s-1ACL\s+1) to another file@@@\f3cpacl(3C)\f1 .\" index@copy access control list (\s-1ACL\s+1) to another file@@@\f3cpacl(3C)\f1 .\" index@access control list (\s-1ACL\s+1), copy to another file@@@\f3cpacl(3C)\f1 .\" index@file: copy access control list (\s-1ACL\s+1) to another file@@@\f3cpacl(3C)\f1 .\" toc@\f3cpacl(3C)\f1:\0\0\f4cpacl()\fP, \f4fcpacl()\fP@@@copy access control list (\s-1ACL\s+1) to another file .\" toc@\f4fcpacl()\fP: copy access control list (\s-1ACL\s+1) to another file@@@see \f3cpacl(3C)\f1 .\" links@cpacl.3c fcpacl.3c .\" .\" fileset_database@cpacl.3c PROGRAMING-MAN .\" $Header: crt0.3,v 72.4 94/09/02 14:40:25 ssa Exp $ .TA c .TH crt0 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crt0.o, gcrt0.o, mcrt0.o \- execution startup routines .SH DESCRIPTION .PP The C, Pascal, and FORTRAN compilers link in the object files .CR crt0.o , .CR gcrt0.o , or .C mcrt0.o to provide startup capabilities and environments for program execution. All are identical except that .C gcrt0.o and .C mcrt0.o provide additional functionality for .IR gprof (1) and .IR prof (1) profiling support respectively. .PP The following symbols are defined in these object files: .RS .TP 20 .C _\|_argc_value A variable of type .I int containing the number of arguments. .TP .C _\|_argv_value An array of character pointers to the arguments themselves. .TP .C _environ An array of character pointers to the environment in which the program will run. This array is terminated by a null pointer. .TP .SM .C _FPU_MODEL A variable of type .I short containing the FPU model number returned by the FP status instruction. This variable is initialized with data from the kernel. .TP .SM .C _FPU_REVISION A variable of type .I short containing the FPU revision number returned by the FP status instruction. This variable is initialized with data from the kernel. .TP .SM .C _CPU_REVISION A variable of type .I int containing the CPU revision of the machine. This variable is initialized with data from the kernel. .TP .SM .C _SYSTEM_ID A variable of type .I int containing the system id value for an executable program. .TP .SM .C $START$ Execution start address. .TP .C _start A secondary startup routine for C programs, called from .CR $START$ , which in turn calls .CR main . This routine is contained in the C library rather than the .C crt0.o file. For Pascal and F\s-2ORTRAN\s0 programs, this symbol labels the beginning of the outer block (main program) and is generated by the compilers. .TP .C $global$ The initial address of the program's data pointer. The startup code loads this address into general register 27. .TP .C $UNWIND_START The beginning of the stack unwind table. .TP .C $UNWIND_END The end of the stack unwind table. .TP .C $RECOVER_START The beginning of the try/recover table. .TP .C $RECOVER_END The end of the try/recover table. .RE .PP The .C crt0.o file defines a null procedure for .CR _mcount , so programs compiled with profiling can be linked without profiling. .PP The linker defines the following two symbols: .RS .TP 20 .C _\|_text_start The beginning address of the program's text area. .PD 0 .TP .C _\|_data_start The beginning address of the program's data area. .PD .RE .SH AUTHOR The features described in this entry originated from .SM AT&T UNIX System III. .SH SEE ALSO .PD .SS Profiling and Debugging Tools: .TP 18 .IR gprof(1) display call graph profile data .PD 0 .TP .IR monitor(3C) prepare execution profile .TP .IR prof(1) display profile data .TP .IR profil(2) execution time profile .PD .SS System Tools: .TP 18 .IR cc(1) invoke the HP-UX C compiler .PD 0 .TP .IR exec(2) execute a file .TP f77(1) invoke the HP-UX FORTRAN compiler .TP .IR ld(1) invoke the link editor .TP .IR pc(1) invoke the HP-UX Pascal compiler .PD .SS Miscellaneous: .TP 18 .IR end(3C) symbol of the last locations in program .PD .\" .\" index@\f4crt0.o\f1, \f4gcrt0.o\f1, \f4mcrt0.o\f1, \f4frt0.o\f1, \f4mfrt0.o\f1 \- execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4crt0.o\f1, \f4mcrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4gcrt0.o\f1, \f4gfrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4gfrt0.o\f1, \f4gcrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4mcrt0.o\f1, \f4crt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4frt0.o\f1, \f4mfrt0.o\f1 \- F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4mfrt0.o\f1, \f4frt0.o\f1 \- F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@Pascal and C execution startup routines@@@\f3crt0(3)\f1 .\" index@F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@execution startup routines, C, Pascal, and F\s-2ORTRAN\s+2@@@\f3crt0(3)\f1 .\" .\" toc@\f3crt0(3)\f1:\0\0\f4crt0.o\f1, \f4mcrt0.o\f1, \f4frt0.o\f1, \f4mfrt0.o\f1@@@execution startup routines .\" toc@\f4crt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4gcrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4mcrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4frt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4mfrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" .\" links@crt0.3 crt0.o.3 .\" links@crt0.3 gcrt0.o.3 .\" links@crt0.3 mcrt0.o.3 .\" links@crt0.3 frt0.o.3 .\" links@crt0.3 gfrt0.o.3 .\" links@crt0.3 mfrt0.o.3 .\" .\" fileset_database@crt0.3 PROGRAMING-MAN .\" $Header: crt0.3,v 72.4 94/09/02 14:40:25 ssa Exp $ .TA c .TH crt0 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crt0.o, gcrt0.o, mcrt0.o \- execution startup routines .SH DESCRIPTION .PP The C, Pascal, and FORTRAN compilers link in the object files .CR crt0.o , .CR gcrt0.o , or .C mcrt0.o to provide startup capabilities and environments for program execution. All are identical except that .C gcrt0.o and .C mcrt0.o provide additional functionality for .IR gprof (1) and .IR prof (1) profiling support respectively. .PP The following symbols are defined in these object files: .RS .TP 20 .C _\|_argc_value A variable of type .I int containing the number of arguments. .TP .C _\|_argv_value An array of character pointers to the arguments themselves. .TP .C _environ An array of character pointers to the environment in which the program will run. This array is terminated by a null pointer. .TP .SM .C _FPU_MODEL A variable of type .I short containing the FPU model number returned by the FP status instruction. This variable is initialized with data from the kernel. .TP .SM .C _FPU_REVISION A variable of type .I short containing the FPU revision number returned by the FP status instruction. This variable is initialized with data from the kernel. .TP .SM .C _CPU_REVISION A variable of type .I int containing the CPU revision of the machine. This variable is initialized with data from the kernel. .TP .SM .C _SYSTEM_ID A variable of type .I int containing the system id value for an executable program. .TP .SM .C $START$ Execution start address. .TP .C _start A secondary startup routine for C programs, called from .CR $START$ , which in turn calls .CR main . This routine is contained in the C library rather than the .C crt0.o file. For Pascal and F\s-2ORTRAN\s0 programs, this symbol labels the beginning of the outer block (main program) and is generated by the compilers. .TP .C $global$ The initial address of the program's data pointer. The startup code loads this address into general register 27. .TP .C $UNWIND_START The beginning of the stack unwind table. .TP .C $UNWIND_END The end of the stack unwind table. .TP .C $RECOVER_START The beginning of the try/recover table. .TP .C $RECOVER_END The end of the try/recover table. .RE .PP The .C crt0.o file defines a null procedure for .CR _mcount , so programs compiled with profiling can be linked without profiling. .PP The linker defines the following two symbols: .RS .TP 20 .C _\|_text_start The beginning address of the program's text area. .PD 0 .TP .C _\|_data_start The beginning address of the program's data area. .PD .RE .SH AUTHOR The features described in this entry originated from .SM AT&T UNIX System III. .SH SEE ALSO .PD .SS Profiling and Debugging Tools: .TP 18 .IR gprof(1) display call graph profile data .PD 0 .TP .IR monitor(3C) prepare execution profile .TP .IR prof(1) display profile data .TP .IR profil(2) execution time profile .PD .SS System Tools: .TP 18 .IR cc(1) invoke the HP-UX C compiler .PD 0 .TP .IR exec(2) execute a file .TP f77(1) invoke the HP-UX FORTRAN compiler .TP .IR ld(1) invoke the link editor .TP .IR pc(1) invoke the HP-UX Pascal compiler .PD .SS Miscellaneous: .TP 18 .IR end(3C) symbol of the last locations in program .PD .\" .\" index@\f4crt0.o\f1, \f4gcrt0.o\f1, \f4mcrt0.o\f1, \f4frt0.o\f1, \f4mfrt0.o\f1 \- execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4crt0.o\f1, \f4mcrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4gcrt0.o\f1, \f4gfrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4gfrt0.o\f1, \f4gcrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4mcrt0.o\f1, \f4crt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4frt0.o\f1, \f4mfrt0.o\f1 \- F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4mfrt0.o\f1, \f4frt0.o\f1 \- F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@Pascal and C execution startup routines@@@\f3crt0(3)\f1 .\" index@F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@execution startup routines, C, Pascal, and F\s-2ORTRAN\s+2@@@\f3crt0(3)\f1 .\" .\" toc@\f3crt0(3)\f1:\0\0\f4crt0.o\f1, \f4mcrt0.o\f1, \f4frt0.o\f1, \f4mfrt0.o\f1@@@execution startup routines .\" toc@\f4crt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4gcrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4mcrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4frt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4mfrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" .\" links@crt0.3 crt0.o.3 .\" links@crt0.3 gcrt0.o.3 .\" links@crt0.3 mcrt0.o.3 .\" links@crt0.3 frt0.o.3 .\" links@crt0.3 gfrt0.o.3 .\" links@crt0.3 mfrt0.o.3 .\" .\" fileset_database@crt0.3 PROGRAMING-MAN .\" $Header: crypt.3c,v 72.5 94/11/14 13:14:01 ssa Exp $ .TA c .TH crypt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crypt, crypt_r, setkey, setkey_r, encrypt, encrypt_r \- generate hashing encryption .SH SYNOPSIS .nf .C "#include " .C "#include " .fi .PP .C "char *crypt(const char *key, const char *salt);" .PP .C "char *crypt_r(const char *key, const char *salt, CRYPTD *cd);" .PP .C "void setkey(const char *key);" .PP .C "void setkey_r(const char *key, CRYPTD *cd);" .PP .C "void encrypt(char block[64], int edflag);" .PP .C "void encrypt_r(char block[64], int edflag, CRYPTD *cd);" .SH DESCRIPTION .SS crypt(\|): .C crypt() is the password encryption function. It is based on a one way hashing encryption algorithm with variations intended (among other things) to frustrate use of hardware implementations of a key search. .PP .I key is a user's typed password. .I salt is a two-character string chosen from the set .CR [a-zA-Z0-9./] ; this string is used to perturb the hashing algorithm in one of 4096 different ways, after which the password is used as the key to encrypt repeatedly a constant string. The returned value points to the encrypted password. The first two characters are the salt itself. .SS setkey(\|) and encrypt(\|): .C setkey() and .C encrypt() provide (rather primitive) access to the actual hashing algorithm. The argument to .C setkey() is a character array of length 64 containing only the characters with numerical value 0 and 1. If this string is divided into groups of 8, the low-order bit in each group is ignored; this gives a 56-bit key which is set into the machine. This is the key that is used with the hashing algorithm to encrypt or decrypt the string .I block with the function .CR encrypt() . .PP The .I block argument to .C encrypt() is a character array of length 64 containing only the characters with numerical value 0 and 1. The argument array is modified in place to a similar array representing the bits of the argument after having been subjected to the hashing algorithm using the key that was set by .CR setkey() . If .I edflag is zero, the argument is encrypted; if non-zero it is decrypted. .SS Reentrant Interfaces .I cd is a pointer to a CRYPTD object, which is defined in .RC < crypt.h >. .PP For .C crypt_r(), .I cd is used as a buffer to store the result string. .PP In the case of .C setkey_r() and .C encrypt_r(), .I cd is used to hold key information set by the .C setkey_r() call, and used by the .C encrypt_r() call. .SH SEE ALSO crypt(1), login(1), passwd(1), getpass(3C), passwd(4). .SH WARNINGS The return value for .C crypt() points to static data whose content is overwritten by each call. .CR crypt() , .CR setkey() , and .CR encrypt() are unsafe in multi-thread applications. .CR crypt_r() , .CR setkey_r() , and .C encrypt_r() are MT-Safe and should be used instead. .SH STANDARDS CONFORMANCE .CR crypt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR encrypt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR setkey() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4crypt()\f1, \f4setkey()\f1, \f4setkey_r()\f1, \f4encrypt_r()\f1, \f4encrypt()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4setkey()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4setkey_r()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4encrypt()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4encrypt_r()\f1 \- generate hashing encyption@@@\f3crypt(3C)\f1 .\" index@generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@hashing encryption, generate@@@\f3crypt(3C)\f1 .\" index@encryption, hashing, generate@@@\f3crypt(3C)\f1 .\" index@encryption, password@@@\f3crypt(3C)\f1 .\" index@password encryption function@@@\f3crypt(3C)\f1 .\" .\" toc@\f3crypt(3C)\f1:\0\0\f4crypt()\f1, \f4setkey()\f1, \f4setkey_r()\f1, \f4encrypt()\f1, \f4encrypt_r()\f1@@@generate hashing encryption .\" toc@\f4setkey()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4setkey_r()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4encrypt()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4encrypt_r()\f1:\0\0gerneate hashing encryption@@@see \f3crypt(3C)\f1 .\" .\" links@crypt.3c crypt_r.3c .\" links@crypt.3c setkey.3c .\" links@crypt.3c setkey_r.3c .\" links@crypt.3c encrypt.3c .\" links@crypt.3c encrypt_r.3c .\" .\" fileset_database@crypt.3c PROGRAMING-MAN .\" $Header: crypt.3c,v 72.5 94/11/14 13:14:01 ssa Exp $ .TA c .TH crypt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crypt, crypt_r, setkey, setkey_r, encrypt, encrypt_r \- generate hashing encryption .SH SYNOPSIS .nf .C "#include " .C "#include " .fi .PP .C "char *crypt(const char *key, const char *salt);" .PP .C "char *crypt_r(const char *key, const char *salt, CRYPTD *cd);" .PP .C "void setkey(const char *key);" .PP .C "void setkey_r(const char *key, CRYPTD *cd);" .PP .C "void encrypt(char block[64], int edflag);" .PP .C "void encrypt_r(char block[64], int edflag, CRYPTD *cd);" .SH DESCRIPTION .SS crypt(\|): .C crypt() is the password encryption function. It is based on a one way hashing encryption algorithm with variations intended (among other things) to frustrate use of hardware implementations of a key search. .PP .I key is a user's typed password. .I salt is a two-character string chosen from the set .CR [a-zA-Z0-9./] ; this string is used to perturb the hashing algorithm in one of 4096 different ways, after which the password is used as the key to encrypt repeatedly a constant string. The returned value points to the encrypted password. The first two characters are the salt itself. .SS setkey(\|) and encrypt(\|): .C setkey() and .C encrypt() provide (rather primitive) access to the actual hashing algorithm. The argument to .C setkey() is a character array of length 64 containing only the characters with numerical value 0 and 1. If this string is divided into groups of 8, the low-order bit in each group is ignored; this gives a 56-bit key which is set into the machine. This is the key that is used with the hashing algorithm to encrypt or decrypt the string .I block with the function .CR encrypt() . .PP The .I block argument to .C encrypt() is a character array of length 64 containing only the characters with numerical value 0 and 1. The argument array is modified in place to a similar array representing the bits of the argument after having been subjected to the hashing algorithm using the key that was set by .CR setkey() . If .I edflag is zero, the argument is encrypted; if non-zero it is decrypted. .SS Reentrant Interfaces .I cd is a pointer to a CRYPTD object, which is defined in .RC < crypt.h >. .PP For .C crypt_r(), .I cd is used as a buffer to store the result string. .PP In the case of .C setkey_r() and .C encrypt_r(), .I cd is used to hold key information set by the .C setkey_r() call, and used by the .C encrypt_r() call. .SH SEE ALSO crypt(1), login(1), passwd(1), getpass(3C), passwd(4). .SH WARNINGS The return value for .C crypt() points to static data whose content is overwritten by each call. .CR crypt() , .CR setkey() , and .CR encrypt() are unsafe in multi-thread applications. .CR crypt_r() , .CR setkey_r() , and .C encrypt_r() are MT-Safe and should be used instead. .SH STANDARDS CONFORMANCE .CR crypt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR encrypt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR setkey() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4crypt()\f1, \f4setkey()\f1, \f4setkey_r()\f1, \f4encrypt_r()\f1, \f4encrypt()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4setkey()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4setkey_r()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4encrypt()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4encrypt_r()\f1 \- generate hashing encyption@@@\f3crypt(3C)\f1 .\" index@generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@hashing encryption, generate@@@\f3crypt(3C)\f1 .\" index@encryption, hashing, generate@@@\f3crypt(3C)\f1 .\" index@encryption, password@@@\f3crypt(3C)\f1 .\" index@password encryption function@@@\f3crypt(3C)\f1 .\" .\" toc@\f3crypt(3C)\f1:\0\0\f4crypt()\f1, \f4setkey()\f1, \f4setkey_r()\f1, \f4encrypt()\f1, \f4encrypt_r()\f1@@@generate hashing encryption .\" toc@\f4setkey()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4setkey_r()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4encrypt()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4encrypt_r()\f1:\0\0gerneate hashing encryption@@@see \f3crypt(3C)\f1 .\" .\" links@crypt.3c crypt_r.3c .\" links@crypt.3c setkey.3c .\" links@crypt.3c setkey_r.3c .\" links@crypt.3c encrypt.3c .\" links@crypt.3c encrypt_r.3c .\" .\" fileset_database@crypt.3c PROGRAMING-MAN .\" $Header: ctermid.3s,v 72.5 94/11/14 13:14:27 ssa Exp $ .TA c .TH ctermid 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctermid(\|) \- generate file name for terminal .SH SYNOPSIS .C "#include " .PP .C "char *ctermid(char *s);" .SH DESCRIPTION .CR ctermid() generates a string that, when used as a pathname, refers to the the controlling terminal for the current process. .PP If .I s is a .SM NULL pointer, the string is stored in an internal static area, the contents of which are overwritten at the next call to .CR ctermid() , and the address of which is returned. Otherwise, .I s is assumed to point to a character array of at least .CR L_ctermid elements; the path name is placed in this array and the value of .I s is returned. The constant .CR L_ctermid is defined in the .RC < stdio.h > header file. .PP If the process has no controlling terminal, the pathname for the controlling terminal cannot be determined, or some other error occurs, .CR ctermid() returns an empty string. .PP For multi-thread applications, if .I s is a .SM NULL pointer, the operation is not performed and a .SM NULL pointer is returned. .SH NOTES The difference between .CR ctermid() and .CR ttyname() is that .CR ttyname() must be handed a file descriptor and returns the actual name of the terminal associated with that file descriptor, while .CR ctermid() returns a string .RC ( /dev/tty ) that refers to the terminal if used as a file name. (see .IR ttyname (3C)). Thus .CR ttyname() is useful only if the process already has at least one file open to a terminal. .SH SEE ALSO ttyname(3C). .SH STANDARDS CONFORMANCE .CR ctermid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4ctermid()\fP \- generate file name for terminal@@@\f3ctermid(3S)\f1 .\" index@generate file name of controlling terminal@@@\f3ctermid(3S)\f1 .\" index@file name of controlling terminal, generate@@@\f3ctermid(3S)\f1 .\" index@controlling terminal, generate file name of@@@\f3ctermid(3S)\f1 .\" index@terminal, generate file name of controlling@@@\f3ctermid(3S)\f1 .\" .\" toc@\f3ctermid(3S)\f1:\0\0\f4ctermid()\fP@@@generate file name for terminal .\" $Header: ctime.3c,v 76.1 95/07/05 17:27:14 ssa Exp $ .TA c .TH ctime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctime(\|), ctime_r(\|), localtime(\|), localtime_r(\|), gmtime(\|), gmtime_r(\|), mktime(\|), difftime(\|), asctime(\|), asctime_r(\|), timezone(\|), daylight(\|), tzname(\|), tzset(\|) \- convert date and time to string .SH SYNOPSIS .nf .C "#include " .PP .C "char *asctime(const struct tm *timeptr);" .PP .C "int asctime_r(const struct tm *timeptr, char *buffer, int buflen);" .PP .C "char *ctime(const time_t *timer);" .PP .C "int ctime_r(const time_t *timer, char *buffer, int buflen);" .PP .C "double difftime(time_t time1, time_t time0);" .PP .C "struct tm *gmtime(const time_t *timer);" .PP .C "int gmtime_r(const time_t *timer, struct tm *result);" .PP .C "struct tm *localtime(const time_t *timer);" .PP .C "int localtime_r(const time_t *timer, struct tm *result);" .PP .C "time_t mktime(struct tm *timeptr);" .PP .C "extern long timezone;" .PP .C "extern int daylight;" .PP .C "extern char *tzname[2];" .PP .C "void tzset(void);" .fi .SH DESCRIPTION .TP 18 .C asctime() Convert the broken-down time contained in the structure pointed to by .I timeptr and return a pointer to a 26-character string in the form: .RS .IP .C "Sun Sep 16 01:03:52 1973\en\e0" .RE .IP All the fields have constant width. .TP .C asctime_r() is identical to .CR asctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C ctime() Convert the calendar time pointed to by .IR timer , representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: .RS .IP .C asctime(localtime(timer)) .RE .TP .C ctime_r() is identical to .CR ctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C gmtime() Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. .C gmtime() returns a pointer to the .C tm structure described below. .TP .C gmtime_r() is identical to .CR gmtime() , except that .C gmtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C localtime() Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA\c), according to the contents of the TZ environment variable (see Environment Variables below). .C localtime() returns a pointer to the .C tm structure described below. .TP .C localtime_r() is identical to .CR localtime() , except that .C localtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C difftime() Return the difference in seconds between two calendar times: .IR "time1 \(mi time0" . .TP .C mktime() Convert the broken-down time (expressed as local time) in the structure pointed to by .I timeptr into a calendar time value with the same encoding as that of the values returned by .IR time (2). The original values of the .C tm_wday and .C tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below. .IP A positive or zero value for .C tm_isdst causes .C mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for .C tm_isdst causes .C mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time. .IP Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of .C tm_mday is not set until .C tm_mon and .C tm_year are determined. .C mktime() returns the specified calendar time encoded as a value of type .CR time_t . .IP If the calendar time cannot be represented, the function returns the value .RC ( time_t )\|\(em\|1 and sets .C errno to .CR ERANGE . Note the value .RC ( time_t )\|\(em\|1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and .C errno to reliably detect an error condition. .TP .C tzset() Sets the values of the external variables .IR timezone , .IR daylight , and .I tzname according to the contents of the .C TZ environment variable (independent of any time value). The functions .CR localtime() , .CR mktime() , .CR ctime() , .CR asctime() , and .C strftime() (see .IR strftime (3C)) call .C tzset() and use the values returned in the external variables described below for their operations. .C tzset() can also be called directly by the user. .PP The .RC < time.h > header file contains declarations of all relevant functions and externals. It also contains the .C tm structure, which includes the following members: .RS .PP .nf .ift .ft 4 .ps +1 int tm_sec; /* seconds after the minute - [0,61] */ int tm_min; /* minutes after the hour - [0,59] */ int tm_hour; /* hours - [0,23] */ int tm_mday; /* day of month - [1,31] */ int tm_mon; /* month of year - [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday - [0,6] */ int tm_yday; /* days since January 1 - [0,365] */ int tm_isdst; /* daylight savings time flag */ .ift .ft .ps .fi .PP The value of .C tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available. .RE .PP The external variable .C timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), .C timezone is 5\(**60\(**60). The external variable .C daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable .C tzname[2] contains the local standard and local summer time zone abbreviations as specified by the .C TZ environment variable. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .SS Environment Variables The .C tzset() function uses the contents of .C TZ to set the values of the external variables .CR timezone , .C daylight , and .CR tzname . .C TZ also determines the time zone name substituted for the .C %Z and .C %z directives and the time zone adjustments performed by .CR localtime() , .CR mktime() , and .CR ctime() . Two methods for specifying a time zone within .C TZ are described in .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH "RETURN VALUE" .PP For .C asctime_r() and .C ctime_r(), if the buffer is of insufficient length, -1 is returned. For .C asctime_r(), ctime_r(), gmtime_r(), and .C localtime_r(), if the operation is successful, 0 is returned. .SH WARNINGS The return values for .CR asctime() , .CR ctime() , .CR gmtime() , and .CR localtime() point to static data whose contents is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() are MT-Safe and should be used instead. .PP Users of .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .PP The range of .C tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by .IR time (2) and passed as the .I timer argument does not include accumulated leap seconds. The .C tm structure generated by .C localtime() and .C gmtime() will never reflect any leap seconds. Upon successful completion, .C mktime() forces the value of the .C tm_sec component to the range [0,59]. .PP .CR ctime() , .CR ctime_r() , .CR asctime() , and .CR asctime_r() are considered obsolescent and may be removed in a future release. Use of .IR strftime (3C) is recommended instead. .SH AUTHOR .C ctime() was developed by AT&T and HP. .SH SEE ALSO time(2), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR ctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR asctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR daylight ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR difftime() ": AES, SVID3, XPG4, ANSI C" .PP .CR gmtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR localtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mktime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR timezone ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR tzname ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tzset() ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4asctime()\fP, \f4asctime_r()\f1 \- convert \f3tm\f1 structure date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4ctime()\fP, \f4ctime_r()\f1 \- convert \f4clock()\fP date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4daylight()\fP \- Daylight Savings Time flag@@@\f3ctime(3C)\f1 .\" index@\f4gmtime()\fP, \f4gmtime_r()\fP \- convert date and time to Greenwich Mean Time@@@\f3ctime(3C)\f1 .\" index@\f4localtime()\fP, \f4localtime_r()\fP \- convert date and time to local timezone@@@\f3ctime(3C)\f1 .\" index@\f4timezone()\fP \- difference between \s-1UCT\s+1 and local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzname()\fP \- name of local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzset()\fP \- initialize \f4timezone()\fP, \f4daylight()\fP, and \f4tzname()\fP using \s-1TZ\s+1 variable@@@\f3ctime(3C)\f1 .\" index@\f4mktime()\fP \- convert time into calendar time value@@@\f3ctime(3C)\f1 .\" index@\f4difftime()\fP \- difference between two calendar time values@@@\f3ctime(3C)\f1 .\" index@convert date and time to string@@@\f3ctime(3C)\f1 .\" index@string, convert date and time to@@@\f3ctime(3C)\f1 .\" index@date and time, convert to string@@@\f3ctime(3C)\f1 .\" index@time and date, convert to string@@@\f3ctime(3C)\f1 .\" .\" toc@\f3ctime(3C)\f1:\0\0\f4ctime()\fP, \f4ctime_r()\fP, \f4localtime()\fP, \f4localtime_r()\fP, \f4difftime()\f1, \f4 mktime()\f1, \n\f4gmtime()\fP, \f4gmtime_r()\fP,\f4asctime()\fP, \f4asctime_r()\fP, \f4timezone()\fP, \f4daylight()\fP, \f4tzname()\fP,\n\f4tzset()\f1@@@convert date and time to string .\" toc@\f4ctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4ctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4timezone()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4daylight()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzname()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzset()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4difftime()\fP:\0\0difference between calendar times@@@see \f3ctime(3C)\f1 .\" toc@\f4mktime()\fP:\0\0create calendar time value@@@see \f3ctime(3C)\f1 .\" .\" links@ctime.3c ctime_r.3c .\" links@ctime.3c localtime.3c .\" links@ctime.3c localtime_r.3c .\" links@ctime.3c gmtime.3c .\" links@ctime.3c gmtime_r.3c .\" links@ctime.3c asctime.3c .\" links@ctime.3c asctime_r.3c .\" links@ctime.3c timezone.3c .\" links@ctime.3c daylight.3c .\" links@ctime.3c tzname.3c .\" links@ctime.3c tzset.3c .\" links@ctime.3c difftime.3c .\" links@ctime.3c mktime.3c .\" .\" fileset_database@ctime.3c PROGRAMING-MAN .\" $Header: ctime.3c,v 76.1 95/07/05 17:27:14 ssa Exp $ .TA c .TH ctime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctime(\|), ctime_r(\|), localtime(\|), localtime_r(\|), gmtime(\|), gmtime_r(\|), mktime(\|), difftime(\|), asctime(\|), asctime_r(\|), timezone(\|), daylight(\|), tzname(\|), tzset(\|) \- convert date and time to string .SH SYNOPSIS .nf .C "#include " .PP .C "char *asctime(const struct tm *timeptr);" .PP .C "int asctime_r(const struct tm *timeptr, char *buffer, int buflen);" .PP .C "char *ctime(const time_t *timer);" .PP .C "int ctime_r(const time_t *timer, char *buffer, int buflen);" .PP .C "double difftime(time_t time1, time_t time0);" .PP .C "struct tm *gmtime(const time_t *timer);" .PP .C "int gmtime_r(const time_t *timer, struct tm *result);" .PP .C "struct tm *localtime(const time_t *timer);" .PP .C "int localtime_r(const time_t *timer, struct tm *result);" .PP .C "time_t mktime(struct tm *timeptr);" .PP .C "extern long timezone;" .PP .C "extern int daylight;" .PP .C "extern char *tzname[2];" .PP .C "void tzset(void);" .fi .SH DESCRIPTION .TP 18 .C asctime() Convert the broken-down time contained in the structure pointed to by .I timeptr and return a pointer to a 26-character string in the form: .RS .IP .C "Sun Sep 16 01:03:52 1973\en\e0" .RE .IP All the fields have constant width. .TP .C asctime_r() is identical to .CR asctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C ctime() Convert the calendar time pointed to by .IR timer , representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: .RS .IP .C asctime(localtime(timer)) .RE .TP .C ctime_r() is identical to .CR ctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C gmtime() Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. .C gmtime() returns a pointer to the .C tm structure described below. .TP .C gmtime_r() is identical to .CR gmtime() , except that .C gmtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C localtime() Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA\c), according to the contents of the TZ environment variable (see Environment Variables below). .C localtime() returns a pointer to the .C tm structure described below. .TP .C localtime_r() is identical to .CR localtime() , except that .C localtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C difftime() Return the difference in seconds between two calendar times: .IR "time1 \(mi time0" . .TP .C mktime() Convert the broken-down time (expressed as local time) in the structure pointed to by .I timeptr into a calendar time value with the same encoding as that of the values returned by .IR time (2). The original values of the .C tm_wday and .C tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below. .IP A positive or zero value for .C tm_isdst causes .C mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for .C tm_isdst causes .C mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time. .IP Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of .C tm_mday is not set until .C tm_mon and .C tm_year are determined. .C mktime() returns the specified calendar time encoded as a value of type .CR time_t . .IP If the calendar time cannot be represented, the function returns the value .RC ( time_t )\|\(em\|1 and sets .C errno to .CR ERANGE . Note the value .RC ( time_t )\|\(em\|1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and .C errno to reliably detect an error condition. .TP .C tzset() Sets the values of the external variables .IR timezone , .IR daylight , and .I tzname according to the contents of the .C TZ environment variable (independent of any time value). The functions .CR localtime() , .CR mktime() , .CR ctime() , .CR asctime() , and .C strftime() (see .IR strftime (3C)) call .C tzset() and use the values returned in the external variables described below for their operations. .C tzset() can also be called directly by the user. .PP The .RC < time.h > header file contains declarations of all relevant functions and externals. It also contains the .C tm structure, which includes the following members: .RS .PP .nf .ift .ft 4 .ps +1 int tm_sec; /* seconds after the minute - [0,61] */ int tm_min; /* minutes after the hour - [0,59] */ int tm_hour; /* hours - [0,23] */ int tm_mday; /* day of month - [1,31] */ int tm_mon; /* month of year - [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday - [0,6] */ int tm_yday; /* days since January 1 - [0,365] */ int tm_isdst; /* daylight savings time flag */ .ift .ft .ps .fi .PP The value of .C tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available. .RE .PP The external variable .C timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), .C timezone is 5\(**60\(**60). The external variable .C daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable .C tzname[2] contains the local standard and local summer time zone abbreviations as specified by the .C TZ environment variable. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .SS Environment Variables The .C tzset() function uses the contents of .C TZ to set the values of the external variables .CR timezone , .C daylight , and .CR tzname . .C TZ also determines the time zone name substituted for the .C %Z and .C %z directives and the time zone adjustments performed by .CR localtime() , .CR mktime() , and .CR ctime() . Two methods for specifying a time zone within .C TZ are described in .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH "RETURN VALUE" .PP For .C asctime_r() and .C ctime_r(), if the buffer is of insufficient length, -1 is returned. For .C asctime_r(), ctime_r(), gmtime_r(), and .C localtime_r(), if the operation is successful, 0 is returned. .SH WARNINGS The return values for .CR asctime() , .CR ctime() , .CR gmtime() , and .CR localtime() point to static data whose contents is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() are MT-Safe and should be used instead. .PP Users of .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .PP The range of .C tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by .IR time (2) and passed as the .I timer argument does not include accumulated leap seconds. The .C tm structure generated by .C localtime() and .C gmtime() will never reflect any leap seconds. Upon successful completion, .C mktime() forces the value of the .C tm_sec component to the range [0,59]. .PP .CR ctime() , .CR ctime_r() , .CR asctime() , and .CR asctime_r() are considered obsolescent and may be removed in a future release. Use of .IR strftime (3C) is recommended instead. .SH AUTHOR .C ctime() was developed by AT&T and HP. .SH SEE ALSO time(2), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR ctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR asctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR daylight ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR difftime() ": AES, SVID3, XPG4, ANSI C" .PP .CR gmtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR localtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mktime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR timezone ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR tzname ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tzset() ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4asctime()\fP, \f4asctime_r()\f1 \- convert \f3tm\f1 structure date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4ctime()\fP, \f4ctime_r()\f1 \- convert \f4clock()\fP date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4daylight()\fP \- Daylight Savings Time flag@@@\f3ctime(3C)\f1 .\" index@\f4gmtime()\fP, \f4gmtime_r()\fP \- convert date and time to Greenwich Mean Time@@@\f3ctime(3C)\f1 .\" index@\f4localtime()\fP, \f4localtime_r()\fP \- convert date and time to local timezone@@@\f3ctime(3C)\f1 .\" index@\f4timezone()\fP \- difference between \s-1UCT\s+1 and local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzname()\fP \- name of local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzset()\fP \- initialize \f4timezone()\fP, \f4daylight()\fP, and \f4tzname()\fP using \s-1TZ\s+1 variable@@@\f3ctime(3C)\f1 .\" index@\f4mktime()\fP \- convert time into calendar time value@@@\f3ctime(3C)\f1 .\" index@\f4difftime()\fP \- difference between two calendar time values@@@\f3ctime(3C)\f1 .\" index@convert date and time to string@@@\f3ctime(3C)\f1 .\" index@string, convert date and time to@@@\f3ctime(3C)\f1 .\" index@date and time, convert to string@@@\f3ctime(3C)\f1 .\" index@time and date, convert to string@@@\f3ctime(3C)\f1 .\" .\" toc@\f3ctime(3C)\f1:\0\0\f4ctime()\fP, \f4ctime_r()\fP, \f4localtime()\fP, \f4localtime_r()\fP, \f4difftime()\f1, \f4 mktime()\f1, \n\f4gmtime()\fP, \f4gmtime_r()\fP,\f4asctime()\fP, \f4asctime_r()\fP, \f4timezone()\fP, \f4daylight()\fP, \f4tzname()\fP,\n\f4tzset()\f1@@@convert date and time to string .\" toc@\f4ctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4ctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4timezone()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4daylight()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzname()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzset()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4difftime()\fP:\0\0difference between calendar times@@@see \f3ctime(3C)\f1 .\" toc@\f4mktime()\fP:\0\0create calendar time value@@@see \f3ctime(3C)\f1 .\" .\" links@ctime.3c ctime_r.3c .\" links@ctime.3c localtime.3c .\" links@ctime.3c localtime_r.3c .\" links@ctime.3c gmtime.3c .\" links@ctime.3c gmtime_r.3c .\" links@ctime.3c asctime.3c .\" links@ctime.3c asctime_r.3c .\" links@ctime.3c timezone.3c .\" links@ctime.3c daylight.3c .\" links@ctime.3c tzname.3c .\" links@ctime.3c tzset.3c .\" links@ctime.3c difftime.3c .\" links@ctime.3c mktime.3c .\" .\" fileset_database@ctime.3c PROGRAMING-MAN .\" $Header: ctype.3c,v 72.6 94/11/28 08:25:33 ssa Exp $ .TA c .TH ctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isalpha(\|), isupper(\|), islower(\|), isdigit(\|), isxdigit(\|), isalnum(\|), isspace(\|), ispunct(\|), isprint(\|), isgraph(\|), iscntrl(\|), isascii(\|) \- classify characters .SH SYNOPSIS .C "#include " .PP .C "int isalnum(int c);" .br .C "int isalpha(int c);" .br .C "int iscntrl(int c);" .br .C "int isdigit(int c);" .br .C "int isgraph(int c);" .br .C "int islower(int c);" .br .C "int isprint(int c);" .br .C "int ispunct(int c);" .br .C "int isspace(int c);" .br .C "int isupper(int c);" .br .C "int isxdigit(int c);" .br .C "int isascii(int c);" .SH DESCRIPTION These functions classify character-coded integer values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). Each function is a predicate returning non-zero for true, zero for false. .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP .C isascii() is defined on all integer values; the other functions are defined for the range .C -1 .SM (EOF) through .CR 255 . .PP The functions return non-zero under the following circumstances; zero otherwise: .RS .TP 18 .CR isalpha( c ) .I c is a letter. .TP .CR isupper( c ) .I c is an uppercase letter. .TP .CR islower( c ) .I c is a lowercase letter. .TP .CR isdigit( c ) .I c is a decimal digit (in .SM ASCII\c : characters [0-9]). .TP .CR isxdigit( c ) .I c is a hexadecimal digit (in .SM ASCII\c : characters [0-9], [A-F] or [a-f]). .TP .CR isalnum( c ) .I c is an alphanumeric (letters or digits). .TP .CR isspace( c ) .I c is a character that creates ``white space'' in displayed text (in .SM ASCII\c : space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CR ispunct( c ) .I c is a punctuation character (in .SM ASCII\c : any printing character except the space character (040), digits, letters). .TP .CR isprint( c ) .I c is a printing character. .TP .CR isgraph( c ) .I c is a visible character (in .SM ASCII\c : printing characters, excluding the space character (040)). .TP .CR iscntrl( c ) .I c is a control character (in .SM ASCII\c : character codes less than 040 and the delete character (0177)). .TP .CR isascii( c ) .I c is any .SM ASCII character code between 0 and 0177, inclusive. .RE .PP If the argument to any of these functions is outside the domain of the function, the result is undefined. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS These functions are supplied both as library functions and as macros defined in the .RC < ctype.h > header. Normally, the macro versions are used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parenthesis or take its address. The following example uses the library functions for .CR isalpha() , .CR isdigit() , and .CR isspace() : .nf .IP .C "#include " .C "#undef isalpha" \h'.5i'... .C "main() .C "{ .C " int (*ctype_func)();" \h'.8i'... .C " if ( isalpha(c) )" \h'.8i'... .C " if ( (isdigit)(c) )" \h'.8i'... .C " ctype_func = isspace;" \h'.8i'... .C } .fi .SH AUTHOR .CR ctype() was developed by IBM, OSF, and HP. .SH SEE ALSO setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR isalnum() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isalpha() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR iscntrl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isgraph() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR islower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isprint() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ispunct() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isspace() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isxdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4isalpha()\f1 \- character is alpha@@@\f3ctype(3C)\f1 .\" index@\f4isupper()\f1 \- character is uppercase@@@\f3ctype(3C)\f1 .\" index@\f4islower()\f1 \- character is lowercase@@@\f3ctype(3C)\f1 .\" index@\f4isdigit()\f1 \- character is a digit@@@\f3ctype(3C)\f1 .\" index@\f4isxdigit()\f1 \- character is a hexadecimal digit@@@\f3ctype(3C)\f1 .\" index@\f4isalnum()\f1 \- character is alphanumeric@@@\f3ctype(3C)\f1 .\" index@\f4isspace()\f1 \- character is whitespace@@@\f3ctype(3C)\f1 .\" index@\f4ispunct()\f1 \- character is punctuation@@@\f3ctype(3C)\f1 .\" index@\f4isprint()\f1 \- character is a printing character@@@\f3ctype(3C)\f1 .\" index@\f4isgraph()\f1 \- character is a visible character@@@\f3ctype(3C)\f1 .\" index@\f4iscntrl()\f1 \- character is a control character@@@\f3ctype(3C)\f1 .\" index@\f4isascii()\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3ctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3ctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3ctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3ctype(3C)\f1 .\" .\" toc@\f3ctype(3C)\f1:\0\0\f4isalpha()\f1, \f4isupper()\f1, \f4islower()\f1, \f4isdigit()\f1, \f4isxdigit()\f1, \f4isalnum()\f1, \f4isspace()\f1,\n\f4ispunct()\f1, \f4isprint()\f1, \f4isgraph()\f1, \f4iscntrl()\f1, \f4isascii()\f1@@@classify characters .\" toc@\f4isalpha()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isupper()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4islower()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isxdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isalnum()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isspace()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4ispunct()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isprint()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isgraph()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4iscntrl()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isascii()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" .\" links@ctype.3c isalpha.3c .\" links@ctype.3c isupper.3c .\" links@ctype.3c islower.3c .\" links@ctype.3c isdigit.3c .\" links@ctype.3c isxdigit.3c .\" links@ctype.3c isalnum.3c .\" links@ctype.3c isspace.3c .\" links@ctype.3c ispunct.3c .\" links@ctype.3c isprint.3c .\" links@ctype.3c isgraph.3c .\" links@ctype.3c iscntrl.3c .\" links@ctype.3c isascii.3c .\" .\" fileset_database@ctype.3c PROGRAMING-MAN .\" $Header: cur_term.3x,v 76.2 95/07/31 17:33:23 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH cur_term 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cur_term \(em current terminal information .SH SYNOPSIS .C "#include " .P .C "extern TERMINAL *cur_term;" .SH DESCRIPTION The external variable .I cur_term identifies the record in the terminfo database associated with the terminal currently in use. .SH "SEE ALSO" set_curterm(), tigetflag(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4cur_term()\f1 \- current terminal information@@@\f3cur_term(3X)\f1 .\" index@\f1current terminal information@@@\f3cur_term(3X)\f1 .\" index@\f1information on current terminal@@@\f3cur_term(3X)\f1 .\" index@\f1terminal, information on current terminal@@@\f3cur_term(3X)\f1 .\" .\" toc@\f3cur_term(3X)\f1:\0\0\f4cur_term()\f1@@@current terminal information .\" .\" fileset_database@cur_term.3x CURS-ENG-A-MAN .\" $Header: curs_set.3x,v 76.2 95/07/31 17:34:27 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH curs_set 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME curs_set \(em set the cursor mode .SH SYNOPSIS .C "#include " .P .C "int curs_set(int \f2visibility\fP);" .SH DESCRIPTION The .Fn curs_set function sets the appearance of the cursor based on the value of \f2visibility\fP: .PP .TS box center tab(`); cb cb c l. Value of \f2visibility\fP`Appearance of Cursor _ 0`Invisible 1`Terminal-specific normal mode 2`Terminal-specific high visibility mode .TE .PP The terminal does not necessarily support all the above values. .SH "RETURN VALUE" If the terminal supports the cursor mode specified by .I visibility , then .Fn curs_set returns the previous cursor state. Otherwise, the function returns ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4curs_set()\f1 \- set the cursor mode@@@\f3curs_set(3X)\f1 .\" index@\f1set the cursor mode@@@\f3curs_set(3X)\f1 .\" index@\f1cursor, set the cursor mode@@@\f3curs_set(3X)\f1 .\" index@\f1mode, set the cursor mode@@@\f3curs_set(3X)\f1 .\" .\" toc@\f3curs_set(3X)\f1:\0\0\f4curs_set()\f1@@@set the cursor mode .\" .\" fileset_database@curs_set.3x CURS-ENG-A-MAN .\" $Header: curscr.3x,v 76.2 95/07/31 17:35:44 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH curscr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME curscr \(em current window .SH SYNOPSIS .C "#include " .P .C "extern WINDOW *curscr;" .SH DESCRIPTION The external variable .I curscr points to an internal data structure. It can be specified as an argument to certain functions, such as .Fn clearok , where permitted in this specification. .SH "SEE ALSO" clearok(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4curscr()\f1 \- current window@@@\f3curscr(3X)\f1 .\" index@\f1current window@@@\f3curscr(3X)\f1 .\" index@\f1window, current@@@\f3curscr(3X)\f1 .\" .\" toc@\f3curscr(3X)\f1:\0\0\f4curscr()\f1@@@current window .\" .\" fileset_database@curscr.3x CURS-ENG-A-MAN .\" $Header: curses.3x,v 72.6 94/11/14 13:15:46 ssa Exp $ .TA c .TH curses 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME curses(\|) \- \s-1CRT\s+1 screen handling and optimization package .SH SYNOPSIS .C "#include " .PP .C cc .RI [\| flags \|] .IR file \0... .C -lcurses .RI [\| libraries \|] .SH DESCRIPTION These routines provide a method for updating screens with reasonable optimization. To initialize .C curses routines, .C initscr() must be called before calling any other routine that deals with windows and screens. .C endwin() should be called before exiting. To get character-at-a-time input without echoing, (most interactive, screen oriented-programs need this) after calling .C initscr() the program should call: .IP .C nonl(); .C cbreak(); .C noecho(); .PP The full .C curses interface permits manipulation of data structures called "windows", which can be thought of as two-dimensional arrays of characters representing all or part of a .SM CRT screen. A default window called .C stdscr is supplied, and others can be created using .CR newwin . Windows are referred to by variables declared .CR "WINDOW *" , the type .C WINDOW is defined in .RC < curses.h > to be a C structure. These data structures are manipulated by using functions described below, among which the most basic are .CR move() , and .CR addch() . (More general versions of these functions are included. Their names begin with .CR w , allowing the programmer to specify a window. Routines not beginning with .C w affect .CR stdscr .) Then .C refresh() is called, telling the routines to make the user's .SM CRT screen resemble .CR stdscr . .PP If the environment variable .C TERMINFO is defined, any program using curses checks for a local terminal definition before checking in the standard place. For example, if the standard place is .CR /usr/share/lib/terminfo , and .C TERM is set to .CR vt100 , the compiled file is normally found in .CR /usr/share/lib/terminfo/v/vt100 (the .C v is copied from the first letter of .C vt100 to avoid creation of huge directories). However, if .C TERMINFO is set to .CR /home/mark/myterms , .C curses first checks .CR /home/mark/myterms/v/vt100 , then, if that fails, checks .CR /usr/share/lib/terminfo/v/vt100 . This is useful for developing experimental definitions, or when write permission in .CR /usr/share/lib/terminfo is not available. .SS Functions .PP .PD 0 .TP 35 .CI addch( ch ) Add a character to .I stdscr (similar to .CR putchar() ; wraps to next line at end of line). .TP .CI addstr( str ) Call .C addch() with each character in .I str .TP .CI attroff( attrs ) Turn off attributes named .TP .CI attron( attrs ) Turn on attributes named .TP .CI attrset( attrs ) Set current attributes to .I attrs .TP .CR baudrate() Current terminal speed .TP .CR beep() Sound beep on terminal .TP .ift .CI box( "win\f4,\fP vert\f4,\fP hor" ) .ifn .CI box( "win\f3,\fP vert\f3,\fP hor" ) Draw a box around edges of .IR win . .I vert and .I hor are chars to use for vertical and horizontal edges of box .TP .C clear() Clear .I stdscr .TP .CI clearok( win , \ bf ) Clear screen before next redraw of .I win .TP .C clrtobot() Clear to bottom of .I stdscr .TP .C clrtoeol() Clear to end of line on .I stdscr .TP .CR cbreak() Set cbreak mode .TP .CR def_prog_mode() Save the current terminal mode as the .IR program (in CURSES) state .TP .CR def_shell_mode() Save the current terminal mode as the .IR shell (not in CURSES) state .TP .CI delay_output( ms ) Insert .I ms millisecond pause in output .TP .C delch() Delete a character .TP .C deleteln() Delete a line .TP .CI delwin( win ) Delete .I win .TP .C doupdate() Update screen from all .C wnooutrefresh() .TP .CR echo() Set echo mode .TP .CR endwin() End window modes .TP .C erase() Erase .I stdscr .TP .C erasechar() Return user's erase character .TP .C fixterm() Restore tty to ``in-curses'' state .TP .C flash() Flash screen or beep .TP .CR flushinp() Throw away any type-ahead characters .TP .C getch() Get a char from tty .TP .CI getstr( str ) Get a string through .I stdscr .TP .C gettmode() Establish current tty modes .TP .ift .CI getyx( "win\f4,\fP y\f4,\fP x" ) .ifn .CI getyx( "win\f3,\fP y\f3,\fP x" ) Get .RI ( y , \ x ) co-ordinates .TP .C has_ic() True if terminal can do insert character .TP .C has_il() True if terminal can do insert line .TP .CI idlok( win , \ bf ) Use terminal's insert/delete line if .I bf != 0 .TP .C inch() Get char at current .RI ( y , \ x ) co-ordinates .TP .CR initscr() Initialize screens .TP .CI insch( c ) Insert a char .TP .C insertln() Insert a line .TP .CI intrflush( win , \ bf ) Interrupts flush output if .I bf is .SM TRUE .TP .CI keypad( win , \ bf ) Enable keypad input .TP .C killchar() Return current user's kill character .TP .CI leaveok( win , \ flag ) Permissible to leave cursor anywhere after refresh if .I flag !=0 for .IR win ; otherwise cursor must be left at current position. .TP .C longname() Return verbose name of terminal .TP .CI meta( win , \ flag ) Allow meta characters on input if .I flag != 0 .TP .CI move( y , \ x ) move to .RI ( y , \ x ) on .I stdscr .TP .ift .CI mvaddch( "y\f4,\fP x\f4,\fP ch" ) .ifn .CI mvaddch( "y\f3,\fP x\f3,\fP ch" ) .CI move( y , \ x ) then .CI addch( ch ) .TP .ift .CI mvaddstr( "y\f4,\fP x\f4,\fP str" ) .ifn .CI mvaddstr( "y\f3,\fP x\f3,\fP str" ) Similar... .TP .ift .CI mvcur( "oldrow\f4,\fP oldcol\f4,\fP newrow\f4,\fP newcol" ) .ifn .CI mvcur( "oldrow\f3,\fP oldcol\f3,\fP newrow\f3,\fP newcol" ) Low-level cursor motion .TP .CI mvdelch( y , \ x ) Similar to .CR delch() , but .CI move( y , \ x ) first .TP .CI mvgetch( y , \ x ) etc. .TP .CI mvgetstr( y , \ x ) .TP .CI mvinch( y , \ x ) .TP .ift .CI mvinsch( "y\f4,\fP x\f4,\fP c" ) .ifn .CI mvinsch( "y\f3,\fP x\f3,\fP c" ) .TP .ift .CI mvprintw( "y\f4,\fP x\f4,\fP fmt\f4,\fP args" ) .ifn .CI mvprintw( "y\f3,\fP x\f3,\fP fmt\f3,\fP args" ) .TP .ift .CI mvscanw( "y\f4,\fP x\f4,\fP fmt\f4,\fP args" ) .ifn .CI mvscanw( "y\f3,\fP x\f3,\fP fmt\f3,\fP args" ) .TP .ift .CI mvwaddch( "win\f4,\fP y\f4,\fP x\f4,\fP ch" ) .ifn .CI mvwaddch( "win\f3,\fP y\f3,\fP x\f3,\fP ch" ) .TP .ift .CI mvwaddstr( "win\f4,\fP y\f4,\fP x\f4,\fP str" ) .ifn .CI mvwaddstr( "win\f3,\fP y\f3,\fP x\f3,\fP str" ) .TP .ift .CI mvwdelch( "win\f4,\fP y\f4,\fP, x" ) .ifn .CI mvwdelch( "win\f3,\fP y\f3,\fP, x" ) .TP .ift .CI mvwgetch( "win\f4,\fP y\f4,\fP, x" ) .ifn .CI mvwgetch( "win\f3,\fP y\f3,\fP, x" ) .TP .ift .CI mvwgetstr( "win\f4,\fP y\f4,\fP, x" ) .ifn .CI mvwgetstr( "win\f3,\fP y\f3,\fP, x" ) .TP .ift .CI mvwin( "win\f4,\fP by\f4,\fP, bx" ) .ifn .CI mvwin( "win\f3,\fP by\f3,\fP, bx" ) .TP .ift .CI mvwinch( "win\f4,\fP y\f4,\fP, x" ) .ifn .CI mvwinch( "win\f3,\fP y\f3,\fP, x" ) .TP .ift .CI mvwinsch( "win\f4,\fP y\f4,\fP x\f4,\fP c" ) .ifn .CI mvwinsch( "win\f3,\fP y\f3,\fP x\f3,\fP c" ) .TP .ift .CI mvwprintw( "win\f4,\fP y\f4,\fP x\f4,\fP fmt\f4,\fP args" ) .ifn .CI mvwprintw( "win\f3,\fP y\f3,\fP x\f3,\fP fmt\f3,\fP args" ) .TP .ift .CI mvwscanw( "win\f4,\fP y\f4,\fP x\f4,\fP fmt\f4,\fP args" ) .ifn .CI mvwscanw( "win\f3,\fP y\f3,\fP x\f3,\fP fmt\f3,\fP args" ) .TP .CI newpad( nlines , \ ncols ) Create a new pad with given dimensions .TP .ift .CI newterm( "type\f4,\fP outfd\f4,\fP infd" ) .ifn .CI newterm( "type\f3,\fP outfd\f3,\fP infd" ) Set up new terminal of given type to output on .IR outfd , using input (if needed) from .I infd .TP .ift .CI newwin( "lines\f4,\fP cols\f4,\fP begin_y\f4,\fP begin_x" ) .ifn .CI newwin( "lines\f3,\fP cols\f3,\fP begin_y\f3,\fP begin_x" ) Create a new window .TP .CR nl() Set new-line mapping .TP .CR nocbreak() Unset cbreak mode .TP .CI nodelay( win , \ bf ) Enable nodelay input mode through .C getch() .TP .CR noecho() Unset echo mode .TP .CR nonl() Unset new-line mapping .TP .CR noraw() Unset raw mode .TP .CI overlay( win1 , \ win2 ) Overlay .I win1 on .I win2 .TP .CI overwrite( win1 , \ win2 ) Overwrite .I win1 on .I win2 .TP .ift .CI pnoutrefresh( "pad\f4,\fP pminrow\f4,\fP pmincol\f4,\fP sminrow\f4,\fP smincol\f4,\fP smaxrow\f4,\fP smaxcol" ) .ifn .CI pnoutrefresh( "pad\f3,\fP pminrow\f3,\fP pmincol\f3,\fP sminrow\f3,\fP smincol\f3,\fP smaxrow\f3,\fP smaxcol" ) Similar to .C prefresh() but with no output until .C doupdate() called .TP .ift .CI prefresh( "pad\f4,\fP pminrow\f4,\fP pmincol\f4,\fP sminrow\f4,\fP smincol\f4,\fP smaxrow\f4,\fP smaxcol" ) .ifn .CI prefresh( "pad\f3,\fP pminrow\f3,\fP pmincol\f3,\fP sminrow\f3,\fP smincol\f3,\fP smaxrow\f3,\fP smaxcol" ) Refresh from pad starting with given upper left corner of pad with output to given portion of screen .TP .ift .CI printw( "fmt\f4,\fP arg1\f4,\fP arg2\f4,\fP ..." ) .ifn .CI printw( "fmt\f3,\fP arg1\f3,\fP arg2\f3,\fP ..." ) .C printf() on .I stdscr .TP .CR raw() Set raw mode .TP .CR refresh() Make current screen look like .I stdscr .TP .CR reset_prog_mode() Restore the terminal to .IR program (in CURSES) state .TP .CR reset_shell_mode() Restore the terminal to .IR shell (out of CURSES) state .TP .CR resetterm() Set tty modes to "out of curses" state .TP .CR resetty() Reset tty flags to stored value .TP .CR saveterm() Save current modes as "in curses" state .TP .CR savetty() Store current tty flags .TP .ift .CI scanw( "fmt\f4,\fP arg1\f4,\fP arg2\f4,\fP ..." ) .ifn .CI scanw( "fmt\f3,\fP arg1\f3,\fP arg2\f3,\fP ..." ) .C scanf() through .I stdscr .TP .CI scroll( win ) Scroll .I win one line .TP .CI scrollok( win , \ flag ) Allow terminal to scroll if .I flag != 0 .TP .CI set_term( new ) Switch to terminal .I new .TP .CI setscrreg( t , \ b ) set user scrolling region to lines t through b .TP .CI setterm( type ) Establish terminal with given type .TP .ift .CI setupterm( "term\f4,\fP filenum\f4,\fP errret" ) .ifn .CI setupterm( "term\f3,\fP filenum\f3,\fP errret" ) .TP .CR standend() Clear standout mode attribute .TP .CR standout() Set standout mode attribute .TP .ift .CI subwin( "win\f4,\fP lines\f4,\fP cols\f4,\fP begin_y\f4,\fP begin_x" ) .ifn .CI subwin( "win\f3,\fP lines\f3,\fP cols\f3,\fP begin_y\f3,\fP begin_x" ) create a subwindow .TP .CI touchwin( win ) Change all of .I win .TP .C traceoff() Turn off debugging trace output .TP .C traceon() Turn on debugging trace output .TP .CI typeahead( fd ) Use file descriptor .I fd to check type-ahead .TP .CI unctrl( ch ) Printable version of .I ch .TP .CI waddch( win , \ ch ) Add char to .I win .TP .CI waddstr( win , \ str ) Add string to .I win .TP .CI wattroff( win , \ attrs ) Turn off .I attrs in .I win .TP .CI wattron( win , \ attrs ) Turn on .I attrs in .I win .TP .CI wattrset( win , \ attrs ) Set attrs in .I win to .I attrs .TP .CI wclear( win ) Clear .I win .TP .CI wclrtobot( win ) Clear to bottom of .I win .TP .CI wclrtoeol( win ) Clear to end of line on .I win .TP .CI wdelch( win , \ c ) Delete char from .I win .TP .CI wdeleteln( win ) Delete line from .I win .TP .CI werase( win ) Erase .I win .TP .CI wgetch( win ) Get a char through .I win .TP .CI wgetstr( win , \ str ) Get a string through .I win .TP .CI winch( win ) Get char at current .RI ( y , \ x ) in .I win .TP .CI winsch( win , \ c ) Insert char into .I win .TP .CI winsertln( win ) Insert line into .I win .TP .ift .CI wmove( "win\f4,\fP y\f4,\fP x" ) .ifn .CI wmove( "win\f3,\fP y\f3,\fP x" ) Set current .RI ( y , \ x ) co-ordinates on .I win .TP .CI wnoutrefresh( win ) Refresh but no screen output .TP .ift .CI wprintw( "win\f4,\fP fmt\f4,\fP arg1\f4,\fP arg2\f4,\fP ..." ) .ifn .CI wprintw( "win\f3,\fP fmt\f3,\fP arg1\f3,\fP arg2\f3,\fP ..." ) .C printf() on .I win .TP .CI wrefresh( win ) Make screen look like .I win .TP .ift .CI wscanw( "win\f4,\fP fmt\f4,\fP arg1\f4,\fP arg2\f4,\fP ..." ) .ifn .CI wscanw( "win\f3,\fP fmt\f3,\fP arg1\f3,\fP arg2\f3,\fP ..." ) .CI scanf() through .I win .TP .ift .CI wsetscrreg( "win\f4,\fP t\f4,\fP b" ) .ifn .CI wsetscrreg( "win\f3,\fP t\f3,\fP b" ) Set scrolling region of .I win .TP .CI wstandend( win ) Clear standout attribute in .I win .TP .CI wstandout( win ) Set standout attribute in .I win .PD .SS "Terminfo Level Routines" .PP These routines should be called by programs that need to deal directly with the .IR terminfo (4) database. Due to the low level of this interface, its use is discouraged. Initially, .C setupterm() should be called to define the set of terminal-dependent variables defined in .IR terminfo (4). The header files .RC < curses.h > and .RC < term.h > should be included to get the definitions for these strings, numbers, and flags. Parameterized strings should be passed through .C tparm() to instantiate them. All .IR terminfo (4) strings (including the output of .CR tparm() ) should be printed with .C tputs() or .CR putp() . Before exiting, .C resetterm() should be called to restore the tty modes. (Programs desiring shell escapes or suspending with control-Z can call .C resetterm() before the shell is called and .C fixterm() after returning from the shell.) .TP 35 .C fixterm() Restore tty modes for terminfo use (called by .CR setupterm() ) .TP .C resetterm() Reset tty modes to state before program entry .TP .ift .CI setupterm( "term\f4,\fP fd\f4,\fP rc" ) .ifn .CI setupterm( "term\f3,\fP fd\f3,\fP rc" ) Read in database. Terminal type is the character string .IR term , all output is to .SM HP-UX System file descriptor .IR fd . A status value is returned in the integer pointed to by .IR rc : 1 is normal. The simplest call would be .C setupterm(0, 1, 0) which uses all defaults. .TP .ift .CI tparm( "str\f4,\fP p1\f4,\fP p2\f4,\fP ...\f4,\fP p9" ) .ifn .CI tparm( "str\f3,\fP p1\f3,\fP p2\f3,\fP ...\f3,\fP p9" ) Instantiate string str with parms .IR p\di\u . .TP .ift .CI tputs( "str\f4,\fP affcnt\f4,\fP putc" ) .ifn .CI tputs( "str\f3,\fP affcnt\f3,\fP putc" ) Apply padding info to string .IR str . .I affcnt is the number of lines affected, or 1 if not applicable. .C putc() is a putchar-like function to which the characters are passed, one at a time. .TP .CI putp( str ) A handy function that calls .CI tputs( str ", 1, " putchar ) \f1. .TP .CI vidputs( attrs , \ putc ) output the string to put terminal in video attribute mode .IR attrs , which is any combination of the attributes listed below. Chars are passed to putchar-like function .CR putc() . .TP .CI vidattr( attrs ) Like vidputs but outputs through putchar .TP .CI set_curterm( term ) Set the database pointed to by term .TP .CI del_curterm( term ) Free the space pointed to by term .SS "Termcap Compatibility Routines" .PP These routines were included as a conversion aid for programs that use termcap. Calling parameters are the same as for termcap. They are emulated using the .IR terminfo (4) database. Their use in new software is not recommended because they might be deleted in future .SM HP-UX releases. .TP 35 .CI tgetent( bp , \ name ) look up termcap entry for name .PD 0 .TP .CI tgetflag( id ) get boolean entry for id .TP .CI tgetnum( id ) get numeric entry for id .TP .CI tgetstr( id , \ area ) get string entry for id .TP .CI tgoto( cap , \ col ,\ \f2\s-1row\s0\fP) apply parms to given cap .TP .CI tputs( cap , \ affcnt ,\ \f2\s-1fn\s0\fP) apply padding to cap calling fn as putchar .PD .SS Attributes .PP The following video attributes can be passed to the functions .CR attron() , .CR attroff() , and .CR attrset() . .PP .PD 0 .TP 20 .C A_STANDOUT Terminal's best highlighting mode .TP .C A_UNDERLINE Underlining .TP .C A_REVERSE Reverse video .TP .C A_BLINK Blinking .TP .C A_DIM Half bright .TP .C A_BOLD Extra bright or bold .TP .C A_BLANK Blanking (invisible) .TP .C A_PROTECT Protected .TP .C A_ALTCHARSET Alternate character set .PD .SS "NLS Attributes" .PP The following .SM NLS attributes might be returned by .CR inch() : .PP .PD 0 .TP 20 .C A_FIRSTOF2 First byte of 16-bit character .TP .C A_SECOF2 Second byte of 16-bit character .PD .SS "Function Keys" .PP The following function keys could possibly be returned by .I getch if .I keypad has been enabled. Note that not all of these are currently supported due to lack of definitions in .IR terminfo or the terminal not transmitting a unique code when the key is pressed. .PP .ta 1.5i .PD 0 .TP 40 .I Name Value .I Key name .TP .C KEY_BREAK 0401 break key (unreliable) .TP .C KEY_DOWN 0402 The four arrow keys ... .TP .C KEY_UP 0403 .TP .C KEY_LEFT 0404 .TP .C KEY_RIGHT 0405 ... .TP .C KEY_HOME 0406 Home key (upward+left arrow) .TP .C KEY_BACKSPACE 0407 backspace (unreliable) .TP .C KEY_F0 0410 Function keys. Space reserved for up to 64 keys. .TP .C KEY_F(n) (KEY_F0+(n)) Formula for fn. .TP .C KEY_DL 0510 Delete line .TP .C KEY_IL 0511 Insert line .TP .C KEY_DC 0512 Delete character .TP .C KEY_IC 0513 Insert char or enter insert mode .TP .C KEY_EIC 0514 Exit insert char mode .TP .C KEY_CLEAR 0515 Clear screen .TP .C KEY_EOS 0516 Clear to end of screen .TP .C KEY_EOL 0517 Clear to end of line .TP .C KEY_SF 0520 Scroll 1 line forward .TP .C KEY_SR 0521 Scroll 1 line backwards (reverse) .TP .C KEY_NPAGE 0522 Next page .TP .C KEY_PPAGE 0523 Previous page .TP .C KEY_STAB 0524 Set tab .TP .C KEY_CTAB 0525 Clear tab .TP .C KEY_CATAB 0526 Clear all tabs .TP .C KEY_ENTER 0527 Enter or send (unreliable) .TP .C KEY_SRESET 0530 soft (partial) reset (unreliable) .TP .C KEY_RESET 0531 reset or hard reset (unreliable) .TP .C KEY_PRINT 0532 print or copy .TP .C KEY_LL 0533 home down or bottom (lower left) .PD .SS Window-Change Signal Support All curses routines except the min-curses subset provide .C SIGWINCH support. Applications that are linked with curses routines immediately redraw the screen in response to window size changes. The environmental variables .C LINES and .C COLUMNS are also updated so that children processes work with the correct window size. .PP If there is a window size reduction, part of the application display is trimmed. The trimmed portion is saved in internal memory at the time of resize. Moreover, this portion is not affected by the application as long as it stays invisible. If the application's cursor is trimmed, unexpected behavior results. .PP On the other hand, if the window is enlarged, any previously trimmed area is re-displayed (and re-activated). If the window is enlarged beyond its initial size, the extra area is padded with blank spaces. .PP The default .C SIGWINCH support can be disabled by installing a custom .C SIGWINCH signal handler via the sigvector command (see .IR sigvector (2)). .SH WARNINGS HP supports only terminals listed on the current list of HP-supported devices. However, the .IR terminfo (4) database may contain information for other terminals besides those that are officially supported. If you use such unsupported terminals, they may not work correctly. .PP The .C endwin() routine does not release memory allocated by the .C initscr() routine. Repeated calls to .C initscr() can cause a program to use more memory than was intended. .PP Some of these routines call .C malloc() to allocate memory (see .IR malloc (3C)) and can therefore fail for any of the reasons described in the .IR malloc (3C) manual entry. .SH SEE ALSO sigvector(2), terminfo(4). .SH STANDARDS CONFORMANCE .CR curses() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4curses()\fP \- \s-1CRT\s+1 screen handling and optimization package@@@\f3curses(3X)\f1 .\" index@\s-1CRT\s+1 screen handling and optimization package@@@\f3curses(3X)\f1 .\" index@routines, \s-1CRT\s+1 screen handling and optimization@@@\f3curses(3X)\f1 .\" index@screen handling and optimization package, \s-1CRT\s+1@@@\f3curses(3X)\f1 .\" index@optimization package, \s-1CRT\s+1 screen handling and@@@\f3curses(3X)\f1 .\" index@\s-1CRT\s+1 optimization and screen handling package@@@\f3curses(3X)\f1 .\" index@cursor control, \s-1CRT\s+1 optimization, and screen handling package@@@\f3curses(3X)\f1 .\" .\" toc@\f3curses(3X)\f1:\0\0\f4curses()\fP@@@\s-1CRT\s+1 screen handling and optimization package .\" .\" fileset_database@curses.3x PROGRAMING-MAN .\" $Header: curses_intro.3x,v 76.3 95/10/05 14:40:59 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH curses_intro 3X "X/Open CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME curses(\|) \- Terminal and printer handling and optimization package .SH DESCRIPTION .SH "Use and Implementation of Interfaces" These routines provide a method for updating screens with reasonable optimization in a terminal independent manner. Each of the following statements applies unless explicitly stated otherwise in the detailed descriptions that follow. If an argument to a function has an invalid value (such as a value outside the domain of the function, or a pointer outside the address space of the program, or a null pointer), the behaviour is undefined. Any function declared in a header may also be implemented as a macro defined in the header, so a library function should not be declared explicitly if its header is included. Any macro definition of a function can be suppressed locally by enclosing the name of the function in parentheses, because the name is then not followed by the left parenthesis that indicates expansion of a macro function name. For the same syntactic reason, it is permitted to take the address of a library function even if it is also defined as a macro. The use of the C-language .B #undef construct to remove any such macro definition will also ensure that an actual function is referred to. Any invocation of a library function that is implemented as a macro will expand to code that evaluates each of its arguments exactly once, fully protected by parentheses where necessary, so it is generally safe to use arbitrary expressions as arguments. Likewise, those function-like macros described in the following sections may be invoked in an expression anywhere a function with a compatible return type could be called. .P Provided that a library function can be declared without reference to any type defined in a header, it is also permissible to declare the function, either explicitly or implicitly, and use it without including its associated header. If a function that accepts a variable number of arguments is not declared (explicitly or by including its associated header), the behaviour is undefined. .P As a result of changes introduced in this version of the \*(Z4, application writers are only required to include the minimum number of headers. Implementations of XSI-conformant systems will make all necessary symbols visible as described in the Headers section of this document. .SH "C Language Definition" The C language that is the basis for the synopses and code examples in this document is \f2ISO C\fP, as specified in the referenced ISO C standard. \f2Common Usage C\fP, which refers to the C language before standardisation, was the basis for previous editions of this specification. .SH "The Compilation Environment" Applications should ensure that the feature test macro _XOPEN_SOURCE is defined before inclusion of any header. This is needed to enable the functionality described in this document, and possibly to enable functionality defined elsewhere in the Common Applications Environment. .P The _XOPEN_SOURCE macro may be defined automatically by the compilation process, but to ensure maximum portability, applications should make sure that _XOPEN_SOURCE is defined by using either compiler options or .B #define directives in the source files, before any .B #include directives. Identifiers in this document may only be undefined using the .B #undef directive. These .B #undef directives must follow all .B #include directives of any headers. .P Most strictly conforming POSIX and ISO C applications will compile on systems compliant to this specification. However, an application which uses any of the items marked as an extension to POSIX and ISO C, for any purpose other than that shown here, may not compile. In such cases, it may be necessary to alter those applications to use alternative identifiers. .P Since this document is aligned with the ISO C standard, and since all functionality enabled by the _POSIX_C_SOURCE set equal to 2 should be enabled by _XOPEN_SOURCE, there should be no need to define either _POSIX_SOURCE or _POSIX_C_SOURCE if _XOPEN_SOURCE is defined. Therefore if _XOPEN_SOURCE is defined and _POSIX_SOURCE is defined, or _POSIX_C_SOURCE is set equal to 1 or 2, the behaviour is the same as if only _XOPEN_SOURCE is defined. However should _POSIX_C_SOURCE be set to a value greater than 2, the behaviour is undefined. .P The .I c89 and .I cc utilities recognise the additional .B "\(mil" operand for standard libraries: .RS .TP 15 .C "\f3\(mil\0curses\fP" This operand makes visible all library functions referenced in this specification, (except for those labelled ENHANCED CURSES and except for portions marked with the \s-3EC\s0 margin legend). .IP If the implementation defines _XOPEN_CURSES and if the application defines the _XOPEN_SOURCE_EXTENDED feature test macro, then .B "-l\0curses" also makes visible all library functions referenced in this specification and labelled ENHANCED CURSES. .RE .P An application that uses any API specified as ENHANCED CURSES must define _XOPEN_SOURCE_EXTENDED = 1 in each source file or as part of its compilation environment. When _XOPEN_SOURCE_EXTENDED = 1 is defined in a source file, it must appear before any header is included. .P If the implementation supports the utilities marked .B "DEVELOPMENT" in the \*(ZC, the .I lint utility recognises the additional .B "\(mil\0curses" operand for standard libraries: .RS .TP 15 .C "\f3\(mil\0curses\fP" Names the library .B "llib-lcurses.ln" , which will contain functions specified in this document. .RE .P It is unspecified whether the library .B "llib-lcurses.ln" exists as a regular file. .SS "The X/Open Name Space (ENHANCED CURSES)" The requirements in this section are in effect only for implementations that claim Enhanced Curses compliance. .P All identifiers in this document are defined in at least one of the headers .CR , .CR , .CR . When _XOPEN_SOURCE is defined, each header defines or declares some identifiers, potentially conflicting with identifiers used by the application. The set of identifiers visible to the application consists of precisely those identifiers from the header pages of the included headers, as well as additional identifiers reserved for the implementation. In addition, some headers may make visible identifiers from other headers as indicated on the relevant header pages. .P The identifiers reserved for use by the implementation are described below. .P .RS .TP 10 .C 1 Each identifier with external linkage described in the header section is reserved for use as an identifier with external linkage if the header is included. .TP .C 2 Each macro name described in the header section is reserved for any use if the header is included. .TP .C 3 Each identifier with file scope described in the header section is reserved for use as an identifier with file scope in the same name space if the header is included. .TP .C 4 All identifiers consisting of exactly 2 upper-case letters. .RE .P If any header in the following table is included, identifiers with the prefixes, suffixes or complete names shown are reserved for use by the implementation. .P .TS box tab (@); lb lb lb lb. Header@Prefix@Suffix@Complete @@@Name _ @add, attr, get, in, mousr, mv,@@ @scr, slk, un, wadd, wattr, wbkg, win@ @ ANY header@@_t@ @ .TE .P If any header in the following table is included, macros with the prefixes shown may be defined. After the last inclusion of a given header, an application may use identifiers with the corresponding prefixes for its own purpose, provided their use is preceded by an .B #undef of the corresponding macro. .P .TS box tab (@); lb lb lb l. Header@Prefix _ @A_, ACS_, ALL_, BUTTON, COLOR_, KEY_, MOUSE, REPORT_, @WA_, WACS_ @ext_ .TE .P The following identifiers are reserved regardless of the inclusion of headers: .RS .TP 10 .C 1 All identifiers that begin with an underscore and either an upper-case letter or another underscore are always reserved for any use by the implementation. .TP .C 2 All identifiers that begin with an underscore are always reserved for use as identifiers with file scope in both the ordinary identifier and tag name spaces. .TP .C 3 All identifiers listed as reserved in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification are reserved for use as identifiers with external linkage. .RE .P All the identifiers defined in this document that have external linkage are always reserved for use as identifiers with external linkage. .P No other identifiers are reserved. .P Applications must not declare or define identifiers with the same name as an identifier reserved in the same context. Since macro names are replaced whenever found, independent of scope and name space, macro names matching any of the reserved identifier names must not be defined if any associated header is included. .P Headers may be included in any order, and each may be included more than once in a given scope, with no difference in effect from that of being included only once. .P If used, a header must be included outside of any external declaration or definition, and it must be first included before the first reference to any type or macro it defines, or to any function or object it declares. However, if an identifier is declared or defined in more than one header, the second and subsequent associated headers may be included after the initial reference to the identifier. Prior to the inclusion of a header, the program must not define any macros with names lexically identical to symbols defined by that header. .br .ne 15 .SS "Interfaces Implemented as Macros (ENHANCED CURSES)" The requirements in this section are in effect only for implementations that claim Enhanced Curses compliance. .P The following interfaces with arguments must be implemented as macros. The relevance to the application programmer is that the `\f4&\f1' character cannot be used before the arguments. .P .TS box center tab(`); cb cb l li. Macros`Man Page _ COLOR_PAIR\^(\|), PAIR_NUMBER\^(\|)`can_change_color(\|) \f2getbegyx\fP\^(\|), \f2getmaxyx\fP\^(\|), \f2getparyx\fP\^(\|), \f2getyx\fP\^(\|)`getbegyx(\|) .TE .P The descriptions in .Hd curses.h , .Hd term.h , .Hd unctrl.h list other macros, like COLOR_BLACK, that do not take arguments. .nr Ej 1 .SH "Relationship to the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification " .SS "Error Numbers" .P Most functions provide an error number in .I errno , which is either a variable or macro defined in .CR ; the macro expands to a modifiable .CR lvalue of type .CR int . .P A list of valid values for .I errno and advice to application writers on the use of .I errno appears in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification . .SH "Data Types" All of the data types used by Curses functions are defined by the implementation. The following list describes these types: .RS .TP 12 .C \f3\*!attr_t\f1 An integral type that can contain at least an \f3unsigned short\f1. The type \f3attr_t\f1 is used to hold an OR-ed set of attributes defined in .Hd curses.h that begin with the prefix WA_. .TP .C \f3bool\f1 Boolean data type .TP .C \f3chtype\f1 An integral type that can contain at least an \f3unsigned char\f1 and attributes. Values of type \f3chtype\f1 are formed by OR-ing together an \f3unsigned char\f1 value and zero or more of the base attribute flags defined in .Hd curses.h that have the A_ prefix. The application can extract these components of a \f3chtype\f1 value using the base masks defined in .Hd curses.h for this purpose. .P The \f3chtype\f1 data type also contains a colour-pair. Values of type \f3chtype\f1 are formed by OR-ing together an \f3unsigned char\f1 value, a colour pair, and zero or more of the attributes defined in .Hd curses.h that begin with the prefix A_. The application can extract these components of a \f3chtype\f1 value using the masks defined in .Hd curses.h for this purpose. .TP 12 .C \f3SCREEN\f1 An opaque terminal representation. .TP .C \f3\*!wchar_t\f1 As described in .Hd stddef.h . .TP .C \f3\*!cchar_t\f1 A type that can reference a string of wide characters of up to an implementation-dependent length, a colour-pair, and zero or more attributes from the set of all attributes defined in this document. A null \f3cchar_t\f1 object is an object that references a empty wide-character string. Arrays of \f3cchar_t\f1 objects are terminated by a null \f3cchar_t\f1 object. .TP .C \f3WINDOW\f1 An opaque window representation. .RE .eF e .\" Copyright 1994, The X/Open Company Ltd. .ds SI @(#) 1.4 95/02/01 .SH "Interface Overview" .SH "Components" .nr Ej 2 A Curses initialisation function, usually .Fn initscr , determines the terminal model in use, by reference to either an argument or an environment variable. If that model is defined in \f3terminfo\f1, then the same \f3terminfo\f1 entry tells Curses exactly how to operate the terminal. .P In this case, a comprehensive API lets the application perform terminal operations. The Curses run-time system receives each terminal request and sends appropriate commands to the terminal to achieve the desired effect. .SS "Relationship to the \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification " Applications using Curses should not also control the terminal using capabilities of the general terminal interface defined in the \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Chapter 9,\f3General Terminal Interface\f1. .P There is no requirement that the paradigms that exist while in Curses mode be carried over outside the Curses environment (see the .Fn def_prog_mode page). .SS "Relationship to Signals" Curses implementations may provide for special handling of the SIGINT, SIGQUIT and SIGTSTP signals if their disposition is SIGDFL at the time .Fn initscr is called (see the .Fn initscr page). .P Any special handling for these signals may remain in effect for the life of the process or until the process changes the disposition of the signal. .P None of the Curses functions are required to be safe with respect to signals (see .Fn sigaction in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ). .P The behaviour of Curses with respect to signals not defined by the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification is unspecified. .SH "Screens, Windows and Terminals" .SS "Screen" A screen is the physical output device of the terminal. In Curses, a \f3SCREEN\f1 data type is an opaque data type associated with a terminal. Each window (see below) is associated with a \f3SCREEN\f1. .SS "Windows" The Curses functions permit manipulation of .I window objects, which can be thought of as two-dimensional arrays of characters and their renditions. A default window called .I stdscr , which is the size of the terminal screen, is supplied. Others may be created with .Fn newwin . .P Variables declared as \f3WINDOW *\f1 refer to windows (and to subwindows, derived windows, and pads, as described below). These data structures are manipulated with functions described on the reference manual pages in terminfo(4). Among the most basic functions are .Fn move and .Fn addch . More general versions of these functions are included that allow a process to specify a window. .P After using functions to manipulate a window, .Fn refresh is called, telling Curses to make the CRT screen look like .I stdscr . .P Line drawing characters may be specified to be output. On input, Curses is also able to translate arrow and function keys that transmit escape sequences into single values. The line drawing characters and input values use names defined in .Hd curses.h . .P Each window has a flag that indicates that the information in the window could differ from the information displayed on the terminal device. Making any change to the contents of the window, moving or modifying the window, or setting the window's cursor position, sets this flag (\c .I touches the window). .SS "Subwindows" A .I subwindow is a window, created within another window (called the .I "parent window" ), and positioned relative to the parent window. A subwindow can be created by calling .Fn derwin , .Fn newpad or .Fn subwin. Changes made to a subwindow do not affect its parent window. .P Subwindows can be created from a parent window by calling .Fn subwin . The position and size of subwindows on the screen must be identical to or totally within the parent window. Changes to either the parent window or the subwindow affect both. Window clipping is not a property of subwindows. .SS "Ancestors" The term .I ancestor refers to a window's parent, or its parent, or so on. .SS "Derived Windows" Derived windows are subwindows whose position is defined by reference to the parent window rather than in absolute screen coordinates. Derived windows are otherwise no different from subwindows. .SS "Pads" A pad is a specialised case of subwindow that is not necessarily associated with a viewable part of a screen. Functions that deal with pads are all discussed in .Fn newpad . .SS "Terminal" A terminal is the logical input and output device through which character-based applications interact with the user. .B TERMINAL is an opaque data type associated with a terminal. A .B TERMINAL data structure primarily contains information about the capabilities of the terminal, as defined by .BR terminfo . A .B TERMINAL also contains information about the terminal modes and current state for input and output operations. Each screen (see above) is associated with a .BR TERMINAL . .SH "Characters" .SS "Character Storage Size" Historically, a position on the screen has corresponded to a single stored byte. This correspondence is no longer true for several reasons: .RS .TP 5 .C \(bu Some characters may occupy several columns when displayed on the screen (see \f3Multi-column Characters\f1). .TP .C \(bu Some characters may be non-spacing characters, defined only in association with a spacing character (see \f3Non-spacing Characters (ENHANCED CURSES)\f1). .TP .C \(bu The number of bytes to hold a character from the extended character sets depends on the LC_CTYPE locale category. .RE .PP The internal storage format of characters and renditions is unspecified. There is no implied correspondence between the internal storage format and the external representation of characters and renditions in objects of type .B chtype and .BR cchar_t . .SS "Multi-column Characters" Some character sets define .I "multi-column characters" that occupy more than one column position when displayed on the screen. .P Writing a character whose width is greater than the width of the destination window is an error. .SS "Attributes" Each character can be displayed with .I attributes such as underlining, reverse video or colour on terminals that support such display enhancements. Current attributes of a window are applied to all characters that are written into the window with .CR waddch() , .CR wadd_wch() , .CR waddstr() , .CR waddchstr() , .CR waddwstr() , .Fn waddwchstr and .CR wprintw() . Attributes can be combined. .P Attributes can be specified using constants with the A_ prefix specified in .CR . The A_ constants manipulate attributes in objects of type .BR chtype . \ Additional attributes can be specified using constants with the WA_ prefix. The WA_ constants manipulate attributes in objects of type .BR attr_t . .P Two constants that begin with A_ and WA_ and that represent the same terminal capability refer to the same attribute in the .B terminfo database and in the window data structure. The effect on a window does not differ depending on whether the application specifies A_ or WA_ constants. For example, when an application updates window attributes using the interfaces that support the A_ values, a query of the window attribute using the function that returns WA_ values reflects this update. When it updates window attributes using the interfaces that support the WA_ values, for which corresponding A_ values exist, a query of the window attribute using the function that returns A_ values reflects this update. .SS "Rendition" The .I rendition of a character displayed on the screen is its attributes \ and a colour pair. .P The rendition of a character written to the screen becomes a property of the character and moves with the character through any scrolling and insert/delete line/character operations. To the extent possible on a particular terminal, a character's rendition corresponds to the graphic rendition of the character put on the screen. .P If a given terminal does not support a rendition that an application program is trying to use, Curses may substitute a different rendition for it. .P Colours are always used in pairs (referred to as colour-pairs). A colour-pair consists of a foreground colour (for characters) and a background colour (for the field on which the characters are displayed). .br .SS "Non-spacing Characters" The requirements in this section are in effect only for implementations that claim Enhanced Curses compliance. .P Some character sets may contain .I non-spacing characters. (Non-spacing characters are those for which .Fn wcwidth returns a width of zero.) The application may write non-spacing characters to a window. Every non-spacing character in a window is associated with a spacing character and modifies the spacing character. Non-spacing characters in a window cannot be addressed separately. A non-spacing character is implicitly addressed whenever a Curses operation affects the spacing character with which the non-spacing character is associated. .P Non-spacing characters do not support attributes. For interfaces that use wide characters and attributes, the attributes are ignored if the wide character is a non-spacing character. Multi-column characters have a single set of attributes for all columns. The association of non-spacing characters with spacing characters can be controlled by the application using the wide character interfaces. The wide character string functions provide codeset-dependent association. .P Two typical effects of a non-spacing character associated with a spacing character called \f2c\f1, are as follows: .RS .TP 5 .C \(bu The non-spacing character may modify the appearance of \f2c\f1. (For instance, there may be non-spacing characters that add diacritical marks to characters. However, there may also be spacing characters with built-in diacritical marks.) .TP .C \(bu The non-spacing character may bridge \f2c\f1 to the character following \f2c\f1. (Examples of this usage are the formation of ligatures and the conversion of characters into compound display forms, words, or ideograms.) .RE .P Implementations may limit the number of non-spacing characters that can be associated with a spacing character, provided any limit is at least 5. .SS "Complex Characters" A .I "complex character" is a set of associated characters, which may include a spacing character and may include any non-spacing characters associated with it. A .I "spacing complex character" is a spacing character followed by any non-spacing characters associated with it. That is, a spacing complex character is a complex character that includes one spacing character. An example of a code set that has complex characters is ISO/IEC 10646\-1:1993. .P A complex character can be written to the screen; if it does not include a spacing character, any non-spacing characters are associated with the spacing complex character that exists at the specified screen position. When the application reads information back from the screen, it obtains spacing complex characters. .P The .B cchar_t data type represents a complex character and its rendition. When a .B cchar_t represents a non-spacing complex character (that is, when there is no spacing character within the complex character), then its rendition is not used; when it is written to the screen, it uses the rendition specified by the spacing character already displayed. .P An object of type \f3cchar_t\f1 can be initialised using .Fn setcchar and its contents can be extracted using .CR getcchar() . The behaviour of functions that take a \f3cchar_t\f1 input argument is undefined if the application provides a \f3cchar_t\f1 value that was not initialised in this way or obtained from a Curses function that has a \f3cchar_t\f1 output argument. .SS "Window Properties" Associated with each window are the following properties that affect the placing of characters into the window (see \f3Rendition of Characters Placed into a Window\f1 in curses_intro). .SS "Window Rendition" Each window has a rendition, which is separate from the rendition component of the window's background property described below. .SS "Window Background" Each window has a background property. The background property specifies: .RS .TP 5 .C \(bu A spacing complex character (the background character) that will be used in a variety of situations where visible information is deleted from the screen. .TP .C \(bu A rendition to use in displaying the background character in those situations, and in other situations specified in \f3Rendition of Characters Placed into a Window\f1 in curses_intro. .RE .SH "Conceptual Operations" .SS "Screen Addressing" Many Curses functions use a coordinate pair. In the .B "DESCRIPTION" , coordinate locations are represented as (\f2y\f1, \f2x\f1) since the \f2y\f1 argument always precedes the \f2x\f1 argument in the function call. These coordinates denote a line/column position, not a character position. .P The coordinate \f2y\f1 always refers to the row (of the window), and \f2x\f1 always refers to the column. The first row and the first column is number 0, not 1. The position (0, 0) is the window's .I origin . .P For example, for terminals that display the ISO 8859\-1 character set (with left-to-right writing), (0, 0) represents the upper left-hand corner of the screen. .P Functions that start with .I mv take arguments that specify a (\f2y\f1, \f2x\f1) position and move the cursor (as though .Fn move were called) before performing the requested action. As part of the requested action, further cursor movement may occur, specified on the respective reference manual page. .SH "Basic Character Operations" .SS "Adding (Overwriting)" The Curses functions that contain the word add, such as .Fn addch , actually specify one or more characters to replace (overwrite) characters already in the window. If these functions specify only non-spacing characters, they are appended to a spacing character already in the window; see also \f3Non-spacing Characters (ENHANCED CURSES)\f1. .P When replacing a multi-column character with a character that requires fewer columns, the new character is added starting at the specified or implied column position. All columns that the former multi-column character occupied that the new character does not require are \f2orphaned columns\fP, which are filled using the background character and rendition. .P Replacing a character with a character that requires more columns also replaces one or more subsequent characters on the line. This process may also produce orphaned columns. .SS "Truncation, Wrapping and Scrolling" .P If the application specifies a character or a string of characters such that writing them to a window would extend beyond the end of the line (for example, if the application tries to deposit any multi-column character at the last column in a line), \ the behaviour depends on whether the function supports line wrapping: .RS .TP 5 .C \(bu If the function does not wrap, it fails. .TP .C \(bu If the function wraps, then it places one or more characters in the window at the start of the next line, beginning with the first character that would not completely fit on the original line. .P If the final character on the line is a multi-column character that does not completely fit on the line, the entire character wraps to the next line and columns at the end of the original line may be orphaned. .P If the original line was the last line in the window, the wrap may cause a scroll to occur: .RS .TP 5 .C \(em If scrolling is enabled, a scroll occurs. The contents of the first line of the window are lost. The contents of each remaining line in the window move to the previous line. The last line of the window is filled with any characters that wrapped. Any remaining space on the last line is filled with the background character and rendition. .TP .C \(em If scrolling is disabled, any characters that would extend beyond the last column of the last line are truncated. .RE .P The .Fn scrollok function enables and disables scrolling. .RE .P Some \f2add\f1 functions move the cursor just beyond the end of the last character added. If this position is beyond the end of a line, it causes wrapping and scrolling under the conditions specified in the second bullet above. .SS "Insertion" Insertion functions (such as .Fn insch ) insert characters immediately before the character at the specified or implied cursor position. .P The insertion shifts all characters that were formerly at or beyond the cursor position on the cursor line toward the end of that line. The disposition of the characters that would thus extend beyond the end of the line depends on whether the function supports wrapping: .RS .TP 5 .C \(bu If the function does not wrap, those characters are removed from the window. This may produce orphaned columns. .TP .C \(bu If the function supports wrapping, the effect is as described above in .B truncation (except that the overwriting discussed in the final dash is an insertion). .RE .P If multi-column characters are displayed, some cursor positions are within a multi-column character but not at the beginning of a character. Any request to insert data at a position that is not the beginning of a multi-column character will be adjusted so that the actual cursor position is at the beginning of the multi-column character in which the requested position occurs. .P There are no warning indications relative to cursor relocation. The application should not maintain an image of the cursor position, since this constitutes placing terminal-specific information in the application and defeats the purpose of using Curses. .P Portable applications cannot assume that a cursor position specified in an insert function is a reusable indication of the actual cursor position. .SS "Deletion" Deletion functions (such as .Fn delch ) delete the simple \ or complex \ character at the specified or implied cursor position, \ no matter which column of the character this is. \ All column positions are replaced by the background character and rendition and the cursor is not relocated. If a character-deletion operation would cause a previous wrapping operation to be undone, then the results are unspecified. .SS "Window Operations" Overlapping a window (that is, placing one window on top of another) and overwriting a window (that is, copying the contents of one window into another) follows the operation of overwriting \ multi-column \ glyphs around its edge. Any orphaned columns are handled as in the character operations. .SS "Characters that Straddle the Subwindow Border" A subwindow can be defined such that multi-column characters straddle the subwindow border. The character operations deal with these straddling characters as follows: .RS .TP 5 .C \(bu Reading the subwindow with a function such as .Fn in_wch reads the entire straddling character. .TP .C \(bu Adding, inserting or deleting in the subwindow deletes the entire straddling character before the requested operation begins and does not relocate the cursor. .TP .C \(bu Scrolling lines in the subwindow has the following effects: .RS .TP 5 .C \(em A straddling character at the start of the line is completely erased before the scroll operation begins. .TP .C \(em A straddling character at the end of the line moves in the direction of the scroll and continues to straddle the subwindow border. Column positions outside the subwindow at the straddling character's former position are orphaned unless another straddling character scrolls into those positions. .RE .RE .P If the application calls a function such as .Fn border , the above situations do not occur because writing the border on the subwindow deletes any straddling characters. .P In the above cases involving multi-column characters, operations confined to a subwindow can modify the screen outside the subwindow. Therefore, saving a subwindow, performing operations within the subwindow, and then restoring the subwindow may disturb the appearance of the screen. To overcome these effects (for example, for pop-up windows), the application should refresh the entire screen. .SH "Special Characters" Some functions process special characters as specified below. .P In functions that do not move the cursor based on the information placed in the window, these special characters would only be used within a string in order to affect the placement of subsequent characters; the cursor movement specified below does not persist in the visible cursor beyond the end of the operation. In functions that do move the cursor, these special characters can be used to affect the placement of subsequent characters and to achieve movement of the visible cursor. .RS .TP 18 .C Unless the cursor was already in column 0, moves the cursor one column toward the start of the current line and any characters after the are added or inserted starting there. .TP .C "" Unless the cursor was already in column 0, moves the cursor to the start of the current line. Any characters after the are added or inserted starting there. .TP .C In an add operation, Curses adds the background character into successive columns until reaching the end of the line. Scrolling occurs as described in \f3Truncation, Wrapping and Scrolling\f1 in curses_intro. Any characters after the character are added at the start of the new line. .P In an insert operation, moves the cursor to the start of a new line (causing scrolling as described in \f3Truncation, Wrapping and Scrolling\f1 in curses_intro). Any characters after the character are placed at the start of the new line. .P The .Fn filter function may inhibit this processing. .LI Tab characters in text move subsequent characters to the next horizontal tab stop. By default, tab stops are in column 0, 8, 16, and so on. .P In an insert or add operation, Curses inserts or adds, respectively, the background character into successive columns until reaching the next tab stop. If there are no more tab stops in the current line, wrapping and scrolling occur as described in \f3Truncation, Wrapping and Scrolling\f1 in curses_intro. .RE .SS "Control Characters" The Curses functions that perform special-character processing conceptually convert control characters to the caret ('\f4^\f1') character followed by a second character (which is an upper-case letter if it is alphabetic) and write this string to the window in place of the control character. The functions that retrieve text from the window will not retrieve the original control character. .SH "Rendition of Characters Placed into a Window" When the application adds or inserts characters into a window, the effect is as follows: .P If the character is not the space character, then the window receives: .RS .TP 5 .C \(bu the character that the application specifies .TP .C \(bu the colour that the application specifies; or the window colour, if the application does not specify a colour .TP .C \(bu the attributes specified, OR-ed with the window attributes. .RE .P If the character is the space character, then the window receives: .RS .TP 5 .C \(bu the background character .TP .C \(bu the colour that the application specifies; or the background colour, if the application does not specify a colour .TP .C \(bu the attributes specified, OR-ed with the background attributes. .RE .SH "Input Processing" The Curses input model provides a variety of ways to obtain input from the keyboard. .SH "Keypad Processing" The application can enable or disable .I "keypad translation" by calling .Fn keypad . When translation is enabled, Curses attempts to translate a sequence of terminal input that represents the pressing of a function key into a single key code. When translation is disabled, Curses passes terminal input to the application without such translation, and any interpretation of the input as representing the pressing of a keypad key must be done by the application. .P The complete set of key codes for keypad keys that Curses can process is specified by the constants defined in .Hd curses.h whose names begin with ``KEY_''. Each terminal type described in the .B terminfo database may support some or all of these key codes. The .B terminfo database specifies the sequence of input characters from the terminal type that correspond to each key code (see \f3Keypad\f1 in terminfo(4)). .P The Curses implementation cannot translate keypad keys on terminals where pressing the keys does not transmit a unique sequence. .P When translation is enabled and a character that could be the beginning of a function key (such as escape) is received, Curses notes the time and begins accumulating characters. If Curses receives additional characters that represent the pressing of a keypad key, within an unspecified interval from the time the first character was received, then Curses converts this input to a key code for presentation to the application. If such characters are not received during this interval, translation of this input does not occur and the individual characters are presented to the application separately. (Because Curses waits for this interval to accumulate a key code, many terminals experience a delay between the time a user presses the escape key and the time the escape is returned to the application.) .P In addition, No Timeout Mode provides that in any case where Curses has received part of a function key sequence, it waits indefinitely for the complete key sequence. The ``unspecified interval'' in the previous paragraph becomes infinite in No Timeout Mode. No Timeout Mode allows the use of function keys over slow communication lines. No Timeout Mode lets the user type the individual characters of a function key sequence, but also delays application response when the user types a character (not a function key) that begins a function key sequence. For this reason, in No Timeout Mode many terminals will appear to hang between the time a user presses the escape key and the time another key is pressed. No Timeout Mode is switchable by calling .Fn notimeout . .P If any special characters (see \f3Special Characters\f1 in curses_intro) are defined or redefined to be characters that are members of a function key sequence, then Curses will be unable to recognise and translate those function keys. .P Several of the modes discussed below are described in terms of availability of input. If keypad translation is enabled, then input is not available once Curses has begun receiving a keypad sequence until the sequence is completely received or the interval has elapsed. .br .ne 30 .SH "Input Mode" The \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification (\f3Special Characters\fP) defines flow-control characters, the interrupt character, the erase character, and the kill character. Four mutually-exclusive Curses modes let the application control the effect of these input characters: .ift .bp .PP .TS box tab(`); cb | cbw(50) l | l. Input Mode`Effect _ Cooked Mode`T{ This achieves normal line-at-a-time processing with all special characters handled outside the application. This achieves the same effect as canonical-mode input processing as specified in the \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification . The state of the ISIG and IXON flags are not changed upon entering this mode by calling .CR cbreak (), and are set upon entering this mode by calling .CR noraw (). T} .P .sP eC `T{ \*!The implementation supports erase and kill characters from any supported locale, no matter what the width of the character is. T} .P \f2cbreak\f1 Mode`T{ Characters typed by the user are immediately available to the application and Curses does not perform special processing on either the erase character or the kill character. An application can select \f2cbreak\f1 mode to do its own line editing but to let the abort character be used to abort the task. This mode achieves the same effect as non-canonical-mode, Case B input processing (with MIN set to 1 and ICRNL cleared) as specified in the \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification . The state of the ISIG and IXON flags are not changed upon entering this mode. T} .P Half-Delay Mode`T{ The effect is the same as \f2cbreak\fP, except that input functions wait until a character is available or an interval defined by the application elapses, whichever comes first. This mode achieves the same effect as non-canonical-mode, Case C input processing (with TIME set to the value specified by the application) as specified in the \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification . The state of the ISIG and IXON flags are not changed upon entering this mode. T} .P Raw Mode`T{ Raw mode gives the application maximum control over terminal input. The application sees each character as it is typed. This achieves the same effect as non-canonical mode, Case D input processing as specified in the \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification . The ISIG and IXON flags are cleared upon entering this mode. T} .TE .P The terminal interface settings are recorded when the process calls .Fn initscr or .Fn newterm to initialise Curses and restores these settings when .Fn endwin is called. The initial input mode for Curses operations is unspecified \ unless the implementation supports Enhanced Curses compliance, in which the initial input mode is \f2cbreak\f1 mode. .P The behaviour of the BREAK key depends on other bits in the display driver that are not set by Curses. .br .ne 10 .SH "Delay Mode" Two mutually-exclusive delay modes specify how quickly certain Curses functions return to the application when there is no terminal input waiting when the function is called: .RS .TP 15 .C "No Delay" The function fails. .TP .C "Delay" The application waits until the implementation passes text through to the application. If \f2cbreak\f1 or Raw Mode is set, this is after one character. Otherwise, this is after the first character, end-of-line character, or end-of-file character. .RE .P The effect of No Delay Mode on function key processing is unspecified. .SH "Echo Processing" Echo mode determines whether Curses echoes typed characters to the screen. The effect of Echo mode is analogous to the effect of the ECHO flag in the local mode field of the \f3termios\f1 structure associated with the terminal device connected to the window. However, Curses always clears the ECHO flag while it is operating, to inhibit the operating system from performing echoing. The method of echoing characters is not identical to the operating system's method of echoing characters, because Curses performs additional processing of terminal input. .P If in Echo mode, Curses performs its own echoing: Any visible input character is stored in the current or specified window by the input function that the application called, at that window's cursor position, as though .Fn addch were called, with all consequent effects such as cursor movement and wrapping. .P If not in Echo mode, any echoing of input must be performed by the application. Applications often perform their own echoing in a controlled area of the screen, or do not echo at all, so they disable Echo mode. .SH "The Set of Curses Functions" The Curses functions allow: overall screen, window and pad manipulation; output to windows and pads; reading terminal input; control over terminal and Curses input and output options; environment query functions; colour manipulation; use of soft label keys; access to the \f3terminfo\f1 database of terminal capabilities; and access to low-level functions. .SH "Function Name Conventions" The reference manual pages present families of multiple Curses functions. Most function families have different functions that give the programmer the following options: .RS .TP 5 .C \(bu A function with the basic name operates on the window .I stdscr . A function with the same name plus the \f2w\f1 prefix operates on a window specified by the \f2win\f1 argument. .P When the reference manual page for a function family refers to the .I "current or specified window" , it means .I stdscr for the basic functions and the window specified by \f2win\f1 for any \f2w\f1 function. .P Functions whose names have the \f2p\f1 prefix require an argument that is a pad instead of a window. .TP .C \(bu A function with the basic name operates based on the current cursor position (of the current or specified window, as described above). A function with the same name plus the \f2mv\f1 prefix moves the cursor to a position specified by the \f2y\f1 and \f2x\f1 arguments before performing the specified operation. .P When the reference manual page for a function family refers to the .I "current or specified position" , it means the cursor position for the basic functions and the position (\f2y\fP, \f2x\fP) for any \f2mv\f1 function. .P The \f2mvw\f1 prefix exists and combines the \f2mv\f1 semantics discussed here with the \f2w\f1 semantics discussed above. The window argument is always specified before the coordinates. .TP .C \(bu A function with the basic name is often provided for historical compatibility and operates only on single-byte characters. A function with the same name plus the \f2w\f1 infix operates on wide (multi-byte) characters. A function with the same name plus the \f2_w\f1 infix operates on complex characters and their renditions. .TP .C \(bu When a function with the basic name operates on a single character, there is sometimes a function with the same name plus the \f2n\f1 infix that operates on multiple characters. An \f2n\f1 argument specifies the number of characters to process. The respective manual page specifies the outcome if the value of \f2n\f1 is inappropriate. .RE .SK .SH "Function Families Provided" .PP .TS box center tab(`); cb1 cb1 | ce1 | ce1 | ce1 | cb li l | c | c | c | li. Function Names`Description`s`w`c`Refer to _ `\f3Add (Overwrite)\f1 \f1[\f2mv\f1][\f2w\f1]\f2addch\*(Z$`add a character`Y`Y`Y`addch\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2addch\f1[\f2n\f1]\f2str\*(Z$`add a character string`N`N`N`addchstr\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2add\f1[\f2n\f1]\f2str\*(Z$`add a string`Y`Y`Y`addnstr\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2add\f1[\f2n\f1]\f2wstr\*(Z$`add a wide character string`Y`Y`Y`addnwstr\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2add_wch\*(Z$`add a wide character and rendition`Y`Y`Y`add_wch\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2add_wch\f1[\f2n\f1]\f2str\*(Z$`add an array of wide characters and renditions`?`N`N`add_wchnstr\*(Z$ _ `\f3Change Renditions\f1 \f1[\f2mv\f1][\f2w\f1]\f2chgat\*(Z$`change renditions of characters in a window`-`N`N`chgat\*(Z$ _ `\f3Delete\f1 \f1[\f2mv\f1][\f2w\f1]\f2delch\*(Z$`delete a character`-`-`N`delch\*(Z$ _ `\f3Get (Input from Keyboard to Window)\f1 \f1[\f2mv\f1][\f2w\f1]\f2getch\*(Z$`get a character`Y`Y`Y`getch\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2get\f1[\f2n\f1]\f2str\*(Z$`get a character string`Y`Y`Y`getnstr\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2get_wch\*(Z$`get a wide character`Y`Y`Y`get_wch\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2get\f1[\f2n\f1]\f2_wstr\*(Z$`get an array of wide characters and key codes`Y`Y`Y`get_wstr\*(Z$ _ `\f3Explicit Cursor Movement\f1 \f1[\f2w\f1]\f2move\*(Z$`move the cursor`-`-`-`move\*(Z$ _ `\f3Input (Read Back from Window)\f1 \f1[\f2mv\f1][\f2w\f1]\f2inch\*(Z$`input a character`-`-`-`inch\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2inch\f1[\f2n\f1]\f2str\*(Z$`input an array of characters and attributes`-`-`-`inchnstr\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2in\f1[\f2n\f1]\f2str\*(Z$`input a string`-`-`-`innstr\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2in\f1[\f2n\f1]\f2wstr\*(Z$`input a string of wide characters`-`-`-`innwstr\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2in_wch\*(Z$`input a wide character and rendition`-`-`-`in_wch\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2in_wch\f1[\f2n\f1]\f2str\*(Z$`input an array of wide characters and renditions`-`-`-`inwchnstr\*(Z$ _ `\f3Insert\f1 \f1[\f2mv\f1][\f2w\f1]\f2insch\*(Z$`insert a character`Y`N`N`insch\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2ins\f1[\f2n\f1]\f2str\*(Z$`insert a character string`Y`N`N`insnstr\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2ins_\f1[\f2n\f1]\f2wstr\*(Z$`insert a wide-character string`Y`N`N`ins_nwstr\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2ins_wch\*(Z$`insert a wide character`Y`N`N`ins_wch\*(Z$ _ `\f3Print and Scan\f1 \f1[\f2mv\f1][\f2w\f1]\f2printw\*(Z$`print formatted output`-`-`-`mvprintw\*(Z$ \f1[\f2mv\f1][\f2w\f1]\f2scanw\*(Z$`convert formatted output`-`-`-`mvscanw\*(Z$ .TE .sp -1v \" TO FIT ON A SINGLE PAGE .PP .PP .SS "Legend" The following notation indicates the effect when characters are moved to the screen. (For the Get functions, this applies only when echoing is enabled.) .RS .TP 4 .C s Y means these functions perform special-character processing (see \f3Special Characters\f1 in curses_intro). N means they do not. ? means the results are unspecified when these functions are applied to special characters. .TP .C w Y means these functions perform wrapping (see \f3Truncation, Wrapping and Scrolling\f1 in curses_intro). N means they do not. .TP .C c Y means these functions advance the cursor (see \f3Truncation, Wrapping and Scrolling\f1 in curses_intro). N means they do not. .TP .C - The attribute specified by this column does not apply to these functions. .RE .SH "Interfaces Implemented as Macros" The following interfaces with arguments must be implemented as macros. The relevance to the application programmer is that the `\f4&\f1' character cannot be used before the arguments. .P .TS box tab(`) center; cb cb l l. Macros`Man page Entry _ COLOR_PAIR\^(\|)`\f2can_change_color\fP\^(\|) \f2getbegyx\fP\^(\|), \f2getmaxyx\fP\^(\|), \f2getparyx\fP\^(\|), \f2getyx\fP\^(\|)`\f2getbegyx\fP\^(\|) .TE .P The header file reference manual pages list other macros, like COLOR_BLACK, that do not take arguments. .nr Ej 1 .SH "Initialised Curses Environment" .nr Ej 2 Before executing an application that uses Curses, the terminal must be prepared as follows: .RS .TP 5 .C \(bu If the terminal has hardware tab stops, they should be set. .TP .C \(bu Any initialisation strings defined for the terminal must be output to the terminal. .RE .P The resulting state of the terminal must be compatible with the model of the terminal that Curses has, as reflected in the terminal's entry in the .B terminfo database (see .IR terminfo (4)). .P To initialise Curses, the application must call .Fn initscr or .Fn newterm before calling any of the other functions that deal with windows and screens, and it must call .Fn endwin before exiting. To get character-at-a-time input without echoing (most interactive, screen-oriented programs want this), the following sequence should be used: .P .DS I .Fn initscr .Fn cbreak .Fn noecho .DE .P Most programs would additionally use the sequence: .P .DS I .Fn nonl \f2intrflush\f1(\f2stdscr\f1, FALSE) \f2keypad\f1(\f2stdscr\f1, TRUE) .DE .SH "Synchronous and Networked Asynchronous Terminals" This section indicates to the application writer some considerations to be borne in mind when driving synchronous, networked asynchronous (NWA) or non-standard directly-connected asynchronous terminals. .P Such terminals are often used in a mainframe environment and communicate to the host in block mode. That is, the user types characters at the terminal then presses a special key to initiate transmission of the characters to the host. .P Frequently, although it may be possible to send arbitrary sized blocks to the host, it is not possible or desirable to cause a character to be transmitted with only a single keystroke. .P This can cause severe problems to an application wishing to make use of single-character input; see \f3Input Processing\f1 in curses_intro. .SS "Output" The Curses interface can be used in the normal way for all operations pertaining to output to the terminal, with the possible exception that on some terminals the .Fn refresh routine may have to redraw the entire screen contents in order to perform any update. .P If it is additionally necessary to clear the screen before each such operation, the result could be undesirable. .SS "Input" Because of the nature of operation of synchronous (block-mode) and NWA terminals, it might not be possible to support all or any of the Curses input functions. In particular, the following points should be noted: .RS .TP 5 .C \(bu Single-character input might not be possible. It may be necessary to press a special key to cause all characters typed at the terminal to be transmitted to the host. .TP .C \(bu It is sometimes not possible to disable echo. Character echo may be performed directly by the terminal. On terminals that behave in this way, any Curses application that performs input should be aware that any characters typed will appear on the screen at wherever the cursor is positioned. This does not necessarily correspond to the position of the cursor in the window. .RE .P .eF e .\" .\" index@\f4curses_intro\f1 \- introduction to curses@@@\f3curses_intro(3X)\f1 .\" .\" toc@\f3curses_intro(3X)\f1:\0\0\f4curses_intro\f1@@@introduction to curses .\" .\" fileset_database@curses_intro.3x CURS-ENG-A-MAN .\" $Header: cuserid.3s,v 72.5 94/11/14 13:16:21 ssa Exp $ .TA c .TH cuserid 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cuserid(\|) \- get character login name of the user .SH SYNOPSIS .C "#include " .PP .C "char *cuserid(char *s);" .SS Remarks: Because this function behaved differently in previous releases of HP-UX, and behaves differently on other systems, its use is not recommended. It is provided only for conformance to current industry standards, and is subject to withdrawal in future releases of HP-UX. .PP For portability and security, application writers and maintainers should search their existing code and replace references to .C cuserid() with equivalent calls to .CR getpwuid(getuid()) , .CR getpwuid(geteuid()) , or .CR getlogin() , depending on which user name is desired. .SH DESCRIPTION .CR cuserid() generates a character-string representation of the user name corresponding to the effective user .SM ID of the process. If .I s is a .SM NULL pointer, this representation is generated in an internal static area, the address of which is returned. Otherwise, .I s is assumed to point to an array of at least .CR L_cuserid characters; the representation is left in this array. The constant .CR L_cuserid is defined in the .RC < stdio.h > header file. .PP For multi-thread applications, if .I s is a .SM NULL pointer, the operation is not performed and a .SM NULL pointer is returned. .SH DIAGNOSTICS If the login name cannot be found, .CR cuserid() returns a .SM NULL pointer; if .I s is not a .SM NULL pointer, a null character .RC ( \e0 ) is placed at .IR s [0]. .SH SEE ALSO geteuid(2), getlogin(3C), getpwuid(3C). .SH STANDARDS CONFORMANCE .CR cuserid() ": AES, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4cuserid()\fP \- get character-string login name of the user@@@\f3cuserid(3S)\f1 .\" index@character-string login name of the user, get@@@\f3cuserid(3S)\f1 .\" index@login name of the user, get character-string@@@\f3cuserid(3S)\f1 .\" index@name: get character-string representation of user login name@@@\f3cuserid(3S)\f1 .\" index@user login name, get character-string representation of@@@\f3cuserid(3S)\f1 .\" .\" toc@\f3cuserid(3S)\f1:\0\0\f4cuserid()\fP@@@get character login name of the user .\" $Header: datalock.3c,v 72.3 93/01/14 14:45:46 ssa Exp $ .TA d .TH datalock 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME datalock(\|) \- lock process into memory after allocating data and stack space .SH SYNOPSIS .C "#include " .PP .C "int datalock(size_t datsiz, size_t stsiz);" .SH DESCRIPTION .C datalock() allocates at least .I datsiz bytes of data space and .I stsiz bytes of stack space, then locks the program in memory. The data space is allocated by .C malloc() (see .IR malloc (3C)). After the program is locked, this space is released by .C free() (see .IR malloc (3C)), making it available for use. This allows the calling program to use that much space dynamically without receiving the .C SIGSEGV signal. .PP The effective user .SM ID of the calling process must be super-user or be a member of or have an effective group .SM ID of a group having .SM PRIV_MLOCK access to use this call (see .IR setprivgrp (2)). .SH EXAMPLES The following call to .C datalock() allocates 4096 bytes of data space and 2048 bytes of stack space, then locks the process in memory: .IP .C "datalock (4096, 2048);" .SH RETURN VALUE .C datalock() returns \-1 if .C malloc() cannot allocate enough memory or if .C plock() returned an error (see .IR plock (2)). .SH WARNINGS Multiple datalocks cannot be the same as one big one. .PP Methods for calculating the required size are not yet well developed. .SH AUTHOR .C datalock() was developed by HP. .SH SEE ALSO getprivgrp(2), plock(2). .\" index@\f4datalock()\fP \- lock process into memory after allocating data and stack space@@@\f3datalock(3C)\f1 .\" index@lock process into memory after allocating data and stack space@@@\f3datalock(3C)\f1 .\" index@process, lock into memory after allocating data and stack space@@@\f3datalock(3C)\f1 .\" index@memory, lock process into after allocating data and stack space@@@\f3datalock(3C)\f1 .\" index@allocate data and stack space then lock process into memory@@@\f3datalock(3C)\f1 .\" index@data and stack space, allocate then lock process into memory@@@\f3datalock(3C)\f1 .\" index@stack and data space, allocate then lock process into memory@@@\f3datalock(3C)\f1 .\" index@space, stack and data, allocate then lock process into memory@@@\f3datalock(3C)\f1 .\" .\" toc@\f3datalock(3C)\f1:\0\0\f4datalock()\fP@@@lock process into memory after allocating data and stack space .\" .\" fileset_database@datalock.3c PROGRAMING-MAN .\" $Header: ctime.3c,v 76.1 95/07/05 17:27:14 ssa Exp $ .TA c .TH ctime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctime(\|), ctime_r(\|), localtime(\|), localtime_r(\|), gmtime(\|), gmtime_r(\|), mktime(\|), difftime(\|), asctime(\|), asctime_r(\|), timezone(\|), daylight(\|), tzname(\|), tzset(\|) \- convert date and time to string .SH SYNOPSIS .nf .C "#include " .PP .C "char *asctime(const struct tm *timeptr);" .PP .C "int asctime_r(const struct tm *timeptr, char *buffer, int buflen);" .PP .C "char *ctime(const time_t *timer);" .PP .C "int ctime_r(const time_t *timer, char *buffer, int buflen);" .PP .C "double difftime(time_t time1, time_t time0);" .PP .C "struct tm *gmtime(const time_t *timer);" .PP .C "int gmtime_r(const time_t *timer, struct tm *result);" .PP .C "struct tm *localtime(const time_t *timer);" .PP .C "int localtime_r(const time_t *timer, struct tm *result);" .PP .C "time_t mktime(struct tm *timeptr);" .PP .C "extern long timezone;" .PP .C "extern int daylight;" .PP .C "extern char *tzname[2];" .PP .C "void tzset(void);" .fi .SH DESCRIPTION .TP 18 .C asctime() Convert the broken-down time contained in the structure pointed to by .I timeptr and return a pointer to a 26-character string in the form: .RS .IP .C "Sun Sep 16 01:03:52 1973\en\e0" .RE .IP All the fields have constant width. .TP .C asctime_r() is identical to .CR asctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C ctime() Convert the calendar time pointed to by .IR timer , representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: .RS .IP .C asctime(localtime(timer)) .RE .TP .C ctime_r() is identical to .CR ctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C gmtime() Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. .C gmtime() returns a pointer to the .C tm structure described below. .TP .C gmtime_r() is identical to .CR gmtime() , except that .C gmtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C localtime() Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA\c), according to the contents of the TZ environment variable (see Environment Variables below). .C localtime() returns a pointer to the .C tm structure described below. .TP .C localtime_r() is identical to .CR localtime() , except that .C localtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C difftime() Return the difference in seconds between two calendar times: .IR "time1 \(mi time0" . .TP .C mktime() Convert the broken-down time (expressed as local time) in the structure pointed to by .I timeptr into a calendar time value with the same encoding as that of the values returned by .IR time (2). The original values of the .C tm_wday and .C tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below. .IP A positive or zero value for .C tm_isdst causes .C mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for .C tm_isdst causes .C mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time. .IP Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of .C tm_mday is not set until .C tm_mon and .C tm_year are determined. .C mktime() returns the specified calendar time encoded as a value of type .CR time_t . .IP If the calendar time cannot be represented, the function returns the value .RC ( time_t )\|\(em\|1 and sets .C errno to .CR ERANGE . Note the value .RC ( time_t )\|\(em\|1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and .C errno to reliably detect an error condition. .TP .C tzset() Sets the values of the external variables .IR timezone , .IR daylight , and .I tzname according to the contents of the .C TZ environment variable (independent of any time value). The functions .CR localtime() , .CR mktime() , .CR ctime() , .CR asctime() , and .C strftime() (see .IR strftime (3C)) call .C tzset() and use the values returned in the external variables described below for their operations. .C tzset() can also be called directly by the user. .PP The .RC < time.h > header file contains declarations of all relevant functions and externals. It also contains the .C tm structure, which includes the following members: .RS .PP .nf .ift .ft 4 .ps +1 int tm_sec; /* seconds after the minute - [0,61] */ int tm_min; /* minutes after the hour - [0,59] */ int tm_hour; /* hours - [0,23] */ int tm_mday; /* day of month - [1,31] */ int tm_mon; /* month of year - [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday - [0,6] */ int tm_yday; /* days since January 1 - [0,365] */ int tm_isdst; /* daylight savings time flag */ .ift .ft .ps .fi .PP The value of .C tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available. .RE .PP The external variable .C timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), .C timezone is 5\(**60\(**60). The external variable .C daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable .C tzname[2] contains the local standard and local summer time zone abbreviations as specified by the .C TZ environment variable. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .SS Environment Variables The .C tzset() function uses the contents of .C TZ to set the values of the external variables .CR timezone , .C daylight , and .CR tzname . .C TZ also determines the time zone name substituted for the .C %Z and .C %z directives and the time zone adjustments performed by .CR localtime() , .CR mktime() , and .CR ctime() . Two methods for specifying a time zone within .C TZ are described in .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH "RETURN VALUE" .PP For .C asctime_r() and .C ctime_r(), if the buffer is of insufficient length, -1 is returned. For .C asctime_r(), ctime_r(), gmtime_r(), and .C localtime_r(), if the operation is successful, 0 is returned. .SH WARNINGS The return values for .CR asctime() , .CR ctime() , .CR gmtime() , and .CR localtime() point to static data whose contents is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() are MT-Safe and should be used instead. .PP Users of .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .PP The range of .C tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by .IR time (2) and passed as the .I timer argument does not include accumulated leap seconds. The .C tm structure generated by .C localtime() and .C gmtime() will never reflect any leap seconds. Upon successful completion, .C mktime() forces the value of the .C tm_sec component to the range [0,59]. .PP .CR ctime() , .CR ctime_r() , .CR asctime() , and .CR asctime_r() are considered obsolescent and may be removed in a future release. Use of .IR strftime (3C) is recommended instead. .SH AUTHOR .C ctime() was developed by AT&T and HP. .SH SEE ALSO time(2), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR ctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR asctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR daylight ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR difftime() ": AES, SVID3, XPG4, ANSI C" .PP .CR gmtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR localtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mktime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR timezone ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR tzname ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tzset() ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4asctime()\fP, \f4asctime_r()\f1 \- convert \f3tm\f1 structure date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4ctime()\fP, \f4ctime_r()\f1 \- convert \f4clock()\fP date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4daylight()\fP \- Daylight Savings Time flag@@@\f3ctime(3C)\f1 .\" index@\f4gmtime()\fP, \f4gmtime_r()\fP \- convert date and time to Greenwich Mean Time@@@\f3ctime(3C)\f1 .\" index@\f4localtime()\fP, \f4localtime_r()\fP \- convert date and time to local timezone@@@\f3ctime(3C)\f1 .\" index@\f4timezone()\fP \- difference between \s-1UCT\s+1 and local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzname()\fP \- name of local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzset()\fP \- initialize \f4timezone()\fP, \f4daylight()\fP, and \f4tzname()\fP using \s-1TZ\s+1 variable@@@\f3ctime(3C)\f1 .\" index@\f4mktime()\fP \- convert time into calendar time value@@@\f3ctime(3C)\f1 .\" index@\f4difftime()\fP \- difference between two calendar time values@@@\f3ctime(3C)\f1 .\" index@convert date and time to string@@@\f3ctime(3C)\f1 .\" index@string, convert date and time to@@@\f3ctime(3C)\f1 .\" index@date and time, convert to string@@@\f3ctime(3C)\f1 .\" index@time and date, convert to string@@@\f3ctime(3C)\f1 .\" .\" toc@\f3ctime(3C)\f1:\0\0\f4ctime()\fP, \f4ctime_r()\fP, \f4localtime()\fP, \f4localtime_r()\fP, \f4difftime()\f1, \f4 mktime()\f1, \n\f4gmtime()\fP, \f4gmtime_r()\fP,\f4asctime()\fP, \f4asctime_r()\fP, \f4timezone()\fP, \f4daylight()\fP, \f4tzname()\fP,\n\f4tzset()\f1@@@convert date and time to string .\" toc@\f4ctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4ctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4timezone()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4daylight()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzname()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzset()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4difftime()\fP:\0\0difference between calendar times@@@see \f3ctime(3C)\f1 .\" toc@\f4mktime()\fP:\0\0create calendar time value@@@see \f3ctime(3C)\f1 .\" .\" links@ctime.3c ctime_r.3c .\" links@ctime.3c localtime.3c .\" links@ctime.3c localtime_r.3c .\" links@ctime.3c gmtime.3c .\" links@ctime.3c gmtime_r.3c .\" links@ctime.3c asctime.3c .\" links@ctime.3c asctime_r.3c .\" links@ctime.3c timezone.3c .\" links@ctime.3c daylight.3c .\" links@ctime.3c tzname.3c .\" links@ctime.3c tzset.3c .\" links@ctime.3c difftime.3c .\" links@ctime.3c mktime.3c .\" .\" fileset_database@ctime.3c PROGRAMING-MAN .\" $Header: dbm.3x,v 76.1 95/07/05 17:27:37 ssa Exp $ .TA d .TH dbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbminit, fetch, store, delete, firstkey, nextkey, dbmclose \- database subroutines .SH SYNOPSIS .C "#include " .P .C "int dbminit(const char *file);" .P .C "datum fetch(datum key);" .P .C "int store(datum key, datum content);" .P .C "int delete(datum key);" .P .C "datum firstkey(void);" .P .C "datum nextkey(datum key);" .P .C "int dbmclose(void);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can locate a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .I dptr. Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbminit . At the time of this call, the files .IC file .dir and .IC file .pag must exist. (An empty database is created by creating zero-length .C .dir and .C .pag files.) .PP Once open, data stored under a key is accessed by .IC fetch , and data is placed under a key by .IC store . Storing data on an existing key replaces the existing data. A key (and its associated contents) is deleted by .CR delete . A linear pass through all keys in a database can be made, in (apparently) random order by using .C firstkey and .CR nextkey . .C firstkey returns the first key in the database. With any key, .C nextkey returns the next key in the database. The following code can be used to traverse the database: .IP .C "for (key = firstkey(); key.dptr != NULL; key = nextkey(key))" .PP A database can be closed by calling .C dbmclose. A currently open database must be closed before opening a new one. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .IR dptr . .SH WARNINGS The .I dbm functions provided in this library should not be confused in any way with those of a general-purpose database management system such as .SM ALLBASE/HP-UX SQL. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful data base functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C store returns an error if a disk block fills with inseparable data. .PP .C delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C firstkey and .C nextkey depends on a hashing function, not on anything interesting. .PP A .C store or .C delete during a pass through the keys by .C firstkey and .C nextkey may yield unexpected results. .SH AUTHOR .IR dbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO ndbm(3X). .\" index@\f4dbminit()\fP \- open a single database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4fetch()\fP \- access data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4store()\fP \- store data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4delete()\fP \- delete key and data under it (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4firstkey()\fP \- get first key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4nextkey()\fP \- get next key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4dbmclose()\fP \- close currently open database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@database subroutines (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" index@subroutines, database (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" .\" toc@\f3dbm(3X)\f1:\0\0\f4dbminit()\fP, \f4fetch()\fP, \f4store()\fP, \f4delete()\fP, \f4firstkey()\fP,\n\f4nextkey()\fP, \f4dbmclose()\fP@@@database subroutines .\" toc@\f4dbminit()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4fetch()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4store()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4delete()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4firstkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4nextkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4dbmclose()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" .\" links@dbm.3x dbminit.3x .\" links@dbm.3x fetch.3x .\" links@dbm.3x store.3x .\" links@dbm.3x delete.3x .\" links@dbm.3x firstkey.3x .\" links@dbm.3x nextkey.3x .\" links@dbm.3x dbmclose.3x .\" .\" fileset_database@dbm.3x PROGRAMING-MAN .\" $Header: ndbm.3x,v 78.1 96/02/13 14:30:00 ssa Exp $ .TA n .TH ndbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr \- database subroutines .SH SYNOPSIS .C "#include " .PP .C "DBM *dbm_open(const char *file, int flags, mode_t mode);" .PP .C "void dbm_close(DBM *db);" .PP .C "datum dbm_fetch(DBM *db, datum key);" .PP .C "int dbm_store(DBM *db, datum key, datum content, int flags);" .PP .C "int dbm_delete(DBM *db, datum key);" .PP .C "datum dbm_firstkey(DBM *db);" .PP .C "datum dbm_nextkey(DBM *db);" .PP .C "int dbm_error(DBM *db);" .PP .C "int dbm_clearerr(DBM *db);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can access a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .IR dptr . Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbm_open . This will open and/or create the files .IC file .dir and .IC file .pag depending on the .I flags parameter (see .IR open (2)). .PP Once open, the data stored under a key is accessed by .C dbm_fetch and data is placed under a key by .CR dbm_store . The .I flags field can be either .C DBM_INSERT or .CR DBM_REPLACE . .C DBM_INSERT can only insert new entries into the database, and cannot change an existing entry having the same key. .C DBM_REPLACE replaces an existing entry if it has the same key. A key (and its associated contents) is deleted by .CR dbm_delete . A linear pass through all keys in a database can be made in (apparently) random order by use of .C dbm_firstkey and .CR dbm_nextkey . .C dbm_firstkey returns the first key in the database. .C dbm_nextkey returns the next key in the database, The following code can be used to traverse the database: .IP .C "for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))" .PP .C dbm_error returns non-zero when an error has occurred reading or writing the database. .C dbm_clearerr resets the error condition on the named database. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .I dptr. If .CR dbm_store is called with a .I flags value of .C DBM_INSERT and finds an existing entry with the same key, a value of .C 1 is returned. If a call to .CR dbm_store results in an internal block overflow, a value of -2 is returned. .SH WARNINGS The .I ndbm functions provided in this library should not be confused in any way with those of a general-purpose database management system. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful database functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The pointer to data that is returned from these functions are not aligned. This can cause problems if the block contains data that must be aligned to a specific boundry. If the block contains data that must be aligned, the block should be copied to an appropriately aligned area. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C dbm_store returns an error in the event that a disk block fills with inseparable data. .PP .C dbm_delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C dbm_firstkey and .C dbm_nextkey depends on a hashing function, not on anything interesting. .PP A .C dbm_store or .C dbm_delete during a pass through the keys by .C dbm_firstkey and .C dbm_nextkey may yield unexpected results. .SH AUTHOR .IR ndbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO dbm(3X). .\" index@\f4dbm_clearerr\f1 \- reset error condition on named database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_close\f1 \- close an open database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_delete\f1 \- delete a database key and associated contents@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_error\f1 \- error in reading or writing in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_fetch\f1 \- access a database entry under a key@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_firstkey\f1 \- get first key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_nextkey\f1 \- get next key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_open\f1 \- open a database for access@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_store\f1 \- store an entry under a key in a database@@@\f3ndbm(3X)\f1 .\" index@database subroutines (new multiple database version)@@@\f3ndbm(3X)\f1 .\" index@subroutines, database (new multiple database version)@@@\f3ndbm(3X)\f1 .\" .\" toc@\f3ndbm(3X)\f1:\0\0\f4dbm_open()\f1, \f4dbm_close()\f1, \f4dbm_fetch()\f1, \f4dbm_store()\f1, \f4dbm_delete()\f1, \n\f4dbm_firstkey()\f1, \f4dbm_nextkey()\f1, \f4dbm_error()\f1, \f4dbm_clearerr()\f1@@@database subroutines .\" toc@\f4dbm_open\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_close\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_fetch\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_store\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_delete\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_firstkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_nextkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_error\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_clearerr\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" .\" links@ndbm.3x dbm_open.3x .\" links@ndbm.3x dbm_close.3x .\" links@ndbm.3x dbm_fetch.3x .\" links@ndbm.3x dbm_store.3x .\" links@ndbm.3x dbm_delete.3x .\" links@ndbm.3x dbm_firstke.3x .\" links@ndbm.3x dbm_nextkey.3x .\" links@ndbm.3x dbm_error.3x .\" links@ndbm.3x dbm_clearer.3x .\" .\" fileset_database@ndbm.3x PROGRAMING-MAN .\" $Header: ndbm.3x,v 78.1 96/02/13 14:30:00 ssa Exp $ .TA n .TH ndbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr \- database subroutines .SH SYNOPSIS .C "#include " .PP .C "DBM *dbm_open(const char *file, int flags, mode_t mode);" .PP .C "void dbm_close(DBM *db);" .PP .C "datum dbm_fetch(DBM *db, datum key);" .PP .C "int dbm_store(DBM *db, datum key, datum content, int flags);" .PP .C "int dbm_delete(DBM *db, datum key);" .PP .C "datum dbm_firstkey(DBM *db);" .PP .C "datum dbm_nextkey(DBM *db);" .PP .C "int dbm_error(DBM *db);" .PP .C "int dbm_clearerr(DBM *db);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can access a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .IR dptr . Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbm_open . This will open and/or create the files .IC file .dir and .IC file .pag depending on the .I flags parameter (see .IR open (2)). .PP Once open, the data stored under a key is accessed by .C dbm_fetch and data is placed under a key by .CR dbm_store . The .I flags field can be either .C DBM_INSERT or .CR DBM_REPLACE . .C DBM_INSERT can only insert new entries into the database, and cannot change an existing entry having the same key. .C DBM_REPLACE replaces an existing entry if it has the same key. A key (and its associated contents) is deleted by .CR dbm_delete . A linear pass through all keys in a database can be made in (apparently) random order by use of .C dbm_firstkey and .CR dbm_nextkey . .C dbm_firstkey returns the first key in the database. .C dbm_nextkey returns the next key in the database, The following code can be used to traverse the database: .IP .C "for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))" .PP .C dbm_error returns non-zero when an error has occurred reading or writing the database. .C dbm_clearerr resets the error condition on the named database. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .I dptr. If .CR dbm_store is called with a .I flags value of .C DBM_INSERT and finds an existing entry with the same key, a value of .C 1 is returned. If a call to .CR dbm_store results in an internal block overflow, a value of -2 is returned. .SH WARNINGS The .I ndbm functions provided in this library should not be confused in any way with those of a general-purpose database management system. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful database functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The pointer to data that is returned from these functions are not aligned. This can cause problems if the block contains data that must be aligned to a specific boundry. If the block contains data that must be aligned, the block should be copied to an appropriately aligned area. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C dbm_store returns an error in the event that a disk block fills with inseparable data. .PP .C dbm_delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C dbm_firstkey and .C dbm_nextkey depends on a hashing function, not on anything interesting. .PP A .C dbm_store or .C dbm_delete during a pass through the keys by .C dbm_firstkey and .C dbm_nextkey may yield unexpected results. .SH AUTHOR .IR ndbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO dbm(3X). .\" index@\f4dbm_clearerr\f1 \- reset error condition on named database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_close\f1 \- close an open database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_delete\f1 \- delete a database key and associated contents@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_error\f1 \- error in reading or writing in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_fetch\f1 \- access a database entry under a key@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_firstkey\f1 \- get first key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_nextkey\f1 \- get next key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_open\f1 \- open a database for access@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_store\f1 \- store an entry under a key in a database@@@\f3ndbm(3X)\f1 .\" index@database subroutines (new multiple database version)@@@\f3ndbm(3X)\f1 .\" index@subroutines, database (new multiple database version)@@@\f3ndbm(3X)\f1 .\" .\" toc@\f3ndbm(3X)\f1:\0\0\f4dbm_open()\f1, \f4dbm_close()\f1, \f4dbm_fetch()\f1, \f4dbm_store()\f1, \f4dbm_delete()\f1, \n\f4dbm_firstkey()\f1, \f4dbm_nextkey()\f1, \f4dbm_error()\f1, \f4dbm_clearerr()\f1@@@database subroutines .\" toc@\f4dbm_open\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_close\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_fetch\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_store\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_delete\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_firstkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_nextkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_error\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_clearerr\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" .\" links@ndbm.3x dbm_open.3x .\" links@ndbm.3x dbm_close.3x .\" links@ndbm.3x dbm_fetch.3x .\" links@ndbm.3x dbm_store.3x .\" links@ndbm.3x dbm_delete.3x .\" links@ndbm.3x dbm_firstke.3x .\" links@ndbm.3x dbm_nextkey.3x .\" links@ndbm.3x dbm_error.3x .\" links@ndbm.3x dbm_clearer.3x .\" .\" fileset_database@ndbm.3x PROGRAMING-MAN .\" $Header: ndbm.3x,v 78.1 96/02/13 14:30:00 ssa Exp $ .TA n .TH ndbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr \- database subroutines .SH SYNOPSIS .C "#include " .PP .C "DBM *dbm_open(const char *file, int flags, mode_t mode);" .PP .C "void dbm_close(DBM *db);" .PP .C "datum dbm_fetch(DBM *db, datum key);" .PP .C "int dbm_store(DBM *db, datum key, datum content, int flags);" .PP .C "int dbm_delete(DBM *db, datum key);" .PP .C "datum dbm_firstkey(DBM *db);" .PP .C "datum dbm_nextkey(DBM *db);" .PP .C "int dbm_error(DBM *db);" .PP .C "int dbm_clearerr(DBM *db);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can access a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .IR dptr . Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbm_open . This will open and/or create the files .IC file .dir and .IC file .pag depending on the .I flags parameter (see .IR open (2)). .PP Once open, the data stored under a key is accessed by .C dbm_fetch and data is placed under a key by .CR dbm_store . The .I flags field can be either .C DBM_INSERT or .CR DBM_REPLACE . .C DBM_INSERT can only insert new entries into the database, and cannot change an existing entry having the same key. .C DBM_REPLACE replaces an existing entry if it has the same key. A key (and its associated contents) is deleted by .CR dbm_delete . A linear pass through all keys in a database can be made in (apparently) random order by use of .C dbm_firstkey and .CR dbm_nextkey . .C dbm_firstkey returns the first key in the database. .C dbm_nextkey returns the next key in the database, The following code can be used to traverse the database: .IP .C "for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))" .PP .C dbm_error returns non-zero when an error has occurred reading or writing the database. .C dbm_clearerr resets the error condition on the named database. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .I dptr. If .CR dbm_store is called with a .I flags value of .C DBM_INSERT and finds an existing entry with the same key, a value of .C 1 is returned. If a call to .CR dbm_store results in an internal block overflow, a value of -2 is returned. .SH WARNINGS The .I ndbm functions provided in this library should not be confused in any way with those of a general-purpose database management system. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful database functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The pointer to data that is returned from these functions are not aligned. This can cause problems if the block contains data that must be aligned to a specific boundry. If the block contains data that must be aligned, the block should be copied to an appropriately aligned area. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C dbm_store returns an error in the event that a disk block fills with inseparable data. .PP .C dbm_delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C dbm_firstkey and .C dbm_nextkey depends on a hashing function, not on anything interesting. .PP A .C dbm_store or .C dbm_delete during a pass through the keys by .C dbm_firstkey and .C dbm_nextkey may yield unexpected results. .SH AUTHOR .IR ndbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO dbm(3X). .\" index@\f4dbm_clearerr\f1 \- reset error condition on named database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_close\f1 \- close an open database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_delete\f1 \- delete a database key and associated contents@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_error\f1 \- error in reading or writing in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_fetch\f1 \- access a database entry under a key@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_firstkey\f1 \- get first key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_nextkey\f1 \- get next key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_open\f1 \- open a database for access@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_store\f1 \- store an entry under a key in a database@@@\f3ndbm(3X)\f1 .\" index@database subroutines (new multiple database version)@@@\f3ndbm(3X)\f1 .\" index@subroutines, database (new multiple database version)@@@\f3ndbm(3X)\f1 .\" .\" toc@\f3ndbm(3X)\f1:\0\0\f4dbm_open()\f1, \f4dbm_close()\f1, \f4dbm_fetch()\f1, \f4dbm_store()\f1, \f4dbm_delete()\f1, \n\f4dbm_firstkey()\f1, \f4dbm_nextkey()\f1, \f4dbm_error()\f1, \f4dbm_clearerr()\f1@@@database subroutines .\" toc@\f4dbm_open\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_close\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_fetch\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_store\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_delete\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_firstkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_nextkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_error\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_clearerr\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" .\" links@ndbm.3x dbm_open.3x .\" links@ndbm.3x dbm_close.3x .\" links@ndbm.3x dbm_fetch.3x .\" links@ndbm.3x dbm_store.3x .\" links@ndbm.3x dbm_delete.3x .\" links@ndbm.3x dbm_firstke.3x .\" links@ndbm.3x dbm_nextkey.3x .\" links@ndbm.3x dbm_error.3x .\" links@ndbm.3x dbm_clearer.3x .\" .\" fileset_database@ndbm.3x PROGRAMING-MAN .\" $Header: ndbm.3x,v 78.1 96/02/13 14:30:00 ssa Exp $ .TA n .TH ndbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr \- database subroutines .SH SYNOPSIS .C "#include " .PP .C "DBM *dbm_open(const char *file, int flags, mode_t mode);" .PP .C "void dbm_close(DBM *db);" .PP .C "datum dbm_fetch(DBM *db, datum key);" .PP .C "int dbm_store(DBM *db, datum key, datum content, int flags);" .PP .C "int dbm_delete(DBM *db, datum key);" .PP .C "datum dbm_firstkey(DBM *db);" .PP .C "datum dbm_nextkey(DBM *db);" .PP .C "int dbm_error(DBM *db);" .PP .C "int dbm_clearerr(DBM *db);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can access a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .IR dptr . Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbm_open . This will open and/or create the files .IC file .dir and .IC file .pag depending on the .I flags parameter (see .IR open (2)). .PP Once open, the data stored under a key is accessed by .C dbm_fetch and data is placed under a key by .CR dbm_store . The .I flags field can be either .C DBM_INSERT or .CR DBM_REPLACE . .C DBM_INSERT can only insert new entries into the database, and cannot change an existing entry having the same key. .C DBM_REPLACE replaces an existing entry if it has the same key. A key (and its associated contents) is deleted by .CR dbm_delete . A linear pass through all keys in a database can be made in (apparently) random order by use of .C dbm_firstkey and .CR dbm_nextkey . .C dbm_firstkey returns the first key in the database. .C dbm_nextkey returns the next key in the database, The following code can be used to traverse the database: .IP .C "for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))" .PP .C dbm_error returns non-zero when an error has occurred reading or writing the database. .C dbm_clearerr resets the error condition on the named database. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .I dptr. If .CR dbm_store is called with a .I flags value of .C DBM_INSERT and finds an existing entry with the same key, a value of .C 1 is returned. If a call to .CR dbm_store results in an internal block overflow, a value of -2 is returned. .SH WARNINGS The .I ndbm functions provided in this library should not be confused in any way with those of a general-purpose database management system. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful database functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The pointer to data that is returned from these functions are not aligned. This can cause problems if the block contains data that must be aligned to a specific boundry. If the block contains data that must be aligned, the block should be copied to an appropriately aligned area. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C dbm_store returns an error in the event that a disk block fills with inseparable data. .PP .C dbm_delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C dbm_firstkey and .C dbm_nextkey depends on a hashing function, not on anything interesting. .PP A .C dbm_store or .C dbm_delete during a pass through the keys by .C dbm_firstkey and .C dbm_nextkey may yield unexpected results. .SH AUTHOR .IR ndbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO dbm(3X). .\" index@\f4dbm_clearerr\f1 \- reset error condition on named database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_close\f1 \- close an open database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_delete\f1 \- delete a database key and associated contents@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_error\f1 \- error in reading or writing in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_fetch\f1 \- access a database entry under a key@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_firstkey\f1 \- get first key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_nextkey\f1 \- get next key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_open\f1 \- open a database for access@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_store\f1 \- store an entry under a key in a database@@@\f3ndbm(3X)\f1 .\" index@database subroutines (new multiple database version)@@@\f3ndbm(3X)\f1 .\" index@subroutines, database (new multiple database version)@@@\f3ndbm(3X)\f1 .\" .\" toc@\f3ndbm(3X)\f1:\0\0\f4dbm_open()\f1, \f4dbm_close()\f1, \f4dbm_fetch()\f1, \f4dbm_store()\f1, \f4dbm_delete()\f1, \n\f4dbm_firstkey()\f1, \f4dbm_nextkey()\f1, \f4dbm_error()\f1, \f4dbm_clearerr()\f1@@@database subroutines .\" toc@\f4dbm_open\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_close\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_fetch\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_store\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_delete\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_firstkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_nextkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_error\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_clearerr\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" .\" links@ndbm.3x dbm_open.3x .\" links@ndbm.3x dbm_close.3x .\" links@ndbm.3x dbm_fetch.3x .\" links@ndbm.3x dbm_store.3x .\" links@ndbm.3x dbm_delete.3x .\" links@ndbm.3x dbm_firstke.3x .\" links@ndbm.3x dbm_nextkey.3x .\" links@ndbm.3x dbm_error.3x .\" links@ndbm.3x dbm_clearer.3x .\" .\" fileset_database@ndbm.3x PROGRAMING-MAN .\" $Header: ndbm.3x,v 78.1 96/02/13 14:30:00 ssa Exp $ .TA n .TH ndbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr \- database subroutines .SH SYNOPSIS .C "#include " .PP .C "DBM *dbm_open(const char *file, int flags, mode_t mode);" .PP .C "void dbm_close(DBM *db);" .PP .C "datum dbm_fetch(DBM *db, datum key);" .PP .C "int dbm_store(DBM *db, datum key, datum content, int flags);" .PP .C "int dbm_delete(DBM *db, datum key);" .PP .C "datum dbm_firstkey(DBM *db);" .PP .C "datum dbm_nextkey(DBM *db);" .PP .C "int dbm_error(DBM *db);" .PP .C "int dbm_clearerr(DBM *db);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can access a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .IR dptr . Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbm_open . This will open and/or create the files .IC file .dir and .IC file .pag depending on the .I flags parameter (see .IR open (2)). .PP Once open, the data stored under a key is accessed by .C dbm_fetch and data is placed under a key by .CR dbm_store . The .I flags field can be either .C DBM_INSERT or .CR DBM_REPLACE . .C DBM_INSERT can only insert new entries into the database, and cannot change an existing entry having the same key. .C DBM_REPLACE replaces an existing entry if it has the same key. A key (and its associated contents) is deleted by .CR dbm_delete . A linear pass through all keys in a database can be made in (apparently) random order by use of .C dbm_firstkey and .CR dbm_nextkey . .C dbm_firstkey returns the first key in the database. .C dbm_nextkey returns the next key in the database, The following code can be used to traverse the database: .IP .C "for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))" .PP .C dbm_error returns non-zero when an error has occurred reading or writing the database. .C dbm_clearerr resets the error condition on the named database. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .I dptr. If .CR dbm_store is called with a .I flags value of .C DBM_INSERT and finds an existing entry with the same key, a value of .C 1 is returned. If a call to .CR dbm_store results in an internal block overflow, a value of -2 is returned. .SH WARNINGS The .I ndbm functions provided in this library should not be confused in any way with those of a general-purpose database management system. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful database functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The pointer to data that is returned from these functions are not aligned. This can cause problems if the block contains data that must be aligned to a specific boundry. If the block contains data that must be aligned, the block should be copied to an appropriately aligned area. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C dbm_store returns an error in the event that a disk block fills with inseparable data. .PP .C dbm_delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C dbm_firstkey and .C dbm_nextkey depends on a hashing function, not on anything interesting. .PP A .C dbm_store or .C dbm_delete during a pass through the keys by .C dbm_firstkey and .C dbm_nextkey may yield unexpected results. .SH AUTHOR .IR ndbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO dbm(3X). .\" index@\f4dbm_clearerr\f1 \- reset error condition on named database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_close\f1 \- close an open database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_delete\f1 \- delete a database key and associated contents@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_error\f1 \- error in reading or writing in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_fetch\f1 \- access a database entry under a key@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_firstkey\f1 \- get first key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_nextkey\f1 \- get next key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_open\f1 \- open a database for access@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_store\f1 \- store an entry under a key in a database@@@\f3ndbm(3X)\f1 .\" index@database subroutines (new multiple database version)@@@\f3ndbm(3X)\f1 .\" index@subroutines, database (new multiple database version)@@@\f3ndbm(3X)\f1 .\" .\" toc@\f3ndbm(3X)\f1:\0\0\f4dbm_open()\f1, \f4dbm_close()\f1, \f4dbm_fetch()\f1, \f4dbm_store()\f1, \f4dbm_delete()\f1, \n\f4dbm_firstkey()\f1, \f4dbm_nextkey()\f1, \f4dbm_error()\f1, \f4dbm_clearerr()\f1@@@database subroutines .\" toc@\f4dbm_open\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_close\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_fetch\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_store\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_delete\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_firstkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_nextkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_error\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_clearerr\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" .\" links@ndbm.3x dbm_open.3x .\" links@ndbm.3x dbm_close.3x .\" links@ndbm.3x dbm_fetch.3x .\" links@ndbm.3x dbm_store.3x .\" links@ndbm.3x dbm_delete.3x .\" links@ndbm.3x dbm_firstke.3x .\" links@ndbm.3x dbm_nextkey.3x .\" links@ndbm.3x dbm_error.3x .\" links@ndbm.3x dbm_clearer.3x .\" .\" fileset_database@ndbm.3x PROGRAMING-MAN .\" $Header: ndbm.3x,v 78.1 96/02/13 14:30:00 ssa Exp $ .TA n .TH ndbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr \- database subroutines .SH SYNOPSIS .C "#include " .PP .C "DBM *dbm_open(const char *file, int flags, mode_t mode);" .PP .C "void dbm_close(DBM *db);" .PP .C "datum dbm_fetch(DBM *db, datum key);" .PP .C "int dbm_store(DBM *db, datum key, datum content, int flags);" .PP .C "int dbm_delete(DBM *db, datum key);" .PP .C "datum dbm_firstkey(DBM *db);" .PP .C "datum dbm_nextkey(DBM *db);" .PP .C "int dbm_error(DBM *db);" .PP .C "int dbm_clearerr(DBM *db);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can access a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .IR dptr . Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbm_open . This will open and/or create the files .IC file .dir and .IC file .pag depending on the .I flags parameter (see .IR open (2)). .PP Once open, the data stored under a key is accessed by .C dbm_fetch and data is placed under a key by .CR dbm_store . The .I flags field can be either .C DBM_INSERT or .CR DBM_REPLACE . .C DBM_INSERT can only insert new entries into the database, and cannot change an existing entry having the same key. .C DBM_REPLACE replaces an existing entry if it has the same key. A key (and its associated contents) is deleted by .CR dbm_delete . A linear pass through all keys in a database can be made in (apparently) random order by use of .C dbm_firstkey and .CR dbm_nextkey . .C dbm_firstkey returns the first key in the database. .C dbm_nextkey returns the next key in the database, The following code can be used to traverse the database: .IP .C "for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))" .PP .C dbm_error returns non-zero when an error has occurred reading or writing the database. .C dbm_clearerr resets the error condition on the named database. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .I dptr. If .CR dbm_store is called with a .I flags value of .C DBM_INSERT and finds an existing entry with the same key, a value of .C 1 is returned. If a call to .CR dbm_store results in an internal block overflow, a value of -2 is returned. .SH WARNINGS The .I ndbm functions provided in this library should not be confused in any way with those of a general-purpose database management system. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful database functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The pointer to data that is returned from these functions are not aligned. This can cause problems if the block contains data that must be aligned to a specific boundry. If the block contains data that must be aligned, the block should be copied to an appropriately aligned area. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C dbm_store returns an error in the event that a disk block fills with inseparable data. .PP .C dbm_delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C dbm_firstkey and .C dbm_nextkey depends on a hashing function, not on anything interesting. .PP A .C dbm_store or .C dbm_delete during a pass through the keys by .C dbm_firstkey and .C dbm_nextkey may yield unexpected results. .SH AUTHOR .IR ndbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO dbm(3X). .\" index@\f4dbm_clearerr\f1 \- reset error condition on named database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_close\f1 \- close an open database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_delete\f1 \- delete a database key and associated contents@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_error\f1 \- error in reading or writing in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_fetch\f1 \- access a database entry under a key@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_firstkey\f1 \- get first key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_nextkey\f1 \- get next key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_open\f1 \- open a database for access@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_store\f1 \- store an entry under a key in a database@@@\f3ndbm(3X)\f1 .\" index@database subroutines (new multiple database version)@@@\f3ndbm(3X)\f1 .\" index@subroutines, database (new multiple database version)@@@\f3ndbm(3X)\f1 .\" .\" toc@\f3ndbm(3X)\f1:\0\0\f4dbm_open()\f1, \f4dbm_close()\f1, \f4dbm_fetch()\f1, \f4dbm_store()\f1, \f4dbm_delete()\f1, \n\f4dbm_firstkey()\f1, \f4dbm_nextkey()\f1, \f4dbm_error()\f1, \f4dbm_clearerr()\f1@@@database subroutines .\" toc@\f4dbm_open\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_close\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_fetch\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_store\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_delete\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_firstkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_nextkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_error\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_clearerr\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" .\" links@ndbm.3x dbm_open.3x .\" links@ndbm.3x dbm_close.3x .\" links@ndbm.3x dbm_fetch.3x .\" links@ndbm.3x dbm_store.3x .\" links@ndbm.3x dbm_delete.3x .\" links@ndbm.3x dbm_firstke.3x .\" links@ndbm.3x dbm_nextkey.3x .\" links@ndbm.3x dbm_error.3x .\" links@ndbm.3x dbm_clearer.3x .\" .\" fileset_database@ndbm.3x PROGRAMING-MAN .\" $Header: ndbm.3x,v 78.1 96/02/13 14:30:00 ssa Exp $ .TA n .TH ndbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr \- database subroutines .SH SYNOPSIS .C "#include " .PP .C "DBM *dbm_open(const char *file, int flags, mode_t mode);" .PP .C "void dbm_close(DBM *db);" .PP .C "datum dbm_fetch(DBM *db, datum key);" .PP .C "int dbm_store(DBM *db, datum key, datum content, int flags);" .PP .C "int dbm_delete(DBM *db, datum key);" .PP .C "datum dbm_firstkey(DBM *db);" .PP .C "datum dbm_nextkey(DBM *db);" .PP .C "int dbm_error(DBM *db);" .PP .C "int dbm_clearerr(DBM *db);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can access a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .IR dptr . Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbm_open . This will open and/or create the files .IC file .dir and .IC file .pag depending on the .I flags parameter (see .IR open (2)). .PP Once open, the data stored under a key is accessed by .C dbm_fetch and data is placed under a key by .CR dbm_store . The .I flags field can be either .C DBM_INSERT or .CR DBM_REPLACE . .C DBM_INSERT can only insert new entries into the database, and cannot change an existing entry having the same key. .C DBM_REPLACE replaces an existing entry if it has the same key. A key (and its associated contents) is deleted by .CR dbm_delete . A linear pass through all keys in a database can be made in (apparently) random order by use of .C dbm_firstkey and .CR dbm_nextkey . .C dbm_firstkey returns the first key in the database. .C dbm_nextkey returns the next key in the database, The following code can be used to traverse the database: .IP .C "for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))" .PP .C dbm_error returns non-zero when an error has occurred reading or writing the database. .C dbm_clearerr resets the error condition on the named database. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .I dptr. If .CR dbm_store is called with a .I flags value of .C DBM_INSERT and finds an existing entry with the same key, a value of .C 1 is returned. If a call to .CR dbm_store results in an internal block overflow, a value of -2 is returned. .SH WARNINGS The .I ndbm functions provided in this library should not be confused in any way with those of a general-purpose database management system. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful database functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The pointer to data that is returned from these functions are not aligned. This can cause problems if the block contains data that must be aligned to a specific boundry. If the block contains data that must be aligned, the block should be copied to an appropriately aligned area. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C dbm_store returns an error in the event that a disk block fills with inseparable data. .PP .C dbm_delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C dbm_firstkey and .C dbm_nextkey depends on a hashing function, not on anything interesting. .PP A .C dbm_store or .C dbm_delete during a pass through the keys by .C dbm_firstkey and .C dbm_nextkey may yield unexpected results. .SH AUTHOR .IR ndbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO dbm(3X). .\" index@\f4dbm_clearerr\f1 \- reset error condition on named database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_close\f1 \- close an open database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_delete\f1 \- delete a database key and associated contents@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_error\f1 \- error in reading or writing in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_fetch\f1 \- access a database entry under a key@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_firstkey\f1 \- get first key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_nextkey\f1 \- get next key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_open\f1 \- open a database for access@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_store\f1 \- store an entry under a key in a database@@@\f3ndbm(3X)\f1 .\" index@database subroutines (new multiple database version)@@@\f3ndbm(3X)\f1 .\" index@subroutines, database (new multiple database version)@@@\f3ndbm(3X)\f1 .\" .\" toc@\f3ndbm(3X)\f1:\0\0\f4dbm_open()\f1, \f4dbm_close()\f1, \f4dbm_fetch()\f1, \f4dbm_store()\f1, \f4dbm_delete()\f1, \n\f4dbm_firstkey()\f1, \f4dbm_nextkey()\f1, \f4dbm_error()\f1, \f4dbm_clearerr()\f1@@@database subroutines .\" toc@\f4dbm_open\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_close\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_fetch\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_store\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_delete\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_firstkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_nextkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_error\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_clearerr\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" .\" links@ndbm.3x dbm_open.3x .\" links@ndbm.3x dbm_close.3x .\" links@ndbm.3x dbm_fetch.3x .\" links@ndbm.3x dbm_store.3x .\" links@ndbm.3x dbm_delete.3x .\" links@ndbm.3x dbm_firstke.3x .\" links@ndbm.3x dbm_nextkey.3x .\" links@ndbm.3x dbm_error.3x .\" links@ndbm.3x dbm_clearer.3x .\" .\" fileset_database@ndbm.3x PROGRAMING-MAN .\" $Header: ndbm.3x,v 78.1 96/02/13 14:30:00 ssa Exp $ .TA n .TH ndbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr \- database subroutines .SH SYNOPSIS .C "#include " .PP .C "DBM *dbm_open(const char *file, int flags, mode_t mode);" .PP .C "void dbm_close(DBM *db);" .PP .C "datum dbm_fetch(DBM *db, datum key);" .PP .C "int dbm_store(DBM *db, datum key, datum content, int flags);" .PP .C "int dbm_delete(DBM *db, datum key);" .PP .C "datum dbm_firstkey(DBM *db);" .PP .C "datum dbm_nextkey(DBM *db);" .PP .C "int dbm_error(DBM *db);" .PP .C "int dbm_clearerr(DBM *db);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can access a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .IR dptr . Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbm_open . This will open and/or create the files .IC file .dir and .IC file .pag depending on the .I flags parameter (see .IR open (2)). .PP Once open, the data stored under a key is accessed by .C dbm_fetch and data is placed under a key by .CR dbm_store . The .I flags field can be either .C DBM_INSERT or .CR DBM_REPLACE . .C DBM_INSERT can only insert new entries into the database, and cannot change an existing entry having the same key. .C DBM_REPLACE replaces an existing entry if it has the same key. A key (and its associated contents) is deleted by .CR dbm_delete . A linear pass through all keys in a database can be made in (apparently) random order by use of .C dbm_firstkey and .CR dbm_nextkey . .C dbm_firstkey returns the first key in the database. .C dbm_nextkey returns the next key in the database, The following code can be used to traverse the database: .IP .C "for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))" .PP .C dbm_error returns non-zero when an error has occurred reading or writing the database. .C dbm_clearerr resets the error condition on the named database. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .I dptr. If .CR dbm_store is called with a .I flags value of .C DBM_INSERT and finds an existing entry with the same key, a value of .C 1 is returned. If a call to .CR dbm_store results in an internal block overflow, a value of -2 is returned. .SH WARNINGS The .I ndbm functions provided in this library should not be confused in any way with those of a general-purpose database management system. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful database functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The pointer to data that is returned from these functions are not aligned. This can cause problems if the block contains data that must be aligned to a specific boundry. If the block contains data that must be aligned, the block should be copied to an appropriately aligned area. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C dbm_store returns an error in the event that a disk block fills with inseparable data. .PP .C dbm_delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C dbm_firstkey and .C dbm_nextkey depends on a hashing function, not on anything interesting. .PP A .C dbm_store or .C dbm_delete during a pass through the keys by .C dbm_firstkey and .C dbm_nextkey may yield unexpected results. .SH AUTHOR .IR ndbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO dbm(3X). .\" index@\f4dbm_clearerr\f1 \- reset error condition on named database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_close\f1 \- close an open database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_delete\f1 \- delete a database key and associated contents@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_error\f1 \- error in reading or writing in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_fetch\f1 \- access a database entry under a key@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_firstkey\f1 \- get first key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_nextkey\f1 \- get next key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_open\f1 \- open a database for access@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_store\f1 \- store an entry under a key in a database@@@\f3ndbm(3X)\f1 .\" index@database subroutines (new multiple database version)@@@\f3ndbm(3X)\f1 .\" index@subroutines, database (new multiple database version)@@@\f3ndbm(3X)\f1 .\" .\" toc@\f3ndbm(3X)\f1:\0\0\f4dbm_open()\f1, \f4dbm_close()\f1, \f4dbm_fetch()\f1, \f4dbm_store()\f1, \f4dbm_delete()\f1, \n\f4dbm_firstkey()\f1, \f4dbm_nextkey()\f1, \f4dbm_error()\f1, \f4dbm_clearerr()\f1@@@database subroutines .\" toc@\f4dbm_open\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_close\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_fetch\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_store\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_delete\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_firstkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_nextkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_error\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_clearerr\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" .\" links@ndbm.3x dbm_open.3x .\" links@ndbm.3x dbm_close.3x .\" links@ndbm.3x dbm_fetch.3x .\" links@ndbm.3x dbm_store.3x .\" links@ndbm.3x dbm_delete.3x .\" links@ndbm.3x dbm_firstke.3x .\" links@ndbm.3x dbm_nextkey.3x .\" links@ndbm.3x dbm_error.3x .\" links@ndbm.3x dbm_clearer.3x .\" .\" fileset_database@ndbm.3x PROGRAMING-MAN .\" $Header: ndbm.3x,v 78.1 96/02/13 14:30:00 ssa Exp $ .TA n .TH ndbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr \- database subroutines .SH SYNOPSIS .C "#include " .PP .C "DBM *dbm_open(const char *file, int flags, mode_t mode);" .PP .C "void dbm_close(DBM *db);" .PP .C "datum dbm_fetch(DBM *db, datum key);" .PP .C "int dbm_store(DBM *db, datum key, datum content, int flags);" .PP .C "int dbm_delete(DBM *db, datum key);" .PP .C "datum dbm_firstkey(DBM *db);" .PP .C "datum dbm_nextkey(DBM *db);" .PP .C "int dbm_error(DBM *db);" .PP .C "int dbm_clearerr(DBM *db);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can access a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .IR dptr . Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbm_open . This will open and/or create the files .IC file .dir and .IC file .pag depending on the .I flags parameter (see .IR open (2)). .PP Once open, the data stored under a key is accessed by .C dbm_fetch and data is placed under a key by .CR dbm_store . The .I flags field can be either .C DBM_INSERT or .CR DBM_REPLACE . .C DBM_INSERT can only insert new entries into the database, and cannot change an existing entry having the same key. .C DBM_REPLACE replaces an existing entry if it has the same key. A key (and its associated contents) is deleted by .CR dbm_delete . A linear pass through all keys in a database can be made in (apparently) random order by use of .C dbm_firstkey and .CR dbm_nextkey . .C dbm_firstkey returns the first key in the database. .C dbm_nextkey returns the next key in the database, The following code can be used to traverse the database: .IP .C "for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))" .PP .C dbm_error returns non-zero when an error has occurred reading or writing the database. .C dbm_clearerr resets the error condition on the named database. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .I dptr. If .CR dbm_store is called with a .I flags value of .C DBM_INSERT and finds an existing entry with the same key, a value of .C 1 is returned. If a call to .CR dbm_store results in an internal block overflow, a value of -2 is returned. .SH WARNINGS The .I ndbm functions provided in this library should not be confused in any way with those of a general-purpose database management system. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful database functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The pointer to data that is returned from these functions are not aligned. This can cause problems if the block contains data that must be aligned to a specific boundry. If the block contains data that must be aligned, the block should be copied to an appropriately aligned area. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C dbm_store returns an error in the event that a disk block fills with inseparable data. .PP .C dbm_delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C dbm_firstkey and .C dbm_nextkey depends on a hashing function, not on anything interesting. .PP A .C dbm_store or .C dbm_delete during a pass through the keys by .C dbm_firstkey and .C dbm_nextkey may yield unexpected results. .SH AUTHOR .IR ndbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO dbm(3X). .\" index@\f4dbm_clearerr\f1 \- reset error condition on named database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_close\f1 \- close an open database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_delete\f1 \- delete a database key and associated contents@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_error\f1 \- error in reading or writing in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_fetch\f1 \- access a database entry under a key@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_firstkey\f1 \- get first key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_nextkey\f1 \- get next key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_open\f1 \- open a database for access@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_store\f1 \- store an entry under a key in a database@@@\f3ndbm(3X)\f1 .\" index@database subroutines (new multiple database version)@@@\f3ndbm(3X)\f1 .\" index@subroutines, database (new multiple database version)@@@\f3ndbm(3X)\f1 .\" .\" toc@\f3ndbm(3X)\f1:\0\0\f4dbm_open()\f1, \f4dbm_close()\f1, \f4dbm_fetch()\f1, \f4dbm_store()\f1, \f4dbm_delete()\f1, \n\f4dbm_firstkey()\f1, \f4dbm_nextkey()\f1, \f4dbm_error()\f1, \f4dbm_clearerr()\f1@@@database subroutines .\" toc@\f4dbm_open\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_close\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_fetch\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_store\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_delete\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_firstkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_nextkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_error\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_clearerr\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" .\" links@ndbm.3x dbm_open.3x .\" links@ndbm.3x dbm_close.3x .\" links@ndbm.3x dbm_fetch.3x .\" links@ndbm.3x dbm_store.3x .\" links@ndbm.3x dbm_delete.3x .\" links@ndbm.3x dbm_firstke.3x .\" links@ndbm.3x dbm_nextkey.3x .\" links@ndbm.3x dbm_error.3x .\" links@ndbm.3x dbm_clearer.3x .\" .\" fileset_database@ndbm.3x PROGRAMING-MAN .\" $Header: dbm.3x,v 76.1 95/07/05 17:27:37 ssa Exp $ .TA d .TH dbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbminit, fetch, store, delete, firstkey, nextkey, dbmclose \- database subroutines .SH SYNOPSIS .C "#include " .P .C "int dbminit(const char *file);" .P .C "datum fetch(datum key);" .P .C "int store(datum key, datum content);" .P .C "int delete(datum key);" .P .C "datum firstkey(void);" .P .C "datum nextkey(datum key);" .P .C "int dbmclose(void);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can locate a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .I dptr. Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbminit . At the time of this call, the files .IC file .dir and .IC file .pag must exist. (An empty database is created by creating zero-length .C .dir and .C .pag files.) .PP Once open, data stored under a key is accessed by .IC fetch , and data is placed under a key by .IC store . Storing data on an existing key replaces the existing data. A key (and its associated contents) is deleted by .CR delete . A linear pass through all keys in a database can be made, in (apparently) random order by using .C firstkey and .CR nextkey . .C firstkey returns the first key in the database. With any key, .C nextkey returns the next key in the database. The following code can be used to traverse the database: .IP .C "for (key = firstkey(); key.dptr != NULL; key = nextkey(key))" .PP A database can be closed by calling .C dbmclose. A currently open database must be closed before opening a new one. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .IR dptr . .SH WARNINGS The .I dbm functions provided in this library should not be confused in any way with those of a general-purpose database management system such as .SM ALLBASE/HP-UX SQL. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful data base functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C store returns an error if a disk block fills with inseparable data. .PP .C delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C firstkey and .C nextkey depends on a hashing function, not on anything interesting. .PP A .C store or .C delete during a pass through the keys by .C firstkey and .C nextkey may yield unexpected results. .SH AUTHOR .IR dbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO ndbm(3X). .\" index@\f4dbminit()\fP \- open a single database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4fetch()\fP \- access data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4store()\fP \- store data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4delete()\fP \- delete key and data under it (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4firstkey()\fP \- get first key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4nextkey()\fP \- get next key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4dbmclose()\fP \- close currently open database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@database subroutines (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" index@subroutines, database (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" .\" toc@\f3dbm(3X)\f1:\0\0\f4dbminit()\fP, \f4fetch()\fP, \f4store()\fP, \f4delete()\fP, \f4firstkey()\fP,\n\f4nextkey()\fP, \f4dbmclose()\fP@@@database subroutines .\" toc@\f4dbminit()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4fetch()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4store()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4delete()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4firstkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4nextkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4dbmclose()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" .\" links@dbm.3x dbminit.3x .\" links@dbm.3x fetch.3x .\" links@dbm.3x store.3x .\" links@dbm.3x delete.3x .\" links@dbm.3x firstkey.3x .\" links@dbm.3x nextkey.3x .\" links@dbm.3x dbmclose.3x .\" .\" fileset_database@dbm.3x PROGRAMING-MAN .\" $Header: dbm.3x,v 76.1 95/07/05 17:27:37 ssa Exp $ .TA d .TH dbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbminit, fetch, store, delete, firstkey, nextkey, dbmclose \- database subroutines .SH SYNOPSIS .C "#include " .P .C "int dbminit(const char *file);" .P .C "datum fetch(datum key);" .P .C "int store(datum key, datum content);" .P .C "int delete(datum key);" .P .C "datum firstkey(void);" .P .C "datum nextkey(datum key);" .P .C "int dbmclose(void);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can locate a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .I dptr. Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbminit . At the time of this call, the files .IC file .dir and .IC file .pag must exist. (An empty database is created by creating zero-length .C .dir and .C .pag files.) .PP Once open, data stored under a key is accessed by .IC fetch , and data is placed under a key by .IC store . Storing data on an existing key replaces the existing data. A key (and its associated contents) is deleted by .CR delete . A linear pass through all keys in a database can be made, in (apparently) random order by using .C firstkey and .CR nextkey . .C firstkey returns the first key in the database. With any key, .C nextkey returns the next key in the database. The following code can be used to traverse the database: .IP .C "for (key = firstkey(); key.dptr != NULL; key = nextkey(key))" .PP A database can be closed by calling .C dbmclose. A currently open database must be closed before opening a new one. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .IR dptr . .SH WARNINGS The .I dbm functions provided in this library should not be confused in any way with those of a general-purpose database management system such as .SM ALLBASE/HP-UX SQL. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful data base functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C store returns an error if a disk block fills with inseparable data. .PP .C delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C firstkey and .C nextkey depends on a hashing function, not on anything interesting. .PP A .C store or .C delete during a pass through the keys by .C firstkey and .C nextkey may yield unexpected results. .SH AUTHOR .IR dbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO ndbm(3X). .\" index@\f4dbminit()\fP \- open a single database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4fetch()\fP \- access data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4store()\fP \- store data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4delete()\fP \- delete key and data under it (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4firstkey()\fP \- get first key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4nextkey()\fP \- get next key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4dbmclose()\fP \- close currently open database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@database subroutines (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" index@subroutines, database (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" .\" toc@\f3dbm(3X)\f1:\0\0\f4dbminit()\fP, \f4fetch()\fP, \f4store()\fP, \f4delete()\fP, \f4firstkey()\fP,\n\f4nextkey()\fP, \f4dbmclose()\fP@@@database subroutines .\" toc@\f4dbminit()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4fetch()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4store()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4delete()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4firstkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4nextkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4dbmclose()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" .\" links@dbm.3x dbminit.3x .\" links@dbm.3x fetch.3x .\" links@dbm.3x store.3x .\" links@dbm.3x delete.3x .\" links@dbm.3x firstkey.3x .\" links@dbm.3x nextkey.3x .\" links@dbm.3x dbmclose.3x .\" .\" fileset_database@dbm.3x PROGRAMING-MAN .\" $Header: dcnodes.3x,v 74.2 95/05/10 21:04:24 ssa Exp $ .TA d .TH dcnodes 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" =========== .SH NAME dcnodes(), dcnodes_status(), dcnodes_status_string(), dcnodes_error_string(), dcnodes_server_ipaddr(), enddcnodes() \- report on diskless cluster nodes .\" =========== .SH SYNOPSIS .C "#include " .PP .C "int dcnodes (" .nf .PD 0 .IP .C "const int mode," .C "struct dcnode **dcnode" .PP .C ");" .PD .PP .C "int dcnodes_status (" .nf .PD 0 .IP .C "const int mode," .C "struct dcnode *dcnode," .C "const int num_dcnodes," .C "const time_t timeout" .PP .C ");" .PD .PP .C "int dcnodes_status_string ( .nf .PD 0 .IP .C "const int mode," .C "const int statval" .PP .C ");" .PD .PP .C "int dcnodes_error_string (const int retval);" .PP .C "int dcnodes_server_ipaddr (" .nf .PD 0 .IP .C "char *ipaddr," .C "const int len" .PP .C ");" .PD .PP .C "unsigned long dcnodes_mtime (void);" .PP .C "void enddcnodes (void);" .\" =========== .SS Remarks These functions reside in libdc.a, and are linked using the .C -ldc option to the .C ld or .C cc command. .\" =========== .SH DESCRIPTION These functions help a program get static (configuration) and dynamic (status) information about diskless cluster nodes (server, and clients). The .C dcnodes() and .C dcnodes_status() functions return information about all nodes in a cluster (including the cluster server), when run on any node in the cluster. The .C dcnodes_server_ipaddr() function returns the internet address of a cluster client's server system. .PP The .C dcnode structure is defined in .RC < dcnodes.h > and includes at least the following members. Each string is null-terminated. .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. char@dcn_name[];@/* node name; see below@*/ char@dcn_ipaddr[];@/* IP address, dot form@*/ char@dcn_hwaddr[];@/* hardware address, hex form@*/ char@dcn_netmask[];@/* net/subnet mask, dot form@*/ char@dcn_route[];@/* default route, dot form@*/ char@dcn_shroot[];@/* OS shared root description@*/ int@dcn_status;@/* system status; see below@*/ .TE .ft P .RE .PP The file also defines the following constants and data types: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. DCNODES_SHORT@/* mode parameter to dcnodes(); see below@*/ DCNODES_LONG DCNODES_LONGER DCNODES_ALL DCNODES_TYPE .TE .ft P .RE .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. DCNODES_STATUS@/* mode parameter to dcnodes_status()@*/ DCNODES_STATUS_DETAILS .TE .ft P .RE .PP These lengths do not include the null terminator: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. DCN_NAME_LEN@/* maximum dcnode name length@*/ DCN_IPADDR_LEN@/* maximum IP address length@*/ DCN_HWADDR_LEN@/* maximum HW address length@*/ DCN_NETMASK_LEN@/* maximum net/subnet mask length@*/ DCN_ROUTE_LEN@/* maximum default route length@*/ DCN_SHROOT_LEN@/* maximum OS shared root length@*/ DCN_STATUS_LEN@/* size of status value (int)@*/ DCN_VALUE_UNKNOWN@/* field value cannot be determined@*/ DCN_TYPE_STANDALONE@/* results of DCNODES_TYPE@*/ DCN_TYPE_SERVER DCN_TYPE_CLIENT DCN_ERR_MEMORY@/* error return codes; see below@*/ DCN_ERR_IPADDR DCN_ERR_RCMD DCN_ERR_FDOPEN DCN_ERR_STARTUP DCN_ERR_VERSION DCN_ERR_EXEC DCN_ERR_READ DCN_ERR_SOCKET DCN_ERR_CONNECT DCN_STATUS_UNKNOWN@/* status values; see below@*/ DCN_STATUS_STANDALONE DCN_STATUS_SERVER DCN_STATUS_ACTIVE DCN_STATUS_INACTIVE DCN_STATUS_NO_IP_ADDR DCN_STATUS_NO_DATA DCN_IS_UP(status)@/* macros for checking status value@*/ DCN_IS_SERVER(status) DCN_IS_CLIENT(status) DCN_IS_LOCAL_ROOT(status) .TE .PP .C "typedef struct dcnode *dcnp_t;" .ifn \f3 .ift \f4 .TS tab(@); l l. #define DCN_NULLP@((dcnp_t) 0) #define DCN_NULLPP@((dcnp_t *) 0) #define DCN_SIZE@(sizeof (struct dcnode)) #define DCN_PROG_NULLP@((void (*)()) 0) .TE .ft P .RE .PP If invoked on a cluster client (remote-root) node, .C dcnodes() and .C dcnodes_status() contact the node's root server system to obtain information about all of the cluster's nodes, except as noted below. This requires .C rcmd() access from the client to the server by the effective user .SM ID of the calling process (see .IR rcmd (3N) and .IR setuid (2)) to execute the .CR dcnodes command. .PP The functions have the following purposes: .PP .TP 15 .C dcnodes() This function modifies the .I dcnode pointer to point to an array of .I dcnode structures, each containing information for one node, and returns the number of nodes in the list. The cluster server is always the first system in the list. The .I mode parameter determines which operation is performed: .RS 5 .TP 15 .C DCNODES_SHORT Return a count, and a list, of cluster node names; other structure fields are undefined (except .CR dcn_ipaddr , which is set to null for convenience in calling .CR dcnodes_status() ). The cluster server's .C dcn_name value is its domain-expanded .C hostname value (see .IR gethostname (2)), that is, the result of looking up the system's .C hostname in the hosts database using .C gethostbyname() (see .IR gethostent (3N)). Cluster clients' .C dcn_name values are their names as listed in the cluster client list on the server (see .SM FILES below), normally including domain parts, which should but might not match each client's .C hostname and .C uname.nodename values. .IP With .CR DCNODES_SHORT , the .I dcnode parameter can be a null pointer, which causes .C dcnodes not to allocate space for, and build the list of, cluster node names. In this case it only returns a count of cluster nodes. .IP An unrecognized .I mode value is treated as .CR DCNODES_SHORT . .TP .C DCNODES_LONG Fill in all structure fields except .C dcn_shroot and .CR dcn_status . .C dcn_shroot is undefined. .C dcn_status is set to one of the following as appropriate: .RS .TP 25 .C DCN_STATUS_UNKNOWN for cluster clients (default value) .PD 0 .TP .C DCN_STATUS_SERVER for cluster server systems .TP .C DCN_STATUS_STANDALONE for standalone systems .PD .RE .IP The .C dcn_status field can be filled in by calling .C dcnodes_status() as described below. If .C dcnodes() cannot determine the value for any field, that field is set to the value of the .C DCN_VALUE_UNKNOWN macro. .IP If a standalone or cluster server system has multiple .SM LAN interface cards, there is an entry for each card in the returned array. Each of those entries contains the same values for .C dcn_route and .CR dcn_status , but different values for .C dcn_ipaddr and .CR dcn_hwaddr . The values for .C dcn_name and .C dcn_netmask might differ, reflecting each of the server's .SM LAN interface cards. If a .SM LAN interface card is down, its .C dcn_ipaddr value is .RC `` "(card down)" ''. .IP If the system on which .C dcnodes() is invoked is standalone and has no .SM LAN cards, a single entry is returned with .C dcn_name set to the host's domain-expanded hostname value, and .CR dcn_ipaddr , .CR dcn_hwaddr , and .C dcn_netmask set to the value of .CR DCN_VALUE_UNKNOWN . .TP .C DCNODES_LONGER Same as .C DCNODES_LONG except also fill in the .C dcn_shroot field. This can take significant extra time. The cluster server's .C dcn_shroot value is always ``/''; client values are truncated if necessary, and always null-terminated. If any client's .SM OS shared root description is null, its path appears instead. .TP .C DCNODES_ALL Fill in the array just as for .CR DCNODES_LONGER , and then call .C dcnodes_status() with a .I mode of .C DCNODES_STATUS and a .I timeout value of 10 seconds to also fill in .C dcn_status fields (for all clients) before returning. This saves the caller from calling .C dcnodes_status() separately. .TP .C DCNODES_TYPE Ignore the .I dcnode parameter and just return .C DCN_TYPE_SERVER if the system is a cluster server, .C DCN_TYPE_CLIENT if it is a cluster client, or .C DCN_TYPE_STANDALONE if it is a standalone system (it has a local root and no remote-root clients are configured). When .C dcnodes() is called on a remote-root client with this .I mode it does not contact the cluster server. .RE .IP "" 15 The returned array exists in static space (malloc'd memory \(em see .IR malloc (3C)). This memory is overwritten by the next call, so previously returned pointers become invalid after the next call. .TP .C dcnodes_status() Using an array of .C dcnode structures containing one or more elements, .C dcnodes_status() obtains information on the status of each node from the dcnodes status daemon ( .C dcnodesd ). Information from the daemon is matched with a .C dcnode array entry by .C dcnodes_status() uses the .C dcn_ipaddr field in each .C dcnode structure if it is non-null, and not equal to the value .CR DCN_VALUE_UNKNOWN ; otherwise, it uses the .C dcn_name field in the .C dcnodes structure. .C dcnodes_status() then fills in the .C dcn_status field for each node's element. See .RB `` "Status Fields" '' below for a description of possible field values. .IP Pass the function a mode .RI ( mode ) value which is either .C DCNODES_STATUS or .CR DCNODES_STATUS_DETAILS , a count .RI ( num_dcnodes ) of the number of nodes to process, and a pointer .RI ( dcnode ) to the first element of the array. If any node's .SM IP address is not specified, it converts the node's name to an .SM IP address using .C gethostbyname() (see .IR gethostent (3N)). .IP Also pass the function a timeout value in seconds. This value is the number of seconds that must elapse between the time that a client sends a keepalive packet to the server and the time when the client is inactive. By default, clients send keepalive packets every five seconds. A 10 second timeout, then, means that any timestamp older than 10 seconds is considered invalid and the client is marked as inactive. .TP .C dcnodes_status_string() This function takes a .I mode value .RC ( DCNODES_SHORT or .CR DCNODES_LONG ) and a client status value (the .C dcn_status field, any of .CR DCN_STATUS_ *), and returns a constant or static string equivalent (changed or overwritten by the next call to this function or to .CR catgets() ), in either short or long form. If the status value is .C DCN_STATUS_UNKNOWN or any unrecognized value, the returned string is the value of .CR DCN_VALUE_UNKNOWN . .TP .C dcnodes_error_string() This function takes a return value from .C dcnodes() or .CR dcnodes_status() and returns a constant or static string (changed or overwritten by the next call to this function or to .CR catgets() ), that describes the error condition, suitable for use in an error message. The string begins with an uppercase letter but lacks a trailing period. If the error condition has an .C errno value associated (see .SM "RETURN VALUE" below), the global .C errno value is interpreted as part of the returned error message. If the value passed to .C dcnodes_error_string() is unrecognized, it returns an appropriate message. .TP .C dcnodes_server_ipaddr() This function looks up the internet address part of the mount point for .RC `` / '' and copies it to the caller's .C ipaddr buffer. The string is always null-terminated and truncated if necessary to fit. The size of the buffer and the .C len value are normally .C DCN_IPADDR_LEN + 1. .IP This function should only be called on a cluster client, that is, a remote-root system whose .RC `` / '' directory is \s-1NFS\s0-mounted. The server's .SM IP address is derived from the mount point of .RC `` / '' in the system mount table. This function assumes the server .SM ID is an .SM IP address, not a name. .TP .C dcnodes_mtime() cwThis function allows an application to avoid calling .C dcnodes() again if it's unnecessary to do so because the data hasn't changed. .C dcnodes_mtime() returns the latest mtime stamp on any file used by .C dcnodes() to return its data. If none of the files exists, returns 0. .IP This function can only be called on a cluster server. .TP .C enddcnodes() Frees any malloc'd memory previously allocated by .CR dcnodes() . (Do not call .C free() on a .I dcnode pointer previously passed to .CR dcnodes() , because .C dcnodes() does this itself.) Memory is only allocated by calls to .C dcnodes() with .CR DCNODES_LONG , .CR DCNODES_LONGER , .CR DCNODES_ALL , or .C DCNODES_SHORT with a non-null .C dcnode pointer. .PP Note that a system with a local root directory (root volume) is considered to be standalone or a cluster server as appropriate, not a cluster client, even if most of its files are \s-1NFS\s0-mounted from other systems. .\" ----------- .SS Status Fields The .C dcn_status field for each node is set to one of the following values (defined in .CR dcnodes.h ) by .C dcnodes_status() when it is called using a .I mode parameter of .CR DCNODES_STATUS : .TP 22 .C DCN_STATUS_UNKNOWN Default value from .CR dcnodes() ; also used if the node name and .SM IP address passed to .C dcnodes_status() are both null or equal to the value of .CR DCN_VALUE_UNKNOWN . .TP .C DCN_STATUS_STANDALONE System on which .C dcnodes_status() was invoked is up with a local root volume and has no remote-root clients configured. .TP .C DCN_STATUS_SERVER Cluster (root) server, which is necessarily ``up''. .TP .C DCN_STATUS_ACTIVE Node is up as a remote-root client of the local cluster. It allows .C rcmd() from the cluster (root) server and identifies that system as its root server. Note that all nodes in a cluster are normally configured to allow .C rcmd() access, at least to privileged users, between the cluster server and clients. .TP .C DCN_STATUS_INACTIVE Node has an unknown name (cannot look up internet address), does not respond to or does not allow .C rcmd() from the cluster (root) server, is up standalone (local-rooted), or is booted on another root server. A node is marked inactive if anything goes wrong, including timeout, while trying to check that is it active. .PP If the .I mode parameter is .CR DCNODES_STATUS_DETAILS , instead of marking a client with .C DCN_STATUS_INACTIVE its status value is one of the following: .TP 22 .C DCN_STATUS_NO_IP_ADDR A .C dcn_name value was provided, .C dcn_ipaddr was not, and the given client name is unknown to the hosts database (cannot be mapped to an .SM IP address). .TP .C DCN_STATUS_NO_DATA The .C dcnodesd daemon could not be contacted, or had no data for the specified client. .\" =========== .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG specifies the language used to return messages from .C dcnodes_status_string() and .CR dcnodes_error_string() . .PP If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, the string functions behave as if all internationalization variables are set to ``C''. See .IR environ (5). .\" =========== .SH RETURN VALUE Upon successful completion, .C dcnodes() and .C dcnodes_status() return the number of array elements in the list. This value is 1 or greater, except if .C dcnodes_status() is called with .I num_dcnodes less than 1, it returns 0, and if it is called on a cluster client with more than about 10Kb worth of node names, it returns the number of array elements for which status was set (see .SM WARNINGS below). .PP If .C dcnodes() is called with .CR DCNODES_SHORT , the number of array elements is the number of cluster nodes; with .CR DCNODES_LONG , .CR DCNODES_LONGER , or .CR DCNODES_ALL , there are more elements than dcnodes if the server has multiple .SM LAN cards; with .CR DCNODES_TYPE , the return value is .C DCN_TYPE_STANDALONE (standalone system), .C DCN_TYPE_SERVER (cluster server), or .C DCN_TYPE_CLIENT (cluster client). .PP In case of error, .C dcnodes() and .C dcnodes_status() return a negative value, and do not alter the .I dcnode parameter. .TP 20 .C DCN_ERR_MEMORY Cannot allocate memory to hold the returned array (for .CR dcnodes() ) or an internal array (for .CR dcnodes_status() ); .C errno is set. .PP The following errors are returned if called on a cluster client when there is difficulty contacting, and reading information from, the client's cluster (root) server. .TP 20 .C DCN_ERR_IPADDR Cannot determine the server's .SM IP address from the .RC `` / '' mount point. .TP .C DCN_ERR_RCMD Cannot call .C rcmd() to get information from the server. Problems include failure to find service ``shell'' of type ``tcp'' in the services database, or the effective user's name in the accounts database. .TP .C DCN_ERR_FDOPEN Cannot map file descriptor to a stream using .C fdopen() (see .IR fdopen (3S)); .C errno is set. .TP .C DCN_ERR_STARTUP .C dcnodes command on the server did not return a data format version number. The command might be missing or non-executable, or might have failed before issuing a version number. .TP .C DCN_ERR_VERSION .C dcnodes command on the server did not return the expected data format version number. The command is incompatible with the local version of the .C dcnodes() or .C dcnodes_status() function. .TP .C DCN_ERR_EXEC .C dcnodes command on the server failed (returned -1) after issuing a correct data format version number. The reason is unknown. .TP .C DCN_ERR_READ .C dcnodes command on the server failed (returned wrong amount of data) after issuing a correct data format version number. The reason is unknown. In this case only, .C dcnodes_status() might have modified some of the .C dcn_status fields in the .C dcnode parameter (array). .PP .C dcnodes_server_ipaddr() returns 0 if it sets .C ipaddr successfully. It returns .CR DCN_ERR_IPADDR , and .C ipaddr is unchanged, if it cannot find .RC `` / '' in the system mount table, or if .RC `` / '' is not \s-1NFS\s0-mounted. .\" =========== .SH EXAMPLES The following code fragment obtains all but status information for all members of the cluster on which it is run, and then fills in basic status information for the first three clients (after the cluster server's entries), or for as many clients as there are if there are fewer than three, with a timeout of 20 seconds. .nf .RS .ifn \f3 .ift \f4 #include int num_dcnodes; /* count of nodes */ dcnp_t dcnp; /* node information */ int index; /* in dcnp */ if ((num_dcnodes = dcnodes (\s-1DCNODES_LONG\s0, & dcnp)) <= 0) { \f2(handle error)\fP ... dcnodes_error_string (num_dcnodes) ... } /* skip standalone/server entries: */ for (index = 1; index < num_dcnodes; ++index) if (dcnp[index].dcn_status == DCN_STATUS_UNKNOWN)) break; if (index < num_dcnodes) /* have one or more clients */ { int num_clients = num_dcnodes - index; if (dcnodes_status (\s-1DCNODES_STATUS\s0, dcnp + index, (num_clients < 3) ? num_clients : 3, /* timeout = */ 20) < 0) { \f2(handle error)\fP } ... dcnodes_status_string (\s-1DCNODES_SHORT\s0, dcnp -> dcn_status) ... } .fi .RE .ft P .\" =========== .SH WARNINGS These functions are unsafe in multi-thread applications. .PP Using .C dcnodes() it is possible to distinguish between standalone, server, and client systems, and behave differently depending on the system type. However, it is desirable that applications not make this distinction, and it is usually found to be unnecessary upon closer analysis. .PP .C dcnodes() uses .C malloc() and .C free() to manage the memory for the array it returns. If desired, save a copy of an old array in new memory before calling .C dcnodes() again with a non-null .I dcnode pointer. Call .CR enddcnodes() , not .CR free() , to release the current array when it's no longer needed. .PP .C dcnodes_status() expects to be called only with cluster client names or .SM IP addresses obtained via .CR dcnodes() . It assumes each specified host is a cluster member. It does not check for or distinguish non-members. They appear to be inactive clients. .PP On a cluster client .C dcnodes_status() does not build a command line (to run on the cluster server) with a length greater than 10 kilobytes. It ignores (does not modify status field for) any additional clients whose names or .SM IP addresses don't fit, and returns the number of clients for which status was determined. .PP Normally the cluster server system provides boot, root, and .SM OS shared root services to all client nodes in its cluster. If boot, root, and/or .SM OS shared root services are provided by separate systems, .C dcnodes() and .C dcnodes_status() might return incomplete information, that is, field values of .CR DCN_VALUE_UNKNOWN . They consider the cluster clients of a root server system to be those appearing in the system's list of configured cluster client nodes (see .SM FILES below). When invoked on a remote-root client, they return information about the cluster nodes listed for the client's root server system, using information in files on that server system. If any file is missing (or any error occurs trying to access it), .C dcnodes() and .C dcnodes_status() do not complain, but return incomplete data. .PP The .C dcnodes() and .C dcnodes_status() functions call .C rcmd() to reach the cluster server when called on a cluster client. To ensure success, .C dcnodes() and .C dcnodes_status() on a cluster client should only be invoked by programs running with appropriate privilege to use .C rcmd() to reach the cluster server. Also, .C rcmd() writes messages to standard error in case of failure, and can cause log entries in the syslog files on the target systems if .C inetd is run with the .C -l option (see .IR inetd (1M)). .\" ----------- .SS Performance Issues .C dcnodes_status() might run much faster if .C dcn_ipaddr is specified for each client (not just .CR dcn_name ), because it does not have to look up each client's internet addresses in the hosts database (although this does allow .C dcnodes_status() to try all of the addresses, if necessary, to reach a client). .PP If .C dcnodes_status() is invoked on a cluster client with just that system's name in the dcnodes list, it still contacts the cluster server to determine that the system is active. This is inefficient. .\" =========== .SH AUTHOR .PP These functions were developed by .SM HP. .\" =========== .SH FILES .TP 25 .C /etc/clients.dc list of configured cluster client nodes that receive root service from a system; blank and comment lines (starting with .RC `` # '') are allowed and ignored .TP .C /etc/bootptab control file for .C bootpd (see .IR bootpd (1M)) that contains most of the client information returned by .C dcnodes() .\" =========== .SH SEE ALSO swlist(1), bootpd(1M), dcnodes(1M), dcnodesd(1M), inetd(1M), gethostname(2), setrlimit(2), setuid(2), gethostent(3N), fdopen(3S), malloc(3C), rcmd(3N). .\" .\" toc@\f3dcnodes(3X)\f1:\0\0\f4dcnodes\f1, \f4dcnodes_status\f1, \f4dcnodes_status_string\f1, \f4dcnodes_error_string\f1,\n\f4dcnodes_server_ipaddr\f1, \f4dcnodes_mtime\f1, \f4enddcnodes\f1@@@diskless cluster node information .\" .\" index@\f4dcnodes\f1 \- diskless cluster node information@@@\f3dcnodes(3X)\f1 .\" index@\f1report on diskless cluster nodes@@@\f3dcnodes(3X)\f1 .\" index@\f1diskless cluster nodes, report information about@@@\f3dcnodes(3X)\f1 .\" .\" links@dcnodes.3x dcnodes_status.3x .\" links@dcnodes.3x dcnodes_server_ipaddr.3x .\" links@dcnodes.3x enddcnodes.3x .\" $Header: dcnodes.3x,v 74.2 95/05/10 21:04:24 ssa Exp $ .TA d .TH dcnodes 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" =========== .SH NAME dcnodes(), dcnodes_status(), dcnodes_status_string(), dcnodes_error_string(), dcnodes_server_ipaddr(), enddcnodes() \- report on diskless cluster nodes .\" =========== .SH SYNOPSIS .C "#include " .PP .C "int dcnodes (" .nf .PD 0 .IP .C "const int mode," .C "struct dcnode **dcnode" .PP .C ");" .PD .PP .C "int dcnodes_status (" .nf .PD 0 .IP .C "const int mode," .C "struct dcnode *dcnode," .C "const int num_dcnodes," .C "const time_t timeout" .PP .C ");" .PD .PP .C "int dcnodes_status_string ( .nf .PD 0 .IP .C "const int mode," .C "const int statval" .PP .C ");" .PD .PP .C "int dcnodes_error_string (const int retval);" .PP .C "int dcnodes_server_ipaddr (" .nf .PD 0 .IP .C "char *ipaddr," .C "const int len" .PP .C ");" .PD .PP .C "unsigned long dcnodes_mtime (void);" .PP .C "void enddcnodes (void);" .\" =========== .SS Remarks These functions reside in libdc.a, and are linked using the .C -ldc option to the .C ld or .C cc command. .\" =========== .SH DESCRIPTION These functions help a program get static (configuration) and dynamic (status) information about diskless cluster nodes (server, and clients). The .C dcnodes() and .C dcnodes_status() functions return information about all nodes in a cluster (including the cluster server), when run on any node in the cluster. The .C dcnodes_server_ipaddr() function returns the internet address of a cluster client's server system. .PP The .C dcnode structure is defined in .RC < dcnodes.h > and includes at least the following members. Each string is null-terminated. .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. char@dcn_name[];@/* node name; see below@*/ char@dcn_ipaddr[];@/* IP address, dot form@*/ char@dcn_hwaddr[];@/* hardware address, hex form@*/ char@dcn_netmask[];@/* net/subnet mask, dot form@*/ char@dcn_route[];@/* default route, dot form@*/ char@dcn_shroot[];@/* OS shared root description@*/ int@dcn_status;@/* system status; see below@*/ .TE .ft P .RE .PP The file also defines the following constants and data types: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. DCNODES_SHORT@/* mode parameter to dcnodes(); see below@*/ DCNODES_LONG DCNODES_LONGER DCNODES_ALL DCNODES_TYPE .TE .ft P .RE .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. DCNODES_STATUS@/* mode parameter to dcnodes_status()@*/ DCNODES_STATUS_DETAILS .TE .ft P .RE .PP These lengths do not include the null terminator: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. DCN_NAME_LEN@/* maximum dcnode name length@*/ DCN_IPADDR_LEN@/* maximum IP address length@*/ DCN_HWADDR_LEN@/* maximum HW address length@*/ DCN_NETMASK_LEN@/* maximum net/subnet mask length@*/ DCN_ROUTE_LEN@/* maximum default route length@*/ DCN_SHROOT_LEN@/* maximum OS shared root length@*/ DCN_STATUS_LEN@/* size of status value (int)@*/ DCN_VALUE_UNKNOWN@/* field value cannot be determined@*/ DCN_TYPE_STANDALONE@/* results of DCNODES_TYPE@*/ DCN_TYPE_SERVER DCN_TYPE_CLIENT DCN_ERR_MEMORY@/* error return codes; see below@*/ DCN_ERR_IPADDR DCN_ERR_RCMD DCN_ERR_FDOPEN DCN_ERR_STARTUP DCN_ERR_VERSION DCN_ERR_EXEC DCN_ERR_READ DCN_ERR_SOCKET DCN_ERR_CONNECT DCN_STATUS_UNKNOWN@/* status values; see below@*/ DCN_STATUS_STANDALONE DCN_STATUS_SERVER DCN_STATUS_ACTIVE DCN_STATUS_INACTIVE DCN_STATUS_NO_IP_ADDR DCN_STATUS_NO_DATA DCN_IS_UP(status)@/* macros for checking status value@*/ DCN_IS_SERVER(status) DCN_IS_CLIENT(status) DCN_IS_LOCAL_ROOT(status) .TE .PP .C "typedef struct dcnode *dcnp_t;" .ifn \f3 .ift \f4 .TS tab(@); l l. #define DCN_NULLP@((dcnp_t) 0) #define DCN_NULLPP@((dcnp_t *) 0) #define DCN_SIZE@(sizeof (struct dcnode)) #define DCN_PROG_NULLP@((void (*)()) 0) .TE .ft P .RE .PP If invoked on a cluster client (remote-root) node, .C dcnodes() and .C dcnodes_status() contact the node's root server system to obtain information about all of the cluster's nodes, except as noted below. This requires .C rcmd() access from the client to the server by the effective user .SM ID of the calling process (see .IR rcmd (3N) and .IR setuid (2)) to execute the .CR dcnodes command. .PP The functions have the following purposes: .PP .TP 15 .C dcnodes() This function modifies the .I dcnode pointer to point to an array of .I dcnode structures, each containing information for one node, and returns the number of nodes in the list. The cluster server is always the first system in the list. The .I mode parameter determines which operation is performed: .RS 5 .TP 15 .C DCNODES_SHORT Return a count, and a list, of cluster node names; other structure fields are undefined (except .CR dcn_ipaddr , which is set to null for convenience in calling .CR dcnodes_status() ). The cluster server's .C dcn_name value is its domain-expanded .C hostname value (see .IR gethostname (2)), that is, the result of looking up the system's .C hostname in the hosts database using .C gethostbyname() (see .IR gethostent (3N)). Cluster clients' .C dcn_name values are their names as listed in the cluster client list on the server (see .SM FILES below), normally including domain parts, which should but might not match each client's .C hostname and .C uname.nodename values. .IP With .CR DCNODES_SHORT , the .I dcnode parameter can be a null pointer, which causes .C dcnodes not to allocate space for, and build the list of, cluster node names. In this case it only returns a count of cluster nodes. .IP An unrecognized .I mode value is treated as .CR DCNODES_SHORT . .TP .C DCNODES_LONG Fill in all structure fields except .C dcn_shroot and .CR dcn_status . .C dcn_shroot is undefined. .C dcn_status is set to one of the following as appropriate: .RS .TP 25 .C DCN_STATUS_UNKNOWN for cluster clients (default value) .PD 0 .TP .C DCN_STATUS_SERVER for cluster server systems .TP .C DCN_STATUS_STANDALONE for standalone systems .PD .RE .IP The .C dcn_status field can be filled in by calling .C dcnodes_status() as described below. If .C dcnodes() cannot determine the value for any field, that field is set to the value of the .C DCN_VALUE_UNKNOWN macro. .IP If a standalone or cluster server system has multiple .SM LAN interface cards, there is an entry for each card in the returned array. Each of those entries contains the same values for .C dcn_route and .CR dcn_status , but different values for .C dcn_ipaddr and .CR dcn_hwaddr . The values for .C dcn_name and .C dcn_netmask might differ, reflecting each of the server's .SM LAN interface cards. If a .SM LAN interface card is down, its .C dcn_ipaddr value is .RC `` "(card down)" ''. .IP If the system on which .C dcnodes() is invoked is standalone and has no .SM LAN cards, a single entry is returned with .C dcn_name set to the host's domain-expanded hostname value, and .CR dcn_ipaddr , .CR dcn_hwaddr , and .C dcn_netmask set to the value of .CR DCN_VALUE_UNKNOWN . .TP .C DCNODES_LONGER Same as .C DCNODES_LONG except also fill in the .C dcn_shroot field. This can take significant extra time. The cluster server's .C dcn_shroot value is always ``/''; client values are truncated if necessary, and always null-terminated. If any client's .SM OS shared root description is null, its path appears instead. .TP .C DCNODES_ALL Fill in the array just as for .CR DCNODES_LONGER , and then call .C dcnodes_status() with a .I mode of .C DCNODES_STATUS and a .I timeout value of 10 seconds to also fill in .C dcn_status fields (for all clients) before returning. This saves the caller from calling .C dcnodes_status() separately. .TP .C DCNODES_TYPE Ignore the .I dcnode parameter and just return .C DCN_TYPE_SERVER if the system is a cluster server, .C DCN_TYPE_CLIENT if it is a cluster client, or .C DCN_TYPE_STANDALONE if it is a standalone system (it has a local root and no remote-root clients are configured). When .C dcnodes() is called on a remote-root client with this .I mode it does not contact the cluster server. .RE .IP "" 15 The returned array exists in static space (malloc'd memory \(em see .IR malloc (3C)). This memory is overwritten by the next call, so previously returned pointers become invalid after the next call. .TP .C dcnodes_status() Using an array of .C dcnode structures containing one or more elements, .C dcnodes_status() obtains information on the status of each node from the dcnodes status daemon ( .C dcnodesd ). Information from the daemon is matched with a .C dcnode array entry by .C dcnodes_status() uses the .C dcn_ipaddr field in each .C dcnode structure if it is non-null, and not equal to the value .CR DCN_VALUE_UNKNOWN ; otherwise, it uses the .C dcn_name field in the .C dcnodes structure. .C dcnodes_status() then fills in the .C dcn_status field for each node's element. See .RB `` "Status Fields" '' below for a description of possible field values. .IP Pass the function a mode .RI ( mode ) value which is either .C DCNODES_STATUS or .CR DCNODES_STATUS_DETAILS , a count .RI ( num_dcnodes ) of the number of nodes to process, and a pointer .RI ( dcnode ) to the first element of the array. If any node's .SM IP address is not specified, it converts the node's name to an .SM IP address using .C gethostbyname() (see .IR gethostent (3N)). .IP Also pass the function a timeout value in seconds. This value is the number of seconds that must elapse between the time that a client sends a keepalive packet to the server and the time when the client is inactive. By default, clients send keepalive packets every five seconds. A 10 second timeout, then, means that any timestamp older than 10 seconds is considered invalid and the client is marked as inactive. .TP .C dcnodes_status_string() This function takes a .I mode value .RC ( DCNODES_SHORT or .CR DCNODES_LONG ) and a client status value (the .C dcn_status field, any of .CR DCN_STATUS_ *), and returns a constant or static string equivalent (changed or overwritten by the next call to this function or to .CR catgets() ), in either short or long form. If the status value is .C DCN_STATUS_UNKNOWN or any unrecognized value, the returned string is the value of .CR DCN_VALUE_UNKNOWN . .TP .C dcnodes_error_string() This function takes a return value from .C dcnodes() or .CR dcnodes_status() and returns a constant or static string (changed or overwritten by the next call to this function or to .CR catgets() ), that describes the error condition, suitable for use in an error message. The string begins with an uppercase letter but lacks a trailing period. If the error condition has an .C errno value associated (see .SM "RETURN VALUE" below), the global .C errno value is interpreted as part of the returned error message. If the value passed to .C dcnodes_error_string() is unrecognized, it returns an appropriate message. .TP .C dcnodes_server_ipaddr() This function looks up the internet address part of the mount point for .RC `` / '' and copies it to the caller's .C ipaddr buffer. The string is always null-terminated and truncated if necessary to fit. The size of the buffer and the .C len value are normally .C DCN_IPADDR_LEN + 1. .IP This function should only be called on a cluster client, that is, a remote-root system whose .RC `` / '' directory is \s-1NFS\s0-mounted. The server's .SM IP address is derived from the mount point of .RC `` / '' in the system mount table. This function assumes the server .SM ID is an .SM IP address, not a name. .TP .C dcnodes_mtime() cwThis function allows an application to avoid calling .C dcnodes() again if it's unnecessary to do so because the data hasn't changed. .C dcnodes_mtime() returns the latest mtime stamp on any file used by .C dcnodes() to return its data. If none of the files exists, returns 0. .IP This function can only be called on a cluster server. .TP .C enddcnodes() Frees any malloc'd memory previously allocated by .CR dcnodes() . (Do not call .C free() on a .I dcnode pointer previously passed to .CR dcnodes() , because .C dcnodes() does this itself.) Memory is only allocated by calls to .C dcnodes() with .CR DCNODES_LONG , .CR DCNODES_LONGER , .CR DCNODES_ALL , or .C DCNODES_SHORT with a non-null .C dcnode pointer. .PP Note that a system with a local root directory (root volume) is considered to be standalone or a cluster server as appropriate, not a cluster client, even if most of its files are \s-1NFS\s0-mounted from other systems. .\" ----------- .SS Status Fields The .C dcn_status field for each node is set to one of the following values (defined in .CR dcnodes.h ) by .C dcnodes_status() when it is called using a .I mode parameter of .CR DCNODES_STATUS : .TP 22 .C DCN_STATUS_UNKNOWN Default value from .CR dcnodes() ; also used if the node name and .SM IP address passed to .C dcnodes_status() are both null or equal to the value of .CR DCN_VALUE_UNKNOWN . .TP .C DCN_STATUS_STANDALONE System on which .C dcnodes_status() was invoked is up with a local root volume and has no remote-root clients configured. .TP .C DCN_STATUS_SERVER Cluster (root) server, which is necessarily ``up''. .TP .C DCN_STATUS_ACTIVE Node is up as a remote-root client of the local cluster. It allows .C rcmd() from the cluster (root) server and identifies that system as its root server. Note that all nodes in a cluster are normally configured to allow .C rcmd() access, at least to privileged users, between the cluster server and clients. .TP .C DCN_STATUS_INACTIVE Node has an unknown name (cannot look up internet address), does not respond to or does not allow .C rcmd() from the cluster (root) server, is up standalone (local-rooted), or is booted on another root server. A node is marked inactive if anything goes wrong, including timeout, while trying to check that is it active. .PP If the .I mode parameter is .CR DCNODES_STATUS_DETAILS , instead of marking a client with .C DCN_STATUS_INACTIVE its status value is one of the following: .TP 22 .C DCN_STATUS_NO_IP_ADDR A .C dcn_name value was provided, .C dcn_ipaddr was not, and the given client name is unknown to the hosts database (cannot be mapped to an .SM IP address). .TP .C DCN_STATUS_NO_DATA The .C dcnodesd daemon could not be contacted, or had no data for the specified client. .\" =========== .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG specifies the language used to return messages from .C dcnodes_status_string() and .CR dcnodes_error_string() . .PP If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, the string functions behave as if all internationalization variables are set to ``C''. See .IR environ (5). .\" =========== .SH RETURN VALUE Upon successful completion, .C dcnodes() and .C dcnodes_status() return the number of array elements in the list. This value is 1 or greater, except if .C dcnodes_status() is called with .I num_dcnodes less than 1, it returns 0, and if it is called on a cluster client with more than about 10Kb worth of node names, it returns the number of array elements for which status was set (see .SM WARNINGS below). .PP If .C dcnodes() is called with .CR DCNODES_SHORT , the number of array elements is the number of cluster nodes; with .CR DCNODES_LONG , .CR DCNODES_LONGER , or .CR DCNODES_ALL , there are more elements than dcnodes if the server has multiple .SM LAN cards; with .CR DCNODES_TYPE , the return value is .C DCN_TYPE_STANDALONE (standalone system), .C DCN_TYPE_SERVER (cluster server), or .C DCN_TYPE_CLIENT (cluster client). .PP In case of error, .C dcnodes() and .C dcnodes_status() return a negative value, and do not alter the .I dcnode parameter. .TP 20 .C DCN_ERR_MEMORY Cannot allocate memory to hold the returned array (for .CR dcnodes() ) or an internal array (for .CR dcnodes_status() ); .C errno is set. .PP The following errors are returned if called on a cluster client when there is difficulty contacting, and reading information from, the client's cluster (root) server. .TP 20 .C DCN_ERR_IPADDR Cannot determine the server's .SM IP address from the .RC `` / '' mount point. .TP .C DCN_ERR_RCMD Cannot call .C rcmd() to get information from the server. Problems include failure to find service ``shell'' of type ``tcp'' in the services database, or the effective user's name in the accounts database. .TP .C DCN_ERR_FDOPEN Cannot map file descriptor to a stream using .C fdopen() (see .IR fdopen (3S)); .C errno is set. .TP .C DCN_ERR_STARTUP .C dcnodes command on the server did not return a data format version number. The command might be missing or non-executable, or might have failed before issuing a version number. .TP .C DCN_ERR_VERSION .C dcnodes command on the server did not return the expected data format version number. The command is incompatible with the local version of the .C dcnodes() or .C dcnodes_status() function. .TP .C DCN_ERR_EXEC .C dcnodes command on the server failed (returned -1) after issuing a correct data format version number. The reason is unknown. .TP .C DCN_ERR_READ .C dcnodes command on the server failed (returned wrong amount of data) after issuing a correct data format version number. The reason is unknown. In this case only, .C dcnodes_status() might have modified some of the .C dcn_status fields in the .C dcnode parameter (array). .PP .C dcnodes_server_ipaddr() returns 0 if it sets .C ipaddr successfully. It returns .CR DCN_ERR_IPADDR , and .C ipaddr is unchanged, if it cannot find .RC `` / '' in the system mount table, or if .RC `` / '' is not \s-1NFS\s0-mounted. .\" =========== .SH EXAMPLES The following code fragment obtains all but status information for all members of the cluster on which it is run, and then fills in basic status information for the first three clients (after the cluster server's entries), or for as many clients as there are if there are fewer than three, with a timeout of 20 seconds. .nf .RS .ifn \f3 .ift \f4 #include int num_dcnodes; /* count of nodes */ dcnp_t dcnp; /* node information */ int index; /* in dcnp */ if ((num_dcnodes = dcnodes (\s-1DCNODES_LONG\s0, & dcnp)) <= 0) { \f2(handle error)\fP ... dcnodes_error_string (num_dcnodes) ... } /* skip standalone/server entries: */ for (index = 1; index < num_dcnodes; ++index) if (dcnp[index].dcn_status == DCN_STATUS_UNKNOWN)) break; if (index < num_dcnodes) /* have one or more clients */ { int num_clients = num_dcnodes - index; if (dcnodes_status (\s-1DCNODES_STATUS\s0, dcnp + index, (num_clients < 3) ? num_clients : 3, /* timeout = */ 20) < 0) { \f2(handle error)\fP } ... dcnodes_status_string (\s-1DCNODES_SHORT\s0, dcnp -> dcn_status) ... } .fi .RE .ft P .\" =========== .SH WARNINGS These functions are unsafe in multi-thread applications. .PP Using .C dcnodes() it is possible to distinguish between standalone, server, and client systems, and behave differently depending on the system type. However, it is desirable that applications not make this distinction, and it is usually found to be unnecessary upon closer analysis. .PP .C dcnodes() uses .C malloc() and .C free() to manage the memory for the array it returns. If desired, save a copy of an old array in new memory before calling .C dcnodes() again with a non-null .I dcnode pointer. Call .CR enddcnodes() , not .CR free() , to release the current array when it's no longer needed. .PP .C dcnodes_status() expects to be called only with cluster client names or .SM IP addresses obtained via .CR dcnodes() . It assumes each specified host is a cluster member. It does not check for or distinguish non-members. They appear to be inactive clients. .PP On a cluster client .C dcnodes_status() does not build a command line (to run on the cluster server) with a length greater than 10 kilobytes. It ignores (does not modify status field for) any additional clients whose names or .SM IP addresses don't fit, and returns the number of clients for which status was determined. .PP Normally the cluster server system provides boot, root, and .SM OS shared root services to all client nodes in its cluster. If boot, root, and/or .SM OS shared root services are provided by separate systems, .C dcnodes() and .C dcnodes_status() might return incomplete information, that is, field values of .CR DCN_VALUE_UNKNOWN . They consider the cluster clients of a root server system to be those appearing in the system's list of configured cluster client nodes (see .SM FILES below). When invoked on a remote-root client, they return information about the cluster nodes listed for the client's root server system, using information in files on that server system. If any file is missing (or any error occurs trying to access it), .C dcnodes() and .C dcnodes_status() do not complain, but return incomplete data. .PP The .C dcnodes() and .C dcnodes_status() functions call .C rcmd() to reach the cluster server when called on a cluster client. To ensure success, .C dcnodes() and .C dcnodes_status() on a cluster client should only be invoked by programs running with appropriate privilege to use .C rcmd() to reach the cluster server. Also, .C rcmd() writes messages to standard error in case of failure, and can cause log entries in the syslog files on the target systems if .C inetd is run with the .C -l option (see .IR inetd (1M)). .\" ----------- .SS Performance Issues .C dcnodes_status() might run much faster if .C dcn_ipaddr is specified for each client (not just .CR dcn_name ), because it does not have to look up each client's internet addresses in the hosts database (although this does allow .C dcnodes_status() to try all of the addresses, if necessary, to reach a client). .PP If .C dcnodes_status() is invoked on a cluster client with just that system's name in the dcnodes list, it still contacts the cluster server to determine that the system is active. This is inefficient. .\" =========== .SH AUTHOR .PP These functions were developed by .SM HP. .\" =========== .SH FILES .TP 25 .C /etc/clients.dc list of configured cluster client nodes that receive root service from a system; blank and comment lines (starting with .RC `` # '') are allowed and ignored .TP .C /etc/bootptab control file for .C bootpd (see .IR bootpd (1M)) that contains most of the client information returned by .C dcnodes() .\" =========== .SH SEE ALSO swlist(1), bootpd(1M), dcnodes(1M), dcnodesd(1M), inetd(1M), gethostname(2), setrlimit(2), setuid(2), gethostent(3N), fdopen(3S), malloc(3C), rcmd(3N). .\" .\" toc@\f3dcnodes(3X)\f1:\0\0\f4dcnodes\f1, \f4dcnodes_status\f1, \f4dcnodes_status_string\f1, \f4dcnodes_error_string\f1,\n\f4dcnodes_server_ipaddr\f1, \f4dcnodes_mtime\f1, \f4enddcnodes\f1@@@diskless cluster node information .\" .\" index@\f4dcnodes\f1 \- diskless cluster node information@@@\f3dcnodes(3X)\f1 .\" index@\f1report on diskless cluster nodes@@@\f3dcnodes(3X)\f1 .\" index@\f1diskless cluster nodes, report information about@@@\f3dcnodes(3X)\f1 .\" .\" links@dcnodes.3x dcnodes_status.3x .\" links@dcnodes.3x dcnodes_server_ipaddr.3x .\" links@dcnodes.3x enddcnodes.3x .\" $Header: dcnodes.3x,v 74.2 95/05/10 21:04:24 ssa Exp $ .TA d .TH dcnodes 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" =========== .SH NAME dcnodes(), dcnodes_status(), dcnodes_status_string(), dcnodes_error_string(), dcnodes_server_ipaddr(), enddcnodes() \- report on diskless cluster nodes .\" =========== .SH SYNOPSIS .C "#include " .PP .C "int dcnodes (" .nf .PD 0 .IP .C "const int mode," .C "struct dcnode **dcnode" .PP .C ");" .PD .PP .C "int dcnodes_status (" .nf .PD 0 .IP .C "const int mode," .C "struct dcnode *dcnode," .C "const int num_dcnodes," .C "const time_t timeout" .PP .C ");" .PD .PP .C "int dcnodes_status_string ( .nf .PD 0 .IP .C "const int mode," .C "const int statval" .PP .C ");" .PD .PP .C "int dcnodes_error_string (const int retval);" .PP .C "int dcnodes_server_ipaddr (" .nf .PD 0 .IP .C "char *ipaddr," .C "const int len" .PP .C ");" .PD .PP .C "unsigned long dcnodes_mtime (void);" .PP .C "void enddcnodes (void);" .\" =========== .SS Remarks These functions reside in libdc.a, and are linked using the .C -ldc option to the .C ld or .C cc command. .\" =========== .SH DESCRIPTION These functions help a program get static (configuration) and dynamic (status) information about diskless cluster nodes (server, and clients). The .C dcnodes() and .C dcnodes_status() functions return information about all nodes in a cluster (including the cluster server), when run on any node in the cluster. The .C dcnodes_server_ipaddr() function returns the internet address of a cluster client's server system. .PP The .C dcnode structure is defined in .RC < dcnodes.h > and includes at least the following members. Each string is null-terminated. .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. char@dcn_name[];@/* node name; see below@*/ char@dcn_ipaddr[];@/* IP address, dot form@*/ char@dcn_hwaddr[];@/* hardware address, hex form@*/ char@dcn_netmask[];@/* net/subnet mask, dot form@*/ char@dcn_route[];@/* default route, dot form@*/ char@dcn_shroot[];@/* OS shared root description@*/ int@dcn_status;@/* system status; see below@*/ .TE .ft P .RE .PP The file also defines the following constants and data types: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. DCNODES_SHORT@/* mode parameter to dcnodes(); see below@*/ DCNODES_LONG DCNODES_LONGER DCNODES_ALL DCNODES_TYPE .TE .ft P .RE .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. DCNODES_STATUS@/* mode parameter to dcnodes_status()@*/ DCNODES_STATUS_DETAILS .TE .ft P .RE .PP These lengths do not include the null terminator: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. DCN_NAME_LEN@/* maximum dcnode name length@*/ DCN_IPADDR_LEN@/* maximum IP address length@*/ DCN_HWADDR_LEN@/* maximum HW address length@*/ DCN_NETMASK_LEN@/* maximum net/subnet mask length@*/ DCN_ROUTE_LEN@/* maximum default route length@*/ DCN_SHROOT_LEN@/* maximum OS shared root length@*/ DCN_STATUS_LEN@/* size of status value (int)@*/ DCN_VALUE_UNKNOWN@/* field value cannot be determined@*/ DCN_TYPE_STANDALONE@/* results of DCNODES_TYPE@*/ DCN_TYPE_SERVER DCN_TYPE_CLIENT DCN_ERR_MEMORY@/* error return codes; see below@*/ DCN_ERR_IPADDR DCN_ERR_RCMD DCN_ERR_FDOPEN DCN_ERR_STARTUP DCN_ERR_VERSION DCN_ERR_EXEC DCN_ERR_READ DCN_ERR_SOCKET DCN_ERR_CONNECT DCN_STATUS_UNKNOWN@/* status values; see below@*/ DCN_STATUS_STANDALONE DCN_STATUS_SERVER DCN_STATUS_ACTIVE DCN_STATUS_INACTIVE DCN_STATUS_NO_IP_ADDR DCN_STATUS_NO_DATA DCN_IS_UP(status)@/* macros for checking status value@*/ DCN_IS_SERVER(status) DCN_IS_CLIENT(status) DCN_IS_LOCAL_ROOT(status) .TE .PP .C "typedef struct dcnode *dcnp_t;" .ifn \f3 .ift \f4 .TS tab(@); l l. #define DCN_NULLP@((dcnp_t) 0) #define DCN_NULLPP@((dcnp_t *) 0) #define DCN_SIZE@(sizeof (struct dcnode)) #define DCN_PROG_NULLP@((void (*)()) 0) .TE .ft P .RE .PP If invoked on a cluster client (remote-root) node, .C dcnodes() and .C dcnodes_status() contact the node's root server system to obtain information about all of the cluster's nodes, except as noted below. This requires .C rcmd() access from the client to the server by the effective user .SM ID of the calling process (see .IR rcmd (3N) and .IR setuid (2)) to execute the .CR dcnodes command. .PP The functions have the following purposes: .PP .TP 15 .C dcnodes() This function modifies the .I dcnode pointer to point to an array of .I dcnode structures, each containing information for one node, and returns the number of nodes in the list. The cluster server is always the first system in the list. The .I mode parameter determines which operation is performed: .RS 5 .TP 15 .C DCNODES_SHORT Return a count, and a list, of cluster node names; other structure fields are undefined (except .CR dcn_ipaddr , which is set to null for convenience in calling .CR dcnodes_status() ). The cluster server's .C dcn_name value is its domain-expanded .C hostname value (see .IR gethostname (2)), that is, the result of looking up the system's .C hostname in the hosts database using .C gethostbyname() (see .IR gethostent (3N)). Cluster clients' .C dcn_name values are their names as listed in the cluster client list on the server (see .SM FILES below), normally including domain parts, which should but might not match each client's .C hostname and .C uname.nodename values. .IP With .CR DCNODES_SHORT , the .I dcnode parameter can be a null pointer, which causes .C dcnodes not to allocate space for, and build the list of, cluster node names. In this case it only returns a count of cluster nodes. .IP An unrecognized .I mode value is treated as .CR DCNODES_SHORT . .TP .C DCNODES_LONG Fill in all structure fields except .C dcn_shroot and .CR dcn_status . .C dcn_shroot is undefined. .C dcn_status is set to one of the following as appropriate: .RS .TP 25 .C DCN_STATUS_UNKNOWN for cluster clients (default value) .PD 0 .TP .C DCN_STATUS_SERVER for cluster server systems .TP .C DCN_STATUS_STANDALONE for standalone systems .PD .RE .IP The .C dcn_status field can be filled in by calling .C dcnodes_status() as described below. If .C dcnodes() cannot determine the value for any field, that field is set to the value of the .C DCN_VALUE_UNKNOWN macro. .IP If a standalone or cluster server system has multiple .SM LAN interface cards, there is an entry for each card in the returned array. Each of those entries contains the same values for .C dcn_route and .CR dcn_status , but different values for .C dcn_ipaddr and .CR dcn_hwaddr . The values for .C dcn_name and .C dcn_netmask might differ, reflecting each of the server's .SM LAN interface cards. If a .SM LAN interface card is down, its .C dcn_ipaddr value is .RC `` "(card down)" ''. .IP If the system on which .C dcnodes() is invoked is standalone and has no .SM LAN cards, a single entry is returned with .C dcn_name set to the host's domain-expanded hostname value, and .CR dcn_ipaddr , .CR dcn_hwaddr , and .C dcn_netmask set to the value of .CR DCN_VALUE_UNKNOWN . .TP .C DCNODES_LONGER Same as .C DCNODES_LONG except also fill in the .C dcn_shroot field. This can take significant extra time. The cluster server's .C dcn_shroot value is always ``/''; client values are truncated if necessary, and always null-terminated. If any client's .SM OS shared root description is null, its path appears instead. .TP .C DCNODES_ALL Fill in the array just as for .CR DCNODES_LONGER , and then call .C dcnodes_status() with a .I mode of .C DCNODES_STATUS and a .I timeout value of 10 seconds to also fill in .C dcn_status fields (for all clients) before returning. This saves the caller from calling .C dcnodes_status() separately. .TP .C DCNODES_TYPE Ignore the .I dcnode parameter and just return .C DCN_TYPE_SERVER if the system is a cluster server, .C DCN_TYPE_CLIENT if it is a cluster client, or .C DCN_TYPE_STANDALONE if it is a standalone system (it has a local root and no remote-root clients are configured). When .C dcnodes() is called on a remote-root client with this .I mode it does not contact the cluster server. .RE .IP "" 15 The returned array exists in static space (malloc'd memory \(em see .IR malloc (3C)). This memory is overwritten by the next call, so previously returned pointers become invalid after the next call. .TP .C dcnodes_status() Using an array of .C dcnode structures containing one or more elements, .C dcnodes_status() obtains information on the status of each node from the dcnodes status daemon ( .C dcnodesd ). Information from the daemon is matched with a .C dcnode array entry by .C dcnodes_status() uses the .C dcn_ipaddr field in each .C dcnode structure if it is non-null, and not equal to the value .CR DCN_VALUE_UNKNOWN ; otherwise, it uses the .C dcn_name field in the .C dcnodes structure. .C dcnodes_status() then fills in the .C dcn_status field for each node's element. See .RB `` "Status Fields" '' below for a description of possible field values. .IP Pass the function a mode .RI ( mode ) value which is either .C DCNODES_STATUS or .CR DCNODES_STATUS_DETAILS , a count .RI ( num_dcnodes ) of the number of nodes to process, and a pointer .RI ( dcnode ) to the first element of the array. If any node's .SM IP address is not specified, it converts the node's name to an .SM IP address using .C gethostbyname() (see .IR gethostent (3N)). .IP Also pass the function a timeout value in seconds. This value is the number of seconds that must elapse between the time that a client sends a keepalive packet to the server and the time when the client is inactive. By default, clients send keepalive packets every five seconds. A 10 second timeout, then, means that any timestamp older than 10 seconds is considered invalid and the client is marked as inactive. .TP .C dcnodes_status_string() This function takes a .I mode value .RC ( DCNODES_SHORT or .CR DCNODES_LONG ) and a client status value (the .C dcn_status field, any of .CR DCN_STATUS_ *), and returns a constant or static string equivalent (changed or overwritten by the next call to this function or to .CR catgets() ), in either short or long form. If the status value is .C DCN_STATUS_UNKNOWN or any unrecognized value, the returned string is the value of .CR DCN_VALUE_UNKNOWN . .TP .C dcnodes_error_string() This function takes a return value from .C dcnodes() or .CR dcnodes_status() and returns a constant or static string (changed or overwritten by the next call to this function or to .CR catgets() ), that describes the error condition, suitable for use in an error message. The string begins with an uppercase letter but lacks a trailing period. If the error condition has an .C errno value associated (see .SM "RETURN VALUE" below), the global .C errno value is interpreted as part of the returned error message. If the value passed to .C dcnodes_error_string() is unrecognized, it returns an appropriate message. .TP .C dcnodes_server_ipaddr() This function looks up the internet address part of the mount point for .RC `` / '' and copies it to the caller's .C ipaddr buffer. The string is always null-terminated and truncated if necessary to fit. The size of the buffer and the .C len value are normally .C DCN_IPADDR_LEN + 1. .IP This function should only be called on a cluster client, that is, a remote-root system whose .RC `` / '' directory is \s-1NFS\s0-mounted. The server's .SM IP address is derived from the mount point of .RC `` / '' in the system mount table. This function assumes the server .SM ID is an .SM IP address, not a name. .TP .C dcnodes_mtime() cwThis function allows an application to avoid calling .C dcnodes() again if it's unnecessary to do so because the data hasn't changed. .C dcnodes_mtime() returns the latest mtime stamp on any file used by .C dcnodes() to return its data. If none of the files exists, returns 0. .IP This function can only be called on a cluster server. .TP .C enddcnodes() Frees any malloc'd memory previously allocated by .CR dcnodes() . (Do not call .C free() on a .I dcnode pointer previously passed to .CR dcnodes() , because .C dcnodes() does this itself.) Memory is only allocated by calls to .C dcnodes() with .CR DCNODES_LONG , .CR DCNODES_LONGER , .CR DCNODES_ALL , or .C DCNODES_SHORT with a non-null .C dcnode pointer. .PP Note that a system with a local root directory (root volume) is considered to be standalone or a cluster server as appropriate, not a cluster client, even if most of its files are \s-1NFS\s0-mounted from other systems. .\" ----------- .SS Status Fields The .C dcn_status field for each node is set to one of the following values (defined in .CR dcnodes.h ) by .C dcnodes_status() when it is called using a .I mode parameter of .CR DCNODES_STATUS : .TP 22 .C DCN_STATUS_UNKNOWN Default value from .CR dcnodes() ; also used if the node name and .SM IP address passed to .C dcnodes_status() are both null or equal to the value of .CR DCN_VALUE_UNKNOWN . .TP .C DCN_STATUS_STANDALONE System on which .C dcnodes_status() was invoked is up with a local root volume and has no remote-root clients configured. .TP .C DCN_STATUS_SERVER Cluster (root) server, which is necessarily ``up''. .TP .C DCN_STATUS_ACTIVE Node is up as a remote-root client of the local cluster. It allows .C rcmd() from the cluster (root) server and identifies that system as its root server. Note that all nodes in a cluster are normally configured to allow .C rcmd() access, at least to privileged users, between the cluster server and clients. .TP .C DCN_STATUS_INACTIVE Node has an unknown name (cannot look up internet address), does not respond to or does not allow .C rcmd() from the cluster (root) server, is up standalone (local-rooted), or is booted on another root server. A node is marked inactive if anything goes wrong, including timeout, while trying to check that is it active. .PP If the .I mode parameter is .CR DCNODES_STATUS_DETAILS , instead of marking a client with .C DCN_STATUS_INACTIVE its status value is one of the following: .TP 22 .C DCN_STATUS_NO_IP_ADDR A .C dcn_name value was provided, .C dcn_ipaddr was not, and the given client name is unknown to the hosts database (cannot be mapped to an .SM IP address). .TP .C DCN_STATUS_NO_DATA The .C dcnodesd daemon could not be contacted, or had no data for the specified client. .\" =========== .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG specifies the language used to return messages from .C dcnodes_status_string() and .CR dcnodes_error_string() . .PP If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, the string functions behave as if all internationalization variables are set to ``C''. See .IR environ (5). .\" =========== .SH RETURN VALUE Upon successful completion, .C dcnodes() and .C dcnodes_status() return the number of array elements in the list. This value is 1 or greater, except if .C dcnodes_status() is called with .I num_dcnodes less than 1, it returns 0, and if it is called on a cluster client with more than about 10Kb worth of node names, it returns the number of array elements for which status was set (see .SM WARNINGS below). .PP If .C dcnodes() is called with .CR DCNODES_SHORT , the number of array elements is the number of cluster nodes; with .CR DCNODES_LONG , .CR DCNODES_LONGER , or .CR DCNODES_ALL , there are more elements than dcnodes if the server has multiple .SM LAN cards; with .CR DCNODES_TYPE , the return value is .C DCN_TYPE_STANDALONE (standalone system), .C DCN_TYPE_SERVER (cluster server), or .C DCN_TYPE_CLIENT (cluster client). .PP In case of error, .C dcnodes() and .C dcnodes_status() return a negative value, and do not alter the .I dcnode parameter. .TP 20 .C DCN_ERR_MEMORY Cannot allocate memory to hold the returned array (for .CR dcnodes() ) or an internal array (for .CR dcnodes_status() ); .C errno is set. .PP The following errors are returned if called on a cluster client when there is difficulty contacting, and reading information from, the client's cluster (root) server. .TP 20 .C DCN_ERR_IPADDR Cannot determine the server's .SM IP address from the .RC `` / '' mount point. .TP .C DCN_ERR_RCMD Cannot call .C rcmd() to get information from the server. Problems include failure to find service ``shell'' of type ``tcp'' in the services database, or the effective user's name in the accounts database. .TP .C DCN_ERR_FDOPEN Cannot map file descriptor to a stream using .C fdopen() (see .IR fdopen (3S)); .C errno is set. .TP .C DCN_ERR_STARTUP .C dcnodes command on the server did not return a data format version number. The command might be missing or non-executable, or might have failed before issuing a version number. .TP .C DCN_ERR_VERSION .C dcnodes command on the server did not return the expected data format version number. The command is incompatible with the local version of the .C dcnodes() or .C dcnodes_status() function. .TP .C DCN_ERR_EXEC .C dcnodes command on the server failed (returned -1) after issuing a correct data format version number. The reason is unknown. .TP .C DCN_ERR_READ .C dcnodes command on the server failed (returned wrong amount of data) after issuing a correct data format version number. The reason is unknown. In this case only, .C dcnodes_status() might have modified some of the .C dcn_status fields in the .C dcnode parameter (array). .PP .C dcnodes_server_ipaddr() returns 0 if it sets .C ipaddr successfully. It returns .CR DCN_ERR_IPADDR , and .C ipaddr is unchanged, if it cannot find .RC `` / '' in the system mount table, or if .RC `` / '' is not \s-1NFS\s0-mounted. .\" =========== .SH EXAMPLES The following code fragment obtains all but status information for all members of the cluster on which it is run, and then fills in basic status information for the first three clients (after the cluster server's entries), or for as many clients as there are if there are fewer than three, with a timeout of 20 seconds. .nf .RS .ifn \f3 .ift \f4 #include int num_dcnodes; /* count of nodes */ dcnp_t dcnp; /* node information */ int index; /* in dcnp */ if ((num_dcnodes = dcnodes (\s-1DCNODES_LONG\s0, & dcnp)) <= 0) { \f2(handle error)\fP ... dcnodes_error_string (num_dcnodes) ... } /* skip standalone/server entries: */ for (index = 1; index < num_dcnodes; ++index) if (dcnp[index].dcn_status == DCN_STATUS_UNKNOWN)) break; if (index < num_dcnodes) /* have one or more clients */ { int num_clients = num_dcnodes - index; if (dcnodes_status (\s-1DCNODES_STATUS\s0, dcnp + index, (num_clients < 3) ? num_clients : 3, /* timeout = */ 20) < 0) { \f2(handle error)\fP } ... dcnodes_status_string (\s-1DCNODES_SHORT\s0, dcnp -> dcn_status) ... } .fi .RE .ft P .\" =========== .SH WARNINGS These functions are unsafe in multi-thread applications. .PP Using .C dcnodes() it is possible to distinguish between standalone, server, and client systems, and behave differently depending on the system type. However, it is desirable that applications not make this distinction, and it is usually found to be unnecessary upon closer analysis. .PP .C dcnodes() uses .C malloc() and .C free() to manage the memory for the array it returns. If desired, save a copy of an old array in new memory before calling .C dcnodes() again with a non-null .I dcnode pointer. Call .CR enddcnodes() , not .CR free() , to release the current array when it's no longer needed. .PP .C dcnodes_status() expects to be called only with cluster client names or .SM IP addresses obtained via .CR dcnodes() . It assumes each specified host is a cluster member. It does not check for or distinguish non-members. They appear to be inactive clients. .PP On a cluster client .C dcnodes_status() does not build a command line (to run on the cluster server) with a length greater than 10 kilobytes. It ignores (does not modify status field for) any additional clients whose names or .SM IP addresses don't fit, and returns the number of clients for which status was determined. .PP Normally the cluster server system provides boot, root, and .SM OS shared root services to all client nodes in its cluster. If boot, root, and/or .SM OS shared root services are provided by separate systems, .C dcnodes() and .C dcnodes_status() might return incomplete information, that is, field values of .CR DCN_VALUE_UNKNOWN . They consider the cluster clients of a root server system to be those appearing in the system's list of configured cluster client nodes (see .SM FILES below). When invoked on a remote-root client, they return information about the cluster nodes listed for the client's root server system, using information in files on that server system. If any file is missing (or any error occurs trying to access it), .C dcnodes() and .C dcnodes_status() do not complain, but return incomplete data. .PP The .C dcnodes() and .C dcnodes_status() functions call .C rcmd() to reach the cluster server when called on a cluster client. To ensure success, .C dcnodes() and .C dcnodes_status() on a cluster client should only be invoked by programs running with appropriate privilege to use .C rcmd() to reach the cluster server. Also, .C rcmd() writes messages to standard error in case of failure, and can cause log entries in the syslog files on the target systems if .C inetd is run with the .C -l option (see .IR inetd (1M)). .\" ----------- .SS Performance Issues .C dcnodes_status() might run much faster if .C dcn_ipaddr is specified for each client (not just .CR dcn_name ), because it does not have to look up each client's internet addresses in the hosts database (although this does allow .C dcnodes_status() to try all of the addresses, if necessary, to reach a client). .PP If .C dcnodes_status() is invoked on a cluster client with just that system's name in the dcnodes list, it still contacts the cluster server to determine that the system is active. This is inefficient. .\" =========== .SH AUTHOR .PP These functions were developed by .SM HP. .\" =========== .SH FILES .TP 25 .C /etc/clients.dc list of configured cluster client nodes that receive root service from a system; blank and comment lines (starting with .RC `` # '') are allowed and ignored .TP .C /etc/bootptab control file for .C bootpd (see .IR bootpd (1M)) that contains most of the client information returned by .C dcnodes() .\" =========== .SH SEE ALSO swlist(1), bootpd(1M), dcnodes(1M), dcnodesd(1M), inetd(1M), gethostname(2), setrlimit(2), setuid(2), gethostent(3N), fdopen(3S), malloc(3C), rcmd(3N). .\" .\" toc@\f3dcnodes(3X)\f1:\0\0\f4dcnodes\f1, \f4dcnodes_status\f1, \f4dcnodes_status_string\f1, \f4dcnodes_error_string\f1,\n\f4dcnodes_server_ipaddr\f1, \f4dcnodes_mtime\f1, \f4enddcnodes\f1@@@diskless cluster node information .\" .\" index@\f4dcnodes\f1 \- diskless cluster node information@@@\f3dcnodes(3X)\f1 .\" index@\f1report on diskless cluster nodes@@@\f3dcnodes(3X)\f1 .\" index@\f1diskless cluster nodes, report information about@@@\f3dcnodes(3X)\f1 .\" .\" links@dcnodes.3x dcnodes_status.3x .\" links@dcnodes.3x dcnodes_server_ipaddr.3x .\" links@dcnodes.3x enddcnodes.3x .\" $Header: def_prog_mode.3x,v 76.2 95/07/31 11:23:20 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH def_prog_mode 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 defshell .SH NAME def_prog_mode, def_shell_mode, reset_prog_mode, reset_shell_mode \(em save or restore program or shell terminal modes .SH SYNOPSIS .C "#include " .P .C "int def_prog_mode(void);" .P .C "int def_shell_mode(void);" .P .C "int reset_prog_mode(void);" .P .C "int reset_shell_mode(void);" .SH DESCRIPTION The .Fn def_prog_mode function saves the current terminal modes as the ``program'' (in Curses) state for use by .Fn reset_prog_mode . .P The .Fn def_shell_mode function saves the current terminal modes as the ``shell'' (not in Curses) state for use by .Fn reset_shell_mode . .P The .Fn reset_prog_mode function restores the terminal to the ``program'' (in Curses) state. .P The .Fn reset_shell_mode function restores the terminal to the ``shell'' (not in Curses) state. .P These functions affect the mode of the terminal associated with the current screen. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn initscr function achieves the effect of calling .Fn def_shell_mode to save the prior terminal settings so they can be restored during the call to .Fn endwin , and of calling .Fn def_prog_mode to specify an initial definition of the program terminal mode. .P Applications normally do not need to refer to the shell terminal mode. Applications may find it useful to save and restore the program terminal mode. .SH "SEE ALSO" doupdate(), endwin(), initscr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The .Fn reset_prog_mode and .Fn reset_shell_mode functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The argument list for all these functions is explicitly declared as \f3void\f1. .\" .\" .\" toc@\f3def_prog_mode(3x)\f1:\0\0\f4def_prog_mode()\f1, \f4def_shell_mode()\f1, \f4reset_prog_mode()\f1, \n\f4reset_shell_mode()\f1@@@save or restore program or shell terminal modes .\" toc@\f4def_shell_mode()\f1:\0\0save current terminal modes as the ``shell'' (not in Curses) state@@@\f1see \f3def_prog_mode(3x)\f1 .\" toc@\f4reset_prog_mode()\f1:\0\0restore terminal modes to ``program'' (in Curses) state@@@\f1see \f3def_prog_mode(3x)\f1 .\" toc@\f4reset_shell_mode()\f1:\0\0restore terminal modes to ``shell'' (not in Curses) state@@@\f1see \f3def_prog_mode(3x)\f1 .\" .\" index@\f4def_shell_mode()\f1 \- save terminal modes as the ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" index@\f4def_prog_mode()\f1 \- save or restore program or shell terminal modes@@@\f3def_prog_mode(3x)\f1 .\" index@\f4reset_prog_mode()\f1 \- restore shell terminal modes to ``program'' state @@@\f3def_prog_mode(3x)\f1 .\" index@\f4reset_shell_mode()\f1 \- restore terminal modes to ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" .\" index@\f1save terminal modes as the ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" index@\f1save or restore program or shell terminal modes@@@\f3def_prog_mode(3x)\f1 .\" index@\f1restore shell terminal modes to ``program'' state @@@\f3def_prog_mode(3x)\f1 .\" index@\f1restore terminal modes to ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" .\" .\" links@def_prog_mode.3x def_shell_mode.3x .\" links@def_prog_mode.3x reset_prog_mode.3x .\" links@def_prog_mode.3x reset_shell_mode.3x .\" .\" fileset_database@def_prog_mode.3x CURS-ENG-A-MAN .\" $Header: def_prog_mode.3x,v 76.2 95/07/31 11:23:20 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH def_prog_mode 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 defshell .SH NAME def_prog_mode, def_shell_mode, reset_prog_mode, reset_shell_mode \(em save or restore program or shell terminal modes .SH SYNOPSIS .C "#include " .P .C "int def_prog_mode(void);" .P .C "int def_shell_mode(void);" .P .C "int reset_prog_mode(void);" .P .C "int reset_shell_mode(void);" .SH DESCRIPTION The .Fn def_prog_mode function saves the current terminal modes as the ``program'' (in Curses) state for use by .Fn reset_prog_mode . .P The .Fn def_shell_mode function saves the current terminal modes as the ``shell'' (not in Curses) state for use by .Fn reset_shell_mode . .P The .Fn reset_prog_mode function restores the terminal to the ``program'' (in Curses) state. .P The .Fn reset_shell_mode function restores the terminal to the ``shell'' (not in Curses) state. .P These functions affect the mode of the terminal associated with the current screen. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn initscr function achieves the effect of calling .Fn def_shell_mode to save the prior terminal settings so they can be restored during the call to .Fn endwin , and of calling .Fn def_prog_mode to specify an initial definition of the program terminal mode. .P Applications normally do not need to refer to the shell terminal mode. Applications may find it useful to save and restore the program terminal mode. .SH "SEE ALSO" doupdate(), endwin(), initscr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The .Fn reset_prog_mode and .Fn reset_shell_mode functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The argument list for all these functions is explicitly declared as \f3void\f1. .\" .\" .\" toc@\f3def_prog_mode(3x)\f1:\0\0\f4def_prog_mode()\f1, \f4def_shell_mode()\f1, \f4reset_prog_mode()\f1, \n\f4reset_shell_mode()\f1@@@save or restore program or shell terminal modes .\" toc@\f4def_shell_mode()\f1:\0\0save current terminal modes as the ``shell'' (not in Curses) state@@@\f1see \f3def_prog_mode(3x)\f1 .\" toc@\f4reset_prog_mode()\f1:\0\0restore terminal modes to ``program'' (in Curses) state@@@\f1see \f3def_prog_mode(3x)\f1 .\" toc@\f4reset_shell_mode()\f1:\0\0restore terminal modes to ``shell'' (not in Curses) state@@@\f1see \f3def_prog_mode(3x)\f1 .\" .\" index@\f4def_shell_mode()\f1 \- save terminal modes as the ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" index@\f4def_prog_mode()\f1 \- save or restore program or shell terminal modes@@@\f3def_prog_mode(3x)\f1 .\" index@\f4reset_prog_mode()\f1 \- restore shell terminal modes to ``program'' state @@@\f3def_prog_mode(3x)\f1 .\" index@\f4reset_shell_mode()\f1 \- restore terminal modes to ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" .\" index@\f1save terminal modes as the ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" index@\f1save or restore program or shell terminal modes@@@\f3def_prog_mode(3x)\f1 .\" index@\f1restore shell terminal modes to ``program'' state @@@\f3def_prog_mode(3x)\f1 .\" index@\f1restore terminal modes to ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" .\" .\" links@def_prog_mode.3x def_shell_mode.3x .\" links@def_prog_mode.3x reset_prog_mode.3x .\" links@def_prog_mode.3x reset_shell_mode.3x .\" .\" fileset_database@def_prog_mode.3x CURS-ENG-A-MAN .\" $Header: del_curterm.3x,v 76.2 95/07/31 11:24:20 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH del_curterm 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME del_curterm, restartterm, set_curterm, setupterm \(em interfaces to the \f3terminfo\f1 database .SH SYNOPSIS .C "#include " .P .C "int del_curterm(TERMINAL *\f2oterm\f4);" .P .C "int restartterm(char *\f2term\f4, int \f2fildes\f4, int *\f2errret\f4);" .P .C "TERMINAL *set_curterm(TERMINAL *\f2nterm\f4);" .P .C "int setupterm(char *\f2term\f4, int \f2fildes\f4, int *\f2errret\f4);" .P .C "extern TERMINAL *cur_term;" .SH DESCRIPTION These functions retrieve information from the \f3terminfo\f1 database. .P To gain access to the \f3terminfo\f1 database, .Fn setupterm must be called first. It is automatically called by .Fn initscr and .Fn newterm . The .Fn setupterm function initializes the other functions to use the \f3terminfo\f1 record for a specified terminal (which depends on whether .Fn use_env was called). It sets the .I cur_term external variable to a \f3TERMINAL\f1 structure that contains the record from the \f3terminfo\f1 database for the specified terminal. .P The terminal type is the character string \f2term;\f1 if \f2term\f1 is a null pointer, the environment variable TERM is used. If TERM is not set or if its value is an empty string, then \f4"unknown"\f1 is used as the terminal type. The application must set \f2fildes\f1 to a file descriptor, open for output, to the terminal device, before calling .Fn setupterm . If \f2errret\f1 is not null, the integer it points to is set to one of the following values to report the function outcome: .PP .RS .TP 10 .CR \(mi1 The \f3terminfo\f1 database was not found (function fails). .TP .CR 0 The entry for the terminal was not found in \f3terminfo\f1 (function fails). .TP .CR 1 Success. .PP .RE If .Fn setupterm detects an error and \f2errret\f1 is a null pointer, .Fn setupterm writes a diagnostic message and exits. .P A simple call to .Fn setupterm that uses all the defaults and sends the output to \f2stdout\f1 is: .\" .Cs I .IP setupterm((char *)0, fileno(stdout), (int *)0); .\" .Ce .PP The .Fn set_curterm function sets the variable \f2cur_term\f1 to \f2nterm\f1, and makes all of the \f3terminfo\f1 boolean, numeric, and string variables use the values from \f2nterm.\f1 .P The .Fn del_curterm function frees the space pointed to by \f2oterm\f1 and makes it available for further use. If \f2oterm\f1 is the same as \f2cur_term\f1, references to any of the \f3terminfo\f1 boolean, numeric, and string variables thereafter may refer to invalid memory locations until .Fn setupterm is called again. .P The .Fn restartterm function assumes a previous call to .Fn setupterm (perhaps from .Fn initscr or .Fn newterm ). It lets the application specify a different terminal type in \f2term\f1 and updates the information returned by .Fn baudrate based on \f2fildes\f1, but does not destroy other information created by .Fn initscr , .Fn newterm or .Fn setupterm . .SH "RETURN VALUE" Upon successful completion, .Fn set_curterm returns the previous value of \f2cur_term\f1. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" An application would call .Fn setupterm if it required access to the \f3terminfo\f1 database but did not otherwise need to use Curses. .SH "SEE ALSO" \f3Selecting a Terminal\f1 in terminfo(4), baudrate(), erasechar(), has_ic(), longname(), putc(), termattrs(), termname(), tgetent(), tigetflag(), use_env(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3del_curterm(3x)\f1:\0\0\f4del_curterm()\f1, \f4restartterm()\f1, \f4set_curterm()\f1,\n\f4setupterm()\f1@@@interfaces to terminfo database .\" .\" toc@\f4del_curterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" toc@\f4restartterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" toc@\f4set_curterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" toc@\f4setupterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" .\" index@\f4del_curterm()\f1, \f4restartterm()\f1, \f4set_curterm()\f1, \f4setupterm()\f1 \- interfaces to \nterminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f4restartterm()\f1 \- interface to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f4set_curterm()\f1 \- interface to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f4setupterm()\f1 \- interface to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f1interfaces to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f1terminfo database, interfaces@@@\f3del_curterm(3x)\f1 .\" .\" links@del_curterm.3x restartterm.3x .\" links@del_curterm.3x set_curterm.3x .\" links@del_curterm.3x setupterm.3x .\" .\" fileset_database@del_curtem.3x CURS-ENG-A-MAN .\" .\" $Header: delay_output.3x,v 76.2 95/08/01 15:02:59 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH delay_output 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME delay_output \(em delay output .SH SYNOPSIS .C "#include " .P .C "int delay_output(int \f2ms\fP);" .SH DESCRIPTION On terminals that support pad characters, .Fn delay_output pauses the output for at least \f2ms\f1 milliseconds. Otherwise, the length of the delay is unspecified. .SH "RETURN VALUE" Upon successful completion, .Fn delay_output returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Whether or not the terminal supports pad characters, the .Fn delay_output function is not a precise method of timekeeping. .SH "SEE ALSO" \f3Defined Capabilities\f1 in terminfo(4), napms(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" toc@\f3delay_output(3x)\f1@@@delay output .\" .\" index@\f4delay_output()\f1 \- delay output@@@\f3delay_output(3x)\f1 .\" .\" fileset_database@delay_output.3x CURS-ENG-A-MAN .\" .\" $Header: delch.3x,v 76.2 95/08/01 15:04:04 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH delch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME delch, mvdelch, mvwdelch, wdelch \(em delete a character from a window. .SH SYNOPSIS .C "#include " .P .C "int delch(void);" .P .C "int mvdelch(int \f2y\fP, int \f2x\fP);" .P .C "int mvwdelch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "int wdelch(WINDOW *\f2win\fP);" .SH DESCRIPTION These functions delete the character at the current or specified position in the current or specified window. This function does not change the cursor position. .SS "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SS ERRORS No errors are defined. .SS "SEE ALSO" . .SS "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn delch function is explicitly declared as \f3void\f1. .\" .\" toc@\f3delch(3x)\f1:\0\0\f4delch()\f1, \f4mvdelch()\f1, \f4mvwdelch()\f1, \f4wdelch()\f1@@@delete character from a window .\" .\" toc@\f3mvdelch()\f1:\0\0delete character from a window@@@\f1see\f3delch(3x)\f1 .\" toc@\f3mvwdelch()\f1:\0\0delete character from a window@@@\f1see\f3delch(3x)\f1 .\" toc@\f3wdelch()\f1:\0\0delete character from a window@@@\f1see\f3delch(3x)\f1 .\" .\" index@\f4delch()\f1, \f4mvdelch()\f1, \f4mvwdelch()\f1, \f4wdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" index@\f4mvdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" index@\f4mvwdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" index@\f4wdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" .\" links@delch.3x mvdelch.3x .\" links@delch.3x mvwdelch.3x .\" links@delch.3x wdelch.3x .\" .\" fileset_database@delch.3x CURS-ENG-A-MAN .\" .\" $Header: dbm.3x,v 76.1 95/07/05 17:27:37 ssa Exp $ .TA d .TH dbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbminit, fetch, store, delete, firstkey, nextkey, dbmclose \- database subroutines .SH SYNOPSIS .C "#include " .P .C "int dbminit(const char *file);" .P .C "datum fetch(datum key);" .P .C "int store(datum key, datum content);" .P .C "int delete(datum key);" .P .C "datum firstkey(void);" .P .C "datum nextkey(datum key);" .P .C "int dbmclose(void);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can locate a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .I dptr. Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbminit . At the time of this call, the files .IC file .dir and .IC file .pag must exist. (An empty database is created by creating zero-length .C .dir and .C .pag files.) .PP Once open, data stored under a key is accessed by .IC fetch , and data is placed under a key by .IC store . Storing data on an existing key replaces the existing data. A key (and its associated contents) is deleted by .CR delete . A linear pass through all keys in a database can be made, in (apparently) random order by using .C firstkey and .CR nextkey . .C firstkey returns the first key in the database. With any key, .C nextkey returns the next key in the database. The following code can be used to traverse the database: .IP .C "for (key = firstkey(); key.dptr != NULL; key = nextkey(key))" .PP A database can be closed by calling .C dbmclose. A currently open database must be closed before opening a new one. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .IR dptr . .SH WARNINGS The .I dbm functions provided in this library should not be confused in any way with those of a general-purpose database management system such as .SM ALLBASE/HP-UX SQL. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful data base functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C store returns an error if a disk block fills with inseparable data. .PP .C delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C firstkey and .C nextkey depends on a hashing function, not on anything interesting. .PP A .C store or .C delete during a pass through the keys by .C firstkey and .C nextkey may yield unexpected results. .SH AUTHOR .IR dbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO ndbm(3X). .\" index@\f4dbminit()\fP \- open a single database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4fetch()\fP \- access data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4store()\fP \- store data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4delete()\fP \- delete key and data under it (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4firstkey()\fP \- get first key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4nextkey()\fP \- get next key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4dbmclose()\fP \- close currently open database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@database subroutines (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" index@subroutines, database (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" .\" toc@\f3dbm(3X)\f1:\0\0\f4dbminit()\fP, \f4fetch()\fP, \f4store()\fP, \f4delete()\fP, \f4firstkey()\fP,\n\f4nextkey()\fP, \f4dbmclose()\fP@@@database subroutines .\" toc@\f4dbminit()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4fetch()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4store()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4delete()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4firstkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4nextkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4dbmclose()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" .\" links@dbm.3x dbminit.3x .\" links@dbm.3x fetch.3x .\" links@dbm.3x store.3x .\" links@dbm.3x delete.3x .\" links@dbm.3x firstkey.3x .\" links@dbm.3x nextkey.3x .\" links@dbm.3x dbmclose.3x .\" .\" fileset_database@dbm.3x PROGRAMING-MAN .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "delete_child" "Xt \- Intrinsics Methods" .SH "Name" .Na delete_child \- Composite class method called when a child is destroyed. .Nz .XX "delete_child method" .XX "methods, delete_child" .SH "Synopsis" .Sy typedef void (*XtWidgetProc)(Widget); .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the child that is to be removed from its parent's \f(CWchildren\fP array. .\" .SH "Description" The \f(CWdelete_child()\fP method is registered on the \f(CWdelete_child\fP field of the Composite class part structure. It is called by \f(CWXtDestroyWidget()\fP to remove a child from its parent's \f(CWchildren\fP array. .LP Note that the argument to the \f(CWdelete_child()\fP method is the child widget, not the composite widget that defines the method. This method must remove the specified child from its parent's \f(CWchildren\fP array, and free up any other memory that the class uses to keep track of the child. .LP The \f(CWdelete_child()\fP method is not chained. If a class does not define a \f(CWdelete_child()\fP method, it should inherit the method from its superclass by specifying \f(CWXtInheritDeleteChild\fP in the \f(CWdelete_child\fP field of its Composite class part structure. This field should not be set to \f(CWNULL\fP. .\" .SH "Usage" Most widgets simply inherit the \f(CWdelete_child()\fR method from their superclass. Some widget classes, though, create companion widgets for each of their children (the Xaw Paned widget creates the Grip widgets that separate the panes, for example) or maintain information about each child that must be freed up when the child is destroyed. These classes must provide their own \f(CWdelete_child()\fP procedures. These procedures commonly "envelop" their superclass's method by providing a procedure that does class-specific processing and explicitly invokes the superclass method. This technique allows a kind of non-automatic inheritance, and is shown in the example below. .LP Note that the Composite \f(CWinsert_child()\fR and \f(CWdelete_child()\fR methods exploit internal common data structures, so you should inherit or envelop both or neither. If you do not inherit or envelop these methods, then your methods are responsible for adding and removing the child widget from the \f(CWchildren\fP array. .\" .SH "Example" The following procedure is the \f(CWdelete_child()\fP method of the Xaw Paned widget class. Note how it destroys the Grip widget that was automatically created as a sibling of the child, and then explicitly invokes its superclass's \f(CWdelete_child()\fP method to remove the child from the Composite \f(CWchildren\fP array. See \f(CWinsert_child\fP(4) for the corresponding \f(CWinsert_child()\fP procedure. .Nd 6 .Ps static void DeleteChild(w) Widget w; { /* remove the subwidget info and destroy the grip */ if ( IsPane(w) && HasGrip(w) ) XtDestroyWidget(PaneInfo(w)->grip); /* delete the child widget in the composite children list with the */ /* superclass delete_child routine. */ (*SuperClass->composite_class.delete_child) (w); } /* DeleteChild */ .Pe In this example, \f(CWSuperClass\fP is a symbolic name for the superclass of the Paned widget class. Note that this method does \fInot\fP determine the superclass as follows: .Ps XtSuperclass(XtParent(w)) .Pe The parent of \f(CIw\fP may be a subclass of \f(CWPaned\fP, and therefore its superclass pointer will not always be the class whose method should be invoked. .SH "See Also" .na .br \s-1\fIComposite\fR\s+1\*(s3, .br \s-1\fIinsert_child\fR\s+1\*(s4. .ad .\"last line comment .\" $Header: deleteln.3x,v 76.2 95/08/01 15:07:08 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH deleteln 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME deleteln, wdeleteln \(em delete lines in a window .SH SYNOPSIS .C "#include " .P .C "int deleteln(void);" .P .C "int wdeleteln(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn deleteln and .Fn wdeleteln functions delete the line containing the cursor in the current or specified window and move all lines following the current line one line toward the cursor. The last line of the window is cleared. The cursor position does not change. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" insdelln(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn deleteln function is explicitly declared as \f3void\f1. .\" .\" toc@\f3deleteln(3x)\f1:\0\0\f4deleteln()\f1, \f4wdeleteln()\f1@@@delete lines in window .\" .\" toc@\f3deleteln()\f1:\0\0delete lines in window@@@\f1see \f3deleteln(3x)\f1 .\" toc@\f3wdeleteln()\f1:\0\0delete lines in window@@@\f1see \f3deleteln(3x)\f1 .\" .\" index@\f4deleteln()\f1, \f4wdeleteln()\f1 \- delete lines in window@@@\f3deleteln(3x)\f1 .\" index@\f4wdeleteln()\f1, \f4deleteln()\f1 \- delete lines in window@@@\f3deleteln(3x)\f1 .\" .\" links@deleteln.3x wdeleteln.3x .\" .\" fileset_database@deleteln.3x CURS-ENG-A-MAN .\" .\" $Header: delscreen.3x,v 76.2 95/08/01 15:09:35 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH delscreen 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME delscreen \(em free storage associated with a screen .SH SYNOPSIS .C "#include " .P .C "void delscreen(SCREEN *\f2sp\fP);" .SH DESCRIPTION The .Fn delscreen function frees storage associated with the \f3SCREEN\f1 pointed to by \f2sp\f1. .SH "RETURN VALUE" The .Fn delscreen function does not return a value. .SH ERRORS No errors are defined. .SH "SEE ALSO" endwin(), initscr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3delscreen(3x)\f1:\0\0\f4delscreen()\f1@@@free storage associated with a screen .\" .\" index@\f4delscreen()\f1 \- free storage associated with a screen@@@\f3delscreen(3x)\f1 .\" index@\f1storage associated with a screen@@@\f3delscreen(3x)\f1 .\" index@\f1screen, free storage associated with a screen@@@\f3delscreen(3x)\f1 .\" .\" fileset_database@delscreen.3x CURS-ENG-A-MAN .\" .\" $Header: delwin.3x,v 76.2 95/08/01 15:12:41 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH delwin 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME delwin \(em delete a window .SH SYNOPSIS .C "#include " .P .C "int delwin(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn delwin function deletes \f2win\fP, freeing all memory associated with it. The application must delete subwindows before deleting the main window. .SH "RETURN VALUE" Upon successful completion, .Fn delwin returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" derwin(), dupwin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" toc@\f3delwin(3x)\f1:\0\0\f4delwin()\f1@@@delete a window .\" .\" index@\f4delwin()\f1 \- delete a window@@@\f3delwin(3x)\f1 .\" index@\f1delete a window@@@\f3delwin(3x)\f1 .\" index@\f1window, delete@@@\f3delwin(3x)\f1 .\" .\" fileset_database@delwin.3x CURS-ENG-A-MAN .\" .\" $Header: derwin.3x,v 76.2 95/08/01 15:13:55 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH derwin 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME derwin\(em relative window creation function .SH SYNOPSIS .C "#include " .P .C "WINDOW *derwin(WINDOW *\f2orig\fP, int \f2nlines\fP, int \f2ncols\fP, int \f2begin_y\fP," .C " int \f2begin_x\fP);" .SH DESCRIPTION .P The .Fn derwin function creates a new window with \f2nlines\f1 lines and \f2ncols\f1 columns, positioned so that the origin is at (\f2begin_y\f1, \f2begin_x\f1) relative to the origin of the window \f2orig\f1. If any part of the new window is outside \f2orig\fP, the function fails and the window is not created. .SH "RETURN VALUE" Upon successful completion, these functions return a pointer to the new window. Otherwise, they return a null pointer. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Before performing the first refresh of a subwindow, portable applications should call .Fn touchwin or .Fn touchline on the parent window. .P Each window maintains internal descriptions of the screen image and status. The screen image is shared among all windows in the window hierarchy. Refresh operations rely on information on what has changed within a window, which is private to each window. Refreshing a window, when updates were made to a different window, may fail to perform needed updates because the windows do not share this information. .P .SH "SEE ALSO" delwin(), newwin(), is_linetouched(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3derwin(3x)\f1:\0\0\f4delwin()\f1@@@relative window creation function .\" .\" index@\f4derwin()\f1 \- relative window creation function@@@\f3derwin(3x)\f1 .\" index@\f1relative window creation function@@@\f3derwin(3x)\f1 .\" index@\f1window creation function@@@\f3derwin(3x)\f1 .\" index@\f1creation function, relative window@@@\f3derwin(3x)\f1 .\" index@\f1function, relative window creation@@@\f3derwin(3x)\f1 .\" .\" fileset_database@derwin.3x CURS-ENG-A-MAN .\" .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "destroy" "Xt \- Intrinsics Methods" .SH "Name" .Na destroy \- Object class method called when a widget is destroyed. .Nz .XX "destroy method" .XX "methods, destroy" .SH "Synopsis" .Sy typedef void (*XtWidgetProc)(Widget); .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that is being destroyed. .\" .SH "Description" The \f(CWdestroy()\fP method is registered on the \f(CWdestroy\fP field of the Object, RectObj, or Core class part structures. It is invoked by \f(CWXtDestroyWidget()\fP as part of the destruction process when any widget or object is destroyed, and should deallocate any memory or resources associated with the part of the widget instance structure specific to this class. It does not free the widget instance structure itself. .LP The \f(CWdestroy()\fP methods of a widget class and all its superclasses are called in subclass-to-superclass order. (Note that this is the reverse of the usual superclass-to-subclass chaining sequence.) The \f(CWdestroy()\fP method of a widget class should deallocate memory or other resources that were explicitly allocated by this class. Any resource that was obtained from the resource database or passed in an argument list was not created by the widget and therefore should not be destroyed by it (unless the widget allocated memory to copy the resource value, in which case the memory must be freed). .LP To reclaim memory, at least the following deallocations should be performed: .IP \(bu 3n Call \f(CWXtFree()\fR on dynamic storage allocated with \f(CWXtCalloc()\fR, \f(CWXtMalloc()\fR, etc. .IP \(bu Call \f(CWXFreePixmap()\fR on pixmaps created with direct Xlib calls. .IP \(bu Call \f(CWXtReleaseGC()\fR on GCs allocated with \f(CWXtGetGC()\fR. .IP \(bu Call \f(CWXFreeGC()\fR on GCs allocated with direct Xlib calls. .IP \(bu Call \f(CWXtRemoveEventHandler()\fR on event handlers added with \f(CWXtAddEventHandler()\fR. .IP \(bu Call \f(CWXtRemoveTimeOut()\fR on timers created with \f(CWXtAppAddTimeOut()\fR. .IP \(bu Call \f(CWXtDestroyWidget()\fR for each child if the widget has children and is not a subclass of \f(CWcompositeWidgetClass\fR. .LP The \f(CWdestroy()\fP method is chained, so it cannot be inherited. If a widget does not need to deallocate any storage, the \f(CWdestroy\fP field in its widget class record should be \f(CWNULL\fR. .LP See \f(CWXtDestroyWidget\fP(1) for details on the process of widget destruction. .\" .SH "Usage" In general, a \f(CWdestroy()\fP method will deallocate any resources allocated in the \f(CWinitialize()\fP and \f(CWset_values()\fP methods. This often includes GCs, pixmaps, and any copies that were made of string resources. .\" .SH "Example" The following procedure is the \f(CWdestroy()\fP method of the Xaw Label widget. It frees the copy it made of its label string resource, deallocates two shared GCs, and frees the stipple pixmap it used to draw itself in insensitive mode. .Ps static void Destroy(w) Widget w; { LabelWidget lw = (LabelWidget)w; XtFree( lw->label.label ); XtReleaseGC( w, lw->label.normal_GC ); XtReleaseGC( w, lw->label.gray_GC); XmuReleaseStippledPixmap( XtScreen(w), lw->label.stipple ); } .Pe .\" .SH "See Also" .na \s-1\fIXtDestroyWidget\fR\s+1\*(s1, .br \s-1\fICore\fR\s+1\*(s3, .br \s-1\fIConstraint destroy\fR\s+1\*(s4, \s-1\fIinitialize\fR\s+1\*(s4, \s-1\fIset_values\fR\s+1\*(s4. .ad .\"last line comment .\" $Header: devnm.3,v 72.4 94/09/13 16:41:12 ssa Exp $ .TA d .TH devnm 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME devnm \- map device \s-1ID\s0 to file path .SH SYNOPSIS .nf .C "#include " .PP .C "int devnm (" .PD 0 .IP .C "mode_t devtype," .C "dev_t devid," .C "char *path," .C "size_t pathlen," .C "int cache" .C ); .fi .PD .SH DESCRIPTION Given a device type, a device .SM ID, and a string in which to return the result, .C devnm() maps the type and .SM ID to a block or character special file (device file) name by searching .CR /dev . It returns in .I path the full path name of the first special file encountered with a matching device type and .SM ID. It searches .C /dev and all its subdirectories recursively in unspecified order. .PP The parameters are: .RS .TP 10 .I devtype One of the file type values .C S_IFBLK or .C S_IFCHR documented in .IR stat (5). Bits other than those in the .C S_IFMT set are ignored. Hence the value can be, for example, an .C st_mode value returned by .C stat() (see .IR stat (2)). .TP .I devid A device .SM ID (the combined major and minor numbers) such as returned by .C stat() in the .C st_dev or .C st_rdev field. .TP .I path Pointer to the buffer in which to return the path name result. .TP .I pathlen Tells the available length of the .I path string, including the .SM NUL terminator character. If .I path is too short to hold the full path name, only the first .I pathlen\c \(mi1 characters are returned in a null-terminated string, and the return value is altered (see below). .TP .I cache A flag that tells .C devnm() whether to save file information in .CR malloc() 'd memory, and later, whether to use that saved information instead of searching .C /dev again. A subsequent call with .I cache non-zero can be much faster, especially if .C /dev is a large tree. However, the first call with .I cache true might be slower because .C devnm() must read all of the .C /dev tree once to create the cache, rather than returning immediately upon finding a matching file. Any call with .I cache set to zero ignores the cache, if any, and reads the directory. .IP To allow for possible future enhancements, .I cache should be restricted to the values 0 and 1. .RE .PP There is no way to tell .C devnm() to free its cached memory. .PP .C devnm() ignores unreadable directories and files for which .C stat() fails. .SH RETURN VALUE .C devnm() returns one of the following values: .RS .TP 8 .B \00 Successful. The result is in .IR path . .TP .B \(mi1 .C ftw() failed. .C errno contains the value returned from .CR ftw() . .I path might be altered if .I cache is set. If .I cache was set for the first time, .C devnm() freed any memory allocated by the current call. .TP .B \(mi2 No matching special file was found. .C errno is undefined. .I path is unaltered. .TP .B \(mi3 A matching special file was found, but the name was truncated to fit in .IR path . .C errno is undefined. .RE .PP If .C malloc() fails, .C devnm() silently abandons the attempt to do caching in the current or any later call with .I cache true, and frees any memory allocated by the current call. .SH AUTHOR .C devnm() was created by .SM HP. .SH SEE ALSO devnm(1M), stat(2), ftw(3), malloc(3), ttyname(3), stat(5). .\" .\" toc@\f3devnm(3)\f1:\0\0\f4devnm()\f1@@@map device \s-1ID\s0 to file path .\" .\" index@\f4devnm()\f1 \- map device \s-1ID\s0 to file path@@@\f3devnm(3)\f1 .\" index@map device \s-1ID\s0 to file path@@@\f3devnm(3)\f1 .\" index@device \s-1ID\s0 to file path, map@@@\f3devnm(3)\f1 .\" index@\s-1ID\s0 to file path, map device@@@\f3devnm(3)\f1 .\" index@file path, map device \s-1ID\s0 to@@@\f3devnm(3)\f1 .\" index@path, map device \s-1ID\s0 to file@@@\f3devnm(3)\f1 .\" .\" fileset_database@devnm.3 PROGRAMING-MAN .\" $Header: dial.3c,v 72.5 94/11/02 11:55:44 ssa Exp $ .TA d .TH dial 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dial(), undial() \- establish an outgoing terminal line connection .SH SYNOPSIS .C "#include " .PP .C "int dial(CALL call);" .PP .C "void undial(int fd);" .SH DESCRIPTION The .CR dial() function returns a file descriptor for a terminal line open for read/write. The argument to .CR dial() is a .CR CALL structure (defined in the .RC < dial.h > header file). .PP When finished with the terminal line, the calling program must invoke .CR undial() to release the semaphore that has been set during the allocation of the terminal device. .PP The definition of .CR CALL in the .RC < dial.h > header file is: .PP .RS .nf .C "typedef struct {" .RS .C "struct termio *attr; /* pointer to termio attribute struct */" .C "int baud; /* transmission data rate */" .C "int speed; /* 212A modem: low=300, high=1200 */" .C "char *line; /* device name for out-going line */" .C "char *telno; /* pointer to tel-no digits string */ .C "int modem; /* specify modem control for direct lines */" .C "char *device; /* Will hold the name of the device used" .C " to make a connection */" .C "int dev_len; /* The length of the device used to" .C " make connection */" .RE .C "} CALL;" .fi .RE .PP .CR CALL elements are as follows: .RS .TP 12 .I speed Intended only for use with an outgoing dialed call, in which case its value should be either 300 or 1200 to identify the 113A modem, or the high- or low-speed setting on the 212A modem. Note that the 113A modem or the low-speed setting of the 212A modem transmits at any rate between 0 and 300 bits per second. However, the high-speed setting of the 212A modem transmits and receives at 1200 bits per second only. .TP .I baud Desired transmission baud rate. For example, one might set .I baud to 110 and .I speed to 300 (or 1200). However, if .I speed is set to 1200, .I baud must be set to high (1200). .TP .I line If the desired terminal line is a direct line, a string pointer to its device name should be placed in the .I line element in the .CR CALL structure. Legal values for such terminal device names are kept in the .CR Devices file. In this case, the value of the .I baud element need not be specified as it will be determined from the .CR Devices file. .TP .I telno A pointer to a character string representing the telephone number to be dialed. Such numbers can consist only of symbols described below. The termination symbol is supplied by the .CR dial() function, and should not be included in the .I telno string passed to .CR dial() in the .CR CALL structure. .IP .RS .RS .TS box; lB s lw l. .vs +1p Permissible Codes _ 0-9 dial 0-9 _ * or : dial * _ # or ; dial # _ - 4-second delay for second dial tone _ e or < end-of-number _ w or = wait for secondary dial tone _ f flash off hook for 1 second .TE .sp .5 .RE .RE .TP 12 .I modem Specifies modem control for direct lines. Set to non-zero if modem control is required. .TP .I attr Pointer to a .CR termio structure, as defined in the .RC < termio.h > header file. A NULL value for this pointer element can be passed to the .CR dial() function, but if such a structure is included, the elements specified in it are set for the outgoing terminal line before the connection is established. This is often important for certain attributes such as parity and baud rate. .TP .I device Holds the device name that establishes the connection. .TP .I dev_len Length of the device name that is copied into the array device. .SH RETURN VALUE On failure, a negative value indicating the reason for the failure is returned. Mnemonics for these negative indices as listed here are defined in the .RC < dial.h > header file. .PP .RS .nf .C "INTRPT -1 /* interrupt occurred */" .C "D_HUNG -2 /* dialer hung (no return from write) */" .C "NO_ANS -3 /* no answer within 10 seconds */" .C "ILL_BD -4 /* illegal baud-rate */" .C "A_PROB -5 /* automatic call unit (acu) problem (open() failure) */" .C "L_PROB -6 /* line problem (open() failure) */" .C "NO_Ldv -7 /* can't open LDEVS file */" .C "DV_NT_A -8 /* requested device not available */" .C "DV_NT_K -9 /* requested device not known */" .C "NO_BD_A -10 /* no device available at requested baud */" .C "NO_BD_K -11 /* no device known at requested baud */" .fi .RE .SH WARNINGS Including the .RC < dial.h > header file automatically includes the .RC < termio.h > header file. .PP The above routine uses .RC < stdio.h >, which causes unexpected increases in the size of programs that otherwise do not use standard I/O. .PP The .CR dial() function will modify the values of some of the fields of the the .CR CALL structure so if .CR dial() , is reinvoked, reinitialize the values of the .CR CALL structure. .SH FILES .C /etc/uucp/Devices .SH SEE ALSO uucp(1), alarm(2), read(2), write(2), termio(7). .PP .IR UUCP tutorial in .IR "Remote Access User's Guide" . .\" .\" index@\f4dial()\f1 \- establish an out-bound terminal line connection@@@\f3dial(3C)\f1 .\" index@\f4undial()\f1\- establish an out-bound terminal line connection@@@\f3dial(3C)\f1 .\" index@\f1establish an out-bound terminal line connection@@@\f3dial(3C)\f1 .\" index@\f1out-bound terminal line connection, establish an@@@\f3dial(3C)\f1 .\" index@\f1terminal line connection, establish an out-bound@@@\f3dial(3C)\f1 .\" index@\f1line connection, establish an out-bound terminal@@@\f3dial(3C)\f1 .\" index@\f1connection, establish an out-bound terminal line@@@\f3dial(3C)\f1 .\" .\" toc@\f3dial(3C)\f1:\0\0\f4dial()\fP, \f4undial()\f1@@@establish an outgoing terminal line connection\f1 .\" toc@\f4undial()\f1:\0\0establish an outgoing terminal line connection@@@\f1`see \f3dial(3C)\f1 .\" .\" links@dial.3c undial.3c .\" $Header: ctime.3c,v 76.1 95/07/05 17:27:14 ssa Exp $ .TA c .TH ctime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctime(\|), ctime_r(\|), localtime(\|), localtime_r(\|), gmtime(\|), gmtime_r(\|), mktime(\|), difftime(\|), asctime(\|), asctime_r(\|), timezone(\|), daylight(\|), tzname(\|), tzset(\|) \- convert date and time to string .SH SYNOPSIS .nf .C "#include " .PP .C "char *asctime(const struct tm *timeptr);" .PP .C "int asctime_r(const struct tm *timeptr, char *buffer, int buflen);" .PP .C "char *ctime(const time_t *timer);" .PP .C "int ctime_r(const time_t *timer, char *buffer, int buflen);" .PP .C "double difftime(time_t time1, time_t time0);" .PP .C "struct tm *gmtime(const time_t *timer);" .PP .C "int gmtime_r(const time_t *timer, struct tm *result);" .PP .C "struct tm *localtime(const time_t *timer);" .PP .C "int localtime_r(const time_t *timer, struct tm *result);" .PP .C "time_t mktime(struct tm *timeptr);" .PP .C "extern long timezone;" .PP .C "extern int daylight;" .PP .C "extern char *tzname[2];" .PP .C "void tzset(void);" .fi .SH DESCRIPTION .TP 18 .C asctime() Convert the broken-down time contained in the structure pointed to by .I timeptr and return a pointer to a 26-character string in the form: .RS .IP .C "Sun Sep 16 01:03:52 1973\en\e0" .RE .IP All the fields have constant width. .TP .C asctime_r() is identical to .CR asctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C ctime() Convert the calendar time pointed to by .IR timer , representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: .RS .IP .C asctime(localtime(timer)) .RE .TP .C ctime_r() is identical to .CR ctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C gmtime() Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. .C gmtime() returns a pointer to the .C tm structure described below. .TP .C gmtime_r() is identical to .CR gmtime() , except that .C gmtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C localtime() Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA\c), according to the contents of the TZ environment variable (see Environment Variables below). .C localtime() returns a pointer to the .C tm structure described below. .TP .C localtime_r() is identical to .CR localtime() , except that .C localtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C difftime() Return the difference in seconds between two calendar times: .IR "time1 \(mi time0" . .TP .C mktime() Convert the broken-down time (expressed as local time) in the structure pointed to by .I timeptr into a calendar time value with the same encoding as that of the values returned by .IR time (2). The original values of the .C tm_wday and .C tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below. .IP A positive or zero value for .C tm_isdst causes .C mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for .C tm_isdst causes .C mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time. .IP Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of .C tm_mday is not set until .C tm_mon and .C tm_year are determined. .C mktime() returns the specified calendar time encoded as a value of type .CR time_t . .IP If the calendar time cannot be represented, the function returns the value .RC ( time_t )\|\(em\|1 and sets .C errno to .CR ERANGE . Note the value .RC ( time_t )\|\(em\|1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and .C errno to reliably detect an error condition. .TP .C tzset() Sets the values of the external variables .IR timezone , .IR daylight , and .I tzname according to the contents of the .C TZ environment variable (independent of any time value). The functions .CR localtime() , .CR mktime() , .CR ctime() , .CR asctime() , and .C strftime() (see .IR strftime (3C)) call .C tzset() and use the values returned in the external variables described below for their operations. .C tzset() can also be called directly by the user. .PP The .RC < time.h > header file contains declarations of all relevant functions and externals. It also contains the .C tm structure, which includes the following members: .RS .PP .nf .ift .ft 4 .ps +1 int tm_sec; /* seconds after the minute - [0,61] */ int tm_min; /* minutes after the hour - [0,59] */ int tm_hour; /* hours - [0,23] */ int tm_mday; /* day of month - [1,31] */ int tm_mon; /* month of year - [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday - [0,6] */ int tm_yday; /* days since January 1 - [0,365] */ int tm_isdst; /* daylight savings time flag */ .ift .ft .ps .fi .PP The value of .C tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available. .RE .PP The external variable .C timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), .C timezone is 5\(**60\(**60). The external variable .C daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable .C tzname[2] contains the local standard and local summer time zone abbreviations as specified by the .C TZ environment variable. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .SS Environment Variables The .C tzset() function uses the contents of .C TZ to set the values of the external variables .CR timezone , .C daylight , and .CR tzname . .C TZ also determines the time zone name substituted for the .C %Z and .C %z directives and the time zone adjustments performed by .CR localtime() , .CR mktime() , and .CR ctime() . Two methods for specifying a time zone within .C TZ are described in .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH "RETURN VALUE" .PP For .C asctime_r() and .C ctime_r(), if the buffer is of insufficient length, -1 is returned. For .C asctime_r(), ctime_r(), gmtime_r(), and .C localtime_r(), if the operation is successful, 0 is returned. .SH WARNINGS The return values for .CR asctime() , .CR ctime() , .CR gmtime() , and .CR localtime() point to static data whose contents is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() are MT-Safe and should be used instead. .PP Users of .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .PP The range of .C tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by .IR time (2) and passed as the .I timer argument does not include accumulated leap seconds. The .C tm structure generated by .C localtime() and .C gmtime() will never reflect any leap seconds. Upon successful completion, .C mktime() forces the value of the .C tm_sec component to the range [0,59]. .PP .CR ctime() , .CR ctime_r() , .CR asctime() , and .CR asctime_r() are considered obsolescent and may be removed in a future release. Use of .IR strftime (3C) is recommended instead. .SH AUTHOR .C ctime() was developed by AT&T and HP. .SH SEE ALSO time(2), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR ctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR asctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR daylight ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR difftime() ": AES, SVID3, XPG4, ANSI C" .PP .CR gmtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR localtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mktime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR timezone ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR tzname ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tzset() ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4asctime()\fP, \f4asctime_r()\f1 \- convert \f3tm\f1 structure date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4ctime()\fP, \f4ctime_r()\f1 \- convert \f4clock()\fP date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4daylight()\fP \- Daylight Savings Time flag@@@\f3ctime(3C)\f1 .\" index@\f4gmtime()\fP, \f4gmtime_r()\fP \- convert date and time to Greenwich Mean Time@@@\f3ctime(3C)\f1 .\" index@\f4localtime()\fP, \f4localtime_r()\fP \- convert date and time to local timezone@@@\f3ctime(3C)\f1 .\" index@\f4timezone()\fP \- difference between \s-1UCT\s+1 and local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzname()\fP \- name of local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzset()\fP \- initialize \f4timezone()\fP, \f4daylight()\fP, and \f4tzname()\fP using \s-1TZ\s+1 variable@@@\f3ctime(3C)\f1 .\" index@\f4mktime()\fP \- convert time into calendar time value@@@\f3ctime(3C)\f1 .\" index@\f4difftime()\fP \- difference between two calendar time values@@@\f3ctime(3C)\f1 .\" index@convert date and time to string@@@\f3ctime(3C)\f1 .\" index@string, convert date and time to@@@\f3ctime(3C)\f1 .\" index@date and time, convert to string@@@\f3ctime(3C)\f1 .\" index@time and date, convert to string@@@\f3ctime(3C)\f1 .\" .\" toc@\f3ctime(3C)\f1:\0\0\f4ctime()\fP, \f4ctime_r()\fP, \f4localtime()\fP, \f4localtime_r()\fP, \f4difftime()\f1, \f4 mktime()\f1, \n\f4gmtime()\fP, \f4gmtime_r()\fP,\f4asctime()\fP, \f4asctime_r()\fP, \f4timezone()\fP, \f4daylight()\fP, \f4tzname()\fP,\n\f4tzset()\f1@@@convert date and time to string .\" toc@\f4ctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4ctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4timezone()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4daylight()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzname()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzset()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4difftime()\fP:\0\0difference between calendar times@@@see \f3ctime(3C)\f1 .\" toc@\f4mktime()\fP:\0\0create calendar time value@@@see \f3ctime(3C)\f1 .\" .\" links@ctime.3c ctime_r.3c .\" links@ctime.3c localtime.3c .\" links@ctime.3c localtime_r.3c .\" links@ctime.3c gmtime.3c .\" links@ctime.3c gmtime_r.3c .\" links@ctime.3c asctime.3c .\" links@ctime.3c asctime_r.3c .\" links@ctime.3c timezone.3c .\" links@ctime.3c daylight.3c .\" links@ctime.3c tzname.3c .\" links@ctime.3c tzset.3c .\" links@ctime.3c difftime.3c .\" links@ctime.3c mktime.3c .\" .\" fileset_database@ctime.3c PROGRAMING-MAN .\" $Header: directory.3c,v 76.1 95/07/05 17:28:05 ssa Exp $ .TA d .TH directory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME opendir(\|), readdir(\|), readdir_r(\|), telldir(\|), seekdir(\|), rewinddir(\|), closedir(\|) \- directory operations .SH SYNOPSIS .C "#include " .PP .C "DIR *opendir(const char *dirname);" .PP .C "struct dirent *readdir(DIR *dirp);" .PP .C "int readdir_r(DIR *dirp, struct dirent *result);" .PP .C "long int telldir(DIR *dirp);" .PP .C "void seekdir(DIR *dirp, long int loc);" .PP .C "void rewinddir(DIR *dirp);" .PP .C "int closedir(DIR *dirp);" .SH DESCRIPTION This library package provides functions that allow programs to read directory entries without having to know the actual directory format associated with the file system. Because these functions allow programs to be used portably on file systems with different directory formats, this is the recommended way to read directory entries. .TP 15 .CR opendir() opens the directory .I dirname and associates a directory stream with it. .CR opendir() returns a pointer used to identify the directory stream in subsequent operations. .CR opendir() uses .IR malloc (3C) to allocate memory. .TP .CR readdir() returns a pointer to the next directory entry. It returns a .SM NULL pointer upon reaching the end of the directory or detecting an invalid .CR seekdir() operation. See .IR dirent (5) for a description of the fields available in a directory entry. .TP .CR readdir_r() expects to be passed the address of a .CR "struct dirent" and will store the result at the supplied location. .TP .CR telldir() returns the current location (encoded) associated with the directory stream to which .IR dirp refers. .TP .CR seekdir() sets the position of the next .CR readdir() operation on the directory stream to which .IR dirp refers. The .IR loc argument is a location within the directory stream obtained from .CR telldir() . The position of the directory stream is restored to where it was when .CR telldir() returned that .I loc value. Values returned by .CR telldir() are valid only while the .CR DIR pointer from which they are derived remains open. If the directory stream is closed and then reopened, the .CR telldir() value might be invalid. .TP .CR rewinddir() resets the position of the directory stream to which .IR dirp refers to the beginning of the directory. It also causes the directory stream to refer to the current state of the corresponding directory, as a call to .CR opendir() would have done. .TP .CR closedir() closes the named directory stream, then frees the structure associated with the .CR DIR pointer. .SH RETURN VALUE .TP 15 .CR opendir() , upon successful completion, returns a pointer to an object of type .CR DIR referring to an open directory stream. Otherwise, it returns a .SM NULL pointer and sets the global variable .CR errno to indicate the error. .TP .CR readdir() , upon successful completion, returns a pointer to an object of type .CR struct dirent describing a directory entry. Upon reaching the end of the directory, .CR readdir() returns a .SM NULL pointer and does not change the value of .CR errno . Otherwise, it returns a .SM NULL pointer and sets .CR errno to indicate the error. .TP .CR readdir_r() , upon successful completion, returns a 0. Upon reaching the end of directory or encountering an error, it returns a -1 and sets .CR errno to indicate the error. .TP .CR telldir() , upon successful completion, returns a long value indicating the current position in the directory. Otherwise it returns .CR \-1 and sets .CR errno to indicate the error. .TP .CR seekdir() does not return any value, but if an error is encountered, .CR errno is set to indicate the error. .TP .CR closedir() , upon successful completion, returns a value of .CR 0 . Otherwise, it returns a value of .CR \-1 and sets .CR errno to indicate the error. .SH ERRORS .CR opendir() fails if any of the following conditions are encountered: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of .IR dirname , or read permission is denied for .IR dirname . .TP .SM [EFAULT] .I dirname points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the path name. .TP .SM [EMFILE] Too many open file descriptors are currently open for the calling process. .TP .SM [ENAMETOOLONG] A component of .IR dirname exceeds .CR PATH_MAX bytes, or the entire length of .IR dirname exceeds .CR PATH_MAX \(mi 1 bytes while .CR _POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] Too many open file descriptors are currently open on the system. .TP .SM [ENOENT] A component of .I dirname does not exist. .TP .SM [ENOMEM] .CR malloc() failed to provide sufficient memory to process the directory. .TP .SM [ENOTDIR] A component of .I dirname is not a directory. .TP .SM [ENOENT] The .IR dirname argument points to an empty string. .RE .PP .CR readdir() " or " readdir_r() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] The directory stream to which .IR dirp refers is not located at a valid directory entry. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR telldir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR seekdir() might fail if the following condition is encountered: .RS .TP 20 .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR closedir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP 20 .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR rewinddir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .SH EXAMPLES The following code searches the current directory for an entry .IR name : .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 DIR *dirp; struct dirent *dp; dirp = opendir("."); while ((dp = readdir(dirp)) != NULL) { if (strcmp(dp->d_name, name) == 0) { (void) closedir(dirp); return FOUND; } } (void) closedir(dirp); return NOT_FOUND; .ft .ps .fi .RE .SH WARNINGS .CR readdir() and .CR getdirentries() (see .IR getdirentries (2) are the only ways to access remote .SM NFS directories. Attempting to read a remote directory via .SM NFS by using .CR read() returns .CR \-1 and sets .CR errno to .SM EISDIR (see .IR read (2)). .PP .CR readdir() is unsafe in multi-thread applications. .CR readdir_r() is MT-Safe and should be used instead. Users of .CR readdir_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH APPLICATION USAGE The header file required for these functions and the type of the return value from .CR readdir() has been changed for compatibility with System V Release 3 and the .IR "X/Open Portability Guide" . See .IR ndir (5) for a description of the header file .RC < ndir.h >, which is provided to allow existing .SM HP-UX applications to compile unmodified. .PP New applications should use the .RC < dirent.h > header file for portability to System V and X/Open systems. .SH AUTHOR .CR directory was developed by AT&T, HP, and the University of California, Berkeley. .SH SEE ALSO close(2), getdirentries(2), lseek(2), open(2), read(2), dir(4), dirent(5), ndir(5). .SH STANDARDS CONFORMANCE .CR closedir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR opendir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR readdir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR rewinddir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR seekdir() ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR telldir() ": AES, XPG2, XPG3, XPG4" .\" .\" index@\f4opendir()\f1 \- open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f4readdir()\f1 \- get pointer to current entry in open directory@@@\f3directory(3C)\f1 .\" index@\f4telldir()\f1 \- get current location of named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4seekdir()\f1 \- set position of next \f4readdir()\f1 operation on named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4rewinddir()\f1 \- reset position of named \f2directory stream\f1 to beginning of directory@@@\f3directory(3C)\f1 .\" index@\f4closedir()\f1 \- close a currently open directory@@@\f3directory(3C)\f1 .\" index@open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f2directory stream\f1, directory and associated, open for access@@@\f3directory(3C)\f1 .\" index@open, access, or close a directory@@@\f3directory(3C)\f1 .\" index@close, access, or open a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@directory: access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" .\" toc@\f3directory(3C)\f1:\0\0\f4directory()\f1, \f4opendir()\f1, \f4readdir()\f1, \f4telldir()\f1, \f4seekdir()\f1, \f4rewinddir()\f1,\n\f4closedir()\f1@@@directory operations .\" toc@\f4opendir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4readdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4telldir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4seekdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4rewinddir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4closedir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" .\" links@directory.3c opendir.3c .\" links@directory.3c readdir.3c .\" links@directory.3c readdir_r.3c .\" links@directory.3c telldir.3c .\" links@directory.3c seekdir.3c .\" links@directory.3c rewinddir.3c .\" links@directory.3c closedir.3c .\" $Header: basename.3c,v 72.3 94/10/17 16:27:52 ssa Exp $ .TA b .TH basename 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME basename(\|), dirname(\|) \- extract components of a path name .SH SYNOPSIS .C "#include " .PP .C "char *basename(char *path);" .PP .C "char *dirname(char *path);" .SH DESCRIPTION .C basename() takes the path name pointed to by .I path and returns a pointer to the final component of the path name, deleting any trailing '/' characters. If the string consists entirely of '/' characters, .C basename() returns a pointer to the string "/". If .I path is a null pointer or points to the empty string, .C basename() returns a pointer to the string ".". .PP .C dirname() takes the path name pointed to by .I path and returns a pointer to a string that is a path name of the parent directory of that file. If .I path is a null pointer, points to the empty string, or does not contain a '/' character, then .C dirname() returns a pointer to the string ".". .SH RETURN VALUE .C basename() returns a pointer to the final component of .IR path . .PP .C dirname() returns a pointer to a string that is the parent directory of .IR path . .SH EXAMPLES The following code fragment calls .C basename() and .CR dirname() . .nf .IP .C #include .IP .C char *path="/usr/local/bin/foo"; .C char *base, dir; .IP .C base=basename(path); .C dir=dirname(path); .fi .SH WARNINGS The return value points to static data whose content is overwritten by each call. .SH AUTHOR .C basename() and .C dirname() were developed by HP. .SH SEE ALSO basename(1). .SH STANDARDS CONFORMANCE .nf .CR basename() ": XPG4.2 .CR dirname() ": XPG4.2 .fi .\" .\" toc@\f3basename(3C)\f1:\0\0\f4basename()\f1, \f4dirname()\f1@@@extract components of a path name .\" toc@\f4dirname()\f1:\0\0return path name of parent directory@@@\f1see \f3basename(3C)\f1 .\" .\" index@\f4basename()\f1 \- return final component of path name@@@\f3basename(3C)\f1 .\" index@\f4dirname()\f1 \- return path name of parent directory@@@\f3basename(3C)\f1 .\" index@\f1path name of parent directory@@@\f3basename(3C)\f1 .\" index@\f1path name component@@@\f3basename(3C)\f1 .\" .\" links@basename.3c dirname.3c .\" .\" fileset_database@basename.3c PROGRAMING-MAN .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "display_accelerator" "Xt \- Intrinsics Methods" .SH "Name" .Na display_accelerator \- Core method to display current accelerators. .Nz .XN "accelerators: (see also methods, display_accelerator)" .XX "methods, display_accelerator" .XX "display: display_accelerator method" .SH "Synopsis" .Sy typedef void (*XtStringProc)(Widget, String); .As Widget \f(CIw\fP; String \f(CIstring\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the source widget that supplied the accelerators. .IP \f(CIstring\fP 1i Provides the string representation of the accelerators that were installed. .SH "Description" The Core \f(CWdisplay_accelerator()\fR method is registered on the \f(CWdisplay_accelerator\fP field of the Core class part structure, and is called when the application installs a widget's accelerators with \f(CWXtInstallAccelerators()\fP or \f(CWXtInstallAllAccelerators()\fP. .LP The argument \f(CIw\fP is the widget instance that has had its accelerators installed, and \f(CIstring\fP is a string representation of the widget's accelerator table. Some widget classes will want to display themselves differently when accelerators are installed so that the user is aware that they are available. (Menu buttons that display their keyboard equivalents are a good example.) .LP The method is passed a string version of the current accelerator table, in canonical form. This form may differ from the original source of the accelerator table itself. .LP The \f(CWdisplay_accelerator()\fP method is not chained. A widget class can inherit its superclass's \f(CWdisplay_accelerator()\fP method by specifying \f(CWXtInheritDisplayAccelerator\fP in its Core \f(CWdisplay_accelerator\fP field. A widget that does not wish to display any accelerators may set this field to \f(CWNULL\fP. .\" .SH "Usage" The translation table syntax is not particularly easy for a user to read or particularly easy for a widget to convert into a simpler form, so a widget class may prefer to define a resource which is the string that should be displayed when the accelerator is installed. That way the application programmer can specify both the accelerator and the representation of the accelerator that the user will see. .LP None of the Intrinsics or Xaw widget classes define a \f(CWdisplay_accelerator()\fP method. .\" .SH "See Also" .na \s-1\fIXtInstallAccelerators\fR\s+1\*(s1. .ad .\"last line comment .\" $Header: div.3c,v 72.4 94/11/14 15:27:43 ssa Exp $ .TA d .TH div 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME div(\|), ldiv(\|) \- integer division and remainder .SH SYNOPSIS .C "#include " .PP .C "div_t div(int numer, int denom);" .PP .C "ldiv_t ldiv(long int numer, long int denom);" .SH DESCRIPTION .TP 15 .C div() Computes the quotient and remainder of the division of the numerator .I numer by the denominator .IR denom . If the division is inexact, the sign of the resulting quotient is that of the algebraic quotient, and the magnitude of the resulting quotient is the largest integer less than the magnitude of the algebraic quotient. If the result can be represented, the result is returned in a structure of type .C div_t (defined in .RC < stdlib.h >) having members .I quot and .I rem for the quotient and remainder respectively. Both members have type .C int and values such that .IR "quot \(mu denom + rem = numer" . If the result cannot be represented, the behavior is undefined. .TP .C ldiv() Similar to .CR div() , except that the arguments each have type .C long int and the result is returned in a structure of type .C ldiv_t (defined in .RC < stdlib.h >) having .C long int members .I quot and .I rem for the quotient and remainder respectively. .SH WARNINGS Behavior is undefined if .I denom is zero. .SH SEE ALSO floor(3M). .SH STANDARDS CONFORMANCE .CR div() ": AES, SVID3, XPG4, ANSI C" .PP .CR ldiv() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4div()\fP, \f4ldiv()\fP \- integer division and remainder@@@\f3div(3C)\f1 .\" index@\f4ldiv()\fP \- long integer division and remainder@@@\f3div(3C)\f1 .\" index@integer division and remainder@@@\f3div(3C)\f1 .\" index@division and remainder, integer@@@\f3div(3C)\f1 .\" index@remainder, integer division and@@@\f3div(3C)\f1 .\" .\" toc@\f3div(3C)\f1:\0\0\f4div()\fP, \f4ldiv()\fP@@@integer division and remainder .\" toc@\f4ldiv()\fP: long integer division and remainder@@@see \f3div(3C)\f1 .\" .\" links@div.3c ldiv.3c .\" .\" fileset_database@div.3c PROGRAMING-MAN .\" $Header: resolver.3n,v 74.1 95/05/10 21:11:16 ssa Exp $ .TA r .TH resolver 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME res_query(\|), res_search(\|), res_mkquery(\|), res_send(\|), res_init(\|), dn_comp(\|), dn_expand(\|), herror(\|) \- resolver routines .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .C "#include " .PP .C "int res_query(" .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_search( .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_mkquery( .C " int op," .C " char *dname," .C " int class," .C " int type," .C " char *data," .C " int datalen," .C " struct rrec *newrr," .C " char *buf," .C " int buflen" .C ); .PP .C "int res_send( .C " char *msg," .C " int msglen," .C " char *answer, .C " int anslen .C ); .PP .C void res_init(); .PP .C int dn_comp( .C " char *exp_dn," .C " char *comp_dn," .C " int length," .C " char **dnptrs," .C " char **lastdnptr" .C ); .PP .C int dn_expand( .C " char *msg," .C " char *eomorig," .C " char *comp_dn," .C " char exp_dn," .C " int length" .C ); .PP .C extern int h_errno; .PP .C void herror(char *s); .PP .SH DESCRIPTION These routines are used for making, sending, and interpreting query and reply messages with Internet domain name servers. .PP Global configuration and state information used by the resolver routines are kept in the structure .CR _res and are defined in .RC < resolv.h >. Most of the fields have reasonable defaults and can be ignored. The resolver options are stored in the .CR _res.options field and are listed below. The options are stored as a simple bit mask containing the bitwise OR of the options enabled. .RS .TP 20 .C RES_INIT True if the initial name server address and default domain name are initialized (i.e., .C res_init() has been called). .TP .C RES_DEBUG Print debugging messages. .TP .C RES_AAONLY Accept authoritative answers only. With this option, .C res_send() should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. .TP .C RES_PRIMARY Query the primary server only. Currently this is not implemented. .TP .C RES_USEVC Use TCP connections for queries instead of UDP datagrams. .TP .C RES_STAYOPEN Used with .C RES_USEVC to keep the TCP connection open between queries. This is useful only in programs that regularly do many queries. UDP should be the normal mode used. .TP .C RES_IGNTC The name server will set the truncation bit if all of the data does not fit into the response datagram packet. If .C RES_IGNTC is set, .C res_send() will not retry the query with TCP (i.e., ignore truncation errors). .TP .C RES_RECURSE Set the recursion-desired bit in queries. This is the default. (\c .C res_send() does not do iterative queries and expects the name server to handle recursion.) .TP .C RES_DEFNAMES If set, .C res_search() appends the default domain name to single-component names (those that do not contain a dot). This option is enabled by default. .TP .C RES_DNSRCH If this option is set, .C res_search() searches for host names in the current domain and in parent domains; see .IR hostname (5). This is used by the standard host lookup routine .C gethostbyname() (see .IR gethostbyname (3N)). This option is enabled by default. .RE .PP Initialization of the resolver structure normally occurs on the first call to one of the resolver routines below. If there are errors in the configuration file, they are silently ignored. .RE .SS Primary Routines .TP 20 .C res_init() Reads the configuration file, .CR /etc/resolv.conf , to get the default domain name, search list, and the Internet address of the local name server(s). If no server is configured, the host running the resolver is tried. The current domain name is defined by the hostname if not specified in the configuration file; it can be overridden by the environment variable .CR LOCALDOMAIN . This environment variable may contain several blank separated tokens and overrides the search list on a per process basis. This is similar to the .CR search command in the configuration file. Another environment variable ( .CR RES_OPTIONS ) can be set to override certain internal resolver options which are set by calling some of the configuration routines above, or by using the configuration file's .CR options command. The syntax of the .CR RES_OPTIONS environment variable is explained in .IR resolver(4). .TP .C res_query() Provides an interface to the server query mechanism. It constructs a query, sends it to the local server, awaits a response, and makes preliminary checks on the reply. The query requests information of the specified .I type and .I class for the specified fully-qualified domain name .IR dname . The reply message is left in the .I answer buffer with length .I anslen supplied by the caller. .TP .C res_search() Makes a query and awaits a response much like .CR res_query() , but in addition, it implements the default and search rules controlled by the .C RES_DEFNAMES and .C RES_DNSRCH options. It returns the first successful reply. .SS Other Routines Routines described here are lower-level routines used by .CR res_query() . .TP 20 .C res_mkquery() Constructs a standard query message and places it in .IR buf . It returns the size of the query, or \(mi1 if the query is larger than .IR buflen . The query type .I op is usually .CR QUERY , but can be any of the query types defined in .RC < arpa/nameser.h >. The domain name for the query is given by .IR dname . .I class can be any of the query classes defined in .RC < arpa/nameser.h >. .I type can be any of the query types defined in .RC < arpa/nameser.h >. .I data is the data for an inverse query .RC ( IQUERY ). .I newrr is currently unused but is intended for making update messages. .TP .C res_send() Sends a pre-formatted query and returns an answer. It calls .C res_init() if .C RES_INIT is not set, sends the query to the local name server, and handles timeouts and retries. .C res_send() returns the length of the reply message, or \(mi1 if there were errors. .TP .C dn_comp() Compresses the domain name .I exp_dn and stores it in .IR comp_dn . The size of the compressed name is returned or \(mi1 if there were errors. .I length is the size of the array pointed to by .IR comp_dn . The compression uses an array of pointers .I dnptrs to previously compressed names in the current message. The first pointer points to to the beginning of the message and the list ends with NULL. The limit to the array is specified by .IR lastdnptr . A side effect of .C dn_comp() is to update the list of pointers for labels inserted into the message as the name is compressed. If .I dnptr is NULL, names are not compressed. If .I lastdnptr is NULL, the list of labels is not updated. .TP .C dn_expand() Expands the compressed domain name .I comp_dn to a full domain name. The compressed name is contained in a query or reply message; .I msg is a pointer to the beginning of the message. The uncompressed name is placed in the buffer indicated by .I exp_dn which is of size .IR length . The size of compressed name is returned or \(mi1 if there was an error. .SH RETURN VALUE Error return status from .C res_search() is indicated by a return value of \(mi1. The external integer .C h_errno can then be checked to see whether this is a temporary failure or an invalid or unknown host. The routine .C herror() can be used to print an error message describing the failure. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. .SH ERRORS .C h_errno can have the following values: .RS .TP 20 .C HOST_NOT_FOUND No such host is known. .TP .C TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .C NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. .TP .C NO_DATA The name is known to the name server, but there is no data of the requested type associated with this name; this is not a temporary error. Another type of request to the name server using this domain name will result in an answer. .RE .SH AUTHOR These resolver routines were developed by the University of California, Berkeley. .SH FILES .TP 30 .C /etc/resolv.conf Resolver configuration file. .SH SEE ALSO named(1m), gethostent(3N), resolver(4), hostname(5), RFC1034, RFC1035, RFC1535. .\" .\" index@\f4res_mkquery\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_query\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_search\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_send\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_init\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_comp\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1routines, resolver@@@\f3resolver(3N)\f1 .\" .\" toc@\f3resolver(3N)\f1:\0\0\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \f4dn_comp\f1, \f4dn_expand\f1, \n\f4herror\f1,\f1@@@resolver routines .\" toc@\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4dn_comp\f1, \f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" .\" links@resolver.3n res_mkquery.3n .\" links@resolver.3n res_query.3n .\" links@resolver.3n res_search.3n .\" links@resolver.3n res_send.3n .\" links@resolver.3n res_init.3n .\" links@resolver.3n dn_comp.3n .\" links@resolver.3n dn_expand.3n .\" links@resolver.3n herror.3n .\" .\" fileset_database@resolver.3n INETSVCS-MAN .\" $Header: resolver.3n,v 74.1 95/05/10 21:11:16 ssa Exp $ .TA r .TH resolver 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME res_query(\|), res_search(\|), res_mkquery(\|), res_send(\|), res_init(\|), dn_comp(\|), dn_expand(\|), herror(\|) \- resolver routines .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .C "#include " .PP .C "int res_query(" .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_search( .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_mkquery( .C " int op," .C " char *dname," .C " int class," .C " int type," .C " char *data," .C " int datalen," .C " struct rrec *newrr," .C " char *buf," .C " int buflen" .C ); .PP .C "int res_send( .C " char *msg," .C " int msglen," .C " char *answer, .C " int anslen .C ); .PP .C void res_init(); .PP .C int dn_comp( .C " char *exp_dn," .C " char *comp_dn," .C " int length," .C " char **dnptrs," .C " char **lastdnptr" .C ); .PP .C int dn_expand( .C " char *msg," .C " char *eomorig," .C " char *comp_dn," .C " char exp_dn," .C " int length" .C ); .PP .C extern int h_errno; .PP .C void herror(char *s); .PP .SH DESCRIPTION These routines are used for making, sending, and interpreting query and reply messages with Internet domain name servers. .PP Global configuration and state information used by the resolver routines are kept in the structure .CR _res and are defined in .RC < resolv.h >. Most of the fields have reasonable defaults and can be ignored. The resolver options are stored in the .CR _res.options field and are listed below. The options are stored as a simple bit mask containing the bitwise OR of the options enabled. .RS .TP 20 .C RES_INIT True if the initial name server address and default domain name are initialized (i.e., .C res_init() has been called). .TP .C RES_DEBUG Print debugging messages. .TP .C RES_AAONLY Accept authoritative answers only. With this option, .C res_send() should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. .TP .C RES_PRIMARY Query the primary server only. Currently this is not implemented. .TP .C RES_USEVC Use TCP connections for queries instead of UDP datagrams. .TP .C RES_STAYOPEN Used with .C RES_USEVC to keep the TCP connection open between queries. This is useful only in programs that regularly do many queries. UDP should be the normal mode used. .TP .C RES_IGNTC The name server will set the truncation bit if all of the data does not fit into the response datagram packet. If .C RES_IGNTC is set, .C res_send() will not retry the query with TCP (i.e., ignore truncation errors). .TP .C RES_RECURSE Set the recursion-desired bit in queries. This is the default. (\c .C res_send() does not do iterative queries and expects the name server to handle recursion.) .TP .C RES_DEFNAMES If set, .C res_search() appends the default domain name to single-component names (those that do not contain a dot). This option is enabled by default. .TP .C RES_DNSRCH If this option is set, .C res_search() searches for host names in the current domain and in parent domains; see .IR hostname (5). This is used by the standard host lookup routine .C gethostbyname() (see .IR gethostbyname (3N)). This option is enabled by default. .RE .PP Initialization of the resolver structure normally occurs on the first call to one of the resolver routines below. If there are errors in the configuration file, they are silently ignored. .RE .SS Primary Routines .TP 20 .C res_init() Reads the configuration file, .CR /etc/resolv.conf , to get the default domain name, search list, and the Internet address of the local name server(s). If no server is configured, the host running the resolver is tried. The current domain name is defined by the hostname if not specified in the configuration file; it can be overridden by the environment variable .CR LOCALDOMAIN . This environment variable may contain several blank separated tokens and overrides the search list on a per process basis. This is similar to the .CR search command in the configuration file. Another environment variable ( .CR RES_OPTIONS ) can be set to override certain internal resolver options which are set by calling some of the configuration routines above, or by using the configuration file's .CR options command. The syntax of the .CR RES_OPTIONS environment variable is explained in .IR resolver(4). .TP .C res_query() Provides an interface to the server query mechanism. It constructs a query, sends it to the local server, awaits a response, and makes preliminary checks on the reply. The query requests information of the specified .I type and .I class for the specified fully-qualified domain name .IR dname . The reply message is left in the .I answer buffer with length .I anslen supplied by the caller. .TP .C res_search() Makes a query and awaits a response much like .CR res_query() , but in addition, it implements the default and search rules controlled by the .C RES_DEFNAMES and .C RES_DNSRCH options. It returns the first successful reply. .SS Other Routines Routines described here are lower-level routines used by .CR res_query() . .TP 20 .C res_mkquery() Constructs a standard query message and places it in .IR buf . It returns the size of the query, or \(mi1 if the query is larger than .IR buflen . The query type .I op is usually .CR QUERY , but can be any of the query types defined in .RC < arpa/nameser.h >. The domain name for the query is given by .IR dname . .I class can be any of the query classes defined in .RC < arpa/nameser.h >. .I type can be any of the query types defined in .RC < arpa/nameser.h >. .I data is the data for an inverse query .RC ( IQUERY ). .I newrr is currently unused but is intended for making update messages. .TP .C res_send() Sends a pre-formatted query and returns an answer. It calls .C res_init() if .C RES_INIT is not set, sends the query to the local name server, and handles timeouts and retries. .C res_send() returns the length of the reply message, or \(mi1 if there were errors. .TP .C dn_comp() Compresses the domain name .I exp_dn and stores it in .IR comp_dn . The size of the compressed name is returned or \(mi1 if there were errors. .I length is the size of the array pointed to by .IR comp_dn . The compression uses an array of pointers .I dnptrs to previously compressed names in the current message. The first pointer points to to the beginning of the message and the list ends with NULL. The limit to the array is specified by .IR lastdnptr . A side effect of .C dn_comp() is to update the list of pointers for labels inserted into the message as the name is compressed. If .I dnptr is NULL, names are not compressed. If .I lastdnptr is NULL, the list of labels is not updated. .TP .C dn_expand() Expands the compressed domain name .I comp_dn to a full domain name. The compressed name is contained in a query or reply message; .I msg is a pointer to the beginning of the message. The uncompressed name is placed in the buffer indicated by .I exp_dn which is of size .IR length . The size of compressed name is returned or \(mi1 if there was an error. .SH RETURN VALUE Error return status from .C res_search() is indicated by a return value of \(mi1. The external integer .C h_errno can then be checked to see whether this is a temporary failure or an invalid or unknown host. The routine .C herror() can be used to print an error message describing the failure. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. .SH ERRORS .C h_errno can have the following values: .RS .TP 20 .C HOST_NOT_FOUND No such host is known. .TP .C TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .C NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. .TP .C NO_DATA The name is known to the name server, but there is no data of the requested type associated with this name; this is not a temporary error. Another type of request to the name server using this domain name will result in an answer. .RE .SH AUTHOR These resolver routines were developed by the University of California, Berkeley. .SH FILES .TP 30 .C /etc/resolv.conf Resolver configuration file. .SH SEE ALSO named(1m), gethostent(3N), resolver(4), hostname(5), RFC1034, RFC1035, RFC1535. .\" .\" index@\f4res_mkquery\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_query\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_search\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_send\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_init\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_comp\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1routines, resolver@@@\f3resolver(3N)\f1 .\" .\" toc@\f3resolver(3N)\f1:\0\0\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \f4dn_comp\f1, \f4dn_expand\f1, \n\f4herror\f1,\f1@@@resolver routines .\" toc@\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4dn_comp\f1, \f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" .\" links@resolver.3n res_mkquery.3n .\" links@resolver.3n res_query.3n .\" links@resolver.3n res_search.3n .\" links@resolver.3n res_send.3n .\" links@resolver.3n res_init.3n .\" links@resolver.3n dn_comp.3n .\" links@resolver.3n dn_expand.3n .\" links@resolver.3n herror.3n .\" .\" fileset_database@resolver.3n INETSVCS-MAN .\" $Header: doupdate.3x,v 76.2 95/08/01 15:14:36 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH doupdate 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME doupdate, refresh, wnoutrefresh, wrefresh \(em refresh windows and lines .SH SYNOPSIS .C "#include " .P .C "int doupdate(void);" .P .C "int refresh(void);" .P .C "int wnoutrefresh(WINDOW *\f2win\fP);" .P .C "int wrefresh(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn refresh and .Fn wrefresh functions refresh the current or specified window. The functions position the terminal's cursor at the cursor position of the window, except that if the .Fn leaveok mode has been enabled, they may leave the cursor at an arbitrary position. .P The .Fn wnoutrefresh function determines which parts of the terminal may need updating. The .Fn doupdate function sends to the terminal the commands to perform any required changes. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Refreshing an entire window is typically more efficient than refreshing several subwindows separately. An efficient sequence is to call .Fn wnoutrefresh on each subwindow that has changed, followed by a call to .Fn doupdate , which updates the terminal. .P The .Fn refresh or .Fn wrefresh function (or .Fn wnoutrefresh followed by .Fn doupdate ) must be called to send output to the terminal, as other Curses functions merely manipulate data structures. .SH "SEE ALSO" clearok(), redrawwin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .P This entry is a merger of the X/Open Curses, Issue 3 entries .Fn refresh and .Fn wnoutrefresh . The .B DESCRIPTION is rewritten for clarity and the argument list for the .Fn doupdate and .Fn refresh functions is explicitly declared as \f3void\f1. Otherwise the functionality is identical to that defined in X/Open Curses, Issue 3. .\" .\" toc@\f3doupdate(3x)\f1:\0\0\f4doupdate()\f1, \f4refresh()\f1, \f4wnoutrefresh()\f1, \f4wrefresh()\f1@@@refresh windows and lines .\" .\" toc@\f3refresh()\f1:\0\0refresh windows and lines@@@\f1see \f3doupdate(3x)\f1 .\" toc@\f3wnoutrefresh()\f1:\0\0refresh windows and lines@@@\f1see \f3doupdate(3x)\f1 .\" toc@\f3wrefresh()\f1:\0\0refresh windows and lines@@@\f1see \f3doupdate(3x)\f1 .\" .\" index@\f4doupdate()\f1, \f4refresh()\f1, \f4wnoutrefresh()\f1, \n\f4wrefresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" index@\f4refresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" index@\f4wnoutrefresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" index@\f4wrefresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" .\" links@doupdate.3x refresh.3x .\" links@doupdate.3x wnoutrefresh.3x .\" links@doupdate.3x wrefresh.3x .\" .\" fileset_database@doupdate.3x CURS-ENG-A-MAN .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: remainder.3m,v 78.1 96/02/13 13:43:42 ssa Exp $ .TA r .TH remainder 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME remainder(\|), drem(\|) \- remainder function .SH SYNOPSIS .C "#include " .PP .C "double remainder(double x, double y);" .PP .C "double drem(double x, double y);" .SH DESCRIPTION The .CR remainder() function returns the floating-point remainder .I r \(eq .I x \(mi .I ny when .I y is nonzero. The value .I n is the integral value nearest the exact value .IR x / y ; when \(bv \f2n\f1 \(mi \f2x\f1/\f2y\f1 \(bv \(eq \(12, the value .I n is chosen to be even. .\" .br .\" when .\" .RI | n " - " .\" .IR x / y | .\" = \(12, .\" the value .\" .I n .\" is chosen to be even. .PP The .CR remainder() is independent of the rounding mode. .PP The .CR drem() function is identical to the .CR remainder() function. It is provided for backward compatibility. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH "RETURN VALUE" If .I y .ift is \(+-INFINITY and .ifn is +\-INFINITY and .I x .ift is not \(+-INFINITY, .ifn is not +\-INFINITY, .CR remainder() returns .IR x . .PP If .I x .ift is \(+-zero and .ifn is +\-zero and .I y is nonzero, .CR remainder() returns .IR x . .PP If .I x or .I y is NaN, .CR remainder() returns NaN. .PP If .I y is zero, .CR remainder() returns NaN and sets .CR errno to [EDOM]. .PP If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR remainder() returns NaN and sets .CR errno to [EDOM]. .SH ERRORS If .CR remainder() fails, .CR errno is set to one of the following values. .RS .TP 20 [EDOM] .I y is zero. .TP 20 [EDOM] .I x .ift is \(+-INFINITY. .ifn is +\-INFINITY. .RE .SH "SEE ALSO" fmod(3M), fabs(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR remainder() ": SVID3, XPG4.2" .\" index@\f4remainder()\f1, \f4drem()\f1 \- remainder function@@@\f3remainder(3M)\f1 .\" index@\f4drem()\f1 \- remainder function@@@\f3remainder(3M)\f1 .\" index@\f1math: remainder function@@@\f3remainder(3M)\f1 .\" index@\f1remainder function@@@\f3remainder(3M)\f1 .\" .\" toc@\f3remainder(3M)\f1:\0\0\f4remainder()\f1, \f4drem\f1@@@remainder function .\" toc@\f4drem()\f1:\0\0remainder function@@@see \f3remainder(3M)\f1 .\" .\" links@remainder.3m drem.3m .\" .\" fileset_database@remainder.3m PROGRAMING-MAN .\" $Header: dupwin.3x,v 76.2 95/08/01 15:15:21 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH dupwin 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dupwin \(em duplicate a window .SH SYNOPSIS .C "#include " .P .C "WINDOW *dupwin(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn dupwin function creates a duplicate of the window \f2win\f1. .SH "RETURN VALUE" Upon successful completion, .Fn dupwin returns a pointer to the new window. Otherwise, it returns a null pointer. .SH ERRORS No errors are defined. .SH "SEE ALSO" derwin(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3dupwin(3x)\f1:\0\0\f4dupwin()\f1@@@duplicate a window .\" .\" index@\f4dupwin()\f1 \- duplicate a window@@@\f3dupwin(3x)\f1 .\" index@\f1duplicate a window@@@\f3dupwin(3x)\f1 .\" index@\f1window, duplicate@@@\f3dupwin(3x)\f1 .\" .\" fileset_database@dupwin.3x CURS-ENG-A-MAN .\" .\" $Header: echo.3x,v 76.2 95/07/31 17:42:26 ssa Exp $ .TA e .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH echo 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME echo, noecho \(em enable/disable terminal echo .SH SYNOPSIS .C "#include " .P .C "int echo(void);" .P .C "int noecho(void);" .SH DESCRIPTION The .Fn echo function enables Echo mode for the current screen. The .Fn noecho function disables Echo mode for the current screen. Initially, curses software echo mode is enabled and hardware echo mode of the tty driver is disabled. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, getch(), , \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Section 9.2, \f3Parameters That Can Be Set\f1. .SH "CHANGE HISTORY" First released in Issue . .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn echo and .Fn noecho functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3echo(3X)\f1:\0\0\f4echo()\f1, \f4noecho()\f1@@@enable/disable terminal echo .\" toc@\f4noecho()\f1: enable/disable terminal echo@@@see \f3echo(3X)\f1 .\" .\" index@\f4echo()\f1 \- enable/disable terminal echo@@@\f3echo(3X)\f1 .\" index@\f4noecho()\f1 \- enable/disable terminal echo@@@\f3echo(3X)\f1 .\" index@\f1enable/disable terminal echo@@@\f3echo(3X)\f1 .\" index@\f1disable/enable terminal echo@@@\f3echo(3X)\f1 .\" index@\f1terminal echo, enable/disable@@@\f3echo(3X)\f1 .\" .\" links@echo.3x noecho.3x .\" .\" fileset_database@echo.3x CURS-ENG-A-MAN .\" $Header: echo_wchar.3x,v 76.2 95/07/31 17:43:21 ssa Exp $ .TA e .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH echo_wchar 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME echo_wchar, wecho_wchar \(em write a complex character and immediately refresh the window .SH SYNOPSIS .C "#include " .P .C "int echo_wchar(cchar_t *const \f2wch\fP);" .P .C "int wecho_wchar(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .SH DESCRIPTION .P The .Fn echo_wchar function is equivalent to calling .Fn add_wch and then calling .CR refresh() . .P The .Fn wecho_wchar function is equivalent to calling .Fn wadd_wch and then calling .CR wrefresh() . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" addch(), add_wch(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3echo_wchar(3X)\f1:\0\0\f4echo_wchar()\f1, \f4wecho_wchar()\f1\n@@@write a complex character and immediately refresh the window .\" toc@\f4wecho_wchar()\f1: write a complex character and immediately refresh the window@@@see \f3echo_wchar(3X)\f1 .\" .\" index@\f4echo_wchar()\f1 \- write a complex character and immediately refresh the window@@@\f3echo_wchar(3X)\f1 .\" index@\f4wecho_wchar()\f1 \- write a complex character and immediately refresh the window@@@\f3echo_wchar(3X)\f1 .\" index@\f1write a complex character and immediately refresh the window@@@\f3echo_wchar(3X)\f1 .\" index@\f1window, refresh immediately after writing a complex character@@@\f3echo_wchar(3X)\f1 .\" index@\f1complex character, write and immediately refresh the window@@@\f3echo_wchar(3X)\f1 .\" index@\f1refresh the window immediately after writing a complex character@@@\f3echo_wchar(3X)\f1 .\" .\" links@echo_wchar.3x wecho_wchar.3x .\" .\" fileset_database@echo_wchar.3x CURS-ENG-A-MAN .\" $Header: echochar.3x,v 76.2 95/07/31 17:44:25 ssa Exp $ .TA e .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH echochar 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME echochar, wechochar \(em echo single-byte character and rendition to a window and refresh .SH SYNOPSIS .C "#include " .P .C "int echochar(const chtype \f2ch\fP);" .P .C "int wechochar(WINDOW *\f2win\fP, const chtype \f2ch\fP);" .SH DESCRIPTION The .Fn echochar function is equivalent to a call to .Fn addch followed by a call to .CR refresh() . .P The .Fn wechochar function is equivalent to a call to .Fn waddch followed by a call to .CR wrefresh() . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" addch(), doupdate(), echo_wchar(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3echochar(3X)\f1:\0\0\f4echochar()\f1, \f4wechochar()\f1@@@echo single-byte character and rendition to a window and refresh .\" toc@\f4wechochar()\f1: echo single-byte character and rendition to a window and refresh@@@see \f3echochar(3X)\f1 .\" .\" index@\f4echochar()\f1 \- echo single-byte character and rendition to a window and refresh@@@\f3echochar(3X)\f1 .\" index@\f4wechochar()\f1 \- echo single-byte character and rendition to a window and refresh@@@\f3echochar(3X)\f1 .\" index@\f1echo single-byte character and rendition to a window and refresh@@@\f3echochar(3X)\f1 .\" index@\f1single-byte character and rendition, echo to a window and refresh@@@\f3echochar(3X)\f1 .\" index@\f1window refreshed after echo single-byte character and rendition@@@\f3echochar(3X)\f1 .\" .\" links@echochar.3x wechochar.3x .\" .\" fileset_database@echochar.3x CURS-ENG-A-MAN .\" $Header: ecvt.3c,v 72.6 94/11/30 15:42:51 ssa Exp $ .TA e .TH ecvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ecvt(\|), ecvt_r(\|), fcvt,(\|) fcvt_r(\|), gcvt(\|) \- convert floating-point number to string .SH SYNOPSIS .C "#include " .PP .C "char *ecvt(double value, int ndigit, int *decpt, int *sign);" .PP .C "int ecvt_r(" .nf .PD 0 .IP .C "double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PP .C "char *fcvt(double value, int ndigit, int *decpt, int *sign);" .PP .C "int fcvt_r(" .nf .PD 0 .IP .C "double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char *gcvt(double value, int ndigit, char *buf);" .SH DESCRIPTION .TP 12 .C ecvt() Converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero, otherwise it is zero. .IP One of three non-digit characters strings could be returned if the converted value is out of range. A .C -\|- or .C +\|+ is returned if the value is larger than the exponent can contain, and is negative, or positive, respectively. The third string is returned if the number is illegal, a zero divide for example. The result value is Not A Number .SM (NAN) and would return a .C ? character. .TP .C ecvt_r() Identical to .CR ecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C fcvt() Identical to .CR ecvt() , except that the correct digit has been rounded for printf .C %f (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C fcvt_r() Identical to .CR fcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C gcvt() Converts the .I value to a null-terminated string in the array pointed to by .I buf and returns .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character is included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C", is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the value of the radix character within the current .SM NLS environment. .SH WARNINGS The values returned by .C ecvt() and .C fcvt() point to a single static data array whose content is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .C ecvt_r() and .C fcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .C ecvt() and .C fcvt() were developed by AT&T. .C gcvt() was developed by AT&T and HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH STANDARDS CONFORMANCE .CR ecvt() ": XPG2" .PP .CR fcvt() ": XPG2" .PP .CR gcvt() ": XPG2" .\" .\" index@\f4ecvt()\fP, \f4fcvt()\fP \- convert floating-point number to string@@@\f3ecvt(3C)\f1 .\" index@\f4fcvt()\fP, \f4ecvt()\fP \- convert floating-point number to string@@@\f3ecvt(3C)\f1 .\" index@\f4gcvt()\f1 \- convert floating-point number to string array element@@@\f3ecvt(3C)\f1 .\" index@\f4gcvt()\fP \- convert floating-point number to string array element@@@\f3ecvt(3C)\f1 .\" index@convert floating-point number to string or string array element@@@\f3ecvt(3C)\f1 .\" index@floating-point: convert floating-point number to string or string array element@@@\f3ecvt(3C)\f1 .\" index@number to string or string array element, convert floating-point@@@\f3ecvt(3C)\f1 .\" index@string or string array element, convert floating-point number to@@@\f3ecvt(3C)\f1 .\" index@array element, convert floating-point number to string or string@@@\f3ecvt(3C)\f1 .\" index@element, convert floating-point number to string or string array@@@\f3ecvt(3C)\f1 .\" .\" toc@\f3ecvt(3C)\f1:\0\0\f4ecvt()\fP, \f4fcvt()\fP, \f4gcvt()\f1@@@convert floating-point number to string .\" toc@\f4fcvt()\fP:\0\0convert floating-point number to string@@@see \f3ecvt(3C)\f1 .\" toc@\f4gcvt()\fP:\0\0convert floating-point number to string@@@see \f3ecvt(3C)\f1 .\" .\" links@ecvt.3c ecvt_r.3c .\" links@ecvt.3c fcvt.3c .\" links@ecvt.3c fcvt_r.3c .\" links@ecvt.3c gcvt.3c .\" .\" fileset_database@ecvt.3c PROGRAMING-MAN .\" $Header: ecvt.3c,v 72.6 94/11/30 15:42:51 ssa Exp $ .TA e .TH ecvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ecvt(\|), ecvt_r(\|), fcvt,(\|) fcvt_r(\|), gcvt(\|) \- convert floating-point number to string .SH SYNOPSIS .C "#include " .PP .C "char *ecvt(double value, int ndigit, int *decpt, int *sign);" .PP .C "int ecvt_r(" .nf .PD 0 .IP .C "double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PP .C "char *fcvt(double value, int ndigit, int *decpt, int *sign);" .PP .C "int fcvt_r(" .nf .PD 0 .IP .C "double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char *gcvt(double value, int ndigit, char *buf);" .SH DESCRIPTION .TP 12 .C ecvt() Converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero, otherwise it is zero. .IP One of three non-digit characters strings could be returned if the converted value is out of range. A .C -\|- or .C +\|+ is returned if the value is larger than the exponent can contain, and is negative, or positive, respectively. The third string is returned if the number is illegal, a zero divide for example. The result value is Not A Number .SM (NAN) and would return a .C ? character. .TP .C ecvt_r() Identical to .CR ecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C fcvt() Identical to .CR ecvt() , except that the correct digit has been rounded for printf .C %f (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C fcvt_r() Identical to .CR fcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C gcvt() Converts the .I value to a null-terminated string in the array pointed to by .I buf and returns .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character is included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C", is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the value of the radix character within the current .SM NLS environment. .SH WARNINGS The values returned by .C ecvt() and .C fcvt() point to a single static data array whose content is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .C ecvt_r() and .C fcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .C ecvt() and .C fcvt() were developed by AT&T. .C gcvt() was developed by AT&T and HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH STANDARDS CONFORMANCE .CR ecvt() ": XPG2" .PP .CR fcvt() ": XPG2" .PP .CR gcvt() ": XPG2" .\" .\" index@\f4ecvt()\fP, \f4fcvt()\fP \- convert floating-point number to string@@@\f3ecvt(3C)\f1 .\" index@\f4fcvt()\fP, \f4ecvt()\fP \- convert floating-point number to string@@@\f3ecvt(3C)\f1 .\" index@\f4gcvt()\f1 \- convert floating-point number to string array element@@@\f3ecvt(3C)\f1 .\" index@\f4gcvt()\fP \- convert floating-point number to string array element@@@\f3ecvt(3C)\f1 .\" index@convert floating-point number to string or string array element@@@\f3ecvt(3C)\f1 .\" index@floating-point: convert floating-point number to string or string array element@@@\f3ecvt(3C)\f1 .\" index@number to string or string array element, convert floating-point@@@\f3ecvt(3C)\f1 .\" index@string or string array element, convert floating-point number to@@@\f3ecvt(3C)\f1 .\" index@array element, convert floating-point number to string or string@@@\f3ecvt(3C)\f1 .\" index@element, convert floating-point number to string or string array@@@\f3ecvt(3C)\f1 .\" .\" toc@\f3ecvt(3C)\f1:\0\0\f4ecvt()\fP, \f4fcvt()\fP, \f4gcvt()\f1@@@convert floating-point number to string .\" toc@\f4fcvt()\fP:\0\0convert floating-point number to string@@@see \f3ecvt(3C)\f1 .\" toc@\f4gcvt()\fP:\0\0convert floating-point number to string@@@see \f3ecvt(3C)\f1 .\" .\" links@ecvt.3c ecvt_r.3c .\" links@ecvt.3c fcvt.3c .\" links@ecvt.3c fcvt_r.3c .\" links@ecvt.3c gcvt.3c .\" .\" fileset_database@ecvt.3c PROGRAMING-MAN .\" $Header: end.3c,v 72.5 94/11/14 15:27:57 ssa Exp $ .TH end 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME .\"end, etext, edata \- last locations in program end, etext, edata, __data_start, __text_start \- last locations in program .SH SYNOPSIS .\".C "extern void *_end, *end, *_etext, *etext, *_edata, *edata;" .C "extern void *_end, *end, *_etext, *etext, *_edata, *edata, *__data_start," .C " *__text_start;" .SH DESCRIPTION These names refer neither to routines nor to locations with interesting contents. The address of the symbols .C _etext and .C etext is the first address above the program text, the address of .C _edata and .C edata is the first address above the initialized data region, and the address of .C _end and .C end is the first address above the uninitialized data region. .PP The address of the symbols .C __data_start is the beginning address of the program's data area, and .C __text_start is the beginning address of the program's text area. .PP The linker defines these symbols with the appropriate values if they are referenced by the program but not defined. The linker issues an error if the user attempts to define .CR _etext , .CR _edata , .\"or .\".CR _end . .CR _end , .CR __data_start , or .CR __text_start . .PP When execution begins, the program break (the first location beyond the data) coincides with .CR _end , but the program break can be reset by the routines of .IR brk (2), .IR malloc (3C), standard input/output .RI ( stdio (3S)), the profile .RC ( -p ) option of .IR cc (1), and so on. Thus, the current value of the program break should be determined by .C sbrk(0) (see .IR brk (2)). .SH WARNINGS In C, these names must look like addresses. Thus, use .C &end instead of .C end to access the current value of .IR end . .SH SEE ALSO .PD .SS System Tools: .TP 18 .IR cc(1) invoke the HP-UX C compiler .PD 0 .TP .IR ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 .IR brk(2) change data segment space allocation .PD 0 .TP .IR crt0(3) execution startup routine .TP .IR malloc(3C) main memory allocator .TP .IR stdio(3S) standard buffered input/output stream file package .PD .SH STANDARDS CONFORMANCE .CR end() ": XPG2" .PP .CR edata() ": XPG2" .PP .CR etext() ": XPG2" .\" .\" index \f4end\fP \- first address beyond uninitialized program data region \f3end(3C)\f1 .\" index \f4edata\fP \- first address beyond initialized program data region \f3end(3C)\f1 .\" index \f4etext\fP \- first address beyond program text region \f3end(3C)\f1 .\" index last locations of allocated regions in program \f3end(3C)\f1 .\" index end locations of allocated regions in program \f3end(3C)\f1 .\" index addresses \- first locations beyond allocated program regions \f3end(3C)\f1 .\" index first locations beyond allocated program regions \f3end(3C)\f1 .\" index locations beyond allocated program regions, first \f3end(3C)\f1 .\" index allocated program regions, first locations beyond \f3end(3C)\f1 .\" index program regions, first locations beyond allocated \f3end(3C)\f1 .\" index regions, first locations beyond allocated program \f3end(3C)\f1 .\" .\" toc \f3end(3C)\f1:\0\0\f4end\fP, \f4etext\fP, \f4edata\fP last locations in program .\" toc \f4etext\fP:\0\0last locations in program see \f3end(3C)\f1 .\" toc \f4edata\fP:\0\0last locations in program see \f3end(3C)\f1 .\" .\" links end.3c etext.3c .\" links end.3c edata.3c .\" .\" fileset_database end.3c PROG-AUX-MAN .\" $Header: crypt.3c,v 72.5 94/11/14 13:14:01 ssa Exp $ .TA c .TH crypt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crypt, crypt_r, setkey, setkey_r, encrypt, encrypt_r \- generate hashing encryption .SH SYNOPSIS .nf .C "#include " .C "#include " .fi .PP .C "char *crypt(const char *key, const char *salt);" .PP .C "char *crypt_r(const char *key, const char *salt, CRYPTD *cd);" .PP .C "void setkey(const char *key);" .PP .C "void setkey_r(const char *key, CRYPTD *cd);" .PP .C "void encrypt(char block[64], int edflag);" .PP .C "void encrypt_r(char block[64], int edflag, CRYPTD *cd);" .SH DESCRIPTION .SS crypt(\|): .C crypt() is the password encryption function. It is based on a one way hashing encryption algorithm with variations intended (among other things) to frustrate use of hardware implementations of a key search. .PP .I key is a user's typed password. .I salt is a two-character string chosen from the set .CR [a-zA-Z0-9./] ; this string is used to perturb the hashing algorithm in one of 4096 different ways, after which the password is used as the key to encrypt repeatedly a constant string. The returned value points to the encrypted password. The first two characters are the salt itself. .SS setkey(\|) and encrypt(\|): .C setkey() and .C encrypt() provide (rather primitive) access to the actual hashing algorithm. The argument to .C setkey() is a character array of length 64 containing only the characters with numerical value 0 and 1. If this string is divided into groups of 8, the low-order bit in each group is ignored; this gives a 56-bit key which is set into the machine. This is the key that is used with the hashing algorithm to encrypt or decrypt the string .I block with the function .CR encrypt() . .PP The .I block argument to .C encrypt() is a character array of length 64 containing only the characters with numerical value 0 and 1. The argument array is modified in place to a similar array representing the bits of the argument after having been subjected to the hashing algorithm using the key that was set by .CR setkey() . If .I edflag is zero, the argument is encrypted; if non-zero it is decrypted. .SS Reentrant Interfaces .I cd is a pointer to a CRYPTD object, which is defined in .RC < crypt.h >. .PP For .C crypt_r(), .I cd is used as a buffer to store the result string. .PP In the case of .C setkey_r() and .C encrypt_r(), .I cd is used to hold key information set by the .C setkey_r() call, and used by the .C encrypt_r() call. .SH SEE ALSO crypt(1), login(1), passwd(1), getpass(3C), passwd(4). .SH WARNINGS The return value for .C crypt() points to static data whose content is overwritten by each call. .CR crypt() , .CR setkey() , and .CR encrypt() are unsafe in multi-thread applications. .CR crypt_r() , .CR setkey_r() , and .C encrypt_r() are MT-Safe and should be used instead. .SH STANDARDS CONFORMANCE .CR crypt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR encrypt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR setkey() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4crypt()\f1, \f4setkey()\f1, \f4setkey_r()\f1, \f4encrypt_r()\f1, \f4encrypt()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4setkey()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4setkey_r()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4encrypt()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4encrypt_r()\f1 \- generate hashing encyption@@@\f3crypt(3C)\f1 .\" index@generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@hashing encryption, generate@@@\f3crypt(3C)\f1 .\" index@encryption, hashing, generate@@@\f3crypt(3C)\f1 .\" index@encryption, password@@@\f3crypt(3C)\f1 .\" index@password encryption function@@@\f3crypt(3C)\f1 .\" .\" toc@\f3crypt(3C)\f1:\0\0\f4crypt()\f1, \f4setkey()\f1, \f4setkey_r()\f1, \f4encrypt()\f1, \f4encrypt_r()\f1@@@generate hashing encryption .\" toc@\f4setkey()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4setkey_r()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4encrypt()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4encrypt_r()\f1:\0\0gerneate hashing encryption@@@see \f3crypt(3C)\f1 .\" .\" links@crypt.3c crypt_r.3c .\" links@crypt.3c setkey.3c .\" links@crypt.3c setkey_r.3c .\" links@crypt.3c encrypt.3c .\" links@crypt.3c encrypt_r.3c .\" .\" fileset_database@crypt.3c PROGRAMING-MAN .\" $Header: crypt.3c,v 72.5 94/11/14 13:14:01 ssa Exp $ .TA c .TH crypt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crypt, crypt_r, setkey, setkey_r, encrypt, encrypt_r \- generate hashing encryption .SH SYNOPSIS .nf .C "#include " .C "#include " .fi .PP .C "char *crypt(const char *key, const char *salt);" .PP .C "char *crypt_r(const char *key, const char *salt, CRYPTD *cd);" .PP .C "void setkey(const char *key);" .PP .C "void setkey_r(const char *key, CRYPTD *cd);" .PP .C "void encrypt(char block[64], int edflag);" .PP .C "void encrypt_r(char block[64], int edflag, CRYPTD *cd);" .SH DESCRIPTION .SS crypt(\|): .C crypt() is the password encryption function. It is based on a one way hashing encryption algorithm with variations intended (among other things) to frustrate use of hardware implementations of a key search. .PP .I key is a user's typed password. .I salt is a two-character string chosen from the set .CR [a-zA-Z0-9./] ; this string is used to perturb the hashing algorithm in one of 4096 different ways, after which the password is used as the key to encrypt repeatedly a constant string. The returned value points to the encrypted password. The first two characters are the salt itself. .SS setkey(\|) and encrypt(\|): .C setkey() and .C encrypt() provide (rather primitive) access to the actual hashing algorithm. The argument to .C setkey() is a character array of length 64 containing only the characters with numerical value 0 and 1. If this string is divided into groups of 8, the low-order bit in each group is ignored; this gives a 56-bit key which is set into the machine. This is the key that is used with the hashing algorithm to encrypt or decrypt the string .I block with the function .CR encrypt() . .PP The .I block argument to .C encrypt() is a character array of length 64 containing only the characters with numerical value 0 and 1. The argument array is modified in place to a similar array representing the bits of the argument after having been subjected to the hashing algorithm using the key that was set by .CR setkey() . If .I edflag is zero, the argument is encrypted; if non-zero it is decrypted. .SS Reentrant Interfaces .I cd is a pointer to a CRYPTD object, which is defined in .RC < crypt.h >. .PP For .C crypt_r(), .I cd is used as a buffer to store the result string. .PP In the case of .C setkey_r() and .C encrypt_r(), .I cd is used to hold key information set by the .C setkey_r() call, and used by the .C encrypt_r() call. .SH SEE ALSO crypt(1), login(1), passwd(1), getpass(3C), passwd(4). .SH WARNINGS The return value for .C crypt() points to static data whose content is overwritten by each call. .CR crypt() , .CR setkey() , and .CR encrypt() are unsafe in multi-thread applications. .CR crypt_r() , .CR setkey_r() , and .C encrypt_r() are MT-Safe and should be used instead. .SH STANDARDS CONFORMANCE .CR crypt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR encrypt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR setkey() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4crypt()\f1, \f4setkey()\f1, \f4setkey_r()\f1, \f4encrypt_r()\f1, \f4encrypt()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4setkey()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4setkey_r()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4encrypt()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4encrypt_r()\f1 \- generate hashing encyption@@@\f3crypt(3C)\f1 .\" index@generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@hashing encryption, generate@@@\f3crypt(3C)\f1 .\" index@encryption, hashing, generate@@@\f3crypt(3C)\f1 .\" index@encryption, password@@@\f3crypt(3C)\f1 .\" index@password encryption function@@@\f3crypt(3C)\f1 .\" .\" toc@\f3crypt(3C)\f1:\0\0\f4crypt()\f1, \f4setkey()\f1, \f4setkey_r()\f1, \f4encrypt()\f1, \f4encrypt_r()\f1@@@generate hashing encryption .\" toc@\f4setkey()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4setkey_r()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4encrypt()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4encrypt_r()\f1:\0\0gerneate hashing encryption@@@see \f3crypt(3C)\f1 .\" .\" links@crypt.3c crypt_r.3c .\" links@crypt.3c setkey.3c .\" links@crypt.3c setkey_r.3c .\" links@crypt.3c encrypt.3c .\" links@crypt.3c encrypt_r.3c .\" .\" fileset_database@crypt.3c PROGRAMING-MAN .\" $Header: end.3c,v 72.5 94/11/14 15:27:57 ssa Exp $ .TH end 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME .\"end, etext, edata \- last locations in program end, etext, edata, __data_start, __text_start \- last locations in program .SH SYNOPSIS .\".C "extern void *_end, *end, *_etext, *etext, *_edata, *edata;" .C "extern void *_end, *end, *_etext, *etext, *_edata, *edata, *__data_start," .C " *__text_start;" .SH DESCRIPTION These names refer neither to routines nor to locations with interesting contents. The address of the symbols .C _etext and .C etext is the first address above the program text, the address of .C _edata and .C edata is the first address above the initialized data region, and the address of .C _end and .C end is the first address above the uninitialized data region. .PP The address of the symbols .C __data_start is the beginning address of the program's data area, and .C __text_start is the beginning address of the program's text area. .PP The linker defines these symbols with the appropriate values if they are referenced by the program but not defined. The linker issues an error if the user attempts to define .CR _etext , .CR _edata , .\"or .\".CR _end . .CR _end , .CR __data_start , or .CR __text_start . .PP When execution begins, the program break (the first location beyond the data) coincides with .CR _end , but the program break can be reset by the routines of .IR brk (2), .IR malloc (3C), standard input/output .RI ( stdio (3S)), the profile .RC ( -p ) option of .IR cc (1), and so on. Thus, the current value of the program break should be determined by .C sbrk(0) (see .IR brk (2)). .SH WARNINGS In C, these names must look like addresses. Thus, use .C &end instead of .C end to access the current value of .IR end . .SH SEE ALSO .PD .SS System Tools: .TP 18 .IR cc(1) invoke the HP-UX C compiler .PD 0 .TP .IR ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 .IR brk(2) change data segment space allocation .PD 0 .TP .IR crt0(3) execution startup routine .TP .IR malloc(3C) main memory allocator .TP .IR stdio(3S) standard buffered input/output stream file package .PD .SH STANDARDS CONFORMANCE .CR end() ": XPG2" .PP .CR edata() ": XPG2" .PP .CR etext() ": XPG2" .\" .\" index \f4end\fP \- first address beyond uninitialized program data region \f3end(3C)\f1 .\" index \f4edata\fP \- first address beyond initialized program data region \f3end(3C)\f1 .\" index \f4etext\fP \- first address beyond program text region \f3end(3C)\f1 .\" index last locations of allocated regions in program \f3end(3C)\f1 .\" index end locations of allocated regions in program \f3end(3C)\f1 .\" index addresses \- first locations beyond allocated program regions \f3end(3C)\f1 .\" index first locations beyond allocated program regions \f3end(3C)\f1 .\" index locations beyond allocated program regions, first \f3end(3C)\f1 .\" index allocated program regions, first locations beyond \f3end(3C)\f1 .\" index program regions, first locations beyond allocated \f3end(3C)\f1 .\" index regions, first locations beyond allocated program \f3end(3C)\f1 .\" .\" toc \f3end(3C)\f1:\0\0\f4end\fP, \f4etext\fP, \f4edata\fP last locations in program .\" toc \f4etext\fP:\0\0last locations in program see \f3end(3C)\f1 .\" toc \f4edata\fP:\0\0last locations in program see \f3end(3C)\f1 .\" .\" links end.3c etext.3c .\" links end.3c edata.3c .\" .\" fileset_database end.3c PROG-AUX-MAN .\" $Header: getbootpent.3x,v 74.1 95/05/10 21:04:42 ssa Exp $ .TA g .TH getbootpent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" =========== .SH NAME getbootpent(), putbootpent(), setbootpent(), endbootpent(), parse_bp_htype(), parse_bp_haddr(), parse_bp_iaddr() \- get or put bootptab entry .\" =========== .SH SYNOPSIS .C "#include " .PP .C "int getbootpent (struct bootpent **bootpent);" .PP .C "int setbootpent (const char *path);" .PP .C "int endbootpent (void);" .PP .C "void putbootpent (" .nf .PD 0 .IP .C "const struct bootpent *bootpent," .C "const int numfields," .C "\s-1FILE\s0 * bootpfile" .PP .C ");" .PD .fi .PP .C "int parse_bp_htype (const char *source);" .PP .C "int parse_bp_haddr (" .nf .PD 0 .IP .C "char **source," .C "int htype," .C "unsigned char *result," .C "unsigned int *bytes" .PP .C ");" .PD .PP .C "int parse_bp_iaddr (" .nf .PD 0 .IP .C "char **source," .C "unsigned long *result" .PP .C ");" .PD .\" =========== .SS Remarks These functions reside in libdc.a, and are linked using the .C -ldc option to the .C ld or .C cc command. .\" =========== .SH DESCRIPTION These functions help a program read or modify a bootptab .RC ( bootpd control) file one entry at a time. .C getbootpent() locates an entry in the .C /etc/bootptab file, or an alternate file specified to .CR setbootpent() , and returns a pointer to an array of objects of type .C struct bootpent that breaks the entry into separate data fields with preceding, or embedded, comment (text) lines. .PP The .C bootpent structure is defined in .RC < bootpent.h > and includes the following members: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. int@bp_type;@/* BP_DATA, BP_COMMENT, BP_BLANK@*/ char@*bp_text;@/* one field or one comment line@*/ .TE .ft P .RE .PP The file also defines the following data type and constants: .IP .C "typedef struct bootpent *bpp_t;" .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. #define BP_NULLP@((bpp_t) 0) #define BP_SIZE@(sizeof (struct bootpent)) .TE .ft P .RE .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. #define MAXHADDRLEN@6 #define HTYPE_UNKNOWN@0@/* 0 bytes@*/ #define HTYPE_ETHERNET@1@/* 6 bytes@*/ #define HTYPE_EXP_ETHERNET@2@/* 1 byte@*/ #define HTYPE_AX25@3@/* 0 bytes@*/ #define HTYPE_PRONET@4@/* 1 byte@*/ #define HTYPE_CHAOS@5@/* 0 bytes@*/ #define HTYPE_IEEE802@6@/* 6 bytes@*/ #define HTYPE_ARCNET@7@/* 0 bytes@*/ #define MAXHTYPES@7 .TE .ft P .RE .PP The fields are described in the .RB `` "Field Definitions" '' section below. The purpose of each function is as follows. .TP 25 .C getbootpent() When first called, .C getbootpent() returns a pointer to, and the number of elements in, an array of .C bootpent structures. The array holds the first entry in the .C /etc/bootptab file (or from an alternate file specified by a call to .CR setbootpent() ), including leading, or embedded, comment lines. Each subsequent call returns a pointer to the next entry in the file so that successive calls can be used to search the entire file. .IP If no file is currently in memory, .C getbootpent() reads the .C /etc/bootptab file prior to doing its work. .IP The returned array exists in static space (malloc'd memory) overwritten by the next call (so previously returned pointers become invalid). However, each array element's .C bp_text pointer points to text in an in-memory copy of the file. This text is not altered by the next call (nor by changes to the file itself). Hence, it is possible to copy an entry's array in order to save it, as illustrated in .SM EXAMPLES below. The data remains valid until the next call of .C setbootpent() or .CR endbootpent(). .IP If there are comments after the last entry, they are returned as a separate entry with no data parts. .TP .C setbootpent() Opens the specified file for reading by .CR getbootpent() , reads a copy into memory, and closes the file (which as a side-effect releases any locks on the file; see .IR lockf (2)). If the given .I path is a null pointer or a null string, .C setbootpent() opens and reads .CR /etc/bootptab . .IP If the last file opened by .C setbootpent() (or implicitly by .CR getbootpent() ) was .CR /etc/bootptab , a subsequent call to .C setbootpent() for the same file rewinds the file to the beginning, making visible any recent changes to the file, without first requiring a call to .CR endbootpent() . .TP .C endbootpent() Frees the in-memory copy of the last file opened by .CR setbootpent() , or .CR getbootpent() . .TP .C putbootpent() Writes (to the current location in the stream specified by .IR bootpfile ) the .SM ASCII equivalent of the specified array of .C bootpent structures containing one file entry, and its leading, or embedded, comments (a total of .I numfields array elements). Entries are written in canonical form, meaning the entry name and each data field are on separate lines, data fields are preceded by one tab each, and each line except the last ends with ``:\e''. If .I numfields is less than or equal to zero, nothing is written. .TP .C parse_bp_htype() Converts a host address type from string to numeric format .RC ( HTYPE_ *) in the same manner as .CR bootpd . .TP .C parse_bp_haddr() Converts a host (hardware, link level) address from string to binary format in the same manner as .C bootpd given a host address type .RC ( HTYPE_ *). The calling program's .IR result , which must be an array containing at least .SM MAXHADDRLEN elements, is modified to hold the host address binary value, and .C bytes is modified to indicate the length in bytes of the resulting address. This can be used to compare two host addresses, independent of string representations. .I source is modified to point to the first char after the parsed address. .TP .C parse_bp_iaddr() Converts an internet address from string to binary format in the same manner as .CR bootpd . This can be used to compare two internet addresses, independent of string representations. The calling program's .I result is modified to hold the internet address binary value. .I source is modified to point to the first char after the parsed address. .\" ----------- .SS Field Definitions If .C bootpent.bp_type is .SM BP_DATA, the associated text is one field from the current entry, either the name field or one of the tag fields. Null tag fields (two colons in a row) are ignored, not returned. .PP If .C bootpent.bp_type is .SM BP_COMMENT or .SM BP_BLANK, the associated text is one comment line or blank line from the file, either preceding the current entry or embedded in it following a data line that was continued with a backslash. The text is exactly as it appears in the file, including any whitespace appearing on a blank line, and there is no trailing newline. .PP The returned array elements are in the same order as data fields and comment lines appear in the file. .PP Entry field strings are of the form: .IP .IR tag [\c .ift \f4\s+1@\s0\fP\c .ifn \f3@\fP\c .RC ]\|[ =\c .C """\c .I value\c .C """\c .RC ] .PP with surrounding whitespace, if any, removed (see .IR bootpd (1M) for the full description). Double quotes, and backslashes, can appear anywhere in the field strings. .PP Template entries (those referred to by other entries using .C tc fields) are not special. They can be managed like other entries. It is the calling program's responsibility to correctly manage the order of fields, .C tc fields, and ``@'' fields that override earlier field values. .\" =========== .SH RETURN VALUE .C getbootpent() returns the number of valid array elements (one or more) upon successful completion. At the end of the input file it returns zero. If it cannot open or close the file it returns \-1. If it encounters a memory allocation or map error, or a read error, it returns \-2. .PP .C setbootpent() returns zero if successful opening and reading the specified or default file. If it cannot open or close the file it returns \-1. If it encounters a memory allocation or map error or a read error it returns \-2. .PP .C endbootpent() returns zero if successful freeing the memory for the current open file. If there is no current file it returns \-1. If it cannot free the memory for the current file it returns \-2. .PP .C putbootpent() returns zero if successful writing an entry to the specified file, with the .C ferror() indication clear (see .IR ferror (3S)). Otherwise it returns non-zero with .C ferror() set. .PP In all cases above, if a failure is due to a failed system call, the .C errno value from the system is valid on return from the called function. .PP .C parse_bp_htype() returns .SM HTYPE_UNKNOWN if the hardware type string is unrecognized. .PP .C parse_bp_haddr() returns zero if successful, otherwise non-zero in case of parsing error, invalid .IR htype , or a host address type for which the address length is unknown; .I source is modified to point to the first illegal char (a .SM NUL if the string is too short). The caller's .I bytes value is unmodified, but .I result might be changed. .PP .C parse_bp_iaddr() returns zero if successful, otherwise non-zero, and .I source is modified to point to the first illegal char (a .SM NUL if the string is null). .\" =========== .SH EXAMPLES The following code fragment copies all data and comments from .C /etc/bootptab to a temporary copy of the file. It converts data entries to canonical form as a side effect, and prints to standard output the first field of each entry copied (should be the field name, assuming the entry doesn't start with a continuation line). .RS .PP .nf .ifn \f3 .ift \f4 #include \s-1FILE\s0 *newfilep; /* to write temp file */ bpp_t bp; /* read from file */ int field; /* current field number */ int fields; /* total in array for one entry */ if ((newfilep = fopen ("/tmp/bootptab", "w")) == (\s-1FILE\s0 *) \s-1NULL\s0) { \f2(handle error)\fP } while ((fields = getbootpent (&bp)) > 0) { for (field = 0; field < fields; ++field) { if ((bp[field].bp_type) == \s-1BP_DATA\s0) { (void) puts (bp[field].bp_text); break; } } if (putbootpent (bp, fields, newfilep)) { \f2(handle error)\fP } } if (fields < 0) /* error reading file */ { \f2(handle error)\fP } if (endbootpent()) { \f2(handle error)\fP } if (fclose (newfilep)) { \f2(handle error)\fP } .ft P .fi .RE .PP The following code fragment saves a copy of a bootptab entry returned by .CR getbootpent() . .RS .PP .nf .ifn \f3 .ift \f4 #include #include #include bpp_t bpnew; unsigned size; size = fields *\s-1BP_SIZE\s0; if ((bpnew = (bpp_t) malloc (size)) == \s-1BP_NULLP\s0) { \f2(handle error)\fP } (void) memcpy ((void *)bpnew, (void *)bp, size); .ft P .fi .RE .\" =========== .SH WARNINGS These functions are unsafe in multi-thread applications. .PP Calling .C setbootpent() releases any locks on the file it opens. .\" =========== .SH AUTHOR .PP These functions were developed by .SM HP. .\" =========== .SH FILES .TP 20 .C /etc/bootptab control file for .C bootpd .\" =========== .SH SEE ALSO bootpd(1M), .\" chbootptab(1M), (SAM-only, not currently supported for 10.0) errno(2), lockf(2), ferror(3S), fopen(3S), malloc(3C). .\" .\" toc@\f3getbootpent(3X)\f1:\0\0\f4getbootpent(), putbootpent(), setbootpent(), endbootpent(), \nparse_bp_htype(), parse_bp_hpaddr(), parse_bp_iaddr()\f1@@@get, or put bootptab entry .\" .\" index@get, or put bootptab entry \- @@@\f3getbootpent(3X)\f1 .\" index@bootptab entry, get or put@@@\f3getbootpent(3X)\f1 .\" .\" links@getbootpent.3x setbootpent.3x .\" links@getbootpent.3x endbootpent.3x .\" links@getbootpent.3x putbootpent.3x .\" links@getbootpent.3x parse_bp_htype.3x .\" links@getbootpent.3x parse_bp_haddr.3x .\" links@getbootpent.3x parse_bp_iaddr.3x .\" $Header: dcnodes.3x,v 74.2 95/05/10 21:04:24 ssa Exp $ .TA d .TH dcnodes 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" =========== .SH NAME dcnodes(), dcnodes_status(), dcnodes_status_string(), dcnodes_error_string(), dcnodes_server_ipaddr(), enddcnodes() \- report on diskless cluster nodes .\" =========== .SH SYNOPSIS .C "#include " .PP .C "int dcnodes (" .nf .PD 0 .IP .C "const int mode," .C "struct dcnode **dcnode" .PP .C ");" .PD .PP .C "int dcnodes_status (" .nf .PD 0 .IP .C "const int mode," .C "struct dcnode *dcnode," .C "const int num_dcnodes," .C "const time_t timeout" .PP .C ");" .PD .PP .C "int dcnodes_status_string ( .nf .PD 0 .IP .C "const int mode," .C "const int statval" .PP .C ");" .PD .PP .C "int dcnodes_error_string (const int retval);" .PP .C "int dcnodes_server_ipaddr (" .nf .PD 0 .IP .C "char *ipaddr," .C "const int len" .PP .C ");" .PD .PP .C "unsigned long dcnodes_mtime (void);" .PP .C "void enddcnodes (void);" .\" =========== .SS Remarks These functions reside in libdc.a, and are linked using the .C -ldc option to the .C ld or .C cc command. .\" =========== .SH DESCRIPTION These functions help a program get static (configuration) and dynamic (status) information about diskless cluster nodes (server, and clients). The .C dcnodes() and .C dcnodes_status() functions return information about all nodes in a cluster (including the cluster server), when run on any node in the cluster. The .C dcnodes_server_ipaddr() function returns the internet address of a cluster client's server system. .PP The .C dcnode structure is defined in .RC < dcnodes.h > and includes at least the following members. Each string is null-terminated. .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. char@dcn_name[];@/* node name; see below@*/ char@dcn_ipaddr[];@/* IP address, dot form@*/ char@dcn_hwaddr[];@/* hardware address, hex form@*/ char@dcn_netmask[];@/* net/subnet mask, dot form@*/ char@dcn_route[];@/* default route, dot form@*/ char@dcn_shroot[];@/* OS shared root description@*/ int@dcn_status;@/* system status; see below@*/ .TE .ft P .RE .PP The file also defines the following constants and data types: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. DCNODES_SHORT@/* mode parameter to dcnodes(); see below@*/ DCNODES_LONG DCNODES_LONGER DCNODES_ALL DCNODES_TYPE .TE .ft P .RE .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. DCNODES_STATUS@/* mode parameter to dcnodes_status()@*/ DCNODES_STATUS_DETAILS .TE .ft P .RE .PP These lengths do not include the null terminator: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. DCN_NAME_LEN@/* maximum dcnode name length@*/ DCN_IPADDR_LEN@/* maximum IP address length@*/ DCN_HWADDR_LEN@/* maximum HW address length@*/ DCN_NETMASK_LEN@/* maximum net/subnet mask length@*/ DCN_ROUTE_LEN@/* maximum default route length@*/ DCN_SHROOT_LEN@/* maximum OS shared root length@*/ DCN_STATUS_LEN@/* size of status value (int)@*/ DCN_VALUE_UNKNOWN@/* field value cannot be determined@*/ DCN_TYPE_STANDALONE@/* results of DCNODES_TYPE@*/ DCN_TYPE_SERVER DCN_TYPE_CLIENT DCN_ERR_MEMORY@/* error return codes; see below@*/ DCN_ERR_IPADDR DCN_ERR_RCMD DCN_ERR_FDOPEN DCN_ERR_STARTUP DCN_ERR_VERSION DCN_ERR_EXEC DCN_ERR_READ DCN_ERR_SOCKET DCN_ERR_CONNECT DCN_STATUS_UNKNOWN@/* status values; see below@*/ DCN_STATUS_STANDALONE DCN_STATUS_SERVER DCN_STATUS_ACTIVE DCN_STATUS_INACTIVE DCN_STATUS_NO_IP_ADDR DCN_STATUS_NO_DATA DCN_IS_UP(status)@/* macros for checking status value@*/ DCN_IS_SERVER(status) DCN_IS_CLIENT(status) DCN_IS_LOCAL_ROOT(status) .TE .PP .C "typedef struct dcnode *dcnp_t;" .ifn \f3 .ift \f4 .TS tab(@); l l. #define DCN_NULLP@((dcnp_t) 0) #define DCN_NULLPP@((dcnp_t *) 0) #define DCN_SIZE@(sizeof (struct dcnode)) #define DCN_PROG_NULLP@((void (*)()) 0) .TE .ft P .RE .PP If invoked on a cluster client (remote-root) node, .C dcnodes() and .C dcnodes_status() contact the node's root server system to obtain information about all of the cluster's nodes, except as noted below. This requires .C rcmd() access from the client to the server by the effective user .SM ID of the calling process (see .IR rcmd (3N) and .IR setuid (2)) to execute the .CR dcnodes command. .PP The functions have the following purposes: .PP .TP 15 .C dcnodes() This function modifies the .I dcnode pointer to point to an array of .I dcnode structures, each containing information for one node, and returns the number of nodes in the list. The cluster server is always the first system in the list. The .I mode parameter determines which operation is performed: .RS 5 .TP 15 .C DCNODES_SHORT Return a count, and a list, of cluster node names; other structure fields are undefined (except .CR dcn_ipaddr , which is set to null for convenience in calling .CR dcnodes_status() ). The cluster server's .C dcn_name value is its domain-expanded .C hostname value (see .IR gethostname (2)), that is, the result of looking up the system's .C hostname in the hosts database using .C gethostbyname() (see .IR gethostent (3N)). Cluster clients' .C dcn_name values are their names as listed in the cluster client list on the server (see .SM FILES below), normally including domain parts, which should but might not match each client's .C hostname and .C uname.nodename values. .IP With .CR DCNODES_SHORT , the .I dcnode parameter can be a null pointer, which causes .C dcnodes not to allocate space for, and build the list of, cluster node names. In this case it only returns a count of cluster nodes. .IP An unrecognized .I mode value is treated as .CR DCNODES_SHORT . .TP .C DCNODES_LONG Fill in all structure fields except .C dcn_shroot and .CR dcn_status . .C dcn_shroot is undefined. .C dcn_status is set to one of the following as appropriate: .RS .TP 25 .C DCN_STATUS_UNKNOWN for cluster clients (default value) .PD 0 .TP .C DCN_STATUS_SERVER for cluster server systems .TP .C DCN_STATUS_STANDALONE for standalone systems .PD .RE .IP The .C dcn_status field can be filled in by calling .C dcnodes_status() as described below. If .C dcnodes() cannot determine the value for any field, that field is set to the value of the .C DCN_VALUE_UNKNOWN macro. .IP If a standalone or cluster server system has multiple .SM LAN interface cards, there is an entry for each card in the returned array. Each of those entries contains the same values for .C dcn_route and .CR dcn_status , but different values for .C dcn_ipaddr and .CR dcn_hwaddr . The values for .C dcn_name and .C dcn_netmask might differ, reflecting each of the server's .SM LAN interface cards. If a .SM LAN interface card is down, its .C dcn_ipaddr value is .RC `` "(card down)" ''. .IP If the system on which .C dcnodes() is invoked is standalone and has no .SM LAN cards, a single entry is returned with .C dcn_name set to the host's domain-expanded hostname value, and .CR dcn_ipaddr , .CR dcn_hwaddr , and .C dcn_netmask set to the value of .CR DCN_VALUE_UNKNOWN . .TP .C DCNODES_LONGER Same as .C DCNODES_LONG except also fill in the .C dcn_shroot field. This can take significant extra time. The cluster server's .C dcn_shroot value is always ``/''; client values are truncated if necessary, and always null-terminated. If any client's .SM OS shared root description is null, its path appears instead. .TP .C DCNODES_ALL Fill in the array just as for .CR DCNODES_LONGER , and then call .C dcnodes_status() with a .I mode of .C DCNODES_STATUS and a .I timeout value of 10 seconds to also fill in .C dcn_status fields (for all clients) before returning. This saves the caller from calling .C dcnodes_status() separately. .TP .C DCNODES_TYPE Ignore the .I dcnode parameter and just return .C DCN_TYPE_SERVER if the system is a cluster server, .C DCN_TYPE_CLIENT if it is a cluster client, or .C DCN_TYPE_STANDALONE if it is a standalone system (it has a local root and no remote-root clients are configured). When .C dcnodes() is called on a remote-root client with this .I mode it does not contact the cluster server. .RE .IP "" 15 The returned array exists in static space (malloc'd memory \(em see .IR malloc (3C)). This memory is overwritten by the next call, so previously returned pointers become invalid after the next call. .TP .C dcnodes_status() Using an array of .C dcnode structures containing one or more elements, .C dcnodes_status() obtains information on the status of each node from the dcnodes status daemon ( .C dcnodesd ). Information from the daemon is matched with a .C dcnode array entry by .C dcnodes_status() uses the .C dcn_ipaddr field in each .C dcnode structure if it is non-null, and not equal to the value .CR DCN_VALUE_UNKNOWN ; otherwise, it uses the .C dcn_name field in the .C dcnodes structure. .C dcnodes_status() then fills in the .C dcn_status field for each node's element. See .RB `` "Status Fields" '' below for a description of possible field values. .IP Pass the function a mode .RI ( mode ) value which is either .C DCNODES_STATUS or .CR DCNODES_STATUS_DETAILS , a count .RI ( num_dcnodes ) of the number of nodes to process, and a pointer .RI ( dcnode ) to the first element of the array. If any node's .SM IP address is not specified, it converts the node's name to an .SM IP address using .C gethostbyname() (see .IR gethostent (3N)). .IP Also pass the function a timeout value in seconds. This value is the number of seconds that must elapse between the time that a client sends a keepalive packet to the server and the time when the client is inactive. By default, clients send keepalive packets every five seconds. A 10 second timeout, then, means that any timestamp older than 10 seconds is considered invalid and the client is marked as inactive. .TP .C dcnodes_status_string() This function takes a .I mode value .RC ( DCNODES_SHORT or .CR DCNODES_LONG ) and a client status value (the .C dcn_status field, any of .CR DCN_STATUS_ *), and returns a constant or static string equivalent (changed or overwritten by the next call to this function or to .CR catgets() ), in either short or long form. If the status value is .C DCN_STATUS_UNKNOWN or any unrecognized value, the returned string is the value of .CR DCN_VALUE_UNKNOWN . .TP .C dcnodes_error_string() This function takes a return value from .C dcnodes() or .CR dcnodes_status() and returns a constant or static string (changed or overwritten by the next call to this function or to .CR catgets() ), that describes the error condition, suitable for use in an error message. The string begins with an uppercase letter but lacks a trailing period. If the error condition has an .C errno value associated (see .SM "RETURN VALUE" below), the global .C errno value is interpreted as part of the returned error message. If the value passed to .C dcnodes_error_string() is unrecognized, it returns an appropriate message. .TP .C dcnodes_server_ipaddr() This function looks up the internet address part of the mount point for .RC `` / '' and copies it to the caller's .C ipaddr buffer. The string is always null-terminated and truncated if necessary to fit. The size of the buffer and the .C len value are normally .C DCN_IPADDR_LEN + 1. .IP This function should only be called on a cluster client, that is, a remote-root system whose .RC `` / '' directory is \s-1NFS\s0-mounted. The server's .SM IP address is derived from the mount point of .RC `` / '' in the system mount table. This function assumes the server .SM ID is an .SM IP address, not a name. .TP .C dcnodes_mtime() cwThis function allows an application to avoid calling .C dcnodes() again if it's unnecessary to do so because the data hasn't changed. .C dcnodes_mtime() returns the latest mtime stamp on any file used by .C dcnodes() to return its data. If none of the files exists, returns 0. .IP This function can only be called on a cluster server. .TP .C enddcnodes() Frees any malloc'd memory previously allocated by .CR dcnodes() . (Do not call .C free() on a .I dcnode pointer previously passed to .CR dcnodes() , because .C dcnodes() does this itself.) Memory is only allocated by calls to .C dcnodes() with .CR DCNODES_LONG , .CR DCNODES_LONGER , .CR DCNODES_ALL , or .C DCNODES_SHORT with a non-null .C dcnode pointer. .PP Note that a system with a local root directory (root volume) is considered to be standalone or a cluster server as appropriate, not a cluster client, even if most of its files are \s-1NFS\s0-mounted from other systems. .\" ----------- .SS Status Fields The .C dcn_status field for each node is set to one of the following values (defined in .CR dcnodes.h ) by .C dcnodes_status() when it is called using a .I mode parameter of .CR DCNODES_STATUS : .TP 22 .C DCN_STATUS_UNKNOWN Default value from .CR dcnodes() ; also used if the node name and .SM IP address passed to .C dcnodes_status() are both null or equal to the value of .CR DCN_VALUE_UNKNOWN . .TP .C DCN_STATUS_STANDALONE System on which .C dcnodes_status() was invoked is up with a local root volume and has no remote-root clients configured. .TP .C DCN_STATUS_SERVER Cluster (root) server, which is necessarily ``up''. .TP .C DCN_STATUS_ACTIVE Node is up as a remote-root client of the local cluster. It allows .C rcmd() from the cluster (root) server and identifies that system as its root server. Note that all nodes in a cluster are normally configured to allow .C rcmd() access, at least to privileged users, between the cluster server and clients. .TP .C DCN_STATUS_INACTIVE Node has an unknown name (cannot look up internet address), does not respond to or does not allow .C rcmd() from the cluster (root) server, is up standalone (local-rooted), or is booted on another root server. A node is marked inactive if anything goes wrong, including timeout, while trying to check that is it active. .PP If the .I mode parameter is .CR DCNODES_STATUS_DETAILS , instead of marking a client with .C DCN_STATUS_INACTIVE its status value is one of the following: .TP 22 .C DCN_STATUS_NO_IP_ADDR A .C dcn_name value was provided, .C dcn_ipaddr was not, and the given client name is unknown to the hosts database (cannot be mapped to an .SM IP address). .TP .C DCN_STATUS_NO_DATA The .C dcnodesd daemon could not be contacted, or had no data for the specified client. .\" =========== .SH EXTERNAL INFLUENCES .SS Environment Variables .C LANG specifies the language used to return messages from .C dcnodes_status_string() and .CR dcnodes_error_string() . .PP If .C LANG is not specified or is set to the empty string, a default of ``C'' (see .IR lang (5)) is used instead of .CR LANG . If any internationalization variable contains an invalid setting, the string functions behave as if all internationalization variables are set to ``C''. See .IR environ (5). .\" =========== .SH RETURN VALUE Upon successful completion, .C dcnodes() and .C dcnodes_status() return the number of array elements in the list. This value is 1 or greater, except if .C dcnodes_status() is called with .I num_dcnodes less than 1, it returns 0, and if it is called on a cluster client with more than about 10Kb worth of node names, it returns the number of array elements for which status was set (see .SM WARNINGS below). .PP If .C dcnodes() is called with .CR DCNODES_SHORT , the number of array elements is the number of cluster nodes; with .CR DCNODES_LONG , .CR DCNODES_LONGER , or .CR DCNODES_ALL , there are more elements than dcnodes if the server has multiple .SM LAN cards; with .CR DCNODES_TYPE , the return value is .C DCN_TYPE_STANDALONE (standalone system), .C DCN_TYPE_SERVER (cluster server), or .C DCN_TYPE_CLIENT (cluster client). .PP In case of error, .C dcnodes() and .C dcnodes_status() return a negative value, and do not alter the .I dcnode parameter. .TP 20 .C DCN_ERR_MEMORY Cannot allocate memory to hold the returned array (for .CR dcnodes() ) or an internal array (for .CR dcnodes_status() ); .C errno is set. .PP The following errors are returned if called on a cluster client when there is difficulty contacting, and reading information from, the client's cluster (root) server. .TP 20 .C DCN_ERR_IPADDR Cannot determine the server's .SM IP address from the .RC `` / '' mount point. .TP .C DCN_ERR_RCMD Cannot call .C rcmd() to get information from the server. Problems include failure to find service ``shell'' of type ``tcp'' in the services database, or the effective user's name in the accounts database. .TP .C DCN_ERR_FDOPEN Cannot map file descriptor to a stream using .C fdopen() (see .IR fdopen (3S)); .C errno is set. .TP .C DCN_ERR_STARTUP .C dcnodes command on the server did not return a data format version number. The command might be missing or non-executable, or might have failed before issuing a version number. .TP .C DCN_ERR_VERSION .C dcnodes command on the server did not return the expected data format version number. The command is incompatible with the local version of the .C dcnodes() or .C dcnodes_status() function. .TP .C DCN_ERR_EXEC .C dcnodes command on the server failed (returned -1) after issuing a correct data format version number. The reason is unknown. .TP .C DCN_ERR_READ .C dcnodes command on the server failed (returned wrong amount of data) after issuing a correct data format version number. The reason is unknown. In this case only, .C dcnodes_status() might have modified some of the .C dcn_status fields in the .C dcnode parameter (array). .PP .C dcnodes_server_ipaddr() returns 0 if it sets .C ipaddr successfully. It returns .CR DCN_ERR_IPADDR , and .C ipaddr is unchanged, if it cannot find .RC `` / '' in the system mount table, or if .RC `` / '' is not \s-1NFS\s0-mounted. .\" =========== .SH EXAMPLES The following code fragment obtains all but status information for all members of the cluster on which it is run, and then fills in basic status information for the first three clients (after the cluster server's entries), or for as many clients as there are if there are fewer than three, with a timeout of 20 seconds. .nf .RS .ifn \f3 .ift \f4 #include int num_dcnodes; /* count of nodes */ dcnp_t dcnp; /* node information */ int index; /* in dcnp */ if ((num_dcnodes = dcnodes (\s-1DCNODES_LONG\s0, & dcnp)) <= 0) { \f2(handle error)\fP ... dcnodes_error_string (num_dcnodes) ... } /* skip standalone/server entries: */ for (index = 1; index < num_dcnodes; ++index) if (dcnp[index].dcn_status == DCN_STATUS_UNKNOWN)) break; if (index < num_dcnodes) /* have one or more clients */ { int num_clients = num_dcnodes - index; if (dcnodes_status (\s-1DCNODES_STATUS\s0, dcnp + index, (num_clients < 3) ? num_clients : 3, /* timeout = */ 20) < 0) { \f2(handle error)\fP } ... dcnodes_status_string (\s-1DCNODES_SHORT\s0, dcnp -> dcn_status) ... } .fi .RE .ft P .\" =========== .SH WARNINGS These functions are unsafe in multi-thread applications. .PP Using .C dcnodes() it is possible to distinguish between standalone, server, and client systems, and behave differently depending on the system type. However, it is desirable that applications not make this distinction, and it is usually found to be unnecessary upon closer analysis. .PP .C dcnodes() uses .C malloc() and .C free() to manage the memory for the array it returns. If desired, save a copy of an old array in new memory before calling .C dcnodes() again with a non-null .I dcnode pointer. Call .CR enddcnodes() , not .CR free() , to release the current array when it's no longer needed. .PP .C dcnodes_status() expects to be called only with cluster client names or .SM IP addresses obtained via .CR dcnodes() . It assumes each specified host is a cluster member. It does not check for or distinguish non-members. They appear to be inactive clients. .PP On a cluster client .C dcnodes_status() does not build a command line (to run on the cluster server) with a length greater than 10 kilobytes. It ignores (does not modify status field for) any additional clients whose names or .SM IP addresses don't fit, and returns the number of clients for which status was determined. .PP Normally the cluster server system provides boot, root, and .SM OS shared root services to all client nodes in its cluster. If boot, root, and/or .SM OS shared root services are provided by separate systems, .C dcnodes() and .C dcnodes_status() might return incomplete information, that is, field values of .CR DCN_VALUE_UNKNOWN . They consider the cluster clients of a root server system to be those appearing in the system's list of configured cluster client nodes (see .SM FILES below). When invoked on a remote-root client, they return information about the cluster nodes listed for the client's root server system, using information in files on that server system. If any file is missing (or any error occurs trying to access it), .C dcnodes() and .C dcnodes_status() do not complain, but return incomplete data. .PP The .C dcnodes() and .C dcnodes_status() functions call .C rcmd() to reach the cluster server when called on a cluster client. To ensure success, .C dcnodes() and .C dcnodes_status() on a cluster client should only be invoked by programs running with appropriate privilege to use .C rcmd() to reach the cluster server. Also, .C rcmd() writes messages to standard error in case of failure, and can cause log entries in the syslog files on the target systems if .C inetd is run with the .C -l option (see .IR inetd (1M)). .\" ----------- .SS Performance Issues .C dcnodes_status() might run much faster if .C dcn_ipaddr is specified for each client (not just .CR dcn_name ), because it does not have to look up each client's internet addresses in the hosts database (although this does allow .C dcnodes_status() to try all of the addresses, if necessary, to reach a client). .PP If .C dcnodes_status() is invoked on a cluster client with just that system's name in the dcnodes list, it still contacts the cluster server to determine that the system is active. This is inefficient. .\" =========== .SH AUTHOR .PP These functions were developed by .SM HP. .\" =========== .SH FILES .TP 25 .C /etc/clients.dc list of configured cluster client nodes that receive root service from a system; blank and comment lines (starting with .RC `` # '') are allowed and ignored .TP .C /etc/bootptab control file for .C bootpd (see .IR bootpd (1M)) that contains most of the client information returned by .C dcnodes() .\" =========== .SH SEE ALSO swlist(1), bootpd(1M), dcnodes(1M), dcnodesd(1M), inetd(1M), gethostname(2), setrlimit(2), setuid(2), gethostent(3N), fdopen(3S), malloc(3C), rcmd(3N). .\" .\" toc@\f3dcnodes(3X)\f1:\0\0\f4dcnodes\f1, \f4dcnodes_status\f1, \f4dcnodes_status_string\f1, \f4dcnodes_error_string\f1,\n\f4dcnodes_server_ipaddr\f1, \f4dcnodes_mtime\f1, \f4enddcnodes\f1@@@diskless cluster node information .\" .\" index@\f4dcnodes\f1 \- diskless cluster node information@@@\f3dcnodes(3X)\f1 .\" index@\f1report on diskless cluster nodes@@@\f3dcnodes(3X)\f1 .\" index@\f1diskless cluster nodes, report information about@@@\f3dcnodes(3X)\f1 .\" .\" links@dcnodes.3x dcnodes_status.3x .\" links@dcnodes.3x dcnodes_server_ipaddr.3x .\" links@dcnodes.3x enddcnodes.3x .\" $Header: getdvagent.3,v 72.3 94/07/05 17:58:22 ssa Exp $ .TA g .TH getdvagent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getdvagent, getdvagnam, setdvagent, enddvagent, putdvagnam, copydvagent \- manipulate device assignment database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct dev_asg \(**getdvagent(\|);" .PP .CR "struct dev_asg \(**getdvagnam(const char \(**name);" .PP .CR "void setdvagent(\|);" .PP .CR "void enddvagent(\|);" .PP .CR "int putdvagnam(const char \(**name, struct dev_asg \(**dv);" .PP .CR "struct dev_asg \(**copydvagent(struct dev_asg \(**dv);" .fi .SH DESCRIPTION .IR getdvagent , .IR getdvagnam , and .I copydvagent each return a pointer to an object with the following structure containing the broken-out fields of an entry in the Device Assignment database. Each database entry is returned as a .I dev_asg structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v struct dev_field { char *fd_name; /* external name */ char **fd_devs; /* device list */ mask_t fd_type[1]; /* tape, printer, terminal */ char **fd_users; /* authorized user list */ }; .IP /* Device Assignment Database entry */ .IP #define \s-1AUTH_DEV_TYPE\s0 "device type" #define \s-1AUTH_DEV_PRINTER\s0 0 #define \s-1AUTH_DEV_TERMINAL\s0 1 #define \s-1AUTH_DEV_TAPE\s0 2 #define \s-1AUTH_DEV_REMOTE\s0 3 #define \s-1AUTH_MAX_DEV_TYPE\s0 3 #define \s-1AUTH_DEV_TYPE_SIZE\s0 (\s-1WORD_OF_BIT\s0 (\s-1AUTH_MAX_DEV_TY PE\s0) + 1) .IP /* this structure tells which of the corresponding fields * in dev_field are valid (filled). */ struct dev_flag { unsigned short fg_name : 1, fg_devs : 1, fg_type : 1, fg_users : 1, ; }; .IP struct dev_asg { struct dev_field ufld; struct dev_flag uflg; struct dev_field sfld; struct dev_flag sflg; }; .fi .PP The Device Assignment database stores device characteristics that are related to user authorizations and synonyms. On systems supporting network connections, the Device Assignment database stores information about hosts initiating connections. .PP Each entry contains a .IR name , which is a cross reference to the terminal control database, and a list of .IR devices , each of which is a pathname corresponding to that device. This list allows the device assignment software of the trusted system to invalidate all references to a device when re-assigning it. The list is a table of character string pointers, whose last entry is a .SM .B NULL pointer. .PP .I fd_users is a pointer to a null-terminated table of character string pointers referring to user allowed access. .PP For trusted system versions supporting network connections, the device name can be a 12 character host name, where the first 8 characters are the .SM ASCII hex address of the device, and the last 4 characters are .SM ASCII zeroes. For example, a host with Internet address 129.75.0.3 has device name 814b00030000. The trailing four zeroes are for compatibility with ports on terminal concentrators. The SAM API's supports conversion of host name to device name. Thus, sensitivity level ranges and user authorization lists can be enforced on hosts as well as on directly connected terminals. .PP When .I getdvagent is first called, it returns a pointer to the first device assignment entry. Thereafter, it returns a pointer to the next entry, so successive calls can be used to search the database. .I getdvagnam searches from the beginning of the database until an entry with a device name matching .I name is found, and returns a pointer to that entry. If an end of file or an error is encountered on reading, these functions return a .SM .B NULL pointer. .I copydvagent copies a device assignment structure and the fields to which it refers to a newly-allocated data area. Since .IR getdvagent , .IR getdvagnam , and .I putdvagent re-use a static structure when accessing the database, the values of any entry must be saved if these routines are used again. The .I dev_asg structure returned by .I copydvagent can be freed using .I free (see .IR malloc (3C) or .IR malloc (3X)). .PP A call to .I setdvagent has the effect of setting the device assignment database back to the first entry, to allow repeated searches of the database. .I enddvagent frees all memory and closes all files used to support these routines. .PP .I putdvagnam rewrites or adds an entry to the database. If there is an entry whose .I fd_name field matches the .I name argument, that entry is replaced with the contents of the .I dv structure. Otherwise, that entry is added to the database. .SH RETURN VALUE .IR getdvagent and .IR getdvagnam return a pointer to a static structure on success, or a .SM .B NULL pointer on failure. This static structure is overwritten by .IR getdvagent , .IR getdvagnam , and .IR putdvagnam . .PP .I putdvagnam returns 1 on success, or 0 on failure. .PP .I copydvagent returns a pointer to the newly-allocated structure on success, or a .SM .B NULL pointer if there was a memory allocation error. .SH "WARNINGS" The structure returned by this routine contains .I pointers to character strings and lists rather than being self-contained. .I copydvagent must be used instead of structure assignments to save a returned structure. .PP The value returned by .I getdvagent and .I getdvagnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using .I copydvagent and supply the modified buffer to .IR putdvagent . .SH NOTES Programs using this routine must be compiled with .BR \-lsec . .SH AUTHOR SecureWare Inc. .SH FILES .TP 40 .CR /tcb/files/devassign Device assignment database .PD .SH SEE ALSO authcap(4). .\" .\" index@\f4getdvagent\f1 \- return pointer for device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f1getdvagnam\f1 \- return success or failure information@@@\f3getdvagent(3)\f1 .\" index@\f4setdvagent\f1 \- set device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f4enddvagent\f1 \- free memory and close file@@@\f3getdvagent(3)\f1 .\" index@\f4putdvagnam\f1 \- add or rewrite device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f4copydvagent\f1 \- copy device assignment structure@@@\f3getdvagent(3)\f1 .\" index@\f1manipulate device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f1device assignment database entry, manipulate@@@\f3getdvagent(3)\f1 .\" index@\f1assignment database entry, manipulate device@@@\f3getdvagent(3)\f1 .\" index@\f1database entry, manipulate device assignment@@@\f3getdvagent(3)\f1 .\" .\" .\" toc@\f3getdvagent(3)\f1:\0\0\f4getdvagent\f1, \f4getdvagnam\f1, \f4setdvagent\f1, \f4enddvagent\f1, \f4putdvagnam\f1, \n\f4copydvagent\f1@@@manipulate device assignment database entry for a trusted system .\" toc@\f4getdvagent\f1:\0\0return pointer for device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4getdvagnam\f1:\0\0return success or failure information@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4setdvagent\f1:\0\0set device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4enddvagent\f1:\0\0free memory and closes file@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4putdvagnam\f1:\0\0add or rewrite device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4copydvagent\f1:\0\0copy device assignment structure@@@\f1see \f3getdvagent(3)\f1 .\" .\" .\" links@getdvagent.3 getdvagnam.3 .\" links@getdvagent.3 setdvagent.3 .\" links@getdvagent.3 enddvagent.3 .\" links@getdvagent.3 putdvagnam.3 .\" links@getdvagent.3 copydvagent.3 .\" .\" fileset_database@getdvagent.3 UX-CORE-MAN .\" $Header: exportent.3n,v 74.1 95/01/25 16:26:52 ssa Exp $ .TA e .TH exportent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME exportent(\|), getexportent(\|), setexportent(\|), addexportent(\|), remexportent(\|), endexportent(\|), getexportopt(\|) \- access exported file system information .SH SYNOPSIS .nf .C #include .C #include .PP .C "FILE *setexportent();" .PP .C "struct exportent *getexportent(FILE *fildep);" .PP .C "int addexportent(FILE *filep, char *dirname, char *options);" .PP .C "int remexportent(FILE *filep, char *dirname);" .PP .C "char *getexportopt(struct exportent *xent, char *opt);" .PP .C "void endexportent(FILE *filep);" .fi .SH DESCRIPTION These routines access the exported filesystem information in .CR /etc/xtab . .ift .TP 22 .ifn .TP 10 .C setexportent() Open the export information file and return a file pointer to use with .CR getexportent() , .CR addexportent() , .CR remexportent() , and .CR endexportent() . Returns .SM NULL if the file is locked or if an error is encountered in opening the file. .TP .C getexportent() Read the next line from .I filep and return a pointer to an object with the following structure containing the broken-out fields of a line in file .CR /etc/xtab . The fields have meanings described in .IR exports (4). .nf .IP .ift .ft 4 .ifn .ft 3 #define ACCESS_OPT "access" /* machines that can mount fs */ #define ROOT_OPT "root" /* machines with root access to fs */ #define RO_OPT "ro" /* export read-only */ #define ANON_OPT "anon" /* uid for anonymous requests */ #define ASYNC_OPT "async" /* all mounts will be aynchronous */ .ift .sp .5v .ifn .sp 1v struct exportent { char *xent_dirname; /* directory (or file) to export */ char *xent_options; /* options, as above */ }; .ft .fi .IP .C getexportent() returns .SM NULL if it encounters end of file. .TP .C addexportent() Add the .I exportent to the end of the open file .IR filep . It returns 0 if successful and \(mi1 on failure. .TP .C remexportent() Remove the indicated entry from the list. Returns 0 on success and \(mi1 on failure. .TP .C getexportopt() Scans the .C xent_options field of the .C exportent structure for a substring that matches .IR opt . Returns the string value of .IR opt , or .SM NULL if the option is not found. .TP .C endexportent() Close the file. .SH RETURN VALUE .CR setexportent() , .CR getexportent() , and .C getexportopt() return a .SM NULL pointer on .SM EOF or error. .PP .C addexportent() and .C remexportent() return \(mi1 if they fail. .SH WARNINGS The returned .C exportent structure points to static information that is overwritten in each call. .SH AUTHOR .CR exportent , .CR getexportent() , .CR setexportent() , .CR addexportent() , .CR remexportent() , .CR endexportent() , and .C getexportopt() were developed by Sun Microsystems, Inc. .SH FILES .C /etc/exports .C /etc/xtab .SH SEE ALSO exportfs(1M), exports(4). .\" .\" toc@\f3exportent(3N)\f1:\0\0\f4exportent(\|)\f1, \f4getexportent(\|)\f1, \f4setexportent(\|)\f1, \f4addexportent(\|)\f1, \f4remexportent(\|)\f1,\n\f4endexportent(\|)\f1, \f4getexportopt(\|)\f1@@@access exported file system information .\" toc@\f4getexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4setexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4addexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4remexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4endexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4getexportopt(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" .\" index@\f4exportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4getexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4setexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4addexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4remexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4endexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4getexportopt(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@access exported file system information@@@\f3exportent(3N)\f1 .\" index@exported file system information, access@@@\f3exportent(3N)\f1 .\" index@file system information, access exported@@@\f3exportent(3N)\f1 .\" index@information, access exported file system@@@\f3exportent(3N)\f1 .\" .\" links@exportent.3n getexporten.3n .\" links@exportent.3n setexporten.3n .\" links@exportent.3n addexporten.3n .\" links@exportent.3n remexporten.3n .\" links@exportent.3n endexporten.3n .\" links@exportent.3n getexportop.3n .\" .\" fileset_database@exportent.3n PROGRAMING-MAN .\" $Header: getfsent.3x,v 72.4 94/11/02 14:55:23 ssa Exp $ .TA g .TH getfsent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getfsent(\|), getfsspec(\|), getfsfile(\|), getfstype(\|), setfsent(\|), endfsent(\|) \- get file system descriptor file entry .SH SYNOPSIS .C "#include " .PP .C "struct checklist *getfsent(void);" .PP .C "struct checklist *getfsspec(const char *spec);" .PP .C "struct checklist *getfsfile(const char *file);" .PP .C "struct checklist *getfstype(const char *type);" .PP .C "int setfsent(void);" .PP .C "int endfsent(void);" .SS Remarks: These routines are included only for compatibility with 4.2 .SM BSD. For maximum portability and improved functionality, new applications should use the .IR getmntent (3X) library routines. .SH DESCRIPTION .CR getfsent() , .CR getfsspec() , .CR getfsfile() , and .C getfstype() each returns a pointer to an object with the following structure containing the broken-out fields of a line in the .C /etc/fstab file. The structure is declared in the .RC < checklist.h > header file: .nf .IP .C "struct checklist {" .C " char *fs_spec; /* special file name */" .C " char *fs_bspec; /* block special file name */" .C " char *fs_dir; /* file sys directory name */" .C " char *fs_type; /* type: ro, rw, sw, xx */" .C " int fs_passno; /* fsck pass number */" .C " int fs_freq; /* backup frequency */" .C }; .fi .PP The fields have meanings described in .IR fstab (4). If the block special file name, the file system directory name, and the type are not all defined on the associated line in .CR /etc/fstab , these routines return pointers to .SM NULL in the .CR fs_bspec , .CR fs_dir , and .C fs_type fields. If the pass number or the backup frequency field are not present on the line, these routines return \(mi1 in the corresponding structure member. .C fs_freq is reserved for future use. .TP 20 .C getfsent() Reads the next line of the file, opening the file if necessary. .TP .C setfsent() Opens and rewinds the file. .TP .C endfsent() Closes the file. .TP .C getfsspec() Sequentially searches from beginning of file until a matching special file name is found, or until .SM EOF is encountered. .TP .C getfsfile() Sequentially searches from the beginning of the file until a matching file system file name is found, or until .SM EOF is encountered. .C getfstype() Sequentially searches from the beginning of the file until a matching file system type field is found, or until .SM EOF is encountered. .SH DIAGNOSTICS A null pointer is returned on .SM EOF, invalid entry, or error. .SH WARNINGS Since all information is contained in a static area, it must be copied to be saved. .SH AUTHOR .C getfsent() was developed by HP and the University of California, Berkeley. .SH FILES .C /etc/fstab .SH SEE ALSO fstab(4). .\" index@\f4getfsent()\fP \- get next line in file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@\f4getfsspec()\fP \- search descriptor file for special (device) file entry@@@\f3getfsent(3X)\f1 .\" index@\f4getfsfile()\fP \- search descriptor file for ordinary file entry@@@\f3getfsent(3X)\f1 .\" index@\f4getfstype()\fP \- search descriptor file for specified file type entry@@@\f3getfsent(3X)\f1 .\" index@\f4setfsent()\fP \- open and rewind file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@\f4endfsent()\fP \- close file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@get: file system descriptor file entry (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@file system: get file system descriptor file entry (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@descriptor file entry, get file system (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@file entry, get file system descriptor (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@entry, get file system descriptor file (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" .\" toc@\f3getfsent(3X)\f1:\0\0\f4getfsent()\fP, \f4getfsspec()\fP, \f4getfsfile()\fP, \f4getfstype()\fP,\n\f4setfsent()\fP, \f4endfsent()\fP@@@get file system descriptor file entry .\" toc@\f4getfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfsspec()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfsfile()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfstype()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4setfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4endfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" .\" links@getfsent.3x getfsspec.3x .\" links@getfsent.3x getfsfile.3x .\" links@getfsent.3x getfstype.3x .\" links@getfsent.3x setfsent.3x .\" links@getfsent.3x endfsent.3x .\" .\" fileset_database@getfsent.3x PROGRAMING-MAN .\" $Header: getgrent.3c,v 76.1 95/07/05 17:29:02 ssa Exp $ .TA g .TH getgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getgrent(\|), getgrent_r(\|), getgrgid(\|), getgrgid_r(\|), getgrnam(\|), getgrnam_r(\|), setgrent(\|), setgrent_r(\|), endgrent(\|), endgrent_r(\|), fgetgrent(\|), fgetgrent_r(\|) \- get group file entry .SH SYNOPSIS .C "#include " .PP .C "struct group *getgrent(void);" .PD 0 .PP .C "int getgrent_r(" .nf .PD 0 .IP .C "struct group *result," .C "char *buffer," .C "int buflen," .C "FILE **grfp);" .PD 0 .PP .C "struct group *getgrgid(gid_t gid);" .PP .C "int getgrgid_r(" .nf .PD 0 .IP .C "gid_t gid," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "struct group *getgrnam(const char *name);" .PP .C "int getgrnam_r(" .nf .PD 0 .IP .C "const char *name," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "void setgrent(void);" .PP .C "void setgrent_r(FILE **grfp);" .PP .C "void endgrent(void);" .PP .C "void endgrent_r(FILE **grfp);" .PP .C "struct group *fgetgrent(FILE *stream);" .PP .C "int fgetgrent_r(" .nf .PD 0 .IP .C "FILE *stream," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD .SH DESCRIPTION .CR getgrent() , .CR getgrgid() , and .CR getgrnam() locate an entry in the .CR /etc/group file, and return a pointer to an object of type .CR "struct group" . .PP The .CR group structure is defined in .RC < grp.h > and includes the following members: .nf .IP .C "char *gr_name; /* the name of the group */" .C "char *gr_passwd; /* the encrypted group password */" .C "gid_t gr_gid; /* the numerical group \s-1ID\s+1 */" .C "char **gr_mem; /* null-terminated array of pointers" .C " to member names */" .fi .TP 20 .C getgrent() When first called, .CR getgrent() returns a pointer to the first .CR group structure in the file; thereafter, it returns a pointer to the next .CR group structure in the file. In this way, successive calls can be used to search the entire file. .CR getgrent() opens the .CR /etc/group file prior to doing its work and leaves the file open afterward; .TP .C setgrent() Has the effect of rewinding this file to allow repeated searches; .TP .C endgrent() Can be called to close the file when processing is complete. .TP .C getgrgid() Searches from the beginning of the file until a numeric group ID matching .I gid is found, and returns a pointer to the particular structure in which it was found. .TP .C getgrnam() Searches from the beginning of the file until a group name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .C fgetgrent() Returns a pointer to the next .CR group structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/group . .SS Reentrant Interfaces .CR getgrgid_r() , .CR getgrnam_r() and .CR fgetgrent_r() expect to be passed three extra parameters: .PD 0 .TP 3 1. The address of a .C "struct group" where the result will be stored; .TP 2. A buffer to store character strings, such as the group name, to which fields in the .C "struct group" will point; .TP 3. The length of the user-supplied buffer. .PD .PP In addition to the above three parameters, .CR getgrent_r() requires a pointer to a .I "(FILE *)" variable into which is stored the result of an .I fopen() call on the .CR /etc/group file. This parameter allows threads to independently scan through the .CR /etc/group file. .CR setgrent_r() and .CR endgrent_r() are to be used only in conjunction with .CR getgrent_r() and take the same pointer to a .I "(FILE *)" variable as a parameter. .CR setgrent_r() can be used to rewind or open the .CR /etc/group file. .CR endgrent_r() must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .I "(FILE *)" variable must be initialized to NULL before it is passed to either .CR getgrent_r() or .CR setgrent_r() for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH NETWORKING FEATURES .SS NFS If an entry beginning with a plus sign .RC ( + ) or a minus sign .RC (\| \(mi \|) is found, these routines try to use the Network Information Service network database for data. See .IR group (4) for proper syntax and operation. .SH RETURN VALUE .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .CR group structure. .PP .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , and .CR fgetgrent_r() return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getgrent() , .CR getgrgid() , .CR getgrnam() and .CR fgetgrent() fail if any of the following are true: .RS .TP 12 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX file descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .PD .RE .SH EXAMPLE The following code excerpt counts the number of entries in the .CR /etc/group file: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct group gpbuf; char buffer[1024]; FILE *grf = NULL; setgrent_r(&grf); while (getgrent_r(&gpbuf, buffer, sizeof(buffer), &grf) != -1) count++; endgrent_r(&grf); .ft .ps .fi .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library. This causes them to increase the size of programs that do not otherwise use standard I/O and Network Information Service more than might ordinarily be expected. .PP The value returned by .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() points to a single static area that is overwritten by each call to any of the functions. It must be copied if it is to be saved. .PP .CR getgrent() , .CR getgrgid() , .CR getgrnam() , .CR setgrent() , .CR endgrent() , and .CR fgetgrent() are unsafe in multi-thread applications. .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , .CR setgrent_r() , .CR endgrent_r() , and .CR fgetgrent_r() are MT-Safe and should be used instead. .PP Users of .CR getgrent_r() and .CR getgrnam_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH DEPENDENCIES .SS NFS: .br .B FILES .RS .CI /var/yp/ domainname /group.byname .br .CI /var/yp/ domainname /group.bygid .RE .SM .B SEE ALSO: .RS ypcat(1). .RE .SH FILES .C /etc/group .SH SEE ALSO getgroups(2), getpwent(3C), stdio(3S), group(4). .SH STANDARDS CONFORMANCE .CR getgrent() ": SVID2, SVID3, XPG2" .PP .CR endgrent() ": SVID2, SVID3, XPG2" .PP .CR fgetgrent() ": SVID2, SVID3, XPG2" .PP .CR getgrgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgrnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setgrent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getgrent()\f1 \- get next entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4fgetgrent()\f1 \- get next entry in \f4group()\f1-file-formatted input stream@@@\f3getgrent(3C)\f1 .\" index@\f4getgrgid()\f1 \- get entry from \f4group()\f1 file that matches \f4gid()\fP@@@\f3getgrent(3C)\f1 .\" index@\f4getgrnam()\f1 \- get entry from \f4group()\fP file that matches group name \f4name()\f1@@@\f3getgrent(3C)\f1 .\" index@\f4setgrent()\f1 \- rewind pointer to first entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4endgrent()\f1 \- close currently open \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@get: entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@entry from \f4group()\f1 file, get@@@\f3getgrent(3C)\f1 .\" index@\f4group()\f1 file, get entry from@@@\f3getgrent(3C)\f1 .\" index@file, group: get entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" .\" toc@\f3getgrent(3C)\f1:\0\0\f4getgrent()\f1, \f4getgrgid()\f1, \f4getgrnam()\f1, \f4setgrent()\f1, \f4endgrent()\f1,\n \f4fgetgrent()\f1@@@get group file entry .\" toc@\f4getgrgid()\fP, \f4getgrnam()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4setgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4endgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4fgetgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" .\" links@getgrent.3c getgrent_r.3c .\" links@getgrent.3c getgrgid.3c .\" links@getgrent.3c getgrgid_r.3c .\" links@getgrent.3c getgrnam.3c .\" links@getgrent.3c getgrnam_r.3c .\" links@getgrent.3c setgrent.3c .\" links@getgrent.3c setgrent_r.3c .\" links@getgrent.3c endgrent.3c .\" links@getgrent.3c endgrent_r.3c .\" links@getgrent.3c fgetgrent.3c .\" links@getgrent.3c fgetgrent_r.3c .\" .\" fileset_database@getgrent.3c PROGRAMING-MAN .\" $Header: getgrent.3c,v 76.1 95/07/05 17:29:02 ssa Exp $ .TA g .TH getgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getgrent(\|), getgrent_r(\|), getgrgid(\|), getgrgid_r(\|), getgrnam(\|), getgrnam_r(\|), setgrent(\|), setgrent_r(\|), endgrent(\|), endgrent_r(\|), fgetgrent(\|), fgetgrent_r(\|) \- get group file entry .SH SYNOPSIS .C "#include " .PP .C "struct group *getgrent(void);" .PD 0 .PP .C "int getgrent_r(" .nf .PD 0 .IP .C "struct group *result," .C "char *buffer," .C "int buflen," .C "FILE **grfp);" .PD 0 .PP .C "struct group *getgrgid(gid_t gid);" .PP .C "int getgrgid_r(" .nf .PD 0 .IP .C "gid_t gid," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "struct group *getgrnam(const char *name);" .PP .C "int getgrnam_r(" .nf .PD 0 .IP .C "const char *name," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "void setgrent(void);" .PP .C "void setgrent_r(FILE **grfp);" .PP .C "void endgrent(void);" .PP .C "void endgrent_r(FILE **grfp);" .PP .C "struct group *fgetgrent(FILE *stream);" .PP .C "int fgetgrent_r(" .nf .PD 0 .IP .C "FILE *stream," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD .SH DESCRIPTION .CR getgrent() , .CR getgrgid() , and .CR getgrnam() locate an entry in the .CR /etc/group file, and return a pointer to an object of type .CR "struct group" . .PP The .CR group structure is defined in .RC < grp.h > and includes the following members: .nf .IP .C "char *gr_name; /* the name of the group */" .C "char *gr_passwd; /* the encrypted group password */" .C "gid_t gr_gid; /* the numerical group \s-1ID\s+1 */" .C "char **gr_mem; /* null-terminated array of pointers" .C " to member names */" .fi .TP 20 .C getgrent() When first called, .CR getgrent() returns a pointer to the first .CR group structure in the file; thereafter, it returns a pointer to the next .CR group structure in the file. In this way, successive calls can be used to search the entire file. .CR getgrent() opens the .CR /etc/group file prior to doing its work and leaves the file open afterward; .TP .C setgrent() Has the effect of rewinding this file to allow repeated searches; .TP .C endgrent() Can be called to close the file when processing is complete. .TP .C getgrgid() Searches from the beginning of the file until a numeric group ID matching .I gid is found, and returns a pointer to the particular structure in which it was found. .TP .C getgrnam() Searches from the beginning of the file until a group name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .C fgetgrent() Returns a pointer to the next .CR group structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/group . .SS Reentrant Interfaces .CR getgrgid_r() , .CR getgrnam_r() and .CR fgetgrent_r() expect to be passed three extra parameters: .PD 0 .TP 3 1. The address of a .C "struct group" where the result will be stored; .TP 2. A buffer to store character strings, such as the group name, to which fields in the .C "struct group" will point; .TP 3. The length of the user-supplied buffer. .PD .PP In addition to the above three parameters, .CR getgrent_r() requires a pointer to a .I "(FILE *)" variable into which is stored the result of an .I fopen() call on the .CR /etc/group file. This parameter allows threads to independently scan through the .CR /etc/group file. .CR setgrent_r() and .CR endgrent_r() are to be used only in conjunction with .CR getgrent_r() and take the same pointer to a .I "(FILE *)" variable as a parameter. .CR setgrent_r() can be used to rewind or open the .CR /etc/group file. .CR endgrent_r() must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .I "(FILE *)" variable must be initialized to NULL before it is passed to either .CR getgrent_r() or .CR setgrent_r() for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH NETWORKING FEATURES .SS NFS If an entry beginning with a plus sign .RC ( + ) or a minus sign .RC (\| \(mi \|) is found, these routines try to use the Network Information Service network database for data. See .IR group (4) for proper syntax and operation. .SH RETURN VALUE .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .CR group structure. .PP .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , and .CR fgetgrent_r() return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getgrent() , .CR getgrgid() , .CR getgrnam() and .CR fgetgrent() fail if any of the following are true: .RS .TP 12 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX file descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .PD .RE .SH EXAMPLE The following code excerpt counts the number of entries in the .CR /etc/group file: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct group gpbuf; char buffer[1024]; FILE *grf = NULL; setgrent_r(&grf); while (getgrent_r(&gpbuf, buffer, sizeof(buffer), &grf) != -1) count++; endgrent_r(&grf); .ft .ps .fi .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library. This causes them to increase the size of programs that do not otherwise use standard I/O and Network Information Service more than might ordinarily be expected. .PP The value returned by .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() points to a single static area that is overwritten by each call to any of the functions. It must be copied if it is to be saved. .PP .CR getgrent() , .CR getgrgid() , .CR getgrnam() , .CR setgrent() , .CR endgrent() , and .CR fgetgrent() are unsafe in multi-thread applications. .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , .CR setgrent_r() , .CR endgrent_r() , and .CR fgetgrent_r() are MT-Safe and should be used instead. .PP Users of .CR getgrent_r() and .CR getgrnam_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH DEPENDENCIES .SS NFS: .br .B FILES .RS .CI /var/yp/ domainname /group.byname .br .CI /var/yp/ domainname /group.bygid .RE .SM .B SEE ALSO: .RS ypcat(1). .RE .SH FILES .C /etc/group .SH SEE ALSO getgroups(2), getpwent(3C), stdio(3S), group(4). .SH STANDARDS CONFORMANCE .CR getgrent() ": SVID2, SVID3, XPG2" .PP .CR endgrent() ": SVID2, SVID3, XPG2" .PP .CR fgetgrent() ": SVID2, SVID3, XPG2" .PP .CR getgrgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgrnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setgrent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getgrent()\f1 \- get next entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4fgetgrent()\f1 \- get next entry in \f4group()\f1-file-formatted input stream@@@\f3getgrent(3C)\f1 .\" index@\f4getgrgid()\f1 \- get entry from \f4group()\f1 file that matches \f4gid()\fP@@@\f3getgrent(3C)\f1 .\" index@\f4getgrnam()\f1 \- get entry from \f4group()\fP file that matches group name \f4name()\f1@@@\f3getgrent(3C)\f1 .\" index@\f4setgrent()\f1 \- rewind pointer to first entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4endgrent()\f1 \- close currently open \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@get: entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@entry from \f4group()\f1 file, get@@@\f3getgrent(3C)\f1 .\" index@\f4group()\f1 file, get entry from@@@\f3getgrent(3C)\f1 .\" index@file, group: get entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" .\" toc@\f3getgrent(3C)\f1:\0\0\f4getgrent()\f1, \f4getgrgid()\f1, \f4getgrnam()\f1, \f4setgrent()\f1, \f4endgrent()\f1,\n \f4fgetgrent()\f1@@@get group file entry .\" toc@\f4getgrgid()\fP, \f4getgrnam()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4setgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4endgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4fgetgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" .\" links@getgrent.3c getgrent_r.3c .\" links@getgrent.3c getgrgid.3c .\" links@getgrent.3c getgrgid_r.3c .\" links@getgrent.3c getgrnam.3c .\" links@getgrent.3c getgrnam_r.3c .\" links@getgrent.3c setgrent.3c .\" links@getgrent.3c setgrent_r.3c .\" links@getgrent.3c endgrent.3c .\" links@getgrent.3c endgrent_r.3c .\" links@getgrent.3c fgetgrent.3c .\" links@getgrent.3c fgetgrent_r.3c .\" .\" fileset_database@getgrent.3c PROGRAMING-MAN .\" $Header: gethostent.3n,v 78.1 96/03/15 15:56:59 ssa Exp $ .TA g .TH gethostent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gethostent(), gethostent_r(), gethostbyaddr(), gethostbyaddr_r(), gethostbyname(), gethostbyname_r(), sethostent(), sethostent_r(), endhostent(), endhostent_r() \- get network host entry .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .PP .C "extern int h_errno;" .PP .C "struct hostent *gethostent(void);" .PP .C "int gethostent_r(struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyname(const char *name);" .PP .C "int gethostbyname_r(const char *name," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyaddr(const char *addr, .C " int len, .C " int type); .PP .C "_XOPEN_SOURCE_EXTENDED only .C "struct hostent *gethostbyaddr(const void *addr, .C " size_t len, .C " int type); .PP .C "int gethostbyaddr_r(const char *addr," .C " int len," .C " int type," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "int sethostent(int stayopen);" .PP .C "int sethostent_r(int stayopen, struct hostent_data *buffer);" .PP .C "int endhostent(void);" .PP .C "int endhostent_r(struct hostent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only .C "void sethostent(int stayopen);" .C "void endhostent(void);" .fi .SH DESCRIPTION The .CR gethostent() , .CR gethostbyname() , and .CR gethostbyaddr() functions each return a pointer to a structure of type .CR hostent , defined as follows in .CR : .nf .IP .C "struct hostent {" .C " char *h_name;" .C " char **h_aliases;" .C " int h_addrtype;" .C " int h_length;" .C " char **h_addr_list;" .C "};" .IP .C "#define h_addr h_addr_list[0]" .fi .PP The members of this structure are: .RS .TP 20 .CR h_name The official name of the host. .TP .CR h_aliases A null-terminated array of alternate names for the host. .TP .CR h_addrtype The type of address being returned; always .CR AF_INET . .TP .CR h_length The length, in bytes, of the address. .TP .CR h_addr_list A null-terminated array of network addresses for the host. .TP .CR h_addr The first address in .CR h_addr_list ; this is for compatibility with previous HP-UX implementations where a .CR "struct hostent" contains only one network address per host. .RE .SS Reentrant Interfaces .CR gethostent_r() , .CR gethostbyname_r() , and .CR gethostbyaddr_r() expect to be passed the address of a .CR "struct hostent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct hostent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct hostent" will point, as well as state information such as open file descriptors. The .CR "struct hostent_data" is defined in the header file .CR . .PP .CR sethostent_r() and .CR endhostent_r() are to be used only in conjunction with .CR gethostent_r() and take the same pointer to a .CR "struct hostent_data" as a parameter. If the Network Information Service is being used, .CR sethostent_r() initializes an internal database key. If the .CR /etc/hosts file is being used, .CR sethostent_r() opens or rewinds the file. If the .CR named name server (see .IR named (1M)) is being used, then .CR sethostent_r() has no effect. .CR endhostent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR sethostent_r() currently has no effect. However, .CR sethostent() can still be used to keep the .CR /etc/hosts file open, or to use connected stream sockets to the name server, when making calls to .CR gethostbyaddr_r() and .CR gethostbyname_r() . .PP The .I hostf field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to either .CR gethostent_r() or .CR sethostent_r() for the first time. The .I current field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to .CR gethostbyname_r() or .CR gethostbyaddr_r() for the first time. Thereafter, these fields should not be modified in any way. These are the only .CR hostent_data fields that should ever be explicitly accessed. .SS Name Service Switch-Based Operation These host entry library routines internally call the name service switch to access the "hosts" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve host names and Internet addresses. The operations of the three name services: Domain Name Server, NIS, and nonserver mode (e.g., files) are listed below. .SS Domain Name Server Operation If the local system is configured to use the .CR named name server (see .IR named(1M) and .IR resolver(4)) for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Always returns a NULL pointer. .TP .CR sethostent() , Requests the use of a connected stream socket for queries to the name server if the .I stayopen flag is non-zero. The connection is retained after each call to .CR gethostbyname() or .CR gethostbyaddr() . .TP .CR endhostent() Closes the stream socket connection. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the name server. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS NIS Server Operation If .CR ypserv, the server for the Network Information Service (see .IR ypserv (1M)), is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Returns the next entry in the NIS database. .TP .CR sethostent() Initializes an internal key for the NIS database. If the .I stayopen flag is non-zero, the internal key is not cleared after calls to .CR endhostent() . .TP .CR endhostent() Clears the internal NIS database key. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the NIS database. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS Nonserver Operation If the .CR /etc/hosts file is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Reads the next line of .CR /etc/hosts , opening the file if necessary. .TP .CR sethostent() opens and rewinds the file. If the .I stayopen flag is non-zero, the host data base is not closed after each call to .CR gethostent() (either directly or indirectly through one of the other .CR gethost calls). .TP .CR endhostent() Closes the file. .TP .CR gethostbyname() Sequentially searches from the beginning of the file until a host name (among either the official names or the aliases) matching its .I name parameter is found, or until EOF is encountered. Names are matched without respect to uppercase or lowercase, as described above in the name server case. .TP .CR gethostbyaddr() Sequentially searches from the beginning of the file until an Internet address matching its .I addr parameter is found, or until EOF is encountered. .RE .SS Arguments Currently, only the Internet address format is understood. In calls to .CR gethostbyaddr() , the parameter .I addr must be a pointer to an .IR in_addr structure, an Internet address in network order (see .IR byteorder (3N)) and the header file .CR ). The parameter .I len must be the number of bytes in an Internet address; that is, .CR "sizeof (struct in_addr)" . The parameter .I type must be the constant .CR AF_INET . .SH RETURN VALUE If successful, .CR gethostbyname() , .CR gethostbyaddr() , and .CR gethostent() return a pointer to the requested .CR hostent structure. .PP .CR gethostbyname() and .CR gethostbyaddr() return NULL if their .I host or .I addr parameters, respectively, cannot be found in the database. If .CR /etc/hosts is being used, they also return NULL if they are unable to open .CR /etc/hosts . .PP .CR gethostbyaddr() also returns NULL if either its .I addr or .I len parameter is invalid. .PP .CR gethostent() always returns NULL if the name server is being used. .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 is returned if the operation is unsuccessful or, in the case of .CR gethostent_r() , if the end of the hosts list has been reached. .CR 0 is returned otherwise. .SH ERRORS If the name server is being used and .CR gethostbyname() or .CR gethostbyaddr() returns a NULL pointer, the external integer .CR h_errno contains one of the following values: .RS .TP 23 .CR HOST_NOT_FOUND No such host is known. .TP .CR TRY_AGAIN This is usually a temporary error. The local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .CR NO_RECOVERY This is a non-recoverable error. .TP .CR NO_ADDRESS The requested name is valid but does not have an IP address; this is not a temporary error. This means another type of request to the name server will result in an answer. .RE .PP If the name server is not being used, the value of .CR h_errno may not be meaningful. .SH EXAMPLES The following code excerpt counts the number of host entries: .RS .nf .PP .C "int count = 0; .C "struct hostent htbuf; .C "struct hostent_data hdbuf; .PP .C "hdbuf.hostf = NULL; .C "(void) sethostent_r(0, &hdbuf); .C "while (gethostent_r(&htbuf, &hdbuf) != -1) .C " count++; .C "(void) endhostent_r(&hdbuf); .fi .RE .SH WARNINGS For the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR gethostent() , .CR gethostbyaddr() , .CR gethostbyname() , .CR sethostent() , and .CR endhostent() are unsafe in multi-thread applications. .CR gethostent_r() , .CR gethostbyaddr_r() , .CR gethostbyname_r() , .CR sethostent_r() , and .CR endhostent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR gethostent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/hosts .SH SEE ALSO named(1M), ypserv(1M), resolver(3N), ypclnt(3C), hosts(4), switch(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR gethostent() ": XPG4" .\" .\" index@\f1end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1entry, get, set, or end network host@@@\f3gethostent(3N)\f1 .\" index@\f1get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1host entry, get, set, or end network@@@\f3gethostent(3N)\f1 .\" index@\f1network host entry, get, set, or end@@@\f3gethostent(3N)\f1 .\" index@\f1set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1thread-safe, get, set, or end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent()\f1 \- end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent_r()\f1 \- end network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent()\f1 \- set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent_r()\f1 \- set network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" .\" links@gethostent.3n endhostent.3n .\" links@gethostent.3n endhostent_.3n .\" links@gethostent.3n gethostbyad.3n .\" links@gethostent.3n gethostbyna.3n .\" links@gethostent.3n gethostent_.3n .\" links@gethostent.3n sethostent.3n .\" links@gethostent.3n sethostent_.3n .\" .\" toc@\f3gethostent(3N)\f1:\0\0\f4endhostent()\f1, \f4endhostent_r()\f1, \f4gethostbyaddr()\f1, \f4gethostbyaddr_r()\f1,\n\f4gethostbyname()\f1, \f4gethostbyname_r()\f1, \f4gethostent()\f1, \f4gethostent_r()\f1,\n\f4sethostent()\f1, \f4sethostent_r()\f1@@@get, set, or end network host entry .\" .\" toc@\f4endhostent()\f1:\0\0end network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4endhostent_r()\f1:\0\0end network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostent_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent()\f1:\0\0set network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent_r()\f1:\0\0set network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" $Header: gethostent.3n,v 78.1 96/03/15 15:56:59 ssa Exp $ .TA g .TH gethostent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gethostent(), gethostent_r(), gethostbyaddr(), gethostbyaddr_r(), gethostbyname(), gethostbyname_r(), sethostent(), sethostent_r(), endhostent(), endhostent_r() \- get network host entry .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .PP .C "extern int h_errno;" .PP .C "struct hostent *gethostent(void);" .PP .C "int gethostent_r(struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyname(const char *name);" .PP .C "int gethostbyname_r(const char *name," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyaddr(const char *addr, .C " int len, .C " int type); .PP .C "_XOPEN_SOURCE_EXTENDED only .C "struct hostent *gethostbyaddr(const void *addr, .C " size_t len, .C " int type); .PP .C "int gethostbyaddr_r(const char *addr," .C " int len," .C " int type," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "int sethostent(int stayopen);" .PP .C "int sethostent_r(int stayopen, struct hostent_data *buffer);" .PP .C "int endhostent(void);" .PP .C "int endhostent_r(struct hostent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only .C "void sethostent(int stayopen);" .C "void endhostent(void);" .fi .SH DESCRIPTION The .CR gethostent() , .CR gethostbyname() , and .CR gethostbyaddr() functions each return a pointer to a structure of type .CR hostent , defined as follows in .CR : .nf .IP .C "struct hostent {" .C " char *h_name;" .C " char **h_aliases;" .C " int h_addrtype;" .C " int h_length;" .C " char **h_addr_list;" .C "};" .IP .C "#define h_addr h_addr_list[0]" .fi .PP The members of this structure are: .RS .TP 20 .CR h_name The official name of the host. .TP .CR h_aliases A null-terminated array of alternate names for the host. .TP .CR h_addrtype The type of address being returned; always .CR AF_INET . .TP .CR h_length The length, in bytes, of the address. .TP .CR h_addr_list A null-terminated array of network addresses for the host. .TP .CR h_addr The first address in .CR h_addr_list ; this is for compatibility with previous HP-UX implementations where a .CR "struct hostent" contains only one network address per host. .RE .SS Reentrant Interfaces .CR gethostent_r() , .CR gethostbyname_r() , and .CR gethostbyaddr_r() expect to be passed the address of a .CR "struct hostent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct hostent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct hostent" will point, as well as state information such as open file descriptors. The .CR "struct hostent_data" is defined in the header file .CR . .PP .CR sethostent_r() and .CR endhostent_r() are to be used only in conjunction with .CR gethostent_r() and take the same pointer to a .CR "struct hostent_data" as a parameter. If the Network Information Service is being used, .CR sethostent_r() initializes an internal database key. If the .CR /etc/hosts file is being used, .CR sethostent_r() opens or rewinds the file. If the .CR named name server (see .IR named (1M)) is being used, then .CR sethostent_r() has no effect. .CR endhostent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR sethostent_r() currently has no effect. However, .CR sethostent() can still be used to keep the .CR /etc/hosts file open, or to use connected stream sockets to the name server, when making calls to .CR gethostbyaddr_r() and .CR gethostbyname_r() . .PP The .I hostf field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to either .CR gethostent_r() or .CR sethostent_r() for the first time. The .I current field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to .CR gethostbyname_r() or .CR gethostbyaddr_r() for the first time. Thereafter, these fields should not be modified in any way. These are the only .CR hostent_data fields that should ever be explicitly accessed. .SS Name Service Switch-Based Operation These host entry library routines internally call the name service switch to access the "hosts" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve host names and Internet addresses. The operations of the three name services: Domain Name Server, NIS, and nonserver mode (e.g., files) are listed below. .SS Domain Name Server Operation If the local system is configured to use the .CR named name server (see .IR named(1M) and .IR resolver(4)) for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Always returns a NULL pointer. .TP .CR sethostent() , Requests the use of a connected stream socket for queries to the name server if the .I stayopen flag is non-zero. The connection is retained after each call to .CR gethostbyname() or .CR gethostbyaddr() . .TP .CR endhostent() Closes the stream socket connection. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the name server. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS NIS Server Operation If .CR ypserv, the server for the Network Information Service (see .IR ypserv (1M)), is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Returns the next entry in the NIS database. .TP .CR sethostent() Initializes an internal key for the NIS database. If the .I stayopen flag is non-zero, the internal key is not cleared after calls to .CR endhostent() . .TP .CR endhostent() Clears the internal NIS database key. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the NIS database. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS Nonserver Operation If the .CR /etc/hosts file is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Reads the next line of .CR /etc/hosts , opening the file if necessary. .TP .CR sethostent() opens and rewinds the file. If the .I stayopen flag is non-zero, the host data base is not closed after each call to .CR gethostent() (either directly or indirectly through one of the other .CR gethost calls). .TP .CR endhostent() Closes the file. .TP .CR gethostbyname() Sequentially searches from the beginning of the file until a host name (among either the official names or the aliases) matching its .I name parameter is found, or until EOF is encountered. Names are matched without respect to uppercase or lowercase, as described above in the name server case. .TP .CR gethostbyaddr() Sequentially searches from the beginning of the file until an Internet address matching its .I addr parameter is found, or until EOF is encountered. .RE .SS Arguments Currently, only the Internet address format is understood. In calls to .CR gethostbyaddr() , the parameter .I addr must be a pointer to an .IR in_addr structure, an Internet address in network order (see .IR byteorder (3N)) and the header file .CR ). The parameter .I len must be the number of bytes in an Internet address; that is, .CR "sizeof (struct in_addr)" . The parameter .I type must be the constant .CR AF_INET . .SH RETURN VALUE If successful, .CR gethostbyname() , .CR gethostbyaddr() , and .CR gethostent() return a pointer to the requested .CR hostent structure. .PP .CR gethostbyname() and .CR gethostbyaddr() return NULL if their .I host or .I addr parameters, respectively, cannot be found in the database. If .CR /etc/hosts is being used, they also return NULL if they are unable to open .CR /etc/hosts . .PP .CR gethostbyaddr() also returns NULL if either its .I addr or .I len parameter is invalid. .PP .CR gethostent() always returns NULL if the name server is being used. .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 is returned if the operation is unsuccessful or, in the case of .CR gethostent_r() , if the end of the hosts list has been reached. .CR 0 is returned otherwise. .SH ERRORS If the name server is being used and .CR gethostbyname() or .CR gethostbyaddr() returns a NULL pointer, the external integer .CR h_errno contains one of the following values: .RS .TP 23 .CR HOST_NOT_FOUND No such host is known. .TP .CR TRY_AGAIN This is usually a temporary error. The local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .CR NO_RECOVERY This is a non-recoverable error. .TP .CR NO_ADDRESS The requested name is valid but does not have an IP address; this is not a temporary error. This means another type of request to the name server will result in an answer. .RE .PP If the name server is not being used, the value of .CR h_errno may not be meaningful. .SH EXAMPLES The following code excerpt counts the number of host entries: .RS .nf .PP .C "int count = 0; .C "struct hostent htbuf; .C "struct hostent_data hdbuf; .PP .C "hdbuf.hostf = NULL; .C "(void) sethostent_r(0, &hdbuf); .C "while (gethostent_r(&htbuf, &hdbuf) != -1) .C " count++; .C "(void) endhostent_r(&hdbuf); .fi .RE .SH WARNINGS For the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR gethostent() , .CR gethostbyaddr() , .CR gethostbyname() , .CR sethostent() , and .CR endhostent() are unsafe in multi-thread applications. .CR gethostent_r() , .CR gethostbyaddr_r() , .CR gethostbyname_r() , .CR sethostent_r() , and .CR endhostent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR gethostent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/hosts .SH SEE ALSO named(1M), ypserv(1M), resolver(3N), ypclnt(3C), hosts(4), switch(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR gethostent() ": XPG4" .\" .\" index@\f1end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1entry, get, set, or end network host@@@\f3gethostent(3N)\f1 .\" index@\f1get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1host entry, get, set, or end network@@@\f3gethostent(3N)\f1 .\" index@\f1network host entry, get, set, or end@@@\f3gethostent(3N)\f1 .\" index@\f1set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1thread-safe, get, set, or end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent()\f1 \- end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent_r()\f1 \- end network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent()\f1 \- set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent_r()\f1 \- set network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" .\" links@gethostent.3n endhostent.3n .\" links@gethostent.3n endhostent_.3n .\" links@gethostent.3n gethostbyad.3n .\" links@gethostent.3n gethostbyna.3n .\" links@gethostent.3n gethostent_.3n .\" links@gethostent.3n sethostent.3n .\" links@gethostent.3n sethostent_.3n .\" .\" toc@\f3gethostent(3N)\f1:\0\0\f4endhostent()\f1, \f4endhostent_r()\f1, \f4gethostbyaddr()\f1, \f4gethostbyaddr_r()\f1,\n\f4gethostbyname()\f1, \f4gethostbyname_r()\f1, \f4gethostent()\f1, \f4gethostent_r()\f1,\n\f4sethostent()\f1, \f4sethostent_r()\f1@@@get, set, or end network host entry .\" .\" toc@\f4endhostent()\f1:\0\0end network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4endhostent_r()\f1:\0\0end network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostent_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent()\f1:\0\0set network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent_r()\f1:\0\0set network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" $Header: getmntent.3x,v 76.1 95/07/05 17:29:38 ssa Exp $ .TA g .TH getmntent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getmntent(\|), getmntent_r(\|), setmntent(\|), addmntent(\|), endmntent(\|), hasmntopt(\|) \- get file system descriptor file entry .SH SYNOPSIS .C "#include " .PP .C "\s-1FILE\s0 \(**setmntent(const char \(**path, char \(**type);" .PP .C "struct mntent \(**getmntent(\s-1FILE\s0 \(**stream);" .PP .C "int getmntent_r(" .nf .PD 0 .IP .C "\s-1FILE\s0 *stream," .C "struct mntent *result," .C "char *buffer," .C "int buflen);" .PD .PP .C "int addmntent(\s-1FILE\s0 \(**stream, struct mntent \(**mnt);" .PP .C "char \(**hasmntopt(struct mntent \(**mnt, const char \(**opt);" .PP .C "int endmntent(\s-1FILE\s0 \(**stream);" .SH DESCRIPTION These routines replace the obsolete .C getfsent() routines (see .IR getfsent (3X)) for accessing the file system description file .CR /etc/fstab . They are also used to access the mounted file system description file .CR /etc/mnttab . .TP 20 .C setmntent() Opens a file system description file and returns a file pointer which can then be used with .CR getmntent() , .CR addmntent() , or .CR endmntent() . The .I type argument is the same as in .IR fopen (3C). .TP .C getmntent() Reads the next line from .I stream and returns a pointer to an object with the following structure containing the broken-out fields of a line in the file-system description file, .RC < mntent.h >. The fields have meanings described in .IR fstab (4). .nf .IP .C struct mntent { .C " char *mnt_fsname; /* file system name */" .C " char *mnt_dir; /* file system path prefix */" .C " char *mnt_type; /* hfs, nfs, swap, or xx */" .C " char *mnt_opts; /* ro, suid, etc. */" .C " int mnt_freq; /* dump frequency, in days */" .C " int mnt_passno; /* pass number on parallel fsck */" .C " long mnt_time; /* When file system was mounted; */" .C " /* see mnttab(4). */" .C " /* (0 for NFS) */" .C }; .ft .ps .fi .IP .TP .C getmntent_r() Uses three extra parameters to provide results equivalent to those produced by .CR getmntent() . The extra parameters are: .PD 0 .IP 1. The address of a .C "struct mntent" where the result will be stored. .IP 2. A buffer to store character strings to which fields in the .C "struct mntent" will point. .IP 3. The length of the user-supplied buffer. A buffer length of 1025 is recommended. .PD .TP .C addmntent() Adds the .C mntent structure .I mnt to the end of the open file .IR stream . Note that .I stream must be opened for writing. .TP .C hasmntopt() Scans the .C mnt_opts field of the .C mntent structure .I mnt for a substring that matches .IR opt . It returns the address of the substring if a match is found; .C 0 otherwise. .TP .C endmntent() Closes the file. .PP The following definitions are provided in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNT_CHECKLIST "/etc/fstab" #define MNT_MNTTAB "/etc/mnttab" #define MNTMAXSTR 128 /* Max size string in mntent */ #define MNTTYPE_HFS "hfs" /* HFS file system */ #define MNTTYPE_CDFS "hfs" /* CD-ROM file system */ #define MNTTYPE_NFS "nfs" /* Network file system */ #define MNTTYPE_SWAP "swap" /* Swap device */ #define MNTTYPE_SWAPFS "swapfs" /* File system swap */ #define MNTTYPE_IGNORE "ignore" /* Ignore this entry */ #define MNTOPT_DEFAULTS "defaults" /* Use all default options */ #define MNTOPT_RO "ro" /* Read only */ #define MNTOPT_RW "rw" /* Read/write */ #define MNTOPT_SUID "suid" /* Set uid allowed */ #define MNTOPT_NOSUID "nosuid" /* No set uid allowed */ #define MNTOPT_QUOTA "quota" /* Enable disk quotas */ #define MNTOPT_NOQUOTA "noquota" /* Disable disk quotas */ .ft .ps .fi .RE .PP The following definition is provided for device swap in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_END "end" /* swap after end of file system, Series 300/400/700 only */ .ft .ps .fi .RE .PP The following definitions are provided for file system swap in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_MIN "min" /* minimum file system swap */ #define MNTOPT_LIM "lim" /* maximum file system swap */ #define MNTOPT_RES "res" /* reserve space for file system */ #define MNTOPT_PRI "pri" /* file system swap priority */ .ft .ps .RE .PP .SH NETWORKING FEATURES .SS NFS The following definitions are provided in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_BG "bg" /* Retry mount in background */ #define MNTOPT_FG "fg" /* Retry mount in foreground */ #define MNTOPT_RETRY "retry" /* Number of retries allowed */ #define MNTOPT_RSIZE "rsize" /* Read buffer size in bytes */ #define MNTOPT_WSIZE "wsize" /* Write buffer size in bytes*/ #define MNTOPT_TIMEO "timeo" /* Timeout in 1/10 seconds */ #define MNTOPT_RETRANS "retrans" /* Number of retransmissions */ #define MNTOPT_PORT "port" /* Server's IP NFS port */ #define MNTOPT_SOFT "soft" /* Soft mount */ #define MNTOPT_HARD "hard" /* Hard mount */ #define MNTOPT_INTR "intr" /* Interruptable hard mounts */ #define MNTOPT_NOINTR "nointr" /* Uninterruptable hard mounts*/ #define MNTOPT_DEVS "devs" /* Device file access allowed */ #define MNTOPT_NODEVS "nodevs" /* No device file access allowed */ .ft .ps .fi .TE .SH RETURN VALUE .TP 20 .C setmntent() Returns a null pointer on error. .TP .C getmntent() Returns a null pointer on error or EOF. Otherwise, .C getmntent() returns a pointer to a mntent structure. Some of the fields comprising a mntent structure are optional in .C /etc/fstab and .CR /etc/mnttab . In the supplied structure, such missing character pointer fields are set to NULL and missing integer fields are set to \(mi1 for .C mnt_freq and .C mnt_passno. If the integer field for .C mnt_time is missing, it is set to 0. .TP .C getmntent_r() Returns a .C -1 on error or EOF, or if the supplied buffer is of insufficient length. If the operation is successful, .C 0 is returned. .TP .C addmntent() Returns .C 1 on error. .TP .C endmntent() Returns .CR 1 . .SH WARNINGS The return value for .C getmntent() points to static information that is overwritten in each call. Thus, .C getmntent() is unsafe for multi-thread applications. .C getmntent_r() is MT-Safe and should be used instead. .SH AUTHOR .CR addmntent() , .CR endmntent() , .CR getmntent() , .CR hasmntopt() , and .C setmntent() were developed by The University of California, Berkeley, Sun Microsystems, Inc., and HP. .SH FILES .C /etc/fstab .br .C /etc/mnttab .SH SEE ALSO fstab(4), getfsent(3X), mnttab(4). .\" .\" index@\f4getmntent()\f1 \- get a file system description file entry@@@\f3getmntent(3X)\f1 .\" index@\f4setmntent()\f1 \- open a file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4addmntent()\f1 \- add entry to open file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4endmntent()\f1 \- close file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4hasmntopt()\f1 \- search mount option field in file system description file@@@\f3getmntent(3X)\f1 .\" index@file system description file entry@@@\f3getmntent(3X)\f1 .\" index@file entry get file system description@@@\f3getmntent(3X)\f1 .\" index@get file system description file@@@\f3getmntent(3X)\f1 .\" .\" toc@\f3getmntent(3X)\f1:\0\0\f4getmntent()\f1, \f4getmntent_r()\f1, \f4setmntent()\f1, \f4addmntent()\f1, \f4endmntent()\f1, \n\f4hasmntopt()\f1@@@get file system descriptor file entry .\" toc@\f4setmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4addmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4endmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4hasmntopt()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" .\" links@getmntent.3x getmntent_r.3x .\" links@getmntent.3x setmntent.3x .\" links@getmntent.3x addmntent.3x .\" links@getmntent.3x endmntent.3x .\" links@getmntent.3x hasmntopt.3x .\ .\" fileset_database@getmntent.3x PROGRAMING-MAN .\" $Header: getnetent.3n,v 78.1 96/03/15 15:57:28 ssa Exp $ .TA g .TH getnetent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnetent(\|), getnetent_r(\|), getnetbyaddr(\|), getnetbyaddr_r(\|), getnetbyname(\|), getnetbyname_r(\|), setnetent(\|), setnetent_r(\|), endnetent(\|),endnetent_r(\|) \- get network entry .SH SYNOPSIS .nf .C #include .C #include .PP .C "struct netent *getnetent(void);" .PP .C "int getnetent_r(struct netent *result, struct netent_data *buffer);" .PP .C "struct netent *getnetbyname(const char *name);" .PP .C "int getnetbyname_r(" .PD 0 .IP .C "const char *name," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "struct netent *getnetbyaddr(int net, int type);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "struct netent *getnetbyaddr(in_addr_t net, int type);" .PP .C "int getnetbyaddr_r(" .PD 0 .IP .C "int net," .C "int type," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "int setnetent(int stayopen);" .PP .C "int setnetent_r(int stayopen, struct netent_data *buffer);" .PP .C "int endnetent(void);" .PP .C "int endnetent_r(struct netent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setnetent(int stayopen);" .C "void endnetent(void);" .fi .SH DESCRIPTION .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() each return a pointer to a structure of type .I netent containing the broken-out fields of a line in the network data base, .CR /etc/networks . .PP The members of this structure are: .RS .TP 15 .CR n_name The official name of the network. .TP .CR n_aliases A null-terminated list of alternate names for the network. .TP .CR n_addrtype The type of the network number returned; always AF_INET. .TP .CR n_net The network number. .RE .PP Functions behave as follows: .RS .TP 22 .CR getnetent() Reads the next line of the file, opening the file if necessary. .TP .CR setnetent() opens and rewinds the file. If the .I stayopen flag is non-zero, the network data base is not closed after each call to .CR getnetent() (either directly or indirectly through one of the other .CR getnet* calls). .TP .CR endnetent() Closes the file. .TP .CR getnetbyname() Sequentially searches from the beginning of the file until a network name (among either the official names or the aliases) matching its parameter .I name is found, or until .SM EOF is encountered. .TP .CR getnetbyaddr() Sequentially searches from the beginning of the file until a network number matching its parameter .I net is found, or until .SM EOF is encountered. The parameter .I net must be in network order. The parameter .I type must be the constant .CR AF_INET . Network numbers are supplied in host order (see .IR byteorder (3N)). .PP If the system is running Network Information Service .SM (NFS), .CR getnetbyname() and .CR getnetbyaddr() obtain their network information from the .SM NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getnetent_r() , .CR getnetbyname_r() and .CR getnetbyaddr_r() expect to be passed the address of a .I "struct netent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct netent_data" , must also be supplied. This structure is used to store data, to which fields in the .I "struct netent" will point, as well as state information such as open file descriptors. The .I "struct netent_data" is defined in the file .CR . .PP .CR setnetent_r() and .CR endnetent_r() are to be used only in conjunction with .CR getnetent_r() and take the same pointer to a .I "struct netent_data" as a parameter. If the Network Information Service is being used, .CR setnetent_r() initializes an internal database key. If the .B /etc/networks file is being used, .CR setnetent_r() opens or rewinds the file. .CR endnetent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setnetent_r() currently has no effect. However, .CR setnetent() can still be used to keep the .B /etc/networks file open when making calls to .CR getnetbyaddr_r() and .CR getnetbyname_r() . .PP The .I net_fp field in the .I "struct netent_data" must be initialized to .SM NULL before it is passed to either .CR getnetent_r() or .CR setnetent_r() for the first time. Thereafter it should not be modified in any way. This is the only .I netent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getnetbyname() , .CR getnetbyaddr() , .CR getnetent() , and their reentrant counterparts, internally call the name service switch to access the "networks" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve network names and addresses. .SH RETURN VALUE .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() return a null pointer (0) on .SM EOF or when they are unable to open .CR /etc/networks . .CR getnetbyaddr() also returns a null pointer if its .I type parameter is invalid. .PP .CR getnetent_r() , .CR getnetbyname_r() , .CR getnetbyaddr_r() , .CR setnetent_r() , and .CR endnetent_r() return a -1 if the operation is unsuccessful or, in the case of .CR getnetent_r() , if the end of the networks list has been reached. A 0 is returned otherwise. .SH EXAMPLE The following code excerpt counts the number of network entries: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct netent netbuf; struct netent_data ndbuf; ndbuf.net_fp = NULL; (void) setnetent_r(0, &ndbuf); while (getnetent_r(&netbuf, &ndbuf) != -1) count++; (void) endnetent_r(&ndbuf); .ft .ps .fi .RE .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getnetent() , .CR getnetbyaddr() , .CR getnetbyname() , .CR setnetent() , and .CR endnetent() are unsafe in multi-thread applications. .CR getnetent_r() , .CR getnetbyaddr_r() , .CR getnetbyname_r() , .CR setnetent_r() , and .CR endnetent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getnetent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/networks .SH SEE ALSO ypserv(1M), networks(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getnetent() ": XPG4" .\" .\" index@\f4endnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyaddr()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyname()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4setnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1set network entry@@@\f3getnetent(3N)\f1 .\" index@\f1network entry, get or set@@@\f3getnetent(3N)\f1 .\" .\" toc@\f3getnetent(3N)\f1:\0\0\f4getnetent()\f1, \f4getnetbyaddr()\f1, \f4getnetbyname()\f1, \f4setnetent()\f1, \n\f4endnetent()\f1@@@get network entry .\" toc@\f4getnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" .\" links@getnetent.3n getnetbyadd.3n .\" links@getnetent.3n getnetbynam.3n .\" links@getnetent.3n setnetent.3n .\" links@getnetent.3n endnetent.3n .\" links@getnetent.3n getnetent_r.3n .\" links@getnetent.3n getnetbyaddr_r.3n .\" links@getnetent.3n getnetbyname_r.3n .\" links@getnetent.3n setnetent_r.3n .\" links@getnetent.3n endnetent_r.3n .\" .\" fileset_database@getnetent.3n INETSVCS-MAN .\" $Header: getnetent.3n,v 78.1 96/03/15 15:57:28 ssa Exp $ .TA g .TH getnetent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnetent(\|), getnetent_r(\|), getnetbyaddr(\|), getnetbyaddr_r(\|), getnetbyname(\|), getnetbyname_r(\|), setnetent(\|), setnetent_r(\|), endnetent(\|),endnetent_r(\|) \- get network entry .SH SYNOPSIS .nf .C #include .C #include .PP .C "struct netent *getnetent(void);" .PP .C "int getnetent_r(struct netent *result, struct netent_data *buffer);" .PP .C "struct netent *getnetbyname(const char *name);" .PP .C "int getnetbyname_r(" .PD 0 .IP .C "const char *name," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "struct netent *getnetbyaddr(int net, int type);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "struct netent *getnetbyaddr(in_addr_t net, int type);" .PP .C "int getnetbyaddr_r(" .PD 0 .IP .C "int net," .C "int type," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "int setnetent(int stayopen);" .PP .C "int setnetent_r(int stayopen, struct netent_data *buffer);" .PP .C "int endnetent(void);" .PP .C "int endnetent_r(struct netent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setnetent(int stayopen);" .C "void endnetent(void);" .fi .SH DESCRIPTION .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() each return a pointer to a structure of type .I netent containing the broken-out fields of a line in the network data base, .CR /etc/networks . .PP The members of this structure are: .RS .TP 15 .CR n_name The official name of the network. .TP .CR n_aliases A null-terminated list of alternate names for the network. .TP .CR n_addrtype The type of the network number returned; always AF_INET. .TP .CR n_net The network number. .RE .PP Functions behave as follows: .RS .TP 22 .CR getnetent() Reads the next line of the file, opening the file if necessary. .TP .CR setnetent() opens and rewinds the file. If the .I stayopen flag is non-zero, the network data base is not closed after each call to .CR getnetent() (either directly or indirectly through one of the other .CR getnet* calls). .TP .CR endnetent() Closes the file. .TP .CR getnetbyname() Sequentially searches from the beginning of the file until a network name (among either the official names or the aliases) matching its parameter .I name is found, or until .SM EOF is encountered. .TP .CR getnetbyaddr() Sequentially searches from the beginning of the file until a network number matching its parameter .I net is found, or until .SM EOF is encountered. The parameter .I net must be in network order. The parameter .I type must be the constant .CR AF_INET . Network numbers are supplied in host order (see .IR byteorder (3N)). .PP If the system is running Network Information Service .SM (NFS), .CR getnetbyname() and .CR getnetbyaddr() obtain their network information from the .SM NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getnetent_r() , .CR getnetbyname_r() and .CR getnetbyaddr_r() expect to be passed the address of a .I "struct netent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct netent_data" , must also be supplied. This structure is used to store data, to which fields in the .I "struct netent" will point, as well as state information such as open file descriptors. The .I "struct netent_data" is defined in the file .CR . .PP .CR setnetent_r() and .CR endnetent_r() are to be used only in conjunction with .CR getnetent_r() and take the same pointer to a .I "struct netent_data" as a parameter. If the Network Information Service is being used, .CR setnetent_r() initializes an internal database key. If the .B /etc/networks file is being used, .CR setnetent_r() opens or rewinds the file. .CR endnetent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setnetent_r() currently has no effect. However, .CR setnetent() can still be used to keep the .B /etc/networks file open when making calls to .CR getnetbyaddr_r() and .CR getnetbyname_r() . .PP The .I net_fp field in the .I "struct netent_data" must be initialized to .SM NULL before it is passed to either .CR getnetent_r() or .CR setnetent_r() for the first time. Thereafter it should not be modified in any way. This is the only .I netent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getnetbyname() , .CR getnetbyaddr() , .CR getnetent() , and their reentrant counterparts, internally call the name service switch to access the "networks" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve network names and addresses. .SH RETURN VALUE .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() return a null pointer (0) on .SM EOF or when they are unable to open .CR /etc/networks . .CR getnetbyaddr() also returns a null pointer if its .I type parameter is invalid. .PP .CR getnetent_r() , .CR getnetbyname_r() , .CR getnetbyaddr_r() , .CR setnetent_r() , and .CR endnetent_r() return a -1 if the operation is unsuccessful or, in the case of .CR getnetent_r() , if the end of the networks list has been reached. A 0 is returned otherwise. .SH EXAMPLE The following code excerpt counts the number of network entries: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct netent netbuf; struct netent_data ndbuf; ndbuf.net_fp = NULL; (void) setnetent_r(0, &ndbuf); while (getnetent_r(&netbuf, &ndbuf) != -1) count++; (void) endnetent_r(&ndbuf); .ft .ps .fi .RE .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getnetent() , .CR getnetbyaddr() , .CR getnetbyname() , .CR setnetent() , and .CR endnetent() are unsafe in multi-thread applications. .CR getnetent_r() , .CR getnetbyaddr_r() , .CR getnetbyname_r() , .CR setnetent_r() , and .CR endnetent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getnetent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/networks .SH SEE ALSO ypserv(1M), networks(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getnetent() ": XPG4" .\" .\" index@\f4endnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyaddr()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyname()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4setnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1set network entry@@@\f3getnetent(3N)\f1 .\" index@\f1network entry, get or set@@@\f3getnetent(3N)\f1 .\" .\" toc@\f3getnetent(3N)\f1:\0\0\f4getnetent()\f1, \f4getnetbyaddr()\f1, \f4getnetbyname()\f1, \f4setnetent()\f1, \n\f4endnetent()\f1@@@get network entry .\" toc@\f4getnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" .\" links@getnetent.3n getnetbyadd.3n .\" links@getnetent.3n getnetbynam.3n .\" links@getnetent.3n setnetent.3n .\" links@getnetent.3n endnetent.3n .\" links@getnetent.3n getnetent_r.3n .\" links@getnetent.3n getnetbyaddr_r.3n .\" links@getnetent.3n getnetbyname_r.3n .\" links@getnetent.3n setnetent_r.3n .\" links@getnetent.3n endnetent_r.3n .\" .\" fileset_database@getnetent.3n INETSVCS-MAN .\" $Header: getnetgrent.3c,v 76.2 95/05/26 17:06:46 ssa Exp $ .TA g .TH getnetgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnetgrent(\|), setnetgrent(\|), endnetgrent(\|), innetgr(\|), getnetgrent_r(\|), setnetgrent_r(\|), endnetgrent_r(\|) \- get network group entry .SH SYNOPSIS .nf .C int innetgr( .C " char *netgroup, " .C " char *machine, " .C " char *user, " .C " char *domain" .C ); .PP .C int setnetgrent(char *netgroup); .PP .C int setnetgrent_r( .C " char *grp," .C " char **ngstate" .C ); .PP .C int endnetgrent(); .PP .C int endnetgrent_r( .C " char **ngstaste" .C ); .PP .C int getnetgrent( .C " char **machinep, " .C " char **userp, " .C " char **domainp" .C ); .PP .C int getnetgrent_r( .C " char **machinep," .C " char **namep," .C " char **domainp," .C " char **ngstate" .C ); .fi .SH DESCRIPTION .TP 20 .C innetgr() Returns 1 if .C netgroup contains the machine, user, and domain triple as a member. Otherwise, it returns 0. If .IR machine , .IR user , or .I domain is .SM NULL, .C innetgr interprets .SM NULL to mean, any machine, user, or domain respectively. Refer to .IR netgroup (4) for a description of .C netgroup membership criteria. .TP .C getnetgrent() Returns the next member of a network group. After the call, .I machinep contains a pointer to a string containing the name of the machine part of the network group member. Pointers .I userp and .I domainp behave in a manner similar to .IR machinep . If any of these pointers are returned with a .SM NULL value, they are interpreted as wild cards. .C getnetgrent() allocates space for the names. This space is released when an .C endnetgrent() call is made. .C getnetgrent() returns 1 if it succeeded in obtaining another network group member, 0 if it reached the end of the group. .TP .C setnetgrent() Establishes the network group from which .C getnetgrent() obtains members, and also restarts calls to .C getnetgrent() from the beginning of the list. If the previous .C setnetgrent() call was to a different network group, a .C endnetgrent() call is implied. .TP .C endnetgrent() Frees the space allocated during .C getnetgrent() calls. .PD .PP If the system is running the Network Information Service (NIS) services, .CR setnetgrent() gets the netgroup information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getnetgrent_r(), .CR setnetgrent_r(), and .CR endnetgrent_r(), expect to be passed a pointer of .CR "char **ngstate" that will store the result of the lookup at the supplied location. This structure is used to store data, which the other reentrant (_r) routines use. .PP .CR setnetgrent_r() and .CR endnetgrent_r() are to be used only in conjunction with .CR getnetgrent_r() and take the same pointer to a char **ngstate as a parameter. .PP The .I **ngstate pointer must be initialized to NULL before it is passed to .CR setnetgrent_r() for the first time. Thereafter is should not be modified in any way. .SS Name Service Switch-Based Operation The library routine, .CR innetgr() , setnetgrent() , and setnetgrent_r(), internally call the name service switch to access the "netgroup" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve netgroup lookups. .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getnetgrent() , .CR setnetgrent() , and .CR endnetgrent() are unsafe in multi-thread applications. .CR getnetgrent_r() , .CR setnetgrent_r() , and .CR endnetgrent_r() are MT-Safe and should be used instead. .SH AUTHOR .C getnetgrent() was developed by Sun Microsystems, Inc. .SH FILES .C /etc/netgroup .C /etc/nsswitch.conf .SH SEE ALSO netgroup(4), switch(4). .\" .\" index@\f4getnetgrent()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@\f4endnetgrent()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@\f4innetgr()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@\f4setnetgrent()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@set network group entry@@@\f3getnetgrent(3C)\f1 .\" index@network group entry, get or set@@@\f3getnetgrent(3C)\f1 .\" index@group entry, network, get or set@@@\f3getnetgrent(3C)\f1 .\" index@entry, network group, get or set@@@\f3getnetgrent(3C)\f1 .\" .\" toc@\f3getnetgrent(3C)\f1: \f4getnetgrent()\fP, \f4setnetgrent()\fP, \f4endnetgrent()\fP, \f4innetgr()\fP@@@get network group entry .\" .\" links@getnetgrent.3c setnetgrent.3c .\" links@getnetgrent.3c endnetgrent.3c .\" links@getnetgrent.3c innetgr.3c .\" .\" fileset_database@getnetgrent.3c PROGRAMING-MAN .\" $Header: getprdfent.3,v 72.3 94/07/05 18:07:26 ssa Exp $ .TA g .TH getprdfent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprdfent, getprdfnam, setprdfent, endprdfent, putprdfnam \- manipulate system default database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct pr_default \(**getprdfent(void);" .PP .CR "struct pr_default \(**getprdfnam(const char \(**name);" .PP .CR "void setprdfent(void);" .PP .CR "void endprdfent(void);" .PP .CR "int putprdfnam(const char \(**name, struct pr_default \(**pr);" .fi .SH DESCRIPTION .I getprdfent and .I getprdfnam each returns a pointer to an object with the following structure containing the broken-out fields of a line in the system default database. Each line in the database contains a .I pr_default structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v struct system_default_fields { time_t fd_inactivity_timeout ; char fd_boot_authenticate ; } ; struct system_default_flags { unsigned short fg_inactivity_timeout:1, fg_boot_authenticate:1, } ; struct pr_default { char dd_name[20] ; char dg_name ; struct pr_field prd ; struct pr_flag prg ; struct t_field tcd ; struct t_flag tcg ; struct dev_field devd ; struct dev_flag devg ; struct system_default_fields sfld ; struct system_default_flags sflg ; } ; .fi .RE .PP Currently there is only one entry in the system default database, referenced by name .BR default . .PP The System Default database contains default values for all parameters in the Protected Password, Terminal Control, and Device Assignment databases, as well as configurable system-wide parameters. The fields from the other databases are described in the corresponding manual entries. .I fd_inactivity_timeout is the number of seconds until a session is terminated on trusted systems. .PP .I fd_boot_authenticate is a boolean flag that indicates whether an authorized user must authenticate before the system begins operation. .PP .I getprdfent returns a pointer to the first .I pr_default structure in the database when first called. Thereafter, it returns a pointer to the next .I pr_default structure in the database, so that successive calls can be used to search the database (not currently supported). .PP .I getprdfnam searches from the beginning of the file until a default entry matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a .SM .B NULL pointer. Currently, all programs access the default database by calling .I getprdfnam ("default"). .PP A call to .I setprdfent has the effect of rewinding the default control file to allow repeated searches. .I endprdfent can be called to close the database when processing is complete. .PP .I putprdfnam puts a new or replaced default control entry .I pr with key .I name into the database. If the .I prg.fd_name field is 0, the requested entry is deleted from the system default database. .I putprdfnam locks the database for all update operations, and performs an .I endprdfent after the update or failed attempt. .SH RETURN VALUE .I getprdfent and .I getprdfnam return .SM .B NULL pointers on .SM EOF or error. .I putprdfnam returns 0 if it cannot add or update the entry. .SH WARNINGS Do not delete the system default entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 45 .C /tcb/files/auth/system/default System Defaults database .SH SEE ALSO authcap(4), default(4), getprpwent(3), getprtcent(3), getdvagent(3). .SH NOTES The value returned by .I getprdfent and .I getprdfnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .IR putprdfnam . .PP Programs using these routines must be compiled with .BR \-lsec . .\" .\" index@\f4getprdfent\f1 \- manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f4getprdfnam\f1 \- manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f4setprdfent\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" index@\f4endprdfent\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" .\" index@\f4putprdfnam\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" index@\f1manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f1manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f1system default database entry, manipulate@@@\f3getprdfent(3)\f1 .\" index@\f1default database entry, manipulate system@@@\f3getprdfent(3)\f1 .\" index@\f1database entry, manipulate system default@@@\f3getprdfent(3)\f1 .\" index@\f1entry, manipulate system default database@@@\f3getprdfent(3)\f1 .\" .\" toc@\f3getprdfent(3)\f1:\0\0\f4getprdfent\f1, \f4getprdfnam\f1, \f4setprdfent\f1, \f4endprdfent\f1,\n\f4putprdfnam\f1@@@manipulate system default database entry for a trusted system .\" toc@\f4getprdfnam\f1:\0\0search for file@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4setprdfent\f1:\0\0rewind default control files@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4endprdfent\f1:\0\0close system default database@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4putprdfnam\f1:\0\0put default control entry@@@\f1see \f3getprdfent(3)\f1 .\" .\" links@getprdfent.3 getprdfnam.3 .\" links@getprdfent.3 setprdfent.3 .\" links@getprdfent.3 endprdfent.3 .\" links@getprdfent.3 putprdfnam.3 .\" .\" fileset_database@getprdfent.3 UX-CORE-MAN .\" $Header: getprotoent.3n,v 78.1 96/03/17 09:48:20 ssa Exp $ .TA g .TH getprotoent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprotoent(), getprotoent_r(), getprotobynumber(), getprotobynumber_r(), getprotobyname(), getprotobyname_r(), setprotoent(), setprotoent_r(), endprotoent(), endprotoent_r() \- get protocol entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct protoent *getprotoent(void);" .PP .C "int getprotoent_r(struct protoent *result," .C " struct protoent_data *buffer);" .PP .C "struct protoent *getprotobyname(const char *name);" .PP .C "int getprotobyname_r(const char *name," .C " struct protoent *result," .C " struct protoent_data *buffer);" .PP .C "struct protoent *getprotobynumber(int proto);" .PP .C "int getprotobynumber_r(int proto," .C " struct protoent *result," .C " struct protoent_data *buffer);" .PP .C "int setprotoent(int stayopen);" .PP .C "int setprotoent_r(int stayopen, struct protoent_data *buffer);" .PP .C "int endprotoent(void);" .PP .C "int endprotoent_r(struct protoent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setprotoent(int stayopen);" .C "void endprotoent(void);" .fi .SH DESCRIPTION The .CR getprotoent() , .CR getprotobyname() , and .CR getprotobynumber() functions each return a pointer to a structure of type .I protoent containing the broken-out fields of a line in the network protocol data base, .CR /etc/protocols . .PP The members of this structure are: .RS .TP 15 .CR p_name The official name of the protocol. .TP .CR p_aliases A null-terminated list of alternate names for the protocol. .TP .CR p_proto The protocol number. .RE .PP Functions behave as follows: .RS .TP 26 .CR getprotoent() Reads the next line of the file, opening the file if necessary. .TP .CR setprotoent() Opens and rewinds the file. If the .I stayopen flag is non-zero, the protocol data base is not closed after each call to .CR getprotoent() (either directly or indirectly through one of the other .CR getproto* calls). .TP .CR endprotoent() Closes the file. .TP .CR getprotobyname() .PD 0 .TP .CR getprotobynumber() Each sequentially searches from the beginning of the file until a matching protocol name (among either the official names or the aliases) or protocol number is found, or until EOF is encountered. .PD .PP If the system is running the Network Information Service (NIS) services, .CR getprotobyname() and .CR getprotobynumber() get the protocol information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getprotoent_r() , .CR getprotobyname_r() , and .CR getprotobynumber_r() expect to be passed the address of a .CR "struct protoent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct protoent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct protoent" will point, as well as state information such as open file descriptors. The .CR "struct protoent_data" is defined in the file .CR . .PP .CR setprotoent_r() and .CR endprotoent_r() are to be used only in conjunction with .CR getprotoent_r() and take the same pointer to a .CR "struct protoent_data" as a parameter. If the Network Information Service is being used, .CR setprotoent_r() initializes an internal database key. If the .B /etc/protocols file is being used, .CR setprotoent_r() opens or rewinds the file. .CR endprotoent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setprotoent_r() currently has no effect. However, .CR setprotoent() can still be used to keep the .B /etc/protocols file open when making calls to .CR getprotobyname_r() and .CR getprotobynumber_r() . .PP The .I proto_fp field in the .CR "struct protoent_data" must be initialized to NULL before it is passed to either .CR getprotoent_r() or .CR setprotoent_r() for the first time. Thereafter it should not be modified in any way. This is the only .CR protoent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getprotobyname() , .CR getprotobynumber() , .CR getprotoent() , and their reentrant counterparts, internally call the name service switch to access the "protocols" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve protocol names and numbers. .SH RETURN VALUE .CR getprotoent() , .CR getprotobyname() , and .CR getprotobynumber() return a null pointer (0) on EOF or when they are unable to open .CR /etc/protocols . .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 will be returned if the operation is unsuccessful or, in the case of .CR getprotoent_r() , if the end of the protocols list has been reached. .CR 0 is returned otherwise. .SH EXAMPLES The following code excerpt counts the number of protocols entries: .RS .nf .PP .C "int count = 0;" .C "struct protoent protobuf;" .C "struct protoent_data pdbuf;" .PP .C "pdbuf.proto_fp = NULL;" .C "(void) setprotoent_r(0, &pdbuf);" .C "while (getprotoent_r(&protobuf, &pdbuf) != -1)" .C " count++;" .C "(void) endprotoent_r(&pdbuf);" .fi .RE .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getprotoent() , .CR getprotobynumber() , .CR getprotobyname() , .CR setprotoent() , and .CR endprotoent() are unsafe in multi-thread applications. .CR getprotoent_r() , .CR getprotobynumber_r() , .CR getprotobyname_r() , .CR setprotoent_r() , and .CR endprotoent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getprotoent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/protocols .SH SEE ALSO ypserv(1M), protocols(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getprotoent() ": XPG4" .\" .\" index@\f1end protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f1entry, get, set, or end protocol@@@\f3getprotoent(3N)\f1 .\" index@\f1get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f1protocol entry, get, set, or end@@@\f3getprotoent(3N)\f1 .\" index@\f1set protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f1thread-safe, get, set, or end protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4endprotoent()\f1 \- end protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4endprotoent_r()\f1 \- end protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobyname()\f1 \- get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobyname_r()\f1 \- get protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobynumber()\f1 \- get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobynumber_r()\f1 \- get protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotoent()\f1 \- get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotoent_r()\f1 \- get protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4setprotoent()\f1 \- set protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4setprotoent_r()\f1 \- set protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" .\" links@getprotoent.3n endprotoent.3n .\" links@getprotoent.3n getprotobyn.3n .\" links@getprotoent.3n setprotoent.3n .\" .\" toc@\f3getprotoent(3N)\f1:\0\0\f4endprotoent()\f1, \f4endprotoent_r()\f1, \f4getprotobyname()\f1, \f4getprotobyname_r()\f1,\n\f4getprotobynumber()\f1, \f4getprotobynumber_r()\f1, \f4getprotoent()\f1, \f4getprotoent_r()\f1,\n\f4setprotoent()\f1, \f4setprotoent_r()\f1,@@@get, set, or end protocol entry .\" .\" toc@\f4endprotoent()\f1:\0\0end protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4endprotoent_r()\f1:\0\0end protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobyname()\f1:\0\0get protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobyname_r()\f1:\0\0get protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobynumber()\f1:\0\0get protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobynumber_r()\f1:\0\0get protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotoent_r()\f1:\0\0get protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4setprotoent()\f1:\0\0set protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4setprotoent_r()\f1:\0\0set protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" $Header: getprpwent.3,v 78.3 96/01/19 20:14:34 ssa Exp $ .TA g .TH getprpwent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprpwent, getprpwuid, getprpwnam, getprpwaid, setprpwent, endprpwent, putprpwnam \- manipulate protected password database entry (for trusted systems only) .SH SYNOPSIS .nf .B "#include " .B "#include " .B "#include " .PP .B "struct pr_passwd \(**getprpwent(void);" .PP .B "struct pr_passwd \(**getprpwuid(uid_t uid);" .PP .B "struct pr_passwd \(**getprpwnam(const char \(**name);" \c .PP .B "struct pr_passwd \(**getprpwaid(aid_t aid)" \c .PP .B "void setprpwent(void);" .PP .B "void endprpwent(void);" .PP .B "int putprpwnam(const char \(**name, struct pr_passwd \(**pr);" .fi .SH DESCRIPTION .CR getprpwent (), .CR getprpwuid (), .CR getprpwaid (), and .CR getprpwnam () each returns a pointer to a .C pr_passwd structure containing the broken-out fields of a line in the protected password database. Each line in the database contains a .C pr_passwd structure, declared in the .RC < prot.h > header file: .IP .nf .ift .sp -1v struct pr_field { /\(** Identity: \(**/ char fd_name[9]; /\(** uses 8 character maximum(and NULL) from utmp \(**/ uid_t fd_uid; /\(** uid associated with name above \(**/ char fd_encrypt[xxx]; /\(** encrypted password \(**/ char fd_owner[9]; /\(** if a pseudo-user, the user accountable \(**/ char fd_boot_auth; /\(** boot authorization \(**/ mask_t fd_auditcntl; /\(** reserved \(**/ mask_t audit_reserve1; /\(** reserved \(**/ mask_t fd_auditdisp; /\(** reserved \(**/ mask_t audit_reserve2; /\(** reserved \(**/ aid_t fd_pw_audid; /\(** audit ID \(**/ int fd_pw_audflg; /\(** audit flag \(**/ .IP /\(** Password maintenance parameters: \(**/ time_t fd_min; /\(** minimum time between password changes \(**/ int fd_maxlen; /\(** maximum length of password \(**/ time_t fd_expire; /\(** expiration time duration in secs \(**/ time_t fd_lifetime; /\(** account death duration in seconds \(**/ time_t fd_schange; /\(** last successful change in secs past 1/1/70 \(**/ time_t fd_uchange; /\(** last unsuccessful change \(**/ time_t fd_acct_expire; /\(** absolute account lifetime in seconds \(**/ time_t fd_max_llogin; /\(** max time allowed between logins \(**/ time_t fd_pw_expire_warning; /\(** password expiration warning \(**/ uid_t fd_pswduser; /\(** who can change this user's password \(**/ char fd_pick_pwd; /\(** can user pick his own passwords? \(**/ char fd_gen_pwd; /\(** can user get passwords generated for him? \(**/ char fd_restrict; /\(** should generated passwords be restricted? \(**/ char fd_nullpw; /\(** is user allowed to have a NULL password? \(**/ uid_t fd_pwchanger; /\(** who last changed user's password \(**/ long fd_pw_admin_num;/\(** password generation verifier \(**/ char fd_gen_chars; /\(** can have password of random ASCII? \(**/ char fd_gen_letters; /\(** can have password of random letters? \(**/ char fd_tod[AUTH_TOD_SIZE]; /\(** times when user may login \(**/ .IP /\(** Login parameters: \(**/ time_t fd_slogin; /\(** last successful login \(**/ time_t fd_ulogin; /\(** last unsuccessful login \(**/ char fd_suctty[14]; /\(** tty of last successful login \(**/ short fd_nlogins; /\(** consecutive unsuccessful logins \(**/ char fd_unsuctty[14];/\(** tty of last unsuccessful login \(**/ short fd_max_tries; /\(** maximum unsuc login tries allowed \(**/ char fd_lock; /\(** Unconditionally lock account? \(**/ }; .IP struct pr_flag { unsigned short /\(** Identity: \(**/ fg_name:1, /\(** Is fd_name set? \(**/ fg_uid:1, /\(** Is fd_uid set? \(**/ fg_encrypt:1, /\(** Is fd_encrypt set? \(**/ fg_owner:1, /\(** Is fd_owner set? \(**/ fg_boot_auth:1, /\(** Is fd_boot_auth set? \(**/ fg_pw_audid:1, /\(** Is fd_auditcntl set? \(**/ fg_pw_audflg:1, /\(** Is fd_auditdisp set? \(**/ .IP /\(** Password maintenance parameters: \(**/ fg_min:1, /\(** Is fd_min set? \(**/ fg_maxlen:1, /\(** Is fd_maxlen set? \(**/ fg_expire:1, /\(** Is fd_expire set? \(**/ fg_lifetime:1, /\(** Is fd_lifetime set? \(**/ fg_schange:1, /\(** Is fd_schange set? \(**/ fg_uchange:1, /\(** Is fd_fchange set? \(**/ fg_acct_expire:1, /\(** Is fd_acct_expire set? \(**/ fg_max_llogin:1, /\(** Is fd_max_llogin set? \(**/ fg_pw_expire_warning:1, /\(** Is fd_pw_expire_warning set? \(**/ fg_pswduser:1, /\(** Is fd_pswduser set? \(**/ fg_pick_pwd:1, /\(** Is fd_pick_pwd set? \(**/ fg_gen_pwd:1, /\(** Is fd_gen_pwd set? \(**/ fg_restrict:1, /\(** Is fd_restrict set? \(**/ fg_nullpw:1, /\(** Is fd_nullpw set? \(**/ fg_pwchanger:1, /\(** Is fd_pwchanger set? \(**/ fg_pw_admin_num:1, /\(** Is fd_pw_admin_num set? \(**/ fg_gen_chars:1, /\(** Is fd_gen_chars set? \(**/ fg_gen_letters:1, /\(** Is fd_gen_letters set? \(**/ fg_tod:1, /\(** Is fd_tod set? \(**/ .IP /\(** Login parameters: \(**/ fg_slogin:1, /\(** Is fd_slogin set? \(**/ fg_suctty: 1, /\(** is fd_suctty set ? \(**/ fg_unsuctty: 1, /\(** is fd_unsuctty set ? \(**/ fg_ulogin:1, /\(** Is fd_ulogin set? \(**/ fg_nlogins:1, /\(** Is fd_nlogins set? \(**/ fg_max_tries:1, /\(** Is fd_max_tries set? \(**/ fg_lock:1; /\(** Is fd_lock set? \(**/ }; .IP struct pr_passwd { struct pr_field ufld; /\(** user specific fields \(**/ struct pr_flag uflg; /\(** user specific flags \(**/ struct pr_field sfld; /\(** system wide fields \(**/ struct pr_flag sflg; /\(** system wide flags \(**/ }; .fi .PP The protected password database stores user authentication profiles. The .C pr_passwd structure in the user-specific entry refers to parameters specific to a user. The .C pr_passwd structure in the system default database sets parameters that are used when there is no user-specific override. .PP The user-specific entry is keyed on the .I fd_name field, which is a cross reference to the .C /etc/passwd entry for the user. The .I fd_uid field must match the UID in that file as well. The .I fd_encrypt field is the encrypted password. The password is encrypted in eight character segments, so the size of this field is a multiple of the number of characters in an encrypted segment (\c .C AUTH_CIPHERTEXT_SIZE macro). .PP .I fd_owner is the user name accountable for the account. \c The .I fd_boot_auth field is used when the system default file specifies boot authorization is required. .I init(1M) prompts for a user name and password. If the authentication succeeds, a value in this field allows the user to continue the system boot process. \c .PP .I fd_min is the time, in seconds, that must elapse before the user can change passwords. .I fd_maxlen is the maximum password length (in characters) for the user. .I fd_expire is the time, in seconds, until the user's password expires. .I fd_lifetime is the number of seconds that must elapse before the password dies. The account is considered locked if the password is dead. .PP .I fd_schange and .I fd_uchange record the last successful and unsuccessful password change times. .PP The .I fd_acct_expire field specifies the absolute period of time in seconds that the account can be used. An absolute expiration date may be specified, which is then converted into seconds stored in this field. This is different from .I fd_expire in that .I fd_acct_expire specifies an absolute expiration date, while .I fd_expire is reset with each password change. .PP .I fd_max_llogin specifies the maximum time in seconds allowed since the last login before the account becomes locked. .I fd_pw_expire_warning is the time in seconds before the end of .I fd_expire that the system warns the user the password is about to expire. .I fd_pswduser stores the user ID of the user allowed to change passwords for the account. \c Typically, this is the account owner. \c .PP The next flag fields control password generation. .IR fd_pick_pwd , if set, allows the user to pick his or her own password. .IR fd_nullpw , if set, allows the account to be used without a password. .I fd_gen_pwd enables the use of the random pronounceable password generator for passwords for this account. .I fd_gen_chars and .I fd_gen_letters allow the password generator to generate passwords composed of random printable characters and random letters, neither of which is easy to remember. The password change software allows the user to pick from whichever options are available for his or her account. One of these three fields .RI ( fd_gen_pwd , .IR fd_gen_chars , or .IR fd_gen_letters ) must be set. .PP .I fd_pwchanger is the user ID of the user who last changed the password on the user's account, if it was not the account owner. .IR fd_restrict , if set, causes triviality checks to be made after the account password has been chosen to avoid palindromes, user name and machine name permutations, and words appearing in the dictionary. .PP The .I fd_tod specifier is a string, formatted like the UUCP .C Systems file, which specifies time intervals during which the user can log in. \c .PP The next fields are used to protect against login spoofing, listing the time and location of last login. .I fd_slogin and .I fd_ulogin are time stamps of the last successful and unsuccessful login attempts. .I fd_suctty and .I fd_unsuctty are the terminal device or (if supported) host names of the terminal or host from which the last login attempt occurred. .PP .I fd_nlogins is the number of unsuccessful login attempts since the last successful login. It is reset to zero after a successful login. .I fd_max_tries is the number of unsuccessful attempts until the account is considered locked. .PP .I fd_lock indicates whether the administrative lock on the account is set. The account is considered disabled (locked) if one or more of these activities has occurred: .PD 0 .PP 1. if the password is dead, .PP 2. if the maximum number of unsuccessful attempts has been exceeded, .PP 3. if the administrative lock is set, .PP 4. if the account expiration is reached, or .PP 5. if the time since last login is exceeded. .PD .PP When .CR getprpwent () is first called, it returns a pointer to the first user .C pr_passwd structure in the database; thereafter, it returns a pointer to the next .C pr_passwd structure in the database so that successive calls can be used to search the database. Note that entries without a corresponding entry in .C /etc/passwd are skipped. The entries are scanned in the order they appear in .CR /etc/passwd . .PP .CR getprpwuid () searches from the beginning of the database until a numerical user ID matching .I uid is found and returns a pointer to the particular structure in which it was found. \c .CR getprpwaid () functions like .CR getprpwuid () only it uses the audit ID instead of the uid. \c .PP .CR getprpwnam () searches from the beginning of the database until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a NULL pointer. .PP A call to .CR setprpwent () has the effect of rewinding the protected password database to allow repeated searches. .CR endprpwent () can be called to close the protected password database when processing is complete. .PP .CR putprpwnam () puts a new or replaced protected password entry .I pr with key .I name into the database. If the .I uflg.fg_name field is 0, the requested entry is deleted from the protected password database. .CR putprpwnam () locks the database for all update operations, and performs a .CR endprpwent () after the update or failed attempt. .SS Notes .PP The value returned by .CR getprpwent () and .CR getprpwnam () refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .CR putprpwnam (). .PP On systems supporting network connections, the .I fd_suctty and .I fd_unsuctty fields can be the ASCII representation of the network address of the host from which the last successful or unsuccessful remote login to the account occurred. Use .IR getdvagnam (3) to investigate the type of device to determine whether a host or a terminal was used for the last successful or unsuccessful login. .PP Programs using these routines must be compiled with .CR \-lsec . .PP .CR getprpwent () assumes one name per UID and one UID per name. The sequential scan loops between the first two instances of a multiple UID. .PP .CR getprpwent () uses .IR getpwent (3) routines to sequentially scan databases. User program references to password entries obtained using .IR getpwent (3) routines will not be valid after using any routines described here (ie., the * .CR prp * routines). .SH RETURN VALUE .CR getprpwent (), .CR getprpwuid (), and .CR getprpwnam () return NULL pointers on EOF or error. .CR putprpwnam () returns 0 if it cannot add or update the entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 35 .C /etc/passwd System Password file .PD 0 .TP .C /tcb/files/auth/\(**/\(** Protected Password database .TP .C /tcb/files/auth/system/default System Defaults database .PD .SH SEE ALSO authcap(4), getpwent(3), getprdfent(3), prpwd(4). .\" .\" index@\f4getprpwuid\f1 \- get protected password database user ID@@@\f3getprpwent(3)\f1 .\" index@\f4getprpwaid\f1 \- get protected password database audit ID@@@\f3getprpwent(3)\f1 .\" index@\f4getprpwnam\f1 \- get protected password database user name@@@\f3getprpwent(3)\f1 .\" index@\f4setprpwent\f1 \- set protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f4endprpwent\f1 \- manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f4putprpwnam\f1 \- manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1access protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1protected password database entry, manipulate@@@\f3getprpwent(3)\f1 .\" index@\f1password database entry, manipulate protected@@@\f3getprpwent(3)\f1 .\" index@\f1database entry, manipulate protected password@@@\f3getprpwent(3)\f1 .\" index@\f1entry, manipulate protected password database@@@\f3getprpwent(3)\f1 .\" .\" toc@\f3getprpwent(3)\f1:\0\0\f4getprpwent\f1, \f4getprpwuid\f1, \f4getprpwnam\f1, \f4getprpwaid\f1, \f4setprpwent\f1,\n\f4endprpwent\f1, \f4putprpwnam\f1@@@manipulate protected password database entry .\" toc@\f4getprpwuid\f1:\0\0get protected password database user ID@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4getprpwaid\f1:\0\0get protected password database audit ID@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4getprpwnam\f1:\0\0get protected password database user name@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4setprpwent\f1:\0\0set protected password database entry@@@\f1 see \f3getprpwent(3)\f1 .\" toc@\f4endprpwent\f1:\0\0manipulate protected password database entry@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4putprpwnam\f1:\0\0manipulate protected password database entry@@@\f1 see \f3getprpwent(3)\f1 .\" .\" links@getprpwent.3 getprpwuid.3 .\" links@getprpwent.3 getprpwnam.3 .\" links@getprpwent.3 setprpwent.3 .\" links@getprpwent.3 endprpwent.3 .\" links@getprpwent.3 putprpwnam.3 .\" links@getprpwent.3 getprpwaid.3 .\" .\" $Header: getprtcent.3,v 78.2 96/01/19 20:15:15 ssa Exp $ .TA g .TH getprtcent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprtcent, getprtcnam, setprtcent, endprtcent, putprtcnam \- manipulate terminal control database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct pr_term \(**getprtcent(void);" .PP .CR "struct pr_term \(**getprtcnam(const char \(**name);" .PP .CR "void setprtcent(void);" .PP .CR "void endprtcent(void);" .PP .CR "int putprtcnam(const char \(**name, struct pr_term \(**pr);" .fi .SH DESCRIPTION .IR getprtcent and .I getprtcnam each returns a pointer to an object with the following structure containing the broken-out fields of an entry in the terminal control database. Each entry in the database contains a .I pr_term structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v .ift .ta 2i .ifn .ta 3i .ne 15 struct t_field { char fd_devname[14]; /* Terminal (or host) name */ uid_t fd_uid; /* uid of last successful login */ time_t fd_slogin; /* time stamp of successful login */ uid_t fd_uuid; /* uid of last unsuccessful login */ time_t fd_ulogin; /* time stamp of unsuccessful login */ ushort fd_nlogins; /* consecutive failed attempts */ ushort fd_max_tries; /* maximum unsuc login tries allowed */ time_t fd_logdelay; /* delay between login tries */ char fd_lock; /* terminal locked? */ ushort fd_login_timeout ; /* login timeout in seconds */ }; .IP .ne 17 struct t_flag { unsigned short fg_devname:1, /* Is fd_devname set? */ fg_uid:1, /* Is fd_uid set? */ fg_slogin:1, /* Is fd_stime set? */ fg_uuid:1, /* Is fd_uuid set? */ fg_ulogin:1, /* Is fd_ftime set? */ fg_nlogins:1, /* Is fd_nlogins set? */ fg_max_tries:1, /* Is fd_max_tries set? */ fg_logdelay:1, /* Is fd_logdelay set? */ fg_lock:1, /* Is fd_lock set? */ fg_login_timeout:1 /* is fd_login_timeout valid? */ ; }; .IP .ne 6 struct pr_term { struct t_field ufld; struct t_flag uflg; struct t_field sfld; struct t_flag sflg; }; .fi .DT .PP The system stores the user ID and time of the last successful login ( .I fd_uid and .I fd_slogin ) and unsuccessful login ( .I fd_uuid and .I fd_ulogin ) in the appropriate Terminal Control database entry. The system increments .I fd_nlogins with each unsuccessful login, and resets the field to 0 on a successful login. The .I fd_max_tries field is a limit on the number of unsuccessful logins until the account is locked. An administrative lock can also be applied, indicated by a non-zero .I fd_lock field. .I fd_logdelay stores the amount of time (in seconds) that the system waits between unsuccessful login attempts, and .I fd_login_timeout stores the number of seconds from the beginning of an authentication attempt until the login attempt is terminated. .PP Note that .I ufld and .I uflg refer to user specific entries, and .I sfld and .I sflg refer to the system default values (see .IR authcap (4)). .PP The value returned by .I getprtcent or .I getprtcnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .IR putprtcnam . .PP .I getprtcent returns a pointer to the first terminal .I pr_term structure in the database when first called. Thereafter, it returns a pointer to the next .I pr_term structure in the database, so successive calls can be used to search the database. .I getprtcnam searches from the beginning of the database until a terminal name matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a .B NULL pointer. .PP A call to .I setprtcent has the effect of rewinding the Terminal Control database to allow repeated searches. .I endprtcent can be called to close the Terminal Control database when processing is complete. .PP .I putprtcnam puts a new or replaced terminal control entry .I pr with key .I name into the database. If the .I fg_devname field is 0, the requested entry is deleted from the Terminal Control database. .I putprtcnam locks the database for all update operations, and performs an .I endprtcent after the update or failed attempt. .SH RETURN VALUE .I getprtcent and .I getprtcnam return .SM .B NULL pointers on .SM EOF or error. .I putprtcnam returns 0 if it cannot add or update the entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 45 .C /tcb/files/ttys Terminal Control database .PD 0 .TP .C /tcb/files/auth/system/default System Defaults database .PD .SH SEE ALSO getprdfent(3), authcap(4), ttys(4). .SH NOTES The .I fd_devname field, on systems supporting connections, may refer to the .SM ASCII representation of a host name. This can be determined by using .IR getdvagnam (3) to interrogate the Device Assignment database as to the type of the device, passing in the .I fd_devname field of the Terminal Control structure as an argument. This allows lockout by machine, instead of the device (typically pseudo tty) on which the session originated. .PP Programs using these routines must be compiled with .BR \-lsec . .PP The .I sfld and .I sflg structures are filled from corresponding fields in the system default database. Thus, a program can easily extract the user-specific or system-wide parameters for each database field (see .I getprpwent and .IR getdvagent ). .\" .\" index@\f4getprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4getprtcnam\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4setprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4endprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4putprtcnam\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f1manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f1terminal control database entry, manipulate@@@\f3getprtcent(3)\f1 .\" index@\f1database entry, manipulate terminal control@@@\f3getprtcent(3)\f1 .\" index@\f1entry, manipulate terminal control database@@@\f3getprtcent(3)\f1 .\" .\" toc@\f3getprtcent(3)\f1:\0\0\f4getprtcent\f1, \f4getprtcnam\f1, \f4setprtcent\f1, \f4endprtcent\f1,\n\f4putprtcnam\f1@@@manipulate terminal control database entry for a trusted system .\" toc@\f4getprtcent\f1:\0\0return pointer to terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc \f4getprtcnam\f1:\0\0search terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4setprtcent\f1:\0\0rewind terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4endprtcent\f1:\0\0close terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4putprtcnam\f1:\0\0put entry into terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" .\" links@getprtcent.3 getprtcnam.3 .\" links@getprtcent.3 setprtcent.3 .\" links@getprtcent.3 endprtcent.3 .\" links@getprtcent.3 putprtcnam.3 .\" .\" $Header: getpwent.3c,v 78.1 95/12/20 10:53:01 ssa Exp $ .TA g .TH getpwent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpwent(\|), getpwent_r(\|), getpwuid(\|), getpwuid_r(\|), getpwnam(\|), getpwnam_r(\|), setpwent(\|), setpwent_r(\|), endpwent(\|), endpwent_r(\|), fgetpwent(\|), fgetpwent_r(\|) \- get password file entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct passwd *getpwent(void);" .PP .C "int getpwent_r(struct passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct passwd *getpwuid(uid_t uid);" .PP .PD 0 .C "int getpwuid_r(uid_t uid, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct passwd *getpwnam(const char *name);" .PP .PD 0 .C "int getpwnam_r(char *name, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setpwent(void);" .PP .C "void setpwent_r(FILE **pwfp);" .PP .C "void endpwent(void);" .PP .C "void endpwent_r(FILE **pwfp);" .PP .C "struct passwd *fgetpwent(FILE *stream);" .PP .C "int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, int buflen);" .fi .SH DESCRIPTION .CR getpwent (), .CR getpwuid (), and .CR getpwnam () locate an entry in the .C /etc/passwd file, and return a pointer to an object of .C passwd structure. .PP The .C passwd structure is defined in .RC < pwd.h > and includes the following members: .nf .IP .CR "char *pw_name; " "/* user name */" .CR "char *pw_passwd; " "/* encrypted password */" .CR "uid_t pw_uid; " "/* user id */" .CR "gid_t pw_gid; " "/* group id */" .CR "char *pw_age; " "/* password aging */" .CR "char *pw_comment;" "/* unused */" .CR "char *pw_gecos; " "/* user fullname, office, extension, homephone*/" .CR "char *pw_dir; " "/* initial directory */" .CR "char *pw_shell; " "/* initial shell */" .CR "aid_t pw_audid; " "/* numerical audit id */" .CR "int pw_audflg; " "/* numerical audit flag */" .fi .PP The .I pw_comment field is unused; for more information on the other fields, refer to .IR passwd (4). .TP 20 .CR getpwent () When first called, .CR getpwent () returns a pointer to the first .C passwd structure in the file. Thereafter, it returns a pointer to the next .C passwd structure in the file. In this way, successive calls can be used to search the entire file. .CR getpwent () opens the .C /etc/passwd file prior to doing its work and leaves the file open afterward; .TP .CR setpwent () Has the effect of rewinding this file to allow repeated searches; .TP .CR endpwent () Can be called to close the file when processing is complete. .TP .CR getpwuid () Searches from the beginning of the file until a numeric user .SM ID matching .I uid is found, and returns a pointer to the particular structure in which it was found. .TP .CR getpwnam () searches from the beginning of the file until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .CR fgetpwent () returns a pointer to the next .C passwd structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/passwd . .SS Reentrant Interfaces .CR getpwuid_r (), .CR getpwnam_r () and .CR fgetpwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .C passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in .C passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getpwent_r () requires a pointer to a .RI ( "FILE *" ) variable into which is stored the result of an .CR fopen () call on the .C /etc/passwd file. This is to allow threads to independently scan through the .C /etc/passwd file. .CR setpwent_r () and .CR endpwent_r () are to be used only in conjunction with .CR getpwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setpwent_r () can be used to rewind or open the .C /etc/passwd file. .CR endpwent_r () must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getpwent_r () or .CR setpwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH SECURITY FEATURES If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default .CR * that is in .C /etc/passwd and the audit ID and audit flag will be set to \(mi1. On trusted systems, if it is not necessary to obtain information from the regular password file, .CR /etc/passwd , users should use .CR getprpwent () to access the protected password database. See .IR getprpwent (3) and .IR getspwent (3X). .PP .CR putpwent () affects only .CR /etc/passwd ; the audit .SM ID and audit flag in the password structure are ignored. .CR putprpwnam () must be used to modify the protected password databse entries. See .IR getprpwent (3). .SH NETWORKING FEATURES .SS \s-1NFS\s0 If an entry beginning with a plus sign .RC ( + ) or a minus sign .RB ( \(mi ) is found, these routines try to use the Network Information Service network database for data. See .IR passwd (4) for proper syntax and operation. .PP Network Information Service (NIS) is not supported on trusted systems. .SH RETURN VALUE .CR getpwent (), .CR getpwuid (), .CR getpwnam (), and .CR fgetpwent () return a .SM NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .C passwd structure. .PP .CR getpwent_r (), .CR getpwuid_r (), .CR getpwnam_r (), and .CR fgetpwent_r (), return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getpwent() , .CR getpwuid() , and .CR fgetpwent() fail if any of the following are true: .RS .TP 15 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library, which causes them to increase the size of programs, not otherwise using standard .SM I/O and Network Information Service, more than might be expected. .PP The value returned by .CR getpwent() , .CR getpwuid() , .CR getpwnam() , and .C fgetpwent() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved. .PP .CR getpwent() , .CR getpwuid() , .CR getpwnam() , .CR setpwent() , .CR endpwent() , and .C fgetpwent() are unsafe in multi-thread applications. .CR getpwent_r() , .CR getpwuid_r() , .CR getpwnam_r() , .CR setpwent_r() , .CR endpwent_r() , and .C fgetpwent_r() are MT-Safe and should be used instead. .PP The following fields have numerical limitations as noted: .RS .TP 3 \(bu The user ID is an integer value between -2 and UID_MAX inclusive. .TP \(bu The group ID is an integer value between 0 and UID_MAX inclusive. .RE .PP Users of .CR getpwnam_r() and .CR getpwuid_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH EXAMPLE The following code excerpt counts the number of entries in the .C /etc/passwd file: .PP .nf .IP .C "int count = 0;" .C "struct passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setpwent_r(&pwf);" .C "while (getpwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endpwent_r(&pwf);" .fi .SH DEPENDENCIES .SS \s-1NFS\s0 .B Files: .RS .CI /var/yp/ domainname /passwd.byname .br .CI /var/yp/ domainname /passwd.byuid .RE .PP .B See Also: .RS ypcat(1). .RE .SH AUTHOR .CR getpwent (), .CR getpwuid (), .CR getpwnam (), .CR setpwent (), .CR endpwent (), and .CR fgetpwent () were developed by AT&T and HP. .SH FILES .TP 30 .C /etc/passwd System Password file .SH SEE ALSO ypcat(1), cuserid(3S), getgrent(3C), getlogin(3C), getprpwent(3), getspwent(3X), stdio(3S), putpwent(3C), putspwent(3X), passwd(4), limits(5). .SH STANDARDS CONFORMANCE .CR getpwent() ": SVID2, SVID3, XPG2" .PP .CR endpwent() ": SVID2, SVID3, XPG2" .PP .CR fgetpwent() ": SVID2, SVID3, XPG2" .PP .CR getpwnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpwuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setpwent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getpwent()\f1 \- get next password file entry@@@\f3getpwent(3C)\f1 .\" index@\f4fgetpwent()\f1 \- get next entry in password-file-formatted input stream@@@\f3getpwent(3C)\f1 .\" index@\f4getpwuid()\f1 \- get password file entry matching \f4uid()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4getpwnam()\f1 \- get password file entry matching login name \f4name()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4setpwent()\f1 \- rewind pointer to beginning of password file@@@\f3getpwent(3C)\f1 .\" index@\f4endpwent()\f1 \- close currently open password file@@@\f3getpwent(3C)\f1 .\" index@entry from password file, get@@@\f3getpwent(3C)\f1 .\" index@password file, get entry from@@@\f3getpwent(3C)\f1 .\" index@file, password: get entry from password file@@@\f3getpwent(3C)\f1 .\" .\" toc@\f3getpwent(3C)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f , \f4endpwent()\f1, \n\f4fgetpwent()\f1@@@get password file entry .\" toc@\f4getpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4setpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4endpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" .\" links@getpwent.3c getpwuid.3c .\" links@getpwent.3c getpwnam.3c .\" links@getpwent.3c setpwent.3c .\" links@getpwent.3c endpwent.3c .\" links@getpwent.3c fgetpwent.3c .\" links@getpwent.3c getpwent_r.3c .\" links@getpwent.3c getpwuid_r.3c .\" links@getpwent.3c getpwnam_r.3c .\" links@getpwent.3c setpwent_r.3c .\" links@getpwent.3c endpwent_r.3c .\" links@getpwent.3c fgetpwent_r.3c .\" .\" fileset_database@getpwent.3c PROGRAMING-MAN .\" $Header: getpwent.3c,v 78.1 95/12/20 10:53:01 ssa Exp $ .TA g .TH getpwent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpwent(\|), getpwent_r(\|), getpwuid(\|), getpwuid_r(\|), getpwnam(\|), getpwnam_r(\|), setpwent(\|), setpwent_r(\|), endpwent(\|), endpwent_r(\|), fgetpwent(\|), fgetpwent_r(\|) \- get password file entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct passwd *getpwent(void);" .PP .C "int getpwent_r(struct passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct passwd *getpwuid(uid_t uid);" .PP .PD 0 .C "int getpwuid_r(uid_t uid, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct passwd *getpwnam(const char *name);" .PP .PD 0 .C "int getpwnam_r(char *name, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setpwent(void);" .PP .C "void setpwent_r(FILE **pwfp);" .PP .C "void endpwent(void);" .PP .C "void endpwent_r(FILE **pwfp);" .PP .C "struct passwd *fgetpwent(FILE *stream);" .PP .C "int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, int buflen);" .fi .SH DESCRIPTION .CR getpwent (), .CR getpwuid (), and .CR getpwnam () locate an entry in the .C /etc/passwd file, and return a pointer to an object of .C passwd structure. .PP The .C passwd structure is defined in .RC < pwd.h > and includes the following members: .nf .IP .CR "char *pw_name; " "/* user name */" .CR "char *pw_passwd; " "/* encrypted password */" .CR "uid_t pw_uid; " "/* user id */" .CR "gid_t pw_gid; " "/* group id */" .CR "char *pw_age; " "/* password aging */" .CR "char *pw_comment;" "/* unused */" .CR "char *pw_gecos; " "/* user fullname, office, extension, homephone*/" .CR "char *pw_dir; " "/* initial directory */" .CR "char *pw_shell; " "/* initial shell */" .CR "aid_t pw_audid; " "/* numerical audit id */" .CR "int pw_audflg; " "/* numerical audit flag */" .fi .PP The .I pw_comment field is unused; for more information on the other fields, refer to .IR passwd (4). .TP 20 .CR getpwent () When first called, .CR getpwent () returns a pointer to the first .C passwd structure in the file. Thereafter, it returns a pointer to the next .C passwd structure in the file. In this way, successive calls can be used to search the entire file. .CR getpwent () opens the .C /etc/passwd file prior to doing its work and leaves the file open afterward; .TP .CR setpwent () Has the effect of rewinding this file to allow repeated searches; .TP .CR endpwent () Can be called to close the file when processing is complete. .TP .CR getpwuid () Searches from the beginning of the file until a numeric user .SM ID matching .I uid is found, and returns a pointer to the particular structure in which it was found. .TP .CR getpwnam () searches from the beginning of the file until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .CR fgetpwent () returns a pointer to the next .C passwd structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/passwd . .SS Reentrant Interfaces .CR getpwuid_r (), .CR getpwnam_r () and .CR fgetpwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .C passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in .C passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getpwent_r () requires a pointer to a .RI ( "FILE *" ) variable into which is stored the result of an .CR fopen () call on the .C /etc/passwd file. This is to allow threads to independently scan through the .C /etc/passwd file. .CR setpwent_r () and .CR endpwent_r () are to be used only in conjunction with .CR getpwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setpwent_r () can be used to rewind or open the .C /etc/passwd file. .CR endpwent_r () must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getpwent_r () or .CR setpwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH SECURITY FEATURES If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default .CR * that is in .C /etc/passwd and the audit ID and audit flag will be set to \(mi1. On trusted systems, if it is not necessary to obtain information from the regular password file, .CR /etc/passwd , users should use .CR getprpwent () to access the protected password database. See .IR getprpwent (3) and .IR getspwent (3X). .PP .CR putpwent () affects only .CR /etc/passwd ; the audit .SM ID and audit flag in the password structure are ignored. .CR putprpwnam () must be used to modify the protected password databse entries. See .IR getprpwent (3). .SH NETWORKING FEATURES .SS \s-1NFS\s0 If an entry beginning with a plus sign .RC ( + ) or a minus sign .RB ( \(mi ) is found, these routines try to use the Network Information Service network database for data. See .IR passwd (4) for proper syntax and operation. .PP Network Information Service (NIS) is not supported on trusted systems. .SH RETURN VALUE .CR getpwent (), .CR getpwuid (), .CR getpwnam (), and .CR fgetpwent () return a .SM NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .C passwd structure. .PP .CR getpwent_r (), .CR getpwuid_r (), .CR getpwnam_r (), and .CR fgetpwent_r (), return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getpwent() , .CR getpwuid() , and .CR fgetpwent() fail if any of the following are true: .RS .TP 15 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library, which causes them to increase the size of programs, not otherwise using standard .SM I/O and Network Information Service, more than might be expected. .PP The value returned by .CR getpwent() , .CR getpwuid() , .CR getpwnam() , and .C fgetpwent() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved. .PP .CR getpwent() , .CR getpwuid() , .CR getpwnam() , .CR setpwent() , .CR endpwent() , and .C fgetpwent() are unsafe in multi-thread applications. .CR getpwent_r() , .CR getpwuid_r() , .CR getpwnam_r() , .CR setpwent_r() , .CR endpwent_r() , and .C fgetpwent_r() are MT-Safe and should be used instead. .PP The following fields have numerical limitations as noted: .RS .TP 3 \(bu The user ID is an integer value between -2 and UID_MAX inclusive. .TP \(bu The group ID is an integer value between 0 and UID_MAX inclusive. .RE .PP Users of .CR getpwnam_r() and .CR getpwuid_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH EXAMPLE The following code excerpt counts the number of entries in the .C /etc/passwd file: .PP .nf .IP .C "int count = 0;" .C "struct passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setpwent_r(&pwf);" .C "while (getpwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endpwent_r(&pwf);" .fi .SH DEPENDENCIES .SS \s-1NFS\s0 .B Files: .RS .CI /var/yp/ domainname /passwd.byname .br .CI /var/yp/ domainname /passwd.byuid .RE .PP .B See Also: .RS ypcat(1). .RE .SH AUTHOR .CR getpwent (), .CR getpwuid (), .CR getpwnam (), .CR setpwent (), .CR endpwent (), and .CR fgetpwent () were developed by AT&T and HP. .SH FILES .TP 30 .C /etc/passwd System Password file .SH SEE ALSO ypcat(1), cuserid(3S), getgrent(3C), getlogin(3C), getprpwent(3), getspwent(3X), stdio(3S), putpwent(3C), putspwent(3X), passwd(4), limits(5). .SH STANDARDS CONFORMANCE .CR getpwent() ": SVID2, SVID3, XPG2" .PP .CR endpwent() ": SVID2, SVID3, XPG2" .PP .CR fgetpwent() ": SVID2, SVID3, XPG2" .PP .CR getpwnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpwuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setpwent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getpwent()\f1 \- get next password file entry@@@\f3getpwent(3C)\f1 .\" index@\f4fgetpwent()\f1 \- get next entry in password-file-formatted input stream@@@\f3getpwent(3C)\f1 .\" index@\f4getpwuid()\f1 \- get password file entry matching \f4uid()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4getpwnam()\f1 \- get password file entry matching login name \f4name()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4setpwent()\f1 \- rewind pointer to beginning of password file@@@\f3getpwent(3C)\f1 .\" index@\f4endpwent()\f1 \- close currently open password file@@@\f3getpwent(3C)\f1 .\" index@entry from password file, get@@@\f3getpwent(3C)\f1 .\" index@password file, get entry from@@@\f3getpwent(3C)\f1 .\" index@file, password: get entry from password file@@@\f3getpwent(3C)\f1 .\" .\" toc@\f3getpwent(3C)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f , \f4endpwent()\f1, \n\f4fgetpwent()\f1@@@get password file entry .\" toc@\f4getpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4setpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4endpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" .\" links@getpwent.3c getpwuid.3c .\" links@getpwent.3c getpwnam.3c .\" links@getpwent.3c setpwent.3c .\" links@getpwent.3c endpwent.3c .\" links@getpwent.3c fgetpwent.3c .\" links@getpwent.3c getpwent_r.3c .\" links@getpwent.3c getpwuid_r.3c .\" links@getpwent.3c getpwnam_r.3c .\" links@getpwent.3c setpwent_r.3c .\" links@getpwent.3c endpwent_r.3c .\" links@getpwent.3c fgetpwent_r.3c .\" .\" fileset_database@getpwent.3c PROGRAMING-MAN .\" $Header: getservent.3n,v 78.1 96/03/15 15:57:56 ssa Exp $ .TA g .TH getservent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getservent(), getservent_r(), getservbyport(), getservbyport_r(), getservbyname(), getservbyname_r(), setservent(), setservent_r(), endservent(), endservent_r() \- get service entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct servent *getservent(void);" .PP .C "int getservent_r(struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyname(const char *name, .C " const char *proto);" .PP .C "int getservbyname_r(const char *name," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyport(int port, const char *proto);" .PP .C "int getservbyport_r(int port," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PD .PP .C "int setservent(int stayopen);" .PP .C "int setservent_r(int stayopen, struct servent_data *buffer);" .PP .C "int endservent(void);" .PP .C "int endservent_r(struct servent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setservent(int stayopen);" .C "void endservent(void);" .fi .SH DESCRIPTION The .CR getservent() , .CR getservbyname() , and .CR getservbyport() functions each return a pointer to a structure of type .I servent containing the broken-out fields of a line in the network services data base, .CR /etc/services . .PP The members of this structure are: .RS .TP 15 .CR s_name The official name of the service. .TP .CR s_aliases A null-terminated list of alternate names for the service. .TP .CR s_port The port number at which the service resides. .TP .CR s_proto The name of the protocol to use when contacting the service. .RE .PP Functions behave as follows: .RS .TP 25 .CR getservent() Reads the next line of the file, opening the file if necessary. .TP .CR setservent() Opens and rewinds the file. If the .I stayopen flag is non-zero, the services data base is not closed after each call to .CR getservent() (either directly or indirectly through one of the other .CR getserv* calls). .TP .CR endservent() Closes the file. .TP .CR getservbyname() .PD 0 .TP .CR getservbyport() Each sequentially searches from the beginning of the file until a matching service name (among either the official names or the aliases) or port number is found, or until EOF is encountered. If a non-NULL protocol name is also supplied (such as .CR tcp or .CR udp ), searches must also match the protocol. .PD .IP If the system is running the Network Information Service (NIS), .CR getservbyname() gets the service information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getservent_r() , .CR getservbyname_r() , and .CR getservbyport_r() expect to be passed the address of a .CR "struct servent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct servent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct servent" will point, as well as state information such as open file descriptors. The .CR "struct servent_data" is defined in the file .CR . .PP .CR setservent_r() and .CR endservent_r() are to be used only in conjunction with .CR getservent_r() and take the same pointer to a .CR "struct servent_data" as a parameter. If the Network Information Service is being used, .CR setservent_r() initializes an internal database key. If the .CR /etc/services file is being used, .CR setservent_r() opens or rewinds the file. .CR endservent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setservent_r() currently has no effect. However, .CR setservent() can still be used to keep the .B /etc/services file open when making calls to .CR getservbyname_r() and .CR getservbyport_r() . .PP The .I serv_fp field in the .CR "servent_data struct" must be initialized to NULL before it is passed to either .CR getservent_r() or .CR setservent_r() for the first time. Thereafter it should not be modified in any way. This is the only .CR "servent_data" field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getservbyname() , .CR getservbyport() , .CR getservent() , and their reentrant counterparts, internally call the name service switch to access the "services" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve service names and ports. .SH RETURN VALUE .CR getservent() , .CR getservbyname() , and .CR getservbyport() return a null pointer (0) on EOF or when they are unable to open .CR /etc/services . .PP The reentrant .RC ( _r ) versions of these routines return .CR -1 if the operation is unsuccessful or, in the case of .CR getservent_r() , if the end of the services list has been reached. .CR 0 is returned otherwise. .SH EXAMPLES The following code excerpt counts the number of service entries: .RS .nf .PP .C "int count = 0;" .C "struct servent servbuf;" .C "struct servent_data sdbuf;" .PP .C "sdbuf.serv_fp = NULL;" .C "(void) setservent_r(0, &sdbuf);" .C "while (getservent_r(&servbuf, &sdbuf) != -1)" .C " count++;" .C "(void) endservent_r(&sdbuf);" .fi .RE .SH WARNINGS In the nonreentrant versions of these routines, all information is contained in a static area, so it must be copied if it is to be saved. .PP .CR getservent() , .CR getservbyport() , .CR getservbyname() , .CR setservent() , and .CR endservent() are unsafe in multi-thread applications. .CR getservent_r() , .CR getservbyport_r() , .CR getservbyname_r() , .CR setservent_r() , and .CR endservent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getservent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/services .SH SEE ALSO ypserv(1M), services(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getservent() ": XPG4" .\" .\" index@\f1end service entry@@@\f3getservent(3N)\f1 .\" index@\f1entry, get, set, or end service@@@\f3getservent(3N)\f1 .\" index@\f1get service entry@@@\f3getservent(3N)\f1 .\" index@\f1service entry, get, set, or end@@@\f3getservent(3N)\f1 .\" index@\f1set service entry@@@\f3getservent(3N)\f1 .\" index@\f1thread-safe, get, set, or end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent()\f1 \- end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent_r()\f1 \- end service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservent()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservent_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4setservent()\f1 \- set service entry@@@\f3getservent(3N)\f1 .\" index@\f4setservent_r()\f1 \- set service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" .\" links@getservent.3n endservent.3n .\" links@getservent.3n endservent_.3n .\" links@getservent.3n getservbyna.3n .\" links@getservent.3n getservbypo.3n .\" links@getservent.3n getservent_.3n .\" links@getservent.3n setservent.3n .\" links@getservent.3n setservent_.3n .\" .\" toc@\f3getservent(3N)\f1:\0\0\f4endservent()\f1, \f4endservent_r()\f1, \f4getservbyname()\f1, \f4getservbyname_r()\f1,\n\f4getservbyport()\f1, \f4getservbyport_r()\f1, \f4getservent()\f1, \f4getservent_r()\f1,\n\f4setservent()\f1, \f4setservent_r()\f1@@@get, set, or end service entry .\" .\" toc@\f4endservent()\f1:\0\0end service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4endservent_r()\f1:\0\0end service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent()\f1:\0\0set service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent_r()\f1:\0\0set service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" $Header: getservent.3n,v 78.1 96/03/15 15:57:56 ssa Exp $ .TA g .TH getservent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getservent(), getservent_r(), getservbyport(), getservbyport_r(), getservbyname(), getservbyname_r(), setservent(), setservent_r(), endservent(), endservent_r() \- get service entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct servent *getservent(void);" .PP .C "int getservent_r(struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyname(const char *name, .C " const char *proto);" .PP .C "int getservbyname_r(const char *name," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyport(int port, const char *proto);" .PP .C "int getservbyport_r(int port," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PD .PP .C "int setservent(int stayopen);" .PP .C "int setservent_r(int stayopen, struct servent_data *buffer);" .PP .C "int endservent(void);" .PP .C "int endservent_r(struct servent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setservent(int stayopen);" .C "void endservent(void);" .fi .SH DESCRIPTION The .CR getservent() , .CR getservbyname() , and .CR getservbyport() functions each return a pointer to a structure of type .I servent containing the broken-out fields of a line in the network services data base, .CR /etc/services . .PP The members of this structure are: .RS .TP 15 .CR s_name The official name of the service. .TP .CR s_aliases A null-terminated list of alternate names for the service. .TP .CR s_port The port number at which the service resides. .TP .CR s_proto The name of the protocol to use when contacting the service. .RE .PP Functions behave as follows: .RS .TP 25 .CR getservent() Reads the next line of the file, opening the file if necessary. .TP .CR setservent() Opens and rewinds the file. If the .I stayopen flag is non-zero, the services data base is not closed after each call to .CR getservent() (either directly or indirectly through one of the other .CR getserv* calls). .TP .CR endservent() Closes the file. .TP .CR getservbyname() .PD 0 .TP .CR getservbyport() Each sequentially searches from the beginning of the file until a matching service name (among either the official names or the aliases) or port number is found, or until EOF is encountered. If a non-NULL protocol name is also supplied (such as .CR tcp or .CR udp ), searches must also match the protocol. .PD .IP If the system is running the Network Information Service (NIS), .CR getservbyname() gets the service information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getservent_r() , .CR getservbyname_r() , and .CR getservbyport_r() expect to be passed the address of a .CR "struct servent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct servent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct servent" will point, as well as state information such as open file descriptors. The .CR "struct servent_data" is defined in the file .CR . .PP .CR setservent_r() and .CR endservent_r() are to be used only in conjunction with .CR getservent_r() and take the same pointer to a .CR "struct servent_data" as a parameter. If the Network Information Service is being used, .CR setservent_r() initializes an internal database key. If the .CR /etc/services file is being used, .CR setservent_r() opens or rewinds the file. .CR endservent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setservent_r() currently has no effect. However, .CR setservent() can still be used to keep the .B /etc/services file open when making calls to .CR getservbyname_r() and .CR getservbyport_r() . .PP The .I serv_fp field in the .CR "servent_data struct" must be initialized to NULL before it is passed to either .CR getservent_r() or .CR setservent_r() for the first time. Thereafter it should not be modified in any way. This is the only .CR "servent_data" field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getservbyname() , .CR getservbyport() , .CR getservent() , and their reentrant counterparts, internally call the name service switch to access the "services" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve service names and ports. .SH RETURN VALUE .CR getservent() , .CR getservbyname() , and .CR getservbyport() return a null pointer (0) on EOF or when they are unable to open .CR /etc/services . .PP The reentrant .RC ( _r ) versions of these routines return .CR -1 if the operation is unsuccessful or, in the case of .CR getservent_r() , if the end of the services list has been reached. .CR 0 is returned otherwise. .SH EXAMPLES The following code excerpt counts the number of service entries: .RS .nf .PP .C "int count = 0;" .C "struct servent servbuf;" .C "struct servent_data sdbuf;" .PP .C "sdbuf.serv_fp = NULL;" .C "(void) setservent_r(0, &sdbuf);" .C "while (getservent_r(&servbuf, &sdbuf) != -1)" .C " count++;" .C "(void) endservent_r(&sdbuf);" .fi .RE .SH WARNINGS In the nonreentrant versions of these routines, all information is contained in a static area, so it must be copied if it is to be saved. .PP .CR getservent() , .CR getservbyport() , .CR getservbyname() , .CR setservent() , and .CR endservent() are unsafe in multi-thread applications. .CR getservent_r() , .CR getservbyport_r() , .CR getservbyname_r() , .CR setservent_r() , and .CR endservent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getservent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/services .SH SEE ALSO ypserv(1M), services(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getservent() ": XPG4" .\" .\" index@\f1end service entry@@@\f3getservent(3N)\f1 .\" index@\f1entry, get, set, or end service@@@\f3getservent(3N)\f1 .\" index@\f1get service entry@@@\f3getservent(3N)\f1 .\" index@\f1service entry, get, set, or end@@@\f3getservent(3N)\f1 .\" index@\f1set service entry@@@\f3getservent(3N)\f1 .\" index@\f1thread-safe, get, set, or end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent()\f1 \- end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent_r()\f1 \- end service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservent()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservent_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4setservent()\f1 \- set service entry@@@\f3getservent(3N)\f1 .\" index@\f4setservent_r()\f1 \- set service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" .\" links@getservent.3n endservent.3n .\" links@getservent.3n endservent_.3n .\" links@getservent.3n getservbyna.3n .\" links@getservent.3n getservbypo.3n .\" links@getservent.3n getservent_.3n .\" links@getservent.3n setservent.3n .\" links@getservent.3n setservent_.3n .\" .\" toc@\f3getservent(3N)\f1:\0\0\f4endservent()\f1, \f4endservent_r()\f1, \f4getservbyname()\f1, \f4getservbyname_r()\f1,\n\f4getservbyport()\f1, \f4getservbyport_r()\f1, \f4getservent()\f1, \f4getservent_r()\f1,\n\f4setservent()\f1, \f4setservent_r()\f1@@@get, set, or end service entry .\" .\" toc@\f4endservent()\f1:\0\0end service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4endservent_r()\f1:\0\0end service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent()\f1:\0\0set service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent_r()\f1:\0\0set service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" $Header: getspent.3c,v 72.3 94/07/03 15:08:29 ssa Exp $ .TA g .TH getspent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME .CR getspent , .CR getspnam , .CR setspent , .C endspent \- access secure password entries, for trusted systems only. .SH SYNOPSIS .C #include .br .C struct spwd * getspent (void); .br .C struct spwd * getspnam (const char *name); .br .C void setspent (void) .br .C void endspent (void) .SH DESCRIPTION The routines .CR getspent () and .CR getspnam () return a pointer to the next secured password entry. Each entry is a .C spwd structure, declared in the .C shadow.h header file with the following members: .nf .IP .CR "char *sp_namp; " "/* the user's login name */" .CR "char *sp_pwdp; " "/* the encrypted password for the user */" .CR "long sp_lstchg; " "/* # of days from 1/1/70 when passwd was last modified */" .CR "long sp_min; " "/* min # of days allowed between password changes */" .CR "long sp_max; " "/* max # of days allowed between password changes */" .CR "long sp_warn; " "/* # of days before password expires and warning issued*/" .CR "long sp_inact; " "/* # of days between account inactive and disabled */" .CR "long sp_expire; " "/* # of days from 1/1/70 when account is locked */" .CR "unsigned long sp_flag;" "/* currently unused */" .fi .PP The .CR getspent () routine returns a pointer to the first .C spwd structure when first called. Subsequent calls return pointers to successive .C spwd structures. Repeated calls to .CR getspent () can be used to search all entries in the protected password database. The .C getspnam () routine searches password entries from beginning to end until a login name matching .I name is found, and returns a pointer to that entry. .PP If the fields corresponding to .CR sp_min , .CR sp_max , .CR sp_lstchg , .CR sp_warn , .CR sp_inact , .CR sp_expire , or .C sp_flag are not specified in the entry, they default to -1. If an end-of-file or an error is encountered in reading or a format error is detected, these functions return a null pointer and; for an error, .C errno is set to .CR EINVAL . .PP The .CR setspent () routine is used to reset access to the secured password entries. After .CR setspent () is called, the subsequent call to .CR getspent () returns the first secured password entry. This mechanism is used to allow repeated searches of the secured password entries. The .CR endspent () routine is used to indicate that processing of secured password entries is complete. .PP .CR getspent () is only supported on trusted systems. .PP The secured password facility is implemented without the use of the .C /etc/shadow file. .CR getspent (), .CR getspnam (), .CR setspent (), and .CR endspent () read from the trusted system's protected password database .RC ( /tcb/files/auth/\c .I *\c .C /\c .IR * ) and not .CR /etc/shadow . The file .C /etc/shadow is not used in any way by the HP-UX login facility. .PP These routines return a null pointer and sets ERRNO to ENOENT if the system has not been converted to trusted system. In all other cases, the return value is set similarly to .CR getprpwent (). See .IR getprpwent (3) for more information. .PP Programs using these routines must be compiled with .CR \-lsec . .SH FILES .TP 30 .PD 0 .C /etc/passwd System Password file. .TP .CR /tcb/files/auth/*/* Protected password database, for trusted systems. .PD .SH SEE ALSO getpwent(3C), getprpwent(3C), passwd(4). .SH DIAGNOSTICS .CR getspent (), .CR getspnam (), and .CR fgetspent () return a null pointer on EOF or error. .SH STANDARDS CONFORMANCE .C getspent : SVID3 .\" index@\f4getspent()\fP \- get next secure password file entry@@@\f3getspent(3C)\f1 .\" index@\f4getspnam()\fP \- get secure password file entry matching \f4name()\fP@@@\f3getspent(3C)\f1 .\" index@\f4setspent()\fP \- rewind pointer to beginning of secure password file@@@\f3getspent(3C)\f1 .\" index@\f4endspent()\fP \- close currently open secure password file@@@\f3getspent(3C)\f1 .\" index@entry from secure password file, get@@@\f3getspent(3C)\f1 .\" index@trusted system password database, get entry from@@@\f3getspent(3C)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspent(3C)\f1 .\" .\" toc@\f3getspent(3C)\f1:\0\0\f4getspent()\fP, \f4getspnam()\fP, \f4setspent()\fP, \f4endspent()\fP@@@get secure password file entry .\" toc@\f4getspent()\fP:\0\0get secure password file entry@@@see \f3getspent(3C)\f1 .\" toc@\f4setpwent()\fP:\0\0get secure password file entry@@@see \f3getspent(3C)\f1 .\" toc@\f4endpwent()\fP:\0\0get secure password file entry@@@see \f3getspent(3C)\f1 .\" .\" links@getspent.3c getspnam.3c .\" links@getspent.3c setspent.3c .\" links@getspent.3c endspent.3c .\" .\" $Header: getspwent.3x,v 72.6 94/11/30 10:11:44 ssa Exp $ .TA g .TH getspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getspwent(\|), getspwent_r(\|), getspwuid(\|), getspwuid_r(\|), getspwaid(\|), getspwaid_r(\|), getspwnam(\|), getspwnam_r(\|), setspwent(\|), setspwent_r(\|), endspwent(\|), endspwent_r(\|), fgetspwent(\|), fgetspwent_r(\|) \- get secure password file entry\c , on trusted systems .SH SYNOPSIS .C "#include " .PP .C "struct s_passwd *getspwent(void);" .PP .C "int getspwent_r(struct s_passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct s_passwd *getspwuid(uid_t uid);" .PP .PD 0 .C "int getspwuid_r(uid_t uid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwaid(aid_t aid);" .PP .PD 0 .C "int getspwaid_r(aid_t aid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwnam(const char *name);" .PP .PD 0 .C "int getspwnam_r(char *name, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setspwent(void);" .PP .C "void setspwent_r(FILE **pwfp);" .PP .C "void endspwent(void);" .PP .C "void endspwent_r(FILE **pwfp);" .PP .C "struct s_passwd *fgetspwent(\s-1FILE\s0 *stream);" .PP .PD 0 .C "int fgetspwent_r(FILE *f, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .SH DESCRIPTION These privileged routines provide access to the protected password database in a manner similar to the way .IR getpwent (3C) routines handle the regular password file, .RC ( \|/etc/passwd\| ). .PP These routines are particularly useful in situations where it is not necessary to get information from the regular password file. .IR getspwent (3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, .CR libsec . .PP Note that .CR getspwent () routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the .CR getprpwent () routines. See .IR getprpwent (3). .PP .CR getspwent (), .CR getspwuid (), .CR getspwaid (), and .CR getspwnam () each returns a pointer to an object of .CR s_passwd structure. The .CR s_passwd structure is maintained for compatibility with existing software and consists of five fields as follows: .nf .IP .C "struct\ s_passwd\ {" .C " char *pw_name; /* login name */" .C " char *pw_passwd; /* encrypted password */" .C " char *pw_age; /* password age */" .C " int pw_audid; /* audit ID */" .C " int pw_audflg; /* audit flag 1=on, 0=off */" .C }; .fi .PP Since the .CR s_passwd structure is declared in the .RC < pwd.h > header file, it is unnecessary to redeclare it. .PP To access other fields in the protected password database that are not included in the .CR s_passwd structure, use .CR getprpwent (). See .IR getprpwent (3) for more information. .PP .TP 20 .CR getspwent () When first called, .CR getspwent () returns a pointer to each .CR s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database. .TP .CR getspwuid () Searches for an entry that matches the specified .IR uid . It then returns a pointer to the particular structure in which .I uid is found. .TP .CR getspwaid () Similarly searches for a numerical audit ID matching .I aid and returns a pointer to the particular structure in which .I aid is found (see .IR spasswd (4) for details on this field). .TP .CR getspwnam () Searches for an entry that matches the specified .IR name . Returns a pointer to the particular structure in which .I name is found. .TP .CR setspwent () Resets the protected password database pointer to the beginning of the file to allow repeated searches. .TP .CR endspwent () Should be called to close the protected password database file when processing is complete. .TP .CR fgetspwent () Is no longer supported. It is provided for those applications that did not use .CR /.secure/etc/passwd . .SS Reentrant Interfaces .CR getspwuid_r (), .CR getspwaid_r (), .CR getspwnam_r (), and .CR fgetspwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .CR s_passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in the .CR s_passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getspwent_r () requires a pointer to a .RI ( "FILE *" ) variable. .CR setspwent_r () and .CR endspwent_r () are to be used only in conjunction with .CR getspwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setspwent_r () can be used to rewind or open the protected password database. .CR endspwent_r () should be called when done to close the file. .PP The .CR /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database. .PP .CR fgetspwent_r () is no longer supported, but is included for those users that did not use the .CR /.secure/etc/passwd file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getspwent_r () or .CR setspwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH RETURN VALUE .CR getspwent () returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the calling process is not zero. .PP .CR getspwent_r () returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned. .SH WARNINGS The above routines use .RC < stdio.h >, which causes them to increase the size of programs by more than might otherwise be expected. .PP Since all information for .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() is contained in a static area, it must be copied to be saved. .PP .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() are unsafe in multi-thread applications. .CR getspwent_r() , .CR getspwuid_r() , .CR getspwaid_r() , .CR getspwnam_r() , .CR setspwent_r() , .CR endspwent_r() , and .CR fgetspwent_r() are MT-Safe and should be used instead. .PP Network Information Service is not supported on trusted systems. .SH EXAMPLE The following code excerpt counts the number of entries in the protected password database: .nf .IP .C "int count = 0;" .C "struct s_passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setspwent_r(&pwf);" .C "while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endspwent_r(&pwf);" .SH AUTHOR .CR getspwent () was developed by HP. .SH FILES .TP 30 .C /tcb/files/auth/*/* Protected Password database .SH SEE ALSO ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), putspwent(3X), passwd(4). .\" .\" index@\f4getspwent()\f1 \- get next secure password file entry@@@\f3getspwent(3X)\f1 .\" index@\f4getspwaid()\f1 \- get next secure password file audit ID@@@\f3getspwent(3X)\f1 .\" index@\f4fgetspwent()\f1 \- get next entry in secure password-file-formatted input stream@@@\f3getspwent(3X)\f1 .\" index@\f4getspwuid()\f1 \- get secure password file entry matching \f4uid()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4getspwnam()\f1 \- get secure password file entry matching login name \f4name()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4setspwent()\f1 \- rewind pointer to beginning of secure password file@@@\f3getspwent(3X)\f1 .\" index@\f4endspwent()\f1 \- close currently open secure password file@@@\f3getspwent(3X)\f1 .\" index@entry from secure password file, get@@@\f3getspwent(3X)\f1 .\" index@secure password file, get entry from@@@\f3getspwent(3X)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspwent(3C)\f1 .\" .\" toc@\f3getspwent(3X)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f1,\n\f4endpwent()\f1, \f4fgetpwent()\f1@@@get secure password file entry .\" toc@\f4getpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4setpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4endpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4getspwaid()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" .\" links@getspwent.3x getspwuid.3x .\" links@getspwent.3x getspwnam.3x .\" links@getspwent.3x setspwent.3x .\" links@getspwent.3x endspwent.3x .\" links@getspwent.3x fgetspwent.3x .\" links@getspwent.3x getspwaid.3x .\" links@getspwent.3x getspwent_r.3x .\" links@getspwent.3x getspwuid_r.3x .\" links@getspwent.3x getspwaid_r.3x .\" links@getspwent.3x getspwnam_r.3x .\" links@getspwent.3x setspwent_r.3x .\" links@getspwent.3x endspwent_r.3x .\" links@getspwent.3x fgetspwent_.3x .\" .\" fileset_database@getspwent.3x PROGRAMING-MAN .\" $Header: getspwent.3x,v 72.6 94/11/30 10:11:44 ssa Exp $ .TA g .TH getspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getspwent(\|), getspwent_r(\|), getspwuid(\|), getspwuid_r(\|), getspwaid(\|), getspwaid_r(\|), getspwnam(\|), getspwnam_r(\|), setspwent(\|), setspwent_r(\|), endspwent(\|), endspwent_r(\|), fgetspwent(\|), fgetspwent_r(\|) \- get secure password file entry\c , on trusted systems .SH SYNOPSIS .C "#include " .PP .C "struct s_passwd *getspwent(void);" .PP .C "int getspwent_r(struct s_passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct s_passwd *getspwuid(uid_t uid);" .PP .PD 0 .C "int getspwuid_r(uid_t uid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwaid(aid_t aid);" .PP .PD 0 .C "int getspwaid_r(aid_t aid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwnam(const char *name);" .PP .PD 0 .C "int getspwnam_r(char *name, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setspwent(void);" .PP .C "void setspwent_r(FILE **pwfp);" .PP .C "void endspwent(void);" .PP .C "void endspwent_r(FILE **pwfp);" .PP .C "struct s_passwd *fgetspwent(\s-1FILE\s0 *stream);" .PP .PD 0 .C "int fgetspwent_r(FILE *f, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .SH DESCRIPTION These privileged routines provide access to the protected password database in a manner similar to the way .IR getpwent (3C) routines handle the regular password file, .RC ( \|/etc/passwd\| ). .PP These routines are particularly useful in situations where it is not necessary to get information from the regular password file. .IR getspwent (3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, .CR libsec . .PP Note that .CR getspwent () routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the .CR getprpwent () routines. See .IR getprpwent (3). .PP .CR getspwent (), .CR getspwuid (), .CR getspwaid (), and .CR getspwnam () each returns a pointer to an object of .CR s_passwd structure. The .CR s_passwd structure is maintained for compatibility with existing software and consists of five fields as follows: .nf .IP .C "struct\ s_passwd\ {" .C " char *pw_name; /* login name */" .C " char *pw_passwd; /* encrypted password */" .C " char *pw_age; /* password age */" .C " int pw_audid; /* audit ID */" .C " int pw_audflg; /* audit flag 1=on, 0=off */" .C }; .fi .PP Since the .CR s_passwd structure is declared in the .RC < pwd.h > header file, it is unnecessary to redeclare it. .PP To access other fields in the protected password database that are not included in the .CR s_passwd structure, use .CR getprpwent (). See .IR getprpwent (3) for more information. .PP .TP 20 .CR getspwent () When first called, .CR getspwent () returns a pointer to each .CR s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database. .TP .CR getspwuid () Searches for an entry that matches the specified .IR uid . It then returns a pointer to the particular structure in which .I uid is found. .TP .CR getspwaid () Similarly searches for a numerical audit ID matching .I aid and returns a pointer to the particular structure in which .I aid is found (see .IR spasswd (4) for details on this field). .TP .CR getspwnam () Searches for an entry that matches the specified .IR name . Returns a pointer to the particular structure in which .I name is found. .TP .CR setspwent () Resets the protected password database pointer to the beginning of the file to allow repeated searches. .TP .CR endspwent () Should be called to close the protected password database file when processing is complete. .TP .CR fgetspwent () Is no longer supported. It is provided for those applications that did not use .CR /.secure/etc/passwd . .SS Reentrant Interfaces .CR getspwuid_r (), .CR getspwaid_r (), .CR getspwnam_r (), and .CR fgetspwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .CR s_passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in the .CR s_passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getspwent_r () requires a pointer to a .RI ( "FILE *" ) variable. .CR setspwent_r () and .CR endspwent_r () are to be used only in conjunction with .CR getspwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setspwent_r () can be used to rewind or open the protected password database. .CR endspwent_r () should be called when done to close the file. .PP The .CR /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database. .PP .CR fgetspwent_r () is no longer supported, but is included for those users that did not use the .CR /.secure/etc/passwd file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getspwent_r () or .CR setspwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH RETURN VALUE .CR getspwent () returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the calling process is not zero. .PP .CR getspwent_r () returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned. .SH WARNINGS The above routines use .RC < stdio.h >, which causes them to increase the size of programs by more than might otherwise be expected. .PP Since all information for .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() is contained in a static area, it must be copied to be saved. .PP .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() are unsafe in multi-thread applications. .CR getspwent_r() , .CR getspwuid_r() , .CR getspwaid_r() , .CR getspwnam_r() , .CR setspwent_r() , .CR endspwent_r() , and .CR fgetspwent_r() are MT-Safe and should be used instead. .PP Network Information Service is not supported on trusted systems. .SH EXAMPLE The following code excerpt counts the number of entries in the protected password database: .nf .IP .C "int count = 0;" .C "struct s_passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setspwent_r(&pwf);" .C "while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endspwent_r(&pwf);" .SH AUTHOR .CR getspwent () was developed by HP. .SH FILES .TP 30 .C /tcb/files/auth/*/* Protected Password database .SH SEE ALSO ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), putspwent(3X), passwd(4). .\" .\" index@\f4getspwent()\f1 \- get next secure password file entry@@@\f3getspwent(3X)\f1 .\" index@\f4getspwaid()\f1 \- get next secure password file audit ID@@@\f3getspwent(3X)\f1 .\" index@\f4fgetspwent()\f1 \- get next entry in secure password-file-formatted input stream@@@\f3getspwent(3X)\f1 .\" index@\f4getspwuid()\f1 \- get secure password file entry matching \f4uid()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4getspwnam()\f1 \- get secure password file entry matching login name \f4name()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4setspwent()\f1 \- rewind pointer to beginning of secure password file@@@\f3getspwent(3X)\f1 .\" index@\f4endspwent()\f1 \- close currently open secure password file@@@\f3getspwent(3X)\f1 .\" index@entry from secure password file, get@@@\f3getspwent(3X)\f1 .\" index@secure password file, get entry from@@@\f3getspwent(3X)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspwent(3C)\f1 .\" .\" toc@\f3getspwent(3X)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f1,\n\f4endpwent()\f1, \f4fgetpwent()\f1@@@get secure password file entry .\" toc@\f4getpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4setpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4endpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4getspwaid()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" .\" links@getspwent.3x getspwuid.3x .\" links@getspwent.3x getspwnam.3x .\" links@getspwent.3x setspwent.3x .\" links@getspwent.3x endspwent.3x .\" links@getspwent.3x fgetspwent.3x .\" links@getspwent.3x getspwaid.3x .\" links@getspwent.3x getspwent_r.3x .\" links@getspwent.3x getspwuid_r.3x .\" links@getspwent.3x getspwaid_r.3x .\" links@getspwent.3x getspwnam_r.3x .\" links@getspwent.3x setspwent_r.3x .\" links@getspwent.3x endspwent_r.3x .\" links@getspwent.3x fgetspwent_.3x .\" .\" fileset_database@getspwent.3x PROGRAMING-MAN .\" $Header: getusershel.3c,v 72.6 94/11/02 15:43:32 ssa Exp $ .TA g .TH getusershell 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getusershell(\|), getusershell_r(\|), setusershell(\|), setusershell_r(\|), endusershell(\|), endusershell_r(\|) \- get legal user shells .SH SYNOPSIS .C "#include " .PP .C "char *getusershell(void);" .PP .C "char *getusershell_r(char **shell_datap);" .PP .C "void setusershell(void);" .PP .C "void setusershell_r(char **shell_datap);" .PP .C "void endusershell(void);" .PP .C "void endusershell_r(char **shell_datap);" .SH DESCRIPTION .TP 25 .CR getusershell() Returns a pointer to the first legal user shell as defined in the file .CR /etc/shells (see .IR shells (4)). If .CR /etc/shells does not exist or is not readable, .CR getusershell() returns the following standard system shells: .RS .nf .IP .CR /sbin/sh .CR /usr/bin/sh .CR /usr/bin/rsh .CR /usr/bin/ksh .CR /usr/bin/rksh .CR /usr/bin/csh .CR /usr/bin/keysh .fi .RE .IP as if they were contained in .CR /etc/shells . The file is left open so that the next call returns the next shell. A null pointer (0) is returned on .SM EOF or error. .TP .CR setusershell() Rewinds the file. .TP .CR endusershell() Closes the file. .SS Reentrant Interfaces .PP .CR getusershell_r() , .CR setusershell_r() and .CR endusershell_r() expect to be passed the address of a character pointer so that state information can be maintained between calls. .I *shell_datap should be initialized to .SM NULL before the first call to either .CR setusershell_r() or .CR getusershell_r() . Thereafter it should not be modified. After the first call to .CR setusershell_r() or .CR getusershell_r() , .I *shell_datap points to state information that is needed on subsequent calls to .CR getusershell_r() . .PP .CR endusershell_r() should be called when done so that any memory that has been internally allocated can be freed. .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area and therefore must be copied if it is to be saved. .PP .CR getusershell() , .CR setusershell() , and .CR endusershell() are unsafe in multi-thread applications. .CR getusershell_r() , .CR setusershell_r() , and .CR endusershell_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getusershell() was developed by HP and the University of California, Berkeley. .SH FILES .CR /etc/shells .SH SEE ALSO shells(4). .\" .\" index@\f4getusershell()\fP \- get legal user shells@@@\f3getusershell(3C)\f1 .\" index@\f4setusershell()\fP \- rewind legal user shells file@@@\f3getusershell(3C)\f1 .\" index@\f4endusershell()\fP \- close legal user shells file@@@\f3getusershell(3C)\f1 .\" index@get legal user shells@@@\f3getusershell(3C)\f1 .\" index@rewind legal user shells file@@@\f3getusershell(3C)\f1 .\" index@close legal user shells file@@@\f3getusershell(3C)\f1 .\" index@legal user shells, get@@@\f3getusershell(3C)\f1 .\" index@user shells, get legal@@@\f3getusershell(3C)\f1 .\" index@shells, get legal user@@@\f3getusershell(3C)\f1 .\" .\" toc@\f3getusershell(3C)\f1:\0\0\f4getusershell()\fP, \f4setusershell()\fP, \f4endusershell()\fP@@@get legal user shells .\" toc@\f4endusershell()\fP \- close legal user shells file@@@see \f3getusershell(3C)\f1 .\" toc@\f4setusershell()\fP \- rewind legal user shells file@@@see \f3getusershell(3C)\f1 .\" .\" links@getusershel.3c setusershel.3c .\" links@getusershel.3c endusershel.3c .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getutx.3c,v 76.4 95/09/12 12:01:34 ssa Exp $ .TA g .TH getutx 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutxent(\|), getutxid(\|), getutxline(\|), pututxline(\|), setutxent(\|), endutxent(\|) \- access utmpx file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmpx *getutxent(void);" .PP .C "struct utmpx *getutxid(const struct utmpx *id);" .nf .PP .C "struct utmpx *getutxline(const struct utmpx *line);" .PP .C "struct utmpx *_pututxline(const struct utmpx *utmpx);" .PP .C "void pututxline(const struct utmpx *utmpx);" .PP .C "void setutxent(void);" .PP .C "void endutxent(void);" .PP .fi .SH DESCRIPTION .CR getutxent() , .CR getutxid() , and .C getutxline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmpx { char ut_user[24]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct __exit_status { short __e_termination; /* Process termination status */ short __e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ struct timeval { time_t tv_sec; /* seconds */ long tv_usec; /* and microseconds */ } ut_tv; /* time entry was made */ char ut_host[64]; /* host name, if remote; NOT SUPPORTED */ unsigned long ut_addr; /* Internet addr of host, if remote */ char ut_reserved2[12] ; /* Reserved for future use */ }; .ps .ft .fi .RE .TP 20 .C getutxent() Reads in the next entry from a .CR utmpx -like file. If the file is not already open, .C getutxent() opens it. If it reaches the end of the file, .C getutxent() fails. .TP .C getutxid() Searches forward from the current point in the .I utmpx file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutxid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutxid() fails. .TP .C getutxline() Searches forward from the current point in the .I utmpx file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutxline() fails. .TP .C pututxline() Writes out the supplied .C utmpx structure into the .I utmpx file, translates the supplied .C utmpx structure into a .C utmp structure and writes it to a .I utmp file. .C pututxline() uses .C getutxid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getutx() routines before calling .CR pututxline() . If the search as already been made, .C pututxline() does not repeat it. If .C pututxline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututxline() Performs the same actions as .CR pututxline() , except that it returns a value useful for error checking. .TP .C setutxent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutxent() Closes the currently open file. .TP .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutxid() or .CR getutxline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutxline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutxline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututxline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutxent() , .CR getutxid() , or .C getutxline() if the user has just modified those contents and passed the pointer back to .CR pututxline() . .PP .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmpx)" . .PP .C _pututxline() behaves the same as .CR pututxline() , except that it returns a pointer to a static location containing the most current utmpx entry if the .C _pututxline() call succeeds. The contents of this structure are identical to the contents of the supplied .C utmpx structure if successful. If .C _pututline() fails upon writing to .C utmpx , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmpx file and fails in writing to the .C utmp file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmpx file and the .C utmp file may not be in sync due to the above behavior. .C pututxline() and .C _pututxline() are only guaranteed to have written to the .C utmpx file upon successful completion. .SH FILES .PP .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututline(3), utmpname(3). .SH STANDARDS CONFORMANCE .CR endutxent() ": XPG4.2" .PP .CR getutxent() ": XPG4.2" .PP .CR getutxid() ": XPG4.2" .PP .CR getutxline() ": XPG4.2" .PP .CR pututxline() ": XPG4.2" .PP .CR setutxent() ": XPG4.2" .PP .\" .\" index@\f4getutxent()\f1 \- get pointer to next entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4_pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4setutxent()\f1 \- reset input stream to beginning of \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4endutxent()\f1 \- close currently open \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@access \f4utmpx()\f1 or \f4wtmp()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4utmpx()\f1 or \f4wtmp()\f1 file, access@@@\f3getutx(3C)\f1 .\" index@file: access \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" .\" toc@\f3getutx(3C)\f1:\0\0\f4getutxent()\f1, \f4getutxid()\f1, \f4getutxline()\f1, \f4pututxline()\f1, \f4setutxent()\f1,\n\f4endutxent()\f1@@@access utmpx file entry .\" toc@\f4getutxent()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxid()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4_pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4setutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4endutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f1utmpx file entry@@@see \f3getutx(3C)\f1 .\" .\" links@getutx.3c getutxent.3c .\" links@getutx.3c getutxid.3c .\" links@getutx.3c getutxline.3c .\" links@getutx.3c pututxline.3c .\" links@getutx.3c _pututxline.3c .\" links@getutx.3c setutxent.3c .\" links@getutx.3c endutxent.3c .\" $Header: endwin.3x,v 76.2 95/07/31 17:45:46 ssa Exp $ .TA e .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH endwin 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME endwin \(em suspend Curses session .SH SYNOPSIS .C "#include " .P .C "int endwin(void);" .SH DESCRIPTION The .Fn endwin function restores the terminal after Curses activity by at least restoring the saved shell terminal mode, flushing any output to the terminal and moving the cursor to the first column of the last line of the screen. Refreshing a window resumes program mode. The application must call .Fn endwin for each terminal being used before exiting. If .Fn newterm is called more than once for the same terminal, the first screen created must be the last one for which .Fn endwin is called. .SH "RETURN VALUE" Upon successful completion, .Fn endwin returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn endwin function does not free storage associated with a screen, so .Fn delscreen should be called after .Fn endwin if a particular screen is no longer needed. .P To leave Curses mode temporarily, portable applications should call .CR endwin() . Subsequently, to return to Curses mode, they should call .CR doupdate() , .Fn refresh or .Fn wrefresh . .SS "SEE ALSO" delscreen(), doupdate(), initscr(), isendwin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list is explicitly declared as \f3void\f1. .\" .\" index@\f4endwin()\f1 \- suspend Curses session@@@\f3endwin(3X)\f1 .\" index@\f1suspend Curses session@@@\f3endwin(3X)\f1 .\" index@\f1Curses session, suspend@@@\f3endwin(3X)\f1 .\" .\" toc@\f3endwin(3X)\f1:\0\0\f4endwin()\f1@@@suspend Curses session .\" .\" fileset_database@endwin.3x CURS-ENG-A-MAN .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: clear.3x,v 76.2 95/07/31 17:24:33 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH clear 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clear, erase, wclear, werase \(em clear a window .SH SYNOPSIS .C "#include " .P .C "int clear(void);" .P .C "int erase(void);" .P .C "int wclear(WINDOW *\f2win\fP);" .P .C "int werase(WINDOW *\f2win\fP);" .SH DESCRIPTION The .CR clear() , .CR erase() , .Fn wclear and .Fn werase functions clear every position in the current or specified window. .P The .Fn clear and .Fn wclear functions also achieve the same effect as calling .Fn clearok , so that the window is cleared completely on the next call to .Fn wrefresh for the window and is redrawn in its entirety. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" clearok(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn erase and .Fn werase functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The argument list for the .Fn clear and .Fn erase functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3clear(3X)\f1:\0\0\f4clear()\f1, \f4erase()\f1, \f4wclear()\f1, \f4werase()\f1@@@clear a window .\" toc@\f4erase()\f1: clear a window@@@see \f3clear(3X)\f1 .\" toc@\f4werase()\f1: clear a window@@@see \f3clear(3X)\f1 .\" toc@\f4wclear()\f1: clear a window@@@see \f3clear(3X)\f1 .\" .\" index@\f4clear()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f4wclear()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f4erase()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f4werase()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f1clear a window@@@\f3clear(3X)\f1 .\" index@\f1window, clear@@@\f3clear(3X)\f1 .\" .\" links@clear.3x wclear.3x .\" links@clear.3x erase.3x .\" links@clear.3x werase.3x .\" .\" fileset_database@clear.3x CURS-ENG-A-MAN .\" $Header: erasechar.3x,v 76.2 95/07/31 17:46:43 ssa Exp $ .TA e .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH erasechar 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME erasechar, killchar \(em single-byte terminal environment query functions .SH SYNOPSIS .C "#include " .P .C "char erasechar(void);" .P .C "char killchar(void);" .SH DESCRIPTION The .Fn erasechar function returns the current erase character. \ The .Fn erasewchar function stores the current erase character in the object pointed to by \f2ch\f1. If no erase character has been defined, the function will fail and the object pointed to by \f2ch\f1 will not be changed. .P The .Fn killchar function returns the current line kill character. .SH "RETURN VALUE" The .Fn erasechar function returns the erase character and .Fn killchar returns the line kill character. The return value is unspecified when these characters are multi-byte characters. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn erasechar and .Fn killchar functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. Moreover, they do not reliably indicate cases in which when the erase or line kill character, respectively, has not been defined. The .Fn erasewchar and .Fn killwchar functions overcome these limitations. .SH "SEE ALSO" \f3Attributes\f1 in curses_intro, clearok(), delscreen(), erasewchar(), , tcgetattr() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn killchar function is merged with this entry. In previous issues, it appeared in an entry of its own. .P The entry is rewritten for clarity. The argument list for the .Fn erasechar and .Fn killchar functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3erasechar(3X)\f1:\0\0\f4erasechar()\f1, \f4killchar()\f1@@@single-byte terminal environment query functions .\" toc@\f4killchar()\f1: single-byte line kill character@@@see \f3erasechar(3X)\f1 .\" .\" index@\f4erasechar()\f1 \- single-byte erase character@@@\f3erasechar(3X)\f1 .\" index@\f4killchar()\f1 \- single-byte line kill@@@\f3erasechar(3X)\f1 .\" index@\f1single-byte terminal environment query functions@@@\f3erasechar(3X)\f1 .\" index@\f1line kill character, single-byte@@@\f3erasechar(3X)\f1 .\" index@\f1erase character, single-byte@@@\f3erasechar(3X)\f1 .\" .\" links@erasechar.3x killchar.3x .\" .\" fileset_database@erasechar.3x CURS-ENG-A-MAN .\" $Header: erasewchar.3x,v 76.2 95/07/31 17:47:49 ssa Exp $ .TA e .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH erasewchar 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME erasewchar, killwchar \(em terminal environment query functions .SH SYNOPSIS .C "#include " .P .C "int erasewchar(wchar_t *\f2ch\fP);" .P .C "int killwchar(wchar_t *\f2ch\fP);" .SH DESCRIPTION The .Fn erasewchar function stores the current erase character in the object pointed to by \f2ch\f1. If no erase character has been defined, the function will fail and the object pointed to by \f2ch\f1 will not be changed. .P The .Fn killwchar function stores the current line kill character in the object pointed to by \f2ch\f1. If no line kill character has been defined, the function will fail and the object pointed to by \f2ch\f1 will not be changed. .SH "RETURN VALUE" .P Upon successful completion, .Fn erasewchar and .Fn killwchar return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Attributes\f1 in curses_intro, clearok(), delscreen(), , tcgetattr() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3erasewchar(3X)\f1:\0\0\f4erasewchar()\f1, \f4killwchar()\f1@@@current erase and line kill characters .\" toc@\f4killwchar()\f1: current line kill character@@@see \f3erasewchar(3X)\f1 .\" .\" index@\f4erasewchar()\f1 \- current erase character@@@\f3erasewchar(3X)\f1 .\" index@\f4killwchar()\f1 \- current line kill character@@@\f3erasewchar(3X)\f1 .\" index@\f1current erase and line kill characters@@@\f3erasewchar(3X)\f1 .\" index@\f1line kill character@@@\f3erasewchar(3X)\f1 .\" index@\f1kill line character@@@\f3erasewchar(3X)\f1 .\" index@\f1erase character@@@\f3erasewchar(3X)\f1 .\" .\" links@erasewchar.3x killwchar.3x .\" .\" fileset_database@erasewchar.3x CURS-ENG-A-MAN .\" $Header: erf.3m,v 78.2 96/02/13 10:27:30 ssa Exp $ .TA e .TH erf 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME erf(\|), erfc(\|) \- error function and complementary error function .SH SYNOPSIS .C "#include " .PP .C "double erf(double x);" .PP .C "double erfc(double x);" .SH DESCRIPTION .CR erf() returns the error function of .IR x , defined as: .RS .HP .RC (2/ sqrt ( pi )) * .br (integral with respect to .I t from 0 to .I x of .RC ( exp ( pow (\-\f2t\f1,2)))) .RE .PP .CR erfc() returns the complementary value, 1.0 \(mi .CI erf( x )\f1. It prevents the extreme loss of relative accuracy if .CI erf( x ) is called for a large .I x and the result is subtracted from 1.0 (for example, for .I x = 5, twelve decimal places are lost). .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is +INFINITY, .CR erf() returns 1.0. .PP If .I x is \(miINFINITY, .CR erf() returns \(mi1.0. .PP If .I x is +INFINITY, .CR erfc() returns zero. .PP If .I x is \(miINFINITY, .CR erfc() returns 2.0. .PP If .I x is NaN, .CR erf() and .CR erfc() return NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR erf() and .CR erfc() return zero. .SH ERRORS No errors are defined. .SH SEE ALSO exp(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR erf() ": SVID3, XPG4.2" .PP .CR erfc() ": SVID3, XPG4.2" .\" .\" index@\f4erf()\f1 \- error function@@@\f3erf(3M)\f1 .\" index@\f4erfc()\f1 \- complementary error function@@@\f3erf(3M)\f1 .\" index@\f1math: error function and complementary error function@@@\f3erf(3M)\f1 .\" index@\f1error function@@@\f3erf(3M)\f1 .\" index@\f1complementary error function@@@\f3erf(3M)\f1 .\" .\" toc@\f3erf(3M)\f1:\0\0\f4erf()\f1, \f4erfc()\f1@@@error function and complementary error function .\" toc@\f4erfc()\f1:\0\0complementary error function@@@see \f3erf(3M)\f1 .\" .\" links@erf.3m erfc.3m .\" $Header: erf.3m,v 78.2 96/02/13 10:27:30 ssa Exp $ .TA e .TH erf 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME erf(\|), erfc(\|) \- error function and complementary error function .SH SYNOPSIS .C "#include " .PP .C "double erf(double x);" .PP .C "double erfc(double x);" .SH DESCRIPTION .CR erf() returns the error function of .IR x , defined as: .RS .HP .RC (2/ sqrt ( pi )) * .br (integral with respect to .I t from 0 to .I x of .RC ( exp ( pow (\-\f2t\f1,2)))) .RE .PP .CR erfc() returns the complementary value, 1.0 \(mi .CI erf( x )\f1. It prevents the extreme loss of relative accuracy if .CI erf( x ) is called for a large .I x and the result is subtracted from 1.0 (for example, for .I x = 5, twelve decimal places are lost). .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is +INFINITY, .CR erf() returns 1.0. .PP If .I x is \(miINFINITY, .CR erf() returns \(mi1.0. .PP If .I x is +INFINITY, .CR erfc() returns zero. .PP If .I x is \(miINFINITY, .CR erfc() returns 2.0. .PP If .I x is NaN, .CR erf() and .CR erfc() return NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR erf() and .CR erfc() return zero. .SH ERRORS No errors are defined. .SH SEE ALSO exp(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR erf() ": SVID3, XPG4.2" .PP .CR erfc() ": SVID3, XPG4.2" .\" .\" index@\f4erf()\f1 \- error function@@@\f3erf(3M)\f1 .\" index@\f4erfc()\f1 \- complementary error function@@@\f3erf(3M)\f1 .\" index@\f1math: error function and complementary error function@@@\f3erf(3M)\f1 .\" index@\f1error function@@@\f3erf(3M)\f1 .\" index@\f1complementary error function@@@\f3erf(3M)\f1 .\" .\" toc@\f3erf(3M)\f1:\0\0\f4erf()\f1, \f4erfc()\f1@@@error function and complementary error function .\" toc@\f4erfc()\f1:\0\0complementary error function@@@see \f3erf(3M)\f1 .\" .\" links@erf.3m erfc.3m .\" $Header: perror.3c,v 74.1 95/03/23 18:05:29 ssa Exp $ .TA p .TH perror 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME perror(\|), strerror(\|), strerror_r(\|), errno, sys_errlist, sys_nerr \- system error messages .SH SYNOPSIS .C "#include " .PP .C "void perror(const char *s);" .PP .C "char *strerror(int errnum);" .PP .C "int strerror_r(int errnum, char *buffer, int buflen);" .PP .C "extern int errno;" .PP .C "extern char *sys_errlist[\|];" .PP .C "extern int sys_nerr;" .SH DESCRIPTION .CR perror() writes a language-dependent message to the standard error output, describing the last error encountered during a call to a system or library function. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. To be most useful, the argument string should include the name of the program that incurred the error. The error number is taken from the external variable .CR errno , which is set when errors occur but not cleared when non-erroneous calls are made. The contents of the message is identical to those returned by the .CR strerror() function with .CR errno as the argument. If given a .SM NULL string, the .CR perror() function prints only the message and a new-line. .PP To simplify variant formatting of messages, the .CR strerror() function and the .CR sys_errlist array of message strings are provided. The .CR strerror() function maps the error number in .I errnum to a language-dependent error message string and returns a pointer to the string. The message string is returned without a new-line. .CR errno can be used as an index into .CR sys_errlist to get an untranslated message string without the new-line. .CR sys_nerr is the largest message number provided for in the table; it should be checked because new error codes might be added to the system before they are added to the table. .CR strerror() must be used to retrieve messages when translations are desired. .PP .CR strerror_r() is identical to .CR strerror() , except that the result string is passed back in the supplied buffer. A buffer length of 80 is recommended. If an error is detected or the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .SH EXTERNAL INFLUENCES .SS Environment Variables The language of the message returned by .CR strerror() and printed by .CR perror() is specified by the .CR LANG environment variable. If the language-dependent message is not available, or if .CR LANG is not set or is set to the empty string, the default version of the message associated with the "C" language (see .IR lang (5)) is used. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .CR perror() returns no value. .PP If the .I errnum message number is valid, .CR strerror() returns a pointer to a language-dependent message string. The array pointed to should not be modified by the program, and might be overwritten by a subsequent call to the function. If a valid .I errnum message number does not have a corresponding language-dependent message, .CR strerror() uses .I errnum as an index into .CR sys_errlist to get the message string. If the .I errnum message number is invalid, .CR strerror() returns a pointer to a .SM NULL string. .SH WARNINGS The return value for .CR strerror() points to static data whose content is overwritten by each call. .CR strerror() is unsafe for multi-thread applications. .CR strerror_r() is MT-Safe and should be used instead. .br .ne 12v .SH SEE ALSO errno(2), lang(5), environ(5). .SH STANDARDS CONFORMANCE .CR perror() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strerror() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR sys_errlist() ": SVID2, SVID3, XPG2" .PP .CR sys_nerr() ": SVID2, SVID3, XPG2" .\" .\" index@\f4perror()\fP, \f4errno()\fP, \f4sys_errlist()\fP, \f4sys_nerr()\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4errno\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4strerror()\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4sys_errlist\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4sys_nerr\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@system error messages@@@\f3perror(3C)\f1 .\" index@error messages, system@@@\f3perror(3C)\f1 .\" index@messages, system error@@@\f3perror(3C)\f1 .\" .\" toc@\f3perror(3C)\f1:\0\0\f4perror()\fP, \f4errno()\fP, \f4sys_errlist()\f1, \f4sys_nerr()\f1@@@system error messages .\" toc@\f4errno\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4strerror()\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4sys_errlist\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4sys_nerr\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" .\" links@perror.3c strerror.3c .\" links@perror.3c strerror_r.3c .\" links@perror.3c errno.3c .\" links@perror.3c sys_errlist.3c .\" links@perror.3c sys_nerr.3c .\" $Header: error_c_get.3,v 72.4 94/10/27 14:32:36 ssa Exp $ .TA e .TH error_$c_get_text 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME error_$c_get_text \- return subsystem, module, and error texts for a status code .SH SYNOPSIS .nf .C void error_$c_get_text( .PD 0 .IP .C status_$t \f2status\fP, .C char *\f2subsys\fP, .C long \f2subsysmax\fP, .C char *\f2module\fP, .C long \f2modulemax\fP, .C char *\f2error\fP, .C long \f2errormax\fP) .fi .PD .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RB `` $ '' character. .SH DESCRIPTION The .C error_$c_get_text() call returns predefined text strings that describe the subsystem, the module, and the error represented by a status code. The strings are null terminated. .RS .TP .I status A status code in .C status_$t format. .TP .I subsys A character string. The subsystem represented by the status code. .TP .I subsysmax The maximum number of bytes to be returned in .IR subsys . .TP .I module A character string. The module represented by the status code. .TP .I modulemax The maximum number of bytes to be returned in .IR module . .TP .I error A character string. The error represented by the status code. .TP .I errormax The maximum number of bytes to be returned in .IR error . .RE .SH EXAMPLE The following statement returns text strings for the subsystem, module, and error represented by the status code .CR st : .IP .C "error_$c_get_text (st, subsys, MAX, module, MAX, error, MAX\s0);" .SH SEE ALSO error_$intro(3), error_$c_text(3). .\" .\" index@\f4error_$c_get_text()\fP \- return subsystem, module, and error texts for a status code@@@\f3error_$c_get_text(3)\f1 .\" index@subsystem, module, and error texts for a status code, return@@@\f3error_$c_get_text(3)\f1 .\" index@module, and error texts for a status code, return subsystem,@@@\f3error_$c_get_text(3)\f1 .\" index@error texts for a status code, return subsystem, module, and@@@\f3error_$c_get_text(3)\f1 .\" index@texts for a status code, return subsystem, module, and error@@@\f3error_$c_get_text(3)\f1 .\" index@status code, return subsystem, module, and error texts for a@@@\f3error_$c_get_text(3)\f1 .\" .\" toc@\f3error_$c_get_text(3)\f1:\0\0\f4error_$c_get_text()\fP@@@return subsystem, module, and error texts for a status code .\" .\" fileset_database@error_c_get.3 PROGRAMING-MAN .\" $Header: error_c_tex.3,v 72.4 94/10/27 14:33:17 ssa Exp $ .TA e .TH error_$c_text 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME error_$c_text \- return an error message for a status code .SH SYNOPSIS .nf .PD 0 .C char *error_$c_text( .IP .C status_$t \f2status\fP, .C char *\f2message\fP, .C int \f2messagemax\fP) .fi .PD .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RB `` $ '' character. .SH DESCRIPTION .C error_$c_text() returns a null-terminated error message for reporting the completion status of a call. The error message is composed from predefined text strings that describe the subsystem, the module, and the error represented by the status code. .RS .TP 15 .I status A status code in .C status_$t format. .TP .I message A character string. The error message represented by the status code. .TP .I messagemax The maximum number of bytes to be returned in .IR message . .RE .SH EXAMPLE The following statement returns an error message for reporting the status code .CR st : .IP .C error_$c_text (st, message, MAX\s0); .SH SEE ALSO error_$intro(3), error_$c_get_text(3). .\" .\" index@\f4error_$c_text()\fP \- return an error message for a status code@@@\f3error_$c_text(3)\f1 .\" index@error message for a status code, return an@@@\f3error_$c_text(3)\f1 .\" index@message for a status code, return an error@@@\f3error_$c_text(3)\f1 .\" index@completion status code, return an error message for a@@@\f3error_$c_text(3)\f1 .\" index@status code, return an error message for a@@@\f3error_$c_text(3)\f1 .\" .\" toc@\f3error_$c_text(3)\f1:\0\0\f4error_$c_text()\fP@@@return an error message for a status code .\" .\" fileset_database@error_c_tex.3 PROGRAMING-MAN .\" $Header: error_intro.3,v 72.4 94/10/27 14:33:58 ssa Exp $ .TA e .TH error_$intro 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME error_$intro \- error text database operations .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RB `` $ '' character. .SH DESCRIPTION .C error_$() calls are part of the Network Computing System. .C error_$() calls convert status codes into textual error messages, and include: .RS .TP 20 .C error_$c_get_text() Return subsystem, module, and error texts for a status code. .TP .C error_$c_text() Return an error message for a status code. .RE .PP There is no header file for the .C error_$() calls. They can be declared as follows: .IP .C extern void error_$c_get_text(); .br .C extern char *error_$c_text(); .PP .C error_$() calls use the .C status_$t data type, which is defined in .RC < idl/c/nbase.h >. .SS Data Types .C error_$() calls take as input a status code in .C status_$t format. .RS .TP 15 .C status_$t A status code. Most .SM NCS calls supply their completion status in this format. The .C status_$t type is defined as a structure containing a long integer: .RS .nf .IP .C struct status_$t { .C " long all;" .C " }" .RE .fi .IP However, the calls can also use .C status_$t as a set of bit fields. To access the fields in a returned status code, assign the value of the status code to a union defined as follows: .RS .nf .IP .C typedef union { .C " struct {" .C " unsigned fail : 1," .C " subsys : 7," .C " modc : 8;" .C " short code;" .C " } s;" .C " long all;" .C } status_u; .fi .RE .TP .C all All 32 bits in the status code. If .C all is equal to .CR status_$ok , the call that supplied the status was successful. .TP .C fail If this bit is set, the error was not within the scope of the module invoked, but occurred within a lower-level module. .TP .C subsys This indicates the subsystem that encountered the error. .TP .C modc This indicates the module that encountered the error. .TP .C code This is a signed number that identifies the type of error that occurred. .RE .SH SEE ALSO error_$c_get_text(3), error_$c_text(3). .\" .\" index@\f2error_$intro\f1 \- error text database operations@@@\f3error_$intro(3)\f1 .\" index@error text database operations@@@\f3error_$intro(3)\f1 .\" index@text database operations, error@@@\f3error_$intro(3)\f1 .\" index@database operations, error text@@@\f3error_$intro(3)\f1 .\" .\" toc@\f3error_$intro(3)\f1:\0\0\f2error_$intro\f1@@@error text database operations .\" .\" fileset_database@error_intro.3 PROGRAMING-MAN .\" $Header: end.3c,v 72.5 94/11/14 15:27:57 ssa Exp $ .TH end 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME .\"end, etext, edata \- last locations in program end, etext, edata, __data_start, __text_start \- last locations in program .SH SYNOPSIS .\".C "extern void *_end, *end, *_etext, *etext, *_edata, *edata;" .C "extern void *_end, *end, *_etext, *etext, *_edata, *edata, *__data_start," .C " *__text_start;" .SH DESCRIPTION These names refer neither to routines nor to locations with interesting contents. The address of the symbols .C _etext and .C etext is the first address above the program text, the address of .C _edata and .C edata is the first address above the initialized data region, and the address of .C _end and .C end is the first address above the uninitialized data region. .PP The address of the symbols .C __data_start is the beginning address of the program's data area, and .C __text_start is the beginning address of the program's text area. .PP The linker defines these symbols with the appropriate values if they are referenced by the program but not defined. The linker issues an error if the user attempts to define .CR _etext , .CR _edata , .\"or .\".CR _end . .CR _end , .CR __data_start , or .CR __text_start . .PP When execution begins, the program break (the first location beyond the data) coincides with .CR _end , but the program break can be reset by the routines of .IR brk (2), .IR malloc (3C), standard input/output .RI ( stdio (3S)), the profile .RC ( -p ) option of .IR cc (1), and so on. Thus, the current value of the program break should be determined by .C sbrk(0) (see .IR brk (2)). .SH WARNINGS In C, these names must look like addresses. Thus, use .C &end instead of .C end to access the current value of .IR end . .SH SEE ALSO .PD .SS System Tools: .TP 18 .IR cc(1) invoke the HP-UX C compiler .PD 0 .TP .IR ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 .IR brk(2) change data segment space allocation .PD 0 .TP .IR crt0(3) execution startup routine .TP .IR malloc(3C) main memory allocator .TP .IR stdio(3S) standard buffered input/output stream file package .PD .SH STANDARDS CONFORMANCE .CR end() ": XPG2" .PP .CR edata() ": XPG2" .PP .CR etext() ": XPG2" .\" .\" index \f4end\fP \- first address beyond uninitialized program data region \f3end(3C)\f1 .\" index \f4edata\fP \- first address beyond initialized program data region \f3end(3C)\f1 .\" index \f4etext\fP \- first address beyond program text region \f3end(3C)\f1 .\" index last locations of allocated regions in program \f3end(3C)\f1 .\" index end locations of allocated regions in program \f3end(3C)\f1 .\" index addresses \- first locations beyond allocated program regions \f3end(3C)\f1 .\" index first locations beyond allocated program regions \f3end(3C)\f1 .\" index locations beyond allocated program regions, first \f3end(3C)\f1 .\" index allocated program regions, first locations beyond \f3end(3C)\f1 .\" index program regions, first locations beyond allocated \f3end(3C)\f1 .\" index regions, first locations beyond allocated program \f3end(3C)\f1 .\" .\" toc \f3end(3C)\f1:\0\0\f4end\fP, \f4etext\fP, \f4edata\fP last locations in program .\" toc \f4etext\fP:\0\0last locations in program see \f3end(3C)\f1 .\" toc \f4edata\fP:\0\0last locations in program see \f3end(3C)\f1 .\" .\" links end.3c etext.3c .\" links end.3c edata.3c .\" .\" fileset_database end.3c PROG-AUX-MAN ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" Copyright (c) 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH exceptions 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .zA " New reference page " .SH NAME .PP \*Lexceptions\*O - Exception handling in DCE Threads .wH "" .SH "DESCRIPTION" .PP DCE Threads provides the following two ways to obtain information about the status of a threads routine: .ad l .ML .LI The routine returns a status value to the thread. .LI The routine raises an exception. .LE .ad b .PP Before you write a multithreaded program, you must choose only one of the preceding two methods of receiving status. These two methods cannot be used together in the same code module. .PP .zA"defect,5262,R1.0.2, value 1 should be -1" The POSIX P1003.4a (pthreads) draft standard specifies that errors be reported to the thread by setting the external variable \*Lerrno\*O to an error code and returning a function value of \-1. .zZ"defect,5262,R1.0.2, value 1 should be -1" The threads reference pages document this status value-returning interface. However, an alternative to status values is provided by DCE Threads in the exception-returning interface. .PP Access to exceptions from the C language is defined by the macros in the \*Lexc_handling.h\*O file. The \*Lexc_handling.h\*O header file is included automatically when you include \*Lpthread_exc.h.\*O .PP To use the exception-returning interface, replace .oS #include .oE .wH "" with the following include statement: .zA "def,7544,R1.0.3,corrected include path" .oS #include .wH "" .oE .zZ "def,7544,R1.0.3,corrected include path" .PP The following example shows the syntax for handling exceptions: .oS TRY try_block [CATCH (exception_name) handler_block]... [CATCH_ALL handler_block] ENDTRY .oE ...\" .zZ " New reference page " .wH "" .\" $Header: exp.3m,v 78.1 96/02/13 10:28:02 ssa Exp $ .TA e .TH exp 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME exp(\|), expf(\|) \- exponential functions .SH SYNOPSIS .C "#include " .PP .C "double exp(double x);" .PP .C "float expf(float x);" .SH DESCRIPTION .CR exp() returns .ifn \f2e\f1^\f2x\f1. .ift \f2e\u\s-2x\s0\d\f1. .PP .CR expf() is a .CR float version of .CR exp() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR expf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is +INFINITY, .CR exp() returns +INFINITY. .PP If .I x is \(miINFINITY, .CR exp() returns zero. .PP If .I x is NaN, .CR exp() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR exp() returns zero. .PP If the correct value would overflow, .CR exp() returns .CR HUGE_VAL and sets .CR errno to [ERANGE]. .RE .SH ERRORS If .CR exp() fails, .CR errno is set to the following value. .RS .TP 20 [ERANGE] The correct value would overflow. .RE .SH DEPENDENCIES Millicode versions of the .CR exp() function are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO log(3M), pow(3M), sqrt(3M), cbrt(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR exp() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4exp()\f1, \f4expf()\f1 \- exponential functions@@@\f3exp(3M)\f1 .\" index@\f4expf()\f1, \f4exp()\f1 \- exponential functions@@@\f3exp(3M)\f1 .\" index@\f1math: exponential functions@@@\f3exp(3M)\f1 .\" index@\f1exponential functions@@@\f3exp(3M)\f1 .\" .\" toc@\f3exp(3M)\f1:\0\0\f4exp()\f1, \f4expf()\f1@@@exponential functions .\" toc@\f4expf()\f1:\0\0exponential function (float version)@@@see \f3exp(3M)\f1 .\" .\" links@exp.3m expf.3m .\" .\" fileset_database@exp.3m PROGRAMING-MAN .\" $Header: exp.3m,v 78.1 96/02/13 10:28:02 ssa Exp $ .TA e .TH exp 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME exp(\|), expf(\|) \- exponential functions .SH SYNOPSIS .C "#include " .PP .C "double exp(double x);" .PP .C "float expf(float x);" .SH DESCRIPTION .CR exp() returns .ifn \f2e\f1^\f2x\f1. .ift \f2e\u\s-2x\s0\d\f1. .PP .CR expf() is a .CR float version of .CR exp() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR expf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is +INFINITY, .CR exp() returns +INFINITY. .PP If .I x is \(miINFINITY, .CR exp() returns zero. .PP If .I x is NaN, .CR exp() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR exp() returns zero. .PP If the correct value would overflow, .CR exp() returns .CR HUGE_VAL and sets .CR errno to [ERANGE]. .RE .SH ERRORS If .CR exp() fails, .CR errno is set to the following value. .RS .TP 20 [ERANGE] The correct value would overflow. .RE .SH DEPENDENCIES Millicode versions of the .CR exp() function are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO log(3M), pow(3M), sqrt(3M), cbrt(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR exp() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4exp()\f1, \f4expf()\f1 \- exponential functions@@@\f3exp(3M)\f1 .\" index@\f4expf()\f1, \f4exp()\f1 \- exponential functions@@@\f3exp(3M)\f1 .\" index@\f1math: exponential functions@@@\f3exp(3M)\f1 .\" index@\f1exponential functions@@@\f3exp(3M)\f1 .\" .\" toc@\f3exp(3M)\f1:\0\0\f4exp()\f1, \f4expf()\f1@@@exponential functions .\" toc@\f4expf()\f1:\0\0exponential function (float version)@@@see \f3exp(3M)\f1 .\" .\" links@exp.3m expf.3m .\" .\" fileset_database@exp.3m PROGRAMING-MAN .\" $Header: expm1.3m,v 78.1 96/02/13 10:31:54 ssa Exp $ .TA e .TH expm1 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME expm1(\|) \- computes exponential functions .SH SYNOPSIS .C "#include " .PP .C "double expm1(double x);" .SH DESCRIPTION The .CR expm1() function is equivalent to .CI exp( x ) \- 1, but may be more accurate for very small values of .IR x . .PP The .CR expm1() and .CR log1p() functions are useful to guarantee that financial calculations of \%(((1+\f2x\f1)**n)-1)/\f2x\f1, namely: .sp .in +1 .CR expm1 "(n * " log1p (\f2x\f1))/\f2x\f1 .sp .in -1 are accurate when .I x is very small (for example, when calculating small daily interest rates). These functions also simplify writing accurate inverse hyperbolic functions. .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH "RETURN VALUE" If .I x is +INFINITY, .CR expm1() returns +INFINITY. .PP If .I x is \(miINFINITY, .CR expm1() returns \-1.0. .PP If .I x is NaN, .CR expm1() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR expm1() returns zero. .PP If the value overflows, .CR expm1() returns .CR HUGE_VAL and sets .CR errno to [ERANGE]. .SH "ERRORS" If .CR expm1() fails, .CR errno is set to the following value. .RS .TP 20 [ERANGE] The result overflows. .SH "SEE ALSO" exp(3M), log1p(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR expm1() ": XPG4.2" .\" index@\f4expm1()\f1 \- exponential functions@@@\f3expm1(3M)\f1 .\" index@exponential functions@@@\f3expm1(3M)\f1 .\" index@math: exponential functions@@@\f3expm1(3M)\f1 .\" .\" toc@\f3expm1(3M)\f1:\0\0\f4expm1()\f1@@@exponential functions .\" .\" fileset_database@expm1.3m PROGRAMING-MAN .\" $Header: exportent.3n,v 74.1 95/01/25 16:26:52 ssa Exp $ .TA e .TH exportent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME exportent(\|), getexportent(\|), setexportent(\|), addexportent(\|), remexportent(\|), endexportent(\|), getexportopt(\|) \- access exported file system information .SH SYNOPSIS .nf .C #include .C #include .PP .C "FILE *setexportent();" .PP .C "struct exportent *getexportent(FILE *fildep);" .PP .C "int addexportent(FILE *filep, char *dirname, char *options);" .PP .C "int remexportent(FILE *filep, char *dirname);" .PP .C "char *getexportopt(struct exportent *xent, char *opt);" .PP .C "void endexportent(FILE *filep);" .fi .SH DESCRIPTION These routines access the exported filesystem information in .CR /etc/xtab . .ift .TP 22 .ifn .TP 10 .C setexportent() Open the export information file and return a file pointer to use with .CR getexportent() , .CR addexportent() , .CR remexportent() , and .CR endexportent() . Returns .SM NULL if the file is locked or if an error is encountered in opening the file. .TP .C getexportent() Read the next line from .I filep and return a pointer to an object with the following structure containing the broken-out fields of a line in file .CR /etc/xtab . The fields have meanings described in .IR exports (4). .nf .IP .ift .ft 4 .ifn .ft 3 #define ACCESS_OPT "access" /* machines that can mount fs */ #define ROOT_OPT "root" /* machines with root access to fs */ #define RO_OPT "ro" /* export read-only */ #define ANON_OPT "anon" /* uid for anonymous requests */ #define ASYNC_OPT "async" /* all mounts will be aynchronous */ .ift .sp .5v .ifn .sp 1v struct exportent { char *xent_dirname; /* directory (or file) to export */ char *xent_options; /* options, as above */ }; .ft .fi .IP .C getexportent() returns .SM NULL if it encounters end of file. .TP .C addexportent() Add the .I exportent to the end of the open file .IR filep . It returns 0 if successful and \(mi1 on failure. .TP .C remexportent() Remove the indicated entry from the list. Returns 0 on success and \(mi1 on failure. .TP .C getexportopt() Scans the .C xent_options field of the .C exportent structure for a substring that matches .IR opt . Returns the string value of .IR opt , or .SM NULL if the option is not found. .TP .C endexportent() Close the file. .SH RETURN VALUE .CR setexportent() , .CR getexportent() , and .C getexportopt() return a .SM NULL pointer on .SM EOF or error. .PP .C addexportent() and .C remexportent() return \(mi1 if they fail. .SH WARNINGS The returned .C exportent structure points to static information that is overwritten in each call. .SH AUTHOR .CR exportent , .CR getexportent() , .CR setexportent() , .CR addexportent() , .CR remexportent() , .CR endexportent() , and .C getexportopt() were developed by Sun Microsystems, Inc. .SH FILES .C /etc/exports .C /etc/xtab .SH SEE ALSO exportfs(1M), exports(4). .\" .\" toc@\f3exportent(3N)\f1:\0\0\f4exportent(\|)\f1, \f4getexportent(\|)\f1, \f4setexportent(\|)\f1, \f4addexportent(\|)\f1, \f4remexportent(\|)\f1,\n\f4endexportent(\|)\f1, \f4getexportopt(\|)\f1@@@access exported file system information .\" toc@\f4getexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4setexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4addexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4remexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4endexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4getexportopt(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" .\" index@\f4exportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4getexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4setexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4addexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4remexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4endexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4getexportopt(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@access exported file system information@@@\f3exportent(3N)\f1 .\" index@exported file system information, access@@@\f3exportent(3N)\f1 .\" index@file system information, access exported@@@\f3exportent(3N)\f1 .\" index@information, access exported file system@@@\f3exportent(3N)\f1 .\" .\" links@exportent.3n getexporten.3n .\" links@exportent.3n setexporten.3n .\" links@exportent.3n addexporten.3n .\" links@exportent.3n remexporten.3n .\" links@exportent.3n endexporten.3n .\" links@exportent.3n getexportop.3n .\" .\" fileset_database@exportent.3n PROGRAMING-MAN .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "expose" "Xt \- Intrinsics Methods" .SH "Name" .Na expose \- Core class method that draws a widget's graphics. .Nz .XS "methods: expose; XtExposeProc" .XS "expose, method" .SH "Synopsis" .Sy typedef void (*XtExposeProc)(Widget, XEvent *, Region); .As Widget \f(CIw\fP; XEvent *\f(CIevent\fP; Region \f(CIregion\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget instance requiring redisplay. .IP \f(CIevent\fP 1i Specifies the exposure event giving the rectangle requiring redisplay. .IP \f(CIregion\fP 1i Specifies the union of all rectangles in this exposure sequence. .\" .SH "Description" The \f(CWexpose()\fP method is installed on the \f(CWexpose\fP field of the Core class part structure, and is called to draw or redraw the widget's window when exposure events arrive for that window. An \f(CWexpose()\fP method may also be registered on the \f(CWexpose\fP field of the RectObj class part structure, but because RectObj widgets do not have windows, this method will not be called by the Intrinsics. (Although some composite widgets may call the \f(CWexpose()\fP methods of their non-widget children.) .LP The \f(CIw\fP argument is the widget for which exposure events have arrived. \f(CIevent\fP is the exposure event, or the latest in a series of exposure events, if the widget uses exposure compression. It contains a bounding box of the exposed area. \f(CIregion\fP is \f(CWNULL\fP if there is no exposure compression, or specifies the union of all exposure events in the compressed sequence. The \f(CWexpose()\fP method must redraw at least the graphics within the bounding box of the event. Simple widgets may simply redraw their entire window; more complicated widgets may attempt to minimize the amount of redraw required by using the \f(CIregion\fP argument. Exposure compression is specified with the \f(CWcompress_exposure\fP field in the Core class part structure. See the "Background" section below for details. .LP A widget need not redisplay itself if it is not visible. A widget can obtain a hint about whether it is currently visible by checking the \f(CWvisible\fP field in the Core instance structure. If \f(CWvisible_interest\fP in the Core class structure is \f(CWTrue\fP, then the \f(CWvisible\fP field is usually \f(CWFalse\fP if no part of the widget is currently visible. See the "Background" section for details. .LP The \f(CWexpose()\fP method is not chained. A widget class can inherit the \f(CWexpose()\fP method of its superclass by specifying \f(CWXtInheritExpose\fP on the \f(CWexpose\fP field of its RectObj or Core class part structure. A widget that does not display any graphics (such as many composite widgets) can set this field to \f(CWNULL\fP. .LP The long "Usage" section below explains some common strategies to handling expose events on a widget. .\" .SH "Usage" The \f(CWexpose()\fP method is responsible for initially drawing into a widget's window and for redrawing the window every time a part of the window becomes exposed. This redrawing is necessary because the X server does not normally maintain the contents of windows when they are obscured. When a window becomes visible again, it must be redrawn. .LP .XX "display, display lists" Most widgets keep track of what they draw in some form of arrays or display lists. This could be an array of lines of text to be drawn, for example, or an array of lines which can be drawn with a single call to \f(CWXDrawLines()\fP. When a widget of this sort needs to redisplay itself, it simply calls the procedure that draws the widget based on the saved data. .LP The graphic contents of a widget often change in response to user events handled with action procedures or event handlers. These procedures usually draw into the widget directly, but must also store the appropriate data so that the current state of the widget can be regenerated, if necessary. .LP An \f(CWexpose()\fP method can be made more efficient if as much data as possible is pre-computed. A label widget that draws its text centered in its window, for example, should pre-compute the x and y coordinates at which the text will be drawn. If it does not, the expose method will have to compute the position based on the height of the font, the width of the string (which is time consuming to compute), and the size of the window. These pre-computed positions should only need to be updated in the \f(CWresize()\fP and \f(CWset_values()\fP methods. .LP Simple widgets may just redisplay their entire window when the expose event is called. More complicated widgets may redisplay everything within the bounding box of the event (which will be the same as the bounding box of the specified Region if it is non-\f(CWNULL\fP). For widgets that are very time-consuming for the client or server to redraw, you might want to use this region in a more sophisticated way. You can use this region as a clip mask in your GC (see \f(CWXSetRegion()\fP) to clip output to the exposed region, and possibly calculate which drawing primitives affect this area. Xlib also provides region mathematics routines (such as \f(CWXRectInRegion()\fP) so that you can compare the regions in which your widget needs to draw graphics with the region that was exposed. If certain areas do not require redrawing, you can skip the code that redraws them. If you plan to write a sophisticated \f(CWexpose()\fP method, bear in mind that the calculations required to optimize the redisplay are time consuming, too, and too much clipping and testing of rectangles may slow down your widget. The cost/benefit ratio should be examined. .XX "XRectInRegion Xlib function" .XX "regions" .LP Some widgets do not bother to remember how to redraw themselves. Instead they draw their graphics into a pixmap and copy the contents of the pixmap into their window as needed. For some widgets this approach is much simpler than retaining the state needed to redraw from scratch. If the widget is very large, however, the pixmap will take up a lot of memory in the X server. .LP A widget that is insensitive (see \f(CWXtSetSensitive\fP(1)) may wish to indicate this to the user by drawing itself in a different way. A common approach is to draw with a GC with a stipple to so that everything appears "grayed-out." .LP A composite widget that accepts non-widget children which are subclasses of RectObj ("gadgets") will have to display the graphics of those children in its own window. It may narrowly define the types of children it will accept to be the type of children that it knows how to draw. Or instead it may require that its RectObj children have their own \f(CWexpose()\fP methods and call those methods when it .ne 2 detects that the region of the window occupied by a child needs to be redrawn. .LP If a widget has no display semantics, it can specify \f(CWNULL\fR for the \f(CWexpose()\fR field. Many composite widgets serve only as containers for their children and have no \f(CWexpose()\fP method. If the \f(CWexpose()\fP method is \f(CWNULL\fR, \f(CWXtRealizeWidget()\fR fills in a default bit gravity of \f(CWNorthWestGravity\fR before it calls the widget's \f(CWrealize()\fP method. .\" .SH "Example" The following procedure is the \f(CWexpose()\fP method of the Xaw Label widget with code for handling the left bitmap and multi-line string removed. Note that it first tests that the exposed region intersects the region that the label string or pixmap occupies. It also has commented-out code that sets the region as the clipmask of the GC. For such a simple redisplay, doing the clipping may have taken more time than simply drawing the text of pixmap. This method does not test the \f(CWvisible\fP field, and the widget class has its \f(CWvisible_interest\fP field set to \f(CWFalse\fP. Finally, note that if the widget is insensitive, it uses a special GC to draw itself "grayed-out." .Ps /* ARGSUSED */ static void Redisplay(w, event, region) Widget w; XEvent *event; Region region; { LabelWidget lw = (LabelWidget) w; GC gc; if (region != NULL) { int x = lw->label.label_x; unsigned int width = lw->label.label_width; if (lw->label.lbm_width) { if (lw->label.label_x > (x = lw->label.internal_width)) width += lw->label.label_x - x; } if (XRectInRegion(region, x, lw->label.label_y, width, lw->label.label_height) == RectangleOut) return; } gc = XtIsSensitive((Widget)lw) ? lw->label.normal_GC : lw->label.gray_GC; #ifdef notdef if (region != NULL) XSetRegion(XtDisplay(w), gc, region); #endif /*notdef*/ if (lw->label.pixmap == None) { int len = lw->label.label_len; char *label = lw->label.label; Position y = lw->label.label_y + lw->label.font->max_bounds.ascent; if (len) { if (lw->label.encoding) XDrawString16(XtDisplay(w), XtWindow(w), gc, lw->label.label_x, y, (TXT16*)label, len/2); else XDrawString(XtDisplay(w), XtWindow(w), gc, lw->label.label_x, y, label, len); } } else if (lw->label.label_len == 1) { /* depth */ XCopyPlane(XtDisplay(w), lw->label.pixmap, XtWindow(w), gc, 0, 0, lw->label.label_width, lw->label.label_height, lw->label.label_x, lw->label.label_y, 1L); } else { XCopyArea(XtDisplay(w), lw->label.pixmap, XtWindow(w), gc, 0, 0, lw->label.label_width, lw->label.label_height, lw->label.label_x, lw->label.label_y); } #ifdef notdef if (region != NULL) XSetClipMask(XtDisplay(w), gc, (Pixmap)None); #endif /* notdef */ } .Pe .\" .SH "Background" Many widgets prefer to process a series of exposure events as a single expose region rather than as individual rectangles. Widgets with complex displays might use the expose region as a clip list in a graphics context, and widgets with simple displays might ignore the region entirely and redisplay their whole window or might get the bounding box from the region and redisplay only that rectangle. .LP In either case, these widgets want some kind of exposure compression. The \f(CWcompress_exposure\fP field in the widget class structure specifies the type and number of exposure events that will be dispatched to the widget's expose procedure. This field must be set to \f(CWXtExposeNoCompress\fP, \f(CWXtExposeCompressSeries\fP, \f(CWXtExposeCompressMultiple\fP, or \f(CWXtExposeCompressMaximal\fP, optionally ORed with any combination of the \f(CWXtExposeGraphicsExpose\fP, \f(CWXtExposeGraphicsExposeMerged\fP, and \f(CWXtExposeNoExpose\fP flags. (Specifying \f(CWFalse\fP for the \f(CWcompress_exposure\fP field is equivalent to \f(CWXtExposeNoCompress\fP with no flags and specifying \f(CWTrue\fP is equivalent to \f(CWXtExposeCompressSeries\fP with no flags.) .LP If the \f(CIcompress_exposure\fP field in the widget class structure does not specify \f(CWXtExposeNoCompress\fP, the event manager calls the widget's expose procedure only once for a series of exposure events. In this case, all \f(CWExpose\fP or \f(CWGraphicsExpose\fP events are accumulated into a region. When the final event is received, the event manager replaces the rectangle in the event with the bounding box for the region and calls the widget's \f(CWexpose()\fP method, passing the modified exposure event and the region. .LP The different types of exposure compression are as follows: .IP "\f(CWXtExposeNoCompress\fP" 5n .XX "XtExposeNoCompress" No exposure compression is performed; every selected event is individually dispatched to the expose procedure with a \f(CIregion\fP argument of \f(CWNULL\fP. .Nd 4 .IP "\f(CWXtExposeCompressSeries\fP" 5n .XX "XtExposeCompressSeries" Each series of exposure events is coalesced into a single event, which is dispatched when an exposure event with count equal to zero is reached. .IP "\f(CWXtExposeCompressMultiple\fP" 5n .XX "XtExposeCompressMultiple" Consecutive series of exposure events are coalesced into a single event, which is dispatched when an exposure event with count equal to zero is reached and either the event queue is empty or the next event is not an exposure event for the same widget. .IP "\f(CWXtExposeCompressMaximal\fP" 5n .XX "XtExposeCompressMaximal" All expose series currently in the queue for the widget are coalesced into a single event without regard to intervening non-exposure events. If a partial series is in the end of the queue, the Intrinsics will block until the end of the series is received. .LP The optional flags have the following meanings: .IP "\f(CWXtExposeGraphicsExpose\fP" 5n .XX "XtExposeGraphicsExpose" Specifies that \f(CWGraphicsExpose\fP events are also to be dispatched to the expose procedure. \f(CWGraphicsExpose\fP events will be compressed, if specified, in the same manner as \f(CWExpose\fP events. .IP "\f(CWXtExposeGraphicsExposeMerged\fP" 5n .XX "XtExposeGraphicsExposeMerged" Specifies in the case of \f(CWXtExposeCompressMultiple\fP and \f(CWXtExposeCompressMaximal\fP that a series of \f(CWGraphicsExpose\fP and \f(CWExpose\fP events are to be compressed together, with the final event type determining the type of the event passed to the expose procedure. If this flag is not set, then only series of the same event type as the event at the head of the queue are coalesced. This flag also implies \f(CWXtExposeGraphicsExpose\fP. .IP "\f(CWXtExposeNoExpose\fP" .XX "XtExposeNoExpose" Specifies that \f(CWNoExpose\fP events are also to be dispatched to the expose procedure. \f(CWNoExpose\fP events are never coalesced with other exposure events or with each other. .LP Some widgets use substantial computing resources to display data. However, this effort is wasted if the widget is not actually visible on the screen (e.g., when the widget is obscured by another application or is iconified). The \f(CWvisible\fR field in the Core widget instance structure provides the widget with a hint that it need not display data. If any part of the widget is visible, the \f(CWvisible\fR field is guaranteed to be \f(CWTrue\fR by the time an \f(CWExpose\fR event is processed; if the widget is not visible, this field is usually \f(CWFalse\fR. .LP Widgets can either use or ignore the \f(CWvisible\fR hint. If they ignore it, the \f(CWvisible_interest\fR field in their widget class record should be set to \f(CWFalse\fR. In this case, the \f(CWvisible\fR field is initialized to \f(CWTrue\fR and never changes. If \f(CWvisible_interest\fR is \f(CWTrue\fP, however, the event manager asks for \f(CWVisibilityNotify\fR events for the widget and updates the \f(CWvisible\fR field accordingly. .\" .Nd 8 .SH "Structures" \f(CWRegion\fP is an opaque type defined by Xlib. .\" .SH "See Also" .na \s-1\fICore\fR\s+1\*(s3. .ad .XE "methods: expose; XtExposeProc" .XE "expose, method" .\"last line comment .\" $Header: fabs.3m,v 78.1 96/02/13 10:32:51 ssa Exp $ .TA f .TH fabs 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fabs(\|), fabsf(\|) \- absolute value functions .SH SYNOPSIS .C "#include " .PP .C "double fabs(double x);" .PP .C "float fabsf(float x);" .SH DESCRIPTION .CR fabs() returns the absolute value of .IR x , .RI | x |. .PP .CR fabsf() is a .CR float version of .CR fabs() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR fabsf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR fabs() returns +INFINITY. .PP If if .I x is NaN, .CR fabs() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR fabs() returns zero. .SH ERRORS No errors are defined. .SH SEE ALSO abs(3C), floor(3M), ceil(3M), fmod(3M), rint(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR fabs() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4fabs()\f1 \- absolute value functions@@@\f3fabs(3M)\f1 .\" index@\f4fabsf()\f1 \- absolute value functions@@@\f3fabs(3M)\f1 .\" index@\f1math: absolute value functions@@@\f3fabs(3M)\f1 .\" index@\f1absolute value functions@@@\f3fabs(3M)\f1 .\" .\" toc@\f3fabs(3M)\f1:\0\0\f4fabs()\f1, \f4fabsf()\f1@@@absolute value functions .\" toc@\f4fabsf()\f1:\0\0absolute value function (float version)@@@see \f3fabs(3M)\f1 .\" .\" links@fabs.3m fabsf.3m .\" .\" fileset_database@fabs.3m PROGRAMING-MAN .\" $Header: fabs.3m,v 78.1 96/02/13 10:32:51 ssa Exp $ .TA f .TH fabs 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fabs(\|), fabsf(\|) \- absolute value functions .SH SYNOPSIS .C "#include " .PP .C "double fabs(double x);" .PP .C "float fabsf(float x);" .SH DESCRIPTION .CR fabs() returns the absolute value of .IR x , .RI | x |. .PP .CR fabsf() is a .CR float version of .CR fabs() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR fabsf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR fabs() returns +INFINITY. .PP If if .I x is NaN, .CR fabs() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR fabs() returns zero. .SH ERRORS No errors are defined. .SH SEE ALSO abs(3C), floor(3M), ceil(3M), fmod(3M), rint(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR fabs() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4fabs()\f1 \- absolute value functions@@@\f3fabs(3M)\f1 .\" index@\f4fabsf()\f1 \- absolute value functions@@@\f3fabs(3M)\f1 .\" index@\f1math: absolute value functions@@@\f3fabs(3M)\f1 .\" index@\f1absolute value functions@@@\f3fabs(3M)\f1 .\" .\" toc@\f3fabs(3M)\f1:\0\0\f4fabs()\f1, \f4fabsf()\f1@@@absolute value functions .\" toc@\f4fabsf()\f1:\0\0absolute value function (float version)@@@see \f3fabs(3M)\f1 .\" .\" links@fabs.3m fabsf.3m .\" .\" fileset_database@fabs.3m PROGRAMING-MAN .\" $Header: fattach.3c,v 72.2 94/08/30 16:00:36 ssa Exp $ .TA f .TH fattach 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fattach(\|) \- attach a STREAMS file descriptor to an object in the file system name space .SH SYNOPSIS .C "#include " .br .sp .C "int fattach(int fd, const char *path);" .PP .SH DESCRIPTION The .C fattach() function attaches the .I fd file descriptor to an object in the file system name space designated by .I path. .I fd specifies an open file descriptor to a STREAMS device or STREAMS-based pipe. .I path specifies the pathname of an existing object in the file system. A STREAMS device or pipe can be attached to more than one node in the file system name space. In other words, a STREAMS device or pipe is allowed to have several associated names. Until the STREAMS device or pipe is detached from the node (with .CR fdetach(3c) or .CR fdetach(1m) ), all operations on .I path will act on the STREAMS device or pipe instead of the file system object .I path. .PP The fattached stream's attributes (see the .IR stat (2) reference page) are set according to the following scheme: .TP 3 \(bu The group ID, user ID, times, and permissions are set to those of .I path. .TP \(bu The size as well as the device number are set to those of the STREAMS device or pipe designated by the .I fd parameter. Note that although the attributes of the fattached STREAMS device or pipe may change (see the .IR chmod (2) reference page), the attributes of the underlying file system object .I path will not be changed. .TP \(bu The number of links is set to 1. .SH RETURN VALUE Upon successful completion, the .C fattach() function returns a value of 0 (zero). Otherwise, it returns a value of -1, and .C errno is set to indicate the error. .SH ERRORS If any of the following conditions occurs, the .C fattach() function sets .C errno to the value that corresponds to the condition. .PP .TP 20 [EACCES] Although the user is the owner of .I path, the user has no write permissions for it. .TP [EBADF] The .I fd parameter is an invalid file descriptor. .TP [EBUSY] The existing object specified by the .I path parameter is already mounted or has a file descriptor attached to it. .TP [EFAULT] The .I path parameter points to a location outside of the allocated address space of the process. .TP [EINVAL] The .I fd parameter does not refer to a STREAMS device or STREAMS-based pipe. .TP [ELOOP] When .I path was translated, too many symbolic links were found. .TP [ENOENT] .I path does not exist. .TP [ENOTDIR] The directory portion of the .I path parameter does not exist. .TP [ENAMETOOLONG] The size of a pathname component is longer than NAME_MAX when _POSIX_NO_TRUNC is in effect, or the pathname length is longer than PATH_MAX. .TP [EPERM] The current effective user ID is not the owner of the existing object specified by the .I path parameter. .SH SEE ALSO fdetach(3c), isastream(3c), chmod(2), stat(2), fdetach(1m), streamio(7). .SH STANDARDS COMPLIANCE .CR fattach() ": SVID3" .\" .\" index@\f4fattach\f1 \- attach a STREAMS file descriptor@@@\f3fattach(3c)\f1 .\" index@\f1attach a STREAMS file descriptor to an object in the file system name space@@@\f3fattach(3c)\f1 .\" index@\f1file descriptor: attach a STREAMS file descriptor@@@\f3fattach(3c)\f1 .\" index@\f1file system name space: attach a STREAMS file descriptor@@@\f3fattach(3c)\f1 .\" index@\f1name space: attach a STREAMS file descriptor@@@\f3fattach(3c)\f1 .\" index@\f1STREAMS file descriptor@@@\f3fattach(3c)\f1 .\" index@\f1STREAMS: attach a STREAMS file descriptor@@@\f3fattach(3c)\f1 .\" .\" toc@\f3fattach(3c)\f1:\0\0\f4fattach()\f1@@@attach a STREAMS file descriptor to an object in the file system name space .\" .\" fileset_database@fattach.3c STREAMS-MAN .\" $Header: fclose.3s,v 72.5 94/11/14 15:28:19 ssa Exp $ .TA f .TH fclose 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fclose(\|), fclose_unlocked(\|), fflush(\|), fflush_unlocked(\|) \- close or flush a stream .SH SYNOPSIS .C "#include " .PP .C "int fclose(FILE *stream);" .PP .C "int fclose_unlocked(FILE *stream);" .PP .C "int fflush(FILE *stream);" .PP .C "int fflush_unlocked(FILE *stream);" .SH DESCRIPTION .CR fclose() causes any buffered data for the named .I stream to be written out, and the .I stream to be closed. Buffers allocated by the standard input/output system may be freed. .PP .CR fclose() is performed automatically for all open files upon calling .IR exit (2). .PP If .I stream points to an output stream or an update stream in which the most recent operation was output, .CR fflush() causes any buffered data for the .I stream to be written to that file; otherwise any buffered data is discarded. The .I stream remains open. .PP If .I stream is a null pointer, .CR fflush() performs this flushing action on all currently open streams. .PP .CR fclose_unlocked() and .CR fflush_unlocked() are identical to .CR fclose() and .CR fflush() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .I stream (see .IR flockfile (3S)). .SH RETURN VALUE Upon successful completion, .CR fclose() and .CR fflush() return 0. Otherwise, they return EOF and set .CR errno to indicate the error. .SH ERRORS .CR fclose() , .CR fclose_unlocked() , .CR fflush() , and .CR fflush_unlocked() fail if: .RS .TP 15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not valid. .TP .SM [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP .SM [EINTR] .CR fclose() or .CR fflush() was interrupted by a signal. .TP .SM [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt was made to write to a pipe that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .PP Additional .CR errno values may be set by the underlying .CR write() , .CR lseek() , and .CR close() functions (see .IR write (2), .IR lseek (2) and .IR close (2)). .SH SEE ALSO close(2), exit(2), lseek(2), write(2), flockfile(3S), fopen(3S), setbuf(3S). .SH STANDARDS CONFORMANCE .CR fclose() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fflush() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fclose()\fP \- flush buffer then close stream@@@\f3fclose(3S)\f1 .\" index@\f4fflush()\fP \- flush buffer without closing stream@@@\f3fclose(3S)\f1 .\" index@flush buffer with or without closing stream@@@\f3fclose(3S)\f1 .\" index@buffer, flush with or without closing stream@@@\f3fclose(3S)\f1 .\" index@stream, flush buffer with or without closing@@@\f3fclose(3S)\f1 .\" index@close a stream@@@\f3fclose(3S)\f1 .\" index@stream, close a@@@\f3fclose(3S)\f1 .\" .\" toc@\f3fclose(3S)\f1:\0\0\f4fclose()\fP, \f4fflush()\fP@@@close or flush a stream .\" toc@\f4fflush()\fP:\0\0flush a stream@@@see \f3fclose(3S)\f1 .\" .\" links@fclose.3s fclose_unlo.3s .\" links@fclose.3s fflush.3s .\" links@fclose.3s fflush_unlo.3s .\" $Header: fclose.3s,v 72.5 94/11/14 15:28:19 ssa Exp $ .TA f .TH fclose 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fclose(\|), fclose_unlocked(\|), fflush(\|), fflush_unlocked(\|) \- close or flush a stream .SH SYNOPSIS .C "#include " .PP .C "int fclose(FILE *stream);" .PP .C "int fclose_unlocked(FILE *stream);" .PP .C "int fflush(FILE *stream);" .PP .C "int fflush_unlocked(FILE *stream);" .SH DESCRIPTION .CR fclose() causes any buffered data for the named .I stream to be written out, and the .I stream to be closed. Buffers allocated by the standard input/output system may be freed. .PP .CR fclose() is performed automatically for all open files upon calling .IR exit (2). .PP If .I stream points to an output stream or an update stream in which the most recent operation was output, .CR fflush() causes any buffered data for the .I stream to be written to that file; otherwise any buffered data is discarded. The .I stream remains open. .PP If .I stream is a null pointer, .CR fflush() performs this flushing action on all currently open streams. .PP .CR fclose_unlocked() and .CR fflush_unlocked() are identical to .CR fclose() and .CR fflush() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .I stream (see .IR flockfile (3S)). .SH RETURN VALUE Upon successful completion, .CR fclose() and .CR fflush() return 0. Otherwise, they return EOF and set .CR errno to indicate the error. .SH ERRORS .CR fclose() , .CR fclose_unlocked() , .CR fflush() , and .CR fflush_unlocked() fail if: .RS .TP 15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not valid. .TP .SM [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP .SM [EINTR] .CR fclose() or .CR fflush() was interrupted by a signal. .TP .SM [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt was made to write to a pipe that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .PP Additional .CR errno values may be set by the underlying .CR write() , .CR lseek() , and .CR close() functions (see .IR write (2), .IR lseek (2) and .IR close (2)). .SH SEE ALSO close(2), exit(2), lseek(2), write(2), flockfile(3S), fopen(3S), setbuf(3S). .SH STANDARDS CONFORMANCE .CR fclose() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fflush() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fclose()\fP \- flush buffer then close stream@@@\f3fclose(3S)\f1 .\" index@\f4fflush()\fP \- flush buffer without closing stream@@@\f3fclose(3S)\f1 .\" index@flush buffer with or without closing stream@@@\f3fclose(3S)\f1 .\" index@buffer, flush with or without closing stream@@@\f3fclose(3S)\f1 .\" index@stream, flush buffer with or without closing@@@\f3fclose(3S)\f1 .\" index@close a stream@@@\f3fclose(3S)\f1 .\" index@stream, close a@@@\f3fclose(3S)\f1 .\" .\" toc@\f3fclose(3S)\f1:\0\0\f4fclose()\fP, \f4fflush()\fP@@@close or flush a stream .\" toc@\f4fflush()\fP:\0\0flush a stream@@@see \f3fclose(3S)\f1 .\" .\" links@fclose.3s fclose_unlo.3s .\" links@fclose.3s fflush.3s .\" links@fclose.3s fflush_unlo.3s .\" $Header: cpacl.3c,v 72.3 93/01/14 14:45:24 ssa Exp $ .TA c .TH cpacl 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cpacl(\|), fcpacl(\|) \- copy the access control list (ACL) and mode bits from one file to another .SH SYNOPSIS .C "#include " .PP .C "int cpacl(" .PD 0 .nf .IP .C "const char *fromfile," .C "const char *tofile," .C "mode_t frommode," .C "uid_t fromuid," .C "gid_t fromgid," .C "uid_t touid," .C "gid_t togid" .PP .C ");" .PD .PP .PD 0 .C "int fcpacl(" .IP .C "int fromfd," .C "int tofd," .C "mode_t frommode," .C "uid_t fromuid," .C "gid_t fromgid," .C "uid_t touid," .C "gid_t togid" .PP .C ");" .PD .fi .SS Remarks: To ensure continued conformance with emerging industry standards, features described in this manual entry are likely to change in a future release. .SH DESCRIPTION Both .C cpacl() and .C fcpacl() copy the access control list and mode bits (that is, file access permission bits and miscellaneous mode bits; see .IR chmod (2)) from one file to another, and transfer ownership much like .IR chown (2). .C cpacl() and .C fcpacl() take the following parameters: .RS .TP 3 \(bu Path names .RI ( fromfile and .IR tofile ) or open file descriptors .RI ( fromfd and .IR tofd ). .TP \(bu A mode value .RI ( frommode , typically the .C st_mode value returned by .C stat() \(mi see .IR stat (2)) containing file miscellaneous mode bits which are always copied, and file access permission bits which are copied instead of the access control list if either file is remote. .TP \(bu User .SM ID and group .SM ID of the file .RI ( fromuid , .I touid and .IR fromgid , .IR togid ) for transferring ownership. (Typically .I fromuid and .IR fromgid are the .C st_uid and .C st_gid values returned by .CR stat() , and .IR touid and .IR togid are the return values from .C geteuid() and .C getegid() \(mi see .IR geteuid (2) and .IR getegid (2).) .RE .PP When both files are local, the .C cpacl() routines copy the access control list and call .C chownacl() (see .IR chownacl (3C)) to transfer ownership from the .I fromfile to the .IR tofile , if necessary. .PP .C cpacl() .RC ( fcpacl() ) handles remote copying (via .SM NFS) after recognizing failures of .C getacl() .RC ( fgetacl() ) or .C setacl() .RC ( fsetacl() ) (see .IR setacl (2)). When copying the mode from .I fromfile .RI ( fromfd ) to .I tofile .RI ( tofd ), .C cpacl() copies the entire .I frommode (that is, the file miscellaneous mode bits and the file access permission bits) to .I tofile .RI ( tofd ) using .CR chmod() .RC ( fchmod() ). Some of the miscellaneous mode bits can be turned off; see .IR chmod (2). .PP .C cpacl() .RC ( fcpacl ) can copy an access control list from .I fromfile .RI ( fromfd ) to .I tofile .RI ( tofd ) without transferring ownership, but ensuring error checking and handling of remote files. This is done by passing .I fromuid equal to .I touid and .I fromgid equal to .I togid (that is, four zeros). For remote files, .IR fromuid , .IR touid , .IR fromgid , and .I togid are ignored. .SH RETURN VALUE If successful, .C cpacl() and .C fcpacl() return zero. If an error occurs, they set .C errno to indicate the cause of failure and return a negative value, as follows: .TP \(mi-1 Unable to perform .C getacl() .RC ( fgetacl() ) on a local .I fromfile .RI ( fromfd ). .TP \(mi-2 Unable to perform .C chmod() .RC ( fchmod() ) on .I tofile .RI ( tofd ) to set its file miscellaneous mode bits. .C cpacl() .RC ( fcpacl() ) attempts this regardless of whether a file is local or remote, as long as .I fromfile .RI ( fromfd ) is local. .TP \(mi-3 Unable to perform .C setacl() .RC ( fsetacl() ) on a local .I tofile .RI ( tofd ). As a consequence, the file's optional .SM ACL entries are deleted, its file access permission bits are zeroed, and its miscellaneous mode bits might be altered. .TP \(mi-4 Unable to perform .C chmod() .RC ( fchmod() ) on .I tofile .RI ( tofd ) to set its mode. As a consequence, if .I fromfile .RI ( fromfd ) is local, .IR tofile 's .RI ( tofd 's) optional .SM ACL entries are deleted, its access permission bits are zeroed, and its file miscellaneous mode bits might be altered, regardless of whether the file is local or remote. .SH EXAMPLES The following code fragment gets .I stat information on .C oldfile and copies its file miscellaneous bits and access control list to .C newfile owned by the caller. If either file is remote, only the .C st_mode on .C oldfile is copied. .nf .IP .C #include .C #include .IP .C struct stat statbuf; .IP .C if (stat ("oldfile", & statbuf) < 0) .C error (...); .IP .C if (cpacl ("oldfile", "newfile", statbuf.st_mode, .C statbuf.st_uid, statbuf.st_gid, geteuid(), getegid()) < 0) .C { .C error (...); .C } .fi .SH AUTHOR .C cpacl() and .C fcpacl() were developed by .SM HP. .SH SEE ALSO chown(2), getacl(2), getegid(2), geteuid(2), setacl(2), stat(2). acltostr(3C), chownacl(3C), setentry(3C), strtoacl(3C), acl(5). .\" index@\f4fcpacl()\fP \- copy access control list (\s-1ACL\s+1) to another file@@@\f3cpacl(3C)\f1 .\" index@\f4cpacl()\fP \- copy access control list (\s-1ACL\s+1) to another file@@@\f3cpacl(3C)\f1 .\" index@copy access control list (\s-1ACL\s+1) to another file@@@\f3cpacl(3C)\f1 .\" index@access control list (\s-1ACL\s+1), copy to another file@@@\f3cpacl(3C)\f1 .\" index@file: copy access control list (\s-1ACL\s+1) to another file@@@\f3cpacl(3C)\f1 .\" toc@\f3cpacl(3C)\f1:\0\0\f4cpacl()\fP, \f4fcpacl()\fP@@@copy access control list (\s-1ACL\s+1) to another file .\" toc@\f4fcpacl()\fP: copy access control list (\s-1ACL\s+1) to another file@@@see \f3cpacl(3C)\f1 .\" links@cpacl.3c fcpacl.3c .\" .\" fileset_database@cpacl.3c PROGRAMING-MAN .\" $Header: ecvt.3c,v 72.6 94/11/30 15:42:51 ssa Exp $ .TA e .TH ecvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ecvt(\|), ecvt_r(\|), fcvt,(\|) fcvt_r(\|), gcvt(\|) \- convert floating-point number to string .SH SYNOPSIS .C "#include " .PP .C "char *ecvt(double value, int ndigit, int *decpt, int *sign);" .PP .C "int ecvt_r(" .nf .PD 0 .IP .C "double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PP .C "char *fcvt(double value, int ndigit, int *decpt, int *sign);" .PP .C "int fcvt_r(" .nf .PD 0 .IP .C "double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char *gcvt(double value, int ndigit, char *buf);" .SH DESCRIPTION .TP 12 .C ecvt() Converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero, otherwise it is zero. .IP One of three non-digit characters strings could be returned if the converted value is out of range. A .C -\|- or .C +\|+ is returned if the value is larger than the exponent can contain, and is negative, or positive, respectively. The third string is returned if the number is illegal, a zero divide for example. The result value is Not A Number .SM (NAN) and would return a .C ? character. .TP .C ecvt_r() Identical to .CR ecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C fcvt() Identical to .CR ecvt() , except that the correct digit has been rounded for printf .C %f (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C fcvt_r() Identical to .CR fcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C gcvt() Converts the .I value to a null-terminated string in the array pointed to by .I buf and returns .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character is included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C", is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the value of the radix character within the current .SM NLS environment. .SH WARNINGS The values returned by .C ecvt() and .C fcvt() point to a single static data array whose content is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .C ecvt_r() and .C fcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .C ecvt() and .C fcvt() were developed by AT&T. .C gcvt() was developed by AT&T and HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH STANDARDS CONFORMANCE .CR ecvt() ": XPG2" .PP .CR fcvt() ": XPG2" .PP .CR gcvt() ": XPG2" .\" .\" index@\f4ecvt()\fP, \f4fcvt()\fP \- convert floating-point number to string@@@\f3ecvt(3C)\f1 .\" index@\f4fcvt()\fP, \f4ecvt()\fP \- convert floating-point number to string@@@\f3ecvt(3C)\f1 .\" index@\f4gcvt()\f1 \- convert floating-point number to string array element@@@\f3ecvt(3C)\f1 .\" index@\f4gcvt()\fP \- convert floating-point number to string array element@@@\f3ecvt(3C)\f1 .\" index@convert floating-point number to string or string array element@@@\f3ecvt(3C)\f1 .\" index@floating-point: convert floating-point number to string or string array element@@@\f3ecvt(3C)\f1 .\" index@number to string or string array element, convert floating-point@@@\f3ecvt(3C)\f1 .\" index@string or string array element, convert floating-point number to@@@\f3ecvt(3C)\f1 .\" index@array element, convert floating-point number to string or string@@@\f3ecvt(3C)\f1 .\" index@element, convert floating-point number to string or string array@@@\f3ecvt(3C)\f1 .\" .\" toc@\f3ecvt(3C)\f1:\0\0\f4ecvt()\fP, \f4fcvt()\fP, \f4gcvt()\f1@@@convert floating-point number to string .\" toc@\f4fcvt()\fP:\0\0convert floating-point number to string@@@see \f3ecvt(3C)\f1 .\" toc@\f4gcvt()\fP:\0\0convert floating-point number to string@@@see \f3ecvt(3C)\f1 .\" .\" links@ecvt.3c ecvt_r.3c .\" links@ecvt.3c fcvt.3c .\" links@ecvt.3c fcvt_r.3c .\" links@ecvt.3c gcvt.3c .\" .\" fileset_database@ecvt.3c PROGRAMING-MAN .\" $Header: ecvt.3c,v 72.6 94/11/30 15:42:51 ssa Exp $ .TA e .TH ecvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ecvt(\|), ecvt_r(\|), fcvt,(\|) fcvt_r(\|), gcvt(\|) \- convert floating-point number to string .SH SYNOPSIS .C "#include " .PP .C "char *ecvt(double value, int ndigit, int *decpt, int *sign);" .PP .C "int ecvt_r(" .nf .PD 0 .IP .C "double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PP .C "char *fcvt(double value, int ndigit, int *decpt, int *sign);" .PP .C "int fcvt_r(" .nf .PD 0 .IP .C "double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char *gcvt(double value, int ndigit, char *buf);" .SH DESCRIPTION .TP 12 .C ecvt() Converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero, otherwise it is zero. .IP One of three non-digit characters strings could be returned if the converted value is out of range. A .C -\|- or .C +\|+ is returned if the value is larger than the exponent can contain, and is negative, or positive, respectively. The third string is returned if the number is illegal, a zero divide for example. The result value is Not A Number .SM (NAN) and would return a .C ? character. .TP .C ecvt_r() Identical to .CR ecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C fcvt() Identical to .CR ecvt() , except that the correct digit has been rounded for printf .C %f (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C fcvt_r() Identical to .CR fcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C gcvt() Converts the .I value to a null-terminated string in the array pointed to by .I buf and returns .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character is included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C", is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the value of the radix character within the current .SM NLS environment. .SH WARNINGS The values returned by .C ecvt() and .C fcvt() point to a single static data array whose content is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .C ecvt_r() and .C fcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .C ecvt() and .C fcvt() were developed by AT&T. .C gcvt() was developed by AT&T and HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH STANDARDS CONFORMANCE .CR ecvt() ": XPG2" .PP .CR fcvt() ": XPG2" .PP .CR gcvt() ": XPG2" .\" .\" index@\f4ecvt()\fP, \f4fcvt()\fP \- convert floating-point number to string@@@\f3ecvt(3C)\f1 .\" index@\f4fcvt()\fP, \f4ecvt()\fP \- convert floating-point number to string@@@\f3ecvt(3C)\f1 .\" index@\f4gcvt()\f1 \- convert floating-point number to string array element@@@\f3ecvt(3C)\f1 .\" index@\f4gcvt()\fP \- convert floating-point number to string array element@@@\f3ecvt(3C)\f1 .\" index@convert floating-point number to string or string array element@@@\f3ecvt(3C)\f1 .\" index@floating-point: convert floating-point number to string or string array element@@@\f3ecvt(3C)\f1 .\" index@number to string or string array element, convert floating-point@@@\f3ecvt(3C)\f1 .\" index@string or string array element, convert floating-point number to@@@\f3ecvt(3C)\f1 .\" index@array element, convert floating-point number to string or string@@@\f3ecvt(3C)\f1 .\" index@element, convert floating-point number to string or string array@@@\f3ecvt(3C)\f1 .\" .\" toc@\f3ecvt(3C)\f1:\0\0\f4ecvt()\fP, \f4fcvt()\fP, \f4gcvt()\f1@@@convert floating-point number to string .\" toc@\f4fcvt()\fP:\0\0convert floating-point number to string@@@see \f3ecvt(3C)\f1 .\" toc@\f4gcvt()\fP:\0\0convert floating-point number to string@@@see \f3ecvt(3C)\f1 .\" .\" links@ecvt.3c ecvt_r.3c .\" links@ecvt.3c fcvt.3c .\" links@ecvt.3c fcvt_r.3c .\" links@ecvt.3c gcvt.3c .\" .\" fileset_database@ecvt.3c PROGRAMING-MAN .\" $Header: fdetach.3c,v 72.2 94/08/30 16:06:27 ssa Exp $ .TA f .TH fdetach 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fdetach(\|) \- detach a name from a STREAMS file descriptor .SH SYNOPSIS .CR "#include " .br .sp .CR "int fdetach(const char *path);" .SH DESCRIPTION .PP The .CR fdetach() function detaches a file descriptor from a name in the file system designated by .I path. .I path specifies the pathname of an existing object in the file system name space that was previously attached (see the .CR fattach() reference page). As a result of the .CR fdetach() operation, the node's status and permissions return to the state prior to the file attaching to the node. Any later operations on .I path will affect only the file system node and not the attached file. The user must either be superuser or own .I path and have write permission. .SH RETURN VALUE Upon successful completion, the .CR fdetach() function returns a value of 0 (zero). Otherwise, it returns a value of -1 is returned, and .CR errno is set to indicate the error. .SH ERRORS If any of the following conditions occurs, the .CR fdetach() function sets .CR errno to the value that corresponds to the condition. .TP 20 [EFAULT] The .I path parameter points outside the process' allocated address space. .TP [EACCES] The user is not the owner of the file or does not have the correct permissions to access the file. .TP [EINVAL] The object pointed to by the .I path parameter is not fattached to a STREAMS device or pipe. .TP [ELOOP] When .I path was translated, too many symbolic links were found. .TP [ENOENT] The .I path parameter points to a pathname that does not exist. .TP [ENOTDIR] The directory portion of the .I path parameter does not exist. .TP [ENAMETOOLONG] The size of a pathname component is longer than [NAME_MAX] when [_POSIX_NO_TRUNC] is in effect, or the pathname length is longer than [PATH_MAX]. .TP [EPERM] The current effective user ID is not the owner of the existing object specified by the .I path parameter, or the current effective user ID does not specify a user with the correct permissions. .SH SEE ALSO fattach(3c), isastream(3c), umount(3), fdetach(1m), streamio(7). .SH STANDARDS COMPLIANCE .CR fdetach() ": SVID3" .\" .\" index@\f4fdetach\f1 \- detach a name from a STREAMS file descriptor@@@\f3fdetach(3c)\f1 .\" index@\f1detach a name from a STREAMS-based file descriptor@@@\f3fdetach(3c)\f1 .\" index@\f1file descriptor: detach a name from a STREAMS-based file descriptor@@@\f3fdetach(3c)\f1 .\" index@\f1name: detach a name from a STREAMS-based file descriptor@@@\f3fdetach(3c)\f1 .\" index@\f1STREAMS-based file descriptor@@@\f3fdetach(3c)\f1 .\" index@\f1STREAMS: detach a name from a STREAMS-based file descriptor@@@\f3fdetach(3c)\f1 .\" .\" toc@\f3fdetach(3c)\f1:\0\0\f4fdetach()\f1@@@detach a STREAMS-based file descriptor from a filename .\" .\" fileset_database@fdetach.3c STREAMS-MAN .\" $Header: fopen.3s,v 78.1 96/02/12 13:46:50 ssa Exp $ .TA f .TH fopen 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fopen(\|), freopen(\|), fdopen(\|) \- open or re-open a stream file; convert file to stream .SH SYNOPSIS .C "#include " .PP .C "FILE *fopen(const char *pathname, const char *type);" .PP .C "FILE *freopen(const char *pathname, const char *type, FILE *stream);" .PP .C "FILE *fdopen(int fildes, const char *type);" .SH DESCRIPTION .TP 15 .C fopen() Opens the file named by .I pathname and associates a .I stream with it. .C fopen() returns a pointer to the .C FILE structure associated with the .IR stream . .TP .C freopen() substitutes the named file in place of the open .IR stream . The original .I stream is closed, regardless of whether the open ultimately succeeds. .C freopen() returns a pointer to the .C FILE structure associated with .IR stream and makes an implicit call to .C clearerr() (see .IR ferror (3S)). .IP .C freopen() is typically used to attach the preopened .I streams associated with .CR stdin , .CR stdout , and .C stderr to other files. .TP .C fdopen() associates a stream with a file descriptor. File descriptors are obtained from .CR open() , .CR dup() , .CR creat() , or .C pipe() (see .IR open (2), .IR dup (2), .IR creat (2), and .IR pipe (2)), which open files but do not return pointers to a .C FILE structure stream. Streams are necessary input for many of the Section (3S) library routines. The .I type of stream must agree with the mode of the open file. The meanings of .I type used in the .C fdopen() call are exactly as specified above, except that .CR w , .CR w+ , .CR wb , and .C wb+ do not cause truncation of the file. .TP .I pathname Points to a character string containing the name of the file to be opened. .TP .I type Character string having one of the following values: .RS .RS .TP 15 .C r open for reading .TP .C w truncate to zero length or create for writing .TP .C a append; open for writing at end of file, or create for writing .TP .C rb open binary file for reading .TP .C wb truncate to zero length or create binary file for writing .TP .C ab append; open binary file for writing at end-of-file, or create binary file .TP .C r+ open for update (reading and writing) .TP .C w+ truncate to zero length or create for update .TP .C a+ append; open or create for update at end-of-file .TP .CI r+b \0or \0rb+ open binary file for update (reading and writing) .TP .CI w+b \0or \0wb+ truncate to zero length or create binary file for update .TP .CI a+b \0or \0ab+ append; open or create binary file for update at end-of-file .RE .RE .PP When a file is opened for update, both input and output can be done on the resulting .IR stream . However, output cannot be directly followed by input without an intervening call to .C fflush() or to a file positioning function .RC ( fseek() , .CR fsetpos() , or .CR rewind() ), and input cannot be directly followed by output without an intervening call to a file positioning function unless the input operation encounters end-of-file. .PP When a file is opened for append (i.e., when .I type is .C a or .CR a+ ), it is impossible to overwrite information already in the file. All output is written at the end of the file, regardless of intervening calls to .CR fseek() . If two separate processes open the same file for append, each process can write freely to the file without fear of destroying output being written by the other. Output from the two processes will be intermixed in the file in the order in which it is written. .SH RETURN VALUE Upon successful completion, .CR fopen() , .CR fdopen() , and .CR freopen() return a .C FILE * pointer to the stream. Otherwise, a null pointer is returned and .C errno is set to indicate the error. .SH ERRORS .CR fopen() , .CR fdopen() , and .CR freopen() fail if: .TP 15 .SM [EINVAL] The .I type argument is not a valid mode. .TP .SM [ENOMEM] There is insufficient space to allocate a buffer. .PP .C fopen() and .C freopen() fail if: .TP 15 .SM [EACCES] Search permission is denied on a component of the path prefix, or the file exists and the permissions specified by .I type are denied, or the file does not exist and write permission is denied for the parent directory of the file to be created. .TP .SM [EINTR] A signal was caught during .C fopen() or .CR freopen() . function. .TP .SM [EISDIR] The named file is a directory and .I type requires write access. .TP .SM [EMFILE] The calling process has attempted to exceed its open file limit. .TP .SM [ENAMETOOLONG] The length of the .I pathname string exceeds .C PATH_MAX or a pathname component is longer than .C NAME_MAX while .SM POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] The system file table is full. .TP .SM [ENOENT] The named file does not exist or the .I pathname argument points to an empty string. .TP .SM [ENOSPC] The directory or file system that would contain the new file cannot be expanded, the file does not exist, and it was to be created. .TP .SM [ENOTDIR] A component of the path prefix is not a directory. .TP .SM [ENXIO] The named file is a character special or block special file, and the device associated with the special file does not exist. .TP .SM [EOVERFLOW] The named file is a regular file and the size of the file cannot be represented correctly in an object of size .CR off_t in this environment. .TP .SM [EROFS] The named file resides on a read-only file system and .I type requires write access. .PP Additional .C errno values can be set by the underlying .CR open() call made from the .CR fopen() and .CR freopen() functions (see .IR open(2)). .SH NOTES .SM HP-UX binary file .I types are equivalent to their non-binary counterparts. For example, types .C r and .C rb are equivalent. .SH SEE ALSO creat(2), dup(2), open(2), pipe(2), fclose(3S), fopen64(3S), freopen64(3S), fseek(3S), popen(3S), setvbuf(3S). .SH STANDARDS CONFORMANCE .CR fopen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fdopen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR freopen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fopen()\f1 \- open a named file and associate with a stream@@@\f3fopen(3S)\f1 .\" index@\f4freopen()\f1 \- substitute a named file in place of an already open stream@@@\f3fopen(3S)\f1 .\" index@\f4fdopen()\f1 \- associate a stream with an open file descriptor@@@\f3fopen(3S)\f1 .\" index@\f1file, stream: open or re-open a stream file; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1file, stream: convert file to stream; open or re-open a stream file@@@\f3fopen(3S)\f1 .\" index@\f1open or re-open a stream file; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1re-open or open a stream file; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1stream file, open or re-open; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1stream file, open or re-open; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1convert file to stream@@@\f3fopen(3S)\f1 .\" .\" toc@\f3fopen(3S)\f1:\0\0\f4fopen()\f1, \f4freopen()\f1, \f4fdopen()\f1@@@open or re-open a stream file; convert file to stream .\" toc@\f4freopen()\f1:\0\0re-open a stream file; convert file to stream@@@see \f3fopen(3S)\f1 .\" toc@\f4fdopen()\f1:\0\0associate a stream with a file descriptor@@@see \f3fopen(3S)\f1 .\" .\" links@fopen.3s freopen.3s .\" links@fopen.3s fdopen.3s .\" .\" $Header: ferror.3s,v 72.5 94/11/14 15:28:20 ssa Exp $ .TA f .TH ferror 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ferror(\|), ferror_unlocked(\|), feof(\|), feof_unlocked(\|), clearerr(\|), clearerr_unlocked(\|) \- stream status inquiries .SH SYNOPSIS .C "#include " .PP .C "int ferror(FILE *stream);" .PP .C "int ferror_unlocked(FILE *stream);" .PP .C "int feof(FILE *stream);" .PP .C "int feof_unlocked(FILE *stream);" .PP .C "void clearerr(FILE *stream);" .PP .C "void clearerr_unlocked(FILE *stream);" .SH DESCRIPTION .TP 15 .CR ferror() Returns non-zero when an .SM I/O error has previously occurred reading from or writing to the named .IR stream , otherwise zero. Unless cleared by .CR clearerr() , or unless the specific .I stdio routine so indicates, the error indication lasts until the stream is closed. .TP .CR feof() Returns non-zero when .SM EOF has previously been detected reading the named input .IR stream , otherwise zero. .TP .CR clearerr() Resets the error indicator and .SM EOF indicator on the named .I stream to zero. .PP .CR ferror_unlocked() , " feof_unlocked()" , and .CR clearerr_unlocked() are identical to .CR ferror() , " feof()" , and .CR clearerr() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH WARNINGS All these routines are implemented both as library functions and as macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function, either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI-C mode, enclose the function name in parentheses or use the function address. The following example illustrates each of these methods : .nf .IP .CR "#include " .CR "#undef ferror" .CR " ..." .CR "main()" .CR "{" .CR " int (*find_error()) ();" .CR " ..." .CR " return_val=ferror(fd);" .CR " ..." .CR " return_val=(feof)(fd1);" .CR " ..." .CR " find_error = feof;" .CR }; .fi .SS Reentrant Interfaces If .CR _REENTRANT is defined before including .RC < stdio.h >, the locked versions of the library functions for .CR ferror() , " feof()" , and .CR clearerr() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR ferror() , " feof()" , and .CR clearerr() . .br .ne 12v .SH SEE ALSO open(2), flockfile(3S), fopen(3S). .SH STANDARDS CONFORMANCE .CR ferror() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR clearerr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR feof() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f2ferror\f1 \- check for \s-1I/O\s+1 error on stream@@@\f3ferror(3S)\f1 .\" index@\f2feof\f1 \- check for end-of-file error on stream@@@\f3ferror(3S)\f1 .\" index@\f2clearerr\f1 \- clear \s-1I/O\s+1 error on stream@@@\f3ferror(3S)\f1 .\" index@stream status inquiries@@@\f3ferror(3S)\f1 .\" index@status inquiries, stream@@@\f3ferror(3S)\f1 .\" .\" toc@\f3ferror(3S)\f1:\0\0\f2ferror\f1, \f2feof\f1, \f2clearerr\f1@@@stream status inquiries .\" toc@\f2feof\f1:\0\0stream status inquiries@@@see \f3ferror(3S)\f1 .\" toc@\f2clearerr\f1:\0\0stream status inquiries@@@see \f3ferror(3S)\f1 .\" .\" links@ferror.3s ferror_unlo.3s .\" links@ferror.3s feof.3s .\" links@ferror.3s feof_unlock.3s .\" links@ferror.3s clearerr.3s .\" links@ferror.3s clearerr_un.3s .\" $Header: ferror.3s,v 72.5 94/11/14 15:28:20 ssa Exp $ .TA f .TH ferror 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ferror(\|), ferror_unlocked(\|), feof(\|), feof_unlocked(\|), clearerr(\|), clearerr_unlocked(\|) \- stream status inquiries .SH SYNOPSIS .C "#include " .PP .C "int ferror(FILE *stream);" .PP .C "int ferror_unlocked(FILE *stream);" .PP .C "int feof(FILE *stream);" .PP .C "int feof_unlocked(FILE *stream);" .PP .C "void clearerr(FILE *stream);" .PP .C "void clearerr_unlocked(FILE *stream);" .SH DESCRIPTION .TP 15 .CR ferror() Returns non-zero when an .SM I/O error has previously occurred reading from or writing to the named .IR stream , otherwise zero. Unless cleared by .CR clearerr() , or unless the specific .I stdio routine so indicates, the error indication lasts until the stream is closed. .TP .CR feof() Returns non-zero when .SM EOF has previously been detected reading the named input .IR stream , otherwise zero. .TP .CR clearerr() Resets the error indicator and .SM EOF indicator on the named .I stream to zero. .PP .CR ferror_unlocked() , " feof_unlocked()" , and .CR clearerr_unlocked() are identical to .CR ferror() , " feof()" , and .CR clearerr() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH WARNINGS All these routines are implemented both as library functions and as macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function, either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI-C mode, enclose the function name in parentheses or use the function address. The following example illustrates each of these methods : .nf .IP .CR "#include " .CR "#undef ferror" .CR " ..." .CR "main()" .CR "{" .CR " int (*find_error()) ();" .CR " ..." .CR " return_val=ferror(fd);" .CR " ..." .CR " return_val=(feof)(fd1);" .CR " ..." .CR " find_error = feof;" .CR }; .fi .SS Reentrant Interfaces If .CR _REENTRANT is defined before including .RC < stdio.h >, the locked versions of the library functions for .CR ferror() , " feof()" , and .CR clearerr() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR ferror() , " feof()" , and .CR clearerr() . .br .ne 12v .SH SEE ALSO open(2), flockfile(3S), fopen(3S). .SH STANDARDS CONFORMANCE .CR ferror() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR clearerr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR feof() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f2ferror\f1 \- check for \s-1I/O\s+1 error on stream@@@\f3ferror(3S)\f1 .\" index@\f2feof\f1 \- check for end-of-file error on stream@@@\f3ferror(3S)\f1 .\" index@\f2clearerr\f1 \- clear \s-1I/O\s+1 error on stream@@@\f3ferror(3S)\f1 .\" index@stream status inquiries@@@\f3ferror(3S)\f1 .\" index@status inquiries, stream@@@\f3ferror(3S)\f1 .\" .\" toc@\f3ferror(3S)\f1:\0\0\f2ferror\f1, \f2feof\f1, \f2clearerr\f1@@@stream status inquiries .\" toc@\f2feof\f1:\0\0stream status inquiries@@@see \f3ferror(3S)\f1 .\" toc@\f2clearerr\f1:\0\0stream status inquiries@@@see \f3ferror(3S)\f1 .\" .\" links@ferror.3s ferror_unlo.3s .\" links@ferror.3s feof.3s .\" links@ferror.3s feof_unlock.3s .\" links@ferror.3s clearerr.3s .\" links@ferror.3s clearerr_un.3s .\" $Header: ferror.3s,v 72.5 94/11/14 15:28:20 ssa Exp $ .TA f .TH ferror 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ferror(\|), ferror_unlocked(\|), feof(\|), feof_unlocked(\|), clearerr(\|), clearerr_unlocked(\|) \- stream status inquiries .SH SYNOPSIS .C "#include " .PP .C "int ferror(FILE *stream);" .PP .C "int ferror_unlocked(FILE *stream);" .PP .C "int feof(FILE *stream);" .PP .C "int feof_unlocked(FILE *stream);" .PP .C "void clearerr(FILE *stream);" .PP .C "void clearerr_unlocked(FILE *stream);" .SH DESCRIPTION .TP 15 .CR ferror() Returns non-zero when an .SM I/O error has previously occurred reading from or writing to the named .IR stream , otherwise zero. Unless cleared by .CR clearerr() , or unless the specific .I stdio routine so indicates, the error indication lasts until the stream is closed. .TP .CR feof() Returns non-zero when .SM EOF has previously been detected reading the named input .IR stream , otherwise zero. .TP .CR clearerr() Resets the error indicator and .SM EOF indicator on the named .I stream to zero. .PP .CR ferror_unlocked() , " feof_unlocked()" , and .CR clearerr_unlocked() are identical to .CR ferror() , " feof()" , and .CR clearerr() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH WARNINGS All these routines are implemented both as library functions and as macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function, either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI-C mode, enclose the function name in parentheses or use the function address. The following example illustrates each of these methods : .nf .IP .CR "#include " .CR "#undef ferror" .CR " ..." .CR "main()" .CR "{" .CR " int (*find_error()) ();" .CR " ..." .CR " return_val=ferror(fd);" .CR " ..." .CR " return_val=(feof)(fd1);" .CR " ..." .CR " find_error = feof;" .CR }; .fi .SS Reentrant Interfaces If .CR _REENTRANT is defined before including .RC < stdio.h >, the locked versions of the library functions for .CR ferror() , " feof()" , and .CR clearerr() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR ferror() , " feof()" , and .CR clearerr() . .br .ne 12v .SH SEE ALSO open(2), flockfile(3S), fopen(3S). .SH STANDARDS CONFORMANCE .CR ferror() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR clearerr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR feof() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f2ferror\f1 \- check for \s-1I/O\s+1 error on stream@@@\f3ferror(3S)\f1 .\" index@\f2feof\f1 \- check for end-of-file error on stream@@@\f3ferror(3S)\f1 .\" index@\f2clearerr\f1 \- clear \s-1I/O\s+1 error on stream@@@\f3ferror(3S)\f1 .\" index@stream status inquiries@@@\f3ferror(3S)\f1 .\" index@status inquiries, stream@@@\f3ferror(3S)\f1 .\" .\" toc@\f3ferror(3S)\f1:\0\0\f2ferror\f1, \f2feof\f1, \f2clearerr\f1@@@stream status inquiries .\" toc@\f2feof\f1:\0\0stream status inquiries@@@see \f3ferror(3S)\f1 .\" toc@\f2clearerr\f1:\0\0stream status inquiries@@@see \f3ferror(3S)\f1 .\" .\" links@ferror.3s ferror_unlo.3s .\" links@ferror.3s feof.3s .\" links@ferror.3s feof_unlock.3s .\" links@ferror.3s clearerr.3s .\" links@ferror.3s clearerr_un.3s .\" $Header: ferror.3s,v 72.5 94/11/14 15:28:20 ssa Exp $ .TA f .TH ferror 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ferror(\|), ferror_unlocked(\|), feof(\|), feof_unlocked(\|), clearerr(\|), clearerr_unlocked(\|) \- stream status inquiries .SH SYNOPSIS .C "#include " .PP .C "int ferror(FILE *stream);" .PP .C "int ferror_unlocked(FILE *stream);" .PP .C "int feof(FILE *stream);" .PP .C "int feof_unlocked(FILE *stream);" .PP .C "void clearerr(FILE *stream);" .PP .C "void clearerr_unlocked(FILE *stream);" .SH DESCRIPTION .TP 15 .CR ferror() Returns non-zero when an .SM I/O error has previously occurred reading from or writing to the named .IR stream , otherwise zero. Unless cleared by .CR clearerr() , or unless the specific .I stdio routine so indicates, the error indication lasts until the stream is closed. .TP .CR feof() Returns non-zero when .SM EOF has previously been detected reading the named input .IR stream , otherwise zero. .TP .CR clearerr() Resets the error indicator and .SM EOF indicator on the named .I stream to zero. .PP .CR ferror_unlocked() , " feof_unlocked()" , and .CR clearerr_unlocked() are identical to .CR ferror() , " feof()" , and .CR clearerr() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH WARNINGS All these routines are implemented both as library functions and as macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function, either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI-C mode, enclose the function name in parentheses or use the function address. The following example illustrates each of these methods : .nf .IP .CR "#include " .CR "#undef ferror" .CR " ..." .CR "main()" .CR "{" .CR " int (*find_error()) ();" .CR " ..." .CR " return_val=ferror(fd);" .CR " ..." .CR " return_val=(feof)(fd1);" .CR " ..." .CR " find_error = feof;" .CR }; .fi .SS Reentrant Interfaces If .CR _REENTRANT is defined before including .RC < stdio.h >, the locked versions of the library functions for .CR ferror() , " feof()" , and .CR clearerr() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR ferror() , " feof()" , and .CR clearerr() . .br .ne 12v .SH SEE ALSO open(2), flockfile(3S), fopen(3S). .SH STANDARDS CONFORMANCE .CR ferror() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR clearerr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR feof() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f2ferror\f1 \- check for \s-1I/O\s+1 error on stream@@@\f3ferror(3S)\f1 .\" index@\f2feof\f1 \- check for end-of-file error on stream@@@\f3ferror(3S)\f1 .\" index@\f2clearerr\f1 \- clear \s-1I/O\s+1 error on stream@@@\f3ferror(3S)\f1 .\" index@stream status inquiries@@@\f3ferror(3S)\f1 .\" index@status inquiries, stream@@@\f3ferror(3S)\f1 .\" .\" toc@\f3ferror(3S)\f1:\0\0\f2ferror\f1, \f2feof\f1, \f2clearerr\f1@@@stream status inquiries .\" toc@\f2feof\f1:\0\0stream status inquiries@@@see \f3ferror(3S)\f1 .\" toc@\f2clearerr\f1:\0\0stream status inquiries@@@see \f3ferror(3S)\f1 .\" .\" links@ferror.3s ferror_unlo.3s .\" links@ferror.3s feof.3s .\" links@ferror.3s feof_unlock.3s .\" links@ferror.3s clearerr.3s .\" links@ferror.3s clearerr_un.3s .\" $Header: dbm.3x,v 76.1 95/07/05 17:27:37 ssa Exp $ .TA d .TH dbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbminit, fetch, store, delete, firstkey, nextkey, dbmclose \- database subroutines .SH SYNOPSIS .C "#include " .P .C "int dbminit(const char *file);" .P .C "datum fetch(datum key);" .P .C "int store(datum key, datum content);" .P .C "int delete(datum key);" .P .C "datum firstkey(void);" .P .C "datum nextkey(datum key);" .P .C "int dbmclose(void);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can locate a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .I dptr. Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbminit . At the time of this call, the files .IC file .dir and .IC file .pag must exist. (An empty database is created by creating zero-length .C .dir and .C .pag files.) .PP Once open, data stored under a key is accessed by .IC fetch , and data is placed under a key by .IC store . Storing data on an existing key replaces the existing data. A key (and its associated contents) is deleted by .CR delete . A linear pass through all keys in a database can be made, in (apparently) random order by using .C firstkey and .CR nextkey . .C firstkey returns the first key in the database. With any key, .C nextkey returns the next key in the database. The following code can be used to traverse the database: .IP .C "for (key = firstkey(); key.dptr != NULL; key = nextkey(key))" .PP A database can be closed by calling .C dbmclose. A currently open database must be closed before opening a new one. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .IR dptr . .SH WARNINGS The .I dbm functions provided in this library should not be confused in any way with those of a general-purpose database management system such as .SM ALLBASE/HP-UX SQL. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful data base functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C store returns an error if a disk block fills with inseparable data. .PP .C delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C firstkey and .C nextkey depends on a hashing function, not on anything interesting. .PP A .C store or .C delete during a pass through the keys by .C firstkey and .C nextkey may yield unexpected results. .SH AUTHOR .IR dbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO ndbm(3X). .\" index@\f4dbminit()\fP \- open a single database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4fetch()\fP \- access data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4store()\fP \- store data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4delete()\fP \- delete key and data under it (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4firstkey()\fP \- get first key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4nextkey()\fP \- get next key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4dbmclose()\fP \- close currently open database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@database subroutines (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" index@subroutines, database (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" .\" toc@\f3dbm(3X)\f1:\0\0\f4dbminit()\fP, \f4fetch()\fP, \f4store()\fP, \f4delete()\fP, \f4firstkey()\fP,\n\f4nextkey()\fP, \f4dbmclose()\fP@@@database subroutines .\" toc@\f4dbminit()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4fetch()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4store()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4delete()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4firstkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4nextkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4dbmclose()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" .\" links@dbm.3x dbminit.3x .\" links@dbm.3x fetch.3x .\" links@dbm.3x store.3x .\" links@dbm.3x delete.3x .\" links@dbm.3x firstkey.3x .\" links@dbm.3x nextkey.3x .\" links@dbm.3x dbmclose.3x .\" .\" fileset_database@dbm.3x PROGRAMING-MAN .\" $Header: fclose.3s,v 72.5 94/11/14 15:28:19 ssa Exp $ .TA f .TH fclose 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fclose(\|), fclose_unlocked(\|), fflush(\|), fflush_unlocked(\|) \- close or flush a stream .SH SYNOPSIS .C "#include " .PP .C "int fclose(FILE *stream);" .PP .C "int fclose_unlocked(FILE *stream);" .PP .C "int fflush(FILE *stream);" .PP .C "int fflush_unlocked(FILE *stream);" .SH DESCRIPTION .CR fclose() causes any buffered data for the named .I stream to be written out, and the .I stream to be closed. Buffers allocated by the standard input/output system may be freed. .PP .CR fclose() is performed automatically for all open files upon calling .IR exit (2). .PP If .I stream points to an output stream or an update stream in which the most recent operation was output, .CR fflush() causes any buffered data for the .I stream to be written to that file; otherwise any buffered data is discarded. The .I stream remains open. .PP If .I stream is a null pointer, .CR fflush() performs this flushing action on all currently open streams. .PP .CR fclose_unlocked() and .CR fflush_unlocked() are identical to .CR fclose() and .CR fflush() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .I stream (see .IR flockfile (3S)). .SH RETURN VALUE Upon successful completion, .CR fclose() and .CR fflush() return 0. Otherwise, they return EOF and set .CR errno to indicate the error. .SH ERRORS .CR fclose() , .CR fclose_unlocked() , .CR fflush() , and .CR fflush_unlocked() fail if: .RS .TP 15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not valid. .TP .SM [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP .SM [EINTR] .CR fclose() or .CR fflush() was interrupted by a signal. .TP .SM [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt was made to write to a pipe that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .PP Additional .CR errno values may be set by the underlying .CR write() , .CR lseek() , and .CR close() functions (see .IR write (2), .IR lseek (2) and .IR close (2)). .SH SEE ALSO close(2), exit(2), lseek(2), write(2), flockfile(3S), fopen(3S), setbuf(3S). .SH STANDARDS CONFORMANCE .CR fclose() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fflush() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fclose()\fP \- flush buffer then close stream@@@\f3fclose(3S)\f1 .\" index@\f4fflush()\fP \- flush buffer without closing stream@@@\f3fclose(3S)\f1 .\" index@flush buffer with or without closing stream@@@\f3fclose(3S)\f1 .\" index@buffer, flush with or without closing stream@@@\f3fclose(3S)\f1 .\" index@stream, flush buffer with or without closing@@@\f3fclose(3S)\f1 .\" index@close a stream@@@\f3fclose(3S)\f1 .\" index@stream, close a@@@\f3fclose(3S)\f1 .\" .\" toc@\f3fclose(3S)\f1:\0\0\f4fclose()\fP, \f4fflush()\fP@@@close or flush a stream .\" toc@\f4fflush()\fP:\0\0flush a stream@@@see \f3fclose(3S)\f1 .\" .\" links@fclose.3s fclose_unlo.3s .\" links@fclose.3s fflush.3s .\" links@fclose.3s fflush_unlo.3s .\" $Header: fclose.3s,v 72.5 94/11/14 15:28:19 ssa Exp $ .TA f .TH fclose 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fclose(\|), fclose_unlocked(\|), fflush(\|), fflush_unlocked(\|) \- close or flush a stream .SH SYNOPSIS .C "#include " .PP .C "int fclose(FILE *stream);" .PP .C "int fclose_unlocked(FILE *stream);" .PP .C "int fflush(FILE *stream);" .PP .C "int fflush_unlocked(FILE *stream);" .SH DESCRIPTION .CR fclose() causes any buffered data for the named .I stream to be written out, and the .I stream to be closed. Buffers allocated by the standard input/output system may be freed. .PP .CR fclose() is performed automatically for all open files upon calling .IR exit (2). .PP If .I stream points to an output stream or an update stream in which the most recent operation was output, .CR fflush() causes any buffered data for the .I stream to be written to that file; otherwise any buffered data is discarded. The .I stream remains open. .PP If .I stream is a null pointer, .CR fflush() performs this flushing action on all currently open streams. .PP .CR fclose_unlocked() and .CR fflush_unlocked() are identical to .CR fclose() and .CR fflush() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .I stream (see .IR flockfile (3S)). .SH RETURN VALUE Upon successful completion, .CR fclose() and .CR fflush() return 0. Otherwise, they return EOF and set .CR errno to indicate the error. .SH ERRORS .CR fclose() , .CR fclose_unlocked() , .CR fflush() , and .CR fflush_unlocked() fail if: .RS .TP 15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not valid. .TP .SM [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP .SM [EINTR] .CR fclose() or .CR fflush() was interrupted by a signal. .TP .SM [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt was made to write to a pipe that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .PP Additional .CR errno values may be set by the underlying .CR write() , .CR lseek() , and .CR close() functions (see .IR write (2), .IR lseek (2) and .IR close (2)). .SH SEE ALSO close(2), exit(2), lseek(2), write(2), flockfile(3S), fopen(3S), setbuf(3S). .SH STANDARDS CONFORMANCE .CR fclose() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fflush() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fclose()\fP \- flush buffer then close stream@@@\f3fclose(3S)\f1 .\" index@\f4fflush()\fP \- flush buffer without closing stream@@@\f3fclose(3S)\f1 .\" index@flush buffer with or without closing stream@@@\f3fclose(3S)\f1 .\" index@buffer, flush with or without closing stream@@@\f3fclose(3S)\f1 .\" index@stream, flush buffer with or without closing@@@\f3fclose(3S)\f1 .\" index@close a stream@@@\f3fclose(3S)\f1 .\" index@stream, close a@@@\f3fclose(3S)\f1 .\" .\" toc@\f3fclose(3S)\f1:\0\0\f4fclose()\fP, \f4fflush()\fP@@@close or flush a stream .\" toc@\f4fflush()\fP:\0\0flush a stream@@@see \f3fclose(3S)\f1 .\" .\" links@fclose.3s fclose_unlo.3s .\" links@fclose.3s fflush.3s .\" links@fclose.3s fflush_unlo.3s .\" $Header: memory.3c,v 74.1 95/03/23 17:24:13 ssa Exp $ .TA m .TH memory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME memccpy(\|), memchr(\|), memcmp(\|), memcpy(\|), memmove(\|), memset(\|), bcopy(\|), bcmp(\|), bzero(\|), ffs(\|) \- memory operations .SH SYNOPSIS .C "#include " .PP .C "void *memccpy(void *s1, const void *s2, int c, size_t n);" .PP .C "void *memchr(const void *s, int c, size_t n);" .PP .C "int memcmp(const void *s1, const void *s2, size_t n);" .PP .C "void *memcpy(void *s1, const void *s2, size_t n);" .PP .C "void *memmove(void *s1, const void *s2, size_t n);" .PP .C "void *memset(void *s, int c, size_t n);" .PP .C "#include " .PP .C "int bcmp(const void *s1, const void *s2, size_t n);" .PP .C "void bcopy(const void *s1, void *s2, size_t n);" .PP .C "void bzero(char *s, int n);" .PP .C "int ffs(int i);" .SS Remarks: .CR bcmp() , .CR bcopy() , .CR bzero() , .CR ffs() , and .RC < strings.h > are provided solely for portability of .SM BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .CR memcmp() , .CR memmove() , and .CR memset() , respectively. .C ffs() has no portable equivalent. .SH DESCRIPTION These functions operate as efficiently as possible on memory areas (arrays of bytes bounded by a count, not terminated by a null byte). They do not check for the overflow of any receiving memory area. .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RC < string.h > header file. .TP 15 .C memccpy() Copy bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 , stopping after the first occurrence of byte .I c has been copied, or after .I n bytes have been copied, whichever comes first. If copying takes place between objects that overlap, the behavior is undefined. .C memccpy() returns a pointer to the bvyte after the copy of .I c in .IR s1 , or a .SM NULL pointer if .I c was not found in the first .I n bytes of .IR s2 . .TP .C memchr() Locate the first occurrence of .I c (converted to an .CR "unsigned char" ) in the initial .I n bytes (each interpreted as .CR "unsigned char" ) of the object pointed to by .IR s . .C memchr() returns a pointer to the located byte, or a .SM NULL pointer if the byte does not occur in the object. .TP .C memcmp() Compare the first .I n bytes of the object pointed to by .I s1 to the first .I n bytes of the object pointed to by .IR s2 . .C memcmp() returns an integer greater than, equal to, or less than zero, according to whether the object pointed to by .I s1 is greater than, equal to, or less than the object pointed to by .IR s2 . The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes (both interpreted as .CR "unsigned char" ) that differ in the objects being compared. .TP .C memcpy() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . If copying takes place between objects that overlap, the behavior is undefined. .C memcpy() returns the value of .IR s1 . .TP .C memmove() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . Copying takes place as if the .I n bytes from the object pointed to by .I s2 are first copied into a temporary array of .I n bytes that does not overlap the objects pointed to by .I s1 and .IR s2 , and then the .I n bytes from the temporary array are copied into the object pointed to by .IR s1 . .C memmove() returns the value of .IR s1 . .TP .C memset() Copy the value of .I c (converted to an .CR "unsigned char" ) into each of the first .I n bytes of the object pointed to by .IR s . .C memset() returns the value of .IR s . .TP .C bcopy() copies .I n bytes from the area pointed to by .I s1 to the area pointed to by .IR s2 . .TP .C bcmp() Compare the first .I n bytes of the area pointed to by .I s1 with the area pointed to by .IR s2 . .C bcmp() returns zero if they are identical; non-zero otherwise. Both areas are assumed to be .I n bytes in length. .TP .C bzero() Clear .I n bytes in the area pointed to by .I s by setting them to zero. .TP .C ffs() Find the first bit set (beginning with the least significant bit) and return the index of that bit. Bits are numbered starting at one. A return value of 0 indicates that .I i is zero. .SS International Code Set Support These functions support only single-byte byte code sets. .SH WARNINGS The functions defined in .RC < string.h > were previously defined in .RC < memory.h >. .SH FILES .C /usr/include/string.h .SH SEE ALSO string(3C) .SH STANDARDS CONFORMANCE .CR memccpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR memchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memmove() ": AES, SVID3, XPG4, ANSI C" .PP .CR memset() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4memcpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memccpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memchr()\f1 \- find first occurrence of byte in memory area@@@\f3memory(3C)\f1 .\" index@\f4memcmp()\f1 \- compare byte with memory contents@@@\f3memory(3C)\f1 .\" index@\f4memmove()\f1 \- move memory contents@@@\f3memory(3C)\f1 .\" index@\f4memset()\f1 \- set area in memory to contain a specified byte@@@\f3memory(3C)\f1 .\" index@\f4bcopy()\f1 \- \s-1BSD\s+1 memory copy@@@\f3memory(3C)\f1 .\" index@\f4bcmp()\f1 \- \s-1BSD\s+1 memory compare@@@\f3memory(3C)\f1 .\" index@\f4bzero()\f1 \- \s-1BSD\s+1 memory clear@@@\f3memory(3C)\f1 .\" index@\f4ffs()\f1 \- \s-1BSD\s+1 find first set bit@@@\f3memory(3C)\f1 .\" index@\f1memory operations \- copy, compare, test for contents, or set contents to value@@@\f3memory(3C)\f1 .\" index@\f1copy memory to another area@@@\f3memory(3C)\f1 .\" index@\f1test contents of memory area@@@\f3memory(3C)\f1 .\" index@\f1compare contents of memory with byte@@@\f3memory(3C)\f1 .\" index@\f1preset contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1set contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1byte, set contents of memory area to specified@@@\f3memory(3C)\f1 .\" index@\f1byte, compare memory contents with specified@@@\f3memory(3C)\f1 .\" index@\f1byte, find location of in memory@@@\f3memory(3C)\f1 .\" index@\f1location of byte in memory, find@@@\f3memory(3C)\f1 .\" .\" toc@\f3memory(3C)\f1:\0\0\f4memccpy()\f1, \f4memchr()\f1, \f4memcmp()\f1, \f4memcpy()\f1, \f4memset()\f1, \n\f4bcopy()\f1, \f4bcmp()\f1, \f4bzero()\f1, \f4ffs()\f1@@@memory operations .\" toc@\f4memccpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memchr()\f1:\0\0memory operations, locate first character@@@see \f3memory(3C)\f1 .\" toc@\f4memcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memcpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memmove()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memset()\f1:\0\0memory operations, set memory@@@see \f3memory(3C)\f1 .\" toc@\f4bcopy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bzero()\f1:\0\0memory operations, clear bytes@@@see \f3memory(3C)\f1 .\" toc@\f4ffs()\f1:\0\0memory operations, find first bit set@@@see \f3memory(3C)\f1 .\" .\" links@memory.3c memccpy.3c .\" links@memory.3c memchr.3c .\" links@memory.3c memcmp.3c .\" links@memory.3c memcpy.3c .\" links@memory.3c memmove.3c .\" links@memory.3c memset.3c .\" links@memory.3c bcopy.3c .\" links@memory.3c bcmp.3c .\" links@memory.3c bzero.3c .\" links@memory.3c ffs.3c .\" .\" $Header: getc.3s,v 76.1 95/07/05 17:28:24 ssa Exp $ .TA g .TH getc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getc(\|), getc_unlocked(\|), getchar(\|), getchar_unlocked(\|), fgetc(\|), getw(\|), getw_unlocked(\|) \- get character or word from a stream file .SH SYNOPSIS .C "#include " .PP .C "int getc(FILE *stream);" .PP .C "int getc_unlocked(FILE *stream);" .PP .C "int getchar(void);" .PP .C "int getchar_unlocked(void);" .PP .C "int fgetc(FILE *stream);" .PP .C "int getw(FILE *stream);" .PP .C "int getw_unlocked(FILE *stream);" .SH DESCRIPTION .TP 15 .CR getc() Returns the next character (i.e., byte) from the named input .IR stream , as an unsigned character converted to an integer. It also moves the file pointer, if defined, ahead one character in .IR stream. .CR getchar() is defined as .CR getc(stdin) . .CR getc() and .CR getchar() are defined both as macros and as functions. .TP .CR fgetc() Same as .CR getc() , but is a function rather than a macro. .CR fgetc() is slower than .CR getc() , but it takes less space per invocation and its name can be passed as an argument to a function. .TP .CR getw() returns the next word (i.e., .CR int in C) from the named input .IR stream. .CR getw() increments the associated file pointer, if defined, to point to the next word. The size of a word is the size of an integer and varies from machine to machine. .CR getw() assumes no special alignment in the file. .PP .CR getc_unlocked() , " getchar_unlocked()" , and .CR getw_unlocked() are identical to .CR getc() , " getchar()" , and .CR getw() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon sucessful completion, .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , and .CR fgetc() return the next byte from the input stream pointed to by .I stream .RC ( stdin for .CR getchar() " and " getchar_unlocked() ). If the stream is at end-of-file, the end-of-file indicator for the stream is set and .SM EOF is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and .SM EOF is returned. .PP Upon sucessful completion, .CR getw() " and " getw_unlocked() return the next word from the input stream pointed to by .IR stream . If the stream is at end-of-file, the end-of-file indicator for the stream is set and .CR getw() " and " getw_unlocked() return .SM EOF. If a read error occurs, the error indicator for the stream is set, and .CR getw() " and " getw_unlocked() return .SM EOF and set .CR errno to indicate the error. .PP .CR ferror() and .CR feof() (or their .CR _unlocked versions) can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , .CR getw() , " getw_unlocked()" , and .CR fgetc() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 .SM [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP .SM [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP .SM [EIO] A physical I/O error has occurred, or the process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RE .PP Additional .CR errno values may be set by the underlying .CR read() function (see .IR read (2)). .SH WARNING .CR getc() and .CR getchar() are implemented both as library functions and macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI\s0-C mode, enclose the function name in parenthesis or use the function address. The following example illustrates each of these methods : .nf .IP .CR #include .CR #undef getc \h'.4i'... .CR main() .CR { .CR " int (*get_char()) ();" \h'1i'... .CR " return_val=getc(c,fd);" \h'1i'... .CR " return_val=(getc)(c,fd1);" \h'1i'... .CR " get_char = getchar;" .CR }; .fi .PP If the integer value returned by .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , or .CR fgetc() is stored into a character variable then compared against the integer constant .CR EOF , the comparison may never succeed because sign-extension of a character on widening to integer is machine-dependent. .PP The macro version of .CR getc() incorrectly treats a .I stream argument with side effects. In particular, .CR getc(*f++) does not work sensibly. The function version of .CR getc() or .CR fgetc() should be used instead. .br Because of possible differences in word length and byte ordering, files written using .CR putw() are machine-dependent, and may be unreadable by .CR getw() on a different processor. .SS Reentrant Interfaces If .CR _REENTRANT is defined before including .RC < stdio.h >, the locked versions of the library functions for .CR getc() and .CR getchar() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR getc() and .CR getchar() . .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), fread(3S), gets(3S), putc(3S), read(2), scanf(3S). .SH STANDARDS CONFORMANCE .CR getc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fgetc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4.2, FIPS 151-2, POSIX.1, ANSI C" .PP .CR getchar() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR getw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4getc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getc_unlock()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4fgetc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getchar()\f1 \- get character or word from \f4standard input\f1 file@@@\f3getc(3S)\f1 .\" index@\f4getchar_unlocked()\f1 \- get character or word from \f4standard input\f1 file@@@\f3getc(3S)\f1 .\" index@\f4getw()\f1 \- get data word (integer) from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getw_unlocked()\f1 \- get data word (integer) from a stream file@@@\f3getc(3S)\f1 .\" index@\f1get: character or data word from a stream file@@@\f3getc(3S)\f1 .\" index@\f1data, get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f1character or data word from a stream file, get@@@\f3getc(3S)\f1 .\" index@\f1word from a stream file, get character or data@@@\f3getc(3S)\f1 .\" index@\f1stream file, get character or data word from a@@@\f3getc(3S)\f1 .\" index@file, stream: get character or data word from a stream file@@@\f3getc(3S)\f1 .\" .\" toc@\f3getc(3S)\f1:\0\0\f4getc()\f1, \f4getc_unlocked()\f1, \f4getchar()\f1, \f4getchar_unlocked()\f1, \f4fgetc()\f1, \n\f4getw()\f1, \f4getw_unlocked\f1@@@get character or word from a stream file .\" toc@\f4fgetc()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getc_unlocked()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getchar()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getchar_unlocked()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4fgetc()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getw()\f1:\0\0get word from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getw_unlocked()\f1:\0\0get word from a stream file@@@see \f3getc(3S)\f1 .\" .\" links@getc.3s getc_unlock.3s .\" links@getc.3s getchar.3s .\" links@getc.3s getchar_unl.3s .\" links@getc.3s fgetc.3s .\" links@getc.3s getw.3s .\" links@getc.3s getw_unlock.3s .\" $Header: getgrent.3c,v 76.1 95/07/05 17:29:02 ssa Exp $ .TA g .TH getgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getgrent(\|), getgrent_r(\|), getgrgid(\|), getgrgid_r(\|), getgrnam(\|), getgrnam_r(\|), setgrent(\|), setgrent_r(\|), endgrent(\|), endgrent_r(\|), fgetgrent(\|), fgetgrent_r(\|) \- get group file entry .SH SYNOPSIS .C "#include " .PP .C "struct group *getgrent(void);" .PD 0 .PP .C "int getgrent_r(" .nf .PD 0 .IP .C "struct group *result," .C "char *buffer," .C "int buflen," .C "FILE **grfp);" .PD 0 .PP .C "struct group *getgrgid(gid_t gid);" .PP .C "int getgrgid_r(" .nf .PD 0 .IP .C "gid_t gid," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "struct group *getgrnam(const char *name);" .PP .C "int getgrnam_r(" .nf .PD 0 .IP .C "const char *name," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "void setgrent(void);" .PP .C "void setgrent_r(FILE **grfp);" .PP .C "void endgrent(void);" .PP .C "void endgrent_r(FILE **grfp);" .PP .C "struct group *fgetgrent(FILE *stream);" .PP .C "int fgetgrent_r(" .nf .PD 0 .IP .C "FILE *stream," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD .SH DESCRIPTION .CR getgrent() , .CR getgrgid() , and .CR getgrnam() locate an entry in the .CR /etc/group file, and return a pointer to an object of type .CR "struct group" . .PP The .CR group structure is defined in .RC < grp.h > and includes the following members: .nf .IP .C "char *gr_name; /* the name of the group */" .C "char *gr_passwd; /* the encrypted group password */" .C "gid_t gr_gid; /* the numerical group \s-1ID\s+1 */" .C "char **gr_mem; /* null-terminated array of pointers" .C " to member names */" .fi .TP 20 .C getgrent() When first called, .CR getgrent() returns a pointer to the first .CR group structure in the file; thereafter, it returns a pointer to the next .CR group structure in the file. In this way, successive calls can be used to search the entire file. .CR getgrent() opens the .CR /etc/group file prior to doing its work and leaves the file open afterward; .TP .C setgrent() Has the effect of rewinding this file to allow repeated searches; .TP .C endgrent() Can be called to close the file when processing is complete. .TP .C getgrgid() Searches from the beginning of the file until a numeric group ID matching .I gid is found, and returns a pointer to the particular structure in which it was found. .TP .C getgrnam() Searches from the beginning of the file until a group name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .C fgetgrent() Returns a pointer to the next .CR group structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/group . .SS Reentrant Interfaces .CR getgrgid_r() , .CR getgrnam_r() and .CR fgetgrent_r() expect to be passed three extra parameters: .PD 0 .TP 3 1. The address of a .C "struct group" where the result will be stored; .TP 2. A buffer to store character strings, such as the group name, to which fields in the .C "struct group" will point; .TP 3. The length of the user-supplied buffer. .PD .PP In addition to the above three parameters, .CR getgrent_r() requires a pointer to a .I "(FILE *)" variable into which is stored the result of an .I fopen() call on the .CR /etc/group file. This parameter allows threads to independently scan through the .CR /etc/group file. .CR setgrent_r() and .CR endgrent_r() are to be used only in conjunction with .CR getgrent_r() and take the same pointer to a .I "(FILE *)" variable as a parameter. .CR setgrent_r() can be used to rewind or open the .CR /etc/group file. .CR endgrent_r() must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .I "(FILE *)" variable must be initialized to NULL before it is passed to either .CR getgrent_r() or .CR setgrent_r() for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH NETWORKING FEATURES .SS NFS If an entry beginning with a plus sign .RC ( + ) or a minus sign .RC (\| \(mi \|) is found, these routines try to use the Network Information Service network database for data. See .IR group (4) for proper syntax and operation. .SH RETURN VALUE .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .CR group structure. .PP .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , and .CR fgetgrent_r() return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getgrent() , .CR getgrgid() , .CR getgrnam() and .CR fgetgrent() fail if any of the following are true: .RS .TP 12 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX file descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .PD .RE .SH EXAMPLE The following code excerpt counts the number of entries in the .CR /etc/group file: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct group gpbuf; char buffer[1024]; FILE *grf = NULL; setgrent_r(&grf); while (getgrent_r(&gpbuf, buffer, sizeof(buffer), &grf) != -1) count++; endgrent_r(&grf); .ft .ps .fi .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library. This causes them to increase the size of programs that do not otherwise use standard I/O and Network Information Service more than might ordinarily be expected. .PP The value returned by .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() points to a single static area that is overwritten by each call to any of the functions. It must be copied if it is to be saved. .PP .CR getgrent() , .CR getgrgid() , .CR getgrnam() , .CR setgrent() , .CR endgrent() , and .CR fgetgrent() are unsafe in multi-thread applications. .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , .CR setgrent_r() , .CR endgrent_r() , and .CR fgetgrent_r() are MT-Safe and should be used instead. .PP Users of .CR getgrent_r() and .CR getgrnam_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH DEPENDENCIES .SS NFS: .br .B FILES .RS .CI /var/yp/ domainname /group.byname .br .CI /var/yp/ domainname /group.bygid .RE .SM .B SEE ALSO: .RS ypcat(1). .RE .SH FILES .C /etc/group .SH SEE ALSO getgroups(2), getpwent(3C), stdio(3S), group(4). .SH STANDARDS CONFORMANCE .CR getgrent() ": SVID2, SVID3, XPG2" .PP .CR endgrent() ": SVID2, SVID3, XPG2" .PP .CR fgetgrent() ": SVID2, SVID3, XPG2" .PP .CR getgrgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgrnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setgrent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getgrent()\f1 \- get next entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4fgetgrent()\f1 \- get next entry in \f4group()\f1-file-formatted input stream@@@\f3getgrent(3C)\f1 .\" index@\f4getgrgid()\f1 \- get entry from \f4group()\f1 file that matches \f4gid()\fP@@@\f3getgrent(3C)\f1 .\" index@\f4getgrnam()\f1 \- get entry from \f4group()\fP file that matches group name \f4name()\f1@@@\f3getgrent(3C)\f1 .\" index@\f4setgrent()\f1 \- rewind pointer to first entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4endgrent()\f1 \- close currently open \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@get: entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@entry from \f4group()\f1 file, get@@@\f3getgrent(3C)\f1 .\" index@\f4group()\f1 file, get entry from@@@\f3getgrent(3C)\f1 .\" index@file, group: get entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" .\" toc@\f3getgrent(3C)\f1:\0\0\f4getgrent()\f1, \f4getgrgid()\f1, \f4getgrnam()\f1, \f4setgrent()\f1, \f4endgrent()\f1,\n \f4fgetgrent()\f1@@@get group file entry .\" toc@\f4getgrgid()\fP, \f4getgrnam()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4setgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4endgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4fgetgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" .\" links@getgrent.3c getgrent_r.3c .\" links@getgrent.3c getgrgid.3c .\" links@getgrent.3c getgrgid_r.3c .\" links@getgrent.3c getgrnam.3c .\" links@getgrent.3c getgrnam_r.3c .\" links@getgrent.3c setgrent.3c .\" links@getgrent.3c setgrent_r.3c .\" links@getgrent.3c endgrent.3c .\" links@getgrent.3c endgrent_r.3c .\" links@getgrent.3c fgetgrent.3c .\" links@getgrent.3c fgetgrent_r.3c .\" .\" fileset_database@getgrent.3c PROGRAMING-MAN .\" $Header: getgrent.3c,v 76.1 95/07/05 17:29:02 ssa Exp $ .TA g .TH getgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getgrent(\|), getgrent_r(\|), getgrgid(\|), getgrgid_r(\|), getgrnam(\|), getgrnam_r(\|), setgrent(\|), setgrent_r(\|), endgrent(\|), endgrent_r(\|), fgetgrent(\|), fgetgrent_r(\|) \- get group file entry .SH SYNOPSIS .C "#include " .PP .C "struct group *getgrent(void);" .PD 0 .PP .C "int getgrent_r(" .nf .PD 0 .IP .C "struct group *result," .C "char *buffer," .C "int buflen," .C "FILE **grfp);" .PD 0 .PP .C "struct group *getgrgid(gid_t gid);" .PP .C "int getgrgid_r(" .nf .PD 0 .IP .C "gid_t gid," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "struct group *getgrnam(const char *name);" .PP .C "int getgrnam_r(" .nf .PD 0 .IP .C "const char *name," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "void setgrent(void);" .PP .C "void setgrent_r(FILE **grfp);" .PP .C "void endgrent(void);" .PP .C "void endgrent_r(FILE **grfp);" .PP .C "struct group *fgetgrent(FILE *stream);" .PP .C "int fgetgrent_r(" .nf .PD 0 .IP .C "FILE *stream," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD .SH DESCRIPTION .CR getgrent() , .CR getgrgid() , and .CR getgrnam() locate an entry in the .CR /etc/group file, and return a pointer to an object of type .CR "struct group" . .PP The .CR group structure is defined in .RC < grp.h > and includes the following members: .nf .IP .C "char *gr_name; /* the name of the group */" .C "char *gr_passwd; /* the encrypted group password */" .C "gid_t gr_gid; /* the numerical group \s-1ID\s+1 */" .C "char **gr_mem; /* null-terminated array of pointers" .C " to member names */" .fi .TP 20 .C getgrent() When first called, .CR getgrent() returns a pointer to the first .CR group structure in the file; thereafter, it returns a pointer to the next .CR group structure in the file. In this way, successive calls can be used to search the entire file. .CR getgrent() opens the .CR /etc/group file prior to doing its work and leaves the file open afterward; .TP .C setgrent() Has the effect of rewinding this file to allow repeated searches; .TP .C endgrent() Can be called to close the file when processing is complete. .TP .C getgrgid() Searches from the beginning of the file until a numeric group ID matching .I gid is found, and returns a pointer to the particular structure in which it was found. .TP .C getgrnam() Searches from the beginning of the file until a group name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .C fgetgrent() Returns a pointer to the next .CR group structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/group . .SS Reentrant Interfaces .CR getgrgid_r() , .CR getgrnam_r() and .CR fgetgrent_r() expect to be passed three extra parameters: .PD 0 .TP 3 1. The address of a .C "struct group" where the result will be stored; .TP 2. A buffer to store character strings, such as the group name, to which fields in the .C "struct group" will point; .TP 3. The length of the user-supplied buffer. .PD .PP In addition to the above three parameters, .CR getgrent_r() requires a pointer to a .I "(FILE *)" variable into which is stored the result of an .I fopen() call on the .CR /etc/group file. This parameter allows threads to independently scan through the .CR /etc/group file. .CR setgrent_r() and .CR endgrent_r() are to be used only in conjunction with .CR getgrent_r() and take the same pointer to a .I "(FILE *)" variable as a parameter. .CR setgrent_r() can be used to rewind or open the .CR /etc/group file. .CR endgrent_r() must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .I "(FILE *)" variable must be initialized to NULL before it is passed to either .CR getgrent_r() or .CR setgrent_r() for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH NETWORKING FEATURES .SS NFS If an entry beginning with a plus sign .RC ( + ) or a minus sign .RC (\| \(mi \|) is found, these routines try to use the Network Information Service network database for data. See .IR group (4) for proper syntax and operation. .SH RETURN VALUE .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .CR group structure. .PP .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , and .CR fgetgrent_r() return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getgrent() , .CR getgrgid() , .CR getgrnam() and .CR fgetgrent() fail if any of the following are true: .RS .TP 12 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX file descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .PD .RE .SH EXAMPLE The following code excerpt counts the number of entries in the .CR /etc/group file: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct group gpbuf; char buffer[1024]; FILE *grf = NULL; setgrent_r(&grf); while (getgrent_r(&gpbuf, buffer, sizeof(buffer), &grf) != -1) count++; endgrent_r(&grf); .ft .ps .fi .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library. This causes them to increase the size of programs that do not otherwise use standard I/O and Network Information Service more than might ordinarily be expected. .PP The value returned by .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() points to a single static area that is overwritten by each call to any of the functions. It must be copied if it is to be saved. .PP .CR getgrent() , .CR getgrgid() , .CR getgrnam() , .CR setgrent() , .CR endgrent() , and .CR fgetgrent() are unsafe in multi-thread applications. .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , .CR setgrent_r() , .CR endgrent_r() , and .CR fgetgrent_r() are MT-Safe and should be used instead. .PP Users of .CR getgrent_r() and .CR getgrnam_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH DEPENDENCIES .SS NFS: .br .B FILES .RS .CI /var/yp/ domainname /group.byname .br .CI /var/yp/ domainname /group.bygid .RE .SM .B SEE ALSO: .RS ypcat(1). .RE .SH FILES .C /etc/group .SH SEE ALSO getgroups(2), getpwent(3C), stdio(3S), group(4). .SH STANDARDS CONFORMANCE .CR getgrent() ": SVID2, SVID3, XPG2" .PP .CR endgrent() ": SVID2, SVID3, XPG2" .PP .CR fgetgrent() ": SVID2, SVID3, XPG2" .PP .CR getgrgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgrnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setgrent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getgrent()\f1 \- get next entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4fgetgrent()\f1 \- get next entry in \f4group()\f1-file-formatted input stream@@@\f3getgrent(3C)\f1 .\" index@\f4getgrgid()\f1 \- get entry from \f4group()\f1 file that matches \f4gid()\fP@@@\f3getgrent(3C)\f1 .\" index@\f4getgrnam()\f1 \- get entry from \f4group()\fP file that matches group name \f4name()\f1@@@\f3getgrent(3C)\f1 .\" index@\f4setgrent()\f1 \- rewind pointer to first entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4endgrent()\f1 \- close currently open \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@get: entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@entry from \f4group()\f1 file, get@@@\f3getgrent(3C)\f1 .\" index@\f4group()\f1 file, get entry from@@@\f3getgrent(3C)\f1 .\" index@file, group: get entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" .\" toc@\f3getgrent(3C)\f1:\0\0\f4getgrent()\f1, \f4getgrgid()\f1, \f4getgrnam()\f1, \f4setgrent()\f1, \f4endgrent()\f1,\n \f4fgetgrent()\f1@@@get group file entry .\" toc@\f4getgrgid()\fP, \f4getgrnam()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4setgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4endgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4fgetgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" .\" links@getgrent.3c getgrent_r.3c .\" links@getgrent.3c getgrgid.3c .\" links@getgrent.3c getgrgid_r.3c .\" links@getgrent.3c getgrnam.3c .\" links@getgrent.3c getgrnam_r.3c .\" links@getgrent.3c setgrent.3c .\" links@getgrent.3c setgrent_r.3c .\" links@getgrent.3c endgrent.3c .\" links@getgrent.3c endgrent_r.3c .\" links@getgrent.3c fgetgrent.3c .\" links@getgrent.3c fgetgrent_r.3c .\" .\" fileset_database@getgrent.3c PROGRAMING-MAN .\" $Header: fgetpos.3s,v 78.1 96/02/12 13:44:18 ssa Exp $ .TA f .TH fgetpos 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetpos(\|), fsetpos(\|) \- save and restore a file position indicator for a stream .SH SYNOPSIS .C "#include " .PP .C "int fgetpos(FILE *stream, fpos_t *pos);" .PP .C "int fsetpos(FILE *stream, const fpos_t *pos);" .SH DESCRIPTION .TP 15 .C fgetpos() Store the current value of the file position indicator for the stream pointed to by .IR stream in the object pointed to by .IR pos . The value stored contains information usable by .C fsetpos() for repositioning the stream to its position at the time of the call to .CR fgetpos() . .TP .C fsetpos() Set the file position indicator for the stream pointed to by .IR stream according to the value of the object pointed to by .IR pos, which must be a value set by an earlier call to .C fgetpos() on the same stream. .IP A successful call to .C fsetpos() clears the end-of-file indicator for the stream and undoes any effects of .IR ungetc (3S) on the same stream. After a .C fsetpos() call, the next operation on a update stream can be either input or output. .SH RETURN VALUE If successful, these functions return zero; otherwise non-zero. .SH ERRORS If .CR fgetpos() fails, .CR errno is set to one of the following values. .ER .TP 15 [EINVAL] The current value of the file position cannot be represented correctly in an object of size .CR fpos_t in this environment. .PP Additional .CR errno values may be set by the underlying .CR ftell() function (see .IR ftell (3S)). .SH WARNINGS Failure can occur if these functions are used on a file that has not been opened via .CR fopen() . In particular, they must not be used on a terminal or on a file opened via .IR popen (3S). .PP .C fsetpos() has no effect on streams that are open for append (see .IR fopen (3S)). .SH SEE ALSO fgetpos64(3S), fseek(3S), fsetpos64(3S), fopen(3S), popen(3S), ungetc(3S). .SH STANDARDS CONFORMANCE .CR fgetpos() ": AES, SVID3, XPG4, ANSI C" .PP .CR fsetpos() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4fgetpos()\fP \- save file position indicator for a stream@@@\f3fgetpos(3S)\f1 .\" index@\f4fsetpos()\fP \- restore file position indicator for a stream@@@\f3fgetpos(3S)\f1 .\" index@restore or save file position indicator for a stream@@@\f3fgetpos(3S)\f1 .\" index@save or restore file position indicator for a stream@@@\f3fgetpos(3S)\f1 .\" index@stream, save or restore file position indicator for a@@@\f3fgetpos(3S)\f1 .\" index@file position indicator for a stream, save or restore@@@\f3fgetpos(3S)\f1 .\" .\" toc@\f3fgetpos(3S)\f1:\0\0\f4fgetpos()\fP, \f4fsetpos()\fP@@@save or restore file position indicator for a stream .\" toc@\f4fsetpos()\fP \- restore file position indicator for a stream@@@see \f3fgetpos(3S)\f1 .\" .\" links@fgetpos.3s fsetpos.3s .\" .\" $Header: fgetpos64.3s,v 78.3 96/02/12 17:04:12 ssa Exp $ .TA f .TH fgetpos64 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetpos64(\|), fopen64(\|), freopen64(\|), fseeko64(\|), fsetpos64(\|), fstatvfsdev64(\|), ftello64(\|), ftw64(\|), nftw64(\|), statvfsdev64(\|), tmpfile64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0fgetpos64(FILE\0*stream,\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "FILE\0*fopen64(const\0char\0*pathname,\0const\0char\0*type);" .PP .C "#include " .PP .C "FILE\0*freopen64(const\0char\0*pathname,\0const\0char\0*type,\0FILE\0*stream);" .PP .C "#include " .PP .C "int\0fseeko64(FILE\0*stream,\0off64_t\0*offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0fsetpos64(FILE\0*stream,\0const\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "int\0fstatvfsdev64(int\0filedes,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "off64_t\0ftello64(FILE\0*stream);" .PP .nf .C "#include " .PP .C "int ftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags)," .C " int depth);" .PP .C "#include " .PP .C "int nftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .PP .C "#include " .PP .C "int\0statvfsdev64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "FILE\0*tmpfile64(void);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 22 .C fgetpos64() The .C fgetpos64() function is identical to .C fgetpos() except that .C fgetpos64() returns the position in a .C fpos64_t instead of a .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fopen64() The .C fopen64() function is identical to .C fopen() in 64-bit compile environment. The .C fopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR fopen() . .TP .C freopen64() The .C freopen64() function is identical to .C freopen() in 64-bit compile environment. The .C freopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR freopen() . .TP .C fseeko64() The .C fseeko64() function is identical to .C fseeko() except that .C fseeko64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C fsetpos64() The .C fsetpos64() function is identical to .C fsetpos() except that .C fsetpos64() accepts an .CR fpos64_t for the pos parameter instead of .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fstatvfsdev64() The .C fstatvfsdev64() function is identical to .C fstatvfsdev() except that .C fstatvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C ftello64() The .C ftello64() function is identical to .C ftello() except that .C ftello64() returns the file position in an .C off64_t instead of an .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C ftw64() The .C ftw64() function is identical to .C ftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR ftw64() . All other functional behaviors, returns, and errors are identical. .TP .C nftw64() The .C nftw64() function is identical to .C nftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR nftw64() . All other functional behaviors, returns, and errors are identical. .TP .C statvfsdev64() The .C statvfsdev64() function is identical to .C statvfsdev() except that .C statvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C tmpfile64() The .C tmpfile64() function is identical to .C tmpfile() in the 64-bit compile environment. Both interfaces create a temporary file that is capable of growing beyond 2GB's if desired. All other functional behaviors, returns, and errors are identical. .\" .\" toc@\f4fgetpos64(2)\f1:\0\0\f4fopen64\f1, \f4freopen64\f1, \f4fseeko64\f1, \f4fsetpos64\f1, \f4fstatvfsdev64\f1, \f4ftello64\f1, \f4ftw64\f1, \n\f4nftw64\f1, \f4statvfsdev64\f1, \f4tmpfile64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4fgetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4freopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fseeko64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fsetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fstatvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftello64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4nftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4statvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4tmpfile64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3fgetpos64(2)\f1 .\" .\" links@fgetpos64.3s fopen64.3s .\" links@fgetpos64.3s freopen64.3s .\" links@fgetpos64.3s fseek64.3s .\" links@fgetpos64.3s fsetpos64.3s .\" links@fgetpos64.3s fstatvfs64.3s .\" links@fgetpos64.3s ftello64.3s .\" links@fgetpos64.3s ftw64.3s .\" links@fgetpos64.3s nftw64.3s .\" links@fgetpos64.3s statvfsdev64.3s .\" links@fgetpos64.3s tmpfile64.3s .\" .\" $Header: getpwent.3c,v 78.1 95/12/20 10:53:01 ssa Exp $ .TA g .TH getpwent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpwent(\|), getpwent_r(\|), getpwuid(\|), getpwuid_r(\|), getpwnam(\|), getpwnam_r(\|), setpwent(\|), setpwent_r(\|), endpwent(\|), endpwent_r(\|), fgetpwent(\|), fgetpwent_r(\|) \- get password file entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct passwd *getpwent(void);" .PP .C "int getpwent_r(struct passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct passwd *getpwuid(uid_t uid);" .PP .PD 0 .C "int getpwuid_r(uid_t uid, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct passwd *getpwnam(const char *name);" .PP .PD 0 .C "int getpwnam_r(char *name, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setpwent(void);" .PP .C "void setpwent_r(FILE **pwfp);" .PP .C "void endpwent(void);" .PP .C "void endpwent_r(FILE **pwfp);" .PP .C "struct passwd *fgetpwent(FILE *stream);" .PP .C "int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, int buflen);" .fi .SH DESCRIPTION .CR getpwent (), .CR getpwuid (), and .CR getpwnam () locate an entry in the .C /etc/passwd file, and return a pointer to an object of .C passwd structure. .PP The .C passwd structure is defined in .RC < pwd.h > and includes the following members: .nf .IP .CR "char *pw_name; " "/* user name */" .CR "char *pw_passwd; " "/* encrypted password */" .CR "uid_t pw_uid; " "/* user id */" .CR "gid_t pw_gid; " "/* group id */" .CR "char *pw_age; " "/* password aging */" .CR "char *pw_comment;" "/* unused */" .CR "char *pw_gecos; " "/* user fullname, office, extension, homephone*/" .CR "char *pw_dir; " "/* initial directory */" .CR "char *pw_shell; " "/* initial shell */" .CR "aid_t pw_audid; " "/* numerical audit id */" .CR "int pw_audflg; " "/* numerical audit flag */" .fi .PP The .I pw_comment field is unused; for more information on the other fields, refer to .IR passwd (4). .TP 20 .CR getpwent () When first called, .CR getpwent () returns a pointer to the first .C passwd structure in the file. Thereafter, it returns a pointer to the next .C passwd structure in the file. In this way, successive calls can be used to search the entire file. .CR getpwent () opens the .C /etc/passwd file prior to doing its work and leaves the file open afterward; .TP .CR setpwent () Has the effect of rewinding this file to allow repeated searches; .TP .CR endpwent () Can be called to close the file when processing is complete. .TP .CR getpwuid () Searches from the beginning of the file until a numeric user .SM ID matching .I uid is found, and returns a pointer to the particular structure in which it was found. .TP .CR getpwnam () searches from the beginning of the file until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .CR fgetpwent () returns a pointer to the next .C passwd structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/passwd . .SS Reentrant Interfaces .CR getpwuid_r (), .CR getpwnam_r () and .CR fgetpwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .C passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in .C passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getpwent_r () requires a pointer to a .RI ( "FILE *" ) variable into which is stored the result of an .CR fopen () call on the .C /etc/passwd file. This is to allow threads to independently scan through the .C /etc/passwd file. .CR setpwent_r () and .CR endpwent_r () are to be used only in conjunction with .CR getpwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setpwent_r () can be used to rewind or open the .C /etc/passwd file. .CR endpwent_r () must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getpwent_r () or .CR setpwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH SECURITY FEATURES If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default .CR * that is in .C /etc/passwd and the audit ID and audit flag will be set to \(mi1. On trusted systems, if it is not necessary to obtain information from the regular password file, .CR /etc/passwd , users should use .CR getprpwent () to access the protected password database. See .IR getprpwent (3) and .IR getspwent (3X). .PP .CR putpwent () affects only .CR /etc/passwd ; the audit .SM ID and audit flag in the password structure are ignored. .CR putprpwnam () must be used to modify the protected password databse entries. See .IR getprpwent (3). .SH NETWORKING FEATURES .SS \s-1NFS\s0 If an entry beginning with a plus sign .RC ( + ) or a minus sign .RB ( \(mi ) is found, these routines try to use the Network Information Service network database for data. See .IR passwd (4) for proper syntax and operation. .PP Network Information Service (NIS) is not supported on trusted systems. .SH RETURN VALUE .CR getpwent (), .CR getpwuid (), .CR getpwnam (), and .CR fgetpwent () return a .SM NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .C passwd structure. .PP .CR getpwent_r (), .CR getpwuid_r (), .CR getpwnam_r (), and .CR fgetpwent_r (), return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getpwent() , .CR getpwuid() , and .CR fgetpwent() fail if any of the following are true: .RS .TP 15 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library, which causes them to increase the size of programs, not otherwise using standard .SM I/O and Network Information Service, more than might be expected. .PP The value returned by .CR getpwent() , .CR getpwuid() , .CR getpwnam() , and .C fgetpwent() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved. .PP .CR getpwent() , .CR getpwuid() , .CR getpwnam() , .CR setpwent() , .CR endpwent() , and .C fgetpwent() are unsafe in multi-thread applications. .CR getpwent_r() , .CR getpwuid_r() , .CR getpwnam_r() , .CR setpwent_r() , .CR endpwent_r() , and .C fgetpwent_r() are MT-Safe and should be used instead. .PP The following fields have numerical limitations as noted: .RS .TP 3 \(bu The user ID is an integer value between -2 and UID_MAX inclusive. .TP \(bu The group ID is an integer value between 0 and UID_MAX inclusive. .RE .PP Users of .CR getpwnam_r() and .CR getpwuid_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH EXAMPLE The following code excerpt counts the number of entries in the .C /etc/passwd file: .PP .nf .IP .C "int count = 0;" .C "struct passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setpwent_r(&pwf);" .C "while (getpwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endpwent_r(&pwf);" .fi .SH DEPENDENCIES .SS \s-1NFS\s0 .B Files: .RS .CI /var/yp/ domainname /passwd.byname .br .CI /var/yp/ domainname /passwd.byuid .RE .PP .B See Also: .RS ypcat(1). .RE .SH AUTHOR .CR getpwent (), .CR getpwuid (), .CR getpwnam (), .CR setpwent (), .CR endpwent (), and .CR fgetpwent () were developed by AT&T and HP. .SH FILES .TP 30 .C /etc/passwd System Password file .SH SEE ALSO ypcat(1), cuserid(3S), getgrent(3C), getlogin(3C), getprpwent(3), getspwent(3X), stdio(3S), putpwent(3C), putspwent(3X), passwd(4), limits(5). .SH STANDARDS CONFORMANCE .CR getpwent() ": SVID2, SVID3, XPG2" .PP .CR endpwent() ": SVID2, SVID3, XPG2" .PP .CR fgetpwent() ": SVID2, SVID3, XPG2" .PP .CR getpwnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpwuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setpwent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getpwent()\f1 \- get next password file entry@@@\f3getpwent(3C)\f1 .\" index@\f4fgetpwent()\f1 \- get next entry in password-file-formatted input stream@@@\f3getpwent(3C)\f1 .\" index@\f4getpwuid()\f1 \- get password file entry matching \f4uid()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4getpwnam()\f1 \- get password file entry matching login name \f4name()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4setpwent()\f1 \- rewind pointer to beginning of password file@@@\f3getpwent(3C)\f1 .\" index@\f4endpwent()\f1 \- close currently open password file@@@\f3getpwent(3C)\f1 .\" index@entry from password file, get@@@\f3getpwent(3C)\f1 .\" index@password file, get entry from@@@\f3getpwent(3C)\f1 .\" index@file, password: get entry from password file@@@\f3getpwent(3C)\f1 .\" .\" toc@\f3getpwent(3C)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f , \f4endpwent()\f1, \n\f4fgetpwent()\f1@@@get password file entry .\" toc@\f4getpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4setpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4endpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" .\" links@getpwent.3c getpwuid.3c .\" links@getpwent.3c getpwnam.3c .\" links@getpwent.3c setpwent.3c .\" links@getpwent.3c endpwent.3c .\" links@getpwent.3c fgetpwent.3c .\" links@getpwent.3c getpwent_r.3c .\" links@getpwent.3c getpwuid_r.3c .\" links@getpwent.3c getpwnam_r.3c .\" links@getpwent.3c setpwent_r.3c .\" links@getpwent.3c endpwent_r.3c .\" links@getpwent.3c fgetpwent_r.3c .\" .\" fileset_database@getpwent.3c PROGRAMING-MAN .\" $Header: getpwent.3c,v 78.1 95/12/20 10:53:01 ssa Exp $ .TA g .TH getpwent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpwent(\|), getpwent_r(\|), getpwuid(\|), getpwuid_r(\|), getpwnam(\|), getpwnam_r(\|), setpwent(\|), setpwent_r(\|), endpwent(\|), endpwent_r(\|), fgetpwent(\|), fgetpwent_r(\|) \- get password file entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct passwd *getpwent(void);" .PP .C "int getpwent_r(struct passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct passwd *getpwuid(uid_t uid);" .PP .PD 0 .C "int getpwuid_r(uid_t uid, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct passwd *getpwnam(const char *name);" .PP .PD 0 .C "int getpwnam_r(char *name, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setpwent(void);" .PP .C "void setpwent_r(FILE **pwfp);" .PP .C "void endpwent(void);" .PP .C "void endpwent_r(FILE **pwfp);" .PP .C "struct passwd *fgetpwent(FILE *stream);" .PP .C "int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, int buflen);" .fi .SH DESCRIPTION .CR getpwent (), .CR getpwuid (), and .CR getpwnam () locate an entry in the .C /etc/passwd file, and return a pointer to an object of .C passwd structure. .PP The .C passwd structure is defined in .RC < pwd.h > and includes the following members: .nf .IP .CR "char *pw_name; " "/* user name */" .CR "char *pw_passwd; " "/* encrypted password */" .CR "uid_t pw_uid; " "/* user id */" .CR "gid_t pw_gid; " "/* group id */" .CR "char *pw_age; " "/* password aging */" .CR "char *pw_comment;" "/* unused */" .CR "char *pw_gecos; " "/* user fullname, office, extension, homephone*/" .CR "char *pw_dir; " "/* initial directory */" .CR "char *pw_shell; " "/* initial shell */" .CR "aid_t pw_audid; " "/* numerical audit id */" .CR "int pw_audflg; " "/* numerical audit flag */" .fi .PP The .I pw_comment field is unused; for more information on the other fields, refer to .IR passwd (4). .TP 20 .CR getpwent () When first called, .CR getpwent () returns a pointer to the first .C passwd structure in the file. Thereafter, it returns a pointer to the next .C passwd structure in the file. In this way, successive calls can be used to search the entire file. .CR getpwent () opens the .C /etc/passwd file prior to doing its work and leaves the file open afterward; .TP .CR setpwent () Has the effect of rewinding this file to allow repeated searches; .TP .CR endpwent () Can be called to close the file when processing is complete. .TP .CR getpwuid () Searches from the beginning of the file until a numeric user .SM ID matching .I uid is found, and returns a pointer to the particular structure in which it was found. .TP .CR getpwnam () searches from the beginning of the file until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .CR fgetpwent () returns a pointer to the next .C passwd structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/passwd . .SS Reentrant Interfaces .CR getpwuid_r (), .CR getpwnam_r () and .CR fgetpwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .C passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in .C passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getpwent_r () requires a pointer to a .RI ( "FILE *" ) variable into which is stored the result of an .CR fopen () call on the .C /etc/passwd file. This is to allow threads to independently scan through the .C /etc/passwd file. .CR setpwent_r () and .CR endpwent_r () are to be used only in conjunction with .CR getpwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setpwent_r () can be used to rewind or open the .C /etc/passwd file. .CR endpwent_r () must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getpwent_r () or .CR setpwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH SECURITY FEATURES If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default .CR * that is in .C /etc/passwd and the audit ID and audit flag will be set to \(mi1. On trusted systems, if it is not necessary to obtain information from the regular password file, .CR /etc/passwd , users should use .CR getprpwent () to access the protected password database. See .IR getprpwent (3) and .IR getspwent (3X). .PP .CR putpwent () affects only .CR /etc/passwd ; the audit .SM ID and audit flag in the password structure are ignored. .CR putprpwnam () must be used to modify the protected password databse entries. See .IR getprpwent (3). .SH NETWORKING FEATURES .SS \s-1NFS\s0 If an entry beginning with a plus sign .RC ( + ) or a minus sign .RB ( \(mi ) is found, these routines try to use the Network Information Service network database for data. See .IR passwd (4) for proper syntax and operation. .PP Network Information Service (NIS) is not supported on trusted systems. .SH RETURN VALUE .CR getpwent (), .CR getpwuid (), .CR getpwnam (), and .CR fgetpwent () return a .SM NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .C passwd structure. .PP .CR getpwent_r (), .CR getpwuid_r (), .CR getpwnam_r (), and .CR fgetpwent_r (), return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getpwent() , .CR getpwuid() , and .CR fgetpwent() fail if any of the following are true: .RS .TP 15 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library, which causes them to increase the size of programs, not otherwise using standard .SM I/O and Network Information Service, more than might be expected. .PP The value returned by .CR getpwent() , .CR getpwuid() , .CR getpwnam() , and .C fgetpwent() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved. .PP .CR getpwent() , .CR getpwuid() , .CR getpwnam() , .CR setpwent() , .CR endpwent() , and .C fgetpwent() are unsafe in multi-thread applications. .CR getpwent_r() , .CR getpwuid_r() , .CR getpwnam_r() , .CR setpwent_r() , .CR endpwent_r() , and .C fgetpwent_r() are MT-Safe and should be used instead. .PP The following fields have numerical limitations as noted: .RS .TP 3 \(bu The user ID is an integer value between -2 and UID_MAX inclusive. .TP \(bu The group ID is an integer value between 0 and UID_MAX inclusive. .RE .PP Users of .CR getpwnam_r() and .CR getpwuid_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH EXAMPLE The following code excerpt counts the number of entries in the .C /etc/passwd file: .PP .nf .IP .C "int count = 0;" .C "struct passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setpwent_r(&pwf);" .C "while (getpwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endpwent_r(&pwf);" .fi .SH DEPENDENCIES .SS \s-1NFS\s0 .B Files: .RS .CI /var/yp/ domainname /passwd.byname .br .CI /var/yp/ domainname /passwd.byuid .RE .PP .B See Also: .RS ypcat(1). .RE .SH AUTHOR .CR getpwent (), .CR getpwuid (), .CR getpwnam (), .CR setpwent (), .CR endpwent (), and .CR fgetpwent () were developed by AT&T and HP. .SH FILES .TP 30 .C /etc/passwd System Password file .SH SEE ALSO ypcat(1), cuserid(3S), getgrent(3C), getlogin(3C), getprpwent(3), getspwent(3X), stdio(3S), putpwent(3C), putspwent(3X), passwd(4), limits(5). .SH STANDARDS CONFORMANCE .CR getpwent() ": SVID2, SVID3, XPG2" .PP .CR endpwent() ": SVID2, SVID3, XPG2" .PP .CR fgetpwent() ": SVID2, SVID3, XPG2" .PP .CR getpwnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpwuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setpwent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getpwent()\f1 \- get next password file entry@@@\f3getpwent(3C)\f1 .\" index@\f4fgetpwent()\f1 \- get next entry in password-file-formatted input stream@@@\f3getpwent(3C)\f1 .\" index@\f4getpwuid()\f1 \- get password file entry matching \f4uid()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4getpwnam()\f1 \- get password file entry matching login name \f4name()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4setpwent()\f1 \- rewind pointer to beginning of password file@@@\f3getpwent(3C)\f1 .\" index@\f4endpwent()\f1 \- close currently open password file@@@\f3getpwent(3C)\f1 .\" index@entry from password file, get@@@\f3getpwent(3C)\f1 .\" index@password file, get entry from@@@\f3getpwent(3C)\f1 .\" index@file, password: get entry from password file@@@\f3getpwent(3C)\f1 .\" .\" toc@\f3getpwent(3C)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f , \f4endpwent()\f1, \n\f4fgetpwent()\f1@@@get password file entry .\" toc@\f4getpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4setpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4endpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" .\" links@getpwent.3c getpwuid.3c .\" links@getpwent.3c getpwnam.3c .\" links@getpwent.3c setpwent.3c .\" links@getpwent.3c endpwent.3c .\" links@getpwent.3c fgetpwent.3c .\" links@getpwent.3c getpwent_r.3c .\" links@getpwent.3c getpwuid_r.3c .\" links@getpwent.3c getpwnam_r.3c .\" links@getpwent.3c setpwent_r.3c .\" links@getpwent.3c endpwent_r.3c .\" links@getpwent.3c fgetpwent_r.3c .\" .\" fileset_database@getpwent.3c PROGRAMING-MAN .\" $Header: gets.3s,v 72.5 94/11/15 09:54:47 ssa Exp $ .TA g .TH gets 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gets(\|), fgets(\|), fgets_unlocked(\|) \- get a string from a stream .SH SYNOPSIS .C "#include " .PP .C "char *gets(char *s);" .PP .C "char *fgets(char *s, int n, FILE *stream);" .PP .C "char *fgets_unlocked(char *s, int n, FILE *stream);" .SH DESCRIPTION .TP 15 .C gets() Reads characters from the standard input stream, .CR stdin , into the array pointed to by .IR s , until a new-line character is read or an end-of-file condition is encountered. The new-line character is discarded and the string is terminated with a null character. .TP .C fgets() Reads characters from the .I stream into the array pointed to by .IR s , until .IR n \(mi 1 characters are read, a new-line character is read and transferred to .IR s , or an end-of-file condition is encountered. The string is then terminated with a null character. .PP .CR fgets_unlocked() is identical to .CR fgets() except it does not perform any internal locking of the .I stream for multi-thread applications. .CR fgets_unlocked can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon sucessful completion, .CR fgets() , .CR fgets_unlocked() , and .CR gets() return .IR s . If the stream is at end-of-file, the end-of-file indicator for the stream is set and a null pointer is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and a null pointer is returned. .PP .CR ferror() and .CR feof() can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR fgets() , .CR fgets_unlocked() , and .CR gets() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP [EIO] The process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RS .PP Additional .CR errno values can be set by the underlying .CR read() function (see .IR read (2)). .SH SEE ALSO ferror(3S), flockfile(3S), fopen(3S), fread(3S), getc(3S), puts(3S), scanf(3S). .SH STANDARDS CONFORMANCE .CR gets() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fgets() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4gets()\f1, \f4fgets()\f1 \- get a string from a \f2standard input\f1 stream@@@\f3gets(3S)\f1 .\" index@\f4fgets()\f1, \f4gets()\f1 \- get a string from a \f2standard input\f1 stream@@@\f3gets(3S)\f1 .\" index@input string from a \f2standard input\f1 stream@@@\f3gets(3S)\f1 .\" index@string from a \f2standard input\f1 stream, input@@@\f3gets(3S)\f1 .\" index@\f2standard input\f1 stream, input string from a@@@\f3gets(3S)\f1 .\" index@stream, input string from a \f2standard input\f1@@@\f3gets(3S)\f1 .\" .\" toc@\f3gets(3S)\f1:\0\0\f4gets()\f1, \f4fgets()\f1@@@get a string from a stream .\" toc@\f4fgets()\f1:\0\0get a string from a stream@@@see \f3gets(3S)\f1 .\" .\" links@gets.3s fgets.3s .\" links@gets.3s fgets_unloc.3s .\" .\" fileset_database@gets.3s PROGRAMING-MAN .\" $Header: gets.3s,v 72.5 94/11/15 09:54:47 ssa Exp $ .TA g .TH gets 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gets(\|), fgets(\|), fgets_unlocked(\|) \- get a string from a stream .SH SYNOPSIS .C "#include " .PP .C "char *gets(char *s);" .PP .C "char *fgets(char *s, int n, FILE *stream);" .PP .C "char *fgets_unlocked(char *s, int n, FILE *stream);" .SH DESCRIPTION .TP 15 .C gets() Reads characters from the standard input stream, .CR stdin , into the array pointed to by .IR s , until a new-line character is read or an end-of-file condition is encountered. The new-line character is discarded and the string is terminated with a null character. .TP .C fgets() Reads characters from the .I stream into the array pointed to by .IR s , until .IR n \(mi 1 characters are read, a new-line character is read and transferred to .IR s , or an end-of-file condition is encountered. The string is then terminated with a null character. .PP .CR fgets_unlocked() is identical to .CR fgets() except it does not perform any internal locking of the .I stream for multi-thread applications. .CR fgets_unlocked can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon sucessful completion, .CR fgets() , .CR fgets_unlocked() , and .CR gets() return .IR s . If the stream is at end-of-file, the end-of-file indicator for the stream is set and a null pointer is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and a null pointer is returned. .PP .CR ferror() and .CR feof() can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR fgets() , .CR fgets_unlocked() , and .CR gets() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP [EIO] The process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RS .PP Additional .CR errno values can be set by the underlying .CR read() function (see .IR read (2)). .SH SEE ALSO ferror(3S), flockfile(3S), fopen(3S), fread(3S), getc(3S), puts(3S), scanf(3S). .SH STANDARDS CONFORMANCE .CR gets() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fgets() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4gets()\f1, \f4fgets()\f1 \- get a string from a \f2standard input\f1 stream@@@\f3gets(3S)\f1 .\" index@\f4fgets()\f1, \f4gets()\f1 \- get a string from a \f2standard input\f1 stream@@@\f3gets(3S)\f1 .\" index@input string from a \f2standard input\f1 stream@@@\f3gets(3S)\f1 .\" index@string from a \f2standard input\f1 stream, input@@@\f3gets(3S)\f1 .\" index@\f2standard input\f1 stream, input string from a@@@\f3gets(3S)\f1 .\" index@stream, input string from a \f2standard input\f1@@@\f3gets(3S)\f1 .\" .\" toc@\f3gets(3S)\f1:\0\0\f4gets()\f1, \f4fgets()\f1@@@get a string from a stream .\" toc@\f4fgets()\f1:\0\0get a string from a stream@@@see \f3gets(3S)\f1 .\" .\" links@gets.3s fgets.3s .\" links@gets.3s fgets_unloc.3s .\" .\" fileset_database@gets.3s PROGRAMING-MAN .\" $Header: getspwent.3x,v 72.6 94/11/30 10:11:44 ssa Exp $ .TA g .TH getspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getspwent(\|), getspwent_r(\|), getspwuid(\|), getspwuid_r(\|), getspwaid(\|), getspwaid_r(\|), getspwnam(\|), getspwnam_r(\|), setspwent(\|), setspwent_r(\|), endspwent(\|), endspwent_r(\|), fgetspwent(\|), fgetspwent_r(\|) \- get secure password file entry\c , on trusted systems .SH SYNOPSIS .C "#include " .PP .C "struct s_passwd *getspwent(void);" .PP .C "int getspwent_r(struct s_passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct s_passwd *getspwuid(uid_t uid);" .PP .PD 0 .C "int getspwuid_r(uid_t uid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwaid(aid_t aid);" .PP .PD 0 .C "int getspwaid_r(aid_t aid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwnam(const char *name);" .PP .PD 0 .C "int getspwnam_r(char *name, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setspwent(void);" .PP .C "void setspwent_r(FILE **pwfp);" .PP .C "void endspwent(void);" .PP .C "void endspwent_r(FILE **pwfp);" .PP .C "struct s_passwd *fgetspwent(\s-1FILE\s0 *stream);" .PP .PD 0 .C "int fgetspwent_r(FILE *f, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .SH DESCRIPTION These privileged routines provide access to the protected password database in a manner similar to the way .IR getpwent (3C) routines handle the regular password file, .RC ( \|/etc/passwd\| ). .PP These routines are particularly useful in situations where it is not necessary to get information from the regular password file. .IR getspwent (3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, .CR libsec . .PP Note that .CR getspwent () routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the .CR getprpwent () routines. See .IR getprpwent (3). .PP .CR getspwent (), .CR getspwuid (), .CR getspwaid (), and .CR getspwnam () each returns a pointer to an object of .CR s_passwd structure. The .CR s_passwd structure is maintained for compatibility with existing software and consists of five fields as follows: .nf .IP .C "struct\ s_passwd\ {" .C " char *pw_name; /* login name */" .C " char *pw_passwd; /* encrypted password */" .C " char *pw_age; /* password age */" .C " int pw_audid; /* audit ID */" .C " int pw_audflg; /* audit flag 1=on, 0=off */" .C }; .fi .PP Since the .CR s_passwd structure is declared in the .RC < pwd.h > header file, it is unnecessary to redeclare it. .PP To access other fields in the protected password database that are not included in the .CR s_passwd structure, use .CR getprpwent (). See .IR getprpwent (3) for more information. .PP .TP 20 .CR getspwent () When first called, .CR getspwent () returns a pointer to each .CR s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database. .TP .CR getspwuid () Searches for an entry that matches the specified .IR uid . It then returns a pointer to the particular structure in which .I uid is found. .TP .CR getspwaid () Similarly searches for a numerical audit ID matching .I aid and returns a pointer to the particular structure in which .I aid is found (see .IR spasswd (4) for details on this field). .TP .CR getspwnam () Searches for an entry that matches the specified .IR name . Returns a pointer to the particular structure in which .I name is found. .TP .CR setspwent () Resets the protected password database pointer to the beginning of the file to allow repeated searches. .TP .CR endspwent () Should be called to close the protected password database file when processing is complete. .TP .CR fgetspwent () Is no longer supported. It is provided for those applications that did not use .CR /.secure/etc/passwd . .SS Reentrant Interfaces .CR getspwuid_r (), .CR getspwaid_r (), .CR getspwnam_r (), and .CR fgetspwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .CR s_passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in the .CR s_passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getspwent_r () requires a pointer to a .RI ( "FILE *" ) variable. .CR setspwent_r () and .CR endspwent_r () are to be used only in conjunction with .CR getspwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setspwent_r () can be used to rewind or open the protected password database. .CR endspwent_r () should be called when done to close the file. .PP The .CR /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database. .PP .CR fgetspwent_r () is no longer supported, but is included for those users that did not use the .CR /.secure/etc/passwd file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getspwent_r () or .CR setspwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH RETURN VALUE .CR getspwent () returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the calling process is not zero. .PP .CR getspwent_r () returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned. .SH WARNINGS The above routines use .RC < stdio.h >, which causes them to increase the size of programs by more than might otherwise be expected. .PP Since all information for .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() is contained in a static area, it must be copied to be saved. .PP .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() are unsafe in multi-thread applications. .CR getspwent_r() , .CR getspwuid_r() , .CR getspwaid_r() , .CR getspwnam_r() , .CR setspwent_r() , .CR endspwent_r() , and .CR fgetspwent_r() are MT-Safe and should be used instead. .PP Network Information Service is not supported on trusted systems. .SH EXAMPLE The following code excerpt counts the number of entries in the protected password database: .nf .IP .C "int count = 0;" .C "struct s_passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setspwent_r(&pwf);" .C "while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endspwent_r(&pwf);" .SH AUTHOR .CR getspwent () was developed by HP. .SH FILES .TP 30 .C /tcb/files/auth/*/* Protected Password database .SH SEE ALSO ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), putspwent(3X), passwd(4). .\" .\" index@\f4getspwent()\f1 \- get next secure password file entry@@@\f3getspwent(3X)\f1 .\" index@\f4getspwaid()\f1 \- get next secure password file audit ID@@@\f3getspwent(3X)\f1 .\" index@\f4fgetspwent()\f1 \- get next entry in secure password-file-formatted input stream@@@\f3getspwent(3X)\f1 .\" index@\f4getspwuid()\f1 \- get secure password file entry matching \f4uid()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4getspwnam()\f1 \- get secure password file entry matching login name \f4name()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4setspwent()\f1 \- rewind pointer to beginning of secure password file@@@\f3getspwent(3X)\f1 .\" index@\f4endspwent()\f1 \- close currently open secure password file@@@\f3getspwent(3X)\f1 .\" index@entry from secure password file, get@@@\f3getspwent(3X)\f1 .\" index@secure password file, get entry from@@@\f3getspwent(3X)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspwent(3C)\f1 .\" .\" toc@\f3getspwent(3X)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f1,\n\f4endpwent()\f1, \f4fgetpwent()\f1@@@get secure password file entry .\" toc@\f4getpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4setpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4endpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4getspwaid()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" .\" links@getspwent.3x getspwuid.3x .\" links@getspwent.3x getspwnam.3x .\" links@getspwent.3x setspwent.3x .\" links@getspwent.3x endspwent.3x .\" links@getspwent.3x fgetspwent.3x .\" links@getspwent.3x getspwaid.3x .\" links@getspwent.3x getspwent_r.3x .\" links@getspwent.3x getspwuid_r.3x .\" links@getspwent.3x getspwaid_r.3x .\" links@getspwent.3x getspwnam_r.3x .\" links@getspwent.3x setspwent_r.3x .\" links@getspwent.3x endspwent_r.3x .\" links@getspwent.3x fgetspwent_.3x .\" .\" fileset_database@getspwent.3x PROGRAMING-MAN .\" $Header: getspwent.3x,v 72.6 94/11/30 10:11:44 ssa Exp $ .TA g .TH getspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getspwent(\|), getspwent_r(\|), getspwuid(\|), getspwuid_r(\|), getspwaid(\|), getspwaid_r(\|), getspwnam(\|), getspwnam_r(\|), setspwent(\|), setspwent_r(\|), endspwent(\|), endspwent_r(\|), fgetspwent(\|), fgetspwent_r(\|) \- get secure password file entry\c , on trusted systems .SH SYNOPSIS .C "#include " .PP .C "struct s_passwd *getspwent(void);" .PP .C "int getspwent_r(struct s_passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct s_passwd *getspwuid(uid_t uid);" .PP .PD 0 .C "int getspwuid_r(uid_t uid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwaid(aid_t aid);" .PP .PD 0 .C "int getspwaid_r(aid_t aid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwnam(const char *name);" .PP .PD 0 .C "int getspwnam_r(char *name, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setspwent(void);" .PP .C "void setspwent_r(FILE **pwfp);" .PP .C "void endspwent(void);" .PP .C "void endspwent_r(FILE **pwfp);" .PP .C "struct s_passwd *fgetspwent(\s-1FILE\s0 *stream);" .PP .PD 0 .C "int fgetspwent_r(FILE *f, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .SH DESCRIPTION These privileged routines provide access to the protected password database in a manner similar to the way .IR getpwent (3C) routines handle the regular password file, .RC ( \|/etc/passwd\| ). .PP These routines are particularly useful in situations where it is not necessary to get information from the regular password file. .IR getspwent (3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, .CR libsec . .PP Note that .CR getspwent () routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the .CR getprpwent () routines. See .IR getprpwent (3). .PP .CR getspwent (), .CR getspwuid (), .CR getspwaid (), and .CR getspwnam () each returns a pointer to an object of .CR s_passwd structure. The .CR s_passwd structure is maintained for compatibility with existing software and consists of five fields as follows: .nf .IP .C "struct\ s_passwd\ {" .C " char *pw_name; /* login name */" .C " char *pw_passwd; /* encrypted password */" .C " char *pw_age; /* password age */" .C " int pw_audid; /* audit ID */" .C " int pw_audflg; /* audit flag 1=on, 0=off */" .C }; .fi .PP Since the .CR s_passwd structure is declared in the .RC < pwd.h > header file, it is unnecessary to redeclare it. .PP To access other fields in the protected password database that are not included in the .CR s_passwd structure, use .CR getprpwent (). See .IR getprpwent (3) for more information. .PP .TP 20 .CR getspwent () When first called, .CR getspwent () returns a pointer to each .CR s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database. .TP .CR getspwuid () Searches for an entry that matches the specified .IR uid . It then returns a pointer to the particular structure in which .I uid is found. .TP .CR getspwaid () Similarly searches for a numerical audit ID matching .I aid and returns a pointer to the particular structure in which .I aid is found (see .IR spasswd (4) for details on this field). .TP .CR getspwnam () Searches for an entry that matches the specified .IR name . Returns a pointer to the particular structure in which .I name is found. .TP .CR setspwent () Resets the protected password database pointer to the beginning of the file to allow repeated searches. .TP .CR endspwent () Should be called to close the protected password database file when processing is complete. .TP .CR fgetspwent () Is no longer supported. It is provided for those applications that did not use .CR /.secure/etc/passwd . .SS Reentrant Interfaces .CR getspwuid_r (), .CR getspwaid_r (), .CR getspwnam_r (), and .CR fgetspwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .CR s_passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in the .CR s_passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getspwent_r () requires a pointer to a .RI ( "FILE *" ) variable. .CR setspwent_r () and .CR endspwent_r () are to be used only in conjunction with .CR getspwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setspwent_r () can be used to rewind or open the protected password database. .CR endspwent_r () should be called when done to close the file. .PP The .CR /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database. .PP .CR fgetspwent_r () is no longer supported, but is included for those users that did not use the .CR /.secure/etc/passwd file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getspwent_r () or .CR setspwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH RETURN VALUE .CR getspwent () returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the calling process is not zero. .PP .CR getspwent_r () returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned. .SH WARNINGS The above routines use .RC < stdio.h >, which causes them to increase the size of programs by more than might otherwise be expected. .PP Since all information for .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() is contained in a static area, it must be copied to be saved. .PP .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() are unsafe in multi-thread applications. .CR getspwent_r() , .CR getspwuid_r() , .CR getspwaid_r() , .CR getspwnam_r() , .CR setspwent_r() , .CR endspwent_r() , and .CR fgetspwent_r() are MT-Safe and should be used instead. .PP Network Information Service is not supported on trusted systems. .SH EXAMPLE The following code excerpt counts the number of entries in the protected password database: .nf .IP .C "int count = 0;" .C "struct s_passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setspwent_r(&pwf);" .C "while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endspwent_r(&pwf);" .SH AUTHOR .CR getspwent () was developed by HP. .SH FILES .TP 30 .C /tcb/files/auth/*/* Protected Password database .SH SEE ALSO ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), putspwent(3X), passwd(4). .\" .\" index@\f4getspwent()\f1 \- get next secure password file entry@@@\f3getspwent(3X)\f1 .\" index@\f4getspwaid()\f1 \- get next secure password file audit ID@@@\f3getspwent(3X)\f1 .\" index@\f4fgetspwent()\f1 \- get next entry in secure password-file-formatted input stream@@@\f3getspwent(3X)\f1 .\" index@\f4getspwuid()\f1 \- get secure password file entry matching \f4uid()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4getspwnam()\f1 \- get secure password file entry matching login name \f4name()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4setspwent()\f1 \- rewind pointer to beginning of secure password file@@@\f3getspwent(3X)\f1 .\" index@\f4endspwent()\f1 \- close currently open secure password file@@@\f3getspwent(3X)\f1 .\" index@entry from secure password file, get@@@\f3getspwent(3X)\f1 .\" index@secure password file, get entry from@@@\f3getspwent(3X)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspwent(3C)\f1 .\" .\" toc@\f3getspwent(3X)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f1,\n\f4endpwent()\f1, \f4fgetpwent()\f1@@@get secure password file entry .\" toc@\f4getpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4setpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4endpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4getspwaid()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" .\" links@getspwent.3x getspwuid.3x .\" links@getspwent.3x getspwnam.3x .\" links@getspwent.3x setspwent.3x .\" links@getspwent.3x endspwent.3x .\" links@getspwent.3x fgetspwent.3x .\" links@getspwent.3x getspwaid.3x .\" links@getspwent.3x getspwent_r.3x .\" links@getspwent.3x getspwuid_r.3x .\" links@getspwent.3x getspwaid_r.3x .\" links@getspwent.3x getspwnam_r.3x .\" links@getspwent.3x setspwent_r.3x .\" links@getspwent.3x endspwent_r.3x .\" links@getspwent.3x fgetspwent_.3x .\" .\" fileset_database@getspwent.3x PROGRAMING-MAN .\" $Header: getwc.3c,v 76.1 95/07/05 17:30:42 ssa Exp $ .TA g .TH getwc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getwc(\|), getwc_unlocked(\|), getwchar(\|), getwchar_unlocked(\|), fgetwc(\|), fgetwc_unlocked(\|) \- get a wide character from a stream file .SH SYNOPSIS .C "#include " .PP .C "wint_t getwc(FILE *stream);" .PP .C "wint_t getwc_unlocked(FILE *stream);" .PP .C "wint_t getwchar(void);" .PP .C "wint_t getwchar_unlocked(void);" .PP .C "wint_t fgetwc(FILE *stream);" .PP .C "wint_t fgetwc_unlocked(FILE *stream);" .SS Remarks: These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. They parallel the 8 bit character I/O functions defined in .IR getc(3S) . .SH DESCRIPTION .TP 15 .C getwc() Returns the next character from the named input .IR stream , converts that to the corresponding wide character and moves the file pointer ahead one character in .IR stream . .CR getwchar() is defined as .CR getwc(stdin) . .CR getwc() and .CR getwchar() are defined both as macros and as functions. .TP .C fgetwc() Behaves like .CR getwc() , but is a function rather than a macro. .PP Definitions for these functions, the types .CR wint_t , .CR wchar_t and the value .CR WEOF are provided in header file .RC < wchar.h >. .PP .CR getwc_unlocked() , .CR getwchar_unlocked() , and .CR fgetwc_unlocked() are identical to .CR getwc() , .CR getwchar() , and .CR fgetwc() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon successful completion, .CR getwc() , .CR getwc_unlocked() , .CR getwchar() , .CR getwchar_unlocked() , .CR fgetwc() , and .CR fgetwc_unlocked() return the next wide character read from .I stream .RC ( stdin for .CR getwchar() ) converted to a type .CR wint_t . If the stream is at end-of-file, the end-of-file indicator for the stream is set and .CR WEOF is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and .CR WEOF is returned. .PP .CR ferror() and .CR feof() can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR getwc() , .CR getwc_unlocked() , .CR getwchar() , .CR getwchar_unlocked() , .CR fgetwc() , and .CR fgetwc_unlocked() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP [EIO] A physical I/O error has occurred, or the process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .TP [EILSEQ] The data obtained from the input stream does not form a valid wide character. .RE .PP Additional .CR errno values may be set by the underlying .CR read() function (see .IR read (2)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS If the value returned by .CR getwc() , .CR getwchar() , .CR fgetwc() , or .CR fgetwc_unlocked() is stored into a type .CR wchar_t variable then compared against the constant .CR WEOF , the comparison may never succeed because extension of a .CR wchar_t to a .CR wint_t is machine-dependent. .SH AUTHOR .CR getwc() was developed by OSF and HP. .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), fread(3S), fgetws(3C), putwc(3C), read(2), scanf(3S). .SH STANDARDS CONFORMANCE .CR getwc() ": XPG4" .PP .CR fgetwc() ": XPG4" .PP .CR getwchar() ": XPG4" .\" .\" index@\f4getwc()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwc_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwchar()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwchar_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4fgetwc()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4fgetwc_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1get: wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1data, get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1wide character from a stream file, get@@@\f3getwc(3C)\f1 .\" index@\f1stream file, get wide character from a@@@\f3getwc(3C)\f1 .\" index@\f1file, stream: get wide character from a stream file@@@\f3getwc(3C)\f1 .\" .\" toc@\f3getwc(3C)\f1:\0\0\f4getwc()\f1, \f4getwc_unlocked()\f1, \f4getwchar()\f1, \f4getwchar_unlocked\f1, \f4fgetwc()\f1, \n\f4fgetwc_unlocked()\f1@@@get wide character from a stream file .\" toc@\f4getwc()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwc_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwchar()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwchar_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4fgetwc()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4fgetwc_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" .\" links@getwc.3c getwc_unloc.3c .\" links@getwc.3c getwchar_un.3c .\" links@getwc.3c getwchar.3c .\" links@getwc.3c fgetwc.3c .\" links@getwc.3c fgetwc_unlo.3c .\" .\" fileset_database@getwc.3c PROGRAMING-MAN .\" $Header: getwc.3c,v 76.1 95/07/05 17:30:42 ssa Exp $ .TA g .TH getwc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getwc(\|), getwc_unlocked(\|), getwchar(\|), getwchar_unlocked(\|), fgetwc(\|), fgetwc_unlocked(\|) \- get a wide character from a stream file .SH SYNOPSIS .C "#include " .PP .C "wint_t getwc(FILE *stream);" .PP .C "wint_t getwc_unlocked(FILE *stream);" .PP .C "wint_t getwchar(void);" .PP .C "wint_t getwchar_unlocked(void);" .PP .C "wint_t fgetwc(FILE *stream);" .PP .C "wint_t fgetwc_unlocked(FILE *stream);" .SS Remarks: These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. They parallel the 8 bit character I/O functions defined in .IR getc(3S) . .SH DESCRIPTION .TP 15 .C getwc() Returns the next character from the named input .IR stream , converts that to the corresponding wide character and moves the file pointer ahead one character in .IR stream . .CR getwchar() is defined as .CR getwc(stdin) . .CR getwc() and .CR getwchar() are defined both as macros and as functions. .TP .C fgetwc() Behaves like .CR getwc() , but is a function rather than a macro. .PP Definitions for these functions, the types .CR wint_t , .CR wchar_t and the value .CR WEOF are provided in header file .RC < wchar.h >. .PP .CR getwc_unlocked() , .CR getwchar_unlocked() , and .CR fgetwc_unlocked() are identical to .CR getwc() , .CR getwchar() , and .CR fgetwc() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon successful completion, .CR getwc() , .CR getwc_unlocked() , .CR getwchar() , .CR getwchar_unlocked() , .CR fgetwc() , and .CR fgetwc_unlocked() return the next wide character read from .I stream .RC ( stdin for .CR getwchar() ) converted to a type .CR wint_t . If the stream is at end-of-file, the end-of-file indicator for the stream is set and .CR WEOF is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and .CR WEOF is returned. .PP .CR ferror() and .CR feof() can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR getwc() , .CR getwc_unlocked() , .CR getwchar() , .CR getwchar_unlocked() , .CR fgetwc() , and .CR fgetwc_unlocked() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP [EIO] A physical I/O error has occurred, or the process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .TP [EILSEQ] The data obtained from the input stream does not form a valid wide character. .RE .PP Additional .CR errno values may be set by the underlying .CR read() function (see .IR read (2)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS If the value returned by .CR getwc() , .CR getwchar() , .CR fgetwc() , or .CR fgetwc_unlocked() is stored into a type .CR wchar_t variable then compared against the constant .CR WEOF , the comparison may never succeed because extension of a .CR wchar_t to a .CR wint_t is machine-dependent. .SH AUTHOR .CR getwc() was developed by OSF and HP. .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), fread(3S), fgetws(3C), putwc(3C), read(2), scanf(3S). .SH STANDARDS CONFORMANCE .CR getwc() ": XPG4" .PP .CR fgetwc() ": XPG4" .PP .CR getwchar() ": XPG4" .\" .\" index@\f4getwc()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwc_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwchar()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwchar_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4fgetwc()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4fgetwc_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1get: wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1data, get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1wide character from a stream file, get@@@\f3getwc(3C)\f1 .\" index@\f1stream file, get wide character from a@@@\f3getwc(3C)\f1 .\" index@\f1file, stream: get wide character from a stream file@@@\f3getwc(3C)\f1 .\" .\" toc@\f3getwc(3C)\f1:\0\0\f4getwc()\f1, \f4getwc_unlocked()\f1, \f4getwchar()\f1, \f4getwchar_unlocked\f1, \f4fgetwc()\f1, \n\f4fgetwc_unlocked()\f1@@@get wide character from a stream file .\" toc@\f4getwc()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwc_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwchar()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwchar_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4fgetwc()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4fgetwc_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" .\" links@getwc.3c getwc_unloc.3c .\" links@getwc.3c getwchar_un.3c .\" links@getwc.3c getwchar.3c .\" links@getwc.3c fgetwc.3c .\" links@getwc.3c fgetwc_unlo.3c .\" .\" fileset_database@getwc.3c PROGRAMING-MAN .\" $Header: fgetws.3c,v 72.6 94/10/13 20:02:34 ssa Exp $ .TA f .TH fgetws 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetws(\|), fgetws_unlocked(\|) \- get a wide character string from a stream file .SH SYNOPSIS .C "#include " .PP .C "wchar_t *fgetws(wchar_t *ws, int n, FILE *stream);" .PP .C "wchar_t *fgetws_unlocked(wchar_t *ws, int n, FILE *stream);" .SS Remarks: .CR fgetws() is compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. It parallels the 8-bit character I/O function defined in .IR gets(3S) . .SH DESCRIPTION .TP 15 .C fgetws() Reads characters from the .IR stream , converts them into corresponding wide characters, and places them into the array pointed to by .IR ws , until .I n \(mi 1 characters are read, a new-line character is read and transferred to .IR ws , or an end-of-file condition is encountered. The wide string is then terminated with a null wide character. .PP The definition for this functions and the type .CR wchar_t are provided in the .RC < wchar.h > header. .PP .CR fgetws_unlocked() is identical to .CR fgetws() except it does not perform any internal locking of the .I stream for multi-thread applications. .CR fgetws_unlocked can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE Upon successful completion, .CR fgetws() and .CR fgetws_unlocked() return .IR ws . If the stream is at end-of-file, the end-of-file indicator for the stream is set and a null pointer is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and a null pointer is returned. .PP .CR ferror() and .CR feof() can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR fgetws() and .CR fgetws_unlocked() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP [EIO] The process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .TP [EILSEQ] The data obtained from the input stream do not form a valid wide character string. .RE .PP Additional .CR errno values can be set by the underlying .CR read() function (see .IR read (2)). .SH AUTHOR .CR fgetws() was developed by OSF and HP. .SH SEE ALSO ferror(3S), flockfile(3S), fopen(3S), fread(3S), getwc(3C), putws(3C), scanf(3S). .SH STANDARDS COMPLIANCE .CR fgetws() ": XPG4" .\" .\" index@\f4fgetws()\f1 \- get a wide string from a stream file@@@\f3fgetws(3C)\f1 .\" index@input wide string from a stream file@@@\f3fgetws(3C)\f1 .\" index@wide string from a stream file, input@@@\f3fgetws(3C)\f1 .\" index@stream file, input wide string from a@@@\f3fgetws(3C)\f1 .\" .\" toc@\f3fgetws(3C)\f1:\0\0\f4fgetws()\f1@@@get a wide string from a stream .\" .\" links@fgetws.3c fgetws_unlo.3c .\" .\" fileset_database@fgetws.3c PROGRAMING-MAN .\" $Header: fgetws.3c,v 72.6 94/10/13 20:02:34 ssa Exp $ .TA f .TH fgetws 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetws(\|), fgetws_unlocked(\|) \- get a wide character string from a stream file .SH SYNOPSIS .C "#include " .PP .C "wchar_t *fgetws(wchar_t *ws, int n, FILE *stream);" .PP .C "wchar_t *fgetws_unlocked(wchar_t *ws, int n, FILE *stream);" .SS Remarks: .CR fgetws() is compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. It parallels the 8-bit character I/O function defined in .IR gets(3S) . .SH DESCRIPTION .TP 15 .C fgetws() Reads characters from the .IR stream , converts them into corresponding wide characters, and places them into the array pointed to by .IR ws , until .I n \(mi 1 characters are read, a new-line character is read and transferred to .IR ws , or an end-of-file condition is encountered. The wide string is then terminated with a null wide character. .PP The definition for this functions and the type .CR wchar_t are provided in the .RC < wchar.h > header. .PP .CR fgetws_unlocked() is identical to .CR fgetws() except it does not perform any internal locking of the .I stream for multi-thread applications. .CR fgetws_unlocked can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE Upon successful completion, .CR fgetws() and .CR fgetws_unlocked() return .IR ws . If the stream is at end-of-file, the end-of-file indicator for the stream is set and a null pointer is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and a null pointer is returned. .PP .CR ferror() and .CR feof() can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR fgetws() and .CR fgetws_unlocked() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP [EIO] The process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .TP [EILSEQ] The data obtained from the input stream do not form a valid wide character string. .RE .PP Additional .CR errno values can be set by the underlying .CR read() function (see .IR read (2)). .SH AUTHOR .CR fgetws() was developed by OSF and HP. .SH SEE ALSO ferror(3S), flockfile(3S), fopen(3S), fread(3S), getwc(3C), putws(3C), scanf(3S). .SH STANDARDS COMPLIANCE .CR fgetws() ": XPG4" .\" .\" index@\f4fgetws()\f1 \- get a wide string from a stream file@@@\f3fgetws(3C)\f1 .\" index@input wide string from a stream file@@@\f3fgetws(3C)\f1 .\" index@wide string from a stream file, input@@@\f3fgetws(3C)\f1 .\" index@stream file, input wide string from a@@@\f3fgetws(3C)\f1 .\" .\" toc@\f3fgetws(3C)\f1:\0\0\f4fgetws()\f1@@@get a wide string from a stream .\" .\" links@fgetws.3c fgetws_unlo.3c .\" .\" fileset_database@fgetws.3c PROGRAMING-MAN .\" $Header: fileno.3s,v 72.5 94/11/14 15:28:23 ssa Exp $ .TA f .TH fileno 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fileno(\|), fileno_unlocked(\|) \- map stream pointer to file descriptor .SH SYNOPSIS .C "#include " .PP .C "int fileno(FILE *stream);" .PP .C "int fileno_unlocked(FILE *stream);" .SH DESCRIPTION .CR fileno() returns the integer file descriptor associated with the named .IR stream ; see .IR open (2). .PP The following symbolic values in .RC < unistd.h > define the file descriptors associated with .CR stdin , .CR stdout , and .CR stderr when a program is started : .RS .TP 20 .CR STDIN_FILENO Value of zero for standard input, .CR stdin . .PD 0 .TP .CR STDOUT_FILENO Value of 1 for standard output, .CR stdout . .TP .CR STDERR_FILENO Value of 2 for standard error, .CR stderr . .RE .PD .PP .CR fileno_unlocked is identical to .CR fileno except it does not perform any internal locking of the .I stream for multi-thread applications. .CR fileno_unlocked can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon error, .CR fileno() " and " fileno_unlocked() return \-1. .SH SEE ALSO open(2), flockfile(3S), fopen(3S). .SH STANDARDS CONFORMANCE .CR fileno() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4fileno()\f1 \- map stream pointer to file descriptor@@@\f3fileno(3S)\f1 .\" index@map stream pointer to file descriptor@@@\f3fileno(3S)\f1 .\" index@descriptor, map stream pointer to file@@@\f3fileno(3S)\f1 .\" index@file descriptor, map stream pointer to@@@\f3fileno(3S)\f1 .\" index@stream pointer, map to file descriptor@@@\f3fileno(3S)\f1 .\" index@pointer, stream, map to file descriptor@@@\f3fileno(3S)\f1 .\" .\" toc@\f3fileno(3S)\f1:\0\0\f4fileno()\f1@@@map stream pointer to file descriptor .\" $Header: filter.3x,v 76.2 95/07/31 17:49:10 ssa Exp $ .TA f .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH filter 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME filter \(em disable use of certain terminal capabilities .SH SYNOPSIS .C "#include " .P .C "void filter(void);" .SH DESCRIPTION The .Fn filter function changes the algorithm for initialising terminal capabilities that assume that the terminal has more than one line. A subsequent call to .Fn initscr or .Fn newterm performs the following additional actions: .RS .TP 3 \(bu Disable use of .CR clear , .CR cud , .CR cud1 , .CR cup , .CR cuu1 and .CR vpa. .TP 3 \(bu Set the value of the .CR home string to the value of the .CR cr string .TP 3 \(bu Set .CR lines equal to 1. .RE .PP Any call to .Fn filter must precede the call to .Fn initscr or .CR newterm() . .SH "RETURN VALUE" The .Fn filter function does not return a value. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Defined Capabilities\f1 in terminfo(4), initscr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4filter()\f1 \- disable use of certain terminal capabilities@@@\f3filter(3X)\f1 .\" index@\f1disable use of certain terminal capabilities@@@\f3filter(3X)\f1 .\" index@\f1use, disable, of certain terminal capabilities@@@\f3filter(3X)\f1 .\" index@\f1terminal capabilities, disable use of@@@\f3filter(3X)\f1 .\" .\" toc@\f3filter(3X)\f1:\0\0\f4filter()\f1@@@disable the use of certain terminal capabilities .\" .\" fileset_database@filter.3x CURS-ENG-A-MAN .\" $Header: finite.3m,v 78.1 96/02/13 10:44:31 ssa Exp $ .TA f .TH finite 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME finite(\|), finitef(\|) \- finite functions .SH SYNOPSIS .C "#include " .PP .C "int finite(double x);" .PP .C "int finitef(float x);" .SH DESCRIPTION The .CR finite() function is recommended by the IEEE-754 standard for floating-point arithmetic. .PP .CR finite() returns .CR 1 only when \(miINFINITY .RI < \0x\0 < +INFINITY. Otherwise, it returns .CR 0 (that is, when .I x .ift is \(+-INFINITY or .ifn is +\-INFINITY or .I x is NaN). .PP .CR finitef() is a .CR float version of .CR finite() ; it takes a .CR float argument. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR finitef() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH SEE ALSO fpclassify(3M), isinf(3M), isnan(3M), remainder(3M), scalb(3M). .\" .\" index@\f4finite()\f1 \- finite functions@@@\f3finite(3M)\f1 .\" index@\f4finitef()\f1 \- finite functions (float version)@@@\f3finite(3M)\f1 .\" index@\f1math: finite functions@@@\f3finite(3M)\f1 .\" index@\f1finite functions@@@\f3finite(3M)\f1 .\" index@\f1floating-point classification functions@@@\f3finite(3M)\f1 .\" .\" toc@\f3finite(3M)\f1:\0\0\f4finite()\f1, \f4finitef()\f1@@@finite functions\f1 .\" toc@\f4finitef()\f1:\0\0finite functions (float version)@@@\f1see \f3finite(3M)\f1 .\" .\" links@finite.3m finitef.3m .\" $Header: finite.3m,v 78.1 96/02/13 10:44:31 ssa Exp $ .TA f .TH finite 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME finite(\|), finitef(\|) \- finite functions .SH SYNOPSIS .C "#include " .PP .C "int finite(double x);" .PP .C "int finitef(float x);" .SH DESCRIPTION The .CR finite() function is recommended by the IEEE-754 standard for floating-point arithmetic. .PP .CR finite() returns .CR 1 only when \(miINFINITY .RI < \0x\0 < +INFINITY. Otherwise, it returns .CR 0 (that is, when .I x .ift is \(+-INFINITY or .ifn is +\-INFINITY or .I x is NaN). .PP .CR finitef() is a .CR float version of .CR finite() ; it takes a .CR float argument. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR finitef() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH SEE ALSO fpclassify(3M), isinf(3M), isnan(3M), remainder(3M), scalb(3M). .\" .\" index@\f4finite()\f1 \- finite functions@@@\f3finite(3M)\f1 .\" index@\f4finitef()\f1 \- finite functions (float version)@@@\f3finite(3M)\f1 .\" index@\f1math: finite functions@@@\f3finite(3M)\f1 .\" index@\f1finite functions@@@\f3finite(3M)\f1 .\" index@\f1floating-point classification functions@@@\f3finite(3M)\f1 .\" .\" toc@\f3finite(3M)\f1:\0\0\f4finite()\f1, \f4finitef()\f1@@@finite functions\f1 .\" toc@\f4finitef()\f1:\0\0finite functions (float version)@@@\f1see \f3finite(3M)\f1 .\" .\" links@finite.3m finitef.3m .\" $Header: dbm.3x,v 76.1 95/07/05 17:27:37 ssa Exp $ .TA d .TH dbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbminit, fetch, store, delete, firstkey, nextkey, dbmclose \- database subroutines .SH SYNOPSIS .C "#include " .P .C "int dbminit(const char *file);" .P .C "datum fetch(datum key);" .P .C "int store(datum key, datum content);" .P .C "int delete(datum key);" .P .C "datum firstkey(void);" .P .C "datum nextkey(datum key);" .P .C "int dbmclose(void);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can locate a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .I dptr. Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbminit . At the time of this call, the files .IC file .dir and .IC file .pag must exist. (An empty database is created by creating zero-length .C .dir and .C .pag files.) .PP Once open, data stored under a key is accessed by .IC fetch , and data is placed under a key by .IC store . Storing data on an existing key replaces the existing data. A key (and its associated contents) is deleted by .CR delete . A linear pass through all keys in a database can be made, in (apparently) random order by using .C firstkey and .CR nextkey . .C firstkey returns the first key in the database. With any key, .C nextkey returns the next key in the database. The following code can be used to traverse the database: .IP .C "for (key = firstkey(); key.dptr != NULL; key = nextkey(key))" .PP A database can be closed by calling .C dbmclose. A currently open database must be closed before opening a new one. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .IR dptr . .SH WARNINGS The .I dbm functions provided in this library should not be confused in any way with those of a general-purpose database management system such as .SM ALLBASE/HP-UX SQL. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful data base functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C store returns an error if a disk block fills with inseparable data. .PP .C delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C firstkey and .C nextkey depends on a hashing function, not on anything interesting. .PP A .C store or .C delete during a pass through the keys by .C firstkey and .C nextkey may yield unexpected results. .SH AUTHOR .IR dbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO ndbm(3X). .\" index@\f4dbminit()\fP \- open a single database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4fetch()\fP \- access data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4store()\fP \- store data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4delete()\fP \- delete key and data under it (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4firstkey()\fP \- get first key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4nextkey()\fP \- get next key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4dbmclose()\fP \- close currently open database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@database subroutines (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" index@subroutines, database (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" .\" toc@\f3dbm(3X)\f1:\0\0\f4dbminit()\fP, \f4fetch()\fP, \f4store()\fP, \f4delete()\fP, \f4firstkey()\fP,\n\f4nextkey()\fP, \f4dbmclose()\fP@@@database subroutines .\" toc@\f4dbminit()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4fetch()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4store()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4delete()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4firstkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4nextkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4dbmclose()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" .\" links@dbm.3x dbminit.3x .\" links@dbm.3x fetch.3x .\" links@dbm.3x store.3x .\" links@dbm.3x delete.3x .\" links@dbm.3x firstkey.3x .\" links@dbm.3x nextkey.3x .\" links@dbm.3x dbmclose.3x .\" .\" fileset_database@dbm.3x PROGRAMING-MAN .\" $Header: nl_tools_16.3x,v 72.2 94/11/30 15:24:00 ssa Exp $ .TA n .TH nl_tools_16 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl_tools_16: ADVANCE(), byte_status(), BYTE_STATUS(), CHARADV(), CHARAT(), c_colwidth(), C_COLWIDTH(), firstof2(), FIRSTof2(), secof2(), SECof2(), WCHAR(), WCHARADV() \- tools to process 16-bit characters .SH SYNOPSIS .C "#include " .PP .C "int firstof2(int c);" .PP .C "int secof2(int c);" .PP .C "int byte_status(int c, int laststatus);" .PP .C int c_colwidth(int c); .PP .C "int FIRSTof2(int c);" .PP .C "int SECof2(int c);" .PP .C "int BYTE_STATUS(int c, int laststatus);" .PP .C "int C_COLWIDTH(int c);" .PP .C "int CHARAT(const char *p);" .PP .C "int ADVANCE(const char *p);" .PP .C "int CHARADV(const char *p);" .PP .C "int WCHAR(wchar_t wc, char *p);" .PP .C "int WCHARADV(wchar_t wc, char *p);" .PP .C "void PCHAR(int c, char *p);" .PP .C "void PCHARADV(int c, char *p);" .SS Remarks All interfaces listed above whose names begin with a capital letter are implemented as macros; the others are functions. .PP These macros and functions are obsolete. See WARNINGS. .SH DESCRIPTION The following macros and functions perform their operations based upon the loaded NLS environment (see .IR setlocale (3C)). .TP 20 .CR FIRSTof2() Takes a byte and returns a nonzero value if it can be the first byte of a two-byte character according to the NLS environment loaded, and zero if it cannot. .TP .CR SECof2() Takes a byte and returns a nonzero value if it can be the second byte of a two-byte character according to the loaded NLS environment, and zero if it cannot. .TP .CR BYTE_STATUS() Returns one of the following values based on the value of the current byte in .I c and the status of the previous byte interpreted in .I laststatus as returned by the last call to .CR BYTE_STATUS() . These are the status values as defined in .CR : .RS .RS .TP 15 .CR ONEBYTE Single-byte character .PD 0 .TP .CR SECOF2 Second byte of two-byte character .TP .CR FIRSTOF2 First byte of two-byte character .RE .RE .PD .IP To validate a two-byte character, both the first and second bytes must be valid. If the value of .I laststatus is .CR FIRSTOF2 but .CR SECof2( c ) returns false, .CI BYTE_STATUS( c , \ laststatus ) returns .CR ONEBYTE . .TP .CR C_COLWIDTH() Takes a byte which is assumed to be either a one-byte character or the first byte of a two-byte character, and returns the number of columns the character would occupy on a terminal display. .IP For the macros .CR BYTE_STATUS() , .CR C_COLWIDTH() , .CR FIRSTof2() , and .CR SEC0of2() , results are undefined for values of .I c less than \(mi1 (EOF) or greater than 255. .TP .CR CHARAT() Takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case, .CR CHARAT() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p . .TP .CR ADVANCE() Advances its pointer argument by the byte width of the character it is pointing at (either one or two bytes). .TP .CR CHARADV() Combines the functions of .CR CHARAT() and .CR ADVANCE() in a single macro. It takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case .CR CHARADV() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p , and advances .I p beyond the last byte of the character. .TP .CR WCHAR() Converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p . .CR WCHAR() returns the .CR wchar_t value .IR wc . .TP .CR WCHARADV() Combines the functions of .CR WCHAR() and .CR ADVANCE() in a single macro. It converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p , then advances .I p past the last byte. .CR WCHARADV() returns the .CR wchar_t value .IR wc . .TP .CR firstof2() .PD 0 .TP .CR secof2() .TP .CR byte_status() .TP .CR c_colwidth() .PD Subroutine versions of the corresponding macros. These functions can be called from languages other than C. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of single and/or multibyte characters. .SH WARNINGS The HP proprietary functions and macros described in this manual entry are .BR OBSOLETE . They are not portable to other vendor's systems, and will not be provided in future HP-UX releases. .PP For maximum portability, use the routines documented in the .IR multibyte (3C) manual entry for multibyte character processing. .PP Other macros listed in this manual entry cannot be used as the first argument to .CR WCHAR() or .CR WCHARADV() . For example, .IP .C "*t++ = *f++" .PP cannot be replaced by .IP .C "WCHARADV(CHARADV (f),t)" .PP Instead, use a method such as .IP .CR "int c; " ...\& " c = CHARADV (f)," .CR "WCHARADV (c,t)" .PP .CR WCHAR() and .CR WCHARADV() may produce a "null effect" warning from .IR lint (1) if not used as part of another expression or as part of a statement. This does not affect the functionality of either macro. .PP Note that .CR WCHAR() and .CR WCHARADV() are not "replace_char" macros. They do not prevent the second byte of a two-byte character from being left dangling if .CR WCHAR() or .CR WCHARADV() overwrite the first byte of the two-byte character with a single-byte character. .PP .CR CHARAT() , .CR ADVANCE() , and .CR CHARADV() do not examine the byte following the location pointed to by the argument to verify its validity as a .CR SECof2 byte. .SH AUTHOR .CR nl_tools_16() was developed by HP. .SH SEE ALSO setlocale(3C), multibyte(3C), wconv(3X), wctype(3X), hpnls(5). .\" .\" index@\f4ADVANCE()\f1 \- advance pointer to next 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARADV()\f1 \- get character and advance pointer to next character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARAT()\f1 \- get value of 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHAR()\f1, \- put 8- or 16-bit character in memory@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHARADV()\f1, \- put character in memory and advance pointer@@@\f3nl_tools_16(3X)\f1 .\" index@\f4byte_status()\f1, \f4BYTE_STATUS()\f1 \- test for valid 1- or 2-byte character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4firstof2()\f1, \f4FIRSTof2()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4secof2()\f1, \f4SECof2()\f1 \- test for valid second byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f1characters, tools to process 16-bit@@@\f3nl_tools_16(3X)\f1 .\" index@\f1process 16-bit characters, tools to@@@\f3nl_tools_16(3X)\f1 .\" index@\f1sixteen-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f116-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f1tools to process 16-bit characters@@@\f3nl_tools_16(3X)\f1 .\" .\" links@nl_tools_16.3x ADVANCE.3x .\" links@nl_tools_16.3x BYTE_STATUS.3x .\" links@nl_tools_16.3x CHARADV.3x .\" links@nl_tools_16.3x CHARAT.3x .\" links@nl_tools_16.3x FIRSTof2.3x .\" links@nl_tools_16.3x SECof2.3x .\" links@nl_tools_16.3x WCHAR.3x .\" links@nl_tools_16.3x WCHARADV.3x .\" links@nl_tools_16.3x byte_status.3x .\" links@nl_tools_16.3x c_colwidth.3x .\" links@nl_tools_16.3x firstof2.3x .\" links@nl_tools_16.3x secof2.3x .\" .\" toc@\f3nl_tools_16(3X)\f1:\0\0\f4ADVANCE()\f1, \f4byte_status()\f1, \f4BYTE_STATUS()\f1, \f4CHARADV()\f1,\n\f4CHARAT()\f1, \f4C_COLWIDTH()\f1, \f4c_colwidth()\f1, \f4firstof2()\f1, \f4FIRSTof2()\f1,\n\f4secof2()\f1, \f4SECof2()\f1, \f4WCHAR()\f1, \f4WCHARADV()\f1@@@tools to process 16-bit characters .\" toc@\f4ADVANCE()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4byte_status()\f1, \f4BYTE_STATUS()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARAT()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4firstof2()\f1, \f4FIRSTof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4secof2()\f1, \f4SECof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHAR()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" $Header: flash.3x,v 76.2 95/07/31 17:50:14 ssa Exp $ .TA f .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH flash 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME flash \(em flash the screen .SH SYNOPSIS .C "#include " .P .C "int flash(void);" .SH DESCRIPTION The .Fn flash function alerts the user. It flashes the screen, or if that is not possible, it sounds the audible alarm on the terminal. If neither signal is possible, nothing happens. .SH "RETURN VALUE" The .Fn flash function always returns OK. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Nearly all terminals have an audible alarm, but only some can flash the screen. .SH "SEE ALSO" beep(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .P In previous issues, this function was included in the entry for .CR beep() . It is moved to its own entry in X/Open Curses, Issue 4, the argument list is explicitly declared as \f3void\fP, and the .B "RETURN VALUE" section is changed to indicate that the function always returns OK. .\" .\" index@\f4flash()\f1 \- flash the screen@@@\f3flash(3X)\f1 .\" index@\f1flash the screen@@@\f3flash(3X)\f1 .\" index@\f1screen: flash the screen@@@\f3flash(3X)\f1 .\" .\" toc@\f3flash(3X)\f1:\0\0\f4flash()\f1@@@flash the screen .\" .\" fileset_database@flash.3x CURS-ENG-A-MAN .\" $Header: flockfile.3s,v 76.1 95/06/20 14:45:01 ssa Exp $ .TA f .TH flockfile 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME flockfile(\|), funlockfile(\|) \- explicit locking of streams within a multi-thread application .SH SYNOPSIS .C "#include " .PP .C "void flockfile(FILE *stream);" .PP .C "void funlockfile(FILE *stream);" .SH DESCRIPTION The .CR flockfile() and .CR funlockfile() functions provide for explicit application-level locking of streams. These functions can be used by a thread to delineate a sequence of I/O statements that are to be executed as a unit. .PP The .CR flockfile() function is used by a thread to advise the implementation that it is the current owner of a stream. .PP The .CR funlock() function is used to relinquish the ownership granted to the thread. The behavior is undefined if a thread other than the current owner calls the .CR funlockfile() function. .PP Logically, there is a count associated with each stream. This count is implicitly initialized to zero when the stream is created. The stream is unlocked when the count is zero. When the count is positive, a single thread owns the stream. When the .CR flockfile() function is called, if the count is zero or if the count is positive and the caller owns the stream, the count is incremented. Otherwise, the calling thread is suspended, waiting for the count to return to zero. Each call to .CR funlockfile() decrements the count. This allows matching calls to .CR flockfile() and .CR funlockfile() to be nested. .SH RETURN VALUE None. .\" .\" toc@\f3flockfile(3S)\f1:\0\0\f4flockfile\f1, \f4funflockfile\f1@@@explicit locking of streams within a multi-thread application .\" toc@\f4funflockfile\f1:\0\0explicit locking of streams within a multi-thread application@@@see \f3flockfile(3S)\f1 .\" .\" index@\f4flockfile()\f1, \f4funflockfile\f1 \- explicit locking of streams within a multi-thread application@@@\f3flockfile(3S)\f1 .\" index@\f4funflockfile()\f1, \f4flockfile\f1 \- explicit locking of streams within a multi-thread application@@@\f3flockfile(3S)\f1 .\" .\" index@explicit locking of streams within a multi-thread application@@@\f3flockfile(3S)\f1 .\" index@locking of streams within a multi-thread application, explicit@@@\f3flockfile(3S)\f1 .\" index@streams within a multi-thread application, explicit locking of@@@\f3flockfile(3S)\f1 .\" index@multi-thread application, explicit locking of streams within a@@@\f3flockfile(3S)\f1 .\" index@application, explicit locking of streams within a multi-thread@@@\f3flockfile(3S)\f1 .\" .\" links@flockfile.3s funlockfile.3s .\" $Header: floor.3m,v 78.1 96/02/13 10:44:51 ssa Exp $ .TA f .TH floor 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME floor(\|) \- floor function .SH SYNOPSIS .C "#include " .PP .C "double floor(double x);" .SH DESCRIPTION .CR floor() returns the largest integer (represented as a double-precision number) not greater than .IR x . .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x .ift is \(+-INFINITY or \(+-zero, .ifn is +\-INFINITY or +\-zero, .CR floor() returns .IR x . .PP If .I x is NaN, .CR floor() returns NaN. .PP If the correct value would overflow, .CR floor() returns .CR \(miHUGE_VAL and sets .CR errno to [ERANGE]. .SH ERRORS If .CR floor() fails, .CR errno is set to the following value. .RS .TP 12 [ERANGE] The correct value would overflow. .RE .SH SEE ALSO ceil(3M), fmod(3M), fabs(3M), rint(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR floor() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4floor()\fP \- floor function@@@\f3floor(3M)\f1 .\" index@math: floor function@@@\f3floor(3M)\f1 .\" index@floor function@@@\f3floor(3M)\f1 .\" .\" toc@\f3floor(3M)\f1:\0\0\f4floor()\fP@@@floor function .\" .\" .\" fileset_database@floor.3m PROGRAMING-MAN .\" $Header: flushinp.3x,v 76.2 95/08/01 09:56:34 ssa Exp $ .TA f .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH flushinp 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME flushinp \(em discard input .SH SYNOPSIS .C "#include " .P .C "int flushinp(void);" .SH DESCRIPTION The .Fn flushinp function discards (flushes) any characters in the input buffer associated with the current screen. .SH "RETURN VALUE" The .Fn flushinp function always returns OK. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn flushinp function is explicitly declared as \f3void\f1. .\" .\" index@\f4flushinp()\f1 \- discard input@@@\f3flushinp(3X)\f1 .\" index@\f1discard input@@@\f3flushinp(3X)\f1 .\" index@\f1input, discard@@@\f3flushinp(3X)\f1 .\" .\" toc@\f3flushinp(3X)\f1:\0\0\f4flushinp()\f1@@@discard input .\" .\" fileset_database@flushinp.3x CURS-ENG-A-MAN .\" $Header: fmod.3m,v 78.1 96/02/13 10:45:11 ssa Exp $ .TA f .TH fmod 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fmod(\|), fmodf(\|) \- remainder functions .SH SYNOPSIS .C "#include " .PP .C "double fmod(double x, double y);" .PP .C "float fmodf(float x, float y);" .SH DESCRIPTION The .CR fmod() function returns the floating-point remainder .RI ( \|f\| ) of the division of .I x by .IR y , where .I f has the same sign as .IR x , such that .IR x \|=\| iy \|+\| f for some integer .IR i , and .RI | f "| < |" y |. .PP .CR fmodf() is a .CR float version of .CR fmod() ; it takes .CR float arguments and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float arguments to .CR double , and the function returns incorrect results. .PP .CR fmodf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I y .ift is \(+-INFINITY and .ifn is +\-INFINITY and .I x .ift is not \(+-INFINITY, .ifn is not +\-INFINITY, .CR fmod() returns .IR x . .PP If .I x .ift is \(+-zero and .ifn is +\-zero and .I y is nonzero, .CR fmod() returns .IR x . .PP If .I x or .I y is NaN, .CR fmod() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR fmod() returns zero. .PP If .I y is zero, .CR fmod() returns NaN and sets .CR errno to [EDOM]. .PP If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR fmod() returns NaN and sets .CR errno to [EDOM]. .SH ERRORS If .CR fmod() fails, .CR errno is set to one of the following values. .RS .TP 20 [EDOM] .I y is zero. .TP 20 [EDOM] .I x .ift is \(+-INFINITY. .ifn is +\-INFINITY. .RE .SH SEE ALSO ceil(3M), fabs(3M), floor(3M), isinf(3M), isnan(3M), remainder(3M), rint(3M), values(5). .SH STANDARDS CONFORMANCE .CR fmod() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4fmod()\f1 \- remainder functions@@@\f3fmod(3M)\f1 .\" index@\f4fmodf()\f1 \- remainder functions@@@\f3fmod(3M)\f1 .\" index@\f1math: remainder functions@@@\f3fmod(3M)\f1 .\" index@\f1remainder functions@@@\f3fmod(3M)\f1 .\" .\" toc@\f3fmod(3M)\f1:\0\0\f4fmod()\f1, \f4fmodf()\f1@@@remainder functions\f1 .\" toc@\f4fmodf()\f1:\0\0remainder function (float version)@@@see \f3fmod(3M)\f1 .\" .\" links@fmod.3m fmodf.3m .\" $Header: fmod.3m,v 78.1 96/02/13 10:45:11 ssa Exp $ .TA f .TH fmod 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fmod(\|), fmodf(\|) \- remainder functions .SH SYNOPSIS .C "#include " .PP .C "double fmod(double x, double y);" .PP .C "float fmodf(float x, float y);" .SH DESCRIPTION The .CR fmod() function returns the floating-point remainder .RI ( \|f\| ) of the division of .I x by .IR y , where .I f has the same sign as .IR x , such that .IR x \|=\| iy \|+\| f for some integer .IR i , and .RI | f "| < |" y |. .PP .CR fmodf() is a .CR float version of .CR fmod() ; it takes .CR float arguments and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float arguments to .CR double , and the function returns incorrect results. .PP .CR fmodf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I y .ift is \(+-INFINITY and .ifn is +\-INFINITY and .I x .ift is not \(+-INFINITY, .ifn is not +\-INFINITY, .CR fmod() returns .IR x . .PP If .I x .ift is \(+-zero and .ifn is +\-zero and .I y is nonzero, .CR fmod() returns .IR x . .PP If .I x or .I y is NaN, .CR fmod() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR fmod() returns zero. .PP If .I y is zero, .CR fmod() returns NaN and sets .CR errno to [EDOM]. .PP If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR fmod() returns NaN and sets .CR errno to [EDOM]. .SH ERRORS If .CR fmod() fails, .CR errno is set to one of the following values. .RS .TP 20 [EDOM] .I y is zero. .TP 20 [EDOM] .I x .ift is \(+-INFINITY. .ifn is +\-INFINITY. .RE .SH SEE ALSO ceil(3M), fabs(3M), floor(3M), isinf(3M), isnan(3M), remainder(3M), rint(3M), values(5). .SH STANDARDS CONFORMANCE .CR fmod() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4fmod()\f1 \- remainder functions@@@\f3fmod(3M)\f1 .\" index@\f4fmodf()\f1 \- remainder functions@@@\f3fmod(3M)\f1 .\" index@\f1math: remainder functions@@@\f3fmod(3M)\f1 .\" index@\f1remainder functions@@@\f3fmod(3M)\f1 .\" .\" toc@\f3fmod(3M)\f1:\0\0\f4fmod()\f1, \f4fmodf()\f1@@@remainder functions\f1 .\" toc@\f4fmodf()\f1:\0\0remainder function (float version)@@@see \f3fmod(3M)\f1 .\" .\" links@fmod.3m fmodf.3m .\" $Header: fmtmsg.3c,v 72.4 94/10/12 10:16:25 ssa Exp $ .TA f .TH fmtmsg 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fmtmsg() \- displays formatted message on standard error and console .SH SYNOPSIS .C "#include " .PP .nf .C "int fmtmsg(" .RS .PP .C "long class," .C "const char *label," .C "int severity," .C "const char *text," .C "const char *action," .C "const char *tag .RE .C ); .fi .SH DESCRIPTION The .CR fmtmsg() routine is intended as a language-independent error message service. Messages are displayed on the system console, standard error, or both, depending on the setting of the .I class parameter. The format of messages is under the control of the user, who may specify how much of the message is to be displayed on standard error. However, the format of the message displayed to the system console is not under user control. .PP All messages specify a .IR class , which indicates the source and status of the error condition, and where the message should be directed. The .I class may be functionally excluded by specifying .CR MM_NULLMC . If this is done, no message is produced. The class types are: .RS .TP 20 .B Display The display class has allowable values of .CR MM_PRINT , which directs the message to standard error, .CR MM_CONSOLE , which directs the message to the system console, or .CR "MM_PRINT | MM_CONSOLE" , which directs the message to both. .TP .B Error Type The error type class may be one of .CR MM_HARD , indicating a hardware error, .CR MM_SOFT , indicating a software failure, or .CR MM_FIRM , which indicates a firmware error. .TP .B Error Source The error source class may be one of .CR MM_APPL , indicating an application, .CR MM_UTIL , indicating an OS utility, or .CR MM_OPSYS , indicating a system error. .TP .B Recovery Status The recovery status class may be one of .CR MM_RECOVER , indicating recovery from the error is possible, or .CR RMM_NRECOV , stating no recovery is possible. .RE .PP The remaining parameters are functionally optional, in that the message produced may exclude any or all of them. Each is discussed in parameter order. .PP The .IR label component states where the error originated. It has the form .IR major:minor , where .IR major is a 10 character field specifying the major system producing the message and .IR minor is a 14 character field specifying the subsystem in error. For example, .IP .CR mail:send .PP This component can be excluded by setting it to .CR MM_NULLLBL or .CR NULL . .PP The .IR severity component describes the degree of importance of the failure. The predefined severity levels are: .RS .TP 20 .C MM_NOSEV No severity is specified and no print string is generated. .TP .C MM_INFO The message is informational only and the .CR INFO string is generated. .TP .C MM_WARNING The situation might be in error, and should be checked. The .CR WARNING string is generated. .TP .C MM_ERROR An error has been detected. The .CR ERROR string is generated. .TP .C MM_HALT An unrecoverable error has been detected. The .CR HALT string is generated. .RE .PP The .IR text component describes the nature of the failure in the most specific terms. It is expected to provide a sufficiently detailed account of the error to remove all doubt about its cause. It may be excluded by setting .IR text to .CR MM_NULLTXT or .CR MM_NULL . .PP The .IR action component describes the options available for recovery from the error. As output, it is prefaced with the string .CR TO FIX: . It may be disabled by setting .CR action to .CR MM_NULLACT or .CR NULL . .PP The .IR tag component is intended to direct the user to the appropriate documentation to correct or avoid the error. It may be disabled by setting .IR tag to .CR MM_NULLTXT or .CR RMM_NULL . .SH EXTERNAL INFLUENCES .PP The user may control the appearance of the message produced on standard error through the use of two environment variables: .CR MSGVERB and .CR SEV_LEVEL . These have no effect on the console message. .PP The .CR MSGVERB environment variable describes the components the user is interested in seeing. The value of .CR MSGVERB is a list of one or more components, separated by colons if more than one is specified. All components with non-NULL values listed in .CR MSGVERB are displayed when .CR fmtmsg() is called; all other components are excluded. Only the component names .IR label , .IR severity , .IR text , .IR action , and .IR tag are valid list elements. Any others (or an empty list) are considered an error in .CR MSGVERB format. If .CR MSGVERB is erroneous or unset, .CR fmtmsg() produces the full message. .PP The .CR SEV_LEVEL environment variable gives users control over the text string displayed for the severity component if the severity is other than those described above. The predefined severity levels .RC ( MM_NOSEV through .CR MM_HALT ) cannot be overridden. .PP The value of .CR SEV_LEVEL is a list of one or more level specifiers separated by colons. A level specifier is a three item comma list of the form .IR identifier , .IR level, .IR message . The .IR identifier is not used by .CR fmtmsg() , and is only included for compatibility. It is not optional, however, as .CR fmtmsg() expects it when examining level specifiers for the other two parts. The .IR level is a number greater than four indicating the level defined. The .IR message is a string to be displayed in the .CR severity field, in the same manner as .CR HALT and .CR INFO are displayed for the .CR MM_HALT and .CR MM_INFO severities. Level specifiers having more or fewer than three items are invalid, as are null level specifiers. Invalid or null valued .CR SEV_LEVEL lists have no impact on the behavior of .CR fmtmsg() . .SH RETURN VALUE .PP The .CR fmtmsg() routine returns one of the following values on exit: .RS .TP 20 .CR MM_OK Success. .TP .CR MM_NOTOK Failure. .TP .CR MM_NOMSG Failure to standard error, success to the system console. .TP .CR MM_NOCON Success to standard error, failure to the system console. .RE .SH AUTHOR .CR fmtmsg() was developed by OSF and HP. .SH SEE ALSO .PP printf(3s). .SH STANDARDS COMPLIANCE .CR fmtmsg ": SVID3" .\" .\" index@\f4fmtmsg()\f1 \- displays formatted message on standard error and console@@@\f3fmtmsg(3C)\f1 .\" index@\f1displays formatted message on standard error and console@@@\f3fmtmsg(3C)\f1 .\" index@\f1formatted message, displays on standard error and console@@@\f3fmtmsg(3C)\f1 .\" index@\f1standard error and console, displays formatted message on@@@\f3fmtmsg(3C)\f1 .\" index@\f1console and standard error, displays formatted message on@@@\f3fmtmsg(3C)\f1 .\" toc@\f3fmtmsg(3C)\f1:\0\0\f4fmtmsg()\f1@@@displays formatted message on standard error and console\f1 .\" $Header: fnmatch.3c,v 76.1 95/08/23 17:53:37 ssa Exp $ .TA f .TH fnmatch 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fnmatch(\|) \- match filename patterns .SH SYNOPSIS .C "#include " .PP .C "int fnmatch(const char *pattern, const char *string, int flags);" .SH DESCRIPTION .C fnmatch() performs pattern matching as described in .IR regexp (5) under .SM .IR "PATTERN MATCHING NOTATION" . By default, the rule qualifications for filename expansion do not apply; i.e., periods (dots) and slashes are matched as ordinary characters. This default behavior can be modified by using the flags described below. .PP The .I flag argument modifies the interpretation of .I pattern and .I string. If .CR FNM_PATHNAME , which is defined in .RC < fnmatch.h >, is set in .I flag, a slash character in .I string must be explicitly matched by a slash in .I pattern; it cannot be matched by either the asterisk or question mark special characters or by a bracket expression. .PP If .C FNM_PERIOD is set in .I flag, a leading period .RC ( . ) must be explicitly matched. It will not be matched by a bracket expression, question mark or asterisk. By default, a period is leading if it is the first character in .I string. If .C FNM_PATHNAME is set in .IR flag , a period is leading if it is the first character in .I string or immediately follows a slash. .PP If .C FNM_NOESCAPE is not set in .IR flag , a backslash character .RC ( \e ) in .I pattern followed by any other character matches that second character in .IR string . In particular, .C \e\e matches a backslash in .IR string . If .C FNM_NOESCAPE is set, a backslash character is treated as an ordinary character. .PP If .I flag is zero, the slash character and the period are treated as regular characters. If .I flag has any other value, the result is undefined. .SH RETURN VALUE If .I string matches the pattern specified by .IR pattern , .CR fnmatch() returns zero. Otherwise, .CR fnmatch() returns non-zero. .SH EXAMPLE The following excerpt uses .CR fnmatch() to check each file in a directory against the pattern .CR "*.c" : .RS .PP .ift .ft 4 .ps +1 pattern = "*.c"; while(dp = readdir(dirp)){ if((fnmatch(pattern, dp->d_name,0)) == 0){ /* do processing for match */ ... } } .ift .ft .ps .fi .RE .SH AUTHOR .CR fnmatch() was developed by OSF and HP. .SH SEE ALSO sh(1), glob(3c). .SH STANDARDS CONFORMANCE .CR fnmatch() ": XPG4, POSIX.2" .\" .\" index@\f4fnmatch()\fP \- match filename patterns@@@\f3fnmatch(3C)\f1 .\" index@\f1match filename patterns@@@\f3fnmatch(3C)\f1 .\" index@\f1filename patterns, match@@@\f3fnmatch(3C)\f1 .\" index@\f1patterns, match filename@@@\f3fnmatch(3C)\f1 .\" .\" toc@\f3fnmatch(3C)\f1:\0\0\f4fnmatch()\f1@@@match filename patterns .\" .\" $Header: fopen.3s,v 78.1 96/02/12 13:46:50 ssa Exp $ .TA f .TH fopen 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fopen(\|), freopen(\|), fdopen(\|) \- open or re-open a stream file; convert file to stream .SH SYNOPSIS .C "#include " .PP .C "FILE *fopen(const char *pathname, const char *type);" .PP .C "FILE *freopen(const char *pathname, const char *type, FILE *stream);" .PP .C "FILE *fdopen(int fildes, const char *type);" .SH DESCRIPTION .TP 15 .C fopen() Opens the file named by .I pathname and associates a .I stream with it. .C fopen() returns a pointer to the .C FILE structure associated with the .IR stream . .TP .C freopen() substitutes the named file in place of the open .IR stream . The original .I stream is closed, regardless of whether the open ultimately succeeds. .C freopen() returns a pointer to the .C FILE structure associated with .IR stream and makes an implicit call to .C clearerr() (see .IR ferror (3S)). .IP .C freopen() is typically used to attach the preopened .I streams associated with .CR stdin , .CR stdout , and .C stderr to other files. .TP .C fdopen() associates a stream with a file descriptor. File descriptors are obtained from .CR open() , .CR dup() , .CR creat() , or .C pipe() (see .IR open (2), .IR dup (2), .IR creat (2), and .IR pipe (2)), which open files but do not return pointers to a .C FILE structure stream. Streams are necessary input for many of the Section (3S) library routines. The .I type of stream must agree with the mode of the open file. The meanings of .I type used in the .C fdopen() call are exactly as specified above, except that .CR w , .CR w+ , .CR wb , and .C wb+ do not cause truncation of the file. .TP .I pathname Points to a character string containing the name of the file to be opened. .TP .I type Character string having one of the following values: .RS .RS .TP 15 .C r open for reading .TP .C w truncate to zero length or create for writing .TP .C a append; open for writing at end of file, or create for writing .TP .C rb open binary file for reading .TP .C wb truncate to zero length or create binary file for writing .TP .C ab append; open binary file for writing at end-of-file, or create binary file .TP .C r+ open for update (reading and writing) .TP .C w+ truncate to zero length or create for update .TP .C a+ append; open or create for update at end-of-file .TP .CI r+b \0or \0rb+ open binary file for update (reading and writing) .TP .CI w+b \0or \0wb+ truncate to zero length or create binary file for update .TP .CI a+b \0or \0ab+ append; open or create binary file for update at end-of-file .RE .RE .PP When a file is opened for update, both input and output can be done on the resulting .IR stream . However, output cannot be directly followed by input without an intervening call to .C fflush() or to a file positioning function .RC ( fseek() , .CR fsetpos() , or .CR rewind() ), and input cannot be directly followed by output without an intervening call to a file positioning function unless the input operation encounters end-of-file. .PP When a file is opened for append (i.e., when .I type is .C a or .CR a+ ), it is impossible to overwrite information already in the file. All output is written at the end of the file, regardless of intervening calls to .CR fseek() . If two separate processes open the same file for append, each process can write freely to the file without fear of destroying output being written by the other. Output from the two processes will be intermixed in the file in the order in which it is written. .SH RETURN VALUE Upon successful completion, .CR fopen() , .CR fdopen() , and .CR freopen() return a .C FILE * pointer to the stream. Otherwise, a null pointer is returned and .C errno is set to indicate the error. .SH ERRORS .CR fopen() , .CR fdopen() , and .CR freopen() fail if: .TP 15 .SM [EINVAL] The .I type argument is not a valid mode. .TP .SM [ENOMEM] There is insufficient space to allocate a buffer. .PP .C fopen() and .C freopen() fail if: .TP 15 .SM [EACCES] Search permission is denied on a component of the path prefix, or the file exists and the permissions specified by .I type are denied, or the file does not exist and write permission is denied for the parent directory of the file to be created. .TP .SM [EINTR] A signal was caught during .C fopen() or .CR freopen() . function. .TP .SM [EISDIR] The named file is a directory and .I type requires write access. .TP .SM [EMFILE] The calling process has attempted to exceed its open file limit. .TP .SM [ENAMETOOLONG] The length of the .I pathname string exceeds .C PATH_MAX or a pathname component is longer than .C NAME_MAX while .SM POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] The system file table is full. .TP .SM [ENOENT] The named file does not exist or the .I pathname argument points to an empty string. .TP .SM [ENOSPC] The directory or file system that would contain the new file cannot be expanded, the file does not exist, and it was to be created. .TP .SM [ENOTDIR] A component of the path prefix is not a directory. .TP .SM [ENXIO] The named file is a character special or block special file, and the device associated with the special file does not exist. .TP .SM [EOVERFLOW] The named file is a regular file and the size of the file cannot be represented correctly in an object of size .CR off_t in this environment. .TP .SM [EROFS] The named file resides on a read-only file system and .I type requires write access. .PP Additional .C errno values can be set by the underlying .CR open() call made from the .CR fopen() and .CR freopen() functions (see .IR open(2)). .SH NOTES .SM HP-UX binary file .I types are equivalent to their non-binary counterparts. For example, types .C r and .C rb are equivalent. .SH SEE ALSO creat(2), dup(2), open(2), pipe(2), fclose(3S), fopen64(3S), freopen64(3S), fseek(3S), popen(3S), setvbuf(3S). .SH STANDARDS CONFORMANCE .CR fopen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fdopen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR freopen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fopen()\f1 \- open a named file and associate with a stream@@@\f3fopen(3S)\f1 .\" index@\f4freopen()\f1 \- substitute a named file in place of an already open stream@@@\f3fopen(3S)\f1 .\" index@\f4fdopen()\f1 \- associate a stream with an open file descriptor@@@\f3fopen(3S)\f1 .\" index@\f1file, stream: open or re-open a stream file; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1file, stream: convert file to stream; open or re-open a stream file@@@\f3fopen(3S)\f1 .\" index@\f1open or re-open a stream file; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1re-open or open a stream file; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1stream file, open or re-open; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1stream file, open or re-open; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1convert file to stream@@@\f3fopen(3S)\f1 .\" .\" toc@\f3fopen(3S)\f1:\0\0\f4fopen()\f1, \f4freopen()\f1, \f4fdopen()\f1@@@open or re-open a stream file; convert file to stream .\" toc@\f4freopen()\f1:\0\0re-open a stream file; convert file to stream@@@see \f3fopen(3S)\f1 .\" toc@\f4fdopen()\f1:\0\0associate a stream with a file descriptor@@@see \f3fopen(3S)\f1 .\" .\" links@fopen.3s freopen.3s .\" links@fopen.3s fdopen.3s .\" .\" $Header: fgetpos64.3s,v 78.3 96/02/12 17:04:12 ssa Exp $ .TA f .TH fgetpos64 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetpos64(\|), fopen64(\|), freopen64(\|), fseeko64(\|), fsetpos64(\|), fstatvfsdev64(\|), ftello64(\|), ftw64(\|), nftw64(\|), statvfsdev64(\|), tmpfile64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0fgetpos64(FILE\0*stream,\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "FILE\0*fopen64(const\0char\0*pathname,\0const\0char\0*type);" .PP .C "#include " .PP .C "FILE\0*freopen64(const\0char\0*pathname,\0const\0char\0*type,\0FILE\0*stream);" .PP .C "#include " .PP .C "int\0fseeko64(FILE\0*stream,\0off64_t\0*offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0fsetpos64(FILE\0*stream,\0const\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "int\0fstatvfsdev64(int\0filedes,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "off64_t\0ftello64(FILE\0*stream);" .PP .nf .C "#include " .PP .C "int ftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags)," .C " int depth);" .PP .C "#include " .PP .C "int nftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .PP .C "#include " .PP .C "int\0statvfsdev64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "FILE\0*tmpfile64(void);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 22 .C fgetpos64() The .C fgetpos64() function is identical to .C fgetpos() except that .C fgetpos64() returns the position in a .C fpos64_t instead of a .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fopen64() The .C fopen64() function is identical to .C fopen() in 64-bit compile environment. The .C fopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR fopen() . .TP .C freopen64() The .C freopen64() function is identical to .C freopen() in 64-bit compile environment. The .C freopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR freopen() . .TP .C fseeko64() The .C fseeko64() function is identical to .C fseeko() except that .C fseeko64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C fsetpos64() The .C fsetpos64() function is identical to .C fsetpos() except that .C fsetpos64() accepts an .CR fpos64_t for the pos parameter instead of .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fstatvfsdev64() The .C fstatvfsdev64() function is identical to .C fstatvfsdev() except that .C fstatvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C ftello64() The .C ftello64() function is identical to .C ftello() except that .C ftello64() returns the file position in an .C off64_t instead of an .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C ftw64() The .C ftw64() function is identical to .C ftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR ftw64() . All other functional behaviors, returns, and errors are identical. .TP .C nftw64() The .C nftw64() function is identical to .C nftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR nftw64() . All other functional behaviors, returns, and errors are identical. .TP .C statvfsdev64() The .C statvfsdev64() function is identical to .C statvfsdev() except that .C statvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C tmpfile64() The .C tmpfile64() function is identical to .C tmpfile() in the 64-bit compile environment. Both interfaces create a temporary file that is capable of growing beyond 2GB's if desired. All other functional behaviors, returns, and errors are identical. .\" .\" toc@\f4fgetpos64(2)\f1:\0\0\f4fopen64\f1, \f4freopen64\f1, \f4fseeko64\f1, \f4fsetpos64\f1, \f4fstatvfsdev64\f1, \f4ftello64\f1, \f4ftw64\f1, \n\f4nftw64\f1, \f4statvfsdev64\f1, \f4tmpfile64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4fgetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4freopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fseeko64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fsetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fstatvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftello64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4nftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4statvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4tmpfile64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3fgetpos64(2)\f1 .\" .\" links@fgetpos64.3s fopen64.3s .\" links@fgetpos64.3s freopen64.3s .\" links@fgetpos64.3s fseek64.3s .\" links@fgetpos64.3s fsetpos64.3s .\" links@fgetpos64.3s fstatvfs64.3s .\" links@fgetpos64.3s ftello64.3s .\" links@fgetpos64.3s ftw64.3s .\" links@fgetpos64.3s nftw64.3s .\" links@fgetpos64.3s statvfsdev64.3s .\" links@fgetpos64.3s tmpfile64.3s .\" .\" $Header: fpclassify.3m,v 78.1 96/02/13 10:45:31 ssa Exp $ .TA f .TH fpclassify 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fpclassify(\|), fpclassifyf(\|) \- floating-point operand classification functions .SH SYNOPSIS .C "#include " .PP .C "int fpclassify(double x);" .PP .C "int fpclassifyf(float x);" .SH DESCRIPTION .CR fpclassify() and .CR fpclassifyf() return a non-negative integer value that specifies the IEEE operand class to which the argument .I x belongs. The value returned is one of the following macros, which are defined in .RC < math.h >: .RS .PP .nf .ift .ft 4 .ift .ps +1 #define FP_PLUS_NORM 0 /* Positive normalized */ #define FP_MINUS_NORM 1 /* Negative normalized */ #define FP_PLUS_ZERO 2 /* Positive zero */ #define FP_MINUS_ZERO 3 /* Negative zero */ #define FP_PLUS_INF 4 /* Positive infinity */ #define FP_MINUS_INF 5 /* Negative infinity */ #define FP_PLUS_DENORM 6 /* Positive denormalized */ #define FP_MINUS_DENORM 7 /* Negative denormalized */ #define FP_SNAN 8 /* Signalling NaN */ #define FP_QNAN 9 /* Quiet NaN */ .ift .ft .ift .sp .fi .RE .PP Every possible argument value falls into one of these ten categories, so these functions never result in an error. .PP .CR fpclassifyf() is a .CR float version of .CR fpclassify() ; it takes a .CR float argument. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP These functions are not specified by any standard. However, they implement the .CR class() function suggested in the "Recommended Functions and Predicates" appendix of the IEEE-754 floating-point standard. Also, .CR fpclassifyf() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH SEE ALSO finite(3M), isinf(3M), isnan(3M). .\" .\" index@\f4fpclassify()\f1, \f4fpclassifyf()\f1 \- floating-point classification functions@@@\f3fpclassify(3M)\f1 .\" index@\f4fpclassifyf()\f1, \f4fpclassify()\f1 \- floating-point classification functions@@@\f3fpclassify(3M)\f1 .\" index@\f1math: floating-point classification functions@@@\f3fpclassify(3M)\f1 .\" index@\f1floating-point classification functions@@@\f3fpclassify(3M)\f1 .\" .\" toc@\f3fpclassify(3M)\f1:\0\0\f4fpclassify()\f1, \f4fpclassifyf()\f1@@@floating-point classification functions .\" toc@\f4fpclassifyf()\f1:\0\0floating-point classification function (float version)@@@see \f3fpclassify(3M)\f1 .\" .\" links@fpclassify.3m fpclassifyf.3m .\" .\" fileset_database@fpclassify.3m PROGRAMING-MAN .\" $Header: fpclassify.3m,v 78.1 96/02/13 10:45:31 ssa Exp $ .TA f .TH fpclassify 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fpclassify(\|), fpclassifyf(\|) \- floating-point operand classification functions .SH SYNOPSIS .C "#include " .PP .C "int fpclassify(double x);" .PP .C "int fpclassifyf(float x);" .SH DESCRIPTION .CR fpclassify() and .CR fpclassifyf() return a non-negative integer value that specifies the IEEE operand class to which the argument .I x belongs. The value returned is one of the following macros, which are defined in .RC < math.h >: .RS .PP .nf .ift .ft 4 .ift .ps +1 #define FP_PLUS_NORM 0 /* Positive normalized */ #define FP_MINUS_NORM 1 /* Negative normalized */ #define FP_PLUS_ZERO 2 /* Positive zero */ #define FP_MINUS_ZERO 3 /* Negative zero */ #define FP_PLUS_INF 4 /* Positive infinity */ #define FP_MINUS_INF 5 /* Negative infinity */ #define FP_PLUS_DENORM 6 /* Positive denormalized */ #define FP_MINUS_DENORM 7 /* Negative denormalized */ #define FP_SNAN 8 /* Signalling NaN */ #define FP_QNAN 9 /* Quiet NaN */ .ift .ft .ift .sp .fi .RE .PP Every possible argument value falls into one of these ten categories, so these functions never result in an error. .PP .CR fpclassifyf() is a .CR float version of .CR fpclassify() ; it takes a .CR float argument. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP These functions are not specified by any standard. However, they implement the .CR class() function suggested in the "Recommended Functions and Predicates" appendix of the IEEE-754 floating-point standard. Also, .CR fpclassifyf() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH SEE ALSO finite(3M), isinf(3M), isnan(3M). .\" .\" index@\f4fpclassify()\f1, \f4fpclassifyf()\f1 \- floating-point classification functions@@@\f3fpclassify(3M)\f1 .\" index@\f4fpclassifyf()\f1, \f4fpclassify()\f1 \- floating-point classification functions@@@\f3fpclassify(3M)\f1 .\" index@\f1math: floating-point classification functions@@@\f3fpclassify(3M)\f1 .\" index@\f1floating-point classification functions@@@\f3fpclassify(3M)\f1 .\" .\" toc@\f3fpclassify(3M)\f1:\0\0\f4fpclassify()\f1, \f4fpclassifyf()\f1@@@floating-point classification functions .\" toc@\f4fpclassifyf()\f1:\0\0floating-point classification function (float version)@@@see \f3fpclassify(3M)\f1 .\" .\" links@fpclassify.3m fpclassifyf.3m .\" .\" fileset_database@fpclassify.3m PROGRAMING-MAN .\" $Header: fpgetround.3m,v 78.1 96/02/13 10:48:13 ssa Exp $ .TA f .TH fpgetround 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fpgetround(\|), fpsetround(\|), fpgetmask(\|), fpsetmask(\|), fpgetsticky(\|), fpsetsticky(\|), fpsetdefaults(\|), fpgetcontrol(\|), fpsetcontrol(\|), fpgetfastmode(\|), fpsetfastmode(\|) \- floating-point mode-control functions .SH SYNOPSIS .C "#include " .PP .C "fp_rnd fpgetround(void);" .PP .C "fp_rnd fpsetround(fp_rnd mode);" .PP .C "fp_except fpgetmask(void);" .PP .C "fp_except fpsetmask(fp_except value);" .PP .C "fp_except fpgetsticky(void);" .PP .C "fp_except fpsetsticky(fp_except value);" .PP .C "int fpgetfastmode(void);" .PP .C "int fpsetfastmode(int value);" .PP .C "void fpsetdefaults(void);" .PP .C "fp_control fpgetcontrol(void);" .PP .C "fp_control fpsetcontrol(fp_control value);" .PP .SH DESCRIPTION The .CR fpgetround() suite of functions allows programmers to manipulate the floating-point control register (also called the floating-point status register). .PP .CR fpgetround() returns the current rounding mode. The type of the returned value, .CR fp_rnd , is defined as follows in .RC < math.h >: .nf .IP .C "typedef enum {" .C " FP_RZ=0, /* Round toward zero */" .C " FP_RN, /* Round to nearest */" .C " FP_RP, /* Round toward positive infinity */" .C " FP_RM, /* Round toward negative infinity */" .C " } fp_rnd;" .fi .PP The default value is .CR FP_RN . Round-to-nearest mode rounds to the representable value closest to the true value. If two representable values are equally close to the true value, the system chooses the one whose least significant bit is zero. .PP .CR fpsetround() sets the rounding mode to the specified value of type .CR fp_rnd and returns the previous rounding mode. .PP There are five floating-point exceptions: divide-by-zero, overflow, underflow, imprecise (inexact) result, and invalid operation. If a floating-point exception occurs and the corresponding exception trap enable bit is set to 1, the trap takes place. If an exception occurs and the exception trap enable bit is set to 0, the corresponding exception flag is set to 1 and no trap takes place. The exception trap enable bits are sometimes called mask bits; the exception flags are sometimes called sticky bits. The functions .CR fpgetmask() and .CR fpgetsticky() return the current settings of these bits. To change the settings of these bits, use .CR fpsetmask() and .CR fpsetsticky() . .PP .CR fpgetmask() returns the current exception trap enable bits. The type of the returned value, .CR fp_except , is defined as .CR int in .RC < math.h >. The floating-point exception types are defined as follows in .RC < math.h >: .nf .IP .C "#define FP_X_INV 0x10 /* invalid operation exception */" .C "#define FP_X_DZ 0x08 /* divide-by-zero exception */" .C "#define FP_X_OFL 0x04 /* overflow exception */" .C "#define FP_X_UFL 0x02 /* underflow exception */" .C "#define FP_X_IMP 0x01 /* imprecise (inexact result) */" .C "#define FP_X_CLEAR 0x00 /* simply zero to clear all flags */" .fi .PP .CR fpsetmask() sets or clears the exception trap enable bits and returns the previous setting. The argument is an expression of type .CR fp_except . (To set or clear the exception trap enable bits at compile time, use the compiler option .CR +FP\c .IR string ). .PP .CR fpgetsticky() returns the current exception flags. .PP .CR fpsetsticky() sets or clears the exception flags and returns the previous setting. The argument is an expression of type .CR fp_except . .PP .CR fpgetfastmode() and .CR fpsetfastmode() allow the programmer to change the way the system handles underflow. Fast underflow mode, also known as fastmode, is an alternative to IEEE-754-compliant underflow mode. On Series 700/800 systems, most underflow cases are supported by trapping into the kernel, where the IEEE-mandated conversion of the result into a denormalized value or zero is accomplished by software emulation. On later PA1.1 systems and on all PA2.0 systems, fastmode causes the hardware to simply substitute a zero for the result of an operation, with no fault occurring. This may be a significant performance optimization for applications that underflow frequently. Fastmode also causes denormalized floating-point operands to be treated as if they were true zero operands. .PP .CR fpgetfastmode() returns the current fastmode setting: 1 if fastmode is set, 0 if the default IEEE-754-compliant underflow mode is set. On systems that do not support fastmode, this function returns an undefined value. .PP On systems that support fastmode, .CR fpsetfastmode() sets fastmode to either 1 (fastmode) or 0 (IEEE-754-compliant underflow mode) and returns the previous setting. On systems that do not support fastmode, this function has no effect. .PP .CR fpsetdefaults() changes the default environment, which is .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps disabled .br Fast underflow mode disabled .fi .PP .CR fpsetdefaults() changes these defaults to more useful values. Specifically, it enables traps for the invalid operation, divide-by-zero, and overflow exceptions, while leaving the underflow and inexact-result exception traps disabled. It sets the environment as follows: .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps enabled except underflow and inexact result (\c .CR FP_X_INV + FP_X_DZ + FP_X_OFL\c ) .br Fast underflow mode enabled (if the system supports it) .PP .CR fpgetcontrol() and .CR fpsetcontrol() access the floating-point status register. .PP .CR fpgetcontrol() returns the value of the floating-point status register. The type of the returned value, .CR fp_control , is defined as .CR long in .RC < math.h >. .PP .CR fpsetcontrol() sets the value of the floating-point status register and returns the previous value. For the format of this register, see the .I "HP-UX Floating-Point Guide" or the PA-RISC 1.1 or 2.0 architecture and instruction set reference manual. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH WARNINGS .CR fpsetsticky() modifies all exception flags. .CR fpsetmask() modifies all exception trap enable bits. .PP Both C and FORTRAN require truncation (rounding to zero) for floating-point to integer conversions. The current rounding mode has no effect on these conversions. .\" .\" index@\f4fpgetround()\f1, \f4fpsetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetround()\f1, \f4fpgetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetmask()\f1, \f4fpsetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetmask()\f1, \f4fpgetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetdefaults()\f1 \- set floating-point control register defaults@@@\f3fpgetround(3M)\f1 .\" index@math: floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@rounding mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception trap enable bits (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception flags (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@status register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@underflow mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" index@status register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" .\" toc@\f3fpgetround(3M)\f1:\0\0\f4fpgetround()\f1, \f4fpsetround()\f1, \f4fpgetmask()\f1, \f4fpsetmask()\f1, \f4fpgetsticky()\f1, \n\f4fpsetsticky()\f1, \f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1, \f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1, \n\f4fpsetdefaults()\f1@@@floating-point mode control functions .\" toc@\f4fpsetround()\f1, \f4fpgetround()\f1:\0\0floating-point rounding mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetmask()\f1, \f4fpsetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetmask()\f1, \f4fpgetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetdefaults()\f1:\0\0floating-point control register defaults functions@@@see \f3fpgetround(3M)\f1 .\" .\" links@fpgetround.3m fpsetround.3m .\" links@fpgetround.3m fpgetmask.3m .\" links@fpgetround.3m fpsetmask.3m .\" links@fpgetround.3m fpgetsticky.3m .\" links@fpgetround.3m fpsetsticky.3m .\" links@fpgetround.3m fpgetcontro.3m .\" links@fpgetround.3m fpsetcontro.3m .\" links@fpgetround.3m fpgetfastmo.3m .\" links@fpgetround.3m fpsetfastmo.3m .\" links@fpgetround.3m fpsetdefaul.3m .\" .\" fileset_database@fpgetround.3m PROGRAMING-MAN .\" $Header: fpgetround.3m,v 78.1 96/02/13 10:48:13 ssa Exp $ .TA f .TH fpgetround 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fpgetround(\|), fpsetround(\|), fpgetmask(\|), fpsetmask(\|), fpgetsticky(\|), fpsetsticky(\|), fpsetdefaults(\|), fpgetcontrol(\|), fpsetcontrol(\|), fpgetfastmode(\|), fpsetfastmode(\|) \- floating-point mode-control functions .SH SYNOPSIS .C "#include " .PP .C "fp_rnd fpgetround(void);" .PP .C "fp_rnd fpsetround(fp_rnd mode);" .PP .C "fp_except fpgetmask(void);" .PP .C "fp_except fpsetmask(fp_except value);" .PP .C "fp_except fpgetsticky(void);" .PP .C "fp_except fpsetsticky(fp_except value);" .PP .C "int fpgetfastmode(void);" .PP .C "int fpsetfastmode(int value);" .PP .C "void fpsetdefaults(void);" .PP .C "fp_control fpgetcontrol(void);" .PP .C "fp_control fpsetcontrol(fp_control value);" .PP .SH DESCRIPTION The .CR fpgetround() suite of functions allows programmers to manipulate the floating-point control register (also called the floating-point status register). .PP .CR fpgetround() returns the current rounding mode. The type of the returned value, .CR fp_rnd , is defined as follows in .RC < math.h >: .nf .IP .C "typedef enum {" .C " FP_RZ=0, /* Round toward zero */" .C " FP_RN, /* Round to nearest */" .C " FP_RP, /* Round toward positive infinity */" .C " FP_RM, /* Round toward negative infinity */" .C " } fp_rnd;" .fi .PP The default value is .CR FP_RN . Round-to-nearest mode rounds to the representable value closest to the true value. If two representable values are equally close to the true value, the system chooses the one whose least significant bit is zero. .PP .CR fpsetround() sets the rounding mode to the specified value of type .CR fp_rnd and returns the previous rounding mode. .PP There are five floating-point exceptions: divide-by-zero, overflow, underflow, imprecise (inexact) result, and invalid operation. If a floating-point exception occurs and the corresponding exception trap enable bit is set to 1, the trap takes place. If an exception occurs and the exception trap enable bit is set to 0, the corresponding exception flag is set to 1 and no trap takes place. The exception trap enable bits are sometimes called mask bits; the exception flags are sometimes called sticky bits. The functions .CR fpgetmask() and .CR fpgetsticky() return the current settings of these bits. To change the settings of these bits, use .CR fpsetmask() and .CR fpsetsticky() . .PP .CR fpgetmask() returns the current exception trap enable bits. The type of the returned value, .CR fp_except , is defined as .CR int in .RC < math.h >. The floating-point exception types are defined as follows in .RC < math.h >: .nf .IP .C "#define FP_X_INV 0x10 /* invalid operation exception */" .C "#define FP_X_DZ 0x08 /* divide-by-zero exception */" .C "#define FP_X_OFL 0x04 /* overflow exception */" .C "#define FP_X_UFL 0x02 /* underflow exception */" .C "#define FP_X_IMP 0x01 /* imprecise (inexact result) */" .C "#define FP_X_CLEAR 0x00 /* simply zero to clear all flags */" .fi .PP .CR fpsetmask() sets or clears the exception trap enable bits and returns the previous setting. The argument is an expression of type .CR fp_except . (To set or clear the exception trap enable bits at compile time, use the compiler option .CR +FP\c .IR string ). .PP .CR fpgetsticky() returns the current exception flags. .PP .CR fpsetsticky() sets or clears the exception flags and returns the previous setting. The argument is an expression of type .CR fp_except . .PP .CR fpgetfastmode() and .CR fpsetfastmode() allow the programmer to change the way the system handles underflow. Fast underflow mode, also known as fastmode, is an alternative to IEEE-754-compliant underflow mode. On Series 700/800 systems, most underflow cases are supported by trapping into the kernel, where the IEEE-mandated conversion of the result into a denormalized value or zero is accomplished by software emulation. On later PA1.1 systems and on all PA2.0 systems, fastmode causes the hardware to simply substitute a zero for the result of an operation, with no fault occurring. This may be a significant performance optimization for applications that underflow frequently. Fastmode also causes denormalized floating-point operands to be treated as if they were true zero operands. .PP .CR fpgetfastmode() returns the current fastmode setting: 1 if fastmode is set, 0 if the default IEEE-754-compliant underflow mode is set. On systems that do not support fastmode, this function returns an undefined value. .PP On systems that support fastmode, .CR fpsetfastmode() sets fastmode to either 1 (fastmode) or 0 (IEEE-754-compliant underflow mode) and returns the previous setting. On systems that do not support fastmode, this function has no effect. .PP .CR fpsetdefaults() changes the default environment, which is .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps disabled .br Fast underflow mode disabled .fi .PP .CR fpsetdefaults() changes these defaults to more useful values. Specifically, it enables traps for the invalid operation, divide-by-zero, and overflow exceptions, while leaving the underflow and inexact-result exception traps disabled. It sets the environment as follows: .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps enabled except underflow and inexact result (\c .CR FP_X_INV + FP_X_DZ + FP_X_OFL\c ) .br Fast underflow mode enabled (if the system supports it) .PP .CR fpgetcontrol() and .CR fpsetcontrol() access the floating-point status register. .PP .CR fpgetcontrol() returns the value of the floating-point status register. The type of the returned value, .CR fp_control , is defined as .CR long in .RC < math.h >. .PP .CR fpsetcontrol() sets the value of the floating-point status register and returns the previous value. For the format of this register, see the .I "HP-UX Floating-Point Guide" or the PA-RISC 1.1 or 2.0 architecture and instruction set reference manual. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH WARNINGS .CR fpsetsticky() modifies all exception flags. .CR fpsetmask() modifies all exception trap enable bits. .PP Both C and FORTRAN require truncation (rounding to zero) for floating-point to integer conversions. The current rounding mode has no effect on these conversions. .\" .\" index@\f4fpgetround()\f1, \f4fpsetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetround()\f1, \f4fpgetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetmask()\f1, \f4fpsetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetmask()\f1, \f4fpgetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetdefaults()\f1 \- set floating-point control register defaults@@@\f3fpgetround(3M)\f1 .\" index@math: floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@rounding mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception trap enable bits (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception flags (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@status register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@underflow mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" index@status register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" .\" toc@\f3fpgetround(3M)\f1:\0\0\f4fpgetround()\f1, \f4fpsetround()\f1, \f4fpgetmask()\f1, \f4fpsetmask()\f1, \f4fpgetsticky()\f1, \n\f4fpsetsticky()\f1, \f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1, \f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1, \n\f4fpsetdefaults()\f1@@@floating-point mode control functions .\" toc@\f4fpsetround()\f1, \f4fpgetround()\f1:\0\0floating-point rounding mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetmask()\f1, \f4fpsetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetmask()\f1, \f4fpgetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetdefaults()\f1:\0\0floating-point control register defaults functions@@@see \f3fpgetround(3M)\f1 .\" .\" links@fpgetround.3m fpsetround.3m .\" links@fpgetround.3m fpgetmask.3m .\" links@fpgetround.3m fpsetmask.3m .\" links@fpgetround.3m fpgetsticky.3m .\" links@fpgetround.3m fpsetsticky.3m .\" links@fpgetround.3m fpgetcontro.3m .\" links@fpgetround.3m fpsetcontro.3m .\" links@fpgetround.3m fpgetfastmo.3m .\" links@fpgetround.3m fpsetfastmo.3m .\" links@fpgetround.3m fpsetdefaul.3m .\" .\" fileset_database@fpgetround.3m PROGRAMING-MAN .\" $Header: fpgetround.3m,v 78.1 96/02/13 10:48:13 ssa Exp $ .TA f .TH fpgetround 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fpgetround(\|), fpsetround(\|), fpgetmask(\|), fpsetmask(\|), fpgetsticky(\|), fpsetsticky(\|), fpsetdefaults(\|), fpgetcontrol(\|), fpsetcontrol(\|), fpgetfastmode(\|), fpsetfastmode(\|) \- floating-point mode-control functions .SH SYNOPSIS .C "#include " .PP .C "fp_rnd fpgetround(void);" .PP .C "fp_rnd fpsetround(fp_rnd mode);" .PP .C "fp_except fpgetmask(void);" .PP .C "fp_except fpsetmask(fp_except value);" .PP .C "fp_except fpgetsticky(void);" .PP .C "fp_except fpsetsticky(fp_except value);" .PP .C "int fpgetfastmode(void);" .PP .C "int fpsetfastmode(int value);" .PP .C "void fpsetdefaults(void);" .PP .C "fp_control fpgetcontrol(void);" .PP .C "fp_control fpsetcontrol(fp_control value);" .PP .SH DESCRIPTION The .CR fpgetround() suite of functions allows programmers to manipulate the floating-point control register (also called the floating-point status register). .PP .CR fpgetround() returns the current rounding mode. The type of the returned value, .CR fp_rnd , is defined as follows in .RC < math.h >: .nf .IP .C "typedef enum {" .C " FP_RZ=0, /* Round toward zero */" .C " FP_RN, /* Round to nearest */" .C " FP_RP, /* Round toward positive infinity */" .C " FP_RM, /* Round toward negative infinity */" .C " } fp_rnd;" .fi .PP The default value is .CR FP_RN . Round-to-nearest mode rounds to the representable value closest to the true value. If two representable values are equally close to the true value, the system chooses the one whose least significant bit is zero. .PP .CR fpsetround() sets the rounding mode to the specified value of type .CR fp_rnd and returns the previous rounding mode. .PP There are five floating-point exceptions: divide-by-zero, overflow, underflow, imprecise (inexact) result, and invalid operation. If a floating-point exception occurs and the corresponding exception trap enable bit is set to 1, the trap takes place. If an exception occurs and the exception trap enable bit is set to 0, the corresponding exception flag is set to 1 and no trap takes place. The exception trap enable bits are sometimes called mask bits; the exception flags are sometimes called sticky bits. The functions .CR fpgetmask() and .CR fpgetsticky() return the current settings of these bits. To change the settings of these bits, use .CR fpsetmask() and .CR fpsetsticky() . .PP .CR fpgetmask() returns the current exception trap enable bits. The type of the returned value, .CR fp_except , is defined as .CR int in .RC < math.h >. The floating-point exception types are defined as follows in .RC < math.h >: .nf .IP .C "#define FP_X_INV 0x10 /* invalid operation exception */" .C "#define FP_X_DZ 0x08 /* divide-by-zero exception */" .C "#define FP_X_OFL 0x04 /* overflow exception */" .C "#define FP_X_UFL 0x02 /* underflow exception */" .C "#define FP_X_IMP 0x01 /* imprecise (inexact result) */" .C "#define FP_X_CLEAR 0x00 /* simply zero to clear all flags */" .fi .PP .CR fpsetmask() sets or clears the exception trap enable bits and returns the previous setting. The argument is an expression of type .CR fp_except . (To set or clear the exception trap enable bits at compile time, use the compiler option .CR +FP\c .IR string ). .PP .CR fpgetsticky() returns the current exception flags. .PP .CR fpsetsticky() sets or clears the exception flags and returns the previous setting. The argument is an expression of type .CR fp_except . .PP .CR fpgetfastmode() and .CR fpsetfastmode() allow the programmer to change the way the system handles underflow. Fast underflow mode, also known as fastmode, is an alternative to IEEE-754-compliant underflow mode. On Series 700/800 systems, most underflow cases are supported by trapping into the kernel, where the IEEE-mandated conversion of the result into a denormalized value or zero is accomplished by software emulation. On later PA1.1 systems and on all PA2.0 systems, fastmode causes the hardware to simply substitute a zero for the result of an operation, with no fault occurring. This may be a significant performance optimization for applications that underflow frequently. Fastmode also causes denormalized floating-point operands to be treated as if they were true zero operands. .PP .CR fpgetfastmode() returns the current fastmode setting: 1 if fastmode is set, 0 if the default IEEE-754-compliant underflow mode is set. On systems that do not support fastmode, this function returns an undefined value. .PP On systems that support fastmode, .CR fpsetfastmode() sets fastmode to either 1 (fastmode) or 0 (IEEE-754-compliant underflow mode) and returns the previous setting. On systems that do not support fastmode, this function has no effect. .PP .CR fpsetdefaults() changes the default environment, which is .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps disabled .br Fast underflow mode disabled .fi .PP .CR fpsetdefaults() changes these defaults to more useful values. Specifically, it enables traps for the invalid operation, divide-by-zero, and overflow exceptions, while leaving the underflow and inexact-result exception traps disabled. It sets the environment as follows: .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps enabled except underflow and inexact result (\c .CR FP_X_INV + FP_X_DZ + FP_X_OFL\c ) .br Fast underflow mode enabled (if the system supports it) .PP .CR fpgetcontrol() and .CR fpsetcontrol() access the floating-point status register. .PP .CR fpgetcontrol() returns the value of the floating-point status register. The type of the returned value, .CR fp_control , is defined as .CR long in .RC < math.h >. .PP .CR fpsetcontrol() sets the value of the floating-point status register and returns the previous value. For the format of this register, see the .I "HP-UX Floating-Point Guide" or the PA-RISC 1.1 or 2.0 architecture and instruction set reference manual. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH WARNINGS .CR fpsetsticky() modifies all exception flags. .CR fpsetmask() modifies all exception trap enable bits. .PP Both C and FORTRAN require truncation (rounding to zero) for floating-point to integer conversions. The current rounding mode has no effect on these conversions. .\" .\" index@\f4fpgetround()\f1, \f4fpsetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetround()\f1, \f4fpgetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetmask()\f1, \f4fpsetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetmask()\f1, \f4fpgetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetdefaults()\f1 \- set floating-point control register defaults@@@\f3fpgetround(3M)\f1 .\" index@math: floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@rounding mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception trap enable bits (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception flags (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@status register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@underflow mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" index@status register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" .\" toc@\f3fpgetround(3M)\f1:\0\0\f4fpgetround()\f1, \f4fpsetround()\f1, \f4fpgetmask()\f1, \f4fpsetmask()\f1, \f4fpgetsticky()\f1, \n\f4fpsetsticky()\f1, \f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1, \f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1, \n\f4fpsetdefaults()\f1@@@floating-point mode control functions .\" toc@\f4fpsetround()\f1, \f4fpgetround()\f1:\0\0floating-point rounding mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetmask()\f1, \f4fpsetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetmask()\f1, \f4fpgetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetdefaults()\f1:\0\0floating-point control register defaults functions@@@see \f3fpgetround(3M)\f1 .\" .\" links@fpgetround.3m fpsetround.3m .\" links@fpgetround.3m fpgetmask.3m .\" links@fpgetround.3m fpsetmask.3m .\" links@fpgetround.3m fpgetsticky.3m .\" links@fpgetround.3m fpsetsticky.3m .\" links@fpgetround.3m fpgetcontro.3m .\" links@fpgetround.3m fpsetcontro.3m .\" links@fpgetround.3m fpgetfastmo.3m .\" links@fpgetround.3m fpsetfastmo.3m .\" links@fpgetround.3m fpsetdefaul.3m .\" .\" fileset_database@fpgetround.3m PROGRAMING-MAN .\" $Header: fpgetround.3m,v 78.1 96/02/13 10:48:13 ssa Exp $ .TA f .TH fpgetround 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fpgetround(\|), fpsetround(\|), fpgetmask(\|), fpsetmask(\|), fpgetsticky(\|), fpsetsticky(\|), fpsetdefaults(\|), fpgetcontrol(\|), fpsetcontrol(\|), fpgetfastmode(\|), fpsetfastmode(\|) \- floating-point mode-control functions .SH SYNOPSIS .C "#include " .PP .C "fp_rnd fpgetround(void);" .PP .C "fp_rnd fpsetround(fp_rnd mode);" .PP .C "fp_except fpgetmask(void);" .PP .C "fp_except fpsetmask(fp_except value);" .PP .C "fp_except fpgetsticky(void);" .PP .C "fp_except fpsetsticky(fp_except value);" .PP .C "int fpgetfastmode(void);" .PP .C "int fpsetfastmode(int value);" .PP .C "void fpsetdefaults(void);" .PP .C "fp_control fpgetcontrol(void);" .PP .C "fp_control fpsetcontrol(fp_control value);" .PP .SH DESCRIPTION The .CR fpgetround() suite of functions allows programmers to manipulate the floating-point control register (also called the floating-point status register). .PP .CR fpgetround() returns the current rounding mode. The type of the returned value, .CR fp_rnd , is defined as follows in .RC < math.h >: .nf .IP .C "typedef enum {" .C " FP_RZ=0, /* Round toward zero */" .C " FP_RN, /* Round to nearest */" .C " FP_RP, /* Round toward positive infinity */" .C " FP_RM, /* Round toward negative infinity */" .C " } fp_rnd;" .fi .PP The default value is .CR FP_RN . Round-to-nearest mode rounds to the representable value closest to the true value. If two representable values are equally close to the true value, the system chooses the one whose least significant bit is zero. .PP .CR fpsetround() sets the rounding mode to the specified value of type .CR fp_rnd and returns the previous rounding mode. .PP There are five floating-point exceptions: divide-by-zero, overflow, underflow, imprecise (inexact) result, and invalid operation. If a floating-point exception occurs and the corresponding exception trap enable bit is set to 1, the trap takes place. If an exception occurs and the exception trap enable bit is set to 0, the corresponding exception flag is set to 1 and no trap takes place. The exception trap enable bits are sometimes called mask bits; the exception flags are sometimes called sticky bits. The functions .CR fpgetmask() and .CR fpgetsticky() return the current settings of these bits. To change the settings of these bits, use .CR fpsetmask() and .CR fpsetsticky() . .PP .CR fpgetmask() returns the current exception trap enable bits. The type of the returned value, .CR fp_except , is defined as .CR int in .RC < math.h >. The floating-point exception types are defined as follows in .RC < math.h >: .nf .IP .C "#define FP_X_INV 0x10 /* invalid operation exception */" .C "#define FP_X_DZ 0x08 /* divide-by-zero exception */" .C "#define FP_X_OFL 0x04 /* overflow exception */" .C "#define FP_X_UFL 0x02 /* underflow exception */" .C "#define FP_X_IMP 0x01 /* imprecise (inexact result) */" .C "#define FP_X_CLEAR 0x00 /* simply zero to clear all flags */" .fi .PP .CR fpsetmask() sets or clears the exception trap enable bits and returns the previous setting. The argument is an expression of type .CR fp_except . (To set or clear the exception trap enable bits at compile time, use the compiler option .CR +FP\c .IR string ). .PP .CR fpgetsticky() returns the current exception flags. .PP .CR fpsetsticky() sets or clears the exception flags and returns the previous setting. The argument is an expression of type .CR fp_except . .PP .CR fpgetfastmode() and .CR fpsetfastmode() allow the programmer to change the way the system handles underflow. Fast underflow mode, also known as fastmode, is an alternative to IEEE-754-compliant underflow mode. On Series 700/800 systems, most underflow cases are supported by trapping into the kernel, where the IEEE-mandated conversion of the result into a denormalized value or zero is accomplished by software emulation. On later PA1.1 systems and on all PA2.0 systems, fastmode causes the hardware to simply substitute a zero for the result of an operation, with no fault occurring. This may be a significant performance optimization for applications that underflow frequently. Fastmode also causes denormalized floating-point operands to be treated as if they were true zero operands. .PP .CR fpgetfastmode() returns the current fastmode setting: 1 if fastmode is set, 0 if the default IEEE-754-compliant underflow mode is set. On systems that do not support fastmode, this function returns an undefined value. .PP On systems that support fastmode, .CR fpsetfastmode() sets fastmode to either 1 (fastmode) or 0 (IEEE-754-compliant underflow mode) and returns the previous setting. On systems that do not support fastmode, this function has no effect. .PP .CR fpsetdefaults() changes the default environment, which is .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps disabled .br Fast underflow mode disabled .fi .PP .CR fpsetdefaults() changes these defaults to more useful values. Specifically, it enables traps for the invalid operation, divide-by-zero, and overflow exceptions, while leaving the underflow and inexact-result exception traps disabled. It sets the environment as follows: .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps enabled except underflow and inexact result (\c .CR FP_X_INV + FP_X_DZ + FP_X_OFL\c ) .br Fast underflow mode enabled (if the system supports it) .PP .CR fpgetcontrol() and .CR fpsetcontrol() access the floating-point status register. .PP .CR fpgetcontrol() returns the value of the floating-point status register. The type of the returned value, .CR fp_control , is defined as .CR long in .RC < math.h >. .PP .CR fpsetcontrol() sets the value of the floating-point status register and returns the previous value. For the format of this register, see the .I "HP-UX Floating-Point Guide" or the PA-RISC 1.1 or 2.0 architecture and instruction set reference manual. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH WARNINGS .CR fpsetsticky() modifies all exception flags. .CR fpsetmask() modifies all exception trap enable bits. .PP Both C and FORTRAN require truncation (rounding to zero) for floating-point to integer conversions. The current rounding mode has no effect on these conversions. .\" .\" index@\f4fpgetround()\f1, \f4fpsetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetround()\f1, \f4fpgetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetmask()\f1, \f4fpsetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetmask()\f1, \f4fpgetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetdefaults()\f1 \- set floating-point control register defaults@@@\f3fpgetround(3M)\f1 .\" index@math: floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@rounding mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception trap enable bits (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception flags (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@status register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@underflow mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" index@status register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" .\" toc@\f3fpgetround(3M)\f1:\0\0\f4fpgetround()\f1, \f4fpsetround()\f1, \f4fpgetmask()\f1, \f4fpsetmask()\f1, \f4fpgetsticky()\f1, \n\f4fpsetsticky()\f1, \f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1, \f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1, \n\f4fpsetdefaults()\f1@@@floating-point mode control functions .\" toc@\f4fpsetround()\f1, \f4fpgetround()\f1:\0\0floating-point rounding mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetmask()\f1, \f4fpsetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetmask()\f1, \f4fpgetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetdefaults()\f1:\0\0floating-point control register defaults functions@@@see \f3fpgetround(3M)\f1 .\" .\" links@fpgetround.3m fpsetround.3m .\" links@fpgetround.3m fpgetmask.3m .\" links@fpgetround.3m fpsetmask.3m .\" links@fpgetround.3m fpgetsticky.3m .\" links@fpgetround.3m fpsetsticky.3m .\" links@fpgetround.3m fpgetcontro.3m .\" links@fpgetround.3m fpsetcontro.3m .\" links@fpgetround.3m fpgetfastmo.3m .\" links@fpgetround.3m fpsetfastmo.3m .\" links@fpgetround.3m fpsetdefaul.3m .\" .\" fileset_database@fpgetround.3m PROGRAMING-MAN .\" $Header: fpgetround.3m,v 78.1 96/02/13 10:48:13 ssa Exp $ .TA f .TH fpgetround 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fpgetround(\|), fpsetround(\|), fpgetmask(\|), fpsetmask(\|), fpgetsticky(\|), fpsetsticky(\|), fpsetdefaults(\|), fpgetcontrol(\|), fpsetcontrol(\|), fpgetfastmode(\|), fpsetfastmode(\|) \- floating-point mode-control functions .SH SYNOPSIS .C "#include " .PP .C "fp_rnd fpgetround(void);" .PP .C "fp_rnd fpsetround(fp_rnd mode);" .PP .C "fp_except fpgetmask(void);" .PP .C "fp_except fpsetmask(fp_except value);" .PP .C "fp_except fpgetsticky(void);" .PP .C "fp_except fpsetsticky(fp_except value);" .PP .C "int fpgetfastmode(void);" .PP .C "int fpsetfastmode(int value);" .PP .C "void fpsetdefaults(void);" .PP .C "fp_control fpgetcontrol(void);" .PP .C "fp_control fpsetcontrol(fp_control value);" .PP .SH DESCRIPTION The .CR fpgetround() suite of functions allows programmers to manipulate the floating-point control register (also called the floating-point status register). .PP .CR fpgetround() returns the current rounding mode. The type of the returned value, .CR fp_rnd , is defined as follows in .RC < math.h >: .nf .IP .C "typedef enum {" .C " FP_RZ=0, /* Round toward zero */" .C " FP_RN, /* Round to nearest */" .C " FP_RP, /* Round toward positive infinity */" .C " FP_RM, /* Round toward negative infinity */" .C " } fp_rnd;" .fi .PP The default value is .CR FP_RN . Round-to-nearest mode rounds to the representable value closest to the true value. If two representable values are equally close to the true value, the system chooses the one whose least significant bit is zero. .PP .CR fpsetround() sets the rounding mode to the specified value of type .CR fp_rnd and returns the previous rounding mode. .PP There are five floating-point exceptions: divide-by-zero, overflow, underflow, imprecise (inexact) result, and invalid operation. If a floating-point exception occurs and the corresponding exception trap enable bit is set to 1, the trap takes place. If an exception occurs and the exception trap enable bit is set to 0, the corresponding exception flag is set to 1 and no trap takes place. The exception trap enable bits are sometimes called mask bits; the exception flags are sometimes called sticky bits. The functions .CR fpgetmask() and .CR fpgetsticky() return the current settings of these bits. To change the settings of these bits, use .CR fpsetmask() and .CR fpsetsticky() . .PP .CR fpgetmask() returns the current exception trap enable bits. The type of the returned value, .CR fp_except , is defined as .CR int in .RC < math.h >. The floating-point exception types are defined as follows in .RC < math.h >: .nf .IP .C "#define FP_X_INV 0x10 /* invalid operation exception */" .C "#define FP_X_DZ 0x08 /* divide-by-zero exception */" .C "#define FP_X_OFL 0x04 /* overflow exception */" .C "#define FP_X_UFL 0x02 /* underflow exception */" .C "#define FP_X_IMP 0x01 /* imprecise (inexact result) */" .C "#define FP_X_CLEAR 0x00 /* simply zero to clear all flags */" .fi .PP .CR fpsetmask() sets or clears the exception trap enable bits and returns the previous setting. The argument is an expression of type .CR fp_except . (To set or clear the exception trap enable bits at compile time, use the compiler option .CR +FP\c .IR string ). .PP .CR fpgetsticky() returns the current exception flags. .PP .CR fpsetsticky() sets or clears the exception flags and returns the previous setting. The argument is an expression of type .CR fp_except . .PP .CR fpgetfastmode() and .CR fpsetfastmode() allow the programmer to change the way the system handles underflow. Fast underflow mode, also known as fastmode, is an alternative to IEEE-754-compliant underflow mode. On Series 700/800 systems, most underflow cases are supported by trapping into the kernel, where the IEEE-mandated conversion of the result into a denormalized value or zero is accomplished by software emulation. On later PA1.1 systems and on all PA2.0 systems, fastmode causes the hardware to simply substitute a zero for the result of an operation, with no fault occurring. This may be a significant performance optimization for applications that underflow frequently. Fastmode also causes denormalized floating-point operands to be treated as if they were true zero operands. .PP .CR fpgetfastmode() returns the current fastmode setting: 1 if fastmode is set, 0 if the default IEEE-754-compliant underflow mode is set. On systems that do not support fastmode, this function returns an undefined value. .PP On systems that support fastmode, .CR fpsetfastmode() sets fastmode to either 1 (fastmode) or 0 (IEEE-754-compliant underflow mode) and returns the previous setting. On systems that do not support fastmode, this function has no effect. .PP .CR fpsetdefaults() changes the default environment, which is .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps disabled .br Fast underflow mode disabled .fi .PP .CR fpsetdefaults() changes these defaults to more useful values. Specifically, it enables traps for the invalid operation, divide-by-zero, and overflow exceptions, while leaving the underflow and inexact-result exception traps disabled. It sets the environment as follows: .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps enabled except underflow and inexact result (\c .CR FP_X_INV + FP_X_DZ + FP_X_OFL\c ) .br Fast underflow mode enabled (if the system supports it) .PP .CR fpgetcontrol() and .CR fpsetcontrol() access the floating-point status register. .PP .CR fpgetcontrol() returns the value of the floating-point status register. The type of the returned value, .CR fp_control , is defined as .CR long in .RC < math.h >. .PP .CR fpsetcontrol() sets the value of the floating-point status register and returns the previous value. For the format of this register, see the .I "HP-UX Floating-Point Guide" or the PA-RISC 1.1 or 2.0 architecture and instruction set reference manual. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH WARNINGS .CR fpsetsticky() modifies all exception flags. .CR fpsetmask() modifies all exception trap enable bits. .PP Both C and FORTRAN require truncation (rounding to zero) for floating-point to integer conversions. The current rounding mode has no effect on these conversions. .\" .\" index@\f4fpgetround()\f1, \f4fpsetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetround()\f1, \f4fpgetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetmask()\f1, \f4fpsetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetmask()\f1, \f4fpgetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetdefaults()\f1 \- set floating-point control register defaults@@@\f3fpgetround(3M)\f1 .\" index@math: floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@rounding mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception trap enable bits (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception flags (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@status register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@underflow mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" index@status register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" .\" toc@\f3fpgetround(3M)\f1:\0\0\f4fpgetround()\f1, \f4fpsetround()\f1, \f4fpgetmask()\f1, \f4fpsetmask()\f1, \f4fpgetsticky()\f1, \n\f4fpsetsticky()\f1, \f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1, \f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1, \n\f4fpsetdefaults()\f1@@@floating-point mode control functions .\" toc@\f4fpsetround()\f1, \f4fpgetround()\f1:\0\0floating-point rounding mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetmask()\f1, \f4fpsetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetmask()\f1, \f4fpgetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetdefaults()\f1:\0\0floating-point control register defaults functions@@@see \f3fpgetround(3M)\f1 .\" .\" links@fpgetround.3m fpsetround.3m .\" links@fpgetround.3m fpgetmask.3m .\" links@fpgetround.3m fpsetmask.3m .\" links@fpgetround.3m fpgetsticky.3m .\" links@fpgetround.3m fpsetsticky.3m .\" links@fpgetround.3m fpgetcontro.3m .\" links@fpgetround.3m fpsetcontro.3m .\" links@fpgetround.3m fpgetfastmo.3m .\" links@fpgetround.3m fpsetfastmo.3m .\" links@fpgetround.3m fpsetdefaul.3m .\" .\" fileset_database@fpgetround.3m PROGRAMING-MAN .\" $Header: printf.3s,v 72.8 94/11/30 15:46:16 ssa Exp $ .TA p .TH printf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME printf(), fprintf(), sprintf() \- print formatted output .SH SYNOPSIS .C "#include " .PP .C "int printf(const char *format, /* [arg,] */ ...);" .PP .C "int fprintf(FILE *stream, const char *format, /* [arg,] */ ...);" .PP .C "int sprintf(char *s, const char *format, /* [arg,] */ ...);" .SH DESCRIPTION .CR printf() places output on the standard output stream .IR stdout . .PP .CR fprintf() places output on the named output .IR stream . .PP .CR sprintf() places ``output'', followed by the null character .RC ( \e0 ), in consecutive bytes starting at .CI * s \f1. It is the user's responsibility to ensure that enough storage is available. .PP Each function converts, formats, and prints its .IR arg s under control of the .IR format . .I format is a character string containing two types of objects: plain characters that are copied to the output stream, and conversion specifications, each of which results in fetching zero or more .IR arg s. The results are undefined if there are insufficient .IR arg s for the format. If the format is exhausted while .IR arg s remain, excess .IR arg s are ignored. .PP Each conversion specification is introduced by the character .CR % or .CI % n $\f1, where .I n is a decimal integer in the range 1 through .C {NL_ARGMAX} .RC ( NL_ARGMAX is defined in .CR ). The .CI % n $ construction indicates that this conversion should be applied to the .IR n th argument, rather than to the next unused one. .PP An argument can be referenced by a .CI % n $ specification more than once. The two forms of introducing a conversion specification, .CR % and .CI % n $\f1, cannot be mixed within a single .I format string. When numbered argument specifications are used, specifying the Nth argument requires that all the leading arguments, from the first to the (N-1)th, are specified in the format string. Improper use of .CI % n $ in a format string results in a negative return value. .PP After the .CR % or .CI % n $\f1, the following appear in sequence: .RS .TP 5 1. Zero or more .IR flags , which modify the meaning of the conversion specification. .TP 2. An optional string of decimal digits to specify a minimum .I field width in bytes. If the converted value has fewer characters than the field width, it is be padded on the left (or right, if the left-adjustment flag .RC ( - ), described below, has been given) to the field width. If the field width is preceded by a zero, the string is right adjusted with zero-padding on the left (see the leading-zero flag, .CR 0 , described below). .TP 3. A .I precision that gives the minimum number of digits to appear for the .CR d , .CR i , .CR o , .CR u , .CR x , or .CR X conversions, the number of digits to appear after the radix character for the .CR e and .CR f conversions, the maximum number of significant digits for the .CR g conversion, or the maximum number of bytes to be printed from a string in the .CR s conversion. The .I precision takes the form of a period followed by a decimal digit string; a null digit string is treated as zero. .TP 4. An optional .CR l (the letter ``ell''), specifying that a following .CR d , .CR i , .CR o , .CR u , .CR x , or .CR X conversion character applies to a long integer .IR arg ; an optional .CR l specifying that a following .CR n conversion character applies to a pointer to a long integer .IR arg ; an optional .CR h , specifying that a following .CR d , .CR i , .CR o , .CR u , .CR x , or .CR X conversion character applies to a short integer .IR arg ; an optional .CR ll , specifying that a following .CR d , .CR i , .CR o , .CR u , .CR x , or .CR X conversion character applies to a long long integer arg; an optional .CR h specifying that a following .CR n conversion character applies to a pointer to a short integer .IR arg ; an optional .C L specifying that a following .CR e , .CR E , .CR f , .CR g , or .CR G conversion character applies to a long double .IR arg . An .CR l , .CR h , .CR ll or .CR L before any other conversion character is ignored. .TP 5. A conversion character that indicates the type of conversion to be applied. .RE .ift .ne 10 .PP A field width or precision can be indicated by an asterisk instead of a digit string. In this case, an integer .I arg supplies the field width or precision. The .I arg that is actually converted is not fetched until the conversion letter is seen, so the .IR arg s specifying field width, or precision, or both must appear in that order before the .IR arg , if any, to be converted. A negative field width is taken as a .CR - flag followed by a positive field width. A negative precision is taken as if the precision were omitted. Format strings containing .CI % n $ conversion specifications can also indicate a field width or precision by the sequence .CI * n $\f1. The .I n indicates the position of an integer .I arg . With the .CI * n $ sequence, the .IR arg s specifying field width or precision can appear before or after the .I arg to be converted. .PP The flag characters and their meanings are: .RS .TP 10 .C ' The integer portion of the result of a decimal conversion (%i, %d, %u, %f, %g, or %G) will be formatted with thousands' grouping characters. For other conversions the behavior is undefined. The nonmonetary grouping character is used. .TP .C - The resulting conversion is left-justified within the field. .TP .C + The resulting signed conversion always begins with a sign .RC ( + or .CR - ). .TP blank If the first character of a signed conversion is not a sign, a blank is prefixed to the result. This implies that if the blank and .CR + flags both appear, the blank flag is ignored. .TP .C # This flag specifies that the value is converted to an .IR `` alternate form ''. For .CR c , .CR d , .CR i , .CR s , .CR n , and .CR u conversions, the flag has no effect. For .CR o conversion, it increases the precision to force the first digit of the result to be a zero. For .CR x or .CR X conversion, a nonzero result is prefixed by .CR 0x or .CR 0X . For a .CR p conversion, a nonzero result is prefixed by .CR 0x . For .CR e , .CR E , .CR f , .CR g , and .CR G conversions, the result always contains a radix character, even if no digits follow the radix. (Normally, a radix character appears in the resulting conversions only if followed by a digit). For .CR g and .CR G conversions, trailing zeros are .I not removed from the result (which they normally are). .TP .C 0 Leading zeros (following any indication of sign or base) are used to pad to the field width for all conversion characters. No space padding is performed. If both the .CR 0 and .CR - appear, the .CR 0 flag is ignored. For .CR d , .CR i , .CR o , .CR u , .CR p , .CR x , and .CR X , conversions, if a precision is specified, the .CR 0 flag is ignored. .RE .PP The conversion characters and their meanings are: .RS .TP 15 .ift \f4\s+1d\fP\s0,\f4\s+1i\fP\s0,\f4\s+1o\fP\s0,\f4\s+1u\fP\s0,\f4\s+1x\fP\s0,\f4\s+1X\fP\s0 .ifn \f3d\fP,\f3i\fP,\f3o\fP,\f3u\fP,\f3x\fP,\f3X\fP The integer .I arg is converted to signed decimal .RC ( d and .CR i are identical), unsigned octal .RC ( o ), decimal .RC ( u ), or hexadecimal notation .RC ( x and .CR X ), respectively; the letters .CR abcdef are used for .CR x conversion and the letters .CR ABCDEF for .CR X conversion. The precision specifies the minimum number of digits to appear. If the value being converted can be represented in fewer digits, it is expanded with leading zeros. (For compatibility with older versions, padding with leading zeros can alternatively be specified by inserting a zero in front of the field width. This does not imply an octal value for the field width). The default precision is 1. The result of converting a zero value with a precision of zero is a null string. .TP .C f The double .I arg is converted to decimal notation in the style .RC [ - ]\c .CI ddd r ddd , where .I r is the radix character. The number of digits after the radix character is equal to the precision specification. If the precision is missing, six digits are output. If the precision is explicitly zero, no radix character appears. .TP .CR e , E The double .I arg is converted in the style .RC [ - ]\c .CI d r ddde\(+-ddd , where .CR r is the radix character. There is one digit before the radix character and the number of digits after it is equal to the precision; when the precision is missing, six digits are produced; if the precision is zero, no radix character appears. The .CR E format code produces a number with .CR E instead of .CR e introducing the exponent. The exponent always contains at least two digits. .TP .CR g , G The double .I arg is printed in style .CR f or .CR e (or in style .CR E in the case of a .CR G format code), with the precision specifying the number of significant digits. The style used depends on the value converted: style .CR e is used only if the exponent resulting from the conversion is less than .CR \-4 or greater than or equal to the precision. Trailing zeros are removed from the fractional part of the result; a radix character appears only if it is followed by a digit. .TP .C c The integer .I arg is converted to an unsigned char, and the resulting character is printed. .TP .C C The .CR wchar_t .I arg is converted to an array of bytes representing the single wide character according to the setting of .CR LC_CTYPE . Resulting bytes are printed. If the precision is given, it is ignored. If the field width would otherwise cause the wide character to be split, the wide character is printed and the field width is adjusted upward. .TP .C s The .I arg is taken to be a string (character pointer) and characters from the string are printed until a null character .RC ( \e0 ) is encountered or the number of bytes indicated by the precision specification is reached. If the precision is missing, it is taken to be infinite, so all characters up to the first null character are printed. A NULL value for .I arg yields undefined results. .TP .C S The .I arg is taken to be a pointer to a wide character string .RC ( "wchar_t *" ). Wide characters from the string are converted to an array of bytes representing the string of wide characters according to the setting of .CR LC_CTYPE . Resulting bytes are printed until a null wide character .RC ( (wchar_t)0 ) is encountered or the number of bytes indicated by the precision is reached. If the precision is missing, it is taken to be infinite, so all wide characters up to the first null wide character are printed. If the field width would otherwise cause the last multibyte character to be split, the last wide character is not printed. A NULL value for .I arg yields undefined results. .TP .C p The value of a pointer to void .I arg is printed as a sequence of unsigned hexadecimal numbers. The precision specifies the minimum number of digits to appear. If the value being converted can be represented in fewer digits, it is expanded with leading zeros. The default precision is 1. The result of converting a zero value with a precision of zero is a null string. .TP .C n A pointer to an integer .I arg is expected. This pointer is used to store the number of bytes printed on the output stream so far by this call to the function. No argument is converted. .TP .C % Print a .CR % ; no argument is converted. .RE .PP In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result. .PP Characters generated by .CR printf() , and .CR fprintf() are printed as if .CR putc() had been called (see .IR putc (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category affects the following features: .RS .TP 3 \(bu Plain characters within format strings are interpreted as single byte and/or multibyte characters. .TP \(bu Field width is given in terms of bytes. As characters are placed on the output stream, they are interpreted as single byte or multibyte characters and the field width is decremented by the length of the character. .TP \(bu Precision is given in terms of bytes. As characters are placed on the output stream, they are interpreted as single byte or multibyte characters and the precision is decremented by the length of the character. .TP \(bu The return value is given in terms of bytes. As characters are placed on the output stream, they are interpreted as single byte or multibyte characters and the byte count that makes up the return value is incremented by the length of the character. .RE .PP The .CR LC_NUMERIC category determines the radix character used to print floating-point numbers, and the thousands' grouping characters if the grouping flag .CR ' is on. .SS International Code Set Support Single byte character code sets are supported. Multibyte character code sets are also supported as described in the .CR LC_CTYPE category above. .SH RETURN VALUE Each function returns the number of bytes transmitted (excluding the .CR \e0 in the case of .CR sprintf() or a negative value if an output error was encountered. Improper use of .CI % n $ in a format string results in a negative return value. .SH ERRORS .CR printf() , and .CR fprintf() fail if either the .I stream is unbuffered or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked (see .IR write (2)), and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH EXAMPLES To print a date and time in the form "Sunday, July 3, 10:02", where .I weekday and .I month are pointers to null-terminated strings: .RS .nh .PP .ift\f4\s+1printf("%s,\ %s\ %d,\ %d:%.2d",\ weekday,\ month,\ day,\ hour,\ min);\fP\s0 .ifn\f3printf("%s,\ %s\ %d,\ %d:%.2d",\ weekday,\ month,\ day,\ hour,\ min);\fP .RE .PP To print .if n .I pi .if t \(*p to 5 decimal places: .RS .PP .ift \f4\s+1printf("pi \|= \|%.5f", \|4 \(** atan(1\f3.\fP0));\fP\s0 .ifn \f3printf("pi \|= \|%.5f", \|4 \(** atan(1\f3.\fP0));\fP .RE .PP To create a language independent date-and-time printing routine write: .RS .PP .ift \f4\s+1printf(format,weekday,month,day,hour,min,2,2);\fP\s0 .ifn \f3printf(format,weekday,month,day,hour,min,2,2);\fP .RE .PP For American usage, .IR format would point to the string: .IP .ift \f4\s+1"%1$s, %2$s %3$d, %4$*6$.*7$d:%5$*6$.*7$d"\fP\s0 .ifn \f3"%1$s, %2$s %3$d, %4$*6$.*7$d:%5$*6$.*7$d"\fP .PP and result in the output: .IP .ift \f4\s+1"Sunday, July 3, 10:02"\fP\s0 .ifn \f4"Sunday, July 3, 10:02"\fP .PP For German usage, the string: .IP .ift \f4\s+1"%1$s, %3$s %2$d, %4$*6$.*7$d:%5$*6$.*7$d"\fP\s0 .ifn \f3"%1$s, %3$s %2$d, %4$*6$.*7$d:%5$*6$.*7$d"\fP .PP results in the output: .IP .C "Sonntag, 3 Juli 10:02" .SH WARNINGS Notice that with the .CR c conversion character, an int .I arg is converted to an unsigned char. Hence, whole multibyte characters cannot be printed using a single .CR c conversion character. .PP A precision with the .CR s conversion character might result in the truncation of a multibyte character. .SH AUTHOR .CR printf() , .CR fprintf() , and .CR sprintf() were developed by AT&T and HP. .SH SEE ALSO ecvt(3C), ltostr(3C), setlocale(3C), putc(3S), scanf(3S), stdio(3S). .SH STANDARDS CONFORMANCE .CR printf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR sprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4printf()\f1 \- print formatted output to standard output@@@\f3printf(3S)\f1 .\" index@\f4fprintf()\f1 \- print formatted output to a file@@@\f3printf(3S)\f1 .\" index@\f4sprintf()\f1 \- print formatted output to a string@@@\f3printf(3S)\f1 .\" index@\f1print formatted output to standard output, file, or string@@@\f3printf(3S)\f1 .\" index@\f1formatted output, print to standard output, file, or string@@@\f3printf(3S)\f1 .\" index@\f1output, formatted, print to standard output, file, or string@@@\f3printf(3S)\f1 .\" .\" toc@\f3printf(3S)\f1:\0\0\f4printf()\f1, \f4fprintf()\f1, \f4sprintf()\f1@@@print formatted output .\" toc@\f4fprintf()\f1:\0\0print formatted output to a file@@@\f1see \f3printf(3S)\f1 .\" toc@\f4sprintf()\f1:\0\0print formatted output to a string@@@\f1see \f3printf(3S)\f1 .\" .\" links@printf.3s fprintf.3s .\" links@printf.3s sprintf.3s .\" $Header: fpgetround.3m,v 78.1 96/02/13 10:48:13 ssa Exp $ .TA f .TH fpgetround 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fpgetround(\|), fpsetround(\|), fpgetmask(\|), fpsetmask(\|), fpgetsticky(\|), fpsetsticky(\|), fpsetdefaults(\|), fpgetcontrol(\|), fpsetcontrol(\|), fpgetfastmode(\|), fpsetfastmode(\|) \- floating-point mode-control functions .SH SYNOPSIS .C "#include " .PP .C "fp_rnd fpgetround(void);" .PP .C "fp_rnd fpsetround(fp_rnd mode);" .PP .C "fp_except fpgetmask(void);" .PP .C "fp_except fpsetmask(fp_except value);" .PP .C "fp_except fpgetsticky(void);" .PP .C "fp_except fpsetsticky(fp_except value);" .PP .C "int fpgetfastmode(void);" .PP .C "int fpsetfastmode(int value);" .PP .C "void fpsetdefaults(void);" .PP .C "fp_control fpgetcontrol(void);" .PP .C "fp_control fpsetcontrol(fp_control value);" .PP .SH DESCRIPTION The .CR fpgetround() suite of functions allows programmers to manipulate the floating-point control register (also called the floating-point status register). .PP .CR fpgetround() returns the current rounding mode. The type of the returned value, .CR fp_rnd , is defined as follows in .RC < math.h >: .nf .IP .C "typedef enum {" .C " FP_RZ=0, /* Round toward zero */" .C " FP_RN, /* Round to nearest */" .C " FP_RP, /* Round toward positive infinity */" .C " FP_RM, /* Round toward negative infinity */" .C " } fp_rnd;" .fi .PP The default value is .CR FP_RN . Round-to-nearest mode rounds to the representable value closest to the true value. If two representable values are equally close to the true value, the system chooses the one whose least significant bit is zero. .PP .CR fpsetround() sets the rounding mode to the specified value of type .CR fp_rnd and returns the previous rounding mode. .PP There are five floating-point exceptions: divide-by-zero, overflow, underflow, imprecise (inexact) result, and invalid operation. If a floating-point exception occurs and the corresponding exception trap enable bit is set to 1, the trap takes place. If an exception occurs and the exception trap enable bit is set to 0, the corresponding exception flag is set to 1 and no trap takes place. The exception trap enable bits are sometimes called mask bits; the exception flags are sometimes called sticky bits. The functions .CR fpgetmask() and .CR fpgetsticky() return the current settings of these bits. To change the settings of these bits, use .CR fpsetmask() and .CR fpsetsticky() . .PP .CR fpgetmask() returns the current exception trap enable bits. The type of the returned value, .CR fp_except , is defined as .CR int in .RC < math.h >. The floating-point exception types are defined as follows in .RC < math.h >: .nf .IP .C "#define FP_X_INV 0x10 /* invalid operation exception */" .C "#define FP_X_DZ 0x08 /* divide-by-zero exception */" .C "#define FP_X_OFL 0x04 /* overflow exception */" .C "#define FP_X_UFL 0x02 /* underflow exception */" .C "#define FP_X_IMP 0x01 /* imprecise (inexact result) */" .C "#define FP_X_CLEAR 0x00 /* simply zero to clear all flags */" .fi .PP .CR fpsetmask() sets or clears the exception trap enable bits and returns the previous setting. The argument is an expression of type .CR fp_except . (To set or clear the exception trap enable bits at compile time, use the compiler option .CR +FP\c .IR string ). .PP .CR fpgetsticky() returns the current exception flags. .PP .CR fpsetsticky() sets or clears the exception flags and returns the previous setting. The argument is an expression of type .CR fp_except . .PP .CR fpgetfastmode() and .CR fpsetfastmode() allow the programmer to change the way the system handles underflow. Fast underflow mode, also known as fastmode, is an alternative to IEEE-754-compliant underflow mode. On Series 700/800 systems, most underflow cases are supported by trapping into the kernel, where the IEEE-mandated conversion of the result into a denormalized value or zero is accomplished by software emulation. On later PA1.1 systems and on all PA2.0 systems, fastmode causes the hardware to simply substitute a zero for the result of an operation, with no fault occurring. This may be a significant performance optimization for applications that underflow frequently. Fastmode also causes denormalized floating-point operands to be treated as if they were true zero operands. .PP .CR fpgetfastmode() returns the current fastmode setting: 1 if fastmode is set, 0 if the default IEEE-754-compliant underflow mode is set. On systems that do not support fastmode, this function returns an undefined value. .PP On systems that support fastmode, .CR fpsetfastmode() sets fastmode to either 1 (fastmode) or 0 (IEEE-754-compliant underflow mode) and returns the previous setting. On systems that do not support fastmode, this function has no effect. .PP .CR fpsetdefaults() changes the default environment, which is .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps disabled .br Fast underflow mode disabled .fi .PP .CR fpsetdefaults() changes these defaults to more useful values. Specifically, it enables traps for the invalid operation, divide-by-zero, and overflow exceptions, while leaving the underflow and inexact-result exception traps disabled. It sets the environment as follows: .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps enabled except underflow and inexact result (\c .CR FP_X_INV + FP_X_DZ + FP_X_OFL\c ) .br Fast underflow mode enabled (if the system supports it) .PP .CR fpgetcontrol() and .CR fpsetcontrol() access the floating-point status register. .PP .CR fpgetcontrol() returns the value of the floating-point status register. The type of the returned value, .CR fp_control , is defined as .CR long in .RC < math.h >. .PP .CR fpsetcontrol() sets the value of the floating-point status register and returns the previous value. For the format of this register, see the .I "HP-UX Floating-Point Guide" or the PA-RISC 1.1 or 2.0 architecture and instruction set reference manual. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH WARNINGS .CR fpsetsticky() modifies all exception flags. .CR fpsetmask() modifies all exception trap enable bits. .PP Both C and FORTRAN require truncation (rounding to zero) for floating-point to integer conversions. The current rounding mode has no effect on these conversions. .\" .\" index@\f4fpgetround()\f1, \f4fpsetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetround()\f1, \f4fpgetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetmask()\f1, \f4fpsetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetmask()\f1, \f4fpgetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetdefaults()\f1 \- set floating-point control register defaults@@@\f3fpgetround(3M)\f1 .\" index@math: floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@rounding mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception trap enable bits (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception flags (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@status register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@underflow mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" index@status register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" .\" toc@\f3fpgetround(3M)\f1:\0\0\f4fpgetround()\f1, \f4fpsetround()\f1, \f4fpgetmask()\f1, \f4fpsetmask()\f1, \f4fpgetsticky()\f1, \n\f4fpsetsticky()\f1, \f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1, \f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1, \n\f4fpsetdefaults()\f1@@@floating-point mode control functions .\" toc@\f4fpsetround()\f1, \f4fpgetround()\f1:\0\0floating-point rounding mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetmask()\f1, \f4fpsetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetmask()\f1, \f4fpgetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetdefaults()\f1:\0\0floating-point control register defaults functions@@@see \f3fpgetround(3M)\f1 .\" .\" links@fpgetround.3m fpsetround.3m .\" links@fpgetround.3m fpgetmask.3m .\" links@fpgetround.3m fpsetmask.3m .\" links@fpgetround.3m fpgetsticky.3m .\" links@fpgetround.3m fpsetsticky.3m .\" links@fpgetround.3m fpgetcontro.3m .\" links@fpgetround.3m fpsetcontro.3m .\" links@fpgetround.3m fpgetfastmo.3m .\" links@fpgetround.3m fpsetfastmo.3m .\" links@fpgetround.3m fpsetdefaul.3m .\" .\" fileset_database@fpgetround.3m PROGRAMING-MAN .\" $Header: fpgetround.3m,v 78.1 96/02/13 10:48:13 ssa Exp $ .TA f .TH fpgetround 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fpgetround(\|), fpsetround(\|), fpgetmask(\|), fpsetmask(\|), fpgetsticky(\|), fpsetsticky(\|), fpsetdefaults(\|), fpgetcontrol(\|), fpsetcontrol(\|), fpgetfastmode(\|), fpsetfastmode(\|) \- floating-point mode-control functions .SH SYNOPSIS .C "#include " .PP .C "fp_rnd fpgetround(void);" .PP .C "fp_rnd fpsetround(fp_rnd mode);" .PP .C "fp_except fpgetmask(void);" .PP .C "fp_except fpsetmask(fp_except value);" .PP .C "fp_except fpgetsticky(void);" .PP .C "fp_except fpsetsticky(fp_except value);" .PP .C "int fpgetfastmode(void);" .PP .C "int fpsetfastmode(int value);" .PP .C "void fpsetdefaults(void);" .PP .C "fp_control fpgetcontrol(void);" .PP .C "fp_control fpsetcontrol(fp_control value);" .PP .SH DESCRIPTION The .CR fpgetround() suite of functions allows programmers to manipulate the floating-point control register (also called the floating-point status register). .PP .CR fpgetround() returns the current rounding mode. The type of the returned value, .CR fp_rnd , is defined as follows in .RC < math.h >: .nf .IP .C "typedef enum {" .C " FP_RZ=0, /* Round toward zero */" .C " FP_RN, /* Round to nearest */" .C " FP_RP, /* Round toward positive infinity */" .C " FP_RM, /* Round toward negative infinity */" .C " } fp_rnd;" .fi .PP The default value is .CR FP_RN . Round-to-nearest mode rounds to the representable value closest to the true value. If two representable values are equally close to the true value, the system chooses the one whose least significant bit is zero. .PP .CR fpsetround() sets the rounding mode to the specified value of type .CR fp_rnd and returns the previous rounding mode. .PP There are five floating-point exceptions: divide-by-zero, overflow, underflow, imprecise (inexact) result, and invalid operation. If a floating-point exception occurs and the corresponding exception trap enable bit is set to 1, the trap takes place. If an exception occurs and the exception trap enable bit is set to 0, the corresponding exception flag is set to 1 and no trap takes place. The exception trap enable bits are sometimes called mask bits; the exception flags are sometimes called sticky bits. The functions .CR fpgetmask() and .CR fpgetsticky() return the current settings of these bits. To change the settings of these bits, use .CR fpsetmask() and .CR fpsetsticky() . .PP .CR fpgetmask() returns the current exception trap enable bits. The type of the returned value, .CR fp_except , is defined as .CR int in .RC < math.h >. The floating-point exception types are defined as follows in .RC < math.h >: .nf .IP .C "#define FP_X_INV 0x10 /* invalid operation exception */" .C "#define FP_X_DZ 0x08 /* divide-by-zero exception */" .C "#define FP_X_OFL 0x04 /* overflow exception */" .C "#define FP_X_UFL 0x02 /* underflow exception */" .C "#define FP_X_IMP 0x01 /* imprecise (inexact result) */" .C "#define FP_X_CLEAR 0x00 /* simply zero to clear all flags */" .fi .PP .CR fpsetmask() sets or clears the exception trap enable bits and returns the previous setting. The argument is an expression of type .CR fp_except . (To set or clear the exception trap enable bits at compile time, use the compiler option .CR +FP\c .IR string ). .PP .CR fpgetsticky() returns the current exception flags. .PP .CR fpsetsticky() sets or clears the exception flags and returns the previous setting. The argument is an expression of type .CR fp_except . .PP .CR fpgetfastmode() and .CR fpsetfastmode() allow the programmer to change the way the system handles underflow. Fast underflow mode, also known as fastmode, is an alternative to IEEE-754-compliant underflow mode. On Series 700/800 systems, most underflow cases are supported by trapping into the kernel, where the IEEE-mandated conversion of the result into a denormalized value or zero is accomplished by software emulation. On later PA1.1 systems and on all PA2.0 systems, fastmode causes the hardware to simply substitute a zero for the result of an operation, with no fault occurring. This may be a significant performance optimization for applications that underflow frequently. Fastmode also causes denormalized floating-point operands to be treated as if they were true zero operands. .PP .CR fpgetfastmode() returns the current fastmode setting: 1 if fastmode is set, 0 if the default IEEE-754-compliant underflow mode is set. On systems that do not support fastmode, this function returns an undefined value. .PP On systems that support fastmode, .CR fpsetfastmode() sets fastmode to either 1 (fastmode) or 0 (IEEE-754-compliant underflow mode) and returns the previous setting. On systems that do not support fastmode, this function has no effect. .PP .CR fpsetdefaults() changes the default environment, which is .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps disabled .br Fast underflow mode disabled .fi .PP .CR fpsetdefaults() changes these defaults to more useful values. Specifically, it enables traps for the invalid operation, divide-by-zero, and overflow exceptions, while leaving the underflow and inexact-result exception traps disabled. It sets the environment as follows: .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps enabled except underflow and inexact result (\c .CR FP_X_INV + FP_X_DZ + FP_X_OFL\c ) .br Fast underflow mode enabled (if the system supports it) .PP .CR fpgetcontrol() and .CR fpsetcontrol() access the floating-point status register. .PP .CR fpgetcontrol() returns the value of the floating-point status register. The type of the returned value, .CR fp_control , is defined as .CR long in .RC < math.h >. .PP .CR fpsetcontrol() sets the value of the floating-point status register and returns the previous value. For the format of this register, see the .I "HP-UX Floating-Point Guide" or the PA-RISC 1.1 or 2.0 architecture and instruction set reference manual. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH WARNINGS .CR fpsetsticky() modifies all exception flags. .CR fpsetmask() modifies all exception trap enable bits. .PP Both C and FORTRAN require truncation (rounding to zero) for floating-point to integer conversions. The current rounding mode has no effect on these conversions. .\" .\" index@\f4fpgetround()\f1, \f4fpsetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetround()\f1, \f4fpgetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetmask()\f1, \f4fpsetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetmask()\f1, \f4fpgetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetdefaults()\f1 \- set floating-point control register defaults@@@\f3fpgetround(3M)\f1 .\" index@math: floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@rounding mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception trap enable bits (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception flags (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@status register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@underflow mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" index@status register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" .\" toc@\f3fpgetround(3M)\f1:\0\0\f4fpgetround()\f1, \f4fpsetround()\f1, \f4fpgetmask()\f1, \f4fpsetmask()\f1, \f4fpgetsticky()\f1, \n\f4fpsetsticky()\f1, \f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1, \f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1, \n\f4fpsetdefaults()\f1@@@floating-point mode control functions .\" toc@\f4fpsetround()\f1, \f4fpgetround()\f1:\0\0floating-point rounding mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetmask()\f1, \f4fpsetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetmask()\f1, \f4fpgetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetdefaults()\f1:\0\0floating-point control register defaults functions@@@see \f3fpgetround(3M)\f1 .\" .\" links@fpgetround.3m fpsetround.3m .\" links@fpgetround.3m fpgetmask.3m .\" links@fpgetround.3m fpsetmask.3m .\" links@fpgetround.3m fpgetsticky.3m .\" links@fpgetround.3m fpsetsticky.3m .\" links@fpgetround.3m fpgetcontro.3m .\" links@fpgetround.3m fpsetcontro.3m .\" links@fpgetround.3m fpgetfastmo.3m .\" links@fpgetround.3m fpsetfastmo.3m .\" links@fpgetround.3m fpsetdefaul.3m .\" .\" fileset_database@fpgetround.3m PROGRAMING-MAN .\" $Header: fpgetround.3m,v 78.1 96/02/13 10:48:13 ssa Exp $ .TA f .TH fpgetround 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fpgetround(\|), fpsetround(\|), fpgetmask(\|), fpsetmask(\|), fpgetsticky(\|), fpsetsticky(\|), fpsetdefaults(\|), fpgetcontrol(\|), fpsetcontrol(\|), fpgetfastmode(\|), fpsetfastmode(\|) \- floating-point mode-control functions .SH SYNOPSIS .C "#include " .PP .C "fp_rnd fpgetround(void);" .PP .C "fp_rnd fpsetround(fp_rnd mode);" .PP .C "fp_except fpgetmask(void);" .PP .C "fp_except fpsetmask(fp_except value);" .PP .C "fp_except fpgetsticky(void);" .PP .C "fp_except fpsetsticky(fp_except value);" .PP .C "int fpgetfastmode(void);" .PP .C "int fpsetfastmode(int value);" .PP .C "void fpsetdefaults(void);" .PP .C "fp_control fpgetcontrol(void);" .PP .C "fp_control fpsetcontrol(fp_control value);" .PP .SH DESCRIPTION The .CR fpgetround() suite of functions allows programmers to manipulate the floating-point control register (also called the floating-point status register). .PP .CR fpgetround() returns the current rounding mode. The type of the returned value, .CR fp_rnd , is defined as follows in .RC < math.h >: .nf .IP .C "typedef enum {" .C " FP_RZ=0, /* Round toward zero */" .C " FP_RN, /* Round to nearest */" .C " FP_RP, /* Round toward positive infinity */" .C " FP_RM, /* Round toward negative infinity */" .C " } fp_rnd;" .fi .PP The default value is .CR FP_RN . Round-to-nearest mode rounds to the representable value closest to the true value. If two representable values are equally close to the true value, the system chooses the one whose least significant bit is zero. .PP .CR fpsetround() sets the rounding mode to the specified value of type .CR fp_rnd and returns the previous rounding mode. .PP There are five floating-point exceptions: divide-by-zero, overflow, underflow, imprecise (inexact) result, and invalid operation. If a floating-point exception occurs and the corresponding exception trap enable bit is set to 1, the trap takes place. If an exception occurs and the exception trap enable bit is set to 0, the corresponding exception flag is set to 1 and no trap takes place. The exception trap enable bits are sometimes called mask bits; the exception flags are sometimes called sticky bits. The functions .CR fpgetmask() and .CR fpgetsticky() return the current settings of these bits. To change the settings of these bits, use .CR fpsetmask() and .CR fpsetsticky() . .PP .CR fpgetmask() returns the current exception trap enable bits. The type of the returned value, .CR fp_except , is defined as .CR int in .RC < math.h >. The floating-point exception types are defined as follows in .RC < math.h >: .nf .IP .C "#define FP_X_INV 0x10 /* invalid operation exception */" .C "#define FP_X_DZ 0x08 /* divide-by-zero exception */" .C "#define FP_X_OFL 0x04 /* overflow exception */" .C "#define FP_X_UFL 0x02 /* underflow exception */" .C "#define FP_X_IMP 0x01 /* imprecise (inexact result) */" .C "#define FP_X_CLEAR 0x00 /* simply zero to clear all flags */" .fi .PP .CR fpsetmask() sets or clears the exception trap enable bits and returns the previous setting. The argument is an expression of type .CR fp_except . (To set or clear the exception trap enable bits at compile time, use the compiler option .CR +FP\c .IR string ). .PP .CR fpgetsticky() returns the current exception flags. .PP .CR fpsetsticky() sets or clears the exception flags and returns the previous setting. The argument is an expression of type .CR fp_except . .PP .CR fpgetfastmode() and .CR fpsetfastmode() allow the programmer to change the way the system handles underflow. Fast underflow mode, also known as fastmode, is an alternative to IEEE-754-compliant underflow mode. On Series 700/800 systems, most underflow cases are supported by trapping into the kernel, where the IEEE-mandated conversion of the result into a denormalized value or zero is accomplished by software emulation. On later PA1.1 systems and on all PA2.0 systems, fastmode causes the hardware to simply substitute a zero for the result of an operation, with no fault occurring. This may be a significant performance optimization for applications that underflow frequently. Fastmode also causes denormalized floating-point operands to be treated as if they were true zero operands. .PP .CR fpgetfastmode() returns the current fastmode setting: 1 if fastmode is set, 0 if the default IEEE-754-compliant underflow mode is set. On systems that do not support fastmode, this function returns an undefined value. .PP On systems that support fastmode, .CR fpsetfastmode() sets fastmode to either 1 (fastmode) or 0 (IEEE-754-compliant underflow mode) and returns the previous setting. On systems that do not support fastmode, this function has no effect. .PP .CR fpsetdefaults() changes the default environment, which is .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps disabled .br Fast underflow mode disabled .fi .PP .CR fpsetdefaults() changes these defaults to more useful values. Specifically, it enables traps for the invalid operation, divide-by-zero, and overflow exceptions, while leaving the underflow and inexact-result exception traps disabled. It sets the environment as follows: .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps enabled except underflow and inexact result (\c .CR FP_X_INV + FP_X_DZ + FP_X_OFL\c ) .br Fast underflow mode enabled (if the system supports it) .PP .CR fpgetcontrol() and .CR fpsetcontrol() access the floating-point status register. .PP .CR fpgetcontrol() returns the value of the floating-point status register. The type of the returned value, .CR fp_control , is defined as .CR long in .RC < math.h >. .PP .CR fpsetcontrol() sets the value of the floating-point status register and returns the previous value. For the format of this register, see the .I "HP-UX Floating-Point Guide" or the PA-RISC 1.1 or 2.0 architecture and instruction set reference manual. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH WARNINGS .CR fpsetsticky() modifies all exception flags. .CR fpsetmask() modifies all exception trap enable bits. .PP Both C and FORTRAN require truncation (rounding to zero) for floating-point to integer conversions. The current rounding mode has no effect on these conversions. .\" .\" index@\f4fpgetround()\f1, \f4fpsetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetround()\f1, \f4fpgetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetmask()\f1, \f4fpsetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetmask()\f1, \f4fpgetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetdefaults()\f1 \- set floating-point control register defaults@@@\f3fpgetround(3M)\f1 .\" index@math: floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@rounding mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception trap enable bits (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception flags (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@status register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@underflow mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" index@status register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" .\" toc@\f3fpgetround(3M)\f1:\0\0\f4fpgetround()\f1, \f4fpsetround()\f1, \f4fpgetmask()\f1, \f4fpsetmask()\f1, \f4fpgetsticky()\f1, \n\f4fpsetsticky()\f1, \f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1, \f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1, \n\f4fpsetdefaults()\f1@@@floating-point mode control functions .\" toc@\f4fpsetround()\f1, \f4fpgetround()\f1:\0\0floating-point rounding mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetmask()\f1, \f4fpsetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetmask()\f1, \f4fpgetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetdefaults()\f1:\0\0floating-point control register defaults functions@@@see \f3fpgetround(3M)\f1 .\" .\" links@fpgetround.3m fpsetround.3m .\" links@fpgetround.3m fpgetmask.3m .\" links@fpgetround.3m fpsetmask.3m .\" links@fpgetround.3m fpgetsticky.3m .\" links@fpgetround.3m fpsetsticky.3m .\" links@fpgetround.3m fpgetcontro.3m .\" links@fpgetround.3m fpsetcontro.3m .\" links@fpgetround.3m fpgetfastmo.3m .\" links@fpgetround.3m fpsetfastmo.3m .\" links@fpgetround.3m fpsetdefaul.3m .\" .\" fileset_database@fpgetround.3m PROGRAMING-MAN .\" $Header: fpgetround.3m,v 78.1 96/02/13 10:48:13 ssa Exp $ .TA f .TH fpgetround 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fpgetround(\|), fpsetround(\|), fpgetmask(\|), fpsetmask(\|), fpgetsticky(\|), fpsetsticky(\|), fpsetdefaults(\|), fpgetcontrol(\|), fpsetcontrol(\|), fpgetfastmode(\|), fpsetfastmode(\|) \- floating-point mode-control functions .SH SYNOPSIS .C "#include " .PP .C "fp_rnd fpgetround(void);" .PP .C "fp_rnd fpsetround(fp_rnd mode);" .PP .C "fp_except fpgetmask(void);" .PP .C "fp_except fpsetmask(fp_except value);" .PP .C "fp_except fpgetsticky(void);" .PP .C "fp_except fpsetsticky(fp_except value);" .PP .C "int fpgetfastmode(void);" .PP .C "int fpsetfastmode(int value);" .PP .C "void fpsetdefaults(void);" .PP .C "fp_control fpgetcontrol(void);" .PP .C "fp_control fpsetcontrol(fp_control value);" .PP .SH DESCRIPTION The .CR fpgetround() suite of functions allows programmers to manipulate the floating-point control register (also called the floating-point status register). .PP .CR fpgetround() returns the current rounding mode. The type of the returned value, .CR fp_rnd , is defined as follows in .RC < math.h >: .nf .IP .C "typedef enum {" .C " FP_RZ=0, /* Round toward zero */" .C " FP_RN, /* Round to nearest */" .C " FP_RP, /* Round toward positive infinity */" .C " FP_RM, /* Round toward negative infinity */" .C " } fp_rnd;" .fi .PP The default value is .CR FP_RN . Round-to-nearest mode rounds to the representable value closest to the true value. If two representable values are equally close to the true value, the system chooses the one whose least significant bit is zero. .PP .CR fpsetround() sets the rounding mode to the specified value of type .CR fp_rnd and returns the previous rounding mode. .PP There are five floating-point exceptions: divide-by-zero, overflow, underflow, imprecise (inexact) result, and invalid operation. If a floating-point exception occurs and the corresponding exception trap enable bit is set to 1, the trap takes place. If an exception occurs and the exception trap enable bit is set to 0, the corresponding exception flag is set to 1 and no trap takes place. The exception trap enable bits are sometimes called mask bits; the exception flags are sometimes called sticky bits. The functions .CR fpgetmask() and .CR fpgetsticky() return the current settings of these bits. To change the settings of these bits, use .CR fpsetmask() and .CR fpsetsticky() . .PP .CR fpgetmask() returns the current exception trap enable bits. The type of the returned value, .CR fp_except , is defined as .CR int in .RC < math.h >. The floating-point exception types are defined as follows in .RC < math.h >: .nf .IP .C "#define FP_X_INV 0x10 /* invalid operation exception */" .C "#define FP_X_DZ 0x08 /* divide-by-zero exception */" .C "#define FP_X_OFL 0x04 /* overflow exception */" .C "#define FP_X_UFL 0x02 /* underflow exception */" .C "#define FP_X_IMP 0x01 /* imprecise (inexact result) */" .C "#define FP_X_CLEAR 0x00 /* simply zero to clear all flags */" .fi .PP .CR fpsetmask() sets or clears the exception trap enable bits and returns the previous setting. The argument is an expression of type .CR fp_except . (To set or clear the exception trap enable bits at compile time, use the compiler option .CR +FP\c .IR string ). .PP .CR fpgetsticky() returns the current exception flags. .PP .CR fpsetsticky() sets or clears the exception flags and returns the previous setting. The argument is an expression of type .CR fp_except . .PP .CR fpgetfastmode() and .CR fpsetfastmode() allow the programmer to change the way the system handles underflow. Fast underflow mode, also known as fastmode, is an alternative to IEEE-754-compliant underflow mode. On Series 700/800 systems, most underflow cases are supported by trapping into the kernel, where the IEEE-mandated conversion of the result into a denormalized value or zero is accomplished by software emulation. On later PA1.1 systems and on all PA2.0 systems, fastmode causes the hardware to simply substitute a zero for the result of an operation, with no fault occurring. This may be a significant performance optimization for applications that underflow frequently. Fastmode also causes denormalized floating-point operands to be treated as if they were true zero operands. .PP .CR fpgetfastmode() returns the current fastmode setting: 1 if fastmode is set, 0 if the default IEEE-754-compliant underflow mode is set. On systems that do not support fastmode, this function returns an undefined value. .PP On systems that support fastmode, .CR fpsetfastmode() sets fastmode to either 1 (fastmode) or 0 (IEEE-754-compliant underflow mode) and returns the previous setting. On systems that do not support fastmode, this function has no effect. .PP .CR fpsetdefaults() changes the default environment, which is .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps disabled .br Fast underflow mode disabled .fi .PP .CR fpsetdefaults() changes these defaults to more useful values. Specifically, it enables traps for the invalid operation, divide-by-zero, and overflow exceptions, while leaving the underflow and inexact-result exception traps disabled. It sets the environment as follows: .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps enabled except underflow and inexact result (\c .CR FP_X_INV + FP_X_DZ + FP_X_OFL\c ) .br Fast underflow mode enabled (if the system supports it) .PP .CR fpgetcontrol() and .CR fpsetcontrol() access the floating-point status register. .PP .CR fpgetcontrol() returns the value of the floating-point status register. The type of the returned value, .CR fp_control , is defined as .CR long in .RC < math.h >. .PP .CR fpsetcontrol() sets the value of the floating-point status register and returns the previous value. For the format of this register, see the .I "HP-UX Floating-Point Guide" or the PA-RISC 1.1 or 2.0 architecture and instruction set reference manual. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH WARNINGS .CR fpsetsticky() modifies all exception flags. .CR fpsetmask() modifies all exception trap enable bits. .PP Both C and FORTRAN require truncation (rounding to zero) for floating-point to integer conversions. The current rounding mode has no effect on these conversions. .\" .\" index@\f4fpgetround()\f1, \f4fpsetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetround()\f1, \f4fpgetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetmask()\f1, \f4fpsetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetmask()\f1, \f4fpgetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetdefaults()\f1 \- set floating-point control register defaults@@@\f3fpgetround(3M)\f1 .\" index@math: floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@rounding mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception trap enable bits (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception flags (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@status register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@underflow mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" index@status register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" .\" toc@\f3fpgetround(3M)\f1:\0\0\f4fpgetround()\f1, \f4fpsetround()\f1, \f4fpgetmask()\f1, \f4fpsetmask()\f1, \f4fpgetsticky()\f1, \n\f4fpsetsticky()\f1, \f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1, \f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1, \n\f4fpsetdefaults()\f1@@@floating-point mode control functions .\" toc@\f4fpsetround()\f1, \f4fpgetround()\f1:\0\0floating-point rounding mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetmask()\f1, \f4fpsetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetmask()\f1, \f4fpgetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetdefaults()\f1:\0\0floating-point control register defaults functions@@@see \f3fpgetround(3M)\f1 .\" .\" links@fpgetround.3m fpsetround.3m .\" links@fpgetround.3m fpgetmask.3m .\" links@fpgetround.3m fpsetmask.3m .\" links@fpgetround.3m fpgetsticky.3m .\" links@fpgetround.3m fpsetsticky.3m .\" links@fpgetround.3m fpgetcontro.3m .\" links@fpgetround.3m fpsetcontro.3m .\" links@fpgetround.3m fpgetfastmo.3m .\" links@fpgetround.3m fpsetfastmo.3m .\" links@fpgetround.3m fpsetdefaul.3m .\" .\" fileset_database@fpgetround.3m PROGRAMING-MAN .\" $Header: fpgetround.3m,v 78.1 96/02/13 10:48:13 ssa Exp $ .TA f .TH fpgetround 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fpgetround(\|), fpsetround(\|), fpgetmask(\|), fpsetmask(\|), fpgetsticky(\|), fpsetsticky(\|), fpsetdefaults(\|), fpgetcontrol(\|), fpsetcontrol(\|), fpgetfastmode(\|), fpsetfastmode(\|) \- floating-point mode-control functions .SH SYNOPSIS .C "#include " .PP .C "fp_rnd fpgetround(void);" .PP .C "fp_rnd fpsetround(fp_rnd mode);" .PP .C "fp_except fpgetmask(void);" .PP .C "fp_except fpsetmask(fp_except value);" .PP .C "fp_except fpgetsticky(void);" .PP .C "fp_except fpsetsticky(fp_except value);" .PP .C "int fpgetfastmode(void);" .PP .C "int fpsetfastmode(int value);" .PP .C "void fpsetdefaults(void);" .PP .C "fp_control fpgetcontrol(void);" .PP .C "fp_control fpsetcontrol(fp_control value);" .PP .SH DESCRIPTION The .CR fpgetround() suite of functions allows programmers to manipulate the floating-point control register (also called the floating-point status register). .PP .CR fpgetround() returns the current rounding mode. The type of the returned value, .CR fp_rnd , is defined as follows in .RC < math.h >: .nf .IP .C "typedef enum {" .C " FP_RZ=0, /* Round toward zero */" .C " FP_RN, /* Round to nearest */" .C " FP_RP, /* Round toward positive infinity */" .C " FP_RM, /* Round toward negative infinity */" .C " } fp_rnd;" .fi .PP The default value is .CR FP_RN . Round-to-nearest mode rounds to the representable value closest to the true value. If two representable values are equally close to the true value, the system chooses the one whose least significant bit is zero. .PP .CR fpsetround() sets the rounding mode to the specified value of type .CR fp_rnd and returns the previous rounding mode. .PP There are five floating-point exceptions: divide-by-zero, overflow, underflow, imprecise (inexact) result, and invalid operation. If a floating-point exception occurs and the corresponding exception trap enable bit is set to 1, the trap takes place. If an exception occurs and the exception trap enable bit is set to 0, the corresponding exception flag is set to 1 and no trap takes place. The exception trap enable bits are sometimes called mask bits; the exception flags are sometimes called sticky bits. The functions .CR fpgetmask() and .CR fpgetsticky() return the current settings of these bits. To change the settings of these bits, use .CR fpsetmask() and .CR fpsetsticky() . .PP .CR fpgetmask() returns the current exception trap enable bits. The type of the returned value, .CR fp_except , is defined as .CR int in .RC < math.h >. The floating-point exception types are defined as follows in .RC < math.h >: .nf .IP .C "#define FP_X_INV 0x10 /* invalid operation exception */" .C "#define FP_X_DZ 0x08 /* divide-by-zero exception */" .C "#define FP_X_OFL 0x04 /* overflow exception */" .C "#define FP_X_UFL 0x02 /* underflow exception */" .C "#define FP_X_IMP 0x01 /* imprecise (inexact result) */" .C "#define FP_X_CLEAR 0x00 /* simply zero to clear all flags */" .fi .PP .CR fpsetmask() sets or clears the exception trap enable bits and returns the previous setting. The argument is an expression of type .CR fp_except . (To set or clear the exception trap enable bits at compile time, use the compiler option .CR +FP\c .IR string ). .PP .CR fpgetsticky() returns the current exception flags. .PP .CR fpsetsticky() sets or clears the exception flags and returns the previous setting. The argument is an expression of type .CR fp_except . .PP .CR fpgetfastmode() and .CR fpsetfastmode() allow the programmer to change the way the system handles underflow. Fast underflow mode, also known as fastmode, is an alternative to IEEE-754-compliant underflow mode. On Series 700/800 systems, most underflow cases are supported by trapping into the kernel, where the IEEE-mandated conversion of the result into a denormalized value or zero is accomplished by software emulation. On later PA1.1 systems and on all PA2.0 systems, fastmode causes the hardware to simply substitute a zero for the result of an operation, with no fault occurring. This may be a significant performance optimization for applications that underflow frequently. Fastmode also causes denormalized floating-point operands to be treated as if they were true zero operands. .PP .CR fpgetfastmode() returns the current fastmode setting: 1 if fastmode is set, 0 if the default IEEE-754-compliant underflow mode is set. On systems that do not support fastmode, this function returns an undefined value. .PP On systems that support fastmode, .CR fpsetfastmode() sets fastmode to either 1 (fastmode) or 0 (IEEE-754-compliant underflow mode) and returns the previous setting. On systems that do not support fastmode, this function has no effect. .PP .CR fpsetdefaults() changes the default environment, which is .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps disabled .br Fast underflow mode disabled .fi .PP .CR fpsetdefaults() changes these defaults to more useful values. Specifically, it enables traps for the invalid operation, divide-by-zero, and overflow exceptions, while leaving the underflow and inexact-result exception traps disabled. It sets the environment as follows: .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps enabled except underflow and inexact result (\c .CR FP_X_INV + FP_X_DZ + FP_X_OFL\c ) .br Fast underflow mode enabled (if the system supports it) .PP .CR fpgetcontrol() and .CR fpsetcontrol() access the floating-point status register. .PP .CR fpgetcontrol() returns the value of the floating-point status register. The type of the returned value, .CR fp_control , is defined as .CR long in .RC < math.h >. .PP .CR fpsetcontrol() sets the value of the floating-point status register and returns the previous value. For the format of this register, see the .I "HP-UX Floating-Point Guide" or the PA-RISC 1.1 or 2.0 architecture and instruction set reference manual. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH WARNINGS .CR fpsetsticky() modifies all exception flags. .CR fpsetmask() modifies all exception trap enable bits. .PP Both C and FORTRAN require truncation (rounding to zero) for floating-point to integer conversions. The current rounding mode has no effect on these conversions. .\" .\" index@\f4fpgetround()\f1, \f4fpsetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetround()\f1, \f4fpgetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetmask()\f1, \f4fpsetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetmask()\f1, \f4fpgetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetdefaults()\f1 \- set floating-point control register defaults@@@\f3fpgetround(3M)\f1 .\" index@math: floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@rounding mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception trap enable bits (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception flags (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@status register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@underflow mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" index@status register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" .\" toc@\f3fpgetround(3M)\f1:\0\0\f4fpgetround()\f1, \f4fpsetround()\f1, \f4fpgetmask()\f1, \f4fpsetmask()\f1, \f4fpgetsticky()\f1, \n\f4fpsetsticky()\f1, \f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1, \f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1, \n\f4fpsetdefaults()\f1@@@floating-point mode control functions .\" toc@\f4fpsetround()\f1, \f4fpgetround()\f1:\0\0floating-point rounding mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetmask()\f1, \f4fpsetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetmask()\f1, \f4fpgetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetdefaults()\f1:\0\0floating-point control register defaults functions@@@see \f3fpgetround(3M)\f1 .\" .\" links@fpgetround.3m fpsetround.3m .\" links@fpgetround.3m fpgetmask.3m .\" links@fpgetround.3m fpsetmask.3m .\" links@fpgetround.3m fpgetsticky.3m .\" links@fpgetround.3m fpsetsticky.3m .\" links@fpgetround.3m fpgetcontro.3m .\" links@fpgetround.3m fpsetcontro.3m .\" links@fpgetround.3m fpgetfastmo.3m .\" links@fpgetround.3m fpsetfastmo.3m .\" links@fpgetround.3m fpsetdefaul.3m .\" .\" fileset_database@fpgetround.3m PROGRAMING-MAN .\" $Header: fpgetround.3m,v 78.1 96/02/13 10:48:13 ssa Exp $ .TA f .TH fpgetround 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fpgetround(\|), fpsetround(\|), fpgetmask(\|), fpsetmask(\|), fpgetsticky(\|), fpsetsticky(\|), fpsetdefaults(\|), fpgetcontrol(\|), fpsetcontrol(\|), fpgetfastmode(\|), fpsetfastmode(\|) \- floating-point mode-control functions .SH SYNOPSIS .C "#include " .PP .C "fp_rnd fpgetround(void);" .PP .C "fp_rnd fpsetround(fp_rnd mode);" .PP .C "fp_except fpgetmask(void);" .PP .C "fp_except fpsetmask(fp_except value);" .PP .C "fp_except fpgetsticky(void);" .PP .C "fp_except fpsetsticky(fp_except value);" .PP .C "int fpgetfastmode(void);" .PP .C "int fpsetfastmode(int value);" .PP .C "void fpsetdefaults(void);" .PP .C "fp_control fpgetcontrol(void);" .PP .C "fp_control fpsetcontrol(fp_control value);" .PP .SH DESCRIPTION The .CR fpgetround() suite of functions allows programmers to manipulate the floating-point control register (also called the floating-point status register). .PP .CR fpgetround() returns the current rounding mode. The type of the returned value, .CR fp_rnd , is defined as follows in .RC < math.h >: .nf .IP .C "typedef enum {" .C " FP_RZ=0, /* Round toward zero */" .C " FP_RN, /* Round to nearest */" .C " FP_RP, /* Round toward positive infinity */" .C " FP_RM, /* Round toward negative infinity */" .C " } fp_rnd;" .fi .PP The default value is .CR FP_RN . Round-to-nearest mode rounds to the representable value closest to the true value. If two representable values are equally close to the true value, the system chooses the one whose least significant bit is zero. .PP .CR fpsetround() sets the rounding mode to the specified value of type .CR fp_rnd and returns the previous rounding mode. .PP There are five floating-point exceptions: divide-by-zero, overflow, underflow, imprecise (inexact) result, and invalid operation. If a floating-point exception occurs and the corresponding exception trap enable bit is set to 1, the trap takes place. If an exception occurs and the exception trap enable bit is set to 0, the corresponding exception flag is set to 1 and no trap takes place. The exception trap enable bits are sometimes called mask bits; the exception flags are sometimes called sticky bits. The functions .CR fpgetmask() and .CR fpgetsticky() return the current settings of these bits. To change the settings of these bits, use .CR fpsetmask() and .CR fpsetsticky() . .PP .CR fpgetmask() returns the current exception trap enable bits. The type of the returned value, .CR fp_except , is defined as .CR int in .RC < math.h >. The floating-point exception types are defined as follows in .RC < math.h >: .nf .IP .C "#define FP_X_INV 0x10 /* invalid operation exception */" .C "#define FP_X_DZ 0x08 /* divide-by-zero exception */" .C "#define FP_X_OFL 0x04 /* overflow exception */" .C "#define FP_X_UFL 0x02 /* underflow exception */" .C "#define FP_X_IMP 0x01 /* imprecise (inexact result) */" .C "#define FP_X_CLEAR 0x00 /* simply zero to clear all flags */" .fi .PP .CR fpsetmask() sets or clears the exception trap enable bits and returns the previous setting. The argument is an expression of type .CR fp_except . (To set or clear the exception trap enable bits at compile time, use the compiler option .CR +FP\c .IR string ). .PP .CR fpgetsticky() returns the current exception flags. .PP .CR fpsetsticky() sets or clears the exception flags and returns the previous setting. The argument is an expression of type .CR fp_except . .PP .CR fpgetfastmode() and .CR fpsetfastmode() allow the programmer to change the way the system handles underflow. Fast underflow mode, also known as fastmode, is an alternative to IEEE-754-compliant underflow mode. On Series 700/800 systems, most underflow cases are supported by trapping into the kernel, where the IEEE-mandated conversion of the result into a denormalized value or zero is accomplished by software emulation. On later PA1.1 systems and on all PA2.0 systems, fastmode causes the hardware to simply substitute a zero for the result of an operation, with no fault occurring. This may be a significant performance optimization for applications that underflow frequently. Fastmode also causes denormalized floating-point operands to be treated as if they were true zero operands. .PP .CR fpgetfastmode() returns the current fastmode setting: 1 if fastmode is set, 0 if the default IEEE-754-compliant underflow mode is set. On systems that do not support fastmode, this function returns an undefined value. .PP On systems that support fastmode, .CR fpsetfastmode() sets fastmode to either 1 (fastmode) or 0 (IEEE-754-compliant underflow mode) and returns the previous setting. On systems that do not support fastmode, this function has no effect. .PP .CR fpsetdefaults() changes the default environment, which is .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps disabled .br Fast underflow mode disabled .fi .PP .CR fpsetdefaults() changes these defaults to more useful values. Specifically, it enables traps for the invalid operation, divide-by-zero, and overflow exceptions, while leaving the underflow and inexact-result exception traps disabled. It sets the environment as follows: .IP Round to nearest (\c .C FP_RN\c ) .br All exception flags cleared (\c .C FP_X_CLEAR\c ) .br All exception traps enabled except underflow and inexact result (\c .CR FP_X_INV + FP_X_DZ + FP_X_OFL\c ) .br Fast underflow mode enabled (if the system supports it) .PP .CR fpgetcontrol() and .CR fpsetcontrol() access the floating-point status register. .PP .CR fpgetcontrol() returns the value of the floating-point status register. The type of the returned value, .CR fp_control , is defined as .CR long in .RC < math.h >. .PP .CR fpsetcontrol() sets the value of the floating-point status register and returns the previous value. For the format of this register, see the .I "HP-UX Floating-Point Guide" or the PA-RISC 1.1 or 2.0 architecture and instruction set reference manual. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH WARNINGS .CR fpsetsticky() modifies all exception flags. .CR fpsetmask() modifies all exception trap enable bits. .PP Both C and FORTRAN require truncation (rounding to zero) for floating-point to integer conversions. The current rounding mode has no effect on these conversions. .\" .\" index@\f4fpgetround()\f1, \f4fpsetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetround()\f1, \f4fpgetround()\f1 \- examine and set floating-point rounding mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetmask()\f1, \f4fpsetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetmask()\f1, \f4fpgetmask()\f1 \- examine and set floating-point exception trap enables@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1 \- examine and set floating-point exception flags@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1 \- examine and set floating-point control register@@@\f3fpgetround(3M)\f1 .\" index@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1 \- examine and set floating-point underflow mode@@@\f3fpgetround(3M)\f1 .\" index@\f4fpsetdefaults()\f1 \- set floating-point control register defaults@@@\f3fpgetround(3M)\f1 .\" index@math: floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@floating-point mode control functions@@@\f3fpgetround(3M)\f1 .\" index@rounding mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception trap enable bits (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@exception flags (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@status register (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@underflow mode (floating-point), examine and set@@@\f3fpgetround(3M)\f1 .\" index@control register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" index@status register defaults (floating-point), set@@@\f3fpgetround(3M)\f1 .\" .\" toc@\f3fpgetround(3M)\f1:\0\0\f4fpgetround()\f1, \f4fpsetround()\f1, \f4fpgetmask()\f1, \f4fpsetmask()\f1, \f4fpgetsticky()\f1, \n\f4fpsetsticky()\f1, \f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1, \f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1, \n\f4fpsetdefaults()\f1@@@floating-point mode control functions .\" toc@\f4fpsetround()\f1, \f4fpgetround()\f1:\0\0floating-point rounding mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetmask()\f1, \f4fpsetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetmask()\f1, \f4fpgetmask()\f1:\0\0floating-point exception trap enables functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetsticky()\f1, \f4fpsetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetsticky()\f1, \f4fpgetsticky()\f1:\0\0floating-point exception flags functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetcontrol()\f1, \f4fpsetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetcontrol()\f1, \f4fpgetcontrol()\f1:\0\0floating-point control register functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpgetfastmode()\f1, \f4fpsetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetfastmode()\f1, \f4fpgetfastmode()\f1:\0\0floating-point underflow mode functions@@@see \f3fpgetround(3M)\f1 .\" toc@\f4fpsetdefaults()\f1:\0\0floating-point control register defaults functions@@@see \f3fpgetround(3M)\f1 .\" .\" links@fpgetround.3m fpsetround.3m .\" links@fpgetround.3m fpgetmask.3m .\" links@fpgetround.3m fpsetmask.3m .\" links@fpgetround.3m fpgetsticky.3m .\" links@fpgetround.3m fpsetsticky.3m .\" links@fpgetround.3m fpgetcontro.3m .\" links@fpgetround.3m fpsetcontro.3m .\" links@fpgetround.3m fpgetfastmo.3m .\" links@fpgetround.3m fpsetfastmo.3m .\" links@fpgetround.3m fpsetdefaul.3m .\" .\" fileset_database@fpgetround.3m PROGRAMING-MAN .\" $Header: putc.3s,v 76.1 95/07/05 17:44:59 ssa Exp $ .TA p .TH putc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putc(\|), putc_unlocked(\|), putchar(\|), putchar_unlocked(\|), fputc(\|), putw(\|), putw_unlocked(\|) \- put character or word on a stream .SH SYNOPSIS .C "#include " .PP .C "int putc(int c, FILE *stream);" .PP .C "int putc_unlocked(int c, FILE *stream);" .PP .C "int putchar(int c);" .PP .C "int putchar_unlocked(int c);" .PP .C "int fputc(int c, FILE *stream);" .PP .C "int putw(int w, FILE *stream);" .PP .C "int putw_unlocked(int w, FILE *stream);" .SH DESCRIPTION .TP 15 .CR putc() Writes the character .I c onto the output .I stream at the position where the file pointer, if defined, is pointing. .CI putchar( c ) is defined as .CI putc( c , .CR stdout) . .CR putc() and .CR putchar() are defined both as macros and as functions. .TP .CR fputc() Same as .CR putc() , but is a function rather than a macro, and can therefore be used as an argument. .CR fputc() runs more slowly than .CR putc() , but takes less space per invocation, and its name can be passed as an argument to a function. .TP .CR putw() Writes the word (i.e., .CR int in C) .I w to the output .I stream (at the position at which the file pointer, if defined, is pointing). The size of a word is the size of an integer and varies from machine to machine. .CR putw() neither assumes nor causes special alignment in the file. .PP Output streams, with the exception of the standard error stream .CR stderr , are by default buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream, .CR stderr , is by default unbuffered, but use of .CR freopen() (see .IR fopen (3S)) causes it to become buffered or line-buffered. .CR setbuf() or .CR setvbuf() (see .IR setbuf (3S)) can be used to change the stream's buffering strategy. .PP .CR putc_unlocked() , " putchar_unlocked()" , and .CR putw_unlocked() are identical to .CR putc() , " putchar()" , and .CR putw() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE On success, .CR putc() , .CR putc_unlocked() , .CR fputc() , .CR putchar() , and .CR putchar_unlocked() each return the value they have written. On failure, they return the constant .SM EOF, set the error indicator for the stream, and set .CR errno to indicate the error. .PP On success, .CR putw() and .CR putw_unlocked() return 0. Otherwise, a non-zero value is returned, the error indicator for the stream is set, and .CR errno is set to indicate the error. .SH ERRORS .CR putc() , .CR putc_unlocked() , .CR putchar() , .CR putchar_unlocked() , .CR fputc() , .CR putw() , and .CR putw_unlocked() fail if, either the .I stream is unbuffered or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 .SM [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP .SM [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP .SM [EINTR] A signal was caught during the .CR write() system call. .TP .SM [EIO] A physical I/O error has occurred, or the process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt is made to write to a pipe or .SM FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH WARNINGS The .CR putc() and .CR putchar() routines are implemented as both library functions and macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parentheses or use the function address. The following example illustrates each of these methods: .nf .IP .CR #include .CR #undef putc \h'.2i'... .CR main() .CR { .CR " int (*put_char()) ();" \h'.6i'... .CR " return_val=putc(c,fd);" \h'.6i'... .CR " return_val=(putc)(c,fd1);" \h'.6i'... .CR " put_char = putchar;" .CR }; .fi .PP Line buffering may cause confusion or malfunctioning of programs that use standard .SM I/O routines but use .CR read() themselves to read from standard input. When a large amount of computation is done after printing part of a line on an output terminal, it is necessary to .CR fflush() (see .IR fclose (3S)) the standard output before beginning the computation. .PP The macro version of .CR putc() incorrectly treats the argument .I stream with side effects. In particular, the following call may not work as expected: .IP .CR putc(c, *f++); .PP The function version of .CR putc() or .CR fputc() should be used instead. .PP Because of possible differences in word length and byte ordering, files written using .CR putw() are machine-dependent, and may not be readable by .CR getw() on a different processor. .SS Reentrant Interfaces If .CR _REENTRANT is defined, the locked versions of the library functions for .CR putc() and .CR putchar() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR putc() and .CR putchar() . .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), getc(3S), fread(3S), printf(3S), puts(3S), setbuf(3S). .SH STANDARDS CONFORMANCE .CR putc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fputc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR putchar() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR putw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4putc()\fP, \f4fputc()\fP \- put character on a stream@@@\f3putc(3S)\f1 .\" index@\f4fputc()\fP, \f4putc()\fP \- put character on a stream@@@\f3putc(3S)\f1 .\" index@\f4putchar()\fP \- put character on stream \f2standard output\f1@@@\f3putc(3S)\f1 .\" index@\f4putw()\fP \- put word (integer) on a stream@@@\f3putc(3S)\f1 .\" index@character or word, put on a stream@@@\f3putc(3S)\f1 .\" index@put character or word on a stream@@@\f3putc(3S)\f1 .\" index@put word or character on a stream@@@\f3putc(3S)\f1 .\" index@word or character, put on a stream@@@\f3putc(3S)\f1 .\" index@stream, put word or character on a@@@\f3putc(3S)\f1 .\" .\" toc@\f3putc(3S)\f1:\0\0\f4putc()\fP, \f4putchar()\fP, \f4fputc()\fP, \f4putw()\fP@@@put character or word on a stream .\" toc@\f4putchar()\fP:\0\0put character on a stream@@@see \f3putc(3S)\f1 .\" toc@\f4fputc()\fP:\0\0put character on a stream@@@see \f3putc(3S)\f1 .\" toc@\f4putw()\fP:\0\0put word on a stream@@@see \f3putc(3S)\f1 .\" .\" links@putc.3s putc_unlock.3s .\" links@putc.3s putchar.3s .\" links@putc.3s putchar_unl.3s .\" links@putc.3s fputc.3s .\" links@putc.3s putw.3s .\" links@putc.3s putw_unlock.3s .\" $Header: puts.3s,v 72.5 94/11/15 09:55:49 ssa Exp $ .TA p .TH puts 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME puts(\|), puts_unlocked(\|), fputs(\|), fputs_unlocked(\|) \- put a string on a stream .SH SYNOPSIS .C "#include " .PP .C "int puts(const char *s);" .PP .C "int puts_unlocked(const char *s);" .PP .C "int fputs(const char *s, FILE *stream);" .PP .C "int fputs_unlocked(const char *s, FILE *stream);" .SH DESCRIPTION .CR puts() writes the null-terminated string pointed to by .IR s , followed by a new-line character, to the standard output stream .CR stdout . .PP .CR fputs() writes the null-terminated string pointed to by .I s to the named output .IR stream , but does .I not append a new-line character. .PP Neither function writes the terminating null character. .PP .CR puts_unlocked() and .CR fputs_unlocked() are identical to .CR puts() and .CR fputs() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon successful completion, these routines return a non-negative number. Otherwise they return EOF, set the error indicator for the stream, and set .CR errno to indicate the error. .SH ERRORS These routines fail if, either the .I stream is unbuffered or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A SIGPIPE signal is also sent to the process. .RE .PP Additional .CR errno values may be set by the underlying .CR write() function (see .IR write(2)). .SH SEE ALSO ferror(3S), flockfile(3S), fopen(3S), fread(3S), printf(3S), putc(3S). .SH NOTES .CR puts() and .CR puts_unlocked() append a new-line character; .CR fputs() and .CR fputs_unlocked() do not. .SH STANDARDS CONFORMANCE .CR puts() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fputs() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4puts()\f1 \- write null-terminated string to stream \f4stdout()\f1@@@\f3puts(3S)\f1 .\" index@\f4fputs()\f1 \- write null-terminated string to a named stream file@@@\f3puts(3S)\f1 .\" index@\f1put a string on a stream@@@\f3puts(3S)\f1 .\" index@\f1write a null-terminated string on a stream@@@\f3puts(3S)\f1 .\" .\" toc@\f3puts(3S)\f1:\0\0\f4puts()\f1, \f4fputs()\f1@@@put a string on a stream .\" toc@\f4fputs()\f1:\0\0put a string on a stream@@@see \f3puts(3S)\f1 .\" .\" links@puts.3s fputs.3s .\" links@puts.3s puts_unlock.3s .\" links@puts.3s fputs_unloc.3s .\" .\" fileset_database@puts.3s PROGRAMING-MAN .\" $Header: puts.3s,v 72.5 94/11/15 09:55:49 ssa Exp $ .TA p .TH puts 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME puts(\|), puts_unlocked(\|), fputs(\|), fputs_unlocked(\|) \- put a string on a stream .SH SYNOPSIS .C "#include " .PP .C "int puts(const char *s);" .PP .C "int puts_unlocked(const char *s);" .PP .C "int fputs(const char *s, FILE *stream);" .PP .C "int fputs_unlocked(const char *s, FILE *stream);" .SH DESCRIPTION .CR puts() writes the null-terminated string pointed to by .IR s , followed by a new-line character, to the standard output stream .CR stdout . .PP .CR fputs() writes the null-terminated string pointed to by .I s to the named output .IR stream , but does .I not append a new-line character. .PP Neither function writes the terminating null character. .PP .CR puts_unlocked() and .CR fputs_unlocked() are identical to .CR puts() and .CR fputs() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon successful completion, these routines return a non-negative number. Otherwise they return EOF, set the error indicator for the stream, and set .CR errno to indicate the error. .SH ERRORS These routines fail if, either the .I stream is unbuffered or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A SIGPIPE signal is also sent to the process. .RE .PP Additional .CR errno values may be set by the underlying .CR write() function (see .IR write(2)). .SH SEE ALSO ferror(3S), flockfile(3S), fopen(3S), fread(3S), printf(3S), putc(3S). .SH NOTES .CR puts() and .CR puts_unlocked() append a new-line character; .CR fputs() and .CR fputs_unlocked() do not. .SH STANDARDS CONFORMANCE .CR puts() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fputs() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4puts()\f1 \- write null-terminated string to stream \f4stdout()\f1@@@\f3puts(3S)\f1 .\" index@\f4fputs()\f1 \- write null-terminated string to a named stream file@@@\f3puts(3S)\f1 .\" index@\f1put a string on a stream@@@\f3puts(3S)\f1 .\" index@\f1write a null-terminated string on a stream@@@\f3puts(3S)\f1 .\" .\" toc@\f3puts(3S)\f1:\0\0\f4puts()\f1, \f4fputs()\f1@@@put a string on a stream .\" toc@\f4fputs()\f1:\0\0put a string on a stream@@@see \f3puts(3S)\f1 .\" .\" links@puts.3s fputs.3s .\" links@puts.3s puts_unlock.3s .\" links@puts.3s fputs_unloc.3s .\" .\" fileset_database@puts.3s PROGRAMING-MAN .\" $Header: putwc.3c,v 76.1 95/07/05 17:45:14 ssa Exp $ .TA p .TH putwc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putwc(\|), putwc_unlocked(\|), putwchar(\|), putwchar_unlocked(\|), fputwc(\|), fputwc_unlocked(\|) \- put a wide character on a stream file .SH SYNOPSIS .C "#include " .PP .C "wint_t putwc(wint_t wc, FILE *stream);" .PP .C "wint_t putwc_unlocked(wint_t wc, FILE *stream);" .PP .C "wint_t putwchar(wint_t wc);" .PP .C "wint_t putwchar_unlocked(wint_t wc);" .PP .C "wint_t fputwc(wint_t wc, FILE *stream);" .PP .C "wint_t fputwc_unlocked(wint_t wc, FILE *stream);" .SS Remarks: These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. They parallel the 8-bit character I/O functions defined in .IR putc(3S) . .SH DESCRIPTION .TP 15 .CR putwc() Writes the character corresponding to the wide character .I wc onto the output .I stream at the position where the file pointer is pointing. .CI putwchar( wc ) is defined as .CI putwc( wc , .CR stdout) . .CR putwc() and .CR putwchar() are defined both as macros and as functions. .TP .C fputwc() Behaves like .CR putwc() , but is a function rather than a macro, and can therefore be used as an argument. .PP Output streams, with the exception of the standard error stream .CR stderr , are by default buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream, .CR stderr , is by default unbuffered, but use of .CR freopen() (see .IR fopen (3S)) causes it to become buffered or line-buffered. .CR setbuf() or .CR setvbuf() (see .IR setbuf (3S)) can be used to change the stream's buffering strategy. .PP Definitions for these functions, the type .I wint_t and the value WEOF are provided in the .RC < wchar.h > header. .PP .CR putwc_unlocked() , .CR putwchar_unlocked() , and .CR fputwc_unlocked() are identical to .CR putwc() , .CR putwchar() , and .CR fputwc_unlocked() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE On success, .CR putwc() , .CR putwc_unlocked() , .CR fputwc() , .CR fputwc_unlocked() , .CR putwchar() , and .CR putwchar_unlocked() each return the wide character corresponding to the value they have written. On failure, they return the constant .CR WEOF , set the error indicator for the stream, and set .CR errno to indicate the error. .SH ERRORS .CR putwc() , .CR putwc_unlocked() , .CR putwchar() , .CR putwchar_unlocked() , .CR fputwc() , and .CR fputwc_unlocked() fail if either the .I stream is unbuffered, or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] A physical I/O error has occurred, or the process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP [EILSEQ] The wide character .I wc does not correspond to a valid character. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH WARNINGS Line buffering may cause confusion or malfunctioning of programs that use wide character I/O routines but use .CR read() themselves to read from standard input. When a large amount of computation is done after printing part of a line on an output terminal, it is necessary to .CR fflush() (see .IR fclose (3S)) the standard output before beginning the computation. .SH AUTHOR .CR putwc() was developed by OSF and HP. .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), getwc(3C), fread(3S), printf(3S), fputws(3C), setbuf(3S). .SH STANDARDS CONFORMANCE .CR putwc() ": XPG4" .PP .CR fputwc() ": XPG4" .PP .CR putwchar() ": XPG4" .\" .\" index@\f4putwc()\f1, \f4fputwc()\f1 \- put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f4fputwc()\f1, \f4putwc()\f1 \- put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f4putwchar()\f1 \- put wide character on stream \f2standard output\f1@@@\f3putwc(3C)\f1 .\" index@\f1wide character, put on a stream@@@\f3putwc(3C)\f1 .\" index@\f1put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f1stream, put wide character on a@@@\f3putwc(3C)\f1 .\" .\" toc@\f3putwc(3C)\f1:\0\0\f4putwc()\f1, \f4putwchar()\f1, \f4fputwc()\f1@@@put wide character on a stream .\" toc@\f4putwchar()\f1:\0\0put wide character on a stream@@@see \f3putwc(3C)\f1 .\" toc@\f4fputwc()\f1:\0\0put wide character on a stream@@@see \f3putwc(3C)\f1 .\" .\" links@putwc.3c putwc_unloc.3c .\" links@putwc.3c putwchar.3c .\" links@putwc.3c putwchar_un.3c .\" links@putwc.3c fputwc_unlo.3c .\" links@putwc.3c fputwc.3c .\" $Header: putwc.3c,v 76.1 95/07/05 17:45:14 ssa Exp $ .TA p .TH putwc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putwc(\|), putwc_unlocked(\|), putwchar(\|), putwchar_unlocked(\|), fputwc(\|), fputwc_unlocked(\|) \- put a wide character on a stream file .SH SYNOPSIS .C "#include " .PP .C "wint_t putwc(wint_t wc, FILE *stream);" .PP .C "wint_t putwc_unlocked(wint_t wc, FILE *stream);" .PP .C "wint_t putwchar(wint_t wc);" .PP .C "wint_t putwchar_unlocked(wint_t wc);" .PP .C "wint_t fputwc(wint_t wc, FILE *stream);" .PP .C "wint_t fputwc_unlocked(wint_t wc, FILE *stream);" .SS Remarks: These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. They parallel the 8-bit character I/O functions defined in .IR putc(3S) . .SH DESCRIPTION .TP 15 .CR putwc() Writes the character corresponding to the wide character .I wc onto the output .I stream at the position where the file pointer is pointing. .CI putwchar( wc ) is defined as .CI putwc( wc , .CR stdout) . .CR putwc() and .CR putwchar() are defined both as macros and as functions. .TP .C fputwc() Behaves like .CR putwc() , but is a function rather than a macro, and can therefore be used as an argument. .PP Output streams, with the exception of the standard error stream .CR stderr , are by default buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream, .CR stderr , is by default unbuffered, but use of .CR freopen() (see .IR fopen (3S)) causes it to become buffered or line-buffered. .CR setbuf() or .CR setvbuf() (see .IR setbuf (3S)) can be used to change the stream's buffering strategy. .PP Definitions for these functions, the type .I wint_t and the value WEOF are provided in the .RC < wchar.h > header. .PP .CR putwc_unlocked() , .CR putwchar_unlocked() , and .CR fputwc_unlocked() are identical to .CR putwc() , .CR putwchar() , and .CR fputwc_unlocked() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE On success, .CR putwc() , .CR putwc_unlocked() , .CR fputwc() , .CR fputwc_unlocked() , .CR putwchar() , and .CR putwchar_unlocked() each return the wide character corresponding to the value they have written. On failure, they return the constant .CR WEOF , set the error indicator for the stream, and set .CR errno to indicate the error. .SH ERRORS .CR putwc() , .CR putwc_unlocked() , .CR putwchar() , .CR putwchar_unlocked() , .CR fputwc() , and .CR fputwc_unlocked() fail if either the .I stream is unbuffered, or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] A physical I/O error has occurred, or the process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP [EILSEQ] The wide character .I wc does not correspond to a valid character. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH WARNINGS Line buffering may cause confusion or malfunctioning of programs that use wide character I/O routines but use .CR read() themselves to read from standard input. When a large amount of computation is done after printing part of a line on an output terminal, it is necessary to .CR fflush() (see .IR fclose (3S)) the standard output before beginning the computation. .SH AUTHOR .CR putwc() was developed by OSF and HP. .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), getwc(3C), fread(3S), printf(3S), fputws(3C), setbuf(3S). .SH STANDARDS CONFORMANCE .CR putwc() ": XPG4" .PP .CR fputwc() ": XPG4" .PP .CR putwchar() ": XPG4" .\" .\" index@\f4putwc()\f1, \f4fputwc()\f1 \- put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f4fputwc()\f1, \f4putwc()\f1 \- put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f4putwchar()\f1 \- put wide character on stream \f2standard output\f1@@@\f3putwc(3C)\f1 .\" index@\f1wide character, put on a stream@@@\f3putwc(3C)\f1 .\" index@\f1put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f1stream, put wide character on a@@@\f3putwc(3C)\f1 .\" .\" toc@\f3putwc(3C)\f1:\0\0\f4putwc()\f1, \f4putwchar()\f1, \f4fputwc()\f1@@@put wide character on a stream .\" toc@\f4putwchar()\f1:\0\0put wide character on a stream@@@see \f3putwc(3C)\f1 .\" toc@\f4fputwc()\f1:\0\0put wide character on a stream@@@see \f3putwc(3C)\f1 .\" .\" links@putwc.3c putwc_unloc.3c .\" links@putwc.3c putwchar.3c .\" links@putwc.3c putwchar_un.3c .\" links@putwc.3c fputwc_unlo.3c .\" links@putwc.3c fputwc.3c .\" $Header: putws.3c,v 72.3 94/11/15 09:55:52 ssa Exp $ .TA p .TH putws 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putws(\|), putws_unlocked(\|), fputws(\|), fputws_unlocked(\|) \- put a wide character string on a stream file .SH SYNOPSIS .C "#include " .PP .C "int putws(const wchar_t *ws);" .PP .C "int putws_unlocked(const wchar_t *ws);" .PP .C "int fputws(const wchar_t *ws, FILE *stream);" .PP .C "int fputws_unlocked(const wchar_t *ws, FILE *stream);" .SS Remarks: .CR fputws is compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. These functions parallel the 8 bit character I/O functions defined in .IR puts(3S) . .SH DESCRIPTION .CR putws() writes a character string corresponding to the null-terminated wide-character string pointed to by .I ws followed by a new-line character, to the standard output stream .CR stdout . .PP .CR fputws() writes a character string corresponding to the null-terminated wide-character string pointed to by .I ws to the named output .IR stream , but does .I not append a new-line character or a terminating null character. .PP Neither function writes a terminating null character. .PP The definition for these functions, the type .CR wchar_t and the value .CR WEOF are provided in the .RC < wchar.h > header. .PP .CR putws_unlocked() and .CR fputws_unlocked() are identical to .CR putws() and .CR fputws() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. .CR putws_unlocked() and .CR fputws_unlocked() can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE Upon successful completion, .CR putws() , .CR putws_unlocked() , .CR fputws() , and .CR fputws_unlocked() return a non-negative number. Otherwise they return .CR WEOF , set the error indicator for the stream, and set .CR errno to indicate the error. .SH ERRORS .CR putws() , .CR putws_unlocked() , .CR fputws() , and .CR fputws_unlocked() fail if either the .I stream is unbuffered, or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP [EILSEQ] A wide character in .I ws does not correspond to a valid character. .RE .PP Additional .CR errno values may be set by the underlying .CR write() function (see .IR write(2)). .SH AUTHOR .CR putws() and .CR fputws() were developed by OSF and HP. .SH SEE ALSO ferror(3S), flockfile(3S), fopen(3S), fread(3S), printf(3S), putwc(3C). .SH STANDARDS CONFORMANCE .CR fputws() ": XPG4" .\" .\" index@\f4putws()\f1, \f4fputws()\f1 \- write null-terminated wide string to a named stream file@@@\f3putws(3C)\f1 .\" index@\f1write a null-terminated wide string on a stream@@@\f3putws(3C)\f1 .\" .\" toc@\f3putws(3C)\f1:\0\0\f4putws()\f1, \f4fputws()\f1@@@put a wide string on a stream .\" toc@\f4fputws()\f1:\0\0put a wide string on a stream@@@see \f3putws(3C)\f1 .\" .\" links@putws.3c fputws.3c .\" links@putws.3c putws_unloc.3c .\" links@putws.3c fputws_unlo.3c .\" .\" fileset_database@putws.3c PROGRAMING-MAN .\" $Header: putws.3c,v 72.3 94/11/15 09:55:52 ssa Exp $ .TA p .TH putws 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putws(\|), putws_unlocked(\|), fputws(\|), fputws_unlocked(\|) \- put a wide character string on a stream file .SH SYNOPSIS .C "#include " .PP .C "int putws(const wchar_t *ws);" .PP .C "int putws_unlocked(const wchar_t *ws);" .PP .C "int fputws(const wchar_t *ws, FILE *stream);" .PP .C "int fputws_unlocked(const wchar_t *ws, FILE *stream);" .SS Remarks: .CR fputws is compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. These functions parallel the 8 bit character I/O functions defined in .IR puts(3S) . .SH DESCRIPTION .CR putws() writes a character string corresponding to the null-terminated wide-character string pointed to by .I ws followed by a new-line character, to the standard output stream .CR stdout . .PP .CR fputws() writes a character string corresponding to the null-terminated wide-character string pointed to by .I ws to the named output .IR stream , but does .I not append a new-line character or a terminating null character. .PP Neither function writes a terminating null character. .PP The definition for these functions, the type .CR wchar_t and the value .CR WEOF are provided in the .RC < wchar.h > header. .PP .CR putws_unlocked() and .CR fputws_unlocked() are identical to .CR putws() and .CR fputws() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. .CR putws_unlocked() and .CR fputws_unlocked() can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE Upon successful completion, .CR putws() , .CR putws_unlocked() , .CR fputws() , and .CR fputws_unlocked() return a non-negative number. Otherwise they return .CR WEOF , set the error indicator for the stream, and set .CR errno to indicate the error. .SH ERRORS .CR putws() , .CR putws_unlocked() , .CR fputws() , and .CR fputws_unlocked() fail if either the .I stream is unbuffered, or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP [EILSEQ] A wide character in .I ws does not correspond to a valid character. .RE .PP Additional .CR errno values may be set by the underlying .CR write() function (see .IR write(2)). .SH AUTHOR .CR putws() and .CR fputws() were developed by OSF and HP. .SH SEE ALSO ferror(3S), flockfile(3S), fopen(3S), fread(3S), printf(3S), putwc(3C). .SH STANDARDS CONFORMANCE .CR fputws() ": XPG4" .\" .\" index@\f4putws()\f1, \f4fputws()\f1 \- write null-terminated wide string to a named stream file@@@\f3putws(3C)\f1 .\" index@\f1write a null-terminated wide string on a stream@@@\f3putws(3C)\f1 .\" .\" toc@\f3putws(3C)\f1:\0\0\f4putws()\f1, \f4fputws()\f1@@@put a wide string on a stream .\" toc@\f4fputws()\f1:\0\0put a wide string on a stream@@@see \f3putws(3C)\f1 .\" .\" links@putws.3c fputws.3c .\" links@putws.3c putws_unloc.3c .\" links@putws.3c fputws_unlo.3c .\" .\" fileset_database@putws.3c PROGRAMING-MAN .\" $Header: fread.3s,v 72.7 94/11/14 15:28:40 ssa Exp $ .TA f .TH fread 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fread(\|), fread_unlocked(\|), fwrite(\|), fwrite_unlocked(\|) \- buffered binary input/output to a stream file .SH SYNOPSIS .C "#include\0" .nf .PP .C "size_t\0fread(void\0*ptr,\0size_t\0size,\0size_t\0nitems,\0FILE\0*stream);" .PP .C "size_t\0fread_unlocked( .PD 0 .IP .C "void\0*ptr," .C "\0size_t\0size," .C "\0size_t\0nitems," .C "\0FILE\0*stream);" .PD .PP .C "size_t\0fwrite(const\0void\0*ptr,\0size_t\0size,\0size_t\0nitems,\0FILE\0*stream);" .PP .C "size_t\0fwrite_unlocked(" .PD 0 .IP .C "const\0void\0*ptr," .C "\0size_t\0size," .C "\0size_t\0nitems," .C "\0FILE\0*stream);" .PD .SH DESCRIPTION .CR fread() copies, into an array pointed to by .IR ptr , .I nitems items of data from the named input .IR stream , where an item of data is a sequence of bytes (not necessarily terminated by a null byte) of length .IR size . .CR fread() stops appending bytes if an end-of-file or error condition is encountered while reading .IR stream, or if .I nitems items have been read. .CR fread() leaves the file pointer in .IR stream , if defined, pointing to the byte following the last byte read if there is one. .CR fread() does not change the contents of .IR stream . .PP .CR fwrite() appends at most .I nitems items of data from the array pointed to by .I ptr to the named output .IR stream . .CR fwrite() stops appending when it has appended .I nitems items of data or if an error condition is encountered on .IR stream . .CR fwrite() does not change the contents of the array pointed to by .IR ptr . .PP The argument .I size is typically .IR sizeof (\(** ptr ) where the pseudo-function .I sizeof specifies the length of an item pointed to by .IR ptr . .PP .CR fread_unlocked() and .CR fwrite_unlocked() are identical to .CR fread() and .CR fwrite() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH "SEE ALSO" read(2), write(2), fopen(3S), flockfile(3S), getc(3S), gets(3S), printf(3S), putc(3S), puts(3S), scanf(3S). .SH RETURN VALUE .CR fread() , " fread_unlocked()" , " fwrite()" , and .CR fwrite_unlocked() return the number of items read or written. If .I size or .I nitems is non-positive, no characters are read or written and 0 is returned by .CR fread() , " fread_unlocked()" , " fwrite()" , and .CR fwrite_unlocked() . .SH STANDARDS CONFORMANCE .CR fread() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fwrite() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fread()\f1, \f4fwrite()\f1 \- buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@\f4fwrite()\f1, \f4fread()\f1 \- buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@file, stream: buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@binary input/output to a stream file, buffered@@@\f3fread(3S)\f1 .\" index@input/output to a stream file, buffered binary@@@\f3fread(3S)\f1 .\" index@\s-1I/O\s+1 to a stream file, buffered binary@@@\f3fread(3S)\f1 .\" index@stream file, buffered binary input/output to a@@@\f3fread(3S)\f1 .\" .\" toc@\f3fread(3S)\f1:\0\0\f4fread()\f1, \f4fwrite()\f1@@@buffered binary input/output to a stream file .\" toc@\f4fwrite()\f1:\0\0buffered binary output to a stream file@@@see \f3fread(3S)\f1 .\" .\" links@fread.3s fread_unloc.3s .\" links@fread.3s fwrite.3s .\" links@fread.3s fwrite_unlo.3s .\" $Header: fread.3s,v 72.7 94/11/14 15:28:40 ssa Exp $ .TA f .TH fread 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fread(\|), fread_unlocked(\|), fwrite(\|), fwrite_unlocked(\|) \- buffered binary input/output to a stream file .SH SYNOPSIS .C "#include\0" .nf .PP .C "size_t\0fread(void\0*ptr,\0size_t\0size,\0size_t\0nitems,\0FILE\0*stream);" .PP .C "size_t\0fread_unlocked( .PD 0 .IP .C "void\0*ptr," .C "\0size_t\0size," .C "\0size_t\0nitems," .C "\0FILE\0*stream);" .PD .PP .C "size_t\0fwrite(const\0void\0*ptr,\0size_t\0size,\0size_t\0nitems,\0FILE\0*stream);" .PP .C "size_t\0fwrite_unlocked(" .PD 0 .IP .C "const\0void\0*ptr," .C "\0size_t\0size," .C "\0size_t\0nitems," .C "\0FILE\0*stream);" .PD .SH DESCRIPTION .CR fread() copies, into an array pointed to by .IR ptr , .I nitems items of data from the named input .IR stream , where an item of data is a sequence of bytes (not necessarily terminated by a null byte) of length .IR size . .CR fread() stops appending bytes if an end-of-file or error condition is encountered while reading .IR stream, or if .I nitems items have been read. .CR fread() leaves the file pointer in .IR stream , if defined, pointing to the byte following the last byte read if there is one. .CR fread() does not change the contents of .IR stream . .PP .CR fwrite() appends at most .I nitems items of data from the array pointed to by .I ptr to the named output .IR stream . .CR fwrite() stops appending when it has appended .I nitems items of data or if an error condition is encountered on .IR stream . .CR fwrite() does not change the contents of the array pointed to by .IR ptr . .PP The argument .I size is typically .IR sizeof (\(** ptr ) where the pseudo-function .I sizeof specifies the length of an item pointed to by .IR ptr . .PP .CR fread_unlocked() and .CR fwrite_unlocked() are identical to .CR fread() and .CR fwrite() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH "SEE ALSO" read(2), write(2), fopen(3S), flockfile(3S), getc(3S), gets(3S), printf(3S), putc(3S), puts(3S), scanf(3S). .SH RETURN VALUE .CR fread() , " fread_unlocked()" , " fwrite()" , and .CR fwrite_unlocked() return the number of items read or written. If .I size or .I nitems is non-positive, no characters are read or written and 0 is returned by .CR fread() , " fread_unlocked()" , " fwrite()" , and .CR fwrite_unlocked() . .SH STANDARDS CONFORMANCE .CR fread() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fwrite() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fread()\f1, \f4fwrite()\f1 \- buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@\f4fwrite()\f1, \f4fread()\f1 \- buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@file, stream: buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@binary input/output to a stream file, buffered@@@\f3fread(3S)\f1 .\" index@input/output to a stream file, buffered binary@@@\f3fread(3S)\f1 .\" index@\s-1I/O\s+1 to a stream file, buffered binary@@@\f3fread(3S)\f1 .\" index@stream file, buffered binary input/output to a@@@\f3fread(3S)\f1 .\" .\" toc@\f3fread(3S)\f1:\0\0\f4fread()\f1, \f4fwrite()\f1@@@buffered binary input/output to a stream file .\" toc@\f4fwrite()\f1:\0\0buffered binary output to a stream file@@@see \f3fread(3S)\f1 .\" .\" links@fread.3s fread_unloc.3s .\" links@fread.3s fwrite.3s .\" links@fread.3s fwrite_unlo.3s .\" $Header: malloc.3c,v 72.6 94/11/15 09:55:17 ssa Exp $ .TA m .TH malloc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME malloc(), free(), realloc(), calloc(), valloc(), mallopt(), mallinfo(), memorymap(), alloca() \- main memory allocator .SH SYNOPSIS .C "#include " .PP .C "void *malloc(size_t size);" .PP .C "void *calloc(size_t nelem, size_t elsize);" .PP .C "void *realloc(void *ptr, size_t size);" .PP .C "void *valloc(size_t size);" .PP .C "void free(void *ptr);" .PP .C "void memorymap(int show_stats);" .PP .C " " .PP .C "#include " .PP .C "void *alloca(size_t size);" .SH SYSTEM V SYNOPSIS .C "#include " .PP .C "char *malloc(unsigned size);" .PP .C "void free(char *ptr);" .PP .C "char *realloc(char *ptr, unsigned size);" .PP .C "char *calloc(unsigned nelem, unsigned elsize);" .PP .C "int mallopt(int cmd, int value);" .PP .C "struct mallinfo mallinfo(void);" .SS Remarks The functionality in the old .IR malloc (3X) package has been incorporated into .IR malloc (3C). The library .RC ( /usr/lib/libmalloc.a ) corresponding to the .CR -lmalloc linker option is now an empty library. Makefiles that reference this library will continue to work. Applications that used the .IR malloc (3X) package should still work properly with the new .IR malloc (3C) package. If the old versions must be used, they are provided in files .CR /usr/old/libmalloc3x.a and .CR /usr/old/libmalloc3c.o for Release 8.07 only. .SH DESCRIPTION The functions described in this manual entry provide a simple, general purpose memory allocation package: .RS .TP 17 .C malloc() Allocates space for a block of at least .I size bytes, but does not initialize the space. .TP .C calloc() Allocates space for an array of .I nelem elements, each of size .I elsize bytes, and initializes the space to zeros. Actual amount of space allocated will be at least .I nelem * elsize bytes. .TP .C realloc() Changes the size of the block pointed to by .I ptr to .I size bytes and returns a pointer to the (possibly moved) block. Existing contents are unchanged up to the lesser of the new and old sizes. If .I ptr is a NULL pointer, .CR realloc() behaves like .CR malloc() for the specified size. If .I size is zero and .I ptr is not a NULL pointer, the object it points to is freed and NULL is returned. .TP .C valloc() Allocates space for a block of at least .I size bytes starting on a boundary aligned to a multiple of the value returned by .IR sysconf(__SC_PAGESIZE) . This space is uninitialized. .TP .C free() Deallocates the space pointed to by .I ptr (a pointer to a block previously allocated by .CR malloc() , .CR realloc() , or .CR calloc() ) and makes the space available for further allocation. If .I ptr is a NULL pointer, no action occurs. .TP .C mallopt() Provides for control over the allocation algorithm and other options in the .IR malloc (3C) package. The available values for .I cmd are: .RS .RS .TP 15 .C M_MXFAST Set .IR maxfast to .IR value . The algorithm allocates all blocks below the size of .IR maxfast in large groups, then doles them out very quickly. The default value for .IR maxfast is zero. .TP .C M_NLBLKS Set .IR numlblks to .IR value . The above mentioned ``large groups'' each contain .I numlblks blocks. .I numlblks must be greater than 1. The default value for .I numlblks is .CR 100 . .TP .C M_GRAIN Set .I grain to .IR value . The sizes of all blocks smaller than .I maxfast are considered to be rounded up to the nearest multiple of .IR grain . .I grain must be greater than zero. The default value of .I grain is the smallest number of bytes that can accommodate alignment of any data type. .I value is rounded up to a multiple of the default when .I grain is set. .TP .C M_KEEP Preserve data in a freed block until the next .CR malloc() , .CR realloc() , or .CR calloc() . This option is provided only for compatibility with the old version of .CR malloc() and is not recommended. .TP .C M_BLOCK Block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option is provided for those who need to write signal handlers that allocate memory. When set, the .IR malloc (3C) routines can be called from within signal handlers (they become re-entrant). Default action is .I not to block all blockable signals. .TP .C M_UBLOCK Do not block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option cancels signal blocking initiated by the .CR M_BLOCK option. .RE .RE .IP These values are defined in the .CR header file. .IP .CR mallopt() can be called repeatedly, but must not be called after the first small block is allocated (unless .I cmd is set to .CR M_BLOCK or .CR M_UBLOCK ). .TP .C mallinfo() Provides instrumentation describing space usage, but cannot be called until the first small block is allocated. It returns the structure: .nf .IP .C "struct mallinfo {" .C " int arena; /* total space in arena */" .C " int ordblks; /* number of ordinary blocks */" .C " int smblks; /* number of small blocks */" .C " int hblkhd; /* space in holding block headers */" .C " int hblks; /* number of holding blocks */" .C " int usmblks /* space in small blocks in use */" .C " int fsmblks /* space in free small blocks */" .C " int uordblks; /* space in ordinary blocks in use */" .C " int fordblks; /* space in free ordinary blocks */" .C " int keepcost; /* space penalty if keep option is used */" .C } .fi .IP This structure is defined in the .CR header file. .RE .PP Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. .RS .TP 17 .C memorymap() Can be used to display the contents of the memory allocator. A list of addresses and block descriptions is written (using .CR printf() ) to standard output. If the value of the .I show_stats parameter is 1, statistics concerning number of blocks and sizes used will also be written. If the value is zero, only the memory map will be written. .IP The addresses and sizes displayed by .CR memorymap() may not correspond to those requested by an application. The size of a block (as viewed by the allocator) includes header information and padding to properly align the block. The address is also offset by a certain amount to accommodate the header information. .TP .C alloca() Allocates space from the stack of the caller for a block of at least .I size bytes, but does not initialize the space. The space is automatically freed when the calling routine exits. .IP Memory returned by .CR alloca() is not related to memory allocated by other memory allocation functions. Behavior of addresses returned by .CR alloca() as parameters to other memory functions is undefined. .IP The implementation of this routine is system dependent and its use is discouraged. .RE .SH RETURN VALUE Upon successful completion, .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. Otherwise, they return a NULL pointer. If .CR realloc() returns a NULL pointer, the memory pointed to by the original pointer is left intact. .PP .CR mallopt() returns zero for success and nonzero for failure. .SH DIAGNOSTICS .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a NULL pointer if there is no available memory, or if the memory managed by .CR malloc() has been detectably corrupted. This memory may become corrupted if data is stored outside the bounds of a block, or if an invalid pointer (a pointer not generated by .CR malloc() , .CR realloc() , or .CR calloc() ) is passed as an argument to .CR free() or .CR realloc() . .PP If .CR mallopt() is called after any allocation of a small block and .I cmd is not set to .CR M_BLOCK or .CR M_UBLOCK , or if .I cmd or .I value is invalid, nonzero is returned. Otherwise, it returns zero. .SH ERRORS .RS .TP 17 [ENOMEM] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to ENOMEM and return a NULL pointer when an out-of-memory condition arises. .TP [EINVAL] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to EINVAL and return a NULL pointer when the memory being managed by .CR malloc() has been detectably corrupted. .SH WARNINGS .CR malloc() functions use .CR brk() and .CR sbrk() (see .IR brk (2)) to increase the address space of a process. Therefore, an application program that uses .CR brk() or .CR sbrk() must not use them to decrease the address space, because this confuses the .CR malloc() functions. .PP .CR free() and .CR realloc() do not check their pointer argument for validity. .PP If .CR free() or .CR realloc() is passed a pointer that was not the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() , or if space assigned by an allocation function is overrun, loss of data, a memory fault, bus error, or an infinite loop may occur at that time or during any subsequent call to .CR malloc() , .CR realloc() , .CR calloc() , .CR valloc() , or .CR free() . .PP The following actions are not supported and cause undesirable effects: .RS .TP 3 \(bu Attempting to .CR free() or .CR realloc() a pointer not generated as the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() . .RE .PP The following actions are strongly discouraged and may be unsupported in a future implementation of .CR malloc() : .RS .TP 3 \(bu attempting to .CR free() the same block twice, .TP \(bu depending on unmodified contents of a block after it has been freed. .RE .PP Undocumented features of earlier memory allocators have not been duplicated. .SH COMPATIBILITY The only external difference between the old .IR malloc (3X) allocator and the .IR malloc (3C) allocator is that the old allocator would return a NULL pointer for a request of zero bytes. The .IR malloc (3C) allocator returns a valid memory address. This is not a concern for most applications. .ift .br .ift .ne 4 .PP Although the current implementation of .IR malloc (3C) allows for freeing a block twice and does not corrupt the contents of a block after it is freed (until the next call to .CR realloc() , .CR calloc() , .CR malloc() , or .CR valloc() ), support for these features may be discontinued in a future implementation of .IR malloc (3C) and should not be used. .SH SEE ALSO brk(2), errno(2). .SH STANDARDS CONFORMANCE .CR malloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR calloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR free() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mallinfo() ": SVID2, XPG2" .PP .CR mallopt() ": SVID2, SVID3, XPG2" .PP .CR realloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4malloc()\f1 \- allocate block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4free()\f1 \- release allocated block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4realloc()\f1 \- change size of allocated memory block@@@\f3malloc(3C)\f1 .\" index@\f4calloc()\f1 \- allocate memory for array@@@\f3malloc(3C)\f1 .\" index@\f4mallopt()\f1 \- control memory space allocation@@@\f3malloc(3C)\f1 .\" index@\f4mallinfo()\f1 \- display memory space usage@@@\f3malloc(3C)\f1 .\" index@\f4memorymap()\f1 \- display contents of memory allocator@@@\f3malloc(3C)\f1 .\" index@\f4alloca()\f1 \- allocate space from the stack@@@\f3malloc(3C)\f1 .\" index@\f4valloc()\f1 \- allocate space on boundary aligned to sysconf value@@@\f3malloc(3C)\f1 .\" index@\f1main memory allocator@@@\f3malloc(3C)\f1 .\" index@\f1memory allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1main memory space usage, display@@@\f3malloc(3C)\f1 .\" index@\f1main memory space allocation, control@@@\f3malloc(3C)\f1 .\" .\" toc@\f3malloc(3C)\f1:\0\0\f4alloca()\f1, \f4calloc()\f1, \f4free()\f1, \f4mallinfo()\f1,\n\f4malloc()\f1, \f4mallopt()\f1, \f4memorymap()\f1, \f4realloc()\f1, \f4valloc()\f1@@@main memory allocator\f1 .\" .\" toc@\f4free()\f1:\0\0release allocated block of main memory@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4realloc()\f1:\0\0change size of allocated memory block@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4calloc()\f1:\0\0allocate memory for array@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4valloc()\f1:\0\0allocate space on boundary aligned to sysconf value@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallopt()\f1:\0\0control memory space allocation@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallinfo()\f1:\0\0display memory space usage@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4memorymap()\f1:\0\0display contents of memory allocator@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4alloca()\f1:\0\0allocate space from the stack@@@\f1see \f3malloc(3C)\f1 .\" .\" links@malloc.3c free.3c .\" links@malloc.3c realloc.3c .\" links@malloc.3c calloc.3c .\" links@malloc.3c valloc.3c .\" links@malloc.3c mallopt.3c .\" links@malloc.3c mallinfo.3c .\" links@malloc.3c memorymap.3c .\" links@malloc.3c alloca.3c .\" $Header: fopen.3s,v 78.1 96/02/12 13:46:50 ssa Exp $ .TA f .TH fopen 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fopen(\|), freopen(\|), fdopen(\|) \- open or re-open a stream file; convert file to stream .SH SYNOPSIS .C "#include " .PP .C "FILE *fopen(const char *pathname, const char *type);" .PP .C "FILE *freopen(const char *pathname, const char *type, FILE *stream);" .PP .C "FILE *fdopen(int fildes, const char *type);" .SH DESCRIPTION .TP 15 .C fopen() Opens the file named by .I pathname and associates a .I stream with it. .C fopen() returns a pointer to the .C FILE structure associated with the .IR stream . .TP .C freopen() substitutes the named file in place of the open .IR stream . The original .I stream is closed, regardless of whether the open ultimately succeeds. .C freopen() returns a pointer to the .C FILE structure associated with .IR stream and makes an implicit call to .C clearerr() (see .IR ferror (3S)). .IP .C freopen() is typically used to attach the preopened .I streams associated with .CR stdin , .CR stdout , and .C stderr to other files. .TP .C fdopen() associates a stream with a file descriptor. File descriptors are obtained from .CR open() , .CR dup() , .CR creat() , or .C pipe() (see .IR open (2), .IR dup (2), .IR creat (2), and .IR pipe (2)), which open files but do not return pointers to a .C FILE structure stream. Streams are necessary input for many of the Section (3S) library routines. The .I type of stream must agree with the mode of the open file. The meanings of .I type used in the .C fdopen() call are exactly as specified above, except that .CR w , .CR w+ , .CR wb , and .C wb+ do not cause truncation of the file. .TP .I pathname Points to a character string containing the name of the file to be opened. .TP .I type Character string having one of the following values: .RS .RS .TP 15 .C r open for reading .TP .C w truncate to zero length or create for writing .TP .C a append; open for writing at end of file, or create for writing .TP .C rb open binary file for reading .TP .C wb truncate to zero length or create binary file for writing .TP .C ab append; open binary file for writing at end-of-file, or create binary file .TP .C r+ open for update (reading and writing) .TP .C w+ truncate to zero length or create for update .TP .C a+ append; open or create for update at end-of-file .TP .CI r+b \0or \0rb+ open binary file for update (reading and writing) .TP .CI w+b \0or \0wb+ truncate to zero length or create binary file for update .TP .CI a+b \0or \0ab+ append; open or create binary file for update at end-of-file .RE .RE .PP When a file is opened for update, both input and output can be done on the resulting .IR stream . However, output cannot be directly followed by input without an intervening call to .C fflush() or to a file positioning function .RC ( fseek() , .CR fsetpos() , or .CR rewind() ), and input cannot be directly followed by output without an intervening call to a file positioning function unless the input operation encounters end-of-file. .PP When a file is opened for append (i.e., when .I type is .C a or .CR a+ ), it is impossible to overwrite information already in the file. All output is written at the end of the file, regardless of intervening calls to .CR fseek() . If two separate processes open the same file for append, each process can write freely to the file without fear of destroying output being written by the other. Output from the two processes will be intermixed in the file in the order in which it is written. .SH RETURN VALUE Upon successful completion, .CR fopen() , .CR fdopen() , and .CR freopen() return a .C FILE * pointer to the stream. Otherwise, a null pointer is returned and .C errno is set to indicate the error. .SH ERRORS .CR fopen() , .CR fdopen() , and .CR freopen() fail if: .TP 15 .SM [EINVAL] The .I type argument is not a valid mode. .TP .SM [ENOMEM] There is insufficient space to allocate a buffer. .PP .C fopen() and .C freopen() fail if: .TP 15 .SM [EACCES] Search permission is denied on a component of the path prefix, or the file exists and the permissions specified by .I type are denied, or the file does not exist and write permission is denied for the parent directory of the file to be created. .TP .SM [EINTR] A signal was caught during .C fopen() or .CR freopen() . function. .TP .SM [EISDIR] The named file is a directory and .I type requires write access. .TP .SM [EMFILE] The calling process has attempted to exceed its open file limit. .TP .SM [ENAMETOOLONG] The length of the .I pathname string exceeds .C PATH_MAX or a pathname component is longer than .C NAME_MAX while .SM POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] The system file table is full. .TP .SM [ENOENT] The named file does not exist or the .I pathname argument points to an empty string. .TP .SM [ENOSPC] The directory or file system that would contain the new file cannot be expanded, the file does not exist, and it was to be created. .TP .SM [ENOTDIR] A component of the path prefix is not a directory. .TP .SM [ENXIO] The named file is a character special or block special file, and the device associated with the special file does not exist. .TP .SM [EOVERFLOW] The named file is a regular file and the size of the file cannot be represented correctly in an object of size .CR off_t in this environment. .TP .SM [EROFS] The named file resides on a read-only file system and .I type requires write access. .PP Additional .C errno values can be set by the underlying .CR open() call made from the .CR fopen() and .CR freopen() functions (see .IR open(2)). .SH NOTES .SM HP-UX binary file .I types are equivalent to their non-binary counterparts. For example, types .C r and .C rb are equivalent. .SH SEE ALSO creat(2), dup(2), open(2), pipe(2), fclose(3S), fopen64(3S), freopen64(3S), fseek(3S), popen(3S), setvbuf(3S). .SH STANDARDS CONFORMANCE .CR fopen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fdopen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR freopen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fopen()\f1 \- open a named file and associate with a stream@@@\f3fopen(3S)\f1 .\" index@\f4freopen()\f1 \- substitute a named file in place of an already open stream@@@\f3fopen(3S)\f1 .\" index@\f4fdopen()\f1 \- associate a stream with an open file descriptor@@@\f3fopen(3S)\f1 .\" index@\f1file, stream: open or re-open a stream file; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1file, stream: convert file to stream; open or re-open a stream file@@@\f3fopen(3S)\f1 .\" index@\f1open or re-open a stream file; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1re-open or open a stream file; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1stream file, open or re-open; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1stream file, open or re-open; convert file to stream@@@\f3fopen(3S)\f1 .\" index@\f1convert file to stream@@@\f3fopen(3S)\f1 .\" .\" toc@\f3fopen(3S)\f1:\0\0\f4fopen()\f1, \f4freopen()\f1, \f4fdopen()\f1@@@open or re-open a stream file; convert file to stream .\" toc@\f4freopen()\f1:\0\0re-open a stream file; convert file to stream@@@see \f3fopen(3S)\f1 .\" toc@\f4fdopen()\f1:\0\0associate a stream with a file descriptor@@@see \f3fopen(3S)\f1 .\" .\" links@fopen.3s freopen.3s .\" links@fopen.3s fdopen.3s .\" .\" $Header: fgetpos64.3s,v 78.3 96/02/12 17:04:12 ssa Exp $ .TA f .TH fgetpos64 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetpos64(\|), fopen64(\|), freopen64(\|), fseeko64(\|), fsetpos64(\|), fstatvfsdev64(\|), ftello64(\|), ftw64(\|), nftw64(\|), statvfsdev64(\|), tmpfile64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0fgetpos64(FILE\0*stream,\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "FILE\0*fopen64(const\0char\0*pathname,\0const\0char\0*type);" .PP .C "#include " .PP .C "FILE\0*freopen64(const\0char\0*pathname,\0const\0char\0*type,\0FILE\0*stream);" .PP .C "#include " .PP .C "int\0fseeko64(FILE\0*stream,\0off64_t\0*offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0fsetpos64(FILE\0*stream,\0const\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "int\0fstatvfsdev64(int\0filedes,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "off64_t\0ftello64(FILE\0*stream);" .PP .nf .C "#include " .PP .C "int ftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags)," .C " int depth);" .PP .C "#include " .PP .C "int nftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .PP .C "#include " .PP .C "int\0statvfsdev64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "FILE\0*tmpfile64(void);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 22 .C fgetpos64() The .C fgetpos64() function is identical to .C fgetpos() except that .C fgetpos64() returns the position in a .C fpos64_t instead of a .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fopen64() The .C fopen64() function is identical to .C fopen() in 64-bit compile environment. The .C fopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR fopen() . .TP .C freopen64() The .C freopen64() function is identical to .C freopen() in 64-bit compile environment. The .C freopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR freopen() . .TP .C fseeko64() The .C fseeko64() function is identical to .C fseeko() except that .C fseeko64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C fsetpos64() The .C fsetpos64() function is identical to .C fsetpos() except that .C fsetpos64() accepts an .CR fpos64_t for the pos parameter instead of .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fstatvfsdev64() The .C fstatvfsdev64() function is identical to .C fstatvfsdev() except that .C fstatvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C ftello64() The .C ftello64() function is identical to .C ftello() except that .C ftello64() returns the file position in an .C off64_t instead of an .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C ftw64() The .C ftw64() function is identical to .C ftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR ftw64() . All other functional behaviors, returns, and errors are identical. .TP .C nftw64() The .C nftw64() function is identical to .C nftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR nftw64() . All other functional behaviors, returns, and errors are identical. .TP .C statvfsdev64() The .C statvfsdev64() function is identical to .C statvfsdev() except that .C statvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C tmpfile64() The .C tmpfile64() function is identical to .C tmpfile() in the 64-bit compile environment. Both interfaces create a temporary file that is capable of growing beyond 2GB's if desired. All other functional behaviors, returns, and errors are identical. .\" .\" toc@\f4fgetpos64(2)\f1:\0\0\f4fopen64\f1, \f4freopen64\f1, \f4fseeko64\f1, \f4fsetpos64\f1, \f4fstatvfsdev64\f1, \f4ftello64\f1, \f4ftw64\f1, \n\f4nftw64\f1, \f4statvfsdev64\f1, \f4tmpfile64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4fgetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4freopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fseeko64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fsetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fstatvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftello64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4nftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4statvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4tmpfile64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3fgetpos64(2)\f1 .\" .\" links@fgetpos64.3s fopen64.3s .\" links@fgetpos64.3s freopen64.3s .\" links@fgetpos64.3s fseek64.3s .\" links@fgetpos64.3s fsetpos64.3s .\" links@fgetpos64.3s fstatvfs64.3s .\" links@fgetpos64.3s ftello64.3s .\" links@fgetpos64.3s ftw64.3s .\" links@fgetpos64.3s nftw64.3s .\" links@fgetpos64.3s statvfsdev64.3s .\" links@fgetpos64.3s tmpfile64.3s .\" .\" $Header: frexp.3m,v 78.3 96/02/13 11:20:38 ssa Exp $ .TA f .TH frexp 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME frexp(\|) \- extract mantissa and exponent from double-precision number .SH SYNOPSIS .C "#include " .PP .C "double frexp(double num, int *exp);" .SH DESCRIPTION The .CR frexp() function breaks a floating-point number into a normalized fraction and an integral power of 2. It stores the integer exponent in the .CR int object pointed to by .IR exp . .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE The .CR frexp() function returns the value .IR x , such that .I x is a .CR double with magnitude in the interval [0.5, 1] or zero, and .I num equals .I x times 2 raised to the power .IR *exp . .PP If .I num is zero, both parts of the result are zero. .PP If .I num is NaN, .CR frexp() returns NaN, and the value of .I *exp is unspecified. .PP If .I num .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR frexp() returns .IR num , and the value of .I *exp is unspecified. .SH ERRORS No errors are defined. .SH SEE ALSO isnan(3M), ldexp(3M), modf(3M), scalb(3M). .SH STANDARDS CONFORMANCE .CR frexp() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4frexp\f1 \- extract mantissa and exponent from double-precision number@@@\f3frexp(3M)\f1 .\" index@\f1math: extract mantissa and exponent from double-precision number@@@\f3frexp(3M)\f1 .\" index@\f1extract mantissa and exponent from double-precision number@@@\f3frexp(3M)\f1 .\" index@\f1floating-point: extract mantissa and exponent from double-precision number@@@\f3frexp(3M)\f1 .\" index@\f1separate double-precision number into mantissa and exponent@@@\f3frexp(3M)\f1 .\" index@\f1mantissa and exponent, split double-precision number into@@@\f3frexp(3M)\f1 .\" index@\f1exponent and mantissa, split double-precision number into@@@\f3frexp(3M)\f1 .\" .\" toc@\f3frexp(3M)\f1:\0\0\f4frexp\f1@@@extract mantissa and exponent from double-precision number .\" $Header: crt0.3,v 72.4 94/09/02 14:40:25 ssa Exp $ .TA c .TH crt0 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crt0.o, gcrt0.o, mcrt0.o \- execution startup routines .SH DESCRIPTION .PP The C, Pascal, and FORTRAN compilers link in the object files .CR crt0.o , .CR gcrt0.o , or .C mcrt0.o to provide startup capabilities and environments for program execution. All are identical except that .C gcrt0.o and .C mcrt0.o provide additional functionality for .IR gprof (1) and .IR prof (1) profiling support respectively. .PP The following symbols are defined in these object files: .RS .TP 20 .C _\|_argc_value A variable of type .I int containing the number of arguments. .TP .C _\|_argv_value An array of character pointers to the arguments themselves. .TP .C _environ An array of character pointers to the environment in which the program will run. This array is terminated by a null pointer. .TP .SM .C _FPU_MODEL A variable of type .I short containing the FPU model number returned by the FP status instruction. This variable is initialized with data from the kernel. .TP .SM .C _FPU_REVISION A variable of type .I short containing the FPU revision number returned by the FP status instruction. This variable is initialized with data from the kernel. .TP .SM .C _CPU_REVISION A variable of type .I int containing the CPU revision of the machine. This variable is initialized with data from the kernel. .TP .SM .C _SYSTEM_ID A variable of type .I int containing the system id value for an executable program. .TP .SM .C $START$ Execution start address. .TP .C _start A secondary startup routine for C programs, called from .CR $START$ , which in turn calls .CR main . This routine is contained in the C library rather than the .C crt0.o file. For Pascal and F\s-2ORTRAN\s0 programs, this symbol labels the beginning of the outer block (main program) and is generated by the compilers. .TP .C $global$ The initial address of the program's data pointer. The startup code loads this address into general register 27. .TP .C $UNWIND_START The beginning of the stack unwind table. .TP .C $UNWIND_END The end of the stack unwind table. .TP .C $RECOVER_START The beginning of the try/recover table. .TP .C $RECOVER_END The end of the try/recover table. .RE .PP The .C crt0.o file defines a null procedure for .CR _mcount , so programs compiled with profiling can be linked without profiling. .PP The linker defines the following two symbols: .RS .TP 20 .C _\|_text_start The beginning address of the program's text area. .PD 0 .TP .C _\|_data_start The beginning address of the program's data area. .PD .RE .SH AUTHOR The features described in this entry originated from .SM AT&T UNIX System III. .SH SEE ALSO .PD .SS Profiling and Debugging Tools: .TP 18 .IR gprof(1) display call graph profile data .PD 0 .TP .IR monitor(3C) prepare execution profile .TP .IR prof(1) display profile data .TP .IR profil(2) execution time profile .PD .SS System Tools: .TP 18 .IR cc(1) invoke the HP-UX C compiler .PD 0 .TP .IR exec(2) execute a file .TP f77(1) invoke the HP-UX FORTRAN compiler .TP .IR ld(1) invoke the link editor .TP .IR pc(1) invoke the HP-UX Pascal compiler .PD .SS Miscellaneous: .TP 18 .IR end(3C) symbol of the last locations in program .PD .\" .\" index@\f4crt0.o\f1, \f4gcrt0.o\f1, \f4mcrt0.o\f1, \f4frt0.o\f1, \f4mfrt0.o\f1 \- execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4crt0.o\f1, \f4mcrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4gcrt0.o\f1, \f4gfrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4gfrt0.o\f1, \f4gcrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4mcrt0.o\f1, \f4crt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4frt0.o\f1, \f4mfrt0.o\f1 \- F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4mfrt0.o\f1, \f4frt0.o\f1 \- F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@Pascal and C execution startup routines@@@\f3crt0(3)\f1 .\" index@F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@execution startup routines, C, Pascal, and F\s-2ORTRAN\s+2@@@\f3crt0(3)\f1 .\" .\" toc@\f3crt0(3)\f1:\0\0\f4crt0.o\f1, \f4mcrt0.o\f1, \f4frt0.o\f1, \f4mfrt0.o\f1@@@execution startup routines .\" toc@\f4crt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4gcrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4mcrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4frt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4mfrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" .\" links@crt0.3 crt0.o.3 .\" links@crt0.3 gcrt0.o.3 .\" links@crt0.3 mcrt0.o.3 .\" links@crt0.3 frt0.o.3 .\" links@crt0.3 gfrt0.o.3 .\" links@crt0.3 mfrt0.o.3 .\" .\" fileset_database@crt0.3 PROGRAMING-MAN .\" $Header: scanf.3s,v 72.7 94/12/08 12:16:59 ssa Exp $ .TA s .TH scanf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scanf, fscanf, sscanf \- formatted input conversion, read from stream file .SH SYNOPSIS .C "#include " .PP .C "int scanf(const char *format, /* [pointer,] */ ...);" .PP .C "int fscanf(FILE *stream, const char *format, /* [pointer,] */ ...);" .PP .C "int sscanf(const char *s, const char *format, /* [pointer,] */ ...);" .SH DESCRIPTION .C scanf() reads from the standard input stream .IR stdin . .PP .C fscanf() reads from the named input .IR stream . .PP .C sscanf() reads from the character string .IR s . .PP Each function reads characters, interprets them according to the control string .I format argument, and stores the results in its .I pointer arguments. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are ignored. The control string contains conversion specifications and other characters used to direct interpretation of input sequences. The control string contains: .RS .TP 3 \(bu White-space characters (blanks, tabs, newlines, or formfeeds) that cause input to be read up to the next non-white-space character (except in two cases described below). .TP \(bu An ordinary character (not .CR % ) that must match the next character of the input stream. .TP \(bu Conversion specifications, consisting of the character .CR % , an optional assignment suppressing character .CR * , an optional numerical maximum-field width, an optional .C l (ell), .CR ll , (ell ell), .C h or .C L indicating the size of the receiving variable, and a conversion code. .TP \(bu The conversion specification can alternatively be prefixed by the character sequence .CI % n $ instead of the character .CR % , where .I n is a decimal integer in the range .RC (1\|\(mi\| {NL_ARGMAX} ) .RC ( NL_ARGMAX is defined in .RC < limits.h >). The .CI % n $ construction indicates that the value of the next input field should be placed in the .IR n th argument, rather than to the next unused one. The two forms of introducing a conversion specification, .C % and .CI % n $\f1, must not be mixed within a single .I format string with the following exception: Skip fields (see below) can be designated as .C %* or .CI % n $*\f1. In the latter case, .I n is ignored. .RE .PP Unless the specification contains the .C n conversion character (described below), a conversion specification directs the conversion of the next input field. The result of a conversion specification is placed in the variable to which the corresponding argument points, unless .C * indicates assignment suppression. Assignment suppression provides a way to describe an input field to be skipped. An input field is defined as a string of non-space characters; it extends to the next inappropriate character or until the field width, if specified, is exhausted. For all descriptors except .C [ and .CR c , white space leading an input field is ignored. .PP The conversion code indicates the interpretation of the input field; the corresponding pointer argument must be of a restricted type. For a suppressed field, no pointer argument is given. The following conversion codes are legal: .RS .TP 12 .C % A single .C % is expected in the input at this point; no assignment is done. .TP .C d A decimal integer is expected; the corresponding argument should be an integer pointer. .TP .C u An unsigned decimal integer is expected; the corresponding argument should be an unsigned integer pointer. .TP .C o An octal integer is expected; the corresponding argument should be an unsigned integer pointer. .TP .CR x ,\0 X A hexadecimal integer is expected; the corresponding argument should be an unsigned integer pointer. The .C x and .C X conversion characters are equivalent. .TP .C i An integer is expected; the corresponding argument should be an integer pointer. The value of the next input item, interpreted according to C conventions, will be stored; a leading .C 0 implies octal, a leading .C 0x implies hexadecimal; otherwise, decimal is assumed. .TP .C n Cause the total number of bytes (including white space) scanned since the function call to be stored; the corresponding argument should be an integer pointer. No input is consumed. The function return value does not include .CI % n assignments in the count of successfully matched and assigned input items. .TP .ift \s+1\f4e\fP,\f3E\fP,\f3f\fP,\f3g\fP,\f3G\fP\s0 .ifn \f3e\fP,\f3E\fP,\f3f\fP,\f3g\fP,\f3G\fP A floating-point number is expected; the next field is converted accordingly and stored through the corresponding argument, which should be a pointer to a .IR float . The input format for floating-point numbers is an optionally signed string of digits, possibly containing a radix character, followed by an optional exponent field consisting of an .C E or an .CR e , followed by an optional .CR + , .CR - , or space, followed by an integer. The conversion characters .C E and .C G behave the same as, respectively, .C e and .CR g . .TP .C C A character is expected; the corresponding argument should be a .C wchar_t pointer. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use .CR %1S . The character is read and converted into a wide character according to the setting of .CR LC_CTYPE . If a field width is given, the corresponding argument refers to a wide character array; the indicated number of characters is read and converted. .TP .C c A character is expected; the corresponding argument should be a character pointer. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use .CR %1s . If a field width is given, the corresponding argument refers to a character array; the indicated number of characters is read. .TP .C S A character string is expected; the corresponding argument should be a .C wchar_t pointer pointing to an array of wide characters large enough to accept the string and a terminating .CR (wchar_t)0 , which is added automatically. Characters are read and converted into wide characters according to the setting of .CR LC_CTYPE . The input field is terminated by a white-space character. .C scanf() cannot read a null string. .TP .C s A character string is expected; the corresponding argument should be a character pointer pointing to an array of characters large enough to accept the string and a terminating .CR \e0 , which is added automatically. The input field is terminated by a white-space character. .C scanf() cannot read a null string. .TP .C [ Indicates string data and the normal skip-over-leading-white-space is suppressed. The left bracket is followed by a set of characters, called the .IR scanset , and a right bracket; the input field is the maximal sequence of input characters consisting entirely of characters in the scanset. The circumflex .RC ( ^ ), when it appears as the first character in the scanset, serves as a complement operator and redefines the scanset as the set of all characters .IR not contained in the remainder of the scanset string. Construction of the .I scanset follows certain conventions. A range of characters may be represented by the construct .IR first\-last , enabling [0123456789] to be expressed [0\-9]. Using this convention, .IR first must be lexically less than or equal to .IR last ; otherwise, the dash stands for itself. The dash also stands for itself when it is the first or the last character in the scanset. To include the right square bracket as an element of the scanset, it must appear as the first character (possibly preceded by a circumflex) of the scanset, in which case it will not be interpreted syntactically as the closing bracket. The corresponding argument must point to a character array large enough to hold the data field and the terminating .CR \e0 , which are added automatically. At least one character must match for this conversion to succeed. .TP .C p A sequence of unsigned hexadecimal numbers is expected. This sequence may be produced by the .C p conversion character of .CR printf() . The corresponding argument shall be a pointer to a pointer to .C void into which the value represented by the hexadecimal sequence is stored. The behavior of this conversion is undefined for any input item other than a value converted earlier during the same program execution. .PP The conversion characters .CR d , .CR i , and .C n can be preceded by .CR l , .CR ll or .CR h to indicate that a pointer to a .CR long .CR int , .CR long .CR long .CR int or .CR short .CR int rather than to an .CR int is in the argument list. Similarly, the conversion characters .CR u , .CR o , .CR x , and .CR X can be preceded by .CR l , .CR ll or .CR h to indicate that a pointer to .CR unsigned .CR long .CR int , .CR unsigned .CR long .CR long .CR int , or .CR unsigned .CR short .CR int rather than to an .CR unsigned .CR int , is in the argument list. Finally, the conversion characters .CR e , .CR E , .CR f , .CR g , and .CR G can be preceded by .CR l or .CR L to indicate that a pointer to a .CR double or .CR long .CR double rather than to a .CR float is in the argument list. The .CR l , .CR ll , .CR L or .CR h modifier is ignored for other conversion characters. .PP The .CR scanf() functions terminate their conversions at .SM EOF, at the end of the control string, or when an input character conflicts with the control string. In the latter case, the offending character is left unread in the input stream. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of ordinary characters within format strings as single and/or multi-byte characters. Field width is given in terms of bytes. Characters received from the input stream are interpreted as single- or multi-byte characters as determined by the .CR LC_TYPE category and the field width is decremented by the length of the character. .PP The .CR LC_NUMERIC category determines the radix character expected within floating-point numbers. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUES If the input ends before the first conflict or conversion, .SM EOF is returned. Otherwise, these functions return the number of successfully assigned input items. This number is a short count, or even zero if a conflict ensues between an input character and the control string. .SH ERRORS .CR scanf() and .CR fscanf() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP .SM [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP .SM [EIO] The process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RE .PP Additional .CR errno values can be set by the underlying .CR read() function (see .IR read (2)). .SH EXAMPLES The call: .IP .CR "int i, n; float x; char name[50];" .br .ift \f4\s+1n = scanf("%d%f%s", &i, &x, name);\s0\fP .ifn \f3n = scanf("%d%f%s", &i, &x, name);\fP .PP with the input line: .IP .CR "25 54.32E-1 thompson" .PP assigns to .I n the value .CR 3 , to .I i the value .CR 25 , to .I x the value .CR 5.432 , and .I name contains .CR thompson\e0 . Or: .IP .CR "int i; float x; char name[50];" .br .ift \f4\s+1(void) scanf("%2d%f%*d %[0\-9]", &i, &x, name);\s0\fP .ifn \f3(void) scanf("%2d%f%*d %[0\-9]", &i, &x, name);\fP .PP with input: .IP .CR "56789 0123 56a72" .PP assigns .CR 56 to .IR i , .CR 789.0 to .IR x , skips .CR 0123 , and places the string .CR 56\e0 in .IR name . The next call to .CR getchar() (see .IR getc (3S)) returns .CR a . .PP For another example, to create a language-independent date scanning routine, use: .IP .CR "char month[20]; int day, year;" .br .CR "(void) scanf(format, month, &day, &year);" .PP For American usage, .I format would point to a string: .IP .CR "%1$s %2$d %3$d" .PP The input: .IP .CR "July 3 1986" .PP would assign .CR July to .IR month , .CR 3 to .I day and .CR 1986 to .IR year . .PP For German usage, .I format would point to a string: .IP .CR "%2$d %1$s %3$d" .PP The input: .IP 3 Juli 1986 .PP would assign .CR Juli to .IR month , .CR 3 to .I day and .CR 1986 to .IR year . .PP The success of literal matches and suppressed assignments can be determined with the .CR %n conversion specification. Here is an example that checks the success of literal matches: .nf .IP .CR "int i, n1, n2, n3, n4;" .ift .ft 4 .ifn .ft 3 .ps +1 n1 = n2 = n3 = n4 = -1;" scanf( "%nBEGIN%n %d %nEND%n", &n1, &n2, &i, &n3, &n4); if (n2 - n1 == 5) puts( "matched BEGIN"); if (n4 - n3 == 3) puts( "matched END"); .ft .ps .fi .PP Here is an example that checks the success of suppressed assignments: .nf .IP .CR "int i, n1, n2;" .CR "n1 = n2 = -1;" .ift .ft 4 .ifn .ft 3 .ps +1 scanf( "%d %n%*s%n", &i, &n1, &n2); if (n2 > n1) printf( "successful assignment suppression of %d chars\\n", n2 - n1); .ps .ft .SH WARNINGS Trailing white space (including a newline) is left unread unless matched in the control string. .PP Truncation of multi-byte characters may occur if a field width is used with the conversion character. .SH AUTHOR .CR scanf() was developed by AT&T and HP. .SH SEE ALSO getc(3S), setlocale(3C), printf(3S), strtod(3C), strtol(3C). .SH STANDARDS CONFORMANCE .CR scanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fscanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .CR sscanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4scanf()\f1 \- formatted read from \f2standard input\f1 stream file@@@\f3scanf(3S)\f1 .\" index@\f4fscanf()\f1 \- formatted read from named input stream file@@@\f3scanf(3S)\f1 .\" index@\f4sscanf()\f1 \- formatted read from character string@@@\f3scanf(3S)\f1 .\" index@\f4scanf()\f1 \- formatted read from \f2standard input\f1 stream file@@@\f3scanf(3S)\f1 .\" index@\f4fscanf()\f1 \- formatted read from named input stream file@@@\f3scanf(3S)\f1 .\" index@\f4sscanf()\f1 \- formatted read from character string@@@\f3scanf(3S)\f1 .\" index@formatted input conversion, read from stream file or character string@@@\f3scanf(3S)\f1 .\" index@input conversion, formatted read from stream file or character string@@@\f3scanf(3S)\f1 .\" index@formatted read and conversion from stream file or character string@@@\f3scanf(3S)\f1 .\" index@read from stream file or character string with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@stream file or character string, read from with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@file: read from file, stream, or character string with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@character string or stream file, read from with formatted input conversion@@@\f3scanf(3S)\f1 .\" .\" toc@\f3scanf(3S)\f1:\0\0\f4scanf()\fP, \f4fscanf()\fP, \f4sscanf()\f1@@@formatted input conversion, read from stream file .\" toc@\f4fscanf()\fP:\0\0formatted input conversion, read from stream file@@@see \f3scanf(3S)\f1 .\" toc@\f4sscanf()\fP:\0\0formatted input conversion, read from stream file@@@see \f3scanf(3S)\f1 .\" .\" links@scanf.3s fscanf.3s .\" links@scanf.3s sscanf.3s .\" links@scanf.3s nl_scanf.3s .\" links@scanf.3s nl_fscanf.3s .\" links@scanf.3s nl_sscanf.3s .\" $Header: fseek.3s,v 78.1 96/02/12 13:47:11 ssa Exp $ .TA f .TH fseek 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fseek(\|), fseeko(\|), fseek_unlocked(\|), rewind(\|), rewind_unlocked(\|), ftell(\|), ftello(\|), ftell_unlocked(\|) \- reposition a file pointer in a stream .SH SYNOPSIS .C "#include " .PP .C "int\0fseek(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "int\0fseeko(FILE\0*stream,\0off_t\0offset,\0int\0whence);" .PP .C "int\0fseek_unlocked(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "void\0rewind(FILE\0*stream);" .PP .C "void\0rewind_unlocked(FILE\0*stream);" .PP .C "long\0int\0ftell(FILE\0*stream);" .PP .C "off_t\0ftello(FILE\0*stream);" .PP .C "long\0int\0ftell_unlocked(FILE\0*stream);" .SH DESCRIPTION .CR fseek() sets the file-position indicator for .IR stream . The new position, measured in bytes from the beginning of the file, is obtained by adding .I offset to the position specified by .IR whence . The specified position is the beginning of the file for .CR SEEK_SET , the current position for .CR SEEK_CUR , or end-of-file for .CR SEEK_END . .PP .CR fseeko() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR fseek() except that the .IR offset parameter is an .CR off_t instead of a .CR "long int" . All other functional behaviors, returns, and errors are identical to the POSIX .CR fseek() . .PP If the most recent operation, other than .CR ftell() , on the .IR stream is .IR fflush() , the file offset in the underlying open file description is adjusted to reflect the location specified by the .CR fseek() . .PP .CI rewind( stream ) is equivalent to .CR "fseek (stream, 0L, SEEK_SET)" , except that no value is returned. .PP .CR fseek() and .CR rewind() undo any effects of .IR ungetc (3S). .PP After .CR fseek() or .CR rewind() , the next operation on a file opened for update can be either input or output. .CR fseek() clears the .SM EOF indicator for the .IR stream . .CR rewind() does an implicit .CR clearerr() call (see .IR ferror (3S)). .PP .CR ftell() returns the offset of the current byte relative to the beginning of the file associated with the named .IR stream . .PP .CR ftello() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR ftell() except that it returns an .CR off_t instead of a .CR "long int" . All other behaviors, returns, and errors are identical to the POSIX .CR ftell() . .PP .CR fseek_unlocked() , .CR rewind_unlocked() , and .CR ftell_unlocked() are identical to .CR fseek() , .CR rewind() , and .CR ftell() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE .CR fseek() and .CR fseek_unlocked() return zero if they succeed. Otherwise they return \(mi1 and set .CR errno to indicate the error. .PP .CR ftell() and .CR ftell_unlocked() return the current value of the file position indicator for the stream measured in bytes from the beginning of the file. Otherwise, .CR ftell() and .CR ftell_unlocked() return \(mi1 and set .CR errno to indicate the error. .PP .CR rewind() and .CR rewind_unlocked() do not return any value. Therefore, any application that needs to detect errors should clear .CR errno before calling .CR rewind() or .CR rewind_unlocked() . Then, upon completion, if .CR errno is non-zero, it should assume an error has occurred. .SH ERRORS .CR fseek() , .CR fseeko() , .CR fseek_unlocked() , .CR ftell() , .CR ftello() , .CR ftell_unlocked() , .CR rewind() and .CR rewind_unlocked() fail if the .I stream is unbuffered or the buffered data needs to be flushed, or if any of the following conditions are encountered: .RS .TP 15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor and the process would be delayed in the write operation. .TP .SM [EBADF] The underlying file is not open for writing. .TP .SM [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size. See .IR ulimit (2). .TP .SM [EINVAL] The file .IR offset cannot be represented correctly in an object of type .CR long or size .CR off_t in this environment. .TP .SM [EINTR] A signal was caught during the write operation. .TP .SM [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt was made to write to a pipe that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP .SM [ESPIPE] A seek operation was attempted and the file descriptor underlying .I stream is associated with a pipe. .RE .PP .CR fseek() " and " fseek_unlocked() also fail if: .RS .TP 15 .SM [EINVAL] The .I whence argument is invalid, or the file-position indicator would be set to a negative value. .RE .PP Additional .CR errno values may be set by the underlying .CR write() and .CR lseek() functions (see .IR write (2) and .IR lseek (2)). .SH WARNINGS On .SM HP-UX systems, the offset returned by .CR ftell() " or " ftell_unlocked() is measured in bytes and it is permissible to seek to positions relative to that offset. However, when porting to non-\c .SM HP-UX systems, .CR fseek() should be used directly without relying on any offset obtained from .CR ftell() because arithmetic cannot meaningfully be performed on such an offset if it is not measured in bytes on a particular operating system. .PP .CR fseek() , .CR fseek_unlocked() , .CR rewind() , and .CR rewind_unlocked() have no effect on streams that have been opened in append mode (see .IR fopen (3S)). .SH SEE ALSO lseek(2), write(2), ferror(3S), flockfile(3S), fopen(3S), fgetpos(3S), fseeko64(3S), ftello64(3S), ungetc(3S). .SH STANDARDS CONFORMANCE .CR fseek() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ftell() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR rewind() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fseek\f1, \f4rewind\f1, \f4ftell\f1 \- reposition a file pointer in a stream@@@\f3fseek(3S)\f1 .\" index@\f4fseek\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4rewind\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4ftell\f1 \- get offset from beginning-of-file of current byte in stream file@@@\f3fseek(3S)\f1 .\" index@\f1reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1file, stream: reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1get: pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\f1pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\s-1I/O\s+1 operations on a stream file, get or reposition pointer for@@@\f3fseek(3S)\f1 .\" index@\f1operations on a stream file, get or reposition pointer for \s-1I/O\s+1@@@\f3fseek(3S)\f1 .\" index@\f1stream file, get or reposition pointer for \s-1I/O\s+1 operations on a@@@\f3fseek(3S)\f1 .\" .\" index@\f4fseeko\f1 \- set position of next \s-1I/O\s+1 operation on stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4ftello\f1 \- get offset from beginning-of-file of current byte in stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4fseek_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4rewind_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4ftell_unlocked\f1 \- get offset from beginning-of-file of current byte in stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" .\" toc@\f3fseek(3S)\f1:\0\0\f4fseek\f1, \f4fseeko\f1, \f4fseek_unlocked\f1, \f4rewind\f1, \f4rewind_unlocked\f1, \n\f4ftell\f1, \f4ftello\f1, \f4ftell_unlocked\f1@@@reposition a file pointer in a stream .\" toc@\f4rewind\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4rewind_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseeko\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseek_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftello\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" .\" links@fseek.3s fseek_unloc.3s .\" links@fseek.3s rewind.3s .\" links@fseek.3s rewind_unlo.3s .\" links@fseek.3s ftell.3s .\" links@fseek.3s ftell_unloc.3s .\" links@fseek.3s fseeko.3s .\" links@fseek.3s ftello.3s .\" .\" $Header: fgetpos64.3s,v 78.3 96/02/12 17:04:12 ssa Exp $ .TA f .TH fgetpos64 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetpos64(\|), fopen64(\|), freopen64(\|), fseeko64(\|), fsetpos64(\|), fstatvfsdev64(\|), ftello64(\|), ftw64(\|), nftw64(\|), statvfsdev64(\|), tmpfile64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0fgetpos64(FILE\0*stream,\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "FILE\0*fopen64(const\0char\0*pathname,\0const\0char\0*type);" .PP .C "#include " .PP .C "FILE\0*freopen64(const\0char\0*pathname,\0const\0char\0*type,\0FILE\0*stream);" .PP .C "#include " .PP .C "int\0fseeko64(FILE\0*stream,\0off64_t\0*offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0fsetpos64(FILE\0*stream,\0const\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "int\0fstatvfsdev64(int\0filedes,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "off64_t\0ftello64(FILE\0*stream);" .PP .nf .C "#include " .PP .C "int ftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags)," .C " int depth);" .PP .C "#include " .PP .C "int nftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .PP .C "#include " .PP .C "int\0statvfsdev64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "FILE\0*tmpfile64(void);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 22 .C fgetpos64() The .C fgetpos64() function is identical to .C fgetpos() except that .C fgetpos64() returns the position in a .C fpos64_t instead of a .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fopen64() The .C fopen64() function is identical to .C fopen() in 64-bit compile environment. The .C fopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR fopen() . .TP .C freopen64() The .C freopen64() function is identical to .C freopen() in 64-bit compile environment. The .C freopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR freopen() . .TP .C fseeko64() The .C fseeko64() function is identical to .C fseeko() except that .C fseeko64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C fsetpos64() The .C fsetpos64() function is identical to .C fsetpos() except that .C fsetpos64() accepts an .CR fpos64_t for the pos parameter instead of .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fstatvfsdev64() The .C fstatvfsdev64() function is identical to .C fstatvfsdev() except that .C fstatvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C ftello64() The .C ftello64() function is identical to .C ftello() except that .C ftello64() returns the file position in an .C off64_t instead of an .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C ftw64() The .C ftw64() function is identical to .C ftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR ftw64() . All other functional behaviors, returns, and errors are identical. .TP .C nftw64() The .C nftw64() function is identical to .C nftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR nftw64() . All other functional behaviors, returns, and errors are identical. .TP .C statvfsdev64() The .C statvfsdev64() function is identical to .C statvfsdev() except that .C statvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C tmpfile64() The .C tmpfile64() function is identical to .C tmpfile() in the 64-bit compile environment. Both interfaces create a temporary file that is capable of growing beyond 2GB's if desired. All other functional behaviors, returns, and errors are identical. .\" .\" toc@\f4fgetpos64(2)\f1:\0\0\f4fopen64\f1, \f4freopen64\f1, \f4fseeko64\f1, \f4fsetpos64\f1, \f4fstatvfsdev64\f1, \f4ftello64\f1, \f4ftw64\f1, \n\f4nftw64\f1, \f4statvfsdev64\f1, \f4tmpfile64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4fgetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4freopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fseeko64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fsetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fstatvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftello64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4nftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4statvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4tmpfile64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3fgetpos64(2)\f1 .\" .\" links@fgetpos64.3s fopen64.3s .\" links@fgetpos64.3s freopen64.3s .\" links@fgetpos64.3s fseek64.3s .\" links@fgetpos64.3s fsetpos64.3s .\" links@fgetpos64.3s fstatvfs64.3s .\" links@fgetpos64.3s ftello64.3s .\" links@fgetpos64.3s ftw64.3s .\" links@fgetpos64.3s nftw64.3s .\" links@fgetpos64.3s statvfsdev64.3s .\" links@fgetpos64.3s tmpfile64.3s .\" .\" $Header: fseek.3s,v 78.1 96/02/12 13:47:11 ssa Exp $ .TA f .TH fseek 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fseek(\|), fseeko(\|), fseek_unlocked(\|), rewind(\|), rewind_unlocked(\|), ftell(\|), ftello(\|), ftell_unlocked(\|) \- reposition a file pointer in a stream .SH SYNOPSIS .C "#include " .PP .C "int\0fseek(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "int\0fseeko(FILE\0*stream,\0off_t\0offset,\0int\0whence);" .PP .C "int\0fseek_unlocked(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "void\0rewind(FILE\0*stream);" .PP .C "void\0rewind_unlocked(FILE\0*stream);" .PP .C "long\0int\0ftell(FILE\0*stream);" .PP .C "off_t\0ftello(FILE\0*stream);" .PP .C "long\0int\0ftell_unlocked(FILE\0*stream);" .SH DESCRIPTION .CR fseek() sets the file-position indicator for .IR stream . The new position, measured in bytes from the beginning of the file, is obtained by adding .I offset to the position specified by .IR whence . The specified position is the beginning of the file for .CR SEEK_SET , the current position for .CR SEEK_CUR , or end-of-file for .CR SEEK_END . .PP .CR fseeko() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR fseek() except that the .IR offset parameter is an .CR off_t instead of a .CR "long int" . All other functional behaviors, returns, and errors are identical to the POSIX .CR fseek() . .PP If the most recent operation, other than .CR ftell() , on the .IR stream is .IR fflush() , the file offset in the underlying open file description is adjusted to reflect the location specified by the .CR fseek() . .PP .CI rewind( stream ) is equivalent to .CR "fseek (stream, 0L, SEEK_SET)" , except that no value is returned. .PP .CR fseek() and .CR rewind() undo any effects of .IR ungetc (3S). .PP After .CR fseek() or .CR rewind() , the next operation on a file opened for update can be either input or output. .CR fseek() clears the .SM EOF indicator for the .IR stream . .CR rewind() does an implicit .CR clearerr() call (see .IR ferror (3S)). .PP .CR ftell() returns the offset of the current byte relative to the beginning of the file associated with the named .IR stream . .PP .CR ftello() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR ftell() except that it returns an .CR off_t instead of a .CR "long int" . All other behaviors, returns, and errors are identical to the POSIX .CR ftell() . .PP .CR fseek_unlocked() , .CR rewind_unlocked() , and .CR ftell_unlocked() are identical to .CR fseek() , .CR rewind() , and .CR ftell() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE .CR fseek() and .CR fseek_unlocked() return zero if they succeed. Otherwise they return \(mi1 and set .CR errno to indicate the error. .PP .CR ftell() and .CR ftell_unlocked() return the current value of the file position indicator for the stream measured in bytes from the beginning of the file. Otherwise, .CR ftell() and .CR ftell_unlocked() return \(mi1 and set .CR errno to indicate the error. .PP .CR rewind() and .CR rewind_unlocked() do not return any value. Therefore, any application that needs to detect errors should clear .CR errno before calling .CR rewind() or .CR rewind_unlocked() . Then, upon completion, if .CR errno is non-zero, it should assume an error has occurred. .SH ERRORS .CR fseek() , .CR fseeko() , .CR fseek_unlocked() , .CR ftell() , .CR ftello() , .CR ftell_unlocked() , .CR rewind() and .CR rewind_unlocked() fail if the .I stream is unbuffered or the buffered data needs to be flushed, or if any of the following conditions are encountered: .RS .TP 15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor and the process would be delayed in the write operation. .TP .SM [EBADF] The underlying file is not open for writing. .TP .SM [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size. See .IR ulimit (2). .TP .SM [EINVAL] The file .IR offset cannot be represented correctly in an object of type .CR long or size .CR off_t in this environment. .TP .SM [EINTR] A signal was caught during the write operation. .TP .SM [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt was made to write to a pipe that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP .SM [ESPIPE] A seek operation was attempted and the file descriptor underlying .I stream is associated with a pipe. .RE .PP .CR fseek() " and " fseek_unlocked() also fail if: .RS .TP 15 .SM [EINVAL] The .I whence argument is invalid, or the file-position indicator would be set to a negative value. .RE .PP Additional .CR errno values may be set by the underlying .CR write() and .CR lseek() functions (see .IR write (2) and .IR lseek (2)). .SH WARNINGS On .SM HP-UX systems, the offset returned by .CR ftell() " or " ftell_unlocked() is measured in bytes and it is permissible to seek to positions relative to that offset. However, when porting to non-\c .SM HP-UX systems, .CR fseek() should be used directly without relying on any offset obtained from .CR ftell() because arithmetic cannot meaningfully be performed on such an offset if it is not measured in bytes on a particular operating system. .PP .CR fseek() , .CR fseek_unlocked() , .CR rewind() , and .CR rewind_unlocked() have no effect on streams that have been opened in append mode (see .IR fopen (3S)). .SH SEE ALSO lseek(2), write(2), ferror(3S), flockfile(3S), fopen(3S), fgetpos(3S), fseeko64(3S), ftello64(3S), ungetc(3S). .SH STANDARDS CONFORMANCE .CR fseek() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ftell() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR rewind() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fseek\f1, \f4rewind\f1, \f4ftell\f1 \- reposition a file pointer in a stream@@@\f3fseek(3S)\f1 .\" index@\f4fseek\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4rewind\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4ftell\f1 \- get offset from beginning-of-file of current byte in stream file@@@\f3fseek(3S)\f1 .\" index@\f1reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1file, stream: reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1get: pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\f1pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\s-1I/O\s+1 operations on a stream file, get or reposition pointer for@@@\f3fseek(3S)\f1 .\" index@\f1operations on a stream file, get or reposition pointer for \s-1I/O\s+1@@@\f3fseek(3S)\f1 .\" index@\f1stream file, get or reposition pointer for \s-1I/O\s+1 operations on a@@@\f3fseek(3S)\f1 .\" .\" index@\f4fseeko\f1 \- set position of next \s-1I/O\s+1 operation on stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4ftello\f1 \- get offset from beginning-of-file of current byte in stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4fseek_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4rewind_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4ftell_unlocked\f1 \- get offset from beginning-of-file of current byte in stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" .\" toc@\f3fseek(3S)\f1:\0\0\f4fseek\f1, \f4fseeko\f1, \f4fseek_unlocked\f1, \f4rewind\f1, \f4rewind_unlocked\f1, \n\f4ftell\f1, \f4ftello\f1, \f4ftell_unlocked\f1@@@reposition a file pointer in a stream .\" toc@\f4rewind\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4rewind_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseeko\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseek_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftello\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" .\" links@fseek.3s fseek_unloc.3s .\" links@fseek.3s rewind.3s .\" links@fseek.3s rewind_unlo.3s .\" links@fseek.3s ftell.3s .\" links@fseek.3s ftell_unloc.3s .\" links@fseek.3s fseeko.3s .\" links@fseek.3s ftello.3s .\" .\" $Header: fseek.3s,v 78.1 96/02/12 13:47:11 ssa Exp $ .TA f .TH fseek 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fseek(\|), fseeko(\|), fseek_unlocked(\|), rewind(\|), rewind_unlocked(\|), ftell(\|), ftello(\|), ftell_unlocked(\|) \- reposition a file pointer in a stream .SH SYNOPSIS .C "#include " .PP .C "int\0fseek(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "int\0fseeko(FILE\0*stream,\0off_t\0offset,\0int\0whence);" .PP .C "int\0fseek_unlocked(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "void\0rewind(FILE\0*stream);" .PP .C "void\0rewind_unlocked(FILE\0*stream);" .PP .C "long\0int\0ftell(FILE\0*stream);" .PP .C "off_t\0ftello(FILE\0*stream);" .PP .C "long\0int\0ftell_unlocked(FILE\0*stream);" .SH DESCRIPTION .CR fseek() sets the file-position indicator for .IR stream . The new position, measured in bytes from the beginning of the file, is obtained by adding .I offset to the position specified by .IR whence . The specified position is the beginning of the file for .CR SEEK_SET , the current position for .CR SEEK_CUR , or end-of-file for .CR SEEK_END . .PP .CR fseeko() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR fseek() except that the .IR offset parameter is an .CR off_t instead of a .CR "long int" . All other functional behaviors, returns, and errors are identical to the POSIX .CR fseek() . .PP If the most recent operation, other than .CR ftell() , on the .IR stream is .IR fflush() , the file offset in the underlying open file description is adjusted to reflect the location specified by the .CR fseek() . .PP .CI rewind( stream ) is equivalent to .CR "fseek (stream, 0L, SEEK_SET)" , except that no value is returned. .PP .CR fseek() and .CR rewind() undo any effects of .IR ungetc (3S). .PP After .CR fseek() or .CR rewind() , the next operation on a file opened for update can be either input or output. .CR fseek() clears the .SM EOF indicator for the .IR stream . .CR rewind() does an implicit .CR clearerr() call (see .IR ferror (3S)). .PP .CR ftell() returns the offset of the current byte relative to the beginning of the file associated with the named .IR stream . .PP .CR ftello() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR ftell() except that it returns an .CR off_t instead of a .CR "long int" . All other behaviors, returns, and errors are identical to the POSIX .CR ftell() . .PP .CR fseek_unlocked() , .CR rewind_unlocked() , and .CR ftell_unlocked() are identical to .CR fseek() , .CR rewind() , and .CR ftell() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE .CR fseek() and .CR fseek_unlocked() return zero if they succeed. Otherwise they return \(mi1 and set .CR errno to indicate the error. .PP .CR ftell() and .CR ftell_unlocked() return the current value of the file position indicator for the stream measured in bytes from the beginning of the file. Otherwise, .CR ftell() and .CR ftell_unlocked() return \(mi1 and set .CR errno to indicate the error. .PP .CR rewind() and .CR rewind_unlocked() do not return any value. Therefore, any application that needs to detect errors should clear .CR errno before calling .CR rewind() or .CR rewind_unlocked() . Then, upon completion, if .CR errno is non-zero, it should assume an error has occurred. .SH ERRORS .CR fseek() , .CR fseeko() , .CR fseek_unlocked() , .CR ftell() , .CR ftello() , .CR ftell_unlocked() , .CR rewind() and .CR rewind_unlocked() fail if the .I stream is unbuffered or the buffered data needs to be flushed, or if any of the following conditions are encountered: .RS .TP 15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor and the process would be delayed in the write operation. .TP .SM [EBADF] The underlying file is not open for writing. .TP .SM [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size. See .IR ulimit (2). .TP .SM [EINVAL] The file .IR offset cannot be represented correctly in an object of type .CR long or size .CR off_t in this environment. .TP .SM [EINTR] A signal was caught during the write operation. .TP .SM [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt was made to write to a pipe that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP .SM [ESPIPE] A seek operation was attempted and the file descriptor underlying .I stream is associated with a pipe. .RE .PP .CR fseek() " and " fseek_unlocked() also fail if: .RS .TP 15 .SM [EINVAL] The .I whence argument is invalid, or the file-position indicator would be set to a negative value. .RE .PP Additional .CR errno values may be set by the underlying .CR write() and .CR lseek() functions (see .IR write (2) and .IR lseek (2)). .SH WARNINGS On .SM HP-UX systems, the offset returned by .CR ftell() " or " ftell_unlocked() is measured in bytes and it is permissible to seek to positions relative to that offset. However, when porting to non-\c .SM HP-UX systems, .CR fseek() should be used directly without relying on any offset obtained from .CR ftell() because arithmetic cannot meaningfully be performed on such an offset if it is not measured in bytes on a particular operating system. .PP .CR fseek() , .CR fseek_unlocked() , .CR rewind() , and .CR rewind_unlocked() have no effect on streams that have been opened in append mode (see .IR fopen (3S)). .SH SEE ALSO lseek(2), write(2), ferror(3S), flockfile(3S), fopen(3S), fgetpos(3S), fseeko64(3S), ftello64(3S), ungetc(3S). .SH STANDARDS CONFORMANCE .CR fseek() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ftell() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR rewind() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fseek\f1, \f4rewind\f1, \f4ftell\f1 \- reposition a file pointer in a stream@@@\f3fseek(3S)\f1 .\" index@\f4fseek\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4rewind\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4ftell\f1 \- get offset from beginning-of-file of current byte in stream file@@@\f3fseek(3S)\f1 .\" index@\f1reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1file, stream: reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1get: pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\f1pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\s-1I/O\s+1 operations on a stream file, get or reposition pointer for@@@\f3fseek(3S)\f1 .\" index@\f1operations on a stream file, get or reposition pointer for \s-1I/O\s+1@@@\f3fseek(3S)\f1 .\" index@\f1stream file, get or reposition pointer for \s-1I/O\s+1 operations on a@@@\f3fseek(3S)\f1 .\" .\" index@\f4fseeko\f1 \- set position of next \s-1I/O\s+1 operation on stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4ftello\f1 \- get offset from beginning-of-file of current byte in stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4fseek_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4rewind_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4ftell_unlocked\f1 \- get offset from beginning-of-file of current byte in stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" .\" toc@\f3fseek(3S)\f1:\0\0\f4fseek\f1, \f4fseeko\f1, \f4fseek_unlocked\f1, \f4rewind\f1, \f4rewind_unlocked\f1, \n\f4ftell\f1, \f4ftello\f1, \f4ftell_unlocked\f1@@@reposition a file pointer in a stream .\" toc@\f4rewind\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4rewind_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseeko\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseek_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftello\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" .\" links@fseek.3s fseek_unloc.3s .\" links@fseek.3s rewind.3s .\" links@fseek.3s rewind_unlo.3s .\" links@fseek.3s ftell.3s .\" links@fseek.3s ftell_unloc.3s .\" links@fseek.3s fseeko.3s .\" links@fseek.3s ftello.3s .\" .\" $Header: setaclentry.3c,v 78.1 95/12/20 11:11:07 ssa Exp $ .TA s .TH setaclentry 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setaclentry(\|), fsetaclentry(\|) \- add, modify, or delete one entry in file's access control list (ACL) .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "int setaclentry(const char *path, uid_t uid, gid_t gid, int mode);" .PP .C "int fsetaclentry(int fd, uid_t uid, gid_t gid, int mode);" .SH DESCRIPTION Both forms of this call add, modify, or delete one entry in a file's access control list .SM (ACL). .C setaclentry() and .C fsetaclentry() take a path name .RI ( path ) or open file descriptor .RI ( fd ) and an entry identifier .RI ( uid , .IR gid ). They change the indicated entry's access mode bits to the given value .RI ( mode ), meanings of which are defined in .RC < unistd.h >. .I modes are represented as .CR R_OK , .CR W_OK , and .CR X_OK . Irrelevant bits in .I mode values must be zero. .PP If the file's .SM ACL does not have an entry for the given .I uid and .IR gid , the entry is created and added to the .SM ACL. If .I mode is .C MODE_DEL (defined in .RC < acllib.h >), the matching entry is deleted from the file's .SM ACL if it is an optional entry, or its mode bits are set to zero (no access) if it is a base entry. .PP .I uid or .I gid can be .C ACL_NSUSER or .C ACL_NSGROUP (defined in .RC < sys/acl.h >), respectively, to represent non-specific entries .IC u .% , .CI %. g, or .C %.% . The file's .IC u .% or .CI %. g base entries can be referred to using .C ACL_FILEOWNER or .C ACL_FILEGROUP (defined in .RC < acllib.h >), for the file's owner or group .SM ID, respectively. .PP .C setaclentry() and .C fsetaclentry() read the file's .SM ACL with .C getacl() or .C fgetacl() and modify it with .C setacl() or .CR fsetacl() , respectively. .SH RETURN VALUE If successful, .C setaclentry() and .C fsetaclentry() return zero. .SH ERRORS If an error occurs, .C setaclentry() and .C fsetaclentry() return the following negative values and set .CR errno : .TP \(mi1 Unable to perform .C getacl() or .C fgetacl() on the file. .C errno indicates the cause. .TP \-2 Unable to perform .C stat() or .C fstat() on the file. .C errno indicates the cause. .TP \-3 Cannot add a new entry because the .SM ACL already has .C NACLENTRIES (defined in .RC < sys/acl.h >) entries. .TP \-4 Cannot delete a nonexisting entry. .TP \-5 Unable to perform .C setacl() or .C fsetacl() on the file. .C errno indicates the cause. .SH EXAMPLES The following code fragment adds an entry to file ``work/list'' for user .SM ID 115, group .SM ID 32, or modifies the existing entry for that user and group, if any, with a new access mode of read only. It also changes the owner base entry to have all access rights, and deletes the entry, if any, for any user in group 109. .nf .IP .C "#include " .C "#include " .IP .ift \f4\s+1char \(**filename = "work/list";\fP\s0 .ifn \f3char \(**filename = "work/list";\fP .IP .C "setaclentry\0(filename, 115, 32, R_OK);" .C "setaclentry\0(filename,\0ACL_FILEOWNER,\0ACL_NSGROUP,\0R_OK | W_OK | X_OK);" .C "setaclentry\0(filename,\0ACL_NSUSER, 109, MODE_DEL);\f1" .fi .SH DEPENDENCIES .TP 5 .SM NFS .C setaclentry() and .C fsetaclentry() are not supported on remote files. .SH AUTHOR .C setaclentry() and .C fsetaclentry() were developed by HP. .SH SEE ALSO getacl(2), setacl(2), stat(2), acltostr(3C), cpacl(3C), chownacl(3C), strtoacl(3C), acl(5). .\" .\" index@\f4setaclentry()\fP \- add, modify, or delete access control list entry@@@\f3setaclentry(3C)\f1 .\" index@\f4fsetaclentry()\fP \- add, modify, or delete access control list entry@@@\f3setaclentry(3C)\f1 .\" index@add, modify, or delete access control list entry@@@\f3setaclentry(3C)\f1 .\" index@modify, add, or delete access control list entry@@@\f3setaclentry(3C)\f1 .\" index@delete, add, or modify delete access control list entry@@@\f3setaclentry(3C)\f1 .\" index@access control list; add, modify, or delete entry@@@\f3setaclentry(3C)\f1 .\" toc@\f3setaclentry(3C)\f1:\0\0\f4setaclentry()\fP, \f4fsetaclentry()\fP@@@add, modify, or delete access control list entry .\" toc@\f4fsetaclentry()\fP: add, modify, or delete access control list entry@@@see \f3setaclentry(3C)\f1 .\" links@setaclentry.3c fsetaclentr.3c .\" .\" fileset_database@setaclentry.3c PROGRAMING-MAN .\" $Header: fgetpos.3s,v 78.1 96/02/12 13:44:18 ssa Exp $ .TA f .TH fgetpos 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetpos(\|), fsetpos(\|) \- save and restore a file position indicator for a stream .SH SYNOPSIS .C "#include " .PP .C "int fgetpos(FILE *stream, fpos_t *pos);" .PP .C "int fsetpos(FILE *stream, const fpos_t *pos);" .SH DESCRIPTION .TP 15 .C fgetpos() Store the current value of the file position indicator for the stream pointed to by .IR stream in the object pointed to by .IR pos . The value stored contains information usable by .C fsetpos() for repositioning the stream to its position at the time of the call to .CR fgetpos() . .TP .C fsetpos() Set the file position indicator for the stream pointed to by .IR stream according to the value of the object pointed to by .IR pos, which must be a value set by an earlier call to .C fgetpos() on the same stream. .IP A successful call to .C fsetpos() clears the end-of-file indicator for the stream and undoes any effects of .IR ungetc (3S) on the same stream. After a .C fsetpos() call, the next operation on a update stream can be either input or output. .SH RETURN VALUE If successful, these functions return zero; otherwise non-zero. .SH ERRORS If .CR fgetpos() fails, .CR errno is set to one of the following values. .ER .TP 15 [EINVAL] The current value of the file position cannot be represented correctly in an object of size .CR fpos_t in this environment. .PP Additional .CR errno values may be set by the underlying .CR ftell() function (see .IR ftell (3S)). .SH WARNINGS Failure can occur if these functions are used on a file that has not been opened via .CR fopen() . In particular, they must not be used on a terminal or on a file opened via .IR popen (3S). .PP .C fsetpos() has no effect on streams that are open for append (see .IR fopen (3S)). .SH SEE ALSO fgetpos64(3S), fseek(3S), fsetpos64(3S), fopen(3S), popen(3S), ungetc(3S). .SH STANDARDS CONFORMANCE .CR fgetpos() ": AES, SVID3, XPG4, ANSI C" .PP .CR fsetpos() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4fgetpos()\fP \- save file position indicator for a stream@@@\f3fgetpos(3S)\f1 .\" index@\f4fsetpos()\fP \- restore file position indicator for a stream@@@\f3fgetpos(3S)\f1 .\" index@restore or save file position indicator for a stream@@@\f3fgetpos(3S)\f1 .\" index@save or restore file position indicator for a stream@@@\f3fgetpos(3S)\f1 .\" index@stream, save or restore file position indicator for a@@@\f3fgetpos(3S)\f1 .\" index@file position indicator for a stream, save or restore@@@\f3fgetpos(3S)\f1 .\" .\" toc@\f3fgetpos(3S)\f1:\0\0\f4fgetpos()\fP, \f4fsetpos()\fP@@@save or restore file position indicator for a stream .\" toc@\f4fsetpos()\fP \- restore file position indicator for a stream@@@see \f3fgetpos(3S)\f1 .\" .\" links@fgetpos.3s fsetpos.3s .\" .\" $Header: fgetpos64.3s,v 78.3 96/02/12 17:04:12 ssa Exp $ .TA f .TH fgetpos64 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetpos64(\|), fopen64(\|), freopen64(\|), fseeko64(\|), fsetpos64(\|), fstatvfsdev64(\|), ftello64(\|), ftw64(\|), nftw64(\|), statvfsdev64(\|), tmpfile64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0fgetpos64(FILE\0*stream,\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "FILE\0*fopen64(const\0char\0*pathname,\0const\0char\0*type);" .PP .C "#include " .PP .C "FILE\0*freopen64(const\0char\0*pathname,\0const\0char\0*type,\0FILE\0*stream);" .PP .C "#include " .PP .C "int\0fseeko64(FILE\0*stream,\0off64_t\0*offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0fsetpos64(FILE\0*stream,\0const\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "int\0fstatvfsdev64(int\0filedes,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "off64_t\0ftello64(FILE\0*stream);" .PP .nf .C "#include " .PP .C "int ftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags)," .C " int depth);" .PP .C "#include " .PP .C "int nftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .PP .C "#include " .PP .C "int\0statvfsdev64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "FILE\0*tmpfile64(void);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 22 .C fgetpos64() The .C fgetpos64() function is identical to .C fgetpos() except that .C fgetpos64() returns the position in a .C fpos64_t instead of a .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fopen64() The .C fopen64() function is identical to .C fopen() in 64-bit compile environment. The .C fopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR fopen() . .TP .C freopen64() The .C freopen64() function is identical to .C freopen() in 64-bit compile environment. The .C freopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR freopen() . .TP .C fseeko64() The .C fseeko64() function is identical to .C fseeko() except that .C fseeko64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C fsetpos64() The .C fsetpos64() function is identical to .C fsetpos() except that .C fsetpos64() accepts an .CR fpos64_t for the pos parameter instead of .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fstatvfsdev64() The .C fstatvfsdev64() function is identical to .C fstatvfsdev() except that .C fstatvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C ftello64() The .C ftello64() function is identical to .C ftello() except that .C ftello64() returns the file position in an .C off64_t instead of an .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C ftw64() The .C ftw64() function is identical to .C ftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR ftw64() . All other functional behaviors, returns, and errors are identical. .TP .C nftw64() The .C nftw64() function is identical to .C nftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR nftw64() . All other functional behaviors, returns, and errors are identical. .TP .C statvfsdev64() The .C statvfsdev64() function is identical to .C statvfsdev() except that .C statvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C tmpfile64() The .C tmpfile64() function is identical to .C tmpfile() in the 64-bit compile environment. Both interfaces create a temporary file that is capable of growing beyond 2GB's if desired. All other functional behaviors, returns, and errors are identical. .\" .\" toc@\f4fgetpos64(2)\f1:\0\0\f4fopen64\f1, \f4freopen64\f1, \f4fseeko64\f1, \f4fsetpos64\f1, \f4fstatvfsdev64\f1, \f4ftello64\f1, \f4ftw64\f1, \n\f4nftw64\f1, \f4statvfsdev64\f1, \f4tmpfile64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4fgetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4freopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fseeko64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fsetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fstatvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftello64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4nftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4statvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4tmpfile64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3fgetpos64(2)\f1 .\" .\" links@fgetpos64.3s fopen64.3s .\" links@fgetpos64.3s freopen64.3s .\" links@fgetpos64.3s fseek64.3s .\" links@fgetpos64.3s fsetpos64.3s .\" links@fgetpos64.3s fstatvfs64.3s .\" links@fgetpos64.3s ftello64.3s .\" links@fgetpos64.3s ftw64.3s .\" links@fgetpos64.3s nftw64.3s .\" links@fgetpos64.3s statvfsdev64.3s .\" links@fgetpos64.3s tmpfile64.3s .\" .\" $Header: statfsdev.3c,v 72.4 93/01/14 14:50:13 ssa Exp $ .TA s .TH statfsdev 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME statfsdev, fstatfsdev \- get file system statistics .SH SYNOPSIS .C "#include " .PP .C "int statfsdev(const char *path, struct statfs *buf);" .PP .C "int fstatfsdev(int fildes, struct statfs *buf);" .SH DESCRIPTION .C statfsdev() returns information about the file system on the file specified by .I path. .PP .I buf is a pointer to a .C statfs structure into which information is placed concerning the file system. The contents of the structure pointed to by .I buf include the following members: .nf .IP .C "long f_bavail /* free blocks available to non-superuser */" .C "long f_bfree /* free blocks */" .C "long f_blocks /* total blocks in file system */" .C "long f_bsize /* fundamental file system block size in bytes */" .C "long f_ffree /* free file nodes in file system */" .C "long f_files /* total file nodes in file system */" .C "long f_type /* type of info, zero for now */" .C "fsid_t f_fsid /* file system ID. f_fsid[1] is MOUNT_UFS," .C " MOUNT_NFS, or MOUNT_CDFS */" .fi .PP Fields that are undefined for a particular file system are set to \(mi1 . .PP .C fstatfsdev() returns the same information as above, but about the open file referred to by file descriptor .IR fildes . .SH RETURN VALUE Upon successful completion, .C statfsdev() and .C fstatfsdev() return zero. Otherwise, they return \-1 and set the global variable .C errno to indicate the error. .SH ERRORS .C statfsdev() fails if one or more of the following conditions are encountered: .RS .TP 15 .SM [EACCES] Search permission is denied for a component of the path prefix. .TP .SM [EAGAIN] The file exists, enforcement mode file/record locking is set, and there are outstanding record locks on the file. .TP .SM [EFAULT] .I path points to an invalid address. .TP .SM [ELOOP] Too many symbolic links are encountered in translating the path name. .TP .SM [EMFILE] The maximum number of file descriptors allowed are currently open. .TP .SM [ENAMETOOLONG] The length of the specified path name exceeds .C PATH_MAX bytes, or the length of a component of the path name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] The system file table is full. .TP .SM [ENOENT] The named file does not exist. .TP .SM [ENOTDIR] A component of the path prefix is not a directory. .TP .SM [ENXIO] The device specified by the named special file does not exist. .RE .PP .C fstatfsdev() fails if one or more of the following is true: .RS .TP 15 .SM [EBADF] .I fildes is not a valid open file descriptor. .TP 15 .SM [ESPIPE] .I filedes points to an invalid address. .RE .PP Both .C fstatfsdev() and .C statfsdev() fail if one or more of the following is true: .RS .TP 15 .SM [EAGAIN] Enforcement-mode record locking was set, and there was a blocking write lock. .TP .SM [EDEADLK] A resource deadlock would occur as a result of this operation. .TP .SM [EINTR] A system call was interrupted by a signal. .TP .SM [EINVAL] The file specified by .I path or .I filedes does not contain a file system of any known type. .TP .SM [ENOLCK] The system lock table was full, so the read could not go to sleep until the blocking write lock was removed. .SH AUTHOR .C statfsdev() and .C fstatfsdev() were developed by HP. .RE .SH FILES .C /usr/include/sys/mount.h .SH SEE ALSO bdf(1M), df(1M), stat(2), statfs(2). .\" .\" index@\f4statfsdev()\fP, \f4fstatfsdev()\fP \- get file system statistics@@@\f3statfsdev(3C)\f1 .\" index@\f4fstatfsdev()\fP, \f4statfsdev()\fP \- get file system statistics@@@\f3statfsdev(3C)\f1 .\" index@get file system statistics@@@\f3statfsdev(3C)\f1 .\" index@file system statistics, get@@@\f3statfsdev(3C)\f1 .\" index@statistics, get file system@@@\f3statfsdev(3C)\f1 .\" .\" toc@\f3statfsdev(3C)\f1:\0\0\f4statfsdev()\fP, \f4fstatfsdev()\fP@@@get file system statistics .\" toc@\f4fstatfsdev()\fP: get file system statistics@@@see \f3statfsdev(3C)\f1 .\" .\" links@statfsdev.3c fstatfsdev.3c .\" .\" fileset_database@statfsdev.3c PROGRAMING-MAN .\" $Header: fgetpos64.3s,v 78.3 96/02/12 17:04:12 ssa Exp $ .TA f .TH fgetpos64 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetpos64(\|), fopen64(\|), freopen64(\|), fseeko64(\|), fsetpos64(\|), fstatvfsdev64(\|), ftello64(\|), ftw64(\|), nftw64(\|), statvfsdev64(\|), tmpfile64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0fgetpos64(FILE\0*stream,\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "FILE\0*fopen64(const\0char\0*pathname,\0const\0char\0*type);" .PP .C "#include " .PP .C "FILE\0*freopen64(const\0char\0*pathname,\0const\0char\0*type,\0FILE\0*stream);" .PP .C "#include " .PP .C "int\0fseeko64(FILE\0*stream,\0off64_t\0*offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0fsetpos64(FILE\0*stream,\0const\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "int\0fstatvfsdev64(int\0filedes,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "off64_t\0ftello64(FILE\0*stream);" .PP .nf .C "#include " .PP .C "int ftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags)," .C " int depth);" .PP .C "#include " .PP .C "int nftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .PP .C "#include " .PP .C "int\0statvfsdev64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "FILE\0*tmpfile64(void);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 22 .C fgetpos64() The .C fgetpos64() function is identical to .C fgetpos() except that .C fgetpos64() returns the position in a .C fpos64_t instead of a .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fopen64() The .C fopen64() function is identical to .C fopen() in 64-bit compile environment. The .C fopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR fopen() . .TP .C freopen64() The .C freopen64() function is identical to .C freopen() in 64-bit compile environment. The .C freopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR freopen() . .TP .C fseeko64() The .C fseeko64() function is identical to .C fseeko() except that .C fseeko64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C fsetpos64() The .C fsetpos64() function is identical to .C fsetpos() except that .C fsetpos64() accepts an .CR fpos64_t for the pos parameter instead of .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fstatvfsdev64() The .C fstatvfsdev64() function is identical to .C fstatvfsdev() except that .C fstatvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C ftello64() The .C ftello64() function is identical to .C ftello() except that .C ftello64() returns the file position in an .C off64_t instead of an .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C ftw64() The .C ftw64() function is identical to .C ftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR ftw64() . All other functional behaviors, returns, and errors are identical. .TP .C nftw64() The .C nftw64() function is identical to .C nftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR nftw64() . All other functional behaviors, returns, and errors are identical. .TP .C statvfsdev64() The .C statvfsdev64() function is identical to .C statvfsdev() except that .C statvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C tmpfile64() The .C tmpfile64() function is identical to .C tmpfile() in the 64-bit compile environment. Both interfaces create a temporary file that is capable of growing beyond 2GB's if desired. All other functional behaviors, returns, and errors are identical. .\" .\" toc@\f4fgetpos64(2)\f1:\0\0\f4fopen64\f1, \f4freopen64\f1, \f4fseeko64\f1, \f4fsetpos64\f1, \f4fstatvfsdev64\f1, \f4ftello64\f1, \f4ftw64\f1, \n\f4nftw64\f1, \f4statvfsdev64\f1, \f4tmpfile64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4fgetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4freopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fseeko64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fsetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fstatvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftello64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4nftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4statvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4tmpfile64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3fgetpos64(2)\f1 .\" .\" links@fgetpos64.3s fopen64.3s .\" links@fgetpos64.3s freopen64.3s .\" links@fgetpos64.3s fseek64.3s .\" links@fgetpos64.3s fsetpos64.3s .\" links@fgetpos64.3s fstatvfs64.3s .\" links@fgetpos64.3s ftello64.3s .\" links@fgetpos64.3s ftw64.3s .\" links@fgetpos64.3s nftw64.3s .\" links@fgetpos64.3s statvfsdev64.3s .\" links@fgetpos64.3s tmpfile64.3s .\" .\" $Header: statvfsdev.3c,v 78.1 96/02/12 14:19:48 ssa Exp $ .TA s .TH statvfsdev 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME statvfsdev, fstatvfsdev \- get file system information .SH SYNOPSIS .C "#include " .PP .C "int statvfsdev(const char *path, struct statvfs *buf);" .PP .C "int fstatvfsdev(int fildes, struct statvfs *buf);" .SH DESCRIPTION .C statvfsdev() returns information about the file system on the device file specified by .I path. The file system need not be mounted. .PP .C fstatvfsdev() returns similar information for an open file. .PP The parameters for the .CR stat() , .CR fstat() , and .C lstat() functions are as follows: .RS .TP 20 .I path is a pointer to a path name of any file within the file system. (All directories listed in the path name must be searchable.) .TP .I buf is a pointer to a .C statvfs() structure, which is where the file status information is stored. .TP .I fildes is a file descriptor for an open file, which is created with the successful completion of an .CR open() , .CR creat() , .CR dup() , .CR fcntl() , or .CR pipe() system call (see .IR open (2), .IR creat (2), .IR dup (2), .IR fcntl (2), or .IR pipe (2)). .RE .PP .I buf is a pointer to a .C statvfs structure into which information is placed concerning the file system. The contents of the structure pointed to by .I buf are described in .IR statvfs (2). .PP .C fstatvfsdev() returns the same information as above, but about the open device file referred to by file descriptor .IR fildes . .SH RETURN VALUE Upon successful completion, .C statvfsdev() and .C fstatvfsdev() return zero. Otherwise, they return \-1 and set the global variable .C errno to indicate the error. .SH ERRORS If .C statvfsdev() fails, .C errno is set to one of the following values: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of the path prefix. .TP .SM [EFAULT] .I path points to an invalid address. .TP .SM [ELOOP] Too many symbolic links are encountered during path-name translation. .TP .SM [EMFILE] The maximum number of file descriptors allowed are currently open. .TP .SM [ENAMETOOLONG] The length of the specified path name exceeds .C PATH_MAX bytes, or the length of a component of the path name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] The system file table is full. .TP .SM [ENOENT] The named file does not exist. .TP .SM [ENOTDIR] A component of the path prefix is not a directory. .TP .SM [ENXIO] The device specified by the named special file does not exist. .RE .PP If .C fstatvfsdev() fails, .C errno is set to one of the following values: .RS .TP 20 .SM [EBADF] .I fildes is not a valid open file descriptor. .TP 20 .SM [ESPIPE] .I filedes is invalid. .RE .PP When both .C fstatvfsdev() and .C statvfsdev() fail, .C errno is set to one of the following values: .RS .TP 20 .SM [EINTR] A system call was interrupted by a signal. .TP .SM [EINVAL] The file specified by .I path or .I filedes does not contain a file system of any known type. .SH AUTHOR .C statvfsdev() and .C fstatvfsdev() were developed by HP. .RE .SH SEE ALSO bdf(1M), df(1M), stat(2), statvfs(2), fstatvfsdev64(3C), statvfsdev64(3C). .\" .\" index@\f4statvfsdev()\f1, \f4fstatvfsdev()\f1 \- get file system statistics@@@\f3statvfsdev(3C)\f1 .\" index@\f4fstatvfsdev()\f1, \f4statvfsdev()\f1 \- get file system statistics@@@\f3statvfsdev(3C)\f1 .\" index@\f1get file system statistics@@@\f3statvfsdev(3C)\f1 .\" index@\f1file system statistics, get@@@\f3statvfsdev(3C)\f1 .\" index@\f1statistics, get file system@@@\f3statvfsdev(3C)\f1 .\" .\" toc@\f3statvfsdev(3C)\f1:\0\0\f4statvfsdev()\f1, \f4fstatvfsdev()\f1@@@get file system statistics .\" toc@\f4fstatvfsdev()\f1:\0\0get file system statistics@@@see \f3statvfsdev(3C)\f1 .\" .\" links@statvfsdev.3c fstatvfsdev.3c .\" $Header: fseek.3s,v 78.1 96/02/12 13:47:11 ssa Exp $ .TA f .TH fseek 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fseek(\|), fseeko(\|), fseek_unlocked(\|), rewind(\|), rewind_unlocked(\|), ftell(\|), ftello(\|), ftell_unlocked(\|) \- reposition a file pointer in a stream .SH SYNOPSIS .C "#include " .PP .C "int\0fseek(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "int\0fseeko(FILE\0*stream,\0off_t\0offset,\0int\0whence);" .PP .C "int\0fseek_unlocked(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "void\0rewind(FILE\0*stream);" .PP .C "void\0rewind_unlocked(FILE\0*stream);" .PP .C "long\0int\0ftell(FILE\0*stream);" .PP .C "off_t\0ftello(FILE\0*stream);" .PP .C "long\0int\0ftell_unlocked(FILE\0*stream);" .SH DESCRIPTION .CR fseek() sets the file-position indicator for .IR stream . The new position, measured in bytes from the beginning of the file, is obtained by adding .I offset to the position specified by .IR whence . The specified position is the beginning of the file for .CR SEEK_SET , the current position for .CR SEEK_CUR , or end-of-file for .CR SEEK_END . .PP .CR fseeko() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR fseek() except that the .IR offset parameter is an .CR off_t instead of a .CR "long int" . All other functional behaviors, returns, and errors are identical to the POSIX .CR fseek() . .PP If the most recent operation, other than .CR ftell() , on the .IR stream is .IR fflush() , the file offset in the underlying open file description is adjusted to reflect the location specified by the .CR fseek() . .PP .CI rewind( stream ) is equivalent to .CR "fseek (stream, 0L, SEEK_SET)" , except that no value is returned. .PP .CR fseek() and .CR rewind() undo any effects of .IR ungetc (3S). .PP After .CR fseek() or .CR rewind() , the next operation on a file opened for update can be either input or output. .CR fseek() clears the .SM EOF indicator for the .IR stream . .CR rewind() does an implicit .CR clearerr() call (see .IR ferror (3S)). .PP .CR ftell() returns the offset of the current byte relative to the beginning of the file associated with the named .IR stream . .PP .CR ftello() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR ftell() except that it returns an .CR off_t instead of a .CR "long int" . All other behaviors, returns, and errors are identical to the POSIX .CR ftell() . .PP .CR fseek_unlocked() , .CR rewind_unlocked() , and .CR ftell_unlocked() are identical to .CR fseek() , .CR rewind() , and .CR ftell() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE .CR fseek() and .CR fseek_unlocked() return zero if they succeed. Otherwise they return \(mi1 and set .CR errno to indicate the error. .PP .CR ftell() and .CR ftell_unlocked() return the current value of the file position indicator for the stream measured in bytes from the beginning of the file. Otherwise, .CR ftell() and .CR ftell_unlocked() return \(mi1 and set .CR errno to indicate the error. .PP .CR rewind() and .CR rewind_unlocked() do not return any value. Therefore, any application that needs to detect errors should clear .CR errno before calling .CR rewind() or .CR rewind_unlocked() . Then, upon completion, if .CR errno is non-zero, it should assume an error has occurred. .SH ERRORS .CR fseek() , .CR fseeko() , .CR fseek_unlocked() , .CR ftell() , .CR ftello() , .CR ftell_unlocked() , .CR rewind() and .CR rewind_unlocked() fail if the .I stream is unbuffered or the buffered data needs to be flushed, or if any of the following conditions are encountered: .RS .TP 15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor and the process would be delayed in the write operation. .TP .SM [EBADF] The underlying file is not open for writing. .TP .SM [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size. See .IR ulimit (2). .TP .SM [EINVAL] The file .IR offset cannot be represented correctly in an object of type .CR long or size .CR off_t in this environment. .TP .SM [EINTR] A signal was caught during the write operation. .TP .SM [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt was made to write to a pipe that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP .SM [ESPIPE] A seek operation was attempted and the file descriptor underlying .I stream is associated with a pipe. .RE .PP .CR fseek() " and " fseek_unlocked() also fail if: .RS .TP 15 .SM [EINVAL] The .I whence argument is invalid, or the file-position indicator would be set to a negative value. .RE .PP Additional .CR errno values may be set by the underlying .CR write() and .CR lseek() functions (see .IR write (2) and .IR lseek (2)). .SH WARNINGS On .SM HP-UX systems, the offset returned by .CR ftell() " or " ftell_unlocked() is measured in bytes and it is permissible to seek to positions relative to that offset. However, when porting to non-\c .SM HP-UX systems, .CR fseek() should be used directly without relying on any offset obtained from .CR ftell() because arithmetic cannot meaningfully be performed on such an offset if it is not measured in bytes on a particular operating system. .PP .CR fseek() , .CR fseek_unlocked() , .CR rewind() , and .CR rewind_unlocked() have no effect on streams that have been opened in append mode (see .IR fopen (3S)). .SH SEE ALSO lseek(2), write(2), ferror(3S), flockfile(3S), fopen(3S), fgetpos(3S), fseeko64(3S), ftello64(3S), ungetc(3S). .SH STANDARDS CONFORMANCE .CR fseek() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ftell() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR rewind() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fseek\f1, \f4rewind\f1, \f4ftell\f1 \- reposition a file pointer in a stream@@@\f3fseek(3S)\f1 .\" index@\f4fseek\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4rewind\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4ftell\f1 \- get offset from beginning-of-file of current byte in stream file@@@\f3fseek(3S)\f1 .\" index@\f1reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1file, stream: reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1get: pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\f1pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\s-1I/O\s+1 operations on a stream file, get or reposition pointer for@@@\f3fseek(3S)\f1 .\" index@\f1operations on a stream file, get or reposition pointer for \s-1I/O\s+1@@@\f3fseek(3S)\f1 .\" index@\f1stream file, get or reposition pointer for \s-1I/O\s+1 operations on a@@@\f3fseek(3S)\f1 .\" .\" index@\f4fseeko\f1 \- set position of next \s-1I/O\s+1 operation on stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4ftello\f1 \- get offset from beginning-of-file of current byte in stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4fseek_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4rewind_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4ftell_unlocked\f1 \- get offset from beginning-of-file of current byte in stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" .\" toc@\f3fseek(3S)\f1:\0\0\f4fseek\f1, \f4fseeko\f1, \f4fseek_unlocked\f1, \f4rewind\f1, \f4rewind_unlocked\f1, \n\f4ftell\f1, \f4ftello\f1, \f4ftell_unlocked\f1@@@reposition a file pointer in a stream .\" toc@\f4rewind\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4rewind_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseeko\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseek_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftello\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" .\" links@fseek.3s fseek_unloc.3s .\" links@fseek.3s rewind.3s .\" links@fseek.3s rewind_unlo.3s .\" links@fseek.3s ftell.3s .\" links@fseek.3s ftell_unloc.3s .\" links@fseek.3s fseeko.3s .\" links@fseek.3s ftello.3s .\" .\" $Header: fseek.3s,v 78.1 96/02/12 13:47:11 ssa Exp $ .TA f .TH fseek 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fseek(\|), fseeko(\|), fseek_unlocked(\|), rewind(\|), rewind_unlocked(\|), ftell(\|), ftello(\|), ftell_unlocked(\|) \- reposition a file pointer in a stream .SH SYNOPSIS .C "#include " .PP .C "int\0fseek(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "int\0fseeko(FILE\0*stream,\0off_t\0offset,\0int\0whence);" .PP .C "int\0fseek_unlocked(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "void\0rewind(FILE\0*stream);" .PP .C "void\0rewind_unlocked(FILE\0*stream);" .PP .C "long\0int\0ftell(FILE\0*stream);" .PP .C "off_t\0ftello(FILE\0*stream);" .PP .C "long\0int\0ftell_unlocked(FILE\0*stream);" .SH DESCRIPTION .CR fseek() sets the file-position indicator for .IR stream . The new position, measured in bytes from the beginning of the file, is obtained by adding .I offset to the position specified by .IR whence . The specified position is the beginning of the file for .CR SEEK_SET , the current position for .CR SEEK_CUR , or end-of-file for .CR SEEK_END . .PP .CR fseeko() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR fseek() except that the .IR offset parameter is an .CR off_t instead of a .CR "long int" . All other functional behaviors, returns, and errors are identical to the POSIX .CR fseek() . .PP If the most recent operation, other than .CR ftell() , on the .IR stream is .IR fflush() , the file offset in the underlying open file description is adjusted to reflect the location specified by the .CR fseek() . .PP .CI rewind( stream ) is equivalent to .CR "fseek (stream, 0L, SEEK_SET)" , except that no value is returned. .PP .CR fseek() and .CR rewind() undo any effects of .IR ungetc (3S). .PP After .CR fseek() or .CR rewind() , the next operation on a file opened for update can be either input or output. .CR fseek() clears the .SM EOF indicator for the .IR stream . .CR rewind() does an implicit .CR clearerr() call (see .IR ferror (3S)). .PP .CR ftell() returns the offset of the current byte relative to the beginning of the file associated with the named .IR stream . .PP .CR ftello() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR ftell() except that it returns an .CR off_t instead of a .CR "long int" . All other behaviors, returns, and errors are identical to the POSIX .CR ftell() . .PP .CR fseek_unlocked() , .CR rewind_unlocked() , and .CR ftell_unlocked() are identical to .CR fseek() , .CR rewind() , and .CR ftell() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE .CR fseek() and .CR fseek_unlocked() return zero if they succeed. Otherwise they return \(mi1 and set .CR errno to indicate the error. .PP .CR ftell() and .CR ftell_unlocked() return the current value of the file position indicator for the stream measured in bytes from the beginning of the file. Otherwise, .CR ftell() and .CR ftell_unlocked() return \(mi1 and set .CR errno to indicate the error. .PP .CR rewind() and .CR rewind_unlocked() do not return any value. Therefore, any application that needs to detect errors should clear .CR errno before calling .CR rewind() or .CR rewind_unlocked() . Then, upon completion, if .CR errno is non-zero, it should assume an error has occurred. .SH ERRORS .CR fseek() , .CR fseeko() , .CR fseek_unlocked() , .CR ftell() , .CR ftello() , .CR ftell_unlocked() , .CR rewind() and .CR rewind_unlocked() fail if the .I stream is unbuffered or the buffered data needs to be flushed, or if any of the following conditions are encountered: .RS .TP 15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor and the process would be delayed in the write operation. .TP .SM [EBADF] The underlying file is not open for writing. .TP .SM [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size. See .IR ulimit (2). .TP .SM [EINVAL] The file .IR offset cannot be represented correctly in an object of type .CR long or size .CR off_t in this environment. .TP .SM [EINTR] A signal was caught during the write operation. .TP .SM [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt was made to write to a pipe that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP .SM [ESPIPE] A seek operation was attempted and the file descriptor underlying .I stream is associated with a pipe. .RE .PP .CR fseek() " and " fseek_unlocked() also fail if: .RS .TP 15 .SM [EINVAL] The .I whence argument is invalid, or the file-position indicator would be set to a negative value. .RE .PP Additional .CR errno values may be set by the underlying .CR write() and .CR lseek() functions (see .IR write (2) and .IR lseek (2)). .SH WARNINGS On .SM HP-UX systems, the offset returned by .CR ftell() " or " ftell_unlocked() is measured in bytes and it is permissible to seek to positions relative to that offset. However, when porting to non-\c .SM HP-UX systems, .CR fseek() should be used directly without relying on any offset obtained from .CR ftell() because arithmetic cannot meaningfully be performed on such an offset if it is not measured in bytes on a particular operating system. .PP .CR fseek() , .CR fseek_unlocked() , .CR rewind() , and .CR rewind_unlocked() have no effect on streams that have been opened in append mode (see .IR fopen (3S)). .SH SEE ALSO lseek(2), write(2), ferror(3S), flockfile(3S), fopen(3S), fgetpos(3S), fseeko64(3S), ftello64(3S), ungetc(3S). .SH STANDARDS CONFORMANCE .CR fseek() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ftell() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR rewind() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fseek\f1, \f4rewind\f1, \f4ftell\f1 \- reposition a file pointer in a stream@@@\f3fseek(3S)\f1 .\" index@\f4fseek\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4rewind\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4ftell\f1 \- get offset from beginning-of-file of current byte in stream file@@@\f3fseek(3S)\f1 .\" index@\f1reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1file, stream: reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1get: pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\f1pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\s-1I/O\s+1 operations on a stream file, get or reposition pointer for@@@\f3fseek(3S)\f1 .\" index@\f1operations on a stream file, get or reposition pointer for \s-1I/O\s+1@@@\f3fseek(3S)\f1 .\" index@\f1stream file, get or reposition pointer for \s-1I/O\s+1 operations on a@@@\f3fseek(3S)\f1 .\" .\" index@\f4fseeko\f1 \- set position of next \s-1I/O\s+1 operation on stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4ftello\f1 \- get offset from beginning-of-file of current byte in stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4fseek_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4rewind_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4ftell_unlocked\f1 \- get offset from beginning-of-file of current byte in stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" .\" toc@\f3fseek(3S)\f1:\0\0\f4fseek\f1, \f4fseeko\f1, \f4fseek_unlocked\f1, \f4rewind\f1, \f4rewind_unlocked\f1, \n\f4ftell\f1, \f4ftello\f1, \f4ftell_unlocked\f1@@@reposition a file pointer in a stream .\" toc@\f4rewind\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4rewind_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseeko\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseek_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftello\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" .\" links@fseek.3s fseek_unloc.3s .\" links@fseek.3s rewind.3s .\" links@fseek.3s rewind_unlo.3s .\" links@fseek.3s ftell.3s .\" links@fseek.3s ftell_unloc.3s .\" links@fseek.3s fseeko.3s .\" links@fseek.3s ftello.3s .\" .\" $Header: fseek.3s,v 78.1 96/02/12 13:47:11 ssa Exp $ .TA f .TH fseek 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fseek(\|), fseeko(\|), fseek_unlocked(\|), rewind(\|), rewind_unlocked(\|), ftell(\|), ftello(\|), ftell_unlocked(\|) \- reposition a file pointer in a stream .SH SYNOPSIS .C "#include " .PP .C "int\0fseek(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "int\0fseeko(FILE\0*stream,\0off_t\0offset,\0int\0whence);" .PP .C "int\0fseek_unlocked(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "void\0rewind(FILE\0*stream);" .PP .C "void\0rewind_unlocked(FILE\0*stream);" .PP .C "long\0int\0ftell(FILE\0*stream);" .PP .C "off_t\0ftello(FILE\0*stream);" .PP .C "long\0int\0ftell_unlocked(FILE\0*stream);" .SH DESCRIPTION .CR fseek() sets the file-position indicator for .IR stream . The new position, measured in bytes from the beginning of the file, is obtained by adding .I offset to the position specified by .IR whence . The specified position is the beginning of the file for .CR SEEK_SET , the current position for .CR SEEK_CUR , or end-of-file for .CR SEEK_END . .PP .CR fseeko() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR fseek() except that the .IR offset parameter is an .CR off_t instead of a .CR "long int" . All other functional behaviors, returns, and errors are identical to the POSIX .CR fseek() . .PP If the most recent operation, other than .CR ftell() , on the .IR stream is .IR fflush() , the file offset in the underlying open file description is adjusted to reflect the location specified by the .CR fseek() . .PP .CI rewind( stream ) is equivalent to .CR "fseek (stream, 0L, SEEK_SET)" , except that no value is returned. .PP .CR fseek() and .CR rewind() undo any effects of .IR ungetc (3S). .PP After .CR fseek() or .CR rewind() , the next operation on a file opened for update can be either input or output. .CR fseek() clears the .SM EOF indicator for the .IR stream . .CR rewind() does an implicit .CR clearerr() call (see .IR ferror (3S)). .PP .CR ftell() returns the offset of the current byte relative to the beginning of the file associated with the named .IR stream . .PP .CR ftello() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR ftell() except that it returns an .CR off_t instead of a .CR "long int" . All other behaviors, returns, and errors are identical to the POSIX .CR ftell() . .PP .CR fseek_unlocked() , .CR rewind_unlocked() , and .CR ftell_unlocked() are identical to .CR fseek() , .CR rewind() , and .CR ftell() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE .CR fseek() and .CR fseek_unlocked() return zero if they succeed. Otherwise they return \(mi1 and set .CR errno to indicate the error. .PP .CR ftell() and .CR ftell_unlocked() return the current value of the file position indicator for the stream measured in bytes from the beginning of the file. Otherwise, .CR ftell() and .CR ftell_unlocked() return \(mi1 and set .CR errno to indicate the error. .PP .CR rewind() and .CR rewind_unlocked() do not return any value. Therefore, any application that needs to detect errors should clear .CR errno before calling .CR rewind() or .CR rewind_unlocked() . Then, upon completion, if .CR errno is non-zero, it should assume an error has occurred. .SH ERRORS .CR fseek() , .CR fseeko() , .CR fseek_unlocked() , .CR ftell() , .CR ftello() , .CR ftell_unlocked() , .CR rewind() and .CR rewind_unlocked() fail if the .I stream is unbuffered or the buffered data needs to be flushed, or if any of the following conditions are encountered: .RS .TP 15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor and the process would be delayed in the write operation. .TP .SM [EBADF] The underlying file is not open for writing. .TP .SM [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size. See .IR ulimit (2). .TP .SM [EINVAL] The file .IR offset cannot be represented correctly in an object of type .CR long or size .CR off_t in this environment. .TP .SM [EINTR] A signal was caught during the write operation. .TP .SM [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt was made to write to a pipe that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP .SM [ESPIPE] A seek operation was attempted and the file descriptor underlying .I stream is associated with a pipe. .RE .PP .CR fseek() " and " fseek_unlocked() also fail if: .RS .TP 15 .SM [EINVAL] The .I whence argument is invalid, or the file-position indicator would be set to a negative value. .RE .PP Additional .CR errno values may be set by the underlying .CR write() and .CR lseek() functions (see .IR write (2) and .IR lseek (2)). .SH WARNINGS On .SM HP-UX systems, the offset returned by .CR ftell() " or " ftell_unlocked() is measured in bytes and it is permissible to seek to positions relative to that offset. However, when porting to non-\c .SM HP-UX systems, .CR fseek() should be used directly without relying on any offset obtained from .CR ftell() because arithmetic cannot meaningfully be performed on such an offset if it is not measured in bytes on a particular operating system. .PP .CR fseek() , .CR fseek_unlocked() , .CR rewind() , and .CR rewind_unlocked() have no effect on streams that have been opened in append mode (see .IR fopen (3S)). .SH SEE ALSO lseek(2), write(2), ferror(3S), flockfile(3S), fopen(3S), fgetpos(3S), fseeko64(3S), ftello64(3S), ungetc(3S). .SH STANDARDS CONFORMANCE .CR fseek() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ftell() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR rewind() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fseek\f1, \f4rewind\f1, \f4ftell\f1 \- reposition a file pointer in a stream@@@\f3fseek(3S)\f1 .\" index@\f4fseek\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4rewind\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4ftell\f1 \- get offset from beginning-of-file of current byte in stream file@@@\f3fseek(3S)\f1 .\" index@\f1reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1file, stream: reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1get: pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\f1pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\s-1I/O\s+1 operations on a stream file, get or reposition pointer for@@@\f3fseek(3S)\f1 .\" index@\f1operations on a stream file, get or reposition pointer for \s-1I/O\s+1@@@\f3fseek(3S)\f1 .\" index@\f1stream file, get or reposition pointer for \s-1I/O\s+1 operations on a@@@\f3fseek(3S)\f1 .\" .\" index@\f4fseeko\f1 \- set position of next \s-1I/O\s+1 operation on stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4ftello\f1 \- get offset from beginning-of-file of current byte in stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4fseek_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4rewind_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4ftell_unlocked\f1 \- get offset from beginning-of-file of current byte in stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" .\" toc@\f3fseek(3S)\f1:\0\0\f4fseek\f1, \f4fseeko\f1, \f4fseek_unlocked\f1, \f4rewind\f1, \f4rewind_unlocked\f1, \n\f4ftell\f1, \f4ftello\f1, \f4ftell_unlocked\f1@@@reposition a file pointer in a stream .\" toc@\f4rewind\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4rewind_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseeko\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseek_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftello\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" .\" links@fseek.3s fseek_unloc.3s .\" links@fseek.3s rewind.3s .\" links@fseek.3s rewind_unlo.3s .\" links@fseek.3s ftell.3s .\" links@fseek.3s ftell_unloc.3s .\" links@fseek.3s fseeko.3s .\" links@fseek.3s ftello.3s .\" .\" $Header: fgetpos64.3s,v 78.3 96/02/12 17:04:12 ssa Exp $ .TA f .TH fgetpos64 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetpos64(\|), fopen64(\|), freopen64(\|), fseeko64(\|), fsetpos64(\|), fstatvfsdev64(\|), ftello64(\|), ftw64(\|), nftw64(\|), statvfsdev64(\|), tmpfile64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0fgetpos64(FILE\0*stream,\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "FILE\0*fopen64(const\0char\0*pathname,\0const\0char\0*type);" .PP .C "#include " .PP .C "FILE\0*freopen64(const\0char\0*pathname,\0const\0char\0*type,\0FILE\0*stream);" .PP .C "#include " .PP .C "int\0fseeko64(FILE\0*stream,\0off64_t\0*offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0fsetpos64(FILE\0*stream,\0const\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "int\0fstatvfsdev64(int\0filedes,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "off64_t\0ftello64(FILE\0*stream);" .PP .nf .C "#include " .PP .C "int ftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags)," .C " int depth);" .PP .C "#include " .PP .C "int nftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .PP .C "#include " .PP .C "int\0statvfsdev64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "FILE\0*tmpfile64(void);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 22 .C fgetpos64() The .C fgetpos64() function is identical to .C fgetpos() except that .C fgetpos64() returns the position in a .C fpos64_t instead of a .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fopen64() The .C fopen64() function is identical to .C fopen() in 64-bit compile environment. The .C fopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR fopen() . .TP .C freopen64() The .C freopen64() function is identical to .C freopen() in 64-bit compile environment. The .C freopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR freopen() . .TP .C fseeko64() The .C fseeko64() function is identical to .C fseeko() except that .C fseeko64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C fsetpos64() The .C fsetpos64() function is identical to .C fsetpos() except that .C fsetpos64() accepts an .CR fpos64_t for the pos parameter instead of .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fstatvfsdev64() The .C fstatvfsdev64() function is identical to .C fstatvfsdev() except that .C fstatvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C ftello64() The .C ftello64() function is identical to .C ftello() except that .C ftello64() returns the file position in an .C off64_t instead of an .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C ftw64() The .C ftw64() function is identical to .C ftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR ftw64() . All other functional behaviors, returns, and errors are identical. .TP .C nftw64() The .C nftw64() function is identical to .C nftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR nftw64() . All other functional behaviors, returns, and errors are identical. .TP .C statvfsdev64() The .C statvfsdev64() function is identical to .C statvfsdev() except that .C statvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C tmpfile64() The .C tmpfile64() function is identical to .C tmpfile() in the 64-bit compile environment. Both interfaces create a temporary file that is capable of growing beyond 2GB's if desired. All other functional behaviors, returns, and errors are identical. .\" .\" toc@\f4fgetpos64(2)\f1:\0\0\f4fopen64\f1, \f4freopen64\f1, \f4fseeko64\f1, \f4fsetpos64\f1, \f4fstatvfsdev64\f1, \f4ftello64\f1, \f4ftw64\f1, \n\f4nftw64\f1, \f4statvfsdev64\f1, \f4tmpfile64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4fgetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4freopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fseeko64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fsetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fstatvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftello64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4nftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4statvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4tmpfile64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3fgetpos64(2)\f1 .\" .\" links@fgetpos64.3s fopen64.3s .\" links@fgetpos64.3s freopen64.3s .\" links@fgetpos64.3s fseek64.3s .\" links@fgetpos64.3s fsetpos64.3s .\" links@fgetpos64.3s fstatvfs64.3s .\" links@fgetpos64.3s ftello64.3s .\" links@fgetpos64.3s ftw64.3s .\" links@fgetpos64.3s nftw64.3s .\" links@fgetpos64.3s statvfsdev64.3s .\" links@fgetpos64.3s tmpfile64.3s .\" .\" $Header: ftok.3c,v 76.1 95/06/20 14:45:24 ssa Exp $ .TA f .TH ftok 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ftok(\|) \- create interprocess communication identifier .SH SYNOPSIS .C "#include " .PP .C "key_t ftok(const char *path, int id);" .SH DESCRIPTION All interprocess communication facilities require the user to supply a key to be used by the .CR msgget() , .CR semget() , and .CR shmget() system calls to obtain interprocess communication identifiers (see .IR msgget (2), .IR semget (2), and .IR shmget (2)). .PP .C ftok() returns a key based on .I path and .I id that is usable in subsequent .CR msgget() , .CR semget() , and .C shmget() system calls. .PP The parameters for the .C ftok() function are as follows: .RS .TP20 .I path must be the path name of an existing file that is accessible to the process. .TP .I id is a character that uniquely identifies a project. Note that .C ftok() returns the same key for linked files when called with the same .I id and that it returns different keys when called with the same file name but different .IR id s. .RE .SH RETURN VALUE .C ftok() returns .RC ( key_t ) \(mi 1 if .I path does not exist or if it is not accessible to the process. .SH EXAMPLES The following call to .CR ftok () returns a key associated with the file .I myfile and id .CR A : .IP .ift .ft 4 .ifn .ft 3 .ps +1 key_t mykey; mykey = ftok ("myfile", 'A'); .ft .ps .RE .SH WARNINGS If the file whose .I path is passed to .C ftok() is removed when keys still refer to the file, future calls to .C ftok() with the same .I path and .I id will return an error. If the same file is recreated, .C ftok() is likely to return a different key than it did the original time it was called. .SH SEE ALSO intro(2), msgget(2), semget(2), shmget(2). .\" .\" index@\f4ftok()\f1 \- create interprocess communication identifier@@@\f3ftok(3C)\f1 .\" index@\f1create interprocess communication identifier@@@\f3ftok(3C)\f1 .\" index@\f1interprocess communication identifier, create@@@\f3ftok(3C)\f1 .\" index@\f1communication identifier, create interprocess@@@\f3ftok(3C)\f1 .\" index@\f1identifier, create interprocess communication@@@\f3ftok(3C)\f1 .\" .\" toc@\f3ftok(3C)\f1:\0\0\f4ftok()\f1@@@create interprocess communication identifier .\" .\" links@ftok.3c stdipc.3c .\" $Header: ftw.3c,v 78.1 96/02/12 13:48:55 ssa Exp $ .TA f .TH ftw 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ftw(), nftw(), nftw2() \- walk a file tree executing a function .SH SYNOPSIS .nf .C "#include " .PP .C "int ftw (const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat *obj_stat," .C " int obj_flags)," .C " int depth);" .PP .C "int nftw2(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .PP .C "int nftw (const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .SS UNIX95 .nf .C "int nftw (const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat *obj_stat," .C " int obj_flags," .C " struct *FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .SH DESCRIPTION The .CR ftw() function recursively descends the directory hierarchy rooted in .IR path . For each object in the hierarchy, .CR ftw() calls .IR fn , passing it a pointer to a null-terminated character string containing the name of the object, a pointer to a .CR stat structure containing information about the object (see .CR lstat() in .IR stat (2)), and an integer. The possible values of the integer, defined in the .CR header file, are: .RS .TP 15 .CR FTW_F The object is a file. .TP .CR FTW_D The object is a directory. .TP .CR FTW_SL The object is a symbolic link. .TP .CR FTW_DNR The object is a directory without read permission. .I fn will not be called for any of its descendants. .TP .CR FTW_NS .CR lstat() failed on the object. The contents of the .CR stat structure are undefined. If the .CR lstat() failure is because the object is in a directory without search permission, .I fn is called and the walk continues. If .CR lstat() fails for any other reason, .CR ftw() does not call .IR fn , it sets .CR errno , and returns .CR -1 . .RE .PP Tree traversal continues until the tree is exhausted, an invocation of .I fn returns a nonzero value, or an error is detected within .CR ftw() , such as an I/O error. If the tree is exhausted, .CR ftw() returns zero. If .I fn returns a nonzero value, .CR ftw() stops its tree traversal and returns the same value as returned by .IR fn . If .CR ftw() detects an error, it returns .CR -1 and sets the error type in .CR errno (see .IR errno (2)). .PP .CR ftw() visits a directory before visiting any of its descendants. .PP .CR ftw() and .CR nftw() use one file descriptor for each level in the tree. The .I depth argument limits the number of file descriptors that can be used. If .I depth is 0 or negative, the effect is the same as if it were 1. .I depth must not be greater than the number of file descriptors currently available for use. For best performance, .I depth should be at least as large as the number of levels in the tree. .PP .CR nftw() is similar to .CR ftw() except that it takes the additional argument .IR flags . The .I flags field is the inclusive OR of the following values, as defined in the .CR header file: .RS .TP 15 .CR FTW_PHYS .CR nftw() does a physical walk. It does not follow symbolic links. .CR nftw() follows hard links but does not walk down any path that crosses itself. If .CR FTW_PHYS is not specified, .CR nftw() follows symbolic and hard links but does not walk a path that crosses itself. .TP .CR FTW_MOUNT The walk does not cross a mount point. This means the walk does not visit any files that reside on a device other than the one where the walk started. It does not cross NFS mount points. .TP .CR FTW_DEPTH .CR nftw() performs a depth-first search. This means that a directory's contents are visited before the directory itself is visited. .TP .CR FTW_CHDIR The walk does a .CR chdir() (see .IR chdir (2)) to each directory before reading it. .TP .CR FTW_SERR The walk normally terminates and returns .CR -1 if .CR lstat() fails for any reason. If .CR FTW_SERR is specified and an .CR lstat() failure is encountered, .I fn is called, and the walk continues. .RE .PP .CR nftw() calls .I fn with four arguments for each file and directory visited. The first argument is the path name of the file or directory, the second is a pointer to a .CR stat structure (see .IR lstat (2)) containing information about the object, and the third is an integer giving additional information as follows: .RS .TP 15 .CR FTW_F The object is a file. .TP .CR FTW_D The object is a directory. .TP .CR FTW_DP The object is a directory and subdirectories have been visited. This can be passed to .I fn only if .CR FTW_DEPTH is specified. .TP .CR FTW_SL The object is a symbolic link. This can be passed to .I fn only if .CR FTW_PHYS is specified. .TP .CR FTW_SLN The object is a symbolic link that does not point to an existing object. This can be passed to .I fn only if .CR FTW_PHYS is not specified. .TP .CR FTW_DNR The object is a directory that cannot be read. .I fn is not called for any of its descendants. .TP .CR FTW_NS .CR lstat() failed on the object. The contents of the .CR stat structure passed to .I fn are undefined. If the .CR lstat() failure occurred because the object is in a directory without search permission, .CR errno is set, and .CR nftw() returns .CR -1 after calling .IR fn . Note that this behavior differs from .CR ftw() . If .CR lstat() fails for any other reason, .CR nftw() does not call .IR fn , it sets .CR errno , and returns .CR -1 . This behavior can be altered by specifying the .CR FTW_SERR .IR flag . .RE .PP The fourth argument is different for the default environment and the .CR UNIX95 environment. For the default environment, the fourth argument is a structure .CR FTW . For the .CR UNIX95 environment, the fourth argument is a pointer to a structure .CR FTW (ie: .CR *FTW ). .CR FTW contains the following members: .nf .IP .C "int base;" .C "int level;" .fi .PP The value of .I base is the offset from the first character in the path name to where the base name of the object starts; this path name is passed as the first argument to .IR fn . The value of .I level indicates depth relative to the start of the walk, where the start level has a value of zero. .PP .CR nftw2() is equivalent to .CR nftw() . This function is provided for HP-UX compatibility in future releases. .SH ERRORS If .CR ftw() or .CR nftw() fails, it sets .CR errno (see .IR errno (2)) to one of the following values: .RS .TP 25 [EACCES] If a component of the .IR path prefix denies search permission, or if read permission is denied for .IR path , .I fn returns .CR -1 and does not reset .CR errno . .TP [EINVAL] The value of the .I depth argument is invalid. .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] .I path points to the name of a file that does not exist, or points to an empty string. .TP [ENOTDIR] A component of .I path is not a directory. .TP [EOVERFLOW] One of the values in .C struct stat (st_size or st_blocks) is too large to store into the structure to be passed to the function pointed to by .IR fn. .RE .PP In addition, if the function pointed to by .I fn encounters system errors, .CR errno may be set accordingly. .ift .br .ift .ne 12 .SH WARNINGS Because these functions are recursive, it is possible for them to terminate with a memory fault when applied to very deep file structures. .PP .CR ftw() and .CR nftw() use .CR malloc() to allocate dynamic storage during their operation (see .IR malloc (3C)) If they are forcibly terminated (such as if .CR longjmp() is executed by .I fn or an interrupt routine), the calling function will not have a chance to free that storage, causing it to remain allocated until the process terminates. A safe way to handle interrupts is to store the fact that an interrupt has occurred, and arrange to have .I fn return a nonzero value at its next invocation. .PP The syntax for .CR nftw() may be changed in a future release. (See .CR nftw2() in the DESCRIPTION section). .SH APPLICATION USAGE To use the .CR UNIX95 prototype, the .CR UNIX95 environment must be defined. This is done by defining the .CR UNIX95 environment variable, passing the .CR _XOPEN_UNIX_EXTENDED flag as a compiler option, and adding .CR /usr/xpg4/bin to your path. This can be done as follows: .TP 3 1. .CR "export UNIX95=" .PD 0 .TP 2. .CR "PATH=/usr/xpg4/bin:$PATH" .TP 3. .CR "cc foo.c -D_XOPEN_SOURCE_EXTENDED" .PD .SH AUTHOR .CR ftw() , .CR nftw() , and .CR nftw2() were developed by AT&T and HP. .SH SEE ALSO stat(2), ftw64(3C), nftw64(3C), malloc(3C). .SH STANDARDS CONFORMANCE .CR ftw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f1descend a directory hierarchy recursively, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1directory hierarchy, recursively descend a, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1execute a function, descending a directory tree@@@\f3ftw(3C)\f1 .\" index@\f1file tree, walk, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1function, execute descending a directory tree@@@\f3ftw(3C)\f1 .\" index@\f1hierarchy, directory, recursively descend a, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1recursively descend a directory hierarchy, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1traverse (walk) a file tree, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1tree, walk a file, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1walk a file tree, executing a function@@@\f3ftw(3C)\f1 .\" index@\f4ftw()\f1 \- walk a file tree executing a function@@@\f3ftw(3C)\f1 .\" index@\f4nftw()\f1 \- walk a file tree executing a function@@@\f3ftw(3C)\f1 .\" index@\f4nftw2()\f1 \- walk a file tree executing a function@@@\f3ftw(3C)\f1 .\" .\" toc@\f3ftw(3C)\f1:\0\0\f4ftw()\f1, \f4nftw()\f1, \f4nftw2()\f1@@@walk a file tree, executing a function\f1 .\" toc@\f4nftw()\f1:\0\0walk a file tree, executing a function@@@\f1see \f3ftw(3C)\f1 .\" toc@\f4nftw2()\f1:\0\0walk a file tree, executing a function@@@\f1see \f3ftw(3C)\f1 .\" .\" links@ftw.3c nftw.3c .\" links@ftw.3c nftw2.3c .\" $Header: fgetpos64.3s,v 78.3 96/02/12 17:04:12 ssa Exp $ .TA f .TH fgetpos64 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetpos64(\|), fopen64(\|), freopen64(\|), fseeko64(\|), fsetpos64(\|), fstatvfsdev64(\|), ftello64(\|), ftw64(\|), nftw64(\|), statvfsdev64(\|), tmpfile64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0fgetpos64(FILE\0*stream,\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "FILE\0*fopen64(const\0char\0*pathname,\0const\0char\0*type);" .PP .C "#include " .PP .C "FILE\0*freopen64(const\0char\0*pathname,\0const\0char\0*type,\0FILE\0*stream);" .PP .C "#include " .PP .C "int\0fseeko64(FILE\0*stream,\0off64_t\0*offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0fsetpos64(FILE\0*stream,\0const\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "int\0fstatvfsdev64(int\0filedes,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "off64_t\0ftello64(FILE\0*stream);" .PP .nf .C "#include " .PP .C "int ftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags)," .C " int depth);" .PP .C "#include " .PP .C "int nftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .PP .C "#include " .PP .C "int\0statvfsdev64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "FILE\0*tmpfile64(void);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 22 .C fgetpos64() The .C fgetpos64() function is identical to .C fgetpos() except that .C fgetpos64() returns the position in a .C fpos64_t instead of a .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fopen64() The .C fopen64() function is identical to .C fopen() in 64-bit compile environment. The .C fopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR fopen() . .TP .C freopen64() The .C freopen64() function is identical to .C freopen() in 64-bit compile environment. The .C freopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR freopen() . .TP .C fseeko64() The .C fseeko64() function is identical to .C fseeko() except that .C fseeko64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C fsetpos64() The .C fsetpos64() function is identical to .C fsetpos() except that .C fsetpos64() accepts an .CR fpos64_t for the pos parameter instead of .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fstatvfsdev64() The .C fstatvfsdev64() function is identical to .C fstatvfsdev() except that .C fstatvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C ftello64() The .C ftello64() function is identical to .C ftello() except that .C ftello64() returns the file position in an .C off64_t instead of an .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C ftw64() The .C ftw64() function is identical to .C ftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR ftw64() . All other functional behaviors, returns, and errors are identical. .TP .C nftw64() The .C nftw64() function is identical to .C nftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR nftw64() . All other functional behaviors, returns, and errors are identical. .TP .C statvfsdev64() The .C statvfsdev64() function is identical to .C statvfsdev() except that .C statvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C tmpfile64() The .C tmpfile64() function is identical to .C tmpfile() in the 64-bit compile environment. Both interfaces create a temporary file that is capable of growing beyond 2GB's if desired. All other functional behaviors, returns, and errors are identical. .\" .\" toc@\f4fgetpos64(2)\f1:\0\0\f4fopen64\f1, \f4freopen64\f1, \f4fseeko64\f1, \f4fsetpos64\f1, \f4fstatvfsdev64\f1, \f4ftello64\f1, \f4ftw64\f1, \n\f4nftw64\f1, \f4statvfsdev64\f1, \f4tmpfile64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4fgetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4freopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fseeko64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fsetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fstatvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftello64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4nftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4statvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4tmpfile64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3fgetpos64(2)\f1 .\" .\" links@fgetpos64.3s fopen64.3s .\" links@fgetpos64.3s freopen64.3s .\" links@fgetpos64.3s fseek64.3s .\" links@fgetpos64.3s fsetpos64.3s .\" links@fgetpos64.3s fstatvfs64.3s .\" links@fgetpos64.3s ftello64.3s .\" links@fgetpos64.3s ftw64.3s .\" links@fgetpos64.3s nftw64.3s .\" links@fgetpos64.3s statvfsdev64.3s .\" links@fgetpos64.3s tmpfile64.3s .\" .\" $Header: flockfile.3s,v 76.1 95/06/20 14:45:01 ssa Exp $ .TA f .TH flockfile 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME flockfile(\|), funlockfile(\|) \- explicit locking of streams within a multi-thread application .SH SYNOPSIS .C "#include " .PP .C "void flockfile(FILE *stream);" .PP .C "void funlockfile(FILE *stream);" .SH DESCRIPTION The .CR flockfile() and .CR funlockfile() functions provide for explicit application-level locking of streams. These functions can be used by a thread to delineate a sequence of I/O statements that are to be executed as a unit. .PP The .CR flockfile() function is used by a thread to advise the implementation that it is the current owner of a stream. .PP The .CR funlock() function is used to relinquish the ownership granted to the thread. The behavior is undefined if a thread other than the current owner calls the .CR funlockfile() function. .PP Logically, there is a count associated with each stream. This count is implicitly initialized to zero when the stream is created. The stream is unlocked when the count is zero. When the count is positive, a single thread owns the stream. When the .CR flockfile() function is called, if the count is zero or if the count is positive and the caller owns the stream, the count is incremented. Otherwise, the calling thread is suspended, waiting for the count to return to zero. Each call to .CR funlockfile() decrements the count. This allows matching calls to .CR flockfile() and .CR funlockfile() to be nested. .SH RETURN VALUE None. .\" .\" toc@\f3flockfile(3S)\f1:\0\0\f4flockfile\f1, \f4funflockfile\f1@@@explicit locking of streams within a multi-thread application .\" toc@\f4funflockfile\f1:\0\0explicit locking of streams within a multi-thread application@@@see \f3flockfile(3S)\f1 .\" .\" index@\f4flockfile()\f1, \f4funflockfile\f1 \- explicit locking of streams within a multi-thread application@@@\f3flockfile(3S)\f1 .\" index@\f4funflockfile()\f1, \f4flockfile\f1 \- explicit locking of streams within a multi-thread application@@@\f3flockfile(3S)\f1 .\" .\" index@explicit locking of streams within a multi-thread application@@@\f3flockfile(3S)\f1 .\" index@locking of streams within a multi-thread application, explicit@@@\f3flockfile(3S)\f1 .\" index@streams within a multi-thread application, explicit locking of@@@\f3flockfile(3S)\f1 .\" index@multi-thread application, explicit locking of streams within a@@@\f3flockfile(3S)\f1 .\" index@application, explicit locking of streams within a multi-thread@@@\f3flockfile(3S)\f1 .\" .\" links@flockfile.3s funlockfile.3s .\" $Header: fread.3s,v 72.7 94/11/14 15:28:40 ssa Exp $ .TA f .TH fread 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fread(\|), fread_unlocked(\|), fwrite(\|), fwrite_unlocked(\|) \- buffered binary input/output to a stream file .SH SYNOPSIS .C "#include\0" .nf .PP .C "size_t\0fread(void\0*ptr,\0size_t\0size,\0size_t\0nitems,\0FILE\0*stream);" .PP .C "size_t\0fread_unlocked( .PD 0 .IP .C "void\0*ptr," .C "\0size_t\0size," .C "\0size_t\0nitems," .C "\0FILE\0*stream);" .PD .PP .C "size_t\0fwrite(const\0void\0*ptr,\0size_t\0size,\0size_t\0nitems,\0FILE\0*stream);" .PP .C "size_t\0fwrite_unlocked(" .PD 0 .IP .C "const\0void\0*ptr," .C "\0size_t\0size," .C "\0size_t\0nitems," .C "\0FILE\0*stream);" .PD .SH DESCRIPTION .CR fread() copies, into an array pointed to by .IR ptr , .I nitems items of data from the named input .IR stream , where an item of data is a sequence of bytes (not necessarily terminated by a null byte) of length .IR size . .CR fread() stops appending bytes if an end-of-file or error condition is encountered while reading .IR stream, or if .I nitems items have been read. .CR fread() leaves the file pointer in .IR stream , if defined, pointing to the byte following the last byte read if there is one. .CR fread() does not change the contents of .IR stream . .PP .CR fwrite() appends at most .I nitems items of data from the array pointed to by .I ptr to the named output .IR stream . .CR fwrite() stops appending when it has appended .I nitems items of data or if an error condition is encountered on .IR stream . .CR fwrite() does not change the contents of the array pointed to by .IR ptr . .PP The argument .I size is typically .IR sizeof (\(** ptr ) where the pseudo-function .I sizeof specifies the length of an item pointed to by .IR ptr . .PP .CR fread_unlocked() and .CR fwrite_unlocked() are identical to .CR fread() and .CR fwrite() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH "SEE ALSO" read(2), write(2), fopen(3S), flockfile(3S), getc(3S), gets(3S), printf(3S), putc(3S), puts(3S), scanf(3S). .SH RETURN VALUE .CR fread() , " fread_unlocked()" , " fwrite()" , and .CR fwrite_unlocked() return the number of items read or written. If .I size or .I nitems is non-positive, no characters are read or written and 0 is returned by .CR fread() , " fread_unlocked()" , " fwrite()" , and .CR fwrite_unlocked() . .SH STANDARDS CONFORMANCE .CR fread() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fwrite() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fread()\f1, \f4fwrite()\f1 \- buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@\f4fwrite()\f1, \f4fread()\f1 \- buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@file, stream: buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@binary input/output to a stream file, buffered@@@\f3fread(3S)\f1 .\" index@input/output to a stream file, buffered binary@@@\f3fread(3S)\f1 .\" index@\s-1I/O\s+1 to a stream file, buffered binary@@@\f3fread(3S)\f1 .\" index@stream file, buffered binary input/output to a@@@\f3fread(3S)\f1 .\" .\" toc@\f3fread(3S)\f1:\0\0\f4fread()\f1, \f4fwrite()\f1@@@buffered binary input/output to a stream file .\" toc@\f4fwrite()\f1:\0\0buffered binary output to a stream file@@@see \f3fread(3S)\f1 .\" .\" links@fread.3s fread_unloc.3s .\" links@fread.3s fwrite.3s .\" links@fread.3s fwrite_unlo.3s .\" $Header: fread.3s,v 72.7 94/11/14 15:28:40 ssa Exp $ .TA f .TH fread 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fread(\|), fread_unlocked(\|), fwrite(\|), fwrite_unlocked(\|) \- buffered binary input/output to a stream file .SH SYNOPSIS .C "#include\0" .nf .PP .C "size_t\0fread(void\0*ptr,\0size_t\0size,\0size_t\0nitems,\0FILE\0*stream);" .PP .C "size_t\0fread_unlocked( .PD 0 .IP .C "void\0*ptr," .C "\0size_t\0size," .C "\0size_t\0nitems," .C "\0FILE\0*stream);" .PD .PP .C "size_t\0fwrite(const\0void\0*ptr,\0size_t\0size,\0size_t\0nitems,\0FILE\0*stream);" .PP .C "size_t\0fwrite_unlocked(" .PD 0 .IP .C "const\0void\0*ptr," .C "\0size_t\0size," .C "\0size_t\0nitems," .C "\0FILE\0*stream);" .PD .SH DESCRIPTION .CR fread() copies, into an array pointed to by .IR ptr , .I nitems items of data from the named input .IR stream , where an item of data is a sequence of bytes (not necessarily terminated by a null byte) of length .IR size . .CR fread() stops appending bytes if an end-of-file or error condition is encountered while reading .IR stream, or if .I nitems items have been read. .CR fread() leaves the file pointer in .IR stream , if defined, pointing to the byte following the last byte read if there is one. .CR fread() does not change the contents of .IR stream . .PP .CR fwrite() appends at most .I nitems items of data from the array pointed to by .I ptr to the named output .IR stream . .CR fwrite() stops appending when it has appended .I nitems items of data or if an error condition is encountered on .IR stream . .CR fwrite() does not change the contents of the array pointed to by .IR ptr . .PP The argument .I size is typically .IR sizeof (\(** ptr ) where the pseudo-function .I sizeof specifies the length of an item pointed to by .IR ptr . .PP .CR fread_unlocked() and .CR fwrite_unlocked() are identical to .CR fread() and .CR fwrite() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH "SEE ALSO" read(2), write(2), fopen(3S), flockfile(3S), getc(3S), gets(3S), printf(3S), putc(3S), puts(3S), scanf(3S). .SH RETURN VALUE .CR fread() , " fread_unlocked()" , " fwrite()" , and .CR fwrite_unlocked() return the number of items read or written. If .I size or .I nitems is non-positive, no characters are read or written and 0 is returned by .CR fread() , " fread_unlocked()" , " fwrite()" , and .CR fwrite_unlocked() . .SH STANDARDS CONFORMANCE .CR fread() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fwrite() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fread()\f1, \f4fwrite()\f1 \- buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@\f4fwrite()\f1, \f4fread()\f1 \- buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@file, stream: buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@buffered binary input/output to a stream file@@@\f3fread(3S)\f1 .\" index@binary input/output to a stream file, buffered@@@\f3fread(3S)\f1 .\" index@input/output to a stream file, buffered binary@@@\f3fread(3S)\f1 .\" index@\s-1I/O\s+1 to a stream file, buffered binary@@@\f3fread(3S)\f1 .\" index@stream file, buffered binary input/output to a@@@\f3fread(3S)\f1 .\" .\" toc@\f3fread(3S)\f1:\0\0\f4fread()\f1, \f4fwrite()\f1@@@buffered binary input/output to a stream file .\" toc@\f4fwrite()\f1:\0\0buffered binary output to a stream file@@@see \f3fread(3S)\f1 .\" .\" links@fread.3s fread_unloc.3s .\" links@fread.3s fwrite.3s .\" links@fread.3s fwrite_unlo.3s .\" $Header: lgamma.3m,v 78.1 96/02/13 12:44:15 ssa Exp $ .TA l .TH lgamma 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lgamma(\|), lgamma_r(\|), gamma(\|), signgam(\|) \- log gamma function .SH SYNOPSIS .C "#include " .PP .C "double lgamma(double x);" .PP .C "double gamma(double x);" .PP .C "extern int signgam;" .PP .C "double lgamma_r(double x, int *sign); .SH DESCRIPTION .CR lgamma() and .CR gamma() return .ifn \{\ .CI ln(|Gamma( x )|)\c\} .ift \{\ .CI ln(|\(*G( x )|)\c\} , where .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} is defined as the integral, as .I t goes from zero to infinity, of .CI exp(\(mi t ) times .I t to the power .RI ( x \(mi1). .PP The sign of .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} is returned in the external integer .CR signgam . The argument .I x must not be zero or a negative integer. .RC ( lgamma() is defined over the reals excluding the non-positive integers.) .PP The following C program fragment can be used to calculate .ifn \{\ .RI Gamma( x ):\} .ift \{\ .RI \(*G( x ):\} .nf .IP .CR "if ((y = lgamma(x)) > LN_MAXDOUBLE)" .CR " error(\|);" .CR "y = signgam * exp(y);" .fi .PP where if .I y is greater than .CR LN_MAXDOUBLE , as defined in the .RC < values.h > header file, .CR exp() returns a range error (see .IR exp (3M)). .PP The log gamma function .CR lgamma() is not reentrant, because it uses the global variable .CR signgam . The function .CR lgamma_r() is a reentrant version of .CR lgamma() that can be used in multi-threaded applications. The function .CR lgamma_r() returns the sign of .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} in its parameter list, through the pointer .IR sign . The value pointed to by .I sign is +1 if .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} is positive, \-1 if it is negative. The function .CR lgamma_r() is named in the spirit of the POSIX threads draft standard (P1003.4a), but it has no formal sanction. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is a non-positive integer, .CR lgamma() and .CR gamma() return .CR HUGE_VAL . .PP If the correct value would overflow, .CR lgamma() and .CR gamma() return .CR HUGE_VAL . .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR lgamma() and .CR gamma() return zero. .PP If .I x is NaN, .CR lgamma() and .CR gamma() return NaN. .SH ERRORS No errors are defined. .SH WARNINGS .CR lgamma() and .CR gamma() are unsafe in multi-thread applications. .CR lgamma_r() is MT-Safe and should be used instead. .SH SEE ALSO exp(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR lgamma() ": SVID3, XPG4.2" .PP .CR gamma() ": SVID2, XPG4.2" .PP .CR signgam ": SVID3, XPG4.2" .\" .\" index@\f4gamma()\f1, \f4lgamma()\f1, \f4lgamma_r()\f1, \f4signgam()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f4lgamma()\f1, \f4lgamma_r()\f1, \f4gamma()\f1, \f4signgam()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f4lgamma_r()\f1, \f4gamma()\f1, \f4signgam()\f1, \f4lgamma()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f4signgam()\f1, \f4gamma()\f1, \f4lgamma()\f1, \f4lgamma_r()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f1math: log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f1log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f1gamma function, log@@@\f3lgamma(3M)\f1 .\" .\" toc@\f3lgamma(3M)\f1:\0\0\f4gamma()\f1, \f4lgamma()\f1, \f4lgamma_r()\f1, \f4signgam()\f1@@@log gamma function .\" toc@\f4lgamma()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" toc@\f4lgamma_r()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" toc@\f4gamma()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" toc@\f4signgam()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" .\" links@lgamma.3m signgam.3m .\" links@lgamma.3m gamma.3m .\" links@lgamma.3m lgamma_r.3m .\" $Header: crt0.3,v 72.4 94/09/02 14:40:25 ssa Exp $ .TA c .TH crt0 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crt0.o, gcrt0.o, mcrt0.o \- execution startup routines .SH DESCRIPTION .PP The C, Pascal, and FORTRAN compilers link in the object files .CR crt0.o , .CR gcrt0.o , or .C mcrt0.o to provide startup capabilities and environments for program execution. All are identical except that .C gcrt0.o and .C mcrt0.o provide additional functionality for .IR gprof (1) and .IR prof (1) profiling support respectively. .PP The following symbols are defined in these object files: .RS .TP 20 .C _\|_argc_value A variable of type .I int containing the number of arguments. .TP .C _\|_argv_value An array of character pointers to the arguments themselves. .TP .C _environ An array of character pointers to the environment in which the program will run. This array is terminated by a null pointer. .TP .SM .C _FPU_MODEL A variable of type .I short containing the FPU model number returned by the FP status instruction. This variable is initialized with data from the kernel. .TP .SM .C _FPU_REVISION A variable of type .I short containing the FPU revision number returned by the FP status instruction. This variable is initialized with data from the kernel. .TP .SM .C _CPU_REVISION A variable of type .I int containing the CPU revision of the machine. This variable is initialized with data from the kernel. .TP .SM .C _SYSTEM_ID A variable of type .I int containing the system id value for an executable program. .TP .SM .C $START$ Execution start address. .TP .C _start A secondary startup routine for C programs, called from .CR $START$ , which in turn calls .CR main . This routine is contained in the C library rather than the .C crt0.o file. For Pascal and F\s-2ORTRAN\s0 programs, this symbol labels the beginning of the outer block (main program) and is generated by the compilers. .TP .C $global$ The initial address of the program's data pointer. The startup code loads this address into general register 27. .TP .C $UNWIND_START The beginning of the stack unwind table. .TP .C $UNWIND_END The end of the stack unwind table. .TP .C $RECOVER_START The beginning of the try/recover table. .TP .C $RECOVER_END The end of the try/recover table. .RE .PP The .C crt0.o file defines a null procedure for .CR _mcount , so programs compiled with profiling can be linked without profiling. .PP The linker defines the following two symbols: .RS .TP 20 .C _\|_text_start The beginning address of the program's text area. .PD 0 .TP .C _\|_data_start The beginning address of the program's data area. .PD .RE .SH AUTHOR The features described in this entry originated from .SM AT&T UNIX System III. .SH SEE ALSO .PD .SS Profiling and Debugging Tools: .TP 18 .IR gprof(1) display call graph profile data .PD 0 .TP .IR monitor(3C) prepare execution profile .TP .IR prof(1) display profile data .TP .IR profil(2) execution time profile .PD .SS System Tools: .TP 18 .IR cc(1) invoke the HP-UX C compiler .PD 0 .TP .IR exec(2) execute a file .TP f77(1) invoke the HP-UX FORTRAN compiler .TP .IR ld(1) invoke the link editor .TP .IR pc(1) invoke the HP-UX Pascal compiler .PD .SS Miscellaneous: .TP 18 .IR end(3C) symbol of the last locations in program .PD .\" .\" index@\f4crt0.o\f1, \f4gcrt0.o\f1, \f4mcrt0.o\f1, \f4frt0.o\f1, \f4mfrt0.o\f1 \- execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4crt0.o\f1, \f4mcrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4gcrt0.o\f1, \f4gfrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4gfrt0.o\f1, \f4gcrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4mcrt0.o\f1, \f4crt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4frt0.o\f1, \f4mfrt0.o\f1 \- F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4mfrt0.o\f1, \f4frt0.o\f1 \- F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@Pascal and C execution startup routines@@@\f3crt0(3)\f1 .\" index@F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@execution startup routines, C, Pascal, and F\s-2ORTRAN\s+2@@@\f3crt0(3)\f1 .\" .\" toc@\f3crt0(3)\f1:\0\0\f4crt0.o\f1, \f4mcrt0.o\f1, \f4frt0.o\f1, \f4mfrt0.o\f1@@@execution startup routines .\" toc@\f4crt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4gcrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4mcrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4frt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4mfrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" .\" links@crt0.3 crt0.o.3 .\" links@crt0.3 gcrt0.o.3 .\" links@crt0.3 mcrt0.o.3 .\" links@crt0.3 frt0.o.3 .\" links@crt0.3 gfrt0.o.3 .\" links@crt0.3 mfrt0.o.3 .\" .\" fileset_database@crt0.3 PROGRAMING-MAN .\" $Header: ecvt.3c,v 72.6 94/11/30 15:42:51 ssa Exp $ .TA e .TH ecvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ecvt(\|), ecvt_r(\|), fcvt,(\|) fcvt_r(\|), gcvt(\|) \- convert floating-point number to string .SH SYNOPSIS .C "#include " .PP .C "char *ecvt(double value, int ndigit, int *decpt, int *sign);" .PP .C "int ecvt_r(" .nf .PD 0 .IP .C "double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PP .C "char *fcvt(double value, int ndigit, int *decpt, int *sign);" .PP .C "int fcvt_r(" .nf .PD 0 .IP .C "double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char *gcvt(double value, int ndigit, char *buf);" .SH DESCRIPTION .TP 12 .C ecvt() Converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero, otherwise it is zero. .IP One of three non-digit characters strings could be returned if the converted value is out of range. A .C -\|- or .C +\|+ is returned if the value is larger than the exponent can contain, and is negative, or positive, respectively. The third string is returned if the number is illegal, a zero divide for example. The result value is Not A Number .SM (NAN) and would return a .C ? character. .TP .C ecvt_r() Identical to .CR ecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C fcvt() Identical to .CR ecvt() , except that the correct digit has been rounded for printf .C %f (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C fcvt_r() Identical to .CR fcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C gcvt() Converts the .I value to a null-terminated string in the array pointed to by .I buf and returns .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character is included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C", is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the value of the radix character within the current .SM NLS environment. .SH WARNINGS The values returned by .C ecvt() and .C fcvt() point to a single static data array whose content is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .C ecvt_r() and .C fcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .C ecvt() and .C fcvt() were developed by AT&T. .C gcvt() was developed by AT&T and HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH STANDARDS CONFORMANCE .CR ecvt() ": XPG2" .PP .CR fcvt() ": XPG2" .PP .CR gcvt() ": XPG2" .\" .\" index@\f4ecvt()\fP, \f4fcvt()\fP \- convert floating-point number to string@@@\f3ecvt(3C)\f1 .\" index@\f4fcvt()\fP, \f4ecvt()\fP \- convert floating-point number to string@@@\f3ecvt(3C)\f1 .\" index@\f4gcvt()\f1 \- convert floating-point number to string array element@@@\f3ecvt(3C)\f1 .\" index@\f4gcvt()\fP \- convert floating-point number to string array element@@@\f3ecvt(3C)\f1 .\" index@convert floating-point number to string or string array element@@@\f3ecvt(3C)\f1 .\" index@floating-point: convert floating-point number to string or string array element@@@\f3ecvt(3C)\f1 .\" index@number to string or string array element, convert floating-point@@@\f3ecvt(3C)\f1 .\" index@string or string array element, convert floating-point number to@@@\f3ecvt(3C)\f1 .\" index@array element, convert floating-point number to string or string@@@\f3ecvt(3C)\f1 .\" index@element, convert floating-point number to string or string array@@@\f3ecvt(3C)\f1 .\" .\" toc@\f3ecvt(3C)\f1:\0\0\f4ecvt()\fP, \f4fcvt()\fP, \f4gcvt()\f1@@@convert floating-point number to string .\" toc@\f4fcvt()\fP:\0\0convert floating-point number to string@@@see \f3ecvt(3C)\f1 .\" toc@\f4gcvt()\fP:\0\0convert floating-point number to string@@@see \f3ecvt(3C)\f1 .\" .\" links@ecvt.3c ecvt_r.3c .\" links@ecvt.3c fcvt.3c .\" links@ecvt.3c fcvt_r.3c .\" links@ecvt.3c gcvt.3c .\" .\" fileset_database@ecvt.3c PROGRAMING-MAN .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "geometry_manager" "Xt \- Intrinsics Methods" .SH "Name" .Na geometry_manager \- Composite class method called when a child requests a new geometry. .Nz .XX "geometry management: geometry_manager method" .XX "methods, geometry_manager" .SH "Synopsis" .Sy typedef XtGeometryResult (*XtGeometryHandler)(Widget, XtWidgetGeometry *, .br XtWidgetGeometry *); .As Widget \f(CIw\fP; XtWidgetGeometry *\f(CIrequest\fP; XtWidgetGeometry *\f(CIgeometry_return\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the child widget making the request. .IP \f(CIrequest\fP 1i Specifies the requested geometry. .SS "Outputs" .IP \f(CIgeometry_return\fP 1i Specifies the reply geometry. .SS "Returns" The parent's reply: \f(CWXtGeometryYes\fP, \f(CWXtGeometryNo\fP, \f(CWXtGeometryAlmost\fP, or \f(CWXtGeometryDone\fP. .SH "Description" The \f(CWgeometry_manager()\fR method is registered on the \f(CWgeometry_manager()\fP Composite class part field, and is called when a child widget requests a new geometry or size with \f(CWXtMakeGeometryRequest()\fP or \f(CWXtMakeResizeRequest()\fP. The \f(CWgeometry_manager\fP field must respond to the request by approving it, rejecting it, or proposing a compromise. .LP The \f(CWgeometry_manager()\fP method should examine the contents of the \f(CIrequest\fP structure (see the "Structures" section below) and determine if it can grant the request. \f(CWrequest\f(CW->request_mode\fR contains flags which specify which of the remaining fields of the structure the child cares about. .LP If the widget can satisfy all the changes requested, it should return \f(CWXtGeometryYes\fP. If the \f(CWXtCWQueryOnly\fP flag is not specified, then it should update the specified widget's \f(CWx\fP, \f(CWy\fP, \f(CWwidth\fP, \f(CWheight\fP, and \f(CWborder_width\fP fields appropriately before it returns. The Intrinsics will take these new values and actually call \f(CWXtConfigureWidget()\fP to change the widget's window as appropriate. Some composite widgets may find it more convenient to call their internal layout procedure (if \f(CWXtCWQueryOnly\fP is not specified) from their \f(CWgeometry_manager()\fP method and actually configure the child themselves. In this case, they should return \f(CWXtGeometryDone\fP instead of \f(CWXtGeometryYes\fP. See the warning about this approach, however, in the "Background" section below. If the \f(CWgeometry_manager()\fP method returns \f(CWXtGeometryYes\fP or \f(CWXtGeometryDone\fP, it does not need to return any values in the \f(CIgeometry_return\fP argument. .LP If the \f(CWgeometry_manager()\fP cannot grant the request (because it asks for a position change when only size changes are allowed, for example) it can return \f(CWXtGeometryNo\fP and the child will remain at its current size. It may also return \f(CWXtGeometryNo\fP if the requested geometry is identical to the current geometry. .ne 2 When it returns \f(CWXtGeometryNo\fP, it does not need to return any values in the \f(CWgeometry_return\fP argument. .LP If the \f(CWgeometry_manager()\fP cannot satisfy the request exactly, but can come close (for example, if it can change the height but not the width, or can make the height larger but not as large as requested) it can return \f(CWXtGeometryAlmost\fP, and set the compromise geometry in \f(CWgeometry_return\fP. By returning \f(CWXtGeometryAlmost\fP, it is guaranteeing that it will return \f(CWXtGeometryYes\fP and make the change if the child requests the compromise geometry immediately. .LP The \f(CWgeometry_manager()\fP method is not chained. If a class does not define its own \f(CWgeometry_manager()\fP method, it can use \f(CWXtInheritGeometryManager\fP to inherit the method from its superclass. The \f(CWgeometry_manager\fP field of a widget should not be \f(CWNULL\fP unless the widget class is sure that none of its children will ever issue geometry requests. .LP See the "Background" section below for full details on this process. See \f(CWXtMakeGeometryRequest\fP(1) for the child widget's perspective on geometry negotiation. .\" .SH "Usage" A child will usually initiate a geometry request in response to a change in one of its resources. When a Label widget gets a new string, for example, it may need to grow to accommodate that label. If its parent refuses to grant the resize request, the label may be truncated. Note that the \f(CWgeometry_manager()\fP method is not involved in the geometry negotiations that percolate down from above when a window is resized or when a widget is first managed. .LP In order to determine whether it can grant a geometry request, some widgets will have to make a geometry request of their own to their parent, and the request may percolate up the chain. With \f(CWXtCWQueryOnly\fP requests and \f(CWXtGeometryAlmost\fP replies, the geometry negotiation process can become quite complicated. In practice, however, most widgets do not perform geometry management nearly so sophisticated (and confusing) as the mechanism allows. .LP Some composite widgets will have a resource that controls whether they will allow any child to resize itself. If this resource disallows geometry changes, the geometry manager will always return \f(CWXtGeometryNo\fP. Constraint widgets can use constraint resources to provide this functionality on a child-by-child basis. Some widgets (the Xaw Label, for example) have a resource that controls whether they will ever make a resize request to their parent. All these mechanisms simplify the task of the geometry manager procedure. .LP Some composite widgets will have a liberal policy towards geometry requests. The Xaw Tree widget, for example, will allow any child's resize request without actually testing whether it will have to become larger and whether its parent will allow that. If the child's resize request causes the Tree to request a resize, and the Tree is not allowed to resize, then some of the children of the Tree will probably not be displayed correctly. The philosophy here is that the application developer can take whatever steps are required to ensure that this situation never arises. .LP The best approach to geometry management is probably to make do with the simplest \f(CWgeometry_manager()\fP method possible. The geometry management mechanism provided by the Intrinsics is so general (and so poorly understood) that there are various incompatible styles of geometry management that are supported. A geometry manager can be almost as complicated as you choose to make it, but most of the sophisticated situations it is designed to handle will rarely occur in practice. Keep in mind that many children widgets will not respond in any sophisticated way to \f(CWXtGeometryAlmost\fP replies, and that the grandparent widget may also not be sophisticated enough to provide useful return values to a complex geometry manager. .\" .SH "Example" The procedure below is the \f(CWgeometry_manager()\fP method Xaw Tree widget. It is a permissive geometry manager which will allow resize requests, but never position requests. It never returns \f(CWXtGeometryAlmost\fP. This method may be a little too restrictive: if a programmer requests a size and position change for a child in a single call to \f(CWXtSetValues()\fP, \f(CWXtSetValues()\fP will call \f(CWXtMakeGeometryRequest()\fP for the child, but the Tree widget will deny the size change request because it is accompanied by the position change request. .LP The geometry manager for the Xaw Form widget is not shown here, but it is worth looking at. It checks a constraint resource for each child to determine if it is resizable. It also disallows position requests and never returns \f(CWXtGeometryAlmost\fP. .LP The geometry manager for the Xaw Paned widget may also be worth some study. It is a more sophisticated manager that does return \f(CWXtGeometryAlmost\fP sometimes. This is a more complex method because the Paned widget constrains its children's widths to all be the same size. .Ps /* ARGSUSED */ static XtGeometryResult GeometryManager (w, request, reply) Widget w; XtWidgetGeometry *request; XtWidgetGeometry *reply; { TreeWidget tw = (TreeWidget) w->core.parent; /* * No position changes allowed!. */ if ((request->request_mode & CWX && request->x!=w->core.x) (request->request_mode & CWY && request->y!=w->core.y)) return (XtGeometryNo); /* * Allow all resize requests. */ if (request->request_mode & CWWidth) w->core.width = request->width; if (request->request_mode & CWHeight) w->core.height = request->height; if (request->request_mode & CWBorderWidth) w->core.border_width = request->border_width; if (tw->tree.auto_reconfigure) layout_tree (tw, FALSE); return (XtGeometryYes); } .Pe .\" .Nd 4 .SH "Background" A bit set to zero in the \f(CIrequest\fP \f(CWrequest_mode\fP field means that the child widget does not care about the value of the corresponding field. Then, the geometry manager can change it as it wishes. A bit set to 1 means that the child wants that geometry element changed to the value in the corresponding field. .LP If the geometry manager can satisfy all changes requested, and if \f(CWXtCWQueryOnly\fP is not specified, it updates the widget's \f(CWx\fP, \f(CWy\fP, \f(CWwidth\fP, \f(CWheight\fP, and \f(CWborder_width\fP values appropriately. Then, it returns \f(CWXtGeometryYes\fP, and the value of the \f(CIgeometry_return\fP argument is undefined. The widget's window is moved and resized automatically by \f(CWXtMakeGeometryRequest()\fP. .LP Homogeneous Composite widgets often find it convenient to treat the widget making the request the same as any other widget, possibly reconfiguring it using \f(CWXtConfigureWidget()\fP or \f(CWXtResizeWidget()\fP as part of its layout process, unless \f(CWXtCWQueryOnly\fP is specified. If it does this, it should return \f(CWXtGeometryDone\fP to inform \f(CWXtMakeGeometryRequest()\fP that it does not need to do the configuration itself. .LP To remain compatible with layout techniques used in older widgets (before \f(CWXtGeometryDone\fP was added to the Intrinsics), a geometry manager should avoid using \f(CWXtResizeWidget()\fP or \f(CWXtConfigureWidget()\fP on the child making the request because the layout process of the child may be in an intermediate state in which it is not prepared to handle a call to its resize procedure. A self-contained widget set may choose this alternative geometry management scheme, however, provided that it clearly warns widget developers of the compatibility consequences. .LP Although \f(CWXtMakeGeometryRequest()\fP resizes the widget's window (if the geometry manager returns \f(CWXtGeometryYes\fP), it does not call the widget class's resize procedure. The requesting widget must perform whatever resizing calculations are needed explicitly. .LP If the geometry manager chooses to disallow the request, the widget cannot change its geometry. The value of the \f(CIgeometry_return\fP argument is undefined, and the geometry manager returns \f(CWXtGeometryNo\fP. .LP Sometimes the geometry manager cannot satisfy the request exactly, but it may be able to satisfy a similar request. That is, it could satisfy only a subset of the requests (for example, size but not position) or a lesser request (for example, it cannot make the child as big as the request but it can make the child bigger than its current size). In such cases, the geometry manager fills in \f(CIgeometry_return\fP with the actual changes it is willing to make, including an appropriate mask, and returns \f(CWXtGeometryAlmost\fP. .LP If a bit in \f(CWgeometry_return\->request_mode\fP is 0, the geometry manager does not change the corresponding value if the \f(CIgeometry_return\fP argument is used immediately in a new request. If a bit is 1, the geometry manager does change that element to the corresponding value in \f(CIgeometry_return\fP. More bits may be set in \f(CIgeometry_return\f(CW->request_mode\fR than in the original request if the geometry manager intends to change other fields should the child accept the compromise. .LP .Nd 8 When \f(CWXtGeometryAlmost\fP is returned, the widget must decide if the compromise suggested in \f(CIgeometry_return\fP is acceptable. If it is, the widget must not change its geometry directly; rather, it must make another call to \f(CWXtMakeGeometryRequest()\fP. .LP If the next geometry request from this child uses the \f(CIgeometry_return\fP box filled in by an \f(CWXtGeometryAlmost\fP return, and if there have been no intervening geometry requests on either its parent or any of its other children, the geometry manager must grant the request, if possible. That is, if the child asks immediately with the returned geometry, it should get an answer of \f(CWXtGeometryYes\fP. However, the user's window manager may affect the final outcome. .LP To return an \f(CWXtGeometryYes\fP, the geometry manager frequently rearranges the position of other managed children by calling \f(CWXtMoveWidget()\fP. However, a few geometry managers may sometimes change the size of other managed children by calling \f(CWXtResizeWidget()\fP or \f(CWXtConfigureWidget()\fP. If \f(CWXtCWQueryOnly\fP is specified, the geometry manager must return how it would react to this geometry request without actually moving or resizing any widgets. .LP Geometry managers must not assume that the \f(CIrequest\fP and \f(CIgeometry_return\fP arguments point to independent storage. The caller is permitted to use the same field for both, and the geometry manager must allocate its own temporary storage, if necessary. .LP Sometimes a geometry manager cannot respond to a geometry request from a child without first making a geometry request to the widget's own parent (the original requestor's grandparent). If the request to the grandparent would allow the parent to satisfy the original request, the geometry manager can make the intermediate geometry request as if it were the originator. On the other hand, if the geometry manager already has determined that the original request cannot be completely satisfied (for example, if it always denies position changes), it needs to tell the grandparent to respond to the intermediate request without actually changing the geometry because it does not know if the child will accept the compromise. To accomplish this, the geometry manager uses \f(CWXtCWQueryOnly\fP in the intermediate request. .LP When \f(CWXtCWQueryOnly\fP is used, the geometry manager needs to cache enough information to exactly reconstruct the intermediate request. If the grandparent's response to the intermediate query was \f(CWXtGeometryAlmost\fP, the geometry manager needs to cache the entire reply geometry in the event the child accepts the parent's compromise. .LP If the grandparent's response was \f(CWXtGeometryAlmost\fP, it may also be necessary to cache the entire reply geometry from the grandparent when \f(CWXtCWQueryOnly\fP is not used. If the geometry manager is still able to satisfy the original request, it may immediately accept the grandparent's compromise and then act on the child's request. If the grandparent's compromise geometry is insufficient to allow the child's request and if the geometry manager is willing to offer a different compromise to the child, the grandparent's compromise should not be accepted until the child has accepted the new compromise. .LP Note that a compromise geometry returned with \f(CWXtGeometryAlmost\fP is guaranteed only for the next call to the same widget; therefore, a cache of size 1 is sufficient. .\" .Nd 8 .SH "Structures" The return codes from geometry managers are: .XX "XtGeometryResult" .Ps .ta 4.5n 2i typedef enum _XtGeometryResult { XtGeometryYes, /* Request accepted */ XtGeometryNo, /* Request denied */ XtGeometryAlmost,/* Request denied but willing to take reply */ XtGeometryDone /* Request accepted and performed */ } XtGeometryResult; .Pe The \f(CWXtWidgetGeometry\fR structure is similar to but not identical to the corresponding Xlib structure: .XX "XtGeometryMask" .Ps .ta 4.5n 2i typedef unsigned long XtGeometryMask; .sp .5 typedef struct { XtGeometryMask request_mode; Position x, y; Dimension width, height; Dimension border_width; Widget sibling; int stack_mode; } XtWidgetGeometry; .Pe .LP \f(CWXtMakeGeometryRequest()\fR, like the Xlib \f(CWXConfigureWindow()\fR function, uses \f(CWrequest_mode\fR to determine which fields in the \f(CWXtWidgetGeometry\fR structure you want to specify. The \f(CWrequest_mode\fR definitions are from <\fIX11/X.h\fP>: .Ps .ta .75i 2i #define CWX (1<<0) #define CWY (1<<1) #define CWWidth (1<<2) #define CWHeight (1<<3) #define CWBorderWidth (1<<4) #define CWSibling (1<<5) #define CWStackMode (1<<6) .Pe The Xt Intrinsics also support the following value: .Ps .ta .75i 2i #define XtCWQueryOnly (1<<7) .Pe \f(CWXtCWQueryOnly\fR indicates that the corresponding geometry request is only a query as to what would happen if this geometry request were made and that no widgets should actually be changed. .LP .Nd 5 The \f(CWstack_mode\fR definitions are from <\fIX11/X.h\fP>: .Ps .ta .75i 2i #define Above 0 #define Below 1 #define TopIf 2 #define BottomIf 3 #define Opposite 4 .Pe The Intrinsics also support the following value: .Ps .ta .75i 2i #define XtSMDontChange 5 .Pe .Nd 6 \f(CWXtSMDontChange\fR indicates that the widget wants its current stacking order preserved. For precise definitions of \f(CWAbove\fR, \f(CWBelow\fR, \f(CWTopIf\fR, \f(CWBottomIf\fR, and \f(CWOpposite\fR, see the reference page for \f(CWXConfigureWindow()\fP in \*(V2. .SH "See Also" .na \s-1\fIXtConfigureWidget\fR\s+1\*(s1, \s-1\fIXtMakeResizeRequest\fR\s+1\*(s1, \s-1\fIXtMoveWidget\fR\s+1\*(s1, \s-1\fIXtResizeWidget\fR\s+1\*(s1, .br \s-1\fIComposite\fR\s+1\*(s3, \s-1\fIConstraint\fR\s+1\*(s3. .ad .\"last line comment .\" $Header: secure_rpc.3c,v 74.1 95/05/10 21:12:12 ssa Exp $ .TA s .TH secure_rpc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME secure_rpc(), authdes_create(), authdes_getucred(), get_myaddress(), getnetname(), host2netname(), key_decryptsession(), key_encryptsession(), key_gendes(), key_setsecret(), netname2host(), netname2user(), user2netname() \- library routines for secure remote procedure calls .SH DESCRIPTION .LP .C RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .LP .C RPC allows various authentication flavors. The .B authdes_getucred() and .B authdes_create() routines implement the .B DES authentication flavor. See .BR rpc_clnt_auth (3C) for routines relating to the .B AUTH_NONE and .B AUTH_UNIX authentication types. .IP Note: Both the client and server should have their keys in the .BR publickey (5) database. Also, the keyserver daemon .BR keyserv (1M) must be running on both the client and server hosts for the .B DES authentication system to work. .SS Routines .LP The following routines require that the header .BR be included. .PP The .B AUTH data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "AUTH *" .C "authdes_create(netname, window, syncaddr, deskeyp)" .C "char *netname;" .C "unsigned window;" .C "struct sockaddr_in *syncaddr;" .C "des_block *deskeyp;" .fi .IP .B authdes_create() is an interface to the .B RPC secure authentication system, known as .B DES authentication. .IP Used on the client side, .B authdes_create() returns an authentication handle that enables the use of the secure authentication system. The first parameter .I netname is the network name of the owner of the server process. This field usually represents a .I host derived from the utility routine .BR host2netname() , but could also represent a user name using .BR user2netname() . The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third parameter .I syncaddr is optional. If it is .B NULL, then the authentication system will assume that the local clock is always in sync with the server's clock, and will not attempt to synchronize with the server. If an address is supplied then the system will use it for consulting the remote time service whenever resynchronization is required. This parameter is usually the address of the .B RPC server itself. The final parameter .I deskeyp is also optional. If it is .B NULL, then the authentication system will generate a random .B DES key to be used for the encryption of credentials. If .I deskeyp is supplied then it is used instead. .PP .nf .C "int" .C "authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)" .C "struct authdes_cred *adc;" .C "short *uidp, *gidp, *gidlenp;" .C "int *gidlistp;" .fi .IP .BR authdes_getucred() , is a .B DES authentication routine used by the server for converting a .B DES credential, which is operating system independent, into a .B UNIX credential. .I uidp points to the user .B ID of the user associated with .IR adc ; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. .br .ne 5 .IP This routine differs from the utility routine .B netname2user() in that .B authdes_getucred() pulls its information from a cache, and does not have to do a .B NIS name service lookup every time it is called to get its information. Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "void" .C "get_myaddress(addr)" .C "struct sockaddr_in *addr;" .fi .IP Return the machine's .B IP address in .IR addr. The port number is always set to .BR htons(PMAPPORT) . .PP .nf .C "int" .C "getnetname(netname)" .C "char netname[MAXNETNAMELEN];" .fi .IP Return the unique, operating-system independent netname of the caller in the fixed-length array .IR netname . Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "int" .C "host2netname(netname, host, domain)" .C "char netname[MAXNETNAMELEN];" .C "char *host;" .C "char *domain;" .fi .IP Convert from a domain-specific hostname to an operating-system independent netname. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . This routine should be used if the owner of the server process is the machine that is, the user with effective user .B ID zero. Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2host() . .PP .nf .C "int" .C "key_decryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP An interface routine to the keyserver daemon, which is associated with .B RPC's secure authentication system ( .B DES authentication). User programs rarely need to call it, or its associated routines .BR key_encryptsession() , .B key_gendes() and .BR key_setsecret() . System commands such as .B login and the .B RPC library are the main clients of these four routines. .IP .B key_decryptsession() takes the netname of a server and a .B DES key, and decrypts the key by using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_encryptsession() . .PP .nf .C "int" .C "key_encryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It takes the netname of the server and a .B DES key, and encrypts it using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_decryptsession() . .PP .nf .C "int" .C "key_gendes(deskeyp)" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It is used to ask the keyserver for a secure conversation key. Choosing one at random is usually not good enough, because the common ways of choosing random numbers, such as using the current time, are very easy to guess. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "key_setsecret(keyp)" .C "char *keyp;" .fi .IP A keyserver interface routine. It is used to set the secret key for the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "netname2host(netname, host, hostlen)" .C "char *netname;" .C "char *host;" .C "int hostlen;" .fi .IP Convert an operating-system independent netname to a domain-specific hostname. .I hostlen specifies the size of the array pointed to by .I host. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR host2netname() . .PP .nf .C "int" .C "netname2user(netname, uidp, gidp, gidlenp, gidlistp)" .C "char *netname;" .C "int *uidp, *gidp, *gidlenp, *gidlistp;" .fi .IP Convert an operating-system independent netname to a domain-specific user .B ID. .I uidp points to the user .B ID of the user; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR user2netname() . .PP .nf .C "int" .C "user2netname(netname, uid, domain)" .C "char netname[MAXNETNAMELEN];" .C "int uid;" .C "char *domain;" .fi .IP Convert a domain-specific username to an operating-system independent netname. .I uid is the user .B ID of the owner of the server process. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2user() . .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR login (1), .BR chkey (1), .BR rpc (3C), .BR rpc_clnt_auth (3C), .BR publickey (4), .BR keyserv (1M), .BR newkey (1M) .\" toc@\f3secure_rpc(3C)\f1:\0\0\f4authdes_create()\fP, \f4authdes_getucred()\fP, \f4get_myaddress()\fP, \n\f4getnetaddress()\fP, \f4getnetname()\fP, \f4host2netname()\fP, \n\f4key_decryptsession()\fP, \f4key_encryptsession()\fP, \f4key_gendes()\fP, \n\f4key_setsecret()\fP, \f4netname2host()\fP, \f4netname2user()\fP, \n\f4user2netname()\fP@@@library routines for secure remote procedure calls .\" toc@\f4secure_rpc()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_create()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_getucred()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4get_myaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4host2netname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_decryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_encryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_gendes()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_setsecret()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2host()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2user()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4user2netname()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" index@library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4secure_rpc()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_create()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_getucred()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4get_myaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4host2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_decryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_encryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_gendes()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_setsecret()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2host()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2user()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4user2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" links@secure_rpc.3c authdes_create.3c .\" links@secure_rpc.3c authdes_getucred.3c .\" links@secure_rpc.3c get_myaddress.3c .\" links@secure_rpc.3c getnetaddress.3c .\" links@secure_rpc.3c getnetname.3c .\" links@secure_rpc.3c host2netname.3c .\" links@secure_rpc.3c key_decryptsession.3c .\" links@secure_rpc.3c key_encryptsession.3c .\" links@secure_rpc.3c key_gendes.3c .\" links@secure_rpc.3c key_setsecret.3c .\" links@secure_rpc.3c netname2host.3c .\" links@secure_rpc.3c netname2user.3c .\" links@secure_rpc.3c user2netname.3c .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "get_values_hook" "Xt \- Intrinsics Methods" .SH "Name" .Na get_values_hook \- Object class method for obtaining values of resources that do not appear in the resource list. .Nz .XS "methods, get_values_hook" .XS "get_values_hook" .SH "Synopsis" .Sy typedef void (*XtArgsProc)(Widget, ArgList, Cardinal *); .As Widget \f(CIw\fP; ArgList \f(CIargs\fP; Cardinal *\f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget or object that is having its resources queried. .IP \f(CIargs\fP 1i Specifies the argument list that was passed to \f(CWXtGetValues()\fR. .IP \f(CInum_args\fP 1i Specifies the number of arguments in the argument list. .\" .SH "Description" The \f(CWget_values_hook()\fP method is registered on the \f(CWget_values_hook\fP field of the Object, RectObj, or Core class part structure, and is called by \f(CWXtGetValues()\fP to give the widget a chance to supply the value of any resources that do not appear in the widget's resource list (by calling \f(CWXtGetSubvalues()\fP on a subpart, for example) or to modify any of the returned values. .LP The \f(CWget_values_hook()\fP method is chained in superclass-to-subclass order, and cannot be inherited. Classes that do not need a \f(CWget_value_hook()\fP method should specify \f(CWNULL\fP in the \f(CWget_values_hook\fP field of their class structure. .LP See \f(CWXtGetValues\fP(1) for more information on when this method is invoked. .\" .SH "Usage" If a widget or object has subparts with resources that do not appear in the resource list of the object itself, it can use the \f(CWget_values_hook()\fP method to call \f(CWXtGetSubvalues()\fP passing a pointer to the subpart, the subpart resource list, and the \f(CIargs\fP and \f(CInum_args\fP argument list. Using this technique, the application programmer will be able to query the value of subpart resources as if they were normal widget resources. .LP Note that since the Object class was added in Release 4, it is often easier to use objects rather than subparts, because objects get more automatic resource handling by the Intrinsics than subparts do. A \f(CWget_values_hook()\fP procedure is not limited to calling \f(CWXtGetSubvalues()\fP; it can call \f(CWXtGetValues()\fP on a widget or object, as shown in the examples below. When using objects rather than subparts, it is also possible to give the application programmer direct control over creating those objects. If the programmer keeps a pointer to the created object, then she can directly set and query the resource values of the object, and no \f(CWget_values_hook()\fP is necessary in the parent. .LP The \f(CWget_values_hook()\fP method can also be used to modify the resource values in \f(CIargs\fP that would otherwise be returned to the user. A widget that displays a string, for example, might want to return a copy of that string to the programmer rather than the string itself, so that if the programmer modifies the string, the widget will not be affected. Widgets that use the \f(CWget_values_hook()\fP method in this way should be sure to document which resources are copied in this way and must be freed by the user. (None of the Intrinsics widgets nor the Xaw widgets do this.) .LP Note that the \f(CWget_values_hook()\fP method is not obsolete as are the other hook methods, \f(CWinitialize_hook()\fP and \f(CWset_values_hook()\fP. .\" .XX "methods: get_values_hook; example" .SH "Example" The two procedures below are the \f(CWget_values_hook()\fP methods of the Xaw Dialog and Xaw Text widget classes. Note that both use \f(CWXtGetValues()\fP to obtain resources of a child widget or object, which they "export" as one of their own resources. .LP The Dialog method checks the incoming argument list for a resource named \f(CWXtNvalue\fP, and only queries the child for that single resource. The Text method simply passes the entire argument list in \f(CWXtGetValues()\fP calls to two different child objects. This method assumes that the Text widget and its two children objects do not have any resources by the same name, so there is not potential for name conflicts. The Text widget controls the types of its subobjects, so this is a reasonable assumption. Since all objects have an \f(CWXtNdestroyCallback\fP resource, however, if you were to query the value of this resource for the Text widget, you would get the callback list for one of its internal objects instead. (This is not a practical problem because the callback list is in an internal compiled form and should not be queried anyway.) .Ps static void GetValuesHook(w, args, num_args) Widget w; ArgList args; Cardinal * num_args; { Arg a[1]; String s; DialogWidget src = (DialogWidget) w; register int i; for (i=0; i < *num_args; i++) if (streq(args[i].name, XtNvalue)) { XtSetArg(a[0], XtNstring, &s); XtGetValues(src->dialog.valueW, a, 1); *((char **) args[i].value) = s; } } static void GetValuesHook(w, args, num_args) Widget w; ArgList args; Cardinal * num_args; { XtGetValues( ((TextWidget) w)->text.source, args, *num_args ); XtGetValues( ((TextWidget) w)->text.sink, args, *num_args ); } .Pe .SH "See Also" .na .br \s-1\fIXtGetSubvalues\fR\s+1\*(s1, \s-1\fIXtGetValues\fR\s+1\*(s1, .br \s-1\fICore\fR\s+1\*(s3. .ad .XE "methods, get_values_hook" .XE "get_values_hook" .\"last line comment .\" $Header: get_wch.3x,v 76.2 95/08/01 10:38:24 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH get_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME get_wch, mvget_wch, mvwget_wch, wget_wch \(em get a wide character from a terminal .SH SYNOPSIS .C "#include " .P .C "int get_wch(wint_t *\f2ch\fP);" .P .C "int mvget_wch(int \f2y\fP, int \f2x\fP, wint_t *\f2ch\fP);" .P .C "int mvwget_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2ch\fP);" .P .C "int wget_wch(WINDOW *\f2win\fP, wint_t *\f2ch\fP);" .SH DESCRIPTION These functions read a character from the terminal associated with the current or specified window. If .Fn keypad is enabled, these functions respond to the pressing of a function key by setting the object pointed to by .I ch to the corresponding KEY_ value defined in .Hd curses.h and returning KEY_CODE_YES. .P Processing of terminal input is subject to the general rules described in \f3Input Processing\f1 in curses_intro. .P If echoing is enabled, then the character is echoed as though it were provided as an input argument to .CR ins_wch() , except for the following characters: .PP .TS tab(@); lw(2.00i)@lw(3i). T{ , and the current erase character: T}@T{ The input is interpreted as specified in .CR specialchars and then the character at the resulting cursor position is deleted as though .Fn delch were called, except that if the cursor was originally in the first column of the line, then the user is alerted as though .Fn beep were called. T} .P Function keys@T{ The user is alerted as though .Fn beep were called. Information concerning the function keys is not returned to the caller. T} .TE .P If the current or specified window is not a pad, and it has been moved or modified since the last refresh operation, then it will be refreshed before another character is read. .SH "RETURN VALUE" When these functions successfully report the pressing of a function key, they return KEY_CODE_YES. When they successfully report a wide character, they return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Applications should not define the escape key by itself as a single-character function. .P When using these functions, .Fn nocbreak mode and .Fn echo mode should not be used at the same time. Depending on the state of the terminal when each character is typed, the application may produce undesirable results. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, beep(), cbreak(), ins_wch(), keypad(), move(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3get_wch(3X)\f1:\0\0\f4get_wch()\f1, \f4mvget_wch()\f1, \f4mvwget_wch()\f1, \f4wget_wch\f1()\f1@@@get a wide character from a terminal .\" toc@\f4mvget_wch()\f1: get a wide character from a terminal@@@see \f3get_wch(3X)\f1 .\" toc@\f4mvwget_wch()\f1: get a wide character from a terminal@@@see \f3get_wch(3X)\f1 .\" toc@\f4wget_wch()\f1: get a wide character from a terminal@@@see \f3get_wch(3X)\f1 .\" .\" index@\f4get_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f4mvget_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f4mvwget_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f4wget_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f1get a wide character from a terminal@@@\f3get_wch(3X)\f1 .\" index@\f1wide character, get from a terminal@@@\f3get_wch(3X)\f1 .\" index@\f1terminal, get a wide character from@@@\f3get_wch(3X)\f1 .\" index@\f1character, get a wide character from a terminal@@@\f3get_wch(3X)\f1 .\" .\" links@get_wch.3x mvget_wch.3x .\" links@get_wch.3x mvwget_wch.3x .\" links@get_wch.3x wget_wch.3x .\" .\" fileset_database@get_wch.3x CURS-ENG-A-MAN .\" $Header: getn_wstr.3x,v 76.2 95/08/01 10:52:41 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getn_wstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getn_wstr, get_wstr, mvgetn_wstr, mvget_wstr, mvwgetn_wstr, mvwget_wstr, wgetn_wstr, wget_wstr \(em get an array of wide characters and function key codes from a terminal .SH SYNOPSIS .C "#include " .P .C "int getn_wstr(wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int get_wstr(wint_t *\f2wstr\fP);" .P .C "int mvgetn_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvget_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int mvwgetn_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwget_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int wgetn_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int wget_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP);" .SH DESCRIPTION The effect of .Fn get_wstr is as though a series of calls to .Fn get_wch were made, until a newline character, end-of-line character, or end-of-file character is processed. An end-of-file character is represented by WEOF, as defined in .CR . A newline or end-of-line is represented as its .CR wchar_t value. In all instances, the end of the string is terminated by a null .CR wchar_t . The resulting values are placed in the area pointed to by \f2wstr\f1. .P The user's erase and kill characters are interpreted and affect the sequence of characters returned. .P The effect of .Fn wget_wstr is as though a series of calls to .Fn wget_wch were made. .P The effect of .Fn mvget_wstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_wstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. The effect of .Fn mvget_nwstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_nwstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. .P The .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr and .Fn wgetn_wstr functions read at most \f2n\f1 characters, letting the application prevent overflow of the input buffer. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR get_wstr() , .CR mvget_wstr() , .Fn mvwget_wstr or .Fn wget_wstr causes undefined results. The use of .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr or .Fn wgetn_wstr , respectively, is recommended. .P These functions cannot return KEY_ values as there is no way to distinguish a KEY_ value from a valid .B wchar_t value. .SH "SEE ALSO" get_wch(), getstr(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Chapter 9,\f3General Terminal Interface\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getn_wstr(3X)\f1:\0\0\f4getn_wstr()\f1, \f4get_wstr()\f1, \f4mvgetn_wstr()\f1, \f4mvget_wstr()\f1, \f4mvwgetn_wstr()\f1, \n\f4mvwget_wstr()\f1, \f4wgetn_wstr()\f1, \f4wget_wstr()\f1\n@@@get an array of wide characters and function key codes from a terminal .\" toc@\f4get_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" .\" index@\f4getn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4get_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1array of wide characters and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1wide characters, an array of, and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1terminal, get an array of wide characters and function key codes@@@\f3getn_wstr(3X)\f1 .\" .\" links@getn_wstr.3x get_wstr.3x .\" links@getn_wstr.3x mvgetn_wstr.3x .\" links@getn_wstr.3x mvget_wstr.3x .\" links@getn_wstr.3x mvwgetn_wstr.3x .\" links@getn_wstr.3x mvwget_wstr.3x .\" links@getn_wstr.3x wgetn_wstr.3x .\" links@getn_wstr.3x wget_wstr.3x .\" .\" fileset_database@getn_wstr.3x CURS-ENG-A-MAN .\" $Header: getbegyx.3x,v 76.2 95/08/01 10:43:31 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getbegyx 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getbegyx, getmaxyx, getparyx \(em get additional cursor and window coordinates .SH SYNOPSIS .C "#include " .P .C "void getbegyx(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "void getmaxyx(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "void getparyx(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .SH DESCRIPTION .P The .Fn getbegyx macro stores the absolute screen coordinates of the specified window's origin in \f2y\f1 and \f2x\f1. .P The .Fn getmaxyx macro stores the number of rows of the specified window in \f2y\f1 and stores the window's number of columns in \f2x\f1. .P The .Fn getparyx macro, if the specified window is a subwindow, stores in \f2y\f1 and \f2x\f1 the coordinates of the window's origin relative to its parent window. Otherwise, \(mi1 is stored in \f2y\f1 and \f2x\f1. .SH "RETURN VALUE" No return values are defined. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These interfaces are macros and `\f4&\f1' cannot be used before the \f2y\f1 and \f2x\f1 arguments. .SH "SEE ALSO" getyx(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getbegyx(3X)\f1:\0\0\f4getbegyx()\f1, \f4getmaxyx()\f1, \f4getparyx()\f1@@@get additional cursor and window coordinates .\" toc@\f4getmaxyx()\f1: get additional cursor and window coordinates@@@see \f3getbegyx(3X)\f1 .\" toc@\f4getparyx()\f1: get additional cursor and window coordinates@@@see \f3getbegyx(3X)\f1 .\" .\" index@\f4getbegyx()\f1 \- get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f4getmaxyx()\f1 \- get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f4getparyx()\f1 \- get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f1get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f1coordinates, get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f1additional cursor and window coordinates, get @@@\f3getbegyx(3X)\f1 .\" index@\f1cursor and window coordinates, get additional@@@\f3getbegyx(3X)\f1 .\" index@\f1window and cursor coordinates, get additional@@@\f3getbegyx(3X)\f1 .\" .\" links@getbegyx.3x getmaxyx.3x .\" links@getbegyx.3x getparyx.3x .\" .\" fileset_database@getbegyx.3x CURS-ENG-A-MAN .\" $Header: bkgd.3x,v 76.2 95/07/31 17:03:01 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH bkgd 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bkgd, bkgdset, getbkgd, wbkgd, wbkgdset \(em set or get background character and rendition using a single-byte character .SH SYNOPSIS .C "#include " .P .C "int bkgd(chtype \f2ch\fP);" .P .C "void bkgdset(chtype \f2ch\fP);" .P .C "chtype getbkgd(WINDOW *\f2win\fP);" .P .C "int wbkgd(WINDOW *\f2win\fP, chtype \f2ch\fP);" .P .C "void wbkgdset(WINDOW *\f2win\fP, chtype \f2ch\fP);" .SH DESCRIPTION The .Fn bkgdset and .Fn wbkgdset functions set the background property of the current or specified window based on the information in \f2ch\f1. If \f2ch\f1 refers to a multi-column character, the results are undefined. .P The .Fn bkgd and .Fn wbkgd functions set the background property of the current or specified window and then apply this setting to every character position in that window: .RS .TP 3 .C \(bu The rendition of every character on the screen is changed to the new background rendition. .TP .C \(bu Wherever the former background character appears, it is changed to the new background character. .RE .P The .Fn getbkgd function extracts the specified window's background character and rendition. .SH "RETURN VALUE" Upon successful completion, .Fn bkgd and .Fn wbkgd return OK. Otherwise, they return ERR. .P The .Fn bkgdset and .Fn wbkgdset functions do not return a value. .P Upon successful completion, .Fn getbkgd returns the specified window's background character and rendition. Otherwise, it returns (\f3chtype\fP)ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" \f3Rendition\f1 in curses_intro, . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3bkgd(3X)\f1:\0\0\f4bkgd()\f1, \f4bkgdset()\f1, \f4getbkgd()\f1, \f4wbkgd()\f1, \f4wbkgdset()\f1\n@@@set or get background character and rendition using a single-byte character .\" toc@\f4bkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4bkgdset()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4getbkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4wbkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4wbkgdset()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" .\" index@\f4bkgd()\f1 \- set or get background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1set or get background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1get or set background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1single-byte character, set or get background character or rendition, using@@@\f3bkgd(3X)\f1 .\" .\" links@bkgd.3x bkgdset.3x .\" links@bkgd.3x getbkgd.3x .\" links@bkgd.3x wbkgd.3x .\" links@bkgd.3x wbkgdset.3x .\" .\" fileset_database@bkgd.3x CURS-ENG-A-MAN .\" $Header: bkgrnd.3x,v 76.2 95/07/31 17:05:26 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH bkgrnd 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bkgrnd, bkgrndset, getbkgrnd, wbkgrnd, wbkgrndset, wgetbkgrnd \(em set or get background character and rendition using a complex character .SH SYNOPSIS .C "#include " .P .C "int bkgrnd(cchar_t *const \f2wch\fP);" .P .C "void bkgrndset(cchar_t *const \f2wch\fP);" .P .C "int getbkgrnd(cchar_t *\f2wch\fP);" .P .C "int wbkgrnd(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "void wbkgrndset(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "int wgetbkgrnd(WINDOW *\f2win\fP, cchar_t *\f2wch\fP);" .SH DESCRIPTION The .Fn bkgrndset and .Fn wbkgrndset functions set the background property of the current or specified window based on the information in \f2wch\f1. .P The .Fn bkgrnd and .Fn wbkgrnd functions set the background property of the current or specified window and then apply this setting to every character position in that window: .RS .TP 3 .C \(bu The rendition of every character on the screen is changed to the new background rendition. .TP .C \(bu Wherever the former background character appears, it is changed to the new background character. .RE .P If \f2wch\f1 refers to a non-spacing complex character for .CR bkgrnd() , .CR bkgrndset() , .Fn wbkgrnd and .CR wbkgrndset() , then \f2wch\f1 is added to the existing spacing complex character that is the background character. If \f2wch\f1 refers to a multi-column character, the results are unspecified. .P The .Fn getbkgrnd and .Fn wgetbkgrnd functions store, into the area pointed to by \f2wch\fP, the value of the window's background character and rendition. .SH "RETURN VALUE" The .Fn bkgrndset and .Fn wbkgrndset functions do not return a value. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Rendition\f1 in curses_intro, .Hd curses.h .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3bkgrnd(3X)\f1:\0\0\f4bkgrnd()\f1, \f4bkgrndset()\f1, \f4getbkgrnd()\f1, \f4wbkgrnd()\f1, \f4wbkgrndset()\f1, \f4wgetbkgrnd()\f1\n@@@set or get background character and rendition using a complex character .\" toc@\f4bkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4bkgrndset()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4getbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wbkgrndset()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wgetbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" index@\f1set or get background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1get or set background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1complex character, set or get background character and rendition using@@@\f3bkgrnd(3X)\f1 .\" index@\f4bkgrnd()\f1 \- set or get background character and rendition using omplex character@@@\f3bkgrnd(3X)\f1 .\" .\" links@bkgrnd.3x bkgrndset.3x .\" links@bkgrnd.3x getbkgrnd.3x .\" links@bkgrnd.3x wbkgrnd.3x .\" links@bkgrnd.3x wbkgrndset.3x .\" links@bkgrnd.3x wgetbkgrnd.3x .\" .\" fileset_database@bkgrnd.3x CURS-ENG-A-MAN .\" $Header: getbootpent.3x,v 74.1 95/05/10 21:04:42 ssa Exp $ .TA g .TH getbootpent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" =========== .SH NAME getbootpent(), putbootpent(), setbootpent(), endbootpent(), parse_bp_htype(), parse_bp_haddr(), parse_bp_iaddr() \- get or put bootptab entry .\" =========== .SH SYNOPSIS .C "#include " .PP .C "int getbootpent (struct bootpent **bootpent);" .PP .C "int setbootpent (const char *path);" .PP .C "int endbootpent (void);" .PP .C "void putbootpent (" .nf .PD 0 .IP .C "const struct bootpent *bootpent," .C "const int numfields," .C "\s-1FILE\s0 * bootpfile" .PP .C ");" .PD .fi .PP .C "int parse_bp_htype (const char *source);" .PP .C "int parse_bp_haddr (" .nf .PD 0 .IP .C "char **source," .C "int htype," .C "unsigned char *result," .C "unsigned int *bytes" .PP .C ");" .PD .PP .C "int parse_bp_iaddr (" .nf .PD 0 .IP .C "char **source," .C "unsigned long *result" .PP .C ");" .PD .\" =========== .SS Remarks These functions reside in libdc.a, and are linked using the .C -ldc option to the .C ld or .C cc command. .\" =========== .SH DESCRIPTION These functions help a program read or modify a bootptab .RC ( bootpd control) file one entry at a time. .C getbootpent() locates an entry in the .C /etc/bootptab file, or an alternate file specified to .CR setbootpent() , and returns a pointer to an array of objects of type .C struct bootpent that breaks the entry into separate data fields with preceding, or embedded, comment (text) lines. .PP The .C bootpent structure is defined in .RC < bootpent.h > and includes the following members: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. int@bp_type;@/* BP_DATA, BP_COMMENT, BP_BLANK@*/ char@*bp_text;@/* one field or one comment line@*/ .TE .ft P .RE .PP The file also defines the following data type and constants: .IP .C "typedef struct bootpent *bpp_t;" .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. #define BP_NULLP@((bpp_t) 0) #define BP_SIZE@(sizeof (struct bootpent)) .TE .ft P .RE .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. #define MAXHADDRLEN@6 #define HTYPE_UNKNOWN@0@/* 0 bytes@*/ #define HTYPE_ETHERNET@1@/* 6 bytes@*/ #define HTYPE_EXP_ETHERNET@2@/* 1 byte@*/ #define HTYPE_AX25@3@/* 0 bytes@*/ #define HTYPE_PRONET@4@/* 1 byte@*/ #define HTYPE_CHAOS@5@/* 0 bytes@*/ #define HTYPE_IEEE802@6@/* 6 bytes@*/ #define HTYPE_ARCNET@7@/* 0 bytes@*/ #define MAXHTYPES@7 .TE .ft P .RE .PP The fields are described in the .RB `` "Field Definitions" '' section below. The purpose of each function is as follows. .TP 25 .C getbootpent() When first called, .C getbootpent() returns a pointer to, and the number of elements in, an array of .C bootpent structures. The array holds the first entry in the .C /etc/bootptab file (or from an alternate file specified by a call to .CR setbootpent() ), including leading, or embedded, comment lines. Each subsequent call returns a pointer to the next entry in the file so that successive calls can be used to search the entire file. .IP If no file is currently in memory, .C getbootpent() reads the .C /etc/bootptab file prior to doing its work. .IP The returned array exists in static space (malloc'd memory) overwritten by the next call (so previously returned pointers become invalid). However, each array element's .C bp_text pointer points to text in an in-memory copy of the file. This text is not altered by the next call (nor by changes to the file itself). Hence, it is possible to copy an entry's array in order to save it, as illustrated in .SM EXAMPLES below. The data remains valid until the next call of .C setbootpent() or .CR endbootpent(). .IP If there are comments after the last entry, they are returned as a separate entry with no data parts. .TP .C setbootpent() Opens the specified file for reading by .CR getbootpent() , reads a copy into memory, and closes the file (which as a side-effect releases any locks on the file; see .IR lockf (2)). If the given .I path is a null pointer or a null string, .C setbootpent() opens and reads .CR /etc/bootptab . .IP If the last file opened by .C setbootpent() (or implicitly by .CR getbootpent() ) was .CR /etc/bootptab , a subsequent call to .C setbootpent() for the same file rewinds the file to the beginning, making visible any recent changes to the file, without first requiring a call to .CR endbootpent() . .TP .C endbootpent() Frees the in-memory copy of the last file opened by .CR setbootpent() , or .CR getbootpent() . .TP .C putbootpent() Writes (to the current location in the stream specified by .IR bootpfile ) the .SM ASCII equivalent of the specified array of .C bootpent structures containing one file entry, and its leading, or embedded, comments (a total of .I numfields array elements). Entries are written in canonical form, meaning the entry name and each data field are on separate lines, data fields are preceded by one tab each, and each line except the last ends with ``:\e''. If .I numfields is less than or equal to zero, nothing is written. .TP .C parse_bp_htype() Converts a host address type from string to numeric format .RC ( HTYPE_ *) in the same manner as .CR bootpd . .TP .C parse_bp_haddr() Converts a host (hardware, link level) address from string to binary format in the same manner as .C bootpd given a host address type .RC ( HTYPE_ *). The calling program's .IR result , which must be an array containing at least .SM MAXHADDRLEN elements, is modified to hold the host address binary value, and .C bytes is modified to indicate the length in bytes of the resulting address. This can be used to compare two host addresses, independent of string representations. .I source is modified to point to the first char after the parsed address. .TP .C parse_bp_iaddr() Converts an internet address from string to binary format in the same manner as .CR bootpd . This can be used to compare two internet addresses, independent of string representations. The calling program's .I result is modified to hold the internet address binary value. .I source is modified to point to the first char after the parsed address. .\" ----------- .SS Field Definitions If .C bootpent.bp_type is .SM BP_DATA, the associated text is one field from the current entry, either the name field or one of the tag fields. Null tag fields (two colons in a row) are ignored, not returned. .PP If .C bootpent.bp_type is .SM BP_COMMENT or .SM BP_BLANK, the associated text is one comment line or blank line from the file, either preceding the current entry or embedded in it following a data line that was continued with a backslash. The text is exactly as it appears in the file, including any whitespace appearing on a blank line, and there is no trailing newline. .PP The returned array elements are in the same order as data fields and comment lines appear in the file. .PP Entry field strings are of the form: .IP .IR tag [\c .ift \f4\s+1@\s0\fP\c .ifn \f3@\fP\c .RC ]\|[ =\c .C """\c .I value\c .C """\c .RC ] .PP with surrounding whitespace, if any, removed (see .IR bootpd (1M) for the full description). Double quotes, and backslashes, can appear anywhere in the field strings. .PP Template entries (those referred to by other entries using .C tc fields) are not special. They can be managed like other entries. It is the calling program's responsibility to correctly manage the order of fields, .C tc fields, and ``@'' fields that override earlier field values. .\" =========== .SH RETURN VALUE .C getbootpent() returns the number of valid array elements (one or more) upon successful completion. At the end of the input file it returns zero. If it cannot open or close the file it returns \-1. If it encounters a memory allocation or map error, or a read error, it returns \-2. .PP .C setbootpent() returns zero if successful opening and reading the specified or default file. If it cannot open or close the file it returns \-1. If it encounters a memory allocation or map error or a read error it returns \-2. .PP .C endbootpent() returns zero if successful freeing the memory for the current open file. If there is no current file it returns \-1. If it cannot free the memory for the current file it returns \-2. .PP .C putbootpent() returns zero if successful writing an entry to the specified file, with the .C ferror() indication clear (see .IR ferror (3S)). Otherwise it returns non-zero with .C ferror() set. .PP In all cases above, if a failure is due to a failed system call, the .C errno value from the system is valid on return from the called function. .PP .C parse_bp_htype() returns .SM HTYPE_UNKNOWN if the hardware type string is unrecognized. .PP .C parse_bp_haddr() returns zero if successful, otherwise non-zero in case of parsing error, invalid .IR htype , or a host address type for which the address length is unknown; .I source is modified to point to the first illegal char (a .SM NUL if the string is too short). The caller's .I bytes value is unmodified, but .I result might be changed. .PP .C parse_bp_iaddr() returns zero if successful, otherwise non-zero, and .I source is modified to point to the first illegal char (a .SM NUL if the string is null). .\" =========== .SH EXAMPLES The following code fragment copies all data and comments from .C /etc/bootptab to a temporary copy of the file. It converts data entries to canonical form as a side effect, and prints to standard output the first field of each entry copied (should be the field name, assuming the entry doesn't start with a continuation line). .RS .PP .nf .ifn \f3 .ift \f4 #include \s-1FILE\s0 *newfilep; /* to write temp file */ bpp_t bp; /* read from file */ int field; /* current field number */ int fields; /* total in array for one entry */ if ((newfilep = fopen ("/tmp/bootptab", "w")) == (\s-1FILE\s0 *) \s-1NULL\s0) { \f2(handle error)\fP } while ((fields = getbootpent (&bp)) > 0) { for (field = 0; field < fields; ++field) { if ((bp[field].bp_type) == \s-1BP_DATA\s0) { (void) puts (bp[field].bp_text); break; } } if (putbootpent (bp, fields, newfilep)) { \f2(handle error)\fP } } if (fields < 0) /* error reading file */ { \f2(handle error)\fP } if (endbootpent()) { \f2(handle error)\fP } if (fclose (newfilep)) { \f2(handle error)\fP } .ft P .fi .RE .PP The following code fragment saves a copy of a bootptab entry returned by .CR getbootpent() . .RS .PP .nf .ifn \f3 .ift \f4 #include #include #include bpp_t bpnew; unsigned size; size = fields *\s-1BP_SIZE\s0; if ((bpnew = (bpp_t) malloc (size)) == \s-1BP_NULLP\s0) { \f2(handle error)\fP } (void) memcpy ((void *)bpnew, (void *)bp, size); .ft P .fi .RE .\" =========== .SH WARNINGS These functions are unsafe in multi-thread applications. .PP Calling .C setbootpent() releases any locks on the file it opens. .\" =========== .SH AUTHOR .PP These functions were developed by .SM HP. .\" =========== .SH FILES .TP 20 .C /etc/bootptab control file for .C bootpd .\" =========== .SH SEE ALSO bootpd(1M), .\" chbootptab(1M), (SAM-only, not currently supported for 10.0) errno(2), lockf(2), ferror(3S), fopen(3S), malloc(3C). .\" .\" toc@\f3getbootpent(3X)\f1:\0\0\f4getbootpent(), putbootpent(), setbootpent(), endbootpent(), \nparse_bp_htype(), parse_bp_hpaddr(), parse_bp_iaddr()\f1@@@get, or put bootptab entry .\" .\" index@get, or put bootptab entry \- @@@\f3getbootpent(3X)\f1 .\" index@bootptab entry, get or put@@@\f3getbootpent(3X)\f1 .\" .\" links@getbootpent.3x setbootpent.3x .\" links@getbootpent.3x endbootpent.3x .\" links@getbootpent.3x putbootpent.3x .\" links@getbootpent.3x parse_bp_htype.3x .\" links@getbootpent.3x parse_bp_haddr.3x .\" links@getbootpent.3x parse_bp_iaddr.3x .\" $Header: getc.3s,v 76.1 95/07/05 17:28:24 ssa Exp $ .TA g .TH getc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getc(\|), getc_unlocked(\|), getchar(\|), getchar_unlocked(\|), fgetc(\|), getw(\|), getw_unlocked(\|) \- get character or word from a stream file .SH SYNOPSIS .C "#include " .PP .C "int getc(FILE *stream);" .PP .C "int getc_unlocked(FILE *stream);" .PP .C "int getchar(void);" .PP .C "int getchar_unlocked(void);" .PP .C "int fgetc(FILE *stream);" .PP .C "int getw(FILE *stream);" .PP .C "int getw_unlocked(FILE *stream);" .SH DESCRIPTION .TP 15 .CR getc() Returns the next character (i.e., byte) from the named input .IR stream , as an unsigned character converted to an integer. It also moves the file pointer, if defined, ahead one character in .IR stream. .CR getchar() is defined as .CR getc(stdin) . .CR getc() and .CR getchar() are defined both as macros and as functions. .TP .CR fgetc() Same as .CR getc() , but is a function rather than a macro. .CR fgetc() is slower than .CR getc() , but it takes less space per invocation and its name can be passed as an argument to a function. .TP .CR getw() returns the next word (i.e., .CR int in C) from the named input .IR stream. .CR getw() increments the associated file pointer, if defined, to point to the next word. The size of a word is the size of an integer and varies from machine to machine. .CR getw() assumes no special alignment in the file. .PP .CR getc_unlocked() , " getchar_unlocked()" , and .CR getw_unlocked() are identical to .CR getc() , " getchar()" , and .CR getw() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon sucessful completion, .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , and .CR fgetc() return the next byte from the input stream pointed to by .I stream .RC ( stdin for .CR getchar() " and " getchar_unlocked() ). If the stream is at end-of-file, the end-of-file indicator for the stream is set and .SM EOF is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and .SM EOF is returned. .PP Upon sucessful completion, .CR getw() " and " getw_unlocked() return the next word from the input stream pointed to by .IR stream . If the stream is at end-of-file, the end-of-file indicator for the stream is set and .CR getw() " and " getw_unlocked() return .SM EOF. If a read error occurs, the error indicator for the stream is set, and .CR getw() " and " getw_unlocked() return .SM EOF and set .CR errno to indicate the error. .PP .CR ferror() and .CR feof() (or their .CR _unlocked versions) can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , .CR getw() , " getw_unlocked()" , and .CR fgetc() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 .SM [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP .SM [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP .SM [EIO] A physical I/O error has occurred, or the process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RE .PP Additional .CR errno values may be set by the underlying .CR read() function (see .IR read (2)). .SH WARNING .CR getc() and .CR getchar() are implemented both as library functions and macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI\s0-C mode, enclose the function name in parenthesis or use the function address. The following example illustrates each of these methods : .nf .IP .CR #include .CR #undef getc \h'.4i'... .CR main() .CR { .CR " int (*get_char()) ();" \h'1i'... .CR " return_val=getc(c,fd);" \h'1i'... .CR " return_val=(getc)(c,fd1);" \h'1i'... .CR " get_char = getchar;" .CR }; .fi .PP If the integer value returned by .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , or .CR fgetc() is stored into a character variable then compared against the integer constant .CR EOF , the comparison may never succeed because sign-extension of a character on widening to integer is machine-dependent. .PP The macro version of .CR getc() incorrectly treats a .I stream argument with side effects. In particular, .CR getc(*f++) does not work sensibly. The function version of .CR getc() or .CR fgetc() should be used instead. .br Because of possible differences in word length and byte ordering, files written using .CR putw() are machine-dependent, and may be unreadable by .CR getw() on a different processor. .SS Reentrant Interfaces If .CR _REENTRANT is defined before including .RC < stdio.h >, the locked versions of the library functions for .CR getc() and .CR getchar() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR getc() and .CR getchar() . .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), fread(3S), gets(3S), putc(3S), read(2), scanf(3S). .SH STANDARDS CONFORMANCE .CR getc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fgetc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4.2, FIPS 151-2, POSIX.1, ANSI C" .PP .CR getchar() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR getw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4getc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getc_unlock()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4fgetc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getchar()\f1 \- get character or word from \f4standard input\f1 file@@@\f3getc(3S)\f1 .\" index@\f4getchar_unlocked()\f1 \- get character or word from \f4standard input\f1 file@@@\f3getc(3S)\f1 .\" index@\f4getw()\f1 \- get data word (integer) from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getw_unlocked()\f1 \- get data word (integer) from a stream file@@@\f3getc(3S)\f1 .\" index@\f1get: character or data word from a stream file@@@\f3getc(3S)\f1 .\" index@\f1data, get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f1character or data word from a stream file, get@@@\f3getc(3S)\f1 .\" index@\f1word from a stream file, get character or data@@@\f3getc(3S)\f1 .\" index@\f1stream file, get character or data word from a@@@\f3getc(3S)\f1 .\" index@file, stream: get character or data word from a stream file@@@\f3getc(3S)\f1 .\" .\" toc@\f3getc(3S)\f1:\0\0\f4getc()\f1, \f4getc_unlocked()\f1, \f4getchar()\f1, \f4getchar_unlocked()\f1, \f4fgetc()\f1, \n\f4getw()\f1, \f4getw_unlocked\f1@@@get character or word from a stream file .\" toc@\f4fgetc()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getc_unlocked()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getchar()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getchar_unlocked()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4fgetc()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getw()\f1:\0\0get word from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getw_unlocked()\f1:\0\0get word from a stream file@@@see \f3getc(3S)\f1 .\" .\" links@getc.3s getc_unlock.3s .\" links@getc.3s getchar.3s .\" links@getc.3s getchar_unl.3s .\" links@getc.3s fgetc.3s .\" links@getc.3s getw.3s .\" links@getc.3s getw_unlock.3s .\" $Header: getc.3s,v 76.1 95/07/05 17:28:24 ssa Exp $ .TA g .TH getc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getc(\|), getc_unlocked(\|), getchar(\|), getchar_unlocked(\|), fgetc(\|), getw(\|), getw_unlocked(\|) \- get character or word from a stream file .SH SYNOPSIS .C "#include " .PP .C "int getc(FILE *stream);" .PP .C "int getc_unlocked(FILE *stream);" .PP .C "int getchar(void);" .PP .C "int getchar_unlocked(void);" .PP .C "int fgetc(FILE *stream);" .PP .C "int getw(FILE *stream);" .PP .C "int getw_unlocked(FILE *stream);" .SH DESCRIPTION .TP 15 .CR getc() Returns the next character (i.e., byte) from the named input .IR stream , as an unsigned character converted to an integer. It also moves the file pointer, if defined, ahead one character in .IR stream. .CR getchar() is defined as .CR getc(stdin) . .CR getc() and .CR getchar() are defined both as macros and as functions. .TP .CR fgetc() Same as .CR getc() , but is a function rather than a macro. .CR fgetc() is slower than .CR getc() , but it takes less space per invocation and its name can be passed as an argument to a function. .TP .CR getw() returns the next word (i.e., .CR int in C) from the named input .IR stream. .CR getw() increments the associated file pointer, if defined, to point to the next word. The size of a word is the size of an integer and varies from machine to machine. .CR getw() assumes no special alignment in the file. .PP .CR getc_unlocked() , " getchar_unlocked()" , and .CR getw_unlocked() are identical to .CR getc() , " getchar()" , and .CR getw() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon sucessful completion, .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , and .CR fgetc() return the next byte from the input stream pointed to by .I stream .RC ( stdin for .CR getchar() " and " getchar_unlocked() ). If the stream is at end-of-file, the end-of-file indicator for the stream is set and .SM EOF is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and .SM EOF is returned. .PP Upon sucessful completion, .CR getw() " and " getw_unlocked() return the next word from the input stream pointed to by .IR stream . If the stream is at end-of-file, the end-of-file indicator for the stream is set and .CR getw() " and " getw_unlocked() return .SM EOF. If a read error occurs, the error indicator for the stream is set, and .CR getw() " and " getw_unlocked() return .SM EOF and set .CR errno to indicate the error. .PP .CR ferror() and .CR feof() (or their .CR _unlocked versions) can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , .CR getw() , " getw_unlocked()" , and .CR fgetc() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 .SM [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP .SM [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP .SM [EIO] A physical I/O error has occurred, or the process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RE .PP Additional .CR errno values may be set by the underlying .CR read() function (see .IR read (2)). .SH WARNING .CR getc() and .CR getchar() are implemented both as library functions and macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI\s0-C mode, enclose the function name in parenthesis or use the function address. The following example illustrates each of these methods : .nf .IP .CR #include .CR #undef getc \h'.4i'... .CR main() .CR { .CR " int (*get_char()) ();" \h'1i'... .CR " return_val=getc(c,fd);" \h'1i'... .CR " return_val=(getc)(c,fd1);" \h'1i'... .CR " get_char = getchar;" .CR }; .fi .PP If the integer value returned by .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , or .CR fgetc() is stored into a character variable then compared against the integer constant .CR EOF , the comparison may never succeed because sign-extension of a character on widening to integer is machine-dependent. .PP The macro version of .CR getc() incorrectly treats a .I stream argument with side effects. In particular, .CR getc(*f++) does not work sensibly. The function version of .CR getc() or .CR fgetc() should be used instead. .br Because of possible differences in word length and byte ordering, files written using .CR putw() are machine-dependent, and may be unreadable by .CR getw() on a different processor. .SS Reentrant Interfaces If .CR _REENTRANT is defined before including .RC < stdio.h >, the locked versions of the library functions for .CR getc() and .CR getchar() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR getc() and .CR getchar() . .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), fread(3S), gets(3S), putc(3S), read(2), scanf(3S). .SH STANDARDS CONFORMANCE .CR getc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fgetc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4.2, FIPS 151-2, POSIX.1, ANSI C" .PP .CR getchar() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR getw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4getc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getc_unlock()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4fgetc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getchar()\f1 \- get character or word from \f4standard input\f1 file@@@\f3getc(3S)\f1 .\" index@\f4getchar_unlocked()\f1 \- get character or word from \f4standard input\f1 file@@@\f3getc(3S)\f1 .\" index@\f4getw()\f1 \- get data word (integer) from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getw_unlocked()\f1 \- get data word (integer) from a stream file@@@\f3getc(3S)\f1 .\" index@\f1get: character or data word from a stream file@@@\f3getc(3S)\f1 .\" index@\f1data, get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f1character or data word from a stream file, get@@@\f3getc(3S)\f1 .\" index@\f1word from a stream file, get character or data@@@\f3getc(3S)\f1 .\" index@\f1stream file, get character or data word from a@@@\f3getc(3S)\f1 .\" index@file, stream: get character or data word from a stream file@@@\f3getc(3S)\f1 .\" .\" toc@\f3getc(3S)\f1:\0\0\f4getc()\f1, \f4getc_unlocked()\f1, \f4getchar()\f1, \f4getchar_unlocked()\f1, \f4fgetc()\f1, \n\f4getw()\f1, \f4getw_unlocked\f1@@@get character or word from a stream file .\" toc@\f4fgetc()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getc_unlocked()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getchar()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getchar_unlocked()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4fgetc()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getw()\f1:\0\0get word from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getw_unlocked()\f1:\0\0get word from a stream file@@@see \f3getc(3S)\f1 .\" .\" links@getc.3s getc_unlock.3s .\" links@getc.3s getchar.3s .\" links@getc.3s getchar_unl.3s .\" links@getc.3s fgetc.3s .\" links@getc.3s getw.3s .\" links@getc.3s getw_unlock.3s .\" $Header: getcchar.3x,v 76.2 95/08/01 10:49:35 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getcchar 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getcchar \(em get a wide character string and rendition from a \f3cchar_t\f1 .SH SYNOPSIS .C "#include " .P .C "int getcchar(cchar_t *const \f2wcval\fP, wchar_t *\f2wch\fP, attr_t *\f2attrs\fP," .br .C " short *\f2color_pair\fP, void *\f2opts\fP);" .SH DESCRIPTION When \f2wch\f1 is not a null pointer, the .Fn getcchar function extracts information from a \f3cchar_t\f1 defined by \f2wcval\fP, stores the character attributes in the object pointed to by \f2attrs\fP, stores the colour pair in the object pointed to by \f2color_pair\fP, and stores the wide character string referenced by \f2wcval\f1 into the array pointed to by \f2wch\f1. .P When \f2wch\f1 is a null pointer, .Fn getcchar obtains the number of wide characters in the object pointed to by \f2wcval\f1 and does not change the objects pointed to by \f2attrs\f1 or \f2color_pair\f1. .P The \f2opts\f1 argument is reserved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" When \f2wch\f1 is a null pointer, .Fn getcchar returns the number of wide characters referenced by \f2wcval\fP, including the null terminator. .P When \f2wch\f1 is not a null pointer, .Fn getcchar returns OK upon successful completion, and ERR otherwise. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The \f2wcval\f1 argument may be a value generated by a call to .Fn setcchar or by a function that has a \f3cchar_t\f1 output argument. If \f2wcval\f1 is constructed by any other means, the effect is unspecified. .SH "SEE ALSO" attroff(), can_change_color(), setcchar(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4getcchar()\f1 \- get a wide character string and rendition from a \f4cchar_t\f1@@@\f3getcchar(3X)\f1 .\" index@\f1get a wide character string and rendition from a \f4cchar_t\f1@@@\f3getcchar(3X)\f1 .\" index@\f1wide character string and rendition, get from a \f4cchar_t\f1@@@\f3getcchar(3X)\f1 .\" index@\f1character string and rendition, wide, get from a \f4cchar_t\f1@@@\f3getcchar(3X)\f1 .\" index@\f4cchar_t\f1, get a wide character string and rendition from \f1@@@\f3getcchar(3X)\f1 .\" .\" toc@\f3getcchar(3X)\f1:\0\0\f4getcchar()\f1@@@get a wide character string and rendition from a \f4cchar_t\f1 .\" .\" fileset_database@getcchar.3x CURS-ENG-A-MAN .\" $Header: getch.3x,v 76.2 95/08/01 10:51:16 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getch, wgetch, mvgetch, mvwgetch \(em get a single-byte character from the terminal .SH SYNOPSIS .C "#include " .P .C "int getch(void);" .P .C "int mvgetch(int \f2y\fP, int \f2x\fP);" .P .C "int mvwgetch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "int wgetch(WINDOW *\f2win\fP);" .SH DESCRIPTION These functions read a single-byte character from the terminal associated with the current or specified window. The results are unspecified if the input is not a single-byte character. If .Fn keypad is enabled, these functions respond to the pressing of a function key by returning the corresponding KEY_ value defined in .CR . .P Processing of terminal input is subject to the general rules described in \f3Input Processing\f1 in curses_intro. .P If echoing is enabled, then the character is echoed as though it were provided as an input argument to .CR insch() , except for the following characters: .PP .TS tab(`); lw(2.00i) lw(3i). T{ , and the current erase character: T}`T{ The input is interpreted as specified in .CR specialchars and then the character at the resulting cursor position is deleted as though .Fn delch were called, except that if the cursor was originally in the first column of the line, then the user is alerted as though .Fn beep were called. T} .P Function keys`T{ The user is alerted as though .Fn beep were called. Information concerning the function keys is not returned to the caller. T} .TE .P If the current or specified window is not a pad, and it has been moved or modified since the last refresh operation, then it will be refreshed before another character is read. .SH "RETURN VALUE" Upon successful completion, these functions return the single-byte character, KEY_ value, or ERR. .P If in nodelay mode and no data is available, ERR is returned. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Applications should not define the escape key by itself as a single-character function. .P When using these functions, nocbreak mode (\c .CR nocbreak() ) and echo mode (\c .CR echo() ) should not be used at the same time. Depending on the state of the terminal when each character is typed, the program may produce undesirable results. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, cbreak(), doupdate(), insch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn getch function is explicitly declared as \f3void\f1. .\" .\" toc@\f3getch(3X)\f1:\0\0\f4getch()\f1, \f4wgetch()\f1, \f4mvgetch()\f1, \f4mvwgetch()\f1@@@get a single-byte character from the terminal .\" toc@\f4wgetch()\f1: get a single-byte character from the terminal@@@see \f3getch(3X)\f1 .\" toc@\f4mvwgetch()\f1: get a single-byte character from the terminal@@@see \f3getch(3X)\f1 .\" toc@\f4mvgetch()\f1: get a single-byte character from the terminal@@@see \f3getch(3X)\f1 .\" .\" index@\f4getch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f4wgetch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f4mvgetch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f4mvwgetch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f1get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f1single-byte character, get from the terminal@@@\f3getch(3X)\f1 .\" index@\f1terminal, get a single-byte character@@@\f3getch(3X)\f1 .\" index@\f1character, single-byte, get from the terminal@@@\f3getch(3X)\f1 .\" .\" links@getch.3x wgetch.3x .\" links@getch.3x mvwgetch.3x .\" links@getch.3x mvgetch.3x .\" .\" fileset_database@getch.3x CURS-ENG-A-MAN .\" $Header: getc.3s,v 76.1 95/07/05 17:28:24 ssa Exp $ .TA g .TH getc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getc(\|), getc_unlocked(\|), getchar(\|), getchar_unlocked(\|), fgetc(\|), getw(\|), getw_unlocked(\|) \- get character or word from a stream file .SH SYNOPSIS .C "#include " .PP .C "int getc(FILE *stream);" .PP .C "int getc_unlocked(FILE *stream);" .PP .C "int getchar(void);" .PP .C "int getchar_unlocked(void);" .PP .C "int fgetc(FILE *stream);" .PP .C "int getw(FILE *stream);" .PP .C "int getw_unlocked(FILE *stream);" .SH DESCRIPTION .TP 15 .CR getc() Returns the next character (i.e., byte) from the named input .IR stream , as an unsigned character converted to an integer. It also moves the file pointer, if defined, ahead one character in .IR stream. .CR getchar() is defined as .CR getc(stdin) . .CR getc() and .CR getchar() are defined both as macros and as functions. .TP .CR fgetc() Same as .CR getc() , but is a function rather than a macro. .CR fgetc() is slower than .CR getc() , but it takes less space per invocation and its name can be passed as an argument to a function. .TP .CR getw() returns the next word (i.e., .CR int in C) from the named input .IR stream. .CR getw() increments the associated file pointer, if defined, to point to the next word. The size of a word is the size of an integer and varies from machine to machine. .CR getw() assumes no special alignment in the file. .PP .CR getc_unlocked() , " getchar_unlocked()" , and .CR getw_unlocked() are identical to .CR getc() , " getchar()" , and .CR getw() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon sucessful completion, .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , and .CR fgetc() return the next byte from the input stream pointed to by .I stream .RC ( stdin for .CR getchar() " and " getchar_unlocked() ). If the stream is at end-of-file, the end-of-file indicator for the stream is set and .SM EOF is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and .SM EOF is returned. .PP Upon sucessful completion, .CR getw() " and " getw_unlocked() return the next word from the input stream pointed to by .IR stream . If the stream is at end-of-file, the end-of-file indicator for the stream is set and .CR getw() " and " getw_unlocked() return .SM EOF. If a read error occurs, the error indicator for the stream is set, and .CR getw() " and " getw_unlocked() return .SM EOF and set .CR errno to indicate the error. .PP .CR ferror() and .CR feof() (or their .CR _unlocked versions) can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , .CR getw() , " getw_unlocked()" , and .CR fgetc() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 .SM [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP .SM [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP .SM [EIO] A physical I/O error has occurred, or the process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RE .PP Additional .CR errno values may be set by the underlying .CR read() function (see .IR read (2)). .SH WARNING .CR getc() and .CR getchar() are implemented both as library functions and macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI\s0-C mode, enclose the function name in parenthesis or use the function address. The following example illustrates each of these methods : .nf .IP .CR #include .CR #undef getc \h'.4i'... .CR main() .CR { .CR " int (*get_char()) ();" \h'1i'... .CR " return_val=getc(c,fd);" \h'1i'... .CR " return_val=(getc)(c,fd1);" \h'1i'... .CR " get_char = getchar;" .CR }; .fi .PP If the integer value returned by .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , or .CR fgetc() is stored into a character variable then compared against the integer constant .CR EOF , the comparison may never succeed because sign-extension of a character on widening to integer is machine-dependent. .PP The macro version of .CR getc() incorrectly treats a .I stream argument with side effects. In particular, .CR getc(*f++) does not work sensibly. The function version of .CR getc() or .CR fgetc() should be used instead. .br Because of possible differences in word length and byte ordering, files written using .CR putw() are machine-dependent, and may be unreadable by .CR getw() on a different processor. .SS Reentrant Interfaces If .CR _REENTRANT is defined before including .RC < stdio.h >, the locked versions of the library functions for .CR getc() and .CR getchar() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR getc() and .CR getchar() . .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), fread(3S), gets(3S), putc(3S), read(2), scanf(3S). .SH STANDARDS CONFORMANCE .CR getc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fgetc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4.2, FIPS 151-2, POSIX.1, ANSI C" .PP .CR getchar() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR getw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4getc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getc_unlock()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4fgetc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getchar()\f1 \- get character or word from \f4standard input\f1 file@@@\f3getc(3S)\f1 .\" index@\f4getchar_unlocked()\f1 \- get character or word from \f4standard input\f1 file@@@\f3getc(3S)\f1 .\" index@\f4getw()\f1 \- get data word (integer) from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getw_unlocked()\f1 \- get data word (integer) from a stream file@@@\f3getc(3S)\f1 .\" index@\f1get: character or data word from a stream file@@@\f3getc(3S)\f1 .\" index@\f1data, get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f1character or data word from a stream file, get@@@\f3getc(3S)\f1 .\" index@\f1word from a stream file, get character or data@@@\f3getc(3S)\f1 .\" index@\f1stream file, get character or data word from a@@@\f3getc(3S)\f1 .\" index@file, stream: get character or data word from a stream file@@@\f3getc(3S)\f1 .\" .\" toc@\f3getc(3S)\f1:\0\0\f4getc()\f1, \f4getc_unlocked()\f1, \f4getchar()\f1, \f4getchar_unlocked()\f1, \f4fgetc()\f1, \n\f4getw()\f1, \f4getw_unlocked\f1@@@get character or word from a stream file .\" toc@\f4fgetc()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getc_unlocked()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getchar()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getchar_unlocked()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4fgetc()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getw()\f1:\0\0get word from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getw_unlocked()\f1:\0\0get word from a stream file@@@see \f3getc(3S)\f1 .\" .\" links@getc.3s getc_unlock.3s .\" links@getc.3s getchar.3s .\" links@getc.3s getchar_unl.3s .\" links@getc.3s fgetc.3s .\" links@getc.3s getw.3s .\" links@getc.3s getw_unlock.3s .\" $Header: getc.3s,v 76.1 95/07/05 17:28:24 ssa Exp $ .TA g .TH getc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getc(\|), getc_unlocked(\|), getchar(\|), getchar_unlocked(\|), fgetc(\|), getw(\|), getw_unlocked(\|) \- get character or word from a stream file .SH SYNOPSIS .C "#include " .PP .C "int getc(FILE *stream);" .PP .C "int getc_unlocked(FILE *stream);" .PP .C "int getchar(void);" .PP .C "int getchar_unlocked(void);" .PP .C "int fgetc(FILE *stream);" .PP .C "int getw(FILE *stream);" .PP .C "int getw_unlocked(FILE *stream);" .SH DESCRIPTION .TP 15 .CR getc() Returns the next character (i.e., byte) from the named input .IR stream , as an unsigned character converted to an integer. It also moves the file pointer, if defined, ahead one character in .IR stream. .CR getchar() is defined as .CR getc(stdin) . .CR getc() and .CR getchar() are defined both as macros and as functions. .TP .CR fgetc() Same as .CR getc() , but is a function rather than a macro. .CR fgetc() is slower than .CR getc() , but it takes less space per invocation and its name can be passed as an argument to a function. .TP .CR getw() returns the next word (i.e., .CR int in C) from the named input .IR stream. .CR getw() increments the associated file pointer, if defined, to point to the next word. The size of a word is the size of an integer and varies from machine to machine. .CR getw() assumes no special alignment in the file. .PP .CR getc_unlocked() , " getchar_unlocked()" , and .CR getw_unlocked() are identical to .CR getc() , " getchar()" , and .CR getw() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon sucessful completion, .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , and .CR fgetc() return the next byte from the input stream pointed to by .I stream .RC ( stdin for .CR getchar() " and " getchar_unlocked() ). If the stream is at end-of-file, the end-of-file indicator for the stream is set and .SM EOF is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and .SM EOF is returned. .PP Upon sucessful completion, .CR getw() " and " getw_unlocked() return the next word from the input stream pointed to by .IR stream . If the stream is at end-of-file, the end-of-file indicator for the stream is set and .CR getw() " and " getw_unlocked() return .SM EOF. If a read error occurs, the error indicator for the stream is set, and .CR getw() " and " getw_unlocked() return .SM EOF and set .CR errno to indicate the error. .PP .CR ferror() and .CR feof() (or their .CR _unlocked versions) can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , .CR getw() , " getw_unlocked()" , and .CR fgetc() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 .SM [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP .SM [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP .SM [EIO] A physical I/O error has occurred, or the process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RE .PP Additional .CR errno values may be set by the underlying .CR read() function (see .IR read (2)). .SH WARNING .CR getc() and .CR getchar() are implemented both as library functions and macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI\s0-C mode, enclose the function name in parenthesis or use the function address. The following example illustrates each of these methods : .nf .IP .CR #include .CR #undef getc \h'.4i'... .CR main() .CR { .CR " int (*get_char()) ();" \h'1i'... .CR " return_val=getc(c,fd);" \h'1i'... .CR " return_val=(getc)(c,fd1);" \h'1i'... .CR " get_char = getchar;" .CR }; .fi .PP If the integer value returned by .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , or .CR fgetc() is stored into a character variable then compared against the integer constant .CR EOF , the comparison may never succeed because sign-extension of a character on widening to integer is machine-dependent. .PP The macro version of .CR getc() incorrectly treats a .I stream argument with side effects. In particular, .CR getc(*f++) does not work sensibly. The function version of .CR getc() or .CR fgetc() should be used instead. .br Because of possible differences in word length and byte ordering, files written using .CR putw() are machine-dependent, and may be unreadable by .CR getw() on a different processor. .SS Reentrant Interfaces If .CR _REENTRANT is defined before including .RC < stdio.h >, the locked versions of the library functions for .CR getc() and .CR getchar() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR getc() and .CR getchar() . .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), fread(3S), gets(3S), putc(3S), read(2), scanf(3S). .SH STANDARDS CONFORMANCE .CR getc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fgetc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4.2, FIPS 151-2, POSIX.1, ANSI C" .PP .CR getchar() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR getw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4getc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getc_unlock()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4fgetc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getchar()\f1 \- get character or word from \f4standard input\f1 file@@@\f3getc(3S)\f1 .\" index@\f4getchar_unlocked()\f1 \- get character or word from \f4standard input\f1 file@@@\f3getc(3S)\f1 .\" index@\f4getw()\f1 \- get data word (integer) from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getw_unlocked()\f1 \- get data word (integer) from a stream file@@@\f3getc(3S)\f1 .\" index@\f1get: character or data word from a stream file@@@\f3getc(3S)\f1 .\" index@\f1data, get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f1character or data word from a stream file, get@@@\f3getc(3S)\f1 .\" index@\f1word from a stream file, get character or data@@@\f3getc(3S)\f1 .\" index@\f1stream file, get character or data word from a@@@\f3getc(3S)\f1 .\" index@file, stream: get character or data word from a stream file@@@\f3getc(3S)\f1 .\" .\" toc@\f3getc(3S)\f1:\0\0\f4getc()\f1, \f4getc_unlocked()\f1, \f4getchar()\f1, \f4getchar_unlocked()\f1, \f4fgetc()\f1, \n\f4getw()\f1, \f4getw_unlocked\f1@@@get character or word from a stream file .\" toc@\f4fgetc()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getc_unlocked()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getchar()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getchar_unlocked()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4fgetc()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getw()\f1:\0\0get word from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getw_unlocked()\f1:\0\0get word from a stream file@@@see \f3getc(3S)\f1 .\" .\" links@getc.3s getc_unlock.3s .\" links@getc.3s getchar.3s .\" links@getc.3s getchar_unl.3s .\" links@getc.3s fgetc.3s .\" links@getc.3s getw.3s .\" links@getc.3s getw_unlock.3s .\" $Header: getclock.3c,v 72.5 94/11/14 15:28:48 ssa Exp $ .TA g .TH getclock 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getclock \- get current value of system-wide clock .SH SYNOPSIS .C "#include " .PP .C "int getclock(int clock_type, struct timespec *tp);" .SH DESCRIPTION The .CR getclock() function gets the current value .CR tp of the specified system-wide clock, .CR clock_type . .PP .CR getclock() supports a .CR clock_type of .CR TIMEOFDAY , defined in .RC < sys/timers.h >, which represents the time-of-day clock for the system. For this clock, the values returned by .CR getclock() represent the amount of time since the Epoch. .SH RETURN VALUE Upon successful completion, .CR getclock() returns a value of zero; otherwise it returns a value of \(mi1 and sets .CR errno to indicate the error. .SH ERRORS .CR getclock() fails if any of the following conditions are encountered: .RS .TP 12 [EINVAL] .CR clock_type does not specify a known system-wide clock. .TP [EIO] An error occurred while accessing the clock device. .RE .SH FILES .C /usr/include/sys/timers.h .SH SEE ALSO clock_gettime(2), gettimer(3C), setclock(3C). .SH STANDARDS CONFORMANCE .CR getclock() ": AES" .\" .\" toc@\f3getclock(3C)\f1:\0\0\f4getclock()\f1@@@get current value of system-wide clock\f1 .\" .\" index@\f4getclock()\f1 \- get current value of system-wide clock@@@\f3getclock(3C)\f1 .\" index@\f1get current value of system-wide clock@@@\f3getclock(3C)\f1 .\" index@\f1current value of system-wide clock, get@@@\f3getclock(3C)\f1 .\" index@\f1value of system-wide clock, get current@@@\f3getclock(3C)\f1 .\" index@\f1system-wide clock, get current value of@@@\f3getclock(3C)\f1 .\" index@\f1clock, get current value of system-wide@@@\f3getclock(3C)\f1 .\" $Header: getcwd.3c,v 72.6 94/11/14 15:28:49 ssa Exp $ .TA g .TH getcwd 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getcwd(\|) \- get pathname of current working directory .SH SYNOPSIS .C "#include " .PP .C "char *getcwd(char *buf, size_t size);" .SH DESCRIPTION The .CR getcwd() function places the absolute pathname of the current working directory in the array pointed to by .IR buf , and returns .IR buf . The value of .I size must be at least one greater than the length of the pathname to be returned. .PP If .I buf is a .SM NULL pointer, .CR getcwd() obtains .I size bytes of space using .CR malloc() (see .IR malloc (3C)). In this case, the pointer returned by .CR getcwd() can be used as the argument in a subsequent call to .CR free() (see .IR malloc (3C)). Invoking .CR getcwd() with .I buf as a null pointer is not recommended because this functionality may be removed from the .SM HP-UX operating system in a future release. .SH RETURN VALUE Upon successful completion, .CR getcwd() returns a pointer to the current directory pathname. Otherwise, it returns .SM NULL with .CR errno set if .I size is not large enough, or if an error occurs in a lower-level function. .SH ERRORS .CR getcwd() fails if any of the following conditions are encountered: .RS .TP 20 .SM [EINVAL] The .I size argument is zero or negative. .TP .SM [ERANGE] The .I size argument is greater than zero, but is smaller than the length of the pathname. .TP .SM [ENAMETOOLONG] The length of the specified pathname exceeds .CR PATH_MAX bytes, or the length of a component of the pathname exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .RE .PP .CR getcwd() may fail if any of the following conditions are encountered: .RS .TP 20 .SM [EACCES] Read or search permission is denied for a component of pathname. .TP .SM [EFAULT] .I buf points outside the allocated address space of the process. .CR getcwd() may not always detect this error. .TP .SM [ENOMEM] .CR malloc() failed to provide .I size bytes of memory. .RE .SH EXAMPLES .RS .ift .ft 4 .ifn .ft 3 .ps +1 .nf char *cwd, *getcwd(); char buf[PATH_MAX\|+\|1\|]; \h'1i'.\|.\|. if ((cwd = getcwd((buf *)NULL, PATH_MAX+1)) == NULL) { perror("pwd"); exit(1); } puts(cwd); .fi .RE .SH AUTHOR .CR getcwd() was developed by AT&T. .SH SEE ALSO pwd(1), malloc(3C). .SH STANDARDS CONFORMANCE .CR getcwd() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4getcwd()\fP \- get path-name of current working directory@@@\f3getcwd(3C)\f1 .\" index@get: path-name of current working directory@@@\f3getcwd(3C)\f1 .\" index@path-name of current working directory, get@@@\f3getcwd(3C)\f1 .\" index@current working directory, get path-name of@@@\f3getcwd(3C)\f1 .\" index@working directory, get path-name of current@@@\f3getcwd(3C)\f1 .\" index@directory: get path-name of current working directory@@@\f3getcwd(3C)\f1 .\" .\" toc@\f3getcwd(3C)\f1:\0\0\f4getcwd()\fP@@@get path-name of current working directory .\" .\" fileset_database@getcwd.3c PROGRAMING-MAN .\" $Header: getdate.3c,v 76.2 95/07/24 16:21:15 ssa Exp $ .TA g .TH getdate 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getdate(), getdate_r() \- convert user format date and time .SH SYNOPSIS .C "#include " .PP .C "struct tm *getdate(const char *string);" .PP .C "extern int getdate_err;" .PP .C "int getdate_r(const char *string, struct tm *result, int *errnum);" .SH DESCRIPTION The .CR getdate() function converts user definable date and/or time specifications pointed to by .I string into a .CR "struct tm" . The structure declaration is in the .CR header file (see .IR ctime (3C)). .PP The .CR getdate_r() function expects to be passed the address of a .CR "struct tm" and stores the result at the supplied address. A .CR \(mi1 is returned if an error is encountered and the variable pointed to by .I *errnum is set to indicate the error as described for .CR getdate_err below. If the operation is successful, .CR 0 is returned. .PP User-supplied templates are used to parse and interpret the input string. The templates are text files created by the user and identified via the environment variable .CR DATEMSK . .CR DATEMSK should be set to indicate the full path name of the template file. The first line in the template that matches the input specification is used for interpretation and conversion into the internal time format. Upon successful completion, .CR getdate() returns a pointer to a .CR "struct tm" ; otherwise, it returns NULL and the external variable .CR getdate_err is set to indicate the error. .PP The following field descriptors are supported: .RS .PD 0 .TP 10 .C %% same as .C % .TP 10 .C %a abbreviated weekday name .TP .C %A full weekday name .TP .C %b abbreviated month name .TP .C %B full month name .TP .C %c locale's appropriate date and time representation .TP .C %d day of the month (01 through 31; the leading 0 is optional) .TP .C %e same as .C %d .TP .C %D date as .C %m/%d/%y .TP .C %h abbreviated month name .TP .C %H hour (00 through 23) .TP .C %I hour (01 through 12) .TP .C %m month number (01 through 12) .TP .C %M minute (00 through 59) .TP .C %n same as .C \en .TP .C %p locale's equivalent of either AM or PM .TP .C %r time as .C %I:%M:%S %p .TP .C %R time as .C %H:%M .TP .C %S seconds (00 through 61) .TP .C %t insert a tab .TP .C %T time as .C %H:%M:%S .TP .C %w weekday number (Sunday = 0 through Saturday = 6) .TP .C %x locale's appropriate date representation .TP .C %X locale's appropriate time representation .TP .C %y year without century (00 through 99) .TP .C %Y year as .I ccyy (e.g., 1986) .TP .C %Z time zone name or no characters if no time zone exists. If the time zone supplied by .CR %Z is not the same as the time zone .CR getdate() expects, an invalid specification error is returned. .CR getdate() calculates the expected time zone from the .CR TZ environment variable. .PD .RE .PP Month and weekday names may consist of any combination of uppercase and lowercase letters. The user can request that the input date or time specification be in a specific language by setting the .CR LC_TIME category (see .IR setlocale (3C)). .PP For descriptors that allow leading zeros, leading zeros are optional. However, the number of digits used for those descriptors must not exceed two, including leading zeros. Extra whitespace in either the template file or in .I string is ignored. .PP The field descriptors .CR %c , .CR %x , and .CR %X are not supported if they include unsupported field descriptors. .PP The following example shows the possible contents of a template: .RS .PP .nf .C "%m" .C "%A %B %d, %Y, %H:%M:%S" .C "%A" .C "%B" .C "%m/%d/%y %I %p" .C "%d,%m,%Y %H:%M" .C "at %A the %dst of %B in %Y" .C "run job at %I %p, %B %dnd" .C "%A den %d. %B %Y %H.%M Uhr" .fi .RE .PP The following are examples of valid input specifications for the above template: .RS .PP .nf .C getdate("10/1/87 4 PM"); .C getdate("Friday"); .C getdate("Friday September 18, 1987, 10:30:30"); .C getdate("24,9,1986 10:30"); .C getdate("at monday the 1st of december in 1986"); .C getdate("run job at 3 PM, december 2nd"); .fi .RE .PP If the .CR LC_TIME category is set to a German locale that includes .CR freitag as a weekday name and .CR oktober as a month name, the following would be valid: .IP .ift \f4\getdate("freitag den 10. oktober 1986 10.30 Uhr");\fP .ifn \f3getdate("freitag den 10. oktober 1986 10.30 Uhr");\fP .PP This example shows how local date and time specification can be defined in the template: .RS .PP .TS box; cB | cB lf4 | lf4. Invocation Line in Template _ getdate("11/27/86") %m/%d/%y getdate("27.11.86") %d.%m.%y getdate("86-11-27") %y-%m-%d getdate("Friday 12:00:00") %A %H:%M:%S .TE .RE .PP The following rules apply when converting the input specification into the internal format: .RS .TP 3 \(bu If only the weekday is given, today is assumed if the given day is equal to the current day, and next week if it is less. .TP \(bu If only the month is given, the current month is assumed if the given month is equal to the current month, and next year if it is less and no year is given (the first day of the month is assumed if no day is given). .TP \(bu If no hour, minute and second are given, the current hour, minute and second are assumed. .TP \(bu If no date is given, today is assumed if the given hour is greater than the current hour and tomorrow is assumed if it is less. .RE .PP The following examples help to illustrate the above rules assuming that the current date is .CR "Mon Sep 22 12:19:47 EDT 1986" , and the .CR LC_TIME category is set to the default .CR C locale. .IP .TS box tab(;); cB | cB | cB cB | cB | cB lf4 | lf4 | l . ;Line in; Input;Template;Date _ Mon;%a;Mon Sep 22 12:19:47 EDT 1986 Sun;%a;Sun Sep 28 12:19:47 EDT 1986 Fri;%a;Fri Sep 26 12:19:47 EDT 1986 September;%B;Mon Sep 1 12:19:47 EDT 1986 January;%B;Thu Jan 1 12:19:47 EST 1987 December;%B;Mon Dec 1 12:19:47 EST 1986 Sep Mon;%b %a;Mon Sep 1 12:19:47 EDT 1986 Jan Fri;%b %a;Fri Jan 2 12:19:47 EST 1987 Dec Mon;%b %a;Mon Dec 1 12:19:47 EST 1986 Jan Wed 1989;%b %a %Y;Wed Jan 4 12:19:47 EST 1989 Fri 9;%a %H;Fri Sep 26 09:00:00 EDT 1986 Feb 10:30;%b %H:%S;Sun Feb 1 10:30:00 EST 1987 10:30;%H:%M;Tue Sep 23 10:30:00 EDT 1986 13:30;%H:%M;Mon Sep 22 13:30:00 EDT 1986 .TE .SH ERRORS Upon failure, .CR getdate() returns NULL and the variable .CR getdate_err is set to indicate the error. .PP The following is a complete list of the .CR getdate_err settings and their interpretation: .RS .TP 3 .C 1 the .CR DATEMSK environment variable is null or undefined, .TP .C 2 the template file cannot be opened for reading, .TP .C 3 failed to get file status information, .TP .C 4 the template file is not a regular file, .TP .C 5 an error is encountered while reading the template file, .TP .C 6 memory allocation failed (not enough memory available), .TP .C 7 there is no line in the template that matches the input, .TP .C 8 invalid input specification (example: February 31). .RE .SH WARNINGS The return value for .CR getdate() points to static data whose content is overwritten by each call. Thus, .CR getdate() is unsafe in multi-thread applications. .CR getdate_r() is MT-Safe and should be used instead. .SH SEE ALSO ctime(3C), ctype(3C), setlocale(3C), strftime(3C). .\" .\" index@\f4getdate()\f1 \- convert user format date and time@@@\f3getdate(3C)\f1 .\" index@\f4getdate_r()\f1 \- convert user format date and time@@@\f3getdate(3C)\f1 .\" index@\f1convert user format date and time@@@\f3getdate(3C)\f1 .\" index@\f1user format date and time, convert@@@\f3getdate(3C)\f1 .\" index@\f1format date and time, convert user@@@\f3getdate(3C)\f1 .\" index@\f1date and time, convert user format@@@\f3getdate(3C)\f1 .\" index@\f1time, convert user format date and@@@\f3getdate(3C)\f1 .\" .\" toc@\f3getdate(3C)\f1:\0\0\f4getdate()\f1, \f4getdate_r()\f1@@@convert user format date and time .\" toc@\f4getdate_r()\f1:\0\0convert user format date and time@@@\f1see \f3getdate(3C)\f1 .\" .\" links@getdate.3c getdate_r.3c .\" $Header: getdate.3c,v 76.2 95/07/24 16:21:15 ssa Exp $ .TA g .TH getdate 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getdate(), getdate_r() \- convert user format date and time .SH SYNOPSIS .C "#include " .PP .C "struct tm *getdate(const char *string);" .PP .C "extern int getdate_err;" .PP .C "int getdate_r(const char *string, struct tm *result, int *errnum);" .SH DESCRIPTION The .CR getdate() function converts user definable date and/or time specifications pointed to by .I string into a .CR "struct tm" . The structure declaration is in the .CR header file (see .IR ctime (3C)). .PP The .CR getdate_r() function expects to be passed the address of a .CR "struct tm" and stores the result at the supplied address. A .CR \(mi1 is returned if an error is encountered and the variable pointed to by .I *errnum is set to indicate the error as described for .CR getdate_err below. If the operation is successful, .CR 0 is returned. .PP User-supplied templates are used to parse and interpret the input string. The templates are text files created by the user and identified via the environment variable .CR DATEMSK . .CR DATEMSK should be set to indicate the full path name of the template file. The first line in the template that matches the input specification is used for interpretation and conversion into the internal time format. Upon successful completion, .CR getdate() returns a pointer to a .CR "struct tm" ; otherwise, it returns NULL and the external variable .CR getdate_err is set to indicate the error. .PP The following field descriptors are supported: .RS .PD 0 .TP 10 .C %% same as .C % .TP 10 .C %a abbreviated weekday name .TP .C %A full weekday name .TP .C %b abbreviated month name .TP .C %B full month name .TP .C %c locale's appropriate date and time representation .TP .C %d day of the month (01 through 31; the leading 0 is optional) .TP .C %e same as .C %d .TP .C %D date as .C %m/%d/%y .TP .C %h abbreviated month name .TP .C %H hour (00 through 23) .TP .C %I hour (01 through 12) .TP .C %m month number (01 through 12) .TP .C %M minute (00 through 59) .TP .C %n same as .C \en .TP .C %p locale's equivalent of either AM or PM .TP .C %r time as .C %I:%M:%S %p .TP .C %R time as .C %H:%M .TP .C %S seconds (00 through 61) .TP .C %t insert a tab .TP .C %T time as .C %H:%M:%S .TP .C %w weekday number (Sunday = 0 through Saturday = 6) .TP .C %x locale's appropriate date representation .TP .C %X locale's appropriate time representation .TP .C %y year without century (00 through 99) .TP .C %Y year as .I ccyy (e.g., 1986) .TP .C %Z time zone name or no characters if no time zone exists. If the time zone supplied by .CR %Z is not the same as the time zone .CR getdate() expects, an invalid specification error is returned. .CR getdate() calculates the expected time zone from the .CR TZ environment variable. .PD .RE .PP Month and weekday names may consist of any combination of uppercase and lowercase letters. The user can request that the input date or time specification be in a specific language by setting the .CR LC_TIME category (see .IR setlocale (3C)). .PP For descriptors that allow leading zeros, leading zeros are optional. However, the number of digits used for those descriptors must not exceed two, including leading zeros. Extra whitespace in either the template file or in .I string is ignored. .PP The field descriptors .CR %c , .CR %x , and .CR %X are not supported if they include unsupported field descriptors. .PP The following example shows the possible contents of a template: .RS .PP .nf .C "%m" .C "%A %B %d, %Y, %H:%M:%S" .C "%A" .C "%B" .C "%m/%d/%y %I %p" .C "%d,%m,%Y %H:%M" .C "at %A the %dst of %B in %Y" .C "run job at %I %p, %B %dnd" .C "%A den %d. %B %Y %H.%M Uhr" .fi .RE .PP The following are examples of valid input specifications for the above template: .RS .PP .nf .C getdate("10/1/87 4 PM"); .C getdate("Friday"); .C getdate("Friday September 18, 1987, 10:30:30"); .C getdate("24,9,1986 10:30"); .C getdate("at monday the 1st of december in 1986"); .C getdate("run job at 3 PM, december 2nd"); .fi .RE .PP If the .CR LC_TIME category is set to a German locale that includes .CR freitag as a weekday name and .CR oktober as a month name, the following would be valid: .IP .ift \f4\getdate("freitag den 10. oktober 1986 10.30 Uhr");\fP .ifn \f3getdate("freitag den 10. oktober 1986 10.30 Uhr");\fP .PP This example shows how local date and time specification can be defined in the template: .RS .PP .TS box; cB | cB lf4 | lf4. Invocation Line in Template _ getdate("11/27/86") %m/%d/%y getdate("27.11.86") %d.%m.%y getdate("86-11-27") %y-%m-%d getdate("Friday 12:00:00") %A %H:%M:%S .TE .RE .PP The following rules apply when converting the input specification into the internal format: .RS .TP 3 \(bu If only the weekday is given, today is assumed if the given day is equal to the current day, and next week if it is less. .TP \(bu If only the month is given, the current month is assumed if the given month is equal to the current month, and next year if it is less and no year is given (the first day of the month is assumed if no day is given). .TP \(bu If no hour, minute and second are given, the current hour, minute and second are assumed. .TP \(bu If no date is given, today is assumed if the given hour is greater than the current hour and tomorrow is assumed if it is less. .RE .PP The following examples help to illustrate the above rules assuming that the current date is .CR "Mon Sep 22 12:19:47 EDT 1986" , and the .CR LC_TIME category is set to the default .CR C locale. .IP .TS box tab(;); cB | cB | cB cB | cB | cB lf4 | lf4 | l . ;Line in; Input;Template;Date _ Mon;%a;Mon Sep 22 12:19:47 EDT 1986 Sun;%a;Sun Sep 28 12:19:47 EDT 1986 Fri;%a;Fri Sep 26 12:19:47 EDT 1986 September;%B;Mon Sep 1 12:19:47 EDT 1986 January;%B;Thu Jan 1 12:19:47 EST 1987 December;%B;Mon Dec 1 12:19:47 EST 1986 Sep Mon;%b %a;Mon Sep 1 12:19:47 EDT 1986 Jan Fri;%b %a;Fri Jan 2 12:19:47 EST 1987 Dec Mon;%b %a;Mon Dec 1 12:19:47 EST 1986 Jan Wed 1989;%b %a %Y;Wed Jan 4 12:19:47 EST 1989 Fri 9;%a %H;Fri Sep 26 09:00:00 EDT 1986 Feb 10:30;%b %H:%S;Sun Feb 1 10:30:00 EST 1987 10:30;%H:%M;Tue Sep 23 10:30:00 EDT 1986 13:30;%H:%M;Mon Sep 22 13:30:00 EDT 1986 .TE .SH ERRORS Upon failure, .CR getdate() returns NULL and the variable .CR getdate_err is set to indicate the error. .PP The following is a complete list of the .CR getdate_err settings and their interpretation: .RS .TP 3 .C 1 the .CR DATEMSK environment variable is null or undefined, .TP .C 2 the template file cannot be opened for reading, .TP .C 3 failed to get file status information, .TP .C 4 the template file is not a regular file, .TP .C 5 an error is encountered while reading the template file, .TP .C 6 memory allocation failed (not enough memory available), .TP .C 7 there is no line in the template that matches the input, .TP .C 8 invalid input specification (example: February 31). .RE .SH WARNINGS The return value for .CR getdate() points to static data whose content is overwritten by each call. Thus, .CR getdate() is unsafe in multi-thread applications. .CR getdate_r() is MT-Safe and should be used instead. .SH SEE ALSO ctime(3C), ctype(3C), setlocale(3C), strftime(3C). .\" .\" index@\f4getdate()\f1 \- convert user format date and time@@@\f3getdate(3C)\f1 .\" index@\f4getdate_r()\f1 \- convert user format date and time@@@\f3getdate(3C)\f1 .\" index@\f1convert user format date and time@@@\f3getdate(3C)\f1 .\" index@\f1user format date and time, convert@@@\f3getdate(3C)\f1 .\" index@\f1format date and time, convert user@@@\f3getdate(3C)\f1 .\" index@\f1date and time, convert user format@@@\f3getdate(3C)\f1 .\" index@\f1time, convert user format date and@@@\f3getdate(3C)\f1 .\" .\" toc@\f3getdate(3C)\f1:\0\0\f4getdate()\f1, \f4getdate_r()\f1@@@convert user format date and time .\" toc@\f4getdate_r()\f1:\0\0convert user format date and time@@@\f1see \f3getdate(3C)\f1 .\" .\" links@getdate.3c getdate_r.3c .\" $Header: getdiskbyna.3c,v 72.6 94/10/17 16:41:12 ssa Exp $ .TA g .TH getdiskbyname 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getdiskbyname(\|), getdiskbyname_r(\|) \- get disk description by its name .SH SYNOPSIS .C "#include " .PP .C "struct disktab *getdiskbyname(const char *name);" .PP .C "int getdiskbyname_r(" .nf .PD 0 .IP .C "const char *name," .C "struct disktab *result," .C "char *buffer," .C "int buflen);" .PD .SH DESCRIPTION .C getdiskbyname() takes a disk name (such as hp7959B) and returns a pointer to a structure that describes its geometry information and the standard disk partition tables. All information is obtained from the disktab database file (see .IR disktab (4)). .PP The contents of the structure .C disktab include the following members. Note that there is not necessarily any correlation between the placement in this list and the order in the structure. .nf .IP .ift .ft 4 .ifn .ft 3 .ps +1 char *d_name; /* drive name */ char *d_type; /* drive type */ int d_secsize; /* sector size in bytes */ int d_ntracks; /* # tracks/cylinder */ int d_nsectors; /* # sectors/track */ int d_ncylinders; /* # cylinders */ int d_rpm; /* revolutions/minute */ struct partition { int p_size; /* #sectors in partition */ short p_bsize; /* block size in bytes */ short p_fsize; /* frag size in bytes */ } d_partitions[NSECTIONS]; .ft .ps .fi .PP The constant .C NSECTIONS is defined in .RC < disktab.h >. .SS Reentrant Interfaces .C getdiskbyname_r() expects to be passed three extra parameters: .PP 1. The address of a .C "struct disktab" where the result will be stored. .PD 0 .PP 2. A buffer to store character strings to which fields in the .C "struct disktab" will point. .PP 3. The length of the user-supplied buffer. .PD .PP A buffer length of 100 is recommended. The .C "struct disktab" is defined in the file .RC < disktab.h >. A -1 will be returned if the end-of-file or an error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH DIAGNOSTICS A .SM NULL pointer is returned in case of an error, or if .I name is not found in the disktab database file. .SH WARNINGS The return value for .C getdiskbyname() points to static data whose content is overwritten by each call. Thus, .C getdiskbyname() is unsafe in multi-thread applications. .C getdiskbyname_r() is MT-Safe and should be used instead. .SH AUTHOR .C getdiskbyname() was developed by HP and the University of California, Berkeley. .SH SEE ALSO disktab(4). .\" .\" toc@\f3getdiskbyname(3C)\f1\0\0:\f4getdiskbyname()\fP@@@get disk description by its name .\" toc@\f4getdiskbyname_r(3C)\fP:\0\0get disk description@@@see \f3getdiskbyname(3C)\f1 .\" .\" index@\f4getdiskbyname()\fP \- get disk description by its name@@@\f3getdiskbyname(3C)\f1 .\" index@get disk description by its name@@@\f3getdiskbyname(3C)\f1 .\" index@disk description by its name, get@@@\f3getdiskbyname(3C)\f1 .\" index@description of disk by its name, get@@@\f3getdiskbyname(3C)\f1 .\" index@name, get disk description by its@@@\f3getdiskbyname(3C)\f1 .\" links@getdiskbyna.3c getdiskbyname_r.3c .\" $Header: getdiskbyna.3c,v 72.6 94/10/17 16:41:12 ssa Exp $ .TA g .TH getdiskbyname 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getdiskbyname(\|), getdiskbyname_r(\|) \- get disk description by its name .SH SYNOPSIS .C "#include " .PP .C "struct disktab *getdiskbyname(const char *name);" .PP .C "int getdiskbyname_r(" .nf .PD 0 .IP .C "const char *name," .C "struct disktab *result," .C "char *buffer," .C "int buflen);" .PD .SH DESCRIPTION .C getdiskbyname() takes a disk name (such as hp7959B) and returns a pointer to a structure that describes its geometry information and the standard disk partition tables. All information is obtained from the disktab database file (see .IR disktab (4)). .PP The contents of the structure .C disktab include the following members. Note that there is not necessarily any correlation between the placement in this list and the order in the structure. .nf .IP .ift .ft 4 .ifn .ft 3 .ps +1 char *d_name; /* drive name */ char *d_type; /* drive type */ int d_secsize; /* sector size in bytes */ int d_ntracks; /* # tracks/cylinder */ int d_nsectors; /* # sectors/track */ int d_ncylinders; /* # cylinders */ int d_rpm; /* revolutions/minute */ struct partition { int p_size; /* #sectors in partition */ short p_bsize; /* block size in bytes */ short p_fsize; /* frag size in bytes */ } d_partitions[NSECTIONS]; .ft .ps .fi .PP The constant .C NSECTIONS is defined in .RC < disktab.h >. .SS Reentrant Interfaces .C getdiskbyname_r() expects to be passed three extra parameters: .PP 1. The address of a .C "struct disktab" where the result will be stored. .PD 0 .PP 2. A buffer to store character strings to which fields in the .C "struct disktab" will point. .PP 3. The length of the user-supplied buffer. .PD .PP A buffer length of 100 is recommended. The .C "struct disktab" is defined in the file .RC < disktab.h >. A -1 will be returned if the end-of-file or an error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH DIAGNOSTICS A .SM NULL pointer is returned in case of an error, or if .I name is not found in the disktab database file. .SH WARNINGS The return value for .C getdiskbyname() points to static data whose content is overwritten by each call. Thus, .C getdiskbyname() is unsafe in multi-thread applications. .C getdiskbyname_r() is MT-Safe and should be used instead. .SH AUTHOR .C getdiskbyname() was developed by HP and the University of California, Berkeley. .SH SEE ALSO disktab(4). .\" .\" toc@\f3getdiskbyname(3C)\f1\0\0:\f4getdiskbyname()\fP@@@get disk description by its name .\" toc@\f4getdiskbyname_r(3C)\fP:\0\0get disk description@@@see \f3getdiskbyname(3C)\f1 .\" .\" index@\f4getdiskbyname()\fP \- get disk description by its name@@@\f3getdiskbyname(3C)\f1 .\" index@get disk description by its name@@@\f3getdiskbyname(3C)\f1 .\" index@disk description by its name, get@@@\f3getdiskbyname(3C)\f1 .\" index@description of disk by its name, get@@@\f3getdiskbyname(3C)\f1 .\" index@name, get disk description by its@@@\f3getdiskbyname(3C)\f1 .\" links@getdiskbyna.3c getdiskbyname_r.3c .\" $Header: getdvagent.3,v 72.3 94/07/05 17:58:22 ssa Exp $ .TA g .TH getdvagent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getdvagent, getdvagnam, setdvagent, enddvagent, putdvagnam, copydvagent \- manipulate device assignment database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct dev_asg \(**getdvagent(\|);" .PP .CR "struct dev_asg \(**getdvagnam(const char \(**name);" .PP .CR "void setdvagent(\|);" .PP .CR "void enddvagent(\|);" .PP .CR "int putdvagnam(const char \(**name, struct dev_asg \(**dv);" .PP .CR "struct dev_asg \(**copydvagent(struct dev_asg \(**dv);" .fi .SH DESCRIPTION .IR getdvagent , .IR getdvagnam , and .I copydvagent each return a pointer to an object with the following structure containing the broken-out fields of an entry in the Device Assignment database. Each database entry is returned as a .I dev_asg structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v struct dev_field { char *fd_name; /* external name */ char **fd_devs; /* device list */ mask_t fd_type[1]; /* tape, printer, terminal */ char **fd_users; /* authorized user list */ }; .IP /* Device Assignment Database entry */ .IP #define \s-1AUTH_DEV_TYPE\s0 "device type" #define \s-1AUTH_DEV_PRINTER\s0 0 #define \s-1AUTH_DEV_TERMINAL\s0 1 #define \s-1AUTH_DEV_TAPE\s0 2 #define \s-1AUTH_DEV_REMOTE\s0 3 #define \s-1AUTH_MAX_DEV_TYPE\s0 3 #define \s-1AUTH_DEV_TYPE_SIZE\s0 (\s-1WORD_OF_BIT\s0 (\s-1AUTH_MAX_DEV_TY PE\s0) + 1) .IP /* this structure tells which of the corresponding fields * in dev_field are valid (filled). */ struct dev_flag { unsigned short fg_name : 1, fg_devs : 1, fg_type : 1, fg_users : 1, ; }; .IP struct dev_asg { struct dev_field ufld; struct dev_flag uflg; struct dev_field sfld; struct dev_flag sflg; }; .fi .PP The Device Assignment database stores device characteristics that are related to user authorizations and synonyms. On systems supporting network connections, the Device Assignment database stores information about hosts initiating connections. .PP Each entry contains a .IR name , which is a cross reference to the terminal control database, and a list of .IR devices , each of which is a pathname corresponding to that device. This list allows the device assignment software of the trusted system to invalidate all references to a device when re-assigning it. The list is a table of character string pointers, whose last entry is a .SM .B NULL pointer. .PP .I fd_users is a pointer to a null-terminated table of character string pointers referring to user allowed access. .PP For trusted system versions supporting network connections, the device name can be a 12 character host name, where the first 8 characters are the .SM ASCII hex address of the device, and the last 4 characters are .SM ASCII zeroes. For example, a host with Internet address 129.75.0.3 has device name 814b00030000. The trailing four zeroes are for compatibility with ports on terminal concentrators. The SAM API's supports conversion of host name to device name. Thus, sensitivity level ranges and user authorization lists can be enforced on hosts as well as on directly connected terminals. .PP When .I getdvagent is first called, it returns a pointer to the first device assignment entry. Thereafter, it returns a pointer to the next entry, so successive calls can be used to search the database. .I getdvagnam searches from the beginning of the database until an entry with a device name matching .I name is found, and returns a pointer to that entry. If an end of file or an error is encountered on reading, these functions return a .SM .B NULL pointer. .I copydvagent copies a device assignment structure and the fields to which it refers to a newly-allocated data area. Since .IR getdvagent , .IR getdvagnam , and .I putdvagent re-use a static structure when accessing the database, the values of any entry must be saved if these routines are used again. The .I dev_asg structure returned by .I copydvagent can be freed using .I free (see .IR malloc (3C) or .IR malloc (3X)). .PP A call to .I setdvagent has the effect of setting the device assignment database back to the first entry, to allow repeated searches of the database. .I enddvagent frees all memory and closes all files used to support these routines. .PP .I putdvagnam rewrites or adds an entry to the database. If there is an entry whose .I fd_name field matches the .I name argument, that entry is replaced with the contents of the .I dv structure. Otherwise, that entry is added to the database. .SH RETURN VALUE .IR getdvagent and .IR getdvagnam return a pointer to a static structure on success, or a .SM .B NULL pointer on failure. This static structure is overwritten by .IR getdvagent , .IR getdvagnam , and .IR putdvagnam . .PP .I putdvagnam returns 1 on success, or 0 on failure. .PP .I copydvagent returns a pointer to the newly-allocated structure on success, or a .SM .B NULL pointer if there was a memory allocation error. .SH "WARNINGS" The structure returned by this routine contains .I pointers to character strings and lists rather than being self-contained. .I copydvagent must be used instead of structure assignments to save a returned structure. .PP The value returned by .I getdvagent and .I getdvagnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using .I copydvagent and supply the modified buffer to .IR putdvagent . .SH NOTES Programs using this routine must be compiled with .BR \-lsec . .SH AUTHOR SecureWare Inc. .SH FILES .TP 40 .CR /tcb/files/devassign Device assignment database .PD .SH SEE ALSO authcap(4). .\" .\" index@\f4getdvagent\f1 \- return pointer for device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f1getdvagnam\f1 \- return success or failure information@@@\f3getdvagent(3)\f1 .\" index@\f4setdvagent\f1 \- set device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f4enddvagent\f1 \- free memory and close file@@@\f3getdvagent(3)\f1 .\" index@\f4putdvagnam\f1 \- add or rewrite device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f4copydvagent\f1 \- copy device assignment structure@@@\f3getdvagent(3)\f1 .\" index@\f1manipulate device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f1device assignment database entry, manipulate@@@\f3getdvagent(3)\f1 .\" index@\f1assignment database entry, manipulate device@@@\f3getdvagent(3)\f1 .\" index@\f1database entry, manipulate device assignment@@@\f3getdvagent(3)\f1 .\" .\" .\" toc@\f3getdvagent(3)\f1:\0\0\f4getdvagent\f1, \f4getdvagnam\f1, \f4setdvagent\f1, \f4enddvagent\f1, \f4putdvagnam\f1, \n\f4copydvagent\f1@@@manipulate device assignment database entry for a trusted system .\" toc@\f4getdvagent\f1:\0\0return pointer for device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4getdvagnam\f1:\0\0return success or failure information@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4setdvagent\f1:\0\0set device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4enddvagent\f1:\0\0free memory and closes file@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4putdvagnam\f1:\0\0add or rewrite device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4copydvagent\f1:\0\0copy device assignment structure@@@\f1see \f3getdvagent(3)\f1 .\" .\" .\" links@getdvagent.3 getdvagnam.3 .\" links@getdvagent.3 setdvagent.3 .\" links@getdvagent.3 enddvagent.3 .\" links@getdvagent.3 putdvagnam.3 .\" links@getdvagent.3 copydvagent.3 .\" .\" fileset_database@getdvagent.3 UX-CORE-MAN .\" $Header: getdvagent.3,v 72.3 94/07/05 17:58:22 ssa Exp $ .TA g .TH getdvagent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getdvagent, getdvagnam, setdvagent, enddvagent, putdvagnam, copydvagent \- manipulate device assignment database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct dev_asg \(**getdvagent(\|);" .PP .CR "struct dev_asg \(**getdvagnam(const char \(**name);" .PP .CR "void setdvagent(\|);" .PP .CR "void enddvagent(\|);" .PP .CR "int putdvagnam(const char \(**name, struct dev_asg \(**dv);" .PP .CR "struct dev_asg \(**copydvagent(struct dev_asg \(**dv);" .fi .SH DESCRIPTION .IR getdvagent , .IR getdvagnam , and .I copydvagent each return a pointer to an object with the following structure containing the broken-out fields of an entry in the Device Assignment database. Each database entry is returned as a .I dev_asg structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v struct dev_field { char *fd_name; /* external name */ char **fd_devs; /* device list */ mask_t fd_type[1]; /* tape, printer, terminal */ char **fd_users; /* authorized user list */ }; .IP /* Device Assignment Database entry */ .IP #define \s-1AUTH_DEV_TYPE\s0 "device type" #define \s-1AUTH_DEV_PRINTER\s0 0 #define \s-1AUTH_DEV_TERMINAL\s0 1 #define \s-1AUTH_DEV_TAPE\s0 2 #define \s-1AUTH_DEV_REMOTE\s0 3 #define \s-1AUTH_MAX_DEV_TYPE\s0 3 #define \s-1AUTH_DEV_TYPE_SIZE\s0 (\s-1WORD_OF_BIT\s0 (\s-1AUTH_MAX_DEV_TY PE\s0) + 1) .IP /* this structure tells which of the corresponding fields * in dev_field are valid (filled). */ struct dev_flag { unsigned short fg_name : 1, fg_devs : 1, fg_type : 1, fg_users : 1, ; }; .IP struct dev_asg { struct dev_field ufld; struct dev_flag uflg; struct dev_field sfld; struct dev_flag sflg; }; .fi .PP The Device Assignment database stores device characteristics that are related to user authorizations and synonyms. On systems supporting network connections, the Device Assignment database stores information about hosts initiating connections. .PP Each entry contains a .IR name , which is a cross reference to the terminal control database, and a list of .IR devices , each of which is a pathname corresponding to that device. This list allows the device assignment software of the trusted system to invalidate all references to a device when re-assigning it. The list is a table of character string pointers, whose last entry is a .SM .B NULL pointer. .PP .I fd_users is a pointer to a null-terminated table of character string pointers referring to user allowed access. .PP For trusted system versions supporting network connections, the device name can be a 12 character host name, where the first 8 characters are the .SM ASCII hex address of the device, and the last 4 characters are .SM ASCII zeroes. For example, a host with Internet address 129.75.0.3 has device name 814b00030000. The trailing four zeroes are for compatibility with ports on terminal concentrators. The SAM API's supports conversion of host name to device name. Thus, sensitivity level ranges and user authorization lists can be enforced on hosts as well as on directly connected terminals. .PP When .I getdvagent is first called, it returns a pointer to the first device assignment entry. Thereafter, it returns a pointer to the next entry, so successive calls can be used to search the database. .I getdvagnam searches from the beginning of the database until an entry with a device name matching .I name is found, and returns a pointer to that entry. If an end of file or an error is encountered on reading, these functions return a .SM .B NULL pointer. .I copydvagent copies a device assignment structure and the fields to which it refers to a newly-allocated data area. Since .IR getdvagent , .IR getdvagnam , and .I putdvagent re-use a static structure when accessing the database, the values of any entry must be saved if these routines are used again. The .I dev_asg structure returned by .I copydvagent can be freed using .I free (see .IR malloc (3C) or .IR malloc (3X)). .PP A call to .I setdvagent has the effect of setting the device assignment database back to the first entry, to allow repeated searches of the database. .I enddvagent frees all memory and closes all files used to support these routines. .PP .I putdvagnam rewrites or adds an entry to the database. If there is an entry whose .I fd_name field matches the .I name argument, that entry is replaced with the contents of the .I dv structure. Otherwise, that entry is added to the database. .SH RETURN VALUE .IR getdvagent and .IR getdvagnam return a pointer to a static structure on success, or a .SM .B NULL pointer on failure. This static structure is overwritten by .IR getdvagent , .IR getdvagnam , and .IR putdvagnam . .PP .I putdvagnam returns 1 on success, or 0 on failure. .PP .I copydvagent returns a pointer to the newly-allocated structure on success, or a .SM .B NULL pointer if there was a memory allocation error. .SH "WARNINGS" The structure returned by this routine contains .I pointers to character strings and lists rather than being self-contained. .I copydvagent must be used instead of structure assignments to save a returned structure. .PP The value returned by .I getdvagent and .I getdvagnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using .I copydvagent and supply the modified buffer to .IR putdvagent . .SH NOTES Programs using this routine must be compiled with .BR \-lsec . .SH AUTHOR SecureWare Inc. .SH FILES .TP 40 .CR /tcb/files/devassign Device assignment database .PD .SH SEE ALSO authcap(4). .\" .\" index@\f4getdvagent\f1 \- return pointer for device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f1getdvagnam\f1 \- return success or failure information@@@\f3getdvagent(3)\f1 .\" index@\f4setdvagent\f1 \- set device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f4enddvagent\f1 \- free memory and close file@@@\f3getdvagent(3)\f1 .\" index@\f4putdvagnam\f1 \- add or rewrite device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f4copydvagent\f1 \- copy device assignment structure@@@\f3getdvagent(3)\f1 .\" index@\f1manipulate device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f1device assignment database entry, manipulate@@@\f3getdvagent(3)\f1 .\" index@\f1assignment database entry, manipulate device@@@\f3getdvagent(3)\f1 .\" index@\f1database entry, manipulate device assignment@@@\f3getdvagent(3)\f1 .\" .\" .\" toc@\f3getdvagent(3)\f1:\0\0\f4getdvagent\f1, \f4getdvagnam\f1, \f4setdvagent\f1, \f4enddvagent\f1, \f4putdvagnam\f1, \n\f4copydvagent\f1@@@manipulate device assignment database entry for a trusted system .\" toc@\f4getdvagent\f1:\0\0return pointer for device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4getdvagnam\f1:\0\0return success or failure information@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4setdvagent\f1:\0\0set device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4enddvagent\f1:\0\0free memory and closes file@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4putdvagnam\f1:\0\0add or rewrite device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4copydvagent\f1:\0\0copy device assignment structure@@@\f1see \f3getdvagent(3)\f1 .\" .\" .\" links@getdvagent.3 getdvagnam.3 .\" links@getdvagent.3 setdvagent.3 .\" links@getdvagent.3 enddvagent.3 .\" links@getdvagent.3 putdvagnam.3 .\" links@getdvagent.3 copydvagent.3 .\" .\" fileset_database@getdvagent.3 UX-CORE-MAN .\" $Header: getenv.3c,v 72.4 94/11/14 15:28:50 ssa Exp $ .TA g .TH getenv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getenv(\|) \- return value for environment name .SH SYNOPSIS .C "#include " .PP .C "char *getenv(const char *name);" .SH DESCRIPTION .C getenv() searches the environment list (see .IR environ (5)) for a string of the form .IC name = value\f1, and returns a pointer to the .I value in the current environment if such a string is present, otherwise a .SM NULL pointer. .I name can be either the desired name, null-terminated, or of the form .IC name = value\f1, in which case .C getenv() uses the portion to the left of the .C = as the search key. .SH WARNINGS .C getenv() returns a pointer to static data which can be overwritten by subsequent calls. .SH SEE ALSO exec(2), putenv(3C), environ(5). .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of characters in .I name as single- and/or multi-byte characters. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH STANDARDS CONFORMANCE .CR getenv() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, POSIX.2, ANSI C" .\" .\" index@\f4getenv()\fP \- return value for environment name@@@\f3getenv(3C)\f1 .\" index@search environment list for value of specified variable name@@@\f3getenv(3C)\f1 .\" index@environment list, search for value of specified variable name@@@\f3getenv(3C)\f1 .\" index@environment variable, search environment list for value of@@@\f3getenv(3C)\f1 .\" index@variable, environment, search environment list for value of@@@\f3getenv(3C)\f1 .\" .\" toc@\f3getenv(3C)\f1:\0\0\f4getenv()\fP@@@return value for environment name .\" .\" fileset_database@getenv.3c PROGRAMING-MAN .\" $Header: exportent.3n,v 74.1 95/01/25 16:26:52 ssa Exp $ .TA e .TH exportent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME exportent(\|), getexportent(\|), setexportent(\|), addexportent(\|), remexportent(\|), endexportent(\|), getexportopt(\|) \- access exported file system information .SH SYNOPSIS .nf .C #include .C #include .PP .C "FILE *setexportent();" .PP .C "struct exportent *getexportent(FILE *fildep);" .PP .C "int addexportent(FILE *filep, char *dirname, char *options);" .PP .C "int remexportent(FILE *filep, char *dirname);" .PP .C "char *getexportopt(struct exportent *xent, char *opt);" .PP .C "void endexportent(FILE *filep);" .fi .SH DESCRIPTION These routines access the exported filesystem information in .CR /etc/xtab . .ift .TP 22 .ifn .TP 10 .C setexportent() Open the export information file and return a file pointer to use with .CR getexportent() , .CR addexportent() , .CR remexportent() , and .CR endexportent() . Returns .SM NULL if the file is locked or if an error is encountered in opening the file. .TP .C getexportent() Read the next line from .I filep and return a pointer to an object with the following structure containing the broken-out fields of a line in file .CR /etc/xtab . The fields have meanings described in .IR exports (4). .nf .IP .ift .ft 4 .ifn .ft 3 #define ACCESS_OPT "access" /* machines that can mount fs */ #define ROOT_OPT "root" /* machines with root access to fs */ #define RO_OPT "ro" /* export read-only */ #define ANON_OPT "anon" /* uid for anonymous requests */ #define ASYNC_OPT "async" /* all mounts will be aynchronous */ .ift .sp .5v .ifn .sp 1v struct exportent { char *xent_dirname; /* directory (or file) to export */ char *xent_options; /* options, as above */ }; .ft .fi .IP .C getexportent() returns .SM NULL if it encounters end of file. .TP .C addexportent() Add the .I exportent to the end of the open file .IR filep . It returns 0 if successful and \(mi1 on failure. .TP .C remexportent() Remove the indicated entry from the list. Returns 0 on success and \(mi1 on failure. .TP .C getexportopt() Scans the .C xent_options field of the .C exportent structure for a substring that matches .IR opt . Returns the string value of .IR opt , or .SM NULL if the option is not found. .TP .C endexportent() Close the file. .SH RETURN VALUE .CR setexportent() , .CR getexportent() , and .C getexportopt() return a .SM NULL pointer on .SM EOF or error. .PP .C addexportent() and .C remexportent() return \(mi1 if they fail. .SH WARNINGS The returned .C exportent structure points to static information that is overwritten in each call. .SH AUTHOR .CR exportent , .CR getexportent() , .CR setexportent() , .CR addexportent() , .CR remexportent() , .CR endexportent() , and .C getexportopt() were developed by Sun Microsystems, Inc. .SH FILES .C /etc/exports .C /etc/xtab .SH SEE ALSO exportfs(1M), exports(4). .\" .\" toc@\f3exportent(3N)\f1:\0\0\f4exportent(\|)\f1, \f4getexportent(\|)\f1, \f4setexportent(\|)\f1, \f4addexportent(\|)\f1, \f4remexportent(\|)\f1,\n\f4endexportent(\|)\f1, \f4getexportopt(\|)\f1@@@access exported file system information .\" toc@\f4getexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4setexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4addexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4remexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4endexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4getexportopt(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" .\" index@\f4exportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4getexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4setexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4addexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4remexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4endexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4getexportopt(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@access exported file system information@@@\f3exportent(3N)\f1 .\" index@exported file system information, access@@@\f3exportent(3N)\f1 .\" index@file system information, access exported@@@\f3exportent(3N)\f1 .\" index@information, access exported file system@@@\f3exportent(3N)\f1 .\" .\" links@exportent.3n getexporten.3n .\" links@exportent.3n setexporten.3n .\" links@exportent.3n addexporten.3n .\" links@exportent.3n remexporten.3n .\" links@exportent.3n endexporten.3n .\" links@exportent.3n getexportop.3n .\" .\" fileset_database@exportent.3n PROGRAMING-MAN .\" $Header: exportent.3n,v 74.1 95/01/25 16:26:52 ssa Exp $ .TA e .TH exportent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME exportent(\|), getexportent(\|), setexportent(\|), addexportent(\|), remexportent(\|), endexportent(\|), getexportopt(\|) \- access exported file system information .SH SYNOPSIS .nf .C #include .C #include .PP .C "FILE *setexportent();" .PP .C "struct exportent *getexportent(FILE *fildep);" .PP .C "int addexportent(FILE *filep, char *dirname, char *options);" .PP .C "int remexportent(FILE *filep, char *dirname);" .PP .C "char *getexportopt(struct exportent *xent, char *opt);" .PP .C "void endexportent(FILE *filep);" .fi .SH DESCRIPTION These routines access the exported filesystem information in .CR /etc/xtab . .ift .TP 22 .ifn .TP 10 .C setexportent() Open the export information file and return a file pointer to use with .CR getexportent() , .CR addexportent() , .CR remexportent() , and .CR endexportent() . Returns .SM NULL if the file is locked or if an error is encountered in opening the file. .TP .C getexportent() Read the next line from .I filep and return a pointer to an object with the following structure containing the broken-out fields of a line in file .CR /etc/xtab . The fields have meanings described in .IR exports (4). .nf .IP .ift .ft 4 .ifn .ft 3 #define ACCESS_OPT "access" /* machines that can mount fs */ #define ROOT_OPT "root" /* machines with root access to fs */ #define RO_OPT "ro" /* export read-only */ #define ANON_OPT "anon" /* uid for anonymous requests */ #define ASYNC_OPT "async" /* all mounts will be aynchronous */ .ift .sp .5v .ifn .sp 1v struct exportent { char *xent_dirname; /* directory (or file) to export */ char *xent_options; /* options, as above */ }; .ft .fi .IP .C getexportent() returns .SM NULL if it encounters end of file. .TP .C addexportent() Add the .I exportent to the end of the open file .IR filep . It returns 0 if successful and \(mi1 on failure. .TP .C remexportent() Remove the indicated entry from the list. Returns 0 on success and \(mi1 on failure. .TP .C getexportopt() Scans the .C xent_options field of the .C exportent structure for a substring that matches .IR opt . Returns the string value of .IR opt , or .SM NULL if the option is not found. .TP .C endexportent() Close the file. .SH RETURN VALUE .CR setexportent() , .CR getexportent() , and .C getexportopt() return a .SM NULL pointer on .SM EOF or error. .PP .C addexportent() and .C remexportent() return \(mi1 if they fail. .SH WARNINGS The returned .C exportent structure points to static information that is overwritten in each call. .SH AUTHOR .CR exportent , .CR getexportent() , .CR setexportent() , .CR addexportent() , .CR remexportent() , .CR endexportent() , and .C getexportopt() were developed by Sun Microsystems, Inc. .SH FILES .C /etc/exports .C /etc/xtab .SH SEE ALSO exportfs(1M), exports(4). .\" .\" toc@\f3exportent(3N)\f1:\0\0\f4exportent(\|)\f1, \f4getexportent(\|)\f1, \f4setexportent(\|)\f1, \f4addexportent(\|)\f1, \f4remexportent(\|)\f1,\n\f4endexportent(\|)\f1, \f4getexportopt(\|)\f1@@@access exported file system information .\" toc@\f4getexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4setexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4addexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4remexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4endexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4getexportopt(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" .\" index@\f4exportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4getexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4setexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4addexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4remexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4endexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4getexportopt(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@access exported file system information@@@\f3exportent(3N)\f1 .\" index@exported file system information, access@@@\f3exportent(3N)\f1 .\" index@file system information, access exported@@@\f3exportent(3N)\f1 .\" index@information, access exported file system@@@\f3exportent(3N)\f1 .\" .\" links@exportent.3n getexporten.3n .\" links@exportent.3n setexporten.3n .\" links@exportent.3n addexporten.3n .\" links@exportent.3n remexporten.3n .\" links@exportent.3n endexporten.3n .\" links@exportent.3n getexportop.3n .\" .\" fileset_database@exportent.3n PROGRAMING-MAN .\" $Header: getfsent.3x,v 72.4 94/11/02 14:55:23 ssa Exp $ .TA g .TH getfsent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getfsent(\|), getfsspec(\|), getfsfile(\|), getfstype(\|), setfsent(\|), endfsent(\|) \- get file system descriptor file entry .SH SYNOPSIS .C "#include " .PP .C "struct checklist *getfsent(void);" .PP .C "struct checklist *getfsspec(const char *spec);" .PP .C "struct checklist *getfsfile(const char *file);" .PP .C "struct checklist *getfstype(const char *type);" .PP .C "int setfsent(void);" .PP .C "int endfsent(void);" .SS Remarks: These routines are included only for compatibility with 4.2 .SM BSD. For maximum portability and improved functionality, new applications should use the .IR getmntent (3X) library routines. .SH DESCRIPTION .CR getfsent() , .CR getfsspec() , .CR getfsfile() , and .C getfstype() each returns a pointer to an object with the following structure containing the broken-out fields of a line in the .C /etc/fstab file. The structure is declared in the .RC < checklist.h > header file: .nf .IP .C "struct checklist {" .C " char *fs_spec; /* special file name */" .C " char *fs_bspec; /* block special file name */" .C " char *fs_dir; /* file sys directory name */" .C " char *fs_type; /* type: ro, rw, sw, xx */" .C " int fs_passno; /* fsck pass number */" .C " int fs_freq; /* backup frequency */" .C }; .fi .PP The fields have meanings described in .IR fstab (4). If the block special file name, the file system directory name, and the type are not all defined on the associated line in .CR /etc/fstab , these routines return pointers to .SM NULL in the .CR fs_bspec , .CR fs_dir , and .C fs_type fields. If the pass number or the backup frequency field are not present on the line, these routines return \(mi1 in the corresponding structure member. .C fs_freq is reserved for future use. .TP 20 .C getfsent() Reads the next line of the file, opening the file if necessary. .TP .C setfsent() Opens and rewinds the file. .TP .C endfsent() Closes the file. .TP .C getfsspec() Sequentially searches from beginning of file until a matching special file name is found, or until .SM EOF is encountered. .TP .C getfsfile() Sequentially searches from the beginning of the file until a matching file system file name is found, or until .SM EOF is encountered. .C getfstype() Sequentially searches from the beginning of the file until a matching file system type field is found, or until .SM EOF is encountered. .SH DIAGNOSTICS A null pointer is returned on .SM EOF, invalid entry, or error. .SH WARNINGS Since all information is contained in a static area, it must be copied to be saved. .SH AUTHOR .C getfsent() was developed by HP and the University of California, Berkeley. .SH FILES .C /etc/fstab .SH SEE ALSO fstab(4). .\" index@\f4getfsent()\fP \- get next line in file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@\f4getfsspec()\fP \- search descriptor file for special (device) file entry@@@\f3getfsent(3X)\f1 .\" index@\f4getfsfile()\fP \- search descriptor file for ordinary file entry@@@\f3getfsent(3X)\f1 .\" index@\f4getfstype()\fP \- search descriptor file for specified file type entry@@@\f3getfsent(3X)\f1 .\" index@\f4setfsent()\fP \- open and rewind file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@\f4endfsent()\fP \- close file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@get: file system descriptor file entry (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@file system: get file system descriptor file entry (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@descriptor file entry, get file system (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@file entry, get file system descriptor (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@entry, get file system descriptor file (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" .\" toc@\f3getfsent(3X)\f1:\0\0\f4getfsent()\fP, \f4getfsspec()\fP, \f4getfsfile()\fP, \f4getfstype()\fP,\n\f4setfsent()\fP, \f4endfsent()\fP@@@get file system descriptor file entry .\" toc@\f4getfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfsspec()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfsfile()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfstype()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4setfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4endfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" .\" links@getfsent.3x getfsspec.3x .\" links@getfsent.3x getfsfile.3x .\" links@getfsent.3x getfstype.3x .\" links@getfsent.3x setfsent.3x .\" links@getfsent.3x endfsent.3x .\" .\" fileset_database@getfsent.3x PROGRAMING-MAN .\" $Header: getfsent.3x,v 72.4 94/11/02 14:55:23 ssa Exp $ .TA g .TH getfsent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getfsent(\|), getfsspec(\|), getfsfile(\|), getfstype(\|), setfsent(\|), endfsent(\|) \- get file system descriptor file entry .SH SYNOPSIS .C "#include " .PP .C "struct checklist *getfsent(void);" .PP .C "struct checklist *getfsspec(const char *spec);" .PP .C "struct checklist *getfsfile(const char *file);" .PP .C "struct checklist *getfstype(const char *type);" .PP .C "int setfsent(void);" .PP .C "int endfsent(void);" .SS Remarks: These routines are included only for compatibility with 4.2 .SM BSD. For maximum portability and improved functionality, new applications should use the .IR getmntent (3X) library routines. .SH DESCRIPTION .CR getfsent() , .CR getfsspec() , .CR getfsfile() , and .C getfstype() each returns a pointer to an object with the following structure containing the broken-out fields of a line in the .C /etc/fstab file. The structure is declared in the .RC < checklist.h > header file: .nf .IP .C "struct checklist {" .C " char *fs_spec; /* special file name */" .C " char *fs_bspec; /* block special file name */" .C " char *fs_dir; /* file sys directory name */" .C " char *fs_type; /* type: ro, rw, sw, xx */" .C " int fs_passno; /* fsck pass number */" .C " int fs_freq; /* backup frequency */" .C }; .fi .PP The fields have meanings described in .IR fstab (4). If the block special file name, the file system directory name, and the type are not all defined on the associated line in .CR /etc/fstab , these routines return pointers to .SM NULL in the .CR fs_bspec , .CR fs_dir , and .C fs_type fields. If the pass number or the backup frequency field are not present on the line, these routines return \(mi1 in the corresponding structure member. .C fs_freq is reserved for future use. .TP 20 .C getfsent() Reads the next line of the file, opening the file if necessary. .TP .C setfsent() Opens and rewinds the file. .TP .C endfsent() Closes the file. .TP .C getfsspec() Sequentially searches from beginning of file until a matching special file name is found, or until .SM EOF is encountered. .TP .C getfsfile() Sequentially searches from the beginning of the file until a matching file system file name is found, or until .SM EOF is encountered. .C getfstype() Sequentially searches from the beginning of the file until a matching file system type field is found, or until .SM EOF is encountered. .SH DIAGNOSTICS A null pointer is returned on .SM EOF, invalid entry, or error. .SH WARNINGS Since all information is contained in a static area, it must be copied to be saved. .SH AUTHOR .C getfsent() was developed by HP and the University of California, Berkeley. .SH FILES .C /etc/fstab .SH SEE ALSO fstab(4). .\" index@\f4getfsent()\fP \- get next line in file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@\f4getfsspec()\fP \- search descriptor file for special (device) file entry@@@\f3getfsent(3X)\f1 .\" index@\f4getfsfile()\fP \- search descriptor file for ordinary file entry@@@\f3getfsent(3X)\f1 .\" index@\f4getfstype()\fP \- search descriptor file for specified file type entry@@@\f3getfsent(3X)\f1 .\" index@\f4setfsent()\fP \- open and rewind file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@\f4endfsent()\fP \- close file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@get: file system descriptor file entry (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@file system: get file system descriptor file entry (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@descriptor file entry, get file system (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@file entry, get file system descriptor (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@entry, get file system descriptor file (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" .\" toc@\f3getfsent(3X)\f1:\0\0\f4getfsent()\fP, \f4getfsspec()\fP, \f4getfsfile()\fP, \f4getfstype()\fP,\n\f4setfsent()\fP, \f4endfsent()\fP@@@get file system descriptor file entry .\" toc@\f4getfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfsspec()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfsfile()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfstype()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4setfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4endfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" .\" links@getfsent.3x getfsspec.3x .\" links@getfsent.3x getfsfile.3x .\" links@getfsent.3x getfstype.3x .\" links@getfsent.3x setfsent.3x .\" links@getfsent.3x endfsent.3x .\" .\" fileset_database@getfsent.3x PROGRAMING-MAN .\" $Header: getfsent.3x,v 72.4 94/11/02 14:55:23 ssa Exp $ .TA g .TH getfsent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getfsent(\|), getfsspec(\|), getfsfile(\|), getfstype(\|), setfsent(\|), endfsent(\|) \- get file system descriptor file entry .SH SYNOPSIS .C "#include " .PP .C "struct checklist *getfsent(void);" .PP .C "struct checklist *getfsspec(const char *spec);" .PP .C "struct checklist *getfsfile(const char *file);" .PP .C "struct checklist *getfstype(const char *type);" .PP .C "int setfsent(void);" .PP .C "int endfsent(void);" .SS Remarks: These routines are included only for compatibility with 4.2 .SM BSD. For maximum portability and improved functionality, new applications should use the .IR getmntent (3X) library routines. .SH DESCRIPTION .CR getfsent() , .CR getfsspec() , .CR getfsfile() , and .C getfstype() each returns a pointer to an object with the following structure containing the broken-out fields of a line in the .C /etc/fstab file. The structure is declared in the .RC < checklist.h > header file: .nf .IP .C "struct checklist {" .C " char *fs_spec; /* special file name */" .C " char *fs_bspec; /* block special file name */" .C " char *fs_dir; /* file sys directory name */" .C " char *fs_type; /* type: ro, rw, sw, xx */" .C " int fs_passno; /* fsck pass number */" .C " int fs_freq; /* backup frequency */" .C }; .fi .PP The fields have meanings described in .IR fstab (4). If the block special file name, the file system directory name, and the type are not all defined on the associated line in .CR /etc/fstab , these routines return pointers to .SM NULL in the .CR fs_bspec , .CR fs_dir , and .C fs_type fields. If the pass number or the backup frequency field are not present on the line, these routines return \(mi1 in the corresponding structure member. .C fs_freq is reserved for future use. .TP 20 .C getfsent() Reads the next line of the file, opening the file if necessary. .TP .C setfsent() Opens and rewinds the file. .TP .C endfsent() Closes the file. .TP .C getfsspec() Sequentially searches from beginning of file until a matching special file name is found, or until .SM EOF is encountered. .TP .C getfsfile() Sequentially searches from the beginning of the file until a matching file system file name is found, or until .SM EOF is encountered. .C getfstype() Sequentially searches from the beginning of the file until a matching file system type field is found, or until .SM EOF is encountered. .SH DIAGNOSTICS A null pointer is returned on .SM EOF, invalid entry, or error. .SH WARNINGS Since all information is contained in a static area, it must be copied to be saved. .SH AUTHOR .C getfsent() was developed by HP and the University of California, Berkeley. .SH FILES .C /etc/fstab .SH SEE ALSO fstab(4). .\" index@\f4getfsent()\fP \- get next line in file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@\f4getfsspec()\fP \- search descriptor file for special (device) file entry@@@\f3getfsent(3X)\f1 .\" index@\f4getfsfile()\fP \- search descriptor file for ordinary file entry@@@\f3getfsent(3X)\f1 .\" index@\f4getfstype()\fP \- search descriptor file for specified file type entry@@@\f3getfsent(3X)\f1 .\" index@\f4setfsent()\fP \- open and rewind file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@\f4endfsent()\fP \- close file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@get: file system descriptor file entry (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@file system: get file system descriptor file entry (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@descriptor file entry, get file system (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@file entry, get file system descriptor (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@entry, get file system descriptor file (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" .\" toc@\f3getfsent(3X)\f1:\0\0\f4getfsent()\fP, \f4getfsspec()\fP, \f4getfsfile()\fP, \f4getfstype()\fP,\n\f4setfsent()\fP, \f4endfsent()\fP@@@get file system descriptor file entry .\" toc@\f4getfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfsspec()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfsfile()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfstype()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4setfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4endfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" .\" links@getfsent.3x getfsspec.3x .\" links@getfsent.3x getfsfile.3x .\" links@getfsent.3x getfstype.3x .\" links@getfsent.3x setfsent.3x .\" links@getfsent.3x endfsent.3x .\" .\" fileset_database@getfsent.3x PROGRAMING-MAN .\" $Header: getfsent.3x,v 72.4 94/11/02 14:55:23 ssa Exp $ .TA g .TH getfsent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getfsent(\|), getfsspec(\|), getfsfile(\|), getfstype(\|), setfsent(\|), endfsent(\|) \- get file system descriptor file entry .SH SYNOPSIS .C "#include " .PP .C "struct checklist *getfsent(void);" .PP .C "struct checklist *getfsspec(const char *spec);" .PP .C "struct checklist *getfsfile(const char *file);" .PP .C "struct checklist *getfstype(const char *type);" .PP .C "int setfsent(void);" .PP .C "int endfsent(void);" .SS Remarks: These routines are included only for compatibility with 4.2 .SM BSD. For maximum portability and improved functionality, new applications should use the .IR getmntent (3X) library routines. .SH DESCRIPTION .CR getfsent() , .CR getfsspec() , .CR getfsfile() , and .C getfstype() each returns a pointer to an object with the following structure containing the broken-out fields of a line in the .C /etc/fstab file. The structure is declared in the .RC < checklist.h > header file: .nf .IP .C "struct checklist {" .C " char *fs_spec; /* special file name */" .C " char *fs_bspec; /* block special file name */" .C " char *fs_dir; /* file sys directory name */" .C " char *fs_type; /* type: ro, rw, sw, xx */" .C " int fs_passno; /* fsck pass number */" .C " int fs_freq; /* backup frequency */" .C }; .fi .PP The fields have meanings described in .IR fstab (4). If the block special file name, the file system directory name, and the type are not all defined on the associated line in .CR /etc/fstab , these routines return pointers to .SM NULL in the .CR fs_bspec , .CR fs_dir , and .C fs_type fields. If the pass number or the backup frequency field are not present on the line, these routines return \(mi1 in the corresponding structure member. .C fs_freq is reserved for future use. .TP 20 .C getfsent() Reads the next line of the file, opening the file if necessary. .TP .C setfsent() Opens and rewinds the file. .TP .C endfsent() Closes the file. .TP .C getfsspec() Sequentially searches from beginning of file until a matching special file name is found, or until .SM EOF is encountered. .TP .C getfsfile() Sequentially searches from the beginning of the file until a matching file system file name is found, or until .SM EOF is encountered. .C getfstype() Sequentially searches from the beginning of the file until a matching file system type field is found, or until .SM EOF is encountered. .SH DIAGNOSTICS A null pointer is returned on .SM EOF, invalid entry, or error. .SH WARNINGS Since all information is contained in a static area, it must be copied to be saved. .SH AUTHOR .C getfsent() was developed by HP and the University of California, Berkeley. .SH FILES .C /etc/fstab .SH SEE ALSO fstab(4). .\" index@\f4getfsent()\fP \- get next line in file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@\f4getfsspec()\fP \- search descriptor file for special (device) file entry@@@\f3getfsent(3X)\f1 .\" index@\f4getfsfile()\fP \- search descriptor file for ordinary file entry@@@\f3getfsent(3X)\f1 .\" index@\f4getfstype()\fP \- search descriptor file for specified file type entry@@@\f3getfsent(3X)\f1 .\" index@\f4setfsent()\fP \- open and rewind file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@\f4endfsent()\fP \- close file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@get: file system descriptor file entry (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@file system: get file system descriptor file entry (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@descriptor file entry, get file system (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@file entry, get file system descriptor (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@entry, get file system descriptor file (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" .\" toc@\f3getfsent(3X)\f1:\0\0\f4getfsent()\fP, \f4getfsspec()\fP, \f4getfsfile()\fP, \f4getfstype()\fP,\n\f4setfsent()\fP, \f4endfsent()\fP@@@get file system descriptor file entry .\" toc@\f4getfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfsspec()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfsfile()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfstype()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4setfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4endfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" .\" links@getfsent.3x getfsspec.3x .\" links@getfsent.3x getfsfile.3x .\" links@getfsent.3x getfstype.3x .\" links@getfsent.3x setfsent.3x .\" links@getfsent.3x endfsent.3x .\" .\" fileset_database@getfsent.3x PROGRAMING-MAN .\" $Header: getgrent.3c,v 76.1 95/07/05 17:29:02 ssa Exp $ .TA g .TH getgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getgrent(\|), getgrent_r(\|), getgrgid(\|), getgrgid_r(\|), getgrnam(\|), getgrnam_r(\|), setgrent(\|), setgrent_r(\|), endgrent(\|), endgrent_r(\|), fgetgrent(\|), fgetgrent_r(\|) \- get group file entry .SH SYNOPSIS .C "#include " .PP .C "struct group *getgrent(void);" .PD 0 .PP .C "int getgrent_r(" .nf .PD 0 .IP .C "struct group *result," .C "char *buffer," .C "int buflen," .C "FILE **grfp);" .PD 0 .PP .C "struct group *getgrgid(gid_t gid);" .PP .C "int getgrgid_r(" .nf .PD 0 .IP .C "gid_t gid," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "struct group *getgrnam(const char *name);" .PP .C "int getgrnam_r(" .nf .PD 0 .IP .C "const char *name," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "void setgrent(void);" .PP .C "void setgrent_r(FILE **grfp);" .PP .C "void endgrent(void);" .PP .C "void endgrent_r(FILE **grfp);" .PP .C "struct group *fgetgrent(FILE *stream);" .PP .C "int fgetgrent_r(" .nf .PD 0 .IP .C "FILE *stream," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD .SH DESCRIPTION .CR getgrent() , .CR getgrgid() , and .CR getgrnam() locate an entry in the .CR /etc/group file, and return a pointer to an object of type .CR "struct group" . .PP The .CR group structure is defined in .RC < grp.h > and includes the following members: .nf .IP .C "char *gr_name; /* the name of the group */" .C "char *gr_passwd; /* the encrypted group password */" .C "gid_t gr_gid; /* the numerical group \s-1ID\s+1 */" .C "char **gr_mem; /* null-terminated array of pointers" .C " to member names */" .fi .TP 20 .C getgrent() When first called, .CR getgrent() returns a pointer to the first .CR group structure in the file; thereafter, it returns a pointer to the next .CR group structure in the file. In this way, successive calls can be used to search the entire file. .CR getgrent() opens the .CR /etc/group file prior to doing its work and leaves the file open afterward; .TP .C setgrent() Has the effect of rewinding this file to allow repeated searches; .TP .C endgrent() Can be called to close the file when processing is complete. .TP .C getgrgid() Searches from the beginning of the file until a numeric group ID matching .I gid is found, and returns a pointer to the particular structure in which it was found. .TP .C getgrnam() Searches from the beginning of the file until a group name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .C fgetgrent() Returns a pointer to the next .CR group structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/group . .SS Reentrant Interfaces .CR getgrgid_r() , .CR getgrnam_r() and .CR fgetgrent_r() expect to be passed three extra parameters: .PD 0 .TP 3 1. The address of a .C "struct group" where the result will be stored; .TP 2. A buffer to store character strings, such as the group name, to which fields in the .C "struct group" will point; .TP 3. The length of the user-supplied buffer. .PD .PP In addition to the above three parameters, .CR getgrent_r() requires a pointer to a .I "(FILE *)" variable into which is stored the result of an .I fopen() call on the .CR /etc/group file. This parameter allows threads to independently scan through the .CR /etc/group file. .CR setgrent_r() and .CR endgrent_r() are to be used only in conjunction with .CR getgrent_r() and take the same pointer to a .I "(FILE *)" variable as a parameter. .CR setgrent_r() can be used to rewind or open the .CR /etc/group file. .CR endgrent_r() must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .I "(FILE *)" variable must be initialized to NULL before it is passed to either .CR getgrent_r() or .CR setgrent_r() for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH NETWORKING FEATURES .SS NFS If an entry beginning with a plus sign .RC ( + ) or a minus sign .RC (\| \(mi \|) is found, these routines try to use the Network Information Service network database for data. See .IR group (4) for proper syntax and operation. .SH RETURN VALUE .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .CR group structure. .PP .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , and .CR fgetgrent_r() return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getgrent() , .CR getgrgid() , .CR getgrnam() and .CR fgetgrent() fail if any of the following are true: .RS .TP 12 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX file descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .PD .RE .SH EXAMPLE The following code excerpt counts the number of entries in the .CR /etc/group file: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct group gpbuf; char buffer[1024]; FILE *grf = NULL; setgrent_r(&grf); while (getgrent_r(&gpbuf, buffer, sizeof(buffer), &grf) != -1) count++; endgrent_r(&grf); .ft .ps .fi .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library. This causes them to increase the size of programs that do not otherwise use standard I/O and Network Information Service more than might ordinarily be expected. .PP The value returned by .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() points to a single static area that is overwritten by each call to any of the functions. It must be copied if it is to be saved. .PP .CR getgrent() , .CR getgrgid() , .CR getgrnam() , .CR setgrent() , .CR endgrent() , and .CR fgetgrent() are unsafe in multi-thread applications. .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , .CR setgrent_r() , .CR endgrent_r() , and .CR fgetgrent_r() are MT-Safe and should be used instead. .PP Users of .CR getgrent_r() and .CR getgrnam_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH DEPENDENCIES .SS NFS: .br .B FILES .RS .CI /var/yp/ domainname /group.byname .br .CI /var/yp/ domainname /group.bygid .RE .SM .B SEE ALSO: .RS ypcat(1). .RE .SH FILES .C /etc/group .SH SEE ALSO getgroups(2), getpwent(3C), stdio(3S), group(4). .SH STANDARDS CONFORMANCE .CR getgrent() ": SVID2, SVID3, XPG2" .PP .CR endgrent() ": SVID2, SVID3, XPG2" .PP .CR fgetgrent() ": SVID2, SVID3, XPG2" .PP .CR getgrgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgrnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setgrent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getgrent()\f1 \- get next entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4fgetgrent()\f1 \- get next entry in \f4group()\f1-file-formatted input stream@@@\f3getgrent(3C)\f1 .\" index@\f4getgrgid()\f1 \- get entry from \f4group()\f1 file that matches \f4gid()\fP@@@\f3getgrent(3C)\f1 .\" index@\f4getgrnam()\f1 \- get entry from \f4group()\fP file that matches group name \f4name()\f1@@@\f3getgrent(3C)\f1 .\" index@\f4setgrent()\f1 \- rewind pointer to first entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4endgrent()\f1 \- close currently open \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@get: entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@entry from \f4group()\f1 file, get@@@\f3getgrent(3C)\f1 .\" index@\f4group()\f1 file, get entry from@@@\f3getgrent(3C)\f1 .\" index@file, group: get entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" .\" toc@\f3getgrent(3C)\f1:\0\0\f4getgrent()\f1, \f4getgrgid()\f1, \f4getgrnam()\f1, \f4setgrent()\f1, \f4endgrent()\f1,\n \f4fgetgrent()\f1@@@get group file entry .\" toc@\f4getgrgid()\fP, \f4getgrnam()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4setgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4endgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4fgetgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" .\" links@getgrent.3c getgrent_r.3c .\" links@getgrent.3c getgrgid.3c .\" links@getgrent.3c getgrgid_r.3c .\" links@getgrent.3c getgrnam.3c .\" links@getgrent.3c getgrnam_r.3c .\" links@getgrent.3c setgrent.3c .\" links@getgrent.3c setgrent_r.3c .\" links@getgrent.3c endgrent.3c .\" links@getgrent.3c endgrent_r.3c .\" links@getgrent.3c fgetgrent.3c .\" links@getgrent.3c fgetgrent_r.3c .\" .\" fileset_database@getgrent.3c PROGRAMING-MAN .\" $Header: getgrent.3c,v 76.1 95/07/05 17:29:02 ssa Exp $ .TA g .TH getgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getgrent(\|), getgrent_r(\|), getgrgid(\|), getgrgid_r(\|), getgrnam(\|), getgrnam_r(\|), setgrent(\|), setgrent_r(\|), endgrent(\|), endgrent_r(\|), fgetgrent(\|), fgetgrent_r(\|) \- get group file entry .SH SYNOPSIS .C "#include " .PP .C "struct group *getgrent(void);" .PD 0 .PP .C "int getgrent_r(" .nf .PD 0 .IP .C "struct group *result," .C "char *buffer," .C "int buflen," .C "FILE **grfp);" .PD 0 .PP .C "struct group *getgrgid(gid_t gid);" .PP .C "int getgrgid_r(" .nf .PD 0 .IP .C "gid_t gid," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "struct group *getgrnam(const char *name);" .PP .C "int getgrnam_r(" .nf .PD 0 .IP .C "const char *name," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "void setgrent(void);" .PP .C "void setgrent_r(FILE **grfp);" .PP .C "void endgrent(void);" .PP .C "void endgrent_r(FILE **grfp);" .PP .C "struct group *fgetgrent(FILE *stream);" .PP .C "int fgetgrent_r(" .nf .PD 0 .IP .C "FILE *stream," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD .SH DESCRIPTION .CR getgrent() , .CR getgrgid() , and .CR getgrnam() locate an entry in the .CR /etc/group file, and return a pointer to an object of type .CR "struct group" . .PP The .CR group structure is defined in .RC < grp.h > and includes the following members: .nf .IP .C "char *gr_name; /* the name of the group */" .C "char *gr_passwd; /* the encrypted group password */" .C "gid_t gr_gid; /* the numerical group \s-1ID\s+1 */" .C "char **gr_mem; /* null-terminated array of pointers" .C " to member names */" .fi .TP 20 .C getgrent() When first called, .CR getgrent() returns a pointer to the first .CR group structure in the file; thereafter, it returns a pointer to the next .CR group structure in the file. In this way, successive calls can be used to search the entire file. .CR getgrent() opens the .CR /etc/group file prior to doing its work and leaves the file open afterward; .TP .C setgrent() Has the effect of rewinding this file to allow repeated searches; .TP .C endgrent() Can be called to close the file when processing is complete. .TP .C getgrgid() Searches from the beginning of the file until a numeric group ID matching .I gid is found, and returns a pointer to the particular structure in which it was found. .TP .C getgrnam() Searches from the beginning of the file until a group name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .C fgetgrent() Returns a pointer to the next .CR group structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/group . .SS Reentrant Interfaces .CR getgrgid_r() , .CR getgrnam_r() and .CR fgetgrent_r() expect to be passed three extra parameters: .PD 0 .TP 3 1. The address of a .C "struct group" where the result will be stored; .TP 2. A buffer to store character strings, such as the group name, to which fields in the .C "struct group" will point; .TP 3. The length of the user-supplied buffer. .PD .PP In addition to the above three parameters, .CR getgrent_r() requires a pointer to a .I "(FILE *)" variable into which is stored the result of an .I fopen() call on the .CR /etc/group file. This parameter allows threads to independently scan through the .CR /etc/group file. .CR setgrent_r() and .CR endgrent_r() are to be used only in conjunction with .CR getgrent_r() and take the same pointer to a .I "(FILE *)" variable as a parameter. .CR setgrent_r() can be used to rewind or open the .CR /etc/group file. .CR endgrent_r() must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .I "(FILE *)" variable must be initialized to NULL before it is passed to either .CR getgrent_r() or .CR setgrent_r() for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH NETWORKING FEATURES .SS NFS If an entry beginning with a plus sign .RC ( + ) or a minus sign .RC (\| \(mi \|) is found, these routines try to use the Network Information Service network database for data. See .IR group (4) for proper syntax and operation. .SH RETURN VALUE .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .CR group structure. .PP .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , and .CR fgetgrent_r() return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getgrent() , .CR getgrgid() , .CR getgrnam() and .CR fgetgrent() fail if any of the following are true: .RS .TP 12 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX file descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .PD .RE .SH EXAMPLE The following code excerpt counts the number of entries in the .CR /etc/group file: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct group gpbuf; char buffer[1024]; FILE *grf = NULL; setgrent_r(&grf); while (getgrent_r(&gpbuf, buffer, sizeof(buffer), &grf) != -1) count++; endgrent_r(&grf); .ft .ps .fi .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library. This causes them to increase the size of programs that do not otherwise use standard I/O and Network Information Service more than might ordinarily be expected. .PP The value returned by .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() points to a single static area that is overwritten by each call to any of the functions. It must be copied if it is to be saved. .PP .CR getgrent() , .CR getgrgid() , .CR getgrnam() , .CR setgrent() , .CR endgrent() , and .CR fgetgrent() are unsafe in multi-thread applications. .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , .CR setgrent_r() , .CR endgrent_r() , and .CR fgetgrent_r() are MT-Safe and should be used instead. .PP Users of .CR getgrent_r() and .CR getgrnam_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH DEPENDENCIES .SS NFS: .br .B FILES .RS .CI /var/yp/ domainname /group.byname .br .CI /var/yp/ domainname /group.bygid .RE .SM .B SEE ALSO: .RS ypcat(1). .RE .SH FILES .C /etc/group .SH SEE ALSO getgroups(2), getpwent(3C), stdio(3S), group(4). .SH STANDARDS CONFORMANCE .CR getgrent() ": SVID2, SVID3, XPG2" .PP .CR endgrent() ": SVID2, SVID3, XPG2" .PP .CR fgetgrent() ": SVID2, SVID3, XPG2" .PP .CR getgrgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgrnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setgrent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getgrent()\f1 \- get next entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4fgetgrent()\f1 \- get next entry in \f4group()\f1-file-formatted input stream@@@\f3getgrent(3C)\f1 .\" index@\f4getgrgid()\f1 \- get entry from \f4group()\f1 file that matches \f4gid()\fP@@@\f3getgrent(3C)\f1 .\" index@\f4getgrnam()\f1 \- get entry from \f4group()\fP file that matches group name \f4name()\f1@@@\f3getgrent(3C)\f1 .\" index@\f4setgrent()\f1 \- rewind pointer to first entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4endgrent()\f1 \- close currently open \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@get: entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@entry from \f4group()\f1 file, get@@@\f3getgrent(3C)\f1 .\" index@\f4group()\f1 file, get entry from@@@\f3getgrent(3C)\f1 .\" index@file, group: get entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" .\" toc@\f3getgrent(3C)\f1:\0\0\f4getgrent()\f1, \f4getgrgid()\f1, \f4getgrnam()\f1, \f4setgrent()\f1, \f4endgrent()\f1,\n \f4fgetgrent()\f1@@@get group file entry .\" toc@\f4getgrgid()\fP, \f4getgrnam()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4setgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4endgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4fgetgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" .\" links@getgrent.3c getgrent_r.3c .\" links@getgrent.3c getgrgid.3c .\" links@getgrent.3c getgrgid_r.3c .\" links@getgrent.3c getgrnam.3c .\" links@getgrent.3c getgrnam_r.3c .\" links@getgrent.3c setgrent.3c .\" links@getgrent.3c setgrent_r.3c .\" links@getgrent.3c endgrent.3c .\" links@getgrent.3c endgrent_r.3c .\" links@getgrent.3c fgetgrent.3c .\" links@getgrent.3c fgetgrent_r.3c .\" .\" fileset_database@getgrent.3c PROGRAMING-MAN .\" $Header: getgrent.3c,v 76.1 95/07/05 17:29:02 ssa Exp $ .TA g .TH getgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getgrent(\|), getgrent_r(\|), getgrgid(\|), getgrgid_r(\|), getgrnam(\|), getgrnam_r(\|), setgrent(\|), setgrent_r(\|), endgrent(\|), endgrent_r(\|), fgetgrent(\|), fgetgrent_r(\|) \- get group file entry .SH SYNOPSIS .C "#include " .PP .C "struct group *getgrent(void);" .PD 0 .PP .C "int getgrent_r(" .nf .PD 0 .IP .C "struct group *result," .C "char *buffer," .C "int buflen," .C "FILE **grfp);" .PD 0 .PP .C "struct group *getgrgid(gid_t gid);" .PP .C "int getgrgid_r(" .nf .PD 0 .IP .C "gid_t gid," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "struct group *getgrnam(const char *name);" .PP .C "int getgrnam_r(" .nf .PD 0 .IP .C "const char *name," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "void setgrent(void);" .PP .C "void setgrent_r(FILE **grfp);" .PP .C "void endgrent(void);" .PP .C "void endgrent_r(FILE **grfp);" .PP .C "struct group *fgetgrent(FILE *stream);" .PP .C "int fgetgrent_r(" .nf .PD 0 .IP .C "FILE *stream," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD .SH DESCRIPTION .CR getgrent() , .CR getgrgid() , and .CR getgrnam() locate an entry in the .CR /etc/group file, and return a pointer to an object of type .CR "struct group" . .PP The .CR group structure is defined in .RC < grp.h > and includes the following members: .nf .IP .C "char *gr_name; /* the name of the group */" .C "char *gr_passwd; /* the encrypted group password */" .C "gid_t gr_gid; /* the numerical group \s-1ID\s+1 */" .C "char **gr_mem; /* null-terminated array of pointers" .C " to member names */" .fi .TP 20 .C getgrent() When first called, .CR getgrent() returns a pointer to the first .CR group structure in the file; thereafter, it returns a pointer to the next .CR group structure in the file. In this way, successive calls can be used to search the entire file. .CR getgrent() opens the .CR /etc/group file prior to doing its work and leaves the file open afterward; .TP .C setgrent() Has the effect of rewinding this file to allow repeated searches; .TP .C endgrent() Can be called to close the file when processing is complete. .TP .C getgrgid() Searches from the beginning of the file until a numeric group ID matching .I gid is found, and returns a pointer to the particular structure in which it was found. .TP .C getgrnam() Searches from the beginning of the file until a group name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .C fgetgrent() Returns a pointer to the next .CR group structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/group . .SS Reentrant Interfaces .CR getgrgid_r() , .CR getgrnam_r() and .CR fgetgrent_r() expect to be passed three extra parameters: .PD 0 .TP 3 1. The address of a .C "struct group" where the result will be stored; .TP 2. A buffer to store character strings, such as the group name, to which fields in the .C "struct group" will point; .TP 3. The length of the user-supplied buffer. .PD .PP In addition to the above three parameters, .CR getgrent_r() requires a pointer to a .I "(FILE *)" variable into which is stored the result of an .I fopen() call on the .CR /etc/group file. This parameter allows threads to independently scan through the .CR /etc/group file. .CR setgrent_r() and .CR endgrent_r() are to be used only in conjunction with .CR getgrent_r() and take the same pointer to a .I "(FILE *)" variable as a parameter. .CR setgrent_r() can be used to rewind or open the .CR /etc/group file. .CR endgrent_r() must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .I "(FILE *)" variable must be initialized to NULL before it is passed to either .CR getgrent_r() or .CR setgrent_r() for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH NETWORKING FEATURES .SS NFS If an entry beginning with a plus sign .RC ( + ) or a minus sign .RC (\| \(mi \|) is found, these routines try to use the Network Information Service network database for data. See .IR group (4) for proper syntax and operation. .SH RETURN VALUE .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .CR group structure. .PP .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , and .CR fgetgrent_r() return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getgrent() , .CR getgrgid() , .CR getgrnam() and .CR fgetgrent() fail if any of the following are true: .RS .TP 12 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX file descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .PD .RE .SH EXAMPLE The following code excerpt counts the number of entries in the .CR /etc/group file: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct group gpbuf; char buffer[1024]; FILE *grf = NULL; setgrent_r(&grf); while (getgrent_r(&gpbuf, buffer, sizeof(buffer), &grf) != -1) count++; endgrent_r(&grf); .ft .ps .fi .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library. This causes them to increase the size of programs that do not otherwise use standard I/O and Network Information Service more than might ordinarily be expected. .PP The value returned by .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() points to a single static area that is overwritten by each call to any of the functions. It must be copied if it is to be saved. .PP .CR getgrent() , .CR getgrgid() , .CR getgrnam() , .CR setgrent() , .CR endgrent() , and .CR fgetgrent() are unsafe in multi-thread applications. .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , .CR setgrent_r() , .CR endgrent_r() , and .CR fgetgrent_r() are MT-Safe and should be used instead. .PP Users of .CR getgrent_r() and .CR getgrnam_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH DEPENDENCIES .SS NFS: .br .B FILES .RS .CI /var/yp/ domainname /group.byname .br .CI /var/yp/ domainname /group.bygid .RE .SM .B SEE ALSO: .RS ypcat(1). .RE .SH FILES .C /etc/group .SH SEE ALSO getgroups(2), getpwent(3C), stdio(3S), group(4). .SH STANDARDS CONFORMANCE .CR getgrent() ": SVID2, SVID3, XPG2" .PP .CR endgrent() ": SVID2, SVID3, XPG2" .PP .CR fgetgrent() ": SVID2, SVID3, XPG2" .PP .CR getgrgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgrnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setgrent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getgrent()\f1 \- get next entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4fgetgrent()\f1 \- get next entry in \f4group()\f1-file-formatted input stream@@@\f3getgrent(3C)\f1 .\" index@\f4getgrgid()\f1 \- get entry from \f4group()\f1 file that matches \f4gid()\fP@@@\f3getgrent(3C)\f1 .\" index@\f4getgrnam()\f1 \- get entry from \f4group()\fP file that matches group name \f4name()\f1@@@\f3getgrent(3C)\f1 .\" index@\f4setgrent()\f1 \- rewind pointer to first entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4endgrent()\f1 \- close currently open \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@get: entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@entry from \f4group()\f1 file, get@@@\f3getgrent(3C)\f1 .\" index@\f4group()\f1 file, get entry from@@@\f3getgrent(3C)\f1 .\" index@file, group: get entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" .\" toc@\f3getgrent(3C)\f1:\0\0\f4getgrent()\f1, \f4getgrgid()\f1, \f4getgrnam()\f1, \f4setgrent()\f1, \f4endgrent()\f1,\n \f4fgetgrent()\f1@@@get group file entry .\" toc@\f4getgrgid()\fP, \f4getgrnam()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4setgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4endgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4fgetgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" .\" links@getgrent.3c getgrent_r.3c .\" links@getgrent.3c getgrgid.3c .\" links@getgrent.3c getgrgid_r.3c .\" links@getgrent.3c getgrnam.3c .\" links@getgrent.3c getgrnam_r.3c .\" links@getgrent.3c setgrent.3c .\" links@getgrent.3c setgrent_r.3c .\" links@getgrent.3c endgrent.3c .\" links@getgrent.3c endgrent_r.3c .\" links@getgrent.3c fgetgrent.3c .\" links@getgrent.3c fgetgrent_r.3c .\" .\" fileset_database@getgrent.3c PROGRAMING-MAN .\" $Header: getgrent.3c,v 76.1 95/07/05 17:29:02 ssa Exp $ .TA g .TH getgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getgrent(\|), getgrent_r(\|), getgrgid(\|), getgrgid_r(\|), getgrnam(\|), getgrnam_r(\|), setgrent(\|), setgrent_r(\|), endgrent(\|), endgrent_r(\|), fgetgrent(\|), fgetgrent_r(\|) \- get group file entry .SH SYNOPSIS .C "#include " .PP .C "struct group *getgrent(void);" .PD 0 .PP .C "int getgrent_r(" .nf .PD 0 .IP .C "struct group *result," .C "char *buffer," .C "int buflen," .C "FILE **grfp);" .PD 0 .PP .C "struct group *getgrgid(gid_t gid);" .PP .C "int getgrgid_r(" .nf .PD 0 .IP .C "gid_t gid," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "struct group *getgrnam(const char *name);" .PP .C "int getgrnam_r(" .nf .PD 0 .IP .C "const char *name," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "void setgrent(void);" .PP .C "void setgrent_r(FILE **grfp);" .PP .C "void endgrent(void);" .PP .C "void endgrent_r(FILE **grfp);" .PP .C "struct group *fgetgrent(FILE *stream);" .PP .C "int fgetgrent_r(" .nf .PD 0 .IP .C "FILE *stream," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD .SH DESCRIPTION .CR getgrent() , .CR getgrgid() , and .CR getgrnam() locate an entry in the .CR /etc/group file, and return a pointer to an object of type .CR "struct group" . .PP The .CR group structure is defined in .RC < grp.h > and includes the following members: .nf .IP .C "char *gr_name; /* the name of the group */" .C "char *gr_passwd; /* the encrypted group password */" .C "gid_t gr_gid; /* the numerical group \s-1ID\s+1 */" .C "char **gr_mem; /* null-terminated array of pointers" .C " to member names */" .fi .TP 20 .C getgrent() When first called, .CR getgrent() returns a pointer to the first .CR group structure in the file; thereafter, it returns a pointer to the next .CR group structure in the file. In this way, successive calls can be used to search the entire file. .CR getgrent() opens the .CR /etc/group file prior to doing its work and leaves the file open afterward; .TP .C setgrent() Has the effect of rewinding this file to allow repeated searches; .TP .C endgrent() Can be called to close the file when processing is complete. .TP .C getgrgid() Searches from the beginning of the file until a numeric group ID matching .I gid is found, and returns a pointer to the particular structure in which it was found. .TP .C getgrnam() Searches from the beginning of the file until a group name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .C fgetgrent() Returns a pointer to the next .CR group structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/group . .SS Reentrant Interfaces .CR getgrgid_r() , .CR getgrnam_r() and .CR fgetgrent_r() expect to be passed three extra parameters: .PD 0 .TP 3 1. The address of a .C "struct group" where the result will be stored; .TP 2. A buffer to store character strings, such as the group name, to which fields in the .C "struct group" will point; .TP 3. The length of the user-supplied buffer. .PD .PP In addition to the above three parameters, .CR getgrent_r() requires a pointer to a .I "(FILE *)" variable into which is stored the result of an .I fopen() call on the .CR /etc/group file. This parameter allows threads to independently scan through the .CR /etc/group file. .CR setgrent_r() and .CR endgrent_r() are to be used only in conjunction with .CR getgrent_r() and take the same pointer to a .I "(FILE *)" variable as a parameter. .CR setgrent_r() can be used to rewind or open the .CR /etc/group file. .CR endgrent_r() must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .I "(FILE *)" variable must be initialized to NULL before it is passed to either .CR getgrent_r() or .CR setgrent_r() for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH NETWORKING FEATURES .SS NFS If an entry beginning with a plus sign .RC ( + ) or a minus sign .RC (\| \(mi \|) is found, these routines try to use the Network Information Service network database for data. See .IR group (4) for proper syntax and operation. .SH RETURN VALUE .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .CR group structure. .PP .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , and .CR fgetgrent_r() return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getgrent() , .CR getgrgid() , .CR getgrnam() and .CR fgetgrent() fail if any of the following are true: .RS .TP 12 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX file descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .PD .RE .SH EXAMPLE The following code excerpt counts the number of entries in the .CR /etc/group file: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct group gpbuf; char buffer[1024]; FILE *grf = NULL; setgrent_r(&grf); while (getgrent_r(&gpbuf, buffer, sizeof(buffer), &grf) != -1) count++; endgrent_r(&grf); .ft .ps .fi .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library. This causes them to increase the size of programs that do not otherwise use standard I/O and Network Information Service more than might ordinarily be expected. .PP The value returned by .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() points to a single static area that is overwritten by each call to any of the functions. It must be copied if it is to be saved. .PP .CR getgrent() , .CR getgrgid() , .CR getgrnam() , .CR setgrent() , .CR endgrent() , and .CR fgetgrent() are unsafe in multi-thread applications. .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , .CR setgrent_r() , .CR endgrent_r() , and .CR fgetgrent_r() are MT-Safe and should be used instead. .PP Users of .CR getgrent_r() and .CR getgrnam_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH DEPENDENCIES .SS NFS: .br .B FILES .RS .CI /var/yp/ domainname /group.byname .br .CI /var/yp/ domainname /group.bygid .RE .SM .B SEE ALSO: .RS ypcat(1). .RE .SH FILES .C /etc/group .SH SEE ALSO getgroups(2), getpwent(3C), stdio(3S), group(4). .SH STANDARDS CONFORMANCE .CR getgrent() ": SVID2, SVID3, XPG2" .PP .CR endgrent() ": SVID2, SVID3, XPG2" .PP .CR fgetgrent() ": SVID2, SVID3, XPG2" .PP .CR getgrgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgrnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setgrent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getgrent()\f1 \- get next entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4fgetgrent()\f1 \- get next entry in \f4group()\f1-file-formatted input stream@@@\f3getgrent(3C)\f1 .\" index@\f4getgrgid()\f1 \- get entry from \f4group()\f1 file that matches \f4gid()\fP@@@\f3getgrent(3C)\f1 .\" index@\f4getgrnam()\f1 \- get entry from \f4group()\fP file that matches group name \f4name()\f1@@@\f3getgrent(3C)\f1 .\" index@\f4setgrent()\f1 \- rewind pointer to first entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4endgrent()\f1 \- close currently open \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@get: entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@entry from \f4group()\f1 file, get@@@\f3getgrent(3C)\f1 .\" index@\f4group()\f1 file, get entry from@@@\f3getgrent(3C)\f1 .\" index@file, group: get entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" .\" toc@\f3getgrent(3C)\f1:\0\0\f4getgrent()\f1, \f4getgrgid()\f1, \f4getgrnam()\f1, \f4setgrent()\f1, \f4endgrent()\f1,\n \f4fgetgrent()\f1@@@get group file entry .\" toc@\f4getgrgid()\fP, \f4getgrnam()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4setgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4endgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4fgetgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" .\" links@getgrent.3c getgrent_r.3c .\" links@getgrent.3c getgrgid.3c .\" links@getgrent.3c getgrgid_r.3c .\" links@getgrent.3c getgrnam.3c .\" links@getgrent.3c getgrnam_r.3c .\" links@getgrent.3c setgrent.3c .\" links@getgrent.3c setgrent_r.3c .\" links@getgrent.3c endgrent.3c .\" links@getgrent.3c endgrent_r.3c .\" links@getgrent.3c fgetgrent.3c .\" links@getgrent.3c fgetgrent_r.3c .\" .\" fileset_database@getgrent.3c PROGRAMING-MAN .\" $Header: getgrent.3c,v 76.1 95/07/05 17:29:02 ssa Exp $ .TA g .TH getgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getgrent(\|), getgrent_r(\|), getgrgid(\|), getgrgid_r(\|), getgrnam(\|), getgrnam_r(\|), setgrent(\|), setgrent_r(\|), endgrent(\|), endgrent_r(\|), fgetgrent(\|), fgetgrent_r(\|) \- get group file entry .SH SYNOPSIS .C "#include " .PP .C "struct group *getgrent(void);" .PD 0 .PP .C "int getgrent_r(" .nf .PD 0 .IP .C "struct group *result," .C "char *buffer," .C "int buflen," .C "FILE **grfp);" .PD 0 .PP .C "struct group *getgrgid(gid_t gid);" .PP .C "int getgrgid_r(" .nf .PD 0 .IP .C "gid_t gid," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "struct group *getgrnam(const char *name);" .PP .C "int getgrnam_r(" .nf .PD 0 .IP .C "const char *name," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "void setgrent(void);" .PP .C "void setgrent_r(FILE **grfp);" .PP .C "void endgrent(void);" .PP .C "void endgrent_r(FILE **grfp);" .PP .C "struct group *fgetgrent(FILE *stream);" .PP .C "int fgetgrent_r(" .nf .PD 0 .IP .C "FILE *stream," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD .SH DESCRIPTION .CR getgrent() , .CR getgrgid() , and .CR getgrnam() locate an entry in the .CR /etc/group file, and return a pointer to an object of type .CR "struct group" . .PP The .CR group structure is defined in .RC < grp.h > and includes the following members: .nf .IP .C "char *gr_name; /* the name of the group */" .C "char *gr_passwd; /* the encrypted group password */" .C "gid_t gr_gid; /* the numerical group \s-1ID\s+1 */" .C "char **gr_mem; /* null-terminated array of pointers" .C " to member names */" .fi .TP 20 .C getgrent() When first called, .CR getgrent() returns a pointer to the first .CR group structure in the file; thereafter, it returns a pointer to the next .CR group structure in the file. In this way, successive calls can be used to search the entire file. .CR getgrent() opens the .CR /etc/group file prior to doing its work and leaves the file open afterward; .TP .C setgrent() Has the effect of rewinding this file to allow repeated searches; .TP .C endgrent() Can be called to close the file when processing is complete. .TP .C getgrgid() Searches from the beginning of the file until a numeric group ID matching .I gid is found, and returns a pointer to the particular structure in which it was found. .TP .C getgrnam() Searches from the beginning of the file until a group name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .C fgetgrent() Returns a pointer to the next .CR group structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/group . .SS Reentrant Interfaces .CR getgrgid_r() , .CR getgrnam_r() and .CR fgetgrent_r() expect to be passed three extra parameters: .PD 0 .TP 3 1. The address of a .C "struct group" where the result will be stored; .TP 2. A buffer to store character strings, such as the group name, to which fields in the .C "struct group" will point; .TP 3. The length of the user-supplied buffer. .PD .PP In addition to the above three parameters, .CR getgrent_r() requires a pointer to a .I "(FILE *)" variable into which is stored the result of an .I fopen() call on the .CR /etc/group file. This parameter allows threads to independently scan through the .CR /etc/group file. .CR setgrent_r() and .CR endgrent_r() are to be used only in conjunction with .CR getgrent_r() and take the same pointer to a .I "(FILE *)" variable as a parameter. .CR setgrent_r() can be used to rewind or open the .CR /etc/group file. .CR endgrent_r() must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .I "(FILE *)" variable must be initialized to NULL before it is passed to either .CR getgrent_r() or .CR setgrent_r() for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH NETWORKING FEATURES .SS NFS If an entry beginning with a plus sign .RC ( + ) or a minus sign .RC (\| \(mi \|) is found, these routines try to use the Network Information Service network database for data. See .IR group (4) for proper syntax and operation. .SH RETURN VALUE .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .CR group structure. .PP .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , and .CR fgetgrent_r() return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getgrent() , .CR getgrgid() , .CR getgrnam() and .CR fgetgrent() fail if any of the following are true: .RS .TP 12 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX file descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .PD .RE .SH EXAMPLE The following code excerpt counts the number of entries in the .CR /etc/group file: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct group gpbuf; char buffer[1024]; FILE *grf = NULL; setgrent_r(&grf); while (getgrent_r(&gpbuf, buffer, sizeof(buffer), &grf) != -1) count++; endgrent_r(&grf); .ft .ps .fi .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library. This causes them to increase the size of programs that do not otherwise use standard I/O and Network Information Service more than might ordinarily be expected. .PP The value returned by .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() points to a single static area that is overwritten by each call to any of the functions. It must be copied if it is to be saved. .PP .CR getgrent() , .CR getgrgid() , .CR getgrnam() , .CR setgrent() , .CR endgrent() , and .CR fgetgrent() are unsafe in multi-thread applications. .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , .CR setgrent_r() , .CR endgrent_r() , and .CR fgetgrent_r() are MT-Safe and should be used instead. .PP Users of .CR getgrent_r() and .CR getgrnam_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH DEPENDENCIES .SS NFS: .br .B FILES .RS .CI /var/yp/ domainname /group.byname .br .CI /var/yp/ domainname /group.bygid .RE .SM .B SEE ALSO: .RS ypcat(1). .RE .SH FILES .C /etc/group .SH SEE ALSO getgroups(2), getpwent(3C), stdio(3S), group(4). .SH STANDARDS CONFORMANCE .CR getgrent() ": SVID2, SVID3, XPG2" .PP .CR endgrent() ": SVID2, SVID3, XPG2" .PP .CR fgetgrent() ": SVID2, SVID3, XPG2" .PP .CR getgrgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgrnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setgrent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getgrent()\f1 \- get next entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4fgetgrent()\f1 \- get next entry in \f4group()\f1-file-formatted input stream@@@\f3getgrent(3C)\f1 .\" index@\f4getgrgid()\f1 \- get entry from \f4group()\f1 file that matches \f4gid()\fP@@@\f3getgrent(3C)\f1 .\" index@\f4getgrnam()\f1 \- get entry from \f4group()\fP file that matches group name \f4name()\f1@@@\f3getgrent(3C)\f1 .\" index@\f4setgrent()\f1 \- rewind pointer to first entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4endgrent()\f1 \- close currently open \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@get: entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@entry from \f4group()\f1 file, get@@@\f3getgrent(3C)\f1 .\" index@\f4group()\f1 file, get entry from@@@\f3getgrent(3C)\f1 .\" index@file, group: get entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" .\" toc@\f3getgrent(3C)\f1:\0\0\f4getgrent()\f1, \f4getgrgid()\f1, \f4getgrnam()\f1, \f4setgrent()\f1, \f4endgrent()\f1,\n \f4fgetgrent()\f1@@@get group file entry .\" toc@\f4getgrgid()\fP, \f4getgrnam()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4setgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4endgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4fgetgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" .\" links@getgrent.3c getgrent_r.3c .\" links@getgrent.3c getgrgid.3c .\" links@getgrent.3c getgrgid_r.3c .\" links@getgrent.3c getgrnam.3c .\" links@getgrent.3c getgrnam_r.3c .\" links@getgrent.3c setgrent.3c .\" links@getgrent.3c setgrent_r.3c .\" links@getgrent.3c endgrent.3c .\" links@getgrent.3c endgrent_r.3c .\" links@getgrent.3c fgetgrent.3c .\" links@getgrent.3c fgetgrent_r.3c .\" .\" fileset_database@getgrent.3c PROGRAMING-MAN .\" $Header: getgrent.3c,v 76.1 95/07/05 17:29:02 ssa Exp $ .TA g .TH getgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getgrent(\|), getgrent_r(\|), getgrgid(\|), getgrgid_r(\|), getgrnam(\|), getgrnam_r(\|), setgrent(\|), setgrent_r(\|), endgrent(\|), endgrent_r(\|), fgetgrent(\|), fgetgrent_r(\|) \- get group file entry .SH SYNOPSIS .C "#include " .PP .C "struct group *getgrent(void);" .PD 0 .PP .C "int getgrent_r(" .nf .PD 0 .IP .C "struct group *result," .C "char *buffer," .C "int buflen," .C "FILE **grfp);" .PD 0 .PP .C "struct group *getgrgid(gid_t gid);" .PP .C "int getgrgid_r(" .nf .PD 0 .IP .C "gid_t gid," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "struct group *getgrnam(const char *name);" .PP .C "int getgrnam_r(" .nf .PD 0 .IP .C "const char *name," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "void setgrent(void);" .PP .C "void setgrent_r(FILE **grfp);" .PP .C "void endgrent(void);" .PP .C "void endgrent_r(FILE **grfp);" .PP .C "struct group *fgetgrent(FILE *stream);" .PP .C "int fgetgrent_r(" .nf .PD 0 .IP .C "FILE *stream," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD .SH DESCRIPTION .CR getgrent() , .CR getgrgid() , and .CR getgrnam() locate an entry in the .CR /etc/group file, and return a pointer to an object of type .CR "struct group" . .PP The .CR group structure is defined in .RC < grp.h > and includes the following members: .nf .IP .C "char *gr_name; /* the name of the group */" .C "char *gr_passwd; /* the encrypted group password */" .C "gid_t gr_gid; /* the numerical group \s-1ID\s+1 */" .C "char **gr_mem; /* null-terminated array of pointers" .C " to member names */" .fi .TP 20 .C getgrent() When first called, .CR getgrent() returns a pointer to the first .CR group structure in the file; thereafter, it returns a pointer to the next .CR group structure in the file. In this way, successive calls can be used to search the entire file. .CR getgrent() opens the .CR /etc/group file prior to doing its work and leaves the file open afterward; .TP .C setgrent() Has the effect of rewinding this file to allow repeated searches; .TP .C endgrent() Can be called to close the file when processing is complete. .TP .C getgrgid() Searches from the beginning of the file until a numeric group ID matching .I gid is found, and returns a pointer to the particular structure in which it was found. .TP .C getgrnam() Searches from the beginning of the file until a group name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .C fgetgrent() Returns a pointer to the next .CR group structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/group . .SS Reentrant Interfaces .CR getgrgid_r() , .CR getgrnam_r() and .CR fgetgrent_r() expect to be passed three extra parameters: .PD 0 .TP 3 1. The address of a .C "struct group" where the result will be stored; .TP 2. A buffer to store character strings, such as the group name, to which fields in the .C "struct group" will point; .TP 3. The length of the user-supplied buffer. .PD .PP In addition to the above three parameters, .CR getgrent_r() requires a pointer to a .I "(FILE *)" variable into which is stored the result of an .I fopen() call on the .CR /etc/group file. This parameter allows threads to independently scan through the .CR /etc/group file. .CR setgrent_r() and .CR endgrent_r() are to be used only in conjunction with .CR getgrent_r() and take the same pointer to a .I "(FILE *)" variable as a parameter. .CR setgrent_r() can be used to rewind or open the .CR /etc/group file. .CR endgrent_r() must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .I "(FILE *)" variable must be initialized to NULL before it is passed to either .CR getgrent_r() or .CR setgrent_r() for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH NETWORKING FEATURES .SS NFS If an entry beginning with a plus sign .RC ( + ) or a minus sign .RC (\| \(mi \|) is found, these routines try to use the Network Information Service network database for data. See .IR group (4) for proper syntax and operation. .SH RETURN VALUE .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .CR group structure. .PP .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , and .CR fgetgrent_r() return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getgrent() , .CR getgrgid() , .CR getgrnam() and .CR fgetgrent() fail if any of the following are true: .RS .TP 12 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX file descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .PD .RE .SH EXAMPLE The following code excerpt counts the number of entries in the .CR /etc/group file: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct group gpbuf; char buffer[1024]; FILE *grf = NULL; setgrent_r(&grf); while (getgrent_r(&gpbuf, buffer, sizeof(buffer), &grf) != -1) count++; endgrent_r(&grf); .ft .ps .fi .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library. This causes them to increase the size of programs that do not otherwise use standard I/O and Network Information Service more than might ordinarily be expected. .PP The value returned by .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() points to a single static area that is overwritten by each call to any of the functions. It must be copied if it is to be saved. .PP .CR getgrent() , .CR getgrgid() , .CR getgrnam() , .CR setgrent() , .CR endgrent() , and .CR fgetgrent() are unsafe in multi-thread applications. .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , .CR setgrent_r() , .CR endgrent_r() , and .CR fgetgrent_r() are MT-Safe and should be used instead. .PP Users of .CR getgrent_r() and .CR getgrnam_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH DEPENDENCIES .SS NFS: .br .B FILES .RS .CI /var/yp/ domainname /group.byname .br .CI /var/yp/ domainname /group.bygid .RE .SM .B SEE ALSO: .RS ypcat(1). .RE .SH FILES .C /etc/group .SH SEE ALSO getgroups(2), getpwent(3C), stdio(3S), group(4). .SH STANDARDS CONFORMANCE .CR getgrent() ": SVID2, SVID3, XPG2" .PP .CR endgrent() ": SVID2, SVID3, XPG2" .PP .CR fgetgrent() ": SVID2, SVID3, XPG2" .PP .CR getgrgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgrnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setgrent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getgrent()\f1 \- get next entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4fgetgrent()\f1 \- get next entry in \f4group()\f1-file-formatted input stream@@@\f3getgrent(3C)\f1 .\" index@\f4getgrgid()\f1 \- get entry from \f4group()\f1 file that matches \f4gid()\fP@@@\f3getgrent(3C)\f1 .\" index@\f4getgrnam()\f1 \- get entry from \f4group()\fP file that matches group name \f4name()\f1@@@\f3getgrent(3C)\f1 .\" index@\f4setgrent()\f1 \- rewind pointer to first entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4endgrent()\f1 \- close currently open \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@get: entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@entry from \f4group()\f1 file, get@@@\f3getgrent(3C)\f1 .\" index@\f4group()\f1 file, get entry from@@@\f3getgrent(3C)\f1 .\" index@file, group: get entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" .\" toc@\f3getgrent(3C)\f1:\0\0\f4getgrent()\f1, \f4getgrgid()\f1, \f4getgrnam()\f1, \f4setgrent()\f1, \f4endgrent()\f1,\n \f4fgetgrent()\f1@@@get group file entry .\" toc@\f4getgrgid()\fP, \f4getgrnam()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4setgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4endgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4fgetgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" .\" links@getgrent.3c getgrent_r.3c .\" links@getgrent.3c getgrgid.3c .\" links@getgrent.3c getgrgid_r.3c .\" links@getgrent.3c getgrnam.3c .\" links@getgrent.3c getgrnam_r.3c .\" links@getgrent.3c setgrent.3c .\" links@getgrent.3c setgrent_r.3c .\" links@getgrent.3c endgrent.3c .\" links@getgrent.3c endgrent_r.3c .\" links@getgrent.3c fgetgrent.3c .\" links@getgrent.3c fgetgrent_r.3c .\" .\" fileset_database@getgrent.3c PROGRAMING-MAN .\" $Header: gethostent.3n,v 78.1 96/03/15 15:56:59 ssa Exp $ .TA g .TH gethostent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gethostent(), gethostent_r(), gethostbyaddr(), gethostbyaddr_r(), gethostbyname(), gethostbyname_r(), sethostent(), sethostent_r(), endhostent(), endhostent_r() \- get network host entry .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .PP .C "extern int h_errno;" .PP .C "struct hostent *gethostent(void);" .PP .C "int gethostent_r(struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyname(const char *name);" .PP .C "int gethostbyname_r(const char *name," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyaddr(const char *addr, .C " int len, .C " int type); .PP .C "_XOPEN_SOURCE_EXTENDED only .C "struct hostent *gethostbyaddr(const void *addr, .C " size_t len, .C " int type); .PP .C "int gethostbyaddr_r(const char *addr," .C " int len," .C " int type," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "int sethostent(int stayopen);" .PP .C "int sethostent_r(int stayopen, struct hostent_data *buffer);" .PP .C "int endhostent(void);" .PP .C "int endhostent_r(struct hostent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only .C "void sethostent(int stayopen);" .C "void endhostent(void);" .fi .SH DESCRIPTION The .CR gethostent() , .CR gethostbyname() , and .CR gethostbyaddr() functions each return a pointer to a structure of type .CR hostent , defined as follows in .CR : .nf .IP .C "struct hostent {" .C " char *h_name;" .C " char **h_aliases;" .C " int h_addrtype;" .C " int h_length;" .C " char **h_addr_list;" .C "};" .IP .C "#define h_addr h_addr_list[0]" .fi .PP The members of this structure are: .RS .TP 20 .CR h_name The official name of the host. .TP .CR h_aliases A null-terminated array of alternate names for the host. .TP .CR h_addrtype The type of address being returned; always .CR AF_INET . .TP .CR h_length The length, in bytes, of the address. .TP .CR h_addr_list A null-terminated array of network addresses for the host. .TP .CR h_addr The first address in .CR h_addr_list ; this is for compatibility with previous HP-UX implementations where a .CR "struct hostent" contains only one network address per host. .RE .SS Reentrant Interfaces .CR gethostent_r() , .CR gethostbyname_r() , and .CR gethostbyaddr_r() expect to be passed the address of a .CR "struct hostent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct hostent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct hostent" will point, as well as state information such as open file descriptors. The .CR "struct hostent_data" is defined in the header file .CR . .PP .CR sethostent_r() and .CR endhostent_r() are to be used only in conjunction with .CR gethostent_r() and take the same pointer to a .CR "struct hostent_data" as a parameter. If the Network Information Service is being used, .CR sethostent_r() initializes an internal database key. If the .CR /etc/hosts file is being used, .CR sethostent_r() opens or rewinds the file. If the .CR named name server (see .IR named (1M)) is being used, then .CR sethostent_r() has no effect. .CR endhostent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR sethostent_r() currently has no effect. However, .CR sethostent() can still be used to keep the .CR /etc/hosts file open, or to use connected stream sockets to the name server, when making calls to .CR gethostbyaddr_r() and .CR gethostbyname_r() . .PP The .I hostf field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to either .CR gethostent_r() or .CR sethostent_r() for the first time. The .I current field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to .CR gethostbyname_r() or .CR gethostbyaddr_r() for the first time. Thereafter, these fields should not be modified in any way. These are the only .CR hostent_data fields that should ever be explicitly accessed. .SS Name Service Switch-Based Operation These host entry library routines internally call the name service switch to access the "hosts" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve host names and Internet addresses. The operations of the three name services: Domain Name Server, NIS, and nonserver mode (e.g., files) are listed below. .SS Domain Name Server Operation If the local system is configured to use the .CR named name server (see .IR named(1M) and .IR resolver(4)) for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Always returns a NULL pointer. .TP .CR sethostent() , Requests the use of a connected stream socket for queries to the name server if the .I stayopen flag is non-zero. The connection is retained after each call to .CR gethostbyname() or .CR gethostbyaddr() . .TP .CR endhostent() Closes the stream socket connection. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the name server. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS NIS Server Operation If .CR ypserv, the server for the Network Information Service (see .IR ypserv (1M)), is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Returns the next entry in the NIS database. .TP .CR sethostent() Initializes an internal key for the NIS database. If the .I stayopen flag is non-zero, the internal key is not cleared after calls to .CR endhostent() . .TP .CR endhostent() Clears the internal NIS database key. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the NIS database. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS Nonserver Operation If the .CR /etc/hosts file is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Reads the next line of .CR /etc/hosts , opening the file if necessary. .TP .CR sethostent() opens and rewinds the file. If the .I stayopen flag is non-zero, the host data base is not closed after each call to .CR gethostent() (either directly or indirectly through one of the other .CR gethost calls). .TP .CR endhostent() Closes the file. .TP .CR gethostbyname() Sequentially searches from the beginning of the file until a host name (among either the official names or the aliases) matching its .I name parameter is found, or until EOF is encountered. Names are matched without respect to uppercase or lowercase, as described above in the name server case. .TP .CR gethostbyaddr() Sequentially searches from the beginning of the file until an Internet address matching its .I addr parameter is found, or until EOF is encountered. .RE .SS Arguments Currently, only the Internet address format is understood. In calls to .CR gethostbyaddr() , the parameter .I addr must be a pointer to an .IR in_addr structure, an Internet address in network order (see .IR byteorder (3N)) and the header file .CR ). The parameter .I len must be the number of bytes in an Internet address; that is, .CR "sizeof (struct in_addr)" . The parameter .I type must be the constant .CR AF_INET . .SH RETURN VALUE If successful, .CR gethostbyname() , .CR gethostbyaddr() , and .CR gethostent() return a pointer to the requested .CR hostent structure. .PP .CR gethostbyname() and .CR gethostbyaddr() return NULL if their .I host or .I addr parameters, respectively, cannot be found in the database. If .CR /etc/hosts is being used, they also return NULL if they are unable to open .CR /etc/hosts . .PP .CR gethostbyaddr() also returns NULL if either its .I addr or .I len parameter is invalid. .PP .CR gethostent() always returns NULL if the name server is being used. .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 is returned if the operation is unsuccessful or, in the case of .CR gethostent_r() , if the end of the hosts list has been reached. .CR 0 is returned otherwise. .SH ERRORS If the name server is being used and .CR gethostbyname() or .CR gethostbyaddr() returns a NULL pointer, the external integer .CR h_errno contains one of the following values: .RS .TP 23 .CR HOST_NOT_FOUND No such host is known. .TP .CR TRY_AGAIN This is usually a temporary error. The local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .CR NO_RECOVERY This is a non-recoverable error. .TP .CR NO_ADDRESS The requested name is valid but does not have an IP address; this is not a temporary error. This means another type of request to the name server will result in an answer. .RE .PP If the name server is not being used, the value of .CR h_errno may not be meaningful. .SH EXAMPLES The following code excerpt counts the number of host entries: .RS .nf .PP .C "int count = 0; .C "struct hostent htbuf; .C "struct hostent_data hdbuf; .PP .C "hdbuf.hostf = NULL; .C "(void) sethostent_r(0, &hdbuf); .C "while (gethostent_r(&htbuf, &hdbuf) != -1) .C " count++; .C "(void) endhostent_r(&hdbuf); .fi .RE .SH WARNINGS For the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR gethostent() , .CR gethostbyaddr() , .CR gethostbyname() , .CR sethostent() , and .CR endhostent() are unsafe in multi-thread applications. .CR gethostent_r() , .CR gethostbyaddr_r() , .CR gethostbyname_r() , .CR sethostent_r() , and .CR endhostent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR gethostent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/hosts .SH SEE ALSO named(1M), ypserv(1M), resolver(3N), ypclnt(3C), hosts(4), switch(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR gethostent() ": XPG4" .\" .\" index@\f1end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1entry, get, set, or end network host@@@\f3gethostent(3N)\f1 .\" index@\f1get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1host entry, get, set, or end network@@@\f3gethostent(3N)\f1 .\" index@\f1network host entry, get, set, or end@@@\f3gethostent(3N)\f1 .\" index@\f1set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1thread-safe, get, set, or end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent()\f1 \- end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent_r()\f1 \- end network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent()\f1 \- set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent_r()\f1 \- set network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" .\" links@gethostent.3n endhostent.3n .\" links@gethostent.3n endhostent_.3n .\" links@gethostent.3n gethostbyad.3n .\" links@gethostent.3n gethostbyna.3n .\" links@gethostent.3n gethostent_.3n .\" links@gethostent.3n sethostent.3n .\" links@gethostent.3n sethostent_.3n .\" .\" toc@\f3gethostent(3N)\f1:\0\0\f4endhostent()\f1, \f4endhostent_r()\f1, \f4gethostbyaddr()\f1, \f4gethostbyaddr_r()\f1,\n\f4gethostbyname()\f1, \f4gethostbyname_r()\f1, \f4gethostent()\f1, \f4gethostent_r()\f1,\n\f4sethostent()\f1, \f4sethostent_r()\f1@@@get, set, or end network host entry .\" .\" toc@\f4endhostent()\f1:\0\0end network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4endhostent_r()\f1:\0\0end network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostent_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent()\f1:\0\0set network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent_r()\f1:\0\0set network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" $Header: gethostent.3n,v 78.1 96/03/15 15:56:59 ssa Exp $ .TA g .TH gethostent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gethostent(), gethostent_r(), gethostbyaddr(), gethostbyaddr_r(), gethostbyname(), gethostbyname_r(), sethostent(), sethostent_r(), endhostent(), endhostent_r() \- get network host entry .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .PP .C "extern int h_errno;" .PP .C "struct hostent *gethostent(void);" .PP .C "int gethostent_r(struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyname(const char *name);" .PP .C "int gethostbyname_r(const char *name," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyaddr(const char *addr, .C " int len, .C " int type); .PP .C "_XOPEN_SOURCE_EXTENDED only .C "struct hostent *gethostbyaddr(const void *addr, .C " size_t len, .C " int type); .PP .C "int gethostbyaddr_r(const char *addr," .C " int len," .C " int type," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "int sethostent(int stayopen);" .PP .C "int sethostent_r(int stayopen, struct hostent_data *buffer);" .PP .C "int endhostent(void);" .PP .C "int endhostent_r(struct hostent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only .C "void sethostent(int stayopen);" .C "void endhostent(void);" .fi .SH DESCRIPTION The .CR gethostent() , .CR gethostbyname() , and .CR gethostbyaddr() functions each return a pointer to a structure of type .CR hostent , defined as follows in .CR : .nf .IP .C "struct hostent {" .C " char *h_name;" .C " char **h_aliases;" .C " int h_addrtype;" .C " int h_length;" .C " char **h_addr_list;" .C "};" .IP .C "#define h_addr h_addr_list[0]" .fi .PP The members of this structure are: .RS .TP 20 .CR h_name The official name of the host. .TP .CR h_aliases A null-terminated array of alternate names for the host. .TP .CR h_addrtype The type of address being returned; always .CR AF_INET . .TP .CR h_length The length, in bytes, of the address. .TP .CR h_addr_list A null-terminated array of network addresses for the host. .TP .CR h_addr The first address in .CR h_addr_list ; this is for compatibility with previous HP-UX implementations where a .CR "struct hostent" contains only one network address per host. .RE .SS Reentrant Interfaces .CR gethostent_r() , .CR gethostbyname_r() , and .CR gethostbyaddr_r() expect to be passed the address of a .CR "struct hostent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct hostent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct hostent" will point, as well as state information such as open file descriptors. The .CR "struct hostent_data" is defined in the header file .CR . .PP .CR sethostent_r() and .CR endhostent_r() are to be used only in conjunction with .CR gethostent_r() and take the same pointer to a .CR "struct hostent_data" as a parameter. If the Network Information Service is being used, .CR sethostent_r() initializes an internal database key. If the .CR /etc/hosts file is being used, .CR sethostent_r() opens or rewinds the file. If the .CR named name server (see .IR named (1M)) is being used, then .CR sethostent_r() has no effect. .CR endhostent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR sethostent_r() currently has no effect. However, .CR sethostent() can still be used to keep the .CR /etc/hosts file open, or to use connected stream sockets to the name server, when making calls to .CR gethostbyaddr_r() and .CR gethostbyname_r() . .PP The .I hostf field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to either .CR gethostent_r() or .CR sethostent_r() for the first time. The .I current field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to .CR gethostbyname_r() or .CR gethostbyaddr_r() for the first time. Thereafter, these fields should not be modified in any way. These are the only .CR hostent_data fields that should ever be explicitly accessed. .SS Name Service Switch-Based Operation These host entry library routines internally call the name service switch to access the "hosts" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve host names and Internet addresses. The operations of the three name services: Domain Name Server, NIS, and nonserver mode (e.g., files) are listed below. .SS Domain Name Server Operation If the local system is configured to use the .CR named name server (see .IR named(1M) and .IR resolver(4)) for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Always returns a NULL pointer. .TP .CR sethostent() , Requests the use of a connected stream socket for queries to the name server if the .I stayopen flag is non-zero. The connection is retained after each call to .CR gethostbyname() or .CR gethostbyaddr() . .TP .CR endhostent() Closes the stream socket connection. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the name server. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS NIS Server Operation If .CR ypserv, the server for the Network Information Service (see .IR ypserv (1M)), is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Returns the next entry in the NIS database. .TP .CR sethostent() Initializes an internal key for the NIS database. If the .I stayopen flag is non-zero, the internal key is not cleared after calls to .CR endhostent() . .TP .CR endhostent() Clears the internal NIS database key. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the NIS database. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS Nonserver Operation If the .CR /etc/hosts file is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Reads the next line of .CR /etc/hosts , opening the file if necessary. .TP .CR sethostent() opens and rewinds the file. If the .I stayopen flag is non-zero, the host data base is not closed after each call to .CR gethostent() (either directly or indirectly through one of the other .CR gethost calls). .TP .CR endhostent() Closes the file. .TP .CR gethostbyname() Sequentially searches from the beginning of the file until a host name (among either the official names or the aliases) matching its .I name parameter is found, or until EOF is encountered. Names are matched without respect to uppercase or lowercase, as described above in the name server case. .TP .CR gethostbyaddr() Sequentially searches from the beginning of the file until an Internet address matching its .I addr parameter is found, or until EOF is encountered. .RE .SS Arguments Currently, only the Internet address format is understood. In calls to .CR gethostbyaddr() , the parameter .I addr must be a pointer to an .IR in_addr structure, an Internet address in network order (see .IR byteorder (3N)) and the header file .CR ). The parameter .I len must be the number of bytes in an Internet address; that is, .CR "sizeof (struct in_addr)" . The parameter .I type must be the constant .CR AF_INET . .SH RETURN VALUE If successful, .CR gethostbyname() , .CR gethostbyaddr() , and .CR gethostent() return a pointer to the requested .CR hostent structure. .PP .CR gethostbyname() and .CR gethostbyaddr() return NULL if their .I host or .I addr parameters, respectively, cannot be found in the database. If .CR /etc/hosts is being used, they also return NULL if they are unable to open .CR /etc/hosts . .PP .CR gethostbyaddr() also returns NULL if either its .I addr or .I len parameter is invalid. .PP .CR gethostent() always returns NULL if the name server is being used. .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 is returned if the operation is unsuccessful or, in the case of .CR gethostent_r() , if the end of the hosts list has been reached. .CR 0 is returned otherwise. .SH ERRORS If the name server is being used and .CR gethostbyname() or .CR gethostbyaddr() returns a NULL pointer, the external integer .CR h_errno contains one of the following values: .RS .TP 23 .CR HOST_NOT_FOUND No such host is known. .TP .CR TRY_AGAIN This is usually a temporary error. The local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .CR NO_RECOVERY This is a non-recoverable error. .TP .CR NO_ADDRESS The requested name is valid but does not have an IP address; this is not a temporary error. This means another type of request to the name server will result in an answer. .RE .PP If the name server is not being used, the value of .CR h_errno may not be meaningful. .SH EXAMPLES The following code excerpt counts the number of host entries: .RS .nf .PP .C "int count = 0; .C "struct hostent htbuf; .C "struct hostent_data hdbuf; .PP .C "hdbuf.hostf = NULL; .C "(void) sethostent_r(0, &hdbuf); .C "while (gethostent_r(&htbuf, &hdbuf) != -1) .C " count++; .C "(void) endhostent_r(&hdbuf); .fi .RE .SH WARNINGS For the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR gethostent() , .CR gethostbyaddr() , .CR gethostbyname() , .CR sethostent() , and .CR endhostent() are unsafe in multi-thread applications. .CR gethostent_r() , .CR gethostbyaddr_r() , .CR gethostbyname_r() , .CR sethostent_r() , and .CR endhostent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR gethostent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/hosts .SH SEE ALSO named(1M), ypserv(1M), resolver(3N), ypclnt(3C), hosts(4), switch(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR gethostent() ": XPG4" .\" .\" index@\f1end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1entry, get, set, or end network host@@@\f3gethostent(3N)\f1 .\" index@\f1get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1host entry, get, set, or end network@@@\f3gethostent(3N)\f1 .\" index@\f1network host entry, get, set, or end@@@\f3gethostent(3N)\f1 .\" index@\f1set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1thread-safe, get, set, or end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent()\f1 \- end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent_r()\f1 \- end network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent()\f1 \- set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent_r()\f1 \- set network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" .\" links@gethostent.3n endhostent.3n .\" links@gethostent.3n endhostent_.3n .\" links@gethostent.3n gethostbyad.3n .\" links@gethostent.3n gethostbyna.3n .\" links@gethostent.3n gethostent_.3n .\" links@gethostent.3n sethostent.3n .\" links@gethostent.3n sethostent_.3n .\" .\" toc@\f3gethostent(3N)\f1:\0\0\f4endhostent()\f1, \f4endhostent_r()\f1, \f4gethostbyaddr()\f1, \f4gethostbyaddr_r()\f1,\n\f4gethostbyname()\f1, \f4gethostbyname_r()\f1, \f4gethostent()\f1, \f4gethostent_r()\f1,\n\f4sethostent()\f1, \f4sethostent_r()\f1@@@get, set, or end network host entry .\" .\" toc@\f4endhostent()\f1:\0\0end network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4endhostent_r()\f1:\0\0end network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostent_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent()\f1:\0\0set network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent_r()\f1:\0\0set network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" $Header: gethostent.3n,v 78.1 96/03/15 15:56:59 ssa Exp $ .TA g .TH gethostent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gethostent(), gethostent_r(), gethostbyaddr(), gethostbyaddr_r(), gethostbyname(), gethostbyname_r(), sethostent(), sethostent_r(), endhostent(), endhostent_r() \- get network host entry .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .PP .C "extern int h_errno;" .PP .C "struct hostent *gethostent(void);" .PP .C "int gethostent_r(struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyname(const char *name);" .PP .C "int gethostbyname_r(const char *name," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyaddr(const char *addr, .C " int len, .C " int type); .PP .C "_XOPEN_SOURCE_EXTENDED only .C "struct hostent *gethostbyaddr(const void *addr, .C " size_t len, .C " int type); .PP .C "int gethostbyaddr_r(const char *addr," .C " int len," .C " int type," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "int sethostent(int stayopen);" .PP .C "int sethostent_r(int stayopen, struct hostent_data *buffer);" .PP .C "int endhostent(void);" .PP .C "int endhostent_r(struct hostent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only .C "void sethostent(int stayopen);" .C "void endhostent(void);" .fi .SH DESCRIPTION The .CR gethostent() , .CR gethostbyname() , and .CR gethostbyaddr() functions each return a pointer to a structure of type .CR hostent , defined as follows in .CR : .nf .IP .C "struct hostent {" .C " char *h_name;" .C " char **h_aliases;" .C " int h_addrtype;" .C " int h_length;" .C " char **h_addr_list;" .C "};" .IP .C "#define h_addr h_addr_list[0]" .fi .PP The members of this structure are: .RS .TP 20 .CR h_name The official name of the host. .TP .CR h_aliases A null-terminated array of alternate names for the host. .TP .CR h_addrtype The type of address being returned; always .CR AF_INET . .TP .CR h_length The length, in bytes, of the address. .TP .CR h_addr_list A null-terminated array of network addresses for the host. .TP .CR h_addr The first address in .CR h_addr_list ; this is for compatibility with previous HP-UX implementations where a .CR "struct hostent" contains only one network address per host. .RE .SS Reentrant Interfaces .CR gethostent_r() , .CR gethostbyname_r() , and .CR gethostbyaddr_r() expect to be passed the address of a .CR "struct hostent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct hostent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct hostent" will point, as well as state information such as open file descriptors. The .CR "struct hostent_data" is defined in the header file .CR . .PP .CR sethostent_r() and .CR endhostent_r() are to be used only in conjunction with .CR gethostent_r() and take the same pointer to a .CR "struct hostent_data" as a parameter. If the Network Information Service is being used, .CR sethostent_r() initializes an internal database key. If the .CR /etc/hosts file is being used, .CR sethostent_r() opens or rewinds the file. If the .CR named name server (see .IR named (1M)) is being used, then .CR sethostent_r() has no effect. .CR endhostent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR sethostent_r() currently has no effect. However, .CR sethostent() can still be used to keep the .CR /etc/hosts file open, or to use connected stream sockets to the name server, when making calls to .CR gethostbyaddr_r() and .CR gethostbyname_r() . .PP The .I hostf field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to either .CR gethostent_r() or .CR sethostent_r() for the first time. The .I current field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to .CR gethostbyname_r() or .CR gethostbyaddr_r() for the first time. Thereafter, these fields should not be modified in any way. These are the only .CR hostent_data fields that should ever be explicitly accessed. .SS Name Service Switch-Based Operation These host entry library routines internally call the name service switch to access the "hosts" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve host names and Internet addresses. The operations of the three name services: Domain Name Server, NIS, and nonserver mode (e.g., files) are listed below. .SS Domain Name Server Operation If the local system is configured to use the .CR named name server (see .IR named(1M) and .IR resolver(4)) for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Always returns a NULL pointer. .TP .CR sethostent() , Requests the use of a connected stream socket for queries to the name server if the .I stayopen flag is non-zero. The connection is retained after each call to .CR gethostbyname() or .CR gethostbyaddr() . .TP .CR endhostent() Closes the stream socket connection. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the name server. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS NIS Server Operation If .CR ypserv, the server for the Network Information Service (see .IR ypserv (1M)), is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Returns the next entry in the NIS database. .TP .CR sethostent() Initializes an internal key for the NIS database. If the .I stayopen flag is non-zero, the internal key is not cleared after calls to .CR endhostent() . .TP .CR endhostent() Clears the internal NIS database key. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the NIS database. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS Nonserver Operation If the .CR /etc/hosts file is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Reads the next line of .CR /etc/hosts , opening the file if necessary. .TP .CR sethostent() opens and rewinds the file. If the .I stayopen flag is non-zero, the host data base is not closed after each call to .CR gethostent() (either directly or indirectly through one of the other .CR gethost calls). .TP .CR endhostent() Closes the file. .TP .CR gethostbyname() Sequentially searches from the beginning of the file until a host name (among either the official names or the aliases) matching its .I name parameter is found, or until EOF is encountered. Names are matched without respect to uppercase or lowercase, as described above in the name server case. .TP .CR gethostbyaddr() Sequentially searches from the beginning of the file until an Internet address matching its .I addr parameter is found, or until EOF is encountered. .RE .SS Arguments Currently, only the Internet address format is understood. In calls to .CR gethostbyaddr() , the parameter .I addr must be a pointer to an .IR in_addr structure, an Internet address in network order (see .IR byteorder (3N)) and the header file .CR ). The parameter .I len must be the number of bytes in an Internet address; that is, .CR "sizeof (struct in_addr)" . The parameter .I type must be the constant .CR AF_INET . .SH RETURN VALUE If successful, .CR gethostbyname() , .CR gethostbyaddr() , and .CR gethostent() return a pointer to the requested .CR hostent structure. .PP .CR gethostbyname() and .CR gethostbyaddr() return NULL if their .I host or .I addr parameters, respectively, cannot be found in the database. If .CR /etc/hosts is being used, they also return NULL if they are unable to open .CR /etc/hosts . .PP .CR gethostbyaddr() also returns NULL if either its .I addr or .I len parameter is invalid. .PP .CR gethostent() always returns NULL if the name server is being used. .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 is returned if the operation is unsuccessful or, in the case of .CR gethostent_r() , if the end of the hosts list has been reached. .CR 0 is returned otherwise. .SH ERRORS If the name server is being used and .CR gethostbyname() or .CR gethostbyaddr() returns a NULL pointer, the external integer .CR h_errno contains one of the following values: .RS .TP 23 .CR HOST_NOT_FOUND No such host is known. .TP .CR TRY_AGAIN This is usually a temporary error. The local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .CR NO_RECOVERY This is a non-recoverable error. .TP .CR NO_ADDRESS The requested name is valid but does not have an IP address; this is not a temporary error. This means another type of request to the name server will result in an answer. .RE .PP If the name server is not being used, the value of .CR h_errno may not be meaningful. .SH EXAMPLES The following code excerpt counts the number of host entries: .RS .nf .PP .C "int count = 0; .C "struct hostent htbuf; .C "struct hostent_data hdbuf; .PP .C "hdbuf.hostf = NULL; .C "(void) sethostent_r(0, &hdbuf); .C "while (gethostent_r(&htbuf, &hdbuf) != -1) .C " count++; .C "(void) endhostent_r(&hdbuf); .fi .RE .SH WARNINGS For the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR gethostent() , .CR gethostbyaddr() , .CR gethostbyname() , .CR sethostent() , and .CR endhostent() are unsafe in multi-thread applications. .CR gethostent_r() , .CR gethostbyaddr_r() , .CR gethostbyname_r() , .CR sethostent_r() , and .CR endhostent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR gethostent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/hosts .SH SEE ALSO named(1M), ypserv(1M), resolver(3N), ypclnt(3C), hosts(4), switch(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR gethostent() ": XPG4" .\" .\" index@\f1end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1entry, get, set, or end network host@@@\f3gethostent(3N)\f1 .\" index@\f1get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1host entry, get, set, or end network@@@\f3gethostent(3N)\f1 .\" index@\f1network host entry, get, set, or end@@@\f3gethostent(3N)\f1 .\" index@\f1set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1thread-safe, get, set, or end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent()\f1 \- end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent_r()\f1 \- end network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent()\f1 \- set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent_r()\f1 \- set network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" .\" links@gethostent.3n endhostent.3n .\" links@gethostent.3n endhostent_.3n .\" links@gethostent.3n gethostbyad.3n .\" links@gethostent.3n gethostbyna.3n .\" links@gethostent.3n gethostent_.3n .\" links@gethostent.3n sethostent.3n .\" links@gethostent.3n sethostent_.3n .\" .\" toc@\f3gethostent(3N)\f1:\0\0\f4endhostent()\f1, \f4endhostent_r()\f1, \f4gethostbyaddr()\f1, \f4gethostbyaddr_r()\f1,\n\f4gethostbyname()\f1, \f4gethostbyname_r()\f1, \f4gethostent()\f1, \f4gethostent_r()\f1,\n\f4sethostent()\f1, \f4sethostent_r()\f1@@@get, set, or end network host entry .\" .\" toc@\f4endhostent()\f1:\0\0end network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4endhostent_r()\f1:\0\0end network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostent_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent()\f1:\0\0set network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent_r()\f1:\0\0set network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" $Header: gethostent.3n,v 78.1 96/03/15 15:56:59 ssa Exp $ .TA g .TH gethostent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gethostent(), gethostent_r(), gethostbyaddr(), gethostbyaddr_r(), gethostbyname(), gethostbyname_r(), sethostent(), sethostent_r(), endhostent(), endhostent_r() \- get network host entry .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .PP .C "extern int h_errno;" .PP .C "struct hostent *gethostent(void);" .PP .C "int gethostent_r(struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyname(const char *name);" .PP .C "int gethostbyname_r(const char *name," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyaddr(const char *addr, .C " int len, .C " int type); .PP .C "_XOPEN_SOURCE_EXTENDED only .C "struct hostent *gethostbyaddr(const void *addr, .C " size_t len, .C " int type); .PP .C "int gethostbyaddr_r(const char *addr," .C " int len," .C " int type," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "int sethostent(int stayopen);" .PP .C "int sethostent_r(int stayopen, struct hostent_data *buffer);" .PP .C "int endhostent(void);" .PP .C "int endhostent_r(struct hostent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only .C "void sethostent(int stayopen);" .C "void endhostent(void);" .fi .SH DESCRIPTION The .CR gethostent() , .CR gethostbyname() , and .CR gethostbyaddr() functions each return a pointer to a structure of type .CR hostent , defined as follows in .CR : .nf .IP .C "struct hostent {" .C " char *h_name;" .C " char **h_aliases;" .C " int h_addrtype;" .C " int h_length;" .C " char **h_addr_list;" .C "};" .IP .C "#define h_addr h_addr_list[0]" .fi .PP The members of this structure are: .RS .TP 20 .CR h_name The official name of the host. .TP .CR h_aliases A null-terminated array of alternate names for the host. .TP .CR h_addrtype The type of address being returned; always .CR AF_INET . .TP .CR h_length The length, in bytes, of the address. .TP .CR h_addr_list A null-terminated array of network addresses for the host. .TP .CR h_addr The first address in .CR h_addr_list ; this is for compatibility with previous HP-UX implementations where a .CR "struct hostent" contains only one network address per host. .RE .SS Reentrant Interfaces .CR gethostent_r() , .CR gethostbyname_r() , and .CR gethostbyaddr_r() expect to be passed the address of a .CR "struct hostent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct hostent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct hostent" will point, as well as state information such as open file descriptors. The .CR "struct hostent_data" is defined in the header file .CR . .PP .CR sethostent_r() and .CR endhostent_r() are to be used only in conjunction with .CR gethostent_r() and take the same pointer to a .CR "struct hostent_data" as a parameter. If the Network Information Service is being used, .CR sethostent_r() initializes an internal database key. If the .CR /etc/hosts file is being used, .CR sethostent_r() opens or rewinds the file. If the .CR named name server (see .IR named (1M)) is being used, then .CR sethostent_r() has no effect. .CR endhostent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR sethostent_r() currently has no effect. However, .CR sethostent() can still be used to keep the .CR /etc/hosts file open, or to use connected stream sockets to the name server, when making calls to .CR gethostbyaddr_r() and .CR gethostbyname_r() . .PP The .I hostf field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to either .CR gethostent_r() or .CR sethostent_r() for the first time. The .I current field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to .CR gethostbyname_r() or .CR gethostbyaddr_r() for the first time. Thereafter, these fields should not be modified in any way. These are the only .CR hostent_data fields that should ever be explicitly accessed. .SS Name Service Switch-Based Operation These host entry library routines internally call the name service switch to access the "hosts" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve host names and Internet addresses. The operations of the three name services: Domain Name Server, NIS, and nonserver mode (e.g., files) are listed below. .SS Domain Name Server Operation If the local system is configured to use the .CR named name server (see .IR named(1M) and .IR resolver(4)) for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Always returns a NULL pointer. .TP .CR sethostent() , Requests the use of a connected stream socket for queries to the name server if the .I stayopen flag is non-zero. The connection is retained after each call to .CR gethostbyname() or .CR gethostbyaddr() . .TP .CR endhostent() Closes the stream socket connection. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the name server. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS NIS Server Operation If .CR ypserv, the server for the Network Information Service (see .IR ypserv (1M)), is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Returns the next entry in the NIS database. .TP .CR sethostent() Initializes an internal key for the NIS database. If the .I stayopen flag is non-zero, the internal key is not cleared after calls to .CR endhostent() . .TP .CR endhostent() Clears the internal NIS database key. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the NIS database. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS Nonserver Operation If the .CR /etc/hosts file is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Reads the next line of .CR /etc/hosts , opening the file if necessary. .TP .CR sethostent() opens and rewinds the file. If the .I stayopen flag is non-zero, the host data base is not closed after each call to .CR gethostent() (either directly or indirectly through one of the other .CR gethost calls). .TP .CR endhostent() Closes the file. .TP .CR gethostbyname() Sequentially searches from the beginning of the file until a host name (among either the official names or the aliases) matching its .I name parameter is found, or until EOF is encountered. Names are matched without respect to uppercase or lowercase, as described above in the name server case. .TP .CR gethostbyaddr() Sequentially searches from the beginning of the file until an Internet address matching its .I addr parameter is found, or until EOF is encountered. .RE .SS Arguments Currently, only the Internet address format is understood. In calls to .CR gethostbyaddr() , the parameter .I addr must be a pointer to an .IR in_addr structure, an Internet address in network order (see .IR byteorder (3N)) and the header file .CR ). The parameter .I len must be the number of bytes in an Internet address; that is, .CR "sizeof (struct in_addr)" . The parameter .I type must be the constant .CR AF_INET . .SH RETURN VALUE If successful, .CR gethostbyname() , .CR gethostbyaddr() , and .CR gethostent() return a pointer to the requested .CR hostent structure. .PP .CR gethostbyname() and .CR gethostbyaddr() return NULL if their .I host or .I addr parameters, respectively, cannot be found in the database. If .CR /etc/hosts is being used, they also return NULL if they are unable to open .CR /etc/hosts . .PP .CR gethostbyaddr() also returns NULL if either its .I addr or .I len parameter is invalid. .PP .CR gethostent() always returns NULL if the name server is being used. .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 is returned if the operation is unsuccessful or, in the case of .CR gethostent_r() , if the end of the hosts list has been reached. .CR 0 is returned otherwise. .SH ERRORS If the name server is being used and .CR gethostbyname() or .CR gethostbyaddr() returns a NULL pointer, the external integer .CR h_errno contains one of the following values: .RS .TP 23 .CR HOST_NOT_FOUND No such host is known. .TP .CR TRY_AGAIN This is usually a temporary error. The local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .CR NO_RECOVERY This is a non-recoverable error. .TP .CR NO_ADDRESS The requested name is valid but does not have an IP address; this is not a temporary error. This means another type of request to the name server will result in an answer. .RE .PP If the name server is not being used, the value of .CR h_errno may not be meaningful. .SH EXAMPLES The following code excerpt counts the number of host entries: .RS .nf .PP .C "int count = 0; .C "struct hostent htbuf; .C "struct hostent_data hdbuf; .PP .C "hdbuf.hostf = NULL; .C "(void) sethostent_r(0, &hdbuf); .C "while (gethostent_r(&htbuf, &hdbuf) != -1) .C " count++; .C "(void) endhostent_r(&hdbuf); .fi .RE .SH WARNINGS For the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR gethostent() , .CR gethostbyaddr() , .CR gethostbyname() , .CR sethostent() , and .CR endhostent() are unsafe in multi-thread applications. .CR gethostent_r() , .CR gethostbyaddr_r() , .CR gethostbyname_r() , .CR sethostent_r() , and .CR endhostent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR gethostent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/hosts .SH SEE ALSO named(1M), ypserv(1M), resolver(3N), ypclnt(3C), hosts(4), switch(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR gethostent() ": XPG4" .\" .\" index@\f1end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1entry, get, set, or end network host@@@\f3gethostent(3N)\f1 .\" index@\f1get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1host entry, get, set, or end network@@@\f3gethostent(3N)\f1 .\" index@\f1network host entry, get, set, or end@@@\f3gethostent(3N)\f1 .\" index@\f1set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1thread-safe, get, set, or end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent()\f1 \- end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent_r()\f1 \- end network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent()\f1 \- set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent_r()\f1 \- set network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" .\" links@gethostent.3n endhostent.3n .\" links@gethostent.3n endhostent_.3n .\" links@gethostent.3n gethostbyad.3n .\" links@gethostent.3n gethostbyna.3n .\" links@gethostent.3n gethostent_.3n .\" links@gethostent.3n sethostent.3n .\" links@gethostent.3n sethostent_.3n .\" .\" toc@\f3gethostent(3N)\f1:\0\0\f4endhostent()\f1, \f4endhostent_r()\f1, \f4gethostbyaddr()\f1, \f4gethostbyaddr_r()\f1,\n\f4gethostbyname()\f1, \f4gethostbyname_r()\f1, \f4gethostent()\f1, \f4gethostent_r()\f1,\n\f4sethostent()\f1, \f4sethostent_r()\f1@@@get, set, or end network host entry .\" .\" toc@\f4endhostent()\f1:\0\0end network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4endhostent_r()\f1:\0\0end network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostent_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent()\f1:\0\0set network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent_r()\f1:\0\0set network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" $Header: setlocale.3c,v 72.8 94/11/30 10:15:48 ssa Exp $ .TA s .TH setlocale 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setlocale(\|), setlocale_r(\|), getlocale(\|), getlocale_r(\|) \- set and get the locale of a program .SH SYNOPSIS .CR "#include " .PP .CR "char *setlocale(int category, const char *locale);" .PP .CR "int setlocale_r(int category, const char *locale, char *buffer," .PD 0 .IP .CR " int buflen);" .PD .PP .CR "struct locale_data *getlocale(int type);" .PP .CR "int getlocale_r(int type, struct locale_data *ld);" .SH DESCRIPTION The .CR setlocale() function sets, queries, or restores the aspect of a program's locale that is specified by the .I category argument. A program's locale refers to those areas of the program's Native Language Support (NLS) environment for which the following values of .I category have been defined: .RS .TP 20 .C LC_ALL Affects behavior of all categories below, as well as all .IR nl_langinfo (3C) items. .TP .C LC_COLLATE Affects behavior of regular expressions and the NLS string collation functions (see .IR strcoll (3C), .IR strfxrm (3C), .IR wcscoll (3C), .IR wcsxfrm (3C), and .IR regexp (5)). .TP .C LC_CTYPE Affects behavior of regular expressions, character classification, and conversion functions (see .IR ctype (3C), .IR wctype (3X), .IR wconv (3X), .IR conv (3C), and .IR regexp (5)). The .CR LC_CTYPE category also affects the behavior of all routines that process multibyte characters (see .IR multibyte (3C)). .TP .C LC_MESSAGES Affects the language in which messages are displayed and the processing of affirmative and negative responses (see .IR catopen (3C) and .IR nl_langinfo (3C)). .TP .C LC_MONETARY Affects behavior of functions that handle monetary values (see .IR localeconv (3C) and .IR strfmon (3C)). .TP .C LC_NUMERIC Affects handling of the radix character in the formatted input/output functions (see .IR printf (3C), .IR scanf (3C), and .IR vprintf (3C)) and the string conversion functions (see .IR ecvt (3C) and .IR strtod (3C)). .CR LC_NUMERIC also affects the numeric values found in the .I localeconv structure. .TP .C LC_TIME Affects the behavior of time conversion functions (see .IR getdate (3C), .IR strftime (3C), and .IR strptime (3C)). .RE .PP All .IR nl_langinfo (3C) items are affected by the setting of one of the categories listed above. See .IR langinfo (5) to determine which categories affect each item. .PP The value of the .I locale argument determines the action taken by .CR setlocale() . .I locale is a pointer to a character string. .SS Setting the Locale of a Program To set the program's locale for .IR category , .CR setlocale() accepts one of the following values as the .I locale argument: .IR "locale name" , .CR C , .CR POSIX , or .C """\|""" (the empty string). The actions prescribed by these values are as follows: .RS .TP 20 .I locale name If .I locale is a valid locale name (see .IR lang (5)), .CR setlocale() sets that part of the NLS environment associated with .I category as defined for that locale. .TP .C C If the value of .I locale is set to .CR C , .CR setlocale() sets that part of the NLS environment associated with .I category as defined for the .CR C locale (see .IR lang (5)). The .CR C locale is the default prior to successfully calling .CR setlocale() . .TP .C POSIX Same as .CR C . .ift .br .ift .ne 8 .TP .C """\|""" If the value of .I locale is the empty string, the setting of that part of the NLS environment associated with .I category depends upon the setting of the following environment variables in the user's environment (see .IR environ (5)): .RS .nf .IP .C "LANG LC_MESSAGES" .C "LC_ALL LC_MONETARY" .C "LC_COLLATE LC_NUMERIC" .C "LC_CTYPE LC_TIME" .fi .RE .IP If .I category is any defined value other than .CR LC_ALL , .CR setlocale() sets that category as specified by the value of the .CR LC_ALL environment. This is also the case if .CR LC_ALL is not set to the corresponding environment variable. If the environment variable is not set or is set to the empty string, .CR setlocale() sets the category as specified by the value of the .CR LANG environment variable. If .CR LANG is not set or is set to the empty string, then .CR setlocale() sets the category to the .CR C locale. For example, .RS .IP .C "setlocale(LC_TIME,"""")" .RE .IP sets the program's NLS environment associated with the .CR LC_TIME .I category to the value specified by the user's .CR LC_TIME environment variable. All other aspects of the NLS environment are unaffected. .IP If .I category is .CR LC_ALL , then all categories are set corresponding to the value of .CR LC_ALL if .CR LC_ALL is set, or .CR LANG if .CR LC_ALL is not set, except for those categories in which the corresponding environment variable is set to a valid language name (see .IR lang (5)). In this case the value of the environment variable overrides the values of .CR LC_ALL and .CR LANG for that category. If the values of both .CR LC_ALL and .CR LANG are not set or are set to the empty string, then the .CR C locale is used. .IP The following usage of .CR setlocale() results in the program's locale being set according to the the user's language requirements: .RS .IP .C "setlocale(LC_ALL,"""")" .RE .RE .SS Querying the Locale of a Program .CR setlocale() queries the current NLS environment pertaining to .IR category , if the value of .I locale is NULL. The query operation does not change the environment. The purpose of performing a query is to save that aspect of the user's current NLS environment associated with .IR category , in the value returned by .CR setlocale() , such that it can be restored with a subsequent call to .CR setlocale() . .SS Restoring the Locale of a Program To restore a category within the program locale, a .CR setlocale() call is made with the same .I category argument and the return string of the previous .CR setlocale() call given as the .I locale argument. .PP .CR getlocale() returns a pointer to a .CR locale_data structure (see .CR /usr/include/locale.h ). The members of the .CR locale_data structure contain information about the setting of each .CR setlocale() category. .I type determines what information is contained in the .CR locale_data structure. The only supported value of .I type is: .RS .TP 22 .C LOCALE_STATUS The structure member corresponding to each category contains a string with the name of the locale currently set for that category. The string does not include modifier information. .RE .SS Reentrant Interfaces The .CR setlocale_r() function performs the same function as the .CR setlocale() function except the result string describing locale information for the given category is passed back in the supplied buffer. Note that while .CR setlocale_r() can be called concurrently from multiple threads, the locale data structures that get updated are not protected against reads by other threads. Hence it is up to the application developer to ensure proper synchronization when changing locales. A buffer size of length .CR LC_BUFSIZ (defined in .CR ) is recommended. .PP The .CR getlocale_r() function expects to be passed the address of a .CR "struct locale_data" and stores the requested locale information at the given location. .SH RETURN VALUE If the pointer to a string is given for .I locale and the selection can be honored, the .CR setlocale() function returns a pointer to the string associated with the specified .I category for the new locale. The maximum length of this string is .CR LC_BUFSIZ bytes (see .CR ). If the selection cannot be honored, the .CR setlocale() function returns a null pointer and the program's locale is not changed. .PP A null pointer for .I locale causes .CR setlocale() to return a string associated with the .I category for the program's current locale. .PP The string returned by .CR setlocale() is such that a subsequent call with that string as the .I locale argument and its associated .I category restores that part of the program's locale. .PP For the Reentrant Interfaces, if an error is detected or, in the case of .CR setlocale_r() , the buffer is of insufficient length, .CR \(mi1 is returned. If the operation is successful, .CR 0 is returned. .SH ERRORS If a language name given through the .I locale argument does not identify a valid language name or the language is not available on the system (see .IR lang (5)) a null pointer is returned and the program's locale is not changed. The same behavior occurs when the call: .IP .C "setlocale(LC_ALL, """");" .PP is made and any category related environment variable in the user's environment identifies an invalid language name or a language that is not available on the system. .PP If the .I category argument is not a defined category value, a null pointer is returned and the program's locale is not changed. .PP .CR setlocale() returns a string that reflects the current setting of that aspect of the NLS environment corresponding to the .I category argument. If this return string is used in a subsequent .CR setlocale() call and the .I category arguments of the two calls do not match, the locale remains unchanged and a null pointer is returned. .SH EXAMPLES To set a program's entire locale based on the language requirements specified via the user's environment variables: .IP .C "setlocale(LC_ALL, """");" .PP If in the example the user's environment variables were set as follows: .nf .IP .C "LANG =""de_DE.iso88591"" .C "LC_COLLATE =""es_ES.iso88591"" .C "LC_MONETARY =""""" .C "LC_TIME =""en_US.iso88591"" .fi .PP the .CR LC_CTYPE , .CR LC_MONETARY , and .CR LC_NUMERIC category items would be set to correspond to the .CR de_DE.iso88591 language definition, the .CR LC_COLLATE category items would be set to correspond to the .CR es_ES.iso88591 language definition for collation and the .CR LC_TIME category items would be set corresponding to the .CR en_US.iso88591 language definition. .PP Using the same example, if the following call was made: .IP .C "struct locale_data *locale_info=getlocale(LOCALE_STATUS);" .PP the contents of .CR *locale_info would be: .nf .IP .C "locale_info->LC_ALL_D=""de_DE.iso88591""" .C "locale_info->LC_COLLATE_D=""es_ES.iso88591""" .C "locale_info->LC_CTYPE_D=""de_DE.iso88591""" .C "locale_info->LC_MESSAGES_D=""de_DE.iso88591""" .C "locale_info->LC_MONETARY_D=""de_DE.iso88591""" .C "locale_info->LC_NUMERIC_D=""de_DE.iso88591""" .C "locale_info->LC_TIME_D=""en_US.iso88591""" .fi .PP The next example shows the precedence of the .CR LC_ALL environment variable: .IP .C "setlocale(LC_ALL, """");" .PP with the following settings in the user's environment: .nf .IP .C LANG=de_DE.iso88591 .C LC_ALL=fr_FR.iso88591 .fi .PP All categories will be loaded with .CR fr_FR.iso88591 . .PP Another example showing the precedence of the .CR LC_ALL environment variable: .nf .IP .C "setlocale(LC_CTYPE, """");" .fi .PP with the following settings in the user's environment: .nf .IP .C "LANG=tr_TR.iso88599" .C "LC_ALL=da_DK.iso88591" .C "LC_CTYPE=ru_RU.iso88595" .fi .PP All categories will be loaded with .CR "da_DK.iso88591" . .PP Another example with the .CR LC_ALL environment variable: .IP .C "setlocale(LC_TIME, ""pl_PL.iso88592"");" .PP with the following settings in the user's environment: .nf .IP .C "LANG=it_IT.iso88591" .C "LC_ALL=nl_NL.iso88591" .fi .PP The .CR LC_TIME category will be set to .CR pl_PL.iso88592 , but all other categories will be set to .CR "nl_NL.iso88591" . .PP To set the date/time formats to .CR "fr_FR.iso88591" : .IP .C "setlocale(LC_TIME, ""fr_FR.iso88591"");" .PP To set the collating sequence to the .CR C locale: .IP .C "setlocale(LC_COLLATE, ""C"");" .PP To set monetary handling to the value of the user's .CR LC_MONETARY environment variable: .IP .C "setlocale(LC_MONETARY, """");" .PP Note that if the .CR LC_MONETARY environment variable is not set or is empty, the value of the user's .CR LANG environment variable is used. .PP To query a user's locale: .IP .CR "char *ch = setlocale(LC_ALL, NULL);" .PP To restore the locale saved in the above example: .IP .C "setlocale(LC_ALL, ch);" .PP To query only the part of the user's locale pertaining to the .CR LC_NUMERIC category: .IP .C "char *ch = setlocale(LC_NUMERIC, NULL);" .PP To restore the .CR LC_NUMERIC category of the user's locale saved in the above example: .IP .C "setlocale(LC_NUMERIC, ch);" .SH WARNINGS The format of the return string from .CR setlocale() is implementation specific, is not standardized across vendor's platforms, and is subject to change in future releases. The return string is valid only for the life of the process invoking the .CR setlocale() and should only be used for restoring a previously stored locale setting within the same process. .PP Using .CR getenv() as the .I locale argument is not recommended. An example of such incorrect usage is: .IP .C "setlocale(LC_ALL, getenv(""LANG""));" .PP .CR getenv() returns a character string which can be a language name, an empty string, or a null pointer; depending on the setting of the user's .CR LANG environment variable. Each of these values as the .I locale argument define a specific action to be taken by .CR setlocale() . Therefore the action taken by .CR setlocale() depends upon the value returned from the .CR getenv() call. To ensure that .CR setlocale() sets the program's locale based upon the setting of the user's environment variables the following usage is recommended: .nf .IP .C "setlocale(LC_ALL, """");" .fi .PP The value returned by .CR setlocale() points to a static area that is overwritten during the next call to .CR setlocale() . Be sure to copy these values to another area if they are to be used after a subsequent .CR setlocale() call. .PP .CR getlocale() is an HP proprietary interface, which will be .I obsoleted in a future release, and is not portable to other vendor's platforms. .PP The structure returned through a call to .CR getlocale() is overwritten during the next call to .CR getlocale() . Be sure to save these values if they are to be used after a subsequent .CR getlocale() call. .PP .CR getlocale() and .CR setlocale() are unsafe in multi-thread applications. .CR getlocale_r() and .CR setlocale_r() are MT-Safe and should be used instead. .PP Any program that calls .CR setlocale() before .CR catopen() with the .I oflag parameter set to .CR NL_CAT_LOCALE may behave differently in this release than in previous releases because of the addition of .CR LC_MESSAGES to .CR XPG4 . In the past, .CR catopen() was directed to the desired language by .CR LANG . Now, .CR catopen() with the .I oflag parameter set to .CR NL_CAT_LOCALE , is controlled by .CR LC_MESSAGES . .CR setlocale() can modify the .CR LC_MESSAGES category. For example, if the environment variables are set as follows: .nf .IP .C "LC_MESSAGES=""fr_FR.iso88591"" .fi .PP and the following call to .CR setlocale() is made: .IP .C "setlocale(LC_ALL, ""de_DE.iso88591"");" .PP followed by a call to .CR catopen() , then .CR catopen() will open the message catalogs for .CR de_DE.iso88591 rather than .CR fr_FR.iso88591 . .PP If you use .CR setlocale() and compile/link your application archive, please note that .CR setlocale() has a dependency on .CR libdld.sl that will require a change to the compile/link command. .PP Compile: .IP .C "cc -Wl,-a,archive -Wl,-E -Wl,+n -l:libdld.sl -o " .PP or, .PP Compile with .CR CCOPTS and .CR LDOPTS : .IP .C "export CCOPTS=""-Wl,-a,archive -Wl,-E -l:libdld.sl"" .IP .C "export LDOPTS="" -E +n -l:libdld.sl"" .IP .C "cc -o " .PP The option .CR -Wl,-a,archive is positionally dependent and should occur at the beginning of the compile line. For optimum compatibility in future releases, avoid using archive .CR libc with other shared libraries except for .CR libdld.sl as needed above. .SH AUTHOR .CR setlocale() , .CR setlocale_r() , .CR getlocale() , and .CR getlocale_r() were developed by OSF and HP. .SH FILES .C /usr/include/langinfo.h .br .C /usr/include/locale.h .SH SEE ALSO locale(1), localedef(1M), conv(3C), ctype(3C), ecvt(3C), getdate(3C), multibyte(3C), nl_langinfo(3C), regcomp(3C), strcoll(3C), strerror(3C), strfmon(3C), strftime(3C), string(3C), strptime(3C), strtod(3C), wcsftime(3C), wcstring(3C), printf(3S), scanf(3S), vprintf(3S), wconv(3X), wctype(3X), wstod(3X), wstol(3X), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS COMPLIANCE .CR setlocale() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4getlocale()\f1 \- get the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f4getlocale_r()\f1 \- get the locale of a program (MT-Safe)@@@\f3setlocale(3C)\f1 .\" index@\f4setlocale()\f1 \- set the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f4setlocale_r()\f1 \- set the locale of a program (MT-Safe)@@@\f3setlocale(3C)\f1 .\" index@\f1get the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f1set the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f1locale of a program, get or set the@@@\f3setlocale(3C)\f1 .\" index@\f1program, get or set the locale of a@@@\f3setlocale(3C)\f1 .\" .\" toc@\f3setlocale(3C)\f1:\0\0\f4setlocale_r()\f1, \f4getlocale()\f1, \f4getlocale_r()\f1@@@set and get the locale of a program\f1 .\" toc@\f4getlocale()\f1:\0\0get the locale of a program@@@\f1see \f3setlocale(3C)\f1 .\" toc@\f4getlocale_r()\f1:\0\0get the locale of a program (MT-Safe)@@@\f1see \f3setlocale(3C)\f1 .\" toc@\f4setlocale_r()\f1:\0\0set the locale of a program (MT-Safe)@@@\f1see \f3setlocale(3C)\f1 .\" .\" links@setlocale.3c getlocale.3c .\" links@setlocale.3c getlocale_r.3c .\" links@setlocale.3c setlocale_r.3c .\" $Header: setlocale.3c,v 72.8 94/11/30 10:15:48 ssa Exp $ .TA s .TH setlocale 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setlocale(\|), setlocale_r(\|), getlocale(\|), getlocale_r(\|) \- set and get the locale of a program .SH SYNOPSIS .CR "#include " .PP .CR "char *setlocale(int category, const char *locale);" .PP .CR "int setlocale_r(int category, const char *locale, char *buffer," .PD 0 .IP .CR " int buflen);" .PD .PP .CR "struct locale_data *getlocale(int type);" .PP .CR "int getlocale_r(int type, struct locale_data *ld);" .SH DESCRIPTION The .CR setlocale() function sets, queries, or restores the aspect of a program's locale that is specified by the .I category argument. A program's locale refers to those areas of the program's Native Language Support (NLS) environment for which the following values of .I category have been defined: .RS .TP 20 .C LC_ALL Affects behavior of all categories below, as well as all .IR nl_langinfo (3C) items. .TP .C LC_COLLATE Affects behavior of regular expressions and the NLS string collation functions (see .IR strcoll (3C), .IR strfxrm (3C), .IR wcscoll (3C), .IR wcsxfrm (3C), and .IR regexp (5)). .TP .C LC_CTYPE Affects behavior of regular expressions, character classification, and conversion functions (see .IR ctype (3C), .IR wctype (3X), .IR wconv (3X), .IR conv (3C), and .IR regexp (5)). The .CR LC_CTYPE category also affects the behavior of all routines that process multibyte characters (see .IR multibyte (3C)). .TP .C LC_MESSAGES Affects the language in which messages are displayed and the processing of affirmative and negative responses (see .IR catopen (3C) and .IR nl_langinfo (3C)). .TP .C LC_MONETARY Affects behavior of functions that handle monetary values (see .IR localeconv (3C) and .IR strfmon (3C)). .TP .C LC_NUMERIC Affects handling of the radix character in the formatted input/output functions (see .IR printf (3C), .IR scanf (3C), and .IR vprintf (3C)) and the string conversion functions (see .IR ecvt (3C) and .IR strtod (3C)). .CR LC_NUMERIC also affects the numeric values found in the .I localeconv structure. .TP .C LC_TIME Affects the behavior of time conversion functions (see .IR getdate (3C), .IR strftime (3C), and .IR strptime (3C)). .RE .PP All .IR nl_langinfo (3C) items are affected by the setting of one of the categories listed above. See .IR langinfo (5) to determine which categories affect each item. .PP The value of the .I locale argument determines the action taken by .CR setlocale() . .I locale is a pointer to a character string. .SS Setting the Locale of a Program To set the program's locale for .IR category , .CR setlocale() accepts one of the following values as the .I locale argument: .IR "locale name" , .CR C , .CR POSIX , or .C """\|""" (the empty string). The actions prescribed by these values are as follows: .RS .TP 20 .I locale name If .I locale is a valid locale name (see .IR lang (5)), .CR setlocale() sets that part of the NLS environment associated with .I category as defined for that locale. .TP .C C If the value of .I locale is set to .CR C , .CR setlocale() sets that part of the NLS environment associated with .I category as defined for the .CR C locale (see .IR lang (5)). The .CR C locale is the default prior to successfully calling .CR setlocale() . .TP .C POSIX Same as .CR C . .ift .br .ift .ne 8 .TP .C """\|""" If the value of .I locale is the empty string, the setting of that part of the NLS environment associated with .I category depends upon the setting of the following environment variables in the user's environment (see .IR environ (5)): .RS .nf .IP .C "LANG LC_MESSAGES" .C "LC_ALL LC_MONETARY" .C "LC_COLLATE LC_NUMERIC" .C "LC_CTYPE LC_TIME" .fi .RE .IP If .I category is any defined value other than .CR LC_ALL , .CR setlocale() sets that category as specified by the value of the .CR LC_ALL environment. This is also the case if .CR LC_ALL is not set to the corresponding environment variable. If the environment variable is not set or is set to the empty string, .CR setlocale() sets the category as specified by the value of the .CR LANG environment variable. If .CR LANG is not set or is set to the empty string, then .CR setlocale() sets the category to the .CR C locale. For example, .RS .IP .C "setlocale(LC_TIME,"""")" .RE .IP sets the program's NLS environment associated with the .CR LC_TIME .I category to the value specified by the user's .CR LC_TIME environment variable. All other aspects of the NLS environment are unaffected. .IP If .I category is .CR LC_ALL , then all categories are set corresponding to the value of .CR LC_ALL if .CR LC_ALL is set, or .CR LANG if .CR LC_ALL is not set, except for those categories in which the corresponding environment variable is set to a valid language name (see .IR lang (5)). In this case the value of the environment variable overrides the values of .CR LC_ALL and .CR LANG for that category. If the values of both .CR LC_ALL and .CR LANG are not set or are set to the empty string, then the .CR C locale is used. .IP The following usage of .CR setlocale() results in the program's locale being set according to the the user's language requirements: .RS .IP .C "setlocale(LC_ALL,"""")" .RE .RE .SS Querying the Locale of a Program .CR setlocale() queries the current NLS environment pertaining to .IR category , if the value of .I locale is NULL. The query operation does not change the environment. The purpose of performing a query is to save that aspect of the user's current NLS environment associated with .IR category , in the value returned by .CR setlocale() , such that it can be restored with a subsequent call to .CR setlocale() . .SS Restoring the Locale of a Program To restore a category within the program locale, a .CR setlocale() call is made with the same .I category argument and the return string of the previous .CR setlocale() call given as the .I locale argument. .PP .CR getlocale() returns a pointer to a .CR locale_data structure (see .CR /usr/include/locale.h ). The members of the .CR locale_data structure contain information about the setting of each .CR setlocale() category. .I type determines what information is contained in the .CR locale_data structure. The only supported value of .I type is: .RS .TP 22 .C LOCALE_STATUS The structure member corresponding to each category contains a string with the name of the locale currently set for that category. The string does not include modifier information. .RE .SS Reentrant Interfaces The .CR setlocale_r() function performs the same function as the .CR setlocale() function except the result string describing locale information for the given category is passed back in the supplied buffer. Note that while .CR setlocale_r() can be called concurrently from multiple threads, the locale data structures that get updated are not protected against reads by other threads. Hence it is up to the application developer to ensure proper synchronization when changing locales. A buffer size of length .CR LC_BUFSIZ (defined in .CR ) is recommended. .PP The .CR getlocale_r() function expects to be passed the address of a .CR "struct locale_data" and stores the requested locale information at the given location. .SH RETURN VALUE If the pointer to a string is given for .I locale and the selection can be honored, the .CR setlocale() function returns a pointer to the string associated with the specified .I category for the new locale. The maximum length of this string is .CR LC_BUFSIZ bytes (see .CR ). If the selection cannot be honored, the .CR setlocale() function returns a null pointer and the program's locale is not changed. .PP A null pointer for .I locale causes .CR setlocale() to return a string associated with the .I category for the program's current locale. .PP The string returned by .CR setlocale() is such that a subsequent call with that string as the .I locale argument and its associated .I category restores that part of the program's locale. .PP For the Reentrant Interfaces, if an error is detected or, in the case of .CR setlocale_r() , the buffer is of insufficient length, .CR \(mi1 is returned. If the operation is successful, .CR 0 is returned. .SH ERRORS If a language name given through the .I locale argument does not identify a valid language name or the language is not available on the system (see .IR lang (5)) a null pointer is returned and the program's locale is not changed. The same behavior occurs when the call: .IP .C "setlocale(LC_ALL, """");" .PP is made and any category related environment variable in the user's environment identifies an invalid language name or a language that is not available on the system. .PP If the .I category argument is not a defined category value, a null pointer is returned and the program's locale is not changed. .PP .CR setlocale() returns a string that reflects the current setting of that aspect of the NLS environment corresponding to the .I category argument. If this return string is used in a subsequent .CR setlocale() call and the .I category arguments of the two calls do not match, the locale remains unchanged and a null pointer is returned. .SH EXAMPLES To set a program's entire locale based on the language requirements specified via the user's environment variables: .IP .C "setlocale(LC_ALL, """");" .PP If in the example the user's environment variables were set as follows: .nf .IP .C "LANG =""de_DE.iso88591"" .C "LC_COLLATE =""es_ES.iso88591"" .C "LC_MONETARY =""""" .C "LC_TIME =""en_US.iso88591"" .fi .PP the .CR LC_CTYPE , .CR LC_MONETARY , and .CR LC_NUMERIC category items would be set to correspond to the .CR de_DE.iso88591 language definition, the .CR LC_COLLATE category items would be set to correspond to the .CR es_ES.iso88591 language definition for collation and the .CR LC_TIME category items would be set corresponding to the .CR en_US.iso88591 language definition. .PP Using the same example, if the following call was made: .IP .C "struct locale_data *locale_info=getlocale(LOCALE_STATUS);" .PP the contents of .CR *locale_info would be: .nf .IP .C "locale_info->LC_ALL_D=""de_DE.iso88591""" .C "locale_info->LC_COLLATE_D=""es_ES.iso88591""" .C "locale_info->LC_CTYPE_D=""de_DE.iso88591""" .C "locale_info->LC_MESSAGES_D=""de_DE.iso88591""" .C "locale_info->LC_MONETARY_D=""de_DE.iso88591""" .C "locale_info->LC_NUMERIC_D=""de_DE.iso88591""" .C "locale_info->LC_TIME_D=""en_US.iso88591""" .fi .PP The next example shows the precedence of the .CR LC_ALL environment variable: .IP .C "setlocale(LC_ALL, """");" .PP with the following settings in the user's environment: .nf .IP .C LANG=de_DE.iso88591 .C LC_ALL=fr_FR.iso88591 .fi .PP All categories will be loaded with .CR fr_FR.iso88591 . .PP Another example showing the precedence of the .CR LC_ALL environment variable: .nf .IP .C "setlocale(LC_CTYPE, """");" .fi .PP with the following settings in the user's environment: .nf .IP .C "LANG=tr_TR.iso88599" .C "LC_ALL=da_DK.iso88591" .C "LC_CTYPE=ru_RU.iso88595" .fi .PP All categories will be loaded with .CR "da_DK.iso88591" . .PP Another example with the .CR LC_ALL environment variable: .IP .C "setlocale(LC_TIME, ""pl_PL.iso88592"");" .PP with the following settings in the user's environment: .nf .IP .C "LANG=it_IT.iso88591" .C "LC_ALL=nl_NL.iso88591" .fi .PP The .CR LC_TIME category will be set to .CR pl_PL.iso88592 , but all other categories will be set to .CR "nl_NL.iso88591" . .PP To set the date/time formats to .CR "fr_FR.iso88591" : .IP .C "setlocale(LC_TIME, ""fr_FR.iso88591"");" .PP To set the collating sequence to the .CR C locale: .IP .C "setlocale(LC_COLLATE, ""C"");" .PP To set monetary handling to the value of the user's .CR LC_MONETARY environment variable: .IP .C "setlocale(LC_MONETARY, """");" .PP Note that if the .CR LC_MONETARY environment variable is not set or is empty, the value of the user's .CR LANG environment variable is used. .PP To query a user's locale: .IP .CR "char *ch = setlocale(LC_ALL, NULL);" .PP To restore the locale saved in the above example: .IP .C "setlocale(LC_ALL, ch);" .PP To query only the part of the user's locale pertaining to the .CR LC_NUMERIC category: .IP .C "char *ch = setlocale(LC_NUMERIC, NULL);" .PP To restore the .CR LC_NUMERIC category of the user's locale saved in the above example: .IP .C "setlocale(LC_NUMERIC, ch);" .SH WARNINGS The format of the return string from .CR setlocale() is implementation specific, is not standardized across vendor's platforms, and is subject to change in future releases. The return string is valid only for the life of the process invoking the .CR setlocale() and should only be used for restoring a previously stored locale setting within the same process. .PP Using .CR getenv() as the .I locale argument is not recommended. An example of such incorrect usage is: .IP .C "setlocale(LC_ALL, getenv(""LANG""));" .PP .CR getenv() returns a character string which can be a language name, an empty string, or a null pointer; depending on the setting of the user's .CR LANG environment variable. Each of these values as the .I locale argument define a specific action to be taken by .CR setlocale() . Therefore the action taken by .CR setlocale() depends upon the value returned from the .CR getenv() call. To ensure that .CR setlocale() sets the program's locale based upon the setting of the user's environment variables the following usage is recommended: .nf .IP .C "setlocale(LC_ALL, """");" .fi .PP The value returned by .CR setlocale() points to a static area that is overwritten during the next call to .CR setlocale() . Be sure to copy these values to another area if they are to be used after a subsequent .CR setlocale() call. .PP .CR getlocale() is an HP proprietary interface, which will be .I obsoleted in a future release, and is not portable to other vendor's platforms. .PP The structure returned through a call to .CR getlocale() is overwritten during the next call to .CR getlocale() . Be sure to save these values if they are to be used after a subsequent .CR getlocale() call. .PP .CR getlocale() and .CR setlocale() are unsafe in multi-thread applications. .CR getlocale_r() and .CR setlocale_r() are MT-Safe and should be used instead. .PP Any program that calls .CR setlocale() before .CR catopen() with the .I oflag parameter set to .CR NL_CAT_LOCALE may behave differently in this release than in previous releases because of the addition of .CR LC_MESSAGES to .CR XPG4 . In the past, .CR catopen() was directed to the desired language by .CR LANG . Now, .CR catopen() with the .I oflag parameter set to .CR NL_CAT_LOCALE , is controlled by .CR LC_MESSAGES . .CR setlocale() can modify the .CR LC_MESSAGES category. For example, if the environment variables are set as follows: .nf .IP .C "LC_MESSAGES=""fr_FR.iso88591"" .fi .PP and the following call to .CR setlocale() is made: .IP .C "setlocale(LC_ALL, ""de_DE.iso88591"");" .PP followed by a call to .CR catopen() , then .CR catopen() will open the message catalogs for .CR de_DE.iso88591 rather than .CR fr_FR.iso88591 . .PP If you use .CR setlocale() and compile/link your application archive, please note that .CR setlocale() has a dependency on .CR libdld.sl that will require a change to the compile/link command. .PP Compile: .IP .C "cc -Wl,-a,archive -Wl,-E -Wl,+n -l:libdld.sl -o " .PP or, .PP Compile with .CR CCOPTS and .CR LDOPTS : .IP .C "export CCOPTS=""-Wl,-a,archive -Wl,-E -l:libdld.sl"" .IP .C "export LDOPTS="" -E +n -l:libdld.sl"" .IP .C "cc -o " .PP The option .CR -Wl,-a,archive is positionally dependent and should occur at the beginning of the compile line. For optimum compatibility in future releases, avoid using archive .CR libc with other shared libraries except for .CR libdld.sl as needed above. .SH AUTHOR .CR setlocale() , .CR setlocale_r() , .CR getlocale() , and .CR getlocale_r() were developed by OSF and HP. .SH FILES .C /usr/include/langinfo.h .br .C /usr/include/locale.h .SH SEE ALSO locale(1), localedef(1M), conv(3C), ctype(3C), ecvt(3C), getdate(3C), multibyte(3C), nl_langinfo(3C), regcomp(3C), strcoll(3C), strerror(3C), strfmon(3C), strftime(3C), string(3C), strptime(3C), strtod(3C), wcsftime(3C), wcstring(3C), printf(3S), scanf(3S), vprintf(3S), wconv(3X), wctype(3X), wstod(3X), wstol(3X), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS COMPLIANCE .CR setlocale() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4getlocale()\f1 \- get the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f4getlocale_r()\f1 \- get the locale of a program (MT-Safe)@@@\f3setlocale(3C)\f1 .\" index@\f4setlocale()\f1 \- set the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f4setlocale_r()\f1 \- set the locale of a program (MT-Safe)@@@\f3setlocale(3C)\f1 .\" index@\f1get the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f1set the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f1locale of a program, get or set the@@@\f3setlocale(3C)\f1 .\" index@\f1program, get or set the locale of a@@@\f3setlocale(3C)\f1 .\" .\" toc@\f3setlocale(3C)\f1:\0\0\f4setlocale_r()\f1, \f4getlocale()\f1, \f4getlocale_r()\f1@@@set and get the locale of a program\f1 .\" toc@\f4getlocale()\f1:\0\0get the locale of a program@@@\f1see \f3setlocale(3C)\f1 .\" toc@\f4getlocale_r()\f1:\0\0get the locale of a program (MT-Safe)@@@\f1see \f3setlocale(3C)\f1 .\" toc@\f4setlocale_r()\f1:\0\0set the locale of a program (MT-Safe)@@@\f1see \f3setlocale(3C)\f1 .\" .\" links@setlocale.3c getlocale.3c .\" links@setlocale.3c getlocale_r.3c .\" links@setlocale.3c setlocale_r.3c .\" $Header: getlogin.3c,v 76.1 95/07/05 17:29:21 ssa Exp $ .TA g .TH getlogin 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getlogin(\|), getlogin_r(\|) \- get name of user logged in on this terminal .SH SYNOPSIS .C "#include " .PP .C "char *getlogin(void);" .PP .C "int getlogin_r(char *buf, int buflen);" .SH DESCRIPTION The .CR getlogin() function retrieves the name of the user currently logged in on a terminal associated with the calling process, as found in .CR /etc/utmp . .PP At least one of the standard input, standard output, or standard error must be a terminal. For the first of these found that is a terminal, a user must have logged in on that terminal, and that terminal must be the controlling terminal of the session leader process of the calling process's session. .PP The .CR getlogin() function can be used in conjunction with .CR getpwnam() to locate the correct password file entry when the same user ID is shared by several login names. .PP The recommended procedure to obtain the user name associated with the real user ID of the calling process is to call .CR getlogin() , and if that fails, to call .CR getpwuid(getuid()) . .PP To get the user name associated with the effective user ID, call .CR getpwuid(geteuid()) . .PP .CR getlogin_r() performs the same operations as .CR getlogin() , but returns the login name in the buffer to which .I buf points, whose size in bytes should be passed in .IR buflen . .PP The return value from .CR getlogin() points to static data whose content is overwritten by each call. To avoid this, use .CR getlogin_r() . .SH RETURN VALUE Upon successfully finding and validating the login name of the user logged in on the terminal, .CR getlogin() returns a pointer to the name. Otherwise, it returns a null pointer, and sets .CR errno to indicate the error. .PP Upon successfully finding, validating, and copying to the buffer the login name of the user logged in on the terminal, .CR getlogin_r() returns 0. Otherwise, it returns \(mi1 and sets .CR errno to indicate the error. .ifn .bp .SH ERRORS .CR getlogin() and .CR getlogin_r() fail if any of the following is true: .RS .TP 15 [EACCES] Access permission to read the .CR /etc/utmp file, or to get the status of the terminal device file, was denied. .TP [EMFILE] Too many file descriptors are in use by this process. .TP [ENFILE] Too many file descriptors are in use on the system. .TP [ENOENT] The .CR /etc/utmp file or the terminal device file cannot be found. .TP [ENOTTY] None of the standard input, standard output, or standard error is a terminal, or for the first of these that is a terminal, no current login is registered on that terminal, or the session leader process of the calling process has no controlling terminal. .TP [EPERM] One of the standard input, standard output, or standard error is a terminal, and a current login was found on that terminal, but that terminal is not the same as the controlling terminal of the session of the calling process. .TP [ESRCH] The session leader process of the calling process is no longer running. .RE .PP The error condition associated with [EPERM] prevents processes that have access to some other user's terminal from believing that they are related to that other user's login session. .PP .CR getlogin_r() also fails if the following is true: .RS .TP 15 [ERANGE] The length of the name to be returned, including the terminating null byte, exceeds .IR buflen . .RE .ift .bp .SH FILES .TP 15 .CR /etc/utmp Database that maps user logins to terminals. .SH WARNINGS Users of .CR getlogin_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH SEE ALSO getuid(2), getgrent(3C), getpwent(3C), utmp(4). .SH STANDARDS CONFORMANCE .CR getlogin() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4getlogin()\f1 \- get name of user logged in on this terminal@@@\f3getlogin(3C)\f1 .\" index@\f4getlogin_r()\f1 \- get name of user logged in and return name to buffer@@@\f3getlogin(3C)\f1 .\" index@\f1get name of user logged in on this terminal@@@\f3getlogin(3C)\f1 .\" index@\f1user, get name of user logged in on this terminal@@@\f3getlogin(3C)\f1 .\" index@\f1terminal, get name of user logged in on this terminal@@@\f3getlogin(3C)\f1 .\" index@\f4/etc/utmp\f1, get login name of user from@@@\f3getlogin(3C)\f1 .\" .\" toc@\f3getlogin(3C)\f1:\0\0\f4getlogin()\f1, \f4getlogin_r()\f1@@@get name of user logged in on this terminal\f1 .\" toc@\f4getlogin_r()\f1:\0\0get name of user logged and return to buffer@@@\f1see \f3getlogin(3C)\f1 .\ .\" links@getlogin.3c getlogin_r.3c .\" $Header: getlogin.3c,v 76.1 95/07/05 17:29:21 ssa Exp $ .TA g .TH getlogin 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getlogin(\|), getlogin_r(\|) \- get name of user logged in on this terminal .SH SYNOPSIS .C "#include " .PP .C "char *getlogin(void);" .PP .C "int getlogin_r(char *buf, int buflen);" .SH DESCRIPTION The .CR getlogin() function retrieves the name of the user currently logged in on a terminal associated with the calling process, as found in .CR /etc/utmp . .PP At least one of the standard input, standard output, or standard error must be a terminal. For the first of these found that is a terminal, a user must have logged in on that terminal, and that terminal must be the controlling terminal of the session leader process of the calling process's session. .PP The .CR getlogin() function can be used in conjunction with .CR getpwnam() to locate the correct password file entry when the same user ID is shared by several login names. .PP The recommended procedure to obtain the user name associated with the real user ID of the calling process is to call .CR getlogin() , and if that fails, to call .CR getpwuid(getuid()) . .PP To get the user name associated with the effective user ID, call .CR getpwuid(geteuid()) . .PP .CR getlogin_r() performs the same operations as .CR getlogin() , but returns the login name in the buffer to which .I buf points, whose size in bytes should be passed in .IR buflen . .PP The return value from .CR getlogin() points to static data whose content is overwritten by each call. To avoid this, use .CR getlogin_r() . .SH RETURN VALUE Upon successfully finding and validating the login name of the user logged in on the terminal, .CR getlogin() returns a pointer to the name. Otherwise, it returns a null pointer, and sets .CR errno to indicate the error. .PP Upon successfully finding, validating, and copying to the buffer the login name of the user logged in on the terminal, .CR getlogin_r() returns 0. Otherwise, it returns \(mi1 and sets .CR errno to indicate the error. .ifn .bp .SH ERRORS .CR getlogin() and .CR getlogin_r() fail if any of the following is true: .RS .TP 15 [EACCES] Access permission to read the .CR /etc/utmp file, or to get the status of the terminal device file, was denied. .TP [EMFILE] Too many file descriptors are in use by this process. .TP [ENFILE] Too many file descriptors are in use on the system. .TP [ENOENT] The .CR /etc/utmp file or the terminal device file cannot be found. .TP [ENOTTY] None of the standard input, standard output, or standard error is a terminal, or for the first of these that is a terminal, no current login is registered on that terminal, or the session leader process of the calling process has no controlling terminal. .TP [EPERM] One of the standard input, standard output, or standard error is a terminal, and a current login was found on that terminal, but that terminal is not the same as the controlling terminal of the session of the calling process. .TP [ESRCH] The session leader process of the calling process is no longer running. .RE .PP The error condition associated with [EPERM] prevents processes that have access to some other user's terminal from believing that they are related to that other user's login session. .PP .CR getlogin_r() also fails if the following is true: .RS .TP 15 [ERANGE] The length of the name to be returned, including the terminating null byte, exceeds .IR buflen . .RE .ift .bp .SH FILES .TP 15 .CR /etc/utmp Database that maps user logins to terminals. .SH WARNINGS Users of .CR getlogin_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH SEE ALSO getuid(2), getgrent(3C), getpwent(3C), utmp(4). .SH STANDARDS CONFORMANCE .CR getlogin() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4getlogin()\f1 \- get name of user logged in on this terminal@@@\f3getlogin(3C)\f1 .\" index@\f4getlogin_r()\f1 \- get name of user logged in and return name to buffer@@@\f3getlogin(3C)\f1 .\" index@\f1get name of user logged in on this terminal@@@\f3getlogin(3C)\f1 .\" index@\f1user, get name of user logged in on this terminal@@@\f3getlogin(3C)\f1 .\" index@\f1terminal, get name of user logged in on this terminal@@@\f3getlogin(3C)\f1 .\" index@\f4/etc/utmp\f1, get login name of user from@@@\f3getlogin(3C)\f1 .\" .\" toc@\f3getlogin(3C)\f1:\0\0\f4getlogin()\f1, \f4getlogin_r()\f1@@@get name of user logged in on this terminal\f1 .\" toc@\f4getlogin_r()\f1:\0\0get name of user logged and return to buffer@@@\f1see \f3getlogin(3C)\f1 .\ .\" links@getlogin.3c getlogin_r.3c .\" $Header: getbegyx.3x,v 76.2 95/08/01 10:43:31 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getbegyx 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getbegyx, getmaxyx, getparyx \(em get additional cursor and window coordinates .SH SYNOPSIS .C "#include " .P .C "void getbegyx(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "void getmaxyx(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "void getparyx(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .SH DESCRIPTION .P The .Fn getbegyx macro stores the absolute screen coordinates of the specified window's origin in \f2y\f1 and \f2x\f1. .P The .Fn getmaxyx macro stores the number of rows of the specified window in \f2y\f1 and stores the window's number of columns in \f2x\f1. .P The .Fn getparyx macro, if the specified window is a subwindow, stores in \f2y\f1 and \f2x\f1 the coordinates of the window's origin relative to its parent window. Otherwise, \(mi1 is stored in \f2y\f1 and \f2x\f1. .SH "RETURN VALUE" No return values are defined. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These interfaces are macros and `\f4&\f1' cannot be used before the \f2y\f1 and \f2x\f1 arguments. .SH "SEE ALSO" getyx(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getbegyx(3X)\f1:\0\0\f4getbegyx()\f1, \f4getmaxyx()\f1, \f4getparyx()\f1@@@get additional cursor and window coordinates .\" toc@\f4getmaxyx()\f1: get additional cursor and window coordinates@@@see \f3getbegyx(3X)\f1 .\" toc@\f4getparyx()\f1: get additional cursor and window coordinates@@@see \f3getbegyx(3X)\f1 .\" .\" index@\f4getbegyx()\f1 \- get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f4getmaxyx()\f1 \- get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f4getparyx()\f1 \- get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f1get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f1coordinates, get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f1additional cursor and window coordinates, get @@@\f3getbegyx(3X)\f1 .\" index@\f1cursor and window coordinates, get additional@@@\f3getbegyx(3X)\f1 .\" index@\f1window and cursor coordinates, get additional@@@\f3getbegyx(3X)\f1 .\" .\" links@getbegyx.3x getmaxyx.3x .\" links@getbegyx.3x getparyx.3x .\" .\" fileset_database@getbegyx.3x CURS-ENG-A-MAN .\" $Header: getmntent.3x,v 76.1 95/07/05 17:29:38 ssa Exp $ .TA g .TH getmntent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getmntent(\|), getmntent_r(\|), setmntent(\|), addmntent(\|), endmntent(\|), hasmntopt(\|) \- get file system descriptor file entry .SH SYNOPSIS .C "#include " .PP .C "\s-1FILE\s0 \(**setmntent(const char \(**path, char \(**type);" .PP .C "struct mntent \(**getmntent(\s-1FILE\s0 \(**stream);" .PP .C "int getmntent_r(" .nf .PD 0 .IP .C "\s-1FILE\s0 *stream," .C "struct mntent *result," .C "char *buffer," .C "int buflen);" .PD .PP .C "int addmntent(\s-1FILE\s0 \(**stream, struct mntent \(**mnt);" .PP .C "char \(**hasmntopt(struct mntent \(**mnt, const char \(**opt);" .PP .C "int endmntent(\s-1FILE\s0 \(**stream);" .SH DESCRIPTION These routines replace the obsolete .C getfsent() routines (see .IR getfsent (3X)) for accessing the file system description file .CR /etc/fstab . They are also used to access the mounted file system description file .CR /etc/mnttab . .TP 20 .C setmntent() Opens a file system description file and returns a file pointer which can then be used with .CR getmntent() , .CR addmntent() , or .CR endmntent() . The .I type argument is the same as in .IR fopen (3C). .TP .C getmntent() Reads the next line from .I stream and returns a pointer to an object with the following structure containing the broken-out fields of a line in the file-system description file, .RC < mntent.h >. The fields have meanings described in .IR fstab (4). .nf .IP .C struct mntent { .C " char *mnt_fsname; /* file system name */" .C " char *mnt_dir; /* file system path prefix */" .C " char *mnt_type; /* hfs, nfs, swap, or xx */" .C " char *mnt_opts; /* ro, suid, etc. */" .C " int mnt_freq; /* dump frequency, in days */" .C " int mnt_passno; /* pass number on parallel fsck */" .C " long mnt_time; /* When file system was mounted; */" .C " /* see mnttab(4). */" .C " /* (0 for NFS) */" .C }; .ft .ps .fi .IP .TP .C getmntent_r() Uses three extra parameters to provide results equivalent to those produced by .CR getmntent() . The extra parameters are: .PD 0 .IP 1. The address of a .C "struct mntent" where the result will be stored. .IP 2. A buffer to store character strings to which fields in the .C "struct mntent" will point. .IP 3. The length of the user-supplied buffer. A buffer length of 1025 is recommended. .PD .TP .C addmntent() Adds the .C mntent structure .I mnt to the end of the open file .IR stream . Note that .I stream must be opened for writing. .TP .C hasmntopt() Scans the .C mnt_opts field of the .C mntent structure .I mnt for a substring that matches .IR opt . It returns the address of the substring if a match is found; .C 0 otherwise. .TP .C endmntent() Closes the file. .PP The following definitions are provided in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNT_CHECKLIST "/etc/fstab" #define MNT_MNTTAB "/etc/mnttab" #define MNTMAXSTR 128 /* Max size string in mntent */ #define MNTTYPE_HFS "hfs" /* HFS file system */ #define MNTTYPE_CDFS "hfs" /* CD-ROM file system */ #define MNTTYPE_NFS "nfs" /* Network file system */ #define MNTTYPE_SWAP "swap" /* Swap device */ #define MNTTYPE_SWAPFS "swapfs" /* File system swap */ #define MNTTYPE_IGNORE "ignore" /* Ignore this entry */ #define MNTOPT_DEFAULTS "defaults" /* Use all default options */ #define MNTOPT_RO "ro" /* Read only */ #define MNTOPT_RW "rw" /* Read/write */ #define MNTOPT_SUID "suid" /* Set uid allowed */ #define MNTOPT_NOSUID "nosuid" /* No set uid allowed */ #define MNTOPT_QUOTA "quota" /* Enable disk quotas */ #define MNTOPT_NOQUOTA "noquota" /* Disable disk quotas */ .ft .ps .fi .RE .PP The following definition is provided for device swap in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_END "end" /* swap after end of file system, Series 300/400/700 only */ .ft .ps .fi .RE .PP The following definitions are provided for file system swap in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_MIN "min" /* minimum file system swap */ #define MNTOPT_LIM "lim" /* maximum file system swap */ #define MNTOPT_RES "res" /* reserve space for file system */ #define MNTOPT_PRI "pri" /* file system swap priority */ .ft .ps .RE .PP .SH NETWORKING FEATURES .SS NFS The following definitions are provided in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_BG "bg" /* Retry mount in background */ #define MNTOPT_FG "fg" /* Retry mount in foreground */ #define MNTOPT_RETRY "retry" /* Number of retries allowed */ #define MNTOPT_RSIZE "rsize" /* Read buffer size in bytes */ #define MNTOPT_WSIZE "wsize" /* Write buffer size in bytes*/ #define MNTOPT_TIMEO "timeo" /* Timeout in 1/10 seconds */ #define MNTOPT_RETRANS "retrans" /* Number of retransmissions */ #define MNTOPT_PORT "port" /* Server's IP NFS port */ #define MNTOPT_SOFT "soft" /* Soft mount */ #define MNTOPT_HARD "hard" /* Hard mount */ #define MNTOPT_INTR "intr" /* Interruptable hard mounts */ #define MNTOPT_NOINTR "nointr" /* Uninterruptable hard mounts*/ #define MNTOPT_DEVS "devs" /* Device file access allowed */ #define MNTOPT_NODEVS "nodevs" /* No device file access allowed */ .ft .ps .fi .TE .SH RETURN VALUE .TP 20 .C setmntent() Returns a null pointer on error. .TP .C getmntent() Returns a null pointer on error or EOF. Otherwise, .C getmntent() returns a pointer to a mntent structure. Some of the fields comprising a mntent structure are optional in .C /etc/fstab and .CR /etc/mnttab . In the supplied structure, such missing character pointer fields are set to NULL and missing integer fields are set to \(mi1 for .C mnt_freq and .C mnt_passno. If the integer field for .C mnt_time is missing, it is set to 0. .TP .C getmntent_r() Returns a .C -1 on error or EOF, or if the supplied buffer is of insufficient length. If the operation is successful, .C 0 is returned. .TP .C addmntent() Returns .C 1 on error. .TP .C endmntent() Returns .CR 1 . .SH WARNINGS The return value for .C getmntent() points to static information that is overwritten in each call. Thus, .C getmntent() is unsafe for multi-thread applications. .C getmntent_r() is MT-Safe and should be used instead. .SH AUTHOR .CR addmntent() , .CR endmntent() , .CR getmntent() , .CR hasmntopt() , and .C setmntent() were developed by The University of California, Berkeley, Sun Microsystems, Inc., and HP. .SH FILES .C /etc/fstab .br .C /etc/mnttab .SH SEE ALSO fstab(4), getfsent(3X), mnttab(4). .\" .\" index@\f4getmntent()\f1 \- get a file system description file entry@@@\f3getmntent(3X)\f1 .\" index@\f4setmntent()\f1 \- open a file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4addmntent()\f1 \- add entry to open file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4endmntent()\f1 \- close file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4hasmntopt()\f1 \- search mount option field in file system description file@@@\f3getmntent(3X)\f1 .\" index@file system description file entry@@@\f3getmntent(3X)\f1 .\" index@file entry get file system description@@@\f3getmntent(3X)\f1 .\" index@get file system description file@@@\f3getmntent(3X)\f1 .\" .\" toc@\f3getmntent(3X)\f1:\0\0\f4getmntent()\f1, \f4getmntent_r()\f1, \f4setmntent()\f1, \f4addmntent()\f1, \f4endmntent()\f1, \n\f4hasmntopt()\f1@@@get file system descriptor file entry .\" toc@\f4setmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4addmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4endmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4hasmntopt()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" .\" links@getmntent.3x getmntent_r.3x .\" links@getmntent.3x setmntent.3x .\" links@getmntent.3x addmntent.3x .\" links@getmntent.3x endmntent.3x .\" links@getmntent.3x hasmntopt.3x .\ .\" fileset_database@getmntent.3x PROGRAMING-MAN .\" $Header: getmntent.3x,v 76.1 95/07/05 17:29:38 ssa Exp $ .TA g .TH getmntent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getmntent(\|), getmntent_r(\|), setmntent(\|), addmntent(\|), endmntent(\|), hasmntopt(\|) \- get file system descriptor file entry .SH SYNOPSIS .C "#include " .PP .C "\s-1FILE\s0 \(**setmntent(const char \(**path, char \(**type);" .PP .C "struct mntent \(**getmntent(\s-1FILE\s0 \(**stream);" .PP .C "int getmntent_r(" .nf .PD 0 .IP .C "\s-1FILE\s0 *stream," .C "struct mntent *result," .C "char *buffer," .C "int buflen);" .PD .PP .C "int addmntent(\s-1FILE\s0 \(**stream, struct mntent \(**mnt);" .PP .C "char \(**hasmntopt(struct mntent \(**mnt, const char \(**opt);" .PP .C "int endmntent(\s-1FILE\s0 \(**stream);" .SH DESCRIPTION These routines replace the obsolete .C getfsent() routines (see .IR getfsent (3X)) for accessing the file system description file .CR /etc/fstab . They are also used to access the mounted file system description file .CR /etc/mnttab . .TP 20 .C setmntent() Opens a file system description file and returns a file pointer which can then be used with .CR getmntent() , .CR addmntent() , or .CR endmntent() . The .I type argument is the same as in .IR fopen (3C). .TP .C getmntent() Reads the next line from .I stream and returns a pointer to an object with the following structure containing the broken-out fields of a line in the file-system description file, .RC < mntent.h >. The fields have meanings described in .IR fstab (4). .nf .IP .C struct mntent { .C " char *mnt_fsname; /* file system name */" .C " char *mnt_dir; /* file system path prefix */" .C " char *mnt_type; /* hfs, nfs, swap, or xx */" .C " char *mnt_opts; /* ro, suid, etc. */" .C " int mnt_freq; /* dump frequency, in days */" .C " int mnt_passno; /* pass number on parallel fsck */" .C " long mnt_time; /* When file system was mounted; */" .C " /* see mnttab(4). */" .C " /* (0 for NFS) */" .C }; .ft .ps .fi .IP .TP .C getmntent_r() Uses three extra parameters to provide results equivalent to those produced by .CR getmntent() . The extra parameters are: .PD 0 .IP 1. The address of a .C "struct mntent" where the result will be stored. .IP 2. A buffer to store character strings to which fields in the .C "struct mntent" will point. .IP 3. The length of the user-supplied buffer. A buffer length of 1025 is recommended. .PD .TP .C addmntent() Adds the .C mntent structure .I mnt to the end of the open file .IR stream . Note that .I stream must be opened for writing. .TP .C hasmntopt() Scans the .C mnt_opts field of the .C mntent structure .I mnt for a substring that matches .IR opt . It returns the address of the substring if a match is found; .C 0 otherwise. .TP .C endmntent() Closes the file. .PP The following definitions are provided in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNT_CHECKLIST "/etc/fstab" #define MNT_MNTTAB "/etc/mnttab" #define MNTMAXSTR 128 /* Max size string in mntent */ #define MNTTYPE_HFS "hfs" /* HFS file system */ #define MNTTYPE_CDFS "hfs" /* CD-ROM file system */ #define MNTTYPE_NFS "nfs" /* Network file system */ #define MNTTYPE_SWAP "swap" /* Swap device */ #define MNTTYPE_SWAPFS "swapfs" /* File system swap */ #define MNTTYPE_IGNORE "ignore" /* Ignore this entry */ #define MNTOPT_DEFAULTS "defaults" /* Use all default options */ #define MNTOPT_RO "ro" /* Read only */ #define MNTOPT_RW "rw" /* Read/write */ #define MNTOPT_SUID "suid" /* Set uid allowed */ #define MNTOPT_NOSUID "nosuid" /* No set uid allowed */ #define MNTOPT_QUOTA "quota" /* Enable disk quotas */ #define MNTOPT_NOQUOTA "noquota" /* Disable disk quotas */ .ft .ps .fi .RE .PP The following definition is provided for device swap in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_END "end" /* swap after end of file system, Series 300/400/700 only */ .ft .ps .fi .RE .PP The following definitions are provided for file system swap in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_MIN "min" /* minimum file system swap */ #define MNTOPT_LIM "lim" /* maximum file system swap */ #define MNTOPT_RES "res" /* reserve space for file system */ #define MNTOPT_PRI "pri" /* file system swap priority */ .ft .ps .RE .PP .SH NETWORKING FEATURES .SS NFS The following definitions are provided in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_BG "bg" /* Retry mount in background */ #define MNTOPT_FG "fg" /* Retry mount in foreground */ #define MNTOPT_RETRY "retry" /* Number of retries allowed */ #define MNTOPT_RSIZE "rsize" /* Read buffer size in bytes */ #define MNTOPT_WSIZE "wsize" /* Write buffer size in bytes*/ #define MNTOPT_TIMEO "timeo" /* Timeout in 1/10 seconds */ #define MNTOPT_RETRANS "retrans" /* Number of retransmissions */ #define MNTOPT_PORT "port" /* Server's IP NFS port */ #define MNTOPT_SOFT "soft" /* Soft mount */ #define MNTOPT_HARD "hard" /* Hard mount */ #define MNTOPT_INTR "intr" /* Interruptable hard mounts */ #define MNTOPT_NOINTR "nointr" /* Uninterruptable hard mounts*/ #define MNTOPT_DEVS "devs" /* Device file access allowed */ #define MNTOPT_NODEVS "nodevs" /* No device file access allowed */ .ft .ps .fi .TE .SH RETURN VALUE .TP 20 .C setmntent() Returns a null pointer on error. .TP .C getmntent() Returns a null pointer on error or EOF. Otherwise, .C getmntent() returns a pointer to a mntent structure. Some of the fields comprising a mntent structure are optional in .C /etc/fstab and .CR /etc/mnttab . In the supplied structure, such missing character pointer fields are set to NULL and missing integer fields are set to \(mi1 for .C mnt_freq and .C mnt_passno. If the integer field for .C mnt_time is missing, it is set to 0. .TP .C getmntent_r() Returns a .C -1 on error or EOF, or if the supplied buffer is of insufficient length. If the operation is successful, .C 0 is returned. .TP .C addmntent() Returns .C 1 on error. .TP .C endmntent() Returns .CR 1 . .SH WARNINGS The return value for .C getmntent() points to static information that is overwritten in each call. Thus, .C getmntent() is unsafe for multi-thread applications. .C getmntent_r() is MT-Safe and should be used instead. .SH AUTHOR .CR addmntent() , .CR endmntent() , .CR getmntent() , .CR hasmntopt() , and .C setmntent() were developed by The University of California, Berkeley, Sun Microsystems, Inc., and HP. .SH FILES .C /etc/fstab .br .C /etc/mnttab .SH SEE ALSO fstab(4), getfsent(3X), mnttab(4). .\" .\" index@\f4getmntent()\f1 \- get a file system description file entry@@@\f3getmntent(3X)\f1 .\" index@\f4setmntent()\f1 \- open a file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4addmntent()\f1 \- add entry to open file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4endmntent()\f1 \- close file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4hasmntopt()\f1 \- search mount option field in file system description file@@@\f3getmntent(3X)\f1 .\" index@file system description file entry@@@\f3getmntent(3X)\f1 .\" index@file entry get file system description@@@\f3getmntent(3X)\f1 .\" index@get file system description file@@@\f3getmntent(3X)\f1 .\" .\" toc@\f3getmntent(3X)\f1:\0\0\f4getmntent()\f1, \f4getmntent_r()\f1, \f4setmntent()\f1, \f4addmntent()\f1, \f4endmntent()\f1, \n\f4hasmntopt()\f1@@@get file system descriptor file entry .\" toc@\f4setmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4addmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4endmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4hasmntopt()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" .\" links@getmntent.3x getmntent_r.3x .\" links@getmntent.3x setmntent.3x .\" links@getmntent.3x addmntent.3x .\" links@getmntent.3x endmntent.3x .\" links@getmntent.3x hasmntopt.3x .\ .\" fileset_database@getmntent.3x PROGRAMING-MAN .\" $Header: getn_wstr.3x,v 76.2 95/08/01 10:52:41 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getn_wstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getn_wstr, get_wstr, mvgetn_wstr, mvget_wstr, mvwgetn_wstr, mvwget_wstr, wgetn_wstr, wget_wstr \(em get an array of wide characters and function key codes from a terminal .SH SYNOPSIS .C "#include " .P .C "int getn_wstr(wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int get_wstr(wint_t *\f2wstr\fP);" .P .C "int mvgetn_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvget_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int mvwgetn_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwget_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int wgetn_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int wget_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP);" .SH DESCRIPTION The effect of .Fn get_wstr is as though a series of calls to .Fn get_wch were made, until a newline character, end-of-line character, or end-of-file character is processed. An end-of-file character is represented by WEOF, as defined in .CR . A newline or end-of-line is represented as its .CR wchar_t value. In all instances, the end of the string is terminated by a null .CR wchar_t . The resulting values are placed in the area pointed to by \f2wstr\f1. .P The user's erase and kill characters are interpreted and affect the sequence of characters returned. .P The effect of .Fn wget_wstr is as though a series of calls to .Fn wget_wch were made. .P The effect of .Fn mvget_wstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_wstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. The effect of .Fn mvget_nwstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_nwstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. .P The .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr and .Fn wgetn_wstr functions read at most \f2n\f1 characters, letting the application prevent overflow of the input buffer. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR get_wstr() , .CR mvget_wstr() , .Fn mvwget_wstr or .Fn wget_wstr causes undefined results. The use of .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr or .Fn wgetn_wstr , respectively, is recommended. .P These functions cannot return KEY_ values as there is no way to distinguish a KEY_ value from a valid .B wchar_t value. .SH "SEE ALSO" get_wch(), getstr(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Chapter 9,\f3General Terminal Interface\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getn_wstr(3X)\f1:\0\0\f4getn_wstr()\f1, \f4get_wstr()\f1, \f4mvgetn_wstr()\f1, \f4mvget_wstr()\f1, \f4mvwgetn_wstr()\f1, \n\f4mvwget_wstr()\f1, \f4wgetn_wstr()\f1, \f4wget_wstr()\f1\n@@@get an array of wide characters and function key codes from a terminal .\" toc@\f4get_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" .\" index@\f4getn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4get_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1array of wide characters and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1wide characters, an array of, and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1terminal, get an array of wide characters and function key codes@@@\f3getn_wstr(3X)\f1 .\" .\" links@getn_wstr.3x get_wstr.3x .\" links@getn_wstr.3x mvgetn_wstr.3x .\" links@getn_wstr.3x mvget_wstr.3x .\" links@getn_wstr.3x mvwgetn_wstr.3x .\" links@getn_wstr.3x mvwget_wstr.3x .\" links@getn_wstr.3x wgetn_wstr.3x .\" links@getn_wstr.3x wget_wstr.3x .\" .\" fileset_database@getn_wstr.3x CURS-ENG-A-MAN .\" $Header: secure_rpc.3c,v 74.1 95/05/10 21:12:12 ssa Exp $ .TA s .TH secure_rpc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME secure_rpc(), authdes_create(), authdes_getucred(), get_myaddress(), getnetname(), host2netname(), key_decryptsession(), key_encryptsession(), key_gendes(), key_setsecret(), netname2host(), netname2user(), user2netname() \- library routines for secure remote procedure calls .SH DESCRIPTION .LP .C RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .LP .C RPC allows various authentication flavors. The .B authdes_getucred() and .B authdes_create() routines implement the .B DES authentication flavor. See .BR rpc_clnt_auth (3C) for routines relating to the .B AUTH_NONE and .B AUTH_UNIX authentication types. .IP Note: Both the client and server should have their keys in the .BR publickey (5) database. Also, the keyserver daemon .BR keyserv (1M) must be running on both the client and server hosts for the .B DES authentication system to work. .SS Routines .LP The following routines require that the header .BR be included. .PP The .B AUTH data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "AUTH *" .C "authdes_create(netname, window, syncaddr, deskeyp)" .C "char *netname;" .C "unsigned window;" .C "struct sockaddr_in *syncaddr;" .C "des_block *deskeyp;" .fi .IP .B authdes_create() is an interface to the .B RPC secure authentication system, known as .B DES authentication. .IP Used on the client side, .B authdes_create() returns an authentication handle that enables the use of the secure authentication system. The first parameter .I netname is the network name of the owner of the server process. This field usually represents a .I host derived from the utility routine .BR host2netname() , but could also represent a user name using .BR user2netname() . The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third parameter .I syncaddr is optional. If it is .B NULL, then the authentication system will assume that the local clock is always in sync with the server's clock, and will not attempt to synchronize with the server. If an address is supplied then the system will use it for consulting the remote time service whenever resynchronization is required. This parameter is usually the address of the .B RPC server itself. The final parameter .I deskeyp is also optional. If it is .B NULL, then the authentication system will generate a random .B DES key to be used for the encryption of credentials. If .I deskeyp is supplied then it is used instead. .PP .nf .C "int" .C "authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)" .C "struct authdes_cred *adc;" .C "short *uidp, *gidp, *gidlenp;" .C "int *gidlistp;" .fi .IP .BR authdes_getucred() , is a .B DES authentication routine used by the server for converting a .B DES credential, which is operating system independent, into a .B UNIX credential. .I uidp points to the user .B ID of the user associated with .IR adc ; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. .br .ne 5 .IP This routine differs from the utility routine .B netname2user() in that .B authdes_getucred() pulls its information from a cache, and does not have to do a .B NIS name service lookup every time it is called to get its information. Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "void" .C "get_myaddress(addr)" .C "struct sockaddr_in *addr;" .fi .IP Return the machine's .B IP address in .IR addr. The port number is always set to .BR htons(PMAPPORT) . .PP .nf .C "int" .C "getnetname(netname)" .C "char netname[MAXNETNAMELEN];" .fi .IP Return the unique, operating-system independent netname of the caller in the fixed-length array .IR netname . Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "int" .C "host2netname(netname, host, domain)" .C "char netname[MAXNETNAMELEN];" .C "char *host;" .C "char *domain;" .fi .IP Convert from a domain-specific hostname to an operating-system independent netname. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . This routine should be used if the owner of the server process is the machine that is, the user with effective user .B ID zero. Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2host() . .PP .nf .C "int" .C "key_decryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP An interface routine to the keyserver daemon, which is associated with .B RPC's secure authentication system ( .B DES authentication). User programs rarely need to call it, or its associated routines .BR key_encryptsession() , .B key_gendes() and .BR key_setsecret() . System commands such as .B login and the .B RPC library are the main clients of these four routines. .IP .B key_decryptsession() takes the netname of a server and a .B DES key, and decrypts the key by using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_encryptsession() . .PP .nf .C "int" .C "key_encryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It takes the netname of the server and a .B DES key, and encrypts it using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_decryptsession() . .PP .nf .C "int" .C "key_gendes(deskeyp)" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It is used to ask the keyserver for a secure conversation key. Choosing one at random is usually not good enough, because the common ways of choosing random numbers, such as using the current time, are very easy to guess. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "key_setsecret(keyp)" .C "char *keyp;" .fi .IP A keyserver interface routine. It is used to set the secret key for the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "netname2host(netname, host, hostlen)" .C "char *netname;" .C "char *host;" .C "int hostlen;" .fi .IP Convert an operating-system independent netname to a domain-specific hostname. .I hostlen specifies the size of the array pointed to by .I host. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR host2netname() . .PP .nf .C "int" .C "netname2user(netname, uidp, gidp, gidlenp, gidlistp)" .C "char *netname;" .C "int *uidp, *gidp, *gidlenp, *gidlistp;" .fi .IP Convert an operating-system independent netname to a domain-specific user .B ID. .I uidp points to the user .B ID of the user; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR user2netname() . .PP .nf .C "int" .C "user2netname(netname, uid, domain)" .C "char netname[MAXNETNAMELEN];" .C "int uid;" .C "char *domain;" .fi .IP Convert a domain-specific username to an operating-system independent netname. .I uid is the user .B ID of the owner of the server process. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2user() . .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR login (1), .BR chkey (1), .BR rpc (3C), .BR rpc_clnt_auth (3C), .BR publickey (4), .BR keyserv (1M), .BR newkey (1M) .\" toc@\f3secure_rpc(3C)\f1:\0\0\f4authdes_create()\fP, \f4authdes_getucred()\fP, \f4get_myaddress()\fP, \n\f4getnetaddress()\fP, \f4getnetname()\fP, \f4host2netname()\fP, \n\f4key_decryptsession()\fP, \f4key_encryptsession()\fP, \f4key_gendes()\fP, \n\f4key_setsecret()\fP, \f4netname2host()\fP, \f4netname2user()\fP, \n\f4user2netname()\fP@@@library routines for secure remote procedure calls .\" toc@\f4secure_rpc()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_create()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_getucred()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4get_myaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4host2netname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_decryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_encryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_gendes()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_setsecret()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2host()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2user()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4user2netname()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" index@library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4secure_rpc()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_create()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_getucred()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4get_myaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4host2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_decryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_encryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_gendes()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_setsecret()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2host()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2user()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4user2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" links@secure_rpc.3c authdes_create.3c .\" links@secure_rpc.3c authdes_getucred.3c .\" links@secure_rpc.3c get_myaddress.3c .\" links@secure_rpc.3c getnetaddress.3c .\" links@secure_rpc.3c getnetname.3c .\" links@secure_rpc.3c host2netname.3c .\" links@secure_rpc.3c key_decryptsession.3c .\" links@secure_rpc.3c key_encryptsession.3c .\" links@secure_rpc.3c key_gendes.3c .\" links@secure_rpc.3c key_setsecret.3c .\" links@secure_rpc.3c netname2host.3c .\" links@secure_rpc.3c netname2user.3c .\" links@secure_rpc.3c user2netname.3c .\" $Header: getnetent.3n,v 78.1 96/03/15 15:57:28 ssa Exp $ .TA g .TH getnetent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnetent(\|), getnetent_r(\|), getnetbyaddr(\|), getnetbyaddr_r(\|), getnetbyname(\|), getnetbyname_r(\|), setnetent(\|), setnetent_r(\|), endnetent(\|),endnetent_r(\|) \- get network entry .SH SYNOPSIS .nf .C #include .C #include .PP .C "struct netent *getnetent(void);" .PP .C "int getnetent_r(struct netent *result, struct netent_data *buffer);" .PP .C "struct netent *getnetbyname(const char *name);" .PP .C "int getnetbyname_r(" .PD 0 .IP .C "const char *name," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "struct netent *getnetbyaddr(int net, int type);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "struct netent *getnetbyaddr(in_addr_t net, int type);" .PP .C "int getnetbyaddr_r(" .PD 0 .IP .C "int net," .C "int type," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "int setnetent(int stayopen);" .PP .C "int setnetent_r(int stayopen, struct netent_data *buffer);" .PP .C "int endnetent(void);" .PP .C "int endnetent_r(struct netent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setnetent(int stayopen);" .C "void endnetent(void);" .fi .SH DESCRIPTION .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() each return a pointer to a structure of type .I netent containing the broken-out fields of a line in the network data base, .CR /etc/networks . .PP The members of this structure are: .RS .TP 15 .CR n_name The official name of the network. .TP .CR n_aliases A null-terminated list of alternate names for the network. .TP .CR n_addrtype The type of the network number returned; always AF_INET. .TP .CR n_net The network number. .RE .PP Functions behave as follows: .RS .TP 22 .CR getnetent() Reads the next line of the file, opening the file if necessary. .TP .CR setnetent() opens and rewinds the file. If the .I stayopen flag is non-zero, the network data base is not closed after each call to .CR getnetent() (either directly or indirectly through one of the other .CR getnet* calls). .TP .CR endnetent() Closes the file. .TP .CR getnetbyname() Sequentially searches from the beginning of the file until a network name (among either the official names or the aliases) matching its parameter .I name is found, or until .SM EOF is encountered. .TP .CR getnetbyaddr() Sequentially searches from the beginning of the file until a network number matching its parameter .I net is found, or until .SM EOF is encountered. The parameter .I net must be in network order. The parameter .I type must be the constant .CR AF_INET . Network numbers are supplied in host order (see .IR byteorder (3N)). .PP If the system is running Network Information Service .SM (NFS), .CR getnetbyname() and .CR getnetbyaddr() obtain their network information from the .SM NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getnetent_r() , .CR getnetbyname_r() and .CR getnetbyaddr_r() expect to be passed the address of a .I "struct netent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct netent_data" , must also be supplied. This structure is used to store data, to which fields in the .I "struct netent" will point, as well as state information such as open file descriptors. The .I "struct netent_data" is defined in the file .CR . .PP .CR setnetent_r() and .CR endnetent_r() are to be used only in conjunction with .CR getnetent_r() and take the same pointer to a .I "struct netent_data" as a parameter. If the Network Information Service is being used, .CR setnetent_r() initializes an internal database key. If the .B /etc/networks file is being used, .CR setnetent_r() opens or rewinds the file. .CR endnetent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setnetent_r() currently has no effect. However, .CR setnetent() can still be used to keep the .B /etc/networks file open when making calls to .CR getnetbyaddr_r() and .CR getnetbyname_r() . .PP The .I net_fp field in the .I "struct netent_data" must be initialized to .SM NULL before it is passed to either .CR getnetent_r() or .CR setnetent_r() for the first time. Thereafter it should not be modified in any way. This is the only .I netent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getnetbyname() , .CR getnetbyaddr() , .CR getnetent() , and their reentrant counterparts, internally call the name service switch to access the "networks" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve network names and addresses. .SH RETURN VALUE .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() return a null pointer (0) on .SM EOF or when they are unable to open .CR /etc/networks . .CR getnetbyaddr() also returns a null pointer if its .I type parameter is invalid. .PP .CR getnetent_r() , .CR getnetbyname_r() , .CR getnetbyaddr_r() , .CR setnetent_r() , and .CR endnetent_r() return a -1 if the operation is unsuccessful or, in the case of .CR getnetent_r() , if the end of the networks list has been reached. A 0 is returned otherwise. .SH EXAMPLE The following code excerpt counts the number of network entries: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct netent netbuf; struct netent_data ndbuf; ndbuf.net_fp = NULL; (void) setnetent_r(0, &ndbuf); while (getnetent_r(&netbuf, &ndbuf) != -1) count++; (void) endnetent_r(&ndbuf); .ft .ps .fi .RE .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getnetent() , .CR getnetbyaddr() , .CR getnetbyname() , .CR setnetent() , and .CR endnetent() are unsafe in multi-thread applications. .CR getnetent_r() , .CR getnetbyaddr_r() , .CR getnetbyname_r() , .CR setnetent_r() , and .CR endnetent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getnetent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/networks .SH SEE ALSO ypserv(1M), networks(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getnetent() ": XPG4" .\" .\" index@\f4endnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyaddr()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyname()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4setnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1set network entry@@@\f3getnetent(3N)\f1 .\" index@\f1network entry, get or set@@@\f3getnetent(3N)\f1 .\" .\" toc@\f3getnetent(3N)\f1:\0\0\f4getnetent()\f1, \f4getnetbyaddr()\f1, \f4getnetbyname()\f1, \f4setnetent()\f1, \n\f4endnetent()\f1@@@get network entry .\" toc@\f4getnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" .\" links@getnetent.3n getnetbyadd.3n .\" links@getnetent.3n getnetbynam.3n .\" links@getnetent.3n setnetent.3n .\" links@getnetent.3n endnetent.3n .\" links@getnetent.3n getnetent_r.3n .\" links@getnetent.3n getnetbyaddr_r.3n .\" links@getnetent.3n getnetbyname_r.3n .\" links@getnetent.3n setnetent_r.3n .\" links@getnetent.3n endnetent_r.3n .\" .\" fileset_database@getnetent.3n INETSVCS-MAN .\" $Header: getnetent.3n,v 78.1 96/03/15 15:57:28 ssa Exp $ .TA g .TH getnetent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnetent(\|), getnetent_r(\|), getnetbyaddr(\|), getnetbyaddr_r(\|), getnetbyname(\|), getnetbyname_r(\|), setnetent(\|), setnetent_r(\|), endnetent(\|),endnetent_r(\|) \- get network entry .SH SYNOPSIS .nf .C #include .C #include .PP .C "struct netent *getnetent(void);" .PP .C "int getnetent_r(struct netent *result, struct netent_data *buffer);" .PP .C "struct netent *getnetbyname(const char *name);" .PP .C "int getnetbyname_r(" .PD 0 .IP .C "const char *name," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "struct netent *getnetbyaddr(int net, int type);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "struct netent *getnetbyaddr(in_addr_t net, int type);" .PP .C "int getnetbyaddr_r(" .PD 0 .IP .C "int net," .C "int type," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "int setnetent(int stayopen);" .PP .C "int setnetent_r(int stayopen, struct netent_data *buffer);" .PP .C "int endnetent(void);" .PP .C "int endnetent_r(struct netent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setnetent(int stayopen);" .C "void endnetent(void);" .fi .SH DESCRIPTION .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() each return a pointer to a structure of type .I netent containing the broken-out fields of a line in the network data base, .CR /etc/networks . .PP The members of this structure are: .RS .TP 15 .CR n_name The official name of the network. .TP .CR n_aliases A null-terminated list of alternate names for the network. .TP .CR n_addrtype The type of the network number returned; always AF_INET. .TP .CR n_net The network number. .RE .PP Functions behave as follows: .RS .TP 22 .CR getnetent() Reads the next line of the file, opening the file if necessary. .TP .CR setnetent() opens and rewinds the file. If the .I stayopen flag is non-zero, the network data base is not closed after each call to .CR getnetent() (either directly or indirectly through one of the other .CR getnet* calls). .TP .CR endnetent() Closes the file. .TP .CR getnetbyname() Sequentially searches from the beginning of the file until a network name (among either the official names or the aliases) matching its parameter .I name is found, or until .SM EOF is encountered. .TP .CR getnetbyaddr() Sequentially searches from the beginning of the file until a network number matching its parameter .I net is found, or until .SM EOF is encountered. The parameter .I net must be in network order. The parameter .I type must be the constant .CR AF_INET . Network numbers are supplied in host order (see .IR byteorder (3N)). .PP If the system is running Network Information Service .SM (NFS), .CR getnetbyname() and .CR getnetbyaddr() obtain their network information from the .SM NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getnetent_r() , .CR getnetbyname_r() and .CR getnetbyaddr_r() expect to be passed the address of a .I "struct netent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct netent_data" , must also be supplied. This structure is used to store data, to which fields in the .I "struct netent" will point, as well as state information such as open file descriptors. The .I "struct netent_data" is defined in the file .CR . .PP .CR setnetent_r() and .CR endnetent_r() are to be used only in conjunction with .CR getnetent_r() and take the same pointer to a .I "struct netent_data" as a parameter. If the Network Information Service is being used, .CR setnetent_r() initializes an internal database key. If the .B /etc/networks file is being used, .CR setnetent_r() opens or rewinds the file. .CR endnetent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setnetent_r() currently has no effect. However, .CR setnetent() can still be used to keep the .B /etc/networks file open when making calls to .CR getnetbyaddr_r() and .CR getnetbyname_r() . .PP The .I net_fp field in the .I "struct netent_data" must be initialized to .SM NULL before it is passed to either .CR getnetent_r() or .CR setnetent_r() for the first time. Thereafter it should not be modified in any way. This is the only .I netent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getnetbyname() , .CR getnetbyaddr() , .CR getnetent() , and their reentrant counterparts, internally call the name service switch to access the "networks" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve network names and addresses. .SH RETURN VALUE .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() return a null pointer (0) on .SM EOF or when they are unable to open .CR /etc/networks . .CR getnetbyaddr() also returns a null pointer if its .I type parameter is invalid. .PP .CR getnetent_r() , .CR getnetbyname_r() , .CR getnetbyaddr_r() , .CR setnetent_r() , and .CR endnetent_r() return a -1 if the operation is unsuccessful or, in the case of .CR getnetent_r() , if the end of the networks list has been reached. A 0 is returned otherwise. .SH EXAMPLE The following code excerpt counts the number of network entries: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct netent netbuf; struct netent_data ndbuf; ndbuf.net_fp = NULL; (void) setnetent_r(0, &ndbuf); while (getnetent_r(&netbuf, &ndbuf) != -1) count++; (void) endnetent_r(&ndbuf); .ft .ps .fi .RE .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getnetent() , .CR getnetbyaddr() , .CR getnetbyname() , .CR setnetent() , and .CR endnetent() are unsafe in multi-thread applications. .CR getnetent_r() , .CR getnetbyaddr_r() , .CR getnetbyname_r() , .CR setnetent_r() , and .CR endnetent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getnetent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/networks .SH SEE ALSO ypserv(1M), networks(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getnetent() ": XPG4" .\" .\" index@\f4endnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyaddr()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyname()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4setnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1set network entry@@@\f3getnetent(3N)\f1 .\" index@\f1network entry, get or set@@@\f3getnetent(3N)\f1 .\" .\" toc@\f3getnetent(3N)\f1:\0\0\f4getnetent()\f1, \f4getnetbyaddr()\f1, \f4getnetbyname()\f1, \f4setnetent()\f1, \n\f4endnetent()\f1@@@get network entry .\" toc@\f4getnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" .\" links@getnetent.3n getnetbyadd.3n .\" links@getnetent.3n getnetbynam.3n .\" links@getnetent.3n setnetent.3n .\" links@getnetent.3n endnetent.3n .\" links@getnetent.3n getnetent_r.3n .\" links@getnetent.3n getnetbyaddr_r.3n .\" links@getnetent.3n getnetbyname_r.3n .\" links@getnetent.3n setnetent_r.3n .\" links@getnetent.3n endnetent_r.3n .\" .\" fileset_database@getnetent.3n INETSVCS-MAN .\" $Header: getnetent.3n,v 78.1 96/03/15 15:57:28 ssa Exp $ .TA g .TH getnetent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnetent(\|), getnetent_r(\|), getnetbyaddr(\|), getnetbyaddr_r(\|), getnetbyname(\|), getnetbyname_r(\|), setnetent(\|), setnetent_r(\|), endnetent(\|),endnetent_r(\|) \- get network entry .SH SYNOPSIS .nf .C #include .C #include .PP .C "struct netent *getnetent(void);" .PP .C "int getnetent_r(struct netent *result, struct netent_data *buffer);" .PP .C "struct netent *getnetbyname(const char *name);" .PP .C "int getnetbyname_r(" .PD 0 .IP .C "const char *name," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "struct netent *getnetbyaddr(int net, int type);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "struct netent *getnetbyaddr(in_addr_t net, int type);" .PP .C "int getnetbyaddr_r(" .PD 0 .IP .C "int net," .C "int type," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "int setnetent(int stayopen);" .PP .C "int setnetent_r(int stayopen, struct netent_data *buffer);" .PP .C "int endnetent(void);" .PP .C "int endnetent_r(struct netent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setnetent(int stayopen);" .C "void endnetent(void);" .fi .SH DESCRIPTION .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() each return a pointer to a structure of type .I netent containing the broken-out fields of a line in the network data base, .CR /etc/networks . .PP The members of this structure are: .RS .TP 15 .CR n_name The official name of the network. .TP .CR n_aliases A null-terminated list of alternate names for the network. .TP .CR n_addrtype The type of the network number returned; always AF_INET. .TP .CR n_net The network number. .RE .PP Functions behave as follows: .RS .TP 22 .CR getnetent() Reads the next line of the file, opening the file if necessary. .TP .CR setnetent() opens and rewinds the file. If the .I stayopen flag is non-zero, the network data base is not closed after each call to .CR getnetent() (either directly or indirectly through one of the other .CR getnet* calls). .TP .CR endnetent() Closes the file. .TP .CR getnetbyname() Sequentially searches from the beginning of the file until a network name (among either the official names or the aliases) matching its parameter .I name is found, or until .SM EOF is encountered. .TP .CR getnetbyaddr() Sequentially searches from the beginning of the file until a network number matching its parameter .I net is found, or until .SM EOF is encountered. The parameter .I net must be in network order. The parameter .I type must be the constant .CR AF_INET . Network numbers are supplied in host order (see .IR byteorder (3N)). .PP If the system is running Network Information Service .SM (NFS), .CR getnetbyname() and .CR getnetbyaddr() obtain their network information from the .SM NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getnetent_r() , .CR getnetbyname_r() and .CR getnetbyaddr_r() expect to be passed the address of a .I "struct netent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct netent_data" , must also be supplied. This structure is used to store data, to which fields in the .I "struct netent" will point, as well as state information such as open file descriptors. The .I "struct netent_data" is defined in the file .CR . .PP .CR setnetent_r() and .CR endnetent_r() are to be used only in conjunction with .CR getnetent_r() and take the same pointer to a .I "struct netent_data" as a parameter. If the Network Information Service is being used, .CR setnetent_r() initializes an internal database key. If the .B /etc/networks file is being used, .CR setnetent_r() opens or rewinds the file. .CR endnetent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setnetent_r() currently has no effect. However, .CR setnetent() can still be used to keep the .B /etc/networks file open when making calls to .CR getnetbyaddr_r() and .CR getnetbyname_r() . .PP The .I net_fp field in the .I "struct netent_data" must be initialized to .SM NULL before it is passed to either .CR getnetent_r() or .CR setnetent_r() for the first time. Thereafter it should not be modified in any way. This is the only .I netent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getnetbyname() , .CR getnetbyaddr() , .CR getnetent() , and their reentrant counterparts, internally call the name service switch to access the "networks" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve network names and addresses. .SH RETURN VALUE .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() return a null pointer (0) on .SM EOF or when they are unable to open .CR /etc/networks . .CR getnetbyaddr() also returns a null pointer if its .I type parameter is invalid. .PP .CR getnetent_r() , .CR getnetbyname_r() , .CR getnetbyaddr_r() , .CR setnetent_r() , and .CR endnetent_r() return a -1 if the operation is unsuccessful or, in the case of .CR getnetent_r() , if the end of the networks list has been reached. A 0 is returned otherwise. .SH EXAMPLE The following code excerpt counts the number of network entries: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct netent netbuf; struct netent_data ndbuf; ndbuf.net_fp = NULL; (void) setnetent_r(0, &ndbuf); while (getnetent_r(&netbuf, &ndbuf) != -1) count++; (void) endnetent_r(&ndbuf); .ft .ps .fi .RE .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getnetent() , .CR getnetbyaddr() , .CR getnetbyname() , .CR setnetent() , and .CR endnetent() are unsafe in multi-thread applications. .CR getnetent_r() , .CR getnetbyaddr_r() , .CR getnetbyname_r() , .CR setnetent_r() , and .CR endnetent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getnetent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/networks .SH SEE ALSO ypserv(1M), networks(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getnetent() ": XPG4" .\" .\" index@\f4endnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyaddr()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyname()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4setnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1set network entry@@@\f3getnetent(3N)\f1 .\" index@\f1network entry, get or set@@@\f3getnetent(3N)\f1 .\" .\" toc@\f3getnetent(3N)\f1:\0\0\f4getnetent()\f1, \f4getnetbyaddr()\f1, \f4getnetbyname()\f1, \f4setnetent()\f1, \n\f4endnetent()\f1@@@get network entry .\" toc@\f4getnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" .\" links@getnetent.3n getnetbyadd.3n .\" links@getnetent.3n getnetbynam.3n .\" links@getnetent.3n setnetent.3n .\" links@getnetent.3n endnetent.3n .\" links@getnetent.3n getnetent_r.3n .\" links@getnetent.3n getnetbyaddr_r.3n .\" links@getnetent.3n getnetbyname_r.3n .\" links@getnetent.3n setnetent_r.3n .\" links@getnetent.3n endnetent_r.3n .\" .\" fileset_database@getnetent.3n INETSVCS-MAN .\" $Header: getnetent.3n,v 78.1 96/03/15 15:57:28 ssa Exp $ .TA g .TH getnetent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnetent(\|), getnetent_r(\|), getnetbyaddr(\|), getnetbyaddr_r(\|), getnetbyname(\|), getnetbyname_r(\|), setnetent(\|), setnetent_r(\|), endnetent(\|),endnetent_r(\|) \- get network entry .SH SYNOPSIS .nf .C #include .C #include .PP .C "struct netent *getnetent(void);" .PP .C "int getnetent_r(struct netent *result, struct netent_data *buffer);" .PP .C "struct netent *getnetbyname(const char *name);" .PP .C "int getnetbyname_r(" .PD 0 .IP .C "const char *name," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "struct netent *getnetbyaddr(int net, int type);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "struct netent *getnetbyaddr(in_addr_t net, int type);" .PP .C "int getnetbyaddr_r(" .PD 0 .IP .C "int net," .C "int type," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "int setnetent(int stayopen);" .PP .C "int setnetent_r(int stayopen, struct netent_data *buffer);" .PP .C "int endnetent(void);" .PP .C "int endnetent_r(struct netent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setnetent(int stayopen);" .C "void endnetent(void);" .fi .SH DESCRIPTION .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() each return a pointer to a structure of type .I netent containing the broken-out fields of a line in the network data base, .CR /etc/networks . .PP The members of this structure are: .RS .TP 15 .CR n_name The official name of the network. .TP .CR n_aliases A null-terminated list of alternate names for the network. .TP .CR n_addrtype The type of the network number returned; always AF_INET. .TP .CR n_net The network number. .RE .PP Functions behave as follows: .RS .TP 22 .CR getnetent() Reads the next line of the file, opening the file if necessary. .TP .CR setnetent() opens and rewinds the file. If the .I stayopen flag is non-zero, the network data base is not closed after each call to .CR getnetent() (either directly or indirectly through one of the other .CR getnet* calls). .TP .CR endnetent() Closes the file. .TP .CR getnetbyname() Sequentially searches from the beginning of the file until a network name (among either the official names or the aliases) matching its parameter .I name is found, or until .SM EOF is encountered. .TP .CR getnetbyaddr() Sequentially searches from the beginning of the file until a network number matching its parameter .I net is found, or until .SM EOF is encountered. The parameter .I net must be in network order. The parameter .I type must be the constant .CR AF_INET . Network numbers are supplied in host order (see .IR byteorder (3N)). .PP If the system is running Network Information Service .SM (NFS), .CR getnetbyname() and .CR getnetbyaddr() obtain their network information from the .SM NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getnetent_r() , .CR getnetbyname_r() and .CR getnetbyaddr_r() expect to be passed the address of a .I "struct netent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct netent_data" , must also be supplied. This structure is used to store data, to which fields in the .I "struct netent" will point, as well as state information such as open file descriptors. The .I "struct netent_data" is defined in the file .CR . .PP .CR setnetent_r() and .CR endnetent_r() are to be used only in conjunction with .CR getnetent_r() and take the same pointer to a .I "struct netent_data" as a parameter. If the Network Information Service is being used, .CR setnetent_r() initializes an internal database key. If the .B /etc/networks file is being used, .CR setnetent_r() opens or rewinds the file. .CR endnetent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setnetent_r() currently has no effect. However, .CR setnetent() can still be used to keep the .B /etc/networks file open when making calls to .CR getnetbyaddr_r() and .CR getnetbyname_r() . .PP The .I net_fp field in the .I "struct netent_data" must be initialized to .SM NULL before it is passed to either .CR getnetent_r() or .CR setnetent_r() for the first time. Thereafter it should not be modified in any way. This is the only .I netent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getnetbyname() , .CR getnetbyaddr() , .CR getnetent() , and their reentrant counterparts, internally call the name service switch to access the "networks" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve network names and addresses. .SH RETURN VALUE .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() return a null pointer (0) on .SM EOF or when they are unable to open .CR /etc/networks . .CR getnetbyaddr() also returns a null pointer if its .I type parameter is invalid. .PP .CR getnetent_r() , .CR getnetbyname_r() , .CR getnetbyaddr_r() , .CR setnetent_r() , and .CR endnetent_r() return a -1 if the operation is unsuccessful or, in the case of .CR getnetent_r() , if the end of the networks list has been reached. A 0 is returned otherwise. .SH EXAMPLE The following code excerpt counts the number of network entries: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct netent netbuf; struct netent_data ndbuf; ndbuf.net_fp = NULL; (void) setnetent_r(0, &ndbuf); while (getnetent_r(&netbuf, &ndbuf) != -1) count++; (void) endnetent_r(&ndbuf); .ft .ps .fi .RE .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getnetent() , .CR getnetbyaddr() , .CR getnetbyname() , .CR setnetent() , and .CR endnetent() are unsafe in multi-thread applications. .CR getnetent_r() , .CR getnetbyaddr_r() , .CR getnetbyname_r() , .CR setnetent_r() , and .CR endnetent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getnetent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/networks .SH SEE ALSO ypserv(1M), networks(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getnetent() ": XPG4" .\" .\" index@\f4endnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyaddr()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyname()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4setnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1set network entry@@@\f3getnetent(3N)\f1 .\" index@\f1network entry, get or set@@@\f3getnetent(3N)\f1 .\" .\" toc@\f3getnetent(3N)\f1:\0\0\f4getnetent()\f1, \f4getnetbyaddr()\f1, \f4getnetbyname()\f1, \f4setnetent()\f1, \n\f4endnetent()\f1@@@get network entry .\" toc@\f4getnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" .\" links@getnetent.3n getnetbyadd.3n .\" links@getnetent.3n getnetbynam.3n .\" links@getnetent.3n setnetent.3n .\" links@getnetent.3n endnetent.3n .\" links@getnetent.3n getnetent_r.3n .\" links@getnetent.3n getnetbyaddr_r.3n .\" links@getnetent.3n getnetbyname_r.3n .\" links@getnetent.3n setnetent_r.3n .\" links@getnetent.3n endnetent_r.3n .\" .\" fileset_database@getnetent.3n INETSVCS-MAN .\" $Header: getnetent.3n,v 78.1 96/03/15 15:57:28 ssa Exp $ .TA g .TH getnetent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnetent(\|), getnetent_r(\|), getnetbyaddr(\|), getnetbyaddr_r(\|), getnetbyname(\|), getnetbyname_r(\|), setnetent(\|), setnetent_r(\|), endnetent(\|),endnetent_r(\|) \- get network entry .SH SYNOPSIS .nf .C #include .C #include .PP .C "struct netent *getnetent(void);" .PP .C "int getnetent_r(struct netent *result, struct netent_data *buffer);" .PP .C "struct netent *getnetbyname(const char *name);" .PP .C "int getnetbyname_r(" .PD 0 .IP .C "const char *name," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "struct netent *getnetbyaddr(int net, int type);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "struct netent *getnetbyaddr(in_addr_t net, int type);" .PP .C "int getnetbyaddr_r(" .PD 0 .IP .C "int net," .C "int type," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "int setnetent(int stayopen);" .PP .C "int setnetent_r(int stayopen, struct netent_data *buffer);" .PP .C "int endnetent(void);" .PP .C "int endnetent_r(struct netent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setnetent(int stayopen);" .C "void endnetent(void);" .fi .SH DESCRIPTION .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() each return a pointer to a structure of type .I netent containing the broken-out fields of a line in the network data base, .CR /etc/networks . .PP The members of this structure are: .RS .TP 15 .CR n_name The official name of the network. .TP .CR n_aliases A null-terminated list of alternate names for the network. .TP .CR n_addrtype The type of the network number returned; always AF_INET. .TP .CR n_net The network number. .RE .PP Functions behave as follows: .RS .TP 22 .CR getnetent() Reads the next line of the file, opening the file if necessary. .TP .CR setnetent() opens and rewinds the file. If the .I stayopen flag is non-zero, the network data base is not closed after each call to .CR getnetent() (either directly or indirectly through one of the other .CR getnet* calls). .TP .CR endnetent() Closes the file. .TP .CR getnetbyname() Sequentially searches from the beginning of the file until a network name (among either the official names or the aliases) matching its parameter .I name is found, or until .SM EOF is encountered. .TP .CR getnetbyaddr() Sequentially searches from the beginning of the file until a network number matching its parameter .I net is found, or until .SM EOF is encountered. The parameter .I net must be in network order. The parameter .I type must be the constant .CR AF_INET . Network numbers are supplied in host order (see .IR byteorder (3N)). .PP If the system is running Network Information Service .SM (NFS), .CR getnetbyname() and .CR getnetbyaddr() obtain their network information from the .SM NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getnetent_r() , .CR getnetbyname_r() and .CR getnetbyaddr_r() expect to be passed the address of a .I "struct netent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct netent_data" , must also be supplied. This structure is used to store data, to which fields in the .I "struct netent" will point, as well as state information such as open file descriptors. The .I "struct netent_data" is defined in the file .CR . .PP .CR setnetent_r() and .CR endnetent_r() are to be used only in conjunction with .CR getnetent_r() and take the same pointer to a .I "struct netent_data" as a parameter. If the Network Information Service is being used, .CR setnetent_r() initializes an internal database key. If the .B /etc/networks file is being used, .CR setnetent_r() opens or rewinds the file. .CR endnetent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setnetent_r() currently has no effect. However, .CR setnetent() can still be used to keep the .B /etc/networks file open when making calls to .CR getnetbyaddr_r() and .CR getnetbyname_r() . .PP The .I net_fp field in the .I "struct netent_data" must be initialized to .SM NULL before it is passed to either .CR getnetent_r() or .CR setnetent_r() for the first time. Thereafter it should not be modified in any way. This is the only .I netent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getnetbyname() , .CR getnetbyaddr() , .CR getnetent() , and their reentrant counterparts, internally call the name service switch to access the "networks" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve network names and addresses. .SH RETURN VALUE .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() return a null pointer (0) on .SM EOF or when they are unable to open .CR /etc/networks . .CR getnetbyaddr() also returns a null pointer if its .I type parameter is invalid. .PP .CR getnetent_r() , .CR getnetbyname_r() , .CR getnetbyaddr_r() , .CR setnetent_r() , and .CR endnetent_r() return a -1 if the operation is unsuccessful or, in the case of .CR getnetent_r() , if the end of the networks list has been reached. A 0 is returned otherwise. .SH EXAMPLE The following code excerpt counts the number of network entries: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct netent netbuf; struct netent_data ndbuf; ndbuf.net_fp = NULL; (void) setnetent_r(0, &ndbuf); while (getnetent_r(&netbuf, &ndbuf) != -1) count++; (void) endnetent_r(&ndbuf); .ft .ps .fi .RE .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getnetent() , .CR getnetbyaddr() , .CR getnetbyname() , .CR setnetent() , and .CR endnetent() are unsafe in multi-thread applications. .CR getnetent_r() , .CR getnetbyaddr_r() , .CR getnetbyname_r() , .CR setnetent_r() , and .CR endnetent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getnetent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/networks .SH SEE ALSO ypserv(1M), networks(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getnetent() ": XPG4" .\" .\" index@\f4endnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyaddr()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyname()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4setnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1set network entry@@@\f3getnetent(3N)\f1 .\" index@\f1network entry, get or set@@@\f3getnetent(3N)\f1 .\" .\" toc@\f3getnetent(3N)\f1:\0\0\f4getnetent()\f1, \f4getnetbyaddr()\f1, \f4getnetbyname()\f1, \f4setnetent()\f1, \n\f4endnetent()\f1@@@get network entry .\" toc@\f4getnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" .\" links@getnetent.3n getnetbyadd.3n .\" links@getnetent.3n getnetbynam.3n .\" links@getnetent.3n setnetent.3n .\" links@getnetent.3n endnetent.3n .\" links@getnetent.3n getnetent_r.3n .\" links@getnetent.3n getnetbyaddr_r.3n .\" links@getnetent.3n getnetbyname_r.3n .\" links@getnetent.3n setnetent_r.3n .\" links@getnetent.3n endnetent_r.3n .\" .\" fileset_database@getnetent.3n INETSVCS-MAN .\" $Header: getnetent.3n,v 78.1 96/03/15 15:57:28 ssa Exp $ .TA g .TH getnetent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnetent(\|), getnetent_r(\|), getnetbyaddr(\|), getnetbyaddr_r(\|), getnetbyname(\|), getnetbyname_r(\|), setnetent(\|), setnetent_r(\|), endnetent(\|),endnetent_r(\|) \- get network entry .SH SYNOPSIS .nf .C #include .C #include .PP .C "struct netent *getnetent(void);" .PP .C "int getnetent_r(struct netent *result, struct netent_data *buffer);" .PP .C "struct netent *getnetbyname(const char *name);" .PP .C "int getnetbyname_r(" .PD 0 .IP .C "const char *name," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "struct netent *getnetbyaddr(int net, int type);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "struct netent *getnetbyaddr(in_addr_t net, int type);" .PP .C "int getnetbyaddr_r(" .PD 0 .IP .C "int net," .C "int type," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "int setnetent(int stayopen);" .PP .C "int setnetent_r(int stayopen, struct netent_data *buffer);" .PP .C "int endnetent(void);" .PP .C "int endnetent_r(struct netent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setnetent(int stayopen);" .C "void endnetent(void);" .fi .SH DESCRIPTION .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() each return a pointer to a structure of type .I netent containing the broken-out fields of a line in the network data base, .CR /etc/networks . .PP The members of this structure are: .RS .TP 15 .CR n_name The official name of the network. .TP .CR n_aliases A null-terminated list of alternate names for the network. .TP .CR n_addrtype The type of the network number returned; always AF_INET. .TP .CR n_net The network number. .RE .PP Functions behave as follows: .RS .TP 22 .CR getnetent() Reads the next line of the file, opening the file if necessary. .TP .CR setnetent() opens and rewinds the file. If the .I stayopen flag is non-zero, the network data base is not closed after each call to .CR getnetent() (either directly or indirectly through one of the other .CR getnet* calls). .TP .CR endnetent() Closes the file. .TP .CR getnetbyname() Sequentially searches from the beginning of the file until a network name (among either the official names or the aliases) matching its parameter .I name is found, or until .SM EOF is encountered. .TP .CR getnetbyaddr() Sequentially searches from the beginning of the file until a network number matching its parameter .I net is found, or until .SM EOF is encountered. The parameter .I net must be in network order. The parameter .I type must be the constant .CR AF_INET . Network numbers are supplied in host order (see .IR byteorder (3N)). .PP If the system is running Network Information Service .SM (NFS), .CR getnetbyname() and .CR getnetbyaddr() obtain their network information from the .SM NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getnetent_r() , .CR getnetbyname_r() and .CR getnetbyaddr_r() expect to be passed the address of a .I "struct netent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct netent_data" , must also be supplied. This structure is used to store data, to which fields in the .I "struct netent" will point, as well as state information such as open file descriptors. The .I "struct netent_data" is defined in the file .CR . .PP .CR setnetent_r() and .CR endnetent_r() are to be used only in conjunction with .CR getnetent_r() and take the same pointer to a .I "struct netent_data" as a parameter. If the Network Information Service is being used, .CR setnetent_r() initializes an internal database key. If the .B /etc/networks file is being used, .CR setnetent_r() opens or rewinds the file. .CR endnetent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setnetent_r() currently has no effect. However, .CR setnetent() can still be used to keep the .B /etc/networks file open when making calls to .CR getnetbyaddr_r() and .CR getnetbyname_r() . .PP The .I net_fp field in the .I "struct netent_data" must be initialized to .SM NULL before it is passed to either .CR getnetent_r() or .CR setnetent_r() for the first time. Thereafter it should not be modified in any way. This is the only .I netent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getnetbyname() , .CR getnetbyaddr() , .CR getnetent() , and their reentrant counterparts, internally call the name service switch to access the "networks" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve network names and addresses. .SH RETURN VALUE .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() return a null pointer (0) on .SM EOF or when they are unable to open .CR /etc/networks . .CR getnetbyaddr() also returns a null pointer if its .I type parameter is invalid. .PP .CR getnetent_r() , .CR getnetbyname_r() , .CR getnetbyaddr_r() , .CR setnetent_r() , and .CR endnetent_r() return a -1 if the operation is unsuccessful or, in the case of .CR getnetent_r() , if the end of the networks list has been reached. A 0 is returned otherwise. .SH EXAMPLE The following code excerpt counts the number of network entries: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct netent netbuf; struct netent_data ndbuf; ndbuf.net_fp = NULL; (void) setnetent_r(0, &ndbuf); while (getnetent_r(&netbuf, &ndbuf) != -1) count++; (void) endnetent_r(&ndbuf); .ft .ps .fi .RE .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getnetent() , .CR getnetbyaddr() , .CR getnetbyname() , .CR setnetent() , and .CR endnetent() are unsafe in multi-thread applications. .CR getnetent_r() , .CR getnetbyaddr_r() , .CR getnetbyname_r() , .CR setnetent_r() , and .CR endnetent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getnetent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/networks .SH SEE ALSO ypserv(1M), networks(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getnetent() ": XPG4" .\" .\" index@\f4endnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyaddr()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyname()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4setnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1set network entry@@@\f3getnetent(3N)\f1 .\" index@\f1network entry, get or set@@@\f3getnetent(3N)\f1 .\" .\" toc@\f3getnetent(3N)\f1:\0\0\f4getnetent()\f1, \f4getnetbyaddr()\f1, \f4getnetbyname()\f1, \f4setnetent()\f1, \n\f4endnetent()\f1@@@get network entry .\" toc@\f4getnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" .\" links@getnetent.3n getnetbyadd.3n .\" links@getnetent.3n getnetbynam.3n .\" links@getnetent.3n setnetent.3n .\" links@getnetent.3n endnetent.3n .\" links@getnetent.3n getnetent_r.3n .\" links@getnetent.3n getnetbyaddr_r.3n .\" links@getnetent.3n getnetbyname_r.3n .\" links@getnetent.3n setnetent_r.3n .\" links@getnetent.3n endnetent_r.3n .\" .\" fileset_database@getnetent.3n INETSVCS-MAN .\" $Header: getnetgrent.3c,v 76.2 95/05/26 17:06:46 ssa Exp $ .TA g .TH getnetgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnetgrent(\|), setnetgrent(\|), endnetgrent(\|), innetgr(\|), getnetgrent_r(\|), setnetgrent_r(\|), endnetgrent_r(\|) \- get network group entry .SH SYNOPSIS .nf .C int innetgr( .C " char *netgroup, " .C " char *machine, " .C " char *user, " .C " char *domain" .C ); .PP .C int setnetgrent(char *netgroup); .PP .C int setnetgrent_r( .C " char *grp," .C " char **ngstate" .C ); .PP .C int endnetgrent(); .PP .C int endnetgrent_r( .C " char **ngstaste" .C ); .PP .C int getnetgrent( .C " char **machinep, " .C " char **userp, " .C " char **domainp" .C ); .PP .C int getnetgrent_r( .C " char **machinep," .C " char **namep," .C " char **domainp," .C " char **ngstate" .C ); .fi .SH DESCRIPTION .TP 20 .C innetgr() Returns 1 if .C netgroup contains the machine, user, and domain triple as a member. Otherwise, it returns 0. If .IR machine , .IR user , or .I domain is .SM NULL, .C innetgr interprets .SM NULL to mean, any machine, user, or domain respectively. Refer to .IR netgroup (4) for a description of .C netgroup membership criteria. .TP .C getnetgrent() Returns the next member of a network group. After the call, .I machinep contains a pointer to a string containing the name of the machine part of the network group member. Pointers .I userp and .I domainp behave in a manner similar to .IR machinep . If any of these pointers are returned with a .SM NULL value, they are interpreted as wild cards. .C getnetgrent() allocates space for the names. This space is released when an .C endnetgrent() call is made. .C getnetgrent() returns 1 if it succeeded in obtaining another network group member, 0 if it reached the end of the group. .TP .C setnetgrent() Establishes the network group from which .C getnetgrent() obtains members, and also restarts calls to .C getnetgrent() from the beginning of the list. If the previous .C setnetgrent() call was to a different network group, a .C endnetgrent() call is implied. .TP .C endnetgrent() Frees the space allocated during .C getnetgrent() calls. .PD .PP If the system is running the Network Information Service (NIS) services, .CR setnetgrent() gets the netgroup information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getnetgrent_r(), .CR setnetgrent_r(), and .CR endnetgrent_r(), expect to be passed a pointer of .CR "char **ngstate" that will store the result of the lookup at the supplied location. This structure is used to store data, which the other reentrant (_r) routines use. .PP .CR setnetgrent_r() and .CR endnetgrent_r() are to be used only in conjunction with .CR getnetgrent_r() and take the same pointer to a char **ngstate as a parameter. .PP The .I **ngstate pointer must be initialized to NULL before it is passed to .CR setnetgrent_r() for the first time. Thereafter is should not be modified in any way. .SS Name Service Switch-Based Operation The library routine, .CR innetgr() , setnetgrent() , and setnetgrent_r(), internally call the name service switch to access the "netgroup" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve netgroup lookups. .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getnetgrent() , .CR setnetgrent() , and .CR endnetgrent() are unsafe in multi-thread applications. .CR getnetgrent_r() , .CR setnetgrent_r() , and .CR endnetgrent_r() are MT-Safe and should be used instead. .SH AUTHOR .C getnetgrent() was developed by Sun Microsystems, Inc. .SH FILES .C /etc/netgroup .C /etc/nsswitch.conf .SH SEE ALSO netgroup(4), switch(4). .\" .\" index@\f4getnetgrent()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@\f4endnetgrent()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@\f4innetgr()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@\f4setnetgrent()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@set network group entry@@@\f3getnetgrent(3C)\f1 .\" index@network group entry, get or set@@@\f3getnetgrent(3C)\f1 .\" index@group entry, network, get or set@@@\f3getnetgrent(3C)\f1 .\" index@entry, network group, get or set@@@\f3getnetgrent(3C)\f1 .\" .\" toc@\f3getnetgrent(3C)\f1: \f4getnetgrent()\fP, \f4setnetgrent()\fP, \f4endnetgrent()\fP, \f4innetgr()\fP@@@get network group entry .\" .\" links@getnetgrent.3c setnetgrent.3c .\" links@getnetgrent.3c endnetgrent.3c .\" links@getnetgrent.3c innetgr.3c .\" .\" fileset_database@getnetgrent.3c PROGRAMING-MAN .\" $Header: secure_rpc.3c,v 74.1 95/05/10 21:12:12 ssa Exp $ .TA s .TH secure_rpc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME secure_rpc(), authdes_create(), authdes_getucred(), get_myaddress(), getnetname(), host2netname(), key_decryptsession(), key_encryptsession(), key_gendes(), key_setsecret(), netname2host(), netname2user(), user2netname() \- library routines for secure remote procedure calls .SH DESCRIPTION .LP .C RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .LP .C RPC allows various authentication flavors. The .B authdes_getucred() and .B authdes_create() routines implement the .B DES authentication flavor. See .BR rpc_clnt_auth (3C) for routines relating to the .B AUTH_NONE and .B AUTH_UNIX authentication types. .IP Note: Both the client and server should have their keys in the .BR publickey (5) database. Also, the keyserver daemon .BR keyserv (1M) must be running on both the client and server hosts for the .B DES authentication system to work. .SS Routines .LP The following routines require that the header .BR be included. .PP The .B AUTH data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "AUTH *" .C "authdes_create(netname, window, syncaddr, deskeyp)" .C "char *netname;" .C "unsigned window;" .C "struct sockaddr_in *syncaddr;" .C "des_block *deskeyp;" .fi .IP .B authdes_create() is an interface to the .B RPC secure authentication system, known as .B DES authentication. .IP Used on the client side, .B authdes_create() returns an authentication handle that enables the use of the secure authentication system. The first parameter .I netname is the network name of the owner of the server process. This field usually represents a .I host derived from the utility routine .BR host2netname() , but could also represent a user name using .BR user2netname() . The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third parameter .I syncaddr is optional. If it is .B NULL, then the authentication system will assume that the local clock is always in sync with the server's clock, and will not attempt to synchronize with the server. If an address is supplied then the system will use it for consulting the remote time service whenever resynchronization is required. This parameter is usually the address of the .B RPC server itself. The final parameter .I deskeyp is also optional. If it is .B NULL, then the authentication system will generate a random .B DES key to be used for the encryption of credentials. If .I deskeyp is supplied then it is used instead. .PP .nf .C "int" .C "authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)" .C "struct authdes_cred *adc;" .C "short *uidp, *gidp, *gidlenp;" .C "int *gidlistp;" .fi .IP .BR authdes_getucred() , is a .B DES authentication routine used by the server for converting a .B DES credential, which is operating system independent, into a .B UNIX credential. .I uidp points to the user .B ID of the user associated with .IR adc ; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. .br .ne 5 .IP This routine differs from the utility routine .B netname2user() in that .B authdes_getucred() pulls its information from a cache, and does not have to do a .B NIS name service lookup every time it is called to get its information. Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "void" .C "get_myaddress(addr)" .C "struct sockaddr_in *addr;" .fi .IP Return the machine's .B IP address in .IR addr. The port number is always set to .BR htons(PMAPPORT) . .PP .nf .C "int" .C "getnetname(netname)" .C "char netname[MAXNETNAMELEN];" .fi .IP Return the unique, operating-system independent netname of the caller in the fixed-length array .IR netname . Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "int" .C "host2netname(netname, host, domain)" .C "char netname[MAXNETNAMELEN];" .C "char *host;" .C "char *domain;" .fi .IP Convert from a domain-specific hostname to an operating-system independent netname. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . This routine should be used if the owner of the server process is the machine that is, the user with effective user .B ID zero. Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2host() . .PP .nf .C "int" .C "key_decryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP An interface routine to the keyserver daemon, which is associated with .B RPC's secure authentication system ( .B DES authentication). User programs rarely need to call it, or its associated routines .BR key_encryptsession() , .B key_gendes() and .BR key_setsecret() . System commands such as .B login and the .B RPC library are the main clients of these four routines. .IP .B key_decryptsession() takes the netname of a server and a .B DES key, and decrypts the key by using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_encryptsession() . .PP .nf .C "int" .C "key_encryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It takes the netname of the server and a .B DES key, and encrypts it using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_decryptsession() . .PP .nf .C "int" .C "key_gendes(deskeyp)" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It is used to ask the keyserver for a secure conversation key. Choosing one at random is usually not good enough, because the common ways of choosing random numbers, such as using the current time, are very easy to guess. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "key_setsecret(keyp)" .C "char *keyp;" .fi .IP A keyserver interface routine. It is used to set the secret key for the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "netname2host(netname, host, hostlen)" .C "char *netname;" .C "char *host;" .C "int hostlen;" .fi .IP Convert an operating-system independent netname to a domain-specific hostname. .I hostlen specifies the size of the array pointed to by .I host. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR host2netname() . .PP .nf .C "int" .C "netname2user(netname, uidp, gidp, gidlenp, gidlistp)" .C "char *netname;" .C "int *uidp, *gidp, *gidlenp, *gidlistp;" .fi .IP Convert an operating-system independent netname to a domain-specific user .B ID. .I uidp points to the user .B ID of the user; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR user2netname() . .PP .nf .C "int" .C "user2netname(netname, uid, domain)" .C "char netname[MAXNETNAMELEN];" .C "int uid;" .C "char *domain;" .fi .IP Convert a domain-specific username to an operating-system independent netname. .I uid is the user .B ID of the owner of the server process. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2user() . .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR login (1), .BR chkey (1), .BR rpc (3C), .BR rpc_clnt_auth (3C), .BR publickey (4), .BR keyserv (1M), .BR newkey (1M) .\" toc@\f3secure_rpc(3C)\f1:\0\0\f4authdes_create()\fP, \f4authdes_getucred()\fP, \f4get_myaddress()\fP, \n\f4getnetaddress()\fP, \f4getnetname()\fP, \f4host2netname()\fP, \n\f4key_decryptsession()\fP, \f4key_encryptsession()\fP, \f4key_gendes()\fP, \n\f4key_setsecret()\fP, \f4netname2host()\fP, \f4netname2user()\fP, \n\f4user2netname()\fP@@@library routines for secure remote procedure calls .\" toc@\f4secure_rpc()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_create()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_getucred()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4get_myaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4host2netname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_decryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_encryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_gendes()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_setsecret()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2host()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2user()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4user2netname()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" index@library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4secure_rpc()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_create()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_getucred()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4get_myaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4host2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_decryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_encryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_gendes()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_setsecret()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2host()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2user()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4user2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" links@secure_rpc.3c authdes_create.3c .\" links@secure_rpc.3c authdes_getucred.3c .\" links@secure_rpc.3c get_myaddress.3c .\" links@secure_rpc.3c getnetaddress.3c .\" links@secure_rpc.3c getnetname.3c .\" links@secure_rpc.3c host2netname.3c .\" links@secure_rpc.3c key_decryptsession.3c .\" links@secure_rpc.3c key_encryptsession.3c .\" links@secure_rpc.3c key_gendes.3c .\" links@secure_rpc.3c key_setsecret.3c .\" links@secure_rpc.3c netname2host.3c .\" links@secure_rpc.3c netname2user.3c .\" links@secure_rpc.3c user2netname.3c .\" $Header: getnstr.3x,v 76.2 95/08/01 10:57:27 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnstr, mvgetnstr, mvwgetnstr, wgetnstr, \(em get a multi-byte character length limited string from the terminal .SH SYNOPSIS .C "#include " .P .C "int getnstr(char *\f2str\fP, int \f2n\fP);" .P .C "int mvgetnstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvwgetnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int wgetnstr(WINDOW *\f2win\fP, char *\f2str\fP, int \f2n\fP);" .SH DESCRIPTION The effect of .Fn getnstr and .Fn wgetnstr is as though a series of calls to .Fn getch were made, until a newline or carriage return is received. The resulting value is placed in the area pointed to by \f2str\f1. The .Fn getnstr and .Fn wgetnstr functions read at most \f2n\f1 bytes, thus preventing a possible overflow of the input buffer. The user's erase and kill characters are interpreted, as well as any special keys (such as function keys, home key, clear key, and so on). .P The .Fn mvgetnstr function is identical to .Fn getnstr except that it is as though it is a call to .Fn move and then a series of calls to .CR getch() . The .Fn mvwgetnstr function is identical to .Fn getnstr except it is as though a call to .Fn wmove is made and then a series of calls to .CR wgetch() . .P The .CR getnstr() , .CR wgetnstr() , .Fn mvgetnstr and .Fn mvwgetnstr functions will only return the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character, the functions fill the array with complete characters. If the array is not large enough to contain any complete characters, the function fails. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" .P Traditional implementations often limited the number of bytes returned to 256. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, beep(), getch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getnstr(3X)\f1:\0\0\f4getnstr()\f1, \f4mvgetnstr()\f1, \f4mvwgetnstr()\f1, \f4wgetnstr()\f1\n@@@get a multi-byte character length limited string from the terminal .\" toc@\f4mvgetnstr()\f1: get a multi-byte character length limited string from the terminal@@@see \f3getnstr(3X)\f1 .\" toc@\f4mvwgetnstr()\f1: get a multi-byte character length limited string from the terminal@@@see \f3getnstr(3X)\f1 .\" toc@\f4wgetnstr()\f1: get a multi-byte character length limited string from the terminal@@@see \f3getnstr(3X)\f1 .\" .\" index@\f4getnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f4mvgetnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f4mvwgetnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f4wgetnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1multi-byte character length limited string, get from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1terminal, get a multi-byte character length limited string from@@@\f3getnstr(3X)\f1 .\" index@\f1character, get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1string, get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" .\" links@getnstr.3x mvgetnstr.3x .\" links@getnstr.3x mvwgetnstr.3x .\" links@getnstr.3x wgetnstr.3x .\" .\" fileset_database@getnstr.3x CURS-ENG-A-MAN .\" $Header: getopt.3c,v 72.6 94/12/08 12:12:50 ssa Exp $ .TA g .TH getopt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getopt(\|), optarg, optind, opterr \- get option letter from argument vector .SH SYNOPSIS .C "#include " .PP .C "int getopt(int argc, char * const argv[], const char *optstring);" .PP .C "extern char *optarg;" .PP .C "extern int optind, opterr, optopt;" .SH DESCRIPTION .C getopt() returns the next option letter in .I argv (starting from .IR argv [\|1\|]) that matches a letter in .IR optstring . .I argc and .I argv are the argument count and argument array as passed to .IR main (). .I optstring is a string of recognized option characters; if a character is followed by a colon, the option takes an argument which may or may not be separated from it by white space. .PP .C optind is the index of the next element of the .IR argv [\|] vector to be processed. It is initialized to 1 by the system, and .C getopt() updates it when it finishes with each element of .IR argv []. .PP .C getopt() returns the next option character from .I argv that matches a character in .IR optstring , if there is one that matches. If the option takes an argument, .C getopt() sets the variable .C optarg to point to the option-argument as follows: .RS .TP 3 \(bu If the option was the last character in the string pointed to by an element of .IR argv , then .C optarg contains the next element of .IR argv , and .C optind is incremented by 2. If the resulting value of .C optind is greater than or equal to .IR argc , this indicates a missing option argument, and .C getopt() returns an error indication. .TP \(bu Otherwise, .C optarg points to the string following the option character in that element of .IR argv , and .C optind is incremented by 1. .RE .PP If, when .C getopt() is called, .IR argv [ \|optind\| ] is .SM NULL, or the string pointed to by .IR argv [ \|optind\| ] either does not begin with the character .C - or consists only of the character .CR - , .C getopt() returns \(mi1 without changing .IR optind . If .IR argv [ \|optind\| ] points to the string .CR -\|- , .C getopt() returns \(mi1 after incrementing .IR optind . .PP If .C getopt() encounters an option character that is not contained in .IR optstring , it returns the question-mark .RC ( ? ) character. If it detects a missing option argument, it returns the colon character .RC ( : ) if the first character of .I optstring was a colon, or a question-mark character otherwise. In either case, .C getopt() sets the variable .I optopt to the option character that caused the error. If the application has not set the variable .C opterr to zero and the first character of .I optstring is not a colon, .C getopt() also prints a diagnostic message to standard error. .PP The special option .C -\|- can be used to delimit the end of the options; \(mi1 is returned, and .C -\|- is skipped. .SH RETURN VALUE .C getopt() returns the next option character specified on the command line. A colon .RC ( : ) is returned if .C getopt() detects a missing argument and the first character of .I optstring was a colon .RC ( : ). .PP A question-mark .RC ( ? ) is returned if .C getopt() encounters an option character not in .I optstring or detects a missing argument and the first character of .I optstring was not a colon .RC ( : ). .PP Otherwise, .C getopt() returns \(mi1 when all command line options have been parsed. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of option letters as single and/or multi-byte characters. .SS International Code Set Support Single- and multibyte character code sets are supported. .SH ERRORS .CR getopt() fails under the following conditions: .TP 15 [EILSEQ] An invalid multibyte character sequence was encountered during option processing. .SH EXAMPLES The following code fragment shows to process arguments for a command that can take the mutually exclusive options .C a and .CR b , and the options .C f and .CR o , both of which require arguments: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 #include #include main (int argc, char *argv[]) { int c; int bflg, aflg, errflg; extern char *optarg; extern int optind, optopt; \&\f3.\fP \&\f3.\fP \&\f3.\fP while ((c = getopt(argc, argv, ":abf:o:")) != -1) switch (c) { case \'a\': if (bflg) errflg++; else aflg++; break; case \'b\': if (aflg) errflg++; else { bflg++; bproc( ); } break; case \'f\': ifile = optarg; break; case \'o\': ofile = optarg; break; case \':\': /* -f or -o without arguments */ fprintf(stderr, "Option -%c requires an argument\\n", optopt); errflg++; break; case \'?\': fprintf(stderr, "Unrecognized option: - %c\\n", optopt); errflg++; } if (errflg) { fprintf(stderr, "usage: . . . "); exit (2); } for ( ; optind < argc; optind++) { if (access(argv[optind], 4)) { \&\f3.\fP \&\f3.\fP \&\f3.\fP } .ft .ps .fi .RE .SH WARNINGS .PP Options can be any .SM ASCII characters except colon .RC ( : ), question mark .RC ( ? ), or null .RC ( \e0 ). It is impossible to distinguish between a .C ? used as a legal option, and the character that .C getopt() returns when it encounters an invalid option character in the input. .PP .C getopt() is unsafe in multi-thread applications. .SH SEE ALSO getopt(1). .SH STANDARDS CONFORMANCE .CR getopt() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR optarg ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR opterr ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR optind ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR optopt ": AES, SVID3, XPG4, POSIX.2" .\" .\" index@\f4getopt()\f1, \f4optarg\f1, \f4optind\f1, \f4opterr\f1 \- get option letter from argument vector@@@\f3getopt(3C)\f1 .\" index@\f4optarg\f1, \f4optind\f1, \f4opterr\f1 \- get option letter from argument vector@@@\f3getopt(3C)\f1 .\" index@get: option letter from argument vector@@@\f3getopt(3C)\f1 .\" index@option letter from argument vector, get@@@\f3getopt(3C)\f1 .\" index@argument vector, get option letter from@@@\f3getopt(3C)\f1 .\" index@vector, get option letter from argument@@@\f3getopt(3C)\f1 .\" .\" toc@\f3getopt(3C)\f1:\0\0\f4getopt()\f1, \f4optarg\f1, \f4optind\f1, \f4opterr\f1@@@get option letter from argument vector .\" toc@\f4optarg\f1:\0\0get option letter from argument vector@@@see \f3getopt(3C)\f1 .\" toc@\f4optind\f1:\0\0get option letter from argument vector@@@see \f3getopt(3C)\f1 .\" toc@\f4opterr\f1:\0\0get option letter from argument vector@@@see \f3getopt(3C)\f1 .\" .\" links@getopt.3c optarg.3c .\" links@getopt.3c optind.3c .\" links@getopt.3c opterr.3c .\" $Header: getbegyx.3x,v 76.2 95/08/01 10:43:31 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getbegyx 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getbegyx, getmaxyx, getparyx \(em get additional cursor and window coordinates .SH SYNOPSIS .C "#include " .P .C "void getbegyx(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "void getmaxyx(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "void getparyx(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .SH DESCRIPTION .P The .Fn getbegyx macro stores the absolute screen coordinates of the specified window's origin in \f2y\f1 and \f2x\f1. .P The .Fn getmaxyx macro stores the number of rows of the specified window in \f2y\f1 and stores the window's number of columns in \f2x\f1. .P The .Fn getparyx macro, if the specified window is a subwindow, stores in \f2y\f1 and \f2x\f1 the coordinates of the window's origin relative to its parent window. Otherwise, \(mi1 is stored in \f2y\f1 and \f2x\f1. .SH "RETURN VALUE" No return values are defined. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These interfaces are macros and `\f4&\f1' cannot be used before the \f2y\f1 and \f2x\f1 arguments. .SH "SEE ALSO" getyx(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getbegyx(3X)\f1:\0\0\f4getbegyx()\f1, \f4getmaxyx()\f1, \f4getparyx()\f1@@@get additional cursor and window coordinates .\" toc@\f4getmaxyx()\f1: get additional cursor and window coordinates@@@see \f3getbegyx(3X)\f1 .\" toc@\f4getparyx()\f1: get additional cursor and window coordinates@@@see \f3getbegyx(3X)\f1 .\" .\" index@\f4getbegyx()\f1 \- get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f4getmaxyx()\f1 \- get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f4getparyx()\f1 \- get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f1get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f1coordinates, get additional cursor and window coordinates@@@\f3getbegyx(3X)\f1 .\" index@\f1additional cursor and window coordinates, get @@@\f3getbegyx(3X)\f1 .\" index@\f1cursor and window coordinates, get additional@@@\f3getbegyx(3X)\f1 .\" index@\f1window and cursor coordinates, get additional@@@\f3getbegyx(3X)\f1 .\" .\" links@getbegyx.3x getmaxyx.3x .\" links@getbegyx.3x getparyx.3x .\" .\" fileset_database@getbegyx.3x CURS-ENG-A-MAN .\" $Header: getpass.3c,v 72.5 94/11/14 15:28:55 ssa Exp $ .TA g .TH getpass 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpass(\|) \- read a password .SH SYNOPSIS .C "#include " .PP .C "char *getpass(const char *prompt);" .SH DESCRIPTION .CR getpass() reads up to a newline or .SM EOF from the file .CR /dev/tty , after prompting on the standard error output with the null-terminated string .I prompt and disabling echoing. A pointer is returned to a null-terminated string of at most 8 characters. If .CR /dev/tty cannot be opened, a .SM NULL pointer is returned. An interrupt terminates input and sends an interrupt signal to the calling program before returning. .SH WARNINGS The above routine uses .RC < stdio.h >, which causes it to increase, more than might be expected, the size of programs not otherwise using standard .SM I/O. .PP The return value points to static data whose content is overwritten by each call. .PP .CR getpass() is unsafe in multi-thread applications. .SH FILES .CR /dev/tty .SH SEE ALSO crypt(3C). .SH STANDARDS CONFORMANCE .CR getpass() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4getpass()\fP \- read a password from terminal while suppressing echo@@@\f3getpass(3C)\f1 .\" index@read password from terminal while suppressing echo@@@\f3getpass(3C)\f1 .\" index@password, read from terminal while suppressing echo@@@\f3getpass(3C)\f1 .\" index@terminal, read password from while suppressing echo@@@\f3getpass(3C)\f1 .\" index@echo, suppress while reading password from terminal@@@\f3getpass(3C)\f1 .\" index@suppress echo while reading password from terminal@@@\f3getpass(3C)\f1 .\" .\" toc@\f3getpass(3C)\f1:\0\0\f4getpass()\fP@@@read a password .\" $Header: getprdfent.3,v 72.3 94/07/05 18:07:26 ssa Exp $ .TA g .TH getprdfent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprdfent, getprdfnam, setprdfent, endprdfent, putprdfnam \- manipulate system default database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct pr_default \(**getprdfent(void);" .PP .CR "struct pr_default \(**getprdfnam(const char \(**name);" .PP .CR "void setprdfent(void);" .PP .CR "void endprdfent(void);" .PP .CR "int putprdfnam(const char \(**name, struct pr_default \(**pr);" .fi .SH DESCRIPTION .I getprdfent and .I getprdfnam each returns a pointer to an object with the following structure containing the broken-out fields of a line in the system default database. Each line in the database contains a .I pr_default structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v struct system_default_fields { time_t fd_inactivity_timeout ; char fd_boot_authenticate ; } ; struct system_default_flags { unsigned short fg_inactivity_timeout:1, fg_boot_authenticate:1, } ; struct pr_default { char dd_name[20] ; char dg_name ; struct pr_field prd ; struct pr_flag prg ; struct t_field tcd ; struct t_flag tcg ; struct dev_field devd ; struct dev_flag devg ; struct system_default_fields sfld ; struct system_default_flags sflg ; } ; .fi .RE .PP Currently there is only one entry in the system default database, referenced by name .BR default . .PP The System Default database contains default values for all parameters in the Protected Password, Terminal Control, and Device Assignment databases, as well as configurable system-wide parameters. The fields from the other databases are described in the corresponding manual entries. .I fd_inactivity_timeout is the number of seconds until a session is terminated on trusted systems. .PP .I fd_boot_authenticate is a boolean flag that indicates whether an authorized user must authenticate before the system begins operation. .PP .I getprdfent returns a pointer to the first .I pr_default structure in the database when first called. Thereafter, it returns a pointer to the next .I pr_default structure in the database, so that successive calls can be used to search the database (not currently supported). .PP .I getprdfnam searches from the beginning of the file until a default entry matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a .SM .B NULL pointer. Currently, all programs access the default database by calling .I getprdfnam ("default"). .PP A call to .I setprdfent has the effect of rewinding the default control file to allow repeated searches. .I endprdfent can be called to close the database when processing is complete. .PP .I putprdfnam puts a new or replaced default control entry .I pr with key .I name into the database. If the .I prg.fd_name field is 0, the requested entry is deleted from the system default database. .I putprdfnam locks the database for all update operations, and performs an .I endprdfent after the update or failed attempt. .SH RETURN VALUE .I getprdfent and .I getprdfnam return .SM .B NULL pointers on .SM EOF or error. .I putprdfnam returns 0 if it cannot add or update the entry. .SH WARNINGS Do not delete the system default entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 45 .C /tcb/files/auth/system/default System Defaults database .SH SEE ALSO authcap(4), default(4), getprpwent(3), getprtcent(3), getdvagent(3). .SH NOTES The value returned by .I getprdfent and .I getprdfnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .IR putprdfnam . .PP Programs using these routines must be compiled with .BR \-lsec . .\" .\" index@\f4getprdfent\f1 \- manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f4getprdfnam\f1 \- manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f4setprdfent\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" index@\f4endprdfent\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" .\" index@\f4putprdfnam\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" index@\f1manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f1manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f1system default database entry, manipulate@@@\f3getprdfent(3)\f1 .\" index@\f1default database entry, manipulate system@@@\f3getprdfent(3)\f1 .\" index@\f1database entry, manipulate system default@@@\f3getprdfent(3)\f1 .\" index@\f1entry, manipulate system default database@@@\f3getprdfent(3)\f1 .\" .\" toc@\f3getprdfent(3)\f1:\0\0\f4getprdfent\f1, \f4getprdfnam\f1, \f4setprdfent\f1, \f4endprdfent\f1,\n\f4putprdfnam\f1@@@manipulate system default database entry for a trusted system .\" toc@\f4getprdfnam\f1:\0\0search for file@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4setprdfent\f1:\0\0rewind default control files@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4endprdfent\f1:\0\0close system default database@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4putprdfnam\f1:\0\0put default control entry@@@\f1see \f3getprdfent(3)\f1 .\" .\" links@getprdfent.3 getprdfnam.3 .\" links@getprdfent.3 setprdfent.3 .\" links@getprdfent.3 endprdfent.3 .\" links@getprdfent.3 putprdfnam.3 .\" .\" fileset_database@getprdfent.3 UX-CORE-MAN .\" $Header: getprdfent.3,v 72.3 94/07/05 18:07:26 ssa Exp $ .TA g .TH getprdfent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprdfent, getprdfnam, setprdfent, endprdfent, putprdfnam \- manipulate system default database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct pr_default \(**getprdfent(void);" .PP .CR "struct pr_default \(**getprdfnam(const char \(**name);" .PP .CR "void setprdfent(void);" .PP .CR "void endprdfent(void);" .PP .CR "int putprdfnam(const char \(**name, struct pr_default \(**pr);" .fi .SH DESCRIPTION .I getprdfent and .I getprdfnam each returns a pointer to an object with the following structure containing the broken-out fields of a line in the system default database. Each line in the database contains a .I pr_default structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v struct system_default_fields { time_t fd_inactivity_timeout ; char fd_boot_authenticate ; } ; struct system_default_flags { unsigned short fg_inactivity_timeout:1, fg_boot_authenticate:1, } ; struct pr_default { char dd_name[20] ; char dg_name ; struct pr_field prd ; struct pr_flag prg ; struct t_field tcd ; struct t_flag tcg ; struct dev_field devd ; struct dev_flag devg ; struct system_default_fields sfld ; struct system_default_flags sflg ; } ; .fi .RE .PP Currently there is only one entry in the system default database, referenced by name .BR default . .PP The System Default database contains default values for all parameters in the Protected Password, Terminal Control, and Device Assignment databases, as well as configurable system-wide parameters. The fields from the other databases are described in the corresponding manual entries. .I fd_inactivity_timeout is the number of seconds until a session is terminated on trusted systems. .PP .I fd_boot_authenticate is a boolean flag that indicates whether an authorized user must authenticate before the system begins operation. .PP .I getprdfent returns a pointer to the first .I pr_default structure in the database when first called. Thereafter, it returns a pointer to the next .I pr_default structure in the database, so that successive calls can be used to search the database (not currently supported). .PP .I getprdfnam searches from the beginning of the file until a default entry matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a .SM .B NULL pointer. Currently, all programs access the default database by calling .I getprdfnam ("default"). .PP A call to .I setprdfent has the effect of rewinding the default control file to allow repeated searches. .I endprdfent can be called to close the database when processing is complete. .PP .I putprdfnam puts a new or replaced default control entry .I pr with key .I name into the database. If the .I prg.fd_name field is 0, the requested entry is deleted from the system default database. .I putprdfnam locks the database for all update operations, and performs an .I endprdfent after the update or failed attempt. .SH RETURN VALUE .I getprdfent and .I getprdfnam return .SM .B NULL pointers on .SM EOF or error. .I putprdfnam returns 0 if it cannot add or update the entry. .SH WARNINGS Do not delete the system default entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 45 .C /tcb/files/auth/system/default System Defaults database .SH SEE ALSO authcap(4), default(4), getprpwent(3), getprtcent(3), getdvagent(3). .SH NOTES The value returned by .I getprdfent and .I getprdfnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .IR putprdfnam . .PP Programs using these routines must be compiled with .BR \-lsec . .\" .\" index@\f4getprdfent\f1 \- manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f4getprdfnam\f1 \- manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f4setprdfent\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" index@\f4endprdfent\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" .\" index@\f4putprdfnam\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" index@\f1manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f1manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f1system default database entry, manipulate@@@\f3getprdfent(3)\f1 .\" index@\f1default database entry, manipulate system@@@\f3getprdfent(3)\f1 .\" index@\f1database entry, manipulate system default@@@\f3getprdfent(3)\f1 .\" index@\f1entry, manipulate system default database@@@\f3getprdfent(3)\f1 .\" .\" toc@\f3getprdfent(3)\f1:\0\0\f4getprdfent\f1, \f4getprdfnam\f1, \f4setprdfent\f1, \f4endprdfent\f1,\n\f4putprdfnam\f1@@@manipulate system default database entry for a trusted system .\" toc@\f4getprdfnam\f1:\0\0search for file@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4setprdfent\f1:\0\0rewind default control files@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4endprdfent\f1:\0\0close system default database@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4putprdfnam\f1:\0\0put default control entry@@@\f1see \f3getprdfent(3)\f1 .\" .\" links@getprdfent.3 getprdfnam.3 .\" links@getprdfent.3 setprdfent.3 .\" links@getprdfent.3 endprdfent.3 .\" links@getprdfent.3 putprdfnam.3 .\" .\" fileset_database@getprdfent.3 UX-CORE-MAN .\" $Header: getprotoent.3n,v 78.1 96/03/17 09:48:20 ssa Exp $ .TA g .TH getprotoent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprotoent(), getprotoent_r(), getprotobynumber(), getprotobynumber_r(), getprotobyname(), getprotobyname_r(), setprotoent(), setprotoent_r(), endprotoent(), endprotoent_r() \- get protocol entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct protoent *getprotoent(void);" .PP .C "int getprotoent_r(struct protoent *result," .C " struct protoent_data *buffer);" .PP .C "struct protoent *getprotobyname(const char *name);" .PP .C "int getprotobyname_r(const char *name," .C " struct protoent *result," .C " struct protoent_data *buffer);" .PP .C "struct protoent *getprotobynumber(int proto);" .PP .C "int getprotobynumber_r(int proto," .C " struct protoent *result," .C " struct protoent_data *buffer);" .PP .C "int setprotoent(int stayopen);" .PP .C "int setprotoent_r(int stayopen, struct protoent_data *buffer);" .PP .C "int endprotoent(void);" .PP .C "int endprotoent_r(struct protoent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setprotoent(int stayopen);" .C "void endprotoent(void);" .fi .SH DESCRIPTION The .CR getprotoent() , .CR getprotobyname() , and .CR getprotobynumber() functions each return a pointer to a structure of type .I protoent containing the broken-out fields of a line in the network protocol data base, .CR /etc/protocols . .PP The members of this structure are: .RS .TP 15 .CR p_name The official name of the protocol. .TP .CR p_aliases A null-terminated list of alternate names for the protocol. .TP .CR p_proto The protocol number. .RE .PP Functions behave as follows: .RS .TP 26 .CR getprotoent() Reads the next line of the file, opening the file if necessary. .TP .CR setprotoent() Opens and rewinds the file. If the .I stayopen flag is non-zero, the protocol data base is not closed after each call to .CR getprotoent() (either directly or indirectly through one of the other .CR getproto* calls). .TP .CR endprotoent() Closes the file. .TP .CR getprotobyname() .PD 0 .TP .CR getprotobynumber() Each sequentially searches from the beginning of the file until a matching protocol name (among either the official names or the aliases) or protocol number is found, or until EOF is encountered. .PD .PP If the system is running the Network Information Service (NIS) services, .CR getprotobyname() and .CR getprotobynumber() get the protocol information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getprotoent_r() , .CR getprotobyname_r() , and .CR getprotobynumber_r() expect to be passed the address of a .CR "struct protoent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct protoent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct protoent" will point, as well as state information such as open file descriptors. The .CR "struct protoent_data" is defined in the file .CR . .PP .CR setprotoent_r() and .CR endprotoent_r() are to be used only in conjunction with .CR getprotoent_r() and take the same pointer to a .CR "struct protoent_data" as a parameter. If the Network Information Service is being used, .CR setprotoent_r() initializes an internal database key. If the .B /etc/protocols file is being used, .CR setprotoent_r() opens or rewinds the file. .CR endprotoent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setprotoent_r() currently has no effect. However, .CR setprotoent() can still be used to keep the .B /etc/protocols file open when making calls to .CR getprotobyname_r() and .CR getprotobynumber_r() . .PP The .I proto_fp field in the .CR "struct protoent_data" must be initialized to NULL before it is passed to either .CR getprotoent_r() or .CR setprotoent_r() for the first time. Thereafter it should not be modified in any way. This is the only .CR protoent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getprotobyname() , .CR getprotobynumber() , .CR getprotoent() , and their reentrant counterparts, internally call the name service switch to access the "protocols" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve protocol names and numbers. .SH RETURN VALUE .CR getprotoent() , .CR getprotobyname() , and .CR getprotobynumber() return a null pointer (0) on EOF or when they are unable to open .CR /etc/protocols . .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 will be returned if the operation is unsuccessful or, in the case of .CR getprotoent_r() , if the end of the protocols list has been reached. .CR 0 is returned otherwise. .SH EXAMPLES The following code excerpt counts the number of protocols entries: .RS .nf .PP .C "int count = 0;" .C "struct protoent protobuf;" .C "struct protoent_data pdbuf;" .PP .C "pdbuf.proto_fp = NULL;" .C "(void) setprotoent_r(0, &pdbuf);" .C "while (getprotoent_r(&protobuf, &pdbuf) != -1)" .C " count++;" .C "(void) endprotoent_r(&pdbuf);" .fi .RE .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getprotoent() , .CR getprotobynumber() , .CR getprotobyname() , .CR setprotoent() , and .CR endprotoent() are unsafe in multi-thread applications. .CR getprotoent_r() , .CR getprotobynumber_r() , .CR getprotobyname_r() , .CR setprotoent_r() , and .CR endprotoent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getprotoent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/protocols .SH SEE ALSO ypserv(1M), protocols(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getprotoent() ": XPG4" .\" .\" index@\f1end protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f1entry, get, set, or end protocol@@@\f3getprotoent(3N)\f1 .\" index@\f1get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f1protocol entry, get, set, or end@@@\f3getprotoent(3N)\f1 .\" index@\f1set protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f1thread-safe, get, set, or end protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4endprotoent()\f1 \- end protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4endprotoent_r()\f1 \- end protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobyname()\f1 \- get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobyname_r()\f1 \- get protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobynumber()\f1 \- get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobynumber_r()\f1 \- get protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotoent()\f1 \- get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotoent_r()\f1 \- get protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4setprotoent()\f1 \- set protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4setprotoent_r()\f1 \- set protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" .\" links@getprotoent.3n endprotoent.3n .\" links@getprotoent.3n getprotobyn.3n .\" links@getprotoent.3n setprotoent.3n .\" .\" toc@\f3getprotoent(3N)\f1:\0\0\f4endprotoent()\f1, \f4endprotoent_r()\f1, \f4getprotobyname()\f1, \f4getprotobyname_r()\f1,\n\f4getprotobynumber()\f1, \f4getprotobynumber_r()\f1, \f4getprotoent()\f1, \f4getprotoent_r()\f1,\n\f4setprotoent()\f1, \f4setprotoent_r()\f1,@@@get, set, or end protocol entry .\" .\" toc@\f4endprotoent()\f1:\0\0end protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4endprotoent_r()\f1:\0\0end protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobyname()\f1:\0\0get protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobyname_r()\f1:\0\0get protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobynumber()\f1:\0\0get protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobynumber_r()\f1:\0\0get protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotoent_r()\f1:\0\0get protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4setprotoent()\f1:\0\0set protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4setprotoent_r()\f1:\0\0set protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" $Header: getprotoent.3n,v 78.1 96/03/17 09:48:20 ssa Exp $ .TA g .TH getprotoent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprotoent(), getprotoent_r(), getprotobynumber(), getprotobynumber_r(), getprotobyname(), getprotobyname_r(), setprotoent(), setprotoent_r(), endprotoent(), endprotoent_r() \- get protocol entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct protoent *getprotoent(void);" .PP .C "int getprotoent_r(struct protoent *result," .C " struct protoent_data *buffer);" .PP .C "struct protoent *getprotobyname(const char *name);" .PP .C "int getprotobyname_r(const char *name," .C " struct protoent *result," .C " struct protoent_data *buffer);" .PP .C "struct protoent *getprotobynumber(int proto);" .PP .C "int getprotobynumber_r(int proto," .C " struct protoent *result," .C " struct protoent_data *buffer);" .PP .C "int setprotoent(int stayopen);" .PP .C "int setprotoent_r(int stayopen, struct protoent_data *buffer);" .PP .C "int endprotoent(void);" .PP .C "int endprotoent_r(struct protoent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setprotoent(int stayopen);" .C "void endprotoent(void);" .fi .SH DESCRIPTION The .CR getprotoent() , .CR getprotobyname() , and .CR getprotobynumber() functions each return a pointer to a structure of type .I protoent containing the broken-out fields of a line in the network protocol data base, .CR /etc/protocols . .PP The members of this structure are: .RS .TP 15 .CR p_name The official name of the protocol. .TP .CR p_aliases A null-terminated list of alternate names for the protocol. .TP .CR p_proto The protocol number. .RE .PP Functions behave as follows: .RS .TP 26 .CR getprotoent() Reads the next line of the file, opening the file if necessary. .TP .CR setprotoent() Opens and rewinds the file. If the .I stayopen flag is non-zero, the protocol data base is not closed after each call to .CR getprotoent() (either directly or indirectly through one of the other .CR getproto* calls). .TP .CR endprotoent() Closes the file. .TP .CR getprotobyname() .PD 0 .TP .CR getprotobynumber() Each sequentially searches from the beginning of the file until a matching protocol name (among either the official names or the aliases) or protocol number is found, or until EOF is encountered. .PD .PP If the system is running the Network Information Service (NIS) services, .CR getprotobyname() and .CR getprotobynumber() get the protocol information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getprotoent_r() , .CR getprotobyname_r() , and .CR getprotobynumber_r() expect to be passed the address of a .CR "struct protoent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct protoent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct protoent" will point, as well as state information such as open file descriptors. The .CR "struct protoent_data" is defined in the file .CR . .PP .CR setprotoent_r() and .CR endprotoent_r() are to be used only in conjunction with .CR getprotoent_r() and take the same pointer to a .CR "struct protoent_data" as a parameter. If the Network Information Service is being used, .CR setprotoent_r() initializes an internal database key. If the .B /etc/protocols file is being used, .CR setprotoent_r() opens or rewinds the file. .CR endprotoent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setprotoent_r() currently has no effect. However, .CR setprotoent() can still be used to keep the .B /etc/protocols file open when making calls to .CR getprotobyname_r() and .CR getprotobynumber_r() . .PP The .I proto_fp field in the .CR "struct protoent_data" must be initialized to NULL before it is passed to either .CR getprotoent_r() or .CR setprotoent_r() for the first time. Thereafter it should not be modified in any way. This is the only .CR protoent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getprotobyname() , .CR getprotobynumber() , .CR getprotoent() , and their reentrant counterparts, internally call the name service switch to access the "protocols" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve protocol names and numbers. .SH RETURN VALUE .CR getprotoent() , .CR getprotobyname() , and .CR getprotobynumber() return a null pointer (0) on EOF or when they are unable to open .CR /etc/protocols . .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 will be returned if the operation is unsuccessful or, in the case of .CR getprotoent_r() , if the end of the protocols list has been reached. .CR 0 is returned otherwise. .SH EXAMPLES The following code excerpt counts the number of protocols entries: .RS .nf .PP .C "int count = 0;" .C "struct protoent protobuf;" .C "struct protoent_data pdbuf;" .PP .C "pdbuf.proto_fp = NULL;" .C "(void) setprotoent_r(0, &pdbuf);" .C "while (getprotoent_r(&protobuf, &pdbuf) != -1)" .C " count++;" .C "(void) endprotoent_r(&pdbuf);" .fi .RE .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getprotoent() , .CR getprotobynumber() , .CR getprotobyname() , .CR setprotoent() , and .CR endprotoent() are unsafe in multi-thread applications. .CR getprotoent_r() , .CR getprotobynumber_r() , .CR getprotobyname_r() , .CR setprotoent_r() , and .CR endprotoent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getprotoent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/protocols .SH SEE ALSO ypserv(1M), protocols(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getprotoent() ": XPG4" .\" .\" index@\f1end protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f1entry, get, set, or end protocol@@@\f3getprotoent(3N)\f1 .\" index@\f1get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f1protocol entry, get, set, or end@@@\f3getprotoent(3N)\f1 .\" index@\f1set protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f1thread-safe, get, set, or end protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4endprotoent()\f1 \- end protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4endprotoent_r()\f1 \- end protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobyname()\f1 \- get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobyname_r()\f1 \- get protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobynumber()\f1 \- get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobynumber_r()\f1 \- get protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotoent()\f1 \- get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotoent_r()\f1 \- get protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4setprotoent()\f1 \- set protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4setprotoent_r()\f1 \- set protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" .\" links@getprotoent.3n endprotoent.3n .\" links@getprotoent.3n getprotobyn.3n .\" links@getprotoent.3n setprotoent.3n .\" .\" toc@\f3getprotoent(3N)\f1:\0\0\f4endprotoent()\f1, \f4endprotoent_r()\f1, \f4getprotobyname()\f1, \f4getprotobyname_r()\f1,\n\f4getprotobynumber()\f1, \f4getprotobynumber_r()\f1, \f4getprotoent()\f1, \f4getprotoent_r()\f1,\n\f4setprotoent()\f1, \f4setprotoent_r()\f1,@@@get, set, or end protocol entry .\" .\" toc@\f4endprotoent()\f1:\0\0end protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4endprotoent_r()\f1:\0\0end protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobyname()\f1:\0\0get protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobyname_r()\f1:\0\0get protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobynumber()\f1:\0\0get protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobynumber_r()\f1:\0\0get protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotoent_r()\f1:\0\0get protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4setprotoent()\f1:\0\0set protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4setprotoent_r()\f1:\0\0set protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" $Header: getprpwent.3,v 78.3 96/01/19 20:14:34 ssa Exp $ .TA g .TH getprpwent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprpwent, getprpwuid, getprpwnam, getprpwaid, setprpwent, endprpwent, putprpwnam \- manipulate protected password database entry (for trusted systems only) .SH SYNOPSIS .nf .B "#include " .B "#include " .B "#include " .PP .B "struct pr_passwd \(**getprpwent(void);" .PP .B "struct pr_passwd \(**getprpwuid(uid_t uid);" .PP .B "struct pr_passwd \(**getprpwnam(const char \(**name);" \c .PP .B "struct pr_passwd \(**getprpwaid(aid_t aid)" \c .PP .B "void setprpwent(void);" .PP .B "void endprpwent(void);" .PP .B "int putprpwnam(const char \(**name, struct pr_passwd \(**pr);" .fi .SH DESCRIPTION .CR getprpwent (), .CR getprpwuid (), .CR getprpwaid (), and .CR getprpwnam () each returns a pointer to a .C pr_passwd structure containing the broken-out fields of a line in the protected password database. Each line in the database contains a .C pr_passwd structure, declared in the .RC < prot.h > header file: .IP .nf .ift .sp -1v struct pr_field { /\(** Identity: \(**/ char fd_name[9]; /\(** uses 8 character maximum(and NULL) from utmp \(**/ uid_t fd_uid; /\(** uid associated with name above \(**/ char fd_encrypt[xxx]; /\(** encrypted password \(**/ char fd_owner[9]; /\(** if a pseudo-user, the user accountable \(**/ char fd_boot_auth; /\(** boot authorization \(**/ mask_t fd_auditcntl; /\(** reserved \(**/ mask_t audit_reserve1; /\(** reserved \(**/ mask_t fd_auditdisp; /\(** reserved \(**/ mask_t audit_reserve2; /\(** reserved \(**/ aid_t fd_pw_audid; /\(** audit ID \(**/ int fd_pw_audflg; /\(** audit flag \(**/ .IP /\(** Password maintenance parameters: \(**/ time_t fd_min; /\(** minimum time between password changes \(**/ int fd_maxlen; /\(** maximum length of password \(**/ time_t fd_expire; /\(** expiration time duration in secs \(**/ time_t fd_lifetime; /\(** account death duration in seconds \(**/ time_t fd_schange; /\(** last successful change in secs past 1/1/70 \(**/ time_t fd_uchange; /\(** last unsuccessful change \(**/ time_t fd_acct_expire; /\(** absolute account lifetime in seconds \(**/ time_t fd_max_llogin; /\(** max time allowed between logins \(**/ time_t fd_pw_expire_warning; /\(** password expiration warning \(**/ uid_t fd_pswduser; /\(** who can change this user's password \(**/ char fd_pick_pwd; /\(** can user pick his own passwords? \(**/ char fd_gen_pwd; /\(** can user get passwords generated for him? \(**/ char fd_restrict; /\(** should generated passwords be restricted? \(**/ char fd_nullpw; /\(** is user allowed to have a NULL password? \(**/ uid_t fd_pwchanger; /\(** who last changed user's password \(**/ long fd_pw_admin_num;/\(** password generation verifier \(**/ char fd_gen_chars; /\(** can have password of random ASCII? \(**/ char fd_gen_letters; /\(** can have password of random letters? \(**/ char fd_tod[AUTH_TOD_SIZE]; /\(** times when user may login \(**/ .IP /\(** Login parameters: \(**/ time_t fd_slogin; /\(** last successful login \(**/ time_t fd_ulogin; /\(** last unsuccessful login \(**/ char fd_suctty[14]; /\(** tty of last successful login \(**/ short fd_nlogins; /\(** consecutive unsuccessful logins \(**/ char fd_unsuctty[14];/\(** tty of last unsuccessful login \(**/ short fd_max_tries; /\(** maximum unsuc login tries allowed \(**/ char fd_lock; /\(** Unconditionally lock account? \(**/ }; .IP struct pr_flag { unsigned short /\(** Identity: \(**/ fg_name:1, /\(** Is fd_name set? \(**/ fg_uid:1, /\(** Is fd_uid set? \(**/ fg_encrypt:1, /\(** Is fd_encrypt set? \(**/ fg_owner:1, /\(** Is fd_owner set? \(**/ fg_boot_auth:1, /\(** Is fd_boot_auth set? \(**/ fg_pw_audid:1, /\(** Is fd_auditcntl set? \(**/ fg_pw_audflg:1, /\(** Is fd_auditdisp set? \(**/ .IP /\(** Password maintenance parameters: \(**/ fg_min:1, /\(** Is fd_min set? \(**/ fg_maxlen:1, /\(** Is fd_maxlen set? \(**/ fg_expire:1, /\(** Is fd_expire set? \(**/ fg_lifetime:1, /\(** Is fd_lifetime set? \(**/ fg_schange:1, /\(** Is fd_schange set? \(**/ fg_uchange:1, /\(** Is fd_fchange set? \(**/ fg_acct_expire:1, /\(** Is fd_acct_expire set? \(**/ fg_max_llogin:1, /\(** Is fd_max_llogin set? \(**/ fg_pw_expire_warning:1, /\(** Is fd_pw_expire_warning set? \(**/ fg_pswduser:1, /\(** Is fd_pswduser set? \(**/ fg_pick_pwd:1, /\(** Is fd_pick_pwd set? \(**/ fg_gen_pwd:1, /\(** Is fd_gen_pwd set? \(**/ fg_restrict:1, /\(** Is fd_restrict set? \(**/ fg_nullpw:1, /\(** Is fd_nullpw set? \(**/ fg_pwchanger:1, /\(** Is fd_pwchanger set? \(**/ fg_pw_admin_num:1, /\(** Is fd_pw_admin_num set? \(**/ fg_gen_chars:1, /\(** Is fd_gen_chars set? \(**/ fg_gen_letters:1, /\(** Is fd_gen_letters set? \(**/ fg_tod:1, /\(** Is fd_tod set? \(**/ .IP /\(** Login parameters: \(**/ fg_slogin:1, /\(** Is fd_slogin set? \(**/ fg_suctty: 1, /\(** is fd_suctty set ? \(**/ fg_unsuctty: 1, /\(** is fd_unsuctty set ? \(**/ fg_ulogin:1, /\(** Is fd_ulogin set? \(**/ fg_nlogins:1, /\(** Is fd_nlogins set? \(**/ fg_max_tries:1, /\(** Is fd_max_tries set? \(**/ fg_lock:1; /\(** Is fd_lock set? \(**/ }; .IP struct pr_passwd { struct pr_field ufld; /\(** user specific fields \(**/ struct pr_flag uflg; /\(** user specific flags \(**/ struct pr_field sfld; /\(** system wide fields \(**/ struct pr_flag sflg; /\(** system wide flags \(**/ }; .fi .PP The protected password database stores user authentication profiles. The .C pr_passwd structure in the user-specific entry refers to parameters specific to a user. The .C pr_passwd structure in the system default database sets parameters that are used when there is no user-specific override. .PP The user-specific entry is keyed on the .I fd_name field, which is a cross reference to the .C /etc/passwd entry for the user. The .I fd_uid field must match the UID in that file as well. The .I fd_encrypt field is the encrypted password. The password is encrypted in eight character segments, so the size of this field is a multiple of the number of characters in an encrypted segment (\c .C AUTH_CIPHERTEXT_SIZE macro). .PP .I fd_owner is the user name accountable for the account. \c The .I fd_boot_auth field is used when the system default file specifies boot authorization is required. .I init(1M) prompts for a user name and password. If the authentication succeeds, a value in this field allows the user to continue the system boot process. \c .PP .I fd_min is the time, in seconds, that must elapse before the user can change passwords. .I fd_maxlen is the maximum password length (in characters) for the user. .I fd_expire is the time, in seconds, until the user's password expires. .I fd_lifetime is the number of seconds that must elapse before the password dies. The account is considered locked if the password is dead. .PP .I fd_schange and .I fd_uchange record the last successful and unsuccessful password change times. .PP The .I fd_acct_expire field specifies the absolute period of time in seconds that the account can be used. An absolute expiration date may be specified, which is then converted into seconds stored in this field. This is different from .I fd_expire in that .I fd_acct_expire specifies an absolute expiration date, while .I fd_expire is reset with each password change. .PP .I fd_max_llogin specifies the maximum time in seconds allowed since the last login before the account becomes locked. .I fd_pw_expire_warning is the time in seconds before the end of .I fd_expire that the system warns the user the password is about to expire. .I fd_pswduser stores the user ID of the user allowed to change passwords for the account. \c Typically, this is the account owner. \c .PP The next flag fields control password generation. .IR fd_pick_pwd , if set, allows the user to pick his or her own password. .IR fd_nullpw , if set, allows the account to be used without a password. .I fd_gen_pwd enables the use of the random pronounceable password generator for passwords for this account. .I fd_gen_chars and .I fd_gen_letters allow the password generator to generate passwords composed of random printable characters and random letters, neither of which is easy to remember. The password change software allows the user to pick from whichever options are available for his or her account. One of these three fields .RI ( fd_gen_pwd , .IR fd_gen_chars , or .IR fd_gen_letters ) must be set. .PP .I fd_pwchanger is the user ID of the user who last changed the password on the user's account, if it was not the account owner. .IR fd_restrict , if set, causes triviality checks to be made after the account password has been chosen to avoid palindromes, user name and machine name permutations, and words appearing in the dictionary. .PP The .I fd_tod specifier is a string, formatted like the UUCP .C Systems file, which specifies time intervals during which the user can log in. \c .PP The next fields are used to protect against login spoofing, listing the time and location of last login. .I fd_slogin and .I fd_ulogin are time stamps of the last successful and unsuccessful login attempts. .I fd_suctty and .I fd_unsuctty are the terminal device or (if supported) host names of the terminal or host from which the last login attempt occurred. .PP .I fd_nlogins is the number of unsuccessful login attempts since the last successful login. It is reset to zero after a successful login. .I fd_max_tries is the number of unsuccessful attempts until the account is considered locked. .PP .I fd_lock indicates whether the administrative lock on the account is set. The account is considered disabled (locked) if one or more of these activities has occurred: .PD 0 .PP 1. if the password is dead, .PP 2. if the maximum number of unsuccessful attempts has been exceeded, .PP 3. if the administrative lock is set, .PP 4. if the account expiration is reached, or .PP 5. if the time since last login is exceeded. .PD .PP When .CR getprpwent () is first called, it returns a pointer to the first user .C pr_passwd structure in the database; thereafter, it returns a pointer to the next .C pr_passwd structure in the database so that successive calls can be used to search the database. Note that entries without a corresponding entry in .C /etc/passwd are skipped. The entries are scanned in the order they appear in .CR /etc/passwd . .PP .CR getprpwuid () searches from the beginning of the database until a numerical user ID matching .I uid is found and returns a pointer to the particular structure in which it was found. \c .CR getprpwaid () functions like .CR getprpwuid () only it uses the audit ID instead of the uid. \c .PP .CR getprpwnam () searches from the beginning of the database until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a NULL pointer. .PP A call to .CR setprpwent () has the effect of rewinding the protected password database to allow repeated searches. .CR endprpwent () can be called to close the protected password database when processing is complete. .PP .CR putprpwnam () puts a new or replaced protected password entry .I pr with key .I name into the database. If the .I uflg.fg_name field is 0, the requested entry is deleted from the protected password database. .CR putprpwnam () locks the database for all update operations, and performs a .CR endprpwent () after the update or failed attempt. .SS Notes .PP The value returned by .CR getprpwent () and .CR getprpwnam () refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .CR putprpwnam (). .PP On systems supporting network connections, the .I fd_suctty and .I fd_unsuctty fields can be the ASCII representation of the network address of the host from which the last successful or unsuccessful remote login to the account occurred. Use .IR getdvagnam (3) to investigate the type of device to determine whether a host or a terminal was used for the last successful or unsuccessful login. .PP Programs using these routines must be compiled with .CR \-lsec . .PP .CR getprpwent () assumes one name per UID and one UID per name. The sequential scan loops between the first two instances of a multiple UID. .PP .CR getprpwent () uses .IR getpwent (3) routines to sequentially scan databases. User program references to password entries obtained using .IR getpwent (3) routines will not be valid after using any routines described here (ie., the * .CR prp * routines). .SH RETURN VALUE .CR getprpwent (), .CR getprpwuid (), and .CR getprpwnam () return NULL pointers on EOF or error. .CR putprpwnam () returns 0 if it cannot add or update the entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 35 .C /etc/passwd System Password file .PD 0 .TP .C /tcb/files/auth/\(**/\(** Protected Password database .TP .C /tcb/files/auth/system/default System Defaults database .PD .SH SEE ALSO authcap(4), getpwent(3), getprdfent(3), prpwd(4). .\" .\" index@\f4getprpwuid\f1 \- get protected password database user ID@@@\f3getprpwent(3)\f1 .\" index@\f4getprpwaid\f1 \- get protected password database audit ID@@@\f3getprpwent(3)\f1 .\" index@\f4getprpwnam\f1 \- get protected password database user name@@@\f3getprpwent(3)\f1 .\" index@\f4setprpwent\f1 \- set protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f4endprpwent\f1 \- manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f4putprpwnam\f1 \- manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1access protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1protected password database entry, manipulate@@@\f3getprpwent(3)\f1 .\" index@\f1password database entry, manipulate protected@@@\f3getprpwent(3)\f1 .\" index@\f1database entry, manipulate protected password@@@\f3getprpwent(3)\f1 .\" index@\f1entry, manipulate protected password database@@@\f3getprpwent(3)\f1 .\" .\" toc@\f3getprpwent(3)\f1:\0\0\f4getprpwent\f1, \f4getprpwuid\f1, \f4getprpwnam\f1, \f4getprpwaid\f1, \f4setprpwent\f1,\n\f4endprpwent\f1, \f4putprpwnam\f1@@@manipulate protected password database entry .\" toc@\f4getprpwuid\f1:\0\0get protected password database user ID@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4getprpwaid\f1:\0\0get protected password database audit ID@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4getprpwnam\f1:\0\0get protected password database user name@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4setprpwent\f1:\0\0set protected password database entry@@@\f1 see \f3getprpwent(3)\f1 .\" toc@\f4endprpwent\f1:\0\0manipulate protected password database entry@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4putprpwnam\f1:\0\0manipulate protected password database entry@@@\f1 see \f3getprpwent(3)\f1 .\" .\" links@getprpwent.3 getprpwuid.3 .\" links@getprpwent.3 getprpwnam.3 .\" links@getprpwent.3 setprpwent.3 .\" links@getprpwent.3 endprpwent.3 .\" links@getprpwent.3 putprpwnam.3 .\" links@getprpwent.3 getprpwaid.3 .\" .\" $Header: getprpwent.3,v 78.3 96/01/19 20:14:34 ssa Exp $ .TA g .TH getprpwent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprpwent, getprpwuid, getprpwnam, getprpwaid, setprpwent, endprpwent, putprpwnam \- manipulate protected password database entry (for trusted systems only) .SH SYNOPSIS .nf .B "#include " .B "#include " .B "#include " .PP .B "struct pr_passwd \(**getprpwent(void);" .PP .B "struct pr_passwd \(**getprpwuid(uid_t uid);" .PP .B "struct pr_passwd \(**getprpwnam(const char \(**name);" \c .PP .B "struct pr_passwd \(**getprpwaid(aid_t aid)" \c .PP .B "void setprpwent(void);" .PP .B "void endprpwent(void);" .PP .B "int putprpwnam(const char \(**name, struct pr_passwd \(**pr);" .fi .SH DESCRIPTION .CR getprpwent (), .CR getprpwuid (), .CR getprpwaid (), and .CR getprpwnam () each returns a pointer to a .C pr_passwd structure containing the broken-out fields of a line in the protected password database. Each line in the database contains a .C pr_passwd structure, declared in the .RC < prot.h > header file: .IP .nf .ift .sp -1v struct pr_field { /\(** Identity: \(**/ char fd_name[9]; /\(** uses 8 character maximum(and NULL) from utmp \(**/ uid_t fd_uid; /\(** uid associated with name above \(**/ char fd_encrypt[xxx]; /\(** encrypted password \(**/ char fd_owner[9]; /\(** if a pseudo-user, the user accountable \(**/ char fd_boot_auth; /\(** boot authorization \(**/ mask_t fd_auditcntl; /\(** reserved \(**/ mask_t audit_reserve1; /\(** reserved \(**/ mask_t fd_auditdisp; /\(** reserved \(**/ mask_t audit_reserve2; /\(** reserved \(**/ aid_t fd_pw_audid; /\(** audit ID \(**/ int fd_pw_audflg; /\(** audit flag \(**/ .IP /\(** Password maintenance parameters: \(**/ time_t fd_min; /\(** minimum time between password changes \(**/ int fd_maxlen; /\(** maximum length of password \(**/ time_t fd_expire; /\(** expiration time duration in secs \(**/ time_t fd_lifetime; /\(** account death duration in seconds \(**/ time_t fd_schange; /\(** last successful change in secs past 1/1/70 \(**/ time_t fd_uchange; /\(** last unsuccessful change \(**/ time_t fd_acct_expire; /\(** absolute account lifetime in seconds \(**/ time_t fd_max_llogin; /\(** max time allowed between logins \(**/ time_t fd_pw_expire_warning; /\(** password expiration warning \(**/ uid_t fd_pswduser; /\(** who can change this user's password \(**/ char fd_pick_pwd; /\(** can user pick his own passwords? \(**/ char fd_gen_pwd; /\(** can user get passwords generated for him? \(**/ char fd_restrict; /\(** should generated passwords be restricted? \(**/ char fd_nullpw; /\(** is user allowed to have a NULL password? \(**/ uid_t fd_pwchanger; /\(** who last changed user's password \(**/ long fd_pw_admin_num;/\(** password generation verifier \(**/ char fd_gen_chars; /\(** can have password of random ASCII? \(**/ char fd_gen_letters; /\(** can have password of random letters? \(**/ char fd_tod[AUTH_TOD_SIZE]; /\(** times when user may login \(**/ .IP /\(** Login parameters: \(**/ time_t fd_slogin; /\(** last successful login \(**/ time_t fd_ulogin; /\(** last unsuccessful login \(**/ char fd_suctty[14]; /\(** tty of last successful login \(**/ short fd_nlogins; /\(** consecutive unsuccessful logins \(**/ char fd_unsuctty[14];/\(** tty of last unsuccessful login \(**/ short fd_max_tries; /\(** maximum unsuc login tries allowed \(**/ char fd_lock; /\(** Unconditionally lock account? \(**/ }; .IP struct pr_flag { unsigned short /\(** Identity: \(**/ fg_name:1, /\(** Is fd_name set? \(**/ fg_uid:1, /\(** Is fd_uid set? \(**/ fg_encrypt:1, /\(** Is fd_encrypt set? \(**/ fg_owner:1, /\(** Is fd_owner set? \(**/ fg_boot_auth:1, /\(** Is fd_boot_auth set? \(**/ fg_pw_audid:1, /\(** Is fd_auditcntl set? \(**/ fg_pw_audflg:1, /\(** Is fd_auditdisp set? \(**/ .IP /\(** Password maintenance parameters: \(**/ fg_min:1, /\(** Is fd_min set? \(**/ fg_maxlen:1, /\(** Is fd_maxlen set? \(**/ fg_expire:1, /\(** Is fd_expire set? \(**/ fg_lifetime:1, /\(** Is fd_lifetime set? \(**/ fg_schange:1, /\(** Is fd_schange set? \(**/ fg_uchange:1, /\(** Is fd_fchange set? \(**/ fg_acct_expire:1, /\(** Is fd_acct_expire set? \(**/ fg_max_llogin:1, /\(** Is fd_max_llogin set? \(**/ fg_pw_expire_warning:1, /\(** Is fd_pw_expire_warning set? \(**/ fg_pswduser:1, /\(** Is fd_pswduser set? \(**/ fg_pick_pwd:1, /\(** Is fd_pick_pwd set? \(**/ fg_gen_pwd:1, /\(** Is fd_gen_pwd set? \(**/ fg_restrict:1, /\(** Is fd_restrict set? \(**/ fg_nullpw:1, /\(** Is fd_nullpw set? \(**/ fg_pwchanger:1, /\(** Is fd_pwchanger set? \(**/ fg_pw_admin_num:1, /\(** Is fd_pw_admin_num set? \(**/ fg_gen_chars:1, /\(** Is fd_gen_chars set? \(**/ fg_gen_letters:1, /\(** Is fd_gen_letters set? \(**/ fg_tod:1, /\(** Is fd_tod set? \(**/ .IP /\(** Login parameters: \(**/ fg_slogin:1, /\(** Is fd_slogin set? \(**/ fg_suctty: 1, /\(** is fd_suctty set ? \(**/ fg_unsuctty: 1, /\(** is fd_unsuctty set ? \(**/ fg_ulogin:1, /\(** Is fd_ulogin set? \(**/ fg_nlogins:1, /\(** Is fd_nlogins set? \(**/ fg_max_tries:1, /\(** Is fd_max_tries set? \(**/ fg_lock:1; /\(** Is fd_lock set? \(**/ }; .IP struct pr_passwd { struct pr_field ufld; /\(** user specific fields \(**/ struct pr_flag uflg; /\(** user specific flags \(**/ struct pr_field sfld; /\(** system wide fields \(**/ struct pr_flag sflg; /\(** system wide flags \(**/ }; .fi .PP The protected password database stores user authentication profiles. The .C pr_passwd structure in the user-specific entry refers to parameters specific to a user. The .C pr_passwd structure in the system default database sets parameters that are used when there is no user-specific override. .PP The user-specific entry is keyed on the .I fd_name field, which is a cross reference to the .C /etc/passwd entry for the user. The .I fd_uid field must match the UID in that file as well. The .I fd_encrypt field is the encrypted password. The password is encrypted in eight character segments, so the size of this field is a multiple of the number of characters in an encrypted segment (\c .C AUTH_CIPHERTEXT_SIZE macro). .PP .I fd_owner is the user name accountable for the account. \c The .I fd_boot_auth field is used when the system default file specifies boot authorization is required. .I init(1M) prompts for a user name and password. If the authentication succeeds, a value in this field allows the user to continue the system boot process. \c .PP .I fd_min is the time, in seconds, that must elapse before the user can change passwords. .I fd_maxlen is the maximum password length (in characters) for the user. .I fd_expire is the time, in seconds, until the user's password expires. .I fd_lifetime is the number of seconds that must elapse before the password dies. The account is considered locked if the password is dead. .PP .I fd_schange and .I fd_uchange record the last successful and unsuccessful password change times. .PP The .I fd_acct_expire field specifies the absolute period of time in seconds that the account can be used. An absolute expiration date may be specified, which is then converted into seconds stored in this field. This is different from .I fd_expire in that .I fd_acct_expire specifies an absolute expiration date, while .I fd_expire is reset with each password change. .PP .I fd_max_llogin specifies the maximum time in seconds allowed since the last login before the account becomes locked. .I fd_pw_expire_warning is the time in seconds before the end of .I fd_expire that the system warns the user the password is about to expire. .I fd_pswduser stores the user ID of the user allowed to change passwords for the account. \c Typically, this is the account owner. \c .PP The next flag fields control password generation. .IR fd_pick_pwd , if set, allows the user to pick his or her own password. .IR fd_nullpw , if set, allows the account to be used without a password. .I fd_gen_pwd enables the use of the random pronounceable password generator for passwords for this account. .I fd_gen_chars and .I fd_gen_letters allow the password generator to generate passwords composed of random printable characters and random letters, neither of which is easy to remember. The password change software allows the user to pick from whichever options are available for his or her account. One of these three fields .RI ( fd_gen_pwd , .IR fd_gen_chars , or .IR fd_gen_letters ) must be set. .PP .I fd_pwchanger is the user ID of the user who last changed the password on the user's account, if it was not the account owner. .IR fd_restrict , if set, causes triviality checks to be made after the account password has been chosen to avoid palindromes, user name and machine name permutations, and words appearing in the dictionary. .PP The .I fd_tod specifier is a string, formatted like the UUCP .C Systems file, which specifies time intervals during which the user can log in. \c .PP The next fields are used to protect against login spoofing, listing the time and location of last login. .I fd_slogin and .I fd_ulogin are time stamps of the last successful and unsuccessful login attempts. .I fd_suctty and .I fd_unsuctty are the terminal device or (if supported) host names of the terminal or host from which the last login attempt occurred. .PP .I fd_nlogins is the number of unsuccessful login attempts since the last successful login. It is reset to zero after a successful login. .I fd_max_tries is the number of unsuccessful attempts until the account is considered locked. .PP .I fd_lock indicates whether the administrative lock on the account is set. The account is considered disabled (locked) if one or more of these activities has occurred: .PD 0 .PP 1. if the password is dead, .PP 2. if the maximum number of unsuccessful attempts has been exceeded, .PP 3. if the administrative lock is set, .PP 4. if the account expiration is reached, or .PP 5. if the time since last login is exceeded. .PD .PP When .CR getprpwent () is first called, it returns a pointer to the first user .C pr_passwd structure in the database; thereafter, it returns a pointer to the next .C pr_passwd structure in the database so that successive calls can be used to search the database. Note that entries without a corresponding entry in .C /etc/passwd are skipped. The entries are scanned in the order they appear in .CR /etc/passwd . .PP .CR getprpwuid () searches from the beginning of the database until a numerical user ID matching .I uid is found and returns a pointer to the particular structure in which it was found. \c .CR getprpwaid () functions like .CR getprpwuid () only it uses the audit ID instead of the uid. \c .PP .CR getprpwnam () searches from the beginning of the database until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a NULL pointer. .PP A call to .CR setprpwent () has the effect of rewinding the protected password database to allow repeated searches. .CR endprpwent () can be called to close the protected password database when processing is complete. .PP .CR putprpwnam () puts a new or replaced protected password entry .I pr with key .I name into the database. If the .I uflg.fg_name field is 0, the requested entry is deleted from the protected password database. .CR putprpwnam () locks the database for all update operations, and performs a .CR endprpwent () after the update or failed attempt. .SS Notes .PP The value returned by .CR getprpwent () and .CR getprpwnam () refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .CR putprpwnam (). .PP On systems supporting network connections, the .I fd_suctty and .I fd_unsuctty fields can be the ASCII representation of the network address of the host from which the last successful or unsuccessful remote login to the account occurred. Use .IR getdvagnam (3) to investigate the type of device to determine whether a host or a terminal was used for the last successful or unsuccessful login. .PP Programs using these routines must be compiled with .CR \-lsec . .PP .CR getprpwent () assumes one name per UID and one UID per name. The sequential scan loops between the first two instances of a multiple UID. .PP .CR getprpwent () uses .IR getpwent (3) routines to sequentially scan databases. User program references to password entries obtained using .IR getpwent (3) routines will not be valid after using any routines described here (ie., the * .CR prp * routines). .SH RETURN VALUE .CR getprpwent (), .CR getprpwuid (), and .CR getprpwnam () return NULL pointers on EOF or error. .CR putprpwnam () returns 0 if it cannot add or update the entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 35 .C /etc/passwd System Password file .PD 0 .TP .C /tcb/files/auth/\(**/\(** Protected Password database .TP .C /tcb/files/auth/system/default System Defaults database .PD .SH SEE ALSO authcap(4), getpwent(3), getprdfent(3), prpwd(4). .\" .\" index@\f4getprpwuid\f1 \- get protected password database user ID@@@\f3getprpwent(3)\f1 .\" index@\f4getprpwaid\f1 \- get protected password database audit ID@@@\f3getprpwent(3)\f1 .\" index@\f4getprpwnam\f1 \- get protected password database user name@@@\f3getprpwent(3)\f1 .\" index@\f4setprpwent\f1 \- set protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f4endprpwent\f1 \- manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f4putprpwnam\f1 \- manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1access protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1protected password database entry, manipulate@@@\f3getprpwent(3)\f1 .\" index@\f1password database entry, manipulate protected@@@\f3getprpwent(3)\f1 .\" index@\f1database entry, manipulate protected password@@@\f3getprpwent(3)\f1 .\" index@\f1entry, manipulate protected password database@@@\f3getprpwent(3)\f1 .\" .\" toc@\f3getprpwent(3)\f1:\0\0\f4getprpwent\f1, \f4getprpwuid\f1, \f4getprpwnam\f1, \f4getprpwaid\f1, \f4setprpwent\f1,\n\f4endprpwent\f1, \f4putprpwnam\f1@@@manipulate protected password database entry .\" toc@\f4getprpwuid\f1:\0\0get protected password database user ID@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4getprpwaid\f1:\0\0get protected password database audit ID@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4getprpwnam\f1:\0\0get protected password database user name@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4setprpwent\f1:\0\0set protected password database entry@@@\f1 see \f3getprpwent(3)\f1 .\" toc@\f4endprpwent\f1:\0\0manipulate protected password database entry@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4putprpwnam\f1:\0\0manipulate protected password database entry@@@\f1 see \f3getprpwent(3)\f1 .\" .\" links@getprpwent.3 getprpwuid.3 .\" links@getprpwent.3 getprpwnam.3 .\" links@getprpwent.3 setprpwent.3 .\" links@getprpwent.3 endprpwent.3 .\" links@getprpwent.3 putprpwnam.3 .\" links@getprpwent.3 getprpwaid.3 .\" .\" $Header: getprpwent.3,v 78.3 96/01/19 20:14:34 ssa Exp $ .TA g .TH getprpwent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprpwent, getprpwuid, getprpwnam, getprpwaid, setprpwent, endprpwent, putprpwnam \- manipulate protected password database entry (for trusted systems only) .SH SYNOPSIS .nf .B "#include " .B "#include " .B "#include " .PP .B "struct pr_passwd \(**getprpwent(void);" .PP .B "struct pr_passwd \(**getprpwuid(uid_t uid);" .PP .B "struct pr_passwd \(**getprpwnam(const char \(**name);" \c .PP .B "struct pr_passwd \(**getprpwaid(aid_t aid)" \c .PP .B "void setprpwent(void);" .PP .B "void endprpwent(void);" .PP .B "int putprpwnam(const char \(**name, struct pr_passwd \(**pr);" .fi .SH DESCRIPTION .CR getprpwent (), .CR getprpwuid (), .CR getprpwaid (), and .CR getprpwnam () each returns a pointer to a .C pr_passwd structure containing the broken-out fields of a line in the protected password database. Each line in the database contains a .C pr_passwd structure, declared in the .RC < prot.h > header file: .IP .nf .ift .sp -1v struct pr_field { /\(** Identity: \(**/ char fd_name[9]; /\(** uses 8 character maximum(and NULL) from utmp \(**/ uid_t fd_uid; /\(** uid associated with name above \(**/ char fd_encrypt[xxx]; /\(** encrypted password \(**/ char fd_owner[9]; /\(** if a pseudo-user, the user accountable \(**/ char fd_boot_auth; /\(** boot authorization \(**/ mask_t fd_auditcntl; /\(** reserved \(**/ mask_t audit_reserve1; /\(** reserved \(**/ mask_t fd_auditdisp; /\(** reserved \(**/ mask_t audit_reserve2; /\(** reserved \(**/ aid_t fd_pw_audid; /\(** audit ID \(**/ int fd_pw_audflg; /\(** audit flag \(**/ .IP /\(** Password maintenance parameters: \(**/ time_t fd_min; /\(** minimum time between password changes \(**/ int fd_maxlen; /\(** maximum length of password \(**/ time_t fd_expire; /\(** expiration time duration in secs \(**/ time_t fd_lifetime; /\(** account death duration in seconds \(**/ time_t fd_schange; /\(** last successful change in secs past 1/1/70 \(**/ time_t fd_uchange; /\(** last unsuccessful change \(**/ time_t fd_acct_expire; /\(** absolute account lifetime in seconds \(**/ time_t fd_max_llogin; /\(** max time allowed between logins \(**/ time_t fd_pw_expire_warning; /\(** password expiration warning \(**/ uid_t fd_pswduser; /\(** who can change this user's password \(**/ char fd_pick_pwd; /\(** can user pick his own passwords? \(**/ char fd_gen_pwd; /\(** can user get passwords generated for him? \(**/ char fd_restrict; /\(** should generated passwords be restricted? \(**/ char fd_nullpw; /\(** is user allowed to have a NULL password? \(**/ uid_t fd_pwchanger; /\(** who last changed user's password \(**/ long fd_pw_admin_num;/\(** password generation verifier \(**/ char fd_gen_chars; /\(** can have password of random ASCII? \(**/ char fd_gen_letters; /\(** can have password of random letters? \(**/ char fd_tod[AUTH_TOD_SIZE]; /\(** times when user may login \(**/ .IP /\(** Login parameters: \(**/ time_t fd_slogin; /\(** last successful login \(**/ time_t fd_ulogin; /\(** last unsuccessful login \(**/ char fd_suctty[14]; /\(** tty of last successful login \(**/ short fd_nlogins; /\(** consecutive unsuccessful logins \(**/ char fd_unsuctty[14];/\(** tty of last unsuccessful login \(**/ short fd_max_tries; /\(** maximum unsuc login tries allowed \(**/ char fd_lock; /\(** Unconditionally lock account? \(**/ }; .IP struct pr_flag { unsigned short /\(** Identity: \(**/ fg_name:1, /\(** Is fd_name set? \(**/ fg_uid:1, /\(** Is fd_uid set? \(**/ fg_encrypt:1, /\(** Is fd_encrypt set? \(**/ fg_owner:1, /\(** Is fd_owner set? \(**/ fg_boot_auth:1, /\(** Is fd_boot_auth set? \(**/ fg_pw_audid:1, /\(** Is fd_auditcntl set? \(**/ fg_pw_audflg:1, /\(** Is fd_auditdisp set? \(**/ .IP /\(** Password maintenance parameters: \(**/ fg_min:1, /\(** Is fd_min set? \(**/ fg_maxlen:1, /\(** Is fd_maxlen set? \(**/ fg_expire:1, /\(** Is fd_expire set? \(**/ fg_lifetime:1, /\(** Is fd_lifetime set? \(**/ fg_schange:1, /\(** Is fd_schange set? \(**/ fg_uchange:1, /\(** Is fd_fchange set? \(**/ fg_acct_expire:1, /\(** Is fd_acct_expire set? \(**/ fg_max_llogin:1, /\(** Is fd_max_llogin set? \(**/ fg_pw_expire_warning:1, /\(** Is fd_pw_expire_warning set? \(**/ fg_pswduser:1, /\(** Is fd_pswduser set? \(**/ fg_pick_pwd:1, /\(** Is fd_pick_pwd set? \(**/ fg_gen_pwd:1, /\(** Is fd_gen_pwd set? \(**/ fg_restrict:1, /\(** Is fd_restrict set? \(**/ fg_nullpw:1, /\(** Is fd_nullpw set? \(**/ fg_pwchanger:1, /\(** Is fd_pwchanger set? \(**/ fg_pw_admin_num:1, /\(** Is fd_pw_admin_num set? \(**/ fg_gen_chars:1, /\(** Is fd_gen_chars set? \(**/ fg_gen_letters:1, /\(** Is fd_gen_letters set? \(**/ fg_tod:1, /\(** Is fd_tod set? \(**/ .IP /\(** Login parameters: \(**/ fg_slogin:1, /\(** Is fd_slogin set? \(**/ fg_suctty: 1, /\(** is fd_suctty set ? \(**/ fg_unsuctty: 1, /\(** is fd_unsuctty set ? \(**/ fg_ulogin:1, /\(** Is fd_ulogin set? \(**/ fg_nlogins:1, /\(** Is fd_nlogins set? \(**/ fg_max_tries:1, /\(** Is fd_max_tries set? \(**/ fg_lock:1; /\(** Is fd_lock set? \(**/ }; .IP struct pr_passwd { struct pr_field ufld; /\(** user specific fields \(**/ struct pr_flag uflg; /\(** user specific flags \(**/ struct pr_field sfld; /\(** system wide fields \(**/ struct pr_flag sflg; /\(** system wide flags \(**/ }; .fi .PP The protected password database stores user authentication profiles. The .C pr_passwd structure in the user-specific entry refers to parameters specific to a user. The .C pr_passwd structure in the system default database sets parameters that are used when there is no user-specific override. .PP The user-specific entry is keyed on the .I fd_name field, which is a cross reference to the .C /etc/passwd entry for the user. The .I fd_uid field must match the UID in that file as well. The .I fd_encrypt field is the encrypted password. The password is encrypted in eight character segments, so the size of this field is a multiple of the number of characters in an encrypted segment (\c .C AUTH_CIPHERTEXT_SIZE macro). .PP .I fd_owner is the user name accountable for the account. \c The .I fd_boot_auth field is used when the system default file specifies boot authorization is required. .I init(1M) prompts for a user name and password. If the authentication succeeds, a value in this field allows the user to continue the system boot process. \c .PP .I fd_min is the time, in seconds, that must elapse before the user can change passwords. .I fd_maxlen is the maximum password length (in characters) for the user. .I fd_expire is the time, in seconds, until the user's password expires. .I fd_lifetime is the number of seconds that must elapse before the password dies. The account is considered locked if the password is dead. .PP .I fd_schange and .I fd_uchange record the last successful and unsuccessful password change times. .PP The .I fd_acct_expire field specifies the absolute period of time in seconds that the account can be used. An absolute expiration date may be specified, which is then converted into seconds stored in this field. This is different from .I fd_expire in that .I fd_acct_expire specifies an absolute expiration date, while .I fd_expire is reset with each password change. .PP .I fd_max_llogin specifies the maximum time in seconds allowed since the last login before the account becomes locked. .I fd_pw_expire_warning is the time in seconds before the end of .I fd_expire that the system warns the user the password is about to expire. .I fd_pswduser stores the user ID of the user allowed to change passwords for the account. \c Typically, this is the account owner. \c .PP The next flag fields control password generation. .IR fd_pick_pwd , if set, allows the user to pick his or her own password. .IR fd_nullpw , if set, allows the account to be used without a password. .I fd_gen_pwd enables the use of the random pronounceable password generator for passwords for this account. .I fd_gen_chars and .I fd_gen_letters allow the password generator to generate passwords composed of random printable characters and random letters, neither of which is easy to remember. The password change software allows the user to pick from whichever options are available for his or her account. One of these three fields .RI ( fd_gen_pwd , .IR fd_gen_chars , or .IR fd_gen_letters ) must be set. .PP .I fd_pwchanger is the user ID of the user who last changed the password on the user's account, if it was not the account owner. .IR fd_restrict , if set, causes triviality checks to be made after the account password has been chosen to avoid palindromes, user name and machine name permutations, and words appearing in the dictionary. .PP The .I fd_tod specifier is a string, formatted like the UUCP .C Systems file, which specifies time intervals during which the user can log in. \c .PP The next fields are used to protect against login spoofing, listing the time and location of last login. .I fd_slogin and .I fd_ulogin are time stamps of the last successful and unsuccessful login attempts. .I fd_suctty and .I fd_unsuctty are the terminal device or (if supported) host names of the terminal or host from which the last login attempt occurred. .PP .I fd_nlogins is the number of unsuccessful login attempts since the last successful login. It is reset to zero after a successful login. .I fd_max_tries is the number of unsuccessful attempts until the account is considered locked. .PP .I fd_lock indicates whether the administrative lock on the account is set. The account is considered disabled (locked) if one or more of these activities has occurred: .PD 0 .PP 1. if the password is dead, .PP 2. if the maximum number of unsuccessful attempts has been exceeded, .PP 3. if the administrative lock is set, .PP 4. if the account expiration is reached, or .PP 5. if the time since last login is exceeded. .PD .PP When .CR getprpwent () is first called, it returns a pointer to the first user .C pr_passwd structure in the database; thereafter, it returns a pointer to the next .C pr_passwd structure in the database so that successive calls can be used to search the database. Note that entries without a corresponding entry in .C /etc/passwd are skipped. The entries are scanned in the order they appear in .CR /etc/passwd . .PP .CR getprpwuid () searches from the beginning of the database until a numerical user ID matching .I uid is found and returns a pointer to the particular structure in which it was found. \c .CR getprpwaid () functions like .CR getprpwuid () only it uses the audit ID instead of the uid. \c .PP .CR getprpwnam () searches from the beginning of the database until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a NULL pointer. .PP A call to .CR setprpwent () has the effect of rewinding the protected password database to allow repeated searches. .CR endprpwent () can be called to close the protected password database when processing is complete. .PP .CR putprpwnam () puts a new or replaced protected password entry .I pr with key .I name into the database. If the .I uflg.fg_name field is 0, the requested entry is deleted from the protected password database. .CR putprpwnam () locks the database for all update operations, and performs a .CR endprpwent () after the update or failed attempt. .SS Notes .PP The value returned by .CR getprpwent () and .CR getprpwnam () refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .CR putprpwnam (). .PP On systems supporting network connections, the .I fd_suctty and .I fd_unsuctty fields can be the ASCII representation of the network address of the host from which the last successful or unsuccessful remote login to the account occurred. Use .IR getdvagnam (3) to investigate the type of device to determine whether a host or a terminal was used for the last successful or unsuccessful login. .PP Programs using these routines must be compiled with .CR \-lsec . .PP .CR getprpwent () assumes one name per UID and one UID per name. The sequential scan loops between the first two instances of a multiple UID. .PP .CR getprpwent () uses .IR getpwent (3) routines to sequentially scan databases. User program references to password entries obtained using .IR getpwent (3) routines will not be valid after using any routines described here (ie., the * .CR prp * routines). .SH RETURN VALUE .CR getprpwent (), .CR getprpwuid (), and .CR getprpwnam () return NULL pointers on EOF or error. .CR putprpwnam () returns 0 if it cannot add or update the entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 35 .C /etc/passwd System Password file .PD 0 .TP .C /tcb/files/auth/\(**/\(** Protected Password database .TP .C /tcb/files/auth/system/default System Defaults database .PD .SH SEE ALSO authcap(4), getpwent(3), getprdfent(3), prpwd(4). .\" .\" index@\f4getprpwuid\f1 \- get protected password database user ID@@@\f3getprpwent(3)\f1 .\" index@\f4getprpwaid\f1 \- get protected password database audit ID@@@\f3getprpwent(3)\f1 .\" index@\f4getprpwnam\f1 \- get protected password database user name@@@\f3getprpwent(3)\f1 .\" index@\f4setprpwent\f1 \- set protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f4endprpwent\f1 \- manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f4putprpwnam\f1 \- manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1access protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1protected password database entry, manipulate@@@\f3getprpwent(3)\f1 .\" index@\f1password database entry, manipulate protected@@@\f3getprpwent(3)\f1 .\" index@\f1database entry, manipulate protected password@@@\f3getprpwent(3)\f1 .\" index@\f1entry, manipulate protected password database@@@\f3getprpwent(3)\f1 .\" .\" toc@\f3getprpwent(3)\f1:\0\0\f4getprpwent\f1, \f4getprpwuid\f1, \f4getprpwnam\f1, \f4getprpwaid\f1, \f4setprpwent\f1,\n\f4endprpwent\f1, \f4putprpwnam\f1@@@manipulate protected password database entry .\" toc@\f4getprpwuid\f1:\0\0get protected password database user ID@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4getprpwaid\f1:\0\0get protected password database audit ID@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4getprpwnam\f1:\0\0get protected password database user name@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4setprpwent\f1:\0\0set protected password database entry@@@\f1 see \f3getprpwent(3)\f1 .\" toc@\f4endprpwent\f1:\0\0manipulate protected password database entry@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4putprpwnam\f1:\0\0manipulate protected password database entry@@@\f1 see \f3getprpwent(3)\f1 .\" .\" links@getprpwent.3 getprpwuid.3 .\" links@getprpwent.3 getprpwnam.3 .\" links@getprpwent.3 setprpwent.3 .\" links@getprpwent.3 endprpwent.3 .\" links@getprpwent.3 putprpwnam.3 .\" links@getprpwent.3 getprpwaid.3 .\" .\" $Header: getprpwent.3,v 78.3 96/01/19 20:14:34 ssa Exp $ .TA g .TH getprpwent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprpwent, getprpwuid, getprpwnam, getprpwaid, setprpwent, endprpwent, putprpwnam \- manipulate protected password database entry (for trusted systems only) .SH SYNOPSIS .nf .B "#include " .B "#include " .B "#include " .PP .B "struct pr_passwd \(**getprpwent(void);" .PP .B "struct pr_passwd \(**getprpwuid(uid_t uid);" .PP .B "struct pr_passwd \(**getprpwnam(const char \(**name);" \c .PP .B "struct pr_passwd \(**getprpwaid(aid_t aid)" \c .PP .B "void setprpwent(void);" .PP .B "void endprpwent(void);" .PP .B "int putprpwnam(const char \(**name, struct pr_passwd \(**pr);" .fi .SH DESCRIPTION .CR getprpwent (), .CR getprpwuid (), .CR getprpwaid (), and .CR getprpwnam () each returns a pointer to a .C pr_passwd structure containing the broken-out fields of a line in the protected password database. Each line in the database contains a .C pr_passwd structure, declared in the .RC < prot.h > header file: .IP .nf .ift .sp -1v struct pr_field { /\(** Identity: \(**/ char fd_name[9]; /\(** uses 8 character maximum(and NULL) from utmp \(**/ uid_t fd_uid; /\(** uid associated with name above \(**/ char fd_encrypt[xxx]; /\(** encrypted password \(**/ char fd_owner[9]; /\(** if a pseudo-user, the user accountable \(**/ char fd_boot_auth; /\(** boot authorization \(**/ mask_t fd_auditcntl; /\(** reserved \(**/ mask_t audit_reserve1; /\(** reserved \(**/ mask_t fd_auditdisp; /\(** reserved \(**/ mask_t audit_reserve2; /\(** reserved \(**/ aid_t fd_pw_audid; /\(** audit ID \(**/ int fd_pw_audflg; /\(** audit flag \(**/ .IP /\(** Password maintenance parameters: \(**/ time_t fd_min; /\(** minimum time between password changes \(**/ int fd_maxlen; /\(** maximum length of password \(**/ time_t fd_expire; /\(** expiration time duration in secs \(**/ time_t fd_lifetime; /\(** account death duration in seconds \(**/ time_t fd_schange; /\(** last successful change in secs past 1/1/70 \(**/ time_t fd_uchange; /\(** last unsuccessful change \(**/ time_t fd_acct_expire; /\(** absolute account lifetime in seconds \(**/ time_t fd_max_llogin; /\(** max time allowed between logins \(**/ time_t fd_pw_expire_warning; /\(** password expiration warning \(**/ uid_t fd_pswduser; /\(** who can change this user's password \(**/ char fd_pick_pwd; /\(** can user pick his own passwords? \(**/ char fd_gen_pwd; /\(** can user get passwords generated for him? \(**/ char fd_restrict; /\(** should generated passwords be restricted? \(**/ char fd_nullpw; /\(** is user allowed to have a NULL password? \(**/ uid_t fd_pwchanger; /\(** who last changed user's password \(**/ long fd_pw_admin_num;/\(** password generation verifier \(**/ char fd_gen_chars; /\(** can have password of random ASCII? \(**/ char fd_gen_letters; /\(** can have password of random letters? \(**/ char fd_tod[AUTH_TOD_SIZE]; /\(** times when user may login \(**/ .IP /\(** Login parameters: \(**/ time_t fd_slogin; /\(** last successful login \(**/ time_t fd_ulogin; /\(** last unsuccessful login \(**/ char fd_suctty[14]; /\(** tty of last successful login \(**/ short fd_nlogins; /\(** consecutive unsuccessful logins \(**/ char fd_unsuctty[14];/\(** tty of last unsuccessful login \(**/ short fd_max_tries; /\(** maximum unsuc login tries allowed \(**/ char fd_lock; /\(** Unconditionally lock account? \(**/ }; .IP struct pr_flag { unsigned short /\(** Identity: \(**/ fg_name:1, /\(** Is fd_name set? \(**/ fg_uid:1, /\(** Is fd_uid set? \(**/ fg_encrypt:1, /\(** Is fd_encrypt set? \(**/ fg_owner:1, /\(** Is fd_owner set? \(**/ fg_boot_auth:1, /\(** Is fd_boot_auth set? \(**/ fg_pw_audid:1, /\(** Is fd_auditcntl set? \(**/ fg_pw_audflg:1, /\(** Is fd_auditdisp set? \(**/ .IP /\(** Password maintenance parameters: \(**/ fg_min:1, /\(** Is fd_min set? \(**/ fg_maxlen:1, /\(** Is fd_maxlen set? \(**/ fg_expire:1, /\(** Is fd_expire set? \(**/ fg_lifetime:1, /\(** Is fd_lifetime set? \(**/ fg_schange:1, /\(** Is fd_schange set? \(**/ fg_uchange:1, /\(** Is fd_fchange set? \(**/ fg_acct_expire:1, /\(** Is fd_acct_expire set? \(**/ fg_max_llogin:1, /\(** Is fd_max_llogin set? \(**/ fg_pw_expire_warning:1, /\(** Is fd_pw_expire_warning set? \(**/ fg_pswduser:1, /\(** Is fd_pswduser set? \(**/ fg_pick_pwd:1, /\(** Is fd_pick_pwd set? \(**/ fg_gen_pwd:1, /\(** Is fd_gen_pwd set? \(**/ fg_restrict:1, /\(** Is fd_restrict set? \(**/ fg_nullpw:1, /\(** Is fd_nullpw set? \(**/ fg_pwchanger:1, /\(** Is fd_pwchanger set? \(**/ fg_pw_admin_num:1, /\(** Is fd_pw_admin_num set? \(**/ fg_gen_chars:1, /\(** Is fd_gen_chars set? \(**/ fg_gen_letters:1, /\(** Is fd_gen_letters set? \(**/ fg_tod:1, /\(** Is fd_tod set? \(**/ .IP /\(** Login parameters: \(**/ fg_slogin:1, /\(** Is fd_slogin set? \(**/ fg_suctty: 1, /\(** is fd_suctty set ? \(**/ fg_unsuctty: 1, /\(** is fd_unsuctty set ? \(**/ fg_ulogin:1, /\(** Is fd_ulogin set? \(**/ fg_nlogins:1, /\(** Is fd_nlogins set? \(**/ fg_max_tries:1, /\(** Is fd_max_tries set? \(**/ fg_lock:1; /\(** Is fd_lock set? \(**/ }; .IP struct pr_passwd { struct pr_field ufld; /\(** user specific fields \(**/ struct pr_flag uflg; /\(** user specific flags \(**/ struct pr_field sfld; /\(** system wide fields \(**/ struct pr_flag sflg; /\(** system wide flags \(**/ }; .fi .PP The protected password database stores user authentication profiles. The .C pr_passwd structure in the user-specific entry refers to parameters specific to a user. The .C pr_passwd structure in the system default database sets parameters that are used when there is no user-specific override. .PP The user-specific entry is keyed on the .I fd_name field, which is a cross reference to the .C /etc/passwd entry for the user. The .I fd_uid field must match the UID in that file as well. The .I fd_encrypt field is the encrypted password. The password is encrypted in eight character segments, so the size of this field is a multiple of the number of characters in an encrypted segment (\c .C AUTH_CIPHERTEXT_SIZE macro). .PP .I fd_owner is the user name accountable for the account. \c The .I fd_boot_auth field is used when the system default file specifies boot authorization is required. .I init(1M) prompts for a user name and password. If the authentication succeeds, a value in this field allows the user to continue the system boot process. \c .PP .I fd_min is the time, in seconds, that must elapse before the user can change passwords. .I fd_maxlen is the maximum password length (in characters) for the user. .I fd_expire is the time, in seconds, until the user's password expires. .I fd_lifetime is the number of seconds that must elapse before the password dies. The account is considered locked if the password is dead. .PP .I fd_schange and .I fd_uchange record the last successful and unsuccessful password change times. .PP The .I fd_acct_expire field specifies the absolute period of time in seconds that the account can be used. An absolute expiration date may be specified, which is then converted into seconds stored in this field. This is different from .I fd_expire in that .I fd_acct_expire specifies an absolute expiration date, while .I fd_expire is reset with each password change. .PP .I fd_max_llogin specifies the maximum time in seconds allowed since the last login before the account becomes locked. .I fd_pw_expire_warning is the time in seconds before the end of .I fd_expire that the system warns the user the password is about to expire. .I fd_pswduser stores the user ID of the user allowed to change passwords for the account. \c Typically, this is the account owner. \c .PP The next flag fields control password generation. .IR fd_pick_pwd , if set, allows the user to pick his or her own password. .IR fd_nullpw , if set, allows the account to be used without a password. .I fd_gen_pwd enables the use of the random pronounceable password generator for passwords for this account. .I fd_gen_chars and .I fd_gen_letters allow the password generator to generate passwords composed of random printable characters and random letters, neither of which is easy to remember. The password change software allows the user to pick from whichever options are available for his or her account. One of these three fields .RI ( fd_gen_pwd , .IR fd_gen_chars , or .IR fd_gen_letters ) must be set. .PP .I fd_pwchanger is the user ID of the user who last changed the password on the user's account, if it was not the account owner. .IR fd_restrict , if set, causes triviality checks to be made after the account password has been chosen to avoid palindromes, user name and machine name permutations, and words appearing in the dictionary. .PP The .I fd_tod specifier is a string, formatted like the UUCP .C Systems file, which specifies time intervals during which the user can log in. \c .PP The next fields are used to protect against login spoofing, listing the time and location of last login. .I fd_slogin and .I fd_ulogin are time stamps of the last successful and unsuccessful login attempts. .I fd_suctty and .I fd_unsuctty are the terminal device or (if supported) host names of the terminal or host from which the last login attempt occurred. .PP .I fd_nlogins is the number of unsuccessful login attempts since the last successful login. It is reset to zero after a successful login. .I fd_max_tries is the number of unsuccessful attempts until the account is considered locked. .PP .I fd_lock indicates whether the administrative lock on the account is set. The account is considered disabled (locked) if one or more of these activities has occurred: .PD 0 .PP 1. if the password is dead, .PP 2. if the maximum number of unsuccessful attempts has been exceeded, .PP 3. if the administrative lock is set, .PP 4. if the account expiration is reached, or .PP 5. if the time since last login is exceeded. .PD .PP When .CR getprpwent () is first called, it returns a pointer to the first user .C pr_passwd structure in the database; thereafter, it returns a pointer to the next .C pr_passwd structure in the database so that successive calls can be used to search the database. Note that entries without a corresponding entry in .C /etc/passwd are skipped. The entries are scanned in the order they appear in .CR /etc/passwd . .PP .CR getprpwuid () searches from the beginning of the database until a numerical user ID matching .I uid is found and returns a pointer to the particular structure in which it was found. \c .CR getprpwaid () functions like .CR getprpwuid () only it uses the audit ID instead of the uid. \c .PP .CR getprpwnam () searches from the beginning of the database until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a NULL pointer. .PP A call to .CR setprpwent () has the effect of rewinding the protected password database to allow repeated searches. .CR endprpwent () can be called to close the protected password database when processing is complete. .PP .CR putprpwnam () puts a new or replaced protected password entry .I pr with key .I name into the database. If the .I uflg.fg_name field is 0, the requested entry is deleted from the protected password database. .CR putprpwnam () locks the database for all update operations, and performs a .CR endprpwent () after the update or failed attempt. .SS Notes .PP The value returned by .CR getprpwent () and .CR getprpwnam () refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .CR putprpwnam (). .PP On systems supporting network connections, the .I fd_suctty and .I fd_unsuctty fields can be the ASCII representation of the network address of the host from which the last successful or unsuccessful remote login to the account occurred. Use .IR getdvagnam (3) to investigate the type of device to determine whether a host or a terminal was used for the last successful or unsuccessful login. .PP Programs using these routines must be compiled with .CR \-lsec . .PP .CR getprpwent () assumes one name per UID and one UID per name. The sequential scan loops between the first two instances of a multiple UID. .PP .CR getprpwent () uses .IR getpwent (3) routines to sequentially scan databases. User program references to password entries obtained using .IR getpwent (3) routines will not be valid after using any routines described here (ie., the * .CR prp * routines). .SH RETURN VALUE .CR getprpwent (), .CR getprpwuid (), and .CR getprpwnam () return NULL pointers on EOF or error. .CR putprpwnam () returns 0 if it cannot add or update the entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 35 .C /etc/passwd System Password file .PD 0 .TP .C /tcb/files/auth/\(**/\(** Protected Password database .TP .C /tcb/files/auth/system/default System Defaults database .PD .SH SEE ALSO authcap(4), getpwent(3), getprdfent(3), prpwd(4). .\" .\" index@\f4getprpwuid\f1 \- get protected password database user ID@@@\f3getprpwent(3)\f1 .\" index@\f4getprpwaid\f1 \- get protected password database audit ID@@@\f3getprpwent(3)\f1 .\" index@\f4getprpwnam\f1 \- get protected password database user name@@@\f3getprpwent(3)\f1 .\" index@\f4setprpwent\f1 \- set protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f4endprpwent\f1 \- manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f4putprpwnam\f1 \- manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1access protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1protected password database entry, manipulate@@@\f3getprpwent(3)\f1 .\" index@\f1password database entry, manipulate protected@@@\f3getprpwent(3)\f1 .\" index@\f1database entry, manipulate protected password@@@\f3getprpwent(3)\f1 .\" index@\f1entry, manipulate protected password database@@@\f3getprpwent(3)\f1 .\" .\" toc@\f3getprpwent(3)\f1:\0\0\f4getprpwent\f1, \f4getprpwuid\f1, \f4getprpwnam\f1, \f4getprpwaid\f1, \f4setprpwent\f1,\n\f4endprpwent\f1, \f4putprpwnam\f1@@@manipulate protected password database entry .\" toc@\f4getprpwuid\f1:\0\0get protected password database user ID@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4getprpwaid\f1:\0\0get protected password database audit ID@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4getprpwnam\f1:\0\0get protected password database user name@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4setprpwent\f1:\0\0set protected password database entry@@@\f1 see \f3getprpwent(3)\f1 .\" toc@\f4endprpwent\f1:\0\0manipulate protected password database entry@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4putprpwnam\f1:\0\0manipulate protected password database entry@@@\f1 see \f3getprpwent(3)\f1 .\" .\" links@getprpwent.3 getprpwuid.3 .\" links@getprpwent.3 getprpwnam.3 .\" links@getprpwent.3 setprpwent.3 .\" links@getprpwent.3 endprpwent.3 .\" links@getprpwent.3 putprpwnam.3 .\" links@getprpwent.3 getprpwaid.3 .\" .\" $Header: getprtcent.3,v 78.2 96/01/19 20:15:15 ssa Exp $ .TA g .TH getprtcent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprtcent, getprtcnam, setprtcent, endprtcent, putprtcnam \- manipulate terminal control database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct pr_term \(**getprtcent(void);" .PP .CR "struct pr_term \(**getprtcnam(const char \(**name);" .PP .CR "void setprtcent(void);" .PP .CR "void endprtcent(void);" .PP .CR "int putprtcnam(const char \(**name, struct pr_term \(**pr);" .fi .SH DESCRIPTION .IR getprtcent and .I getprtcnam each returns a pointer to an object with the following structure containing the broken-out fields of an entry in the terminal control database. Each entry in the database contains a .I pr_term structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v .ift .ta 2i .ifn .ta 3i .ne 15 struct t_field { char fd_devname[14]; /* Terminal (or host) name */ uid_t fd_uid; /* uid of last successful login */ time_t fd_slogin; /* time stamp of successful login */ uid_t fd_uuid; /* uid of last unsuccessful login */ time_t fd_ulogin; /* time stamp of unsuccessful login */ ushort fd_nlogins; /* consecutive failed attempts */ ushort fd_max_tries; /* maximum unsuc login tries allowed */ time_t fd_logdelay; /* delay between login tries */ char fd_lock; /* terminal locked? */ ushort fd_login_timeout ; /* login timeout in seconds */ }; .IP .ne 17 struct t_flag { unsigned short fg_devname:1, /* Is fd_devname set? */ fg_uid:1, /* Is fd_uid set? */ fg_slogin:1, /* Is fd_stime set? */ fg_uuid:1, /* Is fd_uuid set? */ fg_ulogin:1, /* Is fd_ftime set? */ fg_nlogins:1, /* Is fd_nlogins set? */ fg_max_tries:1, /* Is fd_max_tries set? */ fg_logdelay:1, /* Is fd_logdelay set? */ fg_lock:1, /* Is fd_lock set? */ fg_login_timeout:1 /* is fd_login_timeout valid? */ ; }; .IP .ne 6 struct pr_term { struct t_field ufld; struct t_flag uflg; struct t_field sfld; struct t_flag sflg; }; .fi .DT .PP The system stores the user ID and time of the last successful login ( .I fd_uid and .I fd_slogin ) and unsuccessful login ( .I fd_uuid and .I fd_ulogin ) in the appropriate Terminal Control database entry. The system increments .I fd_nlogins with each unsuccessful login, and resets the field to 0 on a successful login. The .I fd_max_tries field is a limit on the number of unsuccessful logins until the account is locked. An administrative lock can also be applied, indicated by a non-zero .I fd_lock field. .I fd_logdelay stores the amount of time (in seconds) that the system waits between unsuccessful login attempts, and .I fd_login_timeout stores the number of seconds from the beginning of an authentication attempt until the login attempt is terminated. .PP Note that .I ufld and .I uflg refer to user specific entries, and .I sfld and .I sflg refer to the system default values (see .IR authcap (4)). .PP The value returned by .I getprtcent or .I getprtcnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .IR putprtcnam . .PP .I getprtcent returns a pointer to the first terminal .I pr_term structure in the database when first called. Thereafter, it returns a pointer to the next .I pr_term structure in the database, so successive calls can be used to search the database. .I getprtcnam searches from the beginning of the database until a terminal name matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a .B NULL pointer. .PP A call to .I setprtcent has the effect of rewinding the Terminal Control database to allow repeated searches. .I endprtcent can be called to close the Terminal Control database when processing is complete. .PP .I putprtcnam puts a new or replaced terminal control entry .I pr with key .I name into the database. If the .I fg_devname field is 0, the requested entry is deleted from the Terminal Control database. .I putprtcnam locks the database for all update operations, and performs an .I endprtcent after the update or failed attempt. .SH RETURN VALUE .I getprtcent and .I getprtcnam return .SM .B NULL pointers on .SM EOF or error. .I putprtcnam returns 0 if it cannot add or update the entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 45 .C /tcb/files/ttys Terminal Control database .PD 0 .TP .C /tcb/files/auth/system/default System Defaults database .PD .SH SEE ALSO getprdfent(3), authcap(4), ttys(4). .SH NOTES The .I fd_devname field, on systems supporting connections, may refer to the .SM ASCII representation of a host name. This can be determined by using .IR getdvagnam (3) to interrogate the Device Assignment database as to the type of the device, passing in the .I fd_devname field of the Terminal Control structure as an argument. This allows lockout by machine, instead of the device (typically pseudo tty) on which the session originated. .PP Programs using these routines must be compiled with .BR \-lsec . .PP The .I sfld and .I sflg structures are filled from corresponding fields in the system default database. Thus, a program can easily extract the user-specific or system-wide parameters for each database field (see .I getprpwent and .IR getdvagent ). .\" .\" index@\f4getprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4getprtcnam\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4setprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4endprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4putprtcnam\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f1manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f1terminal control database entry, manipulate@@@\f3getprtcent(3)\f1 .\" index@\f1database entry, manipulate terminal control@@@\f3getprtcent(3)\f1 .\" index@\f1entry, manipulate terminal control database@@@\f3getprtcent(3)\f1 .\" .\" toc@\f3getprtcent(3)\f1:\0\0\f4getprtcent\f1, \f4getprtcnam\f1, \f4setprtcent\f1, \f4endprtcent\f1,\n\f4putprtcnam\f1@@@manipulate terminal control database entry for a trusted system .\" toc@\f4getprtcent\f1:\0\0return pointer to terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc \f4getprtcnam\f1:\0\0search terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4setprtcent\f1:\0\0rewind terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4endprtcent\f1:\0\0close terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4putprtcnam\f1:\0\0put entry into terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" .\" links@getprtcent.3 getprtcnam.3 .\" links@getprtcent.3 setprtcent.3 .\" links@getprtcent.3 endprtcent.3 .\" links@getprtcent.3 putprtcnam.3 .\" .\" $Header: getprtcent.3,v 78.2 96/01/19 20:15:15 ssa Exp $ .TA g .TH getprtcent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprtcent, getprtcnam, setprtcent, endprtcent, putprtcnam \- manipulate terminal control database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct pr_term \(**getprtcent(void);" .PP .CR "struct pr_term \(**getprtcnam(const char \(**name);" .PP .CR "void setprtcent(void);" .PP .CR "void endprtcent(void);" .PP .CR "int putprtcnam(const char \(**name, struct pr_term \(**pr);" .fi .SH DESCRIPTION .IR getprtcent and .I getprtcnam each returns a pointer to an object with the following structure containing the broken-out fields of an entry in the terminal control database. Each entry in the database contains a .I pr_term structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v .ift .ta 2i .ifn .ta 3i .ne 15 struct t_field { char fd_devname[14]; /* Terminal (or host) name */ uid_t fd_uid; /* uid of last successful login */ time_t fd_slogin; /* time stamp of successful login */ uid_t fd_uuid; /* uid of last unsuccessful login */ time_t fd_ulogin; /* time stamp of unsuccessful login */ ushort fd_nlogins; /* consecutive failed attempts */ ushort fd_max_tries; /* maximum unsuc login tries allowed */ time_t fd_logdelay; /* delay between login tries */ char fd_lock; /* terminal locked? */ ushort fd_login_timeout ; /* login timeout in seconds */ }; .IP .ne 17 struct t_flag { unsigned short fg_devname:1, /* Is fd_devname set? */ fg_uid:1, /* Is fd_uid set? */ fg_slogin:1, /* Is fd_stime set? */ fg_uuid:1, /* Is fd_uuid set? */ fg_ulogin:1, /* Is fd_ftime set? */ fg_nlogins:1, /* Is fd_nlogins set? */ fg_max_tries:1, /* Is fd_max_tries set? */ fg_logdelay:1, /* Is fd_logdelay set? */ fg_lock:1, /* Is fd_lock set? */ fg_login_timeout:1 /* is fd_login_timeout valid? */ ; }; .IP .ne 6 struct pr_term { struct t_field ufld; struct t_flag uflg; struct t_field sfld; struct t_flag sflg; }; .fi .DT .PP The system stores the user ID and time of the last successful login ( .I fd_uid and .I fd_slogin ) and unsuccessful login ( .I fd_uuid and .I fd_ulogin ) in the appropriate Terminal Control database entry. The system increments .I fd_nlogins with each unsuccessful login, and resets the field to 0 on a successful login. The .I fd_max_tries field is a limit on the number of unsuccessful logins until the account is locked. An administrative lock can also be applied, indicated by a non-zero .I fd_lock field. .I fd_logdelay stores the amount of time (in seconds) that the system waits between unsuccessful login attempts, and .I fd_login_timeout stores the number of seconds from the beginning of an authentication attempt until the login attempt is terminated. .PP Note that .I ufld and .I uflg refer to user specific entries, and .I sfld and .I sflg refer to the system default values (see .IR authcap (4)). .PP The value returned by .I getprtcent or .I getprtcnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .IR putprtcnam . .PP .I getprtcent returns a pointer to the first terminal .I pr_term structure in the database when first called. Thereafter, it returns a pointer to the next .I pr_term structure in the database, so successive calls can be used to search the database. .I getprtcnam searches from the beginning of the database until a terminal name matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a .B NULL pointer. .PP A call to .I setprtcent has the effect of rewinding the Terminal Control database to allow repeated searches. .I endprtcent can be called to close the Terminal Control database when processing is complete. .PP .I putprtcnam puts a new or replaced terminal control entry .I pr with key .I name into the database. If the .I fg_devname field is 0, the requested entry is deleted from the Terminal Control database. .I putprtcnam locks the database for all update operations, and performs an .I endprtcent after the update or failed attempt. .SH RETURN VALUE .I getprtcent and .I getprtcnam return .SM .B NULL pointers on .SM EOF or error. .I putprtcnam returns 0 if it cannot add or update the entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 45 .C /tcb/files/ttys Terminal Control database .PD 0 .TP .C /tcb/files/auth/system/default System Defaults database .PD .SH SEE ALSO getprdfent(3), authcap(4), ttys(4). .SH NOTES The .I fd_devname field, on systems supporting connections, may refer to the .SM ASCII representation of a host name. This can be determined by using .IR getdvagnam (3) to interrogate the Device Assignment database as to the type of the device, passing in the .I fd_devname field of the Terminal Control structure as an argument. This allows lockout by machine, instead of the device (typically pseudo tty) on which the session originated. .PP Programs using these routines must be compiled with .BR \-lsec . .PP The .I sfld and .I sflg structures are filled from corresponding fields in the system default database. Thus, a program can easily extract the user-specific or system-wide parameters for each database field (see .I getprpwent and .IR getdvagent ). .\" .\" index@\f4getprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4getprtcnam\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4setprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4endprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4putprtcnam\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f1manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f1terminal control database entry, manipulate@@@\f3getprtcent(3)\f1 .\" index@\f1database entry, manipulate terminal control@@@\f3getprtcent(3)\f1 .\" index@\f1entry, manipulate terminal control database@@@\f3getprtcent(3)\f1 .\" .\" toc@\f3getprtcent(3)\f1:\0\0\f4getprtcent\f1, \f4getprtcnam\f1, \f4setprtcent\f1, \f4endprtcent\f1,\n\f4putprtcnam\f1@@@manipulate terminal control database entry for a trusted system .\" toc@\f4getprtcent\f1:\0\0return pointer to terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc \f4getprtcnam\f1:\0\0search terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4setprtcent\f1:\0\0rewind terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4endprtcent\f1:\0\0close terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4putprtcnam\f1:\0\0put entry into terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" .\" links@getprtcent.3 getprtcnam.3 .\" links@getprtcent.3 setprtcent.3 .\" links@getprtcent.3 endprtcent.3 .\" links@getprtcent.3 putprtcnam.3 .\" .\" $Header: publickey.3r,v 72.2 94/08/25 12:42:38 ssa Exp $ .TA p .TH publickey 3R .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME publickey, getpublickey, getsecretkey \- get public or secret key .SH SYNOPSIS .C "#include " .PP .C "#include " .PP .C "getpublickey (netname, publickey)" .PP .C "char netname[MAXNETNAMELEN+1];" .PP .C "char publickey[HEXKEYBYTES+1];" .PP .C "getsecretkey (netname, secretkey, passwd)" .PP .C "char netname[MAXNETNAMELEN+1];" .PP .C "char secretkey[HEXKEYBYTES+1];" .PP .C "char *passwd;" .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These routines are used to get public and secret keys from the NIS .IR publickey (4) database. .PP .CR getsecretkey() has an extra argument, .IR passwd , which is used to decrypt the encrypted secret key stored in the .IR publickey (4) database. .PP Both routines return 1 if they are successful in finding the key; otherwise, these routines return 0. .PP The keys are returned as NULL-terminated, hexadecimal strings. .PP If the password supplied to .CR getsecretkey() fails to decrypt the secret key, the routine will return 1 but the secretkey argument will be a NULL string. .SH AUTHOR The .CR publickey routines were developed by Sun Microsystems, Inc. .SH SEE ALSO publickey(4). .\" .\" index@\f4publickey()\f1, \f4getpublickey()\f1, \f4getsecretkey()\f1 \- get public and secret keys@@@\f3publickey(3R)\f1 .\" index@\f4getpublickey()\f1, \f4publickey()\f1, \f4getsecretkey()\f1 \- get public and secret keys@@@\f3publickey(3R)\f1 .\" index@\f4getsecretkey()\f1, \f4publickey()\f1, \f4getpublickey()\f1 \- get public and secret keys@@@\f3publickey(3R)\f1 .\" .\" index@\f1get, public and secret keys@@@\f3publickey(3R)\f1 .\" index@\f1public keys, get@@@\f3getpublickey(3R)\f1 .\" index@\f1secret keys, get@@@\f3getsecretkey(3R)\f1 .\" .\" toc@\f3publickey(3R)\f1:\0\0\f4publickey()\f1, \f4getpublickey()\f1, \f4getsecretkey\f1@@@get public and secret keys .\" toc@\f4getpublickey()\f1:\0\0get public and secret keys@@@see \f3publickey(3R)\f1 .\" toc@\f4getsecretkey()\f1:\0\0get public and secret keys@@@see \f3publickey(3R)\f1 .\" .\" links@publickey.3r getpublickey.3r .\" links@publickey.3r getsecretkey.3r .\" $Header: getpw.3c,v 72.4 94/11/14 15:29:02 ssa Exp $ .TA g .TH getpw 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpw(\|) \- get name from UID .SH SYNOPSIS .C "#include " .PP .C "int getpw(uid_t uid, char *buf);" .SH DESCRIPTION .C getpw() searches the password file for a user .SM ID number that equals .IR uid , copies the line of the password file in which .I uid was found into the array pointed to by .IR buf , and returns 0. .C getpw() returns non-zero if .I uid cannot be found. The line is null-terminated. .PP This routine is included only for compatibility with prior systems, and should not be used; see .IR getpwent (3C) for routines to use instead. .SH NETWORKING FEATURES .SS \s-1NFS\s0 This routine is implemented using .C getpwuid() (see .IR getpwuid (3C)) and therefore uses the Network Information Service network database as described in .IR passwd (4). .SH RETURN VALUE .C getpw() returns non-zero on error. .SH WARNINGS The above routine uses .RC < stdio.h >, which causes it to increase, more than might be expected, the size of programs not otherwise using standard .SM I/O. .SH AUTHOR .C getpw() was developed by AT&T and HP. .SH FILES /etc/passwd .SH SEE ALSO getpwent(3C), passwd(4). .SH STANDARDS CONFORMANCE .CR getpw() ": XPG2" .\" .\" index@\f4getpw()\fP \- get name from \s-1UID\s+1 (obsolete)@@@\f3getpw(3C)\f1 .\" index@name: get name from \s-1UID\s+1 (obsolete)@@@\f3getpw(3C)\f1 .\" index@\s-1UID\s+1, get name from (obsolete)@@@\f3getpw(3C)\f1 .\" .\" toc@\f3getpw(3C)\f1:\0\0\f4getpw()\fP@@@get name from \s-1UID\s+1 .\" .\" fileset_database@getpw.3c PROGRAMING-MAN .\" $Header: getpwent.3c,v 78.1 95/12/20 10:53:01 ssa Exp $ .TA g .TH getpwent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpwent(\|), getpwent_r(\|), getpwuid(\|), getpwuid_r(\|), getpwnam(\|), getpwnam_r(\|), setpwent(\|), setpwent_r(\|), endpwent(\|), endpwent_r(\|), fgetpwent(\|), fgetpwent_r(\|) \- get password file entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct passwd *getpwent(void);" .PP .C "int getpwent_r(struct passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct passwd *getpwuid(uid_t uid);" .PP .PD 0 .C "int getpwuid_r(uid_t uid, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct passwd *getpwnam(const char *name);" .PP .PD 0 .C "int getpwnam_r(char *name, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setpwent(void);" .PP .C "void setpwent_r(FILE **pwfp);" .PP .C "void endpwent(void);" .PP .C "void endpwent_r(FILE **pwfp);" .PP .C "struct passwd *fgetpwent(FILE *stream);" .PP .C "int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, int buflen);" .fi .SH DESCRIPTION .CR getpwent (), .CR getpwuid (), and .CR getpwnam () locate an entry in the .C /etc/passwd file, and return a pointer to an object of .C passwd structure. .PP The .C passwd structure is defined in .RC < pwd.h > and includes the following members: .nf .IP .CR "char *pw_name; " "/* user name */" .CR "char *pw_passwd; " "/* encrypted password */" .CR "uid_t pw_uid; " "/* user id */" .CR "gid_t pw_gid; " "/* group id */" .CR "char *pw_age; " "/* password aging */" .CR "char *pw_comment;" "/* unused */" .CR "char *pw_gecos; " "/* user fullname, office, extension, homephone*/" .CR "char *pw_dir; " "/* initial directory */" .CR "char *pw_shell; " "/* initial shell */" .CR "aid_t pw_audid; " "/* numerical audit id */" .CR "int pw_audflg; " "/* numerical audit flag */" .fi .PP The .I pw_comment field is unused; for more information on the other fields, refer to .IR passwd (4). .TP 20 .CR getpwent () When first called, .CR getpwent () returns a pointer to the first .C passwd structure in the file. Thereafter, it returns a pointer to the next .C passwd structure in the file. In this way, successive calls can be used to search the entire file. .CR getpwent () opens the .C /etc/passwd file prior to doing its work and leaves the file open afterward; .TP .CR setpwent () Has the effect of rewinding this file to allow repeated searches; .TP .CR endpwent () Can be called to close the file when processing is complete. .TP .CR getpwuid () Searches from the beginning of the file until a numeric user .SM ID matching .I uid is found, and returns a pointer to the particular structure in which it was found. .TP .CR getpwnam () searches from the beginning of the file until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .CR fgetpwent () returns a pointer to the next .C passwd structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/passwd . .SS Reentrant Interfaces .CR getpwuid_r (), .CR getpwnam_r () and .CR fgetpwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .C passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in .C passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getpwent_r () requires a pointer to a .RI ( "FILE *" ) variable into which is stored the result of an .CR fopen () call on the .C /etc/passwd file. This is to allow threads to independently scan through the .C /etc/passwd file. .CR setpwent_r () and .CR endpwent_r () are to be used only in conjunction with .CR getpwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setpwent_r () can be used to rewind or open the .C /etc/passwd file. .CR endpwent_r () must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getpwent_r () or .CR setpwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH SECURITY FEATURES If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default .CR * that is in .C /etc/passwd and the audit ID and audit flag will be set to \(mi1. On trusted systems, if it is not necessary to obtain information from the regular password file, .CR /etc/passwd , users should use .CR getprpwent () to access the protected password database. See .IR getprpwent (3) and .IR getspwent (3X). .PP .CR putpwent () affects only .CR /etc/passwd ; the audit .SM ID and audit flag in the password structure are ignored. .CR putprpwnam () must be used to modify the protected password databse entries. See .IR getprpwent (3). .SH NETWORKING FEATURES .SS \s-1NFS\s0 If an entry beginning with a plus sign .RC ( + ) or a minus sign .RB ( \(mi ) is found, these routines try to use the Network Information Service network database for data. See .IR passwd (4) for proper syntax and operation. .PP Network Information Service (NIS) is not supported on trusted systems. .SH RETURN VALUE .CR getpwent (), .CR getpwuid (), .CR getpwnam (), and .CR fgetpwent () return a .SM NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .C passwd structure. .PP .CR getpwent_r (), .CR getpwuid_r (), .CR getpwnam_r (), and .CR fgetpwent_r (), return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getpwent() , .CR getpwuid() , and .CR fgetpwent() fail if any of the following are true: .RS .TP 15 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library, which causes them to increase the size of programs, not otherwise using standard .SM I/O and Network Information Service, more than might be expected. .PP The value returned by .CR getpwent() , .CR getpwuid() , .CR getpwnam() , and .C fgetpwent() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved. .PP .CR getpwent() , .CR getpwuid() , .CR getpwnam() , .CR setpwent() , .CR endpwent() , and .C fgetpwent() are unsafe in multi-thread applications. .CR getpwent_r() , .CR getpwuid_r() , .CR getpwnam_r() , .CR setpwent_r() , .CR endpwent_r() , and .C fgetpwent_r() are MT-Safe and should be used instead. .PP The following fields have numerical limitations as noted: .RS .TP 3 \(bu The user ID is an integer value between -2 and UID_MAX inclusive. .TP \(bu The group ID is an integer value between 0 and UID_MAX inclusive. .RE .PP Users of .CR getpwnam_r() and .CR getpwuid_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH EXAMPLE The following code excerpt counts the number of entries in the .C /etc/passwd file: .PP .nf .IP .C "int count = 0;" .C "struct passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setpwent_r(&pwf);" .C "while (getpwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endpwent_r(&pwf);" .fi .SH DEPENDENCIES .SS \s-1NFS\s0 .B Files: .RS .CI /var/yp/ domainname /passwd.byname .br .CI /var/yp/ domainname /passwd.byuid .RE .PP .B See Also: .RS ypcat(1). .RE .SH AUTHOR .CR getpwent (), .CR getpwuid (), .CR getpwnam (), .CR setpwent (), .CR endpwent (), and .CR fgetpwent () were developed by AT&T and HP. .SH FILES .TP 30 .C /etc/passwd System Password file .SH SEE ALSO ypcat(1), cuserid(3S), getgrent(3C), getlogin(3C), getprpwent(3), getspwent(3X), stdio(3S), putpwent(3C), putspwent(3X), passwd(4), limits(5). .SH STANDARDS CONFORMANCE .CR getpwent() ": SVID2, SVID3, XPG2" .PP .CR endpwent() ": SVID2, SVID3, XPG2" .PP .CR fgetpwent() ": SVID2, SVID3, XPG2" .PP .CR getpwnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpwuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setpwent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getpwent()\f1 \- get next password file entry@@@\f3getpwent(3C)\f1 .\" index@\f4fgetpwent()\f1 \- get next entry in password-file-formatted input stream@@@\f3getpwent(3C)\f1 .\" index@\f4getpwuid()\f1 \- get password file entry matching \f4uid()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4getpwnam()\f1 \- get password file entry matching login name \f4name()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4setpwent()\f1 \- rewind pointer to beginning of password file@@@\f3getpwent(3C)\f1 .\" index@\f4endpwent()\f1 \- close currently open password file@@@\f3getpwent(3C)\f1 .\" index@entry from password file, get@@@\f3getpwent(3C)\f1 .\" index@password file, get entry from@@@\f3getpwent(3C)\f1 .\" index@file, password: get entry from password file@@@\f3getpwent(3C)\f1 .\" .\" toc@\f3getpwent(3C)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f , \f4endpwent()\f1, \n\f4fgetpwent()\f1@@@get password file entry .\" toc@\f4getpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4setpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4endpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" .\" links@getpwent.3c getpwuid.3c .\" links@getpwent.3c getpwnam.3c .\" links@getpwent.3c setpwent.3c .\" links@getpwent.3c endpwent.3c .\" links@getpwent.3c fgetpwent.3c .\" links@getpwent.3c getpwent_r.3c .\" links@getpwent.3c getpwuid_r.3c .\" links@getpwent.3c getpwnam_r.3c .\" links@getpwent.3c setpwent_r.3c .\" links@getpwent.3c endpwent_r.3c .\" links@getpwent.3c fgetpwent_r.3c .\" .\" fileset_database@getpwent.3c PROGRAMING-MAN .\" $Header: getpwent.3c,v 78.1 95/12/20 10:53:01 ssa Exp $ .TA g .TH getpwent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpwent(\|), getpwent_r(\|), getpwuid(\|), getpwuid_r(\|), getpwnam(\|), getpwnam_r(\|), setpwent(\|), setpwent_r(\|), endpwent(\|), endpwent_r(\|), fgetpwent(\|), fgetpwent_r(\|) \- get password file entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct passwd *getpwent(void);" .PP .C "int getpwent_r(struct passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct passwd *getpwuid(uid_t uid);" .PP .PD 0 .C "int getpwuid_r(uid_t uid, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct passwd *getpwnam(const char *name);" .PP .PD 0 .C "int getpwnam_r(char *name, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setpwent(void);" .PP .C "void setpwent_r(FILE **pwfp);" .PP .C "void endpwent(void);" .PP .C "void endpwent_r(FILE **pwfp);" .PP .C "struct passwd *fgetpwent(FILE *stream);" .PP .C "int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, int buflen);" .fi .SH DESCRIPTION .CR getpwent (), .CR getpwuid (), and .CR getpwnam () locate an entry in the .C /etc/passwd file, and return a pointer to an object of .C passwd structure. .PP The .C passwd structure is defined in .RC < pwd.h > and includes the following members: .nf .IP .CR "char *pw_name; " "/* user name */" .CR "char *pw_passwd; " "/* encrypted password */" .CR "uid_t pw_uid; " "/* user id */" .CR "gid_t pw_gid; " "/* group id */" .CR "char *pw_age; " "/* password aging */" .CR "char *pw_comment;" "/* unused */" .CR "char *pw_gecos; " "/* user fullname, office, extension, homephone*/" .CR "char *pw_dir; " "/* initial directory */" .CR "char *pw_shell; " "/* initial shell */" .CR "aid_t pw_audid; " "/* numerical audit id */" .CR "int pw_audflg; " "/* numerical audit flag */" .fi .PP The .I pw_comment field is unused; for more information on the other fields, refer to .IR passwd (4). .TP 20 .CR getpwent () When first called, .CR getpwent () returns a pointer to the first .C passwd structure in the file. Thereafter, it returns a pointer to the next .C passwd structure in the file. In this way, successive calls can be used to search the entire file. .CR getpwent () opens the .C /etc/passwd file prior to doing its work and leaves the file open afterward; .TP .CR setpwent () Has the effect of rewinding this file to allow repeated searches; .TP .CR endpwent () Can be called to close the file when processing is complete. .TP .CR getpwuid () Searches from the beginning of the file until a numeric user .SM ID matching .I uid is found, and returns a pointer to the particular structure in which it was found. .TP .CR getpwnam () searches from the beginning of the file until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .CR fgetpwent () returns a pointer to the next .C passwd structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/passwd . .SS Reentrant Interfaces .CR getpwuid_r (), .CR getpwnam_r () and .CR fgetpwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .C passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in .C passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getpwent_r () requires a pointer to a .RI ( "FILE *" ) variable into which is stored the result of an .CR fopen () call on the .C /etc/passwd file. This is to allow threads to independently scan through the .C /etc/passwd file. .CR setpwent_r () and .CR endpwent_r () are to be used only in conjunction with .CR getpwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setpwent_r () can be used to rewind or open the .C /etc/passwd file. .CR endpwent_r () must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getpwent_r () or .CR setpwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH SECURITY FEATURES If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default .CR * that is in .C /etc/passwd and the audit ID and audit flag will be set to \(mi1. On trusted systems, if it is not necessary to obtain information from the regular password file, .CR /etc/passwd , users should use .CR getprpwent () to access the protected password database. See .IR getprpwent (3) and .IR getspwent (3X). .PP .CR putpwent () affects only .CR /etc/passwd ; the audit .SM ID and audit flag in the password structure are ignored. .CR putprpwnam () must be used to modify the protected password databse entries. See .IR getprpwent (3). .SH NETWORKING FEATURES .SS \s-1NFS\s0 If an entry beginning with a plus sign .RC ( + ) or a minus sign .RB ( \(mi ) is found, these routines try to use the Network Information Service network database for data. See .IR passwd (4) for proper syntax and operation. .PP Network Information Service (NIS) is not supported on trusted systems. .SH RETURN VALUE .CR getpwent (), .CR getpwuid (), .CR getpwnam (), and .CR fgetpwent () return a .SM NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .C passwd structure. .PP .CR getpwent_r (), .CR getpwuid_r (), .CR getpwnam_r (), and .CR fgetpwent_r (), return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getpwent() , .CR getpwuid() , and .CR fgetpwent() fail if any of the following are true: .RS .TP 15 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library, which causes them to increase the size of programs, not otherwise using standard .SM I/O and Network Information Service, more than might be expected. .PP The value returned by .CR getpwent() , .CR getpwuid() , .CR getpwnam() , and .C fgetpwent() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved. .PP .CR getpwent() , .CR getpwuid() , .CR getpwnam() , .CR setpwent() , .CR endpwent() , and .C fgetpwent() are unsafe in multi-thread applications. .CR getpwent_r() , .CR getpwuid_r() , .CR getpwnam_r() , .CR setpwent_r() , .CR endpwent_r() , and .C fgetpwent_r() are MT-Safe and should be used instead. .PP The following fields have numerical limitations as noted: .RS .TP 3 \(bu The user ID is an integer value between -2 and UID_MAX inclusive. .TP \(bu The group ID is an integer value between 0 and UID_MAX inclusive. .RE .PP Users of .CR getpwnam_r() and .CR getpwuid_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH EXAMPLE The following code excerpt counts the number of entries in the .C /etc/passwd file: .PP .nf .IP .C "int count = 0;" .C "struct passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setpwent_r(&pwf);" .C "while (getpwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endpwent_r(&pwf);" .fi .SH DEPENDENCIES .SS \s-1NFS\s0 .B Files: .RS .CI /var/yp/ domainname /passwd.byname .br .CI /var/yp/ domainname /passwd.byuid .RE .PP .B See Also: .RS ypcat(1). .RE .SH AUTHOR .CR getpwent (), .CR getpwuid (), .CR getpwnam (), .CR setpwent (), .CR endpwent (), and .CR fgetpwent () were developed by AT&T and HP. .SH FILES .TP 30 .C /etc/passwd System Password file .SH SEE ALSO ypcat(1), cuserid(3S), getgrent(3C), getlogin(3C), getprpwent(3), getspwent(3X), stdio(3S), putpwent(3C), putspwent(3X), passwd(4), limits(5). .SH STANDARDS CONFORMANCE .CR getpwent() ": SVID2, SVID3, XPG2" .PP .CR endpwent() ": SVID2, SVID3, XPG2" .PP .CR fgetpwent() ": SVID2, SVID3, XPG2" .PP .CR getpwnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpwuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setpwent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getpwent()\f1 \- get next password file entry@@@\f3getpwent(3C)\f1 .\" index@\f4fgetpwent()\f1 \- get next entry in password-file-formatted input stream@@@\f3getpwent(3C)\f1 .\" index@\f4getpwuid()\f1 \- get password file entry matching \f4uid()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4getpwnam()\f1 \- get password file entry matching login name \f4name()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4setpwent()\f1 \- rewind pointer to beginning of password file@@@\f3getpwent(3C)\f1 .\" index@\f4endpwent()\f1 \- close currently open password file@@@\f3getpwent(3C)\f1 .\" index@entry from password file, get@@@\f3getpwent(3C)\f1 .\" index@password file, get entry from@@@\f3getpwent(3C)\f1 .\" index@file, password: get entry from password file@@@\f3getpwent(3C)\f1 .\" .\" toc@\f3getpwent(3C)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f , \f4endpwent()\f1, \n\f4fgetpwent()\f1@@@get password file entry .\" toc@\f4getpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4setpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4endpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" .\" links@getpwent.3c getpwuid.3c .\" links@getpwent.3c getpwnam.3c .\" links@getpwent.3c setpwent.3c .\" links@getpwent.3c endpwent.3c .\" links@getpwent.3c fgetpwent.3c .\" links@getpwent.3c getpwent_r.3c .\" links@getpwent.3c getpwuid_r.3c .\" links@getpwent.3c getpwnam_r.3c .\" links@getpwent.3c setpwent_r.3c .\" links@getpwent.3c endpwent_r.3c .\" links@getpwent.3c fgetpwent_r.3c .\" .\" fileset_database@getpwent.3c PROGRAMING-MAN .\" $Header: getpwent.3c,v 78.1 95/12/20 10:53:01 ssa Exp $ .TA g .TH getpwent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpwent(\|), getpwent_r(\|), getpwuid(\|), getpwuid_r(\|), getpwnam(\|), getpwnam_r(\|), setpwent(\|), setpwent_r(\|), endpwent(\|), endpwent_r(\|), fgetpwent(\|), fgetpwent_r(\|) \- get password file entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct passwd *getpwent(void);" .PP .C "int getpwent_r(struct passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct passwd *getpwuid(uid_t uid);" .PP .PD 0 .C "int getpwuid_r(uid_t uid, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct passwd *getpwnam(const char *name);" .PP .PD 0 .C "int getpwnam_r(char *name, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setpwent(void);" .PP .C "void setpwent_r(FILE **pwfp);" .PP .C "void endpwent(void);" .PP .C "void endpwent_r(FILE **pwfp);" .PP .C "struct passwd *fgetpwent(FILE *stream);" .PP .C "int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, int buflen);" .fi .SH DESCRIPTION .CR getpwent (), .CR getpwuid (), and .CR getpwnam () locate an entry in the .C /etc/passwd file, and return a pointer to an object of .C passwd structure. .PP The .C passwd structure is defined in .RC < pwd.h > and includes the following members: .nf .IP .CR "char *pw_name; " "/* user name */" .CR "char *pw_passwd; " "/* encrypted password */" .CR "uid_t pw_uid; " "/* user id */" .CR "gid_t pw_gid; " "/* group id */" .CR "char *pw_age; " "/* password aging */" .CR "char *pw_comment;" "/* unused */" .CR "char *pw_gecos; " "/* user fullname, office, extension, homephone*/" .CR "char *pw_dir; " "/* initial directory */" .CR "char *pw_shell; " "/* initial shell */" .CR "aid_t pw_audid; " "/* numerical audit id */" .CR "int pw_audflg; " "/* numerical audit flag */" .fi .PP The .I pw_comment field is unused; for more information on the other fields, refer to .IR passwd (4). .TP 20 .CR getpwent () When first called, .CR getpwent () returns a pointer to the first .C passwd structure in the file. Thereafter, it returns a pointer to the next .C passwd structure in the file. In this way, successive calls can be used to search the entire file. .CR getpwent () opens the .C /etc/passwd file prior to doing its work and leaves the file open afterward; .TP .CR setpwent () Has the effect of rewinding this file to allow repeated searches; .TP .CR endpwent () Can be called to close the file when processing is complete. .TP .CR getpwuid () Searches from the beginning of the file until a numeric user .SM ID matching .I uid is found, and returns a pointer to the particular structure in which it was found. .TP .CR getpwnam () searches from the beginning of the file until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .CR fgetpwent () returns a pointer to the next .C passwd structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/passwd . .SS Reentrant Interfaces .CR getpwuid_r (), .CR getpwnam_r () and .CR fgetpwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .C passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in .C passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getpwent_r () requires a pointer to a .RI ( "FILE *" ) variable into which is stored the result of an .CR fopen () call on the .C /etc/passwd file. This is to allow threads to independently scan through the .C /etc/passwd file. .CR setpwent_r () and .CR endpwent_r () are to be used only in conjunction with .CR getpwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setpwent_r () can be used to rewind or open the .C /etc/passwd file. .CR endpwent_r () must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getpwent_r () or .CR setpwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH SECURITY FEATURES If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default .CR * that is in .C /etc/passwd and the audit ID and audit flag will be set to \(mi1. On trusted systems, if it is not necessary to obtain information from the regular password file, .CR /etc/passwd , users should use .CR getprpwent () to access the protected password database. See .IR getprpwent (3) and .IR getspwent (3X). .PP .CR putpwent () affects only .CR /etc/passwd ; the audit .SM ID and audit flag in the password structure are ignored. .CR putprpwnam () must be used to modify the protected password databse entries. See .IR getprpwent (3). .SH NETWORKING FEATURES .SS \s-1NFS\s0 If an entry beginning with a plus sign .RC ( + ) or a minus sign .RB ( \(mi ) is found, these routines try to use the Network Information Service network database for data. See .IR passwd (4) for proper syntax and operation. .PP Network Information Service (NIS) is not supported on trusted systems. .SH RETURN VALUE .CR getpwent (), .CR getpwuid (), .CR getpwnam (), and .CR fgetpwent () return a .SM NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .C passwd structure. .PP .CR getpwent_r (), .CR getpwuid_r (), .CR getpwnam_r (), and .CR fgetpwent_r (), return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getpwent() , .CR getpwuid() , and .CR fgetpwent() fail if any of the following are true: .RS .TP 15 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library, which causes them to increase the size of programs, not otherwise using standard .SM I/O and Network Information Service, more than might be expected. .PP The value returned by .CR getpwent() , .CR getpwuid() , .CR getpwnam() , and .C fgetpwent() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved. .PP .CR getpwent() , .CR getpwuid() , .CR getpwnam() , .CR setpwent() , .CR endpwent() , and .C fgetpwent() are unsafe in multi-thread applications. .CR getpwent_r() , .CR getpwuid_r() , .CR getpwnam_r() , .CR setpwent_r() , .CR endpwent_r() , and .C fgetpwent_r() are MT-Safe and should be used instead. .PP The following fields have numerical limitations as noted: .RS .TP 3 \(bu The user ID is an integer value between -2 and UID_MAX inclusive. .TP \(bu The group ID is an integer value between 0 and UID_MAX inclusive. .RE .PP Users of .CR getpwnam_r() and .CR getpwuid_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH EXAMPLE The following code excerpt counts the number of entries in the .C /etc/passwd file: .PP .nf .IP .C "int count = 0;" .C "struct passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setpwent_r(&pwf);" .C "while (getpwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endpwent_r(&pwf);" .fi .SH DEPENDENCIES .SS \s-1NFS\s0 .B Files: .RS .CI /var/yp/ domainname /passwd.byname .br .CI /var/yp/ domainname /passwd.byuid .RE .PP .B See Also: .RS ypcat(1). .RE .SH AUTHOR .CR getpwent (), .CR getpwuid (), .CR getpwnam (), .CR setpwent (), .CR endpwent (), and .CR fgetpwent () were developed by AT&T and HP. .SH FILES .TP 30 .C /etc/passwd System Password file .SH SEE ALSO ypcat(1), cuserid(3S), getgrent(3C), getlogin(3C), getprpwent(3), getspwent(3X), stdio(3S), putpwent(3C), putspwent(3X), passwd(4), limits(5). .SH STANDARDS CONFORMANCE .CR getpwent() ": SVID2, SVID3, XPG2" .PP .CR endpwent() ": SVID2, SVID3, XPG2" .PP .CR fgetpwent() ": SVID2, SVID3, XPG2" .PP .CR getpwnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpwuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setpwent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getpwent()\f1 \- get next password file entry@@@\f3getpwent(3C)\f1 .\" index@\f4fgetpwent()\f1 \- get next entry in password-file-formatted input stream@@@\f3getpwent(3C)\f1 .\" index@\f4getpwuid()\f1 \- get password file entry matching \f4uid()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4getpwnam()\f1 \- get password file entry matching login name \f4name()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4setpwent()\f1 \- rewind pointer to beginning of password file@@@\f3getpwent(3C)\f1 .\" index@\f4endpwent()\f1 \- close currently open password file@@@\f3getpwent(3C)\f1 .\" index@entry from password file, get@@@\f3getpwent(3C)\f1 .\" index@password file, get entry from@@@\f3getpwent(3C)\f1 .\" index@file, password: get entry from password file@@@\f3getpwent(3C)\f1 .\" .\" toc@\f3getpwent(3C)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f , \f4endpwent()\f1, \n\f4fgetpwent()\f1@@@get password file entry .\" toc@\f4getpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4setpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4endpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" .\" links@getpwent.3c getpwuid.3c .\" links@getpwent.3c getpwnam.3c .\" links@getpwent.3c setpwent.3c .\" links@getpwent.3c endpwent.3c .\" links@getpwent.3c fgetpwent.3c .\" links@getpwent.3c getpwent_r.3c .\" links@getpwent.3c getpwuid_r.3c .\" links@getpwent.3c getpwnam_r.3c .\" links@getpwent.3c setpwent_r.3c .\" links@getpwent.3c endpwent_r.3c .\" links@getpwent.3c fgetpwent_r.3c .\" .\" fileset_database@getpwent.3c PROGRAMING-MAN .\" $Header: getpwent.3c,v 78.1 95/12/20 10:53:01 ssa Exp $ .TA g .TH getpwent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpwent(\|), getpwent_r(\|), getpwuid(\|), getpwuid_r(\|), getpwnam(\|), getpwnam_r(\|), setpwent(\|), setpwent_r(\|), endpwent(\|), endpwent_r(\|), fgetpwent(\|), fgetpwent_r(\|) \- get password file entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct passwd *getpwent(void);" .PP .C "int getpwent_r(struct passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct passwd *getpwuid(uid_t uid);" .PP .PD 0 .C "int getpwuid_r(uid_t uid, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct passwd *getpwnam(const char *name);" .PP .PD 0 .C "int getpwnam_r(char *name, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setpwent(void);" .PP .C "void setpwent_r(FILE **pwfp);" .PP .C "void endpwent(void);" .PP .C "void endpwent_r(FILE **pwfp);" .PP .C "struct passwd *fgetpwent(FILE *stream);" .PP .C "int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, int buflen);" .fi .SH DESCRIPTION .CR getpwent (), .CR getpwuid (), and .CR getpwnam () locate an entry in the .C /etc/passwd file, and return a pointer to an object of .C passwd structure. .PP The .C passwd structure is defined in .RC < pwd.h > and includes the following members: .nf .IP .CR "char *pw_name; " "/* user name */" .CR "char *pw_passwd; " "/* encrypted password */" .CR "uid_t pw_uid; " "/* user id */" .CR "gid_t pw_gid; " "/* group id */" .CR "char *pw_age; " "/* password aging */" .CR "char *pw_comment;" "/* unused */" .CR "char *pw_gecos; " "/* user fullname, office, extension, homephone*/" .CR "char *pw_dir; " "/* initial directory */" .CR "char *pw_shell; " "/* initial shell */" .CR "aid_t pw_audid; " "/* numerical audit id */" .CR "int pw_audflg; " "/* numerical audit flag */" .fi .PP The .I pw_comment field is unused; for more information on the other fields, refer to .IR passwd (4). .TP 20 .CR getpwent () When first called, .CR getpwent () returns a pointer to the first .C passwd structure in the file. Thereafter, it returns a pointer to the next .C passwd structure in the file. In this way, successive calls can be used to search the entire file. .CR getpwent () opens the .C /etc/passwd file prior to doing its work and leaves the file open afterward; .TP .CR setpwent () Has the effect of rewinding this file to allow repeated searches; .TP .CR endpwent () Can be called to close the file when processing is complete. .TP .CR getpwuid () Searches from the beginning of the file until a numeric user .SM ID matching .I uid is found, and returns a pointer to the particular structure in which it was found. .TP .CR getpwnam () searches from the beginning of the file until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .CR fgetpwent () returns a pointer to the next .C passwd structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/passwd . .SS Reentrant Interfaces .CR getpwuid_r (), .CR getpwnam_r () and .CR fgetpwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .C passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in .C passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getpwent_r () requires a pointer to a .RI ( "FILE *" ) variable into which is stored the result of an .CR fopen () call on the .C /etc/passwd file. This is to allow threads to independently scan through the .C /etc/passwd file. .CR setpwent_r () and .CR endpwent_r () are to be used only in conjunction with .CR getpwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setpwent_r () can be used to rewind or open the .C /etc/passwd file. .CR endpwent_r () must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getpwent_r () or .CR setpwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH SECURITY FEATURES If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default .CR * that is in .C /etc/passwd and the audit ID and audit flag will be set to \(mi1. On trusted systems, if it is not necessary to obtain information from the regular password file, .CR /etc/passwd , users should use .CR getprpwent () to access the protected password database. See .IR getprpwent (3) and .IR getspwent (3X). .PP .CR putpwent () affects only .CR /etc/passwd ; the audit .SM ID and audit flag in the password structure are ignored. .CR putprpwnam () must be used to modify the protected password databse entries. See .IR getprpwent (3). .SH NETWORKING FEATURES .SS \s-1NFS\s0 If an entry beginning with a plus sign .RC ( + ) or a minus sign .RB ( \(mi ) is found, these routines try to use the Network Information Service network database for data. See .IR passwd (4) for proper syntax and operation. .PP Network Information Service (NIS) is not supported on trusted systems. .SH RETURN VALUE .CR getpwent (), .CR getpwuid (), .CR getpwnam (), and .CR fgetpwent () return a .SM NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .C passwd structure. .PP .CR getpwent_r (), .CR getpwuid_r (), .CR getpwnam_r (), and .CR fgetpwent_r (), return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getpwent() , .CR getpwuid() , and .CR fgetpwent() fail if any of the following are true: .RS .TP 15 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library, which causes them to increase the size of programs, not otherwise using standard .SM I/O and Network Information Service, more than might be expected. .PP The value returned by .CR getpwent() , .CR getpwuid() , .CR getpwnam() , and .C fgetpwent() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved. .PP .CR getpwent() , .CR getpwuid() , .CR getpwnam() , .CR setpwent() , .CR endpwent() , and .C fgetpwent() are unsafe in multi-thread applications. .CR getpwent_r() , .CR getpwuid_r() , .CR getpwnam_r() , .CR setpwent_r() , .CR endpwent_r() , and .C fgetpwent_r() are MT-Safe and should be used instead. .PP The following fields have numerical limitations as noted: .RS .TP 3 \(bu The user ID is an integer value between -2 and UID_MAX inclusive. .TP \(bu The group ID is an integer value between 0 and UID_MAX inclusive. .RE .PP Users of .CR getpwnam_r() and .CR getpwuid_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH EXAMPLE The following code excerpt counts the number of entries in the .C /etc/passwd file: .PP .nf .IP .C "int count = 0;" .C "struct passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setpwent_r(&pwf);" .C "while (getpwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endpwent_r(&pwf);" .fi .SH DEPENDENCIES .SS \s-1NFS\s0 .B Files: .RS .CI /var/yp/ domainname /passwd.byname .br .CI /var/yp/ domainname /passwd.byuid .RE .PP .B See Also: .RS ypcat(1). .RE .SH AUTHOR .CR getpwent (), .CR getpwuid (), .CR getpwnam (), .CR setpwent (), .CR endpwent (), and .CR fgetpwent () were developed by AT&T and HP. .SH FILES .TP 30 .C /etc/passwd System Password file .SH SEE ALSO ypcat(1), cuserid(3S), getgrent(3C), getlogin(3C), getprpwent(3), getspwent(3X), stdio(3S), putpwent(3C), putspwent(3X), passwd(4), limits(5). .SH STANDARDS CONFORMANCE .CR getpwent() ": SVID2, SVID3, XPG2" .PP .CR endpwent() ": SVID2, SVID3, XPG2" .PP .CR fgetpwent() ": SVID2, SVID3, XPG2" .PP .CR getpwnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpwuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setpwent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getpwent()\f1 \- get next password file entry@@@\f3getpwent(3C)\f1 .\" index@\f4fgetpwent()\f1 \- get next entry in password-file-formatted input stream@@@\f3getpwent(3C)\f1 .\" index@\f4getpwuid()\f1 \- get password file entry matching \f4uid()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4getpwnam()\f1 \- get password file entry matching login name \f4name()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4setpwent()\f1 \- rewind pointer to beginning of password file@@@\f3getpwent(3C)\f1 .\" index@\f4endpwent()\f1 \- close currently open password file@@@\f3getpwent(3C)\f1 .\" index@entry from password file, get@@@\f3getpwent(3C)\f1 .\" index@password file, get entry from@@@\f3getpwent(3C)\f1 .\" index@file, password: get entry from password file@@@\f3getpwent(3C)\f1 .\" .\" toc@\f3getpwent(3C)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f , \f4endpwent()\f1, \n\f4fgetpwent()\f1@@@get password file entry .\" toc@\f4getpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4setpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4endpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" .\" links@getpwent.3c getpwuid.3c .\" links@getpwent.3c getpwnam.3c .\" links@getpwent.3c setpwent.3c .\" links@getpwent.3c endpwent.3c .\" links@getpwent.3c fgetpwent.3c .\" links@getpwent.3c getpwent_r.3c .\" links@getpwent.3c getpwuid_r.3c .\" links@getpwent.3c getpwnam_r.3c .\" links@getpwent.3c setpwent_r.3c .\" links@getpwent.3c endpwent_r.3c .\" links@getpwent.3c fgetpwent_r.3c .\" .\" fileset_database@getpwent.3c PROGRAMING-MAN .\" $Header: getpwent.3c,v 78.1 95/12/20 10:53:01 ssa Exp $ .TA g .TH getpwent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpwent(\|), getpwent_r(\|), getpwuid(\|), getpwuid_r(\|), getpwnam(\|), getpwnam_r(\|), setpwent(\|), setpwent_r(\|), endpwent(\|), endpwent_r(\|), fgetpwent(\|), fgetpwent_r(\|) \- get password file entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct passwd *getpwent(void);" .PP .C "int getpwent_r(struct passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct passwd *getpwuid(uid_t uid);" .PP .PD 0 .C "int getpwuid_r(uid_t uid, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct passwd *getpwnam(const char *name);" .PP .PD 0 .C "int getpwnam_r(char *name, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setpwent(void);" .PP .C "void setpwent_r(FILE **pwfp);" .PP .C "void endpwent(void);" .PP .C "void endpwent_r(FILE **pwfp);" .PP .C "struct passwd *fgetpwent(FILE *stream);" .PP .C "int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, int buflen);" .fi .SH DESCRIPTION .CR getpwent (), .CR getpwuid (), and .CR getpwnam () locate an entry in the .C /etc/passwd file, and return a pointer to an object of .C passwd structure. .PP The .C passwd structure is defined in .RC < pwd.h > and includes the following members: .nf .IP .CR "char *pw_name; " "/* user name */" .CR "char *pw_passwd; " "/* encrypted password */" .CR "uid_t pw_uid; " "/* user id */" .CR "gid_t pw_gid; " "/* group id */" .CR "char *pw_age; " "/* password aging */" .CR "char *pw_comment;" "/* unused */" .CR "char *pw_gecos; " "/* user fullname, office, extension, homephone*/" .CR "char *pw_dir; " "/* initial directory */" .CR "char *pw_shell; " "/* initial shell */" .CR "aid_t pw_audid; " "/* numerical audit id */" .CR "int pw_audflg; " "/* numerical audit flag */" .fi .PP The .I pw_comment field is unused; for more information on the other fields, refer to .IR passwd (4). .TP 20 .CR getpwent () When first called, .CR getpwent () returns a pointer to the first .C passwd structure in the file. Thereafter, it returns a pointer to the next .C passwd structure in the file. In this way, successive calls can be used to search the entire file. .CR getpwent () opens the .C /etc/passwd file prior to doing its work and leaves the file open afterward; .TP .CR setpwent () Has the effect of rewinding this file to allow repeated searches; .TP .CR endpwent () Can be called to close the file when processing is complete. .TP .CR getpwuid () Searches from the beginning of the file until a numeric user .SM ID matching .I uid is found, and returns a pointer to the particular structure in which it was found. .TP .CR getpwnam () searches from the beginning of the file until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .CR fgetpwent () returns a pointer to the next .C passwd structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/passwd . .SS Reentrant Interfaces .CR getpwuid_r (), .CR getpwnam_r () and .CR fgetpwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .C passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in .C passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getpwent_r () requires a pointer to a .RI ( "FILE *" ) variable into which is stored the result of an .CR fopen () call on the .C /etc/passwd file. This is to allow threads to independently scan through the .C /etc/passwd file. .CR setpwent_r () and .CR endpwent_r () are to be used only in conjunction with .CR getpwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setpwent_r () can be used to rewind or open the .C /etc/passwd file. .CR endpwent_r () must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getpwent_r () or .CR setpwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH SECURITY FEATURES If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default .CR * that is in .C /etc/passwd and the audit ID and audit flag will be set to \(mi1. On trusted systems, if it is not necessary to obtain information from the regular password file, .CR /etc/passwd , users should use .CR getprpwent () to access the protected password database. See .IR getprpwent (3) and .IR getspwent (3X). .PP .CR putpwent () affects only .CR /etc/passwd ; the audit .SM ID and audit flag in the password structure are ignored. .CR putprpwnam () must be used to modify the protected password databse entries. See .IR getprpwent (3). .SH NETWORKING FEATURES .SS \s-1NFS\s0 If an entry beginning with a plus sign .RC ( + ) or a minus sign .RB ( \(mi ) is found, these routines try to use the Network Information Service network database for data. See .IR passwd (4) for proper syntax and operation. .PP Network Information Service (NIS) is not supported on trusted systems. .SH RETURN VALUE .CR getpwent (), .CR getpwuid (), .CR getpwnam (), and .CR fgetpwent () return a .SM NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .C passwd structure. .PP .CR getpwent_r (), .CR getpwuid_r (), .CR getpwnam_r (), and .CR fgetpwent_r (), return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getpwent() , .CR getpwuid() , and .CR fgetpwent() fail if any of the following are true: .RS .TP 15 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library, which causes them to increase the size of programs, not otherwise using standard .SM I/O and Network Information Service, more than might be expected. .PP The value returned by .CR getpwent() , .CR getpwuid() , .CR getpwnam() , and .C fgetpwent() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved. .PP .CR getpwent() , .CR getpwuid() , .CR getpwnam() , .CR setpwent() , .CR endpwent() , and .C fgetpwent() are unsafe in multi-thread applications. .CR getpwent_r() , .CR getpwuid_r() , .CR getpwnam_r() , .CR setpwent_r() , .CR endpwent_r() , and .C fgetpwent_r() are MT-Safe and should be used instead. .PP The following fields have numerical limitations as noted: .RS .TP 3 \(bu The user ID is an integer value between -2 and UID_MAX inclusive. .TP \(bu The group ID is an integer value between 0 and UID_MAX inclusive. .RE .PP Users of .CR getpwnam_r() and .CR getpwuid_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH EXAMPLE The following code excerpt counts the number of entries in the .C /etc/passwd file: .PP .nf .IP .C "int count = 0;" .C "struct passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setpwent_r(&pwf);" .C "while (getpwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endpwent_r(&pwf);" .fi .SH DEPENDENCIES .SS \s-1NFS\s0 .B Files: .RS .CI /var/yp/ domainname /passwd.byname .br .CI /var/yp/ domainname /passwd.byuid .RE .PP .B See Also: .RS ypcat(1). .RE .SH AUTHOR .CR getpwent (), .CR getpwuid (), .CR getpwnam (), .CR setpwent (), .CR endpwent (), and .CR fgetpwent () were developed by AT&T and HP. .SH FILES .TP 30 .C /etc/passwd System Password file .SH SEE ALSO ypcat(1), cuserid(3S), getgrent(3C), getlogin(3C), getprpwent(3), getspwent(3X), stdio(3S), putpwent(3C), putspwent(3X), passwd(4), limits(5). .SH STANDARDS CONFORMANCE .CR getpwent() ": SVID2, SVID3, XPG2" .PP .CR endpwent() ": SVID2, SVID3, XPG2" .PP .CR fgetpwent() ": SVID2, SVID3, XPG2" .PP .CR getpwnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpwuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setpwent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getpwent()\f1 \- get next password file entry@@@\f3getpwent(3C)\f1 .\" index@\f4fgetpwent()\f1 \- get next entry in password-file-formatted input stream@@@\f3getpwent(3C)\f1 .\" index@\f4getpwuid()\f1 \- get password file entry matching \f4uid()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4getpwnam()\f1 \- get password file entry matching login name \f4name()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4setpwent()\f1 \- rewind pointer to beginning of password file@@@\f3getpwent(3C)\f1 .\" index@\f4endpwent()\f1 \- close currently open password file@@@\f3getpwent(3C)\f1 .\" index@entry from password file, get@@@\f3getpwent(3C)\f1 .\" index@password file, get entry from@@@\f3getpwent(3C)\f1 .\" index@file, password: get entry from password file@@@\f3getpwent(3C)\f1 .\" .\" toc@\f3getpwent(3C)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f , \f4endpwent()\f1, \n\f4fgetpwent()\f1@@@get password file entry .\" toc@\f4getpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4setpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4endpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" .\" links@getpwent.3c getpwuid.3c .\" links@getpwent.3c getpwnam.3c .\" links@getpwent.3c setpwent.3c .\" links@getpwent.3c endpwent.3c .\" links@getpwent.3c fgetpwent.3c .\" links@getpwent.3c getpwent_r.3c .\" links@getpwent.3c getpwuid_r.3c .\" links@getpwent.3c getpwnam_r.3c .\" links@getpwent.3c setpwent_r.3c .\" links@getpwent.3c endpwent_r.3c .\" links@getpwent.3c fgetpwent_r.3c .\" .\" fileset_database@getpwent.3c PROGRAMING-MAN .\" $Header: getpwent.3c,v 78.1 95/12/20 10:53:01 ssa Exp $ .TA g .TH getpwent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpwent(\|), getpwent_r(\|), getpwuid(\|), getpwuid_r(\|), getpwnam(\|), getpwnam_r(\|), setpwent(\|), setpwent_r(\|), endpwent(\|), endpwent_r(\|), fgetpwent(\|), fgetpwent_r(\|) \- get password file entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct passwd *getpwent(void);" .PP .C "int getpwent_r(struct passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct passwd *getpwuid(uid_t uid);" .PP .PD 0 .C "int getpwuid_r(uid_t uid, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct passwd *getpwnam(const char *name);" .PP .PD 0 .C "int getpwnam_r(char *name, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setpwent(void);" .PP .C "void setpwent_r(FILE **pwfp);" .PP .C "void endpwent(void);" .PP .C "void endpwent_r(FILE **pwfp);" .PP .C "struct passwd *fgetpwent(FILE *stream);" .PP .C "int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, int buflen);" .fi .SH DESCRIPTION .CR getpwent (), .CR getpwuid (), and .CR getpwnam () locate an entry in the .C /etc/passwd file, and return a pointer to an object of .C passwd structure. .PP The .C passwd structure is defined in .RC < pwd.h > and includes the following members: .nf .IP .CR "char *pw_name; " "/* user name */" .CR "char *pw_passwd; " "/* encrypted password */" .CR "uid_t pw_uid; " "/* user id */" .CR "gid_t pw_gid; " "/* group id */" .CR "char *pw_age; " "/* password aging */" .CR "char *pw_comment;" "/* unused */" .CR "char *pw_gecos; " "/* user fullname, office, extension, homephone*/" .CR "char *pw_dir; " "/* initial directory */" .CR "char *pw_shell; " "/* initial shell */" .CR "aid_t pw_audid; " "/* numerical audit id */" .CR "int pw_audflg; " "/* numerical audit flag */" .fi .PP The .I pw_comment field is unused; for more information on the other fields, refer to .IR passwd (4). .TP 20 .CR getpwent () When first called, .CR getpwent () returns a pointer to the first .C passwd structure in the file. Thereafter, it returns a pointer to the next .C passwd structure in the file. In this way, successive calls can be used to search the entire file. .CR getpwent () opens the .C /etc/passwd file prior to doing its work and leaves the file open afterward; .TP .CR setpwent () Has the effect of rewinding this file to allow repeated searches; .TP .CR endpwent () Can be called to close the file when processing is complete. .TP .CR getpwuid () Searches from the beginning of the file until a numeric user .SM ID matching .I uid is found, and returns a pointer to the particular structure in which it was found. .TP .CR getpwnam () searches from the beginning of the file until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .CR fgetpwent () returns a pointer to the next .C passwd structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/passwd . .SS Reentrant Interfaces .CR getpwuid_r (), .CR getpwnam_r () and .CR fgetpwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .C passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in .C passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getpwent_r () requires a pointer to a .RI ( "FILE *" ) variable into which is stored the result of an .CR fopen () call on the .C /etc/passwd file. This is to allow threads to independently scan through the .C /etc/passwd file. .CR setpwent_r () and .CR endpwent_r () are to be used only in conjunction with .CR getpwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setpwent_r () can be used to rewind or open the .C /etc/passwd file. .CR endpwent_r () must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getpwent_r () or .CR setpwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH SECURITY FEATURES If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default .CR * that is in .C /etc/passwd and the audit ID and audit flag will be set to \(mi1. On trusted systems, if it is not necessary to obtain information from the regular password file, .CR /etc/passwd , users should use .CR getprpwent () to access the protected password database. See .IR getprpwent (3) and .IR getspwent (3X). .PP .CR putpwent () affects only .CR /etc/passwd ; the audit .SM ID and audit flag in the password structure are ignored. .CR putprpwnam () must be used to modify the protected password databse entries. See .IR getprpwent (3). .SH NETWORKING FEATURES .SS \s-1NFS\s0 If an entry beginning with a plus sign .RC ( + ) or a minus sign .RB ( \(mi ) is found, these routines try to use the Network Information Service network database for data. See .IR passwd (4) for proper syntax and operation. .PP Network Information Service (NIS) is not supported on trusted systems. .SH RETURN VALUE .CR getpwent (), .CR getpwuid (), .CR getpwnam (), and .CR fgetpwent () return a .SM NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .C passwd structure. .PP .CR getpwent_r (), .CR getpwuid_r (), .CR getpwnam_r (), and .CR fgetpwent_r (), return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getpwent() , .CR getpwuid() , and .CR fgetpwent() fail if any of the following are true: .RS .TP 15 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library, which causes them to increase the size of programs, not otherwise using standard .SM I/O and Network Information Service, more than might be expected. .PP The value returned by .CR getpwent() , .CR getpwuid() , .CR getpwnam() , and .C fgetpwent() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved. .PP .CR getpwent() , .CR getpwuid() , .CR getpwnam() , .CR setpwent() , .CR endpwent() , and .C fgetpwent() are unsafe in multi-thread applications. .CR getpwent_r() , .CR getpwuid_r() , .CR getpwnam_r() , .CR setpwent_r() , .CR endpwent_r() , and .C fgetpwent_r() are MT-Safe and should be used instead. .PP The following fields have numerical limitations as noted: .RS .TP 3 \(bu The user ID is an integer value between -2 and UID_MAX inclusive. .TP \(bu The group ID is an integer value between 0 and UID_MAX inclusive. .RE .PP Users of .CR getpwnam_r() and .CR getpwuid_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH EXAMPLE The following code excerpt counts the number of entries in the .C /etc/passwd file: .PP .nf .IP .C "int count = 0;" .C "struct passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setpwent_r(&pwf);" .C "while (getpwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endpwent_r(&pwf);" .fi .SH DEPENDENCIES .SS \s-1NFS\s0 .B Files: .RS .CI /var/yp/ domainname /passwd.byname .br .CI /var/yp/ domainname /passwd.byuid .RE .PP .B See Also: .RS ypcat(1). .RE .SH AUTHOR .CR getpwent (), .CR getpwuid (), .CR getpwnam (), .CR setpwent (), .CR endpwent (), and .CR fgetpwent () were developed by AT&T and HP. .SH FILES .TP 30 .C /etc/passwd System Password file .SH SEE ALSO ypcat(1), cuserid(3S), getgrent(3C), getlogin(3C), getprpwent(3), getspwent(3X), stdio(3S), putpwent(3C), putspwent(3X), passwd(4), limits(5). .SH STANDARDS CONFORMANCE .CR getpwent() ": SVID2, SVID3, XPG2" .PP .CR endpwent() ": SVID2, SVID3, XPG2" .PP .CR fgetpwent() ": SVID2, SVID3, XPG2" .PP .CR getpwnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpwuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setpwent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getpwent()\f1 \- get next password file entry@@@\f3getpwent(3C)\f1 .\" index@\f4fgetpwent()\f1 \- get next entry in password-file-formatted input stream@@@\f3getpwent(3C)\f1 .\" index@\f4getpwuid()\f1 \- get password file entry matching \f4uid()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4getpwnam()\f1 \- get password file entry matching login name \f4name()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4setpwent()\f1 \- rewind pointer to beginning of password file@@@\f3getpwent(3C)\f1 .\" index@\f4endpwent()\f1 \- close currently open password file@@@\f3getpwent(3C)\f1 .\" index@entry from password file, get@@@\f3getpwent(3C)\f1 .\" index@password file, get entry from@@@\f3getpwent(3C)\f1 .\" index@file, password: get entry from password file@@@\f3getpwent(3C)\f1 .\" .\" toc@\f3getpwent(3C)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f , \f4endpwent()\f1, \n\f4fgetpwent()\f1@@@get password file entry .\" toc@\f4getpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4setpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4endpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" .\" links@getpwent.3c getpwuid.3c .\" links@getpwent.3c getpwnam.3c .\" links@getpwent.3c setpwent.3c .\" links@getpwent.3c endpwent.3c .\" links@getpwent.3c fgetpwent.3c .\" links@getpwent.3c getpwent_r.3c .\" links@getpwent.3c getpwuid_r.3c .\" links@getpwent.3c getpwnam_r.3c .\" links@getpwent.3c setpwent_r.3c .\" links@getpwent.3c endpwent_r.3c .\" links@getpwent.3c fgetpwent_r.3c .\" .\" fileset_database@getpwent.3c PROGRAMING-MAN .\" $Header: getrpcent.3c,v 76.1 95/05/26 17:09:42 ssa Exp $ .TA g .TH getrpcent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getrpcent(\|), getrpcent_r(\|), getrpcbyname(\|), getrpcbyname_r(\|), getrpcbynumber(\|), getrpcbynumber_r(\|) \- get rpc entry .SH SYNOPSIS .nf .C #include .PP .C struct rpcent *getrpcent(); .PP .C "int getrpcent_r(struct rpcent *rpcent," .C " struct rpcent_data *rpc_data);" .PP .C "struct rpcent *getrpcbyname(char *name);" .PP .C "int getrpcbyname_r (char *name," .C " struct rpcent *rpcent," .C " struct rpcent_data *rpc_data);" .PP .C "struct rpcent *getrpcbynumber(int number);" .PP .C "int getrpcbynumber_r (register int number," .C " struct rpcent *rpcent," .C " struct rpcent_data *rpc_data);" .PP .C "int setrpcent(int stayopen);" .PP .C "int setrpcent_r (int f," .C " sruct rpcent_data *rpc_data);" .PP .C "int endrpcent();" .PP .C "int endrpcent_r (struct rpcent_data *rpc_data);" .SH DESCRIPTION .CR getrpcent() , .CR getrpcbyname() , and .C getrpcbynumber() each return a pointer to an object with the following structure containing the broken-out fields of a line in the rpc program number data base, .CR /etc/rpc . .nf .IP .C "struct rpcent {" .C " char *r_name; /* name of server for this rpc program */" .C " char **r_aliases; /* NULL terminated list of aliases */" .C " int r_number; /* rpc program number for this service */" .C }; .fi .SS Functions .TP 25 .C getrpcent() Read the next line of the file, opening the file if necessary. .TP .C setrpcent() Open and rewind the file. If the .I stayopen flag is non-zero, the rpc database is not closed after each call to .C getrpcent() (either directly or indirectly through one of the other .C getrpc*() calls). .TP .C endrpcent() Close the file. .TP .C getrpcbyname() Sequentially search from the beginning of the file until a matching rpc program name is found, or until .SM EOF is encountered. .TP .C getrpcbynumber() Sequentially search from the beginning of the file until a matching rpc program number is found, or until .SM EOF is encountered. .PD .PP If the system is running the Network Information Service (NIS) services, .CR getrpcbyname() and .CR getrpcbynumber() get the rpc information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getrpcent_r(), .CR getrpcbyname_r(), and .CR getrpcbynumber_r() expect to be passed the address of a .CR "struct rpcent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct rpcent_data", must also be supplied. This structure is used to store data, to which fields in the .CR "struct rpcent" will point, as well as state information such as open file descriptors. The .CR "struct rpcent_data" is defined in the file .CR . .PP .CR setrpcent_r() and .CR endrpcent_r() are to be used only in conjunction with .CR getrpcent_r() and take the same pointer to a .CR "struct rpcent_data" as a parameter. If the Network Information Service is being used, .CR setrpcent_r() initiaizes an internal database key. If the .B /etc/rpc file is being used, .CR setrpcent_r() opens or rewinds the file. .CR endrpcent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setrpcent_r() currently has no effect. However, .CR setrpcent() can still be used to keep the .B /etc/rpc file open when making calls to .CR getrpcbyname_r() and .CR getrpcbynumber_r() .PP The .I rpc_fp field in the .CR "struct rpcent_data" must be initialized to NULL before it is passed to either .CR getrpcent_r() or .CR setrpcent_r() for the first time. Thereafter is should not be modified in any way. This is the only .CR rpcent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getrpcbyname() , .CR getrpcbynumber() , .CR getrpcent() , and their reentrant counterparts, internally call the name service switch to access the "rpc" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve rpc names and numbers. .SH RETURN VALUE .CR getrpcent() , .CR getrpcbyname() , and .C getrpcbynumber() return a null pointer (0) on .SM EOF or when unable to access the information in .C /etc/rpc either directly or through a Network Information Service database. .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 will be returned if the operation is unsuccessful or, in the case of .CR getrpcent_r() , if the end of the rpc list has been reached. .CR 0 is returned otherwise. .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getrpcent() , .CR getrpcbynumber() , .CR getrpcbyname() , .CR setrpcent() , and .CR endrpcent() are unsafe in multi-thread applications. .CR getrpcent_r() , .CR getrpcbynumber_r() , .CR getrpcbyname_r() , .CR setrpcent_r() , and .CR endrpcent_r() are MT-Safe and should be used instead. .SH AUTHOR .C getrpcent() was developed by Sun Microsystems, Inc. .SH FILES .C /etc/rpc .C /etc/nsswitch.conf .SH SEE ALSO rpcinfo(1M), rpc(4), switch(4). .\" index@\f4getrpcent()\fP: get \s-1RPC\s+1 entry@@@\f3getrpcent(3C)\f1 .\" index@\f4getrpcbyname()\fP: get \s-1RPC\s+1 entry@@@\f3getrpcent(3C)\f1 .\" index@\f4getrpcbynumber()\fP: get \s-1RPC\s+1 entry@@@\f3getrpcent(3C)\f1 .\" index@get \s-1RPC\s+1 entry@@@\f3getrpcent(3C)\f1 .\" index@\s-1RPC\s+1 entry, get@@@\f3getrpcent(3C)\f1 .\" index@entry, get \s-1RPC\s+1@@@\f3getrpcent(3C)\f1 .\" toc@\f3getrpcent(3C)\f1: \f4getrpcent()\fP, \f4getrpcbyname()\fP, \f4getrpcbynumber()\fP@@@get rpc entry .\" .\" links@getrpcent.3c getrpcbynam.3c .\" links@getrpcent.3c getrpcbynum.3c .\" .\" fileset_database@getrpcent.3c PROGRAMING-MAN .\" $Header: getrpcent.3c,v 76.1 95/05/26 17:09:42 ssa Exp $ .TA g .TH getrpcent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getrpcent(\|), getrpcent_r(\|), getrpcbyname(\|), getrpcbyname_r(\|), getrpcbynumber(\|), getrpcbynumber_r(\|) \- get rpc entry .SH SYNOPSIS .nf .C #include .PP .C struct rpcent *getrpcent(); .PP .C "int getrpcent_r(struct rpcent *rpcent," .C " struct rpcent_data *rpc_data);" .PP .C "struct rpcent *getrpcbyname(char *name);" .PP .C "int getrpcbyname_r (char *name," .C " struct rpcent *rpcent," .C " struct rpcent_data *rpc_data);" .PP .C "struct rpcent *getrpcbynumber(int number);" .PP .C "int getrpcbynumber_r (register int number," .C " struct rpcent *rpcent," .C " struct rpcent_data *rpc_data);" .PP .C "int setrpcent(int stayopen);" .PP .C "int setrpcent_r (int f," .C " sruct rpcent_data *rpc_data);" .PP .C "int endrpcent();" .PP .C "int endrpcent_r (struct rpcent_data *rpc_data);" .SH DESCRIPTION .CR getrpcent() , .CR getrpcbyname() , and .C getrpcbynumber() each return a pointer to an object with the following structure containing the broken-out fields of a line in the rpc program number data base, .CR /etc/rpc . .nf .IP .C "struct rpcent {" .C " char *r_name; /* name of server for this rpc program */" .C " char **r_aliases; /* NULL terminated list of aliases */" .C " int r_number; /* rpc program number for this service */" .C }; .fi .SS Functions .TP 25 .C getrpcent() Read the next line of the file, opening the file if necessary. .TP .C setrpcent() Open and rewind the file. If the .I stayopen flag is non-zero, the rpc database is not closed after each call to .C getrpcent() (either directly or indirectly through one of the other .C getrpc*() calls). .TP .C endrpcent() Close the file. .TP .C getrpcbyname() Sequentially search from the beginning of the file until a matching rpc program name is found, or until .SM EOF is encountered. .TP .C getrpcbynumber() Sequentially search from the beginning of the file until a matching rpc program number is found, or until .SM EOF is encountered. .PD .PP If the system is running the Network Information Service (NIS) services, .CR getrpcbyname() and .CR getrpcbynumber() get the rpc information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getrpcent_r(), .CR getrpcbyname_r(), and .CR getrpcbynumber_r() expect to be passed the address of a .CR "struct rpcent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct rpcent_data", must also be supplied. This structure is used to store data, to which fields in the .CR "struct rpcent" will point, as well as state information such as open file descriptors. The .CR "struct rpcent_data" is defined in the file .CR . .PP .CR setrpcent_r() and .CR endrpcent_r() are to be used only in conjunction with .CR getrpcent_r() and take the same pointer to a .CR "struct rpcent_data" as a parameter. If the Network Information Service is being used, .CR setrpcent_r() initiaizes an internal database key. If the .B /etc/rpc file is being used, .CR setrpcent_r() opens or rewinds the file. .CR endrpcent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setrpcent_r() currently has no effect. However, .CR setrpcent() can still be used to keep the .B /etc/rpc file open when making calls to .CR getrpcbyname_r() and .CR getrpcbynumber_r() .PP The .I rpc_fp field in the .CR "struct rpcent_data" must be initialized to NULL before it is passed to either .CR getrpcent_r() or .CR setrpcent_r() for the first time. Thereafter is should not be modified in any way. This is the only .CR rpcent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getrpcbyname() , .CR getrpcbynumber() , .CR getrpcent() , and their reentrant counterparts, internally call the name service switch to access the "rpc" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve rpc names and numbers. .SH RETURN VALUE .CR getrpcent() , .CR getrpcbyname() , and .C getrpcbynumber() return a null pointer (0) on .SM EOF or when unable to access the information in .C /etc/rpc either directly or through a Network Information Service database. .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 will be returned if the operation is unsuccessful or, in the case of .CR getrpcent_r() , if the end of the rpc list has been reached. .CR 0 is returned otherwise. .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getrpcent() , .CR getrpcbynumber() , .CR getrpcbyname() , .CR setrpcent() , and .CR endrpcent() are unsafe in multi-thread applications. .CR getrpcent_r() , .CR getrpcbynumber_r() , .CR getrpcbyname_r() , .CR setrpcent_r() , and .CR endrpcent_r() are MT-Safe and should be used instead. .SH AUTHOR .C getrpcent() was developed by Sun Microsystems, Inc. .SH FILES .C /etc/rpc .C /etc/nsswitch.conf .SH SEE ALSO rpcinfo(1M), rpc(4), switch(4). .\" index@\f4getrpcent()\fP: get \s-1RPC\s+1 entry@@@\f3getrpcent(3C)\f1 .\" index@\f4getrpcbyname()\fP: get \s-1RPC\s+1 entry@@@\f3getrpcent(3C)\f1 .\" index@\f4getrpcbynumber()\fP: get \s-1RPC\s+1 entry@@@\f3getrpcent(3C)\f1 .\" index@get \s-1RPC\s+1 entry@@@\f3getrpcent(3C)\f1 .\" index@\s-1RPC\s+1 entry, get@@@\f3getrpcent(3C)\f1 .\" index@entry, get \s-1RPC\s+1@@@\f3getrpcent(3C)\f1 .\" toc@\f3getrpcent(3C)\f1: \f4getrpcent()\fP, \f4getrpcbyname()\fP, \f4getrpcbynumber()\fP@@@get rpc entry .\" .\" links@getrpcent.3c getrpcbynam.3c .\" links@getrpcent.3c getrpcbynum.3c .\" .\" fileset_database@getrpcent.3c PROGRAMING-MAN .\" $Header: getrpcent.3c,v 76.1 95/05/26 17:09:42 ssa Exp $ .TA g .TH getrpcent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getrpcent(\|), getrpcent_r(\|), getrpcbyname(\|), getrpcbyname_r(\|), getrpcbynumber(\|), getrpcbynumber_r(\|) \- get rpc entry .SH SYNOPSIS .nf .C #include .PP .C struct rpcent *getrpcent(); .PP .C "int getrpcent_r(struct rpcent *rpcent," .C " struct rpcent_data *rpc_data);" .PP .C "struct rpcent *getrpcbyname(char *name);" .PP .C "int getrpcbyname_r (char *name," .C " struct rpcent *rpcent," .C " struct rpcent_data *rpc_data);" .PP .C "struct rpcent *getrpcbynumber(int number);" .PP .C "int getrpcbynumber_r (register int number," .C " struct rpcent *rpcent," .C " struct rpcent_data *rpc_data);" .PP .C "int setrpcent(int stayopen);" .PP .C "int setrpcent_r (int f," .C " sruct rpcent_data *rpc_data);" .PP .C "int endrpcent();" .PP .C "int endrpcent_r (struct rpcent_data *rpc_data);" .SH DESCRIPTION .CR getrpcent() , .CR getrpcbyname() , and .C getrpcbynumber() each return a pointer to an object with the following structure containing the broken-out fields of a line in the rpc program number data base, .CR /etc/rpc . .nf .IP .C "struct rpcent {" .C " char *r_name; /* name of server for this rpc program */" .C " char **r_aliases; /* NULL terminated list of aliases */" .C " int r_number; /* rpc program number for this service */" .C }; .fi .SS Functions .TP 25 .C getrpcent() Read the next line of the file, opening the file if necessary. .TP .C setrpcent() Open and rewind the file. If the .I stayopen flag is non-zero, the rpc database is not closed after each call to .C getrpcent() (either directly or indirectly through one of the other .C getrpc*() calls). .TP .C endrpcent() Close the file. .TP .C getrpcbyname() Sequentially search from the beginning of the file until a matching rpc program name is found, or until .SM EOF is encountered. .TP .C getrpcbynumber() Sequentially search from the beginning of the file until a matching rpc program number is found, or until .SM EOF is encountered. .PD .PP If the system is running the Network Information Service (NIS) services, .CR getrpcbyname() and .CR getrpcbynumber() get the rpc information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getrpcent_r(), .CR getrpcbyname_r(), and .CR getrpcbynumber_r() expect to be passed the address of a .CR "struct rpcent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct rpcent_data", must also be supplied. This structure is used to store data, to which fields in the .CR "struct rpcent" will point, as well as state information such as open file descriptors. The .CR "struct rpcent_data" is defined in the file .CR . .PP .CR setrpcent_r() and .CR endrpcent_r() are to be used only in conjunction with .CR getrpcent_r() and take the same pointer to a .CR "struct rpcent_data" as a parameter. If the Network Information Service is being used, .CR setrpcent_r() initiaizes an internal database key. If the .B /etc/rpc file is being used, .CR setrpcent_r() opens or rewinds the file. .CR endrpcent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setrpcent_r() currently has no effect. However, .CR setrpcent() can still be used to keep the .B /etc/rpc file open when making calls to .CR getrpcbyname_r() and .CR getrpcbynumber_r() .PP The .I rpc_fp field in the .CR "struct rpcent_data" must be initialized to NULL before it is passed to either .CR getrpcent_r() or .CR setrpcent_r() for the first time. Thereafter is should not be modified in any way. This is the only .CR rpcent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getrpcbyname() , .CR getrpcbynumber() , .CR getrpcent() , and their reentrant counterparts, internally call the name service switch to access the "rpc" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve rpc names and numbers. .SH RETURN VALUE .CR getrpcent() , .CR getrpcbyname() , and .C getrpcbynumber() return a null pointer (0) on .SM EOF or when unable to access the information in .C /etc/rpc either directly or through a Network Information Service database. .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 will be returned if the operation is unsuccessful or, in the case of .CR getrpcent_r() , if the end of the rpc list has been reached. .CR 0 is returned otherwise. .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getrpcent() , .CR getrpcbynumber() , .CR getrpcbyname() , .CR setrpcent() , and .CR endrpcent() are unsafe in multi-thread applications. .CR getrpcent_r() , .CR getrpcbynumber_r() , .CR getrpcbyname_r() , .CR setrpcent_r() , and .CR endrpcent_r() are MT-Safe and should be used instead. .SH AUTHOR .C getrpcent() was developed by Sun Microsystems, Inc. .SH FILES .C /etc/rpc .C /etc/nsswitch.conf .SH SEE ALSO rpcinfo(1M), rpc(4), switch(4). .\" index@\f4getrpcent()\fP: get \s-1RPC\s+1 entry@@@\f3getrpcent(3C)\f1 .\" index@\f4getrpcbyname()\fP: get \s-1RPC\s+1 entry@@@\f3getrpcent(3C)\f1 .\" index@\f4getrpcbynumber()\fP: get \s-1RPC\s+1 entry@@@\f3getrpcent(3C)\f1 .\" index@get \s-1RPC\s+1 entry@@@\f3getrpcent(3C)\f1 .\" index@\s-1RPC\s+1 entry, get@@@\f3getrpcent(3C)\f1 .\" index@entry, get \s-1RPC\s+1@@@\f3getrpcent(3C)\f1 .\" toc@\f3getrpcent(3C)\f1: \f4getrpcent()\fP, \f4getrpcbyname()\fP, \f4getrpcbynumber()\fP@@@get rpc entry .\" .\" links@getrpcent.3c getrpcbynam.3c .\" links@getrpcent.3c getrpcbynum.3c .\" .\" fileset_database@getrpcent.3c PROGRAMING-MAN .\" $Header: getrpcport.3n,v 72.4 94/06/30 14:47:34 ssa Exp $ .TA g .TH getrpcport 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getrpcport(\|) \- get RPC port number .SH SYNOPSIS .nf .C int getrpcport( .C " char *host," .C " int prognum," .C " int versnum," .C " int proto" .C );" .fi .SH DESCRIPTION .CR getrpcport() returns the port number for version .I versnum of the RPC program .I prognum running on .I host and using protocol .IR proto . It returns .CR 0 if it cannot contact .I portmap or if .I prognum is not registered. If .I prognum is registered but not with version .IR versnum , it returns the port number of the last registered .IR ( prognum, .IR proto ) pair. .SH WARNINGS User applications that call this routine must be linked with .CR /usr/lib/librpcsvc.a . For example, .IP .C cc my_source.c -lrpcsvc .SH AUTHOR .CR getrpcport() was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M). .\" index@\f4getrpcport()\fP \- get \s-1RPC\s+1 port number@@@\f3getrpcport(3N)\f1 .\" index@get \s-1RPC\s+1 port number@@@\f3getrpcport(3N)\f1 .\" index@\s-1RPC\s+1 port number, get@@@\f3getrpcport(3N)\f1 .\" index@port number, \s-1RPC\s+1, get@@@\f3getrpcport(3N)\f1 .\" toc@\f3getrpcport(3N)\f1: \f4getrpcport()\fP@@@get RPC port number .\" $Header: gets.3s,v 72.5 94/11/15 09:54:47 ssa Exp $ .TA g .TH gets 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gets(\|), fgets(\|), fgets_unlocked(\|) \- get a string from a stream .SH SYNOPSIS .C "#include " .PP .C "char *gets(char *s);" .PP .C "char *fgets(char *s, int n, FILE *stream);" .PP .C "char *fgets_unlocked(char *s, int n, FILE *stream);" .SH DESCRIPTION .TP 15 .C gets() Reads characters from the standard input stream, .CR stdin , into the array pointed to by .IR s , until a new-line character is read or an end-of-file condition is encountered. The new-line character is discarded and the string is terminated with a null character. .TP .C fgets() Reads characters from the .I stream into the array pointed to by .IR s , until .IR n \(mi 1 characters are read, a new-line character is read and transferred to .IR s , or an end-of-file condition is encountered. The string is then terminated with a null character. .PP .CR fgets_unlocked() is identical to .CR fgets() except it does not perform any internal locking of the .I stream for multi-thread applications. .CR fgets_unlocked can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon sucessful completion, .CR fgets() , .CR fgets_unlocked() , and .CR gets() return .IR s . If the stream is at end-of-file, the end-of-file indicator for the stream is set and a null pointer is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and a null pointer is returned. .PP .CR ferror() and .CR feof() can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR fgets() , .CR fgets_unlocked() , and .CR gets() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP [EIO] The process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RS .PP Additional .CR errno values can be set by the underlying .CR read() function (see .IR read (2)). .SH SEE ALSO ferror(3S), flockfile(3S), fopen(3S), fread(3S), getc(3S), puts(3S), scanf(3S). .SH STANDARDS CONFORMANCE .CR gets() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fgets() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4gets()\f1, \f4fgets()\f1 \- get a string from a \f2standard input\f1 stream@@@\f3gets(3S)\f1 .\" index@\f4fgets()\f1, \f4gets()\f1 \- get a string from a \f2standard input\f1 stream@@@\f3gets(3S)\f1 .\" index@input string from a \f2standard input\f1 stream@@@\f3gets(3S)\f1 .\" index@string from a \f2standard input\f1 stream, input@@@\f3gets(3S)\f1 .\" index@\f2standard input\f1 stream, input string from a@@@\f3gets(3S)\f1 .\" index@stream, input string from a \f2standard input\f1@@@\f3gets(3S)\f1 .\" .\" toc@\f3gets(3S)\f1:\0\0\f4gets()\f1, \f4fgets()\f1@@@get a string from a stream .\" toc@\f4fgets()\f1:\0\0get a string from a stream@@@see \f3gets(3S)\f1 .\" .\" links@gets.3s fgets.3s .\" links@gets.3s fgets_unloc.3s .\" .\" fileset_database@gets.3s PROGRAMING-MAN .\" $Header: publickey.3r,v 72.2 94/08/25 12:42:38 ssa Exp $ .TA p .TH publickey 3R .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME publickey, getpublickey, getsecretkey \- get public or secret key .SH SYNOPSIS .C "#include " .PP .C "#include " .PP .C "getpublickey (netname, publickey)" .PP .C "char netname[MAXNETNAMELEN+1];" .PP .C "char publickey[HEXKEYBYTES+1];" .PP .C "getsecretkey (netname, secretkey, passwd)" .PP .C "char netname[MAXNETNAMELEN+1];" .PP .C "char secretkey[HEXKEYBYTES+1];" .PP .C "char *passwd;" .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These routines are used to get public and secret keys from the NIS .IR publickey (4) database. .PP .CR getsecretkey() has an extra argument, .IR passwd , which is used to decrypt the encrypted secret key stored in the .IR publickey (4) database. .PP Both routines return 1 if they are successful in finding the key; otherwise, these routines return 0. .PP The keys are returned as NULL-terminated, hexadecimal strings. .PP If the password supplied to .CR getsecretkey() fails to decrypt the secret key, the routine will return 1 but the secretkey argument will be a NULL string. .SH AUTHOR The .CR publickey routines were developed by Sun Microsystems, Inc. .SH SEE ALSO publickey(4). .\" .\" index@\f4publickey()\f1, \f4getpublickey()\f1, \f4getsecretkey()\f1 \- get public and secret keys@@@\f3publickey(3R)\f1 .\" index@\f4getpublickey()\f1, \f4publickey()\f1, \f4getsecretkey()\f1 \- get public and secret keys@@@\f3publickey(3R)\f1 .\" index@\f4getsecretkey()\f1, \f4publickey()\f1, \f4getpublickey()\f1 \- get public and secret keys@@@\f3publickey(3R)\f1 .\" .\" index@\f1get, public and secret keys@@@\f3publickey(3R)\f1 .\" index@\f1public keys, get@@@\f3getpublickey(3R)\f1 .\" index@\f1secret keys, get@@@\f3getsecretkey(3R)\f1 .\" .\" toc@\f3publickey(3R)\f1:\0\0\f4publickey()\f1, \f4getpublickey()\f1, \f4getsecretkey\f1@@@get public and secret keys .\" toc@\f4getpublickey()\f1:\0\0get public and secret keys@@@see \f3publickey(3R)\f1 .\" toc@\f4getsecretkey()\f1:\0\0get public and secret keys@@@see \f3publickey(3R)\f1 .\" .\" links@publickey.3r getpublickey.3r .\" links@publickey.3r getsecretkey.3r .\" $Header: getservent.3n,v 78.1 96/03/15 15:57:56 ssa Exp $ .TA g .TH getservent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getservent(), getservent_r(), getservbyport(), getservbyport_r(), getservbyname(), getservbyname_r(), setservent(), setservent_r(), endservent(), endservent_r() \- get service entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct servent *getservent(void);" .PP .C "int getservent_r(struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyname(const char *name, .C " const char *proto);" .PP .C "int getservbyname_r(const char *name," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyport(int port, const char *proto);" .PP .C "int getservbyport_r(int port," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PD .PP .C "int setservent(int stayopen);" .PP .C "int setservent_r(int stayopen, struct servent_data *buffer);" .PP .C "int endservent(void);" .PP .C "int endservent_r(struct servent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setservent(int stayopen);" .C "void endservent(void);" .fi .SH DESCRIPTION The .CR getservent() , .CR getservbyname() , and .CR getservbyport() functions each return a pointer to a structure of type .I servent containing the broken-out fields of a line in the network services data base, .CR /etc/services . .PP The members of this structure are: .RS .TP 15 .CR s_name The official name of the service. .TP .CR s_aliases A null-terminated list of alternate names for the service. .TP .CR s_port The port number at which the service resides. .TP .CR s_proto The name of the protocol to use when contacting the service. .RE .PP Functions behave as follows: .RS .TP 25 .CR getservent() Reads the next line of the file, opening the file if necessary. .TP .CR setservent() Opens and rewinds the file. If the .I stayopen flag is non-zero, the services data base is not closed after each call to .CR getservent() (either directly or indirectly through one of the other .CR getserv* calls). .TP .CR endservent() Closes the file. .TP .CR getservbyname() .PD 0 .TP .CR getservbyport() Each sequentially searches from the beginning of the file until a matching service name (among either the official names or the aliases) or port number is found, or until EOF is encountered. If a non-NULL protocol name is also supplied (such as .CR tcp or .CR udp ), searches must also match the protocol. .PD .IP If the system is running the Network Information Service (NIS), .CR getservbyname() gets the service information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getservent_r() , .CR getservbyname_r() , and .CR getservbyport_r() expect to be passed the address of a .CR "struct servent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct servent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct servent" will point, as well as state information such as open file descriptors. The .CR "struct servent_data" is defined in the file .CR . .PP .CR setservent_r() and .CR endservent_r() are to be used only in conjunction with .CR getservent_r() and take the same pointer to a .CR "struct servent_data" as a parameter. If the Network Information Service is being used, .CR setservent_r() initializes an internal database key. If the .CR /etc/services file is being used, .CR setservent_r() opens or rewinds the file. .CR endservent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setservent_r() currently has no effect. However, .CR setservent() can still be used to keep the .B /etc/services file open when making calls to .CR getservbyname_r() and .CR getservbyport_r() . .PP The .I serv_fp field in the .CR "servent_data struct" must be initialized to NULL before it is passed to either .CR getservent_r() or .CR setservent_r() for the first time. Thereafter it should not be modified in any way. This is the only .CR "servent_data" field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getservbyname() , .CR getservbyport() , .CR getservent() , and their reentrant counterparts, internally call the name service switch to access the "services" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve service names and ports. .SH RETURN VALUE .CR getservent() , .CR getservbyname() , and .CR getservbyport() return a null pointer (0) on EOF or when they are unable to open .CR /etc/services . .PP The reentrant .RC ( _r ) versions of these routines return .CR -1 if the operation is unsuccessful or, in the case of .CR getservent_r() , if the end of the services list has been reached. .CR 0 is returned otherwise. .SH EXAMPLES The following code excerpt counts the number of service entries: .RS .nf .PP .C "int count = 0;" .C "struct servent servbuf;" .C "struct servent_data sdbuf;" .PP .C "sdbuf.serv_fp = NULL;" .C "(void) setservent_r(0, &sdbuf);" .C "while (getservent_r(&servbuf, &sdbuf) != -1)" .C " count++;" .C "(void) endservent_r(&sdbuf);" .fi .RE .SH WARNINGS In the nonreentrant versions of these routines, all information is contained in a static area, so it must be copied if it is to be saved. .PP .CR getservent() , .CR getservbyport() , .CR getservbyname() , .CR setservent() , and .CR endservent() are unsafe in multi-thread applications. .CR getservent_r() , .CR getservbyport_r() , .CR getservbyname_r() , .CR setservent_r() , and .CR endservent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getservent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/services .SH SEE ALSO ypserv(1M), services(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getservent() ": XPG4" .\" .\" index@\f1end service entry@@@\f3getservent(3N)\f1 .\" index@\f1entry, get, set, or end service@@@\f3getservent(3N)\f1 .\" index@\f1get service entry@@@\f3getservent(3N)\f1 .\" index@\f1service entry, get, set, or end@@@\f3getservent(3N)\f1 .\" index@\f1set service entry@@@\f3getservent(3N)\f1 .\" index@\f1thread-safe, get, set, or end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent()\f1 \- end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent_r()\f1 \- end service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservent()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservent_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4setservent()\f1 \- set service entry@@@\f3getservent(3N)\f1 .\" index@\f4setservent_r()\f1 \- set service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" .\" links@getservent.3n endservent.3n .\" links@getservent.3n endservent_.3n .\" links@getservent.3n getservbyna.3n .\" links@getservent.3n getservbypo.3n .\" links@getservent.3n getservent_.3n .\" links@getservent.3n setservent.3n .\" links@getservent.3n setservent_.3n .\" .\" toc@\f3getservent(3N)\f1:\0\0\f4endservent()\f1, \f4endservent_r()\f1, \f4getservbyname()\f1, \f4getservbyname_r()\f1,\n\f4getservbyport()\f1, \f4getservbyport_r()\f1, \f4getservent()\f1, \f4getservent_r()\f1,\n\f4setservent()\f1, \f4setservent_r()\f1@@@get, set, or end service entry .\" .\" toc@\f4endservent()\f1:\0\0end service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4endservent_r()\f1:\0\0end service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent()\f1:\0\0set service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent_r()\f1:\0\0set service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" $Header: getservent.3n,v 78.1 96/03/15 15:57:56 ssa Exp $ .TA g .TH getservent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getservent(), getservent_r(), getservbyport(), getservbyport_r(), getservbyname(), getservbyname_r(), setservent(), setservent_r(), endservent(), endservent_r() \- get service entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct servent *getservent(void);" .PP .C "int getservent_r(struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyname(const char *name, .C " const char *proto);" .PP .C "int getservbyname_r(const char *name," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyport(int port, const char *proto);" .PP .C "int getservbyport_r(int port," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PD .PP .C "int setservent(int stayopen);" .PP .C "int setservent_r(int stayopen, struct servent_data *buffer);" .PP .C "int endservent(void);" .PP .C "int endservent_r(struct servent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setservent(int stayopen);" .C "void endservent(void);" .fi .SH DESCRIPTION The .CR getservent() , .CR getservbyname() , and .CR getservbyport() functions each return a pointer to a structure of type .I servent containing the broken-out fields of a line in the network services data base, .CR /etc/services . .PP The members of this structure are: .RS .TP 15 .CR s_name The official name of the service. .TP .CR s_aliases A null-terminated list of alternate names for the service. .TP .CR s_port The port number at which the service resides. .TP .CR s_proto The name of the protocol to use when contacting the service. .RE .PP Functions behave as follows: .RS .TP 25 .CR getservent() Reads the next line of the file, opening the file if necessary. .TP .CR setservent() Opens and rewinds the file. If the .I stayopen flag is non-zero, the services data base is not closed after each call to .CR getservent() (either directly or indirectly through one of the other .CR getserv* calls). .TP .CR endservent() Closes the file. .TP .CR getservbyname() .PD 0 .TP .CR getservbyport() Each sequentially searches from the beginning of the file until a matching service name (among either the official names or the aliases) or port number is found, or until EOF is encountered. If a non-NULL protocol name is also supplied (such as .CR tcp or .CR udp ), searches must also match the protocol. .PD .IP If the system is running the Network Information Service (NIS), .CR getservbyname() gets the service information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getservent_r() , .CR getservbyname_r() , and .CR getservbyport_r() expect to be passed the address of a .CR "struct servent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct servent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct servent" will point, as well as state information such as open file descriptors. The .CR "struct servent_data" is defined in the file .CR . .PP .CR setservent_r() and .CR endservent_r() are to be used only in conjunction with .CR getservent_r() and take the same pointer to a .CR "struct servent_data" as a parameter. If the Network Information Service is being used, .CR setservent_r() initializes an internal database key. If the .CR /etc/services file is being used, .CR setservent_r() opens or rewinds the file. .CR endservent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setservent_r() currently has no effect. However, .CR setservent() can still be used to keep the .B /etc/services file open when making calls to .CR getservbyname_r() and .CR getservbyport_r() . .PP The .I serv_fp field in the .CR "servent_data struct" must be initialized to NULL before it is passed to either .CR getservent_r() or .CR setservent_r() for the first time. Thereafter it should not be modified in any way. This is the only .CR "servent_data" field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getservbyname() , .CR getservbyport() , .CR getservent() , and their reentrant counterparts, internally call the name service switch to access the "services" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve service names and ports. .SH RETURN VALUE .CR getservent() , .CR getservbyname() , and .CR getservbyport() return a null pointer (0) on EOF or when they are unable to open .CR /etc/services . .PP The reentrant .RC ( _r ) versions of these routines return .CR -1 if the operation is unsuccessful or, in the case of .CR getservent_r() , if the end of the services list has been reached. .CR 0 is returned otherwise. .SH EXAMPLES The following code excerpt counts the number of service entries: .RS .nf .PP .C "int count = 0;" .C "struct servent servbuf;" .C "struct servent_data sdbuf;" .PP .C "sdbuf.serv_fp = NULL;" .C "(void) setservent_r(0, &sdbuf);" .C "while (getservent_r(&servbuf, &sdbuf) != -1)" .C " count++;" .C "(void) endservent_r(&sdbuf);" .fi .RE .SH WARNINGS In the nonreentrant versions of these routines, all information is contained in a static area, so it must be copied if it is to be saved. .PP .CR getservent() , .CR getservbyport() , .CR getservbyname() , .CR setservent() , and .CR endservent() are unsafe in multi-thread applications. .CR getservent_r() , .CR getservbyport_r() , .CR getservbyname_r() , .CR setservent_r() , and .CR endservent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getservent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/services .SH SEE ALSO ypserv(1M), services(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getservent() ": XPG4" .\" .\" index@\f1end service entry@@@\f3getservent(3N)\f1 .\" index@\f1entry, get, set, or end service@@@\f3getservent(3N)\f1 .\" index@\f1get service entry@@@\f3getservent(3N)\f1 .\" index@\f1service entry, get, set, or end@@@\f3getservent(3N)\f1 .\" index@\f1set service entry@@@\f3getservent(3N)\f1 .\" index@\f1thread-safe, get, set, or end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent()\f1 \- end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent_r()\f1 \- end service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservent()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservent_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4setservent()\f1 \- set service entry@@@\f3getservent(3N)\f1 .\" index@\f4setservent_r()\f1 \- set service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" .\" links@getservent.3n endservent.3n .\" links@getservent.3n endservent_.3n .\" links@getservent.3n getservbyna.3n .\" links@getservent.3n getservbypo.3n .\" links@getservent.3n getservent_.3n .\" links@getservent.3n setservent.3n .\" links@getservent.3n setservent_.3n .\" .\" toc@\f3getservent(3N)\f1:\0\0\f4endservent()\f1, \f4endservent_r()\f1, \f4getservbyname()\f1, \f4getservbyname_r()\f1,\n\f4getservbyport()\f1, \f4getservbyport_r()\f1, \f4getservent()\f1, \f4getservent_r()\f1,\n\f4setservent()\f1, \f4setservent_r()\f1@@@get, set, or end service entry .\" .\" toc@\f4endservent()\f1:\0\0end service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4endservent_r()\f1:\0\0end service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent()\f1:\0\0set service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent_r()\f1:\0\0set service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" $Header: getservent.3n,v 78.1 96/03/15 15:57:56 ssa Exp $ .TA g .TH getservent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getservent(), getservent_r(), getservbyport(), getservbyport_r(), getservbyname(), getservbyname_r(), setservent(), setservent_r(), endservent(), endservent_r() \- get service entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct servent *getservent(void);" .PP .C "int getservent_r(struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyname(const char *name, .C " const char *proto);" .PP .C "int getservbyname_r(const char *name," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyport(int port, const char *proto);" .PP .C "int getservbyport_r(int port," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PD .PP .C "int setservent(int stayopen);" .PP .C "int setservent_r(int stayopen, struct servent_data *buffer);" .PP .C "int endservent(void);" .PP .C "int endservent_r(struct servent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setservent(int stayopen);" .C "void endservent(void);" .fi .SH DESCRIPTION The .CR getservent() , .CR getservbyname() , and .CR getservbyport() functions each return a pointer to a structure of type .I servent containing the broken-out fields of a line in the network services data base, .CR /etc/services . .PP The members of this structure are: .RS .TP 15 .CR s_name The official name of the service. .TP .CR s_aliases A null-terminated list of alternate names for the service. .TP .CR s_port The port number at which the service resides. .TP .CR s_proto The name of the protocol to use when contacting the service. .RE .PP Functions behave as follows: .RS .TP 25 .CR getservent() Reads the next line of the file, opening the file if necessary. .TP .CR setservent() Opens and rewinds the file. If the .I stayopen flag is non-zero, the services data base is not closed after each call to .CR getservent() (either directly or indirectly through one of the other .CR getserv* calls). .TP .CR endservent() Closes the file. .TP .CR getservbyname() .PD 0 .TP .CR getservbyport() Each sequentially searches from the beginning of the file until a matching service name (among either the official names or the aliases) or port number is found, or until EOF is encountered. If a non-NULL protocol name is also supplied (such as .CR tcp or .CR udp ), searches must also match the protocol. .PD .IP If the system is running the Network Information Service (NIS), .CR getservbyname() gets the service information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getservent_r() , .CR getservbyname_r() , and .CR getservbyport_r() expect to be passed the address of a .CR "struct servent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct servent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct servent" will point, as well as state information such as open file descriptors. The .CR "struct servent_data" is defined in the file .CR . .PP .CR setservent_r() and .CR endservent_r() are to be used only in conjunction with .CR getservent_r() and take the same pointer to a .CR "struct servent_data" as a parameter. If the Network Information Service is being used, .CR setservent_r() initializes an internal database key. If the .CR /etc/services file is being used, .CR setservent_r() opens or rewinds the file. .CR endservent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setservent_r() currently has no effect. However, .CR setservent() can still be used to keep the .B /etc/services file open when making calls to .CR getservbyname_r() and .CR getservbyport_r() . .PP The .I serv_fp field in the .CR "servent_data struct" must be initialized to NULL before it is passed to either .CR getservent_r() or .CR setservent_r() for the first time. Thereafter it should not be modified in any way. This is the only .CR "servent_data" field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getservbyname() , .CR getservbyport() , .CR getservent() , and their reentrant counterparts, internally call the name service switch to access the "services" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve service names and ports. .SH RETURN VALUE .CR getservent() , .CR getservbyname() , and .CR getservbyport() return a null pointer (0) on EOF or when they are unable to open .CR /etc/services . .PP The reentrant .RC ( _r ) versions of these routines return .CR -1 if the operation is unsuccessful or, in the case of .CR getservent_r() , if the end of the services list has been reached. .CR 0 is returned otherwise. .SH EXAMPLES The following code excerpt counts the number of service entries: .RS .nf .PP .C "int count = 0;" .C "struct servent servbuf;" .C "struct servent_data sdbuf;" .PP .C "sdbuf.serv_fp = NULL;" .C "(void) setservent_r(0, &sdbuf);" .C "while (getservent_r(&servbuf, &sdbuf) != -1)" .C " count++;" .C "(void) endservent_r(&sdbuf);" .fi .RE .SH WARNINGS In the nonreentrant versions of these routines, all information is contained in a static area, so it must be copied if it is to be saved. .PP .CR getservent() , .CR getservbyport() , .CR getservbyname() , .CR setservent() , and .CR endservent() are unsafe in multi-thread applications. .CR getservent_r() , .CR getservbyport_r() , .CR getservbyname_r() , .CR setservent_r() , and .CR endservent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getservent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/services .SH SEE ALSO ypserv(1M), services(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getservent() ": XPG4" .\" .\" index@\f1end service entry@@@\f3getservent(3N)\f1 .\" index@\f1entry, get, set, or end service@@@\f3getservent(3N)\f1 .\" index@\f1get service entry@@@\f3getservent(3N)\f1 .\" index@\f1service entry, get, set, or end@@@\f3getservent(3N)\f1 .\" index@\f1set service entry@@@\f3getservent(3N)\f1 .\" index@\f1thread-safe, get, set, or end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent()\f1 \- end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent_r()\f1 \- end service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservent()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservent_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4setservent()\f1 \- set service entry@@@\f3getservent(3N)\f1 .\" index@\f4setservent_r()\f1 \- set service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" .\" links@getservent.3n endservent.3n .\" links@getservent.3n endservent_.3n .\" links@getservent.3n getservbyna.3n .\" links@getservent.3n getservbypo.3n .\" links@getservent.3n getservent_.3n .\" links@getservent.3n setservent.3n .\" links@getservent.3n setservent_.3n .\" .\" toc@\f3getservent(3N)\f1:\0\0\f4endservent()\f1, \f4endservent_r()\f1, \f4getservbyname()\f1, \f4getservbyname_r()\f1,\n\f4getservbyport()\f1, \f4getservbyport_r()\f1, \f4getservent()\f1, \f4getservent_r()\f1,\n\f4setservent()\f1, \f4setservent_r()\f1@@@get, set, or end service entry .\" .\" toc@\f4endservent()\f1:\0\0end service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4endservent_r()\f1:\0\0end service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent()\f1:\0\0set service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent_r()\f1:\0\0set service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" $Header: getservent.3n,v 78.1 96/03/15 15:57:56 ssa Exp $ .TA g .TH getservent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getservent(), getservent_r(), getservbyport(), getservbyport_r(), getservbyname(), getservbyname_r(), setservent(), setservent_r(), endservent(), endservent_r() \- get service entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct servent *getservent(void);" .PP .C "int getservent_r(struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyname(const char *name, .C " const char *proto);" .PP .C "int getservbyname_r(const char *name," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyport(int port, const char *proto);" .PP .C "int getservbyport_r(int port," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PD .PP .C "int setservent(int stayopen);" .PP .C "int setservent_r(int stayopen, struct servent_data *buffer);" .PP .C "int endservent(void);" .PP .C "int endservent_r(struct servent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setservent(int stayopen);" .C "void endservent(void);" .fi .SH DESCRIPTION The .CR getservent() , .CR getservbyname() , and .CR getservbyport() functions each return a pointer to a structure of type .I servent containing the broken-out fields of a line in the network services data base, .CR /etc/services . .PP The members of this structure are: .RS .TP 15 .CR s_name The official name of the service. .TP .CR s_aliases A null-terminated list of alternate names for the service. .TP .CR s_port The port number at which the service resides. .TP .CR s_proto The name of the protocol to use when contacting the service. .RE .PP Functions behave as follows: .RS .TP 25 .CR getservent() Reads the next line of the file, opening the file if necessary. .TP .CR setservent() Opens and rewinds the file. If the .I stayopen flag is non-zero, the services data base is not closed after each call to .CR getservent() (either directly or indirectly through one of the other .CR getserv* calls). .TP .CR endservent() Closes the file. .TP .CR getservbyname() .PD 0 .TP .CR getservbyport() Each sequentially searches from the beginning of the file until a matching service name (among either the official names or the aliases) or port number is found, or until EOF is encountered. If a non-NULL protocol name is also supplied (such as .CR tcp or .CR udp ), searches must also match the protocol. .PD .IP If the system is running the Network Information Service (NIS), .CR getservbyname() gets the service information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getservent_r() , .CR getservbyname_r() , and .CR getservbyport_r() expect to be passed the address of a .CR "struct servent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct servent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct servent" will point, as well as state information such as open file descriptors. The .CR "struct servent_data" is defined in the file .CR . .PP .CR setservent_r() and .CR endservent_r() are to be used only in conjunction with .CR getservent_r() and take the same pointer to a .CR "struct servent_data" as a parameter. If the Network Information Service is being used, .CR setservent_r() initializes an internal database key. If the .CR /etc/services file is being used, .CR setservent_r() opens or rewinds the file. .CR endservent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setservent_r() currently has no effect. However, .CR setservent() can still be used to keep the .B /etc/services file open when making calls to .CR getservbyname_r() and .CR getservbyport_r() . .PP The .I serv_fp field in the .CR "servent_data struct" must be initialized to NULL before it is passed to either .CR getservent_r() or .CR setservent_r() for the first time. Thereafter it should not be modified in any way. This is the only .CR "servent_data" field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getservbyname() , .CR getservbyport() , .CR getservent() , and their reentrant counterparts, internally call the name service switch to access the "services" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve service names and ports. .SH RETURN VALUE .CR getservent() , .CR getservbyname() , and .CR getservbyport() return a null pointer (0) on EOF or when they are unable to open .CR /etc/services . .PP The reentrant .RC ( _r ) versions of these routines return .CR -1 if the operation is unsuccessful or, in the case of .CR getservent_r() , if the end of the services list has been reached. .CR 0 is returned otherwise. .SH EXAMPLES The following code excerpt counts the number of service entries: .RS .nf .PP .C "int count = 0;" .C "struct servent servbuf;" .C "struct servent_data sdbuf;" .PP .C "sdbuf.serv_fp = NULL;" .C "(void) setservent_r(0, &sdbuf);" .C "while (getservent_r(&servbuf, &sdbuf) != -1)" .C " count++;" .C "(void) endservent_r(&sdbuf);" .fi .RE .SH WARNINGS In the nonreentrant versions of these routines, all information is contained in a static area, so it must be copied if it is to be saved. .PP .CR getservent() , .CR getservbyport() , .CR getservbyname() , .CR setservent() , and .CR endservent() are unsafe in multi-thread applications. .CR getservent_r() , .CR getservbyport_r() , .CR getservbyname_r() , .CR setservent_r() , and .CR endservent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getservent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/services .SH SEE ALSO ypserv(1M), services(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getservent() ": XPG4" .\" .\" index@\f1end service entry@@@\f3getservent(3N)\f1 .\" index@\f1entry, get, set, or end service@@@\f3getservent(3N)\f1 .\" index@\f1get service entry@@@\f3getservent(3N)\f1 .\" index@\f1service entry, get, set, or end@@@\f3getservent(3N)\f1 .\" index@\f1set service entry@@@\f3getservent(3N)\f1 .\" index@\f1thread-safe, get, set, or end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent()\f1 \- end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent_r()\f1 \- end service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservent()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservent_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4setservent()\f1 \- set service entry@@@\f3getservent(3N)\f1 .\" index@\f4setservent_r()\f1 \- set service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" .\" links@getservent.3n endservent.3n .\" links@getservent.3n endservent_.3n .\" links@getservent.3n getservbyna.3n .\" links@getservent.3n getservbypo.3n .\" links@getservent.3n getservent_.3n .\" links@getservent.3n setservent.3n .\" links@getservent.3n setservent_.3n .\" .\" toc@\f3getservent(3N)\f1:\0\0\f4endservent()\f1, \f4endservent_r()\f1, \f4getservbyname()\f1, \f4getservbyname_r()\f1,\n\f4getservbyport()\f1, \f4getservbyport_r()\f1, \f4getservent()\f1, \f4getservent_r()\f1,\n\f4setservent()\f1, \f4setservent_r()\f1@@@get, set, or end service entry .\" .\" toc@\f4endservent()\f1:\0\0end service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4endservent_r()\f1:\0\0end service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent()\f1:\0\0set service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent_r()\f1:\0\0set service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" $Header: getspent.3c,v 72.3 94/07/03 15:08:29 ssa Exp $ .TA g .TH getspent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME .CR getspent , .CR getspnam , .CR setspent , .C endspent \- access secure password entries, for trusted systems only. .SH SYNOPSIS .C #include .br .C struct spwd * getspent (void); .br .C struct spwd * getspnam (const char *name); .br .C void setspent (void) .br .C void endspent (void) .SH DESCRIPTION The routines .CR getspent () and .CR getspnam () return a pointer to the next secured password entry. Each entry is a .C spwd structure, declared in the .C shadow.h header file with the following members: .nf .IP .CR "char *sp_namp; " "/* the user's login name */" .CR "char *sp_pwdp; " "/* the encrypted password for the user */" .CR "long sp_lstchg; " "/* # of days from 1/1/70 when passwd was last modified */" .CR "long sp_min; " "/* min # of days allowed between password changes */" .CR "long sp_max; " "/* max # of days allowed between password changes */" .CR "long sp_warn; " "/* # of days before password expires and warning issued*/" .CR "long sp_inact; " "/* # of days between account inactive and disabled */" .CR "long sp_expire; " "/* # of days from 1/1/70 when account is locked */" .CR "unsigned long sp_flag;" "/* currently unused */" .fi .PP The .CR getspent () routine returns a pointer to the first .C spwd structure when first called. Subsequent calls return pointers to successive .C spwd structures. Repeated calls to .CR getspent () can be used to search all entries in the protected password database. The .C getspnam () routine searches password entries from beginning to end until a login name matching .I name is found, and returns a pointer to that entry. .PP If the fields corresponding to .CR sp_min , .CR sp_max , .CR sp_lstchg , .CR sp_warn , .CR sp_inact , .CR sp_expire , or .C sp_flag are not specified in the entry, they default to -1. If an end-of-file or an error is encountered in reading or a format error is detected, these functions return a null pointer and; for an error, .C errno is set to .CR EINVAL . .PP The .CR setspent () routine is used to reset access to the secured password entries. After .CR setspent () is called, the subsequent call to .CR getspent () returns the first secured password entry. This mechanism is used to allow repeated searches of the secured password entries. The .CR endspent () routine is used to indicate that processing of secured password entries is complete. .PP .CR getspent () is only supported on trusted systems. .PP The secured password facility is implemented without the use of the .C /etc/shadow file. .CR getspent (), .CR getspnam (), .CR setspent (), and .CR endspent () read from the trusted system's protected password database .RC ( /tcb/files/auth/\c .I *\c .C /\c .IR * ) and not .CR /etc/shadow . The file .C /etc/shadow is not used in any way by the HP-UX login facility. .PP These routines return a null pointer and sets ERRNO to ENOENT if the system has not been converted to trusted system. In all other cases, the return value is set similarly to .CR getprpwent (). See .IR getprpwent (3) for more information. .PP Programs using these routines must be compiled with .CR \-lsec . .SH FILES .TP 30 .PD 0 .C /etc/passwd System Password file. .TP .CR /tcb/files/auth/*/* Protected password database, for trusted systems. .PD .SH SEE ALSO getpwent(3C), getprpwent(3C), passwd(4). .SH DIAGNOSTICS .CR getspent (), .CR getspnam (), and .CR fgetspent () return a null pointer on EOF or error. .SH STANDARDS CONFORMANCE .C getspent : SVID3 .\" index@\f4getspent()\fP \- get next secure password file entry@@@\f3getspent(3C)\f1 .\" index@\f4getspnam()\fP \- get secure password file entry matching \f4name()\fP@@@\f3getspent(3C)\f1 .\" index@\f4setspent()\fP \- rewind pointer to beginning of secure password file@@@\f3getspent(3C)\f1 .\" index@\f4endspent()\fP \- close currently open secure password file@@@\f3getspent(3C)\f1 .\" index@entry from secure password file, get@@@\f3getspent(3C)\f1 .\" index@trusted system password database, get entry from@@@\f3getspent(3C)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspent(3C)\f1 .\" .\" toc@\f3getspent(3C)\f1:\0\0\f4getspent()\fP, \f4getspnam()\fP, \f4setspent()\fP, \f4endspent()\fP@@@get secure password file entry .\" toc@\f4getspent()\fP:\0\0get secure password file entry@@@see \f3getspent(3C)\f1 .\" toc@\f4setpwent()\fP:\0\0get secure password file entry@@@see \f3getspent(3C)\f1 .\" toc@\f4endpwent()\fP:\0\0get secure password file entry@@@see \f3getspent(3C)\f1 .\" .\" links@getspent.3c getspnam.3c .\" links@getspent.3c setspent.3c .\" links@getspent.3c endspent.3c .\" .\" $Header: getspent.3c,v 72.3 94/07/03 15:08:29 ssa Exp $ .TA g .TH getspent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME .CR getspent , .CR getspnam , .CR setspent , .C endspent \- access secure password entries, for trusted systems only. .SH SYNOPSIS .C #include .br .C struct spwd * getspent (void); .br .C struct spwd * getspnam (const char *name); .br .C void setspent (void) .br .C void endspent (void) .SH DESCRIPTION The routines .CR getspent () and .CR getspnam () return a pointer to the next secured password entry. Each entry is a .C spwd structure, declared in the .C shadow.h header file with the following members: .nf .IP .CR "char *sp_namp; " "/* the user's login name */" .CR "char *sp_pwdp; " "/* the encrypted password for the user */" .CR "long sp_lstchg; " "/* # of days from 1/1/70 when passwd was last modified */" .CR "long sp_min; " "/* min # of days allowed between password changes */" .CR "long sp_max; " "/* max # of days allowed between password changes */" .CR "long sp_warn; " "/* # of days before password expires and warning issued*/" .CR "long sp_inact; " "/* # of days between account inactive and disabled */" .CR "long sp_expire; " "/* # of days from 1/1/70 when account is locked */" .CR "unsigned long sp_flag;" "/* currently unused */" .fi .PP The .CR getspent () routine returns a pointer to the first .C spwd structure when first called. Subsequent calls return pointers to successive .C spwd structures. Repeated calls to .CR getspent () can be used to search all entries in the protected password database. The .C getspnam () routine searches password entries from beginning to end until a login name matching .I name is found, and returns a pointer to that entry. .PP If the fields corresponding to .CR sp_min , .CR sp_max , .CR sp_lstchg , .CR sp_warn , .CR sp_inact , .CR sp_expire , or .C sp_flag are not specified in the entry, they default to -1. If an end-of-file or an error is encountered in reading or a format error is detected, these functions return a null pointer and; for an error, .C errno is set to .CR EINVAL . .PP The .CR setspent () routine is used to reset access to the secured password entries. After .CR setspent () is called, the subsequent call to .CR getspent () returns the first secured password entry. This mechanism is used to allow repeated searches of the secured password entries. The .CR endspent () routine is used to indicate that processing of secured password entries is complete. .PP .CR getspent () is only supported on trusted systems. .PP The secured password facility is implemented without the use of the .C /etc/shadow file. .CR getspent (), .CR getspnam (), .CR setspent (), and .CR endspent () read from the trusted system's protected password database .RC ( /tcb/files/auth/\c .I *\c .C /\c .IR * ) and not .CR /etc/shadow . The file .C /etc/shadow is not used in any way by the HP-UX login facility. .PP These routines return a null pointer and sets ERRNO to ENOENT if the system has not been converted to trusted system. In all other cases, the return value is set similarly to .CR getprpwent (). See .IR getprpwent (3) for more information. .PP Programs using these routines must be compiled with .CR \-lsec . .SH FILES .TP 30 .PD 0 .C /etc/passwd System Password file. .TP .CR /tcb/files/auth/*/* Protected password database, for trusted systems. .PD .SH SEE ALSO getpwent(3C), getprpwent(3C), passwd(4). .SH DIAGNOSTICS .CR getspent (), .CR getspnam (), and .CR fgetspent () return a null pointer on EOF or error. .SH STANDARDS CONFORMANCE .C getspent : SVID3 .\" index@\f4getspent()\fP \- get next secure password file entry@@@\f3getspent(3C)\f1 .\" index@\f4getspnam()\fP \- get secure password file entry matching \f4name()\fP@@@\f3getspent(3C)\f1 .\" index@\f4setspent()\fP \- rewind pointer to beginning of secure password file@@@\f3getspent(3C)\f1 .\" index@\f4endspent()\fP \- close currently open secure password file@@@\f3getspent(3C)\f1 .\" index@entry from secure password file, get@@@\f3getspent(3C)\f1 .\" index@trusted system password database, get entry from@@@\f3getspent(3C)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspent(3C)\f1 .\" .\" toc@\f3getspent(3C)\f1:\0\0\f4getspent()\fP, \f4getspnam()\fP, \f4setspent()\fP, \f4endspent()\fP@@@get secure password file entry .\" toc@\f4getspent()\fP:\0\0get secure password file entry@@@see \f3getspent(3C)\f1 .\" toc@\f4setpwent()\fP:\0\0get secure password file entry@@@see \f3getspent(3C)\f1 .\" toc@\f4endpwent()\fP:\0\0get secure password file entry@@@see \f3getspent(3C)\f1 .\" .\" links@getspent.3c getspnam.3c .\" links@getspent.3c setspent.3c .\" links@getspent.3c endspent.3c .\" .\" $Header: getspwent.3x,v 72.6 94/11/30 10:11:44 ssa Exp $ .TA g .TH getspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getspwent(\|), getspwent_r(\|), getspwuid(\|), getspwuid_r(\|), getspwaid(\|), getspwaid_r(\|), getspwnam(\|), getspwnam_r(\|), setspwent(\|), setspwent_r(\|), endspwent(\|), endspwent_r(\|), fgetspwent(\|), fgetspwent_r(\|) \- get secure password file entry\c , on trusted systems .SH SYNOPSIS .C "#include " .PP .C "struct s_passwd *getspwent(void);" .PP .C "int getspwent_r(struct s_passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct s_passwd *getspwuid(uid_t uid);" .PP .PD 0 .C "int getspwuid_r(uid_t uid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwaid(aid_t aid);" .PP .PD 0 .C "int getspwaid_r(aid_t aid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwnam(const char *name);" .PP .PD 0 .C "int getspwnam_r(char *name, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setspwent(void);" .PP .C "void setspwent_r(FILE **pwfp);" .PP .C "void endspwent(void);" .PP .C "void endspwent_r(FILE **pwfp);" .PP .C "struct s_passwd *fgetspwent(\s-1FILE\s0 *stream);" .PP .PD 0 .C "int fgetspwent_r(FILE *f, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .SH DESCRIPTION These privileged routines provide access to the protected password database in a manner similar to the way .IR getpwent (3C) routines handle the regular password file, .RC ( \|/etc/passwd\| ). .PP These routines are particularly useful in situations where it is not necessary to get information from the regular password file. .IR getspwent (3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, .CR libsec . .PP Note that .CR getspwent () routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the .CR getprpwent () routines. See .IR getprpwent (3). .PP .CR getspwent (), .CR getspwuid (), .CR getspwaid (), and .CR getspwnam () each returns a pointer to an object of .CR s_passwd structure. The .CR s_passwd structure is maintained for compatibility with existing software and consists of five fields as follows: .nf .IP .C "struct\ s_passwd\ {" .C " char *pw_name; /* login name */" .C " char *pw_passwd; /* encrypted password */" .C " char *pw_age; /* password age */" .C " int pw_audid; /* audit ID */" .C " int pw_audflg; /* audit flag 1=on, 0=off */" .C }; .fi .PP Since the .CR s_passwd structure is declared in the .RC < pwd.h > header file, it is unnecessary to redeclare it. .PP To access other fields in the protected password database that are not included in the .CR s_passwd structure, use .CR getprpwent (). See .IR getprpwent (3) for more information. .PP .TP 20 .CR getspwent () When first called, .CR getspwent () returns a pointer to each .CR s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database. .TP .CR getspwuid () Searches for an entry that matches the specified .IR uid . It then returns a pointer to the particular structure in which .I uid is found. .TP .CR getspwaid () Similarly searches for a numerical audit ID matching .I aid and returns a pointer to the particular structure in which .I aid is found (see .IR spasswd (4) for details on this field). .TP .CR getspwnam () Searches for an entry that matches the specified .IR name . Returns a pointer to the particular structure in which .I name is found. .TP .CR setspwent () Resets the protected password database pointer to the beginning of the file to allow repeated searches. .TP .CR endspwent () Should be called to close the protected password database file when processing is complete. .TP .CR fgetspwent () Is no longer supported. It is provided for those applications that did not use .CR /.secure/etc/passwd . .SS Reentrant Interfaces .CR getspwuid_r (), .CR getspwaid_r (), .CR getspwnam_r (), and .CR fgetspwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .CR s_passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in the .CR s_passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getspwent_r () requires a pointer to a .RI ( "FILE *" ) variable. .CR setspwent_r () and .CR endspwent_r () are to be used only in conjunction with .CR getspwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setspwent_r () can be used to rewind or open the protected password database. .CR endspwent_r () should be called when done to close the file. .PP The .CR /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database. .PP .CR fgetspwent_r () is no longer supported, but is included for those users that did not use the .CR /.secure/etc/passwd file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getspwent_r () or .CR setspwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH RETURN VALUE .CR getspwent () returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the calling process is not zero. .PP .CR getspwent_r () returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned. .SH WARNINGS The above routines use .RC < stdio.h >, which causes them to increase the size of programs by more than might otherwise be expected. .PP Since all information for .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() is contained in a static area, it must be copied to be saved. .PP .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() are unsafe in multi-thread applications. .CR getspwent_r() , .CR getspwuid_r() , .CR getspwaid_r() , .CR getspwnam_r() , .CR setspwent_r() , .CR endspwent_r() , and .CR fgetspwent_r() are MT-Safe and should be used instead. .PP Network Information Service is not supported on trusted systems. .SH EXAMPLE The following code excerpt counts the number of entries in the protected password database: .nf .IP .C "int count = 0;" .C "struct s_passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setspwent_r(&pwf);" .C "while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endspwent_r(&pwf);" .SH AUTHOR .CR getspwent () was developed by HP. .SH FILES .TP 30 .C /tcb/files/auth/*/* Protected Password database .SH SEE ALSO ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), putspwent(3X), passwd(4). .\" .\" index@\f4getspwent()\f1 \- get next secure password file entry@@@\f3getspwent(3X)\f1 .\" index@\f4getspwaid()\f1 \- get next secure password file audit ID@@@\f3getspwent(3X)\f1 .\" index@\f4fgetspwent()\f1 \- get next entry in secure password-file-formatted input stream@@@\f3getspwent(3X)\f1 .\" index@\f4getspwuid()\f1 \- get secure password file entry matching \f4uid()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4getspwnam()\f1 \- get secure password file entry matching login name \f4name()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4setspwent()\f1 \- rewind pointer to beginning of secure password file@@@\f3getspwent(3X)\f1 .\" index@\f4endspwent()\f1 \- close currently open secure password file@@@\f3getspwent(3X)\f1 .\" index@entry from secure password file, get@@@\f3getspwent(3X)\f1 .\" index@secure password file, get entry from@@@\f3getspwent(3X)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspwent(3C)\f1 .\" .\" toc@\f3getspwent(3X)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f1,\n\f4endpwent()\f1, \f4fgetpwent()\f1@@@get secure password file entry .\" toc@\f4getpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4setpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4endpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4getspwaid()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" .\" links@getspwent.3x getspwuid.3x .\" links@getspwent.3x getspwnam.3x .\" links@getspwent.3x setspwent.3x .\" links@getspwent.3x endspwent.3x .\" links@getspwent.3x fgetspwent.3x .\" links@getspwent.3x getspwaid.3x .\" links@getspwent.3x getspwent_r.3x .\" links@getspwent.3x getspwuid_r.3x .\" links@getspwent.3x getspwaid_r.3x .\" links@getspwent.3x getspwnam_r.3x .\" links@getspwent.3x setspwent_r.3x .\" links@getspwent.3x endspwent_r.3x .\" links@getspwent.3x fgetspwent_.3x .\" .\" fileset_database@getspwent.3x PROGRAMING-MAN .\" $Header: getspwent.3x,v 72.6 94/11/30 10:11:44 ssa Exp $ .TA g .TH getspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getspwent(\|), getspwent_r(\|), getspwuid(\|), getspwuid_r(\|), getspwaid(\|), getspwaid_r(\|), getspwnam(\|), getspwnam_r(\|), setspwent(\|), setspwent_r(\|), endspwent(\|), endspwent_r(\|), fgetspwent(\|), fgetspwent_r(\|) \- get secure password file entry\c , on trusted systems .SH SYNOPSIS .C "#include " .PP .C "struct s_passwd *getspwent(void);" .PP .C "int getspwent_r(struct s_passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct s_passwd *getspwuid(uid_t uid);" .PP .PD 0 .C "int getspwuid_r(uid_t uid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwaid(aid_t aid);" .PP .PD 0 .C "int getspwaid_r(aid_t aid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwnam(const char *name);" .PP .PD 0 .C "int getspwnam_r(char *name, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setspwent(void);" .PP .C "void setspwent_r(FILE **pwfp);" .PP .C "void endspwent(void);" .PP .C "void endspwent_r(FILE **pwfp);" .PP .C "struct s_passwd *fgetspwent(\s-1FILE\s0 *stream);" .PP .PD 0 .C "int fgetspwent_r(FILE *f, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .SH DESCRIPTION These privileged routines provide access to the protected password database in a manner similar to the way .IR getpwent (3C) routines handle the regular password file, .RC ( \|/etc/passwd\| ). .PP These routines are particularly useful in situations where it is not necessary to get information from the regular password file. .IR getspwent (3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, .CR libsec . .PP Note that .CR getspwent () routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the .CR getprpwent () routines. See .IR getprpwent (3). .PP .CR getspwent (), .CR getspwuid (), .CR getspwaid (), and .CR getspwnam () each returns a pointer to an object of .CR s_passwd structure. The .CR s_passwd structure is maintained for compatibility with existing software and consists of five fields as follows: .nf .IP .C "struct\ s_passwd\ {" .C " char *pw_name; /* login name */" .C " char *pw_passwd; /* encrypted password */" .C " char *pw_age; /* password age */" .C " int pw_audid; /* audit ID */" .C " int pw_audflg; /* audit flag 1=on, 0=off */" .C }; .fi .PP Since the .CR s_passwd structure is declared in the .RC < pwd.h > header file, it is unnecessary to redeclare it. .PP To access other fields in the protected password database that are not included in the .CR s_passwd structure, use .CR getprpwent (). See .IR getprpwent (3) for more information. .PP .TP 20 .CR getspwent () When first called, .CR getspwent () returns a pointer to each .CR s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database. .TP .CR getspwuid () Searches for an entry that matches the specified .IR uid . It then returns a pointer to the particular structure in which .I uid is found. .TP .CR getspwaid () Similarly searches for a numerical audit ID matching .I aid and returns a pointer to the particular structure in which .I aid is found (see .IR spasswd (4) for details on this field). .TP .CR getspwnam () Searches for an entry that matches the specified .IR name . Returns a pointer to the particular structure in which .I name is found. .TP .CR setspwent () Resets the protected password database pointer to the beginning of the file to allow repeated searches. .TP .CR endspwent () Should be called to close the protected password database file when processing is complete. .TP .CR fgetspwent () Is no longer supported. It is provided for those applications that did not use .CR /.secure/etc/passwd . .SS Reentrant Interfaces .CR getspwuid_r (), .CR getspwaid_r (), .CR getspwnam_r (), and .CR fgetspwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .CR s_passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in the .CR s_passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getspwent_r () requires a pointer to a .RI ( "FILE *" ) variable. .CR setspwent_r () and .CR endspwent_r () are to be used only in conjunction with .CR getspwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setspwent_r () can be used to rewind or open the protected password database. .CR endspwent_r () should be called when done to close the file. .PP The .CR /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database. .PP .CR fgetspwent_r () is no longer supported, but is included for those users that did not use the .CR /.secure/etc/passwd file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getspwent_r () or .CR setspwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH RETURN VALUE .CR getspwent () returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the calling process is not zero. .PP .CR getspwent_r () returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned. .SH WARNINGS The above routines use .RC < stdio.h >, which causes them to increase the size of programs by more than might otherwise be expected. .PP Since all information for .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() is contained in a static area, it must be copied to be saved. .PP .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() are unsafe in multi-thread applications. .CR getspwent_r() , .CR getspwuid_r() , .CR getspwaid_r() , .CR getspwnam_r() , .CR setspwent_r() , .CR endspwent_r() , and .CR fgetspwent_r() are MT-Safe and should be used instead. .PP Network Information Service is not supported on trusted systems. .SH EXAMPLE The following code excerpt counts the number of entries in the protected password database: .nf .IP .C "int count = 0;" .C "struct s_passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setspwent_r(&pwf);" .C "while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endspwent_r(&pwf);" .SH AUTHOR .CR getspwent () was developed by HP. .SH FILES .TP 30 .C /tcb/files/auth/*/* Protected Password database .SH SEE ALSO ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), putspwent(3X), passwd(4). .\" .\" index@\f4getspwent()\f1 \- get next secure password file entry@@@\f3getspwent(3X)\f1 .\" index@\f4getspwaid()\f1 \- get next secure password file audit ID@@@\f3getspwent(3X)\f1 .\" index@\f4fgetspwent()\f1 \- get next entry in secure password-file-formatted input stream@@@\f3getspwent(3X)\f1 .\" index@\f4getspwuid()\f1 \- get secure password file entry matching \f4uid()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4getspwnam()\f1 \- get secure password file entry matching login name \f4name()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4setspwent()\f1 \- rewind pointer to beginning of secure password file@@@\f3getspwent(3X)\f1 .\" index@\f4endspwent()\f1 \- close currently open secure password file@@@\f3getspwent(3X)\f1 .\" index@entry from secure password file, get@@@\f3getspwent(3X)\f1 .\" index@secure password file, get entry from@@@\f3getspwent(3X)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspwent(3C)\f1 .\" .\" toc@\f3getspwent(3X)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f1,\n\f4endpwent()\f1, \f4fgetpwent()\f1@@@get secure password file entry .\" toc@\f4getpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4setpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4endpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4getspwaid()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" .\" links@getspwent.3x getspwuid.3x .\" links@getspwent.3x getspwnam.3x .\" links@getspwent.3x setspwent.3x .\" links@getspwent.3x endspwent.3x .\" links@getspwent.3x fgetspwent.3x .\" links@getspwent.3x getspwaid.3x .\" links@getspwent.3x getspwent_r.3x .\" links@getspwent.3x getspwuid_r.3x .\" links@getspwent.3x getspwaid_r.3x .\" links@getspwent.3x getspwnam_r.3x .\" links@getspwent.3x setspwent_r.3x .\" links@getspwent.3x endspwent_r.3x .\" links@getspwent.3x fgetspwent_.3x .\" .\" fileset_database@getspwent.3x PROGRAMING-MAN .\" $Header: getspwent.3x,v 72.6 94/11/30 10:11:44 ssa Exp $ .TA g .TH getspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getspwent(\|), getspwent_r(\|), getspwuid(\|), getspwuid_r(\|), getspwaid(\|), getspwaid_r(\|), getspwnam(\|), getspwnam_r(\|), setspwent(\|), setspwent_r(\|), endspwent(\|), endspwent_r(\|), fgetspwent(\|), fgetspwent_r(\|) \- get secure password file entry\c , on trusted systems .SH SYNOPSIS .C "#include " .PP .C "struct s_passwd *getspwent(void);" .PP .C "int getspwent_r(struct s_passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct s_passwd *getspwuid(uid_t uid);" .PP .PD 0 .C "int getspwuid_r(uid_t uid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwaid(aid_t aid);" .PP .PD 0 .C "int getspwaid_r(aid_t aid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwnam(const char *name);" .PP .PD 0 .C "int getspwnam_r(char *name, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setspwent(void);" .PP .C "void setspwent_r(FILE **pwfp);" .PP .C "void endspwent(void);" .PP .C "void endspwent_r(FILE **pwfp);" .PP .C "struct s_passwd *fgetspwent(\s-1FILE\s0 *stream);" .PP .PD 0 .C "int fgetspwent_r(FILE *f, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .SH DESCRIPTION These privileged routines provide access to the protected password database in a manner similar to the way .IR getpwent (3C) routines handle the regular password file, .RC ( \|/etc/passwd\| ). .PP These routines are particularly useful in situations where it is not necessary to get information from the regular password file. .IR getspwent (3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, .CR libsec . .PP Note that .CR getspwent () routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the .CR getprpwent () routines. See .IR getprpwent (3). .PP .CR getspwent (), .CR getspwuid (), .CR getspwaid (), and .CR getspwnam () each returns a pointer to an object of .CR s_passwd structure. The .CR s_passwd structure is maintained for compatibility with existing software and consists of five fields as follows: .nf .IP .C "struct\ s_passwd\ {" .C " char *pw_name; /* login name */" .C " char *pw_passwd; /* encrypted password */" .C " char *pw_age; /* password age */" .C " int pw_audid; /* audit ID */" .C " int pw_audflg; /* audit flag 1=on, 0=off */" .C }; .fi .PP Since the .CR s_passwd structure is declared in the .RC < pwd.h > header file, it is unnecessary to redeclare it. .PP To access other fields in the protected password database that are not included in the .CR s_passwd structure, use .CR getprpwent (). See .IR getprpwent (3) for more information. .PP .TP 20 .CR getspwent () When first called, .CR getspwent () returns a pointer to each .CR s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database. .TP .CR getspwuid () Searches for an entry that matches the specified .IR uid . It then returns a pointer to the particular structure in which .I uid is found. .TP .CR getspwaid () Similarly searches for a numerical audit ID matching .I aid and returns a pointer to the particular structure in which .I aid is found (see .IR spasswd (4) for details on this field). .TP .CR getspwnam () Searches for an entry that matches the specified .IR name . Returns a pointer to the particular structure in which .I name is found. .TP .CR setspwent () Resets the protected password database pointer to the beginning of the file to allow repeated searches. .TP .CR endspwent () Should be called to close the protected password database file when processing is complete. .TP .CR fgetspwent () Is no longer supported. It is provided for those applications that did not use .CR /.secure/etc/passwd . .SS Reentrant Interfaces .CR getspwuid_r (), .CR getspwaid_r (), .CR getspwnam_r (), and .CR fgetspwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .CR s_passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in the .CR s_passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getspwent_r () requires a pointer to a .RI ( "FILE *" ) variable. .CR setspwent_r () and .CR endspwent_r () are to be used only in conjunction with .CR getspwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setspwent_r () can be used to rewind or open the protected password database. .CR endspwent_r () should be called when done to close the file. .PP The .CR /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database. .PP .CR fgetspwent_r () is no longer supported, but is included for those users that did not use the .CR /.secure/etc/passwd file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getspwent_r () or .CR setspwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH RETURN VALUE .CR getspwent () returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the calling process is not zero. .PP .CR getspwent_r () returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned. .SH WARNINGS The above routines use .RC < stdio.h >, which causes them to increase the size of programs by more than might otherwise be expected. .PP Since all information for .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() is contained in a static area, it must be copied to be saved. .PP .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() are unsafe in multi-thread applications. .CR getspwent_r() , .CR getspwuid_r() , .CR getspwaid_r() , .CR getspwnam_r() , .CR setspwent_r() , .CR endspwent_r() , and .CR fgetspwent_r() are MT-Safe and should be used instead. .PP Network Information Service is not supported on trusted systems. .SH EXAMPLE The following code excerpt counts the number of entries in the protected password database: .nf .IP .C "int count = 0;" .C "struct s_passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setspwent_r(&pwf);" .C "while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endspwent_r(&pwf);" .SH AUTHOR .CR getspwent () was developed by HP. .SH FILES .TP 30 .C /tcb/files/auth/*/* Protected Password database .SH SEE ALSO ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), putspwent(3X), passwd(4). .\" .\" index@\f4getspwent()\f1 \- get next secure password file entry@@@\f3getspwent(3X)\f1 .\" index@\f4getspwaid()\f1 \- get next secure password file audit ID@@@\f3getspwent(3X)\f1 .\" index@\f4fgetspwent()\f1 \- get next entry in secure password-file-formatted input stream@@@\f3getspwent(3X)\f1 .\" index@\f4getspwuid()\f1 \- get secure password file entry matching \f4uid()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4getspwnam()\f1 \- get secure password file entry matching login name \f4name()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4setspwent()\f1 \- rewind pointer to beginning of secure password file@@@\f3getspwent(3X)\f1 .\" index@\f4endspwent()\f1 \- close currently open secure password file@@@\f3getspwent(3X)\f1 .\" index@entry from secure password file, get@@@\f3getspwent(3X)\f1 .\" index@secure password file, get entry from@@@\f3getspwent(3X)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspwent(3C)\f1 .\" .\" toc@\f3getspwent(3X)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f1,\n\f4endpwent()\f1, \f4fgetpwent()\f1@@@get secure password file entry .\" toc@\f4getpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4setpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4endpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4getspwaid()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" .\" links@getspwent.3x getspwuid.3x .\" links@getspwent.3x getspwnam.3x .\" links@getspwent.3x setspwent.3x .\" links@getspwent.3x endspwent.3x .\" links@getspwent.3x fgetspwent.3x .\" links@getspwent.3x getspwaid.3x .\" links@getspwent.3x getspwent_r.3x .\" links@getspwent.3x getspwuid_r.3x .\" links@getspwent.3x getspwaid_r.3x .\" links@getspwent.3x getspwnam_r.3x .\" links@getspwent.3x setspwent_r.3x .\" links@getspwent.3x endspwent_r.3x .\" links@getspwent.3x fgetspwent_.3x .\" .\" fileset_database@getspwent.3x PROGRAMING-MAN .\" $Header: getspwent.3x,v 72.6 94/11/30 10:11:44 ssa Exp $ .TA g .TH getspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getspwent(\|), getspwent_r(\|), getspwuid(\|), getspwuid_r(\|), getspwaid(\|), getspwaid_r(\|), getspwnam(\|), getspwnam_r(\|), setspwent(\|), setspwent_r(\|), endspwent(\|), endspwent_r(\|), fgetspwent(\|), fgetspwent_r(\|) \- get secure password file entry\c , on trusted systems .SH SYNOPSIS .C "#include " .PP .C "struct s_passwd *getspwent(void);" .PP .C "int getspwent_r(struct s_passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct s_passwd *getspwuid(uid_t uid);" .PP .PD 0 .C "int getspwuid_r(uid_t uid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwaid(aid_t aid);" .PP .PD 0 .C "int getspwaid_r(aid_t aid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwnam(const char *name);" .PP .PD 0 .C "int getspwnam_r(char *name, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setspwent(void);" .PP .C "void setspwent_r(FILE **pwfp);" .PP .C "void endspwent(void);" .PP .C "void endspwent_r(FILE **pwfp);" .PP .C "struct s_passwd *fgetspwent(\s-1FILE\s0 *stream);" .PP .PD 0 .C "int fgetspwent_r(FILE *f, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .SH DESCRIPTION These privileged routines provide access to the protected password database in a manner similar to the way .IR getpwent (3C) routines handle the regular password file, .RC ( \|/etc/passwd\| ). .PP These routines are particularly useful in situations where it is not necessary to get information from the regular password file. .IR getspwent (3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, .CR libsec . .PP Note that .CR getspwent () routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the .CR getprpwent () routines. See .IR getprpwent (3). .PP .CR getspwent (), .CR getspwuid (), .CR getspwaid (), and .CR getspwnam () each returns a pointer to an object of .CR s_passwd structure. The .CR s_passwd structure is maintained for compatibility with existing software and consists of five fields as follows: .nf .IP .C "struct\ s_passwd\ {" .C " char *pw_name; /* login name */" .C " char *pw_passwd; /* encrypted password */" .C " char *pw_age; /* password age */" .C " int pw_audid; /* audit ID */" .C " int pw_audflg; /* audit flag 1=on, 0=off */" .C }; .fi .PP Since the .CR s_passwd structure is declared in the .RC < pwd.h > header file, it is unnecessary to redeclare it. .PP To access other fields in the protected password database that are not included in the .CR s_passwd structure, use .CR getprpwent (). See .IR getprpwent (3) for more information. .PP .TP 20 .CR getspwent () When first called, .CR getspwent () returns a pointer to each .CR s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database. .TP .CR getspwuid () Searches for an entry that matches the specified .IR uid . It then returns a pointer to the particular structure in which .I uid is found. .TP .CR getspwaid () Similarly searches for a numerical audit ID matching .I aid and returns a pointer to the particular structure in which .I aid is found (see .IR spasswd (4) for details on this field). .TP .CR getspwnam () Searches for an entry that matches the specified .IR name . Returns a pointer to the particular structure in which .I name is found. .TP .CR setspwent () Resets the protected password database pointer to the beginning of the file to allow repeated searches. .TP .CR endspwent () Should be called to close the protected password database file when processing is complete. .TP .CR fgetspwent () Is no longer supported. It is provided for those applications that did not use .CR /.secure/etc/passwd . .SS Reentrant Interfaces .CR getspwuid_r (), .CR getspwaid_r (), .CR getspwnam_r (), and .CR fgetspwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .CR s_passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in the .CR s_passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getspwent_r () requires a pointer to a .RI ( "FILE *" ) variable. .CR setspwent_r () and .CR endspwent_r () are to be used only in conjunction with .CR getspwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setspwent_r () can be used to rewind or open the protected password database. .CR endspwent_r () should be called when done to close the file. .PP The .CR /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database. .PP .CR fgetspwent_r () is no longer supported, but is included for those users that did not use the .CR /.secure/etc/passwd file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getspwent_r () or .CR setspwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH RETURN VALUE .CR getspwent () returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the calling process is not zero. .PP .CR getspwent_r () returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned. .SH WARNINGS The above routines use .RC < stdio.h >, which causes them to increase the size of programs by more than might otherwise be expected. .PP Since all information for .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() is contained in a static area, it must be copied to be saved. .PP .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() are unsafe in multi-thread applications. .CR getspwent_r() , .CR getspwuid_r() , .CR getspwaid_r() , .CR getspwnam_r() , .CR setspwent_r() , .CR endspwent_r() , and .CR fgetspwent_r() are MT-Safe and should be used instead. .PP Network Information Service is not supported on trusted systems. .SH EXAMPLE The following code excerpt counts the number of entries in the protected password database: .nf .IP .C "int count = 0;" .C "struct s_passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setspwent_r(&pwf);" .C "while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endspwent_r(&pwf);" .SH AUTHOR .CR getspwent () was developed by HP. .SH FILES .TP 30 .C /tcb/files/auth/*/* Protected Password database .SH SEE ALSO ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), putspwent(3X), passwd(4). .\" .\" index@\f4getspwent()\f1 \- get next secure password file entry@@@\f3getspwent(3X)\f1 .\" index@\f4getspwaid()\f1 \- get next secure password file audit ID@@@\f3getspwent(3X)\f1 .\" index@\f4fgetspwent()\f1 \- get next entry in secure password-file-formatted input stream@@@\f3getspwent(3X)\f1 .\" index@\f4getspwuid()\f1 \- get secure password file entry matching \f4uid()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4getspwnam()\f1 \- get secure password file entry matching login name \f4name()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4setspwent()\f1 \- rewind pointer to beginning of secure password file@@@\f3getspwent(3X)\f1 .\" index@\f4endspwent()\f1 \- close currently open secure password file@@@\f3getspwent(3X)\f1 .\" index@entry from secure password file, get@@@\f3getspwent(3X)\f1 .\" index@secure password file, get entry from@@@\f3getspwent(3X)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspwent(3C)\f1 .\" .\" toc@\f3getspwent(3X)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f1,\n\f4endpwent()\f1, \f4fgetpwent()\f1@@@get secure password file entry .\" toc@\f4getpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4setpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4endpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4getspwaid()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" .\" links@getspwent.3x getspwuid.3x .\" links@getspwent.3x getspwnam.3x .\" links@getspwent.3x setspwent.3x .\" links@getspwent.3x endspwent.3x .\" links@getspwent.3x fgetspwent.3x .\" links@getspwent.3x getspwaid.3x .\" links@getspwent.3x getspwent_r.3x .\" links@getspwent.3x getspwuid_r.3x .\" links@getspwent.3x getspwaid_r.3x .\" links@getspwent.3x getspwnam_r.3x .\" links@getspwent.3x setspwent_r.3x .\" links@getspwent.3x endspwent_r.3x .\" links@getspwent.3x fgetspwent_.3x .\" .\" fileset_database@getspwent.3x PROGRAMING-MAN .\" $Header: getspwent.3x,v 72.6 94/11/30 10:11:44 ssa Exp $ .TA g .TH getspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getspwent(\|), getspwent_r(\|), getspwuid(\|), getspwuid_r(\|), getspwaid(\|), getspwaid_r(\|), getspwnam(\|), getspwnam_r(\|), setspwent(\|), setspwent_r(\|), endspwent(\|), endspwent_r(\|), fgetspwent(\|), fgetspwent_r(\|) \- get secure password file entry\c , on trusted systems .SH SYNOPSIS .C "#include " .PP .C "struct s_passwd *getspwent(void);" .PP .C "int getspwent_r(struct s_passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct s_passwd *getspwuid(uid_t uid);" .PP .PD 0 .C "int getspwuid_r(uid_t uid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwaid(aid_t aid);" .PP .PD 0 .C "int getspwaid_r(aid_t aid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwnam(const char *name);" .PP .PD 0 .C "int getspwnam_r(char *name, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setspwent(void);" .PP .C "void setspwent_r(FILE **pwfp);" .PP .C "void endspwent(void);" .PP .C "void endspwent_r(FILE **pwfp);" .PP .C "struct s_passwd *fgetspwent(\s-1FILE\s0 *stream);" .PP .PD 0 .C "int fgetspwent_r(FILE *f, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .SH DESCRIPTION These privileged routines provide access to the protected password database in a manner similar to the way .IR getpwent (3C) routines handle the regular password file, .RC ( \|/etc/passwd\| ). .PP These routines are particularly useful in situations where it is not necessary to get information from the regular password file. .IR getspwent (3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, .CR libsec . .PP Note that .CR getspwent () routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the .CR getprpwent () routines. See .IR getprpwent (3). .PP .CR getspwent (), .CR getspwuid (), .CR getspwaid (), and .CR getspwnam () each returns a pointer to an object of .CR s_passwd structure. The .CR s_passwd structure is maintained for compatibility with existing software and consists of five fields as follows: .nf .IP .C "struct\ s_passwd\ {" .C " char *pw_name; /* login name */" .C " char *pw_passwd; /* encrypted password */" .C " char *pw_age; /* password age */" .C " int pw_audid; /* audit ID */" .C " int pw_audflg; /* audit flag 1=on, 0=off */" .C }; .fi .PP Since the .CR s_passwd structure is declared in the .RC < pwd.h > header file, it is unnecessary to redeclare it. .PP To access other fields in the protected password database that are not included in the .CR s_passwd structure, use .CR getprpwent (). See .IR getprpwent (3) for more information. .PP .TP 20 .CR getspwent () When first called, .CR getspwent () returns a pointer to each .CR s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database. .TP .CR getspwuid () Searches for an entry that matches the specified .IR uid . It then returns a pointer to the particular structure in which .I uid is found. .TP .CR getspwaid () Similarly searches for a numerical audit ID matching .I aid and returns a pointer to the particular structure in which .I aid is found (see .IR spasswd (4) for details on this field). .TP .CR getspwnam () Searches for an entry that matches the specified .IR name . Returns a pointer to the particular structure in which .I name is found. .TP .CR setspwent () Resets the protected password database pointer to the beginning of the file to allow repeated searches. .TP .CR endspwent () Should be called to close the protected password database file when processing is complete. .TP .CR fgetspwent () Is no longer supported. It is provided for those applications that did not use .CR /.secure/etc/passwd . .SS Reentrant Interfaces .CR getspwuid_r (), .CR getspwaid_r (), .CR getspwnam_r (), and .CR fgetspwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .CR s_passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in the .CR s_passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getspwent_r () requires a pointer to a .RI ( "FILE *" ) variable. .CR setspwent_r () and .CR endspwent_r () are to be used only in conjunction with .CR getspwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setspwent_r () can be used to rewind or open the protected password database. .CR endspwent_r () should be called when done to close the file. .PP The .CR /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database. .PP .CR fgetspwent_r () is no longer supported, but is included for those users that did not use the .CR /.secure/etc/passwd file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getspwent_r () or .CR setspwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH RETURN VALUE .CR getspwent () returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the calling process is not zero. .PP .CR getspwent_r () returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned. .SH WARNINGS The above routines use .RC < stdio.h >, which causes them to increase the size of programs by more than might otherwise be expected. .PP Since all information for .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() is contained in a static area, it must be copied to be saved. .PP .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() are unsafe in multi-thread applications. .CR getspwent_r() , .CR getspwuid_r() , .CR getspwaid_r() , .CR getspwnam_r() , .CR setspwent_r() , .CR endspwent_r() , and .CR fgetspwent_r() are MT-Safe and should be used instead. .PP Network Information Service is not supported on trusted systems. .SH EXAMPLE The following code excerpt counts the number of entries in the protected password database: .nf .IP .C "int count = 0;" .C "struct s_passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setspwent_r(&pwf);" .C "while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endspwent_r(&pwf);" .SH AUTHOR .CR getspwent () was developed by HP. .SH FILES .TP 30 .C /tcb/files/auth/*/* Protected Password database .SH SEE ALSO ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), putspwent(3X), passwd(4). .\" .\" index@\f4getspwent()\f1 \- get next secure password file entry@@@\f3getspwent(3X)\f1 .\" index@\f4getspwaid()\f1 \- get next secure password file audit ID@@@\f3getspwent(3X)\f1 .\" index@\f4fgetspwent()\f1 \- get next entry in secure password-file-formatted input stream@@@\f3getspwent(3X)\f1 .\" index@\f4getspwuid()\f1 \- get secure password file entry matching \f4uid()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4getspwnam()\f1 \- get secure password file entry matching login name \f4name()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4setspwent()\f1 \- rewind pointer to beginning of secure password file@@@\f3getspwent(3X)\f1 .\" index@\f4endspwent()\f1 \- close currently open secure password file@@@\f3getspwent(3X)\f1 .\" index@entry from secure password file, get@@@\f3getspwent(3X)\f1 .\" index@secure password file, get entry from@@@\f3getspwent(3X)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspwent(3C)\f1 .\" .\" toc@\f3getspwent(3X)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f1,\n\f4endpwent()\f1, \f4fgetpwent()\f1@@@get secure password file entry .\" toc@\f4getpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4setpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4endpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4getspwaid()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" .\" links@getspwent.3x getspwuid.3x .\" links@getspwent.3x getspwnam.3x .\" links@getspwent.3x setspwent.3x .\" links@getspwent.3x endspwent.3x .\" links@getspwent.3x fgetspwent.3x .\" links@getspwent.3x getspwaid.3x .\" links@getspwent.3x getspwent_r.3x .\" links@getspwent.3x getspwuid_r.3x .\" links@getspwent.3x getspwaid_r.3x .\" links@getspwent.3x getspwnam_r.3x .\" links@getspwent.3x setspwent_r.3x .\" links@getspwent.3x endspwent_r.3x .\" links@getspwent.3x fgetspwent_.3x .\" .\" fileset_database@getspwent.3x PROGRAMING-MAN .\" $Header: getspwent.3x,v 72.6 94/11/30 10:11:44 ssa Exp $ .TA g .TH getspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getspwent(\|), getspwent_r(\|), getspwuid(\|), getspwuid_r(\|), getspwaid(\|), getspwaid_r(\|), getspwnam(\|), getspwnam_r(\|), setspwent(\|), setspwent_r(\|), endspwent(\|), endspwent_r(\|), fgetspwent(\|), fgetspwent_r(\|) \- get secure password file entry\c , on trusted systems .SH SYNOPSIS .C "#include " .PP .C "struct s_passwd *getspwent(void);" .PP .C "int getspwent_r(struct s_passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct s_passwd *getspwuid(uid_t uid);" .PP .PD 0 .C "int getspwuid_r(uid_t uid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwaid(aid_t aid);" .PP .PD 0 .C "int getspwaid_r(aid_t aid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwnam(const char *name);" .PP .PD 0 .C "int getspwnam_r(char *name, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setspwent(void);" .PP .C "void setspwent_r(FILE **pwfp);" .PP .C "void endspwent(void);" .PP .C "void endspwent_r(FILE **pwfp);" .PP .C "struct s_passwd *fgetspwent(\s-1FILE\s0 *stream);" .PP .PD 0 .C "int fgetspwent_r(FILE *f, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .SH DESCRIPTION These privileged routines provide access to the protected password database in a manner similar to the way .IR getpwent (3C) routines handle the regular password file, .RC ( \|/etc/passwd\| ). .PP These routines are particularly useful in situations where it is not necessary to get information from the regular password file. .IR getspwent (3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, .CR libsec . .PP Note that .CR getspwent () routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the .CR getprpwent () routines. See .IR getprpwent (3). .PP .CR getspwent (), .CR getspwuid (), .CR getspwaid (), and .CR getspwnam () each returns a pointer to an object of .CR s_passwd structure. The .CR s_passwd structure is maintained for compatibility with existing software and consists of five fields as follows: .nf .IP .C "struct\ s_passwd\ {" .C " char *pw_name; /* login name */" .C " char *pw_passwd; /* encrypted password */" .C " char *pw_age; /* password age */" .C " int pw_audid; /* audit ID */" .C " int pw_audflg; /* audit flag 1=on, 0=off */" .C }; .fi .PP Since the .CR s_passwd structure is declared in the .RC < pwd.h > header file, it is unnecessary to redeclare it. .PP To access other fields in the protected password database that are not included in the .CR s_passwd structure, use .CR getprpwent (). See .IR getprpwent (3) for more information. .PP .TP 20 .CR getspwent () When first called, .CR getspwent () returns a pointer to each .CR s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database. .TP .CR getspwuid () Searches for an entry that matches the specified .IR uid . It then returns a pointer to the particular structure in which .I uid is found. .TP .CR getspwaid () Similarly searches for a numerical audit ID matching .I aid and returns a pointer to the particular structure in which .I aid is found (see .IR spasswd (4) for details on this field). .TP .CR getspwnam () Searches for an entry that matches the specified .IR name . Returns a pointer to the particular structure in which .I name is found. .TP .CR setspwent () Resets the protected password database pointer to the beginning of the file to allow repeated searches. .TP .CR endspwent () Should be called to close the protected password database file when processing is complete. .TP .CR fgetspwent () Is no longer supported. It is provided for those applications that did not use .CR /.secure/etc/passwd . .SS Reentrant Interfaces .CR getspwuid_r (), .CR getspwaid_r (), .CR getspwnam_r (), and .CR fgetspwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .CR s_passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in the .CR s_passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getspwent_r () requires a pointer to a .RI ( "FILE *" ) variable. .CR setspwent_r () and .CR endspwent_r () are to be used only in conjunction with .CR getspwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setspwent_r () can be used to rewind or open the protected password database. .CR endspwent_r () should be called when done to close the file. .PP The .CR /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database. .PP .CR fgetspwent_r () is no longer supported, but is included for those users that did not use the .CR /.secure/etc/passwd file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getspwent_r () or .CR setspwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH RETURN VALUE .CR getspwent () returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the calling process is not zero. .PP .CR getspwent_r () returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned. .SH WARNINGS The above routines use .RC < stdio.h >, which causes them to increase the size of programs by more than might otherwise be expected. .PP Since all information for .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() is contained in a static area, it must be copied to be saved. .PP .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() are unsafe in multi-thread applications. .CR getspwent_r() , .CR getspwuid_r() , .CR getspwaid_r() , .CR getspwnam_r() , .CR setspwent_r() , .CR endspwent_r() , and .CR fgetspwent_r() are MT-Safe and should be used instead. .PP Network Information Service is not supported on trusted systems. .SH EXAMPLE The following code excerpt counts the number of entries in the protected password database: .nf .IP .C "int count = 0;" .C "struct s_passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setspwent_r(&pwf);" .C "while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endspwent_r(&pwf);" .SH AUTHOR .CR getspwent () was developed by HP. .SH FILES .TP 30 .C /tcb/files/auth/*/* Protected Password database .SH SEE ALSO ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), putspwent(3X), passwd(4). .\" .\" index@\f4getspwent()\f1 \- get next secure password file entry@@@\f3getspwent(3X)\f1 .\" index@\f4getspwaid()\f1 \- get next secure password file audit ID@@@\f3getspwent(3X)\f1 .\" index@\f4fgetspwent()\f1 \- get next entry in secure password-file-formatted input stream@@@\f3getspwent(3X)\f1 .\" index@\f4getspwuid()\f1 \- get secure password file entry matching \f4uid()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4getspwnam()\f1 \- get secure password file entry matching login name \f4name()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4setspwent()\f1 \- rewind pointer to beginning of secure password file@@@\f3getspwent(3X)\f1 .\" index@\f4endspwent()\f1 \- close currently open secure password file@@@\f3getspwent(3X)\f1 .\" index@entry from secure password file, get@@@\f3getspwent(3X)\f1 .\" index@secure password file, get entry from@@@\f3getspwent(3X)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspwent(3C)\f1 .\" .\" toc@\f3getspwent(3X)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f1,\n\f4endpwent()\f1, \f4fgetpwent()\f1@@@get secure password file entry .\" toc@\f4getpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4setpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4endpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4getspwaid()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" .\" links@getspwent.3x getspwuid.3x .\" links@getspwent.3x getspwnam.3x .\" links@getspwent.3x setspwent.3x .\" links@getspwent.3x endspwent.3x .\" links@getspwent.3x fgetspwent.3x .\" links@getspwent.3x getspwaid.3x .\" links@getspwent.3x getspwent_r.3x .\" links@getspwent.3x getspwuid_r.3x .\" links@getspwent.3x getspwaid_r.3x .\" links@getspwent.3x getspwnam_r.3x .\" links@getspwent.3x setspwent_r.3x .\" links@getspwent.3x endspwent_r.3x .\" links@getspwent.3x fgetspwent_.3x .\" .\" fileset_database@getspwent.3x PROGRAMING-MAN .\" $Header: getspwent.3x,v 72.6 94/11/30 10:11:44 ssa Exp $ .TA g .TH getspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getspwent(\|), getspwent_r(\|), getspwuid(\|), getspwuid_r(\|), getspwaid(\|), getspwaid_r(\|), getspwnam(\|), getspwnam_r(\|), setspwent(\|), setspwent_r(\|), endspwent(\|), endspwent_r(\|), fgetspwent(\|), fgetspwent_r(\|) \- get secure password file entry\c , on trusted systems .SH SYNOPSIS .C "#include " .PP .C "struct s_passwd *getspwent(void);" .PP .C "int getspwent_r(struct s_passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct s_passwd *getspwuid(uid_t uid);" .PP .PD 0 .C "int getspwuid_r(uid_t uid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwaid(aid_t aid);" .PP .PD 0 .C "int getspwaid_r(aid_t aid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwnam(const char *name);" .PP .PD 0 .C "int getspwnam_r(char *name, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setspwent(void);" .PP .C "void setspwent_r(FILE **pwfp);" .PP .C "void endspwent(void);" .PP .C "void endspwent_r(FILE **pwfp);" .PP .C "struct s_passwd *fgetspwent(\s-1FILE\s0 *stream);" .PP .PD 0 .C "int fgetspwent_r(FILE *f, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .SH DESCRIPTION These privileged routines provide access to the protected password database in a manner similar to the way .IR getpwent (3C) routines handle the regular password file, .RC ( \|/etc/passwd\| ). .PP These routines are particularly useful in situations where it is not necessary to get information from the regular password file. .IR getspwent (3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, .CR libsec . .PP Note that .CR getspwent () routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the .CR getprpwent () routines. See .IR getprpwent (3). .PP .CR getspwent (), .CR getspwuid (), .CR getspwaid (), and .CR getspwnam () each returns a pointer to an object of .CR s_passwd structure. The .CR s_passwd structure is maintained for compatibility with existing software and consists of five fields as follows: .nf .IP .C "struct\ s_passwd\ {" .C " char *pw_name; /* login name */" .C " char *pw_passwd; /* encrypted password */" .C " char *pw_age; /* password age */" .C " int pw_audid; /* audit ID */" .C " int pw_audflg; /* audit flag 1=on, 0=off */" .C }; .fi .PP Since the .CR s_passwd structure is declared in the .RC < pwd.h > header file, it is unnecessary to redeclare it. .PP To access other fields in the protected password database that are not included in the .CR s_passwd structure, use .CR getprpwent (). See .IR getprpwent (3) for more information. .PP .TP 20 .CR getspwent () When first called, .CR getspwent () returns a pointer to each .CR s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database. .TP .CR getspwuid () Searches for an entry that matches the specified .IR uid . It then returns a pointer to the particular structure in which .I uid is found. .TP .CR getspwaid () Similarly searches for a numerical audit ID matching .I aid and returns a pointer to the particular structure in which .I aid is found (see .IR spasswd (4) for details on this field). .TP .CR getspwnam () Searches for an entry that matches the specified .IR name . Returns a pointer to the particular structure in which .I name is found. .TP .CR setspwent () Resets the protected password database pointer to the beginning of the file to allow repeated searches. .TP .CR endspwent () Should be called to close the protected password database file when processing is complete. .TP .CR fgetspwent () Is no longer supported. It is provided for those applications that did not use .CR /.secure/etc/passwd . .SS Reentrant Interfaces .CR getspwuid_r (), .CR getspwaid_r (), .CR getspwnam_r (), and .CR fgetspwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .CR s_passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in the .CR s_passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getspwent_r () requires a pointer to a .RI ( "FILE *" ) variable. .CR setspwent_r () and .CR endspwent_r () are to be used only in conjunction with .CR getspwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setspwent_r () can be used to rewind or open the protected password database. .CR endspwent_r () should be called when done to close the file. .PP The .CR /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database. .PP .CR fgetspwent_r () is no longer supported, but is included for those users that did not use the .CR /.secure/etc/passwd file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getspwent_r () or .CR setspwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH RETURN VALUE .CR getspwent () returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the calling process is not zero. .PP .CR getspwent_r () returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned. .SH WARNINGS The above routines use .RC < stdio.h >, which causes them to increase the size of programs by more than might otherwise be expected. .PP Since all information for .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() is contained in a static area, it must be copied to be saved. .PP .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() are unsafe in multi-thread applications. .CR getspwent_r() , .CR getspwuid_r() , .CR getspwaid_r() , .CR getspwnam_r() , .CR setspwent_r() , .CR endspwent_r() , and .CR fgetspwent_r() are MT-Safe and should be used instead. .PP Network Information Service is not supported on trusted systems. .SH EXAMPLE The following code excerpt counts the number of entries in the protected password database: .nf .IP .C "int count = 0;" .C "struct s_passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setspwent_r(&pwf);" .C "while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endspwent_r(&pwf);" .SH AUTHOR .CR getspwent () was developed by HP. .SH FILES .TP 30 .C /tcb/files/auth/*/* Protected Password database .SH SEE ALSO ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), putspwent(3X), passwd(4). .\" .\" index@\f4getspwent()\f1 \- get next secure password file entry@@@\f3getspwent(3X)\f1 .\" index@\f4getspwaid()\f1 \- get next secure password file audit ID@@@\f3getspwent(3X)\f1 .\" index@\f4fgetspwent()\f1 \- get next entry in secure password-file-formatted input stream@@@\f3getspwent(3X)\f1 .\" index@\f4getspwuid()\f1 \- get secure password file entry matching \f4uid()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4getspwnam()\f1 \- get secure password file entry matching login name \f4name()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4setspwent()\f1 \- rewind pointer to beginning of secure password file@@@\f3getspwent(3X)\f1 .\" index@\f4endspwent()\f1 \- close currently open secure password file@@@\f3getspwent(3X)\f1 .\" index@entry from secure password file, get@@@\f3getspwent(3X)\f1 .\" index@secure password file, get entry from@@@\f3getspwent(3X)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspwent(3C)\f1 .\" .\" toc@\f3getspwent(3X)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f1,\n\f4endpwent()\f1, \f4fgetpwent()\f1@@@get secure password file entry .\" toc@\f4getpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4setpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4endpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4getspwaid()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" .\" links@getspwent.3x getspwuid.3x .\" links@getspwent.3x getspwnam.3x .\" links@getspwent.3x setspwent.3x .\" links@getspwent.3x endspwent.3x .\" links@getspwent.3x fgetspwent.3x .\" links@getspwent.3x getspwaid.3x .\" links@getspwent.3x getspwent_r.3x .\" links@getspwent.3x getspwuid_r.3x .\" links@getspwent.3x getspwaid_r.3x .\" links@getspwent.3x getspwnam_r.3x .\" links@getspwent.3x setspwent_r.3x .\" links@getspwent.3x endspwent_r.3x .\" links@getspwent.3x fgetspwent_.3x .\" .\" fileset_database@getspwent.3x PROGRAMING-MAN .\" $Header: getspwent.3x,v 72.6 94/11/30 10:11:44 ssa Exp $ .TA g .TH getspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getspwent(\|), getspwent_r(\|), getspwuid(\|), getspwuid_r(\|), getspwaid(\|), getspwaid_r(\|), getspwnam(\|), getspwnam_r(\|), setspwent(\|), setspwent_r(\|), endspwent(\|), endspwent_r(\|), fgetspwent(\|), fgetspwent_r(\|) \- get secure password file entry\c , on trusted systems .SH SYNOPSIS .C "#include " .PP .C "struct s_passwd *getspwent(void);" .PP .C "int getspwent_r(struct s_passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct s_passwd *getspwuid(uid_t uid);" .PP .PD 0 .C "int getspwuid_r(uid_t uid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwaid(aid_t aid);" .PP .PD 0 .C "int getspwaid_r(aid_t aid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwnam(const char *name);" .PP .PD 0 .C "int getspwnam_r(char *name, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setspwent(void);" .PP .C "void setspwent_r(FILE **pwfp);" .PP .C "void endspwent(void);" .PP .C "void endspwent_r(FILE **pwfp);" .PP .C "struct s_passwd *fgetspwent(\s-1FILE\s0 *stream);" .PP .PD 0 .C "int fgetspwent_r(FILE *f, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .SH DESCRIPTION These privileged routines provide access to the protected password database in a manner similar to the way .IR getpwent (3C) routines handle the regular password file, .RC ( \|/etc/passwd\| ). .PP These routines are particularly useful in situations where it is not necessary to get information from the regular password file. .IR getspwent (3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, .CR libsec . .PP Note that .CR getspwent () routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the .CR getprpwent () routines. See .IR getprpwent (3). .PP .CR getspwent (), .CR getspwuid (), .CR getspwaid (), and .CR getspwnam () each returns a pointer to an object of .CR s_passwd structure. The .CR s_passwd structure is maintained for compatibility with existing software and consists of five fields as follows: .nf .IP .C "struct\ s_passwd\ {" .C " char *pw_name; /* login name */" .C " char *pw_passwd; /* encrypted password */" .C " char *pw_age; /* password age */" .C " int pw_audid; /* audit ID */" .C " int pw_audflg; /* audit flag 1=on, 0=off */" .C }; .fi .PP Since the .CR s_passwd structure is declared in the .RC < pwd.h > header file, it is unnecessary to redeclare it. .PP To access other fields in the protected password database that are not included in the .CR s_passwd structure, use .CR getprpwent (). See .IR getprpwent (3) for more information. .PP .TP 20 .CR getspwent () When first called, .CR getspwent () returns a pointer to each .CR s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database. .TP .CR getspwuid () Searches for an entry that matches the specified .IR uid . It then returns a pointer to the particular structure in which .I uid is found. .TP .CR getspwaid () Similarly searches for a numerical audit ID matching .I aid and returns a pointer to the particular structure in which .I aid is found (see .IR spasswd (4) for details on this field). .TP .CR getspwnam () Searches for an entry that matches the specified .IR name . Returns a pointer to the particular structure in which .I name is found. .TP .CR setspwent () Resets the protected password database pointer to the beginning of the file to allow repeated searches. .TP .CR endspwent () Should be called to close the protected password database file when processing is complete. .TP .CR fgetspwent () Is no longer supported. It is provided for those applications that did not use .CR /.secure/etc/passwd . .SS Reentrant Interfaces .CR getspwuid_r (), .CR getspwaid_r (), .CR getspwnam_r (), and .CR fgetspwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .CR s_passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in the .CR s_passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getspwent_r () requires a pointer to a .RI ( "FILE *" ) variable. .CR setspwent_r () and .CR endspwent_r () are to be used only in conjunction with .CR getspwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setspwent_r () can be used to rewind or open the protected password database. .CR endspwent_r () should be called when done to close the file. .PP The .CR /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database. .PP .CR fgetspwent_r () is no longer supported, but is included for those users that did not use the .CR /.secure/etc/passwd file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getspwent_r () or .CR setspwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH RETURN VALUE .CR getspwent () returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the calling process is not zero. .PP .CR getspwent_r () returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned. .SH WARNINGS The above routines use .RC < stdio.h >, which causes them to increase the size of programs by more than might otherwise be expected. .PP Since all information for .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() is contained in a static area, it must be copied to be saved. .PP .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() are unsafe in multi-thread applications. .CR getspwent_r() , .CR getspwuid_r() , .CR getspwaid_r() , .CR getspwnam_r() , .CR setspwent_r() , .CR endspwent_r() , and .CR fgetspwent_r() are MT-Safe and should be used instead. .PP Network Information Service is not supported on trusted systems. .SH EXAMPLE The following code excerpt counts the number of entries in the protected password database: .nf .IP .C "int count = 0;" .C "struct s_passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setspwent_r(&pwf);" .C "while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endspwent_r(&pwf);" .SH AUTHOR .CR getspwent () was developed by HP. .SH FILES .TP 30 .C /tcb/files/auth/*/* Protected Password database .SH SEE ALSO ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), putspwent(3X), passwd(4). .\" .\" index@\f4getspwent()\f1 \- get next secure password file entry@@@\f3getspwent(3X)\f1 .\" index@\f4getspwaid()\f1 \- get next secure password file audit ID@@@\f3getspwent(3X)\f1 .\" index@\f4fgetspwent()\f1 \- get next entry in secure password-file-formatted input stream@@@\f3getspwent(3X)\f1 .\" index@\f4getspwuid()\f1 \- get secure password file entry matching \f4uid()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4getspwnam()\f1 \- get secure password file entry matching login name \f4name()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4setspwent()\f1 \- rewind pointer to beginning of secure password file@@@\f3getspwent(3X)\f1 .\" index@\f4endspwent()\f1 \- close currently open secure password file@@@\f3getspwent(3X)\f1 .\" index@entry from secure password file, get@@@\f3getspwent(3X)\f1 .\" index@secure password file, get entry from@@@\f3getspwent(3X)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspwent(3C)\f1 .\" .\" toc@\f3getspwent(3X)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f1,\n\f4endpwent()\f1, \f4fgetpwent()\f1@@@get secure password file entry .\" toc@\f4getpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4setpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4endpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4getspwaid()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" .\" links@getspwent.3x getspwuid.3x .\" links@getspwent.3x getspwnam.3x .\" links@getspwent.3x setspwent.3x .\" links@getspwent.3x endspwent.3x .\" links@getspwent.3x fgetspwent.3x .\" links@getspwent.3x getspwaid.3x .\" links@getspwent.3x getspwent_r.3x .\" links@getspwent.3x getspwuid_r.3x .\" links@getspwent.3x getspwaid_r.3x .\" links@getspwent.3x getspwnam_r.3x .\" links@getspwent.3x setspwent_r.3x .\" links@getspwent.3x endspwent_r.3x .\" links@getspwent.3x fgetspwent_.3x .\" .\" fileset_database@getspwent.3x PROGRAMING-MAN .\" $Header: getstr.3x,v 76.2 95/08/01 10:58:50 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getstr 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getstr, mvgetstr, mvwgetstr, wgetstr \(em get a multi-byte character string from the terminal .SH SYNOPSIS .C "#include " .P .C "int getstr(char *\f2str\fP);" .P .C "int mvgetstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int mvwgetstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int wgetstr(WINDOW *\f2win\fP, char *\f2str\fP);" .SH DESCRIPTION The effect of .Fn getstr is as though a series of calls to .Fn getch were made, until a newline or carriage return is received. The resulting value is placed in the area pointed to by \f2str\f1. The user's erase and kill characters are interpreted, as well as any special keys (such as function keys, home key, clear key, and so on). .P The .Fn mvgetstr function is identical to .Fn getstr except that it is as though it is a call to .Fn move and then a series of calls to .CR getch() . The .Fn mvwgetstr function is identical to .Fn getstr except it is as though a call to .Fn wmove is made and then a series of calls to .CR wgetch() . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2str\f1 with .CR getstr() , .CR mvgetstr() , .Fn mvwgetstr or .Fn wgetstr causes undefined results. .P Traditional implementations often limited the number of bytes returned to 256. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, beep(), getch(), getnstr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .br .ne 5 .SH Issue 3 .P In X/Open Curses, Issue 3, the .CR getstr() , .CR mvgetstr() , .Fn mvwgetstr and .Fn wgetstr functions were described in the .Fn addstr entry. In X/Open Curses, Issue 4, the .B DESCRIPTION of these functions is rewritten for clarity and is updated to indicate that they will handle multi-byte sequences correctly. .\" .\" toc@\f3getstr(3X)\f1:\0\0\f4getstr()\f1, \f4mvgetstr()\f1, \f4mvwgetstr()\f1, \f4wgetstr()\f1\n@@@get a multi-byte character string from the terminal .\" toc@\f4mvgetstr()\f1: get a multi-byte character string from the terminal@@@see \f3getstr(3X)\f1 .\" toc@\f4mvwgetstr()\f1: get a multi-byte character string from the terminal@@@see \f3getstr(3X)\f1 .\" toc@\f4wgetstr()\f1: get a multi-byte character string from the terminal@@@see \f3getstr(3X)\f1 .\" .\" index@\f4getstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f4mvgetstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f4mvwgetstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f4wgetstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1multi-byte character string, get from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1terminal, get a multi-byte character string@@@\f3getstr(3X)\f1 .\" index@\f1character, get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1string, get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" .\" links@getstr.3x mvgetstr.3x .\" links@getstr.3x mvwgetstr.3x .\" links@getstr.3x wgetstr.3x .\" .\" fileset_database@getstr.3x CURS-ENG-A-MAN .\" $Header: getsubopt.3c,v 72.3 93/01/14 14:55:39 ssa Exp $ .TA g .TH getsubopt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getsubopt(\|) \- parse suboptions from a string. .SH SYNOPSIS .C "#include " .PP .C "int getsubopt(char **optionp, char *tokens[], char **valuep);" .SH DESCRIPTION .C getsubopt() parses suboptions in a flag argument that were initially parsed by .C getopt() (see getopt(3C)). These suboptions are separated by commas, and may consist of either a single token, or a token-value pair separated by an equal sign. Because commas delimit suboptions in the option string, they are not allowed to be part of the suboption or the value of a suboption. Similarly, because the equal sign separates a token from its value, a token must not contain an equals sign. An example command that uses this syntax is .CR mount . .C mount allows parameters to be specified with the .C - switch as follows: .IP .C "mount -o rw,hard,bg,wsize=1024 speed:/usr /usr" .PP In this example there are four suboptions: .CR rw , .CR hard , .CR bg , and .CR wsize , the last of which has an associated value of 1024. .PP .C getsubopt() takes the address of a pointer to the option string, a vector of possible tokens, and the address of a value string pointer. It returns the index of the token that matched the suboption in the input string or \(mi1 if there was no match. If the option string at .CI * optionp contains only one suboption, .C getsubopt() updates .CI * optionp to point to the null at the end of the string, otherwise it isolates the suboption by replacing the comma separator with a null, and updates .CI * optionp to point to the start of the next suboption. If the suboption has an associated value, .C getsubopt() updates .CI * valuep to point to the value's first character. Otherwise it sets .CI * valuep to .SM NULL. .PP The token vector is organized as a series of pointers to .SM NULL\c -terminated strings. The end of the token vector is identified by .SM NULL. .PP When .C getsubopt() returns, if .CI * valuep is not .SM NULL then the suboption processed included a value. The calling program can use this information to determine if the presence or lack of a value for this suboption is an error. .PP Additionally, when .C getsubopt() fails to match the suboption with the tokens in the .I tokens array, the calling program should decide if this is an error, or if the unrecognized option should be passed on to another program. .SH EXAMPLES The following code fragment shows how options can be processed to the .C mount command by using .C getsubopt(). .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 char *myopts[] = { #define READONLY 0 "ro", #define READWRITE 1 "rw", #define WRITESIZE 2 "wsize", #define READSIZE 3 "rsize", NULL}; .sp main (int argc, char **argv) { int sc, c, errflag; char *options, *value; extern char *optarg; extern int optind; \&\f3.\fP \&\f3.\fP \&\f3.\fP while ((c = getopt(argc, argv, "abf:o:")) != EOF) switch (c) { case \'a\': /* process \'a\' option */ break; case \'b\': /* process \'b\' option */ break; case \'f\': ofile = optarg; break; case \'?\': errflag++; break; case \'o\': options = optarg; while (*options != \'\\0\') { switch(getsubopt(&options, myopts, &value)) { case READONLY: /* process ro option */ break; case READWRITE: /* process rw option */ break; case WRITESIZE: /* process wsize option */ if (value == NULL) { error_no_arg(); errflag++; } else write_size = atoi(value); break; case READSIZE: /* process rsize option */ if (value == NULL) { error_no_arg(); errflag++; } else read_size = atoi(value); break; default: /* process unknown token */ error_bad_token(value); errflag++; break; } } break; } } if (errflg) { fprintf(stderr, "usage: . . . "); exit (2); } for ( ; optind < argc; optind++) { /* process remaining arguments */ . . . } .ft .ps .fi .RE .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of option letters as single and/or multi-byte characters. .SS International Code Set Support Single- and multi-byte character code sets are supported with the exception of multi-byte-character file names. .SH SEE ALSO getopt(3C). .SH STANDARDS CONFORMANCE .CR getsubopt() ": SVID3" .\" .\" index@\f4getsubopt()\fP \- parse suboptions from a string@@@\f3getsubopt(3C)\f1 .\" index@options, parse suboptions from a string@@@\f3getsubopt(3C)\f1 .\" index@parse suboptions from a string@@@\f3getsubopt(3C)\f1 .\" index@suboptions, parse from a string@@@\f3getsubopt(3C)\f1 .\" index@string, parse suboptions from a@@@\f3getsubopt(3C)\f1 .\" .\" toc@\f3getsubopt(3C)\f1:\0\0\f4getsubopt()\fP@@@parse suboptions from a string. .\" .\" fileset_database@getsubopt.3c PROGRAMING-MAN .\" $Header: gettimer.3c,v 72.5 94/11/15 09:54:48 ssa Exp $ .TA g .TH gettimer 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gettimer \- get value of a per-process timer .SH SYNOPSIS .C "#include " .PP .C "int gettimer(timer_t timerid, struct itimerspec *value);" .SH DESCRIPTION The .CR gettimer() function returns an .CR itimerspec structure value to the .CR value argument. The .CR it_value member of the structure represents the amount of time in the current interval before the timer expires for the timer specified in .CR timerid , or zero if the timer is disabled. The .CR it_interval member has the value last set by .CR reltimer() (see .IR reltimer (3C)). The members of .CR value are subject to the resolution of the timer (see .IR mktimer (3C)). .PP The behavior of this function is undefined if .CR value is NULL. .SH RETURN VALUE Upon successful completion, .CR gettimer() returns zero; otherwise, it returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS .CR gettimer() fails if any of the following conditions are encountered: .RS .TP 12 [EINVAL] .CR timerid does not correspond to an ID returned by .CR mktimer() . .TP [EIO] An error occurred while accessing the clock device. .RE .SH FILES .C /usr/include/sys/timers.h .SH SEE ALSO timer_gettime(2), mktimer(3C), reltimer(3C). .SH STANDARDS CONFORMANCE .CR gettimer() ": AES" .\" .\" toc@\f3gettimer(3C)\f1:\0\0\f4gettimer()\f1@@@get value of a per-process timer\f1 .\" .\" index@\f4gettimer()\f1 \- get value of a per-process timer@@@\f3gettimer(3C)\f1 .\" index@\f1get value of a per-process timer@@@\f3gettimer(3C)\f1 .\" index@\f1value of a per-process timer, get@@@\f3gettimer(3C)\f1 .\" index@\f1per-process timer, get value of a@@@\f3gettimer(3C)\f1 .\" index@\f1timer, get value of a per-process@@@\f3gettimer(3C)\f1 .\" $Header: gettxt.3c,v 72.2 94/07/03 11:59:03 ssa Exp $ .TA g .TH gettxt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gettxt() \- read text string from message file .SH SYNOPSIS .C "#include " .PP .C "char *gettxt(char *msg_id, char *def_str);" .PD .SH DESCRIPTION The .CR gettxt() routine retrieves a text string from a message file for the current locale. .PP .I msg_id has the following syntax: .IP .I msgfilename:msgnumber .PP where .I msgfilename is the name of the message file generated by .IR mkmsgs (1). If .I msgfilename is .CR NULL , .CR gettxt() uses the message file specified in the last call to .IR setcat (3C). .I msgnumber is the sequence number of the text string in the message file (the sequence begins at 1). .PP .CR gettxt() returns the message .IP .C Message not found!! .PP under any of the following conditions: .RS .TP 3 \(bu .I msgfilename is an invalid message catalog name. .TP \(bu No catalog is specified in .I msg_id or through .IR setcat (3C). .TP \(bu .I msgnumber is not a positive number. .TP \(bu No message could be retrieved and .I def_str is .CR NULL . .RE .SH EXTERNAL INFLUENCES .SS Environment Variables .CR gettxt() uses the environment variable .CR LC_MESSAGES to determine the locale to use to search for the .I msgfilename message file. If .CR LC_MESSAGES is not set, the environment variable .CR LANG is used. If .CR LANG is not set, the "C" locale will be used. The user can also change the locale via the .IR setlocale (3C) routine. .PP If the .I msgfilename message file is not found in the specified locale or if the .I msgnumber is out of bounds, .CR gettxt() attempts to retrieve the text string from the "C" locale. .I def_str is the string returned if a text string cannot be retrieved even from the "C" locale. .ifn .bp .SH EXAMPLES The following code fragments are equivalent: .IP .C gettxt("mytest:1", "my default message"); .nf .IP .C setcat("mytest"); .C gettxt(":1", "my default message"); .SH SEE ALSO mkmsgs(1), setcat(3C), setlocale(3C), environ(5). .SH STANDARDS COMPLIANCE .CR gettxt() ": SVID3" .\" .\" toc@\f3gettxt(3C)\f1:\0\0\f4gettxt()\f1@@@read text string from message file\f1 .\" index@\f4gettxt()\f1 \- read text string from message file@@@\f3gettxt(3C)\f1 .\" index@\f4gettxt()\f1 \- text string, read from message file@@@\f3gettxt(3C)\f1 .\" index@\f4gettxt()\f1 \- message file, read text string from@@@\f3gettxt(3C)\f1 .\" $Header: getusershel.3c,v 72.6 94/11/02 15:43:32 ssa Exp $ .TA g .TH getusershell 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getusershell(\|), getusershell_r(\|), setusershell(\|), setusershell_r(\|), endusershell(\|), endusershell_r(\|) \- get legal user shells .SH SYNOPSIS .C "#include " .PP .C "char *getusershell(void);" .PP .C "char *getusershell_r(char **shell_datap);" .PP .C "void setusershell(void);" .PP .C "void setusershell_r(char **shell_datap);" .PP .C "void endusershell(void);" .PP .C "void endusershell_r(char **shell_datap);" .SH DESCRIPTION .TP 25 .CR getusershell() Returns a pointer to the first legal user shell as defined in the file .CR /etc/shells (see .IR shells (4)). If .CR /etc/shells does not exist or is not readable, .CR getusershell() returns the following standard system shells: .RS .nf .IP .CR /sbin/sh .CR /usr/bin/sh .CR /usr/bin/rsh .CR /usr/bin/ksh .CR /usr/bin/rksh .CR /usr/bin/csh .CR /usr/bin/keysh .fi .RE .IP as if they were contained in .CR /etc/shells . The file is left open so that the next call returns the next shell. A null pointer (0) is returned on .SM EOF or error. .TP .CR setusershell() Rewinds the file. .TP .CR endusershell() Closes the file. .SS Reentrant Interfaces .PP .CR getusershell_r() , .CR setusershell_r() and .CR endusershell_r() expect to be passed the address of a character pointer so that state information can be maintained between calls. .I *shell_datap should be initialized to .SM NULL before the first call to either .CR setusershell_r() or .CR getusershell_r() . Thereafter it should not be modified. After the first call to .CR setusershell_r() or .CR getusershell_r() , .I *shell_datap points to state information that is needed on subsequent calls to .CR getusershell_r() . .PP .CR endusershell_r() should be called when done so that any memory that has been internally allocated can be freed. .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area and therefore must be copied if it is to be saved. .PP .CR getusershell() , .CR setusershell() , and .CR endusershell() are unsafe in multi-thread applications. .CR getusershell_r() , .CR setusershell_r() , and .CR endusershell_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getusershell() was developed by HP and the University of California, Berkeley. .SH FILES .CR /etc/shells .SH SEE ALSO shells(4). .\" .\" index@\f4getusershell()\fP \- get legal user shells@@@\f3getusershell(3C)\f1 .\" index@\f4setusershell()\fP \- rewind legal user shells file@@@\f3getusershell(3C)\f1 .\" index@\f4endusershell()\fP \- close legal user shells file@@@\f3getusershell(3C)\f1 .\" index@get legal user shells@@@\f3getusershell(3C)\f1 .\" index@rewind legal user shells file@@@\f3getusershell(3C)\f1 .\" index@close legal user shells file@@@\f3getusershell(3C)\f1 .\" index@legal user shells, get@@@\f3getusershell(3C)\f1 .\" index@user shells, get legal@@@\f3getusershell(3C)\f1 .\" index@shells, get legal user@@@\f3getusershell(3C)\f1 .\" .\" toc@\f3getusershell(3C)\f1:\0\0\f4getusershell()\fP, \f4setusershell()\fP, \f4endusershell()\fP@@@get legal user shells .\" toc@\f4endusershell()\fP \- close legal user shells file@@@see \f3getusershell(3C)\f1 .\" toc@\f4setusershell()\fP \- rewind legal user shells file@@@see \f3getusershell(3C)\f1 .\" .\" links@getusershel.3c setusershel.3c .\" links@getusershel.3c endusershel.3c .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getutx.3c,v 76.4 95/09/12 12:01:34 ssa Exp $ .TA g .TH getutx 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutxent(\|), getutxid(\|), getutxline(\|), pututxline(\|), setutxent(\|), endutxent(\|) \- access utmpx file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmpx *getutxent(void);" .PP .C "struct utmpx *getutxid(const struct utmpx *id);" .nf .PP .C "struct utmpx *getutxline(const struct utmpx *line);" .PP .C "struct utmpx *_pututxline(const struct utmpx *utmpx);" .PP .C "void pututxline(const struct utmpx *utmpx);" .PP .C "void setutxent(void);" .PP .C "void endutxent(void);" .PP .fi .SH DESCRIPTION .CR getutxent() , .CR getutxid() , and .C getutxline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmpx { char ut_user[24]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct __exit_status { short __e_termination; /* Process termination status */ short __e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ struct timeval { time_t tv_sec; /* seconds */ long tv_usec; /* and microseconds */ } ut_tv; /* time entry was made */ char ut_host[64]; /* host name, if remote; NOT SUPPORTED */ unsigned long ut_addr; /* Internet addr of host, if remote */ char ut_reserved2[12] ; /* Reserved for future use */ }; .ps .ft .fi .RE .TP 20 .C getutxent() Reads in the next entry from a .CR utmpx -like file. If the file is not already open, .C getutxent() opens it. If it reaches the end of the file, .C getutxent() fails. .TP .C getutxid() Searches forward from the current point in the .I utmpx file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutxid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutxid() fails. .TP .C getutxline() Searches forward from the current point in the .I utmpx file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutxline() fails. .TP .C pututxline() Writes out the supplied .C utmpx structure into the .I utmpx file, translates the supplied .C utmpx structure into a .C utmp structure and writes it to a .I utmp file. .C pututxline() uses .C getutxid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getutx() routines before calling .CR pututxline() . If the search as already been made, .C pututxline() does not repeat it. If .C pututxline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututxline() Performs the same actions as .CR pututxline() , except that it returns a value useful for error checking. .TP .C setutxent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutxent() Closes the currently open file. .TP .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutxid() or .CR getutxline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutxline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutxline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututxline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutxent() , .CR getutxid() , or .C getutxline() if the user has just modified those contents and passed the pointer back to .CR pututxline() . .PP .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmpx)" . .PP .C _pututxline() behaves the same as .CR pututxline() , except that it returns a pointer to a static location containing the most current utmpx entry if the .C _pututxline() call succeeds. The contents of this structure are identical to the contents of the supplied .C utmpx structure if successful. If .C _pututline() fails upon writing to .C utmpx , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmpx file and fails in writing to the .C utmp file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmpx file and the .C utmp file may not be in sync due to the above behavior. .C pututxline() and .C _pututxline() are only guaranteed to have written to the .C utmpx file upon successful completion. .SH FILES .PP .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututline(3), utmpname(3). .SH STANDARDS CONFORMANCE .CR endutxent() ": XPG4.2" .PP .CR getutxent() ": XPG4.2" .PP .CR getutxid() ": XPG4.2" .PP .CR getutxline() ": XPG4.2" .PP .CR pututxline() ": XPG4.2" .PP .CR setutxent() ": XPG4.2" .PP .\" .\" index@\f4getutxent()\f1 \- get pointer to next entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4_pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4setutxent()\f1 \- reset input stream to beginning of \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4endutxent()\f1 \- close currently open \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@access \f4utmpx()\f1 or \f4wtmp()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4utmpx()\f1 or \f4wtmp()\f1 file, access@@@\f3getutx(3C)\f1 .\" index@file: access \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" .\" toc@\f3getutx(3C)\f1:\0\0\f4getutxent()\f1, \f4getutxid()\f1, \f4getutxline()\f1, \f4pututxline()\f1, \f4setutxent()\f1,\n\f4endutxent()\f1@@@access utmpx file entry .\" toc@\f4getutxent()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxid()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4_pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4setutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4endutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f1utmpx file entry@@@see \f3getutx(3C)\f1 .\" .\" links@getutx.3c getutxent.3c .\" links@getutx.3c getutxid.3c .\" links@getutx.3c getutxline.3c .\" links@getutx.3c pututxline.3c .\" links@getutx.3c _pututxline.3c .\" links@getutx.3c setutxent.3c .\" links@getutx.3c endutxent.3c .\" $Header: getutx.3c,v 76.4 95/09/12 12:01:34 ssa Exp $ .TA g .TH getutx 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutxent(\|), getutxid(\|), getutxline(\|), pututxline(\|), setutxent(\|), endutxent(\|) \- access utmpx file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmpx *getutxent(void);" .PP .C "struct utmpx *getutxid(const struct utmpx *id);" .nf .PP .C "struct utmpx *getutxline(const struct utmpx *line);" .PP .C "struct utmpx *_pututxline(const struct utmpx *utmpx);" .PP .C "void pututxline(const struct utmpx *utmpx);" .PP .C "void setutxent(void);" .PP .C "void endutxent(void);" .PP .fi .SH DESCRIPTION .CR getutxent() , .CR getutxid() , and .C getutxline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmpx { char ut_user[24]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct __exit_status { short __e_termination; /* Process termination status */ short __e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ struct timeval { time_t tv_sec; /* seconds */ long tv_usec; /* and microseconds */ } ut_tv; /* time entry was made */ char ut_host[64]; /* host name, if remote; NOT SUPPORTED */ unsigned long ut_addr; /* Internet addr of host, if remote */ char ut_reserved2[12] ; /* Reserved for future use */ }; .ps .ft .fi .RE .TP 20 .C getutxent() Reads in the next entry from a .CR utmpx -like file. If the file is not already open, .C getutxent() opens it. If it reaches the end of the file, .C getutxent() fails. .TP .C getutxid() Searches forward from the current point in the .I utmpx file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutxid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutxid() fails. .TP .C getutxline() Searches forward from the current point in the .I utmpx file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutxline() fails. .TP .C pututxline() Writes out the supplied .C utmpx structure into the .I utmpx file, translates the supplied .C utmpx structure into a .C utmp structure and writes it to a .I utmp file. .C pututxline() uses .C getutxid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getutx() routines before calling .CR pututxline() . If the search as already been made, .C pututxline() does not repeat it. If .C pututxline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututxline() Performs the same actions as .CR pututxline() , except that it returns a value useful for error checking. .TP .C setutxent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutxent() Closes the currently open file. .TP .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutxid() or .CR getutxline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutxline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutxline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututxline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutxent() , .CR getutxid() , or .C getutxline() if the user has just modified those contents and passed the pointer back to .CR pututxline() . .PP .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmpx)" . .PP .C _pututxline() behaves the same as .CR pututxline() , except that it returns a pointer to a static location containing the most current utmpx entry if the .C _pututxline() call succeeds. The contents of this structure are identical to the contents of the supplied .C utmpx structure if successful. If .C _pututline() fails upon writing to .C utmpx , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmpx file and fails in writing to the .C utmp file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmpx file and the .C utmp file may not be in sync due to the above behavior. .C pututxline() and .C _pututxline() are only guaranteed to have written to the .C utmpx file upon successful completion. .SH FILES .PP .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututline(3), utmpname(3). .SH STANDARDS CONFORMANCE .CR endutxent() ": XPG4.2" .PP .CR getutxent() ": XPG4.2" .PP .CR getutxid() ": XPG4.2" .PP .CR getutxline() ": XPG4.2" .PP .CR pututxline() ": XPG4.2" .PP .CR setutxent() ": XPG4.2" .PP .\" .\" index@\f4getutxent()\f1 \- get pointer to next entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4_pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4setutxent()\f1 \- reset input stream to beginning of \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4endutxent()\f1 \- close currently open \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@access \f4utmpx()\f1 or \f4wtmp()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4utmpx()\f1 or \f4wtmp()\f1 file, access@@@\f3getutx(3C)\f1 .\" index@file: access \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" .\" toc@\f3getutx(3C)\f1:\0\0\f4getutxent()\f1, \f4getutxid()\f1, \f4getutxline()\f1, \f4pututxline()\f1, \f4setutxent()\f1,\n\f4endutxent()\f1@@@access utmpx file entry .\" toc@\f4getutxent()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxid()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4_pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4setutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4endutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f1utmpx file entry@@@see \f3getutx(3C)\f1 .\" .\" links@getutx.3c getutxent.3c .\" links@getutx.3c getutxid.3c .\" links@getutx.3c getutxline.3c .\" links@getutx.3c pututxline.3c .\" links@getutx.3c _pututxline.3c .\" links@getutx.3c setutxent.3c .\" links@getutx.3c endutxent.3c .\" $Header: getutx.3c,v 76.4 95/09/12 12:01:34 ssa Exp $ .TA g .TH getutx 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutxent(\|), getutxid(\|), getutxline(\|), pututxline(\|), setutxent(\|), endutxent(\|) \- access utmpx file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmpx *getutxent(void);" .PP .C "struct utmpx *getutxid(const struct utmpx *id);" .nf .PP .C "struct utmpx *getutxline(const struct utmpx *line);" .PP .C "struct utmpx *_pututxline(const struct utmpx *utmpx);" .PP .C "void pututxline(const struct utmpx *utmpx);" .PP .C "void setutxent(void);" .PP .C "void endutxent(void);" .PP .fi .SH DESCRIPTION .CR getutxent() , .CR getutxid() , and .C getutxline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmpx { char ut_user[24]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct __exit_status { short __e_termination; /* Process termination status */ short __e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ struct timeval { time_t tv_sec; /* seconds */ long tv_usec; /* and microseconds */ } ut_tv; /* time entry was made */ char ut_host[64]; /* host name, if remote; NOT SUPPORTED */ unsigned long ut_addr; /* Internet addr of host, if remote */ char ut_reserved2[12] ; /* Reserved for future use */ }; .ps .ft .fi .RE .TP 20 .C getutxent() Reads in the next entry from a .CR utmpx -like file. If the file is not already open, .C getutxent() opens it. If it reaches the end of the file, .C getutxent() fails. .TP .C getutxid() Searches forward from the current point in the .I utmpx file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutxid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutxid() fails. .TP .C getutxline() Searches forward from the current point in the .I utmpx file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutxline() fails. .TP .C pututxline() Writes out the supplied .C utmpx structure into the .I utmpx file, translates the supplied .C utmpx structure into a .C utmp structure and writes it to a .I utmp file. .C pututxline() uses .C getutxid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getutx() routines before calling .CR pututxline() . If the search as already been made, .C pututxline() does not repeat it. If .C pututxline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututxline() Performs the same actions as .CR pututxline() , except that it returns a value useful for error checking. .TP .C setutxent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutxent() Closes the currently open file. .TP .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutxid() or .CR getutxline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutxline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutxline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututxline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutxent() , .CR getutxid() , or .C getutxline() if the user has just modified those contents and passed the pointer back to .CR pututxline() . .PP .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmpx)" . .PP .C _pututxline() behaves the same as .CR pututxline() , except that it returns a pointer to a static location containing the most current utmpx entry if the .C _pututxline() call succeeds. The contents of this structure are identical to the contents of the supplied .C utmpx structure if successful. If .C _pututline() fails upon writing to .C utmpx , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmpx file and fails in writing to the .C utmp file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmpx file and the .C utmp file may not be in sync due to the above behavior. .C pututxline() and .C _pututxline() are only guaranteed to have written to the .C utmpx file upon successful completion. .SH FILES .PP .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututline(3), utmpname(3). .SH STANDARDS CONFORMANCE .CR endutxent() ": XPG4.2" .PP .CR getutxent() ": XPG4.2" .PP .CR getutxid() ": XPG4.2" .PP .CR getutxline() ": XPG4.2" .PP .CR pututxline() ": XPG4.2" .PP .CR setutxent() ": XPG4.2" .PP .\" .\" index@\f4getutxent()\f1 \- get pointer to next entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4_pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4setutxent()\f1 \- reset input stream to beginning of \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4endutxent()\f1 \- close currently open \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@access \f4utmpx()\f1 or \f4wtmp()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4utmpx()\f1 or \f4wtmp()\f1 file, access@@@\f3getutx(3C)\f1 .\" index@file: access \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" .\" toc@\f3getutx(3C)\f1:\0\0\f4getutxent()\f1, \f4getutxid()\f1, \f4getutxline()\f1, \f4pututxline()\f1, \f4setutxent()\f1,\n\f4endutxent()\f1@@@access utmpx file entry .\" toc@\f4getutxent()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxid()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4_pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4setutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4endutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f1utmpx file entry@@@see \f3getutx(3C)\f1 .\" .\" links@getutx.3c getutxent.3c .\" links@getutx.3c getutxid.3c .\" links@getutx.3c getutxline.3c .\" links@getutx.3c pututxline.3c .\" links@getutx.3c _pututxline.3c .\" links@getutx.3c setutxent.3c .\" links@getutx.3c endutxent.3c .\" $Header: getutx.3c,v 76.4 95/09/12 12:01:34 ssa Exp $ .TA g .TH getutx 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutxent(\|), getutxid(\|), getutxline(\|), pututxline(\|), setutxent(\|), endutxent(\|) \- access utmpx file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmpx *getutxent(void);" .PP .C "struct utmpx *getutxid(const struct utmpx *id);" .nf .PP .C "struct utmpx *getutxline(const struct utmpx *line);" .PP .C "struct utmpx *_pututxline(const struct utmpx *utmpx);" .PP .C "void pututxline(const struct utmpx *utmpx);" .PP .C "void setutxent(void);" .PP .C "void endutxent(void);" .PP .fi .SH DESCRIPTION .CR getutxent() , .CR getutxid() , and .C getutxline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmpx { char ut_user[24]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct __exit_status { short __e_termination; /* Process termination status */ short __e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ struct timeval { time_t tv_sec; /* seconds */ long tv_usec; /* and microseconds */ } ut_tv; /* time entry was made */ char ut_host[64]; /* host name, if remote; NOT SUPPORTED */ unsigned long ut_addr; /* Internet addr of host, if remote */ char ut_reserved2[12] ; /* Reserved for future use */ }; .ps .ft .fi .RE .TP 20 .C getutxent() Reads in the next entry from a .CR utmpx -like file. If the file is not already open, .C getutxent() opens it. If it reaches the end of the file, .C getutxent() fails. .TP .C getutxid() Searches forward from the current point in the .I utmpx file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutxid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutxid() fails. .TP .C getutxline() Searches forward from the current point in the .I utmpx file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutxline() fails. .TP .C pututxline() Writes out the supplied .C utmpx structure into the .I utmpx file, translates the supplied .C utmpx structure into a .C utmp structure and writes it to a .I utmp file. .C pututxline() uses .C getutxid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getutx() routines before calling .CR pututxline() . If the search as already been made, .C pututxline() does not repeat it. If .C pututxline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututxline() Performs the same actions as .CR pututxline() , except that it returns a value useful for error checking. .TP .C setutxent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutxent() Closes the currently open file. .TP .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutxid() or .CR getutxline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutxline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutxline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututxline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutxent() , .CR getutxid() , or .C getutxline() if the user has just modified those contents and passed the pointer back to .CR pututxline() . .PP .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmpx)" . .PP .C _pututxline() behaves the same as .CR pututxline() , except that it returns a pointer to a static location containing the most current utmpx entry if the .C _pututxline() call succeeds. The contents of this structure are identical to the contents of the supplied .C utmpx structure if successful. If .C _pututline() fails upon writing to .C utmpx , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmpx file and fails in writing to the .C utmp file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmpx file and the .C utmp file may not be in sync due to the above behavior. .C pututxline() and .C _pututxline() are only guaranteed to have written to the .C utmpx file upon successful completion. .SH FILES .PP .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututline(3), utmpname(3). .SH STANDARDS CONFORMANCE .CR endutxent() ": XPG4.2" .PP .CR getutxent() ": XPG4.2" .PP .CR getutxid() ": XPG4.2" .PP .CR getutxline() ": XPG4.2" .PP .CR pututxline() ": XPG4.2" .PP .CR setutxent() ": XPG4.2" .PP .\" .\" index@\f4getutxent()\f1 \- get pointer to next entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4_pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4setutxent()\f1 \- reset input stream to beginning of \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4endutxent()\f1 \- close currently open \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@access \f4utmpx()\f1 or \f4wtmp()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4utmpx()\f1 or \f4wtmp()\f1 file, access@@@\f3getutx(3C)\f1 .\" index@file: access \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" .\" toc@\f3getutx(3C)\f1:\0\0\f4getutxent()\f1, \f4getutxid()\f1, \f4getutxline()\f1, \f4pututxline()\f1, \f4setutxent()\f1,\n\f4endutxent()\f1@@@access utmpx file entry .\" toc@\f4getutxent()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxid()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4_pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4setutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4endutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f1utmpx file entry@@@see \f3getutx(3C)\f1 .\" .\" links@getutx.3c getutxent.3c .\" links@getutx.3c getutxid.3c .\" links@getutx.3c getutxline.3c .\" links@getutx.3c pututxline.3c .\" links@getutx.3c _pututxline.3c .\" links@getutx.3c setutxent.3c .\" links@getutx.3c endutxent.3c .\" $Header: getc.3s,v 76.1 95/07/05 17:28:24 ssa Exp $ .TA g .TH getc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getc(\|), getc_unlocked(\|), getchar(\|), getchar_unlocked(\|), fgetc(\|), getw(\|), getw_unlocked(\|) \- get character or word from a stream file .SH SYNOPSIS .C "#include " .PP .C "int getc(FILE *stream);" .PP .C "int getc_unlocked(FILE *stream);" .PP .C "int getchar(void);" .PP .C "int getchar_unlocked(void);" .PP .C "int fgetc(FILE *stream);" .PP .C "int getw(FILE *stream);" .PP .C "int getw_unlocked(FILE *stream);" .SH DESCRIPTION .TP 15 .CR getc() Returns the next character (i.e., byte) from the named input .IR stream , as an unsigned character converted to an integer. It also moves the file pointer, if defined, ahead one character in .IR stream. .CR getchar() is defined as .CR getc(stdin) . .CR getc() and .CR getchar() are defined both as macros and as functions. .TP .CR fgetc() Same as .CR getc() , but is a function rather than a macro. .CR fgetc() is slower than .CR getc() , but it takes less space per invocation and its name can be passed as an argument to a function. .TP .CR getw() returns the next word (i.e., .CR int in C) from the named input .IR stream. .CR getw() increments the associated file pointer, if defined, to point to the next word. The size of a word is the size of an integer and varies from machine to machine. .CR getw() assumes no special alignment in the file. .PP .CR getc_unlocked() , " getchar_unlocked()" , and .CR getw_unlocked() are identical to .CR getc() , " getchar()" , and .CR getw() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon sucessful completion, .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , and .CR fgetc() return the next byte from the input stream pointed to by .I stream .RC ( stdin for .CR getchar() " and " getchar_unlocked() ). If the stream is at end-of-file, the end-of-file indicator for the stream is set and .SM EOF is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and .SM EOF is returned. .PP Upon sucessful completion, .CR getw() " and " getw_unlocked() return the next word from the input stream pointed to by .IR stream . If the stream is at end-of-file, the end-of-file indicator for the stream is set and .CR getw() " and " getw_unlocked() return .SM EOF. If a read error occurs, the error indicator for the stream is set, and .CR getw() " and " getw_unlocked() return .SM EOF and set .CR errno to indicate the error. .PP .CR ferror() and .CR feof() (or their .CR _unlocked versions) can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , .CR getw() , " getw_unlocked()" , and .CR fgetc() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 .SM [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP .SM [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP .SM [EIO] A physical I/O error has occurred, or the process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RE .PP Additional .CR errno values may be set by the underlying .CR read() function (see .IR read (2)). .SH WARNING .CR getc() and .CR getchar() are implemented both as library functions and macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI\s0-C mode, enclose the function name in parenthesis or use the function address. The following example illustrates each of these methods : .nf .IP .CR #include .CR #undef getc \h'.4i'... .CR main() .CR { .CR " int (*get_char()) ();" \h'1i'... .CR " return_val=getc(c,fd);" \h'1i'... .CR " return_val=(getc)(c,fd1);" \h'1i'... .CR " get_char = getchar;" .CR }; .fi .PP If the integer value returned by .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , or .CR fgetc() is stored into a character variable then compared against the integer constant .CR EOF , the comparison may never succeed because sign-extension of a character on widening to integer is machine-dependent. .PP The macro version of .CR getc() incorrectly treats a .I stream argument with side effects. In particular, .CR getc(*f++) does not work sensibly. The function version of .CR getc() or .CR fgetc() should be used instead. .br Because of possible differences in word length and byte ordering, files written using .CR putw() are machine-dependent, and may be unreadable by .CR getw() on a different processor. .SS Reentrant Interfaces If .CR _REENTRANT is defined before including .RC < stdio.h >, the locked versions of the library functions for .CR getc() and .CR getchar() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR getc() and .CR getchar() . .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), fread(3S), gets(3S), putc(3S), read(2), scanf(3S). .SH STANDARDS CONFORMANCE .CR getc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fgetc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4.2, FIPS 151-2, POSIX.1, ANSI C" .PP .CR getchar() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR getw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4getc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getc_unlock()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4fgetc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getchar()\f1 \- get character or word from \f4standard input\f1 file@@@\f3getc(3S)\f1 .\" index@\f4getchar_unlocked()\f1 \- get character or word from \f4standard input\f1 file@@@\f3getc(3S)\f1 .\" index@\f4getw()\f1 \- get data word (integer) from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getw_unlocked()\f1 \- get data word (integer) from a stream file@@@\f3getc(3S)\f1 .\" index@\f1get: character or data word from a stream file@@@\f3getc(3S)\f1 .\" index@\f1data, get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f1character or data word from a stream file, get@@@\f3getc(3S)\f1 .\" index@\f1word from a stream file, get character or data@@@\f3getc(3S)\f1 .\" index@\f1stream file, get character or data word from a@@@\f3getc(3S)\f1 .\" index@file, stream: get character or data word from a stream file@@@\f3getc(3S)\f1 .\" .\" toc@\f3getc(3S)\f1:\0\0\f4getc()\f1, \f4getc_unlocked()\f1, \f4getchar()\f1, \f4getchar_unlocked()\f1, \f4fgetc()\f1, \n\f4getw()\f1, \f4getw_unlocked\f1@@@get character or word from a stream file .\" toc@\f4fgetc()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getc_unlocked()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getchar()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getchar_unlocked()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4fgetc()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getw()\f1:\0\0get word from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getw_unlocked()\f1:\0\0get word from a stream file@@@see \f3getc(3S)\f1 .\" .\" links@getc.3s getc_unlock.3s .\" links@getc.3s getchar.3s .\" links@getc.3s getchar_unl.3s .\" links@getc.3s fgetc.3s .\" links@getc.3s getw.3s .\" links@getc.3s getw_unlock.3s .\" $Header: getc.3s,v 76.1 95/07/05 17:28:24 ssa Exp $ .TA g .TH getc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getc(\|), getc_unlocked(\|), getchar(\|), getchar_unlocked(\|), fgetc(\|), getw(\|), getw_unlocked(\|) \- get character or word from a stream file .SH SYNOPSIS .C "#include " .PP .C "int getc(FILE *stream);" .PP .C "int getc_unlocked(FILE *stream);" .PP .C "int getchar(void);" .PP .C "int getchar_unlocked(void);" .PP .C "int fgetc(FILE *stream);" .PP .C "int getw(FILE *stream);" .PP .C "int getw_unlocked(FILE *stream);" .SH DESCRIPTION .TP 15 .CR getc() Returns the next character (i.e., byte) from the named input .IR stream , as an unsigned character converted to an integer. It also moves the file pointer, if defined, ahead one character in .IR stream. .CR getchar() is defined as .CR getc(stdin) . .CR getc() and .CR getchar() are defined both as macros and as functions. .TP .CR fgetc() Same as .CR getc() , but is a function rather than a macro. .CR fgetc() is slower than .CR getc() , but it takes less space per invocation and its name can be passed as an argument to a function. .TP .CR getw() returns the next word (i.e., .CR int in C) from the named input .IR stream. .CR getw() increments the associated file pointer, if defined, to point to the next word. The size of a word is the size of an integer and varies from machine to machine. .CR getw() assumes no special alignment in the file. .PP .CR getc_unlocked() , " getchar_unlocked()" , and .CR getw_unlocked() are identical to .CR getc() , " getchar()" , and .CR getw() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon sucessful completion, .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , and .CR fgetc() return the next byte from the input stream pointed to by .I stream .RC ( stdin for .CR getchar() " and " getchar_unlocked() ). If the stream is at end-of-file, the end-of-file indicator for the stream is set and .SM EOF is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and .SM EOF is returned. .PP Upon sucessful completion, .CR getw() " and " getw_unlocked() return the next word from the input stream pointed to by .IR stream . If the stream is at end-of-file, the end-of-file indicator for the stream is set and .CR getw() " and " getw_unlocked() return .SM EOF. If a read error occurs, the error indicator for the stream is set, and .CR getw() " and " getw_unlocked() return .SM EOF and set .CR errno to indicate the error. .PP .CR ferror() and .CR feof() (or their .CR _unlocked versions) can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , .CR getw() , " getw_unlocked()" , and .CR fgetc() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 .SM [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP .SM [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP .SM [EIO] A physical I/O error has occurred, or the process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RE .PP Additional .CR errno values may be set by the underlying .CR read() function (see .IR read (2)). .SH WARNING .CR getc() and .CR getchar() are implemented both as library functions and macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI\s0-C mode, enclose the function name in parenthesis or use the function address. The following example illustrates each of these methods : .nf .IP .CR #include .CR #undef getc \h'.4i'... .CR main() .CR { .CR " int (*get_char()) ();" \h'1i'... .CR " return_val=getc(c,fd);" \h'1i'... .CR " return_val=(getc)(c,fd1);" \h'1i'... .CR " get_char = getchar;" .CR }; .fi .PP If the integer value returned by .CR getc() , " getc_unlocked()" , .CR getchar() , " getchar_unlocked()" , or .CR fgetc() is stored into a character variable then compared against the integer constant .CR EOF , the comparison may never succeed because sign-extension of a character on widening to integer is machine-dependent. .PP The macro version of .CR getc() incorrectly treats a .I stream argument with side effects. In particular, .CR getc(*f++) does not work sensibly. The function version of .CR getc() or .CR fgetc() should be used instead. .br Because of possible differences in word length and byte ordering, files written using .CR putw() are machine-dependent, and may be unreadable by .CR getw() on a different processor. .SS Reentrant Interfaces If .CR _REENTRANT is defined before including .RC < stdio.h >, the locked versions of the library functions for .CR getc() and .CR getchar() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR getc() and .CR getchar() . .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), fread(3S), gets(3S), putc(3S), read(2), scanf(3S). .SH STANDARDS CONFORMANCE .CR getc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fgetc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, XPG4.2, FIPS 151-2, POSIX.1, ANSI C" .PP .CR getchar() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR getw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4getc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getc_unlock()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4fgetc()\f1 \- get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getchar()\f1 \- get character or word from \f4standard input\f1 file@@@\f3getc(3S)\f1 .\" index@\f4getchar_unlocked()\f1 \- get character or word from \f4standard input\f1 file@@@\f3getc(3S)\f1 .\" index@\f4getw()\f1 \- get data word (integer) from a stream file@@@\f3getc(3S)\f1 .\" index@\f4getw_unlocked()\f1 \- get data word (integer) from a stream file@@@\f3getc(3S)\f1 .\" index@\f1get: character or data word from a stream file@@@\f3getc(3S)\f1 .\" index@\f1data, get character or word from a stream file@@@\f3getc(3S)\f1 .\" index@\f1character or data word from a stream file, get@@@\f3getc(3S)\f1 .\" index@\f1word from a stream file, get character or data@@@\f3getc(3S)\f1 .\" index@\f1stream file, get character or data word from a@@@\f3getc(3S)\f1 .\" index@file, stream: get character or data word from a stream file@@@\f3getc(3S)\f1 .\" .\" toc@\f3getc(3S)\f1:\0\0\f4getc()\f1, \f4getc_unlocked()\f1, \f4getchar()\f1, \f4getchar_unlocked()\f1, \f4fgetc()\f1, \n\f4getw()\f1, \f4getw_unlocked\f1@@@get character or word from a stream file .\" toc@\f4fgetc()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getc_unlocked()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getchar()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getchar_unlocked()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4fgetc()\f1:\0\0get character from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getw()\f1:\0\0get word from a stream file@@@see \f3getc(3S)\f1 .\" toc@\f4getw_unlocked()\f1:\0\0get word from a stream file@@@see \f3getc(3S)\f1 .\" .\" links@getc.3s getc_unlock.3s .\" links@getc.3s getchar.3s .\" links@getc.3s getchar_unl.3s .\" links@getc.3s fgetc.3s .\" links@getc.3s getw.3s .\" links@getc.3s getw_unlock.3s .\" $Header: getwc.3c,v 76.1 95/07/05 17:30:42 ssa Exp $ .TA g .TH getwc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getwc(\|), getwc_unlocked(\|), getwchar(\|), getwchar_unlocked(\|), fgetwc(\|), fgetwc_unlocked(\|) \- get a wide character from a stream file .SH SYNOPSIS .C "#include " .PP .C "wint_t getwc(FILE *stream);" .PP .C "wint_t getwc_unlocked(FILE *stream);" .PP .C "wint_t getwchar(void);" .PP .C "wint_t getwchar_unlocked(void);" .PP .C "wint_t fgetwc(FILE *stream);" .PP .C "wint_t fgetwc_unlocked(FILE *stream);" .SS Remarks: These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. They parallel the 8 bit character I/O functions defined in .IR getc(3S) . .SH DESCRIPTION .TP 15 .C getwc() Returns the next character from the named input .IR stream , converts that to the corresponding wide character and moves the file pointer ahead one character in .IR stream . .CR getwchar() is defined as .CR getwc(stdin) . .CR getwc() and .CR getwchar() are defined both as macros and as functions. .TP .C fgetwc() Behaves like .CR getwc() , but is a function rather than a macro. .PP Definitions for these functions, the types .CR wint_t , .CR wchar_t and the value .CR WEOF are provided in header file .RC < wchar.h >. .PP .CR getwc_unlocked() , .CR getwchar_unlocked() , and .CR fgetwc_unlocked() are identical to .CR getwc() , .CR getwchar() , and .CR fgetwc() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon successful completion, .CR getwc() , .CR getwc_unlocked() , .CR getwchar() , .CR getwchar_unlocked() , .CR fgetwc() , and .CR fgetwc_unlocked() return the next wide character read from .I stream .RC ( stdin for .CR getwchar() ) converted to a type .CR wint_t . If the stream is at end-of-file, the end-of-file indicator for the stream is set and .CR WEOF is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and .CR WEOF is returned. .PP .CR ferror() and .CR feof() can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR getwc() , .CR getwc_unlocked() , .CR getwchar() , .CR getwchar_unlocked() , .CR fgetwc() , and .CR fgetwc_unlocked() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP [EIO] A physical I/O error has occurred, or the process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .TP [EILSEQ] The data obtained from the input stream does not form a valid wide character. .RE .PP Additional .CR errno values may be set by the underlying .CR read() function (see .IR read (2)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS If the value returned by .CR getwc() , .CR getwchar() , .CR fgetwc() , or .CR fgetwc_unlocked() is stored into a type .CR wchar_t variable then compared against the constant .CR WEOF , the comparison may never succeed because extension of a .CR wchar_t to a .CR wint_t is machine-dependent. .SH AUTHOR .CR getwc() was developed by OSF and HP. .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), fread(3S), fgetws(3C), putwc(3C), read(2), scanf(3S). .SH STANDARDS CONFORMANCE .CR getwc() ": XPG4" .PP .CR fgetwc() ": XPG4" .PP .CR getwchar() ": XPG4" .\" .\" index@\f4getwc()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwc_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwchar()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwchar_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4fgetwc()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4fgetwc_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1get: wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1data, get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1wide character from a stream file, get@@@\f3getwc(3C)\f1 .\" index@\f1stream file, get wide character from a@@@\f3getwc(3C)\f1 .\" index@\f1file, stream: get wide character from a stream file@@@\f3getwc(3C)\f1 .\" .\" toc@\f3getwc(3C)\f1:\0\0\f4getwc()\f1, \f4getwc_unlocked()\f1, \f4getwchar()\f1, \f4getwchar_unlocked\f1, \f4fgetwc()\f1, \n\f4fgetwc_unlocked()\f1@@@get wide character from a stream file .\" toc@\f4getwc()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwc_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwchar()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwchar_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4fgetwc()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4fgetwc_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" .\" links@getwc.3c getwc_unloc.3c .\" links@getwc.3c getwchar_un.3c .\" links@getwc.3c getwchar.3c .\" links@getwc.3c fgetwc.3c .\" links@getwc.3c fgetwc_unlo.3c .\" .\" fileset_database@getwc.3c PROGRAMING-MAN .\" $Header: getwc.3c,v 76.1 95/07/05 17:30:42 ssa Exp $ .TA g .TH getwc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getwc(\|), getwc_unlocked(\|), getwchar(\|), getwchar_unlocked(\|), fgetwc(\|), fgetwc_unlocked(\|) \- get a wide character from a stream file .SH SYNOPSIS .C "#include " .PP .C "wint_t getwc(FILE *stream);" .PP .C "wint_t getwc_unlocked(FILE *stream);" .PP .C "wint_t getwchar(void);" .PP .C "wint_t getwchar_unlocked(void);" .PP .C "wint_t fgetwc(FILE *stream);" .PP .C "wint_t fgetwc_unlocked(FILE *stream);" .SS Remarks: These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. They parallel the 8 bit character I/O functions defined in .IR getc(3S) . .SH DESCRIPTION .TP 15 .C getwc() Returns the next character from the named input .IR stream , converts that to the corresponding wide character and moves the file pointer ahead one character in .IR stream . .CR getwchar() is defined as .CR getwc(stdin) . .CR getwc() and .CR getwchar() are defined both as macros and as functions. .TP .C fgetwc() Behaves like .CR getwc() , but is a function rather than a macro. .PP Definitions for these functions, the types .CR wint_t , .CR wchar_t and the value .CR WEOF are provided in header file .RC < wchar.h >. .PP .CR getwc_unlocked() , .CR getwchar_unlocked() , and .CR fgetwc_unlocked() are identical to .CR getwc() , .CR getwchar() , and .CR fgetwc() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon successful completion, .CR getwc() , .CR getwc_unlocked() , .CR getwchar() , .CR getwchar_unlocked() , .CR fgetwc() , and .CR fgetwc_unlocked() return the next wide character read from .I stream .RC ( stdin for .CR getwchar() ) converted to a type .CR wint_t . If the stream is at end-of-file, the end-of-file indicator for the stream is set and .CR WEOF is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and .CR WEOF is returned. .PP .CR ferror() and .CR feof() can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR getwc() , .CR getwc_unlocked() , .CR getwchar() , .CR getwchar_unlocked() , .CR fgetwc() , and .CR fgetwc_unlocked() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP [EIO] A physical I/O error has occurred, or the process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .TP [EILSEQ] The data obtained from the input stream does not form a valid wide character. .RE .PP Additional .CR errno values may be set by the underlying .CR read() function (see .IR read (2)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS If the value returned by .CR getwc() , .CR getwchar() , .CR fgetwc() , or .CR fgetwc_unlocked() is stored into a type .CR wchar_t variable then compared against the constant .CR WEOF , the comparison may never succeed because extension of a .CR wchar_t to a .CR wint_t is machine-dependent. .SH AUTHOR .CR getwc() was developed by OSF and HP. .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), fread(3S), fgetws(3C), putwc(3C), read(2), scanf(3S). .SH STANDARDS CONFORMANCE .CR getwc() ": XPG4" .PP .CR fgetwc() ": XPG4" .PP .CR getwchar() ": XPG4" .\" .\" index@\f4getwc()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwc_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwchar()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwchar_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4fgetwc()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4fgetwc_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1get: wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1data, get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1wide character from a stream file, get@@@\f3getwc(3C)\f1 .\" index@\f1stream file, get wide character from a@@@\f3getwc(3C)\f1 .\" index@\f1file, stream: get wide character from a stream file@@@\f3getwc(3C)\f1 .\" .\" toc@\f3getwc(3C)\f1:\0\0\f4getwc()\f1, \f4getwc_unlocked()\f1, \f4getwchar()\f1, \f4getwchar_unlocked\f1, \f4fgetwc()\f1, \n\f4fgetwc_unlocked()\f1@@@get wide character from a stream file .\" toc@\f4getwc()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwc_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwchar()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwchar_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4fgetwc()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4fgetwc_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" .\" links@getwc.3c getwc_unloc.3c .\" links@getwc.3c getwchar_un.3c .\" links@getwc.3c getwchar.3c .\" links@getwc.3c fgetwc.3c .\" links@getwc.3c fgetwc_unlo.3c .\" .\" fileset_database@getwc.3c PROGRAMING-MAN .\" $Header: getwc.3c,v 76.1 95/07/05 17:30:42 ssa Exp $ .TA g .TH getwc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getwc(\|), getwc_unlocked(\|), getwchar(\|), getwchar_unlocked(\|), fgetwc(\|), fgetwc_unlocked(\|) \- get a wide character from a stream file .SH SYNOPSIS .C "#include " .PP .C "wint_t getwc(FILE *stream);" .PP .C "wint_t getwc_unlocked(FILE *stream);" .PP .C "wint_t getwchar(void);" .PP .C "wint_t getwchar_unlocked(void);" .PP .C "wint_t fgetwc(FILE *stream);" .PP .C "wint_t fgetwc_unlocked(FILE *stream);" .SS Remarks: These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. They parallel the 8 bit character I/O functions defined in .IR getc(3S) . .SH DESCRIPTION .TP 15 .C getwc() Returns the next character from the named input .IR stream , converts that to the corresponding wide character and moves the file pointer ahead one character in .IR stream . .CR getwchar() is defined as .CR getwc(stdin) . .CR getwc() and .CR getwchar() are defined both as macros and as functions. .TP .C fgetwc() Behaves like .CR getwc() , but is a function rather than a macro. .PP Definitions for these functions, the types .CR wint_t , .CR wchar_t and the value .CR WEOF are provided in header file .RC < wchar.h >. .PP .CR getwc_unlocked() , .CR getwchar_unlocked() , and .CR fgetwc_unlocked() are identical to .CR getwc() , .CR getwchar() , and .CR fgetwc() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon successful completion, .CR getwc() , .CR getwc_unlocked() , .CR getwchar() , .CR getwchar_unlocked() , .CR fgetwc() , and .CR fgetwc_unlocked() return the next wide character read from .I stream .RC ( stdin for .CR getwchar() ) converted to a type .CR wint_t . If the stream is at end-of-file, the end-of-file indicator for the stream is set and .CR WEOF is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and .CR WEOF is returned. .PP .CR ferror() and .CR feof() can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR getwc() , .CR getwc_unlocked() , .CR getwchar() , .CR getwchar_unlocked() , .CR fgetwc() , and .CR fgetwc_unlocked() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP [EIO] A physical I/O error has occurred, or the process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .TP [EILSEQ] The data obtained from the input stream does not form a valid wide character. .RE .PP Additional .CR errno values may be set by the underlying .CR read() function (see .IR read (2)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS If the value returned by .CR getwc() , .CR getwchar() , .CR fgetwc() , or .CR fgetwc_unlocked() is stored into a type .CR wchar_t variable then compared against the constant .CR WEOF , the comparison may never succeed because extension of a .CR wchar_t to a .CR wint_t is machine-dependent. .SH AUTHOR .CR getwc() was developed by OSF and HP. .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), fread(3S), fgetws(3C), putwc(3C), read(2), scanf(3S). .SH STANDARDS CONFORMANCE .CR getwc() ": XPG4" .PP .CR fgetwc() ": XPG4" .PP .CR getwchar() ": XPG4" .\" .\" index@\f4getwc()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwc_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwchar()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwchar_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4fgetwc()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4fgetwc_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1get: wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1data, get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1wide character from a stream file, get@@@\f3getwc(3C)\f1 .\" index@\f1stream file, get wide character from a@@@\f3getwc(3C)\f1 .\" index@\f1file, stream: get wide character from a stream file@@@\f3getwc(3C)\f1 .\" .\" toc@\f3getwc(3C)\f1:\0\0\f4getwc()\f1, \f4getwc_unlocked()\f1, \f4getwchar()\f1, \f4getwchar_unlocked\f1, \f4fgetwc()\f1, \n\f4fgetwc_unlocked()\f1@@@get wide character from a stream file .\" toc@\f4getwc()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwc_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwchar()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwchar_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4fgetwc()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4fgetwc_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" .\" links@getwc.3c getwc_unloc.3c .\" links@getwc.3c getwchar_un.3c .\" links@getwc.3c getwchar.3c .\" links@getwc.3c fgetwc.3c .\" links@getwc.3c fgetwc_unlo.3c .\" .\" fileset_database@getwc.3c PROGRAMING-MAN .\" $Header: getwc.3c,v 76.1 95/07/05 17:30:42 ssa Exp $ .TA g .TH getwc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getwc(\|), getwc_unlocked(\|), getwchar(\|), getwchar_unlocked(\|), fgetwc(\|), fgetwc_unlocked(\|) \- get a wide character from a stream file .SH SYNOPSIS .C "#include " .PP .C "wint_t getwc(FILE *stream);" .PP .C "wint_t getwc_unlocked(FILE *stream);" .PP .C "wint_t getwchar(void);" .PP .C "wint_t getwchar_unlocked(void);" .PP .C "wint_t fgetwc(FILE *stream);" .PP .C "wint_t fgetwc_unlocked(FILE *stream);" .SS Remarks: These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. They parallel the 8 bit character I/O functions defined in .IR getc(3S) . .SH DESCRIPTION .TP 15 .C getwc() Returns the next character from the named input .IR stream , converts that to the corresponding wide character and moves the file pointer ahead one character in .IR stream . .CR getwchar() is defined as .CR getwc(stdin) . .CR getwc() and .CR getwchar() are defined both as macros and as functions. .TP .C fgetwc() Behaves like .CR getwc() , but is a function rather than a macro. .PP Definitions for these functions, the types .CR wint_t , .CR wchar_t and the value .CR WEOF are provided in header file .RC < wchar.h >. .PP .CR getwc_unlocked() , .CR getwchar_unlocked() , and .CR fgetwc_unlocked() are identical to .CR getwc() , .CR getwchar() , and .CR fgetwc() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon successful completion, .CR getwc() , .CR getwc_unlocked() , .CR getwchar() , .CR getwchar_unlocked() , .CR fgetwc() , and .CR fgetwc_unlocked() return the next wide character read from .I stream .RC ( stdin for .CR getwchar() ) converted to a type .CR wint_t . If the stream is at end-of-file, the end-of-file indicator for the stream is set and .CR WEOF is returned. If a read error occurs, the error indicator for the stream is set, .CR errno is set to indicate the error, and .CR WEOF is returned. .PP .CR ferror() and .CR feof() can be used to distinguish between an error condition and an end-of-file condition. .SH ERRORS .CR getwc() , .CR getwc_unlocked() , .CR getwchar() , .CR getwchar_unlocked() , .CR fgetwc() , and .CR fgetwc_unlocked() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP [EIO] A physical I/O error has occurred, or the process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .TP [EILSEQ] The data obtained from the input stream does not form a valid wide character. .RE .PP Additional .CR errno values may be set by the underlying .CR read() function (see .IR read (2)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS If the value returned by .CR getwc() , .CR getwchar() , .CR fgetwc() , or .CR fgetwc_unlocked() is stored into a type .CR wchar_t variable then compared against the constant .CR WEOF , the comparison may never succeed because extension of a .CR wchar_t to a .CR wint_t is machine-dependent. .SH AUTHOR .CR getwc() was developed by OSF and HP. .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), fread(3S), fgetws(3C), putwc(3C), read(2), scanf(3S). .SH STANDARDS CONFORMANCE .CR getwc() ": XPG4" .PP .CR fgetwc() ": XPG4" .PP .CR getwchar() ": XPG4" .\" .\" index@\f4getwc()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwc_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwchar()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4getwchar_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4fgetwc()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f4fgetwc_unlocked()\f1 \- get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1get: wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1data, get wide character from a stream file@@@\f3getwc(3C)\f1 .\" index@\f1wide character from a stream file, get@@@\f3getwc(3C)\f1 .\" index@\f1stream file, get wide character from a@@@\f3getwc(3C)\f1 .\" index@\f1file, stream: get wide character from a stream file@@@\f3getwc(3C)\f1 .\" .\" toc@\f3getwc(3C)\f1:\0\0\f4getwc()\f1, \f4getwc_unlocked()\f1, \f4getwchar()\f1, \f4getwchar_unlocked\f1, \f4fgetwc()\f1, \n\f4fgetwc_unlocked()\f1@@@get wide character from a stream file .\" toc@\f4getwc()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwc_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwchar()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4getwchar_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4fgetwc()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" toc@\f4fgetwc_unlocked()\f1:\0\0get wide character from a stream file@@@see \f3getwc(3C)\f1 .\" .\" links@getwc.3c getwc_unloc.3c .\" links@getwc.3c getwchar_un.3c .\" links@getwc.3c getwchar.3c .\" links@getwc.3c fgetwc.3c .\" links@getwc.3c fgetwc_unlo.3c .\" .\" fileset_database@getwc.3c PROGRAMING-MAN .\" $Header: getwd.3c,v 76.1 95/07/05 17:31:07 ssa Exp $ .TA g .TH getwd 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getwd(\|) \- get pathname of current working directory .SH SYNOPSIS .C "#include " .PP .C "char *getwd(char *buf);" .SH DESCRIPTION .C getwd() places the absolute pathname of the current working directory in the array pointed to by .IR buf , and returns .IR buf . .PP If the length of the pathname of the current working directory is greater than .SM PATH_MAX+1 bytes, .C getwd() fails and returns a null pointer. .PP .SH RETURN VALUE Upon successful completion, .CR getwd() returns a pointer to the current directory pathname. Otherwise, it returns .SM NULL with .C errno set. .SH ERRORS .C getwd() fails if the following condition is encountered: .RS .TP 20 .SM [ENAMETOOLONG] The length of the specified path name exceeds .C PATH_MAX+1 bytes, or the length of a component of the path name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .RE .PP .C getwd() may fail if any of the following conditions are encountered: .RS .TP 20 .SM [EACCES] Read or search permission is denied for a component of pathname. .TP .SM [EFAULT] .I buf points outside the allocated address space of the process. .C getwd() may not always detect this error. .RE .SH EXAMPLES .RS .ift .ft 4 .ifn .ft 3 .ps +1 .nf #include #include char *cwd; char buf[PATH_MAX\|+\|1\|]; \h'1i'.\|.\|. if ((cwd = getwd(buf)) == NULL) { perror("getwd"); exit(1); } puts(cwd); .fi .RE .SH WARNINGS For portability, .C getcwd() is preferred over this function. .SH AUTHOR .C getwd() was developed by HP and the University of California, Berkeley. .SH SEE ALSO getcwd(3C). .SH STANDARDS CONFORMANCE .CR getwd() ": XPG4.2" .\" toc@\f3getwd(3C)\f1:\0\0\f4getwd\f1@@@get pathname of current working directory .\" index@\f4getwd()\f1get pathname of current working directory@@@\f3getwd(3C)\f1 .\" index@get pathname of current working directory@@@\f3getwd(3C)\f1 .\" index@pathname of current working directory, get@@@\f3getwd(3C)\f1 .\" index@current working directory, get pathname of@@@\f3getwd(3C)\f1 .\" index@working directory, get pathname of current@@@\f3getwd(3C)\f1 .\" index@directory, get pathname of current working@@@\f3getwd(3C)\f1 .\" $Header: getwin.3x,v 76.2 95/08/01 11:00:05 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getwin 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getwin, putwin \(em dump window to, and reload window from, a file .SH SYNOPSIS .C "#include " .P .C "WINDOW *getwin(FILE *\f2filep\fP);" .P .C "int putwin(WINDOW *\f2win\fP, FILE *\f2filep\fP);" .SH DESCRIPTION The .Fn getwin function reads window-related data stored in the file by .CR putwin() . The function then creates and initialises a new window using that data. .P The .Fn putwin function writes all data associated with \f2win\f1 into the .I stdio stream to which \f2filep\f1 points, using an unspecified format. This information can be retrieved later using .CR getwin() . .SH "RETURN VALUE" Upon successful completion, .Fn getwin returns a pointer to the window it created. Otherwise, it returns a null pointer. .P Upon successful completion, .Fn putwin returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" scr_dump(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getwin(3X)\f1:\0\0\f4getwin()\f1, \f4putwin()\f1@@@dump window to, and reload window from a file .\" toc@\f4putwin()\f1: dump window to and reload window from a file@@@see \f3getwin(3X)\f1 .\" .\" index@\f4getwin()\f1 \- dump window to and reload window from a file@@@\f3getwin(3X)\f1 .\" index@\f4putwin()\f1 \- dump window to and reload window from a file@@@\f3getwin(3X)\f1 .\" index@\f1dump window to and reload window from a file@@@\f3getwin(3X)\f1 .\" index@\f1reload window from a file@@@\f3getwin(3X)\f1 .\" index@\f1window, dump to and reload from a file@@@\f3getwin(3X)\f1 .\" index@\f1file, dump window to and reload window from@@@\f3getwin(3X)\f1 .\" .\" links@getwin.3x putwin.3x .\" .\" fileset_database@getwin.3x CURS-ENG-A-MAN .\" $Header: getyx.3x,v 76.2 95/08/01 11:01:31 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getyx 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getyx \(em get cursor and window coordinates .SH SYNOPSIS .C "#include " .P .C "void getyx(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .SH DESCRIPTION The .Fn getyx macro stores the cursor position of the specified window in \f2y\f1 and \f2x\f1. .SH "RETURN VALUE" No return values are defined. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These interfaces are macros and `\f4&\f1' cannot be used before the \f2y\f1 and \f2x\f1 arguments. .SH "SEE ALSO" getbegyx(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" index@\f4getyx()\f1 \- get cursor and window coordinates@@@\f3getyx(3X)\f1 .\" index@\f1get cursor and window coordinates@@@\f3getyx(3X)\f1 .\" index@\f1cursor and window coordinates, get@@@\f3getyx(3X)\f1 .\" index@\f1window, get cursor and window coordinates@@@\f3getyx(3X)\f1 .\" index@\f1coordinates, get cursor and window coordinates@@@\f3getyx(3X)\f1 .\" .\" toc@\f3getyx(3X)\f1:\0\0\f4getyx()\f1@@@get cursor and window coordinates .\" .\" fileset_database@getyx.3x CURS-ENG-A-MAN .\" $Header: crt0.3,v 72.4 94/09/02 14:40:25 ssa Exp $ .TA c .TH crt0 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crt0.o, gcrt0.o, mcrt0.o \- execution startup routines .SH DESCRIPTION .PP The C, Pascal, and FORTRAN compilers link in the object files .CR crt0.o , .CR gcrt0.o , or .C mcrt0.o to provide startup capabilities and environments for program execution. All are identical except that .C gcrt0.o and .C mcrt0.o provide additional functionality for .IR gprof (1) and .IR prof (1) profiling support respectively. .PP The following symbols are defined in these object files: .RS .TP 20 .C _\|_argc_value A variable of type .I int containing the number of arguments. .TP .C _\|_argv_value An array of character pointers to the arguments themselves. .TP .C _environ An array of character pointers to the environment in which the program will run. This array is terminated by a null pointer. .TP .SM .C _FPU_MODEL A variable of type .I short containing the FPU model number returned by the FP status instruction. This variable is initialized with data from the kernel. .TP .SM .C _FPU_REVISION A variable of type .I short containing the FPU revision number returned by the FP status instruction. This variable is initialized with data from the kernel. .TP .SM .C _CPU_REVISION A variable of type .I int containing the CPU revision of the machine. This variable is initialized with data from the kernel. .TP .SM .C _SYSTEM_ID A variable of type .I int containing the system id value for an executable program. .TP .SM .C $START$ Execution start address. .TP .C _start A secondary startup routine for C programs, called from .CR $START$ , which in turn calls .CR main . This routine is contained in the C library rather than the .C crt0.o file. For Pascal and F\s-2ORTRAN\s0 programs, this symbol labels the beginning of the outer block (main program) and is generated by the compilers. .TP .C $global$ The initial address of the program's data pointer. The startup code loads this address into general register 27. .TP .C $UNWIND_START The beginning of the stack unwind table. .TP .C $UNWIND_END The end of the stack unwind table. .TP .C $RECOVER_START The beginning of the try/recover table. .TP .C $RECOVER_END The end of the try/recover table. .RE .PP The .C crt0.o file defines a null procedure for .CR _mcount , so programs compiled with profiling can be linked without profiling. .PP The linker defines the following two symbols: .RS .TP 20 .C _\|_text_start The beginning address of the program's text area. .PD 0 .TP .C _\|_data_start The beginning address of the program's data area. .PD .RE .SH AUTHOR The features described in this entry originated from .SM AT&T UNIX System III. .SH SEE ALSO .PD .SS Profiling and Debugging Tools: .TP 18 .IR gprof(1) display call graph profile data .PD 0 .TP .IR monitor(3C) prepare execution profile .TP .IR prof(1) display profile data .TP .IR profil(2) execution time profile .PD .SS System Tools: .TP 18 .IR cc(1) invoke the HP-UX C compiler .PD 0 .TP .IR exec(2) execute a file .TP f77(1) invoke the HP-UX FORTRAN compiler .TP .IR ld(1) invoke the link editor .TP .IR pc(1) invoke the HP-UX Pascal compiler .PD .SS Miscellaneous: .TP 18 .IR end(3C) symbol of the last locations in program .PD .\" .\" index@\f4crt0.o\f1, \f4gcrt0.o\f1, \f4mcrt0.o\f1, \f4frt0.o\f1, \f4mfrt0.o\f1 \- execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4crt0.o\f1, \f4mcrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4gcrt0.o\f1, \f4gfrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4gfrt0.o\f1, \f4gcrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4mcrt0.o\f1, \f4crt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4frt0.o\f1, \f4mfrt0.o\f1 \- F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4mfrt0.o\f1, \f4frt0.o\f1 \- F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@Pascal and C execution startup routines@@@\f3crt0(3)\f1 .\" index@F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@execution startup routines, C, Pascal, and F\s-2ORTRAN\s+2@@@\f3crt0(3)\f1 .\" .\" toc@\f3crt0(3)\f1:\0\0\f4crt0.o\f1, \f4mcrt0.o\f1, \f4frt0.o\f1, \f4mfrt0.o\f1@@@execution startup routines .\" toc@\f4crt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4gcrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4mcrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4frt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4mfrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" .\" links@crt0.3 crt0.o.3 .\" links@crt0.3 gcrt0.o.3 .\" links@crt0.3 mcrt0.o.3 .\" links@crt0.3 frt0.o.3 .\" links@crt0.3 gfrt0.o.3 .\" links@crt0.3 mfrt0.o.3 .\" .\" fileset_database@crt0.3 PROGRAMING-MAN .\" $Header: glob.3c,v 72.5 94/11/15 09:54:56 ssa Exp $ .TA g .TH glob 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME glob(), globfree() \- file name generation function .SH SYNOPSIS .C "#include " .PP .C "int glob(" .nf .PD 0 .IP .C "const char *pattern," .C "int flags," .C "int (*errfunc)(const char *, int)," .C "glob_t *pglob" .PP .C ");" .PD .PP .C "void globfree(glob_t *pglob);" .SH DESCRIPTION .CR glob() is a path name generator. .I pattern is a pointer to a path name pattern to be expanded. If .I pattern contains any of the special characters .CR * , .CR ? , or .CR [ , .I pattern is matched against all accessible path names. In order to have access to a path name, .CR glob() requires: .RS .TP 3 \(bu Search permission on every component of a path except the last. .TP \(bu Read permission on each directory of any file name component of .I pattern that contains any of the above special characters. .RE .PP .CR glob() stores the number of matched path names in .I pglob \|\(mi>\| gl_pathc and a pointer to a sorted list of path names in .IR pglob \|\(mi\|> gl_pathv . The first pointer after the last path name is a NULL pointer. .PP It is the caller's responsibility to allocate space for the structure pointed to by .IR pglob . .CR glob() allocates other space as needed, including the memory pointed to by .IR gl_pathv . .CR globfree() frees any space associated with .IR pglob from a previous call to .CR glob() . .PP The .I flags argument is used to control the behavior of .CR glob() . The value of .I flags is the bit-wise inclusive OR of the following constants defined in .CR : .RS .TP 20 .C GLOB_NOESCAPE Disable backslash escaping. .TP .C GLOB_ERR Causes .CR glob() to return when it first encounters a directory that it cannot open or read. Ordinarily, .CR glob() continues to find matches. .TP .C GLOB_MARK Each path name that matches .I pattern and is a directory, has a .CR / appended. .TP .C GLOB_NOSORT Ordinarily, .CR glob() sorts the matching path names according to the currently active .I collation sequence as defined by the .CR LC_COLLATE category. When this flag is used, the order of path names returned is unspecified. .TP .C GLOB_NOCHECK If .I pattern does not match any path name, .CR glob() returns a list consisting of only .IR pattern , and the number of matched path names is 1. .TP .C GLOB_DOOFFS Make use of .IR pglob \|\(mi>\| gl_offs . If this flag is set, .IR pglob \|\(mi>\| gl_offs is used to specify how many NULL pointers to add to the beginning of .IR pglob \|\(mi>\| gl_pathv . In other words, .IR pglob \|\(mi>\| gl_pathv points to .IR pglob \|\(mi>\| gl_offs NULL pointers, followed by .IR pglob \|\(mi>\| gl_pathc path name pointers, followed by a NULL pointer. .TP .C GLOB_APPEND Append path names generated to the ones from a previous call to .CR glob() . .PP The .CR GLOB_APPEND flag can be used to append a new set of path names to those found in a previous call to .CR glob() . The following rules apply when two or more calls to .CR glob() are made with the same value of .I pglob and without intervening calls to .CR globfree() : .RS .TP 3 \(bu The first call must not set .CR GLOB_APPEND . All subsequent calls must set it. .TP \(bu All of the calls must set .CR GLOB_DOOFFS , or all must not set it. .TP \(bu After the second call, .IR pglob \|\(mi>\| gl_pathv points to a list containing the following: .RS .RS .TP 3 \(bu Zero or more NULL pointers, as specified by .CR GOB_DOOFFS and .IR pglob \|\(mi>\| gl_offs . .TP \(bu Pointers to the path names that were in the .IR pglob \|\(mi>\| gl_pathv list before the call, in the same order as before. .TP \(bu Pointers to the new path names generated by the second call, in the specified order. .RE .RE .TP 3 \(bu The count returned in .IR pglob \|\(mi>\| gl_pathc will be the total number of path names from the two calls. .TP \(bu The application can change any of the fields after a call to .CR glob() . If it does, it must reset them to the original value before a subsequent call, using the same .IR pglob value, to .CR globfree() or .CR glob() with the .CR GLOB_APPEND flag. .RE .RE .PP If, during the search, a directory is encountered that cannot be opened or read and .I errfunc is not NULL, .CR glob() calls .RI ( \(**errfunc )(\|) with two arguments: .RS .TP 3 \(bu A pointer to the path that failed. .TP \(bu The value of .CR errno from the failure. .RE .PP If .I errfunc is called and returns nonzero, or if the .CR GLOB_ERR flag is set in .IR flags , .CR glob() stops the scan and returns .CR GLOB_ABORTED after setting .CR gl_pathc and .CR gl_pathv in .I pglob to reflect the paths already scanned. If .CR GLOB_ERR is not set and either .I errfunc is NULL or .RI ( \(**errfunc )(\|) returns zero, the error is ignored. .SS Pattern Matching Notation The form of the patterns is the Pattern Matching Notation as qualified for Filename Expansion (see .IR regexp (5)) with the following exceptions: .RS .TP 3 \(bu Tilde .RC ( ~ ) expansion is not performed. .TP \(bu Variable expansion is not performed. .RE .PP .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions, and also the order of the returned paths if .CR GLOB_NOSORT is not selected. .PP The .CR LC_CTYPE category determines the interpretation of text as single byte and/or multibyte characters, and determines which characters are matched by character class expressions in regular expressions. .SS International Code Set Support Single byte and multibyte character code sets are supported. .SH RETURN VALUE If .CR glob() terminates due to an error, it returns one of the following constants (defined in .CR ); otherwise, it returns zero. .RS .TP 20 .C GLOB_NOSPACE An attempt to allocate memory failed. .TP .C GLOB_ABORTED The scan was stopped because .CR GLOB_ERR was set or .RI ( \(**errfunc )(\|) returned nonzero. .TP .C GLOB_NOMATCH The .I pattern does not match any existing path name, and .CR GLOB_NOCHECK was not set in .IR flags . .RE .PP In any case, the argument .IR pglob \|\(mi>\| gl_pathc returns the number of matched path names and the argument .IR pglob \|\(mi>\| gl_pathv contains a pointer to a null-terminated list of matched and sorted path names. .PP However, if .IR pglob \|\(mi>\| gl_pathc is zero, the content of .IR pglob \|\(mi>\| gl_pathv is undefined. .PP If the .I pattern argument passed to .CR glob() is badly constructed, .CR glob() returns zero and sets .CR gl_pathc to zero unless .CR GLOB_NOCHECK was set, in which case .I pattern is returned and .CR gl_pathc is set to 1. .SH WARNINGS .CR GLOB_APPEND must not be set in an initial call to .CR glob() . .SH AUTHOR .CR glob() and .CR globfree() were developed by OSF and HP. .SH SEE ALSO sh(1), fnmatch(3C), regexp(5). .SH STANDARDS CONFORMANCE .CR glob() ": XPG4, POSIX.2" .PP .CR globfree() ": XPG4, POSIX.2" .\" .\" index@\f4glob()\f1 \- file name generation function@@@\f3glob(3C)\f1 .\" index@\f4globfree()\f1 \- free space associated with file name generation function@@@\f3glob(3C)\f1 .\" index@\f1file name generation function@@@\f3glob(3C)\f1 .\" index@\f1generate file names@@@\f3glob(3C)\f1 .\" index@\f1create file names@@@\f3glob(3C)\f1 .\" .\" toc@\f3glob(3C)\f1:\0\0\f4glob()\f1, \f4globfree()\f1@@@file name generation function\f1 .\" toc@\f4globfree()\f1:\0\0free space associated with file name generation function@@@\f1see \f3glob(3C)\f1 .\" .\" links@glob.3c globfree.3c .\" $Header: glob.3c,v 72.5 94/11/15 09:54:56 ssa Exp $ .TA g .TH glob 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME glob(), globfree() \- file name generation function .SH SYNOPSIS .C "#include " .PP .C "int glob(" .nf .PD 0 .IP .C "const char *pattern," .C "int flags," .C "int (*errfunc)(const char *, int)," .C "glob_t *pglob" .PP .C ");" .PD .PP .C "void globfree(glob_t *pglob);" .SH DESCRIPTION .CR glob() is a path name generator. .I pattern is a pointer to a path name pattern to be expanded. If .I pattern contains any of the special characters .CR * , .CR ? , or .CR [ , .I pattern is matched against all accessible path names. In order to have access to a path name, .CR glob() requires: .RS .TP 3 \(bu Search permission on every component of a path except the last. .TP \(bu Read permission on each directory of any file name component of .I pattern that contains any of the above special characters. .RE .PP .CR glob() stores the number of matched path names in .I pglob \|\(mi>\| gl_pathc and a pointer to a sorted list of path names in .IR pglob \|\(mi\|> gl_pathv . The first pointer after the last path name is a NULL pointer. .PP It is the caller's responsibility to allocate space for the structure pointed to by .IR pglob . .CR glob() allocates other space as needed, including the memory pointed to by .IR gl_pathv . .CR globfree() frees any space associated with .IR pglob from a previous call to .CR glob() . .PP The .I flags argument is used to control the behavior of .CR glob() . The value of .I flags is the bit-wise inclusive OR of the following constants defined in .CR : .RS .TP 20 .C GLOB_NOESCAPE Disable backslash escaping. .TP .C GLOB_ERR Causes .CR glob() to return when it first encounters a directory that it cannot open or read. Ordinarily, .CR glob() continues to find matches. .TP .C GLOB_MARK Each path name that matches .I pattern and is a directory, has a .CR / appended. .TP .C GLOB_NOSORT Ordinarily, .CR glob() sorts the matching path names according to the currently active .I collation sequence as defined by the .CR LC_COLLATE category. When this flag is used, the order of path names returned is unspecified. .TP .C GLOB_NOCHECK If .I pattern does not match any path name, .CR glob() returns a list consisting of only .IR pattern , and the number of matched path names is 1. .TP .C GLOB_DOOFFS Make use of .IR pglob \|\(mi>\| gl_offs . If this flag is set, .IR pglob \|\(mi>\| gl_offs is used to specify how many NULL pointers to add to the beginning of .IR pglob \|\(mi>\| gl_pathv . In other words, .IR pglob \|\(mi>\| gl_pathv points to .IR pglob \|\(mi>\| gl_offs NULL pointers, followed by .IR pglob \|\(mi>\| gl_pathc path name pointers, followed by a NULL pointer. .TP .C GLOB_APPEND Append path names generated to the ones from a previous call to .CR glob() . .PP The .CR GLOB_APPEND flag can be used to append a new set of path names to those found in a previous call to .CR glob() . The following rules apply when two or more calls to .CR glob() are made with the same value of .I pglob and without intervening calls to .CR globfree() : .RS .TP 3 \(bu The first call must not set .CR GLOB_APPEND . All subsequent calls must set it. .TP \(bu All of the calls must set .CR GLOB_DOOFFS , or all must not set it. .TP \(bu After the second call, .IR pglob \|\(mi>\| gl_pathv points to a list containing the following: .RS .RS .TP 3 \(bu Zero or more NULL pointers, as specified by .CR GOB_DOOFFS and .IR pglob \|\(mi>\| gl_offs . .TP \(bu Pointers to the path names that were in the .IR pglob \|\(mi>\| gl_pathv list before the call, in the same order as before. .TP \(bu Pointers to the new path names generated by the second call, in the specified order. .RE .RE .TP 3 \(bu The count returned in .IR pglob \|\(mi>\| gl_pathc will be the total number of path names from the two calls. .TP \(bu The application can change any of the fields after a call to .CR glob() . If it does, it must reset them to the original value before a subsequent call, using the same .IR pglob value, to .CR globfree() or .CR glob() with the .CR GLOB_APPEND flag. .RE .RE .PP If, during the search, a directory is encountered that cannot be opened or read and .I errfunc is not NULL, .CR glob() calls .RI ( \(**errfunc )(\|) with two arguments: .RS .TP 3 \(bu A pointer to the path that failed. .TP \(bu The value of .CR errno from the failure. .RE .PP If .I errfunc is called and returns nonzero, or if the .CR GLOB_ERR flag is set in .IR flags , .CR glob() stops the scan and returns .CR GLOB_ABORTED after setting .CR gl_pathc and .CR gl_pathv in .I pglob to reflect the paths already scanned. If .CR GLOB_ERR is not set and either .I errfunc is NULL or .RI ( \(**errfunc )(\|) returns zero, the error is ignored. .SS Pattern Matching Notation The form of the patterns is the Pattern Matching Notation as qualified for Filename Expansion (see .IR regexp (5)) with the following exceptions: .RS .TP 3 \(bu Tilde .RC ( ~ ) expansion is not performed. .TP \(bu Variable expansion is not performed. .RE .PP .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions, and also the order of the returned paths if .CR GLOB_NOSORT is not selected. .PP The .CR LC_CTYPE category determines the interpretation of text as single byte and/or multibyte characters, and determines which characters are matched by character class expressions in regular expressions. .SS International Code Set Support Single byte and multibyte character code sets are supported. .SH RETURN VALUE If .CR glob() terminates due to an error, it returns one of the following constants (defined in .CR ); otherwise, it returns zero. .RS .TP 20 .C GLOB_NOSPACE An attempt to allocate memory failed. .TP .C GLOB_ABORTED The scan was stopped because .CR GLOB_ERR was set or .RI ( \(**errfunc )(\|) returned nonzero. .TP .C GLOB_NOMATCH The .I pattern does not match any existing path name, and .CR GLOB_NOCHECK was not set in .IR flags . .RE .PP In any case, the argument .IR pglob \|\(mi>\| gl_pathc returns the number of matched path names and the argument .IR pglob \|\(mi>\| gl_pathv contains a pointer to a null-terminated list of matched and sorted path names. .PP However, if .IR pglob \|\(mi>\| gl_pathc is zero, the content of .IR pglob \|\(mi>\| gl_pathv is undefined. .PP If the .I pattern argument passed to .CR glob() is badly constructed, .CR glob() returns zero and sets .CR gl_pathc to zero unless .CR GLOB_NOCHECK was set, in which case .I pattern is returned and .CR gl_pathc is set to 1. .SH WARNINGS .CR GLOB_APPEND must not be set in an initial call to .CR glob() . .SH AUTHOR .CR glob() and .CR globfree() were developed by OSF and HP. .SH SEE ALSO sh(1), fnmatch(3C), regexp(5). .SH STANDARDS CONFORMANCE .CR glob() ": XPG4, POSIX.2" .PP .CR globfree() ": XPG4, POSIX.2" .\" .\" index@\f4glob()\f1 \- file name generation function@@@\f3glob(3C)\f1 .\" index@\f4globfree()\f1 \- free space associated with file name generation function@@@\f3glob(3C)\f1 .\" index@\f1file name generation function@@@\f3glob(3C)\f1 .\" index@\f1generate file names@@@\f3glob(3C)\f1 .\" index@\f1create file names@@@\f3glob(3C)\f1 .\" .\" toc@\f3glob(3C)\f1:\0\0\f4glob()\f1, \f4globfree()\f1@@@file name generation function\f1 .\" toc@\f4globfree()\f1:\0\0free space associated with file name generation function@@@\f1see \f3glob(3C)\f1 .\" .\" links@glob.3c globfree.3c .\" $Header: ctime.3c,v 76.1 95/07/05 17:27:14 ssa Exp $ .TA c .TH ctime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctime(\|), ctime_r(\|), localtime(\|), localtime_r(\|), gmtime(\|), gmtime_r(\|), mktime(\|), difftime(\|), asctime(\|), asctime_r(\|), timezone(\|), daylight(\|), tzname(\|), tzset(\|) \- convert date and time to string .SH SYNOPSIS .nf .C "#include " .PP .C "char *asctime(const struct tm *timeptr);" .PP .C "int asctime_r(const struct tm *timeptr, char *buffer, int buflen);" .PP .C "char *ctime(const time_t *timer);" .PP .C "int ctime_r(const time_t *timer, char *buffer, int buflen);" .PP .C "double difftime(time_t time1, time_t time0);" .PP .C "struct tm *gmtime(const time_t *timer);" .PP .C "int gmtime_r(const time_t *timer, struct tm *result);" .PP .C "struct tm *localtime(const time_t *timer);" .PP .C "int localtime_r(const time_t *timer, struct tm *result);" .PP .C "time_t mktime(struct tm *timeptr);" .PP .C "extern long timezone;" .PP .C "extern int daylight;" .PP .C "extern char *tzname[2];" .PP .C "void tzset(void);" .fi .SH DESCRIPTION .TP 18 .C asctime() Convert the broken-down time contained in the structure pointed to by .I timeptr and return a pointer to a 26-character string in the form: .RS .IP .C "Sun Sep 16 01:03:52 1973\en\e0" .RE .IP All the fields have constant width. .TP .C asctime_r() is identical to .CR asctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C ctime() Convert the calendar time pointed to by .IR timer , representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: .RS .IP .C asctime(localtime(timer)) .RE .TP .C ctime_r() is identical to .CR ctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C gmtime() Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. .C gmtime() returns a pointer to the .C tm structure described below. .TP .C gmtime_r() is identical to .CR gmtime() , except that .C gmtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C localtime() Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA\c), according to the contents of the TZ environment variable (see Environment Variables below). .C localtime() returns a pointer to the .C tm structure described below. .TP .C localtime_r() is identical to .CR localtime() , except that .C localtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C difftime() Return the difference in seconds between two calendar times: .IR "time1 \(mi time0" . .TP .C mktime() Convert the broken-down time (expressed as local time) in the structure pointed to by .I timeptr into a calendar time value with the same encoding as that of the values returned by .IR time (2). The original values of the .C tm_wday and .C tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below. .IP A positive or zero value for .C tm_isdst causes .C mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for .C tm_isdst causes .C mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time. .IP Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of .C tm_mday is not set until .C tm_mon and .C tm_year are determined. .C mktime() returns the specified calendar time encoded as a value of type .CR time_t . .IP If the calendar time cannot be represented, the function returns the value .RC ( time_t )\|\(em\|1 and sets .C errno to .CR ERANGE . Note the value .RC ( time_t )\|\(em\|1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and .C errno to reliably detect an error condition. .TP .C tzset() Sets the values of the external variables .IR timezone , .IR daylight , and .I tzname according to the contents of the .C TZ environment variable (independent of any time value). The functions .CR localtime() , .CR mktime() , .CR ctime() , .CR asctime() , and .C strftime() (see .IR strftime (3C)) call .C tzset() and use the values returned in the external variables described below for their operations. .C tzset() can also be called directly by the user. .PP The .RC < time.h > header file contains declarations of all relevant functions and externals. It also contains the .C tm structure, which includes the following members: .RS .PP .nf .ift .ft 4 .ps +1 int tm_sec; /* seconds after the minute - [0,61] */ int tm_min; /* minutes after the hour - [0,59] */ int tm_hour; /* hours - [0,23] */ int tm_mday; /* day of month - [1,31] */ int tm_mon; /* month of year - [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday - [0,6] */ int tm_yday; /* days since January 1 - [0,365] */ int tm_isdst; /* daylight savings time flag */ .ift .ft .ps .fi .PP The value of .C tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available. .RE .PP The external variable .C timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), .C timezone is 5\(**60\(**60). The external variable .C daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable .C tzname[2] contains the local standard and local summer time zone abbreviations as specified by the .C TZ environment variable. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .SS Environment Variables The .C tzset() function uses the contents of .C TZ to set the values of the external variables .CR timezone , .C daylight , and .CR tzname . .C TZ also determines the time zone name substituted for the .C %Z and .C %z directives and the time zone adjustments performed by .CR localtime() , .CR mktime() , and .CR ctime() . Two methods for specifying a time zone within .C TZ are described in .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH "RETURN VALUE" .PP For .C asctime_r() and .C ctime_r(), if the buffer is of insufficient length, -1 is returned. For .C asctime_r(), ctime_r(), gmtime_r(), and .C localtime_r(), if the operation is successful, 0 is returned. .SH WARNINGS The return values for .CR asctime() , .CR ctime() , .CR gmtime() , and .CR localtime() point to static data whose contents is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() are MT-Safe and should be used instead. .PP Users of .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .PP The range of .C tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by .IR time (2) and passed as the .I timer argument does not include accumulated leap seconds. The .C tm structure generated by .C localtime() and .C gmtime() will never reflect any leap seconds. Upon successful completion, .C mktime() forces the value of the .C tm_sec component to the range [0,59]. .PP .CR ctime() , .CR ctime_r() , .CR asctime() , and .CR asctime_r() are considered obsolescent and may be removed in a future release. Use of .IR strftime (3C) is recommended instead. .SH AUTHOR .C ctime() was developed by AT&T and HP. .SH SEE ALSO time(2), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR ctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR asctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR daylight ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR difftime() ": AES, SVID3, XPG4, ANSI C" .PP .CR gmtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR localtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mktime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR timezone ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR tzname ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tzset() ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4asctime()\fP, \f4asctime_r()\f1 \- convert \f3tm\f1 structure date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4ctime()\fP, \f4ctime_r()\f1 \- convert \f4clock()\fP date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4daylight()\fP \- Daylight Savings Time flag@@@\f3ctime(3C)\f1 .\" index@\f4gmtime()\fP, \f4gmtime_r()\fP \- convert date and time to Greenwich Mean Time@@@\f3ctime(3C)\f1 .\" index@\f4localtime()\fP, \f4localtime_r()\fP \- convert date and time to local timezone@@@\f3ctime(3C)\f1 .\" index@\f4timezone()\fP \- difference between \s-1UCT\s+1 and local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzname()\fP \- name of local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzset()\fP \- initialize \f4timezone()\fP, \f4daylight()\fP, and \f4tzname()\fP using \s-1TZ\s+1 variable@@@\f3ctime(3C)\f1 .\" index@\f4mktime()\fP \- convert time into calendar time value@@@\f3ctime(3C)\f1 .\" index@\f4difftime()\fP \- difference between two calendar time values@@@\f3ctime(3C)\f1 .\" index@convert date and time to string@@@\f3ctime(3C)\f1 .\" index@string, convert date and time to@@@\f3ctime(3C)\f1 .\" index@date and time, convert to string@@@\f3ctime(3C)\f1 .\" index@time and date, convert to string@@@\f3ctime(3C)\f1 .\" .\" toc@\f3ctime(3C)\f1:\0\0\f4ctime()\fP, \f4ctime_r()\fP, \f4localtime()\fP, \f4localtime_r()\fP, \f4difftime()\f1, \f4 mktime()\f1, \n\f4gmtime()\fP, \f4gmtime_r()\fP,\f4asctime()\fP, \f4asctime_r()\fP, \f4timezone()\fP, \f4daylight()\fP, \f4tzname()\fP,\n\f4tzset()\f1@@@convert date and time to string .\" toc@\f4ctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4ctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4timezone()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4daylight()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzname()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzset()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4difftime()\fP:\0\0difference between calendar times@@@see \f3ctime(3C)\f1 .\" toc@\f4mktime()\fP:\0\0create calendar time value@@@see \f3ctime(3C)\f1 .\" .\" links@ctime.3c ctime_r.3c .\" links@ctime.3c localtime.3c .\" links@ctime.3c localtime_r.3c .\" links@ctime.3c gmtime.3c .\" links@ctime.3c gmtime_r.3c .\" links@ctime.3c asctime.3c .\" links@ctime.3c asctime_r.3c .\" links@ctime.3c timezone.3c .\" links@ctime.3c daylight.3c .\" links@ctime.3c tzname.3c .\" links@ctime.3c tzset.3c .\" links@ctime.3c difftime.3c .\" links@ctime.3c mktime.3c .\" .\" fileset_database@ctime.3c PROGRAMING-MAN .\" $Header: ctime.3c,v 76.1 95/07/05 17:27:14 ssa Exp $ .TA c .TH ctime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctime(\|), ctime_r(\|), localtime(\|), localtime_r(\|), gmtime(\|), gmtime_r(\|), mktime(\|), difftime(\|), asctime(\|), asctime_r(\|), timezone(\|), daylight(\|), tzname(\|), tzset(\|) \- convert date and time to string .SH SYNOPSIS .nf .C "#include " .PP .C "char *asctime(const struct tm *timeptr);" .PP .C "int asctime_r(const struct tm *timeptr, char *buffer, int buflen);" .PP .C "char *ctime(const time_t *timer);" .PP .C "int ctime_r(const time_t *timer, char *buffer, int buflen);" .PP .C "double difftime(time_t time1, time_t time0);" .PP .C "struct tm *gmtime(const time_t *timer);" .PP .C "int gmtime_r(const time_t *timer, struct tm *result);" .PP .C "struct tm *localtime(const time_t *timer);" .PP .C "int localtime_r(const time_t *timer, struct tm *result);" .PP .C "time_t mktime(struct tm *timeptr);" .PP .C "extern long timezone;" .PP .C "extern int daylight;" .PP .C "extern char *tzname[2];" .PP .C "void tzset(void);" .fi .SH DESCRIPTION .TP 18 .C asctime() Convert the broken-down time contained in the structure pointed to by .I timeptr and return a pointer to a 26-character string in the form: .RS .IP .C "Sun Sep 16 01:03:52 1973\en\e0" .RE .IP All the fields have constant width. .TP .C asctime_r() is identical to .CR asctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C ctime() Convert the calendar time pointed to by .IR timer , representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: .RS .IP .C asctime(localtime(timer)) .RE .TP .C ctime_r() is identical to .CR ctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C gmtime() Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. .C gmtime() returns a pointer to the .C tm structure described below. .TP .C gmtime_r() is identical to .CR gmtime() , except that .C gmtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C localtime() Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA\c), according to the contents of the TZ environment variable (see Environment Variables below). .C localtime() returns a pointer to the .C tm structure described below. .TP .C localtime_r() is identical to .CR localtime() , except that .C localtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C difftime() Return the difference in seconds between two calendar times: .IR "time1 \(mi time0" . .TP .C mktime() Convert the broken-down time (expressed as local time) in the structure pointed to by .I timeptr into a calendar time value with the same encoding as that of the values returned by .IR time (2). The original values of the .C tm_wday and .C tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below. .IP A positive or zero value for .C tm_isdst causes .C mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for .C tm_isdst causes .C mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time. .IP Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of .C tm_mday is not set until .C tm_mon and .C tm_year are determined. .C mktime() returns the specified calendar time encoded as a value of type .CR time_t . .IP If the calendar time cannot be represented, the function returns the value .RC ( time_t )\|\(em\|1 and sets .C errno to .CR ERANGE . Note the value .RC ( time_t )\|\(em\|1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and .C errno to reliably detect an error condition. .TP .C tzset() Sets the values of the external variables .IR timezone , .IR daylight , and .I tzname according to the contents of the .C TZ environment variable (independent of any time value). The functions .CR localtime() , .CR mktime() , .CR ctime() , .CR asctime() , and .C strftime() (see .IR strftime (3C)) call .C tzset() and use the values returned in the external variables described below for their operations. .C tzset() can also be called directly by the user. .PP The .RC < time.h > header file contains declarations of all relevant functions and externals. It also contains the .C tm structure, which includes the following members: .RS .PP .nf .ift .ft 4 .ps +1 int tm_sec; /* seconds after the minute - [0,61] */ int tm_min; /* minutes after the hour - [0,59] */ int tm_hour; /* hours - [0,23] */ int tm_mday; /* day of month - [1,31] */ int tm_mon; /* month of year - [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday - [0,6] */ int tm_yday; /* days since January 1 - [0,365] */ int tm_isdst; /* daylight savings time flag */ .ift .ft .ps .fi .PP The value of .C tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available. .RE .PP The external variable .C timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), .C timezone is 5\(**60\(**60). The external variable .C daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable .C tzname[2] contains the local standard and local summer time zone abbreviations as specified by the .C TZ environment variable. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .SS Environment Variables The .C tzset() function uses the contents of .C TZ to set the values of the external variables .CR timezone , .C daylight , and .CR tzname . .C TZ also determines the time zone name substituted for the .C %Z and .C %z directives and the time zone adjustments performed by .CR localtime() , .CR mktime() , and .CR ctime() . Two methods for specifying a time zone within .C TZ are described in .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH "RETURN VALUE" .PP For .C asctime_r() and .C ctime_r(), if the buffer is of insufficient length, -1 is returned. For .C asctime_r(), ctime_r(), gmtime_r(), and .C localtime_r(), if the operation is successful, 0 is returned. .SH WARNINGS The return values for .CR asctime() , .CR ctime() , .CR gmtime() , and .CR localtime() point to static data whose contents is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() are MT-Safe and should be used instead. .PP Users of .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .PP The range of .C tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by .IR time (2) and passed as the .I timer argument does not include accumulated leap seconds. The .C tm structure generated by .C localtime() and .C gmtime() will never reflect any leap seconds. Upon successful completion, .C mktime() forces the value of the .C tm_sec component to the range [0,59]. .PP .CR ctime() , .CR ctime_r() , .CR asctime() , and .CR asctime_r() are considered obsolescent and may be removed in a future release. Use of .IR strftime (3C) is recommended instead. .SH AUTHOR .C ctime() was developed by AT&T and HP. .SH SEE ALSO time(2), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR ctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR asctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR daylight ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR difftime() ": AES, SVID3, XPG4, ANSI C" .PP .CR gmtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR localtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mktime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR timezone ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR tzname ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tzset() ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4asctime()\fP, \f4asctime_r()\f1 \- convert \f3tm\f1 structure date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4ctime()\fP, \f4ctime_r()\f1 \- convert \f4clock()\fP date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4daylight()\fP \- Daylight Savings Time flag@@@\f3ctime(3C)\f1 .\" index@\f4gmtime()\fP, \f4gmtime_r()\fP \- convert date and time to Greenwich Mean Time@@@\f3ctime(3C)\f1 .\" index@\f4localtime()\fP, \f4localtime_r()\fP \- convert date and time to local timezone@@@\f3ctime(3C)\f1 .\" index@\f4timezone()\fP \- difference between \s-1UCT\s+1 and local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzname()\fP \- name of local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzset()\fP \- initialize \f4timezone()\fP, \f4daylight()\fP, and \f4tzname()\fP using \s-1TZ\s+1 variable@@@\f3ctime(3C)\f1 .\" index@\f4mktime()\fP \- convert time into calendar time value@@@\f3ctime(3C)\f1 .\" index@\f4difftime()\fP \- difference between two calendar time values@@@\f3ctime(3C)\f1 .\" index@convert date and time to string@@@\f3ctime(3C)\f1 .\" index@string, convert date and time to@@@\f3ctime(3C)\f1 .\" index@date and time, convert to string@@@\f3ctime(3C)\f1 .\" index@time and date, convert to string@@@\f3ctime(3C)\f1 .\" .\" toc@\f3ctime(3C)\f1:\0\0\f4ctime()\fP, \f4ctime_r()\fP, \f4localtime()\fP, \f4localtime_r()\fP, \f4difftime()\f1, \f4 mktime()\f1, \n\f4gmtime()\fP, \f4gmtime_r()\fP,\f4asctime()\fP, \f4asctime_r()\fP, \f4timezone()\fP, \f4daylight()\fP, \f4tzname()\fP,\n\f4tzset()\f1@@@convert date and time to string .\" toc@\f4ctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4ctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4timezone()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4daylight()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzname()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzset()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4difftime()\fP:\0\0difference between calendar times@@@see \f3ctime(3C)\f1 .\" toc@\f4mktime()\fP:\0\0create calendar time value@@@see \f3ctime(3C)\f1 .\" .\" links@ctime.3c ctime_r.3c .\" links@ctime.3c localtime.3c .\" links@ctime.3c localtime_r.3c .\" links@ctime.3c gmtime.3c .\" links@ctime.3c gmtime_r.3c .\" links@ctime.3c asctime.3c .\" links@ctime.3c asctime_r.3c .\" links@ctime.3c timezone.3c .\" links@ctime.3c daylight.3c .\" links@ctime.3c tzname.3c .\" links@ctime.3c tzset.3c .\" links@ctime.3c difftime.3c .\" links@ctime.3c mktime.3c .\" .\" fileset_database@ctime.3c PROGRAMING-MAN .\" $Header: gpio_get_st.3i,v 74.2 95/05/10 21:36:58 ssa Exp $ .TA g .TH gpio_get_status 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME gpio_get_status \- return status lines of GPIO card .SH SYNOPSIS .C "#include " .PP .C "int gpio_get_status(int eid);" .SH DESCRIPTION .C gpio_get_status() reads the status register of the .SM GPIO interface associated with the device file identified by .IR eid . .I eid is an entity identifier of an open .SM GPIO device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .C creat() call (see .IR open (2), .IR dup (2), .IR fcntl (2), or .IR creat (2)). The current state of each status line on the interface card is mapped to the value returned, with .C STS0 mapped to the least significant bit. Only .I x least-significant bits are used, where .I x is the number of status lines available on the hardware interface being used. .SH DEPENDENCIES .SS Series 300/400 For the HP\|98622A, .I x is 2. .SS Series 800 For the HP\|27114A, .I x is 2. .PP For the HP\|27114B, .I x is 6. .PP For the HP\|28651A, .I x is 5. .SH RETURN VALUE .C gpio_get_status() returns the value of the status register of the .SM GPIO interface associated with .IR eid , and \-1 if an error was encountered. .SH ERRORS .C gpio_get_status() fails if any of the following conditions are encountered and sets .C errno accordingly: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to a .SM GPIO device file. .RE .\" index@\f4gpio_get_status\f1 \- return status lines of \s-1GPIO\s+1 card@@@\f3gpio_get_status(3I)\f1 .\" index@interface, \s-1GPIO\s+1: return status lines of \s-1GPIO\s+1 card@@@\f3gpio_get_status(3I)\f1 .\" index@status lines of \s-1GPIO\s+1 card, return@@@\f3gpio_get_status(3I)\f1 .\" index@lines of \s-1GPIO\s+1 card, return status@@@\f3gpio_get_status(3I)\f1 .\" index@\s-1GPIO\s+1: return status lines of \s-1GPIO\s+1 card@@@\f3gpio_get_status(3I)\f1 .\" index@\s-1I/O\s+1: \s-1GPIO\s+1 card, return status lines of@@@\f3gpio_get_status(3I)\f1 .\" .\" toc@\f3gpio_get_status(3I)\f1:\0\0\f4gpio_get_status\f1@@@return status lines of \s-1GPIO\s+1 card .\" .\" fileset_database@gpio_get_st.3i PROGRAMING-MAN .\" $Header: gpio_set_ct.3i,v 74.1 95/05/10 21:40:23 ssa Exp $ .TA g .TH gpio_set_ctl 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME gpio_set_ctl \- set control lines on GPIO card .SH SYNOPSIS .C "#include " .PP .C "int gpio_set_ctl(int eid, int value);" .SH DESCRIPTION .C gpio_set_ctl() sets the control register of a .SM GPIO interface. .I eid is an entity identifier of an open .SM GPIO device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .C creat() call (see .IR open (2), .IR dup (2), .IR fcntl (2), and .IR creat (2)). .I value is the value to be written into the control register of the .SM GPIO interface associated with .IR eid . .PP .I value is mapped onto the control lines on the interface card, with the least significant bit mapped to .CR CTL0 . Only the .I x least significant bits are used, where .I x is the number of control lines available on the hardware interface being used. .SH DEPENDENCIES .SS Series 300/400 For the HP\|98622A, .I x is 2. .SS Series 800 For the HP\|27114A, .I x is 3. .PP For the HP\|27114B, .I x is 6. .PP For the HP\|28651A, .I x is 5. .SH RETURN VALUE .C gpio_set_ctl() returns 0 if successful and \-1 if an error was encountered. .SH ERRORS .C gpio_set_ctl() fails if any of the following conditions are encountered, and sets .C errno accordingly: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to a .SM GPIO device file. .RE .\" index@\f4gpio_set_ctl\f1 \- set control lines on \s-1GPIO\s+1 card@@@\f3gpio_set_ctl(3I)\f1 .\" index@interface, \s-1GPIO\s+1: set control lines on \s-1GPIO\s+1 card@@@\f3gpio_set_ctl(3I)\f1 .\" index@control lines on \s-1GPIO\s+1 card, set@@@\f3gpio_set_ctl(3I)\f1 .\" index@lines on \s-1GPIO\s+1 card, set control@@@\f3gpio_set_ctl(3I)\f1 .\" index@\s-1GPIO\s+1: set control lines on \s-1GPIO\s+1 card@@@\f3gpio_set_ctl(3I)\f1 .\" index@\s-1I/O\s+1: \s-1GPIO\s+1 card, set control lines on@@@\f3gpio_set_ctl(3I)\f1 .\" .\" toc@\f3gpio_set_ctl(3I)\f1:\0\0\f4gpio_set_ctl\f1@@@set control lines on \s-1GPIO\s+1 card .\" .\" fileset_database@gpio_set_ct.3i PROGRAMING-MAN .\" $Header: grantpt.3c,v 72.2 94/09/18 15:18:24 ssa Exp $ .TA g .TH grantpt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME grantpt \- grant access to the STREAMS slave pty .SH SYNOPSIS .C int grantpt (int fildes); .SH DESCRIPTION The passed parameter, .IR fildes , is a file descriptor that is returned from a successful open of a STREAMS master pty (pseudo-terminal) device. The .C grantpt() function modifies the ownership and mode of the slave pty device special file associated with its master pty counterpart. .PP A .C setuid() root program is spawned to change ownership and mode of the pty slave device file in the following way: The group ID is set to a reserved group named "tty". The slave user ID is set to the effective owner of the calling process. The permissions of the slave device are set so that the owner is allowed read and write access and the group is allowed write access. .SH RETURN VALUE Upon successful completion, the .C grantpt() function returns a value of 0 (zero). Otherwise, it returns a value of -1. .PP Failure may result under the following conditions: .RS .TP 3 \(bu The file descriptor specified by the .IR fildes parameter is not an open file descriptor. .TP \(bu The file descriptor specified by the .IR fildes parameter is not associated with a STREAMS master pty device. .TP \(bu The corresponding slave pty device cannot be accessed. .RE .SH WARNINGS The .C grantpt() function may also fail if the application has installed a signal handler to catch the SIGCHLD (death of a child) signal. .SH EXAMPLES The following example shows how .C grantpt() is typically used. .nf .IP .C int fd_master, fd_slave; .C char *slave; \h'.3i'.\|.\|. .IP " " 10 .C "fd_master = open(""/dev/ptmx"", O_RDWR);" .C "grantpt(fd_master);" .C "unlockpt(fd_master);" .C "slave = ptsname(fd_master);" .C "fd_slave = open(slave, O_RDWR);" .C "ioctl(fd_slave, I_PUSH, ""ptem"");" .C "ioctl(fd_slave, I_PUSH, ""ldterm"");" .fi .SH AUTHOR .C grantpt() was developed by HP and OSF. .SH SEE ALSO open(2), unlockpt(3C), ptsname(3C), ptm(7), pts(7), ptem(7), ldterm(7). .\" .\" index@\f4grantpt()\f1 \- grant access to STREAMS slave pty@@@\f3grantpt(3C)\f1 .\" index@\f1STREAMS slave pty, granting access to@@@\f3grantpt(3C)\f1 .\" index@\f1grant access to STREAMS slave pty@@@\f3grantpt(3C)\f1 .\" index@\f1slave pty, STREAMS, granting access@@@\f3grantpt(3C)\f1 .\" .\" toc@\f3grantpt(3C)\f1:\0\0\f4grantpt\f1@@@grant access to the STREAMS slave pty .\" .\" fileset_database@grantpt.3c STRTIO-MAN .\" $Header: ssignal.3c,v 72.4 94/11/15 09:56:23 ssa Exp $ .TA s .TH ssignal 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ssignal(\|), gsignal(\|) \- software signals .SH SYNOPSIS .C "#include " .PP .C "int (*ssignal(int sig, int (*action)(int)))(int);" .PP .C "int gsignal(int sig);" .SH DESCRIPTION .C ssignal() and .C gsignal() implement a software facility similar to .IR signal (5). This facility is used by the Standard C Library to enable users to indicate the disposition of error conditions, and is also made available to users for their own purposes. .PP Software signals made available to users are associated with integers in the inclusive range 1 through 15. A call to .C ssignal() associates a procedure, .IR action , with the software signal .IR sig ; the software signal, .IR sig , is raised by a call to .CR gsignal() . Raising a software signal causes the action established for that signal to be taken. .PP The first argument to .C ssignal() is a number identifying the type of signal for which an action is to be established. The second argument defines the action; it is either the name of a (user-defined) .I action function or one of the manifest constants .C SIG_DFL (default) or .C SIG_IGN (ignore). .C ssignal() returns the action previously established for that signal type; if no action has been established or the signal number is illegal, .C ssignal() returns .CR SIG_DFL . .PP .C gsignal() raises the signal identified by its argument, .IR sig : .RS .TP 3 \(bu If an action function has been established for .IR sig , that action is reset to .C SIG_DFL and the action function is entered with argument .IR sig . .C gsignal() returns the value returned to it by the action function. .TP \(bu If the action for .I sig is .CR SIG_IGN , .C gsignal() returns the value 1 and takes no other action. .TP \(bu If the action for .I sig is .CR SIG_DFL , .C gsignal() returns the value 0 and takes no other action. .TP \(bu If .I sig has an illegal value or no action was ever specified for .IR sig , .C gsignal() returns the value 0 and takes no other action. .RE .SH SEE ALSO signal(5). .SH NOTES Some additional signals with numbers outside the range 1 through 15 are used by the Standard C Library to indicate error conditions. Those signal numbers outside the range 1 through 15 are legal, although their use may interfere with the operation of the Standard C Library. .SH STANDARDS CONFORMANCE .CR ssignal() ": SVID2, SVID3, XPG2" .PP .CR gsignal() ": SVID2, SVID3, XPG2" .\" .\" index@\f4ssignal()\fP \- raise a software signal and perform an action@@@\f3ssignal(3C)\f1 .\" index@\f4gsignal()\fP \- raise a software signal@@@\f3ssignal(3C)\f1 .\" index@raise a software signal@@@\f3ssignal(3C)\f1 .\" index@software signal, raise a@@@\f3ssignal(3C)\f1 .\" index@signal, raise a software@@@\f3ssignal(3C)\f1 .\" .\" toc@\f3ssignal(3C)\f1:\0\0\f4ssignal()\fP, \f4gsignal()\fP@@@software signals .\" toc@\f4gsignal()\fP:\0\0software signals@@@see \f3ssignal(3C)\f1 .\" .\" links@ssignal.3c gsignal.3c .\" .\" fileset_database@ssignal.3c PROGRAMING-MAN .\" $Header: halfdelay.3x,v 76.2 95/08/01 11:04:33 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH halfdelay 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME halfdelay \(em control input character delay mode .SH SYNOPSIS .C "#include " .P .C "int halfdelay(int \f2tenths\fP);" .SH DESCRIPTION The .Fn halfdelay function sets the input mode for the current window to Half-Delay Mode and specifies \f2tenths\f1 tenths of seconds as the half-delay interval. The \f2tenths\f1 argument must be in a range from 1 up to and including 255. .SH "RETURN VALUE" Upon successful completion, .Fn halfdelay returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The application can call .Fn nocbreak to leave Half-Delay mode. .SH "SEE ALSO" \f3Input Mode\f1 in curses_intro, cbreak(), , \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Chapter 9,\f3General Terminal Interface\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4halfdelay()\f1 \- control input character delay mode@@@\f3halfdelay(3X)\f1 .\" index@\f1control input character delay mode@@@\f3halfdelay(3X)\f1 .\" index@\f1delay mode, control input character delay mode@@@\f3halfdelay(3X)\f1 .\" index@\f1input character, control delay mode@@@\f3halfdelay(3X)\f1 .\" .\" toc@\f3halfdelay(3X)\f1:\0\0\f4halfdelay()\f1@@@control input character delay mode .\" .\" fileset_database@halfdelay.3x CURS-ENG-A-MAN .\" $Header: can_change_color.3x,v 76.3 95/10/05 14:12:23 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH can_change_color 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME can_change_color, color_content, has_colors, init_color, init_pair, start_color, pair_content \(em color manipulation functions .SH SYNOPSIS .C "#include " .P .C "bool can_change_color(void);" .P .C "int color_content(short \f2color\fP, short *\f2red\fP, short *\f2green\fP, short *\f2blue\fP);" .P .C "int COLOR_PAIR(int \f2n\fP);" .P .C "bool has_colors(void);" .P .C "int init_color(short \f2color\fP, short \f2red\fP, short \f2green\fP, short \f2blue\fP);" .P .C "int init_pair(short \f2pair\fP, short \f2f\fP, short \f2b\fP);" .P .C "int pair_content(short \f2pair\fP, short *\f2f\fP, short *\f2b\fP);" .P .C "int PAIR_NUMBER(int \f2value\fP);" .P .C "int start_color(void);" .P .C "extern int COLOR_PAIRS;" .P .C "extern int COLORS;" .SH DESCRIPTION These functions manipulate colour on terminals that support colour. .SS "Querying Capabilities" The .Fn has_colors function indicates whether the terminal is a colour terminal. The .Fn can_change_color function indicates whether the terminal is a colour terminal on which colours can be redefined. .SS "Initialisation" The .Fn start_color function must be called in order to enable use of colours and before any colour manipulation function is called. The function initialises eight basic colours (black, blue, green, cyan, red, magenta, yellow, and white) that can be specified by the colour macros (such as COLOR_BLACK) defined in .CR . (See \f3Colour-related Macros\f1 in \f3\f1.) The initial appearance of these eight colours is not specified. .P The function also initialises two global external variables: .RS .TP 3 .C \(bu COLORS defines the number of colours that the terminal supports. (See .B "Colour Identification" below.) If COLORS is 0, the terminal does not support redefinition of colours (and .Fn can_change_colour will return FALSE). .TP .C \(bu COLOR_PAIRS defines the maximum number of colour-pairs that the terminal supports. (See .B "User-Defined Colour Pairs" below.) .RE .P The .Fn start_color function also restores the colours on the terminal to terminal-specific initial values. The initial background colour is assumed to be black for all terminals. .SS "Colour Identification" The .Fn init_color function redefines colour number \f2color\fP, on terminals that support the redefinition of colours, to have the red, green, and blue intensity components specified by \f2red\fP, \f2green\fP, and \f2blue\fP, respectively. Calling .Fn init_color also changes all occurrences of the specified colour on the screen to the new definition. .P The .Fn color_content function identifies the intensity components of colour number \f2color\f1. It stores the red, green, and blue intensity components of this colour in the addresses pointed to by \f2red\fP, \f2green\fP, and \f2blue\fP, respectively. .P For both functions, the .I color argument must be in the range from 0 to and including COLORS\|\(mi\|1. Valid intensity values range from 0 (no intensity component) up to and including 1000 (maximum intensity in that component). .SS "User-Defined Colour Pairs" Calling .Fn init_pair defines or redefines colour-pair number \f2pair\f1 to have foreground colour \f2f\f1 and background colour \f2b\f1. Calling .Fn init_pair changes any characters that were displayed in the colour pair's old definition to the new definition and refreshes the screen. .P After defining the colour pair, the macro COLOR_PAIR(\f2n\fP) returns the value of colour pair \f2n\f1. This value is the colour attribute as it would be extracted from a .CR chtype . Conversely, the macro PAIR_NUMBER(\f2value\fP) returns the colour pair number associated with the colour attribute \f2value\f1. .P The .Fn pair_content function retrieves the component colours of a colour-pair number \f2pair\f1. It stores the foreground and background colour numbers in the variables pointed to by \f2f\f1 and \f2b\fP, respectively. .P With .Fn init_pair and .Fn pair_content , the value of \f2pair\f1 must be in a range from 0 to and including COLOR_PAIRS\|\(mi\|1. (There may be an implementation-specific lower limit on the valid value of \f2pair\fP, but any such limit is at least 63.) Valid values for \f2f\f1 and \f2b\f1 are the range from 0 to and including COLORS\|\(mi\|1. .SH "RETURN VALUE" The .Fn has_colors function returns TRUE if the terminal can manipulate colors; otherwise, it returns FALSE. .P The .Fn can_change_color function returns TRUE if the terminal supports colors and can change their definitions; otherwise, it returns FALSE. .P Upon successful completion, the other functions return OK; otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" To use these functions, .Fn start_color must be called, usually right after .CR initscr() . .P The .Fn can_change_color and .Fn has_colors functions facilitate writing terminal-independent programs. For example, a programmer can use them to decide whether to use colour or some other video attribute. .P On color terminals, a typical value of COLORS is 8 and the macros such as COLOR_BLACK return a value within the range from 0 to and including 7. However, applications cannot rely on this to be true. .SH "SEE ALSO" attroff(), delscreen(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3can_change_color(3X)\f1:\0\0\f4can_change_color()\f1, \f4color_content()\f1, \f4has_colors()\f1, \f4init_color()\f1, \n\f4init_pair()\f1, \f4start_color()\f1, \f4pair_content()\f1@@@color manipulation functions .\" toc@\f4color_content()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4has_colors()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4init_colors()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4init_pair()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4start_color()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4pair_content()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" .\" index@\f4can_change_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4color_content()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4has_colors()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4init_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4init_pair()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4start_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4pair_content()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f1color manipulation functions@@@\f3can_change_color(3X)\f1 .\" .\" links@can_change_color.3x color_content.3x .\" links@can_change_color.3x has_colors.3x .\" links@can_change_color.3x init_color.3x .\" links@can_change_color.3x init_pair.3x .\" links@can_change_color.3x start_color.3x .\" links@can_change_color.3x pair_content.3x .\" .\" fileset_database@can_change_color.3x CURS-ENG-A-MAN .\" $Header: has_ic.3x,v 76.2 95/08/01 11:06:35 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH has_ic 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME has_ic, has_il \(em query functions for terminal insert and delete capability .SH SYNOPSIS .C "#include " .P .C "bool has_ic(void);" .P .C "bool has_il(void);" .SH DESCRIPTION The .Fn has_ic function indicates whether the terminal has insert- and delete-character capabilities. .P The .Fn has_il function indicates whether the terminal has insert- and delete-line capabilities, or can simulate them using scrolling regions. .SH "RETURN VALUE" The .Fn has_ic function returns TRUE if the terminal has insert- and delete-character capabilities. Otherwise, it returns FALSE. .P The .Fn has_il function returns TRUE if the terminal has insert- and delete-line capabilities. Otherwise, it returns FALSE. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn has_il function may be used to determine if it would be appropriate to turn on physical scrolling using .CR scrollok() . .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn has_il function is merged with this entry. In previous issues, it appeared in an entry of its own. .P The entry is rewritten for clarity. The argument list for the .Fn has_ic and .Fn has_il functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3has_ic(3X)\f1:\0\0\f4has_ic()\f1, \f4has_il()\f1@@@query functions for terminal insert and delay capability .\" toc@\f4has_il()\f1: query functions for terminal insert and delay capability@@@see \f3has_ic(3X)\f1 .\" .\" index@\f4has_ic()\f1 \- query functions for terminal insert and delay capability@@@\f3has_ic(3X)\f1 .\" index@\f4has_il()\f1 \- query functions for terminal insert and delay capability@@@\f3has_ic(3X)\f1 .\" index@\f1query functions for terminal insert and delay capability@@@\f3has_ic(3X)\f1 .\" index@\f1functions, query, for terminal insert and delay capability@@@\f3has_ic(3X)\f1 .\" index@\f1terminal insert and delay capability, query functions@@@\f3has_ic(3X)\f1 .\" index@\f1insert and delay capability, for terminal@@@\f3has_ic(3X)\f1 .\" index@\f1delay and insert capability, for terminal@@@\f3has_ic(3X)\f1 .\" .\" links@has_ic.3x has_il.3x .\" .\" fileset_database@has_ic.3x CURS-ENG-A-MAN .\" $Header: has_ic.3x,v 76.2 95/08/01 11:06:35 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH has_ic 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME has_ic, has_il \(em query functions for terminal insert and delete capability .SH SYNOPSIS .C "#include " .P .C "bool has_ic(void);" .P .C "bool has_il(void);" .SH DESCRIPTION The .Fn has_ic function indicates whether the terminal has insert- and delete-character capabilities. .P The .Fn has_il function indicates whether the terminal has insert- and delete-line capabilities, or can simulate them using scrolling regions. .SH "RETURN VALUE" The .Fn has_ic function returns TRUE if the terminal has insert- and delete-character capabilities. Otherwise, it returns FALSE. .P The .Fn has_il function returns TRUE if the terminal has insert- and delete-line capabilities. Otherwise, it returns FALSE. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn has_il function may be used to determine if it would be appropriate to turn on physical scrolling using .CR scrollok() . .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn has_il function is merged with this entry. In previous issues, it appeared in an entry of its own. .P The entry is rewritten for clarity. The argument list for the .Fn has_ic and .Fn has_il functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3has_ic(3X)\f1:\0\0\f4has_ic()\f1, \f4has_il()\f1@@@query functions for terminal insert and delay capability .\" toc@\f4has_il()\f1: query functions for terminal insert and delay capability@@@see \f3has_ic(3X)\f1 .\" .\" index@\f4has_ic()\f1 \- query functions for terminal insert and delay capability@@@\f3has_ic(3X)\f1 .\" index@\f4has_il()\f1 \- query functions for terminal insert and delay capability@@@\f3has_ic(3X)\f1 .\" index@\f1query functions for terminal insert and delay capability@@@\f3has_ic(3X)\f1 .\" index@\f1functions, query, for terminal insert and delay capability@@@\f3has_ic(3X)\f1 .\" index@\f1terminal insert and delay capability, query functions@@@\f3has_ic(3X)\f1 .\" index@\f1insert and delay capability, for terminal@@@\f3has_ic(3X)\f1 .\" index@\f1delay and insert capability, for terminal@@@\f3has_ic(3X)\f1 .\" .\" links@has_ic.3x has_il.3x .\" .\" fileset_database@has_ic.3x CURS-ENG-A-MAN .\" $Header: getmntent.3x,v 76.1 95/07/05 17:29:38 ssa Exp $ .TA g .TH getmntent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getmntent(\|), getmntent_r(\|), setmntent(\|), addmntent(\|), endmntent(\|), hasmntopt(\|) \- get file system descriptor file entry .SH SYNOPSIS .C "#include " .PP .C "\s-1FILE\s0 \(**setmntent(const char \(**path, char \(**type);" .PP .C "struct mntent \(**getmntent(\s-1FILE\s0 \(**stream);" .PP .C "int getmntent_r(" .nf .PD 0 .IP .C "\s-1FILE\s0 *stream," .C "struct mntent *result," .C "char *buffer," .C "int buflen);" .PD .PP .C "int addmntent(\s-1FILE\s0 \(**stream, struct mntent \(**mnt);" .PP .C "char \(**hasmntopt(struct mntent \(**mnt, const char \(**opt);" .PP .C "int endmntent(\s-1FILE\s0 \(**stream);" .SH DESCRIPTION These routines replace the obsolete .C getfsent() routines (see .IR getfsent (3X)) for accessing the file system description file .CR /etc/fstab . They are also used to access the mounted file system description file .CR /etc/mnttab . .TP 20 .C setmntent() Opens a file system description file and returns a file pointer which can then be used with .CR getmntent() , .CR addmntent() , or .CR endmntent() . The .I type argument is the same as in .IR fopen (3C). .TP .C getmntent() Reads the next line from .I stream and returns a pointer to an object with the following structure containing the broken-out fields of a line in the file-system description file, .RC < mntent.h >. The fields have meanings described in .IR fstab (4). .nf .IP .C struct mntent { .C " char *mnt_fsname; /* file system name */" .C " char *mnt_dir; /* file system path prefix */" .C " char *mnt_type; /* hfs, nfs, swap, or xx */" .C " char *mnt_opts; /* ro, suid, etc. */" .C " int mnt_freq; /* dump frequency, in days */" .C " int mnt_passno; /* pass number on parallel fsck */" .C " long mnt_time; /* When file system was mounted; */" .C " /* see mnttab(4). */" .C " /* (0 for NFS) */" .C }; .ft .ps .fi .IP .TP .C getmntent_r() Uses three extra parameters to provide results equivalent to those produced by .CR getmntent() . The extra parameters are: .PD 0 .IP 1. The address of a .C "struct mntent" where the result will be stored. .IP 2. A buffer to store character strings to which fields in the .C "struct mntent" will point. .IP 3. The length of the user-supplied buffer. A buffer length of 1025 is recommended. .PD .TP .C addmntent() Adds the .C mntent structure .I mnt to the end of the open file .IR stream . Note that .I stream must be opened for writing. .TP .C hasmntopt() Scans the .C mnt_opts field of the .C mntent structure .I mnt for a substring that matches .IR opt . It returns the address of the substring if a match is found; .C 0 otherwise. .TP .C endmntent() Closes the file. .PP The following definitions are provided in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNT_CHECKLIST "/etc/fstab" #define MNT_MNTTAB "/etc/mnttab" #define MNTMAXSTR 128 /* Max size string in mntent */ #define MNTTYPE_HFS "hfs" /* HFS file system */ #define MNTTYPE_CDFS "hfs" /* CD-ROM file system */ #define MNTTYPE_NFS "nfs" /* Network file system */ #define MNTTYPE_SWAP "swap" /* Swap device */ #define MNTTYPE_SWAPFS "swapfs" /* File system swap */ #define MNTTYPE_IGNORE "ignore" /* Ignore this entry */ #define MNTOPT_DEFAULTS "defaults" /* Use all default options */ #define MNTOPT_RO "ro" /* Read only */ #define MNTOPT_RW "rw" /* Read/write */ #define MNTOPT_SUID "suid" /* Set uid allowed */ #define MNTOPT_NOSUID "nosuid" /* No set uid allowed */ #define MNTOPT_QUOTA "quota" /* Enable disk quotas */ #define MNTOPT_NOQUOTA "noquota" /* Disable disk quotas */ .ft .ps .fi .RE .PP The following definition is provided for device swap in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_END "end" /* swap after end of file system, Series 300/400/700 only */ .ft .ps .fi .RE .PP The following definitions are provided for file system swap in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_MIN "min" /* minimum file system swap */ #define MNTOPT_LIM "lim" /* maximum file system swap */ #define MNTOPT_RES "res" /* reserve space for file system */ #define MNTOPT_PRI "pri" /* file system swap priority */ .ft .ps .RE .PP .SH NETWORKING FEATURES .SS NFS The following definitions are provided in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_BG "bg" /* Retry mount in background */ #define MNTOPT_FG "fg" /* Retry mount in foreground */ #define MNTOPT_RETRY "retry" /* Number of retries allowed */ #define MNTOPT_RSIZE "rsize" /* Read buffer size in bytes */ #define MNTOPT_WSIZE "wsize" /* Write buffer size in bytes*/ #define MNTOPT_TIMEO "timeo" /* Timeout in 1/10 seconds */ #define MNTOPT_RETRANS "retrans" /* Number of retransmissions */ #define MNTOPT_PORT "port" /* Server's IP NFS port */ #define MNTOPT_SOFT "soft" /* Soft mount */ #define MNTOPT_HARD "hard" /* Hard mount */ #define MNTOPT_INTR "intr" /* Interruptable hard mounts */ #define MNTOPT_NOINTR "nointr" /* Uninterruptable hard mounts*/ #define MNTOPT_DEVS "devs" /* Device file access allowed */ #define MNTOPT_NODEVS "nodevs" /* No device file access allowed */ .ft .ps .fi .TE .SH RETURN VALUE .TP 20 .C setmntent() Returns a null pointer on error. .TP .C getmntent() Returns a null pointer on error or EOF. Otherwise, .C getmntent() returns a pointer to a mntent structure. Some of the fields comprising a mntent structure are optional in .C /etc/fstab and .CR /etc/mnttab . In the supplied structure, such missing character pointer fields are set to NULL and missing integer fields are set to \(mi1 for .C mnt_freq and .C mnt_passno. If the integer field for .C mnt_time is missing, it is set to 0. .TP .C getmntent_r() Returns a .C -1 on error or EOF, or if the supplied buffer is of insufficient length. If the operation is successful, .C 0 is returned. .TP .C addmntent() Returns .C 1 on error. .TP .C endmntent() Returns .CR 1 . .SH WARNINGS The return value for .C getmntent() points to static information that is overwritten in each call. Thus, .C getmntent() is unsafe for multi-thread applications. .C getmntent_r() is MT-Safe and should be used instead. .SH AUTHOR .CR addmntent() , .CR endmntent() , .CR getmntent() , .CR hasmntopt() , and .C setmntent() were developed by The University of California, Berkeley, Sun Microsystems, Inc., and HP. .SH FILES .C /etc/fstab .br .C /etc/mnttab .SH SEE ALSO fstab(4), getfsent(3X), mnttab(4). .\" .\" index@\f4getmntent()\f1 \- get a file system description file entry@@@\f3getmntent(3X)\f1 .\" index@\f4setmntent()\f1 \- open a file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4addmntent()\f1 \- add entry to open file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4endmntent()\f1 \- close file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4hasmntopt()\f1 \- search mount option field in file system description file@@@\f3getmntent(3X)\f1 .\" index@file system description file entry@@@\f3getmntent(3X)\f1 .\" index@file entry get file system description@@@\f3getmntent(3X)\f1 .\" index@get file system description file@@@\f3getmntent(3X)\f1 .\" .\" toc@\f3getmntent(3X)\f1:\0\0\f4getmntent()\f1, \f4getmntent_r()\f1, \f4setmntent()\f1, \f4addmntent()\f1, \f4endmntent()\f1, \n\f4hasmntopt()\f1@@@get file system descriptor file entry .\" toc@\f4setmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4addmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4endmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4hasmntopt()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" .\" links@getmntent.3x getmntent_r.3x .\" links@getmntent.3x setmntent.3x .\" links@getmntent.3x addmntent.3x .\" links@getmntent.3x endmntent.3x .\" links@getmntent.3x hasmntopt.3x .\ .\" fileset_database@getmntent.3x PROGRAMING-MAN .\" $Header: rstat.3n,v 72.4 94/06/30 15:46:12 ssa Exp $ .TA r .TH rstat 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rstat(\|), havedisk(\|) \- get performance data from remote kernel .SH SYNOPSIS .C #include .br .C #include .PP .C "int havedisk(char *host);" .PP .C "int rstat(char *host, struct statstime *statp);" .SH DESCRIPTION .CR havedisk() returns .CR 1 if .I host has a disk, .CR 0 if it does not, and \(mi1 if this cannot be determined. The .I host string is either the official name of the host or an alias for it. See .IR hosts (4) for more information regarding host names. .PP .CR rstat() fills in the .I statstime structure for .IR host , and returns .CR 0 if it was successful. The relevant structures are: .PP .RS .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct stats { /* RSTATVERS_ORIG */ int cp_time[CPUSTATES]; /* the time spent in each CPU state */ int dk_xfer[DK_NDRIVE]; /* total number of disk transfers on each of the disk interfaces */ unsigned v_pgpgin; /* total VM pages paged in */ unsigned v_pgpgout; /* total VM pages paged out */ unsigned v_pswpin; /* total VM pages paged swapped in */ unsigned v_pswpout; /* total VM pages paged swapped out */ unsigned v_intr; /* total interrupts */ int if_ipackets; /* inbound packets on all interfaces */ int if_ierrors; /* inbound errors on all interfaces */ int if_opackets; /* outbound packets on all interfaces */ int if_oerrors; /* outbound errors on all interfaces */ int if_collisions; /* collisions seen on all interfaces */ }; .sp struct statsswtch { /* RSTATVERS_SWTCH */ int cp_time[CPUSTATES]; /* the time spent in each CPU state */ int dk_xfer[DK_NDRIVE]; /* total number of disk transfers on each of the disk interfaces */ unsigned v_pgpgin; /* total VM pages paged in */ unsigned v_pgpgout; /* total VM pages paged out */ unsigned v_pswpin; /* total VM pages paged swapped in */ unsigned v_pswpout; /* total VM pages paged swapped out */ unsigned v_intr; /* total interrupts */ int if_ipackets; /* inbound packets on all interfaces */ int if_ierrors; /* inbound errors on all interfaces */ int if_opackets; /* outbound packets on all interfaces */ int if_oerrors; /* outbound errors on all interfaces */ int if_collisions; /* collisions seen on all interfaces */ unsigned v_swtch; /* total context switches */ long avenrun[3]; /* average number of running jobs */ struct timeval boottime; /* time of last boot */ }; .sp struct statstime { /* RSTATVERS_TIME */ int cp_time[CPUSTATES]; /* the time spent in each CPU state */ int dk_xfer[DK_NDRIVE]; /* total number of disk transfers on each of the disk interfaces */ unsigned v_pgpgin; /* total VM pages paged in */ unsigned v_pgpgout; /* total VM pages paged out */ unsigned v_pswpin; /* total VM pages paged swapped in */ unsigned v_pswpout; /* total VM pages paged swapped out */ unsigned v_intr; /* total interrupts */ int if_ipackets; /* inbound packets on all interfaces */ int if_ierrors; /* inbound errors on all interfaces */ int if_opackets; /* outbound packets on all interfaces */ int if_oerrors; /* outbound errors on all interfaces */ int if_collisions; /* collisions seen on all interfaces */ unsigned v_swtch; /* total context switches */ long avenrun[3]; /* average number of running jobs */ struct timeval boottime; /* time of last boot */ struct timeval curtime; /* current system time */ }; .ft .ps .fi .RE .SS \s-1RPC\s0 Info .RS .nf program number: \s-1RSTATPROG\s+1 .PP xdr routines: int xdr_stats(xdrs, stat) \s-1XDR\s+1 *xdrs; struct stats *stat; int xdr_statsswtch(xdrs, stat) \s-1XDR\s+1 *xdrs; struct statsswtch *stat; int xdr_statstime(xdrs, stat) \s-1XDR\s+1 *xdrs; struct statstime *stat; int xdr_timeval(xdrs, tv) \s-1XDR\s+1 *xdrs; struct timeval *tv; .PP procs: \s-1RSTATPROC_HAVEDISK\s+1 Takes no arguments, returns \f2long\fP which is true if remote host has a disk. \s-1RSTATPROC_STATS\s+1 Takes no arguments, return \f2struct statsxxx\fP, depending on version. versions: \s-1RSTATVERS_ORIG\s+1 \s-1RSTATVERS_SWTCH\s+1 \s-1RSTATVERS_TIME\s+1 .fi .RE .SH WARNINGS User applications that call this routine must be linked with .CR /usr/lib/librpcsvc.a . For example, .IP .C cc my_source.c -lrpcsvc .SH AUTHOR .CR rstat() was developed by Sun Microsystems, Inc. .SH SEE ALSO rup(1), rstatd(1M). .\" .\" index@\f4rstat()\fP \- get performance data from remote kernel@@@\f3rstat(3N)\f1 .\" index@\f4havedisk()\fP \- get performance data from remote kernel@@@\f3rstat(3N)\f1 .\" index@performance data from remote kernel, get@@@\f3rstat(3N)\f1 .\" index@remote kernel, get performance data from@@@\f3rstat(3N)\f1 .\" index@kernel, remote, get performance data from@@@\f3rstat(3N)\f1 .\" .\" toc@\f3rstat(3N)\f1: \f4rstat()\fP, \f4havedisk()\fP@@@get performance data from remote kernel .\" .\" links@rstat.3n havedisk.3n .\" $Header: hsearch.3c,v 74.1 95/03/23 18:01:43 ssa Exp $ .TA h .TH hsearch 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hsearch(\|), hcreate(\|), hdestroy(\|) \- manage hash search tables .SH SYNOPSIS .C "#include " .PP .C "ENTRY *hsearch(ENTRY item, ACTION action);" .PP .C "int hcreate(unsigned nel);" .PP .C "void hdestroy(void);" .SH DESCRIPTION .C hsearch() is a hash-table search routine generalized from Knuth (6.4) Algorithm D. It returns a pointer into a hash table indicating the location at which an entry can be found. Only pointers are copied, so the calling routine must store the data (the value of the "key" must be unique). .I item is a structure of type .C ENTRY (defined in the .RC < search.h > header file) containing two pointers: .C item.key points to the comparison key, and .C item.data points to any other data to be associated with that key. (Pointers to types other than character should be cast to pointer-to-character.) .I action is a member of an enumeration type .C ACTION indicating the disposition of the entry if it cannot be found in the table. .C ENTER indicates that the item should be inserted in the table at an appropriate point. .C FIND indicates that no entry should be made. Unsuccessful resolution is indicated by the return of a .SM NULL pointer. .PP .C hcreate() allocates sufficient space for the table, and must be called before .C hsearch() is used. .I nel is an estimate of the maximum number of entries that the table will contain. This number can be adjusted upward by the algorithm in order to obtain certain mathematically favorable circumstances. .PP .C hdestroy() destroys the search table, and can be followed by another call to .CR hcreate() . .SH EXAMPLE The following example reads in strings followed by two numbers and stores them in a hash table, discarding duplicates. It then reads in strings and finds the matching entry in the hash table and prints it out. .PP .RS .nf .ift .ft 4 .ps +1 #include #include struct info { /* this is the info stored in the table */ int age, room; /* other than the key. */ }; #define NUM_EMPL 5000 /* # of elements in search table */ main( ) { /* space to store strings */ char string_space[NUM_EMPL*20]; /* space to store employee info */ struct info info_space[NUM_EMPL]; /* next avail space in string_space */ char *str_ptr = string_space; /* next avail space in info_space */ struct info *info_ptr = info_space; ENTRY item, *found_item, *hsearch( ); /* name to look for in table */ char name_to_find[30]; int i = 0; /* create table */ (void) hcreate(NUM_EMPL); while (scanf("%s%d%d", str_ptr, &info_ptr->age, &info_ptr->room) != EOF && i++ < NUM_EMPL) { /* put info in structure, and structure in item */ item.key = str_ptr; item.data = (char *)info_ptr; str_ptr += strlen(str_ptr) + 1; info_ptr++; /* put item into table */ (void) hsearch(item, ENTER); } /* access table */ item.key = name_to_find; while (scanf("%s", item.key) != EOF) { if ((found_item = hsearch(item, FIND)) != NULL) { /* if item is in the table */ (void)printf("found %s, age = %d, room = %d\en", found_item->key, ((struct info *)found_item->data)->age, ((struct info *)found_item->data)->room); } else { (void)printf("no such employee %s\en", name_to_find); } } } .ft .ps .fi .SH RETURN VALUE .C hsearch() returns a .SM NULL pointer if either the action is .SM .C FIND and the item could not be found or the action is .SM .C ENTER and the table is full. .PP .C hcreate() returns zero if it cannot allocate sufficient space for the table. .SH WARNINGS .C hsearch() and .C hcreate() use .C malloc() to allocate space (see .IR malloc (3C)). .PP Only one hash search table can be active at any given time. .PP .C hcreate() and .C hdestroy() are unsafe in multi-thread applications. .SH SEE ALSO bsearch(3C), lsearch(3C), malloc(3C), string(3C), tsearch(3C). .SH STANDARDS CONFORMANCE .CR hsearch() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR hcreate() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR hdestroy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4hcreate()\fP \- allocate space for new hash search table@@@\f3hsearch(3C)\f1 .\" index@\f4hsearch()\fP \- hash table search routine@@@\f3hsearch(3C)\f1 .\" index@\f4hdestroy()\fP \- destroy existing hash search table@@@\f3hsearch(3C)\f1 .\" index@manage hash search tables@@@\f3hsearch(3C)\f1 .\" index@hash search tables, manage@@@\f3hsearch(3C)\f1 .\" index@search tables, hash, manage@@@\f3hsearch(3C)\f1 .\" index@tables, hash search, manage@@@\f3hsearch(3C)\f1 .\" .\" toc@\f3hsearch(3C)\f1:\0\0\f4hsearch()\fP, \f4hcreate()\fP, \f4hdestroy()\fP@@@manage hash search tables .\" toc@\f4hcreate()\fP:\0\0manage hash search tables@@@see \f3hsearch(3C)\f1 .\" toc@\f4hdestroy()\fP:\0\0manage hash search tables@@@see \f3hsearch(3C)\f1 .\" .\" links@hsearch.3c hcreate.3c .\" links@hsearch.3c hdestroy.3c .\" .\" fileset_database@hsearch.3c PROGRAMING-MAN .\" $Header: hsearch.3c,v 74.1 95/03/23 18:01:43 ssa Exp $ .TA h .TH hsearch 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hsearch(\|), hcreate(\|), hdestroy(\|) \- manage hash search tables .SH SYNOPSIS .C "#include " .PP .C "ENTRY *hsearch(ENTRY item, ACTION action);" .PP .C "int hcreate(unsigned nel);" .PP .C "void hdestroy(void);" .SH DESCRIPTION .C hsearch() is a hash-table search routine generalized from Knuth (6.4) Algorithm D. It returns a pointer into a hash table indicating the location at which an entry can be found. Only pointers are copied, so the calling routine must store the data (the value of the "key" must be unique). .I item is a structure of type .C ENTRY (defined in the .RC < search.h > header file) containing two pointers: .C item.key points to the comparison key, and .C item.data points to any other data to be associated with that key. (Pointers to types other than character should be cast to pointer-to-character.) .I action is a member of an enumeration type .C ACTION indicating the disposition of the entry if it cannot be found in the table. .C ENTER indicates that the item should be inserted in the table at an appropriate point. .C FIND indicates that no entry should be made. Unsuccessful resolution is indicated by the return of a .SM NULL pointer. .PP .C hcreate() allocates sufficient space for the table, and must be called before .C hsearch() is used. .I nel is an estimate of the maximum number of entries that the table will contain. This number can be adjusted upward by the algorithm in order to obtain certain mathematically favorable circumstances. .PP .C hdestroy() destroys the search table, and can be followed by another call to .CR hcreate() . .SH EXAMPLE The following example reads in strings followed by two numbers and stores them in a hash table, discarding duplicates. It then reads in strings and finds the matching entry in the hash table and prints it out. .PP .RS .nf .ift .ft 4 .ps +1 #include #include struct info { /* this is the info stored in the table */ int age, room; /* other than the key. */ }; #define NUM_EMPL 5000 /* # of elements in search table */ main( ) { /* space to store strings */ char string_space[NUM_EMPL*20]; /* space to store employee info */ struct info info_space[NUM_EMPL]; /* next avail space in string_space */ char *str_ptr = string_space; /* next avail space in info_space */ struct info *info_ptr = info_space; ENTRY item, *found_item, *hsearch( ); /* name to look for in table */ char name_to_find[30]; int i = 0; /* create table */ (void) hcreate(NUM_EMPL); while (scanf("%s%d%d", str_ptr, &info_ptr->age, &info_ptr->room) != EOF && i++ < NUM_EMPL) { /* put info in structure, and structure in item */ item.key = str_ptr; item.data = (char *)info_ptr; str_ptr += strlen(str_ptr) + 1; info_ptr++; /* put item into table */ (void) hsearch(item, ENTER); } /* access table */ item.key = name_to_find; while (scanf("%s", item.key) != EOF) { if ((found_item = hsearch(item, FIND)) != NULL) { /* if item is in the table */ (void)printf("found %s, age = %d, room = %d\en", found_item->key, ((struct info *)found_item->data)->age, ((struct info *)found_item->data)->room); } else { (void)printf("no such employee %s\en", name_to_find); } } } .ft .ps .fi .SH RETURN VALUE .C hsearch() returns a .SM NULL pointer if either the action is .SM .C FIND and the item could not be found or the action is .SM .C ENTER and the table is full. .PP .C hcreate() returns zero if it cannot allocate sufficient space for the table. .SH WARNINGS .C hsearch() and .C hcreate() use .C malloc() to allocate space (see .IR malloc (3C)). .PP Only one hash search table can be active at any given time. .PP .C hcreate() and .C hdestroy() are unsafe in multi-thread applications. .SH SEE ALSO bsearch(3C), lsearch(3C), malloc(3C), string(3C), tsearch(3C). .SH STANDARDS CONFORMANCE .CR hsearch() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR hcreate() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR hdestroy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4hcreate()\fP \- allocate space for new hash search table@@@\f3hsearch(3C)\f1 .\" index@\f4hsearch()\fP \- hash table search routine@@@\f3hsearch(3C)\f1 .\" index@\f4hdestroy()\fP \- destroy existing hash search table@@@\f3hsearch(3C)\f1 .\" index@manage hash search tables@@@\f3hsearch(3C)\f1 .\" index@hash search tables, manage@@@\f3hsearch(3C)\f1 .\" index@search tables, hash, manage@@@\f3hsearch(3C)\f1 .\" index@tables, hash search, manage@@@\f3hsearch(3C)\f1 .\" .\" toc@\f3hsearch(3C)\f1:\0\0\f4hsearch()\fP, \f4hcreate()\fP, \f4hdestroy()\fP@@@manage hash search tables .\" toc@\f4hcreate()\fP:\0\0manage hash search tables@@@see \f3hsearch(3C)\f1 .\" toc@\f4hdestroy()\fP:\0\0manage hash search tables@@@see \f3hsearch(3C)\f1 .\" .\" links@hsearch.3c hcreate.3c .\" links@hsearch.3c hdestroy.3c .\" .\" fileset_database@hsearch.3c PROGRAMING-MAN .\" $Header: resolver.3n,v 74.1 95/05/10 21:11:16 ssa Exp $ .TA r .TH resolver 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME res_query(\|), res_search(\|), res_mkquery(\|), res_send(\|), res_init(\|), dn_comp(\|), dn_expand(\|), herror(\|) \- resolver routines .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .C "#include " .PP .C "int res_query(" .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_search( .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_mkquery( .C " int op," .C " char *dname," .C " int class," .C " int type," .C " char *data," .C " int datalen," .C " struct rrec *newrr," .C " char *buf," .C " int buflen" .C ); .PP .C "int res_send( .C " char *msg," .C " int msglen," .C " char *answer, .C " int anslen .C ); .PP .C void res_init(); .PP .C int dn_comp( .C " char *exp_dn," .C " char *comp_dn," .C " int length," .C " char **dnptrs," .C " char **lastdnptr" .C ); .PP .C int dn_expand( .C " char *msg," .C " char *eomorig," .C " char *comp_dn," .C " char exp_dn," .C " int length" .C ); .PP .C extern int h_errno; .PP .C void herror(char *s); .PP .SH DESCRIPTION These routines are used for making, sending, and interpreting query and reply messages with Internet domain name servers. .PP Global configuration and state information used by the resolver routines are kept in the structure .CR _res and are defined in .RC < resolv.h >. Most of the fields have reasonable defaults and can be ignored. The resolver options are stored in the .CR _res.options field and are listed below. The options are stored as a simple bit mask containing the bitwise OR of the options enabled. .RS .TP 20 .C RES_INIT True if the initial name server address and default domain name are initialized (i.e., .C res_init() has been called). .TP .C RES_DEBUG Print debugging messages. .TP .C RES_AAONLY Accept authoritative answers only. With this option, .C res_send() should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. .TP .C RES_PRIMARY Query the primary server only. Currently this is not implemented. .TP .C RES_USEVC Use TCP connections for queries instead of UDP datagrams. .TP .C RES_STAYOPEN Used with .C RES_USEVC to keep the TCP connection open between queries. This is useful only in programs that regularly do many queries. UDP should be the normal mode used. .TP .C RES_IGNTC The name server will set the truncation bit if all of the data does not fit into the response datagram packet. If .C RES_IGNTC is set, .C res_send() will not retry the query with TCP (i.e., ignore truncation errors). .TP .C RES_RECURSE Set the recursion-desired bit in queries. This is the default. (\c .C res_send() does not do iterative queries and expects the name server to handle recursion.) .TP .C RES_DEFNAMES If set, .C res_search() appends the default domain name to single-component names (those that do not contain a dot). This option is enabled by default. .TP .C RES_DNSRCH If this option is set, .C res_search() searches for host names in the current domain and in parent domains; see .IR hostname (5). This is used by the standard host lookup routine .C gethostbyname() (see .IR gethostbyname (3N)). This option is enabled by default. .RE .PP Initialization of the resolver structure normally occurs on the first call to one of the resolver routines below. If there are errors in the configuration file, they are silently ignored. .RE .SS Primary Routines .TP 20 .C res_init() Reads the configuration file, .CR /etc/resolv.conf , to get the default domain name, search list, and the Internet address of the local name server(s). If no server is configured, the host running the resolver is tried. The current domain name is defined by the hostname if not specified in the configuration file; it can be overridden by the environment variable .CR LOCALDOMAIN . This environment variable may contain several blank separated tokens and overrides the search list on a per process basis. This is similar to the .CR search command in the configuration file. Another environment variable ( .CR RES_OPTIONS ) can be set to override certain internal resolver options which are set by calling some of the configuration routines above, or by using the configuration file's .CR options command. The syntax of the .CR RES_OPTIONS environment variable is explained in .IR resolver(4). .TP .C res_query() Provides an interface to the server query mechanism. It constructs a query, sends it to the local server, awaits a response, and makes preliminary checks on the reply. The query requests information of the specified .I type and .I class for the specified fully-qualified domain name .IR dname . The reply message is left in the .I answer buffer with length .I anslen supplied by the caller. .TP .C res_search() Makes a query and awaits a response much like .CR res_query() , but in addition, it implements the default and search rules controlled by the .C RES_DEFNAMES and .C RES_DNSRCH options. It returns the first successful reply. .SS Other Routines Routines described here are lower-level routines used by .CR res_query() . .TP 20 .C res_mkquery() Constructs a standard query message and places it in .IR buf . It returns the size of the query, or \(mi1 if the query is larger than .IR buflen . The query type .I op is usually .CR QUERY , but can be any of the query types defined in .RC < arpa/nameser.h >. The domain name for the query is given by .IR dname . .I class can be any of the query classes defined in .RC < arpa/nameser.h >. .I type can be any of the query types defined in .RC < arpa/nameser.h >. .I data is the data for an inverse query .RC ( IQUERY ). .I newrr is currently unused but is intended for making update messages. .TP .C res_send() Sends a pre-formatted query and returns an answer. It calls .C res_init() if .C RES_INIT is not set, sends the query to the local name server, and handles timeouts and retries. .C res_send() returns the length of the reply message, or \(mi1 if there were errors. .TP .C dn_comp() Compresses the domain name .I exp_dn and stores it in .IR comp_dn . The size of the compressed name is returned or \(mi1 if there were errors. .I length is the size of the array pointed to by .IR comp_dn . The compression uses an array of pointers .I dnptrs to previously compressed names in the current message. The first pointer points to to the beginning of the message and the list ends with NULL. The limit to the array is specified by .IR lastdnptr . A side effect of .C dn_comp() is to update the list of pointers for labels inserted into the message as the name is compressed. If .I dnptr is NULL, names are not compressed. If .I lastdnptr is NULL, the list of labels is not updated. .TP .C dn_expand() Expands the compressed domain name .I comp_dn to a full domain name. The compressed name is contained in a query or reply message; .I msg is a pointer to the beginning of the message. The uncompressed name is placed in the buffer indicated by .I exp_dn which is of size .IR length . The size of compressed name is returned or \(mi1 if there was an error. .SH RETURN VALUE Error return status from .C res_search() is indicated by a return value of \(mi1. The external integer .C h_errno can then be checked to see whether this is a temporary failure or an invalid or unknown host. The routine .C herror() can be used to print an error message describing the failure. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. .SH ERRORS .C h_errno can have the following values: .RS .TP 20 .C HOST_NOT_FOUND No such host is known. .TP .C TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .C NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. .TP .C NO_DATA The name is known to the name server, but there is no data of the requested type associated with this name; this is not a temporary error. Another type of request to the name server using this domain name will result in an answer. .RE .SH AUTHOR These resolver routines were developed by the University of California, Berkeley. .SH FILES .TP 30 .C /etc/resolv.conf Resolver configuration file. .SH SEE ALSO named(1m), gethostent(3N), resolver(4), hostname(5), RFC1034, RFC1035, RFC1535. .\" .\" index@\f4res_mkquery\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_query\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_search\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_send\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_init\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_comp\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1routines, resolver@@@\f3resolver(3N)\f1 .\" .\" toc@\f3resolver(3N)\f1:\0\0\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \f4dn_comp\f1, \f4dn_expand\f1, \n\f4herror\f1,\f1@@@resolver routines .\" toc@\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4dn_comp\f1, \f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" .\" links@resolver.3n res_mkquery.3n .\" links@resolver.3n res_query.3n .\" links@resolver.3n res_search.3n .\" links@resolver.3n res_send.3n .\" links@resolver.3n res_init.3n .\" links@resolver.3n dn_comp.3n .\" links@resolver.3n dn_expand.3n .\" links@resolver.3n herror.3n .\" .\" fileset_database@resolver.3n INETSVCS-MAN .\" $Header: hline.3x,v 76.2 95/08/01 11:07:23 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline, mvhline, mvvline, mvwhline, mvwvline, vline, whline, wvline \(em draw lines from single-byte characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvhline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvvline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwhline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwvline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int vline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int whline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int wvline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline() , .CR mvhline() , .Fn mvwhline and .Fn whline functions draw a line proceeding toward the last column of the same line. .P The .CR vline() , .CR mvvline() , .Fn mvwvline and .Fn wvline functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" border(), box(), hline_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline(3X)\f1:\0\0\f4hline()\f1, \f4mvhline()\f1, \f4mvvline()\f1, \f4mvwhline()\f1, \f4mvwvline()\f1, \f4vline()\f1, \f4whline()\f1, \f4wvline()\f1\n@@@draw lines from single-byte characters and renditions .\" toc@\f4mvhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4vline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4whline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4wvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" .\" index@\f4hline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4vline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4whline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4wvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1lines, draw from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1single-byte characters and renditions, draw lines from@@@\f3hline(3X)\f1 .\" index@\f1characters and renditions, draw lines from single-byte@@@\f3hline(3X)\f1 .\" index@\f1renditions and characters, draw lines from single-byte@@@\f3hline(3X)\f1 .\" .\" links@hline.3x mvhline.3x .\" links@hline.3x mvvline.3x .\" links@hline.3x mvwhline.3x .\" links@hline.3x mvwvline.3x .\" links@hline.3x vline.3x .\" links@hline.3x whline.3x .\" links@hline.3x wvline.3x .\" .\" fileset_database@hline.3x CURS-ENG-A-MAN .\" $Header: hline_set.3x,v 76.2 95/08/01 11:08:14 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline_set 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline_set, mvhline_set, mvvline_set, mvwhline_set, mvwvline_set, vline_set, whline_set, wvline_set \(em draw lines from complex characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvhline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvvline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwhline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwvline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int vline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int whline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int wvline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline_set() , .CR mvhline_set() , .Fn mvwhline_set and .Fn whline_set functions draw a line proceeding toward the last column of the same line. .P The .CR vline_set() , .CR mvvline_set() , .Fn mvwvline_set and .Fn wvline_set functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" border_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline_set(3X)\f1:\0\0\f4hline_set()\f1, \f4mvhline_set()\f1, \f4mvvline_set()\f1, \f4mvwhline_set()\f1, \f4mvwvline_set()\f1, \n\f4vline_set()\f1, \f4whline_set()\f1, \f4wvline_set()\f1@@@draw lines from complex characters and renditions .\" toc@\f4mvhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4vline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4whline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4wvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" .\" index@\f4hline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4vline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4whline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4wvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1lines, draw from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1complex characters and renditions, draw lines from@@@\f3hline_set(3X)\f1 .\" index@\f1characters and renditions, complex, draw lines from@@@\f3hline_set(3X)\f1 .\" .\" links@hline_set.3x mvhline_set.3x .\" links@hline_set.3x mvvline_set.3x .\" links@hline_set.3x mvwhline_set.3x .\" links@hline_set.3x mvwvline_set.3x .\" links@hline_set.3x vline_set.3x .\" links@hline_set.3x whline_set.3x .\" links@hline_set.3x wvline_set.3x .\" .\" fileset_database@hline_set.3x CURS-ENG-A-MAN .\" $Header: secure_rpc.3c,v 74.1 95/05/10 21:12:12 ssa Exp $ .TA s .TH secure_rpc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME secure_rpc(), authdes_create(), authdes_getucred(), get_myaddress(), getnetname(), host2netname(), key_decryptsession(), key_encryptsession(), key_gendes(), key_setsecret(), netname2host(), netname2user(), user2netname() \- library routines for secure remote procedure calls .SH DESCRIPTION .LP .C RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .LP .C RPC allows various authentication flavors. The .B authdes_getucred() and .B authdes_create() routines implement the .B DES authentication flavor. See .BR rpc_clnt_auth (3C) for routines relating to the .B AUTH_NONE and .B AUTH_UNIX authentication types. .IP Note: Both the client and server should have their keys in the .BR publickey (5) database. Also, the keyserver daemon .BR keyserv (1M) must be running on both the client and server hosts for the .B DES authentication system to work. .SS Routines .LP The following routines require that the header .BR be included. .PP The .B AUTH data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "AUTH *" .C "authdes_create(netname, window, syncaddr, deskeyp)" .C "char *netname;" .C "unsigned window;" .C "struct sockaddr_in *syncaddr;" .C "des_block *deskeyp;" .fi .IP .B authdes_create() is an interface to the .B RPC secure authentication system, known as .B DES authentication. .IP Used on the client side, .B authdes_create() returns an authentication handle that enables the use of the secure authentication system. The first parameter .I netname is the network name of the owner of the server process. This field usually represents a .I host derived from the utility routine .BR host2netname() , but could also represent a user name using .BR user2netname() . The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third parameter .I syncaddr is optional. If it is .B NULL, then the authentication system will assume that the local clock is always in sync with the server's clock, and will not attempt to synchronize with the server. If an address is supplied then the system will use it for consulting the remote time service whenever resynchronization is required. This parameter is usually the address of the .B RPC server itself. The final parameter .I deskeyp is also optional. If it is .B NULL, then the authentication system will generate a random .B DES key to be used for the encryption of credentials. If .I deskeyp is supplied then it is used instead. .PP .nf .C "int" .C "authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)" .C "struct authdes_cred *adc;" .C "short *uidp, *gidp, *gidlenp;" .C "int *gidlistp;" .fi .IP .BR authdes_getucred() , is a .B DES authentication routine used by the server for converting a .B DES credential, which is operating system independent, into a .B UNIX credential. .I uidp points to the user .B ID of the user associated with .IR adc ; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. .br .ne 5 .IP This routine differs from the utility routine .B netname2user() in that .B authdes_getucred() pulls its information from a cache, and does not have to do a .B NIS name service lookup every time it is called to get its information. Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "void" .C "get_myaddress(addr)" .C "struct sockaddr_in *addr;" .fi .IP Return the machine's .B IP address in .IR addr. The port number is always set to .BR htons(PMAPPORT) . .PP .nf .C "int" .C "getnetname(netname)" .C "char netname[MAXNETNAMELEN];" .fi .IP Return the unique, operating-system independent netname of the caller in the fixed-length array .IR netname . Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "int" .C "host2netname(netname, host, domain)" .C "char netname[MAXNETNAMELEN];" .C "char *host;" .C "char *domain;" .fi .IP Convert from a domain-specific hostname to an operating-system independent netname. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . This routine should be used if the owner of the server process is the machine that is, the user with effective user .B ID zero. Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2host() . .PP .nf .C "int" .C "key_decryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP An interface routine to the keyserver daemon, which is associated with .B RPC's secure authentication system ( .B DES authentication). User programs rarely need to call it, or its associated routines .BR key_encryptsession() , .B key_gendes() and .BR key_setsecret() . System commands such as .B login and the .B RPC library are the main clients of these four routines. .IP .B key_decryptsession() takes the netname of a server and a .B DES key, and decrypts the key by using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_encryptsession() . .PP .nf .C "int" .C "key_encryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It takes the netname of the server and a .B DES key, and encrypts it using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_decryptsession() . .PP .nf .C "int" .C "key_gendes(deskeyp)" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It is used to ask the keyserver for a secure conversation key. Choosing one at random is usually not good enough, because the common ways of choosing random numbers, such as using the current time, are very easy to guess. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "key_setsecret(keyp)" .C "char *keyp;" .fi .IP A keyserver interface routine. It is used to set the secret key for the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "netname2host(netname, host, hostlen)" .C "char *netname;" .C "char *host;" .C "int hostlen;" .fi .IP Convert an operating-system independent netname to a domain-specific hostname. .I hostlen specifies the size of the array pointed to by .I host. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR host2netname() . .PP .nf .C "int" .C "netname2user(netname, uidp, gidp, gidlenp, gidlistp)" .C "char *netname;" .C "int *uidp, *gidp, *gidlenp, *gidlistp;" .fi .IP Convert an operating-system independent netname to a domain-specific user .B ID. .I uidp points to the user .B ID of the user; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR user2netname() . .PP .nf .C "int" .C "user2netname(netname, uid, domain)" .C "char netname[MAXNETNAMELEN];" .C "int uid;" .C "char *domain;" .fi .IP Convert a domain-specific username to an operating-system independent netname. .I uid is the user .B ID of the owner of the server process. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2user() . .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR login (1), .BR chkey (1), .BR rpc (3C), .BR rpc_clnt_auth (3C), .BR publickey (4), .BR keyserv (1M), .BR newkey (1M) .\" toc@\f3secure_rpc(3C)\f1:\0\0\f4authdes_create()\fP, \f4authdes_getucred()\fP, \f4get_myaddress()\fP, \n\f4getnetaddress()\fP, \f4getnetname()\fP, \f4host2netname()\fP, \n\f4key_decryptsession()\fP, \f4key_encryptsession()\fP, \f4key_gendes()\fP, \n\f4key_setsecret()\fP, \f4netname2host()\fP, \f4netname2user()\fP, \n\f4user2netname()\fP@@@library routines for secure remote procedure calls .\" toc@\f4secure_rpc()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_create()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_getucred()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4get_myaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4host2netname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_decryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_encryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_gendes()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_setsecret()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2host()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2user()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4user2netname()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" index@library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4secure_rpc()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_create()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_getucred()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4get_myaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4host2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_decryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_encryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_gendes()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_setsecret()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2host()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2user()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4user2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" links@secure_rpc.3c authdes_create.3c .\" links@secure_rpc.3c authdes_getucred.3c .\" links@secure_rpc.3c get_myaddress.3c .\" links@secure_rpc.3c getnetaddress.3c .\" links@secure_rpc.3c getnetname.3c .\" links@secure_rpc.3c host2netname.3c .\" links@secure_rpc.3c key_decryptsession.3c .\" links@secure_rpc.3c key_encryptsession.3c .\" links@secure_rpc.3c key_gendes.3c .\" links@secure_rpc.3c key_setsecret.3c .\" links@secure_rpc.3c netname2host.3c .\" links@secure_rpc.3c netname2user.3c .\" links@secure_rpc.3c user2netname.3c .\" $Header: hpib_abort.3i,v 74.1 95/05/10 21:43:07 ssa Exp $ .TA h .TH hpib_abort 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME hpib_abort(\|) \- stop activity on specified HP-IB bus .SH SYNOPSIS .C "#include " .PP .C "int hpib_abort(int eid);" .SH DESCRIPTION .C hpib_abort() terminates activity on the addressed .SM HP-IB bus by pulsing the .SM IFC line. .I eid is an entity identifier of an open .SM HP-IB raw bus device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .C creat() call. .PP .C hpib_abort() also sets the .SM REN line and clears the .SM ATN line. The status of the .SM SRQ line is not affected. The interface must be the system controller of the bus. .SH RETURN VALUE .C hpib_abort() returns 0 (zero) if successful, or \(mi1 if an error was encountered. .SH ERRORS .C hpib_abort() fails under the following circumstances, and sets .C errno (see .IR errno (2)) to the value in square brackets: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to an .SM HP-IB raw bus device file. .TP .SM [EIO] the specified interface is not the system controller (see .SM DEPENDENCIES below). .TP .SM [ETIMEDOUT] a timeout occurred. .TP .SM [EACCES] The interface associated with this .I eid is locked by another process and .C O_NDELAY is set for this .I eid (see io_lock(3I)). .RE .SH DEPENDENCIES .SS Series 300/400: The .SM HP 98625A/B and .SM HP 25560A HP-IB interfaces do not clear the .SM ATN line. .SM EIO is returned if a timeout occurs. .SS Series 800: If the interface is not currently the system controller, .C hpib_abort() sets .C errno to .SM [EACCES] instead of to .SM [EIO]. .SH AUTHOR .C hpib_abort() was developed by HP. .SH SEE ALSO dup(2), creat(2), fcntl(2), open(2). .\" index@\f4hpib_abort()\fP \- stop activity on specified \s-1HP-IB\s0@@@\f3hpib_abort(3I)\f1 .\" index@\s-1HP-IB\s+1: stop activity on specified \s-1HP-IB\s0@@@\f3hpib_abort(3I)\f1 .\" index@interface, \s-1HP-IB\s+1: stop activity on specified \s-1HP-IB\s0@@@\f3hpib_abort(3I)\f1 .\" index@stop activity on specified \s-1HP-IB\s0@@@\f3hpib_abort(3I)\f1 .\" index@bus, stop activity on specified \s-1HP-IB\s0@@@\f3hpib_abort(3I)\f1 .\" index@activity on specified \s-1HP-IB\s0 bus, stop@@@\f3hpib_abort(3I)\f1 .\" .\" toc@\f3hpib_abort(3I)\f1:\0\0\f4hpib_abort()\fP@@@stop activity on specified \s-1HP-IB\s0 bus .\" .\" fileset_database@hpib_abort.3i PROGRAMING-MAN .\" $Header: hpib_bus_st.3i,v 74.1 95/05/10 21:43:36 ssa Exp $ .TA h .TH hpib_bus_status 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME hpib_bus_status(\|) \- return status of HP-IB interface .SH SYNOPSIS .C "#include " .PP .C "int hpib_bus_status(int eid, int status);" .SH DESCRIPTION .C hpib_bus_status() obtains status information about an .SM HP-IB channel. .I eid is an entity identifier of an open .SM HP-IB raw bus device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .C creat() call. .I status is an integer determining what status information is returned for a particular call. The values defined for .I status and their associated meanings are: .RS .TP 25 .C REMOTE_STATUS Is the channel currently in remote state? .TP .C SRQ_STATUS What is the current state of the .SM SRQ line? .TP .C NDAC_STATUS What is the current state of the .SM NDAC line? .TP .C SYS_CONT_STATUS Is the channel currently system controller? .TP .C ACT_CONT_STATUS Is the channel currently active controller? .TP .C TALKER_STATUS Is the channel currently addressed as talker? .TP .C LISTENER_STATUS Is the channel currently addressed as listener? .TP .C CURRENT_BUS_ADDRESS What is the channel's bus address? .RE .PP The remote-state status is not defined when the interface is the active controller, although reading remote-state status in such a situation is not an error. Determining the status of the .SM NDAC line is not available on all machines, and its use is therefore discouraged to ensure compatibility among various systems. Machines that do not support sensing the .SM NDAC line return an error. .SH RETURN VALUE The value returned by .C hpib_bus_status() depends upon the value of .IR status . If .I status is .CR CURRENT_BUS_ADDRESS , the return value is either the .SM HP-IB bus address or \(mi1 if an error occurred. If .I status is any of the other values, the return value is 0 if the condition is false (the line is clear), 1 if the condition is true (the line is set), or \(mi1 if an error occurred. .SH ERRORS .C hpib_bus_status() fails under the following conditions, and sets .C errno (see .IR errno (2)) to the value in square brackets: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to an .SM HP-IB raw bus device file. .TP .SM [EINVAL] .I status is not one of the values specified above. .RE .SH DEPENDENCIES .SS Series 300/400: The status of signal lines being driven by the interface is undefined, although reading them in such a situation is not an error. Non-active controllers cannot sense the .SM SRQ line. Active listeners cannot sense the .SM NDAC line. .PP The .SM HP 98625A/B HP-IB interface cannot determine the current state of the .SM NDAC line. Attempts to read this line fail and set .C errno (see .IR errno (2)) to .SM EINVAL. .RE .SH AUTHOR .C hpib_bus_status() was developed by HP. .\" index@\f4hpib_bus_status()\fP \- return status of \s-1HP-IB\s+1 interface@@@\f3hpib_bus_status(3I)\f1 .\" index@\s-1HP-IB\s+1: return status of \s-1HP-IB\s+1 interface@@@\f3hpib_bus_status(3I)\f1 .\" index@interface, \s-1HP-IB\s+1: return status of \s-1HP-IB\s+1 interface@@@\f3hpib_bus_status(3I)\f1 .\" index@return status of \s-1HP-IB\s+1 interface@@@\f3hpib_bus_status(3I)\f1 .\" index@status of \s-1HP-IB\s+1 interface, return@@@\f3hpib_bus_status(3I)\f1 .\" .\" toc@\f3hpib_bus_status(3I)\f1:\0\0\f4hpib_bus_status()\fP@@@return status of \s-1HP-IB\s+1 interface .\" .\" fileset_database@hpib_bus_st.3i PROGRAMING-MAN .\" $Header: hpib_card_p.3i,v 76.1 95/06/20 14:45:47 ssa Exp $ .TA h .TH hpib_card_ppoll_resp 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME hpib_card_ppoll_resp(\|) \- control response to parallel poll on HP-IB .SH SYNOPSIS .C "#include " .PP .C "int hpib_card_ppoll_resp(int eid, int flag);" .SH DESCRIPTION .C hpib_card_ppoll_resp() enables or disables an interface for parallel polls. It also controls the sense, and determines the line on which the response is sent. This provides a means for the interface to ignore or respond to a parallel poll according to whether it is enabled to respond. .PP .I eid is an entity identifier of an open .SM HP-IB raw bus device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .C creat() call. .I flag is an integer having one of the following bit patterns: .RS .TP 18 .B Bit Pattern .B Meaning .TP \0\0 10000 Disable parallel poll response. .TP \0\0 0SPPP Enable parallel poll response, where .IP S = sense of the response, and .IP PPP = 3-bit binary number specifying the line on which the response is sent where the octal values 0 through 7 correspond to lines .SM DIO1 through .SM DIO8. .RE .SH RETURN VALUE .C hpib_card_ppoll_resp() returns 0 (zero) if successful, or \(mi1 if an error was encountered. .SH ERRORS .C hpib_card_ppoll_resp() fails under the following circumstances, and sets .C errno (see .IR errno (2)) to the value in square brackets: .RS .TP 15 .SM [EACCES] The interface associated with this .I eid is locked by another process and .C O_NDELAY is set for this .I eid (see .IR io_lock (3I)). .TP .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to an .SM HP-IB raw bus device file. .TP .SM [EINVAL] the device cannot respond on the line number specified by .IR flag . .TP .SM [ETIMEDOUT] a timeout occurred. .RE .SH DEPENDENCIES Since the sense and response line number are not programmable on the .SM HP\|27110B HP-IB interface, the equivalent parallel poll configuration commands are sent over the .SM HP-IB to the interface. Therefore, this function fails if the interface is not active controller. .SH AUTHOR .C hpib_card_ppoll_resp() was developed by HP. .SH SEE ALSO dup(2), creat(2), fcntl(2), open(2), hpib_ppoll(3I), hpib_ppoll_resp_ctl(3I). .\" index@\f4hpib_card_ppoll_resp()\fP \- control response to parallel poll on \s-1HP-IB\s+1@@@\f3hpib_card_ppoll_resp(3I)\f1 .\" index@control response to parallel poll on \s-1HP-IB\s+1@@@\f3hpib_card_ppoll_resp(3I)\f1 .\" index@\s-1HP-IB\s+1: control response to parallel poll on \s-1HP-IB\s+1@@@\f3hpib_card_ppoll_resp(3I)\f1 .\" index@interface, \s-1HP-IB\s+1: control response to parallel poll on \s-1HP-IB\s+1@@@\f3hpib_card_ppoll_resp(3I)\f1 .\" index@response to parallel poll on \s-1HP-IB\s+1, control@@@\f3hpib_card_ppoll_resp(3I)\f1 .\" index@parallel poll on \s-1HP-IB\s+1, control response to@@@\f3hpib_card_ppoll_resp(3I)\f1 .\" index@poll on \s-1HP-IB\s+1, control response to parallel@@@\f3hpib_card_ppoll_resp(3I)\f1 .\" .\" toc@\f3hpib_card_ppoll_resp(3I)\f1:\0\0\f4hpib_card_ppoll_resp()\fP@@@control response to parallel poll on \s-1HP-IB\s+1 .\" .\" fileset_database@hpib_card_p.3i PROGRAMING-MAN .\" $Header: hpib_eoi_ct.3i,v 74.1 95/05/10 21:44:47 ssa Exp $ .TA h .TH hpib_eoi_ctl 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME hpib_eoi_ctl(\|) \- control EOI mode for HP-IB file .SH SYNOPSIS .C "#include " .PP .C "int hpib_eoi_ctl(int eid, int flag);" .SH DESCRIPTION .C hpib_eoi_ctl() enables you to turn .SM EOI mode on or off. .I eid is an entity identifier of an open .SM HP-IB raw device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .CR creat() call. .I flag is an integer which, if non-zero, enables .SM EOI mode, and otherwise disables it. .PP .SM EOI mode causes the last byte of all subsequent write operations to be written out with the .SM EOI line asserted, signifying the end of the data transmission. By default, .SM EOI mode is disabled when the device file is opened. .PP Entity identifiers for the same device file obtained by separate .C open() requests have their own .SM EOI modes associated with them. Entity identifiers for the same device file obtained by .C dup() or inherited by a .C fork() request share the same .SM EOI mode. In the latter case, if one process enables .SM EOI mode, then .SM EOI mode is in effect for all such entity identifiers. .SH RETURN VALUE .C hpib_eoi_ctl() returns a 0 (zero) if successful, or \(mi1 if an error was encountered. .SH ERRORS .C hpib_eoi_ctl() fails under any of the following circumstances and sets .C errno (see .IR errno (2)) to the value in square brackets: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to an .SM HP-IB device file. .RE .SH DEPENDENCIES .SS Series 800: .SM EOI mode is enabled when the device file is first opened. .SH AUTHOR .C hpib_eoi_ctl() was developed by HP. .\" index@\f4hpib_eoi_ctl()\fP \- control \s-1EOI\s+1 mode for \s-1HP-IB\s+1 file@@@\f3hpib_eoi_ctl(3I)\f1 .\" index@\s-1HP-IB\s+1: control \s-1EOI\s+1 mode for \s-1HP-IB\s+1 file@@@\f3hpib_eoi_ctl(3I)\f1 .\" index@interface, \s-1HP-IB\s+1: control \s-1EOI\s+1 mode for \s-1HP-IB\s+1 file@@@\f3hpib_eoi_ctl(3I)\f1 .\" index@control \s-1EOI\s+1 mode for \s-1HP-IB\s+1 file@@@\f3hpib_eoi_ctl(3I)\f1 .\" index@\s-1EOI\s+1 mode for \s-1HP-IB\s+1 file, control@@@\f3hpib_eoi_ctl(3I)\f1 .\" index@mode, \s-1EOI\s+1, for \s-1HP-IB\s+1 file, control@@@\f3hpib_eoi_ctl(3I)\f1 .\" .\" toc@\f3hpib_eoi_ctl(3I)\f1:\0\0\f4hpib_eoi_ctl()\fP@@@control \s-1EOI\s+1 mode for \s-1HP-IB\s+1 file .\" .\" fileset_database@hpib_eoi_ct.3i PROGRAMING-MAN .\" $Header: hpib_io.3i,v 76.1 95/06/20 14:46:11 ssa Exp $ .TA h .TH hpib_io 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME hpib_io(\|) \- perform I/O with an HP-IB channel from buffers .SH SYNOPSIS .C "#include " .PP .C "int hpib_io(int eid, struct iodetail *iovec, size_t iolen);" .SH DESCRIPTION .C hpib_io() performs and controls read and/or write operations on the specified .SM HP-IB bus. .I eid is an entity identifier of an open .SM HP-IB raw bus device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .CR creat() call. .PP Parameters are as follows: .RS .TP 10 .I iovec Pointer to an array of structures of the form: .RS .nf .IP .C struct\0iodetail\0{ .C " char mode;" .C " char terminator;" .C " int count;" .C " char *buf;" .C }; .fi .RE .IP The .I iodetail structure is defined in the include file .RC < dvio.h >. .TP .I iolen Specifies the number of structures in .IR iovec . .RE .SS iodetail Structure Elements in the .C iodetail structure are: .RS .TP 12 .I mode Describes what is to be done during .SM I/O on the buffer pointed to by .IR buf . .I mode is constructed by .SM OR\s0-ing flags from the following list: .RS .IP One and only one of the following two flags .I must be specified: .RS .RS .TP 12 .C HPIBREAD Perform a read of the .SM HP-IB bus, placing data into the accompanying buffer. .TP .C HPIBWRITE Perform a write to the .SM HP-IB bus, using data from the accompanying buffer. .RE .RE .IP The following flags can be used in most combinations (not all combinations are valid), or not at all: .RS .RS .TP 12 .C HPIBATN Data is written with .SM ATN enabled. .TP .C HPIBEOI Data written is terminated with .SM EOI (this flag is ignored when .C HPIBATN is enabled). .TP .C HPIBCHAR Data read is terminated with the character given in the .I terminator element of the .I iodetail structure. .RE .RE .RE .TP .I terminator Describes the termination character, if any, that should be checked for on input. .I count is an integer specifying the maximum number of bytes to be transferred. .RE .PP A read operation terminates when either .I count is matched, an .SM EOI is detected, or the designated .I terminator is detected (if .C HPIBCHAR is set in .IR mode ). .PP A write operation terminates when .I count is matched, and the final byte is sent with .SM EOI asserted (if .C HPIBEOI is set in .IR mode ). .PP If .C HPIBATN is set in .IR mode , write operations occur with .SM ATN enabled. Setting .C HPIBATN for a read operation is ignored and has no effect. .PP The members of the .C iovec array are accessed in order. .SH RETURN VALUE If all transactions are successful, .C hpib_io() returns a zero and updates the .I count element in each structure in the .C iovec array to reflect the actual number of bytes read or written. .PP If an error is encountered during a transaction defined by an element of .CR iovec , .C hpib_io() returns without completing any transactions that might follow. In particular, if an error occurs, .C hpib_io() returns a \(mi1, and the .I count element of the transaction that caused the error is set to \(mi1. .SH ERRORS .C hpib_io() fails under any of the following circumstances, and sets .C errno (see .IR errno (2)) to the value indicated: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to an .SM HP-IB raw bus device file. .TP .SM [ETIMEDOUT] a timeout occurred. .TP .SM [EIO] .I eid is not the active controller. .RE .SH DEPENDENCIES If the interface is not currently the active controller, .C hpib_io() sets .C errno to .SM [EACCES] instead of to .SM [EIO]. .SH AUTHOR .C hpib_io() was developed by HP. .\" .\" index@\f4hpib_io()\fP \- perform \s-1I/O\s+1 with an \s-1HP-IB\s+1 channel from buffers@@@\f3hpib_io(3I)\f1 .\" index@\s-1HP-IB\s+1: perform \s-1I/O\s+1 with an \s-1HP-IB\s+1 channel from buffers@@@\f3hpib_io(3I)\f1 .\" index@interface, \s-1HP-IB\s+1: perform \s-1I/O\s+1 with an \s-1HP-IB\s+1 channel from buffers@@@\f3hpib_io(3I)\f1 .\" index@perform \s-1I/O\s+1 with an \s-1HP-IB\s+1 channel from buffers@@@\f3hpib_io(3I)\f1 .\" index@\s-1I/O\s+1 with an \s-1HP-IB\s+1 channel from buffers, perform@@@\f3hpib_io(3I)\f1 .\" index@channel from buffers, perform \s-1I/O\s+1 with an \s-1HP-IB\s+1@@@\f3hpib_io(3I)\f1 .\" index@buffers, use to perform \s-1I/O\s+1 with an \s-1HP-IB\s+1 channel@@@\f3hpib_io(3I)\f1 .\" .\" toc@\f3hpib_io(3I)\f1:\0\0\f4hpib_io()\fP@@@perform \s-1I/O\s+1 with an \s-1HP-IB\s+1 channel from buffers .\" .\" fileset_database@hpib_io.3i PROGRAMING-MAN .\" $Header: hpib_pass_c.3i,v 74.1 95/05/10 21:45:29 ssa Exp $ .TA h .TH hpib_pass_ctl 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME hpib_pass_ctl(\|) \- change active controllers on HP-IB .SH SYNOPSIS .C "#include " .PP .C "int hpib_pass_ctl(int eid, int ba);" .SH DESCRIPTION .C hpib_pass_ctl() passes control of a bus to an inactive controller on that bus. The inactive controller becomes the active controller of that bus. .I eid is an entity identifier of an open .SM HP-IB raw bus device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .C creat() call. .I ba is the bus address of the intended device. .PP Not all devices can accept control. Pass control passes only active control of the bus; it cannot pass system control of the bus. The specified interface must be the current active controller but need not be the system controller. The pass control operation does not suspend program execution if the inactive controller does not take active control of the bus. However, the interface is no longer active controller. .SH RETURN VALUE .C hpib_pass_ctl() returns 0 (zero) if successful, or \(mi1 if an error was encountered. .SH ERRORS .C hpib_pass_ctl() fails under any of the following circumstances, and sets .C errno (see .IR errno (2)) to the value in square brackets: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to an .SM HP-IB raw bus device file. .TP .SM [EIO] the interface is not the active controller. .TP .SM [ETIMEDOUT] a timeout occurred. .TP .SM [EINVAL] .I ba is not a valid .SM HP-IB bus address. .TP .SM [EACCES] The interface associated with this .I eid is locked by another process and .C O_NDELAY is set for this .I eid (see .IR io_lock (3I)). .RE .SH DEPENDENCIES .SS Series 300/400: .SM EIO is returned if a timeout occurs. .SS Series 800: If the interface is not currently the active controller, .C hpib_pass_ctl() sets .C errno to .SM [EACCES] instead of to .SM [EIO]. .RE .SH AUTHOR .C hpib_pass_ctl() was developed by HP. .\" index@\f4hpib_pass_ctl()\fP \- change active controllers on \s-1HP-IB\s+1@@@\f3hpib_pass_ctl(3I)\f1 .\" index@\s-1HP-IB\s+1: change active controllers on \s-1HP-IB\s+1@@@\f3hpib_pass_ctl(3I)\f1 .\" index@interface, \s-1HP-IB\s+1: change active controllers on \s-1HP-IB\s+1@@@\f3hpib_pass_ctl(3I)\f1 .\" index@change active controllers on \s-1HP-IB\s+1@@@\f3hpib_pass_ctl(3I)\f1 .\" index@active controllers on \s-1HP-IB\s+1, change@@@\f3hpib_pass_ctl(3I)\f1 .\" index@controllers on \s-1HP-IB\s+1, change active@@@\f3hpib_pass_ctl(3I)\f1 .\" .\" toc@\f3hpib_pass_ctl(3I)\f1:\0\0\f4hpib_pass_ctl()\fP@@@change active controllers on \s-1HP-IB\s+1 .\" .\" fileset_database@hpib_pass_c.3i PROGRAMING-MAN .\" $Header: hpib_ren_ct.3i,v 74.1 95/05/10 21:45:56 ssa Exp $ .TA h .TH hpib_ren_ctl 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME hpib_ren_ctl(\|) \- control the Remote Enable line on HP-IB .SH SYNOPSIS .C "#include " .PP .C "int hpib_ren_ctl(int eid, int flag);" .SH DESCRIPTION .C hpib_ren_ctl() enables/disables the Remote Enable .SM (REN) line depending upon the value of .IR flag . .I eid is an entity identifier of an open .SM HP-IB raw bus device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .C creat() call. .I flag is an integer which, if non-zero, enables the .SM REN line, and otherwise disables it. .PP .C hpib_ren_ctl() can be used in conjunction with .C hpib_send_cmnd() to place devices into the remote state or local state. The .SM REN line is normally enabled at all times, and is in this state at power-up. Only the system controller can enable or disable the .SM REN line. .SH RETURN VALUE .C hpib_ren_ctl() returns 0 (zero) if successful, or \(mi1 if an error was encountered. .SH ERRORS .C hpib_ren_ctl() fails under the following circumstances, and sets .C errno (see .IR errno (2)) to the value in square brackets: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to an .SM HP-IB raw bus device file. .TP .SM [EIO] the interface is not the system controller. .RE .SH AUTHOR .C hpib_ren_ctl() was developed by HP. .\" index@\f4hpib_ren_ctl()\fP \- control the Remote Enable line on \s-1HP-IB\s+1@@@\f3hpib_ren_ctl(3I)\f1 .\" index@\s-1HP-IB\s+1: control the Remote Enable line on \s-1HP-IB\s+1@@@\f3hpib_ren_ctl(3I)\f1 .\" index@interface, \s-1HP-IB\s+1: control the \s-1HP-IB\s+1 interface Remote Enable line@@@\f3hpib_ren_ctl(3I)\f1 .\" index@control the \s-1HP-IB\s+1 interface Remote Enable line@@@\f3hpib_ren_ctl(3I)\f1 .\" index@Remote Enable line on \s-1HP-IB\s+1, control the@@@\f3hpib_ren_ctl(3I)\f1 .\" index@line on \s-1HP-IB\s+1, control the Remote Enable@@@\f3hpib_ren_ctl(3I)\f1 .\" .\" toc@\f3hpib_ren_ctl(3I)\f1:\0\0\f4hpib_ren_ctl()\fP@@@control the Remote Enable line on \s-1HP-IB\s+1 .\" .\" fileset_database@hpib_ren_ct.3i PROGRAMING-MAN .\" $Header: hpib_rqst_s.3i,v 74.1 95/05/10 21:46:16 ssa Exp $ .TA h .TH hpib_rqst_srvce 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME hpib_rqst_srvce(\|) \- allow interface to enable SRQ line on HP-IB .SH SYNOPSIS .C "#include " .PP .C "int hpib_rqst_srvce(int eid, int cv);" .SH DESCRIPTION .C hpib_rqst_srvce() specifies a response byte to be sent by the interface when it is serially polled by the active controller. .I eid is an entity identifier of an open .SM HP-IB raw bus device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .C creat() call. .I cv is an integer control value representation of the desired response byte. .PP .C hpib_rqst_srvce() optionally enables the .SM SRQ line depending upon the response byte. If bit 6 of the response byte is set, the .SM SRQ line is enabled. It remains enabled until the active controller conducts a serial poll or until the computer executes the request function with bit 6 cleared. However, the .SM SRQ line is not enabled as long as the interface is active controller. If bit 6 is set, the interface remembers its response byte, and enables the .SM SRQ line when control is passed to another device on the bus. .PP The response byte is structured as follows: .IP .TS tab(;); cB lB c l. Bit;Meaning 0;\s-1SPOLL\s0 bit (least significant bit of response byte) 1;\s-1SPOLL\s0 bit 2;\s-1SPOLL\s0 bit 3;\s-1SPOLL\s0 bit 4;\s-1SPOLL\s0 bit 5;\s-1SPOLL\s0 bit 6;\s-1SRQ\s0 line 7;\s-1SPOLL\s0 bit (most significant bit of response byte) .TE .RE .SH RETURN VALUE .C hpib_rqst_srvce() returns 0 (zero) if successful, or \(mi1 if an error was encountered. .SH ERRORS .PP .C hpib_rqst_srvce() fails under the following circumstances, and sets .C errno (see .IR errno (2)) to the value in square brackets: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to an .SM HP-IB raw bus device file. .TP .SM [ETIMEDOUT] a timeout occurred. .TP .SM [EACCES] The interface associated with this .I eid is locked by another process and .C O_NDELAY is set for this .I eid (see io_lock(3I)). .RE .SH DEPENDENCIES .SS Series 300/400: The .SM HP\|98625A/B and .SM HP\|25560A HP-IB interface cards allow only bit 6 to be set. All other bits are cleared. .PP .SM EIO is returned if a timeout occurs. .SS Series 800: The .SM HP\|27110B HP-IB interface card allows only bit 6 to be set. All other bits are cleared. .SH AUTHOR .C hpib_rqst_srvce() was developed by HP. .\" index@\f4hpib_rqst_srvce()\fP \- allow interface to enable \s-1SRQ\s+1 line on \s-1HP-IB\s+1@@@\f3hpib_rqst_srvce(3I)\f1 .\" index@\s-1HP-IB\s+1: allow interface to enable \s-1SRQ\s+1 line on \s-1HP-IB\s+1@@@\f3hpib_rqst_srvce(3I)\f1 .\" index@interface, \s-1HP-IB\s+1: allow interface to enable \s-1SRQ\s+1 line on \s-1HP-IB\s+1@@@\f3hpib_rqst_srvce(3I)\f1 .\" index@allow interface to enable \s-1SRQ\s+1 line on \s-1HP-IB\s+1@@@\f3hpib_rqst_srvce(3I)\f1 .\" index@enable \s-1SRQ\s+1 line on \s-1HP-IB\s+1, allow interface to@@@\f3hpib_rqst_srvce(3I)\f1 .\" index@\s-1SRQ\s+1 line on \s-1HP-IB\s+1, allow interface to enable@@@\f3hpib_rqst_srvce(3I)\f1 .\" index@line, \s-1SRQ\s+1, on \s-1HP-IB\s+1, allow interface to enable@@@\f3hpib_rqst_srvce(3I)\f1 .\" .\" toc@\f3hpib_rqst_srvce(3I)\f1:\0\0\f4hpib_rqst_srvce()\fP@@@allow interface to enable \s-1SRQ\s+1 line on \s-1HP-IB\s+1 .\" .\" fileset_database@hpib_rqst_s.3i PROGRAMING-MAN .\" $Header: hpib_send_c.3i,v 74.1 95/05/10 21:46:32 ssa Exp $ .TA h .TH hpib_send_cmnd 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME hpib_send_cmnd(\|) \- send command bytes over HP-IB .SH SYNOPSIS .C "#include " .P .C "int hpib_send_cmnd(int eid, const char *ca, int length);" .SH DESCRIPTION .C hpib_send_cmnd() sends specified arbitrary bytes of information on the .SM HP-IB with the .SM ATN line asserted, providing a means to configure and control the bus. .I eid is an entity identifier of an open .SM HP-IB raw bus device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .C creat() call. .I ca is a character pointer to a string of bytes to be written to the .SM HP-IB bus as commands. .I length is an integer specifying the number of bytes in the string pointed to by .IR ca . .PP The interface must currently be the active controller in order to send commands over the bus. .PP Note that for all .SM HP-IB interfaces, both built-in and plug-in, the most significant bit of each byte is overwritten with a parity bit. All commands are written with odd parity. .SH RETURN VALUE .C hpib_send_cmnd() returns 0 (zero) if successful, or \(mi1 if an error was encountered. .SH ERRORS .C hpib_send_cmnd() fails under the following circumstances, and sets .C errno (see .IR errno (2)) to the value in square brackets: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to an .SM HP-IB raw bus device file. .TP .SM [EIO] the interface is not currently the active controller. .TP .SM [ETIMEDOUT] a timeout occurred. .TP .SM [EACCES] The interface associated with this .I eid is locked by another process and .C O_NDELAY is set for this .I eid (see .IR io_lock (3I)). .TP .SM [EINVAL] The value specified for .I length is invalid, either less than or equal to 0 or greater than .C MAX_HPIB_COMMANDS as defined in .RC < dvio.h >. .RE .SH DEPENDENCIES .SS Series 300/400: .SM EIO is returned if a timeout occurs. .SS Series 800: If the interface is not currently the active controller, .C hpib_send_cmnd() sets .C errno to .SM [EACCES] instead of .SM [EIO]. .SH AUTHOR .C hpib_send_cmnd() was developed by HP. .SH SEE ALSO dup(2), creat(2), fcntl(2), open(2), hpib_parity_ctl(3I). .\" index@\f4hpib_send_cmnd()\fP \- send command bytes over \s-1HP-IB\s+1@@@\f3hpib_send_cmnd(3I)\f1 .\" index@\s-1HP-IB\s+1: send command bytes over \s-1HP-IB\s+1@@@\f3hpib_send_cmnd(3I)\f1 .\" index@interface, \s-1HP-IB\s+1: send command bytes over \s-1HP-IB\s+1@@@\f3hpib_send_cmnd(3I)\f1 .\" index@send command bytes over \s-1HP-IB\s+1@@@\f3hpib_send_cmnd(3I)\f1 .\" index@command bytes over \s-1HP-IB\s+1, send@@@\f3hpib_send_cmnd(3I)\f1 .\" index@bytes over \s-1HP-IB\s+1, send command@@@\f3hpib_send_cmnd(3I)\f1 .\" .\" toc@\f3hpib_send_cmnd(3I)\f1:\0\0\f4hpib_send_cmnd()\fP@@@send command bytes over \s-1HP-IB\s+1 .\" .\" fileset_database@hpib_send_c.3i PROGRAMING-MAN .\" $Header: hpib_spoll.3i,v 76.1 95/06/20 14:46:35 ssa Exp $ .TA h .TH hpib_spoll 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME hpib_spoll(\|) \- conduct a serial poll on HP-IB bus .SH SYNOPSIS .C "#include " .PP .C "int hpib_spoll(int eid, int ba);" .SH DESCRIPTION .C hpib_spoll() conducts a serial poll of the specified device. .I eid is an entity identifier of an open .SM HP-IB raw bus device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .C creat() call. .I ba is the bus address of the intended device. .PP .C hpib_spoll() Polls a single device for its response byte. The information stored in the response byte is device specific with the exception of bit 6. If bit 6 of the response byte is set, the addressed device has asserted the .SM SRQ line, and is requesting service (note that the least significant bit of the response byte is bit 0). .PP Not all devices respond to the serial poll function. Consult device documentation. Specifying a device that does not support serial polling may cause a timeout error or suspend your program indefinitely. The interface cannot serial poll itself. The interface must be the active controller. .SH RETURN VALUE If .C hpib_spoll() is successful, the device response byte is returned in the least significant byte of the return value. Otherwise, \(mi1 is returned, indicating an error. .SH ERRORS .C hpib_spoll() fails under the following circumstances, and sets .C errno (see .IR errno (2)) to the value in square brackets: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to an .SM HP-IB raw bus device file. .TP .SM [EIO] the interface is not the active controller. .TP .SM [ETIMEDOUT] the device polled did not respond before timeout. .TP .SM [EINVAL] .I ba is the address of the polling interface itself. .TP .SM [EACCES] The interface associated with this .I eid is locked by another process and .C O_NDELAY is set for this .I eid (see io_lock(3I)). .RE .SH DEPENDENCIES If the interface is not currently the active controller, .C hpib_spoll() sets .C errno to .SM [EACCES] instead of to .SM [EIO]. .SH AUTHOR .C hpib_spoll() was developed by HP. .SH SEE ALSO dup(2), creat(2), fcntl(2), open(2), hpib_rqst_srvce(3I). .\" index@\f4hpib_spoll()\fP \- conduct a serial poll on \s-1HP-IB\s+1@@@\f3hpib_spoll(3I)\f1 .\" index@\s-1HP-IB\s+1: conduct a serial poll on \s-1HP-IB\s+1@@@\f3hpib_spoll(3I)\f1 .\" index@interface, \s-1HP-IB\s+1: conduct a serial poll on \s-1HP-IB\s+1@@@\f3hpib_spoll(3I)\f1 .\" index@conduct a serial poll on \s-1HP-IB\s+1@@@\f3hpib_spoll(3I)\f1 .\" index@serial poll on \s-1HP-IB\s+1 bus, conduct a@@@\f3hpib_spoll(3I)\f1 .\" index@poll on \s-1HP-IB\s+1 bus, conduct a serial@@@\f3hpib_spoll(3I)\f1 .\" index@bus@@@see \s-1HP-IB\s+1 .\" .\" toc@\f3hpib_spoll(3I)\f1:\0\0\f4hpib_spoll()\fP@@@conduct a serial poll on \s-1HP-IB\s+1 bus .\" .\" fileset_database@hpib_spoll.3i PROGRAMING-MAN .\" $Header: hpib_status.3i,v 76.1 95/06/20 14:46:54 ssa Exp $ .TA h .TH hpib_status_wait 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME hpib_status_wait(\|) \- wait until the requested status condition becomes true .SH SYNOPSIS .C "#include " .PP .C "int hpib_status_wait(int eid, int status);" .C "#include " .SH DESCRIPTION .C hpib_status_wait() waits until a specific condition has occurred before returning. .I eid is an entity identifier of an open .SM HP-IB raw bus device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .C creat() call. .I status is an integer specifying what information is returned. The possible values for .I status and their associated meanings are: .RS .TP 30 .C WAIT_FOR_SRQ Wait until .SM SRQ line is enabled. .TP .C WAIT_FOR_CONTROL Wait until this channel is active controller. .TP .C WAIT_FOR_TALKER Wait until this channel is addressed as talker. .TP .C WAIT_FOR_LISTENER Wait until this channel is addressed as listener. .RE .PP The wait is subject to the current timeout in effect. If a timeout occurs before the desired condition occurs, the function returns with an error. .SH RETURN VALUE .C hpib_status_wait() returns zero when the condition requested becomes true. A value of \(mi1 is returned if an error occurs. A \(mi1 is also returned if a timeout occurs before the desired condition becomes true. .SH ERRORS .C hpib_status_wait() fails under the following circumstances, and sets .C errno (see .IR errno (2)) to the value in square brackets: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to an .SM HP-IB raw bus device file. .TP .SM [ETIMEDOUT] a timeout occurred. .TP .SM [EINVAL] .I status contains an invalid value. .TP .SM [EACCES] the interface associated with this .I eid is locked by another process and .C O_NDELAY is set for this .I eid (see io_lock(3I)). .RE .SH AUTHOR .C hpib_status_wait() was developed by HP. .\" index@\f4hpib_status_wait()\fP \- wait until the requested status condition becomes true@@@\f3hpib_status_wait(3I)\f1 .\" index@\s-1HP-IB\s+1: wait until the requested status condition becomes true@@@\f3hpib_status_wait(3I)\f1 .\" index@interface, \s-1HP-IB\s+1: wait until the requested status condition becomes true@@@\f3hpib_status_wait(3I)\f1 .\" index@wait until the requested status condition becomes true@@@\f3hpib_status_wait(3I)\f1 .\" index@requested status condition becomes true, wait until the@@@\f3hpib_status_wait(3I)\f1 .\" index@status condition becomes true, wait until the requested@@@\f3hpib_status_wait(3I)\f1 .\" index@condition becomes true, wait until the requested status@@@\f3hpib_status_wait(3I)\f1 .\" index@true, wait until the requested status condition becomes@@@\f3hpib_status_wait(3I)\f1 .\" .\" toc@\f3hpib_status_wait(3I)\f1:\0\0\f4hpib_status_wait()\fP@@@wait until the requested status condition becomes true .\" .\" fileset_database@hpib_status.3i PROGRAMING-MAN .\" $Header: hpib_wait_o.3i,v 76.1 95/06/20 14:47:14 ssa Exp $ .TA h .TH hpib_wait_on_ppoll 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME hpib_wait_on_ppoll(\|) \- wait until a particular parallel poll value occurs .SH SYNOPSIS .C "#include " .PP .C "int hpib_wait_on_ppoll(int eid, int mask, int sense);" .SH DESCRIPTION .C hpib_wait_on_ppoll() waits for a parallel poll response to occur on one or more lines. .I eid is an entity identifier of an open .SM HP-IB raw bus device file. .PP The .I mask argument specifies on which lines the parallel poll response is expected. The value of .I mask is treated as an eight-bit binary number where the least significant bit corresponds to line .SM DIO1; the most significant bit to .SM DIO8. For example, if you want to wait for a response on lines .SM DIO2 and .SM DIO6, the corresponding binary number is 00010010, so a hexadecimal value of 12 should be passed as the .I mask argument. .PP The .I sense argument specifies what response is expected on the selected lines. The value of .I sense is constructed in the same way as .IR mask ; eight bits for eight lines. If a bit in .I sense is set, the function returns when the line corresponding to that bit is .IR cleared . If a bit in .I sense is clear, the function returns when the corresponding line is .IR set . Using the previous example, if .I mask is 0x12 and .I sense is 00000010 (0x02 hexadecimal), the function returns when line .SM DIO5 is set, or when line .SM DIO2 is clear. .SH RETURN VALUE .C hpib_wait_on_ppoll() returns a value of \(mi1 if an error or timeout condition occurs. Upon successful completion, the function returns the response byte .SM XOR\s0-ed with the .I sense value and .SM AND\s0-ed with the .IR mask . .SH ERRORS .C hpib_wait_on_ppoll() fails and sets .C errno to indicate the error if any of the following is true: .RS .TP 15 .SM [EACCES] The interface associated with this .I eid is locked by another process and .SM .I O_NDELAY is set for this .I eid (see .IR io_lock (3I)). .TP .SM [EBADF] The .I eid argument is not a valid open entity identifier. .TP .SM [ENOTTY] The .I eid argument does not refer to an .SM HP-IB raw bus device file. .TP .SM [EINVAL] An invalid mask is received. .TP .SM [EIO] The interface is not currently the active controller. .TP .SM [ETIMEDOUT] A timeout occurred (Series 800 only). .RE .SH DEPENDENCIES If the interface is not currently the active controller, .C hpib_wait_on_ppoll() sets .C errno to .SM [EACCES] instead of to .SM [EIO]. .SH AUTHOR .C hpib_wait_on_ppoll() was developed by HP. .\" index@\f4hpib_wait_on_ppoll()\fP \- wait until a particular parallel poll value occurs@@@\f3hpib_wait_on_ppoll(3I)\f1 .\" index@\s-1HP-IB\s+1: wait until a particular parallel poll value occurs@@@\f3hpib_wait_on_ppoll(3I)\f1 .\" index@interface, \s-1HP-IB\s+1: wait until a particular parallel poll value occurs@@@\f3hpib_wait_on_ppoll(3I)\f1 .\" index@wait until a particular parallel poll value occurs@@@\f3hpib_wait_on_ppoll(3I)\f1 .\" index@particular parallel poll value occurs, wait until a@@@\f3hpib_wait_on_ppoll(3I)\f1 .\" index@parallel poll value occurs, wait until a particular@@@\f3hpib_wait_on_ppoll(3I)\f1 .\" index@poll value occurs, wait until a particular parallel@@@\f3hpib_wait_on_ppoll(3I)\f1 .\" index@value occurs, wait until a particular parallel poll@@@\f3hpib_wait_on_ppoll(3I)\f1 .\" .\" toc@\f3hpib_wait_on_ppoll(3I)\f1:\0\0\f4hpib_wait_on_ppoll()\fP@@@wait until a particular parallel poll value occurs .\" .\" fileset_database@hpib_wait_o.3i PROGRAMING-MAN .\" $Header: hppac.3x,v 74.1 95/05/10 21:48:10 ssa Exp $ .TA h .TH hppac 3X "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1HPPACADDD, HPPACCMPD, HPPACCVAD, HPPACCVBD, HPPACCVDA, HPPACCVDB, HPPACDIVD, HPPACLONGDIVD, HPPACMPYD, HPPACNSLD, HPPACSLD, HPPACSRD, HPPACSUBD\s+1 \- 3000-mode packed-decimal library .SH SYNOPSIS .C "#include " .nf .PP .C "void HPPACADDD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCMPD( .PD 0 .IP .C "unsigned char \(**operand1, .C "int op1digs, .C "unsigned char \(**operand2, .C "int op2digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVAD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVBD( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned short \(**source, .C "int sourcewords, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDA( .PD 0 .IP .C "unsigned char \(**target, .C "int targetdigs, .C "unsigned char \(**source, .C "int sign_control, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACCVDB( .PD 0 .IP .C "unsigned short \(**target, .C "unsigned char \(**source, .C "int sourcedigs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .P .C ");" .PD .PP .C "void HPPACDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACLONGDIVD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACMPYD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACNSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int \(**shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSLD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus, .C "int \(**carry" .PP .C ");" .PD .PP .C "void HPPACSRD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "int shift_amt, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .PP .C "void HPPACSUBD( .PD 0 .IP .C "unsigned char \(**operand2, .C "int op2digs, .C "unsigned char \(**operand1, .C "int op1digs, .C "enum HPPAC_CC \(**compcode, .C "int \(**pacstatus" .PP .C ");" .PD .fi .SH DESCRIPTION This set of calls invokes the library functions for emulating 3000-mode .SM (MPE V/E) packed-decimal operations. These functions are in library .C libcl which is searched when the option .C -lcl is used with .IR cc (1) or .IR ld (1). .TP 15 .C HPPACADDD() Performs packed-decimal addition. .TP .C HPPACCMPD() Compares two packed-decimal numbers. .TP .C HPPACCVAD() Converts an ASCII representation to packed-decimal. .TP .C HPPACCVBD() Converts a binary representation to packed-decimal. .TP .C HPPACCVDA() Converts a packed-decimal number to ASCII. .TP .C HPPACCVDB() Converts a packed-decimal number to binary. .TP .C HPPACDIVD() Performs packed-decimal division. .TP .C HPPACLONGDIVD() Performs packed-decimal division (alternate routine). .TP .C HPPACMPYD() Performs packed-decimal multiplication. .TP .C HPPACNSLD() Performs a packed-decimal normalizing left shift. .TP .C HPPACSLD() Performs a packed-decimal left shift. .TP .C HPPACSRD() Performs a packed-decimal right shift. .TP .C HPPACSUBD() Performs packed-decimal subtraction. .PP For all operations, the value returned in the variable to which the .IR compcode argument points is one of the following values of type .C enum .CR HPPAC_CC\s0 : .RS .TP 15 .C HPPAC_CCG Result > 0 or operand1 > operand2 .TP .C HPPAC_CCL Result < 0 or operand1 < operand2 .TP .C HPPAC_CCE Result == 0 or operand1 == operand2 .RE .PP For all operations, the value returned in the variable to which the .IR pacstatus argument points is one of the following values of type .C enum .SM .CR HPPAC_STATUS\s0 . Their meanings are intended to be obvious: .IP .C HPPAC_NO_ERROR .IP .C HPPAC_DECIMAL_OVERFLOW .IP .C HPPAC_INVALID_ASCII_DIGIT .IP .C HPPAC_INVALID_PACKED_DECIMAL_DIGIT .IP .C HPPAC_INVALID_SOURCE_WORD_COUNT .IP .C HPPAC_INVALID_DECIMAL_OPERAND_LENGTH .IP .C HPPAC_DECIMAL_DIVIDE_BY_ZERO .RE .SH AUTHOR The .SM HPPAC library was developed by HP. .SH SEE ALSO .I Compiler Library/XL Reference Manual .\" .\" index@\s-1HPPAC\(**\s+1: \s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@\s-1HP\|3000\s+1-mode packed decimal library@@@\f3hppac(3X)\f1 .\" index@packed decimal library, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@decimal library, packed, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" index@library, packed decimal, \s-1HP\|3000\s+1-mode@@@\f3hppac(3X)\f1 .\" .\" toc@\f3hppac(3X)\f1@@@Series 800 HP\|3000-mode packed decimal library .\" .\" links@hppac.3x HPPACADDD.3x .\" links@hppac.3x HPPACCMPD.3x .\" links@hppac.3x HPPACCVAD.3x .\" links@hppac.3x HPPACCVBD.3x .\" links@hppac.3x HPPACCVDA.3x .\" links@hppac.3x HPPACCVDB.3x .\" links@hppac.3x HPPACDIVD.3x .\" links@hppac.3x HPPACLONGDI.3x .\" links@hppac.3x HPPACMPYD.3x .\" links@hppac.3x HPPACNSLD.3x .\" links@hppac.3x HPPACSLD.3x .\" links@hppac.3x HPPACSRD.3x .\" links@hppac.3x HPPACSUBD.3x .\" .\" fileset_database@hppac.3x PROGRAMING-MAN .\" $Header: hsearch.3c,v 74.1 95/03/23 18:01:43 ssa Exp $ .TA h .TH hsearch 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hsearch(\|), hcreate(\|), hdestroy(\|) \- manage hash search tables .SH SYNOPSIS .C "#include " .PP .C "ENTRY *hsearch(ENTRY item, ACTION action);" .PP .C "int hcreate(unsigned nel);" .PP .C "void hdestroy(void);" .SH DESCRIPTION .C hsearch() is a hash-table search routine generalized from Knuth (6.4) Algorithm D. It returns a pointer into a hash table indicating the location at which an entry can be found. Only pointers are copied, so the calling routine must store the data (the value of the "key" must be unique). .I item is a structure of type .C ENTRY (defined in the .RC < search.h > header file) containing two pointers: .C item.key points to the comparison key, and .C item.data points to any other data to be associated with that key. (Pointers to types other than character should be cast to pointer-to-character.) .I action is a member of an enumeration type .C ACTION indicating the disposition of the entry if it cannot be found in the table. .C ENTER indicates that the item should be inserted in the table at an appropriate point. .C FIND indicates that no entry should be made. Unsuccessful resolution is indicated by the return of a .SM NULL pointer. .PP .C hcreate() allocates sufficient space for the table, and must be called before .C hsearch() is used. .I nel is an estimate of the maximum number of entries that the table will contain. This number can be adjusted upward by the algorithm in order to obtain certain mathematically favorable circumstances. .PP .C hdestroy() destroys the search table, and can be followed by another call to .CR hcreate() . .SH EXAMPLE The following example reads in strings followed by two numbers and stores them in a hash table, discarding duplicates. It then reads in strings and finds the matching entry in the hash table and prints it out. .PP .RS .nf .ift .ft 4 .ps +1 #include #include struct info { /* this is the info stored in the table */ int age, room; /* other than the key. */ }; #define NUM_EMPL 5000 /* # of elements in search table */ main( ) { /* space to store strings */ char string_space[NUM_EMPL*20]; /* space to store employee info */ struct info info_space[NUM_EMPL]; /* next avail space in string_space */ char *str_ptr = string_space; /* next avail space in info_space */ struct info *info_ptr = info_space; ENTRY item, *found_item, *hsearch( ); /* name to look for in table */ char name_to_find[30]; int i = 0; /* create table */ (void) hcreate(NUM_EMPL); while (scanf("%s%d%d", str_ptr, &info_ptr->age, &info_ptr->room) != EOF && i++ < NUM_EMPL) { /* put info in structure, and structure in item */ item.key = str_ptr; item.data = (char *)info_ptr; str_ptr += strlen(str_ptr) + 1; info_ptr++; /* put item into table */ (void) hsearch(item, ENTER); } /* access table */ item.key = name_to_find; while (scanf("%s", item.key) != EOF) { if ((found_item = hsearch(item, FIND)) != NULL) { /* if item is in the table */ (void)printf("found %s, age = %d, room = %d\en", found_item->key, ((struct info *)found_item->data)->age, ((struct info *)found_item->data)->room); } else { (void)printf("no such employee %s\en", name_to_find); } } } .ft .ps .fi .SH RETURN VALUE .C hsearch() returns a .SM NULL pointer if either the action is .SM .C FIND and the item could not be found or the action is .SM .C ENTER and the table is full. .PP .C hcreate() returns zero if it cannot allocate sufficient space for the table. .SH WARNINGS .C hsearch() and .C hcreate() use .C malloc() to allocate space (see .IR malloc (3C)). .PP Only one hash search table can be active at any given time. .PP .C hcreate() and .C hdestroy() are unsafe in multi-thread applications. .SH SEE ALSO bsearch(3C), lsearch(3C), malloc(3C), string(3C), tsearch(3C). .SH STANDARDS CONFORMANCE .CR hsearch() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR hcreate() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR hdestroy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4hcreate()\fP \- allocate space for new hash search table@@@\f3hsearch(3C)\f1 .\" index@\f4hsearch()\fP \- hash table search routine@@@\f3hsearch(3C)\f1 .\" index@\f4hdestroy()\fP \- destroy existing hash search table@@@\f3hsearch(3C)\f1 .\" index@manage hash search tables@@@\f3hsearch(3C)\f1 .\" index@hash search tables, manage@@@\f3hsearch(3C)\f1 .\" index@search tables, hash, manage@@@\f3hsearch(3C)\f1 .\" index@tables, hash search, manage@@@\f3hsearch(3C)\f1 .\" .\" toc@\f3hsearch(3C)\f1:\0\0\f4hsearch()\fP, \f4hcreate()\fP, \f4hdestroy()\fP@@@manage hash search tables .\" toc@\f4hcreate()\fP:\0\0manage hash search tables@@@see \f3hsearch(3C)\f1 .\" toc@\f4hdestroy()\fP:\0\0manage hash search tables@@@see \f3hsearch(3C)\f1 .\" .\" links@hsearch.3c hcreate.3c .\" links@hsearch.3c hdestroy.3c .\" .\" fileset_database@hsearch.3c PROGRAMING-MAN .\" $Header: byteorder.3n,v 78.1 96/03/15 15:46:29 ssa Exp $ .TA b .TH byteorder 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME htonl(\|), htons(\|), ntohl(\|), ntohs(\|) \- convert values between host and network byte order .SH SYNOPSIS .nf .PP .C #include .PP .C _XOPEN_SOURCE_EXTENDED only .C #include .PP .C "unsigned long htonl(unsigned long hostlong);" .PP .C "unsigned short htons(unsigned short hostshort);" .PP .C "unsigned long ntohl(unsigned long netlong);" .PP .C "unsigned short ntohs(unsigned short netshort);" .fi .SH DESCRIPTION These routines convert 16- and 32-bit quantities between network byte order and host byte order. On HP-UX systems, network and host byte orders are identical, so these routines are defined as null macros in the include file .RC < netinet/in.h >. If _XOPEN_SOURCE_EXTENDED is defined then these routines are defined in the include file .RC < arpa/inet.h>. .PP These routines are most often used in conjunction with Internet addresses and ports as returned by .C gethostent() and .C getservent() (see .IR gethostent (3N) and .IR getservent (3N)). Use these routines to write portable programs. .SH AUTHOR .C byteorder() was developed by the University of California, Berkeley. .SH SEE ALSO gethostent(3N), getservent(3N). .SH STANDARDS CONFORMANCE .CR byteorder() ": XPG4" .\" .\" index@\f4htonl()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4htons()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4ntohl()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4ntohs()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1values, convert between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1host and network byte order, convert values between@@@\f3byteorder(3N)\f1 .\" index@\f1network and host byte order, convert values between@@@\f3byteorder(3N)\f1 .\" index@\f1byte order, network and host, convert values between@@@\f3byteorder(3N)\f1 .\" .\" toc@\f3byteorder(3N)\f1:\0\0\f4htonl()\f1, \f4htons()\f1, \f4ntohl()\f1, \f4ntohs()\f1@@@convert values between host and network byte order .\" toc@\f4htonl()\f1, \f4htons()\f1:\0\0convert values from host to network byte order@@@see \f3byteorder(3N)\f1 .\" toc@\f4ntohl()\f1, \f4ntohs()\f1:\0\0convert values from network to host byte order@@@see \f3byteorder(3N)\f1 .\" .\" links@byteorder.3n htonl.3n .\" links@byteorder.3n htons.3n .\" links@byteorder.3n ntohl.3n .\" links@byteorder.3n ntohs.3n .\" $Header: byteorder.3n,v 78.1 96/03/15 15:46:29 ssa Exp $ .TA b .TH byteorder 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME htonl(\|), htons(\|), ntohl(\|), ntohs(\|) \- convert values between host and network byte order .SH SYNOPSIS .nf .PP .C #include .PP .C _XOPEN_SOURCE_EXTENDED only .C #include .PP .C "unsigned long htonl(unsigned long hostlong);" .PP .C "unsigned short htons(unsigned short hostshort);" .PP .C "unsigned long ntohl(unsigned long netlong);" .PP .C "unsigned short ntohs(unsigned short netshort);" .fi .SH DESCRIPTION These routines convert 16- and 32-bit quantities between network byte order and host byte order. On HP-UX systems, network and host byte orders are identical, so these routines are defined as null macros in the include file .RC < netinet/in.h >. If _XOPEN_SOURCE_EXTENDED is defined then these routines are defined in the include file .RC < arpa/inet.h>. .PP These routines are most often used in conjunction with Internet addresses and ports as returned by .C gethostent() and .C getservent() (see .IR gethostent (3N) and .IR getservent (3N)). Use these routines to write portable programs. .SH AUTHOR .C byteorder() was developed by the University of California, Berkeley. .SH SEE ALSO gethostent(3N), getservent(3N). .SH STANDARDS CONFORMANCE .CR byteorder() ": XPG4" .\" .\" index@\f4htonl()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4htons()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4ntohl()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4ntohs()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1values, convert between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1host and network byte order, convert values between@@@\f3byteorder(3N)\f1 .\" index@\f1network and host byte order, convert values between@@@\f3byteorder(3N)\f1 .\" index@\f1byte order, network and host, convert values between@@@\f3byteorder(3N)\f1 .\" .\" toc@\f3byteorder(3N)\f1:\0\0\f4htonl()\f1, \f4htons()\f1, \f4ntohl()\f1, \f4ntohs()\f1@@@convert values between host and network byte order .\" toc@\f4htonl()\f1, \f4htons()\f1:\0\0convert values from host to network byte order@@@see \f3byteorder(3N)\f1 .\" toc@\f4ntohl()\f1, \f4ntohs()\f1:\0\0convert values from network to host byte order@@@see \f3byteorder(3N)\f1 .\" .\" links@byteorder.3n htonl.3n .\" links@byteorder.3n htons.3n .\" links@byteorder.3n ntohl.3n .\" links@byteorder.3n ntohs.3n .\" $Header: hypot.3m,v 78.1 96/02/13 11:58:58 ssa Exp $ .TA h .TH hypot 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hypot(\|), cabs(\|) \- Euclidean distance function, complex absolute value .SH SYNOPSIS .C "#include " .PP .C "double hypot(double x, double y);" .PP .C "double cabs(struct {double x, y;} z);" .SH DESCRIPTION .CR hypot() and .CR cabs() return .CI sqrt( x * x\c .CI + y * y )\c , taking precautions against unwarranted overflows. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x or .I y is NaN, .CR hypot() and .CR cabs() return NaN. .PP If the correct value would overflow, .CR hypot() and .CR cabs() return .CR HUGE_VAL . .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR hypot() and .CR cabs() return zero. .SH ERRORS No errors are defined. .SH SEE ALSO sqrt(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR hypot() ": SVID3, XPG4.2" .\" .\" index@\f4hypot()\fP \- Euclidean distance function@@@\f3hypot(3M)\f1 .\" index@\f4cabs()\fP \- complex absolute value function@@@\f3hypot(3M)\f1 .\" index@math: Euclidean distance (hypotenuse) function@@@\f3hypot(3M)\f1 .\" index@math: complex absolute value function@@@\f3hypot(3M)\f1 .\" index@Euclidean distance (hypotenuse) function@@@\f3hypot(3M)\f1 .\" index@distance function, Euclidean (hypotenuse)@@@\f3hypot(3M)\f1 .\" index@complex absolute value function@@@\f3hypot(3M)\f1 .\" index@absolute value function, complex@@@\f3hypot(3M)\f1 .\" index@hypotenuse of a right triangle@@@\f3hypot(3M)\f1 .\" index@right triangle, hypotenuse of a@@@\f3hypot(3M)\f1 .\" index@triangle, right, hypotenuse of a@@@\f3hypot(3M)\f1 .\" .\" toc@\f3hypot(3M)\f1:\0\0\f4hypot()\fP, \f4cabs()\fP@@@Euclidean distance, complex absolute value function .\" toc@\f4cabs()\fP \- complex absolute value function@@@see \f3hypot(3M)\f1 .\" .\" links@hypot.3m cabs.3m .\" .\" fileset_database@hypot.3m PROGRAMING-MAN .\" $Header: iconv.3c,v 74.1 95/03/23 17:21:12 ssa Exp $ .TA i .TH iconv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iconv, iconv_open, iconv_close \- codeset conversion routines .SH SYNOPSIS .nf .C #include\0 .TP 10 .CI iconv_t\0iconv_open(const\0char\0* tocode ,\0const\0char\0* fromcode ); .TP .C size_t\0iconv( .CI "iconv_t " cd , .CI "const char **" inchar , .CI "size_t *" inbytesleft , .CI "char **" outchar , .CI "size_t *" outbytesleft .C ); .PP .CI int\0iconv_close(iconv_t\0 cd ); .SS Remarks These interfaces conform to the .SM XPG4 standard, and should be used instead of the the 9.0 .CR iconv interfaces, such as, .CR iconvopen() , .CR iconvclose() , .CR iconvsize() , .CR iconvlock() , .CR ICONV() , .CR ICONV1() , and .CR ICONV2() . .PP Please contact the support representative for the white paper entitled .IR "iconv Customization" for an understanding of the conversion process, and how .IR iconv (3C) uses tables and methods to do the conversions. This paper also shows you how to customize your own conversions. .SH DESCRIPTION .PP The entries in the .CR config.iconv file are the set of conversions that are supported by .CI iconv(3C) . The first two columns correspond to the .I fromcode and .I tocode names. These names may be directly used or their corresponding aliases may be used as parameters to .CI iconv_open() . .TP 18 .C iconv_open() Returns a conversion descriptor that describes a conversion from the codeset specified by the string pointed to by the .I fromcode argument to the codeset specified by the .I tocode argument. .IP A conversion descriptor remains valid in a process until that process closes it. .IP The .I fromcode and .I tocode arguments must have a corresponding entry in the configuration file .CR /usr/lib/nls/iconv/config.iconv . (See FILES section.) .TP .C iconv() Converts a sequence of characters from one codeset that is contained in the array specified by .IR inbuf , into a sequence of corresponding characters in another codeset, contained in the array specified by .IR outbuf . The codesets are those specified in the .C iconv_open() call that returned the conversion descriptor .IR cd . The .I inbuf argument points to a variable that points to the first character in the input buffer and .I inbytesleft indicates the number of remaining bytes in the buffer being converted. The .I outbuf argument points to a variable that points to the first available byte in the output buffer and .I outbytesleft indicates the number of the available remaining bytes in the buffer. .IP If a sequence of input bytes does not form a valid character in the specified codeset, conversion stops after the previous successfully converted character. If the input buffer ends with an incomplete character or shift sequence (see section on Special Usage), conversion stops after the previous successfully converted character. If the output buffer is not large enough to hold the entire converted output, conversion stops just prior to the character that would cause the output buffer to overflow. The variable pointed to by .I inbuf is updated to point to the byte following the last byte successfully used in the conversion. The value pointed to by .I inbyesleft is reduced to reflect the number of bytes still not converted in the input buffer. The variable pointed to by .I outbuf is updated to point to the byte following the last byte of converted output data. The value pointed to by .I outbytesleft is reduced to reflect the number of bytes still available in the output buffer. .IP If .CR iconv() encounters a character in the input buffer that is legal but for which an identical character does not exist in the target codeset, .CR iconv() maps this character to a pre-defined character, called the "galley character" that is defined at the time of table generation. (See .IR genxlt (1)). .TP 20 .C iconv_close() Deallocates the conversion descriptor .I cd and all other associated resources allocated by .CR iconv_open() . .SS Application Usage .PP Portable applications must assume that conversion descriptors are not valid after calls to any of the .C exec functions. .SS Special Usage In state-dependent encodings, the characters are interpreted depending on "state" of the input. State shifts occur when a specific sequence of bytes are seen in the input. These sequences will change the way subsequent characters are interpreted (that is, initially the characters may be single-byte characters, after a state shift, subsequent characters may be interpreted as two-byte characters). For state-dependent encodings, the conversion descriptor after .CR "iconv_open()" is in a codeset-dependent initial shift state, ready for immediate use with .CI iconv() . .PP For state-dependent encodings, the conversion descriptor .I cd is placed into its initial shift state by a call to .C iconv() for which the .I inbuf is a null pointer, or for which .I inbuf points to a null pointer. When .C iconv() is called in this way, and .I outbuf is not a null pointer or a pointer to a null pointer, and .I outbytesleft points to a positive value, .C iconv() places the byte sequence to change the output buffer to its initial shift state. If the output buffer is not large enough to hold the entire reset sequence, .C iconv() fails and sets .C errno to .CR [E2BIG] . Subsequent calls with .I inbuf set to other than a null pointer or a pointer to a null pointer cause the conversion to take place from the current state of the conversion descriptor. .PP For state-dependent encodings, the conversion descriptor is updated to reflect the shift state in effect at the end of the last successfully converted byte sequence. .SH RETURN VALUE .TP 20 .C iconv_open() Upon successful completion, .C iconv_open() returns a conversion descriptor for use on subsequent calls to .CR iconv() . Otherwise .C iconv_open() returns .RC ( iconv_t )\(mi1 and sets .C errno to indicate the error. .TP .C iconv() .C iconv() updates the variables pointed to by the arguments to reflect the extent of conversion, and returns the the number of non-identical conversions performed. If the entire string in the input buffer is converted, the value pointed to by .I inbytesleft is zero. If an error occurs, .C iconv() returns .RC ( size_t )\(mi1 and sets .C errno to indicate the error. .TP .C iconv_close() Upon successful completion, .C iconv_close() returns a value of zero. Otherwise it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C iconv_open() fails if any of the following conditions are encountered: .RS .TP 15 .SM [ENOMEM] Insufficient storage space is available. .TP .SM [EINVAL] The conversion specified by the .I fromcode and .I tocode is not supported, or the table or method specified in the configuration file could not be read or loaded correctly. This error will also occur if the configuration file itself is faulty. .RE .PP .C iconv() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EILSEQ] Input conversion stopped due to an input character that does not belong to the input codeset, or if the conversion table does not contain an entry corresponding to this input character and a galley character was not defined for that particular table. .TP .SM [E2BIG] Input conversion stopped due to lack of space in the output buffer. .TP .SM [EINVAL] Input conversion stopped due to an incomplete character or shift sequence at the end of the input buffer. .TP .SM [EBADF] The .I cd argument is not a valid open conversion descriptor. .RE .PP .C iconv_close() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EBADF] The conversion descriptor is invalid. .RE .SH EXAMPLES The following example shows how the .IR iconv (3C) interfaces maybe used for conversions. .nf .ift .ft 4 #include #include main() { .... convert("roman8", "iso88591", fd); .... } int convert(tocode, fromcode, Input) char *tocode; /* tocode name */ char *fromcode /* fromcode name */ int Input; /* input file descriptor */ { extern void error(); /* local error message */ iconv_t cd; /* conversion descriptor */ unsigned char *table; /* ptr to translation table */ int bytesread; /* num bytes read into input buffer */ unsigned char inbuf[BUFSIZ]; /* input buffer */ unsigned char *inchar; /* ptr to input character */ int inbytesleft; /* num bytes left in input buffer */ unsigned char outbuf[BUFSIZ]; /* output buffer */ unsigned char *outchar; /* ptr to output character */ int outbytesleft; /* num bytes left in output buffer */ size_t ret_val; /* number of conversions */ /* Initiate conversion -- get conversion descriptor */ if ((cd = iconv_open(tocode, fromcode)) == (iconv_t)-1) { error(FATAL, BAD_OPEN); } inbytesleft = 0; /* no. of bytes converted */ /* translate the characters */ for ( ;; ) { /* * if any bytes are leftover, they will be in the * beginning of the buffer on the next read(). */ inchar = inbuf; /* points to input buffer */ outchar = outbuf; /* points to output buffer */ outbytesleft = BUFSIZ; /* no of bytes to be converted */ if ((bytesread = read(Input, inbuf+inbytesleft, (size_t)BUFSIZ-inbytesleft)) < 0) { perror("prog"); return BAD; } if (!(inbytesleft += bytesread)) { break; /* end of conversions */ } ret_val = iconv(cd, &inchar, &inbytesleft, &outchar, &outbytesleft); if (write(1, outbuf, (size_t)BUFSIZ-outbytesleft) < 0) { perror("prog"); return BAD; } /* iconv() returns the number of non-identical conversions * performed. If the entire string in the input buffer is * converted, the value pointed to by inbytesleft will be * zero. If the conversion stopped due to any reason, the * value pointed to by inbytesleft will be non-zero and * errno is set to indicate the condition. */ if ((ret_val == -1) && (errno == EINVAL)) { /* Input conversion stopped due to an incomplete * character or shift sequence at the end of the * input buffer. */ /* Copy data left, to the start of buffer */ memcpy((char *)inbuf, (char *)inchar, (size_t)inbytesleft); } else if ((ret_val == -1) && (errno == EILSEQ)) { /* Input conversion stopped due to an input byte * that does not belong to the input codeset. */ error(FATAL, BAD_CONVERSION); } else if ((ret_val == -1) && (errno == E2BIG)) { /* Input conversion stopped due to lack of space * in the output buffer. inbytesleft has the * number of bytes to be converted. */ memcpy((char *)inbuf, (char *)inchar, (size_t)inbytesleft); } /* Go back and read from the input file. */ } /* end conversion & get rid of the conversion table */ if (iconv_close(cd) == BAD) { error(FATAL, BAD_CLOSE); } return GOOD; } .ift .ft .fi .SH WARNINGS If you use .IR iconv (3C) and compile/link your application archive, please note that .IR iconv (3C) has a dependency on .IR libdld.sl that will require a change to the compile/link command: .PP Compile : .IP .C "cc -Wl,-a,archive -Wl,-E -Wl,+n -l:libdld.sl -o " .PP or .PP Compile with .C CCOPTS and .C LDOPTS : .IP .C "export CCOPTS=""-Wl,-a,archive -Wl,-E -l:libdld.sl"" .IP .C "export LDOPTS="" -E +n -l:libdld.sl"" .IP .C "cc -o " .PP The option .IR -Wl,-a,archive is positionally dependent and should occur at the beginning of the compile line. For optimum compatibility in future releases, you should avoid using archive libc with other shared libraries except for libdld.sl as needed above. .PP There is a corner-case situation for multi-byte characters that is not correctly handled by .IR iconv (3C). If the last character in the file being converted is an invalid multi-byte character, .IR iconv (3C) returns EINVAL instead of EILSEQ. The application can get around this by checking whether EOF is reached or if this is the last buffer being converted. In this case, EINVAL should be treated as EILSEQ. .SH AUTHOR .C iconv was developed by HP. .SH FILES .TP 40 .C /usr/lib/nls/iconv/tables Directory containing tables used for conversion. .TP .C /usr/lib/nls/iconv/methods Directory containing methods used for conversion. .TP 45 .C /usr/lib/nls/iconv/config.iconv Configuration file is used by .C iconv_open() to check if the requested conversion is supported, and if so, to determine which table and/or method is used for the conversion. .SH SEE ALSO iconv(1), genxlt(1). .SH STANDARDS CONFORMANCE .nf .CR iconv_open() ": XPG4" .CR iconv() ": XPG4" .CR iconv_close() ": XPG4" .fi .\" .\" index@\f4iconv_open()\f1 \- code set conversion routine, return conversion descriptor@@@\f3iconv(3C)\f1 .\" index@\f4iconv_close()\f1 \- code set conversion routine, deallocate conversion descriptor@@@\f3iconv(3C)\f1 .\" index@\f4iconv()\f1 \- code set conversion routine, convert character@@@\f3iconv(3C)\f1 .\" index@\f1character code set, convert to another@@@\f3iconv(3C)\f1 .\" index@\f1convert character code set to another@@@\f3iconv(3C)\f1 .\" index@\f1translate character code to another code set@@@\f3iconv(3C)\f1 .\" index@\f1code set conversion, character@@@\f3iconv(3C)\f1 .\" .\" toc@\f3iconv(3C)\f1:\0\0\f4iconv()\f1, \f4iconv_open()\f1, \f4iconv_close()\f1@@@code set conversion routines .\" toc@\f4iconv()\f1:\0\0convert characters@@@\f1see \f3iconv(3C)\f1 .\" toc@\f4iconv_open()\f1:\0\0return conversion descriptor@@@\f1see \f3iconv(3C)\f1 .\" toc@\f4iconv_close()\f1:\0\0deallocate conversion descriptor@@@\f1see \f3iconv(3C)\f1 .\" .\" links@iconv.3c iconv_open.3c .\" links@iconv.3c iconv_close.3c .\" $Header: iconv.3c,v 74.1 95/03/23 17:21:12 ssa Exp $ .TA i .TH iconv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iconv, iconv_open, iconv_close \- codeset conversion routines .SH SYNOPSIS .nf .C #include\0 .TP 10 .CI iconv_t\0iconv_open(const\0char\0* tocode ,\0const\0char\0* fromcode ); .TP .C size_t\0iconv( .CI "iconv_t " cd , .CI "const char **" inchar , .CI "size_t *" inbytesleft , .CI "char **" outchar , .CI "size_t *" outbytesleft .C ); .PP .CI int\0iconv_close(iconv_t\0 cd ); .SS Remarks These interfaces conform to the .SM XPG4 standard, and should be used instead of the the 9.0 .CR iconv interfaces, such as, .CR iconvopen() , .CR iconvclose() , .CR iconvsize() , .CR iconvlock() , .CR ICONV() , .CR ICONV1() , and .CR ICONV2() . .PP Please contact the support representative for the white paper entitled .IR "iconv Customization" for an understanding of the conversion process, and how .IR iconv (3C) uses tables and methods to do the conversions. This paper also shows you how to customize your own conversions. .SH DESCRIPTION .PP The entries in the .CR config.iconv file are the set of conversions that are supported by .CI iconv(3C) . The first two columns correspond to the .I fromcode and .I tocode names. These names may be directly used or their corresponding aliases may be used as parameters to .CI iconv_open() . .TP 18 .C iconv_open() Returns a conversion descriptor that describes a conversion from the codeset specified by the string pointed to by the .I fromcode argument to the codeset specified by the .I tocode argument. .IP A conversion descriptor remains valid in a process until that process closes it. .IP The .I fromcode and .I tocode arguments must have a corresponding entry in the configuration file .CR /usr/lib/nls/iconv/config.iconv . (See FILES section.) .TP .C iconv() Converts a sequence of characters from one codeset that is contained in the array specified by .IR inbuf , into a sequence of corresponding characters in another codeset, contained in the array specified by .IR outbuf . The codesets are those specified in the .C iconv_open() call that returned the conversion descriptor .IR cd . The .I inbuf argument points to a variable that points to the first character in the input buffer and .I inbytesleft indicates the number of remaining bytes in the buffer being converted. The .I outbuf argument points to a variable that points to the first available byte in the output buffer and .I outbytesleft indicates the number of the available remaining bytes in the buffer. .IP If a sequence of input bytes does not form a valid character in the specified codeset, conversion stops after the previous successfully converted character. If the input buffer ends with an incomplete character or shift sequence (see section on Special Usage), conversion stops after the previous successfully converted character. If the output buffer is not large enough to hold the entire converted output, conversion stops just prior to the character that would cause the output buffer to overflow. The variable pointed to by .I inbuf is updated to point to the byte following the last byte successfully used in the conversion. The value pointed to by .I inbyesleft is reduced to reflect the number of bytes still not converted in the input buffer. The variable pointed to by .I outbuf is updated to point to the byte following the last byte of converted output data. The value pointed to by .I outbytesleft is reduced to reflect the number of bytes still available in the output buffer. .IP If .CR iconv() encounters a character in the input buffer that is legal but for which an identical character does not exist in the target codeset, .CR iconv() maps this character to a pre-defined character, called the "galley character" that is defined at the time of table generation. (See .IR genxlt (1)). .TP 20 .C iconv_close() Deallocates the conversion descriptor .I cd and all other associated resources allocated by .CR iconv_open() . .SS Application Usage .PP Portable applications must assume that conversion descriptors are not valid after calls to any of the .C exec functions. .SS Special Usage In state-dependent encodings, the characters are interpreted depending on "state" of the input. State shifts occur when a specific sequence of bytes are seen in the input. These sequences will change the way subsequent characters are interpreted (that is, initially the characters may be single-byte characters, after a state shift, subsequent characters may be interpreted as two-byte characters). For state-dependent encodings, the conversion descriptor after .CR "iconv_open()" is in a codeset-dependent initial shift state, ready for immediate use with .CI iconv() . .PP For state-dependent encodings, the conversion descriptor .I cd is placed into its initial shift state by a call to .C iconv() for which the .I inbuf is a null pointer, or for which .I inbuf points to a null pointer. When .C iconv() is called in this way, and .I outbuf is not a null pointer or a pointer to a null pointer, and .I outbytesleft points to a positive value, .C iconv() places the byte sequence to change the output buffer to its initial shift state. If the output buffer is not large enough to hold the entire reset sequence, .C iconv() fails and sets .C errno to .CR [E2BIG] . Subsequent calls with .I inbuf set to other than a null pointer or a pointer to a null pointer cause the conversion to take place from the current state of the conversion descriptor. .PP For state-dependent encodings, the conversion descriptor is updated to reflect the shift state in effect at the end of the last successfully converted byte sequence. .SH RETURN VALUE .TP 20 .C iconv_open() Upon successful completion, .C iconv_open() returns a conversion descriptor for use on subsequent calls to .CR iconv() . Otherwise .C iconv_open() returns .RC ( iconv_t )\(mi1 and sets .C errno to indicate the error. .TP .C iconv() .C iconv() updates the variables pointed to by the arguments to reflect the extent of conversion, and returns the the number of non-identical conversions performed. If the entire string in the input buffer is converted, the value pointed to by .I inbytesleft is zero. If an error occurs, .C iconv() returns .RC ( size_t )\(mi1 and sets .C errno to indicate the error. .TP .C iconv_close() Upon successful completion, .C iconv_close() returns a value of zero. Otherwise it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C iconv_open() fails if any of the following conditions are encountered: .RS .TP 15 .SM [ENOMEM] Insufficient storage space is available. .TP .SM [EINVAL] The conversion specified by the .I fromcode and .I tocode is not supported, or the table or method specified in the configuration file could not be read or loaded correctly. This error will also occur if the configuration file itself is faulty. .RE .PP .C iconv() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EILSEQ] Input conversion stopped due to an input character that does not belong to the input codeset, or if the conversion table does not contain an entry corresponding to this input character and a galley character was not defined for that particular table. .TP .SM [E2BIG] Input conversion stopped due to lack of space in the output buffer. .TP .SM [EINVAL] Input conversion stopped due to an incomplete character or shift sequence at the end of the input buffer. .TP .SM [EBADF] The .I cd argument is not a valid open conversion descriptor. .RE .PP .C iconv_close() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EBADF] The conversion descriptor is invalid. .RE .SH EXAMPLES The following example shows how the .IR iconv (3C) interfaces maybe used for conversions. .nf .ift .ft 4 #include #include main() { .... convert("roman8", "iso88591", fd); .... } int convert(tocode, fromcode, Input) char *tocode; /* tocode name */ char *fromcode /* fromcode name */ int Input; /* input file descriptor */ { extern void error(); /* local error message */ iconv_t cd; /* conversion descriptor */ unsigned char *table; /* ptr to translation table */ int bytesread; /* num bytes read into input buffer */ unsigned char inbuf[BUFSIZ]; /* input buffer */ unsigned char *inchar; /* ptr to input character */ int inbytesleft; /* num bytes left in input buffer */ unsigned char outbuf[BUFSIZ]; /* output buffer */ unsigned char *outchar; /* ptr to output character */ int outbytesleft; /* num bytes left in output buffer */ size_t ret_val; /* number of conversions */ /* Initiate conversion -- get conversion descriptor */ if ((cd = iconv_open(tocode, fromcode)) == (iconv_t)-1) { error(FATAL, BAD_OPEN); } inbytesleft = 0; /* no. of bytes converted */ /* translate the characters */ for ( ;; ) { /* * if any bytes are leftover, they will be in the * beginning of the buffer on the next read(). */ inchar = inbuf; /* points to input buffer */ outchar = outbuf; /* points to output buffer */ outbytesleft = BUFSIZ; /* no of bytes to be converted */ if ((bytesread = read(Input, inbuf+inbytesleft, (size_t)BUFSIZ-inbytesleft)) < 0) { perror("prog"); return BAD; } if (!(inbytesleft += bytesread)) { break; /* end of conversions */ } ret_val = iconv(cd, &inchar, &inbytesleft, &outchar, &outbytesleft); if (write(1, outbuf, (size_t)BUFSIZ-outbytesleft) < 0) { perror("prog"); return BAD; } /* iconv() returns the number of non-identical conversions * performed. If the entire string in the input buffer is * converted, the value pointed to by inbytesleft will be * zero. If the conversion stopped due to any reason, the * value pointed to by inbytesleft will be non-zero and * errno is set to indicate the condition. */ if ((ret_val == -1) && (errno == EINVAL)) { /* Input conversion stopped due to an incomplete * character or shift sequence at the end of the * input buffer. */ /* Copy data left, to the start of buffer */ memcpy((char *)inbuf, (char *)inchar, (size_t)inbytesleft); } else if ((ret_val == -1) && (errno == EILSEQ)) { /* Input conversion stopped due to an input byte * that does not belong to the input codeset. */ error(FATAL, BAD_CONVERSION); } else if ((ret_val == -1) && (errno == E2BIG)) { /* Input conversion stopped due to lack of space * in the output buffer. inbytesleft has the * number of bytes to be converted. */ memcpy((char *)inbuf, (char *)inchar, (size_t)inbytesleft); } /* Go back and read from the input file. */ } /* end conversion & get rid of the conversion table */ if (iconv_close(cd) == BAD) { error(FATAL, BAD_CLOSE); } return GOOD; } .ift .ft .fi .SH WARNINGS If you use .IR iconv (3C) and compile/link your application archive, please note that .IR iconv (3C) has a dependency on .IR libdld.sl that will require a change to the compile/link command: .PP Compile : .IP .C "cc -Wl,-a,archive -Wl,-E -Wl,+n -l:libdld.sl -o " .PP or .PP Compile with .C CCOPTS and .C LDOPTS : .IP .C "export CCOPTS=""-Wl,-a,archive -Wl,-E -l:libdld.sl"" .IP .C "export LDOPTS="" -E +n -l:libdld.sl"" .IP .C "cc -o " .PP The option .IR -Wl,-a,archive is positionally dependent and should occur at the beginning of the compile line. For optimum compatibility in future releases, you should avoid using archive libc with other shared libraries except for libdld.sl as needed above. .PP There is a corner-case situation for multi-byte characters that is not correctly handled by .IR iconv (3C). If the last character in the file being converted is an invalid multi-byte character, .IR iconv (3C) returns EINVAL instead of EILSEQ. The application can get around this by checking whether EOF is reached or if this is the last buffer being converted. In this case, EINVAL should be treated as EILSEQ. .SH AUTHOR .C iconv was developed by HP. .SH FILES .TP 40 .C /usr/lib/nls/iconv/tables Directory containing tables used for conversion. .TP .C /usr/lib/nls/iconv/methods Directory containing methods used for conversion. .TP 45 .C /usr/lib/nls/iconv/config.iconv Configuration file is used by .C iconv_open() to check if the requested conversion is supported, and if so, to determine which table and/or method is used for the conversion. .SH SEE ALSO iconv(1), genxlt(1). .SH STANDARDS CONFORMANCE .nf .CR iconv_open() ": XPG4" .CR iconv() ": XPG4" .CR iconv_close() ": XPG4" .fi .\" .\" index@\f4iconv_open()\f1 \- code set conversion routine, return conversion descriptor@@@\f3iconv(3C)\f1 .\" index@\f4iconv_close()\f1 \- code set conversion routine, deallocate conversion descriptor@@@\f3iconv(3C)\f1 .\" index@\f4iconv()\f1 \- code set conversion routine, convert character@@@\f3iconv(3C)\f1 .\" index@\f1character code set, convert to another@@@\f3iconv(3C)\f1 .\" index@\f1convert character code set to another@@@\f3iconv(3C)\f1 .\" index@\f1translate character code to another code set@@@\f3iconv(3C)\f1 .\" index@\f1code set conversion, character@@@\f3iconv(3C)\f1 .\" .\" toc@\f3iconv(3C)\f1:\0\0\f4iconv()\f1, \f4iconv_open()\f1, \f4iconv_close()\f1@@@code set conversion routines .\" toc@\f4iconv()\f1:\0\0convert characters@@@\f1see \f3iconv(3C)\f1 .\" toc@\f4iconv_open()\f1:\0\0return conversion descriptor@@@\f1see \f3iconv(3C)\f1 .\" toc@\f4iconv_close()\f1:\0\0deallocate conversion descriptor@@@\f1see \f3iconv(3C)\f1 .\" .\" links@iconv.3c iconv_open.3c .\" links@iconv.3c iconv_close.3c .\" $Header: iconv.3c,v 74.1 95/03/23 17:21:12 ssa Exp $ .TA i .TH iconv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iconv, iconv_open, iconv_close \- codeset conversion routines .SH SYNOPSIS .nf .C #include\0 .TP 10 .CI iconv_t\0iconv_open(const\0char\0* tocode ,\0const\0char\0* fromcode ); .TP .C size_t\0iconv( .CI "iconv_t " cd , .CI "const char **" inchar , .CI "size_t *" inbytesleft , .CI "char **" outchar , .CI "size_t *" outbytesleft .C ); .PP .CI int\0iconv_close(iconv_t\0 cd ); .SS Remarks These interfaces conform to the .SM XPG4 standard, and should be used instead of the the 9.0 .CR iconv interfaces, such as, .CR iconvopen() , .CR iconvclose() , .CR iconvsize() , .CR iconvlock() , .CR ICONV() , .CR ICONV1() , and .CR ICONV2() . .PP Please contact the support representative for the white paper entitled .IR "iconv Customization" for an understanding of the conversion process, and how .IR iconv (3C) uses tables and methods to do the conversions. This paper also shows you how to customize your own conversions. .SH DESCRIPTION .PP The entries in the .CR config.iconv file are the set of conversions that are supported by .CI iconv(3C) . The first two columns correspond to the .I fromcode and .I tocode names. These names may be directly used or their corresponding aliases may be used as parameters to .CI iconv_open() . .TP 18 .C iconv_open() Returns a conversion descriptor that describes a conversion from the codeset specified by the string pointed to by the .I fromcode argument to the codeset specified by the .I tocode argument. .IP A conversion descriptor remains valid in a process until that process closes it. .IP The .I fromcode and .I tocode arguments must have a corresponding entry in the configuration file .CR /usr/lib/nls/iconv/config.iconv . (See FILES section.) .TP .C iconv() Converts a sequence of characters from one codeset that is contained in the array specified by .IR inbuf , into a sequence of corresponding characters in another codeset, contained in the array specified by .IR outbuf . The codesets are those specified in the .C iconv_open() call that returned the conversion descriptor .IR cd . The .I inbuf argument points to a variable that points to the first character in the input buffer and .I inbytesleft indicates the number of remaining bytes in the buffer being converted. The .I outbuf argument points to a variable that points to the first available byte in the output buffer and .I outbytesleft indicates the number of the available remaining bytes in the buffer. .IP If a sequence of input bytes does not form a valid character in the specified codeset, conversion stops after the previous successfully converted character. If the input buffer ends with an incomplete character or shift sequence (see section on Special Usage), conversion stops after the previous successfully converted character. If the output buffer is not large enough to hold the entire converted output, conversion stops just prior to the character that would cause the output buffer to overflow. The variable pointed to by .I inbuf is updated to point to the byte following the last byte successfully used in the conversion. The value pointed to by .I inbyesleft is reduced to reflect the number of bytes still not converted in the input buffer. The variable pointed to by .I outbuf is updated to point to the byte following the last byte of converted output data. The value pointed to by .I outbytesleft is reduced to reflect the number of bytes still available in the output buffer. .IP If .CR iconv() encounters a character in the input buffer that is legal but for which an identical character does not exist in the target codeset, .CR iconv() maps this character to a pre-defined character, called the "galley character" that is defined at the time of table generation. (See .IR genxlt (1)). .TP 20 .C iconv_close() Deallocates the conversion descriptor .I cd and all other associated resources allocated by .CR iconv_open() . .SS Application Usage .PP Portable applications must assume that conversion descriptors are not valid after calls to any of the .C exec functions. .SS Special Usage In state-dependent encodings, the characters are interpreted depending on "state" of the input. State shifts occur when a specific sequence of bytes are seen in the input. These sequences will change the way subsequent characters are interpreted (that is, initially the characters may be single-byte characters, after a state shift, subsequent characters may be interpreted as two-byte characters). For state-dependent encodings, the conversion descriptor after .CR "iconv_open()" is in a codeset-dependent initial shift state, ready for immediate use with .CI iconv() . .PP For state-dependent encodings, the conversion descriptor .I cd is placed into its initial shift state by a call to .C iconv() for which the .I inbuf is a null pointer, or for which .I inbuf points to a null pointer. When .C iconv() is called in this way, and .I outbuf is not a null pointer or a pointer to a null pointer, and .I outbytesleft points to a positive value, .C iconv() places the byte sequence to change the output buffer to its initial shift state. If the output buffer is not large enough to hold the entire reset sequence, .C iconv() fails and sets .C errno to .CR [E2BIG] . Subsequent calls with .I inbuf set to other than a null pointer or a pointer to a null pointer cause the conversion to take place from the current state of the conversion descriptor. .PP For state-dependent encodings, the conversion descriptor is updated to reflect the shift state in effect at the end of the last successfully converted byte sequence. .SH RETURN VALUE .TP 20 .C iconv_open() Upon successful completion, .C iconv_open() returns a conversion descriptor for use on subsequent calls to .CR iconv() . Otherwise .C iconv_open() returns .RC ( iconv_t )\(mi1 and sets .C errno to indicate the error. .TP .C iconv() .C iconv() updates the variables pointed to by the arguments to reflect the extent of conversion, and returns the the number of non-identical conversions performed. If the entire string in the input buffer is converted, the value pointed to by .I inbytesleft is zero. If an error occurs, .C iconv() returns .RC ( size_t )\(mi1 and sets .C errno to indicate the error. .TP .C iconv_close() Upon successful completion, .C iconv_close() returns a value of zero. Otherwise it returns \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C iconv_open() fails if any of the following conditions are encountered: .RS .TP 15 .SM [ENOMEM] Insufficient storage space is available. .TP .SM [EINVAL] The conversion specified by the .I fromcode and .I tocode is not supported, or the table or method specified in the configuration file could not be read or loaded correctly. This error will also occur if the configuration file itself is faulty. .RE .PP .C iconv() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EILSEQ] Input conversion stopped due to an input character that does not belong to the input codeset, or if the conversion table does not contain an entry corresponding to this input character and a galley character was not defined for that particular table. .TP .SM [E2BIG] Input conversion stopped due to lack of space in the output buffer. .TP .SM [EINVAL] Input conversion stopped due to an incomplete character or shift sequence at the end of the input buffer. .TP .SM [EBADF] The .I cd argument is not a valid open conversion descriptor. .RE .PP .C iconv_close() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EBADF] The conversion descriptor is invalid. .RE .SH EXAMPLES The following example shows how the .IR iconv (3C) interfaces maybe used for conversions. .nf .ift .ft 4 #include #include main() { .... convert("roman8", "iso88591", fd); .... } int convert(tocode, fromcode, Input) char *tocode; /* tocode name */ char *fromcode /* fromcode name */ int Input; /* input file descriptor */ { extern void error(); /* local error message */ iconv_t cd; /* conversion descriptor */ unsigned char *table; /* ptr to translation table */ int bytesread; /* num bytes read into input buffer */ unsigned char inbuf[BUFSIZ]; /* input buffer */ unsigned char *inchar; /* ptr to input character */ int inbytesleft; /* num bytes left in input buffer */ unsigned char outbuf[BUFSIZ]; /* output buffer */ unsigned char *outchar; /* ptr to output character */ int outbytesleft; /* num bytes left in output buffer */ size_t ret_val; /* number of conversions */ /* Initiate conversion -- get conversion descriptor */ if ((cd = iconv_open(tocode, fromcode)) == (iconv_t)-1) { error(FATAL, BAD_OPEN); } inbytesleft = 0; /* no. of bytes converted */ /* translate the characters */ for ( ;; ) { /* * if any bytes are leftover, they will be in the * beginning of the buffer on the next read(). */ inchar = inbuf; /* points to input buffer */ outchar = outbuf; /* points to output buffer */ outbytesleft = BUFSIZ; /* no of bytes to be converted */ if ((bytesread = read(Input, inbuf+inbytesleft, (size_t)BUFSIZ-inbytesleft)) < 0) { perror("prog"); return BAD; } if (!(inbytesleft += bytesread)) { break; /* end of conversions */ } ret_val = iconv(cd, &inchar, &inbytesleft, &outchar, &outbytesleft); if (write(1, outbuf, (size_t)BUFSIZ-outbytesleft) < 0) { perror("prog"); return BAD; } /* iconv() returns the number of non-identical conversions * performed. If the entire string in the input buffer is * converted, the value pointed to by inbytesleft will be * zero. If the conversion stopped due to any reason, the * value pointed to by inbytesleft will be non-zero and * errno is set to indicate the condition. */ if ((ret_val == -1) && (errno == EINVAL)) { /* Input conversion stopped due to an incomplete * character or shift sequence at the end of the * input buffer. */ /* Copy data left, to the start of buffer */ memcpy((char *)inbuf, (char *)inchar, (size_t)inbytesleft); } else if ((ret_val == -1) && (errno == EILSEQ)) { /* Input conversion stopped due to an input byte * that does not belong to the input codeset. */ error(FATAL, BAD_CONVERSION); } else if ((ret_val == -1) && (errno == E2BIG)) { /* Input conversion stopped due to lack of space * in the output buffer. inbytesleft has the * number of bytes to be converted. */ memcpy((char *)inbuf, (char *)inchar, (size_t)inbytesleft); } /* Go back and read from the input file. */ } /* end conversion & get rid of the conversion table */ if (iconv_close(cd) == BAD) { error(FATAL, BAD_CLOSE); } return GOOD; } .ift .ft .fi .SH WARNINGS If you use .IR iconv (3C) and compile/link your application archive, please note that .IR iconv (3C) has a dependency on .IR libdld.sl that will require a change to the compile/link command: .PP Compile : .IP .C "cc -Wl,-a,archive -Wl,-E -Wl,+n -l:libdld.sl -o " .PP or .PP Compile with .C CCOPTS and .C LDOPTS : .IP .C "export CCOPTS=""-Wl,-a,archive -Wl,-E -l:libdld.sl"" .IP .C "export LDOPTS="" -E +n -l:libdld.sl"" .IP .C "cc -o " .PP The option .IR -Wl,-a,archive is positionally dependent and should occur at the beginning of the compile line. For optimum compatibility in future releases, you should avoid using archive libc with other shared libraries except for libdld.sl as needed above. .PP There is a corner-case situation for multi-byte characters that is not correctly handled by .IR iconv (3C). If the last character in the file being converted is an invalid multi-byte character, .IR iconv (3C) returns EINVAL instead of EILSEQ. The application can get around this by checking whether EOF is reached or if this is the last buffer being converted. In this case, EINVAL should be treated as EILSEQ. .SH AUTHOR .C iconv was developed by HP. .SH FILES .TP 40 .C /usr/lib/nls/iconv/tables Directory containing tables used for conversion. .TP .C /usr/lib/nls/iconv/methods Directory containing methods used for conversion. .TP 45 .C /usr/lib/nls/iconv/config.iconv Configuration file is used by .C iconv_open() to check if the requested conversion is supported, and if so, to determine which table and/or method is used for the conversion. .SH SEE ALSO iconv(1), genxlt(1). .SH STANDARDS CONFORMANCE .nf .CR iconv_open() ": XPG4" .CR iconv() ": XPG4" .CR iconv_close() ": XPG4" .fi .\" .\" index@\f4iconv_open()\f1 \- code set conversion routine, return conversion descriptor@@@\f3iconv(3C)\f1 .\" index@\f4iconv_close()\f1 \- code set conversion routine, deallocate conversion descriptor@@@\f3iconv(3C)\f1 .\" index@\f4iconv()\f1 \- code set conversion routine, convert character@@@\f3iconv(3C)\f1 .\" index@\f1character code set, convert to another@@@\f3iconv(3C)\f1 .\" index@\f1convert character code set to another@@@\f3iconv(3C)\f1 .\" index@\f1translate character code to another code set@@@\f3iconv(3C)\f1 .\" index@\f1code set conversion, character@@@\f3iconv(3C)\f1 .\" .\" toc@\f3iconv(3C)\f1:\0\0\f4iconv()\f1, \f4iconv_open()\f1, \f4iconv_close()\f1@@@code set conversion routines .\" toc@\f4iconv()\f1:\0\0convert characters@@@\f1see \f3iconv(3C)\f1 .\" toc@\f4iconv_open()\f1:\0\0return conversion descriptor@@@\f1see \f3iconv(3C)\f1 .\" toc@\f4iconv_close()\f1:\0\0deallocate conversion descriptor@@@\f1see \f3iconv(3C)\f1 .\" .\" links@iconv.3c iconv_open.3c .\" links@iconv.3c iconv_close.3c .\" $Header: idcok.3x,v 76.2 95/08/01 11:09:15 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH idcok 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME idcok \(em enable or disable use of hardware insert- and delete-character features .SH SYNOPSIS .C "#include " .P .C "void idcok(WINDOW *\f2win\fP, bool \f2bf\fP);" .SH DESCRIPTION The .Fn idcok function specifies whether the implementation may use hardware insert- and delete-character features in \f2win\f1 if the terminal is so equipped. If \f2bf\f1 is TRUE, use of these features in \f2win\f1 is enabled. If \f2bf\f1 is FALSE, use of these features in \f2win\f1 is disabled. The initial state is TRUE. .SH "RETURN VALUE" The .Fn idcok function does not return a value. .SH ERRORS No errors are defined. .SH "SEE ALSO" clearok(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4idcok()\f1 \- enable or disable use of hardware insert- and delete-character features@@@\f3idcok(3X)\f1 .\" index@\f1enable or disable use of hardware insert- and delete-character features@@@\f3idcok(3X)\f1 .\" index@\f1disable/enable use of hardware insert- and delete-character features@@@\f3idcok(3X)\f1 .\" index@\f1hardware insert- and delete-character features, enable or disable use of@@@\f3idcok(3X)\f1 .\" index@\f1insert- and delete-character features, hardware, enable or disable use of@@@\f3idcok(3X)\f1 .\" index@\f1delete-character features, hardware, enable or disable use of@@@\f3idcok(3X)\f1 .\" .\" toc@\f3idcok(3X)\f1:\0\0\f4idcok()\f1@@@enable or disable use of hardware insert- and delete-character features .\" .\" fileset_database@idcok.3x CURS-ENG-A-MAN .\" $Header: clearok.3x,v 76.2 95/07/31 17:25:47 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH clearok 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clearok, idlok, leaveok, scrollok, setscrreg, wsetscrreg \(em terminal output control functions .SH SYNOPSIS .C "#include " .P .C "int clearok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int idlok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int leaveok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int scrollok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int setscrreg(int \f2top\fP, int \f2bot\fP);" .P .C "int wsetscrreg(WINDOW *\f2win\fP, int \f2top\fP, int \f2bot\fP);" .SH DESCRIPTION These functions set options that deal with output within Curses. .P The .Fn clearok function assigns the value of .I bf to an internal flag in the specified window that governs clearing of the screen during a refresh. If, during a refresh operation on the specified window, the flag in .I curscr is TRUE or the flag in the specified window is TRUE, then the implementation clears the screen, redraws it in its entirety, and sets the flag to FALSE in .I curscr and in the specified window. The initial state is unspecified. .P The .Fn idlok function specifies whether the implementation may use the hardware insert-line, delete-line, and scroll features of terminals so equipped. If \f2bf\f1 is TRUE, use of these features is enabled. If \f2bf\f1 is FALSE, use of these features is disabled and lines are instead redrawn as required. The initial state is FALSE. .P The .Fn leaveok function controls the cursor position after a refresh operation. If \f2bf\f1 is TRUE, refresh operations on the specified window may leave the terminal's cursor at an arbitrary position. If \f2bf\f1 is FALSE, then at the end of any refresh operation, the terminal's cursor is positioned at the cursor position contained in the specified window. The initial state is FALSE. .P The .Fn scrollok function controls the use of scrolling. If \f2bf\f1 is TRUE, then scrolling is enabled for the specified window, with the consequences discussed in \f3Truncation, Wrapping and Scrolling\f1 in curses_intro. If \f2bf\f1 is FALSE, scrolling is disabled for the specified window. The initial state is FALSE. .P The .Fn setscrreg and .Fn wsetscrreg functions define a software scrolling region in the current or specified window. The \f2top\f1 and \f2bot\f1 arguments are the line numbers of the first and last line defining the scrolling region. (Line 0 is the top line of the window.) If this option and .Fn scrollok are enabled, an attempt to move off the last line of the margin causes all lines in the scrolling region to scroll one line in the direction of the first line. Only characters in the window are scrolled. If a software scrolling region is set and .Fn scrollok is not enabled, an attempt to move off the last line of the margin does not reposition any lines in the scrolling region. .SH "RETURN VALUE" Upon successful completion, .Fn setscrreg and .Fn wsetscrreg return OK. Otherwise, they return ERR. .P The other functions always return OK. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The only reason to enable the .Fn idlok feature is to use scrolling to achieve the visual effect of motion of a partial window, such as for a screen editor. In other cases, the feature can be visually annoying. .P The .Fn leaveok option provides greater efficiency for applications that do not use the cursor. .SH "SEE ALSO" clear(), delscreen(), doupdate(), scrl(), . .SS "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .CR idlok() , .CR leaveok() , .CR scrollok() , .Fn setscrreq and .Fn wsetscrreq functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The .B DESCRIPTION of .Fn clearok is updated to indicate that clearing of a screen applies if the flag is TRUE in either \f2curscr\f1 or the specified window. .P The .B "RETURN VALUE" is changed to indicate that the .CR clearok() , .Fn leaveok and .Fn scrollok functions always return OK. .\" .\" toc@\f3clearok(3X)\f1:\0\0\f4clearok()\f1, \f4idleok()\f1, \f4leaveok()\f1, \f4scrollok()\f1, \f4setscrreg()\f1, \f4wsetscrreg()\f1\n@@@terminal output control functions .\" toc@\f4idleok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4leaveok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4scrollok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4setscrreg()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4wsetscrreg()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" index@\f4clearok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4idleok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4leaveok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4scrollok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4setscrreg()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4wsetscrreg()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f1terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f1output, terminal, control functions@@@\f3clearok(3X)\f1 .\" index@\f1control functions, terminal output@@@\f3clearok(3X)\f1 .\" .\" links@clearok.3x idleok.3x .\" links@clearok.3x leaveok.3x .\" links@clearok.3x scrollok.3x .\" links@clearok.3x setscrreg.3x .\" links@clearok.3x wsetscrreg.3x .\" .\" fileset_database@clearok.3x CURS-ENG-A-MAN .\" $Header: ilogb.3m,v 78.1 96/02/13 12:01:46 ssa Exp $ .TA i .TH ilogb 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ilogb(\|) \- returns an unbiased exponent .SH SYNOPSIS .C "#include " .PP .C "int ilogb(double x);" .SH DESCRIPTION The .CR ilogb() function returns the exponent part of .IR x . Formally, the return value is the integral part of log base .I r of .RI | x | as a signed integral value, for nonzero .IR x , where .I r is the radix of the machine's floating point arithmetic. The argument .I x is a double-precision floating-point value. .PP Note: .CI ilogb( x ) is equivalent to .CI (int)logb( x ) for all values of .I x .ift except NaN, \(+-INFINITY, and zero. .ifn except NaN, +\-INFINITY, and zero. .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH "RETURN VALUE" If .I x is NaN, .CR ilogb() returns .CR INT_MIN . .PP If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR ilogb() returns .CR INT_MAX . .PP If .I x is zero, .CR ilogb() returns .CR INT_MIN . .SH "ERRORS" No errors are defined. .SH "SEE ALSO" scalb(3M), isinf(3M), isnan(3M), limits(5). .SH STANDARDS CONFORMANCE .CR ilogb() ": XPG4.2" .\" index@\f4ilogb()\f1 \- unbiased exponent function@@@\f3ilogb(3M)\f1 .\" index@\f1unbiased exponent function@@@\f3ilogb(3M)\f1 .\" index@\f1math: unbiased exponent function@@@\f3ilogb(3M)\f1 .\" .\" toc@\f3ilogb(3M)\f1:\0\0\f4ilogb()\f1@@@unbiased exponent function .\" .\" $Header: immedok.3x,v 76.2 95/08/01 11:10:10 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH immedok 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME immedok \(em enable or disable immediate terminal refresh .SH SYNOPSIS .C "#include " .P .C "void immedok(WINDOW *\f2win\fP, bool \f2bf\fP);" .SH DESCRIPTION The .Fn immedok function specifies whether the screen is refreshed whenever the window pointed to by win is changed. If \f2bf\f1 is TRUE, the window is implicitly refreshed on each such change. If \f2bf\f1 is FALSE, the window is not implicitly refreshed. The initial state is FALSE. .SH "RETURN VALUE" The .Fn immedok function does not return a value. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn immedok function is useful for windows that are used as terminal emulators. .SH "SEE ALSO" clearok(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4immedok()\f1 \- enable or disable immediate terminal refresh@@@\f3immedok(3X)\f1 .\" index@\f1enable or disable immediate terminal refresh@@@\f3immedok(3X)\f1 .\" index@\f1disable/enable immediate terminal refresh@@@\f3immedok(3X)\f1 .\" index@\f1immediate terminal refresh, enable/disable@@@\f3immedok(3X)\f1 .\" index@\f1terminal refresh, immediate, enable/disable@@@\f3immedok(3X)\f1 .\" .\" toc@\f3immedok(3X)\f1:\0\0\f4immedok()\f1@@@enable or disable immediate terminal refresh .\" .\" fileset_database@immedok.3x CURS-ENG-A-MAN .\" $Header: in_wch.3x,v 76.2 95/08/01 11:13:14 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH in_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME in_wch, mvin_wch, mvwin_wch, win_wch \(em input a complex character and rendition from a window .SH SYNOPSIS .C "#include " .P .C "int in_wch(cchar_t *\f2wcval\fP);" .P .C "int mvin_wch(int \f2y\fP, int \f2x\fP, cchar_t *\f2wcval\fP);" .P .C "int mvwin_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wcval\fP);" .P .C "int win_wch(WINDOW *\f2win\fP, cchar_t *\f2wcval\fP);" .SH DESCRIPTION These functions extract the complex character and rendition from the current or specified position in the current or specified window into the object pointed to by \f2wcval\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3in_wch(3X)\f1:\0\0\f4in_wch()\f1, \f4mvin_wch()\f1, \f4mvwin_wch()\f1, \f4win_wch()\f1\n@@@input a complex character and rendition from a window .\" toc@\f4mvin_wch()\f1: input a complex character and rendition from a window@@@see \f3in_wch(3X)\f1 .\" toc@\f4mvwin_wch()\f1: input a complex character and rendition from a window@@@see \f3in_wch(3X)\f1 .\" toc@\f4win_wch()\f1: input a complex character and rendition from a window@@@see \f3in_wch(3X)\f1 .\" .\" index@\f4in_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f4mvin_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f4mvwin_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f4win_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f1input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f1complex character and rendition, input from a window@@@\f3in_wch(3X)\f1 .\" index@\f1character and rendition, complex, input from a window@@@\f3in_wch(3X)\f1 .\" index@\f1window, input a complex character and rendition from@@@\f3in_wch(3X)\f1 .\" .\" links@in_wch.3x mvin_wch.3x .\" links@in_wch.3x mvwin_wch.3x .\" links@in_wch.3x win_wch.3x .\" .\" fileset_database@in_wch.3x CURS-ENG-A-MAN .\" $Header: in_wchnstr.3x,v 76.2 95/08/01 11:14:16 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH in_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME in_wchnstr, in_wchstr, mvin_wchnstr, mvin_wchstr, mvwin_wchnstr, mvwin_wchstr, win_wchnstr, win_wchstr \(em input an array of complex characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int in_wchnstr(cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int in_wchstr(cchar_t *\f2wchstr\fP);" .P .C "int mvin_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvin_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int mvwin_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvwin_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int win_wchnstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int win_wchstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP);" .SH DESCRIPTION These functions extract characters from the current or specified window, starting at the current or specified position and ending at the end of the line, and place them in the array pointed to by .I wchstr . .P The .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr and .Fn win_wchnstr fill the array with at most \f2n\f1 \f3cchar_t\f1 elements. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wchstr\f1 with .CR in_wchstr() , .CR mvin_wchstr() , .Fn mvwin_wchstr or .Fn win_wchstr causes undefined results. The use of .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr or .Fn win_wchnstr , respectively, is recommended. .SH "SEE ALSO" in_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3in_wchnstr(3X)\f1:\0\0\f4in_wchnstr()\f1, \f4in_wchstr()\f1, \f4mvin_wchnstr()\f1, \f4mvin_wchstr()\f1, \f4mvwin_wchnstr()\f1, \n\f4mvwin_wchstr()\f1, \f4win_wchnstr()\f1, \f4win_wchstr()\f1\n@@@input an array of complex characters and renditions from a window .\" toc@\f4in_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" .\" index@\f4in_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4in_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1array of complex characters and renditions, input from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1window, input an array of complex characters and renditions from@@@\f3in_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, input an array of, from a window@@@\f3in_wchnstr(3X)\f1 .\" .\" links@in_wchnstr.3x in_wchstr.3x .\" links@in_wchnstr.3x mvin_wchstr.3x .\" links@in_wchnstr.3x mvin_wchnstr.3x .\" links@in_wchnstr.3x mvwin_wchstr.3x .\" links@in_wchnstr.3x mvwin_wchnstr.3x .\" links@in_wchnstr.3x win_wchstr.3x .\" links@in_wchnstr.3x win_wchnstr.3x .\" .\" fileset_database@in_wchnstr.3x CURS-ENG-A-MAN .\" $Header: in_wchnstr.3x,v 76.2 95/08/01 11:14:16 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH in_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME in_wchnstr, in_wchstr, mvin_wchnstr, mvin_wchstr, mvwin_wchnstr, mvwin_wchstr, win_wchnstr, win_wchstr \(em input an array of complex characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int in_wchnstr(cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int in_wchstr(cchar_t *\f2wchstr\fP);" .P .C "int mvin_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvin_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int mvwin_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvwin_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int win_wchnstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int win_wchstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP);" .SH DESCRIPTION These functions extract characters from the current or specified window, starting at the current or specified position and ending at the end of the line, and place them in the array pointed to by .I wchstr . .P The .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr and .Fn win_wchnstr fill the array with at most \f2n\f1 \f3cchar_t\f1 elements. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wchstr\f1 with .CR in_wchstr() , .CR mvin_wchstr() , .Fn mvwin_wchstr or .Fn win_wchstr causes undefined results. The use of .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr or .Fn win_wchnstr , respectively, is recommended. .SH "SEE ALSO" in_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3in_wchnstr(3X)\f1:\0\0\f4in_wchnstr()\f1, \f4in_wchstr()\f1, \f4mvin_wchnstr()\f1, \f4mvin_wchstr()\f1, \f4mvwin_wchnstr()\f1, \n\f4mvwin_wchstr()\f1, \f4win_wchnstr()\f1, \f4win_wchstr()\f1\n@@@input an array of complex characters and renditions from a window .\" toc@\f4in_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" .\" index@\f4in_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4in_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1array of complex characters and renditions, input from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1window, input an array of complex characters and renditions from@@@\f3in_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, input an array of, from a window@@@\f3in_wchnstr(3X)\f1 .\" .\" links@in_wchnstr.3x in_wchstr.3x .\" links@in_wchnstr.3x mvin_wchstr.3x .\" links@in_wchnstr.3x mvin_wchnstr.3x .\" links@in_wchnstr.3x mvwin_wchstr.3x .\" links@in_wchnstr.3x mvwin_wchnstr.3x .\" links@in_wchnstr.3x win_wchstr.3x .\" links@in_wchnstr.3x win_wchnstr.3x .\" .\" fileset_database@in_wchnstr.3x CURS-ENG-A-MAN .\" $Header: inch.3x,v 76.2 95/08/01 11:18:42 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH inch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inch, mvinch, mvwinch, winch \(em input a single-byte character and rendition from a window .SH SYNOPSIS .C "#include " .P .C "chtype inch(void);" .P .C "chtype mvinch(int \f2y\fP, int \f2x\fP);" .P .C "chtype mvwinch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "chtype winch(WINDOW *\f2win\fP);" .SH DESCRIPTION These functions return the character and rendition, of type \f2chtype\f1, at the current or specified position in the current or specified window. .SH "RETURN VALUE" Upon successful completion, the functions return the specified character and rendition. Otherwise, they return (\f3chtype\fP)ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn inch function is explicitly declared as \f3void\f1. .\" .\" toc@\f3inch(3X)\f1:\0\0\f4inch()\f1, \f4mvinch()\f1, \f4mvwinch()\f1, \f4winch\f1@@@input a single-byte character and rendition from a window .\" toc@\f4mvinch()\f1: input a single-byte character and rendition from a window@@@see \f3inch(3X)\f1 .\" toc@\f4mvwinch()\f1: input a single-byte character and rendition from a window@@@see \f3inch(3X)\f1 .\" toc@\f4winch()\f1: input a single-byte character and rendition from a window@@@see \f3inch(3X)\f1 .\" .\" index@\f4inch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f4mvinch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f4mvwinch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f4winch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f1input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f1single-byte character and rendition, input from a window@@@\f3inch(3X)\f1 .\" index@\f1window, input a single-byte character and rendition from@@@\f3inch(3X)\f1 .\" index@\f1character and rendition, input a single-byte from a window@@@\f3inch(3X)\f1 .\" .\" links@inch.3x mvinch.3x .\" links@inch.3x mvwinch.3x .\" links@inch.3x winch.3x .\" .\" fileset_database@inch.3x CURS-ENG-A-MAN .\" $Header: inchnstr.3x,v 76.2 95/08/01 11:20:07 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH inchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inchnstr, inchstr, mvinchnstr, mvinchstr, mvwinchnstr, mvwinchstr, winchnstr, winchstr \(em input an array of single-byte characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int inchnstr(chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int inchstr(chtype *\f2chstr\fP);" .P .C "int mvinchnstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvinchstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int mvwinchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvwinchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int winchnstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int winchstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP);" .SH DESCRIPTION These functions place characters and renditions from the current or specified window into the array pointed to by \f2chstr\f1, starting at the current or specified position and ending at the end of the line. .P The .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr and .Fn winchnstr functions store at most \f2n\f1 elements from the current or specified window into the array pointed to by \f2chstr\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2chstr\f1 with .CR inchstr() , .CR mvinchstr() , .Fn mvwinchstr or .Fn winchstr causes undefined results. The use of .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr or .CR winchnstr() , respectively, is recommended. .SH "SEE ALSO" inch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3inchnstr(3X)\f1:\0\0\f4inchnstr()\f1, \f4inchstr()\f1, \f4mvinchnstr()\f1, \f4mvinchstr()\f1, \f4mvwinchnstr()\f1, \f4mvwinchstr()\f1, \n\f4winchnstr()\f1, \f4winchstr()\f1@@@input an array of single-byte characters and renditions from a window .\" toc@\f4inchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" .\" index@\f4inchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4inchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1array of single-byte characters and renditions, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1single-byte characters and renditions, array of, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1characters and renditions, an array of single-byte, input from a window@@@\f3inchnstr(3X)\f1 .\" .\" links@inchnstr.3x inchstr.3x .\" links@inchnstr.3x mvinchstr.3x .\" links@inchnstr.3x mvinchnstr.3x .\" links@inchnstr.3x mvwinchstr.3x .\" links@inchnstr.3x mvwinchnstr.3x .\" links@inchnstr.3x winchstr.3x .\" links@inchnstr.3x winchnstr.3x .\" .\" fileset_database@inchnstr.3x CURS-ENG-A-MAN .\" $Header: inchnstr.3x,v 76.2 95/08/01 11:20:07 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH inchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inchnstr, inchstr, mvinchnstr, mvinchstr, mvwinchnstr, mvwinchstr, winchnstr, winchstr \(em input an array of single-byte characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int inchnstr(chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int inchstr(chtype *\f2chstr\fP);" .P .C "int mvinchnstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvinchstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int mvwinchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvwinchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int winchnstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int winchstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP);" .SH DESCRIPTION These functions place characters and renditions from the current or specified window into the array pointed to by \f2chstr\f1, starting at the current or specified position and ending at the end of the line. .P The .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr and .Fn winchnstr functions store at most \f2n\f1 elements from the current or specified window into the array pointed to by \f2chstr\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2chstr\f1 with .CR inchstr() , .CR mvinchstr() , .Fn mvwinchstr or .Fn winchstr causes undefined results. The use of .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr or .CR winchnstr() , respectively, is recommended. .SH "SEE ALSO" inch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3inchnstr(3X)\f1:\0\0\f4inchnstr()\f1, \f4inchstr()\f1, \f4mvinchnstr()\f1, \f4mvinchstr()\f1, \f4mvwinchnstr()\f1, \f4mvwinchstr()\f1, \n\f4winchnstr()\f1, \f4winchstr()\f1@@@input an array of single-byte characters and renditions from a window .\" toc@\f4inchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" .\" index@\f4inchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4inchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1array of single-byte characters and renditions, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1single-byte characters and renditions, array of, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1characters and renditions, an array of single-byte, input from a window@@@\f3inchnstr(3X)\f1 .\" .\" links@inchnstr.3x inchstr.3x .\" links@inchnstr.3x mvinchstr.3x .\" links@inchnstr.3x mvinchnstr.3x .\" links@inchnstr.3x mvwinchstr.3x .\" links@inchnstr.3x mvwinchnstr.3x .\" links@inchnstr.3x winchstr.3x .\" links@inchnstr.3x winchnstr.3x .\" .\" fileset_database@inchnstr.3x CURS-ENG-A-MAN .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: inet.3n,v 72.4 94/09/19 10:13:19 ssa Exp $ .TA i .TH inet 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inet_addr(\|), inet_network(\|), inet_ntoa(\|), inet_ntoa_r(\|), inet_makeaddr(\|), inet_lnaof(\|), inet_netof(\|) \- Internet address manipulation routines .SH SYNOPSIS .nf .C #include .C #include .C #include .PP .C "unsigned long inet_addr(const char \(**cp);" .PP .C "unsigned long inet_network(const char \(**cp);" .PP .C "char \(**inet_ntoa(struct in_addr in);" .PP .C "int inet_ntoa_r(struct in_addr in, char *buffer, int buflen);" .PP .C "struct in_addr inet_makeaddr(int net, int lna);" .PP .C "unsigned long inet_lnaof(struct in_addr in);" .PP .C "unsigned long inet_netof(struct in_addr in);" .fi .SH DESCRIPTION .TP 22 .C inet_addr() .PD 0 .TP .C inet_network() .sp -2v Interpret character strings representing numbers expressed in the Internet standard ``dot'' notation. .PD .IP .C inet_addr() returns numbers suitable for use as Internet addresses. .IP .C inet_network() returns numbers suitable for use as Internet network numbers. .IP Return values can be assigned to a .C struct in_addr (defined in .CR /usr/include/netinet/in.h ) by using a technique similar to the following: .RS .nf .IP .C "struct in_addr addr;" .C "char *cp;" .IP .C "addr.s_addr = inet_addr(cp);" .fi .RE .TP .C inet_ntoa() Take an Internet address and return an .SM ASCII string representing the address in .RB `` . '' (dot) notation. .TP .C inet_ntoa_r() Identical to .CR inet_ntoa() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .TP .C inet_makeaddr() Take an Internet network number and a local network address and construct an Internet address from it. .TP .C inet_netof() Break apart Internet host addresses, returning the network number part. .TP .C inet_lnaof() Break apart Internet host addresses, returning the local network address part. .PP All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine-format integer values. Bytes in .SM HP-UX systems are ordered from left to right. .SS Internet Addresses: Values specified using dot notation take one of the following forms: .nf .IP .C a.b.c.d .C a.b.c .C a.b .C a .fi .PP When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. .PP When a three-part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three-part address format convenient for specifying Class B network addresses as in .CR 128.net.host . .PP When a two-part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right-most three bytes of the network address. This makes the two-part address format convenient for specifying Class A network addresses as in .CR net.host . .PP When only one part is given, the value is stored directly in the network address without any byte rearrangement. .PP All numbers supplied as parts in dot notation can be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; a leading 0 implies octal; otherwise, the number is interpreted as decimal). .SH RETURN VALUE .C inet_addr() and .C inet_network() return \(mi1 for malformed requests. .SH WARNINGS The string returned by .C inet_ntoa() resides in a static memory area and must be saved if needed for later use. .PP .C inet_ntoa() is unsafe for multi-thread applications. .C inet_ntoa_r() is MT-Safe and should be used instead. .SH AUTHOR These .C inet routines were developed by the University of California, Berkeley. .SH SEE ALSO gethostent(3N), getnetent(3N), hosts(4), networks(4). .\" .\" index@\f4inet_addr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_lnaof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_makeaddr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_netof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_network()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa_r()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@address manipulation routines, Internet@@@\f3inet(3N)\f1 .\" index@manipulation routines, Internet address@@@\f3inet(3N)\f1 .\" index@routines, Internet address manipulation@@@\f3inet(3N)\f1 .\" .\" toc@\f3inet(3N)\f1:\0\0\f4inet_addr()\fP, \f4inet_network()\fP, \f4inet_ntoa()\fP, \f4inet_ntoa_r()\fP, \n\f4inet_makeaddr()\fP, \f4inet_lnaof()\fP, \f4inet_netof()\fP@@@Internet address manipulation routines .\" toc@\f4inet_addr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_network()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa_r()\fP: Internet address manipulation routines@@@see \f3inet(3X)\f1 .\" toc@\f4inet_makeaddr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_lnaof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_netof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" .\" links@inet.3n inet_addr.3n .\" links@inet.3n inet_networ.3n .\" links@inet.3n inet_ntoa.3n .\" links@inet.3n inet_ntoa_r.3n .\" links@inet.3n inet_makead.3n .\" links@inet.3n inet_lnaof.3n .\" links@inet.3n inet_neto.3n .\" .\" fileset_database@inet.3n INETSVCS-MAN .\" $Header: inet.3n,v 72.4 94/09/19 10:13:19 ssa Exp $ .TA i .TH inet 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inet_addr(\|), inet_network(\|), inet_ntoa(\|), inet_ntoa_r(\|), inet_makeaddr(\|), inet_lnaof(\|), inet_netof(\|) \- Internet address manipulation routines .SH SYNOPSIS .nf .C #include .C #include .C #include .PP .C "unsigned long inet_addr(const char \(**cp);" .PP .C "unsigned long inet_network(const char \(**cp);" .PP .C "char \(**inet_ntoa(struct in_addr in);" .PP .C "int inet_ntoa_r(struct in_addr in, char *buffer, int buflen);" .PP .C "struct in_addr inet_makeaddr(int net, int lna);" .PP .C "unsigned long inet_lnaof(struct in_addr in);" .PP .C "unsigned long inet_netof(struct in_addr in);" .fi .SH DESCRIPTION .TP 22 .C inet_addr() .PD 0 .TP .C inet_network() .sp -2v Interpret character strings representing numbers expressed in the Internet standard ``dot'' notation. .PD .IP .C inet_addr() returns numbers suitable for use as Internet addresses. .IP .C inet_network() returns numbers suitable for use as Internet network numbers. .IP Return values can be assigned to a .C struct in_addr (defined in .CR /usr/include/netinet/in.h ) by using a technique similar to the following: .RS .nf .IP .C "struct in_addr addr;" .C "char *cp;" .IP .C "addr.s_addr = inet_addr(cp);" .fi .RE .TP .C inet_ntoa() Take an Internet address and return an .SM ASCII string representing the address in .RB `` . '' (dot) notation. .TP .C inet_ntoa_r() Identical to .CR inet_ntoa() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .TP .C inet_makeaddr() Take an Internet network number and a local network address and construct an Internet address from it. .TP .C inet_netof() Break apart Internet host addresses, returning the network number part. .TP .C inet_lnaof() Break apart Internet host addresses, returning the local network address part. .PP All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine-format integer values. Bytes in .SM HP-UX systems are ordered from left to right. .SS Internet Addresses: Values specified using dot notation take one of the following forms: .nf .IP .C a.b.c.d .C a.b.c .C a.b .C a .fi .PP When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. .PP When a three-part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three-part address format convenient for specifying Class B network addresses as in .CR 128.net.host . .PP When a two-part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right-most three bytes of the network address. This makes the two-part address format convenient for specifying Class A network addresses as in .CR net.host . .PP When only one part is given, the value is stored directly in the network address without any byte rearrangement. .PP All numbers supplied as parts in dot notation can be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; a leading 0 implies octal; otherwise, the number is interpreted as decimal). .SH RETURN VALUE .C inet_addr() and .C inet_network() return \(mi1 for malformed requests. .SH WARNINGS The string returned by .C inet_ntoa() resides in a static memory area and must be saved if needed for later use. .PP .C inet_ntoa() is unsafe for multi-thread applications. .C inet_ntoa_r() is MT-Safe and should be used instead. .SH AUTHOR These .C inet routines were developed by the University of California, Berkeley. .SH SEE ALSO gethostent(3N), getnetent(3N), hosts(4), networks(4). .\" .\" index@\f4inet_addr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_lnaof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_makeaddr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_netof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_network()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa_r()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@address manipulation routines, Internet@@@\f3inet(3N)\f1 .\" index@manipulation routines, Internet address@@@\f3inet(3N)\f1 .\" index@routines, Internet address manipulation@@@\f3inet(3N)\f1 .\" .\" toc@\f3inet(3N)\f1:\0\0\f4inet_addr()\fP, \f4inet_network()\fP, \f4inet_ntoa()\fP, \f4inet_ntoa_r()\fP, \n\f4inet_makeaddr()\fP, \f4inet_lnaof()\fP, \f4inet_netof()\fP@@@Internet address manipulation routines .\" toc@\f4inet_addr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_network()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa_r()\fP: Internet address manipulation routines@@@see \f3inet(3X)\f1 .\" toc@\f4inet_makeaddr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_lnaof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_netof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" .\" links@inet.3n inet_addr.3n .\" links@inet.3n inet_networ.3n .\" links@inet.3n inet_ntoa.3n .\" links@inet.3n inet_ntoa_r.3n .\" links@inet.3n inet_makead.3n .\" links@inet.3n inet_lnaof.3n .\" links@inet.3n inet_neto.3n .\" .\" fileset_database@inet.3n INETSVCS-MAN .\" $Header: inet.3n,v 72.4 94/09/19 10:13:19 ssa Exp $ .TA i .TH inet 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inet_addr(\|), inet_network(\|), inet_ntoa(\|), inet_ntoa_r(\|), inet_makeaddr(\|), inet_lnaof(\|), inet_netof(\|) \- Internet address manipulation routines .SH SYNOPSIS .nf .C #include .C #include .C #include .PP .C "unsigned long inet_addr(const char \(**cp);" .PP .C "unsigned long inet_network(const char \(**cp);" .PP .C "char \(**inet_ntoa(struct in_addr in);" .PP .C "int inet_ntoa_r(struct in_addr in, char *buffer, int buflen);" .PP .C "struct in_addr inet_makeaddr(int net, int lna);" .PP .C "unsigned long inet_lnaof(struct in_addr in);" .PP .C "unsigned long inet_netof(struct in_addr in);" .fi .SH DESCRIPTION .TP 22 .C inet_addr() .PD 0 .TP .C inet_network() .sp -2v Interpret character strings representing numbers expressed in the Internet standard ``dot'' notation. .PD .IP .C inet_addr() returns numbers suitable for use as Internet addresses. .IP .C inet_network() returns numbers suitable for use as Internet network numbers. .IP Return values can be assigned to a .C struct in_addr (defined in .CR /usr/include/netinet/in.h ) by using a technique similar to the following: .RS .nf .IP .C "struct in_addr addr;" .C "char *cp;" .IP .C "addr.s_addr = inet_addr(cp);" .fi .RE .TP .C inet_ntoa() Take an Internet address and return an .SM ASCII string representing the address in .RB `` . '' (dot) notation. .TP .C inet_ntoa_r() Identical to .CR inet_ntoa() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .TP .C inet_makeaddr() Take an Internet network number and a local network address and construct an Internet address from it. .TP .C inet_netof() Break apart Internet host addresses, returning the network number part. .TP .C inet_lnaof() Break apart Internet host addresses, returning the local network address part. .PP All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine-format integer values. Bytes in .SM HP-UX systems are ordered from left to right. .SS Internet Addresses: Values specified using dot notation take one of the following forms: .nf .IP .C a.b.c.d .C a.b.c .C a.b .C a .fi .PP When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. .PP When a three-part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three-part address format convenient for specifying Class B network addresses as in .CR 128.net.host . .PP When a two-part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right-most three bytes of the network address. This makes the two-part address format convenient for specifying Class A network addresses as in .CR net.host . .PP When only one part is given, the value is stored directly in the network address without any byte rearrangement. .PP All numbers supplied as parts in dot notation can be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; a leading 0 implies octal; otherwise, the number is interpreted as decimal). .SH RETURN VALUE .C inet_addr() and .C inet_network() return \(mi1 for malformed requests. .SH WARNINGS The string returned by .C inet_ntoa() resides in a static memory area and must be saved if needed for later use. .PP .C inet_ntoa() is unsafe for multi-thread applications. .C inet_ntoa_r() is MT-Safe and should be used instead. .SH AUTHOR These .C inet routines were developed by the University of California, Berkeley. .SH SEE ALSO gethostent(3N), getnetent(3N), hosts(4), networks(4). .\" .\" index@\f4inet_addr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_lnaof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_makeaddr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_netof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_network()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa_r()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@address manipulation routines, Internet@@@\f3inet(3N)\f1 .\" index@manipulation routines, Internet address@@@\f3inet(3N)\f1 .\" index@routines, Internet address manipulation@@@\f3inet(3N)\f1 .\" .\" toc@\f3inet(3N)\f1:\0\0\f4inet_addr()\fP, \f4inet_network()\fP, \f4inet_ntoa()\fP, \f4inet_ntoa_r()\fP, \n\f4inet_makeaddr()\fP, \f4inet_lnaof()\fP, \f4inet_netof()\fP@@@Internet address manipulation routines .\" toc@\f4inet_addr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_network()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa_r()\fP: Internet address manipulation routines@@@see \f3inet(3X)\f1 .\" toc@\f4inet_makeaddr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_lnaof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_netof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" .\" links@inet.3n inet_addr.3n .\" links@inet.3n inet_networ.3n .\" links@inet.3n inet_ntoa.3n .\" links@inet.3n inet_ntoa_r.3n .\" links@inet.3n inet_makead.3n .\" links@inet.3n inet_lnaof.3n .\" links@inet.3n inet_neto.3n .\" .\" fileset_database@inet.3n INETSVCS-MAN .\" $Header: inet.3n,v 72.4 94/09/19 10:13:19 ssa Exp $ .TA i .TH inet 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inet_addr(\|), inet_network(\|), inet_ntoa(\|), inet_ntoa_r(\|), inet_makeaddr(\|), inet_lnaof(\|), inet_netof(\|) \- Internet address manipulation routines .SH SYNOPSIS .nf .C #include .C #include .C #include .PP .C "unsigned long inet_addr(const char \(**cp);" .PP .C "unsigned long inet_network(const char \(**cp);" .PP .C "char \(**inet_ntoa(struct in_addr in);" .PP .C "int inet_ntoa_r(struct in_addr in, char *buffer, int buflen);" .PP .C "struct in_addr inet_makeaddr(int net, int lna);" .PP .C "unsigned long inet_lnaof(struct in_addr in);" .PP .C "unsigned long inet_netof(struct in_addr in);" .fi .SH DESCRIPTION .TP 22 .C inet_addr() .PD 0 .TP .C inet_network() .sp -2v Interpret character strings representing numbers expressed in the Internet standard ``dot'' notation. .PD .IP .C inet_addr() returns numbers suitable for use as Internet addresses. .IP .C inet_network() returns numbers suitable for use as Internet network numbers. .IP Return values can be assigned to a .C struct in_addr (defined in .CR /usr/include/netinet/in.h ) by using a technique similar to the following: .RS .nf .IP .C "struct in_addr addr;" .C "char *cp;" .IP .C "addr.s_addr = inet_addr(cp);" .fi .RE .TP .C inet_ntoa() Take an Internet address and return an .SM ASCII string representing the address in .RB `` . '' (dot) notation. .TP .C inet_ntoa_r() Identical to .CR inet_ntoa() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .TP .C inet_makeaddr() Take an Internet network number and a local network address and construct an Internet address from it. .TP .C inet_netof() Break apart Internet host addresses, returning the network number part. .TP .C inet_lnaof() Break apart Internet host addresses, returning the local network address part. .PP All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine-format integer values. Bytes in .SM HP-UX systems are ordered from left to right. .SS Internet Addresses: Values specified using dot notation take one of the following forms: .nf .IP .C a.b.c.d .C a.b.c .C a.b .C a .fi .PP When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. .PP When a three-part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three-part address format convenient for specifying Class B network addresses as in .CR 128.net.host . .PP When a two-part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right-most three bytes of the network address. This makes the two-part address format convenient for specifying Class A network addresses as in .CR net.host . .PP When only one part is given, the value is stored directly in the network address without any byte rearrangement. .PP All numbers supplied as parts in dot notation can be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; a leading 0 implies octal; otherwise, the number is interpreted as decimal). .SH RETURN VALUE .C inet_addr() and .C inet_network() return \(mi1 for malformed requests. .SH WARNINGS The string returned by .C inet_ntoa() resides in a static memory area and must be saved if needed for later use. .PP .C inet_ntoa() is unsafe for multi-thread applications. .C inet_ntoa_r() is MT-Safe and should be used instead. .SH AUTHOR These .C inet routines were developed by the University of California, Berkeley. .SH SEE ALSO gethostent(3N), getnetent(3N), hosts(4), networks(4). .\" .\" index@\f4inet_addr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_lnaof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_makeaddr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_netof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_network()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa_r()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@address manipulation routines, Internet@@@\f3inet(3N)\f1 .\" index@manipulation routines, Internet address@@@\f3inet(3N)\f1 .\" index@routines, Internet address manipulation@@@\f3inet(3N)\f1 .\" .\" toc@\f3inet(3N)\f1:\0\0\f4inet_addr()\fP, \f4inet_network()\fP, \f4inet_ntoa()\fP, \f4inet_ntoa_r()\fP, \n\f4inet_makeaddr()\fP, \f4inet_lnaof()\fP, \f4inet_netof()\fP@@@Internet address manipulation routines .\" toc@\f4inet_addr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_network()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa_r()\fP: Internet address manipulation routines@@@see \f3inet(3X)\f1 .\" toc@\f4inet_makeaddr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_lnaof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_netof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" .\" links@inet.3n inet_addr.3n .\" links@inet.3n inet_networ.3n .\" links@inet.3n inet_ntoa.3n .\" links@inet.3n inet_ntoa_r.3n .\" links@inet.3n inet_makead.3n .\" links@inet.3n inet_lnaof.3n .\" links@inet.3n inet_neto.3n .\" .\" fileset_database@inet.3n INETSVCS-MAN .\" $Header: inet.3n,v 72.4 94/09/19 10:13:19 ssa Exp $ .TA i .TH inet 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inet_addr(\|), inet_network(\|), inet_ntoa(\|), inet_ntoa_r(\|), inet_makeaddr(\|), inet_lnaof(\|), inet_netof(\|) \- Internet address manipulation routines .SH SYNOPSIS .nf .C #include .C #include .C #include .PP .C "unsigned long inet_addr(const char \(**cp);" .PP .C "unsigned long inet_network(const char \(**cp);" .PP .C "char \(**inet_ntoa(struct in_addr in);" .PP .C "int inet_ntoa_r(struct in_addr in, char *buffer, int buflen);" .PP .C "struct in_addr inet_makeaddr(int net, int lna);" .PP .C "unsigned long inet_lnaof(struct in_addr in);" .PP .C "unsigned long inet_netof(struct in_addr in);" .fi .SH DESCRIPTION .TP 22 .C inet_addr() .PD 0 .TP .C inet_network() .sp -2v Interpret character strings representing numbers expressed in the Internet standard ``dot'' notation. .PD .IP .C inet_addr() returns numbers suitable for use as Internet addresses. .IP .C inet_network() returns numbers suitable for use as Internet network numbers. .IP Return values can be assigned to a .C struct in_addr (defined in .CR /usr/include/netinet/in.h ) by using a technique similar to the following: .RS .nf .IP .C "struct in_addr addr;" .C "char *cp;" .IP .C "addr.s_addr = inet_addr(cp);" .fi .RE .TP .C inet_ntoa() Take an Internet address and return an .SM ASCII string representing the address in .RB `` . '' (dot) notation. .TP .C inet_ntoa_r() Identical to .CR inet_ntoa() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .TP .C inet_makeaddr() Take an Internet network number and a local network address and construct an Internet address from it. .TP .C inet_netof() Break apart Internet host addresses, returning the network number part. .TP .C inet_lnaof() Break apart Internet host addresses, returning the local network address part. .PP All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine-format integer values. Bytes in .SM HP-UX systems are ordered from left to right. .SS Internet Addresses: Values specified using dot notation take one of the following forms: .nf .IP .C a.b.c.d .C a.b.c .C a.b .C a .fi .PP When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. .PP When a three-part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three-part address format convenient for specifying Class B network addresses as in .CR 128.net.host . .PP When a two-part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right-most three bytes of the network address. This makes the two-part address format convenient for specifying Class A network addresses as in .CR net.host . .PP When only one part is given, the value is stored directly in the network address without any byte rearrangement. .PP All numbers supplied as parts in dot notation can be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; a leading 0 implies octal; otherwise, the number is interpreted as decimal). .SH RETURN VALUE .C inet_addr() and .C inet_network() return \(mi1 for malformed requests. .SH WARNINGS The string returned by .C inet_ntoa() resides in a static memory area and must be saved if needed for later use. .PP .C inet_ntoa() is unsafe for multi-thread applications. .C inet_ntoa_r() is MT-Safe and should be used instead. .SH AUTHOR These .C inet routines were developed by the University of California, Berkeley. .SH SEE ALSO gethostent(3N), getnetent(3N), hosts(4), networks(4). .\" .\" index@\f4inet_addr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_lnaof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_makeaddr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_netof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_network()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa_r()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@address manipulation routines, Internet@@@\f3inet(3N)\f1 .\" index@manipulation routines, Internet address@@@\f3inet(3N)\f1 .\" index@routines, Internet address manipulation@@@\f3inet(3N)\f1 .\" .\" toc@\f3inet(3N)\f1:\0\0\f4inet_addr()\fP, \f4inet_network()\fP, \f4inet_ntoa()\fP, \f4inet_ntoa_r()\fP, \n\f4inet_makeaddr()\fP, \f4inet_lnaof()\fP, \f4inet_netof()\fP@@@Internet address manipulation routines .\" toc@\f4inet_addr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_network()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa_r()\fP: Internet address manipulation routines@@@see \f3inet(3X)\f1 .\" toc@\f4inet_makeaddr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_lnaof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_netof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" .\" links@inet.3n inet_addr.3n .\" links@inet.3n inet_networ.3n .\" links@inet.3n inet_ntoa.3n .\" links@inet.3n inet_ntoa_r.3n .\" links@inet.3n inet_makead.3n .\" links@inet.3n inet_lnaof.3n .\" links@inet.3n inet_neto.3n .\" .\" fileset_database@inet.3n INETSVCS-MAN .\" $Header: inet.3n,v 72.4 94/09/19 10:13:19 ssa Exp $ .TA i .TH inet 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inet_addr(\|), inet_network(\|), inet_ntoa(\|), inet_ntoa_r(\|), inet_makeaddr(\|), inet_lnaof(\|), inet_netof(\|) \- Internet address manipulation routines .SH SYNOPSIS .nf .C #include .C #include .C #include .PP .C "unsigned long inet_addr(const char \(**cp);" .PP .C "unsigned long inet_network(const char \(**cp);" .PP .C "char \(**inet_ntoa(struct in_addr in);" .PP .C "int inet_ntoa_r(struct in_addr in, char *buffer, int buflen);" .PP .C "struct in_addr inet_makeaddr(int net, int lna);" .PP .C "unsigned long inet_lnaof(struct in_addr in);" .PP .C "unsigned long inet_netof(struct in_addr in);" .fi .SH DESCRIPTION .TP 22 .C inet_addr() .PD 0 .TP .C inet_network() .sp -2v Interpret character strings representing numbers expressed in the Internet standard ``dot'' notation. .PD .IP .C inet_addr() returns numbers suitable for use as Internet addresses. .IP .C inet_network() returns numbers suitable for use as Internet network numbers. .IP Return values can be assigned to a .C struct in_addr (defined in .CR /usr/include/netinet/in.h ) by using a technique similar to the following: .RS .nf .IP .C "struct in_addr addr;" .C "char *cp;" .IP .C "addr.s_addr = inet_addr(cp);" .fi .RE .TP .C inet_ntoa() Take an Internet address and return an .SM ASCII string representing the address in .RB `` . '' (dot) notation. .TP .C inet_ntoa_r() Identical to .CR inet_ntoa() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .TP .C inet_makeaddr() Take an Internet network number and a local network address and construct an Internet address from it. .TP .C inet_netof() Break apart Internet host addresses, returning the network number part. .TP .C inet_lnaof() Break apart Internet host addresses, returning the local network address part. .PP All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine-format integer values. Bytes in .SM HP-UX systems are ordered from left to right. .SS Internet Addresses: Values specified using dot notation take one of the following forms: .nf .IP .C a.b.c.d .C a.b.c .C a.b .C a .fi .PP When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. .PP When a three-part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three-part address format convenient for specifying Class B network addresses as in .CR 128.net.host . .PP When a two-part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right-most three bytes of the network address. This makes the two-part address format convenient for specifying Class A network addresses as in .CR net.host . .PP When only one part is given, the value is stored directly in the network address without any byte rearrangement. .PP All numbers supplied as parts in dot notation can be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; a leading 0 implies octal; otherwise, the number is interpreted as decimal). .SH RETURN VALUE .C inet_addr() and .C inet_network() return \(mi1 for malformed requests. .SH WARNINGS The string returned by .C inet_ntoa() resides in a static memory area and must be saved if needed for later use. .PP .C inet_ntoa() is unsafe for multi-thread applications. .C inet_ntoa_r() is MT-Safe and should be used instead. .SH AUTHOR These .C inet routines were developed by the University of California, Berkeley. .SH SEE ALSO gethostent(3N), getnetent(3N), hosts(4), networks(4). .\" .\" index@\f4inet_addr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_lnaof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_makeaddr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_netof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_network()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa_r()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@address manipulation routines, Internet@@@\f3inet(3N)\f1 .\" index@manipulation routines, Internet address@@@\f3inet(3N)\f1 .\" index@routines, Internet address manipulation@@@\f3inet(3N)\f1 .\" .\" toc@\f3inet(3N)\f1:\0\0\f4inet_addr()\fP, \f4inet_network()\fP, \f4inet_ntoa()\fP, \f4inet_ntoa_r()\fP, \n\f4inet_makeaddr()\fP, \f4inet_lnaof()\fP, \f4inet_netof()\fP@@@Internet address manipulation routines .\" toc@\f4inet_addr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_network()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa_r()\fP: Internet address manipulation routines@@@see \f3inet(3X)\f1 .\" toc@\f4inet_makeaddr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_lnaof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_netof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" .\" links@inet.3n inet_addr.3n .\" links@inet.3n inet_networ.3n .\" links@inet.3n inet_ntoa.3n .\" links@inet.3n inet_ntoa_r.3n .\" links@inet.3n inet_makead.3n .\" links@inet.3n inet_lnaof.3n .\" links@inet.3n inet_neto.3n .\" .\" fileset_database@inet.3n INETSVCS-MAN .\" $Header: inet.3n,v 72.4 94/09/19 10:13:19 ssa Exp $ .TA i .TH inet 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inet_addr(\|), inet_network(\|), inet_ntoa(\|), inet_ntoa_r(\|), inet_makeaddr(\|), inet_lnaof(\|), inet_netof(\|) \- Internet address manipulation routines .SH SYNOPSIS .nf .C #include .C #include .C #include .PP .C "unsigned long inet_addr(const char \(**cp);" .PP .C "unsigned long inet_network(const char \(**cp);" .PP .C "char \(**inet_ntoa(struct in_addr in);" .PP .C "int inet_ntoa_r(struct in_addr in, char *buffer, int buflen);" .PP .C "struct in_addr inet_makeaddr(int net, int lna);" .PP .C "unsigned long inet_lnaof(struct in_addr in);" .PP .C "unsigned long inet_netof(struct in_addr in);" .fi .SH DESCRIPTION .TP 22 .C inet_addr() .PD 0 .TP .C inet_network() .sp -2v Interpret character strings representing numbers expressed in the Internet standard ``dot'' notation. .PD .IP .C inet_addr() returns numbers suitable for use as Internet addresses. .IP .C inet_network() returns numbers suitable for use as Internet network numbers. .IP Return values can be assigned to a .C struct in_addr (defined in .CR /usr/include/netinet/in.h ) by using a technique similar to the following: .RS .nf .IP .C "struct in_addr addr;" .C "char *cp;" .IP .C "addr.s_addr = inet_addr(cp);" .fi .RE .TP .C inet_ntoa() Take an Internet address and return an .SM ASCII string representing the address in .RB `` . '' (dot) notation. .TP .C inet_ntoa_r() Identical to .CR inet_ntoa() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .TP .C inet_makeaddr() Take an Internet network number and a local network address and construct an Internet address from it. .TP .C inet_netof() Break apart Internet host addresses, returning the network number part. .TP .C inet_lnaof() Break apart Internet host addresses, returning the local network address part. .PP All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine-format integer values. Bytes in .SM HP-UX systems are ordered from left to right. .SS Internet Addresses: Values specified using dot notation take one of the following forms: .nf .IP .C a.b.c.d .C a.b.c .C a.b .C a .fi .PP When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. .PP When a three-part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three-part address format convenient for specifying Class B network addresses as in .CR 128.net.host . .PP When a two-part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right-most three bytes of the network address. This makes the two-part address format convenient for specifying Class A network addresses as in .CR net.host . .PP When only one part is given, the value is stored directly in the network address without any byte rearrangement. .PP All numbers supplied as parts in dot notation can be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; a leading 0 implies octal; otherwise, the number is interpreted as decimal). .SH RETURN VALUE .C inet_addr() and .C inet_network() return \(mi1 for malformed requests. .SH WARNINGS The string returned by .C inet_ntoa() resides in a static memory area and must be saved if needed for later use. .PP .C inet_ntoa() is unsafe for multi-thread applications. .C inet_ntoa_r() is MT-Safe and should be used instead. .SH AUTHOR These .C inet routines were developed by the University of California, Berkeley. .SH SEE ALSO gethostent(3N), getnetent(3N), hosts(4), networks(4). .\" .\" index@\f4inet_addr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_lnaof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_makeaddr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_netof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_network()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa_r()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@address manipulation routines, Internet@@@\f3inet(3N)\f1 .\" index@manipulation routines, Internet address@@@\f3inet(3N)\f1 .\" index@routines, Internet address manipulation@@@\f3inet(3N)\f1 .\" .\" toc@\f3inet(3N)\f1:\0\0\f4inet_addr()\fP, \f4inet_network()\fP, \f4inet_ntoa()\fP, \f4inet_ntoa_r()\fP, \n\f4inet_makeaddr()\fP, \f4inet_lnaof()\fP, \f4inet_netof()\fP@@@Internet address manipulation routines .\" toc@\f4inet_addr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_network()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa_r()\fP: Internet address manipulation routines@@@see \f3inet(3X)\f1 .\" toc@\f4inet_makeaddr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_lnaof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_netof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" .\" links@inet.3n inet_addr.3n .\" links@inet.3n inet_networ.3n .\" links@inet.3n inet_ntoa.3n .\" links@inet.3n inet_ntoa_r.3n .\" links@inet.3n inet_makead.3n .\" links@inet.3n inet_lnaof.3n .\" links@inet.3n inet_neto.3n .\" .\" fileset_database@inet.3n INETSVCS-MAN .\" $Header: inet.3n,v 72.4 94/09/19 10:13:19 ssa Exp $ .TA i .TH inet 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inet_addr(\|), inet_network(\|), inet_ntoa(\|), inet_ntoa_r(\|), inet_makeaddr(\|), inet_lnaof(\|), inet_netof(\|) \- Internet address manipulation routines .SH SYNOPSIS .nf .C #include .C #include .C #include .PP .C "unsigned long inet_addr(const char \(**cp);" .PP .C "unsigned long inet_network(const char \(**cp);" .PP .C "char \(**inet_ntoa(struct in_addr in);" .PP .C "int inet_ntoa_r(struct in_addr in, char *buffer, int buflen);" .PP .C "struct in_addr inet_makeaddr(int net, int lna);" .PP .C "unsigned long inet_lnaof(struct in_addr in);" .PP .C "unsigned long inet_netof(struct in_addr in);" .fi .SH DESCRIPTION .TP 22 .C inet_addr() .PD 0 .TP .C inet_network() .sp -2v Interpret character strings representing numbers expressed in the Internet standard ``dot'' notation. .PD .IP .C inet_addr() returns numbers suitable for use as Internet addresses. .IP .C inet_network() returns numbers suitable for use as Internet network numbers. .IP Return values can be assigned to a .C struct in_addr (defined in .CR /usr/include/netinet/in.h ) by using a technique similar to the following: .RS .nf .IP .C "struct in_addr addr;" .C "char *cp;" .IP .C "addr.s_addr = inet_addr(cp);" .fi .RE .TP .C inet_ntoa() Take an Internet address and return an .SM ASCII string representing the address in .RB `` . '' (dot) notation. .TP .C inet_ntoa_r() Identical to .CR inet_ntoa() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .TP .C inet_makeaddr() Take an Internet network number and a local network address and construct an Internet address from it. .TP .C inet_netof() Break apart Internet host addresses, returning the network number part. .TP .C inet_lnaof() Break apart Internet host addresses, returning the local network address part. .PP All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine-format integer values. Bytes in .SM HP-UX systems are ordered from left to right. .SS Internet Addresses: Values specified using dot notation take one of the following forms: .nf .IP .C a.b.c.d .C a.b.c .C a.b .C a .fi .PP When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. .PP When a three-part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three-part address format convenient for specifying Class B network addresses as in .CR 128.net.host . .PP When a two-part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right-most three bytes of the network address. This makes the two-part address format convenient for specifying Class A network addresses as in .CR net.host . .PP When only one part is given, the value is stored directly in the network address without any byte rearrangement. .PP All numbers supplied as parts in dot notation can be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; a leading 0 implies octal; otherwise, the number is interpreted as decimal). .SH RETURN VALUE .C inet_addr() and .C inet_network() return \(mi1 for malformed requests. .SH WARNINGS The string returned by .C inet_ntoa() resides in a static memory area and must be saved if needed for later use. .PP .C inet_ntoa() is unsafe for multi-thread applications. .C inet_ntoa_r() is MT-Safe and should be used instead. .SH AUTHOR These .C inet routines were developed by the University of California, Berkeley. .SH SEE ALSO gethostent(3N), getnetent(3N), hosts(4), networks(4). .\" .\" index@\f4inet_addr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_lnaof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_makeaddr()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_netof()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_network()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@\f4inet_ntoa_r()\fP \- Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@Internet address manipulation routines@@@\f3inet(3N)\f1 .\" index@address manipulation routines, Internet@@@\f3inet(3N)\f1 .\" index@manipulation routines, Internet address@@@\f3inet(3N)\f1 .\" index@routines, Internet address manipulation@@@\f3inet(3N)\f1 .\" .\" toc@\f3inet(3N)\f1:\0\0\f4inet_addr()\fP, \f4inet_network()\fP, \f4inet_ntoa()\fP, \f4inet_ntoa_r()\fP, \n\f4inet_makeaddr()\fP, \f4inet_lnaof()\fP, \f4inet_netof()\fP@@@Internet address manipulation routines .\" toc@\f4inet_addr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_network()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_ntoa_r()\fP: Internet address manipulation routines@@@see \f3inet(3X)\f1 .\" toc@\f4inet_makeaddr()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_lnaof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" toc@\f4inet_netof()\fP: Internet address manipulation routines@@@see \f3inet(3N)\f1 .\" .\" links@inet.3n inet_addr.3n .\" links@inet.3n inet_networ.3n .\" links@inet.3n inet_ntoa.3n .\" links@inet.3n inet_ntoa_r.3n .\" links@inet.3n inet_makead.3n .\" links@inet.3n inet_lnaof.3n .\" links@inet.3n inet_neto.3n .\" .\" fileset_database@inet.3n INETSVCS-MAN .\" $Header: can_change_color.3x,v 76.3 95/10/05 14:12:23 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH can_change_color 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME can_change_color, color_content, has_colors, init_color, init_pair, start_color, pair_content \(em color manipulation functions .SH SYNOPSIS .C "#include " .P .C "bool can_change_color(void);" .P .C "int color_content(short \f2color\fP, short *\f2red\fP, short *\f2green\fP, short *\f2blue\fP);" .P .C "int COLOR_PAIR(int \f2n\fP);" .P .C "bool has_colors(void);" .P .C "int init_color(short \f2color\fP, short \f2red\fP, short \f2green\fP, short \f2blue\fP);" .P .C "int init_pair(short \f2pair\fP, short \f2f\fP, short \f2b\fP);" .P .C "int pair_content(short \f2pair\fP, short *\f2f\fP, short *\f2b\fP);" .P .C "int PAIR_NUMBER(int \f2value\fP);" .P .C "int start_color(void);" .P .C "extern int COLOR_PAIRS;" .P .C "extern int COLORS;" .SH DESCRIPTION These functions manipulate colour on terminals that support colour. .SS "Querying Capabilities" The .Fn has_colors function indicates whether the terminal is a colour terminal. The .Fn can_change_color function indicates whether the terminal is a colour terminal on which colours can be redefined. .SS "Initialisation" The .Fn start_color function must be called in order to enable use of colours and before any colour manipulation function is called. The function initialises eight basic colours (black, blue, green, cyan, red, magenta, yellow, and white) that can be specified by the colour macros (such as COLOR_BLACK) defined in .CR . (See \f3Colour-related Macros\f1 in \f3\f1.) The initial appearance of these eight colours is not specified. .P The function also initialises two global external variables: .RS .TP 3 .C \(bu COLORS defines the number of colours that the terminal supports. (See .B "Colour Identification" below.) If COLORS is 0, the terminal does not support redefinition of colours (and .Fn can_change_colour will return FALSE). .TP .C \(bu COLOR_PAIRS defines the maximum number of colour-pairs that the terminal supports. (See .B "User-Defined Colour Pairs" below.) .RE .P The .Fn start_color function also restores the colours on the terminal to terminal-specific initial values. The initial background colour is assumed to be black for all terminals. .SS "Colour Identification" The .Fn init_color function redefines colour number \f2color\fP, on terminals that support the redefinition of colours, to have the red, green, and blue intensity components specified by \f2red\fP, \f2green\fP, and \f2blue\fP, respectively. Calling .Fn init_color also changes all occurrences of the specified colour on the screen to the new definition. .P The .Fn color_content function identifies the intensity components of colour number \f2color\f1. It stores the red, green, and blue intensity components of this colour in the addresses pointed to by \f2red\fP, \f2green\fP, and \f2blue\fP, respectively. .P For both functions, the .I color argument must be in the range from 0 to and including COLORS\|\(mi\|1. Valid intensity values range from 0 (no intensity component) up to and including 1000 (maximum intensity in that component). .SS "User-Defined Colour Pairs" Calling .Fn init_pair defines or redefines colour-pair number \f2pair\f1 to have foreground colour \f2f\f1 and background colour \f2b\f1. Calling .Fn init_pair changes any characters that were displayed in the colour pair's old definition to the new definition and refreshes the screen. .P After defining the colour pair, the macro COLOR_PAIR(\f2n\fP) returns the value of colour pair \f2n\f1. This value is the colour attribute as it would be extracted from a .CR chtype . Conversely, the macro PAIR_NUMBER(\f2value\fP) returns the colour pair number associated with the colour attribute \f2value\f1. .P The .Fn pair_content function retrieves the component colours of a colour-pair number \f2pair\f1. It stores the foreground and background colour numbers in the variables pointed to by \f2f\f1 and \f2b\fP, respectively. .P With .Fn init_pair and .Fn pair_content , the value of \f2pair\f1 must be in a range from 0 to and including COLOR_PAIRS\|\(mi\|1. (There may be an implementation-specific lower limit on the valid value of \f2pair\fP, but any such limit is at least 63.) Valid values for \f2f\f1 and \f2b\f1 are the range from 0 to and including COLORS\|\(mi\|1. .SH "RETURN VALUE" The .Fn has_colors function returns TRUE if the terminal can manipulate colors; otherwise, it returns FALSE. .P The .Fn can_change_color function returns TRUE if the terminal supports colors and can change their definitions; otherwise, it returns FALSE. .P Upon successful completion, the other functions return OK; otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" To use these functions, .Fn start_color must be called, usually right after .CR initscr() . .P The .Fn can_change_color and .Fn has_colors functions facilitate writing terminal-independent programs. For example, a programmer can use them to decide whether to use colour or some other video attribute. .P On color terminals, a typical value of COLORS is 8 and the macros such as COLOR_BLACK return a value within the range from 0 to and including 7. However, applications cannot rely on this to be true. .SH "SEE ALSO" attroff(), delscreen(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3can_change_color(3X)\f1:\0\0\f4can_change_color()\f1, \f4color_content()\f1, \f4has_colors()\f1, \f4init_color()\f1, \n\f4init_pair()\f1, \f4start_color()\f1, \f4pair_content()\f1@@@color manipulation functions .\" toc@\f4color_content()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4has_colors()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4init_colors()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4init_pair()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4start_color()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4pair_content()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" .\" index@\f4can_change_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4color_content()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4has_colors()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4init_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4init_pair()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4start_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4pair_content()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f1color manipulation functions@@@\f3can_change_color(3X)\f1 .\" .\" links@can_change_color.3x color_content.3x .\" links@can_change_color.3x has_colors.3x .\" links@can_change_color.3x init_color.3x .\" links@can_change_color.3x init_pair.3x .\" links@can_change_color.3x start_color.3x .\" links@can_change_color.3x pair_content.3x .\" .\" fileset_database@can_change_color.3x CURS-ENG-A-MAN .\" $Header: can_change_color.3x,v 76.3 95/10/05 14:12:23 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH can_change_color 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME can_change_color, color_content, has_colors, init_color, init_pair, start_color, pair_content \(em color manipulation functions .SH SYNOPSIS .C "#include " .P .C "bool can_change_color(void);" .P .C "int color_content(short \f2color\fP, short *\f2red\fP, short *\f2green\fP, short *\f2blue\fP);" .P .C "int COLOR_PAIR(int \f2n\fP);" .P .C "bool has_colors(void);" .P .C "int init_color(short \f2color\fP, short \f2red\fP, short \f2green\fP, short \f2blue\fP);" .P .C "int init_pair(short \f2pair\fP, short \f2f\fP, short \f2b\fP);" .P .C "int pair_content(short \f2pair\fP, short *\f2f\fP, short *\f2b\fP);" .P .C "int PAIR_NUMBER(int \f2value\fP);" .P .C "int start_color(void);" .P .C "extern int COLOR_PAIRS;" .P .C "extern int COLORS;" .SH DESCRIPTION These functions manipulate colour on terminals that support colour. .SS "Querying Capabilities" The .Fn has_colors function indicates whether the terminal is a colour terminal. The .Fn can_change_color function indicates whether the terminal is a colour terminal on which colours can be redefined. .SS "Initialisation" The .Fn start_color function must be called in order to enable use of colours and before any colour manipulation function is called. The function initialises eight basic colours (black, blue, green, cyan, red, magenta, yellow, and white) that can be specified by the colour macros (such as COLOR_BLACK) defined in .CR . (See \f3Colour-related Macros\f1 in \f3\f1.) The initial appearance of these eight colours is not specified. .P The function also initialises two global external variables: .RS .TP 3 .C \(bu COLORS defines the number of colours that the terminal supports. (See .B "Colour Identification" below.) If COLORS is 0, the terminal does not support redefinition of colours (and .Fn can_change_colour will return FALSE). .TP .C \(bu COLOR_PAIRS defines the maximum number of colour-pairs that the terminal supports. (See .B "User-Defined Colour Pairs" below.) .RE .P The .Fn start_color function also restores the colours on the terminal to terminal-specific initial values. The initial background colour is assumed to be black for all terminals. .SS "Colour Identification" The .Fn init_color function redefines colour number \f2color\fP, on terminals that support the redefinition of colours, to have the red, green, and blue intensity components specified by \f2red\fP, \f2green\fP, and \f2blue\fP, respectively. Calling .Fn init_color also changes all occurrences of the specified colour on the screen to the new definition. .P The .Fn color_content function identifies the intensity components of colour number \f2color\f1. It stores the red, green, and blue intensity components of this colour in the addresses pointed to by \f2red\fP, \f2green\fP, and \f2blue\fP, respectively. .P For both functions, the .I color argument must be in the range from 0 to and including COLORS\|\(mi\|1. Valid intensity values range from 0 (no intensity component) up to and including 1000 (maximum intensity in that component). .SS "User-Defined Colour Pairs" Calling .Fn init_pair defines or redefines colour-pair number \f2pair\f1 to have foreground colour \f2f\f1 and background colour \f2b\f1. Calling .Fn init_pair changes any characters that were displayed in the colour pair's old definition to the new definition and refreshes the screen. .P After defining the colour pair, the macro COLOR_PAIR(\f2n\fP) returns the value of colour pair \f2n\f1. This value is the colour attribute as it would be extracted from a .CR chtype . Conversely, the macro PAIR_NUMBER(\f2value\fP) returns the colour pair number associated with the colour attribute \f2value\f1. .P The .Fn pair_content function retrieves the component colours of a colour-pair number \f2pair\f1. It stores the foreground and background colour numbers in the variables pointed to by \f2f\f1 and \f2b\fP, respectively. .P With .Fn init_pair and .Fn pair_content , the value of \f2pair\f1 must be in a range from 0 to and including COLOR_PAIRS\|\(mi\|1. (There may be an implementation-specific lower limit on the valid value of \f2pair\fP, but any such limit is at least 63.) Valid values for \f2f\f1 and \f2b\f1 are the range from 0 to and including COLORS\|\(mi\|1. .SH "RETURN VALUE" The .Fn has_colors function returns TRUE if the terminal can manipulate colors; otherwise, it returns FALSE. .P The .Fn can_change_color function returns TRUE if the terminal supports colors and can change their definitions; otherwise, it returns FALSE. .P Upon successful completion, the other functions return OK; otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" To use these functions, .Fn start_color must be called, usually right after .CR initscr() . .P The .Fn can_change_color and .Fn has_colors functions facilitate writing terminal-independent programs. For example, a programmer can use them to decide whether to use colour or some other video attribute. .P On color terminals, a typical value of COLORS is 8 and the macros such as COLOR_BLACK return a value within the range from 0 to and including 7. However, applications cannot rely on this to be true. .SH "SEE ALSO" attroff(), delscreen(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3can_change_color(3X)\f1:\0\0\f4can_change_color()\f1, \f4color_content()\f1, \f4has_colors()\f1, \f4init_color()\f1, \n\f4init_pair()\f1, \f4start_color()\f1, \f4pair_content()\f1@@@color manipulation functions .\" toc@\f4color_content()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4has_colors()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4init_colors()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4init_pair()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4start_color()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4pair_content()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" .\" index@\f4can_change_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4color_content()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4has_colors()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4init_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4init_pair()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4start_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4pair_content()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f1color manipulation functions@@@\f3can_change_color(3X)\f1 .\" .\" links@can_change_color.3x color_content.3x .\" links@can_change_color.3x has_colors.3x .\" links@can_change_color.3x init_color.3x .\" links@can_change_color.3x init_pair.3x .\" links@can_change_color.3x start_color.3x .\" links@can_change_color.3x pair_content.3x .\" .\" fileset_database@can_change_color.3x CURS-ENG-A-MAN .\" $Header: initgroups.3c,v 72.4 94/11/15 09:55:05 ssa Exp $ .TA i .TH initgroups 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME initgroups(\|) \- initialize group access list .SH SYNOPSIS .C "#include " .PP .C "int initgroups(const char *name, gid_t basegid);" .SH DESCRIPTION .C initgroups() reads the login group file, .CR /etc/logingroup , and sets up the group access list for the user specified by .IR name , using the .IR setgroups (2) system call. If the value of .I basegid is zero or positive, it is automatically included in the groups list. Typically this value is given as the group number from the password file. If the login group file does not exist or is empty, .I basegid is the only member of the list. .SH RETURN VALUE .C initgroups() returns .C \-1 if it was not invoked by a user with appropriate privileges. .SH WARNINGS .C initgroups() uses the routines based on .IR getgrent (3C). If the invoking program uses any of these routines, the group structure is overwritten by the call to .CR initgroups() . Subsequent calls to .C initgroups() with the same .I name parameter override the actions of previous calls. .PP On many systems, no one seems to keep .C /etc/logingroup up to date. .SH NETWORKING FEATURES .SS \s-1NFS\s0 If .C /etc/logingroup is linked to .CR /etc/group , .C initgroups() tries to use the Network Information Service .SM (NIS) for entries beginning with a plus sign .RC ( + ). If group membership for .I name is managed by .SM NIS, and no .SM NIS server is able to respond, a call to .C initgroups() does not return until a server does respond. This causes commands such as .IR login (1) and .IR su (1) to wait indefinitely. .PP See .IR group (4) for proper syntax and operation. .SH AUTHOR .C initgroups() was developed by the University of California, Berkeley. .SH FILES .TP 25 .C /etc/logingroup login group file .SH SEE ALSO login(1), su(1), getgroups(2), setgroups(2), group(4). .\" index@\f4initgroups()\fP \- initialize group access list@@@\f3initgroups(3C)\f1 .\" index@initialize group access list@@@\f3initgroups(3C)\f1 .\" index@group access list: initialize group access list@@@\f3initgroups(3C)\f1 .\" index@access list, initialize group@@@\f3initgroups(3C)\f1 .\" index@list, initialize group access@@@\f3initgroups(3C)\f1 .\" .\" toc@\f3initgroups(3C)\f1:\0\0\f4initgroups()\fP@@@initialize group access list .\" .\" fileset_database@initgroups.3c PROGRAMING-MAN .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "Constraint\0initialize" "Xt \- Intrinsics Methods" .SH "Name" .Na Constraint\0initialize \- Constraint class method to initialize a child object or widget's constraint record. .Nz .XX "constraint widgets, initialize method" .XX "methods: Constraint; initialize" .SH "Synopsis" .Sy typedef void (*XtInitProc)(Widget, Widget, ArgList, Cardinal *); .As Widget \f(CIrequest\fP; Widget \f(CIinit\fP; ArgList \f(CIargs\fP; Cardinal *\f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIrequest\fP 1i Specifies the newly created child widget or object instance with its constraint record resource values set as requested by the argument list, the resource database, and the constraint defaults. .IP \f(CIinit\fP 1i Specifies the same widget or object with its constraint record fields as modified by any superclass Constraint \f(CWinitialize()\fR methods. .IP \f(CIargs\fP 1i Specifies the argument list that was passed to \f(CWXtCreateWidget()\fP. .IP \f(CInum_args\fP 1i Specifies the number of entries in the argument list. .\" .SH "Description" The Constraint \f(CWinitialize()\fP method is registered on the \f(CWinitialize\fP field of the Constraint class part structure, and is called by \f(CWXtCreateWidget()\fP when a child of the constraint widget is created. The Constraint \f(CWinitialize()\fP method performs the same sort of initializations on the constraint record of a widget that the normal (Object, RectObj, or Core) \f(CWinitialize()\fP method performs on the widget instance structure. .LP The \f(CWrequest\fP and \f(CIinit\fP arguments specify the child widget that is being created. The \f(CWconstraints\fP field of the \f(CIrequest\fP widget points to a copy of the constraint record as it was after all of the constraint resources were initialized from the argument list, the resource database, or the resource list defaults. The \f(CWconstraints\fP field of the \f(CIinit\fP widget points to the actual constraints record of the widget, and has been further initialized by the Constraint \f(CWinitialize()\fP method of any Constraint superclasses of the parent widget. All modifications should be made to the \f(CIinit\fP constraints record; the \f(CIrequest\fP argument exists so that the widget class can determine which field of the constraints record have been modified by superclass Constraint \f(CWinitialize()\fP methods. .LP The Constraint \f(CWinitialize()\fP method is chained in superclass-to-subclass order, and cannot be inherited. If nothing in the constraint structure needs initialization, the Constraint class part \f(CWinitialize\fP field should be \f(CWNULL\fP. .LP The \f(CIargs\fP and \f(CInum_args\fP arguments were added to this method in Release 4. .LP See \f(CWinitialize\fP(4) for an explanation of the things that an initialize procedure should do. See \f(CWXtCreateWidget\fP(1) for full details of the widget creation process. .\" .Nd 4 .SH "Example" The following procedure is the Constraint \f(CWinitialize()\fP method, slightly modified, of the Athena Form widget class. Note how it obtains the constraint record and the parent form widget from the supplied child widget. Note also that it provides "dynamic defaults" for two of its constraint resources: if \f(CWdx\fP or \f(CWdy\fP is equal to some default value (i.e., if it was not explicitly specified), then it will be replaced by the value of the \f(CWXtNdefaultSpacing\fP resource from the Form widget itself. .LP Note that this procedure (and most other \f(CWinitialize()\fP procedures in existence) has named its \f(CIinit\fP argument \f(CWnew\fP. "new" is a reserved word in C++, and your programs will be more portable if you avoid using it in your C code. .Ps /* ARGSUSED */ static void ConstraintInitialize(request, new, args, num_args) Widget request, new; ArgList args; Cardinal *num_args; { FormConstraints form = (FormConstraints)new->core.constraints; FormWidget fw = (FormWidget)new->core.parent; form->form.virtual_width = (int) new->core.width; form->form.virtual_height = (int) new->core.height; if (form->form.dx == default_value) form->form.dx = fw->form.default_spacing; if (form->form.dy == default_value) form->form.dy = fw->form.default_spacing; form->form.deferred_resize = False; } .Pe .SH "See Also" .na \s-1\fIXtCreateWidget\fR\s+1\*(s1, .br \s-1\fIConstraint\fR\s+1\*(s3, \s-1\fICore\fR\s+1\*(s3, .br \s-1Constraint \fIdestroy\fR\s+1\*(s4, \s-1\fIinitialize\fR\s+1\*(s4, \s-1Constraint \fIset_values\fR\s+1\*(s4. .ad .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "initialize_hook" "Xt \- Intrinsics Methods" .SH "Name" .Na initialize_hook \- obsolete Object method for initializing subpart data. .Nz .XS "methods, initialize_hook" .XS "initialize_hook method" .SH "Synopsis" .Sy typedef void (*XtArgsProc)(Widget, ArgList, Cardinal *); .As Widget \f(CIw\fP; ArgList \f(CIargs\fP; Cardinal *\f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the newly created widget. .IP \f(CIargs\fP 1i Specifies the argument list that was passed to \f(CWXtCreateWidget()\fR. .IP \f(CInum_args\fP 1i Specifies the number of arguments in the argument list. .\" .SH "Availability" Obsolete in Release 4 and later. .\" .SH "Description" The \f(CWinitialize_hook()\fP method is registered on the \f(CWinitialize_hook\fP field of the Object, RectObj, or Core class part structure, and is called by \f(CWXtCreateWidget()\fP. .LP As of Release 4, the \f(CWinitialize_hook()\fP method is obsolete because all of its arguments are now passed to the \f(CWinitialize()\fP method. Its purpose had been to allow the widget class to use the argument list to initialize fields that did not appear in the class resource list, by calling \f(CWXtSetSubvalues()\fP, for example. .LP The \f(CWinitialize_hook()\fP method is chained in superclass-to-subclass order and is called for compatibility with older widgets. It cannot be inherited and new widgets should set their \f(CWinitialize_hook\fP field to \f(CWNULL\fP. See \f(CWXtCreateWidget\fP(1) for details on when it is called. See \f(CWinitialize\fP(4) for more information on initializing subparts or other fields that do not appear in the class resource list. .\" .SH "See Also" .na \s-1\fIXtCreateWidget\fR\s+1\*(s1, \s-1\fIXtSetSubvalues\fR\s+1\*(s1, .br \s-1\fICore\fR\s+1\*(s3, .br \s-1\fIget_values_hook\fR\s+1\*(s4, \s-1\fIset_values_hook\fR\s+1\*(s4, \s-1\fIinitialize\fR\s+1\*(s4. .ad .\"last line comment .XE "methods, initialize_hook" .XE "initialize_hook method" .\" $Header: initscr.3x,v 76.2 95/08/01 11:21:16 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH initscr 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 initscr .SH NAME initscr, newterm \(em screen initialisation functions .SH SYNOPSIS .C "#include " .P .C "WINDOW *initscr(void);" .P .C "SCREEN *newterm(char *\f2type\fP, FILE *\f2outfile\fP, FILE *\f2infile\fP);" .SH DESCRIPTION The .Fn initscr function determines the terminal type and initialises all implementation data structures. The .Ev TERM environment variable specifies the terminal type. The .Fn initscr function also causes the first refresh operation to clear the screen. If errors occur, .Fn initscr writes an appropriate error message to standard error and exits. The only functions that can be called before .Fn initscr or .Fn newterm are .CR filter() , .CR ripoffline() , .CR slk_init() , .Fn use_env and the functions whose prototypes are defined in .CR . Portable applications must not call .Fn initscr twice. .P The .Fn newterm function can be called as many times as desired to attach a terminal device. The \f2type\f1 argument points to a string specifying the terminal type, except that if \f2type\f1 is a null pointer, the .Ev TERM environment variable is used. The \f2outfile\f1 and \f2infile\f1 arguments are file pointers for output to the terminal and input from the terminal, respectively. It is unspecified whether Curses modifies the buffering mode of these file pointers. The .Fn newterm function should be called once for each terminal. .P The .Fn initscr function is equivalent to: .IP newterm(getenv("TERM"), stdout, stdin); .br return stdscr; .PP If the current disposition for the signals SIGINT, SIGQUIT or SIGTSTP is SIGDFL, then .Fn initscr may also install a handler for the signal, which may remain in effect for the life of the process or until the process changes the disposition of the signal. .P The .Fn initscr and .Fn newterm functions initialise the .I cur_term external variable. .SH "RETURN VALUE" Upon successful completion, .Fn initscr returns a pointer to .I stdscr . Otherwise, it does not return. .P Upon successful completion, .Fn newterm returns a pointer to the specified terminal. Otherwise, it returns a null pointer. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" A program that outputs to more than one terminal should use .Fn newterm for each terminal instead of .Fn initscr . A program that needs an indication of error conditions, so it can continue to run in a line-oriented mode if the terminal cannot support a screen-oriented program, would also use this function. .P Applications should perform any required handling of the SIGINT, SIGQUIT or SIGTSTP signals before calling .CR initscr() . .SH "SEE ALSO" \f3Selecting a Terminal\f1 in terminfo(4), delscreen(), doupdate(), del_curterm(), filter(), slk_attroff(), use_env(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn newterm function is merged with this entry. In previous issues, it appeared in an entry of its own. .P The entry is rewritten for clarity. The argument list for the .Fn initscr function is explicitly declared as \f3void\f1. .\" .\" toc@\f3initscr(3X)\f1:\0\0\f4initscr()\f1, \f4newterm()\f1@@@screen initialisation functions .\" toc@\f4newterm()\f1: screen initialisation functions@@@see \f3initscr(3X)\f1 .\" .\" index@\f4initscr()\f1 \- screen initialisation functions@@@\f3initscr(3X)\f1 .\" index@\f4newterm()\f1 \- screen initialisation functions@@@\f3initscr(3X)\f1 .\" index@\f1screen initialisation functions@@@\f3initscr(3X)\f1 .\" index@\f1initialisation functions for screen@@@\f3initscr(3X)\f1 .\" index@\f1functions, screen initialisation functions@@@\f3initscr(3X)\f1 .\" .\" links@initscr.3x newterm.3x .\" .\" fileset_database@initscr.3x CURS-ENG-A-MAN .\" $Header: random.3m,v 76.2 95/07/10 17:17:13 ssa Exp $ .TA r .TH random 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME random(\|), srandom(\|), initstate(\|), setstate(\|) \- generate a pseudorandom number .SH SYNOPSIS .C "#include " .PP .C "long random(void);" .PP .C "void srandom(unsigned seed);" .PP .C "char *initstate(unsigned seed, char *state, size_t size);" .PP .C "char *setstate(char *state);" .fi .ft 1 .SH DESCRIPTION The .CR random() and .CR srandom() functions are random-number generators that have virtually the same calling sequence and initialization properties as the .CR rand() and .CR srand() functions, but produce sequences that are more random. The low 12 bits generated by the .CR rand() function go through a cyclic pattern, while all the bits generated by the .CR random() function are usable. For example, .C "random() & 01" produces a random binary value. .PP The .CR random() function uses a nonlinear additive feedback random-number generator employing a default state array size of 31 long integers to return successive pseudorandom numbers in the range from 0 to .ift 2\u\s-231\s0\d-1. .ifn (2^31 - 1). The period of this random-number generator is approximately 16 x .ift (2\s-2\u31\d\s0-\f11). .ifn (2^31 - 1). The size of the state array determines the period of the random-number generator. Increasing the state array size increases the period. .PP With 256 bytes of state information, the period of the random-number generator is greater than .ift 2\s-2\u69\s0\d. .ifn 2^69. .PP Like the .CR rand() function, the .CR random() function produces by default a sequence of numbers that can be duplicated by calling the .CR srandom() function with a value of 1 as the seed. .P The .CR srandom() function initializes the current state array using the value of .IR seed . .PP The .CR initstate() and .CR setstate() functions handle restarting and changing random-number generators. The .CR initstate() function allows a state array, pointed to by the .I state argument, to be initialized for future use. The .I size argument, which specifies the size in bytes of the state array, is used by the .CR initstate() function to decide how sophisticated a random-number generator to use; the larger the state array, the more random the numbers. Values for the amount of state information are 8, 32, 64, 128, and 256 bytes. Amounts less than 8 bytes generate an error, while other amounts are rounded down to the nearest known value. The .I seed argument specifies a starting point for the random-number sequence and provides for restarting at the same point. The .CR initstate() function returns a pointer to the previous state information array. .PP Once a state has been initialized, the .CR setstate() function allows switching between state arrays. The array defined by the .I state argument is used for further random-number generation until the .CR initstate() function is called or the .CR setstate() function is called again. The .CR setstate() function returns a pointer to the previous state array. .PP After initialization, a state array can be restarted at a different point in one of two ways: .PP .RS The .CR initstate() function can be used, with the desired seed, state array, and size of the array. .PP The .CR setstate() function, with the desired state, can be used, followed by the .CR srandom() function with the desired seed. The advantage of using both of these functions is that the size of the state array does not have to be saved once it is initialized. .PP .RE .SH RETURN VALUE The .CR random() function returns the generated pseudorandom number. .PP The .CR srandom() function returns no value. .PP Upon successful completion, the .CR initstate() and .CR setstate() functions return a pointer to the previous state array. Otherwise, a NULL pointer is returned. .SH ERRORS If the .CR initstate() function is called with .I size less than 8, or if the .CR setstate() function detects that the state information has been damaged, error messages are written to standard error. .SH SEE ALSO .PP drand48(3C), rand(3C). .SH STANDARDS COMPLIANCE .CR random() "COSE API, XPG 4.2" .br .CR srandom() "COSE API, XPG 4.2" .br .CR initstate() "COSE API, XPG 4.2" .br .CR setstate() "COSE API, XPG 4.2" .\" .\" index@\f4random()\f1, \f4srandom()\f1, \f4initstate()\f1, \f4setstate()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f4srandom()\f1, \f4initstate()\f1, \f4setstate()\f1, \f4random()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f4initstate()\f1, \f4setstate()\f1, \f4random()\f1, \f4srandom()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f4setstate()\f1, \f4random()\f1, \f4srandom()\f1, \f4initstate()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f1math: pseudorandom number generation functions@@@\f3random(3M)\f1 .\" index@\f1pseudorandom number generation functions@@@\f3random(3M)\f1 .\" index@\f1random number generation functions@@@\f3random(3M)\f1 .\" .\" toc@\f3random(3M)\f1:\0\0\f4random()\f1, \f4srandom()\f1, \f4initstate()\f1, \f4setstate()\f1@@@generate a pseudorandom number .\" toc@\f4random()\f1:\0\0pseudorandom number generation functions@@@see \f3random(3M)\f1 .\" toc@\f4srandom()\f1:\0\0pseudorandom number generation functions@@@see \f3random(3M)\f1 .\" toc@\f4initstate()\f1:\0\0pseudorandom number functions@@@see \f3random(3M)\f1 .\" toc@\f4setstate()\f1:\0\0pseudorandom number functions@@@see \f3random(3M)\f1 .\" .\" links@random.3m srandom.3m .\" links@random.3m initstate.3m .\" links@random.3m setstate.3m .\" .\" fileset_database@random.3m PROGRAMING-MAN .\" $Header: getnetgrent.3c,v 76.2 95/05/26 17:06:46 ssa Exp $ .TA g .TH getnetgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnetgrent(\|), setnetgrent(\|), endnetgrent(\|), innetgr(\|), getnetgrent_r(\|), setnetgrent_r(\|), endnetgrent_r(\|) \- get network group entry .SH SYNOPSIS .nf .C int innetgr( .C " char *netgroup, " .C " char *machine, " .C " char *user, " .C " char *domain" .C ); .PP .C int setnetgrent(char *netgroup); .PP .C int setnetgrent_r( .C " char *grp," .C " char **ngstate" .C ); .PP .C int endnetgrent(); .PP .C int endnetgrent_r( .C " char **ngstaste" .C ); .PP .C int getnetgrent( .C " char **machinep, " .C " char **userp, " .C " char **domainp" .C ); .PP .C int getnetgrent_r( .C " char **machinep," .C " char **namep," .C " char **domainp," .C " char **ngstate" .C ); .fi .SH DESCRIPTION .TP 20 .C innetgr() Returns 1 if .C netgroup contains the machine, user, and domain triple as a member. Otherwise, it returns 0. If .IR machine , .IR user , or .I domain is .SM NULL, .C innetgr interprets .SM NULL to mean, any machine, user, or domain respectively. Refer to .IR netgroup (4) for a description of .C netgroup membership criteria. .TP .C getnetgrent() Returns the next member of a network group. After the call, .I machinep contains a pointer to a string containing the name of the machine part of the network group member. Pointers .I userp and .I domainp behave in a manner similar to .IR machinep . If any of these pointers are returned with a .SM NULL value, they are interpreted as wild cards. .C getnetgrent() allocates space for the names. This space is released when an .C endnetgrent() call is made. .C getnetgrent() returns 1 if it succeeded in obtaining another network group member, 0 if it reached the end of the group. .TP .C setnetgrent() Establishes the network group from which .C getnetgrent() obtains members, and also restarts calls to .C getnetgrent() from the beginning of the list. If the previous .C setnetgrent() call was to a different network group, a .C endnetgrent() call is implied. .TP .C endnetgrent() Frees the space allocated during .C getnetgrent() calls. .PD .PP If the system is running the Network Information Service (NIS) services, .CR setnetgrent() gets the netgroup information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getnetgrent_r(), .CR setnetgrent_r(), and .CR endnetgrent_r(), expect to be passed a pointer of .CR "char **ngstate" that will store the result of the lookup at the supplied location. This structure is used to store data, which the other reentrant (_r) routines use. .PP .CR setnetgrent_r() and .CR endnetgrent_r() are to be used only in conjunction with .CR getnetgrent_r() and take the same pointer to a char **ngstate as a parameter. .PP The .I **ngstate pointer must be initialized to NULL before it is passed to .CR setnetgrent_r() for the first time. Thereafter is should not be modified in any way. .SS Name Service Switch-Based Operation The library routine, .CR innetgr() , setnetgrent() , and setnetgrent_r(), internally call the name service switch to access the "netgroup" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve netgroup lookups. .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getnetgrent() , .CR setnetgrent() , and .CR endnetgrent() are unsafe in multi-thread applications. .CR getnetgrent_r() , .CR setnetgrent_r() , and .CR endnetgrent_r() are MT-Safe and should be used instead. .SH AUTHOR .C getnetgrent() was developed by Sun Microsystems, Inc. .SH FILES .C /etc/netgroup .C /etc/nsswitch.conf .SH SEE ALSO netgroup(4), switch(4). .\" .\" index@\f4getnetgrent()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@\f4endnetgrent()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@\f4innetgr()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@\f4setnetgrent()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@set network group entry@@@\f3getnetgrent(3C)\f1 .\" index@network group entry, get or set@@@\f3getnetgrent(3C)\f1 .\" index@group entry, network, get or set@@@\f3getnetgrent(3C)\f1 .\" index@entry, network group, get or set@@@\f3getnetgrent(3C)\f1 .\" .\" toc@\f3getnetgrent(3C)\f1: \f4getnetgrent()\fP, \f4setnetgrent()\fP, \f4endnetgrent()\fP, \f4innetgr()\fP@@@get network group entry .\" .\" links@getnetgrent.3c setnetgrent.3c .\" links@getnetgrent.3c endnetgrent.3c .\" links@getnetgrent.3c innetgr.3c .\" .\" fileset_database@getnetgrent.3c PROGRAMING-MAN .\" $Header: innstr.3x,v 76.2 95/08/01 11:22:05 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innstr, instr, mvinnstr, mvinstr, mvwinnstr, mvwinstr, winnstr, winstr \(em input a multi-byte character string from a window .SH SYNOPSIS .C "#include " .P .C "int innstr(char *\f2str\fP, int \f2n\fP);" .P .C "int instr(char *\f2str\fP);" .P .C "int mvinnstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvinstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int mvwinnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvwinstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int winnstr(WINDOW *\f2win\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int winstr(WINDOW *\f2win\fP, char *\f2str\fP);" .SH DESCRIPTION These functions place a string of characters from the current or specified window into the array pointed to by \f2str\fP, starting at the current or specified position and ending at the end of the line. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions store at most \f2n\f1 bytes in the string pointed to by \f2str\f1. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions will only store the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character the array is filled with complete characters. If the array is not large enough to contain any complete characters, the function fails. .SH "RETURN VALUE" Upon successful completion, .CR instr() , .CR mvinstr() , .Fn mvwinstr and .Fn winstr return OK. .P Upon successful completion, .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since multi-byte characters may be processed, there might not be a one-to-one correspondence between the number of column positions on the screen and the number of bytes returned. .P These functions do not return rendition information. .P Reading a line that overflows the array pointed to by \f2str\f1 with .CR instr() , .CR mvinstr() , .Fn mvwinstr or .Fn winstr causes undefined results. The use of .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr or .CR winnstr() , respectively, is recommended. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innstr(3X)\f1:\0\0\f4innstr()\f1, \f4instr()\f1, \f4mvinnstr()\f1, \f4mvinstr()\f1, \f4mvwinnstr()\f1, \f4mvwinstr()\f1, \f4winnstr()\f1, \n\f4winstr()\f1@@@input a multi-byte character string from a window .\" toc@\f4instr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" .\" index@\f4innstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4instr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1multi-byte character string, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1character string, multi-byte, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1window, input a multi-byte character string from@@@\f3innstr(3X)\f1 .\" .\" links@innstr.3x instr.3x .\" links@innstr.3x mvinstr.3x .\" links@innstr.3x mvinnstr.3x .\" links@innstr.3x mvwinstr.3x .\" links@innstr.3x mvwinnstr.3x .\" links@innstr.3x winstr.3x .\" links@innstr.3x winnstr.3x .\" .\" fileset_database@innstr.3x CURS-ENG-A-MAN .\" $Header: innwstr.3x,v 76.2 95/08/01 11:22:59 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innwstr, inwstr, mvinnwstr, mvinwstr, mvwinnwstr, mvwinwstr, winnwstr, winwstr \(em input a string of wide characters from a window .SH SYNOPSIS .C "#include " .P .C "int innwstr(wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int inwstr(wchar_t *\f2wstr\fP);" .P .C "int mvinnwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvinwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int mvwinnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwinwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int winnwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int winwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP);" .SH DESCRIPTION These functions place a string of \f3wchar_t\f1 characters from the current or specified window into the array pointed to by \f2wstr\f1 starting at the current or specified cursor position and ending at the end of the line. .P These functions will only store the entire wide character sequence associated with a spacing complex character. If the array is large enough to contain at least one complete spacing complex character, the array is filled with complete characters. If the array is not large enough to contain any complete characters this is an error. .P The .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr functions store at most \f2n\f1 characters in the array pointed to by \f2wstr\f1. .SH "RETURN VALUE" Upon successful completion, .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr and .Fn winwstr return OK. .P Upon successful completion, .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr or .Fn winwstr causes undefined results. The use of .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr or .CR winnwstr() , respectively, is recommended. .P These functions do not return rendition information. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innwstr(3X)\f1:\0\0\f4innwstr()\f1, \f4inwstr()\f1, \f4mvinnwstr()\f1, \f4mvinwstr()\f1, \f4mvwinnwstr()\f1, \f4mvwinwstr()\f1, \n\f4winnwstr()\f1, \f4winwstr()\f1@@@input a string of wide characters from a window .\" toc@\f4innwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4inwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" .\" index@\f4innwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4inwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1string of wide characters, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1wide characters, string of, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1window, input a string of wide characters from@@@\f3innwstr(3X)\f1 .\" index@\f1characters, wide, input a string of, from a window@@@\f3innwstr(3X)\f1 .\" .\" links@innwstr.3x inwstr.3x .\" links@innwstr.3x mvinnwstr.3x .\" links@innwstr.3x mvinwstr.3x .\" links@innwstr.3x mvwinnwstr.3x .\" links@innwstr.3x mvwinwstr.3x .\" links@innwstr.3x winnwstr.3x .\" links@innwstr.3x winwstr.3x .\" .\" fileset_database@innwstr.3x CURS-ENG-A-MAN .\" $Header: ins_nwstr.3x,v 76.2 95/08/01 11:23:53 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ins_nwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ins_nwstr, ins_wstr, mvins_nwstr, mvins_wstr, mvwins_nwstr, mvwins_wstr, wins_nwstr, wins_wstr \(em insert a wide-character string into a window .SH SYNOPSIS .C "#include " .P .C "int ins_nwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int ins_wstr(wchar_t *const \f2wstr\fP);" .P .C "int mvins_nwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvins_wstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwins_nwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwins_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int wins_nwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int wins_wstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions insert a .B wchar_t character string (as many .B wchar_t characters as will fit on the line) in the current or specified window immediately before the current or specified position. .P Any non-spacing characters in the string are associated with the first spacing character in the string that precedes the non-spacing characters. If the first character in the string is a non-spacing character, these functions will fail. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing. .P The .CR ins_nwstr() , .CR mvins_nwstr() , .Fn mvwins_nwstr and .Fn wins_nwstr functions insert at most \f2n\f1 \f3wchar_t\f1 characters. If \f2n\f1 is less than 1, then the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3ins_nwstr(3X)\f1:\0\0\f4ins_nwstr()\f1, \f4ins_wstr()\f1, \f4mvins_nwstr()\f1, \f4mvins_wstr()\f1, \f4mvwins_nwstr()\f1, \n\f4mvwins_wstr()\f1, \f4wins_nwstr()\f1, \f4wins_wstr()\f1@@@insert a wide-character string into a window .\" toc@\f4ins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" .\" index@\f4ins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4ins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1wide-character string, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1string of wide-character, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1window, insert a wide-character string into@@@\f3ins_nwstr(3X)\f1 .\" index@\f1character, insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" .\" links@ins_nwstr.3x ins_wstr.3x .\" links@ins_nwstr.3x mvins_nwstr.3x .\" links@ins_nwstr.3x mvins_wstr.3x .\" links@ins_nwstr.3x mvwins_nwstr.3x .\" links@ins_nwstr.3x mvwins_wstr.3x .\" links@ins_nwstr.3x wins_nwstr.3x .\" links@ins_nwstr.3x wins_wstr.3x .\" .\" fileset_database@ins_nwstr.3x CURS-ENG-A-MAN .\" $Header: ins_wch.3x,v 76.2 95/08/01 11:24:46 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ins_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ins_wch, mvins_wch, mvwins_wch, wins_wch \(em insert a complex character and rendition into a window .SH SYNOPSIS .C "#include " .P .C "int ins_wch(cchar_t *const \f2wch\fP);" .P .C "int wins_wch(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "int mvins_wch(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .P .C "int mvwins_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .SH DESCRIPTION These functions insert the complex character \f2wch\f1 with its rendition in the current or specified window at the current or specified cursor position. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing, with the exception that if a newline is inserted into the last line of a window and scrolling is not enabled, the behaviour is unspecified. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" For non-spacing characters, .Fn add_wch can be used to add the non-spacing characters to a spacing complex character already in the window. .SH "SEE ALSO" add_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3ins_wch(3X)\f1:\0\0\f4ins_wch()\f1, \f4mvins_wch()\f1, \f4mvwins_wch()\f1, \f4wins_wch()\f1\n@@@insert a complex character and rendition into a window .\" toc@\f4mvins_wch()\f1: insert a complex character and rendition into a window@@@see \f3ins_wch(3X)\f1 .\" toc@\f4mvwins_wch()\f1: insert a complex character and rendition into a window@@@see \f3ins_wch(3X)\f1 .\" toc@\f4wins_wch()\f1: insert a complex character and rendition into a window@@@see \f3ins_wch(3X)\f1 .\" .\" index@\f4ins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f4mvins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f4mvwins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f4wins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1complex character and rendition, insert into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1character and rendition, complex, insert into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1window, insert a complex character and rendition into@@@\f3ins_wch(3X)\f1 .\" .\" links@ins_wch.3x mvins_wch.3x .\" links@ins_wch.3x mvwins_wch.3x .\" links@ins_wch.3x wins_wch.3x .\" .\" fileset_database@ins_wch.3x CURS-ENG-A-MAN .\" $Header: ins_nwstr.3x,v 76.2 95/08/01 11:23:53 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ins_nwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ins_nwstr, ins_wstr, mvins_nwstr, mvins_wstr, mvwins_nwstr, mvwins_wstr, wins_nwstr, wins_wstr \(em insert a wide-character string into a window .SH SYNOPSIS .C "#include " .P .C "int ins_nwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int ins_wstr(wchar_t *const \f2wstr\fP);" .P .C "int mvins_nwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvins_wstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwins_nwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwins_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int wins_nwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int wins_wstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions insert a .B wchar_t character string (as many .B wchar_t characters as will fit on the line) in the current or specified window immediately before the current or specified position. .P Any non-spacing characters in the string are associated with the first spacing character in the string that precedes the non-spacing characters. If the first character in the string is a non-spacing character, these functions will fail. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing. .P The .CR ins_nwstr() , .CR mvins_nwstr() , .Fn mvwins_nwstr and .Fn wins_nwstr functions insert at most \f2n\f1 \f3wchar_t\f1 characters. If \f2n\f1 is less than 1, then the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3ins_nwstr(3X)\f1:\0\0\f4ins_nwstr()\f1, \f4ins_wstr()\f1, \f4mvins_nwstr()\f1, \f4mvins_wstr()\f1, \f4mvwins_nwstr()\f1, \n\f4mvwins_wstr()\f1, \f4wins_nwstr()\f1, \f4wins_wstr()\f1@@@insert a wide-character string into a window .\" toc@\f4ins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" .\" index@\f4ins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4ins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1wide-character string, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1string of wide-character, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1window, insert a wide-character string into@@@\f3ins_nwstr(3X)\f1 .\" index@\f1character, insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" .\" links@ins_nwstr.3x ins_wstr.3x .\" links@ins_nwstr.3x mvins_nwstr.3x .\" links@ins_nwstr.3x mvins_wstr.3x .\" links@ins_nwstr.3x mvwins_nwstr.3x .\" links@ins_nwstr.3x mvwins_wstr.3x .\" links@ins_nwstr.3x wins_nwstr.3x .\" links@ins_nwstr.3x wins_wstr.3x .\" .\" fileset_database@ins_nwstr.3x CURS-ENG-A-MAN .\" $Header: insch.3x,v 76.2 95/08/01 11:25:41 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insch, mvinsch, mvwinsch, winsch \(em insert a single-byte character and rendition into a window .SH SYNOPSIS .C "#include " .P .C "int insch(chtype \f2ch\fP);" .P .C "int mvinsch(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP);" .P .C "int mvwinsch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP);" .P .C "int winsch(WINDOW *\f2win\fP, chtype \f2ch\fP);" .SH DESCRIPTION These functions insert the character and rendition from \f2ch\f1 into the current or specified window at the current or specified position. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing, with the exception that if a newline is inserted into the last line of a window and scrolling is not enabled, the behaviour is unspecified. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" ins_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" toc@\f3insch(3X)\f1:\0\0\f4insch()\f1, \f4mvinsch()\f1, \f4mvwinsch()\f1, \f4winsch()\f1\n@@@insert a single-byte character and rendition into a window .\" toc@\f4mvinsch()\f1: insert a single-byte character and rendition into a window@@@see \f3insch(3X)\f1 .\" toc@\f4mvwinsch()\f1: insert a single-byte character and rendition into a window@@@see \f3insch(3X)\f1 .\" toc@\f4winsch()\f1: insert a single-byte character and rendition into a window@@@see \f3insch(3X)\f1 .\" .\" index@\f4insch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f4mvinsch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f4mvwinsch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f4winsch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f1insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f1single-byte character and rendition, insert into a window@@@\f3insch(3X)\f1 .\" index@\f1character and rendition, single-byte, insert into a window@@@\f3insch(3X)\f1 .\" index@\f1window, insert a single-byte character and rendition into@@@\f3insch(3X)\f1 .\" .\" links@insch.3x mvinsch.3x .\" links@insch.3x mvwinsch.3x .\" links@insch.3x winsch.3x .\" .\" fileset_database@insch.3x CURS-ENG-A-MAN .\" $Header: insdelln.3x,v 76.2 95/08/01 11:26:22 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insdelln 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insdelln, winsdelln \(em delete or insert lines into a window .SH SYNOPSIS .C "#include " .P .C "int insdelln(int \f2n\fP);" .P .C "int winsdelln(WINDOW *\f2win\fP, int \f2n\fP);" .SH DESCRIPTION The .Fn insdelln and .Fn winsdelln functions perform the following actions: .RS .TP 3 .C \(bu If \f2n\f1 is positive, these functions insert \f2n\f1 lines into the current or specified window before the current line. The \f2n\f1 last lines are no longer displayed. .TP .C \(bu If \f2n\f1 is negative, these functions delete \f2n\f1 lines from the current or specified window starting with the current line, and move the remaining lines toward the cursor. The last \f2n\f1 lines are cleared. .RE .P The current cursor position remains the same. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" deleteln(), insertln(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3insdelln(3X)\f1:\0\0\f4insdelln()\f1, \f4winsdelln()\f1@@@delete or insert lines into a window .\" toc@\f4winsdelln()\f1: delete or insert lines into a window@@@see \f3insdelln(3X)\f1 .\" .\" index@\f4insdelln()\f1 \- delete or insert lines into a window@@@\f3insdelln(3X)\f1 .\" index@\f4winsdelln()\f1 \- delete or insert lines into a window@@@\f3insdelln(3X)\f1 .\" index@\f1delete or insert lines into a window@@@\f3insdelln(3X)\f1 .\" index@\f1insert or delete lines into a window@@@\f3insdelln(3X)\f1 .\" index@\f1lines, delete or insert into a window@@@\f3insdelln(3X)\f1 .\" index@\f1window, delete or insert lines into@@@\f3insdelln(3X)\f1 .\" .\" links@insdelln.3x winsdelln.3x .\" .\" fileset_database@insdelln.3x CURS-ENG-A-MAN .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "insert_child" "Xt \- Intrinsics Methods" .SH "Name" .Na insert_child \- Composite class method called when a child is created. .Nz .XX "insert_child method" .XX "methods, insert_child" .SH "Synopsis" .Sy typedef void (*XtWidgetProc)(Widget); .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget which has been created and is to be added to its parent's \f(CWchildren\fP array. .\" .SH "Description" The \f(CWinsert_child()\fP method is registered on the \f(CWinsert_child\fP field of the Composite class part structure. It is called by \f(CWXtCreateWidget()\fP to insert a newly created child into its parent's \f(CWchildren\fP array. .LP Note that the argument to the \f(CWinsert_child()\fP method is the child widget, not the composite widget that defines the method. This method must add the specified child to its parent's \f(CWchildren\fP array, and do anything else that the particular class uses to keep track of its children. .LP The \f(CWinsert_child()\fP method is not chained. If a class does not define an \f(CWinsert_child()\fP method, it should inherit the method from its superclass by specifying \f(CWXtInheritInsertChild\fP in the \f(CWinsert_child\fP field of its Composite class part structure. This field should never be \f(CWNULL\fP. .\" .SH "Usage" Most composite widgets inherit this method from their superclass. Some composite widget classes define their own \f(CWinsert_child()\fR method so that they can order their children in some convenient way, create companion widgets for each child, or limit the number or class of their children. These classes commonly "envelop" their superclass's method by providing a procedure that does class-specific processing and explicitly invokes the superclass method. This technique allows a kind of non-automatic inheritance, and is shown in the example below. .LP Note that the Composite \f(CWinsert_child()\fR and \f(CWdelete_child()\fR methods exploit internal common data structures, so you should inherit or envelop both or neither. If you do not inherit or envelop these methods, then your methods are responsible for adding and removing the child widget from the \f(CWchildren\fP array. The "Background" section below explains what the \f(CWinsert_child()\fP method of the Composite class itself does. .\" .SH "Example" The following procedure is the \f(CWinsert_child()\fP method of the Xaw Paned widget class. Note that it first calls the \f(CWinsert_child()\fP method of its superclass, and then creates a Grip widget for the new child. (Unless the child has constraint resource \f(CWXtNshowGrip\fP \f(CWFalse\fP.) See \f(CWdelete_child\fP(4) for the corresponding \f(CWdelete_child()\fP method. .Ps .ps 8 static void InsertChild(w) register Widget w; .ne 12 { Pane pane = PaneInfo(w); /* insert the child widget in the composite children list with the */ /* superclass insert_child routine. */ (*SuperClass->composite_class.insert_child)(w); if (!IsPane(w)) return; /* Panes will be added in the order they are created, temporarily */ if ( pane->show_grip == TRUE ) { CreateGrip(w); if (pane->min == PANED_GRIP_SIZE) pane->min = PaneSize(pane->grip, IsVert((PanedWidget) XtParent(w))); } else { if (pane->min == PANED_GRIP_SIZE) pane->min = 1; pane->grip = NULL; } pane->size = 0; pane->paned_adjusted_me = FALSE; } /* InsertChild */ .ps .Pe In this example, \f(CWSuperClass\fP is a symbolic name for the superclass of the Paned widget class. Note that this method does \fInot\fP determine the superclass as follows: .Ps XtSuperclass(XtParent(w)) .Pe The parent of \f(CIw\fP may be a subclass of \f(CWPaned\fP, and therefore its superclass pointer will not always be the class whose method should be invoked. .\" .SH "Background" The \f(CWinsert_child()\fP method of the Composite class itself is commonly inherited by subclasses or explicitly invoked by them. It performs the following: .IP \(bu 3n Calls the \f(CWXtOrderProc\fP registered on the \f(CWXtNinsertPosition\fP resource of the composite widget to determine the position in the children array at which the child should be inserted. If there is no procedure specified for this resource, it inserts the child at the end of the array. .IP \(bu 3n Inserts the child at the appropriate position in the array, moving other children if necessary. If there is not enough room to insert a new child in the children array (that is, \f(CWnum_children\fR = \f(CWnum_slots\fR), it reallocates the array and updates \f(CWnum_slots\fP. .IP \(bu 3n Increments \f(CWnum_children\fP. .LP If a composite widget class does not have an \f(CWCompositeClassExtension\fR record or if the \f(CWaccepts_objects\fP field of that record is \f(CWFalse\fR, the Intrinsics will not allow non-widget children of that widget. Therefore, the \f(CWinsert_child()\fP method of a widget class that does not accept object children is guaranteed never to be passed a non-widget child. .\" .SH "See Also" .na .br \s-1\fIXtCreateWidget\fR\s+1\*(s1, .br \s-1\fIComposite\fR\s+1\*(s3, \s-1\fIConstraint\fR\s+1\*(s3, .br \s-1\fIdelete_child\fR\s+1\*(s4. .ad .\"last line comment .\" $Header: insertln.3x,v 76.2 95/08/01 11:27:16 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insertln 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insertln, winsertln \(em insert lines into a window .SH SYNOPSIS .C "#include " .P .C "int insertln(void);" .P .C "int winsertln(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn insertln and .Fn winsertln functions insert a blank line before the current line in the current or specified window. The bottom line is no longer displayed. The cursor position does not change. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" insdelln(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn insertln function is explicitly declared as \f3void\f1. .\" .\" toc@\f3insertln(3X)\f1:\0\0\f4insertln()\f1, \f4winsertln()\f1@@@insert lines into a window .\" toc@\f4winsertln()\f1: insert lines into a window@@@see \f3insertln(3X)\f1 .\" .\" index@\f4insertln()\f1 \- insert lines into a window@@@\f3insertln(3X)\f1 .\" index@\f4winsertln()\f1 \- insert lines into a window@@@\f3insertln(3X)\f1 .\" index@\f1insert lines into a window@@@\f3insertln(3X)\f1 .\" index@\f1lines, insert into a window@@@\f3insertln(3X)\f1 .\" index@\f1window, insert lines into@@@\f3insertln(3X)\f1 .\" .\" links@insertln.3x winsertln.3x .\" .\" fileset_database@insertln.3x CURS-ENG-A-MAN .\" $Header: insnstr.3x,v 76.3 95/10/05 14:42:06 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insnstr, insstr, mvinsnstr, mvinsstr, mvwinsnstr, mvwinsstr, winsnstr, winsstr \(em insert a multi-byte character string into a window .SH SYNOPSIS .C "#include " .P .C "int insnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int insstr(char *const \f2str\fP);" .P .C "int mvinsnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvinsstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwinsnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwinsstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int winsnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int winsstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions insert a character string (as many characters as will fit on the line) before the current or specified position in the current or specified window. .P These functions do not advance the cursor position. These functions perform special-character processing. The .Fn innstr and .Fn innwstr functions perform wrapping. The .Fn instr and .Fn inswstr functions do not perform wrapping. .P The .CR insnstr() , .CR mvinsnstr() , .Fn mvwinsnstr and .Fn winsnstr functions insert .\" entire multi-byte characters contained in the first at most \f2n\f1 bytes. If \f2n\f1 is less than 1, the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since the string may contain multi-byte characters, there might not be a one-to-one correspondence between the number of column positions occupied by the characters and the number of bytes in the string. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3insnstr(3X)\f1:\0\0\f4insnstr()\f1, \f4insstr()\f1, \f4mvinsnstr()\f1, \f4mvinsstr()\f1, \f4mvwinsnstr()\f1, \f4mvwinsstr()\f1, \n\f4winsnstr()\f1, \f4winsstr()\f1@@@insert a multi-byte character into a window .\" toc@\f4insstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" .\" index@\f4insnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4insstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1multi-byte character, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1character, multi-byte, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1window, insert a multi-byte character into@@@\f3insnstr(3X)\f1 .\" .\" links@insnstr.3x insstr.3x .\" links@insnstr.3x mvinsnstr.3x .\" links@insnstr.3x mvinsstr.3x .\" links@insnstr.3x mvwinsnstr.3x .\" links@insnstr.3x mvwinsstr.3x .\" links@insnstr.3x winsnstr.3x .\" links@insnstr.3x winsstr.3x .\" .\" fileset_database@insnstr.3x CURS-ENG-A-MAN .\" $Header: insque.3c,v 72.2 94/08/18 10:45:50 ssa Exp $ .TA i .TH insque 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insque(), remque() \- insert or remove an element in a queue .SH SYNOPSIS .C "#include " .PP .C "void insque(void *element, void *pred);" .PP .C "void remque(void *element);" .SH DESCRIPTION The .CR insque() and .CR remque() functions manipulate queues built from doubly-linked lists. An application using these functions must define a structure in which the first two members of the structure are pointers to the same type of structure. Any additional members of the structure are application specific. The first two members of the structure are used for forward and backward pointers. The names of the structure and of the pointers are not subject to any restrictions. .PP The .CR insque() function inserts the object pointed to by the .I element argument into a queue immediately after the object pointed to by the .I pred argument. .PP The .CR remque() function removes the object pointed to by the .I element argument from a queue. .SH AUTHOR .CR insque() and .CR remque() were developed by HP and the University of California, Berkeley. .SH STANDARDS COMPLIANCE .CR insque() ": XPG4.2" .PP .CR remque() ": XPG4.2" .\" .\" toc@\f3insque(3C)\f1:\0\0\f4insque()\f1, \f4remque()\f1@@@insert or remove an element in a queue\f1 .\" toc@\f4remque()\f1:\0\0remove an element in a queue@@@\f1see \f3insque(3C)\f1 .\" index@\f4insque()\f1 \- insert an element in a queue@@@\f3insque(3C)\f1 .\" index@\f4remque()\f1 \- remove an element in a queue@@@\f3insque(3C)\f1 .\" index@\f1insert or remove an element in a queue@@@\f3insque(3C)\f1 .\" index@\f1remove or insert an element in a queue@@@\f3insque(3C)\f1 .\" index@\f1queue, insert or remove an element@@@\f3insque(3C)\f1 .\" .\" links@insque.3c remque.3c .\" $Header: insnstr.3x,v 76.3 95/10/05 14:42:06 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insnstr, insstr, mvinsnstr, mvinsstr, mvwinsnstr, mvwinsstr, winsnstr, winsstr \(em insert a multi-byte character string into a window .SH SYNOPSIS .C "#include " .P .C "int insnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int insstr(char *const \f2str\fP);" .P .C "int mvinsnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvinsstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwinsnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwinsstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int winsnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int winsstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions insert a character string (as many characters as will fit on the line) before the current or specified position in the current or specified window. .P These functions do not advance the cursor position. These functions perform special-character processing. The .Fn innstr and .Fn innwstr functions perform wrapping. The .Fn instr and .Fn inswstr functions do not perform wrapping. .P The .CR insnstr() , .CR mvinsnstr() , .Fn mvwinsnstr and .Fn winsnstr functions insert .\" entire multi-byte characters contained in the first at most \f2n\f1 bytes. If \f2n\f1 is less than 1, the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since the string may contain multi-byte characters, there might not be a one-to-one correspondence between the number of column positions occupied by the characters and the number of bytes in the string. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3insnstr(3X)\f1:\0\0\f4insnstr()\f1, \f4insstr()\f1, \f4mvinsnstr()\f1, \f4mvinsstr()\f1, \f4mvwinsnstr()\f1, \f4mvwinsstr()\f1, \n\f4winsnstr()\f1, \f4winsstr()\f1@@@insert a multi-byte character into a window .\" toc@\f4insstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" .\" index@\f4insnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4insstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1multi-byte character, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1character, multi-byte, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1window, insert a multi-byte character into@@@\f3insnstr(3X)\f1 .\" .\" links@insnstr.3x insstr.3x .\" links@insnstr.3x mvinsnstr.3x .\" links@insnstr.3x mvinsstr.3x .\" links@insnstr.3x mvwinsnstr.3x .\" links@insnstr.3x mvwinsstr.3x .\" links@insnstr.3x winsnstr.3x .\" links@insnstr.3x winsstr.3x .\" .\" fileset_database@insnstr.3x CURS-ENG-A-MAN .\" $Header: innstr.3x,v 76.2 95/08/01 11:22:05 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innstr, instr, mvinnstr, mvinstr, mvwinnstr, mvwinstr, winnstr, winstr \(em input a multi-byte character string from a window .SH SYNOPSIS .C "#include " .P .C "int innstr(char *\f2str\fP, int \f2n\fP);" .P .C "int instr(char *\f2str\fP);" .P .C "int mvinnstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvinstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int mvwinnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvwinstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int winnstr(WINDOW *\f2win\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int winstr(WINDOW *\f2win\fP, char *\f2str\fP);" .SH DESCRIPTION These functions place a string of characters from the current or specified window into the array pointed to by \f2str\fP, starting at the current or specified position and ending at the end of the line. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions store at most \f2n\f1 bytes in the string pointed to by \f2str\f1. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions will only store the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character the array is filled with complete characters. If the array is not large enough to contain any complete characters, the function fails. .SH "RETURN VALUE" Upon successful completion, .CR instr() , .CR mvinstr() , .Fn mvwinstr and .Fn winstr return OK. .P Upon successful completion, .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since multi-byte characters may be processed, there might not be a one-to-one correspondence between the number of column positions on the screen and the number of bytes returned. .P These functions do not return rendition information. .P Reading a line that overflows the array pointed to by \f2str\f1 with .CR instr() , .CR mvinstr() , .Fn mvwinstr or .Fn winstr causes undefined results. The use of .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr or .CR winnstr() , respectively, is recommended. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innstr(3X)\f1:\0\0\f4innstr()\f1, \f4instr()\f1, \f4mvinnstr()\f1, \f4mvinstr()\f1, \f4mvwinnstr()\f1, \f4mvwinstr()\f1, \f4winnstr()\f1, \n\f4winstr()\f1@@@input a multi-byte character string from a window .\" toc@\f4instr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" .\" index@\f4innstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4instr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1multi-byte character string, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1character string, multi-byte, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1window, input a multi-byte character string from@@@\f3innstr(3X)\f1 .\" .\" links@innstr.3x instr.3x .\" links@innstr.3x mvinstr.3x .\" links@innstr.3x mvinnstr.3x .\" links@innstr.3x mvwinstr.3x .\" links@innstr.3x mvwinnstr.3x .\" links@innstr.3x winstr.3x .\" links@innstr.3x winnstr.3x .\" .\" fileset_database@innstr.3x CURS-ENG-A-MAN .\" $Header: intrflush.3x,v 76.2 95/08/01 11:28:58 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH intrflush 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME intrflush \(em enable or disable flush on interrupt .SH SYNOPSIS .C "#include " .P .C "int intrflush(WINDOW *\f2win\fP, bool \f2bf\fP);" .SH DESCRIPTION The .Fn intrflush function specifies whether pressing an interrupt key (interrupt, suspend or quit) will flush the input buffer associated with the current screen. If \f2bf\f1 is TRUE, pressing an interrupt key will flush this input buffer. If \f2bf\f1 is FALSE, pressing an interrupt key will not flush this input buffer. The default for the option is inherited from the display driver settings. The \f2win\f1 argument must refer to a window associated with the current screen. .SH "RETURN VALUE" Upon successful completion, .Fn intrflush returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The same effect is achieved outside Curses using the NOFLSH local mode flag specified in the \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification (\f3General Terminal Interface\fP). .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, , \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Section 9.2, \f3Parameters That Can Be Set\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" index@\f4intrflush()\f1 \- enable or disable flush on interrupt@@@\f3intrflush(3X)\f1 .\" index@\f1enable or disable flush on interrupt@@@\f3intrflush(3X)\f1 .\" index@\f1disable or enable flush on interrupt@@@\f3intrflush(3X)\f1 .\" index@\f1flush, enable or disable on interrupt@@@\f3intrflush(3X)\f1 .\" index@\f1interrupt, enable or disable flush@@@\f3intrflush(3X)\f1 .\" .\" toc@\f3intrflush(3X)\f1:\0\0\f4intrflush()\f1@@@enable or disable flush on interrupt .\" .\" fileset_database@intrflush.3x CURS-ENG-A-MAN .\" $Header: intro.3c,v 72.4 94/11/02 01:44:48 ssa Exp $ .TA a .TH intro 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME intro \- introduction to subroutines and libraries .SH SYNOPSIS .C #include .PP .C #include .SH DESCRIPTION This section describes functions found in various libraries, other than those functions that directly invoke .SM HP-UX system primitives, which are described in Section (2) of this volume. Certain major collections are identified by a letter after the section identifier (3): .RS .TP 10 (3C) These functions, together with the Operating System Calls and those marked (3S), constitute the Standard C Library which is automatically loaded by the C compiler, .IR cc (1). The link editor .IR ld (1) searches this library if the .C \-lc option is specified. Declarations for some of these functions can be obtained from .C #include files indicated in the appropriate entries. .TP (3G) These functions constitute the graphics library, and are documented in separate manuals. .TP (3I) These functions constitute the instrument support (Device .SM I/O\c ) library. .TP (3M) These functions constitute the Math Libraries, .C libm.a and .CR libM.a . All of the functions are in both libraries except for .C matherr (see .IR matherr (3M) for more details). The .SM HP-UX operating system provides two different libraries due to to conflicts between Issue 2 of the .SM SVID specification and the .SM ANSI C standard. If behavior conforming to .SM SVID Issue 2 is desired, .C libm.a should be used. If behavior conforming to the .SM ANSI C standard is desired, .C libM.a should be used. The .C libm.a library is automatically linked as needed by the F\s-2ORTRAN\s0 compiler (see .IR f77 (1)). Neither is automatically loaded by the C compiler (see .IR cc (1)); however, the link editor searches this library if the .C \-lm (for .CR libm.a ) or .C \-lM (for .CR libM.a ) option is specified. Declarations for these functions are available in the header file .RC < math.h >. Several generally useful mathematical constants are also defined there (see .IR math (5)). .TP (3N) These functions are applicable to the Internet network, and are part of the standard C library, .CR libc.a . .TP (3S) These functions constitute the ``standard .SM I/O package'' (see .IR stdio (3S)). These functions are in the library .CR libc , already mentioned. Declarations for these functions can be obtained from the .C #include file .RC < stdio.h >. .TP (3X) Various specialized libraries. The files in which these libraries are found are specified in the appropriate entries. .RE .SS Definitions The word .B character is used to refer to a bit representation that fits in a byte and represents a single graphic character or control function. The .B null character is a character with value 0, represented in the C language as .CR \e0 . A .B character array is a sequence of characters. A .B null-terminated character array is a sequence of characters, the last of which is the .BR "null character" . A .B string is a designation for a .BR "null-terminated character array" . The .B "null string" is a character array containing only the null character. A null pointer is the value that is obtained by casting .C 0 into a pointer. The C language guarantees that two null pointers always compare equal, and a null pointer always compares unequal to a pointer to any object or function. Consquently, many functions that return pointers return a null pointer to indicate an error. The macro .C NULL expands to a null pointer constant and is defined in .RC < stddef.h > and certain other headers. .PP Many groups of F\s-2ORTRAN\s0 intrinsic functions have generic function names that do not require explicit or implicit type declaration. The type of the function is determined by the type of its argument or arguments. For example, the generic function .C max returns an integer value if given integer arguments .RC ( max0 ), a real value if given real arguments .RC ( amax1 ), or a double-precision value if given double-precision arguments .RC ( dmax1 ). .SH DIAGNOSTICS Functions in the C and Math Libraries, (3C) and (3M), may return the conventional values .C 0 or .C \(+-HUGE_VAL (the largest-magnitude double-precision floating-point numbers; .C HUGE_VAL is defined in the .RC < math.h > header file) when the function is undefined for the given arguments or when the value is not representable. Functions in the Math Libraries may also return .C \(+-INFINITY or .CR NaN . In these cases, the external variable .C errno (see .IR errno (2)) is set to the value .SM EDOM or .SM ERANGE. As many of the F\s-2ORTRAN\s0 intrinsic functions use the routines found in the Math Library, the same conventions apply. .SH WARNINGS Library routines in .C libc.a and .C libm.a often call other routines in these libraries. Prior to .SM HP-UX release 7.0, a user could define a function having the same name as one of these library routines, and this function would be linked in instead of the library version. In this way, a user could effectively replace a library routine with his own (see .IR matherr (3M) for a supported example of this). More often, this type of linkage would occur unintentionally, causing unexpected behavior which was difficult to debug. .PP Starting at Release 7.0, object names in libraries have been modified such that they are much less likely to collide with user names. Therefore, calls to library routines from within other library routines are much more likely to call the actual library routine. .RI ( matherr (3M) is the only exception to this.) .PP In spite of these changes, it is still remotely possible for name conflicts to occur. The .IR lint (1) program checker reports name conflicts of this kind as ``multiple declarations'' of the names in question. Definitions for Sections (2), (3C), and (3S) are checked automatically. Other definitions can be included by using the .C \-l option (for example, .C \-lm includes definitions for the Math Library, .CR libm.a. Use of .IR lint (1) is highly recommended. .SH FILES .TP 20 /usr/lib/libc.a Standard .SM I/O, operating system calls, and general purpose routines archive library. .TP /usr/lib/libc.sl Standard .SM I/O, operating system calls, and general purpose routines shared library. .TP /usr/lib/libcurses.sl .SM CRT screen handling shared library. .TP /usr/lib/libm.a .SM SVID2 compliant math archive library. .TP /usr/lib/libm.sl .SM SVID2 compliant math shared library. .TP /usr/lib/libM.a .SM XPG3, POSIX.1, ANSI-C compliant math archive library. .TP /usr/lib/libM.sl .SM XPG3, POSIX.1, ANSI-C compliant math shared library. .TP /usr/lib/libF77.a General F\s-2ORTRAN\s0 77 routines archive library. .TP /usr/lib/libF77.sl General F\s-2ORTRAN\s0 77 routines shared library. .SH SEE ALSO intro(2), stdio(3S), math(5), hier(5), ar(1), cc(1), f77(1), ld(1), lint(1), nm(1). .PP The introduction to this manual. .PP .I "Device I/O Library," tutorial in .I "Device I/O Users Guide" . .\" .\" index@\f4intro()\fP \- introduction to subroutines and libraries@@@\f3intro(3)\f1 .\" index@introduction to subroutines and libraries@@@\f3intro(3)\f1 .\" index@subroutines and libraries, introduction to@@@\f3intro(3)\f1 .\" index@libraries and subroutines, introduction to@@@\f3intro(3)\f1 .\" .\" toc@\f3intro(3)\f1:\0\0\f4intro()\fP@@@introduction to subroutines and libraries .\" toc@\f3intro(3)\f1:\0\0\f4intro()\fP@@@introduction to subroutines and libraries .\" .\" fileset_database@intro.3c PROGRAMING-MAN .\" $Header: innwstr.3x,v 76.2 95/08/01 11:22:59 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innwstr, inwstr, mvinnwstr, mvinwstr, mvwinnwstr, mvwinwstr, winnwstr, winwstr \(em input a string of wide characters from a window .SH SYNOPSIS .C "#include " .P .C "int innwstr(wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int inwstr(wchar_t *\f2wstr\fP);" .P .C "int mvinnwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvinwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int mvwinnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwinwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int winnwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int winwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP);" .SH DESCRIPTION These functions place a string of \f3wchar_t\f1 characters from the current or specified window into the array pointed to by \f2wstr\f1 starting at the current or specified cursor position and ending at the end of the line. .P These functions will only store the entire wide character sequence associated with a spacing complex character. If the array is large enough to contain at least one complete spacing complex character, the array is filled with complete characters. If the array is not large enough to contain any complete characters this is an error. .P The .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr functions store at most \f2n\f1 characters in the array pointed to by \f2wstr\f1. .SH "RETURN VALUE" Upon successful completion, .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr and .Fn winwstr return OK. .P Upon successful completion, .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr or .Fn winwstr causes undefined results. The use of .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr or .CR winnwstr() , respectively, is recommended. .P These functions do not return rendition information. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innwstr(3X)\f1:\0\0\f4innwstr()\f1, \f4inwstr()\f1, \f4mvinnwstr()\f1, \f4mvinwstr()\f1, \f4mvwinnwstr()\f1, \f4mvwinwstr()\f1, \n\f4winnwstr()\f1, \f4winwstr()\f1@@@input a string of wide characters from a window .\" toc@\f4innwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4inwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" .\" index@\f4innwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4inwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1string of wide characters, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1wide characters, string of, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1window, input a string of wide characters from@@@\f3innwstr(3X)\f1 .\" index@\f1characters, wide, input a string of, from a window@@@\f3innwstr(3X)\f1 .\" .\" links@innwstr.3x inwstr.3x .\" links@innwstr.3x mvinnwstr.3x .\" links@innwstr.3x mvinwstr.3x .\" links@innwstr.3x mvwinnwstr.3x .\" links@innwstr.3x mvwinwstr.3x .\" links@innwstr.3x winnwstr.3x .\" links@innwstr.3x winwstr.3x .\" .\" fileset_database@innwstr.3x CURS-ENG-A-MAN .\" $Header: io_eol_ctl.3i,v 74.1 95/05/10 21:49:35 ssa Exp $ .TA i .TH io_eol_ctl 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME io_eol_ctl(\|) \- set up read termination character on special file .SH SYNOPSIS .C "#include " .PP .C "int io_eol_ctl(int eid, int flag, int match);" .SH DESCRIPTION .C io_eol_ctl() specifies a character to be used in terminating a read operation from the specified file (entity identifier). .PP .I eid is an entity identifier of an open .SM HP-IB raw bus, Centronics-compatible parallel, or .SM GPIO device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .CR creat() call. .I flag is an integer that enables or disables character-match termination. A non-zero value enables character-match termination, while a zero value disables it. .I match is an integer containing the numerical equivalent of the termination character. .I match is ignored if .I flag is zero. When in 8-bit mode, the lower 8 bits of .I match are used as the termination character. In 16-bit mode, the lower 16 bits are used. .PP Upon opening a file, the default condition is character-match termination disabled. When enabled, the character specified by .I match is checked for during read operations. The read is terminated upon receipt of this character, or upon any of the other termination conditions normally in effect for this file. Examples of other conditions are satisfying the specified byte count, and receiving a character when the .SM EOI line is asserted .SM (HP-IB). When the read is terminated by a .I match character, this character is the last character returned in the buffer. .PP Entity identifiers for the same device file obtained by separate .C open() calls have their own termination characters associated with them. Entity identifiers for the same device file inherited by a .C fork() call share the same termination character. In the latter case, if one process changes the termination character, the new termination character is in effect for all such entity identifiers. .SH RETURN VALUE .C io_eol_ctl() returns 0 (zero) if successful, or \(mi1 if an error was encountered. .SH ERRORS .C io_eol_ctl() fails under the following circumstances, and sets .C errno (see .IR errno (2)) to the value indicated: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to a channel device file. .RE .SH AUTHOR .C io_eol_ctl() was developed by HP. .SH SEE ALSO dup(2), creat(2), fcntl(2), open(2), io_width_ctl(3I). .\" index@\f4io_eol_ctl\f1 \- set up \s-1I/O\s+1 read termination character on special file@@@\f3io_eol_ctl(3I)\f1 .\" index@set up \s-1I/O\s+1 read termination character on special file@@@\f3io_eol_ctl(3I)\f1 .\" index@specify \s-1I/O\s+1 read termination character on special file@@@\f3io_eol_ctl(3I)\f1 .\" index@\s-1I/O\s+1 read termination character on special file, set up@@@\f3io_eol_ctl(3I)\f1 .\" index@read termination character on special file, set up \s-1I/O\s+1@@@\f3io_eol_ctl(3I)\f1 .\" index@termination character on special file, set up \s-1I/O\s+1 read@@@\f3io_eol_ctl(3I)\f1 .\" index@special file, set up \s-1I/O\s+1 read termination character on@@@\f3io_eol_ctl(3I)\f1 .\" .\" toc@\f3io_eol_ctl(3I)\f1:\0\0\f4io_eol_ctl\f1@@@set up read termination character on special file .\" .\" fileset_database@io_eol_ctl.3i PROGRAMING-MAN .\" $Header: io_get_term.3i,v 76.1 95/07/06 14:49:54 ssa Exp $ .TA i .TH io_get_term_reason 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME io_get_term_reason(\|) \- determine how last read terminated .SH SYNOPSIS .C "#include " .PP .C "int io_get_term_reason(int eid);" .SH DESCRIPTION .C io_get_term_reason() returns the termination reason for the last read made on this entity id. .I eid is an entity identifier of an open .SM HP-IB raw bus, Centronics-compatible parallel interface, or .SM GPIO device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .C creat() call. .PP All entity identifiers descending from an .C open() request (such as from .CR dup() or .CR fork()) set this status. For example, if the calling process had opened this entity identifier and later forked, the status returned would be from the last read done by either the calling process or its child. .SH RETURN VALUE .C io_get_term_reason() returns a value indicating how the last read on the specified entity identifier was terminated. This value is interpreted as follows (note that combinations are possible): .IP .TS lB lB c lw(4i) c l. Value Description _ \(mi1 T{ An error was encountered while making this function request. T} 0 T{ Last read encountered some abnormal termination reason not covered by any of the other reasons. T} 1 T{ Last read terminated by reading the number of bytes requested. T} 2 T{ Last read terminated by detecting the specified termination character. T} 4 T{ Last read terminated by detecting some device-imposed termination condition. Examples are: \s-1EOI\s+1 for \s-1HP-IB\s+1, \s-1PSTS\s+1 line on \s-1GPIO\s+1, or some other end-of-record condition, such as the physical end-of-record mark on a 9-track tape. T} .TE .SH ERRORS .C io_get_term_reason() fails under the following circumstances, and sets .C errno (see .IR errno (2)) to the value indicated: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to a channel device file. .RE .SH AUTHOR .C io_get_term_reason() was developed by HP. .SH SEE ALSO dup(2), creat(2), fcntl(2), open(2), read(2), io_eol_ctl(3I). .\" index@\f4io_get_term_reason()\fP \- determine how last read terminated@@@\f3io_get_term_reason(3I)\f1 .\" index@determine how last \s-1I/O\s+1 read terminated@@@\f3io_get_term_reason(3I)\f1 .\" index@last \s-1I/O\s+1 read, determine how terminated@@@\f3io_get_term_reason(3I)\f1 .\" index@\s-1I/O\s+1 read, determine how last terminated@@@\f3io_get_term_reason(3I)\f1 .\" index@read, \s-1I/O\s+1, determine how last terminated@@@\f3io_get_term_reason(3I)\f1 .\" index@terminated, determine how last \s-1I/O\s+1 read@@@\f3io_get_term_reason(3I)\f1 .\" .\" toc@\f3io_get_term_reason(3I)\f1:\0\0\f4io_get_term_reason()\fP@@@determine how last read terminated .\" .\" fileset_database@io_get_term.3i PROGRAMING-MAN .\" $Header: io_interrup.3i,v 74.1 95/05/10 21:50:31 ssa Exp $ .TA i .TH io_interrupt_ctl 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME io_interrupt_ctl(\|) \- enable/disable interrupts for the associated eid .SH SYNOPSIS .C "#include " .PP .C "int io_interrupt_ctl(int eid, int enable_flag);" .SH DESCRIPTION .I eid is the entity identifier of an open .SM HP-IB raw bus, Centronics-compatible parallel, or .SM GPIO device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .CR creat() call. .I flag is an integer which enables or disables interrupts for the associated .IR eid . A non-zero value enables interrupts. .PP Interrupts can be disabled or enabled as desired. When an interrupt occurs for a given .I eid the interrupts associated with this .I eid are automatically disabled from recurring. To re-enable interrupts for this .IR eid , use .CR io_interrupt_ctl() . .SH RETURN VALUE .C io_interrupt_ctl() returns 0 (zero) if successful, or \(mi1 if an error was encountered. .SH ERRORS .C io_interrupt_ctl() fails under the following situations, and sets .C errno (see .IR errno (2)) to the value indicated: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to a device that supports interrupts. .TP .SM [EINVAL] No interrupt conditions were specified for this .IR eid . .RE .SH AUTHOR .C io_interrupt_ctl() was developed by HP. .SH SEE ALSO dup(2), creat(2), fcntl(2), open(2), io_on_interrupt(3I). .\" index@\f4io_interrupt_ctl()\fP \- enable/disable interrupts for the associated \f4eid()\fP@@@\f3io_interrupt_ctl(3I)\f1 .\" index@enable or disable \s-1I/O\s+1 interrupts for the associated \f4eid()\fP@@@\f3io_interrupt_ctl(3I)\f1 .\" index@disable or enable \s-1I/O\s+1 interrupts for the associated \f4eid()\fP@@@\f3io_interrupt_ctl(3I)\f1 .\" index@\s-1I/O\s+1 interrupts for the associated \f4eid()\fP, disable or enable@@@\f3io_interrupt_ctl(3I)\f1 .\" index@interrupts for the associated \f4eid()\fP, disable or enable \s-1I/O\s+1@@@\f3io_interrupt_ctl(3I)\f1 .\" .\" toc@\f3io_interrupt_ctl(3I)\f1:\0\0\f4io_interrupt_ctl()\fP@@@enable/disable interrupts for the associated eid .\" .\" fileset_database@io_interrup.3i PROGRAMING-MAN .\" $Header: io_lock.3i,v 76.1 95/07/06 14:50:16 ssa Exp $ .TA i .TH io_lock 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME io_lock, io_unlock \- lock and unlock an interface .SH SYNOPSIS .C "#include " .PP .C "int io_lock(int eid);" .PP .C "int io_unlock(int eid);" .SH DESCRIPTION .C iolock() attempts to lock the interface associated with an entity identifier for the requesting process. Locking an interface gives exclusive use of the interface associated with the .I eid to the requesting process, thus avoiding unintended interference from other processes during a series of separate .SM I/O requests. All locks for a process are removed when the process closes the file or terminates. .PP .I eid is an entity identifier of an open .SM HP-IB, Centronics-compatible parallel, or .SM GPIO device file, obtained from an .CR open() , .CR dup() , .CR fcntl() , or .CR creat() call (see .IR open (2), .IR dup (2), .IR fcntl (2), and .IR creat (2)). .PP Other processes that attempt to access or lock a locked interface either return an error or sleep until the interface becomes unlocked. The action taken is determined by the current setting of the .C O_NDELAY flag (see .IR open (2). If the .C O_NDELAY flag is set, accesses to a locked interface fail and set .C errno to indicate the error. If the .C O_NDELAY flag is not set, accesses to a locked interface block until the interface is unlocked, the current timeout expires, or the request is interrupted by a signal. .PP A lock is associated with a process, not with an .IR eid . Locking an interface with a particular .I eid does not prevent the process that owns the lock from accessing the interface through another .IR eid . A lock associated with an .I eid is not inherited by a child process during a .C fork() (see .IR fork (2)). .PP Nested locking is fully supported. If a process owns a locked interface and calls a generic subroutine that does a lock and unlock, the calling process does not lose its lock on the interface. Locking requests produced by a given process for an interface already locked by the same process increment the current lock count for that interface. .PP .C io_unlock() allows a process to remove a lock from the interface associated with the .IR eid . A locked interface can be unlocked only by the process that directly owns the lock. When an unlock operation is applied to an .I eid that is currently multiply locked, the unlock operation decrements the current lock counter for that interface, and the interface remains locked until the count is reduced to zero. .SH RETURN VALUE .C io_lock() and .C io_unlock() return the integer value of the current lock count if successful. A lock count greater than zero indicates that the interface is still locked. A lock count of zero indicates that the interface is no longer locked. A \-1 indicates that an error has occured. .SH ERRORS .C io_lock() and .C io_unlock() fail in the following situations, and set .C errno (see .IR errno (2)) to the value indicated: .RS .TP 15 .SM [EACCES] An attempt was made to lock an interface locked by another process with .C O_NDELAY set. .TP .SM [EBADF] .I eid does not refer to an open file. .TP .SM [EINTR] A signal was caught while attempting to perform the lock with .C O_NDELAY clear. .TP .SM [EINVAL] an attempt was made to unlock when the interface is not locked. .TP .SM [ETIMEDOUT] A timeout occured while attempting to perform the lock with .SM O_NDELAY clear. .TP .SM [ENOTTY] .I eid does not refer to a channel device file. .TP .SM [EPERM] An attempt was made to unlock when lock is not owned by this user. .RE .SH WARNINGS .C io_lock() provides a mandatory lock enforced by the system, and should not be used with any interface supporting a system disk or swap device. .PP Processes that lock .SM HP-IB or .SM GPIO interfaces should clear all locks before exiting. The driver attempts to clear them if the process terminates unexpectedly; however, a lock might be left outstanding if the locker dies after creating new file descriptors (via .C fork() or .CR dup() ) that refer to the same device file. Ensuring that all open file descriptors on a given interface are closed remedies the situation. .SH AUTHOR .C io_lock() and .C io_unlock() were developed by HP. .SH SEE ALSO io_timeout_ctl(3I), open(2). .\" index@\f4io_lock(), io_unlock()\f1 \- lock and unlock an \s-1I/O\s+1 interface@@@\f3io_lock(3I)\f1 .\" index@\f4io_unlock()\f1 \- unlock an \s-1I/O\s+1 interface@@@\f3io_lock(3I)\f1 .\" index@lock or unlock an \s-1I/O\s+1 interface@@@\f3io_lock(3I)\f1 .\" index@unlock or lock an \s-1I/O\s+1 interface@@@\f3io_lock(3I)\f1 .\" index@\s-1I/O\s+1 interface, unlock or lock an@@@\f3io_lock(3I)\f1 .\" index@interface, unlock or lock an \s-1I/O\s+1@@@\f3io_lock(3I)\f1 .\" .\" toc@\f3io_lock(3I)\f1:\0\0\f4io_lock\f1, \f4io_unlock\f1@@@lock and unlock an interface .\" toc@\f4io_unlock\f1:\0\0lock and unlock an interface@@@see \f3io_lock(3I)\f1 .\" .\" links@io_lock.3i io_unlock.3i .\" .\" fileset_database@io_lock.3i PROGRAMING-MAN .\" $Header: io_on_inter.3i,v 76.1 95/06/20 14:51:34 ssa Exp $ .TA i .TH io_on_interrupt 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME io_on_interrupt(\|) \- device interrupt (fault) control .SH SYNOPSIS .C "#include " .PP .C "int (*io_on_interrupt(" .nf .PD 0 .IP .C "int eid," .C "struct interrupt_struct *causevec," .C "int (*handler)(int, struct interrupt_struct *)" .PP .C "))(int, struct interrupt_struct *);" .PD .fi .SH DESCRIPTION .I eid is an entity identifier of an open .SM HP-IB raw bus, Centronics-compatible parallel interface, or .SM GPIO device file, obtained from an .CR open() , .CR dup() , .CR fcntl() , or .CR creat() call. .PP .I causevec is a pointer to a structure of the form: .nf .IP .C "struct interrupt_struct {" .C " integer cause;" .C " integer mask;" .C }; .fi .PP The .C interrupt_struct structure is defined in the file .CR dvio.h . .PP .I cause is a bit vector specifying which of the interrupt or fault events can cause the handler routine to be invoked. The interrupt causes are often specific to the type of interface being considered. Also, certain exception (error) conditions can be handled using the .C io_on_interrupt() capability. Specifying a zero valued .I cause vector effectively turns off the interrupt for that .IR eid . .PP The .I mask parameter is used when an .SM HP-IB parallel poll interrupt is being defined. .I mask is an integer that specifies which parallel poll response lines are of interest. The value of .I mask is viewed as an 8-bit binary number where the least significant bit corresponds to line .SM DIO1; the most significant bit to line .SM DIO8. For example, to activate an interrupt handler when a response occurs on lines 2 or 6, the correct binary number is 00100010. Thus a hexadecimal value of 22 is the correct argument value for .IR mask . .PP When an enabled interrupt condition on the specified .I eid occurs, the receiving process executes the interrupt-handler function pointed to by .IR handler . The entity identifier .I eid and the interrupt condition .I cause are returned as the first and second parameters, respectively. .PP When an interrupt that is to be caught occurs during a .CR read() , .CR write() , .CR open() , or .C ioctl() system call on a slow device such as a terminal (but not a file), during a .C pause() system call, a .CR sigpause() system call, or a .CR wait() system call that does not return immediately due to the existence of a previously stopped or zombie process, the interrupt handling function is executed and the interrupted system call returns \(mi1 to the calling process with .C errno set to .SM EINTR. .PP Interrupt .I handlers are not inherited across a .CR fork() . .IR eid s for the same device file produced by .C dup() share the same .IR handler . .PP An interrupt for a given .I eid is implicitly disabled after the occurrence of the event. The interrupt condition can be re-enabled by using .C io_interrupt_ctl() (see .IR io_interrupt_ctl (3I)). .PP When an event specified by .I cause occurs, the receiving process executes the interrupt .I handler function pointed to by .IR handler . When the .I handler returns, the user process resumes at the execution point where the event occurred. .PP Two parameters are passed to .IR handler : the .I eid associated with the event, and a pointer to a .C causevec structure. The cause of the interrupt can be determined by the value returned in the .I cause field of the .C causevec structure (more than 1 bit can be set, indicating that more than 1 interrupting condition has occurred). If the interrupt .I handler was invoked due to a parallel poll interrupt, the .I mask field of the .C causevec structure contains the parallel poll response byte. .SS \s-1HP-IB\s0 Interrupts This section describes interrupt causes specific to an .SM HP-IB device. For an .SM HP-IB device, the cause is a bit vector which is used as follows. To enable a given event, the appropriate bit (in .IR cause ), shown below, must be set to .CR 1 : .RS .TP 10 .C SRQ .SM SRQ and active controller .PD 0 .TP .C TLK Talker addressed .TP .C LTN Listener addressed .TP .C TCT Controller in charge .TP .C IFC .SM IFC has been asserted .TP .C REN Remote enable .TP .C DCL Device clear .TP .C GET Group execution trigger .TP .C PPOLL Parallel poll .PD .RE .SS \s-1GPIO\s0 Interrupts This section describes interrupt causes specific to a .SM GPIO device. For a .SM GPIO device, .I cause is a bit vector which is used as follows. To enable a given event, the appropriate bit (in .IR cause ), shown below, must be set to .CR 1 : .RS .TP 10 .C EIR External interrupt .PD 0 .TP .C SIE0 Status line 0 .TP .C SIE1 Status line 1 .PD .RE .SS Parallel Interrupts This section describes interrupt causes specific to a Centronics-compatible parallel device. For a Centronics-compatible parallel device, .I cause is a bit vector which is used as follows. To enable a given event, the appropriate bit (in .IR cause ), shown below, must be set to .CR 1 : .RS .TP 10 .C NERROR Nerror interrupt .PD 0 .TP .C SELECT Select interrupt .TP .C PE Paper error interrupt .PD .RE .SH RETURN VALUE .C io_on_interrupt() returns a pointer to the previous .I handler if the new .I handler is successfully installed; otherwise it returns a \(mi1 and sets .C errno to indicate the error. .SH ERRORS .C io_on_interrupt() fails for any of the following reasons and sets .C errno to the value indicated: .RS .TP 15 .SM [EACCES] The interface associated with this .I eid is locked by another process and .C O_NDELAY is set for this .I eid (see .IR iolock (3I)). .TP .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to a .SM GPIO, Centronics-compatible parallel, or a raw .SM HP-IB device file. .TP .SM [EFAULT] .I handler points to an illegal address. The reliable detection of this error is implementation dependent. .TP .SM [EFAULT] .I causevec points to an illegal address. The reliable detection of this error is implementation dependent. .RE .SH DEPENDENCIES For the .SM HP 27114 AFI interface, only the .SM EIR interrupt is available. .SH AUTHOR .C io_on_interrupt() was developed by HP. .SH SEE ALSO dup(2), creat(2), fcntl(2), open(2), pause(2), sigpause(2), io_interrupt_ctl(3I). .\" index@\f4io_on_interrupt()\fP \(mi device \s-1I/O\s+1 interrupt (fault) control@@@\f3io_on_interrupt(3I)\f1 .\" index@device \s-1I/O\s+1 interrupt (fault) control@@@\f3io_on_interrupt(3I)\f1 .\" index@\s-1I/O\s+1 device interrupt (fault) control@@@\f3io_on_interrupt(3I)\f1 .\" index@define \s-1I/O\s+1 device interrupt (fault) conditions@@@\f3io_on_interrupt(3I)\f1 .\" index@interrupt (fault) conditions, define for \s-1I/O\s+1 device@@@\f3io_on_interrupt(3I)\f1 .\" index@conditions, define for \s-1I/O\s+1 device interrupt@@@\f3io_on_interrupt(3I)\f1 .\" index@fault (interrupt) conditions, define for \s-1I/O\s+1 device@@@\f3io_on_interrupt(3I)\f1 .\" .\" toc@\f3io_on_interrupt(3I)\f1:\0\0\f4io_on_interrupt()\fP@@@device interrupt (fault) control .\" .\" fileset_database@io_on_inter.3i PROGRAMING-MAN .\" $Header: io_reset.3i,v 74.1 95/05/10 21:51:41 ssa Exp $ .TA i .TH io_reset 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME io_reset(\|) \- reset an I/O interface .SH SYNOPSIS .C "#include " .PP .C "int io_reset(int eid);" .SH DESCRIPTION .C io_reset() resets the interface associated with the device file that was opened. It also pulses the peripheral reset line on the .SM GPIO interface, or the .SM IFC line on the .SM HP-IB. .I eid is an entity identifier of an open .SM HP-IB, Centronics-compatible parallel interface, or .SM GPIO device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .CR creat() call. .PP .C io_reset() also causes an interface to go through its self-test, and returns a failure indication if the interface fails its test. .SH RETURN VALUE .C io_reset() returns 0 (zero) if successful, or \(mi1 if an error was encountered. .SH ERRORS .C io_reset() fails under the following circumstances, and sets .C errno (see .IR errno (2)) to the value indicated: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to a channel device file. .TP .SM [EIO] Interface could not be reset or failed self-test. .TP .SM [EACCES] The interface associated with this .I eid is locked by another process and .C O_NDELAY is set for this .I eid (see .IR io_lock (3I)). .RE .SH DEPENDENCIES .SS Series 300/400: When an .SM HP-IB interface is reset, the interrupt mask is set to 0, the parallel poll response is set to 0, the serial poll response is set to 0, the .SM HP-IB address is assigned its powerup default value, the .SM IFC line is pulsed (if system controller), the card is put on line, and .SM REN is set (if system controller). .PP When a .SM GPIO interface is reset, the peripheral reset line is pulled low, the .SM PCTL line is placed in the clear state, and if the .SM DOUT CLEAR jumper is installed, the data out lines are all cleared. The interrupt enable bit is also cleared. .PP Interface self-test is not supported. .SH AUTHOR .C io_reset() was developed by HP. .\" index@\f4io_reset()\fP \- reset an \s-1I/O\s+1 interface@@@\f3io_reset(3I)\f1 .\" index@reset an \s-1I/O\s+1 interface@@@\f3io_reset(3I)\f1 .\" index@\s-1I/O\s+1 interface, reset an@@@\f3io_reset(3I)\f1 .\" index@interface, reset an \s-1I/O\s+1@@@\f3io_reset(3I)\f1 .\" .\" toc@\f3io_reset(3I)\f1:\0\0\f4io_reset()\fP@@@reset an \s-1I/O\s+1 interface .\" .\" fileset_database@io_reset.3i PROGRAMING-MAN .\" $Header: io_speed_ct.3i,v 76.1 95/06/20 14:51:54 ssa Exp $ .TA i .TH io_speed_ctl 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME io_speed_ctl(\|) \- inform system of required transfer speed .SH SYNOPSIS .C "#include " .PP .C "int io_speed_ctl(int eid, int speed);" .SH DESCRIPTION .C io_speed_ctl() selects the data transfer speed for a data path used for a particular interface. The transfer method (i.e., .SM DMA or fast-handshake) chosen by the system is determined by the speed requirements. .PP .I eid is an entity identifier of an open .SM HP-IB raw bus, Centronics-compatible parallel, or .SM GPIO device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .CR creat() call. .I speed is an integer specifying the data transfer speed in Kbytes per second (one Kbyte equals 1024 bytes). .SH RETURN VALUE .C io_speed_ctl() returns 0 if successful, and \(mi1 otherwise. .SH ERRORS .C io_speed_ctl() fails under the following condition, and sets .C errno to the value indicated: .RS .TP 15 .SM [ENOTTY] .I eid does not refer to channel device file. .TP .SM [EBADF] .I eid does not refer to an open file. .RE .SH DEPENDENCIES .SM DMA is the only supported transfer method. .SH AUTHOR .C io_speed_ctl() was developed by HP. .\" index@\f4io_speed_ctl()\fP \- inform system of required transfer speed@@@\f3io_speed_ctl(3I)\f1 .\" index@transfer speed, inform system of required minimum \s-1I/O\s+1@@@\f3io_speed_ctl(3I)\f1 .\" index@data transfer rate, inform system of required minimum \s-1I/O\s+1@@@\f3io_speed_ctl(3I)\f1 .\" index@required minimum \s-1I/O\s+1 data transfer rate, inform system of@@@\f3io_speed_ctl(3I)\f1 .\" index@minimum \s-1I/O\s+1 data transfer rate, inform system of required@@@\f3io_speed_ctl(3I)\f1 .\" index@rate of \s-1I/O\s+1 data transfer, inform system of required minimum@@@\f3io_speed_ctl(3I)\f1 .\" index@speed, inform system of required minimum \s-1I/O\s+1 transfer@@@\f3io_speed_ctl(3I)\f1 .\" .\" toc@\f3io_speed_ctl(3I)\f1:\0\0\f4io_speed_ctl()\fP@@@inform system of required transfer speed .\" .\" fileset_database@io_speed_ct.3i PROGRAMING-MAN .\" $Header: io_timeout_.3i,v 76.1 95/06/20 14:53:05 ssa Exp $ .TA i .TH io_timeout_ctl 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME io_timeout_ctl(\|) \- establish a time limit for I/O operations .SH SYNOPSIS .C "#include " .PP .C "int io_timeout_ctl(int eid, long time);" .SH DESCRIPTION .C io_timeout_ctl() assigns a timeout value to the specified .I eid (entity identifier). .I eid is an entity identifier of an open .SM HP-IB raw bus, auto-addressed, Centronics-compatible parallel, or .SM GPIO device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .CR creat() call. .I time is a long integer value specifying the length of the timeout in microseconds. A value of 0 for .I time specifies no timeout (infinity). .PP This timeout applies to future read and write requests on this .IR eid . If a read or write request does not complete within the specified time limit, the request is aborted and returns an error indication. If an operation is aborted due to a timeout, .C errno is set to .SM ETIMEDOUT. .PP Although the timeout value is specified in microseconds, the resolution of the timeout is system-dependent. For example, a particular system might have a resolution of 10 milliseconds, in which case the specified timeout value is rounded up to the next 10 msec boundary. A timeout value of zero means that the system never causes a timeout. When a file is opened, a zero timeout value is assigned by default. .PP Entity identifiers for the same device file obtained by separate .C open() calls have their own timeout values associated with them. Entity identifiers for the same device file obtained by .C dup() or inherited by a .C fork() call share the same timeout value. In the latter case, if one process changes the timeout, the new timeout is in effect for all such .IR eid s. .SH RETURN VALUE .C io_timeout_ctl() returns 0 (zero) if successful, or \(mi1 if an error was encountered. .SH ERRORS .C io_timeout_ctl() fails under the following circumstances, and sets .C errno (see .IR errno (2)) to the value indicated: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to a channel device file. .RE .SH AUTHOR .C io_timeout_ctl() was developed by HP. .\" index@\f4io_timeout_ctl()\fP \- establish a time limit for \s-1I/O\s+1 operations@@@\f3io_timeout_ctl(3I)\f1 .\" index@establish time limit for \s-1I/O\s+1 operations@@@\f3io_timeout_ctl(3I)\f1 .\" index@set time limit for \s-1I/O\s+1 operations@@@\f3io_timeout_ctl(3I)\f1 .\" index@time limit for \s-1I/O\s+1 operations, set@@@\f3io_timeout_ctl(3I)\f1 .\" index@timeout limit for \s-1I/O\s+1 operations, set@@@\f3io_timeout_ctl(3I)\f1 .\" index@limit for \s-1I/O\s+1 operations, set time@@@\f3io_timeout_ctl(3I)\f1 .\" index@\s-1I/O\s+1 operations, set time limit for@@@\f3io_timeout_ctl(3I)\f1 .\" index@operations, set time limit for \s-1I/O\s+1@@@\f3io_timeout_ctl(3I)\f1 .\" .\" toc@\f3io_timeout_ctl(3I)\f1:\0\0\f4io_timeout_ctl()\fP@@@establish a time limit for \s-1I/O\s+1 operations .\" .\" fileset_database@io_timeout_.3i PROGRAMING-MAN .\" $Header: io_lock.3i,v 76.1 95/07/06 14:50:16 ssa Exp $ .TA i .TH io_lock 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME io_lock, io_unlock \- lock and unlock an interface .SH SYNOPSIS .C "#include " .PP .C "int io_lock(int eid);" .PP .C "int io_unlock(int eid);" .SH DESCRIPTION .C iolock() attempts to lock the interface associated with an entity identifier for the requesting process. Locking an interface gives exclusive use of the interface associated with the .I eid to the requesting process, thus avoiding unintended interference from other processes during a series of separate .SM I/O requests. All locks for a process are removed when the process closes the file or terminates. .PP .I eid is an entity identifier of an open .SM HP-IB, Centronics-compatible parallel, or .SM GPIO device file, obtained from an .CR open() , .CR dup() , .CR fcntl() , or .CR creat() call (see .IR open (2), .IR dup (2), .IR fcntl (2), and .IR creat (2)). .PP Other processes that attempt to access or lock a locked interface either return an error or sleep until the interface becomes unlocked. The action taken is determined by the current setting of the .C O_NDELAY flag (see .IR open (2). If the .C O_NDELAY flag is set, accesses to a locked interface fail and set .C errno to indicate the error. If the .C O_NDELAY flag is not set, accesses to a locked interface block until the interface is unlocked, the current timeout expires, or the request is interrupted by a signal. .PP A lock is associated with a process, not with an .IR eid . Locking an interface with a particular .I eid does not prevent the process that owns the lock from accessing the interface through another .IR eid . A lock associated with an .I eid is not inherited by a child process during a .C fork() (see .IR fork (2)). .PP Nested locking is fully supported. If a process owns a locked interface and calls a generic subroutine that does a lock and unlock, the calling process does not lose its lock on the interface. Locking requests produced by a given process for an interface already locked by the same process increment the current lock count for that interface. .PP .C io_unlock() allows a process to remove a lock from the interface associated with the .IR eid . A locked interface can be unlocked only by the process that directly owns the lock. When an unlock operation is applied to an .I eid that is currently multiply locked, the unlock operation decrements the current lock counter for that interface, and the interface remains locked until the count is reduced to zero. .SH RETURN VALUE .C io_lock() and .C io_unlock() return the integer value of the current lock count if successful. A lock count greater than zero indicates that the interface is still locked. A lock count of zero indicates that the interface is no longer locked. A \-1 indicates that an error has occured. .SH ERRORS .C io_lock() and .C io_unlock() fail in the following situations, and set .C errno (see .IR errno (2)) to the value indicated: .RS .TP 15 .SM [EACCES] An attempt was made to lock an interface locked by another process with .C O_NDELAY set. .TP .SM [EBADF] .I eid does not refer to an open file. .TP .SM [EINTR] A signal was caught while attempting to perform the lock with .C O_NDELAY clear. .TP .SM [EINVAL] an attempt was made to unlock when the interface is not locked. .TP .SM [ETIMEDOUT] A timeout occured while attempting to perform the lock with .SM O_NDELAY clear. .TP .SM [ENOTTY] .I eid does not refer to a channel device file. .TP .SM [EPERM] An attempt was made to unlock when lock is not owned by this user. .RE .SH WARNINGS .C io_lock() provides a mandatory lock enforced by the system, and should not be used with any interface supporting a system disk or swap device. .PP Processes that lock .SM HP-IB or .SM GPIO interfaces should clear all locks before exiting. The driver attempts to clear them if the process terminates unexpectedly; however, a lock might be left outstanding if the locker dies after creating new file descriptors (via .C fork() or .CR dup() ) that refer to the same device file. Ensuring that all open file descriptors on a given interface are closed remedies the situation. .SH AUTHOR .C io_lock() and .C io_unlock() were developed by HP. .SH SEE ALSO io_timeout_ctl(3I), open(2). .\" index@\f4io_lock(), io_unlock()\f1 \- lock and unlock an \s-1I/O\s+1 interface@@@\f3io_lock(3I)\f1 .\" index@\f4io_unlock()\f1 \- unlock an \s-1I/O\s+1 interface@@@\f3io_lock(3I)\f1 .\" index@lock or unlock an \s-1I/O\s+1 interface@@@\f3io_lock(3I)\f1 .\" index@unlock or lock an \s-1I/O\s+1 interface@@@\f3io_lock(3I)\f1 .\" index@\s-1I/O\s+1 interface, unlock or lock an@@@\f3io_lock(3I)\f1 .\" index@interface, unlock or lock an \s-1I/O\s+1@@@\f3io_lock(3I)\f1 .\" .\" toc@\f3io_lock(3I)\f1:\0\0\f4io_lock\f1, \f4io_unlock\f1@@@lock and unlock an interface .\" toc@\f4io_unlock\f1:\0\0lock and unlock an interface@@@see \f3io_lock(3I)\f1 .\" .\" links@io_lock.3i io_unlock.3i .\" .\" fileset_database@io_lock.3i PROGRAMING-MAN .\" $Header: io_width_ct.3i,v 74.1 95/05/10 21:52:28 ssa Exp $ .TA i .TH io_width_ctl 3I "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" not supported on Series 700 .SH NAME io_width_ctl \- set width of data path .SH SYNOPSIS .C "#include " .PP .C "int io_width_ctl(int eid, int width);" .SH DESCRIPTION .C io_width_ctl() enables you to select the width of the data path to be used for a particular interface. .I eid is an entity identifier of an open .SM HP-IB, Centronics-compatible parallel interface, or .SM GPIO device file obtained from an .CR open() , .CR dup() , .CR fcntl() , or .C creat() call. .I width is an integer specifying the width of the data path in bits. .PP An error is given if an invalid width is specified. Specifying a width with this function sets the width for all users of the device file associated with the given entity id. When first opened, the default width is 8 bits. .PP For the .SM GPIO interface only widths of 8 and 16 bits are currently supported. For the .SM HP-IB and Centronics-compatible parallel interfaces, only a width of 8 bits is supported. .SH RETURN VALUE .C io_width_ctl() returns 0 if successful, and \(mi1 if an error was encountered. .SH ERRORS .C io_width_ctl() fails under the following circumstances and sets .C errno (see .IR errno (2)) to the value indicated: .RS .TP 15 .SM [EBADF] .I eid does not refer to an open file. .TP .SM [ENOTTY] .I eid does not refer to a channel device file. .TP .SM [EINVAL] the specified .I width is not supported on this device file. .RE .SH AUTHOR .C io_width_ctl() was developed by HP. .\" index@\f4io_width_ctl()\fP \- set width (in bits) of data path@@@\f3io_width_ctl(3I)\f1 .\" index@set width (in bits) of data path@@@\f3io_width_ctl(3I)\f1 .\" index@width (in bits) of data path, set@@@\f3io_width_ctl(3I)\f1 .\" index@data path width (in bits), set@@@\f3io_width_ctl(3I)\f1 .\" index@\s-1I/O\s+1 data path width (in bits), set@@@\f3io_width_ctl(3I)\f1 .\" .\" toc@\f3io_width_ctl(3I)\f1:\0\0\f4io_width_ctl()\fP@@@set width of data path .\" .\" fileset_database@io_width_ct.3i PROGRAMING-MAN .\" $Header: is_linetouched.3x,v 76.2 95/08/01 11:31:01 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH is_linetouched 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 manpage_touch .SH NAME is_linetouched, is_wintouched, touchline, untouchwin, wtouchln \(em window refresh control functions .SH SYNOPSIS .C "#include " .P .C "bool is_linetouched(WINDOW *\f2win\fP, int \f2line\fP);" .P .C "bool is_wintouched(WINDOW *\f2win\fP);" .P .C "int touchline(WINDOW *\f2win\fP, int \f2start\fP, int \f2count\fP);" .P .C "int untouchwin(WINDOW *\f2win\fP);" .P .C "int wtouchln(WINDOW *\f2win\fP, int \f2y\fP, int \f2n\fP, int \f2changed\fP);" .SH DESCRIPTION The .Fn touchline function only touches \f2count\f1 lines, beginning with line \f2start\f1. .P The .Fn untouchwin function marks all lines in the window as unchanged since the last refresh operation. .P Calling .Fn wtouchln , if \f2changed\f1 is 1, touches \f2n\f1 lines in the specified window, starting at line \f2y\f1. If \f2changed\f1 is 0, .Fn wtouchln marks such lines as unchanged since the last refresh operation. .P The .Fn is_wintouched function determines whether the specified window is touched. The .Fn is_linetouched function determines whether line .I line of the specified window is touched. .SH "RETURN VALUE" The .Fn is_linetouched and .Fn is_wintouched functions return TRUE if any of the specified lines, or the specified window, respectively, has been touched since the last refresh operation. Otherwise, they return FALSE. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. Exceptions to this are noted in the preceding function descriptions. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Calling .Fn touchwin or .Fn touchline is sometimes necessary when using overlapping windows, since a change to one window affects the other window, but the records of which lines have been changed in the other window do not reflect the change. .SH "SEE ALSO" \f3Screens, Windows and Terminals\f1 in curs_intro, doupdate(), touchwin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3is_linetouched(3X)\f1:\0\0\f4is_linetouched()\f1, \f4is_wintouched()\f1, \f4touchline()\f1, \f4untouchwin()\f1, \n\f4wtouchln()\f1@@@window refresh control functions .\" toc@\f4is_wintouched()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4touchline()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4untouchwin()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4wtouchln()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" .\" index@\f4is_linetouched()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4is_wintouched()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4touchline()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4untouchwin()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4wtouchln()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f1window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f1refresh control functions for window@@@\f3is_linetouched(3X)\f1 .\" index@\f1control functions, window refresh@@@\f3is_linetouched(3X)\f1 .\" index@\f1functions, window refresh control@@@\f3is_linetouched(3X)\f1 .\" .\" links@is_linetouched.3x is_wintouched.3x .\" links@is_linetouched.3x touchline.3x .\" links@is_linetouched.3x untouchwin.3x .\" links@is_linetouched.3x wtouchln.3x .\" .\" fileset_database@is_linetouched.3x CURS-ENG-A-MAN .\" $Header: is_linetouched.3x,v 76.2 95/08/01 11:31:01 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH is_linetouched 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 manpage_touch .SH NAME is_linetouched, is_wintouched, touchline, untouchwin, wtouchln \(em window refresh control functions .SH SYNOPSIS .C "#include " .P .C "bool is_linetouched(WINDOW *\f2win\fP, int \f2line\fP);" .P .C "bool is_wintouched(WINDOW *\f2win\fP);" .P .C "int touchline(WINDOW *\f2win\fP, int \f2start\fP, int \f2count\fP);" .P .C "int untouchwin(WINDOW *\f2win\fP);" .P .C "int wtouchln(WINDOW *\f2win\fP, int \f2y\fP, int \f2n\fP, int \f2changed\fP);" .SH DESCRIPTION The .Fn touchline function only touches \f2count\f1 lines, beginning with line \f2start\f1. .P The .Fn untouchwin function marks all lines in the window as unchanged since the last refresh operation. .P Calling .Fn wtouchln , if \f2changed\f1 is 1, touches \f2n\f1 lines in the specified window, starting at line \f2y\f1. If \f2changed\f1 is 0, .Fn wtouchln marks such lines as unchanged since the last refresh operation. .P The .Fn is_wintouched function determines whether the specified window is touched. The .Fn is_linetouched function determines whether line .I line of the specified window is touched. .SH "RETURN VALUE" The .Fn is_linetouched and .Fn is_wintouched functions return TRUE if any of the specified lines, or the specified window, respectively, has been touched since the last refresh operation. Otherwise, they return FALSE. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. Exceptions to this are noted in the preceding function descriptions. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Calling .Fn touchwin or .Fn touchline is sometimes necessary when using overlapping windows, since a change to one window affects the other window, but the records of which lines have been changed in the other window do not reflect the change. .SH "SEE ALSO" \f3Screens, Windows and Terminals\f1 in curs_intro, doupdate(), touchwin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3is_linetouched(3X)\f1:\0\0\f4is_linetouched()\f1, \f4is_wintouched()\f1, \f4touchline()\f1, \f4untouchwin()\f1, \n\f4wtouchln()\f1@@@window refresh control functions .\" toc@\f4is_wintouched()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4touchline()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4untouchwin()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4wtouchln()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" .\" index@\f4is_linetouched()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4is_wintouched()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4touchline()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4untouchwin()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4wtouchln()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f1window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f1refresh control functions for window@@@\f3is_linetouched(3X)\f1 .\" index@\f1control functions, window refresh@@@\f3is_linetouched(3X)\f1 .\" index@\f1functions, window refresh control@@@\f3is_linetouched(3X)\f1 .\" .\" links@is_linetouched.3x is_wintouched.3x .\" links@is_linetouched.3x touchline.3x .\" links@is_linetouched.3x untouchwin.3x .\" links@is_linetouched.3x wtouchln.3x .\" .\" fileset_database@is_linetouched.3x CURS-ENG-A-MAN .\" $Header: ctype.3c,v 72.6 94/11/28 08:25:33 ssa Exp $ .TA c .TH ctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isalpha(\|), isupper(\|), islower(\|), isdigit(\|), isxdigit(\|), isalnum(\|), isspace(\|), ispunct(\|), isprint(\|), isgraph(\|), iscntrl(\|), isascii(\|) \- classify characters .SH SYNOPSIS .C "#include " .PP .C "int isalnum(int c);" .br .C "int isalpha(int c);" .br .C "int iscntrl(int c);" .br .C "int isdigit(int c);" .br .C "int isgraph(int c);" .br .C "int islower(int c);" .br .C "int isprint(int c);" .br .C "int ispunct(int c);" .br .C "int isspace(int c);" .br .C "int isupper(int c);" .br .C "int isxdigit(int c);" .br .C "int isascii(int c);" .SH DESCRIPTION These functions classify character-coded integer values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). Each function is a predicate returning non-zero for true, zero for false. .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP .C isascii() is defined on all integer values; the other functions are defined for the range .C -1 .SM (EOF) through .CR 255 . .PP The functions return non-zero under the following circumstances; zero otherwise: .RS .TP 18 .CR isalpha( c ) .I c is a letter. .TP .CR isupper( c ) .I c is an uppercase letter. .TP .CR islower( c ) .I c is a lowercase letter. .TP .CR isdigit( c ) .I c is a decimal digit (in .SM ASCII\c : characters [0-9]). .TP .CR isxdigit( c ) .I c is a hexadecimal digit (in .SM ASCII\c : characters [0-9], [A-F] or [a-f]). .TP .CR isalnum( c ) .I c is an alphanumeric (letters or digits). .TP .CR isspace( c ) .I c is a character that creates ``white space'' in displayed text (in .SM ASCII\c : space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CR ispunct( c ) .I c is a punctuation character (in .SM ASCII\c : any printing character except the space character (040), digits, letters). .TP .CR isprint( c ) .I c is a printing character. .TP .CR isgraph( c ) .I c is a visible character (in .SM ASCII\c : printing characters, excluding the space character (040)). .TP .CR iscntrl( c ) .I c is a control character (in .SM ASCII\c : character codes less than 040 and the delete character (0177)). .TP .CR isascii( c ) .I c is any .SM ASCII character code between 0 and 0177, inclusive. .RE .PP If the argument to any of these functions is outside the domain of the function, the result is undefined. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS These functions are supplied both as library functions and as macros defined in the .RC < ctype.h > header. Normally, the macro versions are used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parenthesis or take its address. The following example uses the library functions for .CR isalpha() , .CR isdigit() , and .CR isspace() : .nf .IP .C "#include " .C "#undef isalpha" \h'.5i'... .C "main() .C "{ .C " int (*ctype_func)();" \h'.8i'... .C " if ( isalpha(c) )" \h'.8i'... .C " if ( (isdigit)(c) )" \h'.8i'... .C " ctype_func = isspace;" \h'.8i'... .C } .fi .SH AUTHOR .CR ctype() was developed by IBM, OSF, and HP. .SH SEE ALSO setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR isalnum() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isalpha() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR iscntrl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isgraph() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR islower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isprint() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ispunct() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isspace() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isxdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4isalpha()\f1 \- character is alpha@@@\f3ctype(3C)\f1 .\" index@\f4isupper()\f1 \- character is uppercase@@@\f3ctype(3C)\f1 .\" index@\f4islower()\f1 \- character is lowercase@@@\f3ctype(3C)\f1 .\" index@\f4isdigit()\f1 \- character is a digit@@@\f3ctype(3C)\f1 .\" index@\f4isxdigit()\f1 \- character is a hexadecimal digit@@@\f3ctype(3C)\f1 .\" index@\f4isalnum()\f1 \- character is alphanumeric@@@\f3ctype(3C)\f1 .\" index@\f4isspace()\f1 \- character is whitespace@@@\f3ctype(3C)\f1 .\" index@\f4ispunct()\f1 \- character is punctuation@@@\f3ctype(3C)\f1 .\" index@\f4isprint()\f1 \- character is a printing character@@@\f3ctype(3C)\f1 .\" index@\f4isgraph()\f1 \- character is a visible character@@@\f3ctype(3C)\f1 .\" index@\f4iscntrl()\f1 \- character is a control character@@@\f3ctype(3C)\f1 .\" index@\f4isascii()\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3ctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3ctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3ctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3ctype(3C)\f1 .\" .\" toc@\f3ctype(3C)\f1:\0\0\f4isalpha()\f1, \f4isupper()\f1, \f4islower()\f1, \f4isdigit()\f1, \f4isxdigit()\f1, \f4isalnum()\f1, \f4isspace()\f1,\n\f4ispunct()\f1, \f4isprint()\f1, \f4isgraph()\f1, \f4iscntrl()\f1, \f4isascii()\f1@@@classify characters .\" toc@\f4isalpha()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isupper()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4islower()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isxdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isalnum()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isspace()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4ispunct()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isprint()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isgraph()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4iscntrl()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isascii()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" .\" links@ctype.3c isalpha.3c .\" links@ctype.3c isupper.3c .\" links@ctype.3c islower.3c .\" links@ctype.3c isdigit.3c .\" links@ctype.3c isxdigit.3c .\" links@ctype.3c isalnum.3c .\" links@ctype.3c isspace.3c .\" links@ctype.3c ispunct.3c .\" links@ctype.3c isprint.3c .\" links@ctype.3c isgraph.3c .\" links@ctype.3c iscntrl.3c .\" links@ctype.3c isascii.3c .\" .\" fileset_database@ctype.3c PROGRAMING-MAN .\" $Header: ctype.3c,v 72.6 94/11/28 08:25:33 ssa Exp $ .TA c .TH ctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isalpha(\|), isupper(\|), islower(\|), isdigit(\|), isxdigit(\|), isalnum(\|), isspace(\|), ispunct(\|), isprint(\|), isgraph(\|), iscntrl(\|), isascii(\|) \- classify characters .SH SYNOPSIS .C "#include " .PP .C "int isalnum(int c);" .br .C "int isalpha(int c);" .br .C "int iscntrl(int c);" .br .C "int isdigit(int c);" .br .C "int isgraph(int c);" .br .C "int islower(int c);" .br .C "int isprint(int c);" .br .C "int ispunct(int c);" .br .C "int isspace(int c);" .br .C "int isupper(int c);" .br .C "int isxdigit(int c);" .br .C "int isascii(int c);" .SH DESCRIPTION These functions classify character-coded integer values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). Each function is a predicate returning non-zero for true, zero for false. .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP .C isascii() is defined on all integer values; the other functions are defined for the range .C -1 .SM (EOF) through .CR 255 . .PP The functions return non-zero under the following circumstances; zero otherwise: .RS .TP 18 .CR isalpha( c ) .I c is a letter. .TP .CR isupper( c ) .I c is an uppercase letter. .TP .CR islower( c ) .I c is a lowercase letter. .TP .CR isdigit( c ) .I c is a decimal digit (in .SM ASCII\c : characters [0-9]). .TP .CR isxdigit( c ) .I c is a hexadecimal digit (in .SM ASCII\c : characters [0-9], [A-F] or [a-f]). .TP .CR isalnum( c ) .I c is an alphanumeric (letters or digits). .TP .CR isspace( c ) .I c is a character that creates ``white space'' in displayed text (in .SM ASCII\c : space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CR ispunct( c ) .I c is a punctuation character (in .SM ASCII\c : any printing character except the space character (040), digits, letters). .TP .CR isprint( c ) .I c is a printing character. .TP .CR isgraph( c ) .I c is a visible character (in .SM ASCII\c : printing characters, excluding the space character (040)). .TP .CR iscntrl( c ) .I c is a control character (in .SM ASCII\c : character codes less than 040 and the delete character (0177)). .TP .CR isascii( c ) .I c is any .SM ASCII character code between 0 and 0177, inclusive. .RE .PP If the argument to any of these functions is outside the domain of the function, the result is undefined. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS These functions are supplied both as library functions and as macros defined in the .RC < ctype.h > header. Normally, the macro versions are used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parenthesis or take its address. The following example uses the library functions for .CR isalpha() , .CR isdigit() , and .CR isspace() : .nf .IP .C "#include " .C "#undef isalpha" \h'.5i'... .C "main() .C "{ .C " int (*ctype_func)();" \h'.8i'... .C " if ( isalpha(c) )" \h'.8i'... .C " if ( (isdigit)(c) )" \h'.8i'... .C " ctype_func = isspace;" \h'.8i'... .C } .fi .SH AUTHOR .CR ctype() was developed by IBM, OSF, and HP. .SH SEE ALSO setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR isalnum() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isalpha() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR iscntrl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isgraph() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR islower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isprint() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ispunct() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isspace() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isxdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4isalpha()\f1 \- character is alpha@@@\f3ctype(3C)\f1 .\" index@\f4isupper()\f1 \- character is uppercase@@@\f3ctype(3C)\f1 .\" index@\f4islower()\f1 \- character is lowercase@@@\f3ctype(3C)\f1 .\" index@\f4isdigit()\f1 \- character is a digit@@@\f3ctype(3C)\f1 .\" index@\f4isxdigit()\f1 \- character is a hexadecimal digit@@@\f3ctype(3C)\f1 .\" index@\f4isalnum()\f1 \- character is alphanumeric@@@\f3ctype(3C)\f1 .\" index@\f4isspace()\f1 \- character is whitespace@@@\f3ctype(3C)\f1 .\" index@\f4ispunct()\f1 \- character is punctuation@@@\f3ctype(3C)\f1 .\" index@\f4isprint()\f1 \- character is a printing character@@@\f3ctype(3C)\f1 .\" index@\f4isgraph()\f1 \- character is a visible character@@@\f3ctype(3C)\f1 .\" index@\f4iscntrl()\f1 \- character is a control character@@@\f3ctype(3C)\f1 .\" index@\f4isascii()\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3ctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3ctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3ctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3ctype(3C)\f1 .\" .\" toc@\f3ctype(3C)\f1:\0\0\f4isalpha()\f1, \f4isupper()\f1, \f4islower()\f1, \f4isdigit()\f1, \f4isxdigit()\f1, \f4isalnum()\f1, \f4isspace()\f1,\n\f4ispunct()\f1, \f4isprint()\f1, \f4isgraph()\f1, \f4iscntrl()\f1, \f4isascii()\f1@@@classify characters .\" toc@\f4isalpha()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isupper()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4islower()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isxdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isalnum()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isspace()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4ispunct()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isprint()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isgraph()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4iscntrl()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isascii()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" .\" links@ctype.3c isalpha.3c .\" links@ctype.3c isupper.3c .\" links@ctype.3c islower.3c .\" links@ctype.3c isdigit.3c .\" links@ctype.3c isxdigit.3c .\" links@ctype.3c isalnum.3c .\" links@ctype.3c isspace.3c .\" links@ctype.3c ispunct.3c .\" links@ctype.3c isprint.3c .\" links@ctype.3c isgraph.3c .\" links@ctype.3c iscntrl.3c .\" links@ctype.3c isascii.3c .\" .\" fileset_database@ctype.3c PROGRAMING-MAN .\" $Header: ctype.3c,v 72.6 94/11/28 08:25:33 ssa Exp $ .TA c .TH ctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isalpha(\|), isupper(\|), islower(\|), isdigit(\|), isxdigit(\|), isalnum(\|), isspace(\|), ispunct(\|), isprint(\|), isgraph(\|), iscntrl(\|), isascii(\|) \- classify characters .SH SYNOPSIS .C "#include " .PP .C "int isalnum(int c);" .br .C "int isalpha(int c);" .br .C "int iscntrl(int c);" .br .C "int isdigit(int c);" .br .C "int isgraph(int c);" .br .C "int islower(int c);" .br .C "int isprint(int c);" .br .C "int ispunct(int c);" .br .C "int isspace(int c);" .br .C "int isupper(int c);" .br .C "int isxdigit(int c);" .br .C "int isascii(int c);" .SH DESCRIPTION These functions classify character-coded integer values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). Each function is a predicate returning non-zero for true, zero for false. .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP .C isascii() is defined on all integer values; the other functions are defined for the range .C -1 .SM (EOF) through .CR 255 . .PP The functions return non-zero under the following circumstances; zero otherwise: .RS .TP 18 .CR isalpha( c ) .I c is a letter. .TP .CR isupper( c ) .I c is an uppercase letter. .TP .CR islower( c ) .I c is a lowercase letter. .TP .CR isdigit( c ) .I c is a decimal digit (in .SM ASCII\c : characters [0-9]). .TP .CR isxdigit( c ) .I c is a hexadecimal digit (in .SM ASCII\c : characters [0-9], [A-F] or [a-f]). .TP .CR isalnum( c ) .I c is an alphanumeric (letters or digits). .TP .CR isspace( c ) .I c is a character that creates ``white space'' in displayed text (in .SM ASCII\c : space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CR ispunct( c ) .I c is a punctuation character (in .SM ASCII\c : any printing character except the space character (040), digits, letters). .TP .CR isprint( c ) .I c is a printing character. .TP .CR isgraph( c ) .I c is a visible character (in .SM ASCII\c : printing characters, excluding the space character (040)). .TP .CR iscntrl( c ) .I c is a control character (in .SM ASCII\c : character codes less than 040 and the delete character (0177)). .TP .CR isascii( c ) .I c is any .SM ASCII character code between 0 and 0177, inclusive. .RE .PP If the argument to any of these functions is outside the domain of the function, the result is undefined. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS These functions are supplied both as library functions and as macros defined in the .RC < ctype.h > header. Normally, the macro versions are used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parenthesis or take its address. The following example uses the library functions for .CR isalpha() , .CR isdigit() , and .CR isspace() : .nf .IP .C "#include " .C "#undef isalpha" \h'.5i'... .C "main() .C "{ .C " int (*ctype_func)();" \h'.8i'... .C " if ( isalpha(c) )" \h'.8i'... .C " if ( (isdigit)(c) )" \h'.8i'... .C " ctype_func = isspace;" \h'.8i'... .C } .fi .SH AUTHOR .CR ctype() was developed by IBM, OSF, and HP. .SH SEE ALSO setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR isalnum() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isalpha() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR iscntrl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isgraph() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR islower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isprint() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ispunct() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isspace() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isxdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4isalpha()\f1 \- character is alpha@@@\f3ctype(3C)\f1 .\" index@\f4isupper()\f1 \- character is uppercase@@@\f3ctype(3C)\f1 .\" index@\f4islower()\f1 \- character is lowercase@@@\f3ctype(3C)\f1 .\" index@\f4isdigit()\f1 \- character is a digit@@@\f3ctype(3C)\f1 .\" index@\f4isxdigit()\f1 \- character is a hexadecimal digit@@@\f3ctype(3C)\f1 .\" index@\f4isalnum()\f1 \- character is alphanumeric@@@\f3ctype(3C)\f1 .\" index@\f4isspace()\f1 \- character is whitespace@@@\f3ctype(3C)\f1 .\" index@\f4ispunct()\f1 \- character is punctuation@@@\f3ctype(3C)\f1 .\" index@\f4isprint()\f1 \- character is a printing character@@@\f3ctype(3C)\f1 .\" index@\f4isgraph()\f1 \- character is a visible character@@@\f3ctype(3C)\f1 .\" index@\f4iscntrl()\f1 \- character is a control character@@@\f3ctype(3C)\f1 .\" index@\f4isascii()\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3ctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3ctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3ctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3ctype(3C)\f1 .\" .\" toc@\f3ctype(3C)\f1:\0\0\f4isalpha()\f1, \f4isupper()\f1, \f4islower()\f1, \f4isdigit()\f1, \f4isxdigit()\f1, \f4isalnum()\f1, \f4isspace()\f1,\n\f4ispunct()\f1, \f4isprint()\f1, \f4isgraph()\f1, \f4iscntrl()\f1, \f4isascii()\f1@@@classify characters .\" toc@\f4isalpha()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isupper()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4islower()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isxdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isalnum()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isspace()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4ispunct()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isprint()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isgraph()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4iscntrl()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isascii()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" .\" links@ctype.3c isalpha.3c .\" links@ctype.3c isupper.3c .\" links@ctype.3c islower.3c .\" links@ctype.3c isdigit.3c .\" links@ctype.3c isxdigit.3c .\" links@ctype.3c isalnum.3c .\" links@ctype.3c isspace.3c .\" links@ctype.3c ispunct.3c .\" links@ctype.3c isprint.3c .\" links@ctype.3c isgraph.3c .\" links@ctype.3c iscntrl.3c .\" links@ctype.3c isascii.3c .\" .\" fileset_database@ctype.3c PROGRAMING-MAN .\" $Header: isastream.3c,v 72.2 94/08/30 16:18:20 ssa Exp $ .TA i .TH isastream 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isastream(\|) \- determine if a file descriptor refers to a STREAMS device or STREAMS-based pipe .SH SYNOPSIS .CR "#include " .br .sp .CR "int isastream(int fd);" .SH DESCRIPTION .PP The .CR isastream() function tests whether an open file descriptor ( .I fd ) corresponds to a STREAMS device or STREAMS-based pipe. .SH RETURN VALUE Upon successful completion, the .CR isastream() function returns a value of 1 when the file descriptor of the open file specified by .I fd is a STREAMS device or STREAMS-based pipe, and 0 (zero) if it is not a stream, but is a valid open file descriptor. Otherwise, a value of -1 is returned, and .CR errno is set to indicate the error. .SH ERRORS If any of the following conditions occur, the .CR isastream() function sets .CR errno to the corresponding value: .TP 15 [EBADF] The specified file descriptor does not refer to a valid open file. .SH SEE ALSO fattach(3c), fdetach(3c), streamio(7). .SH STANDARDS COMPLIANCE .CR isastream() ": SVID3" .\" .\" index@\f4isastream\f1 \- determine if file descriptor refers to STREAMS device or STREAMS-based pipe@@@\f3isastream(3c)\f1 .\" index@\f1file descriptor: STREAMS-based pipe@@@\f3isastream(3c)\f1 .\" index@\f1file descriptor: STREAMS device@@@\f3isastream(3c)\f1 .\" index@\f1pipe: STREAMS-based pipe@@@\f3isastream(3c)\f1 .\" index@\f1device: STREAMS device@@@\f3isastream(3c)\f1 .\" index@\f1STREAMS-based pipe@@@\f3isastream(3c)\f1 .\" index@\f1STREAMS: determine if file descriptor refers to STREAMS device or STREAMS-based pipe@@@\f3isastream(3c)\f1 .\" .\" toc@\f3isastream(3c)\f1:\0\0\f4isastream()\f1@@@determine if file descriptor refers to STREAMS device or STREAMS-based pipe .\" .\" fileset_database@isastream.3c STREAMS-MAN .\" $Header: ttyname.3c,v 76.1 95/07/05 17:53:09 ssa Exp $ .TA t .TH ttyname 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ttyname(\|), ttyname_r(\|), isatty(\|) \- find name of a terminal .SH SYNOPSIS .C "#include " .P .C "char *ttyname(int fildes);" .PP .C "int ttyname_r(int fildes, char *buffer, int buflen);" .P .C "int isatty(int fildes);" .SH DESCRIPTION .CR ttyname() returns a pointer to a string containing the null-terminated path name of the terminal device associated with file descriptor .IR fildes . .PP .CR isatty() returns 1 if .I fildes is associated with a terminal device, 0 otherwise. .SS Reentrant Interfaces .CR ttyname_r() returns the result string in the supplied buffer. A buffer length of 64 is recommended. If an error is detected or the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .SH RETURN VALUE .CR ttyname() returns a .SM NULL pointer if .I fildes does not describe a terminal device in directory .CR /dev . .SH ERRORS .CR isatty() and .CR ttyname() fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] The .IR fildes argument is invalid. .TP .SM [ENOTTY] An inappropriate .SM I/O control operation has been attempted. .SH WARNINGS The return value for .CR ttyname() points to static data whose content is overwritten by each call. For streams ptys, .CR ttyname() and .CR isatty() do not consider master ptys to be tty devices. It should also be noted that .CR ttyname() returns a pointer to the master pty name for all master pty devices. This is a result of device files being linked together. .PP .CR ttyname() is unsafe for multi-thread applications. .CR ttyname_r() is MT-Safe and should be used instead. .PP Users of .CR ttyname_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH FILES .CR /dev/* .br .CR /dev/pty/* .SH STANDARDS CONFORMANCE .CR ttyname() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR isatty() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4ttyname()\fP, \f4isatty()\fP \- find name of a terminal@@@\f3ttyname(3C)\f1 .\" index@\f4isatty()\fP \- find name of a terminal@@@\f3ttyname(3C)\f1 .\" index@find name of a terminal@@@\f3ttyname(3C)\f1 .\" index@name: find name of a terminal@@@\f3ttyname(3C)\f1 .\" index@terminal, find name of@@@\f3ttyname(3C)\f1 .\" .\" toc@\f3ttyname(3C)\f1:\0\0\f4ttyname()\fP, \f4isatty()\fP@@@find name of a terminal .\" toc@\f4isatty()\fP:\0\0find name of a terminal@@@see \f3ttyname(3C)\f1 .\" .\" links@ttyname.3c isatty.3c .\" links@ttyname.3c ttyname_r.3c .\" $Header: ctype.3c,v 72.6 94/11/28 08:25:33 ssa Exp $ .TA c .TH ctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isalpha(\|), isupper(\|), islower(\|), isdigit(\|), isxdigit(\|), isalnum(\|), isspace(\|), ispunct(\|), isprint(\|), isgraph(\|), iscntrl(\|), isascii(\|) \- classify characters .SH SYNOPSIS .C "#include " .PP .C "int isalnum(int c);" .br .C "int isalpha(int c);" .br .C "int iscntrl(int c);" .br .C "int isdigit(int c);" .br .C "int isgraph(int c);" .br .C "int islower(int c);" .br .C "int isprint(int c);" .br .C "int ispunct(int c);" .br .C "int isspace(int c);" .br .C "int isupper(int c);" .br .C "int isxdigit(int c);" .br .C "int isascii(int c);" .SH DESCRIPTION These functions classify character-coded integer values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). Each function is a predicate returning non-zero for true, zero for false. .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP .C isascii() is defined on all integer values; the other functions are defined for the range .C -1 .SM (EOF) through .CR 255 . .PP The functions return non-zero under the following circumstances; zero otherwise: .RS .TP 18 .CR isalpha( c ) .I c is a letter. .TP .CR isupper( c ) .I c is an uppercase letter. .TP .CR islower( c ) .I c is a lowercase letter. .TP .CR isdigit( c ) .I c is a decimal digit (in .SM ASCII\c : characters [0-9]). .TP .CR isxdigit( c ) .I c is a hexadecimal digit (in .SM ASCII\c : characters [0-9], [A-F] or [a-f]). .TP .CR isalnum( c ) .I c is an alphanumeric (letters or digits). .TP .CR isspace( c ) .I c is a character that creates ``white space'' in displayed text (in .SM ASCII\c : space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CR ispunct( c ) .I c is a punctuation character (in .SM ASCII\c : any printing character except the space character (040), digits, letters). .TP .CR isprint( c ) .I c is a printing character. .TP .CR isgraph( c ) .I c is a visible character (in .SM ASCII\c : printing characters, excluding the space character (040)). .TP .CR iscntrl( c ) .I c is a control character (in .SM ASCII\c : character codes less than 040 and the delete character (0177)). .TP .CR isascii( c ) .I c is any .SM ASCII character code between 0 and 0177, inclusive. .RE .PP If the argument to any of these functions is outside the domain of the function, the result is undefined. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS These functions are supplied both as library functions and as macros defined in the .RC < ctype.h > header. Normally, the macro versions are used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parenthesis or take its address. The following example uses the library functions for .CR isalpha() , .CR isdigit() , and .CR isspace() : .nf .IP .C "#include " .C "#undef isalpha" \h'.5i'... .C "main() .C "{ .C " int (*ctype_func)();" \h'.8i'... .C " if ( isalpha(c) )" \h'.8i'... .C " if ( (isdigit)(c) )" \h'.8i'... .C " ctype_func = isspace;" \h'.8i'... .C } .fi .SH AUTHOR .CR ctype() was developed by IBM, OSF, and HP. .SH SEE ALSO setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR isalnum() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isalpha() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR iscntrl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isgraph() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR islower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isprint() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ispunct() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isspace() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isxdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4isalpha()\f1 \- character is alpha@@@\f3ctype(3C)\f1 .\" index@\f4isupper()\f1 \- character is uppercase@@@\f3ctype(3C)\f1 .\" index@\f4islower()\f1 \- character is lowercase@@@\f3ctype(3C)\f1 .\" index@\f4isdigit()\f1 \- character is a digit@@@\f3ctype(3C)\f1 .\" index@\f4isxdigit()\f1 \- character is a hexadecimal digit@@@\f3ctype(3C)\f1 .\" index@\f4isalnum()\f1 \- character is alphanumeric@@@\f3ctype(3C)\f1 .\" index@\f4isspace()\f1 \- character is whitespace@@@\f3ctype(3C)\f1 .\" index@\f4ispunct()\f1 \- character is punctuation@@@\f3ctype(3C)\f1 .\" index@\f4isprint()\f1 \- character is a printing character@@@\f3ctype(3C)\f1 .\" index@\f4isgraph()\f1 \- character is a visible character@@@\f3ctype(3C)\f1 .\" index@\f4iscntrl()\f1 \- character is a control character@@@\f3ctype(3C)\f1 .\" index@\f4isascii()\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3ctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3ctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3ctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3ctype(3C)\f1 .\" .\" toc@\f3ctype(3C)\f1:\0\0\f4isalpha()\f1, \f4isupper()\f1, \f4islower()\f1, \f4isdigit()\f1, \f4isxdigit()\f1, \f4isalnum()\f1, \f4isspace()\f1,\n\f4ispunct()\f1, \f4isprint()\f1, \f4isgraph()\f1, \f4iscntrl()\f1, \f4isascii()\f1@@@classify characters .\" toc@\f4isalpha()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isupper()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4islower()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isxdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isalnum()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isspace()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4ispunct()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isprint()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isgraph()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4iscntrl()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isascii()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" .\" links@ctype.3c isalpha.3c .\" links@ctype.3c isupper.3c .\" links@ctype.3c islower.3c .\" links@ctype.3c isdigit.3c .\" links@ctype.3c isxdigit.3c .\" links@ctype.3c isalnum.3c .\" links@ctype.3c isspace.3c .\" links@ctype.3c ispunct.3c .\" links@ctype.3c isprint.3c .\" links@ctype.3c isgraph.3c .\" links@ctype.3c iscntrl.3c .\" links@ctype.3c isascii.3c .\" .\" fileset_database@ctype.3c PROGRAMING-MAN .\" $Header: ctype.3c,v 72.6 94/11/28 08:25:33 ssa Exp $ .TA c .TH ctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isalpha(\|), isupper(\|), islower(\|), isdigit(\|), isxdigit(\|), isalnum(\|), isspace(\|), ispunct(\|), isprint(\|), isgraph(\|), iscntrl(\|), isascii(\|) \- classify characters .SH SYNOPSIS .C "#include " .PP .C "int isalnum(int c);" .br .C "int isalpha(int c);" .br .C "int iscntrl(int c);" .br .C "int isdigit(int c);" .br .C "int isgraph(int c);" .br .C "int islower(int c);" .br .C "int isprint(int c);" .br .C "int ispunct(int c);" .br .C "int isspace(int c);" .br .C "int isupper(int c);" .br .C "int isxdigit(int c);" .br .C "int isascii(int c);" .SH DESCRIPTION These functions classify character-coded integer values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). Each function is a predicate returning non-zero for true, zero for false. .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP .C isascii() is defined on all integer values; the other functions are defined for the range .C -1 .SM (EOF) through .CR 255 . .PP The functions return non-zero under the following circumstances; zero otherwise: .RS .TP 18 .CR isalpha( c ) .I c is a letter. .TP .CR isupper( c ) .I c is an uppercase letter. .TP .CR islower( c ) .I c is a lowercase letter. .TP .CR isdigit( c ) .I c is a decimal digit (in .SM ASCII\c : characters [0-9]). .TP .CR isxdigit( c ) .I c is a hexadecimal digit (in .SM ASCII\c : characters [0-9], [A-F] or [a-f]). .TP .CR isalnum( c ) .I c is an alphanumeric (letters or digits). .TP .CR isspace( c ) .I c is a character that creates ``white space'' in displayed text (in .SM ASCII\c : space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CR ispunct( c ) .I c is a punctuation character (in .SM ASCII\c : any printing character except the space character (040), digits, letters). .TP .CR isprint( c ) .I c is a printing character. .TP .CR isgraph( c ) .I c is a visible character (in .SM ASCII\c : printing characters, excluding the space character (040)). .TP .CR iscntrl( c ) .I c is a control character (in .SM ASCII\c : character codes less than 040 and the delete character (0177)). .TP .CR isascii( c ) .I c is any .SM ASCII character code between 0 and 0177, inclusive. .RE .PP If the argument to any of these functions is outside the domain of the function, the result is undefined. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS These functions are supplied both as library functions and as macros defined in the .RC < ctype.h > header. Normally, the macro versions are used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parenthesis or take its address. The following example uses the library functions for .CR isalpha() , .CR isdigit() , and .CR isspace() : .nf .IP .C "#include " .C "#undef isalpha" \h'.5i'... .C "main() .C "{ .C " int (*ctype_func)();" \h'.8i'... .C " if ( isalpha(c) )" \h'.8i'... .C " if ( (isdigit)(c) )" \h'.8i'... .C " ctype_func = isspace;" \h'.8i'... .C } .fi .SH AUTHOR .CR ctype() was developed by IBM, OSF, and HP. .SH SEE ALSO setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR isalnum() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isalpha() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR iscntrl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isgraph() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR islower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isprint() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ispunct() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isspace() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isxdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4isalpha()\f1 \- character is alpha@@@\f3ctype(3C)\f1 .\" index@\f4isupper()\f1 \- character is uppercase@@@\f3ctype(3C)\f1 .\" index@\f4islower()\f1 \- character is lowercase@@@\f3ctype(3C)\f1 .\" index@\f4isdigit()\f1 \- character is a digit@@@\f3ctype(3C)\f1 .\" index@\f4isxdigit()\f1 \- character is a hexadecimal digit@@@\f3ctype(3C)\f1 .\" index@\f4isalnum()\f1 \- character is alphanumeric@@@\f3ctype(3C)\f1 .\" index@\f4isspace()\f1 \- character is whitespace@@@\f3ctype(3C)\f1 .\" index@\f4ispunct()\f1 \- character is punctuation@@@\f3ctype(3C)\f1 .\" index@\f4isprint()\f1 \- character is a printing character@@@\f3ctype(3C)\f1 .\" index@\f4isgraph()\f1 \- character is a visible character@@@\f3ctype(3C)\f1 .\" index@\f4iscntrl()\f1 \- character is a control character@@@\f3ctype(3C)\f1 .\" index@\f4isascii()\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3ctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3ctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3ctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3ctype(3C)\f1 .\" .\" toc@\f3ctype(3C)\f1:\0\0\f4isalpha()\f1, \f4isupper()\f1, \f4islower()\f1, \f4isdigit()\f1, \f4isxdigit()\f1, \f4isalnum()\f1, \f4isspace()\f1,\n\f4ispunct()\f1, \f4isprint()\f1, \f4isgraph()\f1, \f4iscntrl()\f1, \f4isascii()\f1@@@classify characters .\" toc@\f4isalpha()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isupper()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4islower()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isxdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isalnum()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isspace()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4ispunct()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isprint()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isgraph()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4iscntrl()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isascii()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" .\" links@ctype.3c isalpha.3c .\" links@ctype.3c isupper.3c .\" links@ctype.3c islower.3c .\" links@ctype.3c isdigit.3c .\" links@ctype.3c isxdigit.3c .\" links@ctype.3c isalnum.3c .\" links@ctype.3c isspace.3c .\" links@ctype.3c ispunct.3c .\" links@ctype.3c isprint.3c .\" links@ctype.3c isgraph.3c .\" links@ctype.3c iscntrl.3c .\" links@ctype.3c isascii.3c .\" .\" fileset_database@ctype.3c PROGRAMING-MAN .\" $Header: isendwin.3x,v 76.2 95/08/01 11:31:57 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH isendwin 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isendwin \(em determine whether a screen has been refreshed .SH SYNOPSIS .C "#include " .P .C "bool isendwin(void);" .SH DESCRIPTION The .Fn isendwin function indicates whether the screen has been refreshed since the last call to .Fn endwin . .SH "RETURN VALUE" The .Fn isendwin function returns TRUE if .Fn endwin has been called without any subsequent refresh. Otherwise, it returns FALSE. .SH ERRORS No errors are defined. .SH "SEE ALSO" endwin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4isendwin()\f1 \- determine whether a screen has been refreshed@@@\f3isendwin(3X)\f1 .\" index@\f1determine whether a screen has been refreshed@@@\f3isendwin(3X)\f1 .\" index@\f1screen, determine if it has been refreshed@@@\f3isendwin(3X)\f1 .\" index@\f1refresh, determine whether a screen has been refreshed@@@\f3isendwin(3X)\f1 .\" .\" toc@\f3isendwin(3X)\f1:\0\0\f4isendwin()\f1@@@determine whether a screen has been refreshed .\" .\" fileset_database@isendwin.3x CURS-ENG-A-MAN .\" $Header: ctype.3c,v 72.6 94/11/28 08:25:33 ssa Exp $ .TA c .TH ctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isalpha(\|), isupper(\|), islower(\|), isdigit(\|), isxdigit(\|), isalnum(\|), isspace(\|), ispunct(\|), isprint(\|), isgraph(\|), iscntrl(\|), isascii(\|) \- classify characters .SH SYNOPSIS .C "#include " .PP .C "int isalnum(int c);" .br .C "int isalpha(int c);" .br .C "int iscntrl(int c);" .br .C "int isdigit(int c);" .br .C "int isgraph(int c);" .br .C "int islower(int c);" .br .C "int isprint(int c);" .br .C "int ispunct(int c);" .br .C "int isspace(int c);" .br .C "int isupper(int c);" .br .C "int isxdigit(int c);" .br .C "int isascii(int c);" .SH DESCRIPTION These functions classify character-coded integer values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). Each function is a predicate returning non-zero for true, zero for false. .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP .C isascii() is defined on all integer values; the other functions are defined for the range .C -1 .SM (EOF) through .CR 255 . .PP The functions return non-zero under the following circumstances; zero otherwise: .RS .TP 18 .CR isalpha( c ) .I c is a letter. .TP .CR isupper( c ) .I c is an uppercase letter. .TP .CR islower( c ) .I c is a lowercase letter. .TP .CR isdigit( c ) .I c is a decimal digit (in .SM ASCII\c : characters [0-9]). .TP .CR isxdigit( c ) .I c is a hexadecimal digit (in .SM ASCII\c : characters [0-9], [A-F] or [a-f]). .TP .CR isalnum( c ) .I c is an alphanumeric (letters or digits). .TP .CR isspace( c ) .I c is a character that creates ``white space'' in displayed text (in .SM ASCII\c : space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CR ispunct( c ) .I c is a punctuation character (in .SM ASCII\c : any printing character except the space character (040), digits, letters). .TP .CR isprint( c ) .I c is a printing character. .TP .CR isgraph( c ) .I c is a visible character (in .SM ASCII\c : printing characters, excluding the space character (040)). .TP .CR iscntrl( c ) .I c is a control character (in .SM ASCII\c : character codes less than 040 and the delete character (0177)). .TP .CR isascii( c ) .I c is any .SM ASCII character code between 0 and 0177, inclusive. .RE .PP If the argument to any of these functions is outside the domain of the function, the result is undefined. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS These functions are supplied both as library functions and as macros defined in the .RC < ctype.h > header. Normally, the macro versions are used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parenthesis or take its address. The following example uses the library functions for .CR isalpha() , .CR isdigit() , and .CR isspace() : .nf .IP .C "#include " .C "#undef isalpha" \h'.5i'... .C "main() .C "{ .C " int (*ctype_func)();" \h'.8i'... .C " if ( isalpha(c) )" \h'.8i'... .C " if ( (isdigit)(c) )" \h'.8i'... .C " ctype_func = isspace;" \h'.8i'... .C } .fi .SH AUTHOR .CR ctype() was developed by IBM, OSF, and HP. .SH SEE ALSO setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR isalnum() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isalpha() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR iscntrl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isgraph() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR islower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isprint() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ispunct() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isspace() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isxdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4isalpha()\f1 \- character is alpha@@@\f3ctype(3C)\f1 .\" index@\f4isupper()\f1 \- character is uppercase@@@\f3ctype(3C)\f1 .\" index@\f4islower()\f1 \- character is lowercase@@@\f3ctype(3C)\f1 .\" index@\f4isdigit()\f1 \- character is a digit@@@\f3ctype(3C)\f1 .\" index@\f4isxdigit()\f1 \- character is a hexadecimal digit@@@\f3ctype(3C)\f1 .\" index@\f4isalnum()\f1 \- character is alphanumeric@@@\f3ctype(3C)\f1 .\" index@\f4isspace()\f1 \- character is whitespace@@@\f3ctype(3C)\f1 .\" index@\f4ispunct()\f1 \- character is punctuation@@@\f3ctype(3C)\f1 .\" index@\f4isprint()\f1 \- character is a printing character@@@\f3ctype(3C)\f1 .\" index@\f4isgraph()\f1 \- character is a visible character@@@\f3ctype(3C)\f1 .\" index@\f4iscntrl()\f1 \- character is a control character@@@\f3ctype(3C)\f1 .\" index@\f4isascii()\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3ctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3ctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3ctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3ctype(3C)\f1 .\" .\" toc@\f3ctype(3C)\f1:\0\0\f4isalpha()\f1, \f4isupper()\f1, \f4islower()\f1, \f4isdigit()\f1, \f4isxdigit()\f1, \f4isalnum()\f1, \f4isspace()\f1,\n\f4ispunct()\f1, \f4isprint()\f1, \f4isgraph()\f1, \f4iscntrl()\f1, \f4isascii()\f1@@@classify characters .\" toc@\f4isalpha()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isupper()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4islower()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isxdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isalnum()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isspace()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4ispunct()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isprint()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isgraph()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4iscntrl()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isascii()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" .\" links@ctype.3c isalpha.3c .\" links@ctype.3c isupper.3c .\" links@ctype.3c islower.3c .\" links@ctype.3c isdigit.3c .\" links@ctype.3c isxdigit.3c .\" links@ctype.3c isalnum.3c .\" links@ctype.3c isspace.3c .\" links@ctype.3c ispunct.3c .\" links@ctype.3c isprint.3c .\" links@ctype.3c isgraph.3c .\" links@ctype.3c iscntrl.3c .\" links@ctype.3c isascii.3c .\" .\" fileset_database@ctype.3c PROGRAMING-MAN .\" $Header: isinf.3m,v 78.1 96/02/13 12:05:54 ssa Exp $ .TA i .TH isinf 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isinf(\|), isinff(\|) \- test for INFINITY functions .SH SYNOPSIS .C "#include " .PP .C "int isinf(double x);" .PP .C "int isinff(float x);" .SH DESCRIPTION .CR isinf() returns a positive integer if .I x is +INFINITY, or a negative integer if .I x is \(miINFINITY. Otherwise it returns zero. .PP .CR isinff() is a .CR float version of .CR isinf() ; it takes a .CR float argument. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR isinf() and .CR isinff() are not specified by any standard, but .CR isinff() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH SEE ALSO finite(3M), fpclassify(3M), isnan(3M). .\" .\" index@\f4isinf()\f1, \f4isinff\f1 \- test for INFINITY@@@\f3isinf(3M)\f1 .\" index@\f4isinff()\fP, \f4isinf\fP \- test for INFINITY@@@\f3isinf(3M)\f1 .\" index@\f1math: test for INFINITY@@@\f3isinf(3M)\f1 .\" index@\f1INFINITY, test for@@@\f3isinf(3M)\f1 .\" index@\f1test for INFINITY@@@\f3isinf(3M)\f1 .\" index@\f1floating-point classification functions@@@\f3isinf(3M)\f1 .\" .\" toc@\f3isinf(3M)\f1:\0\0\f4isinf()\f1, \f4isinff()\f1@@@test for INFINITY .\" toc@\f4isinff()\f1:\0\0 test for INFINITY (float version)@@@see \f3isinf(3M)\f1 .\" .\" links@isinf.3m isinff.3m .\" .\" fileset_database@isinf.3m PROGRAMING-MAN .\" $Header: isinf.3m,v 78.1 96/02/13 12:05:54 ssa Exp $ .TA i .TH isinf 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isinf(\|), isinff(\|) \- test for INFINITY functions .SH SYNOPSIS .C "#include " .PP .C "int isinf(double x);" .PP .C "int isinff(float x);" .SH DESCRIPTION .CR isinf() returns a positive integer if .I x is +INFINITY, or a negative integer if .I x is \(miINFINITY. Otherwise it returns zero. .PP .CR isinff() is a .CR float version of .CR isinf() ; it takes a .CR float argument. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR isinf() and .CR isinff() are not specified by any standard, but .CR isinff() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH SEE ALSO finite(3M), fpclassify(3M), isnan(3M). .\" .\" index@\f4isinf()\f1, \f4isinff\f1 \- test for INFINITY@@@\f3isinf(3M)\f1 .\" index@\f4isinff()\fP, \f4isinf\fP \- test for INFINITY@@@\f3isinf(3M)\f1 .\" index@\f1math: test for INFINITY@@@\f3isinf(3M)\f1 .\" index@\f1INFINITY, test for@@@\f3isinf(3M)\f1 .\" index@\f1test for INFINITY@@@\f3isinf(3M)\f1 .\" index@\f1floating-point classification functions@@@\f3isinf(3M)\f1 .\" .\" toc@\f3isinf(3M)\f1:\0\0\f4isinf()\f1, \f4isinff()\f1@@@test for INFINITY .\" toc@\f4isinff()\f1:\0\0 test for INFINITY (float version)@@@see \f3isinf(3M)\f1 .\" .\" links@isinf.3m isinff.3m .\" .\" fileset_database@isinf.3m PROGRAMING-MAN .\" $Header: ctype.3c,v 72.6 94/11/28 08:25:33 ssa Exp $ .TA c .TH ctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isalpha(\|), isupper(\|), islower(\|), isdigit(\|), isxdigit(\|), isalnum(\|), isspace(\|), ispunct(\|), isprint(\|), isgraph(\|), iscntrl(\|), isascii(\|) \- classify characters .SH SYNOPSIS .C "#include " .PP .C "int isalnum(int c);" .br .C "int isalpha(int c);" .br .C "int iscntrl(int c);" .br .C "int isdigit(int c);" .br .C "int isgraph(int c);" .br .C "int islower(int c);" .br .C "int isprint(int c);" .br .C "int ispunct(int c);" .br .C "int isspace(int c);" .br .C "int isupper(int c);" .br .C "int isxdigit(int c);" .br .C "int isascii(int c);" .SH DESCRIPTION These functions classify character-coded integer values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). Each function is a predicate returning non-zero for true, zero for false. .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP .C isascii() is defined on all integer values; the other functions are defined for the range .C -1 .SM (EOF) through .CR 255 . .PP The functions return non-zero under the following circumstances; zero otherwise: .RS .TP 18 .CR isalpha( c ) .I c is a letter. .TP .CR isupper( c ) .I c is an uppercase letter. .TP .CR islower( c ) .I c is a lowercase letter. .TP .CR isdigit( c ) .I c is a decimal digit (in .SM ASCII\c : characters [0-9]). .TP .CR isxdigit( c ) .I c is a hexadecimal digit (in .SM ASCII\c : characters [0-9], [A-F] or [a-f]). .TP .CR isalnum( c ) .I c is an alphanumeric (letters or digits). .TP .CR isspace( c ) .I c is a character that creates ``white space'' in displayed text (in .SM ASCII\c : space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CR ispunct( c ) .I c is a punctuation character (in .SM ASCII\c : any printing character except the space character (040), digits, letters). .TP .CR isprint( c ) .I c is a printing character. .TP .CR isgraph( c ) .I c is a visible character (in .SM ASCII\c : printing characters, excluding the space character (040)). .TP .CR iscntrl( c ) .I c is a control character (in .SM ASCII\c : character codes less than 040 and the delete character (0177)). .TP .CR isascii( c ) .I c is any .SM ASCII character code between 0 and 0177, inclusive. .RE .PP If the argument to any of these functions is outside the domain of the function, the result is undefined. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS These functions are supplied both as library functions and as macros defined in the .RC < ctype.h > header. Normally, the macro versions are used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parenthesis or take its address. The following example uses the library functions for .CR isalpha() , .CR isdigit() , and .CR isspace() : .nf .IP .C "#include " .C "#undef isalpha" \h'.5i'... .C "main() .C "{ .C " int (*ctype_func)();" \h'.8i'... .C " if ( isalpha(c) )" \h'.8i'... .C " if ( (isdigit)(c) )" \h'.8i'... .C " ctype_func = isspace;" \h'.8i'... .C } .fi .SH AUTHOR .CR ctype() was developed by IBM, OSF, and HP. .SH SEE ALSO setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR isalnum() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isalpha() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR iscntrl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isgraph() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR islower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isprint() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ispunct() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isspace() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isxdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4isalpha()\f1 \- character is alpha@@@\f3ctype(3C)\f1 .\" index@\f4isupper()\f1 \- character is uppercase@@@\f3ctype(3C)\f1 .\" index@\f4islower()\f1 \- character is lowercase@@@\f3ctype(3C)\f1 .\" index@\f4isdigit()\f1 \- character is a digit@@@\f3ctype(3C)\f1 .\" index@\f4isxdigit()\f1 \- character is a hexadecimal digit@@@\f3ctype(3C)\f1 .\" index@\f4isalnum()\f1 \- character is alphanumeric@@@\f3ctype(3C)\f1 .\" index@\f4isspace()\f1 \- character is whitespace@@@\f3ctype(3C)\f1 .\" index@\f4ispunct()\f1 \- character is punctuation@@@\f3ctype(3C)\f1 .\" index@\f4isprint()\f1 \- character is a printing character@@@\f3ctype(3C)\f1 .\" index@\f4isgraph()\f1 \- character is a visible character@@@\f3ctype(3C)\f1 .\" index@\f4iscntrl()\f1 \- character is a control character@@@\f3ctype(3C)\f1 .\" index@\f4isascii()\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3ctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3ctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3ctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3ctype(3C)\f1 .\" .\" toc@\f3ctype(3C)\f1:\0\0\f4isalpha()\f1, \f4isupper()\f1, \f4islower()\f1, \f4isdigit()\f1, \f4isxdigit()\f1, \f4isalnum()\f1, \f4isspace()\f1,\n\f4ispunct()\f1, \f4isprint()\f1, \f4isgraph()\f1, \f4iscntrl()\f1, \f4isascii()\f1@@@classify characters .\" toc@\f4isalpha()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isupper()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4islower()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isxdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isalnum()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isspace()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4ispunct()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isprint()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isgraph()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4iscntrl()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isascii()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" .\" links@ctype.3c isalpha.3c .\" links@ctype.3c isupper.3c .\" links@ctype.3c islower.3c .\" links@ctype.3c isdigit.3c .\" links@ctype.3c isxdigit.3c .\" links@ctype.3c isalnum.3c .\" links@ctype.3c isspace.3c .\" links@ctype.3c ispunct.3c .\" links@ctype.3c isprint.3c .\" links@ctype.3c isgraph.3c .\" links@ctype.3c iscntrl.3c .\" links@ctype.3c isascii.3c .\" .\" fileset_database@ctype.3c PROGRAMING-MAN .\" $Header: isnan.3m,v 78.1 96/02/13 12:22:50 ssa Exp $ .TA i .TH isnan 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isnan(\|), isnanf(\|) \- test for NaN functions .SH SYNOPSIS .C "#include " .PP .C "int isnan(double x);" .PP .C "int isnanf(float x);" .SH DESCRIPTION .CR isnan() returns a nonzero integer if .I x is NaN (not-a-number). Otherwise it returns zero. .PP .CR isnanf() is a .CR float version of .CR isnan() ; it takes a .CR float argument. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR isnanf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH SEE ALSO finite(3M), fpclassify(3M), isinf(3M). .SH STANDARDS CONFORMANCE .CR isnan() ": SVID3, XPG4.2" .\" .\" index@\f4isnan()\f1, \f4isnanf()\f1 \- test for NaN@@@\f3isnan(3M)\f1 .\" index@\f4isnanf()\f1, \f4isnan()\f1 \- test for NaN@@@\f3isnan(3M)\f1 .\" index@\f1math: test for NaN@@@\f3isnan(3M)\f1 .\" index@\f1test for NaN@@@\f3isnan(3M)\f1 .\" index@\f1NaN, test for@@@\f3isnan(3M)\f1 .\" index@\f1floating-point classification functions@@@\f3isnan(3M)\f1 .\" .\" toc@\f3isnan(3M)\f1:\0\0\f4isnan()\f1, \f4isnanf()\f1@@@test for NaN .\" toc \f4isnanf()\f1:\0\0 test for NaN (float version)@@@see \f3isnan(3M)\f1 .\" .\" links@isnan.3m isnanf.3m .\" .\" fileset_database@isnan.3m PROGRAMING-MAN .\" $Header: isnan.3m,v 78.1 96/02/13 12:22:50 ssa Exp $ .TA i .TH isnan 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isnan(\|), isnanf(\|) \- test for NaN functions .SH SYNOPSIS .C "#include " .PP .C "int isnan(double x);" .PP .C "int isnanf(float x);" .SH DESCRIPTION .CR isnan() returns a nonzero integer if .I x is NaN (not-a-number). Otherwise it returns zero. .PP .CR isnanf() is a .CR float version of .CR isnan() ; it takes a .CR float argument. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR isnanf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH ERRORS No errors are defined. .SH SEE ALSO finite(3M), fpclassify(3M), isinf(3M). .SH STANDARDS CONFORMANCE .CR isnan() ": SVID3, XPG4.2" .\" .\" index@\f4isnan()\f1, \f4isnanf()\f1 \- test for NaN@@@\f3isnan(3M)\f1 .\" index@\f4isnanf()\f1, \f4isnan()\f1 \- test for NaN@@@\f3isnan(3M)\f1 .\" index@\f1math: test for NaN@@@\f3isnan(3M)\f1 .\" index@\f1test for NaN@@@\f3isnan(3M)\f1 .\" index@\f1NaN, test for@@@\f3isnan(3M)\f1 .\" index@\f1floating-point classification functions@@@\f3isnan(3M)\f1 .\" .\" toc@\f3isnan(3M)\f1:\0\0\f4isnan()\f1, \f4isnanf()\f1@@@test for NaN .\" toc \f4isnanf()\f1:\0\0 test for NaN (float version)@@@see \f3isnan(3M)\f1 .\" .\" links@isnan.3m isnanf.3m .\" .\" fileset_database@isnan.3m PROGRAMING-MAN .\" $Header: ctype.3c,v 72.6 94/11/28 08:25:33 ssa Exp $ .TA c .TH ctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isalpha(\|), isupper(\|), islower(\|), isdigit(\|), isxdigit(\|), isalnum(\|), isspace(\|), ispunct(\|), isprint(\|), isgraph(\|), iscntrl(\|), isascii(\|) \- classify characters .SH SYNOPSIS .C "#include " .PP .C "int isalnum(int c);" .br .C "int isalpha(int c);" .br .C "int iscntrl(int c);" .br .C "int isdigit(int c);" .br .C "int isgraph(int c);" .br .C "int islower(int c);" .br .C "int isprint(int c);" .br .C "int ispunct(int c);" .br .C "int isspace(int c);" .br .C "int isupper(int c);" .br .C "int isxdigit(int c);" .br .C "int isascii(int c);" .SH DESCRIPTION These functions classify character-coded integer values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). Each function is a predicate returning non-zero for true, zero for false. .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP .C isascii() is defined on all integer values; the other functions are defined for the range .C -1 .SM (EOF) through .CR 255 . .PP The functions return non-zero under the following circumstances; zero otherwise: .RS .TP 18 .CR isalpha( c ) .I c is a letter. .TP .CR isupper( c ) .I c is an uppercase letter. .TP .CR islower( c ) .I c is a lowercase letter. .TP .CR isdigit( c ) .I c is a decimal digit (in .SM ASCII\c : characters [0-9]). .TP .CR isxdigit( c ) .I c is a hexadecimal digit (in .SM ASCII\c : characters [0-9], [A-F] or [a-f]). .TP .CR isalnum( c ) .I c is an alphanumeric (letters or digits). .TP .CR isspace( c ) .I c is a character that creates ``white space'' in displayed text (in .SM ASCII\c : space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CR ispunct( c ) .I c is a punctuation character (in .SM ASCII\c : any printing character except the space character (040), digits, letters). .TP .CR isprint( c ) .I c is a printing character. .TP .CR isgraph( c ) .I c is a visible character (in .SM ASCII\c : printing characters, excluding the space character (040)). .TP .CR iscntrl( c ) .I c is a control character (in .SM ASCII\c : character codes less than 040 and the delete character (0177)). .TP .CR isascii( c ) .I c is any .SM ASCII character code between 0 and 0177, inclusive. .RE .PP If the argument to any of these functions is outside the domain of the function, the result is undefined. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS These functions are supplied both as library functions and as macros defined in the .RC < ctype.h > header. Normally, the macro versions are used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parenthesis or take its address. The following example uses the library functions for .CR isalpha() , .CR isdigit() , and .CR isspace() : .nf .IP .C "#include " .C "#undef isalpha" \h'.5i'... .C "main() .C "{ .C " int (*ctype_func)();" \h'.8i'... .C " if ( isalpha(c) )" \h'.8i'... .C " if ( (isdigit)(c) )" \h'.8i'... .C " ctype_func = isspace;" \h'.8i'... .C } .fi .SH AUTHOR .CR ctype() was developed by IBM, OSF, and HP. .SH SEE ALSO setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR isalnum() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isalpha() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR iscntrl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isgraph() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR islower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isprint() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ispunct() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isspace() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isxdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4isalpha()\f1 \- character is alpha@@@\f3ctype(3C)\f1 .\" index@\f4isupper()\f1 \- character is uppercase@@@\f3ctype(3C)\f1 .\" index@\f4islower()\f1 \- character is lowercase@@@\f3ctype(3C)\f1 .\" index@\f4isdigit()\f1 \- character is a digit@@@\f3ctype(3C)\f1 .\" index@\f4isxdigit()\f1 \- character is a hexadecimal digit@@@\f3ctype(3C)\f1 .\" index@\f4isalnum()\f1 \- character is alphanumeric@@@\f3ctype(3C)\f1 .\" index@\f4isspace()\f1 \- character is whitespace@@@\f3ctype(3C)\f1 .\" index@\f4ispunct()\f1 \- character is punctuation@@@\f3ctype(3C)\f1 .\" index@\f4isprint()\f1 \- character is a printing character@@@\f3ctype(3C)\f1 .\" index@\f4isgraph()\f1 \- character is a visible character@@@\f3ctype(3C)\f1 .\" index@\f4iscntrl()\f1 \- character is a control character@@@\f3ctype(3C)\f1 .\" index@\f4isascii()\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3ctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3ctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3ctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3ctype(3C)\f1 .\" .\" toc@\f3ctype(3C)\f1:\0\0\f4isalpha()\f1, \f4isupper()\f1, \f4islower()\f1, \f4isdigit()\f1, \f4isxdigit()\f1, \f4isalnum()\f1, \f4isspace()\f1,\n\f4ispunct()\f1, \f4isprint()\f1, \f4isgraph()\f1, \f4iscntrl()\f1, \f4isascii()\f1@@@classify characters .\" toc@\f4isalpha()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isupper()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4islower()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isxdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isalnum()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isspace()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4ispunct()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isprint()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isgraph()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4iscntrl()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isascii()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" .\" links@ctype.3c isalpha.3c .\" links@ctype.3c isupper.3c .\" links@ctype.3c islower.3c .\" links@ctype.3c isdigit.3c .\" links@ctype.3c isxdigit.3c .\" links@ctype.3c isalnum.3c .\" links@ctype.3c isspace.3c .\" links@ctype.3c ispunct.3c .\" links@ctype.3c isprint.3c .\" links@ctype.3c isgraph.3c .\" links@ctype.3c iscntrl.3c .\" links@ctype.3c isascii.3c .\" .\" fileset_database@ctype.3c PROGRAMING-MAN .\" $Header: ctype.3c,v 72.6 94/11/28 08:25:33 ssa Exp $ .TA c .TH ctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isalpha(\|), isupper(\|), islower(\|), isdigit(\|), isxdigit(\|), isalnum(\|), isspace(\|), ispunct(\|), isprint(\|), isgraph(\|), iscntrl(\|), isascii(\|) \- classify characters .SH SYNOPSIS .C "#include " .PP .C "int isalnum(int c);" .br .C "int isalpha(int c);" .br .C "int iscntrl(int c);" .br .C "int isdigit(int c);" .br .C "int isgraph(int c);" .br .C "int islower(int c);" .br .C "int isprint(int c);" .br .C "int ispunct(int c);" .br .C "int isspace(int c);" .br .C "int isupper(int c);" .br .C "int isxdigit(int c);" .br .C "int isascii(int c);" .SH DESCRIPTION These functions classify character-coded integer values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). Each function is a predicate returning non-zero for true, zero for false. .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP .C isascii() is defined on all integer values; the other functions are defined for the range .C -1 .SM (EOF) through .CR 255 . .PP The functions return non-zero under the following circumstances; zero otherwise: .RS .TP 18 .CR isalpha( c ) .I c is a letter. .TP .CR isupper( c ) .I c is an uppercase letter. .TP .CR islower( c ) .I c is a lowercase letter. .TP .CR isdigit( c ) .I c is a decimal digit (in .SM ASCII\c : characters [0-9]). .TP .CR isxdigit( c ) .I c is a hexadecimal digit (in .SM ASCII\c : characters [0-9], [A-F] or [a-f]). .TP .CR isalnum( c ) .I c is an alphanumeric (letters or digits). .TP .CR isspace( c ) .I c is a character that creates ``white space'' in displayed text (in .SM ASCII\c : space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CR ispunct( c ) .I c is a punctuation character (in .SM ASCII\c : any printing character except the space character (040), digits, letters). .TP .CR isprint( c ) .I c is a printing character. .TP .CR isgraph( c ) .I c is a visible character (in .SM ASCII\c : printing characters, excluding the space character (040)). .TP .CR iscntrl( c ) .I c is a control character (in .SM ASCII\c : character codes less than 040 and the delete character (0177)). .TP .CR isascii( c ) .I c is any .SM ASCII character code between 0 and 0177, inclusive. .RE .PP If the argument to any of these functions is outside the domain of the function, the result is undefined. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS These functions are supplied both as library functions and as macros defined in the .RC < ctype.h > header. Normally, the macro versions are used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parenthesis or take its address. The following example uses the library functions for .CR isalpha() , .CR isdigit() , and .CR isspace() : .nf .IP .C "#include " .C "#undef isalpha" \h'.5i'... .C "main() .C "{ .C " int (*ctype_func)();" \h'.8i'... .C " if ( isalpha(c) )" \h'.8i'... .C " if ( (isdigit)(c) )" \h'.8i'... .C " ctype_func = isspace;" \h'.8i'... .C } .fi .SH AUTHOR .CR ctype() was developed by IBM, OSF, and HP. .SH SEE ALSO setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR isalnum() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isalpha() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR iscntrl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isgraph() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR islower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isprint() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ispunct() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isspace() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isxdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4isalpha()\f1 \- character is alpha@@@\f3ctype(3C)\f1 .\" index@\f4isupper()\f1 \- character is uppercase@@@\f3ctype(3C)\f1 .\" index@\f4islower()\f1 \- character is lowercase@@@\f3ctype(3C)\f1 .\" index@\f4isdigit()\f1 \- character is a digit@@@\f3ctype(3C)\f1 .\" index@\f4isxdigit()\f1 \- character is a hexadecimal digit@@@\f3ctype(3C)\f1 .\" index@\f4isalnum()\f1 \- character is alphanumeric@@@\f3ctype(3C)\f1 .\" index@\f4isspace()\f1 \- character is whitespace@@@\f3ctype(3C)\f1 .\" index@\f4ispunct()\f1 \- character is punctuation@@@\f3ctype(3C)\f1 .\" index@\f4isprint()\f1 \- character is a printing character@@@\f3ctype(3C)\f1 .\" index@\f4isgraph()\f1 \- character is a visible character@@@\f3ctype(3C)\f1 .\" index@\f4iscntrl()\f1 \- character is a control character@@@\f3ctype(3C)\f1 .\" index@\f4isascii()\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3ctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3ctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3ctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3ctype(3C)\f1 .\" .\" toc@\f3ctype(3C)\f1:\0\0\f4isalpha()\f1, \f4isupper()\f1, \f4islower()\f1, \f4isdigit()\f1, \f4isxdigit()\f1, \f4isalnum()\f1, \f4isspace()\f1,\n\f4ispunct()\f1, \f4isprint()\f1, \f4isgraph()\f1, \f4iscntrl()\f1, \f4isascii()\f1@@@classify characters .\" toc@\f4isalpha()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isupper()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4islower()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isxdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isalnum()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isspace()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4ispunct()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isprint()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isgraph()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4iscntrl()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isascii()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" .\" links@ctype.3c isalpha.3c .\" links@ctype.3c isupper.3c .\" links@ctype.3c islower.3c .\" links@ctype.3c isdigit.3c .\" links@ctype.3c isxdigit.3c .\" links@ctype.3c isalnum.3c .\" links@ctype.3c isspace.3c .\" links@ctype.3c ispunct.3c .\" links@ctype.3c isprint.3c .\" links@ctype.3c isgraph.3c .\" links@ctype.3c iscntrl.3c .\" links@ctype.3c isascii.3c .\" .\" fileset_database@ctype.3c PROGRAMING-MAN .\" $Header: ctype.3c,v 72.6 94/11/28 08:25:33 ssa Exp $ .TA c .TH ctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isalpha(\|), isupper(\|), islower(\|), isdigit(\|), isxdigit(\|), isalnum(\|), isspace(\|), ispunct(\|), isprint(\|), isgraph(\|), iscntrl(\|), isascii(\|) \- classify characters .SH SYNOPSIS .C "#include " .PP .C "int isalnum(int c);" .br .C "int isalpha(int c);" .br .C "int iscntrl(int c);" .br .C "int isdigit(int c);" .br .C "int isgraph(int c);" .br .C "int islower(int c);" .br .C "int isprint(int c);" .br .C "int ispunct(int c);" .br .C "int isspace(int c);" .br .C "int isupper(int c);" .br .C "int isxdigit(int c);" .br .C "int isascii(int c);" .SH DESCRIPTION These functions classify character-coded integer values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). Each function is a predicate returning non-zero for true, zero for false. .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP .C isascii() is defined on all integer values; the other functions are defined for the range .C -1 .SM (EOF) through .CR 255 . .PP The functions return non-zero under the following circumstances; zero otherwise: .RS .TP 18 .CR isalpha( c ) .I c is a letter. .TP .CR isupper( c ) .I c is an uppercase letter. .TP .CR islower( c ) .I c is a lowercase letter. .TP .CR isdigit( c ) .I c is a decimal digit (in .SM ASCII\c : characters [0-9]). .TP .CR isxdigit( c ) .I c is a hexadecimal digit (in .SM ASCII\c : characters [0-9], [A-F] or [a-f]). .TP .CR isalnum( c ) .I c is an alphanumeric (letters or digits). .TP .CR isspace( c ) .I c is a character that creates ``white space'' in displayed text (in .SM ASCII\c : space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CR ispunct( c ) .I c is a punctuation character (in .SM ASCII\c : any printing character except the space character (040), digits, letters). .TP .CR isprint( c ) .I c is a printing character. .TP .CR isgraph( c ) .I c is a visible character (in .SM ASCII\c : printing characters, excluding the space character (040)). .TP .CR iscntrl( c ) .I c is a control character (in .SM ASCII\c : character codes less than 040 and the delete character (0177)). .TP .CR isascii( c ) .I c is any .SM ASCII character code between 0 and 0177, inclusive. .RE .PP If the argument to any of these functions is outside the domain of the function, the result is undefined. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS These functions are supplied both as library functions and as macros defined in the .RC < ctype.h > header. Normally, the macro versions are used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parenthesis or take its address. The following example uses the library functions for .CR isalpha() , .CR isdigit() , and .CR isspace() : .nf .IP .C "#include " .C "#undef isalpha" \h'.5i'... .C "main() .C "{ .C " int (*ctype_func)();" \h'.8i'... .C " if ( isalpha(c) )" \h'.8i'... .C " if ( (isdigit)(c) )" \h'.8i'... .C " ctype_func = isspace;" \h'.8i'... .C } .fi .SH AUTHOR .CR ctype() was developed by IBM, OSF, and HP. .SH SEE ALSO setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR isalnum() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isalpha() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR iscntrl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isgraph() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR islower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isprint() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ispunct() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isspace() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isxdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4isalpha()\f1 \- character is alpha@@@\f3ctype(3C)\f1 .\" index@\f4isupper()\f1 \- character is uppercase@@@\f3ctype(3C)\f1 .\" index@\f4islower()\f1 \- character is lowercase@@@\f3ctype(3C)\f1 .\" index@\f4isdigit()\f1 \- character is a digit@@@\f3ctype(3C)\f1 .\" index@\f4isxdigit()\f1 \- character is a hexadecimal digit@@@\f3ctype(3C)\f1 .\" index@\f4isalnum()\f1 \- character is alphanumeric@@@\f3ctype(3C)\f1 .\" index@\f4isspace()\f1 \- character is whitespace@@@\f3ctype(3C)\f1 .\" index@\f4ispunct()\f1 \- character is punctuation@@@\f3ctype(3C)\f1 .\" index@\f4isprint()\f1 \- character is a printing character@@@\f3ctype(3C)\f1 .\" index@\f4isgraph()\f1 \- character is a visible character@@@\f3ctype(3C)\f1 .\" index@\f4iscntrl()\f1 \- character is a control character@@@\f3ctype(3C)\f1 .\" index@\f4isascii()\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3ctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3ctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3ctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3ctype(3C)\f1 .\" .\" toc@\f3ctype(3C)\f1:\0\0\f4isalpha()\f1, \f4isupper()\f1, \f4islower()\f1, \f4isdigit()\f1, \f4isxdigit()\f1, \f4isalnum()\f1, \f4isspace()\f1,\n\f4ispunct()\f1, \f4isprint()\f1, \f4isgraph()\f1, \f4iscntrl()\f1, \f4isascii()\f1@@@classify characters .\" toc@\f4isalpha()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isupper()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4islower()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isxdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isalnum()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isspace()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4ispunct()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isprint()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isgraph()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4iscntrl()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isascii()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" .\" links@ctype.3c isalpha.3c .\" links@ctype.3c isupper.3c .\" links@ctype.3c islower.3c .\" links@ctype.3c isdigit.3c .\" links@ctype.3c isxdigit.3c .\" links@ctype.3c isalnum.3c .\" links@ctype.3c isspace.3c .\" links@ctype.3c ispunct.3c .\" links@ctype.3c isprint.3c .\" links@ctype.3c isgraph.3c .\" links@ctype.3c iscntrl.3c .\" links@ctype.3c isascii.3c .\" .\" fileset_database@ctype.3c PROGRAMING-MAN .\" $Header: ctype.3c,v 72.6 94/11/28 08:25:33 ssa Exp $ .TA c .TH ctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isalpha(\|), isupper(\|), islower(\|), isdigit(\|), isxdigit(\|), isalnum(\|), isspace(\|), ispunct(\|), isprint(\|), isgraph(\|), iscntrl(\|), isascii(\|) \- classify characters .SH SYNOPSIS .C "#include " .PP .C "int isalnum(int c);" .br .C "int isalpha(int c);" .br .C "int iscntrl(int c);" .br .C "int isdigit(int c);" .br .C "int isgraph(int c);" .br .C "int islower(int c);" .br .C "int isprint(int c);" .br .C "int ispunct(int c);" .br .C "int isspace(int c);" .br .C "int isupper(int c);" .br .C "int isxdigit(int c);" .br .C "int isascii(int c);" .SH DESCRIPTION These functions classify character-coded integer values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). Each function is a predicate returning non-zero for true, zero for false. .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP .C isascii() is defined on all integer values; the other functions are defined for the range .C -1 .SM (EOF) through .CR 255 . .PP The functions return non-zero under the following circumstances; zero otherwise: .RS .TP 18 .CR isalpha( c ) .I c is a letter. .TP .CR isupper( c ) .I c is an uppercase letter. .TP .CR islower( c ) .I c is a lowercase letter. .TP .CR isdigit( c ) .I c is a decimal digit (in .SM ASCII\c : characters [0-9]). .TP .CR isxdigit( c ) .I c is a hexadecimal digit (in .SM ASCII\c : characters [0-9], [A-F] or [a-f]). .TP .CR isalnum( c ) .I c is an alphanumeric (letters or digits). .TP .CR isspace( c ) .I c is a character that creates ``white space'' in displayed text (in .SM ASCII\c : space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CR ispunct( c ) .I c is a punctuation character (in .SM ASCII\c : any printing character except the space character (040), digits, letters). .TP .CR isprint( c ) .I c is a printing character. .TP .CR isgraph( c ) .I c is a visible character (in .SM ASCII\c : printing characters, excluding the space character (040)). .TP .CR iscntrl( c ) .I c is a control character (in .SM ASCII\c : character codes less than 040 and the delete character (0177)). .TP .CR isascii( c ) .I c is any .SM ASCII character code between 0 and 0177, inclusive. .RE .PP If the argument to any of these functions is outside the domain of the function, the result is undefined. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS These functions are supplied both as library functions and as macros defined in the .RC < ctype.h > header. Normally, the macro versions are used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parenthesis or take its address. The following example uses the library functions for .CR isalpha() , .CR isdigit() , and .CR isspace() : .nf .IP .C "#include " .C "#undef isalpha" \h'.5i'... .C "main() .C "{ .C " int (*ctype_func)();" \h'.8i'... .C " if ( isalpha(c) )" \h'.8i'... .C " if ( (isdigit)(c) )" \h'.8i'... .C " ctype_func = isspace;" \h'.8i'... .C } .fi .SH AUTHOR .CR ctype() was developed by IBM, OSF, and HP. .SH SEE ALSO setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR isalnum() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isalpha() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR iscntrl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isgraph() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR islower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isprint() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ispunct() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isspace() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isxdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4isalpha()\f1 \- character is alpha@@@\f3ctype(3C)\f1 .\" index@\f4isupper()\f1 \- character is uppercase@@@\f3ctype(3C)\f1 .\" index@\f4islower()\f1 \- character is lowercase@@@\f3ctype(3C)\f1 .\" index@\f4isdigit()\f1 \- character is a digit@@@\f3ctype(3C)\f1 .\" index@\f4isxdigit()\f1 \- character is a hexadecimal digit@@@\f3ctype(3C)\f1 .\" index@\f4isalnum()\f1 \- character is alphanumeric@@@\f3ctype(3C)\f1 .\" index@\f4isspace()\f1 \- character is whitespace@@@\f3ctype(3C)\f1 .\" index@\f4ispunct()\f1 \- character is punctuation@@@\f3ctype(3C)\f1 .\" index@\f4isprint()\f1 \- character is a printing character@@@\f3ctype(3C)\f1 .\" index@\f4isgraph()\f1 \- character is a visible character@@@\f3ctype(3C)\f1 .\" index@\f4iscntrl()\f1 \- character is a control character@@@\f3ctype(3C)\f1 .\" index@\f4isascii()\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3ctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3ctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3ctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3ctype(3C)\f1 .\" .\" toc@\f3ctype(3C)\f1:\0\0\f4isalpha()\f1, \f4isupper()\f1, \f4islower()\f1, \f4isdigit()\f1, \f4isxdigit()\f1, \f4isalnum()\f1, \f4isspace()\f1,\n\f4ispunct()\f1, \f4isprint()\f1, \f4isgraph()\f1, \f4iscntrl()\f1, \f4isascii()\f1@@@classify characters .\" toc@\f4isalpha()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isupper()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4islower()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isxdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isalnum()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isspace()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4ispunct()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isprint()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isgraph()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4iscntrl()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isascii()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" .\" links@ctype.3c isalpha.3c .\" links@ctype.3c isupper.3c .\" links@ctype.3c islower.3c .\" links@ctype.3c isdigit.3c .\" links@ctype.3c isxdigit.3c .\" links@ctype.3c isalnum.3c .\" links@ctype.3c isspace.3c .\" links@ctype.3c ispunct.3c .\" links@ctype.3c isprint.3c .\" links@ctype.3c isgraph.3c .\" links@ctype.3c iscntrl.3c .\" links@ctype.3c isascii.3c .\" .\" fileset_database@ctype.3c PROGRAMING-MAN .\" $Header: wctype.3c,v 72.7 94/11/28 08:38:08 ssa Exp $ .TA w .TH wctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iswalpha(\|), iswupper(\|), iswlower(\|), iswdigit(\|), iswxdigit(\|), iswalnum(\|), iswspace(\|), iswpunct(\|), iswprint(\|), iswgraph(\|), iswcntrl(\|), wctype(\|), iswctype(\|) \- classify wide characters .SH SYNOPSIS .nf .C "#include " .PP .C "wctype_t wctype(const char *charclass);" .C "int iswctype(wint_t wc, wctype_t prop);" .C "int iswalnum(wint_t wc);" .C "int iswalpha(wint_t wc);" .C "int iswcntrl(wint_t wc);" .C "int iswdigit(wint_t wc);" .C "int iswgraph(wint_t wc);" .C "int iswlower(wint_t wc);" .C "int iswprint(wint_t wc);" .C "int iswpunct(wint_t wc);" .C "int iswspace(wint_t wc);" .C "int iswupper(wint_t wc);" .C "int iswxdigit(wint_t wc);" .fi .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character classification functions. They parallel the 8-bit character classification functions defined in .IR ctype(3C) . .SH DESCRIPTION These functions classify wide character values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP Each of the classification functions is a predicate that returns non-zero for true, zero for false. .PP .C wctype() is defined for valid character class names as defined in the current locale. .I charclass is a string identifying a generic character class for which codeset-specific type information is required. The following class names are defined in all locales: .CR alnum , .CR alpha , .CR blank , .CR cntrl , .CR digit , .CR graph , .CR lower , .CR print , .CR punct , .CR space , .CR upper , and .CR xdigit . User-defined class names may be specified if supported by the current locale as defined by .C setlocale() (see .IR setlocale (3C)). .C wctype() returns a value of type .C wctype_t that can be used in a subsequent call to .CR iswctype() , or .C (wctype_t)-1 if .I charclass is not valid in the current locale. .PP The classification functions return non-zero under the following circumstances, and zero otherwise: .RS .TP 20 .CI iswctype( wc , prop ) .I wc has the property defined by .IR prop . .TP .CI iswalpha( wc ) .I wc is a letter. .TP .CI iswupper( wc ) .I wc is an uppercase letter. .TP .CI iswlower( wc ) .I wc is a lowercase letter. .TP .CI iswdigit( wc ) .I wc is a decimal digit (in .SM ASCII\s0: characters [0-9]). .TP .CI iswxdigit( wc ) .I wc is a hexadecimal digit (in .SM ASCII\s0: characters [0-9], [A-F] or [a-f]). .TP .CI iswalnum( wc ) .I wc is an alphanumeric (letters or digits). .TP .CI iswspace( wc ) .I wc is a character that creates "white space" in displayed text (in .SM ASCII\s0: space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CI iswpunct( wc ) .I wc is a punctuation character (in .SM ASCII\s0: any printing character except the space character (040), digits, letters). .TP .CI iswprint( wc ) .I wc is a printing character. .TP .CI iswgraph( wc ) .I wc is a visible character (in .SM ASCII\s0: printing characters, excluding the space character (040)). .TP .CI iswcntrl( wc ) .I wc is a control character (in .SM ASCII\s0: character codes less than 040 and the delete character (0177)). .RE .PP If the argument to any of these functions is outside the domain of the function, the result is 0 (false). .PP Definitions for these functions and the types .CR wint_t , .CR wchar_t , and .C wctype_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wctype() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), multibyte(3C), setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR wctype() ": XPG4" .PP .CR iswalnum() ": XPG4" .PP .CR iswalpha() ": XPG4" .PP .CR iswcntrl() ": XPG4" .PP .CR iswctype() ": XPG4" .PP .CR iswdigit() ": XPG4" .PP .CR iswgraph() ": XPG4" .PP .CR iswlower() ": XPG4" .PP .CR iswprint() ": XPG4" .PP .CR iswpunct() ": XPG4" .PP .CR iswspace() ": XPG4" .PP .CR iswupper() ": XPG4" .PP .CR iswxdigit() ": XPG4" .\" .\" index@\f4wctype()\f1 \- classify characters according to type@@@\f3wctype(3C)\f1 .\" .\" index@\f4iswalpha\f1 \- character is alpha@@@\f3wctype(3C)\f1 .\" index@\f4iswupper\f1 \- character is uppercase@@@\f3wctype(3C)\f1 .\" index@\f4iswlower\f1 \- character is lowercase@@@\f3wctype(3C)\f1 .\" index@\f4iswdigit\f1 \- character is a digit@@@\f3wctype(3C)\f1 .\" index@\f4iswxdigit\f1 \- character is a hexadecimal digit@@@\f3wctype(3C)\f1 .\" index@\f4iswalnum\f1 \- character is alphanumeric@@@\f3wctype(3C)\f1 .\" index@\f4iswspace\f1 \- character is whitespace@@@\f3wctype(3C)\f1 .\" index@\f4iswpunct\f1 \- character is punctuation@@@\f3wctype(3C)\f1 .\" index@\f4iswprint\f1 \- character is a printing character@@@\f3wctype(3C)\f1 .\" index@\f4iswgraph\f1 \- character is a visible character@@@\f3wctype(3C)\f1 .\" index@\f4iswcntrl\f1 \- character is a control character@@@\f3wctype(3C)\f1 .\" index@\f4ISASCII\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3wctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3wctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3wctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3wctype(3C)\f1 .\" .\" toc@\f3wctype(3C)\f1:\0\0\f4iswalpha\f1, \f4iswupper\f1, \f4iswlower\f1, \f4iswdigit\f1, \f4iswxdigit\f1, \f4iswalnum\f1, \f4iswspace\f1,\n\f4iswpunct\f1, \f4iswprint\f1, \f4iswgraph\f1, \f4iswcntrl\f1@@@classify wide characters .\" toc@\f4iswalpha\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswupper\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswlower\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswxdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswalnum\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswspace\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswpunct\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswprint\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswgraph\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswcntrl\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" .\" links@wctype.3c iswctype.3c .\" links@wctype.3c iswalpha.3c .\" links@wctype.3c iswupper.3c .\" links@wctype.3c iswlower.3c .\" links@wctype.3c iswdigit.3c .\" links@wctype.3c iswxdigit.3c .\" links@wctype.3c iswalnum.3c .\" links@wctype.3c iswspace.3c .\" links@wctype.3c iswpunct.3c .\" links@wctype.3c iswprint.3c .\" links@wctype.3c iswgraph.3c .\" links@wctype.3c iswcntrl.3c .\" .\" fileset_database@wctype.3c PROGRAMING-MAN .\" $Header: wctype.3c,v 72.7 94/11/28 08:38:08 ssa Exp $ .TA w .TH wctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iswalpha(\|), iswupper(\|), iswlower(\|), iswdigit(\|), iswxdigit(\|), iswalnum(\|), iswspace(\|), iswpunct(\|), iswprint(\|), iswgraph(\|), iswcntrl(\|), wctype(\|), iswctype(\|) \- classify wide characters .SH SYNOPSIS .nf .C "#include " .PP .C "wctype_t wctype(const char *charclass);" .C "int iswctype(wint_t wc, wctype_t prop);" .C "int iswalnum(wint_t wc);" .C "int iswalpha(wint_t wc);" .C "int iswcntrl(wint_t wc);" .C "int iswdigit(wint_t wc);" .C "int iswgraph(wint_t wc);" .C "int iswlower(wint_t wc);" .C "int iswprint(wint_t wc);" .C "int iswpunct(wint_t wc);" .C "int iswspace(wint_t wc);" .C "int iswupper(wint_t wc);" .C "int iswxdigit(wint_t wc);" .fi .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character classification functions. They parallel the 8-bit character classification functions defined in .IR ctype(3C) . .SH DESCRIPTION These functions classify wide character values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP Each of the classification functions is a predicate that returns non-zero for true, zero for false. .PP .C wctype() is defined for valid character class names as defined in the current locale. .I charclass is a string identifying a generic character class for which codeset-specific type information is required. The following class names are defined in all locales: .CR alnum , .CR alpha , .CR blank , .CR cntrl , .CR digit , .CR graph , .CR lower , .CR print , .CR punct , .CR space , .CR upper , and .CR xdigit . User-defined class names may be specified if supported by the current locale as defined by .C setlocale() (see .IR setlocale (3C)). .C wctype() returns a value of type .C wctype_t that can be used in a subsequent call to .CR iswctype() , or .C (wctype_t)-1 if .I charclass is not valid in the current locale. .PP The classification functions return non-zero under the following circumstances, and zero otherwise: .RS .TP 20 .CI iswctype( wc , prop ) .I wc has the property defined by .IR prop . .TP .CI iswalpha( wc ) .I wc is a letter. .TP .CI iswupper( wc ) .I wc is an uppercase letter. .TP .CI iswlower( wc ) .I wc is a lowercase letter. .TP .CI iswdigit( wc ) .I wc is a decimal digit (in .SM ASCII\s0: characters [0-9]). .TP .CI iswxdigit( wc ) .I wc is a hexadecimal digit (in .SM ASCII\s0: characters [0-9], [A-F] or [a-f]). .TP .CI iswalnum( wc ) .I wc is an alphanumeric (letters or digits). .TP .CI iswspace( wc ) .I wc is a character that creates "white space" in displayed text (in .SM ASCII\s0: space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CI iswpunct( wc ) .I wc is a punctuation character (in .SM ASCII\s0: any printing character except the space character (040), digits, letters). .TP .CI iswprint( wc ) .I wc is a printing character. .TP .CI iswgraph( wc ) .I wc is a visible character (in .SM ASCII\s0: printing characters, excluding the space character (040)). .TP .CI iswcntrl( wc ) .I wc is a control character (in .SM ASCII\s0: character codes less than 040 and the delete character (0177)). .RE .PP If the argument to any of these functions is outside the domain of the function, the result is 0 (false). .PP Definitions for these functions and the types .CR wint_t , .CR wchar_t , and .C wctype_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wctype() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), multibyte(3C), setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR wctype() ": XPG4" .PP .CR iswalnum() ": XPG4" .PP .CR iswalpha() ": XPG4" .PP .CR iswcntrl() ": XPG4" .PP .CR iswctype() ": XPG4" .PP .CR iswdigit() ": XPG4" .PP .CR iswgraph() ": XPG4" .PP .CR iswlower() ": XPG4" .PP .CR iswprint() ": XPG4" .PP .CR iswpunct() ": XPG4" .PP .CR iswspace() ": XPG4" .PP .CR iswupper() ": XPG4" .PP .CR iswxdigit() ": XPG4" .\" .\" index@\f4wctype()\f1 \- classify characters according to type@@@\f3wctype(3C)\f1 .\" .\" index@\f4iswalpha\f1 \- character is alpha@@@\f3wctype(3C)\f1 .\" index@\f4iswupper\f1 \- character is uppercase@@@\f3wctype(3C)\f1 .\" index@\f4iswlower\f1 \- character is lowercase@@@\f3wctype(3C)\f1 .\" index@\f4iswdigit\f1 \- character is a digit@@@\f3wctype(3C)\f1 .\" index@\f4iswxdigit\f1 \- character is a hexadecimal digit@@@\f3wctype(3C)\f1 .\" index@\f4iswalnum\f1 \- character is alphanumeric@@@\f3wctype(3C)\f1 .\" index@\f4iswspace\f1 \- character is whitespace@@@\f3wctype(3C)\f1 .\" index@\f4iswpunct\f1 \- character is punctuation@@@\f3wctype(3C)\f1 .\" index@\f4iswprint\f1 \- character is a printing character@@@\f3wctype(3C)\f1 .\" index@\f4iswgraph\f1 \- character is a visible character@@@\f3wctype(3C)\f1 .\" index@\f4iswcntrl\f1 \- character is a control character@@@\f3wctype(3C)\f1 .\" index@\f4ISASCII\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3wctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3wctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3wctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3wctype(3C)\f1 .\" .\" toc@\f3wctype(3C)\f1:\0\0\f4iswalpha\f1, \f4iswupper\f1, \f4iswlower\f1, \f4iswdigit\f1, \f4iswxdigit\f1, \f4iswalnum\f1, \f4iswspace\f1,\n\f4iswpunct\f1, \f4iswprint\f1, \f4iswgraph\f1, \f4iswcntrl\f1@@@classify wide characters .\" toc@\f4iswalpha\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswupper\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswlower\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswxdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswalnum\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswspace\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswpunct\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswprint\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswgraph\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswcntrl\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" .\" links@wctype.3c iswctype.3c .\" links@wctype.3c iswalpha.3c .\" links@wctype.3c iswupper.3c .\" links@wctype.3c iswlower.3c .\" links@wctype.3c iswdigit.3c .\" links@wctype.3c iswxdigit.3c .\" links@wctype.3c iswalnum.3c .\" links@wctype.3c iswspace.3c .\" links@wctype.3c iswpunct.3c .\" links@wctype.3c iswprint.3c .\" links@wctype.3c iswgraph.3c .\" links@wctype.3c iswcntrl.3c .\" .\" fileset_database@wctype.3c PROGRAMING-MAN .\" $Header: wctype.3c,v 72.7 94/11/28 08:38:08 ssa Exp $ .TA w .TH wctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iswalpha(\|), iswupper(\|), iswlower(\|), iswdigit(\|), iswxdigit(\|), iswalnum(\|), iswspace(\|), iswpunct(\|), iswprint(\|), iswgraph(\|), iswcntrl(\|), wctype(\|), iswctype(\|) \- classify wide characters .SH SYNOPSIS .nf .C "#include " .PP .C "wctype_t wctype(const char *charclass);" .C "int iswctype(wint_t wc, wctype_t prop);" .C "int iswalnum(wint_t wc);" .C "int iswalpha(wint_t wc);" .C "int iswcntrl(wint_t wc);" .C "int iswdigit(wint_t wc);" .C "int iswgraph(wint_t wc);" .C "int iswlower(wint_t wc);" .C "int iswprint(wint_t wc);" .C "int iswpunct(wint_t wc);" .C "int iswspace(wint_t wc);" .C "int iswupper(wint_t wc);" .C "int iswxdigit(wint_t wc);" .fi .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character classification functions. They parallel the 8-bit character classification functions defined in .IR ctype(3C) . .SH DESCRIPTION These functions classify wide character values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP Each of the classification functions is a predicate that returns non-zero for true, zero for false. .PP .C wctype() is defined for valid character class names as defined in the current locale. .I charclass is a string identifying a generic character class for which codeset-specific type information is required. The following class names are defined in all locales: .CR alnum , .CR alpha , .CR blank , .CR cntrl , .CR digit , .CR graph , .CR lower , .CR print , .CR punct , .CR space , .CR upper , and .CR xdigit . User-defined class names may be specified if supported by the current locale as defined by .C setlocale() (see .IR setlocale (3C)). .C wctype() returns a value of type .C wctype_t that can be used in a subsequent call to .CR iswctype() , or .C (wctype_t)-1 if .I charclass is not valid in the current locale. .PP The classification functions return non-zero under the following circumstances, and zero otherwise: .RS .TP 20 .CI iswctype( wc , prop ) .I wc has the property defined by .IR prop . .TP .CI iswalpha( wc ) .I wc is a letter. .TP .CI iswupper( wc ) .I wc is an uppercase letter. .TP .CI iswlower( wc ) .I wc is a lowercase letter. .TP .CI iswdigit( wc ) .I wc is a decimal digit (in .SM ASCII\s0: characters [0-9]). .TP .CI iswxdigit( wc ) .I wc is a hexadecimal digit (in .SM ASCII\s0: characters [0-9], [A-F] or [a-f]). .TP .CI iswalnum( wc ) .I wc is an alphanumeric (letters or digits). .TP .CI iswspace( wc ) .I wc is a character that creates "white space" in displayed text (in .SM ASCII\s0: space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CI iswpunct( wc ) .I wc is a punctuation character (in .SM ASCII\s0: any printing character except the space character (040), digits, letters). .TP .CI iswprint( wc ) .I wc is a printing character. .TP .CI iswgraph( wc ) .I wc is a visible character (in .SM ASCII\s0: printing characters, excluding the space character (040)). .TP .CI iswcntrl( wc ) .I wc is a control character (in .SM ASCII\s0: character codes less than 040 and the delete character (0177)). .RE .PP If the argument to any of these functions is outside the domain of the function, the result is 0 (false). .PP Definitions for these functions and the types .CR wint_t , .CR wchar_t , and .C wctype_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wctype() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), multibyte(3C), setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR wctype() ": XPG4" .PP .CR iswalnum() ": XPG4" .PP .CR iswalpha() ": XPG4" .PP .CR iswcntrl() ": XPG4" .PP .CR iswctype() ": XPG4" .PP .CR iswdigit() ": XPG4" .PP .CR iswgraph() ": XPG4" .PP .CR iswlower() ": XPG4" .PP .CR iswprint() ": XPG4" .PP .CR iswpunct() ": XPG4" .PP .CR iswspace() ": XPG4" .PP .CR iswupper() ": XPG4" .PP .CR iswxdigit() ": XPG4" .\" .\" index@\f4wctype()\f1 \- classify characters according to type@@@\f3wctype(3C)\f1 .\" .\" index@\f4iswalpha\f1 \- character is alpha@@@\f3wctype(3C)\f1 .\" index@\f4iswupper\f1 \- character is uppercase@@@\f3wctype(3C)\f1 .\" index@\f4iswlower\f1 \- character is lowercase@@@\f3wctype(3C)\f1 .\" index@\f4iswdigit\f1 \- character is a digit@@@\f3wctype(3C)\f1 .\" index@\f4iswxdigit\f1 \- character is a hexadecimal digit@@@\f3wctype(3C)\f1 .\" index@\f4iswalnum\f1 \- character is alphanumeric@@@\f3wctype(3C)\f1 .\" index@\f4iswspace\f1 \- character is whitespace@@@\f3wctype(3C)\f1 .\" index@\f4iswpunct\f1 \- character is punctuation@@@\f3wctype(3C)\f1 .\" index@\f4iswprint\f1 \- character is a printing character@@@\f3wctype(3C)\f1 .\" index@\f4iswgraph\f1 \- character is a visible character@@@\f3wctype(3C)\f1 .\" index@\f4iswcntrl\f1 \- character is a control character@@@\f3wctype(3C)\f1 .\" index@\f4ISASCII\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3wctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3wctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3wctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3wctype(3C)\f1 .\" .\" toc@\f3wctype(3C)\f1:\0\0\f4iswalpha\f1, \f4iswupper\f1, \f4iswlower\f1, \f4iswdigit\f1, \f4iswxdigit\f1, \f4iswalnum\f1, \f4iswspace\f1,\n\f4iswpunct\f1, \f4iswprint\f1, \f4iswgraph\f1, \f4iswcntrl\f1@@@classify wide characters .\" toc@\f4iswalpha\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswupper\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswlower\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswxdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswalnum\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswspace\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswpunct\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswprint\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswgraph\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswcntrl\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" .\" links@wctype.3c iswctype.3c .\" links@wctype.3c iswalpha.3c .\" links@wctype.3c iswupper.3c .\" links@wctype.3c iswlower.3c .\" links@wctype.3c iswdigit.3c .\" links@wctype.3c iswxdigit.3c .\" links@wctype.3c iswalnum.3c .\" links@wctype.3c iswspace.3c .\" links@wctype.3c iswpunct.3c .\" links@wctype.3c iswprint.3c .\" links@wctype.3c iswgraph.3c .\" links@wctype.3c iswcntrl.3c .\" .\" fileset_database@wctype.3c PROGRAMING-MAN .\" $Header: wctype.3c,v 72.7 94/11/28 08:38:08 ssa Exp $ .TA w .TH wctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iswalpha(\|), iswupper(\|), iswlower(\|), iswdigit(\|), iswxdigit(\|), iswalnum(\|), iswspace(\|), iswpunct(\|), iswprint(\|), iswgraph(\|), iswcntrl(\|), wctype(\|), iswctype(\|) \- classify wide characters .SH SYNOPSIS .nf .C "#include " .PP .C "wctype_t wctype(const char *charclass);" .C "int iswctype(wint_t wc, wctype_t prop);" .C "int iswalnum(wint_t wc);" .C "int iswalpha(wint_t wc);" .C "int iswcntrl(wint_t wc);" .C "int iswdigit(wint_t wc);" .C "int iswgraph(wint_t wc);" .C "int iswlower(wint_t wc);" .C "int iswprint(wint_t wc);" .C "int iswpunct(wint_t wc);" .C "int iswspace(wint_t wc);" .C "int iswupper(wint_t wc);" .C "int iswxdigit(wint_t wc);" .fi .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character classification functions. They parallel the 8-bit character classification functions defined in .IR ctype(3C) . .SH DESCRIPTION These functions classify wide character values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP Each of the classification functions is a predicate that returns non-zero for true, zero for false. .PP .C wctype() is defined for valid character class names as defined in the current locale. .I charclass is a string identifying a generic character class for which codeset-specific type information is required. The following class names are defined in all locales: .CR alnum , .CR alpha , .CR blank , .CR cntrl , .CR digit , .CR graph , .CR lower , .CR print , .CR punct , .CR space , .CR upper , and .CR xdigit . User-defined class names may be specified if supported by the current locale as defined by .C setlocale() (see .IR setlocale (3C)). .C wctype() returns a value of type .C wctype_t that can be used in a subsequent call to .CR iswctype() , or .C (wctype_t)-1 if .I charclass is not valid in the current locale. .PP The classification functions return non-zero under the following circumstances, and zero otherwise: .RS .TP 20 .CI iswctype( wc , prop ) .I wc has the property defined by .IR prop . .TP .CI iswalpha( wc ) .I wc is a letter. .TP .CI iswupper( wc ) .I wc is an uppercase letter. .TP .CI iswlower( wc ) .I wc is a lowercase letter. .TP .CI iswdigit( wc ) .I wc is a decimal digit (in .SM ASCII\s0: characters [0-9]). .TP .CI iswxdigit( wc ) .I wc is a hexadecimal digit (in .SM ASCII\s0: characters [0-9], [A-F] or [a-f]). .TP .CI iswalnum( wc ) .I wc is an alphanumeric (letters or digits). .TP .CI iswspace( wc ) .I wc is a character that creates "white space" in displayed text (in .SM ASCII\s0: space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CI iswpunct( wc ) .I wc is a punctuation character (in .SM ASCII\s0: any printing character except the space character (040), digits, letters). .TP .CI iswprint( wc ) .I wc is a printing character. .TP .CI iswgraph( wc ) .I wc is a visible character (in .SM ASCII\s0: printing characters, excluding the space character (040)). .TP .CI iswcntrl( wc ) .I wc is a control character (in .SM ASCII\s0: character codes less than 040 and the delete character (0177)). .RE .PP If the argument to any of these functions is outside the domain of the function, the result is 0 (false). .PP Definitions for these functions and the types .CR wint_t , .CR wchar_t , and .C wctype_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wctype() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), multibyte(3C), setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR wctype() ": XPG4" .PP .CR iswalnum() ": XPG4" .PP .CR iswalpha() ": XPG4" .PP .CR iswcntrl() ": XPG4" .PP .CR iswctype() ": XPG4" .PP .CR iswdigit() ": XPG4" .PP .CR iswgraph() ": XPG4" .PP .CR iswlower() ": XPG4" .PP .CR iswprint() ": XPG4" .PP .CR iswpunct() ": XPG4" .PP .CR iswspace() ": XPG4" .PP .CR iswupper() ": XPG4" .PP .CR iswxdigit() ": XPG4" .\" .\" index@\f4wctype()\f1 \- classify characters according to type@@@\f3wctype(3C)\f1 .\" .\" index@\f4iswalpha\f1 \- character is alpha@@@\f3wctype(3C)\f1 .\" index@\f4iswupper\f1 \- character is uppercase@@@\f3wctype(3C)\f1 .\" index@\f4iswlower\f1 \- character is lowercase@@@\f3wctype(3C)\f1 .\" index@\f4iswdigit\f1 \- character is a digit@@@\f3wctype(3C)\f1 .\" index@\f4iswxdigit\f1 \- character is a hexadecimal digit@@@\f3wctype(3C)\f1 .\" index@\f4iswalnum\f1 \- character is alphanumeric@@@\f3wctype(3C)\f1 .\" index@\f4iswspace\f1 \- character is whitespace@@@\f3wctype(3C)\f1 .\" index@\f4iswpunct\f1 \- character is punctuation@@@\f3wctype(3C)\f1 .\" index@\f4iswprint\f1 \- character is a printing character@@@\f3wctype(3C)\f1 .\" index@\f4iswgraph\f1 \- character is a visible character@@@\f3wctype(3C)\f1 .\" index@\f4iswcntrl\f1 \- character is a control character@@@\f3wctype(3C)\f1 .\" index@\f4ISASCII\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3wctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3wctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3wctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3wctype(3C)\f1 .\" .\" toc@\f3wctype(3C)\f1:\0\0\f4iswalpha\f1, \f4iswupper\f1, \f4iswlower\f1, \f4iswdigit\f1, \f4iswxdigit\f1, \f4iswalnum\f1, \f4iswspace\f1,\n\f4iswpunct\f1, \f4iswprint\f1, \f4iswgraph\f1, \f4iswcntrl\f1@@@classify wide characters .\" toc@\f4iswalpha\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswupper\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswlower\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswxdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswalnum\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswspace\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswpunct\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswprint\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswgraph\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswcntrl\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" .\" links@wctype.3c iswctype.3c .\" links@wctype.3c iswalpha.3c .\" links@wctype.3c iswupper.3c .\" links@wctype.3c iswlower.3c .\" links@wctype.3c iswdigit.3c .\" links@wctype.3c iswxdigit.3c .\" links@wctype.3c iswalnum.3c .\" links@wctype.3c iswspace.3c .\" links@wctype.3c iswpunct.3c .\" links@wctype.3c iswprint.3c .\" links@wctype.3c iswgraph.3c .\" links@wctype.3c iswcntrl.3c .\" .\" fileset_database@wctype.3c PROGRAMING-MAN .\" $Header: wctype.3c,v 72.7 94/11/28 08:38:08 ssa Exp $ .TA w .TH wctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iswalpha(\|), iswupper(\|), iswlower(\|), iswdigit(\|), iswxdigit(\|), iswalnum(\|), iswspace(\|), iswpunct(\|), iswprint(\|), iswgraph(\|), iswcntrl(\|), wctype(\|), iswctype(\|) \- classify wide characters .SH SYNOPSIS .nf .C "#include " .PP .C "wctype_t wctype(const char *charclass);" .C "int iswctype(wint_t wc, wctype_t prop);" .C "int iswalnum(wint_t wc);" .C "int iswalpha(wint_t wc);" .C "int iswcntrl(wint_t wc);" .C "int iswdigit(wint_t wc);" .C "int iswgraph(wint_t wc);" .C "int iswlower(wint_t wc);" .C "int iswprint(wint_t wc);" .C "int iswpunct(wint_t wc);" .C "int iswspace(wint_t wc);" .C "int iswupper(wint_t wc);" .C "int iswxdigit(wint_t wc);" .fi .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character classification functions. They parallel the 8-bit character classification functions defined in .IR ctype(3C) . .SH DESCRIPTION These functions classify wide character values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP Each of the classification functions is a predicate that returns non-zero for true, zero for false. .PP .C wctype() is defined for valid character class names as defined in the current locale. .I charclass is a string identifying a generic character class for which codeset-specific type information is required. The following class names are defined in all locales: .CR alnum , .CR alpha , .CR blank , .CR cntrl , .CR digit , .CR graph , .CR lower , .CR print , .CR punct , .CR space , .CR upper , and .CR xdigit . User-defined class names may be specified if supported by the current locale as defined by .C setlocale() (see .IR setlocale (3C)). .C wctype() returns a value of type .C wctype_t that can be used in a subsequent call to .CR iswctype() , or .C (wctype_t)-1 if .I charclass is not valid in the current locale. .PP The classification functions return non-zero under the following circumstances, and zero otherwise: .RS .TP 20 .CI iswctype( wc , prop ) .I wc has the property defined by .IR prop . .TP .CI iswalpha( wc ) .I wc is a letter. .TP .CI iswupper( wc ) .I wc is an uppercase letter. .TP .CI iswlower( wc ) .I wc is a lowercase letter. .TP .CI iswdigit( wc ) .I wc is a decimal digit (in .SM ASCII\s0: characters [0-9]). .TP .CI iswxdigit( wc ) .I wc is a hexadecimal digit (in .SM ASCII\s0: characters [0-9], [A-F] or [a-f]). .TP .CI iswalnum( wc ) .I wc is an alphanumeric (letters or digits). .TP .CI iswspace( wc ) .I wc is a character that creates "white space" in displayed text (in .SM ASCII\s0: space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CI iswpunct( wc ) .I wc is a punctuation character (in .SM ASCII\s0: any printing character except the space character (040), digits, letters). .TP .CI iswprint( wc ) .I wc is a printing character. .TP .CI iswgraph( wc ) .I wc is a visible character (in .SM ASCII\s0: printing characters, excluding the space character (040)). .TP .CI iswcntrl( wc ) .I wc is a control character (in .SM ASCII\s0: character codes less than 040 and the delete character (0177)). .RE .PP If the argument to any of these functions is outside the domain of the function, the result is 0 (false). .PP Definitions for these functions and the types .CR wint_t , .CR wchar_t , and .C wctype_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wctype() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), multibyte(3C), setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR wctype() ": XPG4" .PP .CR iswalnum() ": XPG4" .PP .CR iswalpha() ": XPG4" .PP .CR iswcntrl() ": XPG4" .PP .CR iswctype() ": XPG4" .PP .CR iswdigit() ": XPG4" .PP .CR iswgraph() ": XPG4" .PP .CR iswlower() ": XPG4" .PP .CR iswprint() ": XPG4" .PP .CR iswpunct() ": XPG4" .PP .CR iswspace() ": XPG4" .PP .CR iswupper() ": XPG4" .PP .CR iswxdigit() ": XPG4" .\" .\" index@\f4wctype()\f1 \- classify characters according to type@@@\f3wctype(3C)\f1 .\" .\" index@\f4iswalpha\f1 \- character is alpha@@@\f3wctype(3C)\f1 .\" index@\f4iswupper\f1 \- character is uppercase@@@\f3wctype(3C)\f1 .\" index@\f4iswlower\f1 \- character is lowercase@@@\f3wctype(3C)\f1 .\" index@\f4iswdigit\f1 \- character is a digit@@@\f3wctype(3C)\f1 .\" index@\f4iswxdigit\f1 \- character is a hexadecimal digit@@@\f3wctype(3C)\f1 .\" index@\f4iswalnum\f1 \- character is alphanumeric@@@\f3wctype(3C)\f1 .\" index@\f4iswspace\f1 \- character is whitespace@@@\f3wctype(3C)\f1 .\" index@\f4iswpunct\f1 \- character is punctuation@@@\f3wctype(3C)\f1 .\" index@\f4iswprint\f1 \- character is a printing character@@@\f3wctype(3C)\f1 .\" index@\f4iswgraph\f1 \- character is a visible character@@@\f3wctype(3C)\f1 .\" index@\f4iswcntrl\f1 \- character is a control character@@@\f3wctype(3C)\f1 .\" index@\f4ISASCII\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3wctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3wctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3wctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3wctype(3C)\f1 .\" .\" toc@\f3wctype(3C)\f1:\0\0\f4iswalpha\f1, \f4iswupper\f1, \f4iswlower\f1, \f4iswdigit\f1, \f4iswxdigit\f1, \f4iswalnum\f1, \f4iswspace\f1,\n\f4iswpunct\f1, \f4iswprint\f1, \f4iswgraph\f1, \f4iswcntrl\f1@@@classify wide characters .\" toc@\f4iswalpha\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswupper\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswlower\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswxdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswalnum\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswspace\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswpunct\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswprint\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswgraph\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswcntrl\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" .\" links@wctype.3c iswctype.3c .\" links@wctype.3c iswalpha.3c .\" links@wctype.3c iswupper.3c .\" links@wctype.3c iswlower.3c .\" links@wctype.3c iswdigit.3c .\" links@wctype.3c iswxdigit.3c .\" links@wctype.3c iswalnum.3c .\" links@wctype.3c iswspace.3c .\" links@wctype.3c iswpunct.3c .\" links@wctype.3c iswprint.3c .\" links@wctype.3c iswgraph.3c .\" links@wctype.3c iswcntrl.3c .\" .\" fileset_database@wctype.3c PROGRAMING-MAN .\" $Header: wctype.3c,v 72.7 94/11/28 08:38:08 ssa Exp $ .TA w .TH wctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iswalpha(\|), iswupper(\|), iswlower(\|), iswdigit(\|), iswxdigit(\|), iswalnum(\|), iswspace(\|), iswpunct(\|), iswprint(\|), iswgraph(\|), iswcntrl(\|), wctype(\|), iswctype(\|) \- classify wide characters .SH SYNOPSIS .nf .C "#include " .PP .C "wctype_t wctype(const char *charclass);" .C "int iswctype(wint_t wc, wctype_t prop);" .C "int iswalnum(wint_t wc);" .C "int iswalpha(wint_t wc);" .C "int iswcntrl(wint_t wc);" .C "int iswdigit(wint_t wc);" .C "int iswgraph(wint_t wc);" .C "int iswlower(wint_t wc);" .C "int iswprint(wint_t wc);" .C "int iswpunct(wint_t wc);" .C "int iswspace(wint_t wc);" .C "int iswupper(wint_t wc);" .C "int iswxdigit(wint_t wc);" .fi .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character classification functions. They parallel the 8-bit character classification functions defined in .IR ctype(3C) . .SH DESCRIPTION These functions classify wide character values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP Each of the classification functions is a predicate that returns non-zero for true, zero for false. .PP .C wctype() is defined for valid character class names as defined in the current locale. .I charclass is a string identifying a generic character class for which codeset-specific type information is required. The following class names are defined in all locales: .CR alnum , .CR alpha , .CR blank , .CR cntrl , .CR digit , .CR graph , .CR lower , .CR print , .CR punct , .CR space , .CR upper , and .CR xdigit . User-defined class names may be specified if supported by the current locale as defined by .C setlocale() (see .IR setlocale (3C)). .C wctype() returns a value of type .C wctype_t that can be used in a subsequent call to .CR iswctype() , or .C (wctype_t)-1 if .I charclass is not valid in the current locale. .PP The classification functions return non-zero under the following circumstances, and zero otherwise: .RS .TP 20 .CI iswctype( wc , prop ) .I wc has the property defined by .IR prop . .TP .CI iswalpha( wc ) .I wc is a letter. .TP .CI iswupper( wc ) .I wc is an uppercase letter. .TP .CI iswlower( wc ) .I wc is a lowercase letter. .TP .CI iswdigit( wc ) .I wc is a decimal digit (in .SM ASCII\s0: characters [0-9]). .TP .CI iswxdigit( wc ) .I wc is a hexadecimal digit (in .SM ASCII\s0: characters [0-9], [A-F] or [a-f]). .TP .CI iswalnum( wc ) .I wc is an alphanumeric (letters or digits). .TP .CI iswspace( wc ) .I wc is a character that creates "white space" in displayed text (in .SM ASCII\s0: space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CI iswpunct( wc ) .I wc is a punctuation character (in .SM ASCII\s0: any printing character except the space character (040), digits, letters). .TP .CI iswprint( wc ) .I wc is a printing character. .TP .CI iswgraph( wc ) .I wc is a visible character (in .SM ASCII\s0: printing characters, excluding the space character (040)). .TP .CI iswcntrl( wc ) .I wc is a control character (in .SM ASCII\s0: character codes less than 040 and the delete character (0177)). .RE .PP If the argument to any of these functions is outside the domain of the function, the result is 0 (false). .PP Definitions for these functions and the types .CR wint_t , .CR wchar_t , and .C wctype_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wctype() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), multibyte(3C), setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR wctype() ": XPG4" .PP .CR iswalnum() ": XPG4" .PP .CR iswalpha() ": XPG4" .PP .CR iswcntrl() ": XPG4" .PP .CR iswctype() ": XPG4" .PP .CR iswdigit() ": XPG4" .PP .CR iswgraph() ": XPG4" .PP .CR iswlower() ": XPG4" .PP .CR iswprint() ": XPG4" .PP .CR iswpunct() ": XPG4" .PP .CR iswspace() ": XPG4" .PP .CR iswupper() ": XPG4" .PP .CR iswxdigit() ": XPG4" .\" .\" index@\f4wctype()\f1 \- classify characters according to type@@@\f3wctype(3C)\f1 .\" .\" index@\f4iswalpha\f1 \- character is alpha@@@\f3wctype(3C)\f1 .\" index@\f4iswupper\f1 \- character is uppercase@@@\f3wctype(3C)\f1 .\" index@\f4iswlower\f1 \- character is lowercase@@@\f3wctype(3C)\f1 .\" index@\f4iswdigit\f1 \- character is a digit@@@\f3wctype(3C)\f1 .\" index@\f4iswxdigit\f1 \- character is a hexadecimal digit@@@\f3wctype(3C)\f1 .\" index@\f4iswalnum\f1 \- character is alphanumeric@@@\f3wctype(3C)\f1 .\" index@\f4iswspace\f1 \- character is whitespace@@@\f3wctype(3C)\f1 .\" index@\f4iswpunct\f1 \- character is punctuation@@@\f3wctype(3C)\f1 .\" index@\f4iswprint\f1 \- character is a printing character@@@\f3wctype(3C)\f1 .\" index@\f4iswgraph\f1 \- character is a visible character@@@\f3wctype(3C)\f1 .\" index@\f4iswcntrl\f1 \- character is a control character@@@\f3wctype(3C)\f1 .\" index@\f4ISASCII\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3wctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3wctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3wctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3wctype(3C)\f1 .\" .\" toc@\f3wctype(3C)\f1:\0\0\f4iswalpha\f1, \f4iswupper\f1, \f4iswlower\f1, \f4iswdigit\f1, \f4iswxdigit\f1, \f4iswalnum\f1, \f4iswspace\f1,\n\f4iswpunct\f1, \f4iswprint\f1, \f4iswgraph\f1, \f4iswcntrl\f1@@@classify wide characters .\" toc@\f4iswalpha\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswupper\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswlower\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswxdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswalnum\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswspace\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswpunct\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswprint\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswgraph\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswcntrl\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" .\" links@wctype.3c iswctype.3c .\" links@wctype.3c iswalpha.3c .\" links@wctype.3c iswupper.3c .\" links@wctype.3c iswlower.3c .\" links@wctype.3c iswdigit.3c .\" links@wctype.3c iswxdigit.3c .\" links@wctype.3c iswalnum.3c .\" links@wctype.3c iswspace.3c .\" links@wctype.3c iswpunct.3c .\" links@wctype.3c iswprint.3c .\" links@wctype.3c iswgraph.3c .\" links@wctype.3c iswcntrl.3c .\" .\" fileset_database@wctype.3c PROGRAMING-MAN .\" $Header: wctype.3c,v 72.7 94/11/28 08:38:08 ssa Exp $ .TA w .TH wctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iswalpha(\|), iswupper(\|), iswlower(\|), iswdigit(\|), iswxdigit(\|), iswalnum(\|), iswspace(\|), iswpunct(\|), iswprint(\|), iswgraph(\|), iswcntrl(\|), wctype(\|), iswctype(\|) \- classify wide characters .SH SYNOPSIS .nf .C "#include " .PP .C "wctype_t wctype(const char *charclass);" .C "int iswctype(wint_t wc, wctype_t prop);" .C "int iswalnum(wint_t wc);" .C "int iswalpha(wint_t wc);" .C "int iswcntrl(wint_t wc);" .C "int iswdigit(wint_t wc);" .C "int iswgraph(wint_t wc);" .C "int iswlower(wint_t wc);" .C "int iswprint(wint_t wc);" .C "int iswpunct(wint_t wc);" .C "int iswspace(wint_t wc);" .C "int iswupper(wint_t wc);" .C "int iswxdigit(wint_t wc);" .fi .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character classification functions. They parallel the 8-bit character classification functions defined in .IR ctype(3C) . .SH DESCRIPTION These functions classify wide character values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP Each of the classification functions is a predicate that returns non-zero for true, zero for false. .PP .C wctype() is defined for valid character class names as defined in the current locale. .I charclass is a string identifying a generic character class for which codeset-specific type information is required. The following class names are defined in all locales: .CR alnum , .CR alpha , .CR blank , .CR cntrl , .CR digit , .CR graph , .CR lower , .CR print , .CR punct , .CR space , .CR upper , and .CR xdigit . User-defined class names may be specified if supported by the current locale as defined by .C setlocale() (see .IR setlocale (3C)). .C wctype() returns a value of type .C wctype_t that can be used in a subsequent call to .CR iswctype() , or .C (wctype_t)-1 if .I charclass is not valid in the current locale. .PP The classification functions return non-zero under the following circumstances, and zero otherwise: .RS .TP 20 .CI iswctype( wc , prop ) .I wc has the property defined by .IR prop . .TP .CI iswalpha( wc ) .I wc is a letter. .TP .CI iswupper( wc ) .I wc is an uppercase letter. .TP .CI iswlower( wc ) .I wc is a lowercase letter. .TP .CI iswdigit( wc ) .I wc is a decimal digit (in .SM ASCII\s0: characters [0-9]). .TP .CI iswxdigit( wc ) .I wc is a hexadecimal digit (in .SM ASCII\s0: characters [0-9], [A-F] or [a-f]). .TP .CI iswalnum( wc ) .I wc is an alphanumeric (letters or digits). .TP .CI iswspace( wc ) .I wc is a character that creates "white space" in displayed text (in .SM ASCII\s0: space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CI iswpunct( wc ) .I wc is a punctuation character (in .SM ASCII\s0: any printing character except the space character (040), digits, letters). .TP .CI iswprint( wc ) .I wc is a printing character. .TP .CI iswgraph( wc ) .I wc is a visible character (in .SM ASCII\s0: printing characters, excluding the space character (040)). .TP .CI iswcntrl( wc ) .I wc is a control character (in .SM ASCII\s0: character codes less than 040 and the delete character (0177)). .RE .PP If the argument to any of these functions is outside the domain of the function, the result is 0 (false). .PP Definitions for these functions and the types .CR wint_t , .CR wchar_t , and .C wctype_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wctype() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), multibyte(3C), setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR wctype() ": XPG4" .PP .CR iswalnum() ": XPG4" .PP .CR iswalpha() ": XPG4" .PP .CR iswcntrl() ": XPG4" .PP .CR iswctype() ": XPG4" .PP .CR iswdigit() ": XPG4" .PP .CR iswgraph() ": XPG4" .PP .CR iswlower() ": XPG4" .PP .CR iswprint() ": XPG4" .PP .CR iswpunct() ": XPG4" .PP .CR iswspace() ": XPG4" .PP .CR iswupper() ": XPG4" .PP .CR iswxdigit() ": XPG4" .\" .\" index@\f4wctype()\f1 \- classify characters according to type@@@\f3wctype(3C)\f1 .\" .\" index@\f4iswalpha\f1 \- character is alpha@@@\f3wctype(3C)\f1 .\" index@\f4iswupper\f1 \- character is uppercase@@@\f3wctype(3C)\f1 .\" index@\f4iswlower\f1 \- character is lowercase@@@\f3wctype(3C)\f1 .\" index@\f4iswdigit\f1 \- character is a digit@@@\f3wctype(3C)\f1 .\" index@\f4iswxdigit\f1 \- character is a hexadecimal digit@@@\f3wctype(3C)\f1 .\" index@\f4iswalnum\f1 \- character is alphanumeric@@@\f3wctype(3C)\f1 .\" index@\f4iswspace\f1 \- character is whitespace@@@\f3wctype(3C)\f1 .\" index@\f4iswpunct\f1 \- character is punctuation@@@\f3wctype(3C)\f1 .\" index@\f4iswprint\f1 \- character is a printing character@@@\f3wctype(3C)\f1 .\" index@\f4iswgraph\f1 \- character is a visible character@@@\f3wctype(3C)\f1 .\" index@\f4iswcntrl\f1 \- character is a control character@@@\f3wctype(3C)\f1 .\" index@\f4ISASCII\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3wctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3wctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3wctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3wctype(3C)\f1 .\" .\" toc@\f3wctype(3C)\f1:\0\0\f4iswalpha\f1, \f4iswupper\f1, \f4iswlower\f1, \f4iswdigit\f1, \f4iswxdigit\f1, \f4iswalnum\f1, \f4iswspace\f1,\n\f4iswpunct\f1, \f4iswprint\f1, \f4iswgraph\f1, \f4iswcntrl\f1@@@classify wide characters .\" toc@\f4iswalpha\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswupper\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswlower\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswxdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswalnum\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswspace\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswpunct\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswprint\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswgraph\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswcntrl\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" .\" links@wctype.3c iswctype.3c .\" links@wctype.3c iswalpha.3c .\" links@wctype.3c iswupper.3c .\" links@wctype.3c iswlower.3c .\" links@wctype.3c iswdigit.3c .\" links@wctype.3c iswxdigit.3c .\" links@wctype.3c iswalnum.3c .\" links@wctype.3c iswspace.3c .\" links@wctype.3c iswpunct.3c .\" links@wctype.3c iswprint.3c .\" links@wctype.3c iswgraph.3c .\" links@wctype.3c iswcntrl.3c .\" .\" fileset_database@wctype.3c PROGRAMING-MAN .\" $Header: wctype.3c,v 72.7 94/11/28 08:38:08 ssa Exp $ .TA w .TH wctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iswalpha(\|), iswupper(\|), iswlower(\|), iswdigit(\|), iswxdigit(\|), iswalnum(\|), iswspace(\|), iswpunct(\|), iswprint(\|), iswgraph(\|), iswcntrl(\|), wctype(\|), iswctype(\|) \- classify wide characters .SH SYNOPSIS .nf .C "#include " .PP .C "wctype_t wctype(const char *charclass);" .C "int iswctype(wint_t wc, wctype_t prop);" .C "int iswalnum(wint_t wc);" .C "int iswalpha(wint_t wc);" .C "int iswcntrl(wint_t wc);" .C "int iswdigit(wint_t wc);" .C "int iswgraph(wint_t wc);" .C "int iswlower(wint_t wc);" .C "int iswprint(wint_t wc);" .C "int iswpunct(wint_t wc);" .C "int iswspace(wint_t wc);" .C "int iswupper(wint_t wc);" .C "int iswxdigit(wint_t wc);" .fi .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character classification functions. They parallel the 8-bit character classification functions defined in .IR ctype(3C) . .SH DESCRIPTION These functions classify wide character values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP Each of the classification functions is a predicate that returns non-zero for true, zero for false. .PP .C wctype() is defined for valid character class names as defined in the current locale. .I charclass is a string identifying a generic character class for which codeset-specific type information is required. The following class names are defined in all locales: .CR alnum , .CR alpha , .CR blank , .CR cntrl , .CR digit , .CR graph , .CR lower , .CR print , .CR punct , .CR space , .CR upper , and .CR xdigit . User-defined class names may be specified if supported by the current locale as defined by .C setlocale() (see .IR setlocale (3C)). .C wctype() returns a value of type .C wctype_t that can be used in a subsequent call to .CR iswctype() , or .C (wctype_t)-1 if .I charclass is not valid in the current locale. .PP The classification functions return non-zero under the following circumstances, and zero otherwise: .RS .TP 20 .CI iswctype( wc , prop ) .I wc has the property defined by .IR prop . .TP .CI iswalpha( wc ) .I wc is a letter. .TP .CI iswupper( wc ) .I wc is an uppercase letter. .TP .CI iswlower( wc ) .I wc is a lowercase letter. .TP .CI iswdigit( wc ) .I wc is a decimal digit (in .SM ASCII\s0: characters [0-9]). .TP .CI iswxdigit( wc ) .I wc is a hexadecimal digit (in .SM ASCII\s0: characters [0-9], [A-F] or [a-f]). .TP .CI iswalnum( wc ) .I wc is an alphanumeric (letters or digits). .TP .CI iswspace( wc ) .I wc is a character that creates "white space" in displayed text (in .SM ASCII\s0: space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CI iswpunct( wc ) .I wc is a punctuation character (in .SM ASCII\s0: any printing character except the space character (040), digits, letters). .TP .CI iswprint( wc ) .I wc is a printing character. .TP .CI iswgraph( wc ) .I wc is a visible character (in .SM ASCII\s0: printing characters, excluding the space character (040)). .TP .CI iswcntrl( wc ) .I wc is a control character (in .SM ASCII\s0: character codes less than 040 and the delete character (0177)). .RE .PP If the argument to any of these functions is outside the domain of the function, the result is 0 (false). .PP Definitions for these functions and the types .CR wint_t , .CR wchar_t , and .C wctype_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wctype() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), multibyte(3C), setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR wctype() ": XPG4" .PP .CR iswalnum() ": XPG4" .PP .CR iswalpha() ": XPG4" .PP .CR iswcntrl() ": XPG4" .PP .CR iswctype() ": XPG4" .PP .CR iswdigit() ": XPG4" .PP .CR iswgraph() ": XPG4" .PP .CR iswlower() ": XPG4" .PP .CR iswprint() ": XPG4" .PP .CR iswpunct() ": XPG4" .PP .CR iswspace() ": XPG4" .PP .CR iswupper() ": XPG4" .PP .CR iswxdigit() ": XPG4" .\" .\" index@\f4wctype()\f1 \- classify characters according to type@@@\f3wctype(3C)\f1 .\" .\" index@\f4iswalpha\f1 \- character is alpha@@@\f3wctype(3C)\f1 .\" index@\f4iswupper\f1 \- character is uppercase@@@\f3wctype(3C)\f1 .\" index@\f4iswlower\f1 \- character is lowercase@@@\f3wctype(3C)\f1 .\" index@\f4iswdigit\f1 \- character is a digit@@@\f3wctype(3C)\f1 .\" index@\f4iswxdigit\f1 \- character is a hexadecimal digit@@@\f3wctype(3C)\f1 .\" index@\f4iswalnum\f1 \- character is alphanumeric@@@\f3wctype(3C)\f1 .\" index@\f4iswspace\f1 \- character is whitespace@@@\f3wctype(3C)\f1 .\" index@\f4iswpunct\f1 \- character is punctuation@@@\f3wctype(3C)\f1 .\" index@\f4iswprint\f1 \- character is a printing character@@@\f3wctype(3C)\f1 .\" index@\f4iswgraph\f1 \- character is a visible character@@@\f3wctype(3C)\f1 .\" index@\f4iswcntrl\f1 \- character is a control character@@@\f3wctype(3C)\f1 .\" index@\f4ISASCII\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3wctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3wctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3wctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3wctype(3C)\f1 .\" .\" toc@\f3wctype(3C)\f1:\0\0\f4iswalpha\f1, \f4iswupper\f1, \f4iswlower\f1, \f4iswdigit\f1, \f4iswxdigit\f1, \f4iswalnum\f1, \f4iswspace\f1,\n\f4iswpunct\f1, \f4iswprint\f1, \f4iswgraph\f1, \f4iswcntrl\f1@@@classify wide characters .\" toc@\f4iswalpha\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswupper\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswlower\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswxdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswalnum\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswspace\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswpunct\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswprint\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswgraph\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswcntrl\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" .\" links@wctype.3c iswctype.3c .\" links@wctype.3c iswalpha.3c .\" links@wctype.3c iswupper.3c .\" links@wctype.3c iswlower.3c .\" links@wctype.3c iswdigit.3c .\" links@wctype.3c iswxdigit.3c .\" links@wctype.3c iswalnum.3c .\" links@wctype.3c iswspace.3c .\" links@wctype.3c iswpunct.3c .\" links@wctype.3c iswprint.3c .\" links@wctype.3c iswgraph.3c .\" links@wctype.3c iswcntrl.3c .\" .\" fileset_database@wctype.3c PROGRAMING-MAN .\" $Header: wctype.3c,v 72.7 94/11/28 08:38:08 ssa Exp $ .TA w .TH wctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iswalpha(\|), iswupper(\|), iswlower(\|), iswdigit(\|), iswxdigit(\|), iswalnum(\|), iswspace(\|), iswpunct(\|), iswprint(\|), iswgraph(\|), iswcntrl(\|), wctype(\|), iswctype(\|) \- classify wide characters .SH SYNOPSIS .nf .C "#include " .PP .C "wctype_t wctype(const char *charclass);" .C "int iswctype(wint_t wc, wctype_t prop);" .C "int iswalnum(wint_t wc);" .C "int iswalpha(wint_t wc);" .C "int iswcntrl(wint_t wc);" .C "int iswdigit(wint_t wc);" .C "int iswgraph(wint_t wc);" .C "int iswlower(wint_t wc);" .C "int iswprint(wint_t wc);" .C "int iswpunct(wint_t wc);" .C "int iswspace(wint_t wc);" .C "int iswupper(wint_t wc);" .C "int iswxdigit(wint_t wc);" .fi .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character classification functions. They parallel the 8-bit character classification functions defined in .IR ctype(3C) . .SH DESCRIPTION These functions classify wide character values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP Each of the classification functions is a predicate that returns non-zero for true, zero for false. .PP .C wctype() is defined for valid character class names as defined in the current locale. .I charclass is a string identifying a generic character class for which codeset-specific type information is required. The following class names are defined in all locales: .CR alnum , .CR alpha , .CR blank , .CR cntrl , .CR digit , .CR graph , .CR lower , .CR print , .CR punct , .CR space , .CR upper , and .CR xdigit . User-defined class names may be specified if supported by the current locale as defined by .C setlocale() (see .IR setlocale (3C)). .C wctype() returns a value of type .C wctype_t that can be used in a subsequent call to .CR iswctype() , or .C (wctype_t)-1 if .I charclass is not valid in the current locale. .PP The classification functions return non-zero under the following circumstances, and zero otherwise: .RS .TP 20 .CI iswctype( wc , prop ) .I wc has the property defined by .IR prop . .TP .CI iswalpha( wc ) .I wc is a letter. .TP .CI iswupper( wc ) .I wc is an uppercase letter. .TP .CI iswlower( wc ) .I wc is a lowercase letter. .TP .CI iswdigit( wc ) .I wc is a decimal digit (in .SM ASCII\s0: characters [0-9]). .TP .CI iswxdigit( wc ) .I wc is a hexadecimal digit (in .SM ASCII\s0: characters [0-9], [A-F] or [a-f]). .TP .CI iswalnum( wc ) .I wc is an alphanumeric (letters or digits). .TP .CI iswspace( wc ) .I wc is a character that creates "white space" in displayed text (in .SM ASCII\s0: space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CI iswpunct( wc ) .I wc is a punctuation character (in .SM ASCII\s0: any printing character except the space character (040), digits, letters). .TP .CI iswprint( wc ) .I wc is a printing character. .TP .CI iswgraph( wc ) .I wc is a visible character (in .SM ASCII\s0: printing characters, excluding the space character (040)). .TP .CI iswcntrl( wc ) .I wc is a control character (in .SM ASCII\s0: character codes less than 040 and the delete character (0177)). .RE .PP If the argument to any of these functions is outside the domain of the function, the result is 0 (false). .PP Definitions for these functions and the types .CR wint_t , .CR wchar_t , and .C wctype_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wctype() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), multibyte(3C), setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR wctype() ": XPG4" .PP .CR iswalnum() ": XPG4" .PP .CR iswalpha() ": XPG4" .PP .CR iswcntrl() ": XPG4" .PP .CR iswctype() ": XPG4" .PP .CR iswdigit() ": XPG4" .PP .CR iswgraph() ": XPG4" .PP .CR iswlower() ": XPG4" .PP .CR iswprint() ": XPG4" .PP .CR iswpunct() ": XPG4" .PP .CR iswspace() ": XPG4" .PP .CR iswupper() ": XPG4" .PP .CR iswxdigit() ": XPG4" .\" .\" index@\f4wctype()\f1 \- classify characters according to type@@@\f3wctype(3C)\f1 .\" .\" index@\f4iswalpha\f1 \- character is alpha@@@\f3wctype(3C)\f1 .\" index@\f4iswupper\f1 \- character is uppercase@@@\f3wctype(3C)\f1 .\" index@\f4iswlower\f1 \- character is lowercase@@@\f3wctype(3C)\f1 .\" index@\f4iswdigit\f1 \- character is a digit@@@\f3wctype(3C)\f1 .\" index@\f4iswxdigit\f1 \- character is a hexadecimal digit@@@\f3wctype(3C)\f1 .\" index@\f4iswalnum\f1 \- character is alphanumeric@@@\f3wctype(3C)\f1 .\" index@\f4iswspace\f1 \- character is whitespace@@@\f3wctype(3C)\f1 .\" index@\f4iswpunct\f1 \- character is punctuation@@@\f3wctype(3C)\f1 .\" index@\f4iswprint\f1 \- character is a printing character@@@\f3wctype(3C)\f1 .\" index@\f4iswgraph\f1 \- character is a visible character@@@\f3wctype(3C)\f1 .\" index@\f4iswcntrl\f1 \- character is a control character@@@\f3wctype(3C)\f1 .\" index@\f4ISASCII\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3wctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3wctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3wctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3wctype(3C)\f1 .\" .\" toc@\f3wctype(3C)\f1:\0\0\f4iswalpha\f1, \f4iswupper\f1, \f4iswlower\f1, \f4iswdigit\f1, \f4iswxdigit\f1, \f4iswalnum\f1, \f4iswspace\f1,\n\f4iswpunct\f1, \f4iswprint\f1, \f4iswgraph\f1, \f4iswcntrl\f1@@@classify wide characters .\" toc@\f4iswalpha\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswupper\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswlower\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswxdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswalnum\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswspace\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswpunct\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswprint\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswgraph\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswcntrl\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" .\" links@wctype.3c iswctype.3c .\" links@wctype.3c iswalpha.3c .\" links@wctype.3c iswupper.3c .\" links@wctype.3c iswlower.3c .\" links@wctype.3c iswdigit.3c .\" links@wctype.3c iswxdigit.3c .\" links@wctype.3c iswalnum.3c .\" links@wctype.3c iswspace.3c .\" links@wctype.3c iswpunct.3c .\" links@wctype.3c iswprint.3c .\" links@wctype.3c iswgraph.3c .\" links@wctype.3c iswcntrl.3c .\" .\" fileset_database@wctype.3c PROGRAMING-MAN .\" $Header: wctype.3c,v 72.7 94/11/28 08:38:08 ssa Exp $ .TA w .TH wctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iswalpha(\|), iswupper(\|), iswlower(\|), iswdigit(\|), iswxdigit(\|), iswalnum(\|), iswspace(\|), iswpunct(\|), iswprint(\|), iswgraph(\|), iswcntrl(\|), wctype(\|), iswctype(\|) \- classify wide characters .SH SYNOPSIS .nf .C "#include " .PP .C "wctype_t wctype(const char *charclass);" .C "int iswctype(wint_t wc, wctype_t prop);" .C "int iswalnum(wint_t wc);" .C "int iswalpha(wint_t wc);" .C "int iswcntrl(wint_t wc);" .C "int iswdigit(wint_t wc);" .C "int iswgraph(wint_t wc);" .C "int iswlower(wint_t wc);" .C "int iswprint(wint_t wc);" .C "int iswpunct(wint_t wc);" .C "int iswspace(wint_t wc);" .C "int iswupper(wint_t wc);" .C "int iswxdigit(wint_t wc);" .fi .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character classification functions. They parallel the 8-bit character classification functions defined in .IR ctype(3C) . .SH DESCRIPTION These functions classify wide character values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP Each of the classification functions is a predicate that returns non-zero for true, zero for false. .PP .C wctype() is defined for valid character class names as defined in the current locale. .I charclass is a string identifying a generic character class for which codeset-specific type information is required. The following class names are defined in all locales: .CR alnum , .CR alpha , .CR blank , .CR cntrl , .CR digit , .CR graph , .CR lower , .CR print , .CR punct , .CR space , .CR upper , and .CR xdigit . User-defined class names may be specified if supported by the current locale as defined by .C setlocale() (see .IR setlocale (3C)). .C wctype() returns a value of type .C wctype_t that can be used in a subsequent call to .CR iswctype() , or .C (wctype_t)-1 if .I charclass is not valid in the current locale. .PP The classification functions return non-zero under the following circumstances, and zero otherwise: .RS .TP 20 .CI iswctype( wc , prop ) .I wc has the property defined by .IR prop . .TP .CI iswalpha( wc ) .I wc is a letter. .TP .CI iswupper( wc ) .I wc is an uppercase letter. .TP .CI iswlower( wc ) .I wc is a lowercase letter. .TP .CI iswdigit( wc ) .I wc is a decimal digit (in .SM ASCII\s0: characters [0-9]). .TP .CI iswxdigit( wc ) .I wc is a hexadecimal digit (in .SM ASCII\s0: characters [0-9], [A-F] or [a-f]). .TP .CI iswalnum( wc ) .I wc is an alphanumeric (letters or digits). .TP .CI iswspace( wc ) .I wc is a character that creates "white space" in displayed text (in .SM ASCII\s0: space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CI iswpunct( wc ) .I wc is a punctuation character (in .SM ASCII\s0: any printing character except the space character (040), digits, letters). .TP .CI iswprint( wc ) .I wc is a printing character. .TP .CI iswgraph( wc ) .I wc is a visible character (in .SM ASCII\s0: printing characters, excluding the space character (040)). .TP .CI iswcntrl( wc ) .I wc is a control character (in .SM ASCII\s0: character codes less than 040 and the delete character (0177)). .RE .PP If the argument to any of these functions is outside the domain of the function, the result is 0 (false). .PP Definitions for these functions and the types .CR wint_t , .CR wchar_t , and .C wctype_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wctype() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), multibyte(3C), setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR wctype() ": XPG4" .PP .CR iswalnum() ": XPG4" .PP .CR iswalpha() ": XPG4" .PP .CR iswcntrl() ": XPG4" .PP .CR iswctype() ": XPG4" .PP .CR iswdigit() ": XPG4" .PP .CR iswgraph() ": XPG4" .PP .CR iswlower() ": XPG4" .PP .CR iswprint() ": XPG4" .PP .CR iswpunct() ": XPG4" .PP .CR iswspace() ": XPG4" .PP .CR iswupper() ": XPG4" .PP .CR iswxdigit() ": XPG4" .\" .\" index@\f4wctype()\f1 \- classify characters according to type@@@\f3wctype(3C)\f1 .\" .\" index@\f4iswalpha\f1 \- character is alpha@@@\f3wctype(3C)\f1 .\" index@\f4iswupper\f1 \- character is uppercase@@@\f3wctype(3C)\f1 .\" index@\f4iswlower\f1 \- character is lowercase@@@\f3wctype(3C)\f1 .\" index@\f4iswdigit\f1 \- character is a digit@@@\f3wctype(3C)\f1 .\" index@\f4iswxdigit\f1 \- character is a hexadecimal digit@@@\f3wctype(3C)\f1 .\" index@\f4iswalnum\f1 \- character is alphanumeric@@@\f3wctype(3C)\f1 .\" index@\f4iswspace\f1 \- character is whitespace@@@\f3wctype(3C)\f1 .\" index@\f4iswpunct\f1 \- character is punctuation@@@\f3wctype(3C)\f1 .\" index@\f4iswprint\f1 \- character is a printing character@@@\f3wctype(3C)\f1 .\" index@\f4iswgraph\f1 \- character is a visible character@@@\f3wctype(3C)\f1 .\" index@\f4iswcntrl\f1 \- character is a control character@@@\f3wctype(3C)\f1 .\" index@\f4ISASCII\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3wctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3wctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3wctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3wctype(3C)\f1 .\" .\" toc@\f3wctype(3C)\f1:\0\0\f4iswalpha\f1, \f4iswupper\f1, \f4iswlower\f1, \f4iswdigit\f1, \f4iswxdigit\f1, \f4iswalnum\f1, \f4iswspace\f1,\n\f4iswpunct\f1, \f4iswprint\f1, \f4iswgraph\f1, \f4iswcntrl\f1@@@classify wide characters .\" toc@\f4iswalpha\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswupper\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswlower\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswxdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswalnum\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswspace\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswpunct\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswprint\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswgraph\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswcntrl\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" .\" links@wctype.3c iswctype.3c .\" links@wctype.3c iswalpha.3c .\" links@wctype.3c iswupper.3c .\" links@wctype.3c iswlower.3c .\" links@wctype.3c iswdigit.3c .\" links@wctype.3c iswxdigit.3c .\" links@wctype.3c iswalnum.3c .\" links@wctype.3c iswspace.3c .\" links@wctype.3c iswpunct.3c .\" links@wctype.3c iswprint.3c .\" links@wctype.3c iswgraph.3c .\" links@wctype.3c iswcntrl.3c .\" .\" fileset_database@wctype.3c PROGRAMING-MAN .\" $Header: wctype.3c,v 72.7 94/11/28 08:38:08 ssa Exp $ .TA w .TH wctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iswalpha(\|), iswupper(\|), iswlower(\|), iswdigit(\|), iswxdigit(\|), iswalnum(\|), iswspace(\|), iswpunct(\|), iswprint(\|), iswgraph(\|), iswcntrl(\|), wctype(\|), iswctype(\|) \- classify wide characters .SH SYNOPSIS .nf .C "#include " .PP .C "wctype_t wctype(const char *charclass);" .C "int iswctype(wint_t wc, wctype_t prop);" .C "int iswalnum(wint_t wc);" .C "int iswalpha(wint_t wc);" .C "int iswcntrl(wint_t wc);" .C "int iswdigit(wint_t wc);" .C "int iswgraph(wint_t wc);" .C "int iswlower(wint_t wc);" .C "int iswprint(wint_t wc);" .C "int iswpunct(wint_t wc);" .C "int iswspace(wint_t wc);" .C "int iswupper(wint_t wc);" .C "int iswxdigit(wint_t wc);" .fi .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character classification functions. They parallel the 8-bit character classification functions defined in .IR ctype(3C) . .SH DESCRIPTION These functions classify wide character values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP Each of the classification functions is a predicate that returns non-zero for true, zero for false. .PP .C wctype() is defined for valid character class names as defined in the current locale. .I charclass is a string identifying a generic character class for which codeset-specific type information is required. The following class names are defined in all locales: .CR alnum , .CR alpha , .CR blank , .CR cntrl , .CR digit , .CR graph , .CR lower , .CR print , .CR punct , .CR space , .CR upper , and .CR xdigit . User-defined class names may be specified if supported by the current locale as defined by .C setlocale() (see .IR setlocale (3C)). .C wctype() returns a value of type .C wctype_t that can be used in a subsequent call to .CR iswctype() , or .C (wctype_t)-1 if .I charclass is not valid in the current locale. .PP The classification functions return non-zero under the following circumstances, and zero otherwise: .RS .TP 20 .CI iswctype( wc , prop ) .I wc has the property defined by .IR prop . .TP .CI iswalpha( wc ) .I wc is a letter. .TP .CI iswupper( wc ) .I wc is an uppercase letter. .TP .CI iswlower( wc ) .I wc is a lowercase letter. .TP .CI iswdigit( wc ) .I wc is a decimal digit (in .SM ASCII\s0: characters [0-9]). .TP .CI iswxdigit( wc ) .I wc is a hexadecimal digit (in .SM ASCII\s0: characters [0-9], [A-F] or [a-f]). .TP .CI iswalnum( wc ) .I wc is an alphanumeric (letters or digits). .TP .CI iswspace( wc ) .I wc is a character that creates "white space" in displayed text (in .SM ASCII\s0: space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CI iswpunct( wc ) .I wc is a punctuation character (in .SM ASCII\s0: any printing character except the space character (040), digits, letters). .TP .CI iswprint( wc ) .I wc is a printing character. .TP .CI iswgraph( wc ) .I wc is a visible character (in .SM ASCII\s0: printing characters, excluding the space character (040)). .TP .CI iswcntrl( wc ) .I wc is a control character (in .SM ASCII\s0: character codes less than 040 and the delete character (0177)). .RE .PP If the argument to any of these functions is outside the domain of the function, the result is 0 (false). .PP Definitions for these functions and the types .CR wint_t , .CR wchar_t , and .C wctype_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wctype() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), multibyte(3C), setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR wctype() ": XPG4" .PP .CR iswalnum() ": XPG4" .PP .CR iswalpha() ": XPG4" .PP .CR iswcntrl() ": XPG4" .PP .CR iswctype() ": XPG4" .PP .CR iswdigit() ": XPG4" .PP .CR iswgraph() ": XPG4" .PP .CR iswlower() ": XPG4" .PP .CR iswprint() ": XPG4" .PP .CR iswpunct() ": XPG4" .PP .CR iswspace() ": XPG4" .PP .CR iswupper() ": XPG4" .PP .CR iswxdigit() ": XPG4" .\" .\" index@\f4wctype()\f1 \- classify characters according to type@@@\f3wctype(3C)\f1 .\" .\" index@\f4iswalpha\f1 \- character is alpha@@@\f3wctype(3C)\f1 .\" index@\f4iswupper\f1 \- character is uppercase@@@\f3wctype(3C)\f1 .\" index@\f4iswlower\f1 \- character is lowercase@@@\f3wctype(3C)\f1 .\" index@\f4iswdigit\f1 \- character is a digit@@@\f3wctype(3C)\f1 .\" index@\f4iswxdigit\f1 \- character is a hexadecimal digit@@@\f3wctype(3C)\f1 .\" index@\f4iswalnum\f1 \- character is alphanumeric@@@\f3wctype(3C)\f1 .\" index@\f4iswspace\f1 \- character is whitespace@@@\f3wctype(3C)\f1 .\" index@\f4iswpunct\f1 \- character is punctuation@@@\f3wctype(3C)\f1 .\" index@\f4iswprint\f1 \- character is a printing character@@@\f3wctype(3C)\f1 .\" index@\f4iswgraph\f1 \- character is a visible character@@@\f3wctype(3C)\f1 .\" index@\f4iswcntrl\f1 \- character is a control character@@@\f3wctype(3C)\f1 .\" index@\f4ISASCII\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3wctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3wctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3wctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3wctype(3C)\f1 .\" .\" toc@\f3wctype(3C)\f1:\0\0\f4iswalpha\f1, \f4iswupper\f1, \f4iswlower\f1, \f4iswdigit\f1, \f4iswxdigit\f1, \f4iswalnum\f1, \f4iswspace\f1,\n\f4iswpunct\f1, \f4iswprint\f1, \f4iswgraph\f1, \f4iswcntrl\f1@@@classify wide characters .\" toc@\f4iswalpha\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswupper\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswlower\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswxdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswalnum\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswspace\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswpunct\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswprint\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswgraph\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswcntrl\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" .\" links@wctype.3c iswctype.3c .\" links@wctype.3c iswalpha.3c .\" links@wctype.3c iswupper.3c .\" links@wctype.3c iswlower.3c .\" links@wctype.3c iswdigit.3c .\" links@wctype.3c iswxdigit.3c .\" links@wctype.3c iswalnum.3c .\" links@wctype.3c iswspace.3c .\" links@wctype.3c iswpunct.3c .\" links@wctype.3c iswprint.3c .\" links@wctype.3c iswgraph.3c .\" links@wctype.3c iswcntrl.3c .\" .\" fileset_database@wctype.3c PROGRAMING-MAN .\" $Header: wctype.3c,v 72.7 94/11/28 08:38:08 ssa Exp $ .TA w .TH wctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iswalpha(\|), iswupper(\|), iswlower(\|), iswdigit(\|), iswxdigit(\|), iswalnum(\|), iswspace(\|), iswpunct(\|), iswprint(\|), iswgraph(\|), iswcntrl(\|), wctype(\|), iswctype(\|) \- classify wide characters .SH SYNOPSIS .nf .C "#include " .PP .C "wctype_t wctype(const char *charclass);" .C "int iswctype(wint_t wc, wctype_t prop);" .C "int iswalnum(wint_t wc);" .C "int iswalpha(wint_t wc);" .C "int iswcntrl(wint_t wc);" .C "int iswdigit(wint_t wc);" .C "int iswgraph(wint_t wc);" .C "int iswlower(wint_t wc);" .C "int iswprint(wint_t wc);" .C "int iswpunct(wint_t wc);" .C "int iswspace(wint_t wc);" .C "int iswupper(wint_t wc);" .C "int iswxdigit(wint_t wc);" .fi .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character classification functions. They parallel the 8-bit character classification functions defined in .IR ctype(3C) . .SH DESCRIPTION These functions classify wide character values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP Each of the classification functions is a predicate that returns non-zero for true, zero for false. .PP .C wctype() is defined for valid character class names as defined in the current locale. .I charclass is a string identifying a generic character class for which codeset-specific type information is required. The following class names are defined in all locales: .CR alnum , .CR alpha , .CR blank , .CR cntrl , .CR digit , .CR graph , .CR lower , .CR print , .CR punct , .CR space , .CR upper , and .CR xdigit . User-defined class names may be specified if supported by the current locale as defined by .C setlocale() (see .IR setlocale (3C)). .C wctype() returns a value of type .C wctype_t that can be used in a subsequent call to .CR iswctype() , or .C (wctype_t)-1 if .I charclass is not valid in the current locale. .PP The classification functions return non-zero under the following circumstances, and zero otherwise: .RS .TP 20 .CI iswctype( wc , prop ) .I wc has the property defined by .IR prop . .TP .CI iswalpha( wc ) .I wc is a letter. .TP .CI iswupper( wc ) .I wc is an uppercase letter. .TP .CI iswlower( wc ) .I wc is a lowercase letter. .TP .CI iswdigit( wc ) .I wc is a decimal digit (in .SM ASCII\s0: characters [0-9]). .TP .CI iswxdigit( wc ) .I wc is a hexadecimal digit (in .SM ASCII\s0: characters [0-9], [A-F] or [a-f]). .TP .CI iswalnum( wc ) .I wc is an alphanumeric (letters or digits). .TP .CI iswspace( wc ) .I wc is a character that creates "white space" in displayed text (in .SM ASCII\s0: space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CI iswpunct( wc ) .I wc is a punctuation character (in .SM ASCII\s0: any printing character except the space character (040), digits, letters). .TP .CI iswprint( wc ) .I wc is a printing character. .TP .CI iswgraph( wc ) .I wc is a visible character (in .SM ASCII\s0: printing characters, excluding the space character (040)). .TP .CI iswcntrl( wc ) .I wc is a control character (in .SM ASCII\s0: character codes less than 040 and the delete character (0177)). .RE .PP If the argument to any of these functions is outside the domain of the function, the result is 0 (false). .PP Definitions for these functions and the types .CR wint_t , .CR wchar_t , and .C wctype_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wctype() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), multibyte(3C), setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR wctype() ": XPG4" .PP .CR iswalnum() ": XPG4" .PP .CR iswalpha() ": XPG4" .PP .CR iswcntrl() ": XPG4" .PP .CR iswctype() ": XPG4" .PP .CR iswdigit() ": XPG4" .PP .CR iswgraph() ": XPG4" .PP .CR iswlower() ": XPG4" .PP .CR iswprint() ": XPG4" .PP .CR iswpunct() ": XPG4" .PP .CR iswspace() ": XPG4" .PP .CR iswupper() ": XPG4" .PP .CR iswxdigit() ": XPG4" .\" .\" index@\f4wctype()\f1 \- classify characters according to type@@@\f3wctype(3C)\f1 .\" .\" index@\f4iswalpha\f1 \- character is alpha@@@\f3wctype(3C)\f1 .\" index@\f4iswupper\f1 \- character is uppercase@@@\f3wctype(3C)\f1 .\" index@\f4iswlower\f1 \- character is lowercase@@@\f3wctype(3C)\f1 .\" index@\f4iswdigit\f1 \- character is a digit@@@\f3wctype(3C)\f1 .\" index@\f4iswxdigit\f1 \- character is a hexadecimal digit@@@\f3wctype(3C)\f1 .\" index@\f4iswalnum\f1 \- character is alphanumeric@@@\f3wctype(3C)\f1 .\" index@\f4iswspace\f1 \- character is whitespace@@@\f3wctype(3C)\f1 .\" index@\f4iswpunct\f1 \- character is punctuation@@@\f3wctype(3C)\f1 .\" index@\f4iswprint\f1 \- character is a printing character@@@\f3wctype(3C)\f1 .\" index@\f4iswgraph\f1 \- character is a visible character@@@\f3wctype(3C)\f1 .\" index@\f4iswcntrl\f1 \- character is a control character@@@\f3wctype(3C)\f1 .\" index@\f4ISASCII\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3wctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3wctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3wctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3wctype(3C)\f1 .\" .\" toc@\f3wctype(3C)\f1:\0\0\f4iswalpha\f1, \f4iswupper\f1, \f4iswlower\f1, \f4iswdigit\f1, \f4iswxdigit\f1, \f4iswalnum\f1, \f4iswspace\f1,\n\f4iswpunct\f1, \f4iswprint\f1, \f4iswgraph\f1, \f4iswcntrl\f1@@@classify wide characters .\" toc@\f4iswalpha\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswupper\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswlower\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswxdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswalnum\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswspace\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswpunct\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswprint\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswgraph\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswcntrl\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" .\" links@wctype.3c iswctype.3c .\" links@wctype.3c iswalpha.3c .\" links@wctype.3c iswupper.3c .\" links@wctype.3c iswlower.3c .\" links@wctype.3c iswdigit.3c .\" links@wctype.3c iswxdigit.3c .\" links@wctype.3c iswalnum.3c .\" links@wctype.3c iswspace.3c .\" links@wctype.3c iswpunct.3c .\" links@wctype.3c iswprint.3c .\" links@wctype.3c iswgraph.3c .\" links@wctype.3c iswcntrl.3c .\" .\" fileset_database@wctype.3c PROGRAMING-MAN .\" $Header: ctype.3c,v 72.6 94/11/28 08:25:33 ssa Exp $ .TA c .TH ctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME isalpha(\|), isupper(\|), islower(\|), isdigit(\|), isxdigit(\|), isalnum(\|), isspace(\|), ispunct(\|), isprint(\|), isgraph(\|), iscntrl(\|), isascii(\|) \- classify characters .SH SYNOPSIS .C "#include " .PP .C "int isalnum(int c);" .br .C "int isalpha(int c);" .br .C "int iscntrl(int c);" .br .C "int isdigit(int c);" .br .C "int isgraph(int c);" .br .C "int islower(int c);" .br .C "int isprint(int c);" .br .C "int ispunct(int c);" .br .C "int isspace(int c);" .br .C "int isupper(int c);" .br .C "int isxdigit(int c);" .br .C "int isascii(int c);" .SH DESCRIPTION These functions classify character-coded integer values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). Each function is a predicate returning non-zero for true, zero for false. .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP .C isascii() is defined on all integer values; the other functions are defined for the range .C -1 .SM (EOF) through .CR 255 . .PP The functions return non-zero under the following circumstances; zero otherwise: .RS .TP 18 .CR isalpha( c ) .I c is a letter. .TP .CR isupper( c ) .I c is an uppercase letter. .TP .CR islower( c ) .I c is a lowercase letter. .TP .CR isdigit( c ) .I c is a decimal digit (in .SM ASCII\c : characters [0-9]). .TP .CR isxdigit( c ) .I c is a hexadecimal digit (in .SM ASCII\c : characters [0-9], [A-F] or [a-f]). .TP .CR isalnum( c ) .I c is an alphanumeric (letters or digits). .TP .CR isspace( c ) .I c is a character that creates ``white space'' in displayed text (in .SM ASCII\c : space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CR ispunct( c ) .I c is a punctuation character (in .SM ASCII\c : any printing character except the space character (040), digits, letters). .TP .CR isprint( c ) .I c is a printing character. .TP .CR isgraph( c ) .I c is a visible character (in .SM ASCII\c : printing characters, excluding the space character (040)). .TP .CR iscntrl( c ) .I c is a control character (in .SM ASCII\c : character codes less than 040 and the delete character (0177)). .TP .CR isascii( c ) .I c is any .SM ASCII character code between 0 and 0177, inclusive. .RE .PP If the argument to any of these functions is outside the domain of the function, the result is undefined. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS These functions are supplied both as library functions and as macros defined in the .RC < ctype.h > header. Normally, the macro versions are used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parenthesis or take its address. The following example uses the library functions for .CR isalpha() , .CR isdigit() , and .CR isspace() : .nf .IP .C "#include " .C "#undef isalpha" \h'.5i'... .C "main() .C "{ .C " int (*ctype_func)();" \h'.8i'... .C " if ( isalpha(c) )" \h'.8i'... .C " if ( (isdigit)(c) )" \h'.8i'... .C " ctype_func = isspace;" \h'.8i'... .C } .fi .SH AUTHOR .CR ctype() was developed by IBM, OSF, and HP. .SH SEE ALSO setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR isalnum() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isalpha() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR iscntrl() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isgraph() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR islower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isprint() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ispunct() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isspace() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR isxdigit() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4isalpha()\f1 \- character is alpha@@@\f3ctype(3C)\f1 .\" index@\f4isupper()\f1 \- character is uppercase@@@\f3ctype(3C)\f1 .\" index@\f4islower()\f1 \- character is lowercase@@@\f3ctype(3C)\f1 .\" index@\f4isdigit()\f1 \- character is a digit@@@\f3ctype(3C)\f1 .\" index@\f4isxdigit()\f1 \- character is a hexadecimal digit@@@\f3ctype(3C)\f1 .\" index@\f4isalnum()\f1 \- character is alphanumeric@@@\f3ctype(3C)\f1 .\" index@\f4isspace()\f1 \- character is whitespace@@@\f3ctype(3C)\f1 .\" index@\f4ispunct()\f1 \- character is punctuation@@@\f3ctype(3C)\f1 .\" index@\f4isprint()\f1 \- character is a printing character@@@\f3ctype(3C)\f1 .\" index@\f4isgraph()\f1 \- character is a visible character@@@\f3ctype(3C)\f1 .\" index@\f4iscntrl()\f1 \- character is a control character@@@\f3ctype(3C)\f1 .\" index@\f4isascii()\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3ctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3ctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3ctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3ctype(3C)\f1 .\" .\" toc@\f3ctype(3C)\f1:\0\0\f4isalpha()\f1, \f4isupper()\f1, \f4islower()\f1, \f4isdigit()\f1, \f4isxdigit()\f1, \f4isalnum()\f1, \f4isspace()\f1,\n\f4ispunct()\f1, \f4isprint()\f1, \f4isgraph()\f1, \f4iscntrl()\f1, \f4isascii()\f1@@@classify characters .\" toc@\f4isalpha()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isupper()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4islower()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isxdigit()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isalnum()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isspace()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4ispunct()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isprint()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isgraph()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4iscntrl()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" toc@\f4isascii()\f1:\0\0classify characters@@@see \f3ctype(3C)\f1 .\" .\" links@ctype.3c isalpha.3c .\" links@ctype.3c isupper.3c .\" links@ctype.3c islower.3c .\" links@ctype.3c isdigit.3c .\" links@ctype.3c isxdigit.3c .\" links@ctype.3c isalnum.3c .\" links@ctype.3c isspace.3c .\" links@ctype.3c ispunct.3c .\" links@ctype.3c isprint.3c .\" links@ctype.3c isgraph.3c .\" links@ctype.3c iscntrl.3c .\" links@ctype.3c isascii.3c .\" .\" fileset_database@ctype.3c PROGRAMING-MAN .\" $Header: j0.3m,v 78.1 96/02/13 12:26:03 ssa Exp $ .TA j .TH j0 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME j0(\|), j1(\|), jn(\|) \- Bessel functions of the first kind .SH SYNOPSIS .C "#include " .PP .C "double j0(double x);" .PP .C "double j1(double x);" .PP .C "double jn(int n, double x);" .SH DESCRIPTION .CR j0() and .CR j1() return Bessel functions of .I x of the first kind of orders 0 and 1 respectively. .CR jn() returns the Bessel function of .I x of the first kind of order .IR n . .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is NaN, .CR j0() , .CR j1() , and .CR jn() return NaN. .PP If the correct result after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR j0() , .CR j1() , and .CR jn() return zero. .SH ERRORS No errors are defined. .SH SEE ALSO y0(3M), isnan(3M), values(5). .PP M. Abramowitz and I. Stegun, .I "Handbook of Mathematical Functions" (New York: Dover Publications, 1972). .SH STANDARDS CONFORMANCE .CR j0() ": SVID3, XPG4.2" .PP .CR j1() ": SVID3, XPG4.2" .PP .CR jn() ": SVID3, XPG4.2" .\" .\" index@\f4j0()\f1, \f4j1()\f1, \f4jn()\fP \- Bessel functions of the first kind@@@\f3j0(3M)\f1 .\" index@math: Bessel functions of the first kind@@@\f3j0(3M)\f1 .\" index@Bessel functions of the first kind@@@\f3j0(3M)\f1 .\" index@\f4j1()\f1 \- Bessel function@@@\f3j0(3M)\f1 .\" index@\f4jn()\fP \- Bessel function@@@\f3j0(3M)\f1 .\" .\" toc@\f3j0(3M)\f1:\0\0\f4j0()\f1, \f4j1()\f1, \f4jn()\fP@@@Bessel functions of the first kind .\" toc@\f4j1()\f1:\0\0Bessel function@@@see \f3j0(3M)\f1 .\" toc@\f4jn()\fP:\0\0Bessel function@@@see \f3j0(3M)\f1 .\" .\" links@j0.3m j1.3m .\" links@j0.3m jn.3m .\" .\" fileset_database@j0.3m PROGRAMING-MAN .\" $Header: j0.3m,v 78.1 96/02/13 12:26:03 ssa Exp $ .TA j .TH j0 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME j0(\|), j1(\|), jn(\|) \- Bessel functions of the first kind .SH SYNOPSIS .C "#include " .PP .C "double j0(double x);" .PP .C "double j1(double x);" .PP .C "double jn(int n, double x);" .SH DESCRIPTION .CR j0() and .CR j1() return Bessel functions of .I x of the first kind of orders 0 and 1 respectively. .CR jn() returns the Bessel function of .I x of the first kind of order .IR n . .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is NaN, .CR j0() , .CR j1() , and .CR jn() return NaN. .PP If the correct result after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR j0() , .CR j1() , and .CR jn() return zero. .SH ERRORS No errors are defined. .SH SEE ALSO y0(3M), isnan(3M), values(5). .PP M. Abramowitz and I. Stegun, .I "Handbook of Mathematical Functions" (New York: Dover Publications, 1972). .SH STANDARDS CONFORMANCE .CR j0() ": SVID3, XPG4.2" .PP .CR j1() ": SVID3, XPG4.2" .PP .CR jn() ": SVID3, XPG4.2" .\" .\" index@\f4j0()\f1, \f4j1()\f1, \f4jn()\fP \- Bessel functions of the first kind@@@\f3j0(3M)\f1 .\" index@math: Bessel functions of the first kind@@@\f3j0(3M)\f1 .\" index@Bessel functions of the first kind@@@\f3j0(3M)\f1 .\" index@\f4j1()\f1 \- Bessel function@@@\f3j0(3M)\f1 .\" index@\f4jn()\fP \- Bessel function@@@\f3j0(3M)\f1 .\" .\" toc@\f3j0(3M)\f1:\0\0\f4j0()\f1, \f4j1()\f1, \f4jn()\fP@@@Bessel functions of the first kind .\" toc@\f4j1()\f1:\0\0Bessel function@@@see \f3j0(3M)\f1 .\" toc@\f4jn()\fP:\0\0Bessel function@@@see \f3j0(3M)\f1 .\" .\" links@j0.3m j1.3m .\" links@j0.3m jn.3m .\" .\" fileset_database@j0.3m PROGRAMING-MAN .\" $Header: j0.3m,v 78.1 96/02/13 12:26:03 ssa Exp $ .TA j .TH j0 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME j0(\|), j1(\|), jn(\|) \- Bessel functions of the first kind .SH SYNOPSIS .C "#include " .PP .C "double j0(double x);" .PP .C "double j1(double x);" .PP .C "double jn(int n, double x);" .SH DESCRIPTION .CR j0() and .CR j1() return Bessel functions of .I x of the first kind of orders 0 and 1 respectively. .CR jn() returns the Bessel function of .I x of the first kind of order .IR n . .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is NaN, .CR j0() , .CR j1() , and .CR jn() return NaN. .PP If the correct result after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR j0() , .CR j1() , and .CR jn() return zero. .SH ERRORS No errors are defined. .SH SEE ALSO y0(3M), isnan(3M), values(5). .PP M. Abramowitz and I. Stegun, .I "Handbook of Mathematical Functions" (New York: Dover Publications, 1972). .SH STANDARDS CONFORMANCE .CR j0() ": SVID3, XPG4.2" .PP .CR j1() ": SVID3, XPG4.2" .PP .CR jn() ": SVID3, XPG4.2" .\" .\" index@\f4j0()\f1, \f4j1()\f1, \f4jn()\fP \- Bessel functions of the first kind@@@\f3j0(3M)\f1 .\" index@math: Bessel functions of the first kind@@@\f3j0(3M)\f1 .\" index@Bessel functions of the first kind@@@\f3j0(3M)\f1 .\" index@\f4j1()\f1 \- Bessel function@@@\f3j0(3M)\f1 .\" index@\f4jn()\fP \- Bessel function@@@\f3j0(3M)\f1 .\" .\" toc@\f3j0(3M)\f1:\0\0\f4j0()\f1, \f4j1()\f1, \f4jn()\fP@@@Bessel functions of the first kind .\" toc@\f4j1()\f1:\0\0Bessel function@@@see \f3j0(3M)\f1 .\" toc@\f4jn()\fP:\0\0Bessel function@@@see \f3j0(3M)\f1 .\" .\" links@j0.3m j1.3m .\" links@j0.3m jn.3m .\" .\" fileset_database@j0.3m PROGRAMING-MAN .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: secure_rpc.3c,v 74.1 95/05/10 21:12:12 ssa Exp $ .TA s .TH secure_rpc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME secure_rpc(), authdes_create(), authdes_getucred(), get_myaddress(), getnetname(), host2netname(), key_decryptsession(), key_encryptsession(), key_gendes(), key_setsecret(), netname2host(), netname2user(), user2netname() \- library routines for secure remote procedure calls .SH DESCRIPTION .LP .C RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .LP .C RPC allows various authentication flavors. The .B authdes_getucred() and .B authdes_create() routines implement the .B DES authentication flavor. See .BR rpc_clnt_auth (3C) for routines relating to the .B AUTH_NONE and .B AUTH_UNIX authentication types. .IP Note: Both the client and server should have their keys in the .BR publickey (5) database. Also, the keyserver daemon .BR keyserv (1M) must be running on both the client and server hosts for the .B DES authentication system to work. .SS Routines .LP The following routines require that the header .BR be included. .PP The .B AUTH data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "AUTH *" .C "authdes_create(netname, window, syncaddr, deskeyp)" .C "char *netname;" .C "unsigned window;" .C "struct sockaddr_in *syncaddr;" .C "des_block *deskeyp;" .fi .IP .B authdes_create() is an interface to the .B RPC secure authentication system, known as .B DES authentication. .IP Used on the client side, .B authdes_create() returns an authentication handle that enables the use of the secure authentication system. The first parameter .I netname is the network name of the owner of the server process. This field usually represents a .I host derived from the utility routine .BR host2netname() , but could also represent a user name using .BR user2netname() . The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third parameter .I syncaddr is optional. If it is .B NULL, then the authentication system will assume that the local clock is always in sync with the server's clock, and will not attempt to synchronize with the server. If an address is supplied then the system will use it for consulting the remote time service whenever resynchronization is required. This parameter is usually the address of the .B RPC server itself. The final parameter .I deskeyp is also optional. If it is .B NULL, then the authentication system will generate a random .B DES key to be used for the encryption of credentials. If .I deskeyp is supplied then it is used instead. .PP .nf .C "int" .C "authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)" .C "struct authdes_cred *adc;" .C "short *uidp, *gidp, *gidlenp;" .C "int *gidlistp;" .fi .IP .BR authdes_getucred() , is a .B DES authentication routine used by the server for converting a .B DES credential, which is operating system independent, into a .B UNIX credential. .I uidp points to the user .B ID of the user associated with .IR adc ; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. .br .ne 5 .IP This routine differs from the utility routine .B netname2user() in that .B authdes_getucred() pulls its information from a cache, and does not have to do a .B NIS name service lookup every time it is called to get its information. Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "void" .C "get_myaddress(addr)" .C "struct sockaddr_in *addr;" .fi .IP Return the machine's .B IP address in .IR addr. The port number is always set to .BR htons(PMAPPORT) . .PP .nf .C "int" .C "getnetname(netname)" .C "char netname[MAXNETNAMELEN];" .fi .IP Return the unique, operating-system independent netname of the caller in the fixed-length array .IR netname . Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "int" .C "host2netname(netname, host, domain)" .C "char netname[MAXNETNAMELEN];" .C "char *host;" .C "char *domain;" .fi .IP Convert from a domain-specific hostname to an operating-system independent netname. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . This routine should be used if the owner of the server process is the machine that is, the user with effective user .B ID zero. Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2host() . .PP .nf .C "int" .C "key_decryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP An interface routine to the keyserver daemon, which is associated with .B RPC's secure authentication system ( .B DES authentication). User programs rarely need to call it, or its associated routines .BR key_encryptsession() , .B key_gendes() and .BR key_setsecret() . System commands such as .B login and the .B RPC library are the main clients of these four routines. .IP .B key_decryptsession() takes the netname of a server and a .B DES key, and decrypts the key by using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_encryptsession() . .PP .nf .C "int" .C "key_encryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It takes the netname of the server and a .B DES key, and encrypts it using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_decryptsession() . .PP .nf .C "int" .C "key_gendes(deskeyp)" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It is used to ask the keyserver for a secure conversation key. Choosing one at random is usually not good enough, because the common ways of choosing random numbers, such as using the current time, are very easy to guess. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "key_setsecret(keyp)" .C "char *keyp;" .fi .IP A keyserver interface routine. It is used to set the secret key for the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "netname2host(netname, host, hostlen)" .C "char *netname;" .C "char *host;" .C "int hostlen;" .fi .IP Convert an operating-system independent netname to a domain-specific hostname. .I hostlen specifies the size of the array pointed to by .I host. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR host2netname() . .PP .nf .C "int" .C "netname2user(netname, uidp, gidp, gidlenp, gidlistp)" .C "char *netname;" .C "int *uidp, *gidp, *gidlenp, *gidlistp;" .fi .IP Convert an operating-system independent netname to a domain-specific user .B ID. .I uidp points to the user .B ID of the user; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR user2netname() . .PP .nf .C "int" .C "user2netname(netname, uid, domain)" .C "char netname[MAXNETNAMELEN];" .C "int uid;" .C "char *domain;" .fi .IP Convert a domain-specific username to an operating-system independent netname. .I uid is the user .B ID of the owner of the server process. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2user() . .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR login (1), .BR chkey (1), .BR rpc (3C), .BR rpc_clnt_auth (3C), .BR publickey (4), .BR keyserv (1M), .BR newkey (1M) .\" toc@\f3secure_rpc(3C)\f1:\0\0\f4authdes_create()\fP, \f4authdes_getucred()\fP, \f4get_myaddress()\fP, \n\f4getnetaddress()\fP, \f4getnetname()\fP, \f4host2netname()\fP, \n\f4key_decryptsession()\fP, \f4key_encryptsession()\fP, \f4key_gendes()\fP, \n\f4key_setsecret()\fP, \f4netname2host()\fP, \f4netname2user()\fP, \n\f4user2netname()\fP@@@library routines for secure remote procedure calls .\" toc@\f4secure_rpc()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_create()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_getucred()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4get_myaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4host2netname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_decryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_encryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_gendes()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_setsecret()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2host()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2user()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4user2netname()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" index@library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4secure_rpc()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_create()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_getucred()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4get_myaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4host2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_decryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_encryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_gendes()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_setsecret()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2host()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2user()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4user2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" links@secure_rpc.3c authdes_create.3c .\" links@secure_rpc.3c authdes_getucred.3c .\" links@secure_rpc.3c get_myaddress.3c .\" links@secure_rpc.3c getnetaddress.3c .\" links@secure_rpc.3c getnetname.3c .\" links@secure_rpc.3c host2netname.3c .\" links@secure_rpc.3c key_decryptsession.3c .\" links@secure_rpc.3c key_encryptsession.3c .\" links@secure_rpc.3c key_gendes.3c .\" links@secure_rpc.3c key_setsecret.3c .\" links@secure_rpc.3c netname2host.3c .\" links@secure_rpc.3c netname2user.3c .\" links@secure_rpc.3c user2netname.3c .\" $Header: secure_rpc.3c,v 74.1 95/05/10 21:12:12 ssa Exp $ .TA s .TH secure_rpc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME secure_rpc(), authdes_create(), authdes_getucred(), get_myaddress(), getnetname(), host2netname(), key_decryptsession(), key_encryptsession(), key_gendes(), key_setsecret(), netname2host(), netname2user(), user2netname() \- library routines for secure remote procedure calls .SH DESCRIPTION .LP .C RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .LP .C RPC allows various authentication flavors. The .B authdes_getucred() and .B authdes_create() routines implement the .B DES authentication flavor. See .BR rpc_clnt_auth (3C) for routines relating to the .B AUTH_NONE and .B AUTH_UNIX authentication types. .IP Note: Both the client and server should have their keys in the .BR publickey (5) database. Also, the keyserver daemon .BR keyserv (1M) must be running on both the client and server hosts for the .B DES authentication system to work. .SS Routines .LP The following routines require that the header .BR be included. .PP The .B AUTH data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "AUTH *" .C "authdes_create(netname, window, syncaddr, deskeyp)" .C "char *netname;" .C "unsigned window;" .C "struct sockaddr_in *syncaddr;" .C "des_block *deskeyp;" .fi .IP .B authdes_create() is an interface to the .B RPC secure authentication system, known as .B DES authentication. .IP Used on the client side, .B authdes_create() returns an authentication handle that enables the use of the secure authentication system. The first parameter .I netname is the network name of the owner of the server process. This field usually represents a .I host derived from the utility routine .BR host2netname() , but could also represent a user name using .BR user2netname() . The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third parameter .I syncaddr is optional. If it is .B NULL, then the authentication system will assume that the local clock is always in sync with the server's clock, and will not attempt to synchronize with the server. If an address is supplied then the system will use it for consulting the remote time service whenever resynchronization is required. This parameter is usually the address of the .B RPC server itself. The final parameter .I deskeyp is also optional. If it is .B NULL, then the authentication system will generate a random .B DES key to be used for the encryption of credentials. If .I deskeyp is supplied then it is used instead. .PP .nf .C "int" .C "authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)" .C "struct authdes_cred *adc;" .C "short *uidp, *gidp, *gidlenp;" .C "int *gidlistp;" .fi .IP .BR authdes_getucred() , is a .B DES authentication routine used by the server for converting a .B DES credential, which is operating system independent, into a .B UNIX credential. .I uidp points to the user .B ID of the user associated with .IR adc ; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. .br .ne 5 .IP This routine differs from the utility routine .B netname2user() in that .B authdes_getucred() pulls its information from a cache, and does not have to do a .B NIS name service lookup every time it is called to get its information. Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "void" .C "get_myaddress(addr)" .C "struct sockaddr_in *addr;" .fi .IP Return the machine's .B IP address in .IR addr. The port number is always set to .BR htons(PMAPPORT) . .PP .nf .C "int" .C "getnetname(netname)" .C "char netname[MAXNETNAMELEN];" .fi .IP Return the unique, operating-system independent netname of the caller in the fixed-length array .IR netname . Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "int" .C "host2netname(netname, host, domain)" .C "char netname[MAXNETNAMELEN];" .C "char *host;" .C "char *domain;" .fi .IP Convert from a domain-specific hostname to an operating-system independent netname. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . This routine should be used if the owner of the server process is the machine that is, the user with effective user .B ID zero. Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2host() . .PP .nf .C "int" .C "key_decryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP An interface routine to the keyserver daemon, which is associated with .B RPC's secure authentication system ( .B DES authentication). User programs rarely need to call it, or its associated routines .BR key_encryptsession() , .B key_gendes() and .BR key_setsecret() . System commands such as .B login and the .B RPC library are the main clients of these four routines. .IP .B key_decryptsession() takes the netname of a server and a .B DES key, and decrypts the key by using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_encryptsession() . .PP .nf .C "int" .C "key_encryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It takes the netname of the server and a .B DES key, and encrypts it using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_decryptsession() . .PP .nf .C "int" .C "key_gendes(deskeyp)" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It is used to ask the keyserver for a secure conversation key. Choosing one at random is usually not good enough, because the common ways of choosing random numbers, such as using the current time, are very easy to guess. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "key_setsecret(keyp)" .C "char *keyp;" .fi .IP A keyserver interface routine. It is used to set the secret key for the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "netname2host(netname, host, hostlen)" .C "char *netname;" .C "char *host;" .C "int hostlen;" .fi .IP Convert an operating-system independent netname to a domain-specific hostname. .I hostlen specifies the size of the array pointed to by .I host. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR host2netname() . .PP .nf .C "int" .C "netname2user(netname, uidp, gidp, gidlenp, gidlistp)" .C "char *netname;" .C "int *uidp, *gidp, *gidlenp, *gidlistp;" .fi .IP Convert an operating-system independent netname to a domain-specific user .B ID. .I uidp points to the user .B ID of the user; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR user2netname() . .PP .nf .C "int" .C "user2netname(netname, uid, domain)" .C "char netname[MAXNETNAMELEN];" .C "int uid;" .C "char *domain;" .fi .IP Convert a domain-specific username to an operating-system independent netname. .I uid is the user .B ID of the owner of the server process. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2user() . .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR login (1), .BR chkey (1), .BR rpc (3C), .BR rpc_clnt_auth (3C), .BR publickey (4), .BR keyserv (1M), .BR newkey (1M) .\" toc@\f3secure_rpc(3C)\f1:\0\0\f4authdes_create()\fP, \f4authdes_getucred()\fP, \f4get_myaddress()\fP, \n\f4getnetaddress()\fP, \f4getnetname()\fP, \f4host2netname()\fP, \n\f4key_decryptsession()\fP, \f4key_encryptsession()\fP, \f4key_gendes()\fP, \n\f4key_setsecret()\fP, \f4netname2host()\fP, \f4netname2user()\fP, \n\f4user2netname()\fP@@@library routines for secure remote procedure calls .\" toc@\f4secure_rpc()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_create()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_getucred()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4get_myaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4host2netname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_decryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_encryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_gendes()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_setsecret()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2host()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2user()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4user2netname()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" index@library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4secure_rpc()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_create()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_getucred()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4get_myaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4host2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_decryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_encryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_gendes()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_setsecret()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2host()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2user()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4user2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" links@secure_rpc.3c authdes_create.3c .\" links@secure_rpc.3c authdes_getucred.3c .\" links@secure_rpc.3c get_myaddress.3c .\" links@secure_rpc.3c getnetaddress.3c .\" links@secure_rpc.3c getnetname.3c .\" links@secure_rpc.3c host2netname.3c .\" links@secure_rpc.3c key_decryptsession.3c .\" links@secure_rpc.3c key_encryptsession.3c .\" links@secure_rpc.3c key_gendes.3c .\" links@secure_rpc.3c key_setsecret.3c .\" links@secure_rpc.3c netname2host.3c .\" links@secure_rpc.3c netname2user.3c .\" links@secure_rpc.3c user2netname.3c .\" $Header: secure_rpc.3c,v 74.1 95/05/10 21:12:12 ssa Exp $ .TA s .TH secure_rpc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME secure_rpc(), authdes_create(), authdes_getucred(), get_myaddress(), getnetname(), host2netname(), key_decryptsession(), key_encryptsession(), key_gendes(), key_setsecret(), netname2host(), netname2user(), user2netname() \- library routines for secure remote procedure calls .SH DESCRIPTION .LP .C RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .LP .C RPC allows various authentication flavors. The .B authdes_getucred() and .B authdes_create() routines implement the .B DES authentication flavor. See .BR rpc_clnt_auth (3C) for routines relating to the .B AUTH_NONE and .B AUTH_UNIX authentication types. .IP Note: Both the client and server should have their keys in the .BR publickey (5) database. Also, the keyserver daemon .BR keyserv (1M) must be running on both the client and server hosts for the .B DES authentication system to work. .SS Routines .LP The following routines require that the header .BR be included. .PP The .B AUTH data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "AUTH *" .C "authdes_create(netname, window, syncaddr, deskeyp)" .C "char *netname;" .C "unsigned window;" .C "struct sockaddr_in *syncaddr;" .C "des_block *deskeyp;" .fi .IP .B authdes_create() is an interface to the .B RPC secure authentication system, known as .B DES authentication. .IP Used on the client side, .B authdes_create() returns an authentication handle that enables the use of the secure authentication system. The first parameter .I netname is the network name of the owner of the server process. This field usually represents a .I host derived from the utility routine .BR host2netname() , but could also represent a user name using .BR user2netname() . The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third parameter .I syncaddr is optional. If it is .B NULL, then the authentication system will assume that the local clock is always in sync with the server's clock, and will not attempt to synchronize with the server. If an address is supplied then the system will use it for consulting the remote time service whenever resynchronization is required. This parameter is usually the address of the .B RPC server itself. The final parameter .I deskeyp is also optional. If it is .B NULL, then the authentication system will generate a random .B DES key to be used for the encryption of credentials. If .I deskeyp is supplied then it is used instead. .PP .nf .C "int" .C "authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)" .C "struct authdes_cred *adc;" .C "short *uidp, *gidp, *gidlenp;" .C "int *gidlistp;" .fi .IP .BR authdes_getucred() , is a .B DES authentication routine used by the server for converting a .B DES credential, which is operating system independent, into a .B UNIX credential. .I uidp points to the user .B ID of the user associated with .IR adc ; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. .br .ne 5 .IP This routine differs from the utility routine .B netname2user() in that .B authdes_getucred() pulls its information from a cache, and does not have to do a .B NIS name service lookup every time it is called to get its information. Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "void" .C "get_myaddress(addr)" .C "struct sockaddr_in *addr;" .fi .IP Return the machine's .B IP address in .IR addr. The port number is always set to .BR htons(PMAPPORT) . .PP .nf .C "int" .C "getnetname(netname)" .C "char netname[MAXNETNAMELEN];" .fi .IP Return the unique, operating-system independent netname of the caller in the fixed-length array .IR netname . Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "int" .C "host2netname(netname, host, domain)" .C "char netname[MAXNETNAMELEN];" .C "char *host;" .C "char *domain;" .fi .IP Convert from a domain-specific hostname to an operating-system independent netname. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . This routine should be used if the owner of the server process is the machine that is, the user with effective user .B ID zero. Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2host() . .PP .nf .C "int" .C "key_decryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP An interface routine to the keyserver daemon, which is associated with .B RPC's secure authentication system ( .B DES authentication). User programs rarely need to call it, or its associated routines .BR key_encryptsession() , .B key_gendes() and .BR key_setsecret() . System commands such as .B login and the .B RPC library are the main clients of these four routines. .IP .B key_decryptsession() takes the netname of a server and a .B DES key, and decrypts the key by using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_encryptsession() . .PP .nf .C "int" .C "key_encryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It takes the netname of the server and a .B DES key, and encrypts it using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_decryptsession() . .PP .nf .C "int" .C "key_gendes(deskeyp)" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It is used to ask the keyserver for a secure conversation key. Choosing one at random is usually not good enough, because the common ways of choosing random numbers, such as using the current time, are very easy to guess. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "key_setsecret(keyp)" .C "char *keyp;" .fi .IP A keyserver interface routine. It is used to set the secret key for the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "netname2host(netname, host, hostlen)" .C "char *netname;" .C "char *host;" .C "int hostlen;" .fi .IP Convert an operating-system independent netname to a domain-specific hostname. .I hostlen specifies the size of the array pointed to by .I host. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR host2netname() . .PP .nf .C "int" .C "netname2user(netname, uidp, gidp, gidlenp, gidlistp)" .C "char *netname;" .C "int *uidp, *gidp, *gidlenp, *gidlistp;" .fi .IP Convert an operating-system independent netname to a domain-specific user .B ID. .I uidp points to the user .B ID of the user; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR user2netname() . .PP .nf .C "int" .C "user2netname(netname, uid, domain)" .C "char netname[MAXNETNAMELEN];" .C "int uid;" .C "char *domain;" .fi .IP Convert a domain-specific username to an operating-system independent netname. .I uid is the user .B ID of the owner of the server process. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2user() . .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR login (1), .BR chkey (1), .BR rpc (3C), .BR rpc_clnt_auth (3C), .BR publickey (4), .BR keyserv (1M), .BR newkey (1M) .\" toc@\f3secure_rpc(3C)\f1:\0\0\f4authdes_create()\fP, \f4authdes_getucred()\fP, \f4get_myaddress()\fP, \n\f4getnetaddress()\fP, \f4getnetname()\fP, \f4host2netname()\fP, \n\f4key_decryptsession()\fP, \f4key_encryptsession()\fP, \f4key_gendes()\fP, \n\f4key_setsecret()\fP, \f4netname2host()\fP, \f4netname2user()\fP, \n\f4user2netname()\fP@@@library routines for secure remote procedure calls .\" toc@\f4secure_rpc()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_create()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_getucred()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4get_myaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4host2netname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_decryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_encryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_gendes()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_setsecret()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2host()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2user()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4user2netname()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" index@library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4secure_rpc()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_create()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_getucred()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4get_myaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4host2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_decryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_encryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_gendes()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_setsecret()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2host()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2user()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4user2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" links@secure_rpc.3c authdes_create.3c .\" links@secure_rpc.3c authdes_getucred.3c .\" links@secure_rpc.3c get_myaddress.3c .\" links@secure_rpc.3c getnetaddress.3c .\" links@secure_rpc.3c getnetname.3c .\" links@secure_rpc.3c host2netname.3c .\" links@secure_rpc.3c key_decryptsession.3c .\" links@secure_rpc.3c key_encryptsession.3c .\" links@secure_rpc.3c key_gendes.3c .\" links@secure_rpc.3c key_setsecret.3c .\" links@secure_rpc.3c netname2host.3c .\" links@secure_rpc.3c netname2user.3c .\" links@secure_rpc.3c user2netname.3c .\" $Header: keyname.3x,v 76.2 95/08/01 11:32:48 ssa Exp $ .TA k .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH keyname 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME keyname, key_name \(em get name of key .SH SYNOPSIS .C "#include " .P .C "char *keyname(int \f2c\fP);" .P .C "char *key_name(wchar_t \f2c\fP);" .SH DESCRIPTION The .Fn keyname and .Fn key_name functions generate a character string whose value describes the key \f2c\f1. The \f2c\f1 argument of .Fn keyname can be an 8-bit character or a key code. The \f2c\f1 argument of .Fn key_name must be a wide character. .P The string has a format according to the first applicable row in the following table: .P .TS box center tab(`); cb cb l l. Input `Format of Returned String _ Visible character`The same character Control character`\f4^\f2X\f1 Meta-character (\f4keyname\^(\|)\f1 only)`\f4M-\f2X\f1 Key value in <\f3curses.h\fP> (\f4keyname\^(\|)\f1 only)`\f4KEY_\f2name\f1 None of the above`\f4UNKNOWN KEY\f1 .TE .P The meta-character notation shown above is used only if meta-characters are enabled. .SH "RETURN VALUE" Upon successful completion, .Fn keyname returns a pointer to a string as described above. Otherwise, it returns a null pointer. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The return value of .Fn keyname and .Fn key_name may point to a static area which is overwritten by a subsequent call to either of these functions. .P Applications normally process meta-characters without storing them into a window. If an application stores meta-characters in a window and tries to retrieve them as wide characters, .Fn keyname cannot detect meta-characters, since wide characters do not support meta-characters. .SH "SEE ALSO" meta(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3keyname(3X)\f1:\0\0\f4keyname()\f1, \f4key_name()\f1@@@get name of key .\" toc@\f4key_name()\f1: get name of key@@@see \f3keyname(3X)\f1 .\" .\" index@\f4keyname()\f1 \- get name of key@@@\f3keyname(3X)\f1 .\" index@\f4key_name()\f1 \- get name of key@@@\f3keyname(3X)\f1 .\" index@\f1get name of key@@@\f3keyname(3X)\f1 .\" index@\f1name of key, get@@@\f3keyname(3X)\f1 .\" index@\f1key, get name of@@@\f3keyname(3X)\f1 .\" .\" links@keyname.3x key_name.3x .\" .\" fileset_database@keyname.3x CURS-ENG-A-MAN .\" $Header: secure_rpc.3c,v 74.1 95/05/10 21:12:12 ssa Exp $ .TA s .TH secure_rpc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME secure_rpc(), authdes_create(), authdes_getucred(), get_myaddress(), getnetname(), host2netname(), key_decryptsession(), key_encryptsession(), key_gendes(), key_setsecret(), netname2host(), netname2user(), user2netname() \- library routines for secure remote procedure calls .SH DESCRIPTION .LP .C RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .LP .C RPC allows various authentication flavors. The .B authdes_getucred() and .B authdes_create() routines implement the .B DES authentication flavor. See .BR rpc_clnt_auth (3C) for routines relating to the .B AUTH_NONE and .B AUTH_UNIX authentication types. .IP Note: Both the client and server should have their keys in the .BR publickey (5) database. Also, the keyserver daemon .BR keyserv (1M) must be running on both the client and server hosts for the .B DES authentication system to work. .SS Routines .LP The following routines require that the header .BR be included. .PP The .B AUTH data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "AUTH *" .C "authdes_create(netname, window, syncaddr, deskeyp)" .C "char *netname;" .C "unsigned window;" .C "struct sockaddr_in *syncaddr;" .C "des_block *deskeyp;" .fi .IP .B authdes_create() is an interface to the .B RPC secure authentication system, known as .B DES authentication. .IP Used on the client side, .B authdes_create() returns an authentication handle that enables the use of the secure authentication system. The first parameter .I netname is the network name of the owner of the server process. This field usually represents a .I host derived from the utility routine .BR host2netname() , but could also represent a user name using .BR user2netname() . The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third parameter .I syncaddr is optional. If it is .B NULL, then the authentication system will assume that the local clock is always in sync with the server's clock, and will not attempt to synchronize with the server. If an address is supplied then the system will use it for consulting the remote time service whenever resynchronization is required. This parameter is usually the address of the .B RPC server itself. The final parameter .I deskeyp is also optional. If it is .B NULL, then the authentication system will generate a random .B DES key to be used for the encryption of credentials. If .I deskeyp is supplied then it is used instead. .PP .nf .C "int" .C "authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)" .C "struct authdes_cred *adc;" .C "short *uidp, *gidp, *gidlenp;" .C "int *gidlistp;" .fi .IP .BR authdes_getucred() , is a .B DES authentication routine used by the server for converting a .B DES credential, which is operating system independent, into a .B UNIX credential. .I uidp points to the user .B ID of the user associated with .IR adc ; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. .br .ne 5 .IP This routine differs from the utility routine .B netname2user() in that .B authdes_getucred() pulls its information from a cache, and does not have to do a .B NIS name service lookup every time it is called to get its information. Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "void" .C "get_myaddress(addr)" .C "struct sockaddr_in *addr;" .fi .IP Return the machine's .B IP address in .IR addr. The port number is always set to .BR htons(PMAPPORT) . .PP .nf .C "int" .C "getnetname(netname)" .C "char netname[MAXNETNAMELEN];" .fi .IP Return the unique, operating-system independent netname of the caller in the fixed-length array .IR netname . Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "int" .C "host2netname(netname, host, domain)" .C "char netname[MAXNETNAMELEN];" .C "char *host;" .C "char *domain;" .fi .IP Convert from a domain-specific hostname to an operating-system independent netname. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . This routine should be used if the owner of the server process is the machine that is, the user with effective user .B ID zero. Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2host() . .PP .nf .C "int" .C "key_decryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP An interface routine to the keyserver daemon, which is associated with .B RPC's secure authentication system ( .B DES authentication). User programs rarely need to call it, or its associated routines .BR key_encryptsession() , .B key_gendes() and .BR key_setsecret() . System commands such as .B login and the .B RPC library are the main clients of these four routines. .IP .B key_decryptsession() takes the netname of a server and a .B DES key, and decrypts the key by using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_encryptsession() . .PP .nf .C "int" .C "key_encryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It takes the netname of the server and a .B DES key, and encrypts it using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_decryptsession() . .PP .nf .C "int" .C "key_gendes(deskeyp)" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It is used to ask the keyserver for a secure conversation key. Choosing one at random is usually not good enough, because the common ways of choosing random numbers, such as using the current time, are very easy to guess. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "key_setsecret(keyp)" .C "char *keyp;" .fi .IP A keyserver interface routine. It is used to set the secret key for the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "netname2host(netname, host, hostlen)" .C "char *netname;" .C "char *host;" .C "int hostlen;" .fi .IP Convert an operating-system independent netname to a domain-specific hostname. .I hostlen specifies the size of the array pointed to by .I host. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR host2netname() . .PP .nf .C "int" .C "netname2user(netname, uidp, gidp, gidlenp, gidlistp)" .C "char *netname;" .C "int *uidp, *gidp, *gidlenp, *gidlistp;" .fi .IP Convert an operating-system independent netname to a domain-specific user .B ID. .I uidp points to the user .B ID of the user; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR user2netname() . .PP .nf .C "int" .C "user2netname(netname, uid, domain)" .C "char netname[MAXNETNAMELEN];" .C "int uid;" .C "char *domain;" .fi .IP Convert a domain-specific username to an operating-system independent netname. .I uid is the user .B ID of the owner of the server process. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2user() . .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR login (1), .BR chkey (1), .BR rpc (3C), .BR rpc_clnt_auth (3C), .BR publickey (4), .BR keyserv (1M), .BR newkey (1M) .\" toc@\f3secure_rpc(3C)\f1:\0\0\f4authdes_create()\fP, \f4authdes_getucred()\fP, \f4get_myaddress()\fP, \n\f4getnetaddress()\fP, \f4getnetname()\fP, \f4host2netname()\fP, \n\f4key_decryptsession()\fP, \f4key_encryptsession()\fP, \f4key_gendes()\fP, \n\f4key_setsecret()\fP, \f4netname2host()\fP, \f4netname2user()\fP, \n\f4user2netname()\fP@@@library routines for secure remote procedure calls .\" toc@\f4secure_rpc()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_create()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_getucred()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4get_myaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4host2netname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_decryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_encryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_gendes()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_setsecret()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2host()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2user()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4user2netname()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" index@library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4secure_rpc()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_create()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_getucred()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4get_myaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4host2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_decryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_encryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_gendes()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_setsecret()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2host()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2user()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4user2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" links@secure_rpc.3c authdes_create.3c .\" links@secure_rpc.3c authdes_getucred.3c .\" links@secure_rpc.3c get_myaddress.3c .\" links@secure_rpc.3c getnetaddress.3c .\" links@secure_rpc.3c getnetname.3c .\" links@secure_rpc.3c host2netname.3c .\" links@secure_rpc.3c key_decryptsession.3c .\" links@secure_rpc.3c key_encryptsession.3c .\" links@secure_rpc.3c key_gendes.3c .\" links@secure_rpc.3c key_setsecret.3c .\" links@secure_rpc.3c netname2host.3c .\" links@secure_rpc.3c netname2user.3c .\" links@secure_rpc.3c user2netname.3c .\" $Header: keyname.3x,v 76.2 95/08/01 11:32:48 ssa Exp $ .TA k .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH keyname 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME keyname, key_name \(em get name of key .SH SYNOPSIS .C "#include " .P .C "char *keyname(int \f2c\fP);" .P .C "char *key_name(wchar_t \f2c\fP);" .SH DESCRIPTION The .Fn keyname and .Fn key_name functions generate a character string whose value describes the key \f2c\f1. The \f2c\f1 argument of .Fn keyname can be an 8-bit character or a key code. The \f2c\f1 argument of .Fn key_name must be a wide character. .P The string has a format according to the first applicable row in the following table: .P .TS box center tab(`); cb cb l l. Input `Format of Returned String _ Visible character`The same character Control character`\f4^\f2X\f1 Meta-character (\f4keyname\^(\|)\f1 only)`\f4M-\f2X\f1 Key value in <\f3curses.h\fP> (\f4keyname\^(\|)\f1 only)`\f4KEY_\f2name\f1 None of the above`\f4UNKNOWN KEY\f1 .TE .P The meta-character notation shown above is used only if meta-characters are enabled. .SH "RETURN VALUE" Upon successful completion, .Fn keyname returns a pointer to a string as described above. Otherwise, it returns a null pointer. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The return value of .Fn keyname and .Fn key_name may point to a static area which is overwritten by a subsequent call to either of these functions. .P Applications normally process meta-characters without storing them into a window. If an application stores meta-characters in a window and tries to retrieve them as wide characters, .Fn keyname cannot detect meta-characters, since wide characters do not support meta-characters. .SH "SEE ALSO" meta(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3keyname(3X)\f1:\0\0\f4keyname()\f1, \f4key_name()\f1@@@get name of key .\" toc@\f4key_name()\f1: get name of key@@@see \f3keyname(3X)\f1 .\" .\" index@\f4keyname()\f1 \- get name of key@@@\f3keyname(3X)\f1 .\" index@\f4key_name()\f1 \- get name of key@@@\f3keyname(3X)\f1 .\" index@\f1get name of key@@@\f3keyname(3X)\f1 .\" index@\f1name of key, get@@@\f3keyname(3X)\f1 .\" index@\f1key, get name of@@@\f3keyname(3X)\f1 .\" .\" links@keyname.3x key_name.3x .\" .\" fileset_database@keyname.3x CURS-ENG-A-MAN .\" $Header: keypad.3x,v 76.2 95/08/01 11:33:38 ssa Exp $ .TA k .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH keypad 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME keypad \(em enable/disable abbreviation of function keys .SH SYNOPSIS .C "#include " .P .C "int keypad(WINDOW *\f2win\fP, bool \f2bf\fP);" .SH DESCRIPTION The .Fn keypad function controls keypad translation. If \f2bf\f1 is TRUE, keypad translation is turned on. If \f2bf\f1 is FALSE, keypad translation is turned off. The initial state is FALSE. .P This function affects the behaviour of any function that provides keyboard input. .P If the terminal in use requires a command to enable it to transmit distinctive codes when a function key is pressed, then after keypad translation is first enabled, the implementation transmits this command to the terminal before an affected input function tries to read any characters from that terminal. .SH "RETURN VALUE" Upon successful completion, .Fn keypad returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Keypad Processing\f1 in curs_intro, . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" index@\f4keypad()\f1 \- enable/disable abbreviation of function keys@@@\f3keypad(3X)\f1 .\" index@\f1enable/disable abbreviation of function keys@@@\f3keypad(3X)\f1 .\" index@\f1disable or enable abbreviation of function keys@@@\f3keypad(3X)\f1 .\" index@\f1abbreviation of function keys, enable/disable@@@\f3keypad(3X)\f1 .\" index@\f1function keys, enable/disable abbreviation of@@@\f3keypad(3X)\f1 .\" .\" toc@\f3keypad(3X)\f1:\0\0\f4keypad()\f1@@@enable/disable abbreviation of function keys .\" .\" fileset_database@keypad.3x CURS-ENG-A-MAN .\" $Header: erasechar.3x,v 76.2 95/07/31 17:46:43 ssa Exp $ .TA e .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH erasechar 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME erasechar, killchar \(em single-byte terminal environment query functions .SH SYNOPSIS .C "#include " .P .C "char erasechar(void);" .P .C "char killchar(void);" .SH DESCRIPTION The .Fn erasechar function returns the current erase character. \ The .Fn erasewchar function stores the current erase character in the object pointed to by \f2ch\f1. If no erase character has been defined, the function will fail and the object pointed to by \f2ch\f1 will not be changed. .P The .Fn killchar function returns the current line kill character. .SH "RETURN VALUE" The .Fn erasechar function returns the erase character and .Fn killchar returns the line kill character. The return value is unspecified when these characters are multi-byte characters. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn erasechar and .Fn killchar functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. Moreover, they do not reliably indicate cases in which when the erase or line kill character, respectively, has not been defined. The .Fn erasewchar and .Fn killwchar functions overcome these limitations. .SH "SEE ALSO" \f3Attributes\f1 in curses_intro, clearok(), delscreen(), erasewchar(), , tcgetattr() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn killchar function is merged with this entry. In previous issues, it appeared in an entry of its own. .P The entry is rewritten for clarity. The argument list for the .Fn erasechar and .Fn killchar functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3erasechar(3X)\f1:\0\0\f4erasechar()\f1, \f4killchar()\f1@@@single-byte terminal environment query functions .\" toc@\f4killchar()\f1: single-byte line kill character@@@see \f3erasechar(3X)\f1 .\" .\" index@\f4erasechar()\f1 \- single-byte erase character@@@\f3erasechar(3X)\f1 .\" index@\f4killchar()\f1 \- single-byte line kill@@@\f3erasechar(3X)\f1 .\" index@\f1single-byte terminal environment query functions@@@\f3erasechar(3X)\f1 .\" index@\f1line kill character, single-byte@@@\f3erasechar(3X)\f1 .\" index@\f1erase character, single-byte@@@\f3erasechar(3X)\f1 .\" .\" links@erasechar.3x killchar.3x .\" .\" fileset_database@erasechar.3x CURS-ENG-A-MAN .\" $Header: erasewchar.3x,v 76.2 95/07/31 17:47:49 ssa Exp $ .TA e .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH erasewchar 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME erasewchar, killwchar \(em terminal environment query functions .SH SYNOPSIS .C "#include " .P .C "int erasewchar(wchar_t *\f2ch\fP);" .P .C "int killwchar(wchar_t *\f2ch\fP);" .SH DESCRIPTION The .Fn erasewchar function stores the current erase character in the object pointed to by \f2ch\f1. If no erase character has been defined, the function will fail and the object pointed to by \f2ch\f1 will not be changed. .P The .Fn killwchar function stores the current line kill character in the object pointed to by \f2ch\f1. If no line kill character has been defined, the function will fail and the object pointed to by \f2ch\f1 will not be changed. .SH "RETURN VALUE" .P Upon successful completion, .Fn erasewchar and .Fn killwchar return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Attributes\f1 in curses_intro, clearok(), delscreen(), , tcgetattr() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3erasewchar(3X)\f1:\0\0\f4erasewchar()\f1, \f4killwchar()\f1@@@current erase and line kill characters .\" toc@\f4killwchar()\f1: current line kill character@@@see \f3erasewchar(3X)\f1 .\" .\" index@\f4erasewchar()\f1 \- current erase character@@@\f3erasewchar(3X)\f1 .\" index@\f4killwchar()\f1 \- current line kill character@@@\f3erasewchar(3X)\f1 .\" index@\f1current erase and line kill characters@@@\f3erasewchar(3X)\f1 .\" index@\f1line kill character@@@\f3erasewchar(3X)\f1 .\" index@\f1kill line character@@@\f3erasewchar(3X)\f1 .\" index@\f1erase character@@@\f3erasewchar(3X)\f1 .\" .\" links@erasewchar.3x killwchar.3x .\" .\" fileset_database@erasewchar.3x CURS-ENG-A-MAN .\" $Header: l3tol.3c,v 72.4 94/11/15 09:55:07 ssa Exp $ .TA l .TH l3tol 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME l3tol(\|), ltol3(\|) \- convert between 3-byte integers and long integers .SH SYNOPSIS .C "#include " .PP .C "void l3tol(long int *lp, const char *cp, int n);" .PP .C "void ltol3(char *cp, const long int *lp, int n);" .SH DESCRIPTION .TP 15 .C l3tol() Convert a list of .I n three-byte integers packed into a character string pointed to by .I cp into a list of long integers pointed to by .IR lp . .TP .C ltol3() Perform the reverse conversion from long integers .RI ( lp ) to three-byte integers .RI ( cp ). .PP These functions are useful for file-system maintenance where the block numbers are three bytes long. .SH SEE ALSO fs(4). .SH WARNINGS Because of possible differences in byte ordering, the numerical values of the long integers are machine-dependent. .SH STANDARDS CONFORMANCE .CR l3tol() ": XPG2" .PP .CR ltol3() ": XPG2" .\" .\" index@\f4l3tol()\f1 \- convert 3-byte integer to long integer@@@\f3l3tol(3C)\f1 .\" index@\f4ltol3()\f1 \- convert long integer to 3-byte integer@@@\f3l3tol(3C)\f1 .\" index@convert between 3-byte integers and long integers@@@\f3l3tol(3C)\f1 .\" index@three-byte integers and long integers, convert between@@@\f3l3tol(3C)\f1 .\" index@long integers and 3-byte integers, convert between@@@\f3l3tol(3C)\f1 .\" index@integers, convert between 3-byte integers and long integers@@@\f3l3tol(3C)\f1 .\" .\" toc@\f3l3tol(3C)\f1:\0\0\f4l3tol()\f1, \f4ltol3()\f1@@@convert between 3-byte integers and long integers .\" toc@\f4ltol3()\f1:\0\0convert between 3-byte integers and long integers@@@see \f3l3tol(3C)\f1 .\" .\" links@l3tol.3c ltol3.3c .\" .\" fileset_database@l3tol.3c PROGRAMING-MAN .\" $Header: a64l.3c,v 72.5 94/11/14 11:59:22 ssa Exp $ .TA a .TH a64l 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME a64l(\|), l64a(\|), l64a_r(\|) \- convert between long integer and base-64 ASCII string .SH SYNOPSIS .C "#include " .PP .C "long int a64l(const char *s);" .PP .C "char *l64a(long int l);" .PP .C "int l64a_r(long int l, char *buffer, int buflen);" .SH DESCRIPTION These functions are used to maintain numbers stored in .I base-64 .SM ASCII characters. This is a notation by which long integers can be represented by up to six characters; each character represents a "digit" in a radix-64 notation. .PP The characters used to represent "digits" are .C . for 0, .C / for 1, .C 0 through .C 9 for 2\-11, .C A through .C Z for 12\-37, and .C a through .C z for 38\-63. .PP The leftmost character is the least significant digit. For example, .RS 15 .if n a0 = (38 x 64^0) + (2 x 64^1) = 166 .if t a0 = (38 x 64\u\s-20\s+2\d) + (2 x 64\u\s-21\s+2\d) = 166 .RE .PP .C a64l() takes a pointer to a null-terminated base-64 representation and returns a corresponding .C long value. If the string pointed to by .I s contains more than six characters, .C a64l() uses the first six. .PP .C l64a() takes a .C long argument and returns a pointer to the corresponding base-64 representation. If the argument is 0, .C l64a() returns a pointer to a null string. .SS Reentrant Interfaces .C l64a_r() passes the result string back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .SH WARNINGS The value returned by .C l64a() is a pointer into a static buffer, the contents of which are overwritten by each call. Thus, .C l64a() is unsafe in multi-thread applications. .C l64a_r() is MT-Safe and should be used instead. .SH STANDARDS CONFORMANCE .CR a64l() ": SVID2, SVID3" .PP .CR l64a() ": SVID2, SVID3" .\" .\" index@\f4a64l()\f1 \- convert base-64 value to long integer \s-1ASCII\s+1 string@@@\f3a64l(3C)\f1 .\" index@\f4l64a()\f1 \- convert long integer to base-64 value \s-1ASCII\s+1 string@@@\f3a64l(3C)\f1 .\" index@\f4l64a_r()\f1 \- convert between long integer and base-64 \s-1ASCII\s+1 string@@@\f3a64l(3C)\f1 .\" index@convert between long integer and base-64 \s-1ASCII\s+1 string@@@\f3a64l(3C)\f1 .\" index@\s-1ASCII\s+1 string, convert between long integer and base-64@@@\f3a64l(3C)\f1 .\" index@string, convert between long integer and base-64 \s-1ASCII\s+1@@@\f3a64l(3C)\f1 .\" index@long integer to base-64 \s-1ASCII\s+1 string, convert@@@\f3a64l(3C)\f1 .\" index@integer to base-64 \s-1ASCII\s+1 string, convert long@@@\f3a64l(3C)\f1 .\" index@base-64 \s-1ASCII\s+1 string, convert long integer to@@@\f3a64l(3C)\f1 .\" .\" toc@\f3a64l(3C)\f1:\0\0\f4a64l()\f1, \f4l64a()\f1, \f4l64a_r()\f1@@@convert between long integer and base-64 \s-1ASCII\s+1 string .\" toc@\f2l64a\f1:\0\0convert between long integer and base-64 \s-1ASCII\s+1 string@@@see \f3a64l(3C)\f1 .\" toc@\f2l64a_r\f1:\0\0convert between long integer and base-64 \s-1ASCII\s+1 string@@@see \f3a64l(3X)\f1 .\" .\" links@a64l.3c l64a.3c .\" links@a64l.3c l64a_r.3c .\" .\" fileset_database@a64l.3c PROGRAMING-MAN .\" $Header: a64l.3c,v 72.5 94/11/14 11:59:22 ssa Exp $ .TA a .TH a64l 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME a64l(\|), l64a(\|), l64a_r(\|) \- convert between long integer and base-64 ASCII string .SH SYNOPSIS .C "#include " .PP .C "long int a64l(const char *s);" .PP .C "char *l64a(long int l);" .PP .C "int l64a_r(long int l, char *buffer, int buflen);" .SH DESCRIPTION These functions are used to maintain numbers stored in .I base-64 .SM ASCII characters. This is a notation by which long integers can be represented by up to six characters; each character represents a "digit" in a radix-64 notation. .PP The characters used to represent "digits" are .C . for 0, .C / for 1, .C 0 through .C 9 for 2\-11, .C A through .C Z for 12\-37, and .C a through .C z for 38\-63. .PP The leftmost character is the least significant digit. For example, .RS 15 .if n a0 = (38 x 64^0) + (2 x 64^1) = 166 .if t a0 = (38 x 64\u\s-20\s+2\d) + (2 x 64\u\s-21\s+2\d) = 166 .RE .PP .C a64l() takes a pointer to a null-terminated base-64 representation and returns a corresponding .C long value. If the string pointed to by .I s contains more than six characters, .C a64l() uses the first six. .PP .C l64a() takes a .C long argument and returns a pointer to the corresponding base-64 representation. If the argument is 0, .C l64a() returns a pointer to a null string. .SS Reentrant Interfaces .C l64a_r() passes the result string back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .SH WARNINGS The value returned by .C l64a() is a pointer into a static buffer, the contents of which are overwritten by each call. Thus, .C l64a() is unsafe in multi-thread applications. .C l64a_r() is MT-Safe and should be used instead. .SH STANDARDS CONFORMANCE .CR a64l() ": SVID2, SVID3" .PP .CR l64a() ": SVID2, SVID3" .\" .\" index@\f4a64l()\f1 \- convert base-64 value to long integer \s-1ASCII\s+1 string@@@\f3a64l(3C)\f1 .\" index@\f4l64a()\f1 \- convert long integer to base-64 value \s-1ASCII\s+1 string@@@\f3a64l(3C)\f1 .\" index@\f4l64a_r()\f1 \- convert between long integer and base-64 \s-1ASCII\s+1 string@@@\f3a64l(3C)\f1 .\" index@convert between long integer and base-64 \s-1ASCII\s+1 string@@@\f3a64l(3C)\f1 .\" index@\s-1ASCII\s+1 string, convert between long integer and base-64@@@\f3a64l(3C)\f1 .\" index@string, convert between long integer and base-64 \s-1ASCII\s+1@@@\f3a64l(3C)\f1 .\" index@long integer to base-64 \s-1ASCII\s+1 string, convert@@@\f3a64l(3C)\f1 .\" index@integer to base-64 \s-1ASCII\s+1 string, convert long@@@\f3a64l(3C)\f1 .\" index@base-64 \s-1ASCII\s+1 string, convert long integer to@@@\f3a64l(3C)\f1 .\" .\" toc@\f3a64l(3C)\f1:\0\0\f4a64l()\f1, \f4l64a()\f1, \f4l64a_r()\f1@@@convert between long integer and base-64 \s-1ASCII\s+1 string .\" toc@\f2l64a\f1:\0\0convert between long integer and base-64 \s-1ASCII\s+1 string@@@see \f3a64l(3C)\f1 .\" toc@\f2l64a_r\f1:\0\0convert between long integer and base-64 \s-1ASCII\s+1 string@@@see \f3a64l(3X)\f1 .\" .\" links@a64l.3c l64a.3c .\" links@a64l.3c l64a_r.3c .\" .\" fileset_database@a64l.3c PROGRAMING-MAN .\" $Header: abs.3c,v 72.4 94/11/14 11:59:52 ssa Exp $ .TA a .TH abs 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME abs(\|), labs(\|) \- return integer absolute value .SH SYNOPSIS .C "#include " .PP .C "int abs(int i);" .PP .C "long int labs(long int i);" .SH DESCRIPTION .C abs() returns the absolute value of its integer operand. .PP .C labs() is similar to .CR abs() , except that the argument and the returned value each have type long int. .PP The largest negative integer returns itself. .SH WARNINGS In two's-complement representation, the absolute value of the negative integer with largest magnitude is undefined. Some implementations trap this error, but others simply ignore it. .SH SEE ALSO floor(3M). .SH STANDARDS CONFORMANCE .CR abs() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR labs() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4abs()\f1, \f4labs()\f1 \- return integer absolute value@@@\f3abs(3C)\f1 .\" index@\f4labs()\f1 \- return long integer absolute value@@@\f3abs(3C)\f1 .\" index@return integer absolute value@@@\f3abs(3C)\f1 .\" index@integer absolute value, return@@@\f3abs(3C)\f1 .\" index@absolute value, return integer@@@\f3abs(3C)\f1 .\" index@value, return integer absolute@@@\f3abs(3C)\f1 .\" .\" toc@\f3abs(3C)\f1:\0\0\f4abs()\f1, \f4abs()\f1@@@return integer absolute value .\" .\" links@abs.3c labs.3c .\" .\" fileset_database@abs.3c PROGRAMING-MAN .\" $Header: lckpwdf.3c,v 72.2 94/07/03 11:05:08 ssa Exp $ .TA l .TH lckpwdf 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lckpwdf(), ulckpwdf() \- control access to /etc/passwd file .SH SYNOPSIS .C #include .br .C int lckpwdf (void) .br .C int ulckpwdf (void) .SH DESCRIPTION The .CR lckpwdf() and .CR ulckpwdf() routines are used to coordinate modification access to the password file .CR /etc/passwd and to the secure password entries. The lock file used by these two routines is .CR /etc/.pwd.lock . A process first calls .CR lckpwdf() to gain exclusive access rights for password modification. When modifications are complete, .CR ulckpwdf() is called to release the lock on .CR /etc/.pwd.lock . This mechanism prevents simultaneous modification of password files or entries. .SH RETURN VALUE The .CR lckpwdf() routine returns zero upon successful completion. If the lock could not be obtained, it returns \(mi1 and sets .CR errno to indicate the error. .PP The .CR ulckpwdf() routine returns zero upon successful completion. If the lock has already been released, .CR ulckpwdf() returns \(mi1 and sets .CR errno to indicate the error. .SH FILES .C /etc/passwd .br .C /etc/.pwd.lock .SH SEE ALSO getpwent(3C), passwd(4). .\" toc@\f3lckpwdf(3C)\f1:\0\0f4lckpwdf()\f1, \f4ulckpwdf()\f1@@@control access to /etc/passwd file\f1 .\" toc@\f3ulckpwdf()\f1:\0\0unlock access to /etc/passwd file@@@\f1see \f3lckpwd(3C)\f1 .\" .\" index@\f4lckpwdf()\f1 \- control access to /etc/passwd file@@@\f3lckpwdf(3C)\f1 .\" index@\f4ulckpwdf()\f1 \- control access to /etc/passwd file@@@\f3lckpwdf(3C)\f1 .\" index@\f1access to /etc/passwd file, control@@@\f3lckpwdf(3C)\f1 .\" index@\f1lock access to /etc/passwd file@@@\f3lckpwdf(3C)\f1 .\" index@\f1unlock access to /etc/passwd file@@@\f3lckpwdf(3C)\f1 .\" .\" links@lckpwdf.3c ulckpwdf.3c .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\"$Header: ldcvt.3c,v 72.5 94/09/06 15:04:08 ssa Exp $ .TA l .TH ldcvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _ldecvt(\|), _ldecvt_r(\|), _ldfcvt(\|), _ldfcvt_r(\|), _ldgcvt(\|) \- convert long-double floating-point number to string .SH SYNOPSIS .nf .C "#include " .PP .C "char\0*_ldecvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldecvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldfcvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldfcvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldgcvt(long_double\0value,\0int\0ndigit,\0char\0*buf);" .SH DESCRIPTION .TP 15 .C _ldecvt() converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero; otherwise it is zero. .TP .C _ldecvt_r() is identical to .CR _ldecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldfcvt() is identical to .CR _ldecvt() , except that the correct digit has been rounded for printf .C %Lf (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C _ldfcvt_r() is identical to .CR _ldfcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldgcvt() Convert the .I value to a null-terminated string in the array pointed to by .I buf and return .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character are included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C" is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH RETURN VALUE .C NaN is returned for Not-a-Number, and .C \(+-INFINITY is returned for Infinity. .SH WARNINGS The values returned by .C _ldecvt() and .C _ldfcvt() point to a single static-data array whose content is overwritten by each call. .PP .C _ldecvt() and .C _ldfcvt() are unsafe in multi-thread applications. .C _ldecvt_r() and .C _ldfcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR _ldecvt() , .CR _ldfcvt() , and .C _ldgcvt() were developed by HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the radix character. .SS International Code Set Support Single-byte character code sets are supported. .\" .\" index@\f4ldecvt()\fP, (\f4_ldecvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldfcvt()\fP, (\f4_ldfcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldgcvt()\fP, (\f4_ldgcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1 \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@convert long double floating-point number to string@@@\f3ldcvt(3C)\f1 .\" index@long double floating-point number to string, convert@@@\f3ldcvt(3C)\f1 .\" index@floating-point number to string, convert long double@@@\f3ldcvt(3C)\f1 .\" index@number to string, convert long double floating-point@@@\f3ldcvt(3C)\f1 .\" index@string, convert long double floating-point number to@@@\f3ldcvt(3C)\f1 .\" .\" toc@\f3ldcvt(3C)\f1:\0\0\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1@@@convert long double floating-point number to string .\" toc@\f4ldecvt()\fP (\f4_ldecvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldfcvt()\fP (\f4_ldfcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldgcvt()\fP (\f4_ldgcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldecvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldfcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldgcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" .\" links@ldcvt.3c _ldecvt.3c .\" links@ldcvt.3c _ldecvt_r.3c .\" links@ldcvt.3c _ldfcvt.3c .\" links@ldcvt.3c _ldfcvt_r.3c .\" links@ldcvt.3c _ldgcvt.3c .\" links@ldcvt.3c _ldgcvt_r.3c .\" links@ldcvt.3c ldecvt.3c .\" links@ldcvt.3c ldecvt_r.3c .\" links@ldcvt.3c ldfcvt.3c .\" links@ldcvt.3c ldfcvt_r.3c .\" links@ldcvt.3c ldgcvt.3c .\" links@ldcvt.3c ldgcvt_r.3c .\"$Header: ldcvt.3c,v 72.5 94/09/06 15:04:08 ssa Exp $ .TA l .TH ldcvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _ldecvt(\|), _ldecvt_r(\|), _ldfcvt(\|), _ldfcvt_r(\|), _ldgcvt(\|) \- convert long-double floating-point number to string .SH SYNOPSIS .nf .C "#include " .PP .C "char\0*_ldecvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldecvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldfcvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldfcvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldgcvt(long_double\0value,\0int\0ndigit,\0char\0*buf);" .SH DESCRIPTION .TP 15 .C _ldecvt() converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero; otherwise it is zero. .TP .C _ldecvt_r() is identical to .CR _ldecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldfcvt() is identical to .CR _ldecvt() , except that the correct digit has been rounded for printf .C %Lf (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C _ldfcvt_r() is identical to .CR _ldfcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldgcvt() Convert the .I value to a null-terminated string in the array pointed to by .I buf and return .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character are included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C" is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH RETURN VALUE .C NaN is returned for Not-a-Number, and .C \(+-INFINITY is returned for Infinity. .SH WARNINGS The values returned by .C _ldecvt() and .C _ldfcvt() point to a single static-data array whose content is overwritten by each call. .PP .C _ldecvt() and .C _ldfcvt() are unsafe in multi-thread applications. .C _ldecvt_r() and .C _ldfcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR _ldecvt() , .CR _ldfcvt() , and .C _ldgcvt() were developed by HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the radix character. .SS International Code Set Support Single-byte character code sets are supported. .\" .\" index@\f4ldecvt()\fP, (\f4_ldecvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldfcvt()\fP, (\f4_ldfcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldgcvt()\fP, (\f4_ldgcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1 \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@convert long double floating-point number to string@@@\f3ldcvt(3C)\f1 .\" index@long double floating-point number to string, convert@@@\f3ldcvt(3C)\f1 .\" index@floating-point number to string, convert long double@@@\f3ldcvt(3C)\f1 .\" index@number to string, convert long double floating-point@@@\f3ldcvt(3C)\f1 .\" index@string, convert long double floating-point number to@@@\f3ldcvt(3C)\f1 .\" .\" toc@\f3ldcvt(3C)\f1:\0\0\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1@@@convert long double floating-point number to string .\" toc@\f4ldecvt()\fP (\f4_ldecvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldfcvt()\fP (\f4_ldfcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldgcvt()\fP (\f4_ldgcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldecvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldfcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldgcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" .\" links@ldcvt.3c _ldecvt.3c .\" links@ldcvt.3c _ldecvt_r.3c .\" links@ldcvt.3c _ldfcvt.3c .\" links@ldcvt.3c _ldfcvt_r.3c .\" links@ldcvt.3c _ldgcvt.3c .\" links@ldcvt.3c _ldgcvt_r.3c .\" links@ldcvt.3c ldecvt.3c .\" links@ldcvt.3c ldecvt_r.3c .\" links@ldcvt.3c ldfcvt.3c .\" links@ldcvt.3c ldfcvt_r.3c .\" links@ldcvt.3c ldgcvt.3c .\" links@ldcvt.3c ldgcvt_r.3c .\"$Header: ldcvt.3c,v 72.5 94/09/06 15:04:08 ssa Exp $ .TA l .TH ldcvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _ldecvt(\|), _ldecvt_r(\|), _ldfcvt(\|), _ldfcvt_r(\|), _ldgcvt(\|) \- convert long-double floating-point number to string .SH SYNOPSIS .nf .C "#include " .PP .C "char\0*_ldecvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldecvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldfcvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldfcvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldgcvt(long_double\0value,\0int\0ndigit,\0char\0*buf);" .SH DESCRIPTION .TP 15 .C _ldecvt() converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero; otherwise it is zero. .TP .C _ldecvt_r() is identical to .CR _ldecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldfcvt() is identical to .CR _ldecvt() , except that the correct digit has been rounded for printf .C %Lf (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C _ldfcvt_r() is identical to .CR _ldfcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldgcvt() Convert the .I value to a null-terminated string in the array pointed to by .I buf and return .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character are included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C" is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH RETURN VALUE .C NaN is returned for Not-a-Number, and .C \(+-INFINITY is returned for Infinity. .SH WARNINGS The values returned by .C _ldecvt() and .C _ldfcvt() point to a single static-data array whose content is overwritten by each call. .PP .C _ldecvt() and .C _ldfcvt() are unsafe in multi-thread applications. .C _ldecvt_r() and .C _ldfcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR _ldecvt() , .CR _ldfcvt() , and .C _ldgcvt() were developed by HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the radix character. .SS International Code Set Support Single-byte character code sets are supported. .\" .\" index@\f4ldecvt()\fP, (\f4_ldecvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldfcvt()\fP, (\f4_ldfcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldgcvt()\fP, (\f4_ldgcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1 \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@convert long double floating-point number to string@@@\f3ldcvt(3C)\f1 .\" index@long double floating-point number to string, convert@@@\f3ldcvt(3C)\f1 .\" index@floating-point number to string, convert long double@@@\f3ldcvt(3C)\f1 .\" index@number to string, convert long double floating-point@@@\f3ldcvt(3C)\f1 .\" index@string, convert long double floating-point number to@@@\f3ldcvt(3C)\f1 .\" .\" toc@\f3ldcvt(3C)\f1:\0\0\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1@@@convert long double floating-point number to string .\" toc@\f4ldecvt()\fP (\f4_ldecvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldfcvt()\fP (\f4_ldfcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldgcvt()\fP (\f4_ldgcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldecvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldfcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldgcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" .\" links@ldcvt.3c _ldecvt.3c .\" links@ldcvt.3c _ldecvt_r.3c .\" links@ldcvt.3c _ldfcvt.3c .\" links@ldcvt.3c _ldfcvt_r.3c .\" links@ldcvt.3c _ldgcvt.3c .\" links@ldcvt.3c _ldgcvt_r.3c .\" links@ldcvt.3c ldecvt.3c .\" links@ldcvt.3c ldecvt_r.3c .\" links@ldcvt.3c ldfcvt.3c .\" links@ldcvt.3c ldfcvt_r.3c .\" links@ldcvt.3c ldgcvt.3c .\" links@ldcvt.3c ldgcvt_r.3c .\" $Header: ldexp.3m,v 78.2 96/02/13 12:31:22 ssa Exp $ .TA l .TH ldexp 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ldexp(\|) \- load exponent of a floating-point number .SH SYNOPSIS .C "#include " .PP .C "double ldexp(double x, int exp);" .SH DESCRIPTION The .CR ldexp() function computes the quantity .ift .IR x\| "\(** 2" \u\s-2exp\s+2\d . .ifn .IR x " \(** (2**" exp ). .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE Upon successful completion, the .CR ldexp() function returns a .CR double representing the value .I x multiplied by 2 raised to the power .IR exp . .PP If .I x is NaN, .CR ldexp() returns NaN. .PP If the correct value would overflow, .CR ldexp() returns .ift .CR \(+-HUGE_VAL .ifn .CR +\-HUGE_VAL (according to the sign of .IR x ) and sets .CR errno to [ERANGE]. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR ldexp() returns zero and sets .CR errno to [ERANGE]. .SH "ERRORS" If .CR ldexp() fails, .CR errno is set to one of the following values. .RS .TP 20 [ERANGE] The correct value would overflow. .TP 20 [ERANGE] The correct value after rounding would be smaller in magnitude than .CR MINDOUBLE . .RE .SH "SEE ALSO" frexp(3M), isinf(3M), isnan(3M), modf(3M), scalb(3M), values(5). .SH STANDARDS CONFORMANCE .CR ldexp() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4ldexp\f1 \- load exponent of a floating-point number@@@\f3ldexp(3M)\f1 .\" index@\f1math: load exponent of a floating-point number@@@\f3ldexp(3M)\f1 .\" index@\f1load exponent of a floating-point number@@@\f3ldexp(3M)\f1 .\" index@\f1floating-point number, load exponent of a@@@\f3ldexp(3M)\f1 .\" index@\f1exponent of a floating-point number, load@@@\f3ldexp(3M)\f1 .\" .\" toc@\f3ldexp(3M)\f1:\0\0f4scalb()\f1@@@load exponent of a floating-point number .\"$Header: ldcvt.3c,v 72.5 94/09/06 15:04:08 ssa Exp $ .TA l .TH ldcvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _ldecvt(\|), _ldecvt_r(\|), _ldfcvt(\|), _ldfcvt_r(\|), _ldgcvt(\|) \- convert long-double floating-point number to string .SH SYNOPSIS .nf .C "#include " .PP .C "char\0*_ldecvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldecvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldfcvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldfcvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldgcvt(long_double\0value,\0int\0ndigit,\0char\0*buf);" .SH DESCRIPTION .TP 15 .C _ldecvt() converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero; otherwise it is zero. .TP .C _ldecvt_r() is identical to .CR _ldecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldfcvt() is identical to .CR _ldecvt() , except that the correct digit has been rounded for printf .C %Lf (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C _ldfcvt_r() is identical to .CR _ldfcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldgcvt() Convert the .I value to a null-terminated string in the array pointed to by .I buf and return .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character are included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C" is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH RETURN VALUE .C NaN is returned for Not-a-Number, and .C \(+-INFINITY is returned for Infinity. .SH WARNINGS The values returned by .C _ldecvt() and .C _ldfcvt() point to a single static-data array whose content is overwritten by each call. .PP .C _ldecvt() and .C _ldfcvt() are unsafe in multi-thread applications. .C _ldecvt_r() and .C _ldfcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR _ldecvt() , .CR _ldfcvt() , and .C _ldgcvt() were developed by HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the radix character. .SS International Code Set Support Single-byte character code sets are supported. .\" .\" index@\f4ldecvt()\fP, (\f4_ldecvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldfcvt()\fP, (\f4_ldfcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldgcvt()\fP, (\f4_ldgcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1 \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@convert long double floating-point number to string@@@\f3ldcvt(3C)\f1 .\" index@long double floating-point number to string, convert@@@\f3ldcvt(3C)\f1 .\" index@floating-point number to string, convert long double@@@\f3ldcvt(3C)\f1 .\" index@number to string, convert long double floating-point@@@\f3ldcvt(3C)\f1 .\" index@string, convert long double floating-point number to@@@\f3ldcvt(3C)\f1 .\" .\" toc@\f3ldcvt(3C)\f1:\0\0\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1@@@convert long double floating-point number to string .\" toc@\f4ldecvt()\fP (\f4_ldecvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldfcvt()\fP (\f4_ldfcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldgcvt()\fP (\f4_ldgcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldecvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldfcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldgcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" .\" links@ldcvt.3c _ldecvt.3c .\" links@ldcvt.3c _ldecvt_r.3c .\" links@ldcvt.3c _ldfcvt.3c .\" links@ldcvt.3c _ldfcvt_r.3c .\" links@ldcvt.3c _ldgcvt.3c .\" links@ldcvt.3c _ldgcvt_r.3c .\" links@ldcvt.3c ldecvt.3c .\" links@ldcvt.3c ldecvt_r.3c .\" links@ldcvt.3c ldfcvt.3c .\" links@ldcvt.3c ldfcvt_r.3c .\" links@ldcvt.3c ldgcvt.3c .\" links@ldcvt.3c ldgcvt_r.3c .\"$Header: ldcvt.3c,v 72.5 94/09/06 15:04:08 ssa Exp $ .TA l .TH ldcvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _ldecvt(\|), _ldecvt_r(\|), _ldfcvt(\|), _ldfcvt_r(\|), _ldgcvt(\|) \- convert long-double floating-point number to string .SH SYNOPSIS .nf .C "#include " .PP .C "char\0*_ldecvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldecvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldfcvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldfcvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldgcvt(long_double\0value,\0int\0ndigit,\0char\0*buf);" .SH DESCRIPTION .TP 15 .C _ldecvt() converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero; otherwise it is zero. .TP .C _ldecvt_r() is identical to .CR _ldecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldfcvt() is identical to .CR _ldecvt() , except that the correct digit has been rounded for printf .C %Lf (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C _ldfcvt_r() is identical to .CR _ldfcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldgcvt() Convert the .I value to a null-terminated string in the array pointed to by .I buf and return .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character are included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C" is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH RETURN VALUE .C NaN is returned for Not-a-Number, and .C \(+-INFINITY is returned for Infinity. .SH WARNINGS The values returned by .C _ldecvt() and .C _ldfcvt() point to a single static-data array whose content is overwritten by each call. .PP .C _ldecvt() and .C _ldfcvt() are unsafe in multi-thread applications. .C _ldecvt_r() and .C _ldfcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR _ldecvt() , .CR _ldfcvt() , and .C _ldgcvt() were developed by HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the radix character. .SS International Code Set Support Single-byte character code sets are supported. .\" .\" index@\f4ldecvt()\fP, (\f4_ldecvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldfcvt()\fP, (\f4_ldfcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldgcvt()\fP, (\f4_ldgcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1 \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@convert long double floating-point number to string@@@\f3ldcvt(3C)\f1 .\" index@long double floating-point number to string, convert@@@\f3ldcvt(3C)\f1 .\" index@floating-point number to string, convert long double@@@\f3ldcvt(3C)\f1 .\" index@number to string, convert long double floating-point@@@\f3ldcvt(3C)\f1 .\" index@string, convert long double floating-point number to@@@\f3ldcvt(3C)\f1 .\" .\" toc@\f3ldcvt(3C)\f1:\0\0\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1@@@convert long double floating-point number to string .\" toc@\f4ldecvt()\fP (\f4_ldecvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldfcvt()\fP (\f4_ldfcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldgcvt()\fP (\f4_ldgcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldecvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldfcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldgcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" .\" links@ldcvt.3c _ldecvt.3c .\" links@ldcvt.3c _ldecvt_r.3c .\" links@ldcvt.3c _ldfcvt.3c .\" links@ldcvt.3c _ldfcvt_r.3c .\" links@ldcvt.3c _ldgcvt.3c .\" links@ldcvt.3c _ldgcvt_r.3c .\" links@ldcvt.3c ldecvt.3c .\" links@ldcvt.3c ldecvt_r.3c .\" links@ldcvt.3c ldfcvt.3c .\" links@ldcvt.3c ldfcvt_r.3c .\" links@ldcvt.3c ldgcvt.3c .\" links@ldcvt.3c ldgcvt_r.3c .\"$Header: ldcvt.3c,v 72.5 94/09/06 15:04:08 ssa Exp $ .TA l .TH ldcvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _ldecvt(\|), _ldecvt_r(\|), _ldfcvt(\|), _ldfcvt_r(\|), _ldgcvt(\|) \- convert long-double floating-point number to string .SH SYNOPSIS .nf .C "#include " .PP .C "char\0*_ldecvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldecvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldfcvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldfcvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldgcvt(long_double\0value,\0int\0ndigit,\0char\0*buf);" .SH DESCRIPTION .TP 15 .C _ldecvt() converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero; otherwise it is zero. .TP .C _ldecvt_r() is identical to .CR _ldecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldfcvt() is identical to .CR _ldecvt() , except that the correct digit has been rounded for printf .C %Lf (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C _ldfcvt_r() is identical to .CR _ldfcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldgcvt() Convert the .I value to a null-terminated string in the array pointed to by .I buf and return .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character are included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C" is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH RETURN VALUE .C NaN is returned for Not-a-Number, and .C \(+-INFINITY is returned for Infinity. .SH WARNINGS The values returned by .C _ldecvt() and .C _ldfcvt() point to a single static-data array whose content is overwritten by each call. .PP .C _ldecvt() and .C _ldfcvt() are unsafe in multi-thread applications. .C _ldecvt_r() and .C _ldfcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR _ldecvt() , .CR _ldfcvt() , and .C _ldgcvt() were developed by HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the radix character. .SS International Code Set Support Single-byte character code sets are supported. .\" .\" index@\f4ldecvt()\fP, (\f4_ldecvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldfcvt()\fP, (\f4_ldfcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldgcvt()\fP, (\f4_ldgcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1 \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@convert long double floating-point number to string@@@\f3ldcvt(3C)\f1 .\" index@long double floating-point number to string, convert@@@\f3ldcvt(3C)\f1 .\" index@floating-point number to string, convert long double@@@\f3ldcvt(3C)\f1 .\" index@number to string, convert long double floating-point@@@\f3ldcvt(3C)\f1 .\" index@string, convert long double floating-point number to@@@\f3ldcvt(3C)\f1 .\" .\" toc@\f3ldcvt(3C)\f1:\0\0\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1@@@convert long double floating-point number to string .\" toc@\f4ldecvt()\fP (\f4_ldecvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldfcvt()\fP (\f4_ldfcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldgcvt()\fP (\f4_ldgcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldecvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldfcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldgcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" .\" links@ldcvt.3c _ldecvt.3c .\" links@ldcvt.3c _ldecvt_r.3c .\" links@ldcvt.3c _ldfcvt.3c .\" links@ldcvt.3c _ldfcvt_r.3c .\" links@ldcvt.3c _ldgcvt.3c .\" links@ldcvt.3c _ldgcvt_r.3c .\" links@ldcvt.3c ldecvt.3c .\" links@ldcvt.3c ldecvt_r.3c .\" links@ldcvt.3c ldfcvt.3c .\" links@ldcvt.3c ldfcvt_r.3c .\" links@ldcvt.3c ldgcvt.3c .\" links@ldcvt.3c ldgcvt_r.3c .\"$Header: ldcvt.3c,v 72.5 94/09/06 15:04:08 ssa Exp $ .TA l .TH ldcvt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _ldecvt(\|), _ldecvt_r(\|), _ldfcvt(\|), _ldfcvt_r(\|), _ldgcvt(\|) \- convert long-double floating-point number to string .SH SYNOPSIS .nf .C "#include " .PP .C "char\0*_ldecvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldecvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldfcvt(long_double\0value,\0int\0ndigit,\0int\0*decpt,\0int\0*sign);" .PP .C "int _ldfcvt_r(" .PD 0 .IP .C "long_double value," .C "int ndigit," .C "int *decpt," .C "int *sign," .C "char *buffer," .C "int buflen);" .PD .PP .C "char\0*_ldgcvt(long_double\0value,\0int\0ndigit,\0char\0*buf);" .SH DESCRIPTION .TP 15 .C _ldecvt() converts .I value to a null-terminated string of .I ndigit digits and returns a pointer to the string. The high-order digit is non-zero, unless the value is zero. The low-order digit is rounded. The position of the radix character relative to the beginning of the string is stored indirectly through .I decpt (negative means to the left of the returned digits). The radix character is not included in the returned string. If the sign of the result is negative, the word pointed to by .I sign is non-zero; otherwise it is zero. .TP .C _ldecvt_r() is identical to .CR _ldecvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldfcvt() is identical to .CR _ldecvt() , except that the correct digit has been rounded for printf .C %Lf (F\s-2ORTRAN\s0 F-format) output of the number of digits specified by .IR ndigit . .TP .C _ldfcvt_r() is identical to .CR _ldfcvt() , except that the result string is passed back in the supplied buffer. If the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .TP .C _ldgcvt() Convert the .I value to a null-terminated string in the array pointed to by .I buf and return .IR buf . It produces .I ndigit significant digits in F\s-2ORTRAN\s0 F-format if possible, or E-format otherwise. A minus sign, if required, and a radix character are included in the returned string. Trailing zeros are suppressed. The radix character is determined by the currently loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C" is used (see .IR lang (5)). The default environment specifies a period .RC ( . ) as the radix character. .SH RETURN VALUE .C NaN is returned for Not-a-Number, and .C \(+-INFINITY is returned for Infinity. .SH WARNINGS The values returned by .C _ldecvt() and .C _ldfcvt() point to a single static-data array whose content is overwritten by each call. .PP .C _ldecvt() and .C _ldfcvt() are unsafe in multi-thread applications. .C _ldecvt_r() and .C _ldfcvt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR _ldecvt() , .CR _ldfcvt() , and .C _ldgcvt() were developed by HP. .SH SEE ALSO setlocale(3C), printf(3S), hpnls(5), lang(5). .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the radix character. .SS International Code Set Support Single-byte character code sets are supported. .\" .\" index@\f4ldecvt()\fP, (\f4_ldecvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldfcvt()\fP, (\f4_ldfcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4ldgcvt()\fP, (\f4_ldgcvt()\f1) \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1 \- convert long double to string@@@\f3ldcvt(3C)\f1 .\" index@convert long double floating-point number to string@@@\f3ldcvt(3C)\f1 .\" index@long double floating-point number to string, convert@@@\f3ldcvt(3C)\f1 .\" index@floating-point number to string, convert long double@@@\f3ldcvt(3C)\f1 .\" index@number to string, convert long double floating-point@@@\f3ldcvt(3C)\f1 .\" index@string, convert long double floating-point number to@@@\f3ldcvt(3C)\f1 .\" .\" toc@\f3ldcvt(3C)\f1:\0\0\f4_ldecvt()\f1, \f4_ldfcvt()\f1, \f4_ldgcvt()\f1@@@convert long double floating-point number to string .\" toc@\f4ldecvt()\fP (\f4_ldecvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldfcvt()\fP (\f4_ldfcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4ldgcvt()\fP (\f4_ldgcvt()\f1) \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldecvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldfcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" toc@\f4_ldgcvt()\f1 \- convert long double floating-point number to string@@@see \f3ldcvt(3C)\f1 .\" .\" links@ldcvt.3c _ldecvt.3c .\" links@ldcvt.3c _ldecvt_r.3c .\" links@ldcvt.3c _ldfcvt.3c .\" links@ldcvt.3c _ldfcvt_r.3c .\" links@ldcvt.3c _ldgcvt.3c .\" links@ldcvt.3c _ldgcvt_r.3c .\" links@ldcvt.3c ldecvt.3c .\" links@ldcvt.3c ldecvt_r.3c .\" links@ldcvt.3c ldfcvt.3c .\" links@ldcvt.3c ldfcvt_r.3c .\" links@ldcvt.3c ldgcvt.3c .\" links@ldcvt.3c ldgcvt_r.3c .\" $Header: div.3c,v 72.4 94/11/14 15:27:43 ssa Exp $ .TA d .TH div 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME div(\|), ldiv(\|) \- integer division and remainder .SH SYNOPSIS .C "#include " .PP .C "div_t div(int numer, int denom);" .PP .C "ldiv_t ldiv(long int numer, long int denom);" .SH DESCRIPTION .TP 15 .C div() Computes the quotient and remainder of the division of the numerator .I numer by the denominator .IR denom . If the division is inexact, the sign of the resulting quotient is that of the algebraic quotient, and the magnitude of the resulting quotient is the largest integer less than the magnitude of the algebraic quotient. If the result can be represented, the result is returned in a structure of type .C div_t (defined in .RC < stdlib.h >) having members .I quot and .I rem for the quotient and remainder respectively. Both members have type .C int and values such that .IR "quot \(mu denom + rem = numer" . If the result cannot be represented, the behavior is undefined. .TP .C ldiv() Similar to .CR div() , except that the arguments each have type .C long int and the result is returned in a structure of type .C ldiv_t (defined in .RC < stdlib.h >) having .C long int members .I quot and .I rem for the quotient and remainder respectively. .SH WARNINGS Behavior is undefined if .I denom is zero. .SH SEE ALSO floor(3M). .SH STANDARDS CONFORMANCE .CR div() ": AES, SVID3, XPG4, ANSI C" .PP .CR ldiv() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4div()\fP, \f4ldiv()\fP \- integer division and remainder@@@\f3div(3C)\f1 .\" index@\f4ldiv()\fP \- long integer division and remainder@@@\f3div(3C)\f1 .\" index@integer division and remainder@@@\f3div(3C)\f1 .\" index@division and remainder, integer@@@\f3div(3C)\f1 .\" index@remainder, integer division and@@@\f3div(3C)\f1 .\" .\" toc@\f3div(3C)\f1:\0\0\f4div()\fP, \f4ldiv()\fP@@@integer division and remainder .\" toc@\f4ldiv()\fP: long integer division and remainder@@@see \f3div(3C)\f1 .\" .\" links@div.3c ldiv.3c .\" .\" fileset_database@div.3c PROGRAMING-MAN .\" $Header: clearok.3x,v 76.2 95/07/31 17:25:47 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH clearok 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clearok, idlok, leaveok, scrollok, setscrreg, wsetscrreg \(em terminal output control functions .SH SYNOPSIS .C "#include " .P .C "int clearok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int idlok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int leaveok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int scrollok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int setscrreg(int \f2top\fP, int \f2bot\fP);" .P .C "int wsetscrreg(WINDOW *\f2win\fP, int \f2top\fP, int \f2bot\fP);" .SH DESCRIPTION These functions set options that deal with output within Curses. .P The .Fn clearok function assigns the value of .I bf to an internal flag in the specified window that governs clearing of the screen during a refresh. If, during a refresh operation on the specified window, the flag in .I curscr is TRUE or the flag in the specified window is TRUE, then the implementation clears the screen, redraws it in its entirety, and sets the flag to FALSE in .I curscr and in the specified window. The initial state is unspecified. .P The .Fn idlok function specifies whether the implementation may use the hardware insert-line, delete-line, and scroll features of terminals so equipped. If \f2bf\f1 is TRUE, use of these features is enabled. If \f2bf\f1 is FALSE, use of these features is disabled and lines are instead redrawn as required. The initial state is FALSE. .P The .Fn leaveok function controls the cursor position after a refresh operation. If \f2bf\f1 is TRUE, refresh operations on the specified window may leave the terminal's cursor at an arbitrary position. If \f2bf\f1 is FALSE, then at the end of any refresh operation, the terminal's cursor is positioned at the cursor position contained in the specified window. The initial state is FALSE. .P The .Fn scrollok function controls the use of scrolling. If \f2bf\f1 is TRUE, then scrolling is enabled for the specified window, with the consequences discussed in \f3Truncation, Wrapping and Scrolling\f1 in curses_intro. If \f2bf\f1 is FALSE, scrolling is disabled for the specified window. The initial state is FALSE. .P The .Fn setscrreg and .Fn wsetscrreg functions define a software scrolling region in the current or specified window. The \f2top\f1 and \f2bot\f1 arguments are the line numbers of the first and last line defining the scrolling region. (Line 0 is the top line of the window.) If this option and .Fn scrollok are enabled, an attempt to move off the last line of the margin causes all lines in the scrolling region to scroll one line in the direction of the first line. Only characters in the window are scrolled. If a software scrolling region is set and .Fn scrollok is not enabled, an attempt to move off the last line of the margin does not reposition any lines in the scrolling region. .SH "RETURN VALUE" Upon successful completion, .Fn setscrreg and .Fn wsetscrreg return OK. Otherwise, they return ERR. .P The other functions always return OK. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The only reason to enable the .Fn idlok feature is to use scrolling to achieve the visual effect of motion of a partial window, such as for a screen editor. In other cases, the feature can be visually annoying. .P The .Fn leaveok option provides greater efficiency for applications that do not use the cursor. .SH "SEE ALSO" clear(), delscreen(), doupdate(), scrl(), . .SS "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .CR idlok() , .CR leaveok() , .CR scrollok() , .Fn setscrreq and .Fn wsetscrreq functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The .B DESCRIPTION of .Fn clearok is updated to indicate that clearing of a screen applies if the flag is TRUE in either \f2curscr\f1 or the specified window. .P The .B "RETURN VALUE" is changed to indicate that the .CR clearok() , .Fn leaveok and .Fn scrollok functions always return OK. .\" .\" toc@\f3clearok(3X)\f1:\0\0\f4clearok()\f1, \f4idleok()\f1, \f4leaveok()\f1, \f4scrollok()\f1, \f4setscrreg()\f1, \f4wsetscrreg()\f1\n@@@terminal output control functions .\" toc@\f4idleok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4leaveok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4scrollok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4setscrreg()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4wsetscrreg()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" index@\f4clearok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4idleok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4leaveok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4scrollok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4setscrreg()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4wsetscrreg()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f1terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f1output, terminal, control functions@@@\f3clearok(3X)\f1 .\" index@\f1control functions, terminal output@@@\f3clearok(3X)\f1 .\" .\" links@clearok.3x idleok.3x .\" links@clearok.3x leaveok.3x .\" links@clearok.3x scrollok.3x .\" links@clearok.3x setscrreg.3x .\" links@clearok.3x wsetscrreg.3x .\" .\" fileset_database@clearok.3x CURS-ENG-A-MAN .\" $Header: lsearch.3c,v 72.4 94/11/15 09:55:16 ssa Exp $ .TA l .TH lsearch 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lsearch(\|), lfind(\|) \- linear search and update .SH SYNOPSIS .C "#include " .PP .C "void *lsearch(" .PD 0 .nf .IP .C "const void *key," .C "void *base," .C "size_t *nelp," .C "size_t width," .C "int (*compar)(const void *, const void *)" .P .C ");" .PD .fi .PP .C "void *lfind(" .PD 0 .nf .IP .C "const void *key," .C "const void *base," .C "size_t *nelp," .C "size_t width," .C "int (*compar)(const void *, const void *)" .P .C ");" .PD .fi .SH DESCRIPTION .TP 15 .C lsearch() is a linear search routine generalized from Knuth (6.1) Algorithm S. It returns a pointer into a table indicating where a datum may be found. If the datum does not occur, it is added at the end of the table. .RS .RS .TP 15 .I key Points to the datum to be sought in the table. .TP .I base Points to the first element in the table. .TP .I nelp Points to an integer containing the current number of elements in the table. The integer is incremented if the datum is added to the table. .TP .I compar Name of the comparison function which the user must supply .RC ( strcmp() , for example). It is called with two arguments that point to the elements being compared. The function must return zero if the elements are equal and non-zero otherwise. .RE .RE .TP .C lfind() Same as .C lsearch() except that if the datum is not found, it is not added to the table. Instead, a .SM NULL pointer is returned. .SS Notes The pointers to the key and the element at the base of the table should be of type pointer-to-element, and cast to type pointer-to-character. .PP The comparison function need not compare every byte, so arbitrary data may be contained in the elements in addition to the values being compared. .PP Although declared as type pointer-to-character, the value returned should be cast into type pointer-to-element. .SH EXAMPLES This code fragment reads in \(<= .C TABSIZE strings of length \(<= .C ELSIZE and stores them in a table, eliminating duplicates. .nf .IP .C #include .C #define TABSIZE 50 .C #define ELSIZE 120 .C " char line[ELSIZE], tab[TABSIZE][ELSIZE], *lsearch( );" .C " unsigned nel = 0;" .C " int strcmp( );" \h'.6i'.\|.\|. .C " while (fgets(line, ELSIZE, stdin) != NULL &&" .C " nel < TABSIZE)" .C " (void) lsearch(line, (char *)tab, &nel," .C " ELSIZE, strcmp);" \h'.6i'.\|.\|. .fi .SH SEE ALSO bsearch(3C), hsearch(3C), tsearch(3C). .SH RETURN VALUE If the searched-for datum is found, both .C lsearch() and .C lfind() return a pointer to it. Otherwise, .C lfind() returns NULL and .C lsearch() returns a pointer to the newly added element. .SH WARNINGS Undefined results can occur if there is not enough room in the table to add a new item. .SH STANDARDS CONFORMANCE .CR lsearch() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lfind() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4lsearch()\fP, \f4lfind()\fP \- linear search and update@@@\f3lsearch(3C)\f1 .\" index@linear table search with optional update@@@\f3lsearch(3C)\f1 .\" index@search table for entry; optional update if missing@@@\f3lsearch(3C)\f1 .\" index@table, eliminate duplicate entries in a@@@\f3lsearch(3C)\f1 .\" index@table, linear search for entry; optional update if missing@@@\f3lsearch(3C)\f1 .\" index@update table if entry missing after search@@@\f3lsearch(3C)\f1 .\" index@eliminate duplicate entries in a table@@@\f3lsearch(3C)\f1 .\" index@duplicate entries in a table, eliminate@@@\f3lsearch(3C)\f1 .\" index@entries in a table, eliminate duplicate@@@\f3lsearch(3C)\f1 .\" .\" toc@\f3lsearch(3C)\f1:\0\0\f4lsearch()\fP, \f4lfind()\fP@@@linear search and update .\" toc@\f4lfind()\fP:\0\0linear search and update@@@see \f3lsearch(3C)\f1 .\" .\" links@lsearch.3c lfind.3c .\" .\" fileset_database@lsearch.3c PROGRAMING-MAN .\" $Header: lgamma.3m,v 78.1 96/02/13 12:44:15 ssa Exp $ .TA l .TH lgamma 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lgamma(\|), lgamma_r(\|), gamma(\|), signgam(\|) \- log gamma function .SH SYNOPSIS .C "#include " .PP .C "double lgamma(double x);" .PP .C "double gamma(double x);" .PP .C "extern int signgam;" .PP .C "double lgamma_r(double x, int *sign); .SH DESCRIPTION .CR lgamma() and .CR gamma() return .ifn \{\ .CI ln(|Gamma( x )|)\c\} .ift \{\ .CI ln(|\(*G( x )|)\c\} , where .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} is defined as the integral, as .I t goes from zero to infinity, of .CI exp(\(mi t ) times .I t to the power .RI ( x \(mi1). .PP The sign of .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} is returned in the external integer .CR signgam . The argument .I x must not be zero or a negative integer. .RC ( lgamma() is defined over the reals excluding the non-positive integers.) .PP The following C program fragment can be used to calculate .ifn \{\ .RI Gamma( x ):\} .ift \{\ .RI \(*G( x ):\} .nf .IP .CR "if ((y = lgamma(x)) > LN_MAXDOUBLE)" .CR " error(\|);" .CR "y = signgam * exp(y);" .fi .PP where if .I y is greater than .CR LN_MAXDOUBLE , as defined in the .RC < values.h > header file, .CR exp() returns a range error (see .IR exp (3M)). .PP The log gamma function .CR lgamma() is not reentrant, because it uses the global variable .CR signgam . The function .CR lgamma_r() is a reentrant version of .CR lgamma() that can be used in multi-threaded applications. The function .CR lgamma_r() returns the sign of .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} in its parameter list, through the pointer .IR sign . The value pointed to by .I sign is +1 if .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} is positive, \-1 if it is negative. The function .CR lgamma_r() is named in the spirit of the POSIX threads draft standard (P1003.4a), but it has no formal sanction. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is a non-positive integer, .CR lgamma() and .CR gamma() return .CR HUGE_VAL . .PP If the correct value would overflow, .CR lgamma() and .CR gamma() return .CR HUGE_VAL . .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR lgamma() and .CR gamma() return zero. .PP If .I x is NaN, .CR lgamma() and .CR gamma() return NaN. .SH ERRORS No errors are defined. .SH WARNINGS .CR lgamma() and .CR gamma() are unsafe in multi-thread applications. .CR lgamma_r() is MT-Safe and should be used instead. .SH SEE ALSO exp(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR lgamma() ": SVID3, XPG4.2" .PP .CR gamma() ": SVID2, XPG4.2" .PP .CR signgam ": SVID3, XPG4.2" .\" .\" index@\f4gamma()\f1, \f4lgamma()\f1, \f4lgamma_r()\f1, \f4signgam()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f4lgamma()\f1, \f4lgamma_r()\f1, \f4gamma()\f1, \f4signgam()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f4lgamma_r()\f1, \f4gamma()\f1, \f4signgam()\f1, \f4lgamma()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f4signgam()\f1, \f4gamma()\f1, \f4lgamma()\f1, \f4lgamma_r()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f1math: log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f1log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f1gamma function, log@@@\f3lgamma(3M)\f1 .\" .\" toc@\f3lgamma(3M)\f1:\0\0\f4gamma()\f1, \f4lgamma()\f1, \f4lgamma_r()\f1, \f4signgam()\f1@@@log gamma function .\" toc@\f4lgamma()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" toc@\f4lgamma_r()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" toc@\f4gamma()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" toc@\f4signgam()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" .\" links@lgamma.3m signgam.3m .\" links@lgamma.3m gamma.3m .\" links@lgamma.3m lgamma_r.3m .\" $Header: lgamma.3m,v 78.1 96/02/13 12:44:15 ssa Exp $ .TA l .TH lgamma 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lgamma(\|), lgamma_r(\|), gamma(\|), signgam(\|) \- log gamma function .SH SYNOPSIS .C "#include " .PP .C "double lgamma(double x);" .PP .C "double gamma(double x);" .PP .C "extern int signgam;" .PP .C "double lgamma_r(double x, int *sign); .SH DESCRIPTION .CR lgamma() and .CR gamma() return .ifn \{\ .CI ln(|Gamma( x )|)\c\} .ift \{\ .CI ln(|\(*G( x )|)\c\} , where .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} is defined as the integral, as .I t goes from zero to infinity, of .CI exp(\(mi t ) times .I t to the power .RI ( x \(mi1). .PP The sign of .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} is returned in the external integer .CR signgam . The argument .I x must not be zero or a negative integer. .RC ( lgamma() is defined over the reals excluding the non-positive integers.) .PP The following C program fragment can be used to calculate .ifn \{\ .RI Gamma( x ):\} .ift \{\ .RI \(*G( x ):\} .nf .IP .CR "if ((y = lgamma(x)) > LN_MAXDOUBLE)" .CR " error(\|);" .CR "y = signgam * exp(y);" .fi .PP where if .I y is greater than .CR LN_MAXDOUBLE , as defined in the .RC < values.h > header file, .CR exp() returns a range error (see .IR exp (3M)). .PP The log gamma function .CR lgamma() is not reentrant, because it uses the global variable .CR signgam . The function .CR lgamma_r() is a reentrant version of .CR lgamma() that can be used in multi-threaded applications. The function .CR lgamma_r() returns the sign of .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} in its parameter list, through the pointer .IR sign . The value pointed to by .I sign is +1 if .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} is positive, \-1 if it is negative. The function .CR lgamma_r() is named in the spirit of the POSIX threads draft standard (P1003.4a), but it has no formal sanction. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is a non-positive integer, .CR lgamma() and .CR gamma() return .CR HUGE_VAL . .PP If the correct value would overflow, .CR lgamma() and .CR gamma() return .CR HUGE_VAL . .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR lgamma() and .CR gamma() return zero. .PP If .I x is NaN, .CR lgamma() and .CR gamma() return NaN. .SH ERRORS No errors are defined. .SH WARNINGS .CR lgamma() and .CR gamma() are unsafe in multi-thread applications. .CR lgamma_r() is MT-Safe and should be used instead. .SH SEE ALSO exp(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR lgamma() ": SVID3, XPG4.2" .PP .CR gamma() ": SVID2, XPG4.2" .PP .CR signgam ": SVID3, XPG4.2" .\" .\" index@\f4gamma()\f1, \f4lgamma()\f1, \f4lgamma_r()\f1, \f4signgam()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f4lgamma()\f1, \f4lgamma_r()\f1, \f4gamma()\f1, \f4signgam()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f4lgamma_r()\f1, \f4gamma()\f1, \f4signgam()\f1, \f4lgamma()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f4signgam()\f1, \f4gamma()\f1, \f4lgamma()\f1, \f4lgamma_r()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f1math: log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f1log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f1gamma function, log@@@\f3lgamma(3M)\f1 .\" .\" toc@\f3lgamma(3M)\f1:\0\0\f4gamma()\f1, \f4lgamma()\f1, \f4lgamma_r()\f1, \f4signgam()\f1@@@log gamma function .\" toc@\f4lgamma()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" toc@\f4lgamma_r()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" toc@\f4gamma()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" toc@\f4signgam()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" .\" links@lgamma.3m signgam.3m .\" links@lgamma.3m gamma.3m .\" links@lgamma.3m lgamma_r.3m .\" $Header: lines.3x,v 76.2 95/08/01 11:34:29 ssa Exp $ .TA L .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH LINES 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME LINES \(em number of lines on terminal screen .SH SYNOPSIS .C "#include " .P .C "extern int LINES;" .SH DESCRIPTION The external variable .I LINES indicates the number of lines on the terminal screen. .SH "SEE ALSO" initscr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4LINES\f1 \- number of lines on terminal screen@@@\f3LINES(3X)\f1 .\" index@\f1number of lines on terminal screen@@@\f3LINES(3X)\f1 .\" index@\f1terminal screen, number of lines@@@\f3LINES(3X)\f1 .\" index@\f1screen, number of lines on@@@\f3LINES(3X)\f1 .\" index@\f1lines, number of, on terminal screen@@@\f3LINES(3X)\f1 .\" .\" toc@\f3LINES(3X)\f1:\0\0\f4LINES\f1@@@number of lines on terminal screen .\" .\" fileset_database@LINES.3x CURS-ENG-A-MAN .\" $Header: localeconv.3c,v 72.6 94/11/15 09:55:12 ssa Exp $ .TA l .TH localeconv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME localeconv() \- query the numeric formatting conventions of the current locale .SH SYNOPSIS .C "#include " .PP .C "struct lconv *localeconv(void);" .SH DESCRIPTION The .CR localeconv() function sets the components of an object of type .CR "struct lconv" (defined in .CR ) with values appropriate for the formatting of numeric quantities (monetary and otherwise) according to the rules of the program's current locale (see .IR setlocale (3C)). .PP The members of the structure with type .CR "char *" are strings, any of which (except .CR decimal_point ) can point to "" (the empty string) to indicate that the value is not available in the current locale or is of zero length. The members with type .CR char are nonnegative numbers, any of which can be .CR CHAR_MAX (defined in .CR ) to indicate that the value is not available in the current locale. The members include the following: .RS .TP 10 .C char *decimal_point The decimal point character used to format nonmonetary quantities. This is the same value as that returned by a call to .CR nl_langinfo() with .CR RADIXCHAR as its argument (see .IR nl_langinfo (3C)). .TP .C char *thousands_sep The character used to separate groups of digits to the left of the decimal point character in formatted nonmonetary quantities. This is the same value as that returned by a call to .CR nl_langinfo() with .CR THOUSEP as its argument (see .IR nl_langinfo (3C)). .TP .C char *grouping A string where the numeric value of each byte indicates the size of each group of digits in formatted nonmonetary quantities. .TP .C char *int_curr_symbol The international currency symbol applicable to the current locale. The first three characters contain the alphabetic international currency symbol in accordance with those specified in .IR "ISO 4217 Codes for the Representation of Currency and Funds" . The fourth character (immediately preceding the null character) is the character used to separate the international currency symbol from the monetary quantity. .TP .C char *currency_symbol The local currency symbol applicable to the current locale. This value along with positioning information is returned by a call to .CR nl_langinfo() with .CR CRNCYSTR as its argument (see .IR nl_langinfo (3C)). .TP .C char *mon_decimal_point The decimal point used to format monetary quantities. .TP .C char *mon_thousands_sep The separator for groups of digits to the left of the decimal point in formatted monetary quantities. .TP .C char *mon_grouping A string where the numeric value of each byte indicates the size of each group of digits in formatted monetary quantities. .TP .C char *positive_sign The string used to indicate a nonnegative valued formatted monetary quantity. .TP .C char *negative_sign The string used to indicate a negative valued formatted monetary quantity. .TP .C char int_frac_digits The number of fractional digits (those to the right of the decimal point) to be displayed in an internationally formatted monetary quantity. .TP .C char frac_digits The number of fractional digits (those to the right of the decimal point) to be displayed in a locally formatted monetary quantity. .TP .C char p_cs_precedes Set to 1 or 0 if the .CR currency_symbol or .CR int_curr_symbol respectively precedes or succeeds the value for a nonnegative formatted monetary quantity. .TP .C char p_sep_by_space Set to 1 or 0 if the .CR currency_symbol or .CR int_curr_symbol respectively is or is not separated by a space from the value for a nonnegative formatted monetary quantity; and set to 2 if a space separates the symbol and the sign string, if adjacent. .TP .C char n_cs_precedes Set to 1 or 0 if the .CR currency_symbol or .CR int_curr_symbol respectively precedes or succeeds the value for a negative formatted monetary quantity. .TP .C char n_sep_by_space Set to 1 or 0 if the .CR currency_symbol or .CR int_curr_symbol respectively is or is not separated by a space from the value for a negative formatted monetary quantity; and set to 2 if a space separates the symbol and the sign string, if adjacent. .TP .C char p_sign_posn Set to a value indicating the positioning of the .CR positive_sign for a nonnegative formatted monetary quantity. .TP .C char n_sign_posn Set to a value indicating the positioning of the .CR negative_sign for a negative formatted monetary quantity. .RE .PP The numeric value of each byte of .CR grouping and .CR mon_grouping is interpreted according to the following: .RS .TP 10 .C CHAR_MAX No further grouping is to be performed. .TP .C 0 The previous byte is to be repeatedly used for the remainder of the digits. .TP .I other The value is the number of digits that comprise the current group. The next byte is examined to determine the size of the next group of digits to the left of the current group. .RE .PP The values of .CR p_sign_posn and .CR n_sign_posn are interpreted according to the following: .RS .TP 10 .C 0 Parentheses surround the quantity and .CR currency_symbol or .CR int_curr_symbol . .TP .C 1 The sign string precedes the quantity and .CR currency_symbol or .CR int_curr_symbol . .TP .C 2 The sign string succeeds the quantity and .CR currency_symbol or .CR int_curr_symbol . .TP .C 3 The sign string immediately precedes the .CR currency_symbol or .CR int_curr_symbol . .TP .C 4 The sign string immediately succeeds the .CR currency_symbol or .CR int_curr_symbol . .RE .PP .CR localeconv() behaves as if no library function calls .CR localeconv() . .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_NUMERIC category influences the .CR decimal_point , .CR thousands_sep , and .CR grouping members of the structure referenced by the pointer returned from a call to .CR localeconv() . .PP The .CR LC_MONETARY category influences all of the other members of this structure. .SS International Code Set Support Single- and multibyte character code sets are supported. .SH RETURN VALUE .CR localeconv() returns a pointer to the filled-in .CR "struct lconv" . .ne 10 .SH EXAMPLES The following table illustrates the formatting used in five languages for monetary quantities. .PP .TS box, center; cb | cb | cb | cb lf4 | af4 | af4 | af4. Country Positive format Negative format International format = en_US.iso88591 $1,234.56 -$1,234.56 USD\01,234.56 _ it_IT.iso88591 L.1.234 -L.1.234 ITL.1.234 _ nl_NL.iso88591 F\01.234,56 F\0-1.234,56 NLG\01.234,56 _ no_NO.iso88591 kr1.234,56 kr1.234,56- NOK\01.234,56 _ pt_PT.iso88591 1,234$56 -1,234$56 PTE 1,234$56 .TE .PP For these five languages, the respective values for the monetary members of the structure returned by .CR localeconv() are: .PP .TS box, center; cb | cb | cb | cb | cb | cb lf4 | cf4 | cf4 | cf4 | cf4 | cf4. \& en_US.iso88591 it_IT.iso88591 nl_NL.iso88591 no_NO.iso88591 pt_PT.iso88591 = int_curr_symbol USD ITL. NLG NOK PTE _ currency_symbol $ L. F kr $ _ mon_decimal_point . "" , , $ _ mon_thousands_sep , . . . , _ mon_grouping \e3 \e3 \e3 \e3 \e3 _ positive_sign "" "" "" "" "" _ negative_sign - - - - - _ int_frac_digits 2 0 2 2 2 _ frac_digits 2 0 2 2 2 _ p_cs_precedes 1 1 1 1 0 _ p_sep_by_space 0 0 1 0 0 _ n_cs_precedes 1 1 1 1 0 _ n_sep_by_space 0 0 1 0 0 _ p_sign_posn 1 1 1 1 1 _ n_sign_posn 4 1 4 2 1 .TE .SH WARNINGS The structure returned by .CR localeconv() should not be modified by the calling program. Calls to .CR setlocale() with categories .CR LC_ALL , .CR LC_MONETARY , or .CR LC_NUMERIC can overwrite the contents of the structure that .CR localeconv() points to when it returns (see .IR setlocale (3C)). .SH AUTHOR .CR localeconv() was developed by OSF and HP. .SH SEE ALSO nl_langinfo(3C), setlocale(3C), localedef(4), hpnls(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR localeconv() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4localeconv()\f1 \- query numeric formatting conventions of current locale@@@\f3localeconv(3C)\f1 .\" index@\f1NLS, query numeric formatting conventions of current locale@@@\f3localeconv(3C)\f1 .\" index@\f1query numeric formatting conventions of current locale@@@\f3localeconv(3C)\f1 .\" index@\f1numeric formatting conventions of current locale, query@@@\f3localeconv(3C)\f1 .\" index@\f1formatting conventions, numeric, of current locale, query@@@\f3localeconv(3C)\f1 .\" index@\f1conventions, numeric formatting, of current locale, query@@@\f3localeconv(3C)\f1 .\" index@\f1current locale, query numeric formatting conventions of@@@\f3localeconv(3C)\f1 .\" index@\f1locale, current, query numeric formatting conventions of@@@\f3localeconv(3C)\f1 .\" .\" toc@\f3localeconv(3C)\f1:\0\0\f4localeconv()\f1@@@query numeric formatting conventions of current locale\f1 .\" .\" $Header: ctime.3c,v 76.1 95/07/05 17:27:14 ssa Exp $ .TA c .TH ctime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctime(\|), ctime_r(\|), localtime(\|), localtime_r(\|), gmtime(\|), gmtime_r(\|), mktime(\|), difftime(\|), asctime(\|), asctime_r(\|), timezone(\|), daylight(\|), tzname(\|), tzset(\|) \- convert date and time to string .SH SYNOPSIS .nf .C "#include " .PP .C "char *asctime(const struct tm *timeptr);" .PP .C "int asctime_r(const struct tm *timeptr, char *buffer, int buflen);" .PP .C "char *ctime(const time_t *timer);" .PP .C "int ctime_r(const time_t *timer, char *buffer, int buflen);" .PP .C "double difftime(time_t time1, time_t time0);" .PP .C "struct tm *gmtime(const time_t *timer);" .PP .C "int gmtime_r(const time_t *timer, struct tm *result);" .PP .C "struct tm *localtime(const time_t *timer);" .PP .C "int localtime_r(const time_t *timer, struct tm *result);" .PP .C "time_t mktime(struct tm *timeptr);" .PP .C "extern long timezone;" .PP .C "extern int daylight;" .PP .C "extern char *tzname[2];" .PP .C "void tzset(void);" .fi .SH DESCRIPTION .TP 18 .C asctime() Convert the broken-down time contained in the structure pointed to by .I timeptr and return a pointer to a 26-character string in the form: .RS .IP .C "Sun Sep 16 01:03:52 1973\en\e0" .RE .IP All the fields have constant width. .TP .C asctime_r() is identical to .CR asctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C ctime() Convert the calendar time pointed to by .IR timer , representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: .RS .IP .C asctime(localtime(timer)) .RE .TP .C ctime_r() is identical to .CR ctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C gmtime() Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. .C gmtime() returns a pointer to the .C tm structure described below. .TP .C gmtime_r() is identical to .CR gmtime() , except that .C gmtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C localtime() Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA\c), according to the contents of the TZ environment variable (see Environment Variables below). .C localtime() returns a pointer to the .C tm structure described below. .TP .C localtime_r() is identical to .CR localtime() , except that .C localtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C difftime() Return the difference in seconds between two calendar times: .IR "time1 \(mi time0" . .TP .C mktime() Convert the broken-down time (expressed as local time) in the structure pointed to by .I timeptr into a calendar time value with the same encoding as that of the values returned by .IR time (2). The original values of the .C tm_wday and .C tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below. .IP A positive or zero value for .C tm_isdst causes .C mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for .C tm_isdst causes .C mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time. .IP Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of .C tm_mday is not set until .C tm_mon and .C tm_year are determined. .C mktime() returns the specified calendar time encoded as a value of type .CR time_t . .IP If the calendar time cannot be represented, the function returns the value .RC ( time_t )\|\(em\|1 and sets .C errno to .CR ERANGE . Note the value .RC ( time_t )\|\(em\|1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and .C errno to reliably detect an error condition. .TP .C tzset() Sets the values of the external variables .IR timezone , .IR daylight , and .I tzname according to the contents of the .C TZ environment variable (independent of any time value). The functions .CR localtime() , .CR mktime() , .CR ctime() , .CR asctime() , and .C strftime() (see .IR strftime (3C)) call .C tzset() and use the values returned in the external variables described below for their operations. .C tzset() can also be called directly by the user. .PP The .RC < time.h > header file contains declarations of all relevant functions and externals. It also contains the .C tm structure, which includes the following members: .RS .PP .nf .ift .ft 4 .ps +1 int tm_sec; /* seconds after the minute - [0,61] */ int tm_min; /* minutes after the hour - [0,59] */ int tm_hour; /* hours - [0,23] */ int tm_mday; /* day of month - [1,31] */ int tm_mon; /* month of year - [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday - [0,6] */ int tm_yday; /* days since January 1 - [0,365] */ int tm_isdst; /* daylight savings time flag */ .ift .ft .ps .fi .PP The value of .C tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available. .RE .PP The external variable .C timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), .C timezone is 5\(**60\(**60). The external variable .C daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable .C tzname[2] contains the local standard and local summer time zone abbreviations as specified by the .C TZ environment variable. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .SS Environment Variables The .C tzset() function uses the contents of .C TZ to set the values of the external variables .CR timezone , .C daylight , and .CR tzname . .C TZ also determines the time zone name substituted for the .C %Z and .C %z directives and the time zone adjustments performed by .CR localtime() , .CR mktime() , and .CR ctime() . Two methods for specifying a time zone within .C TZ are described in .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH "RETURN VALUE" .PP For .C asctime_r() and .C ctime_r(), if the buffer is of insufficient length, -1 is returned. For .C asctime_r(), ctime_r(), gmtime_r(), and .C localtime_r(), if the operation is successful, 0 is returned. .SH WARNINGS The return values for .CR asctime() , .CR ctime() , .CR gmtime() , and .CR localtime() point to static data whose contents is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() are MT-Safe and should be used instead. .PP Users of .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .PP The range of .C tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by .IR time (2) and passed as the .I timer argument does not include accumulated leap seconds. The .C tm structure generated by .C localtime() and .C gmtime() will never reflect any leap seconds. Upon successful completion, .C mktime() forces the value of the .C tm_sec component to the range [0,59]. .PP .CR ctime() , .CR ctime_r() , .CR asctime() , and .CR asctime_r() are considered obsolescent and may be removed in a future release. Use of .IR strftime (3C) is recommended instead. .SH AUTHOR .C ctime() was developed by AT&T and HP. .SH SEE ALSO time(2), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR ctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR asctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR daylight ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR difftime() ": AES, SVID3, XPG4, ANSI C" .PP .CR gmtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR localtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mktime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR timezone ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR tzname ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tzset() ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4asctime()\fP, \f4asctime_r()\f1 \- convert \f3tm\f1 structure date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4ctime()\fP, \f4ctime_r()\f1 \- convert \f4clock()\fP date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4daylight()\fP \- Daylight Savings Time flag@@@\f3ctime(3C)\f1 .\" index@\f4gmtime()\fP, \f4gmtime_r()\fP \- convert date and time to Greenwich Mean Time@@@\f3ctime(3C)\f1 .\" index@\f4localtime()\fP, \f4localtime_r()\fP \- convert date and time to local timezone@@@\f3ctime(3C)\f1 .\" index@\f4timezone()\fP \- difference between \s-1UCT\s+1 and local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzname()\fP \- name of local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzset()\fP \- initialize \f4timezone()\fP, \f4daylight()\fP, and \f4tzname()\fP using \s-1TZ\s+1 variable@@@\f3ctime(3C)\f1 .\" index@\f4mktime()\fP \- convert time into calendar time value@@@\f3ctime(3C)\f1 .\" index@\f4difftime()\fP \- difference between two calendar time values@@@\f3ctime(3C)\f1 .\" index@convert date and time to string@@@\f3ctime(3C)\f1 .\" index@string, convert date and time to@@@\f3ctime(3C)\f1 .\" index@date and time, convert to string@@@\f3ctime(3C)\f1 .\" index@time and date, convert to string@@@\f3ctime(3C)\f1 .\" .\" toc@\f3ctime(3C)\f1:\0\0\f4ctime()\fP, \f4ctime_r()\fP, \f4localtime()\fP, \f4localtime_r()\fP, \f4difftime()\f1, \f4 mktime()\f1, \n\f4gmtime()\fP, \f4gmtime_r()\fP,\f4asctime()\fP, \f4asctime_r()\fP, \f4timezone()\fP, \f4daylight()\fP, \f4tzname()\fP,\n\f4tzset()\f1@@@convert date and time to string .\" toc@\f4ctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4ctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4timezone()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4daylight()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzname()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzset()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4difftime()\fP:\0\0difference between calendar times@@@see \f3ctime(3C)\f1 .\" toc@\f4mktime()\fP:\0\0create calendar time value@@@see \f3ctime(3C)\f1 .\" .\" links@ctime.3c ctime_r.3c .\" links@ctime.3c localtime.3c .\" links@ctime.3c localtime_r.3c .\" links@ctime.3c gmtime.3c .\" links@ctime.3c gmtime_r.3c .\" links@ctime.3c asctime.3c .\" links@ctime.3c asctime_r.3c .\" links@ctime.3c timezone.3c .\" links@ctime.3c daylight.3c .\" links@ctime.3c tzname.3c .\" links@ctime.3c tzset.3c .\" links@ctime.3c difftime.3c .\" links@ctime.3c mktime.3c .\" .\" fileset_database@ctime.3c PROGRAMING-MAN .\" $Header: ctime.3c,v 76.1 95/07/05 17:27:14 ssa Exp $ .TA c .TH ctime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctime(\|), ctime_r(\|), localtime(\|), localtime_r(\|), gmtime(\|), gmtime_r(\|), mktime(\|), difftime(\|), asctime(\|), asctime_r(\|), timezone(\|), daylight(\|), tzname(\|), tzset(\|) \- convert date and time to string .SH SYNOPSIS .nf .C "#include " .PP .C "char *asctime(const struct tm *timeptr);" .PP .C "int asctime_r(const struct tm *timeptr, char *buffer, int buflen);" .PP .C "char *ctime(const time_t *timer);" .PP .C "int ctime_r(const time_t *timer, char *buffer, int buflen);" .PP .C "double difftime(time_t time1, time_t time0);" .PP .C "struct tm *gmtime(const time_t *timer);" .PP .C "int gmtime_r(const time_t *timer, struct tm *result);" .PP .C "struct tm *localtime(const time_t *timer);" .PP .C "int localtime_r(const time_t *timer, struct tm *result);" .PP .C "time_t mktime(struct tm *timeptr);" .PP .C "extern long timezone;" .PP .C "extern int daylight;" .PP .C "extern char *tzname[2];" .PP .C "void tzset(void);" .fi .SH DESCRIPTION .TP 18 .C asctime() Convert the broken-down time contained in the structure pointed to by .I timeptr and return a pointer to a 26-character string in the form: .RS .IP .C "Sun Sep 16 01:03:52 1973\en\e0" .RE .IP All the fields have constant width. .TP .C asctime_r() is identical to .CR asctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C ctime() Convert the calendar time pointed to by .IR timer , representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: .RS .IP .C asctime(localtime(timer)) .RE .TP .C ctime_r() is identical to .CR ctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C gmtime() Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. .C gmtime() returns a pointer to the .C tm structure described below. .TP .C gmtime_r() is identical to .CR gmtime() , except that .C gmtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C localtime() Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA\c), according to the contents of the TZ environment variable (see Environment Variables below). .C localtime() returns a pointer to the .C tm structure described below. .TP .C localtime_r() is identical to .CR localtime() , except that .C localtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C difftime() Return the difference in seconds between two calendar times: .IR "time1 \(mi time0" . .TP .C mktime() Convert the broken-down time (expressed as local time) in the structure pointed to by .I timeptr into a calendar time value with the same encoding as that of the values returned by .IR time (2). The original values of the .C tm_wday and .C tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below. .IP A positive or zero value for .C tm_isdst causes .C mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for .C tm_isdst causes .C mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time. .IP Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of .C tm_mday is not set until .C tm_mon and .C tm_year are determined. .C mktime() returns the specified calendar time encoded as a value of type .CR time_t . .IP If the calendar time cannot be represented, the function returns the value .RC ( time_t )\|\(em\|1 and sets .C errno to .CR ERANGE . Note the value .RC ( time_t )\|\(em\|1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and .C errno to reliably detect an error condition. .TP .C tzset() Sets the values of the external variables .IR timezone , .IR daylight , and .I tzname according to the contents of the .C TZ environment variable (independent of any time value). The functions .CR localtime() , .CR mktime() , .CR ctime() , .CR asctime() , and .C strftime() (see .IR strftime (3C)) call .C tzset() and use the values returned in the external variables described below for their operations. .C tzset() can also be called directly by the user. .PP The .RC < time.h > header file contains declarations of all relevant functions and externals. It also contains the .C tm structure, which includes the following members: .RS .PP .nf .ift .ft 4 .ps +1 int tm_sec; /* seconds after the minute - [0,61] */ int tm_min; /* minutes after the hour - [0,59] */ int tm_hour; /* hours - [0,23] */ int tm_mday; /* day of month - [1,31] */ int tm_mon; /* month of year - [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday - [0,6] */ int tm_yday; /* days since January 1 - [0,365] */ int tm_isdst; /* daylight savings time flag */ .ift .ft .ps .fi .PP The value of .C tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available. .RE .PP The external variable .C timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), .C timezone is 5\(**60\(**60). The external variable .C daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable .C tzname[2] contains the local standard and local summer time zone abbreviations as specified by the .C TZ environment variable. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .SS Environment Variables The .C tzset() function uses the contents of .C TZ to set the values of the external variables .CR timezone , .C daylight , and .CR tzname . .C TZ also determines the time zone name substituted for the .C %Z and .C %z directives and the time zone adjustments performed by .CR localtime() , .CR mktime() , and .CR ctime() . Two methods for specifying a time zone within .C TZ are described in .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH "RETURN VALUE" .PP For .C asctime_r() and .C ctime_r(), if the buffer is of insufficient length, -1 is returned. For .C asctime_r(), ctime_r(), gmtime_r(), and .C localtime_r(), if the operation is successful, 0 is returned. .SH WARNINGS The return values for .CR asctime() , .CR ctime() , .CR gmtime() , and .CR localtime() point to static data whose contents is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() are MT-Safe and should be used instead. .PP Users of .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .PP The range of .C tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by .IR time (2) and passed as the .I timer argument does not include accumulated leap seconds. The .C tm structure generated by .C localtime() and .C gmtime() will never reflect any leap seconds. Upon successful completion, .C mktime() forces the value of the .C tm_sec component to the range [0,59]. .PP .CR ctime() , .CR ctime_r() , .CR asctime() , and .CR asctime_r() are considered obsolescent and may be removed in a future release. Use of .IR strftime (3C) is recommended instead. .SH AUTHOR .C ctime() was developed by AT&T and HP. .SH SEE ALSO time(2), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR ctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR asctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR daylight ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR difftime() ": AES, SVID3, XPG4, ANSI C" .PP .CR gmtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR localtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mktime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR timezone ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR tzname ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tzset() ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4asctime()\fP, \f4asctime_r()\f1 \- convert \f3tm\f1 structure date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4ctime()\fP, \f4ctime_r()\f1 \- convert \f4clock()\fP date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4daylight()\fP \- Daylight Savings Time flag@@@\f3ctime(3C)\f1 .\" index@\f4gmtime()\fP, \f4gmtime_r()\fP \- convert date and time to Greenwich Mean Time@@@\f3ctime(3C)\f1 .\" index@\f4localtime()\fP, \f4localtime_r()\fP \- convert date and time to local timezone@@@\f3ctime(3C)\f1 .\" index@\f4timezone()\fP \- difference between \s-1UCT\s+1 and local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzname()\fP \- name of local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzset()\fP \- initialize \f4timezone()\fP, \f4daylight()\fP, and \f4tzname()\fP using \s-1TZ\s+1 variable@@@\f3ctime(3C)\f1 .\" index@\f4mktime()\fP \- convert time into calendar time value@@@\f3ctime(3C)\f1 .\" index@\f4difftime()\fP \- difference between two calendar time values@@@\f3ctime(3C)\f1 .\" index@convert date and time to string@@@\f3ctime(3C)\f1 .\" index@string, convert date and time to@@@\f3ctime(3C)\f1 .\" index@date and time, convert to string@@@\f3ctime(3C)\f1 .\" index@time and date, convert to string@@@\f3ctime(3C)\f1 .\" .\" toc@\f3ctime(3C)\f1:\0\0\f4ctime()\fP, \f4ctime_r()\fP, \f4localtime()\fP, \f4localtime_r()\fP, \f4difftime()\f1, \f4 mktime()\f1, \n\f4gmtime()\fP, \f4gmtime_r()\fP,\f4asctime()\fP, \f4asctime_r()\fP, \f4timezone()\fP, \f4daylight()\fP, \f4tzname()\fP,\n\f4tzset()\f1@@@convert date and time to string .\" toc@\f4ctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4ctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4timezone()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4daylight()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzname()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzset()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4difftime()\fP:\0\0difference between calendar times@@@see \f3ctime(3C)\f1 .\" toc@\f4mktime()\fP:\0\0create calendar time value@@@see \f3ctime(3C)\f1 .\" .\" links@ctime.3c ctime_r.3c .\" links@ctime.3c localtime.3c .\" links@ctime.3c localtime_r.3c .\" links@ctime.3c gmtime.3c .\" links@ctime.3c gmtime_r.3c .\" links@ctime.3c asctime.3c .\" links@ctime.3c asctime_r.3c .\" links@ctime.3c timezone.3c .\" links@ctime.3c daylight.3c .\" links@ctime.3c tzname.3c .\" links@ctime.3c tzset.3c .\" links@ctime.3c difftime.3c .\" links@ctime.3c mktime.3c .\" .\" fileset_database@ctime.3c PROGRAMING-MAN .\" $Header: log.3m,v 78.1 96/02/13 12:44:52 ssa Exp $ .TA l .TH log 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME log(\|), logf(\|) \- natural logarithm functions .SH SYNOPSIS .C "#include " .PP .C "double log(double x);" .PP .C "float logf(float x);" .SH DESCRIPTION .CR log() returns the natural logarithm of .IR x . The value of .I x must be positive. .PP .CR logf() is a .CR float version of .CR log() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR logf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is +INFINITY, .CR log() returns +INFINITY. .PP If .I x is zero, .CR log() returns .CR \(miHUGE_VAL . .PP If .I x is NaN, .CR log() returns NaN. .PP If .I x is negative, .CR log() returns NaN and sets .CR errno to [EDOM]. .SH ERRORS If .CR log() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] .I x is negative. .RE .SH DEPENDENCIES Millicode versions of the .CR log() and .CR logf() functions are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO exp(3M), log10(3M), log2(3M), pow(3M), sqrt(3M), cbrt(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR log() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4log()\f1, \f4logf()\f1 \- natural logarithm functions@@@\f3log(3M)\f1 .\" index@\f4logf()\f1, \f4log()\f1 \- natural logarithm functions@@@\f3log(3M)\f1 .\" index@\f1math: natural logarithm functions@@@\f3log(3M)\f1 .\" index@\f1logarithm functions (natural logarithm)@@@\f3log(3M)\f1 .\" index@\f1natural logarithm functions@@@\f3log(3M)\f1 .\" .\" toc@\f3log(3M)\f1:\0\0\f4log()\f1, \f4logf()\f1@@@natural logarithm functions .\" toc@\f4logf()\fP:\0\0natural logarithm function (float version)@@@see \f3log(3M)\f1 .\" .\" links@log.3m logf.3m .\" $Header: log10.3m,v 78.1 96/02/13 12:45:13 ssa Exp $ .TA l .TH log10 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME log10(\|), log10f(\|) \- common logarithm functions .SH SYNOPSIS .C "#include " .PP .C "double log10(double x);" .PP .C "float log10f(float x);" .SH DESCRIPTION .CR log10() returns the logarithm base ten of .IR x . The value of .I x must be positive. .PP .CR log10f() is a .CR float version of .CR log10() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR log10f() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is +INFINITY, .CR log10() returns +INFINITY. .PP If .I x is zero, .CR log10() returns .CR \(miHUGE_VAL . .PP If .I x is NaN, .CR log10() returns NaN. .PP If .I x is negative, .CR log10() returns NaN and sets .CR errno to [EDOM]. .SH ERRORS If .CR log10() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] .I x is negative. .RE .SH DEPENDENCIES Millicode versions of the .CR log10() function are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO exp(3M), log(3M), log2(3M), pow(3M), sqrt(3M), cbrt(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR log10() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4log10()\f1, \f4log10f()\f1 \- common logarithm functions@@@\f3log10(3M)\f1 .\" index@\f4log10f()\f1, \f4log10()\f1 \- common logarithm functions@@@\f3log10(3M)\f1 .\" index@\f1math: common logarithm functions@@@\f3log10(3M)\f1 .\" index@\f1common logarithm functions@@@\f3log10(3M)\f1 .\" index@\f1logarithm base ten functions@@@\f3log10(3M)\f1 .\" .\" toc@\f3log10(3M)\f1:\0\0\f4log10()\f1, \f4log10f()\f1@@@common logarithm functions .\" toc@\f4log10f()\f1\f1:\0\0common logarithm function (float version)@@@see \f3log10(3M)\f1 .\" .\" links@log10.3m log10f.3m .\" .\" fileset_database@log10.3m PROGRAMING-MAN .\" $Header: log10.3m,v 78.1 96/02/13 12:45:13 ssa Exp $ .TA l .TH log10 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME log10(\|), log10f(\|) \- common logarithm functions .SH SYNOPSIS .C "#include " .PP .C "double log10(double x);" .PP .C "float log10f(float x);" .SH DESCRIPTION .CR log10() returns the logarithm base ten of .IR x . The value of .I x must be positive. .PP .CR log10f() is a .CR float version of .CR log10() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR log10f() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is +INFINITY, .CR log10() returns +INFINITY. .PP If .I x is zero, .CR log10() returns .CR \(miHUGE_VAL . .PP If .I x is NaN, .CR log10() returns NaN. .PP If .I x is negative, .CR log10() returns NaN and sets .CR errno to [EDOM]. .SH ERRORS If .CR log10() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] .I x is negative. .RE .SH DEPENDENCIES Millicode versions of the .CR log10() function are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO exp(3M), log(3M), log2(3M), pow(3M), sqrt(3M), cbrt(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR log10() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4log10()\f1, \f4log10f()\f1 \- common logarithm functions@@@\f3log10(3M)\f1 .\" index@\f4log10f()\f1, \f4log10()\f1 \- common logarithm functions@@@\f3log10(3M)\f1 .\" index@\f1math: common logarithm functions@@@\f3log10(3M)\f1 .\" index@\f1common logarithm functions@@@\f3log10(3M)\f1 .\" index@\f1logarithm base ten functions@@@\f3log10(3M)\f1 .\" .\" toc@\f3log10(3M)\f1:\0\0\f4log10()\f1, \f4log10f()\f1@@@common logarithm functions .\" toc@\f4log10f()\f1\f1:\0\0common logarithm function (float version)@@@see \f3log10(3M)\f1 .\" .\" links@log10.3m log10f.3m .\" .\" fileset_database@log10.3m PROGRAMING-MAN .\" $Header: log1p.3m,v 78.1 96/02/13 12:47:53 ssa Exp $ .TA l .TH log1p 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME log1p(\|) \- computes logarithmic functions .SH SYNOPSIS .C "#include " .PP .C "double log1p(double x);" .SH DESCRIPTION .PP The .CR log1p() function computes logarithmic functions. .PP The .CR log1p() function is equivalent to .CI "log(1 + " x )\f1, but may be more accurate for very small values of .IR x . .PP The .CR expm1() and .CR log1p() functions are useful to guarantee that financial calculations of (((1+\f2x\f1)**n)-1)/\f2x\f1, namely: .sp .in +1 .CR expm1 "(n * " log1p (\f2x\f1))/\f2x\f1 .sp .in -1 are accurate when .I x is very small (for example, when calculating small daily interest rates). These functions also simplify writing accurate inverse hyperbolic functions. .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH "RETURN VALUE" .CR log1p() returns the natural logarithm of (1 + .IR x ). .PP If .I x is +INFINITY, .CR log1p() returns +INFINITY. .PP If .I x = \-1.0, .CR log1p() returns .CR \(miHUGE_VAL . .PP If .I x is NaN, .CR log1p() returns NaN. .PP If .I x < \-1.0, .CR log1p() returns NaN and sets .CR errno to [EDOM]. .SH ERRORS If .CR log1p() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] .I x is less than \-1.0. .SH "SEE ALSO" log(3M), expm1(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR log1p() ": XPG4.2" .\" .\" index@\f4log1p()\f1 \- computes logarithmic functions@@@\f3log1p(3M)\f1 .\" index@logarithmic functions@@@\f3log1p(3M)\f1 .\" index@math: logarithmic functions@@@\f3log1p(3M)\f1 .\" .\" toc@\f3log1p(3M)\f1:\0\0\f4log1p()\f1@@@logarithmic functions .\" .\" fileset_database@log1p.3m PROGRAMING-MAN .\" $Header: log2.3m,v 78.1 96/02/13 13:05:29 ssa Exp $ .TA l .TH log2 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME log2(\|), log2f(\|) \- logarithm base two functions .SH SYNOPSIS .C "#include " .PP .C "double log2(double x);" .PP .C "float log2f(float x);" .SH DESCRIPTION .CR log2() returns the logarithm base two of .IR x . The value of .I x must be positive. .PP .CR log2f() is a .CR float version of .CR log2() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR log2() and .CR log2f() are not specified by any standard, but .CR log2f() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is +INFINITY, .CR log2() returns +INFINITY. .PP If .I x is zero, .CR log2() returns .CR \(miHUGE_VAL . .PP If .I x is NaN, .CR log2() returns NaN. .PP If .I x is negative, .CR log2() returns NaN and sets .CR errno to [EDOM]. .SH ERRORS If .CR log2() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] .I x is negative. .RE .SH SEE ALSO exp(3M), log(3M), log10(3M), pow(3M), sqrt(3M), cbrt(3M), isinf(3M), isnan(3M). .\" .\" index@\f4log2()\f1, \f4log2f()\f1 \- logarithm base two functions@@@\f3log2(3M)\f1 .\" index@\f4log2f()\f1, \f4log2()\f1 \- logarithm base two functions@@@\f3log2(3M)\f1 .\" index@\f1math: logarithm base two functions@@@\f3log2(3M)\f1 .\" index@\f1logarithm base two functions@@@\f3log2(3M)\f1 .\" index@\f1base two logarithm functions@@@\f3log2(3M)\f1 .\" .\" toc@\f3log2(3M)\f1:\0\0\f4log2()\f1, \f4log2f()\f1@@@logarithm base two functions .\" toc@\f4log2f()\fP\f1:\0\0logarithm base two function (float version)@@@see \f3log2(3M)\f1 .\" .\" links@log2.3m log2f.3m .\" .\" fileset_database@log2.3m PROGRAMING-MAN .\" $Header: log2.3m,v 78.1 96/02/13 13:05:29 ssa Exp $ .TA l .TH log2 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME log2(\|), log2f(\|) \- logarithm base two functions .SH SYNOPSIS .C "#include " .PP .C "double log2(double x);" .PP .C "float log2f(float x);" .SH DESCRIPTION .CR log2() returns the logarithm base two of .IR x . The value of .I x must be positive. .PP .CR log2f() is a .CR float version of .CR log2() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR log2() and .CR log2f() are not specified by any standard, but .CR log2f() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is +INFINITY, .CR log2() returns +INFINITY. .PP If .I x is zero, .CR log2() returns .CR \(miHUGE_VAL . .PP If .I x is NaN, .CR log2() returns NaN. .PP If .I x is negative, .CR log2() returns NaN and sets .CR errno to [EDOM]. .SH ERRORS If .CR log2() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] .I x is negative. .RE .SH SEE ALSO exp(3M), log(3M), log10(3M), pow(3M), sqrt(3M), cbrt(3M), isinf(3M), isnan(3M). .\" .\" index@\f4log2()\f1, \f4log2f()\f1 \- logarithm base two functions@@@\f3log2(3M)\f1 .\" index@\f4log2f()\f1, \f4log2()\f1 \- logarithm base two functions@@@\f3log2(3M)\f1 .\" index@\f1math: logarithm base two functions@@@\f3log2(3M)\f1 .\" index@\f1logarithm base two functions@@@\f3log2(3M)\f1 .\" index@\f1base two logarithm functions@@@\f3log2(3M)\f1 .\" .\" toc@\f3log2(3M)\f1:\0\0\f4log2()\f1, \f4log2f()\f1@@@logarithm base two functions .\" toc@\f4log2f()\fP\f1:\0\0logarithm base two function (float version)@@@see \f3log2(3M)\f1 .\" .\" links@log2.3m log2f.3m .\" .\" fileset_database@log2.3m PROGRAMING-MAN .\" $Header: logb.3m,v 78.2 96/02/13 13:08:16 ssa Exp $ .TA l .TH logb 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME logb(\|) \- radix-independent exponent .SH SYNOPSIS .C "#include " .PP .C "double logb(double x);" .SH DESCRIPTION .PP The .CR logb() function computes the exponent of .IR x . Formally, the return value is the integral part of log base .I r of .RI | x | as a signed floating point value, for nonzero .IR x , where .I r is the radix of the machine's floating-point arithmetic. .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH "RETURN VALUE" .PP Upon successful completion, .CR logb() returns the exponent of .CR x . .PP If .I x is NaN, .CR logb() returns NaN. .PP If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR logb() returns +INFINITY. .PP If .I x is zero, .CR logb() returns .CR \(miHUGE_VAL and sets .CR errno to [EDOM]. .SH "ERRORS" .PP If .CR logb() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] .I x is zero. .RE .SH "SEE ALSO" ilogb(3M), isinf(3M), isnan(3M), scalb(3M), limits(5). .SH STANDARDS CONFORMANCE .CR logb() ": SVID3, XPG4.2" .\" index@\f4logb()\f1 \- radix-independent exponent@@@\f3logb(3M)\f1 .\" index@\f1radix-independent exponent@@@\f3logb(3M)\f1 .\" index@\f1exponent, radix-independent@@@\f3logb(3M)\f1 .\" index@\f1math: radix-independent exponent@@@\f3logb(3M)\f1 .\" .\" toc@\f3logb(3M)\f1:\0\0\f4logb()\f1@@@radix-independent exponent .\" $Header: log.3m,v 78.1 96/02/13 12:44:52 ssa Exp $ .TA l .TH log 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME log(\|), logf(\|) \- natural logarithm functions .SH SYNOPSIS .C "#include " .PP .C "double log(double x);" .PP .C "float logf(float x);" .SH DESCRIPTION .CR log() returns the natural logarithm of .IR x . The value of .I x must be positive. .PP .CR logf() is a .CR float version of .CR log() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR logf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is +INFINITY, .CR log() returns +INFINITY. .PP If .I x is zero, .CR log() returns .CR \(miHUGE_VAL . .PP If .I x is NaN, .CR log() returns NaN. .PP If .I x is negative, .CR log() returns NaN and sets .CR errno to [EDOM]. .SH ERRORS If .CR log() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] .I x is negative. .RE .SH DEPENDENCIES Millicode versions of the .CR log() and .CR logf() functions are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO exp(3M), log10(3M), log2(3M), pow(3M), sqrt(3M), cbrt(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR log() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4log()\f1, \f4logf()\f1 \- natural logarithm functions@@@\f3log(3M)\f1 .\" index@\f4logf()\f1, \f4log()\f1 \- natural logarithm functions@@@\f3log(3M)\f1 .\" index@\f1math: natural logarithm functions@@@\f3log(3M)\f1 .\" index@\f1logarithm functions (natural logarithm)@@@\f3log(3M)\f1 .\" index@\f1natural logarithm functions@@@\f3log(3M)\f1 .\" .\" toc@\f3log(3M)\f1:\0\0\f4log()\f1, \f4logf()\f1@@@natural logarithm functions .\" toc@\f4logf()\fP:\0\0natural logarithm function (float version)@@@see \f3log(3M)\f1 .\" .\" links@log.3m logf.3m .\" $Header: logname.3c,v 72.4 94/11/15 09:55:14 ssa Exp $ .TA l .TH logname 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME logname(\|) \- return login name of user .SH SYNOPSIS .C "#include " .PP .C "char *logname(void);" .SH DESCRIPTION .C logname() returns a pointer to the null-terminated login name; it extracts the .C $LOGNAME variable from the user's environment. .SH WARNINGS .C logname() returns a pointer to static data that is overwritten by each subsequent call. .PP This method of determining a login name is subject to forgery. .SH FILES /etc/profile .SH SEE ALSO env(1), login(1), profile(4), environ(5). .SH STANDARDS CONFORMANCE .CR logname() ": SVID2, XPG2" .\" .\" index@\f4logname()\fP \- return login name of user@@@\f3logname(3C)\f1 .\" index@login name of user, obtain@@@\f3logname(3C)\f1 .\" index@user login name, obtain@@@\f3logname(3C)\f1 .\" index@name: obtain user login name@@@\f3logname(3C)\f1 .\" .\" toc@\f3logname(3C)\f1:\0\0\f4logname()\fP@@@return login name of user .\" .\" fileset_database@logname.3c PROGRAMING-MAN .\" $Header: setjmp.3c,v 72.5 94/11/15 09:56:14 ssa Exp $ .TA s .TH setjmp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setjmp(\|), longjmp(\|), sigsetjmp(\|), siglongjmp(\|) \- non-local goto .SH SYNOPSIS .C "#include " .PP .C "int setjmp(jmp_buf env);" .PP .C "void longjmp(jmp_buf env, int val);" .PP .C "int _setjmp(jmp_buf env);" .PP .C "void _longjmp(jmp_buf env, int val);" .PP .C "int sigsetjmp(sigjmp_buf env, int savemask);" .PP .C "void siglongjmp(sigjmp_buf env, int val);" .SH DESCRIPTION .C setjmp() and .C longjmp() are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. They exist in three variant forms: .CR setjmp() and .CR longjmp() ; .CR _setjmp() and .CR _longjmp() ; .CR sigsetjmp() and .CR siglongjmp() . Unless indicated otherwise, references to .C setjmp() and .C longjmp() apply to all three versions. .RS .TP 18 .C setjmp() saves its stack environment in .I env (whose type, .CR jmp_buf , is defined in the .RC < setjmp.h > header file) for later use by .CR longjmp() . It returns the value .CR 0 . .TP .C longjmp() restores the environment saved by the last call of .C setjmp() with the corresponding .I env argument. After .C longjmp() is completed, program execution continues as if the corresponding call of .C setjmp() (which must not itself have returned in the interim) had just returned the value .IR val . .C longjmp() cannot cause .C setjmp() to return the value .CR 0 . If .C longjmp() is invoked with a second argument of .CR 0 , .C setjmp() returns .CR 1 . All accessible data values are valid as of the time .C longjmp() is called. .RE .PP Upon the return from a .C setjmp() call caused by a .CR longjmp() , the values of any non-static local variables belonging to the routine from which .C setjmp() was called are undefined. Code which depends on such values is not guaranteed to be portable. .SS Variant Forms The following functions behave the same as .C setjmp() and .C longjmp() except in the handling of the process' signal mask (see .IR sigaction (2) and .IR sigvector (2)). This distinction is only significant for programs which use .CR sigaction() , .CR sigprocmask() , .CR sigvector() , .CR sigblock() , and/or .CR sigsetmask() . .RS .TP 18 .C setjmp() .PD 0 .TP .C longjmp() These always save and restore the signal mask. .PD .TP .C _setjmp() .PD 0 .TP .C _longjmp() These never manipulate the signal mask. .PD .TP .C sigsetjmp() Saves the signal mask if and only if .I savemask is non-zero. .TP .C siglongjmp() Restores the signal mask if and only if it is saved by .CR sigsetjmp() . .SS Programming Considerations If a .C longjmp() is executed and the environment in which the .C setjmp() is executed no longer exists, errors can occur. The conditions under which the environment of the .C setjmp() no longer exists include exiting the procedure that contains the .C setjmp() call, and exiting an inner block with temporary storage (such as a block with declarations in C or a .C with statement in Pascal). This condition might not be detectable, in which case the .C longjmp() occurs and, if the environment no longer exists, the contents of the temporary storage of an inner block are unpredictable. This condition might also cause unexpected process termination. If the procedure has been exited the results are unpredictable. .PP Passing .C longjmp() a pointer to a buffer not created by .CR setjmp() , passing .C _longjmp() a pointer to a buffer not created by either .C setjmp() or .CR _setjmp() , passing .C siglongjmp() a pointer to a buffer not created by .C sigsetjmp() or passing any of these three functions a buffer that has been modified by the user, can cause all the problems listed above, and more. .PP Some implementations of Pascal support a ``try/recover'' mechanism, which also creates stack marker information. If a .C longjmp() operation occurs in a scope which is nested inside a try/recover, and the corresponding .C setjmp() is not inside the scope of the try/recover, the recover block will not be executed and the currently active recover block will become the one enclosing the .CR setjmp() , if one exists. .SH WARNINGS A call to .C longjmp() to leave the guaranteed stack space reserved by .C sigspace() might remove the guarantee that the ordinary execution of the program will not extend into the guaranteed space. It might also cause the program to forever lose its ability to automatically increase the stack size, and the program might then be limited to the guaranteed space. .PP The result of using .C setjmp() within an expression can be unpredictable. .PP If .C longjmp() is called even though .I env was never primed by a call to .CR setjmp() , or when the last such call was in a function that has since returned, total chaos is guaranteed. .SH AUTHOR .C setjmp() was developed by AT&T and HP. .SH SEE ALSO sigaction(2), sigblock(2), signal(5), sigprocmask(2), sigsetmask(2), sigspace(2), sigsuspend(2), sigvector(2). .SH STANDARDS CONFORMANCE .CR setjmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR longjmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR siglongjmp() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigsetjmp() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4_setjmp()\fP \- save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4_longjmp()\fP \- restore stack environment after non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4sigsetjmp()\fP \- save signal mask if savemask is non-zero@@@\f3setjmp(3C)\f1 .\" index@\f4setjmp()\fP \- save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4longjmp()\fP \- restore stack environment after non-local goto@@@\f3setjmp(3C)\f1 .\" index@save/restore stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@restore/save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@non-local goto, save/restore stack environment for@@@\f3setjmp(3C)\f1 .\" index@goto, save/restore stack environment for non-local@@@\f3setjmp(3C)\f1 .\" index@stack environment, save/restore for non-local goto@@@\f3setjmp(3C)\f1 .\" index@environment, save/restore stack for non-local goto@@@\f3setjmp(3C)\f1 .\" .\" toc@\f3setjmp(3S)\f1:\0\0\f4setjmp()\fP, \f4longjmp()\fP@@@save/restore stack environment for non-local goto .\" toc@\f4longjmp()\fP:\0\0restore stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" toc@\f4sigsetjmp()\fP:\0\0save signal mask if savemask is non-zero@@@see \f3setjmp(3C)\f1 .\" toc@\f4_longjmp()\fP:\0\0restore stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" toc@\f4_setjmp()\fP:\0\0save stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" .\" links@setjmp.3c longjmp.3c .\" links@setjmp.3c sigsetjmp.3c .\" links@setjmp.3c siglongjmp.3c .\" links@setjmp.3c _longjmp.3c .\" links@setjmp.3c _setjmp.3c .\" .\" fileset_database@setjmp.3c PROGRAMING-MAN .\" $Header: longname.3x,v 76.2 95/08/01 11:35:36 ssa Exp $ .TA l .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH longname 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME longname \(em get verbose description of current terminal .SH SYNOPSIS .C "#include " .P .C "char *longname(void);" .SH DESCRIPTION The .Fn longname function generates a verbose description of the current terminal. The maximum length of a verbose description is 128 bytes. It is defined only after the call to .Fn initscr or .CR newterm() . .SH "RETURN VALUE" Upon successful completion, .Fn longname returns a pointer to the description specified above. Otherwise, it returns a null pointer on error. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The return value of .Fn longname may point to a static area which is overwritten by a subsequent call to .CR newterm() . .SH "SEE ALSO" initscr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn longname function is explicitly declared as \f3void\f1. .\" .\" index@\f4longname()\f1 \- get verbose description of current terminal@@@\f3longname(3X)\f1 .\" index@\f1get verbose description of current terminal@@@\f3longname(3X)\f1 .\" index@\f1verbose description of current terminal, get@@@\f3longname(3X)\f1 .\" index@\f1description, verbose, of current terminal@@@\f3longname(3X)\f1 .\" index@\f1current terminal, get verbose description of@@@\f3longname(3X)\f1 .\" index@\f1terminal, get verbose description of@@@\f3longname(3X)\f1 .\" .\" toc@\f3longname(3X)\f1:\0\0\f4longname()\f1@@@get verbose description of current terminal .\" .\" fileset_database@longname.3x CURS-ENG-A-MAN .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: lsearch.3c,v 72.4 94/11/15 09:55:16 ssa Exp $ .TA l .TH lsearch 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lsearch(\|), lfind(\|) \- linear search and update .SH SYNOPSIS .C "#include " .PP .C "void *lsearch(" .PD 0 .nf .IP .C "const void *key," .C "void *base," .C "size_t *nelp," .C "size_t width," .C "int (*compar)(const void *, const void *)" .P .C ");" .PD .fi .PP .C "void *lfind(" .PD 0 .nf .IP .C "const void *key," .C "const void *base," .C "size_t *nelp," .C "size_t width," .C "int (*compar)(const void *, const void *)" .P .C ");" .PD .fi .SH DESCRIPTION .TP 15 .C lsearch() is a linear search routine generalized from Knuth (6.1) Algorithm S. It returns a pointer into a table indicating where a datum may be found. If the datum does not occur, it is added at the end of the table. .RS .RS .TP 15 .I key Points to the datum to be sought in the table. .TP .I base Points to the first element in the table. .TP .I nelp Points to an integer containing the current number of elements in the table. The integer is incremented if the datum is added to the table. .TP .I compar Name of the comparison function which the user must supply .RC ( strcmp() , for example). It is called with two arguments that point to the elements being compared. The function must return zero if the elements are equal and non-zero otherwise. .RE .RE .TP .C lfind() Same as .C lsearch() except that if the datum is not found, it is not added to the table. Instead, a .SM NULL pointer is returned. .SS Notes The pointers to the key and the element at the base of the table should be of type pointer-to-element, and cast to type pointer-to-character. .PP The comparison function need not compare every byte, so arbitrary data may be contained in the elements in addition to the values being compared. .PP Although declared as type pointer-to-character, the value returned should be cast into type pointer-to-element. .SH EXAMPLES This code fragment reads in \(<= .C TABSIZE strings of length \(<= .C ELSIZE and stores them in a table, eliminating duplicates. .nf .IP .C #include .C #define TABSIZE 50 .C #define ELSIZE 120 .C " char line[ELSIZE], tab[TABSIZE][ELSIZE], *lsearch( );" .C " unsigned nel = 0;" .C " int strcmp( );" \h'.6i'.\|.\|. .C " while (fgets(line, ELSIZE, stdin) != NULL &&" .C " nel < TABSIZE)" .C " (void) lsearch(line, (char *)tab, &nel," .C " ELSIZE, strcmp);" \h'.6i'.\|.\|. .fi .SH SEE ALSO bsearch(3C), hsearch(3C), tsearch(3C). .SH RETURN VALUE If the searched-for datum is found, both .C lsearch() and .C lfind() return a pointer to it. Otherwise, .C lfind() returns NULL and .C lsearch() returns a pointer to the newly added element. .SH WARNINGS Undefined results can occur if there is not enough room in the table to add a new item. .SH STANDARDS CONFORMANCE .CR lsearch() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lfind() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4lsearch()\fP, \f4lfind()\fP \- linear search and update@@@\f3lsearch(3C)\f1 .\" index@linear table search with optional update@@@\f3lsearch(3C)\f1 .\" index@search table for entry; optional update if missing@@@\f3lsearch(3C)\f1 .\" index@table, eliminate duplicate entries in a@@@\f3lsearch(3C)\f1 .\" index@table, linear search for entry; optional update if missing@@@\f3lsearch(3C)\f1 .\" index@update table if entry missing after search@@@\f3lsearch(3C)\f1 .\" index@eliminate duplicate entries in a table@@@\f3lsearch(3C)\f1 .\" index@duplicate entries in a table, eliminate@@@\f3lsearch(3C)\f1 .\" index@entries in a table, eliminate duplicate@@@\f3lsearch(3C)\f1 .\" .\" toc@\f3lsearch(3C)\f1:\0\0\f4lsearch()\fP, \f4lfind()\fP@@@linear search and update .\" toc@\f4lfind()\fP:\0\0linear search and update@@@see \f3lsearch(3C)\f1 .\" .\" links@lsearch.3c lfind.3c .\" .\" fileset_database@lsearch.3c PROGRAMING-MAN .\" $Header: ltostr.3c,v 74.1 95/05/10 21:07:18 ssa Exp $ .TA l .TH ltostr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ltostr(), ltostr_r(), ultostr(), ultostr_r(), ltoa(), ltoa_r(), ultoa(), ultoa_r() \- convert long integers to strings .SH SYNOPSIS .C "#include " .PP .C "char *ltostr(long n, int base);" .PP .C "int ltostr_r(long n, int base, char *buffer, int buflen);" .PP .C "char *ultostr(unsigned long n, int base);" .PP .C "int ultostr_r(unsigned long n, int base, char *buffer, int buflen);" .PP .C "char *ltoa(long n);" .PP .C "int ltoa_r(long n, char *buffer, int buflen);" .PP .C "char *ultoa(unsigned long n);" .PP .C "int ultoa_r(unsigned long n, char *buffer, int buflen);" .SH DESCRIPTION .RS .TP 15 .CR ltostr() Convert a signed long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ultostr() Convert an unsigned long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ltoa() Convert a signed long integer to the corresponding base 10 string representation, returning a pointer to the result. .TP .CR ultoa() Convert an unsigned long integer to the corresponding base 10 string representation, returning a pointer to the result. .RE .PP These functions are smaller and faster than using .CR sprintf() for simple conversions (see .IR printf (3S)). .SS Reentrant Interfaces For the reentrant .CR "(_r)" interfaces, the result string is passed back in the supplied buffer. If the buffer is of insufficient length, .CR \(mi1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .SH ERRORS If the value of .I base is not between 2 and 36, .CR ltostr() and .CR ultostr() return NULL and set the external variable .CR errno to ERANGE. The reentrant versions .RC ( ltostr_r() " and " ultostr_r() ) return .CR \(mi1 and set the external variable .CR errno to ERANGE. .SH WARNINGS The return values for .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() point to static data whose content is overwritten by each call. .PP .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() are unsafe in multi-thread applications. .CR ltostr_r() , .CR ultostr_r() , .CR ltoa_r() , and .CR ultoa_r() are MT-Safe and should be used instead. .SH AUTHOR .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() were developed by HP. .SH SEE ALSO printf(3C), strtol(3C), printf(3S). .\" .\" index@\f4ltostr()\f1 \- convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ltostr_r()\f1 \- convert long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa()\f1 \- convert long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa_r()\f1 \- convert long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr()\f1 \- convert unsigned long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr_r()\f1 \- convert unsigned long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa()\f1 \- convert unsigned long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa_r()\f1 \- convert unsigned long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f1convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f1long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1unsigned long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1integer, long, convert to string,@@@\f3ltostr(3C)\f1 .\" index@\f1string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1decimal ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" .\" toc@\f3ltostr(3C)\f1:\0\0\f4ltostr()\f1, \f4ltostr_r()\f1, \f4ultostr()\f1, \f4ultostr_r()\f1, \f4ltoa()\f1, \n\f4ltoa_r()\f1, \f4ultoa()\f1, \f4ultoa_r()\f1@@@convert long integers to strings .\" toc@\f4ltostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr()\f1:\0\0unsigned long to ASCII@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa()\f1:\0\0long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa_r()\f1:\0\0long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa()\f1:\0\0unsigned long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa_r()\f1:\0\0unsigned long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" links@ltostr.3c ltostr_r.3c .\" links@ltostr.3c ultostr.3c .\" links@ltostr.3c ultostr_r.3c .\" links@ltostr.3c ultoa.3c .\" links@ltostr.3c ultoa_r.3c .\" links@ltostr.3c ltoa.3c .\" links@ltostr.3c ltoa_r.3c .\" $Header: ltostr.3c,v 74.1 95/05/10 21:07:18 ssa Exp $ .TA l .TH ltostr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ltostr(), ltostr_r(), ultostr(), ultostr_r(), ltoa(), ltoa_r(), ultoa(), ultoa_r() \- convert long integers to strings .SH SYNOPSIS .C "#include " .PP .C "char *ltostr(long n, int base);" .PP .C "int ltostr_r(long n, int base, char *buffer, int buflen);" .PP .C "char *ultostr(unsigned long n, int base);" .PP .C "int ultostr_r(unsigned long n, int base, char *buffer, int buflen);" .PP .C "char *ltoa(long n);" .PP .C "int ltoa_r(long n, char *buffer, int buflen);" .PP .C "char *ultoa(unsigned long n);" .PP .C "int ultoa_r(unsigned long n, char *buffer, int buflen);" .SH DESCRIPTION .RS .TP 15 .CR ltostr() Convert a signed long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ultostr() Convert an unsigned long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ltoa() Convert a signed long integer to the corresponding base 10 string representation, returning a pointer to the result. .TP .CR ultoa() Convert an unsigned long integer to the corresponding base 10 string representation, returning a pointer to the result. .RE .PP These functions are smaller and faster than using .CR sprintf() for simple conversions (see .IR printf (3S)). .SS Reentrant Interfaces For the reentrant .CR "(_r)" interfaces, the result string is passed back in the supplied buffer. If the buffer is of insufficient length, .CR \(mi1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .SH ERRORS If the value of .I base is not between 2 and 36, .CR ltostr() and .CR ultostr() return NULL and set the external variable .CR errno to ERANGE. The reentrant versions .RC ( ltostr_r() " and " ultostr_r() ) return .CR \(mi1 and set the external variable .CR errno to ERANGE. .SH WARNINGS The return values for .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() point to static data whose content is overwritten by each call. .PP .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() are unsafe in multi-thread applications. .CR ltostr_r() , .CR ultostr_r() , .CR ltoa_r() , and .CR ultoa_r() are MT-Safe and should be used instead. .SH AUTHOR .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() were developed by HP. .SH SEE ALSO printf(3C), strtol(3C), printf(3S). .\" .\" index@\f4ltostr()\f1 \- convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ltostr_r()\f1 \- convert long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa()\f1 \- convert long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa_r()\f1 \- convert long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr()\f1 \- convert unsigned long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr_r()\f1 \- convert unsigned long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa()\f1 \- convert unsigned long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa_r()\f1 \- convert unsigned long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f1convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f1long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1unsigned long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1integer, long, convert to string,@@@\f3ltostr(3C)\f1 .\" index@\f1string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1decimal ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" .\" toc@\f3ltostr(3C)\f1:\0\0\f4ltostr()\f1, \f4ltostr_r()\f1, \f4ultostr()\f1, \f4ultostr_r()\f1, \f4ltoa()\f1, \n\f4ltoa_r()\f1, \f4ultoa()\f1, \f4ultoa_r()\f1@@@convert long integers to strings .\" toc@\f4ltostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr()\f1:\0\0unsigned long to ASCII@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa()\f1:\0\0long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa_r()\f1:\0\0long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa()\f1:\0\0unsigned long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa_r()\f1:\0\0unsigned long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" links@ltostr.3c ltostr_r.3c .\" links@ltostr.3c ultostr.3c .\" links@ltostr.3c ultostr_r.3c .\" links@ltostr.3c ultoa.3c .\" links@ltostr.3c ultoa_r.3c .\" links@ltostr.3c ltoa.3c .\" links@ltostr.3c ltoa_r.3c .\" $Header: l3tol.3c,v 72.4 94/11/15 09:55:07 ssa Exp $ .TA l .TH l3tol 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME l3tol(\|), ltol3(\|) \- convert between 3-byte integers and long integers .SH SYNOPSIS .C "#include " .PP .C "void l3tol(long int *lp, const char *cp, int n);" .PP .C "void ltol3(char *cp, const long int *lp, int n);" .SH DESCRIPTION .TP 15 .C l3tol() Convert a list of .I n three-byte integers packed into a character string pointed to by .I cp into a list of long integers pointed to by .IR lp . .TP .C ltol3() Perform the reverse conversion from long integers .RI ( lp ) to three-byte integers .RI ( cp ). .PP These functions are useful for file-system maintenance where the block numbers are three bytes long. .SH SEE ALSO fs(4). .SH WARNINGS Because of possible differences in byte ordering, the numerical values of the long integers are machine-dependent. .SH STANDARDS CONFORMANCE .CR l3tol() ": XPG2" .PP .CR ltol3() ": XPG2" .\" .\" index@\f4l3tol()\f1 \- convert 3-byte integer to long integer@@@\f3l3tol(3C)\f1 .\" index@\f4ltol3()\f1 \- convert long integer to 3-byte integer@@@\f3l3tol(3C)\f1 .\" index@convert between 3-byte integers and long integers@@@\f3l3tol(3C)\f1 .\" index@three-byte integers and long integers, convert between@@@\f3l3tol(3C)\f1 .\" index@long integers and 3-byte integers, convert between@@@\f3l3tol(3C)\f1 .\" index@integers, convert between 3-byte integers and long integers@@@\f3l3tol(3C)\f1 .\" .\" toc@\f3l3tol(3C)\f1:\0\0\f4l3tol()\f1, \f4ltol3()\f1@@@convert between 3-byte integers and long integers .\" toc@\f4ltol3()\f1:\0\0convert between 3-byte integers and long integers@@@see \f3l3tol(3C)\f1 .\" .\" links@l3tol.3c ltol3.3c .\" .\" fileset_database@l3tol.3c PROGRAMING-MAN .\" $Header: ltostr.3c,v 74.1 95/05/10 21:07:18 ssa Exp $ .TA l .TH ltostr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ltostr(), ltostr_r(), ultostr(), ultostr_r(), ltoa(), ltoa_r(), ultoa(), ultoa_r() \- convert long integers to strings .SH SYNOPSIS .C "#include " .PP .C "char *ltostr(long n, int base);" .PP .C "int ltostr_r(long n, int base, char *buffer, int buflen);" .PP .C "char *ultostr(unsigned long n, int base);" .PP .C "int ultostr_r(unsigned long n, int base, char *buffer, int buflen);" .PP .C "char *ltoa(long n);" .PP .C "int ltoa_r(long n, char *buffer, int buflen);" .PP .C "char *ultoa(unsigned long n);" .PP .C "int ultoa_r(unsigned long n, char *buffer, int buflen);" .SH DESCRIPTION .RS .TP 15 .CR ltostr() Convert a signed long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ultostr() Convert an unsigned long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ltoa() Convert a signed long integer to the corresponding base 10 string representation, returning a pointer to the result. .TP .CR ultoa() Convert an unsigned long integer to the corresponding base 10 string representation, returning a pointer to the result. .RE .PP These functions are smaller and faster than using .CR sprintf() for simple conversions (see .IR printf (3S)). .SS Reentrant Interfaces For the reentrant .CR "(_r)" interfaces, the result string is passed back in the supplied buffer. If the buffer is of insufficient length, .CR \(mi1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .SH ERRORS If the value of .I base is not between 2 and 36, .CR ltostr() and .CR ultostr() return NULL and set the external variable .CR errno to ERANGE. The reentrant versions .RC ( ltostr_r() " and " ultostr_r() ) return .CR \(mi1 and set the external variable .CR errno to ERANGE. .SH WARNINGS The return values for .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() point to static data whose content is overwritten by each call. .PP .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() are unsafe in multi-thread applications. .CR ltostr_r() , .CR ultostr_r() , .CR ltoa_r() , and .CR ultoa_r() are MT-Safe and should be used instead. .SH AUTHOR .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() were developed by HP. .SH SEE ALSO printf(3C), strtol(3C), printf(3S). .\" .\" index@\f4ltostr()\f1 \- convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ltostr_r()\f1 \- convert long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa()\f1 \- convert long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa_r()\f1 \- convert long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr()\f1 \- convert unsigned long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr_r()\f1 \- convert unsigned long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa()\f1 \- convert unsigned long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa_r()\f1 \- convert unsigned long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f1convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f1long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1unsigned long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1integer, long, convert to string,@@@\f3ltostr(3C)\f1 .\" index@\f1string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1decimal ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" .\" toc@\f3ltostr(3C)\f1:\0\0\f4ltostr()\f1, \f4ltostr_r()\f1, \f4ultostr()\f1, \f4ultostr_r()\f1, \f4ltoa()\f1, \n\f4ltoa_r()\f1, \f4ultoa()\f1, \f4ultoa_r()\f1@@@convert long integers to strings .\" toc@\f4ltostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr()\f1:\0\0unsigned long to ASCII@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa()\f1:\0\0long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa_r()\f1:\0\0long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa()\f1:\0\0unsigned long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa_r()\f1:\0\0unsigned long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" links@ltostr.3c ltostr_r.3c .\" links@ltostr.3c ultostr.3c .\" links@ltostr.3c ultostr_r.3c .\" links@ltostr.3c ultoa.3c .\" links@ltostr.3c ultoa_r.3c .\" links@ltostr.3c ltoa.3c .\" links@ltostr.3c ltoa_r.3c .\" $Header: ltostr.3c,v 74.1 95/05/10 21:07:18 ssa Exp $ .TA l .TH ltostr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ltostr(), ltostr_r(), ultostr(), ultostr_r(), ltoa(), ltoa_r(), ultoa(), ultoa_r() \- convert long integers to strings .SH SYNOPSIS .C "#include " .PP .C "char *ltostr(long n, int base);" .PP .C "int ltostr_r(long n, int base, char *buffer, int buflen);" .PP .C "char *ultostr(unsigned long n, int base);" .PP .C "int ultostr_r(unsigned long n, int base, char *buffer, int buflen);" .PP .C "char *ltoa(long n);" .PP .C "int ltoa_r(long n, char *buffer, int buflen);" .PP .C "char *ultoa(unsigned long n);" .PP .C "int ultoa_r(unsigned long n, char *buffer, int buflen);" .SH DESCRIPTION .RS .TP 15 .CR ltostr() Convert a signed long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ultostr() Convert an unsigned long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ltoa() Convert a signed long integer to the corresponding base 10 string representation, returning a pointer to the result. .TP .CR ultoa() Convert an unsigned long integer to the corresponding base 10 string representation, returning a pointer to the result. .RE .PP These functions are smaller and faster than using .CR sprintf() for simple conversions (see .IR printf (3S)). .SS Reentrant Interfaces For the reentrant .CR "(_r)" interfaces, the result string is passed back in the supplied buffer. If the buffer is of insufficient length, .CR \(mi1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .SH ERRORS If the value of .I base is not between 2 and 36, .CR ltostr() and .CR ultostr() return NULL and set the external variable .CR errno to ERANGE. The reentrant versions .RC ( ltostr_r() " and " ultostr_r() ) return .CR \(mi1 and set the external variable .CR errno to ERANGE. .SH WARNINGS The return values for .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() point to static data whose content is overwritten by each call. .PP .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() are unsafe in multi-thread applications. .CR ltostr_r() , .CR ultostr_r() , .CR ltoa_r() , and .CR ultoa_r() are MT-Safe and should be used instead. .SH AUTHOR .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() were developed by HP. .SH SEE ALSO printf(3C), strtol(3C), printf(3S). .\" .\" index@\f4ltostr()\f1 \- convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ltostr_r()\f1 \- convert long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa()\f1 \- convert long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa_r()\f1 \- convert long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr()\f1 \- convert unsigned long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr_r()\f1 \- convert unsigned long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa()\f1 \- convert unsigned long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa_r()\f1 \- convert unsigned long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f1convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f1long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1unsigned long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1integer, long, convert to string,@@@\f3ltostr(3C)\f1 .\" index@\f1string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1decimal ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" .\" toc@\f3ltostr(3C)\f1:\0\0\f4ltostr()\f1, \f4ltostr_r()\f1, \f4ultostr()\f1, \f4ultostr_r()\f1, \f4ltoa()\f1, \n\f4ltoa_r()\f1, \f4ultoa()\f1, \f4ultoa_r()\f1@@@convert long integers to strings .\" toc@\f4ltostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr()\f1:\0\0unsigned long to ASCII@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa()\f1:\0\0long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa_r()\f1:\0\0long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa()\f1:\0\0unsigned long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa_r()\f1:\0\0unsigned long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" links@ltostr.3c ltostr_r.3c .\" links@ltostr.3c ultostr.3c .\" links@ltostr.3c ultostr_r.3c .\" links@ltostr.3c ultoa.3c .\" links@ltostr.3c ultoa_r.3c .\" links@ltostr.3c ltoa.3c .\" links@ltostr.3c ltoa_r.3c .\" $Header: malloc.3c,v 72.6 94/11/15 09:55:17 ssa Exp $ .TA m .TH malloc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME malloc(), free(), realloc(), calloc(), valloc(), mallopt(), mallinfo(), memorymap(), alloca() \- main memory allocator .SH SYNOPSIS .C "#include " .PP .C "void *malloc(size_t size);" .PP .C "void *calloc(size_t nelem, size_t elsize);" .PP .C "void *realloc(void *ptr, size_t size);" .PP .C "void *valloc(size_t size);" .PP .C "void free(void *ptr);" .PP .C "void memorymap(int show_stats);" .PP .C " " .PP .C "#include " .PP .C "void *alloca(size_t size);" .SH SYSTEM V SYNOPSIS .C "#include " .PP .C "char *malloc(unsigned size);" .PP .C "void free(char *ptr);" .PP .C "char *realloc(char *ptr, unsigned size);" .PP .C "char *calloc(unsigned nelem, unsigned elsize);" .PP .C "int mallopt(int cmd, int value);" .PP .C "struct mallinfo mallinfo(void);" .SS Remarks The functionality in the old .IR malloc (3X) package has been incorporated into .IR malloc (3C). The library .RC ( /usr/lib/libmalloc.a ) corresponding to the .CR -lmalloc linker option is now an empty library. Makefiles that reference this library will continue to work. Applications that used the .IR malloc (3X) package should still work properly with the new .IR malloc (3C) package. If the old versions must be used, they are provided in files .CR /usr/old/libmalloc3x.a and .CR /usr/old/libmalloc3c.o for Release 8.07 only. .SH DESCRIPTION The functions described in this manual entry provide a simple, general purpose memory allocation package: .RS .TP 17 .C malloc() Allocates space for a block of at least .I size bytes, but does not initialize the space. .TP .C calloc() Allocates space for an array of .I nelem elements, each of size .I elsize bytes, and initializes the space to zeros. Actual amount of space allocated will be at least .I nelem * elsize bytes. .TP .C realloc() Changes the size of the block pointed to by .I ptr to .I size bytes and returns a pointer to the (possibly moved) block. Existing contents are unchanged up to the lesser of the new and old sizes. If .I ptr is a NULL pointer, .CR realloc() behaves like .CR malloc() for the specified size. If .I size is zero and .I ptr is not a NULL pointer, the object it points to is freed and NULL is returned. .TP .C valloc() Allocates space for a block of at least .I size bytes starting on a boundary aligned to a multiple of the value returned by .IR sysconf(__SC_PAGESIZE) . This space is uninitialized. .TP .C free() Deallocates the space pointed to by .I ptr (a pointer to a block previously allocated by .CR malloc() , .CR realloc() , or .CR calloc() ) and makes the space available for further allocation. If .I ptr is a NULL pointer, no action occurs. .TP .C mallopt() Provides for control over the allocation algorithm and other options in the .IR malloc (3C) package. The available values for .I cmd are: .RS .RS .TP 15 .C M_MXFAST Set .IR maxfast to .IR value . The algorithm allocates all blocks below the size of .IR maxfast in large groups, then doles them out very quickly. The default value for .IR maxfast is zero. .TP .C M_NLBLKS Set .IR numlblks to .IR value . The above mentioned ``large groups'' each contain .I numlblks blocks. .I numlblks must be greater than 1. The default value for .I numlblks is .CR 100 . .TP .C M_GRAIN Set .I grain to .IR value . The sizes of all blocks smaller than .I maxfast are considered to be rounded up to the nearest multiple of .IR grain . .I grain must be greater than zero. The default value of .I grain is the smallest number of bytes that can accommodate alignment of any data type. .I value is rounded up to a multiple of the default when .I grain is set. .TP .C M_KEEP Preserve data in a freed block until the next .CR malloc() , .CR realloc() , or .CR calloc() . This option is provided only for compatibility with the old version of .CR malloc() and is not recommended. .TP .C M_BLOCK Block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option is provided for those who need to write signal handlers that allocate memory. When set, the .IR malloc (3C) routines can be called from within signal handlers (they become re-entrant). Default action is .I not to block all blockable signals. .TP .C M_UBLOCK Do not block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option cancels signal blocking initiated by the .CR M_BLOCK option. .RE .RE .IP These values are defined in the .CR header file. .IP .CR mallopt() can be called repeatedly, but must not be called after the first small block is allocated (unless .I cmd is set to .CR M_BLOCK or .CR M_UBLOCK ). .TP .C mallinfo() Provides instrumentation describing space usage, but cannot be called until the first small block is allocated. It returns the structure: .nf .IP .C "struct mallinfo {" .C " int arena; /* total space in arena */" .C " int ordblks; /* number of ordinary blocks */" .C " int smblks; /* number of small blocks */" .C " int hblkhd; /* space in holding block headers */" .C " int hblks; /* number of holding blocks */" .C " int usmblks /* space in small blocks in use */" .C " int fsmblks /* space in free small blocks */" .C " int uordblks; /* space in ordinary blocks in use */" .C " int fordblks; /* space in free ordinary blocks */" .C " int keepcost; /* space penalty if keep option is used */" .C } .fi .IP This structure is defined in the .CR header file. .RE .PP Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. .RS .TP 17 .C memorymap() Can be used to display the contents of the memory allocator. A list of addresses and block descriptions is written (using .CR printf() ) to standard output. If the value of the .I show_stats parameter is 1, statistics concerning number of blocks and sizes used will also be written. If the value is zero, only the memory map will be written. .IP The addresses and sizes displayed by .CR memorymap() may not correspond to those requested by an application. The size of a block (as viewed by the allocator) includes header information and padding to properly align the block. The address is also offset by a certain amount to accommodate the header information. .TP .C alloca() Allocates space from the stack of the caller for a block of at least .I size bytes, but does not initialize the space. The space is automatically freed when the calling routine exits. .IP Memory returned by .CR alloca() is not related to memory allocated by other memory allocation functions. Behavior of addresses returned by .CR alloca() as parameters to other memory functions is undefined. .IP The implementation of this routine is system dependent and its use is discouraged. .RE .SH RETURN VALUE Upon successful completion, .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. Otherwise, they return a NULL pointer. If .CR realloc() returns a NULL pointer, the memory pointed to by the original pointer is left intact. .PP .CR mallopt() returns zero for success and nonzero for failure. .SH DIAGNOSTICS .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a NULL pointer if there is no available memory, or if the memory managed by .CR malloc() has been detectably corrupted. This memory may become corrupted if data is stored outside the bounds of a block, or if an invalid pointer (a pointer not generated by .CR malloc() , .CR realloc() , or .CR calloc() ) is passed as an argument to .CR free() or .CR realloc() . .PP If .CR mallopt() is called after any allocation of a small block and .I cmd is not set to .CR M_BLOCK or .CR M_UBLOCK , or if .I cmd or .I value is invalid, nonzero is returned. Otherwise, it returns zero. .SH ERRORS .RS .TP 17 [ENOMEM] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to ENOMEM and return a NULL pointer when an out-of-memory condition arises. .TP [EINVAL] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to EINVAL and return a NULL pointer when the memory being managed by .CR malloc() has been detectably corrupted. .SH WARNINGS .CR malloc() functions use .CR brk() and .CR sbrk() (see .IR brk (2)) to increase the address space of a process. Therefore, an application program that uses .CR brk() or .CR sbrk() must not use them to decrease the address space, because this confuses the .CR malloc() functions. .PP .CR free() and .CR realloc() do not check their pointer argument for validity. .PP If .CR free() or .CR realloc() is passed a pointer that was not the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() , or if space assigned by an allocation function is overrun, loss of data, a memory fault, bus error, or an infinite loop may occur at that time or during any subsequent call to .CR malloc() , .CR realloc() , .CR calloc() , .CR valloc() , or .CR free() . .PP The following actions are not supported and cause undesirable effects: .RS .TP 3 \(bu Attempting to .CR free() or .CR realloc() a pointer not generated as the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() . .RE .PP The following actions are strongly discouraged and may be unsupported in a future implementation of .CR malloc() : .RS .TP 3 \(bu attempting to .CR free() the same block twice, .TP \(bu depending on unmodified contents of a block after it has been freed. .RE .PP Undocumented features of earlier memory allocators have not been duplicated. .SH COMPATIBILITY The only external difference between the old .IR malloc (3X) allocator and the .IR malloc (3C) allocator is that the old allocator would return a NULL pointer for a request of zero bytes. The .IR malloc (3C) allocator returns a valid memory address. This is not a concern for most applications. .ift .br .ift .ne 4 .PP Although the current implementation of .IR malloc (3C) allows for freeing a block twice and does not corrupt the contents of a block after it is freed (until the next call to .CR realloc() , .CR calloc() , .CR malloc() , or .CR valloc() ), support for these features may be discontinued in a future implementation of .IR malloc (3C) and should not be used. .SH SEE ALSO brk(2), errno(2). .SH STANDARDS CONFORMANCE .CR malloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR calloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR free() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mallinfo() ": SVID2, XPG2" .PP .CR mallopt() ": SVID2, SVID3, XPG2" .PP .CR realloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4malloc()\f1 \- allocate block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4free()\f1 \- release allocated block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4realloc()\f1 \- change size of allocated memory block@@@\f3malloc(3C)\f1 .\" index@\f4calloc()\f1 \- allocate memory for array@@@\f3malloc(3C)\f1 .\" index@\f4mallopt()\f1 \- control memory space allocation@@@\f3malloc(3C)\f1 .\" index@\f4mallinfo()\f1 \- display memory space usage@@@\f3malloc(3C)\f1 .\" index@\f4memorymap()\f1 \- display contents of memory allocator@@@\f3malloc(3C)\f1 .\" index@\f4alloca()\f1 \- allocate space from the stack@@@\f3malloc(3C)\f1 .\" index@\f4valloc()\f1 \- allocate space on boundary aligned to sysconf value@@@\f3malloc(3C)\f1 .\" index@\f1main memory allocator@@@\f3malloc(3C)\f1 .\" index@\f1memory allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1main memory space usage, display@@@\f3malloc(3C)\f1 .\" index@\f1main memory space allocation, control@@@\f3malloc(3C)\f1 .\" .\" toc@\f3malloc(3C)\f1:\0\0\f4alloca()\f1, \f4calloc()\f1, \f4free()\f1, \f4mallinfo()\f1,\n\f4malloc()\f1, \f4mallopt()\f1, \f4memorymap()\f1, \f4realloc()\f1, \f4valloc()\f1@@@main memory allocator\f1 .\" .\" toc@\f4free()\f1:\0\0release allocated block of main memory@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4realloc()\f1:\0\0change size of allocated memory block@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4calloc()\f1:\0\0allocate memory for array@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4valloc()\f1:\0\0allocate space on boundary aligned to sysconf value@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallopt()\f1:\0\0control memory space allocation@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallinfo()\f1:\0\0display memory space usage@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4memorymap()\f1:\0\0display contents of memory allocator@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4alloca()\f1:\0\0allocate space from the stack@@@\f1see \f3malloc(3C)\f1 .\" .\" links@malloc.3c free.3c .\" links@malloc.3c realloc.3c .\" links@malloc.3c calloc.3c .\" links@malloc.3c valloc.3c .\" links@malloc.3c mallopt.3c .\" links@malloc.3c mallinfo.3c .\" links@malloc.3c memorymap.3c .\" links@malloc.3c alloca.3c .\" $Header: malloc.3c,v 72.6 94/11/15 09:55:17 ssa Exp $ .TA m .TH malloc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME malloc(), free(), realloc(), calloc(), valloc(), mallopt(), mallinfo(), memorymap(), alloca() \- main memory allocator .SH SYNOPSIS .C "#include " .PP .C "void *malloc(size_t size);" .PP .C "void *calloc(size_t nelem, size_t elsize);" .PP .C "void *realloc(void *ptr, size_t size);" .PP .C "void *valloc(size_t size);" .PP .C "void free(void *ptr);" .PP .C "void memorymap(int show_stats);" .PP .C " " .PP .C "#include " .PP .C "void *alloca(size_t size);" .SH SYSTEM V SYNOPSIS .C "#include " .PP .C "char *malloc(unsigned size);" .PP .C "void free(char *ptr);" .PP .C "char *realloc(char *ptr, unsigned size);" .PP .C "char *calloc(unsigned nelem, unsigned elsize);" .PP .C "int mallopt(int cmd, int value);" .PP .C "struct mallinfo mallinfo(void);" .SS Remarks The functionality in the old .IR malloc (3X) package has been incorporated into .IR malloc (3C). The library .RC ( /usr/lib/libmalloc.a ) corresponding to the .CR -lmalloc linker option is now an empty library. Makefiles that reference this library will continue to work. Applications that used the .IR malloc (3X) package should still work properly with the new .IR malloc (3C) package. If the old versions must be used, they are provided in files .CR /usr/old/libmalloc3x.a and .CR /usr/old/libmalloc3c.o for Release 8.07 only. .SH DESCRIPTION The functions described in this manual entry provide a simple, general purpose memory allocation package: .RS .TP 17 .C malloc() Allocates space for a block of at least .I size bytes, but does not initialize the space. .TP .C calloc() Allocates space for an array of .I nelem elements, each of size .I elsize bytes, and initializes the space to zeros. Actual amount of space allocated will be at least .I nelem * elsize bytes. .TP .C realloc() Changes the size of the block pointed to by .I ptr to .I size bytes and returns a pointer to the (possibly moved) block. Existing contents are unchanged up to the lesser of the new and old sizes. If .I ptr is a NULL pointer, .CR realloc() behaves like .CR malloc() for the specified size. If .I size is zero and .I ptr is not a NULL pointer, the object it points to is freed and NULL is returned. .TP .C valloc() Allocates space for a block of at least .I size bytes starting on a boundary aligned to a multiple of the value returned by .IR sysconf(__SC_PAGESIZE) . This space is uninitialized. .TP .C free() Deallocates the space pointed to by .I ptr (a pointer to a block previously allocated by .CR malloc() , .CR realloc() , or .CR calloc() ) and makes the space available for further allocation. If .I ptr is a NULL pointer, no action occurs. .TP .C mallopt() Provides for control over the allocation algorithm and other options in the .IR malloc (3C) package. The available values for .I cmd are: .RS .RS .TP 15 .C M_MXFAST Set .IR maxfast to .IR value . The algorithm allocates all blocks below the size of .IR maxfast in large groups, then doles them out very quickly. The default value for .IR maxfast is zero. .TP .C M_NLBLKS Set .IR numlblks to .IR value . The above mentioned ``large groups'' each contain .I numlblks blocks. .I numlblks must be greater than 1. The default value for .I numlblks is .CR 100 . .TP .C M_GRAIN Set .I grain to .IR value . The sizes of all blocks smaller than .I maxfast are considered to be rounded up to the nearest multiple of .IR grain . .I grain must be greater than zero. The default value of .I grain is the smallest number of bytes that can accommodate alignment of any data type. .I value is rounded up to a multiple of the default when .I grain is set. .TP .C M_KEEP Preserve data in a freed block until the next .CR malloc() , .CR realloc() , or .CR calloc() . This option is provided only for compatibility with the old version of .CR malloc() and is not recommended. .TP .C M_BLOCK Block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option is provided for those who need to write signal handlers that allocate memory. When set, the .IR malloc (3C) routines can be called from within signal handlers (they become re-entrant). Default action is .I not to block all blockable signals. .TP .C M_UBLOCK Do not block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option cancels signal blocking initiated by the .CR M_BLOCK option. .RE .RE .IP These values are defined in the .CR header file. .IP .CR mallopt() can be called repeatedly, but must not be called after the first small block is allocated (unless .I cmd is set to .CR M_BLOCK or .CR M_UBLOCK ). .TP .C mallinfo() Provides instrumentation describing space usage, but cannot be called until the first small block is allocated. It returns the structure: .nf .IP .C "struct mallinfo {" .C " int arena; /* total space in arena */" .C " int ordblks; /* number of ordinary blocks */" .C " int smblks; /* number of small blocks */" .C " int hblkhd; /* space in holding block headers */" .C " int hblks; /* number of holding blocks */" .C " int usmblks /* space in small blocks in use */" .C " int fsmblks /* space in free small blocks */" .C " int uordblks; /* space in ordinary blocks in use */" .C " int fordblks; /* space in free ordinary blocks */" .C " int keepcost; /* space penalty if keep option is used */" .C } .fi .IP This structure is defined in the .CR header file. .RE .PP Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. .RS .TP 17 .C memorymap() Can be used to display the contents of the memory allocator. A list of addresses and block descriptions is written (using .CR printf() ) to standard output. If the value of the .I show_stats parameter is 1, statistics concerning number of blocks and sizes used will also be written. If the value is zero, only the memory map will be written. .IP The addresses and sizes displayed by .CR memorymap() may not correspond to those requested by an application. The size of a block (as viewed by the allocator) includes header information and padding to properly align the block. The address is also offset by a certain amount to accommodate the header information. .TP .C alloca() Allocates space from the stack of the caller for a block of at least .I size bytes, but does not initialize the space. The space is automatically freed when the calling routine exits. .IP Memory returned by .CR alloca() is not related to memory allocated by other memory allocation functions. Behavior of addresses returned by .CR alloca() as parameters to other memory functions is undefined. .IP The implementation of this routine is system dependent and its use is discouraged. .RE .SH RETURN VALUE Upon successful completion, .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. Otherwise, they return a NULL pointer. If .CR realloc() returns a NULL pointer, the memory pointed to by the original pointer is left intact. .PP .CR mallopt() returns zero for success and nonzero for failure. .SH DIAGNOSTICS .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a NULL pointer if there is no available memory, or if the memory managed by .CR malloc() has been detectably corrupted. This memory may become corrupted if data is stored outside the bounds of a block, or if an invalid pointer (a pointer not generated by .CR malloc() , .CR realloc() , or .CR calloc() ) is passed as an argument to .CR free() or .CR realloc() . .PP If .CR mallopt() is called after any allocation of a small block and .I cmd is not set to .CR M_BLOCK or .CR M_UBLOCK , or if .I cmd or .I value is invalid, nonzero is returned. Otherwise, it returns zero. .SH ERRORS .RS .TP 17 [ENOMEM] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to ENOMEM and return a NULL pointer when an out-of-memory condition arises. .TP [EINVAL] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to EINVAL and return a NULL pointer when the memory being managed by .CR malloc() has been detectably corrupted. .SH WARNINGS .CR malloc() functions use .CR brk() and .CR sbrk() (see .IR brk (2)) to increase the address space of a process. Therefore, an application program that uses .CR brk() or .CR sbrk() must not use them to decrease the address space, because this confuses the .CR malloc() functions. .PP .CR free() and .CR realloc() do not check their pointer argument for validity. .PP If .CR free() or .CR realloc() is passed a pointer that was not the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() , or if space assigned by an allocation function is overrun, loss of data, a memory fault, bus error, or an infinite loop may occur at that time or during any subsequent call to .CR malloc() , .CR realloc() , .CR calloc() , .CR valloc() , or .CR free() . .PP The following actions are not supported and cause undesirable effects: .RS .TP 3 \(bu Attempting to .CR free() or .CR realloc() a pointer not generated as the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() . .RE .PP The following actions are strongly discouraged and may be unsupported in a future implementation of .CR malloc() : .RS .TP 3 \(bu attempting to .CR free() the same block twice, .TP \(bu depending on unmodified contents of a block after it has been freed. .RE .PP Undocumented features of earlier memory allocators have not been duplicated. .SH COMPATIBILITY The only external difference between the old .IR malloc (3X) allocator and the .IR malloc (3C) allocator is that the old allocator would return a NULL pointer for a request of zero bytes. The .IR malloc (3C) allocator returns a valid memory address. This is not a concern for most applications. .ift .br .ift .ne 4 .PP Although the current implementation of .IR malloc (3C) allows for freeing a block twice and does not corrupt the contents of a block after it is freed (until the next call to .CR realloc() , .CR calloc() , .CR malloc() , or .CR valloc() ), support for these features may be discontinued in a future implementation of .IR malloc (3C) and should not be used. .SH SEE ALSO brk(2), errno(2). .SH STANDARDS CONFORMANCE .CR malloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR calloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR free() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mallinfo() ": SVID2, XPG2" .PP .CR mallopt() ": SVID2, SVID3, XPG2" .PP .CR realloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4malloc()\f1 \- allocate block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4free()\f1 \- release allocated block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4realloc()\f1 \- change size of allocated memory block@@@\f3malloc(3C)\f1 .\" index@\f4calloc()\f1 \- allocate memory for array@@@\f3malloc(3C)\f1 .\" index@\f4mallopt()\f1 \- control memory space allocation@@@\f3malloc(3C)\f1 .\" index@\f4mallinfo()\f1 \- display memory space usage@@@\f3malloc(3C)\f1 .\" index@\f4memorymap()\f1 \- display contents of memory allocator@@@\f3malloc(3C)\f1 .\" index@\f4alloca()\f1 \- allocate space from the stack@@@\f3malloc(3C)\f1 .\" index@\f4valloc()\f1 \- allocate space on boundary aligned to sysconf value@@@\f3malloc(3C)\f1 .\" index@\f1main memory allocator@@@\f3malloc(3C)\f1 .\" index@\f1memory allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1main memory space usage, display@@@\f3malloc(3C)\f1 .\" index@\f1main memory space allocation, control@@@\f3malloc(3C)\f1 .\" .\" toc@\f3malloc(3C)\f1:\0\0\f4alloca()\f1, \f4calloc()\f1, \f4free()\f1, \f4mallinfo()\f1,\n\f4malloc()\f1, \f4mallopt()\f1, \f4memorymap()\f1, \f4realloc()\f1, \f4valloc()\f1@@@main memory allocator\f1 .\" .\" toc@\f4free()\f1:\0\0release allocated block of main memory@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4realloc()\f1:\0\0change size of allocated memory block@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4calloc()\f1:\0\0allocate memory for array@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4valloc()\f1:\0\0allocate space on boundary aligned to sysconf value@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallopt()\f1:\0\0control memory space allocation@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallinfo()\f1:\0\0display memory space usage@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4memorymap()\f1:\0\0display contents of memory allocator@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4alloca()\f1:\0\0allocate space from the stack@@@\f1see \f3malloc(3C)\f1 .\" .\" links@malloc.3c free.3c .\" links@malloc.3c realloc.3c .\" links@malloc.3c calloc.3c .\" links@malloc.3c valloc.3c .\" links@malloc.3c mallopt.3c .\" links@malloc.3c mallinfo.3c .\" links@malloc.3c memorymap.3c .\" links@malloc.3c alloca.3c .\" $Header: malloc.3c,v 72.6 94/11/15 09:55:17 ssa Exp $ .TA m .TH malloc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME malloc(), free(), realloc(), calloc(), valloc(), mallopt(), mallinfo(), memorymap(), alloca() \- main memory allocator .SH SYNOPSIS .C "#include " .PP .C "void *malloc(size_t size);" .PP .C "void *calloc(size_t nelem, size_t elsize);" .PP .C "void *realloc(void *ptr, size_t size);" .PP .C "void *valloc(size_t size);" .PP .C "void free(void *ptr);" .PP .C "void memorymap(int show_stats);" .PP .C " " .PP .C "#include " .PP .C "void *alloca(size_t size);" .SH SYSTEM V SYNOPSIS .C "#include " .PP .C "char *malloc(unsigned size);" .PP .C "void free(char *ptr);" .PP .C "char *realloc(char *ptr, unsigned size);" .PP .C "char *calloc(unsigned nelem, unsigned elsize);" .PP .C "int mallopt(int cmd, int value);" .PP .C "struct mallinfo mallinfo(void);" .SS Remarks The functionality in the old .IR malloc (3X) package has been incorporated into .IR malloc (3C). The library .RC ( /usr/lib/libmalloc.a ) corresponding to the .CR -lmalloc linker option is now an empty library. Makefiles that reference this library will continue to work. Applications that used the .IR malloc (3X) package should still work properly with the new .IR malloc (3C) package. If the old versions must be used, they are provided in files .CR /usr/old/libmalloc3x.a and .CR /usr/old/libmalloc3c.o for Release 8.07 only. .SH DESCRIPTION The functions described in this manual entry provide a simple, general purpose memory allocation package: .RS .TP 17 .C malloc() Allocates space for a block of at least .I size bytes, but does not initialize the space. .TP .C calloc() Allocates space for an array of .I nelem elements, each of size .I elsize bytes, and initializes the space to zeros. Actual amount of space allocated will be at least .I nelem * elsize bytes. .TP .C realloc() Changes the size of the block pointed to by .I ptr to .I size bytes and returns a pointer to the (possibly moved) block. Existing contents are unchanged up to the lesser of the new and old sizes. If .I ptr is a NULL pointer, .CR realloc() behaves like .CR malloc() for the specified size. If .I size is zero and .I ptr is not a NULL pointer, the object it points to is freed and NULL is returned. .TP .C valloc() Allocates space for a block of at least .I size bytes starting on a boundary aligned to a multiple of the value returned by .IR sysconf(__SC_PAGESIZE) . This space is uninitialized. .TP .C free() Deallocates the space pointed to by .I ptr (a pointer to a block previously allocated by .CR malloc() , .CR realloc() , or .CR calloc() ) and makes the space available for further allocation. If .I ptr is a NULL pointer, no action occurs. .TP .C mallopt() Provides for control over the allocation algorithm and other options in the .IR malloc (3C) package. The available values for .I cmd are: .RS .RS .TP 15 .C M_MXFAST Set .IR maxfast to .IR value . The algorithm allocates all blocks below the size of .IR maxfast in large groups, then doles them out very quickly. The default value for .IR maxfast is zero. .TP .C M_NLBLKS Set .IR numlblks to .IR value . The above mentioned ``large groups'' each contain .I numlblks blocks. .I numlblks must be greater than 1. The default value for .I numlblks is .CR 100 . .TP .C M_GRAIN Set .I grain to .IR value . The sizes of all blocks smaller than .I maxfast are considered to be rounded up to the nearest multiple of .IR grain . .I grain must be greater than zero. The default value of .I grain is the smallest number of bytes that can accommodate alignment of any data type. .I value is rounded up to a multiple of the default when .I grain is set. .TP .C M_KEEP Preserve data in a freed block until the next .CR malloc() , .CR realloc() , or .CR calloc() . This option is provided only for compatibility with the old version of .CR malloc() and is not recommended. .TP .C M_BLOCK Block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option is provided for those who need to write signal handlers that allocate memory. When set, the .IR malloc (3C) routines can be called from within signal handlers (they become re-entrant). Default action is .I not to block all blockable signals. .TP .C M_UBLOCK Do not block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option cancels signal blocking initiated by the .CR M_BLOCK option. .RE .RE .IP These values are defined in the .CR header file. .IP .CR mallopt() can be called repeatedly, but must not be called after the first small block is allocated (unless .I cmd is set to .CR M_BLOCK or .CR M_UBLOCK ). .TP .C mallinfo() Provides instrumentation describing space usage, but cannot be called until the first small block is allocated. It returns the structure: .nf .IP .C "struct mallinfo {" .C " int arena; /* total space in arena */" .C " int ordblks; /* number of ordinary blocks */" .C " int smblks; /* number of small blocks */" .C " int hblkhd; /* space in holding block headers */" .C " int hblks; /* number of holding blocks */" .C " int usmblks /* space in small blocks in use */" .C " int fsmblks /* space in free small blocks */" .C " int uordblks; /* space in ordinary blocks in use */" .C " int fordblks; /* space in free ordinary blocks */" .C " int keepcost; /* space penalty if keep option is used */" .C } .fi .IP This structure is defined in the .CR header file. .RE .PP Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. .RS .TP 17 .C memorymap() Can be used to display the contents of the memory allocator. A list of addresses and block descriptions is written (using .CR printf() ) to standard output. If the value of the .I show_stats parameter is 1, statistics concerning number of blocks and sizes used will also be written. If the value is zero, only the memory map will be written. .IP The addresses and sizes displayed by .CR memorymap() may not correspond to those requested by an application. The size of a block (as viewed by the allocator) includes header information and padding to properly align the block. The address is also offset by a certain amount to accommodate the header information. .TP .C alloca() Allocates space from the stack of the caller for a block of at least .I size bytes, but does not initialize the space. The space is automatically freed when the calling routine exits. .IP Memory returned by .CR alloca() is not related to memory allocated by other memory allocation functions. Behavior of addresses returned by .CR alloca() as parameters to other memory functions is undefined. .IP The implementation of this routine is system dependent and its use is discouraged. .RE .SH RETURN VALUE Upon successful completion, .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. Otherwise, they return a NULL pointer. If .CR realloc() returns a NULL pointer, the memory pointed to by the original pointer is left intact. .PP .CR mallopt() returns zero for success and nonzero for failure. .SH DIAGNOSTICS .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a NULL pointer if there is no available memory, or if the memory managed by .CR malloc() has been detectably corrupted. This memory may become corrupted if data is stored outside the bounds of a block, or if an invalid pointer (a pointer not generated by .CR malloc() , .CR realloc() , or .CR calloc() ) is passed as an argument to .CR free() or .CR realloc() . .PP If .CR mallopt() is called after any allocation of a small block and .I cmd is not set to .CR M_BLOCK or .CR M_UBLOCK , or if .I cmd or .I value is invalid, nonzero is returned. Otherwise, it returns zero. .SH ERRORS .RS .TP 17 [ENOMEM] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to ENOMEM and return a NULL pointer when an out-of-memory condition arises. .TP [EINVAL] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to EINVAL and return a NULL pointer when the memory being managed by .CR malloc() has been detectably corrupted. .SH WARNINGS .CR malloc() functions use .CR brk() and .CR sbrk() (see .IR brk (2)) to increase the address space of a process. Therefore, an application program that uses .CR brk() or .CR sbrk() must not use them to decrease the address space, because this confuses the .CR malloc() functions. .PP .CR free() and .CR realloc() do not check their pointer argument for validity. .PP If .CR free() or .CR realloc() is passed a pointer that was not the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() , or if space assigned by an allocation function is overrun, loss of data, a memory fault, bus error, or an infinite loop may occur at that time or during any subsequent call to .CR malloc() , .CR realloc() , .CR calloc() , .CR valloc() , or .CR free() . .PP The following actions are not supported and cause undesirable effects: .RS .TP 3 \(bu Attempting to .CR free() or .CR realloc() a pointer not generated as the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() . .RE .PP The following actions are strongly discouraged and may be unsupported in a future implementation of .CR malloc() : .RS .TP 3 \(bu attempting to .CR free() the same block twice, .TP \(bu depending on unmodified contents of a block after it has been freed. .RE .PP Undocumented features of earlier memory allocators have not been duplicated. .SH COMPATIBILITY The only external difference between the old .IR malloc (3X) allocator and the .IR malloc (3C) allocator is that the old allocator would return a NULL pointer for a request of zero bytes. The .IR malloc (3C) allocator returns a valid memory address. This is not a concern for most applications. .ift .br .ift .ne 4 .PP Although the current implementation of .IR malloc (3C) allows for freeing a block twice and does not corrupt the contents of a block after it is freed (until the next call to .CR realloc() , .CR calloc() , .CR malloc() , or .CR valloc() ), support for these features may be discontinued in a future implementation of .IR malloc (3C) and should not be used. .SH SEE ALSO brk(2), errno(2). .SH STANDARDS CONFORMANCE .CR malloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR calloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR free() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mallinfo() ": SVID2, XPG2" .PP .CR mallopt() ": SVID2, SVID3, XPG2" .PP .CR realloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4malloc()\f1 \- allocate block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4free()\f1 \- release allocated block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4realloc()\f1 \- change size of allocated memory block@@@\f3malloc(3C)\f1 .\" index@\f4calloc()\f1 \- allocate memory for array@@@\f3malloc(3C)\f1 .\" index@\f4mallopt()\f1 \- control memory space allocation@@@\f3malloc(3C)\f1 .\" index@\f4mallinfo()\f1 \- display memory space usage@@@\f3malloc(3C)\f1 .\" index@\f4memorymap()\f1 \- display contents of memory allocator@@@\f3malloc(3C)\f1 .\" index@\f4alloca()\f1 \- allocate space from the stack@@@\f3malloc(3C)\f1 .\" index@\f4valloc()\f1 \- allocate space on boundary aligned to sysconf value@@@\f3malloc(3C)\f1 .\" index@\f1main memory allocator@@@\f3malloc(3C)\f1 .\" index@\f1memory allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1main memory space usage, display@@@\f3malloc(3C)\f1 .\" index@\f1main memory space allocation, control@@@\f3malloc(3C)\f1 .\" .\" toc@\f3malloc(3C)\f1:\0\0\f4alloca()\f1, \f4calloc()\f1, \f4free()\f1, \f4mallinfo()\f1,\n\f4malloc()\f1, \f4mallopt()\f1, \f4memorymap()\f1, \f4realloc()\f1, \f4valloc()\f1@@@main memory allocator\f1 .\" .\" toc@\f4free()\f1:\0\0release allocated block of main memory@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4realloc()\f1:\0\0change size of allocated memory block@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4calloc()\f1:\0\0allocate memory for array@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4valloc()\f1:\0\0allocate space on boundary aligned to sysconf value@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallopt()\f1:\0\0control memory space allocation@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallinfo()\f1:\0\0display memory space usage@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4memorymap()\f1:\0\0display contents of memory allocator@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4alloca()\f1:\0\0allocate space from the stack@@@\f1see \f3malloc(3C)\f1 .\" .\" links@malloc.3c free.3c .\" links@malloc.3c realloc.3c .\" links@malloc.3c calloc.3c .\" links@malloc.3c valloc.3c .\" links@malloc.3c mallopt.3c .\" links@malloc.3c mallinfo.3c .\" links@malloc.3c memorymap.3c .\" links@malloc.3c alloca.3c .\" $Header: matherr.3m,v 78.1 96/02/13 15:57:56 ssa Exp $ .\" name of actual manpage file for IC8 is matherr.3m .\" link statements reversed at end of manpage -- ajasper feb 13 1996 .TA m .TH _matherr 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME _matherr(\|) \- error-handling function (TO BE WITHDRAWN) .SH SYNOPSIS .C "#include " .PP .C "int _matherr(struct exception *x)" .br .C "{" .br .C " /* your math error handling here */" .br .C "}" .SH DESCRIPTION .CR _matherr() is invoked by some functions in the math library when errors are detected. Programmers can define their own procedures for handling errors by including a function named .CR _matherr() in their programs. .CR _matherr() must be of the form described above. When an error occurs, a pointer to the exception structure .I x is passed to the user-supplied .CR _matherr() function. This structure, which is declared in the .RC < math.h > header file and allocated on the stack by one of the math library internal routines, is as follows: .nf .IP .CR "struct exception {" .CR " int type;" .CR " char *name;" .CR " double arg1, arg2, retval;" .CR }; .fi .RE .PP The element .CR type is an integer describing the type of error that has occurred, from the following list of constants (defined in the header file): .RS .TP 15 .CR DOMAIN argument domain error .PD 0 .TP .CR SING argument singularity .TP .CR OVERFLOW overflow range error .TP .CR UNDERFLOW underflow range error .RE .PD .PP The element .CR name points to a string containing the name of the function that incurred the error. The variables .CR arg1 and .CR arg2 are the arguments with which the function was invoked. .CR retval is set to the default value that will be returned by the function unless the user's .CR _matherr() sets it to a different value. If there is only one argument, .CR arg1 is set to it, and .CR arg2 is undefined. .PP If the user's .CR _matherr() function returns non-zero, no error message is printed, and .CR errno is not set. .PP If .CR _matherr() is not supplied by the user, the default error-handling procedures (described in the man pages for the math functions) are invoked upon error, and the program continues. .PP When .CR _matherr() is called from a .CR float type math function (for example, .CR expf() or .CR logf() ), the argument(s) and default return value .RC ( arg1 , .CR arg2 , and .CR retval ) are converted to .CR double . If an argument is a NaN, it is converted to a .CR double NaN, without trapping, even if it is a signaling NaN. If a user-supplied .CR _matherr() function modifies .CR retval , the value is converted to .CR float when .CR _matherr() returns. If that conversion fails, then a signal is generated. Therefore, it is the responsibility of the user-supplied .CR _matherr() to select values for .CR retval that can be successfully converted to .CR float . .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .PP The .CR matherr() and .CR _matherr() functions are obsolete and will not be supported at the next release of HP-UX. The .CR matherr() function is not required by any version of XPG nor by ANSI C, and has not been part of any standard since SVID2. In the HP-UX math library, the SVID2 .CR matherr() function has been renamed to .CR _matherr() , and no error messages are printed to the standard error output. .CR _matherr() is provided in .CR libm.a in order to assist in supporting old programs. Executables that use the old .CR matherr() or .CR _matherr() will continue to run indefinitely, even on future releases of HP-UX. .PP However, if you intend to recompile or relink any of your current programs that use .CR matherr() or .CR _matherr() on a future release of HP\-UX, you should be aware that any function called .CR matherr() or .CR _matherr() will no longer be called in case of library errors. .PP If you want to intercept math library calls that experience argument errors, you should consider writing wrapper routines that intervene between the original caller and the math library. Such a wrapper could check the value of .CR errno after the math library function returns, and if appropriate, invoke your special error handler. .SH EXAMPLE .RS .sp .nf .ift .ft 4 .ift .ps +1 #include .ift .sp .5v .ifn .sp int _matherr(x) register struct exception *x; { switch (x->type) { case DOMAIN: /* change sqrt to return sqrt(-arg1), not 0 */ if (!strcmp(x->name, "sqrt")) { x->retval = sqrt(-x->arg1); return (0); /* set errno */ } else if (!strcmp(x->name, "sqrtf")) { x->retval = sqrtf(-x->arg1); return (0); /* set errno */ } case SING: /* all other domain or sing errors, print message and abort */ fprintf(stderr, "domain error in %s\en", x->name); abort( ); } return (0); /* all other errors, execute default procedure */ } .ift .ft .ift .ps .fi .RE .SH STANDARDS CONFORMANCE .CR matherr() ": SVID2" .\" .\" index@\f4_matherr()\f1 \- math library error-handling function@@@\f3_matherr(3M)\f1 .\" index@\f1math: math library error-handling function@@@\f3_matherr(3M)\f1 .\" index@\f1math library error-handling function@@@\f3_matherr(3M)\f1 .\" index@\f1error-handling function, math library@@@\f3_matherr(3M)\f1 .\" .\" toc@\f3_matherr(3M)\f1:\0\0\f4_matherr()\f1@@@error-handling function .\" .\" links@matherr.3m _matherr.3m .\" $Header: multibyte.3c,v 72.6 94/11/15 09:55:30 ssa Exp $ .TA m .TH multibyte 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mblen(\|), mbtowc(\|), mbstowcs(\|), wctomb(\|), wcstombs(\|) \- multibyte characters and strings conversions .SH SYNOPSIS .C "#include " .PP .C "int mblen(const char *s, size_t n);" .PP .C "int mbtowc(wchar_t *pwc, const char *s, size_t n);" .PP .C "int wctomb(char *s, wchar_t wchar);" .PP .C "size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);" .PP .C "size_t wcstombs(char *s, const wchar_t *pwcs, size_t n);" .SH DESCRIPTION A multibyte character is composed of one or more bytes that represent a "whole" character in a character encoding. A wide character (type of .CR wchar_t ) is composed of a fixed number of bytes whose code value can represent any character in a character encoding. .TP 12 .C mblen() Determine the number of bytes in the multibyte character pointed to by .IR s . Equivalent to: .IP .C "mbtowc((wchar_t *)0, s, n);" .IP If .I s is a null pointer, .I mblen returns a nonzero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .I mblen returns the number of bytes in the multibyte character if the next .I n or fewer bytes form a valid multibyte character, or return \-1 if they do not form a valid multibyte character. If .I s points to the null character, .I mblen returns 0. .TP .C mbtowc() Determine the number of bytes in the multibyte character pointed to by .IR s , determine the code for the value of type .C wchar_t corresponding to that multibyte character, then store the code in the object pointed to by .IR pwc . The value of the code corresponding to the null character is zero. At most .I n characters are examined, starting at the character pointed to by .IR s . .IP If .I s is a null pointer, .C mbtowc() returns a non-zero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .C mbtowc() returns the number of bytes in the converted multibyte character if the next .I n or fewer bytes form a valid multibyte character, or \-1 if they do not form a valid multibyte character. If .I s points to the null character, .C mbtowc() returns 0. The value returned is never greater than .I n or the value of the .C MB_CUR_MAX macro. .TP .C wctomb() Determine the number of bytes needed to represent the multibyte character corresponding to the code whose value is .I wchar and store the multibyte character representation in the array object pointed to by .IR s . At most .C MB_CUR_MAX characters are stored. .IP If .I s is a null pointer, .C wctomb() returns a nonzero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .C wctomb() returns the number of bytes in the multibyte character corresponding to the value of .IR wchar , or \-1 if the value of .I wchar does not correspond to a valid multibyte character. The value returned is never greater than the value of the .C MB_CUR_MAX macro. .TP .C mbstowcs() Convert a sequence of multibyte characters from the array pointed to by .I s into a sequence of corresponding codes and store these codes into the array pointed to by .IR pwcs , stopping after either .I n codes or a code with value zero (a converted null character) is stored. Each multibyte character is converted as if by a call to .CR mbtowc() . No more than .I n elements are modified in the array pointed to by .IR pwcs . .IP If an invalid multibyte character is encountered, .C mbstowcs() returns (size_t)\|\(mi\|1. Otherwise, .C mbstowcs() returns the number of array elements modified, not including a terminating zero code, if any. The array is not null- or zero-terminated if the value returned is .IR n . If .I pwcs is a null pointer, .C mbstowcs() returns the number of elements required for the wide-character-code array. .TP .C wcstombs() Convert a sequence of codes corresponding to multibyte characters from the array pointed to by .I pwcs into a sequence of multibyte characters and store them into the array pointed to by .IR s , stopping if a multibyte character exceeds the limit of .I n total bytes or if a null character is stored. Each code is converted as if by a call to .CR wctomb() . No more than .I n bytes are modified in the array pointed to by .IR s . .IP If a code is encountered that does not correspond to a valid multibyte character, .C wcstombs() returns (size_t)\|\(mi\|1. Otherwise, .C wcstombs() returns the number of bytes modified, not including a terminating null character, if any. The array is not null- or zero-terminated if the value returned is .IR n . If .I s is a null pointer, .C wcstombs() returns the number of bytes required for the character array. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the behavior of the multibyte character and string functions. .SH ERRORS .CR mblen() , .CR mbstowcs() , .CR mbtowc() , .C wcstombs() and .C wctomb() may fail and .C errno is set if the following condition is encountered: .RS .TP 15 .SM [EILSEQ] An invalid multibyte sequence or wide character code was found. .RE .SH WARNINGS With the exception of .SM ASCII characters, the code values of wide characters (type of .CR wchar_t ) are specific to the effective locale specified by the .C LC_CTYPE environment variable. These values may not be compatible with values obtained by specifying other locales that are supported now, or which may be supported in the future. It is recommended that wide character constants and wide string literals (see the .IR "C Reference Manual" ) not be used, and that wide character code values not be stored in files or devices because future standards may dictate changes in the code value assignments of the wide characters. However, wide character constants and wide string literals corresponding to the characters of the .SM ASCII code set can be safely used since their values are guaranteed to be the same as their .SM ASCII code set values. .SH AUTHOR The multibyte functions in this entry were developed by OSF and HP. .SH SEE ALSO setlocale(3C), wctype(3X). .SH STANDARDS CONFORMANCE .CR mblen() ": AES, SVID3, XPG4, ANSI C" .PP .CR mbstowcs() ": AES, SVID3, XPG4, ANSI C" .PP .CR mbtowc() ": AES, SVID3, XPG4, ANSI C" .PP .CR wcstombs() ": AES, SVID3, XPG4, ANSI C" .PP .CR wctomb() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4multibyte()\f1 \- multibyte characters and strings conversions@@@\f3multibyte(3C)\f1 .\" .\" index@\f4mblen()\f1 \- number of bytes in the multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4mbtowc()\f1 \- number of bytes in the multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4wctomb()\f1 \- number of bytes needed to represent multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4mbstowcs()\f1 \- convert sequence of multibyte characters@@@\f3multibyte(3C)\f1 .\" index@\f4wcstombs()\f1 \- convert sequence of codes corresponding to multibyte characters@@@\f3multibyte(3C)\f1 .\" .\" .\" index@\f1multibyte characters and strings conversions@@@\f3multibyte(3C)\f1 .\" index@\f1characters and strings conversions, multibyte@@@\f3multibyte(3C)\f1 .\" index@\f1strings and characters conversions, multibyte@@@\f3multibyte(3C)\f1 .\" index@\f1conversions, multibyte characters and strings@@@\f3multibyte(3C)\f1 .\" .\" toc@\f3multibyte(3C)\f1:\0\0\f4mblen()\f1, \f4mbtowc()\f1, \f4mbstowcs()\f1, \f4wctomb()\f1,\n \f4wcstombs()\f1@@@multibyte characters and strings conversions .\" toc@\f4mblen()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4mbstowcs()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4mbtowc()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4wctomb()\f1: multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4wctombs()\f1: multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" .\" links@multibyte.3c mblen.3c .\" links@multibyte.3c mbtowc.3c .\" links@multibyte.3c mbstowcs.3c .\" links@multibyte.3c wctomb.3c .\" links@multibyte.3c wcstombs.3c .\" $Header: multibyte.3c,v 72.6 94/11/15 09:55:30 ssa Exp $ .TA m .TH multibyte 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mblen(\|), mbtowc(\|), mbstowcs(\|), wctomb(\|), wcstombs(\|) \- multibyte characters and strings conversions .SH SYNOPSIS .C "#include " .PP .C "int mblen(const char *s, size_t n);" .PP .C "int mbtowc(wchar_t *pwc, const char *s, size_t n);" .PP .C "int wctomb(char *s, wchar_t wchar);" .PP .C "size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);" .PP .C "size_t wcstombs(char *s, const wchar_t *pwcs, size_t n);" .SH DESCRIPTION A multibyte character is composed of one or more bytes that represent a "whole" character in a character encoding. A wide character (type of .CR wchar_t ) is composed of a fixed number of bytes whose code value can represent any character in a character encoding. .TP 12 .C mblen() Determine the number of bytes in the multibyte character pointed to by .IR s . Equivalent to: .IP .C "mbtowc((wchar_t *)0, s, n);" .IP If .I s is a null pointer, .I mblen returns a nonzero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .I mblen returns the number of bytes in the multibyte character if the next .I n or fewer bytes form a valid multibyte character, or return \-1 if they do not form a valid multibyte character. If .I s points to the null character, .I mblen returns 0. .TP .C mbtowc() Determine the number of bytes in the multibyte character pointed to by .IR s , determine the code for the value of type .C wchar_t corresponding to that multibyte character, then store the code in the object pointed to by .IR pwc . The value of the code corresponding to the null character is zero. At most .I n characters are examined, starting at the character pointed to by .IR s . .IP If .I s is a null pointer, .C mbtowc() returns a non-zero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .C mbtowc() returns the number of bytes in the converted multibyte character if the next .I n or fewer bytes form a valid multibyte character, or \-1 if they do not form a valid multibyte character. If .I s points to the null character, .C mbtowc() returns 0. The value returned is never greater than .I n or the value of the .C MB_CUR_MAX macro. .TP .C wctomb() Determine the number of bytes needed to represent the multibyte character corresponding to the code whose value is .I wchar and store the multibyte character representation in the array object pointed to by .IR s . At most .C MB_CUR_MAX characters are stored. .IP If .I s is a null pointer, .C wctomb() returns a nonzero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .C wctomb() returns the number of bytes in the multibyte character corresponding to the value of .IR wchar , or \-1 if the value of .I wchar does not correspond to a valid multibyte character. The value returned is never greater than the value of the .C MB_CUR_MAX macro. .TP .C mbstowcs() Convert a sequence of multibyte characters from the array pointed to by .I s into a sequence of corresponding codes and store these codes into the array pointed to by .IR pwcs , stopping after either .I n codes or a code with value zero (a converted null character) is stored. Each multibyte character is converted as if by a call to .CR mbtowc() . No more than .I n elements are modified in the array pointed to by .IR pwcs . .IP If an invalid multibyte character is encountered, .C mbstowcs() returns (size_t)\|\(mi\|1. Otherwise, .C mbstowcs() returns the number of array elements modified, not including a terminating zero code, if any. The array is not null- or zero-terminated if the value returned is .IR n . If .I pwcs is a null pointer, .C mbstowcs() returns the number of elements required for the wide-character-code array. .TP .C wcstombs() Convert a sequence of codes corresponding to multibyte characters from the array pointed to by .I pwcs into a sequence of multibyte characters and store them into the array pointed to by .IR s , stopping if a multibyte character exceeds the limit of .I n total bytes or if a null character is stored. Each code is converted as if by a call to .CR wctomb() . No more than .I n bytes are modified in the array pointed to by .IR s . .IP If a code is encountered that does not correspond to a valid multibyte character, .C wcstombs() returns (size_t)\|\(mi\|1. Otherwise, .C wcstombs() returns the number of bytes modified, not including a terminating null character, if any. The array is not null- or zero-terminated if the value returned is .IR n . If .I s is a null pointer, .C wcstombs() returns the number of bytes required for the character array. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the behavior of the multibyte character and string functions. .SH ERRORS .CR mblen() , .CR mbstowcs() , .CR mbtowc() , .C wcstombs() and .C wctomb() may fail and .C errno is set if the following condition is encountered: .RS .TP 15 .SM [EILSEQ] An invalid multibyte sequence or wide character code was found. .RE .SH WARNINGS With the exception of .SM ASCII characters, the code values of wide characters (type of .CR wchar_t ) are specific to the effective locale specified by the .C LC_CTYPE environment variable. These values may not be compatible with values obtained by specifying other locales that are supported now, or which may be supported in the future. It is recommended that wide character constants and wide string literals (see the .IR "C Reference Manual" ) not be used, and that wide character code values not be stored in files or devices because future standards may dictate changes in the code value assignments of the wide characters. However, wide character constants and wide string literals corresponding to the characters of the .SM ASCII code set can be safely used since their values are guaranteed to be the same as their .SM ASCII code set values. .SH AUTHOR The multibyte functions in this entry were developed by OSF and HP. .SH SEE ALSO setlocale(3C), wctype(3X). .SH STANDARDS CONFORMANCE .CR mblen() ": AES, SVID3, XPG4, ANSI C" .PP .CR mbstowcs() ": AES, SVID3, XPG4, ANSI C" .PP .CR mbtowc() ": AES, SVID3, XPG4, ANSI C" .PP .CR wcstombs() ": AES, SVID3, XPG4, ANSI C" .PP .CR wctomb() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4multibyte()\f1 \- multibyte characters and strings conversions@@@\f3multibyte(3C)\f1 .\" .\" index@\f4mblen()\f1 \- number of bytes in the multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4mbtowc()\f1 \- number of bytes in the multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4wctomb()\f1 \- number of bytes needed to represent multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4mbstowcs()\f1 \- convert sequence of multibyte characters@@@\f3multibyte(3C)\f1 .\" index@\f4wcstombs()\f1 \- convert sequence of codes corresponding to multibyte characters@@@\f3multibyte(3C)\f1 .\" .\" .\" index@\f1multibyte characters and strings conversions@@@\f3multibyte(3C)\f1 .\" index@\f1characters and strings conversions, multibyte@@@\f3multibyte(3C)\f1 .\" index@\f1strings and characters conversions, multibyte@@@\f3multibyte(3C)\f1 .\" index@\f1conversions, multibyte characters and strings@@@\f3multibyte(3C)\f1 .\" .\" toc@\f3multibyte(3C)\f1:\0\0\f4mblen()\f1, \f4mbtowc()\f1, \f4mbstowcs()\f1, \f4wctomb()\f1,\n \f4wcstombs()\f1@@@multibyte characters and strings conversions .\" toc@\f4mblen()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4mbstowcs()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4mbtowc()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4wctomb()\f1: multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4wctombs()\f1: multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" .\" links@multibyte.3c mblen.3c .\" links@multibyte.3c mbtowc.3c .\" links@multibyte.3c mbstowcs.3c .\" links@multibyte.3c wctomb.3c .\" links@multibyte.3c wcstombs.3c .\" $Header: multibyte.3c,v 72.6 94/11/15 09:55:30 ssa Exp $ .TA m .TH multibyte 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mblen(\|), mbtowc(\|), mbstowcs(\|), wctomb(\|), wcstombs(\|) \- multibyte characters and strings conversions .SH SYNOPSIS .C "#include " .PP .C "int mblen(const char *s, size_t n);" .PP .C "int mbtowc(wchar_t *pwc, const char *s, size_t n);" .PP .C "int wctomb(char *s, wchar_t wchar);" .PP .C "size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);" .PP .C "size_t wcstombs(char *s, const wchar_t *pwcs, size_t n);" .SH DESCRIPTION A multibyte character is composed of one or more bytes that represent a "whole" character in a character encoding. A wide character (type of .CR wchar_t ) is composed of a fixed number of bytes whose code value can represent any character in a character encoding. .TP 12 .C mblen() Determine the number of bytes in the multibyte character pointed to by .IR s . Equivalent to: .IP .C "mbtowc((wchar_t *)0, s, n);" .IP If .I s is a null pointer, .I mblen returns a nonzero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .I mblen returns the number of bytes in the multibyte character if the next .I n or fewer bytes form a valid multibyte character, or return \-1 if they do not form a valid multibyte character. If .I s points to the null character, .I mblen returns 0. .TP .C mbtowc() Determine the number of bytes in the multibyte character pointed to by .IR s , determine the code for the value of type .C wchar_t corresponding to that multibyte character, then store the code in the object pointed to by .IR pwc . The value of the code corresponding to the null character is zero. At most .I n characters are examined, starting at the character pointed to by .IR s . .IP If .I s is a null pointer, .C mbtowc() returns a non-zero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .C mbtowc() returns the number of bytes in the converted multibyte character if the next .I n or fewer bytes form a valid multibyte character, or \-1 if they do not form a valid multibyte character. If .I s points to the null character, .C mbtowc() returns 0. The value returned is never greater than .I n or the value of the .C MB_CUR_MAX macro. .TP .C wctomb() Determine the number of bytes needed to represent the multibyte character corresponding to the code whose value is .I wchar and store the multibyte character representation in the array object pointed to by .IR s . At most .C MB_CUR_MAX characters are stored. .IP If .I s is a null pointer, .C wctomb() returns a nonzero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .C wctomb() returns the number of bytes in the multibyte character corresponding to the value of .IR wchar , or \-1 if the value of .I wchar does not correspond to a valid multibyte character. The value returned is never greater than the value of the .C MB_CUR_MAX macro. .TP .C mbstowcs() Convert a sequence of multibyte characters from the array pointed to by .I s into a sequence of corresponding codes and store these codes into the array pointed to by .IR pwcs , stopping after either .I n codes or a code with value zero (a converted null character) is stored. Each multibyte character is converted as if by a call to .CR mbtowc() . No more than .I n elements are modified in the array pointed to by .IR pwcs . .IP If an invalid multibyte character is encountered, .C mbstowcs() returns (size_t)\|\(mi\|1. Otherwise, .C mbstowcs() returns the number of array elements modified, not including a terminating zero code, if any. The array is not null- or zero-terminated if the value returned is .IR n . If .I pwcs is a null pointer, .C mbstowcs() returns the number of elements required for the wide-character-code array. .TP .C wcstombs() Convert a sequence of codes corresponding to multibyte characters from the array pointed to by .I pwcs into a sequence of multibyte characters and store them into the array pointed to by .IR s , stopping if a multibyte character exceeds the limit of .I n total bytes or if a null character is stored. Each code is converted as if by a call to .CR wctomb() . No more than .I n bytes are modified in the array pointed to by .IR s . .IP If a code is encountered that does not correspond to a valid multibyte character, .C wcstombs() returns (size_t)\|\(mi\|1. Otherwise, .C wcstombs() returns the number of bytes modified, not including a terminating null character, if any. The array is not null- or zero-terminated if the value returned is .IR n . If .I s is a null pointer, .C wcstombs() returns the number of bytes required for the character array. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the behavior of the multibyte character and string functions. .SH ERRORS .CR mblen() , .CR mbstowcs() , .CR mbtowc() , .C wcstombs() and .C wctomb() may fail and .C errno is set if the following condition is encountered: .RS .TP 15 .SM [EILSEQ] An invalid multibyte sequence or wide character code was found. .RE .SH WARNINGS With the exception of .SM ASCII characters, the code values of wide characters (type of .CR wchar_t ) are specific to the effective locale specified by the .C LC_CTYPE environment variable. These values may not be compatible with values obtained by specifying other locales that are supported now, or which may be supported in the future. It is recommended that wide character constants and wide string literals (see the .IR "C Reference Manual" ) not be used, and that wide character code values not be stored in files or devices because future standards may dictate changes in the code value assignments of the wide characters. However, wide character constants and wide string literals corresponding to the characters of the .SM ASCII code set can be safely used since their values are guaranteed to be the same as their .SM ASCII code set values. .SH AUTHOR The multibyte functions in this entry were developed by OSF and HP. .SH SEE ALSO setlocale(3C), wctype(3X). .SH STANDARDS CONFORMANCE .CR mblen() ": AES, SVID3, XPG4, ANSI C" .PP .CR mbstowcs() ": AES, SVID3, XPG4, ANSI C" .PP .CR mbtowc() ": AES, SVID3, XPG4, ANSI C" .PP .CR wcstombs() ": AES, SVID3, XPG4, ANSI C" .PP .CR wctomb() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4multibyte()\f1 \- multibyte characters and strings conversions@@@\f3multibyte(3C)\f1 .\" .\" index@\f4mblen()\f1 \- number of bytes in the multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4mbtowc()\f1 \- number of bytes in the multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4wctomb()\f1 \- number of bytes needed to represent multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4mbstowcs()\f1 \- convert sequence of multibyte characters@@@\f3multibyte(3C)\f1 .\" index@\f4wcstombs()\f1 \- convert sequence of codes corresponding to multibyte characters@@@\f3multibyte(3C)\f1 .\" .\" .\" index@\f1multibyte characters and strings conversions@@@\f3multibyte(3C)\f1 .\" index@\f1characters and strings conversions, multibyte@@@\f3multibyte(3C)\f1 .\" index@\f1strings and characters conversions, multibyte@@@\f3multibyte(3C)\f1 .\" index@\f1conversions, multibyte characters and strings@@@\f3multibyte(3C)\f1 .\" .\" toc@\f3multibyte(3C)\f1:\0\0\f4mblen()\f1, \f4mbtowc()\f1, \f4mbstowcs()\f1, \f4wctomb()\f1,\n \f4wcstombs()\f1@@@multibyte characters and strings conversions .\" toc@\f4mblen()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4mbstowcs()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4mbtowc()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4wctomb()\f1: multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4wctombs()\f1: multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" .\" links@multibyte.3c mblen.3c .\" links@multibyte.3c mbtowc.3c .\" links@multibyte.3c mbstowcs.3c .\" links@multibyte.3c wctomb.3c .\" links@multibyte.3c wcstombs.3c .\" $Header: crt0.3,v 72.4 94/09/02 14:40:25 ssa Exp $ .TA c .TH crt0 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crt0.o, gcrt0.o, mcrt0.o \- execution startup routines .SH DESCRIPTION .PP The C, Pascal, and FORTRAN compilers link in the object files .CR crt0.o , .CR gcrt0.o , or .C mcrt0.o to provide startup capabilities and environments for program execution. All are identical except that .C gcrt0.o and .C mcrt0.o provide additional functionality for .IR gprof (1) and .IR prof (1) profiling support respectively. .PP The following symbols are defined in these object files: .RS .TP 20 .C _\|_argc_value A variable of type .I int containing the number of arguments. .TP .C _\|_argv_value An array of character pointers to the arguments themselves. .TP .C _environ An array of character pointers to the environment in which the program will run. This array is terminated by a null pointer. .TP .SM .C _FPU_MODEL A variable of type .I short containing the FPU model number returned by the FP status instruction. This variable is initialized with data from the kernel. .TP .SM .C _FPU_REVISION A variable of type .I short containing the FPU revision number returned by the FP status instruction. This variable is initialized with data from the kernel. .TP .SM .C _CPU_REVISION A variable of type .I int containing the CPU revision of the machine. This variable is initialized with data from the kernel. .TP .SM .C _SYSTEM_ID A variable of type .I int containing the system id value for an executable program. .TP .SM .C $START$ Execution start address. .TP .C _start A secondary startup routine for C programs, called from .CR $START$ , which in turn calls .CR main . This routine is contained in the C library rather than the .C crt0.o file. For Pascal and F\s-2ORTRAN\s0 programs, this symbol labels the beginning of the outer block (main program) and is generated by the compilers. .TP .C $global$ The initial address of the program's data pointer. The startup code loads this address into general register 27. .TP .C $UNWIND_START The beginning of the stack unwind table. .TP .C $UNWIND_END The end of the stack unwind table. .TP .C $RECOVER_START The beginning of the try/recover table. .TP .C $RECOVER_END The end of the try/recover table. .RE .PP The .C crt0.o file defines a null procedure for .CR _mcount , so programs compiled with profiling can be linked without profiling. .PP The linker defines the following two symbols: .RS .TP 20 .C _\|_text_start The beginning address of the program's text area. .PD 0 .TP .C _\|_data_start The beginning address of the program's data area. .PD .RE .SH AUTHOR The features described in this entry originated from .SM AT&T UNIX System III. .SH SEE ALSO .PD .SS Profiling and Debugging Tools: .TP 18 .IR gprof(1) display call graph profile data .PD 0 .TP .IR monitor(3C) prepare execution profile .TP .IR prof(1) display profile data .TP .IR profil(2) execution time profile .PD .SS System Tools: .TP 18 .IR cc(1) invoke the HP-UX C compiler .PD 0 .TP .IR exec(2) execute a file .TP f77(1) invoke the HP-UX FORTRAN compiler .TP .IR ld(1) invoke the link editor .TP .IR pc(1) invoke the HP-UX Pascal compiler .PD .SS Miscellaneous: .TP 18 .IR end(3C) symbol of the last locations in program .PD .\" .\" index@\f4crt0.o\f1, \f4gcrt0.o\f1, \f4mcrt0.o\f1, \f4frt0.o\f1, \f4mfrt0.o\f1 \- execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4crt0.o\f1, \f4mcrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4gcrt0.o\f1, \f4gfrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4gfrt0.o\f1, \f4gcrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4mcrt0.o\f1, \f4crt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4frt0.o\f1, \f4mfrt0.o\f1 \- F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4mfrt0.o\f1, \f4frt0.o\f1 \- F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@Pascal and C execution startup routines@@@\f3crt0(3)\f1 .\" index@F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@execution startup routines, C, Pascal, and F\s-2ORTRAN\s+2@@@\f3crt0(3)\f1 .\" .\" toc@\f3crt0(3)\f1:\0\0\f4crt0.o\f1, \f4mcrt0.o\f1, \f4frt0.o\f1, \f4mfrt0.o\f1@@@execution startup routines .\" toc@\f4crt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4gcrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4mcrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4frt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4mfrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" .\" links@crt0.3 crt0.o.3 .\" links@crt0.3 gcrt0.o.3 .\" links@crt0.3 mcrt0.o.3 .\" links@crt0.3 frt0.o.3 .\" links@crt0.3 gfrt0.o.3 .\" links@crt0.3 mfrt0.o.3 .\" .\" fileset_database@crt0.3 PROGRAMING-MAN .\" $Header: memory.3c,v 74.1 95/03/23 17:24:13 ssa Exp $ .TA m .TH memory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME memccpy(\|), memchr(\|), memcmp(\|), memcpy(\|), memmove(\|), memset(\|), bcopy(\|), bcmp(\|), bzero(\|), ffs(\|) \- memory operations .SH SYNOPSIS .C "#include " .PP .C "void *memccpy(void *s1, const void *s2, int c, size_t n);" .PP .C "void *memchr(const void *s, int c, size_t n);" .PP .C "int memcmp(const void *s1, const void *s2, size_t n);" .PP .C "void *memcpy(void *s1, const void *s2, size_t n);" .PP .C "void *memmove(void *s1, const void *s2, size_t n);" .PP .C "void *memset(void *s, int c, size_t n);" .PP .C "#include " .PP .C "int bcmp(const void *s1, const void *s2, size_t n);" .PP .C "void bcopy(const void *s1, void *s2, size_t n);" .PP .C "void bzero(char *s, int n);" .PP .C "int ffs(int i);" .SS Remarks: .CR bcmp() , .CR bcopy() , .CR bzero() , .CR ffs() , and .RC < strings.h > are provided solely for portability of .SM BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .CR memcmp() , .CR memmove() , and .CR memset() , respectively. .C ffs() has no portable equivalent. .SH DESCRIPTION These functions operate as efficiently as possible on memory areas (arrays of bytes bounded by a count, not terminated by a null byte). They do not check for the overflow of any receiving memory area. .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RC < string.h > header file. .TP 15 .C memccpy() Copy bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 , stopping after the first occurrence of byte .I c has been copied, or after .I n bytes have been copied, whichever comes first. If copying takes place between objects that overlap, the behavior is undefined. .C memccpy() returns a pointer to the bvyte after the copy of .I c in .IR s1 , or a .SM NULL pointer if .I c was not found in the first .I n bytes of .IR s2 . .TP .C memchr() Locate the first occurrence of .I c (converted to an .CR "unsigned char" ) in the initial .I n bytes (each interpreted as .CR "unsigned char" ) of the object pointed to by .IR s . .C memchr() returns a pointer to the located byte, or a .SM NULL pointer if the byte does not occur in the object. .TP .C memcmp() Compare the first .I n bytes of the object pointed to by .I s1 to the first .I n bytes of the object pointed to by .IR s2 . .C memcmp() returns an integer greater than, equal to, or less than zero, according to whether the object pointed to by .I s1 is greater than, equal to, or less than the object pointed to by .IR s2 . The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes (both interpreted as .CR "unsigned char" ) that differ in the objects being compared. .TP .C memcpy() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . If copying takes place between objects that overlap, the behavior is undefined. .C memcpy() returns the value of .IR s1 . .TP .C memmove() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . Copying takes place as if the .I n bytes from the object pointed to by .I s2 are first copied into a temporary array of .I n bytes that does not overlap the objects pointed to by .I s1 and .IR s2 , and then the .I n bytes from the temporary array are copied into the object pointed to by .IR s1 . .C memmove() returns the value of .IR s1 . .TP .C memset() Copy the value of .I c (converted to an .CR "unsigned char" ) into each of the first .I n bytes of the object pointed to by .IR s . .C memset() returns the value of .IR s . .TP .C bcopy() copies .I n bytes from the area pointed to by .I s1 to the area pointed to by .IR s2 . .TP .C bcmp() Compare the first .I n bytes of the area pointed to by .I s1 with the area pointed to by .IR s2 . .C bcmp() returns zero if they are identical; non-zero otherwise. Both areas are assumed to be .I n bytes in length. .TP .C bzero() Clear .I n bytes in the area pointed to by .I s by setting them to zero. .TP .C ffs() Find the first bit set (beginning with the least significant bit) and return the index of that bit. Bits are numbered starting at one. A return value of 0 indicates that .I i is zero. .SS International Code Set Support These functions support only single-byte byte code sets. .SH WARNINGS The functions defined in .RC < string.h > were previously defined in .RC < memory.h >. .SH FILES .C /usr/include/string.h .SH SEE ALSO string(3C) .SH STANDARDS CONFORMANCE .CR memccpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR memchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memmove() ": AES, SVID3, XPG4, ANSI C" .PP .CR memset() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4memcpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memccpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memchr()\f1 \- find first occurrence of byte in memory area@@@\f3memory(3C)\f1 .\" index@\f4memcmp()\f1 \- compare byte with memory contents@@@\f3memory(3C)\f1 .\" index@\f4memmove()\f1 \- move memory contents@@@\f3memory(3C)\f1 .\" index@\f4memset()\f1 \- set area in memory to contain a specified byte@@@\f3memory(3C)\f1 .\" index@\f4bcopy()\f1 \- \s-1BSD\s+1 memory copy@@@\f3memory(3C)\f1 .\" index@\f4bcmp()\f1 \- \s-1BSD\s+1 memory compare@@@\f3memory(3C)\f1 .\" index@\f4bzero()\f1 \- \s-1BSD\s+1 memory clear@@@\f3memory(3C)\f1 .\" index@\f4ffs()\f1 \- \s-1BSD\s+1 find first set bit@@@\f3memory(3C)\f1 .\" index@\f1memory operations \- copy, compare, test for contents, or set contents to value@@@\f3memory(3C)\f1 .\" index@\f1copy memory to another area@@@\f3memory(3C)\f1 .\" index@\f1test contents of memory area@@@\f3memory(3C)\f1 .\" index@\f1compare contents of memory with byte@@@\f3memory(3C)\f1 .\" index@\f1preset contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1set contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1byte, set contents of memory area to specified@@@\f3memory(3C)\f1 .\" index@\f1byte, compare memory contents with specified@@@\f3memory(3C)\f1 .\" index@\f1byte, find location of in memory@@@\f3memory(3C)\f1 .\" index@\f1location of byte in memory, find@@@\f3memory(3C)\f1 .\" .\" toc@\f3memory(3C)\f1:\0\0\f4memccpy()\f1, \f4memchr()\f1, \f4memcmp()\f1, \f4memcpy()\f1, \f4memset()\f1, \n\f4bcopy()\f1, \f4bcmp()\f1, \f4bzero()\f1, \f4ffs()\f1@@@memory operations .\" toc@\f4memccpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memchr()\f1:\0\0memory operations, locate first character@@@see \f3memory(3C)\f1 .\" toc@\f4memcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memcpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memmove()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memset()\f1:\0\0memory operations, set memory@@@see \f3memory(3C)\f1 .\" toc@\f4bcopy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bzero()\f1:\0\0memory operations, clear bytes@@@see \f3memory(3C)\f1 .\" toc@\f4ffs()\f1:\0\0memory operations, find first bit set@@@see \f3memory(3C)\f1 .\" .\" links@memory.3c memccpy.3c .\" links@memory.3c memchr.3c .\" links@memory.3c memcmp.3c .\" links@memory.3c memcpy.3c .\" links@memory.3c memmove.3c .\" links@memory.3c memset.3c .\" links@memory.3c bcopy.3c .\" links@memory.3c bcmp.3c .\" links@memory.3c bzero.3c .\" links@memory.3c ffs.3c .\" .\" $Header: memory.3c,v 74.1 95/03/23 17:24:13 ssa Exp $ .TA m .TH memory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME memccpy(\|), memchr(\|), memcmp(\|), memcpy(\|), memmove(\|), memset(\|), bcopy(\|), bcmp(\|), bzero(\|), ffs(\|) \- memory operations .SH SYNOPSIS .C "#include " .PP .C "void *memccpy(void *s1, const void *s2, int c, size_t n);" .PP .C "void *memchr(const void *s, int c, size_t n);" .PP .C "int memcmp(const void *s1, const void *s2, size_t n);" .PP .C "void *memcpy(void *s1, const void *s2, size_t n);" .PP .C "void *memmove(void *s1, const void *s2, size_t n);" .PP .C "void *memset(void *s, int c, size_t n);" .PP .C "#include " .PP .C "int bcmp(const void *s1, const void *s2, size_t n);" .PP .C "void bcopy(const void *s1, void *s2, size_t n);" .PP .C "void bzero(char *s, int n);" .PP .C "int ffs(int i);" .SS Remarks: .CR bcmp() , .CR bcopy() , .CR bzero() , .CR ffs() , and .RC < strings.h > are provided solely for portability of .SM BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .CR memcmp() , .CR memmove() , and .CR memset() , respectively. .C ffs() has no portable equivalent. .SH DESCRIPTION These functions operate as efficiently as possible on memory areas (arrays of bytes bounded by a count, not terminated by a null byte). They do not check for the overflow of any receiving memory area. .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RC < string.h > header file. .TP 15 .C memccpy() Copy bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 , stopping after the first occurrence of byte .I c has been copied, or after .I n bytes have been copied, whichever comes first. If copying takes place between objects that overlap, the behavior is undefined. .C memccpy() returns a pointer to the bvyte after the copy of .I c in .IR s1 , or a .SM NULL pointer if .I c was not found in the first .I n bytes of .IR s2 . .TP .C memchr() Locate the first occurrence of .I c (converted to an .CR "unsigned char" ) in the initial .I n bytes (each interpreted as .CR "unsigned char" ) of the object pointed to by .IR s . .C memchr() returns a pointer to the located byte, or a .SM NULL pointer if the byte does not occur in the object. .TP .C memcmp() Compare the first .I n bytes of the object pointed to by .I s1 to the first .I n bytes of the object pointed to by .IR s2 . .C memcmp() returns an integer greater than, equal to, or less than zero, according to whether the object pointed to by .I s1 is greater than, equal to, or less than the object pointed to by .IR s2 . The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes (both interpreted as .CR "unsigned char" ) that differ in the objects being compared. .TP .C memcpy() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . If copying takes place between objects that overlap, the behavior is undefined. .C memcpy() returns the value of .IR s1 . .TP .C memmove() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . Copying takes place as if the .I n bytes from the object pointed to by .I s2 are first copied into a temporary array of .I n bytes that does not overlap the objects pointed to by .I s1 and .IR s2 , and then the .I n bytes from the temporary array are copied into the object pointed to by .IR s1 . .C memmove() returns the value of .IR s1 . .TP .C memset() Copy the value of .I c (converted to an .CR "unsigned char" ) into each of the first .I n bytes of the object pointed to by .IR s . .C memset() returns the value of .IR s . .TP .C bcopy() copies .I n bytes from the area pointed to by .I s1 to the area pointed to by .IR s2 . .TP .C bcmp() Compare the first .I n bytes of the area pointed to by .I s1 with the area pointed to by .IR s2 . .C bcmp() returns zero if they are identical; non-zero otherwise. Both areas are assumed to be .I n bytes in length. .TP .C bzero() Clear .I n bytes in the area pointed to by .I s by setting them to zero. .TP .C ffs() Find the first bit set (beginning with the least significant bit) and return the index of that bit. Bits are numbered starting at one. A return value of 0 indicates that .I i is zero. .SS International Code Set Support These functions support only single-byte byte code sets. .SH WARNINGS The functions defined in .RC < string.h > were previously defined in .RC < memory.h >. .SH FILES .C /usr/include/string.h .SH SEE ALSO string(3C) .SH STANDARDS CONFORMANCE .CR memccpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR memchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memmove() ": AES, SVID3, XPG4, ANSI C" .PP .CR memset() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4memcpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memccpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memchr()\f1 \- find first occurrence of byte in memory area@@@\f3memory(3C)\f1 .\" index@\f4memcmp()\f1 \- compare byte with memory contents@@@\f3memory(3C)\f1 .\" index@\f4memmove()\f1 \- move memory contents@@@\f3memory(3C)\f1 .\" index@\f4memset()\f1 \- set area in memory to contain a specified byte@@@\f3memory(3C)\f1 .\" index@\f4bcopy()\f1 \- \s-1BSD\s+1 memory copy@@@\f3memory(3C)\f1 .\" index@\f4bcmp()\f1 \- \s-1BSD\s+1 memory compare@@@\f3memory(3C)\f1 .\" index@\f4bzero()\f1 \- \s-1BSD\s+1 memory clear@@@\f3memory(3C)\f1 .\" index@\f4ffs()\f1 \- \s-1BSD\s+1 find first set bit@@@\f3memory(3C)\f1 .\" index@\f1memory operations \- copy, compare, test for contents, or set contents to value@@@\f3memory(3C)\f1 .\" index@\f1copy memory to another area@@@\f3memory(3C)\f1 .\" index@\f1test contents of memory area@@@\f3memory(3C)\f1 .\" index@\f1compare contents of memory with byte@@@\f3memory(3C)\f1 .\" index@\f1preset contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1set contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1byte, set contents of memory area to specified@@@\f3memory(3C)\f1 .\" index@\f1byte, compare memory contents with specified@@@\f3memory(3C)\f1 .\" index@\f1byte, find location of in memory@@@\f3memory(3C)\f1 .\" index@\f1location of byte in memory, find@@@\f3memory(3C)\f1 .\" .\" toc@\f3memory(3C)\f1:\0\0\f4memccpy()\f1, \f4memchr()\f1, \f4memcmp()\f1, \f4memcpy()\f1, \f4memset()\f1, \n\f4bcopy()\f1, \f4bcmp()\f1, \f4bzero()\f1, \f4ffs()\f1@@@memory operations .\" toc@\f4memccpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memchr()\f1:\0\0memory operations, locate first character@@@see \f3memory(3C)\f1 .\" toc@\f4memcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memcpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memmove()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memset()\f1:\0\0memory operations, set memory@@@see \f3memory(3C)\f1 .\" toc@\f4bcopy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bzero()\f1:\0\0memory operations, clear bytes@@@see \f3memory(3C)\f1 .\" toc@\f4ffs()\f1:\0\0memory operations, find first bit set@@@see \f3memory(3C)\f1 .\" .\" links@memory.3c memccpy.3c .\" links@memory.3c memchr.3c .\" links@memory.3c memcmp.3c .\" links@memory.3c memcpy.3c .\" links@memory.3c memmove.3c .\" links@memory.3c memset.3c .\" links@memory.3c bcopy.3c .\" links@memory.3c bcmp.3c .\" links@memory.3c bzero.3c .\" links@memory.3c ffs.3c .\" .\" $Header: memory.3c,v 74.1 95/03/23 17:24:13 ssa Exp $ .TA m .TH memory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME memccpy(\|), memchr(\|), memcmp(\|), memcpy(\|), memmove(\|), memset(\|), bcopy(\|), bcmp(\|), bzero(\|), ffs(\|) \- memory operations .SH SYNOPSIS .C "#include " .PP .C "void *memccpy(void *s1, const void *s2, int c, size_t n);" .PP .C "void *memchr(const void *s, int c, size_t n);" .PP .C "int memcmp(const void *s1, const void *s2, size_t n);" .PP .C "void *memcpy(void *s1, const void *s2, size_t n);" .PP .C "void *memmove(void *s1, const void *s2, size_t n);" .PP .C "void *memset(void *s, int c, size_t n);" .PP .C "#include " .PP .C "int bcmp(const void *s1, const void *s2, size_t n);" .PP .C "void bcopy(const void *s1, void *s2, size_t n);" .PP .C "void bzero(char *s, int n);" .PP .C "int ffs(int i);" .SS Remarks: .CR bcmp() , .CR bcopy() , .CR bzero() , .CR ffs() , and .RC < strings.h > are provided solely for portability of .SM BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .CR memcmp() , .CR memmove() , and .CR memset() , respectively. .C ffs() has no portable equivalent. .SH DESCRIPTION These functions operate as efficiently as possible on memory areas (arrays of bytes bounded by a count, not terminated by a null byte). They do not check for the overflow of any receiving memory area. .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RC < string.h > header file. .TP 15 .C memccpy() Copy bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 , stopping after the first occurrence of byte .I c has been copied, or after .I n bytes have been copied, whichever comes first. If copying takes place between objects that overlap, the behavior is undefined. .C memccpy() returns a pointer to the bvyte after the copy of .I c in .IR s1 , or a .SM NULL pointer if .I c was not found in the first .I n bytes of .IR s2 . .TP .C memchr() Locate the first occurrence of .I c (converted to an .CR "unsigned char" ) in the initial .I n bytes (each interpreted as .CR "unsigned char" ) of the object pointed to by .IR s . .C memchr() returns a pointer to the located byte, or a .SM NULL pointer if the byte does not occur in the object. .TP .C memcmp() Compare the first .I n bytes of the object pointed to by .I s1 to the first .I n bytes of the object pointed to by .IR s2 . .C memcmp() returns an integer greater than, equal to, or less than zero, according to whether the object pointed to by .I s1 is greater than, equal to, or less than the object pointed to by .IR s2 . The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes (both interpreted as .CR "unsigned char" ) that differ in the objects being compared. .TP .C memcpy() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . If copying takes place between objects that overlap, the behavior is undefined. .C memcpy() returns the value of .IR s1 . .TP .C memmove() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . Copying takes place as if the .I n bytes from the object pointed to by .I s2 are first copied into a temporary array of .I n bytes that does not overlap the objects pointed to by .I s1 and .IR s2 , and then the .I n bytes from the temporary array are copied into the object pointed to by .IR s1 . .C memmove() returns the value of .IR s1 . .TP .C memset() Copy the value of .I c (converted to an .CR "unsigned char" ) into each of the first .I n bytes of the object pointed to by .IR s . .C memset() returns the value of .IR s . .TP .C bcopy() copies .I n bytes from the area pointed to by .I s1 to the area pointed to by .IR s2 . .TP .C bcmp() Compare the first .I n bytes of the area pointed to by .I s1 with the area pointed to by .IR s2 . .C bcmp() returns zero if they are identical; non-zero otherwise. Both areas are assumed to be .I n bytes in length. .TP .C bzero() Clear .I n bytes in the area pointed to by .I s by setting them to zero. .TP .C ffs() Find the first bit set (beginning with the least significant bit) and return the index of that bit. Bits are numbered starting at one. A return value of 0 indicates that .I i is zero. .SS International Code Set Support These functions support only single-byte byte code sets. .SH WARNINGS The functions defined in .RC < string.h > were previously defined in .RC < memory.h >. .SH FILES .C /usr/include/string.h .SH SEE ALSO string(3C) .SH STANDARDS CONFORMANCE .CR memccpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR memchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memmove() ": AES, SVID3, XPG4, ANSI C" .PP .CR memset() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4memcpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memccpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memchr()\f1 \- find first occurrence of byte in memory area@@@\f3memory(3C)\f1 .\" index@\f4memcmp()\f1 \- compare byte with memory contents@@@\f3memory(3C)\f1 .\" index@\f4memmove()\f1 \- move memory contents@@@\f3memory(3C)\f1 .\" index@\f4memset()\f1 \- set area in memory to contain a specified byte@@@\f3memory(3C)\f1 .\" index@\f4bcopy()\f1 \- \s-1BSD\s+1 memory copy@@@\f3memory(3C)\f1 .\" index@\f4bcmp()\f1 \- \s-1BSD\s+1 memory compare@@@\f3memory(3C)\f1 .\" index@\f4bzero()\f1 \- \s-1BSD\s+1 memory clear@@@\f3memory(3C)\f1 .\" index@\f4ffs()\f1 \- \s-1BSD\s+1 find first set bit@@@\f3memory(3C)\f1 .\" index@\f1memory operations \- copy, compare, test for contents, or set contents to value@@@\f3memory(3C)\f1 .\" index@\f1copy memory to another area@@@\f3memory(3C)\f1 .\" index@\f1test contents of memory area@@@\f3memory(3C)\f1 .\" index@\f1compare contents of memory with byte@@@\f3memory(3C)\f1 .\" index@\f1preset contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1set contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1byte, set contents of memory area to specified@@@\f3memory(3C)\f1 .\" index@\f1byte, compare memory contents with specified@@@\f3memory(3C)\f1 .\" index@\f1byte, find location of in memory@@@\f3memory(3C)\f1 .\" index@\f1location of byte in memory, find@@@\f3memory(3C)\f1 .\" .\" toc@\f3memory(3C)\f1:\0\0\f4memccpy()\f1, \f4memchr()\f1, \f4memcmp()\f1, \f4memcpy()\f1, \f4memset()\f1, \n\f4bcopy()\f1, \f4bcmp()\f1, \f4bzero()\f1, \f4ffs()\f1@@@memory operations .\" toc@\f4memccpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memchr()\f1:\0\0memory operations, locate first character@@@see \f3memory(3C)\f1 .\" toc@\f4memcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memcpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memmove()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memset()\f1:\0\0memory operations, set memory@@@see \f3memory(3C)\f1 .\" toc@\f4bcopy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bzero()\f1:\0\0memory operations, clear bytes@@@see \f3memory(3C)\f1 .\" toc@\f4ffs()\f1:\0\0memory operations, find first bit set@@@see \f3memory(3C)\f1 .\" .\" links@memory.3c memccpy.3c .\" links@memory.3c memchr.3c .\" links@memory.3c memcmp.3c .\" links@memory.3c memcpy.3c .\" links@memory.3c memmove.3c .\" links@memory.3c memset.3c .\" links@memory.3c bcopy.3c .\" links@memory.3c bcmp.3c .\" links@memory.3c bzero.3c .\" links@memory.3c ffs.3c .\" .\" $Header: memory.3c,v 74.1 95/03/23 17:24:13 ssa Exp $ .TA m .TH memory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME memccpy(\|), memchr(\|), memcmp(\|), memcpy(\|), memmove(\|), memset(\|), bcopy(\|), bcmp(\|), bzero(\|), ffs(\|) \- memory operations .SH SYNOPSIS .C "#include " .PP .C "void *memccpy(void *s1, const void *s2, int c, size_t n);" .PP .C "void *memchr(const void *s, int c, size_t n);" .PP .C "int memcmp(const void *s1, const void *s2, size_t n);" .PP .C "void *memcpy(void *s1, const void *s2, size_t n);" .PP .C "void *memmove(void *s1, const void *s2, size_t n);" .PP .C "void *memset(void *s, int c, size_t n);" .PP .C "#include " .PP .C "int bcmp(const void *s1, const void *s2, size_t n);" .PP .C "void bcopy(const void *s1, void *s2, size_t n);" .PP .C "void bzero(char *s, int n);" .PP .C "int ffs(int i);" .SS Remarks: .CR bcmp() , .CR bcopy() , .CR bzero() , .CR ffs() , and .RC < strings.h > are provided solely for portability of .SM BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .CR memcmp() , .CR memmove() , and .CR memset() , respectively. .C ffs() has no portable equivalent. .SH DESCRIPTION These functions operate as efficiently as possible on memory areas (arrays of bytes bounded by a count, not terminated by a null byte). They do not check for the overflow of any receiving memory area. .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RC < string.h > header file. .TP 15 .C memccpy() Copy bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 , stopping after the first occurrence of byte .I c has been copied, or after .I n bytes have been copied, whichever comes first. If copying takes place between objects that overlap, the behavior is undefined. .C memccpy() returns a pointer to the bvyte after the copy of .I c in .IR s1 , or a .SM NULL pointer if .I c was not found in the first .I n bytes of .IR s2 . .TP .C memchr() Locate the first occurrence of .I c (converted to an .CR "unsigned char" ) in the initial .I n bytes (each interpreted as .CR "unsigned char" ) of the object pointed to by .IR s . .C memchr() returns a pointer to the located byte, or a .SM NULL pointer if the byte does not occur in the object. .TP .C memcmp() Compare the first .I n bytes of the object pointed to by .I s1 to the first .I n bytes of the object pointed to by .IR s2 . .C memcmp() returns an integer greater than, equal to, or less than zero, according to whether the object pointed to by .I s1 is greater than, equal to, or less than the object pointed to by .IR s2 . The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes (both interpreted as .CR "unsigned char" ) that differ in the objects being compared. .TP .C memcpy() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . If copying takes place between objects that overlap, the behavior is undefined. .C memcpy() returns the value of .IR s1 . .TP .C memmove() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . Copying takes place as if the .I n bytes from the object pointed to by .I s2 are first copied into a temporary array of .I n bytes that does not overlap the objects pointed to by .I s1 and .IR s2 , and then the .I n bytes from the temporary array are copied into the object pointed to by .IR s1 . .C memmove() returns the value of .IR s1 . .TP .C memset() Copy the value of .I c (converted to an .CR "unsigned char" ) into each of the first .I n bytes of the object pointed to by .IR s . .C memset() returns the value of .IR s . .TP .C bcopy() copies .I n bytes from the area pointed to by .I s1 to the area pointed to by .IR s2 . .TP .C bcmp() Compare the first .I n bytes of the area pointed to by .I s1 with the area pointed to by .IR s2 . .C bcmp() returns zero if they are identical; non-zero otherwise. Both areas are assumed to be .I n bytes in length. .TP .C bzero() Clear .I n bytes in the area pointed to by .I s by setting them to zero. .TP .C ffs() Find the first bit set (beginning with the least significant bit) and return the index of that bit. Bits are numbered starting at one. A return value of 0 indicates that .I i is zero. .SS International Code Set Support These functions support only single-byte byte code sets. .SH WARNINGS The functions defined in .RC < string.h > were previously defined in .RC < memory.h >. .SH FILES .C /usr/include/string.h .SH SEE ALSO string(3C) .SH STANDARDS CONFORMANCE .CR memccpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR memchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memmove() ": AES, SVID3, XPG4, ANSI C" .PP .CR memset() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4memcpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memccpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memchr()\f1 \- find first occurrence of byte in memory area@@@\f3memory(3C)\f1 .\" index@\f4memcmp()\f1 \- compare byte with memory contents@@@\f3memory(3C)\f1 .\" index@\f4memmove()\f1 \- move memory contents@@@\f3memory(3C)\f1 .\" index@\f4memset()\f1 \- set area in memory to contain a specified byte@@@\f3memory(3C)\f1 .\" index@\f4bcopy()\f1 \- \s-1BSD\s+1 memory copy@@@\f3memory(3C)\f1 .\" index@\f4bcmp()\f1 \- \s-1BSD\s+1 memory compare@@@\f3memory(3C)\f1 .\" index@\f4bzero()\f1 \- \s-1BSD\s+1 memory clear@@@\f3memory(3C)\f1 .\" index@\f4ffs()\f1 \- \s-1BSD\s+1 find first set bit@@@\f3memory(3C)\f1 .\" index@\f1memory operations \- copy, compare, test for contents, or set contents to value@@@\f3memory(3C)\f1 .\" index@\f1copy memory to another area@@@\f3memory(3C)\f1 .\" index@\f1test contents of memory area@@@\f3memory(3C)\f1 .\" index@\f1compare contents of memory with byte@@@\f3memory(3C)\f1 .\" index@\f1preset contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1set contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1byte, set contents of memory area to specified@@@\f3memory(3C)\f1 .\" index@\f1byte, compare memory contents with specified@@@\f3memory(3C)\f1 .\" index@\f1byte, find location of in memory@@@\f3memory(3C)\f1 .\" index@\f1location of byte in memory, find@@@\f3memory(3C)\f1 .\" .\" toc@\f3memory(3C)\f1:\0\0\f4memccpy()\f1, \f4memchr()\f1, \f4memcmp()\f1, \f4memcpy()\f1, \f4memset()\f1, \n\f4bcopy()\f1, \f4bcmp()\f1, \f4bzero()\f1, \f4ffs()\f1@@@memory operations .\" toc@\f4memccpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memchr()\f1:\0\0memory operations, locate first character@@@see \f3memory(3C)\f1 .\" toc@\f4memcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memcpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memmove()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memset()\f1:\0\0memory operations, set memory@@@see \f3memory(3C)\f1 .\" toc@\f4bcopy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bzero()\f1:\0\0memory operations, clear bytes@@@see \f3memory(3C)\f1 .\" toc@\f4ffs()\f1:\0\0memory operations, find first bit set@@@see \f3memory(3C)\f1 .\" .\" links@memory.3c memccpy.3c .\" links@memory.3c memchr.3c .\" links@memory.3c memcmp.3c .\" links@memory.3c memcpy.3c .\" links@memory.3c memmove.3c .\" links@memory.3c memset.3c .\" links@memory.3c bcopy.3c .\" links@memory.3c bcmp.3c .\" links@memory.3c bzero.3c .\" links@memory.3c ffs.3c .\" .\" $Header: memory.3c,v 74.1 95/03/23 17:24:13 ssa Exp $ .TA m .TH memory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME memccpy(\|), memchr(\|), memcmp(\|), memcpy(\|), memmove(\|), memset(\|), bcopy(\|), bcmp(\|), bzero(\|), ffs(\|) \- memory operations .SH SYNOPSIS .C "#include " .PP .C "void *memccpy(void *s1, const void *s2, int c, size_t n);" .PP .C "void *memchr(const void *s, int c, size_t n);" .PP .C "int memcmp(const void *s1, const void *s2, size_t n);" .PP .C "void *memcpy(void *s1, const void *s2, size_t n);" .PP .C "void *memmove(void *s1, const void *s2, size_t n);" .PP .C "void *memset(void *s, int c, size_t n);" .PP .C "#include " .PP .C "int bcmp(const void *s1, const void *s2, size_t n);" .PP .C "void bcopy(const void *s1, void *s2, size_t n);" .PP .C "void bzero(char *s, int n);" .PP .C "int ffs(int i);" .SS Remarks: .CR bcmp() , .CR bcopy() , .CR bzero() , .CR ffs() , and .RC < strings.h > are provided solely for portability of .SM BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .CR memcmp() , .CR memmove() , and .CR memset() , respectively. .C ffs() has no portable equivalent. .SH DESCRIPTION These functions operate as efficiently as possible on memory areas (arrays of bytes bounded by a count, not terminated by a null byte). They do not check for the overflow of any receiving memory area. .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RC < string.h > header file. .TP 15 .C memccpy() Copy bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 , stopping after the first occurrence of byte .I c has been copied, or after .I n bytes have been copied, whichever comes first. If copying takes place between objects that overlap, the behavior is undefined. .C memccpy() returns a pointer to the bvyte after the copy of .I c in .IR s1 , or a .SM NULL pointer if .I c was not found in the first .I n bytes of .IR s2 . .TP .C memchr() Locate the first occurrence of .I c (converted to an .CR "unsigned char" ) in the initial .I n bytes (each interpreted as .CR "unsigned char" ) of the object pointed to by .IR s . .C memchr() returns a pointer to the located byte, or a .SM NULL pointer if the byte does not occur in the object. .TP .C memcmp() Compare the first .I n bytes of the object pointed to by .I s1 to the first .I n bytes of the object pointed to by .IR s2 . .C memcmp() returns an integer greater than, equal to, or less than zero, according to whether the object pointed to by .I s1 is greater than, equal to, or less than the object pointed to by .IR s2 . The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes (both interpreted as .CR "unsigned char" ) that differ in the objects being compared. .TP .C memcpy() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . If copying takes place between objects that overlap, the behavior is undefined. .C memcpy() returns the value of .IR s1 . .TP .C memmove() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . Copying takes place as if the .I n bytes from the object pointed to by .I s2 are first copied into a temporary array of .I n bytes that does not overlap the objects pointed to by .I s1 and .IR s2 , and then the .I n bytes from the temporary array are copied into the object pointed to by .IR s1 . .C memmove() returns the value of .IR s1 . .TP .C memset() Copy the value of .I c (converted to an .CR "unsigned char" ) into each of the first .I n bytes of the object pointed to by .IR s . .C memset() returns the value of .IR s . .TP .C bcopy() copies .I n bytes from the area pointed to by .I s1 to the area pointed to by .IR s2 . .TP .C bcmp() Compare the first .I n bytes of the area pointed to by .I s1 with the area pointed to by .IR s2 . .C bcmp() returns zero if they are identical; non-zero otherwise. Both areas are assumed to be .I n bytes in length. .TP .C bzero() Clear .I n bytes in the area pointed to by .I s by setting them to zero. .TP .C ffs() Find the first bit set (beginning with the least significant bit) and return the index of that bit. Bits are numbered starting at one. A return value of 0 indicates that .I i is zero. .SS International Code Set Support These functions support only single-byte byte code sets. .SH WARNINGS The functions defined in .RC < string.h > were previously defined in .RC < memory.h >. .SH FILES .C /usr/include/string.h .SH SEE ALSO string(3C) .SH STANDARDS CONFORMANCE .CR memccpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR memchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memmove() ": AES, SVID3, XPG4, ANSI C" .PP .CR memset() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4memcpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memccpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memchr()\f1 \- find first occurrence of byte in memory area@@@\f3memory(3C)\f1 .\" index@\f4memcmp()\f1 \- compare byte with memory contents@@@\f3memory(3C)\f1 .\" index@\f4memmove()\f1 \- move memory contents@@@\f3memory(3C)\f1 .\" index@\f4memset()\f1 \- set area in memory to contain a specified byte@@@\f3memory(3C)\f1 .\" index@\f4bcopy()\f1 \- \s-1BSD\s+1 memory copy@@@\f3memory(3C)\f1 .\" index@\f4bcmp()\f1 \- \s-1BSD\s+1 memory compare@@@\f3memory(3C)\f1 .\" index@\f4bzero()\f1 \- \s-1BSD\s+1 memory clear@@@\f3memory(3C)\f1 .\" index@\f4ffs()\f1 \- \s-1BSD\s+1 find first set bit@@@\f3memory(3C)\f1 .\" index@\f1memory operations \- copy, compare, test for contents, or set contents to value@@@\f3memory(3C)\f1 .\" index@\f1copy memory to another area@@@\f3memory(3C)\f1 .\" index@\f1test contents of memory area@@@\f3memory(3C)\f1 .\" index@\f1compare contents of memory with byte@@@\f3memory(3C)\f1 .\" index@\f1preset contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1set contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1byte, set contents of memory area to specified@@@\f3memory(3C)\f1 .\" index@\f1byte, compare memory contents with specified@@@\f3memory(3C)\f1 .\" index@\f1byte, find location of in memory@@@\f3memory(3C)\f1 .\" index@\f1location of byte in memory, find@@@\f3memory(3C)\f1 .\" .\" toc@\f3memory(3C)\f1:\0\0\f4memccpy()\f1, \f4memchr()\f1, \f4memcmp()\f1, \f4memcpy()\f1, \f4memset()\f1, \n\f4bcopy()\f1, \f4bcmp()\f1, \f4bzero()\f1, \f4ffs()\f1@@@memory operations .\" toc@\f4memccpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memchr()\f1:\0\0memory operations, locate first character@@@see \f3memory(3C)\f1 .\" toc@\f4memcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memcpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memmove()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memset()\f1:\0\0memory operations, set memory@@@see \f3memory(3C)\f1 .\" toc@\f4bcopy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bzero()\f1:\0\0memory operations, clear bytes@@@see \f3memory(3C)\f1 .\" toc@\f4ffs()\f1:\0\0memory operations, find first bit set@@@see \f3memory(3C)\f1 .\" .\" links@memory.3c memccpy.3c .\" links@memory.3c memchr.3c .\" links@memory.3c memcmp.3c .\" links@memory.3c memcpy.3c .\" links@memory.3c memmove.3c .\" links@memory.3c memset.3c .\" links@memory.3c bcopy.3c .\" links@memory.3c bcmp.3c .\" links@memory.3c bzero.3c .\" links@memory.3c ffs.3c .\" .\" $Header: memory.3c,v 74.1 95/03/23 17:24:13 ssa Exp $ .TA m .TH memory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME memccpy(\|), memchr(\|), memcmp(\|), memcpy(\|), memmove(\|), memset(\|), bcopy(\|), bcmp(\|), bzero(\|), ffs(\|) \- memory operations .SH SYNOPSIS .C "#include " .PP .C "void *memccpy(void *s1, const void *s2, int c, size_t n);" .PP .C "void *memchr(const void *s, int c, size_t n);" .PP .C "int memcmp(const void *s1, const void *s2, size_t n);" .PP .C "void *memcpy(void *s1, const void *s2, size_t n);" .PP .C "void *memmove(void *s1, const void *s2, size_t n);" .PP .C "void *memset(void *s, int c, size_t n);" .PP .C "#include " .PP .C "int bcmp(const void *s1, const void *s2, size_t n);" .PP .C "void bcopy(const void *s1, void *s2, size_t n);" .PP .C "void bzero(char *s, int n);" .PP .C "int ffs(int i);" .SS Remarks: .CR bcmp() , .CR bcopy() , .CR bzero() , .CR ffs() , and .RC < strings.h > are provided solely for portability of .SM BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .CR memcmp() , .CR memmove() , and .CR memset() , respectively. .C ffs() has no portable equivalent. .SH DESCRIPTION These functions operate as efficiently as possible on memory areas (arrays of bytes bounded by a count, not terminated by a null byte). They do not check for the overflow of any receiving memory area. .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RC < string.h > header file. .TP 15 .C memccpy() Copy bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 , stopping after the first occurrence of byte .I c has been copied, or after .I n bytes have been copied, whichever comes first. If copying takes place between objects that overlap, the behavior is undefined. .C memccpy() returns a pointer to the bvyte after the copy of .I c in .IR s1 , or a .SM NULL pointer if .I c was not found in the first .I n bytes of .IR s2 . .TP .C memchr() Locate the first occurrence of .I c (converted to an .CR "unsigned char" ) in the initial .I n bytes (each interpreted as .CR "unsigned char" ) of the object pointed to by .IR s . .C memchr() returns a pointer to the located byte, or a .SM NULL pointer if the byte does not occur in the object. .TP .C memcmp() Compare the first .I n bytes of the object pointed to by .I s1 to the first .I n bytes of the object pointed to by .IR s2 . .C memcmp() returns an integer greater than, equal to, or less than zero, according to whether the object pointed to by .I s1 is greater than, equal to, or less than the object pointed to by .IR s2 . The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes (both interpreted as .CR "unsigned char" ) that differ in the objects being compared. .TP .C memcpy() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . If copying takes place between objects that overlap, the behavior is undefined. .C memcpy() returns the value of .IR s1 . .TP .C memmove() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . Copying takes place as if the .I n bytes from the object pointed to by .I s2 are first copied into a temporary array of .I n bytes that does not overlap the objects pointed to by .I s1 and .IR s2 , and then the .I n bytes from the temporary array are copied into the object pointed to by .IR s1 . .C memmove() returns the value of .IR s1 . .TP .C memset() Copy the value of .I c (converted to an .CR "unsigned char" ) into each of the first .I n bytes of the object pointed to by .IR s . .C memset() returns the value of .IR s . .TP .C bcopy() copies .I n bytes from the area pointed to by .I s1 to the area pointed to by .IR s2 . .TP .C bcmp() Compare the first .I n bytes of the area pointed to by .I s1 with the area pointed to by .IR s2 . .C bcmp() returns zero if they are identical; non-zero otherwise. Both areas are assumed to be .I n bytes in length. .TP .C bzero() Clear .I n bytes in the area pointed to by .I s by setting them to zero. .TP .C ffs() Find the first bit set (beginning with the least significant bit) and return the index of that bit. Bits are numbered starting at one. A return value of 0 indicates that .I i is zero. .SS International Code Set Support These functions support only single-byte byte code sets. .SH WARNINGS The functions defined in .RC < string.h > were previously defined in .RC < memory.h >. .SH FILES .C /usr/include/string.h .SH SEE ALSO string(3C) .SH STANDARDS CONFORMANCE .CR memccpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR memchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memmove() ": AES, SVID3, XPG4, ANSI C" .PP .CR memset() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4memcpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memccpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memchr()\f1 \- find first occurrence of byte in memory area@@@\f3memory(3C)\f1 .\" index@\f4memcmp()\f1 \- compare byte with memory contents@@@\f3memory(3C)\f1 .\" index@\f4memmove()\f1 \- move memory contents@@@\f3memory(3C)\f1 .\" index@\f4memset()\f1 \- set area in memory to contain a specified byte@@@\f3memory(3C)\f1 .\" index@\f4bcopy()\f1 \- \s-1BSD\s+1 memory copy@@@\f3memory(3C)\f1 .\" index@\f4bcmp()\f1 \- \s-1BSD\s+1 memory compare@@@\f3memory(3C)\f1 .\" index@\f4bzero()\f1 \- \s-1BSD\s+1 memory clear@@@\f3memory(3C)\f1 .\" index@\f4ffs()\f1 \- \s-1BSD\s+1 find first set bit@@@\f3memory(3C)\f1 .\" index@\f1memory operations \- copy, compare, test for contents, or set contents to value@@@\f3memory(3C)\f1 .\" index@\f1copy memory to another area@@@\f3memory(3C)\f1 .\" index@\f1test contents of memory area@@@\f3memory(3C)\f1 .\" index@\f1compare contents of memory with byte@@@\f3memory(3C)\f1 .\" index@\f1preset contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1set contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1byte, set contents of memory area to specified@@@\f3memory(3C)\f1 .\" index@\f1byte, compare memory contents with specified@@@\f3memory(3C)\f1 .\" index@\f1byte, find location of in memory@@@\f3memory(3C)\f1 .\" index@\f1location of byte in memory, find@@@\f3memory(3C)\f1 .\" .\" toc@\f3memory(3C)\f1:\0\0\f4memccpy()\f1, \f4memchr()\f1, \f4memcmp()\f1, \f4memcpy()\f1, \f4memset()\f1, \n\f4bcopy()\f1, \f4bcmp()\f1, \f4bzero()\f1, \f4ffs()\f1@@@memory operations .\" toc@\f4memccpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memchr()\f1:\0\0memory operations, locate first character@@@see \f3memory(3C)\f1 .\" toc@\f4memcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memcpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memmove()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memset()\f1:\0\0memory operations, set memory@@@see \f3memory(3C)\f1 .\" toc@\f4bcopy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bzero()\f1:\0\0memory operations, clear bytes@@@see \f3memory(3C)\f1 .\" toc@\f4ffs()\f1:\0\0memory operations, find first bit set@@@see \f3memory(3C)\f1 .\" .\" links@memory.3c memccpy.3c .\" links@memory.3c memchr.3c .\" links@memory.3c memcmp.3c .\" links@memory.3c memcpy.3c .\" links@memory.3c memmove.3c .\" links@memory.3c memset.3c .\" links@memory.3c bcopy.3c .\" links@memory.3c bcmp.3c .\" links@memory.3c bzero.3c .\" links@memory.3c ffs.3c .\" .\" $Header: malloc.3c,v 72.6 94/11/15 09:55:17 ssa Exp $ .TA m .TH malloc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME malloc(), free(), realloc(), calloc(), valloc(), mallopt(), mallinfo(), memorymap(), alloca() \- main memory allocator .SH SYNOPSIS .C "#include " .PP .C "void *malloc(size_t size);" .PP .C "void *calloc(size_t nelem, size_t elsize);" .PP .C "void *realloc(void *ptr, size_t size);" .PP .C "void *valloc(size_t size);" .PP .C "void free(void *ptr);" .PP .C "void memorymap(int show_stats);" .PP .C " " .PP .C "#include " .PP .C "void *alloca(size_t size);" .SH SYSTEM V SYNOPSIS .C "#include " .PP .C "char *malloc(unsigned size);" .PP .C "void free(char *ptr);" .PP .C "char *realloc(char *ptr, unsigned size);" .PP .C "char *calloc(unsigned nelem, unsigned elsize);" .PP .C "int mallopt(int cmd, int value);" .PP .C "struct mallinfo mallinfo(void);" .SS Remarks The functionality in the old .IR malloc (3X) package has been incorporated into .IR malloc (3C). The library .RC ( /usr/lib/libmalloc.a ) corresponding to the .CR -lmalloc linker option is now an empty library. Makefiles that reference this library will continue to work. Applications that used the .IR malloc (3X) package should still work properly with the new .IR malloc (3C) package. If the old versions must be used, they are provided in files .CR /usr/old/libmalloc3x.a and .CR /usr/old/libmalloc3c.o for Release 8.07 only. .SH DESCRIPTION The functions described in this manual entry provide a simple, general purpose memory allocation package: .RS .TP 17 .C malloc() Allocates space for a block of at least .I size bytes, but does not initialize the space. .TP .C calloc() Allocates space for an array of .I nelem elements, each of size .I elsize bytes, and initializes the space to zeros. Actual amount of space allocated will be at least .I nelem * elsize bytes. .TP .C realloc() Changes the size of the block pointed to by .I ptr to .I size bytes and returns a pointer to the (possibly moved) block. Existing contents are unchanged up to the lesser of the new and old sizes. If .I ptr is a NULL pointer, .CR realloc() behaves like .CR malloc() for the specified size. If .I size is zero and .I ptr is not a NULL pointer, the object it points to is freed and NULL is returned. .TP .C valloc() Allocates space for a block of at least .I size bytes starting on a boundary aligned to a multiple of the value returned by .IR sysconf(__SC_PAGESIZE) . This space is uninitialized. .TP .C free() Deallocates the space pointed to by .I ptr (a pointer to a block previously allocated by .CR malloc() , .CR realloc() , or .CR calloc() ) and makes the space available for further allocation. If .I ptr is a NULL pointer, no action occurs. .TP .C mallopt() Provides for control over the allocation algorithm and other options in the .IR malloc (3C) package. The available values for .I cmd are: .RS .RS .TP 15 .C M_MXFAST Set .IR maxfast to .IR value . The algorithm allocates all blocks below the size of .IR maxfast in large groups, then doles them out very quickly. The default value for .IR maxfast is zero. .TP .C M_NLBLKS Set .IR numlblks to .IR value . The above mentioned ``large groups'' each contain .I numlblks blocks. .I numlblks must be greater than 1. The default value for .I numlblks is .CR 100 . .TP .C M_GRAIN Set .I grain to .IR value . The sizes of all blocks smaller than .I maxfast are considered to be rounded up to the nearest multiple of .IR grain . .I grain must be greater than zero. The default value of .I grain is the smallest number of bytes that can accommodate alignment of any data type. .I value is rounded up to a multiple of the default when .I grain is set. .TP .C M_KEEP Preserve data in a freed block until the next .CR malloc() , .CR realloc() , or .CR calloc() . This option is provided only for compatibility with the old version of .CR malloc() and is not recommended. .TP .C M_BLOCK Block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option is provided for those who need to write signal handlers that allocate memory. When set, the .IR malloc (3C) routines can be called from within signal handlers (they become re-entrant). Default action is .I not to block all blockable signals. .TP .C M_UBLOCK Do not block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option cancels signal blocking initiated by the .CR M_BLOCK option. .RE .RE .IP These values are defined in the .CR header file. .IP .CR mallopt() can be called repeatedly, but must not be called after the first small block is allocated (unless .I cmd is set to .CR M_BLOCK or .CR M_UBLOCK ). .TP .C mallinfo() Provides instrumentation describing space usage, but cannot be called until the first small block is allocated. It returns the structure: .nf .IP .C "struct mallinfo {" .C " int arena; /* total space in arena */" .C " int ordblks; /* number of ordinary blocks */" .C " int smblks; /* number of small blocks */" .C " int hblkhd; /* space in holding block headers */" .C " int hblks; /* number of holding blocks */" .C " int usmblks /* space in small blocks in use */" .C " int fsmblks /* space in free small blocks */" .C " int uordblks; /* space in ordinary blocks in use */" .C " int fordblks; /* space in free ordinary blocks */" .C " int keepcost; /* space penalty if keep option is used */" .C } .fi .IP This structure is defined in the .CR header file. .RE .PP Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. .RS .TP 17 .C memorymap() Can be used to display the contents of the memory allocator. A list of addresses and block descriptions is written (using .CR printf() ) to standard output. If the value of the .I show_stats parameter is 1, statistics concerning number of blocks and sizes used will also be written. If the value is zero, only the memory map will be written. .IP The addresses and sizes displayed by .CR memorymap() may not correspond to those requested by an application. The size of a block (as viewed by the allocator) includes header information and padding to properly align the block. The address is also offset by a certain amount to accommodate the header information. .TP .C alloca() Allocates space from the stack of the caller for a block of at least .I size bytes, but does not initialize the space. The space is automatically freed when the calling routine exits. .IP Memory returned by .CR alloca() is not related to memory allocated by other memory allocation functions. Behavior of addresses returned by .CR alloca() as parameters to other memory functions is undefined. .IP The implementation of this routine is system dependent and its use is discouraged. .RE .SH RETURN VALUE Upon successful completion, .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. Otherwise, they return a NULL pointer. If .CR realloc() returns a NULL pointer, the memory pointed to by the original pointer is left intact. .PP .CR mallopt() returns zero for success and nonzero for failure. .SH DIAGNOSTICS .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a NULL pointer if there is no available memory, or if the memory managed by .CR malloc() has been detectably corrupted. This memory may become corrupted if data is stored outside the bounds of a block, or if an invalid pointer (a pointer not generated by .CR malloc() , .CR realloc() , or .CR calloc() ) is passed as an argument to .CR free() or .CR realloc() . .PP If .CR mallopt() is called after any allocation of a small block and .I cmd is not set to .CR M_BLOCK or .CR M_UBLOCK , or if .I cmd or .I value is invalid, nonzero is returned. Otherwise, it returns zero. .SH ERRORS .RS .TP 17 [ENOMEM] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to ENOMEM and return a NULL pointer when an out-of-memory condition arises. .TP [EINVAL] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to EINVAL and return a NULL pointer when the memory being managed by .CR malloc() has been detectably corrupted. .SH WARNINGS .CR malloc() functions use .CR brk() and .CR sbrk() (see .IR brk (2)) to increase the address space of a process. Therefore, an application program that uses .CR brk() or .CR sbrk() must not use them to decrease the address space, because this confuses the .CR malloc() functions. .PP .CR free() and .CR realloc() do not check their pointer argument for validity. .PP If .CR free() or .CR realloc() is passed a pointer that was not the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() , or if space assigned by an allocation function is overrun, loss of data, a memory fault, bus error, or an infinite loop may occur at that time or during any subsequent call to .CR malloc() , .CR realloc() , .CR calloc() , .CR valloc() , or .CR free() . .PP The following actions are not supported and cause undesirable effects: .RS .TP 3 \(bu Attempting to .CR free() or .CR realloc() a pointer not generated as the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() . .RE .PP The following actions are strongly discouraged and may be unsupported in a future implementation of .CR malloc() : .RS .TP 3 \(bu attempting to .CR free() the same block twice, .TP \(bu depending on unmodified contents of a block after it has been freed. .RE .PP Undocumented features of earlier memory allocators have not been duplicated. .SH COMPATIBILITY The only external difference between the old .IR malloc (3X) allocator and the .IR malloc (3C) allocator is that the old allocator would return a NULL pointer for a request of zero bytes. The .IR malloc (3C) allocator returns a valid memory address. This is not a concern for most applications. .ift .br .ift .ne 4 .PP Although the current implementation of .IR malloc (3C) allows for freeing a block twice and does not corrupt the contents of a block after it is freed (until the next call to .CR realloc() , .CR calloc() , .CR malloc() , or .CR valloc() ), support for these features may be discontinued in a future implementation of .IR malloc (3C) and should not be used. .SH SEE ALSO brk(2), errno(2). .SH STANDARDS CONFORMANCE .CR malloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR calloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR free() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mallinfo() ": SVID2, XPG2" .PP .CR mallopt() ": SVID2, SVID3, XPG2" .PP .CR realloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4malloc()\f1 \- allocate block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4free()\f1 \- release allocated block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4realloc()\f1 \- change size of allocated memory block@@@\f3malloc(3C)\f1 .\" index@\f4calloc()\f1 \- allocate memory for array@@@\f3malloc(3C)\f1 .\" index@\f4mallopt()\f1 \- control memory space allocation@@@\f3malloc(3C)\f1 .\" index@\f4mallinfo()\f1 \- display memory space usage@@@\f3malloc(3C)\f1 .\" index@\f4memorymap()\f1 \- display contents of memory allocator@@@\f3malloc(3C)\f1 .\" index@\f4alloca()\f1 \- allocate space from the stack@@@\f3malloc(3C)\f1 .\" index@\f4valloc()\f1 \- allocate space on boundary aligned to sysconf value@@@\f3malloc(3C)\f1 .\" index@\f1main memory allocator@@@\f3malloc(3C)\f1 .\" index@\f1memory allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1main memory space usage, display@@@\f3malloc(3C)\f1 .\" index@\f1main memory space allocation, control@@@\f3malloc(3C)\f1 .\" .\" toc@\f3malloc(3C)\f1:\0\0\f4alloca()\f1, \f4calloc()\f1, \f4free()\f1, \f4mallinfo()\f1,\n\f4malloc()\f1, \f4mallopt()\f1, \f4memorymap()\f1, \f4realloc()\f1, \f4valloc()\f1@@@main memory allocator\f1 .\" .\" toc@\f4free()\f1:\0\0release allocated block of main memory@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4realloc()\f1:\0\0change size of allocated memory block@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4calloc()\f1:\0\0allocate memory for array@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4valloc()\f1:\0\0allocate space on boundary aligned to sysconf value@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallopt()\f1:\0\0control memory space allocation@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallinfo()\f1:\0\0display memory space usage@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4memorymap()\f1:\0\0display contents of memory allocator@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4alloca()\f1:\0\0allocate space from the stack@@@\f1see \f3malloc(3C)\f1 .\" .\" links@malloc.3c free.3c .\" links@malloc.3c realloc.3c .\" links@malloc.3c calloc.3c .\" links@malloc.3c valloc.3c .\" links@malloc.3c mallopt.3c .\" links@malloc.3c mallinfo.3c .\" links@malloc.3c memorymap.3c .\" links@malloc.3c alloca.3c .\" $Header: memory.3c,v 74.1 95/03/23 17:24:13 ssa Exp $ .TA m .TH memory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME memccpy(\|), memchr(\|), memcmp(\|), memcpy(\|), memmove(\|), memset(\|), bcopy(\|), bcmp(\|), bzero(\|), ffs(\|) \- memory operations .SH SYNOPSIS .C "#include " .PP .C "void *memccpy(void *s1, const void *s2, int c, size_t n);" .PP .C "void *memchr(const void *s, int c, size_t n);" .PP .C "int memcmp(const void *s1, const void *s2, size_t n);" .PP .C "void *memcpy(void *s1, const void *s2, size_t n);" .PP .C "void *memmove(void *s1, const void *s2, size_t n);" .PP .C "void *memset(void *s, int c, size_t n);" .PP .C "#include " .PP .C "int bcmp(const void *s1, const void *s2, size_t n);" .PP .C "void bcopy(const void *s1, void *s2, size_t n);" .PP .C "void bzero(char *s, int n);" .PP .C "int ffs(int i);" .SS Remarks: .CR bcmp() , .CR bcopy() , .CR bzero() , .CR ffs() , and .RC < strings.h > are provided solely for portability of .SM BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .CR memcmp() , .CR memmove() , and .CR memset() , respectively. .C ffs() has no portable equivalent. .SH DESCRIPTION These functions operate as efficiently as possible on memory areas (arrays of bytes bounded by a count, not terminated by a null byte). They do not check for the overflow of any receiving memory area. .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RC < string.h > header file. .TP 15 .C memccpy() Copy bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 , stopping after the first occurrence of byte .I c has been copied, or after .I n bytes have been copied, whichever comes first. If copying takes place between objects that overlap, the behavior is undefined. .C memccpy() returns a pointer to the bvyte after the copy of .I c in .IR s1 , or a .SM NULL pointer if .I c was not found in the first .I n bytes of .IR s2 . .TP .C memchr() Locate the first occurrence of .I c (converted to an .CR "unsigned char" ) in the initial .I n bytes (each interpreted as .CR "unsigned char" ) of the object pointed to by .IR s . .C memchr() returns a pointer to the located byte, or a .SM NULL pointer if the byte does not occur in the object. .TP .C memcmp() Compare the first .I n bytes of the object pointed to by .I s1 to the first .I n bytes of the object pointed to by .IR s2 . .C memcmp() returns an integer greater than, equal to, or less than zero, according to whether the object pointed to by .I s1 is greater than, equal to, or less than the object pointed to by .IR s2 . The sign of a non-zero return value is determined by the sign of the difference between the values of the first pair of bytes (both interpreted as .CR "unsigned char" ) that differ in the objects being compared. .TP .C memcpy() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . If copying takes place between objects that overlap, the behavior is undefined. .C memcpy() returns the value of .IR s1 . .TP .C memmove() Copy .I n bytes from the object pointed to by .I s2 into the object pointed to by .IR s1 . Copying takes place as if the .I n bytes from the object pointed to by .I s2 are first copied into a temporary array of .I n bytes that does not overlap the objects pointed to by .I s1 and .IR s2 , and then the .I n bytes from the temporary array are copied into the object pointed to by .IR s1 . .C memmove() returns the value of .IR s1 . .TP .C memset() Copy the value of .I c (converted to an .CR "unsigned char" ) into each of the first .I n bytes of the object pointed to by .IR s . .C memset() returns the value of .IR s . .TP .C bcopy() copies .I n bytes from the area pointed to by .I s1 to the area pointed to by .IR s2 . .TP .C bcmp() Compare the first .I n bytes of the area pointed to by .I s1 with the area pointed to by .IR s2 . .C bcmp() returns zero if they are identical; non-zero otherwise. Both areas are assumed to be .I n bytes in length. .TP .C bzero() Clear .I n bytes in the area pointed to by .I s by setting them to zero. .TP .C ffs() Find the first bit set (beginning with the least significant bit) and return the index of that bit. Bits are numbered starting at one. A return value of 0 indicates that .I i is zero. .SS International Code Set Support These functions support only single-byte byte code sets. .SH WARNINGS The functions defined in .RC < string.h > were previously defined in .RC < memory.h >. .SH FILES .C /usr/include/string.h .SH SEE ALSO string(3C) .SH STANDARDS CONFORMANCE .CR memccpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR memchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR memmove() ": AES, SVID3, XPG4, ANSI C" .PP .CR memset() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4memcpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memccpy()\f1 \- copy bytes from memory to another memory location@@@\f3memory(3C)\f1 .\" index@\f4memchr()\f1 \- find first occurrence of byte in memory area@@@\f3memory(3C)\f1 .\" index@\f4memcmp()\f1 \- compare byte with memory contents@@@\f3memory(3C)\f1 .\" index@\f4memmove()\f1 \- move memory contents@@@\f3memory(3C)\f1 .\" index@\f4memset()\f1 \- set area in memory to contain a specified byte@@@\f3memory(3C)\f1 .\" index@\f4bcopy()\f1 \- \s-1BSD\s+1 memory copy@@@\f3memory(3C)\f1 .\" index@\f4bcmp()\f1 \- \s-1BSD\s+1 memory compare@@@\f3memory(3C)\f1 .\" index@\f4bzero()\f1 \- \s-1BSD\s+1 memory clear@@@\f3memory(3C)\f1 .\" index@\f4ffs()\f1 \- \s-1BSD\s+1 find first set bit@@@\f3memory(3C)\f1 .\" index@\f1memory operations \- copy, compare, test for contents, or set contents to value@@@\f3memory(3C)\f1 .\" index@\f1copy memory to another area@@@\f3memory(3C)\f1 .\" index@\f1test contents of memory area@@@\f3memory(3C)\f1 .\" index@\f1compare contents of memory with byte@@@\f3memory(3C)\f1 .\" index@\f1preset contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1set contents of memory area to specified byte@@@\f3memory(3C)\f1 .\" index@\f1byte, set contents of memory area to specified@@@\f3memory(3C)\f1 .\" index@\f1byte, compare memory contents with specified@@@\f3memory(3C)\f1 .\" index@\f1byte, find location of in memory@@@\f3memory(3C)\f1 .\" index@\f1location of byte in memory, find@@@\f3memory(3C)\f1 .\" .\" toc@\f3memory(3C)\f1:\0\0\f4memccpy()\f1, \f4memchr()\f1, \f4memcmp()\f1, \f4memcpy()\f1, \f4memset()\f1, \n\f4bcopy()\f1, \f4bcmp()\f1, \f4bzero()\f1, \f4ffs()\f1@@@memory operations .\" toc@\f4memccpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memchr()\f1:\0\0memory operations, locate first character@@@see \f3memory(3C)\f1 .\" toc@\f4memcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memcpy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memmove()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4memset()\f1:\0\0memory operations, set memory@@@see \f3memory(3C)\f1 .\" toc@\f4bcopy()\f1:\0\0memory operations, copy bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bcmp()\f1:\0\0memory operations, compare bytes@@@see \f3memory(3C)\f1 .\" toc@\f4bzero()\f1:\0\0memory operations, clear bytes@@@see \f3memory(3C)\f1 .\" toc@\f4ffs()\f1:\0\0memory operations, find first bit set@@@see \f3memory(3C)\f1 .\" .\" links@memory.3c memccpy.3c .\" links@memory.3c memchr.3c .\" links@memory.3c memcmp.3c .\" links@memory.3c memcpy.3c .\" links@memory.3c memmove.3c .\" links@memory.3c memset.3c .\" links@memory.3c bcopy.3c .\" links@memory.3c bcmp.3c .\" links@memory.3c bzero.3c .\" links@memory.3c ffs.3c .\" .\" $Header: meta.3x,v 76.2 95/08/01 11:46:02 ssa Exp $ .TA m .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH meta 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME meta \(em enable/disable meta-keys .SH SYNOPSIS .C "#include " .P .C "int meta(WINDOW *\f2win\fP, bool \f2bf\fP);" .SH DESCRIPTION Initially, whether the terminal returns 7 or 8 significant bits on input depends on the control mode of the display driver (see the \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification , \f3General Terminal Interface\fP). To force 8 bits to be returned, invoke \f2meta\f1(\f2win\f1, TRUE). To force 7 bits to be returned, invoke \f2meta\f1(\f2win\f1, FALSE). The \f2win\f1 argument is always ignored. If the \f3terminfo\f1 capabilities \f3smm\f1 (meta_on) and \f3rmm\f1 (meta_off) are defined for the terminal, \f3smm\f1 is sent to the terminal when \f2meta\f1(\f2win\f1, TRUE) is called and \f3rmm\f1 is sent when \f2meta\f1(\f2win\f1, FALSE) is called. .SH "RETURN VALUE" Upon successful completion, .Fn meta returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The same effect is achieved outside Curses using the CS7 or CS8 control mode flag specified in the \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification (\f3General Terminal Interface\fP). .P The .Fn meta function was designed for use with terminals with 7-bit character sets and a ``meta'' key that could be used to set the eighth bit. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, getch(), , \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Section 9.2, \f3Parameters That Can Be Set\f1 (ISTRIP flag). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4meta()\f1 \- enable/disable meta-keys@@@\f3meta(3X)\f1 .\" index@\f1enable/disable meta-keys@@@\f3meta(3X)\f1 .\" index@\f1disable/enable meta-keys@@@\f3meta(3X)\f1 .\" index@\f1meta-keys, enable/disable@@@\f3meta(3X)\f1 .\" .\" toc@\f3meta(3X)\f1:\0\0\f4meta()\f1@@@enable/disable meta-keys .\" .\" fileset_database@meta.3x CURS-ENG-A-MAN .\" $Header: crt0.3,v 72.4 94/09/02 14:40:25 ssa Exp $ .TA c .TH crt0 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crt0.o, gcrt0.o, mcrt0.o \- execution startup routines .SH DESCRIPTION .PP The C, Pascal, and FORTRAN compilers link in the object files .CR crt0.o , .CR gcrt0.o , or .C mcrt0.o to provide startup capabilities and environments for program execution. All are identical except that .C gcrt0.o and .C mcrt0.o provide additional functionality for .IR gprof (1) and .IR prof (1) profiling support respectively. .PP The following symbols are defined in these object files: .RS .TP 20 .C _\|_argc_value A variable of type .I int containing the number of arguments. .TP .C _\|_argv_value An array of character pointers to the arguments themselves. .TP .C _environ An array of character pointers to the environment in which the program will run. This array is terminated by a null pointer. .TP .SM .C _FPU_MODEL A variable of type .I short containing the FPU model number returned by the FP status instruction. This variable is initialized with data from the kernel. .TP .SM .C _FPU_REVISION A variable of type .I short containing the FPU revision number returned by the FP status instruction. This variable is initialized with data from the kernel. .TP .SM .C _CPU_REVISION A variable of type .I int containing the CPU revision of the machine. This variable is initialized with data from the kernel. .TP .SM .C _SYSTEM_ID A variable of type .I int containing the system id value for an executable program. .TP .SM .C $START$ Execution start address. .TP .C _start A secondary startup routine for C programs, called from .CR $START$ , which in turn calls .CR main . This routine is contained in the C library rather than the .C crt0.o file. For Pascal and F\s-2ORTRAN\s0 programs, this symbol labels the beginning of the outer block (main program) and is generated by the compilers. .TP .C $global$ The initial address of the program's data pointer. The startup code loads this address into general register 27. .TP .C $UNWIND_START The beginning of the stack unwind table. .TP .C $UNWIND_END The end of the stack unwind table. .TP .C $RECOVER_START The beginning of the try/recover table. .TP .C $RECOVER_END The end of the try/recover table. .RE .PP The .C crt0.o file defines a null procedure for .CR _mcount , so programs compiled with profiling can be linked without profiling. .PP The linker defines the following two symbols: .RS .TP 20 .C _\|_text_start The beginning address of the program's text area. .PD 0 .TP .C _\|_data_start The beginning address of the program's data area. .PD .RE .SH AUTHOR The features described in this entry originated from .SM AT&T UNIX System III. .SH SEE ALSO .PD .SS Profiling and Debugging Tools: .TP 18 .IR gprof(1) display call graph profile data .PD 0 .TP .IR monitor(3C) prepare execution profile .TP .IR prof(1) display profile data .TP .IR profil(2) execution time profile .PD .SS System Tools: .TP 18 .IR cc(1) invoke the HP-UX C compiler .PD 0 .TP .IR exec(2) execute a file .TP f77(1) invoke the HP-UX FORTRAN compiler .TP .IR ld(1) invoke the link editor .TP .IR pc(1) invoke the HP-UX Pascal compiler .PD .SS Miscellaneous: .TP 18 .IR end(3C) symbol of the last locations in program .PD .\" .\" index@\f4crt0.o\f1, \f4gcrt0.o\f1, \f4mcrt0.o\f1, \f4frt0.o\f1, \f4mfrt0.o\f1 \- execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4crt0.o\f1, \f4mcrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4gcrt0.o\f1, \f4gfrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4gfrt0.o\f1, \f4gcrt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4mcrt0.o\f1, \f4crt0.o\f1 \- C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4frt0.o\f1, \f4mfrt0.o\f1 \- F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@\f4mfrt0.o\f1, \f4frt0.o\f1 \- F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@C and Pascal execution startup routines@@@\f3crt0(3)\f1 .\" index@Pascal and C execution startup routines@@@\f3crt0(3)\f1 .\" index@F\s-2ORTRAN\s+2 execution startup routines@@@\f3crt0(3)\f1 .\" index@execution startup routines, C, Pascal, and F\s-2ORTRAN\s+2@@@\f3crt0(3)\f1 .\" .\" toc@\f3crt0(3)\f1:\0\0\f4crt0.o\f1, \f4mcrt0.o\f1, \f4frt0.o\f1, \f4mfrt0.o\f1@@@execution startup routines .\" toc@\f4crt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4gcrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4mcrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4frt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" toc@\f4mfrt0.o\f1:\0\0execution startup routines@@@see \f3crt0(3)\f1 .\" .\" links@crt0.3 crt0.o.3 .\" links@crt0.3 gcrt0.o.3 .\" links@crt0.3 mcrt0.o.3 .\" links@crt0.3 frt0.o.3 .\" links@crt0.3 gfrt0.o.3 .\" links@crt0.3 mfrt0.o.3 .\" .\" fileset_database@crt0.3 PROGRAMING-MAN .\" $Header: mkfifo.3c,v 72.5 94/11/15 09:55:25 ssa Exp $ .TA m .TH mkfifo 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mkfifo(\|) \- make a \s-1FIFO\s0 file .SH SYNOPSIS .C "#include " .PP .C "int mkfifo(char *path, mode_t mode);" .SH DESCRIPTION .C mkfifo() creates a new .SM FIFO (first-in-first-out) file, at the path name to which .IR path points. The file permission bits of the new file are initialized from the .I mode argument, as modified by the process's file creation mask: for each bit set in the process's file mode creation mask, the corresponding bit in the new file's mode is cleared (see .IR umask (2)). Bits in .I mode other than the file permission bits are ignored. .PP The .SM FIFO owner .SM ID is set to the process's effective-user-\c .SM ID. The .SM FIFO group .SM ID is set to the group .SM ID of the parent directory if the set-group-\c .SM ID bit is set on that directory. Otherwise the .SM FIFO group .SM ID is set to the process's effective group .SM ID. .PP For details of the .SM I/O behavior of pipes see .IR read (2) and .IR write (2). .PP The following symbolic constants are defined in the .RC < sys/stat.h > header, and should be used to construct the value of the .I mode argument. The value passed should be the bitwise inclusive .SM OR of the desired permissions: .RS .TP 15 .PD 0 .C S_IRUSR Read by owner. .TP .C S_IWUSR Write by owner. .TP .C S_IRGRP Read by group. .TP .C S_IWGRP Write by group. .TP .C S_IROTH Read by other users. .TP .C S_IWOTH Write by other users. .PD .RE .SH RETURN VALUE .C mkfifo() returns 0 upon successful completion. Otherwise, it returns \-1, no .SM FIFO is created, and .C errno is set to indicate the error. .SH ERRORS .C mkfifo() fails and the new file is not created if any of the following conditions are encountered: .RS .TP 15 .SM [EACCES] A component of the path prefix denies search permission. .TP .SM [EEXIST] The named file already exists. .TP .SM [EFAULT] The .I path argument points outside the process's allocated address space. The reliable detection of this error is implementation dependent. .TP .SM [ELOOP] Too many symbolic links encountered in translating the path name. .TP .SM [ENAMETOOLONG] The length of the specified path name exceeds .C PATH_MAX bytes, or the length of a component of the path name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ENOENT] A component of the path prefix does not exist. .TP .SM [ENOENT] The .I path argument is null. .TP .SM [ENOSPC] Not enough space on the file system. .TP .SM [ENOTDIR] A component of the path prefix is not a directory. .TP .SM [EROFS] The directory in which the file is being created is located in a read-only file system. .RE .SH SEE ALSO chmod(2), mknod(2), pipe(2), stat(2), umask(2), fs(4), mknod(5), stat(5), types(5). .SH AUTHOR .C mkfifo() was developed by HP. .SH STANDARDS CONFORMANCE .CR mkfifo() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4mkfifo()\fP \- make a \s-1FIFO\s+1 special file@@@\f3mkfifo(3C)\f1 .\" index@make a \s-1FIFO\s+1 special file@@@\f3mkfifo(3C)\f1 .\" index@\s-1FIFO\s+1 special file, make a@@@\f3mkfifo(3C)\f1 .\" index@special file, \s-1FIFO\s+1, make a@@@\f3mkfifo(3C)\f1 .\" index@device file, \s-1FIFO\s+1, make a@@@\f3mkfifo(3C)\f1 .\" .\" toc@\f3mkfifo(3C)\f1:\0\0\f4mkfifo()\fP@@@make a \s-1FIFO\s+1 special file .\" .\" fileset_database@mkfifo.3c PROGRAMING-MAN .\" $Header: mktemp.3c,v 72.5 94/11/15 09:55:26 ssa Exp $ .TA m .TH mktemp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mktemp(\|), mkstemp(\|) \- make a unique file name .SH SYNOPSIS .C "#include " .PP .C "char *mktemp(char *template);" .PP .C "int mkstemp(char *template);" .SS Remarks: These functions are provided solely for backward compatibility and importability of applications, and are not recommended for new applications where portability is important. For portable applications, use .C tmpfile() instead (see .IR tmpfile (3S)). .SH DESCRIPTION .C mktemp() replaces the contents of the string pointed to by .I template by a unique file name, and returns the address of .IR template . The string in .I template should look like a file name with six trailing .CR X s; .C mktemp() replaces the .CR X s with a letter and the current process .SM ID. The letter is chosen such that the resulting name does not duplicate the name of an existing file. If there are fewer than six .CR X s, the letter is dropped first, followed by dropping the high-order digits of the process .SM ID. .PP .C mkstemp() makes the same replacement to the template, but also returns a file descriptor for the template file after opening the file for reading and writing. .C mkstemp() thus prevents any possible race condition between testing whether the file exists and opening it for use. .SH RETURN VALUE .C mktemp() returns its argument except when it runs out of letters, in which case the result is a pointer to the empty string .ift \f4\s+1""\fP\s0. .ifn \f3""\fP. .PP .C mkstemp() returns an open file descriptor upon successful completion, or \-1 if no suitable file could be created. .SH SEE ALSO getpid(2), open(2), tmpfile(3S), tmpnam(3S). .SH WARNINGS It is possible to run out of letters. .PP .C mktemp() and .C mkstemp() do not check to determine whether the file name part of .I template exceeds the maximum allowable file name length. .SH STANDARDS CONFORMANCE .CR mktemp() ": SVID2, SVID3, XPG2" .\" .\" index@\f4mktemp()\fP \- make a unique (temporary) file name@@@\f3mktemp(3C)\f1 .\" index@make a unique (usually temporary) file name@@@\f3mktemp(3C)\f1 .\" index@create a unique (usually temporary) file name@@@\f3mktemp(3C)\f1 .\" index@unique (usually temporary) file name, make a@@@\f3mktemp(3C)\f1 .\" index@temporary (unique) file name, make a@@@\f3mktemp(3C)\f1 .\" index@file: make a unique (usually temporary) file name@@@\f3mktemp(3C)\f1 .\" .\" toc@\f3mktemp(3C)\f1:\0\0\f4mktemp()\fP@@@make a unique file name .\" .\" links@mktemp.3c mkstemp.3c .\" .\" fileset_database@mktemp.3c PROGRAMING-MAN .\" $Header: mktemp.3c,v 72.5 94/11/15 09:55:26 ssa Exp $ .TA m .TH mktemp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mktemp(\|), mkstemp(\|) \- make a unique file name .SH SYNOPSIS .C "#include " .PP .C "char *mktemp(char *template);" .PP .C "int mkstemp(char *template);" .SS Remarks: These functions are provided solely for backward compatibility and importability of applications, and are not recommended for new applications where portability is important. For portable applications, use .C tmpfile() instead (see .IR tmpfile (3S)). .SH DESCRIPTION .C mktemp() replaces the contents of the string pointed to by .I template by a unique file name, and returns the address of .IR template . The string in .I template should look like a file name with six trailing .CR X s; .C mktemp() replaces the .CR X s with a letter and the current process .SM ID. The letter is chosen such that the resulting name does not duplicate the name of an existing file. If there are fewer than six .CR X s, the letter is dropped first, followed by dropping the high-order digits of the process .SM ID. .PP .C mkstemp() makes the same replacement to the template, but also returns a file descriptor for the template file after opening the file for reading and writing. .C mkstemp() thus prevents any possible race condition between testing whether the file exists and opening it for use. .SH RETURN VALUE .C mktemp() returns its argument except when it runs out of letters, in which case the result is a pointer to the empty string .ift \f4\s+1""\fP\s0. .ifn \f3""\fP. .PP .C mkstemp() returns an open file descriptor upon successful completion, or \-1 if no suitable file could be created. .SH SEE ALSO getpid(2), open(2), tmpfile(3S), tmpnam(3S). .SH WARNINGS It is possible to run out of letters. .PP .C mktemp() and .C mkstemp() do not check to determine whether the file name part of .I template exceeds the maximum allowable file name length. .SH STANDARDS CONFORMANCE .CR mktemp() ": SVID2, SVID3, XPG2" .\" .\" index@\f4mktemp()\fP \- make a unique (temporary) file name@@@\f3mktemp(3C)\f1 .\" index@make a unique (usually temporary) file name@@@\f3mktemp(3C)\f1 .\" index@create a unique (usually temporary) file name@@@\f3mktemp(3C)\f1 .\" index@unique (usually temporary) file name, make a@@@\f3mktemp(3C)\f1 .\" index@temporary (unique) file name, make a@@@\f3mktemp(3C)\f1 .\" index@file: make a unique (usually temporary) file name@@@\f3mktemp(3C)\f1 .\" .\" toc@\f3mktemp(3C)\f1:\0\0\f4mktemp()\fP@@@make a unique file name .\" .\" links@mktemp.3c mkstemp.3c .\" .\" fileset_database@mktemp.3c PROGRAMING-MAN .\" $Header: ctime.3c,v 76.1 95/07/05 17:27:14 ssa Exp $ .TA c .TH ctime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctime(\|), ctime_r(\|), localtime(\|), localtime_r(\|), gmtime(\|), gmtime_r(\|), mktime(\|), difftime(\|), asctime(\|), asctime_r(\|), timezone(\|), daylight(\|), tzname(\|), tzset(\|) \- convert date and time to string .SH SYNOPSIS .nf .C "#include " .PP .C "char *asctime(const struct tm *timeptr);" .PP .C "int asctime_r(const struct tm *timeptr, char *buffer, int buflen);" .PP .C "char *ctime(const time_t *timer);" .PP .C "int ctime_r(const time_t *timer, char *buffer, int buflen);" .PP .C "double difftime(time_t time1, time_t time0);" .PP .C "struct tm *gmtime(const time_t *timer);" .PP .C "int gmtime_r(const time_t *timer, struct tm *result);" .PP .C "struct tm *localtime(const time_t *timer);" .PP .C "int localtime_r(const time_t *timer, struct tm *result);" .PP .C "time_t mktime(struct tm *timeptr);" .PP .C "extern long timezone;" .PP .C "extern int daylight;" .PP .C "extern char *tzname[2];" .PP .C "void tzset(void);" .fi .SH DESCRIPTION .TP 18 .C asctime() Convert the broken-down time contained in the structure pointed to by .I timeptr and return a pointer to a 26-character string in the form: .RS .IP .C "Sun Sep 16 01:03:52 1973\en\e0" .RE .IP All the fields have constant width. .TP .C asctime_r() is identical to .CR asctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C ctime() Convert the calendar time pointed to by .IR timer , representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: .RS .IP .C asctime(localtime(timer)) .RE .TP .C ctime_r() is identical to .CR ctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C gmtime() Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. .C gmtime() returns a pointer to the .C tm structure described below. .TP .C gmtime_r() is identical to .CR gmtime() , except that .C gmtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C localtime() Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA\c), according to the contents of the TZ environment variable (see Environment Variables below). .C localtime() returns a pointer to the .C tm structure described below. .TP .C localtime_r() is identical to .CR localtime() , except that .C localtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C difftime() Return the difference in seconds between two calendar times: .IR "time1 \(mi time0" . .TP .C mktime() Convert the broken-down time (expressed as local time) in the structure pointed to by .I timeptr into a calendar time value with the same encoding as that of the values returned by .IR time (2). The original values of the .C tm_wday and .C tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below. .IP A positive or zero value for .C tm_isdst causes .C mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for .C tm_isdst causes .C mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time. .IP Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of .C tm_mday is not set until .C tm_mon and .C tm_year are determined. .C mktime() returns the specified calendar time encoded as a value of type .CR time_t . .IP If the calendar time cannot be represented, the function returns the value .RC ( time_t )\|\(em\|1 and sets .C errno to .CR ERANGE . Note the value .RC ( time_t )\|\(em\|1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and .C errno to reliably detect an error condition. .TP .C tzset() Sets the values of the external variables .IR timezone , .IR daylight , and .I tzname according to the contents of the .C TZ environment variable (independent of any time value). The functions .CR localtime() , .CR mktime() , .CR ctime() , .CR asctime() , and .C strftime() (see .IR strftime (3C)) call .C tzset() and use the values returned in the external variables described below for their operations. .C tzset() can also be called directly by the user. .PP The .RC < time.h > header file contains declarations of all relevant functions and externals. It also contains the .C tm structure, which includes the following members: .RS .PP .nf .ift .ft 4 .ps +1 int tm_sec; /* seconds after the minute - [0,61] */ int tm_min; /* minutes after the hour - [0,59] */ int tm_hour; /* hours - [0,23] */ int tm_mday; /* day of month - [1,31] */ int tm_mon; /* month of year - [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday - [0,6] */ int tm_yday; /* days since January 1 - [0,365] */ int tm_isdst; /* daylight savings time flag */ .ift .ft .ps .fi .PP The value of .C tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available. .RE .PP The external variable .C timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), .C timezone is 5\(**60\(**60). The external variable .C daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable .C tzname[2] contains the local standard and local summer time zone abbreviations as specified by the .C TZ environment variable. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .SS Environment Variables The .C tzset() function uses the contents of .C TZ to set the values of the external variables .CR timezone , .C daylight , and .CR tzname . .C TZ also determines the time zone name substituted for the .C %Z and .C %z directives and the time zone adjustments performed by .CR localtime() , .CR mktime() , and .CR ctime() . Two methods for specifying a time zone within .C TZ are described in .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH "RETURN VALUE" .PP For .C asctime_r() and .C ctime_r(), if the buffer is of insufficient length, -1 is returned. For .C asctime_r(), ctime_r(), gmtime_r(), and .C localtime_r(), if the operation is successful, 0 is returned. .SH WARNINGS The return values for .CR asctime() , .CR ctime() , .CR gmtime() , and .CR localtime() point to static data whose contents is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() are MT-Safe and should be used instead. .PP Users of .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .PP The range of .C tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by .IR time (2) and passed as the .I timer argument does not include accumulated leap seconds. The .C tm structure generated by .C localtime() and .C gmtime() will never reflect any leap seconds. Upon successful completion, .C mktime() forces the value of the .C tm_sec component to the range [0,59]. .PP .CR ctime() , .CR ctime_r() , .CR asctime() , and .CR asctime_r() are considered obsolescent and may be removed in a future release. Use of .IR strftime (3C) is recommended instead. .SH AUTHOR .C ctime() was developed by AT&T and HP. .SH SEE ALSO time(2), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR ctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR asctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR daylight ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR difftime() ": AES, SVID3, XPG4, ANSI C" .PP .CR gmtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR localtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mktime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR timezone ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR tzname ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tzset() ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4asctime()\fP, \f4asctime_r()\f1 \- convert \f3tm\f1 structure date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4ctime()\fP, \f4ctime_r()\f1 \- convert \f4clock()\fP date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4daylight()\fP \- Daylight Savings Time flag@@@\f3ctime(3C)\f1 .\" index@\f4gmtime()\fP, \f4gmtime_r()\fP \- convert date and time to Greenwich Mean Time@@@\f3ctime(3C)\f1 .\" index@\f4localtime()\fP, \f4localtime_r()\fP \- convert date and time to local timezone@@@\f3ctime(3C)\f1 .\" index@\f4timezone()\fP \- difference between \s-1UCT\s+1 and local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzname()\fP \- name of local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzset()\fP \- initialize \f4timezone()\fP, \f4daylight()\fP, and \f4tzname()\fP using \s-1TZ\s+1 variable@@@\f3ctime(3C)\f1 .\" index@\f4mktime()\fP \- convert time into calendar time value@@@\f3ctime(3C)\f1 .\" index@\f4difftime()\fP \- difference between two calendar time values@@@\f3ctime(3C)\f1 .\" index@convert date and time to string@@@\f3ctime(3C)\f1 .\" index@string, convert date and time to@@@\f3ctime(3C)\f1 .\" index@date and time, convert to string@@@\f3ctime(3C)\f1 .\" index@time and date, convert to string@@@\f3ctime(3C)\f1 .\" .\" toc@\f3ctime(3C)\f1:\0\0\f4ctime()\fP, \f4ctime_r()\fP, \f4localtime()\fP, \f4localtime_r()\fP, \f4difftime()\f1, \f4 mktime()\f1, \n\f4gmtime()\fP, \f4gmtime_r()\fP,\f4asctime()\fP, \f4asctime_r()\fP, \f4timezone()\fP, \f4daylight()\fP, \f4tzname()\fP,\n\f4tzset()\f1@@@convert date and time to string .\" toc@\f4ctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4ctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4timezone()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4daylight()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzname()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzset()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4difftime()\fP:\0\0difference between calendar times@@@see \f3ctime(3C)\f1 .\" toc@\f4mktime()\fP:\0\0create calendar time value@@@see \f3ctime(3C)\f1 .\" .\" links@ctime.3c ctime_r.3c .\" links@ctime.3c localtime.3c .\" links@ctime.3c localtime_r.3c .\" links@ctime.3c gmtime.3c .\" links@ctime.3c gmtime_r.3c .\" links@ctime.3c asctime.3c .\" links@ctime.3c asctime_r.3c .\" links@ctime.3c timezone.3c .\" links@ctime.3c daylight.3c .\" links@ctime.3c tzname.3c .\" links@ctime.3c tzset.3c .\" links@ctime.3c difftime.3c .\" links@ctime.3c mktime.3c .\" .\" fileset_database@ctime.3c PROGRAMING-MAN .\" $Header: mktimer.3c,v 72.5 94/11/15 09:55:28 ssa Exp $ .TA m .TH mktimer 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mktimer \- allocate a per-process timer .SH SYNOPSIS .C "#include " .PP .C "timer_t mktimer(int clock_type, int notify_type, void *itimercbp);" .SH DESCRIPTION The .CR mktimer() function is used to allocate a per-process timer using the specified system-wide clock as the timing base. .CR mktimer() returns an unique timer ID of type .CR timer_t used to identify the timer in timer requests (see .IR gettimer (3C)). .CR clock_type specifies the system-wide clock to be used as the timing base for the new timer. .CR notify_type specifies the mechanism by which the process is to be notified when the timer expires. .PP .CR mktimer() supports one per-process timer with a .CR clock_type of .CR TIMEOFDAY and .CR notify_type of .CR DELIVERY_SIGNALS . .PP If .CR notify_type is .CR DELIVERY_SIGNALS , the system causes a .CR SIGALRM signal to be sent to the process whenever the timer expires. .PP For .CR clock_type .CR TIMEOFDAY , the machine-dependent clock resolution and maximum value are .CR 1/\c .CR HZ and .CR MAX_ALARM seconds, respectively. These constants are defined in .RC < sys/param.h >. .SH RETURN VALUE Upon successful completion, .CR mktimer() returns a .CR timer_t , which can be passed to the per_process timer calls. If unsuccessful, .CR mktimer() returns a value of .RC ( timer_t )\|\(mi1 and sets .CR errno to indicate the error. .SH ERRORS .CR mktimer() fails if any of the following conditions are encountered: .RS .TP 12 [EAGAIN] The calling process has already allocated all of the timers it is allowed. .TP [EINVAL] .CR clock_type is not defined, or does not allow the specified notification mechanism. .RE .SH FILES .TP .C /usr/include/sys/timers.h .TP .C /usr/include/sys/param.h .SH SEE ALSO timer_create(2), getclock(3C), gettimer(3C), reltimer(3C), rmtimer(3C), setclock(3C), .SH STANDARDS CONFORMANCE .CR mktimer() ": AES" .\" .\" toc@\f3mktimer(3C)\f1:\0\0\f4mktimer()\f1@@@allocate a per-process timer\f1 .\" .\" index@\f4mktimer()\f1 \- allocate a per-process timer@@@\f3mktimer(3C)\f1 .\" index@\f1allocate a per-process timer@@@\f3mktimer(3C)\f1 .\" index@\f1per-process timer, allocate a@@@\f3mktimer(3C)\f1 .\" index@\f1timer, allocate a per-process@@@\f3mktimer(3C)\f1 .\" $Header: modf.3m,v 78.2 96/02/13 13:20:15 ssa Exp $ .TA m .TH modf 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME modf(\|) \- decompose floating-point number .SH SYNOPSIS .C "#include " .PP .C "double modf(double x, double *iptr);" .SH DESCRIPTION The .CR modf() function breaks the argument .I x into integral and fractional parts, each of which has the same sign as the argument. It stores the integral part as a .CR double in the object pointed to by .IR iptr . .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE Upon successful completion, the .CR modf() function returns the signed fractional part of .IR x . .PP If .I x is NaN, .CR modf() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR modf() returns zero. .SH ERRORS No errors are defined. .SH "SEE ALSO" frexp(3M), isnan(3M), ldexp(3M), scalb(3M), values(5). .SH STANDARDS CONFORMANCE .CR modf() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4modf\f1 \- decompose floating-point number@@@\f3modf(3M)\f1 .\" index@\f1math: decompose floating-point number@@@\f3modf(3M)\f1 .\" index@\f1decompose floating-point number@@@\f3modf(3M)\f1 .\" index@\f1floating-point number: decompose@@@\f3modf(3M)\f1 .\" .\" toc@\f3modf(3M)\f1:\0\0\f4modf\f1@@@decompose floating-point number .\" $Header: monitor.3c,v 72.5 94/11/15 09:55:29 ssa Exp $ .TA m .TH monitor 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME monitor(\|) \- prepare execution profile .SH SYNOPSIS .C "#include " .PP .C "void monitor(" .nf .PD 0 .IP .C "void (*lowpc)()," .C "void (*highpc)()," .C "WORD *buffer," .C "int bufsize," .C "int nfunc" .PP .C ");" .PD .fi .SH DESCRIPTION An executable program created by .C cc \-p automatically includes calls for .C monitor() with default parameters; .C monitor() need not be called explicitly except to gain fine control over profiling. .PP .C monitor() is an interface to .IR profil (2). .I lowpc and .I highpc are the addresses of two functions; .I buffer is the address of a (user-supplied) array of .I bufsize .SM WORD\s0s (defined in the .RC < mon.h > header file). .C monitor() arranges to record in the buffer a histogram of periodically sampled values of the program counter, and of counts of calls of certain functions. The lowest address sampled is that of .I lowpc and the highest is just below .IR highpc . .I lowpc must not equal 0 for this use of .IR monitor . Not more than .I nfunc call counts can be kept; only calls of functions compiled with the profiling option .C \-p of .IR cc (1) are recorded. (The C Library and Math Library supplied when .C cc \-p is used also have call counts recorded.) .PP For results to be significant, especially where there are small, heavily used routines, it is suggested that the buffer be no more than a few times smaller than the range of locations sampled. .PP To profile the entire program, it is sufficient to use .nf .IP .C extern etext; \h'.5i'... .C "monitor ((int (*)())2, ((int(*)())& etext, buf, bufsize, nfunc);" .fi .PP .I etext lies just above all the program text (see .IR end (3C)). .PP To stop execution monitoring and write the results on file .CR mon.out , use .IP .C "monitor ((int (*)())0, (int(*)())0, 0, 0, 0); .PP .IR prof (1) can then be used to examine the results. .SH FILES .C /usr/lib/libc.a .br .C /usr/lib/libm.a .br .C mon.out .SH SEE ALSO cc(1), prof(1), profil(2), end(3C). .SH STANDARDS CONFORMANCE .CR monitor() ": SVID2, SVID3, XPG2" .\" .\" index@\f4monitor()\fP \- prepare execution profile@@@\f3monitor(3C)\f1 .\" index@prepare execution profile@@@\f3monitor(3C)\f1 .\" index@execution profile, prepare@@@\f3monitor(3C)\f1 .\" index@profile of execution, prepare@@@\f3monitor(3C)\f1 .\" .\" toc@\f3monitor(3C)\f1:\0\0\f4monitor()\fP@@@prepare execution profile .\" .\" fileset_database@monitor.3c PROGRAMING-MAN .\" $Header: mount.3n,v 72.4 94/08/31 15:57:22 ssa Exp $ .TA m .TH mount 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mount \- keep track of remotely mounted file systems .SH SYNOPSIS .C "#include " .SH DESCRIPTION .SS Program number .nf .PP .C "MOUNTPROG" .fi .PP The following are the .CR xdr routines provided: .nf .PP .C "xdr_exportbody(xdrs, ex)" .C " XDR *xdrs;" .C " struct exports *ex;" .PP .C "xdr_exports(xdrs, ex);" .C " XDR *xdrs;" .C " struct exports **ex;" .PP .C "xdr_fhandle(xdrs, fh);" .C " XDR *xdrs;" .C " fhandle_t *fp;" .PP .C "xdr_fhstatus(xdrs, fhs);" .C " XDR *xdrs;" .C " struct fhstatus *fhs;" .PP .C "xdr_groups(xdrs, gr);" .C " XDR *xdrs;" .C " struct groups *gr;" .PP .C "xdr_mountbody(xdrs, ml)" .C " XDR *xdrs;" .C " struct mountlist *ml;" .PP .C "xdr_mountlist(xdrs, ml);" .C " XDR *xdrs;" .C " struct mountlist **ml;" .PP .C "xdr_path(xdrs, path);" .C " XDR *xdrs;" .C " char **path;" .fi .PP .SS Procs .TP 20 .C "MOUNTPROC_MNT" Argument of .CR xdr_path ; returns .CR fhstatus . Requires UNIX authentication. .TP .C "MOUNTPROC_DUMP" No arguments; returns .CR "struct mountlist" .TP .C "MOUNTPROC_UMNT" Argument of .CR xdr_path ; no results. Requires UNIX authentication. .TP .C "MOUNTPROC_UMNTALL" No arguments; no results. Requires UNIX authentication. Unmounts all remote mounts of sender. .TP .C "MOUNTPROC_EXPORT" No arguments; returns .CR "struct exports" .TP .C "MOUNTPROC_EXPORTALL" No arguments; returns .CR "struct exports" .fi .PP .SS Versions .nf .PP .C "MOUNTVERS_ORIG" .fi .PP .SS Structures .nf .PP .C "struct mountlist { /* what is mounted */" .C " char *ml_name;" .C " char *ml_path;" .C " struct mountlist *ml_nxt;" .C " };" .PP .C "struct fhstatus {" .C " int fhs_status;" .C " fhandle_t fhs_fh;" .C " };" .PP .C "/*" .C " * List of exported directories" .C " * An export entry with ex_groups" .C " * NULL indicates an entry which is exported to the world." .C " */" .PP .C "struct exports {" .C " dev_t ex_dev; /* dev of directory */" .C " char *ex_name; /* name of directory */" .C " struct groups *ex_groups; /* groups allowed to */" .C " /* mount this entry */" .C " struct exports *ex_next;" .C " };" .PP .C "struct groups {" .C " char *g_name;" .C " struct groups *g_next;" .C " };" .fi .SH AUTHOR .IR mount (3N) was developed by Sun Microsystems, Inc. .SH SEE ALSO mount(1M), mountd(1M), showmount(1M). .\" .\" index@\f1keep track of remotely mounted file systems@@@\f3mount(3N)\f1 .\" index@\f1remotely mounted file systems, keep track of@@@\f3mount(3N)\f1 .\" index@\f1mounted file systems, keep track of remotely@@@\f3mount(3N)\f1 .\" index@\f1file systems, keep track of remotely mounted@@@\f3mount(3N)\f1 .\" .\" toc@\f3mount(3N)\f1@@@keep track of remotely mounted file systems .\" $Header: move.3x,v 76.2 95/08/01 11:46:48 ssa Exp $ .TA m .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH move 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME move, wmove \(em window cursor location functions .SH SYNOPSIS .C "#include " .P .C "int move(int \f2y\fP, int \f2x\fP);" .P .C "int wmove(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .SH DESCRIPTION The .Fn move and .Fn wmove functions move the cursor associated with the current or specified window to (\f2y\f1, \f2x\f1) relative to the window's origin. This function does not move the terminal's cursor until the next refresh operation. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" toc@\f3move(3X)\f1:\0\0\f4move()\f1, \f4wmove()\f1@@@window cursor location functions .\" toc@\f4wmove()\f1: window cursor location functions@@@see \f3move(3X)\f1 .\" .\" index@\f4move()\f1 \- window cursor location functions@@@\f3move(3X)\f1 .\" index@\f4wmove()\f1 \- window cursor location functions@@@\f3move(3X)\f1 .\" index@\f1window cursor location functions@@@\f3move(3X)\f1 .\" index@\f1cursor, window location functions@@@\f3move(3X)\f1 .\" index@\f1location functions, window cursor@@@\f3move(3X)\f1 .\" index@\f1functions, window cursor location@@@\f3move(3X)\f1 .\" .\" links@move.3x wmove.3x .\" .\" fileset_database@move.3x CURS-ENG-A-MAN .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: multibyte.3c,v 72.6 94/11/15 09:55:30 ssa Exp $ .TA m .TH multibyte 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mblen(\|), mbtowc(\|), mbstowcs(\|), wctomb(\|), wcstombs(\|) \- multibyte characters and strings conversions .SH SYNOPSIS .C "#include " .PP .C "int mblen(const char *s, size_t n);" .PP .C "int mbtowc(wchar_t *pwc, const char *s, size_t n);" .PP .C "int wctomb(char *s, wchar_t wchar);" .PP .C "size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);" .PP .C "size_t wcstombs(char *s, const wchar_t *pwcs, size_t n);" .SH DESCRIPTION A multibyte character is composed of one or more bytes that represent a "whole" character in a character encoding. A wide character (type of .CR wchar_t ) is composed of a fixed number of bytes whose code value can represent any character in a character encoding. .TP 12 .C mblen() Determine the number of bytes in the multibyte character pointed to by .IR s . Equivalent to: .IP .C "mbtowc((wchar_t *)0, s, n);" .IP If .I s is a null pointer, .I mblen returns a nonzero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .I mblen returns the number of bytes in the multibyte character if the next .I n or fewer bytes form a valid multibyte character, or return \-1 if they do not form a valid multibyte character. If .I s points to the null character, .I mblen returns 0. .TP .C mbtowc() Determine the number of bytes in the multibyte character pointed to by .IR s , determine the code for the value of type .C wchar_t corresponding to that multibyte character, then store the code in the object pointed to by .IR pwc . The value of the code corresponding to the null character is zero. At most .I n characters are examined, starting at the character pointed to by .IR s . .IP If .I s is a null pointer, .C mbtowc() returns a non-zero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .C mbtowc() returns the number of bytes in the converted multibyte character if the next .I n or fewer bytes form a valid multibyte character, or \-1 if they do not form a valid multibyte character. If .I s points to the null character, .C mbtowc() returns 0. The value returned is never greater than .I n or the value of the .C MB_CUR_MAX macro. .TP .C wctomb() Determine the number of bytes needed to represent the multibyte character corresponding to the code whose value is .I wchar and store the multibyte character representation in the array object pointed to by .IR s . At most .C MB_CUR_MAX characters are stored. .IP If .I s is a null pointer, .C wctomb() returns a nonzero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .C wctomb() returns the number of bytes in the multibyte character corresponding to the value of .IR wchar , or \-1 if the value of .I wchar does not correspond to a valid multibyte character. The value returned is never greater than the value of the .C MB_CUR_MAX macro. .TP .C mbstowcs() Convert a sequence of multibyte characters from the array pointed to by .I s into a sequence of corresponding codes and store these codes into the array pointed to by .IR pwcs , stopping after either .I n codes or a code with value zero (a converted null character) is stored. Each multibyte character is converted as if by a call to .CR mbtowc() . No more than .I n elements are modified in the array pointed to by .IR pwcs . .IP If an invalid multibyte character is encountered, .C mbstowcs() returns (size_t)\|\(mi\|1. Otherwise, .C mbstowcs() returns the number of array elements modified, not including a terminating zero code, if any. The array is not null- or zero-terminated if the value returned is .IR n . If .I pwcs is a null pointer, .C mbstowcs() returns the number of elements required for the wide-character-code array. .TP .C wcstombs() Convert a sequence of codes corresponding to multibyte characters from the array pointed to by .I pwcs into a sequence of multibyte characters and store them into the array pointed to by .IR s , stopping if a multibyte character exceeds the limit of .I n total bytes or if a null character is stored. Each code is converted as if by a call to .CR wctomb() . No more than .I n bytes are modified in the array pointed to by .IR s . .IP If a code is encountered that does not correspond to a valid multibyte character, .C wcstombs() returns (size_t)\|\(mi\|1. Otherwise, .C wcstombs() returns the number of bytes modified, not including a terminating null character, if any. The array is not null- or zero-terminated if the value returned is .IR n . If .I s is a null pointer, .C wcstombs() returns the number of bytes required for the character array. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the behavior of the multibyte character and string functions. .SH ERRORS .CR mblen() , .CR mbstowcs() , .CR mbtowc() , .C wcstombs() and .C wctomb() may fail and .C errno is set if the following condition is encountered: .RS .TP 15 .SM [EILSEQ] An invalid multibyte sequence or wide character code was found. .RE .SH WARNINGS With the exception of .SM ASCII characters, the code values of wide characters (type of .CR wchar_t ) are specific to the effective locale specified by the .C LC_CTYPE environment variable. These values may not be compatible with values obtained by specifying other locales that are supported now, or which may be supported in the future. It is recommended that wide character constants and wide string literals (see the .IR "C Reference Manual" ) not be used, and that wide character code values not be stored in files or devices because future standards may dictate changes in the code value assignments of the wide characters. However, wide character constants and wide string literals corresponding to the characters of the .SM ASCII code set can be safely used since their values are guaranteed to be the same as their .SM ASCII code set values. .SH AUTHOR The multibyte functions in this entry were developed by OSF and HP. .SH SEE ALSO setlocale(3C), wctype(3X). .SH STANDARDS CONFORMANCE .CR mblen() ": AES, SVID3, XPG4, ANSI C" .PP .CR mbstowcs() ": AES, SVID3, XPG4, ANSI C" .PP .CR mbtowc() ": AES, SVID3, XPG4, ANSI C" .PP .CR wcstombs() ": AES, SVID3, XPG4, ANSI C" .PP .CR wctomb() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4multibyte()\f1 \- multibyte characters and strings conversions@@@\f3multibyte(3C)\f1 .\" .\" index@\f4mblen()\f1 \- number of bytes in the multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4mbtowc()\f1 \- number of bytes in the multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4wctomb()\f1 \- number of bytes needed to represent multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4mbstowcs()\f1 \- convert sequence of multibyte characters@@@\f3multibyte(3C)\f1 .\" index@\f4wcstombs()\f1 \- convert sequence of codes corresponding to multibyte characters@@@\f3multibyte(3C)\f1 .\" .\" .\" index@\f1multibyte characters and strings conversions@@@\f3multibyte(3C)\f1 .\" index@\f1characters and strings conversions, multibyte@@@\f3multibyte(3C)\f1 .\" index@\f1strings and characters conversions, multibyte@@@\f3multibyte(3C)\f1 .\" index@\f1conversions, multibyte characters and strings@@@\f3multibyte(3C)\f1 .\" .\" toc@\f3multibyte(3C)\f1:\0\0\f4mblen()\f1, \f4mbtowc()\f1, \f4mbstowcs()\f1, \f4wctomb()\f1,\n \f4wcstombs()\f1@@@multibyte characters and strings conversions .\" toc@\f4mblen()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4mbstowcs()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4mbtowc()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4wctomb()\f1: multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4wctombs()\f1: multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" .\" links@multibyte.3c mblen.3c .\" links@multibyte.3c mbtowc.3c .\" links@multibyte.3c mbstowcs.3c .\" links@multibyte.3c wctomb.3c .\" links@multibyte.3c wcstombs.3c .\" $Header: add_wch.3x,v 76.2 95/07/31 11:12:51 ssa Exp $ .TA a .TH add_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME add_wch, mvadd_wch, mvwadd_wch, wadd_wch \(em add a complex character and rendition to a window .SH SYNOPSIS .C "#include " .P .C "int add_wch(cchar_t *const \f2wch\fP);" .P .C "int wadd_wch(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "int mvadd_wch(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .P .C "int mvwadd_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .SH DESCRIPTION These functions add information to the current or specified window at the current or specified position, and then advance the cursor. These functions perform wrapping. These functions perform special-character processing. .RS .TP 3 .C \(bu If \f2wch\f1 refers to a spacing character, then any previous character at that location is removed, a new character specified by \f2wch\f1 is placed at that location with rendition specified by \f2wch\fP; then the cursor advances to the next spacing character on the screen. .TP .C \(bu If \f2wch\f1 refers to a non-spacing character, all previous characters at that location are preserved, the non-spacing characters of \f2wch\f1 are added to the spacing complex character, and the rendition specified by \f2wch\f1 is ignored. .RE .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Rendition of Characters Placed into a Window\f1 in curses_intro, addch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4add_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f4mvadd_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f4mvwadd_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f4wadd_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f1add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f1character and rendition to a window, add a complex@@@\f3add_wch(3X)\f1 .\" index@\f1complex character and rendition, add to a window@@@\f3add_wch(3X)\f1 .\" .\" toc@\f3add_wch(3X)\f1:\0\0\f4add_wch()\f1, \f4mvadd_wch()\f1, \f4mvwadd_wch()\f1, \n\f4wadd_ch()\f1@@@add a complex character and rendition to a window .\" toc@\f4mvadd_wch()\f1: add a complex character and rendition to a window@@@see \f3add_wch(3X)\f1 .\" toc@\f4mvwadd_wch()\f1: add a complex character and rendition to a window@@@see \f3add_wch(3X)\f1 .\" toc@\f4wadd_wch()\f1: add a complex character and rendition to a window@@@see \f3add_wch(3X)\f1 .\" .\" links@add_wch.3x mvadd_wch.3x .\" links@add_wch.3x mvwadd_wch.3x .\" links@add_wch.3x wadd_wch.3x .\" .\" fileset_database@add_wch.3x CURS-ENG-A-MAN .\" $Header: add_wchnstr.3x,v 76.2 95/07/31 11:15:08 ssa Exp $ .TA a .TH add_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME add_wchnstr, add_wchstr, mvadd_wchnstr, mvadd_wchstr, mvwadd_wchnstr, mvwadd_wchstr, wadd_wchnstr, wadd_wchstr \(em add an array of complex characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int add_wchnstr(cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int add_wchstr(cchar_t *const \f2wchstr\fP);" .P .C "int wadd_wchnstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int wadd_wchstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvadd_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int mvadd_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvwadd_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP," .br .C " int \f2n\fP);" .P .C "int mvwadd_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .SH DESCRIPTION These functions write the array of \f3cchar_t\f1 specified by \f2wchstr\f1 into the current or specified window starting at the current or specified cursor position. .P These functions do not advance the cursor. The results are unspecified if \f2wchstr\f1 contains any special characters. .P The functions end successfully on encountering a null \f3cchar_t\f1. The functions also end successfully when they fill the current line. If a character cannot completely fit at the end of the current line, those columns are filled with the background character and rendition. .P The .CR add_wchnstr() , .CR mvadd_wchnstr() , .CR mvwadd_wchnstr() and .CR wadd_wchnstr() functions end successfully after writing \f2n\f1 \f3cchar_t\fPs (or the entire array of \f3cchar_t\fPs, if \f2n\f1 is \(mi1). .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3add_wchnstr(3X)\f1:\0\0\f4add_wchstr()\f1, \f4mvadd_wchnstr()\f1, \f4mvadd_wchstr()\f1, \f4mvwadd_wchnstr()\f1,\n\f4mvwadd_wchstr\f1, \f4wadd_wchnstr\f1, \n\f4wadd_wchstr\f1@@@add an array of complex characters and renditions to a window .\" toc@\f4add_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" .\" index@\f4add_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4add_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1an array of complex characters and renditions to a window, add@@@\f3add_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, add an array of, to a window@@@\f3add_wchnstr(3X)\f1 .\" .\" links@add_wchnstr.3x add_wchstr.3x .\" links@add_wchnstr.3x mvadd_wchnstr.3x .\" links@add_wchnstr.3x mvadd_wchstr.3x .\" links@add_wchnstr.3x mvwadd_wchnstr.3x .\" links@add_wchnstr.3x mvwadd_wchstr.3x .\" links@add_wchnstr.3x wadd_wchnstr.3x .\" links@add_wchnstr.3x wadd_wchstr.3x .\" .\" fileset_database@add_wchnstr.3x CURS-ENG-A-MAN .\" $Header: add_wchnstr.3x,v 76.2 95/07/31 11:15:08 ssa Exp $ .TA a .TH add_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME add_wchnstr, add_wchstr, mvadd_wchnstr, mvadd_wchstr, mvwadd_wchnstr, mvwadd_wchstr, wadd_wchnstr, wadd_wchstr \(em add an array of complex characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int add_wchnstr(cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int add_wchstr(cchar_t *const \f2wchstr\fP);" .P .C "int wadd_wchnstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int wadd_wchstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvadd_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int mvadd_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvwadd_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP," .br .C " int \f2n\fP);" .P .C "int mvwadd_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .SH DESCRIPTION These functions write the array of \f3cchar_t\f1 specified by \f2wchstr\f1 into the current or specified window starting at the current or specified cursor position. .P These functions do not advance the cursor. The results are unspecified if \f2wchstr\f1 contains any special characters. .P The functions end successfully on encountering a null \f3cchar_t\f1. The functions also end successfully when they fill the current line. If a character cannot completely fit at the end of the current line, those columns are filled with the background character and rendition. .P The .CR add_wchnstr() , .CR mvadd_wchnstr() , .CR mvwadd_wchnstr() and .CR wadd_wchnstr() functions end successfully after writing \f2n\f1 \f3cchar_t\fPs (or the entire array of \f3cchar_t\fPs, if \f2n\f1 is \(mi1). .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3add_wchnstr(3X)\f1:\0\0\f4add_wchstr()\f1, \f4mvadd_wchnstr()\f1, \f4mvadd_wchstr()\f1, \f4mvwadd_wchnstr()\f1,\n\f4mvwadd_wchstr\f1, \f4wadd_wchnstr\f1, \n\f4wadd_wchstr\f1@@@add an array of complex characters and renditions to a window .\" toc@\f4add_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" .\" index@\f4add_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4add_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1an array of complex characters and renditions to a window, add@@@\f3add_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, add an array of, to a window@@@\f3add_wchnstr(3X)\f1 .\" .\" links@add_wchnstr.3x add_wchstr.3x .\" links@add_wchnstr.3x mvadd_wchnstr.3x .\" links@add_wchnstr.3x mvadd_wchstr.3x .\" links@add_wchnstr.3x mvwadd_wchnstr.3x .\" links@add_wchnstr.3x mvwadd_wchstr.3x .\" links@add_wchnstr.3x wadd_wchnstr.3x .\" links@add_wchnstr.3x wadd_wchstr.3x .\" .\" fileset_database@add_wchnstr.3x CURS-ENG-A-MAN .\" $Header: addch.3x,v 76.2 95/07/28 16:16:36 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addch, mvaddch, mvwaddch, waddch \(em add a single-byte character and rendition to a window and advance the cursor .SH SYNOPSIS .C "#include " .P .C "int addch(const chtype \f2ch\fP);" .P .C "int mvaddch(int \f2y\fP, int \f2x\fP, const chtype \f2ch\fP);" .P .C "int mvwaddch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, const chtype \f2ch\fP);" .P .C "int waddch(WINDOW *\f2win\fP, const chtype \f2ch\fP);" .SH DESCRIPTION The .CR addch() , .CR mvaddch() , .CR mvwaddch() and .CR waddch() functions place \f2ch\f1 into the current or specified window at the current or specified position, and then advance the window's cursor position. These functions perform wrapping. These functions perform special-character processing. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" \f3Rendition of Characters Placed into a Window\f1 in curses_intro, add_wch(), attroff(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The entry is rewritten for clarity. Also the type of argument \f2ch\f1 is changed from \f3chtype\f1 to \f3const chtype\f1. .\" .\" toc@\f3addch(3X)\f1:\0\0\f4addch()\f1, \f4mvaddch()\f1, \f4mvwaddch()\f1, \f4waddch\f1\n@@@add a single-byte character and rendition to a window and advance the cursor .\" toc@\f4mvaddch()\f1: add a single-byte character and rendition to a window and advance the cursor@@@see \f3addch(3X)\f1 .\" toc@\f4mvwaddch()\f1: add a single-byte character and rendition to a window and advance the cursor@@@see \f3addch(3X)\f1 .\" toc@\f4waddch()\f1: add a single-byte character and rendition to a window and advance the cursor@@@see \f3addch(3X)\f1 .\" .\" index@\f4addch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f4mvaddch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f4mvwaddch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f4waddch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f1add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f1single-byte character and rendition, add, to a window and advance the cursor@@@\f3addch(3X)\f1 .\" .\" links@addch.3x mvaddch.3x .\" links@addch.3x mvwaddch.3x .\" links@addch.3x waddch.3x .\" .\" fileset_database@addch.3x CURS-ENG-A-MAN .\" $Header: addchnstr.3x,v 76.2 95/07/31 11:17:15 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addchnstr, mvaddchnstr, mvwaddchnstr, waddchnstr \(em add length limited string of single-byte characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int addchnstr(chtype *const \f2chstr\fP, int \f2n\fP);" .P .C "int mvaddchnstr(int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP, int \f2n\fP);" .P .C "int mvwaddchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP," .br .C " int \f2n\fP);" .P .C "int waddchnstr(WINDOW *\f2win\fP, chtype *const \f2chstr\fP, int \f2n\fP);" .SH DESCRIPTION These functions overlay the contents of the current or specified window, starting at the current or specified position, with the contents of the array pointed to by .I chstr until a null .B chtype is encountered in the array pointed to by .I chstr . .P These functions do not change the cursor position. These functions do not perform special-character processing. These functions do not perform wrapping. .P These functions copy at most \f2n\f1 items, but no more than will fit on the line. If \f2n\f1\ is \(mi1 then the whole string is copied, to the maximum number that fit on the line. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" addch(), add_wch(), add_wchstr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addchnstr(3X)\f1:\0\0\f4mvaddchnstr()\f1, \f4mvwaddchnstr()\f1, \f4waddchnstr()\f1\n@@@add length limited string of single-byte characters and renditions to a window .\" toc@\f4mvaddchnstr()\f1: add length limited string of single-byte characters and renditions to a window\n@@@see \f3addchnstr(3X)\f1 .\" toc@\f4mvwaddchnstr()\f1: add length limited string of single-byte characters and renditions to a window\n@@@see \f3addchnstr(3X)\f1 .\" toc@\f4waddchnstr()\f1: add length limited string of single-byte characters and renditions to a window\n@@@see \f3addchnstr(3X)\f1 .\" .\" index@\f4addchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window@@@\f3addchnstr(3X)\f1 .\" index@\f4mvaddchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window\n@@@\f3addchnstr(3X)\f1 .\" index@\f4mvwaddchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window\n@@@\f3addchnstr(3X)\f1 .\" index@\f4waddchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window@@@\f3addchnstr(3X)\f1 .\" index@\f1add length limited string of single-byte characters and renditions to a window@@@\f3addchnstr(3X)\f1 .\" index@\f1length limited string of single-byte characters and renditions to a window, add@@@\f3addchnstr(3X)\f1 .\" index@\f1single-byte characters and renditions to a window, add length limited string of@@@\f3addchnstr(3X)\f1 .\" .\" links@addchnstr.3x mvaddchnstr.3x .\" links@addchnstr.3x mvwaddchnstr.3x .\" links@addchnstr.3x waddchnstr.3x .\" .\" fileset_database@addchnstr.3x CURS-ENG-A-MAN .\" $Header: addchstr.3x,v 76.2 95/07/31 11:19:11 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addchstr 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addchstr, mvaddchstr, mvwaddchstr, waddchstr \(em add string of single-byte characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int addchstr(chtype *const \f2chstr\fP);" .P .C "int mvaddchstr(int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP);" .P .C "int mvwaddchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP);" .P .C "int waddchstr(WINDOW *\f2win\fP, chtype *const \f2chstr\fP);" .SH DESCRIPTION These functions overlay the contents of the current or specified window, starting at the current or specified position, with the contents of the array pointed to by .I chstr until a null .CR chtype is encountered in the array pointed to by .IR chstr . .P These functions do not change the cursor position. These functions do not perform special-character processing. These functions do not perform wrapping. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" addch(), addchnstr(), add_wch(), add_wchstr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addchstr(3X)\f1:\0\0\f4mvaddchstr()\f1, \f4mvwaddchstr()\f1, \f4waddchstr()\f1\n@@@add string of single-byte characters and renditions to a window .\" toc@\f4mvaddchstr()\f1: add string of single-byte characters and renditions to a window@@@see \f3addchstr(3X)\f1 .\" toc@\f4mvwaddchstr()\f1: add string of single-byte characters and renditions to a window@@@see \f3addchstr(3X)\f1 .\" toc@\f4waddchstr()\f1: add string of single-byte characters and renditions to a window@@@see \f3addchstr(3X)\f1 .\" .\" index@\f4addchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f4mvaddchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f4mvwaddchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f4waddchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f1add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f1string of single-byte characters and renditions to a window, add@@@\f3addchstr(3X)\f1 .\" index@\f1single-byte characters and renditions to a window, add string of@@@\f3addchstr(3X)\f1 .\" .\" links@addchstr.3x mvaddchstr.3x .\" links@addchstr.3x mvwaddchstr.3x .\" links@addchstr.3x waddchstr.3x .\" .\" fileset_database@addchstr.3x CURS-ENG-A-MAN .\" $Header: addnstr.3x,v 76.2 95/07/31 11:20:19 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnstr, addstr, mvaddnstr, mvaddstr, mvwaddnstr, mvwaddstr waddnstr, waddstr \(em add a string of multi-byte characters without rendition to a window and advance cursor .SH SYNOPSIS .C "#include " .P .C "int addnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int addstr(char *const \f2str\fP);" .P .C "int mvaddnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvaddstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwaddnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwaddstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int waddnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int waddstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions write the characters of the string \f2str\f1 on the current or specified window starting at the current or specified position using the background rendition. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions are similar to calling .CR mbstowcs() on \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .P The .CR addnstr() , .CR mvaddnstr() , .CR mvwaddnstr() and .CR waddnstr() functions use at most \f2n\f1 bytes from \f2str\f1. These functions add the entire string when \f2n\f1 is \(mi1. These functions are similar to calling .CR mbstowcs() on the first \f2n\f1 bytes of \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" addnwstr(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .P In X/Open Curses, Issue 3, the .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions were described in the .CR addstr() entry. In X/Open Curses, Issue 4, the type of the \f2str\f1 argument defined for these functions is changed from \f3char\ *\f1 to \f3char\ *const\fP, and the .BR DESCRIPTION is changed to indicate that the functions will handle multi-byte sequences correctly. .\" toc@\f3addnstr(3X)\f1:\0\0\f4addstr()\f1, \f4mvaddnstr()\f1, \f4mvaddstr()\f1, \f4mvwaddnstr()\f1, \f4mvwaddstr()\f1, \f4waddnstr()\f1, \n\f4waddstr()\f1@@@add a string of multi-byte characters without rendition to a window and advance cursor .\" toc@\f4addstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" .\" index@\f4addnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4addstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1add a string of multi-byte characters without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1multi-byte characters, add a string of, without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" .\" links@addnstr.3x addstr.3x .\" links@addnstr.3x mvaddnstr.3x .\" links@addnstr.3x mvaddstr.3x .\" links@addnstr.3x mvwaddstr.3x .\" links@addnstr.3x mvwaddnstr.3x .\" links@addnstr.3x waddstr.3x .\" links@addnstr.3x waddnstr.3x .\" .\" fileset_database@addnstr.3x CURS-ENG-A-MAN .\" $Header: addnwstr.3x,v 76.2 95/07/28 16:19:15 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnwstr, addwstr, mvaddnwstr, mvaddwstr, mvwaddnwstr, mvwaddwstr, waddnwstr, waddwstr \(em add a wide-character string to a window and advance the cursor .SH SYNOPSIS .C "#include " .P .C "int addnwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int addwstr(wchar_t *const \f2wstr\fP);" .P .C "int mvaddnwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvaddwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwaddnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwaddwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int waddnwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int waddwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions write the characters of the wide character string \f2wstr\f1 on the current or specified window at that window's current or specified cursor position. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The effect is similar to building a \f3cchar_t\f1 from the \f3wchar_t\f1 and the background rendition and calling .CR wadd_wch() once for each \f3wchar_t\f1 character in the string. The cursor movement specified by the .I mv functions occurs only once at the start of the operation. .P The .CR addnwstr() , .CR mvaddnwstr() , .CR mvwaddnwstr() and .CR waddnwstr() functions write at most \f2n\f1 wide characters. If \f2n\f1 is \(mi1, then the entire string will be added. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" add_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addnwstr(3X)\f1:\0\0\f4addnwstr()\f1, \f4addwstr()\f1, \f4mvaddnwstr()\f1, \f4mvaddwstr()\f1, \f4mvwaddnwstr()\f1, \f4mvwaddwstr()\f1, \n\f4waddnwstr()\f1, \f4waddwstr()\f1@@@add a wide-character string to a window and advance the cursor .\" toc@\f4addwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" .\" index@\f4addnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4addwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f1add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" .\" links@addnwstr.3x addwstr.3x .\" links@addnwstr.3x mvaddnwstr.3x .\" links@addnwstr.3x mvaddwstr.3x .\" links@addnwstr.3x mvwaddnwstr.3x .\" links@addnwstr.3x mvwaddwstr.3x .\" links@addnwstr.3x waddnwstr.3x .\" links@addnwstr.3x waddwstr.3x .\" .\" fileset_database@addnwstr.3x CURS-ENG-A-MAN .\" $Header: addnstr.3x,v 76.2 95/07/31 11:20:19 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnstr, addstr, mvaddnstr, mvaddstr, mvwaddnstr, mvwaddstr waddnstr, waddstr \(em add a string of multi-byte characters without rendition to a window and advance cursor .SH SYNOPSIS .C "#include " .P .C "int addnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int addstr(char *const \f2str\fP);" .P .C "int mvaddnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvaddstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwaddnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwaddstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int waddnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int waddstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions write the characters of the string \f2str\f1 on the current or specified window starting at the current or specified position using the background rendition. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions are similar to calling .CR mbstowcs() on \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .P The .CR addnstr() , .CR mvaddnstr() , .CR mvwaddnstr() and .CR waddnstr() functions use at most \f2n\f1 bytes from \f2str\f1. These functions add the entire string when \f2n\f1 is \(mi1. These functions are similar to calling .CR mbstowcs() on the first \f2n\f1 bytes of \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" addnwstr(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .P In X/Open Curses, Issue 3, the .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions were described in the .CR addstr() entry. In X/Open Curses, Issue 4, the type of the \f2str\f1 argument defined for these functions is changed from \f3char\ *\f1 to \f3char\ *const\fP, and the .BR DESCRIPTION is changed to indicate that the functions will handle multi-byte sequences correctly. .\" toc@\f3addnstr(3X)\f1:\0\0\f4addstr()\f1, \f4mvaddnstr()\f1, \f4mvaddstr()\f1, \f4mvwaddnstr()\f1, \f4mvwaddstr()\f1, \f4waddnstr()\f1, \n\f4waddstr()\f1@@@add a string of multi-byte characters without rendition to a window and advance cursor .\" toc@\f4addstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" .\" index@\f4addnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4addstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1add a string of multi-byte characters without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1multi-byte characters, add a string of, without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" .\" links@addnstr.3x addstr.3x .\" links@addnstr.3x mvaddnstr.3x .\" links@addnstr.3x mvaddstr.3x .\" links@addnstr.3x mvwaddstr.3x .\" links@addnstr.3x mvwaddnstr.3x .\" links@addnstr.3x waddstr.3x .\" links@addnstr.3x waddnstr.3x .\" .\" fileset_database@addnstr.3x CURS-ENG-A-MAN .\" $Header: addnwstr.3x,v 76.2 95/07/28 16:19:15 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnwstr, addwstr, mvaddnwstr, mvaddwstr, mvwaddnwstr, mvwaddwstr, waddnwstr, waddwstr \(em add a wide-character string to a window and advance the cursor .SH SYNOPSIS .C "#include " .P .C "int addnwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int addwstr(wchar_t *const \f2wstr\fP);" .P .C "int mvaddnwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvaddwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwaddnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwaddwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int waddnwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int waddwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions write the characters of the wide character string \f2wstr\f1 on the current or specified window at that window's current or specified cursor position. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The effect is similar to building a \f3cchar_t\f1 from the \f3wchar_t\f1 and the background rendition and calling .CR wadd_wch() once for each \f3wchar_t\f1 character in the string. The cursor movement specified by the .I mv functions occurs only once at the start of the operation. .P The .CR addnwstr() , .CR mvaddnwstr() , .CR mvwaddnwstr() and .CR waddnwstr() functions write at most \f2n\f1 wide characters. If \f2n\f1 is \(mi1, then the entire string will be added. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" add_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addnwstr(3X)\f1:\0\0\f4addnwstr()\f1, \f4addwstr()\f1, \f4mvaddnwstr()\f1, \f4mvaddwstr()\f1, \f4mvwaddnwstr()\f1, \f4mvwaddwstr()\f1, \n\f4waddnwstr()\f1, \f4waddwstr()\f1@@@add a wide-character string to a window and advance the cursor .\" toc@\f4addwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" .\" index@\f4addnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4addwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f1add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" .\" links@addnwstr.3x addwstr.3x .\" links@addnwstr.3x mvaddnwstr.3x .\" links@addnwstr.3x mvaddwstr.3x .\" links@addnwstr.3x mvwaddnwstr.3x .\" links@addnwstr.3x mvwaddwstr.3x .\" links@addnwstr.3x waddnwstr.3x .\" links@addnwstr.3x waddwstr.3x .\" .\" fileset_database@addnwstr.3x CURS-ENG-A-MAN .\" $Header: chgat.3x,v 76.2 95/07/31 17:23:18 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH chgat 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chgat, mvchgat, mvwchgat, wchgat \(em change renditions of characters in a window .SH SYNOPSIS .C "#include " .P .C "int chgat(int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP, void *const \f2opts\fP);" .P .C "int mvchgat(int \f2y\fP, int \f2x\fP, int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP," .br .C " void *const \f2opts\fP);" .P .C "int mvwchgat(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, int \f2n\fP, attr_t \f2attr\fP," .br .C " short \f2color\fP, void *const \f2opts\fP);" .P .C "int wchgat(WINDOW *\f2win\fP, int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP," .br .C " void *const \f2opts\fP);" .SH DESCRIPTION These functions change the renditions of the next \f2n\f1 characters in the current or specified window (or of the remaining characters on the line, if \f2n\f1 is \(mi1), starting at the current or specified cursor position. The attributes and colors are specified by \f2attr\f1 and \f2color\f1 as for .CR setcchar() . .P These functions do not update the cursor. These functions do not perform wrapping. .P A value of \f2n\f1 that is greater than the remaining characters on a line is not an error. .P The \f2opts\f1 argument is reserved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" setcchar(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3chgat(3X)\f1:\0\0\f4chgat()\f1, \f4mvchgat()\f1, \f4mvwchgat()\f1, \f4wchgat()\f1@@@change renditions of characters in a window .\" toc@\f4mvchgat()\f1: change renditions of characters in a window@@@see \f3chgat(3X)\f1 .\" toc@\f4mvwchgat()\f1: change renditions of characters in a window@@@see \f3chgat(3X)\f1 .\" toc@\f4wchgat()\f1: change renditions of characters in a window@@@see \f3chgat(3X)\f1 .\" .\" index@\f4chgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f4mvchgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f4mvwchgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f4wchgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f1change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f1renditions of characters in a window, change@@@\f3chgat(3X)\f1 .\" index@\f1window, change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f1characters, renditions of, change in a window@@@\f3chgat(3X)\f1 .\" .\" links@chgat.3x mvchgat.3x .\" links@chgat.3x mvwchgat.3x .\" links@chgat.3x wchgat.3x .\" .\" fileset_database@chgat.3x CURS-ENG-A-MAN .\" $Header: mvcur.3x,v 76.2 95/08/01 11:55:13 ssa Exp $ .TA m .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH mvcur 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mvcur \(em output cursor movement commands to the terminal .SH SYNOPSIS .C "#include " .P .C "int mvcur(int \f2oldrow\fP, int \f2oldcol\fP, int \f2newrow\fP, int \f2newcol\fP);" .SH DESCRIPTION The .Fn mvcur function outputs one or more commands to the terminal that move the terminal's cursor to (\f2newrow\fP, \f2newcol\fP), an absolute position on the terminal screen. The (\f2oldrow\fP, \f2oldcol\fP) arguments specify the former cursor position. Specifying the former position is necessary on terminals that do not provide coordinate-based movement commands. On terminals that provide these commands, Curses may select a more efficient way to move the cursor based on the former position. If (\f2newrow\fP, \f2newcol\fP) is not a valid address for the terminal in use, .Fn mvcur fails. If (\f2oldrow\fP, \f2oldcol\fP) is the same as (\f2newrow\fP, \f2newcol\fP), then .Fn mvcur succeeds without taking any action. If .Fn mvcur outputs a cursor movement command, it updates its information concerning the location of the cursor on the terminal. .SH "RETURN VALUE" Upon successful completion, .Fn mvcur returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" After use of .Fn mvcur , the model Curses maintains of the state of the terminal might not match the actual state of the terminal. The application should touch and refresh the window before resuming conventional use of Curses. .SH "SEE ALSO" doupdate(), is_linetouched(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4mvcur()\f1 \- output cursor movement commands to the terminal@@@\f3mvcur(3X)\f1 .\" index@\f1output cursor movement commands to the terminal@@@\f3mvcur(3X)\f1 .\" index@\f1cursor, output movement commands to the terminal@@@\f3mvcur(3X)\f1 .\" index@\f1movement commands cursor, output to the terminal@@@\f3mvcur(3X)\f1 .\" index@\f1terminal, output cursor movement commands to@@@\f3mvcur(3X)\f1 .\" .\" toc@\f3mvcur(3X)\f1:\0\0\f4mvcur()\f1@@@output cursor movement commands to the terminal .\" .\" fileset_database@mvcur.3x CURS-ENG-A-MAN .\" $Header: delch.3x,v 76.2 95/08/01 15:04:04 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH delch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME delch, mvdelch, mvwdelch, wdelch \(em delete a character from a window. .SH SYNOPSIS .C "#include " .P .C "int delch(void);" .P .C "int mvdelch(int \f2y\fP, int \f2x\fP);" .P .C "int mvwdelch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "int wdelch(WINDOW *\f2win\fP);" .SH DESCRIPTION These functions delete the character at the current or specified position in the current or specified window. This function does not change the cursor position. .SS "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SS ERRORS No errors are defined. .SS "SEE ALSO" . .SS "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn delch function is explicitly declared as \f3void\f1. .\" .\" toc@\f3delch(3x)\f1:\0\0\f4delch()\f1, \f4mvdelch()\f1, \f4mvwdelch()\f1, \f4wdelch()\f1@@@delete character from a window .\" .\" toc@\f3mvdelch()\f1:\0\0delete character from a window@@@\f1see\f3delch(3x)\f1 .\" toc@\f3mvwdelch()\f1:\0\0delete character from a window@@@\f1see\f3delch(3x)\f1 .\" toc@\f3wdelch()\f1:\0\0delete character from a window@@@\f1see\f3delch(3x)\f1 .\" .\" index@\f4delch()\f1, \f4mvdelch()\f1, \f4mvwdelch()\f1, \f4wdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" index@\f4mvdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" index@\f4mvwdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" index@\f4wdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" .\" links@delch.3x mvdelch.3x .\" links@delch.3x mvwdelch.3x .\" links@delch.3x wdelch.3x .\" .\" fileset_database@delch.3x CURS-ENG-A-MAN .\" .\" $Header: mvderwin.3x,v 76.2 95/08/01 11:55:55 ssa Exp $ .TA m .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH mvderwin 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mvderwin \(em define window coordinate transformation .SH SYNOPSIS .C "#include " .P .C "int mvderwin(WINDOW *\f2win\fP, int \f2par_y\fP, int \f2par_x\fP);" .SH DESCRIPTION The .Fn mvderwin function specifies a mapping of characters. The function identifies a mapped area of the parent of the specified window, whose size is the same as the size of the specified window and whose origin is at (\f2par_y\fP, \f2par_x\fP) of the parent window. .RS .TP 3 .C \(bu During any refresh of the specified window, the characters displayed in that window's display area of the terminal are taken from the mapped area. .TP .C \(bu Any references to characters in the specified window obtain or modify characters in the mapped area. .RE .P That is, .Fn mvderwin defines a coordinate transformation from each position in the mapped area to a corresponding position (same \f2y\fP, \f2x\f1 offset from the origin) in the specified window. .SH "RETURN VALUE" Upon successful completion, .Fn mvderwin returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" derwin(), doupdate(), dupwin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4mvderwin()\f1 \- define window coordinate transformation@@@\f3mvderwin(3X)\f1 .\" index@\f1define window coordinate transformation@@@\f3mvderwin(3X)\f1 .\" index@\f1window coordinate transformation, define@@@\f3mvderwin(3X)\f1 .\" index@\f1coordinate, window, transformation, define@@@\f3mvderwin(3X)\f1 .\" .\" toc@\f3mvderwin(3X)\f1:\0\0\f4mvderwin()\f1@@@define window coordinate transformation .\" .\" fileset_database@mvderwin.3x CURS-ENG-A-MAN .\" $Header: get_wch.3x,v 76.2 95/08/01 10:38:24 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH get_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME get_wch, mvget_wch, mvwget_wch, wget_wch \(em get a wide character from a terminal .SH SYNOPSIS .C "#include " .P .C "int get_wch(wint_t *\f2ch\fP);" .P .C "int mvget_wch(int \f2y\fP, int \f2x\fP, wint_t *\f2ch\fP);" .P .C "int mvwget_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2ch\fP);" .P .C "int wget_wch(WINDOW *\f2win\fP, wint_t *\f2ch\fP);" .SH DESCRIPTION These functions read a character from the terminal associated with the current or specified window. If .Fn keypad is enabled, these functions respond to the pressing of a function key by setting the object pointed to by .I ch to the corresponding KEY_ value defined in .Hd curses.h and returning KEY_CODE_YES. .P Processing of terminal input is subject to the general rules described in \f3Input Processing\f1 in curses_intro. .P If echoing is enabled, then the character is echoed as though it were provided as an input argument to .CR ins_wch() , except for the following characters: .PP .TS tab(@); lw(2.00i)@lw(3i). T{ , and the current erase character: T}@T{ The input is interpreted as specified in .CR specialchars and then the character at the resulting cursor position is deleted as though .Fn delch were called, except that if the cursor was originally in the first column of the line, then the user is alerted as though .Fn beep were called. T} .P Function keys@T{ The user is alerted as though .Fn beep were called. Information concerning the function keys is not returned to the caller. T} .TE .P If the current or specified window is not a pad, and it has been moved or modified since the last refresh operation, then it will be refreshed before another character is read. .SH "RETURN VALUE" When these functions successfully report the pressing of a function key, they return KEY_CODE_YES. When they successfully report a wide character, they return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Applications should not define the escape key by itself as a single-character function. .P When using these functions, .Fn nocbreak mode and .Fn echo mode should not be used at the same time. Depending on the state of the terminal when each character is typed, the application may produce undesirable results. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, beep(), cbreak(), ins_wch(), keypad(), move(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3get_wch(3X)\f1:\0\0\f4get_wch()\f1, \f4mvget_wch()\f1, \f4mvwget_wch()\f1, \f4wget_wch\f1()\f1@@@get a wide character from a terminal .\" toc@\f4mvget_wch()\f1: get a wide character from a terminal@@@see \f3get_wch(3X)\f1 .\" toc@\f4mvwget_wch()\f1: get a wide character from a terminal@@@see \f3get_wch(3X)\f1 .\" toc@\f4wget_wch()\f1: get a wide character from a terminal@@@see \f3get_wch(3X)\f1 .\" .\" index@\f4get_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f4mvget_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f4mvwget_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f4wget_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f1get a wide character from a terminal@@@\f3get_wch(3X)\f1 .\" index@\f1wide character, get from a terminal@@@\f3get_wch(3X)\f1 .\" index@\f1terminal, get a wide character from@@@\f3get_wch(3X)\f1 .\" index@\f1character, get a wide character from a terminal@@@\f3get_wch(3X)\f1 .\" .\" links@get_wch.3x mvget_wch.3x .\" links@get_wch.3x mvwget_wch.3x .\" links@get_wch.3x wget_wch.3x .\" .\" fileset_database@get_wch.3x CURS-ENG-A-MAN .\" $Header: getn_wstr.3x,v 76.2 95/08/01 10:52:41 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getn_wstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getn_wstr, get_wstr, mvgetn_wstr, mvget_wstr, mvwgetn_wstr, mvwget_wstr, wgetn_wstr, wget_wstr \(em get an array of wide characters and function key codes from a terminal .SH SYNOPSIS .C "#include " .P .C "int getn_wstr(wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int get_wstr(wint_t *\f2wstr\fP);" .P .C "int mvgetn_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvget_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int mvwgetn_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwget_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int wgetn_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int wget_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP);" .SH DESCRIPTION The effect of .Fn get_wstr is as though a series of calls to .Fn get_wch were made, until a newline character, end-of-line character, or end-of-file character is processed. An end-of-file character is represented by WEOF, as defined in .CR . A newline or end-of-line is represented as its .CR wchar_t value. In all instances, the end of the string is terminated by a null .CR wchar_t . The resulting values are placed in the area pointed to by \f2wstr\f1. .P The user's erase and kill characters are interpreted and affect the sequence of characters returned. .P The effect of .Fn wget_wstr is as though a series of calls to .Fn wget_wch were made. .P The effect of .Fn mvget_wstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_wstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. The effect of .Fn mvget_nwstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_nwstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. .P The .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr and .Fn wgetn_wstr functions read at most \f2n\f1 characters, letting the application prevent overflow of the input buffer. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR get_wstr() , .CR mvget_wstr() , .Fn mvwget_wstr or .Fn wget_wstr causes undefined results. The use of .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr or .Fn wgetn_wstr , respectively, is recommended. .P These functions cannot return KEY_ values as there is no way to distinguish a KEY_ value from a valid .B wchar_t value. .SH "SEE ALSO" get_wch(), getstr(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Chapter 9,\f3General Terminal Interface\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getn_wstr(3X)\f1:\0\0\f4getn_wstr()\f1, \f4get_wstr()\f1, \f4mvgetn_wstr()\f1, \f4mvget_wstr()\f1, \f4mvwgetn_wstr()\f1, \n\f4mvwget_wstr()\f1, \f4wgetn_wstr()\f1, \f4wget_wstr()\f1\n@@@get an array of wide characters and function key codes from a terminal .\" toc@\f4get_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" .\" index@\f4getn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4get_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1array of wide characters and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1wide characters, an array of, and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1terminal, get an array of wide characters and function key codes@@@\f3getn_wstr(3X)\f1 .\" .\" links@getn_wstr.3x get_wstr.3x .\" links@getn_wstr.3x mvgetn_wstr.3x .\" links@getn_wstr.3x mvget_wstr.3x .\" links@getn_wstr.3x mvwgetn_wstr.3x .\" links@getn_wstr.3x mvwget_wstr.3x .\" links@getn_wstr.3x wgetn_wstr.3x .\" links@getn_wstr.3x wget_wstr.3x .\" .\" fileset_database@getn_wstr.3x CURS-ENG-A-MAN .\" $Header: getch.3x,v 76.2 95/08/01 10:51:16 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getch, wgetch, mvgetch, mvwgetch \(em get a single-byte character from the terminal .SH SYNOPSIS .C "#include " .P .C "int getch(void);" .P .C "int mvgetch(int \f2y\fP, int \f2x\fP);" .P .C "int mvwgetch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "int wgetch(WINDOW *\f2win\fP);" .SH DESCRIPTION These functions read a single-byte character from the terminal associated with the current or specified window. The results are unspecified if the input is not a single-byte character. If .Fn keypad is enabled, these functions respond to the pressing of a function key by returning the corresponding KEY_ value defined in .CR . .P Processing of terminal input is subject to the general rules described in \f3Input Processing\f1 in curses_intro. .P If echoing is enabled, then the character is echoed as though it were provided as an input argument to .CR insch() , except for the following characters: .PP .TS tab(`); lw(2.00i) lw(3i). T{ , and the current erase character: T}`T{ The input is interpreted as specified in .CR specialchars and then the character at the resulting cursor position is deleted as though .Fn delch were called, except that if the cursor was originally in the first column of the line, then the user is alerted as though .Fn beep were called. T} .P Function keys`T{ The user is alerted as though .Fn beep were called. Information concerning the function keys is not returned to the caller. T} .TE .P If the current or specified window is not a pad, and it has been moved or modified since the last refresh operation, then it will be refreshed before another character is read. .SH "RETURN VALUE" Upon successful completion, these functions return the single-byte character, KEY_ value, or ERR. .P If in nodelay mode and no data is available, ERR is returned. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Applications should not define the escape key by itself as a single-character function. .P When using these functions, nocbreak mode (\c .CR nocbreak() ) and echo mode (\c .CR echo() ) should not be used at the same time. Depending on the state of the terminal when each character is typed, the program may produce undesirable results. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, cbreak(), doupdate(), insch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn getch function is explicitly declared as \f3void\f1. .\" .\" toc@\f3getch(3X)\f1:\0\0\f4getch()\f1, \f4wgetch()\f1, \f4mvgetch()\f1, \f4mvwgetch()\f1@@@get a single-byte character from the terminal .\" toc@\f4wgetch()\f1: get a single-byte character from the terminal@@@see \f3getch(3X)\f1 .\" toc@\f4mvwgetch()\f1: get a single-byte character from the terminal@@@see \f3getch(3X)\f1 .\" toc@\f4mvgetch()\f1: get a single-byte character from the terminal@@@see \f3getch(3X)\f1 .\" .\" index@\f4getch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f4wgetch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f4mvgetch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f4mvwgetch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f1get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f1single-byte character, get from the terminal@@@\f3getch(3X)\f1 .\" index@\f1terminal, get a single-byte character@@@\f3getch(3X)\f1 .\" index@\f1character, single-byte, get from the terminal@@@\f3getch(3X)\f1 .\" .\" links@getch.3x wgetch.3x .\" links@getch.3x mvwgetch.3x .\" links@getch.3x mvgetch.3x .\" .\" fileset_database@getch.3x CURS-ENG-A-MAN .\" $Header: getn_wstr.3x,v 76.2 95/08/01 10:52:41 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getn_wstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getn_wstr, get_wstr, mvgetn_wstr, mvget_wstr, mvwgetn_wstr, mvwget_wstr, wgetn_wstr, wget_wstr \(em get an array of wide characters and function key codes from a terminal .SH SYNOPSIS .C "#include " .P .C "int getn_wstr(wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int get_wstr(wint_t *\f2wstr\fP);" .P .C "int mvgetn_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvget_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int mvwgetn_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwget_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int wgetn_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int wget_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP);" .SH DESCRIPTION The effect of .Fn get_wstr is as though a series of calls to .Fn get_wch were made, until a newline character, end-of-line character, or end-of-file character is processed. An end-of-file character is represented by WEOF, as defined in .CR . A newline or end-of-line is represented as its .CR wchar_t value. In all instances, the end of the string is terminated by a null .CR wchar_t . The resulting values are placed in the area pointed to by \f2wstr\f1. .P The user's erase and kill characters are interpreted and affect the sequence of characters returned. .P The effect of .Fn wget_wstr is as though a series of calls to .Fn wget_wch were made. .P The effect of .Fn mvget_wstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_wstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. The effect of .Fn mvget_nwstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_nwstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. .P The .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr and .Fn wgetn_wstr functions read at most \f2n\f1 characters, letting the application prevent overflow of the input buffer. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR get_wstr() , .CR mvget_wstr() , .Fn mvwget_wstr or .Fn wget_wstr causes undefined results. The use of .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr or .Fn wgetn_wstr , respectively, is recommended. .P These functions cannot return KEY_ values as there is no way to distinguish a KEY_ value from a valid .B wchar_t value. .SH "SEE ALSO" get_wch(), getstr(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Chapter 9,\f3General Terminal Interface\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getn_wstr(3X)\f1:\0\0\f4getn_wstr()\f1, \f4get_wstr()\f1, \f4mvgetn_wstr()\f1, \f4mvget_wstr()\f1, \f4mvwgetn_wstr()\f1, \n\f4mvwget_wstr()\f1, \f4wgetn_wstr()\f1, \f4wget_wstr()\f1\n@@@get an array of wide characters and function key codes from a terminal .\" toc@\f4get_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" .\" index@\f4getn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4get_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1array of wide characters and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1wide characters, an array of, and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1terminal, get an array of wide characters and function key codes@@@\f3getn_wstr(3X)\f1 .\" .\" links@getn_wstr.3x get_wstr.3x .\" links@getn_wstr.3x mvgetn_wstr.3x .\" links@getn_wstr.3x mvget_wstr.3x .\" links@getn_wstr.3x mvwgetn_wstr.3x .\" links@getn_wstr.3x mvwget_wstr.3x .\" links@getn_wstr.3x wgetn_wstr.3x .\" links@getn_wstr.3x wget_wstr.3x .\" .\" fileset_database@getn_wstr.3x CURS-ENG-A-MAN .\" $Header: getnstr.3x,v 76.2 95/08/01 10:57:27 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnstr, mvgetnstr, mvwgetnstr, wgetnstr, \(em get a multi-byte character length limited string from the terminal .SH SYNOPSIS .C "#include " .P .C "int getnstr(char *\f2str\fP, int \f2n\fP);" .P .C "int mvgetnstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvwgetnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int wgetnstr(WINDOW *\f2win\fP, char *\f2str\fP, int \f2n\fP);" .SH DESCRIPTION The effect of .Fn getnstr and .Fn wgetnstr is as though a series of calls to .Fn getch were made, until a newline or carriage return is received. The resulting value is placed in the area pointed to by \f2str\f1. The .Fn getnstr and .Fn wgetnstr functions read at most \f2n\f1 bytes, thus preventing a possible overflow of the input buffer. The user's erase and kill characters are interpreted, as well as any special keys (such as function keys, home key, clear key, and so on). .P The .Fn mvgetnstr function is identical to .Fn getnstr except that it is as though it is a call to .Fn move and then a series of calls to .CR getch() . The .Fn mvwgetnstr function is identical to .Fn getnstr except it is as though a call to .Fn wmove is made and then a series of calls to .CR wgetch() . .P The .CR getnstr() , .CR wgetnstr() , .Fn mvgetnstr and .Fn mvwgetnstr functions will only return the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character, the functions fill the array with complete characters. If the array is not large enough to contain any complete characters, the function fails. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" .P Traditional implementations often limited the number of bytes returned to 256. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, beep(), getch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getnstr(3X)\f1:\0\0\f4getnstr()\f1, \f4mvgetnstr()\f1, \f4mvwgetnstr()\f1, \f4wgetnstr()\f1\n@@@get a multi-byte character length limited string from the terminal .\" toc@\f4mvgetnstr()\f1: get a multi-byte character length limited string from the terminal@@@see \f3getnstr(3X)\f1 .\" toc@\f4mvwgetnstr()\f1: get a multi-byte character length limited string from the terminal@@@see \f3getnstr(3X)\f1 .\" toc@\f4wgetnstr()\f1: get a multi-byte character length limited string from the terminal@@@see \f3getnstr(3X)\f1 .\" .\" index@\f4getnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f4mvgetnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f4mvwgetnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f4wgetnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1multi-byte character length limited string, get from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1terminal, get a multi-byte character length limited string from@@@\f3getnstr(3X)\f1 .\" index@\f1character, get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1string, get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" .\" links@getnstr.3x mvgetnstr.3x .\" links@getnstr.3x mvwgetnstr.3x .\" links@getnstr.3x wgetnstr.3x .\" .\" fileset_database@getnstr.3x CURS-ENG-A-MAN .\" $Header: getstr.3x,v 76.2 95/08/01 10:58:50 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getstr 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getstr, mvgetstr, mvwgetstr, wgetstr \(em get a multi-byte character string from the terminal .SH SYNOPSIS .C "#include " .P .C "int getstr(char *\f2str\fP);" .P .C "int mvgetstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int mvwgetstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int wgetstr(WINDOW *\f2win\fP, char *\f2str\fP);" .SH DESCRIPTION The effect of .Fn getstr is as though a series of calls to .Fn getch were made, until a newline or carriage return is received. The resulting value is placed in the area pointed to by \f2str\f1. The user's erase and kill characters are interpreted, as well as any special keys (such as function keys, home key, clear key, and so on). .P The .Fn mvgetstr function is identical to .Fn getstr except that it is as though it is a call to .Fn move and then a series of calls to .CR getch() . The .Fn mvwgetstr function is identical to .Fn getstr except it is as though a call to .Fn wmove is made and then a series of calls to .CR wgetch() . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2str\f1 with .CR getstr() , .CR mvgetstr() , .Fn mvwgetstr or .Fn wgetstr causes undefined results. .P Traditional implementations often limited the number of bytes returned to 256. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, beep(), getch(), getnstr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .br .ne 5 .SH Issue 3 .P In X/Open Curses, Issue 3, the .CR getstr() , .CR mvgetstr() , .Fn mvwgetstr and .Fn wgetstr functions were described in the .Fn addstr entry. In X/Open Curses, Issue 4, the .B DESCRIPTION of these functions is rewritten for clarity and is updated to indicate that they will handle multi-byte sequences correctly. .\" .\" toc@\f3getstr(3X)\f1:\0\0\f4getstr()\f1, \f4mvgetstr()\f1, \f4mvwgetstr()\f1, \f4wgetstr()\f1\n@@@get a multi-byte character string from the terminal .\" toc@\f4mvgetstr()\f1: get a multi-byte character string from the terminal@@@see \f3getstr(3X)\f1 .\" toc@\f4mvwgetstr()\f1: get a multi-byte character string from the terminal@@@see \f3getstr(3X)\f1 .\" toc@\f4wgetstr()\f1: get a multi-byte character string from the terminal@@@see \f3getstr(3X)\f1 .\" .\" index@\f4getstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f4mvgetstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f4mvwgetstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f4wgetstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1multi-byte character string, get from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1terminal, get a multi-byte character string@@@\f3getstr(3X)\f1 .\" index@\f1character, get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1string, get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" .\" links@getstr.3x mvgetstr.3x .\" links@getstr.3x mvwgetstr.3x .\" links@getstr.3x wgetstr.3x .\" .\" fileset_database@getstr.3x CURS-ENG-A-MAN .\" $Header: hline.3x,v 76.2 95/08/01 11:07:23 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline, mvhline, mvvline, mvwhline, mvwvline, vline, whline, wvline \(em draw lines from single-byte characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvhline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvvline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwhline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwvline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int vline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int whline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int wvline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline() , .CR mvhline() , .Fn mvwhline and .Fn whline functions draw a line proceeding toward the last column of the same line. .P The .CR vline() , .CR mvvline() , .Fn mvwvline and .Fn wvline functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" border(), box(), hline_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline(3X)\f1:\0\0\f4hline()\f1, \f4mvhline()\f1, \f4mvvline()\f1, \f4mvwhline()\f1, \f4mvwvline()\f1, \f4vline()\f1, \f4whline()\f1, \f4wvline()\f1\n@@@draw lines from single-byte characters and renditions .\" toc@\f4mvhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4vline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4whline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4wvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" .\" index@\f4hline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4vline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4whline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4wvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1lines, draw from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1single-byte characters and renditions, draw lines from@@@\f3hline(3X)\f1 .\" index@\f1characters and renditions, draw lines from single-byte@@@\f3hline(3X)\f1 .\" index@\f1renditions and characters, draw lines from single-byte@@@\f3hline(3X)\f1 .\" .\" links@hline.3x mvhline.3x .\" links@hline.3x mvvline.3x .\" links@hline.3x mvwhline.3x .\" links@hline.3x mvwvline.3x .\" links@hline.3x vline.3x .\" links@hline.3x whline.3x .\" links@hline.3x wvline.3x .\" .\" fileset_database@hline.3x CURS-ENG-A-MAN .\" $Header: hline_set.3x,v 76.2 95/08/01 11:08:14 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline_set 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline_set, mvhline_set, mvvline_set, mvwhline_set, mvwvline_set, vline_set, whline_set, wvline_set \(em draw lines from complex characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvhline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvvline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwhline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwvline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int vline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int whline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int wvline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline_set() , .CR mvhline_set() , .Fn mvwhline_set and .Fn whline_set functions draw a line proceeding toward the last column of the same line. .P The .CR vline_set() , .CR mvvline_set() , .Fn mvwvline_set and .Fn wvline_set functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" border_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline_set(3X)\f1:\0\0\f4hline_set()\f1, \f4mvhline_set()\f1, \f4mvvline_set()\f1, \f4mvwhline_set()\f1, \f4mvwvline_set()\f1, \n\f4vline_set()\f1, \f4whline_set()\f1, \f4wvline_set()\f1@@@draw lines from complex characters and renditions .\" toc@\f4mvhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4vline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4whline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4wvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" .\" index@\f4hline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4vline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4whline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4wvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1lines, draw from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1complex characters and renditions, draw lines from@@@\f3hline_set(3X)\f1 .\" index@\f1characters and renditions, complex, draw lines from@@@\f3hline_set(3X)\f1 .\" .\" links@hline_set.3x mvhline_set.3x .\" links@hline_set.3x mvvline_set.3x .\" links@hline_set.3x mvwhline_set.3x .\" links@hline_set.3x mvwvline_set.3x .\" links@hline_set.3x vline_set.3x .\" links@hline_set.3x whline_set.3x .\" links@hline_set.3x wvline_set.3x .\" .\" fileset_database@hline_set.3x CURS-ENG-A-MAN .\" $Header: in_wch.3x,v 76.2 95/08/01 11:13:14 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH in_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME in_wch, mvin_wch, mvwin_wch, win_wch \(em input a complex character and rendition from a window .SH SYNOPSIS .C "#include " .P .C "int in_wch(cchar_t *\f2wcval\fP);" .P .C "int mvin_wch(int \f2y\fP, int \f2x\fP, cchar_t *\f2wcval\fP);" .P .C "int mvwin_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wcval\fP);" .P .C "int win_wch(WINDOW *\f2win\fP, cchar_t *\f2wcval\fP);" .SH DESCRIPTION These functions extract the complex character and rendition from the current or specified position in the current or specified window into the object pointed to by \f2wcval\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3in_wch(3X)\f1:\0\0\f4in_wch()\f1, \f4mvin_wch()\f1, \f4mvwin_wch()\f1, \f4win_wch()\f1\n@@@input a complex character and rendition from a window .\" toc@\f4mvin_wch()\f1: input a complex character and rendition from a window@@@see \f3in_wch(3X)\f1 .\" toc@\f4mvwin_wch()\f1: input a complex character and rendition from a window@@@see \f3in_wch(3X)\f1 .\" toc@\f4win_wch()\f1: input a complex character and rendition from a window@@@see \f3in_wch(3X)\f1 .\" .\" index@\f4in_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f4mvin_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f4mvwin_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f4win_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f1input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f1complex character and rendition, input from a window@@@\f3in_wch(3X)\f1 .\" index@\f1character and rendition, complex, input from a window@@@\f3in_wch(3X)\f1 .\" index@\f1window, input a complex character and rendition from@@@\f3in_wch(3X)\f1 .\" .\" links@in_wch.3x mvin_wch.3x .\" links@in_wch.3x mvwin_wch.3x .\" links@in_wch.3x win_wch.3x .\" .\" fileset_database@in_wch.3x CURS-ENG-A-MAN .\" $Header: in_wchnstr.3x,v 76.2 95/08/01 11:14:16 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH in_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME in_wchnstr, in_wchstr, mvin_wchnstr, mvin_wchstr, mvwin_wchnstr, mvwin_wchstr, win_wchnstr, win_wchstr \(em input an array of complex characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int in_wchnstr(cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int in_wchstr(cchar_t *\f2wchstr\fP);" .P .C "int mvin_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvin_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int mvwin_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvwin_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int win_wchnstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int win_wchstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP);" .SH DESCRIPTION These functions extract characters from the current or specified window, starting at the current or specified position and ending at the end of the line, and place them in the array pointed to by .I wchstr . .P The .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr and .Fn win_wchnstr fill the array with at most \f2n\f1 \f3cchar_t\f1 elements. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wchstr\f1 with .CR in_wchstr() , .CR mvin_wchstr() , .Fn mvwin_wchstr or .Fn win_wchstr causes undefined results. The use of .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr or .Fn win_wchnstr , respectively, is recommended. .SH "SEE ALSO" in_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3in_wchnstr(3X)\f1:\0\0\f4in_wchnstr()\f1, \f4in_wchstr()\f1, \f4mvin_wchnstr()\f1, \f4mvin_wchstr()\f1, \f4mvwin_wchnstr()\f1, \n\f4mvwin_wchstr()\f1, \f4win_wchnstr()\f1, \f4win_wchstr()\f1\n@@@input an array of complex characters and renditions from a window .\" toc@\f4in_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" .\" index@\f4in_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4in_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1array of complex characters and renditions, input from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1window, input an array of complex characters and renditions from@@@\f3in_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, input an array of, from a window@@@\f3in_wchnstr(3X)\f1 .\" .\" links@in_wchnstr.3x in_wchstr.3x .\" links@in_wchnstr.3x mvin_wchstr.3x .\" links@in_wchnstr.3x mvin_wchnstr.3x .\" links@in_wchnstr.3x mvwin_wchstr.3x .\" links@in_wchnstr.3x mvwin_wchnstr.3x .\" links@in_wchnstr.3x win_wchstr.3x .\" links@in_wchnstr.3x win_wchnstr.3x .\" .\" fileset_database@in_wchnstr.3x CURS-ENG-A-MAN .\" $Header: in_wchnstr.3x,v 76.2 95/08/01 11:14:16 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH in_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME in_wchnstr, in_wchstr, mvin_wchnstr, mvin_wchstr, mvwin_wchnstr, mvwin_wchstr, win_wchnstr, win_wchstr \(em input an array of complex characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int in_wchnstr(cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int in_wchstr(cchar_t *\f2wchstr\fP);" .P .C "int mvin_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvin_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int mvwin_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvwin_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int win_wchnstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int win_wchstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP);" .SH DESCRIPTION These functions extract characters from the current or specified window, starting at the current or specified position and ending at the end of the line, and place them in the array pointed to by .I wchstr . .P The .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr and .Fn win_wchnstr fill the array with at most \f2n\f1 \f3cchar_t\f1 elements. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wchstr\f1 with .CR in_wchstr() , .CR mvin_wchstr() , .Fn mvwin_wchstr or .Fn win_wchstr causes undefined results. The use of .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr or .Fn win_wchnstr , respectively, is recommended. .SH "SEE ALSO" in_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3in_wchnstr(3X)\f1:\0\0\f4in_wchnstr()\f1, \f4in_wchstr()\f1, \f4mvin_wchnstr()\f1, \f4mvin_wchstr()\f1, \f4mvwin_wchnstr()\f1, \n\f4mvwin_wchstr()\f1, \f4win_wchnstr()\f1, \f4win_wchstr()\f1\n@@@input an array of complex characters and renditions from a window .\" toc@\f4in_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" .\" index@\f4in_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4in_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1array of complex characters and renditions, input from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1window, input an array of complex characters and renditions from@@@\f3in_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, input an array of, from a window@@@\f3in_wchnstr(3X)\f1 .\" .\" links@in_wchnstr.3x in_wchstr.3x .\" links@in_wchnstr.3x mvin_wchstr.3x .\" links@in_wchnstr.3x mvin_wchnstr.3x .\" links@in_wchnstr.3x mvwin_wchstr.3x .\" links@in_wchnstr.3x mvwin_wchnstr.3x .\" links@in_wchnstr.3x win_wchstr.3x .\" links@in_wchnstr.3x win_wchnstr.3x .\" .\" fileset_database@in_wchnstr.3x CURS-ENG-A-MAN .\" $Header: inch.3x,v 76.2 95/08/01 11:18:42 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH inch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inch, mvinch, mvwinch, winch \(em input a single-byte character and rendition from a window .SH SYNOPSIS .C "#include " .P .C "chtype inch(void);" .P .C "chtype mvinch(int \f2y\fP, int \f2x\fP);" .P .C "chtype mvwinch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "chtype winch(WINDOW *\f2win\fP);" .SH DESCRIPTION These functions return the character and rendition, of type \f2chtype\f1, at the current or specified position in the current or specified window. .SH "RETURN VALUE" Upon successful completion, the functions return the specified character and rendition. Otherwise, they return (\f3chtype\fP)ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn inch function is explicitly declared as \f3void\f1. .\" .\" toc@\f3inch(3X)\f1:\0\0\f4inch()\f1, \f4mvinch()\f1, \f4mvwinch()\f1, \f4winch\f1@@@input a single-byte character and rendition from a window .\" toc@\f4mvinch()\f1: input a single-byte character and rendition from a window@@@see \f3inch(3X)\f1 .\" toc@\f4mvwinch()\f1: input a single-byte character and rendition from a window@@@see \f3inch(3X)\f1 .\" toc@\f4winch()\f1: input a single-byte character and rendition from a window@@@see \f3inch(3X)\f1 .\" .\" index@\f4inch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f4mvinch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f4mvwinch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f4winch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f1input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f1single-byte character and rendition, input from a window@@@\f3inch(3X)\f1 .\" index@\f1window, input a single-byte character and rendition from@@@\f3inch(3X)\f1 .\" index@\f1character and rendition, input a single-byte from a window@@@\f3inch(3X)\f1 .\" .\" links@inch.3x mvinch.3x .\" links@inch.3x mvwinch.3x .\" links@inch.3x winch.3x .\" .\" fileset_database@inch.3x CURS-ENG-A-MAN .\" $Header: inchnstr.3x,v 76.2 95/08/01 11:20:07 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH inchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inchnstr, inchstr, mvinchnstr, mvinchstr, mvwinchnstr, mvwinchstr, winchnstr, winchstr \(em input an array of single-byte characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int inchnstr(chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int inchstr(chtype *\f2chstr\fP);" .P .C "int mvinchnstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvinchstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int mvwinchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvwinchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int winchnstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int winchstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP);" .SH DESCRIPTION These functions place characters and renditions from the current or specified window into the array pointed to by \f2chstr\f1, starting at the current or specified position and ending at the end of the line. .P The .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr and .Fn winchnstr functions store at most \f2n\f1 elements from the current or specified window into the array pointed to by \f2chstr\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2chstr\f1 with .CR inchstr() , .CR mvinchstr() , .Fn mvwinchstr or .Fn winchstr causes undefined results. The use of .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr or .CR winchnstr() , respectively, is recommended. .SH "SEE ALSO" inch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3inchnstr(3X)\f1:\0\0\f4inchnstr()\f1, \f4inchstr()\f1, \f4mvinchnstr()\f1, \f4mvinchstr()\f1, \f4mvwinchnstr()\f1, \f4mvwinchstr()\f1, \n\f4winchnstr()\f1, \f4winchstr()\f1@@@input an array of single-byte characters and renditions from a window .\" toc@\f4inchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" .\" index@\f4inchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4inchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1array of single-byte characters and renditions, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1single-byte characters and renditions, array of, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1characters and renditions, an array of single-byte, input from a window@@@\f3inchnstr(3X)\f1 .\" .\" links@inchnstr.3x inchstr.3x .\" links@inchnstr.3x mvinchstr.3x .\" links@inchnstr.3x mvinchnstr.3x .\" links@inchnstr.3x mvwinchstr.3x .\" links@inchnstr.3x mvwinchnstr.3x .\" links@inchnstr.3x winchstr.3x .\" links@inchnstr.3x winchnstr.3x .\" .\" fileset_database@inchnstr.3x CURS-ENG-A-MAN .\" $Header: inchnstr.3x,v 76.2 95/08/01 11:20:07 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH inchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inchnstr, inchstr, mvinchnstr, mvinchstr, mvwinchnstr, mvwinchstr, winchnstr, winchstr \(em input an array of single-byte characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int inchnstr(chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int inchstr(chtype *\f2chstr\fP);" .P .C "int mvinchnstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvinchstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int mvwinchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvwinchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int winchnstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int winchstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP);" .SH DESCRIPTION These functions place characters and renditions from the current or specified window into the array pointed to by \f2chstr\f1, starting at the current or specified position and ending at the end of the line. .P The .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr and .Fn winchnstr functions store at most \f2n\f1 elements from the current or specified window into the array pointed to by \f2chstr\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2chstr\f1 with .CR inchstr() , .CR mvinchstr() , .Fn mvwinchstr or .Fn winchstr causes undefined results. The use of .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr or .CR winchnstr() , respectively, is recommended. .SH "SEE ALSO" inch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3inchnstr(3X)\f1:\0\0\f4inchnstr()\f1, \f4inchstr()\f1, \f4mvinchnstr()\f1, \f4mvinchstr()\f1, \f4mvwinchnstr()\f1, \f4mvwinchstr()\f1, \n\f4winchnstr()\f1, \f4winchstr()\f1@@@input an array of single-byte characters and renditions from a window .\" toc@\f4inchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" .\" index@\f4inchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4inchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1array of single-byte characters and renditions, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1single-byte characters and renditions, array of, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1characters and renditions, an array of single-byte, input from a window@@@\f3inchnstr(3X)\f1 .\" .\" links@inchnstr.3x inchstr.3x .\" links@inchnstr.3x mvinchstr.3x .\" links@inchnstr.3x mvinchnstr.3x .\" links@inchnstr.3x mvwinchstr.3x .\" links@inchnstr.3x mvwinchnstr.3x .\" links@inchnstr.3x winchstr.3x .\" links@inchnstr.3x winchnstr.3x .\" .\" fileset_database@inchnstr.3x CURS-ENG-A-MAN .\" $Header: innstr.3x,v 76.2 95/08/01 11:22:05 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innstr, instr, mvinnstr, mvinstr, mvwinnstr, mvwinstr, winnstr, winstr \(em input a multi-byte character string from a window .SH SYNOPSIS .C "#include " .P .C "int innstr(char *\f2str\fP, int \f2n\fP);" .P .C "int instr(char *\f2str\fP);" .P .C "int mvinnstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvinstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int mvwinnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvwinstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int winnstr(WINDOW *\f2win\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int winstr(WINDOW *\f2win\fP, char *\f2str\fP);" .SH DESCRIPTION These functions place a string of characters from the current or specified window into the array pointed to by \f2str\fP, starting at the current or specified position and ending at the end of the line. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions store at most \f2n\f1 bytes in the string pointed to by \f2str\f1. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions will only store the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character the array is filled with complete characters. If the array is not large enough to contain any complete characters, the function fails. .SH "RETURN VALUE" Upon successful completion, .CR instr() , .CR mvinstr() , .Fn mvwinstr and .Fn winstr return OK. .P Upon successful completion, .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since multi-byte characters may be processed, there might not be a one-to-one correspondence between the number of column positions on the screen and the number of bytes returned. .P These functions do not return rendition information. .P Reading a line that overflows the array pointed to by \f2str\f1 with .CR instr() , .CR mvinstr() , .Fn mvwinstr or .Fn winstr causes undefined results. The use of .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr or .CR winnstr() , respectively, is recommended. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innstr(3X)\f1:\0\0\f4innstr()\f1, \f4instr()\f1, \f4mvinnstr()\f1, \f4mvinstr()\f1, \f4mvwinnstr()\f1, \f4mvwinstr()\f1, \f4winnstr()\f1, \n\f4winstr()\f1@@@input a multi-byte character string from a window .\" toc@\f4instr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" .\" index@\f4innstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4instr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1multi-byte character string, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1character string, multi-byte, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1window, input a multi-byte character string from@@@\f3innstr(3X)\f1 .\" .\" links@innstr.3x instr.3x .\" links@innstr.3x mvinstr.3x .\" links@innstr.3x mvinnstr.3x .\" links@innstr.3x mvwinstr.3x .\" links@innstr.3x mvwinnstr.3x .\" links@innstr.3x winstr.3x .\" links@innstr.3x winnstr.3x .\" .\" fileset_database@innstr.3x CURS-ENG-A-MAN .\" $Header: innwstr.3x,v 76.2 95/08/01 11:22:59 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innwstr, inwstr, mvinnwstr, mvinwstr, mvwinnwstr, mvwinwstr, winnwstr, winwstr \(em input a string of wide characters from a window .SH SYNOPSIS .C "#include " .P .C "int innwstr(wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int inwstr(wchar_t *\f2wstr\fP);" .P .C "int mvinnwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvinwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int mvwinnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwinwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int winnwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int winwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP);" .SH DESCRIPTION These functions place a string of \f3wchar_t\f1 characters from the current or specified window into the array pointed to by \f2wstr\f1 starting at the current or specified cursor position and ending at the end of the line. .P These functions will only store the entire wide character sequence associated with a spacing complex character. If the array is large enough to contain at least one complete spacing complex character, the array is filled with complete characters. If the array is not large enough to contain any complete characters this is an error. .P The .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr functions store at most \f2n\f1 characters in the array pointed to by \f2wstr\f1. .SH "RETURN VALUE" Upon successful completion, .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr and .Fn winwstr return OK. .P Upon successful completion, .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr or .Fn winwstr causes undefined results. The use of .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr or .CR winnwstr() , respectively, is recommended. .P These functions do not return rendition information. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innwstr(3X)\f1:\0\0\f4innwstr()\f1, \f4inwstr()\f1, \f4mvinnwstr()\f1, \f4mvinwstr()\f1, \f4mvwinnwstr()\f1, \f4mvwinwstr()\f1, \n\f4winnwstr()\f1, \f4winwstr()\f1@@@input a string of wide characters from a window .\" toc@\f4innwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4inwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" .\" index@\f4innwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4inwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1string of wide characters, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1wide characters, string of, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1window, input a string of wide characters from@@@\f3innwstr(3X)\f1 .\" index@\f1characters, wide, input a string of, from a window@@@\f3innwstr(3X)\f1 .\" .\" links@innwstr.3x inwstr.3x .\" links@innwstr.3x mvinnwstr.3x .\" links@innwstr.3x mvinwstr.3x .\" links@innwstr.3x mvwinnwstr.3x .\" links@innwstr.3x mvwinwstr.3x .\" links@innwstr.3x winnwstr.3x .\" links@innwstr.3x winwstr.3x .\" .\" fileset_database@innwstr.3x CURS-ENG-A-MAN .\" $Header: ins_nwstr.3x,v 76.2 95/08/01 11:23:53 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ins_nwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ins_nwstr, ins_wstr, mvins_nwstr, mvins_wstr, mvwins_nwstr, mvwins_wstr, wins_nwstr, wins_wstr \(em insert a wide-character string into a window .SH SYNOPSIS .C "#include " .P .C "int ins_nwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int ins_wstr(wchar_t *const \f2wstr\fP);" .P .C "int mvins_nwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvins_wstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwins_nwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwins_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int wins_nwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int wins_wstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions insert a .B wchar_t character string (as many .B wchar_t characters as will fit on the line) in the current or specified window immediately before the current or specified position. .P Any non-spacing characters in the string are associated with the first spacing character in the string that precedes the non-spacing characters. If the first character in the string is a non-spacing character, these functions will fail. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing. .P The .CR ins_nwstr() , .CR mvins_nwstr() , .Fn mvwins_nwstr and .Fn wins_nwstr functions insert at most \f2n\f1 \f3wchar_t\f1 characters. If \f2n\f1 is less than 1, then the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3ins_nwstr(3X)\f1:\0\0\f4ins_nwstr()\f1, \f4ins_wstr()\f1, \f4mvins_nwstr()\f1, \f4mvins_wstr()\f1, \f4mvwins_nwstr()\f1, \n\f4mvwins_wstr()\f1, \f4wins_nwstr()\f1, \f4wins_wstr()\f1@@@insert a wide-character string into a window .\" toc@\f4ins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" .\" index@\f4ins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4ins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1wide-character string, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1string of wide-character, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1window, insert a wide-character string into@@@\f3ins_nwstr(3X)\f1 .\" index@\f1character, insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" .\" links@ins_nwstr.3x ins_wstr.3x .\" links@ins_nwstr.3x mvins_nwstr.3x .\" links@ins_nwstr.3x mvins_wstr.3x .\" links@ins_nwstr.3x mvwins_nwstr.3x .\" links@ins_nwstr.3x mvwins_wstr.3x .\" links@ins_nwstr.3x wins_nwstr.3x .\" links@ins_nwstr.3x wins_wstr.3x .\" .\" fileset_database@ins_nwstr.3x CURS-ENG-A-MAN .\" $Header: ins_wch.3x,v 76.2 95/08/01 11:24:46 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ins_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ins_wch, mvins_wch, mvwins_wch, wins_wch \(em insert a complex character and rendition into a window .SH SYNOPSIS .C "#include " .P .C "int ins_wch(cchar_t *const \f2wch\fP);" .P .C "int wins_wch(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "int mvins_wch(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .P .C "int mvwins_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .SH DESCRIPTION These functions insert the complex character \f2wch\f1 with its rendition in the current or specified window at the current or specified cursor position. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing, with the exception that if a newline is inserted into the last line of a window and scrolling is not enabled, the behaviour is unspecified. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" For non-spacing characters, .Fn add_wch can be used to add the non-spacing characters to a spacing complex character already in the window. .SH "SEE ALSO" add_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3ins_wch(3X)\f1:\0\0\f4ins_wch()\f1, \f4mvins_wch()\f1, \f4mvwins_wch()\f1, \f4wins_wch()\f1\n@@@insert a complex character and rendition into a window .\" toc@\f4mvins_wch()\f1: insert a complex character and rendition into a window@@@see \f3ins_wch(3X)\f1 .\" toc@\f4mvwins_wch()\f1: insert a complex character and rendition into a window@@@see \f3ins_wch(3X)\f1 .\" toc@\f4wins_wch()\f1: insert a complex character and rendition into a window@@@see \f3ins_wch(3X)\f1 .\" .\" index@\f4ins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f4mvins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f4mvwins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f4wins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1complex character and rendition, insert into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1character and rendition, complex, insert into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1window, insert a complex character and rendition into@@@\f3ins_wch(3X)\f1 .\" .\" links@ins_wch.3x mvins_wch.3x .\" links@ins_wch.3x mvwins_wch.3x .\" links@ins_wch.3x wins_wch.3x .\" .\" fileset_database@ins_wch.3x CURS-ENG-A-MAN .\" $Header: ins_nwstr.3x,v 76.2 95/08/01 11:23:53 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ins_nwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ins_nwstr, ins_wstr, mvins_nwstr, mvins_wstr, mvwins_nwstr, mvwins_wstr, wins_nwstr, wins_wstr \(em insert a wide-character string into a window .SH SYNOPSIS .C "#include " .P .C "int ins_nwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int ins_wstr(wchar_t *const \f2wstr\fP);" .P .C "int mvins_nwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvins_wstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwins_nwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwins_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int wins_nwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int wins_wstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions insert a .B wchar_t character string (as many .B wchar_t characters as will fit on the line) in the current or specified window immediately before the current or specified position. .P Any non-spacing characters in the string are associated with the first spacing character in the string that precedes the non-spacing characters. If the first character in the string is a non-spacing character, these functions will fail. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing. .P The .CR ins_nwstr() , .CR mvins_nwstr() , .Fn mvwins_nwstr and .Fn wins_nwstr functions insert at most \f2n\f1 \f3wchar_t\f1 characters. If \f2n\f1 is less than 1, then the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3ins_nwstr(3X)\f1:\0\0\f4ins_nwstr()\f1, \f4ins_wstr()\f1, \f4mvins_nwstr()\f1, \f4mvins_wstr()\f1, \f4mvwins_nwstr()\f1, \n\f4mvwins_wstr()\f1, \f4wins_nwstr()\f1, \f4wins_wstr()\f1@@@insert a wide-character string into a window .\" toc@\f4ins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" .\" index@\f4ins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4ins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1wide-character string, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1string of wide-character, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1window, insert a wide-character string into@@@\f3ins_nwstr(3X)\f1 .\" index@\f1character, insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" .\" links@ins_nwstr.3x ins_wstr.3x .\" links@ins_nwstr.3x mvins_nwstr.3x .\" links@ins_nwstr.3x mvins_wstr.3x .\" links@ins_nwstr.3x mvwins_nwstr.3x .\" links@ins_nwstr.3x mvwins_wstr.3x .\" links@ins_nwstr.3x wins_nwstr.3x .\" links@ins_nwstr.3x wins_wstr.3x .\" .\" fileset_database@ins_nwstr.3x CURS-ENG-A-MAN .\" $Header: insch.3x,v 76.2 95/08/01 11:25:41 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insch, mvinsch, mvwinsch, winsch \(em insert a single-byte character and rendition into a window .SH SYNOPSIS .C "#include " .P .C "int insch(chtype \f2ch\fP);" .P .C "int mvinsch(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP);" .P .C "int mvwinsch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP);" .P .C "int winsch(WINDOW *\f2win\fP, chtype \f2ch\fP);" .SH DESCRIPTION These functions insert the character and rendition from \f2ch\f1 into the current or specified window at the current or specified position. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing, with the exception that if a newline is inserted into the last line of a window and scrolling is not enabled, the behaviour is unspecified. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" ins_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" toc@\f3insch(3X)\f1:\0\0\f4insch()\f1, \f4mvinsch()\f1, \f4mvwinsch()\f1, \f4winsch()\f1\n@@@insert a single-byte character and rendition into a window .\" toc@\f4mvinsch()\f1: insert a single-byte character and rendition into a window@@@see \f3insch(3X)\f1 .\" toc@\f4mvwinsch()\f1: insert a single-byte character and rendition into a window@@@see \f3insch(3X)\f1 .\" toc@\f4winsch()\f1: insert a single-byte character and rendition into a window@@@see \f3insch(3X)\f1 .\" .\" index@\f4insch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f4mvinsch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f4mvwinsch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f4winsch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f1insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f1single-byte character and rendition, insert into a window@@@\f3insch(3X)\f1 .\" index@\f1character and rendition, single-byte, insert into a window@@@\f3insch(3X)\f1 .\" index@\f1window, insert a single-byte character and rendition into@@@\f3insch(3X)\f1 .\" .\" links@insch.3x mvinsch.3x .\" links@insch.3x mvwinsch.3x .\" links@insch.3x winsch.3x .\" .\" fileset_database@insch.3x CURS-ENG-A-MAN .\" $Header: insnstr.3x,v 76.3 95/10/05 14:42:06 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insnstr, insstr, mvinsnstr, mvinsstr, mvwinsnstr, mvwinsstr, winsnstr, winsstr \(em insert a multi-byte character string into a window .SH SYNOPSIS .C "#include " .P .C "int insnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int insstr(char *const \f2str\fP);" .P .C "int mvinsnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvinsstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwinsnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwinsstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int winsnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int winsstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions insert a character string (as many characters as will fit on the line) before the current or specified position in the current or specified window. .P These functions do not advance the cursor position. These functions perform special-character processing. The .Fn innstr and .Fn innwstr functions perform wrapping. The .Fn instr and .Fn inswstr functions do not perform wrapping. .P The .CR insnstr() , .CR mvinsnstr() , .Fn mvwinsnstr and .Fn winsnstr functions insert .\" entire multi-byte characters contained in the first at most \f2n\f1 bytes. If \f2n\f1 is less than 1, the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since the string may contain multi-byte characters, there might not be a one-to-one correspondence between the number of column positions occupied by the characters and the number of bytes in the string. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3insnstr(3X)\f1:\0\0\f4insnstr()\f1, \f4insstr()\f1, \f4mvinsnstr()\f1, \f4mvinsstr()\f1, \f4mvwinsnstr()\f1, \f4mvwinsstr()\f1, \n\f4winsnstr()\f1, \f4winsstr()\f1@@@insert a multi-byte character into a window .\" toc@\f4insstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" .\" index@\f4insnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4insstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1multi-byte character, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1character, multi-byte, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1window, insert a multi-byte character into@@@\f3insnstr(3X)\f1 .\" .\" links@insnstr.3x insstr.3x .\" links@insnstr.3x mvinsnstr.3x .\" links@insnstr.3x mvinsstr.3x .\" links@insnstr.3x mvwinsnstr.3x .\" links@insnstr.3x mvwinsstr.3x .\" links@insnstr.3x winsnstr.3x .\" links@insnstr.3x winsstr.3x .\" .\" fileset_database@insnstr.3x CURS-ENG-A-MAN .\" $Header: insnstr.3x,v 76.3 95/10/05 14:42:06 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insnstr, insstr, mvinsnstr, mvinsstr, mvwinsnstr, mvwinsstr, winsnstr, winsstr \(em insert a multi-byte character string into a window .SH SYNOPSIS .C "#include " .P .C "int insnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int insstr(char *const \f2str\fP);" .P .C "int mvinsnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvinsstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwinsnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwinsstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int winsnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int winsstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions insert a character string (as many characters as will fit on the line) before the current or specified position in the current or specified window. .P These functions do not advance the cursor position. These functions perform special-character processing. The .Fn innstr and .Fn innwstr functions perform wrapping. The .Fn instr and .Fn inswstr functions do not perform wrapping. .P The .CR insnstr() , .CR mvinsnstr() , .Fn mvwinsnstr and .Fn winsnstr functions insert .\" entire multi-byte characters contained in the first at most \f2n\f1 bytes. If \f2n\f1 is less than 1, the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since the string may contain multi-byte characters, there might not be a one-to-one correspondence between the number of column positions occupied by the characters and the number of bytes in the string. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3insnstr(3X)\f1:\0\0\f4insnstr()\f1, \f4insstr()\f1, \f4mvinsnstr()\f1, \f4mvinsstr()\f1, \f4mvwinsnstr()\f1, \f4mvwinsstr()\f1, \n\f4winsnstr()\f1, \f4winsstr()\f1@@@insert a multi-byte character into a window .\" toc@\f4insstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" .\" index@\f4insnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4insstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1multi-byte character, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1character, multi-byte, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1window, insert a multi-byte character into@@@\f3insnstr(3X)\f1 .\" .\" links@insnstr.3x insstr.3x .\" links@insnstr.3x mvinsnstr.3x .\" links@insnstr.3x mvinsstr.3x .\" links@insnstr.3x mvwinsnstr.3x .\" links@insnstr.3x mvwinsstr.3x .\" links@insnstr.3x winsnstr.3x .\" links@insnstr.3x winsstr.3x .\" .\" fileset_database@insnstr.3x CURS-ENG-A-MAN .\" $Header: innstr.3x,v 76.2 95/08/01 11:22:05 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innstr, instr, mvinnstr, mvinstr, mvwinnstr, mvwinstr, winnstr, winstr \(em input a multi-byte character string from a window .SH SYNOPSIS .C "#include " .P .C "int innstr(char *\f2str\fP, int \f2n\fP);" .P .C "int instr(char *\f2str\fP);" .P .C "int mvinnstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvinstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int mvwinnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvwinstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int winnstr(WINDOW *\f2win\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int winstr(WINDOW *\f2win\fP, char *\f2str\fP);" .SH DESCRIPTION These functions place a string of characters from the current or specified window into the array pointed to by \f2str\fP, starting at the current or specified position and ending at the end of the line. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions store at most \f2n\f1 bytes in the string pointed to by \f2str\f1. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions will only store the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character the array is filled with complete characters. If the array is not large enough to contain any complete characters, the function fails. .SH "RETURN VALUE" Upon successful completion, .CR instr() , .CR mvinstr() , .Fn mvwinstr and .Fn winstr return OK. .P Upon successful completion, .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since multi-byte characters may be processed, there might not be a one-to-one correspondence between the number of column positions on the screen and the number of bytes returned. .P These functions do not return rendition information. .P Reading a line that overflows the array pointed to by \f2str\f1 with .CR instr() , .CR mvinstr() , .Fn mvwinstr or .Fn winstr causes undefined results. The use of .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr or .CR winnstr() , respectively, is recommended. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innstr(3X)\f1:\0\0\f4innstr()\f1, \f4instr()\f1, \f4mvinnstr()\f1, \f4mvinstr()\f1, \f4mvwinnstr()\f1, \f4mvwinstr()\f1, \f4winnstr()\f1, \n\f4winstr()\f1@@@input a multi-byte character string from a window .\" toc@\f4instr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" .\" index@\f4innstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4instr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1multi-byte character string, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1character string, multi-byte, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1window, input a multi-byte character string from@@@\f3innstr(3X)\f1 .\" .\" links@innstr.3x instr.3x .\" links@innstr.3x mvinstr.3x .\" links@innstr.3x mvinnstr.3x .\" links@innstr.3x mvwinstr.3x .\" links@innstr.3x mvwinnstr.3x .\" links@innstr.3x winstr.3x .\" links@innstr.3x winnstr.3x .\" .\" fileset_database@innstr.3x CURS-ENG-A-MAN .\" $Header: innwstr.3x,v 76.2 95/08/01 11:22:59 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innwstr, inwstr, mvinnwstr, mvinwstr, mvwinnwstr, mvwinwstr, winnwstr, winwstr \(em input a string of wide characters from a window .SH SYNOPSIS .C "#include " .P .C "int innwstr(wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int inwstr(wchar_t *\f2wstr\fP);" .P .C "int mvinnwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvinwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int mvwinnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwinwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int winnwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int winwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP);" .SH DESCRIPTION These functions place a string of \f3wchar_t\f1 characters from the current or specified window into the array pointed to by \f2wstr\f1 starting at the current or specified cursor position and ending at the end of the line. .P These functions will only store the entire wide character sequence associated with a spacing complex character. If the array is large enough to contain at least one complete spacing complex character, the array is filled with complete characters. If the array is not large enough to contain any complete characters this is an error. .P The .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr functions store at most \f2n\f1 characters in the array pointed to by \f2wstr\f1. .SH "RETURN VALUE" Upon successful completion, .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr and .Fn winwstr return OK. .P Upon successful completion, .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr or .Fn winwstr causes undefined results. The use of .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr or .CR winnwstr() , respectively, is recommended. .P These functions do not return rendition information. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innwstr(3X)\f1:\0\0\f4innwstr()\f1, \f4inwstr()\f1, \f4mvinnwstr()\f1, \f4mvinwstr()\f1, \f4mvwinnwstr()\f1, \f4mvwinwstr()\f1, \n\f4winnwstr()\f1, \f4winwstr()\f1@@@input a string of wide characters from a window .\" toc@\f4innwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4inwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" .\" index@\f4innwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4inwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1string of wide characters, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1wide characters, string of, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1window, input a string of wide characters from@@@\f3innwstr(3X)\f1 .\" index@\f1characters, wide, input a string of, from a window@@@\f3innwstr(3X)\f1 .\" .\" links@innwstr.3x inwstr.3x .\" links@innwstr.3x mvinnwstr.3x .\" links@innwstr.3x mvinwstr.3x .\" links@innwstr.3x mvwinnwstr.3x .\" links@innwstr.3x mvwinwstr.3x .\" links@innwstr.3x winnwstr.3x .\" links@innwstr.3x winwstr.3x .\" .\" fileset_database@innwstr.3x CURS-ENG-A-MAN .\" $Header: mvprintw.3x,v 76.2 95/08/01 11:56:52 ssa Exp $ .TA m .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH mvprintw 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mvprintw, mvwprintw, printw, wprintw \(em print formatted output in window .SH SYNOPSIS .C "#include " .P .C "int mvprintw(int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int mvwprintw(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int printw(char *\f2fmt\fP, ...);" .P .C "int wprintw(WINDOW *\f2win\fP, char *\f2fmt\fP, ...);" .SH DESCRIPTION The .CR mvprintw() , .CR mvwprintw() , .Fn printw and .Fn wprintw functions are analogous to .CR printf() . The effect of these functions is as though .Fn sprintf were used to format the string, and then .Fn waddstr were used to add that multi-byte string to the current or specified window at the current or specified cursor position. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" addnstr(), fprintf() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity and its name is changed from .Fn printw to .CR mvprintw() . .\" .\" toc@\f3mvprintw(3X)\f1:\0\0\f4mvprintw()\f1, \f4mvwprintw()\f1, \f4printw()\f1, \f4wprintw\f1@@@print formatted output in window .\" toc@\f4mvwprintw()\f1: print formatted output in window@@@see \f3mvprintw(3X)\f1 .\" toc@\f4printw()\f1: print formatted output in window@@@see \f3mvprintw(3X)\f1 .\" toc@\f4wprintw()\f1: print formatted output in window@@@see \f3mvprintw(3X)\f1 .\" .\" index@\f4mvprintw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f4mvwprintw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f4printw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f4wprintw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f1print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f1formatted output, print in window@@@\f3mvprintw(3X)\f1 .\" index@\f1output, formatted, print in window@@@\f3mvprintw(3X)\f1 .\" index@\f1window, print formatted output in@@@\f3mvprintw(3X)\f1 .\" .\" links@mvprintw.3x mvwprintw.3x .\" links@mvprintw.3x printw.3x .\" links@mvprintw.3x wprintw.3x .\" .\" fileset_database@mvprintw.3x CURS-ENG-A-MAN .\" $Header: mvscanw.3x,v 76.2 95/08/01 11:58:38 ssa Exp $ .TA m .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH mvscanw 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mvscanw, mvwscanw, scanw, wscanw \(em convert formatted input from a window .SH SYNOPSIS .C "#include " .P .C "int mvscanw(int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int mvwscanw(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int scanw(char *\f2fmt\fP, ...);" .P .C "int wscanw(WINDOW *\f2win\fP, char *\f2fmt\fP, ...);" .SH DESCRIPTION These functions are similar to .CR scanf() . Their effect is as though .Fn mvwgetstr were called to get a multi-byte character string from the current or specified window at the current or specified cursor position, and then .Fn sscanf were used to interpret and convert that string. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" getnstr(), printw(), fscanf() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), wcstombs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity and its name is changed from .Fn scanw to .CR mvscanw() . .\" .\" toc@\f3mvscanw(3X)\f1:\0\0\f4mvscanw()\f1, \f4mvwscanw()\f1, \f4scanw()\f1, \f4wscanw()\f1@@@convert formatted input from a window .\" toc@\f4mvwscanw()\f1: convert formatted input from a window@@@see \f3mvscanw(3X)\f1 .\" toc@\f4scanw()\f1: convert formatted input from a window@@@see \f3mvscanw(3X)\f1 .\" toc@\f4wscanw()\f1: convert formatted input from a window@@@see \f3mvscanw(3X)\f1 .\" .\" index@\f4mvscanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f4mvwscanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f4scanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f4wscanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1formatted input, convert, from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1input, convert formatted, from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1window, convert formatted input from@@@\f3mvscanw(3X)\f1 .\" .\" links@mvscanw.3x mvwscanw.3x .\" links@mvscanw.3x scanw.3x .\" links@mvscanw.3x wscanw.3x .\" .\" fileset_database@mvscanw.3x CURS-ENG-A-MAN .\" $Header: hline.3x,v 76.2 95/08/01 11:07:23 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline, mvhline, mvvline, mvwhline, mvwvline, vline, whline, wvline \(em draw lines from single-byte characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvhline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvvline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwhline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwvline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int vline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int whline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int wvline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline() , .CR mvhline() , .Fn mvwhline and .Fn whline functions draw a line proceeding toward the last column of the same line. .P The .CR vline() , .CR mvvline() , .Fn mvwvline and .Fn wvline functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" border(), box(), hline_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline(3X)\f1:\0\0\f4hline()\f1, \f4mvhline()\f1, \f4mvvline()\f1, \f4mvwhline()\f1, \f4mvwvline()\f1, \f4vline()\f1, \f4whline()\f1, \f4wvline()\f1\n@@@draw lines from single-byte characters and renditions .\" toc@\f4mvhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4vline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4whline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4wvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" .\" index@\f4hline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4vline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4whline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4wvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1lines, draw from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1single-byte characters and renditions, draw lines from@@@\f3hline(3X)\f1 .\" index@\f1characters and renditions, draw lines from single-byte@@@\f3hline(3X)\f1 .\" index@\f1renditions and characters, draw lines from single-byte@@@\f3hline(3X)\f1 .\" .\" links@hline.3x mvhline.3x .\" links@hline.3x mvvline.3x .\" links@hline.3x mvwhline.3x .\" links@hline.3x mvwvline.3x .\" links@hline.3x vline.3x .\" links@hline.3x whline.3x .\" links@hline.3x wvline.3x .\" .\" fileset_database@hline.3x CURS-ENG-A-MAN .\" $Header: hline_set.3x,v 76.2 95/08/01 11:08:14 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline_set 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline_set, mvhline_set, mvvline_set, mvwhline_set, mvwvline_set, vline_set, whline_set, wvline_set \(em draw lines from complex characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvhline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvvline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwhline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwvline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int vline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int whline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int wvline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline_set() , .CR mvhline_set() , .Fn mvwhline_set and .Fn whline_set functions draw a line proceeding toward the last column of the same line. .P The .CR vline_set() , .CR mvvline_set() , .Fn mvwvline_set and .Fn wvline_set functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" border_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline_set(3X)\f1:\0\0\f4hline_set()\f1, \f4mvhline_set()\f1, \f4mvvline_set()\f1, \f4mvwhline_set()\f1, \f4mvwvline_set()\f1, \n\f4vline_set()\f1, \f4whline_set()\f1, \f4wvline_set()\f1@@@draw lines from complex characters and renditions .\" toc@\f4mvhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4vline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4whline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4wvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" .\" index@\f4hline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4vline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4whline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4wvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1lines, draw from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1complex characters and renditions, draw lines from@@@\f3hline_set(3X)\f1 .\" index@\f1characters and renditions, complex, draw lines from@@@\f3hline_set(3X)\f1 .\" .\" links@hline_set.3x mvhline_set.3x .\" links@hline_set.3x mvvline_set.3x .\" links@hline_set.3x mvwhline_set.3x .\" links@hline_set.3x mvwvline_set.3x .\" links@hline_set.3x vline_set.3x .\" links@hline_set.3x whline_set.3x .\" links@hline_set.3x wvline_set.3x .\" .\" fileset_database@hline_set.3x CURS-ENG-A-MAN .\" $Header: add_wch.3x,v 76.2 95/07/31 11:12:51 ssa Exp $ .TA a .TH add_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME add_wch, mvadd_wch, mvwadd_wch, wadd_wch \(em add a complex character and rendition to a window .SH SYNOPSIS .C "#include " .P .C "int add_wch(cchar_t *const \f2wch\fP);" .P .C "int wadd_wch(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "int mvadd_wch(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .P .C "int mvwadd_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .SH DESCRIPTION These functions add information to the current or specified window at the current or specified position, and then advance the cursor. These functions perform wrapping. These functions perform special-character processing. .RS .TP 3 .C \(bu If \f2wch\f1 refers to a spacing character, then any previous character at that location is removed, a new character specified by \f2wch\f1 is placed at that location with rendition specified by \f2wch\fP; then the cursor advances to the next spacing character on the screen. .TP .C \(bu If \f2wch\f1 refers to a non-spacing character, all previous characters at that location are preserved, the non-spacing characters of \f2wch\f1 are added to the spacing complex character, and the rendition specified by \f2wch\f1 is ignored. .RE .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Rendition of Characters Placed into a Window\f1 in curses_intro, addch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4add_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f4mvadd_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f4mvwadd_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f4wadd_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f1add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f1character and rendition to a window, add a complex@@@\f3add_wch(3X)\f1 .\" index@\f1complex character and rendition, add to a window@@@\f3add_wch(3X)\f1 .\" .\" toc@\f3add_wch(3X)\f1:\0\0\f4add_wch()\f1, \f4mvadd_wch()\f1, \f4mvwadd_wch()\f1, \n\f4wadd_ch()\f1@@@add a complex character and rendition to a window .\" toc@\f4mvadd_wch()\f1: add a complex character and rendition to a window@@@see \f3add_wch(3X)\f1 .\" toc@\f4mvwadd_wch()\f1: add a complex character and rendition to a window@@@see \f3add_wch(3X)\f1 .\" toc@\f4wadd_wch()\f1: add a complex character and rendition to a window@@@see \f3add_wch(3X)\f1 .\" .\" links@add_wch.3x mvadd_wch.3x .\" links@add_wch.3x mvwadd_wch.3x .\" links@add_wch.3x wadd_wch.3x .\" .\" fileset_database@add_wch.3x CURS-ENG-A-MAN .\" $Header: add_wchnstr.3x,v 76.2 95/07/31 11:15:08 ssa Exp $ .TA a .TH add_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME add_wchnstr, add_wchstr, mvadd_wchnstr, mvadd_wchstr, mvwadd_wchnstr, mvwadd_wchstr, wadd_wchnstr, wadd_wchstr \(em add an array of complex characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int add_wchnstr(cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int add_wchstr(cchar_t *const \f2wchstr\fP);" .P .C "int wadd_wchnstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int wadd_wchstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvadd_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int mvadd_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvwadd_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP," .br .C " int \f2n\fP);" .P .C "int mvwadd_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .SH DESCRIPTION These functions write the array of \f3cchar_t\f1 specified by \f2wchstr\f1 into the current or specified window starting at the current or specified cursor position. .P These functions do not advance the cursor. The results are unspecified if \f2wchstr\f1 contains any special characters. .P The functions end successfully on encountering a null \f3cchar_t\f1. The functions also end successfully when they fill the current line. If a character cannot completely fit at the end of the current line, those columns are filled with the background character and rendition. .P The .CR add_wchnstr() , .CR mvadd_wchnstr() , .CR mvwadd_wchnstr() and .CR wadd_wchnstr() functions end successfully after writing \f2n\f1 \f3cchar_t\fPs (or the entire array of \f3cchar_t\fPs, if \f2n\f1 is \(mi1). .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3add_wchnstr(3X)\f1:\0\0\f4add_wchstr()\f1, \f4mvadd_wchnstr()\f1, \f4mvadd_wchstr()\f1, \f4mvwadd_wchnstr()\f1,\n\f4mvwadd_wchstr\f1, \f4wadd_wchnstr\f1, \n\f4wadd_wchstr\f1@@@add an array of complex characters and renditions to a window .\" toc@\f4add_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" .\" index@\f4add_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4add_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1an array of complex characters and renditions to a window, add@@@\f3add_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, add an array of, to a window@@@\f3add_wchnstr(3X)\f1 .\" .\" links@add_wchnstr.3x add_wchstr.3x .\" links@add_wchnstr.3x mvadd_wchnstr.3x .\" links@add_wchnstr.3x mvadd_wchstr.3x .\" links@add_wchnstr.3x mvwadd_wchnstr.3x .\" links@add_wchnstr.3x mvwadd_wchstr.3x .\" links@add_wchnstr.3x wadd_wchnstr.3x .\" links@add_wchnstr.3x wadd_wchstr.3x .\" .\" fileset_database@add_wchnstr.3x CURS-ENG-A-MAN .\" $Header: add_wchnstr.3x,v 76.2 95/07/31 11:15:08 ssa Exp $ .TA a .TH add_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME add_wchnstr, add_wchstr, mvadd_wchnstr, mvadd_wchstr, mvwadd_wchnstr, mvwadd_wchstr, wadd_wchnstr, wadd_wchstr \(em add an array of complex characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int add_wchnstr(cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int add_wchstr(cchar_t *const \f2wchstr\fP);" .P .C "int wadd_wchnstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int wadd_wchstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvadd_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int mvadd_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvwadd_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP," .br .C " int \f2n\fP);" .P .C "int mvwadd_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .SH DESCRIPTION These functions write the array of \f3cchar_t\f1 specified by \f2wchstr\f1 into the current or specified window starting at the current or specified cursor position. .P These functions do not advance the cursor. The results are unspecified if \f2wchstr\f1 contains any special characters. .P The functions end successfully on encountering a null \f3cchar_t\f1. The functions also end successfully when they fill the current line. If a character cannot completely fit at the end of the current line, those columns are filled with the background character and rendition. .P The .CR add_wchnstr() , .CR mvadd_wchnstr() , .CR mvwadd_wchnstr() and .CR wadd_wchnstr() functions end successfully after writing \f2n\f1 \f3cchar_t\fPs (or the entire array of \f3cchar_t\fPs, if \f2n\f1 is \(mi1). .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3add_wchnstr(3X)\f1:\0\0\f4add_wchstr()\f1, \f4mvadd_wchnstr()\f1, \f4mvadd_wchstr()\f1, \f4mvwadd_wchnstr()\f1,\n\f4mvwadd_wchstr\f1, \f4wadd_wchnstr\f1, \n\f4wadd_wchstr\f1@@@add an array of complex characters and renditions to a window .\" toc@\f4add_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" .\" index@\f4add_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4add_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1an array of complex characters and renditions to a window, add@@@\f3add_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, add an array of, to a window@@@\f3add_wchnstr(3X)\f1 .\" .\" links@add_wchnstr.3x add_wchstr.3x .\" links@add_wchnstr.3x mvadd_wchnstr.3x .\" links@add_wchnstr.3x mvadd_wchstr.3x .\" links@add_wchnstr.3x mvwadd_wchnstr.3x .\" links@add_wchnstr.3x mvwadd_wchstr.3x .\" links@add_wchnstr.3x wadd_wchnstr.3x .\" links@add_wchnstr.3x wadd_wchstr.3x .\" .\" fileset_database@add_wchnstr.3x CURS-ENG-A-MAN .\" $Header: addch.3x,v 76.2 95/07/28 16:16:36 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addch, mvaddch, mvwaddch, waddch \(em add a single-byte character and rendition to a window and advance the cursor .SH SYNOPSIS .C "#include " .P .C "int addch(const chtype \f2ch\fP);" .P .C "int mvaddch(int \f2y\fP, int \f2x\fP, const chtype \f2ch\fP);" .P .C "int mvwaddch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, const chtype \f2ch\fP);" .P .C "int waddch(WINDOW *\f2win\fP, const chtype \f2ch\fP);" .SH DESCRIPTION The .CR addch() , .CR mvaddch() , .CR mvwaddch() and .CR waddch() functions place \f2ch\f1 into the current or specified window at the current or specified position, and then advance the window's cursor position. These functions perform wrapping. These functions perform special-character processing. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" \f3Rendition of Characters Placed into a Window\f1 in curses_intro, add_wch(), attroff(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The entry is rewritten for clarity. Also the type of argument \f2ch\f1 is changed from \f3chtype\f1 to \f3const chtype\f1. .\" .\" toc@\f3addch(3X)\f1:\0\0\f4addch()\f1, \f4mvaddch()\f1, \f4mvwaddch()\f1, \f4waddch\f1\n@@@add a single-byte character and rendition to a window and advance the cursor .\" toc@\f4mvaddch()\f1: add a single-byte character and rendition to a window and advance the cursor@@@see \f3addch(3X)\f1 .\" toc@\f4mvwaddch()\f1: add a single-byte character and rendition to a window and advance the cursor@@@see \f3addch(3X)\f1 .\" toc@\f4waddch()\f1: add a single-byte character and rendition to a window and advance the cursor@@@see \f3addch(3X)\f1 .\" .\" index@\f4addch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f4mvaddch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f4mvwaddch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f4waddch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f1add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f1single-byte character and rendition, add, to a window and advance the cursor@@@\f3addch(3X)\f1 .\" .\" links@addch.3x mvaddch.3x .\" links@addch.3x mvwaddch.3x .\" links@addch.3x waddch.3x .\" .\" fileset_database@addch.3x CURS-ENG-A-MAN .\" $Header: addchnstr.3x,v 76.2 95/07/31 11:17:15 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addchnstr, mvaddchnstr, mvwaddchnstr, waddchnstr \(em add length limited string of single-byte characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int addchnstr(chtype *const \f2chstr\fP, int \f2n\fP);" .P .C "int mvaddchnstr(int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP, int \f2n\fP);" .P .C "int mvwaddchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP," .br .C " int \f2n\fP);" .P .C "int waddchnstr(WINDOW *\f2win\fP, chtype *const \f2chstr\fP, int \f2n\fP);" .SH DESCRIPTION These functions overlay the contents of the current or specified window, starting at the current or specified position, with the contents of the array pointed to by .I chstr until a null .B chtype is encountered in the array pointed to by .I chstr . .P These functions do not change the cursor position. These functions do not perform special-character processing. These functions do not perform wrapping. .P These functions copy at most \f2n\f1 items, but no more than will fit on the line. If \f2n\f1\ is \(mi1 then the whole string is copied, to the maximum number that fit on the line. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" addch(), add_wch(), add_wchstr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addchnstr(3X)\f1:\0\0\f4mvaddchnstr()\f1, \f4mvwaddchnstr()\f1, \f4waddchnstr()\f1\n@@@add length limited string of single-byte characters and renditions to a window .\" toc@\f4mvaddchnstr()\f1: add length limited string of single-byte characters and renditions to a window\n@@@see \f3addchnstr(3X)\f1 .\" toc@\f4mvwaddchnstr()\f1: add length limited string of single-byte characters and renditions to a window\n@@@see \f3addchnstr(3X)\f1 .\" toc@\f4waddchnstr()\f1: add length limited string of single-byte characters and renditions to a window\n@@@see \f3addchnstr(3X)\f1 .\" .\" index@\f4addchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window@@@\f3addchnstr(3X)\f1 .\" index@\f4mvaddchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window\n@@@\f3addchnstr(3X)\f1 .\" index@\f4mvwaddchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window\n@@@\f3addchnstr(3X)\f1 .\" index@\f4waddchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window@@@\f3addchnstr(3X)\f1 .\" index@\f1add length limited string of single-byte characters and renditions to a window@@@\f3addchnstr(3X)\f1 .\" index@\f1length limited string of single-byte characters and renditions to a window, add@@@\f3addchnstr(3X)\f1 .\" index@\f1single-byte characters and renditions to a window, add length limited string of@@@\f3addchnstr(3X)\f1 .\" .\" links@addchnstr.3x mvaddchnstr.3x .\" links@addchnstr.3x mvwaddchnstr.3x .\" links@addchnstr.3x waddchnstr.3x .\" .\" fileset_database@addchnstr.3x CURS-ENG-A-MAN .\" $Header: addchstr.3x,v 76.2 95/07/31 11:19:11 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addchstr 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addchstr, mvaddchstr, mvwaddchstr, waddchstr \(em add string of single-byte characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int addchstr(chtype *const \f2chstr\fP);" .P .C "int mvaddchstr(int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP);" .P .C "int mvwaddchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP);" .P .C "int waddchstr(WINDOW *\f2win\fP, chtype *const \f2chstr\fP);" .SH DESCRIPTION These functions overlay the contents of the current or specified window, starting at the current or specified position, with the contents of the array pointed to by .I chstr until a null .CR chtype is encountered in the array pointed to by .IR chstr . .P These functions do not change the cursor position. These functions do not perform special-character processing. These functions do not perform wrapping. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" addch(), addchnstr(), add_wch(), add_wchstr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addchstr(3X)\f1:\0\0\f4mvaddchstr()\f1, \f4mvwaddchstr()\f1, \f4waddchstr()\f1\n@@@add string of single-byte characters and renditions to a window .\" toc@\f4mvaddchstr()\f1: add string of single-byte characters and renditions to a window@@@see \f3addchstr(3X)\f1 .\" toc@\f4mvwaddchstr()\f1: add string of single-byte characters and renditions to a window@@@see \f3addchstr(3X)\f1 .\" toc@\f4waddchstr()\f1: add string of single-byte characters and renditions to a window@@@see \f3addchstr(3X)\f1 .\" .\" index@\f4addchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f4mvaddchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f4mvwaddchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f4waddchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f1add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f1string of single-byte characters and renditions to a window, add@@@\f3addchstr(3X)\f1 .\" index@\f1single-byte characters and renditions to a window, add string of@@@\f3addchstr(3X)\f1 .\" .\" links@addchstr.3x mvaddchstr.3x .\" links@addchstr.3x mvwaddchstr.3x .\" links@addchstr.3x waddchstr.3x .\" .\" fileset_database@addchstr.3x CURS-ENG-A-MAN .\" $Header: addnstr.3x,v 76.2 95/07/31 11:20:19 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnstr, addstr, mvaddnstr, mvaddstr, mvwaddnstr, mvwaddstr waddnstr, waddstr \(em add a string of multi-byte characters without rendition to a window and advance cursor .SH SYNOPSIS .C "#include " .P .C "int addnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int addstr(char *const \f2str\fP);" .P .C "int mvaddnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvaddstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwaddnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwaddstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int waddnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int waddstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions write the characters of the string \f2str\f1 on the current or specified window starting at the current or specified position using the background rendition. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions are similar to calling .CR mbstowcs() on \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .P The .CR addnstr() , .CR mvaddnstr() , .CR mvwaddnstr() and .CR waddnstr() functions use at most \f2n\f1 bytes from \f2str\f1. These functions add the entire string when \f2n\f1 is \(mi1. These functions are similar to calling .CR mbstowcs() on the first \f2n\f1 bytes of \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" addnwstr(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .P In X/Open Curses, Issue 3, the .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions were described in the .CR addstr() entry. In X/Open Curses, Issue 4, the type of the \f2str\f1 argument defined for these functions is changed from \f3char\ *\f1 to \f3char\ *const\fP, and the .BR DESCRIPTION is changed to indicate that the functions will handle multi-byte sequences correctly. .\" toc@\f3addnstr(3X)\f1:\0\0\f4addstr()\f1, \f4mvaddnstr()\f1, \f4mvaddstr()\f1, \f4mvwaddnstr()\f1, \f4mvwaddstr()\f1, \f4waddnstr()\f1, \n\f4waddstr()\f1@@@add a string of multi-byte characters without rendition to a window and advance cursor .\" toc@\f4addstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" .\" index@\f4addnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4addstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1add a string of multi-byte characters without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1multi-byte characters, add a string of, without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" .\" links@addnstr.3x addstr.3x .\" links@addnstr.3x mvaddnstr.3x .\" links@addnstr.3x mvaddstr.3x .\" links@addnstr.3x mvwaddstr.3x .\" links@addnstr.3x mvwaddnstr.3x .\" links@addnstr.3x waddstr.3x .\" links@addnstr.3x waddnstr.3x .\" .\" fileset_database@addnstr.3x CURS-ENG-A-MAN .\" $Header: addnwstr.3x,v 76.2 95/07/28 16:19:15 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnwstr, addwstr, mvaddnwstr, mvaddwstr, mvwaddnwstr, mvwaddwstr, waddnwstr, waddwstr \(em add a wide-character string to a window and advance the cursor .SH SYNOPSIS .C "#include " .P .C "int addnwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int addwstr(wchar_t *const \f2wstr\fP);" .P .C "int mvaddnwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvaddwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwaddnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwaddwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int waddnwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int waddwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions write the characters of the wide character string \f2wstr\f1 on the current or specified window at that window's current or specified cursor position. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The effect is similar to building a \f3cchar_t\f1 from the \f3wchar_t\f1 and the background rendition and calling .CR wadd_wch() once for each \f3wchar_t\f1 character in the string. The cursor movement specified by the .I mv functions occurs only once at the start of the operation. .P The .CR addnwstr() , .CR mvaddnwstr() , .CR mvwaddnwstr() and .CR waddnwstr() functions write at most \f2n\f1 wide characters. If \f2n\f1 is \(mi1, then the entire string will be added. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" add_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addnwstr(3X)\f1:\0\0\f4addnwstr()\f1, \f4addwstr()\f1, \f4mvaddnwstr()\f1, \f4mvaddwstr()\f1, \f4mvwaddnwstr()\f1, \f4mvwaddwstr()\f1, \n\f4waddnwstr()\f1, \f4waddwstr()\f1@@@add a wide-character string to a window and advance the cursor .\" toc@\f4addwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" .\" index@\f4addnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4addwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f1add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" .\" links@addnwstr.3x addwstr.3x .\" links@addnwstr.3x mvaddnwstr.3x .\" links@addnwstr.3x mvaddwstr.3x .\" links@addnwstr.3x mvwaddnwstr.3x .\" links@addnwstr.3x mvwaddwstr.3x .\" links@addnwstr.3x waddnwstr.3x .\" links@addnwstr.3x waddwstr.3x .\" .\" fileset_database@addnwstr.3x CURS-ENG-A-MAN .\" $Header: addnstr.3x,v 76.2 95/07/31 11:20:19 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnstr, addstr, mvaddnstr, mvaddstr, mvwaddnstr, mvwaddstr waddnstr, waddstr \(em add a string of multi-byte characters without rendition to a window and advance cursor .SH SYNOPSIS .C "#include " .P .C "int addnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int addstr(char *const \f2str\fP);" .P .C "int mvaddnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvaddstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwaddnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwaddstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int waddnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int waddstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions write the characters of the string \f2str\f1 on the current or specified window starting at the current or specified position using the background rendition. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions are similar to calling .CR mbstowcs() on \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .P The .CR addnstr() , .CR mvaddnstr() , .CR mvwaddnstr() and .CR waddnstr() functions use at most \f2n\f1 bytes from \f2str\f1. These functions add the entire string when \f2n\f1 is \(mi1. These functions are similar to calling .CR mbstowcs() on the first \f2n\f1 bytes of \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" addnwstr(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .P In X/Open Curses, Issue 3, the .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions were described in the .CR addstr() entry. In X/Open Curses, Issue 4, the type of the \f2str\f1 argument defined for these functions is changed from \f3char\ *\f1 to \f3char\ *const\fP, and the .BR DESCRIPTION is changed to indicate that the functions will handle multi-byte sequences correctly. .\" toc@\f3addnstr(3X)\f1:\0\0\f4addstr()\f1, \f4mvaddnstr()\f1, \f4mvaddstr()\f1, \f4mvwaddnstr()\f1, \f4mvwaddstr()\f1, \f4waddnstr()\f1, \n\f4waddstr()\f1@@@add a string of multi-byte characters without rendition to a window and advance cursor .\" toc@\f4addstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" .\" index@\f4addnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4addstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1add a string of multi-byte characters without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1multi-byte characters, add a string of, without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" .\" links@addnstr.3x addstr.3x .\" links@addnstr.3x mvaddnstr.3x .\" links@addnstr.3x mvaddstr.3x .\" links@addnstr.3x mvwaddstr.3x .\" links@addnstr.3x mvwaddnstr.3x .\" links@addnstr.3x waddstr.3x .\" links@addnstr.3x waddnstr.3x .\" .\" fileset_database@addnstr.3x CURS-ENG-A-MAN .\" $Header: addnwstr.3x,v 76.2 95/07/28 16:19:15 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnwstr, addwstr, mvaddnwstr, mvaddwstr, mvwaddnwstr, mvwaddwstr, waddnwstr, waddwstr \(em add a wide-character string to a window and advance the cursor .SH SYNOPSIS .C "#include " .P .C "int addnwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int addwstr(wchar_t *const \f2wstr\fP);" .P .C "int mvaddnwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvaddwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwaddnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwaddwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int waddnwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int waddwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions write the characters of the wide character string \f2wstr\f1 on the current or specified window at that window's current or specified cursor position. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The effect is similar to building a \f3cchar_t\f1 from the \f3wchar_t\f1 and the background rendition and calling .CR wadd_wch() once for each \f3wchar_t\f1 character in the string. The cursor movement specified by the .I mv functions occurs only once at the start of the operation. .P The .CR addnwstr() , .CR mvaddnwstr() , .CR mvwaddnwstr() and .CR waddnwstr() functions write at most \f2n\f1 wide characters. If \f2n\f1 is \(mi1, then the entire string will be added. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" add_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addnwstr(3X)\f1:\0\0\f4addnwstr()\f1, \f4addwstr()\f1, \f4mvaddnwstr()\f1, \f4mvaddwstr()\f1, \f4mvwaddnwstr()\f1, \f4mvwaddwstr()\f1, \n\f4waddnwstr()\f1, \f4waddwstr()\f1@@@add a wide-character string to a window and advance the cursor .\" toc@\f4addwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" .\" index@\f4addnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4addwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f1add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" .\" links@addnwstr.3x addwstr.3x .\" links@addnwstr.3x mvaddnwstr.3x .\" links@addnwstr.3x mvaddwstr.3x .\" links@addnwstr.3x mvwaddnwstr.3x .\" links@addnwstr.3x mvwaddwstr.3x .\" links@addnwstr.3x waddnwstr.3x .\" links@addnwstr.3x waddwstr.3x .\" .\" fileset_database@addnwstr.3x CURS-ENG-A-MAN .\" $Header: chgat.3x,v 76.2 95/07/31 17:23:18 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH chgat 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chgat, mvchgat, mvwchgat, wchgat \(em change renditions of characters in a window .SH SYNOPSIS .C "#include " .P .C "int chgat(int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP, void *const \f2opts\fP);" .P .C "int mvchgat(int \f2y\fP, int \f2x\fP, int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP," .br .C " void *const \f2opts\fP);" .P .C "int mvwchgat(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, int \f2n\fP, attr_t \f2attr\fP," .br .C " short \f2color\fP, void *const \f2opts\fP);" .P .C "int wchgat(WINDOW *\f2win\fP, int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP," .br .C " void *const \f2opts\fP);" .SH DESCRIPTION These functions change the renditions of the next \f2n\f1 characters in the current or specified window (or of the remaining characters on the line, if \f2n\f1 is \(mi1), starting at the current or specified cursor position. The attributes and colors are specified by \f2attr\f1 and \f2color\f1 as for .CR setcchar() . .P These functions do not update the cursor. These functions do not perform wrapping. .P A value of \f2n\f1 that is greater than the remaining characters on a line is not an error. .P The \f2opts\f1 argument is reserved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" setcchar(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3chgat(3X)\f1:\0\0\f4chgat()\f1, \f4mvchgat()\f1, \f4mvwchgat()\f1, \f4wchgat()\f1@@@change renditions of characters in a window .\" toc@\f4mvchgat()\f1: change renditions of characters in a window@@@see \f3chgat(3X)\f1 .\" toc@\f4mvwchgat()\f1: change renditions of characters in a window@@@see \f3chgat(3X)\f1 .\" toc@\f4wchgat()\f1: change renditions of characters in a window@@@see \f3chgat(3X)\f1 .\" .\" index@\f4chgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f4mvchgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f4mvwchgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f4wchgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f1change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f1renditions of characters in a window, change@@@\f3chgat(3X)\f1 .\" index@\f1window, change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f1characters, renditions of, change in a window@@@\f3chgat(3X)\f1 .\" .\" links@chgat.3x mvchgat.3x .\" links@chgat.3x mvwchgat.3x .\" links@chgat.3x wchgat.3x .\" .\" fileset_database@chgat.3x CURS-ENG-A-MAN .\" $Header: delch.3x,v 76.2 95/08/01 15:04:04 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH delch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME delch, mvdelch, mvwdelch, wdelch \(em delete a character from a window. .SH SYNOPSIS .C "#include " .P .C "int delch(void);" .P .C "int mvdelch(int \f2y\fP, int \f2x\fP);" .P .C "int mvwdelch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "int wdelch(WINDOW *\f2win\fP);" .SH DESCRIPTION These functions delete the character at the current or specified position in the current or specified window. This function does not change the cursor position. .SS "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SS ERRORS No errors are defined. .SS "SEE ALSO" . .SS "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn delch function is explicitly declared as \f3void\f1. .\" .\" toc@\f3delch(3x)\f1:\0\0\f4delch()\f1, \f4mvdelch()\f1, \f4mvwdelch()\f1, \f4wdelch()\f1@@@delete character from a window .\" .\" toc@\f3mvdelch()\f1:\0\0delete character from a window@@@\f1see\f3delch(3x)\f1 .\" toc@\f3mvwdelch()\f1:\0\0delete character from a window@@@\f1see\f3delch(3x)\f1 .\" toc@\f3wdelch()\f1:\0\0delete character from a window@@@\f1see\f3delch(3x)\f1 .\" .\" index@\f4delch()\f1, \f4mvdelch()\f1, \f4mvwdelch()\f1, \f4wdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" index@\f4mvdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" index@\f4mvwdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" index@\f4wdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" .\" links@delch.3x mvdelch.3x .\" links@delch.3x mvwdelch.3x .\" links@delch.3x wdelch.3x .\" .\" fileset_database@delch.3x CURS-ENG-A-MAN .\" .\" $Header: get_wch.3x,v 76.2 95/08/01 10:38:24 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH get_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME get_wch, mvget_wch, mvwget_wch, wget_wch \(em get a wide character from a terminal .SH SYNOPSIS .C "#include " .P .C "int get_wch(wint_t *\f2ch\fP);" .P .C "int mvget_wch(int \f2y\fP, int \f2x\fP, wint_t *\f2ch\fP);" .P .C "int mvwget_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2ch\fP);" .P .C "int wget_wch(WINDOW *\f2win\fP, wint_t *\f2ch\fP);" .SH DESCRIPTION These functions read a character from the terminal associated with the current or specified window. If .Fn keypad is enabled, these functions respond to the pressing of a function key by setting the object pointed to by .I ch to the corresponding KEY_ value defined in .Hd curses.h and returning KEY_CODE_YES. .P Processing of terminal input is subject to the general rules described in \f3Input Processing\f1 in curses_intro. .P If echoing is enabled, then the character is echoed as though it were provided as an input argument to .CR ins_wch() , except for the following characters: .PP .TS tab(@); lw(2.00i)@lw(3i). T{ , and the current erase character: T}@T{ The input is interpreted as specified in .CR specialchars and then the character at the resulting cursor position is deleted as though .Fn delch were called, except that if the cursor was originally in the first column of the line, then the user is alerted as though .Fn beep were called. T} .P Function keys@T{ The user is alerted as though .Fn beep were called. Information concerning the function keys is not returned to the caller. T} .TE .P If the current or specified window is not a pad, and it has been moved or modified since the last refresh operation, then it will be refreshed before another character is read. .SH "RETURN VALUE" When these functions successfully report the pressing of a function key, they return KEY_CODE_YES. When they successfully report a wide character, they return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Applications should not define the escape key by itself as a single-character function. .P When using these functions, .Fn nocbreak mode and .Fn echo mode should not be used at the same time. Depending on the state of the terminal when each character is typed, the application may produce undesirable results. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, beep(), cbreak(), ins_wch(), keypad(), move(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3get_wch(3X)\f1:\0\0\f4get_wch()\f1, \f4mvget_wch()\f1, \f4mvwget_wch()\f1, \f4wget_wch\f1()\f1@@@get a wide character from a terminal .\" toc@\f4mvget_wch()\f1: get a wide character from a terminal@@@see \f3get_wch(3X)\f1 .\" toc@\f4mvwget_wch()\f1: get a wide character from a terminal@@@see \f3get_wch(3X)\f1 .\" toc@\f4wget_wch()\f1: get a wide character from a terminal@@@see \f3get_wch(3X)\f1 .\" .\" index@\f4get_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f4mvget_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f4mvwget_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f4wget_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f1get a wide character from a terminal@@@\f3get_wch(3X)\f1 .\" index@\f1wide character, get from a terminal@@@\f3get_wch(3X)\f1 .\" index@\f1terminal, get a wide character from@@@\f3get_wch(3X)\f1 .\" index@\f1character, get a wide character from a terminal@@@\f3get_wch(3X)\f1 .\" .\" links@get_wch.3x mvget_wch.3x .\" links@get_wch.3x mvwget_wch.3x .\" links@get_wch.3x wget_wch.3x .\" .\" fileset_database@get_wch.3x CURS-ENG-A-MAN .\" $Header: getn_wstr.3x,v 76.2 95/08/01 10:52:41 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getn_wstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getn_wstr, get_wstr, mvgetn_wstr, mvget_wstr, mvwgetn_wstr, mvwget_wstr, wgetn_wstr, wget_wstr \(em get an array of wide characters and function key codes from a terminal .SH SYNOPSIS .C "#include " .P .C "int getn_wstr(wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int get_wstr(wint_t *\f2wstr\fP);" .P .C "int mvgetn_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvget_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int mvwgetn_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwget_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int wgetn_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int wget_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP);" .SH DESCRIPTION The effect of .Fn get_wstr is as though a series of calls to .Fn get_wch were made, until a newline character, end-of-line character, or end-of-file character is processed. An end-of-file character is represented by WEOF, as defined in .CR . A newline or end-of-line is represented as its .CR wchar_t value. In all instances, the end of the string is terminated by a null .CR wchar_t . The resulting values are placed in the area pointed to by \f2wstr\f1. .P The user's erase and kill characters are interpreted and affect the sequence of characters returned. .P The effect of .Fn wget_wstr is as though a series of calls to .Fn wget_wch were made. .P The effect of .Fn mvget_wstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_wstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. The effect of .Fn mvget_nwstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_nwstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. .P The .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr and .Fn wgetn_wstr functions read at most \f2n\f1 characters, letting the application prevent overflow of the input buffer. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR get_wstr() , .CR mvget_wstr() , .Fn mvwget_wstr or .Fn wget_wstr causes undefined results. The use of .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr or .Fn wgetn_wstr , respectively, is recommended. .P These functions cannot return KEY_ values as there is no way to distinguish a KEY_ value from a valid .B wchar_t value. .SH "SEE ALSO" get_wch(), getstr(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Chapter 9,\f3General Terminal Interface\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getn_wstr(3X)\f1:\0\0\f4getn_wstr()\f1, \f4get_wstr()\f1, \f4mvgetn_wstr()\f1, \f4mvget_wstr()\f1, \f4mvwgetn_wstr()\f1, \n\f4mvwget_wstr()\f1, \f4wgetn_wstr()\f1, \f4wget_wstr()\f1\n@@@get an array of wide characters and function key codes from a terminal .\" toc@\f4get_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" .\" index@\f4getn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4get_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1array of wide characters and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1wide characters, an array of, and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1terminal, get an array of wide characters and function key codes@@@\f3getn_wstr(3X)\f1 .\" .\" links@getn_wstr.3x get_wstr.3x .\" links@getn_wstr.3x mvgetn_wstr.3x .\" links@getn_wstr.3x mvget_wstr.3x .\" links@getn_wstr.3x mvwgetn_wstr.3x .\" links@getn_wstr.3x mvwget_wstr.3x .\" links@getn_wstr.3x wgetn_wstr.3x .\" links@getn_wstr.3x wget_wstr.3x .\" .\" fileset_database@getn_wstr.3x CURS-ENG-A-MAN .\" $Header: getch.3x,v 76.2 95/08/01 10:51:16 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getch, wgetch, mvgetch, mvwgetch \(em get a single-byte character from the terminal .SH SYNOPSIS .C "#include " .P .C "int getch(void);" .P .C "int mvgetch(int \f2y\fP, int \f2x\fP);" .P .C "int mvwgetch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "int wgetch(WINDOW *\f2win\fP);" .SH DESCRIPTION These functions read a single-byte character from the terminal associated with the current or specified window. The results are unspecified if the input is not a single-byte character. If .Fn keypad is enabled, these functions respond to the pressing of a function key by returning the corresponding KEY_ value defined in .CR . .P Processing of terminal input is subject to the general rules described in \f3Input Processing\f1 in curses_intro. .P If echoing is enabled, then the character is echoed as though it were provided as an input argument to .CR insch() , except for the following characters: .PP .TS tab(`); lw(2.00i) lw(3i). T{ , and the current erase character: T}`T{ The input is interpreted as specified in .CR specialchars and then the character at the resulting cursor position is deleted as though .Fn delch were called, except that if the cursor was originally in the first column of the line, then the user is alerted as though .Fn beep were called. T} .P Function keys`T{ The user is alerted as though .Fn beep were called. Information concerning the function keys is not returned to the caller. T} .TE .P If the current or specified window is not a pad, and it has been moved or modified since the last refresh operation, then it will be refreshed before another character is read. .SH "RETURN VALUE" Upon successful completion, these functions return the single-byte character, KEY_ value, or ERR. .P If in nodelay mode and no data is available, ERR is returned. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Applications should not define the escape key by itself as a single-character function. .P When using these functions, nocbreak mode (\c .CR nocbreak() ) and echo mode (\c .CR echo() ) should not be used at the same time. Depending on the state of the terminal when each character is typed, the program may produce undesirable results. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, cbreak(), doupdate(), insch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn getch function is explicitly declared as \f3void\f1. .\" .\" toc@\f3getch(3X)\f1:\0\0\f4getch()\f1, \f4wgetch()\f1, \f4mvgetch()\f1, \f4mvwgetch()\f1@@@get a single-byte character from the terminal .\" toc@\f4wgetch()\f1: get a single-byte character from the terminal@@@see \f3getch(3X)\f1 .\" toc@\f4mvwgetch()\f1: get a single-byte character from the terminal@@@see \f3getch(3X)\f1 .\" toc@\f4mvgetch()\f1: get a single-byte character from the terminal@@@see \f3getch(3X)\f1 .\" .\" index@\f4getch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f4wgetch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f4mvgetch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f4mvwgetch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f1get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f1single-byte character, get from the terminal@@@\f3getch(3X)\f1 .\" index@\f1terminal, get a single-byte character@@@\f3getch(3X)\f1 .\" index@\f1character, single-byte, get from the terminal@@@\f3getch(3X)\f1 .\" .\" links@getch.3x wgetch.3x .\" links@getch.3x mvwgetch.3x .\" links@getch.3x mvgetch.3x .\" .\" fileset_database@getch.3x CURS-ENG-A-MAN .\" $Header: getn_wstr.3x,v 76.2 95/08/01 10:52:41 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getn_wstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getn_wstr, get_wstr, mvgetn_wstr, mvget_wstr, mvwgetn_wstr, mvwget_wstr, wgetn_wstr, wget_wstr \(em get an array of wide characters and function key codes from a terminal .SH SYNOPSIS .C "#include " .P .C "int getn_wstr(wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int get_wstr(wint_t *\f2wstr\fP);" .P .C "int mvgetn_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvget_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int mvwgetn_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwget_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int wgetn_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int wget_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP);" .SH DESCRIPTION The effect of .Fn get_wstr is as though a series of calls to .Fn get_wch were made, until a newline character, end-of-line character, or end-of-file character is processed. An end-of-file character is represented by WEOF, as defined in .CR . A newline or end-of-line is represented as its .CR wchar_t value. In all instances, the end of the string is terminated by a null .CR wchar_t . The resulting values are placed in the area pointed to by \f2wstr\f1. .P The user's erase and kill characters are interpreted and affect the sequence of characters returned. .P The effect of .Fn wget_wstr is as though a series of calls to .Fn wget_wch were made. .P The effect of .Fn mvget_wstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_wstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. The effect of .Fn mvget_nwstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_nwstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. .P The .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr and .Fn wgetn_wstr functions read at most \f2n\f1 characters, letting the application prevent overflow of the input buffer. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR get_wstr() , .CR mvget_wstr() , .Fn mvwget_wstr or .Fn wget_wstr causes undefined results. The use of .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr or .Fn wgetn_wstr , respectively, is recommended. .P These functions cannot return KEY_ values as there is no way to distinguish a KEY_ value from a valid .B wchar_t value. .SH "SEE ALSO" get_wch(), getstr(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Chapter 9,\f3General Terminal Interface\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getn_wstr(3X)\f1:\0\0\f4getn_wstr()\f1, \f4get_wstr()\f1, \f4mvgetn_wstr()\f1, \f4mvget_wstr()\f1, \f4mvwgetn_wstr()\f1, \n\f4mvwget_wstr()\f1, \f4wgetn_wstr()\f1, \f4wget_wstr()\f1\n@@@get an array of wide characters and function key codes from a terminal .\" toc@\f4get_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" .\" index@\f4getn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4get_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1array of wide characters and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1wide characters, an array of, and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1terminal, get an array of wide characters and function key codes@@@\f3getn_wstr(3X)\f1 .\" .\" links@getn_wstr.3x get_wstr.3x .\" links@getn_wstr.3x mvgetn_wstr.3x .\" links@getn_wstr.3x mvget_wstr.3x .\" links@getn_wstr.3x mvwgetn_wstr.3x .\" links@getn_wstr.3x mvwget_wstr.3x .\" links@getn_wstr.3x wgetn_wstr.3x .\" links@getn_wstr.3x wget_wstr.3x .\" .\" fileset_database@getn_wstr.3x CURS-ENG-A-MAN .\" $Header: getnstr.3x,v 76.2 95/08/01 10:57:27 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnstr, mvgetnstr, mvwgetnstr, wgetnstr, \(em get a multi-byte character length limited string from the terminal .SH SYNOPSIS .C "#include " .P .C "int getnstr(char *\f2str\fP, int \f2n\fP);" .P .C "int mvgetnstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvwgetnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int wgetnstr(WINDOW *\f2win\fP, char *\f2str\fP, int \f2n\fP);" .SH DESCRIPTION The effect of .Fn getnstr and .Fn wgetnstr is as though a series of calls to .Fn getch were made, until a newline or carriage return is received. The resulting value is placed in the area pointed to by \f2str\f1. The .Fn getnstr and .Fn wgetnstr functions read at most \f2n\f1 bytes, thus preventing a possible overflow of the input buffer. The user's erase and kill characters are interpreted, as well as any special keys (such as function keys, home key, clear key, and so on). .P The .Fn mvgetnstr function is identical to .Fn getnstr except that it is as though it is a call to .Fn move and then a series of calls to .CR getch() . The .Fn mvwgetnstr function is identical to .Fn getnstr except it is as though a call to .Fn wmove is made and then a series of calls to .CR wgetch() . .P The .CR getnstr() , .CR wgetnstr() , .Fn mvgetnstr and .Fn mvwgetnstr functions will only return the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character, the functions fill the array with complete characters. If the array is not large enough to contain any complete characters, the function fails. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" .P Traditional implementations often limited the number of bytes returned to 256. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, beep(), getch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getnstr(3X)\f1:\0\0\f4getnstr()\f1, \f4mvgetnstr()\f1, \f4mvwgetnstr()\f1, \f4wgetnstr()\f1\n@@@get a multi-byte character length limited string from the terminal .\" toc@\f4mvgetnstr()\f1: get a multi-byte character length limited string from the terminal@@@see \f3getnstr(3X)\f1 .\" toc@\f4mvwgetnstr()\f1: get a multi-byte character length limited string from the terminal@@@see \f3getnstr(3X)\f1 .\" toc@\f4wgetnstr()\f1: get a multi-byte character length limited string from the terminal@@@see \f3getnstr(3X)\f1 .\" .\" index@\f4getnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f4mvgetnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f4mvwgetnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f4wgetnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1multi-byte character length limited string, get from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1terminal, get a multi-byte character length limited string from@@@\f3getnstr(3X)\f1 .\" index@\f1character, get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1string, get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" .\" links@getnstr.3x mvgetnstr.3x .\" links@getnstr.3x mvwgetnstr.3x .\" links@getnstr.3x wgetnstr.3x .\" .\" fileset_database@getnstr.3x CURS-ENG-A-MAN .\" $Header: getstr.3x,v 76.2 95/08/01 10:58:50 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getstr 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getstr, mvgetstr, mvwgetstr, wgetstr \(em get a multi-byte character string from the terminal .SH SYNOPSIS .C "#include " .P .C "int getstr(char *\f2str\fP);" .P .C "int mvgetstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int mvwgetstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int wgetstr(WINDOW *\f2win\fP, char *\f2str\fP);" .SH DESCRIPTION The effect of .Fn getstr is as though a series of calls to .Fn getch were made, until a newline or carriage return is received. The resulting value is placed in the area pointed to by \f2str\f1. The user's erase and kill characters are interpreted, as well as any special keys (such as function keys, home key, clear key, and so on). .P The .Fn mvgetstr function is identical to .Fn getstr except that it is as though it is a call to .Fn move and then a series of calls to .CR getch() . The .Fn mvwgetstr function is identical to .Fn getstr except it is as though a call to .Fn wmove is made and then a series of calls to .CR wgetch() . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2str\f1 with .CR getstr() , .CR mvgetstr() , .Fn mvwgetstr or .Fn wgetstr causes undefined results. .P Traditional implementations often limited the number of bytes returned to 256. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, beep(), getch(), getnstr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .br .ne 5 .SH Issue 3 .P In X/Open Curses, Issue 3, the .CR getstr() , .CR mvgetstr() , .Fn mvwgetstr and .Fn wgetstr functions were described in the .Fn addstr entry. In X/Open Curses, Issue 4, the .B DESCRIPTION of these functions is rewritten for clarity and is updated to indicate that they will handle multi-byte sequences correctly. .\" .\" toc@\f3getstr(3X)\f1:\0\0\f4getstr()\f1, \f4mvgetstr()\f1, \f4mvwgetstr()\f1, \f4wgetstr()\f1\n@@@get a multi-byte character string from the terminal .\" toc@\f4mvgetstr()\f1: get a multi-byte character string from the terminal@@@see \f3getstr(3X)\f1 .\" toc@\f4mvwgetstr()\f1: get a multi-byte character string from the terminal@@@see \f3getstr(3X)\f1 .\" toc@\f4wgetstr()\f1: get a multi-byte character string from the terminal@@@see \f3getstr(3X)\f1 .\" .\" index@\f4getstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f4mvgetstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f4mvwgetstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f4wgetstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1multi-byte character string, get from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1terminal, get a multi-byte character string@@@\f3getstr(3X)\f1 .\" index@\f1character, get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1string, get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" .\" links@getstr.3x mvgetstr.3x .\" links@getstr.3x mvwgetstr.3x .\" links@getstr.3x wgetstr.3x .\" .\" fileset_database@getstr.3x CURS-ENG-A-MAN .\" $Header: hline.3x,v 76.2 95/08/01 11:07:23 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline, mvhline, mvvline, mvwhline, mvwvline, vline, whline, wvline \(em draw lines from single-byte characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvhline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvvline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwhline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwvline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int vline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int whline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int wvline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline() , .CR mvhline() , .Fn mvwhline and .Fn whline functions draw a line proceeding toward the last column of the same line. .P The .CR vline() , .CR mvvline() , .Fn mvwvline and .Fn wvline functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" border(), box(), hline_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline(3X)\f1:\0\0\f4hline()\f1, \f4mvhline()\f1, \f4mvvline()\f1, \f4mvwhline()\f1, \f4mvwvline()\f1, \f4vline()\f1, \f4whline()\f1, \f4wvline()\f1\n@@@draw lines from single-byte characters and renditions .\" toc@\f4mvhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4vline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4whline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4wvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" .\" index@\f4hline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4vline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4whline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4wvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1lines, draw from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1single-byte characters and renditions, draw lines from@@@\f3hline(3X)\f1 .\" index@\f1characters and renditions, draw lines from single-byte@@@\f3hline(3X)\f1 .\" index@\f1renditions and characters, draw lines from single-byte@@@\f3hline(3X)\f1 .\" .\" links@hline.3x mvhline.3x .\" links@hline.3x mvvline.3x .\" links@hline.3x mvwhline.3x .\" links@hline.3x mvwvline.3x .\" links@hline.3x vline.3x .\" links@hline.3x whline.3x .\" links@hline.3x wvline.3x .\" .\" fileset_database@hline.3x CURS-ENG-A-MAN .\" $Header: hline_set.3x,v 76.2 95/08/01 11:08:14 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline_set 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline_set, mvhline_set, mvvline_set, mvwhline_set, mvwvline_set, vline_set, whline_set, wvline_set \(em draw lines from complex characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvhline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvvline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwhline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwvline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int vline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int whline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int wvline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline_set() , .CR mvhline_set() , .Fn mvwhline_set and .Fn whline_set functions draw a line proceeding toward the last column of the same line. .P The .CR vline_set() , .CR mvvline_set() , .Fn mvwvline_set and .Fn wvline_set functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" border_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline_set(3X)\f1:\0\0\f4hline_set()\f1, \f4mvhline_set()\f1, \f4mvvline_set()\f1, \f4mvwhline_set()\f1, \f4mvwvline_set()\f1, \n\f4vline_set()\f1, \f4whline_set()\f1, \f4wvline_set()\f1@@@draw lines from complex characters and renditions .\" toc@\f4mvhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4vline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4whline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4wvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" .\" index@\f4hline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4vline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4whline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4wvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1lines, draw from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1complex characters and renditions, draw lines from@@@\f3hline_set(3X)\f1 .\" index@\f1characters and renditions, complex, draw lines from@@@\f3hline_set(3X)\f1 .\" .\" links@hline_set.3x mvhline_set.3x .\" links@hline_set.3x mvvline_set.3x .\" links@hline_set.3x mvwhline_set.3x .\" links@hline_set.3x mvwvline_set.3x .\" links@hline_set.3x vline_set.3x .\" links@hline_set.3x whline_set.3x .\" links@hline_set.3x wvline_set.3x .\" .\" fileset_database@hline_set.3x CURS-ENG-A-MAN .\" $Header: mvwin.3x,v 76.2 95/08/01 14:04:59 ssa Exp $ .TA m .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH mvwin 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mvwin \(em move window .SH SYNOPSIS .C "#include " .P .C "int mvwin(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .SH DESCRIPTION The .Fn mvwin function moves the specified window so that its origin is at position (\f2y\f1, \f2x\f1). If the move would cause any portion of the window to extend past any edge of the screen, the function fails and the window is not moved. .SH "RETURN VALUE" Upon successful completion, .Fn mvwin returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The application should not move subwindows by calling .CR mvwin() . .SH "SEE ALSO" derwin(), doupdate(), is_linetouched(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" index@\f4mvwin()\f1 \- move window@@@\f3mvwin(3X)\f1 .\" index@\f1move window@@@\f3mvwin(3X)\f1 .\" index@\f1window, move@@@\f3mvwin(3X)\f1 .\" .\" toc@\f3mvwin(3X)\f1:\0\0\f4mvwin()\f1@@@move window .\" .\" fileset_database@mvwin.3x CURS-ENG-A-MAN .\" $Header: in_wch.3x,v 76.2 95/08/01 11:13:14 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH in_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME in_wch, mvin_wch, mvwin_wch, win_wch \(em input a complex character and rendition from a window .SH SYNOPSIS .C "#include " .P .C "int in_wch(cchar_t *\f2wcval\fP);" .P .C "int mvin_wch(int \f2y\fP, int \f2x\fP, cchar_t *\f2wcval\fP);" .P .C "int mvwin_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wcval\fP);" .P .C "int win_wch(WINDOW *\f2win\fP, cchar_t *\f2wcval\fP);" .SH DESCRIPTION These functions extract the complex character and rendition from the current or specified position in the current or specified window into the object pointed to by \f2wcval\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3in_wch(3X)\f1:\0\0\f4in_wch()\f1, \f4mvin_wch()\f1, \f4mvwin_wch()\f1, \f4win_wch()\f1\n@@@input a complex character and rendition from a window .\" toc@\f4mvin_wch()\f1: input a complex character and rendition from a window@@@see \f3in_wch(3X)\f1 .\" toc@\f4mvwin_wch()\f1: input a complex character and rendition from a window@@@see \f3in_wch(3X)\f1 .\" toc@\f4win_wch()\f1: input a complex character and rendition from a window@@@see \f3in_wch(3X)\f1 .\" .\" index@\f4in_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f4mvin_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f4mvwin_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f4win_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f1input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f1complex character and rendition, input from a window@@@\f3in_wch(3X)\f1 .\" index@\f1character and rendition, complex, input from a window@@@\f3in_wch(3X)\f1 .\" index@\f1window, input a complex character and rendition from@@@\f3in_wch(3X)\f1 .\" .\" links@in_wch.3x mvin_wch.3x .\" links@in_wch.3x mvwin_wch.3x .\" links@in_wch.3x win_wch.3x .\" .\" fileset_database@in_wch.3x CURS-ENG-A-MAN .\" $Header: in_wchnstr.3x,v 76.2 95/08/01 11:14:16 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH in_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME in_wchnstr, in_wchstr, mvin_wchnstr, mvin_wchstr, mvwin_wchnstr, mvwin_wchstr, win_wchnstr, win_wchstr \(em input an array of complex characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int in_wchnstr(cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int in_wchstr(cchar_t *\f2wchstr\fP);" .P .C "int mvin_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvin_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int mvwin_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvwin_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int win_wchnstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int win_wchstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP);" .SH DESCRIPTION These functions extract characters from the current or specified window, starting at the current or specified position and ending at the end of the line, and place them in the array pointed to by .I wchstr . .P The .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr and .Fn win_wchnstr fill the array with at most \f2n\f1 \f3cchar_t\f1 elements. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wchstr\f1 with .CR in_wchstr() , .CR mvin_wchstr() , .Fn mvwin_wchstr or .Fn win_wchstr causes undefined results. The use of .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr or .Fn win_wchnstr , respectively, is recommended. .SH "SEE ALSO" in_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3in_wchnstr(3X)\f1:\0\0\f4in_wchnstr()\f1, \f4in_wchstr()\f1, \f4mvin_wchnstr()\f1, \f4mvin_wchstr()\f1, \f4mvwin_wchnstr()\f1, \n\f4mvwin_wchstr()\f1, \f4win_wchnstr()\f1, \f4win_wchstr()\f1\n@@@input an array of complex characters and renditions from a window .\" toc@\f4in_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" .\" index@\f4in_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4in_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1array of complex characters and renditions, input from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1window, input an array of complex characters and renditions from@@@\f3in_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, input an array of, from a window@@@\f3in_wchnstr(3X)\f1 .\" .\" links@in_wchnstr.3x in_wchstr.3x .\" links@in_wchnstr.3x mvin_wchstr.3x .\" links@in_wchnstr.3x mvin_wchnstr.3x .\" links@in_wchnstr.3x mvwin_wchstr.3x .\" links@in_wchnstr.3x mvwin_wchnstr.3x .\" links@in_wchnstr.3x win_wchstr.3x .\" links@in_wchnstr.3x win_wchnstr.3x .\" .\" fileset_database@in_wchnstr.3x CURS-ENG-A-MAN .\" $Header: in_wchnstr.3x,v 76.2 95/08/01 11:14:16 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH in_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME in_wchnstr, in_wchstr, mvin_wchnstr, mvin_wchstr, mvwin_wchnstr, mvwin_wchstr, win_wchnstr, win_wchstr \(em input an array of complex characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int in_wchnstr(cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int in_wchstr(cchar_t *\f2wchstr\fP);" .P .C "int mvin_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvin_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int mvwin_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvwin_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int win_wchnstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int win_wchstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP);" .SH DESCRIPTION These functions extract characters from the current or specified window, starting at the current or specified position and ending at the end of the line, and place them in the array pointed to by .I wchstr . .P The .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr and .Fn win_wchnstr fill the array with at most \f2n\f1 \f3cchar_t\f1 elements. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wchstr\f1 with .CR in_wchstr() , .CR mvin_wchstr() , .Fn mvwin_wchstr or .Fn win_wchstr causes undefined results. The use of .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr or .Fn win_wchnstr , respectively, is recommended. .SH "SEE ALSO" in_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3in_wchnstr(3X)\f1:\0\0\f4in_wchnstr()\f1, \f4in_wchstr()\f1, \f4mvin_wchnstr()\f1, \f4mvin_wchstr()\f1, \f4mvwin_wchnstr()\f1, \n\f4mvwin_wchstr()\f1, \f4win_wchnstr()\f1, \f4win_wchstr()\f1\n@@@input an array of complex characters and renditions from a window .\" toc@\f4in_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" .\" index@\f4in_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4in_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1array of complex characters and renditions, input from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1window, input an array of complex characters and renditions from@@@\f3in_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, input an array of, from a window@@@\f3in_wchnstr(3X)\f1 .\" .\" links@in_wchnstr.3x in_wchstr.3x .\" links@in_wchnstr.3x mvin_wchstr.3x .\" links@in_wchnstr.3x mvin_wchnstr.3x .\" links@in_wchnstr.3x mvwin_wchstr.3x .\" links@in_wchnstr.3x mvwin_wchnstr.3x .\" links@in_wchnstr.3x win_wchstr.3x .\" links@in_wchnstr.3x win_wchnstr.3x .\" .\" fileset_database@in_wchnstr.3x CURS-ENG-A-MAN .\" $Header: inch.3x,v 76.2 95/08/01 11:18:42 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH inch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inch, mvinch, mvwinch, winch \(em input a single-byte character and rendition from a window .SH SYNOPSIS .C "#include " .P .C "chtype inch(void);" .P .C "chtype mvinch(int \f2y\fP, int \f2x\fP);" .P .C "chtype mvwinch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "chtype winch(WINDOW *\f2win\fP);" .SH DESCRIPTION These functions return the character and rendition, of type \f2chtype\f1, at the current or specified position in the current or specified window. .SH "RETURN VALUE" Upon successful completion, the functions return the specified character and rendition. Otherwise, they return (\f3chtype\fP)ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn inch function is explicitly declared as \f3void\f1. .\" .\" toc@\f3inch(3X)\f1:\0\0\f4inch()\f1, \f4mvinch()\f1, \f4mvwinch()\f1, \f4winch\f1@@@input a single-byte character and rendition from a window .\" toc@\f4mvinch()\f1: input a single-byte character and rendition from a window@@@see \f3inch(3X)\f1 .\" toc@\f4mvwinch()\f1: input a single-byte character and rendition from a window@@@see \f3inch(3X)\f1 .\" toc@\f4winch()\f1: input a single-byte character and rendition from a window@@@see \f3inch(3X)\f1 .\" .\" index@\f4inch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f4mvinch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f4mvwinch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f4winch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f1input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f1single-byte character and rendition, input from a window@@@\f3inch(3X)\f1 .\" index@\f1window, input a single-byte character and rendition from@@@\f3inch(3X)\f1 .\" index@\f1character and rendition, input a single-byte from a window@@@\f3inch(3X)\f1 .\" .\" links@inch.3x mvinch.3x .\" links@inch.3x mvwinch.3x .\" links@inch.3x winch.3x .\" .\" fileset_database@inch.3x CURS-ENG-A-MAN .\" $Header: inchnstr.3x,v 76.2 95/08/01 11:20:07 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH inchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inchnstr, inchstr, mvinchnstr, mvinchstr, mvwinchnstr, mvwinchstr, winchnstr, winchstr \(em input an array of single-byte characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int inchnstr(chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int inchstr(chtype *\f2chstr\fP);" .P .C "int mvinchnstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvinchstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int mvwinchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvwinchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int winchnstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int winchstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP);" .SH DESCRIPTION These functions place characters and renditions from the current or specified window into the array pointed to by \f2chstr\f1, starting at the current or specified position and ending at the end of the line. .P The .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr and .Fn winchnstr functions store at most \f2n\f1 elements from the current or specified window into the array pointed to by \f2chstr\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2chstr\f1 with .CR inchstr() , .CR mvinchstr() , .Fn mvwinchstr or .Fn winchstr causes undefined results. The use of .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr or .CR winchnstr() , respectively, is recommended. .SH "SEE ALSO" inch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3inchnstr(3X)\f1:\0\0\f4inchnstr()\f1, \f4inchstr()\f1, \f4mvinchnstr()\f1, \f4mvinchstr()\f1, \f4mvwinchnstr()\f1, \f4mvwinchstr()\f1, \n\f4winchnstr()\f1, \f4winchstr()\f1@@@input an array of single-byte characters and renditions from a window .\" toc@\f4inchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" .\" index@\f4inchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4inchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1array of single-byte characters and renditions, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1single-byte characters and renditions, array of, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1characters and renditions, an array of single-byte, input from a window@@@\f3inchnstr(3X)\f1 .\" .\" links@inchnstr.3x inchstr.3x .\" links@inchnstr.3x mvinchstr.3x .\" links@inchnstr.3x mvinchnstr.3x .\" links@inchnstr.3x mvwinchstr.3x .\" links@inchnstr.3x mvwinchnstr.3x .\" links@inchnstr.3x winchstr.3x .\" links@inchnstr.3x winchnstr.3x .\" .\" fileset_database@inchnstr.3x CURS-ENG-A-MAN .\" $Header: inchnstr.3x,v 76.2 95/08/01 11:20:07 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH inchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inchnstr, inchstr, mvinchnstr, mvinchstr, mvwinchnstr, mvwinchstr, winchnstr, winchstr \(em input an array of single-byte characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int inchnstr(chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int inchstr(chtype *\f2chstr\fP);" .P .C "int mvinchnstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvinchstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int mvwinchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvwinchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int winchnstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int winchstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP);" .SH DESCRIPTION These functions place characters and renditions from the current or specified window into the array pointed to by \f2chstr\f1, starting at the current or specified position and ending at the end of the line. .P The .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr and .Fn winchnstr functions store at most \f2n\f1 elements from the current or specified window into the array pointed to by \f2chstr\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2chstr\f1 with .CR inchstr() , .CR mvinchstr() , .Fn mvwinchstr or .Fn winchstr causes undefined results. The use of .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr or .CR winchnstr() , respectively, is recommended. .SH "SEE ALSO" inch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3inchnstr(3X)\f1:\0\0\f4inchnstr()\f1, \f4inchstr()\f1, \f4mvinchnstr()\f1, \f4mvinchstr()\f1, \f4mvwinchnstr()\f1, \f4mvwinchstr()\f1, \n\f4winchnstr()\f1, \f4winchstr()\f1@@@input an array of single-byte characters and renditions from a window .\" toc@\f4inchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" .\" index@\f4inchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4inchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1array of single-byte characters and renditions, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1single-byte characters and renditions, array of, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1characters and renditions, an array of single-byte, input from a window@@@\f3inchnstr(3X)\f1 .\" .\" links@inchnstr.3x inchstr.3x .\" links@inchnstr.3x mvinchstr.3x .\" links@inchnstr.3x mvinchnstr.3x .\" links@inchnstr.3x mvwinchstr.3x .\" links@inchnstr.3x mvwinchnstr.3x .\" links@inchnstr.3x winchstr.3x .\" links@inchnstr.3x winchnstr.3x .\" .\" fileset_database@inchnstr.3x CURS-ENG-A-MAN .\" $Header: innstr.3x,v 76.2 95/08/01 11:22:05 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innstr, instr, mvinnstr, mvinstr, mvwinnstr, mvwinstr, winnstr, winstr \(em input a multi-byte character string from a window .SH SYNOPSIS .C "#include " .P .C "int innstr(char *\f2str\fP, int \f2n\fP);" .P .C "int instr(char *\f2str\fP);" .P .C "int mvinnstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvinstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int mvwinnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvwinstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int winnstr(WINDOW *\f2win\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int winstr(WINDOW *\f2win\fP, char *\f2str\fP);" .SH DESCRIPTION These functions place a string of characters from the current or specified window into the array pointed to by \f2str\fP, starting at the current or specified position and ending at the end of the line. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions store at most \f2n\f1 bytes in the string pointed to by \f2str\f1. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions will only store the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character the array is filled with complete characters. If the array is not large enough to contain any complete characters, the function fails. .SH "RETURN VALUE" Upon successful completion, .CR instr() , .CR mvinstr() , .Fn mvwinstr and .Fn winstr return OK. .P Upon successful completion, .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since multi-byte characters may be processed, there might not be a one-to-one correspondence between the number of column positions on the screen and the number of bytes returned. .P These functions do not return rendition information. .P Reading a line that overflows the array pointed to by \f2str\f1 with .CR instr() , .CR mvinstr() , .Fn mvwinstr or .Fn winstr causes undefined results. The use of .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr or .CR winnstr() , respectively, is recommended. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innstr(3X)\f1:\0\0\f4innstr()\f1, \f4instr()\f1, \f4mvinnstr()\f1, \f4mvinstr()\f1, \f4mvwinnstr()\f1, \f4mvwinstr()\f1, \f4winnstr()\f1, \n\f4winstr()\f1@@@input a multi-byte character string from a window .\" toc@\f4instr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" .\" index@\f4innstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4instr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1multi-byte character string, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1character string, multi-byte, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1window, input a multi-byte character string from@@@\f3innstr(3X)\f1 .\" .\" links@innstr.3x instr.3x .\" links@innstr.3x mvinstr.3x .\" links@innstr.3x mvinnstr.3x .\" links@innstr.3x mvwinstr.3x .\" links@innstr.3x mvwinnstr.3x .\" links@innstr.3x winstr.3x .\" links@innstr.3x winnstr.3x .\" .\" fileset_database@innstr.3x CURS-ENG-A-MAN .\" $Header: innwstr.3x,v 76.2 95/08/01 11:22:59 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innwstr, inwstr, mvinnwstr, mvinwstr, mvwinnwstr, mvwinwstr, winnwstr, winwstr \(em input a string of wide characters from a window .SH SYNOPSIS .C "#include " .P .C "int innwstr(wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int inwstr(wchar_t *\f2wstr\fP);" .P .C "int mvinnwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvinwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int mvwinnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwinwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int winnwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int winwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP);" .SH DESCRIPTION These functions place a string of \f3wchar_t\f1 characters from the current or specified window into the array pointed to by \f2wstr\f1 starting at the current or specified cursor position and ending at the end of the line. .P These functions will only store the entire wide character sequence associated with a spacing complex character. If the array is large enough to contain at least one complete spacing complex character, the array is filled with complete characters. If the array is not large enough to contain any complete characters this is an error. .P The .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr functions store at most \f2n\f1 characters in the array pointed to by \f2wstr\f1. .SH "RETURN VALUE" Upon successful completion, .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr and .Fn winwstr return OK. .P Upon successful completion, .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr or .Fn winwstr causes undefined results. The use of .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr or .CR winnwstr() , respectively, is recommended. .P These functions do not return rendition information. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innwstr(3X)\f1:\0\0\f4innwstr()\f1, \f4inwstr()\f1, \f4mvinnwstr()\f1, \f4mvinwstr()\f1, \f4mvwinnwstr()\f1, \f4mvwinwstr()\f1, \n\f4winnwstr()\f1, \f4winwstr()\f1@@@input a string of wide characters from a window .\" toc@\f4innwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4inwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" .\" index@\f4innwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4inwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1string of wide characters, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1wide characters, string of, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1window, input a string of wide characters from@@@\f3innwstr(3X)\f1 .\" index@\f1characters, wide, input a string of, from a window@@@\f3innwstr(3X)\f1 .\" .\" links@innwstr.3x inwstr.3x .\" links@innwstr.3x mvinnwstr.3x .\" links@innwstr.3x mvinwstr.3x .\" links@innwstr.3x mvwinnwstr.3x .\" links@innwstr.3x mvwinwstr.3x .\" links@innwstr.3x winnwstr.3x .\" links@innwstr.3x winwstr.3x .\" .\" fileset_database@innwstr.3x CURS-ENG-A-MAN .\" $Header: ins_nwstr.3x,v 76.2 95/08/01 11:23:53 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ins_nwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ins_nwstr, ins_wstr, mvins_nwstr, mvins_wstr, mvwins_nwstr, mvwins_wstr, wins_nwstr, wins_wstr \(em insert a wide-character string into a window .SH SYNOPSIS .C "#include " .P .C "int ins_nwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int ins_wstr(wchar_t *const \f2wstr\fP);" .P .C "int mvins_nwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvins_wstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwins_nwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwins_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int wins_nwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int wins_wstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions insert a .B wchar_t character string (as many .B wchar_t characters as will fit on the line) in the current or specified window immediately before the current or specified position. .P Any non-spacing characters in the string are associated with the first spacing character in the string that precedes the non-spacing characters. If the first character in the string is a non-spacing character, these functions will fail. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing. .P The .CR ins_nwstr() , .CR mvins_nwstr() , .Fn mvwins_nwstr and .Fn wins_nwstr functions insert at most \f2n\f1 \f3wchar_t\f1 characters. If \f2n\f1 is less than 1, then the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3ins_nwstr(3X)\f1:\0\0\f4ins_nwstr()\f1, \f4ins_wstr()\f1, \f4mvins_nwstr()\f1, \f4mvins_wstr()\f1, \f4mvwins_nwstr()\f1, \n\f4mvwins_wstr()\f1, \f4wins_nwstr()\f1, \f4wins_wstr()\f1@@@insert a wide-character string into a window .\" toc@\f4ins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" .\" index@\f4ins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4ins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1wide-character string, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1string of wide-character, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1window, insert a wide-character string into@@@\f3ins_nwstr(3X)\f1 .\" index@\f1character, insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" .\" links@ins_nwstr.3x ins_wstr.3x .\" links@ins_nwstr.3x mvins_nwstr.3x .\" links@ins_nwstr.3x mvins_wstr.3x .\" links@ins_nwstr.3x mvwins_nwstr.3x .\" links@ins_nwstr.3x mvwins_wstr.3x .\" links@ins_nwstr.3x wins_nwstr.3x .\" links@ins_nwstr.3x wins_wstr.3x .\" .\" fileset_database@ins_nwstr.3x CURS-ENG-A-MAN .\" $Header: ins_wch.3x,v 76.2 95/08/01 11:24:46 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ins_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ins_wch, mvins_wch, mvwins_wch, wins_wch \(em insert a complex character and rendition into a window .SH SYNOPSIS .C "#include " .P .C "int ins_wch(cchar_t *const \f2wch\fP);" .P .C "int wins_wch(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "int mvins_wch(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .P .C "int mvwins_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .SH DESCRIPTION These functions insert the complex character \f2wch\f1 with its rendition in the current or specified window at the current or specified cursor position. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing, with the exception that if a newline is inserted into the last line of a window and scrolling is not enabled, the behaviour is unspecified. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" For non-spacing characters, .Fn add_wch can be used to add the non-spacing characters to a spacing complex character already in the window. .SH "SEE ALSO" add_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3ins_wch(3X)\f1:\0\0\f4ins_wch()\f1, \f4mvins_wch()\f1, \f4mvwins_wch()\f1, \f4wins_wch()\f1\n@@@insert a complex character and rendition into a window .\" toc@\f4mvins_wch()\f1: insert a complex character and rendition into a window@@@see \f3ins_wch(3X)\f1 .\" toc@\f4mvwins_wch()\f1: insert a complex character and rendition into a window@@@see \f3ins_wch(3X)\f1 .\" toc@\f4wins_wch()\f1: insert a complex character and rendition into a window@@@see \f3ins_wch(3X)\f1 .\" .\" index@\f4ins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f4mvins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f4mvwins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f4wins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1complex character and rendition, insert into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1character and rendition, complex, insert into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1window, insert a complex character and rendition into@@@\f3ins_wch(3X)\f1 .\" .\" links@ins_wch.3x mvins_wch.3x .\" links@ins_wch.3x mvwins_wch.3x .\" links@ins_wch.3x wins_wch.3x .\" .\" fileset_database@ins_wch.3x CURS-ENG-A-MAN .\" $Header: ins_nwstr.3x,v 76.2 95/08/01 11:23:53 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ins_nwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ins_nwstr, ins_wstr, mvins_nwstr, mvins_wstr, mvwins_nwstr, mvwins_wstr, wins_nwstr, wins_wstr \(em insert a wide-character string into a window .SH SYNOPSIS .C "#include " .P .C "int ins_nwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int ins_wstr(wchar_t *const \f2wstr\fP);" .P .C "int mvins_nwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvins_wstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwins_nwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwins_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int wins_nwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int wins_wstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions insert a .B wchar_t character string (as many .B wchar_t characters as will fit on the line) in the current or specified window immediately before the current or specified position. .P Any non-spacing characters in the string are associated with the first spacing character in the string that precedes the non-spacing characters. If the first character in the string is a non-spacing character, these functions will fail. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing. .P The .CR ins_nwstr() , .CR mvins_nwstr() , .Fn mvwins_nwstr and .Fn wins_nwstr functions insert at most \f2n\f1 \f3wchar_t\f1 characters. If \f2n\f1 is less than 1, then the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3ins_nwstr(3X)\f1:\0\0\f4ins_nwstr()\f1, \f4ins_wstr()\f1, \f4mvins_nwstr()\f1, \f4mvins_wstr()\f1, \f4mvwins_nwstr()\f1, \n\f4mvwins_wstr()\f1, \f4wins_nwstr()\f1, \f4wins_wstr()\f1@@@insert a wide-character string into a window .\" toc@\f4ins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" .\" index@\f4ins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4ins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1wide-character string, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1string of wide-character, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1window, insert a wide-character string into@@@\f3ins_nwstr(3X)\f1 .\" index@\f1character, insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" .\" links@ins_nwstr.3x ins_wstr.3x .\" links@ins_nwstr.3x mvins_nwstr.3x .\" links@ins_nwstr.3x mvins_wstr.3x .\" links@ins_nwstr.3x mvwins_nwstr.3x .\" links@ins_nwstr.3x mvwins_wstr.3x .\" links@ins_nwstr.3x wins_nwstr.3x .\" links@ins_nwstr.3x wins_wstr.3x .\" .\" fileset_database@ins_nwstr.3x CURS-ENG-A-MAN .\" $Header: insch.3x,v 76.2 95/08/01 11:25:41 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insch, mvinsch, mvwinsch, winsch \(em insert a single-byte character and rendition into a window .SH SYNOPSIS .C "#include " .P .C "int insch(chtype \f2ch\fP);" .P .C "int mvinsch(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP);" .P .C "int mvwinsch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP);" .P .C "int winsch(WINDOW *\f2win\fP, chtype \f2ch\fP);" .SH DESCRIPTION These functions insert the character and rendition from \f2ch\f1 into the current or specified window at the current or specified position. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing, with the exception that if a newline is inserted into the last line of a window and scrolling is not enabled, the behaviour is unspecified. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" ins_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" toc@\f3insch(3X)\f1:\0\0\f4insch()\f1, \f4mvinsch()\f1, \f4mvwinsch()\f1, \f4winsch()\f1\n@@@insert a single-byte character and rendition into a window .\" toc@\f4mvinsch()\f1: insert a single-byte character and rendition into a window@@@see \f3insch(3X)\f1 .\" toc@\f4mvwinsch()\f1: insert a single-byte character and rendition into a window@@@see \f3insch(3X)\f1 .\" toc@\f4winsch()\f1: insert a single-byte character and rendition into a window@@@see \f3insch(3X)\f1 .\" .\" index@\f4insch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f4mvinsch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f4mvwinsch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f4winsch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f1insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f1single-byte character and rendition, insert into a window@@@\f3insch(3X)\f1 .\" index@\f1character and rendition, single-byte, insert into a window@@@\f3insch(3X)\f1 .\" index@\f1window, insert a single-byte character and rendition into@@@\f3insch(3X)\f1 .\" .\" links@insch.3x mvinsch.3x .\" links@insch.3x mvwinsch.3x .\" links@insch.3x winsch.3x .\" .\" fileset_database@insch.3x CURS-ENG-A-MAN .\" $Header: insnstr.3x,v 76.3 95/10/05 14:42:06 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insnstr, insstr, mvinsnstr, mvinsstr, mvwinsnstr, mvwinsstr, winsnstr, winsstr \(em insert a multi-byte character string into a window .SH SYNOPSIS .C "#include " .P .C "int insnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int insstr(char *const \f2str\fP);" .P .C "int mvinsnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvinsstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwinsnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwinsstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int winsnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int winsstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions insert a character string (as many characters as will fit on the line) before the current or specified position in the current or specified window. .P These functions do not advance the cursor position. These functions perform special-character processing. The .Fn innstr and .Fn innwstr functions perform wrapping. The .Fn instr and .Fn inswstr functions do not perform wrapping. .P The .CR insnstr() , .CR mvinsnstr() , .Fn mvwinsnstr and .Fn winsnstr functions insert .\" entire multi-byte characters contained in the first at most \f2n\f1 bytes. If \f2n\f1 is less than 1, the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since the string may contain multi-byte characters, there might not be a one-to-one correspondence between the number of column positions occupied by the characters and the number of bytes in the string. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3insnstr(3X)\f1:\0\0\f4insnstr()\f1, \f4insstr()\f1, \f4mvinsnstr()\f1, \f4mvinsstr()\f1, \f4mvwinsnstr()\f1, \f4mvwinsstr()\f1, \n\f4winsnstr()\f1, \f4winsstr()\f1@@@insert a multi-byte character into a window .\" toc@\f4insstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" .\" index@\f4insnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4insstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1multi-byte character, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1character, multi-byte, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1window, insert a multi-byte character into@@@\f3insnstr(3X)\f1 .\" .\" links@insnstr.3x insstr.3x .\" links@insnstr.3x mvinsnstr.3x .\" links@insnstr.3x mvinsstr.3x .\" links@insnstr.3x mvwinsnstr.3x .\" links@insnstr.3x mvwinsstr.3x .\" links@insnstr.3x winsnstr.3x .\" links@insnstr.3x winsstr.3x .\" .\" fileset_database@insnstr.3x CURS-ENG-A-MAN .\" $Header: insnstr.3x,v 76.3 95/10/05 14:42:06 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insnstr, insstr, mvinsnstr, mvinsstr, mvwinsnstr, mvwinsstr, winsnstr, winsstr \(em insert a multi-byte character string into a window .SH SYNOPSIS .C "#include " .P .C "int insnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int insstr(char *const \f2str\fP);" .P .C "int mvinsnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvinsstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwinsnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwinsstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int winsnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int winsstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions insert a character string (as many characters as will fit on the line) before the current or specified position in the current or specified window. .P These functions do not advance the cursor position. These functions perform special-character processing. The .Fn innstr and .Fn innwstr functions perform wrapping. The .Fn instr and .Fn inswstr functions do not perform wrapping. .P The .CR insnstr() , .CR mvinsnstr() , .Fn mvwinsnstr and .Fn winsnstr functions insert .\" entire multi-byte characters contained in the first at most \f2n\f1 bytes. If \f2n\f1 is less than 1, the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since the string may contain multi-byte characters, there might not be a one-to-one correspondence between the number of column positions occupied by the characters and the number of bytes in the string. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3insnstr(3X)\f1:\0\0\f4insnstr()\f1, \f4insstr()\f1, \f4mvinsnstr()\f1, \f4mvinsstr()\f1, \f4mvwinsnstr()\f1, \f4mvwinsstr()\f1, \n\f4winsnstr()\f1, \f4winsstr()\f1@@@insert a multi-byte character into a window .\" toc@\f4insstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" .\" index@\f4insnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4insstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1multi-byte character, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1character, multi-byte, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1window, insert a multi-byte character into@@@\f3insnstr(3X)\f1 .\" .\" links@insnstr.3x insstr.3x .\" links@insnstr.3x mvinsnstr.3x .\" links@insnstr.3x mvinsstr.3x .\" links@insnstr.3x mvwinsnstr.3x .\" links@insnstr.3x mvwinsstr.3x .\" links@insnstr.3x winsnstr.3x .\" links@insnstr.3x winsstr.3x .\" .\" fileset_database@insnstr.3x CURS-ENG-A-MAN .\" $Header: innstr.3x,v 76.2 95/08/01 11:22:05 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innstr, instr, mvinnstr, mvinstr, mvwinnstr, mvwinstr, winnstr, winstr \(em input a multi-byte character string from a window .SH SYNOPSIS .C "#include " .P .C "int innstr(char *\f2str\fP, int \f2n\fP);" .P .C "int instr(char *\f2str\fP);" .P .C "int mvinnstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvinstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int mvwinnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvwinstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int winnstr(WINDOW *\f2win\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int winstr(WINDOW *\f2win\fP, char *\f2str\fP);" .SH DESCRIPTION These functions place a string of characters from the current or specified window into the array pointed to by \f2str\fP, starting at the current or specified position and ending at the end of the line. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions store at most \f2n\f1 bytes in the string pointed to by \f2str\f1. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions will only store the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character the array is filled with complete characters. If the array is not large enough to contain any complete characters, the function fails. .SH "RETURN VALUE" Upon successful completion, .CR instr() , .CR mvinstr() , .Fn mvwinstr and .Fn winstr return OK. .P Upon successful completion, .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since multi-byte characters may be processed, there might not be a one-to-one correspondence between the number of column positions on the screen and the number of bytes returned. .P These functions do not return rendition information. .P Reading a line that overflows the array pointed to by \f2str\f1 with .CR instr() , .CR mvinstr() , .Fn mvwinstr or .Fn winstr causes undefined results. The use of .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr or .CR winnstr() , respectively, is recommended. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innstr(3X)\f1:\0\0\f4innstr()\f1, \f4instr()\f1, \f4mvinnstr()\f1, \f4mvinstr()\f1, \f4mvwinnstr()\f1, \f4mvwinstr()\f1, \f4winnstr()\f1, \n\f4winstr()\f1@@@input a multi-byte character string from a window .\" toc@\f4instr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" .\" index@\f4innstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4instr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1multi-byte character string, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1character string, multi-byte, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1window, input a multi-byte character string from@@@\f3innstr(3X)\f1 .\" .\" links@innstr.3x instr.3x .\" links@innstr.3x mvinstr.3x .\" links@innstr.3x mvinnstr.3x .\" links@innstr.3x mvwinstr.3x .\" links@innstr.3x mvwinnstr.3x .\" links@innstr.3x winstr.3x .\" links@innstr.3x winnstr.3x .\" .\" fileset_database@innstr.3x CURS-ENG-A-MAN .\" $Header: innwstr.3x,v 76.2 95/08/01 11:22:59 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innwstr, inwstr, mvinnwstr, mvinwstr, mvwinnwstr, mvwinwstr, winnwstr, winwstr \(em input a string of wide characters from a window .SH SYNOPSIS .C "#include " .P .C "int innwstr(wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int inwstr(wchar_t *\f2wstr\fP);" .P .C "int mvinnwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvinwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int mvwinnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwinwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int winnwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int winwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP);" .SH DESCRIPTION These functions place a string of \f3wchar_t\f1 characters from the current or specified window into the array pointed to by \f2wstr\f1 starting at the current or specified cursor position and ending at the end of the line. .P These functions will only store the entire wide character sequence associated with a spacing complex character. If the array is large enough to contain at least one complete spacing complex character, the array is filled with complete characters. If the array is not large enough to contain any complete characters this is an error. .P The .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr functions store at most \f2n\f1 characters in the array pointed to by \f2wstr\f1. .SH "RETURN VALUE" Upon successful completion, .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr and .Fn winwstr return OK. .P Upon successful completion, .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr or .Fn winwstr causes undefined results. The use of .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr or .CR winnwstr() , respectively, is recommended. .P These functions do not return rendition information. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innwstr(3X)\f1:\0\0\f4innwstr()\f1, \f4inwstr()\f1, \f4mvinnwstr()\f1, \f4mvinwstr()\f1, \f4mvwinnwstr()\f1, \f4mvwinwstr()\f1, \n\f4winnwstr()\f1, \f4winwstr()\f1@@@input a string of wide characters from a window .\" toc@\f4innwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4inwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" .\" index@\f4innwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4inwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1string of wide characters, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1wide characters, string of, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1window, input a string of wide characters from@@@\f3innwstr(3X)\f1 .\" index@\f1characters, wide, input a string of, from a window@@@\f3innwstr(3X)\f1 .\" .\" links@innwstr.3x inwstr.3x .\" links@innwstr.3x mvinnwstr.3x .\" links@innwstr.3x mvinwstr.3x .\" links@innwstr.3x mvwinnwstr.3x .\" links@innwstr.3x mvwinwstr.3x .\" links@innwstr.3x winnwstr.3x .\" links@innwstr.3x winwstr.3x .\" .\" fileset_database@innwstr.3x CURS-ENG-A-MAN .\" $Header: mvprintw.3x,v 76.2 95/08/01 11:56:52 ssa Exp $ .TA m .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH mvprintw 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mvprintw, mvwprintw, printw, wprintw \(em print formatted output in window .SH SYNOPSIS .C "#include " .P .C "int mvprintw(int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int mvwprintw(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int printw(char *\f2fmt\fP, ...);" .P .C "int wprintw(WINDOW *\f2win\fP, char *\f2fmt\fP, ...);" .SH DESCRIPTION The .CR mvprintw() , .CR mvwprintw() , .Fn printw and .Fn wprintw functions are analogous to .CR printf() . The effect of these functions is as though .Fn sprintf were used to format the string, and then .Fn waddstr were used to add that multi-byte string to the current or specified window at the current or specified cursor position. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" addnstr(), fprintf() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity and its name is changed from .Fn printw to .CR mvprintw() . .\" .\" toc@\f3mvprintw(3X)\f1:\0\0\f4mvprintw()\f1, \f4mvwprintw()\f1, \f4printw()\f1, \f4wprintw\f1@@@print formatted output in window .\" toc@\f4mvwprintw()\f1: print formatted output in window@@@see \f3mvprintw(3X)\f1 .\" toc@\f4printw()\f1: print formatted output in window@@@see \f3mvprintw(3X)\f1 .\" toc@\f4wprintw()\f1: print formatted output in window@@@see \f3mvprintw(3X)\f1 .\" .\" index@\f4mvprintw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f4mvwprintw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f4printw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f4wprintw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f1print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f1formatted output, print in window@@@\f3mvprintw(3X)\f1 .\" index@\f1output, formatted, print in window@@@\f3mvprintw(3X)\f1 .\" index@\f1window, print formatted output in@@@\f3mvprintw(3X)\f1 .\" .\" links@mvprintw.3x mvwprintw.3x .\" links@mvprintw.3x printw.3x .\" links@mvprintw.3x wprintw.3x .\" .\" fileset_database@mvprintw.3x CURS-ENG-A-MAN .\" $Header: mvscanw.3x,v 76.2 95/08/01 11:58:38 ssa Exp $ .TA m .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH mvscanw 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mvscanw, mvwscanw, scanw, wscanw \(em convert formatted input from a window .SH SYNOPSIS .C "#include " .P .C "int mvscanw(int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int mvwscanw(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int scanw(char *\f2fmt\fP, ...);" .P .C "int wscanw(WINDOW *\f2win\fP, char *\f2fmt\fP, ...);" .SH DESCRIPTION These functions are similar to .CR scanf() . Their effect is as though .Fn mvwgetstr were called to get a multi-byte character string from the current or specified window at the current or specified cursor position, and then .Fn sscanf were used to interpret and convert that string. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" getnstr(), printw(), fscanf() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), wcstombs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity and its name is changed from .Fn scanw to .CR mvscanw() . .\" .\" toc@\f3mvscanw(3X)\f1:\0\0\f4mvscanw()\f1, \f4mvwscanw()\f1, \f4scanw()\f1, \f4wscanw()\f1@@@convert formatted input from a window .\" toc@\f4mvwscanw()\f1: convert formatted input from a window@@@see \f3mvscanw(3X)\f1 .\" toc@\f4scanw()\f1: convert formatted input from a window@@@see \f3mvscanw(3X)\f1 .\" toc@\f4wscanw()\f1: convert formatted input from a window@@@see \f3mvscanw(3X)\f1 .\" .\" index@\f4mvscanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f4mvwscanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f4scanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f4wscanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1formatted input, convert, from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1input, convert formatted, from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1window, convert formatted input from@@@\f3mvscanw(3X)\f1 .\" .\" links@mvscanw.3x mvwscanw.3x .\" links@mvscanw.3x scanw.3x .\" links@mvscanw.3x wscanw.3x .\" .\" fileset_database@mvscanw.3x CURS-ENG-A-MAN .\" $Header: hline.3x,v 76.2 95/08/01 11:07:23 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline, mvhline, mvvline, mvwhline, mvwvline, vline, whline, wvline \(em draw lines from single-byte characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvhline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvvline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwhline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwvline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int vline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int whline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int wvline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline() , .CR mvhline() , .Fn mvwhline and .Fn whline functions draw a line proceeding toward the last column of the same line. .P The .CR vline() , .CR mvvline() , .Fn mvwvline and .Fn wvline functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" border(), box(), hline_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline(3X)\f1:\0\0\f4hline()\f1, \f4mvhline()\f1, \f4mvvline()\f1, \f4mvwhline()\f1, \f4mvwvline()\f1, \f4vline()\f1, \f4whline()\f1, \f4wvline()\f1\n@@@draw lines from single-byte characters and renditions .\" toc@\f4mvhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4vline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4whline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4wvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" .\" index@\f4hline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4vline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4whline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4wvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1lines, draw from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1single-byte characters and renditions, draw lines from@@@\f3hline(3X)\f1 .\" index@\f1characters and renditions, draw lines from single-byte@@@\f3hline(3X)\f1 .\" index@\f1renditions and characters, draw lines from single-byte@@@\f3hline(3X)\f1 .\" .\" links@hline.3x mvhline.3x .\" links@hline.3x mvvline.3x .\" links@hline.3x mvwhline.3x .\" links@hline.3x mvwvline.3x .\" links@hline.3x vline.3x .\" links@hline.3x whline.3x .\" links@hline.3x wvline.3x .\" .\" fileset_database@hline.3x CURS-ENG-A-MAN .\" $Header: hline_set.3x,v 76.2 95/08/01 11:08:14 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline_set 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline_set, mvhline_set, mvvline_set, mvwhline_set, mvwvline_set, vline_set, whline_set, wvline_set \(em draw lines from complex characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvhline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvvline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwhline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwvline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int vline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int whline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int wvline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline_set() , .CR mvhline_set() , .Fn mvwhline_set and .Fn whline_set functions draw a line proceeding toward the last column of the same line. .P The .CR vline_set() , .CR mvvline_set() , .Fn mvwvline_set and .Fn wvline_set functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" border_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline_set(3X)\f1:\0\0\f4hline_set()\f1, \f4mvhline_set()\f1, \f4mvvline_set()\f1, \f4mvwhline_set()\f1, \f4mvwvline_set()\f1, \n\f4vline_set()\f1, \f4whline_set()\f1, \f4wvline_set()\f1@@@draw lines from complex characters and renditions .\" toc@\f4mvhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4vline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4whline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4wvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" .\" index@\f4hline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4vline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4whline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4wvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1lines, draw from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1complex characters and renditions, draw lines from@@@\f3hline_set(3X)\f1 .\" index@\f1characters and renditions, complex, draw lines from@@@\f3hline_set(3X)\f1 .\" .\" links@hline_set.3x mvhline_set.3x .\" links@hline_set.3x mvvline_set.3x .\" links@hline_set.3x mvwhline_set.3x .\" links@hline_set.3x mvwvline_set.3x .\" links@hline_set.3x vline_set.3x .\" links@hline_set.3x whline_set.3x .\" links@hline_set.3x wvline_set.3x .\" .\" fileset_database@hline_set.3x CURS-ENG-A-MAN .\" $Header: napms.3x,v 76.2 95/08/01 14:26:48 ssa Exp $ .TA n .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH napms 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME napms \(em suspend the calling process .SH SYNOPSIS .C "#include " .P .C "int napms(int \f2ms\fP);" .SH DESCRIPTION The .Fn napms function takes at least \f2ms\f1 milliseconds to return. .SH "RETURN VALUE" The .Fn napms function returns OK. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" A more reliable method of achieving a timed delay is the .Fn usleep function. .SH "SEE ALSO" delay_output(), usleep() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4napms()\f1 \- suspend the calling process@@@\f3napms(3X)\f1 .\" index@\f1suspend the calling process@@@\f3napms(3X)\f1 .\" index@\f1calling process, suspend@@@\f3napms(3X)\f1 .\" index@\f1process, suspend the calling process@@@\f3napms(3X)\f1 .\" .\" toc@\f3napms(3X)\f1:\0\0\f4napms()\f1@@@suspend the calling process .\" .\" fileset_database@napms.3x CURS-ENG-A-MAN .\" $Header: ndbm.3x,v 78.1 96/02/13 14:30:00 ssa Exp $ .TA n .TH ndbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr \- database subroutines .SH SYNOPSIS .C "#include " .PP .C "DBM *dbm_open(const char *file, int flags, mode_t mode);" .PP .C "void dbm_close(DBM *db);" .PP .C "datum dbm_fetch(DBM *db, datum key);" .PP .C "int dbm_store(DBM *db, datum key, datum content, int flags);" .PP .C "int dbm_delete(DBM *db, datum key);" .PP .C "datum dbm_firstkey(DBM *db);" .PP .C "datum dbm_nextkey(DBM *db);" .PP .C "int dbm_error(DBM *db);" .PP .C "int dbm_clearerr(DBM *db);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can access a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .IR dptr . Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbm_open . This will open and/or create the files .IC file .dir and .IC file .pag depending on the .I flags parameter (see .IR open (2)). .PP Once open, the data stored under a key is accessed by .C dbm_fetch and data is placed under a key by .CR dbm_store . The .I flags field can be either .C DBM_INSERT or .CR DBM_REPLACE . .C DBM_INSERT can only insert new entries into the database, and cannot change an existing entry having the same key. .C DBM_REPLACE replaces an existing entry if it has the same key. A key (and its associated contents) is deleted by .CR dbm_delete . A linear pass through all keys in a database can be made in (apparently) random order by use of .C dbm_firstkey and .CR dbm_nextkey . .C dbm_firstkey returns the first key in the database. .C dbm_nextkey returns the next key in the database, The following code can be used to traverse the database: .IP .C "for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))" .PP .C dbm_error returns non-zero when an error has occurred reading or writing the database. .C dbm_clearerr resets the error condition on the named database. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .I dptr. If .CR dbm_store is called with a .I flags value of .C DBM_INSERT and finds an existing entry with the same key, a value of .C 1 is returned. If a call to .CR dbm_store results in an internal block overflow, a value of -2 is returned. .SH WARNINGS The .I ndbm functions provided in this library should not be confused in any way with those of a general-purpose database management system. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful database functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The pointer to data that is returned from these functions are not aligned. This can cause problems if the block contains data that must be aligned to a specific boundry. If the block contains data that must be aligned, the block should be copied to an appropriately aligned area. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C dbm_store returns an error in the event that a disk block fills with inseparable data. .PP .C dbm_delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C dbm_firstkey and .C dbm_nextkey depends on a hashing function, not on anything interesting. .PP A .C dbm_store or .C dbm_delete during a pass through the keys by .C dbm_firstkey and .C dbm_nextkey may yield unexpected results. .SH AUTHOR .IR ndbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO dbm(3X). .\" index@\f4dbm_clearerr\f1 \- reset error condition on named database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_close\f1 \- close an open database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_delete\f1 \- delete a database key and associated contents@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_error\f1 \- error in reading or writing in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_fetch\f1 \- access a database entry under a key@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_firstkey\f1 \- get first key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_nextkey\f1 \- get next key in a database@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_open\f1 \- open a database for access@@@\f3ndbm(3X)\f1 .\" index@\f4dbm_store\f1 \- store an entry under a key in a database@@@\f3ndbm(3X)\f1 .\" index@database subroutines (new multiple database version)@@@\f3ndbm(3X)\f1 .\" index@subroutines, database (new multiple database version)@@@\f3ndbm(3X)\f1 .\" .\" toc@\f3ndbm(3X)\f1:\0\0\f4dbm_open()\f1, \f4dbm_close()\f1, \f4dbm_fetch()\f1, \f4dbm_store()\f1, \f4dbm_delete()\f1, \n\f4dbm_firstkey()\f1, \f4dbm_nextkey()\f1, \f4dbm_error()\f1, \f4dbm_clearerr()\f1@@@database subroutines .\" toc@\f4dbm_open\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_close\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_fetch\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_store\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_delete\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_firstkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_nextkey\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_error\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" toc@\f4dbm_clearerr\f1:\0\0database subroutines@@@see \f3ndbm(3X)\f1 .\" .\" links@ndbm.3x dbm_open.3x .\" links@ndbm.3x dbm_close.3x .\" links@ndbm.3x dbm_fetch.3x .\" links@ndbm.3x dbm_store.3x .\" links@ndbm.3x dbm_delete.3x .\" links@ndbm.3x dbm_firstke.3x .\" links@ndbm.3x dbm_nextkey.3x .\" links@ndbm.3x dbm_error.3x .\" links@ndbm.3x dbm_clearer.3x .\" .\" fileset_database@ndbm.3x PROGRAMING-MAN .\" $Header: net_aton.3c,v 72.4 94/09/21 13:49:39 ssa Exp $ .TA n .TH net_aton 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME net_aton(\|), net_ntoa(\|) \- network station address string conversion routines .SH SYNOPSIS .C "#include " .PP .C "char *net_aton(char *dstr, const char *sstr, int size);" .PP .C "char *net_ntoa(char *dstr, const char *sstr, int size);" .SH DESCRIPTION .C net_aton() and .C net_ntoa() translate station addresses between hexadecimal, octal or decimal, and binary formats: .RS .TP 20 .C net_aton() converts a hexadecimal, octal or decimal address to a binary address; .TP .C net_ntoa() converts a binary address to an ASCII hexadecimal address. .RE .PP Both routines are provided in the standard C library and are loaded automatically during compilation. .SS net_aton Parameters The following parameters are used by .CR net_aton() : .RS .TP 10 .I dstr Pointer to the binary address returned by the function. .TP .I sstr Pointer to a null-terminated ASCII form of a station address (Ethernet or IEEE 802.3). This address can be an octal, decimal, or hexadecimal number as used in the C language (in other words, a leading 0x or 0X implies hexadecimal; a leading 0 implies octal; otherwise, the number is interpreted as decimal). .TP .I size Length of the binary address to be returned in .I dstr. The length is 6 for Ethernet/\c IEEE 802.3 addresses. .RE .SS net_ntoa Parameters .C net_ntoa() converts a 48-bit binary station address to its ASCII hexadecimal equivalent. The following parameters are used by .CR net_ntoa() : .RS .TP 10 .I dstr Pointer to the ASCII hexadecimal address returned by the function. .I dstr is null-terminated and padded with leading zeroes if necessary. .I dstr must be at least (2 \(mu .I size + 3) bytes long to accommodate the size of the converted address. .TP .I sstr Pointer to a station address in its binary form. .TP .I size Length of .IR sstr . .RE .SH RETURN VALUE .CR net_aton() and .CR net_ntoa() return NULL if any error occurs. .SH EXAMPLES .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 #include #define destination_addr "0x00DD0002AD00" ... struct fis arg; char str[16]; ... (void) net_aton(arg.value.s, destination_addr, 6); /* arg.value.s = "<48-bit binary value>" */ (void) net_ntoa(str, arg.value.s, 6); /* str = "0x00DD0002AD00" */ .ft .ps .fi .SH AUTHOR .CR net_aton() was developed by HP. .SH SEE ALSO lan(7). .\" .\" index@\f4net_aton()\f1 \- network station address string conversion routines@@@\f3net_aton(3C)\f1 .\" index@\f4net_ntoa()\f1 \- network station address string conversion routines@@@\f3net_aton(3C)\f1 .\" index@\f1network station address string conversion routines@@@\f3net_aton(3C)\f1 .\" index@\f1station address string conversion routines, network@@@\f3net_aton(3C)\f1 .\" index@\f1address string conversion routines, network station@@@\f3net_aton(3C)\f1 .\" index@\f1string conversion routines, network station address@@@\f3net_aton(3C)\f1 .\" index@\f1conversion routines, network station address string@@@\f3net_aton(3C)\f1 .\" index@\f1routines, network station address string conversion@@@\f3net_aton(3C)\f1 .\" .\" toc@\f3net_aton(3C)\f1:\0\0\f4net_aton()\f1, \f4net_ntoa()\f1@@@network station address string conversion routines .\" toc@\f4net_ntoa()\f1: network station address string conversion routines@@@see \f3net_aton(3C)\f1 .\" .\" links@net_aton.3c net_ntoa.3c .\" .\" fileset_database@net_aton.3c INETSVCS-MAN .\" $Header: net_aton.3c,v 72.4 94/09/21 13:49:39 ssa Exp $ .TA n .TH net_aton 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME net_aton(\|), net_ntoa(\|) \- network station address string conversion routines .SH SYNOPSIS .C "#include " .PP .C "char *net_aton(char *dstr, const char *sstr, int size);" .PP .C "char *net_ntoa(char *dstr, const char *sstr, int size);" .SH DESCRIPTION .C net_aton() and .C net_ntoa() translate station addresses between hexadecimal, octal or decimal, and binary formats: .RS .TP 20 .C net_aton() converts a hexadecimal, octal or decimal address to a binary address; .TP .C net_ntoa() converts a binary address to an ASCII hexadecimal address. .RE .PP Both routines are provided in the standard C library and are loaded automatically during compilation. .SS net_aton Parameters The following parameters are used by .CR net_aton() : .RS .TP 10 .I dstr Pointer to the binary address returned by the function. .TP .I sstr Pointer to a null-terminated ASCII form of a station address (Ethernet or IEEE 802.3). This address can be an octal, decimal, or hexadecimal number as used in the C language (in other words, a leading 0x or 0X implies hexadecimal; a leading 0 implies octal; otherwise, the number is interpreted as decimal). .TP .I size Length of the binary address to be returned in .I dstr. The length is 6 for Ethernet/\c IEEE 802.3 addresses. .RE .SS net_ntoa Parameters .C net_ntoa() converts a 48-bit binary station address to its ASCII hexadecimal equivalent. The following parameters are used by .CR net_ntoa() : .RS .TP 10 .I dstr Pointer to the ASCII hexadecimal address returned by the function. .I dstr is null-terminated and padded with leading zeroes if necessary. .I dstr must be at least (2 \(mu .I size + 3) bytes long to accommodate the size of the converted address. .TP .I sstr Pointer to a station address in its binary form. .TP .I size Length of .IR sstr . .RE .SH RETURN VALUE .CR net_aton() and .CR net_ntoa() return NULL if any error occurs. .SH EXAMPLES .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 #include #define destination_addr "0x00DD0002AD00" ... struct fis arg; char str[16]; ... (void) net_aton(arg.value.s, destination_addr, 6); /* arg.value.s = "<48-bit binary value>" */ (void) net_ntoa(str, arg.value.s, 6); /* str = "0x00DD0002AD00" */ .ft .ps .fi .SH AUTHOR .CR net_aton() was developed by HP. .SH SEE ALSO lan(7). .\" .\" index@\f4net_aton()\f1 \- network station address string conversion routines@@@\f3net_aton(3C)\f1 .\" index@\f4net_ntoa()\f1 \- network station address string conversion routines@@@\f3net_aton(3C)\f1 .\" index@\f1network station address string conversion routines@@@\f3net_aton(3C)\f1 .\" index@\f1station address string conversion routines, network@@@\f3net_aton(3C)\f1 .\" index@\f1address string conversion routines, network station@@@\f3net_aton(3C)\f1 .\" index@\f1string conversion routines, network station address@@@\f3net_aton(3C)\f1 .\" index@\f1conversion routines, network station address string@@@\f3net_aton(3C)\f1 .\" index@\f1routines, network station address string conversion@@@\f3net_aton(3C)\f1 .\" .\" toc@\f3net_aton(3C)\f1:\0\0\f4net_aton()\f1, \f4net_ntoa()\f1@@@network station address string conversion routines .\" toc@\f4net_ntoa()\f1: network station address string conversion routines@@@see \f3net_aton(3C)\f1 .\" .\" links@net_aton.3c net_ntoa.3c .\" .\" fileset_database@net_aton.3c INETSVCS-MAN .\" $Header: secure_rpc.3c,v 74.1 95/05/10 21:12:12 ssa Exp $ .TA s .TH secure_rpc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME secure_rpc(), authdes_create(), authdes_getucred(), get_myaddress(), getnetname(), host2netname(), key_decryptsession(), key_encryptsession(), key_gendes(), key_setsecret(), netname2host(), netname2user(), user2netname() \- library routines for secure remote procedure calls .SH DESCRIPTION .LP .C RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .LP .C RPC allows various authentication flavors. The .B authdes_getucred() and .B authdes_create() routines implement the .B DES authentication flavor. See .BR rpc_clnt_auth (3C) for routines relating to the .B AUTH_NONE and .B AUTH_UNIX authentication types. .IP Note: Both the client and server should have their keys in the .BR publickey (5) database. Also, the keyserver daemon .BR keyserv (1M) must be running on both the client and server hosts for the .B DES authentication system to work. .SS Routines .LP The following routines require that the header .BR be included. .PP The .B AUTH data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "AUTH *" .C "authdes_create(netname, window, syncaddr, deskeyp)" .C "char *netname;" .C "unsigned window;" .C "struct sockaddr_in *syncaddr;" .C "des_block *deskeyp;" .fi .IP .B authdes_create() is an interface to the .B RPC secure authentication system, known as .B DES authentication. .IP Used on the client side, .B authdes_create() returns an authentication handle that enables the use of the secure authentication system. The first parameter .I netname is the network name of the owner of the server process. This field usually represents a .I host derived from the utility routine .BR host2netname() , but could also represent a user name using .BR user2netname() . The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third parameter .I syncaddr is optional. If it is .B NULL, then the authentication system will assume that the local clock is always in sync with the server's clock, and will not attempt to synchronize with the server. If an address is supplied then the system will use it for consulting the remote time service whenever resynchronization is required. This parameter is usually the address of the .B RPC server itself. The final parameter .I deskeyp is also optional. If it is .B NULL, then the authentication system will generate a random .B DES key to be used for the encryption of credentials. If .I deskeyp is supplied then it is used instead. .PP .nf .C "int" .C "authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)" .C "struct authdes_cred *adc;" .C "short *uidp, *gidp, *gidlenp;" .C "int *gidlistp;" .fi .IP .BR authdes_getucred() , is a .B DES authentication routine used by the server for converting a .B DES credential, which is operating system independent, into a .B UNIX credential. .I uidp points to the user .B ID of the user associated with .IR adc ; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. .br .ne 5 .IP This routine differs from the utility routine .B netname2user() in that .B authdes_getucred() pulls its information from a cache, and does not have to do a .B NIS name service lookup every time it is called to get its information. Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "void" .C "get_myaddress(addr)" .C "struct sockaddr_in *addr;" .fi .IP Return the machine's .B IP address in .IR addr. The port number is always set to .BR htons(PMAPPORT) . .PP .nf .C "int" .C "getnetname(netname)" .C "char netname[MAXNETNAMELEN];" .fi .IP Return the unique, operating-system independent netname of the caller in the fixed-length array .IR netname . Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "int" .C "host2netname(netname, host, domain)" .C "char netname[MAXNETNAMELEN];" .C "char *host;" .C "char *domain;" .fi .IP Convert from a domain-specific hostname to an operating-system independent netname. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . This routine should be used if the owner of the server process is the machine that is, the user with effective user .B ID zero. Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2host() . .PP .nf .C "int" .C "key_decryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP An interface routine to the keyserver daemon, which is associated with .B RPC's secure authentication system ( .B DES authentication). User programs rarely need to call it, or its associated routines .BR key_encryptsession() , .B key_gendes() and .BR key_setsecret() . System commands such as .B login and the .B RPC library are the main clients of these four routines. .IP .B key_decryptsession() takes the netname of a server and a .B DES key, and decrypts the key by using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_encryptsession() . .PP .nf .C "int" .C "key_encryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It takes the netname of the server and a .B DES key, and encrypts it using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_decryptsession() . .PP .nf .C "int" .C "key_gendes(deskeyp)" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It is used to ask the keyserver for a secure conversation key. Choosing one at random is usually not good enough, because the common ways of choosing random numbers, such as using the current time, are very easy to guess. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "key_setsecret(keyp)" .C "char *keyp;" .fi .IP A keyserver interface routine. It is used to set the secret key for the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "netname2host(netname, host, hostlen)" .C "char *netname;" .C "char *host;" .C "int hostlen;" .fi .IP Convert an operating-system independent netname to a domain-specific hostname. .I hostlen specifies the size of the array pointed to by .I host. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR host2netname() . .PP .nf .C "int" .C "netname2user(netname, uidp, gidp, gidlenp, gidlistp)" .C "char *netname;" .C "int *uidp, *gidp, *gidlenp, *gidlistp;" .fi .IP Convert an operating-system independent netname to a domain-specific user .B ID. .I uidp points to the user .B ID of the user; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR user2netname() . .PP .nf .C "int" .C "user2netname(netname, uid, domain)" .C "char netname[MAXNETNAMELEN];" .C "int uid;" .C "char *domain;" .fi .IP Convert a domain-specific username to an operating-system independent netname. .I uid is the user .B ID of the owner of the server process. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2user() . .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR login (1), .BR chkey (1), .BR rpc (3C), .BR rpc_clnt_auth (3C), .BR publickey (4), .BR keyserv (1M), .BR newkey (1M) .\" toc@\f3secure_rpc(3C)\f1:\0\0\f4authdes_create()\fP, \f4authdes_getucred()\fP, \f4get_myaddress()\fP, \n\f4getnetaddress()\fP, \f4getnetname()\fP, \f4host2netname()\fP, \n\f4key_decryptsession()\fP, \f4key_encryptsession()\fP, \f4key_gendes()\fP, \n\f4key_setsecret()\fP, \f4netname2host()\fP, \f4netname2user()\fP, \n\f4user2netname()\fP@@@library routines for secure remote procedure calls .\" toc@\f4secure_rpc()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_create()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_getucred()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4get_myaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4host2netname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_decryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_encryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_gendes()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_setsecret()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2host()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2user()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4user2netname()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" index@library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4secure_rpc()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_create()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_getucred()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4get_myaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4host2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_decryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_encryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_gendes()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_setsecret()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2host()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2user()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4user2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" links@secure_rpc.3c authdes_create.3c .\" links@secure_rpc.3c authdes_getucred.3c .\" links@secure_rpc.3c get_myaddress.3c .\" links@secure_rpc.3c getnetaddress.3c .\" links@secure_rpc.3c getnetname.3c .\" links@secure_rpc.3c host2netname.3c .\" links@secure_rpc.3c key_decryptsession.3c .\" links@secure_rpc.3c key_encryptsession.3c .\" links@secure_rpc.3c key_gendes.3c .\" links@secure_rpc.3c key_setsecret.3c .\" links@secure_rpc.3c netname2host.3c .\" links@secure_rpc.3c netname2user.3c .\" links@secure_rpc.3c user2netname.3c .\" $Header: secure_rpc.3c,v 74.1 95/05/10 21:12:12 ssa Exp $ .TA s .TH secure_rpc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME secure_rpc(), authdes_create(), authdes_getucred(), get_myaddress(), getnetname(), host2netname(), key_decryptsession(), key_encryptsession(), key_gendes(), key_setsecret(), netname2host(), netname2user(), user2netname() \- library routines for secure remote procedure calls .SH DESCRIPTION .LP .C RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .LP .C RPC allows various authentication flavors. The .B authdes_getucred() and .B authdes_create() routines implement the .B DES authentication flavor. See .BR rpc_clnt_auth (3C) for routines relating to the .B AUTH_NONE and .B AUTH_UNIX authentication types. .IP Note: Both the client and server should have their keys in the .BR publickey (5) database. Also, the keyserver daemon .BR keyserv (1M) must be running on both the client and server hosts for the .B DES authentication system to work. .SS Routines .LP The following routines require that the header .BR be included. .PP The .B AUTH data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "AUTH *" .C "authdes_create(netname, window, syncaddr, deskeyp)" .C "char *netname;" .C "unsigned window;" .C "struct sockaddr_in *syncaddr;" .C "des_block *deskeyp;" .fi .IP .B authdes_create() is an interface to the .B RPC secure authentication system, known as .B DES authentication. .IP Used on the client side, .B authdes_create() returns an authentication handle that enables the use of the secure authentication system. The first parameter .I netname is the network name of the owner of the server process. This field usually represents a .I host derived from the utility routine .BR host2netname() , but could also represent a user name using .BR user2netname() . The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third parameter .I syncaddr is optional. If it is .B NULL, then the authentication system will assume that the local clock is always in sync with the server's clock, and will not attempt to synchronize with the server. If an address is supplied then the system will use it for consulting the remote time service whenever resynchronization is required. This parameter is usually the address of the .B RPC server itself. The final parameter .I deskeyp is also optional. If it is .B NULL, then the authentication system will generate a random .B DES key to be used for the encryption of credentials. If .I deskeyp is supplied then it is used instead. .PP .nf .C "int" .C "authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)" .C "struct authdes_cred *adc;" .C "short *uidp, *gidp, *gidlenp;" .C "int *gidlistp;" .fi .IP .BR authdes_getucred() , is a .B DES authentication routine used by the server for converting a .B DES credential, which is operating system independent, into a .B UNIX credential. .I uidp points to the user .B ID of the user associated with .IR adc ; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. .br .ne 5 .IP This routine differs from the utility routine .B netname2user() in that .B authdes_getucred() pulls its information from a cache, and does not have to do a .B NIS name service lookup every time it is called to get its information. Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "void" .C "get_myaddress(addr)" .C "struct sockaddr_in *addr;" .fi .IP Return the machine's .B IP address in .IR addr. The port number is always set to .BR htons(PMAPPORT) . .PP .nf .C "int" .C "getnetname(netname)" .C "char netname[MAXNETNAMELEN];" .fi .IP Return the unique, operating-system independent netname of the caller in the fixed-length array .IR netname . Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "int" .C "host2netname(netname, host, domain)" .C "char netname[MAXNETNAMELEN];" .C "char *host;" .C "char *domain;" .fi .IP Convert from a domain-specific hostname to an operating-system independent netname. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . This routine should be used if the owner of the server process is the machine that is, the user with effective user .B ID zero. Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2host() . .PP .nf .C "int" .C "key_decryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP An interface routine to the keyserver daemon, which is associated with .B RPC's secure authentication system ( .B DES authentication). User programs rarely need to call it, or its associated routines .BR key_encryptsession() , .B key_gendes() and .BR key_setsecret() . System commands such as .B login and the .B RPC library are the main clients of these four routines. .IP .B key_decryptsession() takes the netname of a server and a .B DES key, and decrypts the key by using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_encryptsession() . .PP .nf .C "int" .C "key_encryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It takes the netname of the server and a .B DES key, and encrypts it using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_decryptsession() . .PP .nf .C "int" .C "key_gendes(deskeyp)" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It is used to ask the keyserver for a secure conversation key. Choosing one at random is usually not good enough, because the common ways of choosing random numbers, such as using the current time, are very easy to guess. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "key_setsecret(keyp)" .C "char *keyp;" .fi .IP A keyserver interface routine. It is used to set the secret key for the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "netname2host(netname, host, hostlen)" .C "char *netname;" .C "char *host;" .C "int hostlen;" .fi .IP Convert an operating-system independent netname to a domain-specific hostname. .I hostlen specifies the size of the array pointed to by .I host. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR host2netname() . .PP .nf .C "int" .C "netname2user(netname, uidp, gidp, gidlenp, gidlistp)" .C "char *netname;" .C "int *uidp, *gidp, *gidlenp, *gidlistp;" .fi .IP Convert an operating-system independent netname to a domain-specific user .B ID. .I uidp points to the user .B ID of the user; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR user2netname() . .PP .nf .C "int" .C "user2netname(netname, uid, domain)" .C "char netname[MAXNETNAMELEN];" .C "int uid;" .C "char *domain;" .fi .IP Convert a domain-specific username to an operating-system independent netname. .I uid is the user .B ID of the owner of the server process. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2user() . .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR login (1), .BR chkey (1), .BR rpc (3C), .BR rpc_clnt_auth (3C), .BR publickey (4), .BR keyserv (1M), .BR newkey (1M) .\" toc@\f3secure_rpc(3C)\f1:\0\0\f4authdes_create()\fP, \f4authdes_getucred()\fP, \f4get_myaddress()\fP, \n\f4getnetaddress()\fP, \f4getnetname()\fP, \f4host2netname()\fP, \n\f4key_decryptsession()\fP, \f4key_encryptsession()\fP, \f4key_gendes()\fP, \n\f4key_setsecret()\fP, \f4netname2host()\fP, \f4netname2user()\fP, \n\f4user2netname()\fP@@@library routines for secure remote procedure calls .\" toc@\f4secure_rpc()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_create()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_getucred()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4get_myaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4host2netname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_decryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_encryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_gendes()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_setsecret()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2host()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2user()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4user2netname()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" index@library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4secure_rpc()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_create()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_getucred()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4get_myaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4host2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_decryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_encryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_gendes()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_setsecret()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2host()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2user()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4user2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" links@secure_rpc.3c authdes_create.3c .\" links@secure_rpc.3c authdes_getucred.3c .\" links@secure_rpc.3c get_myaddress.3c .\" links@secure_rpc.3c getnetaddress.3c .\" links@secure_rpc.3c getnetname.3c .\" links@secure_rpc.3c host2netname.3c .\" links@secure_rpc.3c key_decryptsession.3c .\" links@secure_rpc.3c key_encryptsession.3c .\" links@secure_rpc.3c key_gendes.3c .\" links@secure_rpc.3c key_setsecret.3c .\" links@secure_rpc.3c netname2host.3c .\" links@secure_rpc.3c netname2user.3c .\" links@secure_rpc.3c user2netname.3c .\" $Header: newpad.3x,v 76.2 95/08/01 14:27:39 ssa Exp $ .TA n .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH newpad 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 newpad .SH NAME newpad, pnoutrefresh, prefresh \(em pad management functions .SH SYNOPSIS .C "#include " .P .C "WINDOW *newpad(int \f2nlines\fP, int \f2ncols\fP);" .P .C "int pnoutrefresh(WINDOW *\f2pad\fP, int \f2pminrow\fP, int \f2pmincol\fP, int \f2sminrow\fP," .br .C " int \f2smincol\fP, int \f2smaxrow\fP, int \f2smaxcol\fP);" .P .C "int prefresh(WINDOW *\f2pad\fP, int \f2pminrow\fP, int \f2pmincol\fP, int \f2sminrow\fP," .br .C " int \f2smincol\fP, int \f2smaxrow\fP, int \f2smaxcol\fP);" .SH DESCRIPTION The .Fn newpad function creates a specialised .CR WINDOW data structure representing a pad with \f2nlines\f1 lines and \f2ncols\f1 columns. A pad is like a window, except that it is not necessarily associated with a viewable part of the screen. Automatic refreshes of pads do not occur. .P The .Fn prefresh and .Fn pnoutrefresh functions are analogous to .Fn wrefresh and .Fn wnoutrefresh except that they relate to pads instead of windows. The additional arguments indicate what part of the pad and screen are involved. The \f2pminrow\f1 and \f2pmincol\f1 arguments specify the origin of the rectangle to be displayed in the pad. The \f2sminrow\f1, \f2smincol\f1, \f2smaxrow\f1 and \f2smaxcol\f1 arguments specify the edges of the rectangle to be displayed on the screen. The lower right-hand corner of the rectangle to be displayed in the pad is calculated from the screen coordinates, since the rectangles must be the same size. Both rectangles must be entirely contained within their respective structures. Negative values of \f2pminrow\f1, \f2pmincol\f1, \f2sminrow\f1 or \f2smincol\f1 are treated as if they were zero. .SH "RETURN VALUE" Upon successful completion, the .Fn newpad function returns a pointer to the pad data structure. Otherwise, it returns a null pointer. .P Upon successful completion, .Fn pnoutrefresh and .Fn prefresh return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" To refresh a pad, call .Fn prefresh or .CR pnoutrefresh() , not .CR wrefresh() . When porting code to use pads from WINDOWS, remember that these functions require additional arguments to specify the part of the pad to be displayed and the location on the screen to be used for the display. .P Although a subwindow and its parent pad may share memory representing characters in the pad, they need not share status information about what has changed in the pad. Therefore, after modifying a subwindow within a pad, it may be necessary to call .Fn touchwin or .Fn touchline on the pad before calling .CR prefresh() . .SH "SEE ALSO" derwin(), doupdate(), is_linetouched(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn pnoutrefresh and .Fn prefresh functions are merged with this entry. In previous issues, they appeared in the entry for .CR prefresh() . .\" .\" toc@\f3newpad(3X)\f1:\0\0\f4newpad()\f1, \f4pnoutrefresh()\f1, \f4prefresh()\f1@@@pad management functions .\" toc@\f4pnoutrefresh()\f1: pad management functions@@@see \f3newpad(3X)\f1 .\" toc@\f4prefresh()\f1: pad management functions@@@see \f3newpad(3X)\f1 .\" .\" index@\f4newpad()\f1 \- pad management functions@@@\f3newpad(3X)\f1 .\" index@\f4pnoutrefresh()\f1 \- pad management functions@@@\f3newpad(3X)\f1 .\" index@\f4prefresh()\f1 \- pad management functions@@@\f3newpad(3X)\f1 .\" index@\f1pad management functions@@@\f3newpad(3X)\f1 .\" index@\f1management functions, for pad@@@\f3newpad(3X)\f1 .\" index@\f1functions, for pad management@@@\f3newpad(3X)\f1 .\" .\" links@newpad.3x pnoutrefresh.3x .\" links@newpad.3x prefresh.3x .\" .\" fileset_database@newpad.3x CURS-ENG-A-MAN .\" $Header: initscr.3x,v 76.2 95/08/01 11:21:16 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH initscr 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 initscr .SH NAME initscr, newterm \(em screen initialisation functions .SH SYNOPSIS .C "#include " .P .C "WINDOW *initscr(void);" .P .C "SCREEN *newterm(char *\f2type\fP, FILE *\f2outfile\fP, FILE *\f2infile\fP);" .SH DESCRIPTION The .Fn initscr function determines the terminal type and initialises all implementation data structures. The .Ev TERM environment variable specifies the terminal type. The .Fn initscr function also causes the first refresh operation to clear the screen. If errors occur, .Fn initscr writes an appropriate error message to standard error and exits. The only functions that can be called before .Fn initscr or .Fn newterm are .CR filter() , .CR ripoffline() , .CR slk_init() , .Fn use_env and the functions whose prototypes are defined in .CR . Portable applications must not call .Fn initscr twice. .P The .Fn newterm function can be called as many times as desired to attach a terminal device. The \f2type\f1 argument points to a string specifying the terminal type, except that if \f2type\f1 is a null pointer, the .Ev TERM environment variable is used. The \f2outfile\f1 and \f2infile\f1 arguments are file pointers for output to the terminal and input from the terminal, respectively. It is unspecified whether Curses modifies the buffering mode of these file pointers. The .Fn newterm function should be called once for each terminal. .P The .Fn initscr function is equivalent to: .IP newterm(getenv("TERM"), stdout, stdin); .br return stdscr; .PP If the current disposition for the signals SIGINT, SIGQUIT or SIGTSTP is SIGDFL, then .Fn initscr may also install a handler for the signal, which may remain in effect for the life of the process or until the process changes the disposition of the signal. .P The .Fn initscr and .Fn newterm functions initialise the .I cur_term external variable. .SH "RETURN VALUE" Upon successful completion, .Fn initscr returns a pointer to .I stdscr . Otherwise, it does not return. .P Upon successful completion, .Fn newterm returns a pointer to the specified terminal. Otherwise, it returns a null pointer. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" A program that outputs to more than one terminal should use .Fn newterm for each terminal instead of .Fn initscr . A program that needs an indication of error conditions, so it can continue to run in a line-oriented mode if the terminal cannot support a screen-oriented program, would also use this function. .P Applications should perform any required handling of the SIGINT, SIGQUIT or SIGTSTP signals before calling .CR initscr() . .SH "SEE ALSO" \f3Selecting a Terminal\f1 in terminfo(4), delscreen(), doupdate(), del_curterm(), filter(), slk_attroff(), use_env(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn newterm function is merged with this entry. In previous issues, it appeared in an entry of its own. .P The entry is rewritten for clarity. The argument list for the .Fn initscr function is explicitly declared as \f3void\f1. .\" .\" toc@\f3initscr(3X)\f1:\0\0\f4initscr()\f1, \f4newterm()\f1@@@screen initialisation functions .\" toc@\f4newterm()\f1: screen initialisation functions@@@see \f3initscr(3X)\f1 .\" .\" index@\f4initscr()\f1 \- screen initialisation functions@@@\f3initscr(3X)\f1 .\" index@\f4newterm()\f1 \- screen initialisation functions@@@\f3initscr(3X)\f1 .\" index@\f1screen initialisation functions@@@\f3initscr(3X)\f1 .\" index@\f1initialisation functions for screen@@@\f3initscr(3X)\f1 .\" index@\f1functions, screen initialisation functions@@@\f3initscr(3X)\f1 .\" .\" links@initscr.3x newterm.3x .\" .\" fileset_database@initscr.3x CURS-ENG-A-MAN .\" $Header: newwin.3x,v 76.2 95/08/01 14:28:38 ssa Exp $ .TA n .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH newwin 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME newwin, subwin \(em window creation functions .SH SYNOPSIS .C "#include " .P .C "WINDOW *newwin(int \f2nlines\fP, int \f2ncols\fP, int \f2begin_y\fP, int \f2begin_x\fP);" .P .C "WINDOW *subwin(WINDOW *\f2orig\fP, int \f2nlines\fP, int \f2ncols\fP, int \f2begin_y\fP," .br .C " int \f2begin_x\fP);" .SH DESCRIPTION .P The .Fn newwin function creates a new window with \f2nlines\f1 lines and \f2ncols\f1 columns, positioned so that the origin is (\f2begin_y\f1, \f2begin_x\f1). If \f2nlines\f1 is zero, it defaults to .CR LINES \(mi \f2begin_y\fP; if \f2ncols\f1 is zero, it defaults to .CR COLS \(mi \f2begin_x\f1. .P The .Fn subwin function creates a new window with \f2nlines\f1 lines and \f2ncols\f1 columns, positioned so that the origin is at (\f2begin_y\f1, \f2begin_x\f1). (This position is an absolute screen position, not a position relative to the window \f2orig\f1.) If any part of the new window is outside \f2orig\fP, the function fails and the window is not created. .SH "RETURN VALUE" Upon successful completion, these functions return a pointer to the new window. Otherwise, they return a null pointer. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Before performing the first refresh of a subwindow, portable applications should call .Fn touchwin or .Fn touchline on the parent window. .P Each window maintains internal descriptions of the screen image and status. The screen image is shared among all windows in the window hierarchy. Refresh operations rely on information on what has changed within a window, which is private to each window. Refreshing a window, when updates were made to a different window, may fail to perform needed updates because the windows do not share this information. .P A new full-screen window is created by calling: .IP .C "newwin(0, 0, 0, 0);" .PP .SH "SEE ALSO" delwin(), is_linetouched(), doupdate(), . .SH "CHANGE HISTORY" First released in Issue 2 .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" toc@\f3newwin(3X)\f1:\0\0\f4newwin()\f1, \f4subwin()\f1@@@window creation functions .\" toc@\f4subwin()\f1: window creation functions@@@see \f3subwin(3X)\f1 .\" .\" index@\f4newwin()\f1 \- window creation functions@@@\f3newwin(3X)\f1 .\" index@\f4subwin()\f1 \- window creation functions@@@\f3newwin(3X)\f1 .\" index@\f1window creation functions@@@\f3newwin(3X)\f1 .\" index@\f1functions, window creation functions@@@\f3newwin(3X)\f1 .\" index@\f1create, windows, functions@@@\f3newwin(3X)\f1 .\" .\" links@newwin.3x subwin.3x .\" .\" fileset_database@newwin.3x CURS-ENG-A-MAN .\" $Header: nextafter.3m,v 78.2 96/02/13 13:29:48 ssa Exp $ .TA n .TH nextafter 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nextafter(\|) \- next representable double-precision floating-point number .SH SYNOPSIS .C "#include " .PP .C "double nextafter(double x, double y);" .SH DESCRIPTION .PP The .CR nextafter() function computes the next representable double-precision floating-point value following .I x in the direction of .IR y . Thus, if .I y is less than .IR x , .CR nextafter() returns the largest representable floating-point number less than .IR x . .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH "RETURN VALUE" .PP The .CR nextafter() function returns the next representable double-precision floating-point value following .I x in the direction of .IR y . .PP If .I x or .I y is NaN, .CR nextafter() returns NaN. .PP If .I x is finite and the correct function value would overflow, .CR nextafter() returns .ift .CR \(+-HUGE_VAL .ifn .CR +\-HUGE_VAL (according to the sign of .IR x ) and sets .CR errno to [ERANGE]. .SH "ERRORS" .PP If .CR nextafter() fails, .CR errno is set to the following value. .RS .TP 20 [ERANGE] The correct value would overflow. .RE .SH "SEE ALSO" isinf(3M), isnan(3M), limits(5). .SH STANDARDS CONFORMANCE .CR nextafter() ": SVID3, XPG4.2" .\" index@\f4nextafter()\f1 \- next representable double-precision floating-point number@@@\f3nextafter(3M)\f1 .\" index@\f1next representable double-precision floating-point number@@@\f3nextafter(3M)\f1 .\" index@\f1math: next representable double-precision floating-point number@@@\f3nextafter(3M)\f1 .\" .\" toc@\f3nextafter(3M)\f1:\0\0\f4nextafter()\f1@@@next representable double-precision floating-point number .\" $Header: dbm.3x,v 76.1 95/07/05 17:27:37 ssa Exp $ .TA d .TH dbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbminit, fetch, store, delete, firstkey, nextkey, dbmclose \- database subroutines .SH SYNOPSIS .C "#include " .P .C "int dbminit(const char *file);" .P .C "datum fetch(datum key);" .P .C "int store(datum key, datum content);" .P .C "int delete(datum key);" .P .C "datum firstkey(void);" .P .C "datum nextkey(datum key);" .P .C "int dbmclose(void);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can locate a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .I dptr. Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbminit . At the time of this call, the files .IC file .dir and .IC file .pag must exist. (An empty database is created by creating zero-length .C .dir and .C .pag files.) .PP Once open, data stored under a key is accessed by .IC fetch , and data is placed under a key by .IC store . Storing data on an existing key replaces the existing data. A key (and its associated contents) is deleted by .CR delete . A linear pass through all keys in a database can be made, in (apparently) random order by using .C firstkey and .CR nextkey . .C firstkey returns the first key in the database. With any key, .C nextkey returns the next key in the database. The following code can be used to traverse the database: .IP .C "for (key = firstkey(); key.dptr != NULL; key = nextkey(key))" .PP A database can be closed by calling .C dbmclose. A currently open database must be closed before opening a new one. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .IR dptr . .SH WARNINGS The .I dbm functions provided in this library should not be confused in any way with those of a general-purpose database management system such as .SM ALLBASE/HP-UX SQL. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful data base functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C store returns an error if a disk block fills with inseparable data. .PP .C delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C firstkey and .C nextkey depends on a hashing function, not on anything interesting. .PP A .C store or .C delete during a pass through the keys by .C firstkey and .C nextkey may yield unexpected results. .SH AUTHOR .IR dbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO ndbm(3X). .\" index@\f4dbminit()\fP \- open a single database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4fetch()\fP \- access data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4store()\fP \- store data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4delete()\fP \- delete key and data under it (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4firstkey()\fP \- get first key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4nextkey()\fP \- get next key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4dbmclose()\fP \- close currently open database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@database subroutines (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" index@subroutines, database (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" .\" toc@\f3dbm(3X)\f1:\0\0\f4dbminit()\fP, \f4fetch()\fP, \f4store()\fP, \f4delete()\fP, \f4firstkey()\fP,\n\f4nextkey()\fP, \f4dbmclose()\fP@@@database subroutines .\" toc@\f4dbminit()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4fetch()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4store()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4delete()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4firstkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4nextkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4dbmclose()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" .\" links@dbm.3x dbminit.3x .\" links@dbm.3x fetch.3x .\" links@dbm.3x store.3x .\" links@dbm.3x delete.3x .\" links@dbm.3x firstkey.3x .\" links@dbm.3x nextkey.3x .\" links@dbm.3x dbmclose.3x .\" .\" fileset_database@dbm.3x PROGRAMING-MAN .\" $Header: ftw.3c,v 78.1 96/02/12 13:48:55 ssa Exp $ .TA f .TH ftw 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ftw(), nftw(), nftw2() \- walk a file tree executing a function .SH SYNOPSIS .nf .C "#include " .PP .C "int ftw (const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat *obj_stat," .C " int obj_flags)," .C " int depth);" .PP .C "int nftw2(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .PP .C "int nftw (const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .SS UNIX95 .nf .C "int nftw (const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat *obj_stat," .C " int obj_flags," .C " struct *FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .SH DESCRIPTION The .CR ftw() function recursively descends the directory hierarchy rooted in .IR path . For each object in the hierarchy, .CR ftw() calls .IR fn , passing it a pointer to a null-terminated character string containing the name of the object, a pointer to a .CR stat structure containing information about the object (see .CR lstat() in .IR stat (2)), and an integer. The possible values of the integer, defined in the .CR header file, are: .RS .TP 15 .CR FTW_F The object is a file. .TP .CR FTW_D The object is a directory. .TP .CR FTW_SL The object is a symbolic link. .TP .CR FTW_DNR The object is a directory without read permission. .I fn will not be called for any of its descendants. .TP .CR FTW_NS .CR lstat() failed on the object. The contents of the .CR stat structure are undefined. If the .CR lstat() failure is because the object is in a directory without search permission, .I fn is called and the walk continues. If .CR lstat() fails for any other reason, .CR ftw() does not call .IR fn , it sets .CR errno , and returns .CR -1 . .RE .PP Tree traversal continues until the tree is exhausted, an invocation of .I fn returns a nonzero value, or an error is detected within .CR ftw() , such as an I/O error. If the tree is exhausted, .CR ftw() returns zero. If .I fn returns a nonzero value, .CR ftw() stops its tree traversal and returns the same value as returned by .IR fn . If .CR ftw() detects an error, it returns .CR -1 and sets the error type in .CR errno (see .IR errno (2)). .PP .CR ftw() visits a directory before visiting any of its descendants. .PP .CR ftw() and .CR nftw() use one file descriptor for each level in the tree. The .I depth argument limits the number of file descriptors that can be used. If .I depth is 0 or negative, the effect is the same as if it were 1. .I depth must not be greater than the number of file descriptors currently available for use. For best performance, .I depth should be at least as large as the number of levels in the tree. .PP .CR nftw() is similar to .CR ftw() except that it takes the additional argument .IR flags . The .I flags field is the inclusive OR of the following values, as defined in the .CR header file: .RS .TP 15 .CR FTW_PHYS .CR nftw() does a physical walk. It does not follow symbolic links. .CR nftw() follows hard links but does not walk down any path that crosses itself. If .CR FTW_PHYS is not specified, .CR nftw() follows symbolic and hard links but does not walk a path that crosses itself. .TP .CR FTW_MOUNT The walk does not cross a mount point. This means the walk does not visit any files that reside on a device other than the one where the walk started. It does not cross NFS mount points. .TP .CR FTW_DEPTH .CR nftw() performs a depth-first search. This means that a directory's contents are visited before the directory itself is visited. .TP .CR FTW_CHDIR The walk does a .CR chdir() (see .IR chdir (2)) to each directory before reading it. .TP .CR FTW_SERR The walk normally terminates and returns .CR -1 if .CR lstat() fails for any reason. If .CR FTW_SERR is specified and an .CR lstat() failure is encountered, .I fn is called, and the walk continues. .RE .PP .CR nftw() calls .I fn with four arguments for each file and directory visited. The first argument is the path name of the file or directory, the second is a pointer to a .CR stat structure (see .IR lstat (2)) containing information about the object, and the third is an integer giving additional information as follows: .RS .TP 15 .CR FTW_F The object is a file. .TP .CR FTW_D The object is a directory. .TP .CR FTW_DP The object is a directory and subdirectories have been visited. This can be passed to .I fn only if .CR FTW_DEPTH is specified. .TP .CR FTW_SL The object is a symbolic link. This can be passed to .I fn only if .CR FTW_PHYS is specified. .TP .CR FTW_SLN The object is a symbolic link that does not point to an existing object. This can be passed to .I fn only if .CR FTW_PHYS is not specified. .TP .CR FTW_DNR The object is a directory that cannot be read. .I fn is not called for any of its descendants. .TP .CR FTW_NS .CR lstat() failed on the object. The contents of the .CR stat structure passed to .I fn are undefined. If the .CR lstat() failure occurred because the object is in a directory without search permission, .CR errno is set, and .CR nftw() returns .CR -1 after calling .IR fn . Note that this behavior differs from .CR ftw() . If .CR lstat() fails for any other reason, .CR nftw() does not call .IR fn , it sets .CR errno , and returns .CR -1 . This behavior can be altered by specifying the .CR FTW_SERR .IR flag . .RE .PP The fourth argument is different for the default environment and the .CR UNIX95 environment. For the default environment, the fourth argument is a structure .CR FTW . For the .CR UNIX95 environment, the fourth argument is a pointer to a structure .CR FTW (ie: .CR *FTW ). .CR FTW contains the following members: .nf .IP .C "int base;" .C "int level;" .fi .PP The value of .I base is the offset from the first character in the path name to where the base name of the object starts; this path name is passed as the first argument to .IR fn . The value of .I level indicates depth relative to the start of the walk, where the start level has a value of zero. .PP .CR nftw2() is equivalent to .CR nftw() . This function is provided for HP-UX compatibility in future releases. .SH ERRORS If .CR ftw() or .CR nftw() fails, it sets .CR errno (see .IR errno (2)) to one of the following values: .RS .TP 25 [EACCES] If a component of the .IR path prefix denies search permission, or if read permission is denied for .IR path , .I fn returns .CR -1 and does not reset .CR errno . .TP [EINVAL] The value of the .I depth argument is invalid. .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] .I path points to the name of a file that does not exist, or points to an empty string. .TP [ENOTDIR] A component of .I path is not a directory. .TP [EOVERFLOW] One of the values in .C struct stat (st_size or st_blocks) is too large to store into the structure to be passed to the function pointed to by .IR fn. .RE .PP In addition, if the function pointed to by .I fn encounters system errors, .CR errno may be set accordingly. .ift .br .ift .ne 12 .SH WARNINGS Because these functions are recursive, it is possible for them to terminate with a memory fault when applied to very deep file structures. .PP .CR ftw() and .CR nftw() use .CR malloc() to allocate dynamic storage during their operation (see .IR malloc (3C)) If they are forcibly terminated (such as if .CR longjmp() is executed by .I fn or an interrupt routine), the calling function will not have a chance to free that storage, causing it to remain allocated until the process terminates. A safe way to handle interrupts is to store the fact that an interrupt has occurred, and arrange to have .I fn return a nonzero value at its next invocation. .PP The syntax for .CR nftw() may be changed in a future release. (See .CR nftw2() in the DESCRIPTION section). .SH APPLICATION USAGE To use the .CR UNIX95 prototype, the .CR UNIX95 environment must be defined. This is done by defining the .CR UNIX95 environment variable, passing the .CR _XOPEN_UNIX_EXTENDED flag as a compiler option, and adding .CR /usr/xpg4/bin to your path. This can be done as follows: .TP 3 1. .CR "export UNIX95=" .PD 0 .TP 2. .CR "PATH=/usr/xpg4/bin:$PATH" .TP 3. .CR "cc foo.c -D_XOPEN_SOURCE_EXTENDED" .PD .SH AUTHOR .CR ftw() , .CR nftw() , and .CR nftw2() were developed by AT&T and HP. .SH SEE ALSO stat(2), ftw64(3C), nftw64(3C), malloc(3C). .SH STANDARDS CONFORMANCE .CR ftw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f1descend a directory hierarchy recursively, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1directory hierarchy, recursively descend a, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1execute a function, descending a directory tree@@@\f3ftw(3C)\f1 .\" index@\f1file tree, walk, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1function, execute descending a directory tree@@@\f3ftw(3C)\f1 .\" index@\f1hierarchy, directory, recursively descend a, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1recursively descend a directory hierarchy, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1traverse (walk) a file tree, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1tree, walk a file, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1walk a file tree, executing a function@@@\f3ftw(3C)\f1 .\" index@\f4ftw()\f1 \- walk a file tree executing a function@@@\f3ftw(3C)\f1 .\" index@\f4nftw()\f1 \- walk a file tree executing a function@@@\f3ftw(3C)\f1 .\" index@\f4nftw2()\f1 \- walk a file tree executing a function@@@\f3ftw(3C)\f1 .\" .\" toc@\f3ftw(3C)\f1:\0\0\f4ftw()\f1, \f4nftw()\f1, \f4nftw2()\f1@@@walk a file tree, executing a function\f1 .\" toc@\f4nftw()\f1:\0\0walk a file tree, executing a function@@@\f1see \f3ftw(3C)\f1 .\" toc@\f4nftw2()\f1:\0\0walk a file tree, executing a function@@@\f1see \f3ftw(3C)\f1 .\" .\" links@ftw.3c nftw.3c .\" links@ftw.3c nftw2.3c .\" $Header: ftw.3c,v 78.1 96/02/12 13:48:55 ssa Exp $ .TA f .TH ftw 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ftw(), nftw(), nftw2() \- walk a file tree executing a function .SH SYNOPSIS .nf .C "#include " .PP .C "int ftw (const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat *obj_stat," .C " int obj_flags)," .C " int depth);" .PP .C "int nftw2(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .PP .C "int nftw (const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .SS UNIX95 .nf .C "int nftw (const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat *obj_stat," .C " int obj_flags," .C " struct *FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .SH DESCRIPTION The .CR ftw() function recursively descends the directory hierarchy rooted in .IR path . For each object in the hierarchy, .CR ftw() calls .IR fn , passing it a pointer to a null-terminated character string containing the name of the object, a pointer to a .CR stat structure containing information about the object (see .CR lstat() in .IR stat (2)), and an integer. The possible values of the integer, defined in the .CR header file, are: .RS .TP 15 .CR FTW_F The object is a file. .TP .CR FTW_D The object is a directory. .TP .CR FTW_SL The object is a symbolic link. .TP .CR FTW_DNR The object is a directory without read permission. .I fn will not be called for any of its descendants. .TP .CR FTW_NS .CR lstat() failed on the object. The contents of the .CR stat structure are undefined. If the .CR lstat() failure is because the object is in a directory without search permission, .I fn is called and the walk continues. If .CR lstat() fails for any other reason, .CR ftw() does not call .IR fn , it sets .CR errno , and returns .CR -1 . .RE .PP Tree traversal continues until the tree is exhausted, an invocation of .I fn returns a nonzero value, or an error is detected within .CR ftw() , such as an I/O error. If the tree is exhausted, .CR ftw() returns zero. If .I fn returns a nonzero value, .CR ftw() stops its tree traversal and returns the same value as returned by .IR fn . If .CR ftw() detects an error, it returns .CR -1 and sets the error type in .CR errno (see .IR errno (2)). .PP .CR ftw() visits a directory before visiting any of its descendants. .PP .CR ftw() and .CR nftw() use one file descriptor for each level in the tree. The .I depth argument limits the number of file descriptors that can be used. If .I depth is 0 or negative, the effect is the same as if it were 1. .I depth must not be greater than the number of file descriptors currently available for use. For best performance, .I depth should be at least as large as the number of levels in the tree. .PP .CR nftw() is similar to .CR ftw() except that it takes the additional argument .IR flags . The .I flags field is the inclusive OR of the following values, as defined in the .CR header file: .RS .TP 15 .CR FTW_PHYS .CR nftw() does a physical walk. It does not follow symbolic links. .CR nftw() follows hard links but does not walk down any path that crosses itself. If .CR FTW_PHYS is not specified, .CR nftw() follows symbolic and hard links but does not walk a path that crosses itself. .TP .CR FTW_MOUNT The walk does not cross a mount point. This means the walk does not visit any files that reside on a device other than the one where the walk started. It does not cross NFS mount points. .TP .CR FTW_DEPTH .CR nftw() performs a depth-first search. This means that a directory's contents are visited before the directory itself is visited. .TP .CR FTW_CHDIR The walk does a .CR chdir() (see .IR chdir (2)) to each directory before reading it. .TP .CR FTW_SERR The walk normally terminates and returns .CR -1 if .CR lstat() fails for any reason. If .CR FTW_SERR is specified and an .CR lstat() failure is encountered, .I fn is called, and the walk continues. .RE .PP .CR nftw() calls .I fn with four arguments for each file and directory visited. The first argument is the path name of the file or directory, the second is a pointer to a .CR stat structure (see .IR lstat (2)) containing information about the object, and the third is an integer giving additional information as follows: .RS .TP 15 .CR FTW_F The object is a file. .TP .CR FTW_D The object is a directory. .TP .CR FTW_DP The object is a directory and subdirectories have been visited. This can be passed to .I fn only if .CR FTW_DEPTH is specified. .TP .CR FTW_SL The object is a symbolic link. This can be passed to .I fn only if .CR FTW_PHYS is specified. .TP .CR FTW_SLN The object is a symbolic link that does not point to an existing object. This can be passed to .I fn only if .CR FTW_PHYS is not specified. .TP .CR FTW_DNR The object is a directory that cannot be read. .I fn is not called for any of its descendants. .TP .CR FTW_NS .CR lstat() failed on the object. The contents of the .CR stat structure passed to .I fn are undefined. If the .CR lstat() failure occurred because the object is in a directory without search permission, .CR errno is set, and .CR nftw() returns .CR -1 after calling .IR fn . Note that this behavior differs from .CR ftw() . If .CR lstat() fails for any other reason, .CR nftw() does not call .IR fn , it sets .CR errno , and returns .CR -1 . This behavior can be altered by specifying the .CR FTW_SERR .IR flag . .RE .PP The fourth argument is different for the default environment and the .CR UNIX95 environment. For the default environment, the fourth argument is a structure .CR FTW . For the .CR UNIX95 environment, the fourth argument is a pointer to a structure .CR FTW (ie: .CR *FTW ). .CR FTW contains the following members: .nf .IP .C "int base;" .C "int level;" .fi .PP The value of .I base is the offset from the first character in the path name to where the base name of the object starts; this path name is passed as the first argument to .IR fn . The value of .I level indicates depth relative to the start of the walk, where the start level has a value of zero. .PP .CR nftw2() is equivalent to .CR nftw() . This function is provided for HP-UX compatibility in future releases. .SH ERRORS If .CR ftw() or .CR nftw() fails, it sets .CR errno (see .IR errno (2)) to one of the following values: .RS .TP 25 [EACCES] If a component of the .IR path prefix denies search permission, or if read permission is denied for .IR path , .I fn returns .CR -1 and does not reset .CR errno . .TP [EINVAL] The value of the .I depth argument is invalid. .TP [ENAMETOOLONG] The length of the specified path name exceeds .CR PATH_MAX bytes, or the length of a component of the path name exceeds .CR NAME_MAX bytes while .CR _POSIX_NO_TRUNC is in effect. .TP [ENOENT] .I path points to the name of a file that does not exist, or points to an empty string. .TP [ENOTDIR] A component of .I path is not a directory. .TP [EOVERFLOW] One of the values in .C struct stat (st_size or st_blocks) is too large to store into the structure to be passed to the function pointed to by .IR fn. .RE .PP In addition, if the function pointed to by .I fn encounters system errors, .CR errno may be set accordingly. .ift .br .ift .ne 12 .SH WARNINGS Because these functions are recursive, it is possible for them to terminate with a memory fault when applied to very deep file structures. .PP .CR ftw() and .CR nftw() use .CR malloc() to allocate dynamic storage during their operation (see .IR malloc (3C)) If they are forcibly terminated (such as if .CR longjmp() is executed by .I fn or an interrupt routine), the calling function will not have a chance to free that storage, causing it to remain allocated until the process terminates. A safe way to handle interrupts is to store the fact that an interrupt has occurred, and arrange to have .I fn return a nonzero value at its next invocation. .PP The syntax for .CR nftw() may be changed in a future release. (See .CR nftw2() in the DESCRIPTION section). .SH APPLICATION USAGE To use the .CR UNIX95 prototype, the .CR UNIX95 environment must be defined. This is done by defining the .CR UNIX95 environment variable, passing the .CR _XOPEN_UNIX_EXTENDED flag as a compiler option, and adding .CR /usr/xpg4/bin to your path. This can be done as follows: .TP 3 1. .CR "export UNIX95=" .PD 0 .TP 2. .CR "PATH=/usr/xpg4/bin:$PATH" .TP 3. .CR "cc foo.c -D_XOPEN_SOURCE_EXTENDED" .PD .SH AUTHOR .CR ftw() , .CR nftw() , and .CR nftw2() were developed by AT&T and HP. .SH SEE ALSO stat(2), ftw64(3C), nftw64(3C), malloc(3C). .SH STANDARDS CONFORMANCE .CR ftw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f1descend a directory hierarchy recursively, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1directory hierarchy, recursively descend a, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1execute a function, descending a directory tree@@@\f3ftw(3C)\f1 .\" index@\f1file tree, walk, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1function, execute descending a directory tree@@@\f3ftw(3C)\f1 .\" index@\f1hierarchy, directory, recursively descend a, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1recursively descend a directory hierarchy, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1traverse (walk) a file tree, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1tree, walk a file, executing a function@@@\f3ftw(3C)\f1 .\" index@\f1walk a file tree, executing a function@@@\f3ftw(3C)\f1 .\" index@\f4ftw()\f1 \- walk a file tree executing a function@@@\f3ftw(3C)\f1 .\" index@\f4nftw()\f1 \- walk a file tree executing a function@@@\f3ftw(3C)\f1 .\" index@\f4nftw2()\f1 \- walk a file tree executing a function@@@\f3ftw(3C)\f1 .\" .\" toc@\f3ftw(3C)\f1:\0\0\f4ftw()\f1, \f4nftw()\f1, \f4nftw2()\f1@@@walk a file tree, executing a function\f1 .\" toc@\f4nftw()\f1:\0\0walk a file tree, executing a function@@@\f1see \f3ftw(3C)\f1 .\" toc@\f4nftw2()\f1:\0\0walk a file tree, executing a function@@@\f1see \f3ftw(3C)\f1 .\" .\" links@ftw.3c nftw.3c .\" links@ftw.3c nftw2.3c .\" $Header: fgetpos64.3s,v 78.3 96/02/12 17:04:12 ssa Exp $ .TA f .TH fgetpos64 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetpos64(\|), fopen64(\|), freopen64(\|), fseeko64(\|), fsetpos64(\|), fstatvfsdev64(\|), ftello64(\|), ftw64(\|), nftw64(\|), statvfsdev64(\|), tmpfile64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0fgetpos64(FILE\0*stream,\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "FILE\0*fopen64(const\0char\0*pathname,\0const\0char\0*type);" .PP .C "#include " .PP .C "FILE\0*freopen64(const\0char\0*pathname,\0const\0char\0*type,\0FILE\0*stream);" .PP .C "#include " .PP .C "int\0fseeko64(FILE\0*stream,\0off64_t\0*offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0fsetpos64(FILE\0*stream,\0const\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "int\0fstatvfsdev64(int\0filedes,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "off64_t\0ftello64(FILE\0*stream);" .PP .nf .C "#include " .PP .C "int ftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags)," .C " int depth);" .PP .C "#include " .PP .C "int nftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .PP .C "#include " .PP .C "int\0statvfsdev64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "FILE\0*tmpfile64(void);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 22 .C fgetpos64() The .C fgetpos64() function is identical to .C fgetpos() except that .C fgetpos64() returns the position in a .C fpos64_t instead of a .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fopen64() The .C fopen64() function is identical to .C fopen() in 64-bit compile environment. The .C fopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR fopen() . .TP .C freopen64() The .C freopen64() function is identical to .C freopen() in 64-bit compile environment. The .C freopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR freopen() . .TP .C fseeko64() The .C fseeko64() function is identical to .C fseeko() except that .C fseeko64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C fsetpos64() The .C fsetpos64() function is identical to .C fsetpos() except that .C fsetpos64() accepts an .CR fpos64_t for the pos parameter instead of .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fstatvfsdev64() The .C fstatvfsdev64() function is identical to .C fstatvfsdev() except that .C fstatvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C ftello64() The .C ftello64() function is identical to .C ftello() except that .C ftello64() returns the file position in an .C off64_t instead of an .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C ftw64() The .C ftw64() function is identical to .C ftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR ftw64() . All other functional behaviors, returns, and errors are identical. .TP .C nftw64() The .C nftw64() function is identical to .C nftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR nftw64() . All other functional behaviors, returns, and errors are identical. .TP .C statvfsdev64() The .C statvfsdev64() function is identical to .C statvfsdev() except that .C statvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C tmpfile64() The .C tmpfile64() function is identical to .C tmpfile() in the 64-bit compile environment. Both interfaces create a temporary file that is capable of growing beyond 2GB's if desired. All other functional behaviors, returns, and errors are identical. .\" .\" toc@\f4fgetpos64(2)\f1:\0\0\f4fopen64\f1, \f4freopen64\f1, \f4fseeko64\f1, \f4fsetpos64\f1, \f4fstatvfsdev64\f1, \f4ftello64\f1, \f4ftw64\f1, \n\f4nftw64\f1, \f4statvfsdev64\f1, \f4tmpfile64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4fgetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4freopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fseeko64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fsetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fstatvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftello64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4nftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4statvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4tmpfile64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3fgetpos64(2)\f1 .\" .\" links@fgetpos64.3s fopen64.3s .\" links@fgetpos64.3s freopen64.3s .\" links@fgetpos64.3s fseek64.3s .\" links@fgetpos64.3s fsetpos64.3s .\" links@fgetpos64.3s fstatvfs64.3s .\" links@fgetpos64.3s ftello64.3s .\" links@fgetpos64.3s ftw64.3s .\" links@fgetpos64.3s nftw64.3s .\" links@fgetpos64.3s statvfsdev64.3s .\" links@fgetpos64.3s tmpfile64.3s .\" .\" $Header: nl.3x,v 76.2 95/08/01 14:29:57 ssa Exp $ .TA n .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH nl 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl, nonl \(em enable/disable newline translation .SH SYNOPSIS .C "#include " .P .C "int nl(void);" .P .C "int nonl(void);" .SH DESCRIPTION The .Fn nl function enables a mode in which carriage return is translated to newline on input. The .Fn nonl function disables the above translation. Initially, the above translation is enabled. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The default translation adapts the terminal to environments in which newline is the line termination character. However, by disabling the translation with .Fn nonl , the application can sense the pressing of the carriage return key. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn nl and .Fn nonl functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3nl(3X)\f1:\0\0\f4nl()\f1, \f4nonl()\f1@@@enable/disable newline translation .\" toc@\f4nonl()\f1: enable/disable newline translation@@@see \f3nl(3X)\f1 .\" .\" index@\f4nl()\f1 \- enable/disable newline translation@@@\f3nl(3X)\f1 .\" index@\f4nonl()\f1 \- enable/disable newline translation@@@\f3nl(3X)\f1 .\" index@\f1enable/disable newline translation@@@\f3nl(3X)\f1 .\" index@\f1disable/enable newline translation@@@\f3nl(3X)\f1 .\" index@\f1newline translation, enable/disable@@@\f3nl(3X)\f1 .\" .\" links@nl.3x nonl.3x .\" .\" fileset_database@nl.3x CURS-ENG-A-MAN .\" $Header: strtod.3c,v 72.6 94/11/30 15:47:58 ssa Exp $ .TA s .TH strtod 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strtod, atof \- convert string to double-precision number .SH SYNOPSIS .C "#include " .PP .C "double strtod(const char *str, char **ptr);" .PP .C "double atof(const char *str);" .SH DESCRIPTION .C strtod() returns, as a double-precision floating-point number, the value represented by the character string pointed to by .IR str . The string is scanned (leading white-space characters as defined by .C isspace() in .IR ctype (3C) are ignored) up to the first unrecognized character. If no conversion can take place, zero is returned. .PP .C strtod() recognizes characters in the following sequence: .RS .TP 5 1. An optional string of ``white-space'' characters which are ignored, .PD 0 .TP 2. An optional sign, .TP 3. A string of digits optionally containing a radix character, .TP 4. An optional .C e or .C E followed by an optional sign or space, followed by an integer. .PD .RE .PP The radix character is determined by the loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C", is used (see .IR lang (5)). The default environment specifies a period (.) as the radix character. .PP If the value of .I ptr is not .CR "(char **)NULL , the variable to which it points is set to point at the character after the last number, if any, that was recognized. If no number can be formed, .I \(**ptr is set to .IR str , and zero is returned. .PP .CI atof( str ) is equivalent to .CI "strtod (" str ", (char **)NULL)\f1." .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the value of the radix character within the currently loaded .SM NLS environment. .SH RETURN VALUE If the correct value would cause overflow, .C +HUGE_VAL or .C -HUGE_VAL is returned (according to the sign of the value), and .C errno is set to .SM ERANGE. .PP If the correct value would cause underflow, zero is returned and .C errno is set to .SM ERANGE. .SH AUTHOR .C strtod() was developed by AT&T and HP. .SH SEE ALSO ctype(3C), setlocale(3C), scanf(3S), strtol(3C), hpnls(5), lang(5). .SH STANDARDS CONFORMANCE .CR strtod() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR atof() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4strtod()\fP \- convert string to double-precision number@@@\f3strtod(3C)\f1 .\" index@\f4atof()\fP \- convert string to double-precision number@@@\f3strtod(3C)\f1 .\" index@convert string to double-precision number@@@\f3strtod(3C)\f1 .\" index@string to double-precision number, convert@@@\f3strtod(3C)\f1 .\" index@double-precision number, convert string to@@@\f3strtod(3C)\f1 .\" index@number, convert string to double-precision@@@\f3strtod(3C)\f1 .\" .\" toc@\f3strtod(3C)\f1:\0\0\f4strtod()\fP, \f4atof()\f1@@@convert string to double-precision number .\" toc@\f4atof()\fP:\0\0convert string to double-precision number@@@see \f3strtod(3C)\f1 .\" .\" links@strtod.3c atof.3c .\" links@strtod.3c nl_strtod.3c .\" links@strtod.3c nl_atof.3c .\" $Header: scanf.3s,v 72.7 94/12/08 12:16:59 ssa Exp $ .TA s .TH scanf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scanf, fscanf, sscanf \- formatted input conversion, read from stream file .SH SYNOPSIS .C "#include " .PP .C "int scanf(const char *format, /* [pointer,] */ ...);" .PP .C "int fscanf(FILE *stream, const char *format, /* [pointer,] */ ...);" .PP .C "int sscanf(const char *s, const char *format, /* [pointer,] */ ...);" .SH DESCRIPTION .C scanf() reads from the standard input stream .IR stdin . .PP .C fscanf() reads from the named input .IR stream . .PP .C sscanf() reads from the character string .IR s . .PP Each function reads characters, interprets them according to the control string .I format argument, and stores the results in its .I pointer arguments. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are ignored. The control string contains conversion specifications and other characters used to direct interpretation of input sequences. The control string contains: .RS .TP 3 \(bu White-space characters (blanks, tabs, newlines, or formfeeds) that cause input to be read up to the next non-white-space character (except in two cases described below). .TP \(bu An ordinary character (not .CR % ) that must match the next character of the input stream. .TP \(bu Conversion specifications, consisting of the character .CR % , an optional assignment suppressing character .CR * , an optional numerical maximum-field width, an optional .C l (ell), .CR ll , (ell ell), .C h or .C L indicating the size of the receiving variable, and a conversion code. .TP \(bu The conversion specification can alternatively be prefixed by the character sequence .CI % n $ instead of the character .CR % , where .I n is a decimal integer in the range .RC (1\|\(mi\| {NL_ARGMAX} ) .RC ( NL_ARGMAX is defined in .RC < limits.h >). The .CI % n $ construction indicates that the value of the next input field should be placed in the .IR n th argument, rather than to the next unused one. The two forms of introducing a conversion specification, .C % and .CI % n $\f1, must not be mixed within a single .I format string with the following exception: Skip fields (see below) can be designated as .C %* or .CI % n $*\f1. In the latter case, .I n is ignored. .RE .PP Unless the specification contains the .C n conversion character (described below), a conversion specification directs the conversion of the next input field. The result of a conversion specification is placed in the variable to which the corresponding argument points, unless .C * indicates assignment suppression. Assignment suppression provides a way to describe an input field to be skipped. An input field is defined as a string of non-space characters; it extends to the next inappropriate character or until the field width, if specified, is exhausted. For all descriptors except .C [ and .CR c , white space leading an input field is ignored. .PP The conversion code indicates the interpretation of the input field; the corresponding pointer argument must be of a restricted type. For a suppressed field, no pointer argument is given. The following conversion codes are legal: .RS .TP 12 .C % A single .C % is expected in the input at this point; no assignment is done. .TP .C d A decimal integer is expected; the corresponding argument should be an integer pointer. .TP .C u An unsigned decimal integer is expected; the corresponding argument should be an unsigned integer pointer. .TP .C o An octal integer is expected; the corresponding argument should be an unsigned integer pointer. .TP .CR x ,\0 X A hexadecimal integer is expected; the corresponding argument should be an unsigned integer pointer. The .C x and .C X conversion characters are equivalent. .TP .C i An integer is expected; the corresponding argument should be an integer pointer. The value of the next input item, interpreted according to C conventions, will be stored; a leading .C 0 implies octal, a leading .C 0x implies hexadecimal; otherwise, decimal is assumed. .TP .C n Cause the total number of bytes (including white space) scanned since the function call to be stored; the corresponding argument should be an integer pointer. No input is consumed. The function return value does not include .CI % n assignments in the count of successfully matched and assigned input items. .TP .ift \s+1\f4e\fP,\f3E\fP,\f3f\fP,\f3g\fP,\f3G\fP\s0 .ifn \f3e\fP,\f3E\fP,\f3f\fP,\f3g\fP,\f3G\fP A floating-point number is expected; the next field is converted accordingly and stored through the corresponding argument, which should be a pointer to a .IR float . The input format for floating-point numbers is an optionally signed string of digits, possibly containing a radix character, followed by an optional exponent field consisting of an .C E or an .CR e , followed by an optional .CR + , .CR - , or space, followed by an integer. The conversion characters .C E and .C G behave the same as, respectively, .C e and .CR g . .TP .C C A character is expected; the corresponding argument should be a .C wchar_t pointer. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use .CR %1S . The character is read and converted into a wide character according to the setting of .CR LC_CTYPE . If a field width is given, the corresponding argument refers to a wide character array; the indicated number of characters is read and converted. .TP .C c A character is expected; the corresponding argument should be a character pointer. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use .CR %1s . If a field width is given, the corresponding argument refers to a character array; the indicated number of characters is read. .TP .C S A character string is expected; the corresponding argument should be a .C wchar_t pointer pointing to an array of wide characters large enough to accept the string and a terminating .CR (wchar_t)0 , which is added automatically. Characters are read and converted into wide characters according to the setting of .CR LC_CTYPE . The input field is terminated by a white-space character. .C scanf() cannot read a null string. .TP .C s A character string is expected; the corresponding argument should be a character pointer pointing to an array of characters large enough to accept the string and a terminating .CR \e0 , which is added automatically. The input field is terminated by a white-space character. .C scanf() cannot read a null string. .TP .C [ Indicates string data and the normal skip-over-leading-white-space is suppressed. The left bracket is followed by a set of characters, called the .IR scanset , and a right bracket; the input field is the maximal sequence of input characters consisting entirely of characters in the scanset. The circumflex .RC ( ^ ), when it appears as the first character in the scanset, serves as a complement operator and redefines the scanset as the set of all characters .IR not contained in the remainder of the scanset string. Construction of the .I scanset follows certain conventions. A range of characters may be represented by the construct .IR first\-last , enabling [0123456789] to be expressed [0\-9]. Using this convention, .IR first must be lexically less than or equal to .IR last ; otherwise, the dash stands for itself. The dash also stands for itself when it is the first or the last character in the scanset. To include the right square bracket as an element of the scanset, it must appear as the first character (possibly preceded by a circumflex) of the scanset, in which case it will not be interpreted syntactically as the closing bracket. The corresponding argument must point to a character array large enough to hold the data field and the terminating .CR \e0 , which are added automatically. At least one character must match for this conversion to succeed. .TP .C p A sequence of unsigned hexadecimal numbers is expected. This sequence may be produced by the .C p conversion character of .CR printf() . The corresponding argument shall be a pointer to a pointer to .C void into which the value represented by the hexadecimal sequence is stored. The behavior of this conversion is undefined for any input item other than a value converted earlier during the same program execution. .PP The conversion characters .CR d , .CR i , and .C n can be preceded by .CR l , .CR ll or .CR h to indicate that a pointer to a .CR long .CR int , .CR long .CR long .CR int or .CR short .CR int rather than to an .CR int is in the argument list. Similarly, the conversion characters .CR u , .CR o , .CR x , and .CR X can be preceded by .CR l , .CR ll or .CR h to indicate that a pointer to .CR unsigned .CR long .CR int , .CR unsigned .CR long .CR long .CR int , or .CR unsigned .CR short .CR int rather than to an .CR unsigned .CR int , is in the argument list. Finally, the conversion characters .CR e , .CR E , .CR f , .CR g , and .CR G can be preceded by .CR l or .CR L to indicate that a pointer to a .CR double or .CR long .CR double rather than to a .CR float is in the argument list. The .CR l , .CR ll , .CR L or .CR h modifier is ignored for other conversion characters. .PP The .CR scanf() functions terminate their conversions at .SM EOF, at the end of the control string, or when an input character conflicts with the control string. In the latter case, the offending character is left unread in the input stream. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of ordinary characters within format strings as single and/or multi-byte characters. Field width is given in terms of bytes. Characters received from the input stream are interpreted as single- or multi-byte characters as determined by the .CR LC_TYPE category and the field width is decremented by the length of the character. .PP The .CR LC_NUMERIC category determines the radix character expected within floating-point numbers. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUES If the input ends before the first conflict or conversion, .SM EOF is returned. Otherwise, these functions return the number of successfully assigned input items. This number is a short count, or even zero if a conflict ensues between an input character and the control string. .SH ERRORS .CR scanf() and .CR fscanf() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP .SM [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP .SM [EIO] The process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RE .PP Additional .CR errno values can be set by the underlying .CR read() function (see .IR read (2)). .SH EXAMPLES The call: .IP .CR "int i, n; float x; char name[50];" .br .ift \f4\s+1n = scanf("%d%f%s", &i, &x, name);\s0\fP .ifn \f3n = scanf("%d%f%s", &i, &x, name);\fP .PP with the input line: .IP .CR "25 54.32E-1 thompson" .PP assigns to .I n the value .CR 3 , to .I i the value .CR 25 , to .I x the value .CR 5.432 , and .I name contains .CR thompson\e0 . Or: .IP .CR "int i; float x; char name[50];" .br .ift \f4\s+1(void) scanf("%2d%f%*d %[0\-9]", &i, &x, name);\s0\fP .ifn \f3(void) scanf("%2d%f%*d %[0\-9]", &i, &x, name);\fP .PP with input: .IP .CR "56789 0123 56a72" .PP assigns .CR 56 to .IR i , .CR 789.0 to .IR x , skips .CR 0123 , and places the string .CR 56\e0 in .IR name . The next call to .CR getchar() (see .IR getc (3S)) returns .CR a . .PP For another example, to create a language-independent date scanning routine, use: .IP .CR "char month[20]; int day, year;" .br .CR "(void) scanf(format, month, &day, &year);" .PP For American usage, .I format would point to a string: .IP .CR "%1$s %2$d %3$d" .PP The input: .IP .CR "July 3 1986" .PP would assign .CR July to .IR month , .CR 3 to .I day and .CR 1986 to .IR year . .PP For German usage, .I format would point to a string: .IP .CR "%2$d %1$s %3$d" .PP The input: .IP 3 Juli 1986 .PP would assign .CR Juli to .IR month , .CR 3 to .I day and .CR 1986 to .IR year . .PP The success of literal matches and suppressed assignments can be determined with the .CR %n conversion specification. Here is an example that checks the success of literal matches: .nf .IP .CR "int i, n1, n2, n3, n4;" .ift .ft 4 .ifn .ft 3 .ps +1 n1 = n2 = n3 = n4 = -1;" scanf( "%nBEGIN%n %d %nEND%n", &n1, &n2, &i, &n3, &n4); if (n2 - n1 == 5) puts( "matched BEGIN"); if (n4 - n3 == 3) puts( "matched END"); .ft .ps .fi .PP Here is an example that checks the success of suppressed assignments: .nf .IP .CR "int i, n1, n2;" .CR "n1 = n2 = -1;" .ift .ft 4 .ifn .ft 3 .ps +1 scanf( "%d %n%*s%n", &i, &n1, &n2); if (n2 > n1) printf( "successful assignment suppression of %d chars\\n", n2 - n1); .ps .ft .SH WARNINGS Trailing white space (including a newline) is left unread unless matched in the control string. .PP Truncation of multi-byte characters may occur if a field width is used with the conversion character. .SH AUTHOR .CR scanf() was developed by AT&T and HP. .SH SEE ALSO getc(3S), setlocale(3C), printf(3S), strtod(3C), strtol(3C). .SH STANDARDS CONFORMANCE .CR scanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fscanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .CR sscanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4scanf()\f1 \- formatted read from \f2standard input\f1 stream file@@@\f3scanf(3S)\f1 .\" index@\f4fscanf()\f1 \- formatted read from named input stream file@@@\f3scanf(3S)\f1 .\" index@\f4sscanf()\f1 \- formatted read from character string@@@\f3scanf(3S)\f1 .\" index@\f4scanf()\f1 \- formatted read from \f2standard input\f1 stream file@@@\f3scanf(3S)\f1 .\" index@\f4fscanf()\f1 \- formatted read from named input stream file@@@\f3scanf(3S)\f1 .\" index@\f4sscanf()\f1 \- formatted read from character string@@@\f3scanf(3S)\f1 .\" index@formatted input conversion, read from stream file or character string@@@\f3scanf(3S)\f1 .\" index@input conversion, formatted read from stream file or character string@@@\f3scanf(3S)\f1 .\" index@formatted read and conversion from stream file or character string@@@\f3scanf(3S)\f1 .\" index@read from stream file or character string with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@stream file or character string, read from with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@file: read from file, stream, or character string with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@character string or stream file, read from with formatted input conversion@@@\f3scanf(3S)\f1 .\" .\" toc@\f3scanf(3S)\f1:\0\0\f4scanf()\fP, \f4fscanf()\fP, \f4sscanf()\f1@@@formatted input conversion, read from stream file .\" toc@\f4fscanf()\fP:\0\0formatted input conversion, read from stream file@@@see \f3scanf(3S)\f1 .\" toc@\f4sscanf()\fP:\0\0formatted input conversion, read from stream file@@@see \f3scanf(3S)\f1 .\" .\" links@scanf.3s fscanf.3s .\" links@scanf.3s sscanf.3s .\" links@scanf.3s nl_scanf.3s .\" links@scanf.3s nl_fscanf.3s .\" links@scanf.3s nl_sscanf.3s .\" $Header: nl_langinfo.3c,v 72.6 94/11/15 09:55:33 ssa Exp $ .TA n .TH nl_langinfo 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl_langinfo(\|) \- language information .SH SYNOPSIS .C "#include " .PP .C "char *nl_langinfo(nl_item item);" .SH DESCRIPTION .CR nl_langinfo() returns a pointer to a null-terminated string containing information relevant to a particular language or cultural area defined in the program's locale (see .IR setlocale (3C)). The manifest constant names and values of .CR item are defined in .RC < langinfo.h >. For example: .IP .CR nl_langinfo(ABDAY_1) .PP returns a pointer to the string ``Dom'' if the language identified by the current locale is pt_PT.iso88591, and ``Su'' if the identified language is fi_FI.iso88591. .PP If an invalid .CR item is specified, a pointer to an empty string is returned. An empty string can also be returned for a valid .CR item if that item is not applicable to the language or customs of the current locale. For example, a thousands separator is not used when writing numbers according to the customs associated with the Arabic language. .SH EXTERNAL INFLUENCES .SS Locale The string returned for a particular .CR item is determined by the locale category specified for that item in .IR langinfo (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH WARNINGS .CR nl_langinfo() returns a pointer to a static area that is overwritten on each call. .SH AUTHOR .CR nl_langinfo() was developed by OSF and HP. .SH SEE ALSO localeconv(3C), setlocale(3C), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR nl_langinfo() ": AES, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4nl_langinfo()\f1 \- obtain NLS string form of local language variable@@@\f3nl_langinfo(3C)\f1 .\" index@\f1information, NLS, about native languages@@@\f3nl_langinfo(3C)\f1 .\" index@\f1NLS, information about native languages@@@\f3nl_langinfo(3C)\f1 .\" index@\f1local (native) languages, NLS information about@@@\f3nl_langinfo(3C)\f1 .\" index@\f1native languages, NLS information about@@@\f3nl_langinfo(3C)\f1 .\" index@\f1languages, NLS information about native (local)@@@\f3nl_langinfo(3C)\f1 .\" .\" toc@\f3nl_langinfo(3C)\f1:\0\0\f4nl_langinfo()\f1@@@NLS information about native languages\f1 .\" $Header: scanf.3s,v 72.7 94/12/08 12:16:59 ssa Exp $ .TA s .TH scanf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scanf, fscanf, sscanf \- formatted input conversion, read from stream file .SH SYNOPSIS .C "#include " .PP .C "int scanf(const char *format, /* [pointer,] */ ...);" .PP .C "int fscanf(FILE *stream, const char *format, /* [pointer,] */ ...);" .PP .C "int sscanf(const char *s, const char *format, /* [pointer,] */ ...);" .SH DESCRIPTION .C scanf() reads from the standard input stream .IR stdin . .PP .C fscanf() reads from the named input .IR stream . .PP .C sscanf() reads from the character string .IR s . .PP Each function reads characters, interprets them according to the control string .I format argument, and stores the results in its .I pointer arguments. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are ignored. The control string contains conversion specifications and other characters used to direct interpretation of input sequences. The control string contains: .RS .TP 3 \(bu White-space characters (blanks, tabs, newlines, or formfeeds) that cause input to be read up to the next non-white-space character (except in two cases described below). .TP \(bu An ordinary character (not .CR % ) that must match the next character of the input stream. .TP \(bu Conversion specifications, consisting of the character .CR % , an optional assignment suppressing character .CR * , an optional numerical maximum-field width, an optional .C l (ell), .CR ll , (ell ell), .C h or .C L indicating the size of the receiving variable, and a conversion code. .TP \(bu The conversion specification can alternatively be prefixed by the character sequence .CI % n $ instead of the character .CR % , where .I n is a decimal integer in the range .RC (1\|\(mi\| {NL_ARGMAX} ) .RC ( NL_ARGMAX is defined in .RC < limits.h >). The .CI % n $ construction indicates that the value of the next input field should be placed in the .IR n th argument, rather than to the next unused one. The two forms of introducing a conversion specification, .C % and .CI % n $\f1, must not be mixed within a single .I format string with the following exception: Skip fields (see below) can be designated as .C %* or .CI % n $*\f1. In the latter case, .I n is ignored. .RE .PP Unless the specification contains the .C n conversion character (described below), a conversion specification directs the conversion of the next input field. The result of a conversion specification is placed in the variable to which the corresponding argument points, unless .C * indicates assignment suppression. Assignment suppression provides a way to describe an input field to be skipped. An input field is defined as a string of non-space characters; it extends to the next inappropriate character or until the field width, if specified, is exhausted. For all descriptors except .C [ and .CR c , white space leading an input field is ignored. .PP The conversion code indicates the interpretation of the input field; the corresponding pointer argument must be of a restricted type. For a suppressed field, no pointer argument is given. The following conversion codes are legal: .RS .TP 12 .C % A single .C % is expected in the input at this point; no assignment is done. .TP .C d A decimal integer is expected; the corresponding argument should be an integer pointer. .TP .C u An unsigned decimal integer is expected; the corresponding argument should be an unsigned integer pointer. .TP .C o An octal integer is expected; the corresponding argument should be an unsigned integer pointer. .TP .CR x ,\0 X A hexadecimal integer is expected; the corresponding argument should be an unsigned integer pointer. The .C x and .C X conversion characters are equivalent. .TP .C i An integer is expected; the corresponding argument should be an integer pointer. The value of the next input item, interpreted according to C conventions, will be stored; a leading .C 0 implies octal, a leading .C 0x implies hexadecimal; otherwise, decimal is assumed. .TP .C n Cause the total number of bytes (including white space) scanned since the function call to be stored; the corresponding argument should be an integer pointer. No input is consumed. The function return value does not include .CI % n assignments in the count of successfully matched and assigned input items. .TP .ift \s+1\f4e\fP,\f3E\fP,\f3f\fP,\f3g\fP,\f3G\fP\s0 .ifn \f3e\fP,\f3E\fP,\f3f\fP,\f3g\fP,\f3G\fP A floating-point number is expected; the next field is converted accordingly and stored through the corresponding argument, which should be a pointer to a .IR float . The input format for floating-point numbers is an optionally signed string of digits, possibly containing a radix character, followed by an optional exponent field consisting of an .C E or an .CR e , followed by an optional .CR + , .CR - , or space, followed by an integer. The conversion characters .C E and .C G behave the same as, respectively, .C e and .CR g . .TP .C C A character is expected; the corresponding argument should be a .C wchar_t pointer. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use .CR %1S . The character is read and converted into a wide character according to the setting of .CR LC_CTYPE . If a field width is given, the corresponding argument refers to a wide character array; the indicated number of characters is read and converted. .TP .C c A character is expected; the corresponding argument should be a character pointer. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use .CR %1s . If a field width is given, the corresponding argument refers to a character array; the indicated number of characters is read. .TP .C S A character string is expected; the corresponding argument should be a .C wchar_t pointer pointing to an array of wide characters large enough to accept the string and a terminating .CR (wchar_t)0 , which is added automatically. Characters are read and converted into wide characters according to the setting of .CR LC_CTYPE . The input field is terminated by a white-space character. .C scanf() cannot read a null string. .TP .C s A character string is expected; the corresponding argument should be a character pointer pointing to an array of characters large enough to accept the string and a terminating .CR \e0 , which is added automatically. The input field is terminated by a white-space character. .C scanf() cannot read a null string. .TP .C [ Indicates string data and the normal skip-over-leading-white-space is suppressed. The left bracket is followed by a set of characters, called the .IR scanset , and a right bracket; the input field is the maximal sequence of input characters consisting entirely of characters in the scanset. The circumflex .RC ( ^ ), when it appears as the first character in the scanset, serves as a complement operator and redefines the scanset as the set of all characters .IR not contained in the remainder of the scanset string. Construction of the .I scanset follows certain conventions. A range of characters may be represented by the construct .IR first\-last , enabling [0123456789] to be expressed [0\-9]. Using this convention, .IR first must be lexically less than or equal to .IR last ; otherwise, the dash stands for itself. The dash also stands for itself when it is the first or the last character in the scanset. To include the right square bracket as an element of the scanset, it must appear as the first character (possibly preceded by a circumflex) of the scanset, in which case it will not be interpreted syntactically as the closing bracket. The corresponding argument must point to a character array large enough to hold the data field and the terminating .CR \e0 , which are added automatically. At least one character must match for this conversion to succeed. .TP .C p A sequence of unsigned hexadecimal numbers is expected. This sequence may be produced by the .C p conversion character of .CR printf() . The corresponding argument shall be a pointer to a pointer to .C void into which the value represented by the hexadecimal sequence is stored. The behavior of this conversion is undefined for any input item other than a value converted earlier during the same program execution. .PP The conversion characters .CR d , .CR i , and .C n can be preceded by .CR l , .CR ll or .CR h to indicate that a pointer to a .CR long .CR int , .CR long .CR long .CR int or .CR short .CR int rather than to an .CR int is in the argument list. Similarly, the conversion characters .CR u , .CR o , .CR x , and .CR X can be preceded by .CR l , .CR ll or .CR h to indicate that a pointer to .CR unsigned .CR long .CR int , .CR unsigned .CR long .CR long .CR int , or .CR unsigned .CR short .CR int rather than to an .CR unsigned .CR int , is in the argument list. Finally, the conversion characters .CR e , .CR E , .CR f , .CR g , and .CR G can be preceded by .CR l or .CR L to indicate that a pointer to a .CR double or .CR long .CR double rather than to a .CR float is in the argument list. The .CR l , .CR ll , .CR L or .CR h modifier is ignored for other conversion characters. .PP The .CR scanf() functions terminate their conversions at .SM EOF, at the end of the control string, or when an input character conflicts with the control string. In the latter case, the offending character is left unread in the input stream. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of ordinary characters within format strings as single and/or multi-byte characters. Field width is given in terms of bytes. Characters received from the input stream are interpreted as single- or multi-byte characters as determined by the .CR LC_TYPE category and the field width is decremented by the length of the character. .PP The .CR LC_NUMERIC category determines the radix character expected within floating-point numbers. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUES If the input ends before the first conflict or conversion, .SM EOF is returned. Otherwise, these functions return the number of successfully assigned input items. This number is a short count, or even zero if a conflict ensues between an input character and the control string. .SH ERRORS .CR scanf() and .CR fscanf() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP .SM [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP .SM [EIO] The process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RE .PP Additional .CR errno values can be set by the underlying .CR read() function (see .IR read (2)). .SH EXAMPLES The call: .IP .CR "int i, n; float x; char name[50];" .br .ift \f4\s+1n = scanf("%d%f%s", &i, &x, name);\s0\fP .ifn \f3n = scanf("%d%f%s", &i, &x, name);\fP .PP with the input line: .IP .CR "25 54.32E-1 thompson" .PP assigns to .I n the value .CR 3 , to .I i the value .CR 25 , to .I x the value .CR 5.432 , and .I name contains .CR thompson\e0 . Or: .IP .CR "int i; float x; char name[50];" .br .ift \f4\s+1(void) scanf("%2d%f%*d %[0\-9]", &i, &x, name);\s0\fP .ifn \f3(void) scanf("%2d%f%*d %[0\-9]", &i, &x, name);\fP .PP with input: .IP .CR "56789 0123 56a72" .PP assigns .CR 56 to .IR i , .CR 789.0 to .IR x , skips .CR 0123 , and places the string .CR 56\e0 in .IR name . The next call to .CR getchar() (see .IR getc (3S)) returns .CR a . .PP For another example, to create a language-independent date scanning routine, use: .IP .CR "char month[20]; int day, year;" .br .CR "(void) scanf(format, month, &day, &year);" .PP For American usage, .I format would point to a string: .IP .CR "%1$s %2$d %3$d" .PP The input: .IP .CR "July 3 1986" .PP would assign .CR July to .IR month , .CR 3 to .I day and .CR 1986 to .IR year . .PP For German usage, .I format would point to a string: .IP .CR "%2$d %1$s %3$d" .PP The input: .IP 3 Juli 1986 .PP would assign .CR Juli to .IR month , .CR 3 to .I day and .CR 1986 to .IR year . .PP The success of literal matches and suppressed assignments can be determined with the .CR %n conversion specification. Here is an example that checks the success of literal matches: .nf .IP .CR "int i, n1, n2, n3, n4;" .ift .ft 4 .ifn .ft 3 .ps +1 n1 = n2 = n3 = n4 = -1;" scanf( "%nBEGIN%n %d %nEND%n", &n1, &n2, &i, &n3, &n4); if (n2 - n1 == 5) puts( "matched BEGIN"); if (n4 - n3 == 3) puts( "matched END"); .ft .ps .fi .PP Here is an example that checks the success of suppressed assignments: .nf .IP .CR "int i, n1, n2;" .CR "n1 = n2 = -1;" .ift .ft 4 .ifn .ft 3 .ps +1 scanf( "%d %n%*s%n", &i, &n1, &n2); if (n2 > n1) printf( "successful assignment suppression of %d chars\\n", n2 - n1); .ps .ft .SH WARNINGS Trailing white space (including a newline) is left unread unless matched in the control string. .PP Truncation of multi-byte characters may occur if a field width is used with the conversion character. .SH AUTHOR .CR scanf() was developed by AT&T and HP. .SH SEE ALSO getc(3S), setlocale(3C), printf(3S), strtod(3C), strtol(3C). .SH STANDARDS CONFORMANCE .CR scanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fscanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .CR sscanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4scanf()\f1 \- formatted read from \f2standard input\f1 stream file@@@\f3scanf(3S)\f1 .\" index@\f4fscanf()\f1 \- formatted read from named input stream file@@@\f3scanf(3S)\f1 .\" index@\f4sscanf()\f1 \- formatted read from character string@@@\f3scanf(3S)\f1 .\" index@\f4scanf()\f1 \- formatted read from \f2standard input\f1 stream file@@@\f3scanf(3S)\f1 .\" index@\f4fscanf()\f1 \- formatted read from named input stream file@@@\f3scanf(3S)\f1 .\" index@\f4sscanf()\f1 \- formatted read from character string@@@\f3scanf(3S)\f1 .\" index@formatted input conversion, read from stream file or character string@@@\f3scanf(3S)\f1 .\" index@input conversion, formatted read from stream file or character string@@@\f3scanf(3S)\f1 .\" index@formatted read and conversion from stream file or character string@@@\f3scanf(3S)\f1 .\" index@read from stream file or character string with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@stream file or character string, read from with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@file: read from file, stream, or character string with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@character string or stream file, read from with formatted input conversion@@@\f3scanf(3S)\f1 .\" .\" toc@\f3scanf(3S)\f1:\0\0\f4scanf()\fP, \f4fscanf()\fP, \f4sscanf()\f1@@@formatted input conversion, read from stream file .\" toc@\f4fscanf()\fP:\0\0formatted input conversion, read from stream file@@@see \f3scanf(3S)\f1 .\" toc@\f4sscanf()\fP:\0\0formatted input conversion, read from stream file@@@see \f3scanf(3S)\f1 .\" .\" links@scanf.3s fscanf.3s .\" links@scanf.3s sscanf.3s .\" links@scanf.3s nl_scanf.3s .\" links@scanf.3s nl_fscanf.3s .\" links@scanf.3s nl_sscanf.3s .\" $Header: scanf.3s,v 72.7 94/12/08 12:16:59 ssa Exp $ .TA s .TH scanf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scanf, fscanf, sscanf \- formatted input conversion, read from stream file .SH SYNOPSIS .C "#include " .PP .C "int scanf(const char *format, /* [pointer,] */ ...);" .PP .C "int fscanf(FILE *stream, const char *format, /* [pointer,] */ ...);" .PP .C "int sscanf(const char *s, const char *format, /* [pointer,] */ ...);" .SH DESCRIPTION .C scanf() reads from the standard input stream .IR stdin . .PP .C fscanf() reads from the named input .IR stream . .PP .C sscanf() reads from the character string .IR s . .PP Each function reads characters, interprets them according to the control string .I format argument, and stores the results in its .I pointer arguments. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are ignored. The control string contains conversion specifications and other characters used to direct interpretation of input sequences. The control string contains: .RS .TP 3 \(bu White-space characters (blanks, tabs, newlines, or formfeeds) that cause input to be read up to the next non-white-space character (except in two cases described below). .TP \(bu An ordinary character (not .CR % ) that must match the next character of the input stream. .TP \(bu Conversion specifications, consisting of the character .CR % , an optional assignment suppressing character .CR * , an optional numerical maximum-field width, an optional .C l (ell), .CR ll , (ell ell), .C h or .C L indicating the size of the receiving variable, and a conversion code. .TP \(bu The conversion specification can alternatively be prefixed by the character sequence .CI % n $ instead of the character .CR % , where .I n is a decimal integer in the range .RC (1\|\(mi\| {NL_ARGMAX} ) .RC ( NL_ARGMAX is defined in .RC < limits.h >). The .CI % n $ construction indicates that the value of the next input field should be placed in the .IR n th argument, rather than to the next unused one. The two forms of introducing a conversion specification, .C % and .CI % n $\f1, must not be mixed within a single .I format string with the following exception: Skip fields (see below) can be designated as .C %* or .CI % n $*\f1. In the latter case, .I n is ignored. .RE .PP Unless the specification contains the .C n conversion character (described below), a conversion specification directs the conversion of the next input field. The result of a conversion specification is placed in the variable to which the corresponding argument points, unless .C * indicates assignment suppression. Assignment suppression provides a way to describe an input field to be skipped. An input field is defined as a string of non-space characters; it extends to the next inappropriate character or until the field width, if specified, is exhausted. For all descriptors except .C [ and .CR c , white space leading an input field is ignored. .PP The conversion code indicates the interpretation of the input field; the corresponding pointer argument must be of a restricted type. For a suppressed field, no pointer argument is given. The following conversion codes are legal: .RS .TP 12 .C % A single .C % is expected in the input at this point; no assignment is done. .TP .C d A decimal integer is expected; the corresponding argument should be an integer pointer. .TP .C u An unsigned decimal integer is expected; the corresponding argument should be an unsigned integer pointer. .TP .C o An octal integer is expected; the corresponding argument should be an unsigned integer pointer. .TP .CR x ,\0 X A hexadecimal integer is expected; the corresponding argument should be an unsigned integer pointer. The .C x and .C X conversion characters are equivalent. .TP .C i An integer is expected; the corresponding argument should be an integer pointer. The value of the next input item, interpreted according to C conventions, will be stored; a leading .C 0 implies octal, a leading .C 0x implies hexadecimal; otherwise, decimal is assumed. .TP .C n Cause the total number of bytes (including white space) scanned since the function call to be stored; the corresponding argument should be an integer pointer. No input is consumed. The function return value does not include .CI % n assignments in the count of successfully matched and assigned input items. .TP .ift \s+1\f4e\fP,\f3E\fP,\f3f\fP,\f3g\fP,\f3G\fP\s0 .ifn \f3e\fP,\f3E\fP,\f3f\fP,\f3g\fP,\f3G\fP A floating-point number is expected; the next field is converted accordingly and stored through the corresponding argument, which should be a pointer to a .IR float . The input format for floating-point numbers is an optionally signed string of digits, possibly containing a radix character, followed by an optional exponent field consisting of an .C E or an .CR e , followed by an optional .CR + , .CR - , or space, followed by an integer. The conversion characters .C E and .C G behave the same as, respectively, .C e and .CR g . .TP .C C A character is expected; the corresponding argument should be a .C wchar_t pointer. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use .CR %1S . The character is read and converted into a wide character according to the setting of .CR LC_CTYPE . If a field width is given, the corresponding argument refers to a wide character array; the indicated number of characters is read and converted. .TP .C c A character is expected; the corresponding argument should be a character pointer. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use .CR %1s . If a field width is given, the corresponding argument refers to a character array; the indicated number of characters is read. .TP .C S A character string is expected; the corresponding argument should be a .C wchar_t pointer pointing to an array of wide characters large enough to accept the string and a terminating .CR (wchar_t)0 , which is added automatically. Characters are read and converted into wide characters according to the setting of .CR LC_CTYPE . The input field is terminated by a white-space character. .C scanf() cannot read a null string. .TP .C s A character string is expected; the corresponding argument should be a character pointer pointing to an array of characters large enough to accept the string and a terminating .CR \e0 , which is added automatically. The input field is terminated by a white-space character. .C scanf() cannot read a null string. .TP .C [ Indicates string data and the normal skip-over-leading-white-space is suppressed. The left bracket is followed by a set of characters, called the .IR scanset , and a right bracket; the input field is the maximal sequence of input characters consisting entirely of characters in the scanset. The circumflex .RC ( ^ ), when it appears as the first character in the scanset, serves as a complement operator and redefines the scanset as the set of all characters .IR not contained in the remainder of the scanset string. Construction of the .I scanset follows certain conventions. A range of characters may be represented by the construct .IR first\-last , enabling [0123456789] to be expressed [0\-9]. Using this convention, .IR first must be lexically less than or equal to .IR last ; otherwise, the dash stands for itself. The dash also stands for itself when it is the first or the last character in the scanset. To include the right square bracket as an element of the scanset, it must appear as the first character (possibly preceded by a circumflex) of the scanset, in which case it will not be interpreted syntactically as the closing bracket. The corresponding argument must point to a character array large enough to hold the data field and the terminating .CR \e0 , which are added automatically. At least one character must match for this conversion to succeed. .TP .C p A sequence of unsigned hexadecimal numbers is expected. This sequence may be produced by the .C p conversion character of .CR printf() . The corresponding argument shall be a pointer to a pointer to .C void into which the value represented by the hexadecimal sequence is stored. The behavior of this conversion is undefined for any input item other than a value converted earlier during the same program execution. .PP The conversion characters .CR d , .CR i , and .C n can be preceded by .CR l , .CR ll or .CR h to indicate that a pointer to a .CR long .CR int , .CR long .CR long .CR int or .CR short .CR int rather than to an .CR int is in the argument list. Similarly, the conversion characters .CR u , .CR o , .CR x , and .CR X can be preceded by .CR l , .CR ll or .CR h to indicate that a pointer to .CR unsigned .CR long .CR int , .CR unsigned .CR long .CR long .CR int , or .CR unsigned .CR short .CR int rather than to an .CR unsigned .CR int , is in the argument list. Finally, the conversion characters .CR e , .CR E , .CR f , .CR g , and .CR G can be preceded by .CR l or .CR L to indicate that a pointer to a .CR double or .CR long .CR double rather than to a .CR float is in the argument list. The .CR l , .CR ll , .CR L or .CR h modifier is ignored for other conversion characters. .PP The .CR scanf() functions terminate their conversions at .SM EOF, at the end of the control string, or when an input character conflicts with the control string. In the latter case, the offending character is left unread in the input stream. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of ordinary characters within format strings as single and/or multi-byte characters. Field width is given in terms of bytes. Characters received from the input stream are interpreted as single- or multi-byte characters as determined by the .CR LC_TYPE category and the field width is decremented by the length of the character. .PP The .CR LC_NUMERIC category determines the radix character expected within floating-point numbers. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUES If the input ends before the first conflict or conversion, .SM EOF is returned. Otherwise, these functions return the number of successfully assigned input items. This number is a short count, or even zero if a conflict ensues between an input character and the control string. .SH ERRORS .CR scanf() and .CR fscanf() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP .SM [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP .SM [EIO] The process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RE .PP Additional .CR errno values can be set by the underlying .CR read() function (see .IR read (2)). .SH EXAMPLES The call: .IP .CR "int i, n; float x; char name[50];" .br .ift \f4\s+1n = scanf("%d%f%s", &i, &x, name);\s0\fP .ifn \f3n = scanf("%d%f%s", &i, &x, name);\fP .PP with the input line: .IP .CR "25 54.32E-1 thompson" .PP assigns to .I n the value .CR 3 , to .I i the value .CR 25 , to .I x the value .CR 5.432 , and .I name contains .CR thompson\e0 . Or: .IP .CR "int i; float x; char name[50];" .br .ift \f4\s+1(void) scanf("%2d%f%*d %[0\-9]", &i, &x, name);\s0\fP .ifn \f3(void) scanf("%2d%f%*d %[0\-9]", &i, &x, name);\fP .PP with input: .IP .CR "56789 0123 56a72" .PP assigns .CR 56 to .IR i , .CR 789.0 to .IR x , skips .CR 0123 , and places the string .CR 56\e0 in .IR name . The next call to .CR getchar() (see .IR getc (3S)) returns .CR a . .PP For another example, to create a language-independent date scanning routine, use: .IP .CR "char month[20]; int day, year;" .br .CR "(void) scanf(format, month, &day, &year);" .PP For American usage, .I format would point to a string: .IP .CR "%1$s %2$d %3$d" .PP The input: .IP .CR "July 3 1986" .PP would assign .CR July to .IR month , .CR 3 to .I day and .CR 1986 to .IR year . .PP For German usage, .I format would point to a string: .IP .CR "%2$d %1$s %3$d" .PP The input: .IP 3 Juli 1986 .PP would assign .CR Juli to .IR month , .CR 3 to .I day and .CR 1986 to .IR year . .PP The success of literal matches and suppressed assignments can be determined with the .CR %n conversion specification. Here is an example that checks the success of literal matches: .nf .IP .CR "int i, n1, n2, n3, n4;" .ift .ft 4 .ifn .ft 3 .ps +1 n1 = n2 = n3 = n4 = -1;" scanf( "%nBEGIN%n %d %nEND%n", &n1, &n2, &i, &n3, &n4); if (n2 - n1 == 5) puts( "matched BEGIN"); if (n4 - n3 == 3) puts( "matched END"); .ft .ps .fi .PP Here is an example that checks the success of suppressed assignments: .nf .IP .CR "int i, n1, n2;" .CR "n1 = n2 = -1;" .ift .ft 4 .ifn .ft 3 .ps +1 scanf( "%d %n%*s%n", &i, &n1, &n2); if (n2 > n1) printf( "successful assignment suppression of %d chars\\n", n2 - n1); .ps .ft .SH WARNINGS Trailing white space (including a newline) is left unread unless matched in the control string. .PP Truncation of multi-byte characters may occur if a field width is used with the conversion character. .SH AUTHOR .CR scanf() was developed by AT&T and HP. .SH SEE ALSO getc(3S), setlocale(3C), printf(3S), strtod(3C), strtol(3C). .SH STANDARDS CONFORMANCE .CR scanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fscanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .CR sscanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4scanf()\f1 \- formatted read from \f2standard input\f1 stream file@@@\f3scanf(3S)\f1 .\" index@\f4fscanf()\f1 \- formatted read from named input stream file@@@\f3scanf(3S)\f1 .\" index@\f4sscanf()\f1 \- formatted read from character string@@@\f3scanf(3S)\f1 .\" index@\f4scanf()\f1 \- formatted read from \f2standard input\f1 stream file@@@\f3scanf(3S)\f1 .\" index@\f4fscanf()\f1 \- formatted read from named input stream file@@@\f3scanf(3S)\f1 .\" index@\f4sscanf()\f1 \- formatted read from character string@@@\f3scanf(3S)\f1 .\" index@formatted input conversion, read from stream file or character string@@@\f3scanf(3S)\f1 .\" index@input conversion, formatted read from stream file or character string@@@\f3scanf(3S)\f1 .\" index@formatted read and conversion from stream file or character string@@@\f3scanf(3S)\f1 .\" index@read from stream file or character string with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@stream file or character string, read from with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@file: read from file, stream, or character string with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@character string or stream file, read from with formatted input conversion@@@\f3scanf(3S)\f1 .\" .\" toc@\f3scanf(3S)\f1:\0\0\f4scanf()\fP, \f4fscanf()\fP, \f4sscanf()\f1@@@formatted input conversion, read from stream file .\" toc@\f4fscanf()\fP:\0\0formatted input conversion, read from stream file@@@see \f3scanf(3S)\f1 .\" toc@\f4sscanf()\fP:\0\0formatted input conversion, read from stream file@@@see \f3scanf(3S)\f1 .\" .\" links@scanf.3s fscanf.3s .\" links@scanf.3s sscanf.3s .\" links@scanf.3s nl_scanf.3s .\" links@scanf.3s nl_fscanf.3s .\" links@scanf.3s nl_sscanf.3s .\" $Header: strtod.3c,v 72.6 94/11/30 15:47:58 ssa Exp $ .TA s .TH strtod 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strtod, atof \- convert string to double-precision number .SH SYNOPSIS .C "#include " .PP .C "double strtod(const char *str, char **ptr);" .PP .C "double atof(const char *str);" .SH DESCRIPTION .C strtod() returns, as a double-precision floating-point number, the value represented by the character string pointed to by .IR str . The string is scanned (leading white-space characters as defined by .C isspace() in .IR ctype (3C) are ignored) up to the first unrecognized character. If no conversion can take place, zero is returned. .PP .C strtod() recognizes characters in the following sequence: .RS .TP 5 1. An optional string of ``white-space'' characters which are ignored, .PD 0 .TP 2. An optional sign, .TP 3. A string of digits optionally containing a radix character, .TP 4. An optional .C e or .C E followed by an optional sign or space, followed by an integer. .PD .RE .PP The radix character is determined by the loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C", is used (see .IR lang (5)). The default environment specifies a period (.) as the radix character. .PP If the value of .I ptr is not .CR "(char **)NULL , the variable to which it points is set to point at the character after the last number, if any, that was recognized. If no number can be formed, .I \(**ptr is set to .IR str , and zero is returned. .PP .CI atof( str ) is equivalent to .CI "strtod (" str ", (char **)NULL)\f1." .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the value of the radix character within the currently loaded .SM NLS environment. .SH RETURN VALUE If the correct value would cause overflow, .C +HUGE_VAL or .C -HUGE_VAL is returned (according to the sign of the value), and .C errno is set to .SM ERANGE. .PP If the correct value would cause underflow, zero is returned and .C errno is set to .SM ERANGE. .SH AUTHOR .C strtod() was developed by AT&T and HP. .SH SEE ALSO ctype(3C), setlocale(3C), scanf(3S), strtol(3C), hpnls(5), lang(5). .SH STANDARDS CONFORMANCE .CR strtod() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR atof() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4strtod()\fP \- convert string to double-precision number@@@\f3strtod(3C)\f1 .\" index@\f4atof()\fP \- convert string to double-precision number@@@\f3strtod(3C)\f1 .\" index@convert string to double-precision number@@@\f3strtod(3C)\f1 .\" index@string to double-precision number, convert@@@\f3strtod(3C)\f1 .\" index@double-precision number, convert string to@@@\f3strtod(3C)\f1 .\" index@number, convert string to double-precision@@@\f3strtod(3C)\f1 .\" .\" toc@\f3strtod(3C)\f1:\0\0\f4strtod()\fP, \f4atof()\f1@@@convert string to double-precision number .\" toc@\f4atof()\fP:\0\0convert string to double-precision number@@@see \f3strtod(3C)\f1 .\" .\" links@strtod.3c atof.3c .\" links@strtod.3c nl_strtod.3c .\" links@strtod.3c nl_atof.3c .\" $Header: nl_tools_16.3x,v 72.2 94/11/30 15:24:00 ssa Exp $ .TA n .TH nl_tools_16 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl_tools_16: ADVANCE(), byte_status(), BYTE_STATUS(), CHARADV(), CHARAT(), c_colwidth(), C_COLWIDTH(), firstof2(), FIRSTof2(), secof2(), SECof2(), WCHAR(), WCHARADV() \- tools to process 16-bit characters .SH SYNOPSIS .C "#include " .PP .C "int firstof2(int c);" .PP .C "int secof2(int c);" .PP .C "int byte_status(int c, int laststatus);" .PP .C int c_colwidth(int c); .PP .C "int FIRSTof2(int c);" .PP .C "int SECof2(int c);" .PP .C "int BYTE_STATUS(int c, int laststatus);" .PP .C "int C_COLWIDTH(int c);" .PP .C "int CHARAT(const char *p);" .PP .C "int ADVANCE(const char *p);" .PP .C "int CHARADV(const char *p);" .PP .C "int WCHAR(wchar_t wc, char *p);" .PP .C "int WCHARADV(wchar_t wc, char *p);" .PP .C "void PCHAR(int c, char *p);" .PP .C "void PCHARADV(int c, char *p);" .SS Remarks All interfaces listed above whose names begin with a capital letter are implemented as macros; the others are functions. .PP These macros and functions are obsolete. See WARNINGS. .SH DESCRIPTION The following macros and functions perform their operations based upon the loaded NLS environment (see .IR setlocale (3C)). .TP 20 .CR FIRSTof2() Takes a byte and returns a nonzero value if it can be the first byte of a two-byte character according to the NLS environment loaded, and zero if it cannot. .TP .CR SECof2() Takes a byte and returns a nonzero value if it can be the second byte of a two-byte character according to the loaded NLS environment, and zero if it cannot. .TP .CR BYTE_STATUS() Returns one of the following values based on the value of the current byte in .I c and the status of the previous byte interpreted in .I laststatus as returned by the last call to .CR BYTE_STATUS() . These are the status values as defined in .CR : .RS .RS .TP 15 .CR ONEBYTE Single-byte character .PD 0 .TP .CR SECOF2 Second byte of two-byte character .TP .CR FIRSTOF2 First byte of two-byte character .RE .RE .PD .IP To validate a two-byte character, both the first and second bytes must be valid. If the value of .I laststatus is .CR FIRSTOF2 but .CR SECof2( c ) returns false, .CI BYTE_STATUS( c , \ laststatus ) returns .CR ONEBYTE . .TP .CR C_COLWIDTH() Takes a byte which is assumed to be either a one-byte character or the first byte of a two-byte character, and returns the number of columns the character would occupy on a terminal display. .IP For the macros .CR BYTE_STATUS() , .CR C_COLWIDTH() , .CR FIRSTof2() , and .CR SEC0of2() , results are undefined for values of .I c less than \(mi1 (EOF) or greater than 255. .TP .CR CHARAT() Takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case, .CR CHARAT() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p . .TP .CR ADVANCE() Advances its pointer argument by the byte width of the character it is pointing at (either one or two bytes). .TP .CR CHARADV() Combines the functions of .CR CHARAT() and .CR ADVANCE() in a single macro. It takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case .CR CHARADV() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p , and advances .I p beyond the last byte of the character. .TP .CR WCHAR() Converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p . .CR WCHAR() returns the .CR wchar_t value .IR wc . .TP .CR WCHARADV() Combines the functions of .CR WCHAR() and .CR ADVANCE() in a single macro. It converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p , then advances .I p past the last byte. .CR WCHARADV() returns the .CR wchar_t value .IR wc . .TP .CR firstof2() .PD 0 .TP .CR secof2() .TP .CR byte_status() .TP .CR c_colwidth() .PD Subroutine versions of the corresponding macros. These functions can be called from languages other than C. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of single and/or multibyte characters. .SH WARNINGS The HP proprietary functions and macros described in this manual entry are .BR OBSOLETE . They are not portable to other vendor's systems, and will not be provided in future HP-UX releases. .PP For maximum portability, use the routines documented in the .IR multibyte (3C) manual entry for multibyte character processing. .PP Other macros listed in this manual entry cannot be used as the first argument to .CR WCHAR() or .CR WCHARADV() . For example, .IP .C "*t++ = *f++" .PP cannot be replaced by .IP .C "WCHARADV(CHARADV (f),t)" .PP Instead, use a method such as .IP .CR "int c; " ...\& " c = CHARADV (f)," .CR "WCHARADV (c,t)" .PP .CR WCHAR() and .CR WCHARADV() may produce a "null effect" warning from .IR lint (1) if not used as part of another expression or as part of a statement. This does not affect the functionality of either macro. .PP Note that .CR WCHAR() and .CR WCHARADV() are not "replace_char" macros. They do not prevent the second byte of a two-byte character from being left dangling if .CR WCHAR() or .CR WCHARADV() overwrite the first byte of the two-byte character with a single-byte character. .PP .CR CHARAT() , .CR ADVANCE() , and .CR CHARADV() do not examine the byte following the location pointed to by the argument to verify its validity as a .CR SECof2 byte. .SH AUTHOR .CR nl_tools_16() was developed by HP. .SH SEE ALSO setlocale(3C), multibyte(3C), wconv(3X), wctype(3X), hpnls(5). .\" .\" index@\f4ADVANCE()\f1 \- advance pointer to next 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARADV()\f1 \- get character and advance pointer to next character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARAT()\f1 \- get value of 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHAR()\f1, \- put 8- or 16-bit character in memory@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHARADV()\f1, \- put character in memory and advance pointer@@@\f3nl_tools_16(3X)\f1 .\" index@\f4byte_status()\f1, \f4BYTE_STATUS()\f1 \- test for valid 1- or 2-byte character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4firstof2()\f1, \f4FIRSTof2()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4secof2()\f1, \f4SECof2()\f1 \- test for valid second byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f1characters, tools to process 16-bit@@@\f3nl_tools_16(3X)\f1 .\" index@\f1process 16-bit characters, tools to@@@\f3nl_tools_16(3X)\f1 .\" index@\f1sixteen-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f116-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f1tools to process 16-bit characters@@@\f3nl_tools_16(3X)\f1 .\" .\" links@nl_tools_16.3x ADVANCE.3x .\" links@nl_tools_16.3x BYTE_STATUS.3x .\" links@nl_tools_16.3x CHARADV.3x .\" links@nl_tools_16.3x CHARAT.3x .\" links@nl_tools_16.3x FIRSTof2.3x .\" links@nl_tools_16.3x SECof2.3x .\" links@nl_tools_16.3x WCHAR.3x .\" links@nl_tools_16.3x WCHARADV.3x .\" links@nl_tools_16.3x byte_status.3x .\" links@nl_tools_16.3x c_colwidth.3x .\" links@nl_tools_16.3x firstof2.3x .\" links@nl_tools_16.3x secof2.3x .\" .\" toc@\f3nl_tools_16(3X)\f1:\0\0\f4ADVANCE()\f1, \f4byte_status()\f1, \f4BYTE_STATUS()\f1, \f4CHARADV()\f1,\n\f4CHARAT()\f1, \f4C_COLWIDTH()\f1, \f4c_colwidth()\f1, \f4firstof2()\f1, \f4FIRSTof2()\f1,\n\f4secof2()\f1, \f4SECof2()\f1, \f4WCHAR()\f1, \f4WCHARADV()\f1@@@tools to process 16-bit characters .\" toc@\f4ADVANCE()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4byte_status()\f1, \f4BYTE_STATUS()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARAT()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4firstof2()\f1, \f4FIRSTof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4secof2()\f1, \f4SECof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHAR()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" $Header: nlappend.3x,v 72.3 93/01/14 14:37:02 ssa Exp $ .TA n .TH nlappend 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlappend(\|) \- append the appropriate language identification to a valid MPE file name .SH SYNOPSIS .C "#include " .PP .C "void nlappend(" .nf .PD 0 .IP .C "char *filename," .C "short int langid," .C "unsigned short int err[2]" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlappend() replaces the first three blanks found in .I filename with the language number. Its purpose is to identify the language of a file in an operating system-independent manner. .PP Arguments to .C nlappend() are used as follows: .RS .TP 15 .I filename A string of up to eight .SM ASCII characters terminated by three blanks. .TP .I langid A short integer specifying the language .SM ID. .TP .I err The first element contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 4 .I Filename is not terminated by 3 blanks. .RE .RE .PD .RE .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlappend() was developed by HP. .SH SEE ALSO portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlappend()\fP \- append language \s-1ID\s+1 to valid \s-1MPE\s+1 file name@@@\f3nlappend(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: append language \s-1ID\s+1 to valid \s-1MPE\s+1 file name@@@\f3nlappend(3X)\f1 .\" .\" toc@\f3nlappend(3X)\f1:\0\0\f4nlappend()\fP@@@append appropriate language identification to valid \s-1MPE\s+1 file name .\" .\" fileset_database@nlappend.3x PROGRAMING-MAN .\" $Header: nlcollate.3x,v 72.3 93/01/14 14:37:08 ssa Exp $ .TA n .TH nlcollate 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlcollate(\|) \- compare two character strings according to the MPE language-dependent collating sequence .SH SYNOPSIS .C "#include " .P .C "void nlcollate(" .nf .PD 0 .IP .C "const char *string1," .C "const char *string2," .C "short int length," .C "short *result," .C "short int langid," .C "unsigned short int err[2]," .C "const char *collseq" .P .C ");" .PD .fi .SH DESCRIPTION .I nlcollate collates two character strings according to the collating sequence of the specified language. This routine's purpose is to determine a lexical ordering. It is not intended to be used for searching or matching. .PP If the .I collseq parameter points to the null address, and .I langid is specified as (or defaults to) a language in which binary collation is appropriate, the binary collation is used to compare the two indicated strings. Otherwise, the .I collseq array is used to determine the string-compare operation (note that this may be a binary collation). .PP Arguments to .C nlcollate() are as follows: .RS .TP 15 .I string1 One of the character strings to be collated. .TP .I string2 The second character string to be collated. .TP .I length The length of the string segments to be collated. .TP .I result The result of the character collation is stored in the short integer variable to which .I result points. .RS .RS .TP 10 .C \00 If .I string1 collates equal to .IR string2 . .PD 0 .TP .C -1 If .I string1 collates before .IR string2 . .TP .C \01 If .I string1 collates after .IR string2 . .RE .RE .PD .TP .I langid The language .SM ID indicating the collating sequence to be used for the collation. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid collating table entry. .TP .C 4 Invalid length parameter. .RE .RE .PD .TP .I collseq An array containing the collating sequence to be used, as returned from a call to .IR nlinfo (3X)'s .I itemnumber 11. .RE .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .I nlcollate was developed by HP. .SH SEE ALSO nlinfo(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlcollate()\fP \- compare strings; use \s-1MPE\s+1 language-dependent collating sequence@@@\f3nlcollate(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: compare strings; use \s-1MPE\s+1 language-dependent collating sequence@@@\f3nlcollate(3X)\f1 .\" .\" toc@\f3nlcollate(3X)\f1:\0\0\f4nlcollate()\fP@@@compare strings using \s-1MPE\s+1 language-dependent collating sequence .\" .\" fileset_database@nlcollate.3x PROGRAMING-MAN .\" $Header: nlconvclock.3x,v 72.3 93/01/14 14:37:14 ssa Exp $ .TA n .TH nlconvclock 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlconvclock(\|) \- check and convert time string to \s-1MPE\s0 internal format .SH SYNOPSIS .C "#include " .PP .C "unsigned int nlconvclock(" .nf .PD 0 .IP .C "const char *instr," .C "short int leninstr," .C "short int langid," .C "unsigned short int err[2]" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlconvclock() converts .I instr to a general time format as returned by .IR nlinfo (3X) .I itemnumber 3. This routine is the inverse of .IR nlfmtclock (3X). Note that the seconds and tenths of seconds are always set to zero. .PP The arguments to .C nlconvclock() are used as follows: .RS .TP 15 .I instr A character buffer containing the time to be converted. .TP .I leninstr An unsigned short specifying the length of the buffer. .TP .I langid A short containing the language .SM ID. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid time format. .TP .C 4 Invalid length. .RE .RE .PD .RE .SH RETURN VALUE .C nlconvclock() returns the time in the format: .sp .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|0#7#\|8#15 \&#_#_#_#_ #Hour of Day##Minute of Hour# \&#_#_#_#_ .TE .sp .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|16#23#\|24#31 \&#_#_#_#_ #Seconds##Tenths of Seconds# \&#_#_#_#_ .TE .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlconvclock() was developed by HP. .SH SEE ALSO clock(3X), nlfmtclock(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlconvclock()\fP \- check/convert time string to \s-1MPE\s+1 internal format@@@\f3nlconvclock(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: check/convert time string to \s-1MPE\s+1 internal format@@@\f3nlconvclock(3X)\f1 .\" .\" toc@\f3nlconvclock(3X)\f1:\0\0\f4nlconvclock()\fP@@@check and convert time string to \s-1MPE\s+1 internal format .\" .\" fileset_database@nlconvclock.3x PROGRAMING-MAN .\" $Header: nlconvcustd.3x,v 72.3 93/01/14 14:37:19 ssa Exp $ .TA n .TH nlconvcustdate 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlconvcustdate(\|) \- convert date string to \s-1MPE\s+1 packed date format .SH SYNOPSIS .C "#include " .PP .C "unsigned short nlconvcustdate(" .nf .PD 0 .IP .C "const char *instr," .C "short int leninstr," .C "short int langid," .C "unsigned short int err[2]" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlconvcustda() converts .I instr to a packed date format. This routine is the inverse of .IR nlfmtcustdate (3X). .PP Arguments to .C nlconvcustda() are as follows: .RS .TP 15 .I instr A character buffer containing the date to be converted. .TP .I leninstr A positive integer specifying the length of the string (in bytes). .TP .I langid A short containing the language .SM ID number. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid date format. .TP .C 4 Invalid string length. .RE .RE .PD .RE .SH RETURN VALUE The routine returns the date as an unsigned integer in the format: .sp .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|0#6#\|7#15 \&#_#_#_#_ #Year of Century##Day of Year# \&#_#_#_#_ .TE .SH WARNINGS This routine is provided for compatibility with .SM MPE, another .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlconvcustda() was developed by HP. .SH SEE ALSO calendar(3X), nlfmtcustdate(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlconvcustdate()\fP \- convert date string to \s-1MPE\s+1 packed date format@@@\f3nlconvcustdate(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: convert date string to \s-1MPE\s+1 packed date format@@@\f3nlconvcustdate(3X)\f1 .\" .\" toc@\f3nlconvcustdate(3X)\f1:\0\0\f4nlconvcustdate()\fP@@@convert date string to \s-1MPE\s+1 packed date format .\" .\" fileset_database@nlconvcustd.3x PROGRAMING-MAN .\" $Header: nlconvnum.3x,v 72.3 93/01/14 14:37:24 ssa Exp $ .TA n .TH nlconvnum 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlconvnum(\|) \- convert \s-1MPE\s0 native-language formatted number to \s-1ASCII\s0 number .SH SYNOPSIS .C "#include " .PP .C "void nlconvnum(" .nf .PD 0 .IP .C "short int langid," .C "const char *instr," .C "short int leninstr," .C "char *outstr," .C "short int *plenoutstr," .C "unsigned short int err[2]," .C "const char *numspec," .C "short int fmtmask," .C "short int *pdecimals" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlconvnum() converts a native-language formatted number to an .SM ASCII number, with an n-computer decimal separator .RC ( . ) and thousands separator .RC ( , ), to use for further conversion to .SM INTEGER, REAL, etc. .PP This routine converts the decimal separator and the thousands separators to the n-computer equivalent, or strips them, according to the value of .IR fmtmask . If .I fmtmask .CR and .C M_NUMBERSONLY is not zero, .I instr is validated as a number. If it is null, no validation takes place. .PP For languages using an alternate set of digits (currently only .CR arabic , which uses .SM HINDI digits), .C nlconvnum() also converts these digits to .SM ASCII digits so they can be recognized and used as numeric characters. .PP Arguments to .C nlconvnum() are as follows: .RS .TP 15 .I langid A language ID number. .TP .I instr A character buffer containing the native language formatted number to convert. Leading and trailing spaces are ignored. .TP .I leninstr Length, in bytes, of .IR instr . .TP .I outstr Output buffer; an array containing the converted output. The output is left-justified in the buffer, and .I plenoutstr contains the actual length of the converted number. .I outstring may refer to the same address as .IR instr . .TP .I plenoutstr A pointer to the length, in bytes, of .IR outstr . After a successful call to .IR nlconvnum , the short integer to which .I plenoutstr points contains the actual length of the converted number. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid length specified .RI ( leninstr or .IR plenoutstr ). .TP .C 4 Invalid number specified .RI ( instr ). .TP .C 7 Truncation has occurred .RI ( outstr is left partially formatted). .TP .C 8 Invalid .I numspec parameter. .TP .C 9 Invalid .I fmtmask parameter. .RE .RE .PD .TP .I numspec A character buffer, as returned from .IR nlnumspec , containing information about correct formatting. If this parameter is not null, .I langid is ignored and performance is improved (see the description of .IR nlnumspec ). .TP .I fmtmask An unsigned short specifying how to format the number. The default value is zero, which means substitution only, convert thousands separators, convert decimal separators, and that .I instr can contain any character. .RS .RS .TP 22 Value Description .TP .C M_STRIPTHOU Strip thousands separators. .PD 0 .TP .C M_STRIPDEC Strip decimal separators. .TP .C M_NUMBERSONLY .I instr contains a number. .RE .RE .PD .TP .I pdecimals Pointer to a variable in which the number of decimal places in the input number is returned. .RE .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for HP-UX NLS support. .SH AUTHOR .C nlconvnum() was developed by HP. .SH SEE ALSO nlfmtnum(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlconvnum()\fP \- convert \s-1MPE\s+1 native language formatted number to \s-1ASCII\s+1@@@\f3nlconvnum(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: convert \s-1MPE\s+1 native language formatted number to \s-1ASCII\s+1@@@\f3nlconvnum(3X)\f1 .\" .\" toc@\f3nlconvnum(3X)\f1:\0\0\f4nlconvnum()\fP@@@convert \s-1MPE\s+1 native language formatted number to \s-1ASCII\s+1 number .\" .\" fileset_database@nlconvnum.3x PROGRAMING-MAN .\" $Header: nlfindstr.3x,v 72.3 93/01/14 14:37:30 ssa Exp $ .TA n .TH nlfindstr 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlfindstr(\|) \- search for a string in another string using the MPE character set definition .SH SYNOPSIS .C "#include " .PP .C "short int nlfindstr(" .nf .PD 0 .IP .C "short int langid," .C "const char *string1," .C "short int length1," .C "const char *string2," .C "short int length2," .C "unsigned short int err[2]," .C "const char *charset" .PP .C "); .PD .fi .SH DESCRIPTION .C nlfindstr() searches for the first occurrence of a given string of characters in another character string. .PP Arguments to .C nlfindstr() are: .RS .TP 15 .I langid The .SM ID number of the desired language. .TP .I string1 A pointer to the character buffer to be searched. It can contain single-byte and two-byte characters. .TP .I length1 Length (in bytes) of .IR string1 . .TP .I string2 The character buffer for which to search. .TP .I length2 Length (in bytes) of .IR string2 . .I length2 must be less than or equal to .IR length1 . .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid .I length1 parameter. .PD 0 .TP .C 4 Invalid .I length2 parameter. .PD .RE .RE .TP .I charset A byte buffer containing the character set definition for the language to be used, as returned by .IR nlinfo (3X)'s .I itemnumber 12. .RE .SH RETURN VALUE .I offset is a short integer that holds the number of bytes into .I string1 where .I string2 was found. .C nlfindstr() returns \(mi1 if the string is not found. .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlfindstr() was developed by HP. .SH SEE ALSO nlinfo(3X), mpnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlfindstr()\fP \- search for string in a string using \s-1MPE\s+1 character set definition@@@\f3nlfindstr(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: search for string in a string using \s-1MPE\s+1 character set definition@@@\f3nlfindstr(3X)\f1 .\" .\" toc@\f3nlfindstr(3X)\f1:\0\0\f4nlfindstr()\fP@@@search for string in another string using \s-1MPE\s+1 character set definition .\" .\" fileset_database@nlfindstr.3x PROGRAMING-MAN .\" $Header: nlfmtcal.3x,v 72.3 93/01/14 14:37:35 ssa Exp $ .TA n .TH nlfmtcal 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlfmtcalendar(\|) \- format an MPE packed date using a localized format .SH SYNOPSIS .C "#include " .PP .C "void nlfmtcalendar(" .nf .PD 0 .IP .C "unsigned short int date," .C "char *outstr," .C "short int langid," .C "unsigned short int err[2]" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlfmtcal() formats the specified date in the localized custom version of the date format, but with no time information (see .IR nlfmtclock (3X)). For example: .IP FRI, OCT 2, 1987 .PP Arguments to .C nlfmtcal() are used as follows: .RS .TP 15 .I date An unsigned short indicating the date in the packed date format: .ifn .sp .ift .sp .5v .RS .RS .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|0#6#\|7#15 \&#_#_#_#_ #Year of Century##Day of Year# \&#_#_#_#_ .TE .RE .RE .TP .I outstr A character buffer in which the formatted date is returned. This buffer is 18 bytes long, and padded with blanks if necessary. .TP .I langid A short integer specifying the language whose custom is to be used. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid date format. .RE .RE .PD .RE .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlfmtcal() was developed by HP. .SH SEE ALSO calendar(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlfmtcalendar()\fP \- format \s-1MPE\s+1 packed date using localized format@@@\f3nlfmtcal(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: format \s-1MPE\s+1 packed date using localized format@@@\f3nlfmtcal(3X)\f1 .\" .\" toc@\f3nlfmtcal(3X)\f1:\0\0\f4nlfmtcalendar()\fP@@@format \s-1MPE\s+1 packed date using localized format .\" .\" fileset_database@nlfmtcal.3x PROGRAMING-MAN .\" $Header: nlfmtclock.3x,v 72.3 93/01/14 14:37:41 ssa Exp $ .TA n .TH nlfmtclock 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlfmtclock(\|) \- format \s-1MPE\s0 time of day using localized format .SH SYNOPSIS .C "#include " .PP .C "void nlfmtclock(" .nf .PD 0 .IP .C "unsigned int time," .C "char *outstr," .C "short int langid," .C "unsigned short int err[2]" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlfmtclock() formats the time of day obtained with the clock routine, according to the clock format defined for the specified language. .PP Arguments to .C nlfmtclock() are used as follows: .RS .TP 15 .I time An unsigned int obtained from the clock routine: .ifn .sp .ift .sp .5v .RS .RS .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|0#7#\|8#15 \&#_#_#_#_ #Hour of Day##Minute of Hour# \&#_#_#_#_ .TE .ifn .sp .ift .sp .5v .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|16#23#\|24#31 \&#_#_#_#_ #Seconds##Tenths of Seconds# \&#_#_#_#_ .TE .RE .RE .TP .I outstr An 8-byte buffer in which the formatted time of day is returned. .TP .I langid A short integer specifying the language whose clock format is to be used. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid time format. .RE .RE .PD .RE .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlfmtclock() was developed by HP. .SH SEE ALSO clock(3X), nlconvclock(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlfmtclock()\fP \- format \s-1MPE\s+1 time of day using localized format@@@\f3nlfmtclock(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: format \s-1MPE\s+1 time of day using localized format@@@\f3nlfmtclock(3X)\f1 .\" .\" toc@\f3nlfmtclock(3X)\f1:\0\0\f4nlfmtclock()\fP@@@format \s-1MPE\s+1 time of day using localized format .\" .\" fileset_database@nlfmtclock.3x PROGRAMING-MAN .\" $Header: nlfmtcustda.3x,v 72.3 93/01/14 14:37:47 ssa Exp $ .TA n .TH nlfmtcustdate 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlfmtcustdate(\|) \- format an MPE packed date using a custom date .SH SYNOPSIS .C "#include " .PP .C "void nlfmtcustdate(" .nf .PD 0 .IP .C "unsigned short int date," .C "char *outstr," .C "short int langid," .C "unsigned short int err[2]" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlfmtcustdate() converts the packed date format to the language-dependent custom date as specified in the language definition file. A custom date has an abbreviated format such as .C 10/21/87 or .CR 87.10.21 . .PP Arguments to .C nlfmtcustdate() are used as follows: .RS .TP 15 .I date An unsigned short containing the date in the packed date format: .ifn .sp .ift .sp .5v .RS .RS .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|0#6#\|7#15 \&#_#_#_#_ #Year of Century##Day of Year# \&#_#_#_#_ .TE .RE .RE .TP .I outstr A 13-byte buffer in which the formatted date is returned. .TP .I langid A short integer of the language whose custom date specification is to be used for the format. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid date format. .RE .RE .PD .RE .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlfmtcustdate() was developed by HP. .SH SEE ALSO calendar(3X), nlconvcustdate(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlfmtcustdate()\fP \- format \s-1MPE\s+1 packed date using custom date@@@\f3nlfmtcustdate(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: format \s-1MPE\s+1 packed date using custom date@@@\f3nlfmtcustdate(3X)\f1 .\" .\" toc@\f3nlfmtcustdate(3X)\f1:\0\0\f4nlfmtcustdate()\fP@@@format \s-1MPE\s+1 packed date using custom date .\" .\" fileset_database@nlfmtcustda.3x PROGRAMING-MAN .\" $Header: nlfmtdate.3x,v 72.3 93/01/14 14:37:52 ssa Exp $ .TA n .TH nlfmtdate 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlfmtdate(\|) \- format MPE date and time in a localized format .SH SYNOPSIS .C "#include " .PP .C "void nlfmtdate(" .nf .PD 0 .IP .C "unsigned short int date," .C "unsigned long int time," .C "char *outstr," .C "short int langid," .C "unsigned short int err[2]" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlfmtdate() formats the specified date and time in a localized custom version. For example: .IP .C "SUN, FEB 7, 1988 9:00 AM" .PP Arguments to .C nlfmtdate() are used as follows: .RS .TP 15 .I date An unsigned short indicating the date to be formatted in the packed date format: .ifn .sp .ift .sp .5v .RS .RS .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|0#6#\|7#15 \&#_#_#_#_ #Year of Century##Day of Year# \&#_#_#_#_ .TE .RE .RE .TP .I time An unsigned int indicating the time to be formatted. The double word is in the clock format: .ifn .sp .ift .sp .5v .RS .RS .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|0#7#\|8#15 \&#_#_#_#_ #Hour of Day##Minute of Hour# \&#_#_#_#_ .TE .ifn .sp .ift .sp .5v .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|16#23#\|24#31 \&#_#_#_#_ #Seconds##Tenths of Seconds# \&#_#_#_#_ .TE .RE .RE .TP .I outstr A 28-byte buffer in which the formatted date is returned. .TP .I langid A short containing the language .SM ID indicating the custom to be used. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid date format. .TP .C 4 Invalid time format. .RE .RE .PD .RE .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlfmtdate() was developed by HP. .SH SEE ALSO calendar(3X), clock(3X), nlfmtcal(3X), nlfmtclock(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlfmtdate()\fP \- format \s-1MPE\s+1 date and time in localized format@@@\f3nlfmtdate(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: format \s-1MPE\s+1 date and time in localized format@@@\f3nlfmtdate(3X)\f1 .\" .\" toc@\f3nlfmtdate(3X)\f1:\0\0\f4nlfmtdate()\fP@@@format \s-1MPE\s+1 date and time in localized format .\" .\" fileset_database@nlfmtdate.3x PROGRAMING-MAN .\" $Header: nlfmtlongca.3x,v 72.3 93/01/14 14:51:58 ssa Exp $ .TA n .TH nlfmtlongcal 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlfmtlongcal(\|) \- format an MPE packed date using a long calendar format .SH SYNOPSIS .C "#include " .PP .C "void nlfmtlongcal(" .nf .PD 0 .IP .C "unsigned short int date," .C "char *outstr," .C "short int langid," .C "unsigned short int err[2]" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlfmtlongcal() formats the supplied date according to the long calendar format. The formatting is done according to the template returned by .IR nlinfo (3X), .I itemnumber 30. .PP Arguments to .C nlfmtlongcal() are used as follows: .RS .TP 15 .I date A short integer value containing a date in the packed date format: .ifn .sp .ift .sp .5v .RS .RS .TS tab (#) ; l l r l r l l l l l l | l l | l s | l l l l l . Bits#\|0#6#\|7#15 \&#_#_#_#_ #Year of Century##Day of Year# \&#_#_#_#_ .TE .RE .RE .TP .I outstr A 36-byte buffer to which the formatted long calendar date is returned, padded with blanks if necessary. .TP .I langid An .SM ID number specifying which language-specific format is to be used. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid date format. .RE .RE .PD .RE .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlfmtlongcal() was developed by HP. .SH SEE ALSO calendar(3X), nlfmtcalendar(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlfmtlongcal()\fP \- format \s-1MPE\s+1 packed date using long calendar format@@@\f3nlfmtlongcal(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: format \s-1MPE\s+1 packed date using long calendar format@@@\f3nlfmtlongcal(3X)\f1 .\" .\" toc@\f3nlfmtlongcal(3X)\f1:\0\0\f4nlfmtlongcal()\fP@@@format \s-1MPE\s+1 packed date using long calendar format .\" .\" fileset_database@nlfmtlongca.3x PROGRAMING-MAN .\" $Header: nlfmtnum.3x,v 74.1 95/05/10 21:07:44 ssa Exp $ .TA n .TH nlfmtnum 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlfmtnum(\|) \- convert an ASCII number to an MPE language-specific formatted number .SH SYNOPSIS .C "#include " .PP .C "void nlfmtnum(" .nf .PD 0 .IP .C "short int langid," .C "const char *instr," .C "short int leninstr," .C "char *outstr," .C "short int *plenoutstr," .C "unsigned short int err[2]," .C "const char *numspec," .C "short int fmtmask," .C "short int decimals" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlfmtnum() converts a string containing an .SM ASCII number to a language-specific formatted number using the currency name/symbol, decimal separator, and thousands separators defined for the language. The string may contain the n-computer decimal separator .RC ( . ), thousands separator .RC ( , ), and a dollar sign .RC ( $ ). .PP This routine operates in two modes: substitution mode and formatting mode. The substitution mode (if .I fmtmask is zero) substitutes the native equivalent for .C . and .C , and, for .CR arabic , the alternate set of digits for .SM ASCII digits. The input is not validated as a number, and can contain several individual numbers. No justification takes place, and the output is left-truncated if .I outstr is shorter than .I instr (for example, .C 1,234.56 becomes .CR 234,56 ). .PP If .I fmtmask is not zero, the formatting mode formats the input according to .I fmtmask in addition to performing the substitution. In this mode the input is validated as a number and only .SM ASCII digits and .CR - , .CR + , .CR $ , .CR . , and .C , are allowed. Only one sign and one .C $ is allowed and they must be the first character(s) in .IR instr . Even if insertion (of thousands separators, etc.) is specified in .IR fmtmask , thousands separators and a decimal separator are still valid characters in the input. In this case they are substituted. If no justification is specified, the output is right-justified with the same number of trailing spaces as the input. Note that for languages written right-to-left, trailing spaces in the input are preserved as leading spaces in the output. If the output is truncated, it is left-truncated (for example, .C 1,234.56 becomes .CR .234,56 ). .PP Arguments to .C nlfmtnum() are used as follows: .RS .TP 15 .I langid A language .SM ID number specifying which language's formatting specifications to use for the formatting. .TP .I instr A byte array containing the n-computer formatted .SM ASCII number to be converted, for example, 123,456.78. Leading and trailing spaces are allowed. .TP .I leninstr Length, in bytes, of .IR instr . .TP .I outstr A byte buffer where the language-specific formatted number is returned. The decimal separator, thousands separator, and currency symbol/name are replaced according to the language definition, if present or inserted, or if specified by .IR fmtmask . .I outstr can reference the same address as .IR instr . .TP .I plenoutstr Length, in bytes, of .IR outstr . After a successful call, if specified by .I fmtmask (the two bits starting with bit 12 (from highest to lowest) are equal to .CR 3 ), .I plenoutstr returns the actual length, in bytes, of the formatted number. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured, .PD 0 .TP .C 3 Invalid length specified .RI ( leninstr or .IR \(**plenoutstr ). .TP .C 4 Invalid number specified .RI ( instr ). .TP .C 5 Invalid decimal point in number specified .RI ( instr ). .TP .C 6 Invalid thousand separators in number specified .RI ( instr ). .TP .C 7 Truncation has occurred .RI ( outstr is left partially formatted). .TP .C 8 Invalid .I numspec parameter. .TP .C 9 Invalid .I fmtmask parameter. .TP .C 10 Invalid .I decimals parameter. .PD .RE .RE .TP .I numspec A byte array, as returned from .CR nlnumspec() , containing formatting specifications for the specified language (currency symbol/name, decimal separator, etc.). If this parameter is not null, .I langid is ignored, and performance is improved. (See .IR nlnumspec (3X)). .TP .I fmtmask A short integer value specifying any formatting to be done on the input. The default value is zero, which means a simple substitution. .RS .RS .TP 20 Value Description .TP .C NULL Do not insert thousands separators. .br Do not insert decimal separator. .br No justification of the output. .TP .C M_INSTHOU Insert thousands separators. .PD 0 .TP .C M_INSDEC Insert decimal separator. .TP .C M_CURRENCY Insert currency name/symbol. .TP .C M_LEFTJUST The output is left-justified. .TP .C M_RIGHTJUST Right-justify the output. .TP .C M_RETLENGTH Left-justify the output and return the actual length of the formatted number in .I plenoutstr .RE .RE .PD .TP .I decimals An integer specifying where to insert the decimal separator. The value is ignored if .I fmtmask and .CR M_INSDEC are zero, or a decimal separator is present in the number. .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlfmtnum() was developed by HP. .SH SEE ALSO nlconvnum(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlfmtnum()\fP \- convert \s-1ASCII\s+1 number to \s-1MPE\s+1 language-specific formatted number@@@\f3nlfmtnum(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: convert \s-1ASCII\s+1 number to \n\s-1MPE\s+1 language-specific formatted number@@@\f3nlfmtnum(3X)\f1 .\" .\" toc@\f3nlfmtnum(3X)\f1:\0\0\f4nlfmtnum()\fP@@@convert \s-1ASCII\s+1 number to \s-1MPE\s+1 language-specific formatted number .\" .\" fileset_database@nlfmtnum.3x PROGRAMING-MAN .\" $Header: nlgetlang.3x,v 72.4 94/11/30 15:44:45 ssa Exp $ .TA n .TH nlgetlang 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlgetlang(\|) \- return the current user, data, or system default language .SH SYNOPSIS .C "#include " .PP .C "short int nlgetlang(short int function, unsigned short int err[2]);" .SH DESCRIPTION .C nlgetlang() looks for a .SM LANG string in the user's environment. If it finds it, it returns the corresponding integer as described in .IR lang (5). Otherwise, or if the value of .I function is not valid, it returns .I 0 and sets the .I err parameter. .PP Arguments to .C nlgetlang() are used as follows: .RS .TP 15 .I function A short integer that specifies which language is returned. .RS .RS .TP 10 Value Description .TP .C 1 User language .PD 0 .TP .C 2 Data language .TP .C 3 System default language .RE .RE .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 1 Native Language Support file(s) not found .PD 0 .TP .C 2 Specified language not configured .TP .C 3 Invalid .I function value .TP .C 4 No language specified for .C nlgetlang() to access .RE .RE .PD .RE .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .C nlgetlang() returns the language .SM ID as a short integer. In case of error, zero is returned. .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this function. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlgetlang() was developed by HP. .SH SEE ALSO getenv(3C), portnls(5). .\" .\" index@\f4nlgetlang()\fP \- return current user, data, or system default language@@@\f3nlgetlang(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: return current user, data, or system default language@@@\f3nlgetlang(3X)\f1 .\" .\" toc@\f3nlgetlang(3X)\f1:\0\0\f4nlgetlang()\fP@@@return current user, data, or system default language .\" .\" fileset_database@nlgetlang.3x PROGRAMING-MAN .\" $Header: nlinfo.3x,v 72.3 93/01/14 14:36:51 ssa Exp $ .TA n .TH nlinfo 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlinfo(\|) \- return MPE language-dependent information .SH SYNOPSIS .C "#include " .P .C "void nlinfo(" .nf .PD 0 .IP .C "short int itemnumber," .C "int *itemvalue," .C "short int *langid," .C "unsigned short int err[2]" .P .C ");" .PD .fi .SH DESCRIPTION .C nlinfo() returns such information as the format of the date, the radix character, the direction of the language, etc. .PP The .I itemnumber indicates the type of information the user has requested. The data is passed back in .IR itemvalue . .PP The arguments to .C nlinfo() are used as follows: .RS .TP 15 .I itemnumber A short integer of the item desired. This number specifies which item value is to be returned. See below for a list of item numbers. .TP .I itemvalue A pointer to an integer that contains the value of the item specified by the corresponding item number. The data type of the item value depends on the item itself. .TP .I langid A pointer to a short integer containing the language ID or, for .I itemnumber 22, the location in which the language ID is returned. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 1 Native Language Support file(s) not found .PD 0 .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Specified character set is not configured. .TP .C 10 .I itemnumber is out of range. .RE .RE .PD .RE .SS Item numbers The following is a list of the currently defined item numbers and the information returned. .TP 15 .I itemnumber Description .TP .C 1 An 18-byte buffer in which the calendar format is returned. .TP .C 2 A 13-byte buffer in which the custom date format is returned. .TP .C 3 An 8-byte buffer in which the clock specification is returned. .TP .C 4 A 48-byte buffer in which the month denotation abbreviation table is returned. The abbreviation of each month is 4 bytes long (with blank padding if necessary). The first 4 bytes are the abbreviation for January. .TP .C 5 A 144-byte array in which the month denotation table is returned. Each month denotation is 12 bytes long. The table starts with January. .TP .C 6 A 21-byte array in which the day of the week denotation abbreviation table is returned. Each weekday abbreviation is three bytes long. The first three bytes are the abbreviation for Sunday. .TP .C 7 An 84-byte array in which the day of the week denotation table is returned. Each weekday denotation is 12 bytes long. The table starts with Sunday. .TP .C 8 A 12-byte array in which the YES/NO responses are returned. The first 6 bytes contain the (upshifted) "YES" response; the second 6 bytes contain the (upshifted) "NO" response. .TP .C 9 A 2-byte array in which the symbols for decimal point and thousands indicator are returned. The first byte contains the decimal point, the second contains the thousands indicator. .TP .C 10 A 6-byte array in which the currency signs are returned. The first byte contains the currency sign used in the business formats, the second byte is either a numeric zero, which indicates that the currency symbol precedes the value, or a one, which indicates that a symbol follows the value. The next 4 bytes contain the fully qualified currency sign. .TP .C 11 An array in which the collating sequence table is returned. To determine the size of this array, the length must be determined by a call to .C nlinfo() with .I itemnumber 27. .TP .C 12 A 256-byte array in which the character set definition is returned. Each byte has numeric identification of the character type: .RS .RS .TP 10 .C 0 Numeric character .PD 0 .TP .C 1 Alphabetic lowercase character .TP .C 2 Alphabetic uppercase character .TP .C 3 Undefined graphic character .TP .C 4 Special character .TP .C 5 Control code .TP .C 6 First byte of a two-byte character .RE .RE .PD .TP .C 15 A 256-byte array in which the upshift table is returned. .TP .C 16 A 256-byte array in which the downshift table is returned. .TP .C 17 An array of unsigned shorts in which the language numbers of all configured languages are returned. The first element of this array contains the number of configured languages. The second word contains the language number of the first configured language, etc. The system default language is returned (the .I langid parameter, if specified, is insignificant). .TP .C 18 A short int in which true .RC ( -1 ) is returned if the specified language is supported (configured) on the system. Otherwise, false .RB ( 0 ) is returned. .TP .C 21 A 16-byte array in which the (uppercase) name of the specified language is returned. If the name contains less than 16 bytes, it is padded with blanks. .TP .C 22 The .I itemvalue contains a byte buffer containing a language name or language number (\c .SM ASCII digits) terminated by a blank. The array must contain less than or equal to 16 bytes. The .I langid (third) parameter is assigned the associated language .SM ID number. .TP .C 26 A short integer in which the class number of the specified language is returned. .TP .C 27 An integer in which the length (in two-byte units) of the collating sequence table corresponding to the specified language is returned. .TP .C 28 A short integer in which the length (in two-byte units) of the national dependent information table is returned. If no national table exists for the specified language, an error is returned. .TP .C 29 A byte buffer in which the national-dependent information table is returned. To determine the size of this array, the length must be obtained via a prior call to .C nlinfo() with .I itemnumber 28. .TP .C 30 A 36-byte array in which the long calendar format is returned. It may contain arbitrary text as well as the following descriptors: .RS .RS .TP 10 .C D 1 through 3 of these are to be replaced by that many bytes from the day abbreviation. .PD 0 .TP .C W 1 through 12 of these are to be replaced by that many bytes from the day of the week. .TP .C M 1 through 4 of these are to be replaced by that many bytes from the month abbreviation. .TP .C O 1 through 12 of these are to be replaced by that many bytes from the month of the year. .TP .C mm Numeric month of the year. .TP .C yy Numeric year of the century. .TP .C yyyy Numeric year of the century. .TP .C Nyy National year. .RE .RE .PD .IP In addition, a special literal character .C ~ (tilde) can be used to indicate that the following character should be taken literally in the format, even if it is one of the special characters above. .IP For example, a format could be: .RS .IP .ift \f4\s+1"WWWWWWWWW, OOOOOOOOO dd, A.~D. yyyy "\fP\s0 .ifn \f3"WWWWWWWWW, OOOOOOOOO dd, A.~D. yyyy "\fP .RE .IP This format in n-computer would result in the following: .RS .ift \f4\s+1"WEDNESDAY, NOVEMBER 21, A.D. 1984 "\fP\s0 .ifn \f3"WEDNESDAY, NOVEMBER 21, A.D. 1984 "\fP .RE .TP .C 31 A 16-byte array in which the currency name is returned. .TP .C 32 An 8-byte array, containing information about an Alternate set of digits (currently only used by .CR arabic ). .RS .RS .TP 10 Byte Description .TP .C 0\-1 Alternate digit indicator .br \h'.2i'0 \- No Alternate digits defined .br \h'.2i'1 \- Alternate digits defined .PD 0 .TP .C 2 The Alternate digit .C 0 .TP .C 3 The Alternate digit .C 9 .TP .C 4 The .C + used with Alternate digits .TP .C 5 The .C - used with Alternate digits .TP .C 6 The decimal separator used with Alternate digits .TP .C 7 The thousands separator used with Alternate digits .RE .RE .PD .TP .C 33 A 4-byte array, containing information about the direction of the language. .RS .RS .TP 10 Byte Description .TP .C "0 1" Language direction .br \h'.2i'0 \- Direction is "left-to-right" .br \h'.2i'1 \- Direction is "right-to-left" .PD 0 .TP .C 2 The ``right-to-left'' space .TP .C 3 Undefined .RE .RE .PD .TP .C 34 An unsigned short that returns the data ordering of the language. .RS .TP 10 .C 0 Keyboard order .PD 0 .TP .C 1 Left-to-Right screen order .TP .C 2 Right-to-Left screen order .RE .PD .TP .C 35 An unsigned short that returns the size of the character used by the language. .RS .RS .TP 10 .C 0 One-byte characters (8 bits) .PD 0 .TP .C 1 Two-byte characters (16 bits) .RE .RE .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for HP-UX NLS support. .SH AUTHOR .C nlinfo() was developed by HP. .SH SEE ALSO hpnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlinfo()\fP \- return \s-1MPE\s+1 language-dependent information@@@\f3nlinfo(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: return \s-1MPE\s+1 language-dependent information@@@\f3nlinfo(3X)\f1 .\" .\" toc@\f3nlinfo(3X)\f1:\0\0\f4nlinfo()\fP@@@return \s-1MPE\s+1 language-dependent information .\" .\" fileset_database@nlinfo.3x PROGRAMING-MAN .\" $Header: nlist.3c,v 72.5 94/11/15 09:55:34 ssa Exp $ .TA n .TH nlist 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlist(\|) \- get entries from name list .SH SYNOPSIS .C "#include " .PP .C "int nlist(const char *file_name, struct nlist *nl);" .SS Remarks The use of symbol table type and value information is inherently non-portable. Use of .C nlist() should reduce the effort required to port a program that uses such information, but complete portability across all .SM HP-UX implementations cannot be expected. .SH DESCRIPTION .C nlist() examines the name list in the executable file whose name is pointed to by .IR file_name , and selectively extracts a list of values and puts them in the array of .C nlist() structures pointed to by .IR nl . The array of .C nlist() structures initially contains only the names of variables. Once .C nlist() has been called, the variable names are augmented with types and values. The list is terminated by a null name, which consists of a null string in the variable-name position of the structure. The name list of the file is searched for each variable name. If the name is found, type and value information from the file is inserted into the name list structure. If the name is not found, type and value fields are set to zero. The structure .C nlist is defined in the include file .RC < nlist.h >. See .IR a.out (4) and .IR nlist (4) for further description of the symbol table structure. .PP The file must have the organization and symbol table described for an .C a.out file in .IR a.out (4). The information is extracted from the symbol table used by the loader, .IR ld (1). .PP On machines that have such a file, this subroutine is useful for examining the system name list kept in file .CR /stand/vmunix . In this way programs can obtain system addresses that are up to date. .SH RETURN VALUE All nlist structure fields are set to 0 if the file cannot be found or if it is not a valid object file containing a linker symbol table. .PP .C nlist() returns \-1 upon error; otherwise it returns 0. .SH WARNINGS The .RC < nlist.h > header file is automatically included by .RC < a.out.h > for compatibility. However, including .RC < a.out.h > is discouraged if the only information needed from .RC < a.out.h > is for use by .CR nlist() . If .RC < a.out.h > is included, the line .C #undef n_name may need to follow it. .SH SEE ALSO a.out(4), nlist(4). .SH STANDARDS CONFORMANCE .CR nlist() ": SVID2, SVID3" .\" .\" index@\f4nlist()\fP \- get entries from name list@@@\f3nlist(3C)\f1 .\" index@get: entries from name list@@@\f3nlist(3C)\f1 .\" index@name: get entries from name list@@@\f3nlist(3C)\f1 .\" index@entries from name list, get@@@\f3nlist(3C)\f1 .\" index@list, name, get entries from@@@\f3nlist(3C)\f1 .\" .\" toc@\f3nlist(3C)\f1:\0\0\f4nlist()\fP@@@get entries from name list .\" .\" fileset_database@nlist.3c PROGRAMING-MAN .\" $Header: nljudge.3x,v 74.1 95/05/10 21:08:21 ssa Exp $ .TA n .TH nljudge 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nljudge(\|) \- judge whether a character is a one-byte or multi-byte Asian character using \s-1MPE\s0 character definition table .SH SYNOPSIS .C "#include " .PP .C "short int nljudge(" .nf .PD 0 .IP .C "short int langid," .C "const char *instr," .C "short int length," .C "char *judgeflag," .C "unsigned short int err[2]," .C "const char *charset" .PP .C ");" .PD .fi .SH DESCRIPTION .C nljudge() judges whether or not a character is a one-byte or multi-byte Asian character. If it is a multi-byte character, .I judgeflag is set to .C 1 or .CR 2 . If it is a one-byte character, .I judgeflag is set to .CR 0 . .PP Any language number can be specified as the .I langid parameter. However, if the language specified uses only one-byte characters (see .IR nlinfo (3X)'s .I itemnumber 35), the .I judgeflag returns all zeroes. .PP Arguments to .C nljudge() are used as follows: .RS .TP 15 .I langid The .SM ID number for the desired language. .TP .I instr The character buffer to be judged. .TP .I length A short integer value specifying the number of bytes in .IR instr . .TP .I judgeflag A pointer to a char whose value is set to: .RS .RS .TP 10 .C 0 One-byte character .PD 0 .TP .C 1 First byte of a two-byte character .TP .C 2 Second byte of a two-byte character .TP .C 3 Invalid two-byte character .RE .RE .PD .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid string length. .TP .C 7 Invalid characters found in .IR instr . .RE .RE .PD .TP .I charset A character buffer containing the character set definition for the language to be used, as returned by .IR nlinfo (3X)'s .I itemnumber 12. If it doesn't point to a null address, the .I langid parameter is ignored, and this routine is more efficient. .SH RETURN VALUE .C nljudge() returns the number of multi-byte Asian characters that could be used to check if a string of character contains any Asian characters. .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nljudge() was developed by HP. .SH SEE ALSO nlinfo(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nljudge()\fP \- identify one- or multi-byte Asian character using \s-1MPE\s+1 character table@@@\f3nljudge(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: identify one- or multi-byte Asian character \nusing \s-1MPE\s+1 character table@@@\f3nljudge(3X)\f1 .\" .\" toc@\f3nljudge(3X)\f1:\0\0\f4nljudge()\fP@@@judge whether character is one- or multi-byte Asian using \s-1MPE\s+1 character table .\" .\" fileset_database@nljudge.3x PROGRAMING-MAN .\" $Header: nlkeycompar.3x,v 74.1 95/05/10 21:08:45 ssa Exp $ .TA n .TH nlkeycompare 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlkeycompare(\|) \- determine if a character array (key1) is almost equal to another (key2) using the MPE language-dependent collation table .SH SYNOPSIS .C "#include " .PP .C "void nlkeycompare(" .nf .PD 0 .IP .C "const char *key1," .C "short int length1," .C "const char *key2," .C "short int length2," .C "short int *presult," .C "short int langid," .C "unsigned short err[2]," .C "const unsigned short *collseq" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlkeycompare() determines if a character array (key1) is almost equal to another character array (key2). Two character arrays are considered almost equal when they differ only in case or accent priorities. For example, the arrays .C ABC and .C aBc are almost equal in English. .PP .C nlkeycompare() determines if a given character array can be collated before or after another character array of a different length. For example, .C nlkeycompare() examines the records in a file sorted in a given language and determines if the character array .C key1 can be found later on in the file as the leading substring of the sort key, if the value of the last record read is .C key2. .PP Arguments to .C nlkeycompare() are used as follows: .RS .TP 15 .I key1 A byte array being compared to .IR key2 . .TP .I length1 The length in bytes of .IR key1 . .I length1 must be less than .IR length2 . .TP .I key2 A byte array containing a character array to which to compare .IR key1 . .TP .I length2 The length in bytes of .IR key2 . .I length2 must be greater than .IR length1 . .TP .I presult A pointer to a short integer variable in which to return the result of the comparison. .RS .RS .TP 10 .C 0 The retrieved key2 matches the key1. .PD 0 .TP .C 1 The retrieved key2 does not match the key1. It is different only in case or accent priority. .TP .C 2 The retrieved key2 is less than the key1 (its collating order is before the desired one). .TP .C 3 The retrieved key2 is greater than the key1 (it collates after the desired key). .RE .RE .PD .TP .I langid The language .SM ID number indicating the collating sequence to be used for the compare. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid collating table entry. .TP .C 4 Invalid length parameter. .TP .C 7 .I length1 is greater than .IR length2 . .RE .RE .PD .TP .I collseq An array containing the collating sequence table as returned by .IR nlinfo (3X)'s .I itemnumber 11. .RE .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlkeycompare() was developed by HP. .SH SEE ALSO nlcollate(3X), nlinfo(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlkeycompare()\fP \- compare character arrays using \s-1MPE\s+1 collation table@@@\f3nlkeycompare(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: compare character arrays (key1, key2) \nusing \s-1MPE\s+1 collation table@@@\f3nlkeycompare(3X)\f1 .\" .\" toc@\f3nlkeycompare(3X)\f1:\n\f4nlkeycompare()\fP@@@compare character arrays (key1, key2) using \s-1MPE\s+1 collation table .\" .\" fileset_database@nlkeycompar.3x PROGRAMING-MAN .\" $Header: nlnumspec.3x,v 74.1 95/05/10 21:09:14 ssa Exp $ .TA n .TH nlnumspec 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlnumspec(\|) \- return information needed by \s-1MPE\s0 routines for formatting and converting numbers .SH SYNOPSIS .C "#include " .PP .C "void nlnumspec(short int langid, char *numspec, unsigned short err[2]);" .SH DESCRIPTION .C nlnumspec() returns the information needed for formatting and converting numbers. It combines several calls to .C nlinfo() in order to simplify the use of native language formatting. By calling .C nlnumspec() once, and passing the obtained information to .C nlfmtnum() and .CR nlconvnum() , implicit calls to .C nlnumspec() from .C nlfmtnum() and .C nlconvnum() are avoided and performance is improved. .PP .C nlnumspec() combines the functions of .IR nlinfo (3X)'s .IR itemnumber s 9, 10, 31, 32, and 33. The information is formatted where needed. For example, any spaces in the currency symbol/name are included. The currency symbol/name is the shortest non-blank descriptor, as returned from .IR nlinfo (3X) .IR itemnumber s 10 and 31. .PP .C nlnumspec() does not, apart from the mentioned formatting, provide any information not obtainable with .CR nlinfo() , but is included for the convenience of the user. For efficiency, the user of this routine calls it once, saves the result, and then calls .C nlfmtnum() and/or .C nlconvnum() multiple times. .PP Arguments to .C nlnumspec() are used as follows: .RS .TP 15 .I langid The .SM ID number of the desired language. .TP .I numspec A character buffer of at least 60 bytes in which the following information is returned: .RS .RS .TP 10 Byte Description .TP .C 00-01 Language .SM ID number. .PD 0 .TP .C 02-03 Alternate Digit Indicator: .br \h'.3i'0 \- No Alternate digits exist. .br \h'.3i'1 \- Alternate digits exist. .TP .C 04\-05 Language Direction Indicator. .br \h'.3i'0 \- The Language is ``left-to-right''. .br \h'.3i'1 \- The Language is ``right-to-left''. .TP .C 06\-07 The Alternate digit range (``0'', ``9''). .TP .C 08 Decimal separator (\c .SM ASCII\c -digits). .TP .C 09 Decimal separator (Alternate-digits). .TP .C 10 Thousands separator (\c .SM ASCII\c -digits). .TP .C 11 Thousands separator (Alternate-digits). .TP .C 12 ``+'' Alternate-digits. .TP .C 13 ``\(mi'' Alternate-digits. .TP .C 14 ``Right-to-left'' space. .TP .C 15 Reserved. .TP .C 16-17 Currency place. .br \h'.3i'0 \- Currency symbol precedes the number. .br \h'.3i'1 \- Currency symbol follows the number. .br \h'.3i'2 \- Currency symbol replaces the decimal separator. .TP .C 18-19 Length of Currency symbol (including any spaces). .TP .C 20-37 Currency symbol (including any spaces). .TP .C 38-39 Data ordering of the language. .TP .C 40-41 Size of character used by the language. .TP .C 42-59 Reserved. .RE .RE .PD .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .RE .RE .PD .RE .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlnumspec() was developed by HP. .SH SEE ALSO nlinfo(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlnumspec()\fP \- return number conversion/formatting information for \s-1MPE\s+1 routines@@@\f3nlnumspec(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: return number conversion/formatting information \nfor \s-1MPE\s+1 routines@@@\f3nlnumspec(3X)\f1 .\" .\" toc@\f3nlnumspec(3X)\f1:\0\0\f4nlnumspec()\fP@@@return number convert/format information for \s-1MPE\s+1 routines .\" .\" fileset_database@nlnumspec.3x PROGRAMING-MAN .\" $Header: nlrepchar.3x,v 74.1 95/05/10 21:09:35 ssa Exp $ .TA n .TH nlrepchar 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlrepchar(\|) \- replace non-displayable characters of a string using the MPE character set table .SH SYNOPSIS .C "#include " .PP .C "void nlrepchar(" .nf .PD 0 .IP .C "const char *instr," .C "char *outstr," .C "short int length," .C "char repchar," .C "short int langid," .C "unsigned short int err[2]," .C "const char *charset" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlrepchar() replaces all non-displayable characters in the input character buffer with the replacement character. Non-displayable characters are those of types 3 and 5, as returned by .IR nlinfo (3X), .I itemnumber 12. Native language characters of the supported character set are not replaced. .PP Arguments to .C nlrepchar() are used as follows: .RS .TP 15 .I instr A character buffer in which the non-displayable characters must be replaced. .TP .I outstr A character buffer to which the replaced character string is returned. .TP .I length A short integer specifying the length (in bytes) of .IR instr . .TP .I repchar A byte specifying the replacement character to be used. .TP .I langid A short integer value specifying the language .SM ID number of the language that determines the character set to be used. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid replacement character. .TP .C 4 Invalid length parameter. .TP .C 8 The value of .I outstr would overwrite .IR instr . .TP .C 10 Invalid Asian character. .RE .RE .PD .TP .I charset Contains the character set definition for the language to be used, as returned in .IR nlinfo (3X)'s .I itemnumber 12. If this parameter is supplied (i.e., not .SM NULL\c ), .I langid is ignored and this routine is much more efficient. .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlrepchar() was developed by HP. .SH SEE ALSO nlinfo(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlrepchar()\fP \- replace non-displayable string characters using \s-1MPE\s+1 character set table@@@\f3nlrepchar(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: replace non-displayable string characters \nusing \s-1MPE\s+1 character set table@@@\f3nlrepchar(3X)\f1 .\" .\" toc@\f3nlrepchar(3X)\f1:\0\0\f4nlrepchar()\fP@@@replace non-displayable characters \s-1MPE\s+1 character set table .\" .\" fileset_database@nlrepchar.3x PROGRAMING-MAN .\" $Header: nlscanmove.3x,v 72.3 93/01/14 14:38:03 ssa Exp $ .TA n .TH nlscanmove 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlscanmove(\|) \- move, scan and case-shift character strings using the \s-1MPE\s0 character set definition table .SH SYNOPSIS .C "#include " .PP .C "short int nlscanmove(" .nf .PD 0 .IP .C "const char *instr," .C "char *outstr," .C "short int flags," .C "int length," .C "short int langid," .C "unsigned short int err[2]," .C "const char *pcharset," .C "const char *pshift" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlscanmove() moves, scans and case-shifts character strings. .PP Arguments to .C nlscanmove() are used as follows: .RS .TP 15 .I instr A character buffer that acts as the source string of the scan or move functions. .TP .I outstr A character buffer that acts as the target. Note that if .I outstr is equal to .IR instr , this routine will act as scan. Otherwise, a move will be performed; see .I err below. .TP .I flags A flag defining the options for the routine invocation. This parameter defines the end condition for the scan or move. .RS .RS .TP 15 Value Description .TP .C M_L Select lowercase alphabetic characters. .TP .C M_U Select uppercase alphabetic characters. .TP .C M_N Select numeric characters. .TP .C M_S Select special characters. .TP .C M_WU By default .C nlscanmove() scans or moves characters while the character currently being scanned is one of those selected (i.e. upper, lower, numeric, special). If .C M_WU is used, .C nlscanmove() scans or moves characters until the character currently being scanned is one of those selected. .TP .C M_US Shift scanned or moved characters to the uppercase. .TP .C M_DS Shift scanned or moved characters to the lowercase. .TP .C M_OB Select one-byte characters. .TP .C M_TB Select two-byte (Asian) characters. .TP .C M_OB or M_TB Select both one- and two-byte characters. .RE .RE .TP .I length A short integer indicating the maximum number of valid bytes to be acted upon during the indicated option. .TP .I langid A short integer containing the language .SM ID number which implies the both the character set definitions of character attributes and the language specific shift. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Overlapping strings, .I instr overwrites .IR outstr . .TP .C 4 Invalid length parameter. .TP .C 7 The reserved part of .I flags is not zero. .TP .C 8 Both upshift and downshift request. .TP .C 9 Invalid table element. .TP .C 10 Invalid Asian character. .RE .RE .PD .TP .I pcharset A pointer to a character buffer containing the character set definition for the language to be used, as returned .IR nlinfo (3X)'s .I itemnumber 12. If not zero, the .I langid parameter is ignored, and this routine is much more efficient. This parameter is required for calls in which bits (12:4) of .I flags is neither .C 0 nor .CR 15 . .TP .I pshift A pointer to a character buffer containing shift information for a desired upshift or downshift (e.g., as returned in .IR nlinfo (3X)'s .I itemnumber 15 or 16). This parameter is used when bits (9:2) of .I flags is not .CR 0 . .RE .SH RETURN VALUE A short containing the number of bytes acted upon in the scan or move operation. .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlscanmove() was developed by HP. .SH SEE ALSO nlinfo(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlscanmove()\fP \- move, scan, case-shift strings using \s-1MPE\s+1 character set table@@@\f3nlscanmove(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: move, scan, case-shift strings using \s-1MPE\s+1 character set table@@@\f3nlscanmove(3X)\f1 .\" .\" toc@\f3nlscanmove(3X)\f1:\0\0\f4nlscanmove()\fP@@@move, scan and case shift character strings using \s-1MPE\s+1 character set table .\" .\" fileset_database@nlscanmove.3x PROGRAMING-MAN .\" $Header: nlsubstr.3x,v 76.1 95/06/20 14:54:18 ssa Exp $ .TA n .TH nlsubstr 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlsubstr(\|) \- extract substring of a string using the \s-1MPE\s0 character set definition table .SH SYNOPSIS .C "#include " .PP .C "void nlsubstr(" .nf .PD 0 .IP .C "const char *instring," .C "short int inlength," .C "char *outstring," .C "short *poutlength," .C "short int start," .C "short int movelength," .C "short int langid," .C "short int flags," .C "unsigned short int err[2]," .C "const unsigned short int *charset" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlsubstr() extracts a substring from .I instring and places the result in .IR outstring . .PP Arguments to .C nlsubstr() are used as follows: .RS .TP 15 .I instring The byte buffer from which the substring is extracted. The string can contain both one-byte and two-byte (Asian) characters. .TP .I inlength Length, in bytes, of .I instring .TP .I outstring Where the sub-string is placed. .TP .I poutlength Length, in bytes, of .IR outstring . After a successful call, the variable to which .I poutlength points contains the actual length of the sub-string moved to .IR outstring . .TP .I start The offset into .I instring where the sub-string starts. A value of zero is the beginning point. .TP .I movelength Length, in bytes, of the sub-string. .TP .I langid The .SM ID number of the desired language. .TP .I flags This flag word is used primarily with Asian languages. It is meaningless with one-byte oriented languages. .I flags is used to indicate the treatment of the case when the first byte of the sub-string is the second byte of a two-byte Asian character and in the case where the last byte in the sub-string is the first byte of a two-byte Asian character. .IP Selection of .CR nlsubstr() 's behavior if the first character is the second byte of an Asian character: .RS .RS .TP 16 Value Description .TP .C F_RETURNERR Return an error condition. .TP .C F_SPP1 Start from .IR start +1. .TP .C F_SPM1 Start from .IR start \-1. .TP .C F_SPBL Start from .IR start , but replace the character with a blank in .IR outstring . .TP .C F_SP Start from .IR start , regardless of the value of the first character. .RE .RE .PD .IP Selection of .CR nlsubstr() 's behavior if the last character is the first byte of an Asian character: .RS .RS .TP 16 Value Description .TP .C F_LMP1 Move until .IR movelength +1 is reached. .TP .C F_LMM1 Move until .IR movelength \-1 is reached. .TP .C F_LMBL Move until .I movelength is reached, but replace the character with a blank in .IR outstring . .TP .C F_LM Move until .I movelength is reached, regardless of the value of the last byte. .RE .RE .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 7 Invalid .IR inlength . .TP .C 8 Invalid .IR start . .TP .C 9 Invalid .IR movelength . .TP .C 11 Invalid value in .I flags bits (8:4). .TP .C 12 Invalid value for .I flags bits (12:4). .TP .C 13 The start position is the second byte of an Asian character, or an underflow condition occurred because of .IR flags . .TP .C 14 The end position is the first byte of an Asian character, or an overflow condition occurred because of .IR flags . .RE .RE .TP .I charset An array containing the character set definition for the language to be used, as returned by .IR nlinfo (3X)'s .I itemnumber 12. .PD .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlsubstr() was developed by HP. .SH SEE ALSO nlinfo(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlsubstr()\fP \- extract substring in string using \s-1MPE\s+1 character set table@@@\f3nlsubstr(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: extract substring in string using \s-1MPE\s+1 character set table@@@\f3nlsubstr(3X)\f1 .\" .\" toc@\f3nlsubstr(3X)\f1:\0\0\f4nlsubstr()\fP@@@extract substring using \s-1MPE\s+1 character set table .\" .\" fileset_database@nlsubstr.3x PROGRAMING-MAN .\" $Header: nlswitchbuf.3x,v 74.1 95/05/10 21:10:00 ssa Exp $ .TA n .TH nlswitchbuf 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nlswitchbuf(\|) \- convert a string of characters between phonetic order and screen order using the MPE character set definition table .SH SYNOPSIS .C "#include " .PP .C "void nlswitchbuf(" .nf .PD 0 .IP .C "short int langid," .C "const char *instr," .C "char *outstr," .C "short int length," .C "unsigned short int lefttoright," .C "unsigned short int err[2]" .PP .C ");" .PD .fi .SH DESCRIPTION .C nlswitchbuf() is useful for handling data from languages written from right-to-left (e.g., Middle Eastern languages). It is used by a program to convert a buffer that is in phonetic order (i.e., the order in which the characters would be typed at a terminal or spoken by a person) to screen order (i.e., the order in which the characters are displayed on a terminal screen or piece of paper), or vice-versa. Screen order is defined as right-to-left if the primary mode of the terminal or printer is from right-to-left (as when it is used principally for entering or displaying data from a right-to-left language). Otherwise, screen order is defined as left-to-right. .PP Phonetic order and screen order are, in general, not the same if .SM USASCII text is mixed with that from a right-to-left language. The relationship between phonetic order and screen order is further complicated by the Hindi digits in Arabic, which play a third role intermediate between .SM ASCII characters and characters of the right-to-left language. .PP Note that this is a somewhat special-purpose native language support routine. .C nlswitchbuf() is useful only for languages that are written from right-to-left, and which may occasionally mix left-to-right text (e.g., English) with right-to-left. Nonetheless, it can be used by a general-purpose (not specifically for handling right-to-left data) program. Such a program calls .C nlswitchbuf() to convert data from phonetic order to screen order and back again (for example, an editor that wants to track cursor movement on a terminal against a buffer of text in memory needs to do this). If the data is not that of a right-to-left language, this routine simply returns the same text unchanged, since for all other languages phonetic order and screen order are the same. .PP Arguments to .C nlswitchbuf() are: .RS .TP 15 .I langid The .SM ID number for the desired language. .TP .I instr The character buffer in phonetic order to be converted to screen order. .TP .I outstr The buffer in which the result of the conversion to screen order is returned. .I outstr and .I instr can reference the same address. .TP .I length The length, in characters, of the buffer to be converted. .TP .I lefttoright An unsigned short integer that specifies whether the implied primary mode of the data (i.e., the way it would be displayed on a terminal) is left-to-right .SM (TRUE) or right-to-left .SM (FALSE). This determines what the opposite language is and, therefore, strings of which characters get switched. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid string length. .RE .RE .PD .RE .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nlswitchbuf() was developed by HP. .SH SEE ALSO nlinfo(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nlswitchbuf()\fP \- convert string between phonetic and screen order using \s-1MPE\s+1 table@@@\f3nlswitchbuf(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: convert string between phonetic and \nscreen order using \s-1MPE\s+1 table@@@\f3nlswitchbuf(3X)\f1 .\" .\" toc@\f3nlswitchbuf(3X)\f1:\0\0\f4nlswitchbuf()\fP@@@convert string screen order using \s-1MPE\s+1 character set table .\" .\" fileset_database@nlswitchbuf.3x PROGRAMING-MAN .\" $Header: nltranslate.3x,v 72.3 93/01/14 14:38:54 ssa Exp $ .TA n .TH nltranslate 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nltranslate(\|) \- translate \s-1ASCII\s0 strings to \s-1EBCDIC\s0 using \s-1MPE\s0 conversion table .SH SYNOPSIS .C "#include " .PP .C "void nltranslate(" .nf .PD 0 .IP .C "short int code," .C "const char *instr," .C "char *outstr," .C "short int length," .C "short int langid," .C "unsigned short int err[2]," .C "const char *table" .PP .C ");" .PD .fi .SH DESCRIPTION .C nltranslate() translates a string of bytes from .SM EBCDIC to .SM ASCII or .SM ASCII to .SM EBCDIC, using the appropriate native language table. .PP Arguments to .C nltranslate() are used as follows: .RS .TP 15 .I code Specifies type of conversion: .RS .RS .TP 10 Value Meaning .TP .C 1 Convert .SM EBCDIC to .SM ASCII. .PD 0 .TP .C 2 Convert .SM ASCII to .SM EBCDIC. .RE .RE .PD .TP .I instr Byte buffer containing the input string to be translated. .TP .I outstr Byte buffer where the translated string is to be returned. .I instr and .I outstr can specify the same array. .TP .I length A short integer specifying the number of bytes of .I instr to be translated. .TP .I langid A short integer containing the .SM ID number of the language whose translation tables are to be used. .TP .I err The first element of this array contains the error number. The second element is always zero. If the call is successful, both elements contain zero. .RS .RS .TP 10 Error # Meaning .TP .C 2 Specified language is not configured. .PD 0 .TP .C 3 Invalid code specified. .TP .C 4 Invalid length parameter. .RE .RE .PD .TP .I table A 256-byte array that holds a translation table. Each byte contains the translation of the byte whose value is its index. This table is provided by the user. .RE .SH WARNINGS This routine is provided for compatibility with .SM MPE, a proprietary .SM HP operating system. See .IR portnls (5) for more information on the use of this routine. Use the Native Language Support routines for C programmers described by .IR hpnls (5) for .SM HP-UX NLS support. .SH AUTHOR .C nltranslate() was developed by HP. .SH SEE ALSO nlinfo(3X), portnls(5). .SH EXTERNAL INFLUENCES .SS International Code Set Support Single- and multi-byte character code sets are supported. .\" .\" index@\f4nltranslate()\fP \- translate \s-1ASCII\s+1 strings to \s-1EBCDIC\s+1 using \s-1MPE\s+1 conversion table@@@\f3nltranslate(3X)\f1 .\" index@\s-1MPE\s+1 Native Language Support: translate \s-1ASCII\s+1 strings to \s-1EBCDIC\s+1 using \s-1MPE\s+1 conversion table@@@\f3nltranslate(3X)\f1 .\" .\" toc@\f3nltranslate(3X)\f1:\0\0\f4nltranslate()\fP@@@translate \s-1ASCII\s+1 \s-1EBCDIC\s+1 using \s-1MPE\s+1 conversion table .\" .\" fileset_database@nltranslate.3x PROGRAMING-MAN .\" $Header: cbreak.3x,v 76.2 95/07/31 17:13:10 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH cbreak 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cbreak, nocbreak, noraw, raw \(em input mode control functions .SH SYNOPSIS .C "#include " .P .C "int cbreak(void);" .P .C "int nocbreak(void);" .P .C "int noraw(void);" .P .C "int raw(void);" .SH DESCRIPTION The .Fn cbreak function sets the input mode for the current terminal to \f2cbreak\f1 mode and overrides a call to .CR raw() . .P The .Fn nocbreak function sets the input mode for the current terminal to Cooked Mode without changing the state of ISIG and IXON. .P The .Fn noraw function sets the input mode for the current terminal to Cooked Mode and sets the ISIG and IXON flags. .P The .Fn raw function sets the input mode for the current terminal to Raw Mode. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" If the application is not certain what the input mode of the process was at the time it called .Fn initscr , it should use these functions to specify the desired input mode. .SH "SEE ALSO" \f3Input Mode\f1 in curses_intro, , .br \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Chapter 9, \f3General Terminal Interface\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn raw and .Fn noraw functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The argument list for all these functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3cbreak(3X)\f1:\0\0\f4cbreak()\f1, \f4nocbreak()\f1, \f4noraw()\f1, \f4raw()\f1@@@input mode control functions .\" toc@\f4nocbreak()\f1: input mode control functions@@@see \f3cbreak(3X)\f1 .\" toc@\f4raw()\f1: input mode control functions@@@see \f3cbreak(3X)\f1 .\" toc@\f4noraw()\f1: input mode control functions@@@see \f3cbreak(3X)\f1 .\" .\" index@\f4cbreak()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f4nocbreak()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f4raw()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f4noraw()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f1input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f1control functions, input mode@@@\f3cbreak(3X)\f1 .\" index@\f1functions, for input mode control@@@\f3cbreak(3X)\f1 .\" .\" links@cbreak.3x nocbreak.3x .\" links@cbreak.3x noraw.3x .\" links@cbreak.3x raw.3x .\" .\" fileset_database@cbreak.3x CURS-ENG-A-MAN .\" $Header: nodelay.3x,v 76.2 95/08/01 14:30:49 ssa Exp $ .TA n .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH nodelay 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nodelay \(em enable or disable block during read .SH SYNOPSIS .C "#include " .P .C "int nodelay(WINDOW *\f2win\fP, bool \f2bf\fP);" .SH DESCRIPTION The .Fn nodelay function specifies whether Delay Mode or No Delay Mode is in effect for the screen associated with the specified window. If \f2bf\f1 is TRUE, this screen is set to No Delay Mode. If \f2bf\f1 is FALSE, this screen is set to Delay Mode. The initial state is FALSE. .SH "RETURN VALUE" Upon successful completion, .Fn nodelay returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, getch(), halfdelay(), , \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Section 9.2, \f3Parameters That Can Be Set\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" index@\f4nodelay()\f1 \- enable or disable block during read@@@\f3nodelay(3X)\f1 .\" index@\f1enable or disable block during read@@@\f3nodelay(3X)\f1 .\" index@\f1disable/enable block during read@@@\f3nodelay(3X)\f1 .\" index@\f1block, enable or disable during read@@@\f3nodelay(3X)\f1 .\" index@\f1read, enable or disable block during@@@\f3nodelay(3X)\f1 .\" .\" toc@\f3nodelay(3X)\f1:\0\0\f4nodelay()\f1@@@enable/disable block during read .\" .\" fileset_database@nodelay.3x CURS-ENG-A-MAN .\" $Header: echo.3x,v 76.2 95/07/31 17:42:26 ssa Exp $ .TA e .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH echo 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME echo, noecho \(em enable/disable terminal echo .SH SYNOPSIS .C "#include " .P .C "int echo(void);" .P .C "int noecho(void);" .SH DESCRIPTION The .Fn echo function enables Echo mode for the current screen. The .Fn noecho function disables Echo mode for the current screen. Initially, curses software echo mode is enabled and hardware echo mode of the tty driver is disabled. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, getch(), , \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Section 9.2, \f3Parameters That Can Be Set\f1. .SH "CHANGE HISTORY" First released in Issue . .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn echo and .Fn noecho functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3echo(3X)\f1:\0\0\f4echo()\f1, \f4noecho()\f1@@@enable/disable terminal echo .\" toc@\f4noecho()\f1: enable/disable terminal echo@@@see \f3echo(3X)\f1 .\" .\" index@\f4echo()\f1 \- enable/disable terminal echo@@@\f3echo(3X)\f1 .\" index@\f4noecho()\f1 \- enable/disable terminal echo@@@\f3echo(3X)\f1 .\" index@\f1enable/disable terminal echo@@@\f3echo(3X)\f1 .\" index@\f1disable/enable terminal echo@@@\f3echo(3X)\f1 .\" index@\f1terminal echo, enable/disable@@@\f3echo(3X)\f1 .\" .\" links@echo.3x noecho.3x .\" .\" fileset_database@echo.3x CURS-ENG-A-MAN .\" $Header: nl.3x,v 76.2 95/08/01 14:29:57 ssa Exp $ .TA n .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH nl 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl, nonl \(em enable/disable newline translation .SH SYNOPSIS .C "#include " .P .C "int nl(void);" .P .C "int nonl(void);" .SH DESCRIPTION The .Fn nl function enables a mode in which carriage return is translated to newline on input. The .Fn nonl function disables the above translation. Initially, the above translation is enabled. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The default translation adapts the terminal to environments in which newline is the line termination character. However, by disabling the translation with .Fn nonl , the application can sense the pressing of the carriage return key. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn nl and .Fn nonl functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3nl(3X)\f1:\0\0\f4nl()\f1, \f4nonl()\f1@@@enable/disable newline translation .\" toc@\f4nonl()\f1: enable/disable newline translation@@@see \f3nl(3X)\f1 .\" .\" index@\f4nl()\f1 \- enable/disable newline translation@@@\f3nl(3X)\f1 .\" index@\f4nonl()\f1 \- enable/disable newline translation@@@\f3nl(3X)\f1 .\" index@\f1enable/disable newline translation@@@\f3nl(3X)\f1 .\" index@\f1disable/enable newline translation@@@\f3nl(3X)\f1 .\" index@\f1newline translation, enable/disable@@@\f3nl(3X)\f1 .\" .\" links@nl.3x nonl.3x .\" .\" fileset_database@nl.3x CURS-ENG-A-MAN .\" $Header: noqiflush.3x,v 76.2 95/08/01 14:31:36 ssa Exp $ .TA n .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH noqiflush 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME noqiflush, qiflush \(em enable/disable queue flushing .SH SYNOPSIS .C "#include " .P .C "void noqiflush(void);" .P .C "void qiflush(void);" .SH DESCRIPTION The .Fn qiflush function causes all output in the display driver queue to be flushed whenever an interrupt key (interrupt, suspend, or quit) is pressed. The .Fn noqiflush causes no such flushing to occur. The default for the option is inherited from the display driver settings. .SH "RETURN VALUE" These functions do not return a value. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Calling .Fn qiflush provides faster response to interrupts, but causes Curses to have the wrong idea of what is on the screen. The same effect is achieved outside Curses using the NOFLSH local mode flag specified in the \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification (\f3General Terminal Interface\fP). .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, intrflush(), , \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Section 9.2, \f3Parameters That Can Be Set\f1 (NOFLSH flag). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3noqiflush(3X)\f1:\0\0\f4noqiflush()\f1, \f4qiflush()\f1@@@enable/disable queue flushing .\" toc@\f4qiflush()\f1: enable/disable queue flushing@@@see \f3noqiflush(3X)\f1 .\" .\" index@\f4noqiflush()\f1 \- enable/disable queue flushing@@@\f3noqiflush(3X)\f1 .\" index@\f4qiflush()\f1 \- enable/disable queue flushing@@@\f3noqiflush(3X)\f1 .\" index@\f1enable/disable queue flushing@@@\f3noqiflush(3X)\f1 .\" index@\f1disable/enable queue flushing@@@\f3noqiflush(3X)\f1 .\" index@\f1queue flushing, enable/disable@@@\f3noqiflush(3X)\f1 .\" index@\f1flushing queue, enable/disable@@@\f3noqiflush(3X)\f1 .\" .\" links@noqiflush.3x qiflush.3x .\" .\" fileset_database@noqiflush.3x CURS-ENG-A-MAN .\" $Header: cbreak.3x,v 76.2 95/07/31 17:13:10 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH cbreak 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cbreak, nocbreak, noraw, raw \(em input mode control functions .SH SYNOPSIS .C "#include " .P .C "int cbreak(void);" .P .C "int nocbreak(void);" .P .C "int noraw(void);" .P .C "int raw(void);" .SH DESCRIPTION The .Fn cbreak function sets the input mode for the current terminal to \f2cbreak\f1 mode and overrides a call to .CR raw() . .P The .Fn nocbreak function sets the input mode for the current terminal to Cooked Mode without changing the state of ISIG and IXON. .P The .Fn noraw function sets the input mode for the current terminal to Cooked Mode and sets the ISIG and IXON flags. .P The .Fn raw function sets the input mode for the current terminal to Raw Mode. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" If the application is not certain what the input mode of the process was at the time it called .Fn initscr , it should use these functions to specify the desired input mode. .SH "SEE ALSO" \f3Input Mode\f1 in curses_intro, , .br \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Chapter 9, \f3General Terminal Interface\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn raw and .Fn noraw functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The argument list for all these functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3cbreak(3X)\f1:\0\0\f4cbreak()\f1, \f4nocbreak()\f1, \f4noraw()\f1, \f4raw()\f1@@@input mode control functions .\" toc@\f4nocbreak()\f1: input mode control functions@@@see \f3cbreak(3X)\f1 .\" toc@\f4raw()\f1: input mode control functions@@@see \f3cbreak(3X)\f1 .\" toc@\f4noraw()\f1: input mode control functions@@@see \f3cbreak(3X)\f1 .\" .\" index@\f4cbreak()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f4nocbreak()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f4raw()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f4noraw()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f1input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f1control functions, input mode@@@\f3cbreak(3X)\f1 .\" index@\f1functions, for input mode control@@@\f3cbreak(3X)\f1 .\" .\" links@cbreak.3x nocbreak.3x .\" links@cbreak.3x noraw.3x .\" links@cbreak.3x raw.3x .\" .\" fileset_database@cbreak.3x CURS-ENG-A-MAN .\" $Header: notimeout.3x,v 76.2 95/08/01 14:32:46 ssa Exp $ .TA n .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH notimeout 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME notimeout, timeout, wtimeout \(em control blocking on input .SH SYNOPSIS .C "#include " .P .C "int notimeout(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "void timeout(int \f2delay\fP);" .P .C "void wtimeout(WINDOW *\f2win\fP, int \f2delay\fP);" .SH DESCRIPTION The .Fn notimeout function specifies whether Timeout Mode or No Timeout Mode is in effect for the screen associated with the specified window. If \f2bf\f1 is TRUE, this screen is set to No Timeout Mode. If \f2bf\f1 is FALSE, this screen is set to Timeout Mode. The initial state is FALSE. .P The .Fn timeout and .Fn wtimeout functions set blocking or non-blocking read for the current or specified window based on the value of \f2delay\fP: .RS .TP 15 .C "\f2delay\fP\0<\00" One or more blocking reads (indefinite waits for input) are used. .TP .C "\f2delay\fP\0=\00" One or more non-blocking reads are used. Any Curses input function will fail if every character of the requested string is not immediately available. .TP .C "\f2delay\fP\0>\00" Any Curses input function blocks for \f2delay\f1 milliseconds and fails if there is still no input. .RE .SH "RETURN VALUE" Upon successful completion, the .Fn notimeout function returns OK. Otherwise, it returns ERR. .P The .Fn timeout and .Fn wtimeout functions do not return a value. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, getch(), halfdelay(), nodelay(), , \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Section 9.2, \f3Parameters That Can Be Set\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3notimeout(3X)\f1:\0\0\f4notimeout()\f1, \f4timeout()\f1, \f4wtimeout()\f1@@@control blocking on input .\" toc@\f4timeout()\f1: control blocking on input@@@see \f3notimeout(3X)\f1 .\" toc@\f4wtimeout()\f1: control blocking on input@@@see \f3notimeout(3X)\f1 .\" .\" index@\f4notimeout()\f1 \- control blocking on input@@@\f3notimeout(3X)\f1 .\" index@\f4timeout()\f1 \- control blocking on input@@@\f3notimeout(3X)\f1 .\" index@\f4wtimeout()\f1 \- control blocking on input@@@\f3notimeout(3X)\f1 .\" index@\f1control blocking on input@@@\f3notimeout(3X)\f1 .\" index@\f1blocking on input, control@@@\f3notimeout(3X)\f1 .\" index@\f1input, control blocking on@@@\f3notimeout(3X)\f1 .\" .\" links@notimeout.3x timeout.3x .\" links@notimeout.3x wtimeout.3x .\" .\" fileset_database@notimeout.3x CURS-ENG-A-MAN .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: byteorder.3n,v 78.1 96/03/15 15:46:29 ssa Exp $ .TA b .TH byteorder 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME htonl(\|), htons(\|), ntohl(\|), ntohs(\|) \- convert values between host and network byte order .SH SYNOPSIS .nf .PP .C #include .PP .C _XOPEN_SOURCE_EXTENDED only .C #include .PP .C "unsigned long htonl(unsigned long hostlong);" .PP .C "unsigned short htons(unsigned short hostshort);" .PP .C "unsigned long ntohl(unsigned long netlong);" .PP .C "unsigned short ntohs(unsigned short netshort);" .fi .SH DESCRIPTION These routines convert 16- and 32-bit quantities between network byte order and host byte order. On HP-UX systems, network and host byte orders are identical, so these routines are defined as null macros in the include file .RC < netinet/in.h >. If _XOPEN_SOURCE_EXTENDED is defined then these routines are defined in the include file .RC < arpa/inet.h>. .PP These routines are most often used in conjunction with Internet addresses and ports as returned by .C gethostent() and .C getservent() (see .IR gethostent (3N) and .IR getservent (3N)). Use these routines to write portable programs. .SH AUTHOR .C byteorder() was developed by the University of California, Berkeley. .SH SEE ALSO gethostent(3N), getservent(3N). .SH STANDARDS CONFORMANCE .CR byteorder() ": XPG4" .\" .\" index@\f4htonl()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4htons()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4ntohl()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4ntohs()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1values, convert between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1host and network byte order, convert values between@@@\f3byteorder(3N)\f1 .\" index@\f1network and host byte order, convert values between@@@\f3byteorder(3N)\f1 .\" index@\f1byte order, network and host, convert values between@@@\f3byteorder(3N)\f1 .\" .\" toc@\f3byteorder(3N)\f1:\0\0\f4htonl()\f1, \f4htons()\f1, \f4ntohl()\f1, \f4ntohs()\f1@@@convert values between host and network byte order .\" toc@\f4htonl()\f1, \f4htons()\f1:\0\0convert values from host to network byte order@@@see \f3byteorder(3N)\f1 .\" toc@\f4ntohl()\f1, \f4ntohs()\f1:\0\0convert values from network to host byte order@@@see \f3byteorder(3N)\f1 .\" .\" links@byteorder.3n htonl.3n .\" links@byteorder.3n htons.3n .\" links@byteorder.3n ntohl.3n .\" links@byteorder.3n ntohs.3n .\" $Header: byteorder.3n,v 78.1 96/03/15 15:46:29 ssa Exp $ .TA b .TH byteorder 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME htonl(\|), htons(\|), ntohl(\|), ntohs(\|) \- convert values between host and network byte order .SH SYNOPSIS .nf .PP .C #include .PP .C _XOPEN_SOURCE_EXTENDED only .C #include .PP .C "unsigned long htonl(unsigned long hostlong);" .PP .C "unsigned short htons(unsigned short hostshort);" .PP .C "unsigned long ntohl(unsigned long netlong);" .PP .C "unsigned short ntohs(unsigned short netshort);" .fi .SH DESCRIPTION These routines convert 16- and 32-bit quantities between network byte order and host byte order. On HP-UX systems, network and host byte orders are identical, so these routines are defined as null macros in the include file .RC < netinet/in.h >. If _XOPEN_SOURCE_EXTENDED is defined then these routines are defined in the include file .RC < arpa/inet.h>. .PP These routines are most often used in conjunction with Internet addresses and ports as returned by .C gethostent() and .C getservent() (see .IR gethostent (3N) and .IR getservent (3N)). Use these routines to write portable programs. .SH AUTHOR .C byteorder() was developed by the University of California, Berkeley. .SH SEE ALSO gethostent(3N), getservent(3N). .SH STANDARDS CONFORMANCE .CR byteorder() ": XPG4" .\" .\" index@\f4htonl()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4htons()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4ntohl()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f4ntohs()\f1 \- convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1convert values between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1values, convert between host and network byte order@@@\f3byteorder(3N)\f1 .\" index@\f1host and network byte order, convert values between@@@\f3byteorder(3N)\f1 .\" index@\f1network and host byte order, convert values between@@@\f3byteorder(3N)\f1 .\" index@\f1byte order, network and host, convert values between@@@\f3byteorder(3N)\f1 .\" .\" toc@\f3byteorder(3N)\f1:\0\0\f4htonl()\f1, \f4htons()\f1, \f4ntohl()\f1, \f4ntohs()\f1@@@convert values between host and network byte order .\" toc@\f4htonl()\f1, \f4htons()\f1:\0\0convert values from host to network byte order@@@see \f3byteorder(3N)\f1 .\" toc@\f4ntohl()\f1, \f4ntohs()\f1:\0\0convert values from network to host byte order@@@see \f3byteorder(3N)\f1 .\" .\" links@byteorder.3n htonl.3n .\" links@byteorder.3n htons.3n .\" links@byteorder.3n ntohl.3n .\" links@byteorder.3n ntohs.3n .\" $Header: directory.3c,v 76.1 95/07/05 17:28:05 ssa Exp $ .TA d .TH directory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME opendir(\|), readdir(\|), readdir_r(\|), telldir(\|), seekdir(\|), rewinddir(\|), closedir(\|) \- directory operations .SH SYNOPSIS .C "#include " .PP .C "DIR *opendir(const char *dirname);" .PP .C "struct dirent *readdir(DIR *dirp);" .PP .C "int readdir_r(DIR *dirp, struct dirent *result);" .PP .C "long int telldir(DIR *dirp);" .PP .C "void seekdir(DIR *dirp, long int loc);" .PP .C "void rewinddir(DIR *dirp);" .PP .C "int closedir(DIR *dirp);" .SH DESCRIPTION This library package provides functions that allow programs to read directory entries without having to know the actual directory format associated with the file system. Because these functions allow programs to be used portably on file systems with different directory formats, this is the recommended way to read directory entries. .TP 15 .CR opendir() opens the directory .I dirname and associates a directory stream with it. .CR opendir() returns a pointer used to identify the directory stream in subsequent operations. .CR opendir() uses .IR malloc (3C) to allocate memory. .TP .CR readdir() returns a pointer to the next directory entry. It returns a .SM NULL pointer upon reaching the end of the directory or detecting an invalid .CR seekdir() operation. See .IR dirent (5) for a description of the fields available in a directory entry. .TP .CR readdir_r() expects to be passed the address of a .CR "struct dirent" and will store the result at the supplied location. .TP .CR telldir() returns the current location (encoded) associated with the directory stream to which .IR dirp refers. .TP .CR seekdir() sets the position of the next .CR readdir() operation on the directory stream to which .IR dirp refers. The .IR loc argument is a location within the directory stream obtained from .CR telldir() . The position of the directory stream is restored to where it was when .CR telldir() returned that .I loc value. Values returned by .CR telldir() are valid only while the .CR DIR pointer from which they are derived remains open. If the directory stream is closed and then reopened, the .CR telldir() value might be invalid. .TP .CR rewinddir() resets the position of the directory stream to which .IR dirp refers to the beginning of the directory. It also causes the directory stream to refer to the current state of the corresponding directory, as a call to .CR opendir() would have done. .TP .CR closedir() closes the named directory stream, then frees the structure associated with the .CR DIR pointer. .SH RETURN VALUE .TP 15 .CR opendir() , upon successful completion, returns a pointer to an object of type .CR DIR referring to an open directory stream. Otherwise, it returns a .SM NULL pointer and sets the global variable .CR errno to indicate the error. .TP .CR readdir() , upon successful completion, returns a pointer to an object of type .CR struct dirent describing a directory entry. Upon reaching the end of the directory, .CR readdir() returns a .SM NULL pointer and does not change the value of .CR errno . Otherwise, it returns a .SM NULL pointer and sets .CR errno to indicate the error. .TP .CR readdir_r() , upon successful completion, returns a 0. Upon reaching the end of directory or encountering an error, it returns a -1 and sets .CR errno to indicate the error. .TP .CR telldir() , upon successful completion, returns a long value indicating the current position in the directory. Otherwise it returns .CR \-1 and sets .CR errno to indicate the error. .TP .CR seekdir() does not return any value, but if an error is encountered, .CR errno is set to indicate the error. .TP .CR closedir() , upon successful completion, returns a value of .CR 0 . Otherwise, it returns a value of .CR \-1 and sets .CR errno to indicate the error. .SH ERRORS .CR opendir() fails if any of the following conditions are encountered: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of .IR dirname , or read permission is denied for .IR dirname . .TP .SM [EFAULT] .I dirname points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the path name. .TP .SM [EMFILE] Too many open file descriptors are currently open for the calling process. .TP .SM [ENAMETOOLONG] A component of .IR dirname exceeds .CR PATH_MAX bytes, or the entire length of .IR dirname exceeds .CR PATH_MAX \(mi 1 bytes while .CR _POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] Too many open file descriptors are currently open on the system. .TP .SM [ENOENT] A component of .I dirname does not exist. .TP .SM [ENOMEM] .CR malloc() failed to provide sufficient memory to process the directory. .TP .SM [ENOTDIR] A component of .I dirname is not a directory. .TP .SM [ENOENT] The .IR dirname argument points to an empty string. .RE .PP .CR readdir() " or " readdir_r() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] The directory stream to which .IR dirp refers is not located at a valid directory entry. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR telldir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR seekdir() might fail if the following condition is encountered: .RS .TP 20 .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR closedir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP 20 .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR rewinddir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .SH EXAMPLES The following code searches the current directory for an entry .IR name : .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 DIR *dirp; struct dirent *dp; dirp = opendir("."); while ((dp = readdir(dirp)) != NULL) { if (strcmp(dp->d_name, name) == 0) { (void) closedir(dirp); return FOUND; } } (void) closedir(dirp); return NOT_FOUND; .ft .ps .fi .RE .SH WARNINGS .CR readdir() and .CR getdirentries() (see .IR getdirentries (2) are the only ways to access remote .SM NFS directories. Attempting to read a remote directory via .SM NFS by using .CR read() returns .CR \-1 and sets .CR errno to .SM EISDIR (see .IR read (2)). .PP .CR readdir() is unsafe in multi-thread applications. .CR readdir_r() is MT-Safe and should be used instead. Users of .CR readdir_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH APPLICATION USAGE The header file required for these functions and the type of the return value from .CR readdir() has been changed for compatibility with System V Release 3 and the .IR "X/Open Portability Guide" . See .IR ndir (5) for a description of the header file .RC < ndir.h >, which is provided to allow existing .SM HP-UX applications to compile unmodified. .PP New applications should use the .RC < dirent.h > header file for portability to System V and X/Open systems. .SH AUTHOR .CR directory was developed by AT&T, HP, and the University of California, Berkeley. .SH SEE ALSO close(2), getdirentries(2), lseek(2), open(2), read(2), dir(4), dirent(5), ndir(5). .SH STANDARDS CONFORMANCE .CR closedir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR opendir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR readdir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR rewinddir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR seekdir() ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR telldir() ": AES, XPG2, XPG3, XPG4" .\" .\" index@\f4opendir()\f1 \- open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f4readdir()\f1 \- get pointer to current entry in open directory@@@\f3directory(3C)\f1 .\" index@\f4telldir()\f1 \- get current location of named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4seekdir()\f1 \- set position of next \f4readdir()\f1 operation on named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4rewinddir()\f1 \- reset position of named \f2directory stream\f1 to beginning of directory@@@\f3directory(3C)\f1 .\" index@\f4closedir()\f1 \- close a currently open directory@@@\f3directory(3C)\f1 .\" index@open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f2directory stream\f1, directory and associated, open for access@@@\f3directory(3C)\f1 .\" index@open, access, or close a directory@@@\f3directory(3C)\f1 .\" index@close, access, or open a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@directory: access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" .\" toc@\f3directory(3C)\f1:\0\0\f4directory()\f1, \f4opendir()\f1, \f4readdir()\f1, \f4telldir()\f1, \f4seekdir()\f1, \f4rewinddir()\f1,\n\f4closedir()\f1@@@directory operations .\" toc@\f4opendir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4readdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4telldir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4seekdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4rewinddir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4closedir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" .\" links@directory.3c opendir.3c .\" links@directory.3c readdir.3c .\" links@directory.3c readdir_r.3c .\" links@directory.3c telldir.3c .\" links@directory.3c seekdir.3c .\" links@directory.3c rewinddir.3c .\" links@directory.3c closedir.3c .\" $Header: syslog.3c,v 76.1 95/07/05 17:52:44 ssa Exp $ .TA s .TH syslog 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME syslog(\|), openlog(\|), closelog(\|), setlogmask(\|) \- control system log .SH SYNOPSIS .C "#include " .PP .C "void syslog(int priority, const char *message, ...);" .PP .C "void openlog(const char *ident, int logopt, int facility);" .PP .C "void closelog(void);" .PP .C "int setlogmask(int maskpri);" .SS Remarks The ANSI C "\c .CR ", ...\$\c" " construct denotes a variable length argument list whose optional [or required] \" EDITOR: make this line fit the specific page members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION .TP 15 .C syslog() writes a message onto the system log maintained by .CR syslogd (see .IR syslogd (1M)). The message is tagged with .IR priority . The .I message is similar to a .IR printf (3S) format string except that .CR %m is replaced by the error message associated with the current value of .CR errno . A trailing newline is added if needed. .IP This message is read by .CR syslogd and written to the system console, log files, selected users' terminals, or forwarded to .CR syslogd on another host as appropriate. .IP .I priority is encoded as the logical OR of a .I level and a .IR facility . The .I level signifies the urgency of the message, and .I facility signifies the subsystem generating the message. .I facility can be encoded explicitly in .IR priority , or a default .I facility can be set with .CR openlog() (see below). .IP .I level is selected from an ordered list: .RS .RS .TP 20 .C LOG_EMERG A panic condition. This is normally broadcast to all users. .TP .C LOG_ALERT A condition that should be corrected immediately, such as a corrupted system database. .TP .C LOG_CRIT Critical conditions, such as hard device errors. .TP .C LOG_ERR Errors. .TP .C LOG_WARNING Warning messages. .TP .C LOG_NOTICE Conditions that are not error conditions, but should possibly be handled specially. .TP .C LOG_INFO Informational messages. .TP .C LOG_DEBUG Messages that contain information normally of use only when debugging a program. .RE .RE .IP .CR syslog() does not log a message that does not have a .I level set. .IP If .CR syslog() cannot pass the message to .CR syslogd , it attempts to write the message on .CR /dev/console if the .CR LOG_CONS option is set (see below). .TP .C openlog() can be called to initialize the log file, if special processing is needed. .I ident is a string that precedes every message. .I logopt is a mask of bits, logically OR'ed together, indicating logging options. The values for .I logopt are: .RS .RS .TP 20 .C LOG_PID Log the process ID with each message; useful for identifying instantiations of daemons. .TP .C LOG_CONS Force writing messages to the console if unable to send it to .CR syslogd . This option is safe to use in daemon processes that have no controlling terminal because .CR syslog() forks before opening the console. .TP .C LOG_NDELAY Open the connection to .CR syslogd immediately. Normally, the open is delayed until the first message is logged. This is useful for programs that need to manage the order in which file descriptors are allocated. .TP .C LOG_NOWAIT Do not wait for children forked to log messages on the console. This option should be used by processes that enable notification of child termination via .CR SIGCLD , because .CR syslog() might otherwise block, waiting for a child whose exit status has already been collected. .RE .RE .IP .I facility encodes a default facility to be assigned to all messages written subsequently by .CR syslog() with no explicit facility encoded. .IP .RS .RS .TP 20 .C LOG_KERN Messages generated by the kernel. These cannot be generated by any user processes. .TP .C LOG_USER Messages generated by random user processes. This is the default facility identifier if none is specified. .TP .C LOG_MAIL The mail system. .TP .C LOG_DAEMON System daemons, such as .IR inetd (1M), .IR ftpd (1M), etc. .TP .C LOG_AUTH The authorization system: .IR login (1), .IR su (1), .IR getty (1M), etc. .TP .C LOG_LPR The line printer spooling system: .IR lp (1), .IR lpsched (1M), etc. .TP .C LOG_LOCAL0 Reserved for local use. Similarly for .CR LOG_LOCAL1 through .CR LOG_LOCAL7 . .RE .RE .TP .C closelog() closes the log file. .TP .C setlogmask() sets the log priority mask to .I maskpri and returns the previous mask. Calls to .CR syslog() with a priority not set in .I maskpri are rejected. The mask for an individual priority .I pri is calculated by the macro .CI LOG_MASK( pri )\c ; the mask for all priorities up to and including .I toppri is given by the macro .CR LOG_UPTO\c .RI ( toppri ). By default, all priorities are logged. .SH ERRORS .CR syslog fails if any of the following conditions are encountered: .RS .TP 15 [EAGAIN] The named pipe .CR /dev/log is blocked for writing. .TP [ENOENT] The named pipe .CR /dev/log bold) could not be opened successfully. .SH EXAMPLES .CR who logs a message regarding some sort of unexpected and serious error: .IP .C "syslog(LOG_ALERT, ""who: internal error 23"");" .PP .CR ftpd uses .CR openlog() to arrange to log its process ID, to log to the console if necessary, and to log in the name of the .I daemon facility: .IP .C "openlog(""ftpd"", LOG_PID|LOG_CONS, LOG_DAEMON);" .PP Arrange to log messages only at levels .CR LOG_ERR and lower: .IP .C setlogmask(LOG_UPTO(LOG_ERR)); .PP Typical usage of .CR syslog() to log a connection: .IP .C "syslog(LOG_INFO,\ ""Connection\ from\ host\ %d"",\ CallingHost);" .PP If the facility has not been set with .CR openlog() , it defaults to .CR LOG_USER . .PP Explicitly set the facility for this message: .IP .C "syslog(LOG_INFO|LOG_LOCAL2,\ ""foobar\ error:\ %m"");" .SH WARNINGS A call to .CR syslog() has no effect unless the syslog daemon .RI ( syslogd (1M)) is running. .CR openlog() does not copy and store the .I ident string internally; it stores only a character pointer. Therefore it is the responsibility of the programmer to make sure that the .I ident argument points to the correct string until the log file is closed. .SH AUTHOR .CR syslog() was developed by the University of California, Berkeley. .SH SEE ALSO logger(1), syslogd(1M). .\" .\" index@\f4syslog()\f1 \- write message onto system log file@@@\f3syslog(3C)\f1 .\" index@\f4openlog()\f1 \- initialize system log file@@@\f3syslog(3C)\f1 .\" index@\f4closelog()\f1 \- close system log file@@@\f3syslog(3C)\f1 .\" index@\f4setlogmask()\f1 \- set system log file priority mask@@@\f3syslog(3C)\f1 .\" index@control system log@@@\f3syslog(3C)\f1 .\" index@system log, control@@@\f3syslog(3C)\f1 .\" index@log, system, control@@@\f3syslog(3C)\f1 .\" .\" toc@\f3syslog(3C)\f1:\0\0\f4syslog()\f1, \f4openlog()\f1, \f4closelog()\f1, \f4setlogmask()\fP@@@control system log .\" toc@\f4openlog()\f1:\0\0control system log@@@see \f3syslog(3C)\f1 .\" toc@\f4closelog()\f1:\0\0control system log@@@see \f3syslog(3C)\f1 .\" toc@\f4setlogmask()\f1:\0\0control system log@@@see \f3syslog(3C)\f1 .\" .\" links@syslog.3c openlog.3c .\" links@syslog.3c closelog.3c .\" links@syslog.3c setlogmask.3c .\" .\" fileset_database@syslog.3c PROGRAMING-MAN .\" $Header: getopt.3c,v 72.6 94/12/08 12:12:50 ssa Exp $ .TA g .TH getopt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getopt(\|), optarg, optind, opterr \- get option letter from argument vector .SH SYNOPSIS .C "#include " .PP .C "int getopt(int argc, char * const argv[], const char *optstring);" .PP .C "extern char *optarg;" .PP .C "extern int optind, opterr, optopt;" .SH DESCRIPTION .C getopt() returns the next option letter in .I argv (starting from .IR argv [\|1\|]) that matches a letter in .IR optstring . .I argc and .I argv are the argument count and argument array as passed to .IR main (). .I optstring is a string of recognized option characters; if a character is followed by a colon, the option takes an argument which may or may not be separated from it by white space. .PP .C optind is the index of the next element of the .IR argv [\|] vector to be processed. It is initialized to 1 by the system, and .C getopt() updates it when it finishes with each element of .IR argv []. .PP .C getopt() returns the next option character from .I argv that matches a character in .IR optstring , if there is one that matches. If the option takes an argument, .C getopt() sets the variable .C optarg to point to the option-argument as follows: .RS .TP 3 \(bu If the option was the last character in the string pointed to by an element of .IR argv , then .C optarg contains the next element of .IR argv , and .C optind is incremented by 2. If the resulting value of .C optind is greater than or equal to .IR argc , this indicates a missing option argument, and .C getopt() returns an error indication. .TP \(bu Otherwise, .C optarg points to the string following the option character in that element of .IR argv , and .C optind is incremented by 1. .RE .PP If, when .C getopt() is called, .IR argv [ \|optind\| ] is .SM NULL, or the string pointed to by .IR argv [ \|optind\| ] either does not begin with the character .C - or consists only of the character .CR - , .C getopt() returns \(mi1 without changing .IR optind . If .IR argv [ \|optind\| ] points to the string .CR -\|- , .C getopt() returns \(mi1 after incrementing .IR optind . .PP If .C getopt() encounters an option character that is not contained in .IR optstring , it returns the question-mark .RC ( ? ) character. If it detects a missing option argument, it returns the colon character .RC ( : ) if the first character of .I optstring was a colon, or a question-mark character otherwise. In either case, .C getopt() sets the variable .I optopt to the option character that caused the error. If the application has not set the variable .C opterr to zero and the first character of .I optstring is not a colon, .C getopt() also prints a diagnostic message to standard error. .PP The special option .C -\|- can be used to delimit the end of the options; \(mi1 is returned, and .C -\|- is skipped. .SH RETURN VALUE .C getopt() returns the next option character specified on the command line. A colon .RC ( : ) is returned if .C getopt() detects a missing argument and the first character of .I optstring was a colon .RC ( : ). .PP A question-mark .RC ( ? ) is returned if .C getopt() encounters an option character not in .I optstring or detects a missing argument and the first character of .I optstring was not a colon .RC ( : ). .PP Otherwise, .C getopt() returns \(mi1 when all command line options have been parsed. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of option letters as single and/or multi-byte characters. .SS International Code Set Support Single- and multibyte character code sets are supported. .SH ERRORS .CR getopt() fails under the following conditions: .TP 15 [EILSEQ] An invalid multibyte character sequence was encountered during option processing. .SH EXAMPLES The following code fragment shows to process arguments for a command that can take the mutually exclusive options .C a and .CR b , and the options .C f and .CR o , both of which require arguments: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 #include #include main (int argc, char *argv[]) { int c; int bflg, aflg, errflg; extern char *optarg; extern int optind, optopt; \&\f3.\fP \&\f3.\fP \&\f3.\fP while ((c = getopt(argc, argv, ":abf:o:")) != -1) switch (c) { case \'a\': if (bflg) errflg++; else aflg++; break; case \'b\': if (aflg) errflg++; else { bflg++; bproc( ); } break; case \'f\': ifile = optarg; break; case \'o\': ofile = optarg; break; case \':\': /* -f or -o without arguments */ fprintf(stderr, "Option -%c requires an argument\\n", optopt); errflg++; break; case \'?\': fprintf(stderr, "Unrecognized option: - %c\\n", optopt); errflg++; } if (errflg) { fprintf(stderr, "usage: . . . "); exit (2); } for ( ; optind < argc; optind++) { if (access(argv[optind], 4)) { \&\f3.\fP \&\f3.\fP \&\f3.\fP } .ft .ps .fi .RE .SH WARNINGS .PP Options can be any .SM ASCII characters except colon .RC ( : ), question mark .RC ( ? ), or null .RC ( \e0 ). It is impossible to distinguish between a .C ? used as a legal option, and the character that .C getopt() returns when it encounters an invalid option character in the input. .PP .C getopt() is unsafe in multi-thread applications. .SH SEE ALSO getopt(1). .SH STANDARDS CONFORMANCE .CR getopt() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR optarg ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR opterr ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR optind ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR optopt ": AES, SVID3, XPG4, POSIX.2" .\" .\" index@\f4getopt()\f1, \f4optarg\f1, \f4optind\f1, \f4opterr\f1 \- get option letter from argument vector@@@\f3getopt(3C)\f1 .\" index@\f4optarg\f1, \f4optind\f1, \f4opterr\f1 \- get option letter from argument vector@@@\f3getopt(3C)\f1 .\" index@get: option letter from argument vector@@@\f3getopt(3C)\f1 .\" index@option letter from argument vector, get@@@\f3getopt(3C)\f1 .\" index@argument vector, get option letter from@@@\f3getopt(3C)\f1 .\" index@vector, get option letter from argument@@@\f3getopt(3C)\f1 .\" .\" toc@\f3getopt(3C)\f1:\0\0\f4getopt()\f1, \f4optarg\f1, \f4optind\f1, \f4opterr\f1@@@get option letter from argument vector .\" toc@\f4optarg\f1:\0\0get option letter from argument vector@@@see \f3getopt(3C)\f1 .\" toc@\f4optind\f1:\0\0get option letter from argument vector@@@see \f3getopt(3C)\f1 .\" toc@\f4opterr\f1:\0\0get option letter from argument vector@@@see \f3getopt(3C)\f1 .\" .\" links@getopt.3c optarg.3c .\" links@getopt.3c optind.3c .\" links@getopt.3c opterr.3c .\" $Header: getopt.3c,v 72.6 94/12/08 12:12:50 ssa Exp $ .TA g .TH getopt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getopt(\|), optarg, optind, opterr \- get option letter from argument vector .SH SYNOPSIS .C "#include " .PP .C "int getopt(int argc, char * const argv[], const char *optstring);" .PP .C "extern char *optarg;" .PP .C "extern int optind, opterr, optopt;" .SH DESCRIPTION .C getopt() returns the next option letter in .I argv (starting from .IR argv [\|1\|]) that matches a letter in .IR optstring . .I argc and .I argv are the argument count and argument array as passed to .IR main (). .I optstring is a string of recognized option characters; if a character is followed by a colon, the option takes an argument which may or may not be separated from it by white space. .PP .C optind is the index of the next element of the .IR argv [\|] vector to be processed. It is initialized to 1 by the system, and .C getopt() updates it when it finishes with each element of .IR argv []. .PP .C getopt() returns the next option character from .I argv that matches a character in .IR optstring , if there is one that matches. If the option takes an argument, .C getopt() sets the variable .C optarg to point to the option-argument as follows: .RS .TP 3 \(bu If the option was the last character in the string pointed to by an element of .IR argv , then .C optarg contains the next element of .IR argv , and .C optind is incremented by 2. If the resulting value of .C optind is greater than or equal to .IR argc , this indicates a missing option argument, and .C getopt() returns an error indication. .TP \(bu Otherwise, .C optarg points to the string following the option character in that element of .IR argv , and .C optind is incremented by 1. .RE .PP If, when .C getopt() is called, .IR argv [ \|optind\| ] is .SM NULL, or the string pointed to by .IR argv [ \|optind\| ] either does not begin with the character .C - or consists only of the character .CR - , .C getopt() returns \(mi1 without changing .IR optind . If .IR argv [ \|optind\| ] points to the string .CR -\|- , .C getopt() returns \(mi1 after incrementing .IR optind . .PP If .C getopt() encounters an option character that is not contained in .IR optstring , it returns the question-mark .RC ( ? ) character. If it detects a missing option argument, it returns the colon character .RC ( : ) if the first character of .I optstring was a colon, or a question-mark character otherwise. In either case, .C getopt() sets the variable .I optopt to the option character that caused the error. If the application has not set the variable .C opterr to zero and the first character of .I optstring is not a colon, .C getopt() also prints a diagnostic message to standard error. .PP The special option .C -\|- can be used to delimit the end of the options; \(mi1 is returned, and .C -\|- is skipped. .SH RETURN VALUE .C getopt() returns the next option character specified on the command line. A colon .RC ( : ) is returned if .C getopt() detects a missing argument and the first character of .I optstring was a colon .RC ( : ). .PP A question-mark .RC ( ? ) is returned if .C getopt() encounters an option character not in .I optstring or detects a missing argument and the first character of .I optstring was not a colon .RC ( : ). .PP Otherwise, .C getopt() returns \(mi1 when all command line options have been parsed. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of option letters as single and/or multi-byte characters. .SS International Code Set Support Single- and multibyte character code sets are supported. .SH ERRORS .CR getopt() fails under the following conditions: .TP 15 [EILSEQ] An invalid multibyte character sequence was encountered during option processing. .SH EXAMPLES The following code fragment shows to process arguments for a command that can take the mutually exclusive options .C a and .CR b , and the options .C f and .CR o , both of which require arguments: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 #include #include main (int argc, char *argv[]) { int c; int bflg, aflg, errflg; extern char *optarg; extern int optind, optopt; \&\f3.\fP \&\f3.\fP \&\f3.\fP while ((c = getopt(argc, argv, ":abf:o:")) != -1) switch (c) { case \'a\': if (bflg) errflg++; else aflg++; break; case \'b\': if (aflg) errflg++; else { bflg++; bproc( ); } break; case \'f\': ifile = optarg; break; case \'o\': ofile = optarg; break; case \':\': /* -f or -o without arguments */ fprintf(stderr, "Option -%c requires an argument\\n", optopt); errflg++; break; case \'?\': fprintf(stderr, "Unrecognized option: - %c\\n", optopt); errflg++; } if (errflg) { fprintf(stderr, "usage: . . . "); exit (2); } for ( ; optind < argc; optind++) { if (access(argv[optind], 4)) { \&\f3.\fP \&\f3.\fP \&\f3.\fP } .ft .ps .fi .RE .SH WARNINGS .PP Options can be any .SM ASCII characters except colon .RC ( : ), question mark .RC ( ? ), or null .RC ( \e0 ). It is impossible to distinguish between a .C ? used as a legal option, and the character that .C getopt() returns when it encounters an invalid option character in the input. .PP .C getopt() is unsafe in multi-thread applications. .SH SEE ALSO getopt(1). .SH STANDARDS CONFORMANCE .CR getopt() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR optarg ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR opterr ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR optind ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR optopt ": AES, SVID3, XPG4, POSIX.2" .\" .\" index@\f4getopt()\f1, \f4optarg\f1, \f4optind\f1, \f4opterr\f1 \- get option letter from argument vector@@@\f3getopt(3C)\f1 .\" index@\f4optarg\f1, \f4optind\f1, \f4opterr\f1 \- get option letter from argument vector@@@\f3getopt(3C)\f1 .\" index@get: option letter from argument vector@@@\f3getopt(3C)\f1 .\" index@option letter from argument vector, get@@@\f3getopt(3C)\f1 .\" index@argument vector, get option letter from@@@\f3getopt(3C)\f1 .\" index@vector, get option letter from argument@@@\f3getopt(3C)\f1 .\" .\" toc@\f3getopt(3C)\f1:\0\0\f4getopt()\f1, \f4optarg\f1, \f4optind\f1, \f4opterr\f1@@@get option letter from argument vector .\" toc@\f4optarg\f1:\0\0get option letter from argument vector@@@see \f3getopt(3C)\f1 .\" toc@\f4optind\f1:\0\0get option letter from argument vector@@@see \f3getopt(3C)\f1 .\" toc@\f4opterr\f1:\0\0get option letter from argument vector@@@see \f3getopt(3C)\f1 .\" .\" links@getopt.3c optarg.3c .\" links@getopt.3c optind.3c .\" links@getopt.3c opterr.3c .\" $Header: getopt.3c,v 72.6 94/12/08 12:12:50 ssa Exp $ .TA g .TH getopt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getopt(\|), optarg, optind, opterr \- get option letter from argument vector .SH SYNOPSIS .C "#include " .PP .C "int getopt(int argc, char * const argv[], const char *optstring);" .PP .C "extern char *optarg;" .PP .C "extern int optind, opterr, optopt;" .SH DESCRIPTION .C getopt() returns the next option letter in .I argv (starting from .IR argv [\|1\|]) that matches a letter in .IR optstring . .I argc and .I argv are the argument count and argument array as passed to .IR main (). .I optstring is a string of recognized option characters; if a character is followed by a colon, the option takes an argument which may or may not be separated from it by white space. .PP .C optind is the index of the next element of the .IR argv [\|] vector to be processed. It is initialized to 1 by the system, and .C getopt() updates it when it finishes with each element of .IR argv []. .PP .C getopt() returns the next option character from .I argv that matches a character in .IR optstring , if there is one that matches. If the option takes an argument, .C getopt() sets the variable .C optarg to point to the option-argument as follows: .RS .TP 3 \(bu If the option was the last character in the string pointed to by an element of .IR argv , then .C optarg contains the next element of .IR argv , and .C optind is incremented by 2. If the resulting value of .C optind is greater than or equal to .IR argc , this indicates a missing option argument, and .C getopt() returns an error indication. .TP \(bu Otherwise, .C optarg points to the string following the option character in that element of .IR argv , and .C optind is incremented by 1. .RE .PP If, when .C getopt() is called, .IR argv [ \|optind\| ] is .SM NULL, or the string pointed to by .IR argv [ \|optind\| ] either does not begin with the character .C - or consists only of the character .CR - , .C getopt() returns \(mi1 without changing .IR optind . If .IR argv [ \|optind\| ] points to the string .CR -\|- , .C getopt() returns \(mi1 after incrementing .IR optind . .PP If .C getopt() encounters an option character that is not contained in .IR optstring , it returns the question-mark .RC ( ? ) character. If it detects a missing option argument, it returns the colon character .RC ( : ) if the first character of .I optstring was a colon, or a question-mark character otherwise. In either case, .C getopt() sets the variable .I optopt to the option character that caused the error. If the application has not set the variable .C opterr to zero and the first character of .I optstring is not a colon, .C getopt() also prints a diagnostic message to standard error. .PP The special option .C -\|- can be used to delimit the end of the options; \(mi1 is returned, and .C -\|- is skipped. .SH RETURN VALUE .C getopt() returns the next option character specified on the command line. A colon .RC ( : ) is returned if .C getopt() detects a missing argument and the first character of .I optstring was a colon .RC ( : ). .PP A question-mark .RC ( ? ) is returned if .C getopt() encounters an option character not in .I optstring or detects a missing argument and the first character of .I optstring was not a colon .RC ( : ). .PP Otherwise, .C getopt() returns \(mi1 when all command line options have been parsed. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of option letters as single and/or multi-byte characters. .SS International Code Set Support Single- and multibyte character code sets are supported. .SH ERRORS .CR getopt() fails under the following conditions: .TP 15 [EILSEQ] An invalid multibyte character sequence was encountered during option processing. .SH EXAMPLES The following code fragment shows to process arguments for a command that can take the mutually exclusive options .C a and .CR b , and the options .C f and .CR o , both of which require arguments: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 #include #include main (int argc, char *argv[]) { int c; int bflg, aflg, errflg; extern char *optarg; extern int optind, optopt; \&\f3.\fP \&\f3.\fP \&\f3.\fP while ((c = getopt(argc, argv, ":abf:o:")) != -1) switch (c) { case \'a\': if (bflg) errflg++; else aflg++; break; case \'b\': if (aflg) errflg++; else { bflg++; bproc( ); } break; case \'f\': ifile = optarg; break; case \'o\': ofile = optarg; break; case \':\': /* -f or -o without arguments */ fprintf(stderr, "Option -%c requires an argument\\n", optopt); errflg++; break; case \'?\': fprintf(stderr, "Unrecognized option: - %c\\n", optopt); errflg++; } if (errflg) { fprintf(stderr, "usage: . . . "); exit (2); } for ( ; optind < argc; optind++) { if (access(argv[optind], 4)) { \&\f3.\fP \&\f3.\fP \&\f3.\fP } .ft .ps .fi .RE .SH WARNINGS .PP Options can be any .SM ASCII characters except colon .RC ( : ), question mark .RC ( ? ), or null .RC ( \e0 ). It is impossible to distinguish between a .C ? used as a legal option, and the character that .C getopt() returns when it encounters an invalid option character in the input. .PP .C getopt() is unsafe in multi-thread applications. .SH SEE ALSO getopt(1). .SH STANDARDS CONFORMANCE .CR getopt() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR optarg ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR opterr ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR optind ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR optopt ": AES, SVID3, XPG4, POSIX.2" .\" .\" index@\f4getopt()\f1, \f4optarg\f1, \f4optind\f1, \f4opterr\f1 \- get option letter from argument vector@@@\f3getopt(3C)\f1 .\" index@\f4optarg\f1, \f4optind\f1, \f4opterr\f1 \- get option letter from argument vector@@@\f3getopt(3C)\f1 .\" index@get: option letter from argument vector@@@\f3getopt(3C)\f1 .\" index@option letter from argument vector, get@@@\f3getopt(3C)\f1 .\" index@argument vector, get option letter from@@@\f3getopt(3C)\f1 .\" index@vector, get option letter from argument@@@\f3getopt(3C)\f1 .\" .\" toc@\f3getopt(3C)\f1:\0\0\f4getopt()\f1, \f4optarg\f1, \f4optind\f1, \f4opterr\f1@@@get option letter from argument vector .\" toc@\f4optarg\f1:\0\0get option letter from argument vector@@@see \f3getopt(3C)\f1 .\" toc@\f4optind\f1:\0\0get option letter from argument vector@@@see \f3getopt(3C)\f1 .\" toc@\f4opterr\f1:\0\0get option letter from argument vector@@@see \f3getopt(3C)\f1 .\" .\" links@getopt.3c optarg.3c .\" links@getopt.3c optind.3c .\" links@getopt.3c opterr.3c .\" $Header: overlay.3x,v 76.2 95/08/01 14:33:54 ssa Exp $ .TA o .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH overlay 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME overlay, overwrite \(em copy overlapped windows .SH SYNOPSIS .C "#include " .P .C "int overlay(WINDOW * const \f2srcwin\fP, WINDOW *\f2dstwin\fP);" .P .C "int overwrite(WINDOW * const \f2srcwin\fP, WINDOW *\f2dstwin\fP);" .SH DESCRIPTION The .Fn overlay and .Fn overwrite functions overlay \f2srcwin\f1 on top of \f2dstwin\f1. The \f2scrwin\f1 and \f2dstwin\f1 arguments need not be the same size; only text where the two windows overlap is copied. .P The .Fn overwrite function copies characters as though a sequence of .Fn win_wch and .Fn wadd_wch were performed with the destination window's attributes and background attributes cleared. .P The .Fn overlay function does the same thing, except that, whenever a character to be copied is the background character of the source window, .Fn overlay does not copy the character but merely moves the destination cursor the width of the source background character. .P If any portion of the overlaying window border is not the first column of a multi-column character then all the column positions will be replaced with the background character and rendition before the overlay is done. If the default background character is a multi-column character when this occurs, then these functions fail. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" copywin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The type of argument .Fn srcwin\f1 is changed from .CR "WINDOW *" to .CR "WINDOW *CONST" . .\" .\" toc@\f3overlay(3X)\f1:\0\0\f4overlay()\f1, \f4overwrite()\f1@@@copy overlapped windows .\" toc@\f4overwrite()\f1: copy overlapped windows@@@see \f3overlay(3X)\f1 .\" .\" index@\f4overlay()\f1 \- copy overlapped windows@@@\f3overlay(3X)\f1 .\" index@\f4overwrite()\f1 \- copy overlapped windows@@@\f3overlay(3X)\f1 .\" index@\f1copy overlapped windows@@@\f3overlay(3X)\f1 .\" index@\f1overlapped windows, copy@@@\f3overlay(3X)\f1 .\" index@\f1windows, copy overlapped windows@@@\f3overlay(3X)\f1 .\" .\" links@overlay.3x overwrite.3x .\" .\" fileset_database@overlay.3x CURS-ENG-A-MAN .\" $Header: overlay.3x,v 76.2 95/08/01 14:33:54 ssa Exp $ .TA o .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH overlay 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME overlay, overwrite \(em copy overlapped windows .SH SYNOPSIS .C "#include " .P .C "int overlay(WINDOW * const \f2srcwin\fP, WINDOW *\f2dstwin\fP);" .P .C "int overwrite(WINDOW * const \f2srcwin\fP, WINDOW *\f2dstwin\fP);" .SH DESCRIPTION The .Fn overlay and .Fn overwrite functions overlay \f2srcwin\f1 on top of \f2dstwin\f1. The \f2scrwin\f1 and \f2dstwin\f1 arguments need not be the same size; only text where the two windows overlap is copied. .P The .Fn overwrite function copies characters as though a sequence of .Fn win_wch and .Fn wadd_wch were performed with the destination window's attributes and background attributes cleared. .P The .Fn overlay function does the same thing, except that, whenever a character to be copied is the background character of the source window, .Fn overlay does not copy the character but merely moves the destination cursor the width of the source background character. .P If any portion of the overlaying window border is not the first column of a multi-column character then all the column positions will be replaced with the background character and rendition before the overlay is done. If the default background character is a multi-column character when this occurs, then these functions fail. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" copywin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The type of argument .Fn srcwin\f1 is changed from .CR "WINDOW *" to .CR "WINDOW *CONST" . .\" .\" toc@\f3overlay(3X)\f1:\0\0\f4overlay()\f1, \f4overwrite()\f1@@@copy overlapped windows .\" toc@\f4overwrite()\f1: copy overlapped windows@@@see \f3overlay(3X)\f1 .\" .\" index@\f4overlay()\f1 \- copy overlapped windows@@@\f3overlay(3X)\f1 .\" index@\f4overwrite()\f1 \- copy overlapped windows@@@\f3overlay(3X)\f1 .\" index@\f1copy overlapped windows@@@\f3overlay(3X)\f1 .\" index@\f1overlapped windows, copy@@@\f3overlay(3X)\f1 .\" index@\f1windows, copy overlapped windows@@@\f3overlay(3X)\f1 .\" .\" links@overlay.3x overwrite.3x .\" .\" fileset_database@overlay.3x CURS-ENG-A-MAN .\" $Header: can_change_color.3x,v 76.3 95/10/05 14:12:23 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH can_change_color 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME can_change_color, color_content, has_colors, init_color, init_pair, start_color, pair_content \(em color manipulation functions .SH SYNOPSIS .C "#include " .P .C "bool can_change_color(void);" .P .C "int color_content(short \f2color\fP, short *\f2red\fP, short *\f2green\fP, short *\f2blue\fP);" .P .C "int COLOR_PAIR(int \f2n\fP);" .P .C "bool has_colors(void);" .P .C "int init_color(short \f2color\fP, short \f2red\fP, short \f2green\fP, short \f2blue\fP);" .P .C "int init_pair(short \f2pair\fP, short \f2f\fP, short \f2b\fP);" .P .C "int pair_content(short \f2pair\fP, short *\f2f\fP, short *\f2b\fP);" .P .C "int PAIR_NUMBER(int \f2value\fP);" .P .C "int start_color(void);" .P .C "extern int COLOR_PAIRS;" .P .C "extern int COLORS;" .SH DESCRIPTION These functions manipulate colour on terminals that support colour. .SS "Querying Capabilities" The .Fn has_colors function indicates whether the terminal is a colour terminal. The .Fn can_change_color function indicates whether the terminal is a colour terminal on which colours can be redefined. .SS "Initialisation" The .Fn start_color function must be called in order to enable use of colours and before any colour manipulation function is called. The function initialises eight basic colours (black, blue, green, cyan, red, magenta, yellow, and white) that can be specified by the colour macros (such as COLOR_BLACK) defined in .CR . (See \f3Colour-related Macros\f1 in \f3\f1.) The initial appearance of these eight colours is not specified. .P The function also initialises two global external variables: .RS .TP 3 .C \(bu COLORS defines the number of colours that the terminal supports. (See .B "Colour Identification" below.) If COLORS is 0, the terminal does not support redefinition of colours (and .Fn can_change_colour will return FALSE). .TP .C \(bu COLOR_PAIRS defines the maximum number of colour-pairs that the terminal supports. (See .B "User-Defined Colour Pairs" below.) .RE .P The .Fn start_color function also restores the colours on the terminal to terminal-specific initial values. The initial background colour is assumed to be black for all terminals. .SS "Colour Identification" The .Fn init_color function redefines colour number \f2color\fP, on terminals that support the redefinition of colours, to have the red, green, and blue intensity components specified by \f2red\fP, \f2green\fP, and \f2blue\fP, respectively. Calling .Fn init_color also changes all occurrences of the specified colour on the screen to the new definition. .P The .Fn color_content function identifies the intensity components of colour number \f2color\f1. It stores the red, green, and blue intensity components of this colour in the addresses pointed to by \f2red\fP, \f2green\fP, and \f2blue\fP, respectively. .P For both functions, the .I color argument must be in the range from 0 to and including COLORS\|\(mi\|1. Valid intensity values range from 0 (no intensity component) up to and including 1000 (maximum intensity in that component). .SS "User-Defined Colour Pairs" Calling .Fn init_pair defines or redefines colour-pair number \f2pair\f1 to have foreground colour \f2f\f1 and background colour \f2b\f1. Calling .Fn init_pair changes any characters that were displayed in the colour pair's old definition to the new definition and refreshes the screen. .P After defining the colour pair, the macro COLOR_PAIR(\f2n\fP) returns the value of colour pair \f2n\f1. This value is the colour attribute as it would be extracted from a .CR chtype . Conversely, the macro PAIR_NUMBER(\f2value\fP) returns the colour pair number associated with the colour attribute \f2value\f1. .P The .Fn pair_content function retrieves the component colours of a colour-pair number \f2pair\f1. It stores the foreground and background colour numbers in the variables pointed to by \f2f\f1 and \f2b\fP, respectively. .P With .Fn init_pair and .Fn pair_content , the value of \f2pair\f1 must be in a range from 0 to and including COLOR_PAIRS\|\(mi\|1. (There may be an implementation-specific lower limit on the valid value of \f2pair\fP, but any such limit is at least 63.) Valid values for \f2f\f1 and \f2b\f1 are the range from 0 to and including COLORS\|\(mi\|1. .SH "RETURN VALUE" The .Fn has_colors function returns TRUE if the terminal can manipulate colors; otherwise, it returns FALSE. .P The .Fn can_change_color function returns TRUE if the terminal supports colors and can change their definitions; otherwise, it returns FALSE. .P Upon successful completion, the other functions return OK; otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" To use these functions, .Fn start_color must be called, usually right after .CR initscr() . .P The .Fn can_change_color and .Fn has_colors functions facilitate writing terminal-independent programs. For example, a programmer can use them to decide whether to use colour or some other video attribute. .P On color terminals, a typical value of COLORS is 8 and the macros such as COLOR_BLACK return a value within the range from 0 to and including 7. However, applications cannot rely on this to be true. .SH "SEE ALSO" attroff(), delscreen(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3can_change_color(3X)\f1:\0\0\f4can_change_color()\f1, \f4color_content()\f1, \f4has_colors()\f1, \f4init_color()\f1, \n\f4init_pair()\f1, \f4start_color()\f1, \f4pair_content()\f1@@@color manipulation functions .\" toc@\f4color_content()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4has_colors()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4init_colors()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4init_pair()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4start_color()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4pair_content()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" .\" index@\f4can_change_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4color_content()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4has_colors()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4init_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4init_pair()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4start_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4pair_content()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f1color manipulation functions@@@\f3can_change_color(3X)\f1 .\" .\" links@can_change_color.3x color_content.3x .\" links@can_change_color.3x has_colors.3x .\" links@can_change_color.3x init_color.3x .\" links@can_change_color.3x init_pair.3x .\" links@can_change_color.3x start_color.3x .\" links@can_change_color.3x pair_content.3x .\" .\" fileset_database@can_change_color.3x CURS-ENG-A-MAN .\" $Header: getbootpent.3x,v 74.1 95/05/10 21:04:42 ssa Exp $ .TA g .TH getbootpent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" =========== .SH NAME getbootpent(), putbootpent(), setbootpent(), endbootpent(), parse_bp_htype(), parse_bp_haddr(), parse_bp_iaddr() \- get or put bootptab entry .\" =========== .SH SYNOPSIS .C "#include " .PP .C "int getbootpent (struct bootpent **bootpent);" .PP .C "int setbootpent (const char *path);" .PP .C "int endbootpent (void);" .PP .C "void putbootpent (" .nf .PD 0 .IP .C "const struct bootpent *bootpent," .C "const int numfields," .C "\s-1FILE\s0 * bootpfile" .PP .C ");" .PD .fi .PP .C "int parse_bp_htype (const char *source);" .PP .C "int parse_bp_haddr (" .nf .PD 0 .IP .C "char **source," .C "int htype," .C "unsigned char *result," .C "unsigned int *bytes" .PP .C ");" .PD .PP .C "int parse_bp_iaddr (" .nf .PD 0 .IP .C "char **source," .C "unsigned long *result" .PP .C ");" .PD .\" =========== .SS Remarks These functions reside in libdc.a, and are linked using the .C -ldc option to the .C ld or .C cc command. .\" =========== .SH DESCRIPTION These functions help a program read or modify a bootptab .RC ( bootpd control) file one entry at a time. .C getbootpent() locates an entry in the .C /etc/bootptab file, or an alternate file specified to .CR setbootpent() , and returns a pointer to an array of objects of type .C struct bootpent that breaks the entry into separate data fields with preceding, or embedded, comment (text) lines. .PP The .C bootpent structure is defined in .RC < bootpent.h > and includes the following members: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. int@bp_type;@/* BP_DATA, BP_COMMENT, BP_BLANK@*/ char@*bp_text;@/* one field or one comment line@*/ .TE .ft P .RE .PP The file also defines the following data type and constants: .IP .C "typedef struct bootpent *bpp_t;" .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. #define BP_NULLP@((bpp_t) 0) #define BP_SIZE@(sizeof (struct bootpent)) .TE .ft P .RE .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. #define MAXHADDRLEN@6 #define HTYPE_UNKNOWN@0@/* 0 bytes@*/ #define HTYPE_ETHERNET@1@/* 6 bytes@*/ #define HTYPE_EXP_ETHERNET@2@/* 1 byte@*/ #define HTYPE_AX25@3@/* 0 bytes@*/ #define HTYPE_PRONET@4@/* 1 byte@*/ #define HTYPE_CHAOS@5@/* 0 bytes@*/ #define HTYPE_IEEE802@6@/* 6 bytes@*/ #define HTYPE_ARCNET@7@/* 0 bytes@*/ #define MAXHTYPES@7 .TE .ft P .RE .PP The fields are described in the .RB `` "Field Definitions" '' section below. The purpose of each function is as follows. .TP 25 .C getbootpent() When first called, .C getbootpent() returns a pointer to, and the number of elements in, an array of .C bootpent structures. The array holds the first entry in the .C /etc/bootptab file (or from an alternate file specified by a call to .CR setbootpent() ), including leading, or embedded, comment lines. Each subsequent call returns a pointer to the next entry in the file so that successive calls can be used to search the entire file. .IP If no file is currently in memory, .C getbootpent() reads the .C /etc/bootptab file prior to doing its work. .IP The returned array exists in static space (malloc'd memory) overwritten by the next call (so previously returned pointers become invalid). However, each array element's .C bp_text pointer points to text in an in-memory copy of the file. This text is not altered by the next call (nor by changes to the file itself). Hence, it is possible to copy an entry's array in order to save it, as illustrated in .SM EXAMPLES below. The data remains valid until the next call of .C setbootpent() or .CR endbootpent(). .IP If there are comments after the last entry, they are returned as a separate entry with no data parts. .TP .C setbootpent() Opens the specified file for reading by .CR getbootpent() , reads a copy into memory, and closes the file (which as a side-effect releases any locks on the file; see .IR lockf (2)). If the given .I path is a null pointer or a null string, .C setbootpent() opens and reads .CR /etc/bootptab . .IP If the last file opened by .C setbootpent() (or implicitly by .CR getbootpent() ) was .CR /etc/bootptab , a subsequent call to .C setbootpent() for the same file rewinds the file to the beginning, making visible any recent changes to the file, without first requiring a call to .CR endbootpent() . .TP .C endbootpent() Frees the in-memory copy of the last file opened by .CR setbootpent() , or .CR getbootpent() . .TP .C putbootpent() Writes (to the current location in the stream specified by .IR bootpfile ) the .SM ASCII equivalent of the specified array of .C bootpent structures containing one file entry, and its leading, or embedded, comments (a total of .I numfields array elements). Entries are written in canonical form, meaning the entry name and each data field are on separate lines, data fields are preceded by one tab each, and each line except the last ends with ``:\e''. If .I numfields is less than or equal to zero, nothing is written. .TP .C parse_bp_htype() Converts a host address type from string to numeric format .RC ( HTYPE_ *) in the same manner as .CR bootpd . .TP .C parse_bp_haddr() Converts a host (hardware, link level) address from string to binary format in the same manner as .C bootpd given a host address type .RC ( HTYPE_ *). The calling program's .IR result , which must be an array containing at least .SM MAXHADDRLEN elements, is modified to hold the host address binary value, and .C bytes is modified to indicate the length in bytes of the resulting address. This can be used to compare two host addresses, independent of string representations. .I source is modified to point to the first char after the parsed address. .TP .C parse_bp_iaddr() Converts an internet address from string to binary format in the same manner as .CR bootpd . This can be used to compare two internet addresses, independent of string representations. The calling program's .I result is modified to hold the internet address binary value. .I source is modified to point to the first char after the parsed address. .\" ----------- .SS Field Definitions If .C bootpent.bp_type is .SM BP_DATA, the associated text is one field from the current entry, either the name field or one of the tag fields. Null tag fields (two colons in a row) are ignored, not returned. .PP If .C bootpent.bp_type is .SM BP_COMMENT or .SM BP_BLANK, the associated text is one comment line or blank line from the file, either preceding the current entry or embedded in it following a data line that was continued with a backslash. The text is exactly as it appears in the file, including any whitespace appearing on a blank line, and there is no trailing newline. .PP The returned array elements are in the same order as data fields and comment lines appear in the file. .PP Entry field strings are of the form: .IP .IR tag [\c .ift \f4\s+1@\s0\fP\c .ifn \f3@\fP\c .RC ]\|[ =\c .C """\c .I value\c .C """\c .RC ] .PP with surrounding whitespace, if any, removed (see .IR bootpd (1M) for the full description). Double quotes, and backslashes, can appear anywhere in the field strings. .PP Template entries (those referred to by other entries using .C tc fields) are not special. They can be managed like other entries. It is the calling program's responsibility to correctly manage the order of fields, .C tc fields, and ``@'' fields that override earlier field values. .\" =========== .SH RETURN VALUE .C getbootpent() returns the number of valid array elements (one or more) upon successful completion. At the end of the input file it returns zero. If it cannot open or close the file it returns \-1. If it encounters a memory allocation or map error, or a read error, it returns \-2. .PP .C setbootpent() returns zero if successful opening and reading the specified or default file. If it cannot open or close the file it returns \-1. If it encounters a memory allocation or map error or a read error it returns \-2. .PP .C endbootpent() returns zero if successful freeing the memory for the current open file. If there is no current file it returns \-1. If it cannot free the memory for the current file it returns \-2. .PP .C putbootpent() returns zero if successful writing an entry to the specified file, with the .C ferror() indication clear (see .IR ferror (3S)). Otherwise it returns non-zero with .C ferror() set. .PP In all cases above, if a failure is due to a failed system call, the .C errno value from the system is valid on return from the called function. .PP .C parse_bp_htype() returns .SM HTYPE_UNKNOWN if the hardware type string is unrecognized. .PP .C parse_bp_haddr() returns zero if successful, otherwise non-zero in case of parsing error, invalid .IR htype , or a host address type for which the address length is unknown; .I source is modified to point to the first illegal char (a .SM NUL if the string is too short). The caller's .I bytes value is unmodified, but .I result might be changed. .PP .C parse_bp_iaddr() returns zero if successful, otherwise non-zero, and .I source is modified to point to the first illegal char (a .SM NUL if the string is null). .\" =========== .SH EXAMPLES The following code fragment copies all data and comments from .C /etc/bootptab to a temporary copy of the file. It converts data entries to canonical form as a side effect, and prints to standard output the first field of each entry copied (should be the field name, assuming the entry doesn't start with a continuation line). .RS .PP .nf .ifn \f3 .ift \f4 #include \s-1FILE\s0 *newfilep; /* to write temp file */ bpp_t bp; /* read from file */ int field; /* current field number */ int fields; /* total in array for one entry */ if ((newfilep = fopen ("/tmp/bootptab", "w")) == (\s-1FILE\s0 *) \s-1NULL\s0) { \f2(handle error)\fP } while ((fields = getbootpent (&bp)) > 0) { for (field = 0; field < fields; ++field) { if ((bp[field].bp_type) == \s-1BP_DATA\s0) { (void) puts (bp[field].bp_text); break; } } if (putbootpent (bp, fields, newfilep)) { \f2(handle error)\fP } } if (fields < 0) /* error reading file */ { \f2(handle error)\fP } if (endbootpent()) { \f2(handle error)\fP } if (fclose (newfilep)) { \f2(handle error)\fP } .ft P .fi .RE .PP The following code fragment saves a copy of a bootptab entry returned by .CR getbootpent() . .RS .PP .nf .ifn \f3 .ift \f4 #include #include #include bpp_t bpnew; unsigned size; size = fields *\s-1BP_SIZE\s0; if ((bpnew = (bpp_t) malloc (size)) == \s-1BP_NULLP\s0) { \f2(handle error)\fP } (void) memcpy ((void *)bpnew, (void *)bp, size); .ft P .fi .RE .\" =========== .SH WARNINGS These functions are unsafe in multi-thread applications. .PP Calling .C setbootpent() releases any locks on the file it opens. .\" =========== .SH AUTHOR .PP These functions were developed by .SM HP. .\" =========== .SH FILES .TP 20 .C /etc/bootptab control file for .C bootpd .\" =========== .SH SEE ALSO bootpd(1M), .\" chbootptab(1M), (SAM-only, not currently supported for 10.0) errno(2), lockf(2), ferror(3S), fopen(3S), malloc(3C). .\" .\" toc@\f3getbootpent(3X)\f1:\0\0\f4getbootpent(), putbootpent(), setbootpent(), endbootpent(), \nparse_bp_htype(), parse_bp_hpaddr(), parse_bp_iaddr()\f1@@@get, or put bootptab entry .\" .\" index@get, or put bootptab entry \- @@@\f3getbootpent(3X)\f1 .\" index@bootptab entry, get or put@@@\f3getbootpent(3X)\f1 .\" .\" links@getbootpent.3x setbootpent.3x .\" links@getbootpent.3x endbootpent.3x .\" links@getbootpent.3x putbootpent.3x .\" links@getbootpent.3x parse_bp_htype.3x .\" links@getbootpent.3x parse_bp_haddr.3x .\" links@getbootpent.3x parse_bp_iaddr.3x .\" $Header: getbootpent.3x,v 74.1 95/05/10 21:04:42 ssa Exp $ .TA g .TH getbootpent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" =========== .SH NAME getbootpent(), putbootpent(), setbootpent(), endbootpent(), parse_bp_htype(), parse_bp_haddr(), parse_bp_iaddr() \- get or put bootptab entry .\" =========== .SH SYNOPSIS .C "#include " .PP .C "int getbootpent (struct bootpent **bootpent);" .PP .C "int setbootpent (const char *path);" .PP .C "int endbootpent (void);" .PP .C "void putbootpent (" .nf .PD 0 .IP .C "const struct bootpent *bootpent," .C "const int numfields," .C "\s-1FILE\s0 * bootpfile" .PP .C ");" .PD .fi .PP .C "int parse_bp_htype (const char *source);" .PP .C "int parse_bp_haddr (" .nf .PD 0 .IP .C "char **source," .C "int htype," .C "unsigned char *result," .C "unsigned int *bytes" .PP .C ");" .PD .PP .C "int parse_bp_iaddr (" .nf .PD 0 .IP .C "char **source," .C "unsigned long *result" .PP .C ");" .PD .\" =========== .SS Remarks These functions reside in libdc.a, and are linked using the .C -ldc option to the .C ld or .C cc command. .\" =========== .SH DESCRIPTION These functions help a program read or modify a bootptab .RC ( bootpd control) file one entry at a time. .C getbootpent() locates an entry in the .C /etc/bootptab file, or an alternate file specified to .CR setbootpent() , and returns a pointer to an array of objects of type .C struct bootpent that breaks the entry into separate data fields with preceding, or embedded, comment (text) lines. .PP The .C bootpent structure is defined in .RC < bootpent.h > and includes the following members: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. int@bp_type;@/* BP_DATA, BP_COMMENT, BP_BLANK@*/ char@*bp_text;@/* one field or one comment line@*/ .TE .ft P .RE .PP The file also defines the following data type and constants: .IP .C "typedef struct bootpent *bpp_t;" .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. #define BP_NULLP@((bpp_t) 0) #define BP_SIZE@(sizeof (struct bootpent)) .TE .ft P .RE .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. #define MAXHADDRLEN@6 #define HTYPE_UNKNOWN@0@/* 0 bytes@*/ #define HTYPE_ETHERNET@1@/* 6 bytes@*/ #define HTYPE_EXP_ETHERNET@2@/* 1 byte@*/ #define HTYPE_AX25@3@/* 0 bytes@*/ #define HTYPE_PRONET@4@/* 1 byte@*/ #define HTYPE_CHAOS@5@/* 0 bytes@*/ #define HTYPE_IEEE802@6@/* 6 bytes@*/ #define HTYPE_ARCNET@7@/* 0 bytes@*/ #define MAXHTYPES@7 .TE .ft P .RE .PP The fields are described in the .RB `` "Field Definitions" '' section below. The purpose of each function is as follows. .TP 25 .C getbootpent() When first called, .C getbootpent() returns a pointer to, and the number of elements in, an array of .C bootpent structures. The array holds the first entry in the .C /etc/bootptab file (or from an alternate file specified by a call to .CR setbootpent() ), including leading, or embedded, comment lines. Each subsequent call returns a pointer to the next entry in the file so that successive calls can be used to search the entire file. .IP If no file is currently in memory, .C getbootpent() reads the .C /etc/bootptab file prior to doing its work. .IP The returned array exists in static space (malloc'd memory) overwritten by the next call (so previously returned pointers become invalid). However, each array element's .C bp_text pointer points to text in an in-memory copy of the file. This text is not altered by the next call (nor by changes to the file itself). Hence, it is possible to copy an entry's array in order to save it, as illustrated in .SM EXAMPLES below. The data remains valid until the next call of .C setbootpent() or .CR endbootpent(). .IP If there are comments after the last entry, they are returned as a separate entry with no data parts. .TP .C setbootpent() Opens the specified file for reading by .CR getbootpent() , reads a copy into memory, and closes the file (which as a side-effect releases any locks on the file; see .IR lockf (2)). If the given .I path is a null pointer or a null string, .C setbootpent() opens and reads .CR /etc/bootptab . .IP If the last file opened by .C setbootpent() (or implicitly by .CR getbootpent() ) was .CR /etc/bootptab , a subsequent call to .C setbootpent() for the same file rewinds the file to the beginning, making visible any recent changes to the file, without first requiring a call to .CR endbootpent() . .TP .C endbootpent() Frees the in-memory copy of the last file opened by .CR setbootpent() , or .CR getbootpent() . .TP .C putbootpent() Writes (to the current location in the stream specified by .IR bootpfile ) the .SM ASCII equivalent of the specified array of .C bootpent structures containing one file entry, and its leading, or embedded, comments (a total of .I numfields array elements). Entries are written in canonical form, meaning the entry name and each data field are on separate lines, data fields are preceded by one tab each, and each line except the last ends with ``:\e''. If .I numfields is less than or equal to zero, nothing is written. .TP .C parse_bp_htype() Converts a host address type from string to numeric format .RC ( HTYPE_ *) in the same manner as .CR bootpd . .TP .C parse_bp_haddr() Converts a host (hardware, link level) address from string to binary format in the same manner as .C bootpd given a host address type .RC ( HTYPE_ *). The calling program's .IR result , which must be an array containing at least .SM MAXHADDRLEN elements, is modified to hold the host address binary value, and .C bytes is modified to indicate the length in bytes of the resulting address. This can be used to compare two host addresses, independent of string representations. .I source is modified to point to the first char after the parsed address. .TP .C parse_bp_iaddr() Converts an internet address from string to binary format in the same manner as .CR bootpd . This can be used to compare two internet addresses, independent of string representations. The calling program's .I result is modified to hold the internet address binary value. .I source is modified to point to the first char after the parsed address. .\" ----------- .SS Field Definitions If .C bootpent.bp_type is .SM BP_DATA, the associated text is one field from the current entry, either the name field or one of the tag fields. Null tag fields (two colons in a row) are ignored, not returned. .PP If .C bootpent.bp_type is .SM BP_COMMENT or .SM BP_BLANK, the associated text is one comment line or blank line from the file, either preceding the current entry or embedded in it following a data line that was continued with a backslash. The text is exactly as it appears in the file, including any whitespace appearing on a blank line, and there is no trailing newline. .PP The returned array elements are in the same order as data fields and comment lines appear in the file. .PP Entry field strings are of the form: .IP .IR tag [\c .ift \f4\s+1@\s0\fP\c .ifn \f3@\fP\c .RC ]\|[ =\c .C """\c .I value\c .C """\c .RC ] .PP with surrounding whitespace, if any, removed (see .IR bootpd (1M) for the full description). Double quotes, and backslashes, can appear anywhere in the field strings. .PP Template entries (those referred to by other entries using .C tc fields) are not special. They can be managed like other entries. It is the calling program's responsibility to correctly manage the order of fields, .C tc fields, and ``@'' fields that override earlier field values. .\" =========== .SH RETURN VALUE .C getbootpent() returns the number of valid array elements (one or more) upon successful completion. At the end of the input file it returns zero. If it cannot open or close the file it returns \-1. If it encounters a memory allocation or map error, or a read error, it returns \-2. .PP .C setbootpent() returns zero if successful opening and reading the specified or default file. If it cannot open or close the file it returns \-1. If it encounters a memory allocation or map error or a read error it returns \-2. .PP .C endbootpent() returns zero if successful freeing the memory for the current open file. If there is no current file it returns \-1. If it cannot free the memory for the current file it returns \-2. .PP .C putbootpent() returns zero if successful writing an entry to the specified file, with the .C ferror() indication clear (see .IR ferror (3S)). Otherwise it returns non-zero with .C ferror() set. .PP In all cases above, if a failure is due to a failed system call, the .C errno value from the system is valid on return from the called function. .PP .C parse_bp_htype() returns .SM HTYPE_UNKNOWN if the hardware type string is unrecognized. .PP .C parse_bp_haddr() returns zero if successful, otherwise non-zero in case of parsing error, invalid .IR htype , or a host address type for which the address length is unknown; .I source is modified to point to the first illegal char (a .SM NUL if the string is too short). The caller's .I bytes value is unmodified, but .I result might be changed. .PP .C parse_bp_iaddr() returns zero if successful, otherwise non-zero, and .I source is modified to point to the first illegal char (a .SM NUL if the string is null). .\" =========== .SH EXAMPLES The following code fragment copies all data and comments from .C /etc/bootptab to a temporary copy of the file. It converts data entries to canonical form as a side effect, and prints to standard output the first field of each entry copied (should be the field name, assuming the entry doesn't start with a continuation line). .RS .PP .nf .ifn \f3 .ift \f4 #include \s-1FILE\s0 *newfilep; /* to write temp file */ bpp_t bp; /* read from file */ int field; /* current field number */ int fields; /* total in array for one entry */ if ((newfilep = fopen ("/tmp/bootptab", "w")) == (\s-1FILE\s0 *) \s-1NULL\s0) { \f2(handle error)\fP } while ((fields = getbootpent (&bp)) > 0) { for (field = 0; field < fields; ++field) { if ((bp[field].bp_type) == \s-1BP_DATA\s0) { (void) puts (bp[field].bp_text); break; } } if (putbootpent (bp, fields, newfilep)) { \f2(handle error)\fP } } if (fields < 0) /* error reading file */ { \f2(handle error)\fP } if (endbootpent()) { \f2(handle error)\fP } if (fclose (newfilep)) { \f2(handle error)\fP } .ft P .fi .RE .PP The following code fragment saves a copy of a bootptab entry returned by .CR getbootpent() . .RS .PP .nf .ifn \f3 .ift \f4 #include #include #include bpp_t bpnew; unsigned size; size = fields *\s-1BP_SIZE\s0; if ((bpnew = (bpp_t) malloc (size)) == \s-1BP_NULLP\s0) { \f2(handle error)\fP } (void) memcpy ((void *)bpnew, (void *)bp, size); .ft P .fi .RE .\" =========== .SH WARNINGS These functions are unsafe in multi-thread applications. .PP Calling .C setbootpent() releases any locks on the file it opens. .\" =========== .SH AUTHOR .PP These functions were developed by .SM HP. .\" =========== .SH FILES .TP 20 .C /etc/bootptab control file for .C bootpd .\" =========== .SH SEE ALSO bootpd(1M), .\" chbootptab(1M), (SAM-only, not currently supported for 10.0) errno(2), lockf(2), ferror(3S), fopen(3S), malloc(3C). .\" .\" toc@\f3getbootpent(3X)\f1:\0\0\f4getbootpent(), putbootpent(), setbootpent(), endbootpent(), \nparse_bp_htype(), parse_bp_hpaddr(), parse_bp_iaddr()\f1@@@get, or put bootptab entry .\" .\" index@get, or put bootptab entry \- @@@\f3getbootpent(3X)\f1 .\" index@bootptab entry, get or put@@@\f3getbootpent(3X)\f1 .\" .\" links@getbootpent.3x setbootpent.3x .\" links@getbootpent.3x endbootpent.3x .\" links@getbootpent.3x putbootpent.3x .\" links@getbootpent.3x parse_bp_htype.3x .\" links@getbootpent.3x parse_bp_haddr.3x .\" links@getbootpent.3x parse_bp_iaddr.3x .\" $Header: getbootpent.3x,v 74.1 95/05/10 21:04:42 ssa Exp $ .TA g .TH getbootpent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" =========== .SH NAME getbootpent(), putbootpent(), setbootpent(), endbootpent(), parse_bp_htype(), parse_bp_haddr(), parse_bp_iaddr() \- get or put bootptab entry .\" =========== .SH SYNOPSIS .C "#include " .PP .C "int getbootpent (struct bootpent **bootpent);" .PP .C "int setbootpent (const char *path);" .PP .C "int endbootpent (void);" .PP .C "void putbootpent (" .nf .PD 0 .IP .C "const struct bootpent *bootpent," .C "const int numfields," .C "\s-1FILE\s0 * bootpfile" .PP .C ");" .PD .fi .PP .C "int parse_bp_htype (const char *source);" .PP .C "int parse_bp_haddr (" .nf .PD 0 .IP .C "char **source," .C "int htype," .C "unsigned char *result," .C "unsigned int *bytes" .PP .C ");" .PD .PP .C "int parse_bp_iaddr (" .nf .PD 0 .IP .C "char **source," .C "unsigned long *result" .PP .C ");" .PD .\" =========== .SS Remarks These functions reside in libdc.a, and are linked using the .C -ldc option to the .C ld or .C cc command. .\" =========== .SH DESCRIPTION These functions help a program read or modify a bootptab .RC ( bootpd control) file one entry at a time. .C getbootpent() locates an entry in the .C /etc/bootptab file, or an alternate file specified to .CR setbootpent() , and returns a pointer to an array of objects of type .C struct bootpent that breaks the entry into separate data fields with preceding, or embedded, comment (text) lines. .PP The .C bootpent structure is defined in .RC < bootpent.h > and includes the following members: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. int@bp_type;@/* BP_DATA, BP_COMMENT, BP_BLANK@*/ char@*bp_text;@/* one field or one comment line@*/ .TE .ft P .RE .PP The file also defines the following data type and constants: .IP .C "typedef struct bootpent *bpp_t;" .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. #define BP_NULLP@((bpp_t) 0) #define BP_SIZE@(sizeof (struct bootpent)) .TE .ft P .RE .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. #define MAXHADDRLEN@6 #define HTYPE_UNKNOWN@0@/* 0 bytes@*/ #define HTYPE_ETHERNET@1@/* 6 bytes@*/ #define HTYPE_EXP_ETHERNET@2@/* 1 byte@*/ #define HTYPE_AX25@3@/* 0 bytes@*/ #define HTYPE_PRONET@4@/* 1 byte@*/ #define HTYPE_CHAOS@5@/* 0 bytes@*/ #define HTYPE_IEEE802@6@/* 6 bytes@*/ #define HTYPE_ARCNET@7@/* 0 bytes@*/ #define MAXHTYPES@7 .TE .ft P .RE .PP The fields are described in the .RB `` "Field Definitions" '' section below. The purpose of each function is as follows. .TP 25 .C getbootpent() When first called, .C getbootpent() returns a pointer to, and the number of elements in, an array of .C bootpent structures. The array holds the first entry in the .C /etc/bootptab file (or from an alternate file specified by a call to .CR setbootpent() ), including leading, or embedded, comment lines. Each subsequent call returns a pointer to the next entry in the file so that successive calls can be used to search the entire file. .IP If no file is currently in memory, .C getbootpent() reads the .C /etc/bootptab file prior to doing its work. .IP The returned array exists in static space (malloc'd memory) overwritten by the next call (so previously returned pointers become invalid). However, each array element's .C bp_text pointer points to text in an in-memory copy of the file. This text is not altered by the next call (nor by changes to the file itself). Hence, it is possible to copy an entry's array in order to save it, as illustrated in .SM EXAMPLES below. The data remains valid until the next call of .C setbootpent() or .CR endbootpent(). .IP If there are comments after the last entry, they are returned as a separate entry with no data parts. .TP .C setbootpent() Opens the specified file for reading by .CR getbootpent() , reads a copy into memory, and closes the file (which as a side-effect releases any locks on the file; see .IR lockf (2)). If the given .I path is a null pointer or a null string, .C setbootpent() opens and reads .CR /etc/bootptab . .IP If the last file opened by .C setbootpent() (or implicitly by .CR getbootpent() ) was .CR /etc/bootptab , a subsequent call to .C setbootpent() for the same file rewinds the file to the beginning, making visible any recent changes to the file, without first requiring a call to .CR endbootpent() . .TP .C endbootpent() Frees the in-memory copy of the last file opened by .CR setbootpent() , or .CR getbootpent() . .TP .C putbootpent() Writes (to the current location in the stream specified by .IR bootpfile ) the .SM ASCII equivalent of the specified array of .C bootpent structures containing one file entry, and its leading, or embedded, comments (a total of .I numfields array elements). Entries are written in canonical form, meaning the entry name and each data field are on separate lines, data fields are preceded by one tab each, and each line except the last ends with ``:\e''. If .I numfields is less than or equal to zero, nothing is written. .TP .C parse_bp_htype() Converts a host address type from string to numeric format .RC ( HTYPE_ *) in the same manner as .CR bootpd . .TP .C parse_bp_haddr() Converts a host (hardware, link level) address from string to binary format in the same manner as .C bootpd given a host address type .RC ( HTYPE_ *). The calling program's .IR result , which must be an array containing at least .SM MAXHADDRLEN elements, is modified to hold the host address binary value, and .C bytes is modified to indicate the length in bytes of the resulting address. This can be used to compare two host addresses, independent of string representations. .I source is modified to point to the first char after the parsed address. .TP .C parse_bp_iaddr() Converts an internet address from string to binary format in the same manner as .CR bootpd . This can be used to compare two internet addresses, independent of string representations. The calling program's .I result is modified to hold the internet address binary value. .I source is modified to point to the first char after the parsed address. .\" ----------- .SS Field Definitions If .C bootpent.bp_type is .SM BP_DATA, the associated text is one field from the current entry, either the name field or one of the tag fields. Null tag fields (two colons in a row) are ignored, not returned. .PP If .C bootpent.bp_type is .SM BP_COMMENT or .SM BP_BLANK, the associated text is one comment line or blank line from the file, either preceding the current entry or embedded in it following a data line that was continued with a backslash. The text is exactly as it appears in the file, including any whitespace appearing on a blank line, and there is no trailing newline. .PP The returned array elements are in the same order as data fields and comment lines appear in the file. .PP Entry field strings are of the form: .IP .IR tag [\c .ift \f4\s+1@\s0\fP\c .ifn \f3@\fP\c .RC ]\|[ =\c .C """\c .I value\c .C """\c .RC ] .PP with surrounding whitespace, if any, removed (see .IR bootpd (1M) for the full description). Double quotes, and backslashes, can appear anywhere in the field strings. .PP Template entries (those referred to by other entries using .C tc fields) are not special. They can be managed like other entries. It is the calling program's responsibility to correctly manage the order of fields, .C tc fields, and ``@'' fields that override earlier field values. .\" =========== .SH RETURN VALUE .C getbootpent() returns the number of valid array elements (one or more) upon successful completion. At the end of the input file it returns zero. If it cannot open or close the file it returns \-1. If it encounters a memory allocation or map error, or a read error, it returns \-2. .PP .C setbootpent() returns zero if successful opening and reading the specified or default file. If it cannot open or close the file it returns \-1. If it encounters a memory allocation or map error or a read error it returns \-2. .PP .C endbootpent() returns zero if successful freeing the memory for the current open file. If there is no current file it returns \-1. If it cannot free the memory for the current file it returns \-2. .PP .C putbootpent() returns zero if successful writing an entry to the specified file, with the .C ferror() indication clear (see .IR ferror (3S)). Otherwise it returns non-zero with .C ferror() set. .PP In all cases above, if a failure is due to a failed system call, the .C errno value from the system is valid on return from the called function. .PP .C parse_bp_htype() returns .SM HTYPE_UNKNOWN if the hardware type string is unrecognized. .PP .C parse_bp_haddr() returns zero if successful, otherwise non-zero in case of parsing error, invalid .IR htype , or a host address type for which the address length is unknown; .I source is modified to point to the first illegal char (a .SM NUL if the string is too short). The caller's .I bytes value is unmodified, but .I result might be changed. .PP .C parse_bp_iaddr() returns zero if successful, otherwise non-zero, and .I source is modified to point to the first illegal char (a .SM NUL if the string is null). .\" =========== .SH EXAMPLES The following code fragment copies all data and comments from .C /etc/bootptab to a temporary copy of the file. It converts data entries to canonical form as a side effect, and prints to standard output the first field of each entry copied (should be the field name, assuming the entry doesn't start with a continuation line). .RS .PP .nf .ifn \f3 .ift \f4 #include \s-1FILE\s0 *newfilep; /* to write temp file */ bpp_t bp; /* read from file */ int field; /* current field number */ int fields; /* total in array for one entry */ if ((newfilep = fopen ("/tmp/bootptab", "w")) == (\s-1FILE\s0 *) \s-1NULL\s0) { \f2(handle error)\fP } while ((fields = getbootpent (&bp)) > 0) { for (field = 0; field < fields; ++field) { if ((bp[field].bp_type) == \s-1BP_DATA\s0) { (void) puts (bp[field].bp_text); break; } } if (putbootpent (bp, fields, newfilep)) { \f2(handle error)\fP } } if (fields < 0) /* error reading file */ { \f2(handle error)\fP } if (endbootpent()) { \f2(handle error)\fP } if (fclose (newfilep)) { \f2(handle error)\fP } .ft P .fi .RE .PP The following code fragment saves a copy of a bootptab entry returned by .CR getbootpent() . .RS .PP .nf .ifn \f3 .ift \f4 #include #include #include bpp_t bpnew; unsigned size; size = fields *\s-1BP_SIZE\s0; if ((bpnew = (bpp_t) malloc (size)) == \s-1BP_NULLP\s0) { \f2(handle error)\fP } (void) memcpy ((void *)bpnew, (void *)bp, size); .ft P .fi .RE .\" =========== .SH WARNINGS These functions are unsafe in multi-thread applications. .PP Calling .C setbootpent() releases any locks on the file it opens. .\" =========== .SH AUTHOR .PP These functions were developed by .SM HP. .\" =========== .SH FILES .TP 20 .C /etc/bootptab control file for .C bootpd .\" =========== .SH SEE ALSO bootpd(1M), .\" chbootptab(1M), (SAM-only, not currently supported for 10.0) errno(2), lockf(2), ferror(3S), fopen(3S), malloc(3C). .\" .\" toc@\f3getbootpent(3X)\f1:\0\0\f4getbootpent(), putbootpent(), setbootpent(), endbootpent(), \nparse_bp_htype(), parse_bp_hpaddr(), parse_bp_iaddr()\f1@@@get, or put bootptab entry .\" .\" index@get, or put bootptab entry \- @@@\f3getbootpent(3X)\f1 .\" index@bootptab entry, get or put@@@\f3getbootpent(3X)\f1 .\" .\" links@getbootpent.3x setbootpent.3x .\" links@getbootpent.3x endbootpent.3x .\" links@getbootpent.3x putbootpent.3x .\" links@getbootpent.3x parse_bp_htype.3x .\" links@getbootpent.3x parse_bp_haddr.3x .\" links@getbootpent.3x parse_bp_iaddr.3x .\" $Header: popen.3s,v 72.5 94/11/15 09:55:37 ssa Exp $ .TA p .TH popen 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME popen(\|), pclose(\|) \- initiate pipe I/O to/from a process .SH SYNOPSIS .C "#include " .PP .C "FILE *popen(const char *command, const char *type);" .PP .C "int pclose(FILE *stream);" .SH DESCRIPTION .C popen() creates a pipe between the calling program and a command to be executed by the .SM POSIX shell, .C /usr/bin/sh (see .IR sh-posix (1)). .PP The arguments to .C popen() are pointers to null-terminated strings containing, respectively, a shell command line and an I/O mode, either .C r for reading or .C w for writing. .PP .C popen() returns a stream pointer such that one can write to the standard input of the command if the I/O mode is .C w by writing to the file .IR stream ; and one can read from the standard output of the command if the I/O mode is .C r by reading from the file .IR stream . .PP A stream opened by .C popen() should be closed by .CR pclose() , which waits for the associated process to terminate and returns the exit status of the command. .PP Because open files are shared, a type .C r command can be used as an input filter and a type .C w command as an output filter. .SH RETURN VALUE .C popen() returns a .SM NULL pointer if files or processes cannot be created. The success of the command execution can be checked by examining the return value of .CR pclose() . .PP .C pclose() returns .C -1 if .I stream is not associated with a .CR popen() ed command, or 127 if .C /usr/bin/sh could not be executed for some reason. .SH WARNINGS If the original and .CR popen() ed processes concurrently read or write a common file, neither should use buffered .SM I/O because the buffering will not work properly. Problems with an output filter can be forestalled by careful buffer flushing, e.g., with .CR fflush() ; see .IR fclose (3S). .SH SEE ALSO pipe(2), wait(2), fclose(3S), fopen(3S), system(3S). .SH STANDARDS CONFORMANCE .CR popen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR pclose() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4popen()\fP \- initiate pipe \s-1I/O\s+1 to or from a process@@@\f3popen(3S)\f1 .\" index@\f4pclose()\fP \- terminate pipe \s-1I/O\s+1 to or from a process@@@\f3popen(3S)\f1 .\" index@close or open pipe \s-1I/O\s+1 to or from a process@@@\f3popen(3S)\f1 .\" index@\s-1I/O\s+1 pipe to or from a process, open or close@@@\f3popen(3S)\f1 .\" index@open or close pipe \s-1I/O\s+1 to or from a process@@@\f3popen(3S)\f1 .\" index@pipe \s-1I/O\s+1 to or from a process, open or close@@@\f3popen(3S)\f1 .\" index@process, open or close pipe \s-1I/O\s+1 to or from a@@@\f3popen(3S)\f1 .\" .\" toc@\f3popen(3S)\f1:\0\0\f4popen()\fP, \f4pclose()\fP@@@initiate pipe \s-1I/O\s+1 to/from a process .\" toc@\f4pclose()\fP:\0\0initiate pipe \s-1I/O\s+1 to/from a process@@@see \f3popen(3S)\f1 .\" .\" links@popen.3s pclose.3s .\" .\" fileset_database@popen.3s PROGRAMING-MAN .\" $Header: pechochar.3x,v 76.2 95/08/01 14:34:57 ssa Exp $ .TA p .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH pechochar 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pechochar, pecho_wchar \(em write a character and rendition and immediately refresh the pad .SH SYNOPSIS .C "#include " .P .C "int pechochar(WINDOW *\f2pad\fP, chtype \f2ch\fP);" .P .C "int pecho_wchar(WINDOW *\f2pad\fP, cchar_t *const \f2wch\fP);" .SH DESCRIPTION The .Fn pechochar and .Fn pecho_wchar functions output one character to a pad and immediately refresh the pad. They are equivalent to a call to .Fn waddch or .CR wadd_wch() , respectively, followed by a call to .CR prefresh() . The last location of the pad on the screen is reused for the arguments to .CR prefresh() . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn pechochar function is only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" echochar(), echo_char(), newpad(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3pechochar(3X)\f1:\0\0\f4pechochar()\f1, \f4pecho_wchar()\f1@@@write a character rendition and immediately refresh the pad .\" toc@\f4pecho_wchar()\f1: write a character rendition and immediately refresh the pad@@@see \f3pechochar(3X)\f1 .\" .\" index@\f4pechochar()\f1 \- write a character rendition and immediately refresh the pad@@@\f3pechochar(3X)\f1 .\" index@\f4pecho_wchar()\f1 \- write a character rendition and immediately refresh the pad@@@\f3pechochar(3X)\f1 .\" index@\f1write a character rendition and immediately refresh the pad@@@\f3pechochar(3X)\f1 .\" index@\f1character rendition, write and immediately refresh the pad@@@\f3pechochar(3X)\f1 .\" index@\f1refresh the pad immediately after writing a character rendition@@@\f3pechochar(3X)\f1 .\" index@\f1pad, refresh immediately after writing a character rendition@@@\f3pechochar(3X)\f1 .\" .\" links@pechochar.3x pecho_wchar.3x .\" .\" fileset_database@pechochar.3x CURS-ENG-A-MAN .\" $Header: pechochar.3x,v 76.2 95/08/01 14:34:57 ssa Exp $ .TA p .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH pechochar 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pechochar, pecho_wchar \(em write a character and rendition and immediately refresh the pad .SH SYNOPSIS .C "#include " .P .C "int pechochar(WINDOW *\f2pad\fP, chtype \f2ch\fP);" .P .C "int pecho_wchar(WINDOW *\f2pad\fP, cchar_t *const \f2wch\fP);" .SH DESCRIPTION The .Fn pechochar and .Fn pecho_wchar functions output one character to a pad and immediately refresh the pad. They are equivalent to a call to .Fn waddch or .CR wadd_wch() , respectively, followed by a call to .CR prefresh() . The last location of the pad on the screen is reused for the arguments to .CR prefresh() . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn pechochar function is only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" echochar(), echo_char(), newpad(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3pechochar(3X)\f1:\0\0\f4pechochar()\f1, \f4pecho_wchar()\f1@@@write a character rendition and immediately refresh the pad .\" toc@\f4pecho_wchar()\f1: write a character rendition and immediately refresh the pad@@@see \f3pechochar(3X)\f1 .\" .\" index@\f4pechochar()\f1 \- write a character rendition and immediately refresh the pad@@@\f3pechochar(3X)\f1 .\" index@\f4pecho_wchar()\f1 \- write a character rendition and immediately refresh the pad@@@\f3pechochar(3X)\f1 .\" index@\f1write a character rendition and immediately refresh the pad@@@\f3pechochar(3X)\f1 .\" index@\f1character rendition, write and immediately refresh the pad@@@\f3pechochar(3X)\f1 .\" index@\f1refresh the pad immediately after writing a character rendition@@@\f3pechochar(3X)\f1 .\" index@\f1pad, refresh immediately after writing a character rendition@@@\f3pechochar(3X)\f1 .\" .\" links@pechochar.3x pecho_wchar.3x .\" .\" fileset_database@pechochar.3x CURS-ENG-A-MAN .\" $Header: perror.3c,v 74.1 95/03/23 18:05:29 ssa Exp $ .TA p .TH perror 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME perror(\|), strerror(\|), strerror_r(\|), errno, sys_errlist, sys_nerr \- system error messages .SH SYNOPSIS .C "#include " .PP .C "void perror(const char *s);" .PP .C "char *strerror(int errnum);" .PP .C "int strerror_r(int errnum, char *buffer, int buflen);" .PP .C "extern int errno;" .PP .C "extern char *sys_errlist[\|];" .PP .C "extern int sys_nerr;" .SH DESCRIPTION .CR perror() writes a language-dependent message to the standard error output, describing the last error encountered during a call to a system or library function. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. To be most useful, the argument string should include the name of the program that incurred the error. The error number is taken from the external variable .CR errno , which is set when errors occur but not cleared when non-erroneous calls are made. The contents of the message is identical to those returned by the .CR strerror() function with .CR errno as the argument. If given a .SM NULL string, the .CR perror() function prints only the message and a new-line. .PP To simplify variant formatting of messages, the .CR strerror() function and the .CR sys_errlist array of message strings are provided. The .CR strerror() function maps the error number in .I errnum to a language-dependent error message string and returns a pointer to the string. The message string is returned without a new-line. .CR errno can be used as an index into .CR sys_errlist to get an untranslated message string without the new-line. .CR sys_nerr is the largest message number provided for in the table; it should be checked because new error codes might be added to the system before they are added to the table. .CR strerror() must be used to retrieve messages when translations are desired. .PP .CR strerror_r() is identical to .CR strerror() , except that the result string is passed back in the supplied buffer. A buffer length of 80 is recommended. If an error is detected or the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .SH EXTERNAL INFLUENCES .SS Environment Variables The language of the message returned by .CR strerror() and printed by .CR perror() is specified by the .CR LANG environment variable. If the language-dependent message is not available, or if .CR LANG is not set or is set to the empty string, the default version of the message associated with the "C" language (see .IR lang (5)) is used. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .CR perror() returns no value. .PP If the .I errnum message number is valid, .CR strerror() returns a pointer to a language-dependent message string. The array pointed to should not be modified by the program, and might be overwritten by a subsequent call to the function. If a valid .I errnum message number does not have a corresponding language-dependent message, .CR strerror() uses .I errnum as an index into .CR sys_errlist to get the message string. If the .I errnum message number is invalid, .CR strerror() returns a pointer to a .SM NULL string. .SH WARNINGS The return value for .CR strerror() points to static data whose content is overwritten by each call. .CR strerror() is unsafe for multi-thread applications. .CR strerror_r() is MT-Safe and should be used instead. .br .ne 12v .SH SEE ALSO errno(2), lang(5), environ(5). .SH STANDARDS CONFORMANCE .CR perror() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strerror() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR sys_errlist() ": SVID2, SVID3, XPG2" .PP .CR sys_nerr() ": SVID2, SVID3, XPG2" .\" .\" index@\f4perror()\fP, \f4errno()\fP, \f4sys_errlist()\fP, \f4sys_nerr()\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4errno\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4strerror()\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4sys_errlist\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4sys_nerr\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@system error messages@@@\f3perror(3C)\f1 .\" index@error messages, system@@@\f3perror(3C)\f1 .\" index@messages, system error@@@\f3perror(3C)\f1 .\" .\" toc@\f3perror(3C)\f1:\0\0\f4perror()\fP, \f4errno()\fP, \f4sys_errlist()\f1, \f4sys_nerr()\f1@@@system error messages .\" toc@\f4errno\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4strerror()\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4sys_errlist\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4sys_nerr\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" .\" links@perror.3c strerror.3c .\" links@perror.3c strerror_r.3c .\" links@perror.3c errno.3c .\" links@perror.3c sys_errlist.3c .\" links@perror.3c sys_nerr.3c .\" $Header: pfm_cleanup.3,v 72.4 94/10/27 14:40:52 ssa Exp $ .TA p .TH pfm_$cleanup 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfm_$cleanup \- establish a cleanup handler .SH SYNOPSIS .C #include .br .C #include .PP .C status_$t pfm_$cleanup( .br .C " pfm_$cleanup_rec *\f2cleanup_record\fP)" .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RC `` $ '' character. .SH DESCRIPTION .C pfm_$cleanup() establishes a cleanup handler that is executed when a fault occurs. A cleanup handler is a piece of code executed before a program exits when a signal is received by the process. The cleanup handler begins where .C pfm_$cleanup() is called; the .C pfm_$cleanup() call registers an entry point with the system where program execution resumes when a fault occurs. When a fault occurs, execution resumes after the most recent call to .CR pfm_$cleanup() . .PP There can be more than one cleanup handler in a program. Multiple cleanup handlers are executed consecutively on a last-in/first-out basis, starting with the most recently established cleanup handler and ending with the first cleanup handler. .PP On Apollo systems, a default cleanup handler is established at program invocation. The default cleanup handler is always called last, just before a program exits, and releases any system resources still held before returning control to the process that invoked the program. .PP On other systems, there is no default cleanup handler. .PP When called to establish a cleanup handler, .C pfm_$cleanup() returns the status .C pfm_$cleanup_set to indicate that the cleanup handler was successfully established. When the cleanup handler is entered in response to a fault signal, .C pfm_$cleanup() effectively returns the value of the fault that triggered the cleanup handler. .PP See the reference description of .C pfm_$init() for a list of the C signals that the .SM PFM package intercepts. .PP .I cleanup_record Is a record of the context when .C pfm_$cleanup() is called. A program should treat this as an opaque data structure and not try to alter or copy its contents. It is needed by .C pfm_$rls_cleanup() and .C pfm_$reset_cleanup() to restore the context of the calling process at the cleanup handler entry point. .SH NOTE The .C pfm_$cleanup() call implicitly performs a .CR pfm_$inhibit() . Cleanup handler code hence runs with asynchronous faults inhibited. When .C pfm_$cleanup() returns something other than .CR pfm_$cleanup_set() , indicating that a fault has occurred, there are four possible ways to leave the cleanup code: .RS .TP 3 \(bu The program can call .C pfm_$signal() to start the next cleanup handler with a fault signal you specify. .TP \(bu The program can call .C pgm_$exit() to start the next cleanup handler with a status of .IR status_$ok . .TP \(bu The program can continue with the code following the cleanup handler. It should generally call .C pfm_$enable() to re-enable asynchronous faults. Execution continues from the end of the cleanup handler code; it does not resume where the fault signal was received. .TP \(bu The program can re-establish the cleanup handler by calling .C pfm_$reset_cleanup() (which implicitly performs a .CR pfm_$enable() ) before proceeding. .RE .SH SEE ALSO pfm_$init(3), pfm_$signal(3). .\" .\" index@\f4pfm_$cleanup()\fP \- establish a cleanup handler@@@\f3pfm_$cleanup(3)\f1 .\" index@establish a cleanup handler@@@\f3pfm_$cleanup(3)\f1 .\" index@cleanup handler, establish a@@@\f3pfm_$cleanup(3)\f1 .\" index@handler, establish a cleanup@@@\f3pfm_$cleanup(3)\f1 .\" .\" toc@\f3pfm_$cleanup(3)\f1:\0\0\f4pfm_$cleanup()\fP@@@establish a cleanup handler .\" .\" fileset_database@pfm_cleanup.3 PROGRAMING-MAN .\" $Header: pfm_enable.3,v 72.4 94/10/27 14:41:05 ssa Exp $ .TA p .TH pfm_$enable 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfm_$enable \- enable asynchronous faults .SH SYNOPSIS .C #include .br .C #include .PP .C void pfm_$enable(void) .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RB `` $ '' character. .SH DESCRIPTION .C pfm_$enable() enables asynchronous faults after they have been inhibited by a call to .CR pfm_$inhibit() ; .C pfm_$enable() causes the operating system to pass asynchronous faults on to the calling process. .PP While faults are inhibited, the operating system holds at most one asynchronous fault. Consequently, when .C pfm_$enable() returns, there can be at most one fault waiting on the process. If more than one fault was received between calls to .C pfm_$inhibit() and .CR pfm_$enable() , the process receives the first asynchronous fault received while faults were inhibited. .SH SEE ALSO pfm_$enable_faults(3), pfm_$inhibit(3). .\" .\" index@\f4pfm_$enable()\fP \- enable asynchronous faults@@@\f3pfm_$enable(3)\f1 .\" index@enable asynchronous faults@@@\f3pfm_$enable(3)\f1 .\" index@asynchronous faults, enable@@@\f3pfm_$enable(3)\f1 .\" index@faults, enable asynchronous@@@\f3pfm_$enable(3)\f1 .\" .\" toc@\f3pfm_$enable(3)\f1:\0\0\f4pfm_$enable()\fP@@@enable asynchronous faults .\" .\" fileset_database@pfm_enable.3 PROGRAMING-MAN .\" $Header: pfm_enable_.3,v 72.4 94/10/27 14:41:22 ssa Exp $ .TA p .TH pfm_$enable_faults 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfm_$enable_faults \- enable asynchronous faults .SH SYNOPSIS .C #include .br .C #include .PP .C void pfm_$enable_faults(void) .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RB `` $ '' character. .SH DESCRIPTION The .C pfm_$enable_faults() call enables asynchronous faults after they have been inhibited by a call to .CR pfm_$inhibit_faults() ; .C pfm_$enable_faults() causes the operating system to pass asynchronous faults on to the calling process. .PP While faults are inhibited, the operating system holds at most one asynchronous fault. Consequently, when .C pfm_$enable_faults() returns, there can be at most one fault waiting on the process. If more than one fault was received between calls to .C pfm_$inhibit_faults() and .CR pfm_$enable_faults() , the process receives the first asynchronous fault received while faults were inhibited. .SH SEE ALSO pfm_$enable(3), pfm_$inhibit_faults(3). .\" .\" index@\f4pfm_$enable_faults()\fP \- enable asynchronous faults@@@\f3pfm_$enable_faults(3)\f1 .\" index@enable asynchronous faults@@@\f3pfm_$enable_faults(3)\f1 .\" index@asynchronous faults, enable@@@\f3pfm_$enable_faults(3)\f1 .\" index@faults, enable asynchronous@@@\f3pfm_$enable_faults(3)\f1 .\" .\" toc@\f3pfm_$enable_faults(3)\f1:\0\0\f4pfm_$enable_faults()\fP@@@enable asynchronous faults .\" .\" fileset_database@pfm_enable_.3 PROGRAMING-MAN .\" $Header: pfm_inhib.3,v 72.4 94/10/27 14:41:36 ssa Exp $ .TA p .TH pfm_$inhibit 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfm_$inhibit \- inhibit asynchronous faults .SH SYNOPSIS (C) .C #include .br .C #include .PP .C void pfm_$inhibit(void); .SH SYNOPSIS (PASCAL) .C %include '/sys/ins/base.ins.pas'; .br .C %include '/sys/ins/pfm.ins.pas'; .PP .C procedure pfm_$inhibit; .ig .SH SYNOPSIS (FORTRAN) \f3%include '/sys/ins/base.ins.ftn'\f1 \f3%include '/sys/ins/pfm.ins.ftn'\f1 \f3call pfm_$inhibit\f1 .. .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RB `` $ '' character. .SH DESCRIPTION .C pfm_$inhibit() prevents asynchronous faults from being passed to the calling process. While faults are inhibited, the operating system holds at most one asynchronous fault. Consequently, a call to .C pfm_$inhibit() can result in the loss of some signals. For that and other reasons, it is good practice to inhibit faults only when absolutely necessary. .PP See the reference description of .C pfm_$init() for a list of the C signals that the .SM PFM package intercepts. .SH NOTE This call has no effect on the processing of synchronous faults such as floating-point and overflow exceptions, access violations, and so on. .SH SEE ALSO pfm_$enable(3), pfm_$inhibit_faults(3), pfm_$init(3). .\" .\" index@\f4pfm_$inhibit()\fP \- inhibit asynchronous faults@@@\f3pfm_$inhibit(3)\f1 .\" index@inhibit asynchronous faults@@@\f3pfm_$inhibit(3)\f1 .\" index@asynchronous faults, inhibit@@@\f3pfm_$inhibit(3)\f1 .\" index@faults, inhibit asynchronous@@@\f3pfm_$inhibit(3)\f1 .\" .\" toc@\f3pfm_$inhibit(3)\f1:\0\0\f4pfm_$inhibit()\fP@@@inhibit asynchronous faults .\" .\" fileset_database@pfm_inhib.3 PROGRAMING-MAN .\" $Header: pfm_inhib_f.3,v 74.1 95/05/10 21:10:35 ssa Exp $ .TA p .TH pfm_$inhibit_faults 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfm_$inhibit_faults \- inhibit asynchronous faults but allow time-sliced task switching .SH SYNOPSIS .C #include .br .C #include .PP .C void pfm_$inhibit_faults(void); .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RB `` $ '' character. .SH DESCRIPTION .C pfm_$inhibit_faults() prevents asynchronous faults (except for time-sliced task switching) from being passed to the calling process. While faults are inhibited, the operating system holds at most one asynchronous fault. Consequently, a call to .C pfm_$inhibit_faults() can result in the loss of some signals. For that and other reasons, it is good practice to inhibit faults only when absolutely necessary. .PP See the reference description of .C pfm_$init() for a list of the C signals that the .SM PFM package intercepts. .SH NOTE This call has no effect on the processing of synchronous faults such as floating-point and overflow exceptions, access violations, and so on. .SH SEE ALSO pfm_$enable_faults(3), pfm_$inhibit(3), pfm_$init(3). .\" .\" index@\f4pfm_$inhibit_faults()\fP \- inhibit asynchronous faults; \nallow time-sliced task switching@@@\f3pfm_$inhibit_faults(3)\f1 .\" index@inhibit asynchronous faults; allow time-sliced task switching@@@\f3pfm_$inhibit_faults(3)\f1 .\" index@asynchronous faults, inhibit but allow time-sliced task switching@@@\f3pfm_$inhibit_faults(3)\f1 .\" index@faults, inhibit asynchronous but allow time-sliced task switching@@@\f3pfm_$inhibit_faults(3)\f1 .\" .\" toc@\f3pfm_$inhibit_faults(3)\f1:\0\0\n\f4pfm_$inhibit_faults()\fP@@@inhibit asynchronous faults; allow time-sliced task switching .\" .\" fileset_database@pfm_inhib_f.3 PROGRAMING-MAN .\" $Header: pfm_inhibit.3,v 72.3 93/01/14 14:52:16 ssa Exp $ .TA p .TH pfm_inhibit 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfm_inhibit \- pointer entry to conflicting online manual entries .SH DESCRIPTION This manual entry is provided for accessing manual entries whose online versions have conflicting filenames due to maximum name length imposed by short-filename (14-character maximum) systems. .ift \{\ .PP The following message is provided for online manual users:\} .TP .C NOTE .IP You have selected a name that conflicts with one or more other names. To display the manual entry you want, enter the man command again as follows: .IP .TS center tab(@); lB lB l lB. To view this entry:@Use this command: .sp .3 _ .sp .3 pfm_inhibit@man pfm_inhib .sp .5 pfm_inhibit_faults@man pfm_inhib_f .TE .\" .\" index@\f2pfm_inhibit\f1 \- pointer entry for conflicting online manual entries@@@\f3pfm_inhibit(3)\f1 .\" index@pointer entry for conflicting online manual entries@@@\f3pfm_inhibit(3)\f1 .\" .\" .\" toc@\f3pfm_inhibit(3)\f1:\0\0\f3pfm_inhibit\f1@@@pointer entry for conflicting online manual entries .\" .\" fileset_database@pfm_inhibit.3 PROGRAMING-MAN .\" $Header: pfm_init.3,v 72.4 94/10/27 14:42:32 ssa Exp $ .TA p .TH pfm_$init 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfm_$init \- initialize the process fault manager (\s-1PFM\s0) package .SH SYNOPSIS .C #include .br .C #include .PP .C void pfm_$init( .br .C " unsigned long \f2flags\fP)" .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RB `` $ '' character. .SH DESCRIPTION .C pfm_$init() initializes the .SM PFM package. The .I flags parameter indicates which initialization activities to perform. .PP Currently, only one .I flags value is valid: .RS .TP 12 .C pfm_$init_signal_handlers() Intercept C signals and convert them to .SM PFM signals. The following .SM HP-UX signals are intercepted: .SM .CR SIGINT , .CR SIGILL , .CR SIGFPE , .CR SIGTERM , .CR SIGHUP , .CR SIGQUIT , .CR SIGTRAP , .CR SIGBUS , .CR SIGSEGV , and .CR SIGSYS . On .SM MS-DOS systems, the first four of these, plus .CR SIGABRT , are intercepted. .RE .PP Applications that use the .SM PFM package should invoke .C pfm_$init() before invoking any other .SM NCS calls. .\" .\" index@\f4pfm_$init()\fP \- initialize the process fault manager package@@@\f3pfm_$init(3)\f1 .\" index@initialize the process fault manager package@@@\f3pfm_$init(3)\f1 .\" index@process fault manager package, initialize the@@@\f3pfm_$init(3)\f1 .\" index@PFM package, initialize the@@@\f3pfm_$init(3)\f1 .\" .\" toc@\f3pfm_$init(3)\f1:\0\0\f4pfm_$init()\fP@@@initialize the process fault manager package .\" .\" fileset_database@pfm_init.3 PROGRAMING-MAN .\" $Header: pfm_intro.3,v 72.4 94/10/27 14:43:10 ssa Exp $ .TA p .TH pfm_$intro 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfm_$intro \- fault management .SH SYNOPSIS .SS C Syntax .C #include .br .C #include .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RB `` $ '' character. .SH DESCRIPTION .C pfm_$() calls, part of the Network Computing System (NCS), allow programs to manage signals, faults, and exceptions by establishing cleanup handlers. .PP .RS .TP 20 .C pfm_$cleanup() Establish a cleanup handler. .TP .C pfm_$enable() Enable asynchronous faults. .TP .C pfm_$enable_faults() Enable asynchronous faults after faults have been inhibited via .CR pfm_$inhibit_faults() . .TP .C pfm_$inhibit() Inhibit asynchronous faults. .TP .C pfm_$inhibit_faults() Inhibit asynchronous faults but allow time-sliced task switching. .TP .C pfm_$init() Initialize the PFM package. .TP .C pfm_$reset_cleanup() Reset a cleanup handler. .TP .C pfm_$rls_cleanup() Release cleanup handlers. .TP .C pfm_$signal() Signal the calling process. .RE .SS "Cleanup Handlers" A cleanup handler is a piece of code that allows a program to terminate gracefully when it receives an error. A cleanup handler begins with a .C pfm_$cleanup() call and usually ends with a call to .C pfm_$signal() or .CR pgm_$exit() , though it can also simply continue back into the program after the cleanup code. .SS "Include Files in NCS Software" .RC < ppfm.h >, is the include file for the "portable PFM" interface. It supersedes .RC < pfm.h>, the include file that was provided in early releases of .SM NCS . .SS Constants .TP .C pfm_$init_signal_handlers A constant used as the .I flags parameter to .CR pfm_$init() , causing C signals to be intercepted and converted to .SM PFM signals. .SS Data Types .TP .C pfm_$cleanup_rec An opaque data type for passing process context among cleanup handler calls. .TP .C status_$t A status code. Most .SM NCS calls supply their completion status in this format. The .C status_$t type is defined as a structure containing a long integer: .RS .nf .IP .C struct status_$t { .br .C " long all;" .br .C " }" .RE .fi .IP However, the calls can also use .C status_$t as a set of bit fields. To access the fields in a returned status code, assign the value of the status code to a union defined as follows: .RS .nf .IP .C typedef union { .C " struct {" .C " unsigned fail : 1," .C " subsys : 7," .C " modc : 8;" .C " short code;" .C " } s;" .C " long all;" .C } status_u; .RE .fi .IP where: .RS .RS .TP 10 .C all All 32 bits in the status code. If .C all is equal to .CR status_$ok , the call that supplied the status was successful. .TP .C fail If this bit is set, the error was not within the scope of the module invoked, but occurred within a lower-level module. .TP .C subsys This indicates the subsystem that encountered the error. .TP .C modc This indicates the module that encountered the error. .TP .C code This is a signed number that identifies the type of error that occurred. .RE .RE .SS Status Codes .TP 10 .C pfm_$bad_rls_order Attempted to release a cleanup handler out of order. .TP .C pfm_$cleanup_not_found There is no pending cleanup handler. .TP .C pfm_$cleanup_set A cleanup handler was established successfully. .TP .C pfm_$cleanup_set_signalled Attempted to use .C pfm_$cleanup_set as a signal. .TP .C pfm_$invalid_cleanup_rec Passed an invalid cleanup record to a call. .TP .C pfm_$no_space Cannot allocate storage for a cleanup handler. .TP .C status_$ok The call was successful. .SH SEE ALSO pfm_$cleanup(3), pfm_$enable(3), pfm_$enable_faults(3), pfm_$inhibit(3), pfm_$inhibit_faults(3), pfm_$init(3), pfm_$reset_cleanup(3), pfm_$rls_cleanup(3), pfm_$signal(3). .\" .\" index@pfm_$intro \- fault management@@@\f3pfm_$intro(3)\f1 .\" index@fault management@@@\f3pfm_$intro\f1 .\" index@process fault management@@@\f3pfm_$intro(3)\f1 .\" index@cleanup handlers@@@\f3pfm_$intro(3)\f1 .\" index@\f3pfm.h\f1@@@\f3pfm_$intro(3)\f1 .\" index@\f3std_$call\f1@@@\f3pfm_$intro(3)\f1 .\" index@managing signal exceptions@@@\f3pfm_$intro(3)\f1 .\" index@signal exceptions, managing@@@\f3pfm_$intro(3)\f1 .\" index@exceptions, managing signal@@@\f3pfm_$intro(3)\f1 .\" index@portable pfm_$ interface@@@\f3pfm_$intro(3)\f1 .\" index@\f3pfm_$cleanup_rec\f1@@@\f3pfm_$intro(3)\f1 .\" index@\f3pfm_$init_signal_handlers\f1@@@\f3pfm_$intro(3)\f1 .\" index@\f3pfm_$bad_rls_order\f1@@@\f3pfm_$intro(3)\f1 .\" index@\f3pfm_$cleanup_not_found\f1@@@\f3pfm_$intro(3)\f1 .\" index@\f3pfm_$cleanup_set\f1@@@\f3pfm_$intro(3)\f1 .\" index@\f3pfm_$cleanup_set_signalled\f1@@@\f3pfm_$intro(3)\f1 .\" index@\f3pfm_$invalid_cleanup_rec\f1@@@\f3pfm_$intro(3)\f1 .\" index@\f3pfm_$no_space\f1@@@\f3pfm_$intro(3)\f1 .\" .\" toc@\f3pfm_$intro(3)\f1:\0\0pfm_$intro@@@fault management .\" .\" fileset_database@pfm_intro.3 PROGRAMING-MAN .\" $Header: pfm_reset_c.3,v 74.1 95/03/23 18:05:46 ssa Exp $ .TA p .TH pfm_$reset_cleanup 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfm_$reset_cleanup \- reset a cleanup handler .SH SYNOPSIS .C #include .br .C #include .C void pfm_$reset_cleanup( .br .C " pfm_$cleanup_rec *\f2cleanup_record\fP," .br .C " status_$t *\f2status\fP)" .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RB `` $ '' character. .SH DESCRIPTION .C pfm_$reset_cleanup() re-establishes the cleanup handler last entered so that any subsequent errors enter it first. This procedure should only be used within cleanup handler code. .PP A .C pfm_$reset_cleanup() implicitly performs a .CR pfm_$enable() , thereby undoing the implicit .C pfm_$inhibit() that .C pfm_$cleanup() performs. .RS .TP 15 .I cleanup_record A record of the context at the cleanup handler entry point. It is supplied by .I pfm_$cleanup when the cleanup handler is first established. .TP .I status The completion status. .\" .\" index@\f2pfm_$reset_cleanup\f1 \- reset a cleanup handler@@@\f3pfm_$reset_cleanup(3)\f1 .\" index@reset a cleanup handler@@@\f3pfm_$reset_cleanup(3)\f1 .\" index@cleanup handler, reset a@@@\f3pfm_$reset_cleanup(3)\f1 .\" index@handler, reset a cleanup@@@\f3pfm_$reset_cleanup(3)\f1 .\" .\" toc@\f3pfm_$reset_cleanup(3)\f1:\0\0\f2pfm_$reset_cleanup\f1@@@reset a cleanup handler .\" .\" fileset_database@pfm_reset_c.3 PROGRAMING-MAN .\" $Header: pfm_rls_cle.3,v 72.4 94/10/27 14:44:23 ssa Exp $ .TA p .TH pfm_$rls_cleanup 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfm_$rls_cleanup \- release a cleanup handler .SH SYNOPSIS .C #include \f1 .br .C #include \f1 .C void pfm_$rls_cleanup( .br .C " pfm_$cleanup_rec *\f2cleanup_record\fP, .br .C " status_$t *\f2status\fP) .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RB `` $ '' character. .SH DESCRIPTION .C pfm_$rls_cleanup() releases the cleanup handler associated with .CR cleanup_record() . .PP On Apollo systems, this call releases the specified cleanup handler and all cleanup handlers established after it. .PP On all other systems, this call releases only the specified cleanup handler, and only the most recently established cleanup handler can be released. .PP If you are concerned about portability, use .C pfm_$rls_cleanup() only to release the most recent cleanup handler. .PP .I cleanup_record specifies the cleanup record to be released by the cleanup handler. .PP .I status is the completion status. .SH ERRORS .TP .C pfm_$bad_rls_order The caller attempted to release a cleanup handler other than the one most recently established. On Apollo systems, this status is only a warning; the specified cleanup handler is released, along with any established after it. On other systems, this status probably indicates a user programming error; no cleanup handlers are released, and continued execution may result in more serious errors. .\" .\" index@\f4pfm_$rls_cleanup()\fP \- release a cleanup handler@@@\f3pfm_$rls_cleanup(3)\f1 .\" index@release a cleanup handler@@@\f3pfm_$rls_cleanup(3)\f1 .\" index@cleanup handler, release a@@@\f3pfm_$rls_cleanup(3)\f1 .\" index@handler, release a cleanup@@@\f3pfm_$rls_cleanup(3)\f1 .\" .\" toc@\f3pfm_$rls_cleanup(3)\f1:\0\0\f4pfm_$rls_cleanup()\fP@@@release a cleanup handler .\" .\" fileset_database@pfm_rls_cle.3 PROGRAMING-MAN .\" $Header: pfm_signal.3,v 72.4 94/10/27 14:44:41 ssa Exp $ .TA p .TH pfm_$signal 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfm_$signal \- signal the calling process .SH SYNOPSIS .C #include .br .C #include .PP .C void pfm_$signal(status_$t \f2fault_signal\fP) .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RB `` $ '' character. .SH DESCRIPTION .C pfm_$signal() signals the fault specified by .I fault_signal to the calling process. It is usually called to leave cleanup handlers. .TP 15 .I fault_signal A fault code. .SH NOTE This call does not return when successful. .\" .\" index@\f4pfm_$signal()\fP \- signal the calling process@@@\f3pfm_$signal(3)\f1 .\" index@signal the calling process@@@\f3pfm_$signal(3)\f1 .\" index@calling process, signal the@@@\f3pfm_$signal(3)\f1 .\" index@process, signal the calling@@@\f3pfm_$signal(3)\f1 .\" index@exiting cleanup handlers@@@\f3pfm_$signal(3)\f1 .\" index@cleanup handlers, exiting@@@\f3pfm_$signal(3)\f1 .\" .\" toc@\f3pfm_$signal(3)\f1:\0\0\f4pfm_$signal()\fP@@@signal the calling process .\" .\" fileset_database@pfm_signal.3 PROGRAMING-MAN .\" $Header: pfmt.3c,v 72.3 94/07/22 11:26:34 ssa Exp $ .TA p .TH pfmt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfmt(), vpfmt() \- display message in standard format .SH SYNOPSIS .nf .C "#include " .C "int pfmt(FILE *stream, long flags, char *fmt, /* [arg, ] */ ...);" .PP .C "#include " .C "#include " .C "int vpfmt(FILE *stream, long flags, char *fmt, va_list ap);" .fi .SH DESCRIPTION The .CR pfmt() system call can be used to write a message in standard format to .IR stream . It can also be used to write a localized string to .IR stream . The arguments to .CR pfmt() are formatted using .CR printf() style formatting. .CR vpfmt() is similar to .CR pfmt() except that the arguments are passed in an argument list (see .IR stdarg (5)). .PP The standard format displayed to .I stream has the following fields: .IP .IC label : severity : text .PP The .I label string is defined through .IR setlabel (3C). If no label is defined, this field is not used. The .I severity string is controlled by the .I severity group of .IR flags . The .I text string is the formatted user string. .PP The .I flags control how formatting is done. The control information is separated into several different groups. Only one flag from each group should be set. .RS .TP .B "Output Format" .RS .TP 20 .C MM_NOSTD Do not use the standard format. Treat .I fmt as a .CR printf() format string. In this mode, only flags related to catalog access can be set. .TP .C MM_STD Format using the standard format .RC ( MM_STD is the default). .RE .TP .B "Catalog Access" .RS .TP 20 .C MM_NOGET Do not access the localized message catalog. Use the .I def_str (a field in .I fmt ) as the format string. .TP .C MM_GET Access the localized message catalog .RC ( MM_GET is the default). .RE .TP .B "Severity" .RS .TP 20 .C MM_HALT Display a localized .CR HALT string. .TP .C MM_ERROR Display a localized .CR ERROR string .RC ( MM_ERROR is the default). .TP .C MM_WARNING Display a localized .CR WARNING string. .TP .C MM_INFO Display a localized .CR INFO string. .RE .IP Besides these reserved severities, additional severity strings may be defined by the user (see .IR addsev (3C)). To specify a user defined severity, .IR flags should be a logical-or of the numeric value of the user defined severity and flags from other control groups. .TP .B "Action" .RS .TP 20 .C MM_ACTION This flag generates the localized string of .CR "TO FIX:" in the .I severity field of the standard format message. If this flag and flags from the severity control group are set, this flag has precedence and the .CR "TO FIX:" string will be displayed. .RE .RE .PP The .I fmt string has the following fields: .IP .IC catalog : msg_number : def_str .PP The .I catalog is the message catalog created by .IR mkmsgs (1) where the localized message is to be retrieved. The .I msg_number is a positive index number identifying the string to be retrieved from the message catalog (begins at 1). The .I def_str is the default string to use if .CR pfmt() fails to retrieve the message from .I catalog from either the current locale or the default locale. The failure may occur if the message catalog does not exist or if the .I msg_number is out of bound. .PP If .I catalog is not specified, .CR pfmt() uses the message catalog defined by .IR setcat (3C). If .CR MM_NOGET is set in .IR flags , only .I def_str must be specified. .PP The .CR pfmt() system call displays .CR "Message not found!!" under the following conditions: .RS .TP 3 \(bu No message catalog is specified in .I fmt and no catalog is defined via .IR setcat (3C). .TP \(bu .I msg_number is not positive. .TP \(bu No message could be retrieved and .I def_str is not specified. .RE .SH RETURN VALUE If successful, .CR pfmt() and .CR vpfmt() return the number of bytes written. Otherwise they return a negative value. .SH EXAMPLES Example 1 .nf .IP .C setlabel("UX:my_appl"); .C pfmt(stderr, MM_INFO,"MY_cat:1:file is writable"); .fi .PP generates the message: .IP .C UX:my_appl: INFO: file is writable .PP Example 2 .nf .IP .C setlabel(""); .C setcat("MY_cat"); .C "pfmt(stderr, MM_ERROR,"":1:%s is writable"", ""my_file"");" .fi .PP generates the message: .IP .C ERROR: my_file is writable .RE .PP Example 3 .nf .IP .C setlabel(""); .C setcat("MY_cat"); .C "pfmt(stderr, MM_NOSTD,"":1:%s is writable"", ""my_file"");" .fi .PP generates the message: .IP .C my_file is writable .RE .PP Example 4 .nf .IP .C #define MM_USER 10 .C setlabel(""); .C "addsev(MM_USER, ""MY_NOTE"");" .C "pfmt(stderr, MM_USER|MM_GET,""MY_cat:1:%s is writable"", ""my_file"");" .fi .PP generates the message: .IP .C MY_NOTE: my_file is writable .RE .SH SEE ALSO mkmsgs(1), addsev(3C), gettxt(3C), setcat(3C), setlabel(3C), setlocale(3C), printf(3S), stdarg(5). .SH STANDARDS COMPLIANCE .CR pfmt() ": SVID3" .PP .CR vpfmt() ": SVID3" .\" .\" toc@\f3pfmt(3C)\f1:\0\0\f4pfmt()\f1, \f4vpfmt()\f1@@@display message in standard format\f1 .\" toc@\f3vpfmt()\f1:\0\0\f1@@@display message in standard format, using argument list\f1@@@\f1see \f3pfmt(3C)\f1 .\" .\" index@\f4pfmt()\f1 \- display message in standard format@@@\f3pfmt(3C)\f1 .\" index@\f4vpfmt()\f1 \- display message in standard format@@@\f3pfmt(3C)\f1 .\" index@\f4pfmt()\f1 \- message, display in standard format@@@\f3pfmt(3C)\f1 .\" index@\f4pfmt()\f1 \- standard format, display message in@@@\f3pfmt(3C)\f1 .\" .\" links@pfmt.3c vpfmt.3c .\" $Header: pgm_exit.3,v 72.4 94/10/27 14:45:09 ssa Exp $ .TA p .TH pgm_$exit 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pgm_$exit(\|) \- exit a program .SH SYNOPSIS .C #include .br .C #include .PP .C void pgm_$exit(void) .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RC `` $ '' character. .SH DESCRIPTION .C pgm_$exit() exits from the calling program. .PP Any cleanup handlers that have been established are executed in sequence from the most recently established to the first. .PP On Apollo systems, this call invokes .C pfm_$signal() with a fault code equal to the last severity level set by .CR pgm_$set_severity() , or .C pgm_$ok() if .C pgm_$set_severity() was not called. .PP On other systems, this call invokes .C pfm_$signal() with a fault code of .CR status_$ok . .SH SEE ALSO pfm_$cleanup(3), pfm_$signal(3). .\" .\" index@\f4pgm_$exit()\fP \- exit a program@@@\f3pgm_$exit(3)\f1 .\" index@exit a program@@@\f3pgm_$exit\f1 .\" index@program, exit a@@@\f3pgm_$exit(3)\f1 .\" .\" toc@\f3pgm_$exit(3)\f1:\0\0\f4pgm_$exit()\fP@@@exit a program .\" .\" fileset_database@pgm_exit.3 PROGRAMING-MAN .\" $Header: pgm_intro.3,v 72.4 94/10/27 14:45:58 ssa Exp $ .TA p .TH pgm_$intro 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pgm_$intro(\|) \- program management .SH SYNOPSIS .C #include .br .C #include .SS Remarks To view this manual entry via the .IR man (1) command, use the function name shown above without the .RB `` $ '' character. .SH DESCRIPTION .ig The .C pgm_$ calls allow programs to invoke other programs, pass system resources to child processes, and monitor their status. .PP .. A portable version of the Apollo Domain/OS .C pgm_$exit() call is supplied with .SM NCS software products. The include file for the ``portable .SM PFM\s0'' interface contains a declaration for this call. .\" .\" index@pgm_$intro \- program management@@@\f3pgm_$intro(3)\f1 .\" index@program management@@@\f3pgm_$intro(3)\f1 .\" index@management, program@@@\f3pgm_$intro(3)\f1 .\" .\" toc@\f3pgm_$intro(3)\f1:\0\0pgm_$intro@@@program management .\" .\" fileset_database@pgm_intro.3 PROGRAMING-MAN .\" $Header: newpad.3x,v 76.2 95/08/01 14:27:39 ssa Exp $ .TA n .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH newpad 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 newpad .SH NAME newpad, pnoutrefresh, prefresh \(em pad management functions .SH SYNOPSIS .C "#include " .P .C "WINDOW *newpad(int \f2nlines\fP, int \f2ncols\fP);" .P .C "int pnoutrefresh(WINDOW *\f2pad\fP, int \f2pminrow\fP, int \f2pmincol\fP, int \f2sminrow\fP," .br .C " int \f2smincol\fP, int \f2smaxrow\fP, int \f2smaxcol\fP);" .P .C "int prefresh(WINDOW *\f2pad\fP, int \f2pminrow\fP, int \f2pmincol\fP, int \f2sminrow\fP," .br .C " int \f2smincol\fP, int \f2smaxrow\fP, int \f2smaxcol\fP);" .SH DESCRIPTION The .Fn newpad function creates a specialised .CR WINDOW data structure representing a pad with \f2nlines\f1 lines and \f2ncols\f1 columns. A pad is like a window, except that it is not necessarily associated with a viewable part of the screen. Automatic refreshes of pads do not occur. .P The .Fn prefresh and .Fn pnoutrefresh functions are analogous to .Fn wrefresh and .Fn wnoutrefresh except that they relate to pads instead of windows. The additional arguments indicate what part of the pad and screen are involved. The \f2pminrow\f1 and \f2pmincol\f1 arguments specify the origin of the rectangle to be displayed in the pad. The \f2sminrow\f1, \f2smincol\f1, \f2smaxrow\f1 and \f2smaxcol\f1 arguments specify the edges of the rectangle to be displayed on the screen. The lower right-hand corner of the rectangle to be displayed in the pad is calculated from the screen coordinates, since the rectangles must be the same size. Both rectangles must be entirely contained within their respective structures. Negative values of \f2pminrow\f1, \f2pmincol\f1, \f2sminrow\f1 or \f2smincol\f1 are treated as if they were zero. .SH "RETURN VALUE" Upon successful completion, the .Fn newpad function returns a pointer to the pad data structure. Otherwise, it returns a null pointer. .P Upon successful completion, .Fn pnoutrefresh and .Fn prefresh return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" To refresh a pad, call .Fn prefresh or .CR pnoutrefresh() , not .CR wrefresh() . When porting code to use pads from WINDOWS, remember that these functions require additional arguments to specify the part of the pad to be displayed and the location on the screen to be used for the display. .P Although a subwindow and its parent pad may share memory representing characters in the pad, they need not share status information about what has changed in the pad. Therefore, after modifying a subwindow within a pad, it may be necessary to call .Fn touchwin or .Fn touchline on the pad before calling .CR prefresh() . .SH "SEE ALSO" derwin(), doupdate(), is_linetouched(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn pnoutrefresh and .Fn prefresh functions are merged with this entry. In previous issues, they appeared in the entry for .CR prefresh() . .\" .\" toc@\f3newpad(3X)\f1:\0\0\f4newpad()\f1, \f4pnoutrefresh()\f1, \f4prefresh()\f1@@@pad management functions .\" toc@\f4pnoutrefresh()\f1: pad management functions@@@see \f3newpad(3X)\f1 .\" toc@\f4prefresh()\f1: pad management functions@@@see \f3newpad(3X)\f1 .\" .\" index@\f4newpad()\f1 \- pad management functions@@@\f3newpad(3X)\f1 .\" index@\f4pnoutrefresh()\f1 \- pad management functions@@@\f3newpad(3X)\f1 .\" index@\f4prefresh()\f1 \- pad management functions@@@\f3newpad(3X)\f1 .\" index@\f1pad management functions@@@\f3newpad(3X)\f1 .\" index@\f1management functions, for pad@@@\f3newpad(3X)\f1 .\" index@\f1functions, for pad management@@@\f3newpad(3X)\f1 .\" .\" links@newpad.3x pnoutrefresh.3x .\" links@newpad.3x prefresh.3x .\" .\" fileset_database@newpad.3x CURS-ENG-A-MAN .\" $Header: popen.3s,v 72.5 94/11/15 09:55:37 ssa Exp $ .TA p .TH popen 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME popen(\|), pclose(\|) \- initiate pipe I/O to/from a process .SH SYNOPSIS .C "#include " .PP .C "FILE *popen(const char *command, const char *type);" .PP .C "int pclose(FILE *stream);" .SH DESCRIPTION .C popen() creates a pipe between the calling program and a command to be executed by the .SM POSIX shell, .C /usr/bin/sh (see .IR sh-posix (1)). .PP The arguments to .C popen() are pointers to null-terminated strings containing, respectively, a shell command line and an I/O mode, either .C r for reading or .C w for writing. .PP .C popen() returns a stream pointer such that one can write to the standard input of the command if the I/O mode is .C w by writing to the file .IR stream ; and one can read from the standard output of the command if the I/O mode is .C r by reading from the file .IR stream . .PP A stream opened by .C popen() should be closed by .CR pclose() , which waits for the associated process to terminate and returns the exit status of the command. .PP Because open files are shared, a type .C r command can be used as an input filter and a type .C w command as an output filter. .SH RETURN VALUE .C popen() returns a .SM NULL pointer if files or processes cannot be created. The success of the command execution can be checked by examining the return value of .CR pclose() . .PP .C pclose() returns .C -1 if .I stream is not associated with a .CR popen() ed command, or 127 if .C /usr/bin/sh could not be executed for some reason. .SH WARNINGS If the original and .CR popen() ed processes concurrently read or write a common file, neither should use buffered .SM I/O because the buffering will not work properly. Problems with an output filter can be forestalled by careful buffer flushing, e.g., with .CR fflush() ; see .IR fclose (3S). .SH SEE ALSO pipe(2), wait(2), fclose(3S), fopen(3S), system(3S). .SH STANDARDS CONFORMANCE .CR popen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .PP .CR pclose() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2" .\" .\" index@\f4popen()\fP \- initiate pipe \s-1I/O\s+1 to or from a process@@@\f3popen(3S)\f1 .\" index@\f4pclose()\fP \- terminate pipe \s-1I/O\s+1 to or from a process@@@\f3popen(3S)\f1 .\" index@close or open pipe \s-1I/O\s+1 to or from a process@@@\f3popen(3S)\f1 .\" index@\s-1I/O\s+1 pipe to or from a process, open or close@@@\f3popen(3S)\f1 .\" index@open or close pipe \s-1I/O\s+1 to or from a process@@@\f3popen(3S)\f1 .\" index@pipe \s-1I/O\s+1 to or from a process, open or close@@@\f3popen(3S)\f1 .\" index@process, open or close pipe \s-1I/O\s+1 to or from a@@@\f3popen(3S)\f1 .\" .\" toc@\f3popen(3S)\f1:\0\0\f4popen()\fP, \f4pclose()\fP@@@initiate pipe \s-1I/O\s+1 to/from a process .\" toc@\f4pclose()\fP:\0\0initiate pipe \s-1I/O\s+1 to/from a process@@@see \f3popen(3S)\f1 .\" .\" links@popen.3s pclose.3s .\" .\" fileset_database@popen.3s PROGRAMING-MAN .\" $Header: portmap.3c,v 72.2 94/08/09 11:49:08 ssa Exp $ .TA p .TH portmap 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pmap_getmaps, pmap_getport, pmap_rmtcall, pmap_set, pmap_unset, xdr_pmap, xdr_pmaplist \- library of routines for RPC binder services .SH SYNOPSIS .nf .C "#include " .C " " .C "/* pmap_getmaps() */" .C "struct pmaplist *" .C "pmap_getmaps(addr)" .C "struct sockaddr_in *addr;" .C " " .C "/* pmap_getport() */" .C "u_short" .C "pmap_getport(addr, prognum, versnum, protocol)" .C "struct sockaddr_in *addr;" .C "u_long prognum, versnum, protocol;" .C " " .C "/* pmap_rmtcall */" .C "enum clnt_stat" .C "pmap_rmtcall(addr, prognum, versnum, procnum, inproc, in," .C "\0\0\0\0\0\0\0\0\0\0\0\0\0\0outproc, out, timeout, portp)" .C "struct sockaddr_in *addr;" .C "u_long prognum, versnum, procnum;" .C "xdrproc_t inproc, outproc;" .C "char *in, *out;" .C "struct timeval timeout;" .C "u_long *portp;" .C " " .C "/* pmap_set */" .C "bool_t" .C "pmap_set(prognum, versnum, protocol, port)" .C "u_long prognum, versnum;" .C "int protocol;" .C "u_short port;" .C " " .C "/* pmap_unset */" .C "bool_t" .C "pmap_unset(prognum, versnum)" .C "u_long prognum, versnum;" .C " " .C "/* xdr_pmap */" .C "bool_t" .C "xdr_pmap(xdrs, regp)" .C "XDR *xdrs;" .C "struct pmap *regp;" .C " " .C "/* xdr_pmaplist */" .C "bool_t" .C "xdr_pmaplist(xdrs, rp)" .C "XDR *xdrs;" .C "struct pmaplist *rp;" .C " " .fi .SH DESCRIPTION .C portmap() maintains a list of mappings between programs and their universal addresses. These .C portmap() routines allow C client programs to make procedure calls to the RPC binder service. .SS Routines To use these routines, the C programs must include the header file .CR . .RS .TP 20 .CR pmap_getmaps ( ) Return a list of the current RPC program-to-address mappings on the host located at the registered IP address, .IR *addr . This routine returns NULL if the remote portmap service could not be contacted. The command .CR "rpcinfo \-p" uses this routine (see .IR rpcinfo (1M) for more information). .TP .CR pmap_getport ( ) Return the port number of a waiting service. The remote (waiting) service supports the program number, .I prognum , version number, .I versnum , and speaks the transport protocol, .I protocol . The value of .I protocol can be .CR IPPROTO_UDP , indicating that UDP/IP protocol is being used, or .CR IPPROTO_TCP , indicating that TCP/IP protocol is being used. The address is returned to .C portmap() in .IR addr , and should be a preallocated IP address. This routine returns a value of zero if the RPC binder service does not find a mapping for the service or if the RPC system fails to contact the remote portmap service. In the latter case, the global variable .I rpc_createer , which is documented in .IR rpc_clnt_create (3C) , contains the RPC status. The call returns a port number if any version number is registered for the referenced program number (even if the requested version number is not registered). .IP .B Note: .CR pmap_getport() returns the port number in host-byte order. Some other network routines may require the port number in network-byte order. For example, if the port number is used as part of the .C sockaddr_in structure, then it should be converted to network-byte order using .CR htons( ). .TP .CR pmap_rmtcall ( ) Request that the portmap on the host at IP address, .IR *addr , make an RPC on the behalf of the caller to a procedure on that host. .I *portp is changed to the program's port number if the procedure succeeds. The definitions of other parameters are provided in the descriptions for .CR callrpc() and .CR clnt_call() (see .IR rpc_clnt_calls(3C) ). .IP .B Warning: If the requested remote procedure is not registered with the remote portmap, no error response is returned and the call times out. Also, no authentication is done. .TP .CR pmap_set ( ) Register a mapping between .RI [ prognum , versnum , protocol\f1] and .I port on the local machine's portmap service. The value of .I protocol can be .CR IPPROTO_UDP , indicating that UDP/IP protocol is being used, or .CR IPPROTO_TCP , indicating that TCP/IP protocol is being used. This routine allows servers to register themselves with the local .C portmap(), and is done automatically by .CR svc_register() . It returns TRUE if it succeeds; otherwise, it returns FALSE. .TP .CR pmap_unset ( ) Deregister all mappings between .RI [ prognum , versnum , *\f1] and ports on the local machine's portmap service. This routine allows servers to deregister themselves with the local .CR portmap() . It returns TRUE if it succeeds; otherwise, it returns FALSE. .TP .CR xdr_pmap ( ) Create parameters to various .CR portmap() procedures, externally. This routine allows users to generate .CR portmap() parameters without using the .C pmap interface. It returns TRUE if it succeeds; otherwise, it returns FALSE. .TP .CR xdr_pmaplist ( ) Create a list of port mappings, externally. This routine allows users to generate .CR portmap() parameters without using the .C pmap interface. It returns TRUE if it succeeds; otherwise, it returns FALSE. .RE .SH AUTHOR .C portmap() and .C rpc() were developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M), rpcinfo(1M), rpc(3C), xdr(3C) .\" .\" index@\f4portmap(3C)\f1 \- library of routines for RPC binder services@@@\f3portmap(3C)\f1 .\" index@\f4pmap_getmaps\f1 \- return RPC program-to-address mappings@@@\f3portmap(3C)\f1 .\" index@\f4pmap_getport\f1 \- return port number of waiting RPC service@@@\f3portmap(3C)\f1 .\" index@\f4pmap_rmtcall\f1 \- request RPC on a remote host@@@\f3portmap(3C)\f1 .\" index@\f4pmap_set\f1 \- register server with local portmap@@@\f3portmap(3C)\f1 .\" index@\f4pmap_unset\f1 \- deregister server with local portmap@@@\f3portmap(3C)\f1 .\" index@\f4xdr_pmap\f1 \- create external parameters to portmap procedures@@@\f3portmap(3C)\f1 .\" index@\f4xdr_pmaplist\f1 \- create external list of port mappings@@@\f3portmap(3C)\f1 .\" .\" toc@\f3portmap(3C)\f1:\0\0\f4portmap\f1@@@library of routines for RPC binder services .\" $Header: pow.3m,v 78.1 96/02/13 13:32:46 ssa Exp $ .TA p .TH pow 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pow(\|), powf(\|) \- power functions .SH SYNOPSIS .C "#include " .PP .C "double pow(double x, double y);" .PP .C "float powf(float x, float y);" .SH DESCRIPTION The .CR pow() function returns .ifn .IR x "**" y . .ift \f2x\u\s-2y\s0\d\f1. If .I x is zero, .I y must be positive. If .I x is negative, .I y must be an integer. .PP The .CR powf() function is a .CR float version of .CR pow() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR powf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is greater than 1.0 and .I y is +INFINITY, .CR pow() returns +INFINITY. .PP If .I x is greater than 1.0 and .I y is \(miINFINITY, .CR pow() returns zero. .PP If .I x is between zero and 1.0 and .I y is \(miINFINITY, .CR pow() returns +INFINITY. .PP If .I x is between zero and 1.0 and .I y is +INFINITY, .CR pow() returns zero. .PP If .I x is +INFINITY and .I y is greater than zero, .CR pow() returns +INFINITY. .PP If .I x is +INFINITY and .I y is less than zero, .CR pow() returns zero. .PP If .I x is \(miINFINITY and .I y is an even integer greater than zero, .CR pow() returns +INFINITY. .PP If .I x is \(miINFINITY and .I y is an odd integer greater than zero, .CR pow() returns \(miINFINITY. .PP If .I x and .I y are both zero, .CR pow() returns 1.0. .PP If .I x or .I y is NaN, .CR pow() returns NaN. .PP If .I x is negative and .I y .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR pow() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR pow() returns zero. .PP If .I x is zero and .I y is negative, .CR pow() returns .CR \(miHUGE_VAL and sets .CR errno to [EDOM]. .PP If .I x is negative and .I y is not an integer, .CR pow() returns NaN and sets .CR errno to [EDOM]. .PP If the correct value would overflow, .CR pow() returns .ift .CR \(+-HUGE_VAL .ifn .CR +\-HUGE_VAL and sets .CR errno to [ERANGE]. .SH ERRORS If .CR pow() fails, .CR errno is set to one of the following values. .RS .TP 20 [EDOM] .I x is zero and .I y is negative. .TP 20 [EDOM] .I x is negative and .I y is not an integer. .TP 20 [ERANGE] The correct value would overflow. .RE .SH DEPENDENCIES Millicode versions of the .CR pow() function are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO cbrt(3M), exp(3M), isinf(3M), isnan(3M), log(3M), sqrt(3M), values(5). .SH STANDARDS CONFORMANCE .CR pow() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4pow()\f1, \f4powf()\f1 \- power function@@@\f3pow(3M)\f1 .\" index@\f4powf()\f1, \f4pow()\f1 \- power function (float version)@@@\f3pow(3M)\f1 .\" index@\f1math: power functions@@@\f3pow(3M)\f1 .\" index@\f1power functions@@@\f3pow(3M)\f1 .\" .\" toc@\f3pow(3M)\f1:\0\0\f4pow()\f1, \f4powf()\f1@@@power functions\f1 .\" toc@\f4powf()\f1:\0\0power function (float version)@@@\f1see \f3pow(3M)\f1 .\" .\" links@pow.3m powf.3m .\" $Header: pow.3m,v 78.1 96/02/13 13:32:46 ssa Exp $ .TA p .TH pow 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pow(\|), powf(\|) \- power functions .SH SYNOPSIS .C "#include " .PP .C "double pow(double x, double y);" .PP .C "float powf(float x, float y);" .SH DESCRIPTION The .CR pow() function returns .ifn .IR x "**" y . .ift \f2x\u\s-2y\s0\d\f1. If .I x is zero, .I y must be positive. If .I x is negative, .I y must be an integer. .PP The .CR powf() function is a .CR float version of .CR pow() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR powf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is greater than 1.0 and .I y is +INFINITY, .CR pow() returns +INFINITY. .PP If .I x is greater than 1.0 and .I y is \(miINFINITY, .CR pow() returns zero. .PP If .I x is between zero and 1.0 and .I y is \(miINFINITY, .CR pow() returns +INFINITY. .PP If .I x is between zero and 1.0 and .I y is +INFINITY, .CR pow() returns zero. .PP If .I x is +INFINITY and .I y is greater than zero, .CR pow() returns +INFINITY. .PP If .I x is +INFINITY and .I y is less than zero, .CR pow() returns zero. .PP If .I x is \(miINFINITY and .I y is an even integer greater than zero, .CR pow() returns +INFINITY. .PP If .I x is \(miINFINITY and .I y is an odd integer greater than zero, .CR pow() returns \(miINFINITY. .PP If .I x and .I y are both zero, .CR pow() returns 1.0. .PP If .I x or .I y is NaN, .CR pow() returns NaN. .PP If .I x is negative and .I y .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR pow() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR pow() returns zero. .PP If .I x is zero and .I y is negative, .CR pow() returns .CR \(miHUGE_VAL and sets .CR errno to [EDOM]. .PP If .I x is negative and .I y is not an integer, .CR pow() returns NaN and sets .CR errno to [EDOM]. .PP If the correct value would overflow, .CR pow() returns .ift .CR \(+-HUGE_VAL .ifn .CR +\-HUGE_VAL and sets .CR errno to [ERANGE]. .SH ERRORS If .CR pow() fails, .CR errno is set to one of the following values. .RS .TP 20 [EDOM] .I x is zero and .I y is negative. .TP 20 [EDOM] .I x is negative and .I y is not an integer. .TP 20 [ERANGE] The correct value would overflow. .RE .SH DEPENDENCIES Millicode versions of the .CR pow() function are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO cbrt(3M), exp(3M), isinf(3M), isnan(3M), log(3M), sqrt(3M), values(5). .SH STANDARDS CONFORMANCE .CR pow() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4pow()\f1, \f4powf()\f1 \- power function@@@\f3pow(3M)\f1 .\" index@\f4powf()\f1, \f4pow()\f1 \- power function (float version)@@@\f3pow(3M)\f1 .\" index@\f1math: power functions@@@\f3pow(3M)\f1 .\" index@\f1power functions@@@\f3pow(3M)\f1 .\" .\" toc@\f3pow(3M)\f1:\0\0\f4pow()\f1, \f4powf()\f1@@@power functions\f1 .\" toc@\f4powf()\f1:\0\0power function (float version)@@@\f1see \f3pow(3M)\f1 .\" .\" links@pow.3m powf.3m .\" $Header: prcmd.3n,v 72.3 94/11/30 10:15:18 ssa Exp $ .TA p .TH prcmd 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" ========== .SH NAME prcmd \- return streams to parallel remote commands .\" ========== .SH SYNOPSIS .C #include .PP .C "void prcmd_init (" .nf .PD 0 .IP .C "struct prc_host *hostp," .C "int num_hosts," .C "int caller_status," .C "char *command," .C "time_t timeout" .PP .C ");" .PD .fi .PP .C "int prcmd (" .nf .PD 0 .IP .C "struct prc_host *hostp," .C "int num_hosts" .PP .C ");" .PD .fi .\" =========== .SS Remarks These functions reside in libdc, and are linked using the .C -ldc option to the .C ld or .C cc command. .\" ========== .SH DESCRIPTION .C prcmd() is an interface similar to .C rcmd() that allows a client-side calling program to use an existing .C rcmd() server side daemon. .CR prcmd() , however, performs in parallel across multiple systems, the time consuming steps associated with executing commands remotely (connection, command invocation, and command execution/interaction). With .CR rcmd() , only command execution and interaction is under the control of the calling program, and it requires the calling program to perform its own .C select() calls in order to manage multiple (parallel) connections. .\" ---------- .PP Features of the existing server-side remote-shell daemon .RC ( remshd ) include: well known service, access control, and shell processing of the command line. .\" ---------- .PP The calling program passes .C prcmd() a pointer .RI ( hostp ) to the first node in a list of hosts for which to initiate, or continue, remote command processing via Internet socket connections. It also supplies the number of hosts in the list .RI ( num_hosts ). .\" ---------- .PP The calling program makes repeated calls to .C prcmd() to advance the status of the host connections. Each call to .C prcmd() causes a single call of .C select() to check the status of all connections that require checking (if there are any). Once a connection (to a remote command) is ready for reading, the calling program can read data from it, optionally write data to it, and then wait for more data to be ready to read back from it. .\" ========== .SS Header File The .C header file defines a .C prc_host structure containing the following fields of interest: .\" ---------- .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. char@*prc_hostid;@/* host name or IP address@*/ int@prc_prev_status;@/* previous connection status@*/ int@prc_conn_status;@/* connection status@*/ time_t@prc_conn_time;@/* time of connection@*/ int@prc_errno;@/* for failed connections@*/ char@*prc_errmsg;@/* string from remshd@*/ FILE@*prc_fp;@/* file ptr to stdin/stdout@*/ FILE@*prc_fp2;@/* file pointer to stderr@*/ int@prc_conn_close;@/* flag: close connection@*/ int@prc_caller_status;@/* caller's info about conn@*/ .TE .ft P .RE .\" ---------- .PP The calling program should change only the .CR prc_hostid , .CR prc_conn_close , .CR prc_caller_status , and possibly .C prc_conn_time fields, as explained below. The other fields should be considered read-only. .\" ---------- .PP The header file also defines the following macros of interest: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. PRC_OK@/* function succeeded, check entries@*/ PRC_ERR_NETWORKING@/* no networking on calling program's system@*/ PRC_ERR_NOFILE@/* cannot get even one file descriptor@*/ PRC_ERR_RCMD@/* cannot get ``shell'' service num/etc.@*/ PRC_ERR_SELECT@/* select() failed@*/ PRC_CSBIT_ERR@/* connection has errored out@*/ PRC_CONN_NONE@/* needs connection@*/ PRC_CONN1_WAIT@/* waiting for stdio connect()@*/ PRC_CONN2_WAIT@/* waiting for stderr connect()@*/ PRC_CONN3_WAIT@/* waiting for remshd reply@*/ PRC_READ_WAIT@/* waiting for data@*/ PRC_READ_READY@/* data is ready to read@*/ PRC_CONN_DONE@/* connection closed@*/ PRC_CONN_NO_IPS@/* can't get IP addresses@*/ PRC_CONN_FAILED@/* various causes@*/ PRC_CONN_REFUSED@/* by remote system@*/ PRC_CONN_TIMEOUT@/* during connection attempt@*/ .TE .ft P .\" ---------- .PP .C "typedef struct prc_host *prcp_t;" .ifn \f3 .ift \f4 .TS tab(@); l l. #define PRC_NULLP@((prcp_t) 0) #define PRC_SIZE@(sizeof (struct prc_host)) .TE .ft P .br .RE .\" ========== .SS Data Initialization The program calling .C prcmd() should create an array of .C prc_host structures with one node for each target system. It should then call .C prcmd_init() using that array .RI ( hostp ) and its size .RI ( num_hosts ), a desired initial value .RI ( caller_status ) for each host's .C prc_caller_status field, a .I command to be executed when initiating a remote connection to a host, and a .I timeout value to apply to each host during setup of its connection. This call sets the values of most fields for each host. The calling program can change each host's value for .CR prc_caller_status , but normally they are all initialized to the same value. .\" ---------- .PP Finally, initialize the following field in each array element before the first call to .CR prcmd() : .\" ---------- .TP 12 .C prc_hostid Either a system name (with or without domain suffix) or an Internet address in dot notation. This value differs for each host; it's easier for the calling program to set the values directly than to pass a list into .CR prcmd_init() . .\" ---------- .IP This value is a pointer to memory allocated by the calling program. Avoid destroying the underlying data until .C prcmd() establishes a connection to the host. After that, it no longer needs .CR prc_hostid . .\" ---------- .IP Like .CR rcmd() , .C prcmd() does name lookup on host names to get internet addresses; but unlike .CR rcmd() , it does not modify the calling program's .C prc_hostid values. .\" ========== .SS Common Error Handling Each time .C prcmd() is called, it scans the host list looking for actions to take based on each host's .C prc_conn_close field and its .C prc_conn_status field, as described below. Errors are generally handled as follows: .\" ---------- .TP 10 Failure If any system call fails while working on a given host's connection, except as noted below, .C prcmd() sets that host's .C prc_conn_status field to .CR PRC_CONN_FAILED , sets its .C prc_errno to the returned .C errno value from the failed call, and closes all file (socket) descriptors, and stream pointers (if any), that are associated with the host. .\" ---------- .TP Refusal If any failure occurs on the remote .RC ( remshd ) side of a connection, as described below, or if an invalid attempt is made to connect back to a host's standard error port, .C prcmd() sets .C prc_conn_status to .C PRC_CONN_REFUSED and closes the files specified by the host's .C prc_fp and .C prc_fp2 fields. If any message is available from the remote .C remshd (up to a limit of .CR BUFSIZ -1 characters) and .C malloc() succeeds, .C prcmd() saves the message text in a location pointed to by the .C prc_errmsg field; otherwise that field remains a null pointer. If instead the refusal occurs for ``local'' reasons and an .C errno value is available, .C prcmd() sets .C prc_errno to that value, otherwise to 0. .\" ---------- .TP Timeout A connection times out when it is in .CR PRC_CONN1_WAIT , .CR PRC_CONN2_WAIT , or .C PRC_CONN3_WAIT state (see below), .C select() reports that the host is not ready for .SM I/O, and at least .I timeout seconds have elapsed since the host entered that state. The test is low-precision, to the second, using .CR time() . In this case, .C prcmd() sets the .C prc_conn_status field for the host to .CR PRC_CONN_TIMEOUT , and closes the files specified by the host's .C prc_fp and .C prc_fp2 fields. .\" ---------- .PP A host specified by name can be listed with multiple .SM IP addresses in the hosts database. In that case, when a connection to one of that host's .SM IP addresses fails, is refused, or times out before reaching the .C PRC_READ_WAIT state, .C prcmd() attempts to open a new connection on the host's next .SM IP address (up to a limit of five .SM IP addresses per host). A failure is not returned for a given host until all of its .SM IP addresses have been tried. .\" ========== .SS Host/Connection Status See .RB `` "Usage Notes" '' for additional information on how calling programs should handle the following connection status conditions. .\" ---------- .TP 20 .C PRC_CONN_NONE .C prcmd() maps the .C prc_hostid value from a name to one or more .SM IP addresses (if it does not appear to already be an address), maps the .SM IP addresses to binary, gets an Internet socket bound to a reserved port number for communicating with the host, maps the socket descriptor to a stream pointer using .CR fdopen() , and performs a non-blocking .C connect() of the socket descriptor to the remote host's ``shell'' service. The socket's send and receive buffer sizes are the default; the calling program can change the sizes with .C "setsockopt (fileno (hostp \(-> prc_fp))" at any time, subject to the restrictions documented in .IR setsockopt (2). .\" ---------- .IP If .C gethostbyname() (see .IR gethostbyname (3N)) or .C inet_addr() (see .IR inet_addr (3N)) fails, .C prcmd() sets the .C prc_conn_status field to .CR PRC_CONN_NO_IPS . .\" ---------- .IP Information needed for an .C rcmd() connection includes the port number for the ``shell'' service and the user name of the effective user .SM ID as the local and remote user names. .C prcmd() looks up this information the first time it makes a connection. If .C prcmd() cannot obtain this information it returns .C PRC_ERR_RCMD (and tries again each time it's called). .\" ---------- .IP If .C socket() fails with any of the following local-host errors: .CR EHOSTDOWN , .CR EAFNOSUPPORT , .CR ESOCKTNOSUPPORT , .CR EPROTONOSUPPORT , .CR EPROTOTYPE , or .CR EINVAL , .C prcmd() returns .C PRC_ERR_NETWORKING and the status of the host list is unspecified. .\" ---------- .IP If .C socket() fails with .C EMFILE or .CR ENFILE , which means the process or the system is out of file descriptors, or if there are no available reserved ports, the .C prc_conn_status field is left as .C PRC_CONN_NONE for later retries. After checking all host entries, if .C prcmd() has no open files (sockets) for any host, and it didn't close any files during this call, it returns .C PRC_ERR_NOFILE \(em that is, all file descriptors are in use for this process, but none by .CR prcmd() . .\" ---------- .IP If .C connect() succeeds, or if it fails with .CR EINPROGRESS , which is normal for a non-blocking connect request, .C prcmd() sets .C prc_conn_status to .CR PRC_CONN1_WAIT , .C prc_conn_time to the current system clock in seconds, and .C prc_fp to the stream pointer for this socket. This host is then included in the .C select() list per .C PRC_CONN1_WAIT (see below). .\" ---------- .TP .C PRC_CONN1_WAIT .C prcmd() includes this host in the .C select() list for write-readiness. If the connection is not ready for writing, the .C prc_conn_status field is left unchanged. .\" ---------- .IP When the connection is ready for writing, .C prcmd() returns the socket to ``blocking'', starts a connection for standard error back from the remote command, sets .C prc_fp2 to the file pointer for this connection, writes standard remsh connection information (see .IR remshd (1M) and also above) to the remote process with .C SIGPIPE temporarily ignored using .CR sigvector() , changes .C prc_conn_status to .CR PRC_CONN2_WAIT , and sets .C prc_conn_time to the current system clock in seconds. .\" ---------- .IP If a connection is refused, .C prcmd() gets .C ECONNREFUSED or .C EPIPE on attempt to write remsh connection information, and handles the error as previously described in the section called .RB `` "Common Error Handling" ''. .\" ---------- .TP .C PRC_CONN2_WAIT .C prcmd() includes this host in the .C select() list for read-readiness \(em for both .C prc_fp (in case of error) and .C prc_fp2 (in case of successful connection back to the standard error port). When neither connection is ready for reading, the .C prc_conn_status field is left unchanged. .\" ---------- .IP When the standard error connection is ready for reading, .C prcmd() does an .C accept() on it, closes the old .C prc_fp2 and revises the value to a new file pointer for the new socket/fd, changes .C prc_conn_status to .CR PRC_CONN3_WAIT , and sets .C prc_conn_time to the current system clock in seconds. .\" ---------- .IP If only the stdout connection is ready for reading, this indicates a .C remshd failure. .C prcmd() treats this as a refused connection, as described earlier under .RB `` "Common Error Handling" ''. .\" ---------- .PP Note that a host is ``held'' in .C PRC_CONN1_WAIT or .C PRC_CONN2_WAIT status if there are no available file descriptors or reserved ports when one is needed. .\" ---------- .TP 20 .C PRC_CONN3_WAIT .C prcmd() includes this host in the .C select() list for read-readiness. If the connection is not ready for reading, the .C prc_conn_status field is left unchanged. .\" ---------- .IP When the connection is ready for reading, .C prcmd() consumes the null byte on stdout from .CR remshd , sets .C prc_conn_status to .CR PRC_READ_WAIT , and resets .C prc_conn_time to the current system clock in seconds for use by the calling program during the ensuing conversation. If anything other than a null byte arrives, this indicates a .C remshd failure. .C prcmd() treats this as a refused connection, as described previously. .\" ---------- .TP .C PRC_READ_WAIT .C prcmd() includes this host in the .C select() list for read-readiness. When the connection is not ready for reading, the .C prc_conn_status field is left unchanged. Note, the remote command might be waiting for the calling program to write data to it. .\" ---------- .IP When the connection is ready for reading, .C prcmd() sets .C prc_conn_status to .CR PRC_READ_READY . .\" ---------- .TP .C PRC_READ_READY .C prcmd() treats a host in this status the same as .CR PRC_READ_WAIT . If the connection is not ready for reading, .C prcmd() sets .C prc_conn_status back to .CR PRC_READ_WAIT . .\" ---------- .TP .C PRC_CONN_DONE .C prcmd() ignores this host's entry. .\" ---------- .IP .C prcmd() enters this state from any other state when the .C prc_conn_close field (set by the calling program) is non-zero. It closes the files specified by .C prc_fp and .C prc_fp2 (if not already null), sets those fields to null, and resets the .C prc_conn_close field to 0. .\" ---------- .TP .C PRC_CONN_NO_IPS .PD 0 .TP .C PRC_CONN_FAILED .TP .C PRC_CONN_REFUSED .TP .C PRC_CONN_TIMEOUT .PD With any of these failure status values, .C prcmd() ignores this host's entry, except if .C prc_conn_close is set, the entry's .C prc_conn_status field is set to .CR PRC_CONN_DONE . .\" ========== .SS Changes in Host Status After each .C prcmd() call, the .C prc_prev_status field for each host's entry is set to the previous value of its .C prc_conn_status field. The calling program can use .C "(prc_prev_status != prc_conn_status)" to quickly check for a new status for any host. This is useful for once-only logging or display of status values except .C PRC_READ_WAIT and .C PRC_READ_READY \(em each of these states can be entered many times during a conversation. .\" ---------- .PP Note that a host can leave and then re-enter .C PRC_CONN_NONE status if it has multiple .SM IP addresses, a connection to one .SM IP fails, and there are no files or ports available to try the host's next .SM IP address. .\" ---------- .PP The calling program can freely use the .C prc_caller_status field to record additional information about the status of each connection. .\" ========== .SS Usage Notes Once a connection is made, and a host is in one of the .CR PRC_READ_ * states, control of the ``conversation'' between the calling program and remote host belongs to the calling program. Conversations are of two types: .\" ---------- .PP 1. calling program communicates first .br 2. remote command communicates first .\" ---------- .PP If the calling program communicates first, it must use the .C prc_caller_status field, or other means, to remember whether or not it has sent initial data to the command; and it must send that data upon the host entering the .C PRC_READ_WAIT state the first time. If the command communicates first, or in any conversation after the calling program sends initial data, the calling program must ``track'' the conversation to know when to send more data, if any, and when to close the conversation by setting .CR prc_conn_close . .\" ---------- .PP Before the calling program can send the next input, or close the connection, it might have to wait through a series of .C PRC_READ_WAIT and .C PRC_READ_READY states (until all bytes of a single response from a command are received). .\" ---------- .PP After each .C prcmd() call, the calling program should check the return value for a serious error. If the return value is .CR PRC_OK , the calling program should next scan the .I hostp array and check .C prc_prev_status (if desired) and .C prc_conn_status fields for each host. The calling program only needs to take action for certain status values (marked with ``\(bu'' below). .\" ---------- .TP 20 .C PRC_CONN_NONE After the first .C prcmd() call: Indicates the process ran out of socket (file) descriptors, or reserved ports, after making at least one (still open) connection (in this call, or in a previous call). Connection to this host is attempted again on the next call. The calling program can increase the number of available file descriptors (by closing files or calling .CR rlimit() ), or wait for existing connections to finish their communications. .\" ---------- .TP .C PRC_CONN1_WAIT .PD 0 .TP .C PRC_CONN2_WAIT .TP .C PRC_CONN3_WAIT These are internal states of little interest to the calling program. No action is needed except to call .C prcmd() again later. If .CR "(prc_prev_status != prc_conn_status)" , the calling program might log/display the host's new status. .PD .\" ---------- .TP .C "PRC_READ_WAIT \(bu" Command is running but has not yet produced output. If the calling program communicates first, meaning the command needs some initial input, write it to the file specified by .C prc_fp and remember that this was done, probably by using the .C prc_caller_status field. Otherwise no action is required, except maybe to log/display the connection's status. .\" ---------- .TP .C "PRC_READ_READY \(bu" Command produced output that is ready for reading. After reading the output, if the command needs more input, write it now to the file specified by .CR prc_fp . If instead the conversation is done, set the .C prc_conn_close field non-zero. .\" ---------- .TP .C PRC_CONN_DONE Command is done; connection was closed in response to the calling program setting the .C prc_conn_close field. No action is required. .\" ---------- .PP The calling program can use .C "(prc_conn_status & PRC_CSBIT_ERR)" to quickly detect any error status. It can use .C "(prc_prev_status != prc_conn_status)" to detect that any failure condition is new so it is only handled once, or use .C prc_caller_status to record that it was processed the first time it appears in a return from .CR prcmd() . In each case the calling program should handle or report the error as desired. .\" ---------- .TP 20 .C "PRC_CONN_NO_IPS \(bu" The .C prc_hostid field appears to be a name, not an address, and .C gethostbyname() fails for it, or .C inet_addr() fails on a numeric .C prc_hostid value. .\" ---------- .PP The remaining conditions only refer to the cause of failure on the last of the host's .SM IP addresses, if it has more than one. .\" ---------- .TP 20 .C "PRC_CONN_FAILED \(bu" Connection could not be initiated for some reason (on any of the host's .SM IP addresses) due to failure on the local system. .C prc_errno is set to the .C errno value from a failed system call. .\" ---------- .TP .C "PRC_CONN_REFUSED \(bu" Connection refused. Per .IR errno (2): ``This usually results from trying to connect to a service that is inactive on the foreign host.'' It can also be due to any other remote .RC ( remshd ) failure, including access denial; and to an improper connection attempt on the standard error port. .\" ---------- .IP The calling program should check the host's .C prc_errmsg field. If it is not a null pointer, message text is available from the remote .C remshd command; and the calling program must .C free() the pointer when done using the value. .\" ---------- .TP .C "PRC_CONN_TIMEOUT \(bu" Connection timed out. The connection has remained in one of the .CR PRC_CONN1_WAIT , .CR PRC_CONN2_WAIT , or .CR PRC_CONN3_WAIT states for more than .I timeout seconds without becoming ready for .SM I/O. .\" ---------- .PP If the calling program performs unbuffered .SM I/O using socket (file) descriptors instead of streams, it can refer to .C fileno(prc_fp) (see .IR fileno (3S)). .\" ---------- .PP If the calling program needs to send a signal to a remote command, it can write the signal number to the file specified by .C prc_fp2 (see .IR rcmd (3N)). .\" ---------- .PP There is no way to tell .C prcmd() to close down all connections, except by setting .C prc_conn_close for all hosts, and calling .C prcmd() once more. This causes .C prc_conn_status to be set to .CR PRC_CONN_DONE . .\" ========== .SS Regarding Timeouts .C prcmd() is designed to maximize the number of parallel connections, and to maximize control by the calling program. Therefore .C prcmd() always calls .C select() with a timeout value of zero (immediate polling). It is the responsibility of the calling program to avoid calling .C prcmd() more frequently than is necessary (therefore consuming excessive .SM CPU time). For example, the calling program might call .C sleep(1) (see .IR sleep (3C)) between .C prcmd() calls. Note: This is unnecessary if the calling program is itself periodically invoked by timer interrupts, or if it performs other (time-consuming) tasks between .C prcmd() calls. .\" ---------- .PP A timeout will occur if the host's connection remains in one of the wait states, .CR PRC_CONN1_WAIT , .CR PRC_CONN2_WAIT , or .CR PRC_CONN3_WAIT , for more than .I timeout seconds without becoming ready for .SM I/O, and no untried .SM IP addresses for this host remain. When a host's connection reaches .C PRC_READ_WAIT state the first time, .C prcmd() resets the host's .C prc_conn_time field but does not check the host again for timeout. The calling program can do this if desired. The calling program is also permitted to reset (update) the .C prc_conn_time field as the communications proceed (for example, each time it writes data to the remote command). .\" ========== .SH RETURN VALUE .TP 25 .C PRC_OK Call succeeded; check the host list for .C prc_prev_status and .C prc_conn_status field values. If .C select() fails with .C EINTR (due to a signal arriving), .C prcmd() returns control to the calling program with .CR PRC_OK . In this case some connections might have been started (entered the .C PRC_CONN1_WAIT state) or stopped (entered the .C PRC_CONN_DONE state), under the calling program's control, but none has advanced due to .SM I/O status; call .C prcmd() again as usual. .\" ---------- .TP .C PRC_ERR_NETWORKING A .C socket() call failed due to any of a number of serious networking problems (see earlier list), indicating the local host's networking is not enabled, and .C prcmd() is useless; .C errno is set on return from .CR prcmd() . .\" ---------- .TP .C PRC_ERR_NOFILE A .C socket() call failed with .C EMFILE or .CR ENFILE , or there were no more available reserved ports, at a time when .C prcmd() had no open connections (sockets). This means further attempts to open connections are futile until the calling program, or the system, frees some file descriptors, or reserved ports. .\" ---------- .TP .C PRC_ERR_RCMD Unable to get the ``shell'' service port number or the username for the effective user .SM ID. It's not useful to call .C prcmd() again unless this condition is corrected. .\" ---------- .TP .C PRC_ERR_SELECT A .C select() call failed (other than with .CR EINTR ); .C errno is set on return from .CR prcmd() . The data in the host list is valid but no hosts are read-ready or write-ready, even if marked .C PRC_READ_READY from a previous successful call. .\" ========== .SH DIAGNOSTICS Unlike .CR rcmd() , .C prcmd() does not copy messages from .C remshd to the local standard error when .C remshd fails. It just puts the host in .C PRC_CONN_REFUSED state. .\" ========== .SH EXAMPLES The following code fragment illustrates how to allocate and initialize an array of hosts, and call .C prcmd() once for the entire list of hosts: .RS .PP .ifn \f3 .ift \f4 .nf int index; struct prc_host prc_host [MAXHOSTS]; .sp prcmd_init (prc_host, argc, 0, REMCMD, TIMEOUT); .sp for (index = 0; index < argc; ++index) (prc_host[index].prc_hostid) = argv [index]; .sp if ((rc = prcmd (prc_host, argc)) != PRC_OK) ... .ft P .fi .RE .\" ========== .SH WARNINGS .C prcmd() is unsafe in multi-thread applications. .\" ---------- .PP Like .CR rcmd() , .C prcmd() should only be called by a privileged process. Otherwise it puts every host in .C PRC_CONN_FAILED status with .C errno = 13 .RC ( EACCES ) because it cannot .C bind() to any reserved port. .\" ---------- .PP At this time .C select() calls are done on files specified by .C prc_fp only, not .CR prc_fp2 . .C prcmd() assumes that the remote command will never write to standard error and then block, but will instead terminate or otherwise close stdout. When stdout is read-ready, the calling program can safely do a blocking .C read() on .CR prc_fp , and upon .SM EOF or error, check .C prc_fp2 with a blocking .CR read() . .\" ---------- .PP (Exception: For status .C PRC_CONN2_WAIT both files are selected since either might come ready depending on success or failure, as described earlier. However, this exception is handled internal to .C prcmd() and does not affect the calling program.) .\" ---------- .PP Note that .C prcmd_init() saves a pointer to the value of .IR command , not the value itself, so the calling program must preserve the value through all calls of .CR prcmd() . .\" ---------- .PP .C connect() times out after about two minutes, even with non-blocking .SM I/O. If this happens to a host's connection, the result is indistinguishable from .C PRC_CONN_REFUSED since .C write() returns .C EPIPE in either case. This is not a problem if the calling program allows less than two minutes for a connection, that is, sends a .I timeout value less than 120, and calls .C prcmd() frequently enough that the latter catches the timeout itself before .C connect() does. .\" ---------- .PP Be careful when using buffered .SM I/O. Avoid calls to .CR fgets() , .CR fread() , and similar functions in circumstances where they might block indefinitely if less data is available than requested. Also, be sure to read all available data from a host via the file specified by .C prc_fp before waiting again for a connection to be read-ready. The connection might appear not-ready even though buffered, pending data was already read by the stdio library, and is available. Avoiding these problems might require the use of non-blocking .SM I/O; see .IR fcntl (2). .\" ---------- .PP Be careful about writing to a socket that might be closed if the remote command terminates, or if the connection is lost. This can cause the calling process to receive .CR SIGPIPE . The calling program must handle this signal if appropriate. .\" ---------- .PP When handling a host whose connection failed with .CR PRC_CONN_REFUSED , remember to .C free() the host's .C prc_errmsg pointer if it is non-null. This can be skipped if regaining malloc'd memory is not required. .\" ---------- .SS Performance Issues It is faster to call .C prcmd() with host \s-1ID\s0s specified as internet addresses rather than names, because .C prcmd() will not need to look up each host in the hosts database. However, when doing so with hosts that have multiple internet addresses, only the specified internet address is tried. .PP There is a limit of about 512 reserved ports on each system, and a soft limit for the number of available file descriptors for each process. Each specified host requires two reserved ports and two file descriptors for the connection to check its status. .C prcmd() defers (serializes) additional connections once all ports or file descriptors are in use, so additional hosts are not ignored, but the time required for all connections to complete increases accordingly. To improve performance, it might be necessary to increase the limit on open files if there are a lot of hosts; see .IR setrlimit (2). .\" ========== .SH AUTHOR .C prcmd() was developed by Hewlett-Packard. .\" ========== .SH SEE ALSO remshd(1M), accept(2), bind(2), connect(2), errno(2), fcntl(2), read(2), select(2), setsockopt(2), sigvector(2), socket(2), time(2), fdopen(3S), fileno(3S), gethostbyname(3N), inet_addr(3N), malloc(3C), rcmd(3N), sleep(3C). .\" .\" toc@\f3prcmd(3N)\f1:\0\0\f4prcmd()\f1@@@return streams to parallel remote commands .\" .\" index@\f4prcmd\f1 \- return streams to parallel remote commands@@@\f3prcmd(3N)\f1 .\" index@remote commands, return streams to (parallel)@@@\f3prcmd(3N)\f1 .\" .\" links@prcmd.3n prcmd_init.3n .\" $Header: prcmd.3n,v 72.3 94/11/30 10:15:18 ssa Exp $ .TA p .TH prcmd 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" ========== .SH NAME prcmd \- return streams to parallel remote commands .\" ========== .SH SYNOPSIS .C #include .PP .C "void prcmd_init (" .nf .PD 0 .IP .C "struct prc_host *hostp," .C "int num_hosts," .C "int caller_status," .C "char *command," .C "time_t timeout" .PP .C ");" .PD .fi .PP .C "int prcmd (" .nf .PD 0 .IP .C "struct prc_host *hostp," .C "int num_hosts" .PP .C ");" .PD .fi .\" =========== .SS Remarks These functions reside in libdc, and are linked using the .C -ldc option to the .C ld or .C cc command. .\" ========== .SH DESCRIPTION .C prcmd() is an interface similar to .C rcmd() that allows a client-side calling program to use an existing .C rcmd() server side daemon. .CR prcmd() , however, performs in parallel across multiple systems, the time consuming steps associated with executing commands remotely (connection, command invocation, and command execution/interaction). With .CR rcmd() , only command execution and interaction is under the control of the calling program, and it requires the calling program to perform its own .C select() calls in order to manage multiple (parallel) connections. .\" ---------- .PP Features of the existing server-side remote-shell daemon .RC ( remshd ) include: well known service, access control, and shell processing of the command line. .\" ---------- .PP The calling program passes .C prcmd() a pointer .RI ( hostp ) to the first node in a list of hosts for which to initiate, or continue, remote command processing via Internet socket connections. It also supplies the number of hosts in the list .RI ( num_hosts ). .\" ---------- .PP The calling program makes repeated calls to .C prcmd() to advance the status of the host connections. Each call to .C prcmd() causes a single call of .C select() to check the status of all connections that require checking (if there are any). Once a connection (to a remote command) is ready for reading, the calling program can read data from it, optionally write data to it, and then wait for more data to be ready to read back from it. .\" ========== .SS Header File The .C header file defines a .C prc_host structure containing the following fields of interest: .\" ---------- .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. char@*prc_hostid;@/* host name or IP address@*/ int@prc_prev_status;@/* previous connection status@*/ int@prc_conn_status;@/* connection status@*/ time_t@prc_conn_time;@/* time of connection@*/ int@prc_errno;@/* for failed connections@*/ char@*prc_errmsg;@/* string from remshd@*/ FILE@*prc_fp;@/* file ptr to stdin/stdout@*/ FILE@*prc_fp2;@/* file pointer to stderr@*/ int@prc_conn_close;@/* flag: close connection@*/ int@prc_caller_status;@/* caller's info about conn@*/ .TE .ft P .RE .\" ---------- .PP The calling program should change only the .CR prc_hostid , .CR prc_conn_close , .CR prc_caller_status , and possibly .C prc_conn_time fields, as explained below. The other fields should be considered read-only. .\" ---------- .PP The header file also defines the following macros of interest: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. PRC_OK@/* function succeeded, check entries@*/ PRC_ERR_NETWORKING@/* no networking on calling program's system@*/ PRC_ERR_NOFILE@/* cannot get even one file descriptor@*/ PRC_ERR_RCMD@/* cannot get ``shell'' service num/etc.@*/ PRC_ERR_SELECT@/* select() failed@*/ PRC_CSBIT_ERR@/* connection has errored out@*/ PRC_CONN_NONE@/* needs connection@*/ PRC_CONN1_WAIT@/* waiting for stdio connect()@*/ PRC_CONN2_WAIT@/* waiting for stderr connect()@*/ PRC_CONN3_WAIT@/* waiting for remshd reply@*/ PRC_READ_WAIT@/* waiting for data@*/ PRC_READ_READY@/* data is ready to read@*/ PRC_CONN_DONE@/* connection closed@*/ PRC_CONN_NO_IPS@/* can't get IP addresses@*/ PRC_CONN_FAILED@/* various causes@*/ PRC_CONN_REFUSED@/* by remote system@*/ PRC_CONN_TIMEOUT@/* during connection attempt@*/ .TE .ft P .\" ---------- .PP .C "typedef struct prc_host *prcp_t;" .ifn \f3 .ift \f4 .TS tab(@); l l. #define PRC_NULLP@((prcp_t) 0) #define PRC_SIZE@(sizeof (struct prc_host)) .TE .ft P .br .RE .\" ========== .SS Data Initialization The program calling .C prcmd() should create an array of .C prc_host structures with one node for each target system. It should then call .C prcmd_init() using that array .RI ( hostp ) and its size .RI ( num_hosts ), a desired initial value .RI ( caller_status ) for each host's .C prc_caller_status field, a .I command to be executed when initiating a remote connection to a host, and a .I timeout value to apply to each host during setup of its connection. This call sets the values of most fields for each host. The calling program can change each host's value for .CR prc_caller_status , but normally they are all initialized to the same value. .\" ---------- .PP Finally, initialize the following field in each array element before the first call to .CR prcmd() : .\" ---------- .TP 12 .C prc_hostid Either a system name (with or without domain suffix) or an Internet address in dot notation. This value differs for each host; it's easier for the calling program to set the values directly than to pass a list into .CR prcmd_init() . .\" ---------- .IP This value is a pointer to memory allocated by the calling program. Avoid destroying the underlying data until .C prcmd() establishes a connection to the host. After that, it no longer needs .CR prc_hostid . .\" ---------- .IP Like .CR rcmd() , .C prcmd() does name lookup on host names to get internet addresses; but unlike .CR rcmd() , it does not modify the calling program's .C prc_hostid values. .\" ========== .SS Common Error Handling Each time .C prcmd() is called, it scans the host list looking for actions to take based on each host's .C prc_conn_close field and its .C prc_conn_status field, as described below. Errors are generally handled as follows: .\" ---------- .TP 10 Failure If any system call fails while working on a given host's connection, except as noted below, .C prcmd() sets that host's .C prc_conn_status field to .CR PRC_CONN_FAILED , sets its .C prc_errno to the returned .C errno value from the failed call, and closes all file (socket) descriptors, and stream pointers (if any), that are associated with the host. .\" ---------- .TP Refusal If any failure occurs on the remote .RC ( remshd ) side of a connection, as described below, or if an invalid attempt is made to connect back to a host's standard error port, .C prcmd() sets .C prc_conn_status to .C PRC_CONN_REFUSED and closes the files specified by the host's .C prc_fp and .C prc_fp2 fields. If any message is available from the remote .C remshd (up to a limit of .CR BUFSIZ -1 characters) and .C malloc() succeeds, .C prcmd() saves the message text in a location pointed to by the .C prc_errmsg field; otherwise that field remains a null pointer. If instead the refusal occurs for ``local'' reasons and an .C errno value is available, .C prcmd() sets .C prc_errno to that value, otherwise to 0. .\" ---------- .TP Timeout A connection times out when it is in .CR PRC_CONN1_WAIT , .CR PRC_CONN2_WAIT , or .C PRC_CONN3_WAIT state (see below), .C select() reports that the host is not ready for .SM I/O, and at least .I timeout seconds have elapsed since the host entered that state. The test is low-precision, to the second, using .CR time() . In this case, .C prcmd() sets the .C prc_conn_status field for the host to .CR PRC_CONN_TIMEOUT , and closes the files specified by the host's .C prc_fp and .C prc_fp2 fields. .\" ---------- .PP A host specified by name can be listed with multiple .SM IP addresses in the hosts database. In that case, when a connection to one of that host's .SM IP addresses fails, is refused, or times out before reaching the .C PRC_READ_WAIT state, .C prcmd() attempts to open a new connection on the host's next .SM IP address (up to a limit of five .SM IP addresses per host). A failure is not returned for a given host until all of its .SM IP addresses have been tried. .\" ========== .SS Host/Connection Status See .RB `` "Usage Notes" '' for additional information on how calling programs should handle the following connection status conditions. .\" ---------- .TP 20 .C PRC_CONN_NONE .C prcmd() maps the .C prc_hostid value from a name to one or more .SM IP addresses (if it does not appear to already be an address), maps the .SM IP addresses to binary, gets an Internet socket bound to a reserved port number for communicating with the host, maps the socket descriptor to a stream pointer using .CR fdopen() , and performs a non-blocking .C connect() of the socket descriptor to the remote host's ``shell'' service. The socket's send and receive buffer sizes are the default; the calling program can change the sizes with .C "setsockopt (fileno (hostp \(-> prc_fp))" at any time, subject to the restrictions documented in .IR setsockopt (2). .\" ---------- .IP If .C gethostbyname() (see .IR gethostbyname (3N)) or .C inet_addr() (see .IR inet_addr (3N)) fails, .C prcmd() sets the .C prc_conn_status field to .CR PRC_CONN_NO_IPS . .\" ---------- .IP Information needed for an .C rcmd() connection includes the port number for the ``shell'' service and the user name of the effective user .SM ID as the local and remote user names. .C prcmd() looks up this information the first time it makes a connection. If .C prcmd() cannot obtain this information it returns .C PRC_ERR_RCMD (and tries again each time it's called). .\" ---------- .IP If .C socket() fails with any of the following local-host errors: .CR EHOSTDOWN , .CR EAFNOSUPPORT , .CR ESOCKTNOSUPPORT , .CR EPROTONOSUPPORT , .CR EPROTOTYPE , or .CR EINVAL , .C prcmd() returns .C PRC_ERR_NETWORKING and the status of the host list is unspecified. .\" ---------- .IP If .C socket() fails with .C EMFILE or .CR ENFILE , which means the process or the system is out of file descriptors, or if there are no available reserved ports, the .C prc_conn_status field is left as .C PRC_CONN_NONE for later retries. After checking all host entries, if .C prcmd() has no open files (sockets) for any host, and it didn't close any files during this call, it returns .C PRC_ERR_NOFILE \(em that is, all file descriptors are in use for this process, but none by .CR prcmd() . .\" ---------- .IP If .C connect() succeeds, or if it fails with .CR EINPROGRESS , which is normal for a non-blocking connect request, .C prcmd() sets .C prc_conn_status to .CR PRC_CONN1_WAIT , .C prc_conn_time to the current system clock in seconds, and .C prc_fp to the stream pointer for this socket. This host is then included in the .C select() list per .C PRC_CONN1_WAIT (see below). .\" ---------- .TP .C PRC_CONN1_WAIT .C prcmd() includes this host in the .C select() list for write-readiness. If the connection is not ready for writing, the .C prc_conn_status field is left unchanged. .\" ---------- .IP When the connection is ready for writing, .C prcmd() returns the socket to ``blocking'', starts a connection for standard error back from the remote command, sets .C prc_fp2 to the file pointer for this connection, writes standard remsh connection information (see .IR remshd (1M) and also above) to the remote process with .C SIGPIPE temporarily ignored using .CR sigvector() , changes .C prc_conn_status to .CR PRC_CONN2_WAIT , and sets .C prc_conn_time to the current system clock in seconds. .\" ---------- .IP If a connection is refused, .C prcmd() gets .C ECONNREFUSED or .C EPIPE on attempt to write remsh connection information, and handles the error as previously described in the section called .RB `` "Common Error Handling" ''. .\" ---------- .TP .C PRC_CONN2_WAIT .C prcmd() includes this host in the .C select() list for read-readiness \(em for both .C prc_fp (in case of error) and .C prc_fp2 (in case of successful connection back to the standard error port). When neither connection is ready for reading, the .C prc_conn_status field is left unchanged. .\" ---------- .IP When the standard error connection is ready for reading, .C prcmd() does an .C accept() on it, closes the old .C prc_fp2 and revises the value to a new file pointer for the new socket/fd, changes .C prc_conn_status to .CR PRC_CONN3_WAIT , and sets .C prc_conn_time to the current system clock in seconds. .\" ---------- .IP If only the stdout connection is ready for reading, this indicates a .C remshd failure. .C prcmd() treats this as a refused connection, as described earlier under .RB `` "Common Error Handling" ''. .\" ---------- .PP Note that a host is ``held'' in .C PRC_CONN1_WAIT or .C PRC_CONN2_WAIT status if there are no available file descriptors or reserved ports when one is needed. .\" ---------- .TP 20 .C PRC_CONN3_WAIT .C prcmd() includes this host in the .C select() list for read-readiness. If the connection is not ready for reading, the .C prc_conn_status field is left unchanged. .\" ---------- .IP When the connection is ready for reading, .C prcmd() consumes the null byte on stdout from .CR remshd , sets .C prc_conn_status to .CR PRC_READ_WAIT , and resets .C prc_conn_time to the current system clock in seconds for use by the calling program during the ensuing conversation. If anything other than a null byte arrives, this indicates a .C remshd failure. .C prcmd() treats this as a refused connection, as described previously. .\" ---------- .TP .C PRC_READ_WAIT .C prcmd() includes this host in the .C select() list for read-readiness. When the connection is not ready for reading, the .C prc_conn_status field is left unchanged. Note, the remote command might be waiting for the calling program to write data to it. .\" ---------- .IP When the connection is ready for reading, .C prcmd() sets .C prc_conn_status to .CR PRC_READ_READY . .\" ---------- .TP .C PRC_READ_READY .C prcmd() treats a host in this status the same as .CR PRC_READ_WAIT . If the connection is not ready for reading, .C prcmd() sets .C prc_conn_status back to .CR PRC_READ_WAIT . .\" ---------- .TP .C PRC_CONN_DONE .C prcmd() ignores this host's entry. .\" ---------- .IP .C prcmd() enters this state from any other state when the .C prc_conn_close field (set by the calling program) is non-zero. It closes the files specified by .C prc_fp and .C prc_fp2 (if not already null), sets those fields to null, and resets the .C prc_conn_close field to 0. .\" ---------- .TP .C PRC_CONN_NO_IPS .PD 0 .TP .C PRC_CONN_FAILED .TP .C PRC_CONN_REFUSED .TP .C PRC_CONN_TIMEOUT .PD With any of these failure status values, .C prcmd() ignores this host's entry, except if .C prc_conn_close is set, the entry's .C prc_conn_status field is set to .CR PRC_CONN_DONE . .\" ========== .SS Changes in Host Status After each .C prcmd() call, the .C prc_prev_status field for each host's entry is set to the previous value of its .C prc_conn_status field. The calling program can use .C "(prc_prev_status != prc_conn_status)" to quickly check for a new status for any host. This is useful for once-only logging or display of status values except .C PRC_READ_WAIT and .C PRC_READ_READY \(em each of these states can be entered many times during a conversation. .\" ---------- .PP Note that a host can leave and then re-enter .C PRC_CONN_NONE status if it has multiple .SM IP addresses, a connection to one .SM IP fails, and there are no files or ports available to try the host's next .SM IP address. .\" ---------- .PP The calling program can freely use the .C prc_caller_status field to record additional information about the status of each connection. .\" ========== .SS Usage Notes Once a connection is made, and a host is in one of the .CR PRC_READ_ * states, control of the ``conversation'' between the calling program and remote host belongs to the calling program. Conversations are of two types: .\" ---------- .PP 1. calling program communicates first .br 2. remote command communicates first .\" ---------- .PP If the calling program communicates first, it must use the .C prc_caller_status field, or other means, to remember whether or not it has sent initial data to the command; and it must send that data upon the host entering the .C PRC_READ_WAIT state the first time. If the command communicates first, or in any conversation after the calling program sends initial data, the calling program must ``track'' the conversation to know when to send more data, if any, and when to close the conversation by setting .CR prc_conn_close . .\" ---------- .PP Before the calling program can send the next input, or close the connection, it might have to wait through a series of .C PRC_READ_WAIT and .C PRC_READ_READY states (until all bytes of a single response from a command are received). .\" ---------- .PP After each .C prcmd() call, the calling program should check the return value for a serious error. If the return value is .CR PRC_OK , the calling program should next scan the .I hostp array and check .C prc_prev_status (if desired) and .C prc_conn_status fields for each host. The calling program only needs to take action for certain status values (marked with ``\(bu'' below). .\" ---------- .TP 20 .C PRC_CONN_NONE After the first .C prcmd() call: Indicates the process ran out of socket (file) descriptors, or reserved ports, after making at least one (still open) connection (in this call, or in a previous call). Connection to this host is attempted again on the next call. The calling program can increase the number of available file descriptors (by closing files or calling .CR rlimit() ), or wait for existing connections to finish their communications. .\" ---------- .TP .C PRC_CONN1_WAIT .PD 0 .TP .C PRC_CONN2_WAIT .TP .C PRC_CONN3_WAIT These are internal states of little interest to the calling program. No action is needed except to call .C prcmd() again later. If .CR "(prc_prev_status != prc_conn_status)" , the calling program might log/display the host's new status. .PD .\" ---------- .TP .C "PRC_READ_WAIT \(bu" Command is running but has not yet produced output. If the calling program communicates first, meaning the command needs some initial input, write it to the file specified by .C prc_fp and remember that this was done, probably by using the .C prc_caller_status field. Otherwise no action is required, except maybe to log/display the connection's status. .\" ---------- .TP .C "PRC_READ_READY \(bu" Command produced output that is ready for reading. After reading the output, if the command needs more input, write it now to the file specified by .CR prc_fp . If instead the conversation is done, set the .C prc_conn_close field non-zero. .\" ---------- .TP .C PRC_CONN_DONE Command is done; connection was closed in response to the calling program setting the .C prc_conn_close field. No action is required. .\" ---------- .PP The calling program can use .C "(prc_conn_status & PRC_CSBIT_ERR)" to quickly detect any error status. It can use .C "(prc_prev_status != prc_conn_status)" to detect that any failure condition is new so it is only handled once, or use .C prc_caller_status to record that it was processed the first time it appears in a return from .CR prcmd() . In each case the calling program should handle or report the error as desired. .\" ---------- .TP 20 .C "PRC_CONN_NO_IPS \(bu" The .C prc_hostid field appears to be a name, not an address, and .C gethostbyname() fails for it, or .C inet_addr() fails on a numeric .C prc_hostid value. .\" ---------- .PP The remaining conditions only refer to the cause of failure on the last of the host's .SM IP addresses, if it has more than one. .\" ---------- .TP 20 .C "PRC_CONN_FAILED \(bu" Connection could not be initiated for some reason (on any of the host's .SM IP addresses) due to failure on the local system. .C prc_errno is set to the .C errno value from a failed system call. .\" ---------- .TP .C "PRC_CONN_REFUSED \(bu" Connection refused. Per .IR errno (2): ``This usually results from trying to connect to a service that is inactive on the foreign host.'' It can also be due to any other remote .RC ( remshd ) failure, including access denial; and to an improper connection attempt on the standard error port. .\" ---------- .IP The calling program should check the host's .C prc_errmsg field. If it is not a null pointer, message text is available from the remote .C remshd command; and the calling program must .C free() the pointer when done using the value. .\" ---------- .TP .C "PRC_CONN_TIMEOUT \(bu" Connection timed out. The connection has remained in one of the .CR PRC_CONN1_WAIT , .CR PRC_CONN2_WAIT , or .CR PRC_CONN3_WAIT states for more than .I timeout seconds without becoming ready for .SM I/O. .\" ---------- .PP If the calling program performs unbuffered .SM I/O using socket (file) descriptors instead of streams, it can refer to .C fileno(prc_fp) (see .IR fileno (3S)). .\" ---------- .PP If the calling program needs to send a signal to a remote command, it can write the signal number to the file specified by .C prc_fp2 (see .IR rcmd (3N)). .\" ---------- .PP There is no way to tell .C prcmd() to close down all connections, except by setting .C prc_conn_close for all hosts, and calling .C prcmd() once more. This causes .C prc_conn_status to be set to .CR PRC_CONN_DONE . .\" ========== .SS Regarding Timeouts .C prcmd() is designed to maximize the number of parallel connections, and to maximize control by the calling program. Therefore .C prcmd() always calls .C select() with a timeout value of zero (immediate polling). It is the responsibility of the calling program to avoid calling .C prcmd() more frequently than is necessary (therefore consuming excessive .SM CPU time). For example, the calling program might call .C sleep(1) (see .IR sleep (3C)) between .C prcmd() calls. Note: This is unnecessary if the calling program is itself periodically invoked by timer interrupts, or if it performs other (time-consuming) tasks between .C prcmd() calls. .\" ---------- .PP A timeout will occur if the host's connection remains in one of the wait states, .CR PRC_CONN1_WAIT , .CR PRC_CONN2_WAIT , or .CR PRC_CONN3_WAIT , for more than .I timeout seconds without becoming ready for .SM I/O, and no untried .SM IP addresses for this host remain. When a host's connection reaches .C PRC_READ_WAIT state the first time, .C prcmd() resets the host's .C prc_conn_time field but does not check the host again for timeout. The calling program can do this if desired. The calling program is also permitted to reset (update) the .C prc_conn_time field as the communications proceed (for example, each time it writes data to the remote command). .\" ========== .SH RETURN VALUE .TP 25 .C PRC_OK Call succeeded; check the host list for .C prc_prev_status and .C prc_conn_status field values. If .C select() fails with .C EINTR (due to a signal arriving), .C prcmd() returns control to the calling program with .CR PRC_OK . In this case some connections might have been started (entered the .C PRC_CONN1_WAIT state) or stopped (entered the .C PRC_CONN_DONE state), under the calling program's control, but none has advanced due to .SM I/O status; call .C prcmd() again as usual. .\" ---------- .TP .C PRC_ERR_NETWORKING A .C socket() call failed due to any of a number of serious networking problems (see earlier list), indicating the local host's networking is not enabled, and .C prcmd() is useless; .C errno is set on return from .CR prcmd() . .\" ---------- .TP .C PRC_ERR_NOFILE A .C socket() call failed with .C EMFILE or .CR ENFILE , or there were no more available reserved ports, at a time when .C prcmd() had no open connections (sockets). This means further attempts to open connections are futile until the calling program, or the system, frees some file descriptors, or reserved ports. .\" ---------- .TP .C PRC_ERR_RCMD Unable to get the ``shell'' service port number or the username for the effective user .SM ID. It's not useful to call .C prcmd() again unless this condition is corrected. .\" ---------- .TP .C PRC_ERR_SELECT A .C select() call failed (other than with .CR EINTR ); .C errno is set on return from .CR prcmd() . The data in the host list is valid but no hosts are read-ready or write-ready, even if marked .C PRC_READ_READY from a previous successful call. .\" ========== .SH DIAGNOSTICS Unlike .CR rcmd() , .C prcmd() does not copy messages from .C remshd to the local standard error when .C remshd fails. It just puts the host in .C PRC_CONN_REFUSED state. .\" ========== .SH EXAMPLES The following code fragment illustrates how to allocate and initialize an array of hosts, and call .C prcmd() once for the entire list of hosts: .RS .PP .ifn \f3 .ift \f4 .nf int index; struct prc_host prc_host [MAXHOSTS]; .sp prcmd_init (prc_host, argc, 0, REMCMD, TIMEOUT); .sp for (index = 0; index < argc; ++index) (prc_host[index].prc_hostid) = argv [index]; .sp if ((rc = prcmd (prc_host, argc)) != PRC_OK) ... .ft P .fi .RE .\" ========== .SH WARNINGS .C prcmd() is unsafe in multi-thread applications. .\" ---------- .PP Like .CR rcmd() , .C prcmd() should only be called by a privileged process. Otherwise it puts every host in .C PRC_CONN_FAILED status with .C errno = 13 .RC ( EACCES ) because it cannot .C bind() to any reserved port. .\" ---------- .PP At this time .C select() calls are done on files specified by .C prc_fp only, not .CR prc_fp2 . .C prcmd() assumes that the remote command will never write to standard error and then block, but will instead terminate or otherwise close stdout. When stdout is read-ready, the calling program can safely do a blocking .C read() on .CR prc_fp , and upon .SM EOF or error, check .C prc_fp2 with a blocking .CR read() . .\" ---------- .PP (Exception: For status .C PRC_CONN2_WAIT both files are selected since either might come ready depending on success or failure, as described earlier. However, this exception is handled internal to .C prcmd() and does not affect the calling program.) .\" ---------- .PP Note that .C prcmd_init() saves a pointer to the value of .IR command , not the value itself, so the calling program must preserve the value through all calls of .CR prcmd() . .\" ---------- .PP .C connect() times out after about two minutes, even with non-blocking .SM I/O. If this happens to a host's connection, the result is indistinguishable from .C PRC_CONN_REFUSED since .C write() returns .C EPIPE in either case. This is not a problem if the calling program allows less than two minutes for a connection, that is, sends a .I timeout value less than 120, and calls .C prcmd() frequently enough that the latter catches the timeout itself before .C connect() does. .\" ---------- .PP Be careful when using buffered .SM I/O. Avoid calls to .CR fgets() , .CR fread() , and similar functions in circumstances where they might block indefinitely if less data is available than requested. Also, be sure to read all available data from a host via the file specified by .C prc_fp before waiting again for a connection to be read-ready. The connection might appear not-ready even though buffered, pending data was already read by the stdio library, and is available. Avoiding these problems might require the use of non-blocking .SM I/O; see .IR fcntl (2). .\" ---------- .PP Be careful about writing to a socket that might be closed if the remote command terminates, or if the connection is lost. This can cause the calling process to receive .CR SIGPIPE . The calling program must handle this signal if appropriate. .\" ---------- .PP When handling a host whose connection failed with .CR PRC_CONN_REFUSED , remember to .C free() the host's .C prc_errmsg pointer if it is non-null. This can be skipped if regaining malloc'd memory is not required. .\" ---------- .SS Performance Issues It is faster to call .C prcmd() with host \s-1ID\s0s specified as internet addresses rather than names, because .C prcmd() will not need to look up each host in the hosts database. However, when doing so with hosts that have multiple internet addresses, only the specified internet address is tried. .PP There is a limit of about 512 reserved ports on each system, and a soft limit for the number of available file descriptors for each process. Each specified host requires two reserved ports and two file descriptors for the connection to check its status. .C prcmd() defers (serializes) additional connections once all ports or file descriptors are in use, so additional hosts are not ignored, but the time required for all connections to complete increases accordingly. To improve performance, it might be necessary to increase the limit on open files if there are a lot of hosts; see .IR setrlimit (2). .\" ========== .SH AUTHOR .C prcmd() was developed by Hewlett-Packard. .\" ========== .SH SEE ALSO remshd(1M), accept(2), bind(2), connect(2), errno(2), fcntl(2), read(2), select(2), setsockopt(2), sigvector(2), socket(2), time(2), fdopen(3S), fileno(3S), gethostbyname(3N), inet_addr(3N), malloc(3C), rcmd(3N), sleep(3C). .\" .\" toc@\f3prcmd(3N)\f1:\0\0\f4prcmd()\f1@@@return streams to parallel remote commands .\" .\" index@\f4prcmd\f1 \- return streams to parallel remote commands@@@\f3prcmd(3N)\f1 .\" index@remote commands, return streams to (parallel)@@@\f3prcmd(3N)\f1 .\" .\" links@prcmd.3n prcmd_init.3n .\" $Header: newpad.3x,v 76.2 95/08/01 14:27:39 ssa Exp $ .TA n .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH newpad 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 newpad .SH NAME newpad, pnoutrefresh, prefresh \(em pad management functions .SH SYNOPSIS .C "#include " .P .C "WINDOW *newpad(int \f2nlines\fP, int \f2ncols\fP);" .P .C "int pnoutrefresh(WINDOW *\f2pad\fP, int \f2pminrow\fP, int \f2pmincol\fP, int \f2sminrow\fP," .br .C " int \f2smincol\fP, int \f2smaxrow\fP, int \f2smaxcol\fP);" .P .C "int prefresh(WINDOW *\f2pad\fP, int \f2pminrow\fP, int \f2pmincol\fP, int \f2sminrow\fP," .br .C " int \f2smincol\fP, int \f2smaxrow\fP, int \f2smaxcol\fP);" .SH DESCRIPTION The .Fn newpad function creates a specialised .CR WINDOW data structure representing a pad with \f2nlines\f1 lines and \f2ncols\f1 columns. A pad is like a window, except that it is not necessarily associated with a viewable part of the screen. Automatic refreshes of pads do not occur. .P The .Fn prefresh and .Fn pnoutrefresh functions are analogous to .Fn wrefresh and .Fn wnoutrefresh except that they relate to pads instead of windows. The additional arguments indicate what part of the pad and screen are involved. The \f2pminrow\f1 and \f2pmincol\f1 arguments specify the origin of the rectangle to be displayed in the pad. The \f2sminrow\f1, \f2smincol\f1, \f2smaxrow\f1 and \f2smaxcol\f1 arguments specify the edges of the rectangle to be displayed on the screen. The lower right-hand corner of the rectangle to be displayed in the pad is calculated from the screen coordinates, since the rectangles must be the same size. Both rectangles must be entirely contained within their respective structures. Negative values of \f2pminrow\f1, \f2pmincol\f1, \f2sminrow\f1 or \f2smincol\f1 are treated as if they were zero. .SH "RETURN VALUE" Upon successful completion, the .Fn newpad function returns a pointer to the pad data structure. Otherwise, it returns a null pointer. .P Upon successful completion, .Fn pnoutrefresh and .Fn prefresh return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" To refresh a pad, call .Fn prefresh or .CR pnoutrefresh() , not .CR wrefresh() . When porting code to use pads from WINDOWS, remember that these functions require additional arguments to specify the part of the pad to be displayed and the location on the screen to be used for the display. .P Although a subwindow and its parent pad may share memory representing characters in the pad, they need not share status information about what has changed in the pad. Therefore, after modifying a subwindow within a pad, it may be necessary to call .Fn touchwin or .Fn touchline on the pad before calling .CR prefresh() . .SH "SEE ALSO" derwin(), doupdate(), is_linetouched(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn pnoutrefresh and .Fn prefresh functions are merged with this entry. In previous issues, they appeared in the entry for .CR prefresh() . .\" .\" toc@\f3newpad(3X)\f1:\0\0\f4newpad()\f1, \f4pnoutrefresh()\f1, \f4prefresh()\f1@@@pad management functions .\" toc@\f4pnoutrefresh()\f1: pad management functions@@@see \f3newpad(3X)\f1 .\" toc@\f4prefresh()\f1: pad management functions@@@see \f3newpad(3X)\f1 .\" .\" index@\f4newpad()\f1 \- pad management functions@@@\f3newpad(3X)\f1 .\" index@\f4pnoutrefresh()\f1 \- pad management functions@@@\f3newpad(3X)\f1 .\" index@\f4prefresh()\f1 \- pad management functions@@@\f3newpad(3X)\f1 .\" index@\f1pad management functions@@@\f3newpad(3X)\f1 .\" index@\f1management functions, for pad@@@\f3newpad(3X)\f1 .\" index@\f1functions, for pad management@@@\f3newpad(3X)\f1 .\" .\" links@newpad.3x pnoutrefresh.3x .\" links@newpad.3x prefresh.3x .\" .\" fileset_database@newpad.3x CURS-ENG-A-MAN .\" $Header: printf.3s,v 72.8 94/11/30 15:46:16 ssa Exp $ .TA p .TH printf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME printf(), fprintf(), sprintf() \- print formatted output .SH SYNOPSIS .C "#include " .PP .C "int printf(const char *format, /* [arg,] */ ...);" .PP .C "int fprintf(FILE *stream, const char *format, /* [arg,] */ ...);" .PP .C "int sprintf(char *s, const char *format, /* [arg,] */ ...);" .SH DESCRIPTION .CR printf() places output on the standard output stream .IR stdout . .PP .CR fprintf() places output on the named output .IR stream . .PP .CR sprintf() places ``output'', followed by the null character .RC ( \e0 ), in consecutive bytes starting at .CI * s \f1. It is the user's responsibility to ensure that enough storage is available. .PP Each function converts, formats, and prints its .IR arg s under control of the .IR format . .I format is a character string containing two types of objects: plain characters that are copied to the output stream, and conversion specifications, each of which results in fetching zero or more .IR arg s. The results are undefined if there are insufficient .IR arg s for the format. If the format is exhausted while .IR arg s remain, excess .IR arg s are ignored. .PP Each conversion specification is introduced by the character .CR % or .CI % n $\f1, where .I n is a decimal integer in the range 1 through .C {NL_ARGMAX} .RC ( NL_ARGMAX is defined in .CR ). The .CI % n $ construction indicates that this conversion should be applied to the .IR n th argument, rather than to the next unused one. .PP An argument can be referenced by a .CI % n $ specification more than once. The two forms of introducing a conversion specification, .CR % and .CI % n $\f1, cannot be mixed within a single .I format string. When numbered argument specifications are used, specifying the Nth argument requires that all the leading arguments, from the first to the (N-1)th, are specified in the format string. Improper use of .CI % n $ in a format string results in a negative return value. .PP After the .CR % or .CI % n $\f1, the following appear in sequence: .RS .TP 5 1. Zero or more .IR flags , which modify the meaning of the conversion specification. .TP 2. An optional string of decimal digits to specify a minimum .I field width in bytes. If the converted value has fewer characters than the field width, it is be padded on the left (or right, if the left-adjustment flag .RC ( - ), described below, has been given) to the field width. If the field width is preceded by a zero, the string is right adjusted with zero-padding on the left (see the leading-zero flag, .CR 0 , described below). .TP 3. A .I precision that gives the minimum number of digits to appear for the .CR d , .CR i , .CR o , .CR u , .CR x , or .CR X conversions, the number of digits to appear after the radix character for the .CR e and .CR f conversions, the maximum number of significant digits for the .CR g conversion, or the maximum number of bytes to be printed from a string in the .CR s conversion. The .I precision takes the form of a period followed by a decimal digit string; a null digit string is treated as zero. .TP 4. An optional .CR l (the letter ``ell''), specifying that a following .CR d , .CR i , .CR o , .CR u , .CR x , or .CR X conversion character applies to a long integer .IR arg ; an optional .CR l specifying that a following .CR n conversion character applies to a pointer to a long integer .IR arg ; an optional .CR h , specifying that a following .CR d , .CR i , .CR o , .CR u , .CR x , or .CR X conversion character applies to a short integer .IR arg ; an optional .CR ll , specifying that a following .CR d , .CR i , .CR o , .CR u , .CR x , or .CR X conversion character applies to a long long integer arg; an optional .CR h specifying that a following .CR n conversion character applies to a pointer to a short integer .IR arg ; an optional .C L specifying that a following .CR e , .CR E , .CR f , .CR g , or .CR G conversion character applies to a long double .IR arg . An .CR l , .CR h , .CR ll or .CR L before any other conversion character is ignored. .TP 5. A conversion character that indicates the type of conversion to be applied. .RE .ift .ne 10 .PP A field width or precision can be indicated by an asterisk instead of a digit string. In this case, an integer .I arg supplies the field width or precision. The .I arg that is actually converted is not fetched until the conversion letter is seen, so the .IR arg s specifying field width, or precision, or both must appear in that order before the .IR arg , if any, to be converted. A negative field width is taken as a .CR - flag followed by a positive field width. A negative precision is taken as if the precision were omitted. Format strings containing .CI % n $ conversion specifications can also indicate a field width or precision by the sequence .CI * n $\f1. The .I n indicates the position of an integer .I arg . With the .CI * n $ sequence, the .IR arg s specifying field width or precision can appear before or after the .I arg to be converted. .PP The flag characters and their meanings are: .RS .TP 10 .C ' The integer portion of the result of a decimal conversion (%i, %d, %u, %f, %g, or %G) will be formatted with thousands' grouping characters. For other conversions the behavior is undefined. The nonmonetary grouping character is used. .TP .C - The resulting conversion is left-justified within the field. .TP .C + The resulting signed conversion always begins with a sign .RC ( + or .CR - ). .TP blank If the first character of a signed conversion is not a sign, a blank is prefixed to the result. This implies that if the blank and .CR + flags both appear, the blank flag is ignored. .TP .C # This flag specifies that the value is converted to an .IR `` alternate form ''. For .CR c , .CR d , .CR i , .CR s , .CR n , and .CR u conversions, the flag has no effect. For .CR o conversion, it increases the precision to force the first digit of the result to be a zero. For .CR x or .CR X conversion, a nonzero result is prefixed by .CR 0x or .CR 0X . For a .CR p conversion, a nonzero result is prefixed by .CR 0x . For .CR e , .CR E , .CR f , .CR g , and .CR G conversions, the result always contains a radix character, even if no digits follow the radix. (Normally, a radix character appears in the resulting conversions only if followed by a digit). For .CR g and .CR G conversions, trailing zeros are .I not removed from the result (which they normally are). .TP .C 0 Leading zeros (following any indication of sign or base) are used to pad to the field width for all conversion characters. No space padding is performed. If both the .CR 0 and .CR - appear, the .CR 0 flag is ignored. For .CR d , .CR i , .CR o , .CR u , .CR p , .CR x , and .CR X , conversions, if a precision is specified, the .CR 0 flag is ignored. .RE .PP The conversion characters and their meanings are: .RS .TP 15 .ift \f4\s+1d\fP\s0,\f4\s+1i\fP\s0,\f4\s+1o\fP\s0,\f4\s+1u\fP\s0,\f4\s+1x\fP\s0,\f4\s+1X\fP\s0 .ifn \f3d\fP,\f3i\fP,\f3o\fP,\f3u\fP,\f3x\fP,\f3X\fP The integer .I arg is converted to signed decimal .RC ( d and .CR i are identical), unsigned octal .RC ( o ), decimal .RC ( u ), or hexadecimal notation .RC ( x and .CR X ), respectively; the letters .CR abcdef are used for .CR x conversion and the letters .CR ABCDEF for .CR X conversion. The precision specifies the minimum number of digits to appear. If the value being converted can be represented in fewer digits, it is expanded with leading zeros. (For compatibility with older versions, padding with leading zeros can alternatively be specified by inserting a zero in front of the field width. This does not imply an octal value for the field width). The default precision is 1. The result of converting a zero value with a precision of zero is a null string. .TP .C f The double .I arg is converted to decimal notation in the style .RC [ - ]\c .CI ddd r ddd , where .I r is the radix character. The number of digits after the radix character is equal to the precision specification. If the precision is missing, six digits are output. If the precision is explicitly zero, no radix character appears. .TP .CR e , E The double .I arg is converted in the style .RC [ - ]\c .CI d r ddde\(+-ddd , where .CR r is the radix character. There is one digit before the radix character and the number of digits after it is equal to the precision; when the precision is missing, six digits are produced; if the precision is zero, no radix character appears. The .CR E format code produces a number with .CR E instead of .CR e introducing the exponent. The exponent always contains at least two digits. .TP .CR g , G The double .I arg is printed in style .CR f or .CR e (or in style .CR E in the case of a .CR G format code), with the precision specifying the number of significant digits. The style used depends on the value converted: style .CR e is used only if the exponent resulting from the conversion is less than .CR \-4 or greater than or equal to the precision. Trailing zeros are removed from the fractional part of the result; a radix character appears only if it is followed by a digit. .TP .C c The integer .I arg is converted to an unsigned char, and the resulting character is printed. .TP .C C The .CR wchar_t .I arg is converted to an array of bytes representing the single wide character according to the setting of .CR LC_CTYPE . Resulting bytes are printed. If the precision is given, it is ignored. If the field width would otherwise cause the wide character to be split, the wide character is printed and the field width is adjusted upward. .TP .C s The .I arg is taken to be a string (character pointer) and characters from the string are printed until a null character .RC ( \e0 ) is encountered or the number of bytes indicated by the precision specification is reached. If the precision is missing, it is taken to be infinite, so all characters up to the first null character are printed. A NULL value for .I arg yields undefined results. .TP .C S The .I arg is taken to be a pointer to a wide character string .RC ( "wchar_t *" ). Wide characters from the string are converted to an array of bytes representing the string of wide characters according to the setting of .CR LC_CTYPE . Resulting bytes are printed until a null wide character .RC ( (wchar_t)0 ) is encountered or the number of bytes indicated by the precision is reached. If the precision is missing, it is taken to be infinite, so all wide characters up to the first null wide character are printed. If the field width would otherwise cause the last multibyte character to be split, the last wide character is not printed. A NULL value for .I arg yields undefined results. .TP .C p The value of a pointer to void .I arg is printed as a sequence of unsigned hexadecimal numbers. The precision specifies the minimum number of digits to appear. If the value being converted can be represented in fewer digits, it is expanded with leading zeros. The default precision is 1. The result of converting a zero value with a precision of zero is a null string. .TP .C n A pointer to an integer .I arg is expected. This pointer is used to store the number of bytes printed on the output stream so far by this call to the function. No argument is converted. .TP .C % Print a .CR % ; no argument is converted. .RE .PP In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result. .PP Characters generated by .CR printf() , and .CR fprintf() are printed as if .CR putc() had been called (see .IR putc (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category affects the following features: .RS .TP 3 \(bu Plain characters within format strings are interpreted as single byte and/or multibyte characters. .TP \(bu Field width is given in terms of bytes. As characters are placed on the output stream, they are interpreted as single byte or multibyte characters and the field width is decremented by the length of the character. .TP \(bu Precision is given in terms of bytes. As characters are placed on the output stream, they are interpreted as single byte or multibyte characters and the precision is decremented by the length of the character. .TP \(bu The return value is given in terms of bytes. As characters are placed on the output stream, they are interpreted as single byte or multibyte characters and the byte count that makes up the return value is incremented by the length of the character. .RE .PP The .CR LC_NUMERIC category determines the radix character used to print floating-point numbers, and the thousands' grouping characters if the grouping flag .CR ' is on. .SS International Code Set Support Single byte character code sets are supported. Multibyte character code sets are also supported as described in the .CR LC_CTYPE category above. .SH RETURN VALUE Each function returns the number of bytes transmitted (excluding the .CR \e0 in the case of .CR sprintf() or a negative value if an output error was encountered. Improper use of .CI % n $ in a format string results in a negative return value. .SH ERRORS .CR printf() , and .CR fprintf() fail if either the .I stream is unbuffered or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked (see .IR write (2)), and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH EXAMPLES To print a date and time in the form "Sunday, July 3, 10:02", where .I weekday and .I month are pointers to null-terminated strings: .RS .nh .PP .ift\f4\s+1printf("%s,\ %s\ %d,\ %d:%.2d",\ weekday,\ month,\ day,\ hour,\ min);\fP\s0 .ifn\f3printf("%s,\ %s\ %d,\ %d:%.2d",\ weekday,\ month,\ day,\ hour,\ min);\fP .RE .PP To print .if n .I pi .if t \(*p to 5 decimal places: .RS .PP .ift \f4\s+1printf("pi \|= \|%.5f", \|4 \(** atan(1\f3.\fP0));\fP\s0 .ifn \f3printf("pi \|= \|%.5f", \|4 \(** atan(1\f3.\fP0));\fP .RE .PP To create a language independent date-and-time printing routine write: .RS .PP .ift \f4\s+1printf(format,weekday,month,day,hour,min,2,2);\fP\s0 .ifn \f3printf(format,weekday,month,day,hour,min,2,2);\fP .RE .PP For American usage, .IR format would point to the string: .IP .ift \f4\s+1"%1$s, %2$s %3$d, %4$*6$.*7$d:%5$*6$.*7$d"\fP\s0 .ifn \f3"%1$s, %2$s %3$d, %4$*6$.*7$d:%5$*6$.*7$d"\fP .PP and result in the output: .IP .ift \f4\s+1"Sunday, July 3, 10:02"\fP\s0 .ifn \f4"Sunday, July 3, 10:02"\fP .PP For German usage, the string: .IP .ift \f4\s+1"%1$s, %3$s %2$d, %4$*6$.*7$d:%5$*6$.*7$d"\fP\s0 .ifn \f3"%1$s, %3$s %2$d, %4$*6$.*7$d:%5$*6$.*7$d"\fP .PP results in the output: .IP .C "Sonntag, 3 Juli 10:02" .SH WARNINGS Notice that with the .CR c conversion character, an int .I arg is converted to an unsigned char. Hence, whole multibyte characters cannot be printed using a single .CR c conversion character. .PP A precision with the .CR s conversion character might result in the truncation of a multibyte character. .SH AUTHOR .CR printf() , .CR fprintf() , and .CR sprintf() were developed by AT&T and HP. .SH SEE ALSO ecvt(3C), ltostr(3C), setlocale(3C), putc(3S), scanf(3S), stdio(3S). .SH STANDARDS CONFORMANCE .CR printf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR sprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4printf()\f1 \- print formatted output to standard output@@@\f3printf(3S)\f1 .\" index@\f4fprintf()\f1 \- print formatted output to a file@@@\f3printf(3S)\f1 .\" index@\f4sprintf()\f1 \- print formatted output to a string@@@\f3printf(3S)\f1 .\" index@\f1print formatted output to standard output, file, or string@@@\f3printf(3S)\f1 .\" index@\f1formatted output, print to standard output, file, or string@@@\f3printf(3S)\f1 .\" index@\f1output, formatted, print to standard output, file, or string@@@\f3printf(3S)\f1 .\" .\" toc@\f3printf(3S)\f1:\0\0\f4printf()\f1, \f4fprintf()\f1, \f4sprintf()\f1@@@print formatted output .\" toc@\f4fprintf()\f1:\0\0print formatted output to a file@@@\f1see \f3printf(3S)\f1 .\" toc@\f4sprintf()\f1:\0\0print formatted output to a string@@@\f1see \f3printf(3S)\f1 .\" .\" links@printf.3s fprintf.3s .\" links@printf.3s sprintf.3s .\" $Header: mvprintw.3x,v 76.2 95/08/01 11:56:52 ssa Exp $ .TA m .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH mvprintw 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mvprintw, mvwprintw, printw, wprintw \(em print formatted output in window .SH SYNOPSIS .C "#include " .P .C "int mvprintw(int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int mvwprintw(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int printw(char *\f2fmt\fP, ...);" .P .C "int wprintw(WINDOW *\f2win\fP, char *\f2fmt\fP, ...);" .SH DESCRIPTION The .CR mvprintw() , .CR mvwprintw() , .Fn printw and .Fn wprintw functions are analogous to .CR printf() . The effect of these functions is as though .Fn sprintf were used to format the string, and then .Fn waddstr were used to add that multi-byte string to the current or specified window at the current or specified cursor position. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" addnstr(), fprintf() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity and its name is changed from .Fn printw to .CR mvprintw() . .\" .\" toc@\f3mvprintw(3X)\f1:\0\0\f4mvprintw()\f1, \f4mvwprintw()\f1, \f4printw()\f1, \f4wprintw\f1@@@print formatted output in window .\" toc@\f4mvwprintw()\f1: print formatted output in window@@@see \f3mvprintw(3X)\f1 .\" toc@\f4printw()\f1: print formatted output in window@@@see \f3mvprintw(3X)\f1 .\" toc@\f4wprintw()\f1: print formatted output in window@@@see \f3mvprintw(3X)\f1 .\" .\" index@\f4mvprintw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f4mvwprintw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f4printw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f4wprintw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f1print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f1formatted output, print in window@@@\f3mvprintw(3X)\f1 .\" index@\f1output, formatted, print in window@@@\f3mvprintw(3X)\f1 .\" index@\f1window, print formatted output in@@@\f3mvprintw(3X)\f1 .\" .\" links@mvprintw.3x mvwprintw.3x .\" links@mvprintw.3x printw.3x .\" links@mvprintw.3x wprintw.3x .\" .\" fileset_database@mvprintw.3x CURS-ENG-A-MAN ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** .wH "" ...\" .rm zA .rm zZ .TH pthread_attr_create 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_attr_create(\|)\*O" .iX "thread attributes object" "creating" .iX "attributes object" "creating" .iX "creating" "thread attributes object" .iX "characteristics of created object" "specifying" .SH NAME .PP \*Lpthread_attr_create\*O - Creates a thread attributes object .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_attr_create( .nL pthread_attr_t *\*Vattr\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Thread attributes object created. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .zA "def,8197,R1.0.3,corrected paragraph" .PP The \*Lpthread_attr_create(\|)\*O routine creates a thread attributes object that is used to specify the attributes of threads when they are created. The attributes object created by this routine is used in calls to \*Lpthread_create(\|)\*O. .zZ "def,8197,R1.0.3,corrected paragraph" .PP The individual attributes (internal fields) of the attributes object are set to default values. (The default values of each attribute are discussed in the descriptions of the following services.) Use the following routines to change the individual attributes: .ML .LI \*Lpthread_attr_setinheritsched(\|)\*O .LI \*Lpthread_attr_setprio(\|)\*O .LI \*Lpthread_attr_setsched(\|)\*O .LI \*Lpthread_attr_setstacksize(\|)\*O .LE .ad b .zA "def,8197,R1.0.3,corrected paragraph" .PP When an attributes object is used to create a thread, the values of the individual attributes determine the characteristics of the new thread. Attributes objects perform in a manner similar to additional parameters. Changing individual attributes does not affect any threads that were previously created using the attributes object. .zZ "def,8197,R1.0.3,corrected paragraph" .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" .zA "def,8197,R1.0.3,corrected paragraph and table" If the function fails, -1 is returned and \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .sp .ne 2.5i .TS center tab(%); l | l | l n | l | lw(3.0i). \*LReturn%Error%Description\*O _ \-1%[\*LENOMEM\*O]%T{ Insufficient memory exists to create the thread attributes object. T} \-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. .TE .zZ "def,8197,R1.0.3,corrected paragraph and table" .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_attr_create (pthread_attr_t *attr); .oE .cE .wH "" .br .ne 1.5i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_delete(3)\*O, \*Lpthread_attr_setinheritsched(3)\*O, \*Lpthread_attr_setprio(3)\*O, \*Lpthread_attr_setsched(3)\*O, \*Lpthread_attr_setstacksize(3)\*O, \*Lpthread_create(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_attr_delete 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_attr_delete(\|)\*O" .iX "thread attributes object" "deleting" .iX "selecting" "thread attributes object" .SH NAME .PP \*Lpthread_attr_delete\*O - Deletes a thread attributes object .wH "" .SH "SYNOPSIS" .sS \*L#include \*L .PP \*Lint pthread_attr_delete( .nL pthread_attr_t *\*Vattr\*L); .sE .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Thread attributes object deleted. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_attr_delete(\|)\*O routine deletes a thread attributes object and gives permission to reclaim storage for the thread attributes object. Threads that were created using this thread attributes object are not affected by the deletion of the thread attributes object. .PP The results of calling this routine are unpredictable if the value specified by the \*Vattr\*O parameter refers to a thread attributes object that does not exist. .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .sp .TS center tab(%); l | l | l n | l | l. \*LReturn%Error%Description\*O _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_attr_delete ( pthread_attr_t *attr); .oE .cE .wH "" .br .ne 1.0i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_create(3)\*O. .wH "" .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_attr_getinheritsched 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_attr_getinheritsched(\|)\*O" .iX "attribute" "scheduling" .iX "inherit scheduling attribute" "obtaining" .iX "creating a thread" "inherit scheduling attribute" .iX "thread creation" "inherit scheduling attribute" .SH NAME .PP \*Lpthread_attr_getinheritsched\*O - Obtains the inherit scheduling attribute .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lint pthread_attr_getinheritsched(\*L .nL \*Lpthread_attr_t \*Vattr\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Thread attributes object whose inherit scheduling attribute is obtained. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_attr_getinheritsched(\|)\*O routine obtains the value of the inherit scheduling attribute in the specified thread attributes object. The inherit scheduling attribute specifies whether threads created using the attributes object inherit the scheduling attributes of the creating thread, or use the scheduling attributes stored in the attributes object that is passed to \*Lpthread_create(\|)\*O. .PP The default value of the inherit scheduling attribute is \*LPTHREAD_INHERIT_SCHED\*O. .br .ne 1.5i .SH "RETURN VALUES" .PP On successful completion, this routine returns the inherit scheduling attribute value. .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb c | l | l. Return%Error%Description _ \&Inherit scheduling attribute%%Successful completion. \&\-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_attr_getinheritsched ( pthread_attr_t attr); .oE .cE .wH "" .br .ne 1.0i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_create(3)\*O, \*Lpthread_attr_setinheritsched(3)\*O, \*Lpthread_create(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_attr_getprio 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_attr_getprio(\|)\*O" .iX "attribute" "priority" .iX "priority attribute" .iX "creating a thread" "priority attribute" .iX "thread creation" "priority attribute" .SH NAME .PP \*Lpthread_attr_getprio\*O - Obtains the scheduling priority attribute .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lint pthread_attr_getprio(\*L .nL \*Lpthread_attr_t \*Vattr\*L); .sE .wH "" .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Thread attributes object whose priority attribute is obtained. .LE .wH "" .SH "DESCRIPTION" .PP The \*Lpthread_attr_getprio(\|)\*O routine obtains the value of the scheduling priority of threads created using the thread attributes object specified by the \*Vattr\*O parameter. .SH "RETURN VALUES" .PP On successful completion, this routine returns the scheduling priority attribute value. .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb c | l | l. Return%Error%Description _ \&Scheduling priority attribute%%Successful completion. \&\-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. .TE .wH "" .cS .SH "EXAMPLES" .PP .oS int pthread_attr_getprio (pthread_attr_t attr); .oE .cE .wH "" .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_create(3)\*O, \*Lpthread_attr_setprio(3)\*O, \*Lpthread_create(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_attr_getsched 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_attr_getsched(\|)\*O" .iX "attribute" "scheduling policy" .iX "scheduling policy attribute" "obtaining" .iX "creating a thread" "scheduling policy attribute" .iX "thread creation" "scheduling policy attribute" .SH NAME .PP \*Lpthread_attr_getsched\*O - Obtains the value of the scheduling policy attribute .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lint pthread_attr_getsched(\*L .nL \*Lpthread_attr_t \*Vattr\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Thread attributes object whose scheduling policy attribute is obtained. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_attr_getsched(\|)\*O routine obtains the scheduling policy of threads created using the thread attributes object specified by the \*Vattr\*O parameter. The default value of the scheduling attribute is \*LSCHED_OTHER\*O. .br .ne 1.5i .SH "RETURN VALUES" .PP On successful completion, this routine returns the value of the scheduling policy attribute. .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb c | l | l. Return%Error%Description _ \&Scheduling policy attribute%%Successful completion. \&\-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_attr_getsched (pthread_attr_t attr); .oE .cE .wH "" .br .ne 1.5i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_create(3)\*O, \*Lpthread_attr_setsched(3)\*O, \*Lpthread_create(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_attr_getstacksize 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_attr_getstacksize(\|)\*O" .iX "attribute" "stacksize" .iX "stacksize attribute" "obtaining" .iX "creating a thread" "stacksize attribute" .iX "thread creation" "stacksize attribute" .iX "stack" "obtaining mimimum size of" .SH NAME .PP \*Lpthread_attr_getstacksize\*O - Obtains the value of the stacksize attribute .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Llong pthread_attr_getstacksize(\*L .nL \*Lpthread_attr_t \*Vattr\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Thread attributes object whose stacksize attribute is obtained. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_attr_getstacksize(\|)\*O routine obtains the minimum size (in bytes) of the stack for a thread created using the thread attributes object specified by the \*Vattr\*O parameter. .br .ne 1.5i .SH "RETURN VALUES" .PP On successful completion, this routine returns the stacksize attribute value. .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb c | l | lw(2.5i). Return%Error%Description _ Stacksize attribute%%Successful completion. \-1%[\*LEINVAL\*O]%T{ The value specified by \*Vattr\*O is invalid. T} .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS .wH "" long pthread_attr_getstacksize (pthread_attr_t attr); .wH "" .oE .cE .wH "" .br .ne 1.5i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_create(3)\*O, \*Lpthread_attr_setstacksize(3)\*O, \*Lpthread_create(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_attr_setinheritsched 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_attr_setinheritsched(\|)\*O" .iX "attribute" "scheduling" .iX "inherit scheduling attribute" "usefulness" .iX "creating a thread" "inherit scheduling attribute" .iX "thread creation" "inherit scheduling attribute" .SH NAME .PP \*Lpthread_attr_setinheritsched\*O - Changes the inherit scheduling attribute .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_attr_setinheritsched(\*L .zA "defect,5220,R1.0.2, changed attr from bold to italics" .nL \*Lpthread_attr_t \*Vattr\*L, .nL \*Lint \*Vinherit\*L); .zZ "defect,5220,R1.0.2, changed attr from bold to italics" .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Thread attributes object to be modified. .LI "\*Vinherit\*O" New value for the inherit scheduling attribute. Valid values are as follows: .VL 5m .LI "\*LPTHREAD_INHERIT_SCHED\*O" This is the default value. The created thread inherits the current priority and scheduling policy of the thread calling \*Lpthread_create(\|)\*O. .LI "\*LPTHREAD_DEFAULT_SCHED\*O" The created thread starts execution with the priority and scheduling policy stored in the thread attributes object. .LE .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_attr_setinheritsched(\|)\*O routine changes the inherit scheduling attribute of thread creation. The inherit scheduling attribute specifies whether threads created using the specified thread attributes object inherit the scheduling attributes of the creating thread, or use the scheduling attributes stored in the thread attributes object that is passed to \*Lpthread_create(\|)\*O. .PP The first thread in an application that is not created by an explicit call to \*Lpthread_create(\|)\*O has a scheduling policy of \*LSCHED_OTHER\*O. (See the \*Lpthread_attr_setprio(\|)\*O and \*Lpthread_attr_setsched(\|)\*O routines for more information on valid priority values and valid scheduling policy values, respectively.) .PP Inheriting scheduling attributes (instead of using the scheduling attributes stored in the attributes object) is useful when a thread is creating several helper threads\(emthreads that are intended to work closely with the creating thread to cooperatively solve the same problem. For example, inherited scheduling attributes ensure that helper threads created in a sort routine execute with the same priority as the calling thread. .br .ne 2.5i .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "def,8178,R1.0.3,corrected paragraph and table" .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, -1 is returned, and \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | l. Return%Error%Description _ \-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. \-1%[\*LEINVAL\*O]%The value specified by \*Vinherit\*O is invalid. .TE .zZ "def,8178,R1.0.3,corrected paragraph and table" .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_attr_setinheritsched (pthread_attr_t *attr, int inherit); .oE .cE .wH "" .br .ne 1.1i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_create(3)\*O, \*Lpthread_attr_getinheritsched(3)\*O, \*Lpthread_attr_setprio(3)\*O, \*Lpthread_attr_setsched(3)\*O, \*Lpthread_create(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_attr_setprio 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_attr_setprio(\|)\*O" .iX "attribute" "priority" .iX "priority attribute" .iX "creating a thread" "priority attribute" .iX "thread creation" "priority attribute" .SH NAME .PP \*Lpthread_attr_setprio\*O - Changes the scheduling priority attribute of thread creation .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lint pthread_attr_setprio(\*L .nL \*Lpthread_attr_t *\*Vattr\*L, .nL \*Lint \*Vpriority\*L); .sS .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Thread attributes object modified. .LI "\*Vpriority\*O" New value for the priority attribute. The priority attribute depends on scheduling policy. Valid values fall within one of the following ranges: .in -5m .ad l .ML .LI \*LPRI_OTHER_MIN\*O <= \*Vpriority\*O <= \*LPRI_OTHER_MAX\*O .nL (use with the \*LSCHED_OTHER\*O policy) .LI \*LPRI_FIFO_MIN\*O <= \*Vpriority\*O <= \*LPRI_FIFO_MAX\*O .nL (use with the \*LSCHED_FIFO\*O policy) .LI \*LPRI_RR_MIN\*O <= \*Vpriority\*O <= \*LPRI_RR_MAX\*O .nL (use with the \*LSCHED_RR\*O policy) .LI \*LPRI_FG_MIN_NP\*O <= \*Vpriority\*O <= \*LPRI_FG_MAX_NP\*O .nL (use with the \*LSCHED_FG_NP\*O policy) .LI \*LPRI_BG_MIN_NP\*O <= \*Vpriority\*O <= \*LPRI_BG_MAX_NP\*O .nL (use with the \*LSCHED_BG_NP\*O policy) .LE .ad b .LE .PP The default priority is the midpoint between \*LPRI_OTHER_MIN\*O and \*LPRI_OTHER_MAX\*O. To specify a minimum or maximum priority, use the appropriate symbol; for example, \*LPRI_FIFO_MIN\*O or \*LPRI_FIFO_MAX\*O. To specify a value between the minimum and maximum, use an appropriate arithmetic expression. For example, to specify a priority midway between the minimum and maximum for the Round Robin scheduling policy, specify the following concept using your programming language's syntax: .zA "def,8410,R1.0.3,corrected formula" .oS pri_rr_mid = (PRI_RR_MIN + PRI_RR_MAX + 1)/2 .oE .zZ "def,8410,R1.0.3,corrected formula" .PP If your expression results in a value outside the range of minimum to maximum, an error results when you attempt to use it. .wH "" .br .ne 1.5i .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_attr_setprio(\|)\*O routine sets the execution priority of threads that are created using the attributes object specified by the \*Vattr\*O parameter. .PP By default, a created thread inherits the priority of the thread calling \*Lpthread_create(\|)\*O. To specify a priority using this routine, scheduling inheritance must be disabled at the time the thread is created. Before calling this routine and \*Lpthread_create(\|)\*O, call \*Lpthread_attr_setinheritsched(\|)\*O and specify the value \*LPTHREAD_DEFAULT_SCHED\*O for the \*Vinherit\*O parameter. .PP An application specifies priority only to express the urgency of executing the thread relative to other threads. Priority is not used to control mutual exclusion when accessing shared data. .zA "defect,7196,R1.0.2, Removed the following sentence (which is false):" ...\" With a sufficient number of processors executing, all ready threads, ...\" regardless of priority, execute simultaneously. .zZ "defect,7196,R1.0.2, Removed the following sentence (which is false):" .br .ne 2i .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(3.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. \-1%[\*LERANGE\*O]%T{ One or more parameters supplied have an invalid value. T} .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_attr_setprio (pthread_attr_t *attr, int priority); .oE .cE .wH "" .br .ne 1.1i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_create(3)\*O, \*Lpthread_attr_getprio(3)\*O, \*Lpthread_attr_setinheritsched(3)\*O, \*Lpthread_create(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_attr_setsched 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_attr_setsched(\|)\*O" .iX "attribute" "scheduling policy" .iX "scheduling policy attribute" .iX "creating a thread" "scheduling policy attribute" .iX "thread creation" "scheduling policy attribute" .SH NAME .PP \*Lpthread_attr_setsched\*O - Changes the scheduling policy attribute of thread creation .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lint pthread_attr_setsched( .nL pthread_attr_t *\*Vattr\*L .nL int \*Vscheduler\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Thread attributes object modified. .LI "\*Vscheduler\*O" New value for the scheduling policy attribute. Valid values are as follows: .VL 9m .LI "\*LSCHED_FIFO\*O" (First In, First Out) The highest-priority thread runs until it blocks. If there is more than one thread with the same priority, and that priority is the highest among other threads, the first thread to begin running continues until it blocks. .LI "\*LSCHED_RR\*O" (Round Robin) The highest-priority thread runs until it blocks; however, threads of equal priority, if that priority is the highest among other threads, are timesliced. Timeslicing is a process in which threads alternate using available processors. .LI "\*LSCHED_OTHER\*O" (Default) .wH "" All threads are timesliced. \*LSCHED_OTHER\*O ensures that all threads, regardless of priority, receive some scheduling so that no thread is completely denied execution time. (However, \*LSCHED_OTHER\*O threads can be denied execution time by \*LSCHED_FIFO\*O or \*LSCHED_RR\*O threads.) .wH "" .LI "\*LSCHED_FG_NP\*O" (Foreground) Same as \*LSCHED_OTHER\*O. Threads are timesliced and priorities can be modified dynamically by the scheduler to ensure fairness. .LI "\*LSCHED_BG_NP\*O" (Background) Ensures that all threads, regardless of priority, receive some scheduling. However, \*LSCHED_BG_NP\*O can be denied execution by \*LSCHED_FIFO\*O or \*LSCHED_RR\*O threads. .LE .LE. .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_attr_setsched(\|)\*O routine sets the scheduling policy of a thread that is created using the attributes object specified by the \*Vattr\*O parameter. The default value of the scheduling attribute is \*LSCHED_OTHER\*O. .ne 2i .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .sp .zA "def,8294,R1.0.3,corrected table" .TS center tab(%); l | l | lw(3.75i) n | l | l. \*LReturn%Error%Description\*O _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. \-1%[\*LEINVAL\*O]%The value specified by \*Vscheduler\*O is invalid. \-1%[\*LEPERM\*O]%T{ The caller does not have the appropriate privileges to set the scheduling policy attribute in the specified threads attribute object. T} .TE .zZ "def,8294,R1.0.3,corrected table" .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_attr_setsched (pthread_attr_t *attr, int scheduler); .oE .cE .wH "" .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_create(3)\*O, \*Lpthread_attr_getsched(3)\*O, \*Lpthread_attr_setinheritsched(3)\*O, \*Lpthread_create(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_attr_setstacksize 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_attr_setstacksize(\|)\*O" .iX "attribute" "stacksize" .iX "stacksize attribute" .iX "creating a thread" "stacksize attribute" .iX "thread creation" "stacksize attribute" .iX "stack" "changing minimum size of" .wH "" .SH NAME .PP \*Lpthread_attr_setstacksize\*O - Changes the stacksize attribute of thread creation .SH "SYNOPSIS" .sS \*L#include \*Lint pthread_attr_setstacksize(\*L .nL \*Lpthread_attr_t *\*Vattr\*L, .nL \*Llong \*Vstacksize\*L); .sE .wH "" .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Thread attributes object modified. .LI "\*Vstacksize\*O" New value for the stacksize attribute. The \*Vstacksize\*O parameter specifies the minimum size (in bytes) of the stack needed for a thread. .LE .wH "" .SH "DESCRIPTION" .PP The \*Lpthread_attr_setstacksize(\|)\*O routine sets the minimum size (in bytes) of the stack needed for a thread created using the attributes object specified by the \*Vattr\*O parameter. Use this routine to adjust the size of the writable area of the stack. The default value of the stacksize attribute is machine specific. .PP A thread's stack is fixed at the time of thread creation. Only the main or initial thread can dynamically extend its stack. .PP Most compilers do not check for stack overflow. Ensure that your thread stack is large enough for anything that you call from the thread. .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .zA "def,8310,R1.0.3,corrected table" .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. \-1%[\*LEINVAL\*O]%The value specified by \*Vstacksize\*O is invalid. .TE .zZ "def,8310,R1.0.3,corrected table" ...\" ...\" .wH "" ...\" .cS ...\" .br ...\" .ne 1.5i ...\" .SH "EXAMPLES" ...\" .PP ...\" .oS ...\" int pthread_attr_setstacksize (pthread_attr_t *attr, ...\" long stacksize); ...\" .oE ...\" .cE ...\" .wH "" .br .ne .75i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_create(3)\*O, \*Lpthread_attr_getstacksize(3)\*O, \*Lpthread_create(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_cancel 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_cancel(\|)\*O" .iX "thread" "canceling" .iX "cancel" "sending to a thread" .iX "cancel" "delivery" .SH NAME .PP \*Lpthread_cancel\*O - Allows a thread to request that it or another thread terminate execution .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_cancel( .nL pthread_t \*Vthread\*L); .sE .wH "" .SH "PARAMETERS" .PP .VL 5m .LI "\*Vthread\*O" Thread that receives a cancel request. .LE .wH "" .SH "DESCRIPTION" .PP .wH "" The \*Lpthread_cancel(\|)\*O routine sends a cancel to the specified thread. A cancel is a mechanism by which a calling thread informs either itself or the called thread to terminate as quickly as possible. Issuing a cancel does not guarantee that the canceled thread receives or handles the cancel. The canceled thread can delay processing the cancel after receiving it. For instance, if a cancel arrives during an important operation, the canceled thread can continue if what it is doing cannot be interrupted at the point where the cancel is requested. .wH "" .PP Because of communications delays, the calling thread can only rely on the fact that a cancel eventually becomes pending in the designated thread (provided that the thread does not terminate beforehand). Furthermore, the calling thread has no guarantee that a pending cancel is to be delivered because delivery is controlled by the designated thread. .PP Termination processing when a cancel is delivered to a thread is similar to \*Lpthread_exit(\|)\*O. Outstanding cleanup routines are executed in the context of the target thread, and a status of \-1 is made available to any threads joining with the target thread. .PP This routine is preferred in implementing Ada's \*Labort\*O statement and any other language (or software-defined construct) for requesting thread cancellation. .PP The results of this routine are unpredictable if the value specified in \*Vthread\*O refers to a thread that does not currently exist. .br .ne 2i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .sp .TS center, tab(%); l | l | l n | l | lw(3.0i). \*LReturn%Error%Description\*O _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The specified thread is invalid. \-1%[\*LERSCH\*O]%T{ The specified thread does not refer to a currently existing thread. T} .TE .wH "" .cS .SH "EXAMPLES" .PP .oS int pthread_cancel (pthread_t *thread); .oE .cE .wH "" .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_exit(3)\*O, \*Lpthread_join(3)\*O, \*Lpthread_setasynccancel(3)\*O, \*Lpthread_setcancel(3)\*O, \*Lpthread_testcancel(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_cleanup_pop 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_cleanup_pop(\|)\*O" .iX "cleanup routine" "executing" .SH NAME .PP \*Lpthread_cleanup_pop\*O - Removes the cleanup handler at the top of the cleanup stack and optionally executes it .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lvoid pthread_cleanup_pop( .nL int \*Vexecute\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vexecute\*O" Integer that specifies whether the cleanup routine that is popped should be executed or just discarded. If the value is nonzero, the cleanup routine is executed. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_cleanup_pop(\|)\*O routine removes the routine specified in \*Lpthread_cleanup_push(\|)\*O from the top of the calling thread's cleanup stack and executes it if the value specified in \*Vexecute\*O is nonzero. .PP This routine and \*Lpthread_cleanup_push(\|)\*O are implemented as macros and must be displayed as statements and in pairs within the same lexical scope. You can think of the \*Lpthread_cleanup_push(\|)\*O macro as expanding to a string whose first character is a \*L{\*O (left brace) and \*Lpthread_cleanup_pop\*O as expanding to a string containing the corresponding \*L}\*O (right brace). .br .ne 1.5i .SH "RETURN VALUES" .PP This routine must be used as a statement. .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS void pthread_cleanup_pop (int execute); .oE .cE .wH "" .br .ne 1.0i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_cleanup_push(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_cleanup_push 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_cleanup_push(\|)\*O" .iX "cleanup routine" "establishing" .SH NAME .PP \*Lpthread_cleanup_push\*O - Establishes a cleanup handler .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lvoid pthread_cleanup_push( .nL \*Lvoid \*Vroutine\*L, .nL \*Lpthread_addr_t \*Varg\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vroutine\*O" Routine executed as the cleanup handler. .LI "\*Varg\*O" Parameter executed with the cleanup routine. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_cleanup_push(\|)\*O routine pushes the specified routine onto the calling thread's cleanup stack. The cleanup routine is popped from the stack and executed with the \*Varg\*O parameter when any of the following actions occur: .ad l .ML .LI The thread calls \*Lpthread_exit(\|)\*O. .LI The thread is canceled. .LI The thread calls \*Lpthread_cleanup_pop(\|)\*O and specifies a nonzero value for the \*Vexecute\*O parameter. .LE .ad b .PP This routine and \*Lpthread_cleanup_pop(\|)\*O are implemented as macros and must be displayed as statements and in pairs within the same lexical scope. You can think of the \*Lpthread_cleanup_push(\|)\*O macro as expanding to a string whose first character is a \*L{\*O (left brace) and \*Lpthread_cleanup_pop(\|)\*O as expanding to a string containing the corresponding \*L}\*O (right brace). .br .ne 1.5i .SH "RETURN VALUES" .PP This routine must be used as a statement. ...\" .wH "" ...\" .cS ...\" .br ...\" .ne 1.5i ...\" .SH "EXAMPLES" ...\" .PP ...\" .oS ...\" void pthread_cleanup_push (void (*routine), ...\" pthread_addr_t *arg); ...\" .oE ...\" .cE ...\" .wH "" .br .ne 1.0i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_cancel(3)\*O, \*Lpthread_cleanup_pop(3)\*O, \*Lpthread_exit(3)\*O, \*Lpthread_testcancel(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_cond_broadcast 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_cond_broadcast(\|)\*O" .iX "waking a thread" .iX "thread" "waking" .iX "broadcasting a wake-up" .SH NAME .PP \*Lpthread_cond_broadcast\*O - Wakes all threads that are waiting on a condition variable .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lint pthread_cond_broadcast( .nL \*Lpthread_cond_t *\*Vcond\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vcond\*O" Condition variable broadcast. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_cond_broadcast(\|)\*O routine wakes all threads waiting on a condition variable. Calling this routine implies that data guarded by the associated mutex has changed so that it might be possible for one or more waiting threads to proceed. If any one waiting thread might be able to proceed, call \*Lpthread_cond_signal(\|)\*O. .PP Call this routine when the associated mutex is either locked or unlocked. .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(3.0i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vcond\*O is invalid. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_cond_broadcast (pthread_cond_t *cond); .oE .cE .wH "" .br .ne 1.5i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_cond_destroy(3)\*O, \*Lpthread_cond_init(3)\*O, \*Lpthread_cond_signal(3)\*O, \*Lpthread_cond_timedwait(3)\*O, \*Lpthread_cond_wait(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_cond_destroy 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_cond_destroy(\|)\*O" .iX "deleting a condition variable" .iX "condition variable" "deleting" .SH NAME .PP \*Lpthread_cond_destroy\*O - Deletes a condition variable .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lint pthread_cond_destroy(\*L .nL \*Lpthread_cond_t *\*Vcond\*L); .sE .PP .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vcond\*O" Condition variable deleted. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_cond_destroy(\|)\*O routine deletes a condition variable. Call this routine when a condition variable is no longer referenced. The effect of calling this routine is to give permission to reclaim storage for the condition variable. .PP The results of this routine are unpredictable if the condition variable specified in \*Vcond\*O does not exist. .PP The results of this routine are also unpredictable if there are threads waiting for the specified condition variable to be signaled or broadcast when it is deleted. .ne 2i .br .ne 1.5i .SH "Return Values" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .ad l .TS center, tab(%); lb | lb | lb n | l | lw(3.75i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vcond\*O is invalid. \-1%[\*LEBUSY\*O]%T{ A thread is currently executing a \*Lpthread_cond_timedwait(\|)\*O routine or \*Lpthread_cond_wait(\|)\*O on the condition variable specified in \*Vcond\*O. T} .TE .ad b .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_cond_destroy (pthread_cond_t *cond); .oE .cE .wH "" .br .ne 1.1i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_cond_broadcast(3)\*O, \*Lpthread_cond_init(3)\*O, \*Lpthread_cond_signal(3)\*O, \*Lpthread_cond_timedwait(3)\*O, \*Lpthread_cond_wait(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_cond_init 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_cond_init(\|)\*O" .iX "creating" "a condition variable" .iX "initializing a condition variable" .iX "condition variable" "creating" .iX "condition variable" "definition of" .iX "predicate" .SH NAME .PP \*Lpthread_cond_init\*O - Creates a condition variable .wH "" .SH "SYNOPSIS" .sS #\*Linclude .PP \*Lint pthread_cond_init( .nL pthread_cond_t *\*Vcond\*L, .nL pthread_condattr_t \*Vattr\*L); .sE .PP .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 3m .LI "\*Vcond\*O" Condition variable that is created. .LI "\*Vattr\*O" Condition variable attributes object that defines the characteristics of the condition variable created. If you specify \*Lpthread_condattr_default\*O, default attributes are used. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_cond_init(\|)\*O routine creates and initializes a condition variable. A condition variable is a synchronization object used in conjunction with a mutex. A mutex controls access to shared data; a condition variable allows threads to wait for that data to enter a defined state. The state is defined by a Boolean expression called a predicate. ...\".gL "predicate" .iX "predicate" "definition of" .iX "condition variable" "definition of predicate" .PP A condition variable is signaled or broadcast to indicate that a predicate might have become true. The broadcast operation indicates that all waiting threads need to resume and reevaluate the predicate. The signal operation is used when any one waiting thread can continue. .PP If a thread that holds a mutex determines that the shared data is not in the correct state for it to proceed (the associated predicate is not true), it waits on a condition variable associated with the desired state. Waiting on the condition variable automatically releases the mutex so that other threads can modify or examine the shared data. When a thread modifies the state of the shared data so that a predicate might be true, it signals or broadcasts on the appropriate condition variable so that threads waiting for that predicate can continue. .PP It is important that all threads waiting on a particular condition variable at any time hold the \*Esame\*O mutex. If they do not, the behavior of the wait operation is unpredictable (an implementation can use the mutex to control internal access to the condition variable object). However, it is legal for a client to store condition variables and mutexes and later reuse them in different combinations. The client must ensure that no threads use the condition variable with the old mutex. At any time, an arbitrary number of condition variables can be associated with a single mutex, each representing a different predicate of the shared data protected by that mutex. .PP Condition variables are not owned by a particular thread. Any associated storage is not automatically deallocated when the creating thread terminates. .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .sp .TS center tab(%); l | l | l n | l | lw(3.0i). \*LReturn%Error%Description\*O _ 0%%Successful completion. \-1%[\*LEAGAIN\*O]%T{ The system lacks the necessary resources to initialize another condition variable. T} .zA"defect,5265,R1.0.2, adding EINVAL error code" \-1%[\*LEINVAL\*O]%T{ Invalid attributes object. T} .zZ"defect,5265,R1.0.2, adding EINVAL error code" \-1%[\*LENOMEM\*O]%T{ Insufficient memory exists to initialize the condition variable. T} .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_cond_init (pthread_cond_t *cond, pthread_condattr_t attr); .oE .cE .wH "" .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_cond_broadcast(3)\*O, \*Lpthread_cond_destroy(3)\*O, \*Lpthread_cond_signal(3)\*O, \*Lpthread_cond_timedwait(3)\*O, \*Lpthread_cond_wait(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_cond_signal 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_cond_signal(\|)\*O" .iX "waking a thread" .iX "thread" "waking" .iX "signaling a wake-up" .SH NAME .PP \*Lpthread_cond_signal\*O - Wakes one thread that is waiting on a condition variable .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lint pthread_cond_signal( .nL \*Lpthread_cond_t *\*Vcond\*L); .sE .PP .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vcond\*O" Condition variable signaled. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_cond_signal(\|)\*O routine wakes one thread waiting on a condition variable. Calling this routine implies that data guarded by the associated mutex has changed so that it is possible for a single waiting thread to proceed. Call this routine when any thread waiting on the specified condition variable might find its predicate true, but only one thread needs to proceed. .PP The scheduling policy determines which thread is awakened. For policies \*LSCHED_FIFO\*O and \*LSCHED_RR\*O a blocked thread is chosen in priority order. .PP Call this routine when the associated mutex is either locked or unlocked. .br .ne 2ii .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vcond\*O is invalid. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_cond_signal (pthread_cond_t *cond); .oE .cE .wH "" .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_cond_broadcast(3)\*O, \*Lpthread_cond_destroy(3)\*O, \*Lpthread_cond_init(3)\*O, \*Lpthread_cond_timedwait(3)\*O, \*Lpthread_cond_wait(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_cond_timedwait 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_cond_timedwait(\|)\*O" .iX "waiting for condition variable" .iX "condition variable" "waiting for a specified time" .SH NAME .PP \*Lpthread_cond_timedwait\*O - Causes a thread to wait for a condition variable to be signaled or broadcast .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lint pthread_cond_timedwait( .nL \*Lpthread_cond_t *\*Vcond\*L, .nL \*Lpthread_mutex_t *\*Vmutex\*L, .nL \*Lstruct timespec *\*Vabstime\*L); .sE .PP .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vcond\*O" Condition variable waited on. .LI "\*Vmutex\*O" Mutex associated with the condition variable specified in \*Vcond\*O. .LI "\*Vabstime\*O" Absolute time at which the wait expires, if the condition has not been signaled or broadcast. (See the \*Lpthread_get_expiration_np(\|)\*O routine, which you can use to obtain a value for this parameter.) .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_cond_timedwait(\|)\*O routine causes a thread to wait until one of the following occurs: .ad l .ML .LI The specified condition variable is signaled or broadcast. .LI The current system clock time is greater than or equal to the time specified by the \*Vabstime\*O parameter. .LE .ad b .PP This routine is identical to \*Lpthread_cond_wait(\|)\*O except that this routine can return before a condition variable is signaled or broadcast\(emspecifically, when a specified time expires. .PP If the current time equals or exceeds the expiration time, this routine returns immediately, without causing the current thread to wait. .PP Call this routine after you lock the mutex specified in \*Vmutex\*O. The results of this routine are unpredictable if this routine is called without first locking the mutex. .br .ne 2.5i .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(3.0i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%T{ The value specified by \*Vcond\*O, \*Vmutex\*O, or \*Vabstime\*O is invalid. T} \-1%[\*LEAGAIN\*O]%The time specified by \*Vabstime\*O expired. \-1%[\*LEDEADLK\*O]%A deadlock condition is detected. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_cond_timedwait (pthread_cond_t *cond, pthread_mutex_t *mutex, struct timespec *abstime); .oE .cE .wH "" .br .ne 1.5i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_cond_broadcast(3)\*O, \*Lpthread_cond_destroy(3)\*O, \*Lpthread_cond_init(3)\*O, \*Lpthread_cond_signal(3)\*O, \*Lpthread_cond_wait(3)\*O, \*Lpthread_get_expiration_np(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_cond_wait 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_cond_wait(\|)\*O" .iX "condition variable" "waiting for" .iX "waiting for condition variable" .SH NAME .PP \*Lpthread_cond_wait\*O - Causes a thread to wait for a condition variable to be signaled or broadcast .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_cond_wait(\*L .nL \*Lpthread_cond_t *\*Vcond\*L, .nL \*Lpthread_mutex_t *\*Vmutex\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vcond\*O" Condition variable waited on. .LI "\*Vmutex\*O" Mutex associated with the condition variable specified in \*Vcond\*O. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_cond_wait(\|)\*O routine causes a thread to wait for a condition variable to be signaled or broadcast. Each condition corresponds to one or more predicates based on shared data. The calling thread waits for the data to reach a particular state (for the predicate to become true). .PP Call this routine after you have locked the mutex specified in \*Vmutex\*O. The results of this routine are unpredictable if this routine is called without first locking the mutex. .PP This routine automatically releases the mutex and causes the calling thread to wait on the condition. If the wait is satisfied as a result of some thread calling \*Lpthread_cond_signal(\|)\*O or \*Lpthread_cond_broadcast(\|)\*O, the mutex is reacquired and the routine returns. .PP A thread that changes the state of storage protected by the mutex in such a way that a predicate associated with a condition variable might now be true must call either \*Lpthread_cond_signal(\|)\*O or \*Lpthread_cond_broadcast(\|)\*O for that condition variable. If neither call is made, any thread waiting on the condition variable continues to wait. .PP This routine might (with low probability) return when the condition variable has not been signaled or broadcast. When a spurious wakeup occurs, the mutex is reacquired before the routine returns. (To handle this type of situation, enclose this routine in a loop that checks the predicate.) .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vcond\*O or \*Vmutex\*O is invalid. \-1%[\*LEDEADLK\*O]%A deadlock condition is detected. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_cond_wait (pthread_cond_t *cond, pthread_mutex_t *mutex); .oE .cE .wH "" .br .ne 1.5i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_cond_broadcast(3)\*O, \*Lpthread_cond_destroy(3)\*O, \*Lpthread_cond_init(3)\*O, \*Lpthread_cond_signal(3)\*O, \*Lpthread_cond_timedwait(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_condattr_create 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_condattr_create(\|)\*O" .iX "condition variable attributes object" "creating" .iX "creating" "condition variable attributes object" .iX "characteristics of created condition variable" "specifying" .wH "" .SH NAME .PP \*Lpthread_condattr_create\*O - Creates a condition variable attributes object .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_condattr_create( .nL pthread_condattr_t *\*Vattr\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Condition variable attributes object that is created. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_condattr_create(\|)\*O routine creates a condition variable attributes object that is used to specify the attributes of condition variables when they are created. The condition variable attributes object is initialized with the default value for all of the attributes defined by a given implementation. .PP When a condition variable attributes object is used to create a condition variable, the values of the individual attributes determine the characteristics of the new object. Attributes objects act like additional parameters to object creation. Changing individual attributes does not affect objects that were previously created using the attributes object. .br .ne 1.5i .SH "RETURN VALUES" .PP The created condition variable attributes object is returned to the \*Vattr\*O parameter. .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .sp .ne 6 .TS center, tab(%); l | l | l n | l | lw(3.0i). \*LReturn%Error%Description\*O _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. \-1%[\*LENOMEM\*O]%T{ Insufficient memory exists to create the condition variable attributes object. T} .TE ...\" .wH "" ...\" .cS ...\" .br ...\" .ne 1.5i ...\" .SH "EXAMPLES" ...\" .PP ...\" .oS ...\" int pthread_condattr_create (pthread_condattr_t *attr); ...\" .oE ...\" .cE ...\" .wH "" .br .ne .75i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_condattr_delete(3)\*O, \*Lpthread_cond_init(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_condattr_delete 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_condattr_delete(\|)\*O" .iX "condition variable attributes object" "deleting" .iX "deleting" "condition variable attributes object" .SH NAME .PP \*Lpthread_condattr_delete\*O - Deletes a condition variable attributes object .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lint pthread_condattr_delete( .nL pthread_condattr_t *\*Vattr\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Condition variable attributes object deleted. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_condattr_delete(\|)\*O routine deletes a condition variable attributes object. Call this routine when a condition variable attributes object created by \*Lpthread_condattr_create(\|)\*O is no longer referenced. .PP This routine gives permission to reclaim storage for the condition variable attributes object. Condition variables that are created using this attributes object are not affected by the deletion of the condition variable attributes object. .PP The results of calling this routine are unpredictable if the handle specified by the \*Vattr\*O parameter refers to an attributes object that does not exist. .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .sp .TS center, tab(%); l | l | l n | l | lw(2.5i). \*LReturn%Error%Description\*O _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_condattr_delete (pthread_condattr_t *attr); .oE .cE .wH "" .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_condattr_create(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_create 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_create(\|)\*O" .iX "\*Lpthread_create(\|)\*O" .iX "thread" "creating" .iX "creating a thread" .iX "thread" "events that cause termination" .iX "thread" "normal termination" .iX "thread" "error termination" .iX "termination of a thread" "events that cause" .iX "termination of a thread" "normal" .iX "termination of a thread" "error" .iX "normal termination of a thread" .iX "error termination of a thread" .SH NAME .PP \*Lpthread_create\*O - Creates a thread object and thread .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_create(\*L .nL \*Lpthread_t *\*Vthread\*L, .nL \*Lpthread_attr_t \*Vattr\*L, .nL \*Lpthread_startroutine_t \*Vstart_routine\*L, .nL \*Lpthread_addr_t \*Varg\*L); .sE .PP .br .ne 1.5i .SH "PARAMETERS" .PP .VL 6m .LI "\*Vthread\*O" Handle to the thread object created. .LI "\*Vattr\*O" Thread attributes object that defines the characteristics of the thread being created. If you specify \*Lpthread_attr_default\*O, default attributes are used. .LI "\*Vstart_routine\*O" Function executed as the new thread's start routine. .LI "\*Varg\*O" Address value copied and passed to the thread's start routine. .LE .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_create(\|)\*O routine creates a thread object and a thread. A \*Lthread\*O is a ...\".gL "thread" single, sequential flow of control within a program. It is the active execution of a designated routine, including any nested routine invocations. A thread object defines and controls the executing thread. .SS "Creating a Thread" .PP Calling this routine sets into motion the following actions: .ad l .ML .LI An internal thread object is created to describe the thread. .LI The associated executable thread is created with attributes specified by the \*Vattr\*O parameter (or with default attributes if \*Lpthread_attr_default\*O is specified). .LI The \*Vthread\*O parameter receives the new thread. .LI The \*Vstart_routine\*O function is called. This may occur before this routine returns successfully. .LE .ad b .SS "Thread Execution" .PP The thread is created in the ready state and therefore might immediately begin executing the function specified by the \*Vstart_routine\*O parameter. The newly created thread begins running before \*Lpthread_create(\|)\*O completes if the new thread follows the \*LSCHED_RR\*O or \*LSCHED_FIFO\*O scheduling policy or has a priority higher than the creating thread, or both. Otherwise, the new thread begins running at its turn, which with sufficient processors might also be before \*Lpthread_create(\|)\*O returns. .PP The \*Vstart_routine\*O parameter is passed a copy of the \*Varg\*O parameter. The value of the \*Varg\*O parameter is unspecified. .PP The thread object exists until the \*Lpthread_detach(\|)\*O routine is called or the thread terminates, whichever occurs last. .PP The synchronization between the caller of \*Lpthread_create(\|)\*O and the newly created thread is through the use of the \*Lpthread_join(\|)\*O routine (or any other mutexes or condition variables they agree to use). .SS "Terminating a Thread" .PP A thread terminates when one of the following events occurs: .ad l .ML .LI The thread returns from its start routine. .LI The thread exits (within a routine) as the result of calling the \*Lpthread_exit(\|)\*O routine. .LI The thread is canceled. .LE .ad b .SS "When a Thread Terminates" .PP The following actions are performed when a thread terminates: .ad l .ML .LI If the thread terminates by returning from its start routine or calling \*Lpthread_exit(\|)\*O, the return value is copied into the thread object. If the start routine returns normally and the start routine is a procedure that does not return a value, then the result obtained by \*Lpthread_join(\|)\*O is unpredictable. If the thread has been cancelled, a return value of \-1 is copied into the thread object. The return value can be retrieved by other threads by calling the \*Lpthread_join(\|)\*O routine. .LI A destructor for each thread-specific data point is removed from the list of destructors for this thread and then is called. This step destroys all the thread-specific data associated with the current thread. .LI Each cleanup handler that has been declared by \*Lpthread_cleanup_push(\|)\*O and not yet removed by \*Lpthread_cleanup_pop(\|)\*O is called. The most recently pushed handler is called first. .LI A flag is set in the thread object indicating that the thread has terminated. This flag must be set in order for callers of \*Lpthread_join(\|)\*O to return from the call. .LI A broadcast is made so that all threads currently waiting in a call to \*Lpthread_join(\|)\*O can return from the call. .LI The thread object is marked to indicate that it is no longer needed by the thread itself. A check is made to determine if the thread object is no longer needed by other threads; that is, if \*Lpthread_detach(\|)\*O has been called. If that routine is called, then the thread object is deallocated. .LE .ad b .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected end of paragraph" .zA "defect,7003,R1.0.2, Reworded the return values section" Upon successful completion, this routine stores the identifier of the created thread at \*Vthread\*O and returns 0. Otherwise, a value of -1 is returned and no thread is created, the contents of \*Vthread\*O are undefined, and \*Lerrno\*O may be set to one of the following values: .zZ "defect,7003,R1.0.2, Reworded the return values section" .zZ "defect,7040,R1.0.2, corrected end of paragraph" .PP .TS center, tab(%); lb | lb | lb l | l | lw(3.0i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEAGAIN\*O]%T{ The system lacks the necessary resources to create another thread. T} \-1%[\*LENOMEM\*O]%T{ Insufficient memory exists to create the thread object. This is not a temporary condition. T} .TE .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_create (pthread_t *thread, pthread_attr_t attr, pthread_startroutine_t start_routine, pthread_addr_t arg); .oE .cE .br .ne 1.2i .zA "1.0.2 update: Deleted extraneous RELATED INFORMATION header" .zZ "1.0.2 update: Deleted extraneous RELATED INFORMATION header" .SH "RELATED INFORMATION" .zA "defect,7564,R1.0.3, turned off fill mode" .ad l .PP Functions: \*Lpthread_attr_create(3)\*O, \*Lpthread_cancel(3)\*O, \*Lpthread_detach(3)\*O, \*Lpthread_exit(3)\*O, \*Lpthread_join(3)\*O. .ad b .zZ "defect,7564,R1.0.3, turned off fill mode" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_delay_np 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_delay_np(\|)\*O" .iX "thread" "delaying execution of" .iX "delaying execution of a thread" .SH NAME .PP \*Lpthread_delay_np\*O - Causes a thread to wait for a specified period .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_delay_np(\*L .nL \*Lstruct timespec *\*Vinterval\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vinterval\*O" Number of seconds and nanoseconds that the calling thread waits before continuing execution. The value specified must be greater than or equal to 0 (zero). .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_delay_np(\|)\*O routine causes a thread to delay execution for a specified period of elapsed wall clock time. The period of time the thread waits is at least as long as the number of seconds and nanoseconds specified in the \*Vinterval\*O parameter. .PP Specifying an interval of 0 seconds and 0 nanoseconds is allowed and can result in the thread giving up the processor or delivering a pending cancel. .PP .wH "" The \*Lstruct timespec\*O structure contains two fields, as follows: .ad l .ML .LI The \*Ltv_sec\*O field is an integer number of seconds. .LI The \*Ltv_nsec\*O field is an integer number of nanoseconds. .LE .ad b .wH "" .PP This routine is a new primitive. .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vinterval\*O is invalid. .TE ...\" .wH "" ...\" .cS ...\" .br ...\" .ne 1.5i ...\" .SH "EXAMPLES" ...\" .PP ...\" .oS ...\" extern int pthread_delay_np (struct timespec *interval); ...\" .oE ...\" .cE ...\" .wH "" .br .ne .8i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_yield(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_detach 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_detach(\|)\*O" .iX "thread" "deleting" .iX "deleting a thread" .SH NAME .PP \*Lpthread_detach\*O - Marks a thread object for deletion .wH "" .SH "SYNOPSIS" ...\" .sS \*L#include .PP \*Lint pthread_detach(\*L .nL \*Lpthread_t *\*Vthread\*L); ...\" .sE ...\" .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vthread\*O" Thread object marked for deletion. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_detach(\|)\*O routine indicates that storage for the specified thread is reclaimed when the thread terminates. This includes storage for the \*Vthread\*O parameter's return value. If \*Vthread\*O has not terminated when this routine is called, this routine does not cause it to terminate. .PP Call this routine when a thread object is no longer referenced. Additionally, call this routine for every thread that is created to ensure that storage for thread objects does not accumulate. .PP You cannot join with a thread after the thread has been detached. .PP The results of this routine are unpredictable if the value of \*Vthread\*O refers to a thread object that does not exist. .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vthread\*O is invalid. \-1%[\*LESRCH\*O]%T{ The value specified by \*Vthread\*O does not refer to an existing thread. T} .TE ...\" .wH "" ...\" .cS ...\" .br ...\" .ne 1.5i ...\" .SH "EXAMPLES" ...\" .PP ...\" .oS ...\" int pthread_detach (pthread_t *thread); ...\" .oE ...\" .cE ...\" .wH "" .br .ne 1.0i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_cancel(3)\*O, \*Lpthread_create(3)\*O, \*Lpthread_exit(3)\*O, \*Lpthread_join(3)\*O. .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_equal 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_equal(\|)\*O" .iX "identifier" "comparing" .zA"defect,5118,R1.0.2, routine in code missing from docs" .SH NAME .PP \*Lpthread_equal\*O - Compares one thread identifier to another thread identifier. .wH "" .SH "SYNOPSIS" .zA "def,8179,R1.0.3,corrected synopsis" .sS #\*Linclude .PP \*Lboolean32 pthread_equal( .nL pthread_t *\*Vthread1\*L, .nL pthread_t *\*Vthread2\*L); .sE .zZ "def,8179,R1.0.3,corrected synopsis" .PP .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 3m .LI "\*Vthread1\*O" The first thread identifier to be compared. .LI "\*Vthread2\*O" The second thread identifier to be compared. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP This routine compares one thread identifier to another thread identifier. (This routine does not check whether the objects that correspond to the identifiers currently exist.) If the identifiers have values indicating that they designate the same object, 1 (true) is returned. If the values do not designate the same object, 0 (false) is returned. .PP This routine is implemented as a C macro. .br .ne 1.5i .SH "RETURN VALUES" .PP Possible return values are as follows: .sp .TS center tab(%); l | l | l n | l | lw(3.0i). \*LReturn%Error%Description\*O _ 0%%Values of thread1 and thread2 do not designate the same object. 1%%Values of thread1 and thread2 designate the same object. .TE .br .ne 1.5i .SH "EXAMPLES" .PP .oS equal = pthread_equal (thread1, thread2) .oE .cE .wH "" .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_create(3)\*O .ad b .zZ"defect,5118,R1.0.2, routine in code missing from docs" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_exit 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_exit(\|)\*O" .iX "thread" "normal termination" .iX "termination of a thread" "normal" .iX "termination of a thread" "premature successful completion" .iX "termination of a thread" "without returning from start routine" .iX "normal termination of a thread" .SH NAME .PP \*Lpthread_exit\*O - Terminates the calling thread .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lvoid pthread_exit( .nL pthread_addr_t \*Vstatus\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vstatus\*O" Address value copied and returned to the caller of \*Lpthread_join(\|)\*O. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_exit(\|)\*O routine terminates the calling thread and makes a status value available to any thread that calls \*Lpthread_join(\|)\*O and specifies the terminating thread. .PP An implicit call to \*Lpthread_exit(\|)\*O is issued when a thread returns from the start routine that was used to create it. The function's return value serves as the thread's exit status. If the return value is -1, an error exit is forced for the thread instead of a normal exit. The process exits when the last running thread calls \*Lpthread_exit(\|)\*O, with an undefined exit status. .SS "Restrictions" .PP The \*Lpthread_exit(\|)\*O routine does not work in the main (initial) thread because DCE Threads relies on information at the base of thread stacks; this information does not exist in the main thread. .LE .br .ne 1.5i .SH "RETURN VALUES" .PP No value is returned. .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS void pthread_exit (pthread_addr_t status); .oE .cE .wH "" .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_create(3)\*O, \*Lpthread_detach(3)\*O, \*Lpthread_join(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_get_expiration_np 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_get_expiration_np(\|)\*O" .iX "time" "obtaining expiration" .iX "time" "adding interval to current time" .iX "expiration time" "obtaining" .SH NAME .PP \*Lpthread_get_expiration_np\*O - Obtains a value representing a desired expiration time .SH "SYNOPSIS" .wH "" ...\" .sS \*L#include .PP \*Lint pthread_get_expiration_np(\*L .nL \*Lstruct timespec *\*Vdelta\*L, .nL \*Lstruct timespec *\*Vabstime\*L); ...\" .sE ...\" .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vdelta\*O" Number of seconds and nanoseconds to add to the current system time. The result is the time when a timed wait expires. .LI "\*Vabstime\*O" Value representing the expiration time. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_get_expiration_np(\|)\*O routine adds a specified interval to the current absolute system time and returns a new absolute time. This new absolute time is used as the expiration time in a call to \*Lpthread_cond_timedwait(\|)\*O. .PP This routine is a new primitive. .PP .wH "" The \*Lstruct timespec\*O structure contains two fields, as follows: .ad l .ML .LI The \*Ltv_sec\*O field is an integer number of seconds. .LI The \*Ltv_nsec\*O field is an integer number of nanoseconds. .LE .ad b .wH "" .br .ne 1.5i .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vdelta\*O is invalid. .TE ...\" .wH "" ...\" .cS ...\" .br ...\" .ne 1.5i ...\" .SH "EXAMPLES" ...\" .PP ...\" .oS ...\" extern int pthread_get_expiration_np (struct timespec *delta, ...\" struct timespec *abstime); ...\" .oE ...\" .cE .wH "" .br .ne .8i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_cond_timedwait(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_getprio 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_getprio(\|)\*O" .iX "thread" "obtaining current priority of" .iX "priority" "obtaining for thread" .SH NAME .PP \*Lpthread_getprio\*O - Obtains the current priority of a thread .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lint pthread_getprio(\*L .nL \*Lpthread_t \*Vthread\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vthread\*O" Thread whose priority is obtained. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_getprio(\|)\*O routine obtains the current priority of a thread. The current priority is different from the initial priority of the thread if the \*Lpthread_setprio(\|)\*O routine is called. .PP The exact effect of different priority values depends upon the scheduling policy assigned to the thread. .br .ne 1.5i .br .ne 1.5i .SH "RETURN VALUES" .PP The current priority value of the thread specified in \*Vthread\*O is returned. (See the \*Lpthread_setprio(\|)\*O reference page for valid values.) .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb c | l | lw(3.0i). Return%Error%Description _ Priority value%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vthread\*O is invalid. \-1%[\*LESRCH\*O]%T{ The value specified by \*Vthread\*O does not refer to an existing thread. T} .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_getprio (pthread_t *thread); .oE .cE .wH "" .br .ne 1.0i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_setprio(3)\*O, \*Lpthread_setprio(3)\*O, \*Lpthread_setscheduler(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_getscheduler 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_getscheduler(\|)\*O" .iX "thread" "obtaining current scheduling policy of" .iX "scheduling policy" "obtaining for thread" .SH NAME .PP \*Lpthread_getscheduler\*O - Obtains the current scheduling policy of a thread .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_getscheduler(\*L .nL \*Lpthread_t \*Vthread\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vthread\*O" Thread whose scheduling policy is obtained. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_getscheduler(\|)\*O routine obtains the current scheduling policy of a thread. The current scheduling policy of a thread is different from the initial scheduling policy if the \*Lpthread_setscheduler(\|)\*O routine is called. .br .ne 1.5i .SH "RETURN VALUES" .PP The current scheduling policy value of the thread specified in \*Vthread\*O is returned. (See the \*Lpthread_setscheduler(\|)\*O reference page for valid values.) .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb c | l | lw(2.5i). Return%Error%Description _ Current scheduling policy%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vthread\*O is invalid. \-1%[\*LESRCH\*O]%T{ The value specified by \*Vthread\*O does not refer to an existing thread. T} .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_getscheduler (pthread_t *thread); .oE .cE .wH "" .br .ne 1.0i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_setscheduler(3)\*O, \*Lpthread_setscheduler(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_getspecific 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_getspecific(\|)\*O" .iX "thread-specific data" "obtaining" .iX "key value" "obtaining thread-specific data for" .iX "thread-specific data" .SH NAME .PP \*Lpthread_getspecific\*O - Obtains the thread-specific data associated with the specified key .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_getspecific(\*L .nL \*Lpthread_key_t \*Vkey\*L, .nL \*Lpthread_addr_t *\*Vvalue\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vkey\*O" Context key value that identifies the data value obtained. This key value must be obtained from \*Lpthread_keycreate(\|)\*O. .LI "\*Vvalue\*O" Address of the current thread-specific data value associated with the specified key. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_getspecific(\|)\*O routine obtains the thread-specific data associated with the specified key for the current thread. .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The key value is invalid. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_getspecific (pthread_key_t key, pthread_addr_t *value); .oE .cE .wH "" .br .ne 1.5i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_keycreate(3)\*O, \*Lpthread_setspecific(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright (c) 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_join 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_join(\|)\*O" .iX "thread" "waiting for the termination of" .iX "termination" "waiting for" .SH NAME .PP \*Lpthread_join\*O - Causes the calling thread to wait for the termination of a specified thread .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_join( .nL pthread_t \*Vthread\*L, .nL pthread_addr_t *\*Vstatus\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .VL 5m .LI "\*Vthread\*O" Thread whose termination is awaited by the caller of this routine. .LI "\*Vstatus\*O" Status value of the terminating thread when that thread calls \*Lpthread_exit(\|)\*O. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_join(\|)\*O routine causes the calling thread to wait for the termination of a specified thread. A call to this routine returns after the specified thread has terminated. .PP Any number of threads can call this routine. All threads are awakened when the specified thread terminates. .PP If the current thread calls this routine to join with itself, an error is returned. .PP The results of this routine are unpredictable if the value for \*Vthread\*O refers to a thread object that no longer exists. .br .ne 2.5i .br .ne 1.5i .SH "RETURN VALUES" .PP If the thread terminates normally, the exit status is the value that is is optionally returned from the thread's start routine. .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .br .ne 1.2i .TS center, tab(%); l | l | l n | l | lw(3.0i). \*LReturn%Error%Description\*O _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vthread\*O is invalid. \-1%[\*LESRCH\*O]%T{ The value specified by \*Vthread\*O does not refer to a currently existing thread. T} \-1%[\*LEDEADLK\*O]%A deadlock is detected. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_join (pthread_t thread, pthread_addr_t *status); .oE .cE .wH "" .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_create(3)\*O, \*Lpthread_detach(3)\*O, \*Lpthread_exit(3)\*O. .wH "" .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright (c) 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_keycreate 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_keycreate(\|)\*O" .iX "thread-specific data" "generating key value for" .iX "thread-specific data" "uses for" .iX "data" "generating key value for" .iX "data" "uses for" .iX "creating thread-specific data key value" .iX "key value" "generating for thread-specific data" .iX "thread" "thread-specific data of" .SH NAME .PP \*Lpthread_keycreate\*O - Generates a unique thread-specific data key value .SH "SYNOPSIS" .wH "" .zA "def,7430,R1.0.3,corrected synopsis" .sS \*L#include .PP \*Lint pthread_keycreate( .nL pthread_key_t *\*Vkey\*L, .nL void (*\*Vdestructor\*L) (void *\*Vvalue\*L)); .sE .zZ "def,7430,R1.0.3,corrected synopsis" .wH "" .br .ne 1.5i .SH "PARAMETERS" .VL 5m .LI "\*Vkey\*O" Value of the new thread-specific data key. .LI "\*Vdestructor\*O" Procedure to be called to destroy a data value associated with the created key when the thread terminates. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_keycreate(\|)\*O routine generates a unique thread-specific data key value. This key value identifies a thread-specific data value, which is an address of memory generated by the client containing arbitrary data of any size. .PP Thread-specific data allows client software to associate information with the current thread. .PP For example, thread-specific data can be used by a language runtime library that needs to associate a language-specific thread-private data structure with an individual thread. The thread-specific data routines also provide a portable means of implementing the class of storage called thread-private static, which is needed to support parallel decomposition in the FORTRAN language. .PP This routine generates and returns a new key value. Each call to this routine within a process returns a key value that is unique within an application invocation. Calls to \*Lpthread_keycreate(\|)\*O must occur in initialization code guaranteed to execute only once in each process. The \*Lpthread_once(\|)\*O routine provides a way of specifying such code. .PP When multiple facilities share access to thread-specific data, the facilities must agree on the key value that is associated with the context. The key value must be created only once and needs to be stored in a location known to each facility. (It may be desirable to encapsulate the creation of a key, and the setting and getting of context values for that key, within a special facility created for that purpose.) .PP When a thread terminates, thread-specific data is automatically destroyed. For each thread-specific data currently associated with the thread, the \*Vdestructor\*O ...\".gL "destructor" routine associated with the key value of that context is called. The order in which per-thread context destructors are called at thread termination is undefined. .br .ne 3.0i .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .sp .TS center, tab(%); l | l | l n | l | lw(2.5i). \*LReturn%Error%Description\*O _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vkey\*O is invalid. .zA "defect,6943,R1.0.2, swapping EAGAIN and ENOMEM return values" \-1%[\*LEAGAIN\*O]%T{ An attempt was made to allocate a key when the key namespace is exhausted. This is not a temporary condition. T} .sp 4p \-1%[\*LENOMEM\*O]%Insufficient memory exists to create the key. .zZ "defect,6943,R1.0.2, swapping EAGAIN and ENOMEM return values" .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_keycreate(pthread_destructor_t destructor, pthread_key_t *key); .oE .cE .wH "" .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_getspecific(3)\*O, \*Lpthread_setspecific(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_lock_global_np 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_lock_global_np(\|)\*O" .iX "global mutex" "locking" .iX "locking a global mutex" .iX "nonreentrant library packages" "calling" .SH NAME .PP \*Lpthread_lock_global_np\*O - Locks the global mutex .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lvoid pthread_lock_global_np(\|); .sE .wH "" .PP .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_lock_global_np(\|)\*O routine locks the global mutex. If the global mutex is currently held by another thread when a thread calls this routine, the thread waits for the global mutex to become available. .PP The thread that has locked the global mutex becomes its current owner and remains the owner until the same thread has unlocked it. This routine returns with the global mutex in the locked state and with the current thread as the global mutex's current owner. .PP Use the global mutex when calling a library package that is not designed to run in a multithreaded environment. (Unless the documentation for a library function specifically states that it is compatible with multithreading, assume that it is not compatible; in other words, assume it is nonreentrant.) .PP The global mutex is one lock. Any code that calls any function that is not known to be reentrant uses the same lock. This prevents dependencies among threads calling library functions and those functions calling other functions, and so on. .PP The global mutex is a recursive mutex. A thread that has locked the global mutex can relock it without deadlocking. (The locking thread must call \*Lpthread_unlock_global_np(\|)\*O as many times as it called this routine to allow another thread to lock the global mutex.) .PP This routine is a new primitive. .br .ne 1.5i .SH RETURN VALUES .PP No value is returned. .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS void pthread_lock_global_np (\|); .oE .cE .wH "" .br .ne 1.0i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_mutexattr_setkind_np(3)\*O, \*Lpthread_mutex_lock(3)\*O, \*Lpthread_mutex_unlock(3)\*O, \*Lpthread_unlock_global_np(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright (c) 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_mutex_destroy 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_mutex_destroy(\|)\*O" .iX "mutex" "deleting" .iX "deleting a mutex" .SH NAME .PP \*Lpthread_mutex_destroy\*O - Deletes a mutex .wH "" .SH "SYNOPSIS" .sS \*L#include \*L .PP \*Lint pthread_mutex_destroy\*L( .nL \*Lpthread_mutex_t *\*Vmutex\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .VL 5m .LI "\*Vmutex\*O" Mutex to be deleted. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_mutex_destroy(\|)\*O routine deletes a mutex and must be called when a mutex object is no longer referenced. The effect of calling this routine is to reclaim storage for the mutex object. .PP It is illegal to delete a mutex that has a current owner (in other words, is locked). .PP The results of this routine are unpredictable if the mutex object specified in the \*Vmutex\*O parameter does not currently exist. .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | l. Return%Error%Description _ 0%%Successful completion. \-1%[\*LEBUSY\*O]%An attempt was made to destroy a mutex that is locked. \-1%[\*LEINVAL\*O]%The value specified by \*Vmutex\*O is invalid. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_mutex_destroy (pthread_mutex_t *mutex); .oE .cE .wH "" .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_mutex_init(3)\*O, \*Lpthread_mutex_lock(3)\*O, \*Lpthread_mutex_trylock(3)\*O, \*Lpthread_mutex_unlock(3)\*O. .wH "" .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_mutex_init 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_mutex_init(\|)\*O" .iX "mutex" "creating" .iX "mutex" "definition of" .iX "creating" "a mutex" .iX "synchronization" "mutex" .SH NAME .PP \*Lpthread_mutex_init\*O - Creates a mutex .wH "" .SH "SYNOPSIS" .sS \*L#include \*L .PP \*Lint pthread_mutex_init\*L( .nL \*Lpthread_mutex_t *\*Vmutex\*L, .nL \*Lpthread_mutexattr_t \*Vattr\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 4m .LI "\*Vmutex\*O" Mutex that is created. .LI "\*Vattr\*O" ...\" Mutex Attributes object that defines the characteristics of the created mutex. If you specify \*Lpthread_mutexattr_default\*O, default attributes are used. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_mutex_init(\|)\*O routine creates a mutex and initializes it to the unlocked state. If the thread that called this routine terminates, the created mutex is not automatically deallocated, because it is considered shared among multiple threads. .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If an error condition occurs, this routine returns \-1, the mutex is not initialized, the contents of \*Vmutex\*O are undefined, and \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .zA "defect,8882,R1.0.3, added EINVAL" .PP .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEAGAIN\*O]%T{ The system lacks the necessary resources to initialize another mutex. T} \-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. \-1%[\*LENOMEM\*O]%Insufficient memory exists to initialize the mutex. .TE .zZ "defect,8882,R1.0.3, added EINVAL" .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_mutex_init (pthread_mutex_t *mutex, pthread_mutexattr_t attr); .oE .cE .wH "" .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_mutexattr_create(3)\*O, \*Lpthread_mutexattr_getkind_np(3)\*O, \*Lpthread_mutexattr_setkind_np(3)\*O, \*Lpthread_mutex_lock(3)\*O, \*Lpthread_mutex_trylock(3)\*O, \*Lpthread_mutex_unlock(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_mutex_lock 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_mutex_lock(\|)\*O" .iX "mutex" "locking" .iX "locking a mutex" .iX "priority inversion" "avoiding" .iX "thread" "waiting for a mutex" .SH NAME .PP \*Lpthread_mutex_lock\*O - Locks an unlocked mutex .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_mutex_lock( .nL \*Lpthread_mutex_t *\*Vmutex\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vmutex\*O" Mutex that is locked. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_mutex_lock(\|)\*O routine locks a mutex. If the mutex is locked when a thread calls this routine, the thread waits for the mutex to become available. .PP The thread that has locked a mutex becomes its current owner and remains the owner until the same thread has unlocked it. This routine returns with the mutex in the locked state and with the current thread as the mutex's current owner. .PP If you specified a fast mutex in a call to \*Lpthread_mutexattr_setkind_np(\|)\*O, .wH "" a deadlock can result .wH "" if the current owner of a mutex calls this routine in an attempt to lock the mutex a second time. If you specified a recursive mutex in a call to \*Lpthread_mutexattr_setkind_np(\|)\*O, the current owner of a mutex can relock the same mutex without blocking. If you specify a nonrecursive mutex in a call to \*Lpthread_mutexattr_setkind_np(\|)\*O, an error is returned and the thread does not block if the current owner of a mutex calls this routine in an attempt to lock the mutex a second time. .PP The preemption of a lower-priority thread that locks a mutex possibly results in the indefinite blocking of higher-priority threads waiting for the same mutex. The execution of the waiting higher-priority threads is blocked for as long as there is a sufficient number of runnable threads of any priority between the lower-priority and higher-priority values. Priority inversion occurs .wH "" when any resource is shared between threads with different priorities. .wH "" .br .ne 1.5i .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vmutex\*O is invalid. \-1%[\*LEDEADLK\*O]%A deadlock condition is detected. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_mutex_lock (pthread_mutex_t *mutex); .oE .cE .wH "" .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_mutexattr_setkind_np(3)\*O, \*Lpthread_mutex_destroy(3)\*O, \*Lpthread_mutex_init(3)\*O, \*Lpthread_mutex_trylock(3)\*O, \*Lpthread_mutex_unlock(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_mutex_trylock 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_mutex_trylock(\|)\*O" .iX "mutex" "locking" .iX "locking a mutex" .SH NAME .PP \*Lpthread_mutex_trylock\*O - Locks a mutex .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_mutex_trylock\*L( .nL \*Lpthread_mutex_t *\*Vmutex\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vmutex\*O" Mutex that is locked. .LE .wH "" .SH "DESCRIPTION" .PP The \*Lpthread_mutex_trylock(\|)\*O routine locks a mutex. If the specified mutex is locked when a thread calls this routine, the calling thread does not wait for the mutex to become available. .PP When a thread calls this routine, an attempt is made to lock the mutex immediately. If the mutex is successfully locked, 1 is returned and the current thread is then the mutex's current owner. .PP If the mutex is locked by another thread when this routine is called, 0 (zero) is returned and the thread does not wait to acquire the lock. .wH "" If a fast mutex is owned by the current thread, 0 is returned. If a recursive mutex is owned by the current thread, 1 is returned and the mutex is relocked. (To unlock a recursive mutex, each call to \*Lpthread_mutex_trylock(\|)\*O must be matched by a call to the \*Lpthread_mutex_unlock(\|)\*O routine.) .wH "" .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .br .ne 1.1i .TS center, tab(%); lb | lb | lb n | l | lw(3.0i). Return%Error%Description _ 1%%Successful completion. 0%%T{ The mutex is locked; therefore, it was not acquired. T} \-1%[\*LEINVAL\*O]%The value specified by \*Vmutex\*O is invalid. .TE .br .wH "" .cS .SH "EXAMPLES" .PP .oS int pthread_mutex_trylock(pthread_mutex_t, *mutex); .oE .wH "" .cE .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_mutexattr_setkind_np(3)\*O, \*Lpthread_mutex_destroy(3)\*O, \*Lpthread_mutex_init(3)\*O, \*Lpthread_mutex_lock(3)\*O, \*Lpthread_mutex_unlock(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_mutex_unlock 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_mutex_unlock(\|)\*O" .iX "mutex" "unlocking" .iX "unlocking a mutex" .SH NAME .PP \*Lpthread_mutex_unlock\*O - Unlocks a mutex .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_mutex_unlock\*L( .nL \*Lpthread_mutex_t *\*Vmutex\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vmutex\*O" Mutex that is unlocked. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_mutex_unlock(\|)\*O routine unlocks a mutex. If no threads are waiting for the mutex, the mutex unlocks with no current owner. If one or more threads are waiting to lock the specified mutex, this routine causes one thread to return from its call to \*Lpthread_mutex_lock(\|)\*O. The scheduling policy is used to determine which thread acquires the mutex. For the \*LSCHED_FIFO\*O and \*L SCHED_RR\*O policies, a blocked thread is chosen in priority order. .PP The results of calling this routine are unpredictable if the mutex specified in \*Vmutex\*O is unlocked. The results of calling this routine are also unpredictable if the mutex specified in \*Vmutex\*O is currently owned by a thread other than the calling thread. .br .ne 1.5i .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vmutex\*O is invalid. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_mutex_unlock (pthread_mutex_t *mutex); .oE .cE .wH "" .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_mutexattr_setkind_np(3)\*O, \*Lpthread_mutex_destroy(3)\*O, \*Lpthread_mutex_init(3)\*O, \*Lpthread_mutex_lock(3)\*O, \*Lpthread_mutex_trylock(3)\*O, \*Lpthread_unlock_global_np(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_mutexattr_create 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_mutexattr_create(\|)\*O" .iX "mutex attributes object" "creating" .iX "creating" "mutex attributes object" .iX "characteristics of created mutex" "specifying" .wH "" .SH NAME .PP \*Lpthread_mutexattr_create\*O - Creates a mutex attributes object .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_mutexattr_create\*L( .nL \*Lpthread_mutexattr_t *\*Vattr\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Mutex attributes object created. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_mutexattr_create(\|)\*O routine creates a mutex attributes object used to specify the attributes of mutexes when they are created. The mutex attributes object is initialized with the default value for all of the attributes defined by a given implementation. .PP When a mutex attributes object is used to create a mutex, the values of the individual attributes determine the characteristics of the new object. Attributes objects act like additional parameters to object creation. Changing individual attributes does not affect any objects that were previously created using the attributes object. .br .ne 2.5i .br .ne 1.5i .SH "RETURN VALUES" .PP The created mutex attributes object is returned to the \*Vattr\*O parameter. .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. \-1%[\*LENOMEM\*O]%T{ Insufficient memory exists to create the mutex attributes object. T} .TE ...\" .wH "" ...\" .cS ...\" .br ...\" .ne 1.5i ...\" .SH "EXAMPLES" ...\" .PP ...\" .oS ...\" int pthread_mutexattr_create (pthread_mutexattr_t *attr); ...\" .oE ...\" .cE ...\" .wH "" .br .ne 1.0i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_create(3)\*O, \*Lpthread_mutexattr_delete(3)\*O, \*Lpthread_mutexattr_getkind_np(3)\*O, \*Lpthread_mutexattr_setkind_np(3)\*O, \*Lpthread_mutex_init(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_mutexattr_delete 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_mutexattr_delete(\|)\*O" .iX "mutex attributes object" "deleting" .iX "deleting" "mutex attributes object" .SH NAME .PP \*Lpthread_mutexattr_delete\*O - Deletes a mutex attributes object .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lint pthread_mutexattr_delete\*L( .nL \*Lpthread_mutexattr_t *\*Vattr\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Mutex attributes object deleted. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_mutexattr_delete(\|)\*O routine deletes a mutex attributes object. Call this routine when a mutex attributes object is no longer referenced by the \*Lpthread_mutexattr_create(\|)\*O routine. .PP This routine gives permission to reclaim storage for the mutex attributes object. Mutexes that were created using this attributes object are not affected by the deletion of the mutex attributes object. .PP The results of calling this routine are unpredictable if the attributes object specified in the \*Vattr\*O parameter does not exist. .br .ne 1.5i .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_mutexattr_delete (pthread_mutexattr_t *attr); .oE .cE .wH "" .br .ne 1.5i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_mutexattr_create(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_mutexattr_getkind_np 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_mutexattr_getkind_np(\|)\*O" .SH NAME .PP \*Lpthread_mutexattr_getkind_np\*O - Obtains the mutex type attribute used when a mutex is created .SH "SYNOPSIS" .wH "" .sS \*L#include .PP \*Lint pthread_mutexattr_getkind_np( .nL pthread_mutexattr_t \*Vattr\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Mutex attributes object whose mutex type is obtained. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_mutexattr_getkind_np(\|)\*O routine obtains the mutex type attribute that is used when a mutex is created. See the \*Lpthread_mutexattr_setkind_np(\|)\*O reference page for information about mutex type attributes. .PP This routine is a new primitive. .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .sp .TS center, tab(%); l | l | l c | l | lw(2.5i). \*LReturn%Error%Description\*O _ \&Mutex type attribute%%Successful completion. \&\-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_mutexattr_getkind_np (pthread_mutexattr_t attr); .oE .cE .wH "" .br .ne 1.5i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_mutexattr_create(3)\*O, \*Lpthread_mutexattr_setkind_np(3)\*O, \*Lpthread_mutex_init(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_mutexattr_setkind_np 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_mutexattr_setkind_np(\|)\*O" .iX "mutex" "fast" .iX "mutex" "recursive" .iX "fast mutex" .iX "recursive mutex" .SH NAME .PP \*Lpthread_mutexattr_setkind_np\*O - Specifies the mutex type attribute .SH "SYNOPSIS" .wH "" .sS \*L#include \*O .PP \*Lint pthread_mutexattr_setkind_np\*L( .nL \*Lpthread_mutexattr_t *\*Vattr\*L, .nL \*Lint \*Vkind\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vattr\*O" Mutex attributes object modified. .LI "\*Vkind\*O" New value for the mutex type attribute. The \*Vkind\*O parameter specifies the type of mutex that is created. Valid values are \*LMUTEX_FAST_NP\*O (default), \*LMUTEX_RECURSIVE_NP\*O, and \*LMUTEX_NONRECURSIVE_NP\*O. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_mutexattr_setkind_np(\|)\*O routine sets the mutex type attribute that is used when a mutex is created. .PP A fast mutex is locked and unlocked in the fastest manner possible. A fast mutex can only be locked (obtained) once. All subsequent calls to \*Lpthread_mutex_lock(\|)\*O cause the calling thread to block until the mutex is freed by the thread that owns it. If the thread that owns the mutex attempts to lock it again, the thread waits for itself to release the mutex (causing a deadlock). .PP A recursive mutex can be locked more than once by the same thread without causing that thread to deadlock. In other words, a single thread can make consecutive calls to \*Lpthread_mutex_lock(\|)\*O without blocking. The thread must then call \*Lpthread_mutex_unlock(\|)\*O the same number of times as it called \*Lpthread_mutex_lock(\|)\*O before another thread can lock the mutex. .PP A nonrecursive mutex is locked only once by a thread, like a fast mutex. If the thread tries to lock the mutex again without first unlocking it, the thread receives an error. Thus, nonrecursive mutexes are more informative than fast mutexes because fast mutexes block in such a case, leaving it up to you to determine why the thread no longer executes. Also, if someone other than the owner tries to unlock a nonrecursive mutex, an error is returned. .PP .wH "" Never use a recursive mutex with condition variables because the implicit unlock performed for a \*Lpthread_cond_wait(\|)\*O or \*Lpthread_cond_timedwait(\|)\*O might not actually release the mutex. In that case, no other thread can satisfy the condition of the predicate. .PP This routine is a new primitive. .wH "" .br .ne 2.2i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vattr\*O is invalid. \-1%[\*LEPERM\*O]%The caller does not have the appropriate privileges. \-1%[\*LERANGE\*O]%One or more parameters supplied have an invalid value. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_mutexattr_setkind_np (pthread_mutexattr_t *attr, int kind); .oE .cE .wH "" .br .ne 1.5i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_mutexattr_create(3)\*O, \*Lpthread_mutexattr_getkind_np(3)\*O, \*Lpthread_mutex_init(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_once 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_once(\|)\*O" .iX "initialization" "one-time" .iX "data structure" "\*Lpthread_once_t\*O" .iX "\*Lpthread_once_t\*O data structure" .SH NAME .PP \*Lpthread_once\*O - Calls an initialization routine executed by one thread, a single time .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_once\*L( .nL \*Lpthread_once_t *\*Vonce_block\*L, .nL \*Lpthread_initroutine_t \*Vinit_routine\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 6m .LI "\*Vonce_block\*O" Address of a record that defines the one-time initialization code. Each one-time initialization routine must have its own unique \*Lpthread_once_t\*O data structure. .LI "\*Vinit_routine\*O" Address of a procedure that performs the initialization. This routine is called only once, regardless of the number of times it and its associated \*Vonce_block\*O are passed to \*Lpthread_once(\|)\*O. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_once(\|)\*O routine calls an initialization routine executed by one thread, a single time. This routine allows you to create your own initialization code that is guaranteed to be run only once, even if called simultaneously by multiple threads or .wH "" multiple times in the same thread. .wH "" .PP For example, a mutex or a thread-specfic data key must be created exactly once. Calling \*Lpthread_once(\|)\*O prevents the code that creates a mutex or thread-specific data from being called by multiple threads. Without this routine, the execution must be serialized so that only one thread performs the initialization. Other threads that reach the same point in the code are delayed until the first thread is finished. .PP This routine initializes the control record if it has not been initialized and then determines if the client one-time initialization routine has executed once. If it has not executed, this routine calls the initialization routine specified in \*Vinit_routine\*O. If the client one-time initialization code has executed once, this routine returns. .PP The \*Lpthread_once_t\*O data structure is a record that allows client initialization operations to guarantee mutual exclusion of access to the initialization routine, and that each initialization routine is executed exactly once. .br .ne 1.0i .PP The client code must declare a variable of type \*Lpthread_once_t\*O to use the client initialization operations. This variable must be initialized using the \*Lpthread_once_init\*O macro, as follows: .oS static pthread_once_t myOnceBlock = pthread_once_init; .oE .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); l | l | l n | l | lw(3.0i). \*LReturn%Error%Description\*O _ \-1%[\*LEINVAL\*O]%The value specified by a parameter is invalid. _ 0%%Successful completion. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS #include .wH ""(pthread.h) static pthread_once_t make_my_mutex = pthread_once_init; static pthread_mutex_t my_mutex; void initialize_mutex (\|) { pthread_mutex_init (&my_mutex, &pthread_mutexattr_default); } pthread_once (&make_my_mutex, initialize_mutex); .oE .cE .wH "" .wH "" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_self 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_self(\|)\*O" .iX "thread" "obtaining identifier of" .SH NAME .PP \*Lpthread_self\*O - Obtains the identifier of the current thread .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lpthread_t pthread_self(\|)\*L; .sE .wH "" .PP .wH "" .SH "DESCRIPTION" .PP The \*Lpthread_self(\|)\*O routine allows a thread to obtain its own identifier. For example, this identifier allows a thread to set its own priority. .PP This value becomes meaningless when the thread object is deleted; that is, when the thread terminates its execution and \*Lpthread_detach(\|)\*O is called. .SH "RETURN VALUES" .PP Returns the identifier of the calling thread to \*Lpthread_t\*O. .wH "" .cS .SH "EXAMPLES" .PP .oS pthread_t pthread_self (\|); .oE .cE .wH "" .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_create(3)\*O, \*Lpthread_setprio(3)\*O, \*Lpthread_setscheduler(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_setasynccancel 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_setasynccancel(\|)\*O" .iX "cancel" "enabling and disabling asynchronous delivery of" .iX "cancel" "asynchronous delivery and exception handlers" .iX "cancelability" "asynchronous" .iX "enabling asynchronous delivery of cancels" .iX "disabling asynchronous delivery of cancels" .iX "delivery of cancels" "enabling and disabling asynchronous delivery of" .SH NAME .PP \*Lpthread_setasynccancel\*O - Enables or disables the current thread's asynchronous cancelability .SH "SYNOPSIS" .wH "" .sS \*L#include \*Lint pthread_setasynccancel( .nL int \*Vstate\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vstate\*O" State of asynchronous cancelability set for the calling thread. On return, receives the prior state of asynchronous cancelability. Valid values are as follows: .VL 10m .LI "\*LCANCEL_ON\*O" Asynchronous cancelability is enabled. .LI "\*LCANCEL_OFF\*O" Asynchronous cancelability is disabled. .LE .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_setasynccancel(\|)\*O routine enables or disables the current thread's asynchronous cancelability and returns the previous asynchronous cancelability state. .PP When general cancelability is set to \*LCANCEL_OFF\*O, a cancel cannot be delivered to the thread, even if a cancelable routine is called or asynchronous cancelability is enabled. When general cancelability is set to \*LCANCEL_ON\*O, cancelability depends on the state of the thread's asynchronous cancelability. .PP When general cancelability is set to \*LCANCEL_ON\*O and asynchronous cancelability is set to \*LCANCEL_OFF\*O, the thread can only receive a cancel at specific cancellation points (for example, condition waits, thread joins, and calls to the \*Lpthread_testcancel(\|)\*O routine). If both general cancelability and asynchronous cancelability are set to \*LCANCEL_ON\*O, the thread can be canceled at any point in its execution. .PP When a thread is created, the default asynchronous cancelability state is \*LCANCEL_OFF\*O. .PP .wH "" If you call this routine to enable asynchronous cancels, call it in a region of code where asynchronous delivery of cancels is disabled by a previous call to this routine. Do not call threads routines in regions of code where asynchronous delivery of cancels is enabled. .wH "" The previous state of asynchronous delivery can be restored later by another call to this routine. .br .ne 2.3i .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" .zA "def,8483,R1.0.3,corrected paragraph" ...\" On successful completion, the previous state of asynchronous cancelability is returned. If the function fails, -1 is returned. Following are the possible return values and the possible corresponding values (if any) for \*Lerrno\*O: ...\" ...\" If the function fails, \*Lerrno\*O may be set to one of the ...\" following values: ...\" .zZ "def,8483,R1.0.3,corrected paragraph" .zZ "defect,7040,R1.0.2, corrected paragraph" .sp .TS center, tab(%); l | l | l c | l | lw(3.0i). \*LReturn%Error%Description\*O _ \*LCANCEL_ON\0\*O%%Asynchronous cancelability was on. \*LCANCEL_OFF\*O%%Asynchronous cancelability was off. \&\-1%[\*LEINVAL\*O]%T{ The specified state is not \*LCANCEL_ON\*O or \*LCANCEL_OFF\*O. T} .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_setasynccancel (int *state); .oE .cE .wH "" .br .ne 1.0i .SH "RELATED INFORMATION" .ad l Functions: \*Lpthread_cancel(3)\*O, \*Lpthread_setcancel(3)\*O, \*Lpthread_testcancel(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_setcancel 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_setcancel(\|)\*O" .iX "cancel" "enabling and disabling delivery of" .iX "cancel" "possible dangers of disabling" .iX "cancel" "obtaining non-cancelable versions of cancelable routines" .iX "delivery of cancels" "enabling and disabling" .iX "cancelability" "general" .SH NAME .PP \*Lpthread_setcancel\*O - Enables or disables the current thread's general cancelability .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_setcancel\*L( .nL \*Lint \*Vstate\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vstate\*O" State of general cancelability set for the calling thread. On return, receives the prior state of general cancelability. Valid values are as follows: .VL 8m .LI "\*LCANCEL_ON\*O" General cancelability is enabled. .LI "\*LCANCEL_OFF\*O" General cancelability is disabled. .LE .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" The \*Lpthread_setcancel(\|)\*O routine enables or disables the current thread's general cancelability and returns the previous general cancelability state. .PP When general cancelability is set to \*LCANCEL_OFF\*O, a cancel cannot be delivered to the thread, even if a cancelable routine is called or asynchronous cancelability is enabled. .PP When a thread is created, the default general cancelability state is \*LCANCEL_ON\*O. .SS "Possible Dangers of Disabling Cancelability" .PP The most important use of cancels is to ensure that indefinite wait operations are terminated. For example, a thread waiting on some network connection, which may take days to respond (or may never respond), is normally made cancelable. .PP However, when cancelability is disabled, no routine is cancelable. Waits must be completed normally before a cancel can be delivered. As a result, the program stops working and the user is unable to cancel the operation. .PP When disabling cancelability, be sure that no long waits can occur or that it is necessary for other reasons to defer cancels around that particular region of code. .br .ne 1.5i .SH "RETURN VALUES" .zA "defect,7040,R1.0.2, corrected paragraph" .zA "def,8483,R1.0.3,corrected paragraph" ...\" On successful completion, the previous state of general cancelability is returned. If the function fails, -1 is returned. Following are the possible return values and the possible corresponding values (if any) for \*Lerrno\*O: ...\" ...\" If the function fails, \*Lerrno\*O may be set to one of the ...\" following values: ...\" .zZ "def,8483,R1.0.3,corrected paragraph" .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb c | l | lw(3.0i). Return%Error%Description _ \*LCANCEL_ON\*O%%Asynchronous cancelability was on. \*LCANCEL_OFF\*O%%Asynchronous cancelability was off. \-1%[\*LEINVAL\*O]%T{ The specified state is not \*LCANCEL_ON\*O or \*LCANCEL_OFF\*O. T} .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_setcancel (int *state); .oE .cE .wH "" .br .ne 1.5i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_cancel(3)\*O, \*Lpthread_setasynccancel(3)\*O, \*Lpthread_testcancel(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_setprio 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_setprio(\|)\*O" .iX "thread" "setting current priority of" .iX "priority" "setting for thread" .SH NAME .PP \*Lpthread_setprio\*O - Changes the current priority of a thread .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_setprio\*L( .nL \*Lpthread_t \*Vthread\*L, .nL \*Lint \*Vpriority\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 5m .LI "\*Vthread\*O" Thread whose priority is changed. .LI "\*Vpriority\*O" New priority value of the thread specified in \*Vthread\*O. The priority value depends on scheduling policy. Valid values fall within one of the following ranges: .ad l .ML .LI \*LPRI_OTHER_MIN <= \*Vpriority <= \*LPRI_OTHER_MAX\*O .LI \*LPRI_FIFO_MIN <= \*Vpriority <= \*LPRI_FIFO_MAX\*O .LI \*LPRI_RR_MIN <= \*Vpriority <= \*LPRI_RR_MAX\*O .LI \*LPRI_FG_MIN_NP <= \*Vpriority <= \*LPRI_FG_MAX_NP\*O .LI \*LPRI_BG_MIN_NP <= \*Vpriority <= \*LPRI_BG_MAX_NP\*O .LE .ad b .LE .PP If you create a new thread without specifying a threads attributes object that contains a changed priority attribute, the default priority of the newly created thread is the midpoint between \*LPRI_OTHER_MIN\*O and \*LPRI_OTHER_MAX\*O (the midpoint between the minimum and the maximum for the \*LSCHED_OTHER\*O policy). .PP When you call this routine to specify a minimum or maximum priority, use the appropriate symbol; for example, \*LPRI_FIFO_MIN\*O or \*LPRI_FIFO_MAX\*O. To specify a value between the minimum and maximum, use an appropriate arithmetic expression. For example, to specify a priority midway between the minimum and maximum for the Round Robin scheduling policy, specify the following concept using your programming language's syntax: .zA "def,8410,R1.0.3,corrected formula" .oS pri_rr_mid = (PRI_RR_MIN + PRI_RR_MAX + 1)/2 .oE .zZ "def,8410,R1.0.3,corrected formula" .PP If your expression results in a value outside the range of minimum to maximum, an error results when you use it. .wH "" .br .ne 1.5i .SH "DESCRIPTION" The \*Lpthread_setprio(\|)\*O routine changes the current priority of a thread. A thread can change its own priority using the identifier returned by \*Lpthread_self(\|)\*O. .PP Changing the priority of a thread can cause it to start executing or be preempted by another thread. The effect of setting different priority values depends on the scheduling priority assigned to the thread. The initial scheduling priority is set by calling the \*Lpthread_attr_setprio(\|)\*O routine. .PP Note that \*Lpthread_attr_setprio(\|)\*O sets the priority attribute that is used to establish the priority of a new thread when it is created. However, \*Lpthread_setprio(\|)\*O changes the priority of an existing thread. .br .ne 3.5i .SH "RETURN VALUES" .PP If successful, this routine returns the previous priority. .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb c | l | lw(2.5i). Return%Error%Description _ \&Previous priority%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vthread\*O is invalid. \-1%[\*LENOTSUP\*O]%T{ An attempt is made to set the policy to an unsupported value. T} \-1%[\*LESRCH\*O]%T{ The value specified by \*Vthread\*O does not refer to an existing thread. T} \-1%[\*LEPERM\*O]%T{ The caller does not have the appropriate privileges to set the priority of the specified thread. T} .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_setprio (pthread_t *thread, int priority); .oE .cE .wH "" .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_setprio(3)\*O, \*Lpthread_attr_setsched(3)\*O, \*Lpthread_create(3)\*O, \*Lpthread_self(3)\*O, \*Lpthread_setscheduler(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_setscheduler 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_setscheduler(\|)\*O" .iX "thread" "setting current scheduling policy and priority of" .iX "scheduling policy" "setting for thread" .iX "priority" "setting for thread" .SH NAME .PP \*Lpthread_setscheduler\*O - Changes the current scheduling policy and priority of a thread .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_setscheduler\*L( .nL \*Lpthread_t \*Vthread\*L, .nL \*Lint \*Vscheduler\*L, .nL \*Lint \*Vpriority\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .PP .VL 4.5m .LI "\*Vthread\*O" Thread whose scheduling policy is to be changed. .LI "\*Vscheduler\*O" New scheduling policy value for the thread specified in \*Vthread\*O. Valid values are as follows: .VL 9m .LI "\*LSCHED_FIFO\*O" (First In, First Out) The highest-priority thread runs until it blocks. If there is more than one thread with the same priority, and that priority is the highest among other threads, the first thread to begin running continues until it blocks. .LI "\*LSCHED_RR\*O" (Round Robin) The highest-priority thread runs until it blocks; however, threads of equal priority, if that priority is the highest among other threads, are timesliced. Timeslicing is a process in which threads alternate using available processors. .LI "\*LSCHED_OTHER\*O" (Default) All threads are timesliced. \*LSCHED_OTHER\*O ensures that all threads, regardless of priority, receive some scheduling, and thus no thread is completely denied execution time. (However, \*LSCHED_OTHER\*O threads can be denied execution time by \*LSCHED_FIFO\*O or \*LSCHED_RR\*O threads.) .LI "\*LSCHED_FG_NP\*O" (Foreground) Same as \*LSCHED_OTHER\*O. Threads are timesliced and priorities can be modified dynamically by the scheduler to ensure fairness. .LI "\*LSCHED_BG_NP\*O" (Background) Like \*LSCHED_OTHER\*O, ensures that all threads, regardless of priority, receive some scheduling. However, \*LSCHED_BG_NP\*O can be denied execution by any of the other scheduling policies. .LE .LI "\*Vpriority\*O" New priority value of the thread specified in \*Vthread\*O. The priority attribute depends on scheduling policy. Valid values fall within one of the following ranges: .in -2m .ad l .ML .LI \*LPRI_OTHER_MIN <= \*Vpriority <= \*LPRI_OTHER_MAX\*O .LI \*LPRI_FIFO_MIN <= \*Vpriority <= \*LPRI_FIFO_MAX\*O .LI \*LPRI_RR_MIN <= \*Vpriority <= \*LPRI_RR_MAX\*O .LI \*LPRI_FG_MIN_NP <= \*Vpriority <= \*LPRI_FG_MAX_NP\*O .LI \*LPRI_BG_MIN_NP <= \*Vpriority <= \*LPRI_BG_MAX_NP\*O .LE .ad b .LE .PP If you create a new thread without specifying a threads attributes object that contains a changed priority attribute, the default priority of the newly created thread is the midpoint between \*LPRI_OTHER_MIN\*O and \*LPRI_OTHER_MAX\*O (the midpoint between the minimum and the maximum for the \*LSCHED_OTHER\*O policy). .PP When you call this routine to specify a minimum or maximum priority, use the appropriate symbol; for example, \*LPRI_FIFO_MIN\*O or \*LPRI_FIFO_MAX\*O. To specify a value between the minimum and maximum, use an appropriate arithmetic expression. For example, to specify a priority midway between the minimum and maximum for the Round Robin scheduling policy, specify the following concept using your programming language's syntax: .oS pri_rr_mid = (PRI_RR_MIN + PRI_RR_MAX)/2 .oE .PP If your expression results in a value outside the range of minimum to maximum, an error results when you use it. .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_setscheduler(\|)\*O routine changes the current scheduling policy and priority of a thread. Call this routine to change both the priority and scheduling policy of a thread at the same time. To change only the priority, call the \*Lpthread_setprio(\|)\*O routine. .PP A thread changes its own scheduling policy and priority .wH "" by using the identifier returned by \*Lpthread_self(\|)\*O. .wH "" Changing the scheduling policy or priority, or both, of a thread can cause it to start executing or to be preempted by another thread. .PP This routine differs from \*Lpthread_attr_setprio(\|)\*O and \*Lpthread_attr_setsched(\|)\*O because those routines set the priority and scheduling policy attributes that are used to establish the priority and scheduling policy of a new thread when it is created. This routine, however, changes the priority and scheduling policy of an existing thread. .br .ne 3.6i .SH "RETURN VALUES" .zA "def,8483,R1.0.3,corrected paragraph" .zA "defect,7040,R1.0.2, corrected paragraph" ...\" If successful, the previous scheduling policy value is returned. If the function fails, \*Lerrno\*O may be set to one of the following values: ...\" .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(3.0i). Return%Error%Description _ Previous policy%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vthread\*O is invalid. \-1%[\*LENOTSUP\*O]%T{ An attempt is made to set the policy to an unsupported value. T} \-1%[\*LESRCH\*O]%T{ The value specified by \*Vthread\*O does not refer to an existing thread. T} \-1%[\*LEPERM\*O]%T{ The caller does not have the appropriate privileges to set the scheduling policy of the specified thread. T} .TE .zZ "def,8483,R1.0.3,corrected paragraph" .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_setscheduler (pthread_t *thread, int scheduler, int priority); .oE .cE .wH "" .br .ne 1.5i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_setprio(3)\*O, \*Lpthread_attr_setsched(3)\*O, \*Lpthread_create(3)\*O, \*Lpthread_self(3)\*O, \*Lpthread_setprio(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright (c) 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_setspecific 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_setspecific(\|)\*O" .iX "thread-specific data" "setting" .iX "context" "setting" .iX "key value" "setting thread-specific data for" .SH NAME .PP \*Lpthread_setspecific\*O - Sets the thread-specific data associated with the specified key for the current thread .wH "" .SH "SYNOPSIS" .sS \*L#include \*L .PP \*Lint pthread_setspecific\*L( .nL \*Lpthread_key_t \*Vkey\*L, .nL \*Lpthread_addr_t \*Vvalue\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .VL 5m .LI "\*Vkey\*O" Context key value that uniquely identifies the context value specified in \*Vvalue\*O. This key value must have been obtained from \*Lpthread_keycreate(\|)\*O. .LI "\*Vvalue\*O" Address containing data to be associated with the specified key for the current thread; this is the thread-specific data. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_setspecific(\|)\*O routine sets the thread-specific data associated with the specified key for the current thread. If a value has already been defined for the key in this thread, the new value is substituted for it. .PP Different threads can bind different values to the same key. These values are typically pointers to blocks of dynamically allocated memory that are reserved for use by the calling thread. .br .ne 1.5i .SH "RETURN VALUES" .PP .zA "def,8483,R1.0.3,corrected paragraph" .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, -1 is returned, and \*Lerrno\*O may be set to the following value: .zZ "defect,7040,R1.0.2, corrected paragraph" .PP .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ \-1%[\*LEINVAL\*O]%The key value is invalid. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS int pthread_setspecific (pthread_key_t key, pthread_addr_t value); .oE .zZ "def,8483,R1.0.3,corrected paragraph" .cE .wH "" .br .ne 1.0i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_getspecific(3)\*O, \*Lpthread_keycreate(3)\*O. .wH "" .ad b ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" Copyright (c) 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_signal_to_cancel_np 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_signal_to_cancel_np(\|)\*O" .iX "thread" "canceling if signal is received by process" .SH NAME .PP \*Lpthread_signal_to_cancel_np\*O - Cancels the specified thread .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lint pthread_signal_to_cancel_np\*L( .nL \*Lsigset_t *\*Vsigset\*L, .nL \*Lpthread_t *\*Vthread\*L); .sE .wH "" .br .ne 1.5i .SH "PARAMETERS" .VL 5m .LI "\*Vsigset\*O" Signal mask containing a list of signals that, when received by the process, cancels the specified thread. .LI "\*Vthread\*O" Thread canceled if a valid signal is received by the process. .LE .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_signal_to_cancel_np(\|)\*O routine requests that the specified thread be canceled if one of the signals specified in the signal mask is received by the process. The set of legal signals is the same as that for the \*Lsigwait(\|)\*O service. The \*Vsigset\*O parameter is not validated. If it is invalid, this routine will return successfully but neither the specified thread nor the previously specified thread will be canceled if a signal occurs. .PP Note that the address of the specified thread is saved in a per-process global variable. Therefore, any subsequent call to this routine by your application or any library function will supercede the thread specified in the previous call, and that thread will not be canceled if one of the signals specified for it is delivered to the process. In other words, take care when you call this routine; if another thread calls it after you do, the expected result of this routine will not occur. .br .ne 2.5i .SH "RETURN VALUES" .PP .zA "defect,7040,R1.0.2, corrected paragraph" If the function fails, \*Lerrno\*O may be set to one of the following values: .zZ "defect,7040,R1.0.2, corrected paragraph" .br .ne 1.0 .TS center, tab(%); lb | lb | lb n | l | lw(2.5i). Return%Error%Description _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by \*Vthread\*O is invalid. .TE .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS extern int pthread_signal_to_cancel_np ( sigset_t *sigset, pthread_t *thread); .oE .cE .wH "" .br .ne .75i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_cancel(3)\*O. .wH "" .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_testcancel 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_testcancel(\|)\*O" .iX "cancel" "requesting delivery of" .iX "delivery of cancel" "requesting" .SH NAME .PP \*Lpthread_testcancel\*O - Requests delivery of a pending cancel to the current thread .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lvoid pthread_testcancel\*L(\|); .sE .wH "" .PP .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_testcancel(\|)\*O routine requests delivery of a pending cancel to the current thread. The cancel is delivered only if a cancel is pending for the current thread and general cancel delivery is not currently disabled. (A thread disables delivery of cancels to itself by calling the \*Lpthread_setcancel(\|)\*O routine.) .PP This routine, when called within very long loops, ensures that a pending cancel is noticed within a reasonable amount of time. .br .ne 1.5i .SH "RETURN VALUES" .PP No value is returned. .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS void pthread_testcancel (\|); .oE .cE .wH "" .br .ne 1.5i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_cancel(3)\*O, \*Lpthread_setasynccancel(3)\*O, \*Lpthread_setcancel(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_unlock_global_np 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_unlock_global_np(\|)\*O" .iX "global mutex" "unlocking" .iX "unlocking a global mutex" .SH NAME .PP \*Lpthread_unlock_global_np\*O - Unlocks a global mutex .wH "" .SH "SYNOPSIS" .sS \*L#include .PP \*Lvoid pthread_unlock_global_np\*L(\|); .sE .wH "" .PP .wH "" .SH "DESCRIPTION" .PP .wH "" The \*Lpthread_unlock_global_np(\|)\*O routine unlocks the global mutex when each call to \*Lpthread_lock_global_np(\|)\*O is matched by a call to this routine. For example, if you called \*Lpthread_lock_global_np(\|)\*O three times, \*Lpthread_unlock_global_np(\|)\*O unlocks the global mutex when you call it the third time. .wH "" If no threads are waiting for the global mutex, it becomes unlocked with no current owner. If one or more threads are waiting to lock the global mutex, one thread returns from its call to \*Lpthread_lock_global_np(\|)\*O. The scheduling policy is used to determine which thread acquires the global mutex. For the policies \*LSCHED_FIFO\*O and \*LSCHED_RR\*O, a blocked thread is chosen in priority order. .PP The results of calling this routine are unpredictable if the global mutex is already unlocked. The results of calling this routine are also unpredictable if the global mutex is owned by a thread other than the calling thread. .PP This routine is a new primitive. .SH "RETURN VALUES" .PP No value is returned. .wH "" .cS .SH "EXAMPLES" .PP .oS void pthread_unlock_global_np (\|); .oE .cE .wH "" .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_lock_global_np(3)\*O, \*Lpthread_mutexattr_setkind_np(3)\*O, \*Lpthread_mutex_lock(3)\*O, \*Lpthread_mutex_unlock(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH pthread_yield 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lpthread_yield(\|)\*O" .iX "thread" "releasing processor" .iX "thread" "yielding processor to another thread" .iX "yielding to another thread" .iX "processor" "causing thread to release control of" .SH NAME .PP \*Lpthread_yield\*O - Notifies the scheduler that the current thread is willing to release its processor .wH "" .SH "SYNOPSIS" .sS \*L#include \*L .PP \*Lvoid pthread_yield\*L(\|); .sE .wH "" .PP .wH "" .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lpthread_yield(\|)\*O routine notifies the scheduler that the current thread is willing to release its processor to other threads of the same priority. (A thread releases its processor to a thread of a higher priority without calling this routine.) .PP If the current thread's scheduling policy (as specified in a call to the \*Lpthread_attr_setsched(\|)\*O or \*Lpthread_setscheduler(\|)\*O routine) is \*LSCHED_FIFO\*O or \*LSCHED_RR\*O, this routine yields the processor to other threads of the same or a higher priority. If no threads of the same priority are ready to execute, the thread continues. .PP This routine allows knowledge of the details of an application to be used to increase fairness. It increases fairness of access to the processor by removing the current thread from the processor. It also increases fairness of access to shared resources by removing the current thread from the processor as soon as it is finished with the resource. .PP Call this routine when a thread is executing code that denies access to other threads on a uniprocessor if the scheduling policy is \*LSCHED_FIFO\*O. .PP Use \*Lpthread_yield(\|)\*O carefully because misuse causes unnecessary context switching, which increases overhead without increasing fairness. For example, it is counterproductive for a thread to yield while it has a needed resource locked. .br .ne 1.5i .SH "RETURN VALUES" .PP No value is returned. .wH "" .cS .br .ne 1.5i .SH "EXAMPLES" .PP .oS void pthread_yield (\|); .oE .cE .wH "" .br .ne 1.0i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_attr_setsched(3)\*O, \*Lpthread_setscheduler(3)\*O. .wH "" .ad b .\" $Header: ptsname.3c,v 72.4 94/09/21 14:03:54 ssa Exp $ .TA p .TH ptsname 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ptsname, ptsname_r \- get the pathname of a slave pty (pseudo-terminal) .SH SYNOPSIS .C "char * ptsname (int fildes);" .PP .C "char * ptsname_r (int fildes, char *slavename, int len);" .SS Remarks: .C ptsname() and .C ptsname_r() support STREAMS pty (see .IR ptm (7) and .IR pts (7)), and non-STREAMS pty (see .IR pty (7)) which have different device naming conventions. Notice that the STREAMS pty, being an optional feature, is supported only when it is installed on the system. .PP .C ptsname() and .C ptsname_r() are useful only on systems that follow the .IR insf (1M) naming conventions for pty (STREAMS and non-STREAMS). .SH DESCRIPTION The passed parameter, .IR fildes , is a file descriptor of an opened master pty. .C ptsname() generates the name of the slave pty corresponding to this master pty. This means that their minor numbers will be identical. .PP .C ptsname_r() is the reentrant version of the .C ptsname() function. The passed parameter, .IR slavename , is a pointer to a character array for the resulting null-terminated pathname of the slave pty. The passed parameter, .IR len , indicates the length of this character array which must be at least 32 bytes long. .SH RETURN VALUE Upon successful completion, .C ptsname() returns a string containing the full path name of a slave pty. Otherwise, a NULL pointer is returned. The return value is pointed to static data area which is overwritten with each call to .CR ptsname() , so it should be copied if it is to be saved. .PP Upon successful completion, .C ptsname_r() stores the resulting slave name in the character array pointed to by the .IR slavename parameter, and returns a value of 0 (zero). Otherwise, it returns a value of -1. .SH ERRORS .C ptsname() fails and returns a .SM NULL pointer under the following conditions: .RS .TP 3 \(bu File descriptor does not refer to an open master pty. .TP \(bu Request falls outside pty name-space. .TP \(bu Pty device naming conventions have not been followed. .TP \(bu .C ptsname() failed to find a match. .RE .C ptsname_r() also fails under the above-mentioned conditions but instead it returns a -1 and sets .C errno to ENXIO. .C ptsname_r() returns a -1 and sets .C errno to ERANGE if the .C slavename parameter is invalid or the .C len parameter is too small, .SH EXAMPLES The following example shows how .C ptsname() is typically used for non-STREAMS pty to obtain the pathname of the slave pty corresponding to a master pty obtained through a pty clone open. .nf .IP .C int fd_master; .C char *path; \h'.3i'.\|.\|. .IP " " 10 .C "fd_master = open(""/dev/ptym/clone"", O_RDONLY);" .C "path = ptsname(fd_master);" .fi .PP The following example shows how .C ptsname() is typically used on obtaining the pathname of the STREAMS slave pty corresponding to a STREAMS master pty. .nf .IP .C int fd_master, fd_slave; .C char *slave; \h'.3i'.\|.\|. .IP " " 10 .C "fd_master = open(""/dev/ptmx"", O_RDWR);" .C "grantpt(fd_master);" .C "unlockpt(fd_master);" .C "slave = ptsname(fd_master);" .C "fd_slave = open(slave, O_RDWR);" .C "ioctl(fd_slave, I_PUSH, ""ptem"");" .C "ioctl(fd_slave, I_PUSH, ""ldterm"");" .fi .SH AUTHOR .C ptsname() and .C ptsname_r() were developed by HP and OSF. .SH SEE ALSO insf(1M), devnm(3), pty(7), grantpt(3C), unlockpt(3C), ptm(7), pts(7), ptem(7), ldterm(7). .\" .\" toc@\f3ptsname(3C)\f1:\0\0\f4ptsname()\f1, \0\f4ptsname_r()\f1@@@get the name of a slave pty .\" toc@\f4ptsname_r()\f1:\0\0get the name of a slave pty@@@\f1see \f3ptsname(3C)\f1 .\" .\" index@\f4ptsname()\f1 \- get the name of a slave pty@@@\f3ptsname(3C)\f1 .\" index@get the name of a slave pty@@@\f3ptsname(3C)\f1 .\" index@name of a slave pty, get the@@@\f3ptsname(3C)\f1 .\" index@slave pty, get the name of a@@@\f3ptsname(3C)\f1 .\" index@pty, get the name of a slave@@@\f3ptsname(3C)\f1 .\" index@STREAMS pty, get the name of a slave@@@\f3ptsname(3C)\f1 .\" index@\f4ptsname_r()\f1 \- get the name of a slave pty@@@\f3ptsname(3C)\f1 .\" .\" links@ptsname.3c ptsname_r.3c .\" .\" fileset_database@ptsname.3c PROGRAMING-MAN .\" $Header: ptsname.3c,v 72.4 94/09/21 14:03:54 ssa Exp $ .TA p .TH ptsname 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ptsname, ptsname_r \- get the pathname of a slave pty (pseudo-terminal) .SH SYNOPSIS .C "char * ptsname (int fildes);" .PP .C "char * ptsname_r (int fildes, char *slavename, int len);" .SS Remarks: .C ptsname() and .C ptsname_r() support STREAMS pty (see .IR ptm (7) and .IR pts (7)), and non-STREAMS pty (see .IR pty (7)) which have different device naming conventions. Notice that the STREAMS pty, being an optional feature, is supported only when it is installed on the system. .PP .C ptsname() and .C ptsname_r() are useful only on systems that follow the .IR insf (1M) naming conventions for pty (STREAMS and non-STREAMS). .SH DESCRIPTION The passed parameter, .IR fildes , is a file descriptor of an opened master pty. .C ptsname() generates the name of the slave pty corresponding to this master pty. This means that their minor numbers will be identical. .PP .C ptsname_r() is the reentrant version of the .C ptsname() function. The passed parameter, .IR slavename , is a pointer to a character array for the resulting null-terminated pathname of the slave pty. The passed parameter, .IR len , indicates the length of this character array which must be at least 32 bytes long. .SH RETURN VALUE Upon successful completion, .C ptsname() returns a string containing the full path name of a slave pty. Otherwise, a NULL pointer is returned. The return value is pointed to static data area which is overwritten with each call to .CR ptsname() , so it should be copied if it is to be saved. .PP Upon successful completion, .C ptsname_r() stores the resulting slave name in the character array pointed to by the .IR slavename parameter, and returns a value of 0 (zero). Otherwise, it returns a value of -1. .SH ERRORS .C ptsname() fails and returns a .SM NULL pointer under the following conditions: .RS .TP 3 \(bu File descriptor does not refer to an open master pty. .TP \(bu Request falls outside pty name-space. .TP \(bu Pty device naming conventions have not been followed. .TP \(bu .C ptsname() failed to find a match. .RE .C ptsname_r() also fails under the above-mentioned conditions but instead it returns a -1 and sets .C errno to ENXIO. .C ptsname_r() returns a -1 and sets .C errno to ERANGE if the .C slavename parameter is invalid or the .C len parameter is too small, .SH EXAMPLES The following example shows how .C ptsname() is typically used for non-STREAMS pty to obtain the pathname of the slave pty corresponding to a master pty obtained through a pty clone open. .nf .IP .C int fd_master; .C char *path; \h'.3i'.\|.\|. .IP " " 10 .C "fd_master = open(""/dev/ptym/clone"", O_RDONLY);" .C "path = ptsname(fd_master);" .fi .PP The following example shows how .C ptsname() is typically used on obtaining the pathname of the STREAMS slave pty corresponding to a STREAMS master pty. .nf .IP .C int fd_master, fd_slave; .C char *slave; \h'.3i'.\|.\|. .IP " " 10 .C "fd_master = open(""/dev/ptmx"", O_RDWR);" .C "grantpt(fd_master);" .C "unlockpt(fd_master);" .C "slave = ptsname(fd_master);" .C "fd_slave = open(slave, O_RDWR);" .C "ioctl(fd_slave, I_PUSH, ""ptem"");" .C "ioctl(fd_slave, I_PUSH, ""ldterm"");" .fi .SH AUTHOR .C ptsname() and .C ptsname_r() were developed by HP and OSF. .SH SEE ALSO insf(1M), devnm(3), pty(7), grantpt(3C), unlockpt(3C), ptm(7), pts(7), ptem(7), ldterm(7). .\" .\" toc@\f3ptsname(3C)\f1:\0\0\f4ptsname()\f1, \0\f4ptsname_r()\f1@@@get the name of a slave pty .\" toc@\f4ptsname_r()\f1:\0\0get the name of a slave pty@@@\f1see \f3ptsname(3C)\f1 .\" .\" index@\f4ptsname()\f1 \- get the name of a slave pty@@@\f3ptsname(3C)\f1 .\" index@get the name of a slave pty@@@\f3ptsname(3C)\f1 .\" index@name of a slave pty, get the@@@\f3ptsname(3C)\f1 .\" index@slave pty, get the name of a@@@\f3ptsname(3C)\f1 .\" index@pty, get the name of a slave@@@\f3ptsname(3C)\f1 .\" index@STREAMS pty, get the name of a slave@@@\f3ptsname(3C)\f1 .\" index@\f4ptsname_r()\f1 \- get the name of a slave pty@@@\f3ptsname(3C)\f1 .\" .\" links@ptsname.3c ptsname_r.3c .\" .\" fileset_database@ptsname.3c PROGRAMING-MAN .\" $Header: publickey.3r,v 72.2 94/08/25 12:42:38 ssa Exp $ .TA p .TH publickey 3R .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME publickey, getpublickey, getsecretkey \- get public or secret key .SH SYNOPSIS .C "#include " .PP .C "#include " .PP .C "getpublickey (netname, publickey)" .PP .C "char netname[MAXNETNAMELEN+1];" .PP .C "char publickey[HEXKEYBYTES+1];" .PP .C "getsecretkey (netname, secretkey, passwd)" .PP .C "char netname[MAXNETNAMELEN+1];" .PP .C "char secretkey[HEXKEYBYTES+1];" .PP .C "char *passwd;" .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These routines are used to get public and secret keys from the NIS .IR publickey (4) database. .PP .CR getsecretkey() has an extra argument, .IR passwd , which is used to decrypt the encrypted secret key stored in the .IR publickey (4) database. .PP Both routines return 1 if they are successful in finding the key; otherwise, these routines return 0. .PP The keys are returned as NULL-terminated, hexadecimal strings. .PP If the password supplied to .CR getsecretkey() fails to decrypt the secret key, the routine will return 1 but the secretkey argument will be a NULL string. .SH AUTHOR The .CR publickey routines were developed by Sun Microsystems, Inc. .SH SEE ALSO publickey(4). .\" .\" index@\f4publickey()\f1, \f4getpublickey()\f1, \f4getsecretkey()\f1 \- get public and secret keys@@@\f3publickey(3R)\f1 .\" index@\f4getpublickey()\f1, \f4publickey()\f1, \f4getsecretkey()\f1 \- get public and secret keys@@@\f3publickey(3R)\f1 .\" index@\f4getsecretkey()\f1, \f4publickey()\f1, \f4getpublickey()\f1 \- get public and secret keys@@@\f3publickey(3R)\f1 .\" .\" index@\f1get, public and secret keys@@@\f3publickey(3R)\f1 .\" index@\f1public keys, get@@@\f3getpublickey(3R)\f1 .\" index@\f1secret keys, get@@@\f3getsecretkey(3R)\f1 .\" .\" toc@\f3publickey(3R)\f1:\0\0\f4publickey()\f1, \f4getpublickey()\f1, \f4getsecretkey\f1@@@get public and secret keys .\" toc@\f4getpublickey()\f1:\0\0get public and secret keys@@@see \f3publickey(3R)\f1 .\" toc@\f4getsecretkey()\f1:\0\0get public and secret keys@@@see \f3publickey(3R)\f1 .\" .\" links@publickey.3r getpublickey.3r .\" links@publickey.3r getsecretkey.3r .\" $Header: getbootpent.3x,v 74.1 95/05/10 21:04:42 ssa Exp $ .TA g .TH getbootpent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" =========== .SH NAME getbootpent(), putbootpent(), setbootpent(), endbootpent(), parse_bp_htype(), parse_bp_haddr(), parse_bp_iaddr() \- get or put bootptab entry .\" =========== .SH SYNOPSIS .C "#include " .PP .C "int getbootpent (struct bootpent **bootpent);" .PP .C "int setbootpent (const char *path);" .PP .C "int endbootpent (void);" .PP .C "void putbootpent (" .nf .PD 0 .IP .C "const struct bootpent *bootpent," .C "const int numfields," .C "\s-1FILE\s0 * bootpfile" .PP .C ");" .PD .fi .PP .C "int parse_bp_htype (const char *source);" .PP .C "int parse_bp_haddr (" .nf .PD 0 .IP .C "char **source," .C "int htype," .C "unsigned char *result," .C "unsigned int *bytes" .PP .C ");" .PD .PP .C "int parse_bp_iaddr (" .nf .PD 0 .IP .C "char **source," .C "unsigned long *result" .PP .C ");" .PD .\" =========== .SS Remarks These functions reside in libdc.a, and are linked using the .C -ldc option to the .C ld or .C cc command. .\" =========== .SH DESCRIPTION These functions help a program read or modify a bootptab .RC ( bootpd control) file one entry at a time. .C getbootpent() locates an entry in the .C /etc/bootptab file, or an alternate file specified to .CR setbootpent() , and returns a pointer to an array of objects of type .C struct bootpent that breaks the entry into separate data fields with preceding, or embedded, comment (text) lines. .PP The .C bootpent structure is defined in .RC < bootpent.h > and includes the following members: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. int@bp_type;@/* BP_DATA, BP_COMMENT, BP_BLANK@*/ char@*bp_text;@/* one field or one comment line@*/ .TE .ft P .RE .PP The file also defines the following data type and constants: .IP .C "typedef struct bootpent *bpp_t;" .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. #define BP_NULLP@((bpp_t) 0) #define BP_SIZE@(sizeof (struct bootpent)) .TE .ft P .RE .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. #define MAXHADDRLEN@6 #define HTYPE_UNKNOWN@0@/* 0 bytes@*/ #define HTYPE_ETHERNET@1@/* 6 bytes@*/ #define HTYPE_EXP_ETHERNET@2@/* 1 byte@*/ #define HTYPE_AX25@3@/* 0 bytes@*/ #define HTYPE_PRONET@4@/* 1 byte@*/ #define HTYPE_CHAOS@5@/* 0 bytes@*/ #define HTYPE_IEEE802@6@/* 6 bytes@*/ #define HTYPE_ARCNET@7@/* 0 bytes@*/ #define MAXHTYPES@7 .TE .ft P .RE .PP The fields are described in the .RB `` "Field Definitions" '' section below. The purpose of each function is as follows. .TP 25 .C getbootpent() When first called, .C getbootpent() returns a pointer to, and the number of elements in, an array of .C bootpent structures. The array holds the first entry in the .C /etc/bootptab file (or from an alternate file specified by a call to .CR setbootpent() ), including leading, or embedded, comment lines. Each subsequent call returns a pointer to the next entry in the file so that successive calls can be used to search the entire file. .IP If no file is currently in memory, .C getbootpent() reads the .C /etc/bootptab file prior to doing its work. .IP The returned array exists in static space (malloc'd memory) overwritten by the next call (so previously returned pointers become invalid). However, each array element's .C bp_text pointer points to text in an in-memory copy of the file. This text is not altered by the next call (nor by changes to the file itself). Hence, it is possible to copy an entry's array in order to save it, as illustrated in .SM EXAMPLES below. The data remains valid until the next call of .C setbootpent() or .CR endbootpent(). .IP If there are comments after the last entry, they are returned as a separate entry with no data parts. .TP .C setbootpent() Opens the specified file for reading by .CR getbootpent() , reads a copy into memory, and closes the file (which as a side-effect releases any locks on the file; see .IR lockf (2)). If the given .I path is a null pointer or a null string, .C setbootpent() opens and reads .CR /etc/bootptab . .IP If the last file opened by .C setbootpent() (or implicitly by .CR getbootpent() ) was .CR /etc/bootptab , a subsequent call to .C setbootpent() for the same file rewinds the file to the beginning, making visible any recent changes to the file, without first requiring a call to .CR endbootpent() . .TP .C endbootpent() Frees the in-memory copy of the last file opened by .CR setbootpent() , or .CR getbootpent() . .TP .C putbootpent() Writes (to the current location in the stream specified by .IR bootpfile ) the .SM ASCII equivalent of the specified array of .C bootpent structures containing one file entry, and its leading, or embedded, comments (a total of .I numfields array elements). Entries are written in canonical form, meaning the entry name and each data field are on separate lines, data fields are preceded by one tab each, and each line except the last ends with ``:\e''. If .I numfields is less than or equal to zero, nothing is written. .TP .C parse_bp_htype() Converts a host address type from string to numeric format .RC ( HTYPE_ *) in the same manner as .CR bootpd . .TP .C parse_bp_haddr() Converts a host (hardware, link level) address from string to binary format in the same manner as .C bootpd given a host address type .RC ( HTYPE_ *). The calling program's .IR result , which must be an array containing at least .SM MAXHADDRLEN elements, is modified to hold the host address binary value, and .C bytes is modified to indicate the length in bytes of the resulting address. This can be used to compare two host addresses, independent of string representations. .I source is modified to point to the first char after the parsed address. .TP .C parse_bp_iaddr() Converts an internet address from string to binary format in the same manner as .CR bootpd . This can be used to compare two internet addresses, independent of string representations. The calling program's .I result is modified to hold the internet address binary value. .I source is modified to point to the first char after the parsed address. .\" ----------- .SS Field Definitions If .C bootpent.bp_type is .SM BP_DATA, the associated text is one field from the current entry, either the name field or one of the tag fields. Null tag fields (two colons in a row) are ignored, not returned. .PP If .C bootpent.bp_type is .SM BP_COMMENT or .SM BP_BLANK, the associated text is one comment line or blank line from the file, either preceding the current entry or embedded in it following a data line that was continued with a backslash. The text is exactly as it appears in the file, including any whitespace appearing on a blank line, and there is no trailing newline. .PP The returned array elements are in the same order as data fields and comment lines appear in the file. .PP Entry field strings are of the form: .IP .IR tag [\c .ift \f4\s+1@\s0\fP\c .ifn \f3@\fP\c .RC ]\|[ =\c .C """\c .I value\c .C """\c .RC ] .PP with surrounding whitespace, if any, removed (see .IR bootpd (1M) for the full description). Double quotes, and backslashes, can appear anywhere in the field strings. .PP Template entries (those referred to by other entries using .C tc fields) are not special. They can be managed like other entries. It is the calling program's responsibility to correctly manage the order of fields, .C tc fields, and ``@'' fields that override earlier field values. .\" =========== .SH RETURN VALUE .C getbootpent() returns the number of valid array elements (one or more) upon successful completion. At the end of the input file it returns zero. If it cannot open or close the file it returns \-1. If it encounters a memory allocation or map error, or a read error, it returns \-2. .PP .C setbootpent() returns zero if successful opening and reading the specified or default file. If it cannot open or close the file it returns \-1. If it encounters a memory allocation or map error or a read error it returns \-2. .PP .C endbootpent() returns zero if successful freeing the memory for the current open file. If there is no current file it returns \-1. If it cannot free the memory for the current file it returns \-2. .PP .C putbootpent() returns zero if successful writing an entry to the specified file, with the .C ferror() indication clear (see .IR ferror (3S)). Otherwise it returns non-zero with .C ferror() set. .PP In all cases above, if a failure is due to a failed system call, the .C errno value from the system is valid on return from the called function. .PP .C parse_bp_htype() returns .SM HTYPE_UNKNOWN if the hardware type string is unrecognized. .PP .C parse_bp_haddr() returns zero if successful, otherwise non-zero in case of parsing error, invalid .IR htype , or a host address type for which the address length is unknown; .I source is modified to point to the first illegal char (a .SM NUL if the string is too short). The caller's .I bytes value is unmodified, but .I result might be changed. .PP .C parse_bp_iaddr() returns zero if successful, otherwise non-zero, and .I source is modified to point to the first illegal char (a .SM NUL if the string is null). .\" =========== .SH EXAMPLES The following code fragment copies all data and comments from .C /etc/bootptab to a temporary copy of the file. It converts data entries to canonical form as a side effect, and prints to standard output the first field of each entry copied (should be the field name, assuming the entry doesn't start with a continuation line). .RS .PP .nf .ifn \f3 .ift \f4 #include \s-1FILE\s0 *newfilep; /* to write temp file */ bpp_t bp; /* read from file */ int field; /* current field number */ int fields; /* total in array for one entry */ if ((newfilep = fopen ("/tmp/bootptab", "w")) == (\s-1FILE\s0 *) \s-1NULL\s0) { \f2(handle error)\fP } while ((fields = getbootpent (&bp)) > 0) { for (field = 0; field < fields; ++field) { if ((bp[field].bp_type) == \s-1BP_DATA\s0) { (void) puts (bp[field].bp_text); break; } } if (putbootpent (bp, fields, newfilep)) { \f2(handle error)\fP } } if (fields < 0) /* error reading file */ { \f2(handle error)\fP } if (endbootpent()) { \f2(handle error)\fP } if (fclose (newfilep)) { \f2(handle error)\fP } .ft P .fi .RE .PP The following code fragment saves a copy of a bootptab entry returned by .CR getbootpent() . .RS .PP .nf .ifn \f3 .ift \f4 #include #include #include bpp_t bpnew; unsigned size; size = fields *\s-1BP_SIZE\s0; if ((bpnew = (bpp_t) malloc (size)) == \s-1BP_NULLP\s0) { \f2(handle error)\fP } (void) memcpy ((void *)bpnew, (void *)bp, size); .ft P .fi .RE .\" =========== .SH WARNINGS These functions are unsafe in multi-thread applications. .PP Calling .C setbootpent() releases any locks on the file it opens. .\" =========== .SH AUTHOR .PP These functions were developed by .SM HP. .\" =========== .SH FILES .TP 20 .C /etc/bootptab control file for .C bootpd .\" =========== .SH SEE ALSO bootpd(1M), .\" chbootptab(1M), (SAM-only, not currently supported for 10.0) errno(2), lockf(2), ferror(3S), fopen(3S), malloc(3C). .\" .\" toc@\f3getbootpent(3X)\f1:\0\0\f4getbootpent(), putbootpent(), setbootpent(), endbootpent(), \nparse_bp_htype(), parse_bp_hpaddr(), parse_bp_iaddr()\f1@@@get, or put bootptab entry .\" .\" index@get, or put bootptab entry \- @@@\f3getbootpent(3X)\f1 .\" index@bootptab entry, get or put@@@\f3getbootpent(3X)\f1 .\" .\" links@getbootpent.3x setbootpent.3x .\" links@getbootpent.3x endbootpent.3x .\" links@getbootpent.3x putbootpent.3x .\" links@getbootpent.3x parse_bp_htype.3x .\" links@getbootpent.3x parse_bp_haddr.3x .\" links@getbootpent.3x parse_bp_iaddr.3x .\" $Header: putc.3s,v 76.1 95/07/05 17:44:59 ssa Exp $ .TA p .TH putc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putc(\|), putc_unlocked(\|), putchar(\|), putchar_unlocked(\|), fputc(\|), putw(\|), putw_unlocked(\|) \- put character or word on a stream .SH SYNOPSIS .C "#include " .PP .C "int putc(int c, FILE *stream);" .PP .C "int putc_unlocked(int c, FILE *stream);" .PP .C "int putchar(int c);" .PP .C "int putchar_unlocked(int c);" .PP .C "int fputc(int c, FILE *stream);" .PP .C "int putw(int w, FILE *stream);" .PP .C "int putw_unlocked(int w, FILE *stream);" .SH DESCRIPTION .TP 15 .CR putc() Writes the character .I c onto the output .I stream at the position where the file pointer, if defined, is pointing. .CI putchar( c ) is defined as .CI putc( c , .CR stdout) . .CR putc() and .CR putchar() are defined both as macros and as functions. .TP .CR fputc() Same as .CR putc() , but is a function rather than a macro, and can therefore be used as an argument. .CR fputc() runs more slowly than .CR putc() , but takes less space per invocation, and its name can be passed as an argument to a function. .TP .CR putw() Writes the word (i.e., .CR int in C) .I w to the output .I stream (at the position at which the file pointer, if defined, is pointing). The size of a word is the size of an integer and varies from machine to machine. .CR putw() neither assumes nor causes special alignment in the file. .PP Output streams, with the exception of the standard error stream .CR stderr , are by default buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream, .CR stderr , is by default unbuffered, but use of .CR freopen() (see .IR fopen (3S)) causes it to become buffered or line-buffered. .CR setbuf() or .CR setvbuf() (see .IR setbuf (3S)) can be used to change the stream's buffering strategy. .PP .CR putc_unlocked() , " putchar_unlocked()" , and .CR putw_unlocked() are identical to .CR putc() , " putchar()" , and .CR putw() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE On success, .CR putc() , .CR putc_unlocked() , .CR fputc() , .CR putchar() , and .CR putchar_unlocked() each return the value they have written. On failure, they return the constant .SM EOF, set the error indicator for the stream, and set .CR errno to indicate the error. .PP On success, .CR putw() and .CR putw_unlocked() return 0. Otherwise, a non-zero value is returned, the error indicator for the stream is set, and .CR errno is set to indicate the error. .SH ERRORS .CR putc() , .CR putc_unlocked() , .CR putchar() , .CR putchar_unlocked() , .CR fputc() , .CR putw() , and .CR putw_unlocked() fail if, either the .I stream is unbuffered or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 .SM [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP .SM [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP .SM [EINTR] A signal was caught during the .CR write() system call. .TP .SM [EIO] A physical I/O error has occurred, or the process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt is made to write to a pipe or .SM FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH WARNINGS The .CR putc() and .CR putchar() routines are implemented as both library functions and macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parentheses or use the function address. The following example illustrates each of these methods: .nf .IP .CR #include .CR #undef putc \h'.2i'... .CR main() .CR { .CR " int (*put_char()) ();" \h'.6i'... .CR " return_val=putc(c,fd);" \h'.6i'... .CR " return_val=(putc)(c,fd1);" \h'.6i'... .CR " put_char = putchar;" .CR }; .fi .PP Line buffering may cause confusion or malfunctioning of programs that use standard .SM I/O routines but use .CR read() themselves to read from standard input. When a large amount of computation is done after printing part of a line on an output terminal, it is necessary to .CR fflush() (see .IR fclose (3S)) the standard output before beginning the computation. .PP The macro version of .CR putc() incorrectly treats the argument .I stream with side effects. In particular, the following call may not work as expected: .IP .CR putc(c, *f++); .PP The function version of .CR putc() or .CR fputc() should be used instead. .PP Because of possible differences in word length and byte ordering, files written using .CR putw() are machine-dependent, and may not be readable by .CR getw() on a different processor. .SS Reentrant Interfaces If .CR _REENTRANT is defined, the locked versions of the library functions for .CR putc() and .CR putchar() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR putc() and .CR putchar() . .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), getc(3S), fread(3S), printf(3S), puts(3S), setbuf(3S). .SH STANDARDS CONFORMANCE .CR putc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fputc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR putchar() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR putw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4putc()\fP, \f4fputc()\fP \- put character on a stream@@@\f3putc(3S)\f1 .\" index@\f4fputc()\fP, \f4putc()\fP \- put character on a stream@@@\f3putc(3S)\f1 .\" index@\f4putchar()\fP \- put character on stream \f2standard output\f1@@@\f3putc(3S)\f1 .\" index@\f4putw()\fP \- put word (integer) on a stream@@@\f3putc(3S)\f1 .\" index@character or word, put on a stream@@@\f3putc(3S)\f1 .\" index@put character or word on a stream@@@\f3putc(3S)\f1 .\" index@put word or character on a stream@@@\f3putc(3S)\f1 .\" index@word or character, put on a stream@@@\f3putc(3S)\f1 .\" index@stream, put word or character on a@@@\f3putc(3S)\f1 .\" .\" toc@\f3putc(3S)\f1:\0\0\f4putc()\fP, \f4putchar()\fP, \f4fputc()\fP, \f4putw()\fP@@@put character or word on a stream .\" toc@\f4putchar()\fP:\0\0put character on a stream@@@see \f3putc(3S)\f1 .\" toc@\f4fputc()\fP:\0\0put character on a stream@@@see \f3putc(3S)\f1 .\" toc@\f4putw()\fP:\0\0put word on a stream@@@see \f3putc(3S)\f1 .\" .\" links@putc.3s putc_unlock.3s .\" links@putc.3s putchar.3s .\" links@putc.3s putchar_unl.3s .\" links@putc.3s fputc.3s .\" links@putc.3s putw.3s .\" links@putc.3s putw_unlock.3s .\" $Header: putc.3s,v 76.1 95/07/05 17:44:59 ssa Exp $ .TA p .TH putc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putc(\|), putc_unlocked(\|), putchar(\|), putchar_unlocked(\|), fputc(\|), putw(\|), putw_unlocked(\|) \- put character or word on a stream .SH SYNOPSIS .C "#include " .PP .C "int putc(int c, FILE *stream);" .PP .C "int putc_unlocked(int c, FILE *stream);" .PP .C "int putchar(int c);" .PP .C "int putchar_unlocked(int c);" .PP .C "int fputc(int c, FILE *stream);" .PP .C "int putw(int w, FILE *stream);" .PP .C "int putw_unlocked(int w, FILE *stream);" .SH DESCRIPTION .TP 15 .CR putc() Writes the character .I c onto the output .I stream at the position where the file pointer, if defined, is pointing. .CI putchar( c ) is defined as .CI putc( c , .CR stdout) . .CR putc() and .CR putchar() are defined both as macros and as functions. .TP .CR fputc() Same as .CR putc() , but is a function rather than a macro, and can therefore be used as an argument. .CR fputc() runs more slowly than .CR putc() , but takes less space per invocation, and its name can be passed as an argument to a function. .TP .CR putw() Writes the word (i.e., .CR int in C) .I w to the output .I stream (at the position at which the file pointer, if defined, is pointing). The size of a word is the size of an integer and varies from machine to machine. .CR putw() neither assumes nor causes special alignment in the file. .PP Output streams, with the exception of the standard error stream .CR stderr , are by default buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream, .CR stderr , is by default unbuffered, but use of .CR freopen() (see .IR fopen (3S)) causes it to become buffered or line-buffered. .CR setbuf() or .CR setvbuf() (see .IR setbuf (3S)) can be used to change the stream's buffering strategy. .PP .CR putc_unlocked() , " putchar_unlocked()" , and .CR putw_unlocked() are identical to .CR putc() , " putchar()" , and .CR putw() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE On success, .CR putc() , .CR putc_unlocked() , .CR fputc() , .CR putchar() , and .CR putchar_unlocked() each return the value they have written. On failure, they return the constant .SM EOF, set the error indicator for the stream, and set .CR errno to indicate the error. .PP On success, .CR putw() and .CR putw_unlocked() return 0. Otherwise, a non-zero value is returned, the error indicator for the stream is set, and .CR errno is set to indicate the error. .SH ERRORS .CR putc() , .CR putc_unlocked() , .CR putchar() , .CR putchar_unlocked() , .CR fputc() , .CR putw() , and .CR putw_unlocked() fail if, either the .I stream is unbuffered or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 .SM [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP .SM [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP .SM [EINTR] A signal was caught during the .CR write() system call. .TP .SM [EIO] A physical I/O error has occurred, or the process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt is made to write to a pipe or .SM FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH WARNINGS The .CR putc() and .CR putchar() routines are implemented as both library functions and macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parentheses or use the function address. The following example illustrates each of these methods: .nf .IP .CR #include .CR #undef putc \h'.2i'... .CR main() .CR { .CR " int (*put_char()) ();" \h'.6i'... .CR " return_val=putc(c,fd);" \h'.6i'... .CR " return_val=(putc)(c,fd1);" \h'.6i'... .CR " put_char = putchar;" .CR }; .fi .PP Line buffering may cause confusion or malfunctioning of programs that use standard .SM I/O routines but use .CR read() themselves to read from standard input. When a large amount of computation is done after printing part of a line on an output terminal, it is necessary to .CR fflush() (see .IR fclose (3S)) the standard output before beginning the computation. .PP The macro version of .CR putc() incorrectly treats the argument .I stream with side effects. In particular, the following call may not work as expected: .IP .CR putc(c, *f++); .PP The function version of .CR putc() or .CR fputc() should be used instead. .PP Because of possible differences in word length and byte ordering, files written using .CR putw() are machine-dependent, and may not be readable by .CR getw() on a different processor. .SS Reentrant Interfaces If .CR _REENTRANT is defined, the locked versions of the library functions for .CR putc() and .CR putchar() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR putc() and .CR putchar() . .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), getc(3S), fread(3S), printf(3S), puts(3S), setbuf(3S). .SH STANDARDS CONFORMANCE .CR putc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fputc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR putchar() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR putw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4putc()\fP, \f4fputc()\fP \- put character on a stream@@@\f3putc(3S)\f1 .\" index@\f4fputc()\fP, \f4putc()\fP \- put character on a stream@@@\f3putc(3S)\f1 .\" index@\f4putchar()\fP \- put character on stream \f2standard output\f1@@@\f3putc(3S)\f1 .\" index@\f4putw()\fP \- put word (integer) on a stream@@@\f3putc(3S)\f1 .\" index@character or word, put on a stream@@@\f3putc(3S)\f1 .\" index@put character or word on a stream@@@\f3putc(3S)\f1 .\" index@put word or character on a stream@@@\f3putc(3S)\f1 .\" index@word or character, put on a stream@@@\f3putc(3S)\f1 .\" index@stream, put word or character on a@@@\f3putc(3S)\f1 .\" .\" toc@\f3putc(3S)\f1:\0\0\f4putc()\fP, \f4putchar()\fP, \f4fputc()\fP, \f4putw()\fP@@@put character or word on a stream .\" toc@\f4putchar()\fP:\0\0put character on a stream@@@see \f3putc(3S)\f1 .\" toc@\f4fputc()\fP:\0\0put character on a stream@@@see \f3putc(3S)\f1 .\" toc@\f4putw()\fP:\0\0put word on a stream@@@see \f3putc(3S)\f1 .\" .\" links@putc.3s putc_unlock.3s .\" links@putc.3s putchar.3s .\" links@putc.3s putchar_unl.3s .\" links@putc.3s fputc.3s .\" links@putc.3s putw.3s .\" links@putc.3s putw_unlock.3s .\" $Header: putc.3s,v 76.1 95/07/05 17:44:59 ssa Exp $ .TA p .TH putc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putc(\|), putc_unlocked(\|), putchar(\|), putchar_unlocked(\|), fputc(\|), putw(\|), putw_unlocked(\|) \- put character or word on a stream .SH SYNOPSIS .C "#include " .PP .C "int putc(int c, FILE *stream);" .PP .C "int putc_unlocked(int c, FILE *stream);" .PP .C "int putchar(int c);" .PP .C "int putchar_unlocked(int c);" .PP .C "int fputc(int c, FILE *stream);" .PP .C "int putw(int w, FILE *stream);" .PP .C "int putw_unlocked(int w, FILE *stream);" .SH DESCRIPTION .TP 15 .CR putc() Writes the character .I c onto the output .I stream at the position where the file pointer, if defined, is pointing. .CI putchar( c ) is defined as .CI putc( c , .CR stdout) . .CR putc() and .CR putchar() are defined both as macros and as functions. .TP .CR fputc() Same as .CR putc() , but is a function rather than a macro, and can therefore be used as an argument. .CR fputc() runs more slowly than .CR putc() , but takes less space per invocation, and its name can be passed as an argument to a function. .TP .CR putw() Writes the word (i.e., .CR int in C) .I w to the output .I stream (at the position at which the file pointer, if defined, is pointing). The size of a word is the size of an integer and varies from machine to machine. .CR putw() neither assumes nor causes special alignment in the file. .PP Output streams, with the exception of the standard error stream .CR stderr , are by default buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream, .CR stderr , is by default unbuffered, but use of .CR freopen() (see .IR fopen (3S)) causes it to become buffered or line-buffered. .CR setbuf() or .CR setvbuf() (see .IR setbuf (3S)) can be used to change the stream's buffering strategy. .PP .CR putc_unlocked() , " putchar_unlocked()" , and .CR putw_unlocked() are identical to .CR putc() , " putchar()" , and .CR putw() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE On success, .CR putc() , .CR putc_unlocked() , .CR fputc() , .CR putchar() , and .CR putchar_unlocked() each return the value they have written. On failure, they return the constant .SM EOF, set the error indicator for the stream, and set .CR errno to indicate the error. .PP On success, .CR putw() and .CR putw_unlocked() return 0. Otherwise, a non-zero value is returned, the error indicator for the stream is set, and .CR errno is set to indicate the error. .SH ERRORS .CR putc() , .CR putc_unlocked() , .CR putchar() , .CR putchar_unlocked() , .CR fputc() , .CR putw() , and .CR putw_unlocked() fail if, either the .I stream is unbuffered or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 .SM [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP .SM [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP .SM [EINTR] A signal was caught during the .CR write() system call. .TP .SM [EIO] A physical I/O error has occurred, or the process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt is made to write to a pipe or .SM FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH WARNINGS The .CR putc() and .CR putchar() routines are implemented as both library functions and macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parentheses or use the function address. The following example illustrates each of these methods: .nf .IP .CR #include .CR #undef putc \h'.2i'... .CR main() .CR { .CR " int (*put_char()) ();" \h'.6i'... .CR " return_val=putc(c,fd);" \h'.6i'... .CR " return_val=(putc)(c,fd1);" \h'.6i'... .CR " put_char = putchar;" .CR }; .fi .PP Line buffering may cause confusion or malfunctioning of programs that use standard .SM I/O routines but use .CR read() themselves to read from standard input. When a large amount of computation is done after printing part of a line on an output terminal, it is necessary to .CR fflush() (see .IR fclose (3S)) the standard output before beginning the computation. .PP The macro version of .CR putc() incorrectly treats the argument .I stream with side effects. In particular, the following call may not work as expected: .IP .CR putc(c, *f++); .PP The function version of .CR putc() or .CR fputc() should be used instead. .PP Because of possible differences in word length and byte ordering, files written using .CR putw() are machine-dependent, and may not be readable by .CR getw() on a different processor. .SS Reentrant Interfaces If .CR _REENTRANT is defined, the locked versions of the library functions for .CR putc() and .CR putchar() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR putc() and .CR putchar() . .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), getc(3S), fread(3S), printf(3S), puts(3S), setbuf(3S). .SH STANDARDS CONFORMANCE .CR putc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fputc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR putchar() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR putw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4putc()\fP, \f4fputc()\fP \- put character on a stream@@@\f3putc(3S)\f1 .\" index@\f4fputc()\fP, \f4putc()\fP \- put character on a stream@@@\f3putc(3S)\f1 .\" index@\f4putchar()\fP \- put character on stream \f2standard output\f1@@@\f3putc(3S)\f1 .\" index@\f4putw()\fP \- put word (integer) on a stream@@@\f3putc(3S)\f1 .\" index@character or word, put on a stream@@@\f3putc(3S)\f1 .\" index@put character or word on a stream@@@\f3putc(3S)\f1 .\" index@put word or character on a stream@@@\f3putc(3S)\f1 .\" index@word or character, put on a stream@@@\f3putc(3S)\f1 .\" index@stream, put word or character on a@@@\f3putc(3S)\f1 .\" .\" toc@\f3putc(3S)\f1:\0\0\f4putc()\fP, \f4putchar()\fP, \f4fputc()\fP, \f4putw()\fP@@@put character or word on a stream .\" toc@\f4putchar()\fP:\0\0put character on a stream@@@see \f3putc(3S)\f1 .\" toc@\f4fputc()\fP:\0\0put character on a stream@@@see \f3putc(3S)\f1 .\" toc@\f4putw()\fP:\0\0put word on a stream@@@see \f3putc(3S)\f1 .\" .\" links@putc.3s putc_unlock.3s .\" links@putc.3s putchar.3s .\" links@putc.3s putchar_unl.3s .\" links@putc.3s fputc.3s .\" links@putc.3s putw.3s .\" links@putc.3s putw_unlock.3s .\" $Header: putc.3s,v 76.1 95/07/05 17:44:59 ssa Exp $ .TA p .TH putc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putc(\|), putc_unlocked(\|), putchar(\|), putchar_unlocked(\|), fputc(\|), putw(\|), putw_unlocked(\|) \- put character or word on a stream .SH SYNOPSIS .C "#include " .PP .C "int putc(int c, FILE *stream);" .PP .C "int putc_unlocked(int c, FILE *stream);" .PP .C "int putchar(int c);" .PP .C "int putchar_unlocked(int c);" .PP .C "int fputc(int c, FILE *stream);" .PP .C "int putw(int w, FILE *stream);" .PP .C "int putw_unlocked(int w, FILE *stream);" .SH DESCRIPTION .TP 15 .CR putc() Writes the character .I c onto the output .I stream at the position where the file pointer, if defined, is pointing. .CI putchar( c ) is defined as .CI putc( c , .CR stdout) . .CR putc() and .CR putchar() are defined both as macros and as functions. .TP .CR fputc() Same as .CR putc() , but is a function rather than a macro, and can therefore be used as an argument. .CR fputc() runs more slowly than .CR putc() , but takes less space per invocation, and its name can be passed as an argument to a function. .TP .CR putw() Writes the word (i.e., .CR int in C) .I w to the output .I stream (at the position at which the file pointer, if defined, is pointing). The size of a word is the size of an integer and varies from machine to machine. .CR putw() neither assumes nor causes special alignment in the file. .PP Output streams, with the exception of the standard error stream .CR stderr , are by default buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream, .CR stderr , is by default unbuffered, but use of .CR freopen() (see .IR fopen (3S)) causes it to become buffered or line-buffered. .CR setbuf() or .CR setvbuf() (see .IR setbuf (3S)) can be used to change the stream's buffering strategy. .PP .CR putc_unlocked() , " putchar_unlocked()" , and .CR putw_unlocked() are identical to .CR putc() , " putchar()" , and .CR putw() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE On success, .CR putc() , .CR putc_unlocked() , .CR fputc() , .CR putchar() , and .CR putchar_unlocked() each return the value they have written. On failure, they return the constant .SM EOF, set the error indicator for the stream, and set .CR errno to indicate the error. .PP On success, .CR putw() and .CR putw_unlocked() return 0. Otherwise, a non-zero value is returned, the error indicator for the stream is set, and .CR errno is set to indicate the error. .SH ERRORS .CR putc() , .CR putc_unlocked() , .CR putchar() , .CR putchar_unlocked() , .CR fputc() , .CR putw() , and .CR putw_unlocked() fail if, either the .I stream is unbuffered or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 .SM [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP .SM [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP .SM [EINTR] A signal was caught during the .CR write() system call. .TP .SM [EIO] A physical I/O error has occurred, or the process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt is made to write to a pipe or .SM FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH WARNINGS The .CR putc() and .CR putchar() routines are implemented as both library functions and macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parentheses or use the function address. The following example illustrates each of these methods: .nf .IP .CR #include .CR #undef putc \h'.2i'... .CR main() .CR { .CR " int (*put_char()) ();" \h'.6i'... .CR " return_val=putc(c,fd);" \h'.6i'... .CR " return_val=(putc)(c,fd1);" \h'.6i'... .CR " put_char = putchar;" .CR }; .fi .PP Line buffering may cause confusion or malfunctioning of programs that use standard .SM I/O routines but use .CR read() themselves to read from standard input. When a large amount of computation is done after printing part of a line on an output terminal, it is necessary to .CR fflush() (see .IR fclose (3S)) the standard output before beginning the computation. .PP The macro version of .CR putc() incorrectly treats the argument .I stream with side effects. In particular, the following call may not work as expected: .IP .CR putc(c, *f++); .PP The function version of .CR putc() or .CR fputc() should be used instead. .PP Because of possible differences in word length and byte ordering, files written using .CR putw() are machine-dependent, and may not be readable by .CR getw() on a different processor. .SS Reentrant Interfaces If .CR _REENTRANT is defined, the locked versions of the library functions for .CR putc() and .CR putchar() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR putc() and .CR putchar() . .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), getc(3S), fread(3S), printf(3S), puts(3S), setbuf(3S). .SH STANDARDS CONFORMANCE .CR putc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fputc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR putchar() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR putw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4putc()\fP, \f4fputc()\fP \- put character on a stream@@@\f3putc(3S)\f1 .\" index@\f4fputc()\fP, \f4putc()\fP \- put character on a stream@@@\f3putc(3S)\f1 .\" index@\f4putchar()\fP \- put character on stream \f2standard output\f1@@@\f3putc(3S)\f1 .\" index@\f4putw()\fP \- put word (integer) on a stream@@@\f3putc(3S)\f1 .\" index@character or word, put on a stream@@@\f3putc(3S)\f1 .\" index@put character or word on a stream@@@\f3putc(3S)\f1 .\" index@put word or character on a stream@@@\f3putc(3S)\f1 .\" index@word or character, put on a stream@@@\f3putc(3S)\f1 .\" index@stream, put word or character on a@@@\f3putc(3S)\f1 .\" .\" toc@\f3putc(3S)\f1:\0\0\f4putc()\fP, \f4putchar()\fP, \f4fputc()\fP, \f4putw()\fP@@@put character or word on a stream .\" toc@\f4putchar()\fP:\0\0put character on a stream@@@see \f3putc(3S)\f1 .\" toc@\f4fputc()\fP:\0\0put character on a stream@@@see \f3putc(3S)\f1 .\" toc@\f4putw()\fP:\0\0put word on a stream@@@see \f3putc(3S)\f1 .\" .\" links@putc.3s putc_unlock.3s .\" links@putc.3s putchar.3s .\" links@putc.3s putchar_unl.3s .\" links@putc.3s fputc.3s .\" links@putc.3s putw.3s .\" links@putc.3s putw_unlock.3s .\" $Header: getdvagent.3,v 72.3 94/07/05 17:58:22 ssa Exp $ .TA g .TH getdvagent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getdvagent, getdvagnam, setdvagent, enddvagent, putdvagnam, copydvagent \- manipulate device assignment database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct dev_asg \(**getdvagent(\|);" .PP .CR "struct dev_asg \(**getdvagnam(const char \(**name);" .PP .CR "void setdvagent(\|);" .PP .CR "void enddvagent(\|);" .PP .CR "int putdvagnam(const char \(**name, struct dev_asg \(**dv);" .PP .CR "struct dev_asg \(**copydvagent(struct dev_asg \(**dv);" .fi .SH DESCRIPTION .IR getdvagent , .IR getdvagnam , and .I copydvagent each return a pointer to an object with the following structure containing the broken-out fields of an entry in the Device Assignment database. Each database entry is returned as a .I dev_asg structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v struct dev_field { char *fd_name; /* external name */ char **fd_devs; /* device list */ mask_t fd_type[1]; /* tape, printer, terminal */ char **fd_users; /* authorized user list */ }; .IP /* Device Assignment Database entry */ .IP #define \s-1AUTH_DEV_TYPE\s0 "device type" #define \s-1AUTH_DEV_PRINTER\s0 0 #define \s-1AUTH_DEV_TERMINAL\s0 1 #define \s-1AUTH_DEV_TAPE\s0 2 #define \s-1AUTH_DEV_REMOTE\s0 3 #define \s-1AUTH_MAX_DEV_TYPE\s0 3 #define \s-1AUTH_DEV_TYPE_SIZE\s0 (\s-1WORD_OF_BIT\s0 (\s-1AUTH_MAX_DEV_TY PE\s0) + 1) .IP /* this structure tells which of the corresponding fields * in dev_field are valid (filled). */ struct dev_flag { unsigned short fg_name : 1, fg_devs : 1, fg_type : 1, fg_users : 1, ; }; .IP struct dev_asg { struct dev_field ufld; struct dev_flag uflg; struct dev_field sfld; struct dev_flag sflg; }; .fi .PP The Device Assignment database stores device characteristics that are related to user authorizations and synonyms. On systems supporting network connections, the Device Assignment database stores information about hosts initiating connections. .PP Each entry contains a .IR name , which is a cross reference to the terminal control database, and a list of .IR devices , each of which is a pathname corresponding to that device. This list allows the device assignment software of the trusted system to invalidate all references to a device when re-assigning it. The list is a table of character string pointers, whose last entry is a .SM .B NULL pointer. .PP .I fd_users is a pointer to a null-terminated table of character string pointers referring to user allowed access. .PP For trusted system versions supporting network connections, the device name can be a 12 character host name, where the first 8 characters are the .SM ASCII hex address of the device, and the last 4 characters are .SM ASCII zeroes. For example, a host with Internet address 129.75.0.3 has device name 814b00030000. The trailing four zeroes are for compatibility with ports on terminal concentrators. The SAM API's supports conversion of host name to device name. Thus, sensitivity level ranges and user authorization lists can be enforced on hosts as well as on directly connected terminals. .PP When .I getdvagent is first called, it returns a pointer to the first device assignment entry. Thereafter, it returns a pointer to the next entry, so successive calls can be used to search the database. .I getdvagnam searches from the beginning of the database until an entry with a device name matching .I name is found, and returns a pointer to that entry. If an end of file or an error is encountered on reading, these functions return a .SM .B NULL pointer. .I copydvagent copies a device assignment structure and the fields to which it refers to a newly-allocated data area. Since .IR getdvagent , .IR getdvagnam , and .I putdvagent re-use a static structure when accessing the database, the values of any entry must be saved if these routines are used again. The .I dev_asg structure returned by .I copydvagent can be freed using .I free (see .IR malloc (3C) or .IR malloc (3X)). .PP A call to .I setdvagent has the effect of setting the device assignment database back to the first entry, to allow repeated searches of the database. .I enddvagent frees all memory and closes all files used to support these routines. .PP .I putdvagnam rewrites or adds an entry to the database. If there is an entry whose .I fd_name field matches the .I name argument, that entry is replaced with the contents of the .I dv structure. Otherwise, that entry is added to the database. .SH RETURN VALUE .IR getdvagent and .IR getdvagnam return a pointer to a static structure on success, or a .SM .B NULL pointer on failure. This static structure is overwritten by .IR getdvagent , .IR getdvagnam , and .IR putdvagnam . .PP .I putdvagnam returns 1 on success, or 0 on failure. .PP .I copydvagent returns a pointer to the newly-allocated structure on success, or a .SM .B NULL pointer if there was a memory allocation error. .SH "WARNINGS" The structure returned by this routine contains .I pointers to character strings and lists rather than being self-contained. .I copydvagent must be used instead of structure assignments to save a returned structure. .PP The value returned by .I getdvagent and .I getdvagnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using .I copydvagent and supply the modified buffer to .IR putdvagent . .SH NOTES Programs using this routine must be compiled with .BR \-lsec . .SH AUTHOR SecureWare Inc. .SH FILES .TP 40 .CR /tcb/files/devassign Device assignment database .PD .SH SEE ALSO authcap(4). .\" .\" index@\f4getdvagent\f1 \- return pointer for device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f1getdvagnam\f1 \- return success or failure information@@@\f3getdvagent(3)\f1 .\" index@\f4setdvagent\f1 \- set device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f4enddvagent\f1 \- free memory and close file@@@\f3getdvagent(3)\f1 .\" index@\f4putdvagnam\f1 \- add or rewrite device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f4copydvagent\f1 \- copy device assignment structure@@@\f3getdvagent(3)\f1 .\" index@\f1manipulate device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f1device assignment database entry, manipulate@@@\f3getdvagent(3)\f1 .\" index@\f1assignment database entry, manipulate device@@@\f3getdvagent(3)\f1 .\" index@\f1database entry, manipulate device assignment@@@\f3getdvagent(3)\f1 .\" .\" .\" toc@\f3getdvagent(3)\f1:\0\0\f4getdvagent\f1, \f4getdvagnam\f1, \f4setdvagent\f1, \f4enddvagent\f1, \f4putdvagnam\f1, \n\f4copydvagent\f1@@@manipulate device assignment database entry for a trusted system .\" toc@\f4getdvagent\f1:\0\0return pointer for device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4getdvagnam\f1:\0\0return success or failure information@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4setdvagent\f1:\0\0set device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4enddvagent\f1:\0\0free memory and closes file@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4putdvagnam\f1:\0\0add or rewrite device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4copydvagent\f1:\0\0copy device assignment structure@@@\f1see \f3getdvagent(3)\f1 .\" .\" .\" links@getdvagent.3 getdvagnam.3 .\" links@getdvagent.3 setdvagent.3 .\" links@getdvagent.3 enddvagent.3 .\" links@getdvagent.3 putdvagnam.3 .\" links@getdvagent.3 copydvagent.3 .\" .\" fileset_database@getdvagent.3 UX-CORE-MAN .\" $Header: putenv.3c,v 72.6 94/12/08 12:16:45 ssa Exp $ .TA p .TH putenv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putenv(\|) \- change or add value to environment .SH SYNOPSIS .C "#include " .PP .C "int putenv(const char *string);" .SH DESCRIPTION .I string points to a string of the form .IB name = value\f1. .C putenv() makes the value of the environment variable .I name equal to .I value by altering an existing variable or creating a new one. In either case, the string pointed to by .I string becomes part of the environment, so altering the string changes the environment. The space used by .I string is no longer used once a new string-defining .I name is passed to .CR putenv() . .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of characters in .I string as single- and/or multi-byte characters. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH DIAGNOSTICS .C putenv() returns non-zero if it was unable to obtain enough space via .C malloc() for an expanded environment, or if an invalid multibyte character sequence was encountered in the string argument; otherwise it returns zero. .SH ERRORS .CR putenv() fails under the following conditions: .RS .TP 15 [ENOMEM] There is insufficient space to expand the environment. .TP [EILSEQ] An invalid multibyte character sequence was encountered in the string argument. .RE .SH WARNINGS .C putenv() manipulates the environment pointed to by .IB environ , and can be used in conjunction with .CR getenv() . However, .I envp (the third argument to .IR main ) is not changed. .PP This routine uses .C malloc() to enlarge the environment (see .IR malloc (3C)). .PP After .C putenv() is called, environmental variables are not in alphabetical order. .PP A potential error is to call .C putenv() with an automatic variable as the argument, then exit the calling function while .I string is still part of the environment. .SH SEE ALSO exec(2), getenv(3C), malloc(3C), environ(5). .SH STANDARDS CONFORMANCE .CR putenv() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4putenv()\fP \- change or add value to environment@@@\f3putenv(3C)\f1 .\" index@change or add value to environment@@@\f3putenv(3C)\f1 .\" index@add value to environment@@@\f3putenv(3C)\f1 .\" index@environment, change or add value to@@@\f3putenv(3C)\f1 .\" index@value, change or add to environment@@@\f3putenv(3C)\f1 .\" .\" toc@\f3putenv(3C)\f1:\0\0\f4putenv()\fP@@@change or add value to environment .\" .\" fileset_database@putenv.3c PROGRAMING-MAN .\" $Header: putp.3x,v 76.2 95/08/01 14:36:10 ssa Exp $ .TA p .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH putp 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putp, tputs \(em output commands to the terminal .SH SYNOPSIS .C "#include " .P .C "int putp(char *const \f2str\fP);" .P .C "int tputs(char *const \f2str\fP, int \f2affcnt\fP, int (*\f2putfunc\fP)(int));" .SH DESCRIPTION These functions output commands contained in the \f3terminfo\f1 database to the terminal. .P The .Fn putp function is equivalent to \f2tputs\f1(\f2str\fP, 1, \f2putchar\f1). The output of .Fn putp always goes to \f3stdout\fP, not to the \f2fildes\f1 specified in .CR setupterm() . .P The .Fn tputs function outputs \f2str\f1 to the terminal. The \f2str\f1 argument must be a \f3terminfo\f1 string variable or the return value from .CR tgetstr() , .CR tgoto() , .Fn tigetstr or .CR tparm() . The \f2affcnt\f1 argument is the number of lines affected, or 1 if not applicable. If the \f3terminfo\f1 database indicates that the terminal in use requires padding after any command in the generated string, .Fn tputs inserts pad characters into the string that is sent to the terminal, at positions indicated by the \f3terminfo\f1 database. The .Fn tputs function outputs each character of the generated string by calling the user-supplied function .I putfunc (see below). .P The user-supplied function .I putfunc (specified as an argument to .CR tputs ) is either .Fn putchar or some other function with the same prototype. The .Fn tputs function ignores the return value of .I putfunc . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" After use of any of these functions, the model Curses maintains of the state of the terminal might not match the actual state of the terminal. The application should touch and refresh the window before resuming conventional use of Curses. .P Use of these functions requires that the application contain so much information about a particular class of terminal that it defeats the purpose of using Curses. .P On some terminals, a command to change rendition conceptually occupies space in the screen buffer (with or without width). Thus, a command to set the terminal to a new rendition would change the rendition of some characters already displayed. .SH "SEE ALSO" doupdate(), is_linetouched(), putchar() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), tgetent(), tigetflag(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3putp(3X)\f1:\0\0\f4putp()\f1, \f4tputs()\f1@@@output commands to the terminal .\" toc@\f4tputs()\f1: output commands to the terminal@@@see \f3putp(3X)\f1 .\" .\" index@\f4putp()\f1 \- output commands to the terminal@@@\f3putp(3X)\f1 .\" index@\f4tputs()\f1 \- output commands to the terminal@@@\f3putp(3X)\f1 .\" index@\f1output commands to the terminal@@@\f3putp(3X)\f1 .\" index@\f1commands, output to the terminal@@@\f3putp(3X)\f1 .\" index@\f1terminal, output commands to@@@\f3putp(3X)\f1 .\" .\" links@putp.3x tputs.3x .\" .\" fileset_database@putp.3x CURS-ENG-A-MAN .\" $Header: getprdfent.3,v 72.3 94/07/05 18:07:26 ssa Exp $ .TA g .TH getprdfent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprdfent, getprdfnam, setprdfent, endprdfent, putprdfnam \- manipulate system default database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct pr_default \(**getprdfent(void);" .PP .CR "struct pr_default \(**getprdfnam(const char \(**name);" .PP .CR "void setprdfent(void);" .PP .CR "void endprdfent(void);" .PP .CR "int putprdfnam(const char \(**name, struct pr_default \(**pr);" .fi .SH DESCRIPTION .I getprdfent and .I getprdfnam each returns a pointer to an object with the following structure containing the broken-out fields of a line in the system default database. Each line in the database contains a .I pr_default structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v struct system_default_fields { time_t fd_inactivity_timeout ; char fd_boot_authenticate ; } ; struct system_default_flags { unsigned short fg_inactivity_timeout:1, fg_boot_authenticate:1, } ; struct pr_default { char dd_name[20] ; char dg_name ; struct pr_field prd ; struct pr_flag prg ; struct t_field tcd ; struct t_flag tcg ; struct dev_field devd ; struct dev_flag devg ; struct system_default_fields sfld ; struct system_default_flags sflg ; } ; .fi .RE .PP Currently there is only one entry in the system default database, referenced by name .BR default . .PP The System Default database contains default values for all parameters in the Protected Password, Terminal Control, and Device Assignment databases, as well as configurable system-wide parameters. The fields from the other databases are described in the corresponding manual entries. .I fd_inactivity_timeout is the number of seconds until a session is terminated on trusted systems. .PP .I fd_boot_authenticate is a boolean flag that indicates whether an authorized user must authenticate before the system begins operation. .PP .I getprdfent returns a pointer to the first .I pr_default structure in the database when first called. Thereafter, it returns a pointer to the next .I pr_default structure in the database, so that successive calls can be used to search the database (not currently supported). .PP .I getprdfnam searches from the beginning of the file until a default entry matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a .SM .B NULL pointer. Currently, all programs access the default database by calling .I getprdfnam ("default"). .PP A call to .I setprdfent has the effect of rewinding the default control file to allow repeated searches. .I endprdfent can be called to close the database when processing is complete. .PP .I putprdfnam puts a new or replaced default control entry .I pr with key .I name into the database. If the .I prg.fd_name field is 0, the requested entry is deleted from the system default database. .I putprdfnam locks the database for all update operations, and performs an .I endprdfent after the update or failed attempt. .SH RETURN VALUE .I getprdfent and .I getprdfnam return .SM .B NULL pointers on .SM EOF or error. .I putprdfnam returns 0 if it cannot add or update the entry. .SH WARNINGS Do not delete the system default entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 45 .C /tcb/files/auth/system/default System Defaults database .SH SEE ALSO authcap(4), default(4), getprpwent(3), getprtcent(3), getdvagent(3). .SH NOTES The value returned by .I getprdfent and .I getprdfnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .IR putprdfnam . .PP Programs using these routines must be compiled with .BR \-lsec . .\" .\" index@\f4getprdfent\f1 \- manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f4getprdfnam\f1 \- manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f4setprdfent\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" index@\f4endprdfent\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" .\" index@\f4putprdfnam\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" index@\f1manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f1manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f1system default database entry, manipulate@@@\f3getprdfent(3)\f1 .\" index@\f1default database entry, manipulate system@@@\f3getprdfent(3)\f1 .\" index@\f1database entry, manipulate system default@@@\f3getprdfent(3)\f1 .\" index@\f1entry, manipulate system default database@@@\f3getprdfent(3)\f1 .\" .\" toc@\f3getprdfent(3)\f1:\0\0\f4getprdfent\f1, \f4getprdfnam\f1, \f4setprdfent\f1, \f4endprdfent\f1,\n\f4putprdfnam\f1@@@manipulate system default database entry for a trusted system .\" toc@\f4getprdfnam\f1:\0\0search for file@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4setprdfent\f1:\0\0rewind default control files@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4endprdfent\f1:\0\0close system default database@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4putprdfnam\f1:\0\0put default control entry@@@\f1see \f3getprdfent(3)\f1 .\" .\" links@getprdfent.3 getprdfnam.3 .\" links@getprdfent.3 setprdfent.3 .\" links@getprdfent.3 endprdfent.3 .\" links@getprdfent.3 putprdfnam.3 .\" .\" fileset_database@getprdfent.3 UX-CORE-MAN .\" $Header: getprpwent.3,v 78.3 96/01/19 20:14:34 ssa Exp $ .TA g .TH getprpwent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprpwent, getprpwuid, getprpwnam, getprpwaid, setprpwent, endprpwent, putprpwnam \- manipulate protected password database entry (for trusted systems only) .SH SYNOPSIS .nf .B "#include " .B "#include " .B "#include " .PP .B "struct pr_passwd \(**getprpwent(void);" .PP .B "struct pr_passwd \(**getprpwuid(uid_t uid);" .PP .B "struct pr_passwd \(**getprpwnam(const char \(**name);" \c .PP .B "struct pr_passwd \(**getprpwaid(aid_t aid)" \c .PP .B "void setprpwent(void);" .PP .B "void endprpwent(void);" .PP .B "int putprpwnam(const char \(**name, struct pr_passwd \(**pr);" .fi .SH DESCRIPTION .CR getprpwent (), .CR getprpwuid (), .CR getprpwaid (), and .CR getprpwnam () each returns a pointer to a .C pr_passwd structure containing the broken-out fields of a line in the protected password database. Each line in the database contains a .C pr_passwd structure, declared in the .RC < prot.h > header file: .IP .nf .ift .sp -1v struct pr_field { /\(** Identity: \(**/ char fd_name[9]; /\(** uses 8 character maximum(and NULL) from utmp \(**/ uid_t fd_uid; /\(** uid associated with name above \(**/ char fd_encrypt[xxx]; /\(** encrypted password \(**/ char fd_owner[9]; /\(** if a pseudo-user, the user accountable \(**/ char fd_boot_auth; /\(** boot authorization \(**/ mask_t fd_auditcntl; /\(** reserved \(**/ mask_t audit_reserve1; /\(** reserved \(**/ mask_t fd_auditdisp; /\(** reserved \(**/ mask_t audit_reserve2; /\(** reserved \(**/ aid_t fd_pw_audid; /\(** audit ID \(**/ int fd_pw_audflg; /\(** audit flag \(**/ .IP /\(** Password maintenance parameters: \(**/ time_t fd_min; /\(** minimum time between password changes \(**/ int fd_maxlen; /\(** maximum length of password \(**/ time_t fd_expire; /\(** expiration time duration in secs \(**/ time_t fd_lifetime; /\(** account death duration in seconds \(**/ time_t fd_schange; /\(** last successful change in secs past 1/1/70 \(**/ time_t fd_uchange; /\(** last unsuccessful change \(**/ time_t fd_acct_expire; /\(** absolute account lifetime in seconds \(**/ time_t fd_max_llogin; /\(** max time allowed between logins \(**/ time_t fd_pw_expire_warning; /\(** password expiration warning \(**/ uid_t fd_pswduser; /\(** who can change this user's password \(**/ char fd_pick_pwd; /\(** can user pick his own passwords? \(**/ char fd_gen_pwd; /\(** can user get passwords generated for him? \(**/ char fd_restrict; /\(** should generated passwords be restricted? \(**/ char fd_nullpw; /\(** is user allowed to have a NULL password? \(**/ uid_t fd_pwchanger; /\(** who last changed user's password \(**/ long fd_pw_admin_num;/\(** password generation verifier \(**/ char fd_gen_chars; /\(** can have password of random ASCII? \(**/ char fd_gen_letters; /\(** can have password of random letters? \(**/ char fd_tod[AUTH_TOD_SIZE]; /\(** times when user may login \(**/ .IP /\(** Login parameters: \(**/ time_t fd_slogin; /\(** last successful login \(**/ time_t fd_ulogin; /\(** last unsuccessful login \(**/ char fd_suctty[14]; /\(** tty of last successful login \(**/ short fd_nlogins; /\(** consecutive unsuccessful logins \(**/ char fd_unsuctty[14];/\(** tty of last unsuccessful login \(**/ short fd_max_tries; /\(** maximum unsuc login tries allowed \(**/ char fd_lock; /\(** Unconditionally lock account? \(**/ }; .IP struct pr_flag { unsigned short /\(** Identity: \(**/ fg_name:1, /\(** Is fd_name set? \(**/ fg_uid:1, /\(** Is fd_uid set? \(**/ fg_encrypt:1, /\(** Is fd_encrypt set? \(**/ fg_owner:1, /\(** Is fd_owner set? \(**/ fg_boot_auth:1, /\(** Is fd_boot_auth set? \(**/ fg_pw_audid:1, /\(** Is fd_auditcntl set? \(**/ fg_pw_audflg:1, /\(** Is fd_auditdisp set? \(**/ .IP /\(** Password maintenance parameters: \(**/ fg_min:1, /\(** Is fd_min set? \(**/ fg_maxlen:1, /\(** Is fd_maxlen set? \(**/ fg_expire:1, /\(** Is fd_expire set? \(**/ fg_lifetime:1, /\(** Is fd_lifetime set? \(**/ fg_schange:1, /\(** Is fd_schange set? \(**/ fg_uchange:1, /\(** Is fd_fchange set? \(**/ fg_acct_expire:1, /\(** Is fd_acct_expire set? \(**/ fg_max_llogin:1, /\(** Is fd_max_llogin set? \(**/ fg_pw_expire_warning:1, /\(** Is fd_pw_expire_warning set? \(**/ fg_pswduser:1, /\(** Is fd_pswduser set? \(**/ fg_pick_pwd:1, /\(** Is fd_pick_pwd set? \(**/ fg_gen_pwd:1, /\(** Is fd_gen_pwd set? \(**/ fg_restrict:1, /\(** Is fd_restrict set? \(**/ fg_nullpw:1, /\(** Is fd_nullpw set? \(**/ fg_pwchanger:1, /\(** Is fd_pwchanger set? \(**/ fg_pw_admin_num:1, /\(** Is fd_pw_admin_num set? \(**/ fg_gen_chars:1, /\(** Is fd_gen_chars set? \(**/ fg_gen_letters:1, /\(** Is fd_gen_letters set? \(**/ fg_tod:1, /\(** Is fd_tod set? \(**/ .IP /\(** Login parameters: \(**/ fg_slogin:1, /\(** Is fd_slogin set? \(**/ fg_suctty: 1, /\(** is fd_suctty set ? \(**/ fg_unsuctty: 1, /\(** is fd_unsuctty set ? \(**/ fg_ulogin:1, /\(** Is fd_ulogin set? \(**/ fg_nlogins:1, /\(** Is fd_nlogins set? \(**/ fg_max_tries:1, /\(** Is fd_max_tries set? \(**/ fg_lock:1; /\(** Is fd_lock set? \(**/ }; .IP struct pr_passwd { struct pr_field ufld; /\(** user specific fields \(**/ struct pr_flag uflg; /\(** user specific flags \(**/ struct pr_field sfld; /\(** system wide fields \(**/ struct pr_flag sflg; /\(** system wide flags \(**/ }; .fi .PP The protected password database stores user authentication profiles. The .C pr_passwd structure in the user-specific entry refers to parameters specific to a user. The .C pr_passwd structure in the system default database sets parameters that are used when there is no user-specific override. .PP The user-specific entry is keyed on the .I fd_name field, which is a cross reference to the .C /etc/passwd entry for the user. The .I fd_uid field must match the UID in that file as well. The .I fd_encrypt field is the encrypted password. The password is encrypted in eight character segments, so the size of this field is a multiple of the number of characters in an encrypted segment (\c .C AUTH_CIPHERTEXT_SIZE macro). .PP .I fd_owner is the user name accountable for the account. \c The .I fd_boot_auth field is used when the system default file specifies boot authorization is required. .I init(1M) prompts for a user name and password. If the authentication succeeds, a value in this field allows the user to continue the system boot process. \c .PP .I fd_min is the time, in seconds, that must elapse before the user can change passwords. .I fd_maxlen is the maximum password length (in characters) for the user. .I fd_expire is the time, in seconds, until the user's password expires. .I fd_lifetime is the number of seconds that must elapse before the password dies. The account is considered locked if the password is dead. .PP .I fd_schange and .I fd_uchange record the last successful and unsuccessful password change times. .PP The .I fd_acct_expire field specifies the absolute period of time in seconds that the account can be used. An absolute expiration date may be specified, which is then converted into seconds stored in this field. This is different from .I fd_expire in that .I fd_acct_expire specifies an absolute expiration date, while .I fd_expire is reset with each password change. .PP .I fd_max_llogin specifies the maximum time in seconds allowed since the last login before the account becomes locked. .I fd_pw_expire_warning is the time in seconds before the end of .I fd_expire that the system warns the user the password is about to expire. .I fd_pswduser stores the user ID of the user allowed to change passwords for the account. \c Typically, this is the account owner. \c .PP The next flag fields control password generation. .IR fd_pick_pwd , if set, allows the user to pick his or her own password. .IR fd_nullpw , if set, allows the account to be used without a password. .I fd_gen_pwd enables the use of the random pronounceable password generator for passwords for this account. .I fd_gen_chars and .I fd_gen_letters allow the password generator to generate passwords composed of random printable characters and random letters, neither of which is easy to remember. The password change software allows the user to pick from whichever options are available for his or her account. One of these three fields .RI ( fd_gen_pwd , .IR fd_gen_chars , or .IR fd_gen_letters ) must be set. .PP .I fd_pwchanger is the user ID of the user who last changed the password on the user's account, if it was not the account owner. .IR fd_restrict , if set, causes triviality checks to be made after the account password has been chosen to avoid palindromes, user name and machine name permutations, and words appearing in the dictionary. .PP The .I fd_tod specifier is a string, formatted like the UUCP .C Systems file, which specifies time intervals during which the user can log in. \c .PP The next fields are used to protect against login spoofing, listing the time and location of last login. .I fd_slogin and .I fd_ulogin are time stamps of the last successful and unsuccessful login attempts. .I fd_suctty and .I fd_unsuctty are the terminal device or (if supported) host names of the terminal or host from which the last login attempt occurred. .PP .I fd_nlogins is the number of unsuccessful login attempts since the last successful login. It is reset to zero after a successful login. .I fd_max_tries is the number of unsuccessful attempts until the account is considered locked. .PP .I fd_lock indicates whether the administrative lock on the account is set. The account is considered disabled (locked) if one or more of these activities has occurred: .PD 0 .PP 1. if the password is dead, .PP 2. if the maximum number of unsuccessful attempts has been exceeded, .PP 3. if the administrative lock is set, .PP 4. if the account expiration is reached, or .PP 5. if the time since last login is exceeded. .PD .PP When .CR getprpwent () is first called, it returns a pointer to the first user .C pr_passwd structure in the database; thereafter, it returns a pointer to the next .C pr_passwd structure in the database so that successive calls can be used to search the database. Note that entries without a corresponding entry in .C /etc/passwd are skipped. The entries are scanned in the order they appear in .CR /etc/passwd . .PP .CR getprpwuid () searches from the beginning of the database until a numerical user ID matching .I uid is found and returns a pointer to the particular structure in which it was found. \c .CR getprpwaid () functions like .CR getprpwuid () only it uses the audit ID instead of the uid. \c .PP .CR getprpwnam () searches from the beginning of the database until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a NULL pointer. .PP A call to .CR setprpwent () has the effect of rewinding the protected password database to allow repeated searches. .CR endprpwent () can be called to close the protected password database when processing is complete. .PP .CR putprpwnam () puts a new or replaced protected password entry .I pr with key .I name into the database. If the .I uflg.fg_name field is 0, the requested entry is deleted from the protected password database. .CR putprpwnam () locks the database for all update operations, and performs a .CR endprpwent () after the update or failed attempt. .SS Notes .PP The value returned by .CR getprpwent () and .CR getprpwnam () refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .CR putprpwnam (). .PP On systems supporting network connections, the .I fd_suctty and .I fd_unsuctty fields can be the ASCII representation of the network address of the host from which the last successful or unsuccessful remote login to the account occurred. Use .IR getdvagnam (3) to investigate the type of device to determine whether a host or a terminal was used for the last successful or unsuccessful login. .PP Programs using these routines must be compiled with .CR \-lsec . .PP .CR getprpwent () assumes one name per UID and one UID per name. The sequential scan loops between the first two instances of a multiple UID. .PP .CR getprpwent () uses .IR getpwent (3) routines to sequentially scan databases. User program references to password entries obtained using .IR getpwent (3) routines will not be valid after using any routines described here (ie., the * .CR prp * routines). .SH RETURN VALUE .CR getprpwent (), .CR getprpwuid (), and .CR getprpwnam () return NULL pointers on EOF or error. .CR putprpwnam () returns 0 if it cannot add or update the entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 35 .C /etc/passwd System Password file .PD 0 .TP .C /tcb/files/auth/\(**/\(** Protected Password database .TP .C /tcb/files/auth/system/default System Defaults database .PD .SH SEE ALSO authcap(4), getpwent(3), getprdfent(3), prpwd(4). .\" .\" index@\f4getprpwuid\f1 \- get protected password database user ID@@@\f3getprpwent(3)\f1 .\" index@\f4getprpwaid\f1 \- get protected password database audit ID@@@\f3getprpwent(3)\f1 .\" index@\f4getprpwnam\f1 \- get protected password database user name@@@\f3getprpwent(3)\f1 .\" index@\f4setprpwent\f1 \- set protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f4endprpwent\f1 \- manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f4putprpwnam\f1 \- manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1access protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1protected password database entry, manipulate@@@\f3getprpwent(3)\f1 .\" index@\f1password database entry, manipulate protected@@@\f3getprpwent(3)\f1 .\" index@\f1database entry, manipulate protected password@@@\f3getprpwent(3)\f1 .\" index@\f1entry, manipulate protected password database@@@\f3getprpwent(3)\f1 .\" .\" toc@\f3getprpwent(3)\f1:\0\0\f4getprpwent\f1, \f4getprpwuid\f1, \f4getprpwnam\f1, \f4getprpwaid\f1, \f4setprpwent\f1,\n\f4endprpwent\f1, \f4putprpwnam\f1@@@manipulate protected password database entry .\" toc@\f4getprpwuid\f1:\0\0get protected password database user ID@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4getprpwaid\f1:\0\0get protected password database audit ID@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4getprpwnam\f1:\0\0get protected password database user name@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4setprpwent\f1:\0\0set protected password database entry@@@\f1 see \f3getprpwent(3)\f1 .\" toc@\f4endprpwent\f1:\0\0manipulate protected password database entry@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4putprpwnam\f1:\0\0manipulate protected password database entry@@@\f1 see \f3getprpwent(3)\f1 .\" .\" links@getprpwent.3 getprpwuid.3 .\" links@getprpwent.3 getprpwnam.3 .\" links@getprpwent.3 setprpwent.3 .\" links@getprpwent.3 endprpwent.3 .\" links@getprpwent.3 putprpwnam.3 .\" links@getprpwent.3 getprpwaid.3 .\" .\" $Header: getprtcent.3,v 78.2 96/01/19 20:15:15 ssa Exp $ .TA g .TH getprtcent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprtcent, getprtcnam, setprtcent, endprtcent, putprtcnam \- manipulate terminal control database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct pr_term \(**getprtcent(void);" .PP .CR "struct pr_term \(**getprtcnam(const char \(**name);" .PP .CR "void setprtcent(void);" .PP .CR "void endprtcent(void);" .PP .CR "int putprtcnam(const char \(**name, struct pr_term \(**pr);" .fi .SH DESCRIPTION .IR getprtcent and .I getprtcnam each returns a pointer to an object with the following structure containing the broken-out fields of an entry in the terminal control database. Each entry in the database contains a .I pr_term structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v .ift .ta 2i .ifn .ta 3i .ne 15 struct t_field { char fd_devname[14]; /* Terminal (or host) name */ uid_t fd_uid; /* uid of last successful login */ time_t fd_slogin; /* time stamp of successful login */ uid_t fd_uuid; /* uid of last unsuccessful login */ time_t fd_ulogin; /* time stamp of unsuccessful login */ ushort fd_nlogins; /* consecutive failed attempts */ ushort fd_max_tries; /* maximum unsuc login tries allowed */ time_t fd_logdelay; /* delay between login tries */ char fd_lock; /* terminal locked? */ ushort fd_login_timeout ; /* login timeout in seconds */ }; .IP .ne 17 struct t_flag { unsigned short fg_devname:1, /* Is fd_devname set? */ fg_uid:1, /* Is fd_uid set? */ fg_slogin:1, /* Is fd_stime set? */ fg_uuid:1, /* Is fd_uuid set? */ fg_ulogin:1, /* Is fd_ftime set? */ fg_nlogins:1, /* Is fd_nlogins set? */ fg_max_tries:1, /* Is fd_max_tries set? */ fg_logdelay:1, /* Is fd_logdelay set? */ fg_lock:1, /* Is fd_lock set? */ fg_login_timeout:1 /* is fd_login_timeout valid? */ ; }; .IP .ne 6 struct pr_term { struct t_field ufld; struct t_flag uflg; struct t_field sfld; struct t_flag sflg; }; .fi .DT .PP The system stores the user ID and time of the last successful login ( .I fd_uid and .I fd_slogin ) and unsuccessful login ( .I fd_uuid and .I fd_ulogin ) in the appropriate Terminal Control database entry. The system increments .I fd_nlogins with each unsuccessful login, and resets the field to 0 on a successful login. The .I fd_max_tries field is a limit on the number of unsuccessful logins until the account is locked. An administrative lock can also be applied, indicated by a non-zero .I fd_lock field. .I fd_logdelay stores the amount of time (in seconds) that the system waits between unsuccessful login attempts, and .I fd_login_timeout stores the number of seconds from the beginning of an authentication attempt until the login attempt is terminated. .PP Note that .I ufld and .I uflg refer to user specific entries, and .I sfld and .I sflg refer to the system default values (see .IR authcap (4)). .PP The value returned by .I getprtcent or .I getprtcnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .IR putprtcnam . .PP .I getprtcent returns a pointer to the first terminal .I pr_term structure in the database when first called. Thereafter, it returns a pointer to the next .I pr_term structure in the database, so successive calls can be used to search the database. .I getprtcnam searches from the beginning of the database until a terminal name matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a .B NULL pointer. .PP A call to .I setprtcent has the effect of rewinding the Terminal Control database to allow repeated searches. .I endprtcent can be called to close the Terminal Control database when processing is complete. .PP .I putprtcnam puts a new or replaced terminal control entry .I pr with key .I name into the database. If the .I fg_devname field is 0, the requested entry is deleted from the Terminal Control database. .I putprtcnam locks the database for all update operations, and performs an .I endprtcent after the update or failed attempt. .SH RETURN VALUE .I getprtcent and .I getprtcnam return .SM .B NULL pointers on .SM EOF or error. .I putprtcnam returns 0 if it cannot add or update the entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 45 .C /tcb/files/ttys Terminal Control database .PD 0 .TP .C /tcb/files/auth/system/default System Defaults database .PD .SH SEE ALSO getprdfent(3), authcap(4), ttys(4). .SH NOTES The .I fd_devname field, on systems supporting connections, may refer to the .SM ASCII representation of a host name. This can be determined by using .IR getdvagnam (3) to interrogate the Device Assignment database as to the type of the device, passing in the .I fd_devname field of the Terminal Control structure as an argument. This allows lockout by machine, instead of the device (typically pseudo tty) on which the session originated. .PP Programs using these routines must be compiled with .BR \-lsec . .PP The .I sfld and .I sflg structures are filled from corresponding fields in the system default database. Thus, a program can easily extract the user-specific or system-wide parameters for each database field (see .I getprpwent and .IR getdvagent ). .\" .\" index@\f4getprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4getprtcnam\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4setprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4endprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4putprtcnam\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f1manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f1terminal control database entry, manipulate@@@\f3getprtcent(3)\f1 .\" index@\f1database entry, manipulate terminal control@@@\f3getprtcent(3)\f1 .\" index@\f1entry, manipulate terminal control database@@@\f3getprtcent(3)\f1 .\" .\" toc@\f3getprtcent(3)\f1:\0\0\f4getprtcent\f1, \f4getprtcnam\f1, \f4setprtcent\f1, \f4endprtcent\f1,\n\f4putprtcnam\f1@@@manipulate terminal control database entry for a trusted system .\" toc@\f4getprtcent\f1:\0\0return pointer to terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc \f4getprtcnam\f1:\0\0search terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4setprtcent\f1:\0\0rewind terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4endprtcent\f1:\0\0close terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4putprtcnam\f1:\0\0put entry into terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" .\" links@getprtcent.3 getprtcnam.3 .\" links@getprtcent.3 setprtcent.3 .\" links@getprtcent.3 endprtcent.3 .\" links@getprtcent.3 putprtcnam.3 .\" .\" $Header: putpwent.3c,v 72.5 94/11/15 09:55:48 ssa Exp $ .TA p .TH putpwent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putpwent(\|) \- write password file entry .SH SYNOPSIS .C "#include " .PP .C "#include " .PP .C "int putpwent(const struct passwd *p, FILE *f);" .SH DESCRIPTION .CR putpwent () is the inverse of .CR getpwent () (see .IR getpwent (3C)). Given a pointer to a .C passwd structure as created by .CR getpwent (), .CR getpwuid (), or .CR getpwnam (); .CR putpwent () writes a line on the stream .IR f , which matches the format of .CR /etc/passwd . .PP .CR putpwent () ignores the audit .SM ID and audit flag in the .C passwd structure; and .I does not create the corresponding entries used in the protected password database, used for trusted systems. .CR putprpwnam (), which produces entries that match the trusted password database file format, must be used to create these entries. See .IR getprpwent (3). .SH DIAGNOSTICS .CR putpwent () returns non-zero if an error was detected during its operation; otherwise it returns zero. .SH FILES .TP 30 .C /etc/passwd System Password file .SH SEE ALSO getpwent(3C), putprpwent(3), passwd(4), prpwd(4), stdio(3S), fopen(3S). .SH STANDARDS CONFORMANCE .CR putpwent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4putpwent()\fP \- write password file entry@@@\f3putpwent(3C)\f1 .\" index@write password file entry@@@\f3putpwent(3C)\f1 .\" index@password file entry, write@@@\f3putpwent(3C)\f1 .\" index@entry, write password file@@@\f3putpwent(3C)\f1 .\" .\" toc@\f3putpwent(3C)\f1:\0\0\f4putpwent()\fP@@@write password file entry .\" .\" fileset_database@putpwent.3c PROGRAMING-MAN .\" $Header: puts.3s,v 72.5 94/11/15 09:55:49 ssa Exp $ .TA p .TH puts 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME puts(\|), puts_unlocked(\|), fputs(\|), fputs_unlocked(\|) \- put a string on a stream .SH SYNOPSIS .C "#include " .PP .C "int puts(const char *s);" .PP .C "int puts_unlocked(const char *s);" .PP .C "int fputs(const char *s, FILE *stream);" .PP .C "int fputs_unlocked(const char *s, FILE *stream);" .SH DESCRIPTION .CR puts() writes the null-terminated string pointed to by .IR s , followed by a new-line character, to the standard output stream .CR stdout . .PP .CR fputs() writes the null-terminated string pointed to by .I s to the named output .IR stream , but does .I not append a new-line character. .PP Neither function writes the terminating null character. .PP .CR puts_unlocked() and .CR fputs_unlocked() are identical to .CR puts() and .CR fputs() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon successful completion, these routines return a non-negative number. Otherwise they return EOF, set the error indicator for the stream, and set .CR errno to indicate the error. .SH ERRORS These routines fail if, either the .I stream is unbuffered or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A SIGPIPE signal is also sent to the process. .RE .PP Additional .CR errno values may be set by the underlying .CR write() function (see .IR write(2)). .SH SEE ALSO ferror(3S), flockfile(3S), fopen(3S), fread(3S), printf(3S), putc(3S). .SH NOTES .CR puts() and .CR puts_unlocked() append a new-line character; .CR fputs() and .CR fputs_unlocked() do not. .SH STANDARDS CONFORMANCE .CR puts() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fputs() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4puts()\f1 \- write null-terminated string to stream \f4stdout()\f1@@@\f3puts(3S)\f1 .\" index@\f4fputs()\f1 \- write null-terminated string to a named stream file@@@\f3puts(3S)\f1 .\" index@\f1put a string on a stream@@@\f3puts(3S)\f1 .\" index@\f1write a null-terminated string on a stream@@@\f3puts(3S)\f1 .\" .\" toc@\f3puts(3S)\f1:\0\0\f4puts()\f1, \f4fputs()\f1@@@put a string on a stream .\" toc@\f4fputs()\f1:\0\0put a string on a stream@@@see \f3puts(3S)\f1 .\" .\" links@puts.3s fputs.3s .\" links@puts.3s puts_unlock.3s .\" links@puts.3s fputs_unloc.3s .\" .\" fileset_database@puts.3s PROGRAMING-MAN .\" $Header: puts.3s,v 72.5 94/11/15 09:55:49 ssa Exp $ .TA p .TH puts 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME puts(\|), puts_unlocked(\|), fputs(\|), fputs_unlocked(\|) \- put a string on a stream .SH SYNOPSIS .C "#include " .PP .C "int puts(const char *s);" .PP .C "int puts_unlocked(const char *s);" .PP .C "int fputs(const char *s, FILE *stream);" .PP .C "int fputs_unlocked(const char *s, FILE *stream);" .SH DESCRIPTION .CR puts() writes the null-terminated string pointed to by .IR s , followed by a new-line character, to the standard output stream .CR stdout . .PP .CR fputs() writes the null-terminated string pointed to by .I s to the named output .IR stream , but does .I not append a new-line character. .PP Neither function writes the terminating null character. .PP .CR puts_unlocked() and .CR fputs_unlocked() are identical to .CR puts() and .CR fputs() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE Upon successful completion, these routines return a non-negative number. Otherwise they return EOF, set the error indicator for the stream, and set .CR errno to indicate the error. .SH ERRORS These routines fail if, either the .I stream is unbuffered or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A SIGPIPE signal is also sent to the process. .RE .PP Additional .CR errno values may be set by the underlying .CR write() function (see .IR write(2)). .SH SEE ALSO ferror(3S), flockfile(3S), fopen(3S), fread(3S), printf(3S), putc(3S). .SH NOTES .CR puts() and .CR puts_unlocked() append a new-line character; .CR fputs() and .CR fputs_unlocked() do not. .SH STANDARDS CONFORMANCE .CR puts() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fputs() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4puts()\f1 \- write null-terminated string to stream \f4stdout()\f1@@@\f3puts(3S)\f1 .\" index@\f4fputs()\f1 \- write null-terminated string to a named stream file@@@\f3puts(3S)\f1 .\" index@\f1put a string on a stream@@@\f3puts(3S)\f1 .\" index@\f1write a null-terminated string on a stream@@@\f3puts(3S)\f1 .\" .\" toc@\f3puts(3S)\f1:\0\0\f4puts()\f1, \f4fputs()\f1@@@put a string on a stream .\" toc@\f4fputs()\f1:\0\0put a string on a stream@@@see \f3puts(3S)\f1 .\" .\" links@puts.3s fputs.3s .\" links@puts.3s puts_unlock.3s .\" links@puts.3s fputs_unloc.3s .\" .\" fileset_database@puts.3s PROGRAMING-MAN .\" $Header: putspwent.3x,v 72.2 94/07/03 14:56:33 ssa Exp $ .TA p .TH putspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putspwent(\|) \- write secure password file entry, for trusted systems .SH SYNOPSIS .C "#include " .PP .C "int putspwent(const struct s_passwd *p, FILE *f);" .SH DESCRIPTION .CR putspwent () is the inverse of .CR getspwent (). See .IR getspwent (3X). .CR putspwent () is no longer supported, but is provided for use by those applications that did not use the old shadow password, .CR /.secure/etc/passwd . .PP To update a entry in the new protected password database for trusted systems, use .IR putprpwnam (3). See .IR getprpwent (3) for more information. .SH AUTHOR .CR putspwent () was developed by HP. .SH SEE ALSO getpwent(3C), getspwent(3X), putpwent(3C), getprpwent(3), prpwd(4). .\" .\" index@\f4putspwent()\fP \- write secure password file entry@@@\f3putspwent(3C)\f1 .\" index@write secure password file entry@@@\f3putspwent(3X)\f1 .\" index@secure password file entry, write@@@\f3putspwent(3X)\f1 .\" index@password file entry, secure, write@@@\f3putspwent(3X)\f1 .\" .\" toc@\f3putspwent(3X)\f1:\0\0\f4putspwent()\fP@@@write secure password file entry .\" .\" fileset_database@putspwent.3c PROGRAMING-MAN .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getutx.3c,v 76.4 95/09/12 12:01:34 ssa Exp $ .TA g .TH getutx 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutxent(\|), getutxid(\|), getutxline(\|), pututxline(\|), setutxent(\|), endutxent(\|) \- access utmpx file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmpx *getutxent(void);" .PP .C "struct utmpx *getutxid(const struct utmpx *id);" .nf .PP .C "struct utmpx *getutxline(const struct utmpx *line);" .PP .C "struct utmpx *_pututxline(const struct utmpx *utmpx);" .PP .C "void pututxline(const struct utmpx *utmpx);" .PP .C "void setutxent(void);" .PP .C "void endutxent(void);" .PP .fi .SH DESCRIPTION .CR getutxent() , .CR getutxid() , and .C getutxline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmpx { char ut_user[24]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct __exit_status { short __e_termination; /* Process termination status */ short __e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ struct timeval { time_t tv_sec; /* seconds */ long tv_usec; /* and microseconds */ } ut_tv; /* time entry was made */ char ut_host[64]; /* host name, if remote; NOT SUPPORTED */ unsigned long ut_addr; /* Internet addr of host, if remote */ char ut_reserved2[12] ; /* Reserved for future use */ }; .ps .ft .fi .RE .TP 20 .C getutxent() Reads in the next entry from a .CR utmpx -like file. If the file is not already open, .C getutxent() opens it. If it reaches the end of the file, .C getutxent() fails. .TP .C getutxid() Searches forward from the current point in the .I utmpx file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutxid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutxid() fails. .TP .C getutxline() Searches forward from the current point in the .I utmpx file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutxline() fails. .TP .C pututxline() Writes out the supplied .C utmpx structure into the .I utmpx file, translates the supplied .C utmpx structure into a .C utmp structure and writes it to a .I utmp file. .C pututxline() uses .C getutxid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getutx() routines before calling .CR pututxline() . If the search as already been made, .C pututxline() does not repeat it. If .C pututxline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututxline() Performs the same actions as .CR pututxline() , except that it returns a value useful for error checking. .TP .C setutxent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutxent() Closes the currently open file. .TP .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutxid() or .CR getutxline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutxline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutxline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututxline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutxent() , .CR getutxid() , or .C getutxline() if the user has just modified those contents and passed the pointer back to .CR pututxline() . .PP .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmpx)" . .PP .C _pututxline() behaves the same as .CR pututxline() , except that it returns a pointer to a static location containing the most current utmpx entry if the .C _pututxline() call succeeds. The contents of this structure are identical to the contents of the supplied .C utmpx structure if successful. If .C _pututline() fails upon writing to .C utmpx , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmpx file and fails in writing to the .C utmp file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmpx file and the .C utmp file may not be in sync due to the above behavior. .C pututxline() and .C _pututxline() are only guaranteed to have written to the .C utmpx file upon successful completion. .SH FILES .PP .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututline(3), utmpname(3). .SH STANDARDS CONFORMANCE .CR endutxent() ": XPG4.2" .PP .CR getutxent() ": XPG4.2" .PP .CR getutxid() ": XPG4.2" .PP .CR getutxline() ": XPG4.2" .PP .CR pututxline() ": XPG4.2" .PP .CR setutxent() ": XPG4.2" .PP .\" .\" index@\f4getutxent()\f1 \- get pointer to next entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4_pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4setutxent()\f1 \- reset input stream to beginning of \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4endutxent()\f1 \- close currently open \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@access \f4utmpx()\f1 or \f4wtmp()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4utmpx()\f1 or \f4wtmp()\f1 file, access@@@\f3getutx(3C)\f1 .\" index@file: access \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" .\" toc@\f3getutx(3C)\f1:\0\0\f4getutxent()\f1, \f4getutxid()\f1, \f4getutxline()\f1, \f4pututxline()\f1, \f4setutxent()\f1,\n\f4endutxent()\f1@@@access utmpx file entry .\" toc@\f4getutxent()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxid()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4_pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4setutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4endutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f1utmpx file entry@@@see \f3getutx(3C)\f1 .\" .\" links@getutx.3c getutxent.3c .\" links@getutx.3c getutxid.3c .\" links@getutx.3c getutxline.3c .\" links@getutx.3c pututxline.3c .\" links@getutx.3c _pututxline.3c .\" links@getutx.3c setutxent.3c .\" links@getutx.3c endutxent.3c .\" $Header: putc.3s,v 76.1 95/07/05 17:44:59 ssa Exp $ .TA p .TH putc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putc(\|), putc_unlocked(\|), putchar(\|), putchar_unlocked(\|), fputc(\|), putw(\|), putw_unlocked(\|) \- put character or word on a stream .SH SYNOPSIS .C "#include " .PP .C "int putc(int c, FILE *stream);" .PP .C "int putc_unlocked(int c, FILE *stream);" .PP .C "int putchar(int c);" .PP .C "int putchar_unlocked(int c);" .PP .C "int fputc(int c, FILE *stream);" .PP .C "int putw(int w, FILE *stream);" .PP .C "int putw_unlocked(int w, FILE *stream);" .SH DESCRIPTION .TP 15 .CR putc() Writes the character .I c onto the output .I stream at the position where the file pointer, if defined, is pointing. .CI putchar( c ) is defined as .CI putc( c , .CR stdout) . .CR putc() and .CR putchar() are defined both as macros and as functions. .TP .CR fputc() Same as .CR putc() , but is a function rather than a macro, and can therefore be used as an argument. .CR fputc() runs more slowly than .CR putc() , but takes less space per invocation, and its name can be passed as an argument to a function. .TP .CR putw() Writes the word (i.e., .CR int in C) .I w to the output .I stream (at the position at which the file pointer, if defined, is pointing). The size of a word is the size of an integer and varies from machine to machine. .CR putw() neither assumes nor causes special alignment in the file. .PP Output streams, with the exception of the standard error stream .CR stderr , are by default buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream, .CR stderr , is by default unbuffered, but use of .CR freopen() (see .IR fopen (3S)) causes it to become buffered or line-buffered. .CR setbuf() or .CR setvbuf() (see .IR setbuf (3S)) can be used to change the stream's buffering strategy. .PP .CR putc_unlocked() , " putchar_unlocked()" , and .CR putw_unlocked() are identical to .CR putc() , " putchar()" , and .CR putw() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE On success, .CR putc() , .CR putc_unlocked() , .CR fputc() , .CR putchar() , and .CR putchar_unlocked() each return the value they have written. On failure, they return the constant .SM EOF, set the error indicator for the stream, and set .CR errno to indicate the error. .PP On success, .CR putw() and .CR putw_unlocked() return 0. Otherwise, a non-zero value is returned, the error indicator for the stream is set, and .CR errno is set to indicate the error. .SH ERRORS .CR putc() , .CR putc_unlocked() , .CR putchar() , .CR putchar_unlocked() , .CR fputc() , .CR putw() , and .CR putw_unlocked() fail if, either the .I stream is unbuffered or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 .SM [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP .SM [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP .SM [EINTR] A signal was caught during the .CR write() system call. .TP .SM [EIO] A physical I/O error has occurred, or the process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt is made to write to a pipe or .SM FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH WARNINGS The .CR putc() and .CR putchar() routines are implemented as both library functions and macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parentheses or use the function address. The following example illustrates each of these methods: .nf .IP .CR #include .CR #undef putc \h'.2i'... .CR main() .CR { .CR " int (*put_char()) ();" \h'.6i'... .CR " return_val=putc(c,fd);" \h'.6i'... .CR " return_val=(putc)(c,fd1);" \h'.6i'... .CR " put_char = putchar;" .CR }; .fi .PP Line buffering may cause confusion or malfunctioning of programs that use standard .SM I/O routines but use .CR read() themselves to read from standard input. When a large amount of computation is done after printing part of a line on an output terminal, it is necessary to .CR fflush() (see .IR fclose (3S)) the standard output before beginning the computation. .PP The macro version of .CR putc() incorrectly treats the argument .I stream with side effects. In particular, the following call may not work as expected: .IP .CR putc(c, *f++); .PP The function version of .CR putc() or .CR fputc() should be used instead. .PP Because of possible differences in word length and byte ordering, files written using .CR putw() are machine-dependent, and may not be readable by .CR getw() on a different processor. .SS Reentrant Interfaces If .CR _REENTRANT is defined, the locked versions of the library functions for .CR putc() and .CR putchar() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR putc() and .CR putchar() . .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), getc(3S), fread(3S), printf(3S), puts(3S), setbuf(3S). .SH STANDARDS CONFORMANCE .CR putc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fputc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR putchar() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR putw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4putc()\fP, \f4fputc()\fP \- put character on a stream@@@\f3putc(3S)\f1 .\" index@\f4fputc()\fP, \f4putc()\fP \- put character on a stream@@@\f3putc(3S)\f1 .\" index@\f4putchar()\fP \- put character on stream \f2standard output\f1@@@\f3putc(3S)\f1 .\" index@\f4putw()\fP \- put word (integer) on a stream@@@\f3putc(3S)\f1 .\" index@character or word, put on a stream@@@\f3putc(3S)\f1 .\" index@put character or word on a stream@@@\f3putc(3S)\f1 .\" index@put word or character on a stream@@@\f3putc(3S)\f1 .\" index@word or character, put on a stream@@@\f3putc(3S)\f1 .\" index@stream, put word or character on a@@@\f3putc(3S)\f1 .\" .\" toc@\f3putc(3S)\f1:\0\0\f4putc()\fP, \f4putchar()\fP, \f4fputc()\fP, \f4putw()\fP@@@put character or word on a stream .\" toc@\f4putchar()\fP:\0\0put character on a stream@@@see \f3putc(3S)\f1 .\" toc@\f4fputc()\fP:\0\0put character on a stream@@@see \f3putc(3S)\f1 .\" toc@\f4putw()\fP:\0\0put word on a stream@@@see \f3putc(3S)\f1 .\" .\" links@putc.3s putc_unlock.3s .\" links@putc.3s putchar.3s .\" links@putc.3s putchar_unl.3s .\" links@putc.3s fputc.3s .\" links@putc.3s putw.3s .\" links@putc.3s putw_unlock.3s .\" $Header: putc.3s,v 76.1 95/07/05 17:44:59 ssa Exp $ .TA p .TH putc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putc(\|), putc_unlocked(\|), putchar(\|), putchar_unlocked(\|), fputc(\|), putw(\|), putw_unlocked(\|) \- put character or word on a stream .SH SYNOPSIS .C "#include " .PP .C "int putc(int c, FILE *stream);" .PP .C "int putc_unlocked(int c, FILE *stream);" .PP .C "int putchar(int c);" .PP .C "int putchar_unlocked(int c);" .PP .C "int fputc(int c, FILE *stream);" .PP .C "int putw(int w, FILE *stream);" .PP .C "int putw_unlocked(int w, FILE *stream);" .SH DESCRIPTION .TP 15 .CR putc() Writes the character .I c onto the output .I stream at the position where the file pointer, if defined, is pointing. .CI putchar( c ) is defined as .CI putc( c , .CR stdout) . .CR putc() and .CR putchar() are defined both as macros and as functions. .TP .CR fputc() Same as .CR putc() , but is a function rather than a macro, and can therefore be used as an argument. .CR fputc() runs more slowly than .CR putc() , but takes less space per invocation, and its name can be passed as an argument to a function. .TP .CR putw() Writes the word (i.e., .CR int in C) .I w to the output .I stream (at the position at which the file pointer, if defined, is pointing). The size of a word is the size of an integer and varies from machine to machine. .CR putw() neither assumes nor causes special alignment in the file. .PP Output streams, with the exception of the standard error stream .CR stderr , are by default buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream, .CR stderr , is by default unbuffered, but use of .CR freopen() (see .IR fopen (3S)) causes it to become buffered or line-buffered. .CR setbuf() or .CR setvbuf() (see .IR setbuf (3S)) can be used to change the stream's buffering strategy. .PP .CR putc_unlocked() , " putchar_unlocked()" , and .CR putw_unlocked() are identical to .CR putc() , " putchar()" , and .CR putw() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE On success, .CR putc() , .CR putc_unlocked() , .CR fputc() , .CR putchar() , and .CR putchar_unlocked() each return the value they have written. On failure, they return the constant .SM EOF, set the error indicator for the stream, and set .CR errno to indicate the error. .PP On success, .CR putw() and .CR putw_unlocked() return 0. Otherwise, a non-zero value is returned, the error indicator for the stream is set, and .CR errno is set to indicate the error. .SH ERRORS .CR putc() , .CR putc_unlocked() , .CR putchar() , .CR putchar_unlocked() , .CR fputc() , .CR putw() , and .CR putw_unlocked() fail if, either the .I stream is unbuffered or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 .SM [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP .SM [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP .SM [EINTR] A signal was caught during the .CR write() system call. .TP .SM [EIO] A physical I/O error has occurred, or the process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt is made to write to a pipe or .SM FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH WARNINGS The .CR putc() and .CR putchar() routines are implemented as both library functions and macros. The macro versions, which are used by default, are defined in .RC < stdio.h >. To obtain the library function either use a .CR #undef to remove the macro definition or, if compiling in .SM ANSI\c -C mode, enclose the function name in parentheses or use the function address. The following example illustrates each of these methods: .nf .IP .CR #include .CR #undef putc \h'.2i'... .CR main() .CR { .CR " int (*put_char()) ();" \h'.6i'... .CR " return_val=putc(c,fd);" \h'.6i'... .CR " return_val=(putc)(c,fd1);" \h'.6i'... .CR " put_char = putchar;" .CR }; .fi .PP Line buffering may cause confusion or malfunctioning of programs that use standard .SM I/O routines but use .CR read() themselves to read from standard input. When a large amount of computation is done after printing part of a line on an output terminal, it is necessary to .CR fflush() (see .IR fclose (3S)) the standard output before beginning the computation. .PP The macro version of .CR putc() incorrectly treats the argument .I stream with side effects. In particular, the following call may not work as expected: .IP .CR putc(c, *f++); .PP The function version of .CR putc() or .CR fputc() should be used instead. .PP Because of possible differences in word length and byte ordering, files written using .CR putw() are machine-dependent, and may not be readable by .CR getw() on a different processor. .SS Reentrant Interfaces If .CR _REENTRANT is defined, the locked versions of the library functions for .CR putc() and .CR putchar() are used by default. For multi-thread applications, if .CR _STDIO_UNLOCK_CHAR_IO is also defined before including .RC < stdio.h >, the unlocked macro versions will be used by default for .CR putc() and .CR putchar() . .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), getc(3S), fread(3S), printf(3S), puts(3S), setbuf(3S). .SH STANDARDS CONFORMANCE .CR putc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fputc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR putchar() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR putw() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4putc()\fP, \f4fputc()\fP \- put character on a stream@@@\f3putc(3S)\f1 .\" index@\f4fputc()\fP, \f4putc()\fP \- put character on a stream@@@\f3putc(3S)\f1 .\" index@\f4putchar()\fP \- put character on stream \f2standard output\f1@@@\f3putc(3S)\f1 .\" index@\f4putw()\fP \- put word (integer) on a stream@@@\f3putc(3S)\f1 .\" index@character or word, put on a stream@@@\f3putc(3S)\f1 .\" index@put character or word on a stream@@@\f3putc(3S)\f1 .\" index@put word or character on a stream@@@\f3putc(3S)\f1 .\" index@word or character, put on a stream@@@\f3putc(3S)\f1 .\" index@stream, put word or character on a@@@\f3putc(3S)\f1 .\" .\" toc@\f3putc(3S)\f1:\0\0\f4putc()\fP, \f4putchar()\fP, \f4fputc()\fP, \f4putw()\fP@@@put character or word on a stream .\" toc@\f4putchar()\fP:\0\0put character on a stream@@@see \f3putc(3S)\f1 .\" toc@\f4fputc()\fP:\0\0put character on a stream@@@see \f3putc(3S)\f1 .\" toc@\f4putw()\fP:\0\0put word on a stream@@@see \f3putc(3S)\f1 .\" .\" links@putc.3s putc_unlock.3s .\" links@putc.3s putchar.3s .\" links@putc.3s putchar_unl.3s .\" links@putc.3s fputc.3s .\" links@putc.3s putw.3s .\" links@putc.3s putw_unlock.3s .\" $Header: putwc.3c,v 76.1 95/07/05 17:45:14 ssa Exp $ .TA p .TH putwc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putwc(\|), putwc_unlocked(\|), putwchar(\|), putwchar_unlocked(\|), fputwc(\|), fputwc_unlocked(\|) \- put a wide character on a stream file .SH SYNOPSIS .C "#include " .PP .C "wint_t putwc(wint_t wc, FILE *stream);" .PP .C "wint_t putwc_unlocked(wint_t wc, FILE *stream);" .PP .C "wint_t putwchar(wint_t wc);" .PP .C "wint_t putwchar_unlocked(wint_t wc);" .PP .C "wint_t fputwc(wint_t wc, FILE *stream);" .PP .C "wint_t fputwc_unlocked(wint_t wc, FILE *stream);" .SS Remarks: These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. They parallel the 8-bit character I/O functions defined in .IR putc(3S) . .SH DESCRIPTION .TP 15 .CR putwc() Writes the character corresponding to the wide character .I wc onto the output .I stream at the position where the file pointer is pointing. .CI putwchar( wc ) is defined as .CI putwc( wc , .CR stdout) . .CR putwc() and .CR putwchar() are defined both as macros and as functions. .TP .C fputwc() Behaves like .CR putwc() , but is a function rather than a macro, and can therefore be used as an argument. .PP Output streams, with the exception of the standard error stream .CR stderr , are by default buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream, .CR stderr , is by default unbuffered, but use of .CR freopen() (see .IR fopen (3S)) causes it to become buffered or line-buffered. .CR setbuf() or .CR setvbuf() (see .IR setbuf (3S)) can be used to change the stream's buffering strategy. .PP Definitions for these functions, the type .I wint_t and the value WEOF are provided in the .RC < wchar.h > header. .PP .CR putwc_unlocked() , .CR putwchar_unlocked() , and .CR fputwc_unlocked() are identical to .CR putwc() , .CR putwchar() , and .CR fputwc_unlocked() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE On success, .CR putwc() , .CR putwc_unlocked() , .CR fputwc() , .CR fputwc_unlocked() , .CR putwchar() , and .CR putwchar_unlocked() each return the wide character corresponding to the value they have written. On failure, they return the constant .CR WEOF , set the error indicator for the stream, and set .CR errno to indicate the error. .SH ERRORS .CR putwc() , .CR putwc_unlocked() , .CR putwchar() , .CR putwchar_unlocked() , .CR fputwc() , and .CR fputwc_unlocked() fail if either the .I stream is unbuffered, or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] A physical I/O error has occurred, or the process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP [EILSEQ] The wide character .I wc does not correspond to a valid character. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH WARNINGS Line buffering may cause confusion or malfunctioning of programs that use wide character I/O routines but use .CR read() themselves to read from standard input. When a large amount of computation is done after printing part of a line on an output terminal, it is necessary to .CR fflush() (see .IR fclose (3S)) the standard output before beginning the computation. .SH AUTHOR .CR putwc() was developed by OSF and HP. .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), getwc(3C), fread(3S), printf(3S), fputws(3C), setbuf(3S). .SH STANDARDS CONFORMANCE .CR putwc() ": XPG4" .PP .CR fputwc() ": XPG4" .PP .CR putwchar() ": XPG4" .\" .\" index@\f4putwc()\f1, \f4fputwc()\f1 \- put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f4fputwc()\f1, \f4putwc()\f1 \- put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f4putwchar()\f1 \- put wide character on stream \f2standard output\f1@@@\f3putwc(3C)\f1 .\" index@\f1wide character, put on a stream@@@\f3putwc(3C)\f1 .\" index@\f1put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f1stream, put wide character on a@@@\f3putwc(3C)\f1 .\" .\" toc@\f3putwc(3C)\f1:\0\0\f4putwc()\f1, \f4putwchar()\f1, \f4fputwc()\f1@@@put wide character on a stream .\" toc@\f4putwchar()\f1:\0\0put wide character on a stream@@@see \f3putwc(3C)\f1 .\" toc@\f4fputwc()\f1:\0\0put wide character on a stream@@@see \f3putwc(3C)\f1 .\" .\" links@putwc.3c putwc_unloc.3c .\" links@putwc.3c putwchar.3c .\" links@putwc.3c putwchar_un.3c .\" links@putwc.3c fputwc_unlo.3c .\" links@putwc.3c fputwc.3c .\" $Header: putwc.3c,v 76.1 95/07/05 17:45:14 ssa Exp $ .TA p .TH putwc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putwc(\|), putwc_unlocked(\|), putwchar(\|), putwchar_unlocked(\|), fputwc(\|), fputwc_unlocked(\|) \- put a wide character on a stream file .SH SYNOPSIS .C "#include " .PP .C "wint_t putwc(wint_t wc, FILE *stream);" .PP .C "wint_t putwc_unlocked(wint_t wc, FILE *stream);" .PP .C "wint_t putwchar(wint_t wc);" .PP .C "wint_t putwchar_unlocked(wint_t wc);" .PP .C "wint_t fputwc(wint_t wc, FILE *stream);" .PP .C "wint_t fputwc_unlocked(wint_t wc, FILE *stream);" .SS Remarks: These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. They parallel the 8-bit character I/O functions defined in .IR putc(3S) . .SH DESCRIPTION .TP 15 .CR putwc() Writes the character corresponding to the wide character .I wc onto the output .I stream at the position where the file pointer is pointing. .CI putwchar( wc ) is defined as .CI putwc( wc , .CR stdout) . .CR putwc() and .CR putwchar() are defined both as macros and as functions. .TP .C fputwc() Behaves like .CR putwc() , but is a function rather than a macro, and can therefore be used as an argument. .PP Output streams, with the exception of the standard error stream .CR stderr , are by default buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream, .CR stderr , is by default unbuffered, but use of .CR freopen() (see .IR fopen (3S)) causes it to become buffered or line-buffered. .CR setbuf() or .CR setvbuf() (see .IR setbuf (3S)) can be used to change the stream's buffering strategy. .PP Definitions for these functions, the type .I wint_t and the value WEOF are provided in the .RC < wchar.h > header. .PP .CR putwc_unlocked() , .CR putwchar_unlocked() , and .CR fputwc_unlocked() are identical to .CR putwc() , .CR putwchar() , and .CR fputwc_unlocked() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE On success, .CR putwc() , .CR putwc_unlocked() , .CR fputwc() , .CR fputwc_unlocked() , .CR putwchar() , and .CR putwchar_unlocked() each return the wide character corresponding to the value they have written. On failure, they return the constant .CR WEOF , set the error indicator for the stream, and set .CR errno to indicate the error. .SH ERRORS .CR putwc() , .CR putwc_unlocked() , .CR putwchar() , .CR putwchar_unlocked() , .CR fputwc() , and .CR fputwc_unlocked() fail if either the .I stream is unbuffered, or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] A physical I/O error has occurred, or the process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP [EILSEQ] The wide character .I wc does not correspond to a valid character. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH WARNINGS Line buffering may cause confusion or malfunctioning of programs that use wide character I/O routines but use .CR read() themselves to read from standard input. When a large amount of computation is done after printing part of a line on an output terminal, it is necessary to .CR fflush() (see .IR fclose (3S)) the standard output before beginning the computation. .SH AUTHOR .CR putwc() was developed by OSF and HP. .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), getwc(3C), fread(3S), printf(3S), fputws(3C), setbuf(3S). .SH STANDARDS CONFORMANCE .CR putwc() ": XPG4" .PP .CR fputwc() ": XPG4" .PP .CR putwchar() ": XPG4" .\" .\" index@\f4putwc()\f1, \f4fputwc()\f1 \- put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f4fputwc()\f1, \f4putwc()\f1 \- put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f4putwchar()\f1 \- put wide character on stream \f2standard output\f1@@@\f3putwc(3C)\f1 .\" index@\f1wide character, put on a stream@@@\f3putwc(3C)\f1 .\" index@\f1put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f1stream, put wide character on a@@@\f3putwc(3C)\f1 .\" .\" toc@\f3putwc(3C)\f1:\0\0\f4putwc()\f1, \f4putwchar()\f1, \f4fputwc()\f1@@@put wide character on a stream .\" toc@\f4putwchar()\f1:\0\0put wide character on a stream@@@see \f3putwc(3C)\f1 .\" toc@\f4fputwc()\f1:\0\0put wide character on a stream@@@see \f3putwc(3C)\f1 .\" .\" links@putwc.3c putwc_unloc.3c .\" links@putwc.3c putwchar.3c .\" links@putwc.3c putwchar_un.3c .\" links@putwc.3c fputwc_unlo.3c .\" links@putwc.3c fputwc.3c .\" $Header: putwc.3c,v 76.1 95/07/05 17:45:14 ssa Exp $ .TA p .TH putwc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putwc(\|), putwc_unlocked(\|), putwchar(\|), putwchar_unlocked(\|), fputwc(\|), fputwc_unlocked(\|) \- put a wide character on a stream file .SH SYNOPSIS .C "#include " .PP .C "wint_t putwc(wint_t wc, FILE *stream);" .PP .C "wint_t putwc_unlocked(wint_t wc, FILE *stream);" .PP .C "wint_t putwchar(wint_t wc);" .PP .C "wint_t putwchar_unlocked(wint_t wc);" .PP .C "wint_t fputwc(wint_t wc, FILE *stream);" .PP .C "wint_t fputwc_unlocked(wint_t wc, FILE *stream);" .SS Remarks: These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. They parallel the 8-bit character I/O functions defined in .IR putc(3S) . .SH DESCRIPTION .TP 15 .CR putwc() Writes the character corresponding to the wide character .I wc onto the output .I stream at the position where the file pointer is pointing. .CI putwchar( wc ) is defined as .CI putwc( wc , .CR stdout) . .CR putwc() and .CR putwchar() are defined both as macros and as functions. .TP .C fputwc() Behaves like .CR putwc() , but is a function rather than a macro, and can therefore be used as an argument. .PP Output streams, with the exception of the standard error stream .CR stderr , are by default buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream, .CR stderr , is by default unbuffered, but use of .CR freopen() (see .IR fopen (3S)) causes it to become buffered or line-buffered. .CR setbuf() or .CR setvbuf() (see .IR setbuf (3S)) can be used to change the stream's buffering strategy. .PP Definitions for these functions, the type .I wint_t and the value WEOF are provided in the .RC < wchar.h > header. .PP .CR putwc_unlocked() , .CR putwchar_unlocked() , and .CR fputwc_unlocked() are identical to .CR putwc() , .CR putwchar() , and .CR fputwc_unlocked() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE On success, .CR putwc() , .CR putwc_unlocked() , .CR fputwc() , .CR fputwc_unlocked() , .CR putwchar() , and .CR putwchar_unlocked() each return the wide character corresponding to the value they have written. On failure, they return the constant .CR WEOF , set the error indicator for the stream, and set .CR errno to indicate the error. .SH ERRORS .CR putwc() , .CR putwc_unlocked() , .CR putwchar() , .CR putwchar_unlocked() , .CR fputwc() , and .CR fputwc_unlocked() fail if either the .I stream is unbuffered, or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] A physical I/O error has occurred, or the process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP [EILSEQ] The wide character .I wc does not correspond to a valid character. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH WARNINGS Line buffering may cause confusion or malfunctioning of programs that use wide character I/O routines but use .CR read() themselves to read from standard input. When a large amount of computation is done after printing part of a line on an output terminal, it is necessary to .CR fflush() (see .IR fclose (3S)) the standard output before beginning the computation. .SH AUTHOR .CR putwc() was developed by OSF and HP. .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), getwc(3C), fread(3S), printf(3S), fputws(3C), setbuf(3S). .SH STANDARDS CONFORMANCE .CR putwc() ": XPG4" .PP .CR fputwc() ": XPG4" .PP .CR putwchar() ": XPG4" .\" .\" index@\f4putwc()\f1, \f4fputwc()\f1 \- put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f4fputwc()\f1, \f4putwc()\f1 \- put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f4putwchar()\f1 \- put wide character on stream \f2standard output\f1@@@\f3putwc(3C)\f1 .\" index@\f1wide character, put on a stream@@@\f3putwc(3C)\f1 .\" index@\f1put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f1stream, put wide character on a@@@\f3putwc(3C)\f1 .\" .\" toc@\f3putwc(3C)\f1:\0\0\f4putwc()\f1, \f4putwchar()\f1, \f4fputwc()\f1@@@put wide character on a stream .\" toc@\f4putwchar()\f1:\0\0put wide character on a stream@@@see \f3putwc(3C)\f1 .\" toc@\f4fputwc()\f1:\0\0put wide character on a stream@@@see \f3putwc(3C)\f1 .\" .\" links@putwc.3c putwc_unloc.3c .\" links@putwc.3c putwchar.3c .\" links@putwc.3c putwchar_un.3c .\" links@putwc.3c fputwc_unlo.3c .\" links@putwc.3c fputwc.3c .\" $Header: putwc.3c,v 76.1 95/07/05 17:45:14 ssa Exp $ .TA p .TH putwc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putwc(\|), putwc_unlocked(\|), putwchar(\|), putwchar_unlocked(\|), fputwc(\|), fputwc_unlocked(\|) \- put a wide character on a stream file .SH SYNOPSIS .C "#include " .PP .C "wint_t putwc(wint_t wc, FILE *stream);" .PP .C "wint_t putwc_unlocked(wint_t wc, FILE *stream);" .PP .C "wint_t putwchar(wint_t wc);" .PP .C "wint_t putwchar_unlocked(wint_t wc);" .PP .C "wint_t fputwc(wint_t wc, FILE *stream);" .PP .C "wint_t fputwc_unlocked(wint_t wc, FILE *stream);" .SS Remarks: These functions are compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. They parallel the 8-bit character I/O functions defined in .IR putc(3S) . .SH DESCRIPTION .TP 15 .CR putwc() Writes the character corresponding to the wide character .I wc onto the output .I stream at the position where the file pointer is pointing. .CI putwchar( wc ) is defined as .CI putwc( wc , .CR stdout) . .CR putwc() and .CR putwchar() are defined both as macros and as functions. .TP .C fputwc() Behaves like .CR putwc() , but is a function rather than a macro, and can therefore be used as an argument. .PP Output streams, with the exception of the standard error stream .CR stderr , are by default buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream, .CR stderr , is by default unbuffered, but use of .CR freopen() (see .IR fopen (3S)) causes it to become buffered or line-buffered. .CR setbuf() or .CR setvbuf() (see .IR setbuf (3S)) can be used to change the stream's buffering strategy. .PP Definitions for these functions, the type .I wint_t and the value WEOF are provided in the .RC < wchar.h > header. .PP .CR putwc_unlocked() , .CR putwchar_unlocked() , and .CR fputwc_unlocked() are identical to .CR putwc() , .CR putwchar() , and .CR fputwc_unlocked() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE On success, .CR putwc() , .CR putwc_unlocked() , .CR fputwc() , .CR fputwc_unlocked() , .CR putwchar() , and .CR putwchar_unlocked() each return the wide character corresponding to the value they have written. On failure, they return the constant .CR WEOF , set the error indicator for the stream, and set .CR errno to indicate the error. .SH ERRORS .CR putwc() , .CR putwc_unlocked() , .CR putwchar() , .CR putwchar_unlocked() , .CR fputwc() , and .CR fputwc_unlocked() fail if either the .I stream is unbuffered, or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] A physical I/O error has occurred, or the process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP [EILSEQ] The wide character .I wc does not correspond to a valid character. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH WARNINGS Line buffering may cause confusion or malfunctioning of programs that use wide character I/O routines but use .CR read() themselves to read from standard input. When a large amount of computation is done after printing part of a line on an output terminal, it is necessary to .CR fflush() (see .IR fclose (3S)) the standard output before beginning the computation. .SH AUTHOR .CR putwc() was developed by OSF and HP. .SH SEE ALSO fclose(3S), ferror(3S), flockfile(3S), fopen(3S), getwc(3C), fread(3S), printf(3S), fputws(3C), setbuf(3S). .SH STANDARDS CONFORMANCE .CR putwc() ": XPG4" .PP .CR fputwc() ": XPG4" .PP .CR putwchar() ": XPG4" .\" .\" index@\f4putwc()\f1, \f4fputwc()\f1 \- put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f4fputwc()\f1, \f4putwc()\f1 \- put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f4putwchar()\f1 \- put wide character on stream \f2standard output\f1@@@\f3putwc(3C)\f1 .\" index@\f1wide character, put on a stream@@@\f3putwc(3C)\f1 .\" index@\f1put wide character on a stream@@@\f3putwc(3C)\f1 .\" index@\f1stream, put wide character on a@@@\f3putwc(3C)\f1 .\" .\" toc@\f3putwc(3C)\f1:\0\0\f4putwc()\f1, \f4putwchar()\f1, \f4fputwc()\f1@@@put wide character on a stream .\" toc@\f4putwchar()\f1:\0\0put wide character on a stream@@@see \f3putwc(3C)\f1 .\" toc@\f4fputwc()\f1:\0\0put wide character on a stream@@@see \f3putwc(3C)\f1 .\" .\" links@putwc.3c putwc_unloc.3c .\" links@putwc.3c putwchar.3c .\" links@putwc.3c putwchar_un.3c .\" links@putwc.3c fputwc_unlo.3c .\" links@putwc.3c fputwc.3c .\" $Header: getwin.3x,v 76.2 95/08/01 11:00:05 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getwin 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getwin, putwin \(em dump window to, and reload window from, a file .SH SYNOPSIS .C "#include " .P .C "WINDOW *getwin(FILE *\f2filep\fP);" .P .C "int putwin(WINDOW *\f2win\fP, FILE *\f2filep\fP);" .SH DESCRIPTION The .Fn getwin function reads window-related data stored in the file by .CR putwin() . The function then creates and initialises a new window using that data. .P The .Fn putwin function writes all data associated with \f2win\f1 into the .I stdio stream to which \f2filep\f1 points, using an unspecified format. This information can be retrieved later using .CR getwin() . .SH "RETURN VALUE" Upon successful completion, .Fn getwin returns a pointer to the window it created. Otherwise, it returns a null pointer. .P Upon successful completion, .Fn putwin returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" scr_dump(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getwin(3X)\f1:\0\0\f4getwin()\f1, \f4putwin()\f1@@@dump window to, and reload window from a file .\" toc@\f4putwin()\f1: dump window to and reload window from a file@@@see \f3getwin(3X)\f1 .\" .\" index@\f4getwin()\f1 \- dump window to and reload window from a file@@@\f3getwin(3X)\f1 .\" index@\f4putwin()\f1 \- dump window to and reload window from a file@@@\f3getwin(3X)\f1 .\" index@\f1dump window to and reload window from a file@@@\f3getwin(3X)\f1 .\" index@\f1reload window from a file@@@\f3getwin(3X)\f1 .\" index@\f1window, dump to and reload from a file@@@\f3getwin(3X)\f1 .\" index@\f1file, dump window to and reload window from@@@\f3getwin(3X)\f1 .\" .\" links@getwin.3x putwin.3x .\" .\" fileset_database@getwin.3x CURS-ENG-A-MAN .\" $Header: putws.3c,v 72.3 94/11/15 09:55:52 ssa Exp $ .TA p .TH putws 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putws(\|), putws_unlocked(\|), fputws(\|), fputws_unlocked(\|) \- put a wide character string on a stream file .SH SYNOPSIS .C "#include " .PP .C "int putws(const wchar_t *ws);" .PP .C "int putws_unlocked(const wchar_t *ws);" .PP .C "int fputws(const wchar_t *ws, FILE *stream);" .PP .C "int fputws_unlocked(const wchar_t *ws, FILE *stream);" .SS Remarks: .CR fputws is compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. These functions parallel the 8 bit character I/O functions defined in .IR puts(3S) . .SH DESCRIPTION .CR putws() writes a character string corresponding to the null-terminated wide-character string pointed to by .I ws followed by a new-line character, to the standard output stream .CR stdout . .PP .CR fputws() writes a character string corresponding to the null-terminated wide-character string pointed to by .I ws to the named output .IR stream , but does .I not append a new-line character or a terminating null character. .PP Neither function writes a terminating null character. .PP The definition for these functions, the type .CR wchar_t and the value .CR WEOF are provided in the .RC < wchar.h > header. .PP .CR putws_unlocked() and .CR fputws_unlocked() are identical to .CR putws() and .CR fputws() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. .CR putws_unlocked() and .CR fputws_unlocked() can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE Upon successful completion, .CR putws() , .CR putws_unlocked() , .CR fputws() , and .CR fputws_unlocked() return a non-negative number. Otherwise they return .CR WEOF , set the error indicator for the stream, and set .CR errno to indicate the error. .SH ERRORS .CR putws() , .CR putws_unlocked() , .CR fputws() , and .CR fputws_unlocked() fail if either the .I stream is unbuffered, or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP [EILSEQ] A wide character in .I ws does not correspond to a valid character. .RE .PP Additional .CR errno values may be set by the underlying .CR write() function (see .IR write(2)). .SH AUTHOR .CR putws() and .CR fputws() were developed by OSF and HP. .SH SEE ALSO ferror(3S), flockfile(3S), fopen(3S), fread(3S), printf(3S), putwc(3C). .SH STANDARDS CONFORMANCE .CR fputws() ": XPG4" .\" .\" index@\f4putws()\f1, \f4fputws()\f1 \- write null-terminated wide string to a named stream file@@@\f3putws(3C)\f1 .\" index@\f1write a null-terminated wide string on a stream@@@\f3putws(3C)\f1 .\" .\" toc@\f3putws(3C)\f1:\0\0\f4putws()\f1, \f4fputws()\f1@@@put a wide string on a stream .\" toc@\f4fputws()\f1:\0\0put a wide string on a stream@@@see \f3putws(3C)\f1 .\" .\" links@putws.3c fputws.3c .\" links@putws.3c putws_unloc.3c .\" links@putws.3c fputws_unlo.3c .\" .\" fileset_database@putws.3c PROGRAMING-MAN .\" $Header: putws.3c,v 72.3 94/11/15 09:55:52 ssa Exp $ .TA p .TH putws 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putws(\|), putws_unlocked(\|), fputws(\|), fputws_unlocked(\|) \- put a wide character string on a stream file .SH SYNOPSIS .C "#include " .PP .C "int putws(const wchar_t *ws);" .PP .C "int putws_unlocked(const wchar_t *ws);" .PP .C "int fputws(const wchar_t *ws, FILE *stream);" .PP .C "int fputws_unlocked(const wchar_t *ws, FILE *stream);" .SS Remarks: .CR fputws is compliant with the XPG4 Worldwide Portability Interface wide-character I/O functions. These functions parallel the 8 bit character I/O functions defined in .IR puts(3S) . .SH DESCRIPTION .CR putws() writes a character string corresponding to the null-terminated wide-character string pointed to by .I ws followed by a new-line character, to the standard output stream .CR stdout . .PP .CR fputws() writes a character string corresponding to the null-terminated wide-character string pointed to by .I ws to the named output .IR stream , but does .I not append a new-line character or a terminating null character. .PP Neither function writes a terminating null character. .PP The definition for these functions, the type .CR wchar_t and the value .CR WEOF are provided in the .RC < wchar.h > header. .PP .CR putws_unlocked() and .CR fputws_unlocked() are identical to .CR putws() and .CR fputws() ; respectively, except they do not perform any internal locking of the .I stream for multi-thread applications. .CR putws_unlocked() and .CR fputws_unlocked() can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE Upon successful completion, .CR putws() , .CR putws_unlocked() , .CR fputws() , and .CR fputws_unlocked() return a non-negative number. Otherwise they return .CR WEOF , set the error indicator for the stream, and set .CR errno to indicate the error. .SH ERRORS .CR putws() , .CR putws_unlocked() , .CR fputws() , and .CR fputws_unlocked() fail if either the .I stream is unbuffered, or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked, and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP [EILSEQ] A wide character in .I ws does not correspond to a valid character. .RE .PP Additional .CR errno values may be set by the underlying .CR write() function (see .IR write(2)). .SH AUTHOR .CR putws() and .CR fputws() were developed by OSF and HP. .SH SEE ALSO ferror(3S), flockfile(3S), fopen(3S), fread(3S), printf(3S), putwc(3C). .SH STANDARDS CONFORMANCE .CR fputws() ": XPG4" .\" .\" index@\f4putws()\f1, \f4fputws()\f1 \- write null-terminated wide string to a named stream file@@@\f3putws(3C)\f1 .\" index@\f1write a null-terminated wide string on a stream@@@\f3putws(3C)\f1 .\" .\" toc@\f3putws(3C)\f1:\0\0\f4putws()\f1, \f4fputws()\f1@@@put a wide string on a stream .\" toc@\f4fputws()\f1:\0\0put a wide string on a stream@@@see \f3putws(3C)\f1 .\" .\" links@putws.3c fputws.3c .\" links@putws.3c putws_unloc.3c .\" links@putws.3c fputws_unlo.3c .\" .\" fileset_database@putws.3c PROGRAMING-MAN .\" $Header: noqiflush.3x,v 76.2 95/08/01 14:31:36 ssa Exp $ .TA n .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH noqiflush 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME noqiflush, qiflush \(em enable/disable queue flushing .SH SYNOPSIS .C "#include " .P .C "void noqiflush(void);" .P .C "void qiflush(void);" .SH DESCRIPTION The .Fn qiflush function causes all output in the display driver queue to be flushed whenever an interrupt key (interrupt, suspend, or quit) is pressed. The .Fn noqiflush causes no such flushing to occur. The default for the option is inherited from the display driver settings. .SH "RETURN VALUE" These functions do not return a value. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Calling .Fn qiflush provides faster response to interrupts, but causes Curses to have the wrong idea of what is on the screen. The same effect is achieved outside Curses using the NOFLSH local mode flag specified in the \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification (\f3General Terminal Interface\fP). .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, intrflush(), , \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Section 9.2, \f3Parameters That Can Be Set\f1 (NOFLSH flag). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3noqiflush(3X)\f1:\0\0\f4noqiflush()\f1, \f4qiflush()\f1@@@enable/disable queue flushing .\" toc@\f4qiflush()\f1: enable/disable queue flushing@@@see \f3noqiflush(3X)\f1 .\" .\" index@\f4noqiflush()\f1 \- enable/disable queue flushing@@@\f3noqiflush(3X)\f1 .\" index@\f4qiflush()\f1 \- enable/disable queue flushing@@@\f3noqiflush(3X)\f1 .\" index@\f1enable/disable queue flushing@@@\f3noqiflush(3X)\f1 .\" index@\f1disable/enable queue flushing@@@\f3noqiflush(3X)\f1 .\" index@\f1queue flushing, enable/disable@@@\f3noqiflush(3X)\f1 .\" index@\f1flushing queue, enable/disable@@@\f3noqiflush(3X)\f1 .\" .\" links@noqiflush.3x qiflush.3x .\" .\" fileset_database@noqiflush.3x CURS-ENG-A-MAN .\" $Header: qsort.3c,v 72.4 94/11/15 09:55:54 ssa Exp $ .TA q .TH qsort 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME qsort(\|) \- quicker sort .SH SYNOPSIS .C "#include " .PP .C "void qsort(" .nf .PD 0 .IP .C "void *base," .C "size_t nel," .C "size_t size," .C "int (*compar)(const void *, const void *)" .PP .C ");" .PD .fi .SH DESCRIPTION .C qsort() is an implementation of the quicker-sort algorithm. It sorts a table of data in place. .RS .TP 12 .I base Pointer to the element at the base of the table. .TP .I nel Number of elements in the table. .TP .I size Size of each element in the table. .TP .I compar Name of the comparison function, which is called with two arguments that point to the elements being compared. The function passed as .I compar must return an integer less than, equal to, or greater than zero, according to whether its first argument is to be considered less than, equal to, or greater than the second. .C strcmp() uses this same return convention (see .IR strcmp (3C)). .RE .SH NOTES The pointer to the base of the table should be of type pointer-to-element, and cast to type pointer-to-void. .PP The comparison function need not compare every byte; thus, arbitrary data can be contained in the elements in addition to the values being compared. .PP The order in the output of two items which compare as equal is unpredictable. .SH SEE ALSO sort(1), bsearch(3C), lsearch(3C), string(3C). .SH WARNINGS If .I size is zero, a divide-by-zero error might be generated. .SH STANDARDS CONFORMANCE .CR qsort() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4qsort()\fP \- quicker sort@@@\f3qsort(3C)\f1 .\" index@quicker sort@@@\f3qsort(3C)\f1 .\" index@sort, quicker@@@\f3qsort(3C)\f1 .\" .\" toc@\f3qsort(3C)\f1:\0\0\f4qsort()\fP@@@quicker sort .\" .\" fileset_database@qsort.3c PROGRAMING-MAN .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "query_geometry" "Xt \- Intrinsics Methods" .SH "Name" .Na query_geometry \- RectObj method called to request a widget's preferred size and position. .Nz .XX "query_geometry method" .XX "methods, query_geometry" .SH "Synopsis" .Sy typedef XtGeometryResult (*XtGeometryHandler)(Widget, XtWidgetGeometry *, .br XtWidgetGeometry *); .As Widget \f(CIw\fP; XtWidgetGeometry *\f(CIrequest\fP; XtWidgetGeometry *\f(CIpreferred_return\fP .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget or object that is being queried. .IP \f(CIrequest\fP 1i Specifies the geometry changes that the parent plans to make. .SS "Outputs" .IP \f(CIpreferred_return\fP 1i Returns the widget or object's preferred geometry. .SS "Returns" The widget's reply: \f(CWXtGeometryYes\fP, \f(CWXtGeometryNo\fP, or \f(CWXtGeometryAlmost\fP. .\" .SH "Description" The \f(CWquery_geometry()\fP method is registered on the \f(CWquery_geometry\fP field of the RectObj or Core class part structure. It is invoked by \f(CWXtQueryGeometry()\fP when the widget's parent wants to determine the widget's preferred geometry. The parent may call this function when it want to know the widget's ideal size in the absence of any constraints, or it may call it before changing some of the widget's geometry fields in order to find out the widget's preference for the other fields. .LP The \f(CIrequest\fP argument indicates the geometry changes the parent plans to make. \f(CIrequest\f(CW->request_mode\fR contains flags that indicate which of the remaining fields are significant. (See the "Structures" section below for a description of the structure and a list of the flags.) The \f(CWquery_geometry()\fP method should examine this proposed change, set its preferred geometry in \f(CIpreferred_return\fP, setting \f(CIpreferred_return\f(CW-> request_mode\fR to indicate which geometry field it cares about, and return one of the following values: .IP \f(CWXtGeometryYes\fP 5n The widget agrees to the change; the parent should make exactly the change it proposed. When \f(CWquery_geometry()\fP returns this value, the contents of \f(CIpreferred_return\fP should be identical to the contents of \f(CIrequest\fP, for each flag bit set in \f(CIpreferred_return\fP. This means that the parent's proposed geometry is exactly the widget's preferred geometry (or that the widget has a flexible notion of "preferred" and feels that the proposal is good enough). .\" .IP \f(CWXtGeometryNo\fP 5n This return value means that the widget's current geometry \fIis\fP its preferred geometry, and it would rather not be changed. When this value is returned, \f(CWquery_geometry()\fP doesn't have to fill in \f(CIpreferred_return\fP, because \f(CWXtQueryGeometry()\fP will fill in any unspecified fields with their current values, which in this case are the preferred values. It is of course up to the parent widget whether or not to honor this request not to change. .\" .IP \f(CWXtGeometryAlmost\fP 5n This return value means that the widget would like a geometry change, but that its preferred geometry differs from the proposed geometry. \f(CWquery_geometry()\fP should return this value if at least one bit is set in the return flags that was not set in the proposed flags, or if any of the returned values (that have their flag bit set) differ from the corresponding proposed values. .LP Note that \f(CWquery_geometry()\fP need only return its preferences for the fields it cares about (generally width and height). \f(CWXtQueryGeometry()\fP will fill in any unspecified fields with the widget's current value. Also, \f(CWquery_geometry()\fP can ignore flag bits set in \f(CIrequest\fP for fields that it does not care about. If a widget doesn't care about its location, for example, and its parent proposes to change its location without changing its size, it should still place its preferred size in \f(CIpreferred_return\fP, and follow the rules above to determine which value to return. .LP It is up to the parent widget to decide what to do with the return value from this function (which it gets from \f(CWXtQueryGeometry()\fP). Some parents will respect the widget's requests, but many will ignore them. Generally, if a parent sets a flag in \f(CWrequest\fP, it will change that field, regardless of the widget's return value. The power of the \f(CWquery_geometry()\fP method lies in the fact that the widget can propose additional geometry changes with the \f(CWXtGeometryAlmost\fP return value. A parent that constrains the width of a widget may call \f(CWXtQueryGeometry()\fP to determine how high the widget would like to be, given its new width. A label widget that supported word wrapping, for example, might request a larger height if its width were made smaller. A cooperating parent would make its change to the width, but also change the height as the child requested. .LP The \f(CWquery_geometry()\fP method is not chained. Widget classes that do not define a \f(CWquery_geometry()\fP method can inherit the method from their superclass by specifying \f(CWXtInheritQueryGeometry\fP on the \f(CWquery_geometry\fP field of the RectObj or Core class part structure. Widgets that have no preference about their geometry can set this field to \f(CWNULL\fP. .LP See the "Background" section below for more details on the \f(CWquery_geometry()\fP method. See \f(CWXtQueryGeometry\fP(1) for the parent widget's perspective on this geometry negotiation process. .\" .SH "Usage" Like the \f(CWgeometry_manager()\fP method, the \f(CWquery_geometry()\fP method can be confusing, and can become almost arbitrarily complex. The \f(CWquery_geometry()\fP mechanism allows much more flexibility than most widgets need and more than most parents support. The fact that there are three possible return values which do not have very clearly defined meanings (at least not well defined in practice) to the child or to the parent makes the situation all the more confusing. There are some factors that can simplify the \f(CWquery_geometry()\fP method, however. .LP Most widgets do not care about anything other than their width and height, and their \f(CWquery_geometry()\fP methods never need to return preferred information about position, border width, or stacking order. Most parents won't bother to query these fields anyway. .LP Most widgets treat their width and height independently, and do not try to increase their height if their width shrinks, for example. These widgets can use a simple method like the example shown below. .LP Some widgets do not even have a preference about their size. A label widget's preferred size is whatever it takes to display the string or pixmap, and a composite widget's preferred size may be whatever it takes to lay out its children. A scrollbar, however, can make do with whatever size it is given, and can simply inherit the \f(CWquery_geometry()\fP method of its parent. .\" .SH "Example" The following procedure is the \f(CWquery_geometry()\fP method from the Xaw Label widget. Most of the Xaw widgets that have a \f(CWquery_geometry()\fP method use almost identical procedures. The first thing it does is set its preferred width and height, which are the width and height of the label plus internal margins. Then it checks to see if the parent's requested geometry had both width and height flags set (note that it masks out any other bits for fields that it does not care about), and if so, and if the parent's request matches the preferred size, it returns \f(CWXtGeometryYes\fP. Otherwise, if the preferred size matches the widget's current size, it returns \f(CWXtGeometryNo\fP, and otherwise it returns \f(CWXtGeometryAlmost\fP. .LP Note that this procedure does not attempt to do anything special if only its width or only its height are constrained. The \f(CWquery_geometry()\fP method of the Xaw Box widget does handle this case, and may be worth study if you will be writing a similar widget. .Ps .ps 8 static XtGeometryResult QueryGeometry(w, intended, preferred) Widget w; XtWidgetGeometry *intended, *preferred; { register LabelWidget lw = (LabelWidget)w; preferred->request_mode = CWWidth CWHeight; preferred->width = (lw->label.label_width + 2 * lw->label.internal_width + LEFT_OFFSET(lw)); preferred->height = lw->label.label_height + 2*lw->label.internal_height; if ( ((intended->request_mode & (CWWidth CWHeight)) == (CWWidth CWHeight)) && intended->width == preferred->width && intended->height == preferred->height) return XtGeometryYes; else if (preferred->width == w->core.width && preferred->height == w->core.height) return XtGeometryNo; else return XtGeometryAlmost; } .ps .Pe .\" .SH "Background" The \f(CWquery_geometry()\fR method is expected to examine the bits set in \f(CIrequest\f(CW->request_mode\fR, evaluate the proposed geometry for the widget, and store the result in \f(CIpreferred_return\fR (setting the bits in \f(CWpreferred_return-> request_mode\fR corresponding to those geometry fields that it cares about). If the proposed geometry change is acceptable without modification, the \f(CWquery_geometry()\fR method should return \f(CWXtGeometryYes\fR. If at least one field in \f(CIpreferred_return\fR is different from the corresponding field in \f(CIrequest\fP or if a bit was set in \f(CIpreferred_return\fR that was not set in \f(CIrequest\fP, the \f(CWquery_geometry()\fR method should return \f(CWXtGeometryAlmost\fR. If the preferred geometry is identical to the current geometry, the \f(CWquery_geometry()\fR method should return \f(CWXtGeometryNo\fR. .LP Note that the \f(CWquery_geometry()\fP method may assume that no \f(CWXtMakeResizeRequest()\fP or \f(CWXtMakeGeometryRequest()\fP is in progress for the specified widget; that is, it is not required to construct a reply consistent with the requested geometry if such a request were actually outstanding. .LP After calling the \f(CWquery_geometry()\fR method or if the \f(CWquery_geometry()\fR field is \f(CWNULL\fR, \f(CWXtQueryGeometry()\fR examines all the unset bits in \f(CIpreferred_return\f(CW-> request_mode\fR and sets the corresponding fields in \f(CIpreferred_return\fR to the current values from the widget instance. If \f(CWCWStackMode\fR is not set, the \f(CWstack_mode\fR field is set to \f(CWXtSMDontChange\fR. \f(CWXtQueryGeometry()\fR returns either the value returned by the \f(CWquery_geometry()\fR method or \f(CWXtGeometryYes\fR if the \f(CWquery_geometry()\fR field is \f(CWNULL\fR. .LP Therefore, the caller can interpret a return of \f(CWXtGeometryYes\fR as not needing to evaluate the contents of the reply and, more importantly, not needing to modify its layout plans. A return of \f(CWXtGeometryAlmost\fR means either that both the parent and the child expressed interest in at least one common field and the child's preference does not match the parent's intentions or that the child expressed interest in a field that the parent might need to consider. A return value of \f(CWXtGeometryNo\fR means that both the parent and the child expressed interest in a field and that the child suggests that the field's current value is its preferred value. In addition, whether or not the caller ignores the return value or the reply mask, it is guaranteed that the \f(CIpreferred_return\fP structure contains complete geometry information for the child. .LP Parents are expected to call \f(CWXtQueryGeometry()\fR in their layout routine and wherever other information is significant after \f(CWchange_managed()\fR has been called. The \f(CWchange_managed()\fR method may assume that the child's current geometry is its preferred geometry. Thus, the child is still responsible for storing values into its own geometry during its \f(CWinitialize()\fR method. .\" .SH "Structures" The possible return values of a \f(CWquery_geometry()\fP method are defined as follows: .XX "XtGeometryResult" .Ps .ta 4.5n 2i typedef enum { XtGeometryYes, /* Request accepted */ XtGeometryNo, /* Request rejected */ XtGeometryAlmost,/* Compromise proposed */ XtGeometryDone /* never returned by query_geometry */ } XtGeometryResult; .Pe The \f(CWXtWidgetGeometry\fR structure is similar to but not identical to the corresponding Xlib structure: .XX "XtGeometryMask" .Ps .ta 4.5n 2i typedef unsigned long XtGeometryMask; .sp .5 typedef struct { XtGeometryMask request_mode; Position x, y; Dimension width, height; Dimension border_width; Widget sibling; int stack_mode; } XtWidgetGeometry; .Pe \f(CWXtQueryGeometry()\fP, like the Xlib \f(CWXConfigureWindow()\fR function, uses \f(CWrequest_mode\fR to determine which fields in the \f(CWXtWidgetGeometry\fR structure the parent and the child have set. The \f(CWrequest_mode\fR definitions are from <\fIX11/X.h\fP>: .Ps .ta .75i 2i #define CWX (1<<0) #define CWY (1<<1) #define CWWidth (1<<2) #define CWHeight (1<<3) .Nd 4 #define CWBorderWidth (1<<4) #define CWSibling (1<<5) #define CWStackMode (1<<6) .Pe .LP The \f(CWstack_mode\fR definitions are from <\fIX11/X.h\fP>: .Ps .ta .75i 2i #define Above 0 #define Below 1 #define TopIf 2 #define BottomIf 3 #define Opposite 4 .Pe The Intrinsics also support the following value: .Ps .ta .75i 2i #define XtSMDontChange 5 .Pe For precise definitions of \f(CWAbove\fR, \f(CWBelow\fR, \f(CWTopIf\fR, \f(CWBottomIf\fR, and \f(CWOpposite\fR, see the reference page for \f(CWXConfigureWindow()\fP in \*(V2. \f(CWXtSMDontChange\fR indicates that the widget wants its current stacking order preserved. .\" .SH "See Also" .na .br \s-1\fIXtQueryGeometry\fR\s+1\*(s1, .br \s-1\fICore\fR\s+1\*(s3. .ad .\"last line comment .\" $Header: rand.3c,v 76.1 95/07/05 17:45:31 ssa Exp $ .TA r .TH rand 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rand(\|), rand_r(\|), srand(\|) \- simple random-number generator .SH SYNOPSIS .C "#include " .PP .C "int rand(void);" .PP .C "int rand_r(unsigned int *seed, int *randval);" .PP .C "void srand(unsigned int seed);" .SH DESCRIPTION .CR rand() uses a multiplicative, congruential, random-number generator with period .if t 2\u\s-232\s0\d .if n 2^32 that returns successive pseudo-random numbers in the range from 0 to .if t 2\u\s-215\s0\d\-1. .if n 2^15-1. .PP .CR srand() can be called at any time to reset the random-number generator to a random starting point. The generator is initially seeded with a value of 1. .SS Reentrant Interfaces .CR rand_r() returns a random number at the address pointed to by the .I randval parameter. The .I seed parameter can be set at any time to start the random-number generator at an arbitrary point. Note that .B rand() is a thread-safe function. The .CR rand_r() interface has been provided to allow multiple threads to generate the same sequence of random numbers concurrently. .SH RETURN VALUE If .IR seed " or " randval is .SM NULL, .CR rand_r() returns -1 and sets .CR errno to .SM EINVAL. Otherwise, .CR rand_r() returns 0. .SH EXAMPLE The following: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int x, y; .PP srand(10); x = rand(); y = rand(); .ft .ps .fi .RE .PP would produce the same results as: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int x, y, s = 10; .PP rand_r(&s, &x); rand_r(&s, &y); .ft .ps .fi .RE .SH NOTE The spectral properties of .CR rand() leave a great deal to be desired. .CR drand48() provides a much better, though more elaborate, random-number generator (see .IR drand48 (3C)). .SH WARNINGS Users of .CR rand_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH SEE ALSO drand48(3C), random(3M). .SH STANDARDS CONFORMANCE .CR rand() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR srand() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4rand()\fP \- generate successive random numbers@@@\f3rand(3C)\f1 .\" index@\f4srand()\fP \- reset random-number generator to random starting point@@@\f3rand(3C)\f1 .\" index@random-number generator, simple@@@\f3rand(3C)\f1 .\" index@generator, simple random-number@@@\f3rand(3C)\f1 .\" .\" toc@\f3rand(3C)\f1:\0\0\f4rand()\fP, \f4srand()\fP@@@simple random-number generator .\" toc@\f4srand()\fP:\0\0simple random-number generator@@@see \f3rand(3C)\f1 .\" .\" links@rand.3c rand_r.3c .\" links@rand.3c srand.3c .\" $Header: rand.3c,v 76.1 95/07/05 17:45:31 ssa Exp $ .TA r .TH rand 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rand(\|), rand_r(\|), srand(\|) \- simple random-number generator .SH SYNOPSIS .C "#include " .PP .C "int rand(void);" .PP .C "int rand_r(unsigned int *seed, int *randval);" .PP .C "void srand(unsigned int seed);" .SH DESCRIPTION .CR rand() uses a multiplicative, congruential, random-number generator with period .if t 2\u\s-232\s0\d .if n 2^32 that returns successive pseudo-random numbers in the range from 0 to .if t 2\u\s-215\s0\d\-1. .if n 2^15-1. .PP .CR srand() can be called at any time to reset the random-number generator to a random starting point. The generator is initially seeded with a value of 1. .SS Reentrant Interfaces .CR rand_r() returns a random number at the address pointed to by the .I randval parameter. The .I seed parameter can be set at any time to start the random-number generator at an arbitrary point. Note that .B rand() is a thread-safe function. The .CR rand_r() interface has been provided to allow multiple threads to generate the same sequence of random numbers concurrently. .SH RETURN VALUE If .IR seed " or " randval is .SM NULL, .CR rand_r() returns -1 and sets .CR errno to .SM EINVAL. Otherwise, .CR rand_r() returns 0. .SH EXAMPLE The following: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int x, y; .PP srand(10); x = rand(); y = rand(); .ft .ps .fi .RE .PP would produce the same results as: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int x, y, s = 10; .PP rand_r(&s, &x); rand_r(&s, &y); .ft .ps .fi .RE .SH NOTE The spectral properties of .CR rand() leave a great deal to be desired. .CR drand48() provides a much better, though more elaborate, random-number generator (see .IR drand48 (3C)). .SH WARNINGS Users of .CR rand_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH SEE ALSO drand48(3C), random(3M). .SH STANDARDS CONFORMANCE .CR rand() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR srand() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4rand()\fP \- generate successive random numbers@@@\f3rand(3C)\f1 .\" index@\f4srand()\fP \- reset random-number generator to random starting point@@@\f3rand(3C)\f1 .\" index@random-number generator, simple@@@\f3rand(3C)\f1 .\" index@generator, simple random-number@@@\f3rand(3C)\f1 .\" .\" toc@\f3rand(3C)\f1:\0\0\f4rand()\fP, \f4srand()\fP@@@simple random-number generator .\" toc@\f4srand()\fP:\0\0simple random-number generator@@@see \f3rand(3C)\f1 .\" .\" links@rand.3c rand_r.3c .\" links@rand.3c srand.3c .\" $Header: random.3m,v 76.2 95/07/10 17:17:13 ssa Exp $ .TA r .TH random 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME random(\|), srandom(\|), initstate(\|), setstate(\|) \- generate a pseudorandom number .SH SYNOPSIS .C "#include " .PP .C "long random(void);" .PP .C "void srandom(unsigned seed);" .PP .C "char *initstate(unsigned seed, char *state, size_t size);" .PP .C "char *setstate(char *state);" .fi .ft 1 .SH DESCRIPTION The .CR random() and .CR srandom() functions are random-number generators that have virtually the same calling sequence and initialization properties as the .CR rand() and .CR srand() functions, but produce sequences that are more random. The low 12 bits generated by the .CR rand() function go through a cyclic pattern, while all the bits generated by the .CR random() function are usable. For example, .C "random() & 01" produces a random binary value. .PP The .CR random() function uses a nonlinear additive feedback random-number generator employing a default state array size of 31 long integers to return successive pseudorandom numbers in the range from 0 to .ift 2\u\s-231\s0\d-1. .ifn (2^31 - 1). The period of this random-number generator is approximately 16 x .ift (2\s-2\u31\d\s0-\f11). .ifn (2^31 - 1). The size of the state array determines the period of the random-number generator. Increasing the state array size increases the period. .PP With 256 bytes of state information, the period of the random-number generator is greater than .ift 2\s-2\u69\s0\d. .ifn 2^69. .PP Like the .CR rand() function, the .CR random() function produces by default a sequence of numbers that can be duplicated by calling the .CR srandom() function with a value of 1 as the seed. .P The .CR srandom() function initializes the current state array using the value of .IR seed . .PP The .CR initstate() and .CR setstate() functions handle restarting and changing random-number generators. The .CR initstate() function allows a state array, pointed to by the .I state argument, to be initialized for future use. The .I size argument, which specifies the size in bytes of the state array, is used by the .CR initstate() function to decide how sophisticated a random-number generator to use; the larger the state array, the more random the numbers. Values for the amount of state information are 8, 32, 64, 128, and 256 bytes. Amounts less than 8 bytes generate an error, while other amounts are rounded down to the nearest known value. The .I seed argument specifies a starting point for the random-number sequence and provides for restarting at the same point. The .CR initstate() function returns a pointer to the previous state information array. .PP Once a state has been initialized, the .CR setstate() function allows switching between state arrays. The array defined by the .I state argument is used for further random-number generation until the .CR initstate() function is called or the .CR setstate() function is called again. The .CR setstate() function returns a pointer to the previous state array. .PP After initialization, a state array can be restarted at a different point in one of two ways: .PP .RS The .CR initstate() function can be used, with the desired seed, state array, and size of the array. .PP The .CR setstate() function, with the desired state, can be used, followed by the .CR srandom() function with the desired seed. The advantage of using both of these functions is that the size of the state array does not have to be saved once it is initialized. .PP .RE .SH RETURN VALUE The .CR random() function returns the generated pseudorandom number. .PP The .CR srandom() function returns no value. .PP Upon successful completion, the .CR initstate() and .CR setstate() functions return a pointer to the previous state array. Otherwise, a NULL pointer is returned. .SH ERRORS If the .CR initstate() function is called with .I size less than 8, or if the .CR setstate() function detects that the state information has been damaged, error messages are written to standard error. .SH SEE ALSO .PP drand48(3C), rand(3C). .SH STANDARDS COMPLIANCE .CR random() "COSE API, XPG 4.2" .br .CR srandom() "COSE API, XPG 4.2" .br .CR initstate() "COSE API, XPG 4.2" .br .CR setstate() "COSE API, XPG 4.2" .\" .\" index@\f4random()\f1, \f4srandom()\f1, \f4initstate()\f1, \f4setstate()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f4srandom()\f1, \f4initstate()\f1, \f4setstate()\f1, \f4random()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f4initstate()\f1, \f4setstate()\f1, \f4random()\f1, \f4srandom()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f4setstate()\f1, \f4random()\f1, \f4srandom()\f1, \f4initstate()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f1math: pseudorandom number generation functions@@@\f3random(3M)\f1 .\" index@\f1pseudorandom number generation functions@@@\f3random(3M)\f1 .\" index@\f1random number generation functions@@@\f3random(3M)\f1 .\" .\" toc@\f3random(3M)\f1:\0\0\f4random()\f1, \f4srandom()\f1, \f4initstate()\f1, \f4setstate()\f1@@@generate a pseudorandom number .\" toc@\f4random()\f1:\0\0pseudorandom number generation functions@@@see \f3random(3M)\f1 .\" toc@\f4srandom()\f1:\0\0pseudorandom number generation functions@@@see \f3random(3M)\f1 .\" toc@\f4initstate()\f1:\0\0pseudorandom number functions@@@see \f3random(3M)\f1 .\" toc@\f4setstate()\f1:\0\0pseudorandom number functions@@@see \f3random(3M)\f1 .\" .\" links@random.3m srandom.3m .\" links@random.3m initstate.3m .\" links@random.3m setstate.3m .\" .\" fileset_database@random.3m PROGRAMING-MAN .\" $Header: cbreak.3x,v 76.2 95/07/31 17:13:10 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH cbreak 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cbreak, nocbreak, noraw, raw \(em input mode control functions .SH SYNOPSIS .C "#include " .P .C "int cbreak(void);" .P .C "int nocbreak(void);" .P .C "int noraw(void);" .P .C "int raw(void);" .SH DESCRIPTION The .Fn cbreak function sets the input mode for the current terminal to \f2cbreak\f1 mode and overrides a call to .CR raw() . .P The .Fn nocbreak function sets the input mode for the current terminal to Cooked Mode without changing the state of ISIG and IXON. .P The .Fn noraw function sets the input mode for the current terminal to Cooked Mode and sets the ISIG and IXON flags. .P The .Fn raw function sets the input mode for the current terminal to Raw Mode. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" If the application is not certain what the input mode of the process was at the time it called .Fn initscr , it should use these functions to specify the desired input mode. .SH "SEE ALSO" \f3Input Mode\f1 in curses_intro, , .br \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Chapter 9, \f3General Terminal Interface\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn raw and .Fn noraw functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The argument list for all these functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3cbreak(3X)\f1:\0\0\f4cbreak()\f1, \f4nocbreak()\f1, \f4noraw()\f1, \f4raw()\f1@@@input mode control functions .\" toc@\f4nocbreak()\f1: input mode control functions@@@see \f3cbreak(3X)\f1 .\" toc@\f4raw()\f1: input mode control functions@@@see \f3cbreak(3X)\f1 .\" toc@\f4noraw()\f1: input mode control functions@@@see \f3cbreak(3X)\f1 .\" .\" index@\f4cbreak()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f4nocbreak()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f4raw()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f4noraw()\f1 \- input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f1input mode control functions@@@\f3cbreak(3X)\f1 .\" index@\f1control functions, input mode@@@\f3cbreak(3X)\f1 .\" index@\f1functions, for input mode control@@@\f3cbreak(3X)\f1 .\" .\" links@cbreak.3x nocbreak.3x .\" links@cbreak.3x noraw.3x .\" links@cbreak.3x raw.3x .\" .\" fileset_database@cbreak.3x CURS-ENG-A-MAN .\" $Header: rcmd.3n,v 72.5 94/12/09 15:04:46 ssa Exp $ .TA r .TH rcmd 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rcmd(), rresvport(), ruserok() \- return a stream to a remote command .SH SYNOPSIS .nf .C "int rcmd(" .C " char **ahost," .C " int remport," .C " const char *locuser," .C " const char *remuser," .C " const char *cmd," .C " int *fd2p);" .PP .C "int rresvport(int *port);" .PP .C "int ruserok(" .C " const char *rhost," .C " int superuser," .C " const char *ruser," .C " const char *luser);" .fi .SH DESCRIPTION .SS rcmd() The .CR rcmd() function is used by privileged programs to execute a command on a remote host. .CR rcmd() returns a file descriptor for the socket to which the standard input and standard output of the command are attached. A command level interface to .CR rcmd() is provided by .CR remsh (see .IR remsh (1)), which is the same as the BSD .CR rsh command. .PP .IR ahost is a pointer to the address of the remote host name. The name of the remote host can be either an official host name or an alias as understood by .CR gethostbyname() (see .IR gethostent (3N), .IR named (1M), and .IR hosts (4)). .PP .IR remport is the Internet port on the remote system, which .CR rcmd() will try to connect to. .PP .I locuser and .I remuser point to the user login name on the local host and on the remote host, respectively. The names are used by the server on the remote host to authenticate the user (see .CR ruserok() below). .PP .I cmd points to a string that specifies the command to be executed on the remote host. .PP .IR fd2p is a pointer to an integer (it can be a NULL pointer). .PP .CR rcmd() looks up the host .CI * ahost using .CR gethostbyname() , returning \(mi1 if the host does not exist. Otherwise, .CI * ahost is set to the standard name of the host and a connection is established to a server accepting requests at the port .IR remport . If the connection is refused after five tries, or if it was refused for a reason other than the port being in use, .CR rcmd() returns \(mi1. .PP If the call succeeds, a socket of type SOCK_STREAM is returned to the caller and given to the remote command as .CR stdin and .CR stdout . If .I fd2p is non-NULL, .CR rcmd() opens a second socket between the calling process (local) and the control process (remote), and places its descriptor in .CI * fd2p\f1. On this connection, the control process sends the diagnostic output .RC ( stderr ) from .I cmd to the calling process, and receives UNIX signals from the calling process, to be forwarded to .IR cmd . If the auxiliary port cannot be set up, .CR rcmd() returns \(mi1. If .I fd2p is NULL, .CR stderr of the remote command is made the same as .CR stdout , and no provision is made for sending arbitrary signals to the remote process. .PP The protocol is described in detail in .IR remshd (1M). .PP Any program using .CR rcmd() must be run as superuser. .SS rresvport() The .CR rresvport() function creates a socket and binds it to a reserved port. This socket is suitable for use by .CR rcmd() and several other routines. .PP The caller is expected to set the initial value of .CI * port to a number between 512 and .CR IPPORT_RESERVED \(mi1. (The value of .CR IPPORT_RESERVED is defined in .CR netinet/in.h and is 1024.) Typically, the initial value of .CI * port is set to .CR IPPORT_RESERVED \(mi1. If the value is outside the valid range, .CR rresvport() resets it silently to .CR IPPORT_RESERVED \(mi1. The function uses the inital value of .CI * port as the first port number that it tries to .I bind to the created socket. If the operation fails, .CR rresvport() decrements .CI * port and attempts to .I bind the new port number to the socket. The process is repeated until either the operation succeeds, or the port numbers between 512 and .CR IPPORT_RESERVED \(mi1 are exhausted. .PP If the call succeeds, the socket descriptor is returned to the caller and the port number is returned in the location pointed to by .IR port . If the call fails, \(mi1 is returned to the caller. .PP The socket returned by .CR rresvport() has the .CR SO_KEEPALIVE option on. .PP Only the superuser is permitted to bind a privileged address to a socket. Therefore, any program using .CR rresvport() must be run as superuser. .SS ruserok() The .CR ruserok() function is used by servers to authenticate clients requesting service with .CR rcmd() . .CR ruserok() verifies that .I ruser on .I rhost is authorized to act as .I luser on the local host. .PP .I superuser is an integer flag that should be nonzero if the local user name corresponds to a superuser. If the .I superuser flag is not set, .CR ruserok() first checks the file .CR /etc/hosts.equiv to authenticate the request for service. If this check succeeds, .CR ruserok() returns 0. If the .I superuser flag is set, or if there is no file .CR /etc/hosts.equiv , or if the check fails, .CR ruserok() then checks the file .CR .rhosts (if there is one) in the local user's home directory. .CR ruserok() returns 0 if this check succeeds. Otherwise, it returns \(mi1. .PP Typically, the file .CR /etc/hosts.equiv contains a list of host names, and users' .CR .rhosts files contain host-name/user-name pairs. A remote user is authenticated by .CR ruserok() if the remote host name appears in .CR /etc/hosts.equiv and the remote user name and local user name are the same, or if the remote host name and the remote user name appear together in .CR .rhosts in the home directory of the local user. .PP For a complete explanation of the syntax understood by .CR ruserok() , see .IR hosts.equiv (4). .SH DIAGNOSTICS .SS rcmd() Diagnostic Messages .CR rcmd() generates the following diagnostic messages. .RS .TP .IC hostname ": Unknown host" .IP .I gethostbyname was unable to find an entry in the hosts database matching the name of the server (see .IR gethostent (3N) and .IR hosts (4)). .IP .IR "Next step" : Have the system administrator of your host check whether the remote host's entry is in the .CR hosts database (see .IR hosts (4)). .TP .CI "connect: \&" hostname ": \&" \f1...\& .IP Unable to establish a connection to the reserved port. A message that specifies the reason for the failure is appended to this diagnostic message. .TP .C "write: Setting up stderr" .IP Error writing to the socket connection set up for error message transmission. .TP .IC "system call" ": \&" \f1...\& .IP Error executing the system call. Appended to this error is a message specifying the reason for the failure. .TP .C "socket: Protocol failure in circuit setup" .IP Socket connection not established on a reserved port or socket address not of the Internet family type. .TP .CI "read: " hostname ": \&" \f1...\& .IP Error in reading information from the standard socket connection. Appended to this error is a message explaining the reason for the error. .TP .C "Connection timeout" .IP The remote host did not connect within 30 seconds to the secondary socket set up as an error connection. .TP .C "Lost connection" .IP The program attempted to read from the socket and failed. This means the socket connection with the remote host was lost. .TP .IR message \f1...\& .IP An error message can be transmitted through the socket connection from the daemon. That message will be sent to .CR stderr . .TP .C "primary connection shutdown" .IP While waiting for the secondary socket to be set up, .CR rcmd() had its primary connection shut down. This may have been caused by an .I inetd security failure. .TP .CR "recv: \&" ...\& .IP While trying to set up the secondary .RC ( stderr ) socket, .CR rcmd() had an error condition on its primary connection. .TP .C "accept: Interrupted system call" .IP While trying to set up its secondary socket, .CR rcmd() ran out of some resource that caused the accept to be timed out. .IP .IR "Next step" : Repeat the command. .RE .SS rresvport() Diagnostic Messages .CR rresvport() generates the following diagnostic messages. These messages can also appear in .CR rcmd() since .CR rcmd() calls .CR rresvport() . .RS .TP .IC "system call" ": \&" \f1...\& .IP Error in executing the system call. The error message returned by the system call is appended to the message. .TP .C "socket: All ports in use" .IP All reserved ports in use. If a timeout occurs, check whether the Internet Services are installed and .CR inetd is running. .RE .SH EXAMPLES To execute the .CR date command on remote host .CR hpxzgy using the remote account .CR chm , call .CR rcmd() as shown below. This program requires superuser privileges and the remote account must be equivalent (see .IR hosts.equiv (4)) to the local account that runs the program. .nf .IP .ift .ft 4 .ifn .ft 3 .ps +1 \#include \#include \#include \#include \#include \#include .ift .sp .5v .ifn .sp struct passwd *getpwuid(); char *host[] = { "hpxzgy" }; char *cmd = "date"; char *ruser = "chm"; .ift .sp .5v .ifn .sp main(argc,argv) int argc; char **argv; { struct servent *sp; struct passwd *pwd; FILE *fp; char ch; int rem; .ift .sp .5v .ifn .sp sp = getservbyname("shell","tcp"); pwd = getpwuid(getuid()); rem = rcmd(host, sp\->s_port, pwd\->pw_name, ruser, cmd, 0); if (rem < 0) exit(1); /* rcmd outputs its own error messages */ fp = fdopen(rem, "r"); while ((ch = getc(fp)) != EOF) putchar(ch); } .ft .ps .fi .SH WARNINGS There is no way to specify options to the .CR socket() call that .CR rcmd() makes. Since .CR rcmd() replaces the pointer to the host name .RC ( * \f2ahost\f1) with a pointer to the standard name of the host in a static data area, this value must be copied into the user's data area if it is to be used later. Otherwise, unpredictable results will occur. .SH AUTHOR .CR rcmd() was developed by the University of California, Berkeley. .SH SEE ALSO login(1), rlogin(1), remsh(1), named(1M), remshd(1M), rexecd(1M), gethostent(3N), rexec(3N), hosts.equiv(4). .\" .\" index@\f4rcmd()\f1 \- execute a command on a remote host@@@\f3rcmd(3N)\f1 .\" index@\f4resvport()\f1 \- return a reserved port socket@@@\f3rcmd(3N)\f1 .\" index@\f4ruserok()\f1 \- verify a remote user as a local user@@@\f3rcmd(3N)\f1 .\" index@\f1execute a command on a remote host@@@\f3rcmd(3N)\f1 .\" index@\f1command on a remote host, execute a@@@\f3rcmd(3N)\f1 .\" index@\f1remote host, execute a command on a@@@\f3rcmd(3N)\f1 .\" index@\f1return a reserved port socket@@@\f3rcmd(3N)\f1 .\" index@\f1reserved port socket, return a@@@\f3rcmd(3N)\f1 .\" index@\f1port socket, return a reserved@@@\f3rcmd(3N)\f1 .\" index@\f1socket, return a reserved port@@@\f3rcmd(3N)\f1 .\" index@\f1verify a remote user as a local user@@@\f3rcmd(3N)\f1 .\" index@\f1local user, verify a remote user as a@@@\f3rcmd(3N)\f1 .\" index@\f1remote user, verify as a local user@@@\f3rcmd(3N)\f1 .\" .\" index@return a stream to a remote command@@@\f3rcmd(3N)\f1 .\" index@stream, return to a remote command@@@\f3rcmd(3N)\f1 .\" index@remote command, return a stream to@@@\f3rcmd(3N)\f1 .\" index@command, remote, return a stream to@@@\f3rcmd(3N)\f1 .\" .\" links@rcmd.3n rresvport.3n .\" links@rcmd.3n ruserok.3n .\" .\" toc@\f3rcmd(3N)\f1:\0\0\f4rcmd()\f1, \f4rresvport()\f1, \f4ruserok()\f1@@@return a stream to a remote command .\" toc@\f4rresvport()\f1:\0\0return a stream to a remote command@@@see \f3rcmd(3N)\f1 .\" toc@\f4ruserok()\f1:\0\0return a stream to a remote command@@@see \f3rcmd(3N)\f1 .\" $Header: re_comp.3x,v 76.3 95/07/24 17:23:12 ssa Exp $ .TA r .TH re_comp 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .de Fn .CR \\$1() .. .de Hd .CR <\\$1> . .. .SH NAME re_comp, re_exec \(em compile and execute regular expressions (\f2TO BE WITHDRAWN\fP) .SH SYNOPSIS .C "#include " .P .C "char *re_comp(const char *\f2string\fP);" .P .C "int re_exec(const char *\f2string\fP);" .SH DESCRIPTION The .Fn re_comp function converts a regular expression string (RE) into an internal form suitable for pattern matching. The .Fn re_exec function compares the string pointed to by the \f2string\f1 argument with the last regular expression passed to .CR re_comp() . .P If .Fn re_comp is called with a null pointer argument, the current regular expression remains unchanged. .P Strings passed to both .Fn re_comp and .Fn re_exec must be terminated by a null byte, and may include newline characters. .P The .Fn re_comp and .Fn re_exec functions support .IR "simple regular expressions" , which are defined below. .P The following one-character REs match a single character: .RS .TP <4> .SM 1.1 An ordinary character (not one of those discussed in 1.2 below) is a one-character RE that matches itself. .TP .SM 1.2 A backslash (\e) followed by any special character is a one-character RE that matches the special character itself. The special characters are: .TP 10 .SM a. \&\f3.\fP, \f3*\fP, \f3[\fP, and \f3\^\e\f1 (period, asterisk, left square bracket, and backslash, respectively), which are always special, except when they appear within square brackets (\^\f3[\|]\fP\^; see 1.4 below). .TP .SM b. ^ (caret or circumflex), which is special at the beginning of an entire RE (see 3.1 and 3.2 below), or when it immediately follows the left of a pair of square brackets (\^\f3[\|]\fP\^) (see 1.4 below). .TP .SM c. \f3$\f1 (dollar symbol), which is special at the end of an entire RE (see 3.2 below). .TP .SM d. The character used to bound (delimit) an entire RE, which is special for that RE. .RE .TP <4> .SM 1.3 A period (\^\f3.\fP\^) is a one-character RE that matches any character except new-line. .TP .SM 1.4 A non-empty string of characters enclosed in square brackets (\^\f3[\|]\fP\^) is a one-character RE that matches any one character in that string. If, however, the first character of the string is a circumflex (^), the one-character RE matches any character except new-line and the remaining characters in the string. The ^ has this special meaning only if it occurs first in the string. The minus (\f3\-\fP) may be used to indicate a range of consecutive ASCII characters; for example, \f3[0\-9]\f1 is equivalent to \f3[0123456789]\f1. The \f3\-\f1 loses this special meaning if it occurs first (after an initial ^, if any) or last in the string. The right square bracket (\^\f3]\fP\^) does not terminate such a string when it is the first character within it (after an initial ^, if any); for example, \f3[\|]a\-f]\f1 matches either a right square bracket (\^\f3]\fP\^) or one of the letters \f3a\f1 through \f3f\f1 inclusive. The four characters listed in 1.2.a above stand for themselves within such a string of characters. .RE .br .ne 8 .P The following rules may be used to construct REs from one-character REs: .RS .TP 4 .SM 2.1 A one-character RE is a RE that matches whatever the one-character RE matches. .TP .SM 2.2 A one-character RE followed by an asterisk (\f3*\fP) is a RE that matches zero or more occurrences of the one-character RE. If there is any choice, the longest leftmost string that permits a match is chosen. .TP .SM 2.3 A one-character RE followed by \f3\^\e{\fP\^\f2m\fP\^\f3\e}\fP, \f3\^\e{\fP\^\f2m,\fP\^\f3\e}\fP, or \f3\^\e{\fP\^\f2m,n\fP\^\f3\e}\f1 is a RE that matches a range of occurrences of the one-character RE. The values of .I m\^ and .I n\^ must be non-negative integers less than 256; \f3\^\e{\fP\^\f2m\fP\^\f3\e}\f1 matches exactly .I m\^ occurrences; \f3\^\e{\fP\^\f2m,\fP\^\f3\e}\f1 matches at least .I m\^ occurrences; \f3\^\e{\fP\^\f2m,n\fP\^\f3\e}\f1 matches any number of occurrences between .I m\^ and .I n\^ inclusive. Whenever a choice exists, the RE matches as many occurrences as possible. .TP .SM 2.4 The concatenation of REs is a RE that matches the concatenation of the strings matched by each component of the RE. .TP .SM 2.5 A RE enclosed between the character sequences \f3\^\e(\f1 and \f3\^\e)\f1 is a RE that matches whatever the unadorned RE matches. .TP .SM 2.6 The expression \f3\^\e\f2n\fP\^ \f1matches the same string of characters as was matched by an expression enclosed between \f3\^\e(\f1 and \f3\^\e)\f1 earlier in the same RE. Here .I n is a digit; the sub-expression specified is that beginning with the .I n -th occurrence of \f3\^\e(\f1 counting from the left. For example, the expression ^\e(.*\e)\e1$ matches a line consisting of two repeated appearances of the same string. .RE .P Finally, an entire RE may be constrained to match only an initial segment or final segment of a line (or both). .RS .TP 4 .SM 3.1 A circumflex (^) at the beginning of an entire RE constrains that RE to match an initial segment of a line. .TP .SM 3.2 A dollar symbol (\^\f3$\fP\^) at the end of an entire RE constrains that RE to match a final segment of a line. The construction ^\f2entire RE\fP$ constrains the entire RE to match the entire line. .RE .P The null RE (that is, \f3//\fP) is equivalent to the last RE encountered. .P The behaviour of .Fn re_comp and .Fn re_exec in locales other than the POSIX locale is unspecified. .SS "RETURN VALUE" The .Fn re_comp function returns a null pointer when the string pointed to by the \f2string\f1 argument is successfully converted. Otherwise, a pointer to an unspecified error message string is returned. .P Upon successful completion, .Fn re_exec returns 1 if \f2string\f1 matches the last compiled regular expression. Otherwise, .Fn re_exec returns 0 if \f2string\f1 fails to match the last compiled regular expression, and \(mi1 if the compiled regular expression is invalid (indicating an internal error). .SS ERRORS No errors are defined. .SS "APPLICATION USAGE" For portability to implementations conforming to earlier versions of this document, .Fn regcomp and .Fn regexec are preferred to these functions. .SS "SEE ALSO" regcomp(3C), . .SS "CHANGE HISTORY" First released in Issue 4, Version 2. .\" .\" index@\f4re_comp()\f1 \- compile and execute regular expressions@@@\f3re_comp(3X)\f1 .\" index@\f4re_exec()\f1 \- compile and execute regular expressions@@@\f3re_comp(3X)\f1 .\" index@\f1compile and execute regular expressions@@@\f3re_comp(3X)\f1 .\" index@\f1execute, and compile, regular expressions@@@\f3re_comp(3X)\f1 .\" index@\f1regular expressions, compile and execute@@@\f3re_comp(3X)\f1 .\" index@\f1expressions, compile and execute regular expressions@@@\f3re_comp(3X)\f1 .\" .\" toc@\f3re_comp(3X)\f1:\0\0\f4re_comp()\f1, \f4re_exec()\f1@@@compile and execute regular expressions .\" toc@\f4re_exec()\f1:\0\0compile and execute regular expressions@@@see \f3re_comp(3X)\f1 .\" .\" links@re_comp.3x re_exec.3x .\" $Header: re_comp.3x,v 76.3 95/07/24 17:23:12 ssa Exp $ .TA r .TH re_comp 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .de Fn .CR \\$1() .. .de Hd .CR <\\$1> . .. .SH NAME re_comp, re_exec \(em compile and execute regular expressions (\f2TO BE WITHDRAWN\fP) .SH SYNOPSIS .C "#include " .P .C "char *re_comp(const char *\f2string\fP);" .P .C "int re_exec(const char *\f2string\fP);" .SH DESCRIPTION The .Fn re_comp function converts a regular expression string (RE) into an internal form suitable for pattern matching. The .Fn re_exec function compares the string pointed to by the \f2string\f1 argument with the last regular expression passed to .CR re_comp() . .P If .Fn re_comp is called with a null pointer argument, the current regular expression remains unchanged. .P Strings passed to both .Fn re_comp and .Fn re_exec must be terminated by a null byte, and may include newline characters. .P The .Fn re_comp and .Fn re_exec functions support .IR "simple regular expressions" , which are defined below. .P The following one-character REs match a single character: .RS .TP <4> .SM 1.1 An ordinary character (not one of those discussed in 1.2 below) is a one-character RE that matches itself. .TP .SM 1.2 A backslash (\e) followed by any special character is a one-character RE that matches the special character itself. The special characters are: .TP 10 .SM a. \&\f3.\fP, \f3*\fP, \f3[\fP, and \f3\^\e\f1 (period, asterisk, left square bracket, and backslash, respectively), which are always special, except when they appear within square brackets (\^\f3[\|]\fP\^; see 1.4 below). .TP .SM b. ^ (caret or circumflex), which is special at the beginning of an entire RE (see 3.1 and 3.2 below), or when it immediately follows the left of a pair of square brackets (\^\f3[\|]\fP\^) (see 1.4 below). .TP .SM c. \f3$\f1 (dollar symbol), which is special at the end of an entire RE (see 3.2 below). .TP .SM d. The character used to bound (delimit) an entire RE, which is special for that RE. .RE .TP <4> .SM 1.3 A period (\^\f3.\fP\^) is a one-character RE that matches any character except new-line. .TP .SM 1.4 A non-empty string of characters enclosed in square brackets (\^\f3[\|]\fP\^) is a one-character RE that matches any one character in that string. If, however, the first character of the string is a circumflex (^), the one-character RE matches any character except new-line and the remaining characters in the string. The ^ has this special meaning only if it occurs first in the string. The minus (\f3\-\fP) may be used to indicate a range of consecutive ASCII characters; for example, \f3[0\-9]\f1 is equivalent to \f3[0123456789]\f1. The \f3\-\f1 loses this special meaning if it occurs first (after an initial ^, if any) or last in the string. The right square bracket (\^\f3]\fP\^) does not terminate such a string when it is the first character within it (after an initial ^, if any); for example, \f3[\|]a\-f]\f1 matches either a right square bracket (\^\f3]\fP\^) or one of the letters \f3a\f1 through \f3f\f1 inclusive. The four characters listed in 1.2.a above stand for themselves within such a string of characters. .RE .br .ne 8 .P The following rules may be used to construct REs from one-character REs: .RS .TP 4 .SM 2.1 A one-character RE is a RE that matches whatever the one-character RE matches. .TP .SM 2.2 A one-character RE followed by an asterisk (\f3*\fP) is a RE that matches zero or more occurrences of the one-character RE. If there is any choice, the longest leftmost string that permits a match is chosen. .TP .SM 2.3 A one-character RE followed by \f3\^\e{\fP\^\f2m\fP\^\f3\e}\fP, \f3\^\e{\fP\^\f2m,\fP\^\f3\e}\fP, or \f3\^\e{\fP\^\f2m,n\fP\^\f3\e}\f1 is a RE that matches a range of occurrences of the one-character RE. The values of .I m\^ and .I n\^ must be non-negative integers less than 256; \f3\^\e{\fP\^\f2m\fP\^\f3\e}\f1 matches exactly .I m\^ occurrences; \f3\^\e{\fP\^\f2m,\fP\^\f3\e}\f1 matches at least .I m\^ occurrences; \f3\^\e{\fP\^\f2m,n\fP\^\f3\e}\f1 matches any number of occurrences between .I m\^ and .I n\^ inclusive. Whenever a choice exists, the RE matches as many occurrences as possible. .TP .SM 2.4 The concatenation of REs is a RE that matches the concatenation of the strings matched by each component of the RE. .TP .SM 2.5 A RE enclosed between the character sequences \f3\^\e(\f1 and \f3\^\e)\f1 is a RE that matches whatever the unadorned RE matches. .TP .SM 2.6 The expression \f3\^\e\f2n\fP\^ \f1matches the same string of characters as was matched by an expression enclosed between \f3\^\e(\f1 and \f3\^\e)\f1 earlier in the same RE. Here .I n is a digit; the sub-expression specified is that beginning with the .I n -th occurrence of \f3\^\e(\f1 counting from the left. For example, the expression ^\e(.*\e)\e1$ matches a line consisting of two repeated appearances of the same string. .RE .P Finally, an entire RE may be constrained to match only an initial segment or final segment of a line (or both). .RS .TP 4 .SM 3.1 A circumflex (^) at the beginning of an entire RE constrains that RE to match an initial segment of a line. .TP .SM 3.2 A dollar symbol (\^\f3$\fP\^) at the end of an entire RE constrains that RE to match a final segment of a line. The construction ^\f2entire RE\fP$ constrains the entire RE to match the entire line. .RE .P The null RE (that is, \f3//\fP) is equivalent to the last RE encountered. .P The behaviour of .Fn re_comp and .Fn re_exec in locales other than the POSIX locale is unspecified. .SS "RETURN VALUE" The .Fn re_comp function returns a null pointer when the string pointed to by the \f2string\f1 argument is successfully converted. Otherwise, a pointer to an unspecified error message string is returned. .P Upon successful completion, .Fn re_exec returns 1 if \f2string\f1 matches the last compiled regular expression. Otherwise, .Fn re_exec returns 0 if \f2string\f1 fails to match the last compiled regular expression, and \(mi1 if the compiled regular expression is invalid (indicating an internal error). .SS ERRORS No errors are defined. .SS "APPLICATION USAGE" For portability to implementations conforming to earlier versions of this document, .Fn regcomp and .Fn regexec are preferred to these functions. .SS "SEE ALSO" regcomp(3C), . .SS "CHANGE HISTORY" First released in Issue 4, Version 2. .\" .\" index@\f4re_comp()\f1 \- compile and execute regular expressions@@@\f3re_comp(3X)\f1 .\" index@\f4re_exec()\f1 \- compile and execute regular expressions@@@\f3re_comp(3X)\f1 .\" index@\f1compile and execute regular expressions@@@\f3re_comp(3X)\f1 .\" index@\f1execute, and compile, regular expressions@@@\f3re_comp(3X)\f1 .\" index@\f1regular expressions, compile and execute@@@\f3re_comp(3X)\f1 .\" index@\f1expressions, compile and execute regular expressions@@@\f3re_comp(3X)\f1 .\" .\" toc@\f3re_comp(3X)\f1:\0\0\f4re_comp()\f1, \f4re_exec()\f1@@@compile and execute regular expressions .\" toc@\f4re_exec()\f1:\0\0compile and execute regular expressions@@@see \f3re_comp(3X)\f1 .\" .\" links@re_comp.3x re_exec.3x .\" $Header: directory.3c,v 76.1 95/07/05 17:28:05 ssa Exp $ .TA d .TH directory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME opendir(\|), readdir(\|), readdir_r(\|), telldir(\|), seekdir(\|), rewinddir(\|), closedir(\|) \- directory operations .SH SYNOPSIS .C "#include " .PP .C "DIR *opendir(const char *dirname);" .PP .C "struct dirent *readdir(DIR *dirp);" .PP .C "int readdir_r(DIR *dirp, struct dirent *result);" .PP .C "long int telldir(DIR *dirp);" .PP .C "void seekdir(DIR *dirp, long int loc);" .PP .C "void rewinddir(DIR *dirp);" .PP .C "int closedir(DIR *dirp);" .SH DESCRIPTION This library package provides functions that allow programs to read directory entries without having to know the actual directory format associated with the file system. Because these functions allow programs to be used portably on file systems with different directory formats, this is the recommended way to read directory entries. .TP 15 .CR opendir() opens the directory .I dirname and associates a directory stream with it. .CR opendir() returns a pointer used to identify the directory stream in subsequent operations. .CR opendir() uses .IR malloc (3C) to allocate memory. .TP .CR readdir() returns a pointer to the next directory entry. It returns a .SM NULL pointer upon reaching the end of the directory or detecting an invalid .CR seekdir() operation. See .IR dirent (5) for a description of the fields available in a directory entry. .TP .CR readdir_r() expects to be passed the address of a .CR "struct dirent" and will store the result at the supplied location. .TP .CR telldir() returns the current location (encoded) associated with the directory stream to which .IR dirp refers. .TP .CR seekdir() sets the position of the next .CR readdir() operation on the directory stream to which .IR dirp refers. The .IR loc argument is a location within the directory stream obtained from .CR telldir() . The position of the directory stream is restored to where it was when .CR telldir() returned that .I loc value. Values returned by .CR telldir() are valid only while the .CR DIR pointer from which they are derived remains open. If the directory stream is closed and then reopened, the .CR telldir() value might be invalid. .TP .CR rewinddir() resets the position of the directory stream to which .IR dirp refers to the beginning of the directory. It also causes the directory stream to refer to the current state of the corresponding directory, as a call to .CR opendir() would have done. .TP .CR closedir() closes the named directory stream, then frees the structure associated with the .CR DIR pointer. .SH RETURN VALUE .TP 15 .CR opendir() , upon successful completion, returns a pointer to an object of type .CR DIR referring to an open directory stream. Otherwise, it returns a .SM NULL pointer and sets the global variable .CR errno to indicate the error. .TP .CR readdir() , upon successful completion, returns a pointer to an object of type .CR struct dirent describing a directory entry. Upon reaching the end of the directory, .CR readdir() returns a .SM NULL pointer and does not change the value of .CR errno . Otherwise, it returns a .SM NULL pointer and sets .CR errno to indicate the error. .TP .CR readdir_r() , upon successful completion, returns a 0. Upon reaching the end of directory or encountering an error, it returns a -1 and sets .CR errno to indicate the error. .TP .CR telldir() , upon successful completion, returns a long value indicating the current position in the directory. Otherwise it returns .CR \-1 and sets .CR errno to indicate the error. .TP .CR seekdir() does not return any value, but if an error is encountered, .CR errno is set to indicate the error. .TP .CR closedir() , upon successful completion, returns a value of .CR 0 . Otherwise, it returns a value of .CR \-1 and sets .CR errno to indicate the error. .SH ERRORS .CR opendir() fails if any of the following conditions are encountered: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of .IR dirname , or read permission is denied for .IR dirname . .TP .SM [EFAULT] .I dirname points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the path name. .TP .SM [EMFILE] Too many open file descriptors are currently open for the calling process. .TP .SM [ENAMETOOLONG] A component of .IR dirname exceeds .CR PATH_MAX bytes, or the entire length of .IR dirname exceeds .CR PATH_MAX \(mi 1 bytes while .CR _POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] Too many open file descriptors are currently open on the system. .TP .SM [ENOENT] A component of .I dirname does not exist. .TP .SM [ENOMEM] .CR malloc() failed to provide sufficient memory to process the directory. .TP .SM [ENOTDIR] A component of .I dirname is not a directory. .TP .SM [ENOENT] The .IR dirname argument points to an empty string. .RE .PP .CR readdir() " or " readdir_r() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] The directory stream to which .IR dirp refers is not located at a valid directory entry. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR telldir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR seekdir() might fail if the following condition is encountered: .RS .TP 20 .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR closedir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP 20 .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR rewinddir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .SH EXAMPLES The following code searches the current directory for an entry .IR name : .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 DIR *dirp; struct dirent *dp; dirp = opendir("."); while ((dp = readdir(dirp)) != NULL) { if (strcmp(dp->d_name, name) == 0) { (void) closedir(dirp); return FOUND; } } (void) closedir(dirp); return NOT_FOUND; .ft .ps .fi .RE .SH WARNINGS .CR readdir() and .CR getdirentries() (see .IR getdirentries (2) are the only ways to access remote .SM NFS directories. Attempting to read a remote directory via .SM NFS by using .CR read() returns .CR \-1 and sets .CR errno to .SM EISDIR (see .IR read (2)). .PP .CR readdir() is unsafe in multi-thread applications. .CR readdir_r() is MT-Safe and should be used instead. Users of .CR readdir_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH APPLICATION USAGE The header file required for these functions and the type of the return value from .CR readdir() has been changed for compatibility with System V Release 3 and the .IR "X/Open Portability Guide" . See .IR ndir (5) for a description of the header file .RC < ndir.h >, which is provided to allow existing .SM HP-UX applications to compile unmodified. .PP New applications should use the .RC < dirent.h > header file for portability to System V and X/Open systems. .SH AUTHOR .CR directory was developed by AT&T, HP, and the University of California, Berkeley. .SH SEE ALSO close(2), getdirentries(2), lseek(2), open(2), read(2), dir(4), dirent(5), ndir(5). .SH STANDARDS CONFORMANCE .CR closedir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR opendir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR readdir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR rewinddir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR seekdir() ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR telldir() ": AES, XPG2, XPG3, XPG4" .\" .\" index@\f4opendir()\f1 \- open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f4readdir()\f1 \- get pointer to current entry in open directory@@@\f3directory(3C)\f1 .\" index@\f4telldir()\f1 \- get current location of named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4seekdir()\f1 \- set position of next \f4readdir()\f1 operation on named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4rewinddir()\f1 \- reset position of named \f2directory stream\f1 to beginning of directory@@@\f3directory(3C)\f1 .\" index@\f4closedir()\f1 \- close a currently open directory@@@\f3directory(3C)\f1 .\" index@open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f2directory stream\f1, directory and associated, open for access@@@\f3directory(3C)\f1 .\" index@open, access, or close a directory@@@\f3directory(3C)\f1 .\" index@close, access, or open a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@directory: access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" .\" toc@\f3directory(3C)\f1:\0\0\f4directory()\f1, \f4opendir()\f1, \f4readdir()\f1, \f4telldir()\f1, \f4seekdir()\f1, \f4rewinddir()\f1,\n\f4closedir()\f1@@@directory operations .\" toc@\f4opendir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4readdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4telldir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4seekdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4rewinddir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4closedir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" .\" links@directory.3c opendir.3c .\" links@directory.3c readdir.3c .\" links@directory.3c readdir_r.3c .\" links@directory.3c telldir.3c .\" links@directory.3c seekdir.3c .\" links@directory.3c rewinddir.3c .\" links@directory.3c closedir.3c .\" $Header: directory.3c,v 76.1 95/07/05 17:28:05 ssa Exp $ .TA d .TH directory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME opendir(\|), readdir(\|), readdir_r(\|), telldir(\|), seekdir(\|), rewinddir(\|), closedir(\|) \- directory operations .SH SYNOPSIS .C "#include " .PP .C "DIR *opendir(const char *dirname);" .PP .C "struct dirent *readdir(DIR *dirp);" .PP .C "int readdir_r(DIR *dirp, struct dirent *result);" .PP .C "long int telldir(DIR *dirp);" .PP .C "void seekdir(DIR *dirp, long int loc);" .PP .C "void rewinddir(DIR *dirp);" .PP .C "int closedir(DIR *dirp);" .SH DESCRIPTION This library package provides functions that allow programs to read directory entries without having to know the actual directory format associated with the file system. Because these functions allow programs to be used portably on file systems with different directory formats, this is the recommended way to read directory entries. .TP 15 .CR opendir() opens the directory .I dirname and associates a directory stream with it. .CR opendir() returns a pointer used to identify the directory stream in subsequent operations. .CR opendir() uses .IR malloc (3C) to allocate memory. .TP .CR readdir() returns a pointer to the next directory entry. It returns a .SM NULL pointer upon reaching the end of the directory or detecting an invalid .CR seekdir() operation. See .IR dirent (5) for a description of the fields available in a directory entry. .TP .CR readdir_r() expects to be passed the address of a .CR "struct dirent" and will store the result at the supplied location. .TP .CR telldir() returns the current location (encoded) associated with the directory stream to which .IR dirp refers. .TP .CR seekdir() sets the position of the next .CR readdir() operation on the directory stream to which .IR dirp refers. The .IR loc argument is a location within the directory stream obtained from .CR telldir() . The position of the directory stream is restored to where it was when .CR telldir() returned that .I loc value. Values returned by .CR telldir() are valid only while the .CR DIR pointer from which they are derived remains open. If the directory stream is closed and then reopened, the .CR telldir() value might be invalid. .TP .CR rewinddir() resets the position of the directory stream to which .IR dirp refers to the beginning of the directory. It also causes the directory stream to refer to the current state of the corresponding directory, as a call to .CR opendir() would have done. .TP .CR closedir() closes the named directory stream, then frees the structure associated with the .CR DIR pointer. .SH RETURN VALUE .TP 15 .CR opendir() , upon successful completion, returns a pointer to an object of type .CR DIR referring to an open directory stream. Otherwise, it returns a .SM NULL pointer and sets the global variable .CR errno to indicate the error. .TP .CR readdir() , upon successful completion, returns a pointer to an object of type .CR struct dirent describing a directory entry. Upon reaching the end of the directory, .CR readdir() returns a .SM NULL pointer and does not change the value of .CR errno . Otherwise, it returns a .SM NULL pointer and sets .CR errno to indicate the error. .TP .CR readdir_r() , upon successful completion, returns a 0. Upon reaching the end of directory or encountering an error, it returns a -1 and sets .CR errno to indicate the error. .TP .CR telldir() , upon successful completion, returns a long value indicating the current position in the directory. Otherwise it returns .CR \-1 and sets .CR errno to indicate the error. .TP .CR seekdir() does not return any value, but if an error is encountered, .CR errno is set to indicate the error. .TP .CR closedir() , upon successful completion, returns a value of .CR 0 . Otherwise, it returns a value of .CR \-1 and sets .CR errno to indicate the error. .SH ERRORS .CR opendir() fails if any of the following conditions are encountered: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of .IR dirname , or read permission is denied for .IR dirname . .TP .SM [EFAULT] .I dirname points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the path name. .TP .SM [EMFILE] Too many open file descriptors are currently open for the calling process. .TP .SM [ENAMETOOLONG] A component of .IR dirname exceeds .CR PATH_MAX bytes, or the entire length of .IR dirname exceeds .CR PATH_MAX \(mi 1 bytes while .CR _POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] Too many open file descriptors are currently open on the system. .TP .SM [ENOENT] A component of .I dirname does not exist. .TP .SM [ENOMEM] .CR malloc() failed to provide sufficient memory to process the directory. .TP .SM [ENOTDIR] A component of .I dirname is not a directory. .TP .SM [ENOENT] The .IR dirname argument points to an empty string. .RE .PP .CR readdir() " or " readdir_r() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] The directory stream to which .IR dirp refers is not located at a valid directory entry. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR telldir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR seekdir() might fail if the following condition is encountered: .RS .TP 20 .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR closedir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP 20 .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR rewinddir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .SH EXAMPLES The following code searches the current directory for an entry .IR name : .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 DIR *dirp; struct dirent *dp; dirp = opendir("."); while ((dp = readdir(dirp)) != NULL) { if (strcmp(dp->d_name, name) == 0) { (void) closedir(dirp); return FOUND; } } (void) closedir(dirp); return NOT_FOUND; .ft .ps .fi .RE .SH WARNINGS .CR readdir() and .CR getdirentries() (see .IR getdirentries (2) are the only ways to access remote .SM NFS directories. Attempting to read a remote directory via .SM NFS by using .CR read() returns .CR \-1 and sets .CR errno to .SM EISDIR (see .IR read (2)). .PP .CR readdir() is unsafe in multi-thread applications. .CR readdir_r() is MT-Safe and should be used instead. Users of .CR readdir_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH APPLICATION USAGE The header file required for these functions and the type of the return value from .CR readdir() has been changed for compatibility with System V Release 3 and the .IR "X/Open Portability Guide" . See .IR ndir (5) for a description of the header file .RC < ndir.h >, which is provided to allow existing .SM HP-UX applications to compile unmodified. .PP New applications should use the .RC < dirent.h > header file for portability to System V and X/Open systems. .SH AUTHOR .CR directory was developed by AT&T, HP, and the University of California, Berkeley. .SH SEE ALSO close(2), getdirentries(2), lseek(2), open(2), read(2), dir(4), dirent(5), ndir(5). .SH STANDARDS CONFORMANCE .CR closedir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR opendir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR readdir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR rewinddir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR seekdir() ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR telldir() ": AES, XPG2, XPG3, XPG4" .\" .\" index@\f4opendir()\f1 \- open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f4readdir()\f1 \- get pointer to current entry in open directory@@@\f3directory(3C)\f1 .\" index@\f4telldir()\f1 \- get current location of named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4seekdir()\f1 \- set position of next \f4readdir()\f1 operation on named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4rewinddir()\f1 \- reset position of named \f2directory stream\f1 to beginning of directory@@@\f3directory(3C)\f1 .\" index@\f4closedir()\f1 \- close a currently open directory@@@\f3directory(3C)\f1 .\" index@open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f2directory stream\f1, directory and associated, open for access@@@\f3directory(3C)\f1 .\" index@open, access, or close a directory@@@\f3directory(3C)\f1 .\" index@close, access, or open a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@directory: access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" .\" toc@\f3directory(3C)\f1:\0\0\f4directory()\f1, \f4opendir()\f1, \f4readdir()\f1, \f4telldir()\f1, \f4seekdir()\f1, \f4rewinddir()\f1,\n\f4closedir()\f1@@@directory operations .\" toc@\f4opendir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4readdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4telldir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4seekdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4rewinddir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4closedir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" .\" links@directory.3c opendir.3c .\" links@directory.3c readdir.3c .\" links@directory.3c readdir_r.3c .\" links@directory.3c telldir.3c .\" links@directory.3c seekdir.3c .\" links@directory.3c rewinddir.3c .\" links@directory.3c closedir.3c .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "realize" "Xt \- Intrinsics Methods" .SH "Name" .Na realize \- Core class method to create a widget's window. .Nz .XS "realize method" .XS "methods, realize" .SH "Synopsis" .Sy typedef void (*XtRealizeProc)(Widget, XtValueMask *, .br XSetWindowAttributes *); .As Widget \f(CIw\fP; XtValueMask *\f(CIvalue_mask\fP; XSetWindowAttributes *\f(CIattributes\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that is to have its window created. .IP \f(CIvalue_mask\fP 1i Specifies which fields in the \f(CIattributes\fR structure are set. .IP \f(CIattributes\fP 1i Specifies the window attributes derived from the widget instance structure. .\" .SH "Description" The \f(CWrealize()\fP method is registered on the \f(CWrealize\fP field of the Core class part structure. It is called when a widget is realized (generally because an ancestor was realized with \f(CWXtRealizeWidget()\fP) and is responsible for creating an X window for the widget. .LP The \f(CIattributes\fP argument points to an \f(CWXSetWindowAttributes\fP structure that has been initialized by the Intrinsics, and \f(CIvalue_mask\fP points to a set of flags that specify which fields have been initialized. The \f(CWXSetWindowAttributes\fP structure is shown in the "Structures" section below. The fields are initialized as follows: .IP \(bu 3n \f(CWbackground_pixmap\fP is set to the value of the widget's \f(CWXtNbackgroundPixmap\fP resource, or if this resource is unspecified, the \f(CWbackground_pixel\fP field is set to the value of the widget's \f(CWXtNbackground\fP resource. .IP \(bu \f(CWborder_pixmap\fP is set to the value of the widget's \f(CWXtNborderPixmap\fP resource, or, if this resource is unspecified, the \f(CWborder_pixel\fP field is set to the value of the \f(CWXtNborderColor\fP resource. .IP \(bu \f(CWcolormap\fR is set to the value of the \f(CWXtNcolormap\fP resource of the widget. .IP \(bu \f(CWevent_mask\fP is set based on the event handlers registered for the widget, the translations that are specified for the widget, whether the widget has an \f(CWexpose()\fP method, and whether the widget's \f(CWvisible_interest\fP field is \f(CWTrue\fR. .IP \(bu \f(CWbit_gravity\fP is set to \f(CWNorthWestGravity\fR if the widget does not have an \f(CWexpose()\fP method. .LP The \f(CWrealize()\fP method may set any other field in \f(CIattributes\fP as appropriate for the particular widget class (and its superclasses), and then should create the widget's window by\p calling \f(CWXtCreateWindow()\fP. This is a convenient procedure that automatically uses the correct parent, position, size, etc., from the widget's instance record, and sets the created window in the widget's \f(CWwindow\fP field. See \f(CWXtCreateWindow\fP(1) for more information. .LP The \f(CWrealize()\fP method is not chained. A widget class that does not need any special window attributes set should inherit the realize method from its superclass by specifying \f(CWXtInheritRealize\fP on the \f(CWrealize\fP field of the Core class part structure. No widget should have a \f(CWNULL\fP \f(CWrealize()\fP method. .\" .SH "Usage" Note that the \f(CIvalue_mask\fP argument to this method is a pointer to the value mask, not the value mask itself. This is unusual, and you should be careful to correctly de-reference this argument when using it. .LP The \f(CWrealize()\fP method defined for Core calls \f(CWXtCreateWindow()\fR with the passed \f(CIvalue_mask\fP and \f(CIattributes\fR and with the \f(CIwindowClass\fP and \f(CIvisual\fP arguments set to \f(CWCopyFromParent\fR. This is sufficient for most widgets; both Composite and Constraint inherit it, and most new widget subclasses can do the same. .LP A common reason to write a custom \f(CWrealize()\fP method is to set the \f(CWbit_gravity\fP window attribute to something other than its default value. A label widget might set bit gravity depending on the justification of the label, for example, and thereby avoid some expose events when the widget was resized. If a widget uses the Shape extension to obtain a non-rectangular window, the window should be re-shaped in the \f(CWrealize()\fP method. (The Xaw Command widget does this.) A composite widget can control the stacking order of its children by explicitly realizing them in the desired order from within its own \f(CWrealize()\fP method. Also, a non-composite widget that creates its own private children widgets must explicitly realize them from the \f(CWrealize()\fP method. .LP Custom \f(CWrealize()\fP methods usually explicitly call the \f(CWrealize()\fP method of their superclass. The superclass's method may have inherited the Core \f(CWrealize()\fP method and create the window, or it may set its own fields in \f(CIattributes\fP and invoke the method of \fIits\fP superclass. Eventually a method will be called that actually creates the window and returns. "Enveloping" the \f(CWrealize()\fP method in this way creates a kind of subclass-to-superclass chaining. When you envelop a method of your superclass, use the superclass pointer directly, do \fInot\fP use \f(CWXtSuperclass()\fP to obtain the superclass of the supplied widget instance. If \fIB\fP is a subclass of \fIA\fP, for example, then the widget passed to \fIB\fP's \f(CWrealize()\fP method may be of class \fIB\fP, or may be of some subclass \fIC\fP of \fIB\fP. If you call \f(CWXtSuperclass()\fP on this widget, you will get class \fIB\fP rather than class \fIA\fP, and the \f(CWrealize()\fP method will recursively call itself and loop until it runs out of stack space and crashes. .\" .SH "Example" The following procedures are the \f(CWrealize()\fP methods from the X11R5 Xaw Command and Panner widgets. The first simply calls its superclass's method to create the window, and then uses the Shape extension to change the window's shape. The second procedure sets a background pixmap for the window, even if the core \f(CWXtNbackgroundPixmap\fP resource is unspecified, and then calls its superclass's method. .LP Note that the first procedure finds its superclass's method by going through its own class pointer directly. The second procedure envelops the superclass method incorrectly, using the instance pointer. A subclass of this widget that inherited this method would crash when realized, as described in the section above. .Nd 5 .Ps static void Realize(w, valueMask, attributes) Widget w; Mask *valueMask; XSetWindowAttributes *attributes; { (*commandWidgetClass->core_class.superclass->core_class.realize) (w, valueMask, attributes); ShapeButton( (CommandWidget) w, FALSE); } static void Realize (gw, valuemaskp, attr) Widget gw; XtValueMask *valuemaskp; XSetWindowAttributes *attr; { PannerWidget pw = (PannerWidget) gw; Pixmap pm = XtUnspecifiedPixmap; Boolean gotpm = FALSE; if (pw->core.background_pixmap == XtUnspecifiedPixmap) { if (pw->panner.stipple_name) pm = BACKGROUND_STIPPLE (pw); if (PIXMAP_OKAY(pm)) { attr->background_pixmap = pm; *valuemaskp = CWBackPixmap; *valuemaskp &= ~CWBackPixel; gotpm = TRUE; } } (*gw->core.widget_class->core_class.superclass->core_class.realize) (gw, valuemaskp, attr); if (gotpm) XFreePixmap (XtDisplay(gw), pm); } .Pe .\" .SH "Structures" The \f(CWXSetWindowAttributes\fP structure, the \f(CWXtValueMask\fP type, and the flags that can be set in this type are defined as follows: .Ps .ps 8 .ta 4n 2.5i typedef struct { Pixmap background_pixmap; /* background or None or ParentRelative * / unsigned long background_pixel; /* background pixel */ Pixmap border_pixmap; /* border of the window */ unsigned long border_pixel; /* border pixel value */ int bit_gravity; /* one of bit gravity values */ int win_gravity; /* one of the window gravity values */ int backing_store; /* NotUseful, WhenMapped, Always */ unsigned long backing_planes; /* planes to be preserved if possible */ unsigned long backing_pixel; /* value to use in restoring planes */ Bool save_under; /* should bits under be saved (popups) */ long event_mask; /* set of events that should be saved */ long do_not_propagate_mask; /* set of events that shouldn't propagate */ Bool override_redirect; /* boolean value for override-redirect */ Colormap colormap; /* colormap to be associated with window */ Cursor cursor; /* cursor to be displayed (or None) */ } XSetWindowAttributes; typedef unsigned long XtValueMask; #define CWBackPixmap (1L<<0) #define CWBackPixel (1L<<1) #define CWBorderPixmap (1L<<2) #define CWBorderPixel (1L<<3) #define CWBitGravity (1L<<4) #define CWWinGravity (1L<<5) #define CWBackingStore (1L<<6) #define CWBackingPlanes (1L<<7) #define CWBackingPixel (1L<<8) #define CWOverrideRedirect (1L<<9) #define CWSaveUnder (1L<<10) #define CWEventMask (1L<<11) #define CWDontPropagate (1L<<12) #define CWColormap (1L<<13) #define CWCursor (1L<<14) .ps 10 .Pe .\" .SH "See Also" .na .br \s-1\fIXtCreateWindow\fR\s+1\*(s1, \s-1\fIXtRealizeWidget\fR\s+1\*(s1, .br \s-1\fICore\fR\s+1\*(s3. .ad .XE "realize method" .XE "methods, realize" .\"last line comment .\" $Header: malloc.3c,v 72.6 94/11/15 09:55:17 ssa Exp $ .TA m .TH malloc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME malloc(), free(), realloc(), calloc(), valloc(), mallopt(), mallinfo(), memorymap(), alloca() \- main memory allocator .SH SYNOPSIS .C "#include " .PP .C "void *malloc(size_t size);" .PP .C "void *calloc(size_t nelem, size_t elsize);" .PP .C "void *realloc(void *ptr, size_t size);" .PP .C "void *valloc(size_t size);" .PP .C "void free(void *ptr);" .PP .C "void memorymap(int show_stats);" .PP .C " " .PP .C "#include " .PP .C "void *alloca(size_t size);" .SH SYSTEM V SYNOPSIS .C "#include " .PP .C "char *malloc(unsigned size);" .PP .C "void free(char *ptr);" .PP .C "char *realloc(char *ptr, unsigned size);" .PP .C "char *calloc(unsigned nelem, unsigned elsize);" .PP .C "int mallopt(int cmd, int value);" .PP .C "struct mallinfo mallinfo(void);" .SS Remarks The functionality in the old .IR malloc (3X) package has been incorporated into .IR malloc (3C). The library .RC ( /usr/lib/libmalloc.a ) corresponding to the .CR -lmalloc linker option is now an empty library. Makefiles that reference this library will continue to work. Applications that used the .IR malloc (3X) package should still work properly with the new .IR malloc (3C) package. If the old versions must be used, they are provided in files .CR /usr/old/libmalloc3x.a and .CR /usr/old/libmalloc3c.o for Release 8.07 only. .SH DESCRIPTION The functions described in this manual entry provide a simple, general purpose memory allocation package: .RS .TP 17 .C malloc() Allocates space for a block of at least .I size bytes, but does not initialize the space. .TP .C calloc() Allocates space for an array of .I nelem elements, each of size .I elsize bytes, and initializes the space to zeros. Actual amount of space allocated will be at least .I nelem * elsize bytes. .TP .C realloc() Changes the size of the block pointed to by .I ptr to .I size bytes and returns a pointer to the (possibly moved) block. Existing contents are unchanged up to the lesser of the new and old sizes. If .I ptr is a NULL pointer, .CR realloc() behaves like .CR malloc() for the specified size. If .I size is zero and .I ptr is not a NULL pointer, the object it points to is freed and NULL is returned. .TP .C valloc() Allocates space for a block of at least .I size bytes starting on a boundary aligned to a multiple of the value returned by .IR sysconf(__SC_PAGESIZE) . This space is uninitialized. .TP .C free() Deallocates the space pointed to by .I ptr (a pointer to a block previously allocated by .CR malloc() , .CR realloc() , or .CR calloc() ) and makes the space available for further allocation. If .I ptr is a NULL pointer, no action occurs. .TP .C mallopt() Provides for control over the allocation algorithm and other options in the .IR malloc (3C) package. The available values for .I cmd are: .RS .RS .TP 15 .C M_MXFAST Set .IR maxfast to .IR value . The algorithm allocates all blocks below the size of .IR maxfast in large groups, then doles them out very quickly. The default value for .IR maxfast is zero. .TP .C M_NLBLKS Set .IR numlblks to .IR value . The above mentioned ``large groups'' each contain .I numlblks blocks. .I numlblks must be greater than 1. The default value for .I numlblks is .CR 100 . .TP .C M_GRAIN Set .I grain to .IR value . The sizes of all blocks smaller than .I maxfast are considered to be rounded up to the nearest multiple of .IR grain . .I grain must be greater than zero. The default value of .I grain is the smallest number of bytes that can accommodate alignment of any data type. .I value is rounded up to a multiple of the default when .I grain is set. .TP .C M_KEEP Preserve data in a freed block until the next .CR malloc() , .CR realloc() , or .CR calloc() . This option is provided only for compatibility with the old version of .CR malloc() and is not recommended. .TP .C M_BLOCK Block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option is provided for those who need to write signal handlers that allocate memory. When set, the .IR malloc (3C) routines can be called from within signal handlers (they become re-entrant). Default action is .I not to block all blockable signals. .TP .C M_UBLOCK Do not block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option cancels signal blocking initiated by the .CR M_BLOCK option. .RE .RE .IP These values are defined in the .CR header file. .IP .CR mallopt() can be called repeatedly, but must not be called after the first small block is allocated (unless .I cmd is set to .CR M_BLOCK or .CR M_UBLOCK ). .TP .C mallinfo() Provides instrumentation describing space usage, but cannot be called until the first small block is allocated. It returns the structure: .nf .IP .C "struct mallinfo {" .C " int arena; /* total space in arena */" .C " int ordblks; /* number of ordinary blocks */" .C " int smblks; /* number of small blocks */" .C " int hblkhd; /* space in holding block headers */" .C " int hblks; /* number of holding blocks */" .C " int usmblks /* space in small blocks in use */" .C " int fsmblks /* space in free small blocks */" .C " int uordblks; /* space in ordinary blocks in use */" .C " int fordblks; /* space in free ordinary blocks */" .C " int keepcost; /* space penalty if keep option is used */" .C } .fi .IP This structure is defined in the .CR header file. .RE .PP Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. .RS .TP 17 .C memorymap() Can be used to display the contents of the memory allocator. A list of addresses and block descriptions is written (using .CR printf() ) to standard output. If the value of the .I show_stats parameter is 1, statistics concerning number of blocks and sizes used will also be written. If the value is zero, only the memory map will be written. .IP The addresses and sizes displayed by .CR memorymap() may not correspond to those requested by an application. The size of a block (as viewed by the allocator) includes header information and padding to properly align the block. The address is also offset by a certain amount to accommodate the header information. .TP .C alloca() Allocates space from the stack of the caller for a block of at least .I size bytes, but does not initialize the space. The space is automatically freed when the calling routine exits. .IP Memory returned by .CR alloca() is not related to memory allocated by other memory allocation functions. Behavior of addresses returned by .CR alloca() as parameters to other memory functions is undefined. .IP The implementation of this routine is system dependent and its use is discouraged. .RE .SH RETURN VALUE Upon successful completion, .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. Otherwise, they return a NULL pointer. If .CR realloc() returns a NULL pointer, the memory pointed to by the original pointer is left intact. .PP .CR mallopt() returns zero for success and nonzero for failure. .SH DIAGNOSTICS .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a NULL pointer if there is no available memory, or if the memory managed by .CR malloc() has been detectably corrupted. This memory may become corrupted if data is stored outside the bounds of a block, or if an invalid pointer (a pointer not generated by .CR malloc() , .CR realloc() , or .CR calloc() ) is passed as an argument to .CR free() or .CR realloc() . .PP If .CR mallopt() is called after any allocation of a small block and .I cmd is not set to .CR M_BLOCK or .CR M_UBLOCK , or if .I cmd or .I value is invalid, nonzero is returned. Otherwise, it returns zero. .SH ERRORS .RS .TP 17 [ENOMEM] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to ENOMEM and return a NULL pointer when an out-of-memory condition arises. .TP [EINVAL] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to EINVAL and return a NULL pointer when the memory being managed by .CR malloc() has been detectably corrupted. .SH WARNINGS .CR malloc() functions use .CR brk() and .CR sbrk() (see .IR brk (2)) to increase the address space of a process. Therefore, an application program that uses .CR brk() or .CR sbrk() must not use them to decrease the address space, because this confuses the .CR malloc() functions. .PP .CR free() and .CR realloc() do not check their pointer argument for validity. .PP If .CR free() or .CR realloc() is passed a pointer that was not the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() , or if space assigned by an allocation function is overrun, loss of data, a memory fault, bus error, or an infinite loop may occur at that time or during any subsequent call to .CR malloc() , .CR realloc() , .CR calloc() , .CR valloc() , or .CR free() . .PP The following actions are not supported and cause undesirable effects: .RS .TP 3 \(bu Attempting to .CR free() or .CR realloc() a pointer not generated as the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() . .RE .PP The following actions are strongly discouraged and may be unsupported in a future implementation of .CR malloc() : .RS .TP 3 \(bu attempting to .CR free() the same block twice, .TP \(bu depending on unmodified contents of a block after it has been freed. .RE .PP Undocumented features of earlier memory allocators have not been duplicated. .SH COMPATIBILITY The only external difference between the old .IR malloc (3X) allocator and the .IR malloc (3C) allocator is that the old allocator would return a NULL pointer for a request of zero bytes. The .IR malloc (3C) allocator returns a valid memory address. This is not a concern for most applications. .ift .br .ift .ne 4 .PP Although the current implementation of .IR malloc (3C) allows for freeing a block twice and does not corrupt the contents of a block after it is freed (until the next call to .CR realloc() , .CR calloc() , .CR malloc() , or .CR valloc() ), support for these features may be discontinued in a future implementation of .IR malloc (3C) and should not be used. .SH SEE ALSO brk(2), errno(2). .SH STANDARDS CONFORMANCE .CR malloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR calloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR free() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mallinfo() ": SVID2, XPG2" .PP .CR mallopt() ": SVID2, SVID3, XPG2" .PP .CR realloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4malloc()\f1 \- allocate block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4free()\f1 \- release allocated block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4realloc()\f1 \- change size of allocated memory block@@@\f3malloc(3C)\f1 .\" index@\f4calloc()\f1 \- allocate memory for array@@@\f3malloc(3C)\f1 .\" index@\f4mallopt()\f1 \- control memory space allocation@@@\f3malloc(3C)\f1 .\" index@\f4mallinfo()\f1 \- display memory space usage@@@\f3malloc(3C)\f1 .\" index@\f4memorymap()\f1 \- display contents of memory allocator@@@\f3malloc(3C)\f1 .\" index@\f4alloca()\f1 \- allocate space from the stack@@@\f3malloc(3C)\f1 .\" index@\f4valloc()\f1 \- allocate space on boundary aligned to sysconf value@@@\f3malloc(3C)\f1 .\" index@\f1main memory allocator@@@\f3malloc(3C)\f1 .\" index@\f1memory allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1main memory space usage, display@@@\f3malloc(3C)\f1 .\" index@\f1main memory space allocation, control@@@\f3malloc(3C)\f1 .\" .\" toc@\f3malloc(3C)\f1:\0\0\f4alloca()\f1, \f4calloc()\f1, \f4free()\f1, \f4mallinfo()\f1,\n\f4malloc()\f1, \f4mallopt()\f1, \f4memorymap()\f1, \f4realloc()\f1, \f4valloc()\f1@@@main memory allocator\f1 .\" .\" toc@\f4free()\f1:\0\0release allocated block of main memory@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4realloc()\f1:\0\0change size of allocated memory block@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4calloc()\f1:\0\0allocate memory for array@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4valloc()\f1:\0\0allocate space on boundary aligned to sysconf value@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallopt()\f1:\0\0control memory space allocation@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallinfo()\f1:\0\0display memory space usage@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4memorymap()\f1:\0\0display contents of memory allocator@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4alloca()\f1:\0\0allocate space from the stack@@@\f1see \f3malloc(3C)\f1 .\" .\" links@malloc.3c free.3c .\" links@malloc.3c realloc.3c .\" links@malloc.3c calloc.3c .\" links@malloc.3c valloc.3c .\" links@malloc.3c mallopt.3c .\" links@malloc.3c mallinfo.3c .\" links@malloc.3c memorymap.3c .\" links@malloc.3c alloca.3c .\" $Header: realpath.3x,v 76.2 95/07/06 14:54:33 ssa Exp $ .TA r .TH realpath 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .de Fn .CR \\$1 () .. .de Hd .BR <\\$1> .. .SH NAME realpath \(em resolve pathname .SH SYNOPSIS .C "#include " .P .C "char *realpath(const char *\f2file_name\fP, char *\f2resolved_name\fP);" .SH DESCRIPTION The .Fn realpath function derives, from the pathname pointed to by .I file_name , an absolute pathname that names the same file, whose resolution does not involve ".", "..", or symbolic links. The generated pathname is stored, up to a maximum of .CR {PATH_MAX} bytes, in the buffer pointed to by .I resolved_name . .SS "RETURN VALUE" On successful completion, .Fn realpath returns a pointer to the resolved name. Otherwise, .Fn realpath returns a null pointer and sets \f2errno\f1 to indicate the error, and the contents of the buffer pointed to by \f2resolved_name\f1 are undefined. .SS ERRORS The .Fn realpath function will fail if: .RS .TP 25 [EACCES] Read or search permission was denied for a component of .I file_name . .TP [EINVAL] Either the \f2file_name\f1 or \f2resolved_name\f1 argument is a null pointer. .TP [EIO] An error occurred while reading from the file system. .TP [ELOOP] Too many symbolic links were encountered in resolving \f2path\f1. .TP [ENAMETOOLONG] The \f2file_name\f1 argument is longer than .CR {PATH_MAX} or a pathname component is longer than .CR {NAME_MAX} . .TP [ENOENT] A component of \f2file_name\f1 does not name an existing file or \f2file_name\f1 points to an empty string. .TP [ENOTDIR] A component of the path prefix is not a directory. .RE .P The .Fn realpath function may fail if: .RS .TP 25 [ENAMETOOLONG] Pathname resolution of a symbolic link produced an intermediate result whose length exceeds .CR {PATH_MAX} . .TP [ENOMEM] Insufficient storage space is available. .RE .SS "SEE ALSO" getcwd(3C), sysconf(2), . .SS "CHANGE HISTORY" First released in Issue 4, Version 2. .\" .\" index@\f4realpath\f1 \- resolve pathname@@@\f3realpath(3X)\f1 .\" index@\f1resolve pathname@@@\f3realpath(3X)\f1 .\" index@\f1pathname, resolve@@@\f3realpath(3X)\f1 .\" .\" toc@\f3realpath(1)\f1:\0\0\f4realpath()\f1@@@resolve pathname .\" $Header: redrawwin.3x,v 76.2 95/08/01 14:37:40 ssa Exp $ .TA r .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH redrawwin 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME redrawwin, wredrawln \(em line update status functions .SH SYNOPSIS .C "#include " .P .C "int redrawwin(WINDOW *\f2win\fP);" .P .C "int wredrawln(WINDOW *\f2win\fP, int \f2beg_line\fP, int \f2num_lines\fP);" .SH DESCRIPTION The .Fn redrawwin and .Fn wredrawln functions inform the implementation that some or all of the information physically displayed for the specified window may have been corrupted. The .Fn redrawwin function marks the entire window; .Fn wredrawln marks only \f2num_lines\f1 lines starting at line number \f2beg_line\f1. The functions prevent the next refresh operation on that window from performing any optimisation based on assumptions about what is physically displayed there. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn redrawwin and .Fn wredrawln functions could be used in a text editor to implement a command that redraws some or all of the screen. .SH "SEE ALSO" clearok(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3redrawwin(3X)\f1:\0\0\f4redrawwin()\f1, \f4wredrawln()\f1@@@line update status functions .\" toc@\f4wredrawln()\f1: line update status functions@@@see \f3redrawwin(3X)\f1 .\" .\" index@\f4redrawwin()\f1 \- line update status functions@@@\f3redrawwin(3X)\f1 .\" index@\f4wredrawln()\f1 \- line update status functions@@@\f3redrawwin(3X)\f1 .\" index@\f1line update status functions@@@\f3redrawwin(3X)\f1 .\" index@\f1functions, for line update status@@@\f3redrawwin(3X)\f1 .\" index@\f1update status, line, functions@@@\f3redrawwin(3X)\f1 .\" index@\f1status, line update status functions@@@\f3redrawwin(3X)\f1 .\" .\" links@redrawwin.3x wredrawln.3x .\" .\" fileset_database@redrawwin.3x CURS-ENG-A-MAN .\" $Header: doupdate.3x,v 76.2 95/08/01 15:14:36 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH doupdate 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME doupdate, refresh, wnoutrefresh, wrefresh \(em refresh windows and lines .SH SYNOPSIS .C "#include " .P .C "int doupdate(void);" .P .C "int refresh(void);" .P .C "int wnoutrefresh(WINDOW *\f2win\fP);" .P .C "int wrefresh(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn refresh and .Fn wrefresh functions refresh the current or specified window. The functions position the terminal's cursor at the cursor position of the window, except that if the .Fn leaveok mode has been enabled, they may leave the cursor at an arbitrary position. .P The .Fn wnoutrefresh function determines which parts of the terminal may need updating. The .Fn doupdate function sends to the terminal the commands to perform any required changes. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Refreshing an entire window is typically more efficient than refreshing several subwindows separately. An efficient sequence is to call .Fn wnoutrefresh on each subwindow that has changed, followed by a call to .Fn doupdate , which updates the terminal. .P The .Fn refresh or .Fn wrefresh function (or .Fn wnoutrefresh followed by .Fn doupdate ) must be called to send output to the terminal, as other Curses functions merely manipulate data structures. .SH "SEE ALSO" clearok(), redrawwin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .P This entry is a merger of the X/Open Curses, Issue 3 entries .Fn refresh and .Fn wnoutrefresh . The .B DESCRIPTION is rewritten for clarity and the argument list for the .Fn doupdate and .Fn refresh functions is explicitly declared as \f3void\f1. Otherwise the functionality is identical to that defined in X/Open Curses, Issue 3. .\" .\" toc@\f3doupdate(3x)\f1:\0\0\f4doupdate()\f1, \f4refresh()\f1, \f4wnoutrefresh()\f1, \f4wrefresh()\f1@@@refresh windows and lines .\" .\" toc@\f3refresh()\f1:\0\0refresh windows and lines@@@\f1see \f3doupdate(3x)\f1 .\" toc@\f3wnoutrefresh()\f1:\0\0refresh windows and lines@@@\f1see \f3doupdate(3x)\f1 .\" toc@\f3wrefresh()\f1:\0\0refresh windows and lines@@@\f1see \f3doupdate(3x)\f1 .\" .\" index@\f4doupdate()\f1, \f4refresh()\f1, \f4wnoutrefresh()\f1, \n\f4wrefresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" index@\f4refresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" index@\f4wnoutrefresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" index@\f4wrefresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" .\" links@doupdate.3x refresh.3x .\" links@doupdate.3x wnoutrefresh.3x .\" links@doupdate.3x wrefresh.3x .\" .\" fileset_database@doupdate.3x CURS-ENG-A-MAN .\" $Header: regcmp.3x,v 72.7 94/11/02 15:53:14 ssa Exp $ .TA r .TH regcmp 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME regcmp(\|), regex(\|) \- compile and execute regular expression .SH SYNOPSIS .C "#include " .PP .C "char *regcmp(" .nf .PD 0 .IP .C "const char *string1," .C "/* string2, */ ..." .C "/*, (char *)0 */" .PP .C ");" .PD .fi .PP .C "char *regex(const char *re, const char *subject, ...);" .PP .C "extern char *__loc1;" .SS Remarks The ANSI C "\c .CR ", ...\$\c" " construct denotes a variable length argument list whose optional [or required] \" EDITOR: make this line fit the specific page members are given in the associated comment .RC ( "/* */" ). .PP Features documented in this manual entry are obsolescent and may be removed in a future HP-UX release. Use of .IR regcomp (3C) instead is recommended. .SH DESCRIPTION .C regcmp() compiles a regular expression and returns a pointer to the compiled form. .IR malloc (3C) is used to create space for the vector. It is the user's responsibility to free unneeded space so allocated. A NULL return from .C regcmp() indicates an incorrect argument. .PP .C regex() executes a compiled pattern against the subject string. Additional arguments are passed to receive values back. .C regex() returns NULL on failure, or a pointer to the next unmatched character on success. A global character pointer .C _\|_loc1 points to where the match began. .C regcmp() and .C regex() were largely borrowed from the editor, .IR ed (1); however, the syntax and semantics have been changed slightly. The following are the valid symbols and their associated meanings: .RS .TP 15 .C []*.^ These symbols retain their current meaning. .TP .C $ Matches the end of the string; .C \en matches a new-line. .TP .C - Used within brackets the hyphen signifies a character range. For example, .C [a-z] is equivalent to .CR [abcd .\|.\|. xyz] . The .C - can represent itself only if used as the first or last character. For example, the character class expression .C []-] matches the characters .C ] and .CR - . .TP .C + A regular expression followed by .C + means one or more times. For example, .C [0\-9]+ is equivalent to .CR [0-9][0-9]* . .TP .C "{\f2m\fP} {\f2m\fP,} {\f2m\fP,\f2u\fP}" Integer values enclosed in .C { } indicate the number of times the preceding regular expression can be applied. The value .I m is the minimum number and .I u is a maximum number, which must be no greater than 256. The syntax .CI { m } indicates the exact number of times the regular expression can be applied. The syntax .CI { m ,} is analogous to .RI { "m," infinity}. The plus .RC ( + ) and asterisk .RC ( * ) operations are equivalent to .C {1,} and .C {0,} respectively. .TP .CR ( \|.\|.\|.\| )$\f2n\fP" The value of the enclosed regular expression is returned. The value is stored in the .RI ( n +1)th argument following the subject argument. A maximum of ten enclosed regular expressions are allowed. .C regex() makes its assignments unconditionally. .TP .CR ( \|.\|.\|.\| ) Parentheses are used for grouping. An operator, such as .CR * , .CR + , or .CR {\0} , can work on a single character or a regular expression enclosed in parentheses. For example, .CR (a\(**(cb+)\(**)$0 . .RE .PP Since all of the above defined symbols are special characters, they must be escaped to be used as themselves. .PP .C regcmp() and .C regex() are kept in .CR /usr/lib/libPW.a , and are linked by using the .C \-lc and .C \-lPW options to the .C ld or .C cc command. See WARNINGS below. .SH EXAMPLES Match a leading new-line in the subject string to which the .I cursor points. .nf .IP .C "char *cursor, *newcursor, *ptr;" \h'.5i'\&.\|.\|. .ift .ft 4 .ifn .ft 3 .ps +1 newcursor = regex((ptr = regcmp("^\en", 0)), cursor); .ft .ps .C free(ptr); .fi .PP Match through the string .C Testing3 and return the address of the character after the last matched character (cursor+11). The string .C Testing3 will be copied to the character array .CR ret0 . .nf .IP .C "char ret0[9];" .C "char \(**newcursor, *name;" \h'.5i'.\|.\|. .ift .ft 4 .ifn .ft 3 .ps +1 name = regcmp("([A\-Za\-z][A\-Za\-z0\-9\_]{0,7})$0", 0); newcursor = regex(name, "123Testing321", ret0); .ft .ps .fi .SH WARNINGS .C regcmp() and .C regex() are kept in .CR /usr/lib/libPW.a . Unfortunately, .C /usr/lib/libPW.a also contains some functions that have the same names as functions contained in the default C library, .CR /usr/lib/libc.a or .CR /usr/lib/libc.sl . To prevent unexpected results due to these name conflicts, always search .C libc before searching .CR libPW . This is done with the .C ld (or .CR cc ) command line option sequence .C -lc -lPW which satisfies all standard C functions from .C libc then searches .C libPW for the .C regcmp() and .C regex() functions (there is also an implied .C -lc following the explicit .C -lPW to satisfy any additional C functions required by .C regcmp() and .CR regex() ). .PP User programs that use .C regcmp() might run out of memory if .C regcmp() is called iteratively without freeing vectors that are no longer required. .SH SEE ALSO ed(1), malloc(3C), regcomp(3C). .\" .\" index@\f4regcmp()\fP \- compile a regular expression@@@\f3regcmp(3X)\f1 .\" index@\f4regex()\fP \- execute a regular expression against a string@@@\f3regcmp(3X)\f1 .\" index@compile a regular expression@@@\f3regcmp(3X)\f1 .\" index@execute a regular expression against a string@@@\f3regcmp(3X)\f1 .\" index@regular expression, compile or execute against a string@@@\f3regcmp(3X)\f1 .\" index@expression, regular, compile or execute against a string@@@\f3regcmp(3X)\f1 .\" .\" toc@\f3regcmp(3X)\f1:\0\0\f4regcmp()\fP, \f4regex()\fP@@@compile and execute regular expression .\" toc@\f4regex()\fP:\0\0compile and execute regular expression@@@see \f3regcmp(3X)\f1 .\" .\" links@regcmp.3x regex.3x .\" .\" fileset_database@regcmp.3x PROGRAMING-MAN .\" $Header: regcomp.3c,v 74.1 95/05/10 21:10:56 ssa Exp $ .TA r .TH regcomp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME regcomp(\|), regerror(\|), regexec(\|), regfree(\|) \- regular expression matching routines .SH SYNOPSIS .C "#include " .PP .C "int regcomp(regex_t *preg, const char *pattern, int cflags);" .PP .C "int regexec(" .nf .PD 0 .IP .C "const regex_t *preg," .C "const char *string," .C "size_t nmatch," .C "regmatch_t pmatch[\|]," .C "int eflags" .PP .C ");" .PD .fi .PP .C "void regfree(regex_t *preg);" .PP .C "size_t regerror( .nf .PD 0 .IP .C "int errcode," .C "const regex_t *preg," .C "char *errbuf," .C "size_t errbuf_size" .PP .C ");" .PD .fi .SH DESCRIPTION These functions interpret regular expressions as described in .IR regexp (5). They support both .I basic and .I extended regular expressions. .PP The structures .C regex_t and .C regmatch_t are defined in the header .RC < regex.h >. .PP The .C regex_t structure contains at least the following member (use of other members results in non-portable code): .RS .TP 25 .C size_t re_nsub Number of parenthesized subexpressions. .RE .PP The .C regmatch_t structure contains at least the following members: .RS .TP 25 .B regoff_t rm_so Byte offset from start of string to start of substring. .TP .B regoff_t rm_eo Byte offset from start of string to the first character after the end of the substring. .RE .PP .CR regcomp() compiles the regular expression specified by the .I pattern argument and places the results in the structure pointed to by .IR preg . The .I cflags argument is the bit-wise logical .SM OR of zero or more of the following flags (defined in .RC < regex.h >): .RS .TP 18 .C REG_EXTENDED Use extended regular expressions. .TP .C REG_NEWLINE IF .C REG_NEWLINE is not set in .IR cflags , a newline character in .I pattern or .I string is treated as an ordinary character. If .C REG_NEWLINE is set, newlines are treated as ordinary characters except as follows: .RS .RS .TP 4 1. A newline in .I string is not matched by a period outside of a bracket expression or by any form of a nonmatching list. .TP 2. A circumflex .RC ( ^ ) in .IR pattern , when used to specify expression anchoring, matches the zero-length string immediately after a newline in .IR string , regardless of the setting of .CR REG_NOTBOL . .TP 3. A dollar-sign .RC ( $ ) in .IR pattern , when used to specify expression anchoring, matches the zero-length string immediately before a newline in .IR string , regardless of the setting of .CR REG_NOTEOL . .RE .RE .TP .C REG_ICASE Ignore case in match. If a character in .I pattern is defined in the current .C LC_CTYPE locale as having one or more opposite-case counterpoints, both the character and any counterpoints match the pattern character. This applies to all portions of the pattern, including a string of characters specified to be matched via a back-reference expression .RC ( \e\f2n\fP ). .IP .IR "Within bracket expressions" : Collation ranges, character classes, and equivalence classes are effectively expanded into equivalent lists of collation elements and characters. Opposite-case counterpoints are then generated for each collation element or character to form the complete matching list or non-matching list for the bracket expression. Opposite-case counterpoints for a multi-character collating element include all possible combinations of opposite-case counterpoints for each individual character comprising the collating element. These are then combined to form new valid multi-character collating elements. For example, the opposite-case counterpoints for .C [.ch.] could be .CR [.Ch.] , .CR [.cH.] , and .CR [.CH.] . .RE .PP The default regular expression type for .I pattern is Basic Regular Expression. The application can specify Extended Regular Expressions by using the .C REG_EXTENDED .I cflags value. .PP If the function .C regcomp() succeeds, it returns zero; otherwise it returns a non-zero value indicating the error. .PP If .C regcomp() succeeds, and if the .C REG_NOSUB flag was not set in .IR cflags , .C regcomp() sets .C re_nsub to the number of parenthesized subexpressions (delimited by .C \e( and .C \e) in basic regular expressions or .C ( and .C ) in extended regular expressions) found in .IR pattern . .PP .C regexec() matches the null-terminated string specified by .I string against the compiled regular expression .I preg initialized by a previous call to .CR regcomp() . If it finds a match, .C regexec() returns zero; otherwise it returns non-zero indicating either no match or an error. The .I eflags argument is the bit-wise logical .SM OR of the following flags: .RS .TP 18 .C REG_NOTBOL The first character of the string pointed to by .I string is not the beginning of the line. Therefore, the circumflex character .RC ( ^ ), when taken as a special character, never matches. .TP .C REG_NOTEOL The last character of the string pointed to by .I string is not the end of the line. Therefore, the dollar sign .RC ( $ ), when taken as a special character, never matches. .RE .PP If .I nmatch is not zero, and .C REG_NOSUB was not set in the .I cflags argument to .CR regcomp() , then .C regexec() fills in the .I pmatch array with byte offsets to the substrings of .I string that correspond to the parenthesized subexpressions of .IR pattern : .IR pmatch [ i ] .rm_so is the byte offset of the beginning and .IR pmatch [ i ] .rm_eo is the byte offset one byte past the end of the substring .IR i . (Subexpression .I i begins at the .IR i th matched left parenthesis, counting from 1). Offsets in .IR pmatch [0] identify the substring that corresponds to the entire regular expression. Unused elements of .I pmatch are set to \(mi1. If there are more than .I nmatch subexpressions in .I pattern .RI ( pattern itself counts as a subexpression), .C regexec() still does the match, but only records the first .I nmatch substrings. .PP When matching a regular expression, any given parenthesized subexpression of .I pattern might participate in the match of several different substrings of .IR string , or it might not match any substring, even though the pattern as a whole did match. The following explains which substrings are reported in .I pmatch when matching regular expressions: .RS .TP 5 1. If subexpression .I i in a regular expression is not contained within another subexpression, and it participated in the match several times, the byte offsets in .IR pmatch [ i ] delimit the last such match. .TP 2. If subexpression .I i is not contained within another subexpression, and it did not participate in an otherwise successful match (because either .CR * , .CR ? , or .C | was used), then the byte offsets in .IR pmatch [ i ] are \(mi1. .TP 3. If subexpression .I i is contained in subexpression .IR j , and a match of subexpression .I j is reported in .IR pmatch [ j ], the match or no-match reported in .IR pmatch [ i ] is the last one that occurred within the substring in .IR pmatch [ j ]. .TP 4. If subexpression .I i is contained in subexpression .IR j , and the offsets in .IR pmatch [ j ] are \(mi1, the offsets in .IR pmatch [ i ] will also be \(mi1. .TP 5. If subexpression .I i matched a zero-length string, both offsets in .IR pmatch [ i ] refer to the character immediately following the zero-length substring. .RE .PP If .C REG_NOSUB was set in .I cflags in the call to .CR regcomp() , and .I nmatch is not zero in the call to .CR regexec() , the content of the .I pmatch array is unspecified. .PP .C regfree() frees any memory allocated by .C regcomp() associated with .IR preg . .PP If the .I preg argument to .C regexec() or .C regfree() is not a compiled regular expression returned by .CR regcomp() , the result is undefined. A .I preg can no longer be treated as a compiled regular expression after it is given to .CR regfree() . .PP .C regerror() provides a mapping from error codes returned by .C regcomp() and .C regexec() to printable strings. .C regerror() generates a string corresponding to the value of the .I errcode parameter, which was the last non-zero value returned by .C regcomp() or .C regexec() with the given value of .IR preg . The .I errcode parameter can take on any of the error values defined in .RC < regex.h >. If .I errbuf_size is not zero, .C regerror() copies an appropriate error message into the buffer specified by .IR errbuf . If the error message (including the terminating null) cannot fit in the buffer, it is truncated to .I errbuf_size \(mi 1 bytes and null terminated. .PP If .I errbuf_size is zero, the .I errbuf parameter is ignored, but the return value is as defined below. .PP .IR regerror (\|) returns the size of the buffer (including terminating null) that is required to hold the entire error message. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions. .PP The .C LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, the characters matched by character-class expressions in regular expressions, and the opposite-case counterpart for each character. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .C regcomp() returns zero for success and non-zero for an invalid expression or other failure. .C regexec() returns zero if it finds a match and non-zero for no match or other failure. .SH ERRORS If .C regcomp() or .C regexec() detects one of the error conditions listed below, it returns the corresponding non-zero error code. The error codes are defined in the header .RC < regex.h >. .RS .TP 20 .C REG_BADBR The contents within the pair .C \e{ (backslash left brace) and .C \e} (backslash right brace) are unusable: not a number, number too large, more than two numbers, or first number larger than second. .TP .C REG_BADPAT An invalid regular expression. .TP .C REG_BADRPT The .CR ? (question mark), .CR * (asterisk), or .CR + (plus sign) symbols are not preceded by a valid regular expression. .TP .C REG_EBRACE The use of a pair of .C \e{ (backslash left brace) and .C \e} (backslash right brace) or .C {} (braces) is unbalanced. .TP .C REG_EBRACK The use of .C [] (brackets) is unbalanced. .TP .C REG_EBOL Using the .C ^ (caret) anchor and not beginning of line. .TP .C REG_ECHAR There is an invalid multibyte character. .TP .C REG_ECOLLATE There is an unusable collating element referenced. .TP .C REG_ECTYPE There is an unusable character class type referenced. .TP .C REG_EEOL Using the $ (dollar) anchor and not end of line. .TP .C REG_EESCAPE There is a trailing .C \e in the pattern. .TP .C REG_EPAREN The use of a pair of .C \e( (backslash left parenthesis) and .C \e) (backslash right parenthesis) or .C () is unbalanced. .TP .C REG_ERANGE There is an unusable endpoint in the range expression. .TP .C REG_ESPACE There is insufficient memory space. .TP .C REG_ESUBREG The number in .CI \e digit is invalid or in error. .TP .C REG_NOMATCH The .C regexec() function failed to match. .RE .SH EXAMPLES .nf .IP .ift .ft 4 .ps +1 /* match string against the extended regular expression in pattern, treating errors as no match. Return 1 for match, 0 for no match. Print an error message if an error occurs. */ .ift .sp .5v .ifn .sp int match(string, pattern) char *string; char *pattern; { int i; regex_t re; char buf[256]; .ift .sp .5v .ifn .sp i=regcomp(&re, pattern, REG_EXTENDED|REG_NOSUB); if (i != 0) { (void)regerror(i,&re,buf,sizeof buf); printf("%s\en",buf); return(0); /* report error */ } i = regexec(&re, string, (size_t) 0, NULL, 0); regfree(&re); if (i != 0) { (void)regerror(i,&re,buf,sizeof buf); printf("%s\en",buf); return(0); /* report error */ } return(1); } .ift .ft .ps .fi .PP The following demonstrates how the .C REG_NOTBOL flag could be used with .C regexec() to find all substrings in a line that match a pattern supplied by a user. .nf .IP .ift .ft 4 .ps +1 (void) regcomp(&re, pattern, 0); /* look for first match at start of line */ error = regexec(&re, &buffer[0], 1, &pm, 0); while (error == 0) { /* while matches found */ /* find next match on line */ error = regexec(&re, &buffer[pm.rm_eo], 1, &pm, REG_NOTBOL); } .ift .ft .ps .fi .SH AUTHOR .CR regcomp() , .CR regerror() , .CR regexec() , and .C regfree() were developed by OSF and HP. .SH SEE ALSO regexp(5). .SH STANDARDS CONFORMANCE .CR regcomp() ": XPG4, POSIX.2" .PP .CR regerror() ": XPG4, POSIX.2" .PP .CR regexec() ": XPG4, POSIX.2" .PP .CR regfree() ": XPG4, POSIX.2" .\" .\" .\" toc@\f3regcomp(3C)\f1:\0\0\f4regcomp()\f1, \f4regerror()\f1, \f4regexec()\f1, \f4regfree()\f1@@@regular expression matching routines .\" toc@\f4regerror()\f1:\0\0regular expression matching routines@@@\f1see \f3regcomp(3C)\f1 .\" toc@\f4regexec()\f1:\0\0regular expression matching routines@@@\f1see \f3regcomp(3C)\f1 .\" toc@\f4regfree()\f1:\0\0regular expression matching routines@@@\f1see \f3regcomp(3C)\f1 .\" .\" index@\f4regcomp()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f4regexec()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f4regfree()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f4regerror()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f1regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f1expression matching routines, regular@@@\f3regcomp(3C)\f1 .\" index@\f1matching routines, regular expression@@@\f3regcomp(3C)\f1 .\" index@\f1compiling routines, regular expression@@@\f3regcomp(3C)\f1 .\" .\" links@regcomp.3c regexec.3c .\" links@regcomp.3c regfree.3c .\" links@regcomp.3c regerror.3c .\" .\" fileset_database@regcomp.3c PROGRAMING-MAN .\" $Header: regcomp.3c,v 74.1 95/05/10 21:10:56 ssa Exp $ .TA r .TH regcomp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME regcomp(\|), regerror(\|), regexec(\|), regfree(\|) \- regular expression matching routines .SH SYNOPSIS .C "#include " .PP .C "int regcomp(regex_t *preg, const char *pattern, int cflags);" .PP .C "int regexec(" .nf .PD 0 .IP .C "const regex_t *preg," .C "const char *string," .C "size_t nmatch," .C "regmatch_t pmatch[\|]," .C "int eflags" .PP .C ");" .PD .fi .PP .C "void regfree(regex_t *preg);" .PP .C "size_t regerror( .nf .PD 0 .IP .C "int errcode," .C "const regex_t *preg," .C "char *errbuf," .C "size_t errbuf_size" .PP .C ");" .PD .fi .SH DESCRIPTION These functions interpret regular expressions as described in .IR regexp (5). They support both .I basic and .I extended regular expressions. .PP The structures .C regex_t and .C regmatch_t are defined in the header .RC < regex.h >. .PP The .C regex_t structure contains at least the following member (use of other members results in non-portable code): .RS .TP 25 .C size_t re_nsub Number of parenthesized subexpressions. .RE .PP The .C regmatch_t structure contains at least the following members: .RS .TP 25 .B regoff_t rm_so Byte offset from start of string to start of substring. .TP .B regoff_t rm_eo Byte offset from start of string to the first character after the end of the substring. .RE .PP .CR regcomp() compiles the regular expression specified by the .I pattern argument and places the results in the structure pointed to by .IR preg . The .I cflags argument is the bit-wise logical .SM OR of zero or more of the following flags (defined in .RC < regex.h >): .RS .TP 18 .C REG_EXTENDED Use extended regular expressions. .TP .C REG_NEWLINE IF .C REG_NEWLINE is not set in .IR cflags , a newline character in .I pattern or .I string is treated as an ordinary character. If .C REG_NEWLINE is set, newlines are treated as ordinary characters except as follows: .RS .RS .TP 4 1. A newline in .I string is not matched by a period outside of a bracket expression or by any form of a nonmatching list. .TP 2. A circumflex .RC ( ^ ) in .IR pattern , when used to specify expression anchoring, matches the zero-length string immediately after a newline in .IR string , regardless of the setting of .CR REG_NOTBOL . .TP 3. A dollar-sign .RC ( $ ) in .IR pattern , when used to specify expression anchoring, matches the zero-length string immediately before a newline in .IR string , regardless of the setting of .CR REG_NOTEOL . .RE .RE .TP .C REG_ICASE Ignore case in match. If a character in .I pattern is defined in the current .C LC_CTYPE locale as having one or more opposite-case counterpoints, both the character and any counterpoints match the pattern character. This applies to all portions of the pattern, including a string of characters specified to be matched via a back-reference expression .RC ( \e\f2n\fP ). .IP .IR "Within bracket expressions" : Collation ranges, character classes, and equivalence classes are effectively expanded into equivalent lists of collation elements and characters. Opposite-case counterpoints are then generated for each collation element or character to form the complete matching list or non-matching list for the bracket expression. Opposite-case counterpoints for a multi-character collating element include all possible combinations of opposite-case counterpoints for each individual character comprising the collating element. These are then combined to form new valid multi-character collating elements. For example, the opposite-case counterpoints for .C [.ch.] could be .CR [.Ch.] , .CR [.cH.] , and .CR [.CH.] . .RE .PP The default regular expression type for .I pattern is Basic Regular Expression. The application can specify Extended Regular Expressions by using the .C REG_EXTENDED .I cflags value. .PP If the function .C regcomp() succeeds, it returns zero; otherwise it returns a non-zero value indicating the error. .PP If .C regcomp() succeeds, and if the .C REG_NOSUB flag was not set in .IR cflags , .C regcomp() sets .C re_nsub to the number of parenthesized subexpressions (delimited by .C \e( and .C \e) in basic regular expressions or .C ( and .C ) in extended regular expressions) found in .IR pattern . .PP .C regexec() matches the null-terminated string specified by .I string against the compiled regular expression .I preg initialized by a previous call to .CR regcomp() . If it finds a match, .C regexec() returns zero; otherwise it returns non-zero indicating either no match or an error. The .I eflags argument is the bit-wise logical .SM OR of the following flags: .RS .TP 18 .C REG_NOTBOL The first character of the string pointed to by .I string is not the beginning of the line. Therefore, the circumflex character .RC ( ^ ), when taken as a special character, never matches. .TP .C REG_NOTEOL The last character of the string pointed to by .I string is not the end of the line. Therefore, the dollar sign .RC ( $ ), when taken as a special character, never matches. .RE .PP If .I nmatch is not zero, and .C REG_NOSUB was not set in the .I cflags argument to .CR regcomp() , then .C regexec() fills in the .I pmatch array with byte offsets to the substrings of .I string that correspond to the parenthesized subexpressions of .IR pattern : .IR pmatch [ i ] .rm_so is the byte offset of the beginning and .IR pmatch [ i ] .rm_eo is the byte offset one byte past the end of the substring .IR i . (Subexpression .I i begins at the .IR i th matched left parenthesis, counting from 1). Offsets in .IR pmatch [0] identify the substring that corresponds to the entire regular expression. Unused elements of .I pmatch are set to \(mi1. If there are more than .I nmatch subexpressions in .I pattern .RI ( pattern itself counts as a subexpression), .C regexec() still does the match, but only records the first .I nmatch substrings. .PP When matching a regular expression, any given parenthesized subexpression of .I pattern might participate in the match of several different substrings of .IR string , or it might not match any substring, even though the pattern as a whole did match. The following explains which substrings are reported in .I pmatch when matching regular expressions: .RS .TP 5 1. If subexpression .I i in a regular expression is not contained within another subexpression, and it participated in the match several times, the byte offsets in .IR pmatch [ i ] delimit the last such match. .TP 2. If subexpression .I i is not contained within another subexpression, and it did not participate in an otherwise successful match (because either .CR * , .CR ? , or .C | was used), then the byte offsets in .IR pmatch [ i ] are \(mi1. .TP 3. If subexpression .I i is contained in subexpression .IR j , and a match of subexpression .I j is reported in .IR pmatch [ j ], the match or no-match reported in .IR pmatch [ i ] is the last one that occurred within the substring in .IR pmatch [ j ]. .TP 4. If subexpression .I i is contained in subexpression .IR j , and the offsets in .IR pmatch [ j ] are \(mi1, the offsets in .IR pmatch [ i ] will also be \(mi1. .TP 5. If subexpression .I i matched a zero-length string, both offsets in .IR pmatch [ i ] refer to the character immediately following the zero-length substring. .RE .PP If .C REG_NOSUB was set in .I cflags in the call to .CR regcomp() , and .I nmatch is not zero in the call to .CR regexec() , the content of the .I pmatch array is unspecified. .PP .C regfree() frees any memory allocated by .C regcomp() associated with .IR preg . .PP If the .I preg argument to .C regexec() or .C regfree() is not a compiled regular expression returned by .CR regcomp() , the result is undefined. A .I preg can no longer be treated as a compiled regular expression after it is given to .CR regfree() . .PP .C regerror() provides a mapping from error codes returned by .C regcomp() and .C regexec() to printable strings. .C regerror() generates a string corresponding to the value of the .I errcode parameter, which was the last non-zero value returned by .C regcomp() or .C regexec() with the given value of .IR preg . The .I errcode parameter can take on any of the error values defined in .RC < regex.h >. If .I errbuf_size is not zero, .C regerror() copies an appropriate error message into the buffer specified by .IR errbuf . If the error message (including the terminating null) cannot fit in the buffer, it is truncated to .I errbuf_size \(mi 1 bytes and null terminated. .PP If .I errbuf_size is zero, the .I errbuf parameter is ignored, but the return value is as defined below. .PP .IR regerror (\|) returns the size of the buffer (including terminating null) that is required to hold the entire error message. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions. .PP The .C LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, the characters matched by character-class expressions in regular expressions, and the opposite-case counterpart for each character. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .C regcomp() returns zero for success and non-zero for an invalid expression or other failure. .C regexec() returns zero if it finds a match and non-zero for no match or other failure. .SH ERRORS If .C regcomp() or .C regexec() detects one of the error conditions listed below, it returns the corresponding non-zero error code. The error codes are defined in the header .RC < regex.h >. .RS .TP 20 .C REG_BADBR The contents within the pair .C \e{ (backslash left brace) and .C \e} (backslash right brace) are unusable: not a number, number too large, more than two numbers, or first number larger than second. .TP .C REG_BADPAT An invalid regular expression. .TP .C REG_BADRPT The .CR ? (question mark), .CR * (asterisk), or .CR + (plus sign) symbols are not preceded by a valid regular expression. .TP .C REG_EBRACE The use of a pair of .C \e{ (backslash left brace) and .C \e} (backslash right brace) or .C {} (braces) is unbalanced. .TP .C REG_EBRACK The use of .C [] (brackets) is unbalanced. .TP .C REG_EBOL Using the .C ^ (caret) anchor and not beginning of line. .TP .C REG_ECHAR There is an invalid multibyte character. .TP .C REG_ECOLLATE There is an unusable collating element referenced. .TP .C REG_ECTYPE There is an unusable character class type referenced. .TP .C REG_EEOL Using the $ (dollar) anchor and not end of line. .TP .C REG_EESCAPE There is a trailing .C \e in the pattern. .TP .C REG_EPAREN The use of a pair of .C \e( (backslash left parenthesis) and .C \e) (backslash right parenthesis) or .C () is unbalanced. .TP .C REG_ERANGE There is an unusable endpoint in the range expression. .TP .C REG_ESPACE There is insufficient memory space. .TP .C REG_ESUBREG The number in .CI \e digit is invalid or in error. .TP .C REG_NOMATCH The .C regexec() function failed to match. .RE .SH EXAMPLES .nf .IP .ift .ft 4 .ps +1 /* match string against the extended regular expression in pattern, treating errors as no match. Return 1 for match, 0 for no match. Print an error message if an error occurs. */ .ift .sp .5v .ifn .sp int match(string, pattern) char *string; char *pattern; { int i; regex_t re; char buf[256]; .ift .sp .5v .ifn .sp i=regcomp(&re, pattern, REG_EXTENDED|REG_NOSUB); if (i != 0) { (void)regerror(i,&re,buf,sizeof buf); printf("%s\en",buf); return(0); /* report error */ } i = regexec(&re, string, (size_t) 0, NULL, 0); regfree(&re); if (i != 0) { (void)regerror(i,&re,buf,sizeof buf); printf("%s\en",buf); return(0); /* report error */ } return(1); } .ift .ft .ps .fi .PP The following demonstrates how the .C REG_NOTBOL flag could be used with .C regexec() to find all substrings in a line that match a pattern supplied by a user. .nf .IP .ift .ft 4 .ps +1 (void) regcomp(&re, pattern, 0); /* look for first match at start of line */ error = regexec(&re, &buffer[0], 1, &pm, 0); while (error == 0) { /* while matches found */ /* find next match on line */ error = regexec(&re, &buffer[pm.rm_eo], 1, &pm, REG_NOTBOL); } .ift .ft .ps .fi .SH AUTHOR .CR regcomp() , .CR regerror() , .CR regexec() , and .C regfree() were developed by OSF and HP. .SH SEE ALSO regexp(5). .SH STANDARDS CONFORMANCE .CR regcomp() ": XPG4, POSIX.2" .PP .CR regerror() ": XPG4, POSIX.2" .PP .CR regexec() ": XPG4, POSIX.2" .PP .CR regfree() ": XPG4, POSIX.2" .\" .\" .\" toc@\f3regcomp(3C)\f1:\0\0\f4regcomp()\f1, \f4regerror()\f1, \f4regexec()\f1, \f4regfree()\f1@@@regular expression matching routines .\" toc@\f4regerror()\f1:\0\0regular expression matching routines@@@\f1see \f3regcomp(3C)\f1 .\" toc@\f4regexec()\f1:\0\0regular expression matching routines@@@\f1see \f3regcomp(3C)\f1 .\" toc@\f4regfree()\f1:\0\0regular expression matching routines@@@\f1see \f3regcomp(3C)\f1 .\" .\" index@\f4regcomp()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f4regexec()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f4regfree()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f4regerror()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f1regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f1expression matching routines, regular@@@\f3regcomp(3C)\f1 .\" index@\f1matching routines, regular expression@@@\f3regcomp(3C)\f1 .\" index@\f1compiling routines, regular expression@@@\f3regcomp(3C)\f1 .\" .\" links@regcomp.3c regexec.3c .\" links@regcomp.3c regfree.3c .\" links@regcomp.3c regerror.3c .\" .\" fileset_database@regcomp.3c PROGRAMING-MAN .\" $Header: regcmp.3x,v 72.7 94/11/02 15:53:14 ssa Exp $ .TA r .TH regcmp 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME regcmp(\|), regex(\|) \- compile and execute regular expression .SH SYNOPSIS .C "#include " .PP .C "char *regcmp(" .nf .PD 0 .IP .C "const char *string1," .C "/* string2, */ ..." .C "/*, (char *)0 */" .PP .C ");" .PD .fi .PP .C "char *regex(const char *re, const char *subject, ...);" .PP .C "extern char *__loc1;" .SS Remarks The ANSI C "\c .CR ", ...\$\c" " construct denotes a variable length argument list whose optional [or required] \" EDITOR: make this line fit the specific page members are given in the associated comment .RC ( "/* */" ). .PP Features documented in this manual entry are obsolescent and may be removed in a future HP-UX release. Use of .IR regcomp (3C) instead is recommended. .SH DESCRIPTION .C regcmp() compiles a regular expression and returns a pointer to the compiled form. .IR malloc (3C) is used to create space for the vector. It is the user's responsibility to free unneeded space so allocated. A NULL return from .C regcmp() indicates an incorrect argument. .PP .C regex() executes a compiled pattern against the subject string. Additional arguments are passed to receive values back. .C regex() returns NULL on failure, or a pointer to the next unmatched character on success. A global character pointer .C _\|_loc1 points to where the match began. .C regcmp() and .C regex() were largely borrowed from the editor, .IR ed (1); however, the syntax and semantics have been changed slightly. The following are the valid symbols and their associated meanings: .RS .TP 15 .C []*.^ These symbols retain their current meaning. .TP .C $ Matches the end of the string; .C \en matches a new-line. .TP .C - Used within brackets the hyphen signifies a character range. For example, .C [a-z] is equivalent to .CR [abcd .\|.\|. xyz] . The .C - can represent itself only if used as the first or last character. For example, the character class expression .C []-] matches the characters .C ] and .CR - . .TP .C + A regular expression followed by .C + means one or more times. For example, .C [0\-9]+ is equivalent to .CR [0-9][0-9]* . .TP .C "{\f2m\fP} {\f2m\fP,} {\f2m\fP,\f2u\fP}" Integer values enclosed in .C { } indicate the number of times the preceding regular expression can be applied. The value .I m is the minimum number and .I u is a maximum number, which must be no greater than 256. The syntax .CI { m } indicates the exact number of times the regular expression can be applied. The syntax .CI { m ,} is analogous to .RI { "m," infinity}. The plus .RC ( + ) and asterisk .RC ( * ) operations are equivalent to .C {1,} and .C {0,} respectively. .TP .CR ( \|.\|.\|.\| )$\f2n\fP" The value of the enclosed regular expression is returned. The value is stored in the .RI ( n +1)th argument following the subject argument. A maximum of ten enclosed regular expressions are allowed. .C regex() makes its assignments unconditionally. .TP .CR ( \|.\|.\|.\| ) Parentheses are used for grouping. An operator, such as .CR * , .CR + , or .CR {\0} , can work on a single character or a regular expression enclosed in parentheses. For example, .CR (a\(**(cb+)\(**)$0 . .RE .PP Since all of the above defined symbols are special characters, they must be escaped to be used as themselves. .PP .C regcmp() and .C regex() are kept in .CR /usr/lib/libPW.a , and are linked by using the .C \-lc and .C \-lPW options to the .C ld or .C cc command. See WARNINGS below. .SH EXAMPLES Match a leading new-line in the subject string to which the .I cursor points. .nf .IP .C "char *cursor, *newcursor, *ptr;" \h'.5i'\&.\|.\|. .ift .ft 4 .ifn .ft 3 .ps +1 newcursor = regex((ptr = regcmp("^\en", 0)), cursor); .ft .ps .C free(ptr); .fi .PP Match through the string .C Testing3 and return the address of the character after the last matched character (cursor+11). The string .C Testing3 will be copied to the character array .CR ret0 . .nf .IP .C "char ret0[9];" .C "char \(**newcursor, *name;" \h'.5i'.\|.\|. .ift .ft 4 .ifn .ft 3 .ps +1 name = regcmp("([A\-Za\-z][A\-Za\-z0\-9\_]{0,7})$0", 0); newcursor = regex(name, "123Testing321", ret0); .ft .ps .fi .SH WARNINGS .C regcmp() and .C regex() are kept in .CR /usr/lib/libPW.a . Unfortunately, .C /usr/lib/libPW.a also contains some functions that have the same names as functions contained in the default C library, .CR /usr/lib/libc.a or .CR /usr/lib/libc.sl . To prevent unexpected results due to these name conflicts, always search .C libc before searching .CR libPW . This is done with the .C ld (or .CR cc ) command line option sequence .C -lc -lPW which satisfies all standard C functions from .C libc then searches .C libPW for the .C regcmp() and .C regex() functions (there is also an implied .C -lc following the explicit .C -lPW to satisfy any additional C functions required by .C regcmp() and .CR regex() ). .PP User programs that use .C regcmp() might run out of memory if .C regcmp() is called iteratively without freeing vectors that are no longer required. .SH SEE ALSO ed(1), malloc(3C), regcomp(3C). .\" .\" index@\f4regcmp()\fP \- compile a regular expression@@@\f3regcmp(3X)\f1 .\" index@\f4regex()\fP \- execute a regular expression against a string@@@\f3regcmp(3X)\f1 .\" index@compile a regular expression@@@\f3regcmp(3X)\f1 .\" index@execute a regular expression against a string@@@\f3regcmp(3X)\f1 .\" index@regular expression, compile or execute against a string@@@\f3regcmp(3X)\f1 .\" index@expression, regular, compile or execute against a string@@@\f3regcmp(3X)\f1 .\" .\" toc@\f3regcmp(3X)\f1:\0\0\f4regcmp()\fP, \f4regex()\fP@@@compile and execute regular expression .\" toc@\f4regex()\fP:\0\0compile and execute regular expression@@@see \f3regcmp(3X)\f1 .\" .\" links@regcmp.3x regex.3x .\" .\" fileset_database@regcmp.3x PROGRAMING-MAN .\" $Header: regcomp.3c,v 74.1 95/05/10 21:10:56 ssa Exp $ .TA r .TH regcomp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME regcomp(\|), regerror(\|), regexec(\|), regfree(\|) \- regular expression matching routines .SH SYNOPSIS .C "#include " .PP .C "int regcomp(regex_t *preg, const char *pattern, int cflags);" .PP .C "int regexec(" .nf .PD 0 .IP .C "const regex_t *preg," .C "const char *string," .C "size_t nmatch," .C "regmatch_t pmatch[\|]," .C "int eflags" .PP .C ");" .PD .fi .PP .C "void regfree(regex_t *preg);" .PP .C "size_t regerror( .nf .PD 0 .IP .C "int errcode," .C "const regex_t *preg," .C "char *errbuf," .C "size_t errbuf_size" .PP .C ");" .PD .fi .SH DESCRIPTION These functions interpret regular expressions as described in .IR regexp (5). They support both .I basic and .I extended regular expressions. .PP The structures .C regex_t and .C regmatch_t are defined in the header .RC < regex.h >. .PP The .C regex_t structure contains at least the following member (use of other members results in non-portable code): .RS .TP 25 .C size_t re_nsub Number of parenthesized subexpressions. .RE .PP The .C regmatch_t structure contains at least the following members: .RS .TP 25 .B regoff_t rm_so Byte offset from start of string to start of substring. .TP .B regoff_t rm_eo Byte offset from start of string to the first character after the end of the substring. .RE .PP .CR regcomp() compiles the regular expression specified by the .I pattern argument and places the results in the structure pointed to by .IR preg . The .I cflags argument is the bit-wise logical .SM OR of zero or more of the following flags (defined in .RC < regex.h >): .RS .TP 18 .C REG_EXTENDED Use extended regular expressions. .TP .C REG_NEWLINE IF .C REG_NEWLINE is not set in .IR cflags , a newline character in .I pattern or .I string is treated as an ordinary character. If .C REG_NEWLINE is set, newlines are treated as ordinary characters except as follows: .RS .RS .TP 4 1. A newline in .I string is not matched by a period outside of a bracket expression or by any form of a nonmatching list. .TP 2. A circumflex .RC ( ^ ) in .IR pattern , when used to specify expression anchoring, matches the zero-length string immediately after a newline in .IR string , regardless of the setting of .CR REG_NOTBOL . .TP 3. A dollar-sign .RC ( $ ) in .IR pattern , when used to specify expression anchoring, matches the zero-length string immediately before a newline in .IR string , regardless of the setting of .CR REG_NOTEOL . .RE .RE .TP .C REG_ICASE Ignore case in match. If a character in .I pattern is defined in the current .C LC_CTYPE locale as having one or more opposite-case counterpoints, both the character and any counterpoints match the pattern character. This applies to all portions of the pattern, including a string of characters specified to be matched via a back-reference expression .RC ( \e\f2n\fP ). .IP .IR "Within bracket expressions" : Collation ranges, character classes, and equivalence classes are effectively expanded into equivalent lists of collation elements and characters. Opposite-case counterpoints are then generated for each collation element or character to form the complete matching list or non-matching list for the bracket expression. Opposite-case counterpoints for a multi-character collating element include all possible combinations of opposite-case counterpoints for each individual character comprising the collating element. These are then combined to form new valid multi-character collating elements. For example, the opposite-case counterpoints for .C [.ch.] could be .CR [.Ch.] , .CR [.cH.] , and .CR [.CH.] . .RE .PP The default regular expression type for .I pattern is Basic Regular Expression. The application can specify Extended Regular Expressions by using the .C REG_EXTENDED .I cflags value. .PP If the function .C regcomp() succeeds, it returns zero; otherwise it returns a non-zero value indicating the error. .PP If .C regcomp() succeeds, and if the .C REG_NOSUB flag was not set in .IR cflags , .C regcomp() sets .C re_nsub to the number of parenthesized subexpressions (delimited by .C \e( and .C \e) in basic regular expressions or .C ( and .C ) in extended regular expressions) found in .IR pattern . .PP .C regexec() matches the null-terminated string specified by .I string against the compiled regular expression .I preg initialized by a previous call to .CR regcomp() . If it finds a match, .C regexec() returns zero; otherwise it returns non-zero indicating either no match or an error. The .I eflags argument is the bit-wise logical .SM OR of the following flags: .RS .TP 18 .C REG_NOTBOL The first character of the string pointed to by .I string is not the beginning of the line. Therefore, the circumflex character .RC ( ^ ), when taken as a special character, never matches. .TP .C REG_NOTEOL The last character of the string pointed to by .I string is not the end of the line. Therefore, the dollar sign .RC ( $ ), when taken as a special character, never matches. .RE .PP If .I nmatch is not zero, and .C REG_NOSUB was not set in the .I cflags argument to .CR regcomp() , then .C regexec() fills in the .I pmatch array with byte offsets to the substrings of .I string that correspond to the parenthesized subexpressions of .IR pattern : .IR pmatch [ i ] .rm_so is the byte offset of the beginning and .IR pmatch [ i ] .rm_eo is the byte offset one byte past the end of the substring .IR i . (Subexpression .I i begins at the .IR i th matched left parenthesis, counting from 1). Offsets in .IR pmatch [0] identify the substring that corresponds to the entire regular expression. Unused elements of .I pmatch are set to \(mi1. If there are more than .I nmatch subexpressions in .I pattern .RI ( pattern itself counts as a subexpression), .C regexec() still does the match, but only records the first .I nmatch substrings. .PP When matching a regular expression, any given parenthesized subexpression of .I pattern might participate in the match of several different substrings of .IR string , or it might not match any substring, even though the pattern as a whole did match. The following explains which substrings are reported in .I pmatch when matching regular expressions: .RS .TP 5 1. If subexpression .I i in a regular expression is not contained within another subexpression, and it participated in the match several times, the byte offsets in .IR pmatch [ i ] delimit the last such match. .TP 2. If subexpression .I i is not contained within another subexpression, and it did not participate in an otherwise successful match (because either .CR * , .CR ? , or .C | was used), then the byte offsets in .IR pmatch [ i ] are \(mi1. .TP 3. If subexpression .I i is contained in subexpression .IR j , and a match of subexpression .I j is reported in .IR pmatch [ j ], the match or no-match reported in .IR pmatch [ i ] is the last one that occurred within the substring in .IR pmatch [ j ]. .TP 4. If subexpression .I i is contained in subexpression .IR j , and the offsets in .IR pmatch [ j ] are \(mi1, the offsets in .IR pmatch [ i ] will also be \(mi1. .TP 5. If subexpression .I i matched a zero-length string, both offsets in .IR pmatch [ i ] refer to the character immediately following the zero-length substring. .RE .PP If .C REG_NOSUB was set in .I cflags in the call to .CR regcomp() , and .I nmatch is not zero in the call to .CR regexec() , the content of the .I pmatch array is unspecified. .PP .C regfree() frees any memory allocated by .C regcomp() associated with .IR preg . .PP If the .I preg argument to .C regexec() or .C regfree() is not a compiled regular expression returned by .CR regcomp() , the result is undefined. A .I preg can no longer be treated as a compiled regular expression after it is given to .CR regfree() . .PP .C regerror() provides a mapping from error codes returned by .C regcomp() and .C regexec() to printable strings. .C regerror() generates a string corresponding to the value of the .I errcode parameter, which was the last non-zero value returned by .C regcomp() or .C regexec() with the given value of .IR preg . The .I errcode parameter can take on any of the error values defined in .RC < regex.h >. If .I errbuf_size is not zero, .C regerror() copies an appropriate error message into the buffer specified by .IR errbuf . If the error message (including the terminating null) cannot fit in the buffer, it is truncated to .I errbuf_size \(mi 1 bytes and null terminated. .PP If .I errbuf_size is zero, the .I errbuf parameter is ignored, but the return value is as defined below. .PP .IR regerror (\|) returns the size of the buffer (including terminating null) that is required to hold the entire error message. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions. .PP The .C LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, the characters matched by character-class expressions in regular expressions, and the opposite-case counterpart for each character. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .C regcomp() returns zero for success and non-zero for an invalid expression or other failure. .C regexec() returns zero if it finds a match and non-zero for no match or other failure. .SH ERRORS If .C regcomp() or .C regexec() detects one of the error conditions listed below, it returns the corresponding non-zero error code. The error codes are defined in the header .RC < regex.h >. .RS .TP 20 .C REG_BADBR The contents within the pair .C \e{ (backslash left brace) and .C \e} (backslash right brace) are unusable: not a number, number too large, more than two numbers, or first number larger than second. .TP .C REG_BADPAT An invalid regular expression. .TP .C REG_BADRPT The .CR ? (question mark), .CR * (asterisk), or .CR + (plus sign) symbols are not preceded by a valid regular expression. .TP .C REG_EBRACE The use of a pair of .C \e{ (backslash left brace) and .C \e} (backslash right brace) or .C {} (braces) is unbalanced. .TP .C REG_EBRACK The use of .C [] (brackets) is unbalanced. .TP .C REG_EBOL Using the .C ^ (caret) anchor and not beginning of line. .TP .C REG_ECHAR There is an invalid multibyte character. .TP .C REG_ECOLLATE There is an unusable collating element referenced. .TP .C REG_ECTYPE There is an unusable character class type referenced. .TP .C REG_EEOL Using the $ (dollar) anchor and not end of line. .TP .C REG_EESCAPE There is a trailing .C \e in the pattern. .TP .C REG_EPAREN The use of a pair of .C \e( (backslash left parenthesis) and .C \e) (backslash right parenthesis) or .C () is unbalanced. .TP .C REG_ERANGE There is an unusable endpoint in the range expression. .TP .C REG_ESPACE There is insufficient memory space. .TP .C REG_ESUBREG The number in .CI \e digit is invalid or in error. .TP .C REG_NOMATCH The .C regexec() function failed to match. .RE .SH EXAMPLES .nf .IP .ift .ft 4 .ps +1 /* match string against the extended regular expression in pattern, treating errors as no match. Return 1 for match, 0 for no match. Print an error message if an error occurs. */ .ift .sp .5v .ifn .sp int match(string, pattern) char *string; char *pattern; { int i; regex_t re; char buf[256]; .ift .sp .5v .ifn .sp i=regcomp(&re, pattern, REG_EXTENDED|REG_NOSUB); if (i != 0) { (void)regerror(i,&re,buf,sizeof buf); printf("%s\en",buf); return(0); /* report error */ } i = regexec(&re, string, (size_t) 0, NULL, 0); regfree(&re); if (i != 0) { (void)regerror(i,&re,buf,sizeof buf); printf("%s\en",buf); return(0); /* report error */ } return(1); } .ift .ft .ps .fi .PP The following demonstrates how the .C REG_NOTBOL flag could be used with .C regexec() to find all substrings in a line that match a pattern supplied by a user. .nf .IP .ift .ft 4 .ps +1 (void) regcomp(&re, pattern, 0); /* look for first match at start of line */ error = regexec(&re, &buffer[0], 1, &pm, 0); while (error == 0) { /* while matches found */ /* find next match on line */ error = regexec(&re, &buffer[pm.rm_eo], 1, &pm, REG_NOTBOL); } .ift .ft .ps .fi .SH AUTHOR .CR regcomp() , .CR regerror() , .CR regexec() , and .C regfree() were developed by OSF and HP. .SH SEE ALSO regexp(5). .SH STANDARDS CONFORMANCE .CR regcomp() ": XPG4, POSIX.2" .PP .CR regerror() ": XPG4, POSIX.2" .PP .CR regexec() ": XPG4, POSIX.2" .PP .CR regfree() ": XPG4, POSIX.2" .\" .\" .\" toc@\f3regcomp(3C)\f1:\0\0\f4regcomp()\f1, \f4regerror()\f1, \f4regexec()\f1, \f4regfree()\f1@@@regular expression matching routines .\" toc@\f4regerror()\f1:\0\0regular expression matching routines@@@\f1see \f3regcomp(3C)\f1 .\" toc@\f4regexec()\f1:\0\0regular expression matching routines@@@\f1see \f3regcomp(3C)\f1 .\" toc@\f4regfree()\f1:\0\0regular expression matching routines@@@\f1see \f3regcomp(3C)\f1 .\" .\" index@\f4regcomp()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f4regexec()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f4regfree()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f4regerror()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f1regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f1expression matching routines, regular@@@\f3regcomp(3C)\f1 .\" index@\f1matching routines, regular expression@@@\f3regcomp(3C)\f1 .\" index@\f1compiling routines, regular expression@@@\f3regcomp(3C)\f1 .\" .\" links@regcomp.3c regexec.3c .\" links@regcomp.3c regfree.3c .\" links@regcomp.3c regerror.3c .\" .\" fileset_database@regcomp.3c PROGRAMING-MAN .\" $Header: regexp.3x,v 72.5 94/11/15 09:56:02 ssa Exp $ .TA r .TH regexp 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compile(\|), step(\|), advance(\|) \- regular expression compile and match routines .SH SYNOPSIS .C #define INIT .I "declarations" .br .C #define GETC() .I "getc statements" .br .C #define PEEKC() .I "peekc statements" .br .C #define UNGETC(c) .I "ungetc statements" .br .C #define RETURN(pointer) .I "return statements" .br .C #define ERROR(val) .I "error statements" .PP .C "#include " .PP .C "char *compile(" .nf .PD 0 .IP .C "const char *instring," .C "char *expbuf," .C "const char *endbuf," .C "int eof" .PP .C ");" .PD .fi .PP .C "int step(const char *string, const char *expbuf);" .PP .C "int advance(const char *string, const char *expbuf);" .PP .C "extern char *loc1, *loc2, *locs;" .PP .C "extern int circf, sed, nbra;" .SS Remarks Features documented in this manual entry are obsolescent and may be removed in a future .SM HP-UX release. Use of .IR regcomp (3C) functions instead is recommended. .SH DESCRIPTION These functions are general-purpose regular expression matching routines to be used in programs that perform Basic Regular Expression (see .IR regexp (5)) matching. These functions are defined in .RC < regexp.h >. .PP The functions .C step() and .C advance() do pattern matching given a character string and a compiled regular expression as input. .C compile() takes a Basic Regular Expression as input and produces a compiled expression that can be used with .C step() and .CR advance() . .PP The interface to this file is unpleasantly complex. Programs that include this file must have the following five macros declared before the .C #include statement. These macros are used by the .C compile() routine. .TP 15 .C GETC() Return the value of the next byte in the regular expression pattern. Successive calls to .C GETC() should return successive bytes of the regular expression. .TP .C PEEKC() Return the next byte in the regular expression. Successive calls to .C PEEKC() should return the same byte (which should also be the next byte returned by .CR GETC() . .TP .CI UNGETC( c ) Cause the argument .I c to be returned by the next call to .C GETC() (and .CR PEEKC() ). No more than one byte of pushback is ever needed, and this byte is guaranteed to be the last byte read by .CR GETC() . The value of the macro .CI UNGETC( c ) is always ignored. .TP .CI RETURN( pointer ) This macro is used on normal exit of the .C compile() routine. The value of the argument .I pointer is a pointer to the character after the last character of the compiled regular expression. This is useful to programs that must manage memory allocation. .TP .CI ERROR( val ) This is the abnormal return from the .C compile() routine. The argument .I val is an error number (see table below for meanings). This call should never return. .RS .RS .PD 0 .TP 8 .B Error .B Meaning .TP 11 Range endpoint too large. .TP 16 Bad number. .TP 25 ``\f3\e\f2digit\f1'' out of range. .TP 36 Illegal or missing delimiter. .TP 41 No remembered search string. .TP 42 .C \e( \e) imbalance. .TP 43 Too many .CR \e( . .TP 44 More than 2 numbers given in .CR \e{\0\e} . .TP 45 .C } expected after .CR \e . .TP 46 First number exceeds second in .CR \e{\0\e} . .TP 49 .C [ ] imbalance. .TP 50 Regular expression overflow. .RE .RE .PD .PP The syntax of the .C compile() routine is as follows: .IP .CI compile( instring , .CI expbuf , .CI endbuf , .CI eof ) .PP The first parameter .I instring is never used explicitly by the .C compile() routine, but is useful for programs that pass down different pointers to input characters. It is sometimes used in the .C INIT declaration (see below). Programs that call functions to input characters or have characters in an external array can pass down a value of .C ((char *) 0) for this parameter. .PP The next parameter .I expbuf is a character pointer. It points to the location where the compiled regular expression will be placed. .PP The parameter .I endbuf is one more than the highest address where the compiled regular expression can be placed. If the compiled expression cannot fit in .RI ( endbuf \|\(mi\| expbuf ) bytes, a call to .C ERROR(50) is made. .PP The parameter .I eof is the character which marks the end of the regular expression. For example, in .IR ed (1), this character is usually a .CR / . .PP Each program that includes this file must have a .C #define statement for .CR INIT . This definition is placed right after the declaration for the function .C compile() and the opening curly brace .CR { . It is used for dependent declarations and initializations. Most often it is used to set a register variable to point to the beginning of the regular expression so that this register variable can be used in the declarations for .CR GETC() , .CR PEEKC() , and .CR UNGETC() . Otherwise it can be used to declare external variables that might be used by .CR GETC() , .CR PEEKC() , and .CR UNGETC() . See the example below of the declarations taken from .IR grep (1). .PP .C step() also performs actual regular expression matching in this file. The call to .I step is as follows: .IP .CI step( string , .CI expbuf ) .PP The first parameter to .C step() is a pointer to a string of characters to be checked for a match. This string should be null-terminated. .PP The second parameter .I expbuf is the compiled regular expression that was obtained by a call to .CR compile() . .PP .C step() returns non-zero if the given string matches the regular expression, and zero if the expressions do not match. If there is a match, two external character pointers are set as a side effect to the call to .CR step() . The variable set in .C step() is .CR loc1 . This is a pointer to the first character that matched the regular expression. The variable .CR loc2 , which is set by the function .CR advance() , points to the character after the last character that matches the regular expression. Thus, if the regular expression matches the entire line, .C loc1 points to the first character of .I string and .C loc2 points to the null at the end of .IR string . .PP .C step() uses the external variable .CR circf() , which is set by .C compile() if the regular expression begins with .CR ^ . If this is set, .C step() tries to match the regular expression to the beginning of the string only. If more than one regular expression is to be compiled before the first is executed, the value of .I circf should be saved for each compiled expression and .I circf should be set to that saved value before each call to .CR step() . .PP .C advance() is called from .C step() with the same arguments as .CR step() . The purpose of .C step() is to step through the .I string argument and call .C advance() until .C advance() returns non-zero, which indicates a match, or until the end of .I string is reached. To constrain .I string to beginning-of-line in all cases, .C step() need not be called; simply call .CR advance() . .PP When .C advance() encounters a .C * or .C \e{\|\e} sequence in the regular expression, it advances its pointer to the string to be matched as far as possible and recursively calls itself, trying to match the rest of the string to the rest of the regular expression. As long as there is no match, .I advance backs up along the string until it finds a match or reaches the point in the string that initially matched the .C * or .CR \e{\|\e} . It is sometimes desirable to stop this backing up before the initial point in the string is reached. If the external character pointer .C locs is equal to the point in the string at sometime during the backing up process, .C advance() breaks out of the loop that backs up and returns zero. This is used by .IR ed (1) and .IR sed (1) for substitutions done globally (not just the first occurrence, but the whole line) so, for example, expressions such as .C s/y*//g do not loop forever. .PP The additional external variables .C sed and .C nbra are used for special purposes. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions. .PP The .C LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, and the characters matched by character class expressions in regular expressions. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following is an example of how the regular expression macros and calls look from .IR grep (1): .nf .IP .C "#define INIT register char *sp = instring;" .C "#define GETC() (*sp++)" .C "#define PEEKC() (*sp)" .C "#define UNGETC(c) (--sp)" .C "#define RETURN(c) return;" .C "#define ERROR(c) regerr()" .IP .C "#include " \h'.5i'.\|.\|. .C "(void) compile(*argv, expbuf, &expbuf[ESIZE], '\e0');" \h'.5i'.\|.\|. .C "if (step(linebuf, expbuf))" .C " succeed();" .fi .SH AUTHOR .CR regexp() was developed by OSF and HP. .SH SEE ALSO grep(1), regcomp(3C), setlocale(3C), regexp(5). .SH STANDARDS CONFORMANCE .CR advance() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR compile() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc1 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc2 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR locs ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR step() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4compile()\f1 \- regular expression compile routine@@@\f3regexp(3X)\f1 .\" index@\f4step()\f1 \- regular expression string comparison routine@@@\f3regexp(3X)\f1 .\" index@\f4advance()\f1 \- regular expression substring comparison routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1expression, regular, compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1compile and match routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1comparison routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1match routines for regular expressions@@@\f3regexp(3X)\f1 .\" .\" toc@\f3regexp(3X)\f1:\0\0\f4compile()\f1, \f4step()\f1, \f4advance()\f1@@@regular expression compile and match routines .\" toc@\f4compile()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4step()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4advance()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" .\" links@regexp.3x compile.3x .\" links@regexp.3x step.3x .\" links@regexp.3x advance.3x .\" links@regexp.3x INIT.3x .\" links@regexp.3x GETC.3x .\" links@regexp.3x PEEKC.3x .\" links@regexp.3x UNGETC.3x .\" links@regexp.3x RETURN.3x .\" links@regexp.3x ERROR.3x .\" .\" fileset_database@regexp.3x PROGRAMING-MAN .\" $Header: regcomp.3c,v 74.1 95/05/10 21:10:56 ssa Exp $ .TA r .TH regcomp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME regcomp(\|), regerror(\|), regexec(\|), regfree(\|) \- regular expression matching routines .SH SYNOPSIS .C "#include " .PP .C "int regcomp(regex_t *preg, const char *pattern, int cflags);" .PP .C "int regexec(" .nf .PD 0 .IP .C "const regex_t *preg," .C "const char *string," .C "size_t nmatch," .C "regmatch_t pmatch[\|]," .C "int eflags" .PP .C ");" .PD .fi .PP .C "void regfree(regex_t *preg);" .PP .C "size_t regerror( .nf .PD 0 .IP .C "int errcode," .C "const regex_t *preg," .C "char *errbuf," .C "size_t errbuf_size" .PP .C ");" .PD .fi .SH DESCRIPTION These functions interpret regular expressions as described in .IR regexp (5). They support both .I basic and .I extended regular expressions. .PP The structures .C regex_t and .C regmatch_t are defined in the header .RC < regex.h >. .PP The .C regex_t structure contains at least the following member (use of other members results in non-portable code): .RS .TP 25 .C size_t re_nsub Number of parenthesized subexpressions. .RE .PP The .C regmatch_t structure contains at least the following members: .RS .TP 25 .B regoff_t rm_so Byte offset from start of string to start of substring. .TP .B regoff_t rm_eo Byte offset from start of string to the first character after the end of the substring. .RE .PP .CR regcomp() compiles the regular expression specified by the .I pattern argument and places the results in the structure pointed to by .IR preg . The .I cflags argument is the bit-wise logical .SM OR of zero or more of the following flags (defined in .RC < regex.h >): .RS .TP 18 .C REG_EXTENDED Use extended regular expressions. .TP .C REG_NEWLINE IF .C REG_NEWLINE is not set in .IR cflags , a newline character in .I pattern or .I string is treated as an ordinary character. If .C REG_NEWLINE is set, newlines are treated as ordinary characters except as follows: .RS .RS .TP 4 1. A newline in .I string is not matched by a period outside of a bracket expression or by any form of a nonmatching list. .TP 2. A circumflex .RC ( ^ ) in .IR pattern , when used to specify expression anchoring, matches the zero-length string immediately after a newline in .IR string , regardless of the setting of .CR REG_NOTBOL . .TP 3. A dollar-sign .RC ( $ ) in .IR pattern , when used to specify expression anchoring, matches the zero-length string immediately before a newline in .IR string , regardless of the setting of .CR REG_NOTEOL . .RE .RE .TP .C REG_ICASE Ignore case in match. If a character in .I pattern is defined in the current .C LC_CTYPE locale as having one or more opposite-case counterpoints, both the character and any counterpoints match the pattern character. This applies to all portions of the pattern, including a string of characters specified to be matched via a back-reference expression .RC ( \e\f2n\fP ). .IP .IR "Within bracket expressions" : Collation ranges, character classes, and equivalence classes are effectively expanded into equivalent lists of collation elements and characters. Opposite-case counterpoints are then generated for each collation element or character to form the complete matching list or non-matching list for the bracket expression. Opposite-case counterpoints for a multi-character collating element include all possible combinations of opposite-case counterpoints for each individual character comprising the collating element. These are then combined to form new valid multi-character collating elements. For example, the opposite-case counterpoints for .C [.ch.] could be .CR [.Ch.] , .CR [.cH.] , and .CR [.CH.] . .RE .PP The default regular expression type for .I pattern is Basic Regular Expression. The application can specify Extended Regular Expressions by using the .C REG_EXTENDED .I cflags value. .PP If the function .C regcomp() succeeds, it returns zero; otherwise it returns a non-zero value indicating the error. .PP If .C regcomp() succeeds, and if the .C REG_NOSUB flag was not set in .IR cflags , .C regcomp() sets .C re_nsub to the number of parenthesized subexpressions (delimited by .C \e( and .C \e) in basic regular expressions or .C ( and .C ) in extended regular expressions) found in .IR pattern . .PP .C regexec() matches the null-terminated string specified by .I string against the compiled regular expression .I preg initialized by a previous call to .CR regcomp() . If it finds a match, .C regexec() returns zero; otherwise it returns non-zero indicating either no match or an error. The .I eflags argument is the bit-wise logical .SM OR of the following flags: .RS .TP 18 .C REG_NOTBOL The first character of the string pointed to by .I string is not the beginning of the line. Therefore, the circumflex character .RC ( ^ ), when taken as a special character, never matches. .TP .C REG_NOTEOL The last character of the string pointed to by .I string is not the end of the line. Therefore, the dollar sign .RC ( $ ), when taken as a special character, never matches. .RE .PP If .I nmatch is not zero, and .C REG_NOSUB was not set in the .I cflags argument to .CR regcomp() , then .C regexec() fills in the .I pmatch array with byte offsets to the substrings of .I string that correspond to the parenthesized subexpressions of .IR pattern : .IR pmatch [ i ] .rm_so is the byte offset of the beginning and .IR pmatch [ i ] .rm_eo is the byte offset one byte past the end of the substring .IR i . (Subexpression .I i begins at the .IR i th matched left parenthesis, counting from 1). Offsets in .IR pmatch [0] identify the substring that corresponds to the entire regular expression. Unused elements of .I pmatch are set to \(mi1. If there are more than .I nmatch subexpressions in .I pattern .RI ( pattern itself counts as a subexpression), .C regexec() still does the match, but only records the first .I nmatch substrings. .PP When matching a regular expression, any given parenthesized subexpression of .I pattern might participate in the match of several different substrings of .IR string , or it might not match any substring, even though the pattern as a whole did match. The following explains which substrings are reported in .I pmatch when matching regular expressions: .RS .TP 5 1. If subexpression .I i in a regular expression is not contained within another subexpression, and it participated in the match several times, the byte offsets in .IR pmatch [ i ] delimit the last such match. .TP 2. If subexpression .I i is not contained within another subexpression, and it did not participate in an otherwise successful match (because either .CR * , .CR ? , or .C | was used), then the byte offsets in .IR pmatch [ i ] are \(mi1. .TP 3. If subexpression .I i is contained in subexpression .IR j , and a match of subexpression .I j is reported in .IR pmatch [ j ], the match or no-match reported in .IR pmatch [ i ] is the last one that occurred within the substring in .IR pmatch [ j ]. .TP 4. If subexpression .I i is contained in subexpression .IR j , and the offsets in .IR pmatch [ j ] are \(mi1, the offsets in .IR pmatch [ i ] will also be \(mi1. .TP 5. If subexpression .I i matched a zero-length string, both offsets in .IR pmatch [ i ] refer to the character immediately following the zero-length substring. .RE .PP If .C REG_NOSUB was set in .I cflags in the call to .CR regcomp() , and .I nmatch is not zero in the call to .CR regexec() , the content of the .I pmatch array is unspecified. .PP .C regfree() frees any memory allocated by .C regcomp() associated with .IR preg . .PP If the .I preg argument to .C regexec() or .C regfree() is not a compiled regular expression returned by .CR regcomp() , the result is undefined. A .I preg can no longer be treated as a compiled regular expression after it is given to .CR regfree() . .PP .C regerror() provides a mapping from error codes returned by .C regcomp() and .C regexec() to printable strings. .C regerror() generates a string corresponding to the value of the .I errcode parameter, which was the last non-zero value returned by .C regcomp() or .C regexec() with the given value of .IR preg . The .I errcode parameter can take on any of the error values defined in .RC < regex.h >. If .I errbuf_size is not zero, .C regerror() copies an appropriate error message into the buffer specified by .IR errbuf . If the error message (including the terminating null) cannot fit in the buffer, it is truncated to .I errbuf_size \(mi 1 bytes and null terminated. .PP If .I errbuf_size is zero, the .I errbuf parameter is ignored, but the return value is as defined below. .PP .IR regerror (\|) returns the size of the buffer (including terminating null) that is required to hold the entire error message. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions. .PP The .C LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, the characters matched by character-class expressions in regular expressions, and the opposite-case counterpart for each character. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .C regcomp() returns zero for success and non-zero for an invalid expression or other failure. .C regexec() returns zero if it finds a match and non-zero for no match or other failure. .SH ERRORS If .C regcomp() or .C regexec() detects one of the error conditions listed below, it returns the corresponding non-zero error code. The error codes are defined in the header .RC < regex.h >. .RS .TP 20 .C REG_BADBR The contents within the pair .C \e{ (backslash left brace) and .C \e} (backslash right brace) are unusable: not a number, number too large, more than two numbers, or first number larger than second. .TP .C REG_BADPAT An invalid regular expression. .TP .C REG_BADRPT The .CR ? (question mark), .CR * (asterisk), or .CR + (plus sign) symbols are not preceded by a valid regular expression. .TP .C REG_EBRACE The use of a pair of .C \e{ (backslash left brace) and .C \e} (backslash right brace) or .C {} (braces) is unbalanced. .TP .C REG_EBRACK The use of .C [] (brackets) is unbalanced. .TP .C REG_EBOL Using the .C ^ (caret) anchor and not beginning of line. .TP .C REG_ECHAR There is an invalid multibyte character. .TP .C REG_ECOLLATE There is an unusable collating element referenced. .TP .C REG_ECTYPE There is an unusable character class type referenced. .TP .C REG_EEOL Using the $ (dollar) anchor and not end of line. .TP .C REG_EESCAPE There is a trailing .C \e in the pattern. .TP .C REG_EPAREN The use of a pair of .C \e( (backslash left parenthesis) and .C \e) (backslash right parenthesis) or .C () is unbalanced. .TP .C REG_ERANGE There is an unusable endpoint in the range expression. .TP .C REG_ESPACE There is insufficient memory space. .TP .C REG_ESUBREG The number in .CI \e digit is invalid or in error. .TP .C REG_NOMATCH The .C regexec() function failed to match. .RE .SH EXAMPLES .nf .IP .ift .ft 4 .ps +1 /* match string against the extended regular expression in pattern, treating errors as no match. Return 1 for match, 0 for no match. Print an error message if an error occurs. */ .ift .sp .5v .ifn .sp int match(string, pattern) char *string; char *pattern; { int i; regex_t re; char buf[256]; .ift .sp .5v .ifn .sp i=regcomp(&re, pattern, REG_EXTENDED|REG_NOSUB); if (i != 0) { (void)regerror(i,&re,buf,sizeof buf); printf("%s\en",buf); return(0); /* report error */ } i = regexec(&re, string, (size_t) 0, NULL, 0); regfree(&re); if (i != 0) { (void)regerror(i,&re,buf,sizeof buf); printf("%s\en",buf); return(0); /* report error */ } return(1); } .ift .ft .ps .fi .PP The following demonstrates how the .C REG_NOTBOL flag could be used with .C regexec() to find all substrings in a line that match a pattern supplied by a user. .nf .IP .ift .ft 4 .ps +1 (void) regcomp(&re, pattern, 0); /* look for first match at start of line */ error = regexec(&re, &buffer[0], 1, &pm, 0); while (error == 0) { /* while matches found */ /* find next match on line */ error = regexec(&re, &buffer[pm.rm_eo], 1, &pm, REG_NOTBOL); } .ift .ft .ps .fi .SH AUTHOR .CR regcomp() , .CR regerror() , .CR regexec() , and .C regfree() were developed by OSF and HP. .SH SEE ALSO regexp(5). .SH STANDARDS CONFORMANCE .CR regcomp() ": XPG4, POSIX.2" .PP .CR regerror() ": XPG4, POSIX.2" .PP .CR regexec() ": XPG4, POSIX.2" .PP .CR regfree() ": XPG4, POSIX.2" .\" .\" .\" toc@\f3regcomp(3C)\f1:\0\0\f4regcomp()\f1, \f4regerror()\f1, \f4regexec()\f1, \f4regfree()\f1@@@regular expression matching routines .\" toc@\f4regerror()\f1:\0\0regular expression matching routines@@@\f1see \f3regcomp(3C)\f1 .\" toc@\f4regexec()\f1:\0\0regular expression matching routines@@@\f1see \f3regcomp(3C)\f1 .\" toc@\f4regfree()\f1:\0\0regular expression matching routines@@@\f1see \f3regcomp(3C)\f1 .\" .\" index@\f4regcomp()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f4regexec()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f4regfree()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f4regerror()\f1 \- regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f1regular expression matching routines@@@\f3regcomp(3C)\f1 .\" index@\f1expression matching routines, regular@@@\f3regcomp(3C)\f1 .\" index@\f1matching routines, regular expression@@@\f3regcomp(3C)\f1 .\" index@\f1compiling routines, regular expression@@@\f3regcomp(3C)\f1 .\" .\" links@regcomp.3c regexec.3c .\" links@regcomp.3c regfree.3c .\" links@regcomp.3c regerror.3c .\" .\" fileset_database@regcomp.3c PROGRAMING-MAN .\" $Header: rpc_svc_calls.3c,v 74.1 95/05/10 21:56:31 ssa Exp $ .TA r .TH rpc_svc_calls 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME registerrpc, svc_register, svc_unregister, xprt_register, xprt_unregister \- library routines for registering servers .SH SYNOPSIS .C "#include " .PP .nf .C /* registerrpc */ .C "int" .C "registerrpc(prognum, versnum, procnum, procname, inproc, outproc)" .C "u_long prognum, versnum, procnum;" .C "char *(*procname) ();" .C "xdrproc_t inproc, outproc;" .fi .PP .nf .C "/* svc_register */" .C "bool_t" .C "svc_register(xprt, prognum, versnum, dispatch, protocol)" .C "SVCXPRT *xprt;" .C "u_long prognum, versnum;" .C "void (*dispatch) ();" .C "u_long protocol;" .fi .PP .nf .C "/* svc_unregister */ .C "void" .C "svc_unregister(prognum, versnum)" .C "u_long prognum, versnum;" .fi .PP .nf .C /* xprt_register */ .C "void" .C "xprt_register(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* xprt_unregister */" .C "void" .C "xprt_unregister(xprt)" .C "SVCXPRT *xprt;" .fi .SH DESCRIPTION These routines are a part of the RPC library, which allows the RPC servers to register themselves with .IR portmap (1M), and it associates the given program and version number with the dispatch function. .SS Routines .PP To use these routines, the C programs must include the header file .CR . .PP The .C SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP 20 .C registerrpc Register procedure .I procname with the RPC service package. If a request arrives for program .IR prognum , version .IR versnum , and procedure .IR procnum , .I procname is called with a pointer to its parameter; .I progname must be a procedure that returns a pointer to its static result; .I inproc is used to decode the parameters while .I outproc is used to encode the results. This routine returns 0 if the registration succeeded, \-1 otherwise. .IP .BR Warning : Remote procedures registered in this form are accessed using the UDP/IP transport; see .C svcudp_create() on .IR rpc_svc_create (3C) for restrictions. This routine should not be used more than once for the same program and version number. .TP .C svc_register Associates .I prognum and .I versnum with the service dispatch procedure, .IR dispatch . If .I protocol is zero, the service is not registered with the .C portmap service. If .I protocol is non-zero, a mapping of the triple .RI [ "prognum, versnum, protocol"\f1] to .C xprt->xp_port is established with the local .C portmap service (generally .I protocol is zero, .C IPPROTO_UDP or .CR IPPROTO_TCP ). The procedure .I dispatch has the following form: .RS 2i .PP .nf .C "dispatch(request, xprt)" .C "struct svc_req *request;" .C "SVCXPRT *xprt;" .ft R .fi .RE .IP The .B svc_register() routine returns .C TRUE if it succeeds, and .C FALSE otherwise. .TP .C svc_unregister Remove all mapping of the pair .RI [ prognum , versnum ] to dispatch routines, and of the triple .RI [ prognum , versnum , *\f1] to port number. .TP .C xprt_register After RPC service transport handles are created, they should register themselves with the RPC service package. This routine modifies the global variable .IR svc_fds . Service implementors usually do not need this routine. .TP .C xprt_unregister Before an RPC service transport handle is destroyed, it should unregister itself with the RPC service package. This routine modifies the global variable .IR svc_fds . Service implementors usually do not need this routine directly. .SH AUTHOR .C rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M), portmap(3C), rpc(3C), rpc_svc_err(3C), rpc_svc_create(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3rpc_svc_calls(3C)\f1:\0\0\f4registerrpc()\f1,\f4svc_register()\f1, \f4svc_unregister()\f1, \f4xprt_register()\f1,\n \f4xprt_unregister()\f1@@@library routines for registering servers .\" toc@\f4registerrpc()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4svc_register()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4svc_unregister()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4xprt_register()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4xprt_unregister()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" index@\f4rpc_svc_calls(3C)\f1library routines for registering servers@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4registerrpc()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4svc_register()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4svc_unregister()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4xprt_register()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4xprt_unregister()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" links@rpc_svc_calls.3c registerrpc.3c .\" links@rpc_svc_calls.3c svc_register.3c .\" links@rpc_svc_calls.3c svc_unregister.3c .\" links@rpc_svc_calls.3c xprt_register.3c .\" links@rpc_svc_calls.3c xprt_unregister.3c .\" $Header: reltimer.3c,v 72.5 94/11/15 09:56:04 ssa Exp $ .TA r .TH reltimer 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME reltimer \- relatively arm a per-process timer .SH SYNOPSIS .C "#include " .PP .C "int reltimer(" .nf .PD 0 .IP .C "timer_t timerid," .C "struct itimerspec *value," .C "struct itimerspec *ovalue," .PP .C ");" .PD .SH DESCRIPTION The .CR reltimer() function sets the .CR it_value of the specified timer to an offset from the current clock setting. .PP If .CR reltimer() specifies a .I value argument with the .CR it_value member equal to zero, the timer is disabled. .CR reltimer() updates the .I it_interval value of the timer to the value specified. Time values smaller than the resolution of the specified timer are rounded up to its resolution; timer values larger than the maximum value of the specified timer are rounded down to the maximum value (see .IR mktimer (3C)). .PP .CR reltimer() returns in the .IR ovalue parameter a value representing the previous amount of time before the timer would have expired or zero if the timer was disabled, together with the previous interval timer period. The members of .IR ovalue are subject to the resolution of the timer, and are the same values that would be returned by a .CR gettimer() call. .PP The behavior of this function is undefined if .I value is NULL. .SH RETURN VALUE Upon successful completion, .CR reltimer() returns zero; otherwise, it returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS .CR reltimer() fails if any of the following conditions are encountered: .RS .TP 12 [EINVAL] .CR timerid does not correspond to an ID returned by .CR mktimer() or the value structure specified a nanosecond value less than zero or greater than or equal to 1000 million. .TP [EIO] An error occurred while accessing the clock device. .RE .SH FILES .C /usr/include/sys/timers.h .SH SEE ALSO timer_settime(2), gettimer(3C), mktimer(3C). .SH STANDARDS CONFORMANCE .CR reltimer() ": AES" .\" .\" toc@\f3reltimer(3C)\f1:\0\0\f4reltimer()\f1@@@relatively arm a per-process timer\f1 .\" .\" index@\f4reltimer()\f1 \- relatively arm a per-process timer@@@\f3reltimer(3C)\f1 .\" index@\f1relatively arm a per-process timer@@@\f3reltimer(3C)\f1 .\" index@\f1arm a per-process timer, relatively@@@\f3reltimer(3C)\f1 .\" index@\f1per-process timer, relatively arm a@@@\f3reltimer(3C)\f1 .\" index@\f1timer, relatively arm a per-process@@@\f3reltimer(3C)\f1 .\" $Header: remainder.3m,v 78.1 96/02/13 13:43:42 ssa Exp $ .TA r .TH remainder 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME remainder(\|), drem(\|) \- remainder function .SH SYNOPSIS .C "#include " .PP .C "double remainder(double x, double y);" .PP .C "double drem(double x, double y);" .SH DESCRIPTION The .CR remainder() function returns the floating-point remainder .I r \(eq .I x \(mi .I ny when .I y is nonzero. The value .I n is the integral value nearest the exact value .IR x / y ; when \(bv \f2n\f1 \(mi \f2x\f1/\f2y\f1 \(bv \(eq \(12, the value .I n is chosen to be even. .\" .br .\" when .\" .RI | n " - " .\" .IR x / y | .\" = \(12, .\" the value .\" .I n .\" is chosen to be even. .PP The .CR remainder() is independent of the rounding mode. .PP The .CR drem() function is identical to the .CR remainder() function. It is provided for backward compatibility. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH "RETURN VALUE" If .I y .ift is \(+-INFINITY and .ifn is +\-INFINITY and .I x .ift is not \(+-INFINITY, .ifn is not +\-INFINITY, .CR remainder() returns .IR x . .PP If .I x .ift is \(+-zero and .ifn is +\-zero and .I y is nonzero, .CR remainder() returns .IR x . .PP If .I x or .I y is NaN, .CR remainder() returns NaN. .PP If .I y is zero, .CR remainder() returns NaN and sets .CR errno to [EDOM]. .PP If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR remainder() returns NaN and sets .CR errno to [EDOM]. .SH ERRORS If .CR remainder() fails, .CR errno is set to one of the following values. .RS .TP 20 [EDOM] .I y is zero. .TP 20 [EDOM] .I x .ift is \(+-INFINITY. .ifn is +\-INFINITY. .RE .SH "SEE ALSO" fmod(3M), fabs(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR remainder() ": SVID3, XPG4.2" .\" index@\f4remainder()\f1, \f4drem()\f1 \- remainder function@@@\f3remainder(3M)\f1 .\" index@\f4drem()\f1 \- remainder function@@@\f3remainder(3M)\f1 .\" index@\f1math: remainder function@@@\f3remainder(3M)\f1 .\" index@\f1remainder function@@@\f3remainder(3M)\f1 .\" .\" toc@\f3remainder(3M)\f1:\0\0\f4remainder()\f1, \f4drem\f1@@@remainder function .\" toc@\f4drem()\f1:\0\0remainder function@@@see \f3remainder(3M)\f1 .\" .\" links@remainder.3m drem.3m .\" .\" fileset_database@remainder.3m PROGRAMING-MAN .\" $Header: exportent.3n,v 74.1 95/01/25 16:26:52 ssa Exp $ .TA e .TH exportent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME exportent(\|), getexportent(\|), setexportent(\|), addexportent(\|), remexportent(\|), endexportent(\|), getexportopt(\|) \- access exported file system information .SH SYNOPSIS .nf .C #include .C #include .PP .C "FILE *setexportent();" .PP .C "struct exportent *getexportent(FILE *fildep);" .PP .C "int addexportent(FILE *filep, char *dirname, char *options);" .PP .C "int remexportent(FILE *filep, char *dirname);" .PP .C "char *getexportopt(struct exportent *xent, char *opt);" .PP .C "void endexportent(FILE *filep);" .fi .SH DESCRIPTION These routines access the exported filesystem information in .CR /etc/xtab . .ift .TP 22 .ifn .TP 10 .C setexportent() Open the export information file and return a file pointer to use with .CR getexportent() , .CR addexportent() , .CR remexportent() , and .CR endexportent() . Returns .SM NULL if the file is locked or if an error is encountered in opening the file. .TP .C getexportent() Read the next line from .I filep and return a pointer to an object with the following structure containing the broken-out fields of a line in file .CR /etc/xtab . The fields have meanings described in .IR exports (4). .nf .IP .ift .ft 4 .ifn .ft 3 #define ACCESS_OPT "access" /* machines that can mount fs */ #define ROOT_OPT "root" /* machines with root access to fs */ #define RO_OPT "ro" /* export read-only */ #define ANON_OPT "anon" /* uid for anonymous requests */ #define ASYNC_OPT "async" /* all mounts will be aynchronous */ .ift .sp .5v .ifn .sp 1v struct exportent { char *xent_dirname; /* directory (or file) to export */ char *xent_options; /* options, as above */ }; .ft .fi .IP .C getexportent() returns .SM NULL if it encounters end of file. .TP .C addexportent() Add the .I exportent to the end of the open file .IR filep . It returns 0 if successful and \(mi1 on failure. .TP .C remexportent() Remove the indicated entry from the list. Returns 0 on success and \(mi1 on failure. .TP .C getexportopt() Scans the .C xent_options field of the .C exportent structure for a substring that matches .IR opt . Returns the string value of .IR opt , or .SM NULL if the option is not found. .TP .C endexportent() Close the file. .SH RETURN VALUE .CR setexportent() , .CR getexportent() , and .C getexportopt() return a .SM NULL pointer on .SM EOF or error. .PP .C addexportent() and .C remexportent() return \(mi1 if they fail. .SH WARNINGS The returned .C exportent structure points to static information that is overwritten in each call. .SH AUTHOR .CR exportent , .CR getexportent() , .CR setexportent() , .CR addexportent() , .CR remexportent() , .CR endexportent() , and .C getexportopt() were developed by Sun Microsystems, Inc. .SH FILES .C /etc/exports .C /etc/xtab .SH SEE ALSO exportfs(1M), exports(4). .\" .\" toc@\f3exportent(3N)\f1:\0\0\f4exportent(\|)\f1, \f4getexportent(\|)\f1, \f4setexportent(\|)\f1, \f4addexportent(\|)\f1, \f4remexportent(\|)\f1,\n\f4endexportent(\|)\f1, \f4getexportopt(\|)\f1@@@access exported file system information .\" toc@\f4getexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4setexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4addexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4remexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4endexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4getexportopt(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" .\" index@\f4exportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4getexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4setexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4addexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4remexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4endexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4getexportopt(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@access exported file system information@@@\f3exportent(3N)\f1 .\" index@exported file system information, access@@@\f3exportent(3N)\f1 .\" index@file system information, access exported@@@\f3exportent(3N)\f1 .\" index@information, access exported file system@@@\f3exportent(3N)\f1 .\" .\" links@exportent.3n getexporten.3n .\" links@exportent.3n setexporten.3n .\" links@exportent.3n addexporten.3n .\" links@exportent.3n remexporten.3n .\" links@exportent.3n endexporten.3n .\" links@exportent.3n getexportop.3n .\" .\" fileset_database@exportent.3n PROGRAMING-MAN .\" $Header: remove.3c,v 72.4 94/11/15 09:56:05 ssa Exp $ .TA r .TH remove 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME remove(\|) \- remove a file .SH SYNOPSIS .C "#include " .PP .C "int remove(const char *path);" .SH DESCRIPTION .C remove() removes the file named by .IR path . If .I path does not name a directory, .CI remove( path ) is equivalent to .CI unlink( path ) . If .I path names a directory, .CI remove( path ) is equivalent to .CI rmdir( path ) . .SH SEE ALSO rmdir(2), unlink(2). .SH STANDARDS CONFORMANCE .CR remove() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4remove()\fP \- remove a file@@@\f3remove(3C)\f1 .\" index@file: remove a file@@@\f3remove(3C)\f1 .\" .\" toc@\f3remove(3C)\f1:\0\0\f4remove()\fP@@@remove a file .\" .\" fileset_database@remove.3c PROGRAMING-MAN .\" $Header: insque.3c,v 72.2 94/08/18 10:45:50 ssa Exp $ .TA i .TH insque 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insque(), remque() \- insert or remove an element in a queue .SH SYNOPSIS .C "#include " .PP .C "void insque(void *element, void *pred);" .PP .C "void remque(void *element);" .SH DESCRIPTION The .CR insque() and .CR remque() functions manipulate queues built from doubly-linked lists. An application using these functions must define a structure in which the first two members of the structure are pointers to the same type of structure. Any additional members of the structure are application specific. The first two members of the structure are used for forward and backward pointers. The names of the structure and of the pointers are not subject to any restrictions. .PP The .CR insque() function inserts the object pointed to by the .I element argument into a queue immediately after the object pointed to by the .I pred argument. .PP The .CR remque() function removes the object pointed to by the .I element argument from a queue. .SH AUTHOR .CR insque() and .CR remque() were developed by HP and the University of California, Berkeley. .SH STANDARDS COMPLIANCE .CR insque() ": XPG4.2" .PP .CR remque() ": XPG4.2" .\" .\" toc@\f3insque(3C)\f1:\0\0\f4insque()\f1, \f4remque()\f1@@@insert or remove an element in a queue\f1 .\" toc@\f4remque()\f1:\0\0remove an element in a queue@@@\f1see \f3insque(3C)\f1 .\" index@\f4insque()\f1 \- insert an element in a queue@@@\f3insque(3C)\f1 .\" index@\f4remque()\f1 \- remove an element in a queue@@@\f3insque(3C)\f1 .\" index@\f1insert or remove an element in a queue@@@\f3insque(3C)\f1 .\" index@\f1remove or insert an element in a queue@@@\f3insque(3C)\f1 .\" index@\f1queue, insert or remove an element@@@\f3insque(3C)\f1 .\" .\" links@insque.3c remque.3c .\" $Header: resolver.3n,v 74.1 95/05/10 21:11:16 ssa Exp $ .TA r .TH resolver 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME res_query(\|), res_search(\|), res_mkquery(\|), res_send(\|), res_init(\|), dn_comp(\|), dn_expand(\|), herror(\|) \- resolver routines .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .C "#include " .PP .C "int res_query(" .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_search( .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_mkquery( .C " int op," .C " char *dname," .C " int class," .C " int type," .C " char *data," .C " int datalen," .C " struct rrec *newrr," .C " char *buf," .C " int buflen" .C ); .PP .C "int res_send( .C " char *msg," .C " int msglen," .C " char *answer, .C " int anslen .C ); .PP .C void res_init(); .PP .C int dn_comp( .C " char *exp_dn," .C " char *comp_dn," .C " int length," .C " char **dnptrs," .C " char **lastdnptr" .C ); .PP .C int dn_expand( .C " char *msg," .C " char *eomorig," .C " char *comp_dn," .C " char exp_dn," .C " int length" .C ); .PP .C extern int h_errno; .PP .C void herror(char *s); .PP .SH DESCRIPTION These routines are used for making, sending, and interpreting query and reply messages with Internet domain name servers. .PP Global configuration and state information used by the resolver routines are kept in the structure .CR _res and are defined in .RC < resolv.h >. Most of the fields have reasonable defaults and can be ignored. The resolver options are stored in the .CR _res.options field and are listed below. The options are stored as a simple bit mask containing the bitwise OR of the options enabled. .RS .TP 20 .C RES_INIT True if the initial name server address and default domain name are initialized (i.e., .C res_init() has been called). .TP .C RES_DEBUG Print debugging messages. .TP .C RES_AAONLY Accept authoritative answers only. With this option, .C res_send() should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. .TP .C RES_PRIMARY Query the primary server only. Currently this is not implemented. .TP .C RES_USEVC Use TCP connections for queries instead of UDP datagrams. .TP .C RES_STAYOPEN Used with .C RES_USEVC to keep the TCP connection open between queries. This is useful only in programs that regularly do many queries. UDP should be the normal mode used. .TP .C RES_IGNTC The name server will set the truncation bit if all of the data does not fit into the response datagram packet. If .C RES_IGNTC is set, .C res_send() will not retry the query with TCP (i.e., ignore truncation errors). .TP .C RES_RECURSE Set the recursion-desired bit in queries. This is the default. (\c .C res_send() does not do iterative queries and expects the name server to handle recursion.) .TP .C RES_DEFNAMES If set, .C res_search() appends the default domain name to single-component names (those that do not contain a dot). This option is enabled by default. .TP .C RES_DNSRCH If this option is set, .C res_search() searches for host names in the current domain and in parent domains; see .IR hostname (5). This is used by the standard host lookup routine .C gethostbyname() (see .IR gethostbyname (3N)). This option is enabled by default. .RE .PP Initialization of the resolver structure normally occurs on the first call to one of the resolver routines below. If there are errors in the configuration file, they are silently ignored. .RE .SS Primary Routines .TP 20 .C res_init() Reads the configuration file, .CR /etc/resolv.conf , to get the default domain name, search list, and the Internet address of the local name server(s). If no server is configured, the host running the resolver is tried. The current domain name is defined by the hostname if not specified in the configuration file; it can be overridden by the environment variable .CR LOCALDOMAIN . This environment variable may contain several blank separated tokens and overrides the search list on a per process basis. This is similar to the .CR search command in the configuration file. Another environment variable ( .CR RES_OPTIONS ) can be set to override certain internal resolver options which are set by calling some of the configuration routines above, or by using the configuration file's .CR options command. The syntax of the .CR RES_OPTIONS environment variable is explained in .IR resolver(4). .TP .C res_query() Provides an interface to the server query mechanism. It constructs a query, sends it to the local server, awaits a response, and makes preliminary checks on the reply. The query requests information of the specified .I type and .I class for the specified fully-qualified domain name .IR dname . The reply message is left in the .I answer buffer with length .I anslen supplied by the caller. .TP .C res_search() Makes a query and awaits a response much like .CR res_query() , but in addition, it implements the default and search rules controlled by the .C RES_DEFNAMES and .C RES_DNSRCH options. It returns the first successful reply. .SS Other Routines Routines described here are lower-level routines used by .CR res_query() . .TP 20 .C res_mkquery() Constructs a standard query message and places it in .IR buf . It returns the size of the query, or \(mi1 if the query is larger than .IR buflen . The query type .I op is usually .CR QUERY , but can be any of the query types defined in .RC < arpa/nameser.h >. The domain name for the query is given by .IR dname . .I class can be any of the query classes defined in .RC < arpa/nameser.h >. .I type can be any of the query types defined in .RC < arpa/nameser.h >. .I data is the data for an inverse query .RC ( IQUERY ). .I newrr is currently unused but is intended for making update messages. .TP .C res_send() Sends a pre-formatted query and returns an answer. It calls .C res_init() if .C RES_INIT is not set, sends the query to the local name server, and handles timeouts and retries. .C res_send() returns the length of the reply message, or \(mi1 if there were errors. .TP .C dn_comp() Compresses the domain name .I exp_dn and stores it in .IR comp_dn . The size of the compressed name is returned or \(mi1 if there were errors. .I length is the size of the array pointed to by .IR comp_dn . The compression uses an array of pointers .I dnptrs to previously compressed names in the current message. The first pointer points to to the beginning of the message and the list ends with NULL. The limit to the array is specified by .IR lastdnptr . A side effect of .C dn_comp() is to update the list of pointers for labels inserted into the message as the name is compressed. If .I dnptr is NULL, names are not compressed. If .I lastdnptr is NULL, the list of labels is not updated. .TP .C dn_expand() Expands the compressed domain name .I comp_dn to a full domain name. The compressed name is contained in a query or reply message; .I msg is a pointer to the beginning of the message. The uncompressed name is placed in the buffer indicated by .I exp_dn which is of size .IR length . The size of compressed name is returned or \(mi1 if there was an error. .SH RETURN VALUE Error return status from .C res_search() is indicated by a return value of \(mi1. The external integer .C h_errno can then be checked to see whether this is a temporary failure or an invalid or unknown host. The routine .C herror() can be used to print an error message describing the failure. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. .SH ERRORS .C h_errno can have the following values: .RS .TP 20 .C HOST_NOT_FOUND No such host is known. .TP .C TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .C NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. .TP .C NO_DATA The name is known to the name server, but there is no data of the requested type associated with this name; this is not a temporary error. Another type of request to the name server using this domain name will result in an answer. .RE .SH AUTHOR These resolver routines were developed by the University of California, Berkeley. .SH FILES .TP 30 .C /etc/resolv.conf Resolver configuration file. .SH SEE ALSO named(1m), gethostent(3N), resolver(4), hostname(5), RFC1034, RFC1035, RFC1535. .\" .\" index@\f4res_mkquery\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_query\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_search\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_send\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_init\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_comp\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1routines, resolver@@@\f3resolver(3N)\f1 .\" .\" toc@\f3resolver(3N)\f1:\0\0\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \f4dn_comp\f1, \f4dn_expand\f1, \n\f4herror\f1,\f1@@@resolver routines .\" toc@\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4dn_comp\f1, \f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" .\" links@resolver.3n res_mkquery.3n .\" links@resolver.3n res_query.3n .\" links@resolver.3n res_search.3n .\" links@resolver.3n res_send.3n .\" links@resolver.3n res_init.3n .\" links@resolver.3n dn_comp.3n .\" links@resolver.3n dn_expand.3n .\" links@resolver.3n herror.3n .\" .\" fileset_database@resolver.3n INETSVCS-MAN .\" $Header: resolver.3n,v 74.1 95/05/10 21:11:16 ssa Exp $ .TA r .TH resolver 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME res_query(\|), res_search(\|), res_mkquery(\|), res_send(\|), res_init(\|), dn_comp(\|), dn_expand(\|), herror(\|) \- resolver routines .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .C "#include " .PP .C "int res_query(" .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_search( .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_mkquery( .C " int op," .C " char *dname," .C " int class," .C " int type," .C " char *data," .C " int datalen," .C " struct rrec *newrr," .C " char *buf," .C " int buflen" .C ); .PP .C "int res_send( .C " char *msg," .C " int msglen," .C " char *answer, .C " int anslen .C ); .PP .C void res_init(); .PP .C int dn_comp( .C " char *exp_dn," .C " char *comp_dn," .C " int length," .C " char **dnptrs," .C " char **lastdnptr" .C ); .PP .C int dn_expand( .C " char *msg," .C " char *eomorig," .C " char *comp_dn," .C " char exp_dn," .C " int length" .C ); .PP .C extern int h_errno; .PP .C void herror(char *s); .PP .SH DESCRIPTION These routines are used for making, sending, and interpreting query and reply messages with Internet domain name servers. .PP Global configuration and state information used by the resolver routines are kept in the structure .CR _res and are defined in .RC < resolv.h >. Most of the fields have reasonable defaults and can be ignored. The resolver options are stored in the .CR _res.options field and are listed below. The options are stored as a simple bit mask containing the bitwise OR of the options enabled. .RS .TP 20 .C RES_INIT True if the initial name server address and default domain name are initialized (i.e., .C res_init() has been called). .TP .C RES_DEBUG Print debugging messages. .TP .C RES_AAONLY Accept authoritative answers only. With this option, .C res_send() should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. .TP .C RES_PRIMARY Query the primary server only. Currently this is not implemented. .TP .C RES_USEVC Use TCP connections for queries instead of UDP datagrams. .TP .C RES_STAYOPEN Used with .C RES_USEVC to keep the TCP connection open between queries. This is useful only in programs that regularly do many queries. UDP should be the normal mode used. .TP .C RES_IGNTC The name server will set the truncation bit if all of the data does not fit into the response datagram packet. If .C RES_IGNTC is set, .C res_send() will not retry the query with TCP (i.e., ignore truncation errors). .TP .C RES_RECURSE Set the recursion-desired bit in queries. This is the default. (\c .C res_send() does not do iterative queries and expects the name server to handle recursion.) .TP .C RES_DEFNAMES If set, .C res_search() appends the default domain name to single-component names (those that do not contain a dot). This option is enabled by default. .TP .C RES_DNSRCH If this option is set, .C res_search() searches for host names in the current domain and in parent domains; see .IR hostname (5). This is used by the standard host lookup routine .C gethostbyname() (see .IR gethostbyname (3N)). This option is enabled by default. .RE .PP Initialization of the resolver structure normally occurs on the first call to one of the resolver routines below. If there are errors in the configuration file, they are silently ignored. .RE .SS Primary Routines .TP 20 .C res_init() Reads the configuration file, .CR /etc/resolv.conf , to get the default domain name, search list, and the Internet address of the local name server(s). If no server is configured, the host running the resolver is tried. The current domain name is defined by the hostname if not specified in the configuration file; it can be overridden by the environment variable .CR LOCALDOMAIN . This environment variable may contain several blank separated tokens and overrides the search list on a per process basis. This is similar to the .CR search command in the configuration file. Another environment variable ( .CR RES_OPTIONS ) can be set to override certain internal resolver options which are set by calling some of the configuration routines above, or by using the configuration file's .CR options command. The syntax of the .CR RES_OPTIONS environment variable is explained in .IR resolver(4). .TP .C res_query() Provides an interface to the server query mechanism. It constructs a query, sends it to the local server, awaits a response, and makes preliminary checks on the reply. The query requests information of the specified .I type and .I class for the specified fully-qualified domain name .IR dname . The reply message is left in the .I answer buffer with length .I anslen supplied by the caller. .TP .C res_search() Makes a query and awaits a response much like .CR res_query() , but in addition, it implements the default and search rules controlled by the .C RES_DEFNAMES and .C RES_DNSRCH options. It returns the first successful reply. .SS Other Routines Routines described here are lower-level routines used by .CR res_query() . .TP 20 .C res_mkquery() Constructs a standard query message and places it in .IR buf . It returns the size of the query, or \(mi1 if the query is larger than .IR buflen . The query type .I op is usually .CR QUERY , but can be any of the query types defined in .RC < arpa/nameser.h >. The domain name for the query is given by .IR dname . .I class can be any of the query classes defined in .RC < arpa/nameser.h >. .I type can be any of the query types defined in .RC < arpa/nameser.h >. .I data is the data for an inverse query .RC ( IQUERY ). .I newrr is currently unused but is intended for making update messages. .TP .C res_send() Sends a pre-formatted query and returns an answer. It calls .C res_init() if .C RES_INIT is not set, sends the query to the local name server, and handles timeouts and retries. .C res_send() returns the length of the reply message, or \(mi1 if there were errors. .TP .C dn_comp() Compresses the domain name .I exp_dn and stores it in .IR comp_dn . The size of the compressed name is returned or \(mi1 if there were errors. .I length is the size of the array pointed to by .IR comp_dn . The compression uses an array of pointers .I dnptrs to previously compressed names in the current message. The first pointer points to to the beginning of the message and the list ends with NULL. The limit to the array is specified by .IR lastdnptr . A side effect of .C dn_comp() is to update the list of pointers for labels inserted into the message as the name is compressed. If .I dnptr is NULL, names are not compressed. If .I lastdnptr is NULL, the list of labels is not updated. .TP .C dn_expand() Expands the compressed domain name .I comp_dn to a full domain name. The compressed name is contained in a query or reply message; .I msg is a pointer to the beginning of the message. The uncompressed name is placed in the buffer indicated by .I exp_dn which is of size .IR length . The size of compressed name is returned or \(mi1 if there was an error. .SH RETURN VALUE Error return status from .C res_search() is indicated by a return value of \(mi1. The external integer .C h_errno can then be checked to see whether this is a temporary failure or an invalid or unknown host. The routine .C herror() can be used to print an error message describing the failure. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. .SH ERRORS .C h_errno can have the following values: .RS .TP 20 .C HOST_NOT_FOUND No such host is known. .TP .C TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .C NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. .TP .C NO_DATA The name is known to the name server, but there is no data of the requested type associated with this name; this is not a temporary error. Another type of request to the name server using this domain name will result in an answer. .RE .SH AUTHOR These resolver routines were developed by the University of California, Berkeley. .SH FILES .TP 30 .C /etc/resolv.conf Resolver configuration file. .SH SEE ALSO named(1m), gethostent(3N), resolver(4), hostname(5), RFC1034, RFC1035, RFC1535. .\" .\" index@\f4res_mkquery\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_query\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_search\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_send\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_init\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_comp\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1routines, resolver@@@\f3resolver(3N)\f1 .\" .\" toc@\f3resolver(3N)\f1:\0\0\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \f4dn_comp\f1, \f4dn_expand\f1, \n\f4herror\f1,\f1@@@resolver routines .\" toc@\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4dn_comp\f1, \f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" .\" links@resolver.3n res_mkquery.3n .\" links@resolver.3n res_query.3n .\" links@resolver.3n res_search.3n .\" links@resolver.3n res_send.3n .\" links@resolver.3n res_init.3n .\" links@resolver.3n dn_comp.3n .\" links@resolver.3n dn_expand.3n .\" links@resolver.3n herror.3n .\" .\" fileset_database@resolver.3n INETSVCS-MAN .\" $Header: resolver.3n,v 74.1 95/05/10 21:11:16 ssa Exp $ .TA r .TH resolver 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME res_query(\|), res_search(\|), res_mkquery(\|), res_send(\|), res_init(\|), dn_comp(\|), dn_expand(\|), herror(\|) \- resolver routines .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .C "#include " .PP .C "int res_query(" .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_search( .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_mkquery( .C " int op," .C " char *dname," .C " int class," .C " int type," .C " char *data," .C " int datalen," .C " struct rrec *newrr," .C " char *buf," .C " int buflen" .C ); .PP .C "int res_send( .C " char *msg," .C " int msglen," .C " char *answer, .C " int anslen .C ); .PP .C void res_init(); .PP .C int dn_comp( .C " char *exp_dn," .C " char *comp_dn," .C " int length," .C " char **dnptrs," .C " char **lastdnptr" .C ); .PP .C int dn_expand( .C " char *msg," .C " char *eomorig," .C " char *comp_dn," .C " char exp_dn," .C " int length" .C ); .PP .C extern int h_errno; .PP .C void herror(char *s); .PP .SH DESCRIPTION These routines are used for making, sending, and interpreting query and reply messages with Internet domain name servers. .PP Global configuration and state information used by the resolver routines are kept in the structure .CR _res and are defined in .RC < resolv.h >. Most of the fields have reasonable defaults and can be ignored. The resolver options are stored in the .CR _res.options field and are listed below. The options are stored as a simple bit mask containing the bitwise OR of the options enabled. .RS .TP 20 .C RES_INIT True if the initial name server address and default domain name are initialized (i.e., .C res_init() has been called). .TP .C RES_DEBUG Print debugging messages. .TP .C RES_AAONLY Accept authoritative answers only. With this option, .C res_send() should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. .TP .C RES_PRIMARY Query the primary server only. Currently this is not implemented. .TP .C RES_USEVC Use TCP connections for queries instead of UDP datagrams. .TP .C RES_STAYOPEN Used with .C RES_USEVC to keep the TCP connection open between queries. This is useful only in programs that regularly do many queries. UDP should be the normal mode used. .TP .C RES_IGNTC The name server will set the truncation bit if all of the data does not fit into the response datagram packet. If .C RES_IGNTC is set, .C res_send() will not retry the query with TCP (i.e., ignore truncation errors). .TP .C RES_RECURSE Set the recursion-desired bit in queries. This is the default. (\c .C res_send() does not do iterative queries and expects the name server to handle recursion.) .TP .C RES_DEFNAMES If set, .C res_search() appends the default domain name to single-component names (those that do not contain a dot). This option is enabled by default. .TP .C RES_DNSRCH If this option is set, .C res_search() searches for host names in the current domain and in parent domains; see .IR hostname (5). This is used by the standard host lookup routine .C gethostbyname() (see .IR gethostbyname (3N)). This option is enabled by default. .RE .PP Initialization of the resolver structure normally occurs on the first call to one of the resolver routines below. If there are errors in the configuration file, they are silently ignored. .RE .SS Primary Routines .TP 20 .C res_init() Reads the configuration file, .CR /etc/resolv.conf , to get the default domain name, search list, and the Internet address of the local name server(s). If no server is configured, the host running the resolver is tried. The current domain name is defined by the hostname if not specified in the configuration file; it can be overridden by the environment variable .CR LOCALDOMAIN . This environment variable may contain several blank separated tokens and overrides the search list on a per process basis. This is similar to the .CR search command in the configuration file. Another environment variable ( .CR RES_OPTIONS ) can be set to override certain internal resolver options which are set by calling some of the configuration routines above, or by using the configuration file's .CR options command. The syntax of the .CR RES_OPTIONS environment variable is explained in .IR resolver(4). .TP .C res_query() Provides an interface to the server query mechanism. It constructs a query, sends it to the local server, awaits a response, and makes preliminary checks on the reply. The query requests information of the specified .I type and .I class for the specified fully-qualified domain name .IR dname . The reply message is left in the .I answer buffer with length .I anslen supplied by the caller. .TP .C res_search() Makes a query and awaits a response much like .CR res_query() , but in addition, it implements the default and search rules controlled by the .C RES_DEFNAMES and .C RES_DNSRCH options. It returns the first successful reply. .SS Other Routines Routines described here are lower-level routines used by .CR res_query() . .TP 20 .C res_mkquery() Constructs a standard query message and places it in .IR buf . It returns the size of the query, or \(mi1 if the query is larger than .IR buflen . The query type .I op is usually .CR QUERY , but can be any of the query types defined in .RC < arpa/nameser.h >. The domain name for the query is given by .IR dname . .I class can be any of the query classes defined in .RC < arpa/nameser.h >. .I type can be any of the query types defined in .RC < arpa/nameser.h >. .I data is the data for an inverse query .RC ( IQUERY ). .I newrr is currently unused but is intended for making update messages. .TP .C res_send() Sends a pre-formatted query and returns an answer. It calls .C res_init() if .C RES_INIT is not set, sends the query to the local name server, and handles timeouts and retries. .C res_send() returns the length of the reply message, or \(mi1 if there were errors. .TP .C dn_comp() Compresses the domain name .I exp_dn and stores it in .IR comp_dn . The size of the compressed name is returned or \(mi1 if there were errors. .I length is the size of the array pointed to by .IR comp_dn . The compression uses an array of pointers .I dnptrs to previously compressed names in the current message. The first pointer points to to the beginning of the message and the list ends with NULL. The limit to the array is specified by .IR lastdnptr . A side effect of .C dn_comp() is to update the list of pointers for labels inserted into the message as the name is compressed. If .I dnptr is NULL, names are not compressed. If .I lastdnptr is NULL, the list of labels is not updated. .TP .C dn_expand() Expands the compressed domain name .I comp_dn to a full domain name. The compressed name is contained in a query or reply message; .I msg is a pointer to the beginning of the message. The uncompressed name is placed in the buffer indicated by .I exp_dn which is of size .IR length . The size of compressed name is returned or \(mi1 if there was an error. .SH RETURN VALUE Error return status from .C res_search() is indicated by a return value of \(mi1. The external integer .C h_errno can then be checked to see whether this is a temporary failure or an invalid or unknown host. The routine .C herror() can be used to print an error message describing the failure. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. .SH ERRORS .C h_errno can have the following values: .RS .TP 20 .C HOST_NOT_FOUND No such host is known. .TP .C TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .C NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. .TP .C NO_DATA The name is known to the name server, but there is no data of the requested type associated with this name; this is not a temporary error. Another type of request to the name server using this domain name will result in an answer. .RE .SH AUTHOR These resolver routines were developed by the University of California, Berkeley. .SH FILES .TP 30 .C /etc/resolv.conf Resolver configuration file. .SH SEE ALSO named(1m), gethostent(3N), resolver(4), hostname(5), RFC1034, RFC1035, RFC1535. .\" .\" index@\f4res_mkquery\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_query\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_search\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_send\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_init\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_comp\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1routines, resolver@@@\f3resolver(3N)\f1 .\" .\" toc@\f3resolver(3N)\f1:\0\0\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \f4dn_comp\f1, \f4dn_expand\f1, \n\f4herror\f1,\f1@@@resolver routines .\" toc@\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4dn_comp\f1, \f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" .\" links@resolver.3n res_mkquery.3n .\" links@resolver.3n res_query.3n .\" links@resolver.3n res_search.3n .\" links@resolver.3n res_send.3n .\" links@resolver.3n res_init.3n .\" links@resolver.3n dn_comp.3n .\" links@resolver.3n dn_expand.3n .\" links@resolver.3n herror.3n .\" .\" fileset_database@resolver.3n INETSVCS-MAN .\" $Header: resolver.3n,v 74.1 95/05/10 21:11:16 ssa Exp $ .TA r .TH resolver 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME res_query(\|), res_search(\|), res_mkquery(\|), res_send(\|), res_init(\|), dn_comp(\|), dn_expand(\|), herror(\|) \- resolver routines .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .C "#include " .PP .C "int res_query(" .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_search( .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_mkquery( .C " int op," .C " char *dname," .C " int class," .C " int type," .C " char *data," .C " int datalen," .C " struct rrec *newrr," .C " char *buf," .C " int buflen" .C ); .PP .C "int res_send( .C " char *msg," .C " int msglen," .C " char *answer, .C " int anslen .C ); .PP .C void res_init(); .PP .C int dn_comp( .C " char *exp_dn," .C " char *comp_dn," .C " int length," .C " char **dnptrs," .C " char **lastdnptr" .C ); .PP .C int dn_expand( .C " char *msg," .C " char *eomorig," .C " char *comp_dn," .C " char exp_dn," .C " int length" .C ); .PP .C extern int h_errno; .PP .C void herror(char *s); .PP .SH DESCRIPTION These routines are used for making, sending, and interpreting query and reply messages with Internet domain name servers. .PP Global configuration and state information used by the resolver routines are kept in the structure .CR _res and are defined in .RC < resolv.h >. Most of the fields have reasonable defaults and can be ignored. The resolver options are stored in the .CR _res.options field and are listed below. The options are stored as a simple bit mask containing the bitwise OR of the options enabled. .RS .TP 20 .C RES_INIT True if the initial name server address and default domain name are initialized (i.e., .C res_init() has been called). .TP .C RES_DEBUG Print debugging messages. .TP .C RES_AAONLY Accept authoritative answers only. With this option, .C res_send() should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. .TP .C RES_PRIMARY Query the primary server only. Currently this is not implemented. .TP .C RES_USEVC Use TCP connections for queries instead of UDP datagrams. .TP .C RES_STAYOPEN Used with .C RES_USEVC to keep the TCP connection open between queries. This is useful only in programs that regularly do many queries. UDP should be the normal mode used. .TP .C RES_IGNTC The name server will set the truncation bit if all of the data does not fit into the response datagram packet. If .C RES_IGNTC is set, .C res_send() will not retry the query with TCP (i.e., ignore truncation errors). .TP .C RES_RECURSE Set the recursion-desired bit in queries. This is the default. (\c .C res_send() does not do iterative queries and expects the name server to handle recursion.) .TP .C RES_DEFNAMES If set, .C res_search() appends the default domain name to single-component names (those that do not contain a dot). This option is enabled by default. .TP .C RES_DNSRCH If this option is set, .C res_search() searches for host names in the current domain and in parent domains; see .IR hostname (5). This is used by the standard host lookup routine .C gethostbyname() (see .IR gethostbyname (3N)). This option is enabled by default. .RE .PP Initialization of the resolver structure normally occurs on the first call to one of the resolver routines below. If there are errors in the configuration file, they are silently ignored. .RE .SS Primary Routines .TP 20 .C res_init() Reads the configuration file, .CR /etc/resolv.conf , to get the default domain name, search list, and the Internet address of the local name server(s). If no server is configured, the host running the resolver is tried. The current domain name is defined by the hostname if not specified in the configuration file; it can be overridden by the environment variable .CR LOCALDOMAIN . This environment variable may contain several blank separated tokens and overrides the search list on a per process basis. This is similar to the .CR search command in the configuration file. Another environment variable ( .CR RES_OPTIONS ) can be set to override certain internal resolver options which are set by calling some of the configuration routines above, or by using the configuration file's .CR options command. The syntax of the .CR RES_OPTIONS environment variable is explained in .IR resolver(4). .TP .C res_query() Provides an interface to the server query mechanism. It constructs a query, sends it to the local server, awaits a response, and makes preliminary checks on the reply. The query requests information of the specified .I type and .I class for the specified fully-qualified domain name .IR dname . The reply message is left in the .I answer buffer with length .I anslen supplied by the caller. .TP .C res_search() Makes a query and awaits a response much like .CR res_query() , but in addition, it implements the default and search rules controlled by the .C RES_DEFNAMES and .C RES_DNSRCH options. It returns the first successful reply. .SS Other Routines Routines described here are lower-level routines used by .CR res_query() . .TP 20 .C res_mkquery() Constructs a standard query message and places it in .IR buf . It returns the size of the query, or \(mi1 if the query is larger than .IR buflen . The query type .I op is usually .CR QUERY , but can be any of the query types defined in .RC < arpa/nameser.h >. The domain name for the query is given by .IR dname . .I class can be any of the query classes defined in .RC < arpa/nameser.h >. .I type can be any of the query types defined in .RC < arpa/nameser.h >. .I data is the data for an inverse query .RC ( IQUERY ). .I newrr is currently unused but is intended for making update messages. .TP .C res_send() Sends a pre-formatted query and returns an answer. It calls .C res_init() if .C RES_INIT is not set, sends the query to the local name server, and handles timeouts and retries. .C res_send() returns the length of the reply message, or \(mi1 if there were errors. .TP .C dn_comp() Compresses the domain name .I exp_dn and stores it in .IR comp_dn . The size of the compressed name is returned or \(mi1 if there were errors. .I length is the size of the array pointed to by .IR comp_dn . The compression uses an array of pointers .I dnptrs to previously compressed names in the current message. The first pointer points to to the beginning of the message and the list ends with NULL. The limit to the array is specified by .IR lastdnptr . A side effect of .C dn_comp() is to update the list of pointers for labels inserted into the message as the name is compressed. If .I dnptr is NULL, names are not compressed. If .I lastdnptr is NULL, the list of labels is not updated. .TP .C dn_expand() Expands the compressed domain name .I comp_dn to a full domain name. The compressed name is contained in a query or reply message; .I msg is a pointer to the beginning of the message. The uncompressed name is placed in the buffer indicated by .I exp_dn which is of size .IR length . The size of compressed name is returned or \(mi1 if there was an error. .SH RETURN VALUE Error return status from .C res_search() is indicated by a return value of \(mi1. The external integer .C h_errno can then be checked to see whether this is a temporary failure or an invalid or unknown host. The routine .C herror() can be used to print an error message describing the failure. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. .SH ERRORS .C h_errno can have the following values: .RS .TP 20 .C HOST_NOT_FOUND No such host is known. .TP .C TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .C NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. .TP .C NO_DATA The name is known to the name server, but there is no data of the requested type associated with this name; this is not a temporary error. Another type of request to the name server using this domain name will result in an answer. .RE .SH AUTHOR These resolver routines were developed by the University of California, Berkeley. .SH FILES .TP 30 .C /etc/resolv.conf Resolver configuration file. .SH SEE ALSO named(1m), gethostent(3N), resolver(4), hostname(5), RFC1034, RFC1035, RFC1535. .\" .\" index@\f4res_mkquery\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_query\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_search\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_send\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_init\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_comp\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1routines, resolver@@@\f3resolver(3N)\f1 .\" .\" toc@\f3resolver(3N)\f1:\0\0\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \f4dn_comp\f1, \f4dn_expand\f1, \n\f4herror\f1,\f1@@@resolver routines .\" toc@\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4dn_comp\f1, \f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" .\" links@resolver.3n res_mkquery.3n .\" links@resolver.3n res_query.3n .\" links@resolver.3n res_search.3n .\" links@resolver.3n res_send.3n .\" links@resolver.3n res_init.3n .\" links@resolver.3n dn_comp.3n .\" links@resolver.3n dn_expand.3n .\" links@resolver.3n herror.3n .\" .\" fileset_database@resolver.3n INETSVCS-MAN .\" $Header: resolver.3n,v 74.1 95/05/10 21:11:16 ssa Exp $ .TA r .TH resolver 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME res_query(\|), res_search(\|), res_mkquery(\|), res_send(\|), res_init(\|), dn_comp(\|), dn_expand(\|), herror(\|) \- resolver routines .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .C "#include " .PP .C "int res_query(" .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_search( .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_mkquery( .C " int op," .C " char *dname," .C " int class," .C " int type," .C " char *data," .C " int datalen," .C " struct rrec *newrr," .C " char *buf," .C " int buflen" .C ); .PP .C "int res_send( .C " char *msg," .C " int msglen," .C " char *answer, .C " int anslen .C ); .PP .C void res_init(); .PP .C int dn_comp( .C " char *exp_dn," .C " char *comp_dn," .C " int length," .C " char **dnptrs," .C " char **lastdnptr" .C ); .PP .C int dn_expand( .C " char *msg," .C " char *eomorig," .C " char *comp_dn," .C " char exp_dn," .C " int length" .C ); .PP .C extern int h_errno; .PP .C void herror(char *s); .PP .SH DESCRIPTION These routines are used for making, sending, and interpreting query and reply messages with Internet domain name servers. .PP Global configuration and state information used by the resolver routines are kept in the structure .CR _res and are defined in .RC < resolv.h >. Most of the fields have reasonable defaults and can be ignored. The resolver options are stored in the .CR _res.options field and are listed below. The options are stored as a simple bit mask containing the bitwise OR of the options enabled. .RS .TP 20 .C RES_INIT True if the initial name server address and default domain name are initialized (i.e., .C res_init() has been called). .TP .C RES_DEBUG Print debugging messages. .TP .C RES_AAONLY Accept authoritative answers only. With this option, .C res_send() should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. .TP .C RES_PRIMARY Query the primary server only. Currently this is not implemented. .TP .C RES_USEVC Use TCP connections for queries instead of UDP datagrams. .TP .C RES_STAYOPEN Used with .C RES_USEVC to keep the TCP connection open between queries. This is useful only in programs that regularly do many queries. UDP should be the normal mode used. .TP .C RES_IGNTC The name server will set the truncation bit if all of the data does not fit into the response datagram packet. If .C RES_IGNTC is set, .C res_send() will not retry the query with TCP (i.e., ignore truncation errors). .TP .C RES_RECURSE Set the recursion-desired bit in queries. This is the default. (\c .C res_send() does not do iterative queries and expects the name server to handle recursion.) .TP .C RES_DEFNAMES If set, .C res_search() appends the default domain name to single-component names (those that do not contain a dot). This option is enabled by default. .TP .C RES_DNSRCH If this option is set, .C res_search() searches for host names in the current domain and in parent domains; see .IR hostname (5). This is used by the standard host lookup routine .C gethostbyname() (see .IR gethostbyname (3N)). This option is enabled by default. .RE .PP Initialization of the resolver structure normally occurs on the first call to one of the resolver routines below. If there are errors in the configuration file, they are silently ignored. .RE .SS Primary Routines .TP 20 .C res_init() Reads the configuration file, .CR /etc/resolv.conf , to get the default domain name, search list, and the Internet address of the local name server(s). If no server is configured, the host running the resolver is tried. The current domain name is defined by the hostname if not specified in the configuration file; it can be overridden by the environment variable .CR LOCALDOMAIN . This environment variable may contain several blank separated tokens and overrides the search list on a per process basis. This is similar to the .CR search command in the configuration file. Another environment variable ( .CR RES_OPTIONS ) can be set to override certain internal resolver options which are set by calling some of the configuration routines above, or by using the configuration file's .CR options command. The syntax of the .CR RES_OPTIONS environment variable is explained in .IR resolver(4). .TP .C res_query() Provides an interface to the server query mechanism. It constructs a query, sends it to the local server, awaits a response, and makes preliminary checks on the reply. The query requests information of the specified .I type and .I class for the specified fully-qualified domain name .IR dname . The reply message is left in the .I answer buffer with length .I anslen supplied by the caller. .TP .C res_search() Makes a query and awaits a response much like .CR res_query() , but in addition, it implements the default and search rules controlled by the .C RES_DEFNAMES and .C RES_DNSRCH options. It returns the first successful reply. .SS Other Routines Routines described here are lower-level routines used by .CR res_query() . .TP 20 .C res_mkquery() Constructs a standard query message and places it in .IR buf . It returns the size of the query, or \(mi1 if the query is larger than .IR buflen . The query type .I op is usually .CR QUERY , but can be any of the query types defined in .RC < arpa/nameser.h >. The domain name for the query is given by .IR dname . .I class can be any of the query classes defined in .RC < arpa/nameser.h >. .I type can be any of the query types defined in .RC < arpa/nameser.h >. .I data is the data for an inverse query .RC ( IQUERY ). .I newrr is currently unused but is intended for making update messages. .TP .C res_send() Sends a pre-formatted query and returns an answer. It calls .C res_init() if .C RES_INIT is not set, sends the query to the local name server, and handles timeouts and retries. .C res_send() returns the length of the reply message, or \(mi1 if there were errors. .TP .C dn_comp() Compresses the domain name .I exp_dn and stores it in .IR comp_dn . The size of the compressed name is returned or \(mi1 if there were errors. .I length is the size of the array pointed to by .IR comp_dn . The compression uses an array of pointers .I dnptrs to previously compressed names in the current message. The first pointer points to to the beginning of the message and the list ends with NULL. The limit to the array is specified by .IR lastdnptr . A side effect of .C dn_comp() is to update the list of pointers for labels inserted into the message as the name is compressed. If .I dnptr is NULL, names are not compressed. If .I lastdnptr is NULL, the list of labels is not updated. .TP .C dn_expand() Expands the compressed domain name .I comp_dn to a full domain name. The compressed name is contained in a query or reply message; .I msg is a pointer to the beginning of the message. The uncompressed name is placed in the buffer indicated by .I exp_dn which is of size .IR length . The size of compressed name is returned or \(mi1 if there was an error. .SH RETURN VALUE Error return status from .C res_search() is indicated by a return value of \(mi1. The external integer .C h_errno can then be checked to see whether this is a temporary failure or an invalid or unknown host. The routine .C herror() can be used to print an error message describing the failure. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. .SH ERRORS .C h_errno can have the following values: .RS .TP 20 .C HOST_NOT_FOUND No such host is known. .TP .C TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .C NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. .TP .C NO_DATA The name is known to the name server, but there is no data of the requested type associated with this name; this is not a temporary error. Another type of request to the name server using this domain name will result in an answer. .RE .SH AUTHOR These resolver routines were developed by the University of California, Berkeley. .SH FILES .TP 30 .C /etc/resolv.conf Resolver configuration file. .SH SEE ALSO named(1m), gethostent(3N), resolver(4), hostname(5), RFC1034, RFC1035, RFC1535. .\" .\" index@\f4res_mkquery\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_query\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_search\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_send\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_init\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_comp\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1routines, resolver@@@\f3resolver(3N)\f1 .\" .\" toc@\f3resolver(3N)\f1:\0\0\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \f4dn_comp\f1, \f4dn_expand\f1, \n\f4herror\f1,\f1@@@resolver routines .\" toc@\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4dn_comp\f1, \f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" .\" links@resolver.3n res_mkquery.3n .\" links@resolver.3n res_query.3n .\" links@resolver.3n res_search.3n .\" links@resolver.3n res_send.3n .\" links@resolver.3n res_init.3n .\" links@resolver.3n dn_comp.3n .\" links@resolver.3n dn_expand.3n .\" links@resolver.3n herror.3n .\" .\" fileset_database@resolver.3n INETSVCS-MAN .\" $Header: def_prog_mode.3x,v 76.2 95/07/31 11:23:20 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH def_prog_mode 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 defshell .SH NAME def_prog_mode, def_shell_mode, reset_prog_mode, reset_shell_mode \(em save or restore program or shell terminal modes .SH SYNOPSIS .C "#include " .P .C "int def_prog_mode(void);" .P .C "int def_shell_mode(void);" .P .C "int reset_prog_mode(void);" .P .C "int reset_shell_mode(void);" .SH DESCRIPTION The .Fn def_prog_mode function saves the current terminal modes as the ``program'' (in Curses) state for use by .Fn reset_prog_mode . .P The .Fn def_shell_mode function saves the current terminal modes as the ``shell'' (not in Curses) state for use by .Fn reset_shell_mode . .P The .Fn reset_prog_mode function restores the terminal to the ``program'' (in Curses) state. .P The .Fn reset_shell_mode function restores the terminal to the ``shell'' (not in Curses) state. .P These functions affect the mode of the terminal associated with the current screen. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn initscr function achieves the effect of calling .Fn def_shell_mode to save the prior terminal settings so they can be restored during the call to .Fn endwin , and of calling .Fn def_prog_mode to specify an initial definition of the program terminal mode. .P Applications normally do not need to refer to the shell terminal mode. Applications may find it useful to save and restore the program terminal mode. .SH "SEE ALSO" doupdate(), endwin(), initscr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The .Fn reset_prog_mode and .Fn reset_shell_mode functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The argument list for all these functions is explicitly declared as \f3void\f1. .\" .\" .\" toc@\f3def_prog_mode(3x)\f1:\0\0\f4def_prog_mode()\f1, \f4def_shell_mode()\f1, \f4reset_prog_mode()\f1, \n\f4reset_shell_mode()\f1@@@save or restore program or shell terminal modes .\" toc@\f4def_shell_mode()\f1:\0\0save current terminal modes as the ``shell'' (not in Curses) state@@@\f1see \f3def_prog_mode(3x)\f1 .\" toc@\f4reset_prog_mode()\f1:\0\0restore terminal modes to ``program'' (in Curses) state@@@\f1see \f3def_prog_mode(3x)\f1 .\" toc@\f4reset_shell_mode()\f1:\0\0restore terminal modes to ``shell'' (not in Curses) state@@@\f1see \f3def_prog_mode(3x)\f1 .\" .\" index@\f4def_shell_mode()\f1 \- save terminal modes as the ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" index@\f4def_prog_mode()\f1 \- save or restore program or shell terminal modes@@@\f3def_prog_mode(3x)\f1 .\" index@\f4reset_prog_mode()\f1 \- restore shell terminal modes to ``program'' state @@@\f3def_prog_mode(3x)\f1 .\" index@\f4reset_shell_mode()\f1 \- restore terminal modes to ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" .\" index@\f1save terminal modes as the ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" index@\f1save or restore program or shell terminal modes@@@\f3def_prog_mode(3x)\f1 .\" index@\f1restore shell terminal modes to ``program'' state @@@\f3def_prog_mode(3x)\f1 .\" index@\f1restore terminal modes to ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" .\" .\" links@def_prog_mode.3x def_shell_mode.3x .\" links@def_prog_mode.3x reset_prog_mode.3x .\" links@def_prog_mode.3x reset_shell_mode.3x .\" .\" fileset_database@def_prog_mode.3x CURS-ENG-A-MAN .\" $Header: def_prog_mode.3x,v 76.2 95/07/31 11:23:20 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH def_prog_mode 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 defshell .SH NAME def_prog_mode, def_shell_mode, reset_prog_mode, reset_shell_mode \(em save or restore program or shell terminal modes .SH SYNOPSIS .C "#include " .P .C "int def_prog_mode(void);" .P .C "int def_shell_mode(void);" .P .C "int reset_prog_mode(void);" .P .C "int reset_shell_mode(void);" .SH DESCRIPTION The .Fn def_prog_mode function saves the current terminal modes as the ``program'' (in Curses) state for use by .Fn reset_prog_mode . .P The .Fn def_shell_mode function saves the current terminal modes as the ``shell'' (not in Curses) state for use by .Fn reset_shell_mode . .P The .Fn reset_prog_mode function restores the terminal to the ``program'' (in Curses) state. .P The .Fn reset_shell_mode function restores the terminal to the ``shell'' (not in Curses) state. .P These functions affect the mode of the terminal associated with the current screen. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn initscr function achieves the effect of calling .Fn def_shell_mode to save the prior terminal settings so they can be restored during the call to .Fn endwin , and of calling .Fn def_prog_mode to specify an initial definition of the program terminal mode. .P Applications normally do not need to refer to the shell terminal mode. Applications may find it useful to save and restore the program terminal mode. .SH "SEE ALSO" doupdate(), endwin(), initscr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The .Fn reset_prog_mode and .Fn reset_shell_mode functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The argument list for all these functions is explicitly declared as \f3void\f1. .\" .\" .\" toc@\f3def_prog_mode(3x)\f1:\0\0\f4def_prog_mode()\f1, \f4def_shell_mode()\f1, \f4reset_prog_mode()\f1, \n\f4reset_shell_mode()\f1@@@save or restore program or shell terminal modes .\" toc@\f4def_shell_mode()\f1:\0\0save current terminal modes as the ``shell'' (not in Curses) state@@@\f1see \f3def_prog_mode(3x)\f1 .\" toc@\f4reset_prog_mode()\f1:\0\0restore terminal modes to ``program'' (in Curses) state@@@\f1see \f3def_prog_mode(3x)\f1 .\" toc@\f4reset_shell_mode()\f1:\0\0restore terminal modes to ``shell'' (not in Curses) state@@@\f1see \f3def_prog_mode(3x)\f1 .\" .\" index@\f4def_shell_mode()\f1 \- save terminal modes as the ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" index@\f4def_prog_mode()\f1 \- save or restore program or shell terminal modes@@@\f3def_prog_mode(3x)\f1 .\" index@\f4reset_prog_mode()\f1 \- restore shell terminal modes to ``program'' state @@@\f3def_prog_mode(3x)\f1 .\" index@\f4reset_shell_mode()\f1 \- restore terminal modes to ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" .\" index@\f1save terminal modes as the ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" index@\f1save or restore program or shell terminal modes@@@\f3def_prog_mode(3x)\f1 .\" index@\f1restore shell terminal modes to ``program'' state @@@\f3def_prog_mode(3x)\f1 .\" index@\f1restore terminal modes to ``shell'' state@@@\f3def_prog_mode(3x)\f1 .\" .\" .\" links@def_prog_mode.3x def_shell_mode.3x .\" links@def_prog_mode.3x reset_prog_mode.3x .\" links@def_prog_mode.3x reset_shell_mode.3x .\" .\" fileset_database@def_prog_mode.3x CURS-ENG-A-MAN .\" $Header: resetty.3x,v 76.2 95/08/01 14:38:44 ssa Exp $ .TA r .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH resetty 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME resetty, savetty \(em save/restore terminal mode .SH SYNOPSIS .C "#include " .P .C "int resetty(void);" .P .C "int savetty(void);" .SH DESCRIPTION The .Fn resetty function restores the program mode as of the most recent call to .CR savetty() . .P The .Fn savetty function saves the state that would be put in place by a call to .CR reset_prog_mode() . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" def_prog_mode(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn resetty and .Fn savetty functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3resetty(3X)\f1:\0\0\f4resetty()\f1, \f4savetty()\f1@@@save/restore terminal mode .\" toc@\f4savetty()\f1: save/restore terminal mode@@@see \f3resetty(3X)\f1 .\" .\" index@\f4resetty()\f1 \- save/restore terminal mode@@@\f3resetty(3X)\f1 .\" index@\f4savetty()\f1 \- save/restore terminal mode@@@\f3resetty(3X)\f1 .\" index@\f1save/restore terminal mode@@@\f3resetty(3X)\f1 .\" index@\f1restore terminal mode@@@\f3resetty(3X)\f1 .\" index@\f1terminal mode, save/restore@@@\f3resetty(3X)\f1 .\" .\" links@resetty.3x savetty.3x .\" .\" fileset_database@resetty.3x CURS-ENG-A-MAN .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "resize" "Xt \- Intrinsics Methods" .SH "Name" .Na resize \- RectObj class method called when a widget is resized. .Nz .XX "resizing: resize method" .XX "methods, resize" .SH "Synopsis" .Sy typedef void (*XtWidgetProc)(Widget); .As Widget \f(CIw\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget that has been resized. .\" .SH "Description" The \f(CWresize()\fP method is registered on the \f(CWresize\fP field of the RectObj or Core class part structure. It is called when a widget is resized through a call to \f(CWXtResizeWidget()\fP or \f(CWXtConfigureWidget()\fP, and is responsible for doing any layout of children or recalculating any cached values necessary for the widget to draw itself at its new size. .LP The \f(CWresize()\fP method is called whether or not the widget is realized. The \f(CWwidth\fR, \f(CWheight\fR, and \f(CWborder_width\fR fields of the widget contain the new size of the widget. Note that this method is not responsible for drawing the widget at its new size. Unless the widget's window has bit gravity set (which is not the default) then when the window is resized, an \f(CWExpose\fP event will be generated, and the \f(CWexpose()\fP method will be called by the Intrinsics. If the \f(CWresize()\fP method does call the \f(CWexpose()\fP method, then the widget will be redrawn twice. .LP The widget must treat \f(CWresize()\fR as a command, not as a request. A widget must neither change its own size from within the \f(CWresize()\fR method, nor appeal the size change by calling \f(CWXtMakeGeometryRequest()\fR or \f(CWXtMakeResizeRequest()\fR. .LP Note that the \f(CWresize()\fP method is not invoked by \f(CWXtMakeResizeRequest()\fP or \f(CWXtMakeGeometryRequest()\fP, but it may be called if the parent explicitly resizes the widget while granting the resize request. Because the widget does not know whether its \f(CWresize()\fP method was called, it should be prepared to perform the necessary layout or calculation after making a geometry request, and may choose to do this simply by calling its resize procedure directly. Resize procedures should be written so that they can safely be called more than once in a row. .LP The \f(CWresize()\fP method is not chained. A widget class can inherit the \f(CWresize()\fP method of its superclass by specifying \f(CWXtInheritResize\fP in the \f(CWresize\fP field of the RectObj or Core class part structure. A widget that needs do no computation when resized can set this field to \f(CWNULL\fP. .\" .SH "Usage" Very simple widgets may check their size and compute how to draw themselves every time their \f(CWexpose()\fP procedure is called. A widget that does this does not need a \f(CWresize()\fP method and can specify \f(CWNULL\fP. Most widgets however, do some pre-computation so that they can more efficiently redraw themselves. The Xaw Label widget, for example, computes the starting position of the text it draws based on the size of the window, the size of the text, the margins, and the value of the \f(CWXtNjustify\fP resource. This pre-computed value is valid until the window size, the label, the font, the margins, or the justification changes. Label's \f(CWresize()\fP method calls an internal procedure to perform these calculations. This procedure is also called from the \f(CWset_values()\fP method. .LP Many composite widgets must recompute the layout of their children when they are resized. This may involve moving or resizing the children widgets. Composite widgets will often call an internal layout procedure from their \f(CWresize()\fP method, and will call the same procedure from their \f(CWchange_managed()\fP method and perhaps also their \f(CWgeometry_manager()\fP method. .\" .SH "Example" The following procedures are the \f(CWresize()\fP methods of the Xaw Clock and Porthole widgets. The first pre-computes a number of values used to draw the clock at a given size, and the second ensures that the child of the Porthole is at least as large as the Porthole itself. Note that the Clock \f(CWresize()\fP method is optimized only to do the resize calculations if the widget is realized. In order to do this, though, it must call this procedure from its \f(CWrealize()\fP method. The Xaw Mailbox widget, which simply displays a pixmap, is so simple that it does not need a \f(CWresize()\fP method. The Xaw Form and Box widgets are examples of composite widgets that must perform some sophisticated layout computations when they are resized. .Ps static void Resize (gw) Widget gw; { ClockWidget w = (ClockWidget) gw; /* don't do this computation if window hasn't been realized yet. */ if (XtIsRealized(gw) && w->clock.analog) { /* need signed value since Dimension is unsigned */ int radius = ((int) min(w->core.width, w->core.height) - (int) (2 * w->clock.padding)) / 2; w->clock.radius = (Dimension) max (radius, 1); w->clock.second_hand_length = (int)(SECOND_HAND_FRACT * w->clock.radius) / 100; w->clock.minute_hand_length = (int)(MINUTE_HAND_FRACT * w->clock.radius) / 100; w->clock.hour_hand_length = (int)(HOUR_HAND_FRACT * w->clock.radius) / 100; w->clock.hand_width = (int)(HAND_WIDTH_FRACT * w->clock.radius) / 100; w->clock.second_hand_width = (int)(SECOND_WIDTH_FRACT * w->clock.radius) / 100; w->clock.centerX = w->core.width / 2; w->clock.centerY = w->core.height / 2; } } static void Resize (gw) Widget gw; { PortholeWidget pw = (PortholeWidget) gw; Widget child = find_child (pw); /* * If we have a child, we need to make sure that it is * at least as big as we are and in the right place. */ if (child) { Position x, y; Dimension width, height; layout_child (pw, child, NULL, &x, &y, &width, &height); XtConfigureWidget (child, x, y, width, height, (Dimension) 0); } SendReport (pw, (unsigned int) (XawPRCanvasWidth XawPRCanvasHeight)); } .Pe .\" .SH "See Also" .na .br \s-1\fIXtConfigureWidget\fR\s+1\*(s1, \s-1\fIXtResizeWidget\fR\s+1\*(s1, .br \s-1\fICore\fR\s+1\*(s3. .ad .\"last line comment .\" $Header: resolver.3n,v 74.1 95/05/10 21:11:16 ssa Exp $ .TA r .TH resolver 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME res_query(\|), res_search(\|), res_mkquery(\|), res_send(\|), res_init(\|), dn_comp(\|), dn_expand(\|), herror(\|) \- resolver routines .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .C "#include " .PP .C "int res_query(" .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_search( .C " char *dname," .C " int class," .C " int type," .C " u_char *answer," .C " int anslen" .C ); .PP .C int res_mkquery( .C " int op," .C " char *dname," .C " int class," .C " int type," .C " char *data," .C " int datalen," .C " struct rrec *newrr," .C " char *buf," .C " int buflen" .C ); .PP .C "int res_send( .C " char *msg," .C " int msglen," .C " char *answer, .C " int anslen .C ); .PP .C void res_init(); .PP .C int dn_comp( .C " char *exp_dn," .C " char *comp_dn," .C " int length," .C " char **dnptrs," .C " char **lastdnptr" .C ); .PP .C int dn_expand( .C " char *msg," .C " char *eomorig," .C " char *comp_dn," .C " char exp_dn," .C " int length" .C ); .PP .C extern int h_errno; .PP .C void herror(char *s); .PP .SH DESCRIPTION These routines are used for making, sending, and interpreting query and reply messages with Internet domain name servers. .PP Global configuration and state information used by the resolver routines are kept in the structure .CR _res and are defined in .RC < resolv.h >. Most of the fields have reasonable defaults and can be ignored. The resolver options are stored in the .CR _res.options field and are listed below. The options are stored as a simple bit mask containing the bitwise OR of the options enabled. .RS .TP 20 .C RES_INIT True if the initial name server address and default domain name are initialized (i.e., .C res_init() has been called). .TP .C RES_DEBUG Print debugging messages. .TP .C RES_AAONLY Accept authoritative answers only. With this option, .C res_send() should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. .TP .C RES_PRIMARY Query the primary server only. Currently this is not implemented. .TP .C RES_USEVC Use TCP connections for queries instead of UDP datagrams. .TP .C RES_STAYOPEN Used with .C RES_USEVC to keep the TCP connection open between queries. This is useful only in programs that regularly do many queries. UDP should be the normal mode used. .TP .C RES_IGNTC The name server will set the truncation bit if all of the data does not fit into the response datagram packet. If .C RES_IGNTC is set, .C res_send() will not retry the query with TCP (i.e., ignore truncation errors). .TP .C RES_RECURSE Set the recursion-desired bit in queries. This is the default. (\c .C res_send() does not do iterative queries and expects the name server to handle recursion.) .TP .C RES_DEFNAMES If set, .C res_search() appends the default domain name to single-component names (those that do not contain a dot). This option is enabled by default. .TP .C RES_DNSRCH If this option is set, .C res_search() searches for host names in the current domain and in parent domains; see .IR hostname (5). This is used by the standard host lookup routine .C gethostbyname() (see .IR gethostbyname (3N)). This option is enabled by default. .RE .PP Initialization of the resolver structure normally occurs on the first call to one of the resolver routines below. If there are errors in the configuration file, they are silently ignored. .RE .SS Primary Routines .TP 20 .C res_init() Reads the configuration file, .CR /etc/resolv.conf , to get the default domain name, search list, and the Internet address of the local name server(s). If no server is configured, the host running the resolver is tried. The current domain name is defined by the hostname if not specified in the configuration file; it can be overridden by the environment variable .CR LOCALDOMAIN . This environment variable may contain several blank separated tokens and overrides the search list on a per process basis. This is similar to the .CR search command in the configuration file. Another environment variable ( .CR RES_OPTIONS ) can be set to override certain internal resolver options which are set by calling some of the configuration routines above, or by using the configuration file's .CR options command. The syntax of the .CR RES_OPTIONS environment variable is explained in .IR resolver(4). .TP .C res_query() Provides an interface to the server query mechanism. It constructs a query, sends it to the local server, awaits a response, and makes preliminary checks on the reply. The query requests information of the specified .I type and .I class for the specified fully-qualified domain name .IR dname . The reply message is left in the .I answer buffer with length .I anslen supplied by the caller. .TP .C res_search() Makes a query and awaits a response much like .CR res_query() , but in addition, it implements the default and search rules controlled by the .C RES_DEFNAMES and .C RES_DNSRCH options. It returns the first successful reply. .SS Other Routines Routines described here are lower-level routines used by .CR res_query() . .TP 20 .C res_mkquery() Constructs a standard query message and places it in .IR buf . It returns the size of the query, or \(mi1 if the query is larger than .IR buflen . The query type .I op is usually .CR QUERY , but can be any of the query types defined in .RC < arpa/nameser.h >. The domain name for the query is given by .IR dname . .I class can be any of the query classes defined in .RC < arpa/nameser.h >. .I type can be any of the query types defined in .RC < arpa/nameser.h >. .I data is the data for an inverse query .RC ( IQUERY ). .I newrr is currently unused but is intended for making update messages. .TP .C res_send() Sends a pre-formatted query and returns an answer. It calls .C res_init() if .C RES_INIT is not set, sends the query to the local name server, and handles timeouts and retries. .C res_send() returns the length of the reply message, or \(mi1 if there were errors. .TP .C dn_comp() Compresses the domain name .I exp_dn and stores it in .IR comp_dn . The size of the compressed name is returned or \(mi1 if there were errors. .I length is the size of the array pointed to by .IR comp_dn . The compression uses an array of pointers .I dnptrs to previously compressed names in the current message. The first pointer points to to the beginning of the message and the list ends with NULL. The limit to the array is specified by .IR lastdnptr . A side effect of .C dn_comp() is to update the list of pointers for labels inserted into the message as the name is compressed. If .I dnptr is NULL, names are not compressed. If .I lastdnptr is NULL, the list of labels is not updated. .TP .C dn_expand() Expands the compressed domain name .I comp_dn to a full domain name. The compressed name is contained in a query or reply message; .I msg is a pointer to the beginning of the message. The uncompressed name is placed in the buffer indicated by .I exp_dn which is of size .IR length . The size of compressed name is returned or \(mi1 if there was an error. .SH RETURN VALUE Error return status from .C res_search() is indicated by a return value of \(mi1. The external integer .C h_errno can then be checked to see whether this is a temporary failure or an invalid or unknown host. The routine .C herror() can be used to print an error message describing the failure. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. .SH ERRORS .C h_errno can have the following values: .RS .TP 20 .C HOST_NOT_FOUND No such host is known. .TP .C TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .C NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. .TP .C NO_DATA The name is known to the name server, but there is no data of the requested type associated with this name; this is not a temporary error. Another type of request to the name server using this domain name will result in an answer. .RE .SH AUTHOR These resolver routines were developed by the University of California, Berkeley. .SH FILES .TP 30 .C /etc/resolv.conf Resolver configuration file. .SH SEE ALSO named(1m), gethostent(3N), resolver(4), hostname(5), RFC1034, RFC1035, RFC1535. .\" .\" index@\f4res_mkquery\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_query\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_search\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_send\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4res_init\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_comp\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1resolver routines@@@\f3resolver(3N)\f1 .\" index@\f1routines, resolver@@@\f3resolver(3N)\f1 .\" .\" toc@\f3resolver(3N)\f1:\0\0\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \f4dn_comp\f1, \f4dn_expand\f1, \n\f4herror\f1,\f1@@@resolver routines .\" toc@\f4res_init\f1, \f4res_mkquery\f1, \f4res_query\f1, \f4res_search\f1, \f4res_send\f1, \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4dn_comp\f1, \f4dn_expand\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" toc@\f4herror\f1 \- resolver routines@@@\f3resolver(3N)\f1 .\" .\" links@resolver.3n res_mkquery.3n .\" links@resolver.3n res_query.3n .\" links@resolver.3n res_search.3n .\" links@resolver.3n res_send.3n .\" links@resolver.3n res_init.3n .\" links@resolver.3n dn_comp.3n .\" links@resolver.3n dn_expand.3n .\" links@resolver.3n herror.3n .\" .\" fileset_database@resolver.3n INETSVCS-MAN .\" $Header: del_curterm.3x,v 76.2 95/07/31 11:24:20 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH del_curterm 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME del_curterm, restartterm, set_curterm, setupterm \(em interfaces to the \f3terminfo\f1 database .SH SYNOPSIS .C "#include " .P .C "int del_curterm(TERMINAL *\f2oterm\f4);" .P .C "int restartterm(char *\f2term\f4, int \f2fildes\f4, int *\f2errret\f4);" .P .C "TERMINAL *set_curterm(TERMINAL *\f2nterm\f4);" .P .C "int setupterm(char *\f2term\f4, int \f2fildes\f4, int *\f2errret\f4);" .P .C "extern TERMINAL *cur_term;" .SH DESCRIPTION These functions retrieve information from the \f3terminfo\f1 database. .P To gain access to the \f3terminfo\f1 database, .Fn setupterm must be called first. It is automatically called by .Fn initscr and .Fn newterm . The .Fn setupterm function initializes the other functions to use the \f3terminfo\f1 record for a specified terminal (which depends on whether .Fn use_env was called). It sets the .I cur_term external variable to a \f3TERMINAL\f1 structure that contains the record from the \f3terminfo\f1 database for the specified terminal. .P The terminal type is the character string \f2term;\f1 if \f2term\f1 is a null pointer, the environment variable TERM is used. If TERM is not set or if its value is an empty string, then \f4"unknown"\f1 is used as the terminal type. The application must set \f2fildes\f1 to a file descriptor, open for output, to the terminal device, before calling .Fn setupterm . If \f2errret\f1 is not null, the integer it points to is set to one of the following values to report the function outcome: .PP .RS .TP 10 .CR \(mi1 The \f3terminfo\f1 database was not found (function fails). .TP .CR 0 The entry for the terminal was not found in \f3terminfo\f1 (function fails). .TP .CR 1 Success. .PP .RE If .Fn setupterm detects an error and \f2errret\f1 is a null pointer, .Fn setupterm writes a diagnostic message and exits. .P A simple call to .Fn setupterm that uses all the defaults and sends the output to \f2stdout\f1 is: .\" .Cs I .IP setupterm((char *)0, fileno(stdout), (int *)0); .\" .Ce .PP The .Fn set_curterm function sets the variable \f2cur_term\f1 to \f2nterm\f1, and makes all of the \f3terminfo\f1 boolean, numeric, and string variables use the values from \f2nterm.\f1 .P The .Fn del_curterm function frees the space pointed to by \f2oterm\f1 and makes it available for further use. If \f2oterm\f1 is the same as \f2cur_term\f1, references to any of the \f3terminfo\f1 boolean, numeric, and string variables thereafter may refer to invalid memory locations until .Fn setupterm is called again. .P The .Fn restartterm function assumes a previous call to .Fn setupterm (perhaps from .Fn initscr or .Fn newterm ). It lets the application specify a different terminal type in \f2term\f1 and updates the information returned by .Fn baudrate based on \f2fildes\f1, but does not destroy other information created by .Fn initscr , .Fn newterm or .Fn setupterm . .SH "RETURN VALUE" Upon successful completion, .Fn set_curterm returns the previous value of \f2cur_term\f1. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" An application would call .Fn setupterm if it required access to the \f3terminfo\f1 database but did not otherwise need to use Curses. .SH "SEE ALSO" \f3Selecting a Terminal\f1 in terminfo(4), baudrate(), erasechar(), has_ic(), longname(), putc(), termattrs(), termname(), tgetent(), tigetflag(), use_env(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3del_curterm(3x)\f1:\0\0\f4del_curterm()\f1, \f4restartterm()\f1, \f4set_curterm()\f1,\n\f4setupterm()\f1@@@interfaces to terminfo database .\" .\" toc@\f4del_curterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" toc@\f4restartterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" toc@\f4set_curterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" toc@\f4setupterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" .\" index@\f4del_curterm()\f1, \f4restartterm()\f1, \f4set_curterm()\f1, \f4setupterm()\f1 \- interfaces to \nterminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f4restartterm()\f1 \- interface to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f4set_curterm()\f1 \- interface to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f4setupterm()\f1 \- interface to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f1interfaces to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f1terminfo database, interfaces@@@\f3del_curterm(3x)\f1 .\" .\" links@del_curterm.3x restartterm.3x .\" links@del_curterm.3x set_curterm.3x .\" links@del_curterm.3x setupterm.3x .\" .\" fileset_database@del_curtem.3x CURS-ENG-A-MAN .\" .\" $Header: fseek.3s,v 78.1 96/02/12 13:47:11 ssa Exp $ .TA f .TH fseek 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fseek(\|), fseeko(\|), fseek_unlocked(\|), rewind(\|), rewind_unlocked(\|), ftell(\|), ftello(\|), ftell_unlocked(\|) \- reposition a file pointer in a stream .SH SYNOPSIS .C "#include " .PP .C "int\0fseek(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "int\0fseeko(FILE\0*stream,\0off_t\0offset,\0int\0whence);" .PP .C "int\0fseek_unlocked(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "void\0rewind(FILE\0*stream);" .PP .C "void\0rewind_unlocked(FILE\0*stream);" .PP .C "long\0int\0ftell(FILE\0*stream);" .PP .C "off_t\0ftello(FILE\0*stream);" .PP .C "long\0int\0ftell_unlocked(FILE\0*stream);" .SH DESCRIPTION .CR fseek() sets the file-position indicator for .IR stream . The new position, measured in bytes from the beginning of the file, is obtained by adding .I offset to the position specified by .IR whence . The specified position is the beginning of the file for .CR SEEK_SET , the current position for .CR SEEK_CUR , or end-of-file for .CR SEEK_END . .PP .CR fseeko() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR fseek() except that the .IR offset parameter is an .CR off_t instead of a .CR "long int" . All other functional behaviors, returns, and errors are identical to the POSIX .CR fseek() . .PP If the most recent operation, other than .CR ftell() , on the .IR stream is .IR fflush() , the file offset in the underlying open file description is adjusted to reflect the location specified by the .CR fseek() . .PP .CI rewind( stream ) is equivalent to .CR "fseek (stream, 0L, SEEK_SET)" , except that no value is returned. .PP .CR fseek() and .CR rewind() undo any effects of .IR ungetc (3S). .PP After .CR fseek() or .CR rewind() , the next operation on a file opened for update can be either input or output. .CR fseek() clears the .SM EOF indicator for the .IR stream . .CR rewind() does an implicit .CR clearerr() call (see .IR ferror (3S)). .PP .CR ftell() returns the offset of the current byte relative to the beginning of the file associated with the named .IR stream . .PP .CR ftello() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR ftell() except that it returns an .CR off_t instead of a .CR "long int" . All other behaviors, returns, and errors are identical to the POSIX .CR ftell() . .PP .CR fseek_unlocked() , .CR rewind_unlocked() , and .CR ftell_unlocked() are identical to .CR fseek() , .CR rewind() , and .CR ftell() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE .CR fseek() and .CR fseek_unlocked() return zero if they succeed. Otherwise they return \(mi1 and set .CR errno to indicate the error. .PP .CR ftell() and .CR ftell_unlocked() return the current value of the file position indicator for the stream measured in bytes from the beginning of the file. Otherwise, .CR ftell() and .CR ftell_unlocked() return \(mi1 and set .CR errno to indicate the error. .PP .CR rewind() and .CR rewind_unlocked() do not return any value. Therefore, any application that needs to detect errors should clear .CR errno before calling .CR rewind() or .CR rewind_unlocked() . Then, upon completion, if .CR errno is non-zero, it should assume an error has occurred. .SH ERRORS .CR fseek() , .CR fseeko() , .CR fseek_unlocked() , .CR ftell() , .CR ftello() , .CR ftell_unlocked() , .CR rewind() and .CR rewind_unlocked() fail if the .I stream is unbuffered or the buffered data needs to be flushed, or if any of the following conditions are encountered: .RS .TP 15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor and the process would be delayed in the write operation. .TP .SM [EBADF] The underlying file is not open for writing. .TP .SM [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size. See .IR ulimit (2). .TP .SM [EINVAL] The file .IR offset cannot be represented correctly in an object of type .CR long or size .CR off_t in this environment. .TP .SM [EINTR] A signal was caught during the write operation. .TP .SM [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt was made to write to a pipe that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP .SM [ESPIPE] A seek operation was attempted and the file descriptor underlying .I stream is associated with a pipe. .RE .PP .CR fseek() " and " fseek_unlocked() also fail if: .RS .TP 15 .SM [EINVAL] The .I whence argument is invalid, or the file-position indicator would be set to a negative value. .RE .PP Additional .CR errno values may be set by the underlying .CR write() and .CR lseek() functions (see .IR write (2) and .IR lseek (2)). .SH WARNINGS On .SM HP-UX systems, the offset returned by .CR ftell() " or " ftell_unlocked() is measured in bytes and it is permissible to seek to positions relative to that offset. However, when porting to non-\c .SM HP-UX systems, .CR fseek() should be used directly without relying on any offset obtained from .CR ftell() because arithmetic cannot meaningfully be performed on such an offset if it is not measured in bytes on a particular operating system. .PP .CR fseek() , .CR fseek_unlocked() , .CR rewind() , and .CR rewind_unlocked() have no effect on streams that have been opened in append mode (see .IR fopen (3S)). .SH SEE ALSO lseek(2), write(2), ferror(3S), flockfile(3S), fopen(3S), fgetpos(3S), fseeko64(3S), ftello64(3S), ungetc(3S). .SH STANDARDS CONFORMANCE .CR fseek() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ftell() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR rewind() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fseek\f1, \f4rewind\f1, \f4ftell\f1 \- reposition a file pointer in a stream@@@\f3fseek(3S)\f1 .\" index@\f4fseek\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4rewind\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4ftell\f1 \- get offset from beginning-of-file of current byte in stream file@@@\f3fseek(3S)\f1 .\" index@\f1reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1file, stream: reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1get: pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\f1pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\s-1I/O\s+1 operations on a stream file, get or reposition pointer for@@@\f3fseek(3S)\f1 .\" index@\f1operations on a stream file, get or reposition pointer for \s-1I/O\s+1@@@\f3fseek(3S)\f1 .\" index@\f1stream file, get or reposition pointer for \s-1I/O\s+1 operations on a@@@\f3fseek(3S)\f1 .\" .\" index@\f4fseeko\f1 \- set position of next \s-1I/O\s+1 operation on stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4ftello\f1 \- get offset from beginning-of-file of current byte in stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4fseek_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4rewind_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4ftell_unlocked\f1 \- get offset from beginning-of-file of current byte in stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" .\" toc@\f3fseek(3S)\f1:\0\0\f4fseek\f1, \f4fseeko\f1, \f4fseek_unlocked\f1, \f4rewind\f1, \f4rewind_unlocked\f1, \n\f4ftell\f1, \f4ftello\f1, \f4ftell_unlocked\f1@@@reposition a file pointer in a stream .\" toc@\f4rewind\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4rewind_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseeko\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseek_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftello\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" .\" links@fseek.3s fseek_unloc.3s .\" links@fseek.3s rewind.3s .\" links@fseek.3s rewind_unlo.3s .\" links@fseek.3s ftell.3s .\" links@fseek.3s ftell_unloc.3s .\" links@fseek.3s fseeko.3s .\" links@fseek.3s ftello.3s .\" .\" $Header: fseek.3s,v 78.1 96/02/12 13:47:11 ssa Exp $ .TA f .TH fseek 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fseek(\|), fseeko(\|), fseek_unlocked(\|), rewind(\|), rewind_unlocked(\|), ftell(\|), ftello(\|), ftell_unlocked(\|) \- reposition a file pointer in a stream .SH SYNOPSIS .C "#include " .PP .C "int\0fseek(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "int\0fseeko(FILE\0*stream,\0off_t\0offset,\0int\0whence);" .PP .C "int\0fseek_unlocked(FILE\0*stream,\0long\0int\0offset,\0int\0whence);" .PP .C "void\0rewind(FILE\0*stream);" .PP .C "void\0rewind_unlocked(FILE\0*stream);" .PP .C "long\0int\0ftell(FILE\0*stream);" .PP .C "off_t\0ftello(FILE\0*stream);" .PP .C "long\0int\0ftell_unlocked(FILE\0*stream);" .SH DESCRIPTION .CR fseek() sets the file-position indicator for .IR stream . The new position, measured in bytes from the beginning of the file, is obtained by adding .I offset to the position specified by .IR whence . The specified position is the beginning of the file for .CR SEEK_SET , the current position for .CR SEEK_CUR , or end-of-file for .CR SEEK_END . .PP .CR fseeko() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR fseek() except that the .IR offset parameter is an .CR off_t instead of a .CR "long int" . All other functional behaviors, returns, and errors are identical to the POSIX .CR fseek() . .PP If the most recent operation, other than .CR ftell() , on the .IR stream is .IR fflush() , the file offset in the underlying open file description is adjusted to reflect the location specified by the .CR fseek() . .PP .CI rewind( stream ) is equivalent to .CR "fseek (stream, 0L, SEEK_SET)" , except that no value is returned. .PP .CR fseek() and .CR rewind() undo any effects of .IR ungetc (3S). .PP After .CR fseek() or .CR rewind() , the next operation on a file opened for update can be either input or output. .CR fseek() clears the .SM EOF indicator for the .IR stream . .CR rewind() does an implicit .CR clearerr() call (see .IR ferror (3S)). .PP .CR ftell() returns the offset of the current byte relative to the beginning of the file associated with the named .IR stream . .PP .CR ftello() is a non-POSIX standard API provided by the _LARGEFILE_SOURCE compile option. It is identical to the .CR ftell() except that it returns an .CR off_t instead of a .CR "long int" . All other behaviors, returns, and errors are identical to the POSIX .CR ftell() . .PP .CR fseek_unlocked() , .CR rewind_unlocked() , and .CR ftell_unlocked() are identical to .CR fseek() , .CR rewind() , and .CR ftell() respectively except they do not perform any internal locking of the .I stream for multi-thread applications. The .CR _unlocked routines can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE .CR fseek() and .CR fseek_unlocked() return zero if they succeed. Otherwise they return \(mi1 and set .CR errno to indicate the error. .PP .CR ftell() and .CR ftell_unlocked() return the current value of the file position indicator for the stream measured in bytes from the beginning of the file. Otherwise, .CR ftell() and .CR ftell_unlocked() return \(mi1 and set .CR errno to indicate the error. .PP .CR rewind() and .CR rewind_unlocked() do not return any value. Therefore, any application that needs to detect errors should clear .CR errno before calling .CR rewind() or .CR rewind_unlocked() . Then, upon completion, if .CR errno is non-zero, it should assume an error has occurred. .SH ERRORS .CR fseek() , .CR fseeko() , .CR fseek_unlocked() , .CR ftell() , .CR ftello() , .CR ftell_unlocked() , .CR rewind() and .CR rewind_unlocked() fail if the .I stream is unbuffered or the buffered data needs to be flushed, or if any of the following conditions are encountered: .RS .TP 15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor and the process would be delayed in the write operation. .TP .SM [EBADF] The underlying file is not open for writing. .TP .SM [EFBIG] An attempt was made to write a file that exceeds the process's file size limit or the maximum file size. See .IR ulimit (2). .TP .SM [EINVAL] The file .IR offset cannot be represented correctly in an object of type .CR long or size .CR off_t in this environment. .TP .SM [EINTR] A signal was caught during the write operation. .TP .SM [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP .SM [ENOSPC] There was no free space remaining on the device containing the file. .TP .SM [EPIPE] An attempt was made to write to a pipe that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .TP .SM [ESPIPE] A seek operation was attempted and the file descriptor underlying .I stream is associated with a pipe. .RE .PP .CR fseek() " and " fseek_unlocked() also fail if: .RS .TP 15 .SM [EINVAL] The .I whence argument is invalid, or the file-position indicator would be set to a negative value. .RE .PP Additional .CR errno values may be set by the underlying .CR write() and .CR lseek() functions (see .IR write (2) and .IR lseek (2)). .SH WARNINGS On .SM HP-UX systems, the offset returned by .CR ftell() " or " ftell_unlocked() is measured in bytes and it is permissible to seek to positions relative to that offset. However, when porting to non-\c .SM HP-UX systems, .CR fseek() should be used directly without relying on any offset obtained from .CR ftell() because arithmetic cannot meaningfully be performed on such an offset if it is not measured in bytes on a particular operating system. .PP .CR fseek() , .CR fseek_unlocked() , .CR rewind() , and .CR rewind_unlocked() have no effect on streams that have been opened in append mode (see .IR fopen (3S)). .SH SEE ALSO lseek(2), write(2), ferror(3S), flockfile(3S), fopen(3S), fgetpos(3S), fseeko64(3S), ftello64(3S), ungetc(3S). .SH STANDARDS CONFORMANCE .CR fseek() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR ftell() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR rewind() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4fseek\f1, \f4rewind\f1, \f4ftell\f1 \- reposition a file pointer in a stream@@@\f3fseek(3S)\f1 .\" index@\f4fseek\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4rewind\f1 \- set position of next \s-1I/O\s+1 operation on stream file@@@\f3fseek(3S)\f1 .\" index@\f4ftell\f1 \- get offset from beginning-of-file of current byte in stream file@@@\f3fseek(3S)\f1 .\" index@\f1reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1file, stream: reposition or get pointer for \s-1I/O\s+1 operations on a stream file@@@\f3fseek(3S)\f1 .\" index@\f1get: pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\f1pointer for \s-1I/O\s+1 operations on a stream file, get or reposition@@@\f3fseek(3S)\f1 .\" index@\s-1I/O\s+1 operations on a stream file, get or reposition pointer for@@@\f3fseek(3S)\f1 .\" index@\f1operations on a stream file, get or reposition pointer for \s-1I/O\s+1@@@\f3fseek(3S)\f1 .\" index@\f1stream file, get or reposition pointer for \s-1I/O\s+1 operations on a@@@\f3fseek(3S)\f1 .\" .\" index@\f4fseeko\f1 \- set position of next \s-1I/O\s+1 operation on stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4ftello\f1 \- get offset from beginning-of-file of current byte in stream file, non-POSIX API@@@\f3fseek(3S)\f1 .\" index@\f4fseek_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4rewind_unlocked\f1 \- set position of next \s-1I/O\s+1 operation on stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" index@\f4ftell_unlocked\f1 \- get offset from beginning-of-file of current byte in stream file, \n\f1no locking of stream for multi-thread applications@@@\f3fseek(3S)\f1 .\" .\" toc@\f3fseek(3S)\f1:\0\0\f4fseek\f1, \f4fseeko\f1, \f4fseek_unlocked\f1, \f4rewind\f1, \f4rewind_unlocked\f1, \n\f4ftell\f1, \f4ftello\f1, \f4ftell_unlocked\f1@@@reposition a file pointer in a stream .\" toc@\f4rewind\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4rewind_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseeko\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4fseek_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftello\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" toc@\f4ftell_unlocked\f1:\0\0reposition a file pointer in a stream@@@see \f3fseek(3S)\f1 .\" .\" links@fseek.3s fseek_unloc.3s .\" links@fseek.3s rewind.3s .\" links@fseek.3s rewind_unlo.3s .\" links@fseek.3s ftell.3s .\" links@fseek.3s ftell_unloc.3s .\" links@fseek.3s fseeko.3s .\" links@fseek.3s ftello.3s .\" .\" $Header: directory.3c,v 76.1 95/07/05 17:28:05 ssa Exp $ .TA d .TH directory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME opendir(\|), readdir(\|), readdir_r(\|), telldir(\|), seekdir(\|), rewinddir(\|), closedir(\|) \- directory operations .SH SYNOPSIS .C "#include " .PP .C "DIR *opendir(const char *dirname);" .PP .C "struct dirent *readdir(DIR *dirp);" .PP .C "int readdir_r(DIR *dirp, struct dirent *result);" .PP .C "long int telldir(DIR *dirp);" .PP .C "void seekdir(DIR *dirp, long int loc);" .PP .C "void rewinddir(DIR *dirp);" .PP .C "int closedir(DIR *dirp);" .SH DESCRIPTION This library package provides functions that allow programs to read directory entries without having to know the actual directory format associated with the file system. Because these functions allow programs to be used portably on file systems with different directory formats, this is the recommended way to read directory entries. .TP 15 .CR opendir() opens the directory .I dirname and associates a directory stream with it. .CR opendir() returns a pointer used to identify the directory stream in subsequent operations. .CR opendir() uses .IR malloc (3C) to allocate memory. .TP .CR readdir() returns a pointer to the next directory entry. It returns a .SM NULL pointer upon reaching the end of the directory or detecting an invalid .CR seekdir() operation. See .IR dirent (5) for a description of the fields available in a directory entry. .TP .CR readdir_r() expects to be passed the address of a .CR "struct dirent" and will store the result at the supplied location. .TP .CR telldir() returns the current location (encoded) associated with the directory stream to which .IR dirp refers. .TP .CR seekdir() sets the position of the next .CR readdir() operation on the directory stream to which .IR dirp refers. The .IR loc argument is a location within the directory stream obtained from .CR telldir() . The position of the directory stream is restored to where it was when .CR telldir() returned that .I loc value. Values returned by .CR telldir() are valid only while the .CR DIR pointer from which they are derived remains open. If the directory stream is closed and then reopened, the .CR telldir() value might be invalid. .TP .CR rewinddir() resets the position of the directory stream to which .IR dirp refers to the beginning of the directory. It also causes the directory stream to refer to the current state of the corresponding directory, as a call to .CR opendir() would have done. .TP .CR closedir() closes the named directory stream, then frees the structure associated with the .CR DIR pointer. .SH RETURN VALUE .TP 15 .CR opendir() , upon successful completion, returns a pointer to an object of type .CR DIR referring to an open directory stream. Otherwise, it returns a .SM NULL pointer and sets the global variable .CR errno to indicate the error. .TP .CR readdir() , upon successful completion, returns a pointer to an object of type .CR struct dirent describing a directory entry. Upon reaching the end of the directory, .CR readdir() returns a .SM NULL pointer and does not change the value of .CR errno . Otherwise, it returns a .SM NULL pointer and sets .CR errno to indicate the error. .TP .CR readdir_r() , upon successful completion, returns a 0. Upon reaching the end of directory or encountering an error, it returns a -1 and sets .CR errno to indicate the error. .TP .CR telldir() , upon successful completion, returns a long value indicating the current position in the directory. Otherwise it returns .CR \-1 and sets .CR errno to indicate the error. .TP .CR seekdir() does not return any value, but if an error is encountered, .CR errno is set to indicate the error. .TP .CR closedir() , upon successful completion, returns a value of .CR 0 . Otherwise, it returns a value of .CR \-1 and sets .CR errno to indicate the error. .SH ERRORS .CR opendir() fails if any of the following conditions are encountered: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of .IR dirname , or read permission is denied for .IR dirname . .TP .SM [EFAULT] .I dirname points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the path name. .TP .SM [EMFILE] Too many open file descriptors are currently open for the calling process. .TP .SM [ENAMETOOLONG] A component of .IR dirname exceeds .CR PATH_MAX bytes, or the entire length of .IR dirname exceeds .CR PATH_MAX \(mi 1 bytes while .CR _POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] Too many open file descriptors are currently open on the system. .TP .SM [ENOENT] A component of .I dirname does not exist. .TP .SM [ENOMEM] .CR malloc() failed to provide sufficient memory to process the directory. .TP .SM [ENOTDIR] A component of .I dirname is not a directory. .TP .SM [ENOENT] The .IR dirname argument points to an empty string. .RE .PP .CR readdir() " or " readdir_r() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] The directory stream to which .IR dirp refers is not located at a valid directory entry. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR telldir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR seekdir() might fail if the following condition is encountered: .RS .TP 20 .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR closedir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP 20 .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR rewinddir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .SH EXAMPLES The following code searches the current directory for an entry .IR name : .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 DIR *dirp; struct dirent *dp; dirp = opendir("."); while ((dp = readdir(dirp)) != NULL) { if (strcmp(dp->d_name, name) == 0) { (void) closedir(dirp); return FOUND; } } (void) closedir(dirp); return NOT_FOUND; .ft .ps .fi .RE .SH WARNINGS .CR readdir() and .CR getdirentries() (see .IR getdirentries (2) are the only ways to access remote .SM NFS directories. Attempting to read a remote directory via .SM NFS by using .CR read() returns .CR \-1 and sets .CR errno to .SM EISDIR (see .IR read (2)). .PP .CR readdir() is unsafe in multi-thread applications. .CR readdir_r() is MT-Safe and should be used instead. Users of .CR readdir_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH APPLICATION USAGE The header file required for these functions and the type of the return value from .CR readdir() has been changed for compatibility with System V Release 3 and the .IR "X/Open Portability Guide" . See .IR ndir (5) for a description of the header file .RC < ndir.h >, which is provided to allow existing .SM HP-UX applications to compile unmodified. .PP New applications should use the .RC < dirent.h > header file for portability to System V and X/Open systems. .SH AUTHOR .CR directory was developed by AT&T, HP, and the University of California, Berkeley. .SH SEE ALSO close(2), getdirentries(2), lseek(2), open(2), read(2), dir(4), dirent(5), ndir(5). .SH STANDARDS CONFORMANCE .CR closedir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR opendir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR readdir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR rewinddir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR seekdir() ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR telldir() ": AES, XPG2, XPG3, XPG4" .\" .\" index@\f4opendir()\f1 \- open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f4readdir()\f1 \- get pointer to current entry in open directory@@@\f3directory(3C)\f1 .\" index@\f4telldir()\f1 \- get current location of named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4seekdir()\f1 \- set position of next \f4readdir()\f1 operation on named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4rewinddir()\f1 \- reset position of named \f2directory stream\f1 to beginning of directory@@@\f3directory(3C)\f1 .\" index@\f4closedir()\f1 \- close a currently open directory@@@\f3directory(3C)\f1 .\" index@open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f2directory stream\f1, directory and associated, open for access@@@\f3directory(3C)\f1 .\" index@open, access, or close a directory@@@\f3directory(3C)\f1 .\" index@close, access, or open a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@directory: access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" .\" toc@\f3directory(3C)\f1:\0\0\f4directory()\f1, \f4opendir()\f1, \f4readdir()\f1, \f4telldir()\f1, \f4seekdir()\f1, \f4rewinddir()\f1,\n\f4closedir()\f1@@@directory operations .\" toc@\f4opendir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4readdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4telldir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4seekdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4rewinddir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4closedir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" .\" links@directory.3c opendir.3c .\" links@directory.3c readdir.3c .\" links@directory.3c readdir_r.3c .\" links@directory.3c telldir.3c .\" links@directory.3c seekdir.3c .\" links@directory.3c rewinddir.3c .\" links@directory.3c closedir.3c .\" $Header: rexec.3n,v 72.5 94/12/09 15:06:07 ssa Exp $ .TA r .TH rexec 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rexec() \- return stream to a remote command .SH SYNOPSIS .nf .C "int rexec(char **ahost," .C " int inport," .C " const char *user," .C " const char *passwd," .C " const char *cmd," .C " int *fd2p);" .fi .SH DESCRIPTION The .CR rexec() routine performs the necessary tasks to arrange for the remote execution of .I cmd on the remote host .CI * ahost as .IR user , who is authenticated with .IR passwd . Upon completion of authentication, a file descriptor is returned for the socket to which standard input and standard output of .I cmd are attached. A command-level interface to .CR rexec() is provided by the .CR rexec command (see .IR remsh (1)). .PP When invoked, .CR rexec() looks up host .CI * ahost using .CR gethostbyname() (see .IR gethostent (3N)) and returns \(mi1 if the host does not exist. The host name can be either the official name or an alias. If the .CR gethostbyname() call succeeds, .CI * ahost is set to the standard name of the host. Next, .CR rexec() passes a user name and password to the remote host for authentication, as specified in the .I user and .I passwd parameters to .CR rexec() . If either .I user or .I passwd are NULL, .CR rexec() searches for the appropriate information in the .CR .netrc file (see .IR netrc (4)) in the user's home directory. If no .I user or .I passwd are found, .CR rexec() prompts the user for the remote user name and password, defaulting to the local user name and a NULL password. .PP The .I inport variable specifies which TCP port to use for the connection; it is normally the value returned by the following call to .IR getservbyname(3N) : .IP .C "getservbyname(""exec"", ""tcp"")" .PP (see .IR getservent (3N)). The protocol used by .CR rexec() is described in detail in .IR rexecd (1M). .PP If the call succeeds, a socket of type .CR SOCK_STREAM is returned to the caller, and given to the remote command as .CR stdin and .CR stdout . If connection to a socket is denied after five tries, or for some other reason (other than the port is in use), .CR rexec() returns \(mi1. If .I fd2p is non-zero, an auxiliary connection to a control process is set up and a file descriptor for it is placed in .CI * fd2p\f1. The control process returns diagnostic output from the command on this connection and accepts bytes on this connection, interpreting them as UNIX signal numbers to be forwarded to the process group of the command. If the auxiliary port cannot be set up, .CR rexec() returns \(mi1. If .I fd2p is 0, .CR stderr of the remote command is made the same as .CR stdout and no provision is made for sending arbitrary signals to the remote process. .SH DIAGNOSTICS When invoked, .CR rexec() produces the following diagnostic messages: .PP .IC hostname ": Unknown host" .IP The remote host name was not found by .CR gethostbyname() . .PP .IC "system call" : " message" .IP Error in executing the .IR "system call" . The .IR message specifies the cause of the failure. .PP .CI "connect: " hostname ": " message .IP Error in connecting to the socket obtained for .CR rexec() . The .IR message specifies the cause of the failure. .PP .CI "Secondary socket: " message .IP Error in creating a secondary socket for error transmission to be used by .CR rexec() . .PP .CI "read: " hostname ": " message .IP Error in reading information transmitted over the socket. The .IR message specifies the cause of the failure. .PP .C "Connection timeout" .IP The remote host did not connect within 30 seconds to the secondary socket set up as an error connection. .PP .C "Lost connection" .IP The program attempts to read from the socket and fails. This means the socket connection with the remote host was lost. .PP .CI ".netrc: " message .IP Error in opening .CR .netrc file in the home directory for a reason other than the file not existing. .PP .C "Error - .netrc file not correct mode." .C "Remove password or correct mode." .IP The .CR .netrc file is readable, writable or executable by someone other than the owner. .IP .IR "Next step" : Check whether .CR .netrc has been modified by someone else and change the mode of .CR .netrc .RC ( "chmod 400 .netrc" ). .PP .CI "Unknown .netrc option " keyword .IP An unrecognized keyword has been found in .CR .netrc (see .IR netrc (4)). .IP .IR "Next step" : Correct the keyword in .CR .netrc . .PP .C "primary connection shutdown" .IP While waiting for the secondary socket to be set up, .CR rexec() had its primary connection shut down. This may have been caused by an .CR inetd security failure (see .CR inetd (1M)). .PP .CI "recv: " message .IP While trying to set up the secondary .RC ( stderr ) socket, .CR rexec() had an error condition on its primary connection. .PP .C "accept: Interrupted system call" .IP While trying to set up a secondary socket, .CR rexec() ran out of a resource, which caused the accept to time out. .IP .IR "Next step" : Repeat the command. If a timeout occurs, check whether the Internet Services are installed and .CR inetd is running. .SH EXAMPLE To execute the .CR date command on remote host .CR hpxzgy using the remote account .CR chm , .CR rexec() is invoked as follows: .RS .PP .nf .C "#include " .C "#include " .C "#include " .C "#include " .C "#include " .C "#include " .PP .C "char *host[] = { ""hpxzgy"" };" .C "char *user = ""chm"";" .C "char *passwd = ""password"";" .C "char *cmd = ""date"";" .PP .C "main(argc, argv)" .C " char **argv;" .C " int argc;" .C "{" .C " char ch;" .C " struct servent *servent;" .C " FILE *fp;" .C " int sd;" .PP .C " servent = getservbyname(""exec"", ""tcp"");" .C " sd = rexec(host, servent\->s_port, user, passwd, cmd, 0);" .C " fp = fdopen(sd, ""r"");" .C " while ((ch = getc(fp)) != EOF)" .C " putchar(ch);" .C "}" .fi .RE .SH WARNINGS There is no way to specify options to the .CR socket() call that .CR rexec() makes. .PP A program using .CR rexec() should not be put in the background when .CR rexec() is expected to prompt for a password or user name. Putting .CR rexec() in the background will cause it to compete with the current shell process for input. .PP Since .CR rexec() replaces the pointer to the host name .RC ( * \f2ahost\f1) with a pointer to the standard name of the host in a static data area, this value must be copied into the user's data area if it is to be used later. .PP The password is sent unencrypted through the socket connection. .SH AUTHOR .CR rexec() was developed by the University of California, Berkeley. .SH SEE ALSO remsh(1), inetd(1M), rexecd(1M), gethostent(3N), getservent(3N), rcmd(3N), netrc(4). .\" .\" index@\f4rexec()\f1 \- return stream to a remote command@@@\f3rexec(3N)\f1 .\" index@command, return stream to a remote@@@\f3rexec(3N)\f1 .\" index@remote command, return stream to a@@@\f3rexec(3N)\f1 .\" index@return stream to a remote command@@@\f3rexec(3N)\f1 .\" index@stream, return to a remote command@@@\f3rexec(3N)\f1 .\" .\" toc@\f3rexec(3N)\f1:\0\0\f4rexec()\f1@@@return stream to a remote command .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: rint.3m,v 78.1 96/02/13 13:44:05 ssa Exp $ .TA r .TH rint 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rint(\|) \- round-to-nearest function .SH SYNOPSIS .C "#include " .PP .C "double rint(double x);" .SH DESCRIPTION .CR rint() returns the integer (represented as a double precision number) nearest .IR x in the direction of the current rounding mode. .PP In the default rounding mode (round to nearest), .CI rint( x ) is the integer nearest .IR x with the additional stipulation that if |\c .CI rint( x )\c .RI \|\(mi\| x |=1/2, then .CI rint( x ) is even. .PP If the current rounding mode rounds toward negative infinity, .CR rint() is identical to .CR floor() . If the current rounding mode rounds toward positive infinity, .CR rint() is identical to .CR ceil() . .PP Another way to obtain an integer near .IR x is to declare (in C): .IP .C "double x; int k; k = x;" .PP The HP C compiler rounds .CR x toward 0 to get the integer .CR k . Note that if .CR x is larger than .CR k can accommodate, the value of .CR k and the presence or absence of an integer overflow are hard to predict. .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .IR x .ift is \(+-INFINITY, the .ifn is +\-INFINITY, the .CR rint() .ift function returns \(+-INFINITY respectively. .ifn function returns +\-INFINITY respectively. .PP If .IR x is NaN, the .CR rint() function returns NaN. .SH ERRORS No errors are defined. .RE .SH SEE ALSO floor(3M), ceil(3M), fmod(3M), fabs(3M), fpgetround(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR rint() ": XPG4.2" .\" .\" index@\f4rint()\f1 \- round-to-nearest function@@@\f3rint(3M)\f1 .\" index@\f1math: round-to-nearest function@@@\f3rint(3M)\f1 .\" index@\f1round-to-nearest function@@@\f3rint(3M)\f1 .\" .\" toc@\f3rint(3M)\f1:\0\0\f4rint()\f1@@@round-to-nearest function .\" .\" fileset_database@rint.3m PROGRAMING-MAN .\" $Header: ripoffline.3x,v 76.2 95/08/01 14:39:37 ssa Exp $ .TA r .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ripoffline 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ripoffline \(em reserve a line for a dedicated purpose .SH SYNOPSIS .C "#include " .P .C "int ripoffline(int \f2line\fP, int (*\f2init\fP)(WINDOW *\f2win\fP, int \f2columns\fP));" .SH DESCRIPTION The .Fn ripoffline function reserves a screen line for use by the application. .P Any call to .Fn ripoffline must precede the call to .Fn initscr or .CR newterm() . If \f2line\f1 is positive, one line is removed from the beginning of .I stdscr ; if \f2line\f1 is negative, one line is removed from the end. Removal occurs during the subsequent call to .Fn initscr or .CR newterm() . When the subsequent call is made, the function pointed to by \f2init\f1 is called with two arguments: a \f3WINDOW\f1 pointer to the one-line window that has been allocated and an integer with the number of columns in the window. The initialisation function cannot use the .B LINES and .B COLS external variables and cannot call .Fn wrefresh or .CR doupdate() , but may call .CR wnoutrefresh() . .P Up to five lines can be ripped off. Calls to .Fn ripoffline above this limit have no effect but report success. .SH "RETURN VALUE" The .Fn ripoffline function returns OK. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Calling .Fn slk_init reduces the size of the screen by one line if .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels. If .Fn slk_init rips off a line, it thereby reduces by one the number of lines an application can reserve by subsequent calls to .CR ripoffline() . Thus, portable applications that use soft label functions should not call .Fn ripoffline more than four times. .P When .Fn initscr or .Fn newterm calls the initialisation function pointed to by .I init , the implementation may pass NULL for the .B WINDOW pointer argument .I win . This indicates inability to allocate a one-line window for the line that the call to .Fn ripoffline ripped off. Portable applications should verify that .I win is not NULL before performing any operation on the window it represents. .SH "SEE ALSO" doupdate(), initscr(), slk_attroff(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4ripoffline()\f1 \- reserve a line for a dedicated purpose@@@\f3ripoffline(3X)\f1 .\" index@\f1reserve a line for a dedicated purpose@@@\f3ripoffline(3X)\f1 .\" index@\f1dedicated line, reserve for a purpose@@@\f3ripoffline(3X)\f1 .\" index@\f1line, dedicated, reserve for a purpose@@@\f3ripoffline(3X)\f1 .\" .\" toc@\f3ripoffline(3X)\f1:\0\0\f4ripoffline()\f1@@@reserve a dedicated line for a purpose .\" .\" fileset_database@ripoffline.3x CURS-ENG-A-MAN .\" $Header: rmtimer.3c,v 72.5 94/11/15 09:56:07 ssa Exp $ .TA r .TH rmtimer 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rmtimer \- free a per-process timer .SH SYNOPSIS .C "#include " .PP .C "int rmtimer(timer_t timerid);" .SH DESCRIPTION The .CR rmtimer() function is used to free a previously allocated timer (returned by .CR mktimer() . Any pending timer event to be generated by this timer has been canceled when the call returns. .SH RETURN VALUE Upon successful completion, .CR rmtimer() returns zero; otherwise, it returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS .CR rmtimer() fails if the following condition is encountered: .RS .TP 12 [EINVAL] .CR timerid is not a valid timer ID. .RE .SH FILES .C /usr/include/sys/timers.h .SH SEE ALSO timer_delete(2), mktimer(3C), reltimer(3C). .SH STANDARDS CONFORMANCE .CR rmtimer() ": AES" .\" .\" toc@\f3rmtimer(3C)\f1:\0\0\f4rmtimer()\f1@@@free a per-process timer\f1 .\" .\" index@\f4rmtimer()\f1 \- free a per-process timer@@@\f3rmtimer(3C)\f1 .\" index@\f1free a per-process timer@@@\f3rmtimer(3C)\f1 .\" index@\f1cancel a per-process timer@@@\f3rmtimer(3C)\f1 .\" index@\f1terminate a per-process timer@@@\f3rmtimer(3C)\f1 .\" index@\f1abort a per-process timer@@@\f3rmtimer(3C)\f1 .\" index@\f1per-process timer, free a@@@\f3rmtimer(3C)\f1 .\" index@\f1timer, free a per-process@@@\f3rmtimer(3C)\f1 .\" $Header: rnusers.3n,v 72.4 94/06/30 15:56:56 ssa Exp $ .TA r .TH rnusers 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rnusers(\|), rusers(\|) \- return information about users on remote machines .SH SYNOPSIS .C #include .br .C #include .PP .C "int rnusers(char \(**host);" .PP .C "int rusers(char \(**host, struct utmpidlearr \(**up);" .SH DESCRIPTION .TP 15 .CR rnusers() returns the number of users logged in on .I host or \(mi1 if it cannot determine that number. The .I host string is either the official name of the host or an alias for it. See .IR hosts (4) for more information regarding host names. .TP .CR rusers() fills in the .CR utmpidlearr structure with data about .IR host and returns 0 if successful. The .CR ut_line field is limited to eight characters on Berkeley systems, so the HP-UX XDR routine truncates from 12 characters to 8. The .CR nonuser() macro does not exist in the HP-UX .CR utmp.h file; therefore, HP-UX windows appear as separate users. .PP The relevant structures are: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmparr { /* RUSERSVERS_ORIG */ struct utmp **uta_arr; int uta_cnt; }; .sp struct utmpidle { struct utmp ui_utmp; unsigned ui_idle; }; .sp struct utmpidlearr { /* RUSERSVERS_IDLE */ struct utmpidle **uia_arr; int uia_cnt; }; .ft .ps .fi .RE .SS \s-1RPC\s0 Information .RS .nf program number: \s-1RUSERSPROG\s+1 .PP xdr routines: int xdr_utmp(xdrs, up) \s-1XDR\s+1 \(**xdrs; struct utmp \(**up; int xdr_utmpidle(xdrs, ui) \s-1XDR\s+1 \(**xdrs; struct utmpidle \(**ui; int xdr_utmpptr(xdrs, up) \s-1XDR\s+1 \(**xdrs; struct utmp \(**\(**up; int xdr_utmpidleptr(xdrs, up) \s-1XDR\s+1 \(**xdrs; struct utmpidle \(**\(**up; int xdr_utmparr(xdrs, up) \s-1XDR\s+1 \(**xdrs; struct utmparr \(**up; int xdr_utmpidlearr(xdrs, up) \s-1XDR\s+1 \(**xdrs; struct utmpidlearr \(**up; .PP procs: \s-1RUSERSPROC_NUM\s+1 No arguments, returns number of users as an \f2unsigned long\fP. \s-1RUSERSPROC_NAMES\s+1 No arguments, returns \f2utmparr\fP or \f2utmpidlearr\fP, depending on version number. \s-1RUSERSPROC_ALLNAMES\s+1 No arguments, returns \f2utmparr\fP or \f2utmpidlearr\fP, depending on version number. Returns listing even for \f2utmp\fP entries satisfying \f2nonuser()\fP in \f2utmp.h\fP. .PP versions: \s-1RUSERSVERS_ORIG\s+1 \s-1RUSERSVERS_IDLE\s+1 structures: .fi .RE .SH WARNINGS User applications that call this routine must be linked with .CR /usr/lib/librpcsvc.a . For example, .IP .C cc my_source.c -lrpcsvc .SH AUTHOR .CR rnusers() was developed by Sun Microsystems, Inc. .SH SEE ALSO rusers(1). .\" .\" index@\f4rnusers()\fP: return information about users on remote machines@@@\f3rnusers(3N)\f1 .\" index@\f4rusers()\fP: return information about users on remote machines@@@\f3rnusers(3N)\f1 .\" index@return information about users on remote machines@@@\f3rnusers(3N)\f1 .\" index@information about users on remote machines, return@@@\f3rnusers(3N)\f1 .\" index@users on remote machines, return information about@@@\f3rnusers(3N)\f1 .\" index@remote machines, return information about users on@@@\f3rnusers(3N)\f1 .\" index@machines, return information about users on remote@@@\f3rnusers(3N)\f1 .\" .\" toc@\f3rnusers(3N)\f1: \f4rnusers()\fP, \f4rusers()\fP@@@return information about users on remote machines .\" .\" links@rnusers.3n rusers.3n .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "root_geometry_manager" "Xt \- Intrinsics Methods" .SH "Name" .Na root_geometry_manager \- Shell class method called to negotiate shell geometry requests with a window manager. .Nz .XX "geometry management: root_geometry_manager method" .XX "methods, root_geometry_manager" .SH "Synopsis" .Sy typedef XtGeometryResult (*XtGeometryHandler)(Widget, XtWidgetGeometry *, .br XtWidgetGeometry *); .As Widget \f(CIw\fP; XtWidgetGeometry *\f(CIrequest\fP; XtWidgetGeometry *\f(CIgeometry_return\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the shell widget making the request. .IP \f(CIrequest\fP 1i Specifies the requested geometry. .SS "Outputs" .IP \f(CIgeometry_return\fP 1i Specifies the reply geometry. .SS "Returns" The window manager's reply: \f(CWXtGeometryYes\fP, \f(CWXtGeometryNo\fP, \f(CWXtGeometryAlmost\fP, or \f(CWXtGeometryDone\fP. .\" .SH "Availability" Release 4 and later. .\" .SH "Description" The \f(CWroot_geometry_manager()\fP method is registered on the \f(CWroot_geometry_manager\fP field of a \f(CWShellClassExtensionRec\fP structure with \f(CWrecord_type\fP \f(CWNULLQUARK\fP, which is itself registered on the \f(CWextension\fP field of the Shell class part structure. The \f(CWroot_geometry_manager()\fP method will be called when a shell widget calls \f(CWXtMakeGeometryRequest()\fP or \f(CWXtMakeResizeRequest()\fP, and should negotiate the requested size with the window manager. .LP The arguments to this method are the same as those passed to the \f(CWgeometry_manager()\fP method. The \f(CWroot_geometry_manager()\fP method should pass the geometry request on to the window manager. If the window manager permits the new geometry, the \f(CWroot_geometry_manager()\fP should return \f(CWXtGeometryYes\fP; if the window manager denies the geometry request or it does not change the window geometry within some timeout interval (the \f(CWXtNwmTimeout\fP resource for WMShell, for example), the \f(CWroot_geometry_manager()\fP should return \f(CWXtGeometryNo\fP. If the window manager makes some alternative geometry change, the \f(CWroot_geometry_manager()\fP method may either return \f(CWXtGeometryNo\fP and handle the new geometry as a resize, or may return \f(CWXtGeometryAlmost\fP in anticipation that the shell will accept the compromise. If the compromise is not accepted, the new size must then be handled as a resize. .LP .Nd 4 Communication with a window manager is an asynchronous process, but the \f(CWroot_geometry_manager()\fP procedure must return its answer synchronously. It will have to issue its request and then block until the reply arrives. .LP The \f(CWroot_geometry_manager()\fP method is not chained. It can be inherited by specifying \f(CWXtInheritRootGeometryManager\fP in the Shell extension record. If there is no Shell extension record with \f(CWrecord_type\fP equal to \f(CWNULLQUARK\fP, then the Intrinsics will behave as if an extension was specified with \f(CWXtInheritRootGeometryManager\fP. .LP See the \fIInter-Client Communications Conventions Manual\fP for information on communicating with window managers. See \f(CWgeometry_manager\fP(4) for a description of the structures and the possible return values of this method. .\" .SH "Usage" The \f(CWroot_geometry_manager()\fP method of the Shell class itself handles communication with ICCCM-compliant window managers. It sets the appropriate properties to make the geometry request, then uses \f(CWXCheckIfEvent()\fP to block until an \f(CWConfigureNotify\fP event arrives in reply. This method also uses private functions internal to the Intrinsics in order to correctly handle the events. Because of the complexity and implementation-specific nature of this method, classes that want to define a custom \f(CWroot_geometry_manager()\fP method should make their requests to the window manager, and then call their superclass's method to make additional requests, block, and get the response. .\" .SH "See Also" .na \s-1\fIXtMakeGeometryRequest\fR\s+1\*(s1, \s-1\fIXtMakeResizeRequest\fR\s+1\*(s1, .br \s-1\fIShell\fR\s+1\*(s3, .br \s-1\fIgeometry_manager\fR\s+1\*(s4. .ad .\"last line comment .\" $Header: rpc.3c,v 72.4 94/08/09 11:54:59 ssa Exp $ .TA r .TH rpc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rpc \- library of routines for remote procedure calls .SH SYNOPSIS .nf .C "#include " .fi .SH DESCRIPTION With RPC routines, C client programs can make procedure calls on other machines across the network. .PP RPC routines are requested and dispatched as follows: .RS .TP 5 .B 1. A C client program calls RPC to request a service on a remote host. .TP .B 2. Upon receipt of the request, the server dispatches a routine to perform the requested service on the remote host. .TP .B 3. The server then sends back a reply and the procedure call returns to the client. .RE .SS Routines To use the RPC routines, C programs must include the header file, .CR . .PP Several libraries of RPC routines are provided, as documented in the following man pages: .TP 30 .I portmap (3C) A library of routines for the RPC binder service, .CR portmap ( ) , including: .RS 35 .nf .C " " .CR pmap_getmaps() .CR pmap_getport() .CR pmap_rmtcall() .CR pmap_set() .CR pmap_unset() .CR xdr_pmap() .CR xdr_pmaplist() .fi .RE .TP .I rpc_clnt_auth (3C) A library of routines for client-side authentication of RPC calls, including: .RS 35 .nf .C " " .CR auth_destroy() .CR authnone_create() .CR authunix_create() .CR authunix_create_default() .fi .RE .TP .I rpc_clnt_calls (3C) A library of routines for client-side RPC calls, including: .RS 35 .nf .C " " .CR callrpc() .CR clnt_broadcast() .CR clnt_call() .CR clnt_freeres() .CR clnt_geterr() .CR clnt_perrno() .CR clnt_perror() .CR clnt_sperrno() .CR clnt_sperror() .fi .RE .TP .I rpc_clnt_create (3C) A library of routines for the creation and manipulation of .CR CLIENT handles, including: .RS 35 .nf .C " " .CR clnt_control() .CR clnt_create() .CR clnt_create_vers() .CR clnt_destroy() .CR clnt_pcreateerror() .CR clntraw_create() .CR clnt_spcreateerror() .CR clnttcp_create() .CR clntudp_bufcreate() .CR clntudp_create() .CR rpc_createrr() .fi .RE .br .ne 8 .TP .I rpc_svc_calls (3C) A library of routines for the registration of servers, including: .RS 35 .nf .C " " .CR registerrpc() .CR svc_register() .CR svc_unregister() .CR xprt_register() .CR xprt_unregister() .fi .RE .TP .I rpc_svc_create (3C) A library of routines for the creation of server-side handles, including: .RS 35 .nf .C " " .CR svc_destroy() .CR svcfd_create() .CR svcraw_create() .CR svctcp_create() .CR svcudp_bufcreate() .fi .RE .TP .I rpc_svc_err (3C) A library of routines for server-side handling of RPC call errors, including: .RS 35 .nf .C " " .CR svcerr_auth() .CR svcerr_decode() .CR svcerr_noproc() .CR svcerr_noprog() .CR svcerr_progvers() .CR svcerr_systemerr() .CR svcerr_weakauth() .fi .RE .TP .I rpc_svc_reg (3C) A library of routines for RPC servers, including: .RS 35 .nf .C " " .CR svc_fds() .CR svc_fdset() .CR svc_freeargs() .CR svc_getargs() .CR svc_getcaller() .CR svc_getreq() .CR svc_getreqset() .CR svc_run() .CR svc_sendreply() .fi .RE .TP .I rpc_xdr (3C) An XDR library of routines for RPC calls, including: .RS 35 .nf .C " " .CR xdr_accepted_reply() .CR xdr_authunix_parms() .CR xdr_callhdr() .CR xdr_callmsg() .CR xdr_opaque_auth() .CR xdr_rejected_reply() .CR xdr_replymsg() .fi .RE .br .ne 13 .TP .I secure_rpc (3C) A library of routines for secure RPC calls, including: .RS 35 .nf .C " " .CR authdes_create() .CR authdes_getucred() .CR get_myaddress() .CR getnetname() .CR host2netname() .CR key_decryptsession() .CR key_encryptsession() .CR key_gendes() .CR key_setsecret() .CR netname2host() .CR netname2user() .CR user2netname() .fi .RE .SH AUTHOR .CR rpc () was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M), keyserv(1M), portmap(3C), rpc_clnt_auth(3C), rpc_clnt_calls(3C), rpc_clnt_create(3C), rpc_svc_calls(3C), rpc_svc_create(3C), rpc_svc_err(3C), rpc_svc_reg(3C), rpc_xdr(3C), secure_rpc(3C), xdr(3C), publickey(4) .PP .IR "Power Programming with RPC". .\" .\" index@\f4rpc\f1 \- library of routines for remote procedure calls@@@\f3rpc(3C)\f1 .\" .\" toc@\f3rpc(3C)\f1:\0\0\f4rpc\f1@@@library of routines for remote procedure calls .\" $Header: rpc_clnt_auth.3c,v 72.2 94/08/09 11:58:17 ssa Exp $ .TA r .TH rpc_clnt_auth 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME auth_destroy, authnone_create, authunix_create, authunix_create_default \- library of routines for client-side authentication of remote procedure calls .SH SYNOPSIS .nf .C " " .C "#include " .C " " .C "/* auth_destroy() */" .C "void" .C "auth_destroy(auth)" .C "AUTH *auth;" .C " " .C "/* authnone_create() */" .C "AUTH *" .C "authnone_create()" .C " " .C "/* authunix_create() */" .C "AUTH *" .C "authunix_create(host, uid, gid, grouplen, gidlistp)" .C "char *host;" .C "int uid, gid, grouplen, *gidlistp;" .C " " .C "/* authunix_create_default() */" .C "AUTH *" .C "authunix_create_default()" .C " " .fi .SH DESCRIPTION The .C rpc_clnt_auth( ) routines are provided for client-side authentication of remote procedure calls. .PP The following types of client-side authentication are supported currently: .RS .TP 10 .C AUTH_NONE, .TP .C AUTH_UNIX, .TP .C AUTH_DES. .RE .PP These routines are called after the .CR CLIENT handle is created, and the client's authentication information is passed to the server when the RPC is made. For routines related to .C AUTH_DES, see .IR secure_rpc (3C) . .SS Routines The .C rpc_clnt_auth( ) routines use the .CR AUTH data structure, which is defined in .IR "Power Programming with RPC" . .PP To use these routines, the header file .CR must be included in the C client program: .RS .TP 15 .CR auth_destroy ( ) Destroys the authentication information associated with the handle, .IR auth . The destruction of this information usually involves the deallocation of private data structures. The use of .I auth is undefined after .CR auth_destroy() is called. .TP .CR authnone_create ( ) Creates and returns an RPC authentication handle that passes no usable authentication information with each RPC call. This is the default authentication used by RPC. .TP .CR authunix_create ( ) Creates and returns an RPC authentication handle with UNIX authentication information, including: .TP 20 .I " " .I host, the name of the machine on which the information was created. .TP .I " " .I uid, the user's identification. .TP .I " " .I gid, the user's current group identification. .TP .I " " .I grouplen, gidlistp, a counted array of groups to which the user belongs. .TP 15 .I "" .B Warning: It is not very difficult to impersonate a user. .TP .C "authunix_create_default()" Calls .CR authunix_create() with the appropriate UNIX defaults. .SH AUTHOR .C rpc() was developed by Sun Microsystems, Inc. .SH SEE ALSO rpc(3C), rpc_clnt_create(3C), rpc_clnt_calls(3C) .\" .\" index@\f4rpc_clnt_auth()\f1 \- library of routines for client-side authentication of RPC calls@@@\f3rpc(3C)\f1 .\" index@\f4auth_destroy\f1 \- deallocate private structures used in client-side authentication of RPC calls@@@\f3rpc_clnt_auth(3C)\f1 .\" index@\f4authnone_create\f1 \- create handle for client-side authentication of RPC calls@@@\f3rpc_clnt_auth(3C)\f1 .\" index@\f4authunix_create\f1 \- create UNIX handle for client-side authentication of RPC calls@@@\f3rpc_clnt_auth(3C)\f1 .\" index@\f4authunix_create_default\f1 \- same as \f4authunix_create\f1, but with UNIX defaults@@@\f3rpc_clnt_auth(3C)\f1 .\" .\" toc@\f3rpc_clnt_auth()\f1@@@library of routines for client-side authentication of remote procedure calls .\" $Header: rpc_clnt_calls.3c,v 72.2 94/08/09 12:00:56 ssa Exp $ .TA r .TH rpc_clnt_calls 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME callrpc, clnt_broadcast, clnt_call, clnt_freeres, clnt_geterr, clnt_perrno, clnt_perror, clnt_sperrno, clnt_sperror \- library of routines for handling the client-side of RPC calls and errors .SH SYNOPSIS .nf .C "#include " .C " " .C "/* callrpc() */ .C "int" .C "callrpc(host, prognum, versnum, procnum, inproc, in, outproc, out)" .C "char *host;" .C "u_long prognum, versnum, procnum;" .C "xdrproc_t inproc, outproc;" .C "char *in, *out;" .C " " .C "/* clnt_broadcast() */ .C "enum clnt_stat" .C "clnt_broadcast(prognum, versnum, procnum, inproc, in, outproc, out, eachresu lt)" .C "u_long prognum, versnum, procnum;" .C "xdrproc_t inproc, outproc;" .C "char *in, *out;" .C "bool_t eachresult;" .C " " .C "/* clnt_call() */ .C "enum clnt_stat" .C "clnt_call(clnt, procnum, inproc, in, outproc, out, timeout)" .C "CLIENT *clnt;" .C "u_long procnum;" .C "xdrproc_t inproc, outproc;" .C "char *in, *out;" .C "struct timeval timeout;" .C " " .C "/* clnt_freeres() */ .C "bool_t" .C "clnt_freeres(clnt, outproc, out)" .C "CLIENT *clnt;" .C "xdrproc_t outproc;" .C "char *out;" .C " " .C "/* clnt_geterr() */" .C "void" .C "clnt_geterr(clnt, errp)" .C "CLIENT *clnt;" .C "struct rpc_err *errp;" .C " " .C "/* clnt_perrno() */" .C "void" .C "clnt_perrno(stat)" .C "enum clnt_stat stat;" .C " " .C "/* clnt_perror */" .C "void" .C "clnt_perror(clnt, str)" .C "CLIENT *clnt;" .C "char *str;" .C " " .C "/* clnt_sperrno() */" .C "char *" .C "clnt_sperrno(stat)" .C "enum clnt_stat stat;" .C " " .C "/* clnt_sperror() */" .C "char *" .C "clnt_sperror(clnt, str)" .C "CLIENT *clnt;" .C "char *str;" .fi .SH DESCRIPTION The .C rpc_clnt_calls() routines .CR clnt_call() , .CR callrpc() , and .C clnt_broadcast() handle the client side of RPC calls. The remaining routines in this library are for error-handling. .SS Routines These routines use the .CR CLIENT data structure, which is defined in .IR "Power Programming with RPC" . .PP To use these routines, the C client program must include the RPC header file, .CR . .RS .TP 16 .C callrpc() Calls a procedure on a remote machine. The .C callrpc() parameters are defined as follows: .TP 20 .I " " .I host is the host id. of the remote machine. .TP .I " " .I prognum is the program number associated with the remote procedure. .TP .I " " .I versnum is the version number associated with the remote procedure. .TP .I " " .I procnum is the procedure number associated with the remote procedure. .TP .I " " .I in is the address of the argument of the remote procedure. .TP .I " " .I out is the address of the result of the remote procedure. .TP .I " " .I inproc is the XDR function used to encode the remote procedure. .TP .I " " .I outproc is the XDR function used to decode the results of the remote procedure. .TP 16 .I " " This routine returns 0 if it succeeds, or the value of .C "enum clnt_stat" cast to an integer if it fails. Use .C clnt_perrno() to translate failure statuses into messages. .TP .I " " .B Warning: Calling remote procedures with this routine uses .C UDP/IP as the transport: see the description of the .C clntudp_create() routine in .CR rpc_clnt_create (3C) for restrictions. You do not have control of timeouts or authentication using this routine. .TP .C clnt_broadcast() Similar to the .CR callrpc() routine with one exception: the RPC message is broadcast to all broadcast nets connected locally. Each time the caller receives a response, this routine calls .CR eachresult() : .TP 20 .I " " .nf .C "int eachresult(out, addr)" .C "char *out;" .C "struct sockaddr_in *addr;" .C " " .fi .TP 16 .I " " The .CR eachresult() parameters are defined as follows: .TP 20 .I " " .I out is the address where the result of the RPC call is decoded. .TP .I " " .I addr points to the address of the machine that sent the results. .TP 16 .I " " If .C eachresult() returns 0, .C clnt_broadcast() waits for more replies; otherwise it returns the appropriate status. If .C eachresult() is NULL, .C clnt_broadcast() returns without waiting for any replies. .TP .I " " .B Note: .C clnt_broadcast() uses the .C AUTH_UNIX style of authentication. .TP .I " " .B Warning: Broadcast packets are limited in size to the maximum transfer unit of the data link. For Ethernet, the callers argument size should not exceed 1400 bytes. .TP .C clnt_call() Calls a remote procedure associated with a client handle (which is created with an RPC routine such as .C clnt_create(), as described in .CR rpc_clnt_create (3C) ) . The .CR clnt_call() parameters are defined as follows: .TP 20 .I " " .I clnt is the client handle. .TP .I " " .I procnum is the procedure number associated with the remote procedure. .TP .I " " .I inproc is the XDR function used to encode the parameters of the remote proceudre. .TP .I " " .I in is the address of the argument of the remote procedure. .TP .I " " .I outproc is the XDR function used to decode the results of the remote procedure. .TP .I " " .I out is the address is the address of the result of the remote procedure. .TP .I " " .I timeout is the time allowed for a response from the server. .TP 16 .C clnt_freeres() Frees any data allocated by the RPC/XDR system when the results of an RPC call were decoded. The .CR clnt_freeres() parameters are defined as follows: .TP 20 .I " " .I clnt is the client handle. .TP .I " " .I outproc is the XDR function used to decode the RPC results. .TP .I " " .I out is the address where the RPC result is placed. .TP 16 .I " " This routine returns TRUE if the results were successfully freed, and FALSE otherwise. .TP .I " " .B Note: This routine is equivalent to doing .C xdr_free() , as described in .IR xdr_simple (3C). .TP .C clnt_geterr() Copies the error structure out of the client handle to the .CR rpc_err structure. The .CR clnt_geterr() parameters are defined as follows: .TP 20 .I " " .I clnt is the client handle. .TP .I " " .I errp is the address of the structure, .CR rpc_err . .I errp should point to a preallocated space. .TP 16 .C clnt_perrno() Used after .CR callrpc() or .CR clnt_broadcast() : Prints a message to the standard error indicating to the condition obtained by .CR stat() . A newline is appended at the end of the message. .TP .C clnt_perror() Used after .CR clnt_call() : Prints a message to the standard error indicating why an RPC call failed. A newline is appended at the end of the message. The .CR clnt_perror() parameters are defined as follows: .TP 20 .I " " .I clnt is the client handle. .TP .I " " .I str is the error message, prefixed with string .I s and a colon. .TP 16 .C clnt_sperrno() Similar to .CR clnt_perrno() with one exception: instead of sending a message to standard error that indicates why an RPC failed, this routine returns a pointer to a message string, and does not append a newline at the end of the message. .IP Use .C clnt_sperrno() instead of .C clnt_perrno() for any of the following reasons: .TP 20 .I " " .nf \(bu\0\0\0the program does not have a standard error (as a program running \0\0\0\0as a server quite likely does not). .fi .TP .I " " .nf \(bu\0\0\0the programmer does not want the message to be output with \f4printf( )\f1. .I " " .fi .TP .I " " .nf \(bu\0\0\0a message format different than that supported by \f4clnt_perrno( )\f1 \0\0\0\0is to be used. .fi .TP 16 .C clnt_sperror() Similiar to the .CR clnt_perror() routine with one exception: like .CR clnt_sperrno(), it returns a string instead of printing to standard error and does not append the message with a newline. .C clnt_sperror() returns a pointer to a static buffer that is overwritten on each call. .RE .SH AUTHOR .CR rpc () was developed by Sun Microsystems, Inc. .SH SEE ALSO printf(3S), rpc(3C), rpc_clnt_auth(3C), rpc_clnt_create(3C), xdr_simple(3C) .\" .\" index@\f4rpc_clnt_calls(3C)\f1 \- library of routines for handling the client side of remote procedure calls@@@\f3rpc(3C)\f1 .\" index@\f4callrpc()\f1 \- call a procedure on a remote host@@@\f3rpc_clnt_calls(3C)\f1 .\" index@\f4clnt_broadcast()\f1 \- perform an RPC with local-net message broadcast@@@\f3rpc_clnt_calls(3C)\f1 .\" index@\f4clnt_call()\f1 \- perform an RPC using the client handle procedure number@@@\f3rpc_clnt_calls(3C)\f1 .\" index@\f4clnt_freeres()\f1 \- free RPC results data decoded and allocated by the RPC/XDR system@@@\f3rpc_clnt_calls(3C)\f1 .\" index@\f4clnt_geterr()\f1 \- copy error structure from client handle to error address@@@\f3rpc_clnt_calls(3C)\f1 .\" index@\f4clnt_perrno()\f1 \- print standard error message for RPC error condition@@@\f3rpc_clnt_calls(3C)\f1 .\" index@\f4clnt_perror()\f1 \- print a standard error to indicate why an RPC call failed@@@\f3rpc_clnt_calls(3C)\f1 .\" index@\f4clnt_sperrno()\f1 \- return a pointer to a message string that indicates why an RPC failed@@@\f3rpc_clnt_calls(3C)\f1 .\" index@\f4clnt_sperror()\f1 \- return a string instead of printing to the standard error@@@\f3rpc_clnt_calls(3C)\f1 .\" .\" toc@\f3rpc_clnt_calls(3C)\f1:\0\0\f4rpc_clnt_calls\f1@@@library of routines for handling the client side of remote procedure calls .\" $Header: rpc_clnt_create.3c,v 72.3 94/10/13 20:00:20 ssa Exp $ .TA r .TH rpc_clnt_create 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clnt_control, clnt_create, clnt_create_vers, clnt_destroy, clnt_pcreateerror, clntraw_create, clnt_spcreateerror, clnttcp_create, clntudp_bufcreate, clntudp_create, rpc_createrr \- library routines for the creation and manipulation of client handles .SH SYNOPSIS .nf .C "#include " .C " " .C "/* clnt_control */" .C "bool_t" .C "clnt_control(clnt, request, info)" .C "CLIENT *clnt;" .C "int request;" .C "char *info;" .C " " .C "/* clnt_create */" .C "CLIENT *" .C "clnt_create(host, prognum, versnum, protocol)" .C "char *host;" .C "u_long prognum, versnum;" .C "char *protocol;" .C " " .C "/* clnt_create_vers */" .C "CLIENT *" .C "clnt_create_vers(host, prognum, vers_outp, vers_low, vers_high, protocol)" .C "char *host;" .C "u_long prognum;" .C "u_long *vers_outp;" .C "u_long vers_low, vers_high;" .C "char *protocol;" .C " " .C "/* clnt_destroy */" .C "void" .C "clnt_destroy(clnt)" .C "CLIENT *clnt;" .C " " .C "/* clnt_pcreateerror */" .C "void" .C "clnt_pcreateerror(str)" .C "char *str;" .C " " .C "/* clntraw_create */" .C "CLIENT *" .C "clntraw_create(prognum, versnum)" .C "u_long prognum, versnum;" .C " " .C "/* clnt_spcreateerror */" .C "char *" .C "clnt_spcreateerror(str)" .C "char *str;" .C " " .C "/* clnttcp_create */" .C "CLIENT *" .C "clnttcp_create(addr, prognum, versnum, sockp, sendsz, recvsz)" .C "struct sockaddr_in *addr;" .C "u_long prognum, versnum;" .C "int *sockp;" .C "u_int sendsz, recvsz;" .C " " .C "/* clntudp_bufcreate */" .C "CLIENT *" .C "clntudp_bufcreate(addr, prognum, versnum, wait, sockp, sendsz, recvsz)" .C "struct sockaddr_in *addr;" .C "u_long prognum, versnum;" .C "struct timeval wait;" .C "int *sockp;" .C "u_int sendsz, recvsz;" .C " " .C "/* clntudp_create */" .C "CLIENT *" .C "clntudp_create(addr, prognum, versnum, wait, sockp)" .C "struct sockaddr_in *addr;" .C "u_long prognum, versnum;" .C "struct timeval wait;" .C "int *sockp;" .C " " .C "/* rpc_createrr */" .C "struct rpc_createerr rpc_createerr;" .fi .SH DESCRIPTION The following .CR rpc_clnt_create() routines support the creation and manipulation of client handles. .PP These routines use the CLIENT data structure, which is defined in .IR "Power Programming with RPC". .PP To use these routines, the C client program must include the header file, .CR . .RS .TP 20 .C clnt_control() Changes or retrieves information about a client object. This routine returns TRUE on successful completion; otherwise, it returns FALSE. The parameters for this routine are defined as follows: .TP 25 .I " " .I clnt is the client object. .TP .I " " .I request is the type of operation to be performed. The following requests are valid for both UDP and TCP networks: .TP 30 .I " " .C CLSET_TIMEOUT \0-\0Sets the total timeout. The argument type is .C struct timeval. .TP .I " " .C CLGET_TIMEOUT \0-\0Gets the total timeout. The argument type is .C struct timeval. .TP .I " " .C CLGET_FD \0-\0Gets the associated socket. The argument type is .C int. .TP .I " " .C CLSET_FD_CLOSE \0-\0Closes the socket on .C clnt_destroy(). The argument type is .C void. .TP .I " " .C CLSET_FD_NCLOSE \0-\0Leaves socket open on .C clnt_destroy(). The argument type is .C void. .TP .I " " .C CLGET_SERVER_ADDR \0-\0Gets server's address. The argument type is .C struct sockaddr_in. .TP .I " " .B Note: If you set the timeout using .CR clnt_control() , the timeout parameter passed to .C clnt_call() will be ignored in all future calls (see .CR rpc_clnt_calls (3C)). .TP 25 .I " " The following requests are valid for UDP only: .TP 30 .I " " .C CLSET_RETRY_TIMEOUT \0-\0Sets the retry timeout. The argument type is .C struct timeval. .TP .I " " .C CLGET_RETRY_TIMEOUT \0-\0Gets the retry timeout. The argument type is .C struct timeval. .TP .I " " .B Note: The retry timeout is the time that UDP RPC waits for the server to reply before retransmitting the request. .TP 25 .I " " .I info is a pointer to the information about the client object. .TP 20 .C clnt_create() Creates a client handle on a remote host. The parameters for this routine are defined as follows: .TP 25 .I " " .I host is the name of the remote host (where the server is located). .TP .I " " .I prognum is the program number associated with the remote procedure. .TP .I " " .I versnum is the version number associated with the remote procedure. .TP .I " " .I protocol is the type of transport protocol to be used. The currently supported values for this field are .C udp and .C tcp. .TP 20 .I " " Default timeouts are set, but they can be modified using .CR clnt_control() . .IP If successful, this routine returns a client handle; otherwise it returns NULL. .TP .I " " .B Warning: Using UDP has its shortcomings. Since UDP-based RPC messages can only hold up to 8 kilobytes of encoded data, this transport cannot be used for procedures that take arguments or return results larger than 8 kilobytes. Use TCP whenever you need to exceed this message-data limit. .TP .I " " .B Note: If a version number for the specified program is registered with the .CR portmap (1M) service on .IR host , .C clnt_create() returns a handle, even if the requested version number .I versnum is not registered. The version mismatch will be discovered by a .C clnt_call() later (see .CR rpc_clnt_calls (3C)). .TP .C clnt_create_vers() Creates a client handle on a remote host with the highest available version number. .IP Default timeouts are also set, but can be modified using .CR clnt_control() . .IP The parameters for this routine are defined as follows: .TP 25 .I " " .I host is the name of the remote host (where the server is located). .TP .I " " .I prognum is the program number associated with the remote procedure. .TP .I " " .IR vers_outp, .IR vers_low, and .IR vers_high are used to create and set the version number for the client handle. If the routine is successful, it returns a client handle created for the highest version that is supported by the server, between .I vers_low and .I vers_high . The .I vers_outp is set to this value after a successful return of .I vers_low <= .I *vers_outp <= .I vers_high. If no version between .I vers_low and .I vers_high is supported by the server, then the routine fails and returns NULL. .TP .I " " .I protocol is the type of transport protocol to be used. The currently supported values for this field are .C udp and .C tcp. .TP 20 .I " " .B Note: .CR clnt_create() returns a valid client handle even if the particular version number supplied to .CR clnt_create() is not registered with the portmap service. This mismatch will be discovered by a .CR clnt_call() later (see .CR rpc_clnt_calls (3C)). However, .CR clnt_create_vers() does this for you and returns a valid handle only if a version within the range supplied is supported by the server. .TP 20 .C clnt_destroy() Destroys the client's RPC handle and deallocates any private data structures, including the client object, .I clnt . (Use of .I clnt is undefined after calling .CR clnt_destroy() .) If the RPC library opened the associated socket, or if .C CLSET_FD_CLOSE was set using .CR clnt_control() , the .CR clnt_destroy() routine closes the socket. .TP .C clnt_pcreateerror() Prints a standard error message to indicate why a client handle could not be created. The message is prefixed with string .I s and a colon. This routine is used when routines such as .CR clnt_create() , .CR clntraw_create() , .CR clnttcp_create() , or .CR clntudp_create() fail. .TP .C clntraw_create() Creates an RPC client for a remote program. .IP This routine allows for RPC simulation and the retrieval of RPC overheads, such as round trip times, without any kernel interference. If the routine is successful it returns a client handle, otherwise it returns NULL. .IP The parameters for this routine are defined as follows: .TP 25 .I " " .I prognum is the program number associated with the remote procedure. .TP .I " " .I versnum is the version number associated with the remote procedure. .TP 20 .I " " Since the transport used to pass messages to the service is actually a buffer within the process's address space, the corresponding RPC server should live in the same address space: see the description for .CR svcraw_create() in .IR rpc_svc_create (3C) for more information. .TP .C clnt_spcreateerror() Returns an error-message string indicating why a client handle could not be created; does not append the message with a newline. .TP .I " " .B Note: .CR clnt_spcreateerror() returns a pointer to a static buffer that is overwritten on each call. .TP .C clnttcp_create() Creates a client handle for a remote program that uses TCP/IP as the transport. .IP If successful, this routine returns a client handle; otherwise it returns NULL. .IP The parameters for this routine are defined as follows: .TP 25 .I " " .I addr is the Internet address of the remote program. If .I addr -> .I sin_port is zero, it is set to the port on which the remote program is listening (the remote .CR portmap() service is consulted for this information). .TP .I " " .I prognum is the program number associated with the remote procedure. .TP .I " " .I versnum is the version number associated with the remote procedure. .TP .I " " .I sockp is a pointer to a socket. If it is .C RPC_ANYSOCK, then a new socket is opened and .IR sockp is updated. .TP .I " " .I sendsz , recvsz are send and receive buffers of a specified size. Since TCP-based RPC uses buffered I/O, the user may specify the size of the send and receive buffers with these parameters, and can use values of zero to set defaults. .TP 20 .I " " .B Warning: If .I addr -> .I sin_port is zero and the requested .I versnum is not registered with the remote portmap service, it returns a handle if (at least) a version number for the given program number is registered. The version mismatch will be discovered by a .C clnt_call() later (see .IR rpc_clnt_calls (3C) for more details). .TP .C clntudp_bufcreate() Creates a client handle for a remote program that uses UDP/IP as the transport; allows user to specify sizes of the send and receive buffers. .IP If this routine is successful it returns a client handle; otherwise it returns NULL. .IP The parameters for this routine are defined as follows: .TP 25 .I " " .I addr is the Internet address of the remote program. If .IR addr -> .I sin_port is zero, it is set to the port on which the remote program is listening (the remote .CR portmap() service is consulted for this information). .TP .I " " .I prognum is the program number associated with the remote procedure. .TP .I " " .I versnum is the version number associated with the remote procedure. .TP .I " " .I wait is the intervals of time that the UDP transport resends the call message until a response is received or until the call times out. The total time for the call to time out is specified by .C clnt_call() (see .IR rpc_clnt_calls (3C) for more information). .TP .I " " .I sockp is the pointer to a socket. If it is .C RPC_ANYSOCK, then a new socket is opened and .IR sockp is updated. .TP .I " " .I sendsz , recvsz are the send and receive buffers of a specified size. Since UDP-based RPC uses buffered I/O, the user may specify the maximum packet size for sending and receiving using these arguments. .TP 20 .I " " .B Warning: If .I addr -> .I sin_port is zero and the requested version number is not registered with the remote portmap service, this routine returns a handle if at least a version number for the given program number is registered. The version mismatch is discovered by a .C clnt_call() later (see .IR rpc_clnt_calls (3C)). .TP .C clntudp_create() Creates a client handle for a remote program; the client uses UDP/IP as the transport. .IP If this routine is successful it returns a client handle; otherwise it returns NULL. .IP The parameters for this routine are defined as follows: .TP 25 .I " " .I addr is the Internet address of the remote program. If .I addr -> .I sin_port is zero, it is set to the port on which the remote program is listening (the remote .CR portmap() service is consulted for this information). .TP .I " " .I prognum is the program number associated with the remote procedure. .TP .I " " .I versnum is the version number associated with the remote procedure. .TP .I " " .I wait is the intervals of time that the UDP transport resends the call message until a response is received or until the call times out. The total time for the call to time out is specified by .C clnt_call() (see .IR rpc_clnt_calls (3C)). .TP .I " " .I sockp is the pointer to a socket. If it is .C RPC_ANYSOCK, a new socket is opened and .IR sockp is updated. .TP 20 .I " " .B Warning: Since UDP-based RPC messages can only hold up to 8 kilobytes of encoded data, this transport cannot be used for procedures that take arguments or results larger than 8 kilobytes. TCP should be used instead. .TP .I " " .B Warning: If .I addr -> .I sin_port is zero and the requested version number is not registered with the remote portmap service, this routine returns a handle if any version number for the given program number is registered. The version mismatch is discovered by a .C clnt_call() later (see .IR rpc_clnt_calls (3C)). .TP .C rpc_createrr() A global variable whose value is set by any RPC client handle creation routine that fails. This routine is used by .C clnt_pcreateerror() to print the reason for the failure. .RE .SH AUTHOR .CR rpc (3C) was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(3C), rpc(3C), rpc_clnt_auth(3C), rpc_clnt_calls(3C), rpc_svc_create(3C) .\" .\" index@\f4rpc_clnt_create(3C)\f1 \- library of routines for the creation and manipulation of client handles@@@\f3rpc(3C)\f1 .\" index@\f4clnt_control()\f1 \- change or retrieve client-object information@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clnt_create()\f1 \- create client handle on remote host@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clnt_create_vers()\f1 \- create client handle on remote host with available version number@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clnt_destroy()\f1 \- destroy RPC client handle and deallocate data structures@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clnt_pcreateerror()\f1 \- print standard error; client handle could not be created@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clntraw_create()\f1 \- create RPC client for remote program@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clnt_spcreateerror()\f1 \- return error-message string; client handle could not be created@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clnttcp_create()\f1 \- create handle for remote TCP/IP program@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clntudp_bufcreate()\f1 \- create handle for remote UDP/IP program@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clntudp_create()\f1 \- creates handle for remote UDP/IP program@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4rpc_createrr()\f1 \- global variable set by any RPC client-handle creation routine that fails@@@\f3rpc_clnt_create(3C)\f1 .\" .\" toc@\f3rpc_clnt_create(3C)\f1:\0\0\f4rpc_clnt_create\f1@@@library of routines for the creation and manipulation of client handles .\" .\" links@rpc_clnt_create.3c rpc_createrr.3c .\" $Header: rpc_clnt_create.3c,v 72.3 94/10/13 20:00:20 ssa Exp $ .TA r .TH rpc_clnt_create 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clnt_control, clnt_create, clnt_create_vers, clnt_destroy, clnt_pcreateerror, clntraw_create, clnt_spcreateerror, clnttcp_create, clntudp_bufcreate, clntudp_create, rpc_createrr \- library routines for the creation and manipulation of client handles .SH SYNOPSIS .nf .C "#include " .C " " .C "/* clnt_control */" .C "bool_t" .C "clnt_control(clnt, request, info)" .C "CLIENT *clnt;" .C "int request;" .C "char *info;" .C " " .C "/* clnt_create */" .C "CLIENT *" .C "clnt_create(host, prognum, versnum, protocol)" .C "char *host;" .C "u_long prognum, versnum;" .C "char *protocol;" .C " " .C "/* clnt_create_vers */" .C "CLIENT *" .C "clnt_create_vers(host, prognum, vers_outp, vers_low, vers_high, protocol)" .C "char *host;" .C "u_long prognum;" .C "u_long *vers_outp;" .C "u_long vers_low, vers_high;" .C "char *protocol;" .C " " .C "/* clnt_destroy */" .C "void" .C "clnt_destroy(clnt)" .C "CLIENT *clnt;" .C " " .C "/* clnt_pcreateerror */" .C "void" .C "clnt_pcreateerror(str)" .C "char *str;" .C " " .C "/* clntraw_create */" .C "CLIENT *" .C "clntraw_create(prognum, versnum)" .C "u_long prognum, versnum;" .C " " .C "/* clnt_spcreateerror */" .C "char *" .C "clnt_spcreateerror(str)" .C "char *str;" .C " " .C "/* clnttcp_create */" .C "CLIENT *" .C "clnttcp_create(addr, prognum, versnum, sockp, sendsz, recvsz)" .C "struct sockaddr_in *addr;" .C "u_long prognum, versnum;" .C "int *sockp;" .C "u_int sendsz, recvsz;" .C " " .C "/* clntudp_bufcreate */" .C "CLIENT *" .C "clntudp_bufcreate(addr, prognum, versnum, wait, sockp, sendsz, recvsz)" .C "struct sockaddr_in *addr;" .C "u_long prognum, versnum;" .C "struct timeval wait;" .C "int *sockp;" .C "u_int sendsz, recvsz;" .C " " .C "/* clntudp_create */" .C "CLIENT *" .C "clntudp_create(addr, prognum, versnum, wait, sockp)" .C "struct sockaddr_in *addr;" .C "u_long prognum, versnum;" .C "struct timeval wait;" .C "int *sockp;" .C " " .C "/* rpc_createrr */" .C "struct rpc_createerr rpc_createerr;" .fi .SH DESCRIPTION The following .CR rpc_clnt_create() routines support the creation and manipulation of client handles. .PP These routines use the CLIENT data structure, which is defined in .IR "Power Programming with RPC". .PP To use these routines, the C client program must include the header file, .CR . .RS .TP 20 .C clnt_control() Changes or retrieves information about a client object. This routine returns TRUE on successful completion; otherwise, it returns FALSE. The parameters for this routine are defined as follows: .TP 25 .I " " .I clnt is the client object. .TP .I " " .I request is the type of operation to be performed. The following requests are valid for both UDP and TCP networks: .TP 30 .I " " .C CLSET_TIMEOUT \0-\0Sets the total timeout. The argument type is .C struct timeval. .TP .I " " .C CLGET_TIMEOUT \0-\0Gets the total timeout. The argument type is .C struct timeval. .TP .I " " .C CLGET_FD \0-\0Gets the associated socket. The argument type is .C int. .TP .I " " .C CLSET_FD_CLOSE \0-\0Closes the socket on .C clnt_destroy(). The argument type is .C void. .TP .I " " .C CLSET_FD_NCLOSE \0-\0Leaves socket open on .C clnt_destroy(). The argument type is .C void. .TP .I " " .C CLGET_SERVER_ADDR \0-\0Gets server's address. The argument type is .C struct sockaddr_in. .TP .I " " .B Note: If you set the timeout using .CR clnt_control() , the timeout parameter passed to .C clnt_call() will be ignored in all future calls (see .CR rpc_clnt_calls (3C)). .TP 25 .I " " The following requests are valid for UDP only: .TP 30 .I " " .C CLSET_RETRY_TIMEOUT \0-\0Sets the retry timeout. The argument type is .C struct timeval. .TP .I " " .C CLGET_RETRY_TIMEOUT \0-\0Gets the retry timeout. The argument type is .C struct timeval. .TP .I " " .B Note: The retry timeout is the time that UDP RPC waits for the server to reply before retransmitting the request. .TP 25 .I " " .I info is a pointer to the information about the client object. .TP 20 .C clnt_create() Creates a client handle on a remote host. The parameters for this routine are defined as follows: .TP 25 .I " " .I host is the name of the remote host (where the server is located). .TP .I " " .I prognum is the program number associated with the remote procedure. .TP .I " " .I versnum is the version number associated with the remote procedure. .TP .I " " .I protocol is the type of transport protocol to be used. The currently supported values for this field are .C udp and .C tcp. .TP 20 .I " " Default timeouts are set, but they can be modified using .CR clnt_control() . .IP If successful, this routine returns a client handle; otherwise it returns NULL. .TP .I " " .B Warning: Using UDP has its shortcomings. Since UDP-based RPC messages can only hold up to 8 kilobytes of encoded data, this transport cannot be used for procedures that take arguments or return results larger than 8 kilobytes. Use TCP whenever you need to exceed this message-data limit. .TP .I " " .B Note: If a version number for the specified program is registered with the .CR portmap (1M) service on .IR host , .C clnt_create() returns a handle, even if the requested version number .I versnum is not registered. The version mismatch will be discovered by a .C clnt_call() later (see .CR rpc_clnt_calls (3C)). .TP .C clnt_create_vers() Creates a client handle on a remote host with the highest available version number. .IP Default timeouts are also set, but can be modified using .CR clnt_control() . .IP The parameters for this routine are defined as follows: .TP 25 .I " " .I host is the name of the remote host (where the server is located). .TP .I " " .I prognum is the program number associated with the remote procedure. .TP .I " " .IR vers_outp, .IR vers_low, and .IR vers_high are used to create and set the version number for the client handle. If the routine is successful, it returns a client handle created for the highest version that is supported by the server, between .I vers_low and .I vers_high . The .I vers_outp is set to this value after a successful return of .I vers_low <= .I *vers_outp <= .I vers_high. If no version between .I vers_low and .I vers_high is supported by the server, then the routine fails and returns NULL. .TP .I " " .I protocol is the type of transport protocol to be used. The currently supported values for this field are .C udp and .C tcp. .TP 20 .I " " .B Note: .CR clnt_create() returns a valid client handle even if the particular version number supplied to .CR clnt_create() is not registered with the portmap service. This mismatch will be discovered by a .CR clnt_call() later (see .CR rpc_clnt_calls (3C)). However, .CR clnt_create_vers() does this for you and returns a valid handle only if a version within the range supplied is supported by the server. .TP 20 .C clnt_destroy() Destroys the client's RPC handle and deallocates any private data structures, including the client object, .I clnt . (Use of .I clnt is undefined after calling .CR clnt_destroy() .) If the RPC library opened the associated socket, or if .C CLSET_FD_CLOSE was set using .CR clnt_control() , the .CR clnt_destroy() routine closes the socket. .TP .C clnt_pcreateerror() Prints a standard error message to indicate why a client handle could not be created. The message is prefixed with string .I s and a colon. This routine is used when routines such as .CR clnt_create() , .CR clntraw_create() , .CR clnttcp_create() , or .CR clntudp_create() fail. .TP .C clntraw_create() Creates an RPC client for a remote program. .IP This routine allows for RPC simulation and the retrieval of RPC overheads, such as round trip times, without any kernel interference. If the routine is successful it returns a client handle, otherwise it returns NULL. .IP The parameters for this routine are defined as follows: .TP 25 .I " " .I prognum is the program number associated with the remote procedure. .TP .I " " .I versnum is the version number associated with the remote procedure. .TP 20 .I " " Since the transport used to pass messages to the service is actually a buffer within the process's address space, the corresponding RPC server should live in the same address space: see the description for .CR svcraw_create() in .IR rpc_svc_create (3C) for more information. .TP .C clnt_spcreateerror() Returns an error-message string indicating why a client handle could not be created; does not append the message with a newline. .TP .I " " .B Note: .CR clnt_spcreateerror() returns a pointer to a static buffer that is overwritten on each call. .TP .C clnttcp_create() Creates a client handle for a remote program that uses TCP/IP as the transport. .IP If successful, this routine returns a client handle; otherwise it returns NULL. .IP The parameters for this routine are defined as follows: .TP 25 .I " " .I addr is the Internet address of the remote program. If .I addr -> .I sin_port is zero, it is set to the port on which the remote program is listening (the remote .CR portmap() service is consulted for this information). .TP .I " " .I prognum is the program number associated with the remote procedure. .TP .I " " .I versnum is the version number associated with the remote procedure. .TP .I " " .I sockp is a pointer to a socket. If it is .C RPC_ANYSOCK, then a new socket is opened and .IR sockp is updated. .TP .I " " .I sendsz , recvsz are send and receive buffers of a specified size. Since TCP-based RPC uses buffered I/O, the user may specify the size of the send and receive buffers with these parameters, and can use values of zero to set defaults. .TP 20 .I " " .B Warning: If .I addr -> .I sin_port is zero and the requested .I versnum is not registered with the remote portmap service, it returns a handle if (at least) a version number for the given program number is registered. The version mismatch will be discovered by a .C clnt_call() later (see .IR rpc_clnt_calls (3C) for more details). .TP .C clntudp_bufcreate() Creates a client handle for a remote program that uses UDP/IP as the transport; allows user to specify sizes of the send and receive buffers. .IP If this routine is successful it returns a client handle; otherwise it returns NULL. .IP The parameters for this routine are defined as follows: .TP 25 .I " " .I addr is the Internet address of the remote program. If .IR addr -> .I sin_port is zero, it is set to the port on which the remote program is listening (the remote .CR portmap() service is consulted for this information). .TP .I " " .I prognum is the program number associated with the remote procedure. .TP .I " " .I versnum is the version number associated with the remote procedure. .TP .I " " .I wait is the intervals of time that the UDP transport resends the call message until a response is received or until the call times out. The total time for the call to time out is specified by .C clnt_call() (see .IR rpc_clnt_calls (3C) for more information). .TP .I " " .I sockp is the pointer to a socket. If it is .C RPC_ANYSOCK, then a new socket is opened and .IR sockp is updated. .TP .I " " .I sendsz , recvsz are the send and receive buffers of a specified size. Since UDP-based RPC uses buffered I/O, the user may specify the maximum packet size for sending and receiving using these arguments. .TP 20 .I " " .B Warning: If .I addr -> .I sin_port is zero and the requested version number is not registered with the remote portmap service, this routine returns a handle if at least a version number for the given program number is registered. The version mismatch is discovered by a .C clnt_call() later (see .IR rpc_clnt_calls (3C)). .TP .C clntudp_create() Creates a client handle for a remote program; the client uses UDP/IP as the transport. .IP If this routine is successful it returns a client handle; otherwise it returns NULL. .IP The parameters for this routine are defined as follows: .TP 25 .I " " .I addr is the Internet address of the remote program. If .I addr -> .I sin_port is zero, it is set to the port on which the remote program is listening (the remote .CR portmap() service is consulted for this information). .TP .I " " .I prognum is the program number associated with the remote procedure. .TP .I " " .I versnum is the version number associated with the remote procedure. .TP .I " " .I wait is the intervals of time that the UDP transport resends the call message until a response is received or until the call times out. The total time for the call to time out is specified by .C clnt_call() (see .IR rpc_clnt_calls (3C)). .TP .I " " .I sockp is the pointer to a socket. If it is .C RPC_ANYSOCK, a new socket is opened and .IR sockp is updated. .TP 20 .I " " .B Warning: Since UDP-based RPC messages can only hold up to 8 kilobytes of encoded data, this transport cannot be used for procedures that take arguments or results larger than 8 kilobytes. TCP should be used instead. .TP .I " " .B Warning: If .I addr -> .I sin_port is zero and the requested version number is not registered with the remote portmap service, this routine returns a handle if any version number for the given program number is registered. The version mismatch is discovered by a .C clnt_call() later (see .IR rpc_clnt_calls (3C)). .TP .C rpc_createrr() A global variable whose value is set by any RPC client handle creation routine that fails. This routine is used by .C clnt_pcreateerror() to print the reason for the failure. .RE .SH AUTHOR .CR rpc (3C) was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(3C), rpc(3C), rpc_clnt_auth(3C), rpc_clnt_calls(3C), rpc_svc_create(3C) .\" .\" index@\f4rpc_clnt_create(3C)\f1 \- library of routines for the creation and manipulation of client handles@@@\f3rpc(3C)\f1 .\" index@\f4clnt_control()\f1 \- change or retrieve client-object information@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clnt_create()\f1 \- create client handle on remote host@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clnt_create_vers()\f1 \- create client handle on remote host with available version number@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clnt_destroy()\f1 \- destroy RPC client handle and deallocate data structures@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clnt_pcreateerror()\f1 \- print standard error; client handle could not be created@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clntraw_create()\f1 \- create RPC client for remote program@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clnt_spcreateerror()\f1 \- return error-message string; client handle could not be created@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clnttcp_create()\f1 \- create handle for remote TCP/IP program@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clntudp_bufcreate()\f1 \- create handle for remote UDP/IP program@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4clntudp_create()\f1 \- creates handle for remote UDP/IP program@@@\f3rpc_clnt_create(3C)\f1 .\" index@\f4rpc_createrr()\f1 \- global variable set by any RPC client-handle creation routine that fails@@@\f3rpc_clnt_create(3C)\f1 .\" .\" toc@\f3rpc_clnt_create(3C)\f1:\0\0\f4rpc_clnt_create\f1@@@library of routines for the creation and manipulation of client handles .\" .\" links@rpc_clnt_create.3c rpc_createrr.3c .\" $Header: rpc_svc_calls.3c,v 74.1 95/05/10 21:56:31 ssa Exp $ .TA r .TH rpc_svc_calls 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME registerrpc, svc_register, svc_unregister, xprt_register, xprt_unregister \- library routines for registering servers .SH SYNOPSIS .C "#include " .PP .nf .C /* registerrpc */ .C "int" .C "registerrpc(prognum, versnum, procnum, procname, inproc, outproc)" .C "u_long prognum, versnum, procnum;" .C "char *(*procname) ();" .C "xdrproc_t inproc, outproc;" .fi .PP .nf .C "/* svc_register */" .C "bool_t" .C "svc_register(xprt, prognum, versnum, dispatch, protocol)" .C "SVCXPRT *xprt;" .C "u_long prognum, versnum;" .C "void (*dispatch) ();" .C "u_long protocol;" .fi .PP .nf .C "/* svc_unregister */ .C "void" .C "svc_unregister(prognum, versnum)" .C "u_long prognum, versnum;" .fi .PP .nf .C /* xprt_register */ .C "void" .C "xprt_register(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* xprt_unregister */" .C "void" .C "xprt_unregister(xprt)" .C "SVCXPRT *xprt;" .fi .SH DESCRIPTION These routines are a part of the RPC library, which allows the RPC servers to register themselves with .IR portmap (1M), and it associates the given program and version number with the dispatch function. .SS Routines .PP To use these routines, the C programs must include the header file .CR . .PP The .C SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP 20 .C registerrpc Register procedure .I procname with the RPC service package. If a request arrives for program .IR prognum , version .IR versnum , and procedure .IR procnum , .I procname is called with a pointer to its parameter; .I progname must be a procedure that returns a pointer to its static result; .I inproc is used to decode the parameters while .I outproc is used to encode the results. This routine returns 0 if the registration succeeded, \-1 otherwise. .IP .BR Warning : Remote procedures registered in this form are accessed using the UDP/IP transport; see .C svcudp_create() on .IR rpc_svc_create (3C) for restrictions. This routine should not be used more than once for the same program and version number. .TP .C svc_register Associates .I prognum and .I versnum with the service dispatch procedure, .IR dispatch . If .I protocol is zero, the service is not registered with the .C portmap service. If .I protocol is non-zero, a mapping of the triple .RI [ "prognum, versnum, protocol"\f1] to .C xprt->xp_port is established with the local .C portmap service (generally .I protocol is zero, .C IPPROTO_UDP or .CR IPPROTO_TCP ). The procedure .I dispatch has the following form: .RS 2i .PP .nf .C "dispatch(request, xprt)" .C "struct svc_req *request;" .C "SVCXPRT *xprt;" .ft R .fi .RE .IP The .B svc_register() routine returns .C TRUE if it succeeds, and .C FALSE otherwise. .TP .C svc_unregister Remove all mapping of the pair .RI [ prognum , versnum ] to dispatch routines, and of the triple .RI [ prognum , versnum , *\f1] to port number. .TP .C xprt_register After RPC service transport handles are created, they should register themselves with the RPC service package. This routine modifies the global variable .IR svc_fds . Service implementors usually do not need this routine. .TP .C xprt_unregister Before an RPC service transport handle is destroyed, it should unregister itself with the RPC service package. This routine modifies the global variable .IR svc_fds . Service implementors usually do not need this routine directly. .SH AUTHOR .C rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M), portmap(3C), rpc(3C), rpc_svc_err(3C), rpc_svc_create(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3rpc_svc_calls(3C)\f1:\0\0\f4registerrpc()\f1,\f4svc_register()\f1, \f4svc_unregister()\f1, \f4xprt_register()\f1,\n \f4xprt_unregister()\f1@@@library routines for registering servers .\" toc@\f4registerrpc()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4svc_register()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4svc_unregister()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4xprt_register()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4xprt_unregister()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" index@\f4rpc_svc_calls(3C)\f1library routines for registering servers@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4registerrpc()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4svc_register()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4svc_unregister()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4xprt_register()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4xprt_unregister()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" links@rpc_svc_calls.3c registerrpc.3c .\" links@rpc_svc_calls.3c svc_register.3c .\" links@rpc_svc_calls.3c svc_unregister.3c .\" links@rpc_svc_calls.3c xprt_register.3c .\" links@rpc_svc_calls.3c xprt_unregister.3c .\" $Header: rpc_svc_create.3c,v 72.2 94/09/20 17:40:07 ssa Exp $ .TA r .TH rpc_svc_create 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_destroy, svcfd_create, svcraw_create, svctcp_create, svcudp_bufcreate \- library routines for dealing with the creation of server handles .SH SYNOPSIS .C "#include " .PP .nf .C "/* svc_destroy */" .C "void" .C "svc_destroy(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcfd_create */" .C "SVCXPRT *" .C "svcfd_create(fd, sendsz, recvsz)" .C "int fd;" .C "u_int sendsz, recvsz;" .fi .PP .nf .C "/* svcraw_create() */" .C "SVCXPRT *" .C "svcraw_create()" .fi .PP .nf .C "/* svctcp_create */" .C "SVCXPRT *" .C "svctcp_create(sock, sendsz, recvsz)" .C "int sock;" .C "u_int sendsz, recvsz;" .fi .PP .nf .C "/* svcudp_bufcreate */" .C "SVCXPRT *" .C "svcudp_bufcreate(sock, sendsz, recvsz)" .C "int sock;" .C "u_int sendsz, recvsz;" .fi .SH DESCRIPTION .PP RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .SS Routines .PP To run these routines, the C programs must include the header file, .CR . .PP The .CR SVCXPRT data structure is defined in .IR "Power Programming with RPC" . .TP 20 .C "svc_destroy" Destroy the RPC service transport handle, .IR xprt . Destruction usually involves deallocation of private data structures, including .I xprt itself. Use of .I xprt is undefined after calling this routine. .TP .C svcfd_create Create a service on top of any open and bound descriptor and return the handle to it. Typically, this descriptor is a connected socket for a stream protocol such as TCP. .I sendsz and .I recvsz indicate sizes for the send and receive buffers. If they are zero, a reasonable default is chosen. It returns .C NULL if it fails. .TP .C "svcraw_create()" Create an RPC service transport, to which it returns a pointer. The transport is a buffer within the process's address space, so the corresponding RPC client must live in the same address space; see .C clntraw_create() on .IR rpc_clnt_create (3C). This routine allows simulation of RPC and getting RPC overheads (such as round trip times), without any kernel interference. This routine returns .C NULL if it fails. .TP .C "svctcp_create" Create a TCP/IP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket .IR sock . If sock is .CR RPC_ANYSOCK , then a new socket is created. If the socket is not bound to a local TCP port, then this routine binds it to an arbitrary port. Upon completion, \f3\%xprt\->xp_sock\f1 is the transport's socket descriptor, and \f3\%xprt\->xp_port\f1 is the port number on which it is listening. This routine returns .C NULL if it fails. Since TCP-based RPC uses buffered I/O, users may specify the size of buffers with .I sendsz and .IR recvsz ; values of zero choose defaults. .TP .C "svcudp_bufcreate" Create a UDP/IP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket .IR sock . If sock is .CR RPC_ANYSOCK , a new socket is created. If the socket is not bound to a local UDP port, this routine binds it to an arbitrary port. Upon completion, \f3\%xprt\->xp_sock\f1 is the service's socket descriptor, and \f3\%xprt\->xp_port\f1 is the service's port number. This routine returns .C NULL if it fails. .IP The user specifies the maximum packet size for sending and receiving UDP-based RPC messages by using the .I sendsz and .I recvsz parameters. .br .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M), rpc(3C), rpc_clnt_create(3C), rpc_svc_calls(3C), rpc_svc_err(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3rpc_svc_create(3C)\f1:\0\0\f4svc_destroy()\f1,\f4svcraw_create()\f1, \f4svcfd_create()\f1, \f4svctcp_create()\f1,\n \f4svcudp_bufcreate()\f1@@@library routines for registering servers .\" toc@\f4svc_destroy()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcraw_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcfd_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svctcp_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcudp_bufcreate()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" index@\f4rpc_svc_create(3C)\f1library routines for dealing with the creation of server handles@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svc_destroy()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcraw_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcfd_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcudp_bufcreate()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svctcp_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" links@rpc_svc_create.3c svc_destroy.3c .\" links@rpc_svc_create.3c svcraw_create.3c .\" links@rpc_svc_create.3c svcfd_create.3c .\" links@rpc_svc_create.3c svcudp_bufcreate.3c .\" links@rpc_svc_create.3c svctcp_create.3c .\" $Header: rpc_svc_err.3c,v 74.1 95/05/10 21:11:51 ssa Exp $ .TA r .TH rpc_svc_err 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog, svcerr_progvers, svcerr_systemerr, svcerr_weakauth \- library routines for server-side remote procedure call errors .SH SYNOPSIS .PP .nf .C "#include " .PP .nf .C "/* svcerr_auth */" .C "void" .C "svcerr_auth(xprt, why)" .C "SVCXPRT *xprt;" .C "enum auth_stat why;" .fi .PP .nf .C "/* svcerr_decode */" .C "void" .C "svcerr_decode(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_noproc */" .C "void" .C "svcerr_noproc(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_noprog */" .C "void" .C "svcerr_noprog(xprt)" .C "SVCXPRT *xprt;" .fi .PP .C "/* svcerr_progvers */" .nf .C "void" .C "svcerr_progvers(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_systemerr */" .C "void" .C "svcerr_systemerr(xprt)" .C "SVCXPRT *xprt;" .fi .PP .C "/* svcerr_weakauth */" .nf .C "void" .C "svcerr_weakauth(xprt)" .C "SVCXPRT *xprt;" .fi .SH DESCRIPTION .PP RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines can be called by the server side dispatch function if there is any error in the transaction with the client. .SS Routines The following routines require that the header file .RC < rpc.h > be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC" . .TP 20 .C svcerr_auth Called by a service dispatch routine that refuses to perform a remote procedure call, due to an authentication error. .TP .C "svcerr_decode" Called by a service dispatch routine that cannot successfully decode the remote parameters. See .CR svc_getargs() in .IR rpc_svc_reg (3C). .TP .C "svcerr_noproc" Called by a service dispatch routine that does not implement the procedure number the caller requests. .TP .C "svcerr_noprog" Called when the desired program is not registered with the RPC package. Service implementors usually do not need this routine. .TP .C "svcerr_progvers" Called when the desired version of a program is not registered with the RPC package. Service implementors usually do not need this routine. .TP .C "svcerr_systemerr" Called by a service dispatch routine when it detects a system error not covered by any particular protocol. For example, if a service can no longer allocate storage, it may call this routine. .TP .C "svcerr_weakauth" Called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient authentication parameters. The routine calls .CR "svcerr_auth(xprt, AUTH_TOOWEAK)" . .SH AUTHOR .C rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO rpc(3C), rpc_svc_calls(3C), rpc_svc_create(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3 rpc_svc_err(3C)\f1:\0\0\f4svcerr_auth()\f1,\f4svcerr_decode()\f1, \f4svcerr_noproc()\f1, \f4svcerr_progvers()\f1, \n \f4svcerr_systemerr()\f1, \f4svcerr_weakauth\f1 \n@@@library routines for server-side remote procedure call errors .\" toc@\f4svcerr_auth()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_decode()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_noproc()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_progvers()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_systemerr()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_weakauth()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" index@\f4rpc_svc_err(3C)\f1library routines for server-side RPC errors@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_auth()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_weakauth()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_decode()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_noproc()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_progvers()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_systemerr()\f1@@@\f3rpc_svc_err(3C)\f1 .\" links@rpc_svc_err.3c svcerr_auth.3c .\" links@rpc_svc_err.3c svcerr_weakauth.3c .\" links@rpc_svc_err.3c svcerr_decode.3c .\" links@rpc_svc_err.3c svcerr_noproc.3c .\" links@rpc_svc_err.3c svcerr_progvers.3c .\" links@rpc_svc_err.3c svcerr_systemerr.3c .\" $Header: rpc_svc_reg.3c,v 74.1 95/05/10 21:56:57 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_svc_reg 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_fds, svc_fdset, svc_freeargs, svc_getargs, svc_getcaller, svc_getreq, svc_getreqset, svc_run, svc_sendreply \- library routines for RPC servers .SH DESCRIPTION .B RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines are associated with the server side of the .B RPC mechanism. Some of them are called by the server side dispatch function, while others (such as .BR svc_run() ) are called when the server is initiated. .SS Routines The following routines require that the header .BR be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "int svc_fds;" .fi .IP Similar to .BR svc_fdset , but limited to 32 descriptors. This interface is obsoleted by .BR svc_fdset . .PP .nf .C "fd_set svc_fdset;" .fi .IP A global variable reflecting the .B RPC server's read file descriptor bit mask; it is suitable as a parameter to the .B select() system call. This is only of interest if a service implementor does not call .BR svc_run() , but rather does their own asynchronous event processing. This variable is read-only (do not pass its address to .BR select() !), yet it may change after calls to .B svc_getreqset() or any creation routines. .PP .nf .C "bool_t" .C "svc_freeargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Free any data allocated by the .B RPC/XDR system when it decoded the arguments to a service procedure using .BR svc_getargs() . This routine returns .B TRUE if the results were successfully freed, and .B FALSE otherwise. .PP .nf .C "bool_t" .C "svc_getargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Decode the arguments of an .B RPC request associated with the .B RPC service transport handle, .IR xprt . The parameter .I in is the address where the arguments will be placed; .I inproc is the .B XDR routine used to decode the arguments. This routine returns .B TRUE if decoding succeeds, and .B FALSE otherwise. .PP .nf .C "struct sockaddr_in *" .C "svc_getcaller(xprt)" .C "SVCXPRT *xprt;" .fi .IP The approved way of getting the network address of the caller of a procedure associated with the .B RPC service transport handle, .IR xprt . .PP .nf .C "void" .C "svc_getreq(rdfds)" .C "int rdfds;" .fi .IP Similar to .BR svc_getreqset() , but limited to 32 descriptors. This interface is obsoleted by .BR svc_getreqset() . .PP .nf .C "void" .C "svc_getreqset(rdfdsp)" .C "fd_set *rdfdsp;" .fi .IP This routine is only of interest if a service implementor does not use .BR svc_run() , but instead implements custom asynchronous event processing. It is called when the .B select() system call has determined that an .B RPC request has arrived on some .B RPC .B socket(s); .I rdfdsp is the resultant read file descriptor bit mask. The routine returns when all sockets associated with the value of .I rdfdsp have been serviced. .PP .nf .C "void" .C "svc_run()" .fi .IP Normally, this routine only returns in the case of some errors. It waits for .B RPC requests to arrive, and calls the appropriate service procedure using .B svc_getreq() when one arrives. This procedure is usually waiting for a .B select() system call to return. .PP .nf .C "bool_t" .C "svc_sendreply(xprt,outproc, out)" .C "SVCXPRT *xprt;" .C "xdrproc_t outproc;" .C "char *out;" .fi .IP Called by an .B RPC service's dispatch routine to send the results of a remote procedure call. The parameter .I xprt is the request's associated transport handle; .I outproc is the .B XDR routine which is used to encode the results; and .I out is the address of the results. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_sev_reg was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR select (2), .BR rpc (3C), .BR rpc_svc_calls (3C), .BR rpc_svc_create (3C), .BR rpc_svc_err (3C) .\" toc@\f3rpc_svc_reg(3C)\f1:\0\0\f4svc_fds()\f1, \f4svc_fdset()\f1, \f4svc_freeargs()\f1, \f4svc_getargs()\f1, \f4svc_getcaller()\f1, \n\f4svc_getreg()\f1, \f4svc_getreqset()\f1, \f4svc_run()\f1, \f4svc_sendreply()\f1@@@library routines for RPC servers .\" toc@\f4rpc_svc_reg()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fds()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fdset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_freeargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getcaller()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getreq()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_setreqset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_run()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_sednreply()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" index@library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4rpc_svc_reg()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fds()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fdset()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_freeargs()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getargs()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getcaller()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreq()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreqset()\fP \- library routines for RPC servers @@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_run()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_sendreply()\fP \- library routines for RPC servers@@@\f3rpc_scv_reg(3C)\f1 .\" links@rpc_svc_reg.3c svc_fds.3c .\" links@rpc_svc_reg.3c svc_fdset.3c .\" links@rpc_svc_reg.3c svc_freeargs.3c .\" links@rpc_svc_reg.3c svc_getargs.3c .\" links@rpc_svc_reg.3c svc_getcaller.3c .\" links@rpc_svc_reg.3c svc_getreq.3c .\" links@rpc_svc_reg.3c svc_getreqset.3c .\" links@rpc_svc_reg.3c svc_run.3c .\" links@rpc_svc_reg.3c svc_sendreply.3c .\" $Header: rpc_xdr.3c,v 74.1 95/05/10 21:57:15 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_xdr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_accepted_reply, xdr_authunix_parms, xdr_callhdr, xdr_callmsg, xdr_opaque_auth, xdr_rejected_reply, xdr_replymsg \- XDR library routines for remote procedure calls .SH DESCRIPTION These routines are used for describing the .B RPC messages in .B XDR language. They should normally be used by those who do not want to use the .B RPC package. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_accepted_reply(xdrs, arp)" .C "XDR *xdrs;" .C "struct accepted_reply *arp;" .fi .IP Used for encoding .B RPC reply messages. It encodes the status of the .B RPC call in the .B XDR language format and in the case of success, it encodes the call results as well. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_authunix_parms(xdrs, aup)" .C "XDR *xdrs;" .C "struct authunix_parms *aup;" .fi .IP Used for describing .B UNIX credentials. It includes machine name, user .B ID, group .B ID list, etc. This routine is useful for users who wish to generate these credentials without using the .B RPC authentication package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_callhdr(xdrs, chdrp)" .C "XDR *xdrs;" .C "struct rpc_msg *chdrp;" .fi .IP Used for describing .B RPC call header messages. It encodes the static part of the call message header in the .B XDR language format. It includes information such as transaction .B ID, .B RPC version number, program number, and version number. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. .PP .nf .C "bool_t" .C "xdr_callmsg(xdrs, cmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *cmsgp;" .fi .IP Used for describing .B RPC call messages. It includes all the .B RPC call information such as transaction .B ID, .B RPC version number, program number, version number, authentication information, etc. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque_auth(xdrs, ap)" .C "XDR *xdrs;" .C "struct opaque_auth *ap;" .fi .IP Used for describing .B RPC authentication information messages. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_rejected_reply(xdrs, rrp)" .C "XDR *xdrs;" .C "struct rejected_reply *rrp;" .fi .IP Used for describing .B RPC reply messages. It encodes the rejected .B RPC message in the .B XDR language format. The message is rejected either because of version number mismatch or because of authentication errors. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_replymsg(xdrs, rmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *rmsgp;" .fi .IP Used for describing .B RPC reply messages. It encodes the .B RPC reply message in the .B XDR language format. This reply could be an acceptance, rejection, or .B NULL. This routine is useful for users who wish to generate .B RPC style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR rpc (3C) .\" toc@\f3rpc_xdr(3C)\f1:\0\0\f4xdr_accepted_reply()\f1, \f4xdr_authunix_parms()\f1, \f4xdr_callhdr()\f1, \n\f4xdr_callmsg()\f1, \f4xdr_opaque_auth()\f1, \f4xdr_rejected_reply()\f1, \n\f4xdr_replymsg()\f1@@@XDR library routines for remote procedure calls .\" toc@\f4rpc_xdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_accepted_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_authunix_parms()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callhdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callmsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_opaque_auth()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_rejected_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_replymsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" index@XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4rpc_accepted_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_authunix_parms()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_callhdr()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr3C)\f1 .\" index@\f4xdr_callmsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_opaque_auth()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_rejected_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_replymsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" links@rpc_xdr.3c xdr_accepted_reply.3c .\" links@rpc_xdr.3c xdr_authunix_parms.3c .\" links@rpc_xdr.3c xdr_callhdr.3c .\" links@rpc_xdr.3c xdr_callmsg.3c .\" links@rpc_xdr.3c xdr_opaque_auth.3c .\" links@rpc_xdr.3c xdr_rejected_reply.3c .\" links@rpc_xdr.3c xdr_replymsg.3c .\" $Header: rcmd.3n,v 72.5 94/12/09 15:04:46 ssa Exp $ .TA r .TH rcmd 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rcmd(), rresvport(), ruserok() \- return a stream to a remote command .SH SYNOPSIS .nf .C "int rcmd(" .C " char **ahost," .C " int remport," .C " const char *locuser," .C " const char *remuser," .C " const char *cmd," .C " int *fd2p);" .PP .C "int rresvport(int *port);" .PP .C "int ruserok(" .C " const char *rhost," .C " int superuser," .C " const char *ruser," .C " const char *luser);" .fi .SH DESCRIPTION .SS rcmd() The .CR rcmd() function is used by privileged programs to execute a command on a remote host. .CR rcmd() returns a file descriptor for the socket to which the standard input and standard output of the command are attached. A command level interface to .CR rcmd() is provided by .CR remsh (see .IR remsh (1)), which is the same as the BSD .CR rsh command. .PP .IR ahost is a pointer to the address of the remote host name. The name of the remote host can be either an official host name or an alias as understood by .CR gethostbyname() (see .IR gethostent (3N), .IR named (1M), and .IR hosts (4)). .PP .IR remport is the Internet port on the remote system, which .CR rcmd() will try to connect to. .PP .I locuser and .I remuser point to the user login name on the local host and on the remote host, respectively. The names are used by the server on the remote host to authenticate the user (see .CR ruserok() below). .PP .I cmd points to a string that specifies the command to be executed on the remote host. .PP .IR fd2p is a pointer to an integer (it can be a NULL pointer). .PP .CR rcmd() looks up the host .CI * ahost using .CR gethostbyname() , returning \(mi1 if the host does not exist. Otherwise, .CI * ahost is set to the standard name of the host and a connection is established to a server accepting requests at the port .IR remport . If the connection is refused after five tries, or if it was refused for a reason other than the port being in use, .CR rcmd() returns \(mi1. .PP If the call succeeds, a socket of type SOCK_STREAM is returned to the caller and given to the remote command as .CR stdin and .CR stdout . If .I fd2p is non-NULL, .CR rcmd() opens a second socket between the calling process (local) and the control process (remote), and places its descriptor in .CI * fd2p\f1. On this connection, the control process sends the diagnostic output .RC ( stderr ) from .I cmd to the calling process, and receives UNIX signals from the calling process, to be forwarded to .IR cmd . If the auxiliary port cannot be set up, .CR rcmd() returns \(mi1. If .I fd2p is NULL, .CR stderr of the remote command is made the same as .CR stdout , and no provision is made for sending arbitrary signals to the remote process. .PP The protocol is described in detail in .IR remshd (1M). .PP Any program using .CR rcmd() must be run as superuser. .SS rresvport() The .CR rresvport() function creates a socket and binds it to a reserved port. This socket is suitable for use by .CR rcmd() and several other routines. .PP The caller is expected to set the initial value of .CI * port to a number between 512 and .CR IPPORT_RESERVED \(mi1. (The value of .CR IPPORT_RESERVED is defined in .CR netinet/in.h and is 1024.) Typically, the initial value of .CI * port is set to .CR IPPORT_RESERVED \(mi1. If the value is outside the valid range, .CR rresvport() resets it silently to .CR IPPORT_RESERVED \(mi1. The function uses the inital value of .CI * port as the first port number that it tries to .I bind to the created socket. If the operation fails, .CR rresvport() decrements .CI * port and attempts to .I bind the new port number to the socket. The process is repeated until either the operation succeeds, or the port numbers between 512 and .CR IPPORT_RESERVED \(mi1 are exhausted. .PP If the call succeeds, the socket descriptor is returned to the caller and the port number is returned in the location pointed to by .IR port . If the call fails, \(mi1 is returned to the caller. .PP The socket returned by .CR rresvport() has the .CR SO_KEEPALIVE option on. .PP Only the superuser is permitted to bind a privileged address to a socket. Therefore, any program using .CR rresvport() must be run as superuser. .SS ruserok() The .CR ruserok() function is used by servers to authenticate clients requesting service with .CR rcmd() . .CR ruserok() verifies that .I ruser on .I rhost is authorized to act as .I luser on the local host. .PP .I superuser is an integer flag that should be nonzero if the local user name corresponds to a superuser. If the .I superuser flag is not set, .CR ruserok() first checks the file .CR /etc/hosts.equiv to authenticate the request for service. If this check succeeds, .CR ruserok() returns 0. If the .I superuser flag is set, or if there is no file .CR /etc/hosts.equiv , or if the check fails, .CR ruserok() then checks the file .CR .rhosts (if there is one) in the local user's home directory. .CR ruserok() returns 0 if this check succeeds. Otherwise, it returns \(mi1. .PP Typically, the file .CR /etc/hosts.equiv contains a list of host names, and users' .CR .rhosts files contain host-name/user-name pairs. A remote user is authenticated by .CR ruserok() if the remote host name appears in .CR /etc/hosts.equiv and the remote user name and local user name are the same, or if the remote host name and the remote user name appear together in .CR .rhosts in the home directory of the local user. .PP For a complete explanation of the syntax understood by .CR ruserok() , see .IR hosts.equiv (4). .SH DIAGNOSTICS .SS rcmd() Diagnostic Messages .CR rcmd() generates the following diagnostic messages. .RS .TP .IC hostname ": Unknown host" .IP .I gethostbyname was unable to find an entry in the hosts database matching the name of the server (see .IR gethostent (3N) and .IR hosts (4)). .IP .IR "Next step" : Have the system administrator of your host check whether the remote host's entry is in the .CR hosts database (see .IR hosts (4)). .TP .CI "connect: \&" hostname ": \&" \f1...\& .IP Unable to establish a connection to the reserved port. A message that specifies the reason for the failure is appended to this diagnostic message. .TP .C "write: Setting up stderr" .IP Error writing to the socket connection set up for error message transmission. .TP .IC "system call" ": \&" \f1...\& .IP Error executing the system call. Appended to this error is a message specifying the reason for the failure. .TP .C "socket: Protocol failure in circuit setup" .IP Socket connection not established on a reserved port or socket address not of the Internet family type. .TP .CI "read: " hostname ": \&" \f1...\& .IP Error in reading information from the standard socket connection. Appended to this error is a message explaining the reason for the error. .TP .C "Connection timeout" .IP The remote host did not connect within 30 seconds to the secondary socket set up as an error connection. .TP .C "Lost connection" .IP The program attempted to read from the socket and failed. This means the socket connection with the remote host was lost. .TP .IR message \f1...\& .IP An error message can be transmitted through the socket connection from the daemon. That message will be sent to .CR stderr . .TP .C "primary connection shutdown" .IP While waiting for the secondary socket to be set up, .CR rcmd() had its primary connection shut down. This may have been caused by an .I inetd security failure. .TP .CR "recv: \&" ...\& .IP While trying to set up the secondary .RC ( stderr ) socket, .CR rcmd() had an error condition on its primary connection. .TP .C "accept: Interrupted system call" .IP While trying to set up its secondary socket, .CR rcmd() ran out of some resource that caused the accept to be timed out. .IP .IR "Next step" : Repeat the command. .RE .SS rresvport() Diagnostic Messages .CR rresvport() generates the following diagnostic messages. These messages can also appear in .CR rcmd() since .CR rcmd() calls .CR rresvport() . .RS .TP .IC "system call" ": \&" \f1...\& .IP Error in executing the system call. The error message returned by the system call is appended to the message. .TP .C "socket: All ports in use" .IP All reserved ports in use. If a timeout occurs, check whether the Internet Services are installed and .CR inetd is running. .RE .SH EXAMPLES To execute the .CR date command on remote host .CR hpxzgy using the remote account .CR chm , call .CR rcmd() as shown below. This program requires superuser privileges and the remote account must be equivalent (see .IR hosts.equiv (4)) to the local account that runs the program. .nf .IP .ift .ft 4 .ifn .ft 3 .ps +1 \#include \#include \#include \#include \#include \#include .ift .sp .5v .ifn .sp struct passwd *getpwuid(); char *host[] = { "hpxzgy" }; char *cmd = "date"; char *ruser = "chm"; .ift .sp .5v .ifn .sp main(argc,argv) int argc; char **argv; { struct servent *sp; struct passwd *pwd; FILE *fp; char ch; int rem; .ift .sp .5v .ifn .sp sp = getservbyname("shell","tcp"); pwd = getpwuid(getuid()); rem = rcmd(host, sp\->s_port, pwd\->pw_name, ruser, cmd, 0); if (rem < 0) exit(1); /* rcmd outputs its own error messages */ fp = fdopen(rem, "r"); while ((ch = getc(fp)) != EOF) putchar(ch); } .ft .ps .fi .SH WARNINGS There is no way to specify options to the .CR socket() call that .CR rcmd() makes. Since .CR rcmd() replaces the pointer to the host name .RC ( * \f2ahost\f1) with a pointer to the standard name of the host in a static data area, this value must be copied into the user's data area if it is to be used later. Otherwise, unpredictable results will occur. .SH AUTHOR .CR rcmd() was developed by the University of California, Berkeley. .SH SEE ALSO login(1), rlogin(1), remsh(1), named(1M), remshd(1M), rexecd(1M), gethostent(3N), rexec(3N), hosts.equiv(4). .\" .\" index@\f4rcmd()\f1 \- execute a command on a remote host@@@\f3rcmd(3N)\f1 .\" index@\f4resvport()\f1 \- return a reserved port socket@@@\f3rcmd(3N)\f1 .\" index@\f4ruserok()\f1 \- verify a remote user as a local user@@@\f3rcmd(3N)\f1 .\" index@\f1execute a command on a remote host@@@\f3rcmd(3N)\f1 .\" index@\f1command on a remote host, execute a@@@\f3rcmd(3N)\f1 .\" index@\f1remote host, execute a command on a@@@\f3rcmd(3N)\f1 .\" index@\f1return a reserved port socket@@@\f3rcmd(3N)\f1 .\" index@\f1reserved port socket, return a@@@\f3rcmd(3N)\f1 .\" index@\f1port socket, return a reserved@@@\f3rcmd(3N)\f1 .\" index@\f1socket, return a reserved port@@@\f3rcmd(3N)\f1 .\" index@\f1verify a remote user as a local user@@@\f3rcmd(3N)\f1 .\" index@\f1local user, verify a remote user as a@@@\f3rcmd(3N)\f1 .\" index@\f1remote user, verify as a local user@@@\f3rcmd(3N)\f1 .\" .\" index@return a stream to a remote command@@@\f3rcmd(3N)\f1 .\" index@stream, return to a remote command@@@\f3rcmd(3N)\f1 .\" index@remote command, return a stream to@@@\f3rcmd(3N)\f1 .\" index@command, remote, return a stream to@@@\f3rcmd(3N)\f1 .\" .\" links@rcmd.3n rresvport.3n .\" links@rcmd.3n ruserok.3n .\" .\" toc@\f3rcmd(3N)\f1:\0\0\f4rcmd()\f1, \f4rresvport()\f1, \f4ruserok()\f1@@@return a stream to a remote command .\" toc@\f4rresvport()\f1:\0\0return a stream to a remote command@@@see \f3rcmd(3N)\f1 .\" toc@\f4ruserok()\f1:\0\0return a stream to a remote command@@@see \f3rcmd(3N)\f1 .\" $Header: rstat.3n,v 72.4 94/06/30 15:46:12 ssa Exp $ .TA r .TH rstat 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rstat(\|), havedisk(\|) \- get performance data from remote kernel .SH SYNOPSIS .C #include .br .C #include .PP .C "int havedisk(char *host);" .PP .C "int rstat(char *host, struct statstime *statp);" .SH DESCRIPTION .CR havedisk() returns .CR 1 if .I host has a disk, .CR 0 if it does not, and \(mi1 if this cannot be determined. The .I host string is either the official name of the host or an alias for it. See .IR hosts (4) for more information regarding host names. .PP .CR rstat() fills in the .I statstime structure for .IR host , and returns .CR 0 if it was successful. The relevant structures are: .PP .RS .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct stats { /* RSTATVERS_ORIG */ int cp_time[CPUSTATES]; /* the time spent in each CPU state */ int dk_xfer[DK_NDRIVE]; /* total number of disk transfers on each of the disk interfaces */ unsigned v_pgpgin; /* total VM pages paged in */ unsigned v_pgpgout; /* total VM pages paged out */ unsigned v_pswpin; /* total VM pages paged swapped in */ unsigned v_pswpout; /* total VM pages paged swapped out */ unsigned v_intr; /* total interrupts */ int if_ipackets; /* inbound packets on all interfaces */ int if_ierrors; /* inbound errors on all interfaces */ int if_opackets; /* outbound packets on all interfaces */ int if_oerrors; /* outbound errors on all interfaces */ int if_collisions; /* collisions seen on all interfaces */ }; .sp struct statsswtch { /* RSTATVERS_SWTCH */ int cp_time[CPUSTATES]; /* the time spent in each CPU state */ int dk_xfer[DK_NDRIVE]; /* total number of disk transfers on each of the disk interfaces */ unsigned v_pgpgin; /* total VM pages paged in */ unsigned v_pgpgout; /* total VM pages paged out */ unsigned v_pswpin; /* total VM pages paged swapped in */ unsigned v_pswpout; /* total VM pages paged swapped out */ unsigned v_intr; /* total interrupts */ int if_ipackets; /* inbound packets on all interfaces */ int if_ierrors; /* inbound errors on all interfaces */ int if_opackets; /* outbound packets on all interfaces */ int if_oerrors; /* outbound errors on all interfaces */ int if_collisions; /* collisions seen on all interfaces */ unsigned v_swtch; /* total context switches */ long avenrun[3]; /* average number of running jobs */ struct timeval boottime; /* time of last boot */ }; .sp struct statstime { /* RSTATVERS_TIME */ int cp_time[CPUSTATES]; /* the time spent in each CPU state */ int dk_xfer[DK_NDRIVE]; /* total number of disk transfers on each of the disk interfaces */ unsigned v_pgpgin; /* total VM pages paged in */ unsigned v_pgpgout; /* total VM pages paged out */ unsigned v_pswpin; /* total VM pages paged swapped in */ unsigned v_pswpout; /* total VM pages paged swapped out */ unsigned v_intr; /* total interrupts */ int if_ipackets; /* inbound packets on all interfaces */ int if_ierrors; /* inbound errors on all interfaces */ int if_opackets; /* outbound packets on all interfaces */ int if_oerrors; /* outbound errors on all interfaces */ int if_collisions; /* collisions seen on all interfaces */ unsigned v_swtch; /* total context switches */ long avenrun[3]; /* average number of running jobs */ struct timeval boottime; /* time of last boot */ struct timeval curtime; /* current system time */ }; .ft .ps .fi .RE .SS \s-1RPC\s0 Info .RS .nf program number: \s-1RSTATPROG\s+1 .PP xdr routines: int xdr_stats(xdrs, stat) \s-1XDR\s+1 *xdrs; struct stats *stat; int xdr_statsswtch(xdrs, stat) \s-1XDR\s+1 *xdrs; struct statsswtch *stat; int xdr_statstime(xdrs, stat) \s-1XDR\s+1 *xdrs; struct statstime *stat; int xdr_timeval(xdrs, tv) \s-1XDR\s+1 *xdrs; struct timeval *tv; .PP procs: \s-1RSTATPROC_HAVEDISK\s+1 Takes no arguments, returns \f2long\fP which is true if remote host has a disk. \s-1RSTATPROC_STATS\s+1 Takes no arguments, return \f2struct statsxxx\fP, depending on version. versions: \s-1RSTATVERS_ORIG\s+1 \s-1RSTATVERS_SWTCH\s+1 \s-1RSTATVERS_TIME\s+1 .fi .RE .SH WARNINGS User applications that call this routine must be linked with .CR /usr/lib/librpcsvc.a . For example, .IP .C cc my_source.c -lrpcsvc .SH AUTHOR .CR rstat() was developed by Sun Microsystems, Inc. .SH SEE ALSO rup(1), rstatd(1M). .\" .\" index@\f4rstat()\fP \- get performance data from remote kernel@@@\f3rstat(3N)\f1 .\" index@\f4havedisk()\fP \- get performance data from remote kernel@@@\f3rstat(3N)\f1 .\" index@performance data from remote kernel, get@@@\f3rstat(3N)\f1 .\" index@remote kernel, get performance data from@@@\f3rstat(3N)\f1 .\" index@kernel, remote, get performance data from@@@\f3rstat(3N)\f1 .\" .\" toc@\f3rstat(3N)\f1: \f4rstat()\fP, \f4havedisk()\fP@@@get performance data from remote kernel .\" .\" links@rstat.3n havedisk.3n .\" $Header: rcmd.3n,v 72.5 94/12/09 15:04:46 ssa Exp $ .TA r .TH rcmd 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rcmd(), rresvport(), ruserok() \- return a stream to a remote command .SH SYNOPSIS .nf .C "int rcmd(" .C " char **ahost," .C " int remport," .C " const char *locuser," .C " const char *remuser," .C " const char *cmd," .C " int *fd2p);" .PP .C "int rresvport(int *port);" .PP .C "int ruserok(" .C " const char *rhost," .C " int superuser," .C " const char *ruser," .C " const char *luser);" .fi .SH DESCRIPTION .SS rcmd() The .CR rcmd() function is used by privileged programs to execute a command on a remote host. .CR rcmd() returns a file descriptor for the socket to which the standard input and standard output of the command are attached. A command level interface to .CR rcmd() is provided by .CR remsh (see .IR remsh (1)), which is the same as the BSD .CR rsh command. .PP .IR ahost is a pointer to the address of the remote host name. The name of the remote host can be either an official host name or an alias as understood by .CR gethostbyname() (see .IR gethostent (3N), .IR named (1M), and .IR hosts (4)). .PP .IR remport is the Internet port on the remote system, which .CR rcmd() will try to connect to. .PP .I locuser and .I remuser point to the user login name on the local host and on the remote host, respectively. The names are used by the server on the remote host to authenticate the user (see .CR ruserok() below). .PP .I cmd points to a string that specifies the command to be executed on the remote host. .PP .IR fd2p is a pointer to an integer (it can be a NULL pointer). .PP .CR rcmd() looks up the host .CI * ahost using .CR gethostbyname() , returning \(mi1 if the host does not exist. Otherwise, .CI * ahost is set to the standard name of the host and a connection is established to a server accepting requests at the port .IR remport . If the connection is refused after five tries, or if it was refused for a reason other than the port being in use, .CR rcmd() returns \(mi1. .PP If the call succeeds, a socket of type SOCK_STREAM is returned to the caller and given to the remote command as .CR stdin and .CR stdout . If .I fd2p is non-NULL, .CR rcmd() opens a second socket between the calling process (local) and the control process (remote), and places its descriptor in .CI * fd2p\f1. On this connection, the control process sends the diagnostic output .RC ( stderr ) from .I cmd to the calling process, and receives UNIX signals from the calling process, to be forwarded to .IR cmd . If the auxiliary port cannot be set up, .CR rcmd() returns \(mi1. If .I fd2p is NULL, .CR stderr of the remote command is made the same as .CR stdout , and no provision is made for sending arbitrary signals to the remote process. .PP The protocol is described in detail in .IR remshd (1M). .PP Any program using .CR rcmd() must be run as superuser. .SS rresvport() The .CR rresvport() function creates a socket and binds it to a reserved port. This socket is suitable for use by .CR rcmd() and several other routines. .PP The caller is expected to set the initial value of .CI * port to a number between 512 and .CR IPPORT_RESERVED \(mi1. (The value of .CR IPPORT_RESERVED is defined in .CR netinet/in.h and is 1024.) Typically, the initial value of .CI * port is set to .CR IPPORT_RESERVED \(mi1. If the value is outside the valid range, .CR rresvport() resets it silently to .CR IPPORT_RESERVED \(mi1. The function uses the inital value of .CI * port as the first port number that it tries to .I bind to the created socket. If the operation fails, .CR rresvport() decrements .CI * port and attempts to .I bind the new port number to the socket. The process is repeated until either the operation succeeds, or the port numbers between 512 and .CR IPPORT_RESERVED \(mi1 are exhausted. .PP If the call succeeds, the socket descriptor is returned to the caller and the port number is returned in the location pointed to by .IR port . If the call fails, \(mi1 is returned to the caller. .PP The socket returned by .CR rresvport() has the .CR SO_KEEPALIVE option on. .PP Only the superuser is permitted to bind a privileged address to a socket. Therefore, any program using .CR rresvport() must be run as superuser. .SS ruserok() The .CR ruserok() function is used by servers to authenticate clients requesting service with .CR rcmd() . .CR ruserok() verifies that .I ruser on .I rhost is authorized to act as .I luser on the local host. .PP .I superuser is an integer flag that should be nonzero if the local user name corresponds to a superuser. If the .I superuser flag is not set, .CR ruserok() first checks the file .CR /etc/hosts.equiv to authenticate the request for service. If this check succeeds, .CR ruserok() returns 0. If the .I superuser flag is set, or if there is no file .CR /etc/hosts.equiv , or if the check fails, .CR ruserok() then checks the file .CR .rhosts (if there is one) in the local user's home directory. .CR ruserok() returns 0 if this check succeeds. Otherwise, it returns \(mi1. .PP Typically, the file .CR /etc/hosts.equiv contains a list of host names, and users' .CR .rhosts files contain host-name/user-name pairs. A remote user is authenticated by .CR ruserok() if the remote host name appears in .CR /etc/hosts.equiv and the remote user name and local user name are the same, or if the remote host name and the remote user name appear together in .CR .rhosts in the home directory of the local user. .PP For a complete explanation of the syntax understood by .CR ruserok() , see .IR hosts.equiv (4). .SH DIAGNOSTICS .SS rcmd() Diagnostic Messages .CR rcmd() generates the following diagnostic messages. .RS .TP .IC hostname ": Unknown host" .IP .I gethostbyname was unable to find an entry in the hosts database matching the name of the server (see .IR gethostent (3N) and .IR hosts (4)). .IP .IR "Next step" : Have the system administrator of your host check whether the remote host's entry is in the .CR hosts database (see .IR hosts (4)). .TP .CI "connect: \&" hostname ": \&" \f1...\& .IP Unable to establish a connection to the reserved port. A message that specifies the reason for the failure is appended to this diagnostic message. .TP .C "write: Setting up stderr" .IP Error writing to the socket connection set up for error message transmission. .TP .IC "system call" ": \&" \f1...\& .IP Error executing the system call. Appended to this error is a message specifying the reason for the failure. .TP .C "socket: Protocol failure in circuit setup" .IP Socket connection not established on a reserved port or socket address not of the Internet family type. .TP .CI "read: " hostname ": \&" \f1...\& .IP Error in reading information from the standard socket connection. Appended to this error is a message explaining the reason for the error. .TP .C "Connection timeout" .IP The remote host did not connect within 30 seconds to the secondary socket set up as an error connection. .TP .C "Lost connection" .IP The program attempted to read from the socket and failed. This means the socket connection with the remote host was lost. .TP .IR message \f1...\& .IP An error message can be transmitted through the socket connection from the daemon. That message will be sent to .CR stderr . .TP .C "primary connection shutdown" .IP While waiting for the secondary socket to be set up, .CR rcmd() had its primary connection shut down. This may have been caused by an .I inetd security failure. .TP .CR "recv: \&" ...\& .IP While trying to set up the secondary .RC ( stderr ) socket, .CR rcmd() had an error condition on its primary connection. .TP .C "accept: Interrupted system call" .IP While trying to set up its secondary socket, .CR rcmd() ran out of some resource that caused the accept to be timed out. .IP .IR "Next step" : Repeat the command. .RE .SS rresvport() Diagnostic Messages .CR rresvport() generates the following diagnostic messages. These messages can also appear in .CR rcmd() since .CR rcmd() calls .CR rresvport() . .RS .TP .IC "system call" ": \&" \f1...\& .IP Error in executing the system call. The error message returned by the system call is appended to the message. .TP .C "socket: All ports in use" .IP All reserved ports in use. If a timeout occurs, check whether the Internet Services are installed and .CR inetd is running. .RE .SH EXAMPLES To execute the .CR date command on remote host .CR hpxzgy using the remote account .CR chm , call .CR rcmd() as shown below. This program requires superuser privileges and the remote account must be equivalent (see .IR hosts.equiv (4)) to the local account that runs the program. .nf .IP .ift .ft 4 .ifn .ft 3 .ps +1 \#include \#include \#include \#include \#include \#include .ift .sp .5v .ifn .sp struct passwd *getpwuid(); char *host[] = { "hpxzgy" }; char *cmd = "date"; char *ruser = "chm"; .ift .sp .5v .ifn .sp main(argc,argv) int argc; char **argv; { struct servent *sp; struct passwd *pwd; FILE *fp; char ch; int rem; .ift .sp .5v .ifn .sp sp = getservbyname("shell","tcp"); pwd = getpwuid(getuid()); rem = rcmd(host, sp\->s_port, pwd\->pw_name, ruser, cmd, 0); if (rem < 0) exit(1); /* rcmd outputs its own error messages */ fp = fdopen(rem, "r"); while ((ch = getc(fp)) != EOF) putchar(ch); } .ft .ps .fi .SH WARNINGS There is no way to specify options to the .CR socket() call that .CR rcmd() makes. Since .CR rcmd() replaces the pointer to the host name .RC ( * \f2ahost\f1) with a pointer to the standard name of the host in a static data area, this value must be copied into the user's data area if it is to be used later. Otherwise, unpredictable results will occur. .SH AUTHOR .CR rcmd() was developed by the University of California, Berkeley. .SH SEE ALSO login(1), rlogin(1), remsh(1), named(1M), remshd(1M), rexecd(1M), gethostent(3N), rexec(3N), hosts.equiv(4). .\" .\" index@\f4rcmd()\f1 \- execute a command on a remote host@@@\f3rcmd(3N)\f1 .\" index@\f4resvport()\f1 \- return a reserved port socket@@@\f3rcmd(3N)\f1 .\" index@\f4ruserok()\f1 \- verify a remote user as a local user@@@\f3rcmd(3N)\f1 .\" index@\f1execute a command on a remote host@@@\f3rcmd(3N)\f1 .\" index@\f1command on a remote host, execute a@@@\f3rcmd(3N)\f1 .\" index@\f1remote host, execute a command on a@@@\f3rcmd(3N)\f1 .\" index@\f1return a reserved port socket@@@\f3rcmd(3N)\f1 .\" index@\f1reserved port socket, return a@@@\f3rcmd(3N)\f1 .\" index@\f1port socket, return a reserved@@@\f3rcmd(3N)\f1 .\" index@\f1socket, return a reserved port@@@\f3rcmd(3N)\f1 .\" index@\f1verify a remote user as a local user@@@\f3rcmd(3N)\f1 .\" index@\f1local user, verify a remote user as a@@@\f3rcmd(3N)\f1 .\" index@\f1remote user, verify as a local user@@@\f3rcmd(3N)\f1 .\" .\" index@return a stream to a remote command@@@\f3rcmd(3N)\f1 .\" index@stream, return to a remote command@@@\f3rcmd(3N)\f1 .\" index@remote command, return a stream to@@@\f3rcmd(3N)\f1 .\" index@command, remote, return a stream to@@@\f3rcmd(3N)\f1 .\" .\" links@rcmd.3n rresvport.3n .\" links@rcmd.3n ruserok.3n .\" .\" toc@\f3rcmd(3N)\f1:\0\0\f4rcmd()\f1, \f4rresvport()\f1, \f4ruserok()\f1@@@return a stream to a remote command .\" toc@\f4rresvport()\f1:\0\0return a stream to a remote command@@@see \f3rcmd(3N)\f1 .\" toc@\f4ruserok()\f1:\0\0return a stream to a remote command@@@see \f3rcmd(3N)\f1 .\" $Header: rnusers.3n,v 72.4 94/06/30 15:56:56 ssa Exp $ .TA r .TH rnusers 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rnusers(\|), rusers(\|) \- return information about users on remote machines .SH SYNOPSIS .C #include .br .C #include .PP .C "int rnusers(char \(**host);" .PP .C "int rusers(char \(**host, struct utmpidlearr \(**up);" .SH DESCRIPTION .TP 15 .CR rnusers() returns the number of users logged in on .I host or \(mi1 if it cannot determine that number. The .I host string is either the official name of the host or an alias for it. See .IR hosts (4) for more information regarding host names. .TP .CR rusers() fills in the .CR utmpidlearr structure with data about .IR host and returns 0 if successful. The .CR ut_line field is limited to eight characters on Berkeley systems, so the HP-UX XDR routine truncates from 12 characters to 8. The .CR nonuser() macro does not exist in the HP-UX .CR utmp.h file; therefore, HP-UX windows appear as separate users. .PP The relevant structures are: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmparr { /* RUSERSVERS_ORIG */ struct utmp **uta_arr; int uta_cnt; }; .sp struct utmpidle { struct utmp ui_utmp; unsigned ui_idle; }; .sp struct utmpidlearr { /* RUSERSVERS_IDLE */ struct utmpidle **uia_arr; int uia_cnt; }; .ft .ps .fi .RE .SS \s-1RPC\s0 Information .RS .nf program number: \s-1RUSERSPROG\s+1 .PP xdr routines: int xdr_utmp(xdrs, up) \s-1XDR\s+1 \(**xdrs; struct utmp \(**up; int xdr_utmpidle(xdrs, ui) \s-1XDR\s+1 \(**xdrs; struct utmpidle \(**ui; int xdr_utmpptr(xdrs, up) \s-1XDR\s+1 \(**xdrs; struct utmp \(**\(**up; int xdr_utmpidleptr(xdrs, up) \s-1XDR\s+1 \(**xdrs; struct utmpidle \(**\(**up; int xdr_utmparr(xdrs, up) \s-1XDR\s+1 \(**xdrs; struct utmparr \(**up; int xdr_utmpidlearr(xdrs, up) \s-1XDR\s+1 \(**xdrs; struct utmpidlearr \(**up; .PP procs: \s-1RUSERSPROC_NUM\s+1 No arguments, returns number of users as an \f2unsigned long\fP. \s-1RUSERSPROC_NAMES\s+1 No arguments, returns \f2utmparr\fP or \f2utmpidlearr\fP, depending on version number. \s-1RUSERSPROC_ALLNAMES\s+1 No arguments, returns \f2utmparr\fP or \f2utmpidlearr\fP, depending on version number. Returns listing even for \f2utmp\fP entries satisfying \f2nonuser()\fP in \f2utmp.h\fP. .PP versions: \s-1RUSERSVERS_ORIG\s+1 \s-1RUSERSVERS_IDLE\s+1 structures: .fi .RE .SH WARNINGS User applications that call this routine must be linked with .CR /usr/lib/librpcsvc.a . For example, .IP .C cc my_source.c -lrpcsvc .SH AUTHOR .CR rnusers() was developed by Sun Microsystems, Inc. .SH SEE ALSO rusers(1). .\" .\" index@\f4rnusers()\fP: return information about users on remote machines@@@\f3rnusers(3N)\f1 .\" index@\f4rusers()\fP: return information about users on remote machines@@@\f3rnusers(3N)\f1 .\" index@return information about users on remote machines@@@\f3rnusers(3N)\f1 .\" index@information about users on remote machines, return@@@\f3rnusers(3N)\f1 .\" index@users on remote machines, return information about@@@\f3rnusers(3N)\f1 .\" index@remote machines, return information about users on@@@\f3rnusers(3N)\f1 .\" index@machines, return information about users on remote@@@\f3rnusers(3N)\f1 .\" .\" toc@\f3rnusers(3N)\f1: \f4rnusers()\fP, \f4rusers()\fP@@@return information about users on remote machines .\" .\" links@rnusers.3n rusers.3n .\" $Header: rwall.3n,v 72.4 94/06/30 15:00:22 ssa Exp $ .TA r .TH rwall 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rwall(\|) \- write to specified remote machines .SH SYNOPSIS .C #include .PP .C "int rwall(char *host, char *msg);" .SH DESCRIPTION .CR rwall() causes .I host to print the string .I msg to all its users. It returns 0 if successful. .SS \s-1RPC\s0 Info .nf program number: \s-1WALLPROG\s+1 .PP procs: \s-1WALLPROC_WALL\s+1 Takes string as argument (wrapstring), returns no arguments. Executes \f2wall\fP on remote host with string. versions: \s-1RSTATVERS_ORIG\s+1 .SH WARNINGS User applications that call this routine must be linked with .CR /usr/lib/librpcsvc.a . For example, .IP .C cc my_source.c -lrpcsvc .SH AUTHOR .CR rwall() was developed by Sun Microsystems, Inc. .SH SEE ALSO rwall(1M), rwalld(1M), shutdown(1M). .\" index@\f4rwall()\fP: write to specified remote machines@@@\f3rwall(3N)\f1 .\" index@write to specified remote machines@@@\f3rwall(3N)\f1 .\" index@specified remote machines, write to@@@\f3rwall(3N)\f1 .\" index@remote machines, write to specified@@@\f3rwall(3N)\f1 .\" index@machines, write to specified remote@@@\f3rwall(3N)\f1 .\" toc@\f3rwall(3N)\f1: \f4rwall()\fP@@@write to specified remote machines .\" $Header: resetty.3x,v 76.2 95/08/01 14:38:44 ssa Exp $ .TA r .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH resetty 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME resetty, savetty \(em save/restore terminal mode .SH SYNOPSIS .C "#include " .P .C "int resetty(void);" .P .C "int savetty(void);" .SH DESCRIPTION The .Fn resetty function restores the program mode as of the most recent call to .CR savetty() . .P The .Fn savetty function saves the state that would be put in place by a call to .CR reset_prog_mode() . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" def_prog_mode(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn resetty and .Fn savetty functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3resetty(3X)\f1:\0\0\f4resetty()\f1, \f4savetty()\f1@@@save/restore terminal mode .\" toc@\f4savetty()\f1: save/restore terminal mode@@@see \f3resetty(3X)\f1 .\" .\" index@\f4resetty()\f1 \- save/restore terminal mode@@@\f3resetty(3X)\f1 .\" index@\f4savetty()\f1 \- save/restore terminal mode@@@\f3resetty(3X)\f1 .\" index@\f1save/restore terminal mode@@@\f3resetty(3X)\f1 .\" index@\f1restore terminal mode@@@\f3resetty(3X)\f1 .\" index@\f1terminal mode, save/restore@@@\f3resetty(3X)\f1 .\" .\" links@resetty.3x savetty.3x .\" .\" fileset_database@resetty.3x CURS-ENG-A-MAN .\" $Header: scalb.3m,v 78.1 96/02/13 13:44:29 ssa Exp $ .TA s .TH scalb 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scalb(\|) \- load exponent of a radix-independent floating-point number .SH SYNOPSIS .C "#include " .PP .C "double scalb(double x, double n);" .SH DESCRIPTION The .CR scalb() function returns .ift .IR x " \(** " r\u\s-2n\s+2\d , .ifn .IR x " \(** " r "**" n , where .I r is the radix of the machine's floating-point arithmetic. When .I r is 2, .CR scalb() is equivalent to .CR ldexp() . .PP To use this function, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH "RETURN VALUE" Upon successful completion, the .CR scalb() function returns .ift .IR x " \(** " r\u\s-2n\s+2\d . .ifn .IR x " \(** " r "**" n . .PP If .I x is NaN, .CR scalb() returns NaN. .PP If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR scalb() returns .IR x . .PP If the correct value would overflow, .CR scalb() returns .ift .CR \(+-HUGE_VAL .ifn .CR +\-HUGE_VAL (according to the sign of .IR x ) and sets .CR errno to [ERANGE]. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR scalb() returns zero and sets .CR errno to [ERANGE]. .SH "ERRORS" If .CR scalb() fails, .CR errno is set to one of the following values. .RS .TP 20 [ERANGE] The correct value would overflow. .TP 20 [ERANGE] The correct value after rounding would be smaller in magnitude than .CR MINDOUBLE . .RE .SH "SEE ALSO" isinf(3M), isnan(3M), ldexp(3M), values(5). .SH STANDARDS CONFORMANCE .CR scalb() ": SVID3, XPG4.2" .\" index@\f4scalb()\f1 \- load exponent of a radix-independent floating-point number@@@\f3scalb(3M)\f1 .\" index@\f1radix-independent floating-point number, load exponent of@@@\f3scalb(3M)\f1 .\" index@\f1load exponent of a radix-independent floating-point number@@@\f3scalb(3M)\f1 .\" index@\f1math: load exponent of a radix-independent floating-point number@@@\f3scalb(3M)\f1 .\" index@\f1floating-point: load exponent of a radix-independent floating-point number@@@\f3scalb(3M)\f1 .\" .\" toc@\f3scalb(3M)\f1:\0\0\f4scalb()\f1@@@load exponent of a radix-independent floating-point number .\" $Header: scandir.3c,v 72.3 93/01/14 14:51:05 ssa Exp $ .TA s .TH scandir 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scandir(\|), alphasort(\|) \- scan a directory .SH SYNOPSIS .C "#include " .P .C "int scandir(" .nf .PD 0 .IP .C "const char *dirname," .C "struct dirent **namelist," .C "int (*select)(const struct dirent * const *)," .C "int (*compar)(" .RS .IP .C "const struct dirent * const *," .C "const struct dirent * const *" .RE .IP .C ")" .P .C ");" .PD .P .C "int alphasort(" .PD 0 .IP .C "const struct dirent * const *d1," .C "const struct dirent * const *d2" .P .C ");" .PD .fi .SH DESCRIPTION .C scandir() reads the directory .I dirname and builds an array of pointers to directory entries using .C malloc() (see .IR malloc (3C)). It returns the number of entries in the array and a pointer to the array through .IR namelist . .PP The .I select parameter is a pointer to a user-supplied subroutine which is called by .C scandir() to select which entries are to be included in the array. The select routine is passed a pointer to a directory entry and should return a non-zero value if the directory entry is to be included in the array. If .I select is null, then all the directory entries will be included. .PP The .I compar parameter is a pointer to a user-supplied subroutine which is passed to .IR qsort (3C) to sort the completed array. If this pointer is null, the array is not sorted. .C alphasort() is a routine which can be used for the .I compar parameter to sort the array alphabetically. .PP The memory allocated for the array can be deallocated with .C free() (see .IR malloc (3C)) by freeing each pointer in the array and the array itself. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by .CR alphasort() . See .IR hpnls (5) for a description of supported collation features. .PP The .C LC_CTYPE category determines the interpretation of bytes in the file name portion of directory entries as single- and/or multi-byte characters by the .C alphasort() function. .PP Results are undefined if the locales specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .SS International Code Set Support Single- and multi-byte character code sets are supported for .CR alphasort() . .SH RETURN VALUE .C scandir() returns \-1 if the directory cannot be opened for reading or if .CR malloc() cannot allocate enough memory to hold all the data structures. .SH EXAMPLE The example program below scans the .C /tmp directory. It does not exclude any entries since .I select is .SM NULL. The contents of .C namelist are sorted by .CR alphasort() . It prints out how many entries are in .C /tmp and the sorted entries of the .C /tmp directory. The memory used by .C scandir() is returned using .CR free() . .RS .PP .nf .ift .ft 4 .ifn .ft 3 .ps +1 #include #include #include extern int scandir(); extern int alphasort(); main() { int num_entries, i; struct dirent **namelist, **list; if ((num_entries = scandir("/tmp", &namelist, NULL, alphasort)) < 0) { fprintf(stderr, "Unexpected error\en"); exit(1); } printf("Number of entries is %d\en", num_entries); if (num_entries) { printf("Entries are:"); for (i=0, list=namelist; id_name); free(\(**list); \(**list++; } free(namelist); printf("\en"); } printf("\en"); exit(0); } .ps .ft .fi .RE .SH SEE ALSO directory(3C), malloc(3C), qsort(3C), string(3C), dirent(5), hpnls(5). .\" .\" index@\f4scandir()\fP \- scan a directory@@@\f3scandir(3C)\f1 .\" index@directory: scan a directory@@@\f3scandir(3C)\f1 .\" index@scan a directory@@@\f3scandir(3C)\f1 .\" index@directory, scan a@@@\f3scandir(3C)\f1 .\" index@\f4alphasort()\fP \- sort a directory pointer array@@@\f3scandir(3C)\f1 .\" index@sort a directory pointer array@@@\f3scandir(3C)\f1 .\" index@directory pointer array, sort a@@@\f3scandir(3C)\f1 .\" index@pointer array, sort a directory@@@\f3scandir(3C)\f1 .\" index@array, sort a directory pointer@@@\f3scandir(3C)\f1 .\" .\" toc@\f3scandir(3C)\f1:\0\0\f4scandir()\fP, \f4alphasort()\fP@@@scan a directory .\" toc@\f4alphasort()\fP \- sort a directory pointer array@@@see \f3scandir(3C)\f1 .\" .\" links@scandir.3c alphasort.3c .\" .\" fileset_database@scandir.3c PROGRAMING-MAN .\" $Header: scanf.3s,v 72.7 94/12/08 12:16:59 ssa Exp $ .TA s .TH scanf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scanf, fscanf, sscanf \- formatted input conversion, read from stream file .SH SYNOPSIS .C "#include " .PP .C "int scanf(const char *format, /* [pointer,] */ ...);" .PP .C "int fscanf(FILE *stream, const char *format, /* [pointer,] */ ...);" .PP .C "int sscanf(const char *s, const char *format, /* [pointer,] */ ...);" .SH DESCRIPTION .C scanf() reads from the standard input stream .IR stdin . .PP .C fscanf() reads from the named input .IR stream . .PP .C sscanf() reads from the character string .IR s . .PP Each function reads characters, interprets them according to the control string .I format argument, and stores the results in its .I pointer arguments. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are ignored. The control string contains conversion specifications and other characters used to direct interpretation of input sequences. The control string contains: .RS .TP 3 \(bu White-space characters (blanks, tabs, newlines, or formfeeds) that cause input to be read up to the next non-white-space character (except in two cases described below). .TP \(bu An ordinary character (not .CR % ) that must match the next character of the input stream. .TP \(bu Conversion specifications, consisting of the character .CR % , an optional assignment suppressing character .CR * , an optional numerical maximum-field width, an optional .C l (ell), .CR ll , (ell ell), .C h or .C L indicating the size of the receiving variable, and a conversion code. .TP \(bu The conversion specification can alternatively be prefixed by the character sequence .CI % n $ instead of the character .CR % , where .I n is a decimal integer in the range .RC (1\|\(mi\| {NL_ARGMAX} ) .RC ( NL_ARGMAX is defined in .RC < limits.h >). The .CI % n $ construction indicates that the value of the next input field should be placed in the .IR n th argument, rather than to the next unused one. The two forms of introducing a conversion specification, .C % and .CI % n $\f1, must not be mixed within a single .I format string with the following exception: Skip fields (see below) can be designated as .C %* or .CI % n $*\f1. In the latter case, .I n is ignored. .RE .PP Unless the specification contains the .C n conversion character (described below), a conversion specification directs the conversion of the next input field. The result of a conversion specification is placed in the variable to which the corresponding argument points, unless .C * indicates assignment suppression. Assignment suppression provides a way to describe an input field to be skipped. An input field is defined as a string of non-space characters; it extends to the next inappropriate character or until the field width, if specified, is exhausted. For all descriptors except .C [ and .CR c , white space leading an input field is ignored. .PP The conversion code indicates the interpretation of the input field; the corresponding pointer argument must be of a restricted type. For a suppressed field, no pointer argument is given. The following conversion codes are legal: .RS .TP 12 .C % A single .C % is expected in the input at this point; no assignment is done. .TP .C d A decimal integer is expected; the corresponding argument should be an integer pointer. .TP .C u An unsigned decimal integer is expected; the corresponding argument should be an unsigned integer pointer. .TP .C o An octal integer is expected; the corresponding argument should be an unsigned integer pointer. .TP .CR x ,\0 X A hexadecimal integer is expected; the corresponding argument should be an unsigned integer pointer. The .C x and .C X conversion characters are equivalent. .TP .C i An integer is expected; the corresponding argument should be an integer pointer. The value of the next input item, interpreted according to C conventions, will be stored; a leading .C 0 implies octal, a leading .C 0x implies hexadecimal; otherwise, decimal is assumed. .TP .C n Cause the total number of bytes (including white space) scanned since the function call to be stored; the corresponding argument should be an integer pointer. No input is consumed. The function return value does not include .CI % n assignments in the count of successfully matched and assigned input items. .TP .ift \s+1\f4e\fP,\f3E\fP,\f3f\fP,\f3g\fP,\f3G\fP\s0 .ifn \f3e\fP,\f3E\fP,\f3f\fP,\f3g\fP,\f3G\fP A floating-point number is expected; the next field is converted accordingly and stored through the corresponding argument, which should be a pointer to a .IR float . The input format for floating-point numbers is an optionally signed string of digits, possibly containing a radix character, followed by an optional exponent field consisting of an .C E or an .CR e , followed by an optional .CR + , .CR - , or space, followed by an integer. The conversion characters .C E and .C G behave the same as, respectively, .C e and .CR g . .TP .C C A character is expected; the corresponding argument should be a .C wchar_t pointer. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use .CR %1S . The character is read and converted into a wide character according to the setting of .CR LC_CTYPE . If a field width is given, the corresponding argument refers to a wide character array; the indicated number of characters is read and converted. .TP .C c A character is expected; the corresponding argument should be a character pointer. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use .CR %1s . If a field width is given, the corresponding argument refers to a character array; the indicated number of characters is read. .TP .C S A character string is expected; the corresponding argument should be a .C wchar_t pointer pointing to an array of wide characters large enough to accept the string and a terminating .CR (wchar_t)0 , which is added automatically. Characters are read and converted into wide characters according to the setting of .CR LC_CTYPE . The input field is terminated by a white-space character. .C scanf() cannot read a null string. .TP .C s A character string is expected; the corresponding argument should be a character pointer pointing to an array of characters large enough to accept the string and a terminating .CR \e0 , which is added automatically. The input field is terminated by a white-space character. .C scanf() cannot read a null string. .TP .C [ Indicates string data and the normal skip-over-leading-white-space is suppressed. The left bracket is followed by a set of characters, called the .IR scanset , and a right bracket; the input field is the maximal sequence of input characters consisting entirely of characters in the scanset. The circumflex .RC ( ^ ), when it appears as the first character in the scanset, serves as a complement operator and redefines the scanset as the set of all characters .IR not contained in the remainder of the scanset string. Construction of the .I scanset follows certain conventions. A range of characters may be represented by the construct .IR first\-last , enabling [0123456789] to be expressed [0\-9]. Using this convention, .IR first must be lexically less than or equal to .IR last ; otherwise, the dash stands for itself. The dash also stands for itself when it is the first or the last character in the scanset. To include the right square bracket as an element of the scanset, it must appear as the first character (possibly preceded by a circumflex) of the scanset, in which case it will not be interpreted syntactically as the closing bracket. The corresponding argument must point to a character array large enough to hold the data field and the terminating .CR \e0 , which are added automatically. At least one character must match for this conversion to succeed. .TP .C p A sequence of unsigned hexadecimal numbers is expected. This sequence may be produced by the .C p conversion character of .CR printf() . The corresponding argument shall be a pointer to a pointer to .C void into which the value represented by the hexadecimal sequence is stored. The behavior of this conversion is undefined for any input item other than a value converted earlier during the same program execution. .PP The conversion characters .CR d , .CR i , and .C n can be preceded by .CR l , .CR ll or .CR h to indicate that a pointer to a .CR long .CR int , .CR long .CR long .CR int or .CR short .CR int rather than to an .CR int is in the argument list. Similarly, the conversion characters .CR u , .CR o , .CR x , and .CR X can be preceded by .CR l , .CR ll or .CR h to indicate that a pointer to .CR unsigned .CR long .CR int , .CR unsigned .CR long .CR long .CR int , or .CR unsigned .CR short .CR int rather than to an .CR unsigned .CR int , is in the argument list. Finally, the conversion characters .CR e , .CR E , .CR f , .CR g , and .CR G can be preceded by .CR l or .CR L to indicate that a pointer to a .CR double or .CR long .CR double rather than to a .CR float is in the argument list. The .CR l , .CR ll , .CR L or .CR h modifier is ignored for other conversion characters. .PP The .CR scanf() functions terminate their conversions at .SM EOF, at the end of the control string, or when an input character conflicts with the control string. In the latter case, the offending character is left unread in the input stream. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of ordinary characters within format strings as single and/or multi-byte characters. Field width is given in terms of bytes. Characters received from the input stream are interpreted as single- or multi-byte characters as determined by the .CR LC_TYPE category and the field width is decremented by the length of the character. .PP The .CR LC_NUMERIC category determines the radix character expected within floating-point numbers. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUES If the input ends before the first conflict or conversion, .SM EOF is returned. Otherwise, these functions return the number of successfully assigned input items. This number is a short count, or even zero if a conflict ensues between an input character and the control string. .SH ERRORS .CR scanf() and .CR fscanf() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP .SM [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP .SM [EIO] The process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RE .PP Additional .CR errno values can be set by the underlying .CR read() function (see .IR read (2)). .SH EXAMPLES The call: .IP .CR "int i, n; float x; char name[50];" .br .ift \f4\s+1n = scanf("%d%f%s", &i, &x, name);\s0\fP .ifn \f3n = scanf("%d%f%s", &i, &x, name);\fP .PP with the input line: .IP .CR "25 54.32E-1 thompson" .PP assigns to .I n the value .CR 3 , to .I i the value .CR 25 , to .I x the value .CR 5.432 , and .I name contains .CR thompson\e0 . Or: .IP .CR "int i; float x; char name[50];" .br .ift \f4\s+1(void) scanf("%2d%f%*d %[0\-9]", &i, &x, name);\s0\fP .ifn \f3(void) scanf("%2d%f%*d %[0\-9]", &i, &x, name);\fP .PP with input: .IP .CR "56789 0123 56a72" .PP assigns .CR 56 to .IR i , .CR 789.0 to .IR x , skips .CR 0123 , and places the string .CR 56\e0 in .IR name . The next call to .CR getchar() (see .IR getc (3S)) returns .CR a . .PP For another example, to create a language-independent date scanning routine, use: .IP .CR "char month[20]; int day, year;" .br .CR "(void) scanf(format, month, &day, &year);" .PP For American usage, .I format would point to a string: .IP .CR "%1$s %2$d %3$d" .PP The input: .IP .CR "July 3 1986" .PP would assign .CR July to .IR month , .CR 3 to .I day and .CR 1986 to .IR year . .PP For German usage, .I format would point to a string: .IP .CR "%2$d %1$s %3$d" .PP The input: .IP 3 Juli 1986 .PP would assign .CR Juli to .IR month , .CR 3 to .I day and .CR 1986 to .IR year . .PP The success of literal matches and suppressed assignments can be determined with the .CR %n conversion specification. Here is an example that checks the success of literal matches: .nf .IP .CR "int i, n1, n2, n3, n4;" .ift .ft 4 .ifn .ft 3 .ps +1 n1 = n2 = n3 = n4 = -1;" scanf( "%nBEGIN%n %d %nEND%n", &n1, &n2, &i, &n3, &n4); if (n2 - n1 == 5) puts( "matched BEGIN"); if (n4 - n3 == 3) puts( "matched END"); .ft .ps .fi .PP Here is an example that checks the success of suppressed assignments: .nf .IP .CR "int i, n1, n2;" .CR "n1 = n2 = -1;" .ift .ft 4 .ifn .ft 3 .ps +1 scanf( "%d %n%*s%n", &i, &n1, &n2); if (n2 > n1) printf( "successful assignment suppression of %d chars\\n", n2 - n1); .ps .ft .SH WARNINGS Trailing white space (including a newline) is left unread unless matched in the control string. .PP Truncation of multi-byte characters may occur if a field width is used with the conversion character. .SH AUTHOR .CR scanf() was developed by AT&T and HP. .SH SEE ALSO getc(3S), setlocale(3C), printf(3S), strtod(3C), strtol(3C). .SH STANDARDS CONFORMANCE .CR scanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fscanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .CR sscanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4scanf()\f1 \- formatted read from \f2standard input\f1 stream file@@@\f3scanf(3S)\f1 .\" index@\f4fscanf()\f1 \- formatted read from named input stream file@@@\f3scanf(3S)\f1 .\" index@\f4sscanf()\f1 \- formatted read from character string@@@\f3scanf(3S)\f1 .\" index@\f4scanf()\f1 \- formatted read from \f2standard input\f1 stream file@@@\f3scanf(3S)\f1 .\" index@\f4fscanf()\f1 \- formatted read from named input stream file@@@\f3scanf(3S)\f1 .\" index@\f4sscanf()\f1 \- formatted read from character string@@@\f3scanf(3S)\f1 .\" index@formatted input conversion, read from stream file or character string@@@\f3scanf(3S)\f1 .\" index@input conversion, formatted read from stream file or character string@@@\f3scanf(3S)\f1 .\" index@formatted read and conversion from stream file or character string@@@\f3scanf(3S)\f1 .\" index@read from stream file or character string with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@stream file or character string, read from with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@file: read from file, stream, or character string with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@character string or stream file, read from with formatted input conversion@@@\f3scanf(3S)\f1 .\" .\" toc@\f3scanf(3S)\f1:\0\0\f4scanf()\fP, \f4fscanf()\fP, \f4sscanf()\f1@@@formatted input conversion, read from stream file .\" toc@\f4fscanf()\fP:\0\0formatted input conversion, read from stream file@@@see \f3scanf(3S)\f1 .\" toc@\f4sscanf()\fP:\0\0formatted input conversion, read from stream file@@@see \f3scanf(3S)\f1 .\" .\" links@scanf.3s fscanf.3s .\" links@scanf.3s sscanf.3s .\" links@scanf.3s nl_scanf.3s .\" links@scanf.3s nl_fscanf.3s .\" links@scanf.3s nl_sscanf.3s .\" $Header: mvscanw.3x,v 76.2 95/08/01 11:58:38 ssa Exp $ .TA m .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH mvscanw 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mvscanw, mvwscanw, scanw, wscanw \(em convert formatted input from a window .SH SYNOPSIS .C "#include " .P .C "int mvscanw(int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int mvwscanw(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int scanw(char *\f2fmt\fP, ...);" .P .C "int wscanw(WINDOW *\f2win\fP, char *\f2fmt\fP, ...);" .SH DESCRIPTION These functions are similar to .CR scanf() . Their effect is as though .Fn mvwgetstr were called to get a multi-byte character string from the current or specified window at the current or specified cursor position, and then .Fn sscanf were used to interpret and convert that string. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" getnstr(), printw(), fscanf() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), wcstombs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity and its name is changed from .Fn scanw to .CR mvscanw() . .\" .\" toc@\f3mvscanw(3X)\f1:\0\0\f4mvscanw()\f1, \f4mvwscanw()\f1, \f4scanw()\f1, \f4wscanw()\f1@@@convert formatted input from a window .\" toc@\f4mvwscanw()\f1: convert formatted input from a window@@@see \f3mvscanw(3X)\f1 .\" toc@\f4scanw()\f1: convert formatted input from a window@@@see \f3mvscanw(3X)\f1 .\" toc@\f4wscanw()\f1: convert formatted input from a window@@@see \f3mvscanw(3X)\f1 .\" .\" index@\f4mvscanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f4mvwscanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f4scanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f4wscanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1formatted input, convert, from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1input, convert formatted, from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1window, convert formatted input from@@@\f3mvscanw(3X)\f1 .\" .\" links@mvscanw.3x mvwscanw.3x .\" links@mvscanw.3x scanw.3x .\" links@mvscanw.3x wscanw.3x .\" .\" fileset_database@mvscanw.3x CURS-ENG-A-MAN .\" $Header: scr_dump.3x,v 76.2 95/08/01 14:40:52 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH scr_dump 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scr_dump, scr_init, scr_restore, scr_set \(em screen file input/output functions .SH SYNOPSIS .C "#include " .P .C "int scr_dump(char *const \f2filename\fP);" .P .C "int scr_init(char *const \f2filename\fP);" .P .C "int scr_restore(char *const \f2filename\fP);" .P .C "int scr_set(char *const \f2filename\fP);" .SH DESCRIPTION The .Fn scr_dump function writes the current contents of the virtual screen to the file named by \f2filename\f1 in an unspecified format. .P The .Fn scr_restore function sets the virtual screen to the contents of the file named by \f2filename\f1, which must have been written using .CR scr_dump() . The next refresh operation restores the screen to the way it looked in the dump file. .P The .Fn scr_init function reads the contents of the file named by \f2filename\f1 and uses them to initialise the Curses data structures to what the terminal currently has on its screen. The next refresh operation bases any updates on this information, unless either of the following conditions is true: .RS .TP 3 .C \(bu The terminal has been written to since the virtual screen was dumped to .I filename .TP .C \(bu The terminfo capabilities .CR rmcup and .CR nrrmc are defined for the current terminal. .RE .P The .Fn scr_set function is a combination of .Fn scr_restore and .CR scr_init() . It tells the program that the information in the file named by \f2filename\f1 is what is currently on the screen, and also what the program wants on the screen. This can be thought of as a screen inheritance function. .SH "RETURN VALUE" On successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn scr_init function is called after .Fn initscr or a .Fn system call to share the screen with another process that has done a .Fn scr_dump after its .Fn endwin call. .P To read a window from a file, call .CR getwin() ; to write a window to a file, call .CR putwin() . .SH "SEE ALSO" delscreen(), doupdate(), endwin(), getwin(), open() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), read() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), write() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3scr_dump(3X)\f1:\0\0\f4scr_dump()\f1, \f4scr_init()\f1, \f4scr_restore()\f1, \f4scr_set()\f1@@@screen file input/output functions .\" toc@\f4scr_init()\f1: screen file input/output functions@@@see \f3scr_dump(3X)\f1 .\" toc@\f4scr_restore()\f1: screen file input/output functions@@@see \f3scr_dump(3X)\f1 .\" toc@\f4scr_set()\f1: screen file input/output functions@@@see \f3scr_dump(3X)\f1 .\" .\" index@\f4scr_dump()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f4scr_init()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f4scr_restore()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f4scr_set()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f1screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f1file, for screen, input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f1functions for screen file input/output@@@\f3scr_dump(3X)\f1 .\" index@\f1input/output functions for screen file@@@\f3scr_dump(3X)\f1 .\" .\" links@scr_dump.3x scr_init.3x .\" links@scr_dump.3x scr_restore.3x .\" links@scr_dump.3x scr_set.3x .\" .\" fileset_database@scr_dump.3x CURS-ENG-A-MAN .\" $Header: scr_dump.3x,v 76.2 95/08/01 14:40:52 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH scr_dump 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scr_dump, scr_init, scr_restore, scr_set \(em screen file input/output functions .SH SYNOPSIS .C "#include " .P .C "int scr_dump(char *const \f2filename\fP);" .P .C "int scr_init(char *const \f2filename\fP);" .P .C "int scr_restore(char *const \f2filename\fP);" .P .C "int scr_set(char *const \f2filename\fP);" .SH DESCRIPTION The .Fn scr_dump function writes the current contents of the virtual screen to the file named by \f2filename\f1 in an unspecified format. .P The .Fn scr_restore function sets the virtual screen to the contents of the file named by \f2filename\f1, which must have been written using .CR scr_dump() . The next refresh operation restores the screen to the way it looked in the dump file. .P The .Fn scr_init function reads the contents of the file named by \f2filename\f1 and uses them to initialise the Curses data structures to what the terminal currently has on its screen. The next refresh operation bases any updates on this information, unless either of the following conditions is true: .RS .TP 3 .C \(bu The terminal has been written to since the virtual screen was dumped to .I filename .TP .C \(bu The terminfo capabilities .CR rmcup and .CR nrrmc are defined for the current terminal. .RE .P The .Fn scr_set function is a combination of .Fn scr_restore and .CR scr_init() . It tells the program that the information in the file named by \f2filename\f1 is what is currently on the screen, and also what the program wants on the screen. This can be thought of as a screen inheritance function. .SH "RETURN VALUE" On successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn scr_init function is called after .Fn initscr or a .Fn system call to share the screen with another process that has done a .Fn scr_dump after its .Fn endwin call. .P To read a window from a file, call .CR getwin() ; to write a window to a file, call .CR putwin() . .SH "SEE ALSO" delscreen(), doupdate(), endwin(), getwin(), open() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), read() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), write() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3scr_dump(3X)\f1:\0\0\f4scr_dump()\f1, \f4scr_init()\f1, \f4scr_restore()\f1, \f4scr_set()\f1@@@screen file input/output functions .\" toc@\f4scr_init()\f1: screen file input/output functions@@@see \f3scr_dump(3X)\f1 .\" toc@\f4scr_restore()\f1: screen file input/output functions@@@see \f3scr_dump(3X)\f1 .\" toc@\f4scr_set()\f1: screen file input/output functions@@@see \f3scr_dump(3X)\f1 .\" .\" index@\f4scr_dump()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f4scr_init()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f4scr_restore()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f4scr_set()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f1screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f1file, for screen, input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f1functions for screen file input/output@@@\f3scr_dump(3X)\f1 .\" index@\f1input/output functions for screen file@@@\f3scr_dump(3X)\f1 .\" .\" links@scr_dump.3x scr_init.3x .\" links@scr_dump.3x scr_restore.3x .\" links@scr_dump.3x scr_set.3x .\" .\" fileset_database@scr_dump.3x CURS-ENG-A-MAN .\" $Header: scr_dump.3x,v 76.2 95/08/01 14:40:52 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH scr_dump 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scr_dump, scr_init, scr_restore, scr_set \(em screen file input/output functions .SH SYNOPSIS .C "#include " .P .C "int scr_dump(char *const \f2filename\fP);" .P .C "int scr_init(char *const \f2filename\fP);" .P .C "int scr_restore(char *const \f2filename\fP);" .P .C "int scr_set(char *const \f2filename\fP);" .SH DESCRIPTION The .Fn scr_dump function writes the current contents of the virtual screen to the file named by \f2filename\f1 in an unspecified format. .P The .Fn scr_restore function sets the virtual screen to the contents of the file named by \f2filename\f1, which must have been written using .CR scr_dump() . The next refresh operation restores the screen to the way it looked in the dump file. .P The .Fn scr_init function reads the contents of the file named by \f2filename\f1 and uses them to initialise the Curses data structures to what the terminal currently has on its screen. The next refresh operation bases any updates on this information, unless either of the following conditions is true: .RS .TP 3 .C \(bu The terminal has been written to since the virtual screen was dumped to .I filename .TP .C \(bu The terminfo capabilities .CR rmcup and .CR nrrmc are defined for the current terminal. .RE .P The .Fn scr_set function is a combination of .Fn scr_restore and .CR scr_init() . It tells the program that the information in the file named by \f2filename\f1 is what is currently on the screen, and also what the program wants on the screen. This can be thought of as a screen inheritance function. .SH "RETURN VALUE" On successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn scr_init function is called after .Fn initscr or a .Fn system call to share the screen with another process that has done a .Fn scr_dump after its .Fn endwin call. .P To read a window from a file, call .CR getwin() ; to write a window to a file, call .CR putwin() . .SH "SEE ALSO" delscreen(), doupdate(), endwin(), getwin(), open() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), read() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), write() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3scr_dump(3X)\f1:\0\0\f4scr_dump()\f1, \f4scr_init()\f1, \f4scr_restore()\f1, \f4scr_set()\f1@@@screen file input/output functions .\" toc@\f4scr_init()\f1: screen file input/output functions@@@see \f3scr_dump(3X)\f1 .\" toc@\f4scr_restore()\f1: screen file input/output functions@@@see \f3scr_dump(3X)\f1 .\" toc@\f4scr_set()\f1: screen file input/output functions@@@see \f3scr_dump(3X)\f1 .\" .\" index@\f4scr_dump()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f4scr_init()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f4scr_restore()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f4scr_set()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f1screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f1file, for screen, input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f1functions for screen file input/output@@@\f3scr_dump(3X)\f1 .\" index@\f1input/output functions for screen file@@@\f3scr_dump(3X)\f1 .\" .\" links@scr_dump.3x scr_init.3x .\" links@scr_dump.3x scr_restore.3x .\" links@scr_dump.3x scr_set.3x .\" .\" fileset_database@scr_dump.3x CURS-ENG-A-MAN .\" $Header: scr_dump.3x,v 76.2 95/08/01 14:40:52 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH scr_dump 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scr_dump, scr_init, scr_restore, scr_set \(em screen file input/output functions .SH SYNOPSIS .C "#include " .P .C "int scr_dump(char *const \f2filename\fP);" .P .C "int scr_init(char *const \f2filename\fP);" .P .C "int scr_restore(char *const \f2filename\fP);" .P .C "int scr_set(char *const \f2filename\fP);" .SH DESCRIPTION The .Fn scr_dump function writes the current contents of the virtual screen to the file named by \f2filename\f1 in an unspecified format. .P The .Fn scr_restore function sets the virtual screen to the contents of the file named by \f2filename\f1, which must have been written using .CR scr_dump() . The next refresh operation restores the screen to the way it looked in the dump file. .P The .Fn scr_init function reads the contents of the file named by \f2filename\f1 and uses them to initialise the Curses data structures to what the terminal currently has on its screen. The next refresh operation bases any updates on this information, unless either of the following conditions is true: .RS .TP 3 .C \(bu The terminal has been written to since the virtual screen was dumped to .I filename .TP .C \(bu The terminfo capabilities .CR rmcup and .CR nrrmc are defined for the current terminal. .RE .P The .Fn scr_set function is a combination of .Fn scr_restore and .CR scr_init() . It tells the program that the information in the file named by \f2filename\f1 is what is currently on the screen, and also what the program wants on the screen. This can be thought of as a screen inheritance function. .SH "RETURN VALUE" On successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn scr_init function is called after .Fn initscr or a .Fn system call to share the screen with another process that has done a .Fn scr_dump after its .Fn endwin call. .P To read a window from a file, call .CR getwin() ; to write a window to a file, call .CR putwin() . .SH "SEE ALSO" delscreen(), doupdate(), endwin(), getwin(), open() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), read() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), write() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3scr_dump(3X)\f1:\0\0\f4scr_dump()\f1, \f4scr_init()\f1, \f4scr_restore()\f1, \f4scr_set()\f1@@@screen file input/output functions .\" toc@\f4scr_init()\f1: screen file input/output functions@@@see \f3scr_dump(3X)\f1 .\" toc@\f4scr_restore()\f1: screen file input/output functions@@@see \f3scr_dump(3X)\f1 .\" toc@\f4scr_set()\f1: screen file input/output functions@@@see \f3scr_dump(3X)\f1 .\" .\" index@\f4scr_dump()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f4scr_init()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f4scr_restore()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f4scr_set()\f1 \- screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f1screen file input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f1file, for screen, input/output functions@@@\f3scr_dump(3X)\f1 .\" index@\f1functions for screen file input/output@@@\f3scr_dump(3X)\f1 .\" index@\f1input/output functions for screen file@@@\f3scr_dump(3X)\f1 .\" .\" links@scr_dump.3x scr_init.3x .\" links@scr_dump.3x scr_restore.3x .\" links@scr_dump.3x scr_set.3x .\" .\" fileset_database@scr_dump.3x CURS-ENG-A-MAN .\" $Header: scrl.3x,v 76.2 95/08/01 14:41:42 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH scrl 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scrl, wscrl \(em enhanced scroll a Curses window functions .SH SYNOPSIS .C "#include " .P .C "int scrl(int \f2n\fP);" .P .C "int wscrl(WINDOW *\f2win\fP, int \f2n\fP);" .SH DESCRIPTION .P The .Fn scrl and .Fn wscrl functions scroll the current or specified window. If \f2n\f1 is positive, the window scrolls \f2n\f1 lines toward the first line. Otherwise, the window scrolls \(mi\f2n\f1 lines toward the last line. .P These functions do not change the cursor position. If scrolling is disabled for the current or specified window, these functions have no effect. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3scrl(3X)\f1:\0\0\f4scrl()\f1, \f4wscrl()\f1@@@enhanced scroll a curses window functions .\" toc@\f4wscrl()\f1: scroll the window, enhanced curses@@@see \f3scrl(3X)\f1 .\" .\" index@\f4scrl()\f1 \- scroll the window, enhanced curses@@@\f3scrl(3X)\f1 .\" index@\f4wscrl()\f1 \- scroll the window, enhanced curses@@@\f3scrl(3X)\f1 .\" index@\f1scroll the window, enhanced curses@@@\f3scrl(3X)\f1 .\" index@\f1window, scroll, enhanced curses@@@\f3scrl(3X)\f1 .\" .\" links@scrl.3x wscrl.3x .\" .\" fileset_database@scrl.3x CURS-ENG-A-MAN .\" $Header: scroll.3x,v 76.2 95/08/01 14:42:40 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH scroll 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scroll \(em scroll a Curses window .SH SYNOPSIS .C "#include " .P .C "int scroll(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn scroll function scrolls \f2win\f1 one line in the direction of the first line. .P This function does not change the cursor position. If scrolling is disabled for the current or specified window, this function has no effect. .SH "RETURN VALUE" Upon successful completion, this function returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO scrl(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" .P This description has been rewritten for clarity, but otherwise its functionality is identical. .\" .\" index@\f4scroll()\f1 \- scroll a curses window@@@\f3scroll(3X)\f1 .\" index@\f1scroll a curses window@@@\f3scroll(3X)\f1 .\" index@\f1window, scroll a curses window@@@\f3scroll(3X)\f1 .\" index@\f1curses window, scroll@@@\f3scroll(3X)\f1 .\" .\" toc@\f3scroll(3X)\f1:\0\0\f4scroll()\f1@@@scroll a curses window .\" .\" fileset_database@scroll.3x CURS-ENG-A-MAN .\" $Header: clearok.3x,v 76.2 95/07/31 17:25:47 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH clearok 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clearok, idlok, leaveok, scrollok, setscrreg, wsetscrreg \(em terminal output control functions .SH SYNOPSIS .C "#include " .P .C "int clearok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int idlok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int leaveok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int scrollok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int setscrreg(int \f2top\fP, int \f2bot\fP);" .P .C "int wsetscrreg(WINDOW *\f2win\fP, int \f2top\fP, int \f2bot\fP);" .SH DESCRIPTION These functions set options that deal with output within Curses. .P The .Fn clearok function assigns the value of .I bf to an internal flag in the specified window that governs clearing of the screen during a refresh. If, during a refresh operation on the specified window, the flag in .I curscr is TRUE or the flag in the specified window is TRUE, then the implementation clears the screen, redraws it in its entirety, and sets the flag to FALSE in .I curscr and in the specified window. The initial state is unspecified. .P The .Fn idlok function specifies whether the implementation may use the hardware insert-line, delete-line, and scroll features of terminals so equipped. If \f2bf\f1 is TRUE, use of these features is enabled. If \f2bf\f1 is FALSE, use of these features is disabled and lines are instead redrawn as required. The initial state is FALSE. .P The .Fn leaveok function controls the cursor position after a refresh operation. If \f2bf\f1 is TRUE, refresh operations on the specified window may leave the terminal's cursor at an arbitrary position. If \f2bf\f1 is FALSE, then at the end of any refresh operation, the terminal's cursor is positioned at the cursor position contained in the specified window. The initial state is FALSE. .P The .Fn scrollok function controls the use of scrolling. If \f2bf\f1 is TRUE, then scrolling is enabled for the specified window, with the consequences discussed in \f3Truncation, Wrapping and Scrolling\f1 in curses_intro. If \f2bf\f1 is FALSE, scrolling is disabled for the specified window. The initial state is FALSE. .P The .Fn setscrreg and .Fn wsetscrreg functions define a software scrolling region in the current or specified window. The \f2top\f1 and \f2bot\f1 arguments are the line numbers of the first and last line defining the scrolling region. (Line 0 is the top line of the window.) If this option and .Fn scrollok are enabled, an attempt to move off the last line of the margin causes all lines in the scrolling region to scroll one line in the direction of the first line. Only characters in the window are scrolled. If a software scrolling region is set and .Fn scrollok is not enabled, an attempt to move off the last line of the margin does not reposition any lines in the scrolling region. .SH "RETURN VALUE" Upon successful completion, .Fn setscrreg and .Fn wsetscrreg return OK. Otherwise, they return ERR. .P The other functions always return OK. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The only reason to enable the .Fn idlok feature is to use scrolling to achieve the visual effect of motion of a partial window, such as for a screen editor. In other cases, the feature can be visually annoying. .P The .Fn leaveok option provides greater efficiency for applications that do not use the cursor. .SH "SEE ALSO" clear(), delscreen(), doupdate(), scrl(), . .SS "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .CR idlok() , .CR leaveok() , .CR scrollok() , .Fn setscrreq and .Fn wsetscrreq functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The .B DESCRIPTION of .Fn clearok is updated to indicate that clearing of a screen applies if the flag is TRUE in either \f2curscr\f1 or the specified window. .P The .B "RETURN VALUE" is changed to indicate that the .CR clearok() , .Fn leaveok and .Fn scrollok functions always return OK. .\" .\" toc@\f3clearok(3X)\f1:\0\0\f4clearok()\f1, \f4idleok()\f1, \f4leaveok()\f1, \f4scrollok()\f1, \f4setscrreg()\f1, \f4wsetscrreg()\f1\n@@@terminal output control functions .\" toc@\f4idleok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4leaveok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4scrollok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4setscrreg()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4wsetscrreg()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" index@\f4clearok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4idleok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4leaveok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4scrollok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4setscrreg()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4wsetscrreg()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f1terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f1output, terminal, control functions@@@\f3clearok(3X)\f1 .\" index@\f1control functions, terminal output@@@\f3clearok(3X)\f1 .\" .\" links@clearok.3x idleok.3x .\" links@clearok.3x leaveok.3x .\" links@clearok.3x scrollok.3x .\" links@clearok.3x setscrreg.3x .\" links@clearok.3x wsetscrreg.3x .\" .\" fileset_database@clearok.3x CURS-ENG-A-MAN .\" $Header: nl_tools_16.3x,v 72.2 94/11/30 15:24:00 ssa Exp $ .TA n .TH nl_tools_16 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME nl_tools_16: ADVANCE(), byte_status(), BYTE_STATUS(), CHARADV(), CHARAT(), c_colwidth(), C_COLWIDTH(), firstof2(), FIRSTof2(), secof2(), SECof2(), WCHAR(), WCHARADV() \- tools to process 16-bit characters .SH SYNOPSIS .C "#include " .PP .C "int firstof2(int c);" .PP .C "int secof2(int c);" .PP .C "int byte_status(int c, int laststatus);" .PP .C int c_colwidth(int c); .PP .C "int FIRSTof2(int c);" .PP .C "int SECof2(int c);" .PP .C "int BYTE_STATUS(int c, int laststatus);" .PP .C "int C_COLWIDTH(int c);" .PP .C "int CHARAT(const char *p);" .PP .C "int ADVANCE(const char *p);" .PP .C "int CHARADV(const char *p);" .PP .C "int WCHAR(wchar_t wc, char *p);" .PP .C "int WCHARADV(wchar_t wc, char *p);" .PP .C "void PCHAR(int c, char *p);" .PP .C "void PCHARADV(int c, char *p);" .SS Remarks All interfaces listed above whose names begin with a capital letter are implemented as macros; the others are functions. .PP These macros and functions are obsolete. See WARNINGS. .SH DESCRIPTION The following macros and functions perform their operations based upon the loaded NLS environment (see .IR setlocale (3C)). .TP 20 .CR FIRSTof2() Takes a byte and returns a nonzero value if it can be the first byte of a two-byte character according to the NLS environment loaded, and zero if it cannot. .TP .CR SECof2() Takes a byte and returns a nonzero value if it can be the second byte of a two-byte character according to the loaded NLS environment, and zero if it cannot. .TP .CR BYTE_STATUS() Returns one of the following values based on the value of the current byte in .I c and the status of the previous byte interpreted in .I laststatus as returned by the last call to .CR BYTE_STATUS() . These are the status values as defined in .CR : .RS .RS .TP 15 .CR ONEBYTE Single-byte character .PD 0 .TP .CR SECOF2 Second byte of two-byte character .TP .CR FIRSTOF2 First byte of two-byte character .RE .RE .PD .IP To validate a two-byte character, both the first and second bytes must be valid. If the value of .I laststatus is .CR FIRSTOF2 but .CR SECof2( c ) returns false, .CI BYTE_STATUS( c , \ laststatus ) returns .CR ONEBYTE . .TP .CR C_COLWIDTH() Takes a byte which is assumed to be either a one-byte character or the first byte of a two-byte character, and returns the number of columns the character would occupy on a terminal display. .IP For the macros .CR BYTE_STATUS() , .CR C_COLWIDTH() , .CR FIRSTof2() , and .CR SEC0of2() , results are undefined for values of .I c less than \(mi1 (EOF) or greater than 255. .TP .CR CHARAT() Takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case, .CR CHARAT() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p . .TP .CR ADVANCE() Advances its pointer argument by the byte width of the character it is pointing at (either one or two bytes). .TP .CR CHARADV() Combines the functions of .CR CHARAT() and .CR ADVANCE() in a single macro. It takes as an argument a pointer .IR p , which is assumed to be pointing at either a one-byte character or the first byte of a two-byte character. In either case .CR CHARADV() returns the .CR wchar_t value that corresponds to the character pointed to by .IR p , and advances .I p beyond the last byte of the character. .TP .CR WCHAR() Converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p . .CR WCHAR() returns the .CR wchar_t value .IR wc . .TP .CR WCHARADV() Combines the functions of .CR WCHAR() and .CR ADVANCE() in a single macro. It converts the .CR wchar_t value .I wc into the corresponding one or two byte character, and writes it at the location specified by .IR p , then advances .I p past the last byte. .CR WCHARADV() returns the .CR wchar_t value .IR wc . .TP .CR firstof2() .PD 0 .TP .CR secof2() .TP .CR byte_status() .TP .CR c_colwidth() .PD Subroutine versions of the corresponding macros. These functions can be called from languages other than C. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of single and/or multibyte characters. .SH WARNINGS The HP proprietary functions and macros described in this manual entry are .BR OBSOLETE . They are not portable to other vendor's systems, and will not be provided in future HP-UX releases. .PP For maximum portability, use the routines documented in the .IR multibyte (3C) manual entry for multibyte character processing. .PP Other macros listed in this manual entry cannot be used as the first argument to .CR WCHAR() or .CR WCHARADV() . For example, .IP .C "*t++ = *f++" .PP cannot be replaced by .IP .C "WCHARADV(CHARADV (f),t)" .PP Instead, use a method such as .IP .CR "int c; " ...\& " c = CHARADV (f)," .CR "WCHARADV (c,t)" .PP .CR WCHAR() and .CR WCHARADV() may produce a "null effect" warning from .IR lint (1) if not used as part of another expression or as part of a statement. This does not affect the functionality of either macro. .PP Note that .CR WCHAR() and .CR WCHARADV() are not "replace_char" macros. They do not prevent the second byte of a two-byte character from being left dangling if .CR WCHAR() or .CR WCHARADV() overwrite the first byte of the two-byte character with a single-byte character. .PP .CR CHARAT() , .CR ADVANCE() , and .CR CHARADV() do not examine the byte following the location pointed to by the argument to verify its validity as a .CR SECof2 byte. .SH AUTHOR .CR nl_tools_16() was developed by HP. .SH SEE ALSO setlocale(3C), multibyte(3C), wconv(3X), wctype(3X), hpnls(5). .\" .\" index@\f4ADVANCE()\f1 \- advance pointer to next 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARADV()\f1 \- get character and advance pointer to next character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4CHARAT()\f1 \- get value of 8- or 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHAR()\f1, \- put 8- or 16-bit character in memory@@@\f3nl_tools_16(3X)\f1 .\" index@\f4WCHARADV()\f1, \- put character in memory and advance pointer@@@\f3nl_tools_16(3X)\f1 .\" index@\f4byte_status()\f1, \f4BYTE_STATUS()\f1 \- test for valid 1- or 2-byte character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4firstof2()\f1, \f4FIRSTof2()\f1 \- test for valid first byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f4secof2()\f1, \f4SECof2()\f1 \- test for valid second byte in 16-bit character@@@\f3nl_tools_16(3X)\f1 .\" index@\f1characters, tools to process 16-bit@@@\f3nl_tools_16(3X)\f1 .\" index@\f1process 16-bit characters, tools to@@@\f3nl_tools_16(3X)\f1 .\" index@\f1sixteen-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f116-bit characters, tools to process@@@\f3nl_tools_16(3X)\f1 .\" index@\f1tools to process 16-bit characters@@@\f3nl_tools_16(3X)\f1 .\" .\" links@nl_tools_16.3x ADVANCE.3x .\" links@nl_tools_16.3x BYTE_STATUS.3x .\" links@nl_tools_16.3x CHARADV.3x .\" links@nl_tools_16.3x CHARAT.3x .\" links@nl_tools_16.3x FIRSTof2.3x .\" links@nl_tools_16.3x SECof2.3x .\" links@nl_tools_16.3x WCHAR.3x .\" links@nl_tools_16.3x WCHARADV.3x .\" links@nl_tools_16.3x byte_status.3x .\" links@nl_tools_16.3x c_colwidth.3x .\" links@nl_tools_16.3x firstof2.3x .\" links@nl_tools_16.3x secof2.3x .\" .\" toc@\f3nl_tools_16(3X)\f1:\0\0\f4ADVANCE()\f1, \f4byte_status()\f1, \f4BYTE_STATUS()\f1, \f4CHARADV()\f1,\n\f4CHARAT()\f1, \f4C_COLWIDTH()\f1, \f4c_colwidth()\f1, \f4firstof2()\f1, \f4FIRSTof2()\f1,\n\f4secof2()\f1, \f4SECof2()\f1, \f4WCHAR()\f1, \f4WCHARADV()\f1@@@tools to process 16-bit characters .\" toc@\f4ADVANCE()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4byte_status()\f1, \f4BYTE_STATUS()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4CHARAT()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4c_colwidth()\f1, \f4C_COLWIDTH()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4firstof2()\f1, \f4FIRSTof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4secof2()\f1, \f4SECof2()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHAR()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" toc@\f4WCHARADV()\f1:\0\0process 16-bit characters@@@see \f3nl_tools_16(3X)\f1 .\" $Header: secure_rpc.3c,v 1.1.111.2 95/05/11 16:06:15 indnetwk Exp $ .TA s .TH secure_rpc 3C .SH NAME secure_rpc(), authdes_create(), authdes_getucred(), get_myaddress(), getnetname(), host2netname(), key_decryptsession(), key_encryptsession(), key_gendes(), key_setsecret(), netname2host(), netname2user(), user2netname() \- library routines for secure remote procedure calls .SH DESCRIPTION .LP .C RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .LP .C RPC allows various authentication flavors. The .B authdes_getucred() and .B authdes_create() routines implement the .B DES authentication flavor. See .BR rpc_clnt_auth (3C) for routines relating to the .B AUTH_NONE and .B AUTH_UNIX authentication types. .IP Note: Both the client and server should have their keys in the .BR publickey (5) database. Also, the keyserver daemon .BR keyserv (1M) must be running on both the client and server hosts for the .B DES authentication system to work. .SS Routines .LP The following routines require that the header .BR be included. .PP The .B AUTH data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "AUTH *" .C "authdes_create(netname, window, syncaddr, deskeyp)" .C "char *netname;" .C "unsigned window;" .C "struct sockaddr_in *syncaddr;" .C "des_block *deskeyp;" .fi .IP .B authdes_create() is an interface to the .B RPC secure authentication system, known as .B DES authentication. .IP Used on the client side, .B authdes_create() returns an authentication handle that enables the use of the secure authentication system. The first parameter .I netname is the network name of the owner of the server process. This field usually represents a .I host derived from the utility routine .BR host2netname() , but could also represent a user name using .BR user2netname() . The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third parameter .I syncaddr is optional. If it is .B NULL, then the authentication system will assume that the local clock is always in sync with the server's clock, and will not attempt to synchronize with the server. If an address is supplied then the system will use it for consulting the remote time service whenever resynchronization is required. This parameter is usually the address of the .B RPC server itself. The final parameter .I deskeyp is also optional. If it is .B NULL, then the authentication system will generate a random .B DES key to be used for the encryption of credentials. If .I deskeyp is supplied then it is used instead. .PP .nf .C "int" .C "authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)" .C "struct authdes_cred *adc;" .C "short *uidp, *gidp, *gidlenp;" .C "int *gidlistp;" .fi .IP .BR authdes_getucred() , is a .B DES authentication routine used by the server for converting a .B DES credential, which is operating system independent, into a .B UNIX credential. .I uidp points to the user .B ID of the user associated with .IR adc ; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. .br .ne 5 .IP This routine differs from the utility routine .B netname2user() in that .B authdes_getucred() pulls its information from a cache, and does not have to do a .B NIS name service lookup every time it is called to get its information. Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "void" .C "get_myaddress(addr)" .C "struct sockaddr_in *addr;" .fi .IP Returns the address of the last interface configured UP. This may not necessarily be the machine's .B IP address configured with the hostname. The port number is always set to .BR htons(PMAPPORT) . .PP .nf .C "int" .C "getnetname(netname)" .C "char netname[MAXNETNAMELEN];" .fi .IP Return the unique, operating-system independent netname of the caller in the fixed-length array .IR netname . Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "int" .C "host2netname(netname, host, domain)" .C "char netname[MAXNETNAMELEN];" .C "char *host;" .C "char *domain;" .fi .IP Convert from a domain-specific hostname to an operating-system independent netname. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . This routine should be used if the owner of the server process is the machine that is, the user with effective user .B ID zero. Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2host() . .PP .nf .C "int" .C "key_decryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP An interface routine to the keyserver daemon, which is associated with .B RPC's secure authentication system ( .B DES authentication). User programs rarely need to call it, or its associated routines .BR key_encryptsession() , .B key_gendes() and .BR key_setsecret() . System commands such as .B login and the .B RPC library are the main clients of these four routines. .IP .B key_decryptsession() takes the netname of a server and a .B DES key, and decrypts the key by using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_encryptsession() . .PP .nf .C "int" .C "key_encryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It takes the netname of the server and a .B DES key, and encrypts it using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_decryptsession() . .PP .nf .C "int" .C "key_gendes(deskeyp)" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It is used to ask the keyserver for a secure conversation key. Choosing one at random is usually not good enough, because the common ways of choosing random numbers, such as using the current time, are very easy to guess. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "key_setsecret(keyp)" .C "char *keyp;" .fi .IP A keyserver interface routine. It is used to set the secret key for the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "netname2host(netname, host, hostlen)" .C "char *netname;" .C "char *host;" .C "int hostlen;" .fi .IP Convert an operating-system independent netname to a domain-specific hostname. .I hostlen specifies the size of the array pointed to by .I host. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR host2netname() . .PP .nf .C "int" .C "netname2user(netname, uidp, gidp, gidlenp, gidlistp)" .C "char *netname;" .C "int *uidp, *gidp, *gidlenp, *gidlistp;" .fi .IP Convert an operating-system independent netname to a domain-specific user .B ID. .I uidp points to the user .B ID of the user; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR user2netname() . .PP .nf .C "int" .C "user2netname(netname, uid, domain)" .C "char netname[MAXNETNAMELEN];" .C "int uid;" .C "char *domain;" .fi .IP Convert a domain-specific username to an operating-system independent netname. .I uid is the user .B ID of the owner of the server process. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2user() . .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR login (1), .BR chkey (1), .BR rpc (3C), .BR rpc_clnt_auth (3C), .BR publickey (4), .BR keyserv (1M), .BR newkey (1M) .\" toc@\f3secure_rpc(3C)\f1:\0\0\f4authdes_create()\fP, \f4authdes_getucred()\fP, \f4get_myaddress()\fP, \n\f4getnetaddress()\fP, \f4getnetname()\fP, \f4host2netname()\fP, \n\f4key_decryptsession()\fP, \f4key_encryptsession()\fP, \f4key_gendes()\fP, \n\f4key_setsecret()\fP, \f4netname2host()\fP, \f4netname2user()\fP, \n\f4user2netname()\fP@@@library routines for secure remote procedure calls .\" toc@\f4secure_rpc()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_create()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_getucred()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4get_myaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4host2netname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_decryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_encryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_gendes()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_setsecret()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2host()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2user()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4user2netname()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" index@library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4secure_rpc()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_create()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_getucred()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4get_myaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4host2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_decryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_encryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_gendes()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_setsecret()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2host()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2user()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4user2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" links@secure_rpc.3c authdes_create.3c .\" links@secure_rpc.3c authdes_getucred.3c .\" links@secure_rpc.3c get_myaddress.3c .\" links@secure_rpc.3c getnetaddress.3c .\" links@secure_rpc.3c getnetname.3c .\" links@secure_rpc.3c host2netname.3c .\" links@secure_rpc.3c key_decryptsession.3c .\" links@secure_rpc.3c key_encryptsession.3c .\" links@secure_rpc.3c key_gendes.3c .\" links@secure_rpc.3c key_setsecret.3c .\" links@secure_rpc.3c netname2host.3c .\" links@secure_rpc.3c netname2user.3c .\" links@secure_rpc.3c user2netname.3c .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: directory.3c,v 76.1 95/07/05 17:28:05 ssa Exp $ .TA d .TH directory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME opendir(\|), readdir(\|), readdir_r(\|), telldir(\|), seekdir(\|), rewinddir(\|), closedir(\|) \- directory operations .SH SYNOPSIS .C "#include " .PP .C "DIR *opendir(const char *dirname);" .PP .C "struct dirent *readdir(DIR *dirp);" .PP .C "int readdir_r(DIR *dirp, struct dirent *result);" .PP .C "long int telldir(DIR *dirp);" .PP .C "void seekdir(DIR *dirp, long int loc);" .PP .C "void rewinddir(DIR *dirp);" .PP .C "int closedir(DIR *dirp);" .SH DESCRIPTION This library package provides functions that allow programs to read directory entries without having to know the actual directory format associated with the file system. Because these functions allow programs to be used portably on file systems with different directory formats, this is the recommended way to read directory entries. .TP 15 .CR opendir() opens the directory .I dirname and associates a directory stream with it. .CR opendir() returns a pointer used to identify the directory stream in subsequent operations. .CR opendir() uses .IR malloc (3C) to allocate memory. .TP .CR readdir() returns a pointer to the next directory entry. It returns a .SM NULL pointer upon reaching the end of the directory or detecting an invalid .CR seekdir() operation. See .IR dirent (5) for a description of the fields available in a directory entry. .TP .CR readdir_r() expects to be passed the address of a .CR "struct dirent" and will store the result at the supplied location. .TP .CR telldir() returns the current location (encoded) associated with the directory stream to which .IR dirp refers. .TP .CR seekdir() sets the position of the next .CR readdir() operation on the directory stream to which .IR dirp refers. The .IR loc argument is a location within the directory stream obtained from .CR telldir() . The position of the directory stream is restored to where it was when .CR telldir() returned that .I loc value. Values returned by .CR telldir() are valid only while the .CR DIR pointer from which they are derived remains open. If the directory stream is closed and then reopened, the .CR telldir() value might be invalid. .TP .CR rewinddir() resets the position of the directory stream to which .IR dirp refers to the beginning of the directory. It also causes the directory stream to refer to the current state of the corresponding directory, as a call to .CR opendir() would have done. .TP .CR closedir() closes the named directory stream, then frees the structure associated with the .CR DIR pointer. .SH RETURN VALUE .TP 15 .CR opendir() , upon successful completion, returns a pointer to an object of type .CR DIR referring to an open directory stream. Otherwise, it returns a .SM NULL pointer and sets the global variable .CR errno to indicate the error. .TP .CR readdir() , upon successful completion, returns a pointer to an object of type .CR struct dirent describing a directory entry. Upon reaching the end of the directory, .CR readdir() returns a .SM NULL pointer and does not change the value of .CR errno . Otherwise, it returns a .SM NULL pointer and sets .CR errno to indicate the error. .TP .CR readdir_r() , upon successful completion, returns a 0. Upon reaching the end of directory or encountering an error, it returns a -1 and sets .CR errno to indicate the error. .TP .CR telldir() , upon successful completion, returns a long value indicating the current position in the directory. Otherwise it returns .CR \-1 and sets .CR errno to indicate the error. .TP .CR seekdir() does not return any value, but if an error is encountered, .CR errno is set to indicate the error. .TP .CR closedir() , upon successful completion, returns a value of .CR 0 . Otherwise, it returns a value of .CR \-1 and sets .CR errno to indicate the error. .SH ERRORS .CR opendir() fails if any of the following conditions are encountered: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of .IR dirname , or read permission is denied for .IR dirname . .TP .SM [EFAULT] .I dirname points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the path name. .TP .SM [EMFILE] Too many open file descriptors are currently open for the calling process. .TP .SM [ENAMETOOLONG] A component of .IR dirname exceeds .CR PATH_MAX bytes, or the entire length of .IR dirname exceeds .CR PATH_MAX \(mi 1 bytes while .CR _POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] Too many open file descriptors are currently open on the system. .TP .SM [ENOENT] A component of .I dirname does not exist. .TP .SM [ENOMEM] .CR malloc() failed to provide sufficient memory to process the directory. .TP .SM [ENOTDIR] A component of .I dirname is not a directory. .TP .SM [ENOENT] The .IR dirname argument points to an empty string. .RE .PP .CR readdir() " or " readdir_r() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] The directory stream to which .IR dirp refers is not located at a valid directory entry. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR telldir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR seekdir() might fail if the following condition is encountered: .RS .TP 20 .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR closedir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP 20 .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR rewinddir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .SH EXAMPLES The following code searches the current directory for an entry .IR name : .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 DIR *dirp; struct dirent *dp; dirp = opendir("."); while ((dp = readdir(dirp)) != NULL) { if (strcmp(dp->d_name, name) == 0) { (void) closedir(dirp); return FOUND; } } (void) closedir(dirp); return NOT_FOUND; .ft .ps .fi .RE .SH WARNINGS .CR readdir() and .CR getdirentries() (see .IR getdirentries (2) are the only ways to access remote .SM NFS directories. Attempting to read a remote directory via .SM NFS by using .CR read() returns .CR \-1 and sets .CR errno to .SM EISDIR (see .IR read (2)). .PP .CR readdir() is unsafe in multi-thread applications. .CR readdir_r() is MT-Safe and should be used instead. Users of .CR readdir_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH APPLICATION USAGE The header file required for these functions and the type of the return value from .CR readdir() has been changed for compatibility with System V Release 3 and the .IR "X/Open Portability Guide" . See .IR ndir (5) for a description of the header file .RC < ndir.h >, which is provided to allow existing .SM HP-UX applications to compile unmodified. .PP New applications should use the .RC < dirent.h > header file for portability to System V and X/Open systems. .SH AUTHOR .CR directory was developed by AT&T, HP, and the University of California, Berkeley. .SH SEE ALSO close(2), getdirentries(2), lseek(2), open(2), read(2), dir(4), dirent(5), ndir(5). .SH STANDARDS CONFORMANCE .CR closedir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR opendir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR readdir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR rewinddir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR seekdir() ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR telldir() ": AES, XPG2, XPG3, XPG4" .\" .\" index@\f4opendir()\f1 \- open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f4readdir()\f1 \- get pointer to current entry in open directory@@@\f3directory(3C)\f1 .\" index@\f4telldir()\f1 \- get current location of named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4seekdir()\f1 \- set position of next \f4readdir()\f1 operation on named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4rewinddir()\f1 \- reset position of named \f2directory stream\f1 to beginning of directory@@@\f3directory(3C)\f1 .\" index@\f4closedir()\f1 \- close a currently open directory@@@\f3directory(3C)\f1 .\" index@open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f2directory stream\f1, directory and associated, open for access@@@\f3directory(3C)\f1 .\" index@open, access, or close a directory@@@\f3directory(3C)\f1 .\" index@close, access, or open a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@directory: access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" .\" toc@\f3directory(3C)\f1:\0\0\f4directory()\f1, \f4opendir()\f1, \f4readdir()\f1, \f4telldir()\f1, \f4seekdir()\f1, \f4rewinddir()\f1,\n\f4closedir()\f1@@@directory operations .\" toc@\f4opendir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4readdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4telldir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4seekdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4rewinddir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4closedir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" .\" links@directory.3c opendir.3c .\" links@directory.3c readdir.3c .\" links@directory.3c readdir_r.3c .\" links@directory.3c telldir.3c .\" links@directory.3c seekdir.3c .\" links@directory.3c rewinddir.3c .\" links@directory.3c closedir.3c .\" $Header: del_curterm.3x,v 76.2 95/07/31 11:24:20 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH del_curterm 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME del_curterm, restartterm, set_curterm, setupterm \(em interfaces to the \f3terminfo\f1 database .SH SYNOPSIS .C "#include " .P .C "int del_curterm(TERMINAL *\f2oterm\f4);" .P .C "int restartterm(char *\f2term\f4, int \f2fildes\f4, int *\f2errret\f4);" .P .C "TERMINAL *set_curterm(TERMINAL *\f2nterm\f4);" .P .C "int setupterm(char *\f2term\f4, int \f2fildes\f4, int *\f2errret\f4);" .P .C "extern TERMINAL *cur_term;" .SH DESCRIPTION These functions retrieve information from the \f3terminfo\f1 database. .P To gain access to the \f3terminfo\f1 database, .Fn setupterm must be called first. It is automatically called by .Fn initscr and .Fn newterm . The .Fn setupterm function initializes the other functions to use the \f3terminfo\f1 record for a specified terminal (which depends on whether .Fn use_env was called). It sets the .I cur_term external variable to a \f3TERMINAL\f1 structure that contains the record from the \f3terminfo\f1 database for the specified terminal. .P The terminal type is the character string \f2term;\f1 if \f2term\f1 is a null pointer, the environment variable TERM is used. If TERM is not set or if its value is an empty string, then \f4"unknown"\f1 is used as the terminal type. The application must set \f2fildes\f1 to a file descriptor, open for output, to the terminal device, before calling .Fn setupterm . If \f2errret\f1 is not null, the integer it points to is set to one of the following values to report the function outcome: .PP .RS .TP 10 .CR \(mi1 The \f3terminfo\f1 database was not found (function fails). .TP .CR 0 The entry for the terminal was not found in \f3terminfo\f1 (function fails). .TP .CR 1 Success. .PP .RE If .Fn setupterm detects an error and \f2errret\f1 is a null pointer, .Fn setupterm writes a diagnostic message and exits. .P A simple call to .Fn setupterm that uses all the defaults and sends the output to \f2stdout\f1 is: .\" .Cs I .IP setupterm((char *)0, fileno(stdout), (int *)0); .\" .Ce .PP The .Fn set_curterm function sets the variable \f2cur_term\f1 to \f2nterm\f1, and makes all of the \f3terminfo\f1 boolean, numeric, and string variables use the values from \f2nterm.\f1 .P The .Fn del_curterm function frees the space pointed to by \f2oterm\f1 and makes it available for further use. If \f2oterm\f1 is the same as \f2cur_term\f1, references to any of the \f3terminfo\f1 boolean, numeric, and string variables thereafter may refer to invalid memory locations until .Fn setupterm is called again. .P The .Fn restartterm function assumes a previous call to .Fn setupterm (perhaps from .Fn initscr or .Fn newterm ). It lets the application specify a different terminal type in \f2term\f1 and updates the information returned by .Fn baudrate based on \f2fildes\f1, but does not destroy other information created by .Fn initscr , .Fn newterm or .Fn setupterm . .SH "RETURN VALUE" Upon successful completion, .Fn set_curterm returns the previous value of \f2cur_term\f1. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" An application would call .Fn setupterm if it required access to the \f3terminfo\f1 database but did not otherwise need to use Curses. .SH "SEE ALSO" \f3Selecting a Terminal\f1 in terminfo(4), baudrate(), erasechar(), has_ic(), longname(), putc(), termattrs(), termname(), tgetent(), tigetflag(), use_env(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3del_curterm(3x)\f1:\0\0\f4del_curterm()\f1, \f4restartterm()\f1, \f4set_curterm()\f1,\n\f4setupterm()\f1@@@interfaces to terminfo database .\" .\" toc@\f4del_curterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" toc@\f4restartterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" toc@\f4set_curterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" toc@\f4setupterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" .\" index@\f4del_curterm()\f1, \f4restartterm()\f1, \f4set_curterm()\f1, \f4setupterm()\f1 \- interfaces to \nterminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f4restartterm()\f1 \- interface to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f4set_curterm()\f1 \- interface to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f4setupterm()\f1 \- interface to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f1interfaces to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f1terminfo database, interfaces@@@\f3del_curterm(3x)\f1 .\" .\" links@del_curterm.3x restartterm.3x .\" links@del_curterm.3x set_curterm.3x .\" links@del_curterm.3x setupterm.3x .\" .\" fileset_database@del_curtem.3x CURS-ENG-A-MAN .\" .\" $Header: set_term.3x,v 76.2 95/08/01 14:43:35 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH set_term 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME set_term \(em switch between screens .SH SYNOPSIS .C "#include " .P .C "SCREEN *set_term(SCREEN *\f2new\fP);" .SH DESCRIPTION The .Fn set_term function switches between different screens. The \f2new\f1 argument specifies the new current screen. .SH "RETURN VALUE" Upon successful completion, .Fn set_term returns a pointer to the previous screen. Otherwise, it returns a null pointer. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" This is the only function that manipulates \f3SCREEN\f1 pointers; all other functions affect only the current screen. .SH "SEE ALSO" \f3Screens, Windows and Terminals\f1 in curs_intro, initscr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" index@\f4set_term()\f1 \- switch between screens@@@\f3set_term(3X)\f1 .\" index@\f1switch between screens@@@\f3set_term(3X)\f1 .\" index@\f1screens, switch between@@@\f3set_term(3X)\f1 .\" .\" toc@\f3set_term(3X)\f1:\0\0\f4set_term()\f1@@@switch between screens .\" .\" fileset_database@set_term.3x CURS-ENG-A-MAN .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "set_values" "Xt \- Intrinsics Methods" .SH "Name" .Na set_values \- Object class method for handling resource changes. .Nz .XS "set_values method" .XS "methods, set_values" .SH "Synopsis" .Sy typedef Boolean (*XtSetValuesFunc)(Widget, Widget, Widget, ArgList, .br Cardinal *); .As Widget \f(CIcurrent\fP; Widget \f(CIrequest\fP; Widget \f(CIset\fP; ArgList \f(CIargs\fP; Cardinal *\f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIcurrent\fP 1i Specifies a copy of the widget made by \f(CWXtSetValues()\fP before any resources are changed or any \f(CWset_values()\fP methods are called. .IP \f(CIrequest\fP 1i Specifies a copy of the widget made by \f(CWXtSetValues()\fP after the resources are changed as requested, but before any \f(CWset_values()\fR methods are called. .IP \f(CIset\fP 1i Specifies the actual widget with resources set and as modified by any superclass methods that have been called by \f(CWXtSetValues()\fP. .IP \f(CIargs\fP 1i Specifies the argument list passed to \f(CWXtSetValues()\fR. .IP \f(CInum_args\fR 1i Specifies the number of arguments in the \f(CIargs\fP. .SS "Returns" \f(CWTrue\fP if the resource changes require the widget to be redrawn; \f(CWFalse\fP otherwise. .\" .SH "Description" The \f(CWset_values()\fP method is registered on the \f(CWset_values\fP field of the Object, RectObj, or Core class part structure. It is called by \f(CWXtSetValues()\fP to do any processing necessary when the values of widget resources are changed. This method is chained in .hw subclass superclass-to-subclass order. .LP The \f(CIset\fP argument is the widget that has had its resources set, and has been passed to the superclass \f(CWset_values()\fP methods. Any changes to resource or non-resource fields should be made to this widget. .LP The \f(CIcurrent\fP argument is a copy of the widget that was made by \f(CWXtSetValues()\fP before any of the resource values were changed as requested in the argument list. The \f(CWset_values()\fP method can compare the resource fields of \f(CIset\fP and \f(CIcurrent\fP to determine which resources have been changed. .LP The \f(CIrequest\fP argument is a copy of the widget made after the resource values were set, but before \f(CWXtSetValues()\fP called any \f(CWset_values()\fP methods. A \f(CWset_values()\fP method can compare fields in \f(CIrequest\fP, \f(CIset\fP, and \f(CIcurrent\fP to determine whether a field was set from the argument list (i.e., at the request of the programmer) or whether it was modified by a superclass \f(CWset_values()\fP method. A \f(CWset_values()\fP method may override values set by a superclass, but shouldn't change values that are explicitly .ne 5 requested in a call to \f(CWXtSetValues()\fP. See the "Background" section below for more information. .LP The \f(CIargs\fP and \f(CInum_args\fP arguments are the argument list that was passed to \f(CWXtSetValues()\fP (or the variable-length argument list passed to \f(CWXtVaSetValues()\fP transformed into an \f(CWArgList\fP). They can be used to set subpart resources with \f(CWXtSetSubvalues()\fP, to set values on privately created children widgets, or to set any other resources that do not appear on the resource list of the widget class. The \f(CIargs\fP and \f(CInum_args\fP arguments were added to this method in Release 4. Prior to Release 4, subpart and other resources had to be set in the \f(CWset_values_hook()\fP method, which is now obsolete. .LP The \f(CWset_values()\fP method returns \f(CWTrue\fP if the widget needs to be redrawn in response to the resources changes, and \f(CWFalse\fP otherwise. It should not do any redisplay itself; if any of the \f(CWset_values()\fP methods returns \f(CWTrue\fP, \f(CWXtSetValues()\fP will generate an \f(CWExpose\fP event for the window by calling \f(CWXClearArea()\fP, and the widget's \f(CWexpose()\fP method will be called. .LP A programmer may call \f(CWXtSetValues()\fP to set a widget's geometry fields directly. A \f(CWset_values()\fP method may also set these fields in response to other resource changes (if a label widget's label changes, for example, it may change its width). Note that this is one of the few times that a widget is allowed to directly set its own geometry fields. The other times are in the \f(CWinitialize()\fP and (obsolete) \f(CWinitialize_hook()\fP methods, and the (also obsolete) \f(CWset_values_hook()\fP method. A \f(CWset_value()\fP method may directly set its geometry fields, but should not do any processing based on those new values; the widget's parent must approve them first. If any of a widget's geometry fields have changed after all the \f(CWset_values()\fP methods have been called, \f(CWXtSetValues()\fP will call \f(CWXtMakeGeometryRequest()\fP to actually request the geometry change from the widget's parent. If the request is denied, \f(CWXtSetValues()\fP will reset the geometry fields to their original values. If the request is successful and the widget's size has changed, it will invoke the widget's \f(CWresize()\fP method. Most widgets will receive an \f(CWExpose\fP event after they are resized, and so a change to geometry fields alone is not reason enough for \f(CWset_values()\fP to return \f(CWTrue\fP. .LP The \f(CWset_values()\fP method must not assume that the widget is realized. .LP The \f(CWset_values()\fP method is chained in superclass-to-subclass order and cannot be inherited. If a widget has no resources, or needs to do no recalculation when those resources change, it does not need a \f(CWset_values()\fP method and can specify \f(CWNULL\fP for the \f(CWset_values\fP field of the class part structure. .LP See \f(CWXtSetValues\fP(1) for full details on the resource-setting process. See Constraint \f(CWset_values\fP(4) for information about handling changes to Constraint resources. See the "Background" section below for information about overriding values set by a superclass. .\" .SH "Usage" A typical \f(CWset_values()\fP method will compare the fields of \f(CIset\fP and \f(CIcurrent\fP for most resources defined by the class. If a resource value has changed, it will take whatever actions are appropriate. Some common tasks of the \f(CWset_values()\fP method are: .IP \(bu 3 Copies resources that are passed by reference. If a resource that was copied in the \f(CWinitialize()\fP method has changed, the old value must be freed, and the new value copied. String resources are typically copied by a widget so that the programmer may modify or free them after setting them in the widget. If this freeing and copying are done in separate procedures, the procedure to free the value can usually be shared with the \f(CWdestroy()\fP method and the procedure to copy the value can usually be shared with the \f(CWinitialize()\fP method. .IP \(bu 3 Recomputes derived fields when the resources they are derived from have changed. If the \f(CWXtNforeground\fP or \f(CWXtNfont\fP resource of a widget has changed, for example, it will probably have to free its current shared GC and allocate a new one. Note that resources may be derived from other resources. If a widget's width can be specified through either the \f(CWXtNwidth\fP or the \f(CWXtNcolumns\fP resource, then a change to either of these resources should cause a change to the other (and if both are changed, one should take clearly defined and documented precedence). If the code to calculate the values of derived fields is placed in separate procedures (code to allocate GCs, for example) those procedures can usually be shared with the \f(CWinitialize()\fP method. .IP \(bu 3 Checks modified resources for consistency and reasonableness. If inconsistent or unreasonable resources are found, their values should be set to something valid, and a warning message should be issued. .IP \(bu 3 Restores the value of resource that are not allowed to be changed. Some widgets do not allow changes to some of their resources. If these values are changed in the \f(CWset_values()\fP method, they should be reset (i.e., the \f(CIset\fP field restored from the \f(CIcurrent\fP field) and a warning message should be issued. .IP \(bu 3 Overrides derived fields calculated by superclasses, if necessary. If the \f(CWXtNcolumns\fP resource of a widget has changed, for example, a superclass may have one way of deriving \f(CWXtNwidth\fP from it, and a subclass may have a different way (the subclass may have different margins, for example). See the "Background" section below, for further discussion about overriding values set by a superclass. .IP \(bu 3 Uses \f(CIargs\fP and \f(CInum_args\fP to set the value of resources that do not appear in the class resource list. These may be subpart resources (set with \f(CWXtSetSubvalues()\fP) or resources of children objects or widgets (set with \f(CWXtSetValues()\fP) which the widget wants to export as its own. (See \f(CWget_values_hook\fP(4) for a discussion and examples of widgets that export resources of child widgets or subparts.) .IP \(bu 3 Checks for changes to the sensitivity state of the widget. \f(CWXtSetSensitive()\fP uses \f(CWXtSetValues()\fP to set the \f(CWsensitive\fP and \f(CWancestor_sensitive\fP fields of a widget. A widget class that displays itself differently when insensitive should check for sensitivity changes in its \f(CWset_values()\fP method. See \f(CWXtSetSensitive\fP(1) for more information on widget sensitivity. .IP \(bu 3 Keeps track of whether the widget needs to be redrawn. A common technique in \f(CWset_values()\fP methods is to initialize a \f(CWneeds_redraw\fP variable to \f(CWFalse\fP, and then set it to \f(CWTrue\fP if any resources are changed that would require the widget to be redrawn. This value then becomes the return value of the method. A widget will commonly need to be redrawn if colors, fonts, or other GC components have changed; if its sensitivity state has .ne 4 changed; or if a resource that specifies data to be displayed (the \f(CWXtNlabel\fP resource of the Label widget, for example) has changed. .\" .SH "Example" The following procedure is the \f(CWset_values()\fP method, slightly edited, from the Xaw List widget. Note that it frees and reallocates its GCs if the foreground, background, or font have changed. If any of a large number of resources have changed that would affect the layout or size of the list, it calls an internal procedure that will calculate internal layout information and set new values for the widget's geometry fields. Finally, it checks whether it has been made insensitive and if so, turns off its highlighting. .LP Note that this procedure (and most existing \f(CWset_values()\fP methods) names the \f(CIset\fP argument \f(CWnew\fP. "new" is a reserved word in C++, and your code will be more portable if you avoid using it in C. .Ps /* ARGSUSED */ static Boolean SetValues(current, request, new, args, num_args) Widget current, request, new; ArgList args; Cardinal *num_args; { ListWidget cl = (ListWidget) current; ListWidget rl = (ListWidget) request; ListWidget nl = (ListWidget) new; Boolean redraw = FALSE; if ((cl->list.foreground != rl->list.foreground) (cl->core.background_pixel != rl->core.background_pixel) (cl->list.font != rl->list.font) ) { XGCValues values; XGetGCValues(XtDisplay(current), cl->list.graygc, GCTile, &values); XmuReleaseStippledPixmap(XtScreen(current), values.tile); XtReleaseGC(current, cl->list.graygc); XtReleaseGC(current, cl->list.revgc); XtReleaseGC(current, cl->list.normgc); GetGCs(new); redraw = TRUE; } /* Reset row height. */ if ((cl->list.row_space != rl->list.row_space) (cl->list.font != rl->list.font)) nl->list.row_height = nl->list.font->max_bounds.ascent + nl->list.font->max_bounds.descent + nl->list.row_space; if ((cl->core.width != rl->core.width) (cl->core.height != rl->core.height) (cl->list.internal_width != rl->list.internal_width) (cl->list.internal_height != rl->list.internal_height) (cl->list.column_space != rl->list.column_space) (cl->list.row_space != rl->list.row_space) (cl->list.default_cols != rl->list.default_cols) ( (cl->list.force_cols != rl->list.force_cols) && (rl->list.force_cols != rl->list.ncols) ) (cl->list.vertical_cols != rl->list.vertical_cols) (cl->list.longest != rl->list.longest) (cl->list.nitems != rl->list.nitems) (cl->list.font != rl->list.font) (cl->list.list != rl->list.list) ) { ResetList(new, TRUE, TRUE); redraw = TRUE; } if (cl->list.list != rl->list.list) nl->list.is_highlighted = nl->list.highlight = NO_HIGHLIGHT; if ((cl->core.sensitive != rl->core.sensitive) (cl->core.ancestor_sensitive != rl->core.ancestor_sensitive)) { nl->list.highlight = NO_HIGHLIGHT; redraw = TRUE; } if (!XtIsRealized(current)) return(FALSE); return(redraw); } .Pe .\" .SH "Background" Like the \f(CWinitialize()\fP method, \f(CWset_values()\fP mostly deals only with the fields defined in the subclass, but it has to resolve conflicts with its superclass, especially conflicts over width and height. .LP Sometimes a subclass may want to overwrite values filled in by its superclass. In particular, size calculations of a superclass are often incorrect for a subclass and, in this case, the subclass must modify or recalculate fields declared and computed by its superclass. .LP As an example, a subclass can visually surround its superclass display. In this case, the width and height calculated by the superclass \f(CWset_values()\fP method are too small and need to be incremented by the size of the surround. The subclass needs to know if its superclass's size was calculated by the superclass or was specified explicitly. All widgets must place themselves into whatever size is explicitly given, but they should compute a reasonable size if no size is requested. How does a subclass know the difference between a specified size and a size computed by a superclass? .LP The \f(CIrequest\fP and \f(CIset\fP parameters provide the necessary information. The \f(CIrequest\fP widget is a copy of the widget, updated as originally requested. The \f(CIset\fP widget starts with the values in the request, but it has additionally been updated by all superclass \f(CWset_values()\fP methods called so far. A subclass \f(CWset_values()\fP method can compare these two to resolve any potential conflicts. The \f(CWset_values()\fP method need not refer to the \f(CIrequest\fP widget unless it must resolve conflicts between the \f(CIcurrent\fP and .ne 2 \f(CIset\fP widgets. Any changes the widget needs to make, including geometry changes, should be made in the \f(CIset\fP widget. .LP In the above example, the subclass with the visual surround can see if the \f(CWwidth\fP and \f(CWheight\fP in the \f(CIrequest\fP widget differ from the \f(CWwidth\fP and \f(CWheight\fP in the \f(CIset\fP widget. If so, it means that a superclass has modified these fields (which means that the programmer did not request them specifically) and the subclass can add its surround size to the \f(CIwidth\fP and \f(CIheight\fP fields in the \f(CIset\fP widget. If the fields are the same, the subclass must make do with the specified size. .LP There is a twist, however, on this problem of not overriding resources explicitly requested by the user. If the programmer sets a new label on a Label widget, for example, the widget is allowed to change its size as needed to accommodate the label. If the programmer sets a new label and a new width at the same time, however, the new width should take precedence, regardless of the size of the label. The difficulty arises in the case that the programmer requests a particular width which happens to be the current width. He is expecting to get exactly that width, but the \f(CWset_values()\fP method may not detect that that resource has changed, and will resize the widget as required for the new label. The only general way out of this situation is to check each element of \f(CIargs\fP to see if the any of the resources that are being set are named \f(CWXtNwidth\fP. .\" .SH "See Also" .na \s-1\fIXtSetValues\fR\s+1\*(s1, .br \s-1\fICore\fR\s+1\*(s3, .br \s-1\fIConstraint set_values\fR\s+1\*(s4, \s-1\fIset_values_almost\fR\s+1\*(s4, \s-1\fIset_values_hook\fR\s+1\*(s4. .ad .XE "set_values method" .XE "methods, set_values" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "set_values_almost" "Xt \- Intrinsics Methods" .SH "Name" .Na set_values_almost \- RectObj class method to negotiate compromise geometries. .Nz .XS "methods, set_values_almost" .XS "set_values_almost method" .XN "geometry management, set_values_almost" .SH "Synopsis" .Sy typedef void (*XtAlmostProc)(Widget, Widget, XtWidgetGeometry *, .br XtWidgetGeometry *); .As Widget \f(CIcurrent\fP; Widget \f(CIset\fP; XtWidgetGeometry *\f(CIrequest_in_out\fP; XtWidgetGeometry *\f(CIreply\fP; .Ae .SS "Inputs" .IP \f(CIcurrent\fP 1i Specifies a copy of the object made by \f(CWXtSetValues()\fP before any resources were set or \f(CWset_values()\fP methods were called. .IP \f(CIset\fP 1i Specifies the object. It has had its resources set and fields modified by \f(CWset_values()\fP, \f(CWset_value_hook()\fP, and Constraint \f(CWset_values()\fP methods. .IP \f(CIrequest_in_out\fP 1i Specifies the geometry request that was sent to the geometry manager. .IP \f(CIreply\fP 1i Specifies the compromise geometry that was returned by the geometry manager. .SS "Outputs" .IP \f(CWrequest_in_out\fP 1i Returns the desired geometry; can be empty, the compromise geometry, or some new geometry to try. .\" .SH "Description" The \f(CWset_values_almost()\fP method is registered on the \f(CWset_values_almost\fP field of the RectObj or Core class part structure. It is invoked by \f(CWXtSetValues()\fP when a widget's geometry fields have changed, but the widget's parent's \f(CWgeometry_manager()\fP will not allow the requested geometry and returns \f(CWXtGeometryNo\fP or \f(CWXtGeometryAlmost\fP. .LP When a widget's geometry fields have been changed from the argument list, or by one of the \f(CWset_values()\fP methods, Constraint \f(CWset_values()\fP, or \f(CWset_values_hook()\fP methods that were called to handle the resource changes, \f(CWXtSetValues()\fP restores the original values, and calls \f(CWXtMakeGeometryRequest()\fP to actually request the new values from the widget's parent. If the return value of the request is \f(CWXtGeometryNo\fP or \f(CWXtGeometryAlmost\fP, \f(CWXtSetValues()\fP calls the widget's \f(CWset_values_almost()\fP method to determine whether the geometry should be left as is, the proposed compromise geometry accepted, or some other geometry tried. .LP The \f(CIcurrent\fP and \f(CIset\fP arguments are the same as the arguments by the same name that are passed to the \f(CWset_values()\fP method, except that the geometry fields of \f(CIset\fP (\f(CWx\fP, \f(CWy\fP, \f(CWwidth\fP, \f(CWheight\fP, and \f(CWborder_width\fP) contain the original values of the widget geometry, not the requested values. .LP The \f(CIrequest_in_out\fP argument is the geometry request made by \f(CWXtSetValues()\fP; it contains the new values of the geometry fields that changed, and \f(CIrequest_in_out\f(CW->request_mode\fR contains flags that indicate which of those fields are set. If the geometry request returned \f(CWXtGeometryAlmost\fP, then \f(CIreply\fP contains the proposed compromise geometry. If the request returned \f(CWXtGeometryNo\fP, then \f(CIreply\f(CW->request_mode\fR will be zero. .LP The \f(CWset_values_almost()\fP method should do one of the following: .IP \(bu 3n Set \f(CIrequest_in_out\f(CW->request_mode\fR to zero to terminate geometry negotiation and retain the original geometry. .IP \(bu 3n Copy the contents of \f(CIreply\fP into \f(CIrequest_in_out\fP to accept the compromise geometry. The parent is guaranteed to accept the compromise. .IP \(bu 3n Set some other geometry proposal into \f(CWrequest_in_out\fP. If the parent does not accept this geometry, the \f(CIset_values_almost()\fP method will be called again. .LP Note that the \f(CWset_values_almost()\fP method is not chained as are the \f(CWset_values()\fP, \f(CWset_values_hook()\fP, and Constraint \f(CWset_values()\fP methods. A widget class can inherit the \f(CWset_values_almost()\fP method of its superclass by specifying \f(CWXtInheritSetValuesAlmost\fP on the \f(CWset_values_almost\fP field of the RectObj or Core class part structure. It is not specified what will happen if the \f(CWset_values_almost\fP field is \f(CWNULL\fP (though some of the Xaw widgets have this method \f(CWNULL\fP). .LP The Intrinsics specification says in one place that \f(CWset_value_almost()\fP will be called on a result of \f(CWXtGeometryNo\fP, and says in another that it will not. Until the specification is clarified, \f(CWset_values_almost()\fP methods should be prepared to handle this case, but widget must not rely on these methods to detect it. .LP See \f(CWset_values\fP(4) for more information on the \f(CWcurrent\fP and \f(CWset\fP arguments. See \f(CWXtSetValues\fP(1) for a full description of the resource setting algorithm. See \f(CWXtMakeGeometryRequest\fP(1) and \f(CWgeometry_manager\fP(4) for details on geometry management. .\" .SH "Usage" Most classes will inherit this method from their superclass. The RectObj \f(CWset_values_almost()\fP method always accepts the compromise geometry; it is shown in the example below. .\" .SH "Example" The following procedure is the RectObj \f(CWset_values_almost()\fP method. It simply copies the contents of \f(CIreply\fP into \f(CIrequest_in_out\fP in order to accept the compromise geometry. .Ps /*ARGSUSED*/ static void RectSetValuesAlmost(old, new, request, reply) Widget old; Widget new; XtWidgetGeometry *request; XtWidgetGeometry *reply; .Nd 5 { *request = *reply; } .Pe .\" .SH "Structures" The \f(CWXtWidgetGeometry\fR structure is similar, but not identical, to the corresponding Xlib structure: .XX "XtGeometryMask" .Ps .ta 4.5n 2i typedef unsigned long XtGeometryMask; .sp .5 typedef struct { XtGeometryMask request_mode; Position x, y; Dimension width, height; Dimension border_width; Widget sibling; int stack_mode; } XtWidgetGeometry; .Pe The \f(CWrequest_mode\fR definitions are from <\fIX11/X.h\fP>: .Ps .ta .75i 2i #define CWX (1<<0) #define CWY (1<<1) #define CWWidth (1<<2) #define CWHeight (1<<3) #define CWBorderWidth (1<<4) #define CWSibling (1<<5) #define CWStackMode (1<<6) .Pe .LP The \f(CWstack_mode\fR definitions are from <\fIX11/X.h\fP>: .Ps .ta .75i 2i #define Above 0 #define Below 1 #define TopIf 2 #define BottomIf 3 #define Opposite 4 .Pe The Intrinsics also support the following value: .Ps .ta .75i 2i #define XtSMDontChange 5 .Pe For precise definitions of \f(CWAbove\fR, \f(CWBelow\fR, \f(CWTopIf\fR, \f(CWBottomIf\fR, and \f(CWOpposite\fR, see the reference page for \f(CWConfigureWindow()\fP in \*(V2. \f(CWXtSMDontChange\fR indicates that the widget wants its current stacking order preserved. .SH "See Also" .na \s-1\fIXtMakeGeometryRequest\fR\s+1\*(s1, \s-1\fIXtSetValues\fR\s+1\*(s1, .br \s-1\fICore\fR\s+1\*(s3, .br \s-1\fIgeometry_manager\fR\s+1\*(s4, \s-1\fIset_values\fR\s+1\*(s4. .ad .XE "methods, set_values_almost" .XE "set_values_almost method" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .de LP .P .. .ds ]V 1992, 1993, 1994, 1995, 1996 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y6 Appendix C,\0\fINaming Conventions\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .\" -*- nroff -*- (tells emacs to enter nroff-mode) .RH "set_values_hook" "Xt \- Intrinsics Methods" .SH "Name" .Na set_values_hook \- obsolete Object method for handling changes to subpart resources. .Nz .XS "set_values_hook method" .XS "methods, set_values_hook" .SH "Synopsis" .Sy typedef Boolean (*XtArgsFunc)(Widget, ArgList, Cardinal *); .As Widget \f(CIw\fP; ArgList \f(CIargs\fP; Cardinal *\f(CInum_args\fP; .Ae .SS "Inputs" .IP \f(CIw\fP 1i Specifies the widget whose nonwidget resource values are to be changed. .IP \f(CIargs\fP 1i Specifies the argument list that was passed to \f(CWXtSetValues()\fR. .IP \f(CInum_args\fP 1i Specifies the number of arguments in the argument list. .SS "Returns" \f(CWTrue\fP if the widget should be redrawn; \f(CWFalse\fP otherwise. .\" .SH "Availability" Obsolete in Release 4 and later. .\" .SH "Description" The \f(CWset_values_hook()\fP method is registered on the \f(CWset_values_hook\fP field of the Object, RectObj, or Core class part structure. It is called by \f(CWXtSetValues()\fP after the class's \f(CWset_values()\fP method has been called. .LP As of Release 4, the \f(CWset_values_hook()\fP method is obsolete, because the \f(CIargs\fP and \f(CInum_args\fP arguments are now passed to the \f(CWset_values()\fP method. Its purpose had been to allow the value of subpart resources to be set from the argument list, by calling \f(CWXtSetSubvalues()\fP for example. .LP The arguments to the \f(CWset_values_hook()\fP method are the widget and the argument list that were passed to \f(CWXtSetValues()\fP. The widget will have been modified by any superclass methods that have already been called. It should return \f(CWTrue\fP if the change to subpart resources will require the widget to be redraw, and \f(CWFalse\fP otherwise. .LP The \f(CWset_values_hook()\fP method is chained in superclass-to-subclass order and is called for compatibility with older widgets. It cannot be inherited, and any new widget classes should set their \f(CWset_values_hook\fP field to \f(CWNULL\fP. See \f(CWXtSetValues\fP(1) for details on when this method is called. See \f(CWset_values\fP(4) for a discussion of setting the values of subpart resources, and other resources that do not appear on the class resource list. .SH "See Also" .na .br \s-1\fIXtSetSubvalues\fR\s+1\*(s1, \s-1\fIXtSetValues\fR\s+1\*(s1, .br \s-1\fICore\fR\s+1\*(s3, .br \s-1\fIset_values\f(F2\*(s4. .ad .XE "set_values_hook method" .XE "methods, set_values_hook" .\"last line comment .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds v0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds v1 Volume One,\0\fIXlib Programming Manual\fP .ds v2 Volume Two,\0\fIXlib Reference Manual\fP .ds v4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds c4 Chapter 4,\0\fIAn Example Application\fP .ds c5 Chapter 5,\0\fIInside a Widget\fP .ds c6 Chapter 6,\0\fIBasic Widget Methods\fP .ds c7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds c8 Chapter 8,\0\fIMore Input Techniques\fP .ds c9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds c0 Chapter 10,\0\fIInterclient Communications\fP .ds c1 Chapter 11,\0\fIGeometry Management\fP .ds c2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds c3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds cc Appendix C,\0\fIEvent Reference\fP .ds cf Appendix F,\0\fITranslation Table Syntax\fP .P .. .ds ]V Last changed: 3/92 .de}H .ev1 .}C .}E .ie\\n()s 'sp 2v .el'sp 3v .ps\\n()S-1 .\".bd1 3 .tl\\*(]H\\*(]L .bd1 .ps\\n()S .ie\\n()s .sp .5.5v .el'sp 3v .ev .ns .. .de RH .po -5n .if n .TH "\\$1" "\\$3" "" "\\$2" .\".if t .TH "\\$1" "" "August 1990" "\\(co O'Reilly & Associates, Inc." "\\$2" .\".if n .ds ]L 9/90 .ds )H Copyright O'Reilly & Assoc. .. .ds F1 \\f(CW .ds F2 \\fR .de Sy .ft CW .. .de As .in +3n .. .de Ae .in .. .de Ps \" Printout start; $1 = indent (default is 5 spaces) .nr pS \\n(.s \" Save current point size .nr vS \\n(.v \" Save current vertical spacing .nr pF \\n(.f \" Save current font .nr pI \\n(.iu \" Save current indent .br .RT .sp \\n(PDu .ns .ps 9 .vs 11 .ft CW .ie !"\\$1"" .in \\n(.iu+\\$1n .el .in \\n(.iu+3n .nf .. .de Pe \" Printout end; if $1 non-null, no concluding blank line .br .if "\\$1"" .sp \\n(PDu .ps \\n(pS .vs \\n(vSu .ft \\n(pF .in \\n(pIu .\".rr pS .\".rr vS .rr pF .rr pI .fi .. .hw sub-class .hw super-class .hw sub-classes .hw super-classes .ds ol \s-1OPEN LOOK\s+1 .ds ]W X Toolkit Intrinsics Reference Manual \(co O'Reilly & Associates .\" Fonts and Section cross-ref strings, for See Also's .ds F1 \^\s-1\fI .ds F2 \fR\s+1 .ds s1 \^\s-1(1)\s+1 .ds s2 \^\s-1(2)\s+1 .ds s3 \^\s-1(3)\s+1 .ds s4 \^\s-1(4)\s+1 .ds s5 \^\s-1(5)\s+1 .ds s6 \^\s-1(6)\s+1 .\" Book names .ds V0 Volume Zero,\0\fIX Protocol Reference Manual\fP .ds V1 Volume One,\0\fIXlib Programming Manual\fP .ds V2 Volume Two,\0\fIXlib Reference Manual\fP .ds V3 Volume Three,\0\fIX Window System User's Guide\fP .ds V4 Volume Four,\0\fIX Toolkit Intrinsics Programming Manual\fP .ds V5 Volume Five,\0\fIX Toolkit Intrinsics Reference Manual\fP .ds V6 Volume Six,\0\fIX Toolkit Widget Reference Manual\fP .ds V7 Volume Seven,\0\fIXView Programming Manual\fP .\" Toolkit Chapters (xtp = X Toolkit Programming) .ds x1 Chapter 1,\0\fIIntroduction to the X Window System\fP .ds x2 Chapter 2,\0\fIIntroduction to the X Toolkit\fP .ds x3 Chapter 3,\0\fIMore Techniques for Using Widgets\fP .ds x4 Chapter 4,\0\fIAn Example Application\fP .ds x5 Chapter 5,\0\fIInside a Widget\fP .ds x6 Chapter 6,\0\fIBasic Widget Methods\fP .ds x7 Chapter 7,\0\fIEvents, Translations, and Accelerators\fP .ds x8 Chapter 8,\0\fIMore Input Techniques\fP .ds x9 Chapter 9,\0\fIResource Management and Type Conversion\fP .ds x0 Chapter 10,\0\fIInterclient Communications\fP .ds y1 Chapter 11,\0\fIGeometry Management\fP .ds y2 Chapter 12,\0\fIMenus, Gadgets, and Cascaded Pop Ups\fP .ds y3 Chapter 13,\0\fIMiscellaneous Toolkit Programming Techniques\fP .ds y4 Appendix A,\0\fIOPEN LOOK and Motif\fP .ds y5 Appendix B,\0\fISpecifying Fonts and Colors\fP .ds y7 Appendix D,\0\fIConverting Widgets from X11 Release 2 to X11 Release 3\fP .ds y8 Appendix E,\0\fIThe xbitmap Application\fP .ds y9 Appendix F,\0\fISources of Additional Information\fP .\" Toolkit Chapters (xtr = X Toolkit Reference) .ds z1 Appendix A,\0\fIFunction Summaries\fP .ds z2 Appendix B,\0\fIX Toolkit Data Types\fP .ds z3 Appendix C,\0\fIEvent Reference\fP .ds z4 Appendix D,\0\fIStandard Errors and Warnings\fP .ds z5 Appendix F,\0\fITranslation Table Syntax\fP .\" .ds r6 Appendix H,\0\fISources of Additional Information\fP .\" xlib z strings moved to /work/sedscrs ... .TH set_values_ 3X "" "" "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX 10.20 : April 1996 .SH NOTE .nf You have selected a name that conflicts with one or more other names. To display the manpage you want, enter the man command again with one of the following names. .sp .5 .sp 1 .in 0 .KS .TS tab(@); l l l l. If you want:@Enter the name: _ .sp set_values_almost@set_valuesA .sp .5 set_values_hook@set_valuesB .sp .5 .TE .KE .in .sp 1 .\" $Header: setaclentry.3c,v 78.1 95/12/20 11:11:07 ssa Exp $ .TA s .TH setaclentry 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setaclentry(\|), fsetaclentry(\|) \- add, modify, or delete one entry in file's access control list (ACL) .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "int setaclentry(const char *path, uid_t uid, gid_t gid, int mode);" .PP .C "int fsetaclentry(int fd, uid_t uid, gid_t gid, int mode);" .SH DESCRIPTION Both forms of this call add, modify, or delete one entry in a file's access control list .SM (ACL). .C setaclentry() and .C fsetaclentry() take a path name .RI ( path ) or open file descriptor .RI ( fd ) and an entry identifier .RI ( uid , .IR gid ). They change the indicated entry's access mode bits to the given value .RI ( mode ), meanings of which are defined in .RC < unistd.h >. .I modes are represented as .CR R_OK , .CR W_OK , and .CR X_OK . Irrelevant bits in .I mode values must be zero. .PP If the file's .SM ACL does not have an entry for the given .I uid and .IR gid , the entry is created and added to the .SM ACL. If .I mode is .C MODE_DEL (defined in .RC < acllib.h >), the matching entry is deleted from the file's .SM ACL if it is an optional entry, or its mode bits are set to zero (no access) if it is a base entry. .PP .I uid or .I gid can be .C ACL_NSUSER or .C ACL_NSGROUP (defined in .RC < sys/acl.h >), respectively, to represent non-specific entries .IC u .% , .CI %. g, or .C %.% . The file's .IC u .% or .CI %. g base entries can be referred to using .C ACL_FILEOWNER or .C ACL_FILEGROUP (defined in .RC < acllib.h >), for the file's owner or group .SM ID, respectively. .PP .C setaclentry() and .C fsetaclentry() read the file's .SM ACL with .C getacl() or .C fgetacl() and modify it with .C setacl() or .CR fsetacl() , respectively. .SH RETURN VALUE If successful, .C setaclentry() and .C fsetaclentry() return zero. .SH ERRORS If an error occurs, .C setaclentry() and .C fsetaclentry() return the following negative values and set .CR errno : .TP \(mi1 Unable to perform .C getacl() or .C fgetacl() on the file. .C errno indicates the cause. .TP \-2 Unable to perform .C stat() or .C fstat() on the file. .C errno indicates the cause. .TP \-3 Cannot add a new entry because the .SM ACL already has .C NACLENTRIES (defined in .RC < sys/acl.h >) entries. .TP \-4 Cannot delete a nonexisting entry. .TP \-5 Unable to perform .C setacl() or .C fsetacl() on the file. .C errno indicates the cause. .SH EXAMPLES The following code fragment adds an entry to file ``work/list'' for user .SM ID 115, group .SM ID 32, or modifies the existing entry for that user and group, if any, with a new access mode of read only. It also changes the owner base entry to have all access rights, and deletes the entry, if any, for any user in group 109. .nf .IP .C "#include " .C "#include " .IP .ift \f4\s+1char \(**filename = "work/list";\fP\s0 .ifn \f3char \(**filename = "work/list";\fP .IP .C "setaclentry\0(filename, 115, 32, R_OK);" .C "setaclentry\0(filename,\0ACL_FILEOWNER,\0ACL_NSGROUP,\0R_OK | W_OK | X_OK);" .C "setaclentry\0(filename,\0ACL_NSUSER, 109, MODE_DEL);\f1" .fi .SH DEPENDENCIES .TP 5 .SM NFS .C setaclentry() and .C fsetaclentry() are not supported on remote files. .SH AUTHOR .C setaclentry() and .C fsetaclentry() were developed by HP. .SH SEE ALSO getacl(2), setacl(2), stat(2), acltostr(3C), cpacl(3C), chownacl(3C), strtoacl(3C), acl(5). .\" .\" index@\f4setaclentry()\fP \- add, modify, or delete access control list entry@@@\f3setaclentry(3C)\f1 .\" index@\f4fsetaclentry()\fP \- add, modify, or delete access control list entry@@@\f3setaclentry(3C)\f1 .\" index@add, modify, or delete access control list entry@@@\f3setaclentry(3C)\f1 .\" index@modify, add, or delete access control list entry@@@\f3setaclentry(3C)\f1 .\" index@delete, add, or modify delete access control list entry@@@\f3setaclentry(3C)\f1 .\" index@access control list; add, modify, or delete entry@@@\f3setaclentry(3C)\f1 .\" toc@\f3setaclentry(3C)\f1:\0\0\f4setaclentry()\fP, \f4fsetaclentry()\fP@@@add, modify, or delete access control list entry .\" toc@\f4fsetaclentry()\fP: add, modify, or delete access control list entry@@@see \f3setaclentry(3C)\f1 .\" links@setaclentry.3c fsetaclentr.3c .\" .\" fileset_database@setaclentry.3c PROGRAMING-MAN .\" $Header: getbootpent.3x,v 74.1 95/05/10 21:04:42 ssa Exp $ .TA g .TH getbootpent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" =========== .SH NAME getbootpent(), putbootpent(), setbootpent(), endbootpent(), parse_bp_htype(), parse_bp_haddr(), parse_bp_iaddr() \- get or put bootptab entry .\" =========== .SH SYNOPSIS .C "#include " .PP .C "int getbootpent (struct bootpent **bootpent);" .PP .C "int setbootpent (const char *path);" .PP .C "int endbootpent (void);" .PP .C "void putbootpent (" .nf .PD 0 .IP .C "const struct bootpent *bootpent," .C "const int numfields," .C "\s-1FILE\s0 * bootpfile" .PP .C ");" .PD .fi .PP .C "int parse_bp_htype (const char *source);" .PP .C "int parse_bp_haddr (" .nf .PD 0 .IP .C "char **source," .C "int htype," .C "unsigned char *result," .C "unsigned int *bytes" .PP .C ");" .PD .PP .C "int parse_bp_iaddr (" .nf .PD 0 .IP .C "char **source," .C "unsigned long *result" .PP .C ");" .PD .\" =========== .SS Remarks These functions reside in libdc.a, and are linked using the .C -ldc option to the .C ld or .C cc command. .\" =========== .SH DESCRIPTION These functions help a program read or modify a bootptab .RC ( bootpd control) file one entry at a time. .C getbootpent() locates an entry in the .C /etc/bootptab file, or an alternate file specified to .CR setbootpent() , and returns a pointer to an array of objects of type .C struct bootpent that breaks the entry into separate data fields with preceding, or embedded, comment (text) lines. .PP The .C bootpent structure is defined in .RC < bootpent.h > and includes the following members: .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. int@bp_type;@/* BP_DATA, BP_COMMENT, BP_BLANK@*/ char@*bp_text;@/* one field or one comment line@*/ .TE .ft P .RE .PP The file also defines the following data type and constants: .IP .C "typedef struct bootpent *bpp_t;" .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l. #define BP_NULLP@((bpp_t) 0) #define BP_SIZE@(sizeof (struct bootpent)) .TE .ft P .RE .PP .RS .ifn \f3 .ift \f4 .TS tab(@); l l l l. #define MAXHADDRLEN@6 #define HTYPE_UNKNOWN@0@/* 0 bytes@*/ #define HTYPE_ETHERNET@1@/* 6 bytes@*/ #define HTYPE_EXP_ETHERNET@2@/* 1 byte@*/ #define HTYPE_AX25@3@/* 0 bytes@*/ #define HTYPE_PRONET@4@/* 1 byte@*/ #define HTYPE_CHAOS@5@/* 0 bytes@*/ #define HTYPE_IEEE802@6@/* 6 bytes@*/ #define HTYPE_ARCNET@7@/* 0 bytes@*/ #define MAXHTYPES@7 .TE .ft P .RE .PP The fields are described in the .RB `` "Field Definitions" '' section below. The purpose of each function is as follows. .TP 25 .C getbootpent() When first called, .C getbootpent() returns a pointer to, and the number of elements in, an array of .C bootpent structures. The array holds the first entry in the .C /etc/bootptab file (or from an alternate file specified by a call to .CR setbootpent() ), including leading, or embedded, comment lines. Each subsequent call returns a pointer to the next entry in the file so that successive calls can be used to search the entire file. .IP If no file is currently in memory, .C getbootpent() reads the .C /etc/bootptab file prior to doing its work. .IP The returned array exists in static space (malloc'd memory) overwritten by the next call (so previously returned pointers become invalid). However, each array element's .C bp_text pointer points to text in an in-memory copy of the file. This text is not altered by the next call (nor by changes to the file itself). Hence, it is possible to copy an entry's array in order to save it, as illustrated in .SM EXAMPLES below. The data remains valid until the next call of .C setbootpent() or .CR endbootpent(). .IP If there are comments after the last entry, they are returned as a separate entry with no data parts. .TP .C setbootpent() Opens the specified file for reading by .CR getbootpent() , reads a copy into memory, and closes the file (which as a side-effect releases any locks on the file; see .IR lockf (2)). If the given .I path is a null pointer or a null string, .C setbootpent() opens and reads .CR /etc/bootptab . .IP If the last file opened by .C setbootpent() (or implicitly by .CR getbootpent() ) was .CR /etc/bootptab , a subsequent call to .C setbootpent() for the same file rewinds the file to the beginning, making visible any recent changes to the file, without first requiring a call to .CR endbootpent() . .TP .C endbootpent() Frees the in-memory copy of the last file opened by .CR setbootpent() , or .CR getbootpent() . .TP .C putbootpent() Writes (to the current location in the stream specified by .IR bootpfile ) the .SM ASCII equivalent of the specified array of .C bootpent structures containing one file entry, and its leading, or embedded, comments (a total of .I numfields array elements). Entries are written in canonical form, meaning the entry name and each data field are on separate lines, data fields are preceded by one tab each, and each line except the last ends with ``:\e''. If .I numfields is less than or equal to zero, nothing is written. .TP .C parse_bp_htype() Converts a host address type from string to numeric format .RC ( HTYPE_ *) in the same manner as .CR bootpd . .TP .C parse_bp_haddr() Converts a host (hardware, link level) address from string to binary format in the same manner as .C bootpd given a host address type .RC ( HTYPE_ *). The calling program's .IR result , which must be an array containing at least .SM MAXHADDRLEN elements, is modified to hold the host address binary value, and .C bytes is modified to indicate the length in bytes of the resulting address. This can be used to compare two host addresses, independent of string representations. .I source is modified to point to the first char after the parsed address. .TP .C parse_bp_iaddr() Converts an internet address from string to binary format in the same manner as .CR bootpd . This can be used to compare two internet addresses, independent of string representations. The calling program's .I result is modified to hold the internet address binary value. .I source is modified to point to the first char after the parsed address. .\" ----------- .SS Field Definitions If .C bootpent.bp_type is .SM BP_DATA, the associated text is one field from the current entry, either the name field or one of the tag fields. Null tag fields (two colons in a row) are ignored, not returned. .PP If .C bootpent.bp_type is .SM BP_COMMENT or .SM BP_BLANK, the associated text is one comment line or blank line from the file, either preceding the current entry or embedded in it following a data line that was continued with a backslash. The text is exactly as it appears in the file, including any whitespace appearing on a blank line, and there is no trailing newline. .PP The returned array elements are in the same order as data fields and comment lines appear in the file. .PP Entry field strings are of the form: .IP .IR tag [\c .ift \f4\s+1@\s0\fP\c .ifn \f3@\fP\c .RC ]\|[ =\c .C """\c .I value\c .C """\c .RC ] .PP with surrounding whitespace, if any, removed (see .IR bootpd (1M) for the full description). Double quotes, and backslashes, can appear anywhere in the field strings. .PP Template entries (those referred to by other entries using .C tc fields) are not special. They can be managed like other entries. It is the calling program's responsibility to correctly manage the order of fields, .C tc fields, and ``@'' fields that override earlier field values. .\" =========== .SH RETURN VALUE .C getbootpent() returns the number of valid array elements (one or more) upon successful completion. At the end of the input file it returns zero. If it cannot open or close the file it returns \-1. If it encounters a memory allocation or map error, or a read error, it returns \-2. .PP .C setbootpent() returns zero if successful opening and reading the specified or default file. If it cannot open or close the file it returns \-1. If it encounters a memory allocation or map error or a read error it returns \-2. .PP .C endbootpent() returns zero if successful freeing the memory for the current open file. If there is no current file it returns \-1. If it cannot free the memory for the current file it returns \-2. .PP .C putbootpent() returns zero if successful writing an entry to the specified file, with the .C ferror() indication clear (see .IR ferror (3S)). Otherwise it returns non-zero with .C ferror() set. .PP In all cases above, if a failure is due to a failed system call, the .C errno value from the system is valid on return from the called function. .PP .C parse_bp_htype() returns .SM HTYPE_UNKNOWN if the hardware type string is unrecognized. .PP .C parse_bp_haddr() returns zero if successful, otherwise non-zero in case of parsing error, invalid .IR htype , or a host address type for which the address length is unknown; .I source is modified to point to the first illegal char (a .SM NUL if the string is too short). The caller's .I bytes value is unmodified, but .I result might be changed. .PP .C parse_bp_iaddr() returns zero if successful, otherwise non-zero, and .I source is modified to point to the first illegal char (a .SM NUL if the string is null). .\" =========== .SH EXAMPLES The following code fragment copies all data and comments from .C /etc/bootptab to a temporary copy of the file. It converts data entries to canonical form as a side effect, and prints to standard output the first field of each entry copied (should be the field name, assuming the entry doesn't start with a continuation line). .RS .PP .nf .ifn \f3 .ift \f4 #include \s-1FILE\s0 *newfilep; /* to write temp file */ bpp_t bp; /* read from file */ int field; /* current field number */ int fields; /* total in array for one entry */ if ((newfilep = fopen ("/tmp/bootptab", "w")) == (\s-1FILE\s0 *) \s-1NULL\s0) { \f2(handle error)\fP } while ((fields = getbootpent (&bp)) > 0) { for (field = 0; field < fields; ++field) { if ((bp[field].bp_type) == \s-1BP_DATA\s0) { (void) puts (bp[field].bp_text); break; } } if (putbootpent (bp, fields, newfilep)) { \f2(handle error)\fP } } if (fields < 0) /* error reading file */ { \f2(handle error)\fP } if (endbootpent()) { \f2(handle error)\fP } if (fclose (newfilep)) { \f2(handle error)\fP } .ft P .fi .RE .PP The following code fragment saves a copy of a bootptab entry returned by .CR getbootpent() . .RS .PP .nf .ifn \f3 .ift \f4 #include #include #include bpp_t bpnew; unsigned size; size = fields *\s-1BP_SIZE\s0; if ((bpnew = (bpp_t) malloc (size)) == \s-1BP_NULLP\s0) { \f2(handle error)\fP } (void) memcpy ((void *)bpnew, (void *)bp, size); .ft P .fi .RE .\" =========== .SH WARNINGS These functions are unsafe in multi-thread applications. .PP Calling .C setbootpent() releases any locks on the file it opens. .\" =========== .SH AUTHOR .PP These functions were developed by .SM HP. .\" =========== .SH FILES .TP 20 .C /etc/bootptab control file for .C bootpd .\" =========== .SH SEE ALSO bootpd(1M), .\" chbootptab(1M), (SAM-only, not currently supported for 10.0) errno(2), lockf(2), ferror(3S), fopen(3S), malloc(3C). .\" .\" toc@\f3getbootpent(3X)\f1:\0\0\f4getbootpent(), putbootpent(), setbootpent(), endbootpent(), \nparse_bp_htype(), parse_bp_hpaddr(), parse_bp_iaddr()\f1@@@get, or put bootptab entry .\" .\" index@get, or put bootptab entry \- @@@\f3getbootpent(3X)\f1 .\" index@bootptab entry, get or put@@@\f3getbootpent(3X)\f1 .\" .\" links@getbootpent.3x setbootpent.3x .\" links@getbootpent.3x endbootpent.3x .\" links@getbootpent.3x putbootpent.3x .\" links@getbootpent.3x parse_bp_htype.3x .\" links@getbootpent.3x parse_bp_haddr.3x .\" links@getbootpent.3x parse_bp_iaddr.3x .\" $Header: setbuf.3s,v 72.5 94/11/15 09:56:11 ssa Exp $ .TA s .TH setbuf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setbuf(\|), setvbuf(\|), setvbuf_unlocked(\|) \- assign buffering to a stream file .SH SYNOPSIS .C "#include " .PP .C "void setbuf(FILE *stream, char *buf);" .PP .C "int setvbuf(FILE *stream, char *buf, int type, size_t size);" .PP .C "int setvbuf_unlocked(FILE *stream, char *buf, int type, size_t size);" .SH DESCRIPTION .CR setbuf() can be used after a stream has been opened but before it is read or written. It causes the array pointed to by .I buf to be used instead of an automatically allocated buffer. If .I buf is the .SM NULL pointer input/output will be completely unbuffered. .PP A constant .CR BUFSIZ , defined in the .RC < stdio.h > header file, tells how big an array is needed: .IP .CR char buf[BUFSIZ]; .PP .CR setvbuf() can be used after a stream has been opened but before it is read or written. .I type determines how .I stream is to be buffered. Legal values for .I type (defined in .RC < stdio.h >) are: .RS .TP 12 .CR _IOFBF causes input/output to be fully buffered. .TP .CR _IOLBF causes output to be line buffered; the buffer will be flushed when a newline is written, the buffer is full, or input is requested. .TP .CR _IONBF causes input/output to be completely unbuffered. .RE .PP When an output stream is unbuffered, information is queued for writing on the destination file or terminal as soon as written; when it is buffered, many characters are saved up and written as a block. When the output stream is line-buffered, each line of output is queued for writing on the destination terminal as soon as the line is completed (that is, as soon as a new-line character is written or terminal input is requested). .CR fflush() can also be used to explicitly write the buffer. .PP If .I buf is not the .SM NULL pointer, the array it points to is used for buffering instead of an automatically allocated buffer (from .CR malloc() ). .I size specifies the size of the buffer to be used. The constant .CR BUFSIZ in .RC < stdio.h > is suggested as a good buffer size. If input/output is unbuffered, .I buf and .I size are ignored. .PP By default, output to a terminal is line buffered and all other input/output is fully buffered. .PP .CR setvbuf_unlocked() is identical to .CR setvbuf() except it does not perform any internal locking of the .I stream for multi-thread applications. .CR setvbuf_unlocked() can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH DIAGNOSTICS If an illegal value for .I type or .I size is provided, .CR setvbuf() " and " setvbuf_unlocked() return a non-zero value. Otherwise, the value returned will be zero. .SH NOTE A common source of error is allocating buffer space as an ``automatic'' variable in a code block, then failing to close the stream in the same block. .SH SEE ALSO flockfile(3S), fopen(3S), getc(3S), malloc(3C), putc(3S), stdio(3S). .SH STANDARDS CONFORMANCE .CR setbuf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR setvbuf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4setbuf()\fP, \f4setvbuf()\fP \- assign buffering to a stream file@@@\f3setbuf(3S)\f1 .\" index@assign buffering to a stream file@@@\f3setbuf(3S)\f1 .\" index@buffering, assign to a stream file@@@\f3setbuf(3S)\f1 .\" index@stream file, assign buffering to a@@@\f3setbuf(3S)\f1 .\" index@file: assign buffering to a stream file@@@\f3setbuf(3S)\f1 .\" .\" toc@\f3setbuf(3S)\f1:\0\0\f4setbuf()\fP, \f4setvbuf()\fP@@@assign buffering to a stream file .\" toc@\f4setvbuf()\fP:\0\0assign buffering to a stream file@@@see \f3setbuf(3S)\f1 .\" .\" links@setbuf.3s setvbuf.3s .\" links@setbuf.3s setvbuf_unl.3s .\" $Header: setcat.3c,v 72.2 94/07/03 16:53:24 ssa Exp $ .TA s .TH setcat 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setcat() \- set the default message catalog .SH SYNOPSIS .C "#include " .PP .C "char *setcat(const char *msgcat);" .SH DESCRIPTION The .CR setcat() routine sets the default message catalog for use by other formatting routines (see .IR gettxt (3C), .IR pfmt (3C), and .IR vpfmt (3C)). .PP .IR msgcat specifies the file to use as the default catalog. The file name is limited to 14 characters. No checking is done to make sure that the file exists. The value of .IR msgcat determines what happens to the default message catalog: .RS .TP 15 .IR string Sets the default message catalog to .IR string . .TP .CR NULL Returns a pointer to the current default message catalog. The default catalog is not changed. .TP empty string Resets to no catalog. .SH RETURN VALUE Upon successful completion, .CR setcat() returns a pointer to the default catalog. Otherwise, .CR setcat() returns a NULL pointer. .SH EXAMPLES The following example gets its message from the .CR my_appl_cat message catalog file: .nf .IP .C setcat("my_appl_cat"); .C pfmt(stderr, MM_INFO,":1:The file is writable"); .fi .SH SEE ALSO gettxt(3C), pfmt(3C), setlocale(3C), vpfmt(3C). .SH STANDARDS COMPLIANCE .CR setcat() ": SVID3" .\" .\" toc@\f3setcat(3)\f1:\0\0\f4setcat()\f1@@@set the default message catalog\f1 .\" .\" index@\f4setcat()\f1 \- set the default message catalog@@@\f3setcat(3)\f1 .\" index@\f1set the default message catalog@@@\f3setcat(3)\f1 .\" index@\f1default message catalog, set@@@\f3setcat(3)\f1 .\" index@\f1message catalog, set the default@@@\f3setcat(3)\f1 .\" index@\f1catalog, set the default message@@@\f3setcat(3)\f1 .\" $Header: setcchar.3x,v 76.2 95/08/01 14:44:37 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH setcchar 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setcchar \(em set \f3cchar_t\f1 from a wide character string and rendition .SH SYNOPSIS .C "#include " .P .C "int setcchar(cchar_t *\f2wcval\fP, wchar_t *const \f2wch\fP, const attr_t \f2attrs\fP," .br .C " short \f2color_pair\fP, void *const \f2opts\fP);" .SH DESCRIPTION The .Fn setcchar function initialises the object pointed to by .I wcval according to the character attributes in .I attrs , the colour pair in .I color_pair and the wide character string pointed to by .I wch . .P The \f2opts\f1 argument is reserved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" Upon successful completion, .Fn setcchar returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Characters\f1 in curs_intro, attroff(), can_change_color(), getcchar(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4setcchar()\f1 \- set \f4cchar_t\f1 from a wide character string and rendition@@@\f3setcchar(3X)\f1 .\" index@\f1set \f4cchar_t\f1 from a wide character string and rendition@@@\f3setcchar(3X)\f1 .\" index@\f1\f4cchar_t\f1, set from a wide character string and rendition@@@\f3setcchar(3X)\f1 .\" index@\f1wide character string and rendition, set \f4cchar_t\f1@@@\f3setcchar(3X)\f1 .\" .\" toc@\f3setcchar(3X)\f1:\0\0\f4setcchar()\f1@@@set \f4cchar_t\f1 from a wide character and rendition .\" .\" fileset_database@setcchar.3x CURS-ENG-A-MAN .\" $Header: setclock.3c,v 72.5 94/11/15 09:56:12 ssa Exp $ .TA s .TH setclock 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setclock \- set value of system-wide clock .SH SYNOPSIS .C "#include " .PP .C "int setclock(int clock_type, struct timespec *tp);" .SH DESCRIPTION The .CR setclock() function sets the current value .CR tp of the specified system-wide clock, .CR clock_type . .PP .CR setclock() supports a .CR clock_type of .CR TIMEOFDAY , defined in .RC < sys/timers.h >, which represents the time-of-day clock for the system. For this clock, the values returned by .CR setclock() represent the amount of time since the Epoch. .PP The calling process must have appropriate privileges to set the .CR TIMEOFDAY clock. .SH RETURN VALUE Upon successful completion, .CR setclock() returns a value of zero; otherwise it returns \(mi1 and sets .CR errno to indicate the error. .SH ERRORS .CR setclock() fails if any of the following conditions are encountered: .RS .TP 12 [EINVAL] .CR clock_type does not specify a known system-wide clock, or .CR tp either is outside the range for a given clock type, or it specifies a nanosecond value less than zero or greater than or equal to 1000 million. .TP [EIO] An error occurred while accessing the clock device. .TP [EPERM] The requesting process does not have the required appropriate privileges to set the specified clock. .RE .SH FILES .C /usr/include/sys/timers.h .SH SEE ALSO clock_settime(2), getclock(3C), gettimer(3C). .SH STANDARDS CONFORMANCE .CR setclock() ": AES" .\" .\" toc@\f3setclock(3C)\f1:\0\0\f4setclock()\f1@@@set value of system-wide clock\f1 .\" .\" index@\f4setclock()\f1 \- set value of system-wide clock@@@\f3setclock(3C)\f1 .\" index@\f1set value of system-wide clock@@@\f3setclock(3C)\f1 .\" index@\f1value of system-wide clock, set@@@\f3setclock(3C)\f1 .\" index@\f1system-wide clock, set value of@@@\f3setclock(3C)\f1 .\" index@\f1clock, set value of system-wide@@@\f3setclock(3C)\f1 .\" $Header: getdvagent.3,v 72.3 94/07/05 17:58:22 ssa Exp $ .TA g .TH getdvagent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getdvagent, getdvagnam, setdvagent, enddvagent, putdvagnam, copydvagent \- manipulate device assignment database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct dev_asg \(**getdvagent(\|);" .PP .CR "struct dev_asg \(**getdvagnam(const char \(**name);" .PP .CR "void setdvagent(\|);" .PP .CR "void enddvagent(\|);" .PP .CR "int putdvagnam(const char \(**name, struct dev_asg \(**dv);" .PP .CR "struct dev_asg \(**copydvagent(struct dev_asg \(**dv);" .fi .SH DESCRIPTION .IR getdvagent , .IR getdvagnam , and .I copydvagent each return a pointer to an object with the following structure containing the broken-out fields of an entry in the Device Assignment database. Each database entry is returned as a .I dev_asg structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v struct dev_field { char *fd_name; /* external name */ char **fd_devs; /* device list */ mask_t fd_type[1]; /* tape, printer, terminal */ char **fd_users; /* authorized user list */ }; .IP /* Device Assignment Database entry */ .IP #define \s-1AUTH_DEV_TYPE\s0 "device type" #define \s-1AUTH_DEV_PRINTER\s0 0 #define \s-1AUTH_DEV_TERMINAL\s0 1 #define \s-1AUTH_DEV_TAPE\s0 2 #define \s-1AUTH_DEV_REMOTE\s0 3 #define \s-1AUTH_MAX_DEV_TYPE\s0 3 #define \s-1AUTH_DEV_TYPE_SIZE\s0 (\s-1WORD_OF_BIT\s0 (\s-1AUTH_MAX_DEV_TY PE\s0) + 1) .IP /* this structure tells which of the corresponding fields * in dev_field are valid (filled). */ struct dev_flag { unsigned short fg_name : 1, fg_devs : 1, fg_type : 1, fg_users : 1, ; }; .IP struct dev_asg { struct dev_field ufld; struct dev_flag uflg; struct dev_field sfld; struct dev_flag sflg; }; .fi .PP The Device Assignment database stores device characteristics that are related to user authorizations and synonyms. On systems supporting network connections, the Device Assignment database stores information about hosts initiating connections. .PP Each entry contains a .IR name , which is a cross reference to the terminal control database, and a list of .IR devices , each of which is a pathname corresponding to that device. This list allows the device assignment software of the trusted system to invalidate all references to a device when re-assigning it. The list is a table of character string pointers, whose last entry is a .SM .B NULL pointer. .PP .I fd_users is a pointer to a null-terminated table of character string pointers referring to user allowed access. .PP For trusted system versions supporting network connections, the device name can be a 12 character host name, where the first 8 characters are the .SM ASCII hex address of the device, and the last 4 characters are .SM ASCII zeroes. For example, a host with Internet address 129.75.0.3 has device name 814b00030000. The trailing four zeroes are for compatibility with ports on terminal concentrators. The SAM API's supports conversion of host name to device name. Thus, sensitivity level ranges and user authorization lists can be enforced on hosts as well as on directly connected terminals. .PP When .I getdvagent is first called, it returns a pointer to the first device assignment entry. Thereafter, it returns a pointer to the next entry, so successive calls can be used to search the database. .I getdvagnam searches from the beginning of the database until an entry with a device name matching .I name is found, and returns a pointer to that entry. If an end of file or an error is encountered on reading, these functions return a .SM .B NULL pointer. .I copydvagent copies a device assignment structure and the fields to which it refers to a newly-allocated data area. Since .IR getdvagent , .IR getdvagnam , and .I putdvagent re-use a static structure when accessing the database, the values of any entry must be saved if these routines are used again. The .I dev_asg structure returned by .I copydvagent can be freed using .I free (see .IR malloc (3C) or .IR malloc (3X)). .PP A call to .I setdvagent has the effect of setting the device assignment database back to the first entry, to allow repeated searches of the database. .I enddvagent frees all memory and closes all files used to support these routines. .PP .I putdvagnam rewrites or adds an entry to the database. If there is an entry whose .I fd_name field matches the .I name argument, that entry is replaced with the contents of the .I dv structure. Otherwise, that entry is added to the database. .SH RETURN VALUE .IR getdvagent and .IR getdvagnam return a pointer to a static structure on success, or a .SM .B NULL pointer on failure. This static structure is overwritten by .IR getdvagent , .IR getdvagnam , and .IR putdvagnam . .PP .I putdvagnam returns 1 on success, or 0 on failure. .PP .I copydvagent returns a pointer to the newly-allocated structure on success, or a .SM .B NULL pointer if there was a memory allocation error. .SH "WARNINGS" The structure returned by this routine contains .I pointers to character strings and lists rather than being self-contained. .I copydvagent must be used instead of structure assignments to save a returned structure. .PP The value returned by .I getdvagent and .I getdvagnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using .I copydvagent and supply the modified buffer to .IR putdvagent . .SH NOTES Programs using this routine must be compiled with .BR \-lsec . .SH AUTHOR SecureWare Inc. .SH FILES .TP 40 .CR /tcb/files/devassign Device assignment database .PD .SH SEE ALSO authcap(4). .\" .\" index@\f4getdvagent\f1 \- return pointer for device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f1getdvagnam\f1 \- return success or failure information@@@\f3getdvagent(3)\f1 .\" index@\f4setdvagent\f1 \- set device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f4enddvagent\f1 \- free memory and close file@@@\f3getdvagent(3)\f1 .\" index@\f4putdvagnam\f1 \- add or rewrite device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f4copydvagent\f1 \- copy device assignment structure@@@\f3getdvagent(3)\f1 .\" index@\f1manipulate device assignment database entry@@@\f3getdvagent(3)\f1 .\" index@\f1device assignment database entry, manipulate@@@\f3getdvagent(3)\f1 .\" index@\f1assignment database entry, manipulate device@@@\f3getdvagent(3)\f1 .\" index@\f1database entry, manipulate device assignment@@@\f3getdvagent(3)\f1 .\" .\" .\" toc@\f3getdvagent(3)\f1:\0\0\f4getdvagent\f1, \f4getdvagnam\f1, \f4setdvagent\f1, \f4enddvagent\f1, \f4putdvagnam\f1, \n\f4copydvagent\f1@@@manipulate device assignment database entry for a trusted system .\" toc@\f4getdvagent\f1:\0\0return pointer for device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4getdvagnam\f1:\0\0return success or failure information@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4setdvagent\f1:\0\0set device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4enddvagent\f1:\0\0free memory and closes file@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4putdvagnam\f1:\0\0add or rewrite device assignment database entry@@@\f1see \f3getdvagent(3)\f1 .\" toc@\f4copydvagent\f1:\0\0copy device assignment structure@@@\f1see \f3getdvagent(3)\f1 .\" .\" .\" links@getdvagent.3 getdvagnam.3 .\" links@getdvagent.3 setdvagent.3 .\" links@getdvagent.3 enddvagent.3 .\" links@getdvagent.3 putdvagnam.3 .\" links@getdvagent.3 copydvagent.3 .\" .\" fileset_database@getdvagent.3 UX-CORE-MAN .\" $Header: exportent.3n,v 74.1 95/01/25 16:26:52 ssa Exp $ .TA e .TH exportent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME exportent(\|), getexportent(\|), setexportent(\|), addexportent(\|), remexportent(\|), endexportent(\|), getexportopt(\|) \- access exported file system information .SH SYNOPSIS .nf .C #include .C #include .PP .C "FILE *setexportent();" .PP .C "struct exportent *getexportent(FILE *fildep);" .PP .C "int addexportent(FILE *filep, char *dirname, char *options);" .PP .C "int remexportent(FILE *filep, char *dirname);" .PP .C "char *getexportopt(struct exportent *xent, char *opt);" .PP .C "void endexportent(FILE *filep);" .fi .SH DESCRIPTION These routines access the exported filesystem information in .CR /etc/xtab . .ift .TP 22 .ifn .TP 10 .C setexportent() Open the export information file and return a file pointer to use with .CR getexportent() , .CR addexportent() , .CR remexportent() , and .CR endexportent() . Returns .SM NULL if the file is locked or if an error is encountered in opening the file. .TP .C getexportent() Read the next line from .I filep and return a pointer to an object with the following structure containing the broken-out fields of a line in file .CR /etc/xtab . The fields have meanings described in .IR exports (4). .nf .IP .ift .ft 4 .ifn .ft 3 #define ACCESS_OPT "access" /* machines that can mount fs */ #define ROOT_OPT "root" /* machines with root access to fs */ #define RO_OPT "ro" /* export read-only */ #define ANON_OPT "anon" /* uid for anonymous requests */ #define ASYNC_OPT "async" /* all mounts will be aynchronous */ .ift .sp .5v .ifn .sp 1v struct exportent { char *xent_dirname; /* directory (or file) to export */ char *xent_options; /* options, as above */ }; .ft .fi .IP .C getexportent() returns .SM NULL if it encounters end of file. .TP .C addexportent() Add the .I exportent to the end of the open file .IR filep . It returns 0 if successful and \(mi1 on failure. .TP .C remexportent() Remove the indicated entry from the list. Returns 0 on success and \(mi1 on failure. .TP .C getexportopt() Scans the .C xent_options field of the .C exportent structure for a substring that matches .IR opt . Returns the string value of .IR opt , or .SM NULL if the option is not found. .TP .C endexportent() Close the file. .SH RETURN VALUE .CR setexportent() , .CR getexportent() , and .C getexportopt() return a .SM NULL pointer on .SM EOF or error. .PP .C addexportent() and .C remexportent() return \(mi1 if they fail. .SH WARNINGS The returned .C exportent structure points to static information that is overwritten in each call. .SH AUTHOR .CR exportent , .CR getexportent() , .CR setexportent() , .CR addexportent() , .CR remexportent() , .CR endexportent() , and .C getexportopt() were developed by Sun Microsystems, Inc. .SH FILES .C /etc/exports .C /etc/xtab .SH SEE ALSO exportfs(1M), exports(4). .\" .\" toc@\f3exportent(3N)\f1:\0\0\f4exportent(\|)\f1, \f4getexportent(\|)\f1, \f4setexportent(\|)\f1, \f4addexportent(\|)\f1, \f4remexportent(\|)\f1,\n\f4endexportent(\|)\f1, \f4getexportopt(\|)\f1@@@access exported file system information .\" toc@\f4getexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4setexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4addexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4remexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4endexportent(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" toc@\f4getexportopt(\|)\f1 \- access exported file system information@@@see \f3exportent(3N)\f1 .\" .\" index@\f4exportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4getexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4setexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4addexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4remexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4endexportent(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@\f4getexportopt(\|)\f1 \- access exported file system information@@@\f3exportent(3N)\f1 .\" index@access exported file system information@@@\f3exportent(3N)\f1 .\" index@exported file system information, access@@@\f3exportent(3N)\f1 .\" index@file system information, access exported@@@\f3exportent(3N)\f1 .\" index@information, access exported file system@@@\f3exportent(3N)\f1 .\" .\" links@exportent.3n getexporten.3n .\" links@exportent.3n setexporten.3n .\" links@exportent.3n addexporten.3n .\" links@exportent.3n remexporten.3n .\" links@exportent.3n endexporten.3n .\" links@exportent.3n getexportop.3n .\" .\" fileset_database@exportent.3n PROGRAMING-MAN .\" $Header: getfsent.3x,v 72.4 94/11/02 14:55:23 ssa Exp $ .TA g .TH getfsent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getfsent(\|), getfsspec(\|), getfsfile(\|), getfstype(\|), setfsent(\|), endfsent(\|) \- get file system descriptor file entry .SH SYNOPSIS .C "#include " .PP .C "struct checklist *getfsent(void);" .PP .C "struct checklist *getfsspec(const char *spec);" .PP .C "struct checklist *getfsfile(const char *file);" .PP .C "struct checklist *getfstype(const char *type);" .PP .C "int setfsent(void);" .PP .C "int endfsent(void);" .SS Remarks: These routines are included only for compatibility with 4.2 .SM BSD. For maximum portability and improved functionality, new applications should use the .IR getmntent (3X) library routines. .SH DESCRIPTION .CR getfsent() , .CR getfsspec() , .CR getfsfile() , and .C getfstype() each returns a pointer to an object with the following structure containing the broken-out fields of a line in the .C /etc/fstab file. The structure is declared in the .RC < checklist.h > header file: .nf .IP .C "struct checklist {" .C " char *fs_spec; /* special file name */" .C " char *fs_bspec; /* block special file name */" .C " char *fs_dir; /* file sys directory name */" .C " char *fs_type; /* type: ro, rw, sw, xx */" .C " int fs_passno; /* fsck pass number */" .C " int fs_freq; /* backup frequency */" .C }; .fi .PP The fields have meanings described in .IR fstab (4). If the block special file name, the file system directory name, and the type are not all defined on the associated line in .CR /etc/fstab , these routines return pointers to .SM NULL in the .CR fs_bspec , .CR fs_dir , and .C fs_type fields. If the pass number or the backup frequency field are not present on the line, these routines return \(mi1 in the corresponding structure member. .C fs_freq is reserved for future use. .TP 20 .C getfsent() Reads the next line of the file, opening the file if necessary. .TP .C setfsent() Opens and rewinds the file. .TP .C endfsent() Closes the file. .TP .C getfsspec() Sequentially searches from beginning of file until a matching special file name is found, or until .SM EOF is encountered. .TP .C getfsfile() Sequentially searches from the beginning of the file until a matching file system file name is found, or until .SM EOF is encountered. .C getfstype() Sequentially searches from the beginning of the file until a matching file system type field is found, or until .SM EOF is encountered. .SH DIAGNOSTICS A null pointer is returned on .SM EOF, invalid entry, or error. .SH WARNINGS Since all information is contained in a static area, it must be copied to be saved. .SH AUTHOR .C getfsent() was developed by HP and the University of California, Berkeley. .SH FILES .C /etc/fstab .SH SEE ALSO fstab(4). .\" index@\f4getfsent()\fP \- get next line in file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@\f4getfsspec()\fP \- search descriptor file for special (device) file entry@@@\f3getfsent(3X)\f1 .\" index@\f4getfsfile()\fP \- search descriptor file for ordinary file entry@@@\f3getfsent(3X)\f1 .\" index@\f4getfstype()\fP \- search descriptor file for specified file type entry@@@\f3getfsent(3X)\f1 .\" index@\f4setfsent()\fP \- open and rewind file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@\f4endfsent()\fP \- close file system descriptor file@@@\f3getfsent(3X)\f1 .\" index@get: file system descriptor file entry (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@file system: get file system descriptor file entry (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@descriptor file entry, get file system (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@file entry, get file system descriptor (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" index@entry, get file system descriptor file (\s-1BSD\s0 4.2 compatibility only)\f1@@@\f3getfsent(3X)\f1 .\" .\" toc@\f3getfsent(3X)\f1:\0\0\f4getfsent()\fP, \f4getfsspec()\fP, \f4getfsfile()\fP, \f4getfstype()\fP,\n\f4setfsent()\fP, \f4endfsent()\fP@@@get file system descriptor file entry .\" toc@\f4getfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfsspec()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfsfile()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4getfstype()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4setfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" toc@\f4endfsent()\fP:\0\0get file system descriptor file entry@@@see \f3getfsent(3X)\f1 .\" .\" links@getfsent.3x getfsspec.3x .\" links@getfsent.3x getfsfile.3x .\" links@getfsent.3x getfstype.3x .\" links@getfsent.3x setfsent.3x .\" links@getfsent.3x endfsent.3x .\" .\" fileset_database@getfsent.3x PROGRAMING-MAN .\" $Header: getgrent.3c,v 76.1 95/07/05 17:29:02 ssa Exp $ .TA g .TH getgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getgrent(\|), getgrent_r(\|), getgrgid(\|), getgrgid_r(\|), getgrnam(\|), getgrnam_r(\|), setgrent(\|), setgrent_r(\|), endgrent(\|), endgrent_r(\|), fgetgrent(\|), fgetgrent_r(\|) \- get group file entry .SH SYNOPSIS .C "#include " .PP .C "struct group *getgrent(void);" .PD 0 .PP .C "int getgrent_r(" .nf .PD 0 .IP .C "struct group *result," .C "char *buffer," .C "int buflen," .C "FILE **grfp);" .PD 0 .PP .C "struct group *getgrgid(gid_t gid);" .PP .C "int getgrgid_r(" .nf .PD 0 .IP .C "gid_t gid," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "struct group *getgrnam(const char *name);" .PP .C "int getgrnam_r(" .nf .PD 0 .IP .C "const char *name," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "void setgrent(void);" .PP .C "void setgrent_r(FILE **grfp);" .PP .C "void endgrent(void);" .PP .C "void endgrent_r(FILE **grfp);" .PP .C "struct group *fgetgrent(FILE *stream);" .PP .C "int fgetgrent_r(" .nf .PD 0 .IP .C "FILE *stream," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD .SH DESCRIPTION .CR getgrent() , .CR getgrgid() , and .CR getgrnam() locate an entry in the .CR /etc/group file, and return a pointer to an object of type .CR "struct group" . .PP The .CR group structure is defined in .RC < grp.h > and includes the following members: .nf .IP .C "char *gr_name; /* the name of the group */" .C "char *gr_passwd; /* the encrypted group password */" .C "gid_t gr_gid; /* the numerical group \s-1ID\s+1 */" .C "char **gr_mem; /* null-terminated array of pointers" .C " to member names */" .fi .TP 20 .C getgrent() When first called, .CR getgrent() returns a pointer to the first .CR group structure in the file; thereafter, it returns a pointer to the next .CR group structure in the file. In this way, successive calls can be used to search the entire file. .CR getgrent() opens the .CR /etc/group file prior to doing its work and leaves the file open afterward; .TP .C setgrent() Has the effect of rewinding this file to allow repeated searches; .TP .C endgrent() Can be called to close the file when processing is complete. .TP .C getgrgid() Searches from the beginning of the file until a numeric group ID matching .I gid is found, and returns a pointer to the particular structure in which it was found. .TP .C getgrnam() Searches from the beginning of the file until a group name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .C fgetgrent() Returns a pointer to the next .CR group structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/group . .SS Reentrant Interfaces .CR getgrgid_r() , .CR getgrnam_r() and .CR fgetgrent_r() expect to be passed three extra parameters: .PD 0 .TP 3 1. The address of a .C "struct group" where the result will be stored; .TP 2. A buffer to store character strings, such as the group name, to which fields in the .C "struct group" will point; .TP 3. The length of the user-supplied buffer. .PD .PP In addition to the above three parameters, .CR getgrent_r() requires a pointer to a .I "(FILE *)" variable into which is stored the result of an .I fopen() call on the .CR /etc/group file. This parameter allows threads to independently scan through the .CR /etc/group file. .CR setgrent_r() and .CR endgrent_r() are to be used only in conjunction with .CR getgrent_r() and take the same pointer to a .I "(FILE *)" variable as a parameter. .CR setgrent_r() can be used to rewind or open the .CR /etc/group file. .CR endgrent_r() must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .I "(FILE *)" variable must be initialized to NULL before it is passed to either .CR getgrent_r() or .CR setgrent_r() for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH NETWORKING FEATURES .SS NFS If an entry beginning with a plus sign .RC ( + ) or a minus sign .RC (\| \(mi \|) is found, these routines try to use the Network Information Service network database for data. See .IR group (4) for proper syntax and operation. .SH RETURN VALUE .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .CR group structure. .PP .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , and .CR fgetgrent_r() return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getgrent() , .CR getgrgid() , .CR getgrnam() and .CR fgetgrent() fail if any of the following are true: .RS .TP 12 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX file descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .PD .RE .SH EXAMPLE The following code excerpt counts the number of entries in the .CR /etc/group file: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct group gpbuf; char buffer[1024]; FILE *grf = NULL; setgrent_r(&grf); while (getgrent_r(&gpbuf, buffer, sizeof(buffer), &grf) != -1) count++; endgrent_r(&grf); .ft .ps .fi .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library. This causes them to increase the size of programs that do not otherwise use standard I/O and Network Information Service more than might ordinarily be expected. .PP The value returned by .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() points to a single static area that is overwritten by each call to any of the functions. It must be copied if it is to be saved. .PP .CR getgrent() , .CR getgrgid() , .CR getgrnam() , .CR setgrent() , .CR endgrent() , and .CR fgetgrent() are unsafe in multi-thread applications. .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , .CR setgrent_r() , .CR endgrent_r() , and .CR fgetgrent_r() are MT-Safe and should be used instead. .PP Users of .CR getgrent_r() and .CR getgrnam_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH DEPENDENCIES .SS NFS: .br .B FILES .RS .CI /var/yp/ domainname /group.byname .br .CI /var/yp/ domainname /group.bygid .RE .SM .B SEE ALSO: .RS ypcat(1). .RE .SH FILES .C /etc/group .SH SEE ALSO getgroups(2), getpwent(3C), stdio(3S), group(4). .SH STANDARDS CONFORMANCE .CR getgrent() ": SVID2, SVID3, XPG2" .PP .CR endgrent() ": SVID2, SVID3, XPG2" .PP .CR fgetgrent() ": SVID2, SVID3, XPG2" .PP .CR getgrgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgrnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setgrent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getgrent()\f1 \- get next entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4fgetgrent()\f1 \- get next entry in \f4group()\f1-file-formatted input stream@@@\f3getgrent(3C)\f1 .\" index@\f4getgrgid()\f1 \- get entry from \f4group()\f1 file that matches \f4gid()\fP@@@\f3getgrent(3C)\f1 .\" index@\f4getgrnam()\f1 \- get entry from \f4group()\fP file that matches group name \f4name()\f1@@@\f3getgrent(3C)\f1 .\" index@\f4setgrent()\f1 \- rewind pointer to first entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4endgrent()\f1 \- close currently open \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@get: entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@entry from \f4group()\f1 file, get@@@\f3getgrent(3C)\f1 .\" index@\f4group()\f1 file, get entry from@@@\f3getgrent(3C)\f1 .\" index@file, group: get entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" .\" toc@\f3getgrent(3C)\f1:\0\0\f4getgrent()\f1, \f4getgrgid()\f1, \f4getgrnam()\f1, \f4setgrent()\f1, \f4endgrent()\f1,\n \f4fgetgrent()\f1@@@get group file entry .\" toc@\f4getgrgid()\fP, \f4getgrnam()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4setgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4endgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4fgetgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" .\" links@getgrent.3c getgrent_r.3c .\" links@getgrent.3c getgrgid.3c .\" links@getgrent.3c getgrgid_r.3c .\" links@getgrent.3c getgrnam.3c .\" links@getgrent.3c getgrnam_r.3c .\" links@getgrent.3c setgrent.3c .\" links@getgrent.3c setgrent_r.3c .\" links@getgrent.3c endgrent.3c .\" links@getgrent.3c endgrent_r.3c .\" links@getgrent.3c fgetgrent.3c .\" links@getgrent.3c fgetgrent_r.3c .\" .\" fileset_database@getgrent.3c PROGRAMING-MAN .\" $Header: getgrent.3c,v 76.1 95/07/05 17:29:02 ssa Exp $ .TA g .TH getgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getgrent(\|), getgrent_r(\|), getgrgid(\|), getgrgid_r(\|), getgrnam(\|), getgrnam_r(\|), setgrent(\|), setgrent_r(\|), endgrent(\|), endgrent_r(\|), fgetgrent(\|), fgetgrent_r(\|) \- get group file entry .SH SYNOPSIS .C "#include " .PP .C "struct group *getgrent(void);" .PD 0 .PP .C "int getgrent_r(" .nf .PD 0 .IP .C "struct group *result," .C "char *buffer," .C "int buflen," .C "FILE **grfp);" .PD 0 .PP .C "struct group *getgrgid(gid_t gid);" .PP .C "int getgrgid_r(" .nf .PD 0 .IP .C "gid_t gid," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "struct group *getgrnam(const char *name);" .PP .C "int getgrnam_r(" .nf .PD 0 .IP .C "const char *name," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD 0 .PP .C "void setgrent(void);" .PP .C "void setgrent_r(FILE **grfp);" .PP .C "void endgrent(void);" .PP .C "void endgrent_r(FILE **grfp);" .PP .C "struct group *fgetgrent(FILE *stream);" .PP .C "int fgetgrent_r(" .nf .PD 0 .IP .C "FILE *stream," .C "struct group *result," .C "char *buffer," .C "int buflen);" .PD .SH DESCRIPTION .CR getgrent() , .CR getgrgid() , and .CR getgrnam() locate an entry in the .CR /etc/group file, and return a pointer to an object of type .CR "struct group" . .PP The .CR group structure is defined in .RC < grp.h > and includes the following members: .nf .IP .C "char *gr_name; /* the name of the group */" .C "char *gr_passwd; /* the encrypted group password */" .C "gid_t gr_gid; /* the numerical group \s-1ID\s+1 */" .C "char **gr_mem; /* null-terminated array of pointers" .C " to member names */" .fi .TP 20 .C getgrent() When first called, .CR getgrent() returns a pointer to the first .CR group structure in the file; thereafter, it returns a pointer to the next .CR group structure in the file. In this way, successive calls can be used to search the entire file. .CR getgrent() opens the .CR /etc/group file prior to doing its work and leaves the file open afterward; .TP .C setgrent() Has the effect of rewinding this file to allow repeated searches; .TP .C endgrent() Can be called to close the file when processing is complete. .TP .C getgrgid() Searches from the beginning of the file until a numeric group ID matching .I gid is found, and returns a pointer to the particular structure in which it was found. .TP .C getgrnam() Searches from the beginning of the file until a group name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .C fgetgrent() Returns a pointer to the next .CR group structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/group . .SS Reentrant Interfaces .CR getgrgid_r() , .CR getgrnam_r() and .CR fgetgrent_r() expect to be passed three extra parameters: .PD 0 .TP 3 1. The address of a .C "struct group" where the result will be stored; .TP 2. A buffer to store character strings, such as the group name, to which fields in the .C "struct group" will point; .TP 3. The length of the user-supplied buffer. .PD .PP In addition to the above three parameters, .CR getgrent_r() requires a pointer to a .I "(FILE *)" variable into which is stored the result of an .I fopen() call on the .CR /etc/group file. This parameter allows threads to independently scan through the .CR /etc/group file. .CR setgrent_r() and .CR endgrent_r() are to be used only in conjunction with .CR getgrent_r() and take the same pointer to a .I "(FILE *)" variable as a parameter. .CR setgrent_r() can be used to rewind or open the .CR /etc/group file. .CR endgrent_r() must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .I "(FILE *)" variable must be initialized to NULL before it is passed to either .CR getgrent_r() or .CR setgrent_r() for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH NETWORKING FEATURES .SS NFS If an entry beginning with a plus sign .RC ( + ) or a minus sign .RC (\| \(mi \|) is found, these routines try to use the Network Information Service network database for data. See .IR group (4) for proper syntax and operation. .SH RETURN VALUE .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() return a NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .CR group structure. .PP .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , and .CR fgetgrent_r() return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getgrent() , .CR getgrgid() , .CR getgrnam() and .CR fgetgrent() fail if any of the following are true: .RS .TP 12 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX file descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .PD .RE .SH EXAMPLE The following code excerpt counts the number of entries in the .CR /etc/group file: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct group gpbuf; char buffer[1024]; FILE *grf = NULL; setgrent_r(&grf); while (getgrent_r(&gpbuf, buffer, sizeof(buffer), &grf) != -1) count++; endgrent_r(&grf); .ft .ps .fi .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library. This causes them to increase the size of programs that do not otherwise use standard I/O and Network Information Service more than might ordinarily be expected. .PP The value returned by .CR getgrent() , .CR getgrgid() , .CR getgrnam() , and .CR fgetgrent() points to a single static area that is overwritten by each call to any of the functions. It must be copied if it is to be saved. .PP .CR getgrent() , .CR getgrgid() , .CR getgrnam() , .CR setgrent() , .CR endgrent() , and .CR fgetgrent() are unsafe in multi-thread applications. .CR getgrent_r() , .CR getgrgid_r() , .CR getgrnam_r() , .CR setgrent_r() , .CR endgrent_r() , and .CR fgetgrent_r() are MT-Safe and should be used instead. .PP Users of .CR getgrent_r() and .CR getgrnam_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH DEPENDENCIES .SS NFS: .br .B FILES .RS .CI /var/yp/ domainname /group.byname .br .CI /var/yp/ domainname /group.bygid .RE .SM .B SEE ALSO: .RS ypcat(1). .RE .SH FILES .C /etc/group .SH SEE ALSO getgroups(2), getpwent(3C), stdio(3S), group(4). .SH STANDARDS CONFORMANCE .CR getgrent() ": SVID2, SVID3, XPG2" .PP .CR endgrent() ": SVID2, SVID3, XPG2" .PP .CR fgetgrent() ": SVID2, SVID3, XPG2" .PP .CR getgrgid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getgrnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setgrent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getgrent()\f1 \- get next entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4fgetgrent()\f1 \- get next entry in \f4group()\f1-file-formatted input stream@@@\f3getgrent(3C)\f1 .\" index@\f4getgrgid()\f1 \- get entry from \f4group()\f1 file that matches \f4gid()\fP@@@\f3getgrent(3C)\f1 .\" index@\f4getgrnam()\f1 \- get entry from \f4group()\fP file that matches group name \f4name()\f1@@@\f3getgrent(3C)\f1 .\" index@\f4setgrent()\f1 \- rewind pointer to first entry in \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@\f4endgrent()\f1 \- close currently open \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@get: entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" index@entry from \f4group()\f1 file, get@@@\f3getgrent(3C)\f1 .\" index@\f4group()\f1 file, get entry from@@@\f3getgrent(3C)\f1 .\" index@file, group: get entry from \f4group()\f1 file@@@\f3getgrent(3C)\f1 .\" .\" toc@\f3getgrent(3C)\f1:\0\0\f4getgrent()\f1, \f4getgrgid()\f1, \f4getgrnam()\f1, \f4setgrent()\f1, \f4endgrent()\f1,\n \f4fgetgrent()\f1@@@get group file entry .\" toc@\f4getgrgid()\fP, \f4getgrnam()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4setgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4endgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" toc@\f4fgetgrent()\fP:\0\0get group file entry@@@see \f3getgrent(3C)\f1 .\" .\" links@getgrent.3c getgrent_r.3c .\" links@getgrent.3c getgrgid.3c .\" links@getgrent.3c getgrgid_r.3c .\" links@getgrent.3c getgrnam.3c .\" links@getgrent.3c getgrnam_r.3c .\" links@getgrent.3c setgrent.3c .\" links@getgrent.3c setgrent_r.3c .\" links@getgrent.3c endgrent.3c .\" links@getgrent.3c endgrent_r.3c .\" links@getgrent.3c fgetgrent.3c .\" links@getgrent.3c fgetgrent_r.3c .\" .\" fileset_database@getgrent.3c PROGRAMING-MAN .\" $Header: gethostent.3n,v 78.1 96/03/15 15:56:59 ssa Exp $ .TA g .TH gethostent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gethostent(), gethostent_r(), gethostbyaddr(), gethostbyaddr_r(), gethostbyname(), gethostbyname_r(), sethostent(), sethostent_r(), endhostent(), endhostent_r() \- get network host entry .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .PP .C "extern int h_errno;" .PP .C "struct hostent *gethostent(void);" .PP .C "int gethostent_r(struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyname(const char *name);" .PP .C "int gethostbyname_r(const char *name," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyaddr(const char *addr, .C " int len, .C " int type); .PP .C "_XOPEN_SOURCE_EXTENDED only .C "struct hostent *gethostbyaddr(const void *addr, .C " size_t len, .C " int type); .PP .C "int gethostbyaddr_r(const char *addr," .C " int len," .C " int type," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "int sethostent(int stayopen);" .PP .C "int sethostent_r(int stayopen, struct hostent_data *buffer);" .PP .C "int endhostent(void);" .PP .C "int endhostent_r(struct hostent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only .C "void sethostent(int stayopen);" .C "void endhostent(void);" .fi .SH DESCRIPTION The .CR gethostent() , .CR gethostbyname() , and .CR gethostbyaddr() functions each return a pointer to a structure of type .CR hostent , defined as follows in .CR : .nf .IP .C "struct hostent {" .C " char *h_name;" .C " char **h_aliases;" .C " int h_addrtype;" .C " int h_length;" .C " char **h_addr_list;" .C "};" .IP .C "#define h_addr h_addr_list[0]" .fi .PP The members of this structure are: .RS .TP 20 .CR h_name The official name of the host. .TP .CR h_aliases A null-terminated array of alternate names for the host. .TP .CR h_addrtype The type of address being returned; always .CR AF_INET . .TP .CR h_length The length, in bytes, of the address. .TP .CR h_addr_list A null-terminated array of network addresses for the host. .TP .CR h_addr The first address in .CR h_addr_list ; this is for compatibility with previous HP-UX implementations where a .CR "struct hostent" contains only one network address per host. .RE .SS Reentrant Interfaces .CR gethostent_r() , .CR gethostbyname_r() , and .CR gethostbyaddr_r() expect to be passed the address of a .CR "struct hostent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct hostent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct hostent" will point, as well as state information such as open file descriptors. The .CR "struct hostent_data" is defined in the header file .CR . .PP .CR sethostent_r() and .CR endhostent_r() are to be used only in conjunction with .CR gethostent_r() and take the same pointer to a .CR "struct hostent_data" as a parameter. If the Network Information Service is being used, .CR sethostent_r() initializes an internal database key. If the .CR /etc/hosts file is being used, .CR sethostent_r() opens or rewinds the file. If the .CR named name server (see .IR named (1M)) is being used, then .CR sethostent_r() has no effect. .CR endhostent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR sethostent_r() currently has no effect. However, .CR sethostent() can still be used to keep the .CR /etc/hosts file open, or to use connected stream sockets to the name server, when making calls to .CR gethostbyaddr_r() and .CR gethostbyname_r() . .PP The .I hostf field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to either .CR gethostent_r() or .CR sethostent_r() for the first time. The .I current field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to .CR gethostbyname_r() or .CR gethostbyaddr_r() for the first time. Thereafter, these fields should not be modified in any way. These are the only .CR hostent_data fields that should ever be explicitly accessed. .SS Name Service Switch-Based Operation These host entry library routines internally call the name service switch to access the "hosts" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve host names and Internet addresses. The operations of the three name services: Domain Name Server, NIS, and nonserver mode (e.g., files) are listed below. .SS Domain Name Server Operation If the local system is configured to use the .CR named name server (see .IR named(1M) and .IR resolver(4)) for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Always returns a NULL pointer. .TP .CR sethostent() , Requests the use of a connected stream socket for queries to the name server if the .I stayopen flag is non-zero. The connection is retained after each call to .CR gethostbyname() or .CR gethostbyaddr() . .TP .CR endhostent() Closes the stream socket connection. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the name server. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS NIS Server Operation If .CR ypserv, the server for the Network Information Service (see .IR ypserv (1M)), is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Returns the next entry in the NIS database. .TP .CR sethostent() Initializes an internal key for the NIS database. If the .I stayopen flag is non-zero, the internal key is not cleared after calls to .CR endhostent() . .TP .CR endhostent() Clears the internal NIS database key. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the NIS database. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS Nonserver Operation If the .CR /etc/hosts file is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Reads the next line of .CR /etc/hosts , opening the file if necessary. .TP .CR sethostent() opens and rewinds the file. If the .I stayopen flag is non-zero, the host data base is not closed after each call to .CR gethostent() (either directly or indirectly through one of the other .CR gethost calls). .TP .CR endhostent() Closes the file. .TP .CR gethostbyname() Sequentially searches from the beginning of the file until a host name (among either the official names or the aliases) matching its .I name parameter is found, or until EOF is encountered. Names are matched without respect to uppercase or lowercase, as described above in the name server case. .TP .CR gethostbyaddr() Sequentially searches from the beginning of the file until an Internet address matching its .I addr parameter is found, or until EOF is encountered. .RE .SS Arguments Currently, only the Internet address format is understood. In calls to .CR gethostbyaddr() , the parameter .I addr must be a pointer to an .IR in_addr structure, an Internet address in network order (see .IR byteorder (3N)) and the header file .CR ). The parameter .I len must be the number of bytes in an Internet address; that is, .CR "sizeof (struct in_addr)" . The parameter .I type must be the constant .CR AF_INET . .SH RETURN VALUE If successful, .CR gethostbyname() , .CR gethostbyaddr() , and .CR gethostent() return a pointer to the requested .CR hostent structure. .PP .CR gethostbyname() and .CR gethostbyaddr() return NULL if their .I host or .I addr parameters, respectively, cannot be found in the database. If .CR /etc/hosts is being used, they also return NULL if they are unable to open .CR /etc/hosts . .PP .CR gethostbyaddr() also returns NULL if either its .I addr or .I len parameter is invalid. .PP .CR gethostent() always returns NULL if the name server is being used. .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 is returned if the operation is unsuccessful or, in the case of .CR gethostent_r() , if the end of the hosts list has been reached. .CR 0 is returned otherwise. .SH ERRORS If the name server is being used and .CR gethostbyname() or .CR gethostbyaddr() returns a NULL pointer, the external integer .CR h_errno contains one of the following values: .RS .TP 23 .CR HOST_NOT_FOUND No such host is known. .TP .CR TRY_AGAIN This is usually a temporary error. The local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .CR NO_RECOVERY This is a non-recoverable error. .TP .CR NO_ADDRESS The requested name is valid but does not have an IP address; this is not a temporary error. This means another type of request to the name server will result in an answer. .RE .PP If the name server is not being used, the value of .CR h_errno may not be meaningful. .SH EXAMPLES The following code excerpt counts the number of host entries: .RS .nf .PP .C "int count = 0; .C "struct hostent htbuf; .C "struct hostent_data hdbuf; .PP .C "hdbuf.hostf = NULL; .C "(void) sethostent_r(0, &hdbuf); .C "while (gethostent_r(&htbuf, &hdbuf) != -1) .C " count++; .C "(void) endhostent_r(&hdbuf); .fi .RE .SH WARNINGS For the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR gethostent() , .CR gethostbyaddr() , .CR gethostbyname() , .CR sethostent() , and .CR endhostent() are unsafe in multi-thread applications. .CR gethostent_r() , .CR gethostbyaddr_r() , .CR gethostbyname_r() , .CR sethostent_r() , and .CR endhostent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR gethostent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/hosts .SH SEE ALSO named(1M), ypserv(1M), resolver(3N), ypclnt(3C), hosts(4), switch(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR gethostent() ": XPG4" .\" .\" index@\f1end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1entry, get, set, or end network host@@@\f3gethostent(3N)\f1 .\" index@\f1get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1host entry, get, set, or end network@@@\f3gethostent(3N)\f1 .\" index@\f1network host entry, get, set, or end@@@\f3gethostent(3N)\f1 .\" index@\f1set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1thread-safe, get, set, or end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent()\f1 \- end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent_r()\f1 \- end network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent()\f1 \- set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent_r()\f1 \- set network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" .\" links@gethostent.3n endhostent.3n .\" links@gethostent.3n endhostent_.3n .\" links@gethostent.3n gethostbyad.3n .\" links@gethostent.3n gethostbyna.3n .\" links@gethostent.3n gethostent_.3n .\" links@gethostent.3n sethostent.3n .\" links@gethostent.3n sethostent_.3n .\" .\" toc@\f3gethostent(3N)\f1:\0\0\f4endhostent()\f1, \f4endhostent_r()\f1, \f4gethostbyaddr()\f1, \f4gethostbyaddr_r()\f1,\n\f4gethostbyname()\f1, \f4gethostbyname_r()\f1, \f4gethostent()\f1, \f4gethostent_r()\f1,\n\f4sethostent()\f1, \f4sethostent_r()\f1@@@get, set, or end network host entry .\" .\" toc@\f4endhostent()\f1:\0\0end network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4endhostent_r()\f1:\0\0end network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostent_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent()\f1:\0\0set network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent_r()\f1:\0\0set network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" $Header: gethostent.3n,v 78.1 96/03/15 15:56:59 ssa Exp $ .TA g .TH gethostent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME gethostent(), gethostent_r(), gethostbyaddr(), gethostbyaddr_r(), gethostbyname(), gethostbyname_r(), sethostent(), sethostent_r(), endhostent(), endhostent_r() \- get network host entry .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .PP .C "extern int h_errno;" .PP .C "struct hostent *gethostent(void);" .PP .C "int gethostent_r(struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyname(const char *name);" .PP .C "int gethostbyname_r(const char *name," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "struct hostent *gethostbyaddr(const char *addr, .C " int len, .C " int type); .PP .C "_XOPEN_SOURCE_EXTENDED only .C "struct hostent *gethostbyaddr(const void *addr, .C " size_t len, .C " int type); .PP .C "int gethostbyaddr_r(const char *addr," .C " int len," .C " int type," .C " struct hostent *result," .C " struct hostent_data *buffer);" .PP .C "int sethostent(int stayopen);" .PP .C "int sethostent_r(int stayopen, struct hostent_data *buffer);" .PP .C "int endhostent(void);" .PP .C "int endhostent_r(struct hostent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only .C "void sethostent(int stayopen);" .C "void endhostent(void);" .fi .SH DESCRIPTION The .CR gethostent() , .CR gethostbyname() , and .CR gethostbyaddr() functions each return a pointer to a structure of type .CR hostent , defined as follows in .CR : .nf .IP .C "struct hostent {" .C " char *h_name;" .C " char **h_aliases;" .C " int h_addrtype;" .C " int h_length;" .C " char **h_addr_list;" .C "};" .IP .C "#define h_addr h_addr_list[0]" .fi .PP The members of this structure are: .RS .TP 20 .CR h_name The official name of the host. .TP .CR h_aliases A null-terminated array of alternate names for the host. .TP .CR h_addrtype The type of address being returned; always .CR AF_INET . .TP .CR h_length The length, in bytes, of the address. .TP .CR h_addr_list A null-terminated array of network addresses for the host. .TP .CR h_addr The first address in .CR h_addr_list ; this is for compatibility with previous HP-UX implementations where a .CR "struct hostent" contains only one network address per host. .RE .SS Reentrant Interfaces .CR gethostent_r() , .CR gethostbyname_r() , and .CR gethostbyaddr_r() expect to be passed the address of a .CR "struct hostent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct hostent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct hostent" will point, as well as state information such as open file descriptors. The .CR "struct hostent_data" is defined in the header file .CR . .PP .CR sethostent_r() and .CR endhostent_r() are to be used only in conjunction with .CR gethostent_r() and take the same pointer to a .CR "struct hostent_data" as a parameter. If the Network Information Service is being used, .CR sethostent_r() initializes an internal database key. If the .CR /etc/hosts file is being used, .CR sethostent_r() opens or rewinds the file. If the .CR named name server (see .IR named (1M)) is being used, then .CR sethostent_r() has no effect. .CR endhostent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR sethostent_r() currently has no effect. However, .CR sethostent() can still be used to keep the .CR /etc/hosts file open, or to use connected stream sockets to the name server, when making calls to .CR gethostbyaddr_r() and .CR gethostbyname_r() . .PP The .I hostf field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to either .CR gethostent_r() or .CR sethostent_r() for the first time. The .I current field in the .CR "struct hostent_data" must be initialized to NULL before it is passed to .CR gethostbyname_r() or .CR gethostbyaddr_r() for the first time. Thereafter, these fields should not be modified in any way. These are the only .CR hostent_data fields that should ever be explicitly accessed. .SS Name Service Switch-Based Operation These host entry library routines internally call the name service switch to access the "hosts" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve host names and Internet addresses. The operations of the three name services: Domain Name Server, NIS, and nonserver mode (e.g., files) are listed below. .SS Domain Name Server Operation If the local system is configured to use the .CR named name server (see .IR named(1M) and .IR resolver(4)) for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Always returns a NULL pointer. .TP .CR sethostent() , Requests the use of a connected stream socket for queries to the name server if the .I stayopen flag is non-zero. The connection is retained after each call to .CR gethostbyname() or .CR gethostbyaddr() . .TP .CR endhostent() Closes the stream socket connection. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the name server. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS NIS Server Operation If .CR ypserv, the server for the Network Information Service (see .IR ypserv (1M)), is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Returns the next entry in the NIS database. .TP .CR sethostent() Initializes an internal key for the NIS database. If the .I stayopen flag is non-zero, the internal key is not cleared after calls to .CR endhostent() . .TP .CR endhostent() Clears the internal NIS database key. .TP .PD 0 .CR gethostbyname() .TP .CR gethostbyaddr() Each retrieves host information from the NIS database. Names are matched without respect to uppercase or lowercase. For example, .CR berkeley.edu , .CR Berkeley.EDU , and .CR BERKELEY.EDU all match the entry for .CR berkeley.edu . .PD .RE .SS Nonserver Operation If the .CR /etc/hosts file is used for name or address resolution, then the function: .RS .TP 23 .CR gethostent() Reads the next line of .CR /etc/hosts , opening the file if necessary. .TP .CR sethostent() opens and rewinds the file. If the .I stayopen flag is non-zero, the host data base is not closed after each call to .CR gethostent() (either directly or indirectly through one of the other .CR gethost calls). .TP .CR endhostent() Closes the file. .TP .CR gethostbyname() Sequentially searches from the beginning of the file until a host name (among either the official names or the aliases) matching its .I name parameter is found, or until EOF is encountered. Names are matched without respect to uppercase or lowercase, as described above in the name server case. .TP .CR gethostbyaddr() Sequentially searches from the beginning of the file until an Internet address matching its .I addr parameter is found, or until EOF is encountered. .RE .SS Arguments Currently, only the Internet address format is understood. In calls to .CR gethostbyaddr() , the parameter .I addr must be a pointer to an .IR in_addr structure, an Internet address in network order (see .IR byteorder (3N)) and the header file .CR ). The parameter .I len must be the number of bytes in an Internet address; that is, .CR "sizeof (struct in_addr)" . The parameter .I type must be the constant .CR AF_INET . .SH RETURN VALUE If successful, .CR gethostbyname() , .CR gethostbyaddr() , and .CR gethostent() return a pointer to the requested .CR hostent structure. .PP .CR gethostbyname() and .CR gethostbyaddr() return NULL if their .I host or .I addr parameters, respectively, cannot be found in the database. If .CR /etc/hosts is being used, they also return NULL if they are unable to open .CR /etc/hosts . .PP .CR gethostbyaddr() also returns NULL if either its .I addr or .I len parameter is invalid. .PP .CR gethostent() always returns NULL if the name server is being used. .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 is returned if the operation is unsuccessful or, in the case of .CR gethostent_r() , if the end of the hosts list has been reached. .CR 0 is returned otherwise. .SH ERRORS If the name server is being used and .CR gethostbyname() or .CR gethostbyaddr() returns a NULL pointer, the external integer .CR h_errno contains one of the following values: .RS .TP 23 .CR HOST_NOT_FOUND No such host is known. .TP .CR TRY_AGAIN This is usually a temporary error. The local server did not receive a response from an authoritative server. A retry at some later time may succeed. .TP .CR NO_RECOVERY This is a non-recoverable error. .TP .CR NO_ADDRESS The requested name is valid but does not have an IP address; this is not a temporary error. This means another type of request to the name server will result in an answer. .RE .PP If the name server is not being used, the value of .CR h_errno may not be meaningful. .SH EXAMPLES The following code excerpt counts the number of host entries: .RS .nf .PP .C "int count = 0; .C "struct hostent htbuf; .C "struct hostent_data hdbuf; .PP .C "hdbuf.hostf = NULL; .C "(void) sethostent_r(0, &hdbuf); .C "while (gethostent_r(&htbuf, &hdbuf) != -1) .C " count++; .C "(void) endhostent_r(&hdbuf); .fi .RE .SH WARNINGS For the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR gethostent() , .CR gethostbyaddr() , .CR gethostbyname() , .CR sethostent() , and .CR endhostent() are unsafe in multi-thread applications. .CR gethostent_r() , .CR gethostbyaddr_r() , .CR gethostbyname_r() , .CR sethostent_r() , and .CR endhostent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR gethostent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/hosts .SH SEE ALSO named(1M), ypserv(1M), resolver(3N), ypclnt(3C), hosts(4), switch(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR gethostent() ": XPG4" .\" .\" index@\f1end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1entry, get, set, or end network host@@@\f3gethostent(3N)\f1 .\" index@\f1get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1host entry, get, set, or end network@@@\f3gethostent(3N)\f1 .\" index@\f1network host entry, get, set, or end@@@\f3gethostent(3N)\f1 .\" index@\f1set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f1thread-safe, get, set, or end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent()\f1 \- end network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4endhostent_r()\f1 \- end network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyaddr_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostbyname_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent()\f1 \- get network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4gethostent_r()\f1 \- get network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent()\f1 \- set network host entry@@@\f3gethostent(3N)\f1 .\" index@\f4sethostent_r()\f1 \- set network host entry (thread-safe)@@@\f3gethostent(3N)\f1 .\" .\" links@gethostent.3n endhostent.3n .\" links@gethostent.3n endhostent_.3n .\" links@gethostent.3n gethostbyad.3n .\" links@gethostent.3n gethostbyna.3n .\" links@gethostent.3n gethostent_.3n .\" links@gethostent.3n sethostent.3n .\" links@gethostent.3n sethostent_.3n .\" .\" toc@\f3gethostent(3N)\f1:\0\0\f4endhostent()\f1, \f4endhostent_r()\f1, \f4gethostbyaddr()\f1, \f4gethostbyaddr_r()\f1,\n\f4gethostbyname()\f1, \f4gethostbyname_r()\f1, \f4gethostent()\f1, \f4gethostent_r()\f1,\n\f4sethostent()\f1, \f4sethostent_r()\f1@@@get, set, or end network host entry .\" .\" toc@\f4endhostent()\f1:\0\0end network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4endhostent_r()\f1:\0\0end network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyaddr_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname()\f1:\0\0get network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostbyname_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4gethostent_r()\f1:\0\0get network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent()\f1:\0\0set network host entry@@@see \f3gethostent(3N)\f1 .\" toc@\f4sethostent_r()\f1:\0\0set network host entry (thread-safe)@@@see \f3gethostent(3N)\f1 .\" $Header: setjmp.3c,v 72.5 94/11/15 09:56:14 ssa Exp $ .TA s .TH setjmp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setjmp(\|), longjmp(\|), sigsetjmp(\|), siglongjmp(\|) \- non-local goto .SH SYNOPSIS .C "#include " .PP .C "int setjmp(jmp_buf env);" .PP .C "void longjmp(jmp_buf env, int val);" .PP .C "int _setjmp(jmp_buf env);" .PP .C "void _longjmp(jmp_buf env, int val);" .PP .C "int sigsetjmp(sigjmp_buf env, int savemask);" .PP .C "void siglongjmp(sigjmp_buf env, int val);" .SH DESCRIPTION .C setjmp() and .C longjmp() are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. They exist in three variant forms: .CR setjmp() and .CR longjmp() ; .CR _setjmp() and .CR _longjmp() ; .CR sigsetjmp() and .CR siglongjmp() . Unless indicated otherwise, references to .C setjmp() and .C longjmp() apply to all three versions. .RS .TP 18 .C setjmp() saves its stack environment in .I env (whose type, .CR jmp_buf , is defined in the .RC < setjmp.h > header file) for later use by .CR longjmp() . It returns the value .CR 0 . .TP .C longjmp() restores the environment saved by the last call of .C setjmp() with the corresponding .I env argument. After .C longjmp() is completed, program execution continues as if the corresponding call of .C setjmp() (which must not itself have returned in the interim) had just returned the value .IR val . .C longjmp() cannot cause .C setjmp() to return the value .CR 0 . If .C longjmp() is invoked with a second argument of .CR 0 , .C setjmp() returns .CR 1 . All accessible data values are valid as of the time .C longjmp() is called. .RE .PP Upon the return from a .C setjmp() call caused by a .CR longjmp() , the values of any non-static local variables belonging to the routine from which .C setjmp() was called are undefined. Code which depends on such values is not guaranteed to be portable. .SS Variant Forms The following functions behave the same as .C setjmp() and .C longjmp() except in the handling of the process' signal mask (see .IR sigaction (2) and .IR sigvector (2)). This distinction is only significant for programs which use .CR sigaction() , .CR sigprocmask() , .CR sigvector() , .CR sigblock() , and/or .CR sigsetmask() . .RS .TP 18 .C setjmp() .PD 0 .TP .C longjmp() These always save and restore the signal mask. .PD .TP .C _setjmp() .PD 0 .TP .C _longjmp() These never manipulate the signal mask. .PD .TP .C sigsetjmp() Saves the signal mask if and only if .I savemask is non-zero. .TP .C siglongjmp() Restores the signal mask if and only if it is saved by .CR sigsetjmp() . .SS Programming Considerations If a .C longjmp() is executed and the environment in which the .C setjmp() is executed no longer exists, errors can occur. The conditions under which the environment of the .C setjmp() no longer exists include exiting the procedure that contains the .C setjmp() call, and exiting an inner block with temporary storage (such as a block with declarations in C or a .C with statement in Pascal). This condition might not be detectable, in which case the .C longjmp() occurs and, if the environment no longer exists, the contents of the temporary storage of an inner block are unpredictable. This condition might also cause unexpected process termination. If the procedure has been exited the results are unpredictable. .PP Passing .C longjmp() a pointer to a buffer not created by .CR setjmp() , passing .C _longjmp() a pointer to a buffer not created by either .C setjmp() or .CR _setjmp() , passing .C siglongjmp() a pointer to a buffer not created by .C sigsetjmp() or passing any of these three functions a buffer that has been modified by the user, can cause all the problems listed above, and more. .PP Some implementations of Pascal support a ``try/recover'' mechanism, which also creates stack marker information. If a .C longjmp() operation occurs in a scope which is nested inside a try/recover, and the corresponding .C setjmp() is not inside the scope of the try/recover, the recover block will not be executed and the currently active recover block will become the one enclosing the .CR setjmp() , if one exists. .SH WARNINGS A call to .C longjmp() to leave the guaranteed stack space reserved by .C sigspace() might remove the guarantee that the ordinary execution of the program will not extend into the guaranteed space. It might also cause the program to forever lose its ability to automatically increase the stack size, and the program might then be limited to the guaranteed space. .PP The result of using .C setjmp() within an expression can be unpredictable. .PP If .C longjmp() is called even though .I env was never primed by a call to .CR setjmp() , or when the last such call was in a function that has since returned, total chaos is guaranteed. .SH AUTHOR .C setjmp() was developed by AT&T and HP. .SH SEE ALSO sigaction(2), sigblock(2), signal(5), sigprocmask(2), sigsetmask(2), sigspace(2), sigsuspend(2), sigvector(2). .SH STANDARDS CONFORMANCE .CR setjmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR longjmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR siglongjmp() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigsetjmp() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4_setjmp()\fP \- save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4_longjmp()\fP \- restore stack environment after non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4sigsetjmp()\fP \- save signal mask if savemask is non-zero@@@\f3setjmp(3C)\f1 .\" index@\f4setjmp()\fP \- save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4longjmp()\fP \- restore stack environment after non-local goto@@@\f3setjmp(3C)\f1 .\" index@save/restore stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@restore/save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@non-local goto, save/restore stack environment for@@@\f3setjmp(3C)\f1 .\" index@goto, save/restore stack environment for non-local@@@\f3setjmp(3C)\f1 .\" index@stack environment, save/restore for non-local goto@@@\f3setjmp(3C)\f1 .\" index@environment, save/restore stack for non-local goto@@@\f3setjmp(3C)\f1 .\" .\" toc@\f3setjmp(3S)\f1:\0\0\f4setjmp()\fP, \f4longjmp()\fP@@@save/restore stack environment for non-local goto .\" toc@\f4longjmp()\fP:\0\0restore stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" toc@\f4sigsetjmp()\fP:\0\0save signal mask if savemask is non-zero@@@see \f3setjmp(3C)\f1 .\" toc@\f4_longjmp()\fP:\0\0restore stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" toc@\f4_setjmp()\fP:\0\0save stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" .\" links@setjmp.3c longjmp.3c .\" links@setjmp.3c sigsetjmp.3c .\" links@setjmp.3c siglongjmp.3c .\" links@setjmp.3c _longjmp.3c .\" links@setjmp.3c _setjmp.3c .\" .\" fileset_database@setjmp.3c PROGRAMING-MAN .\" $Header: crypt.3c,v 72.5 94/11/14 13:14:01 ssa Exp $ .TA c .TH crypt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crypt, crypt_r, setkey, setkey_r, encrypt, encrypt_r \- generate hashing encryption .SH SYNOPSIS .nf .C "#include " .C "#include " .fi .PP .C "char *crypt(const char *key, const char *salt);" .PP .C "char *crypt_r(const char *key, const char *salt, CRYPTD *cd);" .PP .C "void setkey(const char *key);" .PP .C "void setkey_r(const char *key, CRYPTD *cd);" .PP .C "void encrypt(char block[64], int edflag);" .PP .C "void encrypt_r(char block[64], int edflag, CRYPTD *cd);" .SH DESCRIPTION .SS crypt(\|): .C crypt() is the password encryption function. It is based on a one way hashing encryption algorithm with variations intended (among other things) to frustrate use of hardware implementations of a key search. .PP .I key is a user's typed password. .I salt is a two-character string chosen from the set .CR [a-zA-Z0-9./] ; this string is used to perturb the hashing algorithm in one of 4096 different ways, after which the password is used as the key to encrypt repeatedly a constant string. The returned value points to the encrypted password. The first two characters are the salt itself. .SS setkey(\|) and encrypt(\|): .C setkey() and .C encrypt() provide (rather primitive) access to the actual hashing algorithm. The argument to .C setkey() is a character array of length 64 containing only the characters with numerical value 0 and 1. If this string is divided into groups of 8, the low-order bit in each group is ignored; this gives a 56-bit key which is set into the machine. This is the key that is used with the hashing algorithm to encrypt or decrypt the string .I block with the function .CR encrypt() . .PP The .I block argument to .C encrypt() is a character array of length 64 containing only the characters with numerical value 0 and 1. The argument array is modified in place to a similar array representing the bits of the argument after having been subjected to the hashing algorithm using the key that was set by .CR setkey() . If .I edflag is zero, the argument is encrypted; if non-zero it is decrypted. .SS Reentrant Interfaces .I cd is a pointer to a CRYPTD object, which is defined in .RC < crypt.h >. .PP For .C crypt_r(), .I cd is used as a buffer to store the result string. .PP In the case of .C setkey_r() and .C encrypt_r(), .I cd is used to hold key information set by the .C setkey_r() call, and used by the .C encrypt_r() call. .SH SEE ALSO crypt(1), login(1), passwd(1), getpass(3C), passwd(4). .SH WARNINGS The return value for .C crypt() points to static data whose content is overwritten by each call. .CR crypt() , .CR setkey() , and .CR encrypt() are unsafe in multi-thread applications. .CR crypt_r() , .CR setkey_r() , and .C encrypt_r() are MT-Safe and should be used instead. .SH STANDARDS CONFORMANCE .CR crypt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR encrypt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR setkey() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4crypt()\f1, \f4setkey()\f1, \f4setkey_r()\f1, \f4encrypt_r()\f1, \f4encrypt()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4setkey()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4setkey_r()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4encrypt()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4encrypt_r()\f1 \- generate hashing encyption@@@\f3crypt(3C)\f1 .\" index@generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@hashing encryption, generate@@@\f3crypt(3C)\f1 .\" index@encryption, hashing, generate@@@\f3crypt(3C)\f1 .\" index@encryption, password@@@\f3crypt(3C)\f1 .\" index@password encryption function@@@\f3crypt(3C)\f1 .\" .\" toc@\f3crypt(3C)\f1:\0\0\f4crypt()\f1, \f4setkey()\f1, \f4setkey_r()\f1, \f4encrypt()\f1, \f4encrypt_r()\f1@@@generate hashing encryption .\" toc@\f4setkey()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4setkey_r()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4encrypt()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4encrypt_r()\f1:\0\0gerneate hashing encryption@@@see \f3crypt(3C)\f1 .\" .\" links@crypt.3c crypt_r.3c .\" links@crypt.3c setkey.3c .\" links@crypt.3c setkey_r.3c .\" links@crypt.3c encrypt.3c .\" links@crypt.3c encrypt_r.3c .\" .\" fileset_database@crypt.3c PROGRAMING-MAN .\" $Header: crypt.3c,v 72.5 94/11/14 13:14:01 ssa Exp $ .TA c .TH crypt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME crypt, crypt_r, setkey, setkey_r, encrypt, encrypt_r \- generate hashing encryption .SH SYNOPSIS .nf .C "#include " .C "#include " .fi .PP .C "char *crypt(const char *key, const char *salt);" .PP .C "char *crypt_r(const char *key, const char *salt, CRYPTD *cd);" .PP .C "void setkey(const char *key);" .PP .C "void setkey_r(const char *key, CRYPTD *cd);" .PP .C "void encrypt(char block[64], int edflag);" .PP .C "void encrypt_r(char block[64], int edflag, CRYPTD *cd);" .SH DESCRIPTION .SS crypt(\|): .C crypt() is the password encryption function. It is based on a one way hashing encryption algorithm with variations intended (among other things) to frustrate use of hardware implementations of a key search. .PP .I key is a user's typed password. .I salt is a two-character string chosen from the set .CR [a-zA-Z0-9./] ; this string is used to perturb the hashing algorithm in one of 4096 different ways, after which the password is used as the key to encrypt repeatedly a constant string. The returned value points to the encrypted password. The first two characters are the salt itself. .SS setkey(\|) and encrypt(\|): .C setkey() and .C encrypt() provide (rather primitive) access to the actual hashing algorithm. The argument to .C setkey() is a character array of length 64 containing only the characters with numerical value 0 and 1. If this string is divided into groups of 8, the low-order bit in each group is ignored; this gives a 56-bit key which is set into the machine. This is the key that is used with the hashing algorithm to encrypt or decrypt the string .I block with the function .CR encrypt() . .PP The .I block argument to .C encrypt() is a character array of length 64 containing only the characters with numerical value 0 and 1. The argument array is modified in place to a similar array representing the bits of the argument after having been subjected to the hashing algorithm using the key that was set by .CR setkey() . If .I edflag is zero, the argument is encrypted; if non-zero it is decrypted. .SS Reentrant Interfaces .I cd is a pointer to a CRYPTD object, which is defined in .RC < crypt.h >. .PP For .C crypt_r(), .I cd is used as a buffer to store the result string. .PP In the case of .C setkey_r() and .C encrypt_r(), .I cd is used to hold key information set by the .C setkey_r() call, and used by the .C encrypt_r() call. .SH SEE ALSO crypt(1), login(1), passwd(1), getpass(3C), passwd(4). .SH WARNINGS The return value for .C crypt() points to static data whose content is overwritten by each call. .CR crypt() , .CR setkey() , and .CR encrypt() are unsafe in multi-thread applications. .CR crypt_r() , .CR setkey_r() , and .C encrypt_r() are MT-Safe and should be used instead. .SH STANDARDS CONFORMANCE .CR crypt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR encrypt() ": SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR setkey() ": SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4crypt()\f1, \f4setkey()\f1, \f4setkey_r()\f1, \f4encrypt_r()\f1, \f4encrypt()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4setkey()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4setkey_r()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4encrypt()\f1 \- generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@\f4encrypt_r()\f1 \- generate hashing encyption@@@\f3crypt(3C)\f1 .\" index@generate hashing encryption@@@\f3crypt(3C)\f1 .\" index@hashing encryption, generate@@@\f3crypt(3C)\f1 .\" index@encryption, hashing, generate@@@\f3crypt(3C)\f1 .\" index@encryption, password@@@\f3crypt(3C)\f1 .\" index@password encryption function@@@\f3crypt(3C)\f1 .\" .\" toc@\f3crypt(3C)\f1:\0\0\f4crypt()\f1, \f4setkey()\f1, \f4setkey_r()\f1, \f4encrypt()\f1, \f4encrypt_r()\f1@@@generate hashing encryption .\" toc@\f4setkey()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4setkey_r()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4encrypt()\f1:\0\0generate hashing encryption@@@see \f3crypt(3C)\f1 .\" toc@\f4encrypt_r()\f1:\0\0gerneate hashing encryption@@@see \f3crypt(3C)\f1 .\" .\" links@crypt.3c crypt_r.3c .\" links@crypt.3c setkey.3c .\" links@crypt.3c setkey_r.3c .\" links@crypt.3c encrypt.3c .\" links@crypt.3c encrypt_r.3c .\" .\" fileset_database@crypt.3c PROGRAMING-MAN .\" $Header: setlabel.3c,v 72.2 94/07/22 16:11:02 ssa Exp $ .TA s .TH setlabel 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setlabel() \- define label for formatting routines .SH SYNOPSIS .C "#include " .PP .C "int setlabel(const char *label);" .SH DESCRIPTION The .CR setlabel() system call defines a label to be printed by formatting routines (see .IR pfmt (3C) and .IR vpfmt (3C)) in the standard message format. .IR label is a character string limited to 25 characters in length. .PP If .IR label is NULL or an empty string, the label is reset to no label. No label is defined before .CR setlabel() . .PP .CR setlabel() assumes that .IR label has already been translated into a locale-specific string using the current locale. .SH RETURN VALUE .CR setlabel() returns zero upon successful completion or nonzero if the routine failed. .SH EXAMPLES This example, with no label defined: .IP .C pfmt(stderr, MM_INFO,"my_appl_cat:1:file is writable"); .PP generates: .IP .C INFO: file is writable .PP Using .CR setlabel() : .nf .IP .C setlabel("my_appl"); .C pfmt(stderr, MM_INFO,"my_appl_cat:1:file is writable"); .fi .PP generates: .IP .C my_appl: INFO: file is writable .SH SEE ALSO pfmt(3C), vpfmt(3C). .SH STANDARDS COMPLIANCE .CR setlabel() ": SVID3" .\" .\" toc@\f3setlabel(3)\f1:\0\0\f4setlabel()\f1@@@define label for formatting routines\f1 .\" .\" index@\f4setlabel()\f1 \- define label for formatting routines@@@\f3setlabel(3)\f1 .\" index@\f1define label for formatting routines@@@\f3setlabel(3)\f1 .\" index@\f1label, define for formatting routines@@@\f3setlabel(3)\f1 .\" index@\f1formatting routines, define label for@@@\f3setlabel(3)\f1 .\" index@\f1routines, define label for formatting@@@\f3setlabel(3)\f1 .\" $Header: setlocale.3c,v 72.8 94/11/30 10:15:48 ssa Exp $ .TA s .TH setlocale 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setlocale(\|), setlocale_r(\|), getlocale(\|), getlocale_r(\|) \- set and get the locale of a program .SH SYNOPSIS .CR "#include " .PP .CR "char *setlocale(int category, const char *locale);" .PP .CR "int setlocale_r(int category, const char *locale, char *buffer," .PD 0 .IP .CR " int buflen);" .PD .PP .CR "struct locale_data *getlocale(int type);" .PP .CR "int getlocale_r(int type, struct locale_data *ld);" .SH DESCRIPTION The .CR setlocale() function sets, queries, or restores the aspect of a program's locale that is specified by the .I category argument. A program's locale refers to those areas of the program's Native Language Support (NLS) environment for which the following values of .I category have been defined: .RS .TP 20 .C LC_ALL Affects behavior of all categories below, as well as all .IR nl_langinfo (3C) items. .TP .C LC_COLLATE Affects behavior of regular expressions and the NLS string collation functions (see .IR strcoll (3C), .IR strfxrm (3C), .IR wcscoll (3C), .IR wcsxfrm (3C), and .IR regexp (5)). .TP .C LC_CTYPE Affects behavior of regular expressions, character classification, and conversion functions (see .IR ctype (3C), .IR wctype (3X), .IR wconv (3X), .IR conv (3C), and .IR regexp (5)). The .CR LC_CTYPE category also affects the behavior of all routines that process multibyte characters (see .IR multibyte (3C)). .TP .C LC_MESSAGES Affects the language in which messages are displayed and the processing of affirmative and negative responses (see .IR catopen (3C) and .IR nl_langinfo (3C)). .TP .C LC_MONETARY Affects behavior of functions that handle monetary values (see .IR localeconv (3C) and .IR strfmon (3C)). .TP .C LC_NUMERIC Affects handling of the radix character in the formatted input/output functions (see .IR printf (3C), .IR scanf (3C), and .IR vprintf (3C)) and the string conversion functions (see .IR ecvt (3C) and .IR strtod (3C)). .CR LC_NUMERIC also affects the numeric values found in the .I localeconv structure. .TP .C LC_TIME Affects the behavior of time conversion functions (see .IR getdate (3C), .IR strftime (3C), and .IR strptime (3C)). .RE .PP All .IR nl_langinfo (3C) items are affected by the setting of one of the categories listed above. See .IR langinfo (5) to determine which categories affect each item. .PP The value of the .I locale argument determines the action taken by .CR setlocale() . .I locale is a pointer to a character string. .SS Setting the Locale of a Program To set the program's locale for .IR category , .CR setlocale() accepts one of the following values as the .I locale argument: .IR "locale name" , .CR C , .CR POSIX , or .C """\|""" (the empty string). The actions prescribed by these values are as follows: .RS .TP 20 .I locale name If .I locale is a valid locale name (see .IR lang (5)), .CR setlocale() sets that part of the NLS environment associated with .I category as defined for that locale. .TP .C C If the value of .I locale is set to .CR C , .CR setlocale() sets that part of the NLS environment associated with .I category as defined for the .CR C locale (see .IR lang (5)). The .CR C locale is the default prior to successfully calling .CR setlocale() . .TP .C POSIX Same as .CR C . .ift .br .ift .ne 8 .TP .C """\|""" If the value of .I locale is the empty string, the setting of that part of the NLS environment associated with .I category depends upon the setting of the following environment variables in the user's environment (see .IR environ (5)): .RS .nf .IP .C "LANG LC_MESSAGES" .C "LC_ALL LC_MONETARY" .C "LC_COLLATE LC_NUMERIC" .C "LC_CTYPE LC_TIME" .fi .RE .IP If .I category is any defined value other than .CR LC_ALL , .CR setlocale() sets that category as specified by the value of the .CR LC_ALL environment. This is also the case if .CR LC_ALL is not set to the corresponding environment variable. If the environment variable is not set or is set to the empty string, .CR setlocale() sets the category as specified by the value of the .CR LANG environment variable. If .CR LANG is not set or is set to the empty string, then .CR setlocale() sets the category to the .CR C locale. For example, .RS .IP .C "setlocale(LC_TIME,"""")" .RE .IP sets the program's NLS environment associated with the .CR LC_TIME .I category to the value specified by the user's .CR LC_TIME environment variable. All other aspects of the NLS environment are unaffected. .IP If .I category is .CR LC_ALL , then all categories are set corresponding to the value of .CR LC_ALL if .CR LC_ALL is set, or .CR LANG if .CR LC_ALL is not set, except for those categories in which the corresponding environment variable is set to a valid language name (see .IR lang (5)). In this case the value of the environment variable overrides the values of .CR LC_ALL and .CR LANG for that category. If the values of both .CR LC_ALL and .CR LANG are not set or are set to the empty string, then the .CR C locale is used. .IP The following usage of .CR setlocale() results in the program's locale being set according to the the user's language requirements: .RS .IP .C "setlocale(LC_ALL,"""")" .RE .RE .SS Querying the Locale of a Program .CR setlocale() queries the current NLS environment pertaining to .IR category , if the value of .I locale is NULL. The query operation does not change the environment. The purpose of performing a query is to save that aspect of the user's current NLS environment associated with .IR category , in the value returned by .CR setlocale() , such that it can be restored with a subsequent call to .CR setlocale() . .SS Restoring the Locale of a Program To restore a category within the program locale, a .CR setlocale() call is made with the same .I category argument and the return string of the previous .CR setlocale() call given as the .I locale argument. .PP .CR getlocale() returns a pointer to a .CR locale_data structure (see .CR /usr/include/locale.h ). The members of the .CR locale_data structure contain information about the setting of each .CR setlocale() category. .I type determines what information is contained in the .CR locale_data structure. The only supported value of .I type is: .RS .TP 22 .C LOCALE_STATUS The structure member corresponding to each category contains a string with the name of the locale currently set for that category. The string does not include modifier information. .RE .SS Reentrant Interfaces The .CR setlocale_r() function performs the same function as the .CR setlocale() function except the result string describing locale information for the given category is passed back in the supplied buffer. Note that while .CR setlocale_r() can be called concurrently from multiple threads, the locale data structures that get updated are not protected against reads by other threads. Hence it is up to the application developer to ensure proper synchronization when changing locales. A buffer size of length .CR LC_BUFSIZ (defined in .CR ) is recommended. .PP The .CR getlocale_r() function expects to be passed the address of a .CR "struct locale_data" and stores the requested locale information at the given location. .SH RETURN VALUE If the pointer to a string is given for .I locale and the selection can be honored, the .CR setlocale() function returns a pointer to the string associated with the specified .I category for the new locale. The maximum length of this string is .CR LC_BUFSIZ bytes (see .CR ). If the selection cannot be honored, the .CR setlocale() function returns a null pointer and the program's locale is not changed. .PP A null pointer for .I locale causes .CR setlocale() to return a string associated with the .I category for the program's current locale. .PP The string returned by .CR setlocale() is such that a subsequent call with that string as the .I locale argument and its associated .I category restores that part of the program's locale. .PP For the Reentrant Interfaces, if an error is detected or, in the case of .CR setlocale_r() , the buffer is of insufficient length, .CR \(mi1 is returned. If the operation is successful, .CR 0 is returned. .SH ERRORS If a language name given through the .I locale argument does not identify a valid language name or the language is not available on the system (see .IR lang (5)) a null pointer is returned and the program's locale is not changed. The same behavior occurs when the call: .IP .C "setlocale(LC_ALL, """");" .PP is made and any category related environment variable in the user's environment identifies an invalid language name or a language that is not available on the system. .PP If the .I category argument is not a defined category value, a null pointer is returned and the program's locale is not changed. .PP .CR setlocale() returns a string that reflects the current setting of that aspect of the NLS environment corresponding to the .I category argument. If this return string is used in a subsequent .CR setlocale() call and the .I category arguments of the two calls do not match, the locale remains unchanged and a null pointer is returned. .SH EXAMPLES To set a program's entire locale based on the language requirements specified via the user's environment variables: .IP .C "setlocale(LC_ALL, """");" .PP If in the example the user's environment variables were set as follows: .nf .IP .C "LANG =""de_DE.iso88591"" .C "LC_COLLATE =""es_ES.iso88591"" .C "LC_MONETARY =""""" .C "LC_TIME =""en_US.iso88591"" .fi .PP the .CR LC_CTYPE , .CR LC_MONETARY , and .CR LC_NUMERIC category items would be set to correspond to the .CR de_DE.iso88591 language definition, the .CR LC_COLLATE category items would be set to correspond to the .CR es_ES.iso88591 language definition for collation and the .CR LC_TIME category items would be set corresponding to the .CR en_US.iso88591 language definition. .PP Using the same example, if the following call was made: .IP .C "struct locale_data *locale_info=getlocale(LOCALE_STATUS);" .PP the contents of .CR *locale_info would be: .nf .IP .C "locale_info->LC_ALL_D=""de_DE.iso88591""" .C "locale_info->LC_COLLATE_D=""es_ES.iso88591""" .C "locale_info->LC_CTYPE_D=""de_DE.iso88591""" .C "locale_info->LC_MESSAGES_D=""de_DE.iso88591""" .C "locale_info->LC_MONETARY_D=""de_DE.iso88591""" .C "locale_info->LC_NUMERIC_D=""de_DE.iso88591""" .C "locale_info->LC_TIME_D=""en_US.iso88591""" .fi .PP The next example shows the precedence of the .CR LC_ALL environment variable: .IP .C "setlocale(LC_ALL, """");" .PP with the following settings in the user's environment: .nf .IP .C LANG=de_DE.iso88591 .C LC_ALL=fr_FR.iso88591 .fi .PP All categories will be loaded with .CR fr_FR.iso88591 . .PP Another example showing the precedence of the .CR LC_ALL environment variable: .nf .IP .C "setlocale(LC_CTYPE, """");" .fi .PP with the following settings in the user's environment: .nf .IP .C "LANG=tr_TR.iso88599" .C "LC_ALL=da_DK.iso88591" .C "LC_CTYPE=ru_RU.iso88595" .fi .PP All categories will be loaded with .CR "da_DK.iso88591" . .PP Another example with the .CR LC_ALL environment variable: .IP .C "setlocale(LC_TIME, ""pl_PL.iso88592"");" .PP with the following settings in the user's environment: .nf .IP .C "LANG=it_IT.iso88591" .C "LC_ALL=nl_NL.iso88591" .fi .PP The .CR LC_TIME category will be set to .CR pl_PL.iso88592 , but all other categories will be set to .CR "nl_NL.iso88591" . .PP To set the date/time formats to .CR "fr_FR.iso88591" : .IP .C "setlocale(LC_TIME, ""fr_FR.iso88591"");" .PP To set the collating sequence to the .CR C locale: .IP .C "setlocale(LC_COLLATE, ""C"");" .PP To set monetary handling to the value of the user's .CR LC_MONETARY environment variable: .IP .C "setlocale(LC_MONETARY, """");" .PP Note that if the .CR LC_MONETARY environment variable is not set or is empty, the value of the user's .CR LANG environment variable is used. .PP To query a user's locale: .IP .CR "char *ch = setlocale(LC_ALL, NULL);" .PP To restore the locale saved in the above example: .IP .C "setlocale(LC_ALL, ch);" .PP To query only the part of the user's locale pertaining to the .CR LC_NUMERIC category: .IP .C "char *ch = setlocale(LC_NUMERIC, NULL);" .PP To restore the .CR LC_NUMERIC category of the user's locale saved in the above example: .IP .C "setlocale(LC_NUMERIC, ch);" .SH WARNINGS The format of the return string from .CR setlocale() is implementation specific, is not standardized across vendor's platforms, and is subject to change in future releases. The return string is valid only for the life of the process invoking the .CR setlocale() and should only be used for restoring a previously stored locale setting within the same process. .PP Using .CR getenv() as the .I locale argument is not recommended. An example of such incorrect usage is: .IP .C "setlocale(LC_ALL, getenv(""LANG""));" .PP .CR getenv() returns a character string which can be a language name, an empty string, or a null pointer; depending on the setting of the user's .CR LANG environment variable. Each of these values as the .I locale argument define a specific action to be taken by .CR setlocale() . Therefore the action taken by .CR setlocale() depends upon the value returned from the .CR getenv() call. To ensure that .CR setlocale() sets the program's locale based upon the setting of the user's environment variables the following usage is recommended: .nf .IP .C "setlocale(LC_ALL, """");" .fi .PP The value returned by .CR setlocale() points to a static area that is overwritten during the next call to .CR setlocale() . Be sure to copy these values to another area if they are to be used after a subsequent .CR setlocale() call. .PP .CR getlocale() is an HP proprietary interface, which will be .I obsoleted in a future release, and is not portable to other vendor's platforms. .PP The structure returned through a call to .CR getlocale() is overwritten during the next call to .CR getlocale() . Be sure to save these values if they are to be used after a subsequent .CR getlocale() call. .PP .CR getlocale() and .CR setlocale() are unsafe in multi-thread applications. .CR getlocale_r() and .CR setlocale_r() are MT-Safe and should be used instead. .PP Any program that calls .CR setlocale() before .CR catopen() with the .I oflag parameter set to .CR NL_CAT_LOCALE may behave differently in this release than in previous releases because of the addition of .CR LC_MESSAGES to .CR XPG4 . In the past, .CR catopen() was directed to the desired language by .CR LANG . Now, .CR catopen() with the .I oflag parameter set to .CR NL_CAT_LOCALE , is controlled by .CR LC_MESSAGES . .CR setlocale() can modify the .CR LC_MESSAGES category. For example, if the environment variables are set as follows: .nf .IP .C "LC_MESSAGES=""fr_FR.iso88591"" .fi .PP and the following call to .CR setlocale() is made: .IP .C "setlocale(LC_ALL, ""de_DE.iso88591"");" .PP followed by a call to .CR catopen() , then .CR catopen() will open the message catalogs for .CR de_DE.iso88591 rather than .CR fr_FR.iso88591 . .PP If you use .CR setlocale() and compile/link your application archive, please note that .CR setlocale() has a dependency on .CR libdld.sl that will require a change to the compile/link command. .PP Compile: .IP .C "cc -Wl,-a,archive -Wl,-E -Wl,+n -l:libdld.sl -o " .PP or, .PP Compile with .CR CCOPTS and .CR LDOPTS : .IP .C "export CCOPTS=""-Wl,-a,archive -Wl,-E -l:libdld.sl"" .IP .C "export LDOPTS="" -E +n -l:libdld.sl"" .IP .C "cc -o " .PP The option .CR -Wl,-a,archive is positionally dependent and should occur at the beginning of the compile line. For optimum compatibility in future releases, avoid using archive .CR libc with other shared libraries except for .CR libdld.sl as needed above. .SH AUTHOR .CR setlocale() , .CR setlocale_r() , .CR getlocale() , and .CR getlocale_r() were developed by OSF and HP. .SH FILES .C /usr/include/langinfo.h .br .C /usr/include/locale.h .SH SEE ALSO locale(1), localedef(1M), conv(3C), ctype(3C), ecvt(3C), getdate(3C), multibyte(3C), nl_langinfo(3C), regcomp(3C), strcoll(3C), strerror(3C), strfmon(3C), strftime(3C), string(3C), strptime(3C), strtod(3C), wcsftime(3C), wcstring(3C), printf(3S), scanf(3S), vprintf(3S), wconv(3X), wctype(3X), wstod(3X), wstol(3X), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS COMPLIANCE .CR setlocale() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4getlocale()\f1 \- get the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f4getlocale_r()\f1 \- get the locale of a program (MT-Safe)@@@\f3setlocale(3C)\f1 .\" index@\f4setlocale()\f1 \- set the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f4setlocale_r()\f1 \- set the locale of a program (MT-Safe)@@@\f3setlocale(3C)\f1 .\" index@\f1get the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f1set the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f1locale of a program, get or set the@@@\f3setlocale(3C)\f1 .\" index@\f1program, get or set the locale of a@@@\f3setlocale(3C)\f1 .\" .\" toc@\f3setlocale(3C)\f1:\0\0\f4setlocale_r()\f1, \f4getlocale()\f1, \f4getlocale_r()\f1@@@set and get the locale of a program\f1 .\" toc@\f4getlocale()\f1:\0\0get the locale of a program@@@\f1see \f3setlocale(3C)\f1 .\" toc@\f4getlocale_r()\f1:\0\0get the locale of a program (MT-Safe)@@@\f1see \f3setlocale(3C)\f1 .\" toc@\f4setlocale_r()\f1:\0\0set the locale of a program (MT-Safe)@@@\f1see \f3setlocale(3C)\f1 .\" .\" links@setlocale.3c getlocale.3c .\" links@setlocale.3c getlocale_r.3c .\" links@setlocale.3c setlocale_r.3c .\" $Header: setlocale.3c,v 72.8 94/11/30 10:15:48 ssa Exp $ .TA s .TH setlocale 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setlocale(\|), setlocale_r(\|), getlocale(\|), getlocale_r(\|) \- set and get the locale of a program .SH SYNOPSIS .CR "#include " .PP .CR "char *setlocale(int category, const char *locale);" .PP .CR "int setlocale_r(int category, const char *locale, char *buffer," .PD 0 .IP .CR " int buflen);" .PD .PP .CR "struct locale_data *getlocale(int type);" .PP .CR "int getlocale_r(int type, struct locale_data *ld);" .SH DESCRIPTION The .CR setlocale() function sets, queries, or restores the aspect of a program's locale that is specified by the .I category argument. A program's locale refers to those areas of the program's Native Language Support (NLS) environment for which the following values of .I category have been defined: .RS .TP 20 .C LC_ALL Affects behavior of all categories below, as well as all .IR nl_langinfo (3C) items. .TP .C LC_COLLATE Affects behavior of regular expressions and the NLS string collation functions (see .IR strcoll (3C), .IR strfxrm (3C), .IR wcscoll (3C), .IR wcsxfrm (3C), and .IR regexp (5)). .TP .C LC_CTYPE Affects behavior of regular expressions, character classification, and conversion functions (see .IR ctype (3C), .IR wctype (3X), .IR wconv (3X), .IR conv (3C), and .IR regexp (5)). The .CR LC_CTYPE category also affects the behavior of all routines that process multibyte characters (see .IR multibyte (3C)). .TP .C LC_MESSAGES Affects the language in which messages are displayed and the processing of affirmative and negative responses (see .IR catopen (3C) and .IR nl_langinfo (3C)). .TP .C LC_MONETARY Affects behavior of functions that handle monetary values (see .IR localeconv (3C) and .IR strfmon (3C)). .TP .C LC_NUMERIC Affects handling of the radix character in the formatted input/output functions (see .IR printf (3C), .IR scanf (3C), and .IR vprintf (3C)) and the string conversion functions (see .IR ecvt (3C) and .IR strtod (3C)). .CR LC_NUMERIC also affects the numeric values found in the .I localeconv structure. .TP .C LC_TIME Affects the behavior of time conversion functions (see .IR getdate (3C), .IR strftime (3C), and .IR strptime (3C)). .RE .PP All .IR nl_langinfo (3C) items are affected by the setting of one of the categories listed above. See .IR langinfo (5) to determine which categories affect each item. .PP The value of the .I locale argument determines the action taken by .CR setlocale() . .I locale is a pointer to a character string. .SS Setting the Locale of a Program To set the program's locale for .IR category , .CR setlocale() accepts one of the following values as the .I locale argument: .IR "locale name" , .CR C , .CR POSIX , or .C """\|""" (the empty string). The actions prescribed by these values are as follows: .RS .TP 20 .I locale name If .I locale is a valid locale name (see .IR lang (5)), .CR setlocale() sets that part of the NLS environment associated with .I category as defined for that locale. .TP .C C If the value of .I locale is set to .CR C , .CR setlocale() sets that part of the NLS environment associated with .I category as defined for the .CR C locale (see .IR lang (5)). The .CR C locale is the default prior to successfully calling .CR setlocale() . .TP .C POSIX Same as .CR C . .ift .br .ift .ne 8 .TP .C """\|""" If the value of .I locale is the empty string, the setting of that part of the NLS environment associated with .I category depends upon the setting of the following environment variables in the user's environment (see .IR environ (5)): .RS .nf .IP .C "LANG LC_MESSAGES" .C "LC_ALL LC_MONETARY" .C "LC_COLLATE LC_NUMERIC" .C "LC_CTYPE LC_TIME" .fi .RE .IP If .I category is any defined value other than .CR LC_ALL , .CR setlocale() sets that category as specified by the value of the .CR LC_ALL environment. This is also the case if .CR LC_ALL is not set to the corresponding environment variable. If the environment variable is not set or is set to the empty string, .CR setlocale() sets the category as specified by the value of the .CR LANG environment variable. If .CR LANG is not set or is set to the empty string, then .CR setlocale() sets the category to the .CR C locale. For example, .RS .IP .C "setlocale(LC_TIME,"""")" .RE .IP sets the program's NLS environment associated with the .CR LC_TIME .I category to the value specified by the user's .CR LC_TIME environment variable. All other aspects of the NLS environment are unaffected. .IP If .I category is .CR LC_ALL , then all categories are set corresponding to the value of .CR LC_ALL if .CR LC_ALL is set, or .CR LANG if .CR LC_ALL is not set, except for those categories in which the corresponding environment variable is set to a valid language name (see .IR lang (5)). In this case the value of the environment variable overrides the values of .CR LC_ALL and .CR LANG for that category. If the values of both .CR LC_ALL and .CR LANG are not set or are set to the empty string, then the .CR C locale is used. .IP The following usage of .CR setlocale() results in the program's locale being set according to the the user's language requirements: .RS .IP .C "setlocale(LC_ALL,"""")" .RE .RE .SS Querying the Locale of a Program .CR setlocale() queries the current NLS environment pertaining to .IR category , if the value of .I locale is NULL. The query operation does not change the environment. The purpose of performing a query is to save that aspect of the user's current NLS environment associated with .IR category , in the value returned by .CR setlocale() , such that it can be restored with a subsequent call to .CR setlocale() . .SS Restoring the Locale of a Program To restore a category within the program locale, a .CR setlocale() call is made with the same .I category argument and the return string of the previous .CR setlocale() call given as the .I locale argument. .PP .CR getlocale() returns a pointer to a .CR locale_data structure (see .CR /usr/include/locale.h ). The members of the .CR locale_data structure contain information about the setting of each .CR setlocale() category. .I type determines what information is contained in the .CR locale_data structure. The only supported value of .I type is: .RS .TP 22 .C LOCALE_STATUS The structure member corresponding to each category contains a string with the name of the locale currently set for that category. The string does not include modifier information. .RE .SS Reentrant Interfaces The .CR setlocale_r() function performs the same function as the .CR setlocale() function except the result string describing locale information for the given category is passed back in the supplied buffer. Note that while .CR setlocale_r() can be called concurrently from multiple threads, the locale data structures that get updated are not protected against reads by other threads. Hence it is up to the application developer to ensure proper synchronization when changing locales. A buffer size of length .CR LC_BUFSIZ (defined in .CR ) is recommended. .PP The .CR getlocale_r() function expects to be passed the address of a .CR "struct locale_data" and stores the requested locale information at the given location. .SH RETURN VALUE If the pointer to a string is given for .I locale and the selection can be honored, the .CR setlocale() function returns a pointer to the string associated with the specified .I category for the new locale. The maximum length of this string is .CR LC_BUFSIZ bytes (see .CR ). If the selection cannot be honored, the .CR setlocale() function returns a null pointer and the program's locale is not changed. .PP A null pointer for .I locale causes .CR setlocale() to return a string associated with the .I category for the program's current locale. .PP The string returned by .CR setlocale() is such that a subsequent call with that string as the .I locale argument and its associated .I category restores that part of the program's locale. .PP For the Reentrant Interfaces, if an error is detected or, in the case of .CR setlocale_r() , the buffer is of insufficient length, .CR \(mi1 is returned. If the operation is successful, .CR 0 is returned. .SH ERRORS If a language name given through the .I locale argument does not identify a valid language name or the language is not available on the system (see .IR lang (5)) a null pointer is returned and the program's locale is not changed. The same behavior occurs when the call: .IP .C "setlocale(LC_ALL, """");" .PP is made and any category related environment variable in the user's environment identifies an invalid language name or a language that is not available on the system. .PP If the .I category argument is not a defined category value, a null pointer is returned and the program's locale is not changed. .PP .CR setlocale() returns a string that reflects the current setting of that aspect of the NLS environment corresponding to the .I category argument. If this return string is used in a subsequent .CR setlocale() call and the .I category arguments of the two calls do not match, the locale remains unchanged and a null pointer is returned. .SH EXAMPLES To set a program's entire locale based on the language requirements specified via the user's environment variables: .IP .C "setlocale(LC_ALL, """");" .PP If in the example the user's environment variables were set as follows: .nf .IP .C "LANG =""de_DE.iso88591"" .C "LC_COLLATE =""es_ES.iso88591"" .C "LC_MONETARY =""""" .C "LC_TIME =""en_US.iso88591"" .fi .PP the .CR LC_CTYPE , .CR LC_MONETARY , and .CR LC_NUMERIC category items would be set to correspond to the .CR de_DE.iso88591 language definition, the .CR LC_COLLATE category items would be set to correspond to the .CR es_ES.iso88591 language definition for collation and the .CR LC_TIME category items would be set corresponding to the .CR en_US.iso88591 language definition. .PP Using the same example, if the following call was made: .IP .C "struct locale_data *locale_info=getlocale(LOCALE_STATUS);" .PP the contents of .CR *locale_info would be: .nf .IP .C "locale_info->LC_ALL_D=""de_DE.iso88591""" .C "locale_info->LC_COLLATE_D=""es_ES.iso88591""" .C "locale_info->LC_CTYPE_D=""de_DE.iso88591""" .C "locale_info->LC_MESSAGES_D=""de_DE.iso88591""" .C "locale_info->LC_MONETARY_D=""de_DE.iso88591""" .C "locale_info->LC_NUMERIC_D=""de_DE.iso88591""" .C "locale_info->LC_TIME_D=""en_US.iso88591""" .fi .PP The next example shows the precedence of the .CR LC_ALL environment variable: .IP .C "setlocale(LC_ALL, """");" .PP with the following settings in the user's environment: .nf .IP .C LANG=de_DE.iso88591 .C LC_ALL=fr_FR.iso88591 .fi .PP All categories will be loaded with .CR fr_FR.iso88591 . .PP Another example showing the precedence of the .CR LC_ALL environment variable: .nf .IP .C "setlocale(LC_CTYPE, """");" .fi .PP with the following settings in the user's environment: .nf .IP .C "LANG=tr_TR.iso88599" .C "LC_ALL=da_DK.iso88591" .C "LC_CTYPE=ru_RU.iso88595" .fi .PP All categories will be loaded with .CR "da_DK.iso88591" . .PP Another example with the .CR LC_ALL environment variable: .IP .C "setlocale(LC_TIME, ""pl_PL.iso88592"");" .PP with the following settings in the user's environment: .nf .IP .C "LANG=it_IT.iso88591" .C "LC_ALL=nl_NL.iso88591" .fi .PP The .CR LC_TIME category will be set to .CR pl_PL.iso88592 , but all other categories will be set to .CR "nl_NL.iso88591" . .PP To set the date/time formats to .CR "fr_FR.iso88591" : .IP .C "setlocale(LC_TIME, ""fr_FR.iso88591"");" .PP To set the collating sequence to the .CR C locale: .IP .C "setlocale(LC_COLLATE, ""C"");" .PP To set monetary handling to the value of the user's .CR LC_MONETARY environment variable: .IP .C "setlocale(LC_MONETARY, """");" .PP Note that if the .CR LC_MONETARY environment variable is not set or is empty, the value of the user's .CR LANG environment variable is used. .PP To query a user's locale: .IP .CR "char *ch = setlocale(LC_ALL, NULL);" .PP To restore the locale saved in the above example: .IP .C "setlocale(LC_ALL, ch);" .PP To query only the part of the user's locale pertaining to the .CR LC_NUMERIC category: .IP .C "char *ch = setlocale(LC_NUMERIC, NULL);" .PP To restore the .CR LC_NUMERIC category of the user's locale saved in the above example: .IP .C "setlocale(LC_NUMERIC, ch);" .SH WARNINGS The format of the return string from .CR setlocale() is implementation specific, is not standardized across vendor's platforms, and is subject to change in future releases. The return string is valid only for the life of the process invoking the .CR setlocale() and should only be used for restoring a previously stored locale setting within the same process. .PP Using .CR getenv() as the .I locale argument is not recommended. An example of such incorrect usage is: .IP .C "setlocale(LC_ALL, getenv(""LANG""));" .PP .CR getenv() returns a character string which can be a language name, an empty string, or a null pointer; depending on the setting of the user's .CR LANG environment variable. Each of these values as the .I locale argument define a specific action to be taken by .CR setlocale() . Therefore the action taken by .CR setlocale() depends upon the value returned from the .CR getenv() call. To ensure that .CR setlocale() sets the program's locale based upon the setting of the user's environment variables the following usage is recommended: .nf .IP .C "setlocale(LC_ALL, """");" .fi .PP The value returned by .CR setlocale() points to a static area that is overwritten during the next call to .CR setlocale() . Be sure to copy these values to another area if they are to be used after a subsequent .CR setlocale() call. .PP .CR getlocale() is an HP proprietary interface, which will be .I obsoleted in a future release, and is not portable to other vendor's platforms. .PP The structure returned through a call to .CR getlocale() is overwritten during the next call to .CR getlocale() . Be sure to save these values if they are to be used after a subsequent .CR getlocale() call. .PP .CR getlocale() and .CR setlocale() are unsafe in multi-thread applications. .CR getlocale_r() and .CR setlocale_r() are MT-Safe and should be used instead. .PP Any program that calls .CR setlocale() before .CR catopen() with the .I oflag parameter set to .CR NL_CAT_LOCALE may behave differently in this release than in previous releases because of the addition of .CR LC_MESSAGES to .CR XPG4 . In the past, .CR catopen() was directed to the desired language by .CR LANG . Now, .CR catopen() with the .I oflag parameter set to .CR NL_CAT_LOCALE , is controlled by .CR LC_MESSAGES . .CR setlocale() can modify the .CR LC_MESSAGES category. For example, if the environment variables are set as follows: .nf .IP .C "LC_MESSAGES=""fr_FR.iso88591"" .fi .PP and the following call to .CR setlocale() is made: .IP .C "setlocale(LC_ALL, ""de_DE.iso88591"");" .PP followed by a call to .CR catopen() , then .CR catopen() will open the message catalogs for .CR de_DE.iso88591 rather than .CR fr_FR.iso88591 . .PP If you use .CR setlocale() and compile/link your application archive, please note that .CR setlocale() has a dependency on .CR libdld.sl that will require a change to the compile/link command. .PP Compile: .IP .C "cc -Wl,-a,archive -Wl,-E -Wl,+n -l:libdld.sl -o " .PP or, .PP Compile with .CR CCOPTS and .CR LDOPTS : .IP .C "export CCOPTS=""-Wl,-a,archive -Wl,-E -l:libdld.sl"" .IP .C "export LDOPTS="" -E +n -l:libdld.sl"" .IP .C "cc -o " .PP The option .CR -Wl,-a,archive is positionally dependent and should occur at the beginning of the compile line. For optimum compatibility in future releases, avoid using archive .CR libc with other shared libraries except for .CR libdld.sl as needed above. .SH AUTHOR .CR setlocale() , .CR setlocale_r() , .CR getlocale() , and .CR getlocale_r() were developed by OSF and HP. .SH FILES .C /usr/include/langinfo.h .br .C /usr/include/locale.h .SH SEE ALSO locale(1), localedef(1M), conv(3C), ctype(3C), ecvt(3C), getdate(3C), multibyte(3C), nl_langinfo(3C), regcomp(3C), strcoll(3C), strerror(3C), strfmon(3C), strftime(3C), string(3C), strptime(3C), strtod(3C), wcsftime(3C), wcstring(3C), printf(3S), scanf(3S), vprintf(3S), wconv(3X), wctype(3X), wstod(3X), wstol(3X), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS COMPLIANCE .CR setlocale() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4getlocale()\f1 \- get the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f4getlocale_r()\f1 \- get the locale of a program (MT-Safe)@@@\f3setlocale(3C)\f1 .\" index@\f4setlocale()\f1 \- set the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f4setlocale_r()\f1 \- set the locale of a program (MT-Safe)@@@\f3setlocale(3C)\f1 .\" index@\f1get the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f1set the locale of a program@@@\f3setlocale(3C)\f1 .\" index@\f1locale of a program, get or set the@@@\f3setlocale(3C)\f1 .\" index@\f1program, get or set the locale of a@@@\f3setlocale(3C)\f1 .\" .\" toc@\f3setlocale(3C)\f1:\0\0\f4setlocale_r()\f1, \f4getlocale()\f1, \f4getlocale_r()\f1@@@set and get the locale of a program\f1 .\" toc@\f4getlocale()\f1:\0\0get the locale of a program@@@\f1see \f3setlocale(3C)\f1 .\" toc@\f4getlocale_r()\f1:\0\0get the locale of a program (MT-Safe)@@@\f1see \f3setlocale(3C)\f1 .\" toc@\f4setlocale_r()\f1:\0\0set the locale of a program (MT-Safe)@@@\f1see \f3setlocale(3C)\f1 .\" .\" links@setlocale.3c getlocale.3c .\" links@setlocale.3c getlocale_r.3c .\" links@setlocale.3c setlocale_r.3c .\" $Header: syslog.3c,v 76.1 95/07/05 17:52:44 ssa Exp $ .TA s .TH syslog 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME syslog(\|), openlog(\|), closelog(\|), setlogmask(\|) \- control system log .SH SYNOPSIS .C "#include " .PP .C "void syslog(int priority, const char *message, ...);" .PP .C "void openlog(const char *ident, int logopt, int facility);" .PP .C "void closelog(void);" .PP .C "int setlogmask(int maskpri);" .SS Remarks The ANSI C "\c .CR ", ...\$\c" " construct denotes a variable length argument list whose optional [or required] \" EDITOR: make this line fit the specific page members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION .TP 15 .C syslog() writes a message onto the system log maintained by .CR syslogd (see .IR syslogd (1M)). The message is tagged with .IR priority . The .I message is similar to a .IR printf (3S) format string except that .CR %m is replaced by the error message associated with the current value of .CR errno . A trailing newline is added if needed. .IP This message is read by .CR syslogd and written to the system console, log files, selected users' terminals, or forwarded to .CR syslogd on another host as appropriate. .IP .I priority is encoded as the logical OR of a .I level and a .IR facility . The .I level signifies the urgency of the message, and .I facility signifies the subsystem generating the message. .I facility can be encoded explicitly in .IR priority , or a default .I facility can be set with .CR openlog() (see below). .IP .I level is selected from an ordered list: .RS .RS .TP 20 .C LOG_EMERG A panic condition. This is normally broadcast to all users. .TP .C LOG_ALERT A condition that should be corrected immediately, such as a corrupted system database. .TP .C LOG_CRIT Critical conditions, such as hard device errors. .TP .C LOG_ERR Errors. .TP .C LOG_WARNING Warning messages. .TP .C LOG_NOTICE Conditions that are not error conditions, but should possibly be handled specially. .TP .C LOG_INFO Informational messages. .TP .C LOG_DEBUG Messages that contain information normally of use only when debugging a program. .RE .RE .IP .CR syslog() does not log a message that does not have a .I level set. .IP If .CR syslog() cannot pass the message to .CR syslogd , it attempts to write the message on .CR /dev/console if the .CR LOG_CONS option is set (see below). .TP .C openlog() can be called to initialize the log file, if special processing is needed. .I ident is a string that precedes every message. .I logopt is a mask of bits, logically OR'ed together, indicating logging options. The values for .I logopt are: .RS .RS .TP 20 .C LOG_PID Log the process ID with each message; useful for identifying instantiations of daemons. .TP .C LOG_CONS Force writing messages to the console if unable to send it to .CR syslogd . This option is safe to use in daemon processes that have no controlling terminal because .CR syslog() forks before opening the console. .TP .C LOG_NDELAY Open the connection to .CR syslogd immediately. Normally, the open is delayed until the first message is logged. This is useful for programs that need to manage the order in which file descriptors are allocated. .TP .C LOG_NOWAIT Do not wait for children forked to log messages on the console. This option should be used by processes that enable notification of child termination via .CR SIGCLD , because .CR syslog() might otherwise block, waiting for a child whose exit status has already been collected. .RE .RE .IP .I facility encodes a default facility to be assigned to all messages written subsequently by .CR syslog() with no explicit facility encoded. .IP .RS .RS .TP 20 .C LOG_KERN Messages generated by the kernel. These cannot be generated by any user processes. .TP .C LOG_USER Messages generated by random user processes. This is the default facility identifier if none is specified. .TP .C LOG_MAIL The mail system. .TP .C LOG_DAEMON System daemons, such as .IR inetd (1M), .IR ftpd (1M), etc. .TP .C LOG_AUTH The authorization system: .IR login (1), .IR su (1), .IR getty (1M), etc. .TP .C LOG_LPR The line printer spooling system: .IR lp (1), .IR lpsched (1M), etc. .TP .C LOG_LOCAL0 Reserved for local use. Similarly for .CR LOG_LOCAL1 through .CR LOG_LOCAL7 . .RE .RE .TP .C closelog() closes the log file. .TP .C setlogmask() sets the log priority mask to .I maskpri and returns the previous mask. Calls to .CR syslog() with a priority not set in .I maskpri are rejected. The mask for an individual priority .I pri is calculated by the macro .CI LOG_MASK( pri )\c ; the mask for all priorities up to and including .I toppri is given by the macro .CR LOG_UPTO\c .RI ( toppri ). By default, all priorities are logged. .SH ERRORS .CR syslog fails if any of the following conditions are encountered: .RS .TP 15 [EAGAIN] The named pipe .CR /dev/log is blocked for writing. .TP [ENOENT] The named pipe .CR /dev/log bold) could not be opened successfully. .SH EXAMPLES .CR who logs a message regarding some sort of unexpected and serious error: .IP .C "syslog(LOG_ALERT, ""who: internal error 23"");" .PP .CR ftpd uses .CR openlog() to arrange to log its process ID, to log to the console if necessary, and to log in the name of the .I daemon facility: .IP .C "openlog(""ftpd"", LOG_PID|LOG_CONS, LOG_DAEMON);" .PP Arrange to log messages only at levels .CR LOG_ERR and lower: .IP .C setlogmask(LOG_UPTO(LOG_ERR)); .PP Typical usage of .CR syslog() to log a connection: .IP .C "syslog(LOG_INFO,\ ""Connection\ from\ host\ %d"",\ CallingHost);" .PP If the facility has not been set with .CR openlog() , it defaults to .CR LOG_USER . .PP Explicitly set the facility for this message: .IP .C "syslog(LOG_INFO|LOG_LOCAL2,\ ""foobar\ error:\ %m"");" .SH WARNINGS A call to .CR syslog() has no effect unless the syslog daemon .RI ( syslogd (1M)) is running. .CR openlog() does not copy and store the .I ident string internally; it stores only a character pointer. Therefore it is the responsibility of the programmer to make sure that the .I ident argument points to the correct string until the log file is closed. .SH AUTHOR .CR syslog() was developed by the University of California, Berkeley. .SH SEE ALSO logger(1), syslogd(1M). .\" .\" index@\f4syslog()\f1 \- write message onto system log file@@@\f3syslog(3C)\f1 .\" index@\f4openlog()\f1 \- initialize system log file@@@\f3syslog(3C)\f1 .\" index@\f4closelog()\f1 \- close system log file@@@\f3syslog(3C)\f1 .\" index@\f4setlogmask()\f1 \- set system log file priority mask@@@\f3syslog(3C)\f1 .\" index@control system log@@@\f3syslog(3C)\f1 .\" index@system log, control@@@\f3syslog(3C)\f1 .\" index@log, system, control@@@\f3syslog(3C)\f1 .\" .\" toc@\f3syslog(3C)\f1:\0\0\f4syslog()\f1, \f4openlog()\f1, \f4closelog()\f1, \f4setlogmask()\fP@@@control system log .\" toc@\f4openlog()\f1:\0\0control system log@@@see \f3syslog(3C)\f1 .\" toc@\f4closelog()\f1:\0\0control system log@@@see \f3syslog(3C)\f1 .\" toc@\f4setlogmask()\f1:\0\0control system log@@@see \f3syslog(3C)\f1 .\" .\" links@syslog.3c openlog.3c .\" links@syslog.3c closelog.3c .\" links@syslog.3c setlogmask.3c .\" .\" fileset_database@syslog.3c PROGRAMING-MAN .\" $Header: getmntent.3x,v 76.1 95/07/05 17:29:38 ssa Exp $ .TA g .TH getmntent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getmntent(\|), getmntent_r(\|), setmntent(\|), addmntent(\|), endmntent(\|), hasmntopt(\|) \- get file system descriptor file entry .SH SYNOPSIS .C "#include " .PP .C "\s-1FILE\s0 \(**setmntent(const char \(**path, char \(**type);" .PP .C "struct mntent \(**getmntent(\s-1FILE\s0 \(**stream);" .PP .C "int getmntent_r(" .nf .PD 0 .IP .C "\s-1FILE\s0 *stream," .C "struct mntent *result," .C "char *buffer," .C "int buflen);" .PD .PP .C "int addmntent(\s-1FILE\s0 \(**stream, struct mntent \(**mnt);" .PP .C "char \(**hasmntopt(struct mntent \(**mnt, const char \(**opt);" .PP .C "int endmntent(\s-1FILE\s0 \(**stream);" .SH DESCRIPTION These routines replace the obsolete .C getfsent() routines (see .IR getfsent (3X)) for accessing the file system description file .CR /etc/fstab . They are also used to access the mounted file system description file .CR /etc/mnttab . .TP 20 .C setmntent() Opens a file system description file and returns a file pointer which can then be used with .CR getmntent() , .CR addmntent() , or .CR endmntent() . The .I type argument is the same as in .IR fopen (3C). .TP .C getmntent() Reads the next line from .I stream and returns a pointer to an object with the following structure containing the broken-out fields of a line in the file-system description file, .RC < mntent.h >. The fields have meanings described in .IR fstab (4). .nf .IP .C struct mntent { .C " char *mnt_fsname; /* file system name */" .C " char *mnt_dir; /* file system path prefix */" .C " char *mnt_type; /* hfs, nfs, swap, or xx */" .C " char *mnt_opts; /* ro, suid, etc. */" .C " int mnt_freq; /* dump frequency, in days */" .C " int mnt_passno; /* pass number on parallel fsck */" .C " long mnt_time; /* When file system was mounted; */" .C " /* see mnttab(4). */" .C " /* (0 for NFS) */" .C }; .ft .ps .fi .IP .TP .C getmntent_r() Uses three extra parameters to provide results equivalent to those produced by .CR getmntent() . The extra parameters are: .PD 0 .IP 1. The address of a .C "struct mntent" where the result will be stored. .IP 2. A buffer to store character strings to which fields in the .C "struct mntent" will point. .IP 3. The length of the user-supplied buffer. A buffer length of 1025 is recommended. .PD .TP .C addmntent() Adds the .C mntent structure .I mnt to the end of the open file .IR stream . Note that .I stream must be opened for writing. .TP .C hasmntopt() Scans the .C mnt_opts field of the .C mntent structure .I mnt for a substring that matches .IR opt . It returns the address of the substring if a match is found; .C 0 otherwise. .TP .C endmntent() Closes the file. .PP The following definitions are provided in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNT_CHECKLIST "/etc/fstab" #define MNT_MNTTAB "/etc/mnttab" #define MNTMAXSTR 128 /* Max size string in mntent */ #define MNTTYPE_HFS "hfs" /* HFS file system */ #define MNTTYPE_CDFS "hfs" /* CD-ROM file system */ #define MNTTYPE_NFS "nfs" /* Network file system */ #define MNTTYPE_SWAP "swap" /* Swap device */ #define MNTTYPE_SWAPFS "swapfs" /* File system swap */ #define MNTTYPE_IGNORE "ignore" /* Ignore this entry */ #define MNTOPT_DEFAULTS "defaults" /* Use all default options */ #define MNTOPT_RO "ro" /* Read only */ #define MNTOPT_RW "rw" /* Read/write */ #define MNTOPT_SUID "suid" /* Set uid allowed */ #define MNTOPT_NOSUID "nosuid" /* No set uid allowed */ #define MNTOPT_QUOTA "quota" /* Enable disk quotas */ #define MNTOPT_NOQUOTA "noquota" /* Disable disk quotas */ .ft .ps .fi .RE .PP The following definition is provided for device swap in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_END "end" /* swap after end of file system, Series 300/400/700 only */ .ft .ps .fi .RE .PP The following definitions are provided for file system swap in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_MIN "min" /* minimum file system swap */ #define MNTOPT_LIM "lim" /* maximum file system swap */ #define MNTOPT_RES "res" /* reserve space for file system */ #define MNTOPT_PRI "pri" /* file system swap priority */ .ft .ps .RE .PP .SH NETWORKING FEATURES .SS NFS The following definitions are provided in .RC < mntent.h >: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define MNTOPT_BG "bg" /* Retry mount in background */ #define MNTOPT_FG "fg" /* Retry mount in foreground */ #define MNTOPT_RETRY "retry" /* Number of retries allowed */ #define MNTOPT_RSIZE "rsize" /* Read buffer size in bytes */ #define MNTOPT_WSIZE "wsize" /* Write buffer size in bytes*/ #define MNTOPT_TIMEO "timeo" /* Timeout in 1/10 seconds */ #define MNTOPT_RETRANS "retrans" /* Number of retransmissions */ #define MNTOPT_PORT "port" /* Server's IP NFS port */ #define MNTOPT_SOFT "soft" /* Soft mount */ #define MNTOPT_HARD "hard" /* Hard mount */ #define MNTOPT_INTR "intr" /* Interruptable hard mounts */ #define MNTOPT_NOINTR "nointr" /* Uninterruptable hard mounts*/ #define MNTOPT_DEVS "devs" /* Device file access allowed */ #define MNTOPT_NODEVS "nodevs" /* No device file access allowed */ .ft .ps .fi .TE .SH RETURN VALUE .TP 20 .C setmntent() Returns a null pointer on error. .TP .C getmntent() Returns a null pointer on error or EOF. Otherwise, .C getmntent() returns a pointer to a mntent structure. Some of the fields comprising a mntent structure are optional in .C /etc/fstab and .CR /etc/mnttab . In the supplied structure, such missing character pointer fields are set to NULL and missing integer fields are set to \(mi1 for .C mnt_freq and .C mnt_passno. If the integer field for .C mnt_time is missing, it is set to 0. .TP .C getmntent_r() Returns a .C -1 on error or EOF, or if the supplied buffer is of insufficient length. If the operation is successful, .C 0 is returned. .TP .C addmntent() Returns .C 1 on error. .TP .C endmntent() Returns .CR 1 . .SH WARNINGS The return value for .C getmntent() points to static information that is overwritten in each call. Thus, .C getmntent() is unsafe for multi-thread applications. .C getmntent_r() is MT-Safe and should be used instead. .SH AUTHOR .CR addmntent() , .CR endmntent() , .CR getmntent() , .CR hasmntopt() , and .C setmntent() were developed by The University of California, Berkeley, Sun Microsystems, Inc., and HP. .SH FILES .C /etc/fstab .br .C /etc/mnttab .SH SEE ALSO fstab(4), getfsent(3X), mnttab(4). .\" .\" index@\f4getmntent()\f1 \- get a file system description file entry@@@\f3getmntent(3X)\f1 .\" index@\f4setmntent()\f1 \- open a file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4addmntent()\f1 \- add entry to open file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4endmntent()\f1 \- close file system description file@@@\f3getmntent(3X)\f1 .\" index@\f4hasmntopt()\f1 \- search mount option field in file system description file@@@\f3getmntent(3X)\f1 .\" index@file system description file entry@@@\f3getmntent(3X)\f1 .\" index@file entry get file system description@@@\f3getmntent(3X)\f1 .\" index@get file system description file@@@\f3getmntent(3X)\f1 .\" .\" toc@\f3getmntent(3X)\f1:\0\0\f4getmntent()\f1, \f4getmntent_r()\f1, \f4setmntent()\f1, \f4addmntent()\f1, \f4endmntent()\f1, \n\f4hasmntopt()\f1@@@get file system descriptor file entry .\" toc@\f4setmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4addmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4endmntent()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" toc@\f4hasmntopt()\f1:\0\0get file system descriptor file entry@@@see \f3getmntent(3X)\f1 .\" .\" links@getmntent.3x getmntent_r.3x .\" links@getmntent.3x setmntent.3x .\" links@getmntent.3x addmntent.3x .\" links@getmntent.3x endmntent.3x .\" links@getmntent.3x hasmntopt.3x .\ .\" fileset_database@getmntent.3x PROGRAMING-MAN .\" $Header: getnetent.3n,v 78.1 96/03/15 15:57:28 ssa Exp $ .TA g .TH getnetent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnetent(\|), getnetent_r(\|), getnetbyaddr(\|), getnetbyaddr_r(\|), getnetbyname(\|), getnetbyname_r(\|), setnetent(\|), setnetent_r(\|), endnetent(\|),endnetent_r(\|) \- get network entry .SH SYNOPSIS .nf .C #include .C #include .PP .C "struct netent *getnetent(void);" .PP .C "int getnetent_r(struct netent *result, struct netent_data *buffer);" .PP .C "struct netent *getnetbyname(const char *name);" .PP .C "int getnetbyname_r(" .PD 0 .IP .C "const char *name," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "struct netent *getnetbyaddr(int net, int type);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "struct netent *getnetbyaddr(in_addr_t net, int type);" .PP .C "int getnetbyaddr_r(" .PD 0 .IP .C "int net," .C "int type," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "int setnetent(int stayopen);" .PP .C "int setnetent_r(int stayopen, struct netent_data *buffer);" .PP .C "int endnetent(void);" .PP .C "int endnetent_r(struct netent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setnetent(int stayopen);" .C "void endnetent(void);" .fi .SH DESCRIPTION .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() each return a pointer to a structure of type .I netent containing the broken-out fields of a line in the network data base, .CR /etc/networks . .PP The members of this structure are: .RS .TP 15 .CR n_name The official name of the network. .TP .CR n_aliases A null-terminated list of alternate names for the network. .TP .CR n_addrtype The type of the network number returned; always AF_INET. .TP .CR n_net The network number. .RE .PP Functions behave as follows: .RS .TP 22 .CR getnetent() Reads the next line of the file, opening the file if necessary. .TP .CR setnetent() opens and rewinds the file. If the .I stayopen flag is non-zero, the network data base is not closed after each call to .CR getnetent() (either directly or indirectly through one of the other .CR getnet* calls). .TP .CR endnetent() Closes the file. .TP .CR getnetbyname() Sequentially searches from the beginning of the file until a network name (among either the official names or the aliases) matching its parameter .I name is found, or until .SM EOF is encountered. .TP .CR getnetbyaddr() Sequentially searches from the beginning of the file until a network number matching its parameter .I net is found, or until .SM EOF is encountered. The parameter .I net must be in network order. The parameter .I type must be the constant .CR AF_INET . Network numbers are supplied in host order (see .IR byteorder (3N)). .PP If the system is running Network Information Service .SM (NFS), .CR getnetbyname() and .CR getnetbyaddr() obtain their network information from the .SM NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getnetent_r() , .CR getnetbyname_r() and .CR getnetbyaddr_r() expect to be passed the address of a .I "struct netent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct netent_data" , must also be supplied. This structure is used to store data, to which fields in the .I "struct netent" will point, as well as state information such as open file descriptors. The .I "struct netent_data" is defined in the file .CR . .PP .CR setnetent_r() and .CR endnetent_r() are to be used only in conjunction with .CR getnetent_r() and take the same pointer to a .I "struct netent_data" as a parameter. If the Network Information Service is being used, .CR setnetent_r() initializes an internal database key. If the .B /etc/networks file is being used, .CR setnetent_r() opens or rewinds the file. .CR endnetent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setnetent_r() currently has no effect. However, .CR setnetent() can still be used to keep the .B /etc/networks file open when making calls to .CR getnetbyaddr_r() and .CR getnetbyname_r() . .PP The .I net_fp field in the .I "struct netent_data" must be initialized to .SM NULL before it is passed to either .CR getnetent_r() or .CR setnetent_r() for the first time. Thereafter it should not be modified in any way. This is the only .I netent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getnetbyname() , .CR getnetbyaddr() , .CR getnetent() , and their reentrant counterparts, internally call the name service switch to access the "networks" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve network names and addresses. .SH RETURN VALUE .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() return a null pointer (0) on .SM EOF or when they are unable to open .CR /etc/networks . .CR getnetbyaddr() also returns a null pointer if its .I type parameter is invalid. .PP .CR getnetent_r() , .CR getnetbyname_r() , .CR getnetbyaddr_r() , .CR setnetent_r() , and .CR endnetent_r() return a -1 if the operation is unsuccessful or, in the case of .CR getnetent_r() , if the end of the networks list has been reached. A 0 is returned otherwise. .SH EXAMPLE The following code excerpt counts the number of network entries: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct netent netbuf; struct netent_data ndbuf; ndbuf.net_fp = NULL; (void) setnetent_r(0, &ndbuf); while (getnetent_r(&netbuf, &ndbuf) != -1) count++; (void) endnetent_r(&ndbuf); .ft .ps .fi .RE .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getnetent() , .CR getnetbyaddr() , .CR getnetbyname() , .CR setnetent() , and .CR endnetent() are unsafe in multi-thread applications. .CR getnetent_r() , .CR getnetbyaddr_r() , .CR getnetbyname_r() , .CR setnetent_r() , and .CR endnetent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getnetent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/networks .SH SEE ALSO ypserv(1M), networks(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getnetent() ": XPG4" .\" .\" index@\f4endnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyaddr()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyname()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4setnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1set network entry@@@\f3getnetent(3N)\f1 .\" index@\f1network entry, get or set@@@\f3getnetent(3N)\f1 .\" .\" toc@\f3getnetent(3N)\f1:\0\0\f4getnetent()\f1, \f4getnetbyaddr()\f1, \f4getnetbyname()\f1, \f4setnetent()\f1, \n\f4endnetent()\f1@@@get network entry .\" toc@\f4getnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" .\" links@getnetent.3n getnetbyadd.3n .\" links@getnetent.3n getnetbynam.3n .\" links@getnetent.3n setnetent.3n .\" links@getnetent.3n endnetent.3n .\" links@getnetent.3n getnetent_r.3n .\" links@getnetent.3n getnetbyaddr_r.3n .\" links@getnetent.3n getnetbyname_r.3n .\" links@getnetent.3n setnetent_r.3n .\" links@getnetent.3n endnetent_r.3n .\" .\" fileset_database@getnetent.3n INETSVCS-MAN .\" $Header: getnetent.3n,v 78.1 96/03/15 15:57:28 ssa Exp $ .TA g .TH getnetent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnetent(\|), getnetent_r(\|), getnetbyaddr(\|), getnetbyaddr_r(\|), getnetbyname(\|), getnetbyname_r(\|), setnetent(\|), setnetent_r(\|), endnetent(\|),endnetent_r(\|) \- get network entry .SH SYNOPSIS .nf .C #include .C #include .PP .C "struct netent *getnetent(void);" .PP .C "int getnetent_r(struct netent *result, struct netent_data *buffer);" .PP .C "struct netent *getnetbyname(const char *name);" .PP .C "int getnetbyname_r(" .PD 0 .IP .C "const char *name," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "struct netent *getnetbyaddr(int net, int type);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "struct netent *getnetbyaddr(in_addr_t net, int type);" .PP .C "int getnetbyaddr_r(" .PD 0 .IP .C "int net," .C "int type," .C "struct netent *result," .C "struct netent_data *buffer);" .PD .PP .C "int setnetent(int stayopen);" .PP .C "int setnetent_r(int stayopen, struct netent_data *buffer);" .PP .C "int endnetent(void);" .PP .C "int endnetent_r(struct netent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setnetent(int stayopen);" .C "void endnetent(void);" .fi .SH DESCRIPTION .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() each return a pointer to a structure of type .I netent containing the broken-out fields of a line in the network data base, .CR /etc/networks . .PP The members of this structure are: .RS .TP 15 .CR n_name The official name of the network. .TP .CR n_aliases A null-terminated list of alternate names for the network. .TP .CR n_addrtype The type of the network number returned; always AF_INET. .TP .CR n_net The network number. .RE .PP Functions behave as follows: .RS .TP 22 .CR getnetent() Reads the next line of the file, opening the file if necessary. .TP .CR setnetent() opens and rewinds the file. If the .I stayopen flag is non-zero, the network data base is not closed after each call to .CR getnetent() (either directly or indirectly through one of the other .CR getnet* calls). .TP .CR endnetent() Closes the file. .TP .CR getnetbyname() Sequentially searches from the beginning of the file until a network name (among either the official names or the aliases) matching its parameter .I name is found, or until .SM EOF is encountered. .TP .CR getnetbyaddr() Sequentially searches from the beginning of the file until a network number matching its parameter .I net is found, or until .SM EOF is encountered. The parameter .I net must be in network order. The parameter .I type must be the constant .CR AF_INET . Network numbers are supplied in host order (see .IR byteorder (3N)). .PP If the system is running Network Information Service .SM (NFS), .CR getnetbyname() and .CR getnetbyaddr() obtain their network information from the .SM NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getnetent_r() , .CR getnetbyname_r() and .CR getnetbyaddr_r() expect to be passed the address of a .I "struct netent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct netent_data" , must also be supplied. This structure is used to store data, to which fields in the .I "struct netent" will point, as well as state information such as open file descriptors. The .I "struct netent_data" is defined in the file .CR . .PP .CR setnetent_r() and .CR endnetent_r() are to be used only in conjunction with .CR getnetent_r() and take the same pointer to a .I "struct netent_data" as a parameter. If the Network Information Service is being used, .CR setnetent_r() initializes an internal database key. If the .B /etc/networks file is being used, .CR setnetent_r() opens or rewinds the file. .CR endnetent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setnetent_r() currently has no effect. However, .CR setnetent() can still be used to keep the .B /etc/networks file open when making calls to .CR getnetbyaddr_r() and .CR getnetbyname_r() . .PP The .I net_fp field in the .I "struct netent_data" must be initialized to .SM NULL before it is passed to either .CR getnetent_r() or .CR setnetent_r() for the first time. Thereafter it should not be modified in any way. This is the only .I netent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getnetbyname() , .CR getnetbyaddr() , .CR getnetent() , and their reentrant counterparts, internally call the name service switch to access the "networks" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve network names and addresses. .SH RETURN VALUE .CR getnetent() , .CR getnetbyname() , and .CR getnetbyaddr() return a null pointer (0) on .SM EOF or when they are unable to open .CR /etc/networks . .CR getnetbyaddr() also returns a null pointer if its .I type parameter is invalid. .PP .CR getnetent_r() , .CR getnetbyname_r() , .CR getnetbyaddr_r() , .CR setnetent_r() , and .CR endnetent_r() return a -1 if the operation is unsuccessful or, in the case of .CR getnetent_r() , if the end of the networks list has been reached. A 0 is returned otherwise. .SH EXAMPLE The following code excerpt counts the number of network entries: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int count = 0; struct netent netbuf; struct netent_data ndbuf; ndbuf.net_fp = NULL; (void) setnetent_r(0, &ndbuf); while (getnetent_r(&netbuf, &ndbuf) != -1) count++; (void) endnetent_r(&ndbuf); .ft .ps .fi .RE .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getnetent() , .CR getnetbyaddr() , .CR getnetbyname() , .CR setnetent() , and .CR endnetent() are unsafe in multi-thread applications. .CR getnetent_r() , .CR getnetbyaddr_r() , .CR getnetbyname_r() , .CR setnetent_r() , and .CR endnetent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getnetent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/networks .SH SEE ALSO ypserv(1M), networks(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getnetent() ": XPG4" .\" .\" index@\f4endnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyaddr()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetbyname()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4getnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f4setnetent()\f1: get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1get network entry@@@\f3getnetent(3N)\f1 .\" index@\f1set network entry@@@\f3getnetent(3N)\f1 .\" index@\f1network entry, get or set@@@\f3getnetent(3N)\f1 .\" .\" toc@\f3getnetent(3N)\f1:\0\0\f4getnetent()\f1, \f4getnetbyaddr()\f1, \f4getnetbyname()\f1, \f4setnetent()\f1, \n\f4endnetent()\f1@@@get network entry .\" toc@\f4getnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyaddr_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4getnetbyname_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4setnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" toc@\f4endnetent_r()\f1: get network entry@@@see \f3getnetent(3N)\f1 .\" .\" links@getnetent.3n getnetbyadd.3n .\" links@getnetent.3n getnetbynam.3n .\" links@getnetent.3n setnetent.3n .\" links@getnetent.3n endnetent.3n .\" links@getnetent.3n getnetent_r.3n .\" links@getnetent.3n getnetbyaddr_r.3n .\" links@getnetent.3n getnetbyname_r.3n .\" links@getnetent.3n setnetent_r.3n .\" links@getnetent.3n endnetent_r.3n .\" .\" fileset_database@getnetent.3n INETSVCS-MAN .\" $Header: getnetgrent.3c,v 76.2 95/05/26 17:06:46 ssa Exp $ .TA g .TH getnetgrent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnetgrent(\|), setnetgrent(\|), endnetgrent(\|), innetgr(\|), getnetgrent_r(\|), setnetgrent_r(\|), endnetgrent_r(\|) \- get network group entry .SH SYNOPSIS .nf .C int innetgr( .C " char *netgroup, " .C " char *machine, " .C " char *user, " .C " char *domain" .C ); .PP .C int setnetgrent(char *netgroup); .PP .C int setnetgrent_r( .C " char *grp," .C " char **ngstate" .C ); .PP .C int endnetgrent(); .PP .C int endnetgrent_r( .C " char **ngstaste" .C ); .PP .C int getnetgrent( .C " char **machinep, " .C " char **userp, " .C " char **domainp" .C ); .PP .C int getnetgrent_r( .C " char **machinep," .C " char **namep," .C " char **domainp," .C " char **ngstate" .C ); .fi .SH DESCRIPTION .TP 20 .C innetgr() Returns 1 if .C netgroup contains the machine, user, and domain triple as a member. Otherwise, it returns 0. If .IR machine , .IR user , or .I domain is .SM NULL, .C innetgr interprets .SM NULL to mean, any machine, user, or domain respectively. Refer to .IR netgroup (4) for a description of .C netgroup membership criteria. .TP .C getnetgrent() Returns the next member of a network group. After the call, .I machinep contains a pointer to a string containing the name of the machine part of the network group member. Pointers .I userp and .I domainp behave in a manner similar to .IR machinep . If any of these pointers are returned with a .SM NULL value, they are interpreted as wild cards. .C getnetgrent() allocates space for the names. This space is released when an .C endnetgrent() call is made. .C getnetgrent() returns 1 if it succeeded in obtaining another network group member, 0 if it reached the end of the group. .TP .C setnetgrent() Establishes the network group from which .C getnetgrent() obtains members, and also restarts calls to .C getnetgrent() from the beginning of the list. If the previous .C setnetgrent() call was to a different network group, a .C endnetgrent() call is implied. .TP .C endnetgrent() Frees the space allocated during .C getnetgrent() calls. .PD .PP If the system is running the Network Information Service (NIS) services, .CR setnetgrent() gets the netgroup information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getnetgrent_r(), .CR setnetgrent_r(), and .CR endnetgrent_r(), expect to be passed a pointer of .CR "char **ngstate" that will store the result of the lookup at the supplied location. This structure is used to store data, which the other reentrant (_r) routines use. .PP .CR setnetgrent_r() and .CR endnetgrent_r() are to be used only in conjunction with .CR getnetgrent_r() and take the same pointer to a char **ngstate as a parameter. .PP The .I **ngstate pointer must be initialized to NULL before it is passed to .CR setnetgrent_r() for the first time. Thereafter is should not be modified in any way. .SS Name Service Switch-Based Operation The library routine, .CR innetgr() , setnetgrent() , and setnetgrent_r(), internally call the name service switch to access the "netgroup" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve netgroup lookups. .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getnetgrent() , .CR setnetgrent() , and .CR endnetgrent() are unsafe in multi-thread applications. .CR getnetgrent_r() , .CR setnetgrent_r() , and .CR endnetgrent_r() are MT-Safe and should be used instead. .SH AUTHOR .C getnetgrent() was developed by Sun Microsystems, Inc. .SH FILES .C /etc/netgroup .C /etc/nsswitch.conf .SH SEE ALSO netgroup(4), switch(4). .\" .\" index@\f4getnetgrent()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@\f4endnetgrent()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@\f4innetgr()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@\f4setnetgrent()\fP \- get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@get network group entry@@@\f3getnetgrent(3C)\f1 .\" index@set network group entry@@@\f3getnetgrent(3C)\f1 .\" index@network group entry, get or set@@@\f3getnetgrent(3C)\f1 .\" index@group entry, network, get or set@@@\f3getnetgrent(3C)\f1 .\" index@entry, network group, get or set@@@\f3getnetgrent(3C)\f1 .\" .\" toc@\f3getnetgrent(3C)\f1: \f4getnetgrent()\fP, \f4setnetgrent()\fP, \f4endnetgrent()\fP, \f4innetgr()\fP@@@get network group entry .\" .\" links@getnetgrent.3c setnetgrent.3c .\" links@getnetgrent.3c endnetgrent.3c .\" links@getnetgrent.3c innetgr.3c .\" .\" fileset_database@getnetgrent.3c PROGRAMING-MAN .\" $Header: getprdfent.3,v 72.3 94/07/05 18:07:26 ssa Exp $ .TA g .TH getprdfent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprdfent, getprdfnam, setprdfent, endprdfent, putprdfnam \- manipulate system default database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct pr_default \(**getprdfent(void);" .PP .CR "struct pr_default \(**getprdfnam(const char \(**name);" .PP .CR "void setprdfent(void);" .PP .CR "void endprdfent(void);" .PP .CR "int putprdfnam(const char \(**name, struct pr_default \(**pr);" .fi .SH DESCRIPTION .I getprdfent and .I getprdfnam each returns a pointer to an object with the following structure containing the broken-out fields of a line in the system default database. Each line in the database contains a .I pr_default structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v struct system_default_fields { time_t fd_inactivity_timeout ; char fd_boot_authenticate ; } ; struct system_default_flags { unsigned short fg_inactivity_timeout:1, fg_boot_authenticate:1, } ; struct pr_default { char dd_name[20] ; char dg_name ; struct pr_field prd ; struct pr_flag prg ; struct t_field tcd ; struct t_flag tcg ; struct dev_field devd ; struct dev_flag devg ; struct system_default_fields sfld ; struct system_default_flags sflg ; } ; .fi .RE .PP Currently there is only one entry in the system default database, referenced by name .BR default . .PP The System Default database contains default values for all parameters in the Protected Password, Terminal Control, and Device Assignment databases, as well as configurable system-wide parameters. The fields from the other databases are described in the corresponding manual entries. .I fd_inactivity_timeout is the number of seconds until a session is terminated on trusted systems. .PP .I fd_boot_authenticate is a boolean flag that indicates whether an authorized user must authenticate before the system begins operation. .PP .I getprdfent returns a pointer to the first .I pr_default structure in the database when first called. Thereafter, it returns a pointer to the next .I pr_default structure in the database, so that successive calls can be used to search the database (not currently supported). .PP .I getprdfnam searches from the beginning of the file until a default entry matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a .SM .B NULL pointer. Currently, all programs access the default database by calling .I getprdfnam ("default"). .PP A call to .I setprdfent has the effect of rewinding the default control file to allow repeated searches. .I endprdfent can be called to close the database when processing is complete. .PP .I putprdfnam puts a new or replaced default control entry .I pr with key .I name into the database. If the .I prg.fd_name field is 0, the requested entry is deleted from the system default database. .I putprdfnam locks the database for all update operations, and performs an .I endprdfent after the update or failed attempt. .SH RETURN VALUE .I getprdfent and .I getprdfnam return .SM .B NULL pointers on .SM EOF or error. .I putprdfnam returns 0 if it cannot add or update the entry. .SH WARNINGS Do not delete the system default entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 45 .C /tcb/files/auth/system/default System Defaults database .SH SEE ALSO authcap(4), default(4), getprpwent(3), getprtcent(3), getdvagent(3). .SH NOTES The value returned by .I getprdfent and .I getprdfnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .IR putprdfnam . .PP Programs using these routines must be compiled with .BR \-lsec . .\" .\" index@\f4getprdfent\f1 \- manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f4getprdfnam\f1 \- manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f4setprdfent\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" index@\f4endprdfent\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" .\" index@\f4putprdfnam\f1 \- manipulate system default database entry@@@\f4getprdfent(3)\f1 .\" index@\f1manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f1manipulate system default database entry@@@\f3getprdfent(3)\f1 .\" index@\f1system default database entry, manipulate@@@\f3getprdfent(3)\f1 .\" index@\f1default database entry, manipulate system@@@\f3getprdfent(3)\f1 .\" index@\f1database entry, manipulate system default@@@\f3getprdfent(3)\f1 .\" index@\f1entry, manipulate system default database@@@\f3getprdfent(3)\f1 .\" .\" toc@\f3getprdfent(3)\f1:\0\0\f4getprdfent\f1, \f4getprdfnam\f1, \f4setprdfent\f1, \f4endprdfent\f1,\n\f4putprdfnam\f1@@@manipulate system default database entry for a trusted system .\" toc@\f4getprdfnam\f1:\0\0search for file@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4setprdfent\f1:\0\0rewind default control files@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4endprdfent\f1:\0\0close system default database@@@\f1see \f3getprdfent(3)\f1 .\" toc@\f4putprdfnam\f1:\0\0put default control entry@@@\f1see \f3getprdfent(3)\f1 .\" .\" links@getprdfent.3 getprdfnam.3 .\" links@getprdfent.3 setprdfent.3 .\" links@getprdfent.3 endprdfent.3 .\" links@getprdfent.3 putprdfnam.3 .\" .\" fileset_database@getprdfent.3 UX-CORE-MAN .\" $Header: getprotoent.3n,v 78.1 96/03/17 09:48:20 ssa Exp $ .TA g .TH getprotoent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprotoent(), getprotoent_r(), getprotobynumber(), getprotobynumber_r(), getprotobyname(), getprotobyname_r(), setprotoent(), setprotoent_r(), endprotoent(), endprotoent_r() \- get protocol entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct protoent *getprotoent(void);" .PP .C "int getprotoent_r(struct protoent *result," .C " struct protoent_data *buffer);" .PP .C "struct protoent *getprotobyname(const char *name);" .PP .C "int getprotobyname_r(const char *name," .C " struct protoent *result," .C " struct protoent_data *buffer);" .PP .C "struct protoent *getprotobynumber(int proto);" .PP .C "int getprotobynumber_r(int proto," .C " struct protoent *result," .C " struct protoent_data *buffer);" .PP .C "int setprotoent(int stayopen);" .PP .C "int setprotoent_r(int stayopen, struct protoent_data *buffer);" .PP .C "int endprotoent(void);" .PP .C "int endprotoent_r(struct protoent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setprotoent(int stayopen);" .C "void endprotoent(void);" .fi .SH DESCRIPTION The .CR getprotoent() , .CR getprotobyname() , and .CR getprotobynumber() functions each return a pointer to a structure of type .I protoent containing the broken-out fields of a line in the network protocol data base, .CR /etc/protocols . .PP The members of this structure are: .RS .TP 15 .CR p_name The official name of the protocol. .TP .CR p_aliases A null-terminated list of alternate names for the protocol. .TP .CR p_proto The protocol number. .RE .PP Functions behave as follows: .RS .TP 26 .CR getprotoent() Reads the next line of the file, opening the file if necessary. .TP .CR setprotoent() Opens and rewinds the file. If the .I stayopen flag is non-zero, the protocol data base is not closed after each call to .CR getprotoent() (either directly or indirectly through one of the other .CR getproto* calls). .TP .CR endprotoent() Closes the file. .TP .CR getprotobyname() .PD 0 .TP .CR getprotobynumber() Each sequentially searches from the beginning of the file until a matching protocol name (among either the official names or the aliases) or protocol number is found, or until EOF is encountered. .PD .PP If the system is running the Network Information Service (NIS) services, .CR getprotobyname() and .CR getprotobynumber() get the protocol information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getprotoent_r() , .CR getprotobyname_r() , and .CR getprotobynumber_r() expect to be passed the address of a .CR "struct protoent" and will store the result at the supplied location. An additional parameter, a pointer to a .CR "struct protoent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct protoent" will point, as well as state information such as open file descriptors. The .CR "struct protoent_data" is defined in the file .CR . .PP .CR setprotoent_r() and .CR endprotoent_r() are to be used only in conjunction with .CR getprotoent_r() and take the same pointer to a .CR "struct protoent_data" as a parameter. If the Network Information Service is being used, .CR setprotoent_r() initializes an internal database key. If the .B /etc/protocols file is being used, .CR setprotoent_r() opens or rewinds the file. .CR endprotoent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setprotoent_r() currently has no effect. However, .CR setprotoent() can still be used to keep the .B /etc/protocols file open when making calls to .CR getprotobyname_r() and .CR getprotobynumber_r() . .PP The .I proto_fp field in the .CR "struct protoent_data" must be initialized to NULL before it is passed to either .CR getprotoent_r() or .CR setprotoent_r() for the first time. Thereafter it should not be modified in any way. This is the only .CR protoent_data field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getprotobyname() , .CR getprotobynumber() , .CR getprotoent() , and their reentrant counterparts, internally call the name service switch to access the "protocols" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve protocol names and numbers. .SH RETURN VALUE .CR getprotoent() , .CR getprotobyname() , and .CR getprotobynumber() return a null pointer (0) on EOF or when they are unable to open .CR /etc/protocols . .PP For the reentrant .RC ( _r ) versions of these routines, .CR -1 will be returned if the operation is unsuccessful or, in the case of .CR getprotoent_r() , if the end of the protocols list has been reached. .CR 0 is returned otherwise. .SH EXAMPLES The following code excerpt counts the number of protocols entries: .RS .nf .PP .C "int count = 0;" .C "struct protoent protobuf;" .C "struct protoent_data pdbuf;" .PP .C "pdbuf.proto_fp = NULL;" .C "(void) setprotoent_r(0, &pdbuf);" .C "while (getprotoent_r(&protobuf, &pdbuf) != -1)" .C " count++;" .C "(void) endprotoent_r(&pdbuf);" .fi .RE .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area so it must be copied if it is to be saved. .PP .CR getprotoent() , .CR getprotobynumber() , .CR getprotobyname() , .CR setprotoent() , and .CR endprotoent() are unsafe in multi-thread applications. .CR getprotoent_r() , .CR getprotobynumber_r() , .CR getprotobyname_r() , .CR setprotoent_r() , and .CR endprotoent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getprotoent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/protocols .SH SEE ALSO ypserv(1M), protocols(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getprotoent() ": XPG4" .\" .\" index@\f1end protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f1entry, get, set, or end protocol@@@\f3getprotoent(3N)\f1 .\" index@\f1get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f1protocol entry, get, set, or end@@@\f3getprotoent(3N)\f1 .\" index@\f1set protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f1thread-safe, get, set, or end protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4endprotoent()\f1 \- end protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4endprotoent_r()\f1 \- end protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobyname()\f1 \- get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobyname_r()\f1 \- get protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobynumber()\f1 \- get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotobynumber_r()\f1 \- get protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotoent()\f1 \- get protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4getprotoent_r()\f1 \- get protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" index@\f4setprotoent()\f1 \- set protocol entry@@@\f3getprotoent(3N)\f1 .\" index@\f4setprotoent_r()\f1 \- set protocol entry (thread-safe)@@@\f3getprotoent(3N)\f1 .\" .\" links@getprotoent.3n endprotoent.3n .\" links@getprotoent.3n getprotobyn.3n .\" links@getprotoent.3n setprotoent.3n .\" .\" toc@\f3getprotoent(3N)\f1:\0\0\f4endprotoent()\f1, \f4endprotoent_r()\f1, \f4getprotobyname()\f1, \f4getprotobyname_r()\f1,\n\f4getprotobynumber()\f1, \f4getprotobynumber_r()\f1, \f4getprotoent()\f1, \f4getprotoent_r()\f1,\n\f4setprotoent()\f1, \f4setprotoent_r()\f1,@@@get, set, or end protocol entry .\" .\" toc@\f4endprotoent()\f1:\0\0end protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4endprotoent_r()\f1:\0\0end protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobyname()\f1:\0\0get protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobyname_r()\f1:\0\0get protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobynumber()\f1:\0\0get protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotobynumber_r()\f1:\0\0get protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4getprotoent_r()\f1:\0\0get protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" toc@\f4setprotoent()\f1:\0\0set protocol entry@@@see \f3getprotoent(3N)\f1 .\" toc@\f4setprotoent_r()\f1:\0\0set protocol entry (thread-safe)@@@see \f3getprotoent(3N)\f1 .\" $Header: getprpwent.3,v 78.3 96/01/19 20:14:34 ssa Exp $ .TA g .TH getprpwent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprpwent, getprpwuid, getprpwnam, getprpwaid, setprpwent, endprpwent, putprpwnam \- manipulate protected password database entry (for trusted systems only) .SH SYNOPSIS .nf .B "#include " .B "#include " .B "#include " .PP .B "struct pr_passwd \(**getprpwent(void);" .PP .B "struct pr_passwd \(**getprpwuid(uid_t uid);" .PP .B "struct pr_passwd \(**getprpwnam(const char \(**name);" \c .PP .B "struct pr_passwd \(**getprpwaid(aid_t aid)" \c .PP .B "void setprpwent(void);" .PP .B "void endprpwent(void);" .PP .B "int putprpwnam(const char \(**name, struct pr_passwd \(**pr);" .fi .SH DESCRIPTION .CR getprpwent (), .CR getprpwuid (), .CR getprpwaid (), and .CR getprpwnam () each returns a pointer to a .C pr_passwd structure containing the broken-out fields of a line in the protected password database. Each line in the database contains a .C pr_passwd structure, declared in the .RC < prot.h > header file: .IP .nf .ift .sp -1v struct pr_field { /\(** Identity: \(**/ char fd_name[9]; /\(** uses 8 character maximum(and NULL) from utmp \(**/ uid_t fd_uid; /\(** uid associated with name above \(**/ char fd_encrypt[xxx]; /\(** encrypted password \(**/ char fd_owner[9]; /\(** if a pseudo-user, the user accountable \(**/ char fd_boot_auth; /\(** boot authorization \(**/ mask_t fd_auditcntl; /\(** reserved \(**/ mask_t audit_reserve1; /\(** reserved \(**/ mask_t fd_auditdisp; /\(** reserved \(**/ mask_t audit_reserve2; /\(** reserved \(**/ aid_t fd_pw_audid; /\(** audit ID \(**/ int fd_pw_audflg; /\(** audit flag \(**/ .IP /\(** Password maintenance parameters: \(**/ time_t fd_min; /\(** minimum time between password changes \(**/ int fd_maxlen; /\(** maximum length of password \(**/ time_t fd_expire; /\(** expiration time duration in secs \(**/ time_t fd_lifetime; /\(** account death duration in seconds \(**/ time_t fd_schange; /\(** last successful change in secs past 1/1/70 \(**/ time_t fd_uchange; /\(** last unsuccessful change \(**/ time_t fd_acct_expire; /\(** absolute account lifetime in seconds \(**/ time_t fd_max_llogin; /\(** max time allowed between logins \(**/ time_t fd_pw_expire_warning; /\(** password expiration warning \(**/ uid_t fd_pswduser; /\(** who can change this user's password \(**/ char fd_pick_pwd; /\(** can user pick his own passwords? \(**/ char fd_gen_pwd; /\(** can user get passwords generated for him? \(**/ char fd_restrict; /\(** should generated passwords be restricted? \(**/ char fd_nullpw; /\(** is user allowed to have a NULL password? \(**/ uid_t fd_pwchanger; /\(** who last changed user's password \(**/ long fd_pw_admin_num;/\(** password generation verifier \(**/ char fd_gen_chars; /\(** can have password of random ASCII? \(**/ char fd_gen_letters; /\(** can have password of random letters? \(**/ char fd_tod[AUTH_TOD_SIZE]; /\(** times when user may login \(**/ .IP /\(** Login parameters: \(**/ time_t fd_slogin; /\(** last successful login \(**/ time_t fd_ulogin; /\(** last unsuccessful login \(**/ char fd_suctty[14]; /\(** tty of last successful login \(**/ short fd_nlogins; /\(** consecutive unsuccessful logins \(**/ char fd_unsuctty[14];/\(** tty of last unsuccessful login \(**/ short fd_max_tries; /\(** maximum unsuc login tries allowed \(**/ char fd_lock; /\(** Unconditionally lock account? \(**/ }; .IP struct pr_flag { unsigned short /\(** Identity: \(**/ fg_name:1, /\(** Is fd_name set? \(**/ fg_uid:1, /\(** Is fd_uid set? \(**/ fg_encrypt:1, /\(** Is fd_encrypt set? \(**/ fg_owner:1, /\(** Is fd_owner set? \(**/ fg_boot_auth:1, /\(** Is fd_boot_auth set? \(**/ fg_pw_audid:1, /\(** Is fd_auditcntl set? \(**/ fg_pw_audflg:1, /\(** Is fd_auditdisp set? \(**/ .IP /\(** Password maintenance parameters: \(**/ fg_min:1, /\(** Is fd_min set? \(**/ fg_maxlen:1, /\(** Is fd_maxlen set? \(**/ fg_expire:1, /\(** Is fd_expire set? \(**/ fg_lifetime:1, /\(** Is fd_lifetime set? \(**/ fg_schange:1, /\(** Is fd_schange set? \(**/ fg_uchange:1, /\(** Is fd_fchange set? \(**/ fg_acct_expire:1, /\(** Is fd_acct_expire set? \(**/ fg_max_llogin:1, /\(** Is fd_max_llogin set? \(**/ fg_pw_expire_warning:1, /\(** Is fd_pw_expire_warning set? \(**/ fg_pswduser:1, /\(** Is fd_pswduser set? \(**/ fg_pick_pwd:1, /\(** Is fd_pick_pwd set? \(**/ fg_gen_pwd:1, /\(** Is fd_gen_pwd set? \(**/ fg_restrict:1, /\(** Is fd_restrict set? \(**/ fg_nullpw:1, /\(** Is fd_nullpw set? \(**/ fg_pwchanger:1, /\(** Is fd_pwchanger set? \(**/ fg_pw_admin_num:1, /\(** Is fd_pw_admin_num set? \(**/ fg_gen_chars:1, /\(** Is fd_gen_chars set? \(**/ fg_gen_letters:1, /\(** Is fd_gen_letters set? \(**/ fg_tod:1, /\(** Is fd_tod set? \(**/ .IP /\(** Login parameters: \(**/ fg_slogin:1, /\(** Is fd_slogin set? \(**/ fg_suctty: 1, /\(** is fd_suctty set ? \(**/ fg_unsuctty: 1, /\(** is fd_unsuctty set ? \(**/ fg_ulogin:1, /\(** Is fd_ulogin set? \(**/ fg_nlogins:1, /\(** Is fd_nlogins set? \(**/ fg_max_tries:1, /\(** Is fd_max_tries set? \(**/ fg_lock:1; /\(** Is fd_lock set? \(**/ }; .IP struct pr_passwd { struct pr_field ufld; /\(** user specific fields \(**/ struct pr_flag uflg; /\(** user specific flags \(**/ struct pr_field sfld; /\(** system wide fields \(**/ struct pr_flag sflg; /\(** system wide flags \(**/ }; .fi .PP The protected password database stores user authentication profiles. The .C pr_passwd structure in the user-specific entry refers to parameters specific to a user. The .C pr_passwd structure in the system default database sets parameters that are used when there is no user-specific override. .PP The user-specific entry is keyed on the .I fd_name field, which is a cross reference to the .C /etc/passwd entry for the user. The .I fd_uid field must match the UID in that file as well. The .I fd_encrypt field is the encrypted password. The password is encrypted in eight character segments, so the size of this field is a multiple of the number of characters in an encrypted segment (\c .C AUTH_CIPHERTEXT_SIZE macro). .PP .I fd_owner is the user name accountable for the account. \c The .I fd_boot_auth field is used when the system default file specifies boot authorization is required. .I init(1M) prompts for a user name and password. If the authentication succeeds, a value in this field allows the user to continue the system boot process. \c .PP .I fd_min is the time, in seconds, that must elapse before the user can change passwords. .I fd_maxlen is the maximum password length (in characters) for the user. .I fd_expire is the time, in seconds, until the user's password expires. .I fd_lifetime is the number of seconds that must elapse before the password dies. The account is considered locked if the password is dead. .PP .I fd_schange and .I fd_uchange record the last successful and unsuccessful password change times. .PP The .I fd_acct_expire field specifies the absolute period of time in seconds that the account can be used. An absolute expiration date may be specified, which is then converted into seconds stored in this field. This is different from .I fd_expire in that .I fd_acct_expire specifies an absolute expiration date, while .I fd_expire is reset with each password change. .PP .I fd_max_llogin specifies the maximum time in seconds allowed since the last login before the account becomes locked. .I fd_pw_expire_warning is the time in seconds before the end of .I fd_expire that the system warns the user the password is about to expire. .I fd_pswduser stores the user ID of the user allowed to change passwords for the account. \c Typically, this is the account owner. \c .PP The next flag fields control password generation. .IR fd_pick_pwd , if set, allows the user to pick his or her own password. .IR fd_nullpw , if set, allows the account to be used without a password. .I fd_gen_pwd enables the use of the random pronounceable password generator for passwords for this account. .I fd_gen_chars and .I fd_gen_letters allow the password generator to generate passwords composed of random printable characters and random letters, neither of which is easy to remember. The password change software allows the user to pick from whichever options are available for his or her account. One of these three fields .RI ( fd_gen_pwd , .IR fd_gen_chars , or .IR fd_gen_letters ) must be set. .PP .I fd_pwchanger is the user ID of the user who last changed the password on the user's account, if it was not the account owner. .IR fd_restrict , if set, causes triviality checks to be made after the account password has been chosen to avoid palindromes, user name and machine name permutations, and words appearing in the dictionary. .PP The .I fd_tod specifier is a string, formatted like the UUCP .C Systems file, which specifies time intervals during which the user can log in. \c .PP The next fields are used to protect against login spoofing, listing the time and location of last login. .I fd_slogin and .I fd_ulogin are time stamps of the last successful and unsuccessful login attempts. .I fd_suctty and .I fd_unsuctty are the terminal device or (if supported) host names of the terminal or host from which the last login attempt occurred. .PP .I fd_nlogins is the number of unsuccessful login attempts since the last successful login. It is reset to zero after a successful login. .I fd_max_tries is the number of unsuccessful attempts until the account is considered locked. .PP .I fd_lock indicates whether the administrative lock on the account is set. The account is considered disabled (locked) if one or more of these activities has occurred: .PD 0 .PP 1. if the password is dead, .PP 2. if the maximum number of unsuccessful attempts has been exceeded, .PP 3. if the administrative lock is set, .PP 4. if the account expiration is reached, or .PP 5. if the time since last login is exceeded. .PD .PP When .CR getprpwent () is first called, it returns a pointer to the first user .C pr_passwd structure in the database; thereafter, it returns a pointer to the next .C pr_passwd structure in the database so that successive calls can be used to search the database. Note that entries without a corresponding entry in .C /etc/passwd are skipped. The entries are scanned in the order they appear in .CR /etc/passwd . .PP .CR getprpwuid () searches from the beginning of the database until a numerical user ID matching .I uid is found and returns a pointer to the particular structure in which it was found. \c .CR getprpwaid () functions like .CR getprpwuid () only it uses the audit ID instead of the uid. \c .PP .CR getprpwnam () searches from the beginning of the database until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a NULL pointer. .PP A call to .CR setprpwent () has the effect of rewinding the protected password database to allow repeated searches. .CR endprpwent () can be called to close the protected password database when processing is complete. .PP .CR putprpwnam () puts a new or replaced protected password entry .I pr with key .I name into the database. If the .I uflg.fg_name field is 0, the requested entry is deleted from the protected password database. .CR putprpwnam () locks the database for all update operations, and performs a .CR endprpwent () after the update or failed attempt. .SS Notes .PP The value returned by .CR getprpwent () and .CR getprpwnam () refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .CR putprpwnam (). .PP On systems supporting network connections, the .I fd_suctty and .I fd_unsuctty fields can be the ASCII representation of the network address of the host from which the last successful or unsuccessful remote login to the account occurred. Use .IR getdvagnam (3) to investigate the type of device to determine whether a host or a terminal was used for the last successful or unsuccessful login. .PP Programs using these routines must be compiled with .CR \-lsec . .PP .CR getprpwent () assumes one name per UID and one UID per name. The sequential scan loops between the first two instances of a multiple UID. .PP .CR getprpwent () uses .IR getpwent (3) routines to sequentially scan databases. User program references to password entries obtained using .IR getpwent (3) routines will not be valid after using any routines described here (ie., the * .CR prp * routines). .SH RETURN VALUE .CR getprpwent (), .CR getprpwuid (), and .CR getprpwnam () return NULL pointers on EOF or error. .CR putprpwnam () returns 0 if it cannot add or update the entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 35 .C /etc/passwd System Password file .PD 0 .TP .C /tcb/files/auth/\(**/\(** Protected Password database .TP .C /tcb/files/auth/system/default System Defaults database .PD .SH SEE ALSO authcap(4), getpwent(3), getprdfent(3), prpwd(4). .\" .\" index@\f4getprpwuid\f1 \- get protected password database user ID@@@\f3getprpwent(3)\f1 .\" index@\f4getprpwaid\f1 \- get protected password database audit ID@@@\f3getprpwent(3)\f1 .\" index@\f4getprpwnam\f1 \- get protected password database user name@@@\f3getprpwent(3)\f1 .\" index@\f4setprpwent\f1 \- set protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f4endprpwent\f1 \- manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f4putprpwnam\f1 \- manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1access protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1manipulate protected password database entry@@@\f3getprpwent(3)\f1 .\" index@\f1protected password database entry, manipulate@@@\f3getprpwent(3)\f1 .\" index@\f1password database entry, manipulate protected@@@\f3getprpwent(3)\f1 .\" index@\f1database entry, manipulate protected password@@@\f3getprpwent(3)\f1 .\" index@\f1entry, manipulate protected password database@@@\f3getprpwent(3)\f1 .\" .\" toc@\f3getprpwent(3)\f1:\0\0\f4getprpwent\f1, \f4getprpwuid\f1, \f4getprpwnam\f1, \f4getprpwaid\f1, \f4setprpwent\f1,\n\f4endprpwent\f1, \f4putprpwnam\f1@@@manipulate protected password database entry .\" toc@\f4getprpwuid\f1:\0\0get protected password database user ID@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4getprpwaid\f1:\0\0get protected password database audit ID@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4getprpwnam\f1:\0\0get protected password database user name@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4setprpwent\f1:\0\0set protected password database entry@@@\f1 see \f3getprpwent(3)\f1 .\" toc@\f4endprpwent\f1:\0\0manipulate protected password database entry@@@\f1see \f3getprpwent(3)\f1 .\" toc@\f4putprpwnam\f1:\0\0manipulate protected password database entry@@@\f1 see \f3getprpwent(3)\f1 .\" .\" links@getprpwent.3 getprpwuid.3 .\" links@getprpwent.3 getprpwnam.3 .\" links@getprpwent.3 setprpwent.3 .\" links@getprpwent.3 endprpwent.3 .\" links@getprpwent.3 putprpwnam.3 .\" links@getprpwent.3 getprpwaid.3 .\" .\" $Header: getprtcent.3,v 78.2 96/01/19 20:15:15 ssa Exp $ .TA g .TH getprtcent 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getprtcent, getprtcnam, setprtcent, endprtcent, putprtcnam \- manipulate terminal control database entry for a trusted system .SH SYNOPSIS .nf .CR "#include " .CR "#include " .CR "#include " .PP .CR "struct pr_term \(**getprtcent(void);" .PP .CR "struct pr_term \(**getprtcnam(const char \(**name);" .PP .CR "void setprtcent(void);" .PP .CR "void endprtcent(void);" .PP .CR "int putprtcnam(const char \(**name, struct pr_term \(**pr);" .fi .SH DESCRIPTION .IR getprtcent and .I getprtcnam each returns a pointer to an object with the following structure containing the broken-out fields of an entry in the terminal control database. Each entry in the database contains a .I pr_term structure, declared in the .RB < prot.h > header file: .IP .nf .ift .sp -1v .ift .ta 2i .ifn .ta 3i .ne 15 struct t_field { char fd_devname[14]; /* Terminal (or host) name */ uid_t fd_uid; /* uid of last successful login */ time_t fd_slogin; /* time stamp of successful login */ uid_t fd_uuid; /* uid of last unsuccessful login */ time_t fd_ulogin; /* time stamp of unsuccessful login */ ushort fd_nlogins; /* consecutive failed attempts */ ushort fd_max_tries; /* maximum unsuc login tries allowed */ time_t fd_logdelay; /* delay between login tries */ char fd_lock; /* terminal locked? */ ushort fd_login_timeout ; /* login timeout in seconds */ }; .IP .ne 17 struct t_flag { unsigned short fg_devname:1, /* Is fd_devname set? */ fg_uid:1, /* Is fd_uid set? */ fg_slogin:1, /* Is fd_stime set? */ fg_uuid:1, /* Is fd_uuid set? */ fg_ulogin:1, /* Is fd_ftime set? */ fg_nlogins:1, /* Is fd_nlogins set? */ fg_max_tries:1, /* Is fd_max_tries set? */ fg_logdelay:1, /* Is fd_logdelay set? */ fg_lock:1, /* Is fd_lock set? */ fg_login_timeout:1 /* is fd_login_timeout valid? */ ; }; .IP .ne 6 struct pr_term { struct t_field ufld; struct t_flag uflg; struct t_field sfld; struct t_flag sflg; }; .fi .DT .PP The system stores the user ID and time of the last successful login ( .I fd_uid and .I fd_slogin ) and unsuccessful login ( .I fd_uuid and .I fd_ulogin ) in the appropriate Terminal Control database entry. The system increments .I fd_nlogins with each unsuccessful login, and resets the field to 0 on a successful login. The .I fd_max_tries field is a limit on the number of unsuccessful logins until the account is locked. An administrative lock can also be applied, indicated by a non-zero .I fd_lock field. .I fd_logdelay stores the amount of time (in seconds) that the system waits between unsuccessful login attempts, and .I fd_login_timeout stores the number of seconds from the beginning of an authentication attempt until the login attempt is terminated. .PP Note that .I ufld and .I uflg refer to user specific entries, and .I sfld and .I sflg refer to the system default values (see .IR authcap (4)). .PP The value returned by .I getprtcent or .I getprtcnam refers to a structure that is overwritten by calls to these routines. To retrieve an entry, modify it, and replace it in the database, copy the entry using structure assignment and supply the modified buffer to .IR putprtcnam . .PP .I getprtcent returns a pointer to the first terminal .I pr_term structure in the database when first called. Thereafter, it returns a pointer to the next .I pr_term structure in the database, so successive calls can be used to search the database. .I getprtcnam searches from the beginning of the database until a terminal name matching .I name is found, and returns a pointer to the particular structure in which it was found. If an end-of-file or an error is encountered on reading, these functions return a .B NULL pointer. .PP A call to .I setprtcent has the effect of rewinding the Terminal Control database to allow repeated searches. .I endprtcent can be called to close the Terminal Control database when processing is complete. .PP .I putprtcnam puts a new or replaced terminal control entry .I pr with key .I name into the database. If the .I fg_devname field is 0, the requested entry is deleted from the Terminal Control database. .I putprtcnam locks the database for all update operations, and performs an .I endprtcent after the update or failed attempt. .SH RETURN VALUE .I getprtcent and .I getprtcnam return .SM .B NULL pointers on .SM EOF or error. .I putprtcnam returns 0 if it cannot add or update the entry. .SH AUTHOR SecureWare Inc. .SH FILES .TP 45 .C /tcb/files/ttys Terminal Control database .PD 0 .TP .C /tcb/files/auth/system/default System Defaults database .PD .SH SEE ALSO getprdfent(3), authcap(4), ttys(4). .SH NOTES The .I fd_devname field, on systems supporting connections, may refer to the .SM ASCII representation of a host name. This can be determined by using .IR getdvagnam (3) to interrogate the Device Assignment database as to the type of the device, passing in the .I fd_devname field of the Terminal Control structure as an argument. This allows lockout by machine, instead of the device (typically pseudo tty) on which the session originated. .PP Programs using these routines must be compiled with .BR \-lsec . .PP The .I sfld and .I sflg structures are filled from corresponding fields in the system default database. Thus, a program can easily extract the user-specific or system-wide parameters for each database field (see .I getprpwent and .IR getdvagent ). .\" .\" index@\f4getprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4getprtcnam\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4setprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4endprtcent\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f4putprtcnam\f1 \- manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f1manipulate terminal control database entry@@@\f3getprtcent(3)\f1 .\" index@\f1terminal control database entry, manipulate@@@\f3getprtcent(3)\f1 .\" index@\f1database entry, manipulate terminal control@@@\f3getprtcent(3)\f1 .\" index@\f1entry, manipulate terminal control database@@@\f3getprtcent(3)\f1 .\" .\" toc@\f3getprtcent(3)\f1:\0\0\f4getprtcent\f1, \f4getprtcnam\f1, \f4setprtcent\f1, \f4endprtcent\f1,\n\f4putprtcnam\f1@@@manipulate terminal control database entry for a trusted system .\" toc@\f4getprtcent\f1:\0\0return pointer to terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc \f4getprtcnam\f1:\0\0search terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4setprtcent\f1:\0\0rewind terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4endprtcent\f1:\0\0close terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" toc@\f4putprtcnam\f1:\0\0put entry into terminal control database@@@\f1see \f3getprtcent(3)\f1 .\" .\" links@getprtcent.3 getprtcnam.3 .\" links@getprtcent.3 setprtcent.3 .\" links@getprtcent.3 endprtcent.3 .\" links@getprtcent.3 putprtcnam.3 .\" .\" $Header: getpwent.3c,v 78.1 95/12/20 10:53:01 ssa Exp $ .TA g .TH getpwent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpwent(\|), getpwent_r(\|), getpwuid(\|), getpwuid_r(\|), getpwnam(\|), getpwnam_r(\|), setpwent(\|), setpwent_r(\|), endpwent(\|), endpwent_r(\|), fgetpwent(\|), fgetpwent_r(\|) \- get password file entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct passwd *getpwent(void);" .PP .C "int getpwent_r(struct passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct passwd *getpwuid(uid_t uid);" .PP .PD 0 .C "int getpwuid_r(uid_t uid, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct passwd *getpwnam(const char *name);" .PP .PD 0 .C "int getpwnam_r(char *name, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setpwent(void);" .PP .C "void setpwent_r(FILE **pwfp);" .PP .C "void endpwent(void);" .PP .C "void endpwent_r(FILE **pwfp);" .PP .C "struct passwd *fgetpwent(FILE *stream);" .PP .C "int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, int buflen);" .fi .SH DESCRIPTION .CR getpwent (), .CR getpwuid (), and .CR getpwnam () locate an entry in the .C /etc/passwd file, and return a pointer to an object of .C passwd structure. .PP The .C passwd structure is defined in .RC < pwd.h > and includes the following members: .nf .IP .CR "char *pw_name; " "/* user name */" .CR "char *pw_passwd; " "/* encrypted password */" .CR "uid_t pw_uid; " "/* user id */" .CR "gid_t pw_gid; " "/* group id */" .CR "char *pw_age; " "/* password aging */" .CR "char *pw_comment;" "/* unused */" .CR "char *pw_gecos; " "/* user fullname, office, extension, homephone*/" .CR "char *pw_dir; " "/* initial directory */" .CR "char *pw_shell; " "/* initial shell */" .CR "aid_t pw_audid; " "/* numerical audit id */" .CR "int pw_audflg; " "/* numerical audit flag */" .fi .PP The .I pw_comment field is unused; for more information on the other fields, refer to .IR passwd (4). .TP 20 .CR getpwent () When first called, .CR getpwent () returns a pointer to the first .C passwd structure in the file. Thereafter, it returns a pointer to the next .C passwd structure in the file. In this way, successive calls can be used to search the entire file. .CR getpwent () opens the .C /etc/passwd file prior to doing its work and leaves the file open afterward; .TP .CR setpwent () Has the effect of rewinding this file to allow repeated searches; .TP .CR endpwent () Can be called to close the file when processing is complete. .TP .CR getpwuid () Searches from the beginning of the file until a numeric user .SM ID matching .I uid is found, and returns a pointer to the particular structure in which it was found. .TP .CR getpwnam () searches from the beginning of the file until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .CR fgetpwent () returns a pointer to the next .C passwd structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/passwd . .SS Reentrant Interfaces .CR getpwuid_r (), .CR getpwnam_r () and .CR fgetpwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .C passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in .C passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getpwent_r () requires a pointer to a .RI ( "FILE *" ) variable into which is stored the result of an .CR fopen () call on the .C /etc/passwd file. This is to allow threads to independently scan through the .C /etc/passwd file. .CR setpwent_r () and .CR endpwent_r () are to be used only in conjunction with .CR getpwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setpwent_r () can be used to rewind or open the .C /etc/passwd file. .CR endpwent_r () must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getpwent_r () or .CR setpwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH SECURITY FEATURES If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default .CR * that is in .C /etc/passwd and the audit ID and audit flag will be set to \(mi1. On trusted systems, if it is not necessary to obtain information from the regular password file, .CR /etc/passwd , users should use .CR getprpwent () to access the protected password database. See .IR getprpwent (3) and .IR getspwent (3X). .PP .CR putpwent () affects only .CR /etc/passwd ; the audit .SM ID and audit flag in the password structure are ignored. .CR putprpwnam () must be used to modify the protected password databse entries. See .IR getprpwent (3). .SH NETWORKING FEATURES .SS \s-1NFS\s0 If an entry beginning with a plus sign .RC ( + ) or a minus sign .RB ( \(mi ) is found, these routines try to use the Network Information Service network database for data. See .IR passwd (4) for proper syntax and operation. .PP Network Information Service (NIS) is not supported on trusted systems. .SH RETURN VALUE .CR getpwent (), .CR getpwuid (), .CR getpwnam (), and .CR fgetpwent () return a .SM NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .C passwd structure. .PP .CR getpwent_r (), .CR getpwuid_r (), .CR getpwnam_r (), and .CR fgetpwent_r (), return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getpwent() , .CR getpwuid() , and .CR fgetpwent() fail if any of the following are true: .RS .TP 15 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library, which causes them to increase the size of programs, not otherwise using standard .SM I/O and Network Information Service, more than might be expected. .PP The value returned by .CR getpwent() , .CR getpwuid() , .CR getpwnam() , and .C fgetpwent() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved. .PP .CR getpwent() , .CR getpwuid() , .CR getpwnam() , .CR setpwent() , .CR endpwent() , and .C fgetpwent() are unsafe in multi-thread applications. .CR getpwent_r() , .CR getpwuid_r() , .CR getpwnam_r() , .CR setpwent_r() , .CR endpwent_r() , and .C fgetpwent_r() are MT-Safe and should be used instead. .PP The following fields have numerical limitations as noted: .RS .TP 3 \(bu The user ID is an integer value between -2 and UID_MAX inclusive. .TP \(bu The group ID is an integer value between 0 and UID_MAX inclusive. .RE .PP Users of .CR getpwnam_r() and .CR getpwuid_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH EXAMPLE The following code excerpt counts the number of entries in the .C /etc/passwd file: .PP .nf .IP .C "int count = 0;" .C "struct passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setpwent_r(&pwf);" .C "while (getpwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endpwent_r(&pwf);" .fi .SH DEPENDENCIES .SS \s-1NFS\s0 .B Files: .RS .CI /var/yp/ domainname /passwd.byname .br .CI /var/yp/ domainname /passwd.byuid .RE .PP .B See Also: .RS ypcat(1). .RE .SH AUTHOR .CR getpwent (), .CR getpwuid (), .CR getpwnam (), .CR setpwent (), .CR endpwent (), and .CR fgetpwent () were developed by AT&T and HP. .SH FILES .TP 30 .C /etc/passwd System Password file .SH SEE ALSO ypcat(1), cuserid(3S), getgrent(3C), getlogin(3C), getprpwent(3), getspwent(3X), stdio(3S), putpwent(3C), putspwent(3X), passwd(4), limits(5). .SH STANDARDS CONFORMANCE .CR getpwent() ": SVID2, SVID3, XPG2" .PP .CR endpwent() ": SVID2, SVID3, XPG2" .PP .CR fgetpwent() ": SVID2, SVID3, XPG2" .PP .CR getpwnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpwuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setpwent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getpwent()\f1 \- get next password file entry@@@\f3getpwent(3C)\f1 .\" index@\f4fgetpwent()\f1 \- get next entry in password-file-formatted input stream@@@\f3getpwent(3C)\f1 .\" index@\f4getpwuid()\f1 \- get password file entry matching \f4uid()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4getpwnam()\f1 \- get password file entry matching login name \f4name()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4setpwent()\f1 \- rewind pointer to beginning of password file@@@\f3getpwent(3C)\f1 .\" index@\f4endpwent()\f1 \- close currently open password file@@@\f3getpwent(3C)\f1 .\" index@entry from password file, get@@@\f3getpwent(3C)\f1 .\" index@password file, get entry from@@@\f3getpwent(3C)\f1 .\" index@file, password: get entry from password file@@@\f3getpwent(3C)\f1 .\" .\" toc@\f3getpwent(3C)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f , \f4endpwent()\f1, \n\f4fgetpwent()\f1@@@get password file entry .\" toc@\f4getpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4setpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4endpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" .\" links@getpwent.3c getpwuid.3c .\" links@getpwent.3c getpwnam.3c .\" links@getpwent.3c setpwent.3c .\" links@getpwent.3c endpwent.3c .\" links@getpwent.3c fgetpwent.3c .\" links@getpwent.3c getpwent_r.3c .\" links@getpwent.3c getpwuid_r.3c .\" links@getpwent.3c getpwnam_r.3c .\" links@getpwent.3c setpwent_r.3c .\" links@getpwent.3c endpwent_r.3c .\" links@getpwent.3c fgetpwent_r.3c .\" .\" fileset_database@getpwent.3c PROGRAMING-MAN .\" $Header: getpwent.3c,v 78.1 95/12/20 10:53:01 ssa Exp $ .TA g .TH getpwent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getpwent(\|), getpwent_r(\|), getpwuid(\|), getpwuid_r(\|), getpwnam(\|), getpwnam_r(\|), setpwent(\|), setpwent_r(\|), endpwent(\|), endpwent_r(\|), fgetpwent(\|), fgetpwent_r(\|) \- get password file entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct passwd *getpwent(void);" .PP .C "int getpwent_r(struct passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct passwd *getpwuid(uid_t uid);" .PP .PD 0 .C "int getpwuid_r(uid_t uid, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct passwd *getpwnam(const char *name);" .PP .PD 0 .C "int getpwnam_r(char *name, struct passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setpwent(void);" .PP .C "void setpwent_r(FILE **pwfp);" .PP .C "void endpwent(void);" .PP .C "void endpwent_r(FILE **pwfp);" .PP .C "struct passwd *fgetpwent(FILE *stream);" .PP .C "int fgetpwent_r(FILE *f, struct passwd *result, char *buffer, int buflen);" .fi .SH DESCRIPTION .CR getpwent (), .CR getpwuid (), and .CR getpwnam () locate an entry in the .C /etc/passwd file, and return a pointer to an object of .C passwd structure. .PP The .C passwd structure is defined in .RC < pwd.h > and includes the following members: .nf .IP .CR "char *pw_name; " "/* user name */" .CR "char *pw_passwd; " "/* encrypted password */" .CR "uid_t pw_uid; " "/* user id */" .CR "gid_t pw_gid; " "/* group id */" .CR "char *pw_age; " "/* password aging */" .CR "char *pw_comment;" "/* unused */" .CR "char *pw_gecos; " "/* user fullname, office, extension, homephone*/" .CR "char *pw_dir; " "/* initial directory */" .CR "char *pw_shell; " "/* initial shell */" .CR "aid_t pw_audid; " "/* numerical audit id */" .CR "int pw_audflg; " "/* numerical audit flag */" .fi .PP The .I pw_comment field is unused; for more information on the other fields, refer to .IR passwd (4). .TP 20 .CR getpwent () When first called, .CR getpwent () returns a pointer to the first .C passwd structure in the file. Thereafter, it returns a pointer to the next .C passwd structure in the file. In this way, successive calls can be used to search the entire file. .CR getpwent () opens the .C /etc/passwd file prior to doing its work and leaves the file open afterward; .TP .CR setpwent () Has the effect of rewinding this file to allow repeated searches; .TP .CR endpwent () Can be called to close the file when processing is complete. .TP .CR getpwuid () Searches from the beginning of the file until a numeric user .SM ID matching .I uid is found, and returns a pointer to the particular structure in which it was found. .TP .CR getpwnam () searches from the beginning of the file until a login name matching .I name is found, and returns a pointer to the particular structure in which it was found. .TP .CR fgetpwent () returns a pointer to the next .C passwd structure in the standard I/O stream .IR stream , which should be open for reading, and its contents should match the format of .CR /etc/passwd . .SS Reentrant Interfaces .CR getpwuid_r (), .CR getpwnam_r () and .CR fgetpwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .C passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in .C passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getpwent_r () requires a pointer to a .RI ( "FILE *" ) variable into which is stored the result of an .CR fopen () call on the .C /etc/passwd file. This is to allow threads to independently scan through the .C /etc/passwd file. .CR setpwent_r () and .CR endpwent_r () are to be used only in conjunction with .CR getpwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setpwent_r () can be used to rewind or open the .C /etc/passwd file. .CR endpwent_r () must be called when done to close the file and release memory associated with that instance of the opened file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getpwent_r () or .CR setpwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH SECURITY FEATURES If the system has been converted to a trusted system, the password, audit ID, and audit flag are not returned. The password will be the default .CR * that is in .C /etc/passwd and the audit ID and audit flag will be set to \(mi1. On trusted systems, if it is not necessary to obtain information from the regular password file, .CR /etc/passwd , users should use .CR getprpwent () to access the protected password database. See .IR getprpwent (3) and .IR getspwent (3X). .PP .CR putpwent () affects only .CR /etc/passwd ; the audit .SM ID and audit flag in the password structure are ignored. .CR putprpwnam () must be used to modify the protected password databse entries. See .IR getprpwent (3). .SH NETWORKING FEATURES .SS \s-1NFS\s0 If an entry beginning with a plus sign .RC ( + ) or a minus sign .RB ( \(mi ) is found, these routines try to use the Network Information Service network database for data. See .IR passwd (4) for proper syntax and operation. .PP Network Information Service (NIS) is not supported on trusted systems. .SH RETURN VALUE .CR getpwent (), .CR getpwuid (), .CR getpwnam (), and .CR fgetpwent () return a .SM NULL pointer if an end-of-file or error is encountered on reading. Otherwise, the return value points to an internal static area containing a valid .C passwd structure. .PP .CR getpwent_r (), .CR getpwuid_r (), .CR getpwnam_r (), and .CR fgetpwent_r (), return a -1 if the end-of-file or error is encountered, or if the supplied buffer is of insufficient length. If the operation is successful, 0 is returned. .SH ERRORS .CR getpwent() , .CR getpwuid() , and .CR fgetpwent() fail if any of the following are true: .RS .TP 15 [EIO] An I/O error has occurred. .TP [EMFILE] .IR OPEN_MAX descriptors are currently open in the calling process. .TP [ENFILE] The maximum allowable number of files is currently open in the system. .RE .SH WARNINGS The above routines use .RC < stdio.h > and the Network Information Service library, which causes them to increase the size of programs, not otherwise using standard .SM I/O and Network Information Service, more than might be expected. .PP The value returned by .CR getpwent() , .CR getpwuid() , .CR getpwnam() , and .C fgetpwent() points to a single static area that is overwritten by each call to any of the functions, so it must be copied if it is to be saved. .PP .CR getpwent() , .CR getpwuid() , .CR getpwnam() , .CR setpwent() , .CR endpwent() , and .C fgetpwent() are unsafe in multi-thread applications. .CR getpwent_r() , .CR getpwuid_r() , .CR getpwnam_r() , .CR setpwent_r() , .CR endpwent_r() , and .C fgetpwent_r() are MT-Safe and should be used instead. .PP The following fields have numerical limitations as noted: .RS .TP 3 \(bu The user ID is an integer value between -2 and UID_MAX inclusive. .TP \(bu The group ID is an integer value between 0 and UID_MAX inclusive. .RE .PP Users of .CR getpwnam_r() and .CR getpwuid_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .SH EXAMPLE The following code excerpt counts the number of entries in the .C /etc/passwd file: .PP .nf .IP .C "int count = 0;" .C "struct passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setpwent_r(&pwf);" .C "while (getpwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endpwent_r(&pwf);" .fi .SH DEPENDENCIES .SS \s-1NFS\s0 .B Files: .RS .CI /var/yp/ domainname /passwd.byname .br .CI /var/yp/ domainname /passwd.byuid .RE .PP .B See Also: .RS ypcat(1). .RE .SH AUTHOR .CR getpwent (), .CR getpwuid (), .CR getpwnam (), .CR setpwent (), .CR endpwent (), and .CR fgetpwent () were developed by AT&T and HP. .SH FILES .TP 30 .C /etc/passwd System Password file .SH SEE ALSO ypcat(1), cuserid(3S), getgrent(3C), getlogin(3C), getprpwent(3), getspwent(3X), stdio(3S), putpwent(3C), putspwent(3X), passwd(4), limits(5). .SH STANDARDS CONFORMANCE .CR getpwent() ": SVID2, SVID3, XPG2" .PP .CR endpwent() ": SVID2, SVID3, XPG2" .PP .CR fgetpwent() ": SVID2, SVID3, XPG2" .PP .CR getpwnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR getpwuid() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR setpwent() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getpwent()\f1 \- get next password file entry@@@\f3getpwent(3C)\f1 .\" index@\f4fgetpwent()\f1 \- get next entry in password-file-formatted input stream@@@\f3getpwent(3C)\f1 .\" index@\f4getpwuid()\f1 \- get password file entry matching \f4uid()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4getpwnam()\f1 \- get password file entry matching login name \f4name()\f1@@@\f3getpwent(3C)\f1 .\" index@\f4setpwent()\f1 \- rewind pointer to beginning of password file@@@\f3getpwent(3C)\f1 .\" index@\f4endpwent()\f1 \- close currently open password file@@@\f3getpwent(3C)\f1 .\" index@entry from password file, get@@@\f3getpwent(3C)\f1 .\" index@password file, get entry from@@@\f3getpwent(3C)\f1 .\" index@file, password: get entry from password file@@@\f3getpwent(3C)\f1 .\" .\" toc@\f3getpwent(3C)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f , \f4endpwent()\f1, \n\f4fgetpwent()\f1@@@get password file entry .\" toc@\f4getpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4setpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4endpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get password file entry@@@see \f3getpwent(3C)\f1 .\" .\" links@getpwent.3c getpwuid.3c .\" links@getpwent.3c getpwnam.3c .\" links@getpwent.3c setpwent.3c .\" links@getpwent.3c endpwent.3c .\" links@getpwent.3c fgetpwent.3c .\" links@getpwent.3c getpwent_r.3c .\" links@getpwent.3c getpwuid_r.3c .\" links@getpwent.3c getpwnam_r.3c .\" links@getpwent.3c setpwent_r.3c .\" links@getpwent.3c endpwent_r.3c .\" links@getpwent.3c fgetpwent_r.3c .\" .\" fileset_database@getpwent.3c PROGRAMING-MAN .\" $Header: clearok.3x,v 76.2 95/07/31 17:25:47 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH clearok 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clearok, idlok, leaveok, scrollok, setscrreg, wsetscrreg \(em terminal output control functions .SH SYNOPSIS .C "#include " .P .C "int clearok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int idlok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int leaveok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int scrollok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int setscrreg(int \f2top\fP, int \f2bot\fP);" .P .C "int wsetscrreg(WINDOW *\f2win\fP, int \f2top\fP, int \f2bot\fP);" .SH DESCRIPTION These functions set options that deal with output within Curses. .P The .Fn clearok function assigns the value of .I bf to an internal flag in the specified window that governs clearing of the screen during a refresh. If, during a refresh operation on the specified window, the flag in .I curscr is TRUE or the flag in the specified window is TRUE, then the implementation clears the screen, redraws it in its entirety, and sets the flag to FALSE in .I curscr and in the specified window. The initial state is unspecified. .P The .Fn idlok function specifies whether the implementation may use the hardware insert-line, delete-line, and scroll features of terminals so equipped. If \f2bf\f1 is TRUE, use of these features is enabled. If \f2bf\f1 is FALSE, use of these features is disabled and lines are instead redrawn as required. The initial state is FALSE. .P The .Fn leaveok function controls the cursor position after a refresh operation. If \f2bf\f1 is TRUE, refresh operations on the specified window may leave the terminal's cursor at an arbitrary position. If \f2bf\f1 is FALSE, then at the end of any refresh operation, the terminal's cursor is positioned at the cursor position contained in the specified window. The initial state is FALSE. .P The .Fn scrollok function controls the use of scrolling. If \f2bf\f1 is TRUE, then scrolling is enabled for the specified window, with the consequences discussed in \f3Truncation, Wrapping and Scrolling\f1 in curses_intro. If \f2bf\f1 is FALSE, scrolling is disabled for the specified window. The initial state is FALSE. .P The .Fn setscrreg and .Fn wsetscrreg functions define a software scrolling region in the current or specified window. The \f2top\f1 and \f2bot\f1 arguments are the line numbers of the first and last line defining the scrolling region. (Line 0 is the top line of the window.) If this option and .Fn scrollok are enabled, an attempt to move off the last line of the margin causes all lines in the scrolling region to scroll one line in the direction of the first line. Only characters in the window are scrolled. If a software scrolling region is set and .Fn scrollok is not enabled, an attempt to move off the last line of the margin does not reposition any lines in the scrolling region. .SH "RETURN VALUE" Upon successful completion, .Fn setscrreg and .Fn wsetscrreg return OK. Otherwise, they return ERR. .P The other functions always return OK. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The only reason to enable the .Fn idlok feature is to use scrolling to achieve the visual effect of motion of a partial window, such as for a screen editor. In other cases, the feature can be visually annoying. .P The .Fn leaveok option provides greater efficiency for applications that do not use the cursor. .SH "SEE ALSO" clear(), delscreen(), doupdate(), scrl(), . .SS "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .CR idlok() , .CR leaveok() , .CR scrollok() , .Fn setscrreq and .Fn wsetscrreq functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The .B DESCRIPTION of .Fn clearok is updated to indicate that clearing of a screen applies if the flag is TRUE in either \f2curscr\f1 or the specified window. .P The .B "RETURN VALUE" is changed to indicate that the .CR clearok() , .Fn leaveok and .Fn scrollok functions always return OK. .\" .\" toc@\f3clearok(3X)\f1:\0\0\f4clearok()\f1, \f4idleok()\f1, \f4leaveok()\f1, \f4scrollok()\f1, \f4setscrreg()\f1, \f4wsetscrreg()\f1\n@@@terminal output control functions .\" toc@\f4idleok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4leaveok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4scrollok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4setscrreg()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4wsetscrreg()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" index@\f4clearok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4idleok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4leaveok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4scrollok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4setscrreg()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4wsetscrreg()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f1terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f1output, terminal, control functions@@@\f3clearok(3X)\f1 .\" index@\f1control functions, terminal output@@@\f3clearok(3X)\f1 .\" .\" links@clearok.3x idleok.3x .\" links@clearok.3x leaveok.3x .\" links@clearok.3x scrollok.3x .\" links@clearok.3x setscrreg.3x .\" links@clearok.3x wsetscrreg.3x .\" .\" fileset_database@clearok.3x CURS-ENG-A-MAN .\" $Header: getservent.3n,v 78.1 96/03/15 15:57:56 ssa Exp $ .TA g .TH getservent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getservent(), getservent_r(), getservbyport(), getservbyport_r(), getservbyname(), getservbyname_r(), setservent(), setservent_r(), endservent(), endservent_r() \- get service entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct servent *getservent(void);" .PP .C "int getservent_r(struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyname(const char *name, .C " const char *proto);" .PP .C "int getservbyname_r(const char *name," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyport(int port, const char *proto);" .PP .C "int getservbyport_r(int port," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PD .PP .C "int setservent(int stayopen);" .PP .C "int setservent_r(int stayopen, struct servent_data *buffer);" .PP .C "int endservent(void);" .PP .C "int endservent_r(struct servent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setservent(int stayopen);" .C "void endservent(void);" .fi .SH DESCRIPTION The .CR getservent() , .CR getservbyname() , and .CR getservbyport() functions each return a pointer to a structure of type .I servent containing the broken-out fields of a line in the network services data base, .CR /etc/services . .PP The members of this structure are: .RS .TP 15 .CR s_name The official name of the service. .TP .CR s_aliases A null-terminated list of alternate names for the service. .TP .CR s_port The port number at which the service resides. .TP .CR s_proto The name of the protocol to use when contacting the service. .RE .PP Functions behave as follows: .RS .TP 25 .CR getservent() Reads the next line of the file, opening the file if necessary. .TP .CR setservent() Opens and rewinds the file. If the .I stayopen flag is non-zero, the services data base is not closed after each call to .CR getservent() (either directly or indirectly through one of the other .CR getserv* calls). .TP .CR endservent() Closes the file. .TP .CR getservbyname() .PD 0 .TP .CR getservbyport() Each sequentially searches from the beginning of the file until a matching service name (among either the official names or the aliases) or port number is found, or until EOF is encountered. If a non-NULL protocol name is also supplied (such as .CR tcp or .CR udp ), searches must also match the protocol. .PD .IP If the system is running the Network Information Service (NIS), .CR getservbyname() gets the service information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getservent_r() , .CR getservbyname_r() , and .CR getservbyport_r() expect to be passed the address of a .CR "struct servent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct servent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct servent" will point, as well as state information such as open file descriptors. The .CR "struct servent_data" is defined in the file .CR . .PP .CR setservent_r() and .CR endservent_r() are to be used only in conjunction with .CR getservent_r() and take the same pointer to a .CR "struct servent_data" as a parameter. If the Network Information Service is being used, .CR setservent_r() initializes an internal database key. If the .CR /etc/services file is being used, .CR setservent_r() opens or rewinds the file. .CR endservent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setservent_r() currently has no effect. However, .CR setservent() can still be used to keep the .B /etc/services file open when making calls to .CR getservbyname_r() and .CR getservbyport_r() . .PP The .I serv_fp field in the .CR "servent_data struct" must be initialized to NULL before it is passed to either .CR getservent_r() or .CR setservent_r() for the first time. Thereafter it should not be modified in any way. This is the only .CR "servent_data" field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getservbyname() , .CR getservbyport() , .CR getservent() , and their reentrant counterparts, internally call the name service switch to access the "services" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve service names and ports. .SH RETURN VALUE .CR getservent() , .CR getservbyname() , and .CR getservbyport() return a null pointer (0) on EOF or when they are unable to open .CR /etc/services . .PP The reentrant .RC ( _r ) versions of these routines return .CR -1 if the operation is unsuccessful or, in the case of .CR getservent_r() , if the end of the services list has been reached. .CR 0 is returned otherwise. .SH EXAMPLES The following code excerpt counts the number of service entries: .RS .nf .PP .C "int count = 0;" .C "struct servent servbuf;" .C "struct servent_data sdbuf;" .PP .C "sdbuf.serv_fp = NULL;" .C "(void) setservent_r(0, &sdbuf);" .C "while (getservent_r(&servbuf, &sdbuf) != -1)" .C " count++;" .C "(void) endservent_r(&sdbuf);" .fi .RE .SH WARNINGS In the nonreentrant versions of these routines, all information is contained in a static area, so it must be copied if it is to be saved. .PP .CR getservent() , .CR getservbyport() , .CR getservbyname() , .CR setservent() , and .CR endservent() are unsafe in multi-thread applications. .CR getservent_r() , .CR getservbyport_r() , .CR getservbyname_r() , .CR setservent_r() , and .CR endservent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getservent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/services .SH SEE ALSO ypserv(1M), services(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getservent() ": XPG4" .\" .\" index@\f1end service entry@@@\f3getservent(3N)\f1 .\" index@\f1entry, get, set, or end service@@@\f3getservent(3N)\f1 .\" index@\f1get service entry@@@\f3getservent(3N)\f1 .\" index@\f1service entry, get, set, or end@@@\f3getservent(3N)\f1 .\" index@\f1set service entry@@@\f3getservent(3N)\f1 .\" index@\f1thread-safe, get, set, or end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent()\f1 \- end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent_r()\f1 \- end service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservent()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservent_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4setservent()\f1 \- set service entry@@@\f3getservent(3N)\f1 .\" index@\f4setservent_r()\f1 \- set service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" .\" links@getservent.3n endservent.3n .\" links@getservent.3n endservent_.3n .\" links@getservent.3n getservbyna.3n .\" links@getservent.3n getservbypo.3n .\" links@getservent.3n getservent_.3n .\" links@getservent.3n setservent.3n .\" links@getservent.3n setservent_.3n .\" .\" toc@\f3getservent(3N)\f1:\0\0\f4endservent()\f1, \f4endservent_r()\f1, \f4getservbyname()\f1, \f4getservbyname_r()\f1,\n\f4getservbyport()\f1, \f4getservbyport_r()\f1, \f4getservent()\f1, \f4getservent_r()\f1,\n\f4setservent()\f1, \f4setservent_r()\f1@@@get, set, or end service entry .\" .\" toc@\f4endservent()\f1:\0\0end service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4endservent_r()\f1:\0\0end service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent()\f1:\0\0set service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent_r()\f1:\0\0set service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" $Header: getservent.3n,v 78.1 96/03/15 15:57:56 ssa Exp $ .TA g .TH getservent 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getservent(), getservent_r(), getservbyport(), getservbyport_r(), getservbyname(), getservbyname_r(), setservent(), setservent_r(), endservent(), endservent_r() \- get service entry .SH SYNOPSIS .nf .C "#include " .PP .C "struct servent *getservent(void);" .PP .C "int getservent_r(struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyname(const char *name, .C " const char *proto);" .PP .C "int getservbyname_r(const char *name," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PP .C "struct servent *getservbyport(int port, const char *proto);" .PP .C "int getservbyport_r(int port," .C " const char *proto," .C " struct servent *result," .C " struct servent_data *buffer);" .PD .PP .C "int setservent(int stayopen);" .PP .C "int setservent_r(int stayopen, struct servent_data *buffer);" .PP .C "int endservent(void);" .PP .C "int endservent_r(struct servent_data *buffer);" .PP .C "_XOPEN_SOURCE_EXTENDED only" .C "void setservent(int stayopen);" .C "void endservent(void);" .fi .SH DESCRIPTION The .CR getservent() , .CR getservbyname() , and .CR getservbyport() functions each return a pointer to a structure of type .I servent containing the broken-out fields of a line in the network services data base, .CR /etc/services . .PP The members of this structure are: .RS .TP 15 .CR s_name The official name of the service. .TP .CR s_aliases A null-terminated list of alternate names for the service. .TP .CR s_port The port number at which the service resides. .TP .CR s_proto The name of the protocol to use when contacting the service. .RE .PP Functions behave as follows: .RS .TP 25 .CR getservent() Reads the next line of the file, opening the file if necessary. .TP .CR setservent() Opens and rewinds the file. If the .I stayopen flag is non-zero, the services data base is not closed after each call to .CR getservent() (either directly or indirectly through one of the other .CR getserv* calls). .TP .CR endservent() Closes the file. .TP .CR getservbyname() .PD 0 .TP .CR getservbyport() Each sequentially searches from the beginning of the file until a matching service name (among either the official names or the aliases) or port number is found, or until EOF is encountered. If a non-NULL protocol name is also supplied (such as .CR tcp or .CR udp ), searches must also match the protocol. .PD .IP If the system is running the Network Information Service (NIS), .CR getservbyname() gets the service information from the NIS server (see .IR ypserv (1M) and .IR ypfiles (4)). .RE .SS Reentrant Interfaces .CR getservent_r() , .CR getservbyname_r() , and .CR getservbyport_r() expect to be passed the address of a .CR "struct servent" and will store the result at the supplied location. An additional parameter, a pointer to a .IR "struct servent_data" , must also be supplied. This structure is used to store data, to which fields in the .CR "struct servent" will point, as well as state information such as open file descriptors. The .CR "struct servent_data" is defined in the file .CR . .PP .CR setservent_r() and .CR endservent_r() are to be used only in conjunction with .CR getservent_r() and take the same pointer to a .CR "struct servent_data" as a parameter. If the Network Information Service is being used, .CR setservent_r() initializes an internal database key. If the .CR /etc/services file is being used, .CR setservent_r() opens or rewinds the file. .CR endservent_r() should always be called to ensure that files are closed and internally allocated data structures are released. .PP The .I stayopen parameter to .CR setservent_r() currently has no effect. However, .CR setservent() can still be used to keep the .B /etc/services file open when making calls to .CR getservbyname_r() and .CR getservbyport_r() . .PP The .I serv_fp field in the .CR "servent_data struct" must be initialized to NULL before it is passed to either .CR getservent_r() or .CR setservent_r() for the first time. Thereafter it should not be modified in any way. This is the only .CR "servent_data" field that should ever be explicitly accessed. .SS Name Service Switch-Based Operation The library routines, .CR getservbyname() , .CR getservbyport() , .CR getservent() , and their reentrant counterparts, internally call the name service switch to access the "services" database lookup policy configured in the .CR /etc/nsswitch.conf file (see .IR switch(4)). The lookup policy defines the order and the criteria of the supported name services used to resolve service names and ports. .SH RETURN VALUE .CR getservent() , .CR getservbyname() , and .CR getservbyport() return a null pointer (0) on EOF or when they are unable to open .CR /etc/services . .PP The reentrant .RC ( _r ) versions of these routines return .CR -1 if the operation is unsuccessful or, in the case of .CR getservent_r() , if the end of the services list has been reached. .CR 0 is returned otherwise. .SH EXAMPLES The following code excerpt counts the number of service entries: .RS .nf .PP .C "int count = 0;" .C "struct servent servbuf;" .C "struct servent_data sdbuf;" .PP .C "sdbuf.serv_fp = NULL;" .C "(void) setservent_r(0, &sdbuf);" .C "while (getservent_r(&servbuf, &sdbuf) != -1)" .C " count++;" .C "(void) endservent_r(&sdbuf);" .fi .RE .SH WARNINGS In the nonreentrant versions of these routines, all information is contained in a static area, so it must be copied if it is to be saved. .PP .CR getservent() , .CR getservbyport() , .CR getservbyname() , .CR setservent() , and .CR endservent() are unsafe in multi-thread applications. .CR getservent_r() , .CR getservbyport_r() , .CR getservbyname_r() , .CR setservent_r() , and .CR endservent_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getservent() was developed by the University of California, Berkeley. .SH FILES .CR /etc/services .SH SEE ALSO ypserv(1M), services(4), ypfiles(4). .SH STANDARDS CONFORMANCE .CR getservent() ": XPG4" .\" .\" index@\f1end service entry@@@\f3getservent(3N)\f1 .\" index@\f1entry, get, set, or end service@@@\f3getservent(3N)\f1 .\" index@\f1get service entry@@@\f3getservent(3N)\f1 .\" index@\f1service entry, get, set, or end@@@\f3getservent(3N)\f1 .\" index@\f1set service entry@@@\f3getservent(3N)\f1 .\" index@\f1thread-safe, get, set, or end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent()\f1 \- end service entry@@@\f3getservent(3N)\f1 .\" index@\f4endservent_r()\f1 \- end service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyname_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservbyport_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4getservent()\f1 \- get service entry@@@\f3getservent(3N)\f1 .\" index@\f4getservent_r()\f1 \- get service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" index@\f4setservent()\f1 \- set service entry@@@\f3getservent(3N)\f1 .\" index@\f4setservent_r()\f1 \- set service entry (thread-safe)@@@\f3getservent(3N)\f1 .\" .\" links@getservent.3n endservent.3n .\" links@getservent.3n endservent_.3n .\" links@getservent.3n getservbyna.3n .\" links@getservent.3n getservbypo.3n .\" links@getservent.3n getservent_.3n .\" links@getservent.3n setservent.3n .\" links@getservent.3n setservent_.3n .\" .\" toc@\f3getservent(3N)\f1:\0\0\f4endservent()\f1, \f4endservent_r()\f1, \f4getservbyname()\f1, \f4getservbyname_r()\f1,\n\f4getservbyport()\f1, \f4getservbyport_r()\f1, \f4getservent()\f1, \f4getservent_r()\f1,\n\f4setservent()\f1, \f4setservent_r()\f1@@@get, set, or end service entry .\" .\" toc@\f4endservent()\f1:\0\0end service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4endservent_r()\f1:\0\0end service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyname_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservbyport_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent()\f1:\0\0get service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4getservent_r()\f1:\0\0get service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent()\f1:\0\0set service entry@@@see \f3getservent(3N)\f1 .\" toc@\f4setservent_r()\f1:\0\0set service entry (thread-safe)@@@see \f3getservent(3N)\f1 .\" $Header: getspent.3c,v 72.3 94/07/03 15:08:29 ssa Exp $ .TA g .TH getspent 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME .CR getspent , .CR getspnam , .CR setspent , .C endspent \- access secure password entries, for trusted systems only. .SH SYNOPSIS .C #include .br .C struct spwd * getspent (void); .br .C struct spwd * getspnam (const char *name); .br .C void setspent (void) .br .C void endspent (void) .SH DESCRIPTION The routines .CR getspent () and .CR getspnam () return a pointer to the next secured password entry. Each entry is a .C spwd structure, declared in the .C shadow.h header file with the following members: .nf .IP .CR "char *sp_namp; " "/* the user's login name */" .CR "char *sp_pwdp; " "/* the encrypted password for the user */" .CR "long sp_lstchg; " "/* # of days from 1/1/70 when passwd was last modified */" .CR "long sp_min; " "/* min # of days allowed between password changes */" .CR "long sp_max; " "/* max # of days allowed between password changes */" .CR "long sp_warn; " "/* # of days before password expires and warning issued*/" .CR "long sp_inact; " "/* # of days between account inactive and disabled */" .CR "long sp_expire; " "/* # of days from 1/1/70 when account is locked */" .CR "unsigned long sp_flag;" "/* currently unused */" .fi .PP The .CR getspent () routine returns a pointer to the first .C spwd structure when first called. Subsequent calls return pointers to successive .C spwd structures. Repeated calls to .CR getspent () can be used to search all entries in the protected password database. The .C getspnam () routine searches password entries from beginning to end until a login name matching .I name is found, and returns a pointer to that entry. .PP If the fields corresponding to .CR sp_min , .CR sp_max , .CR sp_lstchg , .CR sp_warn , .CR sp_inact , .CR sp_expire , or .C sp_flag are not specified in the entry, they default to -1. If an end-of-file or an error is encountered in reading or a format error is detected, these functions return a null pointer and; for an error, .C errno is set to .CR EINVAL . .PP The .CR setspent () routine is used to reset access to the secured password entries. After .CR setspent () is called, the subsequent call to .CR getspent () returns the first secured password entry. This mechanism is used to allow repeated searches of the secured password entries. The .CR endspent () routine is used to indicate that processing of secured password entries is complete. .PP .CR getspent () is only supported on trusted systems. .PP The secured password facility is implemented without the use of the .C /etc/shadow file. .CR getspent (), .CR getspnam (), .CR setspent (), and .CR endspent () read from the trusted system's protected password database .RC ( /tcb/files/auth/\c .I *\c .C /\c .IR * ) and not .CR /etc/shadow . The file .C /etc/shadow is not used in any way by the HP-UX login facility. .PP These routines return a null pointer and sets ERRNO to ENOENT if the system has not been converted to trusted system. In all other cases, the return value is set similarly to .CR getprpwent (). See .IR getprpwent (3) for more information. .PP Programs using these routines must be compiled with .CR \-lsec . .SH FILES .TP 30 .PD 0 .C /etc/passwd System Password file. .TP .CR /tcb/files/auth/*/* Protected password database, for trusted systems. .PD .SH SEE ALSO getpwent(3C), getprpwent(3C), passwd(4). .SH DIAGNOSTICS .CR getspent (), .CR getspnam (), and .CR fgetspent () return a null pointer on EOF or error. .SH STANDARDS CONFORMANCE .C getspent : SVID3 .\" index@\f4getspent()\fP \- get next secure password file entry@@@\f3getspent(3C)\f1 .\" index@\f4getspnam()\fP \- get secure password file entry matching \f4name()\fP@@@\f3getspent(3C)\f1 .\" index@\f4setspent()\fP \- rewind pointer to beginning of secure password file@@@\f3getspent(3C)\f1 .\" index@\f4endspent()\fP \- close currently open secure password file@@@\f3getspent(3C)\f1 .\" index@entry from secure password file, get@@@\f3getspent(3C)\f1 .\" index@trusted system password database, get entry from@@@\f3getspent(3C)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspent(3C)\f1 .\" .\" toc@\f3getspent(3C)\f1:\0\0\f4getspent()\fP, \f4getspnam()\fP, \f4setspent()\fP, \f4endspent()\fP@@@get secure password file entry .\" toc@\f4getspent()\fP:\0\0get secure password file entry@@@see \f3getspent(3C)\f1 .\" toc@\f4setpwent()\fP:\0\0get secure password file entry@@@see \f3getspent(3C)\f1 .\" toc@\f4endpwent()\fP:\0\0get secure password file entry@@@see \f3getspent(3C)\f1 .\" .\" links@getspent.3c getspnam.3c .\" links@getspent.3c setspent.3c .\" links@getspent.3c endspent.3c .\" .\" $Header: getspwent.3x,v 72.6 94/11/30 10:11:44 ssa Exp $ .TA g .TH getspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getspwent(\|), getspwent_r(\|), getspwuid(\|), getspwuid_r(\|), getspwaid(\|), getspwaid_r(\|), getspwnam(\|), getspwnam_r(\|), setspwent(\|), setspwent_r(\|), endspwent(\|), endspwent_r(\|), fgetspwent(\|), fgetspwent_r(\|) \- get secure password file entry\c , on trusted systems .SH SYNOPSIS .C "#include " .PP .C "struct s_passwd *getspwent(void);" .PP .C "int getspwent_r(struct s_passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct s_passwd *getspwuid(uid_t uid);" .PP .PD 0 .C "int getspwuid_r(uid_t uid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwaid(aid_t aid);" .PP .PD 0 .C "int getspwaid_r(aid_t aid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwnam(const char *name);" .PP .PD 0 .C "int getspwnam_r(char *name, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setspwent(void);" .PP .C "void setspwent_r(FILE **pwfp);" .PP .C "void endspwent(void);" .PP .C "void endspwent_r(FILE **pwfp);" .PP .C "struct s_passwd *fgetspwent(\s-1FILE\s0 *stream);" .PP .PD 0 .C "int fgetspwent_r(FILE *f, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .SH DESCRIPTION These privileged routines provide access to the protected password database in a manner similar to the way .IR getpwent (3C) routines handle the regular password file, .RC ( \|/etc/passwd\| ). .PP These routines are particularly useful in situations where it is not necessary to get information from the regular password file. .IR getspwent (3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, .CR libsec . .PP Note that .CR getspwent () routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the .CR getprpwent () routines. See .IR getprpwent (3). .PP .CR getspwent (), .CR getspwuid (), .CR getspwaid (), and .CR getspwnam () each returns a pointer to an object of .CR s_passwd structure. The .CR s_passwd structure is maintained for compatibility with existing software and consists of five fields as follows: .nf .IP .C "struct\ s_passwd\ {" .C " char *pw_name; /* login name */" .C " char *pw_passwd; /* encrypted password */" .C " char *pw_age; /* password age */" .C " int pw_audid; /* audit ID */" .C " int pw_audflg; /* audit flag 1=on, 0=off */" .C }; .fi .PP Since the .CR s_passwd structure is declared in the .RC < pwd.h > header file, it is unnecessary to redeclare it. .PP To access other fields in the protected password database that are not included in the .CR s_passwd structure, use .CR getprpwent (). See .IR getprpwent (3) for more information. .PP .TP 20 .CR getspwent () When first called, .CR getspwent () returns a pointer to each .CR s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database. .TP .CR getspwuid () Searches for an entry that matches the specified .IR uid . It then returns a pointer to the particular structure in which .I uid is found. .TP .CR getspwaid () Similarly searches for a numerical audit ID matching .I aid and returns a pointer to the particular structure in which .I aid is found (see .IR spasswd (4) for details on this field). .TP .CR getspwnam () Searches for an entry that matches the specified .IR name . Returns a pointer to the particular structure in which .I name is found. .TP .CR setspwent () Resets the protected password database pointer to the beginning of the file to allow repeated searches. .TP .CR endspwent () Should be called to close the protected password database file when processing is complete. .TP .CR fgetspwent () Is no longer supported. It is provided for those applications that did not use .CR /.secure/etc/passwd . .SS Reentrant Interfaces .CR getspwuid_r (), .CR getspwaid_r (), .CR getspwnam_r (), and .CR fgetspwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .CR s_passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in the .CR s_passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getspwent_r () requires a pointer to a .RI ( "FILE *" ) variable. .CR setspwent_r () and .CR endspwent_r () are to be used only in conjunction with .CR getspwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setspwent_r () can be used to rewind or open the protected password database. .CR endspwent_r () should be called when done to close the file. .PP The .CR /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database. .PP .CR fgetspwent_r () is no longer supported, but is included for those users that did not use the .CR /.secure/etc/passwd file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getspwent_r () or .CR setspwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH RETURN VALUE .CR getspwent () returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the calling process is not zero. .PP .CR getspwent_r () returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned. .SH WARNINGS The above routines use .RC < stdio.h >, which causes them to increase the size of programs by more than might otherwise be expected. .PP Since all information for .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() is contained in a static area, it must be copied to be saved. .PP .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() are unsafe in multi-thread applications. .CR getspwent_r() , .CR getspwuid_r() , .CR getspwaid_r() , .CR getspwnam_r() , .CR setspwent_r() , .CR endspwent_r() , and .CR fgetspwent_r() are MT-Safe and should be used instead. .PP Network Information Service is not supported on trusted systems. .SH EXAMPLE The following code excerpt counts the number of entries in the protected password database: .nf .IP .C "int count = 0;" .C "struct s_passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setspwent_r(&pwf);" .C "while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endspwent_r(&pwf);" .SH AUTHOR .CR getspwent () was developed by HP. .SH FILES .TP 30 .C /tcb/files/auth/*/* Protected Password database .SH SEE ALSO ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), putspwent(3X), passwd(4). .\" .\" index@\f4getspwent()\f1 \- get next secure password file entry@@@\f3getspwent(3X)\f1 .\" index@\f4getspwaid()\f1 \- get next secure password file audit ID@@@\f3getspwent(3X)\f1 .\" index@\f4fgetspwent()\f1 \- get next entry in secure password-file-formatted input stream@@@\f3getspwent(3X)\f1 .\" index@\f4getspwuid()\f1 \- get secure password file entry matching \f4uid()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4getspwnam()\f1 \- get secure password file entry matching login name \f4name()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4setspwent()\f1 \- rewind pointer to beginning of secure password file@@@\f3getspwent(3X)\f1 .\" index@\f4endspwent()\f1 \- close currently open secure password file@@@\f3getspwent(3X)\f1 .\" index@entry from secure password file, get@@@\f3getspwent(3X)\f1 .\" index@secure password file, get entry from@@@\f3getspwent(3X)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspwent(3C)\f1 .\" .\" toc@\f3getspwent(3X)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f1,\n\f4endpwent()\f1, \f4fgetpwent()\f1@@@get secure password file entry .\" toc@\f4getpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4setpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4endpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4getspwaid()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" .\" links@getspwent.3x getspwuid.3x .\" links@getspwent.3x getspwnam.3x .\" links@getspwent.3x setspwent.3x .\" links@getspwent.3x endspwent.3x .\" links@getspwent.3x fgetspwent.3x .\" links@getspwent.3x getspwaid.3x .\" links@getspwent.3x getspwent_r.3x .\" links@getspwent.3x getspwuid_r.3x .\" links@getspwent.3x getspwaid_r.3x .\" links@getspwent.3x getspwnam_r.3x .\" links@getspwent.3x setspwent_r.3x .\" links@getspwent.3x endspwent_r.3x .\" links@getspwent.3x fgetspwent_.3x .\" .\" fileset_database@getspwent.3x PROGRAMING-MAN .\" $Header: getspwent.3x,v 72.6 94/11/30 10:11:44 ssa Exp $ .TA g .TH getspwent 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getspwent(\|), getspwent_r(\|), getspwuid(\|), getspwuid_r(\|), getspwaid(\|), getspwaid_r(\|), getspwnam(\|), getspwnam_r(\|), setspwent(\|), setspwent_r(\|), endspwent(\|), endspwent_r(\|), fgetspwent(\|), fgetspwent_r(\|) \- get secure password file entry\c , on trusted systems .SH SYNOPSIS .C "#include " .PP .C "struct s_passwd *getspwent(void);" .PP .C "int getspwent_r(struct s_passwd *result, char *buffer, int buflen," .PD 0 .IP .C " FILE **pwfp);" .PD .PP .C "struct s_passwd *getspwuid(uid_t uid);" .PP .PD 0 .C "int getspwuid_r(uid_t uid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwaid(aid_t aid);" .PP .PD 0 .C "int getspwaid_r(aid_t aid, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "struct s_passwd *getspwnam(const char *name);" .PP .PD 0 .C "int getspwnam_r(char *name, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .PP .C "void setspwent(void);" .PP .C "void setspwent_r(FILE **pwfp);" .PP .C "void endspwent(void);" .PP .C "void endspwent_r(FILE **pwfp);" .PP .C "struct s_passwd *fgetspwent(\s-1FILE\s0 *stream);" .PP .PD 0 .C "int fgetspwent_r(FILE *f, struct s_passwd *result," .IP .C " char *buffer, int buflen);" .PD .SH DESCRIPTION These privileged routines provide access to the protected password database in a manner similar to the way .IR getpwent (3C) routines handle the regular password file, .RC ( \|/etc/passwd\| ). .PP These routines are particularly useful in situations where it is not necessary to get information from the regular password file. .IR getspwent (3X) can be used on a trusted system to return the password, audit ID, and audit flag information. Programs using these routines must be linked with the security library, .CR libsec . .PP Note that .CR getspwent () routines are provided for backward compatibility. New applications accessing the protected password database on trusted systems should use the .CR getprpwent () routines. See .IR getprpwent (3). .PP .CR getspwent (), .CR getspwuid (), .CR getspwaid (), and .CR getspwnam () each returns a pointer to an object of .CR s_passwd structure. The .CR s_passwd structure is maintained for compatibility with existing software and consists of five fields as follows: .nf .IP .C "struct\ s_passwd\ {" .C " char *pw_name; /* login name */" .C " char *pw_passwd; /* encrypted password */" .C " char *pw_age; /* password age */" .C " int pw_audid; /* audit ID */" .C " int pw_audflg; /* audit flag 1=on, 0=off */" .C }; .fi .PP Since the .CR s_passwd structure is declared in the .RC < pwd.h > header file, it is unnecessary to redeclare it. .PP To access other fields in the protected password database that are not included in the .CR s_passwd structure, use .CR getprpwent (). See .IR getprpwent (3) for more information. .PP .TP 20 .CR getspwent () When first called, .CR getspwent () returns a pointer to each .CR s_passwd structure obtained from the protected password database for each user in sequence. Subsequent calls can be used to search the entire database. .TP .CR getspwuid () Searches for an entry that matches the specified .IR uid . It then returns a pointer to the particular structure in which .I uid is found. .TP .CR getspwaid () Similarly searches for a numerical audit ID matching .I aid and returns a pointer to the particular structure in which .I aid is found (see .IR spasswd (4) for details on this field). .TP .CR getspwnam () Searches for an entry that matches the specified .IR name . Returns a pointer to the particular structure in which .I name is found. .TP .CR setspwent () Resets the protected password database pointer to the beginning of the file to allow repeated searches. .TP .CR endspwent () Should be called to close the protected password database file when processing is complete. .TP .CR fgetspwent () Is no longer supported. It is provided for those applications that did not use .CR /.secure/etc/passwd . .SS Reentrant Interfaces .CR getspwuid_r (), .CR getspwaid_r (), .CR getspwnam_r (), and .CR fgetspwent_r () expect to be passed three extra parameters: .PP .TP 3 1. The address of a .CR s_passwd structure where the result will be stored; .TP 2. A buffer to store character strings (such as the password) to which fields in the .CR s_passwd structure will point; .TP 3. The length of the user-supplied buffer. .PP In addition to the above three parameters, .CR getspwent_r () requires a pointer to a .RI ( "FILE *" ) variable. .CR setspwent_r () and .CR endspwent_r () are to be used only in conjunction with .CR getspwent_r () and take the same pointer to a .RI ( "FILE *" ) variable as a parameter. .CR setspwent_r () can be used to rewind or open the protected password database. .CR endspwent_r () should be called when done to close the file. .PP The .CR /.secure/etc/passwd file is no longer supported and these routines provide an interface to the protected password database. .PP .CR fgetspwent_r () is no longer supported, but is included for those users that did not use the .CR /.secure/etc/passwd file. .PP Note that the .RI ( "FILE *" ) variable must be initialized to NULL before it is passed to .CR getspwent_r () or .CR setspwent_r () for the first time. Thereafter it should not be modified in any way. .PP A buffer length of 1024 is recommended. .SH RETURN VALUE .CR getspwent () returns a NULL pointer if any of its routines encounters an end-of-file or error while searching, or if the effective user ID of the calling process is not zero. .PP .CR getspwent_r () returns a -1 if any of its routines encounters an end-of-file or error, or if the supplied buffer has insufficient length. If the operation is successful, 0 is returned. .SH WARNINGS The above routines use .RC < stdio.h >, which causes them to increase the size of programs by more than might otherwise be expected. .PP Since all information for .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() is contained in a static area, it must be copied to be saved. .PP .CR getspwent() , .CR getspwuid() , .CR getspwaid() , .CR getspwnam() , .CR setspwent() , .CR endspwent() , and .CR fgetspwent() are unsafe in multi-thread applications. .CR getspwent_r() , .CR getspwuid_r() , .CR getspwaid_r() , .CR getspwnam_r() , .CR setspwent_r() , .CR endspwent_r() , and .CR fgetspwent_r() are MT-Safe and should be used instead. .PP Network Information Service is not supported on trusted systems. .SH EXAMPLE The following code excerpt counts the number of entries in the protected password database: .nf .IP .C "int count = 0;" .C "struct s_passwd pwbuf;" .C "char buffer[1024];" .C "FILE *pwf = NULL;" .C "setspwent_r(&pwf);" .C "while (getspwent_r(&pwbuf, buffer, 1024, &pwf) != -1)" .C " count++;" .C "endspwent_r(&pwf);" .SH AUTHOR .CR getspwent () was developed by HP. .SH FILES .TP 30 .C /tcb/files/auth/*/* Protected Password database .SH SEE ALSO ypcat(1), getgrent(3C), getlogin(3C), getpwent(3C), getprpwent(3), putspwent(3X), passwd(4). .\" .\" index@\f4getspwent()\f1 \- get next secure password file entry@@@\f3getspwent(3X)\f1 .\" index@\f4getspwaid()\f1 \- get next secure password file audit ID@@@\f3getspwent(3X)\f1 .\" index@\f4fgetspwent()\f1 \- get next entry in secure password-file-formatted input stream@@@\f3getspwent(3X)\f1 .\" index@\f4getspwuid()\f1 \- get secure password file entry matching \f4uid()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4getspwnam()\f1 \- get secure password file entry matching login name \f4name()\f1@@@\f3getspwent(3X)\f1 .\" index@\f4setspwent()\f1 \- rewind pointer to beginning of secure password file@@@\f3getspwent(3X)\f1 .\" index@\f4endspwent()\f1 \- close currently open secure password file@@@\f3getspwent(3X)\f1 .\" index@entry from secure password file, get@@@\f3getspwent(3X)\f1 .\" index@secure password file, get entry from@@@\f3getspwent(3X)\f1 .\" index@file, password: get entry from secure password file@@@\f3getspwent(3C)\f1 .\" .\" toc@\f3getspwent(3X)\f1:\0\0\f4getpwent()\f1, \f4getpwuid()\f1, \f4getpwnam()\f1, \f4setpwent()\f1,\n\f4endpwent()\f1, \f4fgetpwent()\f1@@@get secure password file entry .\" toc@\f4getpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4setpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4endpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4fgetpwent()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" toc@\f4getspwaid()\f1:\0\0get secure password file entry@@@see \f3getspwent(3X)\f1 .\" .\" links@getspwent.3x getspwuid.3x .\" links@getspwent.3x getspwnam.3x .\" links@getspwent.3x setspwent.3x .\" links@getspwent.3x endspwent.3x .\" links@getspwent.3x fgetspwent.3x .\" links@getspwent.3x getspwaid.3x .\" links@getspwent.3x getspwent_r.3x .\" links@getspwent.3x getspwuid_r.3x .\" links@getspwent.3x getspwaid_r.3x .\" links@getspwent.3x getspwnam_r.3x .\" links@getspwent.3x setspwent_r.3x .\" links@getspwent.3x endspwent_r.3x .\" links@getspwent.3x fgetspwent_.3x .\" .\" fileset_database@getspwent.3x PROGRAMING-MAN .\" $Header: random.3m,v 76.2 95/07/10 17:17:13 ssa Exp $ .TA r .TH random 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME random(\|), srandom(\|), initstate(\|), setstate(\|) \- generate a pseudorandom number .SH SYNOPSIS .C "#include " .PP .C "long random(void);" .PP .C "void srandom(unsigned seed);" .PP .C "char *initstate(unsigned seed, char *state, size_t size);" .PP .C "char *setstate(char *state);" .fi .ft 1 .SH DESCRIPTION The .CR random() and .CR srandom() functions are random-number generators that have virtually the same calling sequence and initialization properties as the .CR rand() and .CR srand() functions, but produce sequences that are more random. The low 12 bits generated by the .CR rand() function go through a cyclic pattern, while all the bits generated by the .CR random() function are usable. For example, .C "random() & 01" produces a random binary value. .PP The .CR random() function uses a nonlinear additive feedback random-number generator employing a default state array size of 31 long integers to return successive pseudorandom numbers in the range from 0 to .ift 2\u\s-231\s0\d-1. .ifn (2^31 - 1). The period of this random-number generator is approximately 16 x .ift (2\s-2\u31\d\s0-\f11). .ifn (2^31 - 1). The size of the state array determines the period of the random-number generator. Increasing the state array size increases the period. .PP With 256 bytes of state information, the period of the random-number generator is greater than .ift 2\s-2\u69\s0\d. .ifn 2^69. .PP Like the .CR rand() function, the .CR random() function produces by default a sequence of numbers that can be duplicated by calling the .CR srandom() function with a value of 1 as the seed. .P The .CR srandom() function initializes the current state array using the value of .IR seed . .PP The .CR initstate() and .CR setstate() functions handle restarting and changing random-number generators. The .CR initstate() function allows a state array, pointed to by the .I state argument, to be initialized for future use. The .I size argument, which specifies the size in bytes of the state array, is used by the .CR initstate() function to decide how sophisticated a random-number generator to use; the larger the state array, the more random the numbers. Values for the amount of state information are 8, 32, 64, 128, and 256 bytes. Amounts less than 8 bytes generate an error, while other amounts are rounded down to the nearest known value. The .I seed argument specifies a starting point for the random-number sequence and provides for restarting at the same point. The .CR initstate() function returns a pointer to the previous state information array. .PP Once a state has been initialized, the .CR setstate() function allows switching between state arrays. The array defined by the .I state argument is used for further random-number generation until the .CR initstate() function is called or the .CR setstate() function is called again. The .CR setstate() function returns a pointer to the previous state array. .PP After initialization, a state array can be restarted at a different point in one of two ways: .PP .RS The .CR initstate() function can be used, with the desired seed, state array, and size of the array. .PP The .CR setstate() function, with the desired state, can be used, followed by the .CR srandom() function with the desired seed. The advantage of using both of these functions is that the size of the state array does not have to be saved once it is initialized. .PP .RE .SH RETURN VALUE The .CR random() function returns the generated pseudorandom number. .PP The .CR srandom() function returns no value. .PP Upon successful completion, the .CR initstate() and .CR setstate() functions return a pointer to the previous state array. Otherwise, a NULL pointer is returned. .SH ERRORS If the .CR initstate() function is called with .I size less than 8, or if the .CR setstate() function detects that the state information has been damaged, error messages are written to standard error. .SH SEE ALSO .PP drand48(3C), rand(3C). .SH STANDARDS COMPLIANCE .CR random() "COSE API, XPG 4.2" .br .CR srandom() "COSE API, XPG 4.2" .br .CR initstate() "COSE API, XPG 4.2" .br .CR setstate() "COSE API, XPG 4.2" .\" .\" index@\f4random()\f1, \f4srandom()\f1, \f4initstate()\f1, \f4setstate()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f4srandom()\f1, \f4initstate()\f1, \f4setstate()\f1, \f4random()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f4initstate()\f1, \f4setstate()\f1, \f4random()\f1, \f4srandom()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f4setstate()\f1, \f4random()\f1, \f4srandom()\f1, \f4initstate()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f1math: pseudorandom number generation functions@@@\f3random(3M)\f1 .\" index@\f1pseudorandom number generation functions@@@\f3random(3M)\f1 .\" index@\f1random number generation functions@@@\f3random(3M)\f1 .\" .\" toc@\f3random(3M)\f1:\0\0\f4random()\f1, \f4srandom()\f1, \f4initstate()\f1, \f4setstate()\f1@@@generate a pseudorandom number .\" toc@\f4random()\f1:\0\0pseudorandom number generation functions@@@see \f3random(3M)\f1 .\" toc@\f4srandom()\f1:\0\0pseudorandom number generation functions@@@see \f3random(3M)\f1 .\" toc@\f4initstate()\f1:\0\0pseudorandom number functions@@@see \f3random(3M)\f1 .\" toc@\f4setstate()\f1:\0\0pseudorandom number functions@@@see \f3random(3M)\f1 .\" .\" links@random.3m srandom.3m .\" links@random.3m initstate.3m .\" links@random.3m setstate.3m .\" .\" fileset_database@random.3m PROGRAMING-MAN .\" $Header: del_curterm.3x,v 76.2 95/07/31 11:24:20 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH del_curterm 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME del_curterm, restartterm, set_curterm, setupterm \(em interfaces to the \f3terminfo\f1 database .SH SYNOPSIS .C "#include " .P .C "int del_curterm(TERMINAL *\f2oterm\f4);" .P .C "int restartterm(char *\f2term\f4, int \f2fildes\f4, int *\f2errret\f4);" .P .C "TERMINAL *set_curterm(TERMINAL *\f2nterm\f4);" .P .C "int setupterm(char *\f2term\f4, int \f2fildes\f4, int *\f2errret\f4);" .P .C "extern TERMINAL *cur_term;" .SH DESCRIPTION These functions retrieve information from the \f3terminfo\f1 database. .P To gain access to the \f3terminfo\f1 database, .Fn setupterm must be called first. It is automatically called by .Fn initscr and .Fn newterm . The .Fn setupterm function initializes the other functions to use the \f3terminfo\f1 record for a specified terminal (which depends on whether .Fn use_env was called). It sets the .I cur_term external variable to a \f3TERMINAL\f1 structure that contains the record from the \f3terminfo\f1 database for the specified terminal. .P The terminal type is the character string \f2term;\f1 if \f2term\f1 is a null pointer, the environment variable TERM is used. If TERM is not set or if its value is an empty string, then \f4"unknown"\f1 is used as the terminal type. The application must set \f2fildes\f1 to a file descriptor, open for output, to the terminal device, before calling .Fn setupterm . If \f2errret\f1 is not null, the integer it points to is set to one of the following values to report the function outcome: .PP .RS .TP 10 .CR \(mi1 The \f3terminfo\f1 database was not found (function fails). .TP .CR 0 The entry for the terminal was not found in \f3terminfo\f1 (function fails). .TP .CR 1 Success. .PP .RE If .Fn setupterm detects an error and \f2errret\f1 is a null pointer, .Fn setupterm writes a diagnostic message and exits. .P A simple call to .Fn setupterm that uses all the defaults and sends the output to \f2stdout\f1 is: .\" .Cs I .IP setupterm((char *)0, fileno(stdout), (int *)0); .\" .Ce .PP The .Fn set_curterm function sets the variable \f2cur_term\f1 to \f2nterm\f1, and makes all of the \f3terminfo\f1 boolean, numeric, and string variables use the values from \f2nterm.\f1 .P The .Fn del_curterm function frees the space pointed to by \f2oterm\f1 and makes it available for further use. If \f2oterm\f1 is the same as \f2cur_term\f1, references to any of the \f3terminfo\f1 boolean, numeric, and string variables thereafter may refer to invalid memory locations until .Fn setupterm is called again. .P The .Fn restartterm function assumes a previous call to .Fn setupterm (perhaps from .Fn initscr or .Fn newterm ). It lets the application specify a different terminal type in \f2term\f1 and updates the information returned by .Fn baudrate based on \f2fildes\f1, but does not destroy other information created by .Fn initscr , .Fn newterm or .Fn setupterm . .SH "RETURN VALUE" Upon successful completion, .Fn set_curterm returns the previous value of \f2cur_term\f1. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" An application would call .Fn setupterm if it required access to the \f3terminfo\f1 database but did not otherwise need to use Curses. .SH "SEE ALSO" \f3Selecting a Terminal\f1 in terminfo(4), baudrate(), erasechar(), has_ic(), longname(), putc(), termattrs(), termname(), tgetent(), tigetflag(), use_env(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3del_curterm(3x)\f1:\0\0\f4del_curterm()\f1, \f4restartterm()\f1, \f4set_curterm()\f1,\n\f4setupterm()\f1@@@interfaces to terminfo database .\" .\" toc@\f4del_curterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" toc@\f4restartterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" toc@\f4set_curterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" toc@\f4setupterm()\f1:\0\0interface to terminfo database@@@\f1see \f3del_curterm(3x)\f1 .\" .\" index@\f4del_curterm()\f1, \f4restartterm()\f1, \f4set_curterm()\f1, \f4setupterm()\f1 \- interfaces to \nterminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f4restartterm()\f1 \- interface to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f4set_curterm()\f1 \- interface to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f4setupterm()\f1 \- interface to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f1interfaces to terminfo database@@@\f3del_curterm(3x)\f1 .\" index@\f1terminfo database, interfaces@@@\f3del_curterm(3x)\f1 .\" .\" links@del_curterm.3x restartterm.3x .\" links@del_curterm.3x set_curterm.3x .\" links@del_curterm.3x setupterm.3x .\" .\" fileset_database@del_curtem.3x CURS-ENG-A-MAN .\" .\" $Header: getusershel.3c,v 72.6 94/11/02 15:43:32 ssa Exp $ .TA g .TH getusershell 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getusershell(\|), getusershell_r(\|), setusershell(\|), setusershell_r(\|), endusershell(\|), endusershell_r(\|) \- get legal user shells .SH SYNOPSIS .C "#include " .PP .C "char *getusershell(void);" .PP .C "char *getusershell_r(char **shell_datap);" .PP .C "void setusershell(void);" .PP .C "void setusershell_r(char **shell_datap);" .PP .C "void endusershell(void);" .PP .C "void endusershell_r(char **shell_datap);" .SH DESCRIPTION .TP 25 .CR getusershell() Returns a pointer to the first legal user shell as defined in the file .CR /etc/shells (see .IR shells (4)). If .CR /etc/shells does not exist or is not readable, .CR getusershell() returns the following standard system shells: .RS .nf .IP .CR /sbin/sh .CR /usr/bin/sh .CR /usr/bin/rsh .CR /usr/bin/ksh .CR /usr/bin/rksh .CR /usr/bin/csh .CR /usr/bin/keysh .fi .RE .IP as if they were contained in .CR /etc/shells . The file is left open so that the next call returns the next shell. A null pointer (0) is returned on .SM EOF or error. .TP .CR setusershell() Rewinds the file. .TP .CR endusershell() Closes the file. .SS Reentrant Interfaces .PP .CR getusershell_r() , .CR setusershell_r() and .CR endusershell_r() expect to be passed the address of a character pointer so that state information can be maintained between calls. .I *shell_datap should be initialized to .SM NULL before the first call to either .CR setusershell_r() or .CR getusershell_r() . Thereafter it should not be modified. After the first call to .CR setusershell_r() or .CR getusershell_r() , .I *shell_datap points to state information that is needed on subsequent calls to .CR getusershell_r() . .PP .CR endusershell_r() should be called when done so that any memory that has been internally allocated can be freed. .SH WARNINGS In the non-reentrant versions of these routines, all information is contained in a static area and therefore must be copied if it is to be saved. .PP .CR getusershell() , .CR setusershell() , and .CR endusershell() are unsafe in multi-thread applications. .CR getusershell_r() , .CR setusershell_r() , and .CR endusershell_r() are MT-Safe and should be used instead. .SH AUTHOR .CR getusershell() was developed by HP and the University of California, Berkeley. .SH FILES .CR /etc/shells .SH SEE ALSO shells(4). .\" .\" index@\f4getusershell()\fP \- get legal user shells@@@\f3getusershell(3C)\f1 .\" index@\f4setusershell()\fP \- rewind legal user shells file@@@\f3getusershell(3C)\f1 .\" index@\f4endusershell()\fP \- close legal user shells file@@@\f3getusershell(3C)\f1 .\" index@get legal user shells@@@\f3getusershell(3C)\f1 .\" index@rewind legal user shells file@@@\f3getusershell(3C)\f1 .\" index@close legal user shells file@@@\f3getusershell(3C)\f1 .\" index@legal user shells, get@@@\f3getusershell(3C)\f1 .\" index@user shells, get legal@@@\f3getusershell(3C)\f1 .\" index@shells, get legal user@@@\f3getusershell(3C)\f1 .\" .\" toc@\f3getusershell(3C)\f1:\0\0\f4getusershell()\fP, \f4setusershell()\fP, \f4endusershell()\fP@@@get legal user shells .\" toc@\f4endusershell()\fP \- close legal user shells file@@@see \f3getusershell(3C)\f1 .\" toc@\f4setusershell()\fP \- rewind legal user shells file@@@see \f3getusershell(3C)\f1 .\" .\" links@getusershel.3c setusershel.3c .\" links@getusershel.3c endusershel.3c .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getutx.3c,v 76.4 95/09/12 12:01:34 ssa Exp $ .TA g .TH getutx 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutxent(\|), getutxid(\|), getutxline(\|), pututxline(\|), setutxent(\|), endutxent(\|) \- access utmpx file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmpx *getutxent(void);" .PP .C "struct utmpx *getutxid(const struct utmpx *id);" .nf .PP .C "struct utmpx *getutxline(const struct utmpx *line);" .PP .C "struct utmpx *_pututxline(const struct utmpx *utmpx);" .PP .C "void pututxline(const struct utmpx *utmpx);" .PP .C "void setutxent(void);" .PP .C "void endutxent(void);" .PP .fi .SH DESCRIPTION .CR getutxent() , .CR getutxid() , and .C getutxline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmpx { char ut_user[24]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct __exit_status { short __e_termination; /* Process termination status */ short __e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ struct timeval { time_t tv_sec; /* seconds */ long tv_usec; /* and microseconds */ } ut_tv; /* time entry was made */ char ut_host[64]; /* host name, if remote; NOT SUPPORTED */ unsigned long ut_addr; /* Internet addr of host, if remote */ char ut_reserved2[12] ; /* Reserved for future use */ }; .ps .ft .fi .RE .TP 20 .C getutxent() Reads in the next entry from a .CR utmpx -like file. If the file is not already open, .C getutxent() opens it. If it reaches the end of the file, .C getutxent() fails. .TP .C getutxid() Searches forward from the current point in the .I utmpx file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutxid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutxid() fails. .TP .C getutxline() Searches forward from the current point in the .I utmpx file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutxline() fails. .TP .C pututxline() Writes out the supplied .C utmpx structure into the .I utmpx file, translates the supplied .C utmpx structure into a .C utmp structure and writes it to a .I utmp file. .C pututxline() uses .C getutxid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getutx() routines before calling .CR pututxline() . If the search as already been made, .C pututxline() does not repeat it. If .C pututxline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututxline() Performs the same actions as .CR pututxline() , except that it returns a value useful for error checking. .TP .C setutxent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutxent() Closes the currently open file. .TP .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutxid() or .CR getutxline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutxline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutxline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututxline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutxent() , .CR getutxid() , or .C getutxline() if the user has just modified those contents and passed the pointer back to .CR pututxline() . .PP .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmpx)" . .PP .C _pututxline() behaves the same as .CR pututxline() , except that it returns a pointer to a static location containing the most current utmpx entry if the .C _pututxline() call succeeds. The contents of this structure are identical to the contents of the supplied .C utmpx structure if successful. If .C _pututline() fails upon writing to .C utmpx , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmpx file and fails in writing to the .C utmp file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmpx file and the .C utmp file may not be in sync due to the above behavior. .C pututxline() and .C _pututxline() are only guaranteed to have written to the .C utmpx file upon successful completion. .SH FILES .PP .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututline(3), utmpname(3). .SH STANDARDS CONFORMANCE .CR endutxent() ": XPG4.2" .PP .CR getutxent() ": XPG4.2" .PP .CR getutxid() ": XPG4.2" .PP .CR getutxline() ": XPG4.2" .PP .CR pututxline() ": XPG4.2" .PP .CR setutxent() ": XPG4.2" .PP .\" .\" index@\f4getutxent()\f1 \- get pointer to next entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4getutxline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4_pututxline()\f1 \- update or create entry in a \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4setutxent()\f1 \- reset input stream to beginning of \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4endutxent()\f1 \- close currently open \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" index@access \f4utmpx()\f1 or \f4wtmp()\f1 file@@@\f3getutx(3C)\f1 .\" index@\f4utmpx()\f1 or \f4wtmp()\f1 file, access@@@\f3getutx(3C)\f1 .\" index@file: access \f4utmpx()\f1 file@@@\f3getutx(3C)\f1 .\" .\" toc@\f3getutx(3C)\f1:\0\0\f4getutxent()\f1, \f4getutxid()\f1, \f4getutxline()\f1, \f4pututxline()\f1, \f4setutxent()\f1,\n\f4endutxent()\f1@@@access utmpx file entry .\" toc@\f4getutxent()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxid()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4getutxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4_pututxline()\f1:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4setutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f4endutxent()\fP:\0\0access utmpx file entry@@@see \f3getutx(3C)\f1 .\" toc@\f1utmpx file entry@@@see \f3getutx(3C)\f1 .\" .\" links@getutx.3c getutxent.3c .\" links@getutx.3c getutxid.3c .\" links@getutx.3c getutxline.3c .\" links@getutx.3c pututxline.3c .\" links@getutx.3c _pututxline.3c .\" links@getutx.3c setutxent.3c .\" links@getutx.3c endutxent.3c .\" $Header: setbuf.3s,v 72.5 94/11/15 09:56:11 ssa Exp $ .TA s .TH setbuf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setbuf(\|), setvbuf(\|), setvbuf_unlocked(\|) \- assign buffering to a stream file .SH SYNOPSIS .C "#include " .PP .C "void setbuf(FILE *stream, char *buf);" .PP .C "int setvbuf(FILE *stream, char *buf, int type, size_t size);" .PP .C "int setvbuf_unlocked(FILE *stream, char *buf, int type, size_t size);" .SH DESCRIPTION .CR setbuf() can be used after a stream has been opened but before it is read or written. It causes the array pointed to by .I buf to be used instead of an automatically allocated buffer. If .I buf is the .SM NULL pointer input/output will be completely unbuffered. .PP A constant .CR BUFSIZ , defined in the .RC < stdio.h > header file, tells how big an array is needed: .IP .CR char buf[BUFSIZ]; .PP .CR setvbuf() can be used after a stream has been opened but before it is read or written. .I type determines how .I stream is to be buffered. Legal values for .I type (defined in .RC < stdio.h >) are: .RS .TP 12 .CR _IOFBF causes input/output to be fully buffered. .TP .CR _IOLBF causes output to be line buffered; the buffer will be flushed when a newline is written, the buffer is full, or input is requested. .TP .CR _IONBF causes input/output to be completely unbuffered. .RE .PP When an output stream is unbuffered, information is queued for writing on the destination file or terminal as soon as written; when it is buffered, many characters are saved up and written as a block. When the output stream is line-buffered, each line of output is queued for writing on the destination terminal as soon as the line is completed (that is, as soon as a new-line character is written or terminal input is requested). .CR fflush() can also be used to explicitly write the buffer. .PP If .I buf is not the .SM NULL pointer, the array it points to is used for buffering instead of an automatically allocated buffer (from .CR malloc() ). .I size specifies the size of the buffer to be used. The constant .CR BUFSIZ in .RC < stdio.h > is suggested as a good buffer size. If input/output is unbuffered, .I buf and .I size are ignored. .PP By default, output to a terminal is line buffered and all other input/output is fully buffered. .PP .CR setvbuf_unlocked() is identical to .CR setvbuf() except it does not perform any internal locking of the .I stream for multi-thread applications. .CR setvbuf_unlocked() can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH DIAGNOSTICS If an illegal value for .I type or .I size is provided, .CR setvbuf() " and " setvbuf_unlocked() return a non-zero value. Otherwise, the value returned will be zero. .SH NOTE A common source of error is allocating buffer space as an ``automatic'' variable in a code block, then failing to close the stream in the same block. .SH SEE ALSO flockfile(3S), fopen(3S), getc(3S), malloc(3C), putc(3S), stdio(3S). .SH STANDARDS CONFORMANCE .CR setbuf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR setvbuf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4setbuf()\fP, \f4setvbuf()\fP \- assign buffering to a stream file@@@\f3setbuf(3S)\f1 .\" index@assign buffering to a stream file@@@\f3setbuf(3S)\f1 .\" index@buffering, assign to a stream file@@@\f3setbuf(3S)\f1 .\" index@stream file, assign buffering to a@@@\f3setbuf(3S)\f1 .\" index@file: assign buffering to a stream file@@@\f3setbuf(3S)\f1 .\" .\" toc@\f3setbuf(3S)\f1:\0\0\f4setbuf()\fP, \f4setvbuf()\fP@@@assign buffering to a stream file .\" toc@\f4setvbuf()\fP:\0\0assign buffering to a stream file@@@see \f3setbuf(3S)\f1 .\" .\" links@setbuf.3s setvbuf.3s .\" links@setbuf.3s setvbuf_unl.3s .\" $Header: setbuf.3s,v 72.5 94/11/15 09:56:11 ssa Exp $ .TA s .TH setbuf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setbuf(\|), setvbuf(\|), setvbuf_unlocked(\|) \- assign buffering to a stream file .SH SYNOPSIS .C "#include " .PP .C "void setbuf(FILE *stream, char *buf);" .PP .C "int setvbuf(FILE *stream, char *buf, int type, size_t size);" .PP .C "int setvbuf_unlocked(FILE *stream, char *buf, int type, size_t size);" .SH DESCRIPTION .CR setbuf() can be used after a stream has been opened but before it is read or written. It causes the array pointed to by .I buf to be used instead of an automatically allocated buffer. If .I buf is the .SM NULL pointer input/output will be completely unbuffered. .PP A constant .CR BUFSIZ , defined in the .RC < stdio.h > header file, tells how big an array is needed: .IP .CR char buf[BUFSIZ]; .PP .CR setvbuf() can be used after a stream has been opened but before it is read or written. .I type determines how .I stream is to be buffered. Legal values for .I type (defined in .RC < stdio.h >) are: .RS .TP 12 .CR _IOFBF causes input/output to be fully buffered. .TP .CR _IOLBF causes output to be line buffered; the buffer will be flushed when a newline is written, the buffer is full, or input is requested. .TP .CR _IONBF causes input/output to be completely unbuffered. .RE .PP When an output stream is unbuffered, information is queued for writing on the destination file or terminal as soon as written; when it is buffered, many characters are saved up and written as a block. When the output stream is line-buffered, each line of output is queued for writing on the destination terminal as soon as the line is completed (that is, as soon as a new-line character is written or terminal input is requested). .CR fflush() can also be used to explicitly write the buffer. .PP If .I buf is not the .SM NULL pointer, the array it points to is used for buffering instead of an automatically allocated buffer (from .CR malloc() ). .I size specifies the size of the buffer to be used. The constant .CR BUFSIZ in .RC < stdio.h > is suggested as a good buffer size. If input/output is unbuffered, .I buf and .I size are ignored. .PP By default, output to a terminal is line buffered and all other input/output is fully buffered. .PP .CR setvbuf_unlocked() is identical to .CR setvbuf() except it does not perform any internal locking of the .I stream for multi-thread applications. .CR setvbuf_unlocked() can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH DIAGNOSTICS If an illegal value for .I type or .I size is provided, .CR setvbuf() " and " setvbuf_unlocked() return a non-zero value. Otherwise, the value returned will be zero. .SH NOTE A common source of error is allocating buffer space as an ``automatic'' variable in a code block, then failing to close the stream in the same block. .SH SEE ALSO flockfile(3S), fopen(3S), getc(3S), malloc(3C), putc(3S), stdio(3S). .SH STANDARDS CONFORMANCE .CR setbuf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR setvbuf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .\" .\" index@\f4setbuf()\fP, \f4setvbuf()\fP \- assign buffering to a stream file@@@\f3setbuf(3S)\f1 .\" index@assign buffering to a stream file@@@\f3setbuf(3S)\f1 .\" index@buffering, assign to a stream file@@@\f3setbuf(3S)\f1 .\" index@stream file, assign buffering to a@@@\f3setbuf(3S)\f1 .\" index@file: assign buffering to a stream file@@@\f3setbuf(3S)\f1 .\" .\" toc@\f3setbuf(3S)\f1:\0\0\f4setbuf()\fP, \f4setvbuf()\fP@@@assign buffering to a stream file .\" toc@\f4setvbuf()\fP:\0\0assign buffering to a stream file@@@see \f3setbuf(3S)\f1 .\" .\" links@setbuf.3s setvbuf.3s .\" links@setbuf.3s setvbuf_unl.3s .\" $Header: shl_load.3x,v 78.1 96/02/12 14:14:40 ssa Exp $ .TA s .TH shl_load 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shl_load(\|), shl_definesym(\|), shl_findsym(\|), shl_gethandle(\|), shl_getsymbols(\|), shl_unload(\|), shl_get(\|), shl_gethandle_r(\|), shl_get_r(\|) \- explicit load of shared libraries .SH SYNOPSIS .nf .C "#include " .PP .C "shl_t shl_load(const char *path, int flags, long address);" .PP .C "int shl_findsym(" .PD 0 .IP .C shl_t *handle, .C "const char *sym," .C "short type," .C "void *value" .PP .C ");" .PD .PP .C "int shl_definesym(" .nf .PD 0 .IP .C const char *sym, .C short type, .C long value, .C int flags .PP .C ");" .PD .PP .C "int shl_getsymbols(" .nf .PD 0 .IP .C shl_t handle, .C short type, .C int flags, .C void *(*memory) (), .C struct shl_symbol **symbols, .PP .C ");" .PD .fi .PP .C "int shl_unload(shl_t handle);" .PP .C "int shl_get(int index, struct shl_descriptor **desc);" .PP .C "int shl_gethandle(shl_t handle, struct shl_descriptor **desc);" .PP .C "int shl_get_r(int index, struct shl_descriptor *desc);" .PP .C "int shl_gethandle_r(shl_t handle, struct shl_descriptor *desc);" .SH DESCRIPTION These routines can be used to programmatically load and unload shared libraries, and to obtain information about the libraries (such as the addresses of symbols defined within them). The routines themselves are accessed by specifying the .C \-ldld option on the command line with the .C cc or .C ld command (see .IR cc (1) and .IR ld (1)). In addition, the .C \-E option to the .C ld command can be used to ensure that all symbols defined in the program are available to the loaded libraries. .PP Shared libraries are created by compiling source files with the .C \+z or .C \+Z (position-independent code) options, and linking the resultant object files with the .C \-b (create shared library) option. .TP 20 .C shl_load() Attaches the shared library named by .I path .C or the shared library name that is constructed by using the path part of .I path plus the shared library basename followed by the suffix .C .0 (e.g. .C /usr/lib/libname.0 ) to the process, along with all its dependent libraries. A .C .0 version is looked for first for those shared libraries that do not have internal names. See .IR ld (1)). The library is mapped at the specified .IR address . If .I address is .CR 0L , the system chooses an appropriate address for the library. This is the recommended practice because the system has the most complete knowledge of the address space; currently, the .I address field is ignored, and assumed to be .CR 0L . The flags argument is made up of several fields. One of the following must be specified: .RS .RS .TP 22 .C BIND_IMMEDIATE Resolve symbol references when the library is loaded. .TP .C BIND_DEFERRED Delay code symbol resolution until actual reference. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 22 .C BIND_FIRST Place the library at the head of the symbol search order. In default mode, the library and its dependent libraries are bound independently of each other (see .CR BIND_TOGETHER ). This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NONFATAL Default .C BIND_IMMEDIATE behavior is to treat all unsatisfied symbols as fatal. This flag allows binding of unsatisfied code symbols to be deferred until use. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NOSTART Do not call the initializers for the shared library when the library is loaded, nor on a future call to .CR shl_unload() ; by default, all the initializers registered with the specified library are invoked upon loading. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_VERBOSE Print verbose messages concerning possible unsatisfied symbols. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_RESTRICTED Restrict symbols visible to the library to those present at the time the library is loaded. This flag may not be supported in future 64-bit HP-UX releases. .TP .C DYNAMIC_PATH Allow the loader to dynamically search for the library specified by the .I path argument. The directories to be searched are determined by the .C +s and .C +b options of the .C ld command used when the program was linked. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_TOGETHER When used with .CR BIND_FIRST , the library being mapped and its dependent libraries will be bound together. This is the default behavior for all .C shl_load() requests not using .CR BIND_FIRST . This flag may not be supported in future 64-bit HP-UX releases. .RE .RE .IP If successful, .C shl_load() returns a handle which can be used in subsequent calls to .CR shl_findsym() , .CR shl_unload() , .CR shl_gethandle() , or .CR shl_gethandle_r() ; otherwise .SM NULL is returned. .TP .C shl_findsym() Obtains the address of an exported symbol .I sym from a shared library. The .I handle argument should be a pointer to the handle of a loaded shared library that was returned from a previous call to .C shl_load() or .CR shl_get() . If a pointer to .SM NULL is passed for this argument, .C shl_findsym() searches all currently loaded shared libraries and the program to find the symbol; otherwise .C shl_findsym() searches only the specified shared library. The return value of handle will be .SM NULL if the symbol found was generated via .CR shl_definesym() . Otherwise the handle of the library where the symbol was found is returned. The special handle .C PROG_HANDLE can be used to refer to the program itself, so that symbols exported from the program can also be accessed dynamically. The .I type argument specifies the expected type for the symbol, and should be one of the defined constants .CR TYPE_PROCEDURE , .CR TYPE_DATA , .CR TYPE_STORAGE , or .CR TYPE_UNDEFINED . The latter value suppresses type checking. (The first three constants may not be supported in future 64-bit HP-UX releases.) The address of the symbol is returned in the variable pointed to by .IR value . If a shared library contains multiple versions of the requested symbol, the latest version is returned. This routine returns 0 if successful; otherwise \(mi1 is returned. .TP .C shl_definesym() Adds a symbol to the shared library symbol table for the current process making it the most visible definition. If the .I value falls in the range of a currently loaded library, an association will be made and the symbol is undefined once the associated library is unloaded. The defined symbol can be overridden by a subsequent call to this routine or by loading a more visible library that provides a definition. Symbols overridden in this manner may become visible again if the overriding definition is removed. .IP Possible symbol types include: .RS .RS .TP 22 .C TYPE_PROCEDURE Symbol is a function. .TP .C TYPE_DATA Symbol is data. .RE .RE .IP Possible flag values include: None defined at the present time. Zero should be passed in to prevent conflicts with future uses of this flag. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_getsymbols() Provides an array of symbol records, allocated using the supplied memory allocator, that are associated with the library specified by .IR handle . If the .I handle argument is a pointer to .SM NULL, symbols defined using .C shl_definesym() are returned. If multiple versions of the same symbol have been defined within a library or with .CR shl_definesym() , only the version from the specified symbol information source that would be considered for symbol binding is returned. The .I type argument is used to restrict the return information to a specific type. Values of .CR TYPE_PROCEDURE , .CR TYPE_DATA , and .C TYPE_STORAGE can be used to limit the returned symbols to be either code, data, or storage respectively; the .C TYPE_DATA value causes both data and storage symbols to be returned. The constant .C TYPE_UNDEFINED can be used to return all symbols, regardless of type. The .I flags argument must have one of the following values: .RS .RS .TP 15 .C IMPORT_SYMBOLS Return symbols found on the import list. .TP .C EXPORT_SYMBOLS Return symbols found on the export list. All symbols defined by .C shl_definesym() are export symbols. .TP .C INITIALIZERS Return symbols that are specified as the initializers of the library. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 15 .C NO_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Do not calculate the value field in the return structure to avoid symbol binding by the loader to resolve symbol dependencies. If only a few symbol values are needed, .C shl_findsym() can be used to find the values of interesting symbols. Not to be used with .CR GLOBAL_VALUES . .TP .C GLOBAL_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Use the name and type information of each return symbol and find the most visible occurrence using all symbol information sources. The value and handle fields in the symbol return structure reflect where the most visible occurrence was found. Not to be used with .CR NO_VALUES . .RE .RE .IP The .I memory argument should point to a function with the same interface as .C malloc() (see .IR malloc (3C)). .IP The return information consists of an array of the following records (defined in .RC < dl.h >): .RS .nf .IP .C "struct shl_symbol {" .C " char *name," .C " short type," .C " void *value," .C " shl_t handle," .C }; .fi .RE .IP The .I type field in the return structure can have the values .CR TYPE_PROCEDURE , .CR TYPE_DATA , or .CR TYPE_STORAGE , where .C TYPE_STORAGE is a subset of .CR TYPE_DATA . The .I value and .I handle fields are only valid if export symbols are requested and the .C NO_VALUES flag is not specified. The .I value field contains the address of the symbol, while the .I handle field is the handle of the library that defined the symbol, or .SM NULL for symbols defined via the .C shl_definesym() routine and is useful in conjunction with the .C GLOBAL_VALUES flag. .IP If successful, .C shl_getsymbols() returns the number of symbols found; otherwise it returns \(mi1. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_unload() Can be used to detach a shared library from the process. The .I handle argument should be the handle returned from a previous call to .CR shl_load() . .C shl_unload() returns 0 if successful; otherwise \(mi1 is returned. Any initializers registered with the library are called before detachment. All explicitly loaded libraries are detached automatically on process termination. .TP .C shl_get() Returns information about currently loaded libraries, including those loaded implicitly at startup time. The index argument is the ordinal position of the shared library in the shared library search list for the process. A subsequent call to .C shl_unload() decrements the index values of all libraries having an index greater than the unloaded library. The index value \(mi1 refers to the dynamic loader. The .I desc argument is used to return a pointer to a statically allocated buffer containing a descriptor for the shared library. The format of the descriptor is implementation dependent; to examine its format, look at the contents of file .CR /usr/include/dl.h . Information common to all implementations includes the library handle, pathname, and the range of addresses the library occupies. The buffer for the descriptor used by .C shl_get() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 if an invalid .I index is given. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle() Returns information about the library specified by the handle argument. The special handle .C PROG_HANDLE can be used to refer to the program itself. The descriptor returned is the same as the one returned by the .C shl_get() routine. The buffer for the descriptor used by .C shl_gethandle() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 on error. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_get_r() This is a reentrant version of .CR shl_get() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_get() . This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle_r() This is a reentrant version of .CR shl_gethandle() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_gethandle() . This routine may not be supported in future 64-bit HP-UX releases. .SH DIAGNOSTICS If a library cannot be loaded, .C shl_load() returns .SM NULL and sets .C errno to indicate the error. All other functions return \(mi1 on error and set .CR errno . .PP If .C shl_findsym() cannot find the indicated symbol, .C errno is set to zero. If .C shl_findsym() finds the indicated symbol but cannot resolve all the symbols it depends on, .C errno is set to .SM ENOSYM. .SH ERRORS Possible values for .C errno include: .RS .TP 15 .SM [ENOEXEC] The specified file is not a shared library, or a format error was detected. .TP .SM [ENOSYM] Some symbol required by the shared library could not be found. .TP .SM [EINVAL] The specified handle or index is not valid or an attempt was made to load a library at an invalid address. .TP .SM [ENOMEM] There is insufficient room in the address space to load the library. .TP .SM [ENOENT] The specified library does not exist. .TP .SM [EACCES] Read or execute permission is denied for the specified library. .RE .SH WARNINGS .C shl_unload() detaches the library from the process and frees the memory allocated for it, but does not break existing symbolic linkages into the library. In this respect, an unloaded shared library is much like a block of memory deallocated via .C free() (see .IR free (3C)). .PP Some implementations may not, by default, export all symbols defined by a program (instead exporting only those symbols that are imported by a shared library seen at link time). Therefore the .C -E option to .IR ld (1) should be used when using these routines if the loaded libraries are to refer to program symbols. .PP All symbol information returned by .CR shl_getsymbols() , including the name field, become invalid once the associated library is unloaded by .CR shl_unload() . .PP When a routine or flag is used which may not be supported in the future, the dynamic loader can display a warning message. See the .CR WARNINGS section in .IR dld.sl (5) for further details. .PP Future HP-UX 64-bit environments may only support a subset of these routines and flags. Instead, they will use the SVR4 dynamic loading API. .SH AUTHOR .IR shl_load (3X) and related functions were developed by HP. .SH SEE ALSO .PD .SS System Tools: .TP 18 ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 dld.sl(5) dynamic loader .PD .SS Texts and Tutorials .TP 18 .IR "HP-UX Linker and Libraries Online User Guide" (See the .CR +help option to .IR ld (1)) .TP .IR "Programming on HP-UX" (See .IR manuals (5) for ordering information) .PD .\" .\" index@\f4shl_load()\fP \- load shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_unload()\fP \- unload shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_findsym()\fP \- look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_get()\fP \- get information about shared library@@@\f3shl_load(3X)\f1 .\" index@shared library, load or unload@@@\f3shl_load(3X)\f1 .\" index@shared library, look up symbol in@@@\f3shl_load(3X)\f1 .\" index@load shared library@@@\f3shl_load(3X)\f1 .\" index@unload shared library@@@\f3shl_load(3X)\f1 .\" index@look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@symbol, look up in shared library@@@\f3shl_load(3X)\f1 .\" index@get information about shared library@@@\f3shl_load(3X)\f1 .\" index@explicit load of shared libraries@@@\f3shl_load(3X)\f1 .\" .\" toc@\f3shl_load(3X)\f1:\0\0\f4shl_load()\fP, \f4shl_findsym()\fP, \f4shl_unload()\fP, \f4shl_get()\fP@@@explicit load of shared libraries .\" toc@\f4shl_load()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_unload()\fP \- unload shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- get information about shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_definesym()\fP \- define new symbol for shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_get_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" .\" links@shl_load.3x shl_defines.3x .\" links@shl_load.3x shl_findsym.3x .\" links@shl_load.3x shl_gethand.3x .\" links@shl_load.3x shl_getsymb.3x .\" links@shl_load.3x shl_unload.3x .\" links@shl_load.3x shl_get.3x .\" links@shl_load.3x shl_get_r.3x .\" links@shl_load.3x shl_get_handle_r.3x .\" .\" $Header: shl_load.3x,v 78.1 96/02/12 14:14:40 ssa Exp $ .TA s .TH shl_load 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shl_load(\|), shl_definesym(\|), shl_findsym(\|), shl_gethandle(\|), shl_getsymbols(\|), shl_unload(\|), shl_get(\|), shl_gethandle_r(\|), shl_get_r(\|) \- explicit load of shared libraries .SH SYNOPSIS .nf .C "#include " .PP .C "shl_t shl_load(const char *path, int flags, long address);" .PP .C "int shl_findsym(" .PD 0 .IP .C shl_t *handle, .C "const char *sym," .C "short type," .C "void *value" .PP .C ");" .PD .PP .C "int shl_definesym(" .nf .PD 0 .IP .C const char *sym, .C short type, .C long value, .C int flags .PP .C ");" .PD .PP .C "int shl_getsymbols(" .nf .PD 0 .IP .C shl_t handle, .C short type, .C int flags, .C void *(*memory) (), .C struct shl_symbol **symbols, .PP .C ");" .PD .fi .PP .C "int shl_unload(shl_t handle);" .PP .C "int shl_get(int index, struct shl_descriptor **desc);" .PP .C "int shl_gethandle(shl_t handle, struct shl_descriptor **desc);" .PP .C "int shl_get_r(int index, struct shl_descriptor *desc);" .PP .C "int shl_gethandle_r(shl_t handle, struct shl_descriptor *desc);" .SH DESCRIPTION These routines can be used to programmatically load and unload shared libraries, and to obtain information about the libraries (such as the addresses of symbols defined within them). The routines themselves are accessed by specifying the .C \-ldld option on the command line with the .C cc or .C ld command (see .IR cc (1) and .IR ld (1)). In addition, the .C \-E option to the .C ld command can be used to ensure that all symbols defined in the program are available to the loaded libraries. .PP Shared libraries are created by compiling source files with the .C \+z or .C \+Z (position-independent code) options, and linking the resultant object files with the .C \-b (create shared library) option. .TP 20 .C shl_load() Attaches the shared library named by .I path .C or the shared library name that is constructed by using the path part of .I path plus the shared library basename followed by the suffix .C .0 (e.g. .C /usr/lib/libname.0 ) to the process, along with all its dependent libraries. A .C .0 version is looked for first for those shared libraries that do not have internal names. See .IR ld (1)). The library is mapped at the specified .IR address . If .I address is .CR 0L , the system chooses an appropriate address for the library. This is the recommended practice because the system has the most complete knowledge of the address space; currently, the .I address field is ignored, and assumed to be .CR 0L . The flags argument is made up of several fields. One of the following must be specified: .RS .RS .TP 22 .C BIND_IMMEDIATE Resolve symbol references when the library is loaded. .TP .C BIND_DEFERRED Delay code symbol resolution until actual reference. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 22 .C BIND_FIRST Place the library at the head of the symbol search order. In default mode, the library and its dependent libraries are bound independently of each other (see .CR BIND_TOGETHER ). This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NONFATAL Default .C BIND_IMMEDIATE behavior is to treat all unsatisfied symbols as fatal. This flag allows binding of unsatisfied code symbols to be deferred until use. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NOSTART Do not call the initializers for the shared library when the library is loaded, nor on a future call to .CR shl_unload() ; by default, all the initializers registered with the specified library are invoked upon loading. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_VERBOSE Print verbose messages concerning possible unsatisfied symbols. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_RESTRICTED Restrict symbols visible to the library to those present at the time the library is loaded. This flag may not be supported in future 64-bit HP-UX releases. .TP .C DYNAMIC_PATH Allow the loader to dynamically search for the library specified by the .I path argument. The directories to be searched are determined by the .C +s and .C +b options of the .C ld command used when the program was linked. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_TOGETHER When used with .CR BIND_FIRST , the library being mapped and its dependent libraries will be bound together. This is the default behavior for all .C shl_load() requests not using .CR BIND_FIRST . This flag may not be supported in future 64-bit HP-UX releases. .RE .RE .IP If successful, .C shl_load() returns a handle which can be used in subsequent calls to .CR shl_findsym() , .CR shl_unload() , .CR shl_gethandle() , or .CR shl_gethandle_r() ; otherwise .SM NULL is returned. .TP .C shl_findsym() Obtains the address of an exported symbol .I sym from a shared library. The .I handle argument should be a pointer to the handle of a loaded shared library that was returned from a previous call to .C shl_load() or .CR shl_get() . If a pointer to .SM NULL is passed for this argument, .C shl_findsym() searches all currently loaded shared libraries and the program to find the symbol; otherwise .C shl_findsym() searches only the specified shared library. The return value of handle will be .SM NULL if the symbol found was generated via .CR shl_definesym() . Otherwise the handle of the library where the symbol was found is returned. The special handle .C PROG_HANDLE can be used to refer to the program itself, so that symbols exported from the program can also be accessed dynamically. The .I type argument specifies the expected type for the symbol, and should be one of the defined constants .CR TYPE_PROCEDURE , .CR TYPE_DATA , .CR TYPE_STORAGE , or .CR TYPE_UNDEFINED . The latter value suppresses type checking. (The first three constants may not be supported in future 64-bit HP-UX releases.) The address of the symbol is returned in the variable pointed to by .IR value . If a shared library contains multiple versions of the requested symbol, the latest version is returned. This routine returns 0 if successful; otherwise \(mi1 is returned. .TP .C shl_definesym() Adds a symbol to the shared library symbol table for the current process making it the most visible definition. If the .I value falls in the range of a currently loaded library, an association will be made and the symbol is undefined once the associated library is unloaded. The defined symbol can be overridden by a subsequent call to this routine or by loading a more visible library that provides a definition. Symbols overridden in this manner may become visible again if the overriding definition is removed. .IP Possible symbol types include: .RS .RS .TP 22 .C TYPE_PROCEDURE Symbol is a function. .TP .C TYPE_DATA Symbol is data. .RE .RE .IP Possible flag values include: None defined at the present time. Zero should be passed in to prevent conflicts with future uses of this flag. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_getsymbols() Provides an array of symbol records, allocated using the supplied memory allocator, that are associated with the library specified by .IR handle . If the .I handle argument is a pointer to .SM NULL, symbols defined using .C shl_definesym() are returned. If multiple versions of the same symbol have been defined within a library or with .CR shl_definesym() , only the version from the specified symbol information source that would be considered for symbol binding is returned. The .I type argument is used to restrict the return information to a specific type. Values of .CR TYPE_PROCEDURE , .CR TYPE_DATA , and .C TYPE_STORAGE can be used to limit the returned symbols to be either code, data, or storage respectively; the .C TYPE_DATA value causes both data and storage symbols to be returned. The constant .C TYPE_UNDEFINED can be used to return all symbols, regardless of type. The .I flags argument must have one of the following values: .RS .RS .TP 15 .C IMPORT_SYMBOLS Return symbols found on the import list. .TP .C EXPORT_SYMBOLS Return symbols found on the export list. All symbols defined by .C shl_definesym() are export symbols. .TP .C INITIALIZERS Return symbols that are specified as the initializers of the library. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 15 .C NO_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Do not calculate the value field in the return structure to avoid symbol binding by the loader to resolve symbol dependencies. If only a few symbol values are needed, .C shl_findsym() can be used to find the values of interesting symbols. Not to be used with .CR GLOBAL_VALUES . .TP .C GLOBAL_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Use the name and type information of each return symbol and find the most visible occurrence using all symbol information sources. The value and handle fields in the symbol return structure reflect where the most visible occurrence was found. Not to be used with .CR NO_VALUES . .RE .RE .IP The .I memory argument should point to a function with the same interface as .C malloc() (see .IR malloc (3C)). .IP The return information consists of an array of the following records (defined in .RC < dl.h >): .RS .nf .IP .C "struct shl_symbol {" .C " char *name," .C " short type," .C " void *value," .C " shl_t handle," .C }; .fi .RE .IP The .I type field in the return structure can have the values .CR TYPE_PROCEDURE , .CR TYPE_DATA , or .CR TYPE_STORAGE , where .C TYPE_STORAGE is a subset of .CR TYPE_DATA . The .I value and .I handle fields are only valid if export symbols are requested and the .C NO_VALUES flag is not specified. The .I value field contains the address of the symbol, while the .I handle field is the handle of the library that defined the symbol, or .SM NULL for symbols defined via the .C shl_definesym() routine and is useful in conjunction with the .C GLOBAL_VALUES flag. .IP If successful, .C shl_getsymbols() returns the number of symbols found; otherwise it returns \(mi1. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_unload() Can be used to detach a shared library from the process. The .I handle argument should be the handle returned from a previous call to .CR shl_load() . .C shl_unload() returns 0 if successful; otherwise \(mi1 is returned. Any initializers registered with the library are called before detachment. All explicitly loaded libraries are detached automatically on process termination. .TP .C shl_get() Returns information about currently loaded libraries, including those loaded implicitly at startup time. The index argument is the ordinal position of the shared library in the shared library search list for the process. A subsequent call to .C shl_unload() decrements the index values of all libraries having an index greater than the unloaded library. The index value \(mi1 refers to the dynamic loader. The .I desc argument is used to return a pointer to a statically allocated buffer containing a descriptor for the shared library. The format of the descriptor is implementation dependent; to examine its format, look at the contents of file .CR /usr/include/dl.h . Information common to all implementations includes the library handle, pathname, and the range of addresses the library occupies. The buffer for the descriptor used by .C shl_get() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 if an invalid .I index is given. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle() Returns information about the library specified by the handle argument. The special handle .C PROG_HANDLE can be used to refer to the program itself. The descriptor returned is the same as the one returned by the .C shl_get() routine. The buffer for the descriptor used by .C shl_gethandle() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 on error. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_get_r() This is a reentrant version of .CR shl_get() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_get() . This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle_r() This is a reentrant version of .CR shl_gethandle() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_gethandle() . This routine may not be supported in future 64-bit HP-UX releases. .SH DIAGNOSTICS If a library cannot be loaded, .C shl_load() returns .SM NULL and sets .C errno to indicate the error. All other functions return \(mi1 on error and set .CR errno . .PP If .C shl_findsym() cannot find the indicated symbol, .C errno is set to zero. If .C shl_findsym() finds the indicated symbol but cannot resolve all the symbols it depends on, .C errno is set to .SM ENOSYM. .SH ERRORS Possible values for .C errno include: .RS .TP 15 .SM [ENOEXEC] The specified file is not a shared library, or a format error was detected. .TP .SM [ENOSYM] Some symbol required by the shared library could not be found. .TP .SM [EINVAL] The specified handle or index is not valid or an attempt was made to load a library at an invalid address. .TP .SM [ENOMEM] There is insufficient room in the address space to load the library. .TP .SM [ENOENT] The specified library does not exist. .TP .SM [EACCES] Read or execute permission is denied for the specified library. .RE .SH WARNINGS .C shl_unload() detaches the library from the process and frees the memory allocated for it, but does not break existing symbolic linkages into the library. In this respect, an unloaded shared library is much like a block of memory deallocated via .C free() (see .IR free (3C)). .PP Some implementations may not, by default, export all symbols defined by a program (instead exporting only those symbols that are imported by a shared library seen at link time). Therefore the .C -E option to .IR ld (1) should be used when using these routines if the loaded libraries are to refer to program symbols. .PP All symbol information returned by .CR shl_getsymbols() , including the name field, become invalid once the associated library is unloaded by .CR shl_unload() . .PP When a routine or flag is used which may not be supported in the future, the dynamic loader can display a warning message. See the .CR WARNINGS section in .IR dld.sl (5) for further details. .PP Future HP-UX 64-bit environments may only support a subset of these routines and flags. Instead, they will use the SVR4 dynamic loading API. .SH AUTHOR .IR shl_load (3X) and related functions were developed by HP. .SH SEE ALSO .PD .SS System Tools: .TP 18 ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 dld.sl(5) dynamic loader .PD .SS Texts and Tutorials .TP 18 .IR "HP-UX Linker and Libraries Online User Guide" (See the .CR +help option to .IR ld (1)) .TP .IR "Programming on HP-UX" (See .IR manuals (5) for ordering information) .PD .\" .\" index@\f4shl_load()\fP \- load shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_unload()\fP \- unload shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_findsym()\fP \- look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_get()\fP \- get information about shared library@@@\f3shl_load(3X)\f1 .\" index@shared library, load or unload@@@\f3shl_load(3X)\f1 .\" index@shared library, look up symbol in@@@\f3shl_load(3X)\f1 .\" index@load shared library@@@\f3shl_load(3X)\f1 .\" index@unload shared library@@@\f3shl_load(3X)\f1 .\" index@look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@symbol, look up in shared library@@@\f3shl_load(3X)\f1 .\" index@get information about shared library@@@\f3shl_load(3X)\f1 .\" index@explicit load of shared libraries@@@\f3shl_load(3X)\f1 .\" .\" toc@\f3shl_load(3X)\f1:\0\0\f4shl_load()\fP, \f4shl_findsym()\fP, \f4shl_unload()\fP, \f4shl_get()\fP@@@explicit load of shared libraries .\" toc@\f4shl_load()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_unload()\fP \- unload shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- get information about shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_definesym()\fP \- define new symbol for shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_get_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" .\" links@shl_load.3x shl_defines.3x .\" links@shl_load.3x shl_findsym.3x .\" links@shl_load.3x shl_gethand.3x .\" links@shl_load.3x shl_getsymb.3x .\" links@shl_load.3x shl_unload.3x .\" links@shl_load.3x shl_get.3x .\" links@shl_load.3x shl_get_r.3x .\" links@shl_load.3x shl_get_handle_r.3x .\" .\" $Header: shl_load.3x,v 78.1 96/02/12 14:14:40 ssa Exp $ .TA s .TH shl_load 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shl_load(\|), shl_definesym(\|), shl_findsym(\|), shl_gethandle(\|), shl_getsymbols(\|), shl_unload(\|), shl_get(\|), shl_gethandle_r(\|), shl_get_r(\|) \- explicit load of shared libraries .SH SYNOPSIS .nf .C "#include " .PP .C "shl_t shl_load(const char *path, int flags, long address);" .PP .C "int shl_findsym(" .PD 0 .IP .C shl_t *handle, .C "const char *sym," .C "short type," .C "void *value" .PP .C ");" .PD .PP .C "int shl_definesym(" .nf .PD 0 .IP .C const char *sym, .C short type, .C long value, .C int flags .PP .C ");" .PD .PP .C "int shl_getsymbols(" .nf .PD 0 .IP .C shl_t handle, .C short type, .C int flags, .C void *(*memory) (), .C struct shl_symbol **symbols, .PP .C ");" .PD .fi .PP .C "int shl_unload(shl_t handle);" .PP .C "int shl_get(int index, struct shl_descriptor **desc);" .PP .C "int shl_gethandle(shl_t handle, struct shl_descriptor **desc);" .PP .C "int shl_get_r(int index, struct shl_descriptor *desc);" .PP .C "int shl_gethandle_r(shl_t handle, struct shl_descriptor *desc);" .SH DESCRIPTION These routines can be used to programmatically load and unload shared libraries, and to obtain information about the libraries (such as the addresses of symbols defined within them). The routines themselves are accessed by specifying the .C \-ldld option on the command line with the .C cc or .C ld command (see .IR cc (1) and .IR ld (1)). In addition, the .C \-E option to the .C ld command can be used to ensure that all symbols defined in the program are available to the loaded libraries. .PP Shared libraries are created by compiling source files with the .C \+z or .C \+Z (position-independent code) options, and linking the resultant object files with the .C \-b (create shared library) option. .TP 20 .C shl_load() Attaches the shared library named by .I path .C or the shared library name that is constructed by using the path part of .I path plus the shared library basename followed by the suffix .C .0 (e.g. .C /usr/lib/libname.0 ) to the process, along with all its dependent libraries. A .C .0 version is looked for first for those shared libraries that do not have internal names. See .IR ld (1)). The library is mapped at the specified .IR address . If .I address is .CR 0L , the system chooses an appropriate address for the library. This is the recommended practice because the system has the most complete knowledge of the address space; currently, the .I address field is ignored, and assumed to be .CR 0L . The flags argument is made up of several fields. One of the following must be specified: .RS .RS .TP 22 .C BIND_IMMEDIATE Resolve symbol references when the library is loaded. .TP .C BIND_DEFERRED Delay code symbol resolution until actual reference. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 22 .C BIND_FIRST Place the library at the head of the symbol search order. In default mode, the library and its dependent libraries are bound independently of each other (see .CR BIND_TOGETHER ). This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NONFATAL Default .C BIND_IMMEDIATE behavior is to treat all unsatisfied symbols as fatal. This flag allows binding of unsatisfied code symbols to be deferred until use. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NOSTART Do not call the initializers for the shared library when the library is loaded, nor on a future call to .CR shl_unload() ; by default, all the initializers registered with the specified library are invoked upon loading. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_VERBOSE Print verbose messages concerning possible unsatisfied symbols. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_RESTRICTED Restrict symbols visible to the library to those present at the time the library is loaded. This flag may not be supported in future 64-bit HP-UX releases. .TP .C DYNAMIC_PATH Allow the loader to dynamically search for the library specified by the .I path argument. The directories to be searched are determined by the .C +s and .C +b options of the .C ld command used when the program was linked. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_TOGETHER When used with .CR BIND_FIRST , the library being mapped and its dependent libraries will be bound together. This is the default behavior for all .C shl_load() requests not using .CR BIND_FIRST . This flag may not be supported in future 64-bit HP-UX releases. .RE .RE .IP If successful, .C shl_load() returns a handle which can be used in subsequent calls to .CR shl_findsym() , .CR shl_unload() , .CR shl_gethandle() , or .CR shl_gethandle_r() ; otherwise .SM NULL is returned. .TP .C shl_findsym() Obtains the address of an exported symbol .I sym from a shared library. The .I handle argument should be a pointer to the handle of a loaded shared library that was returned from a previous call to .C shl_load() or .CR shl_get() . If a pointer to .SM NULL is passed for this argument, .C shl_findsym() searches all currently loaded shared libraries and the program to find the symbol; otherwise .C shl_findsym() searches only the specified shared library. The return value of handle will be .SM NULL if the symbol found was generated via .CR shl_definesym() . Otherwise the handle of the library where the symbol was found is returned. The special handle .C PROG_HANDLE can be used to refer to the program itself, so that symbols exported from the program can also be accessed dynamically. The .I type argument specifies the expected type for the symbol, and should be one of the defined constants .CR TYPE_PROCEDURE , .CR TYPE_DATA , .CR TYPE_STORAGE , or .CR TYPE_UNDEFINED . The latter value suppresses type checking. (The first three constants may not be supported in future 64-bit HP-UX releases.) The address of the symbol is returned in the variable pointed to by .IR value . If a shared library contains multiple versions of the requested symbol, the latest version is returned. This routine returns 0 if successful; otherwise \(mi1 is returned. .TP .C shl_definesym() Adds a symbol to the shared library symbol table for the current process making it the most visible definition. If the .I value falls in the range of a currently loaded library, an association will be made and the symbol is undefined once the associated library is unloaded. The defined symbol can be overridden by a subsequent call to this routine or by loading a more visible library that provides a definition. Symbols overridden in this manner may become visible again if the overriding definition is removed. .IP Possible symbol types include: .RS .RS .TP 22 .C TYPE_PROCEDURE Symbol is a function. .TP .C TYPE_DATA Symbol is data. .RE .RE .IP Possible flag values include: None defined at the present time. Zero should be passed in to prevent conflicts with future uses of this flag. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_getsymbols() Provides an array of symbol records, allocated using the supplied memory allocator, that are associated with the library specified by .IR handle . If the .I handle argument is a pointer to .SM NULL, symbols defined using .C shl_definesym() are returned. If multiple versions of the same symbol have been defined within a library or with .CR shl_definesym() , only the version from the specified symbol information source that would be considered for symbol binding is returned. The .I type argument is used to restrict the return information to a specific type. Values of .CR TYPE_PROCEDURE , .CR TYPE_DATA , and .C TYPE_STORAGE can be used to limit the returned symbols to be either code, data, or storage respectively; the .C TYPE_DATA value causes both data and storage symbols to be returned. The constant .C TYPE_UNDEFINED can be used to return all symbols, regardless of type. The .I flags argument must have one of the following values: .RS .RS .TP 15 .C IMPORT_SYMBOLS Return symbols found on the import list. .TP .C EXPORT_SYMBOLS Return symbols found on the export list. All symbols defined by .C shl_definesym() are export symbols. .TP .C INITIALIZERS Return symbols that are specified as the initializers of the library. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 15 .C NO_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Do not calculate the value field in the return structure to avoid symbol binding by the loader to resolve symbol dependencies. If only a few symbol values are needed, .C shl_findsym() can be used to find the values of interesting symbols. Not to be used with .CR GLOBAL_VALUES . .TP .C GLOBAL_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Use the name and type information of each return symbol and find the most visible occurrence using all symbol information sources. The value and handle fields in the symbol return structure reflect where the most visible occurrence was found. Not to be used with .CR NO_VALUES . .RE .RE .IP The .I memory argument should point to a function with the same interface as .C malloc() (see .IR malloc (3C)). .IP The return information consists of an array of the following records (defined in .RC < dl.h >): .RS .nf .IP .C "struct shl_symbol {" .C " char *name," .C " short type," .C " void *value," .C " shl_t handle," .C }; .fi .RE .IP The .I type field in the return structure can have the values .CR TYPE_PROCEDURE , .CR TYPE_DATA , or .CR TYPE_STORAGE , where .C TYPE_STORAGE is a subset of .CR TYPE_DATA . The .I value and .I handle fields are only valid if export symbols are requested and the .C NO_VALUES flag is not specified. The .I value field contains the address of the symbol, while the .I handle field is the handle of the library that defined the symbol, or .SM NULL for symbols defined via the .C shl_definesym() routine and is useful in conjunction with the .C GLOBAL_VALUES flag. .IP If successful, .C shl_getsymbols() returns the number of symbols found; otherwise it returns \(mi1. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_unload() Can be used to detach a shared library from the process. The .I handle argument should be the handle returned from a previous call to .CR shl_load() . .C shl_unload() returns 0 if successful; otherwise \(mi1 is returned. Any initializers registered with the library are called before detachment. All explicitly loaded libraries are detached automatically on process termination. .TP .C shl_get() Returns information about currently loaded libraries, including those loaded implicitly at startup time. The index argument is the ordinal position of the shared library in the shared library search list for the process. A subsequent call to .C shl_unload() decrements the index values of all libraries having an index greater than the unloaded library. The index value \(mi1 refers to the dynamic loader. The .I desc argument is used to return a pointer to a statically allocated buffer containing a descriptor for the shared library. The format of the descriptor is implementation dependent; to examine its format, look at the contents of file .CR /usr/include/dl.h . Information common to all implementations includes the library handle, pathname, and the range of addresses the library occupies. The buffer for the descriptor used by .C shl_get() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 if an invalid .I index is given. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle() Returns information about the library specified by the handle argument. The special handle .C PROG_HANDLE can be used to refer to the program itself. The descriptor returned is the same as the one returned by the .C shl_get() routine. The buffer for the descriptor used by .C shl_gethandle() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 on error. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_get_r() This is a reentrant version of .CR shl_get() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_get() . This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle_r() This is a reentrant version of .CR shl_gethandle() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_gethandle() . This routine may not be supported in future 64-bit HP-UX releases. .SH DIAGNOSTICS If a library cannot be loaded, .C shl_load() returns .SM NULL and sets .C errno to indicate the error. All other functions return \(mi1 on error and set .CR errno . .PP If .C shl_findsym() cannot find the indicated symbol, .C errno is set to zero. If .C shl_findsym() finds the indicated symbol but cannot resolve all the symbols it depends on, .C errno is set to .SM ENOSYM. .SH ERRORS Possible values for .C errno include: .RS .TP 15 .SM [ENOEXEC] The specified file is not a shared library, or a format error was detected. .TP .SM [ENOSYM] Some symbol required by the shared library could not be found. .TP .SM [EINVAL] The specified handle or index is not valid or an attempt was made to load a library at an invalid address. .TP .SM [ENOMEM] There is insufficient room in the address space to load the library. .TP .SM [ENOENT] The specified library does not exist. .TP .SM [EACCES] Read or execute permission is denied for the specified library. .RE .SH WARNINGS .C shl_unload() detaches the library from the process and frees the memory allocated for it, but does not break existing symbolic linkages into the library. In this respect, an unloaded shared library is much like a block of memory deallocated via .C free() (see .IR free (3C)). .PP Some implementations may not, by default, export all symbols defined by a program (instead exporting only those symbols that are imported by a shared library seen at link time). Therefore the .C -E option to .IR ld (1) should be used when using these routines if the loaded libraries are to refer to program symbols. .PP All symbol information returned by .CR shl_getsymbols() , including the name field, become invalid once the associated library is unloaded by .CR shl_unload() . .PP When a routine or flag is used which may not be supported in the future, the dynamic loader can display a warning message. See the .CR WARNINGS section in .IR dld.sl (5) for further details. .PP Future HP-UX 64-bit environments may only support a subset of these routines and flags. Instead, they will use the SVR4 dynamic loading API. .SH AUTHOR .IR shl_load (3X) and related functions were developed by HP. .SH SEE ALSO .PD .SS System Tools: .TP 18 ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 dld.sl(5) dynamic loader .PD .SS Texts and Tutorials .TP 18 .IR "HP-UX Linker and Libraries Online User Guide" (See the .CR +help option to .IR ld (1)) .TP .IR "Programming on HP-UX" (See .IR manuals (5) for ordering information) .PD .\" .\" index@\f4shl_load()\fP \- load shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_unload()\fP \- unload shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_findsym()\fP \- look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_get()\fP \- get information about shared library@@@\f3shl_load(3X)\f1 .\" index@shared library, load or unload@@@\f3shl_load(3X)\f1 .\" index@shared library, look up symbol in@@@\f3shl_load(3X)\f1 .\" index@load shared library@@@\f3shl_load(3X)\f1 .\" index@unload shared library@@@\f3shl_load(3X)\f1 .\" index@look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@symbol, look up in shared library@@@\f3shl_load(3X)\f1 .\" index@get information about shared library@@@\f3shl_load(3X)\f1 .\" index@explicit load of shared libraries@@@\f3shl_load(3X)\f1 .\" .\" toc@\f3shl_load(3X)\f1:\0\0\f4shl_load()\fP, \f4shl_findsym()\fP, \f4shl_unload()\fP, \f4shl_get()\fP@@@explicit load of shared libraries .\" toc@\f4shl_load()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_unload()\fP \- unload shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- get information about shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_definesym()\fP \- define new symbol for shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_get_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" .\" links@shl_load.3x shl_defines.3x .\" links@shl_load.3x shl_findsym.3x .\" links@shl_load.3x shl_gethand.3x .\" links@shl_load.3x shl_getsymb.3x .\" links@shl_load.3x shl_unload.3x .\" links@shl_load.3x shl_get.3x .\" links@shl_load.3x shl_get_r.3x .\" links@shl_load.3x shl_get_handle_r.3x .\" .\" $Header: shl_load.3x,v 78.1 96/02/12 14:14:40 ssa Exp $ .TA s .TH shl_load 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shl_load(\|), shl_definesym(\|), shl_findsym(\|), shl_gethandle(\|), shl_getsymbols(\|), shl_unload(\|), shl_get(\|), shl_gethandle_r(\|), shl_get_r(\|) \- explicit load of shared libraries .SH SYNOPSIS .nf .C "#include " .PP .C "shl_t shl_load(const char *path, int flags, long address);" .PP .C "int shl_findsym(" .PD 0 .IP .C shl_t *handle, .C "const char *sym," .C "short type," .C "void *value" .PP .C ");" .PD .PP .C "int shl_definesym(" .nf .PD 0 .IP .C const char *sym, .C short type, .C long value, .C int flags .PP .C ");" .PD .PP .C "int shl_getsymbols(" .nf .PD 0 .IP .C shl_t handle, .C short type, .C int flags, .C void *(*memory) (), .C struct shl_symbol **symbols, .PP .C ");" .PD .fi .PP .C "int shl_unload(shl_t handle);" .PP .C "int shl_get(int index, struct shl_descriptor **desc);" .PP .C "int shl_gethandle(shl_t handle, struct shl_descriptor **desc);" .PP .C "int shl_get_r(int index, struct shl_descriptor *desc);" .PP .C "int shl_gethandle_r(shl_t handle, struct shl_descriptor *desc);" .SH DESCRIPTION These routines can be used to programmatically load and unload shared libraries, and to obtain information about the libraries (such as the addresses of symbols defined within them). The routines themselves are accessed by specifying the .C \-ldld option on the command line with the .C cc or .C ld command (see .IR cc (1) and .IR ld (1)). In addition, the .C \-E option to the .C ld command can be used to ensure that all symbols defined in the program are available to the loaded libraries. .PP Shared libraries are created by compiling source files with the .C \+z or .C \+Z (position-independent code) options, and linking the resultant object files with the .C \-b (create shared library) option. .TP 20 .C shl_load() Attaches the shared library named by .I path .C or the shared library name that is constructed by using the path part of .I path plus the shared library basename followed by the suffix .C .0 (e.g. .C /usr/lib/libname.0 ) to the process, along with all its dependent libraries. A .C .0 version is looked for first for those shared libraries that do not have internal names. See .IR ld (1)). The library is mapped at the specified .IR address . If .I address is .CR 0L , the system chooses an appropriate address for the library. This is the recommended practice because the system has the most complete knowledge of the address space; currently, the .I address field is ignored, and assumed to be .CR 0L . The flags argument is made up of several fields. One of the following must be specified: .RS .RS .TP 22 .C BIND_IMMEDIATE Resolve symbol references when the library is loaded. .TP .C BIND_DEFERRED Delay code symbol resolution until actual reference. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 22 .C BIND_FIRST Place the library at the head of the symbol search order. In default mode, the library and its dependent libraries are bound independently of each other (see .CR BIND_TOGETHER ). This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NONFATAL Default .C BIND_IMMEDIATE behavior is to treat all unsatisfied symbols as fatal. This flag allows binding of unsatisfied code symbols to be deferred until use. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NOSTART Do not call the initializers for the shared library when the library is loaded, nor on a future call to .CR shl_unload() ; by default, all the initializers registered with the specified library are invoked upon loading. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_VERBOSE Print verbose messages concerning possible unsatisfied symbols. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_RESTRICTED Restrict symbols visible to the library to those present at the time the library is loaded. This flag may not be supported in future 64-bit HP-UX releases. .TP .C DYNAMIC_PATH Allow the loader to dynamically search for the library specified by the .I path argument. The directories to be searched are determined by the .C +s and .C +b options of the .C ld command used when the program was linked. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_TOGETHER When used with .CR BIND_FIRST , the library being mapped and its dependent libraries will be bound together. This is the default behavior for all .C shl_load() requests not using .CR BIND_FIRST . This flag may not be supported in future 64-bit HP-UX releases. .RE .RE .IP If successful, .C shl_load() returns a handle which can be used in subsequent calls to .CR shl_findsym() , .CR shl_unload() , .CR shl_gethandle() , or .CR shl_gethandle_r() ; otherwise .SM NULL is returned. .TP .C shl_findsym() Obtains the address of an exported symbol .I sym from a shared library. The .I handle argument should be a pointer to the handle of a loaded shared library that was returned from a previous call to .C shl_load() or .CR shl_get() . If a pointer to .SM NULL is passed for this argument, .C shl_findsym() searches all currently loaded shared libraries and the program to find the symbol; otherwise .C shl_findsym() searches only the specified shared library. The return value of handle will be .SM NULL if the symbol found was generated via .CR shl_definesym() . Otherwise the handle of the library where the symbol was found is returned. The special handle .C PROG_HANDLE can be used to refer to the program itself, so that symbols exported from the program can also be accessed dynamically. The .I type argument specifies the expected type for the symbol, and should be one of the defined constants .CR TYPE_PROCEDURE , .CR TYPE_DATA , .CR TYPE_STORAGE , or .CR TYPE_UNDEFINED . The latter value suppresses type checking. (The first three constants may not be supported in future 64-bit HP-UX releases.) The address of the symbol is returned in the variable pointed to by .IR value . If a shared library contains multiple versions of the requested symbol, the latest version is returned. This routine returns 0 if successful; otherwise \(mi1 is returned. .TP .C shl_definesym() Adds a symbol to the shared library symbol table for the current process making it the most visible definition. If the .I value falls in the range of a currently loaded library, an association will be made and the symbol is undefined once the associated library is unloaded. The defined symbol can be overridden by a subsequent call to this routine or by loading a more visible library that provides a definition. Symbols overridden in this manner may become visible again if the overriding definition is removed. .IP Possible symbol types include: .RS .RS .TP 22 .C TYPE_PROCEDURE Symbol is a function. .TP .C TYPE_DATA Symbol is data. .RE .RE .IP Possible flag values include: None defined at the present time. Zero should be passed in to prevent conflicts with future uses of this flag. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_getsymbols() Provides an array of symbol records, allocated using the supplied memory allocator, that are associated with the library specified by .IR handle . If the .I handle argument is a pointer to .SM NULL, symbols defined using .C shl_definesym() are returned. If multiple versions of the same symbol have been defined within a library or with .CR shl_definesym() , only the version from the specified symbol information source that would be considered for symbol binding is returned. The .I type argument is used to restrict the return information to a specific type. Values of .CR TYPE_PROCEDURE , .CR TYPE_DATA , and .C TYPE_STORAGE can be used to limit the returned symbols to be either code, data, or storage respectively; the .C TYPE_DATA value causes both data and storage symbols to be returned. The constant .C TYPE_UNDEFINED can be used to return all symbols, regardless of type. The .I flags argument must have one of the following values: .RS .RS .TP 15 .C IMPORT_SYMBOLS Return symbols found on the import list. .TP .C EXPORT_SYMBOLS Return symbols found on the export list. All symbols defined by .C shl_definesym() are export symbols. .TP .C INITIALIZERS Return symbols that are specified as the initializers of the library. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 15 .C NO_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Do not calculate the value field in the return structure to avoid symbol binding by the loader to resolve symbol dependencies. If only a few symbol values are needed, .C shl_findsym() can be used to find the values of interesting symbols. Not to be used with .CR GLOBAL_VALUES . .TP .C GLOBAL_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Use the name and type information of each return symbol and find the most visible occurrence using all symbol information sources. The value and handle fields in the symbol return structure reflect where the most visible occurrence was found. Not to be used with .CR NO_VALUES . .RE .RE .IP The .I memory argument should point to a function with the same interface as .C malloc() (see .IR malloc (3C)). .IP The return information consists of an array of the following records (defined in .RC < dl.h >): .RS .nf .IP .C "struct shl_symbol {" .C " char *name," .C " short type," .C " void *value," .C " shl_t handle," .C }; .fi .RE .IP The .I type field in the return structure can have the values .CR TYPE_PROCEDURE , .CR TYPE_DATA , or .CR TYPE_STORAGE , where .C TYPE_STORAGE is a subset of .CR TYPE_DATA . The .I value and .I handle fields are only valid if export symbols are requested and the .C NO_VALUES flag is not specified. The .I value field contains the address of the symbol, while the .I handle field is the handle of the library that defined the symbol, or .SM NULL for symbols defined via the .C shl_definesym() routine and is useful in conjunction with the .C GLOBAL_VALUES flag. .IP If successful, .C shl_getsymbols() returns the number of symbols found; otherwise it returns \(mi1. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_unload() Can be used to detach a shared library from the process. The .I handle argument should be the handle returned from a previous call to .CR shl_load() . .C shl_unload() returns 0 if successful; otherwise \(mi1 is returned. Any initializers registered with the library are called before detachment. All explicitly loaded libraries are detached automatically on process termination. .TP .C shl_get() Returns information about currently loaded libraries, including those loaded implicitly at startup time. The index argument is the ordinal position of the shared library in the shared library search list for the process. A subsequent call to .C shl_unload() decrements the index values of all libraries having an index greater than the unloaded library. The index value \(mi1 refers to the dynamic loader. The .I desc argument is used to return a pointer to a statically allocated buffer containing a descriptor for the shared library. The format of the descriptor is implementation dependent; to examine its format, look at the contents of file .CR /usr/include/dl.h . Information common to all implementations includes the library handle, pathname, and the range of addresses the library occupies. The buffer for the descriptor used by .C shl_get() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 if an invalid .I index is given. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle() Returns information about the library specified by the handle argument. The special handle .C PROG_HANDLE can be used to refer to the program itself. The descriptor returned is the same as the one returned by the .C shl_get() routine. The buffer for the descriptor used by .C shl_gethandle() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 on error. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_get_r() This is a reentrant version of .CR shl_get() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_get() . This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle_r() This is a reentrant version of .CR shl_gethandle() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_gethandle() . This routine may not be supported in future 64-bit HP-UX releases. .SH DIAGNOSTICS If a library cannot be loaded, .C shl_load() returns .SM NULL and sets .C errno to indicate the error. All other functions return \(mi1 on error and set .CR errno . .PP If .C shl_findsym() cannot find the indicated symbol, .C errno is set to zero. If .C shl_findsym() finds the indicated symbol but cannot resolve all the symbols it depends on, .C errno is set to .SM ENOSYM. .SH ERRORS Possible values for .C errno include: .RS .TP 15 .SM [ENOEXEC] The specified file is not a shared library, or a format error was detected. .TP .SM [ENOSYM] Some symbol required by the shared library could not be found. .TP .SM [EINVAL] The specified handle or index is not valid or an attempt was made to load a library at an invalid address. .TP .SM [ENOMEM] There is insufficient room in the address space to load the library. .TP .SM [ENOENT] The specified library does not exist. .TP .SM [EACCES] Read or execute permission is denied for the specified library. .RE .SH WARNINGS .C shl_unload() detaches the library from the process and frees the memory allocated for it, but does not break existing symbolic linkages into the library. In this respect, an unloaded shared library is much like a block of memory deallocated via .C free() (see .IR free (3C)). .PP Some implementations may not, by default, export all symbols defined by a program (instead exporting only those symbols that are imported by a shared library seen at link time). Therefore the .C -E option to .IR ld (1) should be used when using these routines if the loaded libraries are to refer to program symbols. .PP All symbol information returned by .CR shl_getsymbols() , including the name field, become invalid once the associated library is unloaded by .CR shl_unload() . .PP When a routine or flag is used which may not be supported in the future, the dynamic loader can display a warning message. See the .CR WARNINGS section in .IR dld.sl (5) for further details. .PP Future HP-UX 64-bit environments may only support a subset of these routines and flags. Instead, they will use the SVR4 dynamic loading API. .SH AUTHOR .IR shl_load (3X) and related functions were developed by HP. .SH SEE ALSO .PD .SS System Tools: .TP 18 ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 dld.sl(5) dynamic loader .PD .SS Texts and Tutorials .TP 18 .IR "HP-UX Linker and Libraries Online User Guide" (See the .CR +help option to .IR ld (1)) .TP .IR "Programming on HP-UX" (See .IR manuals (5) for ordering information) .PD .\" .\" index@\f4shl_load()\fP \- load shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_unload()\fP \- unload shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_findsym()\fP \- look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_get()\fP \- get information about shared library@@@\f3shl_load(3X)\f1 .\" index@shared library, load or unload@@@\f3shl_load(3X)\f1 .\" index@shared library, look up symbol in@@@\f3shl_load(3X)\f1 .\" index@load shared library@@@\f3shl_load(3X)\f1 .\" index@unload shared library@@@\f3shl_load(3X)\f1 .\" index@look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@symbol, look up in shared library@@@\f3shl_load(3X)\f1 .\" index@get information about shared library@@@\f3shl_load(3X)\f1 .\" index@explicit load of shared libraries@@@\f3shl_load(3X)\f1 .\" .\" toc@\f3shl_load(3X)\f1:\0\0\f4shl_load()\fP, \f4shl_findsym()\fP, \f4shl_unload()\fP, \f4shl_get()\fP@@@explicit load of shared libraries .\" toc@\f4shl_load()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_unload()\fP \- unload shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- get information about shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_definesym()\fP \- define new symbol for shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_get_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" .\" links@shl_load.3x shl_defines.3x .\" links@shl_load.3x shl_findsym.3x .\" links@shl_load.3x shl_gethand.3x .\" links@shl_load.3x shl_getsymb.3x .\" links@shl_load.3x shl_unload.3x .\" links@shl_load.3x shl_get.3x .\" links@shl_load.3x shl_get_r.3x .\" links@shl_load.3x shl_get_handle_r.3x .\" .\" $Header: shl_load.3x,v 78.1 96/02/12 14:14:40 ssa Exp $ .TA s .TH shl_load 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shl_load(\|), shl_definesym(\|), shl_findsym(\|), shl_gethandle(\|), shl_getsymbols(\|), shl_unload(\|), shl_get(\|), shl_gethandle_r(\|), shl_get_r(\|) \- explicit load of shared libraries .SH SYNOPSIS .nf .C "#include " .PP .C "shl_t shl_load(const char *path, int flags, long address);" .PP .C "int shl_findsym(" .PD 0 .IP .C shl_t *handle, .C "const char *sym," .C "short type," .C "void *value" .PP .C ");" .PD .PP .C "int shl_definesym(" .nf .PD 0 .IP .C const char *sym, .C short type, .C long value, .C int flags .PP .C ");" .PD .PP .C "int shl_getsymbols(" .nf .PD 0 .IP .C shl_t handle, .C short type, .C int flags, .C void *(*memory) (), .C struct shl_symbol **symbols, .PP .C ");" .PD .fi .PP .C "int shl_unload(shl_t handle);" .PP .C "int shl_get(int index, struct shl_descriptor **desc);" .PP .C "int shl_gethandle(shl_t handle, struct shl_descriptor **desc);" .PP .C "int shl_get_r(int index, struct shl_descriptor *desc);" .PP .C "int shl_gethandle_r(shl_t handle, struct shl_descriptor *desc);" .SH DESCRIPTION These routines can be used to programmatically load and unload shared libraries, and to obtain information about the libraries (such as the addresses of symbols defined within them). The routines themselves are accessed by specifying the .C \-ldld option on the command line with the .C cc or .C ld command (see .IR cc (1) and .IR ld (1)). In addition, the .C \-E option to the .C ld command can be used to ensure that all symbols defined in the program are available to the loaded libraries. .PP Shared libraries are created by compiling source files with the .C \+z or .C \+Z (position-independent code) options, and linking the resultant object files with the .C \-b (create shared library) option. .TP 20 .C shl_load() Attaches the shared library named by .I path .C or the shared library name that is constructed by using the path part of .I path plus the shared library basename followed by the suffix .C .0 (e.g. .C /usr/lib/libname.0 ) to the process, along with all its dependent libraries. A .C .0 version is looked for first for those shared libraries that do not have internal names. See .IR ld (1)). The library is mapped at the specified .IR address . If .I address is .CR 0L , the system chooses an appropriate address for the library. This is the recommended practice because the system has the most complete knowledge of the address space; currently, the .I address field is ignored, and assumed to be .CR 0L . The flags argument is made up of several fields. One of the following must be specified: .RS .RS .TP 22 .C BIND_IMMEDIATE Resolve symbol references when the library is loaded. .TP .C BIND_DEFERRED Delay code symbol resolution until actual reference. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 22 .C BIND_FIRST Place the library at the head of the symbol search order. In default mode, the library and its dependent libraries are bound independently of each other (see .CR BIND_TOGETHER ). This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NONFATAL Default .C BIND_IMMEDIATE behavior is to treat all unsatisfied symbols as fatal. This flag allows binding of unsatisfied code symbols to be deferred until use. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NOSTART Do not call the initializers for the shared library when the library is loaded, nor on a future call to .CR shl_unload() ; by default, all the initializers registered with the specified library are invoked upon loading. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_VERBOSE Print verbose messages concerning possible unsatisfied symbols. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_RESTRICTED Restrict symbols visible to the library to those present at the time the library is loaded. This flag may not be supported in future 64-bit HP-UX releases. .TP .C DYNAMIC_PATH Allow the loader to dynamically search for the library specified by the .I path argument. The directories to be searched are determined by the .C +s and .C +b options of the .C ld command used when the program was linked. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_TOGETHER When used with .CR BIND_FIRST , the library being mapped and its dependent libraries will be bound together. This is the default behavior for all .C shl_load() requests not using .CR BIND_FIRST . This flag may not be supported in future 64-bit HP-UX releases. .RE .RE .IP If successful, .C shl_load() returns a handle which can be used in subsequent calls to .CR shl_findsym() , .CR shl_unload() , .CR shl_gethandle() , or .CR shl_gethandle_r() ; otherwise .SM NULL is returned. .TP .C shl_findsym() Obtains the address of an exported symbol .I sym from a shared library. The .I handle argument should be a pointer to the handle of a loaded shared library that was returned from a previous call to .C shl_load() or .CR shl_get() . If a pointer to .SM NULL is passed for this argument, .C shl_findsym() searches all currently loaded shared libraries and the program to find the symbol; otherwise .C shl_findsym() searches only the specified shared library. The return value of handle will be .SM NULL if the symbol found was generated via .CR shl_definesym() . Otherwise the handle of the library where the symbol was found is returned. The special handle .C PROG_HANDLE can be used to refer to the program itself, so that symbols exported from the program can also be accessed dynamically. The .I type argument specifies the expected type for the symbol, and should be one of the defined constants .CR TYPE_PROCEDURE , .CR TYPE_DATA , .CR TYPE_STORAGE , or .CR TYPE_UNDEFINED . The latter value suppresses type checking. (The first three constants may not be supported in future 64-bit HP-UX releases.) The address of the symbol is returned in the variable pointed to by .IR value . If a shared library contains multiple versions of the requested symbol, the latest version is returned. This routine returns 0 if successful; otherwise \(mi1 is returned. .TP .C shl_definesym() Adds a symbol to the shared library symbol table for the current process making it the most visible definition. If the .I value falls in the range of a currently loaded library, an association will be made and the symbol is undefined once the associated library is unloaded. The defined symbol can be overridden by a subsequent call to this routine or by loading a more visible library that provides a definition. Symbols overridden in this manner may become visible again if the overriding definition is removed. .IP Possible symbol types include: .RS .RS .TP 22 .C TYPE_PROCEDURE Symbol is a function. .TP .C TYPE_DATA Symbol is data. .RE .RE .IP Possible flag values include: None defined at the present time. Zero should be passed in to prevent conflicts with future uses of this flag. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_getsymbols() Provides an array of symbol records, allocated using the supplied memory allocator, that are associated with the library specified by .IR handle . If the .I handle argument is a pointer to .SM NULL, symbols defined using .C shl_definesym() are returned. If multiple versions of the same symbol have been defined within a library or with .CR shl_definesym() , only the version from the specified symbol information source that would be considered for symbol binding is returned. The .I type argument is used to restrict the return information to a specific type. Values of .CR TYPE_PROCEDURE , .CR TYPE_DATA , and .C TYPE_STORAGE can be used to limit the returned symbols to be either code, data, or storage respectively; the .C TYPE_DATA value causes both data and storage symbols to be returned. The constant .C TYPE_UNDEFINED can be used to return all symbols, regardless of type. The .I flags argument must have one of the following values: .RS .RS .TP 15 .C IMPORT_SYMBOLS Return symbols found on the import list. .TP .C EXPORT_SYMBOLS Return symbols found on the export list. All symbols defined by .C shl_definesym() are export symbols. .TP .C INITIALIZERS Return symbols that are specified as the initializers of the library. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 15 .C NO_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Do not calculate the value field in the return structure to avoid symbol binding by the loader to resolve symbol dependencies. If only a few symbol values are needed, .C shl_findsym() can be used to find the values of interesting symbols. Not to be used with .CR GLOBAL_VALUES . .TP .C GLOBAL_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Use the name and type information of each return symbol and find the most visible occurrence using all symbol information sources. The value and handle fields in the symbol return structure reflect where the most visible occurrence was found. Not to be used with .CR NO_VALUES . .RE .RE .IP The .I memory argument should point to a function with the same interface as .C malloc() (see .IR malloc (3C)). .IP The return information consists of an array of the following records (defined in .RC < dl.h >): .RS .nf .IP .C "struct shl_symbol {" .C " char *name," .C " short type," .C " void *value," .C " shl_t handle," .C }; .fi .RE .IP The .I type field in the return structure can have the values .CR TYPE_PROCEDURE , .CR TYPE_DATA , or .CR TYPE_STORAGE , where .C TYPE_STORAGE is a subset of .CR TYPE_DATA . The .I value and .I handle fields are only valid if export symbols are requested and the .C NO_VALUES flag is not specified. The .I value field contains the address of the symbol, while the .I handle field is the handle of the library that defined the symbol, or .SM NULL for symbols defined via the .C shl_definesym() routine and is useful in conjunction with the .C GLOBAL_VALUES flag. .IP If successful, .C shl_getsymbols() returns the number of symbols found; otherwise it returns \(mi1. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_unload() Can be used to detach a shared library from the process. The .I handle argument should be the handle returned from a previous call to .CR shl_load() . .C shl_unload() returns 0 if successful; otherwise \(mi1 is returned. Any initializers registered with the library are called before detachment. All explicitly loaded libraries are detached automatically on process termination. .TP .C shl_get() Returns information about currently loaded libraries, including those loaded implicitly at startup time. The index argument is the ordinal position of the shared library in the shared library search list for the process. A subsequent call to .C shl_unload() decrements the index values of all libraries having an index greater than the unloaded library. The index value \(mi1 refers to the dynamic loader. The .I desc argument is used to return a pointer to a statically allocated buffer containing a descriptor for the shared library. The format of the descriptor is implementation dependent; to examine its format, look at the contents of file .CR /usr/include/dl.h . Information common to all implementations includes the library handle, pathname, and the range of addresses the library occupies. The buffer for the descriptor used by .C shl_get() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 if an invalid .I index is given. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle() Returns information about the library specified by the handle argument. The special handle .C PROG_HANDLE can be used to refer to the program itself. The descriptor returned is the same as the one returned by the .C shl_get() routine. The buffer for the descriptor used by .C shl_gethandle() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 on error. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_get_r() This is a reentrant version of .CR shl_get() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_get() . This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle_r() This is a reentrant version of .CR shl_gethandle() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_gethandle() . This routine may not be supported in future 64-bit HP-UX releases. .SH DIAGNOSTICS If a library cannot be loaded, .C shl_load() returns .SM NULL and sets .C errno to indicate the error. All other functions return \(mi1 on error and set .CR errno . .PP If .C shl_findsym() cannot find the indicated symbol, .C errno is set to zero. If .C shl_findsym() finds the indicated symbol but cannot resolve all the symbols it depends on, .C errno is set to .SM ENOSYM. .SH ERRORS Possible values for .C errno include: .RS .TP 15 .SM [ENOEXEC] The specified file is not a shared library, or a format error was detected. .TP .SM [ENOSYM] Some symbol required by the shared library could not be found. .TP .SM [EINVAL] The specified handle or index is not valid or an attempt was made to load a library at an invalid address. .TP .SM [ENOMEM] There is insufficient room in the address space to load the library. .TP .SM [ENOENT] The specified library does not exist. .TP .SM [EACCES] Read or execute permission is denied for the specified library. .RE .SH WARNINGS .C shl_unload() detaches the library from the process and frees the memory allocated for it, but does not break existing symbolic linkages into the library. In this respect, an unloaded shared library is much like a block of memory deallocated via .C free() (see .IR free (3C)). .PP Some implementations may not, by default, export all symbols defined by a program (instead exporting only those symbols that are imported by a shared library seen at link time). Therefore the .C -E option to .IR ld (1) should be used when using these routines if the loaded libraries are to refer to program symbols. .PP All symbol information returned by .CR shl_getsymbols() , including the name field, become invalid once the associated library is unloaded by .CR shl_unload() . .PP When a routine or flag is used which may not be supported in the future, the dynamic loader can display a warning message. See the .CR WARNINGS section in .IR dld.sl (5) for further details. .PP Future HP-UX 64-bit environments may only support a subset of these routines and flags. Instead, they will use the SVR4 dynamic loading API. .SH AUTHOR .IR shl_load (3X) and related functions were developed by HP. .SH SEE ALSO .PD .SS System Tools: .TP 18 ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 dld.sl(5) dynamic loader .PD .SS Texts and Tutorials .TP 18 .IR "HP-UX Linker and Libraries Online User Guide" (See the .CR +help option to .IR ld (1)) .TP .IR "Programming on HP-UX" (See .IR manuals (5) for ordering information) .PD .\" .\" index@\f4shl_load()\fP \- load shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_unload()\fP \- unload shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_findsym()\fP \- look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_get()\fP \- get information about shared library@@@\f3shl_load(3X)\f1 .\" index@shared library, load or unload@@@\f3shl_load(3X)\f1 .\" index@shared library, look up symbol in@@@\f3shl_load(3X)\f1 .\" index@load shared library@@@\f3shl_load(3X)\f1 .\" index@unload shared library@@@\f3shl_load(3X)\f1 .\" index@look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@symbol, look up in shared library@@@\f3shl_load(3X)\f1 .\" index@get information about shared library@@@\f3shl_load(3X)\f1 .\" index@explicit load of shared libraries@@@\f3shl_load(3X)\f1 .\" .\" toc@\f3shl_load(3X)\f1:\0\0\f4shl_load()\fP, \f4shl_findsym()\fP, \f4shl_unload()\fP, \f4shl_get()\fP@@@explicit load of shared libraries .\" toc@\f4shl_load()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_unload()\fP \- unload shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- get information about shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_definesym()\fP \- define new symbol for shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_get_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" .\" links@shl_load.3x shl_defines.3x .\" links@shl_load.3x shl_findsym.3x .\" links@shl_load.3x shl_gethand.3x .\" links@shl_load.3x shl_getsymb.3x .\" links@shl_load.3x shl_unload.3x .\" links@shl_load.3x shl_get.3x .\" links@shl_load.3x shl_get_r.3x .\" links@shl_load.3x shl_get_handle_r.3x .\" .\" $Header: shl_load.3x,v 78.1 96/02/12 14:14:40 ssa Exp $ .TA s .TH shl_load 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shl_load(\|), shl_definesym(\|), shl_findsym(\|), shl_gethandle(\|), shl_getsymbols(\|), shl_unload(\|), shl_get(\|), shl_gethandle_r(\|), shl_get_r(\|) \- explicit load of shared libraries .SH SYNOPSIS .nf .C "#include " .PP .C "shl_t shl_load(const char *path, int flags, long address);" .PP .C "int shl_findsym(" .PD 0 .IP .C shl_t *handle, .C "const char *sym," .C "short type," .C "void *value" .PP .C ");" .PD .PP .C "int shl_definesym(" .nf .PD 0 .IP .C const char *sym, .C short type, .C long value, .C int flags .PP .C ");" .PD .PP .C "int shl_getsymbols(" .nf .PD 0 .IP .C shl_t handle, .C short type, .C int flags, .C void *(*memory) (), .C struct shl_symbol **symbols, .PP .C ");" .PD .fi .PP .C "int shl_unload(shl_t handle);" .PP .C "int shl_get(int index, struct shl_descriptor **desc);" .PP .C "int shl_gethandle(shl_t handle, struct shl_descriptor **desc);" .PP .C "int shl_get_r(int index, struct shl_descriptor *desc);" .PP .C "int shl_gethandle_r(shl_t handle, struct shl_descriptor *desc);" .SH DESCRIPTION These routines can be used to programmatically load and unload shared libraries, and to obtain information about the libraries (such as the addresses of symbols defined within them). The routines themselves are accessed by specifying the .C \-ldld option on the command line with the .C cc or .C ld command (see .IR cc (1) and .IR ld (1)). In addition, the .C \-E option to the .C ld command can be used to ensure that all symbols defined in the program are available to the loaded libraries. .PP Shared libraries are created by compiling source files with the .C \+z or .C \+Z (position-independent code) options, and linking the resultant object files with the .C \-b (create shared library) option. .TP 20 .C shl_load() Attaches the shared library named by .I path .C or the shared library name that is constructed by using the path part of .I path plus the shared library basename followed by the suffix .C .0 (e.g. .C /usr/lib/libname.0 ) to the process, along with all its dependent libraries. A .C .0 version is looked for first for those shared libraries that do not have internal names. See .IR ld (1)). The library is mapped at the specified .IR address . If .I address is .CR 0L , the system chooses an appropriate address for the library. This is the recommended practice because the system has the most complete knowledge of the address space; currently, the .I address field is ignored, and assumed to be .CR 0L . The flags argument is made up of several fields. One of the following must be specified: .RS .RS .TP 22 .C BIND_IMMEDIATE Resolve symbol references when the library is loaded. .TP .C BIND_DEFERRED Delay code symbol resolution until actual reference. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 22 .C BIND_FIRST Place the library at the head of the symbol search order. In default mode, the library and its dependent libraries are bound independently of each other (see .CR BIND_TOGETHER ). This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NONFATAL Default .C BIND_IMMEDIATE behavior is to treat all unsatisfied symbols as fatal. This flag allows binding of unsatisfied code symbols to be deferred until use. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NOSTART Do not call the initializers for the shared library when the library is loaded, nor on a future call to .CR shl_unload() ; by default, all the initializers registered with the specified library are invoked upon loading. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_VERBOSE Print verbose messages concerning possible unsatisfied symbols. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_RESTRICTED Restrict symbols visible to the library to those present at the time the library is loaded. This flag may not be supported in future 64-bit HP-UX releases. .TP .C DYNAMIC_PATH Allow the loader to dynamically search for the library specified by the .I path argument. The directories to be searched are determined by the .C +s and .C +b options of the .C ld command used when the program was linked. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_TOGETHER When used with .CR BIND_FIRST , the library being mapped and its dependent libraries will be bound together. This is the default behavior for all .C shl_load() requests not using .CR BIND_FIRST . This flag may not be supported in future 64-bit HP-UX releases. .RE .RE .IP If successful, .C shl_load() returns a handle which can be used in subsequent calls to .CR shl_findsym() , .CR shl_unload() , .CR shl_gethandle() , or .CR shl_gethandle_r() ; otherwise .SM NULL is returned. .TP .C shl_findsym() Obtains the address of an exported symbol .I sym from a shared library. The .I handle argument should be a pointer to the handle of a loaded shared library that was returned from a previous call to .C shl_load() or .CR shl_get() . If a pointer to .SM NULL is passed for this argument, .C shl_findsym() searches all currently loaded shared libraries and the program to find the symbol; otherwise .C shl_findsym() searches only the specified shared library. The return value of handle will be .SM NULL if the symbol found was generated via .CR shl_definesym() . Otherwise the handle of the library where the symbol was found is returned. The special handle .C PROG_HANDLE can be used to refer to the program itself, so that symbols exported from the program can also be accessed dynamically. The .I type argument specifies the expected type for the symbol, and should be one of the defined constants .CR TYPE_PROCEDURE , .CR TYPE_DATA , .CR TYPE_STORAGE , or .CR TYPE_UNDEFINED . The latter value suppresses type checking. (The first three constants may not be supported in future 64-bit HP-UX releases.) The address of the symbol is returned in the variable pointed to by .IR value . If a shared library contains multiple versions of the requested symbol, the latest version is returned. This routine returns 0 if successful; otherwise \(mi1 is returned. .TP .C shl_definesym() Adds a symbol to the shared library symbol table for the current process making it the most visible definition. If the .I value falls in the range of a currently loaded library, an association will be made and the symbol is undefined once the associated library is unloaded. The defined symbol can be overridden by a subsequent call to this routine or by loading a more visible library that provides a definition. Symbols overridden in this manner may become visible again if the overriding definition is removed. .IP Possible symbol types include: .RS .RS .TP 22 .C TYPE_PROCEDURE Symbol is a function. .TP .C TYPE_DATA Symbol is data. .RE .RE .IP Possible flag values include: None defined at the present time. Zero should be passed in to prevent conflicts with future uses of this flag. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_getsymbols() Provides an array of symbol records, allocated using the supplied memory allocator, that are associated with the library specified by .IR handle . If the .I handle argument is a pointer to .SM NULL, symbols defined using .C shl_definesym() are returned. If multiple versions of the same symbol have been defined within a library or with .CR shl_definesym() , only the version from the specified symbol information source that would be considered for symbol binding is returned. The .I type argument is used to restrict the return information to a specific type. Values of .CR TYPE_PROCEDURE , .CR TYPE_DATA , and .C TYPE_STORAGE can be used to limit the returned symbols to be either code, data, or storage respectively; the .C TYPE_DATA value causes both data and storage symbols to be returned. The constant .C TYPE_UNDEFINED can be used to return all symbols, regardless of type. The .I flags argument must have one of the following values: .RS .RS .TP 15 .C IMPORT_SYMBOLS Return symbols found on the import list. .TP .C EXPORT_SYMBOLS Return symbols found on the export list. All symbols defined by .C shl_definesym() are export symbols. .TP .C INITIALIZERS Return symbols that are specified as the initializers of the library. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 15 .C NO_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Do not calculate the value field in the return structure to avoid symbol binding by the loader to resolve symbol dependencies. If only a few symbol values are needed, .C shl_findsym() can be used to find the values of interesting symbols. Not to be used with .CR GLOBAL_VALUES . .TP .C GLOBAL_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Use the name and type information of each return symbol and find the most visible occurrence using all symbol information sources. The value and handle fields in the symbol return structure reflect where the most visible occurrence was found. Not to be used with .CR NO_VALUES . .RE .RE .IP The .I memory argument should point to a function with the same interface as .C malloc() (see .IR malloc (3C)). .IP The return information consists of an array of the following records (defined in .RC < dl.h >): .RS .nf .IP .C "struct shl_symbol {" .C " char *name," .C " short type," .C " void *value," .C " shl_t handle," .C }; .fi .RE .IP The .I type field in the return structure can have the values .CR TYPE_PROCEDURE , .CR TYPE_DATA , or .CR TYPE_STORAGE , where .C TYPE_STORAGE is a subset of .CR TYPE_DATA . The .I value and .I handle fields are only valid if export symbols are requested and the .C NO_VALUES flag is not specified. The .I value field contains the address of the symbol, while the .I handle field is the handle of the library that defined the symbol, or .SM NULL for symbols defined via the .C shl_definesym() routine and is useful in conjunction with the .C GLOBAL_VALUES flag. .IP If successful, .C shl_getsymbols() returns the number of symbols found; otherwise it returns \(mi1. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_unload() Can be used to detach a shared library from the process. The .I handle argument should be the handle returned from a previous call to .CR shl_load() . .C shl_unload() returns 0 if successful; otherwise \(mi1 is returned. Any initializers registered with the library are called before detachment. All explicitly loaded libraries are detached automatically on process termination. .TP .C shl_get() Returns information about currently loaded libraries, including those loaded implicitly at startup time. The index argument is the ordinal position of the shared library in the shared library search list for the process. A subsequent call to .C shl_unload() decrements the index values of all libraries having an index greater than the unloaded library. The index value \(mi1 refers to the dynamic loader. The .I desc argument is used to return a pointer to a statically allocated buffer containing a descriptor for the shared library. The format of the descriptor is implementation dependent; to examine its format, look at the contents of file .CR /usr/include/dl.h . Information common to all implementations includes the library handle, pathname, and the range of addresses the library occupies. The buffer for the descriptor used by .C shl_get() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 if an invalid .I index is given. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle() Returns information about the library specified by the handle argument. The special handle .C PROG_HANDLE can be used to refer to the program itself. The descriptor returned is the same as the one returned by the .C shl_get() routine. The buffer for the descriptor used by .C shl_gethandle() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 on error. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_get_r() This is a reentrant version of .CR shl_get() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_get() . This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle_r() This is a reentrant version of .CR shl_gethandle() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_gethandle() . This routine may not be supported in future 64-bit HP-UX releases. .SH DIAGNOSTICS If a library cannot be loaded, .C shl_load() returns .SM NULL and sets .C errno to indicate the error. All other functions return \(mi1 on error and set .CR errno . .PP If .C shl_findsym() cannot find the indicated symbol, .C errno is set to zero. If .C shl_findsym() finds the indicated symbol but cannot resolve all the symbols it depends on, .C errno is set to .SM ENOSYM. .SH ERRORS Possible values for .C errno include: .RS .TP 15 .SM [ENOEXEC] The specified file is not a shared library, or a format error was detected. .TP .SM [ENOSYM] Some symbol required by the shared library could not be found. .TP .SM [EINVAL] The specified handle or index is not valid or an attempt was made to load a library at an invalid address. .TP .SM [ENOMEM] There is insufficient room in the address space to load the library. .TP .SM [ENOENT] The specified library does not exist. .TP .SM [EACCES] Read or execute permission is denied for the specified library. .RE .SH WARNINGS .C shl_unload() detaches the library from the process and frees the memory allocated for it, but does not break existing symbolic linkages into the library. In this respect, an unloaded shared library is much like a block of memory deallocated via .C free() (see .IR free (3C)). .PP Some implementations may not, by default, export all symbols defined by a program (instead exporting only those symbols that are imported by a shared library seen at link time). Therefore the .C -E option to .IR ld (1) should be used when using these routines if the loaded libraries are to refer to program symbols. .PP All symbol information returned by .CR shl_getsymbols() , including the name field, become invalid once the associated library is unloaded by .CR shl_unload() . .PP When a routine or flag is used which may not be supported in the future, the dynamic loader can display a warning message. See the .CR WARNINGS section in .IR dld.sl (5) for further details. .PP Future HP-UX 64-bit environments may only support a subset of these routines and flags. Instead, they will use the SVR4 dynamic loading API. .SH AUTHOR .IR shl_load (3X) and related functions were developed by HP. .SH SEE ALSO .PD .SS System Tools: .TP 18 ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 dld.sl(5) dynamic loader .PD .SS Texts and Tutorials .TP 18 .IR "HP-UX Linker and Libraries Online User Guide" (See the .CR +help option to .IR ld (1)) .TP .IR "Programming on HP-UX" (See .IR manuals (5) for ordering information) .PD .\" .\" index@\f4shl_load()\fP \- load shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_unload()\fP \- unload shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_findsym()\fP \- look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_get()\fP \- get information about shared library@@@\f3shl_load(3X)\f1 .\" index@shared library, load or unload@@@\f3shl_load(3X)\f1 .\" index@shared library, look up symbol in@@@\f3shl_load(3X)\f1 .\" index@load shared library@@@\f3shl_load(3X)\f1 .\" index@unload shared library@@@\f3shl_load(3X)\f1 .\" index@look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@symbol, look up in shared library@@@\f3shl_load(3X)\f1 .\" index@get information about shared library@@@\f3shl_load(3X)\f1 .\" index@explicit load of shared libraries@@@\f3shl_load(3X)\f1 .\" .\" toc@\f3shl_load(3X)\f1:\0\0\f4shl_load()\fP, \f4shl_findsym()\fP, \f4shl_unload()\fP, \f4shl_get()\fP@@@explicit load of shared libraries .\" toc@\f4shl_load()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_unload()\fP \- unload shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- get information about shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_definesym()\fP \- define new symbol for shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_get_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" .\" links@shl_load.3x shl_defines.3x .\" links@shl_load.3x shl_findsym.3x .\" links@shl_load.3x shl_gethand.3x .\" links@shl_load.3x shl_getsymb.3x .\" links@shl_load.3x shl_unload.3x .\" links@shl_load.3x shl_get.3x .\" links@shl_load.3x shl_get_r.3x .\" links@shl_load.3x shl_get_handle_r.3x .\" .\" $Header: shl_load.3x,v 78.1 96/02/12 14:14:40 ssa Exp $ .TA s .TH shl_load 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shl_load(\|), shl_definesym(\|), shl_findsym(\|), shl_gethandle(\|), shl_getsymbols(\|), shl_unload(\|), shl_get(\|), shl_gethandle_r(\|), shl_get_r(\|) \- explicit load of shared libraries .SH SYNOPSIS .nf .C "#include " .PP .C "shl_t shl_load(const char *path, int flags, long address);" .PP .C "int shl_findsym(" .PD 0 .IP .C shl_t *handle, .C "const char *sym," .C "short type," .C "void *value" .PP .C ");" .PD .PP .C "int shl_definesym(" .nf .PD 0 .IP .C const char *sym, .C short type, .C long value, .C int flags .PP .C ");" .PD .PP .C "int shl_getsymbols(" .nf .PD 0 .IP .C shl_t handle, .C short type, .C int flags, .C void *(*memory) (), .C struct shl_symbol **symbols, .PP .C ");" .PD .fi .PP .C "int shl_unload(shl_t handle);" .PP .C "int shl_get(int index, struct shl_descriptor **desc);" .PP .C "int shl_gethandle(shl_t handle, struct shl_descriptor **desc);" .PP .C "int shl_get_r(int index, struct shl_descriptor *desc);" .PP .C "int shl_gethandle_r(shl_t handle, struct shl_descriptor *desc);" .SH DESCRIPTION These routines can be used to programmatically load and unload shared libraries, and to obtain information about the libraries (such as the addresses of symbols defined within them). The routines themselves are accessed by specifying the .C \-ldld option on the command line with the .C cc or .C ld command (see .IR cc (1) and .IR ld (1)). In addition, the .C \-E option to the .C ld command can be used to ensure that all symbols defined in the program are available to the loaded libraries. .PP Shared libraries are created by compiling source files with the .C \+z or .C \+Z (position-independent code) options, and linking the resultant object files with the .C \-b (create shared library) option. .TP 20 .C shl_load() Attaches the shared library named by .I path .C or the shared library name that is constructed by using the path part of .I path plus the shared library basename followed by the suffix .C .0 (e.g. .C /usr/lib/libname.0 ) to the process, along with all its dependent libraries. A .C .0 version is looked for first for those shared libraries that do not have internal names. See .IR ld (1)). The library is mapped at the specified .IR address . If .I address is .CR 0L , the system chooses an appropriate address for the library. This is the recommended practice because the system has the most complete knowledge of the address space; currently, the .I address field is ignored, and assumed to be .CR 0L . The flags argument is made up of several fields. One of the following must be specified: .RS .RS .TP 22 .C BIND_IMMEDIATE Resolve symbol references when the library is loaded. .TP .C BIND_DEFERRED Delay code symbol resolution until actual reference. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 22 .C BIND_FIRST Place the library at the head of the symbol search order. In default mode, the library and its dependent libraries are bound independently of each other (see .CR BIND_TOGETHER ). This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NONFATAL Default .C BIND_IMMEDIATE behavior is to treat all unsatisfied symbols as fatal. This flag allows binding of unsatisfied code symbols to be deferred until use. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NOSTART Do not call the initializers for the shared library when the library is loaded, nor on a future call to .CR shl_unload() ; by default, all the initializers registered with the specified library are invoked upon loading. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_VERBOSE Print verbose messages concerning possible unsatisfied symbols. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_RESTRICTED Restrict symbols visible to the library to those present at the time the library is loaded. This flag may not be supported in future 64-bit HP-UX releases. .TP .C DYNAMIC_PATH Allow the loader to dynamically search for the library specified by the .I path argument. The directories to be searched are determined by the .C +s and .C +b options of the .C ld command used when the program was linked. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_TOGETHER When used with .CR BIND_FIRST , the library being mapped and its dependent libraries will be bound together. This is the default behavior for all .C shl_load() requests not using .CR BIND_FIRST . This flag may not be supported in future 64-bit HP-UX releases. .RE .RE .IP If successful, .C shl_load() returns a handle which can be used in subsequent calls to .CR shl_findsym() , .CR shl_unload() , .CR shl_gethandle() , or .CR shl_gethandle_r() ; otherwise .SM NULL is returned. .TP .C shl_findsym() Obtains the address of an exported symbol .I sym from a shared library. The .I handle argument should be a pointer to the handle of a loaded shared library that was returned from a previous call to .C shl_load() or .CR shl_get() . If a pointer to .SM NULL is passed for this argument, .C shl_findsym() searches all currently loaded shared libraries and the program to find the symbol; otherwise .C shl_findsym() searches only the specified shared library. The return value of handle will be .SM NULL if the symbol found was generated via .CR shl_definesym() . Otherwise the handle of the library where the symbol was found is returned. The special handle .C PROG_HANDLE can be used to refer to the program itself, so that symbols exported from the program can also be accessed dynamically. The .I type argument specifies the expected type for the symbol, and should be one of the defined constants .CR TYPE_PROCEDURE , .CR TYPE_DATA , .CR TYPE_STORAGE , or .CR TYPE_UNDEFINED . The latter value suppresses type checking. (The first three constants may not be supported in future 64-bit HP-UX releases.) The address of the symbol is returned in the variable pointed to by .IR value . If a shared library contains multiple versions of the requested symbol, the latest version is returned. This routine returns 0 if successful; otherwise \(mi1 is returned. .TP .C shl_definesym() Adds a symbol to the shared library symbol table for the current process making it the most visible definition. If the .I value falls in the range of a currently loaded library, an association will be made and the symbol is undefined once the associated library is unloaded. The defined symbol can be overridden by a subsequent call to this routine or by loading a more visible library that provides a definition. Symbols overridden in this manner may become visible again if the overriding definition is removed. .IP Possible symbol types include: .RS .RS .TP 22 .C TYPE_PROCEDURE Symbol is a function. .TP .C TYPE_DATA Symbol is data. .RE .RE .IP Possible flag values include: None defined at the present time. Zero should be passed in to prevent conflicts with future uses of this flag. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_getsymbols() Provides an array of symbol records, allocated using the supplied memory allocator, that are associated with the library specified by .IR handle . If the .I handle argument is a pointer to .SM NULL, symbols defined using .C shl_definesym() are returned. If multiple versions of the same symbol have been defined within a library or with .CR shl_definesym() , only the version from the specified symbol information source that would be considered for symbol binding is returned. The .I type argument is used to restrict the return information to a specific type. Values of .CR TYPE_PROCEDURE , .CR TYPE_DATA , and .C TYPE_STORAGE can be used to limit the returned symbols to be either code, data, or storage respectively; the .C TYPE_DATA value causes both data and storage symbols to be returned. The constant .C TYPE_UNDEFINED can be used to return all symbols, regardless of type. The .I flags argument must have one of the following values: .RS .RS .TP 15 .C IMPORT_SYMBOLS Return symbols found on the import list. .TP .C EXPORT_SYMBOLS Return symbols found on the export list. All symbols defined by .C shl_definesym() are export symbols. .TP .C INITIALIZERS Return symbols that are specified as the initializers of the library. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 15 .C NO_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Do not calculate the value field in the return structure to avoid symbol binding by the loader to resolve symbol dependencies. If only a few symbol values are needed, .C shl_findsym() can be used to find the values of interesting symbols. Not to be used with .CR GLOBAL_VALUES . .TP .C GLOBAL_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Use the name and type information of each return symbol and find the most visible occurrence using all symbol information sources. The value and handle fields in the symbol return structure reflect where the most visible occurrence was found. Not to be used with .CR NO_VALUES . .RE .RE .IP The .I memory argument should point to a function with the same interface as .C malloc() (see .IR malloc (3C)). .IP The return information consists of an array of the following records (defined in .RC < dl.h >): .RS .nf .IP .C "struct shl_symbol {" .C " char *name," .C " short type," .C " void *value," .C " shl_t handle," .C }; .fi .RE .IP The .I type field in the return structure can have the values .CR TYPE_PROCEDURE , .CR TYPE_DATA , or .CR TYPE_STORAGE , where .C TYPE_STORAGE is a subset of .CR TYPE_DATA . The .I value and .I handle fields are only valid if export symbols are requested and the .C NO_VALUES flag is not specified. The .I value field contains the address of the symbol, while the .I handle field is the handle of the library that defined the symbol, or .SM NULL for symbols defined via the .C shl_definesym() routine and is useful in conjunction with the .C GLOBAL_VALUES flag. .IP If successful, .C shl_getsymbols() returns the number of symbols found; otherwise it returns \(mi1. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_unload() Can be used to detach a shared library from the process. The .I handle argument should be the handle returned from a previous call to .CR shl_load() . .C shl_unload() returns 0 if successful; otherwise \(mi1 is returned. Any initializers registered with the library are called before detachment. All explicitly loaded libraries are detached automatically on process termination. .TP .C shl_get() Returns information about currently loaded libraries, including those loaded implicitly at startup time. The index argument is the ordinal position of the shared library in the shared library search list for the process. A subsequent call to .C shl_unload() decrements the index values of all libraries having an index greater than the unloaded library. The index value \(mi1 refers to the dynamic loader. The .I desc argument is used to return a pointer to a statically allocated buffer containing a descriptor for the shared library. The format of the descriptor is implementation dependent; to examine its format, look at the contents of file .CR /usr/include/dl.h . Information common to all implementations includes the library handle, pathname, and the range of addresses the library occupies. The buffer for the descriptor used by .C shl_get() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 if an invalid .I index is given. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle() Returns information about the library specified by the handle argument. The special handle .C PROG_HANDLE can be used to refer to the program itself. The descriptor returned is the same as the one returned by the .C shl_get() routine. The buffer for the descriptor used by .C shl_gethandle() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 on error. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_get_r() This is a reentrant version of .CR shl_get() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_get() . This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle_r() This is a reentrant version of .CR shl_gethandle() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_gethandle() . This routine may not be supported in future 64-bit HP-UX releases. .SH DIAGNOSTICS If a library cannot be loaded, .C shl_load() returns .SM NULL and sets .C errno to indicate the error. All other functions return \(mi1 on error and set .CR errno . .PP If .C shl_findsym() cannot find the indicated symbol, .C errno is set to zero. If .C shl_findsym() finds the indicated symbol but cannot resolve all the symbols it depends on, .C errno is set to .SM ENOSYM. .SH ERRORS Possible values for .C errno include: .RS .TP 15 .SM [ENOEXEC] The specified file is not a shared library, or a format error was detected. .TP .SM [ENOSYM] Some symbol required by the shared library could not be found. .TP .SM [EINVAL] The specified handle or index is not valid or an attempt was made to load a library at an invalid address. .TP .SM [ENOMEM] There is insufficient room in the address space to load the library. .TP .SM [ENOENT] The specified library does not exist. .TP .SM [EACCES] Read or execute permission is denied for the specified library. .RE .SH WARNINGS .C shl_unload() detaches the library from the process and frees the memory allocated for it, but does not break existing symbolic linkages into the library. In this respect, an unloaded shared library is much like a block of memory deallocated via .C free() (see .IR free (3C)). .PP Some implementations may not, by default, export all symbols defined by a program (instead exporting only those symbols that are imported by a shared library seen at link time). Therefore the .C -E option to .IR ld (1) should be used when using these routines if the loaded libraries are to refer to program symbols. .PP All symbol information returned by .CR shl_getsymbols() , including the name field, become invalid once the associated library is unloaded by .CR shl_unload() . .PP When a routine or flag is used which may not be supported in the future, the dynamic loader can display a warning message. See the .CR WARNINGS section in .IR dld.sl (5) for further details. .PP Future HP-UX 64-bit environments may only support a subset of these routines and flags. Instead, they will use the SVR4 dynamic loading API. .SH AUTHOR .IR shl_load (3X) and related functions were developed by HP. .SH SEE ALSO .PD .SS System Tools: .TP 18 ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 dld.sl(5) dynamic loader .PD .SS Texts and Tutorials .TP 18 .IR "HP-UX Linker and Libraries Online User Guide" (See the .CR +help option to .IR ld (1)) .TP .IR "Programming on HP-UX" (See .IR manuals (5) for ordering information) .PD .\" .\" index@\f4shl_load()\fP \- load shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_unload()\fP \- unload shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_findsym()\fP \- look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_get()\fP \- get information about shared library@@@\f3shl_load(3X)\f1 .\" index@shared library, load or unload@@@\f3shl_load(3X)\f1 .\" index@shared library, look up symbol in@@@\f3shl_load(3X)\f1 .\" index@load shared library@@@\f3shl_load(3X)\f1 .\" index@unload shared library@@@\f3shl_load(3X)\f1 .\" index@look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@symbol, look up in shared library@@@\f3shl_load(3X)\f1 .\" index@get information about shared library@@@\f3shl_load(3X)\f1 .\" index@explicit load of shared libraries@@@\f3shl_load(3X)\f1 .\" .\" toc@\f3shl_load(3X)\f1:\0\0\f4shl_load()\fP, \f4shl_findsym()\fP, \f4shl_unload()\fP, \f4shl_get()\fP@@@explicit load of shared libraries .\" toc@\f4shl_load()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_unload()\fP \- unload shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- get information about shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_definesym()\fP \- define new symbol for shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_get_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" .\" links@shl_load.3x shl_defines.3x .\" links@shl_load.3x shl_findsym.3x .\" links@shl_load.3x shl_gethand.3x .\" links@shl_load.3x shl_getsymb.3x .\" links@shl_load.3x shl_unload.3x .\" links@shl_load.3x shl_get.3x .\" links@shl_load.3x shl_get_r.3x .\" links@shl_load.3x shl_get_handle_r.3x .\" .\" $Header: shl_load.3x,v 78.1 96/02/12 14:14:40 ssa Exp $ .TA s .TH shl_load 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shl_load(\|), shl_definesym(\|), shl_findsym(\|), shl_gethandle(\|), shl_getsymbols(\|), shl_unload(\|), shl_get(\|), shl_gethandle_r(\|), shl_get_r(\|) \- explicit load of shared libraries .SH SYNOPSIS .nf .C "#include " .PP .C "shl_t shl_load(const char *path, int flags, long address);" .PP .C "int shl_findsym(" .PD 0 .IP .C shl_t *handle, .C "const char *sym," .C "short type," .C "void *value" .PP .C ");" .PD .PP .C "int shl_definesym(" .nf .PD 0 .IP .C const char *sym, .C short type, .C long value, .C int flags .PP .C ");" .PD .PP .C "int shl_getsymbols(" .nf .PD 0 .IP .C shl_t handle, .C short type, .C int flags, .C void *(*memory) (), .C struct shl_symbol **symbols, .PP .C ");" .PD .fi .PP .C "int shl_unload(shl_t handle);" .PP .C "int shl_get(int index, struct shl_descriptor **desc);" .PP .C "int shl_gethandle(shl_t handle, struct shl_descriptor **desc);" .PP .C "int shl_get_r(int index, struct shl_descriptor *desc);" .PP .C "int shl_gethandle_r(shl_t handle, struct shl_descriptor *desc);" .SH DESCRIPTION These routines can be used to programmatically load and unload shared libraries, and to obtain information about the libraries (such as the addresses of symbols defined within them). The routines themselves are accessed by specifying the .C \-ldld option on the command line with the .C cc or .C ld command (see .IR cc (1) and .IR ld (1)). In addition, the .C \-E option to the .C ld command can be used to ensure that all symbols defined in the program are available to the loaded libraries. .PP Shared libraries are created by compiling source files with the .C \+z or .C \+Z (position-independent code) options, and linking the resultant object files with the .C \-b (create shared library) option. .TP 20 .C shl_load() Attaches the shared library named by .I path .C or the shared library name that is constructed by using the path part of .I path plus the shared library basename followed by the suffix .C .0 (e.g. .C /usr/lib/libname.0 ) to the process, along with all its dependent libraries. A .C .0 version is looked for first for those shared libraries that do not have internal names. See .IR ld (1)). The library is mapped at the specified .IR address . If .I address is .CR 0L , the system chooses an appropriate address for the library. This is the recommended practice because the system has the most complete knowledge of the address space; currently, the .I address field is ignored, and assumed to be .CR 0L . The flags argument is made up of several fields. One of the following must be specified: .RS .RS .TP 22 .C BIND_IMMEDIATE Resolve symbol references when the library is loaded. .TP .C BIND_DEFERRED Delay code symbol resolution until actual reference. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 22 .C BIND_FIRST Place the library at the head of the symbol search order. In default mode, the library and its dependent libraries are bound independently of each other (see .CR BIND_TOGETHER ). This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NONFATAL Default .C BIND_IMMEDIATE behavior is to treat all unsatisfied symbols as fatal. This flag allows binding of unsatisfied code symbols to be deferred until use. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NOSTART Do not call the initializers for the shared library when the library is loaded, nor on a future call to .CR shl_unload() ; by default, all the initializers registered with the specified library are invoked upon loading. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_VERBOSE Print verbose messages concerning possible unsatisfied symbols. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_RESTRICTED Restrict symbols visible to the library to those present at the time the library is loaded. This flag may not be supported in future 64-bit HP-UX releases. .TP .C DYNAMIC_PATH Allow the loader to dynamically search for the library specified by the .I path argument. The directories to be searched are determined by the .C +s and .C +b options of the .C ld command used when the program was linked. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_TOGETHER When used with .CR BIND_FIRST , the library being mapped and its dependent libraries will be bound together. This is the default behavior for all .C shl_load() requests not using .CR BIND_FIRST . This flag may not be supported in future 64-bit HP-UX releases. .RE .RE .IP If successful, .C shl_load() returns a handle which can be used in subsequent calls to .CR shl_findsym() , .CR shl_unload() , .CR shl_gethandle() , or .CR shl_gethandle_r() ; otherwise .SM NULL is returned. .TP .C shl_findsym() Obtains the address of an exported symbol .I sym from a shared library. The .I handle argument should be a pointer to the handle of a loaded shared library that was returned from a previous call to .C shl_load() or .CR shl_get() . If a pointer to .SM NULL is passed for this argument, .C shl_findsym() searches all currently loaded shared libraries and the program to find the symbol; otherwise .C shl_findsym() searches only the specified shared library. The return value of handle will be .SM NULL if the symbol found was generated via .CR shl_definesym() . Otherwise the handle of the library where the symbol was found is returned. The special handle .C PROG_HANDLE can be used to refer to the program itself, so that symbols exported from the program can also be accessed dynamically. The .I type argument specifies the expected type for the symbol, and should be one of the defined constants .CR TYPE_PROCEDURE , .CR TYPE_DATA , .CR TYPE_STORAGE , or .CR TYPE_UNDEFINED . The latter value suppresses type checking. (The first three constants may not be supported in future 64-bit HP-UX releases.) The address of the symbol is returned in the variable pointed to by .IR value . If a shared library contains multiple versions of the requested symbol, the latest version is returned. This routine returns 0 if successful; otherwise \(mi1 is returned. .TP .C shl_definesym() Adds a symbol to the shared library symbol table for the current process making it the most visible definition. If the .I value falls in the range of a currently loaded library, an association will be made and the symbol is undefined once the associated library is unloaded. The defined symbol can be overridden by a subsequent call to this routine or by loading a more visible library that provides a definition. Symbols overridden in this manner may become visible again if the overriding definition is removed. .IP Possible symbol types include: .RS .RS .TP 22 .C TYPE_PROCEDURE Symbol is a function. .TP .C TYPE_DATA Symbol is data. .RE .RE .IP Possible flag values include: None defined at the present time. Zero should be passed in to prevent conflicts with future uses of this flag. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_getsymbols() Provides an array of symbol records, allocated using the supplied memory allocator, that are associated with the library specified by .IR handle . If the .I handle argument is a pointer to .SM NULL, symbols defined using .C shl_definesym() are returned. If multiple versions of the same symbol have been defined within a library or with .CR shl_definesym() , only the version from the specified symbol information source that would be considered for symbol binding is returned. The .I type argument is used to restrict the return information to a specific type. Values of .CR TYPE_PROCEDURE , .CR TYPE_DATA , and .C TYPE_STORAGE can be used to limit the returned symbols to be either code, data, or storage respectively; the .C TYPE_DATA value causes both data and storage symbols to be returned. The constant .C TYPE_UNDEFINED can be used to return all symbols, regardless of type. The .I flags argument must have one of the following values: .RS .RS .TP 15 .C IMPORT_SYMBOLS Return symbols found on the import list. .TP .C EXPORT_SYMBOLS Return symbols found on the export list. All symbols defined by .C shl_definesym() are export symbols. .TP .C INITIALIZERS Return symbols that are specified as the initializers of the library. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 15 .C NO_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Do not calculate the value field in the return structure to avoid symbol binding by the loader to resolve symbol dependencies. If only a few symbol values are needed, .C shl_findsym() can be used to find the values of interesting symbols. Not to be used with .CR GLOBAL_VALUES . .TP .C GLOBAL_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Use the name and type information of each return symbol and find the most visible occurrence using all symbol information sources. The value and handle fields in the symbol return structure reflect where the most visible occurrence was found. Not to be used with .CR NO_VALUES . .RE .RE .IP The .I memory argument should point to a function with the same interface as .C malloc() (see .IR malloc (3C)). .IP The return information consists of an array of the following records (defined in .RC < dl.h >): .RS .nf .IP .C "struct shl_symbol {" .C " char *name," .C " short type," .C " void *value," .C " shl_t handle," .C }; .fi .RE .IP The .I type field in the return structure can have the values .CR TYPE_PROCEDURE , .CR TYPE_DATA , or .CR TYPE_STORAGE , where .C TYPE_STORAGE is a subset of .CR TYPE_DATA . The .I value and .I handle fields are only valid if export symbols are requested and the .C NO_VALUES flag is not specified. The .I value field contains the address of the symbol, while the .I handle field is the handle of the library that defined the symbol, or .SM NULL for symbols defined via the .C shl_definesym() routine and is useful in conjunction with the .C GLOBAL_VALUES flag. .IP If successful, .C shl_getsymbols() returns the number of symbols found; otherwise it returns \(mi1. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_unload() Can be used to detach a shared library from the process. The .I handle argument should be the handle returned from a previous call to .CR shl_load() . .C shl_unload() returns 0 if successful; otherwise \(mi1 is returned. Any initializers registered with the library are called before detachment. All explicitly loaded libraries are detached automatically on process termination. .TP .C shl_get() Returns information about currently loaded libraries, including those loaded implicitly at startup time. The index argument is the ordinal position of the shared library in the shared library search list for the process. A subsequent call to .C shl_unload() decrements the index values of all libraries having an index greater than the unloaded library. The index value \(mi1 refers to the dynamic loader. The .I desc argument is used to return a pointer to a statically allocated buffer containing a descriptor for the shared library. The format of the descriptor is implementation dependent; to examine its format, look at the contents of file .CR /usr/include/dl.h . Information common to all implementations includes the library handle, pathname, and the range of addresses the library occupies. The buffer for the descriptor used by .C shl_get() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 if an invalid .I index is given. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle() Returns information about the library specified by the handle argument. The special handle .C PROG_HANDLE can be used to refer to the program itself. The descriptor returned is the same as the one returned by the .C shl_get() routine. The buffer for the descriptor used by .C shl_gethandle() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 on error. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_get_r() This is a reentrant version of .CR shl_get() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_get() . This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle_r() This is a reentrant version of .CR shl_gethandle() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_gethandle() . This routine may not be supported in future 64-bit HP-UX releases. .SH DIAGNOSTICS If a library cannot be loaded, .C shl_load() returns .SM NULL and sets .C errno to indicate the error. All other functions return \(mi1 on error and set .CR errno . .PP If .C shl_findsym() cannot find the indicated symbol, .C errno is set to zero. If .C shl_findsym() finds the indicated symbol but cannot resolve all the symbols it depends on, .C errno is set to .SM ENOSYM. .SH ERRORS Possible values for .C errno include: .RS .TP 15 .SM [ENOEXEC] The specified file is not a shared library, or a format error was detected. .TP .SM [ENOSYM] Some symbol required by the shared library could not be found. .TP .SM [EINVAL] The specified handle or index is not valid or an attempt was made to load a library at an invalid address. .TP .SM [ENOMEM] There is insufficient room in the address space to load the library. .TP .SM [ENOENT] The specified library does not exist. .TP .SM [EACCES] Read or execute permission is denied for the specified library. .RE .SH WARNINGS .C shl_unload() detaches the library from the process and frees the memory allocated for it, but does not break existing symbolic linkages into the library. In this respect, an unloaded shared library is much like a block of memory deallocated via .C free() (see .IR free (3C)). .PP Some implementations may not, by default, export all symbols defined by a program (instead exporting only those symbols that are imported by a shared library seen at link time). Therefore the .C -E option to .IR ld (1) should be used when using these routines if the loaded libraries are to refer to program symbols. .PP All symbol information returned by .CR shl_getsymbols() , including the name field, become invalid once the associated library is unloaded by .CR shl_unload() . .PP When a routine or flag is used which may not be supported in the future, the dynamic loader can display a warning message. See the .CR WARNINGS section in .IR dld.sl (5) for further details. .PP Future HP-UX 64-bit environments may only support a subset of these routines and flags. Instead, they will use the SVR4 dynamic loading API. .SH AUTHOR .IR shl_load (3X) and related functions were developed by HP. .SH SEE ALSO .PD .SS System Tools: .TP 18 ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 dld.sl(5) dynamic loader .PD .SS Texts and Tutorials .TP 18 .IR "HP-UX Linker and Libraries Online User Guide" (See the .CR +help option to .IR ld (1)) .TP .IR "Programming on HP-UX" (See .IR manuals (5) for ordering information) .PD .\" .\" index@\f4shl_load()\fP \- load shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_unload()\fP \- unload shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_findsym()\fP \- look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_get()\fP \- get information about shared library@@@\f3shl_load(3X)\f1 .\" index@shared library, load or unload@@@\f3shl_load(3X)\f1 .\" index@shared library, look up symbol in@@@\f3shl_load(3X)\f1 .\" index@load shared library@@@\f3shl_load(3X)\f1 .\" index@unload shared library@@@\f3shl_load(3X)\f1 .\" index@look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@symbol, look up in shared library@@@\f3shl_load(3X)\f1 .\" index@get information about shared library@@@\f3shl_load(3X)\f1 .\" index@explicit load of shared libraries@@@\f3shl_load(3X)\f1 .\" .\" toc@\f3shl_load(3X)\f1:\0\0\f4shl_load()\fP, \f4shl_findsym()\fP, \f4shl_unload()\fP, \f4shl_get()\fP@@@explicit load of shared libraries .\" toc@\f4shl_load()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_unload()\fP \- unload shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- get information about shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_definesym()\fP \- define new symbol for shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_get_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" .\" links@shl_load.3x shl_defines.3x .\" links@shl_load.3x shl_findsym.3x .\" links@shl_load.3x shl_gethand.3x .\" links@shl_load.3x shl_getsymb.3x .\" links@shl_load.3x shl_unload.3x .\" links@shl_load.3x shl_get.3x .\" links@shl_load.3x shl_get_r.3x .\" links@shl_load.3x shl_get_handle_r.3x .\" .\" $Header: shl_load.3x,v 78.1 96/02/12 14:14:40 ssa Exp $ .TA s .TH shl_load 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME shl_load(\|), shl_definesym(\|), shl_findsym(\|), shl_gethandle(\|), shl_getsymbols(\|), shl_unload(\|), shl_get(\|), shl_gethandle_r(\|), shl_get_r(\|) \- explicit load of shared libraries .SH SYNOPSIS .nf .C "#include " .PP .C "shl_t shl_load(const char *path, int flags, long address);" .PP .C "int shl_findsym(" .PD 0 .IP .C shl_t *handle, .C "const char *sym," .C "short type," .C "void *value" .PP .C ");" .PD .PP .C "int shl_definesym(" .nf .PD 0 .IP .C const char *sym, .C short type, .C long value, .C int flags .PP .C ");" .PD .PP .C "int shl_getsymbols(" .nf .PD 0 .IP .C shl_t handle, .C short type, .C int flags, .C void *(*memory) (), .C struct shl_symbol **symbols, .PP .C ");" .PD .fi .PP .C "int shl_unload(shl_t handle);" .PP .C "int shl_get(int index, struct shl_descriptor **desc);" .PP .C "int shl_gethandle(shl_t handle, struct shl_descriptor **desc);" .PP .C "int shl_get_r(int index, struct shl_descriptor *desc);" .PP .C "int shl_gethandle_r(shl_t handle, struct shl_descriptor *desc);" .SH DESCRIPTION These routines can be used to programmatically load and unload shared libraries, and to obtain information about the libraries (such as the addresses of symbols defined within them). The routines themselves are accessed by specifying the .C \-ldld option on the command line with the .C cc or .C ld command (see .IR cc (1) and .IR ld (1)). In addition, the .C \-E option to the .C ld command can be used to ensure that all symbols defined in the program are available to the loaded libraries. .PP Shared libraries are created by compiling source files with the .C \+z or .C \+Z (position-independent code) options, and linking the resultant object files with the .C \-b (create shared library) option. .TP 20 .C shl_load() Attaches the shared library named by .I path .C or the shared library name that is constructed by using the path part of .I path plus the shared library basename followed by the suffix .C .0 (e.g. .C /usr/lib/libname.0 ) to the process, along with all its dependent libraries. A .C .0 version is looked for first for those shared libraries that do not have internal names. See .IR ld (1)). The library is mapped at the specified .IR address . If .I address is .CR 0L , the system chooses an appropriate address for the library. This is the recommended practice because the system has the most complete knowledge of the address space; currently, the .I address field is ignored, and assumed to be .CR 0L . The flags argument is made up of several fields. One of the following must be specified: .RS .RS .TP 22 .C BIND_IMMEDIATE Resolve symbol references when the library is loaded. .TP .C BIND_DEFERRED Delay code symbol resolution until actual reference. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 22 .C BIND_FIRST Place the library at the head of the symbol search order. In default mode, the library and its dependent libraries are bound independently of each other (see .CR BIND_TOGETHER ). This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NONFATAL Default .C BIND_IMMEDIATE behavior is to treat all unsatisfied symbols as fatal. This flag allows binding of unsatisfied code symbols to be deferred until use. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_NOSTART Do not call the initializers for the shared library when the library is loaded, nor on a future call to .CR shl_unload() ; by default, all the initializers registered with the specified library are invoked upon loading. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_VERBOSE Print verbose messages concerning possible unsatisfied symbols. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_RESTRICTED Restrict symbols visible to the library to those present at the time the library is loaded. This flag may not be supported in future 64-bit HP-UX releases. .TP .C DYNAMIC_PATH Allow the loader to dynamically search for the library specified by the .I path argument. The directories to be searched are determined by the .C +s and .C +b options of the .C ld command used when the program was linked. This flag may not be supported in future 64-bit HP-UX releases. .TP .C BIND_TOGETHER When used with .CR BIND_FIRST , the library being mapped and its dependent libraries will be bound together. This is the default behavior for all .C shl_load() requests not using .CR BIND_FIRST . This flag may not be supported in future 64-bit HP-UX releases. .RE .RE .IP If successful, .C shl_load() returns a handle which can be used in subsequent calls to .CR shl_findsym() , .CR shl_unload() , .CR shl_gethandle() , or .CR shl_gethandle_r() ; otherwise .SM NULL is returned. .TP .C shl_findsym() Obtains the address of an exported symbol .I sym from a shared library. The .I handle argument should be a pointer to the handle of a loaded shared library that was returned from a previous call to .C shl_load() or .CR shl_get() . If a pointer to .SM NULL is passed for this argument, .C shl_findsym() searches all currently loaded shared libraries and the program to find the symbol; otherwise .C shl_findsym() searches only the specified shared library. The return value of handle will be .SM NULL if the symbol found was generated via .CR shl_definesym() . Otherwise the handle of the library where the symbol was found is returned. The special handle .C PROG_HANDLE can be used to refer to the program itself, so that symbols exported from the program can also be accessed dynamically. The .I type argument specifies the expected type for the symbol, and should be one of the defined constants .CR TYPE_PROCEDURE , .CR TYPE_DATA , .CR TYPE_STORAGE , or .CR TYPE_UNDEFINED . The latter value suppresses type checking. (The first three constants may not be supported in future 64-bit HP-UX releases.) The address of the symbol is returned in the variable pointed to by .IR value . If a shared library contains multiple versions of the requested symbol, the latest version is returned. This routine returns 0 if successful; otherwise \(mi1 is returned. .TP .C shl_definesym() Adds a symbol to the shared library symbol table for the current process making it the most visible definition. If the .I value falls in the range of a currently loaded library, an association will be made and the symbol is undefined once the associated library is unloaded. The defined symbol can be overridden by a subsequent call to this routine or by loading a more visible library that provides a definition. Symbols overridden in this manner may become visible again if the overriding definition is removed. .IP Possible symbol types include: .RS .RS .TP 22 .C TYPE_PROCEDURE Symbol is a function. .TP .C TYPE_DATA Symbol is data. .RE .RE .IP Possible flag values include: None defined at the present time. Zero should be passed in to prevent conflicts with future uses of this flag. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_getsymbols() Provides an array of symbol records, allocated using the supplied memory allocator, that are associated with the library specified by .IR handle . If the .I handle argument is a pointer to .SM NULL, symbols defined using .C shl_definesym() are returned. If multiple versions of the same symbol have been defined within a library or with .CR shl_definesym() , only the version from the specified symbol information source that would be considered for symbol binding is returned. The .I type argument is used to restrict the return information to a specific type. Values of .CR TYPE_PROCEDURE , .CR TYPE_DATA , and .C TYPE_STORAGE can be used to limit the returned symbols to be either code, data, or storage respectively; the .C TYPE_DATA value causes both data and storage symbols to be returned. The constant .C TYPE_UNDEFINED can be used to return all symbols, regardless of type. The .I flags argument must have one of the following values: .RS .RS .TP 15 .C IMPORT_SYMBOLS Return symbols found on the import list. .TP .C EXPORT_SYMBOLS Return symbols found on the export list. All symbols defined by .C shl_definesym() are export symbols. .TP .C INITIALIZERS Return symbols that are specified as the initializers of the library. .RE .RE .IP Zero or more of the following can be specified by doing a bitwise .SM OR operation: .RS .RS .TP 15 .C NO_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Do not calculate the value field in the return structure to avoid symbol binding by the loader to resolve symbol dependencies. If only a few symbol values are needed, .C shl_findsym() can be used to find the values of interesting symbols. Not to be used with .CR GLOBAL_VALUES . .TP .C GLOBAL_VALUES Only makes sense when combined with .C EXPORT_SYMBOLS or .CR INITIALIZERS . Use the name and type information of each return symbol and find the most visible occurrence using all symbol information sources. The value and handle fields in the symbol return structure reflect where the most visible occurrence was found. Not to be used with .CR NO_VALUES . .RE .RE .IP The .I memory argument should point to a function with the same interface as .C malloc() (see .IR malloc (3C)). .IP The return information consists of an array of the following records (defined in .RC < dl.h >): .RS .nf .IP .C "struct shl_symbol {" .C " char *name," .C " short type," .C " void *value," .C " shl_t handle," .C }; .fi .RE .IP The .I type field in the return structure can have the values .CR TYPE_PROCEDURE , .CR TYPE_DATA , or .CR TYPE_STORAGE , where .C TYPE_STORAGE is a subset of .CR TYPE_DATA . The .I value and .I handle fields are only valid if export symbols are requested and the .C NO_VALUES flag is not specified. The .I value field contains the address of the symbol, while the .I handle field is the handle of the library that defined the symbol, or .SM NULL for symbols defined via the .C shl_definesym() routine and is useful in conjunction with the .C GLOBAL_VALUES flag. .IP If successful, .C shl_getsymbols() returns the number of symbols found; otherwise it returns \(mi1. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_unload() Can be used to detach a shared library from the process. The .I handle argument should be the handle returned from a previous call to .CR shl_load() . .C shl_unload() returns 0 if successful; otherwise \(mi1 is returned. Any initializers registered with the library are called before detachment. All explicitly loaded libraries are detached automatically on process termination. .TP .C shl_get() Returns information about currently loaded libraries, including those loaded implicitly at startup time. The index argument is the ordinal position of the shared library in the shared library search list for the process. A subsequent call to .C shl_unload() decrements the index values of all libraries having an index greater than the unloaded library. The index value \(mi1 refers to the dynamic loader. The .I desc argument is used to return a pointer to a statically allocated buffer containing a descriptor for the shared library. The format of the descriptor is implementation dependent; to examine its format, look at the contents of file .CR /usr/include/dl.h . Information common to all implementations includes the library handle, pathname, and the range of addresses the library occupies. The buffer for the descriptor used by .C shl_get() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 if an invalid .I index is given. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle() Returns information about the library specified by the handle argument. The special handle .C PROG_HANDLE can be used to refer to the program itself. The descriptor returned is the same as the one returned by the .C shl_get() routine. The buffer for the descriptor used by .C shl_gethandle() is static; the contents should be copied elsewhere before a subsequent call to the routine. The routine returns 0 normally, or \(mi1 on error. This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_get_r() This is a reentrant version of .CR shl_get() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_get() . This routine may not be supported in future 64-bit HP-UX releases. .TP .C shl_gethandle_r() This is a reentrant version of .CR shl_gethandle() . The .I desc argument must point to a buffer of enough user-defined storage to be filled with the library descriptor described in .CR /usr/include/dl.h . Its semantics are otherwise identical to .CR shl_gethandle() . This routine may not be supported in future 64-bit HP-UX releases. .SH DIAGNOSTICS If a library cannot be loaded, .C shl_load() returns .SM NULL and sets .C errno to indicate the error. All other functions return \(mi1 on error and set .CR errno . .PP If .C shl_findsym() cannot find the indicated symbol, .C errno is set to zero. If .C shl_findsym() finds the indicated symbol but cannot resolve all the symbols it depends on, .C errno is set to .SM ENOSYM. .SH ERRORS Possible values for .C errno include: .RS .TP 15 .SM [ENOEXEC] The specified file is not a shared library, or a format error was detected. .TP .SM [ENOSYM] Some symbol required by the shared library could not be found. .TP .SM [EINVAL] The specified handle or index is not valid or an attempt was made to load a library at an invalid address. .TP .SM [ENOMEM] There is insufficient room in the address space to load the library. .TP .SM [ENOENT] The specified library does not exist. .TP .SM [EACCES] Read or execute permission is denied for the specified library. .RE .SH WARNINGS .C shl_unload() detaches the library from the process and frees the memory allocated for it, but does not break existing symbolic linkages into the library. In this respect, an unloaded shared library is much like a block of memory deallocated via .C free() (see .IR free (3C)). .PP Some implementations may not, by default, export all symbols defined by a program (instead exporting only those symbols that are imported by a shared library seen at link time). Therefore the .C -E option to .IR ld (1) should be used when using these routines if the loaded libraries are to refer to program symbols. .PP All symbol information returned by .CR shl_getsymbols() , including the name field, become invalid once the associated library is unloaded by .CR shl_unload() . .PP When a routine or flag is used which may not be supported in the future, the dynamic loader can display a warning message. See the .CR WARNINGS section in .IR dld.sl (5) for further details. .PP Future HP-UX 64-bit environments may only support a subset of these routines and flags. Instead, they will use the SVR4 dynamic loading API. .SH AUTHOR .IR shl_load (3X) and related functions were developed by HP. .SH SEE ALSO .PD .SS System Tools: .TP 18 ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 dld.sl(5) dynamic loader .PD .SS Texts and Tutorials .TP 18 .IR "HP-UX Linker and Libraries Online User Guide" (See the .CR +help option to .IR ld (1)) .TP .IR "Programming on HP-UX" (See .IR manuals (5) for ordering information) .PD .\" .\" index@\f4shl_load()\fP \- load shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_unload()\fP \- unload shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_findsym()\fP \- look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@\f4shl_get()\fP \- get information about shared library@@@\f3shl_load(3X)\f1 .\" index@shared library, load or unload@@@\f3shl_load(3X)\f1 .\" index@shared library, look up symbol in@@@\f3shl_load(3X)\f1 .\" index@load shared library@@@\f3shl_load(3X)\f1 .\" index@unload shared library@@@\f3shl_load(3X)\f1 .\" index@look up symbol in shared library@@@\f3shl_load(3X)\f1 .\" index@symbol, look up in shared library@@@\f3shl_load(3X)\f1 .\" index@get information about shared library@@@\f3shl_load(3X)\f1 .\" index@explicit load of shared libraries@@@\f3shl_load(3X)\f1 .\" .\" toc@\f3shl_load(3X)\f1:\0\0\f4shl_load()\fP, \f4shl_findsym()\fP, \f4shl_unload()\fP, \f4shl_get()\fP@@@explicit load of shared libraries .\" toc@\f4shl_load()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- explicit load of shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_unload()\fP \- unload shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_findsym()\fP \- get information about shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_definesym()\fP \- define new symbol for shared libraries@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_get_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" toc@\f4shl_gethandle_r()\fP \- get shared library information@@@see \f3shl_load(3X)\f1 .\" .\" links@shl_load.3x shl_defines.3x .\" links@shl_load.3x shl_findsym.3x .\" links@shl_load.3x shl_gethand.3x .\" links@shl_load.3x shl_getsymb.3x .\" links@shl_load.3x shl_unload.3x .\" links@shl_load.3x shl_get.3x .\" links@shl_load.3x shl_get_r.3x .\" links@shl_load.3x shl_get_handle_r.3x .\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" ...\" ...\" ...\" ...\" ...\"********************************************************************* ...\" ...\" The information in this document is subject to change without ...\" notice and should not be construed as a commitment by Open ...\" Software Foundation. ...\" ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH sigaction 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lsigaction(\|)\*O" .iX "signal" "examine and change synchronous" .SH NAME .PP \*Lsigaction\*O - Examine and change synchronous signal actions (POSIX software signal facilities) .SH "SYNOPSIS" .sS #\*Linclude .PP \*Lstruct sigaction { .nL void (\*V*sa_handler\*L) (\|); .nL sigset_t \*Vsa_mask\*L; .nL int \*Vsa_flags\*L; .nL };\*O .PP \*Lint sigaction(\*Vsig, act, oact\*L) .nL int \*Vsig\*L; .nL const struct sigaction\*V *act\*L; .nL struct sigaction\*V *oact\*L;\*O .sE .PP .br .ne 1.5i .SH "PARAMETERS" .PP .VL 3m .LI "\*Vsig\*O" Synchronous Signal to examine or change; acceptable values are defined in Appendix D. .LI "\*Vact\*O" Points to a sigaction structure that describes the action to be taken upon receipt of the signal indicated by the value of the \*Vact\*O parameter. .LI "\*Voact\*O" Points to a sigaction structure in which the signal action data in effect at the time of the \*Lsigaction(\|)\*O function call is returned. .LE .br .ne 1.5i .SH "DESCRIPTION" .PP The sigaction POSIX service allows for per-thread handlers to be installed for catching synchronous signals. It is called in a multi-threaded process to establish thread specific actions for such signals. This call is the POSIX equivalent of the sigaction system call with the following exceptions or modifications: .ML .LI The \*Lsigaction(\|)\*O routine only modifies behavior for individual threads. .LI The \*Lsigaction(\|)\*O routine only works for synchronous signals. Attempting to set a signal action for an asynchronous signal is an error. This is true even in a single-threaded process. .PP Any multi-threaded application using DCE Threads will need to use the \*Lsigwait(\|)\*O function for dealing with asynchronous signals. The \*Lsigwait(\|)\*O function can be used to synchronously wait for delivery of asynchronously generated signals. ...\".LI ...\"A process can suppress the generation of the \*LSIGCHLD\*O signal when a child stops by ...\"setting the \*LSA_NOCLDSTOP\*O bit in \*Vsa_flags\*O. .LI The \*LSA_RESTART\*O flag is always set by the underlying system in POSIX mode so that interrupted system calls will fail with return value of -1 and the \*LEINTR\*O error in \*Verrno\*O instead of getting restarted. .PP The system's \*LSA_RESTART\*O flag has the opposite meaning of the \*LSA_RESTART\*O flag in the \*Vsa_flags\*O field and is always set in the underlying system call resulting from \*Lsigaction(\|)\*O regardless of whether \*LSA_RESTART\*O was indicated in \*Vsa_flags\*O. .LI The signal mask is manipulated using the POSIX \(sc 3.3.3 \*Lsigsetops(\|)\*O functions. They are \*Lsigemptyset(\|)\*O, \*Lsigfillset(\|)\*O, \*Lsigaddset(\|)\*O, \*Lsigdelset(\|)\*O, and \*Lsigismember(\|)\*O. .LE .PP The \*Lsigaction(\|)\*O function can be used to inquire about the current handling of a given signal by specifying a null pointer for \*Vact\*O, since the action is unchanged unless this parameter is not a null pointer. In order for the signal action in effect at the time of the \*Lsigaction(\|)\*O call to be returned, the \*Voact\*O parameter must not be a null pointer. .br .ne 1.5i .SH "RETURN VALUES" .PP Possible return values are as follows: .sp .TS center tab(%); l | l | l n | l | lw(3.0i). \*LReturn%Error%Description\*O _ 0%%Successful completion. \-1%[\*LEFAULT\*O]%Either \*Vact\*O or \*Voact\*O points to memory which is not a valid part %%of the process address space. %%A new signal handler is not installed. \-1%[\*LEINVAL\*O]%The value specified by \*Vsig\*O is invalid. %%A new signal handler is not installed. \-1%[\*LEINVAL\*O]%An attempt is made to ignore or supply a handler for %%\*LSIGKILL\*O or \*LSIGSTOP\*O. %%A new signal handler is not installed. .TE .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lsigvec(2)\*O, \*Lsigsetops(3)\*O, \*Lsigprocmask(3)\*O, \*Lsigsuspend(3)\*O, \*Lsigpending(3)\*O, \*Lsetjmp(3)\*O, \*Lsiginterrupt(3)\*O, \*Ltty(4)\*O. .ad b ...\" .\" $Header: sigsetops.3c,v 72.4 94/11/15 09:56:17 ssa Exp $ .TA s .TH sigsetops 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigemptyset(\|), sigfillset(\|), sigaddset(\|), sigdelset(\|), sigismember(\|) \- initialize, manipulate, and test signal sets .SH SYNOPSIS .C "#include " .PP .C "int sigemptyset(sigset_t *set);" .PP .C "int sigfillset(sigset_t *set);" .PP .C "int sigaddset(sigset_t *set, int signo);" .PP .C "int sigdelset(sigset_t *set, int signo);" .PP .C "int sigismember(const sigset_t *set, int signo);" .SH DESCRIPTION .C sigemptyset() initializes the signal set pointed to by .I set, to exclude all signals supported by .SM HP-UX. .PP .C sigfillset() initializes the signal set pointed to by .I set, to include all signals supported by .SM HP-UX. .PP Applications must call either .C sigemptyset() or .C sigfillset() at least once for each object of type .C sigset_t before using that object for anything else, including cases where the object is returned from a function (for example, the .I oset argument to .C sigprocmask() \(em see .IR sigprocmask (2)). .PP .C sigaddset() adds the signal specified by .I signo to the signal set pointed to by .IR set . .PP .C sigdelset() deletes the signal specified by .I signo from the signal set pointed to by .I set. .PP .C sigismember() tests whether the signal specified by .I signo is a member of the signal set pointed to by .IR set . .SH RETURN VALUE Upon successful completion, .C sigismember() returns a value of 1 if the specified signal is a member of the specified set, or a value of 0 if it is not. The other functions return a value of 0 upon successful completion. For all of the above functions, if an error is detected, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .CR sigaddset() , .CR sigdelset() , and .C sigismember() fail if the following is true: .RS .TP 15 .SM [EINVAL] The value of the .I signo argument is out of range. The reliable detection of this error is not guaranteed. .RE .SH WARNINGS The above functions do not detect a bad address passed in for the .I set argument. A segmentation fault is the most likely result. .SH AUTHOR .CR sigfillset() , .CR sigemptyset() , .CR sigaddset() , .CR sigdelset() , and .C sigismember() were derived from the .SM .I IEEE .I "Standard POSIX 1003.1-1988" . .SH SEE ALSO sigaction(2), sigsuspend(2), sigpending(2), sigprocmask(2), signal(5). .SH STANDARDS CONFORMANCE .CR sigaddset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigdelset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigemptyset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigfillset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigismember() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4sigemptyset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigfillset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigaddset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigdelset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigismember()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@manipulate, initialize, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@test, initialize, and manipulate signal sets@@@\f3sigsetops(3C)\f1 .\" index@signal sets, initialize, manipulate, and test@@@\f3sigsetops(3C)\f1 .\" toc@\f3sigsetops(3C)\f1:\0\0\f4sigemptyset()\fP, \f4sigfillset()\fP, \f4sigaddset()\fP,\n\f4sigdelset()\fP, \f4sigismember()\fP@@@initialize, manipulate, and test signal sets .\" toc@\f4sigemptyset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigfillset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigaddset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigdelset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigismember()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" links@sigsetops.3c sigemptyset.3c .\" links@sigsetops.3c sigfillset.3c .\" links@sigsetops.3c sigaddset.3c .\" links@sigsetops.3c sigdelset.3c .\" links@sigsetops.3c sigismember.3c .\" .\" fileset_database@sigsetops.3c PROGRAMING-MAN .\" $Header: sigsetops.3c,v 72.4 94/11/15 09:56:17 ssa Exp $ .TA s .TH sigsetops 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigemptyset(\|), sigfillset(\|), sigaddset(\|), sigdelset(\|), sigismember(\|) \- initialize, manipulate, and test signal sets .SH SYNOPSIS .C "#include " .PP .C "int sigemptyset(sigset_t *set);" .PP .C "int sigfillset(sigset_t *set);" .PP .C "int sigaddset(sigset_t *set, int signo);" .PP .C "int sigdelset(sigset_t *set, int signo);" .PP .C "int sigismember(const sigset_t *set, int signo);" .SH DESCRIPTION .C sigemptyset() initializes the signal set pointed to by .I set, to exclude all signals supported by .SM HP-UX. .PP .C sigfillset() initializes the signal set pointed to by .I set, to include all signals supported by .SM HP-UX. .PP Applications must call either .C sigemptyset() or .C sigfillset() at least once for each object of type .C sigset_t before using that object for anything else, including cases where the object is returned from a function (for example, the .I oset argument to .C sigprocmask() \(em see .IR sigprocmask (2)). .PP .C sigaddset() adds the signal specified by .I signo to the signal set pointed to by .IR set . .PP .C sigdelset() deletes the signal specified by .I signo from the signal set pointed to by .I set. .PP .C sigismember() tests whether the signal specified by .I signo is a member of the signal set pointed to by .IR set . .SH RETURN VALUE Upon successful completion, .C sigismember() returns a value of 1 if the specified signal is a member of the specified set, or a value of 0 if it is not. The other functions return a value of 0 upon successful completion. For all of the above functions, if an error is detected, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .CR sigaddset() , .CR sigdelset() , and .C sigismember() fail if the following is true: .RS .TP 15 .SM [EINVAL] The value of the .I signo argument is out of range. The reliable detection of this error is not guaranteed. .RE .SH WARNINGS The above functions do not detect a bad address passed in for the .I set argument. A segmentation fault is the most likely result. .SH AUTHOR .CR sigfillset() , .CR sigemptyset() , .CR sigaddset() , .CR sigdelset() , and .C sigismember() were derived from the .SM .I IEEE .I "Standard POSIX 1003.1-1988" . .SH SEE ALSO sigaction(2), sigsuspend(2), sigpending(2), sigprocmask(2), signal(5). .SH STANDARDS CONFORMANCE .CR sigaddset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigdelset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigemptyset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigfillset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigismember() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4sigemptyset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigfillset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigaddset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigdelset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigismember()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@manipulate, initialize, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@test, initialize, and manipulate signal sets@@@\f3sigsetops(3C)\f1 .\" index@signal sets, initialize, manipulate, and test@@@\f3sigsetops(3C)\f1 .\" toc@\f3sigsetops(3C)\f1:\0\0\f4sigemptyset()\fP, \f4sigfillset()\fP, \f4sigaddset()\fP,\n\f4sigdelset()\fP, \f4sigismember()\fP@@@initialize, manipulate, and test signal sets .\" toc@\f4sigemptyset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigfillset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigaddset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigdelset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigismember()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" links@sigsetops.3c sigemptyset.3c .\" links@sigsetops.3c sigfillset.3c .\" links@sigsetops.3c sigaddset.3c .\" links@sigsetops.3c sigdelset.3c .\" links@sigsetops.3c sigismember.3c .\" .\" fileset_database@sigsetops.3c PROGRAMING-MAN .\" $Header: sigsetops.3c,v 72.4 94/11/15 09:56:17 ssa Exp $ .TA s .TH sigsetops 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigemptyset(\|), sigfillset(\|), sigaddset(\|), sigdelset(\|), sigismember(\|) \- initialize, manipulate, and test signal sets .SH SYNOPSIS .C "#include " .PP .C "int sigemptyset(sigset_t *set);" .PP .C "int sigfillset(sigset_t *set);" .PP .C "int sigaddset(sigset_t *set, int signo);" .PP .C "int sigdelset(sigset_t *set, int signo);" .PP .C "int sigismember(const sigset_t *set, int signo);" .SH DESCRIPTION .C sigemptyset() initializes the signal set pointed to by .I set, to exclude all signals supported by .SM HP-UX. .PP .C sigfillset() initializes the signal set pointed to by .I set, to include all signals supported by .SM HP-UX. .PP Applications must call either .C sigemptyset() or .C sigfillset() at least once for each object of type .C sigset_t before using that object for anything else, including cases where the object is returned from a function (for example, the .I oset argument to .C sigprocmask() \(em see .IR sigprocmask (2)). .PP .C sigaddset() adds the signal specified by .I signo to the signal set pointed to by .IR set . .PP .C sigdelset() deletes the signal specified by .I signo from the signal set pointed to by .I set. .PP .C sigismember() tests whether the signal specified by .I signo is a member of the signal set pointed to by .IR set . .SH RETURN VALUE Upon successful completion, .C sigismember() returns a value of 1 if the specified signal is a member of the specified set, or a value of 0 if it is not. The other functions return a value of 0 upon successful completion. For all of the above functions, if an error is detected, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .CR sigaddset() , .CR sigdelset() , and .C sigismember() fail if the following is true: .RS .TP 15 .SM [EINVAL] The value of the .I signo argument is out of range. The reliable detection of this error is not guaranteed. .RE .SH WARNINGS The above functions do not detect a bad address passed in for the .I set argument. A segmentation fault is the most likely result. .SH AUTHOR .CR sigfillset() , .CR sigemptyset() , .CR sigaddset() , .CR sigdelset() , and .C sigismember() were derived from the .SM .I IEEE .I "Standard POSIX 1003.1-1988" . .SH SEE ALSO sigaction(2), sigsuspend(2), sigpending(2), sigprocmask(2), signal(5). .SH STANDARDS CONFORMANCE .CR sigaddset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigdelset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigemptyset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigfillset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigismember() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4sigemptyset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigfillset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigaddset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigdelset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigismember()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@manipulate, initialize, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@test, initialize, and manipulate signal sets@@@\f3sigsetops(3C)\f1 .\" index@signal sets, initialize, manipulate, and test@@@\f3sigsetops(3C)\f1 .\" toc@\f3sigsetops(3C)\f1:\0\0\f4sigemptyset()\fP, \f4sigfillset()\fP, \f4sigaddset()\fP,\n\f4sigdelset()\fP, \f4sigismember()\fP@@@initialize, manipulate, and test signal sets .\" toc@\f4sigemptyset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigfillset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigaddset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigdelset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigismember()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" links@sigsetops.3c sigemptyset.3c .\" links@sigsetops.3c sigfillset.3c .\" links@sigsetops.3c sigaddset.3c .\" links@sigsetops.3c sigdelset.3c .\" links@sigsetops.3c sigismember.3c .\" .\" fileset_database@sigsetops.3c PROGRAMING-MAN .\" $Header: sigsetops.3c,v 72.4 94/11/15 09:56:17 ssa Exp $ .TA s .TH sigsetops 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigemptyset(\|), sigfillset(\|), sigaddset(\|), sigdelset(\|), sigismember(\|) \- initialize, manipulate, and test signal sets .SH SYNOPSIS .C "#include " .PP .C "int sigemptyset(sigset_t *set);" .PP .C "int sigfillset(sigset_t *set);" .PP .C "int sigaddset(sigset_t *set, int signo);" .PP .C "int sigdelset(sigset_t *set, int signo);" .PP .C "int sigismember(const sigset_t *set, int signo);" .SH DESCRIPTION .C sigemptyset() initializes the signal set pointed to by .I set, to exclude all signals supported by .SM HP-UX. .PP .C sigfillset() initializes the signal set pointed to by .I set, to include all signals supported by .SM HP-UX. .PP Applications must call either .C sigemptyset() or .C sigfillset() at least once for each object of type .C sigset_t before using that object for anything else, including cases where the object is returned from a function (for example, the .I oset argument to .C sigprocmask() \(em see .IR sigprocmask (2)). .PP .C sigaddset() adds the signal specified by .I signo to the signal set pointed to by .IR set . .PP .C sigdelset() deletes the signal specified by .I signo from the signal set pointed to by .I set. .PP .C sigismember() tests whether the signal specified by .I signo is a member of the signal set pointed to by .IR set . .SH RETURN VALUE Upon successful completion, .C sigismember() returns a value of 1 if the specified signal is a member of the specified set, or a value of 0 if it is not. The other functions return a value of 0 upon successful completion. For all of the above functions, if an error is detected, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .CR sigaddset() , .CR sigdelset() , and .C sigismember() fail if the following is true: .RS .TP 15 .SM [EINVAL] The value of the .I signo argument is out of range. The reliable detection of this error is not guaranteed. .RE .SH WARNINGS The above functions do not detect a bad address passed in for the .I set argument. A segmentation fault is the most likely result. .SH AUTHOR .CR sigfillset() , .CR sigemptyset() , .CR sigaddset() , .CR sigdelset() , and .C sigismember() were derived from the .SM .I IEEE .I "Standard POSIX 1003.1-1988" . .SH SEE ALSO sigaction(2), sigsuspend(2), sigpending(2), sigprocmask(2), signal(5). .SH STANDARDS CONFORMANCE .CR sigaddset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigdelset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigemptyset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigfillset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigismember() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4sigemptyset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigfillset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigaddset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigdelset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigismember()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@manipulate, initialize, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@test, initialize, and manipulate signal sets@@@\f3sigsetops(3C)\f1 .\" index@signal sets, initialize, manipulate, and test@@@\f3sigsetops(3C)\f1 .\" toc@\f3sigsetops(3C)\f1:\0\0\f4sigemptyset()\fP, \f4sigfillset()\fP, \f4sigaddset()\fP,\n\f4sigdelset()\fP, \f4sigismember()\fP@@@initialize, manipulate, and test signal sets .\" toc@\f4sigemptyset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigfillset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigaddset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigdelset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigismember()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" links@sigsetops.3c sigemptyset.3c .\" links@sigsetops.3c sigfillset.3c .\" links@sigsetops.3c sigaddset.3c .\" links@sigsetops.3c sigdelset.3c .\" links@sigsetops.3c sigismember.3c .\" .\" fileset_database@sigsetops.3c PROGRAMING-MAN .\" $Header: sigsetops.3c,v 72.4 94/11/15 09:56:17 ssa Exp $ .TA s .TH sigsetops 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigemptyset(\|), sigfillset(\|), sigaddset(\|), sigdelset(\|), sigismember(\|) \- initialize, manipulate, and test signal sets .SH SYNOPSIS .C "#include " .PP .C "int sigemptyset(sigset_t *set);" .PP .C "int sigfillset(sigset_t *set);" .PP .C "int sigaddset(sigset_t *set, int signo);" .PP .C "int sigdelset(sigset_t *set, int signo);" .PP .C "int sigismember(const sigset_t *set, int signo);" .SH DESCRIPTION .C sigemptyset() initializes the signal set pointed to by .I set, to exclude all signals supported by .SM HP-UX. .PP .C sigfillset() initializes the signal set pointed to by .I set, to include all signals supported by .SM HP-UX. .PP Applications must call either .C sigemptyset() or .C sigfillset() at least once for each object of type .C sigset_t before using that object for anything else, including cases where the object is returned from a function (for example, the .I oset argument to .C sigprocmask() \(em see .IR sigprocmask (2)). .PP .C sigaddset() adds the signal specified by .I signo to the signal set pointed to by .IR set . .PP .C sigdelset() deletes the signal specified by .I signo from the signal set pointed to by .I set. .PP .C sigismember() tests whether the signal specified by .I signo is a member of the signal set pointed to by .IR set . .SH RETURN VALUE Upon successful completion, .C sigismember() returns a value of 1 if the specified signal is a member of the specified set, or a value of 0 if it is not. The other functions return a value of 0 upon successful completion. For all of the above functions, if an error is detected, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .CR sigaddset() , .CR sigdelset() , and .C sigismember() fail if the following is true: .RS .TP 15 .SM [EINVAL] The value of the .I signo argument is out of range. The reliable detection of this error is not guaranteed. .RE .SH WARNINGS The above functions do not detect a bad address passed in for the .I set argument. A segmentation fault is the most likely result. .SH AUTHOR .CR sigfillset() , .CR sigemptyset() , .CR sigaddset() , .CR sigdelset() , and .C sigismember() were derived from the .SM .I IEEE .I "Standard POSIX 1003.1-1988" . .SH SEE ALSO sigaction(2), sigsuspend(2), sigpending(2), sigprocmask(2), signal(5). .SH STANDARDS CONFORMANCE .CR sigaddset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigdelset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigemptyset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigfillset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigismember() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4sigemptyset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigfillset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigaddset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigdelset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigismember()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@manipulate, initialize, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@test, initialize, and manipulate signal sets@@@\f3sigsetops(3C)\f1 .\" index@signal sets, initialize, manipulate, and test@@@\f3sigsetops(3C)\f1 .\" toc@\f3sigsetops(3C)\f1:\0\0\f4sigemptyset()\fP, \f4sigfillset()\fP, \f4sigaddset()\fP,\n\f4sigdelset()\fP, \f4sigismember()\fP@@@initialize, manipulate, and test signal sets .\" toc@\f4sigemptyset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigfillset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigaddset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigdelset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigismember()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" links@sigsetops.3c sigemptyset.3c .\" links@sigsetops.3c sigfillset.3c .\" links@sigsetops.3c sigaddset.3c .\" links@sigsetops.3c sigdelset.3c .\" links@sigsetops.3c sigismember.3c .\" .\" fileset_database@sigsetops.3c PROGRAMING-MAN .\" $Header: setjmp.3c,v 72.5 94/11/15 09:56:14 ssa Exp $ .TA s .TH setjmp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setjmp(\|), longjmp(\|), sigsetjmp(\|), siglongjmp(\|) \- non-local goto .SH SYNOPSIS .C "#include " .PP .C "int setjmp(jmp_buf env);" .PP .C "void longjmp(jmp_buf env, int val);" .PP .C "int _setjmp(jmp_buf env);" .PP .C "void _longjmp(jmp_buf env, int val);" .PP .C "int sigsetjmp(sigjmp_buf env, int savemask);" .PP .C "void siglongjmp(sigjmp_buf env, int val);" .SH DESCRIPTION .C setjmp() and .C longjmp() are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. They exist in three variant forms: .CR setjmp() and .CR longjmp() ; .CR _setjmp() and .CR _longjmp() ; .CR sigsetjmp() and .CR siglongjmp() . Unless indicated otherwise, references to .C setjmp() and .C longjmp() apply to all three versions. .RS .TP 18 .C setjmp() saves its stack environment in .I env (whose type, .CR jmp_buf , is defined in the .RC < setjmp.h > header file) for later use by .CR longjmp() . It returns the value .CR 0 . .TP .C longjmp() restores the environment saved by the last call of .C setjmp() with the corresponding .I env argument. After .C longjmp() is completed, program execution continues as if the corresponding call of .C setjmp() (which must not itself have returned in the interim) had just returned the value .IR val . .C longjmp() cannot cause .C setjmp() to return the value .CR 0 . If .C longjmp() is invoked with a second argument of .CR 0 , .C setjmp() returns .CR 1 . All accessible data values are valid as of the time .C longjmp() is called. .RE .PP Upon the return from a .C setjmp() call caused by a .CR longjmp() , the values of any non-static local variables belonging to the routine from which .C setjmp() was called are undefined. Code which depends on such values is not guaranteed to be portable. .SS Variant Forms The following functions behave the same as .C setjmp() and .C longjmp() except in the handling of the process' signal mask (see .IR sigaction (2) and .IR sigvector (2)). This distinction is only significant for programs which use .CR sigaction() , .CR sigprocmask() , .CR sigvector() , .CR sigblock() , and/or .CR sigsetmask() . .RS .TP 18 .C setjmp() .PD 0 .TP .C longjmp() These always save and restore the signal mask. .PD .TP .C _setjmp() .PD 0 .TP .C _longjmp() These never manipulate the signal mask. .PD .TP .C sigsetjmp() Saves the signal mask if and only if .I savemask is non-zero. .TP .C siglongjmp() Restores the signal mask if and only if it is saved by .CR sigsetjmp() . .SS Programming Considerations If a .C longjmp() is executed and the environment in which the .C setjmp() is executed no longer exists, errors can occur. The conditions under which the environment of the .C setjmp() no longer exists include exiting the procedure that contains the .C setjmp() call, and exiting an inner block with temporary storage (such as a block with declarations in C or a .C with statement in Pascal). This condition might not be detectable, in which case the .C longjmp() occurs and, if the environment no longer exists, the contents of the temporary storage of an inner block are unpredictable. This condition might also cause unexpected process termination. If the procedure has been exited the results are unpredictable. .PP Passing .C longjmp() a pointer to a buffer not created by .CR setjmp() , passing .C _longjmp() a pointer to a buffer not created by either .C setjmp() or .CR _setjmp() , passing .C siglongjmp() a pointer to a buffer not created by .C sigsetjmp() or passing any of these three functions a buffer that has been modified by the user, can cause all the problems listed above, and more. .PP Some implementations of Pascal support a ``try/recover'' mechanism, which also creates stack marker information. If a .C longjmp() operation occurs in a scope which is nested inside a try/recover, and the corresponding .C setjmp() is not inside the scope of the try/recover, the recover block will not be executed and the currently active recover block will become the one enclosing the .CR setjmp() , if one exists. .SH WARNINGS A call to .C longjmp() to leave the guaranteed stack space reserved by .C sigspace() might remove the guarantee that the ordinary execution of the program will not extend into the guaranteed space. It might also cause the program to forever lose its ability to automatically increase the stack size, and the program might then be limited to the guaranteed space. .PP The result of using .C setjmp() within an expression can be unpredictable. .PP If .C longjmp() is called even though .I env was never primed by a call to .CR setjmp() , or when the last such call was in a function that has since returned, total chaos is guaranteed. .SH AUTHOR .C setjmp() was developed by AT&T and HP. .SH SEE ALSO sigaction(2), sigblock(2), signal(5), sigprocmask(2), sigsetmask(2), sigspace(2), sigsuspend(2), sigvector(2). .SH STANDARDS CONFORMANCE .CR setjmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR longjmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR siglongjmp() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigsetjmp() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4_setjmp()\fP \- save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4_longjmp()\fP \- restore stack environment after non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4sigsetjmp()\fP \- save signal mask if savemask is non-zero@@@\f3setjmp(3C)\f1 .\" index@\f4setjmp()\fP \- save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4longjmp()\fP \- restore stack environment after non-local goto@@@\f3setjmp(3C)\f1 .\" index@save/restore stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@restore/save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@non-local goto, save/restore stack environment for@@@\f3setjmp(3C)\f1 .\" index@goto, save/restore stack environment for non-local@@@\f3setjmp(3C)\f1 .\" index@stack environment, save/restore for non-local goto@@@\f3setjmp(3C)\f1 .\" index@environment, save/restore stack for non-local goto@@@\f3setjmp(3C)\f1 .\" .\" toc@\f3setjmp(3S)\f1:\0\0\f4setjmp()\fP, \f4longjmp()\fP@@@save/restore stack environment for non-local goto .\" toc@\f4longjmp()\fP:\0\0restore stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" toc@\f4sigsetjmp()\fP:\0\0save signal mask if savemask is non-zero@@@see \f3setjmp(3C)\f1 .\" toc@\f4_longjmp()\fP:\0\0restore stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" toc@\f4_setjmp()\fP:\0\0save stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" .\" links@setjmp.3c longjmp.3c .\" links@setjmp.3c sigsetjmp.3c .\" links@setjmp.3c siglongjmp.3c .\" links@setjmp.3c _longjmp.3c .\" links@setjmp.3c _setjmp.3c .\" .\" fileset_database@setjmp.3c PROGRAMING-MAN .\" $Header: lgamma.3m,v 78.1 96/02/13 12:44:15 ssa Exp $ .TA l .TH lgamma 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lgamma(\|), lgamma_r(\|), gamma(\|), signgam(\|) \- log gamma function .SH SYNOPSIS .C "#include " .PP .C "double lgamma(double x);" .PP .C "double gamma(double x);" .PP .C "extern int signgam;" .PP .C "double lgamma_r(double x, int *sign); .SH DESCRIPTION .CR lgamma() and .CR gamma() return .ifn \{\ .CI ln(|Gamma( x )|)\c\} .ift \{\ .CI ln(|\(*G( x )|)\c\} , where .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} is defined as the integral, as .I t goes from zero to infinity, of .CI exp(\(mi t ) times .I t to the power .RI ( x \(mi1). .PP The sign of .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} is returned in the external integer .CR signgam . The argument .I x must not be zero or a negative integer. .RC ( lgamma() is defined over the reals excluding the non-positive integers.) .PP The following C program fragment can be used to calculate .ifn \{\ .RI Gamma( x ):\} .ift \{\ .RI \(*G( x ):\} .nf .IP .CR "if ((y = lgamma(x)) > LN_MAXDOUBLE)" .CR " error(\|);" .CR "y = signgam * exp(y);" .fi .PP where if .I y is greater than .CR LN_MAXDOUBLE , as defined in the .RC < values.h > header file, .CR exp() returns a range error (see .IR exp (3M)). .PP The log gamma function .CR lgamma() is not reentrant, because it uses the global variable .CR signgam . The function .CR lgamma_r() is a reentrant version of .CR lgamma() that can be used in multi-threaded applications. The function .CR lgamma_r() returns the sign of .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} in its parameter list, through the pointer .IR sign . The value pointed to by .I sign is +1 if .ifn \{\ .RI Gamma( x )\} .ift \{\ .RI \(*G( x )\} is positive, \-1 if it is negative. The function .CR lgamma_r() is named in the spirit of the POSIX threads draft standard (P1003.4a), but it has no formal sanction. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .I x is a non-positive integer, .CR lgamma() and .CR gamma() return .CR HUGE_VAL . .PP If the correct value would overflow, .CR lgamma() and .CR gamma() return .CR HUGE_VAL . .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR lgamma() and .CR gamma() return zero. .PP If .I x is NaN, .CR lgamma() and .CR gamma() return NaN. .SH ERRORS No errors are defined. .SH WARNINGS .CR lgamma() and .CR gamma() are unsafe in multi-thread applications. .CR lgamma_r() is MT-Safe and should be used instead. .SH SEE ALSO exp(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR lgamma() ": SVID3, XPG4.2" .PP .CR gamma() ": SVID2, XPG4.2" .PP .CR signgam ": SVID3, XPG4.2" .\" .\" index@\f4gamma()\f1, \f4lgamma()\f1, \f4lgamma_r()\f1, \f4signgam()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f4lgamma()\f1, \f4lgamma_r()\f1, \f4gamma()\f1, \f4signgam()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f4lgamma_r()\f1, \f4gamma()\f1, \f4signgam()\f1, \f4lgamma()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f4signgam()\f1, \f4gamma()\f1, \f4lgamma()\f1, \f4lgamma_r()\f1 \- log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f1math: log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f1log gamma function@@@\f3lgamma(3M)\f1 .\" index@\f1gamma function, log@@@\f3lgamma(3M)\f1 .\" .\" toc@\f3lgamma(3M)\f1:\0\0\f4gamma()\f1, \f4lgamma()\f1, \f4lgamma_r()\f1, \f4signgam()\f1@@@log gamma function .\" toc@\f4lgamma()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" toc@\f4lgamma_r()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" toc@\f4gamma()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" toc@\f4signgam()\f1:\0\0log gamma function@@@\f1see \f3lgamma(3M)\f1 .\" .\" links@lgamma.3m signgam.3m .\" links@lgamma.3m gamma.3m .\" links@lgamma.3m lgamma_r.3m ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" ...\" ...\" ...\" ...\" ...\"********************************************************************* ...\" ...\" The information in this document is subject to change without ...\" notice and should not be construed as a commitment by Open ...\" Software Foundation. ...\" ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH sigpending 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lsigprocmask(\|)\*O" .iX "signal" "examine pending signals" .SH NAME .PP \*Lsigppending\*O - Examine pending signals (POSIX software signal facilities) .SH "SYNOPSIS" .sS #\*Linclude .PP .PP \*Lint sigpending(\*Lsigset_t \*V *set\*L); .sE .PP .br .ne 1.5i .SH "PARAMETERS" .PP .VL 3m .LI "\*V set\*O" Points to a location in which the signals that are blocked from delivery and pending at the time of the \*Lsigpending(\|)\*O function call are returned. .LE .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lsigpending(\|)\*O function stores the set of signals that are blocked from delivery and pending for the calling process in the space pointed to by the argument \*Vset\*O. .PP The \*Lsigpending(\|)\*O function may be called by any thread in a multi-threaded process to determine which signals are in the pending set for that thread. Since DCE Threads supports the {_POSIX_THREADS_PER_PROCESS_SIGNALS_1} option, signals pending upon the thread are those that are pending upon the process. .br .ne 1.5i .SH "RETURN VALUES" .PP Possible return values are as follows: .sp .TS center tab(%); l | l | l n | l | lw(3.0i). \*LReturn%Error%Description\*O _ 0%%Successful completion. \-1%[\*LEFAULT\*O]%The \*Vset\*O argument points to memory that is not %%a valid part of the process address space. .TE .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lsigprocmask(3)\*O, \*Lsigsetops(3)\*O. .ad b ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" ...\" ...\" ...\" ...\" ...\"********************************************************************* ...\" ...\" The information in this document is subject to change without ...\" notice and should not be construed as a commitment by Open ...\" Software Foundation. ...\" ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH sigprocmask 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lsigprocmask(\|)\*O" .iX "signal" "examine and change blocked" .SH NAME .PP \*Lsigprocmask\*O - Examine and change blocked signals (POSIX software signal facilities) .SH "SYNOPSIS" .sS #\*Linclude .PP .PP \*Lint sigprocmask(int \*Vhow\*L, const sigset_t\*V *set\*L, sigset_t\*V *oset\*L); .sE .PP .br .ne 1.5i .SH "PARAMETERS" .PP .VL 3m .LI "\*Vhow\*O" The manner in which the values in \*Vset\*O are changed as defined by one of the argument values described below. .LI "\*Vset\*O" A set of signals that will be used to change the current thread's signal mask according to the value in the \*Vhow\*O parameter. .LI "\*Voset\*O" Points to a location in which the signal mask in effect at the time of the \*Lsigprocmask(\|)\*O function call is returned. .LE .br .ne 1.5i .SH "DESCRIPTION" .PP The \*Lsigprocmask(\|)\*O function is used to examine or change (or both) the signal mask of the calling process. If the value of the argument \*Vset\*O is not NULL, it points to a set of signals to be used to change the currently blocked set according to the \*Vhow\*O parameter as follows: .VL 1.0i .LI \*LSIG_BLOCK\*O The resulting signal set is the union of the current set and the signal set pointed to by the argument \*Vset\*O. .LI \*LSIG_UNBLOCK\*O The resulting signal set is the intersection of the current set and the and the complement of the signal set pointed to by the argument \*Vset\*O. .LI \*LSIG_SETMASK\*O The resulting signal set is the signal set pointed to by the argument \*Vset\*O. .LE .PP If the argument \*Voset\*O is not NULL, the previous mask is stored in the space pointed to by \*Voset\*O. .PP The \*Lsigprocmask(\|)\*O function can be used to inquire about the currently blocked signals by specifying a null pointer for \*Vset\*O, since the value of the argument \*Vhow\*O is not significant and the signal mask of the process is unchanged unless this parameter is not a null pointer. In order for the signal mask in effect at the time of the \*Lsigprocmask(\|)\*O call to be returned, the \*Voset\*O argument must not be a null pointer. .PP If there are any pending unblocked signals after the call to the \*Lsigprocmask(\|)\*O function, at least one of those signals shall be delivered before the \*Lsigprocmask(\|)\*O function returns. As a system restriction, the SIGKILL and SIGSTOP signals cannot be blocked. .PP If the \*Lsigprocmask(\|)\*O function fails, the signal mask of the process is not changed by this function call. .br .ne 1.5i .SH "RETURN VALUES" .PP Possible return values are as follows: .sp .TS center tab(%); l | l | l n | l | lw(3.0i). \*LReturn%Error%Description\*O _ 0%%Successful completion. \-1%[\*LEINVAL\*O]%The value specified by the \*Vhow\*O parameter is %%not equal to one of the defined values. %%The signal mask of the process remains unchanged. .TE .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lsigaction(3)\*O, \*Lsigpending(3)\*O, \*Lsigsetops(3)\*O, \*Lsigsuspend(3)\*O. .ad b ...\" .\" $Header: setjmp.3c,v 72.5 94/11/15 09:56:14 ssa Exp $ .TA s .TH setjmp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME setjmp(\|), longjmp(\|), sigsetjmp(\|), siglongjmp(\|) \- non-local goto .SH SYNOPSIS .C "#include " .PP .C "int setjmp(jmp_buf env);" .PP .C "void longjmp(jmp_buf env, int val);" .PP .C "int _setjmp(jmp_buf env);" .PP .C "void _longjmp(jmp_buf env, int val);" .PP .C "int sigsetjmp(sigjmp_buf env, int savemask);" .PP .C "void siglongjmp(sigjmp_buf env, int val);" .SH DESCRIPTION .C setjmp() and .C longjmp() are useful for dealing with errors and interrupts encountered in a low-level subroutine of a program. They exist in three variant forms: .CR setjmp() and .CR longjmp() ; .CR _setjmp() and .CR _longjmp() ; .CR sigsetjmp() and .CR siglongjmp() . Unless indicated otherwise, references to .C setjmp() and .C longjmp() apply to all three versions. .RS .TP 18 .C setjmp() saves its stack environment in .I env (whose type, .CR jmp_buf , is defined in the .RC < setjmp.h > header file) for later use by .CR longjmp() . It returns the value .CR 0 . .TP .C longjmp() restores the environment saved by the last call of .C setjmp() with the corresponding .I env argument. After .C longjmp() is completed, program execution continues as if the corresponding call of .C setjmp() (which must not itself have returned in the interim) had just returned the value .IR val . .C longjmp() cannot cause .C setjmp() to return the value .CR 0 . If .C longjmp() is invoked with a second argument of .CR 0 , .C setjmp() returns .CR 1 . All accessible data values are valid as of the time .C longjmp() is called. .RE .PP Upon the return from a .C setjmp() call caused by a .CR longjmp() , the values of any non-static local variables belonging to the routine from which .C setjmp() was called are undefined. Code which depends on such values is not guaranteed to be portable. .SS Variant Forms The following functions behave the same as .C setjmp() and .C longjmp() except in the handling of the process' signal mask (see .IR sigaction (2) and .IR sigvector (2)). This distinction is only significant for programs which use .CR sigaction() , .CR sigprocmask() , .CR sigvector() , .CR sigblock() , and/or .CR sigsetmask() . .RS .TP 18 .C setjmp() .PD 0 .TP .C longjmp() These always save and restore the signal mask. .PD .TP .C _setjmp() .PD 0 .TP .C _longjmp() These never manipulate the signal mask. .PD .TP .C sigsetjmp() Saves the signal mask if and only if .I savemask is non-zero. .TP .C siglongjmp() Restores the signal mask if and only if it is saved by .CR sigsetjmp() . .SS Programming Considerations If a .C longjmp() is executed and the environment in which the .C setjmp() is executed no longer exists, errors can occur. The conditions under which the environment of the .C setjmp() no longer exists include exiting the procedure that contains the .C setjmp() call, and exiting an inner block with temporary storage (such as a block with declarations in C or a .C with statement in Pascal). This condition might not be detectable, in which case the .C longjmp() occurs and, if the environment no longer exists, the contents of the temporary storage of an inner block are unpredictable. This condition might also cause unexpected process termination. If the procedure has been exited the results are unpredictable. .PP Passing .C longjmp() a pointer to a buffer not created by .CR setjmp() , passing .C _longjmp() a pointer to a buffer not created by either .C setjmp() or .CR _setjmp() , passing .C siglongjmp() a pointer to a buffer not created by .C sigsetjmp() or passing any of these three functions a buffer that has been modified by the user, can cause all the problems listed above, and more. .PP Some implementations of Pascal support a ``try/recover'' mechanism, which also creates stack marker information. If a .C longjmp() operation occurs in a scope which is nested inside a try/recover, and the corresponding .C setjmp() is not inside the scope of the try/recover, the recover block will not be executed and the currently active recover block will become the one enclosing the .CR setjmp() , if one exists. .SH WARNINGS A call to .C longjmp() to leave the guaranteed stack space reserved by .C sigspace() might remove the guarantee that the ordinary execution of the program will not extend into the guaranteed space. It might also cause the program to forever lose its ability to automatically increase the stack size, and the program might then be limited to the guaranteed space. .PP The result of using .C setjmp() within an expression can be unpredictable. .PP If .C longjmp() is called even though .I env was never primed by a call to .CR setjmp() , or when the last such call was in a function that has since returned, total chaos is guaranteed. .SH AUTHOR .C setjmp() was developed by AT&T and HP. .SH SEE ALSO sigaction(2), sigblock(2), signal(5), sigprocmask(2), sigsetmask(2), sigspace(2), sigsuspend(2), sigvector(2). .SH STANDARDS CONFORMANCE .CR setjmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR longjmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR siglongjmp() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigsetjmp() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4_setjmp()\fP \- save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4_longjmp()\fP \- restore stack environment after non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4sigsetjmp()\fP \- save signal mask if savemask is non-zero@@@\f3setjmp(3C)\f1 .\" index@\f4setjmp()\fP \- save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@\f4longjmp()\fP \- restore stack environment after non-local goto@@@\f3setjmp(3C)\f1 .\" index@save/restore stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@restore/save stack environment for non-local goto@@@\f3setjmp(3C)\f1 .\" index@non-local goto, save/restore stack environment for@@@\f3setjmp(3C)\f1 .\" index@goto, save/restore stack environment for non-local@@@\f3setjmp(3C)\f1 .\" index@stack environment, save/restore for non-local goto@@@\f3setjmp(3C)\f1 .\" index@environment, save/restore stack for non-local goto@@@\f3setjmp(3C)\f1 .\" .\" toc@\f3setjmp(3S)\f1:\0\0\f4setjmp()\fP, \f4longjmp()\fP@@@save/restore stack environment for non-local goto .\" toc@\f4longjmp()\fP:\0\0restore stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" toc@\f4sigsetjmp()\fP:\0\0save signal mask if savemask is non-zero@@@see \f3setjmp(3C)\f1 .\" toc@\f4_longjmp()\fP:\0\0restore stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" toc@\f4_setjmp()\fP:\0\0save stack environment for non-local goto@@@see \f3setjmp(3C)\f1 .\" .\" links@setjmp.3c longjmp.3c .\" links@setjmp.3c sigsetjmp.3c .\" links@setjmp.3c siglongjmp.3c .\" links@setjmp.3c _longjmp.3c .\" links@setjmp.3c _setjmp.3c .\" .\" fileset_database@setjmp.3c PROGRAMING-MAN .\" $Header: sigsetops.3c,v 72.4 94/11/15 09:56:17 ssa Exp $ .TA s .TH sigsetops 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sigemptyset(\|), sigfillset(\|), sigaddset(\|), sigdelset(\|), sigismember(\|) \- initialize, manipulate, and test signal sets .SH SYNOPSIS .C "#include " .PP .C "int sigemptyset(sigset_t *set);" .PP .C "int sigfillset(sigset_t *set);" .PP .C "int sigaddset(sigset_t *set, int signo);" .PP .C "int sigdelset(sigset_t *set, int signo);" .PP .C "int sigismember(const sigset_t *set, int signo);" .SH DESCRIPTION .C sigemptyset() initializes the signal set pointed to by .I set, to exclude all signals supported by .SM HP-UX. .PP .C sigfillset() initializes the signal set pointed to by .I set, to include all signals supported by .SM HP-UX. .PP Applications must call either .C sigemptyset() or .C sigfillset() at least once for each object of type .C sigset_t before using that object for anything else, including cases where the object is returned from a function (for example, the .I oset argument to .C sigprocmask() \(em see .IR sigprocmask (2)). .PP .C sigaddset() adds the signal specified by .I signo to the signal set pointed to by .IR set . .PP .C sigdelset() deletes the signal specified by .I signo from the signal set pointed to by .I set. .PP .C sigismember() tests whether the signal specified by .I signo is a member of the signal set pointed to by .IR set . .SH RETURN VALUE Upon successful completion, .C sigismember() returns a value of 1 if the specified signal is a member of the specified set, or a value of 0 if it is not. The other functions return a value of 0 upon successful completion. For all of the above functions, if an error is detected, a value of \(mi1 is returned and .C errno is set to indicate the error. .SH ERRORS .CR sigaddset() , .CR sigdelset() , and .C sigismember() fail if the following is true: .RS .TP 15 .SM [EINVAL] The value of the .I signo argument is out of range. The reliable detection of this error is not guaranteed. .RE .SH WARNINGS The above functions do not detect a bad address passed in for the .I set argument. A segmentation fault is the most likely result. .SH AUTHOR .CR sigfillset() , .CR sigemptyset() , .CR sigaddset() , .CR sigdelset() , and .C sigismember() were derived from the .SM .I IEEE .I "Standard POSIX 1003.1-1988" . .SH SEE ALSO sigaction(2), sigsuspend(2), sigpending(2), sigprocmask(2), signal(5). .SH STANDARDS CONFORMANCE .CR sigaddset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigdelset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigemptyset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigfillset() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR sigismember() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4sigemptyset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigfillset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigaddset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigdelset()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@\f4sigismember()\fP \- initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@initialize, manipulate, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@manipulate, initialize, and test signal sets@@@\f3sigsetops(3C)\f1 .\" index@test, initialize, and manipulate signal sets@@@\f3sigsetops(3C)\f1 .\" index@signal sets, initialize, manipulate, and test@@@\f3sigsetops(3C)\f1 .\" toc@\f3sigsetops(3C)\f1:\0\0\f4sigemptyset()\fP, \f4sigfillset()\fP, \f4sigaddset()\fP,\n\f4sigdelset()\fP, \f4sigismember()\fP@@@initialize, manipulate, and test signal sets .\" toc@\f4sigemptyset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigfillset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigaddset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigdelset()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" toc@\f4sigismember()\fP: initialize, manipulate, and test signal sets@@@see \f3sigsetops(3C)\f1 .\" links@sigsetops.3c sigemptyset.3c .\" links@sigsetops.3c sigfillset.3c .\" links@sigsetops.3c sigaddset.3c .\" links@sigsetops.3c sigdelset.3c .\" links@sigsetops.3c sigismember.3c .\" .\" fileset_database@sigsetops.3c PROGRAMING-MAN .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the .\" src directory for the full copyright text. .\" ...\"********************************************************************* ...\" ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, ...\" Maynard, Massachusetts ...\" All Rights Reserved. ...\" ...\" This document is furnished under a license and may be used and ...\" copied only in accordance with the terms of such license and with ...\" the inclusion of the above copyright notice. No title to or ...\" ownership of the document is hereby transferred. ...\" ...\" The information in this document is subject to change without ...\" notice and should not be construed as a commitment by Digital ...\" Equipment Corporation. ...\" ...\" ******************************************************************** ...\" .rm zA .rm zZ .TH sigwait 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\" .iX "\*Lsigwait(\|)\*O" .iX "signal" "waiting for asynchronous" .zA "defect,7282,R1.0.2,routine in code missing from docs" .SH NAME .PP \*Lsigwait\*O - Causes a thread to wait for an asynchronous signal .SH "SYNOPSIS" .sS #\*Linclude .PP \*Lint sigwait( .nL sigset_t *\*Vset\*L); .sE .PP .br .ne 1.5i .SH "PARAMETERS" .PP .VL 3m .LI "\*Vset\*O" Set of pending signals upon which the calling thread will wait. .LE .br .ne 1.5i .SH "DESCRIPTION" .zA "defect,12658,R1.1,revise definition of sigwait" .PP This routine causes a thread to wait for an asynchronous signal. It atomically chooses a pending signal from \*Vset\*O, atomically clears it from the system's set of pending signals and returns that signal number. If no signal in \*Vset\*O is pending at the time of the call, the thread is blocked until one or more signals becomes pending. The signals defined by \*Vset\*O may be unblocked during the call to this routine and will be blocked when the thread returns from the call unless some other thread is currently waiting for one of those signals. .PP A Thread must block the signals it waits for using \*Lsigprocmask\*O() prior to calling this function. .PP If more than one thread is using this routine to wait for the same signal, only one of these threads will return from this routine with the signal number. .PP A call to \*Lsigwati\*O() is a cancellation point. .br .ne 1.5i .SH "RETURN VALUES" .PP Possible return values are as follows: .sp .TS center tab(%); l | l | l n | l | lw(3.0i). \*LReturn%Error%Description\*O _ Signal number%%Successful completion. \-1%[\*LEINVAL\*O]%One or more of the values specified by \*Vset\*O is invalid. \-1%[\*LEINVAL\*O]%One or more of the values specified by \*Vset\*O is not blocked. \-1%[\*LEINVAL\*O]%There are no values specified in \*Vset\*O. .TE .br .ne 1.2i .SH "RELATED INFORMATION" .PP .ad l Functions: \*Lpthread_cancel(3)\*O, \*Lpthread_setasynccancel(3)\*O, \*Lsigsetops(3)\*O, \*Lsigprocmask(3)\*O, \*Lsigpending(3)\*O, \*Lpause(3)\*O, .ad b .zZ "defect,7282,R1.0.2, routine in code missing from docs" .zZ "defect,12658,R1.1,revise definition of sigwait" .\" $Header: sin.3m,v 78.1 96/02/13 13:45:31 ssa Exp $ .TA s .TH sin 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sin(\|), sinf(\|) \- sine functions .SH SYNOPSIS .C "#include " .PP .C "double sin(double x);" .PP .C "float sinf(float x);" .SH DESCRIPTION .CR sin() returns the sine of .IR x .RI ( x specified in radians). .PP .CR sin() may lose accuracy when .IR x is far from zero. .PP .CR sinf() is a .CR float version of .CR sin() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR sinf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .IR x .ift is NaN or \(+-INFINITY, .ifn is NaN or +\-INFINITY, .CR sin() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR sin() returns zero. .SH ERRORS No errors are defined. .SH DEPENDENCIES Millicode versions of the .CR sin() and .CR sinf() functions are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO sind(3M), cos(3M), tan(3M), asin(3M), acos(3M), atan(3M), atan2(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR sin() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4sin()\f1 \- sine function@@@\f3sin(3M)\f1 .\" index@\f4sinf()\f1 \- sine function (float)@@@\f3sin(3M)\f1 .\" index@\f1sine functions@@@\f3sin(3M)\f1 .\" index@\f1math: sine functions@@@\f3sin(3M)\f1 .\" index@\f1trigonometric sine functions@@@\f3sin(3M)\f1 .\" .\" toc@\f3sin(3M)\f1:\0\0\f4sin()\f1, \f4sinf()\fP@@@sine functions .\" toc@\f4sinf()\f1:\0\0sine function (float)@@@see \f3sin(3M)\f1 .\" .\" links@sin.3m sinf.3m .\" .\" fileset_database@sin.3m PROGRAMING-MAN .\" $Header: sind.3m,v 78.1 96/02/13 13:45:56 ssa Exp $ .TA s .TH sind 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sind(\|), sindf(\|) \- degree-valued sine functions .SH SYNOPSIS .C "#include " .PP .C "double sind(double x);" .PP .C "float sindf(float x);" .SH DESCRIPTION .CR sind() is a degree-valued version of the .CR sin() function. It returns the sine of .IR x .RI ( x specified in degrees). .PP .CR sind() may lose accuracy when .IR x is far from zero. .PP .CR sindf() is a .CR float version of .CR sind() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR sind() and .CR sindf() are not specified by any standard, but .CR sindf() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .IR x .ift is NaN or \(+-INFINITY, .ifn is NaN or +\-INFINITY, .CR sind() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR sind() returns zero. .SH ERRORS No errors are defined. .SH SEE ALSO sin(3M), cosd(3M), tand(3M), asind(3M), acosd(3M), atand(3M), atan2d(3M), isinf(3M), isnan(3M), values(5). .\" .\" index@\f4sind()\f1 \- sine function (degrees)@@@\f3sind(3M)\f1 .\" index@\f4sindf()\f1 \- sine function (float, degrees)@@@\f3sind(3M)\f1 .\" index@\f1sine function (degrees)@@@\f3sind(3M)\f1 .\" index@\f1math: sine functions (degrees)@@@\f3sind(3M)\f1 .\" index@\f1degree-valued sine functions@@@\f3sind(3M)\f1 .\" index@\f1trigonometric sine functions (degrees)@@@\f3sind(3M)\f1 .\" .\" toc@\f3sind(3M)\f1:\0\0\f4sind()\f1, \f4sindf()\f1@@@degree-valued sine functions .\" toc@\f4sindf()\f1:\0\0sine function (float, degrees)@@@see \f3sind(3M)\f1 .\" .\" links@sind.3m sindf.3m .\" .\" fileset_database@sind.3m PROGRAMING-MAN .\" $Header: sind.3m,v 78.1 96/02/13 13:45:56 ssa Exp $ .TA s .TH sind 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sind(\|), sindf(\|) \- degree-valued sine functions .SH SYNOPSIS .C "#include " .PP .C "double sind(double x);" .PP .C "float sindf(float x);" .SH DESCRIPTION .CR sind() is a degree-valued version of the .CR sin() function. It returns the sine of .IR x .RI ( x specified in degrees). .PP .CR sind() may lose accuracy when .IR x is far from zero. .PP .CR sindf() is a .CR float version of .CR sind() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR sind() and .CR sindf() are not specified by any standard, but .CR sindf() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .IR x .ift is NaN or \(+-INFINITY, .ifn is NaN or +\-INFINITY, .CR sind() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR sind() returns zero. .SH ERRORS No errors are defined. .SH SEE ALSO sin(3M), cosd(3M), tand(3M), asind(3M), acosd(3M), atand(3M), atan2d(3M), isinf(3M), isnan(3M), values(5). .\" .\" index@\f4sind()\f1 \- sine function (degrees)@@@\f3sind(3M)\f1 .\" index@\f4sindf()\f1 \- sine function (float, degrees)@@@\f3sind(3M)\f1 .\" index@\f1sine function (degrees)@@@\f3sind(3M)\f1 .\" index@\f1math: sine functions (degrees)@@@\f3sind(3M)\f1 .\" index@\f1degree-valued sine functions@@@\f3sind(3M)\f1 .\" index@\f1trigonometric sine functions (degrees)@@@\f3sind(3M)\f1 .\" .\" toc@\f3sind(3M)\f1:\0\0\f4sind()\f1, \f4sindf()\f1@@@degree-valued sine functions .\" toc@\f4sindf()\f1:\0\0sine function (float, degrees)@@@see \f3sind(3M)\f1 .\" .\" links@sind.3m sindf.3m .\" .\" fileset_database@sind.3m PROGRAMING-MAN .\" $Header: sin.3m,v 78.1 96/02/13 13:45:31 ssa Exp $ .TA s .TH sin 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sin(\|), sinf(\|) \- sine functions .SH SYNOPSIS .C "#include " .PP .C "double sin(double x);" .PP .C "float sinf(float x);" .SH DESCRIPTION .CR sin() returns the sine of .IR x .RI ( x specified in radians). .PP .CR sin() may lose accuracy when .IR x is far from zero. .PP .CR sinf() is a .CR float version of .CR sin() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR sinf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .IR x .ift is NaN or \(+-INFINITY, .ifn is NaN or +\-INFINITY, .CR sin() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR sin() returns zero. .SH ERRORS No errors are defined. .SH DEPENDENCIES Millicode versions of the .CR sin() and .CR sinf() functions are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO sind(3M), cos(3M), tan(3M), asin(3M), acos(3M), atan(3M), atan2(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR sin() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4sin()\f1 \- sine function@@@\f3sin(3M)\f1 .\" index@\f4sinf()\f1 \- sine function (float)@@@\f3sin(3M)\f1 .\" index@\f1sine functions@@@\f3sin(3M)\f1 .\" index@\f1math: sine functions@@@\f3sin(3M)\f1 .\" index@\f1trigonometric sine functions@@@\f3sin(3M)\f1 .\" .\" toc@\f3sin(3M)\f1:\0\0\f4sin()\f1, \f4sinf()\fP@@@sine functions .\" toc@\f4sinf()\f1:\0\0sine function (float)@@@see \f3sin(3M)\f1 .\" .\" links@sin.3m sinf.3m .\" .\" fileset_database@sin.3m PROGRAMING-MAN .\" $Header: sinh.3m,v 78.1 96/02/13 13:48:38 ssa Exp $ .TA s .TH sinh 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sinh(\|), sinhf(\|) \- hyperbolic sine functions .SH SYNOPSIS .C "#include " .PP .C "double sinh(double x);" .PP .C "float sinhf(float x);" .SH DESCRIPTION .CR sinh() returns the hyperbolic sine of its argument. .PP .CR sinhf() is a .CR float version of .CR sinh() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR sinhf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE .PP If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR sinh() .ift returns \(+-INFINITY respectively. .ifn returns +\-INFINITY respectively. .PP If .I x is NaN, .CR sinh() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR sinh() returns zero. .PP If the correct value would overflow, .CR sinh() returns .CR HUGE_VAL (it returns .CR \(miHUGE_VAL for negative .IR x ) and sets .CR errno to [ERANGE]. .SH ERRORS If .CR sinh() fails, .CR errno is set to the following value. .RS .TP 20 [ERANGE] The correct value would overflow. .RE .SH SEE ALSO cosh(3M), tanh(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR sinh() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4sinh()\f1, \f4sinhf()\f1 \- hyperbolic sine functions@@@\f3sinh(3M)\f1 .\" index@\f4sinhf()\f1, \f4sinh()\f1 \- hyperbolic sine functions@@@\f3sinh(3M)\f1 .\" index@\f1math: hyperbolic sine functions@@@\f3sinh(3M)\f1 .\" index@\f1hyperbolic sine functions@@@\f3sinh(3M)\f1 .\" index@\f1sine functions, hyperbolic@@@\f3sinh(3M)\f1 .\" .\" toc@\f3sinh(3M)\f1:\0\0\f4sinh()\f1, sinhf()\f1@@@hyperbolic sine functions .\" toc@\f4sinhf()\f1:\0\0hyperbolic sine function (float version)@@@see \f3sinh(3M)\f1 .\" .\" links@sinh.3m sinhf.3m .\" .\" fileset_database@sinh.3m PROGRAMING-MAN .\" $Header: sinh.3m,v 78.1 96/02/13 13:48:38 ssa Exp $ .TA s .TH sinh 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sinh(\|), sinhf(\|) \- hyperbolic sine functions .SH SYNOPSIS .C "#include " .PP .C "double sinh(double x);" .PP .C "float sinhf(float x);" .SH DESCRIPTION .CR sinh() returns the hyperbolic sine of its argument. .PP .CR sinhf() is a .CR float version of .CR sinh() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR sinhf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE .PP If .I x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR sinh() .ift returns \(+-INFINITY respectively. .ifn returns +\-INFINITY respectively. .PP If .I x is NaN, .CR sinh() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR sinh() returns zero. .PP If the correct value would overflow, .CR sinh() returns .CR HUGE_VAL (it returns .CR \(miHUGE_VAL for negative .IR x ) and sets .CR errno to [ERANGE]. .SH ERRORS If .CR sinh() fails, .CR errno is set to the following value. .RS .TP 20 [ERANGE] The correct value would overflow. .RE .SH SEE ALSO cosh(3M), tanh(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR sinh() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4sinh()\f1, \f4sinhf()\f1 \- hyperbolic sine functions@@@\f3sinh(3M)\f1 .\" index@\f4sinhf()\f1, \f4sinh()\f1 \- hyperbolic sine functions@@@\f3sinh(3M)\f1 .\" index@\f1math: hyperbolic sine functions@@@\f3sinh(3M)\f1 .\" index@\f1hyperbolic sine functions@@@\f3sinh(3M)\f1 .\" index@\f1sine functions, hyperbolic@@@\f3sinh(3M)\f1 .\" .\" toc@\f3sinh(3M)\f1:\0\0\f4sinh()\f1, sinhf()\f1@@@hyperbolic sine functions .\" toc@\f4sinhf()\f1:\0\0hyperbolic sine function (float version)@@@see \f3sinh(3M)\f1 .\" .\" links@sinh.3m sinhf.3m .\" .\" fileset_database@sinh.3m PROGRAMING-MAN .\" $Header: sleep.3c,v 72.4 94/11/15 09:56:20 ssa Exp $ .TA s .TH sleep 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sleep(\|) \- suspend execution for interval .SH SYNOPSIS .C "#include " .PP .C "unsigned int sleep(unsigned int seconds);" .SH DESCRIPTION .C sleep() suspends the current process from execution for the number of .I seconds specified by the argument. .PP Actual suspension time can be less than that requested for two reasons: .RS .TP 3 \(bu Scheduled wakeups occur at fixed 1-second intervals (on the second, according to an internal clock), and .TP \(bu Any caught signal terminates the .I sleep following execution of that signal's catching routine. .RE .PP Suspension time can be an arbitrary amount longer than requested due to the scheduling of other activity in the system. The value returned by .C sleep() is the ``unslept'' amount (the requested time minus the time actually slept) in case the caller had an alarm set to go off earlier than the end of the requested .C sleep() time, or premature arousal due to another caught signal. .PP .C sleep() is implemented by setting an alarm signal and pausing until it (or some other signal) occurs. The previous state of the alarm signal is saved and restored. The calling program may have set up an alarm signal before calling .CR sleep() . If the .C sleep() time exceeds the time until such an alarm signal, the process sleeps only until the alarm signal would have occurred. The caller's alarm catch routine is executed just before the .C sleep() routine returns. If the .C sleep() time is less than the time till such alarm, the prior alarm time is reset to go off at the same time it would have without the intervening .CR sleep() . .PP .I seconds must be less than .if n 2^32. .if t 2\u\s-232\s+2\d. .SH SEE ALSO alarm(2), pause(2), signal(5). .SH STANDARDS CONFORMANCE .CR sleep() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4sleep()\fP \- suspend execution for interval@@@\f3sleep(3C)\f1 .\" index@execution, suspend for interval@@@\f3sleep(3C)\f1 .\" index@suspend execution for interval@@@\f3sleep(3C)\f1 .\" index@interval, suspend execution for@@@\f3sleep(3C)\f1 .\" .\" toc@\f3sleep(3C)\f1:\0\0\f4sleep()\fP@@@suspend execution for interval .\" .\" fileset_database@sleep.3c PROGRAMING-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: slk_attroff.3x,v 76.2 95/08/01 14:46:19 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH slk_attroff 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set, slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh, slk_restore, slk_set, slk_touch, slk_wset \(em soft label functions .SH SYNOPSIS .C "#include " .P .C "int slk_attroff(const chtype \f2attrs\fP);" .P .C "int slk_attr_off(const attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int slk_attron(const chtype \f2attrs\fP);" .P .C "int slk_attr_on(const attr_t \f2attrs\fP, void *\f2opts\f);" .P .C "int slk_attrset(const chtype \f2attrs\fP);" .P .C "int slk_attr_set(const attr_t \f2attrs\fP, short \f2color_pair\f, void *\f2opts\f);" .P .C "int slk_clear(void);" .P .C "int slk_color(short \f2color_pair\fP);" .P .C "int slk_init(int \f2fmt\fP);" .P .C "char *slk_label(int \f2labnum\fP);" .P .C "int slk_noutrefresh(void);" .P .C "int slk_refresh(void);" .P .C "int slk_restore(void);" .P .C "int slk_set(int \f2labnum\fP, char *const \f2label\fP, int \f2justify\fP);" .P .C "int slk_touch(void);" .P .C "int slk_wset(int \f2labnum\fP, wchar_t *const \f2label\fP, int \f2justify\fP);" .SH DESCRIPTION The Curses interface manipulates the set of soft function-key labels that exist on many terminals. For those terminals that do not have soft labels, Curses takes over the bottom line of .I stdscr , reducing the size of .I stdscr and the value of the .B LINES external variable. There can be up to eight labels of up to eight display columns each. .P To use soft labels, .Fn slk_init must be called before .CR initscr() , .Fn newterm or .Fn ripoffline is called. If .Fn initscr eventually uses a line from .I stdscr to emulate the soft labels, then \f2fmt\f1 determines how the labels are arranged on the screen. Setting \f2fmt\f1 to 0 indicates a 3-2-3 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for \f2fmt\f1 are unspecified. .P The .Fn slk_init function has the effect of calling .Fn ripoffline to reserve one screen line to accommodate the requested format. .P The .Fn slk_set and .Fn slk_wset functions specify the text of soft label number \f2labnum\f1, within the range from 1 to and including 8. The \f2label\f1 argument is the string to be put on the label. With .CR slk_set() , and .CR slk_wset() , the width of the label is limited to eight column positions. A null string or a null pointer specifies a blank label. The \f2justify\f1 argument can have the following values to indicate how to justify \f2label\f1 within the space reserved for it: .RS .TP 10 .C 0 Align the start of \f2label\f1 with the start of the space .TP .C 1 Center \f2label\f1 within the space .TP .C 2 Align the end of \f2label\f1 with the end of the space .RE .P The .Fn slk_refresh and .Fn slk_noutrefresh functions correspond to the .Fn wrefresh and .Fn wnoutrefresh functions. .P The .Fn slk_label function obtains soft label number \f2labnum\f1. .P The .Fn slk_clear function immediately clears the soft labels from the screen. .P The .Fn slk_restore function immediately restores the soft labels to the screen after a call to .CR slk_clear() . .P The .Fn slk_touch function forces all the soft labels to be output the next time .Fn slk_noutrefresh or .Fn slk_refresh is called. .P The .CR slk_attron() , .Fn slk_attrset and .Fn slk_attroff functions correspond to .CR attron() , .CR attrset() , and .CR attroff() . They have an effect only if soft labels are simulated on the bottom line of the screen. .P The .CR slk_attr_off() , .CR slk_attr_on() , .Fn slk_attr_set and .Fn slk_color functions correspond to .CR attr_off() , .CR attr_on() , .Fn attr_set and and .CR color_set() , respectively and thus support the attribute constants with the WA_ prefix and color. .SH "RETURN VALUE" Upon successful completion, .Fn slk_label returns the requested label with leading and trailing blanks stripped. Otherwise, it returns a null pointer. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" When using multi-byte character sets, applications should check the width of the string by calling .Fn mbstowcs and then .Fn wcswidth before calling .CR slk_set() . When using wide characters, applications should check the width of the string by calling .Fn wcswidth before calling .CR slk_set() . .P Since the number of columns that a wide character string will occupy is codeset-specific, call .Fn wcwidth and .Fn wcswidth to check the number of column positions in the string before calling .CR slk_wset() . .P Most applications would use .Fn slk_noutrefresh because a .Fn wrefresh is likely to follow soon. .SH "SEE ALSO" attr_get(), attroff(), delscreen(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), ripoffline(), wcswidth() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3slk_attroff(3X)\f1:\0\0\f4slk_attroff()\f1, \f4slk_attr_off()\f1, \f4slk_attron()\f1, \f4slk_attr_on()\f1, \f4slk_attrset()\f1, \n\f4slk_attr_set()\f1, \f4slk_clear()\f1, \f4slk_color()\f1, \f4slk_init()\f1, \f4slk_label()\f1, \n\f4slk_noutrefresh()\f1, \f4slk_refresh()\f1, \f4slk_restore()\f1, \f4slk_set()\f1, \f4slk_touch()\f1, \f4slk_wset()\f1\n@@@soft label functions .\" toc@\f4slk_attr_off()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attron()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_on()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attrset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_attr_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_clear()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_color()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_init()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_label()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_noutrefresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_refresh()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_restore()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_set()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_touch()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" toc@\f4slk_wset()\f1: soft label functions@@@see \f3slk_attroff(3X)\f1 .\" .\" index@\f4slk_attroff()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_off()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attron()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_on()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attrset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_attr_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_clear()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_color()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_init()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_label()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_noutrefresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_refresh()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_restore()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_set()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_touch()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f4slk_wset()\f1 \- soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1soft label functions@@@\f3slk_attroff(3X)\f1 .\" index@\f1functions, soft label@@@\f3slk_attroff(3X)\f1 .\" index@\f1label, soft, functions@@@\f3slk_attroff(3X)\f1 .\" .\" links@slk_attroff.3x slk_attr_off.3x .\" links@slk_attroff.3x slk_attron.3x .\" links@slk_attroff.3x slk_attr_on.3x .\" links@slk_attroff.3x slk_attrset.3x .\" links@slk_attroff.3x slk_attr_set.3x .\" links@slk_attroff.3x slk_clear.3x .\" links@slk_attroff.3x slk_color.3x .\" links@slk_attroff.3x slk_init.3x .\" links@slk_attroff.3x slk_label.3x .\" links@slk_attroff.3x slk_noutrefresh.3x .\" links@slk_attroff.3x slk_refresh.3x .\" links@slk_attroff.3x slk_restore.3x .\" links@slk_attroff.3x slk_set.3x .\" links@slk_attroff.3x slk_touch.3x .\" links@slk_attroff.3x slk_wset.3x .\" .\" fileset_database@slk_attroff.3x CURS-ENG-A-MAN .\" $Header: spray.3n,v 72.4 94/08/09 12:16:35 ssa Exp $ .TA s .TH spray 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME spray \- scatter data in order to check the network .SH SYNOPSIS .C #include .br .C #include .SH DESCRIPTION This reference page describes the data structures and XDR routines used by the .IR spray (1M) program. A .C spray() function call does not exist. Refer to .IR spray (1M) for more information. .SS RPC Information .nf program number: SPRAYPROG .PP xdr routines: xdr_sprayarr(xdrs, arr); XDR *xdrs; struct sprayarr *arr; xdr_spraycumul(xdrs, cumul); XDR *xdrs; struct spraycumul *cumul; procedures: SPRAYPROC_SPRAY Takes no arguments, returns no value. Increments a counter in server daemon. The server does not return this call, so the caller should have a timeout of 0. The sprayarr is only used by the caller, to vary the size of the UDP packets sent. SPRAYPROC_GET Takes no arguments, returns \f2struct spraycumul\fP with the values of counter and clock set to reflect the number of SPRAYPROC_SPRAY calls, and the total time (seconds and microseconds) elapsed since the last SPRAYPROC_CLEAR request. SPRAYPROC_CLEAR Takes no arguments and returns no value. Zeros out counter and clock in preparation for calls to SPRAYPROC_SPRAY. versions: SPRAYVERS_ORIG .PP structures: struct spraycumul { unsigned counter; struct timeval clock; }; struct sprayarr { int *data; int lnth; }; .fi .SH WARNING User applications that call this routine must be linked with .CR /usr/include/librpcsvc.a . For example, .IP .C cc my_source.c -lrpcsvc .SH AUTHOR .C spray was developed by Sun Microsystems, Inc. .SH SEE ALSO spray(1M), sprayd(1M). .\" index@\f4spray\fP: scatter data to check the network@@@\f3spray(3N)\f1 .\" index@scatter data to check the network@@@\f3spray(3N)\f1 .\" index@data to check the network, scatter@@@\f3spray(3N)\f1 .\" index@check the network, scatter data to@@@\f3spray(3N)\f1 .\" index@network, scatter data to check the@@@\f3spray(3N)\f1 .\" toc@\f3spray(3N)\f1: \f4spray\fP@@@scatter data for network checking .\" .\" fileset_database@spray.3n PROGRAMING-MAN .\" $Header: printf.3s,v 72.8 94/11/30 15:46:16 ssa Exp $ .TA p .TH printf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME printf(), fprintf(), sprintf() \- print formatted output .SH SYNOPSIS .C "#include " .PP .C "int printf(const char *format, /* [arg,] */ ...);" .PP .C "int fprintf(FILE *stream, const char *format, /* [arg,] */ ...);" .PP .C "int sprintf(char *s, const char *format, /* [arg,] */ ...);" .SH DESCRIPTION .CR printf() places output on the standard output stream .IR stdout . .PP .CR fprintf() places output on the named output .IR stream . .PP .CR sprintf() places ``output'', followed by the null character .RC ( \e0 ), in consecutive bytes starting at .CI * s \f1. It is the user's responsibility to ensure that enough storage is available. .PP Each function converts, formats, and prints its .IR arg s under control of the .IR format . .I format is a character string containing two types of objects: plain characters that are copied to the output stream, and conversion specifications, each of which results in fetching zero or more .IR arg s. The results are undefined if there are insufficient .IR arg s for the format. If the format is exhausted while .IR arg s remain, excess .IR arg s are ignored. .PP Each conversion specification is introduced by the character .CR % or .CI % n $\f1, where .I n is a decimal integer in the range 1 through .C {NL_ARGMAX} .RC ( NL_ARGMAX is defined in .CR ). The .CI % n $ construction indicates that this conversion should be applied to the .IR n th argument, rather than to the next unused one. .PP An argument can be referenced by a .CI % n $ specification more than once. The two forms of introducing a conversion specification, .CR % and .CI % n $\f1, cannot be mixed within a single .I format string. When numbered argument specifications are used, specifying the Nth argument requires that all the leading arguments, from the first to the (N-1)th, are specified in the format string. Improper use of .CI % n $ in a format string results in a negative return value. .PP After the .CR % or .CI % n $\f1, the following appear in sequence: .RS .TP 5 1. Zero or more .IR flags , which modify the meaning of the conversion specification. .TP 2. An optional string of decimal digits to specify a minimum .I field width in bytes. If the converted value has fewer characters than the field width, it is be padded on the left (or right, if the left-adjustment flag .RC ( - ), described below, has been given) to the field width. If the field width is preceded by a zero, the string is right adjusted with zero-padding on the left (see the leading-zero flag, .CR 0 , described below). .TP 3. A .I precision that gives the minimum number of digits to appear for the .CR d , .CR i , .CR o , .CR u , .CR x , or .CR X conversions, the number of digits to appear after the radix character for the .CR e and .CR f conversions, the maximum number of significant digits for the .CR g conversion, or the maximum number of bytes to be printed from a string in the .CR s conversion. The .I precision takes the form of a period followed by a decimal digit string; a null digit string is treated as zero. .TP 4. An optional .CR l (the letter ``ell''), specifying that a following .CR d , .CR i , .CR o , .CR u , .CR x , or .CR X conversion character applies to a long integer .IR arg ; an optional .CR l specifying that a following .CR n conversion character applies to a pointer to a long integer .IR arg ; an optional .CR h , specifying that a following .CR d , .CR i , .CR o , .CR u , .CR x , or .CR X conversion character applies to a short integer .IR arg ; an optional .CR ll , specifying that a following .CR d , .CR i , .CR o , .CR u , .CR x , or .CR X conversion character applies to a long long integer arg; an optional .CR h specifying that a following .CR n conversion character applies to a pointer to a short integer .IR arg ; an optional .C L specifying that a following .CR e , .CR E , .CR f , .CR g , or .CR G conversion character applies to a long double .IR arg . An .CR l , .CR h , .CR ll or .CR L before any other conversion character is ignored. .TP 5. A conversion character that indicates the type of conversion to be applied. .RE .ift .ne 10 .PP A field width or precision can be indicated by an asterisk instead of a digit string. In this case, an integer .I arg supplies the field width or precision. The .I arg that is actually converted is not fetched until the conversion letter is seen, so the .IR arg s specifying field width, or precision, or both must appear in that order before the .IR arg , if any, to be converted. A negative field width is taken as a .CR - flag followed by a positive field width. A negative precision is taken as if the precision were omitted. Format strings containing .CI % n $ conversion specifications can also indicate a field width or precision by the sequence .CI * n $\f1. The .I n indicates the position of an integer .I arg . With the .CI * n $ sequence, the .IR arg s specifying field width or precision can appear before or after the .I arg to be converted. .PP The flag characters and their meanings are: .RS .TP 10 .C ' The integer portion of the result of a decimal conversion (%i, %d, %u, %f, %g, or %G) will be formatted with thousands' grouping characters. For other conversions the behavior is undefined. The nonmonetary grouping character is used. .TP .C - The resulting conversion is left-justified within the field. .TP .C + The resulting signed conversion always begins with a sign .RC ( + or .CR - ). .TP blank If the first character of a signed conversion is not a sign, a blank is prefixed to the result. This implies that if the blank and .CR + flags both appear, the blank flag is ignored. .TP .C # This flag specifies that the value is converted to an .IR `` alternate form ''. For .CR c , .CR d , .CR i , .CR s , .CR n , and .CR u conversions, the flag has no effect. For .CR o conversion, it increases the precision to force the first digit of the result to be a zero. For .CR x or .CR X conversion, a nonzero result is prefixed by .CR 0x or .CR 0X . For a .CR p conversion, a nonzero result is prefixed by .CR 0x . For .CR e , .CR E , .CR f , .CR g , and .CR G conversions, the result always contains a radix character, even if no digits follow the radix. (Normally, a radix character appears in the resulting conversions only if followed by a digit). For .CR g and .CR G conversions, trailing zeros are .I not removed from the result (which they normally are). .TP .C 0 Leading zeros (following any indication of sign or base) are used to pad to the field width for all conversion characters. No space padding is performed. If both the .CR 0 and .CR - appear, the .CR 0 flag is ignored. For .CR d , .CR i , .CR o , .CR u , .CR p , .CR x , and .CR X , conversions, if a precision is specified, the .CR 0 flag is ignored. .RE .PP The conversion characters and their meanings are: .RS .TP 15 .ift \f4\s+1d\fP\s0,\f4\s+1i\fP\s0,\f4\s+1o\fP\s0,\f4\s+1u\fP\s0,\f4\s+1x\fP\s0,\f4\s+1X\fP\s0 .ifn \f3d\fP,\f3i\fP,\f3o\fP,\f3u\fP,\f3x\fP,\f3X\fP The integer .I arg is converted to signed decimal .RC ( d and .CR i are identical), unsigned octal .RC ( o ), decimal .RC ( u ), or hexadecimal notation .RC ( x and .CR X ), respectively; the letters .CR abcdef are used for .CR x conversion and the letters .CR ABCDEF for .CR X conversion. The precision specifies the minimum number of digits to appear. If the value being converted can be represented in fewer digits, it is expanded with leading zeros. (For compatibility with older versions, padding with leading zeros can alternatively be specified by inserting a zero in front of the field width. This does not imply an octal value for the field width). The default precision is 1. The result of converting a zero value with a precision of zero is a null string. .TP .C f The double .I arg is converted to decimal notation in the style .RC [ - ]\c .CI ddd r ddd , where .I r is the radix character. The number of digits after the radix character is equal to the precision specification. If the precision is missing, six digits are output. If the precision is explicitly zero, no radix character appears. .TP .CR e , E The double .I arg is converted in the style .RC [ - ]\c .CI d r ddde\(+-ddd , where .CR r is the radix character. There is one digit before the radix character and the number of digits after it is equal to the precision; when the precision is missing, six digits are produced; if the precision is zero, no radix character appears. The .CR E format code produces a number with .CR E instead of .CR e introducing the exponent. The exponent always contains at least two digits. .TP .CR g , G The double .I arg is printed in style .CR f or .CR e (or in style .CR E in the case of a .CR G format code), with the precision specifying the number of significant digits. The style used depends on the value converted: style .CR e is used only if the exponent resulting from the conversion is less than .CR \-4 or greater than or equal to the precision. Trailing zeros are removed from the fractional part of the result; a radix character appears only if it is followed by a digit. .TP .C c The integer .I arg is converted to an unsigned char, and the resulting character is printed. .TP .C C The .CR wchar_t .I arg is converted to an array of bytes representing the single wide character according to the setting of .CR LC_CTYPE . Resulting bytes are printed. If the precision is given, it is ignored. If the field width would otherwise cause the wide character to be split, the wide character is printed and the field width is adjusted upward. .TP .C s The .I arg is taken to be a string (character pointer) and characters from the string are printed until a null character .RC ( \e0 ) is encountered or the number of bytes indicated by the precision specification is reached. If the precision is missing, it is taken to be infinite, so all characters up to the first null character are printed. A NULL value for .I arg yields undefined results. .TP .C S The .I arg is taken to be a pointer to a wide character string .RC ( "wchar_t *" ). Wide characters from the string are converted to an array of bytes representing the string of wide characters according to the setting of .CR LC_CTYPE . Resulting bytes are printed until a null wide character .RC ( (wchar_t)0 ) is encountered or the number of bytes indicated by the precision is reached. If the precision is missing, it is taken to be infinite, so all wide characters up to the first null wide character are printed. If the field width would otherwise cause the last multibyte character to be split, the last wide character is not printed. A NULL value for .I arg yields undefined results. .TP .C p The value of a pointer to void .I arg is printed as a sequence of unsigned hexadecimal numbers. The precision specifies the minimum number of digits to appear. If the value being converted can be represented in fewer digits, it is expanded with leading zeros. The default precision is 1. The result of converting a zero value with a precision of zero is a null string. .TP .C n A pointer to an integer .I arg is expected. This pointer is used to store the number of bytes printed on the output stream so far by this call to the function. No argument is converted. .TP .C % Print a .CR % ; no argument is converted. .RE .PP In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result. .PP Characters generated by .CR printf() , and .CR fprintf() are printed as if .CR putc() had been called (see .IR putc (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category affects the following features: .RS .TP 3 \(bu Plain characters within format strings are interpreted as single byte and/or multibyte characters. .TP \(bu Field width is given in terms of bytes. As characters are placed on the output stream, they are interpreted as single byte or multibyte characters and the field width is decremented by the length of the character. .TP \(bu Precision is given in terms of bytes. As characters are placed on the output stream, they are interpreted as single byte or multibyte characters and the precision is decremented by the length of the character. .TP \(bu The return value is given in terms of bytes. As characters are placed on the output stream, they are interpreted as single byte or multibyte characters and the byte count that makes up the return value is incremented by the length of the character. .RE .PP The .CR LC_NUMERIC category determines the radix character used to print floating-point numbers, and the thousands' grouping characters if the grouping flag .CR ' is on. .SS International Code Set Support Single byte character code sets are supported. Multibyte character code sets are also supported as described in the .CR LC_CTYPE category above. .SH RETURN VALUE Each function returns the number of bytes transmitted (excluding the .CR \e0 in the case of .CR sprintf() or a negative value if an output error was encountered. Improper use of .CI % n $ in a format string results in a negative return value. .SH ERRORS .CR printf() , and .CR fprintf() fail if either the .I stream is unbuffered or .IR stream 's buffer needed to be flushed causing an underlying .CR write() call to be invoked (see .IR write (2)), and: .RS .TP 15 [EAGAIN] The .CR O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the write operation. .TP [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for writing. .TP [EFBIG] An attempt was made to write to a file that exceeds the process's file size limit or the maximum file size (see .IR ulimit (2)). .TP [EINTR] A signal was caught during the .CR write() system call. .TP [EIO] The process is in a background process group and is attempting to write to its controlling terminal, .CR TOSTOP is set, the process is neither ignoring nor blocking the .CR SIGTTOU signal, and the process group of the process is orphaned. .TP [ENOSPC] There was no free space remaining on the device containing the file. .TP [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A .CR SIGPIPE signal is also sent to the process. .RE .PP Additional .CR errno values can be set by the underlying .CR write() function (see .IR write(2)). .SH EXAMPLES To print a date and time in the form "Sunday, July 3, 10:02", where .I weekday and .I month are pointers to null-terminated strings: .RS .nh .PP .ift\f4\s+1printf("%s,\ %s\ %d,\ %d:%.2d",\ weekday,\ month,\ day,\ hour,\ min);\fP\s0 .ifn\f3printf("%s,\ %s\ %d,\ %d:%.2d",\ weekday,\ month,\ day,\ hour,\ min);\fP .RE .PP To print .if n .I pi .if t \(*p to 5 decimal places: .RS .PP .ift \f4\s+1printf("pi \|= \|%.5f", \|4 \(** atan(1\f3.\fP0));\fP\s0 .ifn \f3printf("pi \|= \|%.5f", \|4 \(** atan(1\f3.\fP0));\fP .RE .PP To create a language independent date-and-time printing routine write: .RS .PP .ift \f4\s+1printf(format,weekday,month,day,hour,min,2,2);\fP\s0 .ifn \f3printf(format,weekday,month,day,hour,min,2,2);\fP .RE .PP For American usage, .IR format would point to the string: .IP .ift \f4\s+1"%1$s, %2$s %3$d, %4$*6$.*7$d:%5$*6$.*7$d"\fP\s0 .ifn \f3"%1$s, %2$s %3$d, %4$*6$.*7$d:%5$*6$.*7$d"\fP .PP and result in the output: .IP .ift \f4\s+1"Sunday, July 3, 10:02"\fP\s0 .ifn \f4"Sunday, July 3, 10:02"\fP .PP For German usage, the string: .IP .ift \f4\s+1"%1$s, %3$s %2$d, %4$*6$.*7$d:%5$*6$.*7$d"\fP\s0 .ifn \f3"%1$s, %3$s %2$d, %4$*6$.*7$d:%5$*6$.*7$d"\fP .PP results in the output: .IP .C "Sonntag, 3 Juli 10:02" .SH WARNINGS Notice that with the .CR c conversion character, an int .I arg is converted to an unsigned char. Hence, whole multibyte characters cannot be printed using a single .CR c conversion character. .PP A precision with the .CR s conversion character might result in the truncation of a multibyte character. .SH AUTHOR .CR printf() , .CR fprintf() , and .CR sprintf() were developed by AT&T and HP. .SH SEE ALSO ecvt(3C), ltostr(3C), setlocale(3C), putc(3S), scanf(3S), stdio(3S). .SH STANDARDS CONFORMANCE .CR printf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR sprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4printf()\f1 \- print formatted output to standard output@@@\f3printf(3S)\f1 .\" index@\f4fprintf()\f1 \- print formatted output to a file@@@\f3printf(3S)\f1 .\" index@\f4sprintf()\f1 \- print formatted output to a string@@@\f3printf(3S)\f1 .\" index@\f1print formatted output to standard output, file, or string@@@\f3printf(3S)\f1 .\" index@\f1formatted output, print to standard output, file, or string@@@\f3printf(3S)\f1 .\" index@\f1output, formatted, print to standard output, file, or string@@@\f3printf(3S)\f1 .\" .\" toc@\f3printf(3S)\f1:\0\0\f4printf()\f1, \f4fprintf()\f1, \f4sprintf()\f1@@@print formatted output .\" toc@\f4fprintf()\f1:\0\0print formatted output to a file@@@\f1see \f3printf(3S)\f1 .\" toc@\f4sprintf()\f1:\0\0print formatted output to a string@@@\f1see \f3printf(3S)\f1 .\" .\" links@printf.3s fprintf.3s .\" links@printf.3s sprintf.3s .\" $Header: sqrt.3m,v 78.1 96/02/13 13:49:28 ssa Exp $ .TA s .TH sqrt 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sqrt(\|), sqrtf(\|) \- square root functions .SH SYNOPSIS .C "#include " .PP .C "double sqrt(double x);" .PP .C "float sqrtf(float x);" .SH DESCRIPTION .CR sqrt() returns the non-negative square root of .IR x . The value of .IR x must not be negative. .PP .CR sqrtf() is a .CR float version of .CR sqrt() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR sqrtf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .IR x is +INFINITY, .CR sqrt() returns +INFINITY. .PP If .IR x is NaN, .CR sqrt() returns NaN. .PP If .IR x is negative, .CR sqrt() returns NaN and sets .CR errno to [EDOM]. .SH ERRORS If .CR sqrt() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] .IR x is negative. .RE .SH SEE ALSO exp(3M), log(3M), pow(3M), cbrt(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR sqrt() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4sqrt()\f1 \f4sqrtf()\f1 \- square root functions@@@\f3sqrt(3M)\f1 .\" index@\f4sqrtf()\f1, \f4sqrt()\f1 \- square root functions@@@\f3sqrt(3M)\f1 .\" index@\f1math: square root functions@@@\f3sqrt(3M)\f1 .\" index@\f1square root functions@@@\f3sqrt(3M)\f1 .\" .\" toc@\f3sqrt(3M)\f1:\0\0\f4sqrt()\f1, \f4sqrtf()\f1@@@square root functions .\" toc@\f4sqrtf()\f1:\0\0square root function (float version)@@@see \f3sqrt(3M)\f1 .\" .\" links@sqrt.3m sqrtf.3m .\" .\" fileset_database@sqrt.3m PROGRAMING-MAN .\" $Header: sqrt.3m,v 78.1 96/02/13 13:49:28 ssa Exp $ .TA s .TH sqrt 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME sqrt(\|), sqrtf(\|) \- square root functions .SH SYNOPSIS .C "#include " .PP .C "double sqrt(double x);" .PP .C "float sqrtf(float x);" .SH DESCRIPTION .CR sqrt() returns the non-negative square root of .IR x . The value of .IR x must not be negative. .PP .CR sqrtf() is a .CR float version of .CR sqrt() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR sqrtf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .IR x is +INFINITY, .CR sqrt() returns +INFINITY. .PP If .IR x is NaN, .CR sqrt() returns NaN. .PP If .IR x is negative, .CR sqrt() returns NaN and sets .CR errno to [EDOM]. .SH ERRORS If .CR sqrt() fails, .CR errno is set to the following value. .RS .TP 20 [EDOM] .IR x is negative. .RE .SH SEE ALSO exp(3M), log(3M), pow(3M), cbrt(3M), isinf(3M), isnan(3M). .SH STANDARDS CONFORMANCE .CR sqrt() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4sqrt()\f1 \f4sqrtf()\f1 \- square root functions@@@\f3sqrt(3M)\f1 .\" index@\f4sqrtf()\f1, \f4sqrt()\f1 \- square root functions@@@\f3sqrt(3M)\f1 .\" index@\f1math: square root functions@@@\f3sqrt(3M)\f1 .\" index@\f1square root functions@@@\f3sqrt(3M)\f1 .\" .\" toc@\f3sqrt(3M)\f1:\0\0\f4sqrt()\f1, \f4sqrtf()\f1@@@square root functions .\" toc@\f4sqrtf()\f1:\0\0square root function (float version)@@@see \f3sqrt(3M)\f1 .\" .\" links@sqrt.3m sqrtf.3m .\" .\" fileset_database@sqrt.3m PROGRAMING-MAN .\" $Header: rand.3c,v 76.1 95/07/05 17:45:31 ssa Exp $ .TA r .TH rand 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME rand(\|), rand_r(\|), srand(\|) \- simple random-number generator .SH SYNOPSIS .C "#include " .PP .C "int rand(void);" .PP .C "int rand_r(unsigned int *seed, int *randval);" .PP .C "void srand(unsigned int seed);" .SH DESCRIPTION .CR rand() uses a multiplicative, congruential, random-number generator with period .if t 2\u\s-232\s0\d .if n 2^32 that returns successive pseudo-random numbers in the range from 0 to .if t 2\u\s-215\s0\d\-1. .if n 2^15-1. .PP .CR srand() can be called at any time to reset the random-number generator to a random starting point. The generator is initially seeded with a value of 1. .SS Reentrant Interfaces .CR rand_r() returns a random number at the address pointed to by the .I randval parameter. The .I seed parameter can be set at any time to start the random-number generator at an arbitrary point. Note that .B rand() is a thread-safe function. The .CR rand_r() interface has been provided to allow multiple threads to generate the same sequence of random numbers concurrently. .SH RETURN VALUE If .IR seed " or " randval is .SM NULL, .CR rand_r() returns -1 and sets .CR errno to .SM EINVAL. Otherwise, .CR rand_r() returns 0. .SH EXAMPLE The following: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int x, y; .PP srand(10); x = rand(); y = rand(); .ft .ps .fi .RE .PP would produce the same results as: .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int x, y, s = 10; .PP rand_r(&s, &x); rand_r(&s, &y); .ft .ps .fi .RE .SH NOTE The spectral properties of .CR rand() leave a great deal to be desired. .CR drand48() provides a much better, though more elaborate, random-number generator (see .IR drand48 (3C)). .SH WARNINGS Users of .CR rand_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH SEE ALSO drand48(3C), random(3M). .SH STANDARDS CONFORMANCE .CR rand() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR srand() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4rand()\fP \- generate successive random numbers@@@\f3rand(3C)\f1 .\" index@\f4srand()\fP \- reset random-number generator to random starting point@@@\f3rand(3C)\f1 .\" index@random-number generator, simple@@@\f3rand(3C)\f1 .\" index@generator, simple random-number@@@\f3rand(3C)\f1 .\" .\" toc@\f3rand(3C)\f1:\0\0\f4rand()\fP, \f4srand()\fP@@@simple random-number generator .\" toc@\f4srand()\fP:\0\0simple random-number generator@@@see \f3rand(3C)\f1 .\" .\" links@rand.3c rand_r.3c .\" links@rand.3c srand.3c .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: drand48.3c,v 78.1 96/01/09 13:53:12 ssa Exp $ .TA d .TH drand48 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME drand48(\|), drand48_r(\|), erand48(\|), erand48_r(\|), lrand48(\|), lrand48_r(\|), nrand48(\|), nrand48_r(\|), mrand48(\|), mrand48_r(\|), jrand48(\|), jrand48_r(\|), srand48(\|), srand48_r(\|), seed48(\|), seed48_r(\|), lcong48(\|), lcong48_r(\|) \- generate uniformly distributed pseudo-random numbers .SH SYNOPSIS .C "#include " .HP .C "double drand48(void);" .HP .C "int drand48_r(struct drand48_data *dp, double *randval);" .sp .HP .C "double erand48(unsigned short int xsubi[3]);" .HP .C "int erand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "double *randval);" .fi .sp .HP .C "long int lrand48(void);" .HP .C "int lrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int nrand48(unsigned short int xsubi[3]);" .HP .C "int nrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .fi .sp .HP .C "long int mrand48(void);" .HP .C "int mrand48_r(struct drand48_data *dp, long int *randval);" .sp .HP .C "long int jrand48(unsigned short int xsubi[3]);" .HP .C "int jrand48_r(" .nf .C "unsigned short int xsubi[3]," .C "struct drand48_data *dp," .C "long int *randval);" .sp .HP .C "void srand48(long int seedval);" .HP .C "int srand48_r(long int seedval, struct drand48_data *dp);" .sp .HP .C "unsigned short int *seed48(unsigned short int seed16v[3]);" .HP .C "int seed48_r(unsigned short int seed16v[3], struct drand48_data *dp);" .sp .HP .C "void lcong48(unsigned short int param[7]);" .HP .C "int lcong48_r(unsigned short int param[7], struct drand48_data *dp);" .SH DESCRIPTION This family of functions generates pseudo-random numbers using the well-known linear congruential algorithm and 48-bit integer arithmetic. .PP In the following description, the formal mathematical notation .RI [ low , high ) indicates an interval including .I low but not including .IR high . .PP .CR drand48() and .CR erand48() return nonnegative double-precision floating-point values uniformly distributed over the interval [0.0,1.0). .PP .CR lrand48() and .CR nrand48() return nonnegative long integers uniformly distributed over the interval [0,2^31). .PP .CR mrand48() and .CR jrand48() return signed long integers uniformly distributed over the interval [\(mi2^31,2^31). .PP .CR srand48() , .CR seed48() , and .CR lcong48() are initialization entry points, one of which should be invoked before either .CR drand48() , .CR lrand48() , or .CR mrand48() is called. (Although it is not recommended practice, constant default initializer values are supplied automatically if .CR drand48() , .CR lrand48() , or .CR mrand48() is called without a prior call to an initialization entry point.) .CR erand48() , .CR nrand48() , and .CR jrand48() do not require an initialization entry point to be called first. .PP All the routines work by generating a sequence of 48-bit integer values, .IR X [ i ], according to the linear congruential formula .IP \f2X\f1\^[\f2n\f1+1]\0=\0(\f2a\f1*\f2X\f1\^[\f2n\f1] + \f2c\f1) modulo \f2m\f1 \f2n\f1>=0 .PP The parameter .IR m " = 2^48;" hence 48-bit integer arithmetic is performed. .PP Unless .CR lcong48() has been invoked, the default multiplier value .I a and the default addend value .I c are given by .RS .PP .IR a " = 0x5DEECE66D (base 16) = 0273673163155 (base 8)" .br .IR c " = 0xB (base 16) = 013 (base 8)" .RE .PP The value returned by any of the functions .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , or .CR jrand48() is computed by first generating the next 48-bit .IR X [ i ] in the sequence. Then the appropriate number of bits, according to the type of data item to be returned, are copied from the high-order (leftmost) bits of .IR X [ i ] and transformed into the returned value. .PP The functions .CR drand48() , .CR lrand48() , and .CR mrand48() store the last 48-bit .IR X [ i ] generated in an internal buffer; that is why they must be initialized prior to being invoked. The functions .CR erand48() , .CR nrand48() , and .CR jrand48() require the calling program to provide storage for the successive .IR X [ i ] values in the array specified as an argument when the functions are invoked. That is why these routines do not have to be initialized; the calling program merely has to place the desired initial value of .IR X [ i ] into the array and pass it as an argument. By using different arguments, .CR erand48() , .CR nrand48() , and .CR jrand48() allow separate modules of a large program to generate several .I independent streams of pseudo-random numbers; i.e., the sequence of numbers in each stream do .I not depend upon how many times the routines have been called to generate numbers for the other streams. .PP The initializer function .CR srand48() sets the high-order 32 bits of .IR X [ i ] to the 32 bits contained in its argument. The low-order 16 bits of .IR X [ i ] are set to the arbitrary value 0x330E (base 16). .PP The initializer function .CR seed48() sets the value of .IR X [ i ] to the 48-bit value specified in the argument array. In addition, the previous value of .IR X [ i ] is copied into a 48-bit internal buffer, used only by .CR seed48() , and a pointer to this buffer is the value returned by .CR seed48() . This returned pointer, which can be ignored if not needed, is useful if a program is to be restarted from a given point at some future time; use the pointer to get at and store the last .IR X [ i ] value, and then use this value to reinitialize via .CR seed48() when the program is restarted. .PP The initialization function .CR lcong48() allows the user to specify the initial .IR X [ i ], the multiplier value .IR a , and the addend value .IR c . Argument array elements .IR param [0-2] specify .IR X [ i ], .IR param [3-5] specify the multiplier .IR a , and .IR param [6] specifies the 16-bit addend .IR c . After .CR lcong48() has been called, a subsequent call to either .CR srand48() or .CR seed48() restores the default multiplier and addend values for .IR a and .IR c , specified above. .SS Reentrant Interfaces The reentrant .RC ( *_r ) versions of these routines require a .I dp parameter, which is a pointer to a .CR "struct drand48_data" defined in .CR as: .nf .ne 7 .IP .C "struct drand48_data {" .C " unsigned short x[3]; /* 48 bit integer */" .C " unsigned short a[3]; /* multiplier */" .C " unsigned short c; /* addend */" .C " unsigned short lastx[3]; /* previous value of x */" .C " int init; /* initialize ? */" .C "};" .fi .PP Structure member .I init must be initialized to 0 prior to calling any of these routines for the first time. Afterward, the program must not change the structure members in any way. The parameter .I randval is used to store the result or the random number. If these reentrant routines succeed, all of them return 0. If they fail, they return \(mi1 and set .CR errno . .SH ERRORS .TP 15 [EINVAL] .IR xsubi , .IR dp , or .IR randval equals .CR NULL . .SH WARNINGS .CR drand48() , .CR erand48() , .CR lrand48() , .CR nrand48() , .CR mrand48() , .CR jrand48() , .CR srand48() , .CR seed48() , and .CR lcong48() are unsafe in multithread applications. .PP .CR drand48_r() , .CR erand48_r() , .CR lrand48_r() , .CR nrand48_r() , .CR mrand48_r() , .CR jrand48_r() , .CR srand48_r() , .CR seed48_r() , and .CR lcong48_r() are MT-Safe and should be used instead. .SH SEE ALSO rand(3C), random(3M). .SH STANDARDS CONFORMANCE .CR drand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR erand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR jrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lcong48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR lrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR mrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR nrand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR seed48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR srand48() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4drand48()\f1, \f4erand48()\f1 \- generate double-precision pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4lrand48()\f1, \f4nrand48()\f1 \- generate long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4mrand48()\f1, \f4jrand48()\f1 \- generate signed long-integer pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@\f4srand48()\f1, \f4seed48()\f1, \f4lcong48()\f1 \- initialize pseudo-random number generator@@@\f3drand48(3C)\f1 .\" index@generate uniformly distributed pseudo-random numbers@@@\f3drand48(3C)\f1 .\" index@pseudo-random numbers, generate uniformly distributed@@@\f3drand48(3C)\f1 .\" index@numbers, generate uniformly distributed pseudo-random@@@\f3drand48(3C)\f1 .\" .\" toc@\f3drand48(3C)\f1:\0\0\f4drand48()\f1, \f4erand48()\f1, \f4lrand48()\f1, \f4nrand48()\f1, \f4mrand48()\f1, \f4jrand48()\f1, \f4srand48()\f1,\n\f4seed48()\f1, \f4lcong48()\f1@@@generate uniformly distributed pseudo-random numbers .\" toc@\f4erand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4nrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4mrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4jrand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4srand48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4seed48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" toc@\f4lcong48()\f1:\0\0generate pseudo-random numbers@@@see \f3drand48(3C)\f1 .\" .\" links@drand48.3c drand48_r.3c .\" links@drand48.3c erand48.3c .\" links@drand48.3c erand48_r.3c .\" links@drand48.3c lrand48.3c .\" links@drand48.3c lrand48_r.3c .\" links@drand48.3c nrand48.3c .\" links@drand48.3c nrand48_r.3c .\" links@drand48.3c mrand48.3c .\" links@drand48.3c mrand48_r.3c .\" links@drand48.3c jrand48.3c .\" links@drand48.3c jrand48_r.3c .\" links@drand48.3c srand48.3c .\" links@drand48.3c srand48_r.3c .\" links@drand48.3c seed48.3c .\" links@drand48.3c seed48_r.3c .\" links@drand48.3c lcong48.3c .\" links@drand48.3c lcong48_r.3c .\" $Header: random.3m,v 76.2 95/07/10 17:17:13 ssa Exp $ .TA r .TH random 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME random(\|), srandom(\|), initstate(\|), setstate(\|) \- generate a pseudorandom number .SH SYNOPSIS .C "#include " .PP .C "long random(void);" .PP .C "void srandom(unsigned seed);" .PP .C "char *initstate(unsigned seed, char *state, size_t size);" .PP .C "char *setstate(char *state);" .fi .ft 1 .SH DESCRIPTION The .CR random() and .CR srandom() functions are random-number generators that have virtually the same calling sequence and initialization properties as the .CR rand() and .CR srand() functions, but produce sequences that are more random. The low 12 bits generated by the .CR rand() function go through a cyclic pattern, while all the bits generated by the .CR random() function are usable. For example, .C "random() & 01" produces a random binary value. .PP The .CR random() function uses a nonlinear additive feedback random-number generator employing a default state array size of 31 long integers to return successive pseudorandom numbers in the range from 0 to .ift 2\u\s-231\s0\d-1. .ifn (2^31 - 1). The period of this random-number generator is approximately 16 x .ift (2\s-2\u31\d\s0-\f11). .ifn (2^31 - 1). The size of the state array determines the period of the random-number generator. Increasing the state array size increases the period. .PP With 256 bytes of state information, the period of the random-number generator is greater than .ift 2\s-2\u69\s0\d. .ifn 2^69. .PP Like the .CR rand() function, the .CR random() function produces by default a sequence of numbers that can be duplicated by calling the .CR srandom() function with a value of 1 as the seed. .P The .CR srandom() function initializes the current state array using the value of .IR seed . .PP The .CR initstate() and .CR setstate() functions handle restarting and changing random-number generators. The .CR initstate() function allows a state array, pointed to by the .I state argument, to be initialized for future use. The .I size argument, which specifies the size in bytes of the state array, is used by the .CR initstate() function to decide how sophisticated a random-number generator to use; the larger the state array, the more random the numbers. Values for the amount of state information are 8, 32, 64, 128, and 256 bytes. Amounts less than 8 bytes generate an error, while other amounts are rounded down to the nearest known value. The .I seed argument specifies a starting point for the random-number sequence and provides for restarting at the same point. The .CR initstate() function returns a pointer to the previous state information array. .PP Once a state has been initialized, the .CR setstate() function allows switching between state arrays. The array defined by the .I state argument is used for further random-number generation until the .CR initstate() function is called or the .CR setstate() function is called again. The .CR setstate() function returns a pointer to the previous state array. .PP After initialization, a state array can be restarted at a different point in one of two ways: .PP .RS The .CR initstate() function can be used, with the desired seed, state array, and size of the array. .PP The .CR setstate() function, with the desired state, can be used, followed by the .CR srandom() function with the desired seed. The advantage of using both of these functions is that the size of the state array does not have to be saved once it is initialized. .PP .RE .SH RETURN VALUE The .CR random() function returns the generated pseudorandom number. .PP The .CR srandom() function returns no value. .PP Upon successful completion, the .CR initstate() and .CR setstate() functions return a pointer to the previous state array. Otherwise, a NULL pointer is returned. .SH ERRORS If the .CR initstate() function is called with .I size less than 8, or if the .CR setstate() function detects that the state information has been damaged, error messages are written to standard error. .SH SEE ALSO .PP drand48(3C), rand(3C). .SH STANDARDS COMPLIANCE .CR random() "COSE API, XPG 4.2" .br .CR srandom() "COSE API, XPG 4.2" .br .CR initstate() "COSE API, XPG 4.2" .br .CR setstate() "COSE API, XPG 4.2" .\" .\" index@\f4random()\f1, \f4srandom()\f1, \f4initstate()\f1, \f4setstate()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f4srandom()\f1, \f4initstate()\f1, \f4setstate()\f1, \f4random()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f4initstate()\f1, \f4setstate()\f1, \f4random()\f1, \f4srandom()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f4setstate()\f1, \f4random()\f1, \f4srandom()\f1, \f4initstate()\f1 \- generate a pseudorandom number@@@\f3random(3M)\f1 .\" index@\f1math: pseudorandom number generation functions@@@\f3random(3M)\f1 .\" index@\f1pseudorandom number generation functions@@@\f3random(3M)\f1 .\" index@\f1random number generation functions@@@\f3random(3M)\f1 .\" .\" toc@\f3random(3M)\f1:\0\0\f4random()\f1, \f4srandom()\f1, \f4initstate()\f1, \f4setstate()\f1@@@generate a pseudorandom number .\" toc@\f4random()\f1:\0\0pseudorandom number generation functions@@@see \f3random(3M)\f1 .\" toc@\f4srandom()\f1:\0\0pseudorandom number generation functions@@@see \f3random(3M)\f1 .\" toc@\f4initstate()\f1:\0\0pseudorandom number functions@@@see \f3random(3M)\f1 .\" toc@\f4setstate()\f1:\0\0pseudorandom number functions@@@see \f3random(3M)\f1 .\" .\" links@random.3m srandom.3m .\" links@random.3m initstate.3m .\" links@random.3m setstate.3m .\" .\" fileset_database@random.3m PROGRAMING-MAN .\" $Header: scanf.3s,v 72.7 94/12/08 12:16:59 ssa Exp $ .TA s .TH scanf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scanf, fscanf, sscanf \- formatted input conversion, read from stream file .SH SYNOPSIS .C "#include " .PP .C "int scanf(const char *format, /* [pointer,] */ ...);" .PP .C "int fscanf(FILE *stream, const char *format, /* [pointer,] */ ...);" .PP .C "int sscanf(const char *s, const char *format, /* [pointer,] */ ...);" .SH DESCRIPTION .C scanf() reads from the standard input stream .IR stdin . .PP .C fscanf() reads from the named input .IR stream . .PP .C sscanf() reads from the character string .IR s . .PP Each function reads characters, interprets them according to the control string .I format argument, and stores the results in its .I pointer arguments. If there are insufficient arguments for the format, the behavior is undefined. If the format is exhausted while arguments remain, the excess arguments are ignored. The control string contains conversion specifications and other characters used to direct interpretation of input sequences. The control string contains: .RS .TP 3 \(bu White-space characters (blanks, tabs, newlines, or formfeeds) that cause input to be read up to the next non-white-space character (except in two cases described below). .TP \(bu An ordinary character (not .CR % ) that must match the next character of the input stream. .TP \(bu Conversion specifications, consisting of the character .CR % , an optional assignment suppressing character .CR * , an optional numerical maximum-field width, an optional .C l (ell), .CR ll , (ell ell), .C h or .C L indicating the size of the receiving variable, and a conversion code. .TP \(bu The conversion specification can alternatively be prefixed by the character sequence .CI % n $ instead of the character .CR % , where .I n is a decimal integer in the range .RC (1\|\(mi\| {NL_ARGMAX} ) .RC ( NL_ARGMAX is defined in .RC < limits.h >). The .CI % n $ construction indicates that the value of the next input field should be placed in the .IR n th argument, rather than to the next unused one. The two forms of introducing a conversion specification, .C % and .CI % n $\f1, must not be mixed within a single .I format string with the following exception: Skip fields (see below) can be designated as .C %* or .CI % n $*\f1. In the latter case, .I n is ignored. .RE .PP Unless the specification contains the .C n conversion character (described below), a conversion specification directs the conversion of the next input field. The result of a conversion specification is placed in the variable to which the corresponding argument points, unless .C * indicates assignment suppression. Assignment suppression provides a way to describe an input field to be skipped. An input field is defined as a string of non-space characters; it extends to the next inappropriate character or until the field width, if specified, is exhausted. For all descriptors except .C [ and .CR c , white space leading an input field is ignored. .PP The conversion code indicates the interpretation of the input field; the corresponding pointer argument must be of a restricted type. For a suppressed field, no pointer argument is given. The following conversion codes are legal: .RS .TP 12 .C % A single .C % is expected in the input at this point; no assignment is done. .TP .C d A decimal integer is expected; the corresponding argument should be an integer pointer. .TP .C u An unsigned decimal integer is expected; the corresponding argument should be an unsigned integer pointer. .TP .C o An octal integer is expected; the corresponding argument should be an unsigned integer pointer. .TP .CR x ,\0 X A hexadecimal integer is expected; the corresponding argument should be an unsigned integer pointer. The .C x and .C X conversion characters are equivalent. .TP .C i An integer is expected; the corresponding argument should be an integer pointer. The value of the next input item, interpreted according to C conventions, will be stored; a leading .C 0 implies octal, a leading .C 0x implies hexadecimal; otherwise, decimal is assumed. .TP .C n Cause the total number of bytes (including white space) scanned since the function call to be stored; the corresponding argument should be an integer pointer. No input is consumed. The function return value does not include .CI % n assignments in the count of successfully matched and assigned input items. .TP .ift \s+1\f4e\fP,\f3E\fP,\f3f\fP,\f3g\fP,\f3G\fP\s0 .ifn \f3e\fP,\f3E\fP,\f3f\fP,\f3g\fP,\f3G\fP A floating-point number is expected; the next field is converted accordingly and stored through the corresponding argument, which should be a pointer to a .IR float . The input format for floating-point numbers is an optionally signed string of digits, possibly containing a radix character, followed by an optional exponent field consisting of an .C E or an .CR e , followed by an optional .CR + , .CR - , or space, followed by an integer. The conversion characters .C E and .C G behave the same as, respectively, .C e and .CR g . .TP .C C A character is expected; the corresponding argument should be a .C wchar_t pointer. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use .CR %1S . The character is read and converted into a wide character according to the setting of .CR LC_CTYPE . If a field width is given, the corresponding argument refers to a wide character array; the indicated number of characters is read and converted. .TP .C c A character is expected; the corresponding argument should be a character pointer. The normal skip-over-white-space is suppressed in this case; to read the next non-space character, use .CR %1s . If a field width is given, the corresponding argument refers to a character array; the indicated number of characters is read. .TP .C S A character string is expected; the corresponding argument should be a .C wchar_t pointer pointing to an array of wide characters large enough to accept the string and a terminating .CR (wchar_t)0 , which is added automatically. Characters are read and converted into wide characters according to the setting of .CR LC_CTYPE . The input field is terminated by a white-space character. .C scanf() cannot read a null string. .TP .C s A character string is expected; the corresponding argument should be a character pointer pointing to an array of characters large enough to accept the string and a terminating .CR \e0 , which is added automatically. The input field is terminated by a white-space character. .C scanf() cannot read a null string. .TP .C [ Indicates string data and the normal skip-over-leading-white-space is suppressed. The left bracket is followed by a set of characters, called the .IR scanset , and a right bracket; the input field is the maximal sequence of input characters consisting entirely of characters in the scanset. The circumflex .RC ( ^ ), when it appears as the first character in the scanset, serves as a complement operator and redefines the scanset as the set of all characters .IR not contained in the remainder of the scanset string. Construction of the .I scanset follows certain conventions. A range of characters may be represented by the construct .IR first\-last , enabling [0123456789] to be expressed [0\-9]. Using this convention, .IR first must be lexically less than or equal to .IR last ; otherwise, the dash stands for itself. The dash also stands for itself when it is the first or the last character in the scanset. To include the right square bracket as an element of the scanset, it must appear as the first character (possibly preceded by a circumflex) of the scanset, in which case it will not be interpreted syntactically as the closing bracket. The corresponding argument must point to a character array large enough to hold the data field and the terminating .CR \e0 , which are added automatically. At least one character must match for this conversion to succeed. .TP .C p A sequence of unsigned hexadecimal numbers is expected. This sequence may be produced by the .C p conversion character of .CR printf() . The corresponding argument shall be a pointer to a pointer to .C void into which the value represented by the hexadecimal sequence is stored. The behavior of this conversion is undefined for any input item other than a value converted earlier during the same program execution. .PP The conversion characters .CR d , .CR i , and .C n can be preceded by .CR l , .CR ll or .CR h to indicate that a pointer to a .CR long .CR int , .CR long .CR long .CR int or .CR short .CR int rather than to an .CR int is in the argument list. Similarly, the conversion characters .CR u , .CR o , .CR x , and .CR X can be preceded by .CR l , .CR ll or .CR h to indicate that a pointer to .CR unsigned .CR long .CR int , .CR unsigned .CR long .CR long .CR int , or .CR unsigned .CR short .CR int rather than to an .CR unsigned .CR int , is in the argument list. Finally, the conversion characters .CR e , .CR E , .CR f , .CR g , and .CR G can be preceded by .CR l or .CR L to indicate that a pointer to a .CR double or .CR long .CR double rather than to a .CR float is in the argument list. The .CR l , .CR ll , .CR L or .CR h modifier is ignored for other conversion characters. .PP The .CR scanf() functions terminate their conversions at .SM EOF, at the end of the control string, or when an input character conflicts with the control string. In the latter case, the offending character is left unread in the input stream. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines the interpretation of ordinary characters within format strings as single and/or multi-byte characters. Field width is given in terms of bytes. Characters received from the input stream are interpreted as single- or multi-byte characters as determined by the .CR LC_TYPE category and the field width is decremented by the length of the character. .PP The .CR LC_NUMERIC category determines the radix character expected within floating-point numbers. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUES If the input ends before the first conflict or conversion, .SM EOF is returned. Otherwise, these functions return the number of successfully assigned input items. This number is a short count, or even zero if a conflict ensues between an input character and the control string. .SH ERRORS .CR scanf() and .CR fscanf() fail if data needs to be read into the .IR stream 's buffer, and: .RS .TP15 .SM [EAGAIN] The .SM O_NONBLOCK flag is set for the file descriptor underlying .I stream and the process would be delayed in the read operation. .TP .SM [EBADF] The file descriptor underlying .I stream is not a valid file descriptor open for reading. .TP .SM [EINTR] The read operation was terminated due to the receipt of a signal, and either no data was transferred or the implementation does not report partial transfer for this file. .TP .SM [EIO] The process is a member of a background process and is attempting to read from its controlling terminal, and either the process is ignoring or blocking the .CR SIGTTIN signal or the process group of the process is orphaned. .RE .PP Additional .CR errno values can be set by the underlying .CR read() function (see .IR read (2)). .SH EXAMPLES The call: .IP .CR "int i, n; float x; char name[50];" .br .ift \f4\s+1n = scanf("%d%f%s", &i, &x, name);\s0\fP .ifn \f3n = scanf("%d%f%s", &i, &x, name);\fP .PP with the input line: .IP .CR "25 54.32E-1 thompson" .PP assigns to .I n the value .CR 3 , to .I i the value .CR 25 , to .I x the value .CR 5.432 , and .I name contains .CR thompson\e0 . Or: .IP .CR "int i; float x; char name[50];" .br .ift \f4\s+1(void) scanf("%2d%f%*d %[0\-9]", &i, &x, name);\s0\fP .ifn \f3(void) scanf("%2d%f%*d %[0\-9]", &i, &x, name);\fP .PP with input: .IP .CR "56789 0123 56a72" .PP assigns .CR 56 to .IR i , .CR 789.0 to .IR x , skips .CR 0123 , and places the string .CR 56\e0 in .IR name . The next call to .CR getchar() (see .IR getc (3S)) returns .CR a . .PP For another example, to create a language-independent date scanning routine, use: .IP .CR "char month[20]; int day, year;" .br .CR "(void) scanf(format, month, &day, &year);" .PP For American usage, .I format would point to a string: .IP .CR "%1$s %2$d %3$d" .PP The input: .IP .CR "July 3 1986" .PP would assign .CR July to .IR month , .CR 3 to .I day and .CR 1986 to .IR year . .PP For German usage, .I format would point to a string: .IP .CR "%2$d %1$s %3$d" .PP The input: .IP 3 Juli 1986 .PP would assign .CR Juli to .IR month , .CR 3 to .I day and .CR 1986 to .IR year . .PP The success of literal matches and suppressed assignments can be determined with the .CR %n conversion specification. Here is an example that checks the success of literal matches: .nf .IP .CR "int i, n1, n2, n3, n4;" .ift .ft 4 .ifn .ft 3 .ps +1 n1 = n2 = n3 = n4 = -1;" scanf( "%nBEGIN%n %d %nEND%n", &n1, &n2, &i, &n3, &n4); if (n2 - n1 == 5) puts( "matched BEGIN"); if (n4 - n3 == 3) puts( "matched END"); .ft .ps .fi .PP Here is an example that checks the success of suppressed assignments: .nf .IP .CR "int i, n1, n2;" .CR "n1 = n2 = -1;" .ift .ft 4 .ifn .ft 3 .ps +1 scanf( "%d %n%*s%n", &i, &n1, &n2); if (n2 > n1) printf( "successful assignment suppression of %d chars\\n", n2 - n1); .ps .ft .SH WARNINGS Trailing white space (including a newline) is left unread unless matched in the control string. .PP Truncation of multi-byte characters may occur if a field width is used with the conversion character. .SH AUTHOR .CR scanf() was developed by AT&T and HP. .SH SEE ALSO getc(3S), setlocale(3C), printf(3S), strtod(3C), strtol(3C). .SH STANDARDS CONFORMANCE .CR scanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR fscanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .CR sscanf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4scanf()\f1 \- formatted read from \f2standard input\f1 stream file@@@\f3scanf(3S)\f1 .\" index@\f4fscanf()\f1 \- formatted read from named input stream file@@@\f3scanf(3S)\f1 .\" index@\f4sscanf()\f1 \- formatted read from character string@@@\f3scanf(3S)\f1 .\" index@\f4scanf()\f1 \- formatted read from \f2standard input\f1 stream file@@@\f3scanf(3S)\f1 .\" index@\f4fscanf()\f1 \- formatted read from named input stream file@@@\f3scanf(3S)\f1 .\" index@\f4sscanf()\f1 \- formatted read from character string@@@\f3scanf(3S)\f1 .\" index@formatted input conversion, read from stream file or character string@@@\f3scanf(3S)\f1 .\" index@input conversion, formatted read from stream file or character string@@@\f3scanf(3S)\f1 .\" index@formatted read and conversion from stream file or character string@@@\f3scanf(3S)\f1 .\" index@read from stream file or character string with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@stream file or character string, read from with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@file: read from file, stream, or character string with formatted input conversion@@@\f3scanf(3S)\f1 .\" index@character string or stream file, read from with formatted input conversion@@@\f3scanf(3S)\f1 .\" .\" toc@\f3scanf(3S)\f1:\0\0\f4scanf()\fP, \f4fscanf()\fP, \f4sscanf()\f1@@@formatted input conversion, read from stream file .\" toc@\f4fscanf()\fP:\0\0formatted input conversion, read from stream file@@@see \f3scanf(3S)\f1 .\" toc@\f4sscanf()\fP:\0\0formatted input conversion, read from stream file@@@see \f3scanf(3S)\f1 .\" .\" links@scanf.3s fscanf.3s .\" links@scanf.3s sscanf.3s .\" links@scanf.3s nl_scanf.3s .\" links@scanf.3s nl_fscanf.3s .\" links@scanf.3s nl_sscanf.3s .\" $Header: ssignal.3c,v 72.4 94/11/15 09:56:23 ssa Exp $ .TA s .TH ssignal 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ssignal(\|), gsignal(\|) \- software signals .SH SYNOPSIS .C "#include " .PP .C "int (*ssignal(int sig, int (*action)(int)))(int);" .PP .C "int gsignal(int sig);" .SH DESCRIPTION .C ssignal() and .C gsignal() implement a software facility similar to .IR signal (5). This facility is used by the Standard C Library to enable users to indicate the disposition of error conditions, and is also made available to users for their own purposes. .PP Software signals made available to users are associated with integers in the inclusive range 1 through 15. A call to .C ssignal() associates a procedure, .IR action , with the software signal .IR sig ; the software signal, .IR sig , is raised by a call to .CR gsignal() . Raising a software signal causes the action established for that signal to be taken. .PP The first argument to .C ssignal() is a number identifying the type of signal for which an action is to be established. The second argument defines the action; it is either the name of a (user-defined) .I action function or one of the manifest constants .C SIG_DFL (default) or .C SIG_IGN (ignore). .C ssignal() returns the action previously established for that signal type; if no action has been established or the signal number is illegal, .C ssignal() returns .CR SIG_DFL . .PP .C gsignal() raises the signal identified by its argument, .IR sig : .RS .TP 3 \(bu If an action function has been established for .IR sig , that action is reset to .C SIG_DFL and the action function is entered with argument .IR sig . .C gsignal() returns the value returned to it by the action function. .TP \(bu If the action for .I sig is .CR SIG_IGN , .C gsignal() returns the value 1 and takes no other action. .TP \(bu If the action for .I sig is .CR SIG_DFL , .C gsignal() returns the value 0 and takes no other action. .TP \(bu If .I sig has an illegal value or no action was ever specified for .IR sig , .C gsignal() returns the value 0 and takes no other action. .RE .SH SEE ALSO signal(5). .SH NOTES Some additional signals with numbers outside the range 1 through 15 are used by the Standard C Library to indicate error conditions. Those signal numbers outside the range 1 through 15 are legal, although their use may interfere with the operation of the Standard C Library. .SH STANDARDS CONFORMANCE .CR ssignal() ": SVID2, SVID3, XPG2" .PP .CR gsignal() ": SVID2, SVID3, XPG2" .\" .\" index@\f4ssignal()\fP \- raise a software signal and perform an action@@@\f3ssignal(3C)\f1 .\" index@\f4gsignal()\fP \- raise a software signal@@@\f3ssignal(3C)\f1 .\" index@raise a software signal@@@\f3ssignal(3C)\f1 .\" index@software signal, raise a@@@\f3ssignal(3C)\f1 .\" index@signal, raise a software@@@\f3ssignal(3C)\f1 .\" .\" toc@\f3ssignal(3C)\f1:\0\0\f4ssignal()\fP, \f4gsignal()\fP@@@software signals .\" toc@\f4gsignal()\fP:\0\0software signals@@@see \f3ssignal(3C)\f1 .\" .\" links@ssignal.3c gsignal.3c .\" .\" fileset_database@ssignal.3c PROGRAMING-MAN .\" $Header: standend.3x,v 76.2 95/08/01 14:48:02 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH standend 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME standend, standout, wstandend, wstandout \(em set and clear window attributes .SH SYNOPSIS .C "#include " .P .C "int standend(void);" .P .C "int standout(void);" .P .C "int wstandend(WINDOW *\f2win\fP);" .P .C "int wstandout(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn standend and .Fn wstandend functions turn off all attributes of the current or specified window. .P The .Fn standout and .Fn wstandout functions turn on the standout attribute of the current or specified window. .SH "RETURN VALUE" These functions always return 1. .SH ERRORS No errors are defined. .SH "SEE ALSO" attroff(), attr_get(), . .SH "CHANGE HISTORY" Derived from the .Fn attroff entry in X/Open Curses, Issue 3. The entry is reworded for clarity, but otherwise the functionality is identical to previous issues. .\" .\" toc@\f3standend(3X)\f1:\0\0\f4standend()\f1, \f4standout()\f1, \f4wstandend()\f1, \f4wstandout()\f1@@@set and clear window attributes .\" toc@\f4standout()\f1: set and clear window attributes@@@see \f3standend(3X)\f1 .\" toc@\f4wstandend()\f1: set and clear window attributes@@@see \f3standend(3X)\f1 .\" toc@\f4wstandout()\f1: set and clear window attributes@@@see \f3standend(3X)\f1 .\" .\" index@\f4standend()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f4standout()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f4wstandend()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f4wstandout()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f1set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f1clear window attributes@@@\f3standend(3X)\f1 .\" index@\f1window attributes, set and clear@@@\f3standend(3X)\f1 .\" index@\f1attributes, window, set and clear@@@\f3standend(3X)\f1 .\" .\" links@standend.3x standout.3x .\" links@standend.3x wstandend.3x .\" links@standend.3x wstandout.3x .\" .\" fileset_database@standend.3x CURS-ENG-A-MAN .\" $Header: standend.3x,v 76.2 95/08/01 14:48:02 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH standend 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME standend, standout, wstandend, wstandout \(em set and clear window attributes .SH SYNOPSIS .C "#include " .P .C "int standend(void);" .P .C "int standout(void);" .P .C "int wstandend(WINDOW *\f2win\fP);" .P .C "int wstandout(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn standend and .Fn wstandend functions turn off all attributes of the current or specified window. .P The .Fn standout and .Fn wstandout functions turn on the standout attribute of the current or specified window. .SH "RETURN VALUE" These functions always return 1. .SH ERRORS No errors are defined. .SH "SEE ALSO" attroff(), attr_get(), . .SH "CHANGE HISTORY" Derived from the .Fn attroff entry in X/Open Curses, Issue 3. The entry is reworded for clarity, but otherwise the functionality is identical to previous issues. .\" .\" toc@\f3standend(3X)\f1:\0\0\f4standend()\f1, \f4standout()\f1, \f4wstandend()\f1, \f4wstandout()\f1@@@set and clear window attributes .\" toc@\f4standout()\f1: set and clear window attributes@@@see \f3standend(3X)\f1 .\" toc@\f4wstandend()\f1: set and clear window attributes@@@see \f3standend(3X)\f1 .\" toc@\f4wstandout()\f1: set and clear window attributes@@@see \f3standend(3X)\f1 .\" .\" index@\f4standend()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f4standout()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f4wstandend()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f4wstandout()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f1set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f1clear window attributes@@@\f3standend(3X)\f1 .\" index@\f1window attributes, set and clear@@@\f3standend(3X)\f1 .\" index@\f1attributes, window, set and clear@@@\f3standend(3X)\f1 .\" .\" links@standend.3x standout.3x .\" links@standend.3x wstandend.3x .\" links@standend.3x wstandout.3x .\" .\" fileset_database@standend.3x CURS-ENG-A-MAN .\" $Header: can_change_color.3x,v 76.3 95/10/05 14:12:23 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH can_change_color 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME can_change_color, color_content, has_colors, init_color, init_pair, start_color, pair_content \(em color manipulation functions .SH SYNOPSIS .C "#include " .P .C "bool can_change_color(void);" .P .C "int color_content(short \f2color\fP, short *\f2red\fP, short *\f2green\fP, short *\f2blue\fP);" .P .C "int COLOR_PAIR(int \f2n\fP);" .P .C "bool has_colors(void);" .P .C "int init_color(short \f2color\fP, short \f2red\fP, short \f2green\fP, short \f2blue\fP);" .P .C "int init_pair(short \f2pair\fP, short \f2f\fP, short \f2b\fP);" .P .C "int pair_content(short \f2pair\fP, short *\f2f\fP, short *\f2b\fP);" .P .C "int PAIR_NUMBER(int \f2value\fP);" .P .C "int start_color(void);" .P .C "extern int COLOR_PAIRS;" .P .C "extern int COLORS;" .SH DESCRIPTION These functions manipulate colour on terminals that support colour. .SS "Querying Capabilities" The .Fn has_colors function indicates whether the terminal is a colour terminal. The .Fn can_change_color function indicates whether the terminal is a colour terminal on which colours can be redefined. .SS "Initialisation" The .Fn start_color function must be called in order to enable use of colours and before any colour manipulation function is called. The function initialises eight basic colours (black, blue, green, cyan, red, magenta, yellow, and white) that can be specified by the colour macros (such as COLOR_BLACK) defined in .CR . (See \f3Colour-related Macros\f1 in \f3\f1.) The initial appearance of these eight colours is not specified. .P The function also initialises two global external variables: .RS .TP 3 .C \(bu COLORS defines the number of colours that the terminal supports. (See .B "Colour Identification" below.) If COLORS is 0, the terminal does not support redefinition of colours (and .Fn can_change_colour will return FALSE). .TP .C \(bu COLOR_PAIRS defines the maximum number of colour-pairs that the terminal supports. (See .B "User-Defined Colour Pairs" below.) .RE .P The .Fn start_color function also restores the colours on the terminal to terminal-specific initial values. The initial background colour is assumed to be black for all terminals. .SS "Colour Identification" The .Fn init_color function redefines colour number \f2color\fP, on terminals that support the redefinition of colours, to have the red, green, and blue intensity components specified by \f2red\fP, \f2green\fP, and \f2blue\fP, respectively. Calling .Fn init_color also changes all occurrences of the specified colour on the screen to the new definition. .P The .Fn color_content function identifies the intensity components of colour number \f2color\f1. It stores the red, green, and blue intensity components of this colour in the addresses pointed to by \f2red\fP, \f2green\fP, and \f2blue\fP, respectively. .P For both functions, the .I color argument must be in the range from 0 to and including COLORS\|\(mi\|1. Valid intensity values range from 0 (no intensity component) up to and including 1000 (maximum intensity in that component). .SS "User-Defined Colour Pairs" Calling .Fn init_pair defines or redefines colour-pair number \f2pair\f1 to have foreground colour \f2f\f1 and background colour \f2b\f1. Calling .Fn init_pair changes any characters that were displayed in the colour pair's old definition to the new definition and refreshes the screen. .P After defining the colour pair, the macro COLOR_PAIR(\f2n\fP) returns the value of colour pair \f2n\f1. This value is the colour attribute as it would be extracted from a .CR chtype . Conversely, the macro PAIR_NUMBER(\f2value\fP) returns the colour pair number associated with the colour attribute \f2value\f1. .P The .Fn pair_content function retrieves the component colours of a colour-pair number \f2pair\f1. It stores the foreground and background colour numbers in the variables pointed to by \f2f\f1 and \f2b\fP, respectively. .P With .Fn init_pair and .Fn pair_content , the value of \f2pair\f1 must be in a range from 0 to and including COLOR_PAIRS\|\(mi\|1. (There may be an implementation-specific lower limit on the valid value of \f2pair\fP, but any such limit is at least 63.) Valid values for \f2f\f1 and \f2b\f1 are the range from 0 to and including COLORS\|\(mi\|1. .SH "RETURN VALUE" The .Fn has_colors function returns TRUE if the terminal can manipulate colors; otherwise, it returns FALSE. .P The .Fn can_change_color function returns TRUE if the terminal supports colors and can change their definitions; otherwise, it returns FALSE. .P Upon successful completion, the other functions return OK; otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" To use these functions, .Fn start_color must be called, usually right after .CR initscr() . .P The .Fn can_change_color and .Fn has_colors functions facilitate writing terminal-independent programs. For example, a programmer can use them to decide whether to use colour or some other video attribute. .P On color terminals, a typical value of COLORS is 8 and the macros such as COLOR_BLACK return a value within the range from 0 to and including 7. However, applications cannot rely on this to be true. .SH "SEE ALSO" attroff(), delscreen(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3can_change_color(3X)\f1:\0\0\f4can_change_color()\f1, \f4color_content()\f1, \f4has_colors()\f1, \f4init_color()\f1, \n\f4init_pair()\f1, \f4start_color()\f1, \f4pair_content()\f1@@@color manipulation functions .\" toc@\f4color_content()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4has_colors()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4init_colors()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4init_pair()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4start_color()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" toc@\f4pair_content()\f1: color manipulation functions@@@see \f3can_change_color(3X)\f1 .\" .\" index@\f4can_change_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4color_content()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4has_colors()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4init_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4init_pair()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4start_color()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f4pair_content()\f1 \- color manipulation functions@@@\f3can_change_color(3X)\f1 .\" index@\f1color manipulation functions@@@\f3can_change_color(3X)\f1 .\" .\" links@can_change_color.3x color_content.3x .\" links@can_change_color.3x has_colors.3x .\" links@can_change_color.3x init_color.3x .\" links@can_change_color.3x init_pair.3x .\" links@can_change_color.3x start_color.3x .\" links@can_change_color.3x pair_content.3x .\" .\" fileset_database@can_change_color.3x CURS-ENG-A-MAN .\" $Header: statfsdev.3c,v 72.4 93/01/14 14:50:13 ssa Exp $ .TA s .TH statfsdev 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME statfsdev, fstatfsdev \- get file system statistics .SH SYNOPSIS .C "#include " .PP .C "int statfsdev(const char *path, struct statfs *buf);" .PP .C "int fstatfsdev(int fildes, struct statfs *buf);" .SH DESCRIPTION .C statfsdev() returns information about the file system on the file specified by .I path. .PP .I buf is a pointer to a .C statfs structure into which information is placed concerning the file system. The contents of the structure pointed to by .I buf include the following members: .nf .IP .C "long f_bavail /* free blocks available to non-superuser */" .C "long f_bfree /* free blocks */" .C "long f_blocks /* total blocks in file system */" .C "long f_bsize /* fundamental file system block size in bytes */" .C "long f_ffree /* free file nodes in file system */" .C "long f_files /* total file nodes in file system */" .C "long f_type /* type of info, zero for now */" .C "fsid_t f_fsid /* file system ID. f_fsid[1] is MOUNT_UFS," .C " MOUNT_NFS, or MOUNT_CDFS */" .fi .PP Fields that are undefined for a particular file system are set to \(mi1 . .PP .C fstatfsdev() returns the same information as above, but about the open file referred to by file descriptor .IR fildes . .SH RETURN VALUE Upon successful completion, .C statfsdev() and .C fstatfsdev() return zero. Otherwise, they return \-1 and set the global variable .C errno to indicate the error. .SH ERRORS .C statfsdev() fails if one or more of the following conditions are encountered: .RS .TP 15 .SM [EACCES] Search permission is denied for a component of the path prefix. .TP .SM [EAGAIN] The file exists, enforcement mode file/record locking is set, and there are outstanding record locks on the file. .TP .SM [EFAULT] .I path points to an invalid address. .TP .SM [ELOOP] Too many symbolic links are encountered in translating the path name. .TP .SM [EMFILE] The maximum number of file descriptors allowed are currently open. .TP .SM [ENAMETOOLONG] The length of the specified path name exceeds .C PATH_MAX bytes, or the length of a component of the path name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] The system file table is full. .TP .SM [ENOENT] The named file does not exist. .TP .SM [ENOTDIR] A component of the path prefix is not a directory. .TP .SM [ENXIO] The device specified by the named special file does not exist. .RE .PP .C fstatfsdev() fails if one or more of the following is true: .RS .TP 15 .SM [EBADF] .I fildes is not a valid open file descriptor. .TP 15 .SM [ESPIPE] .I filedes points to an invalid address. .RE .PP Both .C fstatfsdev() and .C statfsdev() fail if one or more of the following is true: .RS .TP 15 .SM [EAGAIN] Enforcement-mode record locking was set, and there was a blocking write lock. .TP .SM [EDEADLK] A resource deadlock would occur as a result of this operation. .TP .SM [EINTR] A system call was interrupted by a signal. .TP .SM [EINVAL] The file specified by .I path or .I filedes does not contain a file system of any known type. .TP .SM [ENOLCK] The system lock table was full, so the read could not go to sleep until the blocking write lock was removed. .SH AUTHOR .C statfsdev() and .C fstatfsdev() were developed by HP. .RE .SH FILES .C /usr/include/sys/mount.h .SH SEE ALSO bdf(1M), df(1M), stat(2), statfs(2). .\" .\" index@\f4statfsdev()\fP, \f4fstatfsdev()\fP \- get file system statistics@@@\f3statfsdev(3C)\f1 .\" index@\f4fstatfsdev()\fP, \f4statfsdev()\fP \- get file system statistics@@@\f3statfsdev(3C)\f1 .\" index@get file system statistics@@@\f3statfsdev(3C)\f1 .\" index@file system statistics, get@@@\f3statfsdev(3C)\f1 .\" index@statistics, get file system@@@\f3statfsdev(3C)\f1 .\" .\" toc@\f3statfsdev(3C)\f1:\0\0\f4statfsdev()\fP, \f4fstatfsdev()\fP@@@get file system statistics .\" toc@\f4fstatfsdev()\fP: get file system statistics@@@see \f3statfsdev(3C)\f1 .\" .\" links@statfsdev.3c fstatfsdev.3c .\" .\" fileset_database@statfsdev.3c PROGRAMING-MAN .\" $Header: statvfsdev.3c,v 78.1 96/02/12 14:19:48 ssa Exp $ .TA s .TH statvfsdev 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME statvfsdev, fstatvfsdev \- get file system information .SH SYNOPSIS .C "#include " .PP .C "int statvfsdev(const char *path, struct statvfs *buf);" .PP .C "int fstatvfsdev(int fildes, struct statvfs *buf);" .SH DESCRIPTION .C statvfsdev() returns information about the file system on the device file specified by .I path. The file system need not be mounted. .PP .C fstatvfsdev() returns similar information for an open file. .PP The parameters for the .CR stat() , .CR fstat() , and .C lstat() functions are as follows: .RS .TP 20 .I path is a pointer to a path name of any file within the file system. (All directories listed in the path name must be searchable.) .TP .I buf is a pointer to a .C statvfs() structure, which is where the file status information is stored. .TP .I fildes is a file descriptor for an open file, which is created with the successful completion of an .CR open() , .CR creat() , .CR dup() , .CR fcntl() , or .CR pipe() system call (see .IR open (2), .IR creat (2), .IR dup (2), .IR fcntl (2), or .IR pipe (2)). .RE .PP .I buf is a pointer to a .C statvfs structure into which information is placed concerning the file system. The contents of the structure pointed to by .I buf are described in .IR statvfs (2). .PP .C fstatvfsdev() returns the same information as above, but about the open device file referred to by file descriptor .IR fildes . .SH RETURN VALUE Upon successful completion, .C statvfsdev() and .C fstatvfsdev() return zero. Otherwise, they return \-1 and set the global variable .C errno to indicate the error. .SH ERRORS If .C statvfsdev() fails, .C errno is set to one of the following values: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of the path prefix. .TP .SM [EFAULT] .I path points to an invalid address. .TP .SM [ELOOP] Too many symbolic links are encountered during path-name translation. .TP .SM [EMFILE] The maximum number of file descriptors allowed are currently open. .TP .SM [ENAMETOOLONG] The length of the specified path name exceeds .C PATH_MAX bytes, or the length of a component of the path name exceeds .C NAME_MAX bytes while .C _POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] The system file table is full. .TP .SM [ENOENT] The named file does not exist. .TP .SM [ENOTDIR] A component of the path prefix is not a directory. .TP .SM [ENXIO] The device specified by the named special file does not exist. .RE .PP If .C fstatvfsdev() fails, .C errno is set to one of the following values: .RS .TP 20 .SM [EBADF] .I fildes is not a valid open file descriptor. .TP 20 .SM [ESPIPE] .I filedes is invalid. .RE .PP When both .C fstatvfsdev() and .C statvfsdev() fail, .C errno is set to one of the following values: .RS .TP 20 .SM [EINTR] A system call was interrupted by a signal. .TP .SM [EINVAL] The file specified by .I path or .I filedes does not contain a file system of any known type. .SH AUTHOR .C statvfsdev() and .C fstatvfsdev() were developed by HP. .RE .SH SEE ALSO bdf(1M), df(1M), stat(2), statvfs(2), fstatvfsdev64(3C), statvfsdev64(3C). .\" .\" index@\f4statvfsdev()\f1, \f4fstatvfsdev()\f1 \- get file system statistics@@@\f3statvfsdev(3C)\f1 .\" index@\f4fstatvfsdev()\f1, \f4statvfsdev()\f1 \- get file system statistics@@@\f3statvfsdev(3C)\f1 .\" index@\f1get file system statistics@@@\f3statvfsdev(3C)\f1 .\" index@\f1file system statistics, get@@@\f3statvfsdev(3C)\f1 .\" index@\f1statistics, get file system@@@\f3statvfsdev(3C)\f1 .\" .\" toc@\f3statvfsdev(3C)\f1:\0\0\f4statvfsdev()\f1, \f4fstatvfsdev()\f1@@@get file system statistics .\" toc@\f4fstatvfsdev()\f1:\0\0get file system statistics@@@see \f3statvfsdev(3C)\f1 .\" .\" links@statvfsdev.3c fstatvfsdev.3c .\" $Header: fgetpos64.3s,v 78.3 96/02/12 17:04:12 ssa Exp $ .TA f .TH fgetpos64 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetpos64(\|), fopen64(\|), freopen64(\|), fseeko64(\|), fsetpos64(\|), fstatvfsdev64(\|), ftello64(\|), ftw64(\|), nftw64(\|), statvfsdev64(\|), tmpfile64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0fgetpos64(FILE\0*stream,\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "FILE\0*fopen64(const\0char\0*pathname,\0const\0char\0*type);" .PP .C "#include " .PP .C "FILE\0*freopen64(const\0char\0*pathname,\0const\0char\0*type,\0FILE\0*stream);" .PP .C "#include " .PP .C "int\0fseeko64(FILE\0*stream,\0off64_t\0*offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0fsetpos64(FILE\0*stream,\0const\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "int\0fstatvfsdev64(int\0filedes,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "off64_t\0ftello64(FILE\0*stream);" .PP .nf .C "#include " .PP .C "int ftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags)," .C " int depth);" .PP .C "#include " .PP .C "int nftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .PP .C "#include " .PP .C "int\0statvfsdev64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "FILE\0*tmpfile64(void);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 22 .C fgetpos64() The .C fgetpos64() function is identical to .C fgetpos() except that .C fgetpos64() returns the position in a .C fpos64_t instead of a .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fopen64() The .C fopen64() function is identical to .C fopen() in 64-bit compile environment. The .C fopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR fopen() . .TP .C freopen64() The .C freopen64() function is identical to .C freopen() in 64-bit compile environment. The .C freopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR freopen() . .TP .C fseeko64() The .C fseeko64() function is identical to .C fseeko() except that .C fseeko64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C fsetpos64() The .C fsetpos64() function is identical to .C fsetpos() except that .C fsetpos64() accepts an .CR fpos64_t for the pos parameter instead of .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fstatvfsdev64() The .C fstatvfsdev64() function is identical to .C fstatvfsdev() except that .C fstatvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C ftello64() The .C ftello64() function is identical to .C ftello() except that .C ftello64() returns the file position in an .C off64_t instead of an .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C ftw64() The .C ftw64() function is identical to .C ftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR ftw64() . All other functional behaviors, returns, and errors are identical. .TP .C nftw64() The .C nftw64() function is identical to .C nftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR nftw64() . All other functional behaviors, returns, and errors are identical. .TP .C statvfsdev64() The .C statvfsdev64() function is identical to .C statvfsdev() except that .C statvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C tmpfile64() The .C tmpfile64() function is identical to .C tmpfile() in the 64-bit compile environment. Both interfaces create a temporary file that is capable of growing beyond 2GB's if desired. All other functional behaviors, returns, and errors are identical. .\" .\" toc@\f4fgetpos64(2)\f1:\0\0\f4fopen64\f1, \f4freopen64\f1, \f4fseeko64\f1, \f4fsetpos64\f1, \f4fstatvfsdev64\f1, \f4ftello64\f1, \f4ftw64\f1, \n\f4nftw64\f1, \f4statvfsdev64\f1, \f4tmpfile64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4fgetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4freopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fseeko64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fsetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fstatvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftello64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4nftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4statvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4tmpfile64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3fgetpos64(2)\f1 .\" .\" links@fgetpos64.3s fopen64.3s .\" links@fgetpos64.3s freopen64.3s .\" links@fgetpos64.3s fseek64.3s .\" links@fgetpos64.3s fsetpos64.3s .\" links@fgetpos64.3s fstatvfs64.3s .\" links@fgetpos64.3s ftello64.3s .\" links@fgetpos64.3s ftw64.3s .\" links@fgetpos64.3s nftw64.3s .\" links@fgetpos64.3s statvfsdev64.3s .\" links@fgetpos64.3s tmpfile64.3s .\" .\" $Header: stdio.3s,v 78.1 96/05/09 10:59:31 ssa Exp $ .TA s .TH stdio 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME stdio(\|) \- standard buffered input/output stream file package .SH SYNOPSIS .C "#include " .SH DESCRIPTION The Standard .SM I/O functions described in the subsection .SM (3S) entries of this manual constitute an efficient, user-level .SM I/O buffering scheme. The .CR getc() and .CR putc() functions handle characters quickly. The following funtions all use or act as if they use .C getc() and .CR putc() , and can be freely intermixed: .nf .IP .C "fgetc() fputs() getchar() putchar()" .C "fgets() fread() gets() puts()" .C "fprintf() fscanf() getw() putw()" .C "fputc() fwrite() printf() scanf()" .fi .PP A file with associated buffering is called a .I stream and is declared to be a pointer to a defined type .CR FILE . .C fopen() creates certain descriptive data for a stream and returns a pointer to designate the stream in all further transactions. Section (3S) library routines operate on this stream. .PP At program startup, three streams, .IR "standard input" , .IR "standard output" , and .IR "standard error" , are predefined and do not need to be explicitly opened. When opened, the standard input and standard output streams are fully buffered if the output refers to a file and line-buffered if the output refers to a terminal. The standard error output stream is by default unbuffered. These three streams have the following constant pointers declared in the .RC < stdio.h > header file : .RS .TP 10 .C stdin standard input file .PD 0 .TP .C stdout standard output file .TP .C stderr standard error file .RE .PD .PP A constant, .CR NULL , (0) designates a nonexistent pointer. .PP An integer-constant, .CR EOF , (\-1) is returned upon end-of-file or error by most integer functions that deal with streams (see individual descriptions for details). .PP An integer constant .C BUFSIZ specifies the size of the buffers used by the particular implementation (see .IR setbuf (3S)). .PP Any program that uses this package must include the header file of pertinent macro definitions as follows: .IP .C "#include " .PP The functions and constants mentioned in subsection .SM (3S) entries of this manual are declared in that header file and need no further declaration. .PP A constant .C _NFILE defines the default maximum number of open files allowed per process. To increase the open file limit beyond this default value, see .IR setrlimit (2). .SH WARNINGS Use of .C stdio interfaces with a shared read/write file descriptor on .C non-positional devices will provide undefined behavior. Applications which are doing .C stdio operations on .C non-positional devices need to use seperate file pointers for input and output, even if using the same file descriptor for both types of operations. .SH SEE ALSO close(2), lseek(2), open(2), pipe(2), read(2), setrlimit(2), write(2), ctermid(3S), cuserid(3S), fclose(3S), ferror(3S), fgetpos(3S), fileno(3S), fopen(3S), fread(3S), fseek(3S), fsetpos(3S), getc(3S), gets(3S), popen(3S), printf(3S), putc(3S), puts(3S), scanf(3S), setbuf(3S), system(3S), tmpfile(3S), tmpnam(3S), ungetc(3S). .SH ERRORS Invalid .I stream pointers usually cause grave disorder, possibly including program termination. Individual function descriptions describe the possible error conditions. .SH STANDARDS CONFORMANCE .CR stderr ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR stdin ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR stdout ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4stdio()\fP \- standard buffered input/output stream file package@@@\f3stdio(3S)\f1 .\" index@standard buffered input/output stream file package@@@\f3stdio(3S)\f1 .\" index@buffered input/output standard stream file package@@@\f3stdio(3S)\f1 .\" index@input/output, buffered, standard stream file package@@@\f3stdio(3S)\f1 .\" index@output/input, buffered, standard stream file package@@@\f3stdio(3S)\f1 .\" index@stream file package, standard buffered input/output@@@\f3stdio(3S)\f1 .\" .\" toc@\f3stdio(3S)\f1:\0\0\f4stdio()\fP@@@standard buffered input/output stream file package .\" .\" fileset_database@stdio.3s PROGRAMING-MAN .\" $Header: ftok.3c,v 76.1 95/06/20 14:45:24 ssa Exp $ .TA f .TH ftok 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ftok(\|) \- create interprocess communication identifier .SH SYNOPSIS .C "#include " .PP .C "key_t ftok(const char *path, int id);" .SH DESCRIPTION All interprocess communication facilities require the user to supply a key to be used by the .CR msgget() , .CR semget() , and .CR shmget() system calls to obtain interprocess communication identifiers (see .IR msgget (2), .IR semget (2), and .IR shmget (2)). .PP .C ftok() returns a key based on .I path and .I id that is usable in subsequent .CR msgget() , .CR semget() , and .C shmget() system calls. .PP The parameters for the .C ftok() function are as follows: .RS .TP20 .I path must be the path name of an existing file that is accessible to the process. .TP .I id is a character that uniquely identifies a project. Note that .C ftok() returns the same key for linked files when called with the same .I id and that it returns different keys when called with the same file name but different .IR id s. .RE .SH RETURN VALUE .C ftok() returns .RC ( key_t ) \(mi 1 if .I path does not exist or if it is not accessible to the process. .SH EXAMPLES The following call to .CR ftok () returns a key associated with the file .I myfile and id .CR A : .IP .ift .ft 4 .ifn .ft 3 .ps +1 key_t mykey; mykey = ftok ("myfile", 'A'); .ft .ps .RE .SH WARNINGS If the file whose .I path is passed to .C ftok() is removed when keys still refer to the file, future calls to .C ftok() with the same .I path and .I id will return an error. If the same file is recreated, .C ftok() is likely to return a different key than it did the original time it was called. .SH SEE ALSO intro(2), msgget(2), semget(2), shmget(2). .\" .\" index@\f4ftok()\f1 \- create interprocess communication identifier@@@\f3ftok(3C)\f1 .\" index@\f1create interprocess communication identifier@@@\f3ftok(3C)\f1 .\" index@\f1interprocess communication identifier, create@@@\f3ftok(3C)\f1 .\" index@\f1communication identifier, create interprocess@@@\f3ftok(3C)\f1 .\" index@\f1identifier, create interprocess communication@@@\f3ftok(3C)\f1 .\" .\" toc@\f3ftok(3C)\f1:\0\0\f4ftok()\f1@@@create interprocess communication identifier .\" .\" links@ftok.3c stdipc.3c .\" $Header: stdscr.3x,v 76.2 95/08/01 14:48:53 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH stdscr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME stdscr \(em default window .SH SYNOPSIS .C "#include " .P .C "extern WINDOW *stdscr;" .SH DESCRIPTION The external variable .I stdscr specifies the default window used by functions that do not specify a window using an argument of type .B "WINDOW *" . Other windows may be created using .CR newwin() . .SH "SEE ALSO" derwin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4stdscr()\f1 \- default window@@@\f3stdscr(3X)\f1 .\" index@\f1default window@@@\f3stdscr(3X)\f1 .\" index@\f1window, default@@@\f3stdscr(3X)\f1 .\" .\" toc@\f3stdscr(3X)\f1:\0\0\f4stdscr()\f1@@@default window .\" .\" fileset_database@stdscr.3x CURS-ENG-A-MAN .\" $Header: regexp.3x,v 72.5 94/11/15 09:56:02 ssa Exp $ .TA r .TH regexp 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME compile(\|), step(\|), advance(\|) \- regular expression compile and match routines .SH SYNOPSIS .C #define INIT .I "declarations" .br .C #define GETC() .I "getc statements" .br .C #define PEEKC() .I "peekc statements" .br .C #define UNGETC(c) .I "ungetc statements" .br .C #define RETURN(pointer) .I "return statements" .br .C #define ERROR(val) .I "error statements" .PP .C "#include " .PP .C "char *compile(" .nf .PD 0 .IP .C "const char *instring," .C "char *expbuf," .C "const char *endbuf," .C "int eof" .PP .C ");" .PD .fi .PP .C "int step(const char *string, const char *expbuf);" .PP .C "int advance(const char *string, const char *expbuf);" .PP .C "extern char *loc1, *loc2, *locs;" .PP .C "extern int circf, sed, nbra;" .SS Remarks Features documented in this manual entry are obsolescent and may be removed in a future .SM HP-UX release. Use of .IR regcomp (3C) functions instead is recommended. .SH DESCRIPTION These functions are general-purpose regular expression matching routines to be used in programs that perform Basic Regular Expression (see .IR regexp (5)) matching. These functions are defined in .RC < regexp.h >. .PP The functions .C step() and .C advance() do pattern matching given a character string and a compiled regular expression as input. .C compile() takes a Basic Regular Expression as input and produces a compiled expression that can be used with .C step() and .CR advance() . .PP The interface to this file is unpleasantly complex. Programs that include this file must have the following five macros declared before the .C #include statement. These macros are used by the .C compile() routine. .TP 15 .C GETC() Return the value of the next byte in the regular expression pattern. Successive calls to .C GETC() should return successive bytes of the regular expression. .TP .C PEEKC() Return the next byte in the regular expression. Successive calls to .C PEEKC() should return the same byte (which should also be the next byte returned by .CR GETC() . .TP .CI UNGETC( c ) Cause the argument .I c to be returned by the next call to .C GETC() (and .CR PEEKC() ). No more than one byte of pushback is ever needed, and this byte is guaranteed to be the last byte read by .CR GETC() . The value of the macro .CI UNGETC( c ) is always ignored. .TP .CI RETURN( pointer ) This macro is used on normal exit of the .C compile() routine. The value of the argument .I pointer is a pointer to the character after the last character of the compiled regular expression. This is useful to programs that must manage memory allocation. .TP .CI ERROR( val ) This is the abnormal return from the .C compile() routine. The argument .I val is an error number (see table below for meanings). This call should never return. .RS .RS .PD 0 .TP 8 .B Error .B Meaning .TP 11 Range endpoint too large. .TP 16 Bad number. .TP 25 ``\f3\e\f2digit\f1'' out of range. .TP 36 Illegal or missing delimiter. .TP 41 No remembered search string. .TP 42 .C \e( \e) imbalance. .TP 43 Too many .CR \e( . .TP 44 More than 2 numbers given in .CR \e{\0\e} . .TP 45 .C } expected after .CR \e . .TP 46 First number exceeds second in .CR \e{\0\e} . .TP 49 .C [ ] imbalance. .TP 50 Regular expression overflow. .RE .RE .PD .PP The syntax of the .C compile() routine is as follows: .IP .CI compile( instring , .CI expbuf , .CI endbuf , .CI eof ) .PP The first parameter .I instring is never used explicitly by the .C compile() routine, but is useful for programs that pass down different pointers to input characters. It is sometimes used in the .C INIT declaration (see below). Programs that call functions to input characters or have characters in an external array can pass down a value of .C ((char *) 0) for this parameter. .PP The next parameter .I expbuf is a character pointer. It points to the location where the compiled regular expression will be placed. .PP The parameter .I endbuf is one more than the highest address where the compiled regular expression can be placed. If the compiled expression cannot fit in .RI ( endbuf \|\(mi\| expbuf ) bytes, a call to .C ERROR(50) is made. .PP The parameter .I eof is the character which marks the end of the regular expression. For example, in .IR ed (1), this character is usually a .CR / . .PP Each program that includes this file must have a .C #define statement for .CR INIT . This definition is placed right after the declaration for the function .C compile() and the opening curly brace .CR { . It is used for dependent declarations and initializations. Most often it is used to set a register variable to point to the beginning of the regular expression so that this register variable can be used in the declarations for .CR GETC() , .CR PEEKC() , and .CR UNGETC() . Otherwise it can be used to declare external variables that might be used by .CR GETC() , .CR PEEKC() , and .CR UNGETC() . See the example below of the declarations taken from .IR grep (1). .PP .C step() also performs actual regular expression matching in this file. The call to .I step is as follows: .IP .CI step( string , .CI expbuf ) .PP The first parameter to .C step() is a pointer to a string of characters to be checked for a match. This string should be null-terminated. .PP The second parameter .I expbuf is the compiled regular expression that was obtained by a call to .CR compile() . .PP .C step() returns non-zero if the given string matches the regular expression, and zero if the expressions do not match. If there is a match, two external character pointers are set as a side effect to the call to .CR step() . The variable set in .C step() is .CR loc1 . This is a pointer to the first character that matched the regular expression. The variable .CR loc2 , which is set by the function .CR advance() , points to the character after the last character that matches the regular expression. Thus, if the regular expression matches the entire line, .C loc1 points to the first character of .I string and .C loc2 points to the null at the end of .IR string . .PP .C step() uses the external variable .CR circf() , which is set by .C compile() if the regular expression begins with .CR ^ . If this is set, .C step() tries to match the regular expression to the beginning of the string only. If more than one regular expression is to be compiled before the first is executed, the value of .I circf should be saved for each compiled expression and .I circf should be set to that saved value before each call to .CR step() . .PP .C advance() is called from .C step() with the same arguments as .CR step() . The purpose of .C step() is to step through the .I string argument and call .C advance() until .C advance() returns non-zero, which indicates a match, or until the end of .I string is reached. To constrain .I string to beginning-of-line in all cases, .C step() need not be called; simply call .CR advance() . .PP When .C advance() encounters a .C * or .C \e{\|\e} sequence in the regular expression, it advances its pointer to the string to be matched as far as possible and recursively calls itself, trying to match the rest of the string to the rest of the regular expression. As long as there is no match, .I advance backs up along the string until it finds a match or reaches the point in the string that initially matched the .C * or .CR \e{\|\e} . It is sometimes desirable to stop this backing up before the initial point in the string is reached. If the external character pointer .C locs is equal to the point in the string at sometime during the backing up process, .C advance() breaks out of the loop that backs up and returns zero. This is used by .IR ed (1) and .IR sed (1) for substitutions done globally (not just the first occurrence, but the whole line) so, for example, expressions such as .C s/y*//g do not loop forever. .PP The additional external variables .C sed and .C nbra are used for special purposes. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collating sequence used in compiling and executing regular expressions. .PP The .C LC_CTYPE category determines the interpretation of text as single and/or multi-byte characters, and the characters matched by character class expressions in regular expressions. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH EXAMPLES The following is an example of how the regular expression macros and calls look from .IR grep (1): .nf .IP .C "#define INIT register char *sp = instring;" .C "#define GETC() (*sp++)" .C "#define PEEKC() (*sp)" .C "#define UNGETC(c) (--sp)" .C "#define RETURN(c) return;" .C "#define ERROR(c) regerr()" .IP .C "#include " \h'.5i'.\|.\|. .C "(void) compile(*argv, expbuf, &expbuf[ESIZE], '\e0');" \h'.5i'.\|.\|. .C "if (step(linebuf, expbuf))" .C " succeed();" .fi .SH AUTHOR .CR regexp() was developed by OSF and HP. .SH SEE ALSO grep(1), regcomp(3C), setlocale(3C), regexp(5). .SH STANDARDS CONFORMANCE .CR advance() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR compile() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc1 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR loc2 ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR locs ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR step() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4compile()\f1 \- regular expression compile routine@@@\f3regexp(3X)\f1 .\" index@\f4step()\f1 \- regular expression string comparison routine@@@\f3regexp(3X)\f1 .\" index@\f4advance()\f1 \- regular expression substring comparison routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1regular expression compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1expression, regular, compile and match routines@@@\f3regexp(3X)\f1 .\" index@\f1compile and match routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1comparison routines for regular expressions@@@\f3regexp(3X)\f1 .\" index@\f1match routines for regular expressions@@@\f3regexp(3X)\f1 .\" .\" toc@\f3regexp(3X)\f1:\0\0\f4compile()\f1, \f4step()\f1, \f4advance()\f1@@@regular expression compile and match routines .\" toc@\f4compile()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4step()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" toc@\f4advance()\f1:\0\0regular expression compile and match routines@@@see \f3regexp(3X)\f1 .\" .\" links@regexp.3x compile.3x .\" links@regexp.3x step.3x .\" links@regexp.3x advance.3x .\" links@regexp.3x INIT.3x .\" links@regexp.3x GETC.3x .\" links@regexp.3x PEEKC.3x .\" links@regexp.3x UNGETC.3x .\" links@regexp.3x RETURN.3x .\" links@regexp.3x ERROR.3x .\" .\" fileset_database@regexp.3x PROGRAMING-MAN .\" $Header: dbm.3x,v 76.1 95/07/05 17:27:37 ssa Exp $ .TA d .TH dbm 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dbminit, fetch, store, delete, firstkey, nextkey, dbmclose \- database subroutines .SH SYNOPSIS .C "#include " .P .C "int dbminit(const char *file);" .P .C "datum fetch(datum key);" .P .C "int store(datum key, datum content);" .P .C "int delete(datum key);" .P .C "datum firstkey(void);" .P .C "datum nextkey(datum key);" .P .C "int dbmclose(void);" .SH DESCRIPTION These functions maintain key/content pairs in a database. They handle very large (a billion blocks (block = 1024 bytes)) databases and can locate a keyed item in one or two file system accesses. .PP .I key and .I content parameters are described by the .C datum type. A .C datum specifies a string of .I dsize bytes pointed to by .I dptr. Arbitrary binary data, as well as normal .SM ASCII strings, are allowed. The database is stored in two files. One file is a directory containing a bit map of keys and has .C .dir as its suffix. The second file contains all data and has .C .pag as its suffix. .PP Before a database can be accessed, it must be opened by .CR dbminit . At the time of this call, the files .IC file .dir and .IC file .pag must exist. (An empty database is created by creating zero-length .C .dir and .C .pag files.) .PP Once open, data stored under a key is accessed by .IC fetch , and data is placed under a key by .IC store . Storing data on an existing key replaces the existing data. A key (and its associated contents) is deleted by .CR delete . A linear pass through all keys in a database can be made, in (apparently) random order by using .C firstkey and .CR nextkey . .C firstkey returns the first key in the database. With any key, .C nextkey returns the next key in the database. The following code can be used to traverse the database: .IP .C "for (key = firstkey(); key.dptr != NULL; key = nextkey(key))" .PP A database can be closed by calling .C dbmclose. A currently open database must be closed before opening a new one. .SH DIAGNOSTICS All functions that return an .C int indicate errors with negative values and success with zero. Functions that return a .C datum indicate errors with a null .IR dptr . .SH WARNINGS The .I dbm functions provided in this library should not be confused in any way with those of a general-purpose database management system such as .SM ALLBASE/HP-UX SQL. These functions .I do not provide for multiple search keys per entry, they .I do not protect against multi-user access (in other words they do not lock records or files), and they .I do not provide the many other useful data base functions that are found in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of data copies that occur upon hash collisions. These functions .I are useful for applications requiring fast lookup of relatively static information that is to be indexed by a single key. .PP The .C .pag file will contain holes so that its apparent size is about four times its actual content. Some older .SM UNIX systems create real file blocks for these holes when touched. These files cannot be copied by normal means (such as .IR cp (1), .IR cat (1), .IR tar (1), or .IR ar (1)) without expansion. .PP .I dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. .PP The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). Moreover, all key/content pairs that hash together must fit on a single block. .C store returns an error if a disk block fills with inseparable data. .PP .C delete does not physically reclaim file space, although it does make it available for reuse. .PP The order of keys presented by .C firstkey and .C nextkey depends on a hashing function, not on anything interesting. .PP A .C store or .C delete during a pass through the keys by .C firstkey and .C nextkey may yield unexpected results. .SH AUTHOR .IR dbm (3X) was developed by the University of California, Berkeley. .SH SEE ALSO ndbm(3X). .\" index@\f4dbminit()\fP \- open a single database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4fetch()\fP \- access data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4store()\fP \- store data under a key (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4delete()\fP \- delete key and data under it (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4firstkey()\fP \- get first key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4nextkey()\fP \- get next key in database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@\f4dbmclose()\fP \- close currently open database (old single-data-base version)@@@\f3dbm(3X)\f1 .\" index@database subroutines (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" index@subroutines, database (old version \- see also \f3ndbm(3X)\f1)@@@\f3dbm(3X)\f1 .\" .\" toc@\f3dbm(3X)\f1:\0\0\f4dbminit()\fP, \f4fetch()\fP, \f4store()\fP, \f4delete()\fP, \f4firstkey()\fP,\n\f4nextkey()\fP, \f4dbmclose()\fP@@@database subroutines .\" toc@\f4dbminit()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4fetch()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4store()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4delete()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4firstkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4nextkey()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" toc@\f4dbmclose()\fP:\0\0database subroutines@@@see \f3dbm(3X)\f1 .\" .\" links@dbm.3x dbminit.3x .\" links@dbm.3x fetch.3x .\" links@dbm.3x store.3x .\" links@dbm.3x delete.3x .\" links@dbm.3x firstkey.3x .\" links@dbm.3x nextkey.3x .\" links@dbm.3x dbmclose.3x .\" .\" fileset_database@dbm.3x PROGRAMING-MAN .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: perror.3c,v 74.1 95/03/23 18:05:29 ssa Exp $ .TA p .TH perror 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME perror(\|), strerror(\|), strerror_r(\|), errno, sys_errlist, sys_nerr \- system error messages .SH SYNOPSIS .C "#include " .PP .C "void perror(const char *s);" .PP .C "char *strerror(int errnum);" .PP .C "int strerror_r(int errnum, char *buffer, int buflen);" .PP .C "extern int errno;" .PP .C "extern char *sys_errlist[\|];" .PP .C "extern int sys_nerr;" .SH DESCRIPTION .CR perror() writes a language-dependent message to the standard error output, describing the last error encountered during a call to a system or library function. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. To be most useful, the argument string should include the name of the program that incurred the error. The error number is taken from the external variable .CR errno , which is set when errors occur but not cleared when non-erroneous calls are made. The contents of the message is identical to those returned by the .CR strerror() function with .CR errno as the argument. If given a .SM NULL string, the .CR perror() function prints only the message and a new-line. .PP To simplify variant formatting of messages, the .CR strerror() function and the .CR sys_errlist array of message strings are provided. The .CR strerror() function maps the error number in .I errnum to a language-dependent error message string and returns a pointer to the string. The message string is returned without a new-line. .CR errno can be used as an index into .CR sys_errlist to get an untranslated message string without the new-line. .CR sys_nerr is the largest message number provided for in the table; it should be checked because new error codes might be added to the system before they are added to the table. .CR strerror() must be used to retrieve messages when translations are desired. .PP .CR strerror_r() is identical to .CR strerror() , except that the result string is passed back in the supplied buffer. A buffer length of 80 is recommended. If an error is detected or the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .SH EXTERNAL INFLUENCES .SS Environment Variables The language of the message returned by .CR strerror() and printed by .CR perror() is specified by the .CR LANG environment variable. If the language-dependent message is not available, or if .CR LANG is not set or is set to the empty string, the default version of the message associated with the "C" language (see .IR lang (5)) is used. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .CR perror() returns no value. .PP If the .I errnum message number is valid, .CR strerror() returns a pointer to a language-dependent message string. The array pointed to should not be modified by the program, and might be overwritten by a subsequent call to the function. If a valid .I errnum message number does not have a corresponding language-dependent message, .CR strerror() uses .I errnum as an index into .CR sys_errlist to get the message string. If the .I errnum message number is invalid, .CR strerror() returns a pointer to a .SM NULL string. .SH WARNINGS The return value for .CR strerror() points to static data whose content is overwritten by each call. .CR strerror() is unsafe for multi-thread applications. .CR strerror_r() is MT-Safe and should be used instead. .br .ne 12v .SH SEE ALSO errno(2), lang(5), environ(5). .SH STANDARDS CONFORMANCE .CR perror() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strerror() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR sys_errlist() ": SVID2, SVID3, XPG2" .PP .CR sys_nerr() ": SVID2, SVID3, XPG2" .\" .\" index@\f4perror()\fP, \f4errno()\fP, \f4sys_errlist()\fP, \f4sys_nerr()\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4errno\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4strerror()\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4sys_errlist\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4sys_nerr\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@system error messages@@@\f3perror(3C)\f1 .\" index@error messages, system@@@\f3perror(3C)\f1 .\" index@messages, system error@@@\f3perror(3C)\f1 .\" .\" toc@\f3perror(3C)\f1:\0\0\f4perror()\fP, \f4errno()\fP, \f4sys_errlist()\f1, \f4sys_nerr()\f1@@@system error messages .\" toc@\f4errno\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4strerror()\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4sys_errlist\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4sys_nerr\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" .\" links@perror.3c strerror.3c .\" links@perror.3c strerror_r.3c .\" links@perror.3c errno.3c .\" links@perror.3c sys_errlist.3c .\" links@perror.3c sys_nerr.3c .\" $Header: perror.3c,v 74.1 95/03/23 18:05:29 ssa Exp $ .TA p .TH perror 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME perror(\|), strerror(\|), strerror_r(\|), errno, sys_errlist, sys_nerr \- system error messages .SH SYNOPSIS .C "#include " .PP .C "void perror(const char *s);" .PP .C "char *strerror(int errnum);" .PP .C "int strerror_r(int errnum, char *buffer, int buflen);" .PP .C "extern int errno;" .PP .C "extern char *sys_errlist[\|];" .PP .C "extern int sys_nerr;" .SH DESCRIPTION .CR perror() writes a language-dependent message to the standard error output, describing the last error encountered during a call to a system or library function. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. To be most useful, the argument string should include the name of the program that incurred the error. The error number is taken from the external variable .CR errno , which is set when errors occur but not cleared when non-erroneous calls are made. The contents of the message is identical to those returned by the .CR strerror() function with .CR errno as the argument. If given a .SM NULL string, the .CR perror() function prints only the message and a new-line. .PP To simplify variant formatting of messages, the .CR strerror() function and the .CR sys_errlist array of message strings are provided. The .CR strerror() function maps the error number in .I errnum to a language-dependent error message string and returns a pointer to the string. The message string is returned without a new-line. .CR errno can be used as an index into .CR sys_errlist to get an untranslated message string without the new-line. .CR sys_nerr is the largest message number provided for in the table; it should be checked because new error codes might be added to the system before they are added to the table. .CR strerror() must be used to retrieve messages when translations are desired. .PP .CR strerror_r() is identical to .CR strerror() , except that the result string is passed back in the supplied buffer. A buffer length of 80 is recommended. If an error is detected or the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .SH EXTERNAL INFLUENCES .SS Environment Variables The language of the message returned by .CR strerror() and printed by .CR perror() is specified by the .CR LANG environment variable. If the language-dependent message is not available, or if .CR LANG is not set or is set to the empty string, the default version of the message associated with the "C" language (see .IR lang (5)) is used. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .CR perror() returns no value. .PP If the .I errnum message number is valid, .CR strerror() returns a pointer to a language-dependent message string. The array pointed to should not be modified by the program, and might be overwritten by a subsequent call to the function. If a valid .I errnum message number does not have a corresponding language-dependent message, .CR strerror() uses .I errnum as an index into .CR sys_errlist to get the message string. If the .I errnum message number is invalid, .CR strerror() returns a pointer to a .SM NULL string. .SH WARNINGS The return value for .CR strerror() points to static data whose content is overwritten by each call. .CR strerror() is unsafe for multi-thread applications. .CR strerror_r() is MT-Safe and should be used instead. .br .ne 12v .SH SEE ALSO errno(2), lang(5), environ(5). .SH STANDARDS CONFORMANCE .CR perror() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strerror() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR sys_errlist() ": SVID2, SVID3, XPG2" .PP .CR sys_nerr() ": SVID2, SVID3, XPG2" .\" .\" index@\f4perror()\fP, \f4errno()\fP, \f4sys_errlist()\fP, \f4sys_nerr()\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4errno\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4strerror()\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4sys_errlist\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4sys_nerr\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@system error messages@@@\f3perror(3C)\f1 .\" index@error messages, system@@@\f3perror(3C)\f1 .\" index@messages, system error@@@\f3perror(3C)\f1 .\" .\" toc@\f3perror(3C)\f1:\0\0\f4perror()\fP, \f4errno()\fP, \f4sys_errlist()\f1, \f4sys_nerr()\f1@@@system error messages .\" toc@\f4errno\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4strerror()\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4sys_errlist\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4sys_nerr\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" .\" links@perror.3c strerror.3c .\" links@perror.3c strerror_r.3c .\" links@perror.3c errno.3c .\" links@perror.3c sys_errlist.3c .\" links@perror.3c sys_nerr.3c .\" $Header: strfmon.3c,v 74.1 95/05/10 22:02:36 ssa Exp $ .TA s .TH strfmon 3C "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strfmon \- convert monetary value to string .SH SYNOPSIS .C "#include " .PP .C "ssize_t strfmon(char *stream, size_t maxsize, const char *format, ...);" .SS Remarks The ANSI C "\c .CR ", ...\$\c" " construct denotes a variable length argument list whose optional [or required] \" EDITOR: make this line fit the specific page members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION The .CR strfmon() function places characters into the array pointed to by .I stream as controlled by the string pointed to by .IR format . No more than .I maxsize bytes are placed into the array. .PP The format is a character string that contains two types of objects: plain characters, which are simply copied to the output stream, and conversion specifications, each of which results in the fetching of zero or more arguments that are converted and formatted. The arguments are of type .CR double , see the .C Conversion Characters section for details. The results are undefined if there are insufficient arguments for the format. If the format is exhausted while arguments remain, the excess arguments are ignored. .PP A conversion specification is the string .PP .nf .C "%[flag...][field_width][#left_precision][.right_precision]" .C " conversion_character" .fi .PP Each element of the sequence is specified as follows: .SS Flags .PP One or more of the following optional flags can be specified to control the conversion: .TP 10 .CI = f An .C = (equal sign) followed by a single character .I f which is used as the numeric fill character. The fill character must be representable in a single byte in order to work with precision and width counts. The default numeric fill character is the space character This flag does not affect field width filling which always uses the space character. This flag is ignored unless a left precision (see below) is specified. .TP .C ^ Do not format the currency amount with grouping characters The default is to insert the grouping characters if defined for the current locale. .TP .C + or ( Specify the style for representing positive and negative currency amounts. Only one of .CR + or .CR ( (plus sign or left parenthesis) may be specified If .CR + is specified, the locale's equivalent of + and - are used (for example, in the .CR en_US.roman8 locale: an empty string if positive and - if negative) If .CR ( is specified, negative amounts are enclosed within parentheses If neither flag is specified, the .CR + style is used. .TP .C ! Suppress the currency symbol from the output conversion. .TP .C - A minus sign specifying the alignment If this flag is present all fields are left-justified (padded to the right) rather than right-justified. .PP .SS Field Width .TP 10 .I w A decimal digit string .I w specifying a minimum field width in bytes in which the result of the conversion is right-justified (or left-justified if the flag - is specified) The default is zero. .PP .SS Left Precision .TP 10 .CI # n A .CR # followed by a decimal digit string .I n specifying a maximum number of digits expected to be formatted to the left of the radix character This option can be used to keep the formatted output from multiple calls to the .I strfmon() aligned in the same columns It can also be used to fill unused positions with a special character as in \f4$***123.45\f1. This option causes an amount to be formatted as if it has the number of digits specified by .I n. If more than .I n digit positions are required, this conversion specification is ignored. Digit positions in excess of those actually required are filled with numeric fill character (see the .CI = f flag above). .IP If grouping has not been suppressed with the .CR ^ flag, and it is defined for the current locale, grouping separators are inserted before the fill characters (if any) are added Grouping separators are not applied to fill characters even if the fill character is a digit. .IP To ensure alignment, any characters appearing before or after the number in the formatted output such as currency or sign symbols are padded as necessary with space characters to make their positive and negative formats an equal length. .PP .SS Right Precision .TP 10 .CI . p A period followed by a decimal digit string .I p specifying the number of digits after the radix character If the value of the right precision .I p is zero, no radix character appears If a right precision is not included, a default specified by the current locale is used The amount being formatted is rounded to the specified number of digits prior to formatting. .PP .SS Conversion Characters .PP The conversion characters and their meanings are: .TP 10 .C i The .CR double argument is formatted according to the locale's international currency format (for example, in the .CR en_US.roman8 locale: .CR "USD 1,234.56" ). .TP .C n The .C double argument is formatted according to the locale's national currency format (for example, in the .CR en_US.roman8 locale: .CR "$1,234.56" ). .TP .C % Convert to a .CR % ; no argument is converted The entire conversion specification must be %%. .SH EXTERNAL INFLUENCES .SS Locale The LC_MONETARY category of the program's locale affects the behavior of this function including the monetary radix character (which may be different from the numeric radix character affected by the LC_NUMERIC category), the grouping separator, the currency symbols and formats. .SH RETURN VALUE If the total number of resulting bytes including the terminating null byte is not more than .I maxsize, the .I strfmon() function returns the number of bytes placed into the array pointed to by .I s, not including the terminating null byte Otherwise, -1 is returned, the contents of the array are indeterminate, and .I errno is set to indicate the error. .SH ERRORS The .I strfmon() function will fail if: .TP 15 [E2BIG] Conversion stopped due to lack of space in the buffer. .RE .SH EXAMPLES The following program segment formats the monetary value .CR "-4321.123" using the .CR en_US.roman8 locale with a left precision of .CR 5 and .CR * as the fill character. .nf .IP .ift .ft 4 char string[31]; double amt = -4321.123; setlocale(LC_MONETARY, "en_US.roman8"); strfmon(string, 31, "The amount is %=*#5n.", amt); .ift .ft .ps .fi .PP The .I string array will contain: .nf .IP .ift .ft 4 The amount is -$*4,321.12. .ift .ft .ps .fi .ifn .PP .ift .bp As an other example, given the locale of .C en_US.roman8 and the values .CR 123.45 , .CR "-123.45" and .CR "3456.781" : .PP .TS lll. _ Conversion Output Comments Specification _ %n \f4$123.45\f1 default formatting \f4-$123.45\f1 \f4$3,456.78\f1 _ .T& lnl. %11n \f4$123.45\f1 right align within an 11 character field \f4-$123.45\f1 \f4$3,456.78\f1 _ %#5n \f4$ 123.45\f1 align columns for values up to 99,999 \f4-$ 123.45\f1 \f4$ 3,456.78\f1 _ %=*#5n \f4$***123.45\f1 specify a fill character \f4-$***123.45\f1 \f4$*3,456.78\f1 _ %=0#5n \f4$000123.45\f1 fill characters do not use grouping \f4-$000123.45\f1 even if the fill character is a digit \f4$03,456.78\f1 _ %^#5n \f4$ 123.45\f1 disable the grouping separator \f4-$ 123.45\f1 \f4$ 3456.78\f1 _ %^#5.0n \f4$ 123\f1 round off to whole units \f4-$ 123\f1 \f4$ 3457\f1 _ %^#5.4n \f4$ 123.4500\f1 increase the precision \f4-$ 123.4500\f1 \f4$ 3456.7810\f1 _ %(#5n \f4$ 123.45\f1 use an alternative positive/negative style \f4($ 123.45)\f1 \f4$ 3,456.78\f1 _ %!(#5n \f4123.45\f1 disable the currency symbol \f4( 123.45)\f1 \f43,456.78\f1 _ .TE .SH AUTHOR .CR strfmon was developed by HP. .SH SEE ALSO localeconv(3C). .SH STANDARDS COMPLIANCE .CR strfmon: XPG4 .\" .\" toc@\f3strfmon(3C)\f1:\0\0\f4strfmon\f1@@@convert monetary value to string .\" .\" index@\f4strfmon\f1convert monetary value to string@@@\f3strfmon(3C)\f1 .\" .\" index@monetary value to string, convert@@@\f3strfmon(3C)\f1 .\" index@string, convert monetary value to@@@\f3strfmon(3C)\f1 .\" $Header: strftime.3c,v 72.7 94/11/15 09:56:25 ssa Exp $ .\" EDITOR'S NOTE: SEE date.1 FOR FIXUPS AND FORMATTING -allanp 940208 .TA s .TH strftime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strftime() \- convert date and time to string .SH SYNOPSIS .C "#include " .nf .PP .PD 0 .C "size_t strftime(" .C " char *s," .C " size_t maxsize," .C " const char *format," .C " const struct tm *timeptr" .C ");" .PD .fi .SH DESCRIPTION The .CR strftime() function converts the contents of a .CR tm structure (see .IR ctime (3C)) to a formatted date and time string. .PP .CR strftime() places characters into the array pointed to by .IR s as controlled by the string pointed to by .IR format . The .IR format string consists of zero or more directives and ordinary characters. A directive consists of a .CR % character, an optional field width and precision specification, and a terminating character that determines the directive's behavior. All ordinary characters (including the terminating null character are copied unchanged into the array. No more than .IR maxsize characters are placed into the array. Each directive is replaced by the appropriate characters as described in the following list. The appropriate characters are determined by the program's locale, by the values contained in the structure pointed to by .IR timeptr , and by the .CR TZ environment variable (see External Influences below). .SS Directives The following directives, shown without the optional field width and precision specification, are replaced by the indicated characters: .RS .TP 10 .CR %a Locale's abbreviated weekday name. .PD 0 .TP .CR %A Locale's full weekday name. .TP .CR %b Locale's abbreviated month name. .TP .CR %B Locale's full month name. .TP .CR %c Locale's appropriate date and time representation. .TP .CR %C The century number (the year divided by 100 and truncated to an integer) as a decimal number [00-99]. .TP .CR %d Day of the month as a decimal number [01,31]. .TP .CR %D Equivalent to the directive string .I %m/%d/%y. .TP .CR %e Day of the month as a decimal number [1,31]; a single digit is preceded by a space. .TP .CR %h Equivalent to %b. .TP .CR %H Hour (24-hour clock) as a decimal number [00,23]. .TP .CR %I Hour (12-hour clock) as a decimal number [01,12]. .TP .CR %j Day of the year as a decimal number [001,366]. .TP .CR %m Month as a decimal number [01,12]. .TP .CR %M Minute as a decimal number [00,59]. .TP .CR %n The New-line character. .TP .CR %p Locale's equivalent of either .SM AM or .SM PM. .TP .CR %r The time in AM and PM notation; in the POSIX locale this is equivalent to .I %I:%M:%S %p. .TP .CR %R The time in 24 hour notation (%H:%M). .TP .CR %S Second as a decimal number [00,61]. .TP .CR %t The Tab character. .TP .CR %T The time in hours, minutes, and seconds (%H:%M:%S). .TP .CR %u The weekday as a decimal number [1(Monday),7]. .TP .CR %U Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. .TP .CR %V The week number of the year (Monday as the first day of the week) as a decimal number [01,53]. If the week containing January 1st has four or more days in the new year, then it is considered week 1; otherwise, it is week 53 of the previous year, and the next week is week 1. .TP .CR %w Weekday as a decimal number [0(Sunday),6]. .TP .CR %W Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0. .TP .CR %x Locale's appropriate date representation. .TP .CR %X Locale's appropriate time representation. .TP .CR %y Year without century as a decimal number [00,99]. .TP .CR %Y Year with century as a decimal number. .TP .CR %Z Time zone name (or by no characters if no time zone exists). .TP .CR %% The percent (%) character. .RE .PD .PP The following directives are provided for backward compatibility with the directives supported by .IR date (1) and the .IR ctime (3C) functions. These directives may be removed in a future release. It is recommended that the directives above be used in preference to those below. .RS .TP 10 .CR %E Locale's combined Emperor/Era name and year (use .CR %EC%Ey instead). .TP .CR %F Locale's full month name (use .CR %B instead). .TP .CR %N Locale's Emperor/Era name (use .CR %EC instead). .TP .CR %o Locale's Emperor/Era year (use .CR %Ey instead). .TP .CR %z Time zone name (or by no characters if no time zone exists) (use .CR %Z instead). .RE .PD .PP If a directive is not one of the above, the behavior is undefined. .SS Modified Conversion Specifiers Some conversion specifiers can be modified by the E or O modifer characters to indicate that an alternative format or specification should be used rather than the one normally used by the unmodified conversion specifier. If the alternative format or specification does not exist for the current locale, the behavior will be as if the unmodified conversion specification were used. Alternative numeric symbols refers to those symbols defined by the .CR ALT_DIGIT .IR (see langinfo(5)) in the locale. .RS .TP 10 .CR %Ec The locales alternative appropriate date and time representation. .TP .CR %EC The name of the base year (period/Emperor/Era) in the locale's alternative representation. .TP .CR %Ex The locale's alternative date representation .TP .CR %EX The locale's alternative time representation. .TP .CR %Ey The offset from %EC (year only) in the locale's alternative representation. .TP .CR %EY The full alternative year representation. .TP .CR %Od The day of the month, using the locale's alternative numeric symbols, filled as needed with leading zeros if there is any alternative symbol for zero, otherwise with leading spaces. .TP .CR %Oe the day of the month, using the locale's alternative numeric symbols, filled as needed with leading spaces. .TP .CR %OH The hour (24-hour clock) using the locale's alternative numeric symbols. .TP .CR %OI The hour (12-hour clock) using the locale's alternative numeric symbols. .TP .CR %Om The month using the locale's alternative numeric symbols. .TP .CR %OM The minutes using the locale's alternative numeric symbols. .TP .CR %OS The seconds using the locale's alternative numeric symbols. .TP .CR %Ou The weekday as a number in the locale's alternative representation (Monday=1). .TP .CR %OU The week number of the year (Sunday as the first day of the week, rules corresponding to %U) using the locale's alternative numeric symbols. .TP .CR %OV The week number of the year (Monday as the first day of the week, rules corresponding to %V) using tht locale's alternative numeric symbols. .TP .CR %Ow The number of the weekday (Sunday=0) using the locale's alternative numeric symbols. .TP .CR %OW The week number of the year (Monday as the first day of the week) using the locale's alternative numeric symbols. .TP .CR %Oy The year (offset from %C) in the locale's alternative representation and using the locale's alternative symbols. .RE .TP .SS Field Width and Precision An optional field width and precision specification can immediately follow the initial .CR % of a directive in the following order: .TP 15 .RC [ - \(or 0 ]\f2w\fP The decimal digit string .IR w specifies a minimum field width in which the result of the conversion is right- or left-justified. It is right-justified (with space padding) by default. If the optional flag .CR - is specified, it is left-justified with space padding on the right. If the optional flag .CR 0 is specified, it is right-justified and padded with zeros on the left. .TP .CI . p The decimal digit string .IR p specifies the minimum number of digits to appear for the .CR d , .CR H , .CR I , .CR j , .CR m , .CR M , .CR o , .CR S , .CR U , .CR w , .CR W , .CR y and .CR Y directives, and the maximum number of bytes to be used from the .CR a , .CR A , .CR b , .CR B , .CR c , .CR D , .CR E , .CR F , .CR h , .CR n , .CR N , .CR p , .CR r , .CR t , .CR T , .CR x , .CR X , .CR z , .CR Z , and .CR % directives. In the first case, if a directive supplies fewer digits than specified by the precision, it will be expanded with leading zeros. In the second case, if a directive supplies more bytes than specified by the precision, excess bytes will truncated on the right. .PP If no field width or precision is specified for a .CR d , .CR H , .CR I , .CR m , .CR M , .CR S , .CR U , .CR W , .CR y , or .CR j directive, a default of .CR .2 is used for all but .CR j for which .CR .3 is used. .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_TIME category determines the characters to be substituted for those directives described above as being from the locale. .PP The .CR LC_CTYPE category determines the interpretation of the bytes within .IR format as single and/or multi-byte characters. .PP The .CR LC_NUMERIC category determines the characters used to form numbers for those directives that produce numbers in the output. If .CR ALT_DIGITS (see .IR langinfo (5)) is defined for the locale, the characters so specified are used in place of the default .SM ASCII characters. If both .CR ALT_DIGITS and .CR ALT_DIGIT is defined for the locale, .CR ALT_DIGITS will take precedence over .CR ALT_DIGIT. .SS Environment Variables .CR TZ determines the time zone name substituted for the .CR %Z and .CR %z directives. The time zone name is determined by calling the function .CR tzset() which sets the external variable .CR tzname (see .IR ctime (3C)). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE If the total number of resulting bytes including the terminating null byte is not more than .IR maxsize , .CR strftime() returns the number of bytes placed into the array pointed to by .IR s , not including the terminating null byte. Otherwise, zero is returned and the contents of the array are indeterminate. .SH EXAMPLES If the .IR timeptr argument contains the following values: .nf .IP .C "timeptr->tm_sec = 4;" .C "timeptr->tm_min = 9;" .C "timeptr->tm_hour = 15;" .C "timeptr->tm_mday = 4;" .C "timeptr->tm_mon = 6;" .C "timeptr->tm_year = 88;" .C "timeptr->tm_wday = 1;" .C "timeptr->tm_yday = 185;" .C "timeptr->tm_isdst = 1;" .fi .PP the following combinations of the .CR LC_TIME category and format strings produce the indicated output: .RS .PP .TS lf4 l l lf4 lf4 lf4 . LC_TIME Format String Output _ en_US.roman8 %x Mon, Jul 4, 1988 de_De.roman8 %x Mo., 4. Juli 1988 en_US.roman8 %X 03:09:04 PM fr_FR.roman8 %X 15h09 04 \f2any\f1* %H:%M:%S 15:09:04 \f2any\f1* %.1H:%.1M:%.1S 15:9:4 \f2any\f1* %2.1H:%-3M:%03.1S 15:9 :004 .TE .RE .PP * The directives used in these examples are not affected by the .CR LC_TIME category of the locale. .SH WARNINGS If the arguments .IR s and .IR format are defined such that they overlap, the behavior is undefined. .PP The function .CR tzset() is called upon every invocation of .CR strftime() (whether or not the time zone name is copied to the output array). .PP The range of values for .CR %S ([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the system does not accumulate leap seconds and the .CR tm structure generated by the functions .CR localtime() and .CR gmtime() (see .IR ctime (3C)) never reflects any leap seconds. .PP Results are undefined if values contained in the structure pointed to by .IR timeptr exceed the ranges defined for the .CR tm structure (see .IR ctime (3C)) or are not consistent (such as if the .CR tm_yday element is set to 0, indicating the first day of January, while the .CR tm_mon element is set to 11, indicating a day in December). .SH AUTHOR .CR strftime() was developed by HP. .SH SEE ALSO date(1), ctime(3C), getdate(3C), setlocale(3C), environ(5), hpnls(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR strftime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4strftime()\f1 \- convert date and time to string@@@\f3strftime(3C)\f1 .\" index@convert date and time to string@@@\f3strftime(3C)\f1 .\" index@date and time, convert to string@@@\f3strftime(3C)\f1 .\" index@time and date, convert to string@@@\f3strftime(3C)\f1 .\" index@string, convert date and time to@@@\f3strftime(3C)\f1 .\" .\" toc@\f3strftime(3C)\f1:\0\0\f4strftime()\f1@@@convert date and time to string .\" .\" fileset_database@strftime.3c PROG-AUX-MAN .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: strord.3c,v 72.4 94/11/30 15:47:06 ssa Exp $ .TA s .TH strord 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strord \- convert string data order .SH SYNOPSIS .C "#include " .PP .C "char *strord(char *s1, const char *s2, nl_mode m);" .SH DESCRIPTION The text orientation (mode) of a file can be right-to-left (non-Latin) or left-to-right (Latin). This text orientation can affect the way data is arranged in the file. The data arrangements that result are called screen order and keyboard order (see .IR hpnls (5) for more details). .PP .C strord() converts the order of characters in .I s2 from screen to keyboard order or vice versa and places the result in .IR s1 . The arguments .I s1 and .I s2 point to strings (arrays of characters terminated by a null character). .C strord() returns .IR s1 . .PP .C strord() performs the conversion based on mode information indicated by the argument .IR m . The argument .I m is of type .I nl_mode found in the header file .RC < nl_types.h >. The mode argument can have two possible values: .C NL_LATIN and .CR NL_NONLATIN . .PP If the mode argument is .CR NL_LATIN , the text orientation is left-to-right, and all non-Latin sub-strings are reversed. Non-Latin sub-strings are any number of contiguous right-to-left language characters. Non-Latin sub-strings are delimited by .SM ASCII characters. .PP Similarly, if the mode argument is .CR NL_NONLATIN , the text orientation is right-to-left and all Latin sub-strings are reversed. Latin sub-strings are any number of contiguous printable .SM ASCII characters. Latin sub-strings are delimited by right-to-left language characters and .SM ASCII control codes. .PP Some right-to-left languages have a duplicate set of digits called alternative numbers. Alternative numbers always have a left-to-right orientation. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines whether a right-to-left language has alternative numbers. .SS International Code Set Support Single-byte character code sets are supported. .SH WARNINGS .C strord() does not check for overflow of the array pointed to by .IR s1 . .SH AUTHOR .C strord() was developed by HP. .SH SEE ALSO setlocale(3c), hpnls(5), environ(5), forder(1), nljust(1). .\" index@\f4strord()\fP \- convert string data order@@@\f3strord(3C)\f1 .\" index@convert string data order@@@\f3strord(3C)\f1 .\" index@string data order, convert@@@\f3strord(3C)\f1 .\" index@data order, convert string@@@\f3strord(3C)\f1 .\" index@order of data, convert string@@@\f3strord(3C)\f1 .\" .\" toc@\f3strord(3C)\f1:\0\0\f4strord()\fP@@@convert string data order .\" .\" fileset_database@strord.3c PROGRAMING-MAN .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: strptime.3c,v 72.5 94/10/20 10:53:02 ssa Exp $ .TA s .TH strptime 3C "" "" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strptime \- date and time conversion .SH SYNOPSIS .C "#include " .PP .C "char *strptime(const char *buf, const char *format, struct tm *tm);" .SH DESCRIPTION The .I strptime() function converts the character string pointed to by .I buf to values which are stored in the .C tm structure pointed to by .I tm, using the format specified by .I format. .PP The .I format is composed of zero or more directives. Each directive is composed of one of the following: one or more white-space characters (as specified by the .I isspace() function); an ordinary character (neither % nor a white-space character); or a conversion specification. Each conversion specification is composed of a % character followed by a conversion character which specifies the replacement required. There must be white-space or other non-alphanumeric characters between any two conversion specifications. The following conversion specifications are supported: .PP .RS .TP 8 .C %a is the day of week, using the locale's weekday names; either the abbreviated or full name may be specified. .TP .C %A is the same as %a. .TP .C %b is the month, using the locale's month names; either the abbreviated or full name may be specified. .TP .C %B is the same as %b. .TP .C %c is the date and time, using locale's date and time format (for example, as %x %X). .TP .C %C is the century number [0,99]; leading zeros are permitted but not required. .TP .C %d is the day of month [1,31]; leading zeros are permitted but not required. .TP .C %D is the date as %m/%d/%y. .TP .C %e is the same as %d. .TP .C %h is the same as %b. .TP .C %H is the hour (24-hour clock) [0,23]; leading zeros are permitted but not required. .TP .C %I is the hour (12-hour clock) [1,12]; leading zeros are permitted but not required. .TP .C %j is the day number of the year [1,366]; leading zeros are permitted but not required. .TP .C %m is the month number [1,12]; leading zeros are permitted but not required. .TP .C %M is the minute [0,59]; leading zeros are permitted but not required. .TP .C %n is any white-space. .TP .C %p is the locale's equivalent of a.m or p.m.. .TP .C %r is the time as %I:%M:%S %p. .TP .C %R is the time as %H:%M. .TP .C %S is the seconds [0,61]; leading zeros are permitted but not required. .TP .C %t is any white-space. .TP .C %T is the time as %H:%M:%S. .TP .C %U is the week number of the year (Sunday as the first day of the week) as a decimal number [0,53]; leading zeros are permitted but not required. All days in a year preceding the first Sunday are considered to be in week 0. .TP .C %w is the weekday as a decimal number [0,6], with 0 representing Sunday; leading zeros are permitted but not required. .TP .C %W is the week number of the year (Monday as the first day of the week) as a decimal number [0,53]; leading zeros are permitted but not required. All days in a year preceding the first Monday are considered to be in week 0. .TP .C %x is the date, using the locale's date format. .TP .C %X is the time, using the locale's time format. .TP .C %y is the year within the century [0,99]; leading zeros are permitted but not required. .TP .C %Y is the year, including the century (for example, 1992). .TP .C %% is replaced by %. .PP .RE .SS Modified Directives .PP Some directives can be modified by the E and O modifier characters to indicate that an alternative format or specification should be used rather than the one normally used by the unmodified directive. If the alternative format or specification does not exist in the current locale, the behavior will be as if the unmodified directive were used. .PP .RS .TP .C %Ec is the locale's alternative appropriate date and time representation. .TP .C %EC is the name of the base year (period) in the locale's alternative representation. .TP .C %Ex is the locale's alternative date representation. .TP .C %EX is the locale's alternative time representation. .TP .C %Ey is the offset from %EC (year only) in the locale's alternative representation. .TP .C %EY is the full alternative yeaqr representation. .TP .C %Od is the day of the month using the locale's alternative numeric symbols; leading zeros are permitted by not required. .TP .C %Oe is the same is %Od. .TP .C %OH is the hour (24-hour clock) using the locale's alternative numeric symbols. .TP .C %OI is the hour (12-hour clock) using the locale's alternative numeric symbols. .TP .C %Om is the month using the locale's alternative numeric symbols. .TP .C %OM is the minutes using the locale's alternative numeric symbols. .TP .C %OS is the seconds using the locale's alternative numeric symbols. .TP .C %OU is the week number of the year (Sunday as the first day of the week) using the locale's' alternative numeric symbols. .TP .C %Ow is the number of the weekday (Sunday=0) using the locale's alternative numeric symbols. .TP .C %OW is the week number of the year (Monday as the first day of the week) using the locale's alternative numeric symbols. .TP .C %Oy is the year (offset from %C) in the locale's alternative representation and using the locale's alternative numeric symbols. .PP .RE A directive composed of white-space characters is executed by scanning input up to the first character that is not white-space (which remains unscanned), or until no more characters can be scanned. .PP A directive that is an ordinary character is executed by scanning the next character from the buffer. If the character scanned from the buffer differs from the one comprising the directive, the directive fails, and the differing and subsequent characters remain unscanned. .PP A series of directives composed of .CR %n , .CR %t , white-space characters or any combination thereof is executed by scanning up to the first character that is not white space (which remains unscanned), or until no more characters can be scanned. .PP Any other conversion specification is executed by scanning characters until a character matching the next directive is scanned, or until no more characters can be scanned. These characters, except the one matching the next directive, are then compared to the locale values associated with the conversion specifier. If a match is found, values for the appropriate .C tm structure members are set to values corresponding to the locale information. Case is ignored when matching items in .I buf such as month or weekday names. If no match is found, .I strptime() fails and no more characters are scanned. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category may define the slternative symbols .I (alt_digit -- see localedef(4)) used by the .I %O modifier. The .I alt_digit definition has precedence over .I alt_digits (LC_TIME). Support for .I alt_digit may be removed in a future release of HP-UX. .PP The .C LC_TIME category determines the characters to be interpreted for those directives described above as being from the locale. .PP The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .PP .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE Upon successful completion, .I strptime() returns a pointer to the character following the last character parsed. Otherwise, a null pointer is returned. .SH EXAMPLES The following program segment uses .I strptime() to convert the string (first argument) to values according to the format specified in the second argument. .nf .IP .ift .ft 4 .ps +1 struct tm t; .ift .sp .5v .ifn .sp setlocale(LC_TIME, "en_US.iso88591"); strptime("1:04:23 PM on 10/6/92", "%I:%M:%S %p on %D", &t); .ift .ft .ps .fi .PP The converted value is stored in the structure t as follows: .PP .nf .IP .ift .ft 4 .ps +1 t.tm_sec = 23 t.tm_min = 4 t.tm_hour = 13 t.tm_mday = 6 t.tm_mon = 9 t.tm_year = 92 t.tm_wday = 2 t.tm_yday = 279 t.tm_isdst = 1 .ift .ft .ps .fi .PP .SH AUTHOR .C strptime() was developed by OSF and HP. .SH SEE ALSO scanf(3S), strftime(3C), getdate(3C), ctime(3C), setlocale(3C). .SH STANDARDS COMPLIANCE .CR strptime ": XPG4" .\" .\" .\" toc@\f3strptime(3C)\f1:\0\0\f4strptime\f1@@@date and time conversion .\" .\" index@\f4strptime\f1date and time conversion@@@\f3strptime(3C)\f1 .\" .\" index@\f1time and date conversion@@@\f3strptime(3C)\f1 .\" index@\f1conversion, date and time@@@\f3strptime(3C)\f1 .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: strtoacl.3c,v 78.1 95/12/20 11:16:24 ssa Exp $ .TA s .TH strtoacl 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strtoacl(\|), strtoacl_r(\|), strtoaclpatt(\|), strtoaclpatt_r(\|), aclentrystart[\|] \- convert string form to access control list (\s-1ACL\s0) structure .SH SYNOPSIS .C "#include " .PP .C "int strtoacl(" .nf .PD 0 .IP .C "const char *string," .C "int nentries," .C "int maxentries," .C "struct acl_entry *acl," .C "uid_t fuid," .C "gid_t fgid);" .PD .PP .C "int strtoacl_r(" .nf .PD 0 .IP .C "const char *string," .C "int nentries," .C "int maxentries," .C "struct acl_entry *acl," .C "uid_t fuid," .C "gid_t fgid," .C "char *entrystart[]);" .PD .PP .C "int strtoaclpatt(" .PD 0 .IP .C "const char *string," .C "int maxentries," .C "struct acl_entry_patt *acl);" .PD .PP .C "int strtoaclpatt_r(" .PD 0 .IP .C "const char *string," .C "int maxentries," .C "struct acl_entry_patt *acl" .C "char *entrystart[]);" .PD .fi .SH DESCRIPTION .CR strtoacl() converts an access control list from exact symbolic (string) representation to structure form. It parses the input string and verifies its validity. Optionally it applies the entries in the string as a series of changes to an existing ACL. .PP .CR strtoaclpatt() converts an access control list pattern from symbolic (string) representation to structure form. It parses the input string and verifies its validity. .PP The external array .CR aclentrystart[] , only valid until the next call of either routine, is useful for error reporting. See ERRORS below. .PP The ``operator'' and ``short'' symbolic forms of ACLs and ACL patterns (described in .IR acl (5)) are acceptable as input strings. If the first non-whitespace character in .I string is .CR ( , the ACL or ACL pattern in .I string must be in short form. Otherwise operator form is assumed. .PP .CR strtoacl() takes a pointer to the string to be converted, and a pointer to the first element of an array of ACL entries .RC ( acl[] ) initially containing the indicated number .RI ( nentries ) of valid entries (zero or more). This array can grow to the indicated number of entries .RI ( maxentries ). .CR strtoacl() also takes file user ID .RI ( fuid ) and group ID .RI ( fgid ) values to substitute for .CR "@" characters in .I string and returns the resulting number of entries in .CR acl[] . .PP Redundant entries (identical user ID and group ID values after processing .CR "@" characters) are combined, so that .CR acl[] contains unique entries in the order encountered. If a new entry is mentioned, it is added to the end of the .CR acl array. .SS strtoaclpatt(\|) .CR strtoaclpatt() differs from .CR strtoacl() because it processes an ACL pattern instead of an ACL. Since modification of an existing initial ACL is not useful, it is not supported. .PP Entries with matching user and group ID values are not combined. Each entry input yields one entry in the returned array. .PP The .CR "@" character for user and group IDs (see .IR acl (5)) is converted to special values (\c .CR ACL_FILEOWNER or .CR ACL_FILEGROUP , respectively, defined in .RC < acllib.h >), not to specific user or group names provided by the caller. Thus, .CR strtoaclpatt() need not be called to reparse the ACL pattern for each file, but the caller must handle the special values when comparing an ACL pattern to an ACL. .PP Wildcard user names, group names, and mode values are supported, as are absent mode parts; see .IR acl (5). .PP .CR strtoaclpatt() returns a different structure than .CR strtoacl() . The .I acl_entry_patt structure contains .I onmode and .I offmode masks rather than a single .I mode value. .PP In operator form input, operators have a different effect on .CR strtoaclpatt() : .RS .TP 5 .CR = Sets bits in both the .I onmode and .I offmode fields appropriately, replacing existing bits in the entry, including any set by earlier operators. .TP .CR + Sets bits in .I onmode and clears the same bits in .IR offmode . .TP .CR \- Sets bits in .I offmode and clears the same bits in .IR onmode . .RE .IP In short form input, the mode is treated like the .CR = operator in operator form. .PP For both routines, a non-specific user or group ID of .CR % is converted to .CR ACL_NSUSER or .CR ACL_NSGROUP , respectively. For .CR strtoaclpatt() only, a wildcard user or group ID of .CR * is converted to .CR ACL_ANYUSER or .CR ACL_ANYGROUP , respectively. The values are defined in .RC < acllib.h >. .PP Entries can appear in .I string in any order. .I string can contain redundant entries, and in operator form only, redundant .CR + and .CR \- operators for ACL entry mode modifications (in exact form) or mode bit inclusions/exclusions (in patterns). Entries or modifications are applied left to right. .SS Suggested Use To build a new ACL (ACL pattern) array using .CR strtoacl() .RC ( strtoaclpatt() ), define .CR acl[] with as many entries as desired. Pass it to .CR strtoacl() .RC ( strtoaclpatt() ) with .I nentries set to zero .RC ( strtoacl() only) and .I maxentries set to the number of elements in .CR acl[] . .PP To have .CR strtoacl() modify a file's existing ACL, define .CR acl[] with the maximum possible number of entries .RC ( NACLENTRIES ; see .RC < sys/acl.h >). Call .CR getacl() (see .IR getacl (2)) to read the file's ACL and .CR stat() (see .IR stat (2)) to get the file's owner and group IDs. Then pass the current number of entries, the current ACL, and the ID values to .CR strtoacl() with .I maxentries set to .CR NACLENTRIES . .PP If .CR strtoacl() succeeds, the resulting ACL can be passed safely to .CR setacl() (see .IR setacl (2)) because all redundancies (if any) have been resolved. However, note that since neither .CR strtoacl() nor .CR strtoaclpatt() validate user and group ID values, if the values are not acceptable to the system, .CR setacl() fails. .SS Performance Trick Normally .CR strtoacl() replaces user and group names of .CR "@" with specific user and group ID values, and also combines redundant entries. Therefore, calling .CR stat() and .CR strtoacl() for each of a series of files to which an ACL is being applied is simplest, although time consuming. .PP If .I string contains no .CR "@" character, or if the caller merely wants to compare one ACL against another (and will handle the special case itself), it is sufficient to call .CR strtoacl() once, and pointless to call .CR stat() for each file. To determine this, call .CR strtoacl() the first time with .I fuid set to .CR ACL_FILEOWNER and .I fgid set to .CR ACL_FILEGROUP . Repeated calls with file-specific .I fuid and .I fgid values are needed only if the special values of .I fuid and .I fgid appear in .CR acl[] and the caller needs an exact ACL to set on each file; see EXAMPLES below. .PP If .CR "@" appears in .I string and .CR acl[] will be used later for a call to .CR setacl() , it is necessary to call .CR strtoacl() again to reparse the ACL string for each file. It is possible that not all redundant entries were combined the first time because the .CR "@" names were not resolved to specific IDs. This also complicates comparisons between two ACLs. Furthermore, the caller cannot do the combining later because operator information from operator form input might be lost. .SS Reentrant Interfaces .CR strtoacl_r() and .CR strtoaclpatt_r() require an extra parameter, .IR entrystart , which is used for error reporting. .I entrystart is used in the same way as .CR strtoacl() and .CR strtoaclpatt() use the global array .CR aclentrystart[] . .PP A size of .CR NACLENTRIES + 1 is recommended for the array .IR entrystart . .SH RETURN VALUE If .CR strtoacl() .RC ( strtoaclpatt() ) succeeds, it returns the number of entries in the resulting ACL (ACL pattern), always equal to or greater than .I nentries (zero). .PP .CR strtoaclpatt() also sets values in global array .CR aclentrystart[] to point to the start of each pattern entry it parsed in .IR string , in some cases including leading or trailing whitespace. It only sets a number of pointers equal to its return value plus one (never more than .CR NACLENTRIES + 1). The last valid element points to the null character at the end of .IR string . After calling .CR strtoaclpatt() , an entry pattern's corresponding input string can be used by the caller for error reporting by (temporarily) putting a null at the start of the next entry pattern in .IR string . .SH ERRORS If an error occurs, .CR strtoacl() and .CR strtoaclpatt() return a negative value and the content of .CR acl is undefined (was probably altered). To help with error reporting in this case, .CR aclentrystart[0] and .CR aclentrystart[1] are set to point to the start of the current and next entries, respectively, being parsed when the error occurred. If the current entry does not start with .CR ( , .CR aclentrystart[1] points to the next null character or comma at or after .CR aclentrystart[0] . Otherwise, it points to the next null, or to the character following the next .CR ) . .PP The following values are returned in case of error: .RS .TP 5 \-1 Syntax error: entry doesn't start with .CR ( as expected in short form. .TP \-2 Syntax error: entry doesn't end with .CR ) as expected in short form. .TP \-3 Syntax error: user name is not terminated by a dot. .TP \-4 .RC ( strtoacl() only) Syntax error: group name is not terminated by an operator in operator-form input or a comma in short-form input. .TP \-5 Syntax error: user name is null. .TP \-6 Syntax error: group name is null. .TP \-7 Invalid user name (not found in .CR /etc/passwd file and not a valid number). .TP \-8 Invalid group name (not found in .CR /etc/group file and not a valid number). .TP \-9 Syntax error: invalid mode character, other than .CR 0 ".." 7 , .CR r , .CR w , .CR x , .CR - (allowed in short form only), .CR * (allowed in patterns only), .CR , (to end an entry in operator form), or .CR ) (to end an entry in short form). Or, .CR 0 ".." 7 or .CR * is followed by other mode characters. .TP \-10 The resulting ACL would have more than .I maxentries entries. .RE .SH EXAMPLES The following code fragment converts an ACL from a string to an array of entries using an .I fuid of 103 for the file's owner and .I fgid of 45 for the file's group. .nf .IP .CR #include .IP .CR int nentries; .CR struct acl_entry acl [NACLENTRIES]; .IP .CR "if ((nentries = strtoacl (string, 0, NACLENTRIES, acl, 103, 45)) < 0)" .CR " error (...);" .fi .PP The following code gets the ACL, .IR fuid , and .I fgid for file .CR ../myfile , modifies the ACL using a description string, and changes the ACL on file .CR ../myfile2 to be the new version. .nf .IP .CR #include .CR #include .CR #include .IP .CR "struct stat statbuf;" .CR "int nentries;" .CR "struct acl_entry acl [NACLENTRIES];" .IP .ift .ft 4 .ifn .ft 3 .ps +1 if (stat ("../myfile", & statbuf) < 0) .ft .ps .CR " error (...);" .IP .ift .ft 4 .ifn .ft 3 .ps +1 if ((nentries = getacl ("../myfile", NACLENTRIES, acl)) < 0) .ft .ps .CR " error (...);" .IP .CR "if ((nentries = strtoacl (string, nentries, NACLENTRIES, acl, .CR " statbuf.st_uid, statbuf.st_gid)) < 0)" .CR { .CR " error (...);" .CR } .IP .ift .ft 4 .ifn .ft 3 .ps +1 if (setacl ("../myfile2", nentries, acl) < 0) .ft .ps .CR " error (...);" .fi .PP The following code fragment calls .CR strtoacl() with special values of .I fuid and .IR fgid , then checks to see if they show up in .CR acl[] . .nf .IP .CR #include .IP .CR "int perfile = 0; /* need to stat() and reparse per file? */" .CR "int entry;" .IP .CR "if ((nentries = strtoacl (string, 0, NACLENTRIES, acl," .CR " ACL_FILEOWNER, ACL_FILEGROUP)) < 0)" .CR { .CR " error (...);" .CR } .IP .CR "for (entry = 0; entry < nentries; entry++)" .CR { .CR " if ((acl [entry] . uid == ACL_FILEOWNER)" .CR " || (acl [entry] . gid == ACL_FILEGROUP))" .CR " {" .CR " perfile = 1;" .CR " break;" .CR " }" .CR } .fi .PP The following code fragment converts an ACL pattern from a string to an array of pattern entries. .nf .IP .CR #include .IP .CR "int nentries;" .CR "struct acl_entry_patt acl [NACLENTRIES];" .IP .CR "if ((nentries = strtoaclpatt (string, NACLENTRIES, acl)) < 0)" .CR " error (...);" .fi .PP The following code fragment inside a .CR for loop checks an entry pattern .RC ( p* , .CR onmask , and .CR offmask variable names) against an entry in a file's ACL .RC ( a* variable names) using the file's user and group IDs .RC ( f* variable names). .nf .IP .CR include .CR "if (((puid == ACL_FILEOWNER) && (fuid != auid))" .CR " || ((puid != ACL_ANYUSER) && (puid != auid)))" .CR { .CR " continue;" .CR } .IP .CR "if (((pgid == ACL_FILEGROUP) && (fgid != agid))" .CR " || ((pgid != ACL_ANYGROUP) && (pgid != agid)))" .CR { .CR " continue;" .CR } .IP .CR "if (((( amode) & MODEMASK & onmask ) != onmask)" .CR " || (((~ amode) & MODEMASK & offmask) != offmask))" .CR { .CR " continue;" .CR } .fi .SH WARNINGS .CR strtoacl() and .CR strtoaclpatt() are unsafe in multi-thread applications. .CR strtoacl_r() and .CR strtoaclpatt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR strtoacl() and .CR strtoaclpatt() were developed by HP. .SH FILES .CR /etc/passwd .br .CR /etc/group .SH SEE ALSO getacl(2), setacl(2), acltostr(3C), cpacl(3C), chownacl(3C), setaclentry(3C), acl(5). .\" .\" index@\f4strtoacl()\f1 \- convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@\f4strtoaclpatt()\f1 \- convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@\f4aclentrystart()\f1 \- convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@access control list (ACL) structure, convert string to@@@\f3strtoacl(3C)\f1 .\" index@string, convert to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" .\" toc@\f3strtoacl(3C)\f1:\0\0\f4strtoacl()\f1, \f4strtoaclpatt()\f1@@@convert string to access control list (ACL) structure .\" toc@\f4strtoaclpatt()\f1: convert string to access control list (ACL) structure@@@see \f3strtoacl(3C)\f1 .\" toc@\f4aclentrystart()\f1: convert string to access control list (ACL) structure@@@see \f3strtoacl(3C)\f1 .\" .\" links@strtoacl.3c strtoacl_r.3c .\" links@strtoacl.3c strtoaclpat.3c .\" links@strtoacl.3c aclentrysta.3c .\" $Header: strtoacl.3c,v 78.1 95/12/20 11:16:24 ssa Exp $ .TA s .TH strtoacl 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strtoacl(\|), strtoacl_r(\|), strtoaclpatt(\|), strtoaclpatt_r(\|), aclentrystart[\|] \- convert string form to access control list (\s-1ACL\s0) structure .SH SYNOPSIS .C "#include " .PP .C "int strtoacl(" .nf .PD 0 .IP .C "const char *string," .C "int nentries," .C "int maxentries," .C "struct acl_entry *acl," .C "uid_t fuid," .C "gid_t fgid);" .PD .PP .C "int strtoacl_r(" .nf .PD 0 .IP .C "const char *string," .C "int nentries," .C "int maxentries," .C "struct acl_entry *acl," .C "uid_t fuid," .C "gid_t fgid," .C "char *entrystart[]);" .PD .PP .C "int strtoaclpatt(" .PD 0 .IP .C "const char *string," .C "int maxentries," .C "struct acl_entry_patt *acl);" .PD .PP .C "int strtoaclpatt_r(" .PD 0 .IP .C "const char *string," .C "int maxentries," .C "struct acl_entry_patt *acl" .C "char *entrystart[]);" .PD .fi .SH DESCRIPTION .CR strtoacl() converts an access control list from exact symbolic (string) representation to structure form. It parses the input string and verifies its validity. Optionally it applies the entries in the string as a series of changes to an existing ACL. .PP .CR strtoaclpatt() converts an access control list pattern from symbolic (string) representation to structure form. It parses the input string and verifies its validity. .PP The external array .CR aclentrystart[] , only valid until the next call of either routine, is useful for error reporting. See ERRORS below. .PP The ``operator'' and ``short'' symbolic forms of ACLs and ACL patterns (described in .IR acl (5)) are acceptable as input strings. If the first non-whitespace character in .I string is .CR ( , the ACL or ACL pattern in .I string must be in short form. Otherwise operator form is assumed. .PP .CR strtoacl() takes a pointer to the string to be converted, and a pointer to the first element of an array of ACL entries .RC ( acl[] ) initially containing the indicated number .RI ( nentries ) of valid entries (zero or more). This array can grow to the indicated number of entries .RI ( maxentries ). .CR strtoacl() also takes file user ID .RI ( fuid ) and group ID .RI ( fgid ) values to substitute for .CR "@" characters in .I string and returns the resulting number of entries in .CR acl[] . .PP Redundant entries (identical user ID and group ID values after processing .CR "@" characters) are combined, so that .CR acl[] contains unique entries in the order encountered. If a new entry is mentioned, it is added to the end of the .CR acl array. .SS strtoaclpatt(\|) .CR strtoaclpatt() differs from .CR strtoacl() because it processes an ACL pattern instead of an ACL. Since modification of an existing initial ACL is not useful, it is not supported. .PP Entries with matching user and group ID values are not combined. Each entry input yields one entry in the returned array. .PP The .CR "@" character for user and group IDs (see .IR acl (5)) is converted to special values (\c .CR ACL_FILEOWNER or .CR ACL_FILEGROUP , respectively, defined in .RC < acllib.h >), not to specific user or group names provided by the caller. Thus, .CR strtoaclpatt() need not be called to reparse the ACL pattern for each file, but the caller must handle the special values when comparing an ACL pattern to an ACL. .PP Wildcard user names, group names, and mode values are supported, as are absent mode parts; see .IR acl (5). .PP .CR strtoaclpatt() returns a different structure than .CR strtoacl() . The .I acl_entry_patt structure contains .I onmode and .I offmode masks rather than a single .I mode value. .PP In operator form input, operators have a different effect on .CR strtoaclpatt() : .RS .TP 5 .CR = Sets bits in both the .I onmode and .I offmode fields appropriately, replacing existing bits in the entry, including any set by earlier operators. .TP .CR + Sets bits in .I onmode and clears the same bits in .IR offmode . .TP .CR \- Sets bits in .I offmode and clears the same bits in .IR onmode . .RE .IP In short form input, the mode is treated like the .CR = operator in operator form. .PP For both routines, a non-specific user or group ID of .CR % is converted to .CR ACL_NSUSER or .CR ACL_NSGROUP , respectively. For .CR strtoaclpatt() only, a wildcard user or group ID of .CR * is converted to .CR ACL_ANYUSER or .CR ACL_ANYGROUP , respectively. The values are defined in .RC < acllib.h >. .PP Entries can appear in .I string in any order. .I string can contain redundant entries, and in operator form only, redundant .CR + and .CR \- operators for ACL entry mode modifications (in exact form) or mode bit inclusions/exclusions (in patterns). Entries or modifications are applied left to right. .SS Suggested Use To build a new ACL (ACL pattern) array using .CR strtoacl() .RC ( strtoaclpatt() ), define .CR acl[] with as many entries as desired. Pass it to .CR strtoacl() .RC ( strtoaclpatt() ) with .I nentries set to zero .RC ( strtoacl() only) and .I maxentries set to the number of elements in .CR acl[] . .PP To have .CR strtoacl() modify a file's existing ACL, define .CR acl[] with the maximum possible number of entries .RC ( NACLENTRIES ; see .RC < sys/acl.h >). Call .CR getacl() (see .IR getacl (2)) to read the file's ACL and .CR stat() (see .IR stat (2)) to get the file's owner and group IDs. Then pass the current number of entries, the current ACL, and the ID values to .CR strtoacl() with .I maxentries set to .CR NACLENTRIES . .PP If .CR strtoacl() succeeds, the resulting ACL can be passed safely to .CR setacl() (see .IR setacl (2)) because all redundancies (if any) have been resolved. However, note that since neither .CR strtoacl() nor .CR strtoaclpatt() validate user and group ID values, if the values are not acceptable to the system, .CR setacl() fails. .SS Performance Trick Normally .CR strtoacl() replaces user and group names of .CR "@" with specific user and group ID values, and also combines redundant entries. Therefore, calling .CR stat() and .CR strtoacl() for each of a series of files to which an ACL is being applied is simplest, although time consuming. .PP If .I string contains no .CR "@" character, or if the caller merely wants to compare one ACL against another (and will handle the special case itself), it is sufficient to call .CR strtoacl() once, and pointless to call .CR stat() for each file. To determine this, call .CR strtoacl() the first time with .I fuid set to .CR ACL_FILEOWNER and .I fgid set to .CR ACL_FILEGROUP . Repeated calls with file-specific .I fuid and .I fgid values are needed only if the special values of .I fuid and .I fgid appear in .CR acl[] and the caller needs an exact ACL to set on each file; see EXAMPLES below. .PP If .CR "@" appears in .I string and .CR acl[] will be used later for a call to .CR setacl() , it is necessary to call .CR strtoacl() again to reparse the ACL string for each file. It is possible that not all redundant entries were combined the first time because the .CR "@" names were not resolved to specific IDs. This also complicates comparisons between two ACLs. Furthermore, the caller cannot do the combining later because operator information from operator form input might be lost. .SS Reentrant Interfaces .CR strtoacl_r() and .CR strtoaclpatt_r() require an extra parameter, .IR entrystart , which is used for error reporting. .I entrystart is used in the same way as .CR strtoacl() and .CR strtoaclpatt() use the global array .CR aclentrystart[] . .PP A size of .CR NACLENTRIES + 1 is recommended for the array .IR entrystart . .SH RETURN VALUE If .CR strtoacl() .RC ( strtoaclpatt() ) succeeds, it returns the number of entries in the resulting ACL (ACL pattern), always equal to or greater than .I nentries (zero). .PP .CR strtoaclpatt() also sets values in global array .CR aclentrystart[] to point to the start of each pattern entry it parsed in .IR string , in some cases including leading or trailing whitespace. It only sets a number of pointers equal to its return value plus one (never more than .CR NACLENTRIES + 1). The last valid element points to the null character at the end of .IR string . After calling .CR strtoaclpatt() , an entry pattern's corresponding input string can be used by the caller for error reporting by (temporarily) putting a null at the start of the next entry pattern in .IR string . .SH ERRORS If an error occurs, .CR strtoacl() and .CR strtoaclpatt() return a negative value and the content of .CR acl is undefined (was probably altered). To help with error reporting in this case, .CR aclentrystart[0] and .CR aclentrystart[1] are set to point to the start of the current and next entries, respectively, being parsed when the error occurred. If the current entry does not start with .CR ( , .CR aclentrystart[1] points to the next null character or comma at or after .CR aclentrystart[0] . Otherwise, it points to the next null, or to the character following the next .CR ) . .PP The following values are returned in case of error: .RS .TP 5 \-1 Syntax error: entry doesn't start with .CR ( as expected in short form. .TP \-2 Syntax error: entry doesn't end with .CR ) as expected in short form. .TP \-3 Syntax error: user name is not terminated by a dot. .TP \-4 .RC ( strtoacl() only) Syntax error: group name is not terminated by an operator in operator-form input or a comma in short-form input. .TP \-5 Syntax error: user name is null. .TP \-6 Syntax error: group name is null. .TP \-7 Invalid user name (not found in .CR /etc/passwd file and not a valid number). .TP \-8 Invalid group name (not found in .CR /etc/group file and not a valid number). .TP \-9 Syntax error: invalid mode character, other than .CR 0 ".." 7 , .CR r , .CR w , .CR x , .CR - (allowed in short form only), .CR * (allowed in patterns only), .CR , (to end an entry in operator form), or .CR ) (to end an entry in short form). Or, .CR 0 ".." 7 or .CR * is followed by other mode characters. .TP \-10 The resulting ACL would have more than .I maxentries entries. .RE .SH EXAMPLES The following code fragment converts an ACL from a string to an array of entries using an .I fuid of 103 for the file's owner and .I fgid of 45 for the file's group. .nf .IP .CR #include .IP .CR int nentries; .CR struct acl_entry acl [NACLENTRIES]; .IP .CR "if ((nentries = strtoacl (string, 0, NACLENTRIES, acl, 103, 45)) < 0)" .CR " error (...);" .fi .PP The following code gets the ACL, .IR fuid , and .I fgid for file .CR ../myfile , modifies the ACL using a description string, and changes the ACL on file .CR ../myfile2 to be the new version. .nf .IP .CR #include .CR #include .CR #include .IP .CR "struct stat statbuf;" .CR "int nentries;" .CR "struct acl_entry acl [NACLENTRIES];" .IP .ift .ft 4 .ifn .ft 3 .ps +1 if (stat ("../myfile", & statbuf) < 0) .ft .ps .CR " error (...);" .IP .ift .ft 4 .ifn .ft 3 .ps +1 if ((nentries = getacl ("../myfile", NACLENTRIES, acl)) < 0) .ft .ps .CR " error (...);" .IP .CR "if ((nentries = strtoacl (string, nentries, NACLENTRIES, acl, .CR " statbuf.st_uid, statbuf.st_gid)) < 0)" .CR { .CR " error (...);" .CR } .IP .ift .ft 4 .ifn .ft 3 .ps +1 if (setacl ("../myfile2", nentries, acl) < 0) .ft .ps .CR " error (...);" .fi .PP The following code fragment calls .CR strtoacl() with special values of .I fuid and .IR fgid , then checks to see if they show up in .CR acl[] . .nf .IP .CR #include .IP .CR "int perfile = 0; /* need to stat() and reparse per file? */" .CR "int entry;" .IP .CR "if ((nentries = strtoacl (string, 0, NACLENTRIES, acl," .CR " ACL_FILEOWNER, ACL_FILEGROUP)) < 0)" .CR { .CR " error (...);" .CR } .IP .CR "for (entry = 0; entry < nentries; entry++)" .CR { .CR " if ((acl [entry] . uid == ACL_FILEOWNER)" .CR " || (acl [entry] . gid == ACL_FILEGROUP))" .CR " {" .CR " perfile = 1;" .CR " break;" .CR " }" .CR } .fi .PP The following code fragment converts an ACL pattern from a string to an array of pattern entries. .nf .IP .CR #include .IP .CR "int nentries;" .CR "struct acl_entry_patt acl [NACLENTRIES];" .IP .CR "if ((nentries = strtoaclpatt (string, NACLENTRIES, acl)) < 0)" .CR " error (...);" .fi .PP The following code fragment inside a .CR for loop checks an entry pattern .RC ( p* , .CR onmask , and .CR offmask variable names) against an entry in a file's ACL .RC ( a* variable names) using the file's user and group IDs .RC ( f* variable names). .nf .IP .CR include .CR "if (((puid == ACL_FILEOWNER) && (fuid != auid))" .CR " || ((puid != ACL_ANYUSER) && (puid != auid)))" .CR { .CR " continue;" .CR } .IP .CR "if (((pgid == ACL_FILEGROUP) && (fgid != agid))" .CR " || ((pgid != ACL_ANYGROUP) && (pgid != agid)))" .CR { .CR " continue;" .CR } .IP .CR "if (((( amode) & MODEMASK & onmask ) != onmask)" .CR " || (((~ amode) & MODEMASK & offmask) != offmask))" .CR { .CR " continue;" .CR } .fi .SH WARNINGS .CR strtoacl() and .CR strtoaclpatt() are unsafe in multi-thread applications. .CR strtoacl_r() and .CR strtoaclpatt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR strtoacl() and .CR strtoaclpatt() were developed by HP. .SH FILES .CR /etc/passwd .br .CR /etc/group .SH SEE ALSO getacl(2), setacl(2), acltostr(3C), cpacl(3C), chownacl(3C), setaclentry(3C), acl(5). .\" .\" index@\f4strtoacl()\f1 \- convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@\f4strtoaclpatt()\f1 \- convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@\f4aclentrystart()\f1 \- convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@access control list (ACL) structure, convert string to@@@\f3strtoacl(3C)\f1 .\" index@string, convert to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" .\" toc@\f3strtoacl(3C)\f1:\0\0\f4strtoacl()\f1, \f4strtoaclpatt()\f1@@@convert string to access control list (ACL) structure .\" toc@\f4strtoaclpatt()\f1: convert string to access control list (ACL) structure@@@see \f3strtoacl(3C)\f1 .\" toc@\f4aclentrystart()\f1: convert string to access control list (ACL) structure@@@see \f3strtoacl(3C)\f1 .\" .\" links@strtoacl.3c strtoacl_r.3c .\" links@strtoacl.3c strtoaclpat.3c .\" links@strtoacl.3c aclentrysta.3c .\" $Header: strtoacl.3c,v 78.1 95/12/20 11:16:24 ssa Exp $ .TA s .TH strtoacl 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strtoacl(\|), strtoacl_r(\|), strtoaclpatt(\|), strtoaclpatt_r(\|), aclentrystart[\|] \- convert string form to access control list (\s-1ACL\s0) structure .SH SYNOPSIS .C "#include " .PP .C "int strtoacl(" .nf .PD 0 .IP .C "const char *string," .C "int nentries," .C "int maxentries," .C "struct acl_entry *acl," .C "uid_t fuid," .C "gid_t fgid);" .PD .PP .C "int strtoacl_r(" .nf .PD 0 .IP .C "const char *string," .C "int nentries," .C "int maxentries," .C "struct acl_entry *acl," .C "uid_t fuid," .C "gid_t fgid," .C "char *entrystart[]);" .PD .PP .C "int strtoaclpatt(" .PD 0 .IP .C "const char *string," .C "int maxentries," .C "struct acl_entry_patt *acl);" .PD .PP .C "int strtoaclpatt_r(" .PD 0 .IP .C "const char *string," .C "int maxentries," .C "struct acl_entry_patt *acl" .C "char *entrystart[]);" .PD .fi .SH DESCRIPTION .CR strtoacl() converts an access control list from exact symbolic (string) representation to structure form. It parses the input string and verifies its validity. Optionally it applies the entries in the string as a series of changes to an existing ACL. .PP .CR strtoaclpatt() converts an access control list pattern from symbolic (string) representation to structure form. It parses the input string and verifies its validity. .PP The external array .CR aclentrystart[] , only valid until the next call of either routine, is useful for error reporting. See ERRORS below. .PP The ``operator'' and ``short'' symbolic forms of ACLs and ACL patterns (described in .IR acl (5)) are acceptable as input strings. If the first non-whitespace character in .I string is .CR ( , the ACL or ACL pattern in .I string must be in short form. Otherwise operator form is assumed. .PP .CR strtoacl() takes a pointer to the string to be converted, and a pointer to the first element of an array of ACL entries .RC ( acl[] ) initially containing the indicated number .RI ( nentries ) of valid entries (zero or more). This array can grow to the indicated number of entries .RI ( maxentries ). .CR strtoacl() also takes file user ID .RI ( fuid ) and group ID .RI ( fgid ) values to substitute for .CR "@" characters in .I string and returns the resulting number of entries in .CR acl[] . .PP Redundant entries (identical user ID and group ID values after processing .CR "@" characters) are combined, so that .CR acl[] contains unique entries in the order encountered. If a new entry is mentioned, it is added to the end of the .CR acl array. .SS strtoaclpatt(\|) .CR strtoaclpatt() differs from .CR strtoacl() because it processes an ACL pattern instead of an ACL. Since modification of an existing initial ACL is not useful, it is not supported. .PP Entries with matching user and group ID values are not combined. Each entry input yields one entry in the returned array. .PP The .CR "@" character for user and group IDs (see .IR acl (5)) is converted to special values (\c .CR ACL_FILEOWNER or .CR ACL_FILEGROUP , respectively, defined in .RC < acllib.h >), not to specific user or group names provided by the caller. Thus, .CR strtoaclpatt() need not be called to reparse the ACL pattern for each file, but the caller must handle the special values when comparing an ACL pattern to an ACL. .PP Wildcard user names, group names, and mode values are supported, as are absent mode parts; see .IR acl (5). .PP .CR strtoaclpatt() returns a different structure than .CR strtoacl() . The .I acl_entry_patt structure contains .I onmode and .I offmode masks rather than a single .I mode value. .PP In operator form input, operators have a different effect on .CR strtoaclpatt() : .RS .TP 5 .CR = Sets bits in both the .I onmode and .I offmode fields appropriately, replacing existing bits in the entry, including any set by earlier operators. .TP .CR + Sets bits in .I onmode and clears the same bits in .IR offmode . .TP .CR \- Sets bits in .I offmode and clears the same bits in .IR onmode . .RE .IP In short form input, the mode is treated like the .CR = operator in operator form. .PP For both routines, a non-specific user or group ID of .CR % is converted to .CR ACL_NSUSER or .CR ACL_NSGROUP , respectively. For .CR strtoaclpatt() only, a wildcard user or group ID of .CR * is converted to .CR ACL_ANYUSER or .CR ACL_ANYGROUP , respectively. The values are defined in .RC < acllib.h >. .PP Entries can appear in .I string in any order. .I string can contain redundant entries, and in operator form only, redundant .CR + and .CR \- operators for ACL entry mode modifications (in exact form) or mode bit inclusions/exclusions (in patterns). Entries or modifications are applied left to right. .SS Suggested Use To build a new ACL (ACL pattern) array using .CR strtoacl() .RC ( strtoaclpatt() ), define .CR acl[] with as many entries as desired. Pass it to .CR strtoacl() .RC ( strtoaclpatt() ) with .I nentries set to zero .RC ( strtoacl() only) and .I maxentries set to the number of elements in .CR acl[] . .PP To have .CR strtoacl() modify a file's existing ACL, define .CR acl[] with the maximum possible number of entries .RC ( NACLENTRIES ; see .RC < sys/acl.h >). Call .CR getacl() (see .IR getacl (2)) to read the file's ACL and .CR stat() (see .IR stat (2)) to get the file's owner and group IDs. Then pass the current number of entries, the current ACL, and the ID values to .CR strtoacl() with .I maxentries set to .CR NACLENTRIES . .PP If .CR strtoacl() succeeds, the resulting ACL can be passed safely to .CR setacl() (see .IR setacl (2)) because all redundancies (if any) have been resolved. However, note that since neither .CR strtoacl() nor .CR strtoaclpatt() validate user and group ID values, if the values are not acceptable to the system, .CR setacl() fails. .SS Performance Trick Normally .CR strtoacl() replaces user and group names of .CR "@" with specific user and group ID values, and also combines redundant entries. Therefore, calling .CR stat() and .CR strtoacl() for each of a series of files to which an ACL is being applied is simplest, although time consuming. .PP If .I string contains no .CR "@" character, or if the caller merely wants to compare one ACL against another (and will handle the special case itself), it is sufficient to call .CR strtoacl() once, and pointless to call .CR stat() for each file. To determine this, call .CR strtoacl() the first time with .I fuid set to .CR ACL_FILEOWNER and .I fgid set to .CR ACL_FILEGROUP . Repeated calls with file-specific .I fuid and .I fgid values are needed only if the special values of .I fuid and .I fgid appear in .CR acl[] and the caller needs an exact ACL to set on each file; see EXAMPLES below. .PP If .CR "@" appears in .I string and .CR acl[] will be used later for a call to .CR setacl() , it is necessary to call .CR strtoacl() again to reparse the ACL string for each file. It is possible that not all redundant entries were combined the first time because the .CR "@" names were not resolved to specific IDs. This also complicates comparisons between two ACLs. Furthermore, the caller cannot do the combining later because operator information from operator form input might be lost. .SS Reentrant Interfaces .CR strtoacl_r() and .CR strtoaclpatt_r() require an extra parameter, .IR entrystart , which is used for error reporting. .I entrystart is used in the same way as .CR strtoacl() and .CR strtoaclpatt() use the global array .CR aclentrystart[] . .PP A size of .CR NACLENTRIES + 1 is recommended for the array .IR entrystart . .SH RETURN VALUE If .CR strtoacl() .RC ( strtoaclpatt() ) succeeds, it returns the number of entries in the resulting ACL (ACL pattern), always equal to or greater than .I nentries (zero). .PP .CR strtoaclpatt() also sets values in global array .CR aclentrystart[] to point to the start of each pattern entry it parsed in .IR string , in some cases including leading or trailing whitespace. It only sets a number of pointers equal to its return value plus one (never more than .CR NACLENTRIES + 1). The last valid element points to the null character at the end of .IR string . After calling .CR strtoaclpatt() , an entry pattern's corresponding input string can be used by the caller for error reporting by (temporarily) putting a null at the start of the next entry pattern in .IR string . .SH ERRORS If an error occurs, .CR strtoacl() and .CR strtoaclpatt() return a negative value and the content of .CR acl is undefined (was probably altered). To help with error reporting in this case, .CR aclentrystart[0] and .CR aclentrystart[1] are set to point to the start of the current and next entries, respectively, being parsed when the error occurred. If the current entry does not start with .CR ( , .CR aclentrystart[1] points to the next null character or comma at or after .CR aclentrystart[0] . Otherwise, it points to the next null, or to the character following the next .CR ) . .PP The following values are returned in case of error: .RS .TP 5 \-1 Syntax error: entry doesn't start with .CR ( as expected in short form. .TP \-2 Syntax error: entry doesn't end with .CR ) as expected in short form. .TP \-3 Syntax error: user name is not terminated by a dot. .TP \-4 .RC ( strtoacl() only) Syntax error: group name is not terminated by an operator in operator-form input or a comma in short-form input. .TP \-5 Syntax error: user name is null. .TP \-6 Syntax error: group name is null. .TP \-7 Invalid user name (not found in .CR /etc/passwd file and not a valid number). .TP \-8 Invalid group name (not found in .CR /etc/group file and not a valid number). .TP \-9 Syntax error: invalid mode character, other than .CR 0 ".." 7 , .CR r , .CR w , .CR x , .CR - (allowed in short form only), .CR * (allowed in patterns only), .CR , (to end an entry in operator form), or .CR ) (to end an entry in short form). Or, .CR 0 ".." 7 or .CR * is followed by other mode characters. .TP \-10 The resulting ACL would have more than .I maxentries entries. .RE .SH EXAMPLES The following code fragment converts an ACL from a string to an array of entries using an .I fuid of 103 for the file's owner and .I fgid of 45 for the file's group. .nf .IP .CR #include .IP .CR int nentries; .CR struct acl_entry acl [NACLENTRIES]; .IP .CR "if ((nentries = strtoacl (string, 0, NACLENTRIES, acl, 103, 45)) < 0)" .CR " error (...);" .fi .PP The following code gets the ACL, .IR fuid , and .I fgid for file .CR ../myfile , modifies the ACL using a description string, and changes the ACL on file .CR ../myfile2 to be the new version. .nf .IP .CR #include .CR #include .CR #include .IP .CR "struct stat statbuf;" .CR "int nentries;" .CR "struct acl_entry acl [NACLENTRIES];" .IP .ift .ft 4 .ifn .ft 3 .ps +1 if (stat ("../myfile", & statbuf) < 0) .ft .ps .CR " error (...);" .IP .ift .ft 4 .ifn .ft 3 .ps +1 if ((nentries = getacl ("../myfile", NACLENTRIES, acl)) < 0) .ft .ps .CR " error (...);" .IP .CR "if ((nentries = strtoacl (string, nentries, NACLENTRIES, acl, .CR " statbuf.st_uid, statbuf.st_gid)) < 0)" .CR { .CR " error (...);" .CR } .IP .ift .ft 4 .ifn .ft 3 .ps +1 if (setacl ("../myfile2", nentries, acl) < 0) .ft .ps .CR " error (...);" .fi .PP The following code fragment calls .CR strtoacl() with special values of .I fuid and .IR fgid , then checks to see if they show up in .CR acl[] . .nf .IP .CR #include .IP .CR "int perfile = 0; /* need to stat() and reparse per file? */" .CR "int entry;" .IP .CR "if ((nentries = strtoacl (string, 0, NACLENTRIES, acl," .CR " ACL_FILEOWNER, ACL_FILEGROUP)) < 0)" .CR { .CR " error (...);" .CR } .IP .CR "for (entry = 0; entry < nentries; entry++)" .CR { .CR " if ((acl [entry] . uid == ACL_FILEOWNER)" .CR " || (acl [entry] . gid == ACL_FILEGROUP))" .CR " {" .CR " perfile = 1;" .CR " break;" .CR " }" .CR } .fi .PP The following code fragment converts an ACL pattern from a string to an array of pattern entries. .nf .IP .CR #include .IP .CR "int nentries;" .CR "struct acl_entry_patt acl [NACLENTRIES];" .IP .CR "if ((nentries = strtoaclpatt (string, NACLENTRIES, acl)) < 0)" .CR " error (...);" .fi .PP The following code fragment inside a .CR for loop checks an entry pattern .RC ( p* , .CR onmask , and .CR offmask variable names) against an entry in a file's ACL .RC ( a* variable names) using the file's user and group IDs .RC ( f* variable names). .nf .IP .CR include .CR "if (((puid == ACL_FILEOWNER) && (fuid != auid))" .CR " || ((puid != ACL_ANYUSER) && (puid != auid)))" .CR { .CR " continue;" .CR } .IP .CR "if (((pgid == ACL_FILEGROUP) && (fgid != agid))" .CR " || ((pgid != ACL_ANYGROUP) && (pgid != agid)))" .CR { .CR " continue;" .CR } .IP .CR "if (((( amode) & MODEMASK & onmask ) != onmask)" .CR " || (((~ amode) & MODEMASK & offmask) != offmask))" .CR { .CR " continue;" .CR } .fi .SH WARNINGS .CR strtoacl() and .CR strtoaclpatt() are unsafe in multi-thread applications. .CR strtoacl_r() and .CR strtoaclpatt_r() are MT-Safe and should be used instead. .SH AUTHOR .CR strtoacl() and .CR strtoaclpatt() were developed by HP. .SH FILES .CR /etc/passwd .br .CR /etc/group .SH SEE ALSO getacl(2), setacl(2), acltostr(3C), cpacl(3C), chownacl(3C), setaclentry(3C), acl(5). .\" .\" index@\f4strtoacl()\f1 \- convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@\f4strtoaclpatt()\f1 \- convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@\f4aclentrystart()\f1 \- convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@convert string to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" index@access control list (ACL) structure, convert string to@@@\f3strtoacl(3C)\f1 .\" index@string, convert to access control list (ACL) structure@@@\f3strtoacl(3C)\f1 .\" .\" toc@\f3strtoacl(3C)\f1:\0\0\f4strtoacl()\f1, \f4strtoaclpatt()\f1@@@convert string to access control list (ACL) structure .\" toc@\f4strtoaclpatt()\f1: convert string to access control list (ACL) structure@@@see \f3strtoacl(3C)\f1 .\" toc@\f4aclentrystart()\f1: convert string to access control list (ACL) structure@@@see \f3strtoacl(3C)\f1 .\" .\" links@strtoacl.3c strtoacl_r.3c .\" links@strtoacl.3c strtoaclpat.3c .\" links@strtoacl.3c aclentrysta.3c .\" $Header: strtod.3c,v 72.6 94/11/30 15:47:58 ssa Exp $ .TA s .TH strtod 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strtod, atof \- convert string to double-precision number .SH SYNOPSIS .C "#include " .PP .C "double strtod(const char *str, char **ptr);" .PP .C "double atof(const char *str);" .SH DESCRIPTION .C strtod() returns, as a double-precision floating-point number, the value represented by the character string pointed to by .IR str . The string is scanned (leading white-space characters as defined by .C isspace() in .IR ctype (3C) are ignored) up to the first unrecognized character. If no conversion can take place, zero is returned. .PP .C strtod() recognizes characters in the following sequence: .RS .TP 5 1. An optional string of ``white-space'' characters which are ignored, .PD 0 .TP 2. An optional sign, .TP 3. A string of digits optionally containing a radix character, .TP 4. An optional .C e or .C E followed by an optional sign or space, followed by an integer. .PD .RE .PP The radix character is determined by the loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C", is used (see .IR lang (5)). The default environment specifies a period (.) as the radix character. .PP If the value of .I ptr is not .CR "(char **)NULL , the variable to which it points is set to point at the character after the last number, if any, that was recognized. If no number can be formed, .I \(**ptr is set to .IR str , and zero is returned. .PP .CI atof( str ) is equivalent to .CI "strtod (" str ", (char **)NULL)\f1." .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the value of the radix character within the currently loaded .SM NLS environment. .SH RETURN VALUE If the correct value would cause overflow, .C +HUGE_VAL or .C -HUGE_VAL is returned (according to the sign of the value), and .C errno is set to .SM ERANGE. .PP If the correct value would cause underflow, zero is returned and .C errno is set to .SM ERANGE. .SH AUTHOR .C strtod() was developed by AT&T and HP. .SH SEE ALSO ctype(3C), setlocale(3C), scanf(3S), strtol(3C), hpnls(5), lang(5). .SH STANDARDS CONFORMANCE .CR strtod() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR atof() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4strtod()\fP \- convert string to double-precision number@@@\f3strtod(3C)\f1 .\" index@\f4atof()\fP \- convert string to double-precision number@@@\f3strtod(3C)\f1 .\" index@convert string to double-precision number@@@\f3strtod(3C)\f1 .\" index@string to double-precision number, convert@@@\f3strtod(3C)\f1 .\" index@double-precision number, convert string to@@@\f3strtod(3C)\f1 .\" index@number, convert string to double-precision@@@\f3strtod(3C)\f1 .\" .\" toc@\f3strtod(3C)\f1:\0\0\f4strtod()\fP, \f4atof()\f1@@@convert string to double-precision number .\" toc@\f4atof()\fP:\0\0convert string to double-precision number@@@see \f3strtod(3C)\f1 .\" .\" links@strtod.3c atof.3c .\" links@strtod.3c nl_strtod.3c .\" links@strtod.3c nl_atof.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: strtol.3c,v 72.5 94/11/15 09:56:32 ssa Exp $ .TA s .TH strtol 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strtol(\|), atol(\|), atoi(\|), strtoul(\|) \- convert string to integer .SH SYNOPSIS .C "#include " .PP .C "long strtol(const char *str, char **ptr, int base);" .PP .C "long atol(const char *str);" .PP .C "int atoi(const char *str);" .PP .C "unsigned long strtoul(const char *str, char **ptr, int base);" .SH DESCRIPTION .C strtol() .RC ( strtoul() ) converts the character string pointed to by .I str to .C long int .RC ( "unsigned long int" ) representation. The string is scanned up to the first character inconsistent with the base. Leading ``white-space'' characters (as defined by .C isspace() in .IR ctype (3C)) are ignored. If no conversion can take place, zero is returned. .PP If .I base is greater than or equal to 2 and less than or equal to 36, it is used as the base for conversion. After an optional leading sign, leading zeros are ignored, and .C 0x or .C 0X is ignored if .I base is 16. .PP If .I base is zero, the string itself determines the base as follows: After an optional leading sign, a leading zero indicates octal conversion; a leading .C 0x or .C 0X hexadecimal conversion. Otherwise, decimal conversion is used. .PP If the value of .I ptr is not .CR "(char **)NULL" , a pointer to the character terminating the scan is returned in the location pointed to by .IR ptr . If no integer can be formed, the location pointed to by .I ptr is set to .IR str , and zero is returned. .PP .CI atol ( str ) is equivalent to .CI "strtol(" str ", (char **)NULL, 10)\f1." .PP .CI atoi( str ) is equivalent to .CI "int strtol(" str ", (char **)NULL, 10)\f1." .SH RETURN VALUE Upon successful completion, all functions return the converted value, if any. If the correct value would cause overflow, .C strtol() returns .C LONG_MAX or .C LONG_MIN (according to the sign of the value), and sets .C errno to .SM ERANGE; .C strtoul() returns .C ULONG_MAX and sets .C errno to .SM ERANGE. Overflow conditions are ignored by .C atol() and .CR atoi() . .PP For all other errors, zero is returned and .C errno is set to indicate the error. .SH ERRORS .C strtol() and .C strtoul() fail and .C errno is set if any of the following conditions are encountered: .RS .TP 15 .SM [EINVAL] The value of .I base is not supported. .TP .SM [ERANGE] The value to be returned would have caused overflow. .RE .SH AUTHOR .CR strtol() , .CR atoi() , and .CR atol() , were developed by OSF and HP. .SH SEE ALSO ctype(3C), strtod(3C), scanf(3S). .SH STANDARDS CONFORMANCE .CR strtol() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR atoi() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR atol() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtoul() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4strtol()\fP \(mi convert string to long integer@@@\f3strtol(3C)\f1 .\" index@\f4atol()\fP \(mi convert string to long integer@@@\f3strtol(3C)\f1 .\" index@\f4atoi()\fP \(mi convert string to long integer@@@\f3strtol(3C)\f1 .\" index@\f1string to long integer, convert@@@\f3strtol(3C)\f1 .\" index@\f1integer, convert string to long@@@\f3strtol(3C)\f1 .\" .\" toc@\f3strtol(3C)\f:\0\0\f4strtol()\f1, \f4atol()\f1, \f4atoi()\f1@@@convert string to integer .\" toc@\f4atol()\f1:\0\0convert string to integer@@@\f1see \f3strtol(3C)\f1 .\" toc@\f4atoi()\f1:\0\0convert string to integer@@@\f1see \f3strtol(3C)\f1 .\" .\" links@strtol.3c atol.3c .\" links@strtol.3c atoi.3c .\" links@strtol.3c strtoul.3c .\" .\" fileset_database@strtol.3c PROGRAMING-MAN .\" $Header: strtold.3c,v 72.4 94/11/30 15:48:16 ssa Exp $ .TA s .TH strtold 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strtold(\|) \- convert string to long double-precision number .SH SYNOPSIS .C "#include " .PP .C "long_double strtold(const char *str, char **ptr);" .SH DESCRIPTION .C strtold() returns as a long double-precision number the value represented by the character string pointed to by .IR str . The string is scanned up to the first unrecognized character. .PP .C strtold() recognizes an optional string of ``white-space'' characters (as defined by .C isspace() in .IR ctype (3C)), then an optional sign, then a string of digits optionally containing a radix character, then an optional .C e or .C E followed by an optional sign or space, followed by an integer. The radix character is determined by the loaded .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C" (see .IR lang (5)), is used. The default environment specifies a period .RC ( . ) as the radix character. .PP If the value of .I ptr is not .RC ( "char **" )\c .SM NULL, the variable to which it points is set to point at the character after the last number, if any, that was recognized. If no number can be formed, .I \(**ptr is set to .IR str , and zero is returned. .SH EXTERNAL INFLUENCES .SS International Code Set Support Single-byte character code sets are supported. .SH RETURN VALUE If the correct value would cause overflow, .C +_MAXLDBL or .C -_MAXLDBL is returned (according to the sign of the value), and .C errno is set to .SM ERANGE. .PP If the correct value would cause underflow, zero is returned and .C errno is set to .SM ERANGE. .SH AUTHOR .C strtold() was developed by HP. .SH SEE ALSO ctype(3C), setlocale(3C), scanf(3S), hpnls(5), lang(5). .\" .\" index@\f4strtold()\fP \- convert string to long double-precision number@@@\f3strtold(3C)\f1 .\" index@convert string to long double-precision number@@@\f3strtold(3C)\f1 .\" index@string, convert to long double-precision number@@@\f3strtold(3C)\f1 .\" index@long double-precision number, convert string to@@@\f3strtold(3C)\f1 .\" index@double-precision number, convert string to long@@@\f3strtold(3C)\f1 .\" index@number, convert string to long double-precision@@@\f3strtold(3C)\f1 .\" .\" toc@\f3strtold(3C)\f1:\0\0\f4strtold()\fP@@@convert string to long double-precision number .\" .\" fileset_database@strtold.3c PROGRAMING-MAN .\" $Header: strtol.3c,v 72.5 94/11/15 09:56:32 ssa Exp $ .TA s .TH strtol 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strtol(\|), atol(\|), atoi(\|), strtoul(\|) \- convert string to integer .SH SYNOPSIS .C "#include " .PP .C "long strtol(const char *str, char **ptr, int base);" .PP .C "long atol(const char *str);" .PP .C "int atoi(const char *str);" .PP .C "unsigned long strtoul(const char *str, char **ptr, int base);" .SH DESCRIPTION .C strtol() .RC ( strtoul() ) converts the character string pointed to by .I str to .C long int .RC ( "unsigned long int" ) representation. The string is scanned up to the first character inconsistent with the base. Leading ``white-space'' characters (as defined by .C isspace() in .IR ctype (3C)) are ignored. If no conversion can take place, zero is returned. .PP If .I base is greater than or equal to 2 and less than or equal to 36, it is used as the base for conversion. After an optional leading sign, leading zeros are ignored, and .C 0x or .C 0X is ignored if .I base is 16. .PP If .I base is zero, the string itself determines the base as follows: After an optional leading sign, a leading zero indicates octal conversion; a leading .C 0x or .C 0X hexadecimal conversion. Otherwise, decimal conversion is used. .PP If the value of .I ptr is not .CR "(char **)NULL" , a pointer to the character terminating the scan is returned in the location pointed to by .IR ptr . If no integer can be formed, the location pointed to by .I ptr is set to .IR str , and zero is returned. .PP .CI atol ( str ) is equivalent to .CI "strtol(" str ", (char **)NULL, 10)\f1." .PP .CI atoi( str ) is equivalent to .CI "int strtol(" str ", (char **)NULL, 10)\f1." .SH RETURN VALUE Upon successful completion, all functions return the converted value, if any. If the correct value would cause overflow, .C strtol() returns .C LONG_MAX or .C LONG_MIN (according to the sign of the value), and sets .C errno to .SM ERANGE; .C strtoul() returns .C ULONG_MAX and sets .C errno to .SM ERANGE. Overflow conditions are ignored by .C atol() and .CR atoi() . .PP For all other errors, zero is returned and .C errno is set to indicate the error. .SH ERRORS .C strtol() and .C strtoul() fail and .C errno is set if any of the following conditions are encountered: .RS .TP 15 .SM [EINVAL] The value of .I base is not supported. .TP .SM [ERANGE] The value to be returned would have caused overflow. .RE .SH AUTHOR .CR strtol() , .CR atoi() , and .CR atol() , were developed by OSF and HP. .SH SEE ALSO ctype(3C), strtod(3C), scanf(3S). .SH STANDARDS CONFORMANCE .CR strtol() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, ANSI C" .PP .CR atoi() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR atol() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtoul() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4strtol()\fP \(mi convert string to long integer@@@\f3strtol(3C)\f1 .\" index@\f4atol()\fP \(mi convert string to long integer@@@\f3strtol(3C)\f1 .\" index@\f4atoi()\fP \(mi convert string to long integer@@@\f3strtol(3C)\f1 .\" index@\f1string to long integer, convert@@@\f3strtol(3C)\f1 .\" index@\f1integer, convert string to long@@@\f3strtol(3C)\f1 .\" .\" toc@\f3strtol(3C)\f:\0\0\f4strtol()\f1, \f4atol()\f1, \f4atoi()\f1@@@convert string to integer .\" toc@\f4atol()\f1:\0\0convert string to integer@@@\f1see \f3strtol(3C)\f1 .\" toc@\f4atoi()\f1:\0\0convert string to integer@@@\f1see \f3strtol(3C)\f1 .\" .\" links@strtol.3c atol.3c .\" links@strtol.3c atoi.3c .\" links@strtol.3c strtoul.3c .\" .\" fileset_database@strtol.3c PROGRAMING-MAN .\" $Header: string.3c,v 76.1 95/07/05 17:53:44 ssa Exp $ .TA s .TH string 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME strcat(\|), strncat(\|), strcmp(\|), strncmp(\|), strcasecmp(\|), strncasecmp(\|), strcpy(\|), strncpy(\|), strdup(\|), strlen(\|), strchr(\|), strrchr(\|), strpbrk(\|), strspn(\|), strcspn(\|), strstr(\|), strrstr(\|), strtok(\|), strtok_r(\|), strcoll(\|), strxfrm(\|), index(\|), rindex(\|) \- character string operations .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "char *strcat(char *s1, const char *s2);" .PP .C "char *strncat(char *s1, const char *s2, size_t n);" .PP .C "int strcmp(const char *s1, const char *s2);" .PP .C "int strncmp(const char *s1, const char *s2, size_t n);" .PP .C "int strcasecmp(const char *s1, const char *s2);" .PP .C "int strncasecmp(const char *s1, const char *s2, size_t n);" .PP .C "char *strcpy(char *s1, const char *s2);" .PP .C "char *strncpy(char *s1, const char *s2, size_t n);" .PP .C "char *strdup(const char *s);" .PP .C "size_t strlen(const char *s);" .PP .C "char *strchr(const char *s, int c);" .PP .C "char *strrchr(const char *s, int c);" .PP .C "char *strpbrk(const char *s1, const char *s2);" .PP .C "size_t strspn(const char *s1, const char *s2);" .PP .C "size_t strcspn(const char *s1, const char *s2);" .PP .C "char *strstr(const char *s1, const char *s2);" .PP .C "char *strrstr(const char *s1, const char *s2);" .PP .C "char *strtok(char *s1, const char *s2);" .PP .C "char *strtok_r(char *s1, const char *s2, char **last);" .PP .C "int strcoll(const char *s1, const char *s2);" .PP .C "size_t strxfrm(char *s1, const char *s2, size_t n);" .PP .C "char *index(const char *s, int c);" .PP .C "char *rindex(const char *s, int c);" .SS Remarks: All functions except .C index() and .C rindex() are declared in both headers, so only one of the two headers needs to be included. .PP The functions .C index() and .C rindex() are declared only in .RC < strings.h >, and .RC < strings.h >. They are provided solely for portability of BSD applications, and are not recommended for new applications where portability is important. For portable applications, use .RC < string.h >, .CR strchr() , and .C strrchr() instead. .SH DESCRIPTION Arguments .IR s1 , .IR s2 , and .I s point to strings (arrays of characters terminated by a null byte). .PP Definitions for all these functions, the type .CR size_t , and the constant .C NULL are provided in the .RB < string.h > header. .TP 15 .C strcat() Appends a copy of string .I s2 to the end of string .IR s1 . .C strncat() appends a maximum of .I n characters. It copies fewer if .I s2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR s1 ). .TP .C strcmp() Compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I s1 is lexicographically less than, equal to, or greater than .IR s2 . The comparison of corresponding characters is done as if the type of the characters were .CR "unsigned char" . Null pointer values for .I s1 and .I s2 are treated the same as pointers to empty strings. .C strncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .C strcasecmp() and .C strncasecmp() are identical in function to .C strcmp() and .C strncmp() respectively, but characters are folded by .C _tolower() (see .IR conv (3C)) prior to comparison. The returned lexicographic difference reflects the folding to lowercase. .TP .C strcpy() Copies string .I s2 to .IR s1 , stopping after the null byte has been copied. .C strncpy() copies exactly .I n characters, truncating .I s2 or adding null bytes to .I s1 if necessary, until a total of .I n have been written. The result is not null-terminated if the length of .I s2 is .I n or more. Each function returns .IR s1 . Note that .C strncpy() should not be used to copy .I n bytes of an arbitrary structure. If that structure contains a null byte anywhere, .C strncpy() copies fewer than .I n bytes from the source to the destination and fills the remainder with null bytes. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .TP .C strdup() Returns a pointer to a new string which is a duplicate of the string to which .I s1 points. The space for the new string is obtained using the .C malloc() function (see .IR malloc (3C)). .TP .C strlen() Returns the number of characters in .IR s , not including the terminating null byte. .TP .C strchr() .RC ( strrchr() ) Returns a pointer to the first (last) occurrence of character .I c in string .IR s , or a null pointer if .I c does not occur in the string. The null byte terminating a string is considered to be part of the string. .C index() .RC ( rindex() ) is identical to .C strchr() .RC ( strrchr() ), and is provided solely for portability of BSD applications. .TP .C strpbrk() Returns a pointer to the first occurrence in string .I s1 of any character from string .IR s2 , or a null pointer if no character from .I s2 exists in .IR s1 . .TP .C strspn() .RC ( strcspn() ) Returns the length of the maximum initial segment of string .IR s1 , which consists entirely of characters from (not from) string .IR s2 . .TP .C strstr() .RC ( strrstr() ) Returns a pointer to the first (last) occurrence of string .I s2 in string .IR s1 , or a NULL pointer if .I s2 does not occur in the string. If .I s2 points to a string of zero length, .C strstr() .RC ( strrstr() ) returns .IR s1 . .TP .C strtok() Considers the string .I s1 to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string .IR s2 . The first call (with a nonnull pointer .I s1 specified) returns a pointer to the first character of the first token, and writes a null byte into .I s1 immediately following the returned token. The function keeps track of its position in the string .I s1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the string immediately following that token. In this way subsequent calls work through the string .I s1 until no tokens remain. The separator string .I s2 can be different from call to call. When no token remains in .IR s1 , a null pointer is returned. .TP .C strtok_r() is identical to .CR strtok() , except that it expects to be passed the address of a character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a NULL value if there are no more tokens. .TP .C strcoll() Returns an integer greater than, equal to, or less than zero, according to whether the string pointed to by .I s1 is greater than, equal to, or less than the string pointed to by .IR s2 . The comparison is based on strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C strcoll() works like .CR strcmp() . .TP .C strxfrm() Transforms the string pointed to by .I s2 and places the resulting string into the array pointed to by .IR s1 . The transformation is such that if the .C strcmp() function is applied to two transformed strings, it returns a value greater than, equal to, or less than zero, corresponding to the result of the .C strcoll() function applied to the same two original strings. No more than .I n bytes are placed into the resulting string, including the terminating null character. If the transformed string fits in no more than .I n bytes, the length of the resulting string is returned (not including the terminating null character). Otherwise the return value is the number of bytes that the .I s1 string would occupy (not including the terminating null character), and the contents of the array are indeterminate. .PP .C strcoll() has better performance with respect to .C strxfrm() in cases where a given string is compared to other strings only a few times, or where the strings to be compared are long but a difference in the strings that determines their relative ordering usually comes among the first few characters. .C strxfrm() offers better performance in, for example, a sorting routine where a number of strings are each transformed just once and the transformed versions are compared against each other many times. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within the string arguments to the .CR strcoll() and .CR strxfrm() functions as single and/or multibyte characters. It also determines the case conversions to be done for the .C strcasecmp() and .C strncasecmp() functions. .PP The .C LC_COLLATE category determines the collation ordering used by the .CR strcoll() and .CR strxfrm() functions. See .IR hpnls (5) for a description of supported collation features. Use .C nlsinfo (see .IR nlsinfo (1)) to view the collation used for a particular locale. .SS International Code Set Support Single- and multibyte character code sets are supported for the .CR strcoll() and .CR strxfrm() functions. All other functions support only single-byte character code sets. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .C MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; char *s, *last, *tok[MAXTOK]; .PP tok[0] = strtok_r(s, " ", &last); while (tok[++i] = strtok_r(NULL, " ", &last)); .ft .ps .fi .RE .SH WARNINGS The functions .CR strcat() , .CR strncat() , .CR strcpy() , .CR strncpy() , .CR strtok() , and .C strtok_r() alter the contents of the array to which .I s1 points. They do not check for overflow of the array. .PP Null pointers for destination strings cause undefined behavior. .PP Character movement is performed differently in different implementations, so moves involving overlapping source and destination strings may yield surprises. .PP The transformed string produced by .C strxfrm() for a language using an 8-bit code set is usually at least twice as large as the original string and may be as much four times as large (ordinary characters occupy two bytes each in the transformed string, 1-to-2 characters four bytes, 2-to-1 characters two bytes per original pair, and don't-care characters no bytes). Each character of a multibyte code set (Asian languages) occupies three bytes in the transformed string. .PP For functions .CR strcoll() and .CR strxfrm() results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C strtok() is unsafe for multi-thread applications. .C strtok_r() is MT-Safe and should be used instead. .PP Users of .CR strtok_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH AUTHOR .C string() was developed by the University of California, Berkeley, AT&T, OSF, and HP. .SH SEE ALSO nlsinfo(1), conv(3C), malloc(3C), malloc(3X), memory(3C), setlocale(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR nl_strcmp() ": XPG2" .PP .CR nl_strncmp() ": XPG2" .PP .CR strcat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcoll() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR strcpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strcspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strdup() ": SVID2, SVID3" .PP .CR strlen() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncat() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncmp() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strncpy() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strpbrk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strrchr() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strspn() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strstr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strtok() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strxfrm() ": AES, SVID3, XPG3, XPG4, ANSI C" .\" .\" index@\f4strcat()\f1, \f4strncat()\f1 \- append string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strcmp()\f1, \f4strncmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcasecmp()\f1, \f4strncasecmp()\f1 \- compare two strings@@@\f3string(3C)\f1 .\" index@\f4strcpy()\f1, \f4strncpy()\f1 \- copy string 2 to string 1@@@\f3string(3C)\f1 .\" index@\f4strlen()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strdup()\f1 \- determine length of a string@@@\f3string(3C)\f1 .\" index@\f4strchr()\f1, \f4strrchr()\f1 \- get pointer to character in string@@@\f3string(3C)\f1 .\" index@\f4strpbrk()\f1 \- find occurrence of character from string 2 in string 1@@@\f3string(3C)\f1 .\" index@\f4strcspn()\f1, \f4strspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strspn()\f1, \f4strcspn()\f1 \- find length of matching substrings@@@\f3string(3C)\f1 .\" index@\f4strtok()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strtok_r()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strrstr()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strcoll()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4strxfrm()\f1 \- process string of text tokens@@@\f3string(3C)\f1 .\" index@\f4index()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f4rindex()\f1 \- BSD portability string routine@@@\f3string(3C)\f1 .\" index@\f1character string operations@@@\f3string(3C)\f1 .\" index@\f1string operations, character@@@\f3string(3C)\f1 .\" index@\f1strings, concatenate two@@@\f3string(3C)\f1 .\" index@\f1length of string, find@@@\f3string(3C)\f1 .\" index@\f1compare two strings@@@\f3string(3C)\f1 .\" index@\f1concatenate two strings@@@\f3string(3C)\f1 .\" .\" toc@\f3string(3C)\f1:\0\0\f4string\f1@@@character string operations .\" toc@\f4strcat()\f1, \f4strncat()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcmp()\f1, \f4strncmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcasecmp()\f1, \f4strncasecmp()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcpy()\f1, \f4strncpy()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strlen()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strdup()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strchr()\f1, \f4strrchr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strpbrk()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strrstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strspn()\f1, \f4strcspn()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strstr()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strtok_r()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strcoll()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4strxfrm()\f1:\0\0character string operations@@@see \f3string(3C)\f1 .\" toc@\f4index()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" toc@\f4rindex()\f1:\0\0BSD portability string routine@@@see \f3string(3C)\f1 .\" .\" links@string.3c strcat.3c .\" links@string.3c strncat.3c .\" links@string.3c strcmp.3c .\" links@string.3c strcasecmp.3c .\" links@string.3c strncasecmp.3c .\" links@string.3c strncmp.3c .\" links@string.3c strcpy.3c .\" links@string.3c strncpy.3c .\" links@string.3c strdup.3c .\" links@string.3c strlen.3c .\" links@string.3c strchr.3c .\" links@string.3c strrchr.3c .\" links@string.3c strpbrk.3c .\" links@string.3c strspn.3c .\" links@string.3c strcspn.3c .\" links@string.3c strstr.3c .\" links@string.3c strrstr.3c .\" links@string.3c strtok.3c .\" links@string.3c strtok_r.3c .\" links@string.3c strcoll.3c .\" links@string.3c strxfrm.3c .\" links@string.3c index.3c .\" links@string.3c rindex.3c .\" $Header: subpad.3x,v 76.2 95/08/01 14:49:45 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH subpad 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 subpad .SH NAME subpad \(em enhanced pad management function .SH SYNOPSIS .C "#include " .P .C "WINDOW *subpad(WINDOW *\f2orig\fP, int \f2nlines\fP, int \f2ncols\fP, int \f2begin_y\fP," .br .C " int \f2begin_x\fP);" .SH DESCRIPTION .P The .Fn subpad function creates a subwindow within a pad with \f2nlines\f1 lines and \f2ncols\f1 columns. Unlike .CR subwin() , which uses screen coordinates, the window is at position (\f2begin_y\f1, \f2begin_x\f1) on the pad. The window is made in the middle of the window \f2orig\f1, so that changes made to one window affect both windows. .SH "RETURN VALUE" .Fn subpad function returns a pointer to the pad data structure. Otherwise, it returns a null pointer. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" To refresh a pad, call .Fn prefresh or .CR pnoutrefresh() , not .CR wrefresh() . When porting code to use pads from WINDOWS, remember that these functions require additional arguments to specify the part of the pad to be displayed and the location on the screen to be used for the display. .P Although a subwindow and its parent pad may share memory representing characters in the pad, they need not share status information about what has changed in the pad. Therefore, after modifying a subwindow within a pad, it may be necessary to call .Fn touchwin or .Fn touchline on the pad before calling .CR prefresh() . .SH "SEE ALSO" derwin(), doupdate(), is_linetouched(), newpad(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4subpad()\f1 \- enhanced pad management function@@@\f3subpad(3X)\f1 .\" index@\f1pad, enhanced, management function@@@\f3subpad(3X)\f1 .\" index@\f1function, enhanced pad management@@@\f3subpad(3X)\f1 .\" .\" toc@\f3subpad(3X)\f1:\0\0\f4subpad()\f1@@@enhanced pad management function .\" .\" fileset_database@subpad.3x CURS-ENG-A-MAN .\" $Header: newwin.3x,v 76.2 95/08/01 14:28:38 ssa Exp $ .TA n .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH newwin 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME newwin, subwin \(em window creation functions .SH SYNOPSIS .C "#include " .P .C "WINDOW *newwin(int \f2nlines\fP, int \f2ncols\fP, int \f2begin_y\fP, int \f2begin_x\fP);" .P .C "WINDOW *subwin(WINDOW *\f2orig\fP, int \f2nlines\fP, int \f2ncols\fP, int \f2begin_y\fP," .br .C " int \f2begin_x\fP);" .SH DESCRIPTION .P The .Fn newwin function creates a new window with \f2nlines\f1 lines and \f2ncols\f1 columns, positioned so that the origin is (\f2begin_y\f1, \f2begin_x\f1). If \f2nlines\f1 is zero, it defaults to .CR LINES \(mi \f2begin_y\fP; if \f2ncols\f1 is zero, it defaults to .CR COLS \(mi \f2begin_x\f1. .P The .Fn subwin function creates a new window with \f2nlines\f1 lines and \f2ncols\f1 columns, positioned so that the origin is at (\f2begin_y\f1, \f2begin_x\f1). (This position is an absolute screen position, not a position relative to the window \f2orig\f1.) If any part of the new window is outside \f2orig\fP, the function fails and the window is not created. .SH "RETURN VALUE" Upon successful completion, these functions return a pointer to the new window. Otherwise, they return a null pointer. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Before performing the first refresh of a subwindow, portable applications should call .Fn touchwin or .Fn touchline on the parent window. .P Each window maintains internal descriptions of the screen image and status. The screen image is shared among all windows in the window hierarchy. Refresh operations rely on information on what has changed within a window, which is private to each window. Refreshing a window, when updates were made to a different window, may fail to perform needed updates because the windows do not share this information. .P A new full-screen window is created by calling: .IP .C "newwin(0, 0, 0, 0);" .PP .SH "SEE ALSO" delwin(), is_linetouched(), doupdate(), . .SH "CHANGE HISTORY" First released in Issue 2 .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" toc@\f3newwin(3X)\f1:\0\0\f4newwin()\f1, \f4subwin()\f1@@@window creation functions .\" toc@\f4subwin()\f1: window creation functions@@@see \f3subwin(3X)\f1 .\" .\" index@\f4newwin()\f1 \- window creation functions@@@\f3newwin(3X)\f1 .\" index@\f4subwin()\f1 \- window creation functions@@@\f3newwin(3X)\f1 .\" index@\f1window creation functions@@@\f3newwin(3X)\f1 .\" index@\f1functions, window creation functions@@@\f3newwin(3X)\f1 .\" index@\f1create, windows, functions@@@\f3newwin(3X)\f1 .\" .\" links@newwin.3x subwin.3x .\" .\" fileset_database@newwin.3x CURS-ENG-A-MAN .\" $Header: rpc_svc_create.3c,v 72.2 94/09/20 17:40:07 ssa Exp $ .TA r .TH rpc_svc_create 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_destroy, svcfd_create, svcraw_create, svctcp_create, svcudp_bufcreate \- library routines for dealing with the creation of server handles .SH SYNOPSIS .C "#include " .PP .nf .C "/* svc_destroy */" .C "void" .C "svc_destroy(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcfd_create */" .C "SVCXPRT *" .C "svcfd_create(fd, sendsz, recvsz)" .C "int fd;" .C "u_int sendsz, recvsz;" .fi .PP .nf .C "/* svcraw_create() */" .C "SVCXPRT *" .C "svcraw_create()" .fi .PP .nf .C "/* svctcp_create */" .C "SVCXPRT *" .C "svctcp_create(sock, sendsz, recvsz)" .C "int sock;" .C "u_int sendsz, recvsz;" .fi .PP .nf .C "/* svcudp_bufcreate */" .C "SVCXPRT *" .C "svcudp_bufcreate(sock, sendsz, recvsz)" .C "int sock;" .C "u_int sendsz, recvsz;" .fi .SH DESCRIPTION .PP RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .SS Routines .PP To run these routines, the C programs must include the header file, .CR . .PP The .CR SVCXPRT data structure is defined in .IR "Power Programming with RPC" . .TP 20 .C "svc_destroy" Destroy the RPC service transport handle, .IR xprt . Destruction usually involves deallocation of private data structures, including .I xprt itself. Use of .I xprt is undefined after calling this routine. .TP .C svcfd_create Create a service on top of any open and bound descriptor and return the handle to it. Typically, this descriptor is a connected socket for a stream protocol such as TCP. .I sendsz and .I recvsz indicate sizes for the send and receive buffers. If they are zero, a reasonable default is chosen. It returns .C NULL if it fails. .TP .C "svcraw_create()" Create an RPC service transport, to which it returns a pointer. The transport is a buffer within the process's address space, so the corresponding RPC client must live in the same address space; see .C clntraw_create() on .IR rpc_clnt_create (3C). This routine allows simulation of RPC and getting RPC overheads (such as round trip times), without any kernel interference. This routine returns .C NULL if it fails. .TP .C "svctcp_create" Create a TCP/IP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket .IR sock . If sock is .CR RPC_ANYSOCK , then a new socket is created. If the socket is not bound to a local TCP port, then this routine binds it to an arbitrary port. Upon completion, \f3\%xprt\->xp_sock\f1 is the transport's socket descriptor, and \f3\%xprt\->xp_port\f1 is the port number on which it is listening. This routine returns .C NULL if it fails. Since TCP-based RPC uses buffered I/O, users may specify the size of buffers with .I sendsz and .IR recvsz ; values of zero choose defaults. .TP .C "svcudp_bufcreate" Create a UDP/IP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket .IR sock . If sock is .CR RPC_ANYSOCK , a new socket is created. If the socket is not bound to a local UDP port, this routine binds it to an arbitrary port. Upon completion, \f3\%xprt\->xp_sock\f1 is the service's socket descriptor, and \f3\%xprt\->xp_port\f1 is the service's port number. This routine returns .C NULL if it fails. .IP The user specifies the maximum packet size for sending and receiving UDP-based RPC messages by using the .I sendsz and .I recvsz parameters. .br .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M), rpc(3C), rpc_clnt_create(3C), rpc_svc_calls(3C), rpc_svc_err(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3rpc_svc_create(3C)\f1:\0\0\f4svc_destroy()\f1,\f4svcraw_create()\f1, \f4svcfd_create()\f1, \f4svctcp_create()\f1,\n \f4svcudp_bufcreate()\f1@@@library routines for registering servers .\" toc@\f4svc_destroy()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcraw_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcfd_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svctcp_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcudp_bufcreate()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" index@\f4rpc_svc_create(3C)\f1library routines for dealing with the creation of server handles@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svc_destroy()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcraw_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcfd_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcudp_bufcreate()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svctcp_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" links@rpc_svc_create.3c svc_destroy.3c .\" links@rpc_svc_create.3c svcraw_create.3c .\" links@rpc_svc_create.3c svcfd_create.3c .\" links@rpc_svc_create.3c svcudp_bufcreate.3c .\" links@rpc_svc_create.3c svctcp_create.3c .\" $Header: rpc_svc_reg.3c,v 74.1 95/05/10 21:56:57 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_svc_reg 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_fds, svc_fdset, svc_freeargs, svc_getargs, svc_getcaller, svc_getreq, svc_getreqset, svc_run, svc_sendreply \- library routines for RPC servers .SH DESCRIPTION .B RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines are associated with the server side of the .B RPC mechanism. Some of them are called by the server side dispatch function, while others (such as .BR svc_run() ) are called when the server is initiated. .SS Routines The following routines require that the header .BR be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "int svc_fds;" .fi .IP Similar to .BR svc_fdset , but limited to 32 descriptors. This interface is obsoleted by .BR svc_fdset . .PP .nf .C "fd_set svc_fdset;" .fi .IP A global variable reflecting the .B RPC server's read file descriptor bit mask; it is suitable as a parameter to the .B select() system call. This is only of interest if a service implementor does not call .BR svc_run() , but rather does their own asynchronous event processing. This variable is read-only (do not pass its address to .BR select() !), yet it may change after calls to .B svc_getreqset() or any creation routines. .PP .nf .C "bool_t" .C "svc_freeargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Free any data allocated by the .B RPC/XDR system when it decoded the arguments to a service procedure using .BR svc_getargs() . This routine returns .B TRUE if the results were successfully freed, and .B FALSE otherwise. .PP .nf .C "bool_t" .C "svc_getargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Decode the arguments of an .B RPC request associated with the .B RPC service transport handle, .IR xprt . The parameter .I in is the address where the arguments will be placed; .I inproc is the .B XDR routine used to decode the arguments. This routine returns .B TRUE if decoding succeeds, and .B FALSE otherwise. .PP .nf .C "struct sockaddr_in *" .C "svc_getcaller(xprt)" .C "SVCXPRT *xprt;" .fi .IP The approved way of getting the network address of the caller of a procedure associated with the .B RPC service transport handle, .IR xprt . .PP .nf .C "void" .C "svc_getreq(rdfds)" .C "int rdfds;" .fi .IP Similar to .BR svc_getreqset() , but limited to 32 descriptors. This interface is obsoleted by .BR svc_getreqset() . .PP .nf .C "void" .C "svc_getreqset(rdfdsp)" .C "fd_set *rdfdsp;" .fi .IP This routine is only of interest if a service implementor does not use .BR svc_run() , but instead implements custom asynchronous event processing. It is called when the .B select() system call has determined that an .B RPC request has arrived on some .B RPC .B socket(s); .I rdfdsp is the resultant read file descriptor bit mask. The routine returns when all sockets associated with the value of .I rdfdsp have been serviced. .PP .nf .C "void" .C "svc_run()" .fi .IP Normally, this routine only returns in the case of some errors. It waits for .B RPC requests to arrive, and calls the appropriate service procedure using .B svc_getreq() when one arrives. This procedure is usually waiting for a .B select() system call to return. .PP .nf .C "bool_t" .C "svc_sendreply(xprt,outproc, out)" .C "SVCXPRT *xprt;" .C "xdrproc_t outproc;" .C "char *out;" .fi .IP Called by an .B RPC service's dispatch routine to send the results of a remote procedure call. The parameter .I xprt is the request's associated transport handle; .I outproc is the .B XDR routine which is used to encode the results; and .I out is the address of the results. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_sev_reg was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR select (2), .BR rpc (3C), .BR rpc_svc_calls (3C), .BR rpc_svc_create (3C), .BR rpc_svc_err (3C) .\" toc@\f3rpc_svc_reg(3C)\f1:\0\0\f4svc_fds()\f1, \f4svc_fdset()\f1, \f4svc_freeargs()\f1, \f4svc_getargs()\f1, \f4svc_getcaller()\f1, \n\f4svc_getreg()\f1, \f4svc_getreqset()\f1, \f4svc_run()\f1, \f4svc_sendreply()\f1@@@library routines for RPC servers .\" toc@\f4rpc_svc_reg()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fds()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fdset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_freeargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getcaller()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getreq()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_setreqset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_run()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_sednreply()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" index@library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4rpc_svc_reg()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fds()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fdset()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_freeargs()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getargs()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getcaller()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreq()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreqset()\fP \- library routines for RPC servers @@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_run()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_sendreply()\fP \- library routines for RPC servers@@@\f3rpc_scv_reg(3C)\f1 .\" links@rpc_svc_reg.3c svc_fds.3c .\" links@rpc_svc_reg.3c svc_fdset.3c .\" links@rpc_svc_reg.3c svc_freeargs.3c .\" links@rpc_svc_reg.3c svc_getargs.3c .\" links@rpc_svc_reg.3c svc_getcaller.3c .\" links@rpc_svc_reg.3c svc_getreq.3c .\" links@rpc_svc_reg.3c svc_getreqset.3c .\" links@rpc_svc_reg.3c svc_run.3c .\" links@rpc_svc_reg.3c svc_sendreply.3c .\" $Header: rpc_svc_reg.3c,v 74.1 95/05/10 21:56:57 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_svc_reg 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_fds, svc_fdset, svc_freeargs, svc_getargs, svc_getcaller, svc_getreq, svc_getreqset, svc_run, svc_sendreply \- library routines for RPC servers .SH DESCRIPTION .B RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines are associated with the server side of the .B RPC mechanism. Some of them are called by the server side dispatch function, while others (such as .BR svc_run() ) are called when the server is initiated. .SS Routines The following routines require that the header .BR be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "int svc_fds;" .fi .IP Similar to .BR svc_fdset , but limited to 32 descriptors. This interface is obsoleted by .BR svc_fdset . .PP .nf .C "fd_set svc_fdset;" .fi .IP A global variable reflecting the .B RPC server's read file descriptor bit mask; it is suitable as a parameter to the .B select() system call. This is only of interest if a service implementor does not call .BR svc_run() , but rather does their own asynchronous event processing. This variable is read-only (do not pass its address to .BR select() !), yet it may change after calls to .B svc_getreqset() or any creation routines. .PP .nf .C "bool_t" .C "svc_freeargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Free any data allocated by the .B RPC/XDR system when it decoded the arguments to a service procedure using .BR svc_getargs() . This routine returns .B TRUE if the results were successfully freed, and .B FALSE otherwise. .PP .nf .C "bool_t" .C "svc_getargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Decode the arguments of an .B RPC request associated with the .B RPC service transport handle, .IR xprt . The parameter .I in is the address where the arguments will be placed; .I inproc is the .B XDR routine used to decode the arguments. This routine returns .B TRUE if decoding succeeds, and .B FALSE otherwise. .PP .nf .C "struct sockaddr_in *" .C "svc_getcaller(xprt)" .C "SVCXPRT *xprt;" .fi .IP The approved way of getting the network address of the caller of a procedure associated with the .B RPC service transport handle, .IR xprt . .PP .nf .C "void" .C "svc_getreq(rdfds)" .C "int rdfds;" .fi .IP Similar to .BR svc_getreqset() , but limited to 32 descriptors. This interface is obsoleted by .BR svc_getreqset() . .PP .nf .C "void" .C "svc_getreqset(rdfdsp)" .C "fd_set *rdfdsp;" .fi .IP This routine is only of interest if a service implementor does not use .BR svc_run() , but instead implements custom asynchronous event processing. It is called when the .B select() system call has determined that an .B RPC request has arrived on some .B RPC .B socket(s); .I rdfdsp is the resultant read file descriptor bit mask. The routine returns when all sockets associated with the value of .I rdfdsp have been serviced. .PP .nf .C "void" .C "svc_run()" .fi .IP Normally, this routine only returns in the case of some errors. It waits for .B RPC requests to arrive, and calls the appropriate service procedure using .B svc_getreq() when one arrives. This procedure is usually waiting for a .B select() system call to return. .PP .nf .C "bool_t" .C "svc_sendreply(xprt,outproc, out)" .C "SVCXPRT *xprt;" .C "xdrproc_t outproc;" .C "char *out;" .fi .IP Called by an .B RPC service's dispatch routine to send the results of a remote procedure call. The parameter .I xprt is the request's associated transport handle; .I outproc is the .B XDR routine which is used to encode the results; and .I out is the address of the results. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_sev_reg was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR select (2), .BR rpc (3C), .BR rpc_svc_calls (3C), .BR rpc_svc_create (3C), .BR rpc_svc_err (3C) .\" toc@\f3rpc_svc_reg(3C)\f1:\0\0\f4svc_fds()\f1, \f4svc_fdset()\f1, \f4svc_freeargs()\f1, \f4svc_getargs()\f1, \f4svc_getcaller()\f1, \n\f4svc_getreg()\f1, \f4svc_getreqset()\f1, \f4svc_run()\f1, \f4svc_sendreply()\f1@@@library routines for RPC servers .\" toc@\f4rpc_svc_reg()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fds()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fdset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_freeargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getcaller()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getreq()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_setreqset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_run()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_sednreply()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" index@library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4rpc_svc_reg()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fds()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fdset()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_freeargs()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getargs()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getcaller()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreq()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreqset()\fP \- library routines for RPC servers @@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_run()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_sendreply()\fP \- library routines for RPC servers@@@\f3rpc_scv_reg(3C)\f1 .\" links@rpc_svc_reg.3c svc_fds.3c .\" links@rpc_svc_reg.3c svc_fdset.3c .\" links@rpc_svc_reg.3c svc_freeargs.3c .\" links@rpc_svc_reg.3c svc_getargs.3c .\" links@rpc_svc_reg.3c svc_getcaller.3c .\" links@rpc_svc_reg.3c svc_getreq.3c .\" links@rpc_svc_reg.3c svc_getreqset.3c .\" links@rpc_svc_reg.3c svc_run.3c .\" links@rpc_svc_reg.3c svc_sendreply.3c .\" $Header: rpc_svc_reg.3c,v 74.1 95/05/10 21:56:57 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_svc_reg 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_fds, svc_fdset, svc_freeargs, svc_getargs, svc_getcaller, svc_getreq, svc_getreqset, svc_run, svc_sendreply \- library routines for RPC servers .SH DESCRIPTION .B RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines are associated with the server side of the .B RPC mechanism. Some of them are called by the server side dispatch function, while others (such as .BR svc_run() ) are called when the server is initiated. .SS Routines The following routines require that the header .BR be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "int svc_fds;" .fi .IP Similar to .BR svc_fdset , but limited to 32 descriptors. This interface is obsoleted by .BR svc_fdset . .PP .nf .C "fd_set svc_fdset;" .fi .IP A global variable reflecting the .B RPC server's read file descriptor bit mask; it is suitable as a parameter to the .B select() system call. This is only of interest if a service implementor does not call .BR svc_run() , but rather does their own asynchronous event processing. This variable is read-only (do not pass its address to .BR select() !), yet it may change after calls to .B svc_getreqset() or any creation routines. .PP .nf .C "bool_t" .C "svc_freeargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Free any data allocated by the .B RPC/XDR system when it decoded the arguments to a service procedure using .BR svc_getargs() . This routine returns .B TRUE if the results were successfully freed, and .B FALSE otherwise. .PP .nf .C "bool_t" .C "svc_getargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Decode the arguments of an .B RPC request associated with the .B RPC service transport handle, .IR xprt . The parameter .I in is the address where the arguments will be placed; .I inproc is the .B XDR routine used to decode the arguments. This routine returns .B TRUE if decoding succeeds, and .B FALSE otherwise. .PP .nf .C "struct sockaddr_in *" .C "svc_getcaller(xprt)" .C "SVCXPRT *xprt;" .fi .IP The approved way of getting the network address of the caller of a procedure associated with the .B RPC service transport handle, .IR xprt . .PP .nf .C "void" .C "svc_getreq(rdfds)" .C "int rdfds;" .fi .IP Similar to .BR svc_getreqset() , but limited to 32 descriptors. This interface is obsoleted by .BR svc_getreqset() . .PP .nf .C "void" .C "svc_getreqset(rdfdsp)" .C "fd_set *rdfdsp;" .fi .IP This routine is only of interest if a service implementor does not use .BR svc_run() , but instead implements custom asynchronous event processing. It is called when the .B select() system call has determined that an .B RPC request has arrived on some .B RPC .B socket(s); .I rdfdsp is the resultant read file descriptor bit mask. The routine returns when all sockets associated with the value of .I rdfdsp have been serviced. .PP .nf .C "void" .C "svc_run()" .fi .IP Normally, this routine only returns in the case of some errors. It waits for .B RPC requests to arrive, and calls the appropriate service procedure using .B svc_getreq() when one arrives. This procedure is usually waiting for a .B select() system call to return. .PP .nf .C "bool_t" .C "svc_sendreply(xprt,outproc, out)" .C "SVCXPRT *xprt;" .C "xdrproc_t outproc;" .C "char *out;" .fi .IP Called by an .B RPC service's dispatch routine to send the results of a remote procedure call. The parameter .I xprt is the request's associated transport handle; .I outproc is the .B XDR routine which is used to encode the results; and .I out is the address of the results. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_sev_reg was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR select (2), .BR rpc (3C), .BR rpc_svc_calls (3C), .BR rpc_svc_create (3C), .BR rpc_svc_err (3C) .\" toc@\f3rpc_svc_reg(3C)\f1:\0\0\f4svc_fds()\f1, \f4svc_fdset()\f1, \f4svc_freeargs()\f1, \f4svc_getargs()\f1, \f4svc_getcaller()\f1, \n\f4svc_getreg()\f1, \f4svc_getreqset()\f1, \f4svc_run()\f1, \f4svc_sendreply()\f1@@@library routines for RPC servers .\" toc@\f4rpc_svc_reg()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fds()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fdset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_freeargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getcaller()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getreq()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_setreqset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_run()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_sednreply()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" index@library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4rpc_svc_reg()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fds()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fdset()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_freeargs()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getargs()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getcaller()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreq()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreqset()\fP \- library routines for RPC servers @@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_run()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_sendreply()\fP \- library routines for RPC servers@@@\f3rpc_scv_reg(3C)\f1 .\" links@rpc_svc_reg.3c svc_fds.3c .\" links@rpc_svc_reg.3c svc_fdset.3c .\" links@rpc_svc_reg.3c svc_freeargs.3c .\" links@rpc_svc_reg.3c svc_getargs.3c .\" links@rpc_svc_reg.3c svc_getcaller.3c .\" links@rpc_svc_reg.3c svc_getreq.3c .\" links@rpc_svc_reg.3c svc_getreqset.3c .\" links@rpc_svc_reg.3c svc_run.3c .\" links@rpc_svc_reg.3c svc_sendreply.3c .\" $Header: rpc_svc_reg.3c,v 74.1 95/05/10 21:56:57 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_svc_reg 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_fds, svc_fdset, svc_freeargs, svc_getargs, svc_getcaller, svc_getreq, svc_getreqset, svc_run, svc_sendreply \- library routines for RPC servers .SH DESCRIPTION .B RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines are associated with the server side of the .B RPC mechanism. Some of them are called by the server side dispatch function, while others (such as .BR svc_run() ) are called when the server is initiated. .SS Routines The following routines require that the header .BR be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "int svc_fds;" .fi .IP Similar to .BR svc_fdset , but limited to 32 descriptors. This interface is obsoleted by .BR svc_fdset . .PP .nf .C "fd_set svc_fdset;" .fi .IP A global variable reflecting the .B RPC server's read file descriptor bit mask; it is suitable as a parameter to the .B select() system call. This is only of interest if a service implementor does not call .BR svc_run() , but rather does their own asynchronous event processing. This variable is read-only (do not pass its address to .BR select() !), yet it may change after calls to .B svc_getreqset() or any creation routines. .PP .nf .C "bool_t" .C "svc_freeargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Free any data allocated by the .B RPC/XDR system when it decoded the arguments to a service procedure using .BR svc_getargs() . This routine returns .B TRUE if the results were successfully freed, and .B FALSE otherwise. .PP .nf .C "bool_t" .C "svc_getargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Decode the arguments of an .B RPC request associated with the .B RPC service transport handle, .IR xprt . The parameter .I in is the address where the arguments will be placed; .I inproc is the .B XDR routine used to decode the arguments. This routine returns .B TRUE if decoding succeeds, and .B FALSE otherwise. .PP .nf .C "struct sockaddr_in *" .C "svc_getcaller(xprt)" .C "SVCXPRT *xprt;" .fi .IP The approved way of getting the network address of the caller of a procedure associated with the .B RPC service transport handle, .IR xprt . .PP .nf .C "void" .C "svc_getreq(rdfds)" .C "int rdfds;" .fi .IP Similar to .BR svc_getreqset() , but limited to 32 descriptors. This interface is obsoleted by .BR svc_getreqset() . .PP .nf .C "void" .C "svc_getreqset(rdfdsp)" .C "fd_set *rdfdsp;" .fi .IP This routine is only of interest if a service implementor does not use .BR svc_run() , but instead implements custom asynchronous event processing. It is called when the .B select() system call has determined that an .B RPC request has arrived on some .B RPC .B socket(s); .I rdfdsp is the resultant read file descriptor bit mask. The routine returns when all sockets associated with the value of .I rdfdsp have been serviced. .PP .nf .C "void" .C "svc_run()" .fi .IP Normally, this routine only returns in the case of some errors. It waits for .B RPC requests to arrive, and calls the appropriate service procedure using .B svc_getreq() when one arrives. This procedure is usually waiting for a .B select() system call to return. .PP .nf .C "bool_t" .C "svc_sendreply(xprt,outproc, out)" .C "SVCXPRT *xprt;" .C "xdrproc_t outproc;" .C "char *out;" .fi .IP Called by an .B RPC service's dispatch routine to send the results of a remote procedure call. The parameter .I xprt is the request's associated transport handle; .I outproc is the .B XDR routine which is used to encode the results; and .I out is the address of the results. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_sev_reg was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR select (2), .BR rpc (3C), .BR rpc_svc_calls (3C), .BR rpc_svc_create (3C), .BR rpc_svc_err (3C) .\" toc@\f3rpc_svc_reg(3C)\f1:\0\0\f4svc_fds()\f1, \f4svc_fdset()\f1, \f4svc_freeargs()\f1, \f4svc_getargs()\f1, \f4svc_getcaller()\f1, \n\f4svc_getreg()\f1, \f4svc_getreqset()\f1, \f4svc_run()\f1, \f4svc_sendreply()\f1@@@library routines for RPC servers .\" toc@\f4rpc_svc_reg()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fds()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fdset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_freeargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getcaller()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getreq()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_setreqset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_run()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_sednreply()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" index@library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4rpc_svc_reg()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fds()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fdset()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_freeargs()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getargs()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getcaller()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreq()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreqset()\fP \- library routines for RPC servers @@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_run()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_sendreply()\fP \- library routines for RPC servers@@@\f3rpc_scv_reg(3C)\f1 .\" links@rpc_svc_reg.3c svc_fds.3c .\" links@rpc_svc_reg.3c svc_fdset.3c .\" links@rpc_svc_reg.3c svc_freeargs.3c .\" links@rpc_svc_reg.3c svc_getargs.3c .\" links@rpc_svc_reg.3c svc_getcaller.3c .\" links@rpc_svc_reg.3c svc_getreq.3c .\" links@rpc_svc_reg.3c svc_getreqset.3c .\" links@rpc_svc_reg.3c svc_run.3c .\" links@rpc_svc_reg.3c svc_sendreply.3c .\" $Header: rpc_svc_reg.3c,v 74.1 95/05/10 21:56:57 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_svc_reg 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_fds, svc_fdset, svc_freeargs, svc_getargs, svc_getcaller, svc_getreq, svc_getreqset, svc_run, svc_sendreply \- library routines for RPC servers .SH DESCRIPTION .B RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines are associated with the server side of the .B RPC mechanism. Some of them are called by the server side dispatch function, while others (such as .BR svc_run() ) are called when the server is initiated. .SS Routines The following routines require that the header .BR be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "int svc_fds;" .fi .IP Similar to .BR svc_fdset , but limited to 32 descriptors. This interface is obsoleted by .BR svc_fdset . .PP .nf .C "fd_set svc_fdset;" .fi .IP A global variable reflecting the .B RPC server's read file descriptor bit mask; it is suitable as a parameter to the .B select() system call. This is only of interest if a service implementor does not call .BR svc_run() , but rather does their own asynchronous event processing. This variable is read-only (do not pass its address to .BR select() !), yet it may change after calls to .B svc_getreqset() or any creation routines. .PP .nf .C "bool_t" .C "svc_freeargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Free any data allocated by the .B RPC/XDR system when it decoded the arguments to a service procedure using .BR svc_getargs() . This routine returns .B TRUE if the results were successfully freed, and .B FALSE otherwise. .PP .nf .C "bool_t" .C "svc_getargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Decode the arguments of an .B RPC request associated with the .B RPC service transport handle, .IR xprt . The parameter .I in is the address where the arguments will be placed; .I inproc is the .B XDR routine used to decode the arguments. This routine returns .B TRUE if decoding succeeds, and .B FALSE otherwise. .PP .nf .C "struct sockaddr_in *" .C "svc_getcaller(xprt)" .C "SVCXPRT *xprt;" .fi .IP The approved way of getting the network address of the caller of a procedure associated with the .B RPC service transport handle, .IR xprt . .PP .nf .C "void" .C "svc_getreq(rdfds)" .C "int rdfds;" .fi .IP Similar to .BR svc_getreqset() , but limited to 32 descriptors. This interface is obsoleted by .BR svc_getreqset() . .PP .nf .C "void" .C "svc_getreqset(rdfdsp)" .C "fd_set *rdfdsp;" .fi .IP This routine is only of interest if a service implementor does not use .BR svc_run() , but instead implements custom asynchronous event processing. It is called when the .B select() system call has determined that an .B RPC request has arrived on some .B RPC .B socket(s); .I rdfdsp is the resultant read file descriptor bit mask. The routine returns when all sockets associated with the value of .I rdfdsp have been serviced. .PP .nf .C "void" .C "svc_run()" .fi .IP Normally, this routine only returns in the case of some errors. It waits for .B RPC requests to arrive, and calls the appropriate service procedure using .B svc_getreq() when one arrives. This procedure is usually waiting for a .B select() system call to return. .PP .nf .C "bool_t" .C "svc_sendreply(xprt,outproc, out)" .C "SVCXPRT *xprt;" .C "xdrproc_t outproc;" .C "char *out;" .fi .IP Called by an .B RPC service's dispatch routine to send the results of a remote procedure call. The parameter .I xprt is the request's associated transport handle; .I outproc is the .B XDR routine which is used to encode the results; and .I out is the address of the results. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_sev_reg was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR select (2), .BR rpc (3C), .BR rpc_svc_calls (3C), .BR rpc_svc_create (3C), .BR rpc_svc_err (3C) .\" toc@\f3rpc_svc_reg(3C)\f1:\0\0\f4svc_fds()\f1, \f4svc_fdset()\f1, \f4svc_freeargs()\f1, \f4svc_getargs()\f1, \f4svc_getcaller()\f1, \n\f4svc_getreg()\f1, \f4svc_getreqset()\f1, \f4svc_run()\f1, \f4svc_sendreply()\f1@@@library routines for RPC servers .\" toc@\f4rpc_svc_reg()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fds()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fdset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_freeargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getcaller()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getreq()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_setreqset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_run()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_sednreply()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" index@library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4rpc_svc_reg()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fds()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fdset()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_freeargs()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getargs()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getcaller()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreq()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreqset()\fP \- library routines for RPC servers @@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_run()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_sendreply()\fP \- library routines for RPC servers@@@\f3rpc_scv_reg(3C)\f1 .\" links@rpc_svc_reg.3c svc_fds.3c .\" links@rpc_svc_reg.3c svc_fdset.3c .\" links@rpc_svc_reg.3c svc_freeargs.3c .\" links@rpc_svc_reg.3c svc_getargs.3c .\" links@rpc_svc_reg.3c svc_getcaller.3c .\" links@rpc_svc_reg.3c svc_getreq.3c .\" links@rpc_svc_reg.3c svc_getreqset.3c .\" links@rpc_svc_reg.3c svc_run.3c .\" links@rpc_svc_reg.3c svc_sendreply.3c .\" $Header: rpc_svc_reg.3c,v 74.1 95/05/10 21:56:57 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_svc_reg 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_fds, svc_fdset, svc_freeargs, svc_getargs, svc_getcaller, svc_getreq, svc_getreqset, svc_run, svc_sendreply \- library routines for RPC servers .SH DESCRIPTION .B RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines are associated with the server side of the .B RPC mechanism. Some of them are called by the server side dispatch function, while others (such as .BR svc_run() ) are called when the server is initiated. .SS Routines The following routines require that the header .BR be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "int svc_fds;" .fi .IP Similar to .BR svc_fdset , but limited to 32 descriptors. This interface is obsoleted by .BR svc_fdset . .PP .nf .C "fd_set svc_fdset;" .fi .IP A global variable reflecting the .B RPC server's read file descriptor bit mask; it is suitable as a parameter to the .B select() system call. This is only of interest if a service implementor does not call .BR svc_run() , but rather does their own asynchronous event processing. This variable is read-only (do not pass its address to .BR select() !), yet it may change after calls to .B svc_getreqset() or any creation routines. .PP .nf .C "bool_t" .C "svc_freeargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Free any data allocated by the .B RPC/XDR system when it decoded the arguments to a service procedure using .BR svc_getargs() . This routine returns .B TRUE if the results were successfully freed, and .B FALSE otherwise. .PP .nf .C "bool_t" .C "svc_getargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Decode the arguments of an .B RPC request associated with the .B RPC service transport handle, .IR xprt . The parameter .I in is the address where the arguments will be placed; .I inproc is the .B XDR routine used to decode the arguments. This routine returns .B TRUE if decoding succeeds, and .B FALSE otherwise. .PP .nf .C "struct sockaddr_in *" .C "svc_getcaller(xprt)" .C "SVCXPRT *xprt;" .fi .IP The approved way of getting the network address of the caller of a procedure associated with the .B RPC service transport handle, .IR xprt . .PP .nf .C "void" .C "svc_getreq(rdfds)" .C "int rdfds;" .fi .IP Similar to .BR svc_getreqset() , but limited to 32 descriptors. This interface is obsoleted by .BR svc_getreqset() . .PP .nf .C "void" .C "svc_getreqset(rdfdsp)" .C "fd_set *rdfdsp;" .fi .IP This routine is only of interest if a service implementor does not use .BR svc_run() , but instead implements custom asynchronous event processing. It is called when the .B select() system call has determined that an .B RPC request has arrived on some .B RPC .B socket(s); .I rdfdsp is the resultant read file descriptor bit mask. The routine returns when all sockets associated with the value of .I rdfdsp have been serviced. .PP .nf .C "void" .C "svc_run()" .fi .IP Normally, this routine only returns in the case of some errors. It waits for .B RPC requests to arrive, and calls the appropriate service procedure using .B svc_getreq() when one arrives. This procedure is usually waiting for a .B select() system call to return. .PP .nf .C "bool_t" .C "svc_sendreply(xprt,outproc, out)" .C "SVCXPRT *xprt;" .C "xdrproc_t outproc;" .C "char *out;" .fi .IP Called by an .B RPC service's dispatch routine to send the results of a remote procedure call. The parameter .I xprt is the request's associated transport handle; .I outproc is the .B XDR routine which is used to encode the results; and .I out is the address of the results. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_sev_reg was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR select (2), .BR rpc (3C), .BR rpc_svc_calls (3C), .BR rpc_svc_create (3C), .BR rpc_svc_err (3C) .\" toc@\f3rpc_svc_reg(3C)\f1:\0\0\f4svc_fds()\f1, \f4svc_fdset()\f1, \f4svc_freeargs()\f1, \f4svc_getargs()\f1, \f4svc_getcaller()\f1, \n\f4svc_getreg()\f1, \f4svc_getreqset()\f1, \f4svc_run()\f1, \f4svc_sendreply()\f1@@@library routines for RPC servers .\" toc@\f4rpc_svc_reg()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fds()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fdset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_freeargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getcaller()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getreq()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_setreqset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_run()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_sednreply()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" index@library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4rpc_svc_reg()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fds()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fdset()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_freeargs()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getargs()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getcaller()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreq()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreqset()\fP \- library routines for RPC servers @@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_run()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_sendreply()\fP \- library routines for RPC servers@@@\f3rpc_scv_reg(3C)\f1 .\" links@rpc_svc_reg.3c svc_fds.3c .\" links@rpc_svc_reg.3c svc_fdset.3c .\" links@rpc_svc_reg.3c svc_freeargs.3c .\" links@rpc_svc_reg.3c svc_getargs.3c .\" links@rpc_svc_reg.3c svc_getcaller.3c .\" links@rpc_svc_reg.3c svc_getreq.3c .\" links@rpc_svc_reg.3c svc_getreqset.3c .\" links@rpc_svc_reg.3c svc_run.3c .\" links@rpc_svc_reg.3c svc_sendreply.3c .\" $Header: rpc_svc_reg.3c,v 74.1 95/05/10 21:56:57 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_svc_reg 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_fds, svc_fdset, svc_freeargs, svc_getargs, svc_getcaller, svc_getreq, svc_getreqset, svc_run, svc_sendreply \- library routines for RPC servers .SH DESCRIPTION .B RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines are associated with the server side of the .B RPC mechanism. Some of them are called by the server side dispatch function, while others (such as .BR svc_run() ) are called when the server is initiated. .SS Routines The following routines require that the header .BR be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "int svc_fds;" .fi .IP Similar to .BR svc_fdset , but limited to 32 descriptors. This interface is obsoleted by .BR svc_fdset . .PP .nf .C "fd_set svc_fdset;" .fi .IP A global variable reflecting the .B RPC server's read file descriptor bit mask; it is suitable as a parameter to the .B select() system call. This is only of interest if a service implementor does not call .BR svc_run() , but rather does their own asynchronous event processing. This variable is read-only (do not pass its address to .BR select() !), yet it may change after calls to .B svc_getreqset() or any creation routines. .PP .nf .C "bool_t" .C "svc_freeargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Free any data allocated by the .B RPC/XDR system when it decoded the arguments to a service procedure using .BR svc_getargs() . This routine returns .B TRUE if the results were successfully freed, and .B FALSE otherwise. .PP .nf .C "bool_t" .C "svc_getargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Decode the arguments of an .B RPC request associated with the .B RPC service transport handle, .IR xprt . The parameter .I in is the address where the arguments will be placed; .I inproc is the .B XDR routine used to decode the arguments. This routine returns .B TRUE if decoding succeeds, and .B FALSE otherwise. .PP .nf .C "struct sockaddr_in *" .C "svc_getcaller(xprt)" .C "SVCXPRT *xprt;" .fi .IP The approved way of getting the network address of the caller of a procedure associated with the .B RPC service transport handle, .IR xprt . .PP .nf .C "void" .C "svc_getreq(rdfds)" .C "int rdfds;" .fi .IP Similar to .BR svc_getreqset() , but limited to 32 descriptors. This interface is obsoleted by .BR svc_getreqset() . .PP .nf .C "void" .C "svc_getreqset(rdfdsp)" .C "fd_set *rdfdsp;" .fi .IP This routine is only of interest if a service implementor does not use .BR svc_run() , but instead implements custom asynchronous event processing. It is called when the .B select() system call has determined that an .B RPC request has arrived on some .B RPC .B socket(s); .I rdfdsp is the resultant read file descriptor bit mask. The routine returns when all sockets associated with the value of .I rdfdsp have been serviced. .PP .nf .C "void" .C "svc_run()" .fi .IP Normally, this routine only returns in the case of some errors. It waits for .B RPC requests to arrive, and calls the appropriate service procedure using .B svc_getreq() when one arrives. This procedure is usually waiting for a .B select() system call to return. .PP .nf .C "bool_t" .C "svc_sendreply(xprt,outproc, out)" .C "SVCXPRT *xprt;" .C "xdrproc_t outproc;" .C "char *out;" .fi .IP Called by an .B RPC service's dispatch routine to send the results of a remote procedure call. The parameter .I xprt is the request's associated transport handle; .I outproc is the .B XDR routine which is used to encode the results; and .I out is the address of the results. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_sev_reg was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR select (2), .BR rpc (3C), .BR rpc_svc_calls (3C), .BR rpc_svc_create (3C), .BR rpc_svc_err (3C) .\" toc@\f3rpc_svc_reg(3C)\f1:\0\0\f4svc_fds()\f1, \f4svc_fdset()\f1, \f4svc_freeargs()\f1, \f4svc_getargs()\f1, \f4svc_getcaller()\f1, \n\f4svc_getreg()\f1, \f4svc_getreqset()\f1, \f4svc_run()\f1, \f4svc_sendreply()\f1@@@library routines for RPC servers .\" toc@\f4rpc_svc_reg()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fds()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fdset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_freeargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getcaller()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getreq()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_setreqset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_run()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_sednreply()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" index@library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4rpc_svc_reg()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fds()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fdset()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_freeargs()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getargs()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getcaller()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreq()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreqset()\fP \- library routines for RPC servers @@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_run()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_sendreply()\fP \- library routines for RPC servers@@@\f3rpc_scv_reg(3C)\f1 .\" links@rpc_svc_reg.3c svc_fds.3c .\" links@rpc_svc_reg.3c svc_fdset.3c .\" links@rpc_svc_reg.3c svc_freeargs.3c .\" links@rpc_svc_reg.3c svc_getargs.3c .\" links@rpc_svc_reg.3c svc_getcaller.3c .\" links@rpc_svc_reg.3c svc_getreq.3c .\" links@rpc_svc_reg.3c svc_getreqset.3c .\" links@rpc_svc_reg.3c svc_run.3c .\" links@rpc_svc_reg.3c svc_sendreply.3c .\" $Header: rpc_svc_calls.3c,v 74.1 95/05/10 21:56:31 ssa Exp $ .TA r .TH rpc_svc_calls 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME registerrpc, svc_register, svc_unregister, xprt_register, xprt_unregister \- library routines for registering servers .SH SYNOPSIS .C "#include " .PP .nf .C /* registerrpc */ .C "int" .C "registerrpc(prognum, versnum, procnum, procname, inproc, outproc)" .C "u_long prognum, versnum, procnum;" .C "char *(*procname) ();" .C "xdrproc_t inproc, outproc;" .fi .PP .nf .C "/* svc_register */" .C "bool_t" .C "svc_register(xprt, prognum, versnum, dispatch, protocol)" .C "SVCXPRT *xprt;" .C "u_long prognum, versnum;" .C "void (*dispatch) ();" .C "u_long protocol;" .fi .PP .nf .C "/* svc_unregister */ .C "void" .C "svc_unregister(prognum, versnum)" .C "u_long prognum, versnum;" .fi .PP .nf .C /* xprt_register */ .C "void" .C "xprt_register(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* xprt_unregister */" .C "void" .C "xprt_unregister(xprt)" .C "SVCXPRT *xprt;" .fi .SH DESCRIPTION These routines are a part of the RPC library, which allows the RPC servers to register themselves with .IR portmap (1M), and it associates the given program and version number with the dispatch function. .SS Routines .PP To use these routines, the C programs must include the header file .CR . .PP The .C SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP 20 .C registerrpc Register procedure .I procname with the RPC service package. If a request arrives for program .IR prognum , version .IR versnum , and procedure .IR procnum , .I procname is called with a pointer to its parameter; .I progname must be a procedure that returns a pointer to its static result; .I inproc is used to decode the parameters while .I outproc is used to encode the results. This routine returns 0 if the registration succeeded, \-1 otherwise. .IP .BR Warning : Remote procedures registered in this form are accessed using the UDP/IP transport; see .C svcudp_create() on .IR rpc_svc_create (3C) for restrictions. This routine should not be used more than once for the same program and version number. .TP .C svc_register Associates .I prognum and .I versnum with the service dispatch procedure, .IR dispatch . If .I protocol is zero, the service is not registered with the .C portmap service. If .I protocol is non-zero, a mapping of the triple .RI [ "prognum, versnum, protocol"\f1] to .C xprt->xp_port is established with the local .C portmap service (generally .I protocol is zero, .C IPPROTO_UDP or .CR IPPROTO_TCP ). The procedure .I dispatch has the following form: .RS 2i .PP .nf .C "dispatch(request, xprt)" .C "struct svc_req *request;" .C "SVCXPRT *xprt;" .ft R .fi .RE .IP The .B svc_register() routine returns .C TRUE if it succeeds, and .C FALSE otherwise. .TP .C svc_unregister Remove all mapping of the pair .RI [ prognum , versnum ] to dispatch routines, and of the triple .RI [ prognum , versnum , *\f1] to port number. .TP .C xprt_register After RPC service transport handles are created, they should register themselves with the RPC service package. This routine modifies the global variable .IR svc_fds . Service implementors usually do not need this routine. .TP .C xprt_unregister Before an RPC service transport handle is destroyed, it should unregister itself with the RPC service package. This routine modifies the global variable .IR svc_fds . Service implementors usually do not need this routine directly. .SH AUTHOR .C rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M), portmap(3C), rpc(3C), rpc_svc_err(3C), rpc_svc_create(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3rpc_svc_calls(3C)\f1:\0\0\f4registerrpc()\f1,\f4svc_register()\f1, \f4svc_unregister()\f1, \f4xprt_register()\f1,\n \f4xprt_unregister()\f1@@@library routines for registering servers .\" toc@\f4registerrpc()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4svc_register()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4svc_unregister()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4xprt_register()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4xprt_unregister()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" index@\f4rpc_svc_calls(3C)\f1library routines for registering servers@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4registerrpc()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4svc_register()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4svc_unregister()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4xprt_register()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4xprt_unregister()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" links@rpc_svc_calls.3c registerrpc.3c .\" links@rpc_svc_calls.3c svc_register.3c .\" links@rpc_svc_calls.3c svc_unregister.3c .\" links@rpc_svc_calls.3c xprt_register.3c .\" links@rpc_svc_calls.3c xprt_unregister.3c .\" $Header: rpc_svc_reg.3c,v 74.1 95/05/10 21:56:57 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_svc_reg 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_fds, svc_fdset, svc_freeargs, svc_getargs, svc_getcaller, svc_getreq, svc_getreqset, svc_run, svc_sendreply \- library routines for RPC servers .SH DESCRIPTION .B RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines are associated with the server side of the .B RPC mechanism. Some of them are called by the server side dispatch function, while others (such as .BR svc_run() ) are called when the server is initiated. .SS Routines The following routines require that the header .BR be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "int svc_fds;" .fi .IP Similar to .BR svc_fdset , but limited to 32 descriptors. This interface is obsoleted by .BR svc_fdset . .PP .nf .C "fd_set svc_fdset;" .fi .IP A global variable reflecting the .B RPC server's read file descriptor bit mask; it is suitable as a parameter to the .B select() system call. This is only of interest if a service implementor does not call .BR svc_run() , but rather does their own asynchronous event processing. This variable is read-only (do not pass its address to .BR select() !), yet it may change after calls to .B svc_getreqset() or any creation routines. .PP .nf .C "bool_t" .C "svc_freeargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Free any data allocated by the .B RPC/XDR system when it decoded the arguments to a service procedure using .BR svc_getargs() . This routine returns .B TRUE if the results were successfully freed, and .B FALSE otherwise. .PP .nf .C "bool_t" .C "svc_getargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Decode the arguments of an .B RPC request associated with the .B RPC service transport handle, .IR xprt . The parameter .I in is the address where the arguments will be placed; .I inproc is the .B XDR routine used to decode the arguments. This routine returns .B TRUE if decoding succeeds, and .B FALSE otherwise. .PP .nf .C "struct sockaddr_in *" .C "svc_getcaller(xprt)" .C "SVCXPRT *xprt;" .fi .IP The approved way of getting the network address of the caller of a procedure associated with the .B RPC service transport handle, .IR xprt . .PP .nf .C "void" .C "svc_getreq(rdfds)" .C "int rdfds;" .fi .IP Similar to .BR svc_getreqset() , but limited to 32 descriptors. This interface is obsoleted by .BR svc_getreqset() . .PP .nf .C "void" .C "svc_getreqset(rdfdsp)" .C "fd_set *rdfdsp;" .fi .IP This routine is only of interest if a service implementor does not use .BR svc_run() , but instead implements custom asynchronous event processing. It is called when the .B select() system call has determined that an .B RPC request has arrived on some .B RPC .B socket(s); .I rdfdsp is the resultant read file descriptor bit mask. The routine returns when all sockets associated with the value of .I rdfdsp have been serviced. .PP .nf .C "void" .C "svc_run()" .fi .IP Normally, this routine only returns in the case of some errors. It waits for .B RPC requests to arrive, and calls the appropriate service procedure using .B svc_getreq() when one arrives. This procedure is usually waiting for a .B select() system call to return. .PP .nf .C "bool_t" .C "svc_sendreply(xprt,outproc, out)" .C "SVCXPRT *xprt;" .C "xdrproc_t outproc;" .C "char *out;" .fi .IP Called by an .B RPC service's dispatch routine to send the results of a remote procedure call. The parameter .I xprt is the request's associated transport handle; .I outproc is the .B XDR routine which is used to encode the results; and .I out is the address of the results. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_sev_reg was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR select (2), .BR rpc (3C), .BR rpc_svc_calls (3C), .BR rpc_svc_create (3C), .BR rpc_svc_err (3C) .\" toc@\f3rpc_svc_reg(3C)\f1:\0\0\f4svc_fds()\f1, \f4svc_fdset()\f1, \f4svc_freeargs()\f1, \f4svc_getargs()\f1, \f4svc_getcaller()\f1, \n\f4svc_getreg()\f1, \f4svc_getreqset()\f1, \f4svc_run()\f1, \f4svc_sendreply()\f1@@@library routines for RPC servers .\" toc@\f4rpc_svc_reg()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fds()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fdset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_freeargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getcaller()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getreq()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_setreqset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_run()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_sednreply()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" index@library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4rpc_svc_reg()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fds()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fdset()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_freeargs()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getargs()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getcaller()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreq()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreqset()\fP \- library routines for RPC servers @@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_run()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_sendreply()\fP \- library routines for RPC servers@@@\f3rpc_scv_reg(3C)\f1 .\" links@rpc_svc_reg.3c svc_fds.3c .\" links@rpc_svc_reg.3c svc_fdset.3c .\" links@rpc_svc_reg.3c svc_freeargs.3c .\" links@rpc_svc_reg.3c svc_getargs.3c .\" links@rpc_svc_reg.3c svc_getcaller.3c .\" links@rpc_svc_reg.3c svc_getreq.3c .\" links@rpc_svc_reg.3c svc_getreqset.3c .\" links@rpc_svc_reg.3c svc_run.3c .\" links@rpc_svc_reg.3c svc_sendreply.3c .\" $Header: rpc_svc_reg.3c,v 74.1 95/05/10 21:56:57 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_svc_reg 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_fds, svc_fdset, svc_freeargs, svc_getargs, svc_getcaller, svc_getreq, svc_getreqset, svc_run, svc_sendreply \- library routines for RPC servers .SH DESCRIPTION .B RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines are associated with the server side of the .B RPC mechanism. Some of them are called by the server side dispatch function, while others (such as .BR svc_run() ) are called when the server is initiated. .SS Routines The following routines require that the header .BR be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "int svc_fds;" .fi .IP Similar to .BR svc_fdset , but limited to 32 descriptors. This interface is obsoleted by .BR svc_fdset . .PP .nf .C "fd_set svc_fdset;" .fi .IP A global variable reflecting the .B RPC server's read file descriptor bit mask; it is suitable as a parameter to the .B select() system call. This is only of interest if a service implementor does not call .BR svc_run() , but rather does their own asynchronous event processing. This variable is read-only (do not pass its address to .BR select() !), yet it may change after calls to .B svc_getreqset() or any creation routines. .PP .nf .C "bool_t" .C "svc_freeargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Free any data allocated by the .B RPC/XDR system when it decoded the arguments to a service procedure using .BR svc_getargs() . This routine returns .B TRUE if the results were successfully freed, and .B FALSE otherwise. .PP .nf .C "bool_t" .C "svc_getargs(xprt, inproc, in)" .C "SVCXPRT *xprt;" .C "xdrproc_t inproc;" .C "char *in;" .fi .IP Decode the arguments of an .B RPC request associated with the .B RPC service transport handle, .IR xprt . The parameter .I in is the address where the arguments will be placed; .I inproc is the .B XDR routine used to decode the arguments. This routine returns .B TRUE if decoding succeeds, and .B FALSE otherwise. .PP .nf .C "struct sockaddr_in *" .C "svc_getcaller(xprt)" .C "SVCXPRT *xprt;" .fi .IP The approved way of getting the network address of the caller of a procedure associated with the .B RPC service transport handle, .IR xprt . .PP .nf .C "void" .C "svc_getreq(rdfds)" .C "int rdfds;" .fi .IP Similar to .BR svc_getreqset() , but limited to 32 descriptors. This interface is obsoleted by .BR svc_getreqset() . .PP .nf .C "void" .C "svc_getreqset(rdfdsp)" .C "fd_set *rdfdsp;" .fi .IP This routine is only of interest if a service implementor does not use .BR svc_run() , but instead implements custom asynchronous event processing. It is called when the .B select() system call has determined that an .B RPC request has arrived on some .B RPC .B socket(s); .I rdfdsp is the resultant read file descriptor bit mask. The routine returns when all sockets associated with the value of .I rdfdsp have been serviced. .PP .nf .C "void" .C "svc_run()" .fi .IP Normally, this routine only returns in the case of some errors. It waits for .B RPC requests to arrive, and calls the appropriate service procedure using .B svc_getreq() when one arrives. This procedure is usually waiting for a .B select() system call to return. .PP .nf .C "bool_t" .C "svc_sendreply(xprt,outproc, out)" .C "SVCXPRT *xprt;" .C "xdrproc_t outproc;" .C "char *out;" .fi .IP Called by an .B RPC service's dispatch routine to send the results of a remote procedure call. The parameter .I xprt is the request's associated transport handle; .I outproc is the .B XDR routine which is used to encode the results; and .I out is the address of the results. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_sev_reg was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR select (2), .BR rpc (3C), .BR rpc_svc_calls (3C), .BR rpc_svc_create (3C), .BR rpc_svc_err (3C) .\" toc@\f3rpc_svc_reg(3C)\f1:\0\0\f4svc_fds()\f1, \f4svc_fdset()\f1, \f4svc_freeargs()\f1, \f4svc_getargs()\f1, \f4svc_getcaller()\f1, \n\f4svc_getreg()\f1, \f4svc_getreqset()\f1, \f4svc_run()\f1, \f4svc_sendreply()\f1@@@library routines for RPC servers .\" toc@\f4rpc_svc_reg()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fds()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_fdset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_freeargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getargs()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getcaller()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_getreq()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_setreqset()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_run()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" toc@\f4svc_sednreply()\f1: library routines for RPC servers@@@see \f3rpc_svc_reg(3C)\f1 .\" index@library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4rpc_svc_reg()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fds()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_fdset()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_freeargs()\f1 \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getargs()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getcaller()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreq()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_getreqset()\fP \- library routines for RPC servers @@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_run()\fP \- library routines for RPC servers@@@\f3rpc_svc_reg(3C)\f1 .\" index@\f4svc_sendreply()\fP \- library routines for RPC servers@@@\f3rpc_scv_reg(3C)\f1 .\" links@rpc_svc_reg.3c svc_fds.3c .\" links@rpc_svc_reg.3c svc_fdset.3c .\" links@rpc_svc_reg.3c svc_freeargs.3c .\" links@rpc_svc_reg.3c svc_getargs.3c .\" links@rpc_svc_reg.3c svc_getcaller.3c .\" links@rpc_svc_reg.3c svc_getreq.3c .\" links@rpc_svc_reg.3c svc_getreqset.3c .\" links@rpc_svc_reg.3c svc_run.3c .\" links@rpc_svc_reg.3c svc_sendreply.3c .\" $Header: rpc_svc_calls.3c,v 74.1 95/05/10 21:56:31 ssa Exp $ .TA r .TH rpc_svc_calls 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME registerrpc, svc_register, svc_unregister, xprt_register, xprt_unregister \- library routines for registering servers .SH SYNOPSIS .C "#include " .PP .nf .C /* registerrpc */ .C "int" .C "registerrpc(prognum, versnum, procnum, procname, inproc, outproc)" .C "u_long prognum, versnum, procnum;" .C "char *(*procname) ();" .C "xdrproc_t inproc, outproc;" .fi .PP .nf .C "/* svc_register */" .C "bool_t" .C "svc_register(xprt, prognum, versnum, dispatch, protocol)" .C "SVCXPRT *xprt;" .C "u_long prognum, versnum;" .C "void (*dispatch) ();" .C "u_long protocol;" .fi .PP .nf .C "/* svc_unregister */ .C "void" .C "svc_unregister(prognum, versnum)" .C "u_long prognum, versnum;" .fi .PP .nf .C /* xprt_register */ .C "void" .C "xprt_register(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* xprt_unregister */" .C "void" .C "xprt_unregister(xprt)" .C "SVCXPRT *xprt;" .fi .SH DESCRIPTION These routines are a part of the RPC library, which allows the RPC servers to register themselves with .IR portmap (1M), and it associates the given program and version number with the dispatch function. .SS Routines .PP To use these routines, the C programs must include the header file .CR . .PP The .C SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP 20 .C registerrpc Register procedure .I procname with the RPC service package. If a request arrives for program .IR prognum , version .IR versnum , and procedure .IR procnum , .I procname is called with a pointer to its parameter; .I progname must be a procedure that returns a pointer to its static result; .I inproc is used to decode the parameters while .I outproc is used to encode the results. This routine returns 0 if the registration succeeded, \-1 otherwise. .IP .BR Warning : Remote procedures registered in this form are accessed using the UDP/IP transport; see .C svcudp_create() on .IR rpc_svc_create (3C) for restrictions. This routine should not be used more than once for the same program and version number. .TP .C svc_register Associates .I prognum and .I versnum with the service dispatch procedure, .IR dispatch . If .I protocol is zero, the service is not registered with the .C portmap service. If .I protocol is non-zero, a mapping of the triple .RI [ "prognum, versnum, protocol"\f1] to .C xprt->xp_port is established with the local .C portmap service (generally .I protocol is zero, .C IPPROTO_UDP or .CR IPPROTO_TCP ). The procedure .I dispatch has the following form: .RS 2i .PP .nf .C "dispatch(request, xprt)" .C "struct svc_req *request;" .C "SVCXPRT *xprt;" .ft R .fi .RE .IP The .B svc_register() routine returns .C TRUE if it succeeds, and .C FALSE otherwise. .TP .C svc_unregister Remove all mapping of the pair .RI [ prognum , versnum ] to dispatch routines, and of the triple .RI [ prognum , versnum , *\f1] to port number. .TP .C xprt_register After RPC service transport handles are created, they should register themselves with the RPC service package. This routine modifies the global variable .IR svc_fds . Service implementors usually do not need this routine. .TP .C xprt_unregister Before an RPC service transport handle is destroyed, it should unregister itself with the RPC service package. This routine modifies the global variable .IR svc_fds . Service implementors usually do not need this routine directly. .SH AUTHOR .C rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M), portmap(3C), rpc(3C), rpc_svc_err(3C), rpc_svc_create(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3rpc_svc_calls(3C)\f1:\0\0\f4registerrpc()\f1,\f4svc_register()\f1, \f4svc_unregister()\f1, \f4xprt_register()\f1,\n \f4xprt_unregister()\f1@@@library routines for registering servers .\" toc@\f4registerrpc()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4svc_register()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4svc_unregister()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4xprt_register()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4xprt_unregister()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" index@\f4rpc_svc_calls(3C)\f1library routines for registering servers@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4registerrpc()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4svc_register()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4svc_unregister()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4xprt_register()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4xprt_unregister()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" links@rpc_svc_calls.3c registerrpc.3c .\" links@rpc_svc_calls.3c svc_register.3c .\" links@rpc_svc_calls.3c svc_unregister.3c .\" links@rpc_svc_calls.3c xprt_register.3c .\" links@rpc_svc_calls.3c xprt_unregister.3c .\" $Header: rpc_svc_err.3c,v 74.1 95/05/10 21:11:51 ssa Exp $ .TA r .TH rpc_svc_err 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog, svcerr_progvers, svcerr_systemerr, svcerr_weakauth \- library routines for server-side remote procedure call errors .SH SYNOPSIS .PP .nf .C "#include " .PP .nf .C "/* svcerr_auth */" .C "void" .C "svcerr_auth(xprt, why)" .C "SVCXPRT *xprt;" .C "enum auth_stat why;" .fi .PP .nf .C "/* svcerr_decode */" .C "void" .C "svcerr_decode(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_noproc */" .C "void" .C "svcerr_noproc(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_noprog */" .C "void" .C "svcerr_noprog(xprt)" .C "SVCXPRT *xprt;" .fi .PP .C "/* svcerr_progvers */" .nf .C "void" .C "svcerr_progvers(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_systemerr */" .C "void" .C "svcerr_systemerr(xprt)" .C "SVCXPRT *xprt;" .fi .PP .C "/* svcerr_weakauth */" .nf .C "void" .C "svcerr_weakauth(xprt)" .C "SVCXPRT *xprt;" .fi .SH DESCRIPTION .PP RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines can be called by the server side dispatch function if there is any error in the transaction with the client. .SS Routines The following routines require that the header file .RC < rpc.h > be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC" . .TP 20 .C svcerr_auth Called by a service dispatch routine that refuses to perform a remote procedure call, due to an authentication error. .TP .C "svcerr_decode" Called by a service dispatch routine that cannot successfully decode the remote parameters. See .CR svc_getargs() in .IR rpc_svc_reg (3C). .TP .C "svcerr_noproc" Called by a service dispatch routine that does not implement the procedure number the caller requests. .TP .C "svcerr_noprog" Called when the desired program is not registered with the RPC package. Service implementors usually do not need this routine. .TP .C "svcerr_progvers" Called when the desired version of a program is not registered with the RPC package. Service implementors usually do not need this routine. .TP .C "svcerr_systemerr" Called by a service dispatch routine when it detects a system error not covered by any particular protocol. For example, if a service can no longer allocate storage, it may call this routine. .TP .C "svcerr_weakauth" Called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient authentication parameters. The routine calls .CR "svcerr_auth(xprt, AUTH_TOOWEAK)" . .SH AUTHOR .C rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO rpc(3C), rpc_svc_calls(3C), rpc_svc_create(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3 rpc_svc_err(3C)\f1:\0\0\f4svcerr_auth()\f1,\f4svcerr_decode()\f1, \f4svcerr_noproc()\f1, \f4svcerr_progvers()\f1, \n \f4svcerr_systemerr()\f1, \f4svcerr_weakauth\f1 \n@@@library routines for server-side remote procedure call errors .\" toc@\f4svcerr_auth()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_decode()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_noproc()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_progvers()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_systemerr()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_weakauth()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" index@\f4rpc_svc_err(3C)\f1library routines for server-side RPC errors@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_auth()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_weakauth()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_decode()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_noproc()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_progvers()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_systemerr()\f1@@@\f3rpc_svc_err(3C)\f1 .\" links@rpc_svc_err.3c svcerr_auth.3c .\" links@rpc_svc_err.3c svcerr_weakauth.3c .\" links@rpc_svc_err.3c svcerr_decode.3c .\" links@rpc_svc_err.3c svcerr_noproc.3c .\" links@rpc_svc_err.3c svcerr_progvers.3c .\" links@rpc_svc_err.3c svcerr_systemerr.3c .\" $Header: rpc_svc_err.3c,v 74.1 95/05/10 21:11:51 ssa Exp $ .TA r .TH rpc_svc_err 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog, svcerr_progvers, svcerr_systemerr, svcerr_weakauth \- library routines for server-side remote procedure call errors .SH SYNOPSIS .PP .nf .C "#include " .PP .nf .C "/* svcerr_auth */" .C "void" .C "svcerr_auth(xprt, why)" .C "SVCXPRT *xprt;" .C "enum auth_stat why;" .fi .PP .nf .C "/* svcerr_decode */" .C "void" .C "svcerr_decode(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_noproc */" .C "void" .C "svcerr_noproc(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_noprog */" .C "void" .C "svcerr_noprog(xprt)" .C "SVCXPRT *xprt;" .fi .PP .C "/* svcerr_progvers */" .nf .C "void" .C "svcerr_progvers(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_systemerr */" .C "void" .C "svcerr_systemerr(xprt)" .C "SVCXPRT *xprt;" .fi .PP .C "/* svcerr_weakauth */" .nf .C "void" .C "svcerr_weakauth(xprt)" .C "SVCXPRT *xprt;" .fi .SH DESCRIPTION .PP RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines can be called by the server side dispatch function if there is any error in the transaction with the client. .SS Routines The following routines require that the header file .RC < rpc.h > be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC" . .TP 20 .C svcerr_auth Called by a service dispatch routine that refuses to perform a remote procedure call, due to an authentication error. .TP .C "svcerr_decode" Called by a service dispatch routine that cannot successfully decode the remote parameters. See .CR svc_getargs() in .IR rpc_svc_reg (3C). .TP .C "svcerr_noproc" Called by a service dispatch routine that does not implement the procedure number the caller requests. .TP .C "svcerr_noprog" Called when the desired program is not registered with the RPC package. Service implementors usually do not need this routine. .TP .C "svcerr_progvers" Called when the desired version of a program is not registered with the RPC package. Service implementors usually do not need this routine. .TP .C "svcerr_systemerr" Called by a service dispatch routine when it detects a system error not covered by any particular protocol. For example, if a service can no longer allocate storage, it may call this routine. .TP .C "svcerr_weakauth" Called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient authentication parameters. The routine calls .CR "svcerr_auth(xprt, AUTH_TOOWEAK)" . .SH AUTHOR .C rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO rpc(3C), rpc_svc_calls(3C), rpc_svc_create(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3 rpc_svc_err(3C)\f1:\0\0\f4svcerr_auth()\f1,\f4svcerr_decode()\f1, \f4svcerr_noproc()\f1, \f4svcerr_progvers()\f1, \n \f4svcerr_systemerr()\f1, \f4svcerr_weakauth\f1 \n@@@library routines for server-side remote procedure call errors .\" toc@\f4svcerr_auth()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_decode()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_noproc()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_progvers()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_systemerr()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_weakauth()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" index@\f4rpc_svc_err(3C)\f1library routines for server-side RPC errors@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_auth()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_weakauth()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_decode()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_noproc()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_progvers()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_systemerr()\f1@@@\f3rpc_svc_err(3C)\f1 .\" links@rpc_svc_err.3c svcerr_auth.3c .\" links@rpc_svc_err.3c svcerr_weakauth.3c .\" links@rpc_svc_err.3c svcerr_decode.3c .\" links@rpc_svc_err.3c svcerr_noproc.3c .\" links@rpc_svc_err.3c svcerr_progvers.3c .\" links@rpc_svc_err.3c svcerr_systemerr.3c .\" $Header: rpc_svc_err.3c,v 74.1 95/05/10 21:11:51 ssa Exp $ .TA r .TH rpc_svc_err 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog, svcerr_progvers, svcerr_systemerr, svcerr_weakauth \- library routines for server-side remote procedure call errors .SH SYNOPSIS .PP .nf .C "#include " .PP .nf .C "/* svcerr_auth */" .C "void" .C "svcerr_auth(xprt, why)" .C "SVCXPRT *xprt;" .C "enum auth_stat why;" .fi .PP .nf .C "/* svcerr_decode */" .C "void" .C "svcerr_decode(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_noproc */" .C "void" .C "svcerr_noproc(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_noprog */" .C "void" .C "svcerr_noprog(xprt)" .C "SVCXPRT *xprt;" .fi .PP .C "/* svcerr_progvers */" .nf .C "void" .C "svcerr_progvers(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_systemerr */" .C "void" .C "svcerr_systemerr(xprt)" .C "SVCXPRT *xprt;" .fi .PP .C "/* svcerr_weakauth */" .nf .C "void" .C "svcerr_weakauth(xprt)" .C "SVCXPRT *xprt;" .fi .SH DESCRIPTION .PP RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines can be called by the server side dispatch function if there is any error in the transaction with the client. .SS Routines The following routines require that the header file .RC < rpc.h > be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC" . .TP 20 .C svcerr_auth Called by a service dispatch routine that refuses to perform a remote procedure call, due to an authentication error. .TP .C "svcerr_decode" Called by a service dispatch routine that cannot successfully decode the remote parameters. See .CR svc_getargs() in .IR rpc_svc_reg (3C). .TP .C "svcerr_noproc" Called by a service dispatch routine that does not implement the procedure number the caller requests. .TP .C "svcerr_noprog" Called when the desired program is not registered with the RPC package. Service implementors usually do not need this routine. .TP .C "svcerr_progvers" Called when the desired version of a program is not registered with the RPC package. Service implementors usually do not need this routine. .TP .C "svcerr_systemerr" Called by a service dispatch routine when it detects a system error not covered by any particular protocol. For example, if a service can no longer allocate storage, it may call this routine. .TP .C "svcerr_weakauth" Called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient authentication parameters. The routine calls .CR "svcerr_auth(xprt, AUTH_TOOWEAK)" . .SH AUTHOR .C rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO rpc(3C), rpc_svc_calls(3C), rpc_svc_create(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3 rpc_svc_err(3C)\f1:\0\0\f4svcerr_auth()\f1,\f4svcerr_decode()\f1, \f4svcerr_noproc()\f1, \f4svcerr_progvers()\f1, \n \f4svcerr_systemerr()\f1, \f4svcerr_weakauth\f1 \n@@@library routines for server-side remote procedure call errors .\" toc@\f4svcerr_auth()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_decode()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_noproc()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_progvers()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_systemerr()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_weakauth()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" index@\f4rpc_svc_err(3C)\f1library routines for server-side RPC errors@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_auth()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_weakauth()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_decode()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_noproc()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_progvers()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_systemerr()\f1@@@\f3rpc_svc_err(3C)\f1 .\" links@rpc_svc_err.3c svcerr_auth.3c .\" links@rpc_svc_err.3c svcerr_weakauth.3c .\" links@rpc_svc_err.3c svcerr_decode.3c .\" links@rpc_svc_err.3c svcerr_noproc.3c .\" links@rpc_svc_err.3c svcerr_progvers.3c .\" links@rpc_svc_err.3c svcerr_systemerr.3c .\" $Header: rpc_svc_err.3c,v 74.1 95/05/10 21:11:51 ssa Exp $ .TA r .TH rpc_svc_err 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog, svcerr_progvers, svcerr_systemerr, svcerr_weakauth \- library routines for server-side remote procedure call errors .SH SYNOPSIS .PP .nf .C "#include " .PP .nf .C "/* svcerr_auth */" .C "void" .C "svcerr_auth(xprt, why)" .C "SVCXPRT *xprt;" .C "enum auth_stat why;" .fi .PP .nf .C "/* svcerr_decode */" .C "void" .C "svcerr_decode(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_noproc */" .C "void" .C "svcerr_noproc(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_noprog */" .C "void" .C "svcerr_noprog(xprt)" .C "SVCXPRT *xprt;" .fi .PP .C "/* svcerr_progvers */" .nf .C "void" .C "svcerr_progvers(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_systemerr */" .C "void" .C "svcerr_systemerr(xprt)" .C "SVCXPRT *xprt;" .fi .PP .C "/* svcerr_weakauth */" .nf .C "void" .C "svcerr_weakauth(xprt)" .C "SVCXPRT *xprt;" .fi .SH DESCRIPTION .PP RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines can be called by the server side dispatch function if there is any error in the transaction with the client. .SS Routines The following routines require that the header file .RC < rpc.h > be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC" . .TP 20 .C svcerr_auth Called by a service dispatch routine that refuses to perform a remote procedure call, due to an authentication error. .TP .C "svcerr_decode" Called by a service dispatch routine that cannot successfully decode the remote parameters. See .CR svc_getargs() in .IR rpc_svc_reg (3C). .TP .C "svcerr_noproc" Called by a service dispatch routine that does not implement the procedure number the caller requests. .TP .C "svcerr_noprog" Called when the desired program is not registered with the RPC package. Service implementors usually do not need this routine. .TP .C "svcerr_progvers" Called when the desired version of a program is not registered with the RPC package. Service implementors usually do not need this routine. .TP .C "svcerr_systemerr" Called by a service dispatch routine when it detects a system error not covered by any particular protocol. For example, if a service can no longer allocate storage, it may call this routine. .TP .C "svcerr_weakauth" Called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient authentication parameters. The routine calls .CR "svcerr_auth(xprt, AUTH_TOOWEAK)" . .SH AUTHOR .C rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO rpc(3C), rpc_svc_calls(3C), rpc_svc_create(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3 rpc_svc_err(3C)\f1:\0\0\f4svcerr_auth()\f1,\f4svcerr_decode()\f1, \f4svcerr_noproc()\f1, \f4svcerr_progvers()\f1, \n \f4svcerr_systemerr()\f1, \f4svcerr_weakauth\f1 \n@@@library routines for server-side remote procedure call errors .\" toc@\f4svcerr_auth()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_decode()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_noproc()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_progvers()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_systemerr()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_weakauth()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" index@\f4rpc_svc_err(3C)\f1library routines for server-side RPC errors@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_auth()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_weakauth()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_decode()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_noproc()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_progvers()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_systemerr()\f1@@@\f3rpc_svc_err(3C)\f1 .\" links@rpc_svc_err.3c svcerr_auth.3c .\" links@rpc_svc_err.3c svcerr_weakauth.3c .\" links@rpc_svc_err.3c svcerr_decode.3c .\" links@rpc_svc_err.3c svcerr_noproc.3c .\" links@rpc_svc_err.3c svcerr_progvers.3c .\" links@rpc_svc_err.3c svcerr_systemerr.3c .\" $Header: rpc_svc_err.3c,v 74.1 95/05/10 21:11:51 ssa Exp $ .TA r .TH rpc_svc_err 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog, svcerr_progvers, svcerr_systemerr, svcerr_weakauth \- library routines for server-side remote procedure call errors .SH SYNOPSIS .PP .nf .C "#include " .PP .nf .C "/* svcerr_auth */" .C "void" .C "svcerr_auth(xprt, why)" .C "SVCXPRT *xprt;" .C "enum auth_stat why;" .fi .PP .nf .C "/* svcerr_decode */" .C "void" .C "svcerr_decode(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_noproc */" .C "void" .C "svcerr_noproc(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_noprog */" .C "void" .C "svcerr_noprog(xprt)" .C "SVCXPRT *xprt;" .fi .PP .C "/* svcerr_progvers */" .nf .C "void" .C "svcerr_progvers(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_systemerr */" .C "void" .C "svcerr_systemerr(xprt)" .C "SVCXPRT *xprt;" .fi .PP .C "/* svcerr_weakauth */" .nf .C "void" .C "svcerr_weakauth(xprt)" .C "SVCXPRT *xprt;" .fi .SH DESCRIPTION .PP RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines can be called by the server side dispatch function if there is any error in the transaction with the client. .SS Routines The following routines require that the header file .RC < rpc.h > be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC" . .TP 20 .C svcerr_auth Called by a service dispatch routine that refuses to perform a remote procedure call, due to an authentication error. .TP .C "svcerr_decode" Called by a service dispatch routine that cannot successfully decode the remote parameters. See .CR svc_getargs() in .IR rpc_svc_reg (3C). .TP .C "svcerr_noproc" Called by a service dispatch routine that does not implement the procedure number the caller requests. .TP .C "svcerr_noprog" Called when the desired program is not registered with the RPC package. Service implementors usually do not need this routine. .TP .C "svcerr_progvers" Called when the desired version of a program is not registered with the RPC package. Service implementors usually do not need this routine. .TP .C "svcerr_systemerr" Called by a service dispatch routine when it detects a system error not covered by any particular protocol. For example, if a service can no longer allocate storage, it may call this routine. .TP .C "svcerr_weakauth" Called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient authentication parameters. The routine calls .CR "svcerr_auth(xprt, AUTH_TOOWEAK)" . .SH AUTHOR .C rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO rpc(3C), rpc_svc_calls(3C), rpc_svc_create(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3 rpc_svc_err(3C)\f1:\0\0\f4svcerr_auth()\f1,\f4svcerr_decode()\f1, \f4svcerr_noproc()\f1, \f4svcerr_progvers()\f1, \n \f4svcerr_systemerr()\f1, \f4svcerr_weakauth\f1 \n@@@library routines for server-side remote procedure call errors .\" toc@\f4svcerr_auth()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_decode()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_noproc()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_progvers()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_systemerr()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_weakauth()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" index@\f4rpc_svc_err(3C)\f1library routines for server-side RPC errors@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_auth()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_weakauth()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_decode()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_noproc()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_progvers()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_systemerr()\f1@@@\f3rpc_svc_err(3C)\f1 .\" links@rpc_svc_err.3c svcerr_auth.3c .\" links@rpc_svc_err.3c svcerr_weakauth.3c .\" links@rpc_svc_err.3c svcerr_decode.3c .\" links@rpc_svc_err.3c svcerr_noproc.3c .\" links@rpc_svc_err.3c svcerr_progvers.3c .\" links@rpc_svc_err.3c svcerr_systemerr.3c .\" $Header: rpc_svc_err.3c,v 74.1 95/05/10 21:11:51 ssa Exp $ .TA r .TH rpc_svc_err 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svcerr_auth, svcerr_decode, svcerr_noproc, svcerr_noprog, svcerr_progvers, svcerr_systemerr, svcerr_weakauth \- library routines for server-side remote procedure call errors .SH SYNOPSIS .PP .nf .C "#include " .PP .nf .C "/* svcerr_auth */" .C "void" .C "svcerr_auth(xprt, why)" .C "SVCXPRT *xprt;" .C "enum auth_stat why;" .fi .PP .nf .C "/* svcerr_decode */" .C "void" .C "svcerr_decode(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_noproc */" .C "void" .C "svcerr_noproc(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_noprog */" .C "void" .C "svcerr_noprog(xprt)" .C "SVCXPRT *xprt;" .fi .PP .C "/* svcerr_progvers */" .nf .C "void" .C "svcerr_progvers(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcerr_systemerr */" .C "void" .C "svcerr_systemerr(xprt)" .C "SVCXPRT *xprt;" .fi .PP .C "/* svcerr_weakauth */" .nf .C "void" .C "svcerr_weakauth(xprt)" .C "SVCXPRT *xprt;" .fi .SH DESCRIPTION .PP RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .PP These routines can be called by the server side dispatch function if there is any error in the transaction with the client. .SS Routines The following routines require that the header file .RC < rpc.h > be included. .PP The .B SVCXPRT data structure is defined in .IR "Power Programming with RPC" . .TP 20 .C svcerr_auth Called by a service dispatch routine that refuses to perform a remote procedure call, due to an authentication error. .TP .C "svcerr_decode" Called by a service dispatch routine that cannot successfully decode the remote parameters. See .CR svc_getargs() in .IR rpc_svc_reg (3C). .TP .C "svcerr_noproc" Called by a service dispatch routine that does not implement the procedure number the caller requests. .TP .C "svcerr_noprog" Called when the desired program is not registered with the RPC package. Service implementors usually do not need this routine. .TP .C "svcerr_progvers" Called when the desired version of a program is not registered with the RPC package. Service implementors usually do not need this routine. .TP .C "svcerr_systemerr" Called by a service dispatch routine when it detects a system error not covered by any particular protocol. For example, if a service can no longer allocate storage, it may call this routine. .TP .C "svcerr_weakauth" Called by a service dispatch routine that refuses to perform a remote procedure call due to insufficient authentication parameters. The routine calls .CR "svcerr_auth(xprt, AUTH_TOOWEAK)" . .SH AUTHOR .C rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO rpc(3C), rpc_svc_calls(3C), rpc_svc_create(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3 rpc_svc_err(3C)\f1:\0\0\f4svcerr_auth()\f1,\f4svcerr_decode()\f1, \f4svcerr_noproc()\f1, \f4svcerr_progvers()\f1, \n \f4svcerr_systemerr()\f1, \f4svcerr_weakauth\f1 \n@@@library routines for server-side remote procedure call errors .\" toc@\f4svcerr_auth()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_decode()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_noproc()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_progvers()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_systemerr()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" toc@\f4svcerr_weakauth()\f1:\0\0@@@see \f3rpc_svc_err(3C)\f1 .\" index@\f4rpc_svc_err(3C)\f1library routines for server-side RPC errors@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_auth()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_weakauth()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_decode()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_noproc()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_progvers()\f1@@@\f3rpc_svc_err(3C)\f1 .\" index@\f4svcerr_systemerr()\f1@@@\f3rpc_svc_err(3C)\f1 .\" links@rpc_svc_err.3c svcerr_auth.3c .\" links@rpc_svc_err.3c svcerr_weakauth.3c .\" links@rpc_svc_err.3c svcerr_decode.3c .\" links@rpc_svc_err.3c svcerr_noproc.3c .\" links@rpc_svc_err.3c svcerr_progvers.3c .\" links@rpc_svc_err.3c svcerr_systemerr.3c .\" $Header: rpc_svc_create.3c,v 72.2 94/09/20 17:40:07 ssa Exp $ .TA r .TH rpc_svc_create 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_destroy, svcfd_create, svcraw_create, svctcp_create, svcudp_bufcreate \- library routines for dealing with the creation of server handles .SH SYNOPSIS .C "#include " .PP .nf .C "/* svc_destroy */" .C "void" .C "svc_destroy(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcfd_create */" .C "SVCXPRT *" .C "svcfd_create(fd, sendsz, recvsz)" .C "int fd;" .C "u_int sendsz, recvsz;" .fi .PP .nf .C "/* svcraw_create() */" .C "SVCXPRT *" .C "svcraw_create()" .fi .PP .nf .C "/* svctcp_create */" .C "SVCXPRT *" .C "svctcp_create(sock, sendsz, recvsz)" .C "int sock;" .C "u_int sendsz, recvsz;" .fi .PP .nf .C "/* svcudp_bufcreate */" .C "SVCXPRT *" .C "svcudp_bufcreate(sock, sendsz, recvsz)" .C "int sock;" .C "u_int sendsz, recvsz;" .fi .SH DESCRIPTION .PP RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .SS Routines .PP To run these routines, the C programs must include the header file, .CR . .PP The .CR SVCXPRT data structure is defined in .IR "Power Programming with RPC" . .TP 20 .C "svc_destroy" Destroy the RPC service transport handle, .IR xprt . Destruction usually involves deallocation of private data structures, including .I xprt itself. Use of .I xprt is undefined after calling this routine. .TP .C svcfd_create Create a service on top of any open and bound descriptor and return the handle to it. Typically, this descriptor is a connected socket for a stream protocol such as TCP. .I sendsz and .I recvsz indicate sizes for the send and receive buffers. If they are zero, a reasonable default is chosen. It returns .C NULL if it fails. .TP .C "svcraw_create()" Create an RPC service transport, to which it returns a pointer. The transport is a buffer within the process's address space, so the corresponding RPC client must live in the same address space; see .C clntraw_create() on .IR rpc_clnt_create (3C). This routine allows simulation of RPC and getting RPC overheads (such as round trip times), without any kernel interference. This routine returns .C NULL if it fails. .TP .C "svctcp_create" Create a TCP/IP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket .IR sock . If sock is .CR RPC_ANYSOCK , then a new socket is created. If the socket is not bound to a local TCP port, then this routine binds it to an arbitrary port. Upon completion, \f3\%xprt\->xp_sock\f1 is the transport's socket descriptor, and \f3\%xprt\->xp_port\f1 is the port number on which it is listening. This routine returns .C NULL if it fails. Since TCP-based RPC uses buffered I/O, users may specify the size of buffers with .I sendsz and .IR recvsz ; values of zero choose defaults. .TP .C "svcudp_bufcreate" Create a UDP/IP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket .IR sock . If sock is .CR RPC_ANYSOCK , a new socket is created. If the socket is not bound to a local UDP port, this routine binds it to an arbitrary port. Upon completion, \f3\%xprt\->xp_sock\f1 is the service's socket descriptor, and \f3\%xprt\->xp_port\f1 is the service's port number. This routine returns .C NULL if it fails. .IP The user specifies the maximum packet size for sending and receiving UDP-based RPC messages by using the .I sendsz and .I recvsz parameters. .br .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M), rpc(3C), rpc_clnt_create(3C), rpc_svc_calls(3C), rpc_svc_err(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3rpc_svc_create(3C)\f1:\0\0\f4svc_destroy()\f1,\f4svcraw_create()\f1, \f4svcfd_create()\f1, \f4svctcp_create()\f1,\n \f4svcudp_bufcreate()\f1@@@library routines for registering servers .\" toc@\f4svc_destroy()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcraw_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcfd_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svctcp_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcudp_bufcreate()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" index@\f4rpc_svc_create(3C)\f1library routines for dealing with the creation of server handles@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svc_destroy()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcraw_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcfd_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcudp_bufcreate()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svctcp_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" links@rpc_svc_create.3c svc_destroy.3c .\" links@rpc_svc_create.3c svcraw_create.3c .\" links@rpc_svc_create.3c svcfd_create.3c .\" links@rpc_svc_create.3c svcudp_bufcreate.3c .\" links@rpc_svc_create.3c svctcp_create.3c .\" $Header: rpc_svc_create.3c,v 72.2 94/09/20 17:40:07 ssa Exp $ .TA r .TH rpc_svc_create 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_destroy, svcfd_create, svcraw_create, svctcp_create, svcudp_bufcreate \- library routines for dealing with the creation of server handles .SH SYNOPSIS .C "#include " .PP .nf .C "/* svc_destroy */" .C "void" .C "svc_destroy(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcfd_create */" .C "SVCXPRT *" .C "svcfd_create(fd, sendsz, recvsz)" .C "int fd;" .C "u_int sendsz, recvsz;" .fi .PP .nf .C "/* svcraw_create() */" .C "SVCXPRT *" .C "svcraw_create()" .fi .PP .nf .C "/* svctcp_create */" .C "SVCXPRT *" .C "svctcp_create(sock, sendsz, recvsz)" .C "int sock;" .C "u_int sendsz, recvsz;" .fi .PP .nf .C "/* svcudp_bufcreate */" .C "SVCXPRT *" .C "svcudp_bufcreate(sock, sendsz, recvsz)" .C "int sock;" .C "u_int sendsz, recvsz;" .fi .SH DESCRIPTION .PP RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .SS Routines .PP To run these routines, the C programs must include the header file, .CR . .PP The .CR SVCXPRT data structure is defined in .IR "Power Programming with RPC" . .TP 20 .C "svc_destroy" Destroy the RPC service transport handle, .IR xprt . Destruction usually involves deallocation of private data structures, including .I xprt itself. Use of .I xprt is undefined after calling this routine. .TP .C svcfd_create Create a service on top of any open and bound descriptor and return the handle to it. Typically, this descriptor is a connected socket for a stream protocol such as TCP. .I sendsz and .I recvsz indicate sizes for the send and receive buffers. If they are zero, a reasonable default is chosen. It returns .C NULL if it fails. .TP .C "svcraw_create()" Create an RPC service transport, to which it returns a pointer. The transport is a buffer within the process's address space, so the corresponding RPC client must live in the same address space; see .C clntraw_create() on .IR rpc_clnt_create (3C). This routine allows simulation of RPC and getting RPC overheads (such as round trip times), without any kernel interference. This routine returns .C NULL if it fails. .TP .C "svctcp_create" Create a TCP/IP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket .IR sock . If sock is .CR RPC_ANYSOCK , then a new socket is created. If the socket is not bound to a local TCP port, then this routine binds it to an arbitrary port. Upon completion, \f3\%xprt\->xp_sock\f1 is the transport's socket descriptor, and \f3\%xprt\->xp_port\f1 is the port number on which it is listening. This routine returns .C NULL if it fails. Since TCP-based RPC uses buffered I/O, users may specify the size of buffers with .I sendsz and .IR recvsz ; values of zero choose defaults. .TP .C "svcudp_bufcreate" Create a UDP/IP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket .IR sock . If sock is .CR RPC_ANYSOCK , a new socket is created. If the socket is not bound to a local UDP port, this routine binds it to an arbitrary port. Upon completion, \f3\%xprt\->xp_sock\f1 is the service's socket descriptor, and \f3\%xprt\->xp_port\f1 is the service's port number. This routine returns .C NULL if it fails. .IP The user specifies the maximum packet size for sending and receiving UDP-based RPC messages by using the .I sendsz and .I recvsz parameters. .br .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M), rpc(3C), rpc_clnt_create(3C), rpc_svc_calls(3C), rpc_svc_err(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3rpc_svc_create(3C)\f1:\0\0\f4svc_destroy()\f1,\f4svcraw_create()\f1, \f4svcfd_create()\f1, \f4svctcp_create()\f1,\n \f4svcudp_bufcreate()\f1@@@library routines for registering servers .\" toc@\f4svc_destroy()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcraw_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcfd_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svctcp_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcudp_bufcreate()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" index@\f4rpc_svc_create(3C)\f1library routines for dealing with the creation of server handles@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svc_destroy()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcraw_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcfd_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcudp_bufcreate()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svctcp_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" links@rpc_svc_create.3c svc_destroy.3c .\" links@rpc_svc_create.3c svcraw_create.3c .\" links@rpc_svc_create.3c svcfd_create.3c .\" links@rpc_svc_create.3c svcudp_bufcreate.3c .\" links@rpc_svc_create.3c svctcp_create.3c .\" $Header: rpc_svc_create.3c,v 72.2 94/09/20 17:40:07 ssa Exp $ .TA r .TH rpc_svc_create 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_destroy, svcfd_create, svcraw_create, svctcp_create, svcudp_bufcreate \- library routines for dealing with the creation of server handles .SH SYNOPSIS .C "#include " .PP .nf .C "/* svc_destroy */" .C "void" .C "svc_destroy(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcfd_create */" .C "SVCXPRT *" .C "svcfd_create(fd, sendsz, recvsz)" .C "int fd;" .C "u_int sendsz, recvsz;" .fi .PP .nf .C "/* svcraw_create() */" .C "SVCXPRT *" .C "svcraw_create()" .fi .PP .nf .C "/* svctcp_create */" .C "SVCXPRT *" .C "svctcp_create(sock, sendsz, recvsz)" .C "int sock;" .C "u_int sendsz, recvsz;" .fi .PP .nf .C "/* svcudp_bufcreate */" .C "SVCXPRT *" .C "svcudp_bufcreate(sock, sendsz, recvsz)" .C "int sock;" .C "u_int sendsz, recvsz;" .fi .SH DESCRIPTION .PP RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .SS Routines .PP To run these routines, the C programs must include the header file, .CR . .PP The .CR SVCXPRT data structure is defined in .IR "Power Programming with RPC" . .TP 20 .C "svc_destroy" Destroy the RPC service transport handle, .IR xprt . Destruction usually involves deallocation of private data structures, including .I xprt itself. Use of .I xprt is undefined after calling this routine. .TP .C svcfd_create Create a service on top of any open and bound descriptor and return the handle to it. Typically, this descriptor is a connected socket for a stream protocol such as TCP. .I sendsz and .I recvsz indicate sizes for the send and receive buffers. If they are zero, a reasonable default is chosen. It returns .C NULL if it fails. .TP .C "svcraw_create()" Create an RPC service transport, to which it returns a pointer. The transport is a buffer within the process's address space, so the corresponding RPC client must live in the same address space; see .C clntraw_create() on .IR rpc_clnt_create (3C). This routine allows simulation of RPC and getting RPC overheads (such as round trip times), without any kernel interference. This routine returns .C NULL if it fails. .TP .C "svctcp_create" Create a TCP/IP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket .IR sock . If sock is .CR RPC_ANYSOCK , then a new socket is created. If the socket is not bound to a local TCP port, then this routine binds it to an arbitrary port. Upon completion, \f3\%xprt\->xp_sock\f1 is the transport's socket descriptor, and \f3\%xprt\->xp_port\f1 is the port number on which it is listening. This routine returns .C NULL if it fails. Since TCP-based RPC uses buffered I/O, users may specify the size of buffers with .I sendsz and .IR recvsz ; values of zero choose defaults. .TP .C "svcudp_bufcreate" Create a UDP/IP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket .IR sock . If sock is .CR RPC_ANYSOCK , a new socket is created. If the socket is not bound to a local UDP port, this routine binds it to an arbitrary port. Upon completion, \f3\%xprt\->xp_sock\f1 is the service's socket descriptor, and \f3\%xprt\->xp_port\f1 is the service's port number. This routine returns .C NULL if it fails. .IP The user specifies the maximum packet size for sending and receiving UDP-based RPC messages by using the .I sendsz and .I recvsz parameters. .br .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M), rpc(3C), rpc_clnt_create(3C), rpc_svc_calls(3C), rpc_svc_err(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3rpc_svc_create(3C)\f1:\0\0\f4svc_destroy()\f1,\f4svcraw_create()\f1, \f4svcfd_create()\f1, \f4svctcp_create()\f1,\n \f4svcudp_bufcreate()\f1@@@library routines for registering servers .\" toc@\f4svc_destroy()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcraw_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcfd_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svctcp_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcudp_bufcreate()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" index@\f4rpc_svc_create(3C)\f1library routines for dealing with the creation of server handles@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svc_destroy()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcraw_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcfd_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcudp_bufcreate()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svctcp_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" links@rpc_svc_create.3c svc_destroy.3c .\" links@rpc_svc_create.3c svcraw_create.3c .\" links@rpc_svc_create.3c svcfd_create.3c .\" links@rpc_svc_create.3c svcudp_bufcreate.3c .\" links@rpc_svc_create.3c svctcp_create.3c .\" $Header: rpc_svc_create.3c,v 72.2 94/09/20 17:40:07 ssa Exp $ .TA r .TH rpc_svc_create 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME svc_destroy, svcfd_create, svcraw_create, svctcp_create, svcudp_bufcreate \- library routines for dealing with the creation of server handles .SH SYNOPSIS .C "#include " .PP .nf .C "/* svc_destroy */" .C "void" .C "svc_destroy(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* svcfd_create */" .C "SVCXPRT *" .C "svcfd_create(fd, sendsz, recvsz)" .C "int fd;" .C "u_int sendsz, recvsz;" .fi .PP .nf .C "/* svcraw_create() */" .C "SVCXPRT *" .C "svcraw_create()" .fi .PP .nf .C "/* svctcp_create */" .C "SVCXPRT *" .C "svctcp_create(sock, sendsz, recvsz)" .C "int sock;" .C "u_int sendsz, recvsz;" .fi .PP .nf .C "/* svcudp_bufcreate */" .C "SVCXPRT *" .C "svcudp_bufcreate(sock, sendsz, recvsz)" .C "int sock;" .C "u_int sendsz, recvsz;" .fi .SH DESCRIPTION .PP RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .SS Routines .PP To run these routines, the C programs must include the header file, .CR . .PP The .CR SVCXPRT data structure is defined in .IR "Power Programming with RPC" . .TP 20 .C "svc_destroy" Destroy the RPC service transport handle, .IR xprt . Destruction usually involves deallocation of private data structures, including .I xprt itself. Use of .I xprt is undefined after calling this routine. .TP .C svcfd_create Create a service on top of any open and bound descriptor and return the handle to it. Typically, this descriptor is a connected socket for a stream protocol such as TCP. .I sendsz and .I recvsz indicate sizes for the send and receive buffers. If they are zero, a reasonable default is chosen. It returns .C NULL if it fails. .TP .C "svcraw_create()" Create an RPC service transport, to which it returns a pointer. The transport is a buffer within the process's address space, so the corresponding RPC client must live in the same address space; see .C clntraw_create() on .IR rpc_clnt_create (3C). This routine allows simulation of RPC and getting RPC overheads (such as round trip times), without any kernel interference. This routine returns .C NULL if it fails. .TP .C "svctcp_create" Create a TCP/IP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket .IR sock . If sock is .CR RPC_ANYSOCK , then a new socket is created. If the socket is not bound to a local TCP port, then this routine binds it to an arbitrary port. Upon completion, \f3\%xprt\->xp_sock\f1 is the transport's socket descriptor, and \f3\%xprt\->xp_port\f1 is the port number on which it is listening. This routine returns .C NULL if it fails. Since TCP-based RPC uses buffered I/O, users may specify the size of buffers with .I sendsz and .IR recvsz ; values of zero choose defaults. .TP .C "svcudp_bufcreate" Create a UDP/IP-based RPC service transport, to which it returns a pointer. The transport is associated with the socket .IR sock . If sock is .CR RPC_ANYSOCK , a new socket is created. If the socket is not bound to a local UDP port, this routine binds it to an arbitrary port. Upon completion, \f3\%xprt\->xp_sock\f1 is the service's socket descriptor, and \f3\%xprt\->xp_port\f1 is the service's port number. This routine returns .C NULL if it fails. .IP The user specifies the maximum packet size for sending and receiving UDP-based RPC messages by using the .I sendsz and .I recvsz parameters. .br .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M), rpc(3C), rpc_clnt_create(3C), rpc_svc_calls(3C), rpc_svc_err(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3rpc_svc_create(3C)\f1:\0\0\f4svc_destroy()\f1,\f4svcraw_create()\f1, \f4svcfd_create()\f1, \f4svctcp_create()\f1,\n \f4svcudp_bufcreate()\f1@@@library routines for registering servers .\" toc@\f4svc_destroy()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcraw_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcfd_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svctcp_create()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" toc@\f4svcudp_bufcreate()\f1:\0\0@@@see \f3rpc_svc_create(3C)\f1 .\" index@\f4rpc_svc_create(3C)\f1library routines for dealing with the creation of server handles@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svc_destroy()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcraw_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcfd_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svcudp_bufcreate()\f1@@@\f3rpc_svc_create(3C)\f1 .\" index@\f4svctcp_create()\f1@@@\f3rpc_svc_create(3C)\f1 .\" links@rpc_svc_create.3c svc_destroy.3c .\" links@rpc_svc_create.3c svcraw_create.3c .\" links@rpc_svc_create.3c svcfd_create.3c .\" links@rpc_svc_create.3c svcudp_bufcreate.3c .\" links@rpc_svc_create.3c svctcp_create.3c .\" $Header: swab.3c,v 72.4 94/11/15 09:56:33 ssa Exp $ .TA s .TH swab 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME swab(\|) \- swap bytes .SH SYNOPSIS .C "#include " .PP .C "void swab(const void *from, void *to, ssize_t nbytes);" .SH DESCRIPTION .C swab() copies .I nbytes bytes pointed to by .I from to the array pointed to by .IR to , exchanging adjacent even and odd bytes. It is useful for carrying binary data between byte-swapped and non-byte-swapped machines. .I nbytes should be even and non-negative. If .I nbytes is odd and positive .C swab() uses .IR nbytes \-1 instead. If .I nbytes is negative, .C swab() does nothing. .SH STANDARDS CONFORMANCE .CR swab() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4swab()\fP \- swap bytes@@@\f3swab(3C)\f1 .\" index@swap bytes@@@\f3swab(3C)\f1 .\" index@bytes, swap@@@\f3swab(3C)\f1 .\" .\" toc@\f3swab(3C)\f1:\0\0\f4swab()\fP@@@swap bytes .\" .\" fileset_database@swab.3c PROGRAMING-MAN .\" $Header: syncok.3x,v 76.2 95/08/01 14:50:38 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH syncok 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME syncok, wcursyncup, wsyncdown, wsyncup \(em synchronise a window with its parents or children .SH SYNOPSIS .C "#include " .P .C "int syncok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "void wcursyncup(WINDOW *\f2win\fP);" .P .C "void wsyncdown(WINDOW *\f2win\fP);" .P .C "void wsyncup(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn syncok function determines whether all ancestors of the specified window are implicitly touched whenever there is a change in the window. If \f2bf\f1 is TRUE, such implicit touching occurs. If \f2bf\f1 is FALSE, such implicit touching does not occur. The initial state is FALSE. .P The .Fn wcursyncup function updates the current cursor position of the ancestors of \f2win\f1 to reflect the current cursor position of \f2win\f1. .P The .Fn wsyncdown function touches \f2win\f1 if any ancestor window has been touched. .P The .Fn wsyncup function unconditionally touches all ancestors of \f2win\f1. .SH "RETURN VALUE" Upon successful completion, .Fn syncok returns OK. Otherwise, it returns ERR. .P The other functions do not return a value. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Applications seldom call .Fn wsyncdown because it is called by all refresh operations. .SH "SEE ALSO" doupdate(), is_linetouched(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3syncok(3X)\f1:\0\0\f4syncok()\f1, \f4wcursyncup()\f1, \f4wsyncdown()\f1, \f4wsyncup()\f1\n@@@synchronise a window with its parents or children .\" toc@\f4wcursyncup()\f1: synchronise a window with its parents or children@@@see \f3syncok(3X)\f1 .\" toc@\f4wsyncdown()\f1: synchronise a window with its parents or children@@@see \f3syncok(3X)\f1 .\" toc@\f4wsyncup()\f1: synchronise a window with its parents or children@@@see \f3syncok(3X)\f1 .\" .\" index@\f4syncok()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f4wcursyncup()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f4wsyncup()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f4wsyncdown()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f1synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f1window, synchronise with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f1parents, synchronise a window with@@@\f3syncok(3X)\f1 .\" index@\f1children, synchronise a window with@@@\f3syncok(3X)\f1 .\" .\" links@syncok.3x wcursyncup.3x .\" links@syncok.3x wsyncup.3x .\" links@syncok.3x wsyncdown.3x .\" .\" fileset_database@syncok.3x CURS-ENG-A-MAN .\" $Header: perror.3c,v 74.1 95/03/23 18:05:29 ssa Exp $ .TA p .TH perror 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME perror(\|), strerror(\|), strerror_r(\|), errno, sys_errlist, sys_nerr \- system error messages .SH SYNOPSIS .C "#include " .PP .C "void perror(const char *s);" .PP .C "char *strerror(int errnum);" .PP .C "int strerror_r(int errnum, char *buffer, int buflen);" .PP .C "extern int errno;" .PP .C "extern char *sys_errlist[\|];" .PP .C "extern int sys_nerr;" .SH DESCRIPTION .CR perror() writes a language-dependent message to the standard error output, describing the last error encountered during a call to a system or library function. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. To be most useful, the argument string should include the name of the program that incurred the error. The error number is taken from the external variable .CR errno , which is set when errors occur but not cleared when non-erroneous calls are made. The contents of the message is identical to those returned by the .CR strerror() function with .CR errno as the argument. If given a .SM NULL string, the .CR perror() function prints only the message and a new-line. .PP To simplify variant formatting of messages, the .CR strerror() function and the .CR sys_errlist array of message strings are provided. The .CR strerror() function maps the error number in .I errnum to a language-dependent error message string and returns a pointer to the string. The message string is returned without a new-line. .CR errno can be used as an index into .CR sys_errlist to get an untranslated message string without the new-line. .CR sys_nerr is the largest message number provided for in the table; it should be checked because new error codes might be added to the system before they are added to the table. .CR strerror() must be used to retrieve messages when translations are desired. .PP .CR strerror_r() is identical to .CR strerror() , except that the result string is passed back in the supplied buffer. A buffer length of 80 is recommended. If an error is detected or the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .SH EXTERNAL INFLUENCES .SS Environment Variables The language of the message returned by .CR strerror() and printed by .CR perror() is specified by the .CR LANG environment variable. If the language-dependent message is not available, or if .CR LANG is not set or is set to the empty string, the default version of the message associated with the "C" language (see .IR lang (5)) is used. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .CR perror() returns no value. .PP If the .I errnum message number is valid, .CR strerror() returns a pointer to a language-dependent message string. The array pointed to should not be modified by the program, and might be overwritten by a subsequent call to the function. If a valid .I errnum message number does not have a corresponding language-dependent message, .CR strerror() uses .I errnum as an index into .CR sys_errlist to get the message string. If the .I errnum message number is invalid, .CR strerror() returns a pointer to a .SM NULL string. .SH WARNINGS The return value for .CR strerror() points to static data whose content is overwritten by each call. .CR strerror() is unsafe for multi-thread applications. .CR strerror_r() is MT-Safe and should be used instead. .br .ne 12v .SH SEE ALSO errno(2), lang(5), environ(5). .SH STANDARDS CONFORMANCE .CR perror() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strerror() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR sys_errlist() ": SVID2, SVID3, XPG2" .PP .CR sys_nerr() ": SVID2, SVID3, XPG2" .\" .\" index@\f4perror()\fP, \f4errno()\fP, \f4sys_errlist()\fP, \f4sys_nerr()\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4errno\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4strerror()\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4sys_errlist\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4sys_nerr\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@system error messages@@@\f3perror(3C)\f1 .\" index@error messages, system@@@\f3perror(3C)\f1 .\" index@messages, system error@@@\f3perror(3C)\f1 .\" .\" toc@\f3perror(3C)\f1:\0\0\f4perror()\fP, \f4errno()\fP, \f4sys_errlist()\f1, \f4sys_nerr()\f1@@@system error messages .\" toc@\f4errno\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4strerror()\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4sys_errlist\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4sys_nerr\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" .\" links@perror.3c strerror.3c .\" links@perror.3c strerror_r.3c .\" links@perror.3c errno.3c .\" links@perror.3c sys_errlist.3c .\" links@perror.3c sys_nerr.3c .\" $Header: perror.3c,v 74.1 95/03/23 18:05:29 ssa Exp $ .TA p .TH perror 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME perror(\|), strerror(\|), strerror_r(\|), errno, sys_errlist, sys_nerr \- system error messages .SH SYNOPSIS .C "#include " .PP .C "void perror(const char *s);" .PP .C "char *strerror(int errnum);" .PP .C "int strerror_r(int errnum, char *buffer, int buflen);" .PP .C "extern int errno;" .PP .C "extern char *sys_errlist[\|];" .PP .C "extern int sys_nerr;" .SH DESCRIPTION .CR perror() writes a language-dependent message to the standard error output, describing the last error encountered during a call to a system or library function. The argument string .I s is printed first, followed by a colon, a blank, the message, and a new-line. To be most useful, the argument string should include the name of the program that incurred the error. The error number is taken from the external variable .CR errno , which is set when errors occur but not cleared when non-erroneous calls are made. The contents of the message is identical to those returned by the .CR strerror() function with .CR errno as the argument. If given a .SM NULL string, the .CR perror() function prints only the message and a new-line. .PP To simplify variant formatting of messages, the .CR strerror() function and the .CR sys_errlist array of message strings are provided. The .CR strerror() function maps the error number in .I errnum to a language-dependent error message string and returns a pointer to the string. The message string is returned without a new-line. .CR errno can be used as an index into .CR sys_errlist to get an untranslated message string without the new-line. .CR sys_nerr is the largest message number provided for in the table; it should be checked because new error codes might be added to the system before they are added to the table. .CR strerror() must be used to retrieve messages when translations are desired. .PP .CR strerror_r() is identical to .CR strerror() , except that the result string is passed back in the supplied buffer. A buffer length of 80 is recommended. If an error is detected or the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .SH EXTERNAL INFLUENCES .SS Environment Variables The language of the message returned by .CR strerror() and printed by .CR perror() is specified by the .CR LANG environment variable. If the language-dependent message is not available, or if .CR LANG is not set or is set to the empty string, the default version of the message associated with the "C" language (see .IR lang (5)) is used. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE .CR perror() returns no value. .PP If the .I errnum message number is valid, .CR strerror() returns a pointer to a language-dependent message string. The array pointed to should not be modified by the program, and might be overwritten by a subsequent call to the function. If a valid .I errnum message number does not have a corresponding language-dependent message, .CR strerror() uses .I errnum as an index into .CR sys_errlist to get the message string. If the .I errnum message number is invalid, .CR strerror() returns a pointer to a .SM NULL string. .SH WARNINGS The return value for .CR strerror() points to static data whose content is overwritten by each call. .CR strerror() is unsafe for multi-thread applications. .CR strerror_r() is MT-Safe and should be used instead. .br .ne 12v .SH SEE ALSO errno(2), lang(5), environ(5). .SH STANDARDS CONFORMANCE .CR perror() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR strerror() ": AES, SVID3, XPG3, XPG4, ANSI C" .PP .CR sys_errlist() ": SVID2, SVID3, XPG2" .PP .CR sys_nerr() ": SVID2, SVID3, XPG2" .\" .\" index@\f4perror()\fP, \f4errno()\fP, \f4sys_errlist()\fP, \f4sys_nerr()\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4errno\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4strerror()\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4sys_errlist\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@\f4sys_nerr\fP \- system error messages@@@\f3perror(3C)\f1 .\" index@system error messages@@@\f3perror(3C)\f1 .\" index@error messages, system@@@\f3perror(3C)\f1 .\" index@messages, system error@@@\f3perror(3C)\f1 .\" .\" toc@\f3perror(3C)\f1:\0\0\f4perror()\fP, \f4errno()\fP, \f4sys_errlist()\f1, \f4sys_nerr()\f1@@@system error messages .\" toc@\f4errno\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4strerror()\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4sys_errlist\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" toc@\f4sys_nerr\fP:\0\0system error messages@@@see \f3perror(3C)\f1 .\" .\" links@perror.3c strerror.3c .\" links@perror.3c strerror_r.3c .\" links@perror.3c errno.3c .\" links@perror.3c sys_errlist.3c .\" links@perror.3c sys_nerr.3c .\" $Header: syslog.3c,v 76.1 95/07/05 17:52:44 ssa Exp $ .TA s .TH syslog 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME syslog(\|), openlog(\|), closelog(\|), setlogmask(\|) \- control system log .SH SYNOPSIS .C "#include " .PP .C "void syslog(int priority, const char *message, ...);" .PP .C "void openlog(const char *ident, int logopt, int facility);" .PP .C "void closelog(void);" .PP .C "int setlogmask(int maskpri);" .SS Remarks The ANSI C "\c .CR ", ...\$\c" " construct denotes a variable length argument list whose optional [or required] \" EDITOR: make this line fit the specific page members are given in the associated comment .RC ( "/* */" ). .SH DESCRIPTION .TP 15 .C syslog() writes a message onto the system log maintained by .CR syslogd (see .IR syslogd (1M)). The message is tagged with .IR priority . The .I message is similar to a .IR printf (3S) format string except that .CR %m is replaced by the error message associated with the current value of .CR errno . A trailing newline is added if needed. .IP This message is read by .CR syslogd and written to the system console, log files, selected users' terminals, or forwarded to .CR syslogd on another host as appropriate. .IP .I priority is encoded as the logical OR of a .I level and a .IR facility . The .I level signifies the urgency of the message, and .I facility signifies the subsystem generating the message. .I facility can be encoded explicitly in .IR priority , or a default .I facility can be set with .CR openlog() (see below). .IP .I level is selected from an ordered list: .RS .RS .TP 20 .C LOG_EMERG A panic condition. This is normally broadcast to all users. .TP .C LOG_ALERT A condition that should be corrected immediately, such as a corrupted system database. .TP .C LOG_CRIT Critical conditions, such as hard device errors. .TP .C LOG_ERR Errors. .TP .C LOG_WARNING Warning messages. .TP .C LOG_NOTICE Conditions that are not error conditions, but should possibly be handled specially. .TP .C LOG_INFO Informational messages. .TP .C LOG_DEBUG Messages that contain information normally of use only when debugging a program. .RE .RE .IP .CR syslog() does not log a message that does not have a .I level set. .IP If .CR syslog() cannot pass the message to .CR syslogd , it attempts to write the message on .CR /dev/console if the .CR LOG_CONS option is set (see below). .TP .C openlog() can be called to initialize the log file, if special processing is needed. .I ident is a string that precedes every message. .I logopt is a mask of bits, logically OR'ed together, indicating logging options. The values for .I logopt are: .RS .RS .TP 20 .C LOG_PID Log the process ID with each message; useful for identifying instantiations of daemons. .TP .C LOG_CONS Force writing messages to the console if unable to send it to .CR syslogd . This option is safe to use in daemon processes that have no controlling terminal because .CR syslog() forks before opening the console. .TP .C LOG_NDELAY Open the connection to .CR syslogd immediately. Normally, the open is delayed until the first message is logged. This is useful for programs that need to manage the order in which file descriptors are allocated. .TP .C LOG_NOWAIT Do not wait for children forked to log messages on the console. This option should be used by processes that enable notification of child termination via .CR SIGCLD , because .CR syslog() might otherwise block, waiting for a child whose exit status has already been collected. .RE .RE .IP .I facility encodes a default facility to be assigned to all messages written subsequently by .CR syslog() with no explicit facility encoded. .IP .RS .RS .TP 20 .C LOG_KERN Messages generated by the kernel. These cannot be generated by any user processes. .TP .C LOG_USER Messages generated by random user processes. This is the default facility identifier if none is specified. .TP .C LOG_MAIL The mail system. .TP .C LOG_DAEMON System daemons, such as .IR inetd (1M), .IR ftpd (1M), etc. .TP .C LOG_AUTH The authorization system: .IR login (1), .IR su (1), .IR getty (1M), etc. .TP .C LOG_LPR The line printer spooling system: .IR lp (1), .IR lpsched (1M), etc. .TP .C LOG_LOCAL0 Reserved for local use. Similarly for .CR LOG_LOCAL1 through .CR LOG_LOCAL7 . .RE .RE .TP .C closelog() closes the log file. .TP .C setlogmask() sets the log priority mask to .I maskpri and returns the previous mask. Calls to .CR syslog() with a priority not set in .I maskpri are rejected. The mask for an individual priority .I pri is calculated by the macro .CI LOG_MASK( pri )\c ; the mask for all priorities up to and including .I toppri is given by the macro .CR LOG_UPTO\c .RI ( toppri ). By default, all priorities are logged. .SH ERRORS .CR syslog fails if any of the following conditions are encountered: .RS .TP 15 [EAGAIN] The named pipe .CR /dev/log is blocked for writing. .TP [ENOENT] The named pipe .CR /dev/log bold) could not be opened successfully. .SH EXAMPLES .CR who logs a message regarding some sort of unexpected and serious error: .IP .C "syslog(LOG_ALERT, ""who: internal error 23"");" .PP .CR ftpd uses .CR openlog() to arrange to log its process ID, to log to the console if necessary, and to log in the name of the .I daemon facility: .IP .C "openlog(""ftpd"", LOG_PID|LOG_CONS, LOG_DAEMON);" .PP Arrange to log messages only at levels .CR LOG_ERR and lower: .IP .C setlogmask(LOG_UPTO(LOG_ERR)); .PP Typical usage of .CR syslog() to log a connection: .IP .C "syslog(LOG_INFO,\ ""Connection\ from\ host\ %d"",\ CallingHost);" .PP If the facility has not been set with .CR openlog() , it defaults to .CR LOG_USER . .PP Explicitly set the facility for this message: .IP .C "syslog(LOG_INFO|LOG_LOCAL2,\ ""foobar\ error:\ %m"");" .SH WARNINGS A call to .CR syslog() has no effect unless the syslog daemon .RI ( syslogd (1M)) is running. .CR openlog() does not copy and store the .I ident string internally; it stores only a character pointer. Therefore it is the responsibility of the programmer to make sure that the .I ident argument points to the correct string until the log file is closed. .SH AUTHOR .CR syslog() was developed by the University of California, Berkeley. .SH SEE ALSO logger(1), syslogd(1M). .\" .\" index@\f4syslog()\f1 \- write message onto system log file@@@\f3syslog(3C)\f1 .\" index@\f4openlog()\f1 \- initialize system log file@@@\f3syslog(3C)\f1 .\" index@\f4closelog()\f1 \- close system log file@@@\f3syslog(3C)\f1 .\" index@\f4setlogmask()\f1 \- set system log file priority mask@@@\f3syslog(3C)\f1 .\" index@control system log@@@\f3syslog(3C)\f1 .\" index@system log, control@@@\f3syslog(3C)\f1 .\" index@log, system, control@@@\f3syslog(3C)\f1 .\" .\" toc@\f3syslog(3C)\f1:\0\0\f4syslog()\f1, \f4openlog()\f1, \f4closelog()\f1, \f4setlogmask()\fP@@@control system log .\" toc@\f4openlog()\f1:\0\0control system log@@@see \f3syslog(3C)\f1 .\" toc@\f4closelog()\f1:\0\0control system log@@@see \f3syslog(3C)\f1 .\" toc@\f4setlogmask()\f1:\0\0control system log@@@see \f3syslog(3C)\f1 .\" .\" links@syslog.3c openlog.3c .\" links@syslog.3c closelog.3c .\" links@syslog.3c setlogmask.3c .\" .\" fileset_database@syslog.3c PROGRAMING-MAN .\" $Header: system.3s,v 72.5 94/11/15 09:56:35 ssa Exp $ .TA s .TH system 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME system(\|) \- issue a shell command .SH SYNOPSIS .C "#include " .PP .C "int system(const char *command);" .SH DESCRIPTION .CR system() executes the command specified by the string pointed to by .IR command . The environment of the executed command is as if a child process were created using .C fork() (see .IR fork (2)), and the child process invoked the .IR sh-posix (1) utility via a call to .C execl() (see .IR execl (2)) as follows: .IP .ift \f4\s+1execl("/usr/bin/sh", "sh", "\-c", \f2command\f1, 0);\fP\s0 .ifn \f3execl("/usr/bin/sh", "sh", "\-c", \f2command\f1, 0);\fP .PP .CR system() ignores the .C SIGINT and .C SIGQUIT signals, and blocks the .C SIGCHLD signal, while waiting for the command to terminate. If this might cause the application to miss a signal that would have killed it, the application should examine the return value from .C system() and take whatever action is appropriate to the application if the command terminated due to receipt of a signal. .PP .C system() does not affect the termination status of any child of the calling processes other than the process or processes it itself creates. .PP .C system() does not return until the child process has terminated. .SS Application Usage If the return value of .C system() is not \(mi1, its value can be decoded through the use of the macros described in .RC < sys/wait.h >. For convenience, these macros are also provided in .RC < stdlib.h >. .PP Note that, while .CR system() must ignore .C SIGINT and .C SIGQUIT and block .C SIGCHLD while waiting for the child to terminate, the handling of signals in the executed command is as specified by .IR fork (2) and .IR exec (2). For example, if .C SIGINT is being caught or is set to .C SIG_DFL when .CR system() is called, the child is started with .C SIGINT handling set to .CR SIG_DFL . .PP Ignoring .C SIGINT and .C SIGQUIT in the parent process prevents coordination problems (such as two processes reading from the same terminal) when the executed command ignores or catches one of the signals. .SH RETURN VALUE If .I command is null, .C system() returns non-zero. .PP If .I command is not null, .C system() returns the termination status of the command language interpreter in the format specified by .IR waitpid (2). The termination status of the command language interpreter is as specified for .IR sh-posix (1), except that if some error prevents the command language interpreter from executing after the child process is created, the return value from .CR system() is as if the command language interpreter had terminated using .CR _exit(127) . If a child process cannot be created, or if the termination status for the command language interpreter cannot be obtained, .CR system() returns \(mi1 and sets .C errno to indicate the error. .SH DIAGNOSTICS .C system() forks to create a child process which, in turn, .CR exec() s .C /usr/bin/sh in order to execute .IR string . If the fork fails, .C system() returns \(mi1 and sets .CR errno . If the exec fails, .C system() returns the status value returned by .C waitpid() (see .IR waitpid (2)) for a process that terminates with a call of .CR exit(127) . .SH ERRORS If errors are encountered, .CR system() sets .C errno values as described by .IR fork (2). .SH FILES .C /usr/bin/sh .SH SEE ALSO sh(1), fork(2), exec(2), waitpid(2). .SH STANDARDS CONFORMANCE .CR system() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2, ANSI C" .\" .\" index@\f4system()\fP \- issue a shell command@@@\f3system(3S)\f1 .\" index@issue a shell command@@@\f3system(3S)\f1 .\" index@shell command, issue a@@@\f3system(3S)\f1 .\" index@command, shell, issue a@@@\f3system(3S)\f1 .\" .\" toc@\f3system(3S)\f1:\0\0\f4system()\fP@@@issue a shell command .\" $Header: t_accept.3,v 72.3 94/11/15 13:02:56 ssa Exp $ .TA t .TH t_accept 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_accept() \- accept a connect request .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_accept (fd, resfd, call)" .CR "int fd;" .CR "int resfd;" .CR "struct t_call *call;" .fi .P .SH DESCRIPTION The .CR t_accept() function is issued by a transport user to accept a connect request. .IR fd identifies the local transport endpoint where the connect indication arrived. .IR resfd specifies the local transport endpoint where the connection is to be established. .IR call contains information required by the transport provider to complete the connection. The parameter .IR call points to a .CR t_call structure which contains the following members: .PP .nf .CR " struct netbuf addr; /* address */" .CR " struct netbuf opt; /* options */" .CR " struct netbuf udata; /* user data */" .CR " int sequence; /* sequence number */" .fi .PP The .CR netbuf structure is defined in the .CR or .CR header file. This structure, which is used to define buffer parameters, has the following members: .TP 30 .CR "unsigned int maxlen" maximum byte length of the data buffer .TP .CR "unsigned int len" actual byte length of data written to buffer .TP .CR "char *buf" points to buffer location .P In .IR call , the .IR addr , .IR opt , .IR udata , and .IR sequence parameters are explained here. .IR addr is the protocol address of the calling transport user. .IR opt indicates any options associated with the connection. For XTI over the OSI transport provider, this .CR netbuf should point to a struct of type .CR isoco_options . .IR udata points to any user data to be returned to the caller. .IR sequence is the value returned by .CR t_listen() that uniquely associates the response with a previously received connect indication. The address of the caller, .IR addr , may be null (length zero). When .IR addr is not null, then it may optionally be checked by XTI. .P A transport user may accept a connection on either the same, or on a different, local transport endpoint than the one on which the connect indication arrived. Before the connection can be accepted on the same endpoint (\c .IR resfd==fd ), the user must have responded to any previous connect indications received on that transport endpoint (via .CR t_accept() or .CR t_snddis() ). Otherwise, .CR t_accept() will fail and set .CR t_errno to [TINDOUT]. .P If a different transport endpoint is specified (\c .IR resfd!=fd ), then the user may or may not choose to bind the endpoint before .CR t_accept() is issued. If the endpoint is not bound prior to the .CR t_accept() , then the transport provider will automatically bind it to the same protocol address .IR fd is bound to. If the transport user chooses to bind the endpoint, it must be bound to a protocol address with a .IR qlen of zero and must be in the T_IDLE state before the .CR t_accept() is issued. .P The call to .CR t_accept() will fail with .CR t_errno set to [TLOOK] if there are indications (e.g., connect or disconnect) waiting to be received on the endpoint .IR fd . .P The .IR udata argument enables the called transport user to send user data to the caller. The amount of user data must not exceed the limits supported by the transport provider as returned in the .IR connect field of the .IR info argument of .CR t_open() or .CR t_getinfo() . If the .IR len field of .IR udata is zero, no data will be sent to the caller. All the .IR maxlen fields are meaningless. .P When the user does not indicate any option (\c .IR "call->opt.len " \c = 0), it is assumed that the connection is to be accepted unconditionally. The transport provider may choose options other than the defaults to ensure that the connection is accepted successfully. .PP .SS Valid States fd: .CR T_INCON .P resfd (fd != resfd): .CR T_IDLE .SS Caveats There may be transport provider-specific restrictions on address binding. .P Some transport providers do not differentiate between a connect indication and the connection itself. If the connection has already been established after a successful return of .CR t_listen() , .CR t_accept() will assign the existing connection to the transport endpoint specified by .IR resfd . .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned, and .CR t_errno is set to indicate the error. .SH ERRORS .PP On failure, .CR t_errno is set to one of the following: .TP 17 [TBADF] The file descriptor, .IR fd or .IR resfd , does not refer to a transport endpoint, or the user is illegally accepting a connection of the same transport endpoint on which the connect indication arrived. .TP .SM \%[TOUTSTATE] The function was issued in the wrong sequence on the transport endpoint referenced by .IR fd , or the transport endpoint referred to by .IR resfd is not in the appropriate state. .TP .SM \%[TACCES] The user does not have permission to accept a connection on the responding transport endpoint or use the specified options. .TP .SM \%[TBADOPT] The specified options were in an incorrect format or contained illegal information. .TP .SM \%[TBADDATA] The amount of user data specified was not within the bounds allowed by the transport provider. .TP .SM \%[TBADADDR] The specified protocol address was in an incorrect format or contained illegal information. .TP .SM \%[TBADSEQ] An invalid sequence number was specified. .TP .SM \%[TLOOK] An asynchronous event has occurred on the transport endpoint referenced by .IR fd and requires immediate attention. .TP .SM \%[TNOTSUPPORT] This function is not supported by the underlying transport provider. .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TINDOUT] The function was called with .IR fd==resfd but there are outstanding connection indications on the endpoint. Those other connection indications must be handled either by rejecting them via .CR t_snddis() or accepting them on a different endpoint via .CR t_accept() . .TP 20 .SM \%[TPROVMISTMATCH] (XTI only) The file descriptors .IR fd and .IR resfd do not refer to the same transport provider. .TP 17 .SM \%[TRESQLEN] The endpoint referenced by .IR resfd (where .IR "resfd != fd" ) was bound to a protocol address with a .IR qlen that is greater than zero. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no other suitable XTI (\c .CR t_errno ). .TP .SM \%[TRESADDR] This transport provider requires both .IR fd and .IR resfd to be bound to the same address. This error results if they are not. .SH FILES .TP 35 .CR /usr/include/xti.h XTI data structures .TP .CR /usr/include/xti_iso.h XTI data structures .TP .CR /usr/include/tiuser.h TLI data structures .SH SEE ALSO .PP t_connect(3), t_getstate(3), t_listen(3), t_open(3), t_rcvconnect(3). .\" .SH STANDARDS CONFORMANCE .CR t_accept() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_accept\f1 \- accept a connect request issued by a transport user (X/OPEN TLI-XTI)@@@\f3t_accept(3)\f1 .\" index@\f1connect request issued by a transport user (X/OPEN TLI-XTI)@@@\f3t_accept(3)\f1 .\" index@\f1transport user, accept connect request (X/OPEN TLI-XTI)@@@\f3t_accept(3)\f1 .\" index@\f1XTI function, accept a connect request issued by a transport user@@@\f3t_accept(3)\f1 .\" index@\f1TLI function, accept a connect request issued by a transport user@@@\f3t_accept(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, accept a connect request issued by a transport user@@@\f3t_accept(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, accept a connect request issued by a transport user@@@\f3t_accept(3)\f1 .\" .\" toc@\f3t_accept(3)\f1:\0\0\f4t_accept()\f1@@@X/OPEN TLI-XTI - accept a library structure .\" .\" fileset_database@t_accept.3 TLI-XTI-MAN .\" $Header: t_alloc.3,v 74.1 95/05/10 22:03:38 ssa Exp $ .TA t .TH t_alloc 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_alloc() \- allocate a library structure .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "char *t_alloc (fd, struct_type, fields)" .CR "int fd;" .CR "int struct_type;" .CR "int fields;" .fi .SH DESCRIPTION The .CR t_alloc() function dynamically allocates memory for the various transport function argument structures as specified below. This function will allocate memory for the specified structure and will also allocate memory for buffers referenced by the structure. .P The structure to allocate is specified by .IR struct_type and must be one of the following: .P .RS .TS lp-1 l l. T_BIND struct t_bind T_CALL struct t_call T_OPTMGMT struct t_optmgmt T_DIS struct t_discon T_UNITDATA struct t_unitdata T_UDERROR struct t_uderr T_INFO struct t_info .TE .RE .P where each of these structures may subsequently be used as an argument to one or more transport functions. .P Each of the above structures, except T_INFO, contains at least one field of type .CR "struct netbuf" . For each field of this type, the user may specify that the buffer for that field should be allocated as well. The length of the buffer allocated will be equal to or greater than the appropriate size returned in the .IR info argument of .CR t_open() or .CR t_getinfo(). The relevant fields of the .IR info argument are described in the following list. The .IR fields argument specifies which buffer to allocate, where the argument is the bitwise-OR of any of the following: .TP 17 .SM .CR T_ADDR The .IR addr field of the .CR t_bind , .CR t_call , .CR t_unitdata , or .CR t_uderr structures. .TP .SM .CR T_OPT The .IR opt field of the .CR t_optmgmt , .CR t_call , .CR t_unitdata , or .CR t_uderr structures. .TP .SM .CR T_UDATA The .IR udata field of the .CR t_call , .CR t_discon , or .CR t_unitdata structures. .TP .SM .CR T_ALL All relevant fields of the given structure. Fields which are not supported by e transport provider specified by .IR fd will not be allocated (\c .IR info values are <= 0). .PP For each field specified in .IR fields , .CR t_alloc() will allocate memory for the buffer associated with the field, and initialize the .IR len field to zero and the .IR buf pointer and .IR maxlen field accordingly. Since the length of the buffer allocated will be based on the same size information that is returned to the user on .CR t_open() or .CR t_getinfo() , .IR fd must refer to the transport endpoint through which the newly allocated structure will be passed. In this way the appropriate size information can be accessed. If the size value associated with any specified field is -1 or -2 ( see .IR t_open (3) or .IR t_getinfo (3)), .CR t_alloc() will be unable to determine the size of the buffer to allocate and will fail, setting .CR t_errno to [TSYSERR] and .CR errno to [EINVAL]. For any field not specified in .IR fields , .IR buf will be set to a null pointer and .IR maxlen will be set to zero. .PP Use of .CR t_alloc() to allocate structures will help ensure the compatibility of user programs with future releases of the transport interface functions. .SS Valid States All - apart from .CR T_UNINIT .SH RETURN VALUE Upon successful completion, .CR t_alloc() returns a pointer to the newly allocated structure. On failure, a null pointer is returned. .SH ERRORS .PP On failure, .CR t_errno is set to one of the following: .TP 20 .SM \%[TBADF] .I fd The specified endpoint identifier does not refer to a transport endpoint .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no suitable XTI (\c .CR t_errno ). .TP .SM \%[TNOSTRUCTYPE] Unsupported .IR struct_type requested. This can include a request for a structure type which is inconsistent with the transport provider type specified, i.e., connection-oriented or connectionless. .SH SEE ALSO .PP t_free(3), t_getinfo(3), t_open(3). .\" .SH STANDARDS CONFORMANCE .CR t_alloc() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_alloc\f1 \- allocate library structure for transport function argument structures (X/OPEN TLI-XTI)@@@\f3t_alloc(3)\f1 .\" index@\f1allocate library structure for transport function argument structures (X/OPEN TLI-XTI)@@@\f3t_alloc(3)\f1 .\" index@\f1library structure for transport function argument structures (X/OPEN TLI-XTI)@@@\f3t_alloc(3)\f1 .\" index@\f1transport function argument structures (X/OPEN TLI-XTI), allocate library structure@@@\f3t_alloc(3)\f1 .\" index@\f1XTI function, allocate a library structure@@@\f3t_alloc(3)\f1 .\" index@\f1TLI function, allocate a library structure@@@\f3t_alloc(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, allocate library structure@@@\f3t_alloc(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, allocate library structure@@@\f3t_alloc(3)\f1 .\" .\" toc@\f3t_alloc(3)\f1:\0\0\f4t_alloc()\f1@@@X/OPEN TLI-XTI - allocate library structure .\" .\" fileset_database@t_alloc.3 TLI-XTI-MAN .\" $Header: t_bind.3,v 72.3 94/11/15 13:03:00 ssa Exp $ .TA t .TH t_bind 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_bind() \- bind an address to a transport endpoint .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_bind (fd, req, ret)" .CR "int fd;" .CR "struct t_bind *req;" .CR "struct t_bind *ret;" .fi .SH DESCRIPTION The .CR t_bind() function associates a protocol address with the transport endpoint specified by .IR fd and activates that transport endpoint. In connection mode, the transport provider may begin enqueuing incoming connect indications or servicing a connection request on the transport endpoint. In connectionless mode, the transport user may send or receive data units through the transport endpoint. .P The .IR req and .IR ret arguments point to a .CR t_bind structure containing the following members: .P .nf .CR " struct netbuf addr;" .CR " unsigned qlen;" .fi .P The type .CR netbuf structure is defined in the .CR or .CR header file. This structure, which is used to define buffer parameters, has the following members: .TP 25 .SM .CR "unsigned int maxlen" maximum byte length of the data buffer .TP .SM .CR "unsigned int len" actual byte length of data written to buffer .TP .SM .CR "char *buf" points to buffer location .P The .IR addr field of the .CR t_bind structure specifies a protocol address. The .IR qlen field is used to indicate the maximum number of outstanding connect indications. .P The parameter .IR req is used to request that an address, represented by the .CR netbuf structure, be bound to the given transport endpoint. The parameter .IR len specifies the number of bytes in the address, and .IR buf points to the address buffer. The parameter .IR maxlen has no meaning for the .IR req argument. On return, .IR ret contains the address of that the transport provider actually bound to the transport endpoint. This is the same as the address specified in .IR req . In .IR ret , the user specifies .IR maxlen , which is the maximum size of the address buffer, and .IR buf which points to the buffer where the address is to be placed. On return, .IR len specifies the number of bytes in the bound address, and .IR buf points to the bound address. If .IR maxlen is not large enough to hold the returned address, an error will result. .P If the request address is not available, .CR t_bind() will return -1 with .CR t_errno set as appropriate. If no address is specified in .IR req (the .IR len field of .IR addr in .IR req is zero or .IR req is NULL), the transport provider will assign an appropriate address to be bound, and will return that address in the .IR addr field of .IR ret . If the transport provider could not allocate an address, .CR t_bind() will fail with .CR t_errno set to [TNOADDR]. HP OSI does not support the automatic generation of an address. .P The parameter .IR req may be a null pointer if the user does not wish to specify an address to be bound. Here, the value of .IR qlen is assumed to be zero, and the transport provider will assign an address to the transport endpoint. Similarly, .IR ret may be a null pointer if the user does not care what address was bound by the provider and is not interested in the negotiated value of .IR qlen . It is valid to set .IR req and .IR ret to the null pointer for the same call, in which case the provider chooses the address to bind to the transport endpoint and does not return that information to the user. .P The .IR qlen field has meaning only when initializing a connection-mode service. It specifies the number of outstanding connect indications that the transport provider should support for the given transport endpoint. An outstanding connect indication is one that has been passed to the transport user by the transport provider but which has not been accepted or rejected. A value of .IR qlen greater than zero is only meaningful when issued by a passive transport user that expects others to call it. The value of .IR qlen will be negotiated by the transport provider and may be changed if the transport provider cannot support the specified number of outstanding connect indications. However, this value of .IR qlen will never be negotiated from a requested value greater than zero to zero. This is a requirement on transport providers; see .BR Caveats below. On return, the .IR qlen field in .IR ret will contain the negotiated value. .P If .IR fd refers to a connection-mode service, this function allows more than one transport endpoint to be bound to the same protocol address (however, the transport provider must also support this capability), but it is not possible to bind more than one protocol address to the same transport endpoint. If a user binds more than one transport endpoint to the same protocol address, only one endpoint can be used to listen for the connect indications associated with that protocol address. In other words, only one .CR t_bind() for a given protocol address may specify a value of .IR qlen greater than zero. In this way, the transport provider can identify which transport endpoint should be notified of an incoming connect indication. If a user attempts to bind a protocol address to a second transport endpoint with a value of .IR qlen greater than zero, .CR t_bind() will return -1 and set .CR t_errno to [TADDRBUSY] (XTI) or [TBADADDR] (TLI). When a user accepts a connection on the transport endpoint that is being used as the listening endpoint, the bound protocol address will be found to be busy for the duration of the connection, until a .CR t_unbind() or .CR t_close() call has been issued. No other transport endpoints may be bound for listening on the same protocol address while that initial listening endpoint is active (in the data transfer phase or in the T_IDLE state). This will prevent more than one transport endpoint bound to the same protocol address from accepting connect indications. .P If .IR fd refers to a connectionless-mode service, only one endpoint may be associated with a protocol address. If a user attempts to bind a second transport endpoint to an already bound address, .CR t_bind() will return -1 and set .CR t_errno to [TADDRBUSY]. .SS Valid States T_UNBND .SS Note HP XTI does not support automatic generation of addresses. Therefore a valid local transport address must be specified in .IR req . .SS Caveats The requirement that the value of .IR qlen never be negotiated from a requested value greater than zero to zero implies that transport providers, rather than the XTI implementation itself, accept this restriction. .P A transport provider may not allow an explicit binding of more than one transport endpoint to the same protocol address although it allows more than one connection to be accepted for the same protocol address. To ensure portability, it is, therefore, recommended not to bind transport endpoints that are used as responding endpoints (\c .IR resfd ) in a call to .CR t_accept() if the responding address is to be the same as the called address. .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and .CR t_errno is set to indicate the error. .SH ERRORS .PP On failure, .CR t_errno is set to one of the following: .TP 17 .SM \%[TBADF] The specified file descriptor does not refer to a transport endpoint. .TP .SM \%[TOUTSTATE] The function was issued in the wrong sequence. .TP .SM \%[TBADADDR] The specified protocol address was in an incorrect format or contained illegal information. .TP .SM \%[TNOADDR] The transport provider could not allocate an address. .TP .SM \%[TACCES] The user does not have permission to use the specified address. .TP .SM \%[TBUFOVFLW] The number of bytes allowed for an incoming argument is not sufficient to store the value of that argument. The provider's state will change to T_IDLE and the information to be returned in .I ret will be discarded. .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TADDRBUSY] The address requested is in use and the transport provider could not allocate a new address. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no suitable XTI (\c .CR t_errno ). .SH FILES .TP 35 .CR "/usr/include/xti.h" XTI data structures .TP 35 .CR /usr/include/xti_iso.h XTI data structures .TP 35 .CR /usr/include/tiuser.h TLI data structures .SH SEE ALSO .PP t_alloc(3), t_close(3), t_open(3), t_unbind(3). .\" .SH STANDARDS CONFORMANCE .CR t_bind() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_bind\f1 \- bind address to transport endpoint (X/OPEN TLI-XTI)@@@\f3t_bind(3)\f1 .\" index@\f1bind address to transport endpoint (X/OPEN TLI-XTI)@@@\f3t_bind(3)\f1 .\" index@\f1XTI function, bind address to transport endpoint @@@\f3t_bind(3)\f1 .\" index@\f1TLI function, bind address to transport endpoint @@@\f3t_bind(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, bind address to transport endpoint@@@\f3t_bind(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, bind address to transport endpoint@@@\f3t_bind(3)\f1 .\" .\" toc@\f3t_bind(3)\f1:\0\0\f4t_bind()\f1@@@X/OPEN TLI-XTI - bind address to transport endpoint .\" .\" fileset_database@t_bind.3 TLI-XTI-MAN .\" $Header: t_close.3,v 72.3 94/11/15 13:03:02 ssa Exp $ .TA t .TH t_close 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_close() \- close a transport endpoint .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_close (fd)" .CR "int fd;" .fi .SH DESCRIPTION .PP The .CR t_close() function informs the transport provider that the user is finished with the transport endpoint specified by .IR fd , and frees any local library resources associated with the endpoint. .CR t_close() also closes the file descriptor associated with the transport endpoint. .PP .CR t_close() should be called from the T_UNBND state (see .IR t_getstate (3)). However, this function does not check state information, so it may be called from any state to close a transport endpoint. If this occurs, the local library resources associated with the endpoint will be freed automatically. .CR close() will also be issued for that file descriptor. The close will be abortive if no other process has that file open and will break any transport connection that may be associated with that endpoint. .SS Valid States All - apart from T_UNINIT .SH "RETURN VALUE" Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and .CR t_errno is set to indicate the error. .SH ERRORS .TP 20 .SM \%[TBADF] The specified file descriptor does not refer to a transport endpoint. .TP 20 .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no suitable XTI (\c .CR t_errno ). .SH SEE ALSO .PP t_getstate(3), t_open(3), t_unbind(3). .\" .SH STANDARDS CONFORMANCE .CR t_close() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_close\f1 \- close transport endpoint (X/OPEN TLI-XTI)@@@\f3t_close(3)\f1 .\" index@\f1close transport endpoint (X/OPEN TLI-XTI)@@@\f3t_close(3)\f1 .\" index@\f1XTI function, close transport endpoint@@@\f3t_close(3)\f1 .\" index@\f1TLI function, close transport endpoint@@@\f3t_close(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, close transport endpoint@@@\f3t_close(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, close transport endpoint@@@\f3t_close(3)\f1 .\" .\" toc@\f3t_close(3)\f1:\0\0\f4t_close()\f1@@@X/OPEN TLI-XTI - close transport endpoint .\" .\" fileset_database@t_close.3 TLI-XTI-MAN .\" $Header: t_connect.3,v 72.3 94/11/15 13:03:03 ssa Exp $ .TA t .TH t_connect 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_connect() \- establish a connection with another transport user .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_connect (fd, sndcall, rcvcall)" .CR "int fd;" .CR "struct t_call *sndcall;" .CR "struct t_call *rcvcall;" .fi .P .SH DESCRIPTION .PP This function enables a transport user to request a connection to the specified destination transport user. This function can only be issued in the T_IDLE state. .IR fd identifies the local transport endpoint where communication will be established. .IR sndcall and .IR rcvcall point to a .CR t_call structure which contains the following members: .P .nf .CR " struct netbuf addr;" .CR " struct netbuf opt;" .CR " struct netbuf udata;" .CR " int sequence;" .fi .P The type .CR netbuf structure is defined in the .CR or .CR header file. This structure, which is used to define buffer parameters, has the following members: .TP 25 .SM .CR "unsigned int maxlen" maximum byte length of the data buffer .TP .SM .CR "unsigned int len" actual byte length of data written to buffer .TP .SM .CR "char *buf" points to buffer location .P .IR sndcall specifies information needed by the transport provider to establish a connection. .IR rcvcall specifies information that is associated with the newly established connection. .P In .IR sndcall , .IR addr specifies the protocol address of the destination transport user. .IR opt presents any protocol-specific information that might be needed by the transport provider. .IR udata points to optional user data that may be passed to the destination transport user during connection establishment. .IR sequence has no meaning for this function. .P On return in .IR rcvcall , .IR addr returns the protocol address associated with the responding transport endpoint. .IR opt presents any protocol-specific information associated with the connection. .IR udata points to optional user data that may be returned by the destination transport user during connection establishment. .IR sequence has no meaning for this function. .P The .IR opt argument permits users to define the options that may be passed to the transport provider. These options are specific to the underlying protocols of the transport provider and are described for ISO and TCP protocols in Appendix A, "ISO Transport Protocol Information," Appendix B, "Internet Protocol-specific Information," and Appendix F, "Headers and Definitions" of the .IR "CAE Specification X/Open Transport Interface (XTI)" manual. The user may choose not to negotiate protocol options by setting the .IR len field of .IR opt to zero. In this case, the provider may use default options. .P If the .IR opt argument is used, the .IR sndcall->opt.buf structure must point to the corresponding options structures. For XTI over the OSI transport provider, the options buffer should be a struct of type .CR isoco_options or .CR tcp_options . For TLI, see the documentation for the transport provider being used. The .IR maxlen and .IR buf fields of the .CR netbuf structure pointed by .IR rcvcall->addr and .IR rcvcall->opt must be set before the call. .P The .IR udata argument enables the caller to pass user data to the destination transport user and receive user data from the destination user during connection establishment. However, the amount of user data must not exceed the limits supported by the transport provider as returned in the .IR connect field of the .IR info argument of .CR t_open() or .CR t_getinfo() . If the .IR len of .IR udata is zero in .IR sndcall , no data will be sent to the destination transport user. .P On return, the .IR addr , .IR opt , and .IR udata fields of .IR rcvcall will be updated to reflect values associated with the connection. Thus, the .IR maxlen field of each argument must be set before issuing this function to indicate the maximum size of the buffer for each. However, .IR rcvcall may be a null pointer, in which case no information is given to the user on return from .CR t_connect() . .P By default, .CR t_connect() executes in synchronous mode and will wait for the destination user's response before returning control to the local user. A successful return (i.e., return value of zero) indicates that the requested connection has been established. However, if .CR O_NONBLOCK is set (via .CR t_open() or .CR fcntl() ), .CR t_connect() executes in asynchronous mode. In this case, the call will not wait for the remote user's response, but will return control immediately to the local user and return \-1 with .CR t_errno set to [TNODATA] to indicate that the connection has not yet been established. In this way, the function simply initiates the connection establishment procedure by sending a connect request to the destination transport user. The .CR t_rcvconnect() function is used in conjunction with .CR t_connect() to determine the status of the requested connection. .P When a synchronous .CR t_connect() call is interrupted by the arrival of a signal, the state of the corresponding transport endpoint is T_OUTCON, allowing a further call to either .CR t_rcvconnect() , .CR t_rcvdis() , or .CR t_snddis() . .SS Valid States T_IDLE .SH "RETURN VALUE" Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and .CR t_errno is set to indicate the error. .SH ERRORS .TP 17 .SM \%[TBADF] The specified file descriptor does not refer to a transport endpoint. .TP .SM \%[TOUTSTATE] The function was issued in the wrong sequence. .TP .SM \%[TNODATA] .CR O_NONBLOCK was set, so the function successfully initiated the connection establishment procedure, but did not wait for a response from the remote user. .TP .SM \%[TBADADDR] The specified protocol address was in an incorrect format or contained illegal information. .TP .SM \%[TBADOPT] The specified protocol options were in incorrect format or contained illegal information. .TP .SM \%[TBADDATA] The amount of user data specified was not within the bounds allowed by the transport provider. .TP .SM \%[TACCES] The user does not have permission to use the specified address or options. .TP .SM \%[TBUFOVFLW] The number of bytes allocated for an incoming argument (\c .IR maxlen ) is greater than zero but not sufficient to store the value of that argument. If executed in synchronous mode, the provider's state, as seen by the user, changes to T_DATAXFER, and the connect indication information to be returned in .IR rcvcall is discarded. .TP .SM \%[TLOOK] An asynchronous event has occurred on this transport endpoint and requires immediate attention. .TP .SM \%[TNOTSUPPORT] This function is not supported by the underlying transport provider. .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TADDRBUSY] This transport provider does not support multiple connections with the same local and remote addresses. This error indicates that a connection already exists. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no suitable XTI (\c .CR t_errno ). .SH FILES .TP 35 .CR /usr/include/xti.h XTI data structures .TP .CR /usr/include/tiuser.h TLI data structures .SH SEE ALSO .PP fcntl(2), t_accept(3), t_alloc(3), t_getinfo(3), t_listen(3), t_open(3), t_rcvconnect(3). .\" .SH STANDARDS CONFORMANCE .CR t_connect() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_connect\f1 \- establish connection with another transport user (X/OPEN TLI-XTI)@@@\f3t_connect(3)\f1 .\" index@\f1establish connection with another transport user (X/OPEN TLI-XTI)@@@\f3t_connect(3)\f1 .\" index@\f1connection with another transport user (X/OPEN TLI-XTI)@@@\f3t_connect(3)\f1 .\" index@\f1transport user, establish connection (X/OPEN TLI-XTI)@@@\f3t_connect(3)\f1 .\" index@\f1XTI function, establish connection with another transport user@@@\f3t_connect(3)\f1 .\" index@\f1TLI function, establish connection with another transport user@@@\f3t_connect(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, establish connection with another transport user@@@\f3t_connect(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, establish connection with another transport user@@@\f3t_connect(3)\f1 .\" .\" toc@\f3t_connect(3)\f1:\0\0\f4t_connect()\f1@@@X/OPEN TLI-XTI - establish connection with another transport user .\" .\" fileset_database@t_connect.3 TLI-XTI-MAN .\" $Header: t_error.3,v 72.3 94/11/15 13:03:05 ssa Exp $ .TA t .TH t_error 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_error() \- produce error message .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "void t_error (errmsg)" .CR "char *errmsg;" .CR "extern int t_errno" .CR "extern char *t_errlist[]" .CR "extern int t_nerr;" .fi .SH DESCRIPTION The .CR t_error() function produces a language-dependent message on the standard error output which describes the last error encountered during a call to a transport function. The argument string .IR errmsg is a user-supplied error message that gives context to the error. .P The error message is written as follows: .P .RS 5 First if .IR errmsg is not a null pointer and the character pointed to be .IR errmsg is not the null character, the string pointed to by .IR errmsg is written followed by a colon and a space. .P Then a standard error message string for the current error defined in .CR t_errno is written. If .CR t_errno has a value different from [TSYSERR], the standard error message string is followed by a newline character. If, however, .CR t_errno is equal to [TSYSERR], the .CR t_errno string is followed by the standard error message string for the current error defined in .CR errno followed by a newline. .RE .P The language for error message strings written by .CR t_error() is implementation-defined. If it is in English, the error message string describing the value in .CR t_errno is identical to the comments following the .CR t_errno codes defined in .CR . The contents of the error message strings describing the value in .CR errno are the same as those returned by the .CR strerror() function with an argument of .CR errno . .P To simplify variant formatting of messages, the array of message strings .CR t_errlist is provided; .CR t_errno can be used as an index in this table to get the message string without the newline. The variable .CR t_nerr is the largest message number provided for in the .CR t_errlist table. .P The error number, .CR t_errno , is only set when an error occurs and it is not cleared on successful calls. .SS Valid States All - apart from T_UNINIT .SH RETURN VALUE For XTI, upon completion, a value of 0 is returned. TLI does not return a value. .SH ERRORS No errors are defined for the .CR t_error() function. .SH EXAMPLE If a .CR t_connect() function fails on transport endpoint .IR fd2 because a bad address was given, the following call might follow the failure: .P .nf .C "t_error(""t_connect failed on fd2"");" .fi .P The diagnostic message to be printer would look like: .P .nf .CR "t_connect failed on fd2: Incorrect address format" .fi .P where .CR "Incorrect address format" identifies the specific error that occurred, and .CR "t_connect failed on fd2" tells the user which function failed on which transport endpoint. .SH FILES .TP 50 .CR /usr/lib/nls/msg/C/libnsl_s.cat NLS message catalog for TLI .\" .SH STANDARDS CONFORMANCE .CR t_error() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_error\f1 \- error message function (X/OPEN TLI-XTI)@@@\f3t_error(3)\f1 .\" index@\f1error message function (X/OPEN TLI-XTI)@@@\f3t_error(3)\f1 .\" index@\f1XTI function, error message function@@@\f3t_error(3)\f1 .\" index@\f1TLI function, error message function@@@\f3t_error(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, error message function@@@\f3t_error(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, error message function@@@\f3t_error(3)\f1 .\" .\" toc@\f3t_error(3)\f1:\0\0\f4t_error()\f1@@@X/OPEN TLI-XTI - error message function .\" .\" fileset_database@t_error.3 TLI-XTI-MAN .\" $Header: t_free.3,v 74.1 95/05/10 22:03:54 ssa Exp $ .TA t .TH t_free 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_free() \- free a library structure .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_free (ptr, struct_type)" .CR "char *ptr;" .CR "int struct_type;" .fi .SH DESCRIPTION The .CR t_free() function frees memory previously allocated by .CR t_alloc() . This function will free memory for the specified structure and will also free memory for buffers referenced by the structure. .P The argument .IR ptr points to one of the seven structure types described for .CR t_alloc() . .IR struct_type identifies the type of that structure which must be one of the following: .P .RS .TS lp-1 l l. T_BIND struct t_bind T_CALL struct t_call T_OPTMGMT struct t_optmgmt T_DIS struct t_discon T_UNITDATA struct t_unitdata T_UDERROR struct t_uderr T_INFO struct t_info .TE .RE .P where each of these structures is used as an argument to one or more transport functions. .P .CR t_free() will check the .IR addr , .IR opt , and .IR udata fields of the given structure (as appropriate) and free the buffers pointed to by the .IR buf field of the .CR netbuf structure. If .IR buf is a null pointer, .CR t_free() will not attempt to free memory. After all buffers are freed, .CR t_free() will free the memory associated with the structure pointed to by .IR ptr . .PP Undefined results will occur if .IR ptr or any of the .IR buf pointers points to a block of memory that was not previously allocated by .CR t_alloc() . .SS Valid States All - apart from T_UNINIT .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned, and .CR t_errno is set to indicate the error. .SH ERRORS On failure, .CR t_errno is set to the following: .TP 20 .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TNOSTRUCTYPE] Unsupported .IR struct_type requested. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no suitable XTI (\c .CR t_errno ). .SH SEE ALSO t_alloc(3). .\" .SH STANDARDS CONFORMANCE .CR t_free() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_free\f1 \- free memory for library structure (X/OPEN TLI-XTI)@@@\f3t_free(3)\f1 .\" index@\f1free memory for library structure (X/OPEN TLI-XTI)@@@\f3t_free(3)\f1 .\" index@\f1memory for library structure (X/OPEN TLI-XTI)@@@\f3t_free(3)\f1 .\" index@\f1XTI function, free library structure@@@\f3t_free(3)\f1 .\" index@\f1TLI function, free library structure@@@\f3t_free(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, free library structure@@@\f3t_free(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, free library structure@@@\f3t_free(3)\f1 .\" .\" toc@\f3t_free(3)\f1:\0\0\f4t_free()\f1@@@X/OPEN TLI-XTI - free library structure .\" .\" fileset_database@t_free.3 TLI-XTI-MAN .\" $Header: t_getinfo.3,v 72.3 94/11/15 13:03:11 ssa Exp $ .TA t .TH t_getinfo 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_getinfo() \- get protocol-specific service information .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_getinfo (fd, info)" .CR "int fd;" .CR "struct info *info;" .fi .SH DESCRIPTION The .CR t_getinfo() function returns the current characteristics of the underlying transport protocol associated with file descriptor .IR fd . The .IR info structure is used to return the same information returned by .CR t_open() . This function enables a transport user to access this information during any phase of communication. .PP This argument points to a .CR t_info structure which contains the following members: .P .nf long addr; /* max size of the transport protocol address */ long options; /* max number of bytes of protocol-specific options */ long tsdu; /* max size of a transport service data unit (TSDU) */ long etsdu; /* max size of an expedited transport service data unit (ETSDU) */ long connect; /* max amount of data allowed on connection establishment functions */ long discon; /* max amount of data allowed on t_snddis and t_rcvdis functions */ long servtype; /* service type supported by the transport provider */ long flags; /* other info about the transport provider */ .fi .PP The values of the fields have the following meanings: .TP 17 .SM .IR addr A value greater than or equal to zero indicates the maximum size of a transport protocol address. .RS 17 .P A value of -1 specifies that there is no limit on the address size. .P A value of -2 specifies that the transport provider does not provide user access to transport protocol addresses. .RE .TP .SM .IR options A value greater than or equal to zero indicates the maximum number of bytes of protocol-specific options supported by the provider. .RS 17 .P A value of -1 specifies that there is no limit on the option size. .P A value of -2 specifies that the transport provider does not support user-settable options. .RE .TP .SM .IR tsdu A value greater than zero specifies the maximum size of a transport service data unit (TSDU) .RS 17 .P A value of zero specifies that the transport provider does not support the concept of TSDU although it does support the sending of a data stream with no logical boundaries preserved across a connection. .P A value of -1 specifies that there is no limit on the size of a TSDU. .P A value of -2 specifies that the transfer of normal data is not supported by the transport provider. .RE .TP .SM .IR etsdu A value greater than zero specifies the maximum size of an expedited transport service data unit (ETSDU). .RS 17 .P A value of zero specifies that the transport provider does not support the concept of ETSDU although it does support the sending of an expedited data stream with no logical boundaries preserved across a connection. .P A value of -1 specifies that there is no limit on the size of an ETSDU. .P A value of -2 specifies that the transfer of expedited data is not supported by the transport provider. .RE .TP .SM .IR connect A value greater than or equal to zero specifies the maximum amount of data that may be associated with the connection establishment functions .CR t_connect() and .CR t_rcvconnect() . .RS 17 .P A value of -1 specifies that there is no limit on the amount of data sent during connection establishment. .P A value of -2 specifies that the transport provider does not allow data to be sent with connection establishment functions. .RE .TP .SM .IR discon A value greater than or equal to zero specifies the maximum amount of data that may be associated with the .CR t_snddis() and .CR t_rcvdis() functions. .RS 17 .P A value of -1 specifies that there is no limit on the amount of data sent with these abortive release functions. .P A value of -2 specifies that the transport provider does not allow data to be sent with the abortive release functions. .RE .TP .SM .IR servtype This field specifies the service type supported by the transport provider, as described below. .TP .SM .IR flags This is a bit field used to specify other information about the transport provider. If the T_SENDZERO bit is set in flags, this indicates that the underlying transport provider supports the sending of zero-length TSDUs. See Appendix A, "ISO Transport Protocol Information" of the .IR "CAE Specification X/Open Transport Interface (XTI)" manual for a discussion of the separate issue of zero-length fragments within a TSDU. Note: HP currently does not support T_SENDZERO flag within the .CR timod module. .PP If a transport user is concerned with protocol independence, the above sizes may be accessed to determine how large the buffers must be to hold each piece of information. Alternatively, the .CR t_alloc() function may be used to allocate these buffers. An error will result if a transport user exceeds the allowed data size on any function. The value of each field may change as a result of option negotiation, and .CR t_getinfo() enables a user to retrieve the current characteristics of the underlying transport protocol. .PP The .IR servtype field of .IR info specifies one of the following values on return: .TP 17 .SM .CR T_COTS The transport provider supports a connection-mode service but does not support the optional orderly release facility. .TP .SM .CR T_COTS_ORD The transport provider supports a connection-mode service with the optional orderly release facility. .TP .SM .CR T_CLTS The transport provider supports a connectionless-mode service. For this service type, .CR t_open() will return -2 for .IR etsdu , .IR connect , and .IR discon . .SS Valid States All - apart from T_UNINIT .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned, and .CR t_errno is set to indicate the error. .SH ERRORS On failure, .CR t_errno is set to the following .TP 17 .SM \%[TBADF] The specified identifier does not refer to a transport endpoint. .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no suitable XTI (\c .CR t_errno ). .SH SEE ALSO t_alloc(3), t_open(3). .\" .SH STANDARDS CONFORMANCE .CR t_getinfo() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_getinfo\f1 \- get protocol-specific service information (X/OPEN TLI-XTI)@@@\f3t_getinfo(3)\f1 .\" index@\f1protocol-specific service information (X/OPEN TLI-XTI)@@@\f3t_getinfo(3)\f1 .\" index@\f1XTI function, get protocol-specific service information@@@\f3t_getinfo(3)\f1 .\" index@\f1TLI function, get protocol-specific service information@@@\f3t_getinfo(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, get protocol-specific service information@@@\f3t_getinfo(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, get protocol-specific service information@@@\f3t_getinfo(3)\f1 .\" .\" toc@\f3t_getinfo(3)\f1:\0\0\f4t_getinfo()\f1@@@X/OPEN TLI-XTI - get protocol-specific service information .\" .\" fileset_database@t_getinfo.3 TLI-XTI-MAN .\" $Header: t_getprotaddr.3,v 72.2 94/09/18 16:13:12 ssa Exp $ .TA t .TH t_getprotaddr 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_getprotaddr() \- get the protocol address .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .PP .nf .CR "int t_getprotaddr (fd, boundaddr, perraddr)" .CR "int fd;" .CR "struct t_bind *boundaddr;" .CR "struct t_bind *peeraddr;" .fi .SH DESCRIPTION The .CR t_getprotaddr() function returns local and remote protocol addresses currently associated with the transport endpoint specified by .IR fd . In .IR boundaddr and .IR peeraddr the user specifies .IR maxlen , which is the maximum size of the address buffer, and .IR buf which points to the buffer where the address is to be placed. On return, the .IR buf field of .IR boundaddr points to the address, if any, currently bound to .IR fd , and the .IR len field specifies the length of the address. If the transport endpoint is in the T_UNBND state, zero is returned in the .IR len field of .IR boundaddr . The .IR buf field of .IR peeraddr points to the address, if any, currently connected to .IR fd , and the .IR len field specifies the length of the address. If the transport endpoint is not in the T_DATAXFER state, zero is returned in the .IR len field of .IR peeraddr . .SS Valid States All - apart from T_UNINIT .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned, and .CR t_errno is set to indicate the error. .SH ERRORS On failure, .CR t_errno is set to the following .TP 17 .SM \%[TBADF] The specified identifier does not refer to a transport endpoint. .TP 17 .SM \%[TBUFOVFLW] The number of bytes allocated for an incoming argument (\c .IR maxlen ) is greater than 0 but not sufficient to store the value of that argument. .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no other suitable XTI (\c .CR t_errno ). .SH SEE ALSO t_bind(3). .\" .\" index@\f4t_getprotaddr\f1 \- get protocol address (X/OPEN XTI)@@@\f3t_getprotaddr(3)\f1 .\" index@\f1protocol address (X/OPEN XTI)@@@\f3t_getprotaddr(3)\f1 .\" index@\f1XTI function, get protocol address@@@\f3t_getprotaddr(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, get protocol address@@@\f3t_getprotaddr(3)\f1 .\" .\" toc@\f3t_getprotaddr(3)\f1:\0\0\f4t_getprotaddr()\f1@@@X/OPEN XTI - get protocol address .\" .\" fileset_database@t_getprotaddr.3 TLI-XTI-MAN .\" $Header: t_getstate.3,v 72.3 94/11/15 13:03:17 ssa Exp $ .TA t .TH t_getstate 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_getstate() \- get the current state .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_getstate (fd)" .CR "int fd;" .fi .SH DESCRIPTION The .CR t_getstate() function returns the current state of the provider as seen by the application associated with the transport endpoint specified by .IR fd . .SH RETURN VALUE State is returned upon successful completion. Otherwise, a value of -1 it returned and .CR t_errno is set to indicate the error. The current state is one of the following: .TP 17 .SM \%T_UNBND unbound .TP .SM \%T_IDLE idle .TP .SM \%T_OUTCON outgoing connection pending .TP .SM \%T_INCON incoming connection pending .TP .SM \%T_DATAXFER data transfer .TP .SM \%T_OUTREL outgoing orderly release (waiting for an orderly release indication). .TP .SM \%T_INREL incoming orderly release (waiting for an orderly release request). .P If the provider is undergoing a state transition when .CR t_getstate() is called, the function will fail. .SH ERRORS On failure, .CR t_errno is set to the following: .TP 17 .SM \%[TBADF] The specified identifier does not refer to a transport endpoint. .TP .SM \%[TSTATECHNG] The transport provider is undergoing a transient state change. .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no suitable XTI (\c .CR t_errno ). .SH SEE ALSO t_open(3). .\" .SH STANDARDS CONFORMANCE .CR t_getstate() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_getstate\f1 \- get current state (X/OPEN TLI-XTI)@@@\f3t_getstate(3)\f1 .\" index@\f1current state (X/OPEN TLI-XTI)@@@\f3t_getstate(3)\f1 .\" index@\f1XTI function, get current state@@@\f3t_getstate(3)\f1 .\" index@\f1TLI function, get current state@@@\f3t_getstate(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, get current state@@@\f3t_getstate(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, get current state@@@\f3t_getstate(3)\f1 .\" .\" toc@\f3t_getstate(3)\f1:\0\0\f4t_getstate()\f1@@@X/OPEN TLI-XTI - get current state .\" .\" fileset_database@t_getstate.3 TLI-XTI-MAN .\" $Header: t_listen.3,v 72.3 94/11/15 13:03:19 ssa Exp $ .TA t .TH t_listen 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_listen() \- listen for a connect request .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_listen (fd, call)" .CR "int fd;" .CR "struct t_call *call;" .fi .SH DESCRIPTION The .CR t_listen() function listens for a connect request from a calling transport user. .IR fd identifies the local transport endpoint where connect indications arrive. On return, .IR call contains information describing the connect indication. The parameter .IR call points to a .CR t_call structure which contains the following members: .P .nf struct netbuf addr; struct netbuf opt; struct netbuf udata; int sequence; .fi .P The type .CR netbuf structure is defined in the .CR or .CR header file. This structure, which is used to define buffer parameters, has the following members: .TP 25 .SM .CR "unsigned int maxlen" maximum byte length of the data buffer .TP .SM .CR "unsigned int len" actual byte length of data written to buffer .TP .SM .CR "char *buf" points to buffer location .PP In .IR call , .IR addr returns the protocol address of the calling transport user. This address is in a format usable in future calls to .CR t_connect() . Note, however that .CR t_connect() may fail for other reasons, for example [TADDRBUSY]. .P .IR opt returns protocol-specific parameters associated with the connect request. For XTI over the OSI transport provider, struct .CR isoco_options should be used. For TLI, see the documentation for the transport provider being used. .P .IR udata returns any user data sent by the caller on the connect request. .P .IR sequence is a number that uniquely identifies the returned connect indication. The value of .IR sequence enables the user to listen for multiple connect indications before responding to any of them. .PP Since this function returns values for the .IR addr , .IR opt , and .IR udata fields of .IR call , the .IR maxlen field of each must be set before issuing the .CR t_listen to indicate the maximum size of the buffer for each. .PP By default, .CR t_listen executes in synchronous mode and waits for a connect indication to arrive before returning to the user. However, if .CR O_NONBLOCK is set (via .CR t_open() or .CR fcntl() ), .CR t_listen() executes asynchronously, reducing to a poll for existing connect indications. If none are available, it returns -1 and sets .CR t_errno to [TNODATA]. .SS Valid States T_IDLE, T_INCON .SS Caveats Some transport providers do not differentiate between a connect indication and the connection itself. If this is the case, a successful return of .CR t_listen() indicates an existing connection (see Appendix B, "Internet Protocol-specific Information," of the .IR "CAE Specification X/Open Transport Interface (XTI)" manual). .SH RETURN VALUE Upon successful completion, a value of 0 is returned Otherwise, a value of -1 it returned and .CR t_errno is set to indicate the error. .SH ERRORS On failure, .CR t_errno is set to the following: .TP 17 .SM \%[TBADF] The specified identifier does not refer to a transport endpoint. .TP .SM \%[TBADQLEN] The argument .IR qlen of the endpoint referenced by .IR fd is zero. .TP .SM \%[TBUFOVFLW] The number of bytes allocated for an incoming argument (\c .IR maxlen ) is not sufficient to store the value of that argument. The provider's state, as seen by the user, changes to T_INCON, and the connect indication information to be returned in .IR call is discarded. For XTI only, the value of .IR sequence returned can be used to do a .CR t_snddis() . .TP .SM \%[TNODATA] .CR O_NONBLOCK was set, but no connect indication has been queued. .TP .SM \%[TLOOK] An asynchronous event has occurred on this transport endpoint and requires immediate attention. .TP .SM \%[TOUTSTATE] This function was issued in the wrong sequence on the transport endpoint referenced by .IR fd . .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TQFULL] The maximum number of outstanding indications has been reached for the endpoint referenced by .IR fd . .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no suitable XTI (\c .CR t_errno ). .SH FILES .TP 35 .CR /usr/include/xti.h XTI data structures .TP .CR /usr/include/tiuser.h TLI data structures .SH SEE ALSO fcntl(2), t_accept(3), t_alloc(3), t_bind(3), t_connect(3), t_open(3), t_snddis(3), t_rcvconnect(3). .\" .SH STANDARDS CONFORMANCE .CR t_listen() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_listen\f1 \- listen for connect request (X/OPEN TLI-XTI)@@@\f3t_listen(3)\f1 .\" index@\f1connect request (X/OPEN TLI-XTI)@@@\f3t_listen(3)\f1 .\" index@\f1XTI function, listen for connect request@@@\f3t_listen(3)\f1 .\" index@\f1TLI function, listen for connect request@@@\f3t_listen(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, listen for connect request@@@\f3t_listen(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, listen for connect request@@@\f3t_listen(3)\f1 .\" .\" toc@\f3t_listen(3)\f1:\0\0\f4t_listen()\f1@@@X/OPEN TLI-XTI - listen for connect request .\" .\" fileset_database@t_listen.3 TLI-XTI-MAN .\" $Header: t_look.3,v 76.1 95/06/12 15:53:25 ssa Exp $ .TA t .TH t_look 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_look() \- look at the current event on a transport endpoint .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_look (fd)" .CR "int fd;" .fi .SH DESCRIPTION The .CR t_look() function returns the current event on the transport endpoint specified by .IR fd . This function enables a transport provider to notify a transport user of an asynchronous event when the user is calling functions in synchronous mode. Certain events require immediate notification of the user and are indicated by a specific error, [TLOOK], on the current or next function to be executed. .P This function also enables a transport user to poll a transport endpoint periodically for asynchronous events. .SS Valid States All - apart from T_UNINIT .SH XTI Internet Protocol-specific Information As soon as a segment with the TCP urgent pointer set enters the TCP receive buffer, the event T_EXDATA is indicated. T_EXDATA remains set until all data up to the byte pointed to by the TCP urgent pointer has been received. If the urgent pointer is updated, and the user has not yet received the byte previously pointed to by the urgent pointer, the update is transparent to the user. .SH RETURN VALUE Upon success, .CR t_look() returns a value that indicates which of the following allowable events has occurred, or returns zero if no event exists. One of the following events is returned: .TP 17 .SM \%T_LISTEN connection indication received. .TP .SM \%T_CONNECT connect confirmation received. .TP .SM \%T_DATA normal data received. .TP .SM \%T_ERROR (TLI ONLY) fatal error occurred. .TP .SM \%T_EXDATA expedited data received. .TP .SM \%T_DISCONNECT disconnect received. .TP .SM \%T_UDERR datagram error indication. .TP .SM \%T_ORDREL orderly release indication. .TP .SM \%T_GODATA (XTI only) flow control restrictions on normal data flow have been lifted. Normal data may be sent again. .TP .SM \%T_GOEXDATA (XTI only) flow control restrictions on expedited data flow have been lifted. Expedited data may be sent again. .SH ERRORS On failure, .CR t_errno is set to one of the following: .TP 17 .SM \%[TBADF] The specified identifier does not refer to a transport endpoint. .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no suitable XTI (\c .CR t_errno ). .SH SEE ALSO t_open(3), t_snd(3), t_sndudata(3). .\" .SH STANDARDS CONFORMANCE .CR t_look() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_look\f1 \- look at current event on transport endpoint (X/OPEN TLI-XTI)@@@\f3t_look(3)\f1 .\" index@\f1event on transport endpoint, look at current event (X/OPEN TLI-XTI)@@@\f3t_look(3)\f1 .\" index@\f1XTI function, look at current event on transport endpoint@@@\f3t_look(3)\f1 .\" index@\f1TLI function, look at current event on transport endpoint@@@\f3t_look(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, look at current event on transport endpoint@@@\f3t_look(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, look at current event on transport endpoint@@@\f3t_look(3)\f1 .\" .\" toc@\f3t_look(3)\f1:\0\0\f4t_look()\f1@@@X/OPEN TLI-XTI - look at current event on transport endpoint .\" .\" fileset_database@t_look.3 TLI-XTI-MAN .\" $Header: t_open.3,v 74.2 95/03/15 16:58:01 ssa Exp $ .TA t .TH t_open 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_open() \- establish a transport endpoint .SH SYNOPSIS .PP .CR "#include " .P .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_open (name, oflag, info)" .CR "char *name;" .CR "int oflag;" .CR "struct t_info *info;" .fi .SH DESCRIPTION .PP The .CR t_open() function must be called as the first step in the initialization of a transport endpoint. This function establishes a transport endpoint by opening a file that identifies a particular transport provider and returning a file descriptor that identifies that endpoint. .PP The argument .IR name points to a file name that identifies a transport provider. When using HP XTI to connect to the OSI protocol stack, .IR name must be .CR /dev/ositpi for the connection-mode service, or .CR /dev/osicltpi for the connectionless service. When using HP XTI to connect to the TCP protocol stack, .IR name must be .CR /dev/inet_cots. For UDP, .IR name must be .CR /dev/inet_clts. For TLI, use the device file name of the transport provider desired. Note that HP TCP/UDP/IP and HP OSI COTS and CLTS only support XTI. .PP .IR oflag identifies any open flags (as in .CR open() ) and is constructed from .CR O_RDWR optionally or-ed with .CR O_NONBLOCK . These flags are defined by the header file .CR . .CR t_open() returns a file descriptor that will be used by all subsequent functions to identify the particular local transport endpoint. .P This function also returns various default characteristics of the underlying transport protocol by setting fields in the .CR t_info structure. This argument points to a .CR t_info which contains the following members: .P .nf long addr; /* max size of the transport protocol */ /* address */ long options; /* max number of bytes of */ /* protocol-specific options */ long tsdu; /* max size of a transport service data */ /* unit (TSDU) */ long etsdu; /* max size of an expedited transport */ /* service data unit (ETSDU) */ long connect; /* max amount of data allowed on */ /* connection establishment functions */ long discon; /* max amount of data allowed on */ /* t_snddis and t_rcvdis functions */ long servtype; /* service type supported by the */ /* transport provider */ long flags; /* other info about the transport provider */ .fi .P The values of the fields have the following meanings: .TP 15 .IR addr A value greater than or equal to zero indicates the maximum size of a transport protocol address. .RS 15 .P A value of -1 specifies that there is no limit on the address size. .P A value of -2 specifies that the transport provider does not provide user access to transport protocol addresses. .RE .TP .IR options A value greater than or equal to zero indicates the maximum number of bytes of protocol-specific options supported by the provider. .RS 15 .P A value of -1 specifies that there is no limit on the option size. .P A value of -2 specifies that the transport provider does not support user-settable options. .RE .TP .IR tsdu A value greater than zero specifies the maximum size of a transport service data unit (TSDU). .RS 15 .P A value of zero specifies that the transport provider does not support the concept of TSDU, although it does support the sending of a data stream with no logical boundaries preserved across a connection. .P A value of -1 specifies that there is no limit on the size of a TSDU. .P A value of -2 specifies that the transfer of normal data is not supported by the transport provider. .RE .TP .IR etsdu A value greater than zero specifies the maximum size of an expedited transport service data unit (ETSDU). .RS 15 .P A value of zero specifies that the transport provider does not support the concept of ETSDU, although it does support the sending of an expedited data stream with no logical boundaries preserved across a connection. .P A value of -1 specifies that there is no limit on the size of an ETSDU. .P A value of -2 specifies that the transfer of expedited data is not supported by the transport provider. .RE .TP .IR connect A value greater than or equal to zero specifies the maximum amount of data that may be associated with the connection establishment functions .CR t_connect() and .CR t_rcvconnect() . .RS 15 .P A value of -1 specifies that there is no limit on the amount of data sent during connection establishment. .P A value of -2 specifies that the transport provider does not allow data to be sent with connection establishment functions. .RE .TP .IR discon A value greater than or equal to zero specifies the maximum amount of data that may be associated with the and functions. .RS 15 .P A value of -1 specifies that there is no limit on the amount of data sent with these abortive release functions. .P A value of -2 specifies that the transport provider does not allow data to be sent with the abortive release functions. .RE .TP .IR servtype This field specifies the service type supported by the transport provider, as described below. .TP .IR flags This is a bit field used to specify other information about the transport provider. If the T_SENDZERO bit is set in flags, this indicates the underlying transport provider supports the sending of zero-length TSDUs. See Appendix A, "ISO Transport Protocol Information," of the .IR "CAE Specification X/Open Transport Interface (XTI)" manual from X/Open Company Limited for a discussion of the separate issue of zero-length fragments within a TSDU. .PP If a transport user is concerned with protocol independence, the above sizes may be accessed to determine how large the buffer must be to hold each piece of information. Alternatively, the .CR t_alloc() function may be used to allocate these buffers. An error will result if a transport user exceeds the allowed data size on any function. .PP The .IR servtype field of .IR info specifies one of the following values on return: .TP 15 .SM .CR T_COTS The transport provider supports a connection-mode service but does not support the optional orderly release facility. .TP .SM .CR T_COTS_ORD The transport provider supports a connection-mode service with the optional orderly release facility. .TP .SM .CR T_CLTS The transport provider supports a connectionless-mode service. For this service type, .CR t_open() will return -2 for .IR etsdu , .IR connect , and .IR discon . .P .RS 15 A single transport endpoint may support only one of the above services at one time. .RE .PP If .IR info is set to a null pointer by the transport user, no protocol information is returned by .CR t_open() . .SH "RETURN VALUE" A valid endpoint identifier is returned upon successful completion. Otherwise, a value of -1 is returned and .CR t_errno is set to indicate an error. .PP HP OSI does not support the .CR T_COTS_ORD servtype. .SH ERRORS On error, .CR t_errno is set to one of the following: .TP 15 .SM \%[TBADFLAG] An invalid flag is specified. .TP .SM \%[TBADNAME] Invalid transport provider name. .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no suitable XTI (\c .CR t_errno ). .SH SEE ALSO .PP open(2), t_sync(3). .\" .SH STANDARDS CONFORMANCE .CR t_open() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_open\f1 \- establish transport endpoint (X/OPEN TLI-XTI)@@@\f3t_open(3)\f1 .\" index@\f1transport endpoint, establish (X/OPEN TLI-XTI)@@@\f3t_open(3)\f1 .\" index@\f1XTI function, establish transport endpoint@@@\f3t_open(3)\f1 .\" index@\f1TLI function, establish transport endpoint@@@\f3t_open(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, establish transport endpoint@@@\f3t_open(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, establish transport endpoint@@@\f3t_open(3)\f1 .\" .\" toc@\f3t_open(3)\f1:\0\0\f4t_open()\f1@@@X/OPEN TLI-XTI - establish transport endpoint .\" .\" fileset_database@t_open.3 TLI-XTI-MAN .\" $Header: t_optmgmt.3,v 72.3 94/11/15 13:03:23 ssa Exp $ .TA t .TH t_optmgmt 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_optmgmt() \- manage options for a transport endpoint .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_optmgmt (fd, req, ret)" .CR "int fd;" .CR "struct t_optmgmt *req;" .CR "struct t_optmgmt *ret;" .fi .SH DESCRIPTION The .CR t_optmgmt() function enables a transport user to retrieve, verify or negotiate protocol options with the transport provider. The argument .IR fd identifies a bound transport endpoint. .P The .IR req and .IR ret arguments point to a .CR t_optmgmt structure containing the following members: .P .nf struct netbuf opt; long flags; .fi .P The .IR opt field identifies protocol options. The .IR flags field is used to specify the action to take with those options. .P The options are represented by a .CR netbuf structure in a manner similar to the address in .CR t_bind() . The argument .IR req is used to request a specific action of the provider and to send options to the provider. The argument .IR len specifies the number of bytes in the options. .IR buf points to the options buffer. .IR maxlen has no meaning for the .IR req argument. For XTI over the OSI transport provider, the options buffer should be of struct .CR isoco_options for connection-oriented service, or struct .CR isocl_options for connectionless service. For TLI, see the documentation of the transport provider being used. .PP The transport provider may return options and flag values to the user through .IR ret . For .IR ret , maxlen specifies the maximum size of the options buffer, and .IR buf points to the buffer where the options are to be placed. For XTI over the OSI transport provider, the options buffer should be of struct .CR isoco_options for connection-oriented service, or struct .CR isocl_options for connectionless service. For TLI, see the documentation of the transport provider being used. On return, .IR len specifies the number of bytes of options returned. The value in .IR maxlen has no meaning for the .IR req argument, but must be set in the .IR ret argument to specify the maximum number of bytes the options buffer can hold. The actual content of the options is imposed by the transport provider. .P Each option in the options buffer is of the form .CR "struct t_opthdr" possibly followed by an option value. .P The .IR level field of struct .CR t_opthdr identifies the XTI level or a protocol of the transport provider. The .IR name field identifies the option within the level. .IR len contains its total length; i.e. the length of the option header .CR t_opthdr plus the length of the option value. If .CR t_optmgmt() is called with the action T_NEGOTIATE set, the .IR status field of the returned options contains information about the success or failure of a negotiation. .P Each option in the input or output option buffer must start at a long-word boundary. The macro .CR "OPT_NEXTHDR(pbuf, buflen, option)" can be used for that purpose. The parameter .IR pbuf denotes a pointer to an option buffer .IR opt.buf , and .IR buflen is its length. The parameter .IR option points to a current option in the option buffer. .CR OPT_NEXTHDR returns a pointer to the position of the next option or returns a null pointer if the option buffer is exhausted. The macro is helpful for writing and reading. See .CR in the .IR "CAE Specification X/Open Transport Interface (XTI)" manual from X/Open Company Limited for the exact definition. .P If the transport user specifies several options on input, all options must address the same level. .P If any option in the options buffer does not indicate the same level as the first option, or the level specified is unsupported, then the .CR t_optmgmt() request will fail with [TBADOPT]. If the error is detected, some options have possibly been successfully negotiated. The transport user can check the current status by calling .CR t_optmgmt() with the T_CURRENT flag set. .PP The .IR flags field of .IR req must specify one of the following actions: .TP 17 .SM \%T_NEGOTIATE This action enables the transport user to negotiate option values. .RS 17 .P The user specifies the options of interest and their values in the buffer specified by .IR req->opt.buf and .IR req->opt.len . The negotiated option values are returned in the buffer pointed to by .IR ret->opt.buf . The status field of each returned option is set to indicate the result of the negotiation. The status is one of the following: .TP 20 T_SUCCESS if the proposed value was negotiated. .TP T_PARTSUCCESS if a degraded value was negotiated. .TP T_FAILURE if the negotiation failed according to the negotiation rules. .TP T_NOTSUPPORT if the transport provider does not support this option or illegally requests negotiation of a privileged option. .TP T_READONLY if modification of a read-only option was requested. .P If the status is T_SUCCESS, T_FAILURE, T_NOTSUPPORT or T_READONLY, the returned option value is the same as the one requested on input. .P The overall result of the negotiation is returned in .IR ret->flags . .P This field contains the worst single result, whereby the rating is done according to the order of T_NOTSUPPORT, T_READONLY, T_FAILURE, T_PARTSUCCESS, T_SUCCESS. The value T_NOTSUPPORT is the worst result and T_SUCCESS is the best. .P For each level, the option T_ALLOPT can be requested on input. No value is given with this option; only the .CR t_opthdr part is specified. This input requests to negotiate all supported options of this level to their default values. The result is returned option by option in .IR ret->opt.buf . (Note that depending on the state of the transport endpoint, not all requests to negotiate the default may be successful.) .RE .TP .SM \%T_CHECK This action enables the user to verify whether the options specified in .IR req are supported by the transport provider. .RS 17 .P If an option is specified with no option value (it consists only of a .CR t_opthdr structure), the option is returned with its .IR status field set to T_SUCCESS if it is supported, T_NOTSUPPORT if it is not or needs additional user privileges, and T_READONLY if it is read-only (in the current state). No option value is returned. .P If an option is specified with an option value, the .IR status field of the returned option has the same value, as if the user had tried to negotiate this value with T_NEGOTIATE. If the status is T_SUCCESS, T_FAILURE, T_NOTSUPPORT, or T_READONLY, the returned option value is the same as the one requested on input. .P The overall result of the option checks is returned in .IR ret->flags . This field contains the worst single result of the option checks, whereby the rating is the same as for T_NEGOTIATE. .P Note that no negotiation takes place. All currently effective option values remain unchanged. .RE .TP 17 .SM \%T_DEFAULT This action enables the transport user to retrieve the default option values. The user specifies the option of interest in .IR req->opt.buf . The option values are irrelevant and will be ignored; it is sufficient to specify the .CR t_opthdr part of an option only. The default values are then returned in .IR ret->opt.buf . .RS 17 .P The .IR status field returned is one of the following: .TP 20 T_NOTSUPPORT if the protocol level does not support this option or if the transport user illegally requested a privileged option. .TP T_READONLY if the option is read-only. .TP T_SUCCESS in all other cases. .RE .P .RS 17 The overall result of the request is returned in .IR ret->flags . This field contains the worst single result, whereby the rating is the same as for T_NEGOTIATE. .P For each level, the option T_ALLOPT can be requested on input. All supported options of this level with their default values are then returned. In this case, .IR ret->opt.maxlen must be given at least the value .IR info->options (see .IR t_getinfo (3), .IR t_open (3)) before the call. .RE .TP 17 .SM \%T_CURRENT This action enables the transport user to retrieve the currently effective option values. The user specifies the options of interest in .IR req->opt.buf . The option values are irrelevant and will be ignored; it is sufficient to specify the .CR t_opthdr part of an option only. The default values are then returned in .IR ret->opt.buf . .P .RS 17 The .IR status field returned is one of the following: .TP 20 T_NOTSUPPORT if the protocol level does not support this option or if the transport user illegally requested a privileged option. .TP T_READONLY if the option is read-only. .TP T_SUCCESS in all other cases. .RE .P .RS 17 The overall result of the request is returned in .IR ret->flags . This field contains the worst single result, whereby the rating is the same as for T_NEGOTIATE. .P For each level, the option T_ALLOPT can be requested on input. All supported options of this level with their currently effective values are then returned. .P The option T_ALLOPT can only be used with .CR t_optmgmt() and the actions T_NEGOTIATE, T_DEFAULT, and T_CURRENT. It can be used with any supported level and addresses all supported options of this level. The option has no value; it consists of a .CR t_opthdr only. Since in a .CR t_optmgmt() call only options of one level may be addressed, this option should not be requested together with other options. The function returns as soon as this option has been processed. .P Options are independently processed in the order they appear in the input option buffer. If an option is multiply input, it depends on the implementation whether it is multiply output or whether it is returned only once. .P Transport providers may not be able to provide an interface capable of supporting T_NEGOTIATE and/or T_CHECK functionalities. When this is the case, the error [T_NOTSUPPORT] is returned. .RE .P The function .CR t_optmgmt() may block under various circumstances and depending on the implementation. The function will block, for instance, if the protocol addressed by the call resides on a separate controller. It may also block due to flow control constraints, i.e. if data set previously across this transport endpoint has not yet been fully processed. If the function is interrupted by a signal, the option negotiations that have been done so far may remain valid. The behavior of the function is not changed if O_NONBLOCK is set. .SS XTI-Level Options XTI level options are not specific for a particular transport provider. An XTI implementation supports none, all or any subset of the options defined below. An implementation may restrict the use of any of these options by offering them only in the priveleged or read-only mode, or if .IR fd relates to specific transport providers. .P The subsequent options are not association-related. They may be negotiated in all XTI states except T_UNINIT. .P The protocol level is XTI_GENERIC. For this level, the following options are defined. A request for XTI_DEBUG is an absolute requirement. A request to activate XTI_LINGER is an absolute requirement; the timeout value to this option is not. XTI_RCVBUF, XTI_RECVLOWAT, XTI_SNDBUF, and XTI_SNDLOWAT are not absolute requirements. .TP 17 .SM \%XTI_DEBUG This option enables debugging. The values of this option are implementation- defined. Debugging is disabled if the option is specified with "no value", i.e. with an option header only. .RS 17 .P The system supplies utilities to process the traces. Note that an implementation may also provide other means for debugging. .RE .TP .SM \%XTI_LINGER This option is used to linger the execution of a .CR t_close() or .CR close() if send data is still queued in the send buffer. The option value specifies the linger period. If a .CR close() or .CR t_close() is issued and the send buffer is not empty, the system attempts to send the pending data within the linger period before closing the endpoint. Data still pending after the linger period has elapsed is discarded. .RS 17 .P Depending on the implementation, .CR t_close() or .CR close() either block for at maximum the linger period, or immediately return, whereupon the system holds the connection in existence for at most the linger period. .P The option constists of a structure .CR t_linger declared as: .P .nf struct t_linger{ long l_onoff; /* switch option on/off */ long l_linger; /* linger period in seconds */ } .fi .P Legal values for the .IR l_onoff are: .P .nf T_NO switch option off T_YES activate option .fi .P The value of .IR l_onoff is an absolute requirement. .P The field .IR l_linger determines the linger period in seconds. The transport user can request the default value by setting the field to T_UNSPEC. The default timeout value depends on the underlying transport provider (it is often T_INFINITE). Legal values for this field are T_UNSPEC, T_INFINITE, and all non-negative numbers. .P The .IR l_linger value is not an absolute requirement. The implementation may place upper and lower limits to this value. Requests that fall short of the lower limit are negoitated to the lower limit. .P Note that this option does not linger the execution of .CR t_snddis() . .RE .TP .SM \%XTI_RCVBUF This option is used to adjust the internal buffer size allocated for the receive buffer. The buffer size may be increased for high-volume connections, or decreased to limit the possible backlog of incoming data. .RS 17 .P This request is not an absolute requirement. The implementation may place upper and lower limits on the option value. Requests that fall short of the lower limit are negotiated to the lower limit. .P Legal values are all positive numbers. .RE .TP 17 .SM \%XTI_RCVLOWAT This option is used to set a low-water mark in the receive buffer. The option values gives the minimal number of bytes that must have accumulated in the receive buffer before they become visible to the transport user. If and when the amount of accumulated receive data exceeds the low-water mark, a T_DATA event is created, an event mechanism (e.g. .CR poll() or .CR select() ) indicates the data, and the data can be read by .CR t_rcv() or .CR t_rcvudata() . .RS 17 .P This request is not an absolute requirement. The implementation may place upper and lower limits on the option value. Requests that fall short of the lower limit are negotiated to the lower limit. .P Legal values are all positive numbers. .RE .TP 17 .SM \%XTI_SNDBUF This option is used to adjust the internal buffer size allocated for the send buffer. .RS 17 .P This request is not an absolute requirement. The implementation may place upper and lower limits on the option value. Requests that fall short of the lower limit are negotiated to the lower limit. .P Legal values are all positive numbers. .RE .TP .SM \%XTI_SNDLOWAT This option is used to set a low-water mark in the send buffer. The option value gives the minimal number of bytes that must have accumulated in the send buffer before they are sent. .RS 17 .P This request is not an absolute requirement. The implementation may place upper and lower limits on the option value. Requests that fall short of the lower limit are negotiated to the lower limit. .P Legal values are all positive numbers. .RE .SS Valid States All - apart from T_UNINIT .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned, and .CR t_errno is set to indicate the error. .P TLI supports any transport provider which is compliant with TPI (Transport Provider Interface). Users can access TLI versions of the .CR t_* routines by linking with .CR /usr/lib/libnsl_s.a . For more information on TLI, see the TLI section of .IR "STREAMS/UX for HP 9000 Reference Manual" . .SH ERRORS On failure, .CR t_errno is set to the following .TP 17 .SM \%[TBADF] The specified identifier does not refer to a transport endpoint. .TP .SM \%[TOUTSTATE] The function was issued in the wrong sequence. .TP .SM \%[TACCES] The user does not have the permission to negotiate the specified options. .TP .SM \%[TBADOPT] The specified protocol options were in an incorrect format or contained illegal information. .TP .SM \%[TBADFLAG] An invalid flag was specified. .TP .SM \%[TBUFOVFLW] The number of bytes allowed for an incoming argument (\c .IR maxlen ) is greater than 0 and not sufficient to store the value of that argument. The information to be returned in .IR ret will be discarded. .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no existing XTI .CR t_errno . .TP .SM \%[TNOTSUPPORT] (XTI only) This action is not supported by the underlying transport provider. .SH SEE ALSO t_accept(3), t_alloc(3), t_connect(3), t_getinfo(3), t_listen(3), t_open(3), t_rcvconnect(3). .\" .SH STANDARDS CONFORMANCE .CR t_optmgmt() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_optmgmt\f1 \- manage options for transport endpoint (X/OPEN TLI-XTI)@@@\f3t_optmgmt(3)\f1 .\" index@\f1options for transport endpoint (X/OPEN TLI-XTI)@@@\f3t_optmgmt(3)\f1 .\" index@\f1transport endpoint, manage options (X/OPEN TLI-XTI)@@@\f3t_optmgmt(3)\f1 .\" index@\f1XTI function, manage options for transport endpoint@@@\f3t_optmgmt(3)\f1 .\" index@\f1TLI function, manage options for transport endpoint@@@\f3t_optmgmt(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, manage options for transport endpoint@@@\f3t_optmgmt(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, manage options for transport endpoint@@@\f3t_optmgmt(3)\f1 .\" .\" toc@\f3t_optmgmt(3)\f1:\0\0\f4t_optmgmt()\f1@@@X/OPEN TLI-XTI - manage options for transport endpoint .\" .\" fileset_database@t_optmgmt.3 TLI-XTI-MAN .\" $Header: t_rcv.3,v 76.1 95/06/12 15:54:39 ssa Exp $ .TA t .TH t_rcv 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_rcv() \- receive data or expedited data sent over a connection .SH SYNOPSIS .PP .P .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_rcv (fd, buf, nbytes, flags)" .CR "int fd;" .CR "char *buf;" .CR "unsigned nbytes;" .CR "int *flags;" .fi .SH DESCRIPTION The .CR t_rcv() function receives either normal or expedited data. .IR fd identifies the local transport endpoint through which data will arrive. .IR buf points to a receive buffer where user data will be placed. .IR nbytes specifies the size of the receive buffer. .IR flags may be set on return from .CR t_rcv() and specifies optional flags as described below. .P By default, .CR t_rcv() operates in synchronous mode and will wait for data to arrive if none is currently available. However, if .CR O_NONBLOCK is set (via .CR t_open() or .CR fcntl() ), .CR t_rcv() will execute in asynchronous mode and will fail if no data is available. (See [TNODATA] below.) .P On return from the call, if T_MORE is set in .IR flags , this indicates that there is more data. Thus, the current transport service data unit (TSDU) or expedited transport service data unit (ETSDU) must be received in multiple .CR t_rcv() calls. In the asynchronous mode, the T_MORE flag may be set on return from the .CR t_rcv() call even when the number of bytes received is less than the size of the the receive buffer specified. Each .CR t_rcv() with the T_MORE flag set indicates that another .CR t_rcv() must follow immediately to get more data for the current TSDU. The end of the TSDU is identified by the return of a .CR t_rcv() call with the T_MORE flag not set. If the transport provider does not support the concept of a TSDU as indicated in the .IR info argument on return from .CR t_open() or .CR t_getinfo() , the T_MORE flag is not meaningful and should be ignored. If .IR nbytes is greater than zero on the call to .CR t_rcv() , .CR t_rcv() will return 0 only if the end of a TSDU is being returned to the user. .P On return, the data returned is expedited data if T_EXPEDITED is set in .IR flags . If the number of bytes of expedited data exceeds .IR nbytes , .CR t_rcv() will set T_EXPEDITED and T_MORE on return from the initial call. Subsequent calls to retrieve the remaining ETSDU will have T_EXPEDITED set on return. The end of the ETSDU is identified by the return of a .CR t_rcv() call with the T_MORE flag not set. .P If expedited data arrives after part of a TSDU has been retrieved, receipt of the remainder of the TSDU will be suspended until the ETSDU has been processed. Only after the full ETSDU has been retrieved (T_MORE not set) will the remainder of the TSDU be available to the user. .P In synchronous mode, the only way for the user to be notified of the arrival of normal or expedited data is to issue this function or check for the T_DATA or T_EXDATA events using the .CR t_look() function. .SH XTI Internet Protocol-specific Information The T_MORE flag should be ignored if normal data is delivered. If a byte in the data stream is pointed to by the TCP urgent pointer, as many bytes as possible preceding this marked byte and the marked byte itself are denoted as urgent data and are received with the T_EXPEDITED flag set. If the buffer supplied by the user is too small to hold all urgent data, the T_MORE flag will be set, indicating that urgent data still remains to be read. Note that the number of bytes received with the T_EXPEDITED flag set is not necessarily equal to the number of bytes sent by the peer user with T_EXPEDITED flag set. .SH RETURN VALUE Upon successful completion, .CR t_rcv() returns the number of bytes received. Otherwise, it return -1 and .CR t_errno is set to indicate the error. .SH ERRORS On failure, .CR t_errno is set to one of the following: .TP 17 .SM \%[TBADF] The specified identifier does not refer to a transport endpoint. .TP .SM \%[TNODATA] .CR O_NONBLOCK was set, but no data is currently available from the transport provider. .TP .SM \%[TLOOK] An asynchronous event has occurred on this transport endpoint and requires immediate attention. .TP .SM \%[TNOTSUPPORT] This function is not supported by the underlying transport provider. .TP .SM \%[TOUTSTATE] (XTI only) The function was issued in the wrong sequence on the endpoint referenced by .IR fd . .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no other suitable XTI (\c .CR t_errno ). .PP .SH SEE ALSO t_getinfo(3), t_look(3), t_open(3), t_snd(3), fcntl(2). .\" .SH STANDARDS CONFORMANCE .CR t_rcv() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_rcv\f1 \- receive normal or expedited data sent over connection (X/OPEN TLI-XTI)@@@\f3t_rcv(3)\f1 .\" index@\f1data over connection, receive (X/OPEN TLI-XTI)@@@\f3t_rcv(3)\f1 .\" index@\f1connection, receive data (X/OPEN TLI-XTI)@@@\f3t_rcv(3)\f1 .\" index@\f1XTI function, receive data over connection@@@\f3t_rcv(3)\f1 .\" index@\f1TLI function, receive data over connection@@@\f3t_rcv(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, receive data over connection@@@\f3t_rcv(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, receive data over connection@@@\f3t_rcv(3)\f1 .\" .\" toc@\f3t_rcv(3)\f1:\0\0\f4t_rcv()\f1@@@X/OPEN TLI-XTI - receive data over connection .\" .\" fileset_database@t_rcv.3 TLI-XTI-MAN .\" $Header: t_rcvconnect.3,v 72.3 94/11/15 13:03:26 ssa Exp $ .TA t .TH t_rcvconnect 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_rcvconnect() \- receive the confirmation from a connect request .SH SYNOPSIS .PP .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_rcvconnect (fd, call)" .CR "int fd;" .CR "struct t_call *call;" .fi .SH DESCRIPTION The .CR t_rcvconnect() function enables a calling transport user to determine the status of a previously sent connect request. .CR t_rcvconnect() is also used in conjunction with .CR t_connect() to establish a connection in asynchronous mode. The connection will be established on successful completion of this function. .P .IR fd identifies the local transport endpoint where communication will be established. .IR call contains information associated with the newly established connection. .IR call points to a .CR t_call structure which contains the following members: .P .nf struct netbuf addr; struct netbuf opt; struct netbuf udata; int sequence; .fi .P The type .CR netbuf structure is defined in the .CR or .CR header file. This structure, which is used to define buffer parameters, has the following members: .TP 25 .SM .CR "unsigned int maxlen" maximum byte length of the data buffer .TP .SM .CR "unsigned int len" actual byte length of data written to buffer .TP .SM .CR "char *buf" points to buffer location .P In .IR call , .IR addr returns the protocol address associated with the responding transport endpoint. .IR opt presents any protocol-specific information associated with the connection. For XTI over the OSI transport provider, struct .CR isoco_options should be used. For TLI, see the documentation for the transport provider being used. .IR udata points to optional user data that may be returned by the destination transport user during connection establishment. .IR sequence has no meaning for this function. .P The .IR maxlen field of each argument must be set before issuing this function to indicate the maximum size of the buffer for each. However, .IR call may be a null pointer, in which case no information is given to the user on return from .CR t_rcvconnect() . By default, .CR t_rcvconnect() executes in synchronous mode and waits for the connection to be established before returning. On return, the .IR addr , .IR opt , and .IR udata fields reflect values associated with the connection. .P If .CR O_NONBLOCK is set (via .CR t_open() or .CR fcntl() ), .CR t_rcvconnect() executes in asynchronous mode, and reduces to a poll for existing connect confirmations. If none are available, .CR t_rcvconnect() fails and returns immediately without waiting for the connection to be established. (See [TNODATA] below.) .CR t_rcvconnect() must be re-issued at a later time to complete the connection establishment phase and retrieve the information returned in .IR call . .SS Valid States T_OUTCON .PP .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and .CR t_errno is set to indicate the error. .SH ERRORS On failure, .CR t_errno is set to one of the following: .TP 17 .SM \%[TBADF] The specified identifier does not refer to a transport endpoint. .TP .SM \%[TBUFOVFLW] The number of bytes allocated for an incoming argument is not sufficient to store the value of that argument and the connect information to be returned in .I call will be discarded. The provider's state, as seen by the user, will be changed to T_DATAXFER. .TP .SM \%[TNODATA] .CR O_NONBLOCK was set, but a connect confirmation has not yet arrived. .TP .SM \%[TLOOK] An asynchronous event has occurred on this transport endpoint and requires immediate attention. .TP .SM \%[TNOTSUPPORT] This function is not supported by the underlying transport provider. .TP .SM \%[TOUTSTATE] This function was issued in the wrong sequence on the transport endpoint referenced by .IR fd . .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no existing XTI (\c .CR t_errno ). .SH FILES .PP .TP 32 .CR "/usr/include/xti.h" XTI data structure .TP 32 .CR /usr/include/tiuser.h TLI data structure .SH SEE ALSO fcntl(2), t_accept(3), t_alloc(3), t_bind(3), t_connect(3), t_listen(3), t_open(3). .\" .SH STANDARDS CONFORMANCE .CR t_rcvconnect() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_rcvconnect\f1 \- receive confirmation from connect request (X/OPEN TLI-XTI)@@@\f3t_rcvconnect(3)\f1 .\" index@\f1confirmation from connect request (X/OPEN TLI-XTI)@@@\f3t_rcvconnect(3)\f1 .\" index@\f1request, receive confirmation (X/OPEN TLI-XTI)@@@\f3t_rcvconnect(3)\f1 .\" index@\f1XTI function, receive confirmation from connect request@@@\f3t_rcvconnect(3)\f1 .\" index@\f1TLI function, receive confirmation from connect request@@@\f3t_rcvconnect(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, receive confirmation from connect request@@@\f3t_rcvconnect(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, receive confirmation from connect request@@@\f3t_rcvconnect(3)\f1 .\" .\" toc@\f3t_rcvconnect(3)\f1:\0\0\f4t_rcvconnect()\f1@@@X/OPEN TLI-XTI - receive confirmation from connect request .\" .\" fileset_database@t_rcvconnect.3 TLI-XTI-MAN .\" $Header: t_rcvdis.3,v 72.3 94/11/15 13:03:28 ssa Exp $ .TA t .TH t_rcvdis 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_rcvdis() \- retrieve information from disconnect .SH SYNOPSIS .PP .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_rcvdis (fd, discon)" .CR "int fd;" .CR "struct t_discon *discon;" .fi .SH DESCRIPTION The .CR t_rcvdis() function is used to identify the cause of a disconnect, and to retrieve any user data sent with the disconnect. .IR fd identifies the local transport endpoint where the connection existed. .IR discon points to a .CR t_discon structure containing the following members: .P .nf struct netbuf udata; int reason; int sequence; .fi .P The type .CR netbuf structure is defined in the .CR or .CR header file. This structure, which is used to define buffer parameters, has the following members: .TP 25 .SM .CR "unsigned int maxlen" maximum byte length of the data buffer .TP .SM .CR "unsigned int len" actual byte length of data written to buffer .TP .SM .CR "char *buf" points to buffer location .PP .IR reason specifies the reason for the disconnect through a protocol-dependent reason code. For HP XTI over the OSI transport provider, these codes are described in the OTS/9000 manual section under "Transport Errors". For TLI, see the documentation for the transport provider being used. .IR udata identifies any user data that was sent with the disconnect. .IR sequence may identify an outstanding connect indication with which the disconnect is associated. .IR sequence is only meaningful when .CR t_rcvdis() is issued by a passive transport user who has executed one or more .CR t_listen() functions and is processing the resulting connect indications. If a disconnect indication occurs, .IR sequence can be used to identify which of the outstanding connect indications is associated with the disconnect. .PP If a user does not care that there is incoming data and does not need to know the value of .IR reason or .IR sequence , .IR discon may be a null pointer and any user data associated with the disconnect will be discarded. However, if a user has retrieved more than one outstanding connect indication (via .CR t_listen() ) and .IR discon is a null pointer, the user will be unable to identify with which connect indication the disconnect is associated. .SS Valid States T_DATAXFER, T_OUTCON, T_OUTREL, T_INREL, T_INCON (ocnt > 0) .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and .CR t_errno is set to indicate the error. .SH ERRORS On failure, .CR t_errno is set to one of the following: .TP 17 .SM \%[TBADF] The specified identifier does not refer to a transport endpoint. .TP .SM \%[TNODIS] No disconnect indication currently exists on the specified transport endpoint. .TP .SM \%[TBUFOVFLW] The number of bytes allocated for incoming data is not sufficient to store the data. If .IR fd is a passive endpoint with .IR ocnt (number of outstanding connections) > 1, it remains in state T_INCON (see .CR t_getstate ). Otherwise, the endpoint state is set to T_IDLE. .TP .SM \%[TNOTSUPPORT] This function is not supported by the underlying transport provider. .TP .SM \%[TOUTSTATE] (XTI only) This function was issued in the wrong sequence on the transport endpoint referenced by .IR fd . .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no existing XTI (\c .CR t_errno ). .SH SEE ALSO t_alloc(3), t_connect(3), t_listen(3), t_open(3), t_snddis(3). .\" .SH STANDARDS CONFORMANCE .CR t_rcvdis() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_rcvdis\f1 \- retrieve information from disconnect (X/OPEN TLI-XTI)@@@\f3t_rcvdis(3)\f1 .\" index@\f1disconnect information (X/OPEN TLI-XTI)@@@\f3t_rcvdis(3)\f1 .\" index@\f1XTI function, retrieve disconnect information@@@\f3t_rcvdis(3)\f1 .\" index@\f1TLI function, retrieve disconnect information@@@\f3t_rcvdis(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, retrieve disconnect information@@@\f3t_rcvdis(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, retrieve disconnect information@@@\f3t_rcvdis(3)\f1 .\" .\" toc@\f3t_rcvdis(3)\f1:\0\0\f4t_rcvdis()\f1@@@X/OPEN TLI-XTI - retrieve information from disconnect .\" .\" fileset_database@t_rcvdis.3 TLI-XTI-MAN .\" $Header: t_rcvrel.3,v 72.3 94/11/15 13:03:30 ssa Exp $ .TA t .TH t_rcvrel 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_rcvrel() \- acknowledge receipt of an orderly release indication at a transport endpoint .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_rcvrel (fd)" .CR "int fd;" .fi .SH DESCRIPTION The .CR t_rcvrel() function is used in connection-oriented mode to acknowledge receipt of an orderly release indication at a transport endpoint. The released endpoint is specified by .IR fd , which is a file descriptor previously returned by the .CR t_open() function. .P After receipt of this orderly release indication at the transport endpoint specified by .IR fd , the transport user should not try to receive additional data from that transport endpoint. Any attempt to receive more data from a released transport endpoint blocks continuously. However, the transport user may continue to send data across the connection until a release is sent by the transport user by invoking the .CR t_sndrel() function call. .P The .CR t_rcvrel() function should not be used unless the .IR servtype type-of-service returned by the .CR t_open() or .CR t_getinfo() functions is T_COTS_ORD (supports connection-mode service with the optional orderly release facility). .SS Valid States T_DATAXFER, T_OUTREL .SS Note HP OSI XTI does not support .CR t_rcvrel() . .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and .CR t_errno is set to indicate the error. .SH ERRORS On failure, .CR t_errno is set to one of the following: .TP 17 .SM \%[TBADF] The specified identifier does not refer to a transport endpoint. .TP .SM \%[TNOREL] No orderly release indication currently exists on the specified transport endpoint. .TP .SM \%[TBUFOVFLW] The number of bytes allocated for incoming data is not sufficient to store the data. .TP .SM \%[TNOTSUPPORT] This function is not supported by the underlying transport provider. .TP .SM \%[TLOOK] An asynchronous event has occurred on the transport endpoint referenced by .IR fd and requires immediate attention. .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no other suitable XTI (\c .CR t_errno ). .TP .SM \%[TOUTSTATE] (XTI only) The function was issued in the wrong sequence on the transport endpoint referenced by .IR fd . .SH SEE ALSO t_getinfo(3), t_open(3), t_sndrel(3). .\" .SH STANDARDS CONFORMANCE .CR t_rcvrel() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_rcvrel\f1 \- acknowledge receipt of release indication at transport endpoint (X/OPEN TLI-XTI)@@@\f3t_rcvrel(3)\f1 .\" index@\f1transport endpoint, acknowledge receipt of release (X/OPEN TLI-XTI)@@@\f3t_rcvrel(3)\f1 .\" index@\f1XTI function, acknowledge receipt of orderly release indication at transport endpoint@@@\f3t_rcvrel(3)\f1 .\" index@\f1TLI function, acknowledge receipt of orderly release indication at transport endpoint@@@\f3t_rcvrel(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, acknowledge receipt of orderly release indication \n\f1at transport endpoint@@@\f3t_rcvrel(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, acknowledge receipt of orderly release indication \n\f1at transport endpoint@@@\f3t_rcvrel(3)\f1 .\" .\" toc@\f3t_rcvrel(3)\f1:\0\0\f4t_rcvrel()\f1@@@X/OPEN TLI-XTI - acknowledge receipt of release at transport endpoint .\" .\" fileset_database@t_rcvrel.3 TLI-XTI-MAN .\" $Header: t_rcvudata.3,v 72.3 94/11/15 13:03:35 ssa Exp $ .TA t .TH t_rcvudata 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_rcvudata() \- receive a data unit from remote transport provider user .SH SYNOPSIS .PP .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .PP .nf .CR "int t_rcvudata (fd, unitdata, flags)" .CR "inf fd;" .CR "struct t_unitdata *unitdata;" .CR "int *flags;" .fi .SH DESCRIPTION The .CR t_rcvudata() function is used in connectionless-mode to receive a data unit from a remote transport provider user. The argument .IR fd identifies the local transport endpoint through which data will be received. .IR unitdata holds information associated with the received data unit. .IR flags is set on return to indicate that the complete data unit was not received. The argument .IR unitdata points to a .CR t_unitdata structure containing the following members: .P .nf struct netbuf addr; struct netbuf opt; struct netbuf udata; .fi .P The type .CR netbuf structure is defined in the .CR or .CR header file. This structure, which is used to define buffer parameters, has the following members: .TP 25 .SM .CR "unsigned int maxlen" maximum byte length of the data buffer .TP .SM .CR "unsigned int len" actual byte length of data written to buffer .TP .SM .CR "char *buf" points to buffer location .P The .IR maxlen field of .IR addr , .IR opt and .IR udata must be set before calling this function to indicate the maximum size of the buffer for each. .PP On return from this call, .IR addr specifies the protocol address of the sending user, .IR opt identifies protocol-specific options that were associated with this data unit, and .IR udata specifies the user data that was received. .PP By default, .CR t_rcvudata() executes in the synchronous operating mode. The .CR t_rcvudata() function waits for data to arrive at the transport endpoint specified by .IR fd before returning control to the transport user who called this function. However, when the transport endpoint, specified by the .IR fd parameter, has the .CR O_NONBLOCK option set by .CR t_open() or .CR fcntl() function, the .CR t_rcvudata() function executes in asynchronous mode. In asynchronous mode, when a data unit is unavailable, control is immediately returned to the caller. .PP If the buffer defined in the .IR udata field of .IR unitdata is not large enough to hold the current data unit, the buffer will be filled and T_MORE will be set in .IR flags on return to indicate that another .CR t_rcvudata() should be called to retrieve the rest of the data unit. Subsequent calls to .CR t_rcvudata() will return zero for the length of the address and options until the full data unit has been received. .SS Valid States T_IDLE .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and .CR t_errno is set to indicate the error. .SH ERRORS On failure, .CR t_errno is set to one of the following: .TP 18 .SM \%[TBADF] The specified file descriptor does not refer to a transport endpoint. .TP .SM \%[TNODATA] .CR O_NONBLOCK was set, but no data units are currently available from the transport provider. .TP .SM \%[TBUFOVFLW] The number of bytes allocated for the incoming protocol address or protocol options is not sufficient to store the information. The unit data information normally returned in .IR unitdata is discarded. .TP .SM \%[TLOOK] An asynchronous event has occurred on this transport endpoint required immediate attention. .TP .SM \%[TNOTSUPPORT] This function is not supported by the underlying transport provider. .TP .SM \%[TOUTSTATE] (XTI only) The function was issued in the wrong sequence on the transport endpoint referenced by .IR fd . .TP .SM \%[TSYSERR] A system error occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no other suitable XTI (\c .CR t_errno ). .SH SEE ALSO fcntl(2), t_alloc(3), t_open(3), t_optmgmt(3), t_rcvuderr(3), t_sndudata(3). .\" .SH STANDARDS CONFORMANCE .CR t_rcvudata() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_rcvudata\f1 \- receive data unit from remote transport provider user (X/OPEN TLI-XTI)@@@\f3t_rcvudata(3)\f1 .\" index@\f1data unit from remote transport provider user (X/OPEN TLI-XTI)@@@\f3t_rcvudata(3)\f1 .\" index@\f1remote transport provider user (X/OPEN TLI-XTI)@@@\f3t_rcvudata(3)\f1 .\" index@\f1transport provider user (X/OPEN TLI-XTI)@@@\f3t_rcvudata(3)\f1 .\" index@\f1XTI function, receive data unit from remote transport provider user@@@\f3t_rcvudata(3)\f1 .\" index@\f1TLI function, receive data unit from remote transport provider user@@@\f3t_rcvudata(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, receive data unit from remote transport provider user@@@\f3t_rcvudata(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, receive data unit from remote transport provider user@@@\f3t_rcvudata(3)\f1 .\" .\" toc@\f3t_rcvudata(3)\f1:\0\0\f4t_rcvudata()\f1@@@X/OPEN TLI-XTI - receive data unit from remote transport provider user .\" .\" fileset_database@t_rcvudata.3 TLI-XTI-MAN .\" $Header: t_rcvuderr.3,v 72.3 94/11/15 13:03:36 ssa Exp $ .TA t .TH t_rcvuderr 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_rcvuderr() \- receive a unit data error indication .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .PP .nf .CR "int t_rcvuderr (fd, uderr)" .CR "int fd;" .CR "struct t_uderr *uderr;" .fi .SH DESCRIPTION The .CR t_rcvuderr() function is used in connectionless mode to receive information concerning an error on a previously sent data unit. This function should only be issued following a unit data error indication. It informs the transport user that a data unit with a specific destination address and protocol options produced an error. The argument .IR fd identifies the local transport endpoint through which the error report will be received. .IR uderr points to a type .CR t_uderr structure used to specify the protocol address, protocol options, and the nature of the error associated with the data unit sent through the transport endpoint specified by the .IR fd parameter. The .CR t_uderr structure has the following members: .P .nf struct netbuf addr; struct netbuf opt; long error; .fi .P The type .CR netbuf structure is defined in the .CR or .CR header file. This structure, which is used to define buffer parameters, has the following members: .TP 25 .SM .CR "unsigned int maxlen" maximum byte length of the data buffer .TP .SM .CR "unsigned int len" actual byte length of data written to buffer .TP .SM .CR "char *buf" points to buffer location .P The .IR maxlen field of .IR addr and .IR opt must be set before calling this function to indicate the maximum size of the buffer for each. .PP On return from this call, the .IR addr structure specifies the destination protocol address of the erroneous data unit the .IR opt structure identified protocol-specific options that were associated with the data unit and .IR error specifies a protocol dependent error code. .PP If the user does not care to identify the data unit that produced an error, .IR uderr may be set to a null pointer, and .CR t_rcvuderr() will simply clear the error indication without reporting any information to the user. .SS Valid States T_IDLE .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and .CR t_errno is set to indicate the error. .SH ERRORS On failure, .CR t_errno is set to one of the following: .TP 20 .SM \%[TBADF] The specified file descriptor does not refer to a transport endpoint. .TP .SM \%[TNOUDERR] No unit data error indication currently exists at the specified transport endpoint. .TP .SM \%[TBUFOVFLW] The number of bytes allocated for the incoming protocol address or options information is not sufficient to store that information. The unit data error information to be returned in .I uderr will be discarded. .TP .SM \%[TNOTSUPPORT] This function is not supported by the underlying transport provider. .TP .SM \%[TSYSERR] A system error occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no other suitable XTI (\c .CR t_errno ). .SH SEE ALSO t_look(3), t_rcvudata(3), t_sndudata(3). .\" .SH STANDARDS CONFORMANCE .CR t_rcvuderr() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_rcvuderr\f1 \- receive error information from unit data error indication (X/OPEN TLI-XTI)@@@\f3t_rcvuderr(3)\f1 .\" index@\f1error information from unit data error indication (X/OPEN TLI-XTI)@@@\f3t_rcvuderr(3)\f1 .\" index@\f1unit data error indication (X/OPEN TLI-XTI)@@@\f3t_rcvuderr(3)\f1 .\" index@\f1data error indication (X/OPEN TLI-XTI)@@@\f3t_rcvuderr(3)\f1 .\" index@\f1XTI function, receive error information from unit data error indication@@@\f3t_rcvuderr(3)\f1 .\" index@\f1TLI function, receive error information from unit data error indication@@@\f3t_rcvuderr(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, receive error information from unit data error indication@@@\f3t_rcvuderr(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, receive error information from unit data error indication@@@\f3t_rcvuderr(3)\f1 .\" .\" toc@\f3t_rcvuderr(3)\f1:\0\0\f4t_rcvuderr()\f1@@@X/OPEN TLI-XTI - receive error information from unit data error indication .\" .\" fileset_database@t_rcvuderr.3 TLI-XTI-MAN .\" $Header: t_snd.3,v 72.3 94/11/15 13:03:38 ssa Exp $ .TA t .TH t_snd 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_snd() \- send data or expedited data over a connection .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .PP .nf .CR "int t_snd (fd, buf, nbytes, flags)" .CR "int fd;" .CR "char *buf;" .CR "unsigned nbytes;" .CR "int flags;" .fi .SH DESCRIPTION This function is used to send either normal or expedited data. .IR fd identifies the local transport endpoint over which data should be sent, .IR buf points to the user data, .IR nbytes specifies the number of bytes of user data to be sent, and .IR flags specifies any optional flags described below: .PP .TP 14 .SM .CR T_EXPEDITED if set in .IR flags , the data will be sent as expedited data and will be subject to the interpretations of the transport provider. .TP .SM .CR T_MORE if set in .IR flags , this indicates to the transport provider that the transport service data unit, TSDU (or expedited transport service data unit - ETSDU), is being sent through multiple .CR t_snd() calls. Each \c .CR t_snd() with the T_MORE flag set indicates that another .CR t_snd() will follow with more data for the current TSDU. The end of the TSDU (or ETSDU) is identified by a .CR t_snd() call with the T_MORE flag not set. Use of T_MORE enables a user to break up large logical data units without losing the boundaries of those units at the other end of the connection. The flag implies nothing about how the data is packaged for transfer below the transport interface. If the transport provider does not support the concept of a TSDU as indicated in the .IR info argument on return from .CR t_open() or .CR t_getinfo() , the T_MORE flag is not meaningful and should be ignored. .P The sending of a zero-length fragment of a TSDU or ETSDU is only permitted where this is used to indicate the end of a TSDU or ETSDU, i.e. when the T_MORE flag is not set. Some transport providers also forbid zero-length TSDUs and ETSDUs. .PP By default, .CR t_snd() operates in synchronous mode and may wait if flow control restrictions prevent the data from being accepted by the local transport provider at the time the call is made. However, if .CR O_NONBLOCK is set (via .CR t_open() or .CR fcntl() ), .CR t_snd() will execute in asynchronous mode, and will fail immediately if there are flow control restrictions. For XTI only, the process can arrange to be informed when the flow control restrictions are cleared via .CR t_look() . .PP .CR t_snd() will wait if STREAMS internal resources are not available, even if .CR O_NONBLOCK is set. .CR O_NONBLOCK non-blocking behavior applies only to flow control conditions. .PP On successful completion, .CR t_snd() returns the number of bytes accepted by the transport provider. In synchronous mode, this will equal the number of bytes specified in .IR nbytes . However, if .CR O_NONBLOCK (asynchronous mode) is set, it is possible that only part of the data will actually be accepted by the transport provider. In this case, .CR t_snd() will set T_MORE for the data that can be accepted by the provider, and return a value that is less than the value of .IR nbytes . .PP If .IR nbytes is zero and sending of zero octets is not supported by the underlying transport service, .CR t_snd() will return -1 with .CR t_errno set to [TBADDATA]. .PP The size of each TSDU or ETSDU must not exceed the limits of the transport provider as returned in the TSDU or ETSDU fields of the .IR info argument of .CR t_open() or .CR t_getinfo() . Failure to comply will result in a protocol error. (See [TSYSERR] below.) .PP For XTI only, the error [TLOOK] may be returned to inform the process that an event (e.g., a disconnect) has occurred. .PP For TLI only, if the transport endpoint is in any state but T_DATAXFER or T_INREL, the transport provider will set .CR t_errno to [TSYSERR] and set the system .CR errno to [EPROTO]. .SS Caveats It is important to remember that the transport provider treats all users of a transport endpoint as a single user. Therefore, if several processes issue concurrent .CR t_snd() calls then the different data may be intermixed. .P Multiple sends which exceed the maximum TSDU or ETSDU size may not be discovered by XTI. In this case, an implementation-dependent error will result (generated by the transport provider) perhaps on a subsequent XTI call. This error may take the form of a connection abort, [TSYSERR], [TBADDATA], or a [TPROTO]. .P If multiple sends which exceed the maximum TSDU or ETSDU size are detected by XTI, .CR t_snd() fails with [TBADDATA]. .SH RETURN VALUE On successful completion, .CR t_snd() returns the number of bytes accepted by the transport provider. Otherwise, -1 is returned on failure and .CR t_errno is set to indicate the error. .SH ERRORS On failure, .CR t_errno is set to one of the following: .TP 17 .SM \%[TBADF] The specified identifier does not refer to a transport endpoint. .TP .SM \%[TBADDATA] Illegal amount of data: .RS 17 .P A single send was attempted specifying a TSDU (ETSDU) or fragment TSDU (ETSDU) greater than that specified by the current values of the TSDU or ETSDU fields in the info argument. .P A send of zero byte TSDU (ETSDU) or zero byte fragment of TSDU (ETSDU) is not supported by the provider. .P Multiple sends were attempted resulting in a TSDU (ETSDU) larger than that specified by the current value of the TSDU or ETSDU fields in the .IR info argument. The ability of XTI to catch such an error case is implementation-dependent. .RE .TP 17 .SM \%[TBADFLAG] An invalid flag was specified. .TP .SM \%[TFLOW] .CR O_NONBLOCK was set, but the flow control mechanism prevented the transport provider from accepting all or part of the data at this time. .TP .SM \%[TLOOK] An asynchronous event has occurred on this transport endpoint and requires immediate attention. .TP .SM \%[TNOTSUPPORT] This function is not supported by the underlying transport provider. .TP .SM \%[TOUTSTATE] The function was issued in the wrong sequence on the endpoint referenced by .IR fd . .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no other suitable XTI (\c .CR t_errno ). .SH SEE ALSO t_getinfo(3), t_open(3), t_rcv(3). .\" .SH STANDARDS CONFORMANCE .CR t_snd() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_snd\f1 \- send data or expedited data over a connection (X/OPEN TLI-XTI)@@@\f3t_snd(3)\f1 .\" index@\f1data or expedited data over a connection (X/OPEN TLI-XTI)@@@\f3t_snd(3)\f1 .\" index@\f1expedited data over a connection (X/OPEN TLI-XTI)@@@\f3t_snd(3)\f1 .\" index@\f1connection, send data (X/OPEN TLI-XTI)@@@\f3t_snd(3)\f1 .\" index@\f1XTI function, send data or expedited data over a connection@@@\f3t_snd(3)\f1 .\" index@\f1TLI function, send data or expedited data over a connection@@@\f3t_snd(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, send data or expedited data over a connection@@@\f3t_snd(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, send data or expedited data over a connection@@@\f3t_snd(3)\f1 .\" .\" toc@\f3t_snd(3)\f1:\0\0\f4t_snd()\f1@@@X/OPEN TLI-XTI - send data or expedited data over a connection .\" .\" fileset_database@t_snd.3 TLI-XTI-MAN .\" $Header: t_snddis.3,v 72.3 94/11/15 13:03:40 ssa Exp $ .TA t .TH t_snddis 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_snddis() \- send user-initiated disconnect request .SH SYNOPSIS .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_snddis (fd, call)" .CR "int fd;" .CR "struct t_call *call;" .fi .SH DESCRIPTION The .CR t_snddis() function is used to initiate an abortive release on an already established connection or to reject a connect request. .IR fd identifies the local transport endpoint of the connection, and .IR call specifies information associated with the abortive release. .IR call points to a .CR t_call structure which contains the following members: .P .nf struct netbuf addr; struct netbuf opt; struct netbuf udata; int sequence; .fi .P The type .CR netbuf structure is defined in the .CR or .CR header file. This structure, which is used to define buffer parameters, has the following members: .TP 25 .SM .CR "unsigned int maxlen" maximum byte length of the data buffer .TP .SM .CR "unsigned int len" actual byte length of data written to buffer .TP .SM .CR "char *buf" points to buffer location .PP The values in .IR call have different semantics, depending on the context of the call to .CR t_snddis() . When rejecting a connect request, .IR call must be a non-null pointer and contain a valid value of .IR sequence to uniquely identify the rejected connect indication to the transport provider. The .IR sequence parameter is only meaningful, if the transport connection is in the T_INCON state (see .IR t_getstate (3)). The .IR addr and .IR opt fields of .IR call are ignored. In all other cases, .IR call need only be used when data is being sent with the disconnect request. The .IR addr , .IR opt , and .IR sequence fields of the .CR t_call structure are ignored. If the user does not wish to send data to the remote user, the value of .IR call may be a null pointer. .PP .IR udata specifies the user data to be sent to the remote user. The amount of user data must not exceed the limits supported by the transport provider as returned in the .IR discon field of the .IR info argument of .CR t_open() or .CR t_getinfo() . If the .IR len field of .IR udata is zero, no data will be sent to the remote user. .SS Valid States T_DATAXFER, T_OUTCON, T_OUTREL, T_INREL, T_INCON (ocnt > 0) .SS Caveats .CR t_snddis() is an abortive disconnect. Therefore a .CR t_snddis() issued on a connection endpoint may cause data previously sent via .CR t_snd() or data not yet received to be lost (even if an error is returned). .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and .CR t_errno is set to indicate the error. .SH ERRORS On failure, .CR t_errno is set to one of the following: .TP 17 .SM \%[TBADF] The specified identifier does not refer to a transport endpoint. .TP .SM \%[TOUTSTATE] This function was issued in the wrong sequence on the transport endpoint referenced by .IR fd . .TP .SM \%[TBADDATA] (XTI only) The amount of user data specified was not within the bounds allowed by the transport provider. Some outbound data queued for this endpoint may be lost. .TP .SM \%[TBADSEQ] An invalid sequence was specified, or a null .IR call pointer was specified when rejecting a connect request. Some outbound data queued for this endpoint may be lost. .TP .SM \%[TLOOK] An asynchronous event has occurred on this transport endpoint and requires immediate attention. .TP .SM \%[TNOTSUPPORT] This function is not supported by the underlying transport provider. .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no other suitable XTI (\c .CR t_errno ). .SH SEE ALSO t_connect(3), t_getinfo(3), t_listen(3), t_open(3). .\" .SH STANDARDS CONFORMANCE .CR t_snddis() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_snddis\f1 \- send user-initiated disconnect request (X/OPEN TLI-XTI)@@@\f3t_sndis(3)\f1 .\" index@\f1disconnect request, send user-initiated (X/OPEN TLI-XTI)@@@\f3t_snddis(3)\f1 .\" index@\f1XTI function, send user-initiated disconnect request@@@\f3t_snddis(3)\f1 .\" index@\f1TLI function, send user-initiated disconnect request@@@\f3t_snddis(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, send user-initiated disconnect request@@@\f3t_snddis(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, send user-initiated disconnect request@@@\f3t_snddis(3)\f1 .\" .\" toc@\f3t_snddis(3)\f1:\0\0\f4t_sndis()\f1@@@X/OPEN TLI-XTI - send user-initiated disconnect request .\" .\" fileset_database@t_snddis.3 TLI-XTI-MAN .\" $Header: t_sndrel.3,v 72.3 94/11/15 13:03:42 ssa Exp $ .TA t .TH t_sndrel 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_sndrel() \- initiate an orderly release .SH SYNOPSIS .P .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_sndrel (fd)" .CR "int fd;" .fi .SH DESCRIPTION The .CR t_sndrel() function is used in connection-oriented mode to initiate an orderly release at a transport endpoint specified by .IR fd , which is a file descriptor previously returned by the .CR t_open() function. .P After this orderly release is indicated, the transport user should not try to send more data through that transport endpoint. An attempt to send more data to a released transport endpoint may block continuously. However, the transport user may continue to receive data over the connection until an orderly release indication is received. This function is an optional service of the transport provider and is only supported if the transport provider returned service type .CR T_COTS_ORD on .CR t_open() or .CR t_getinfo() . .SS Note HP OSI XTI does not support .CR t_sndrel() . .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and .CR t_errno is set to indicate the error. .SH ERRORS On failure, .CR t_errno is set to one of the following: .TP 17 .SM \%[TBADF] The specified identifier does not refer to a transport endpoint. .TP .SM \%[TFLOW] Asynchronous mode is indicated because .CR O_NONBLOCK was set, but the transport provider cannot accept a release because of flow-control restrictions. .TP .SM \%[TLOOK] An asynchronous event has occurred on this transport endpoint and requires immediate attention. .TP .SM \%[TNOTSUPPORT] This function is not supported by the underlying transport provider. .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no other suitable XTI (\c .CR t_errno ). .SH SEE ALSO t_getinfo(3), t_open(3), t_rcvrel(3). .\" .SH STANDARDS CONFORMANCE .CR t_sndrel() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_sndrel\f1 \- initiate orderly release at transport endpoint (X/OPEN TLI-XTI)@@@\f3t_sndrel(3)\f1 .\" index@\f1transport endpoint, initiate orderly release (X/OPEN TLI-XTI)@@@\f3t_sndrel(3)\f1 .\" index@\f1XTI function, initiate orderly release at transport endpoint@@@\f3t_sndrel(3)\f1 .\" index@\f1TLI function, initiate orderly release at transport endpoint@@@\f3t_sndrel(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, initiate orderly release at transport endpoint@@@\f3t_sndrel(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, initiate orderly release at transport endpoint@@@\f3t_sndrel(3)\f1 .\" .\" toc@\f3t_sndrel(3)\f1:\0\0\f4t_sndrel()\f1@@@X/OPEN TLI-XTI - initiate orderly release at transport endpoint .\" .\" fileset_database@t_sndrel.3 TLI-XTI-MAN .\" $Header: t_sndudata.3,v 72.3 94/11/15 13:03:43 ssa Exp $ .TA t .TH t_sndudata 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_sndudata() \- send a data unit .SH SYNOPSIS .PP .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI ) .P .nf .CR "int t_sndudata(fd, unitdata)" .CR "int fd;" .CR "struct t_unitdata *unitdata;" .fi .SH DESCRIPTION The .CR t_sndudata() function is used in connectionless mode to send a data unit to another transport user. The argument .IR fd identifies the local transport endpoint through which data is sent. The argument .IR unitdata points to a type .CR t_unitdata structure used to specify a data unit being sent through the transport endpoint specified by the .IR fd parameter. The .CR t_unitdata structure has the following members: .P .nf struct netbuf addr; struct netbuf opt; struct netbuf udata; .fi .P The type netbuf structure is defined in the .CR or .CR header file. This structure, which is used to define buffer parameters, has the following members: .TP 25 .SM .CR "unsigned int maxlen" maximum byte length of the data buffer .TP .SM .CR "unsigned int len" actual byte length of data written to buffer .TP .SM .CR "char *buf" points to buffer location .P In .IR unitdata , .IR addr specifies the protocol address of the destination user, .IR opt identifies protocol-specific options that the user wants associated with this request and .IR udata specifies the user data to be sent. The user may choose not to specify what protocol options are associated with the transfer by setting the .IR len field of .IR opt to zero. In this case, the provider may use default options. .PP If the .IR len field of .IR udata is zero, and sending of zero octets is not supported by the underlying transport service, the .CR t_sndudata() will return -1 with .CR t_errno set to [TBADDATA]. .PP By default, .CR t_sndudata() executes in the synchronous operating mode and may wait if flow control restrictions prevent the data from being accepted by the local transport provider at the time the call is made. However, if .CR O_NONBLOCK is set (via .CR t_open() or .CR fcntl() ), .CR t_sndudata() will execute in asynchronous mode and will fail under such conditions. The process can arrange to be notified of the clearance restriction via either .CR t_look() or the EM interface. .P If the amount of data specified in .IR udata exceeds the TSDU size as returned in the .IR tsdu field of the .IR info argument of .CR t_open() or .CR t_getinfo() , a [TBADDATA] error will be generated. If .CR t_sndudata() is called before the destination user has activated its transport endpoint, the data unit may be discarded. .P If it is not possible for the transport provider to immediately detect the conditions that cause errors [TBADADDR] and [TBADOPT], then these errors will alternatively be returned by .CR t_rcvuderr(). Therefore, an application must be prepared to receive these errors both of these ways. .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and .CR t_errno is set to indicate the error. .SH ERRORS On failure, .CR t_errno is set to one of the following: .TP 17 .SM \%[TBADDATA] Illegal amount of data. Zero octets is not supported. .TP .SM \%[TBADF] The specified file descriptor does not refer to a transport endpoint. .TP .SM \%[TFLOW] Asynchronous mode is indicated because .CR O_NONBLOCK was set, but the transport provider cannot accept the data because of flow-control restrictions. .TP .SM \%[TLOOK] (XTI only) An asynchronous event has occurred on this transport endpoint and requires immediate attention. .TP .SM \%[TNOTSUPPORT] This function is not supported by the underlying transport provider. .TP .SM \%[TOUTSTATE] (XTI only) The .CR t_sndudata() function was issued in the wrong sequence on the transport endpoint referenced by the .IR fd parameter. .TP .SM \%[TSYSERR] A system error occurred during execution of this function. A protocol error may not cause the .CR t_sndudata() function to fail until a subsequent call is made to access the transport endpoint specified by the .IR fd parameter. .TP .SM \%[TBADADDR] The specified protocol address was in an incorrect format or contained illegal information. .TP .SM \%[TBADOPT] The specified options were in an incorrect format or contained illegal information. .TP .SM \%[TPROTO] This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no other suitable XTI (\c .CR t_errno ). .SH SEE ALSO fcntl(2), t_alloc(3), t_open(3), t_rcvudata(3), t_rcvuderr(3). .\" .SH STANDARDS CONFORMANCE .CR t_sndudata() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_sndudata\f1 \- send data unit to transport user (X/OPEN TLI-XTI)@@@\f3t_sndudata(3)\f1 .\" index@\f1data unit, send to transport user (X/OPEN TLI-XTI)@@@\f3t_sndudata(3)\f1 .\" index@\f1transport user, send data unit (X/OPEN TLI-XTI)@@@\f3t_sndudata(3)\f1 .\" index@\f1error processing with t_rcvuderr(3)@@@\f3t_sndudata(3)\f1 .\" index@\f1XTI function, send data unit to transport user@@@\f3t_sndudata(3)\f1 .\" index@\f1TLI function, send data unit to transport user@@@\f3t_sndudata(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, send data unit to transport user@@@\f3t_sndudata(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, send data unit to transport user@@@\f3t_sndudata(3)\f1 .\" .\" toc@\f3t_sndudata(3)\f1:\0\0\f4t_sndudata()\f1@@@X/OPEN TLI-XTI - send data unit to transport user .\" .\" fileset_database@t_sndudata.3 TLI-XTI-MAN .\" $Header: t_strerror.3,v 72.2 94/09/18 16:24:03 ssa Exp $ .TA t .TH t_strerror 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_strerror() \- produce an error message string .SH SYNOPSIS .PP .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P .nf .CR "int *t_strerror (errnum)" .CR "int errnum;" .CR "struct info *info;" .fi .SH DESCRIPTION The .CR t_strerror() function maps the error number in .IR errnum that corresponds to an XTI error to a language-dependent error message string and returns a pointer to the string. The string pointed to will not be modified by the program, but may be overwritten by a subsequent call to the .CR t_strerror() function. The string is not terminated by a newline character. The language for error message strings written by .CR t_strerror() is implementation-defined. If it is English, the error message string describing the value in .CR t_errno is identical to the comments following the .CR t_errno defined in .CR . If an error code is unknown, and the language is English, .CR t_strerror() returns the string: .P .nf ": error unknown" .fi .P where .CR is the error number supplied as input. In other languages, an equivalent text is provided. .SS Valid Status All - apart from T_UNINIT .SH RETURN VALUE The function .CR t_strerror() returns a pointer to the generated message string. .SH SEE ALSO t_error(3). .\" .\" index@\f4t_strerror\f1 \- produce error message string (X/OPEN - XTI)@@@\f3t_strerror(3)\f1 .\" index@\f1error message, produce (X/OPEN - XTI)@@@\f3t_strerror(3)\f1 .\" index@\f1XTI function, produce error message string@@@\f3t_strerror(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, produce error message string@@@\f3t_strerror(3)\f1 .\" .\" toc@\f3t_strerror(3)\f1:\0\0\f4t_strerror()\f1@@@X/OPEN - XTI - produce error message string .\" .\" fileset_database@t_strerror.3 -XTI-MAN .\" $Header: t_sync.3,v 72.3 94/11/15 13:03:45 ssa Exp $ .TA t .TH t_sync 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_sync() \- synchronize transport library .SH SYNOPSIS .PP .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_sync (fd)" .CR "int fd;" .fi .SH DESCRIPTION .PP For the transport endpoint specified by .IR fd , the .CR t_sync() function synchronizes the data structures managed by the transport library with information from the underlying transport provider. In doing so, it can convert an uninitialized file descriptor (obtained via .CR open() , .CR dup() or as a result of a .CR fork() and .CR exec() ) to an initialized endpoint, assuming that the file descriptor referenced a transport endpoint, by updating and allocating the necessary library data structures. This function also allows two cooperating processes to synchronize their interaction with a transport provider. .P For example, if a process forks a new process and issues an .CR exec() , the new process must issue a .CR t_sync() to build the private library data structure associated with a transport endpoint and to synchronize the data structure with the relevant provider information. .P It is important to remember that the transport provider treats all users of a transport endpoint as a single user. If multiple processes are using the same endpoint, they should coordinate their activities so as not to violate the state of the transport endpoint. The function .CR t_sync() returns the current state of the transport endpoint to the user, thereby enabling the user to verify the state before taking further action. This coordination is only valid among cooperating processes; it is possible that a process or an incoming event could change the endpoint's state after a .CR t_sync() is issued. .P If the transport endpoint is undergoing a state transition when .CR t_sync() is called, the function will fail. .SS Valid States All - apart from T_UNINIT .SH "RETURN VALUE" .CR t_sync returns the state of the transport connection endpoint on successful completion and -1 on failure, and .CR t_errno is set to indicate the error. The state returned is one of the following: .PP .TP 15 .SM .CR T_UNBND Unbound .TP .SM .CR T_IDLE Idle .TP .SM .CR T_OUTCON Outgoing connection pending .TP .SM .CR T_INCON Incoming connection pending .TP .SM .CR T_DATAXFER Data transfer .TP .SM .CR T_OUTREL Outgoing orderly release (waiting for an orderly release indication) .TP .SM .CR T_INREL Incoming orderly release (waiting for an orderly release request) .SH ERRORS .PP On failure, .CR t_errno is set to one of the following: .TP 17 .SM \%[TBADF] The specified file descriptor does not refer to a transport endpoint. This error may be returned when the .IR fd has been previously closed or an erroneous number may have been passed to the call. .TP .SM \%[TSTATECHNG] The transport endpoint is undergoing a state change. .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .TP .SM \%[TPROTO] (XTI only) This error indicates that a communication problem has been detected between XTI and the transport provider for which there is no other suitable XTI (\c .CR t_errno ). .SH SEE ALSO .PP t_open(3), t_getstate(3), dup(2), exec(2), fork(2), open(2). .\" .SH STANDARDS CONFORMANCE .CR t_sync() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_sync\f1 \- synchronize transport library for transport endpoint (X/OPEN TLI-XTI)@@@\f3t_sync(3)\f1 .\" index@\f1synchronize transport library for transport endpoint (X/OPEN TLI-XTI)@@@\f3t_sync(3)\f1 .\" index@\f1transport library, synchronize (X/OPEN TLI-XTI)@@@\f3t_sync(3)\f1 .\" index@\f1transport endpoint, synchronize transport library (X/OPEN TLI-XTI)@@@\f3t_sync(3)\f1 .\" index@\f1XTI function, synchronize transport library for transport endpoint@@@\f3t_sync(3)\f1 .\" index@\f1TLI function, synchronize transport library for transport endpoint@@@\f3t_sync(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, synchronize transport library for transport endpoint@@@\f3t_sync(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, synchronize transport library for transport endpoint@@@\f3t_sync(3)\f1 .\" .\" toc@\f3t_sync(3)\f1:\0\0\f4t_sync()\f1@@@X/OPEN TLI-XTI - synchronize transport library for transport endpoint .\" .\" fileset_database@t_sync.3 TLI-XTI-MAN .\" $Header: t_unbind.3,v 72.3 94/11/15 13:03:46 ssa Exp $" .TA t .TH t_unbind 3 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME t_unbind() \- disable a transport endpoint .SH SYNOPSIS .PP .TP 30 .CR "#include " (for X/OPEN Transport Interface - XTI) .P or .P .TP 30 .CR "#include " (for Transport Layer Interface - TLI) .P .nf .CR "int t_unbind (fd)" .CR "int fd;" .fi .SH DESCRIPTION The .CR t_unbind() function disables the transport endpoint specified by .IR fd which was previously bound by .CR t_bind() . On completion of this call, no further data or events destined for this transport endpoint will be accepted by the transport provider. .SS Note Users can access XTI versions of the .CR t_* routines by linking with .CR /usr/lib/libxti.a . For more information on XTI, see .IR "HP-UX/9000 XTI Programmer's Guide" . .P TLI supports any transport provider which is compliant with TPI (Transport Provider Interface). Users can access TLI versions of the t_* routines by linking with .CR /usr/lib/libnsl_s.a . For more information on TLI, see the TLI section of the .IR "STREAMS/UX for HP 9000 Reference Manual" . .SS Valid States T_IDLE .SH RETURN VALUE Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and .CR t_errno is set to indicate an error. .SH ERRORS On failure, .CR t_errno is set to the following: .TP 17 .SM \%[TBADF] The specified identifier does not refer to a transport endpoint. .TP .SM \%[TOUTSTATE] The function was issued in the wrong sequence. .TP .SM \%[TLOOK] An asynchronous event has occurred on this transport endpoint. .TP .SM \%[TSYSERR] A system error has occurred during execution of this function. .SH SEE ALSO t_bind(3). .\" .SH STANDARDS CONFORMANCE .CR t_unbind() ": SVID2, XPG3, XPG4" .\" .\" index@\f4t_unbind\f1 \- disable transport endpoint (X/OPEN TLI-XTI)@@@\f3t_unbind(3)\f1 .\" index@\f1transport endpoint, disable (X/OPEN TLI-XTI)@@@\f3t_unbind(3)\f1 .\" index@\f1XTI function, disable transport endpoint@@@\f3t_unbind(3)\f1 .\" index@\f1TLI function, disable transport endpoint@@@\f3t_unbind(3)\f1 .\" index@\f1X/OPEN Transport Interface - XTI, disable transport endpoint@@@\f3t_unbind(3)\f1 .\" index@\f1X/OPEN Transport Layer Interface - TLI, disable transport endpoint@@@\f3t_unbind(3)\f1 .\" .\" toc@\f3t_unbind(3)\f1:\0\0\f4t_unbind()\f1@@@X/OPEN TLI-XTI - disable transport endpoint .\" .\" fileset_database@t_unbind.3 TLI-XTI-MAN .\" $Header: tan.3m,v 78.1 96/02/13 13:52:47 ssa Exp $ .TA t .TH tan 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tan(\|), tanf(\|) \- tangent functions .SH SYNOPSIS .C "#include " .PP .C "double tan(double x);" .PP .C "float tanf(float x);" .SH DESCRIPTION .CR tan() returns the tangent of .IR x .RI ( x specified in radians). .PP .CR tan() may lose accuracy when .IR x is far from zero. .PP .CR tanf() is a .CR float version of .CR tan() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR tanf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .IR x .ift is NaN or \(+-INFINITY, .ifn is NaN or +\-INFINITY, .CR tan() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR tan() returns zero. .PP If the correct value would overflow, .CR tan() returns .ift .CR \(+-HUGE_VAL .ifn .CR +\-HUGE_VAL and sets .CR errno to [ERANGE]. .SH ERRORS If .CR tan() fails, .CR errno is set to the following value. .RS .TP 20 [ERANGE] The correct value would overflow. .RE .SH DEPENDENCIES Millicode versions of the .CR tan() and .CR tanf() functions are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO tand(3M), sin(3M), cos(3M), asin(3M), acos(3M), atan(3M), atan2(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR tan() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4tan()\f1 \- tangent function@@@\f3tan(3M)\f1 .\" index@\f4tanf()\f1 \- tangent function (float)@@@\f3tan(3M)\f1 .\" index@\f1tangent function@@@\f3tan(3M)\f1 .\" index@\f1math: tangent functions@@@\f3tan(3M)\f1 .\" index@\f1trigonometric tangent functions@@@\f3tan(3M)\f1 .\" .\" toc@\f3tan(3M)\f1:\0\0\f4tan()\f1, \f4tanf()\f1@@@tangent functions .\" toc@\f4tanf()\f1:\0\0tangent function (float)@@@see \f3tan(3M)\f1 .\" .\" links@tan.3m tanf.3m .\" .\" fileset_database@tan.3m PROGRAMING-MAN .\" $Header: tand.3m,v 78.1 96/02/13 13:55:34 ssa Exp $ .TA t .TH tand 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tand(\|), tandf(\|) \- degree-valued tangent functions .SH SYNOPSIS .C "#include " .PP .C "double tand(double x);" .PP .C "float tandf(float x);" .SH DESCRIPTION .CR tand() is a degree-valued version of the .CR tan() function. It returns the tangent of .IR x .RI ( x specified in degrees). .PP .CR tand() may lose accuracy when .IR x is far from zero. .PP .CR tandf() is a .CR float version of .CR tand() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR tand() and .CR tandf() are not specified by any standard, but .CR tandf() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .IR x .ift is NaN or \(+-INFINITY, .ifn is NaN or +\-INFINITY, .CR tand() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR tand() returns zero. .PP If the correct value would overflow, .CR tand() returns .ift .CR \(+-HUGE_VAL .ifn .CR +\-HUGE_VAL and sets .CR errno to [ERANGE]. .SH ERRORS If .CR tand() fails, .CR errno is set to the following value. .RS .TP 20 [ERANGE] The correct value would overflow. .RE .SH SEE ALSO tan(3M), sind(3M), cosd(3M), asind(3M), acosd(3M), atand(3M), atan2d(3M), isinf(3M), isnan(3M), values(5). .\" .\" index@\f4tand()\f1 \- tangent function (degrees)@@@\f3tand(3M)\f1 .\" index@\f4tandf()\f1 \- tangent function (float, degrees)@@@\f3tand(3M)\f1 .\" index@\f1tangent function (degrees)@@@\f3tand(3M)\f1 .\" index@\f1math: tangent functions (degrees)@@@\f3tand(3M)\f1 .\" index@\f1degree-valued tangent functions@@@\f3tand(3M)\f1 .\" index@\f1trigonometric tangent functions (degrees)@@@\f3tand(3M)\f1 .\" .\" toc@\f3tand(3M)\f1:\0\0\f4tand()\f1, \f4tandf()\fP@@@degree-valued tangent functions .\" toc@\f4tandf()\f1:\0\0tangent function (float, degrees)@@@see \f3tand(3M)\f1 .\" .\" links@tand.3m tandf.3m .\" .\" fileset_database@tand.3m PROGRAMING-MAN .\" $Header: tand.3m,v 78.1 96/02/13 13:55:34 ssa Exp $ .TA t .TH tand 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tand(\|), tandf(\|) \- degree-valued tangent functions .SH SYNOPSIS .C "#include " .PP .C "double tand(double x);" .PP .C "float tandf(float x);" .SH DESCRIPTION .CR tand() is a degree-valued version of the .CR tan() function. It returns the tangent of .IR x .RI ( x specified in degrees). .PP .CR tand() may lose accuracy when .IR x is far from zero. .PP .CR tandf() is a .CR float version of .CR tand() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR tand() and .CR tandf() are not specified by any standard, but .CR tandf() is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .IR x .ift is NaN or \(+-INFINITY, .ifn is NaN or +\-INFINITY, .CR tand() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR tand() returns zero. .PP If the correct value would overflow, .CR tand() returns .ift .CR \(+-HUGE_VAL .ifn .CR +\-HUGE_VAL and sets .CR errno to [ERANGE]. .SH ERRORS If .CR tand() fails, .CR errno is set to the following value. .RS .TP 20 [ERANGE] The correct value would overflow. .RE .SH SEE ALSO tan(3M), sind(3M), cosd(3M), asind(3M), acosd(3M), atand(3M), atan2d(3M), isinf(3M), isnan(3M), values(5). .\" .\" index@\f4tand()\f1 \- tangent function (degrees)@@@\f3tand(3M)\f1 .\" index@\f4tandf()\f1 \- tangent function (float, degrees)@@@\f3tand(3M)\f1 .\" index@\f1tangent function (degrees)@@@\f3tand(3M)\f1 .\" index@\f1math: tangent functions (degrees)@@@\f3tand(3M)\f1 .\" index@\f1degree-valued tangent functions@@@\f3tand(3M)\f1 .\" index@\f1trigonometric tangent functions (degrees)@@@\f3tand(3M)\f1 .\" .\" toc@\f3tand(3M)\f1:\0\0\f4tand()\f1, \f4tandf()\fP@@@degree-valued tangent functions .\" toc@\f4tandf()\f1:\0\0tangent function (float, degrees)@@@see \f3tand(3M)\f1 .\" .\" links@tand.3m tandf.3m .\" .\" fileset_database@tand.3m PROGRAMING-MAN .\" $Header: tan.3m,v 78.1 96/02/13 13:52:47 ssa Exp $ .TA t .TH tan 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tan(\|), tanf(\|) \- tangent functions .SH SYNOPSIS .C "#include " .PP .C "double tan(double x);" .PP .C "float tanf(float x);" .SH DESCRIPTION .CR tan() returns the tangent of .IR x .RI ( x specified in radians). .PP .CR tan() may lose accuracy when .IR x is far from zero. .PP .CR tanf() is a .CR float version of .CR tan() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR tanf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .IR x .ift is NaN or \(+-INFINITY, .ifn is NaN or +\-INFINITY, .CR tan() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR tan() returns zero. .PP If the correct value would overflow, .CR tan() returns .ift .CR \(+-HUGE_VAL .ifn .CR +\-HUGE_VAL and sets .CR errno to [ERANGE]. .SH ERRORS If .CR tan() fails, .CR errno is set to the following value. .RS .TP 20 [ERANGE] The correct value would overflow. .RE .SH DEPENDENCIES Millicode versions of the .CR tan() and .CR tanf() functions are available on PA1.1-based and PA2.0-based systems, in the library .CR /usr/lib/milli.a . Millicode versions of math library functions are usually faster than their counterparts in the standard library. To use these versions, compile your program with the .CR +DA1.1 option (the default on PA1.1-based systems) or the .CR +DA2.0 option (the default on PA2.0-based systems) and with the .CR +Olibcalls or the .CR +Oaggressive optimization option. .PP If an error occurs, the millicode versions return the value described in the RETURN VALUE section, but do not set .CR errno . .PP For more information, see the .IR "HP-UX Floating-Point Guide" . .SH SEE ALSO tand(3M), sin(3M), cos(3M), asin(3M), acos(3M), atan(3M), atan2(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR tan() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4tan()\f1 \- tangent function@@@\f3tan(3M)\f1 .\" index@\f4tanf()\f1 \- tangent function (float)@@@\f3tan(3M)\f1 .\" index@\f1tangent function@@@\f3tan(3M)\f1 .\" index@\f1math: tangent functions@@@\f3tan(3M)\f1 .\" index@\f1trigonometric tangent functions@@@\f3tan(3M)\f1 .\" .\" toc@\f3tan(3M)\f1:\0\0\f4tan()\f1, \f4tanf()\f1@@@tangent functions .\" toc@\f4tanf()\f1:\0\0tangent function (float)@@@see \f3tan(3M)\f1 .\" .\" links@tan.3m tanf.3m .\" .\" fileset_database@tan.3m PROGRAMING-MAN .\" $Header: tanh.3m,v 78.1 96/02/13 13:55:53 ssa Exp $ .TA t .TH tanh 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tanh(\|), tanhf(\|) \- hyperbolic tangent functions .SH SYNOPSIS .C "#include " .PP .C "double tanh(double x);" .PP .C "float tanhf(float x);" .SH DESCRIPTION The .CR tanh() function returns the hyperbolic tangent of its argument. .PP .CR tanhf() is a .CR float version of .CR tanh() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR tanhf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .IR x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR tanh() .ift returns \(+-1.0 respectively. .ifn returns +\-1.0 respectively. .PP If .IR x is NaN, .CR tanh() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR tanh() returns zero. .SH ERRORS No errors are defined. .SH SEE ALSO sinh(3M), cosh(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR tanh() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4tanh()\f1, \f4tanhf()\f1 \- hyperbolic tangent functions@@@\f3tanh(3M)\f1 .\" index@\f4tanhf()\f1, \f4tanh()\fP \- hyperbolic tangent functions@@@\f3tanh(3M)\f1 .\" index@\f1math: hyperbolic tangent functions@@@\f3tanh(3M)\f1 .\" index@\f1hyperbolic tangent functions@@@\f3tanh(3M)\f1 .\" index@\f1tangent functions, hyperbolic@@@\f3tanh(3M)\f1 .\" .\" toc@\f4tanh(3M)\f1:\0\0\f4tanh()\f1, \f4tanhf()\f1@@@hyperbolic tangent functions .\" toc@\f4tanhf()\f1:\0\0hyperbolic tangent function (float version)@@@see \f3tanh(3M)\f1 .\" .\" links@tanh.3m tanhf.3m .\" .\" fileset_database@tanh.3m PROGRAMING-MAN .\" $Header: tanh.3m,v 78.1 96/02/13 13:55:53 ssa Exp $ .TA t .TH tanh 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tanh(\|), tanhf(\|) \- hyperbolic tangent functions .SH SYNOPSIS .C "#include " .PP .C "double tanh(double x);" .PP .C "float tanhf(float x);" .SH DESCRIPTION The .CR tanh() function returns the hyperbolic tangent of its argument. .PP .CR tanhf() is a .CR float version of .CR tanh() ; it takes a .CR float argument and returns a .CR float result. To use this function, compile either with the .CR \-Ae option or with the .CR \-Aa and .CR \-D_HPUX_SOURCE options. Otherwise, the compiler promotes the .CR float argument to .CR double , and the function returns incorrect results. .PP .CR tanhf() is not specified by any standard, but it is named in accordance with the conventions specified in the "Future Library Directions" section of the ANSI C standard. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE If .IR x .ift is \(+-INFINITY, .ifn is +\-INFINITY, .CR tanh() .ift returns \(+-1.0 respectively. .ifn returns +\-1.0 respectively. .PP If .IR x is NaN, .CR tanh() returns NaN. .PP If the correct value after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR tanh() returns zero. .SH ERRORS No errors are defined. .SH SEE ALSO sinh(3M), cosh(3M), isinf(3M), isnan(3M), values(5). .SH STANDARDS CONFORMANCE .CR tanh() ": SVID3, XPG4.2, ANSI C" .\" .\" index@\f4tanh()\f1, \f4tanhf()\f1 \- hyperbolic tangent functions@@@\f3tanh(3M)\f1 .\" index@\f4tanhf()\f1, \f4tanh()\fP \- hyperbolic tangent functions@@@\f3tanh(3M)\f1 .\" index@\f1math: hyperbolic tangent functions@@@\f3tanh(3M)\f1 .\" index@\f1hyperbolic tangent functions@@@\f3tanh(3M)\f1 .\" index@\f1tangent functions, hyperbolic@@@\f3tanh(3M)\f1 .\" .\" toc@\f4tanh(3M)\f1:\0\0\f4tanh()\f1, \f4tanhf()\f1@@@hyperbolic tangent functions .\" toc@\f4tanhf()\f1:\0\0hyperbolic tangent function (float version)@@@see \f3tanh(3M)\f1 .\" .\" links@tanh.3m tanhf.3m .\" .\" fileset_database@tanh.3m PROGRAMING-MAN .\" $Header: tcattribute.3c,v 72.5 94/11/15 09:56:36 ssa Exp $ .TA t .TH tcattribute 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tcgetattr(\|), tcsetattr(\|) \- control tty device .SH SYNOPSIS .C "#include " .PP .C "int tcgetattr(int fildes, struct termios *termios_p);" .PP .C "int tcsetattr(" .nf .PD 0 .IP .C "int fildes," .C "int optional_actions," .C "const struct termios *termios_p" .PP .C ");" .PD .fi .SH DESCRIPTION .C tcgetattr() gets the parameters associated with .I fildes and stores them in the .I termios structure referenced by .IR termios_p . If the terminal device does not support split baud rates, the input baud rate stored in the .I termios structure is zero. This function is allowed from a background process (see .IR termio (7)). However, the terminal attributes can be subsequently changed by a foreground process. .PP .C tcsetattr() sets the parameters associated with .I fildes (unless support is required from underlying hardware that is not available) from the .I termios structure referenced by .I termios_p as follows: .RS .TP 3 \(bu If .I optional_actions is .CR TCSANOW , the change is immediate. .TP \(bu If .I optional_actions is .CR TCSADRAIN , the change occurs after all output written to .I fildes is transmitted. .TP \(bu If .I optional_actions is .CR TCSAFLUSH , the change occurs after all output written to .I fildes is transmitted, and all input that has been received but not read is discarded. .RE .SH RETURN VALUE Upon successful completion, a value of zero is returned. Otherwise, a value of \-1 is returned and .C errno is set to indicate the error. .SH ERRORS .C tcgetattr() and .C tcsetattr() fail if any of the following conditions are encountered: .TP 15 .SM [EBADF] .I fildes is not a valid file descriptor. .TP .SM [EINVAL] The .I optional_actions argument is not a proper value or no part of a .C tcsetattr() request could be performed. .TP .SM [ENOTTY] The file associated with .I fildes is not a terminal. .SH WARNINGS .C tcsetattr() will attempt to perform as much of the request as possible. However, the hardware being used may not support all possible c_cflag values. If any part of the request can be performed, those values will be set, any values not supported by the hardware will be ignored, and .C tcsetattr() will complete successfully. If no part of the request can be performed, .C tcsetattr() will fail and set .C errno to .SM [EINVAL]. For any hardware that does not support separate input and output baud rates, an attempt to set different input and output baud rates does not affect either baud rate. .C tcgetattr() always returns the actual values set in hardware. For any hardware that does not support separate input and output baud rates, .C tcgetattr() returns zero for the input baud rate. .SH SEE ALSO cfspeed(3C), tccontrol(3C), termio(7). .SH STANDARDS CONFORMANCE .CR tcgetattr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcsetattr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4tcgetattr()\fP: get tty device operating parameters@@@\f3tcattribute(3C)\f1 .\" index@\f4tcsetattr()\fP: set tty device operating parameters@@@\f3tcattribute(3C)\f1 .\" index@get tty device operating parameters@@@\f3tcattribute(3C)\f1 .\" index@set tty device operating parameters@@@\f3tcattribute(3C)\f1 .\" index@tty device operating parameters, get or set@@@\f3tcattribute(3C)\f1 .\" index@control tty device@@@\f3tcattribute(3C)\f1 .\" .\" toc@\f3tcattribute(3C)\f1:\0\0\f4tcgetattr()\fP, \f4tcsetattr()\fP@@@control tty device .\" toc \f4tcgetattr()\fP: get tty device attributes see \f3tcattribute(3C)\f1 .\" toc \f4tcsetattr()\fP: set tty device attributes see \f3tcattribute(3C)\f1 .\" .\" links@tcattribute.3c tcgetattr.3c .\" links@tcattribute.3c tcsetattr.3c .\" .\" fileset_database@tcattribute.3c PROGRAMING-MAN .\" $Header: tccontrol.3c,v 72.5 94/11/15 09:56:37 ssa Exp $ .TA t .TH tccontrol 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tcsendbreak(\|), tcdrain(\|), tcflush(\|), tcflow(\|) \- tty line control functions .SH SYNOPSIS .C "#include " .P .C "int tcsendbreak(int fildes, int duration);" .P .C "int tcdrain(int fildes);" .P .C "int tcflush(int fildes, int queue_selector);" .P .C "int tcflow(int fildes, int action);" .SH DESCRIPTION If the terminal is using asynchronous serial data transmission, .C tcsendbreak() causes transmission of a continuous stream of zero-valued bits for a specific duration. If .I duration is zero, it causes transmission of zero-valued bits for at least 0.25 seconds, but not more than 0.5 seconds. If .I duration is not zero, zero-valued bits are not transmitted. For all .SM HP-UX implementations, .I duration is ignored. .PP .C tcdrain() waits until all output written to .I fildes has been transmitted. .PP .C tcflush() discards data written to .I fildes but not transmitted, or data received but not read, depending on the value of .IR queue_selector : .RS .TP 3 \(bu If .I queue_selector is .CR TCIFLUSH , data received but not read is flushed. .TP \(bu If .I queue_selector is .CR TCOFLUSH , data written but not transmitted is flushed. .TP \(bu If .I queue_selector is .CR TCIOFLUSH , both data received but not read, and data written but not transmitted is flushed. .RE .PP .C tcflow() suspends transmission of data to .I fildes or reception of data from .I fildes , depending on the value of .IR action : .RS .TP 3 \(bu If .I action is .CR TCOOFF , output is suspended. .TP \(bu If .I action is .CR TCOON , suspended output is restarted. .TP \(bu If .I action is .CR TCIOFF , a .SM STOP character is transmitted which is intended to cause the terminal to stop transmitting data to the system. .TP \(bu If .I action is .CR TCION , a .SM START character is transmitted which is intended to cause the terminal to start transmitting data to the system. .RE .SH RETURN VALUE Upon successful completion, a value of zero is returned. Otherwise, a value of \-1 is returned and .C errno is set to indicate the error. .SH ERRORS These functions fail if one or more of the following is true: .RS .TP 15 .SM [EBADF] .I fildes is not a valid file descriptor. .TP .SM [EINTR] A signal was received during .CR tcdrain() . .TP .SM [EINVAL] The .I queue_selector or the .I action argument is not a proper value. .TP .SM [ENOTTY] The file associated with .I fildes is not a terminal. .RE .SH SEE ALSO tcattribute(3C), tccontrol(3C), termio(7). .SH STANDARDS CONFORMANCE .CR tcdrain() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcflow() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcflush() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcsendbreak() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4tcsendbreak()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcdrain()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcflush()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcflow()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@tty line control functions@@@\f3tccontrol(3C)\f1 .\" index@line control functions, tty@@@\f3tccontrol(3C)\f1 .\" index@control functions, tty line@@@\f3tccontrol(3C)\f1 .\" .\" toc@\f3tccontrol(3C)\f1:\0\0\f4tcsendbreak()\fP, \f4tcdrain()\fP, \f4tcflush()\fP, \f4tcflow()\fP@@@tty line control functions .\" toc@\f4tcsendbreak()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcdrain()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcflush()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcflow()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" .\" links@tccontrol.3c tcsendbreak.3c .\" links@tccontrol.3c tcdrain.3c .\" links@tccontrol.3c tcflush.3c .\" links@tccontrol.3c tcflow.3c .\" .\" fileset_database@tccontrol.3c PROGRAMING-MAN .\" $Header: tccontrol.3c,v 72.5 94/11/15 09:56:37 ssa Exp $ .TA t .TH tccontrol 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tcsendbreak(\|), tcdrain(\|), tcflush(\|), tcflow(\|) \- tty line control functions .SH SYNOPSIS .C "#include " .P .C "int tcsendbreak(int fildes, int duration);" .P .C "int tcdrain(int fildes);" .P .C "int tcflush(int fildes, int queue_selector);" .P .C "int tcflow(int fildes, int action);" .SH DESCRIPTION If the terminal is using asynchronous serial data transmission, .C tcsendbreak() causes transmission of a continuous stream of zero-valued bits for a specific duration. If .I duration is zero, it causes transmission of zero-valued bits for at least 0.25 seconds, but not more than 0.5 seconds. If .I duration is not zero, zero-valued bits are not transmitted. For all .SM HP-UX implementations, .I duration is ignored. .PP .C tcdrain() waits until all output written to .I fildes has been transmitted. .PP .C tcflush() discards data written to .I fildes but not transmitted, or data received but not read, depending on the value of .IR queue_selector : .RS .TP 3 \(bu If .I queue_selector is .CR TCIFLUSH , data received but not read is flushed. .TP \(bu If .I queue_selector is .CR TCOFLUSH , data written but not transmitted is flushed. .TP \(bu If .I queue_selector is .CR TCIOFLUSH , both data received but not read, and data written but not transmitted is flushed. .RE .PP .C tcflow() suspends transmission of data to .I fildes or reception of data from .I fildes , depending on the value of .IR action : .RS .TP 3 \(bu If .I action is .CR TCOOFF , output is suspended. .TP \(bu If .I action is .CR TCOON , suspended output is restarted. .TP \(bu If .I action is .CR TCIOFF , a .SM STOP character is transmitted which is intended to cause the terminal to stop transmitting data to the system. .TP \(bu If .I action is .CR TCION , a .SM START character is transmitted which is intended to cause the terminal to start transmitting data to the system. .RE .SH RETURN VALUE Upon successful completion, a value of zero is returned. Otherwise, a value of \-1 is returned and .C errno is set to indicate the error. .SH ERRORS These functions fail if one or more of the following is true: .RS .TP 15 .SM [EBADF] .I fildes is not a valid file descriptor. .TP .SM [EINTR] A signal was received during .CR tcdrain() . .TP .SM [EINVAL] The .I queue_selector or the .I action argument is not a proper value. .TP .SM [ENOTTY] The file associated with .I fildes is not a terminal. .RE .SH SEE ALSO tcattribute(3C), tccontrol(3C), termio(7). .SH STANDARDS CONFORMANCE .CR tcdrain() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcflow() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcflush() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcsendbreak() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4tcsendbreak()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcdrain()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcflush()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcflow()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@tty line control functions@@@\f3tccontrol(3C)\f1 .\" index@line control functions, tty@@@\f3tccontrol(3C)\f1 .\" index@control functions, tty line@@@\f3tccontrol(3C)\f1 .\" .\" toc@\f3tccontrol(3C)\f1:\0\0\f4tcsendbreak()\fP, \f4tcdrain()\fP, \f4tcflush()\fP, \f4tcflow()\fP@@@tty line control functions .\" toc@\f4tcsendbreak()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcdrain()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcflush()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcflow()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" .\" links@tccontrol.3c tcsendbreak.3c .\" links@tccontrol.3c tcdrain.3c .\" links@tccontrol.3c tcflush.3c .\" links@tccontrol.3c tcflow.3c .\" .\" fileset_database@tccontrol.3c PROGRAMING-MAN .\" $Header: tccontrol.3c,v 72.5 94/11/15 09:56:37 ssa Exp $ .TA t .TH tccontrol 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tcsendbreak(\|), tcdrain(\|), tcflush(\|), tcflow(\|) \- tty line control functions .SH SYNOPSIS .C "#include " .P .C "int tcsendbreak(int fildes, int duration);" .P .C "int tcdrain(int fildes);" .P .C "int tcflush(int fildes, int queue_selector);" .P .C "int tcflow(int fildes, int action);" .SH DESCRIPTION If the terminal is using asynchronous serial data transmission, .C tcsendbreak() causes transmission of a continuous stream of zero-valued bits for a specific duration. If .I duration is zero, it causes transmission of zero-valued bits for at least 0.25 seconds, but not more than 0.5 seconds. If .I duration is not zero, zero-valued bits are not transmitted. For all .SM HP-UX implementations, .I duration is ignored. .PP .C tcdrain() waits until all output written to .I fildes has been transmitted. .PP .C tcflush() discards data written to .I fildes but not transmitted, or data received but not read, depending on the value of .IR queue_selector : .RS .TP 3 \(bu If .I queue_selector is .CR TCIFLUSH , data received but not read is flushed. .TP \(bu If .I queue_selector is .CR TCOFLUSH , data written but not transmitted is flushed. .TP \(bu If .I queue_selector is .CR TCIOFLUSH , both data received but not read, and data written but not transmitted is flushed. .RE .PP .C tcflow() suspends transmission of data to .I fildes or reception of data from .I fildes , depending on the value of .IR action : .RS .TP 3 \(bu If .I action is .CR TCOOFF , output is suspended. .TP \(bu If .I action is .CR TCOON , suspended output is restarted. .TP \(bu If .I action is .CR TCIOFF , a .SM STOP character is transmitted which is intended to cause the terminal to stop transmitting data to the system. .TP \(bu If .I action is .CR TCION , a .SM START character is transmitted which is intended to cause the terminal to start transmitting data to the system. .RE .SH RETURN VALUE Upon successful completion, a value of zero is returned. Otherwise, a value of \-1 is returned and .C errno is set to indicate the error. .SH ERRORS These functions fail if one or more of the following is true: .RS .TP 15 .SM [EBADF] .I fildes is not a valid file descriptor. .TP .SM [EINTR] A signal was received during .CR tcdrain() . .TP .SM [EINVAL] The .I queue_selector or the .I action argument is not a proper value. .TP .SM [ENOTTY] The file associated with .I fildes is not a terminal. .RE .SH SEE ALSO tcattribute(3C), tccontrol(3C), termio(7). .SH STANDARDS CONFORMANCE .CR tcdrain() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcflow() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcflush() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcsendbreak() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4tcsendbreak()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcdrain()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcflush()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcflow()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@tty line control functions@@@\f3tccontrol(3C)\f1 .\" index@line control functions, tty@@@\f3tccontrol(3C)\f1 .\" index@control functions, tty line@@@\f3tccontrol(3C)\f1 .\" .\" toc@\f3tccontrol(3C)\f1:\0\0\f4tcsendbreak()\fP, \f4tcdrain()\fP, \f4tcflush()\fP, \f4tcflow()\fP@@@tty line control functions .\" toc@\f4tcsendbreak()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcdrain()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcflush()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcflow()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" .\" links@tccontrol.3c tcsendbreak.3c .\" links@tccontrol.3c tcdrain.3c .\" links@tccontrol.3c tcflush.3c .\" links@tccontrol.3c tcflow.3c .\" .\" fileset_database@tccontrol.3c PROGRAMING-MAN .\" $Header: tccontrol.3c,v 72.5 94/11/15 09:56:37 ssa Exp $ .TA t .TH tccontrol 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tcsendbreak(\|), tcdrain(\|), tcflush(\|), tcflow(\|) \- tty line control functions .SH SYNOPSIS .C "#include " .P .C "int tcsendbreak(int fildes, int duration);" .P .C "int tcdrain(int fildes);" .P .C "int tcflush(int fildes, int queue_selector);" .P .C "int tcflow(int fildes, int action);" .SH DESCRIPTION If the terminal is using asynchronous serial data transmission, .C tcsendbreak() causes transmission of a continuous stream of zero-valued bits for a specific duration. If .I duration is zero, it causes transmission of zero-valued bits for at least 0.25 seconds, but not more than 0.5 seconds. If .I duration is not zero, zero-valued bits are not transmitted. For all .SM HP-UX implementations, .I duration is ignored. .PP .C tcdrain() waits until all output written to .I fildes has been transmitted. .PP .C tcflush() discards data written to .I fildes but not transmitted, or data received but not read, depending on the value of .IR queue_selector : .RS .TP 3 \(bu If .I queue_selector is .CR TCIFLUSH , data received but not read is flushed. .TP \(bu If .I queue_selector is .CR TCOFLUSH , data written but not transmitted is flushed. .TP \(bu If .I queue_selector is .CR TCIOFLUSH , both data received but not read, and data written but not transmitted is flushed. .RE .PP .C tcflow() suspends transmission of data to .I fildes or reception of data from .I fildes , depending on the value of .IR action : .RS .TP 3 \(bu If .I action is .CR TCOOFF , output is suspended. .TP \(bu If .I action is .CR TCOON , suspended output is restarted. .TP \(bu If .I action is .CR TCIOFF , a .SM STOP character is transmitted which is intended to cause the terminal to stop transmitting data to the system. .TP \(bu If .I action is .CR TCION , a .SM START character is transmitted which is intended to cause the terminal to start transmitting data to the system. .RE .SH RETURN VALUE Upon successful completion, a value of zero is returned. Otherwise, a value of \-1 is returned and .C errno is set to indicate the error. .SH ERRORS These functions fail if one or more of the following is true: .RS .TP 15 .SM [EBADF] .I fildes is not a valid file descriptor. .TP .SM [EINTR] A signal was received during .CR tcdrain() . .TP .SM [EINVAL] The .I queue_selector or the .I action argument is not a proper value. .TP .SM [ENOTTY] The file associated with .I fildes is not a terminal. .RE .SH SEE ALSO tcattribute(3C), tccontrol(3C), termio(7). .SH STANDARDS CONFORMANCE .CR tcdrain() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcflow() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcflush() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcsendbreak() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4tcsendbreak()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcdrain()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcflush()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcflow()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@tty line control functions@@@\f3tccontrol(3C)\f1 .\" index@line control functions, tty@@@\f3tccontrol(3C)\f1 .\" index@control functions, tty line@@@\f3tccontrol(3C)\f1 .\" .\" toc@\f3tccontrol(3C)\f1:\0\0\f4tcsendbreak()\fP, \f4tcdrain()\fP, \f4tcflush()\fP, \f4tcflow()\fP@@@tty line control functions .\" toc@\f4tcsendbreak()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcdrain()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcflush()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcflow()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" .\" links@tccontrol.3c tcsendbreak.3c .\" links@tccontrol.3c tcdrain.3c .\" links@tccontrol.3c tcflush.3c .\" links@tccontrol.3c tcflow.3c .\" .\" fileset_database@tccontrol.3c PROGRAMING-MAN .\" $Header: tcattribute.3c,v 72.5 94/11/15 09:56:36 ssa Exp $ .TA t .TH tcattribute 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tcgetattr(\|), tcsetattr(\|) \- control tty device .SH SYNOPSIS .C "#include " .PP .C "int tcgetattr(int fildes, struct termios *termios_p);" .PP .C "int tcsetattr(" .nf .PD 0 .IP .C "int fildes," .C "int optional_actions," .C "const struct termios *termios_p" .PP .C ");" .PD .fi .SH DESCRIPTION .C tcgetattr() gets the parameters associated with .I fildes and stores them in the .I termios structure referenced by .IR termios_p . If the terminal device does not support split baud rates, the input baud rate stored in the .I termios structure is zero. This function is allowed from a background process (see .IR termio (7)). However, the terminal attributes can be subsequently changed by a foreground process. .PP .C tcsetattr() sets the parameters associated with .I fildes (unless support is required from underlying hardware that is not available) from the .I termios structure referenced by .I termios_p as follows: .RS .TP 3 \(bu If .I optional_actions is .CR TCSANOW , the change is immediate. .TP \(bu If .I optional_actions is .CR TCSADRAIN , the change occurs after all output written to .I fildes is transmitted. .TP \(bu If .I optional_actions is .CR TCSAFLUSH , the change occurs after all output written to .I fildes is transmitted, and all input that has been received but not read is discarded. .RE .SH RETURN VALUE Upon successful completion, a value of zero is returned. Otherwise, a value of \-1 is returned and .C errno is set to indicate the error. .SH ERRORS .C tcgetattr() and .C tcsetattr() fail if any of the following conditions are encountered: .TP 15 .SM [EBADF] .I fildes is not a valid file descriptor. .TP .SM [EINVAL] The .I optional_actions argument is not a proper value or no part of a .C tcsetattr() request could be performed. .TP .SM [ENOTTY] The file associated with .I fildes is not a terminal. .SH WARNINGS .C tcsetattr() will attempt to perform as much of the request as possible. However, the hardware being used may not support all possible c_cflag values. If any part of the request can be performed, those values will be set, any values not supported by the hardware will be ignored, and .C tcsetattr() will complete successfully. If no part of the request can be performed, .C tcsetattr() will fail and set .C errno to .SM [EINVAL]. For any hardware that does not support separate input and output baud rates, an attempt to set different input and output baud rates does not affect either baud rate. .C tcgetattr() always returns the actual values set in hardware. For any hardware that does not support separate input and output baud rates, .C tcgetattr() returns zero for the input baud rate. .SH SEE ALSO cfspeed(3C), tccontrol(3C), termio(7). .SH STANDARDS CONFORMANCE .CR tcgetattr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcsetattr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4tcgetattr()\fP: get tty device operating parameters@@@\f3tcattribute(3C)\f1 .\" index@\f4tcsetattr()\fP: set tty device operating parameters@@@\f3tcattribute(3C)\f1 .\" index@get tty device operating parameters@@@\f3tcattribute(3C)\f1 .\" index@set tty device operating parameters@@@\f3tcattribute(3C)\f1 .\" index@tty device operating parameters, get or set@@@\f3tcattribute(3C)\f1 .\" index@control tty device@@@\f3tcattribute(3C)\f1 .\" .\" toc@\f3tcattribute(3C)\f1:\0\0\f4tcgetattr()\fP, \f4tcsetattr()\fP@@@control tty device .\" toc \f4tcgetattr()\fP: get tty device attributes see \f3tcattribute(3C)\f1 .\" toc \f4tcsetattr()\fP: set tty device attributes see \f3tcattribute(3C)\f1 .\" .\" links@tcattribute.3c tcgetattr.3c .\" links@tcattribute.3c tcsetattr.3c .\" .\" fileset_database@tcattribute.3c PROGRAMING-MAN .\" $Header: tcgetpgrp.3c,v 72.4 94/11/15 09:56:42 ssa Exp $ .TA t .TH tcgetpgrp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tcgetpgrp(\|) \- get foreground process group id .SH SYNOPSIS .C "#include " .P .C "pid_t tcgetpgrp(int fildes);" .SH DESCRIPTION .C tcgetpgrp() returns the value of the process group .SM ID of the foreground process group associated with the terminal referenced by .IR fildes . .C tcgetpgrp() is allowed from a process that is a member of a background process group (see .IR termio (7)); however, the information can be subsequently changed by a process that is a member of a foreground process group. .SH RETURN VALUE Upon successful completion, .C tcgetpgrp() returns the value of the process group .SM ID of the foreground process group associated with the terminal referenced by .IR fildes . Otherwise, .C tcgetpgrp() returns a value of \-1 and sets .C errno to indicate the error. .SH ERRORS .C tcgetpgrp() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EACCES] The file associated with .I fildes is the controlling terminal of the calling process, however, there is no foreground process group defined for the controlling terminal. .TP .SM [EBADF] .I fildes is not a valid file descriptor. .TP .SM [ENOTTY] The file associated with .I fildes is not the controlling terminal or the calling process does not have a controlling terminal. .RE .SH WARNING The error .SM EACCES, which is returned if the controlling terminal has no foreground process group, might not be returned in future releases, depending on the course taken by the .SM POSIX standard. Portable applications therefore should not rely on this error condition. .SH SEE ALSO setpgid(2), setsid(2), tcsetpgrp(3C), termio(7). .SH STANDARDS CONFORMANCE .CR tcgetpgrp() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4tcgetpgrp()\fP: get foreground process group \s-1ID\s+1@@@\f3tcgetpgrp(3C)\f1 .\" index@get foreground process group \s-1ID\s+1@@@\f3tcgetpgrp(3C)\f1 .\" index@foreground process group \s-1ID\s+1, get@@@\f3tcgetpgrp(3C)\f1 .\" index@process group \s-1ID\s+1, foreground, get@@@\f3tcgetpgrp(3C)\f1 .\" index@group \s-1ID\s+1, foreground process, get@@@\f3tcgetpgrp(3C)\f1 .\" index@\s-1ID\s+1, foreground process group, get@@@\f3tcgetpgrp(3C)\f1 .\" .\" toc@\f3tcgetpgrp(3C)\f1:\0\0\f4tcgetpgrp()\fP@@@get foreground process group \s-1ID\s+1 .\" .\" fileset_database@tcgetpgrp.3c PROGRAMING-MAN .\" $Header: tcgetsid.3c,v 76.1 95/07/05 17:54:34 ssa Exp $ .TA t .TH tcgetsid 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tcgetsid() \- get terminal session ID .SH SYNOPSIS .C #include .PP .C pid_t tcgetsid (int fildes); .SH DESCRIPTION The .CR tcgetsid() function returns the value of the session ID of the foreground process associated with the terminal referenced by .IR fildes . .CR tcgetsid() is allowed from a process that is a member of a background process group (see .IR termio (7)). .SH RETURN VALUE Upon successful completion, .CR tcgetsid() returns the value of the session ID of the foreground process associated with the terminal referenced by .IR fildes . Otherwise, .CR tcgetsid() returns a value of .CR \(mi1 and sets .CR errno to indicate the error. .SH ERRORS If the .CR tcgetsid() function fails, it sets .CR errno (see .IR errno (2)) to one of the following values: .RS .TP 15 [EACCES] The file associated with .I fildes is the controlling terminal of the calling process; however, there is no foreground process group defined for the controlling terminal. .TP [EBADF] .I fildes is not a valid file descriptor. .TP [ENOTTY] The file associated with .I fildes is not the controlling terminal or the calling process does not have a controlling terminal. .RE .SH SEE ALSO getsid(2), setsid(2), tcgetpgrp(3C). .\" .\" toc@\f3tcgetsid(3C)\f1:\0\0\f4tcgetsid()\f1@@@get terminal session ID\f1 .\" .\" index@\f4tcgetsid()\f1 \- get terminal session ID@@@\f3tcgetsid(3C)\f1 .\" index@\f1terminal session ID, get@@@\f3tcgetsid(3C)\f1 .\" index@\f1session ID, get terminal@@@\f3tcgetsid(3C)\f1 .\" index@\f1ID, get terminal session@@@\f3tcgetsid(3C)\f1 .\" $Header: tccontrol.3c,v 72.5 94/11/15 09:56:37 ssa Exp $ .TA t .TH tccontrol 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tcsendbreak(\|), tcdrain(\|), tcflush(\|), tcflow(\|) \- tty line control functions .SH SYNOPSIS .C "#include " .P .C "int tcsendbreak(int fildes, int duration);" .P .C "int tcdrain(int fildes);" .P .C "int tcflush(int fildes, int queue_selector);" .P .C "int tcflow(int fildes, int action);" .SH DESCRIPTION If the terminal is using asynchronous serial data transmission, .C tcsendbreak() causes transmission of a continuous stream of zero-valued bits for a specific duration. If .I duration is zero, it causes transmission of zero-valued bits for at least 0.25 seconds, but not more than 0.5 seconds. If .I duration is not zero, zero-valued bits are not transmitted. For all .SM HP-UX implementations, .I duration is ignored. .PP .C tcdrain() waits until all output written to .I fildes has been transmitted. .PP .C tcflush() discards data written to .I fildes but not transmitted, or data received but not read, depending on the value of .IR queue_selector : .RS .TP 3 \(bu If .I queue_selector is .CR TCIFLUSH , data received but not read is flushed. .TP \(bu If .I queue_selector is .CR TCOFLUSH , data written but not transmitted is flushed. .TP \(bu If .I queue_selector is .CR TCIOFLUSH , both data received but not read, and data written but not transmitted is flushed. .RE .PP .C tcflow() suspends transmission of data to .I fildes or reception of data from .I fildes , depending on the value of .IR action : .RS .TP 3 \(bu If .I action is .CR TCOOFF , output is suspended. .TP \(bu If .I action is .CR TCOON , suspended output is restarted. .TP \(bu If .I action is .CR TCIOFF , a .SM STOP character is transmitted which is intended to cause the terminal to stop transmitting data to the system. .TP \(bu If .I action is .CR TCION , a .SM START character is transmitted which is intended to cause the terminal to start transmitting data to the system. .RE .SH RETURN VALUE Upon successful completion, a value of zero is returned. Otherwise, a value of \-1 is returned and .C errno is set to indicate the error. .SH ERRORS These functions fail if one or more of the following is true: .RS .TP 15 .SM [EBADF] .I fildes is not a valid file descriptor. .TP .SM [EINTR] A signal was received during .CR tcdrain() . .TP .SM [EINVAL] The .I queue_selector or the .I action argument is not a proper value. .TP .SM [ENOTTY] The file associated with .I fildes is not a terminal. .RE .SH SEE ALSO tcattribute(3C), tccontrol(3C), termio(7). .SH STANDARDS CONFORMANCE .CR tcdrain() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcflow() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcflush() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcsendbreak() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4tcsendbreak()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcdrain()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcflush()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@\f4tcflow()\fP: tty line control function@@@\f3tccontrol(3C)\f1 .\" index@tty line control functions@@@\f3tccontrol(3C)\f1 .\" index@line control functions, tty@@@\f3tccontrol(3C)\f1 .\" index@control functions, tty line@@@\f3tccontrol(3C)\f1 .\" .\" toc@\f3tccontrol(3C)\f1:\0\0\f4tcsendbreak()\fP, \f4tcdrain()\fP, \f4tcflush()\fP, \f4tcflow()\fP@@@tty line control functions .\" toc@\f4tcsendbreak()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcdrain()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcflush()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" toc@\f4tcflow()\fP: tty line control functions@@@see \f3tccontrol(3C)\f1 .\" .\" links@tccontrol.3c tcsendbreak.3c .\" links@tccontrol.3c tcdrain.3c .\" links@tccontrol.3c tcflush.3c .\" links@tccontrol.3c tcflow.3c .\" .\" fileset_database@tccontrol.3c PROGRAMING-MAN .\" $Header: tcattribute.3c,v 72.5 94/11/15 09:56:36 ssa Exp $ .TA t .TH tcattribute 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tcgetattr(\|), tcsetattr(\|) \- control tty device .SH SYNOPSIS .C "#include " .PP .C "int tcgetattr(int fildes, struct termios *termios_p);" .PP .C "int tcsetattr(" .nf .PD 0 .IP .C "int fildes," .C "int optional_actions," .C "const struct termios *termios_p" .PP .C ");" .PD .fi .SH DESCRIPTION .C tcgetattr() gets the parameters associated with .I fildes and stores them in the .I termios structure referenced by .IR termios_p . If the terminal device does not support split baud rates, the input baud rate stored in the .I termios structure is zero. This function is allowed from a background process (see .IR termio (7)). However, the terminal attributes can be subsequently changed by a foreground process. .PP .C tcsetattr() sets the parameters associated with .I fildes (unless support is required from underlying hardware that is not available) from the .I termios structure referenced by .I termios_p as follows: .RS .TP 3 \(bu If .I optional_actions is .CR TCSANOW , the change is immediate. .TP \(bu If .I optional_actions is .CR TCSADRAIN , the change occurs after all output written to .I fildes is transmitted. .TP \(bu If .I optional_actions is .CR TCSAFLUSH , the change occurs after all output written to .I fildes is transmitted, and all input that has been received but not read is discarded. .RE .SH RETURN VALUE Upon successful completion, a value of zero is returned. Otherwise, a value of \-1 is returned and .C errno is set to indicate the error. .SH ERRORS .C tcgetattr() and .C tcsetattr() fail if any of the following conditions are encountered: .TP 15 .SM [EBADF] .I fildes is not a valid file descriptor. .TP .SM [EINVAL] The .I optional_actions argument is not a proper value or no part of a .C tcsetattr() request could be performed. .TP .SM [ENOTTY] The file associated with .I fildes is not a terminal. .SH WARNINGS .C tcsetattr() will attempt to perform as much of the request as possible. However, the hardware being used may not support all possible c_cflag values. If any part of the request can be performed, those values will be set, any values not supported by the hardware will be ignored, and .C tcsetattr() will complete successfully. If no part of the request can be performed, .C tcsetattr() will fail and set .C errno to .SM [EINVAL]. For any hardware that does not support separate input and output baud rates, an attempt to set different input and output baud rates does not affect either baud rate. .C tcgetattr() always returns the actual values set in hardware. For any hardware that does not support separate input and output baud rates, .C tcgetattr() returns zero for the input baud rate. .SH SEE ALSO cfspeed(3C), tccontrol(3C), termio(7). .SH STANDARDS CONFORMANCE .CR tcgetattr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tcsetattr() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4tcgetattr()\fP: get tty device operating parameters@@@\f3tcattribute(3C)\f1 .\" index@\f4tcsetattr()\fP: set tty device operating parameters@@@\f3tcattribute(3C)\f1 .\" index@get tty device operating parameters@@@\f3tcattribute(3C)\f1 .\" index@set tty device operating parameters@@@\f3tcattribute(3C)\f1 .\" index@tty device operating parameters, get or set@@@\f3tcattribute(3C)\f1 .\" index@control tty device@@@\f3tcattribute(3C)\f1 .\" .\" toc@\f3tcattribute(3C)\f1:\0\0\f4tcgetattr()\fP, \f4tcsetattr()\fP@@@control tty device .\" toc \f4tcgetattr()\fP: get tty device attributes see \f3tcattribute(3C)\f1 .\" toc \f4tcsetattr()\fP: set tty device attributes see \f3tcattribute(3C)\f1 .\" .\" links@tcattribute.3c tcgetattr.3c .\" links@tcattribute.3c tcsetattr.3c .\" .\" fileset_database@tcattribute.3c PROGRAMING-MAN .\" $Header: tcsetpgrp.3c,v 72.4 94/11/15 09:56:44 ssa Exp $ .TA t .TH tcsetpgrp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tcsetpgrp(\|) \- set foreground process group id .SH SYNOPSIS .C "#include " .P .C "int tcsetpgrp(int fildes, pid_t pgrp_id);" .SH DESCRIPTION If the calling process has a controlling terminal, .C tcsetpgrp() sets the foreground process group .SM ID associated with the terminal referenced by .I fildes to .IR pgrp_id . The file associated with .I fildes must be the controlling terminal of the calling process and the controlling terminal must be currently associated with the session of the calling process. The value of .I pgrp_id must match a process group .SM ID of a process in the same session as the calling process. .SH RETURN VALUE Upon successful completion, .C tcsetpgrp() returns zero. Otherwise, .C tcsetpgrp() returns \-1 and sets .C errno to indicate the error. .SH ERRORS .C tcsetpgrp() fails if any of the following conditions are encountered: .RS .TP 15 .SM [EBADF] .I fildes is not a valid file descriptor. .TP .SM [EINVAL] The value of the .I pgrp_id argument is not supported. .TP .SM [ENOTTY] The calling process does not have a controlling terminal, or the .I fildes is not the controlling terminal, or the controlling terminal is no longer associated with the session of the calling process. .TP .SM [EPERM] The value of .I pgrp_id is a supported value but does not match the process group .SM ID of a process in the same session as the calling process. .RE .SH SEE ALSO setpgid(2), setsid(2), tcgetpgrp(3C), termio(7). .SH STANDARDS CONFORMANCE .CR tcsetpgrp() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4tcsetpgrp()\fP: get foreground process group \s-1ID\s+1@@@\f3tcsetpgrp(3C)\f1 .\" index@set foreground process group \s-1ID\s+1@@@\f3tcsetpgrp(3C)\f1 .\" index@foreground process group \s-1ID\s+1, set@@@\f3tcsetpgrp(3C)\f1 .\" index@process group \s-1ID\s+1, foreground, set@@@\f3tcsetpgrp(3C)\f1 .\" index@group \s-1ID\s+1, foreground process, set@@@\f3tcsetpgrp(3C)\f1 .\" index@\s-1ID\s+1, foreground process group, set@@@\f3tcsetpgrp(3C)\f1 .\" .\" toc@\f3tcsetpgrp(3C)\f1:\0\0\f4tcsetpgrp()\fP@@@get foreground process group \s-1ID\s+1 .\" .\" fileset_database@tcsetpgrp.3c PROGRAMING-MAN .\" $Header: tsearch.3c,v 72.5 94/11/15 09:56:53 ssa Exp $ .TA t .TH tsearch 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tsearch(\|), tfind(\|), tdelete(\|), twalk(\|) \- manage binary search trees .SH SYNOPSIS .C "#include " .PP .C "void *tsearch(" .nf .PD 0 .IP .C "const void *key," .C "void **rootp," .C "int (*compar)(const void *, const void *)" .P .C ");" .PD .PP .C "void *tfind(" .PD 0 .IP .C "const void *key," .C "void * const *rootp," .C "int (*compar)(const void *, const void *)" .P .C ");" .PD .PP .C "void *tdelete(" .PD 0 .IP .C "const void *key," .C "void **rootp," .C "int (*compar)(const void *, const void *)" .PP .C ");" .PD .PP .C "void twalk(" .PD 0 .IP .C "const void *root," .C "void (*action)(const void *, VISIT, int)" .PP .C ");" .PD .fi .SH DESCRIPTION .CR tsearch() , .CR tfind() , .CR tdelete() , and .C twalk() are routines for manipulating binary search trees. They are generalized from Knuth (6.2.2) Algorithms T and D. All comparisons are done with a user-supplied routine, .IR compar . This routine is called with two arguments, the pointers to the elements being compared. It returns an integer less than, equal to, or greater than 0, according to whether the first argument is to be considered less than, equal to or greater than the second argument. The comparison function need not compare every byte, so arbitrary data may be contained in the elements in addition to the values being compared. .PP .C tsearch() is used to build and access the tree. .I key is a pointer to an entry to be accessed or stored. If there is an entry in the tree equal to the value pointed to by .IR key , a pointer to the previous key associated with this found entry is returned. Otherwise, .I key is inserted, and a pointer to it returned. Note that since the value returned is a pointer to .I key and .I key itself is a pointer, the value returned is a pointer to a pointer. Only pointers are copied, so the calling routine must store the data. .I rootp points to a variable that points to the root of the tree. A .SM NULL value for the variable pointed to by .I rootp denotes an empty tree; in this case, the variable is set to point to the entry which will be at the root of the new tree. .PP Like .CR tsearch() , .C tfind() searches for an entry in the tree, returning a pointer to it if found. However, if it is not found, .C tfind() returns a .SM NULL pointer. The arguments for .C tfind() are the same as for .CR tsearch() . .PP .C tdelete() deletes a node from a binary search tree. Arguments are the same as for .CR tsearch() . The variable pointed to by .I rootp is changed if the deleted node was the root of the tree. .C tdelete() returns a pointer to the parent of the deleted node, or a .SM NULL pointer if the node is not found. .PP .C twalk() traverses a binary search tree. .I root is the root of the tree to be traversed. (Any node in a tree may be used as the root for a walk below that node.) .I action is the name of a routine to be invoked at each node. This routine is, in turn, called with three arguments: .RS .TP 3 \(bu First argument is the address of the node being visited. .TP \(bu Second argument is a value from an enumeration data type .C "typedef enum { preorder, postorder, endorder, leaf }" .C VISIT; (defined in the .RC < search.h > header file), depending on whether this is the first, second or third time that the node has been visited (during a depth-first, left-to-right traversal of the tree), or whether the node is a leaf. .TP \(bu Third argument is the level of the node in the tree, with the root being level zero. .RE .SH EXAMPLE The following code reads strings, and stores structures containing a pointer to each string and a count of its length. It then walks the tree, printing out the stored strings and their lengths in alphabetical order. .nf .IP .C "#include " .C "#include " .C "#include " .C "#include " .IP .C "struct element /* pointers to these are stored in the tree */" .C { .C " char *string;" .C " int length;" .C " };" .C "char string_space[10000]; /* space to store strings */" .C "struct element elements[500]; /* elements to store */" .C "struct element *root = NULL; /* this points to the root */" .C " .C "void print_node(void *, VISIT, int);" .C "int element_compare(const void *, const void *);" .IP .C "main( )" .C { .C " char *strptr = string_space;" .C " struct element *element_ptr = elements;" .C " struct element **ts_retval;" .IP .C " int i = 0;" .IP .C " while (gets(strptr) != NULL && i++ < 500)" .C " {" .IP .C " /* set element */" .C " element_ptr->string = strptr;" .C " element_ptr->length = strlen(strptr);" .IP .C " /* put element into the tree */" .C " ts_retval = (struct element **) tsearch((void *) element_ptr," .C " (void **) &root, element_compare);" .IP .C " if (*ts_retval == element_ptr)" .C " { .ift .ft 4 .ps +1 .ifn .ft 3 (void) printf("The element \e"%s\e" ", (*ts_retval)->string); (void) printf("has now been inserted into the tree\en"); .ps .ft .C " }" .C " else" .C " {" .ift .ft 4 .ps +1 .ifn .ft 3 (void) printf("The element \e"%s\e" ", (*ts_retval)->string); (void) printf("already existed in the tree\en"); .ps .ft .C " }" .IP .C " /* adjust pointers, so we don't overwrite tree */" .C " strptr += element_ptr->length + 1;" .C " element_ptr++;" .C " }" .C " twalk((void *) root, print_node);" .C } .C "/* This routine compares two elements, based on an" .C " alphabetical ordering of the string field. */" .C int .C "element_compare(elem1, elem2)" .C "void *elem1, *elem2;" .C { .C " return strcmp(((struct element *) elem1)->string," .C " ((struct element *) elem2)->string);" .C } .C "/* This routine prints out a node, the first time" .C " twalk encounters it. */" .C void .C "print_node(element, order, level)" .C "void *element;" .C "VISIT order;" .C "int level;" .C { .C " if (order == preorder || order == leaf)" .C " {" .ift .ft 4 .ps +1 .ifn .ft 3 (void) printf("string = %20s, length = %d\en", .ps .ft .C " (*(struct element **) element)->string," .C " (*(struct element **) element)->length);" .C " }" .C } .fi .RE .SH SEE ALSO bsearch(3C), hsearch(3C), lsearch(3C). .SH RETURN VALUE A .SM NULL pointer is returned by .C tsearch() if there is not enough space available to create a new node. .PP A .SM NULL pointer is returned by .CR tsearch() , .CR tfind() , and .C tdelete() if .I rootp is .SM NULL on entry. .PP If the datum is found, both .C tsearch() and .C tfind() return a pointer to it. If not, .C tfind() returns .SM NULL, and .C tsearch() returns a pointer to the inserted item. .SH WARNINGS The .I root argument to .C twalk() is one level of indirection less than the .I rootp arguments to .C tsearch() and .CR tdelete() . .PP Two nomenclatures are used to refer to the order in which tree nodes are visited. .C tsearch() uses preorder, postorder and endorder to respectively refer to visiting a node before any of its children, after its left child and before its right and after both its children. The alternate nomenclature uses preorder, inorder, and postorder to refer to the same visits, which could result in some confusion over the meaning of postorder. If the calling function alters the pointer to the root, results are unpredictable. .SH STANDARDS CONFORMANCE .CR tsearch() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR tdelete() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR tfind() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR twalk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4tsearch()\fP \- build and access a binary search tree@@@\f3tsearch(3C)\f1 .\" index@\f4tfind()\fP \- get data pointer for binary search tree@@@\f3tsearch(3C)\f1 .\" index@\f4tdelete()\fP \- delete a node from a binary search tree@@@\f3tsearch(3C)\f1 .\" index@\f4twalk()\fP \- traverse a binary search tree@@@\f3tsearch(3C)\f1 .\" index@build or access a binary search tree@@@\f3tsearch(3C)\f1 .\" index@access or build a binary search tree@@@\f3tsearch(3C)\f1 .\" index@get: data pointer for binary search tree@@@\f3tsearch(3C)\f1 .\" index@data pointer for binary search tree, get@@@\f3tsearch(3C)\f1 .\" index@pointer for binary search tree, get data@@@\f3tsearch(3C)\f1 .\" index@delete a node from a binary search tree@@@\f3tsearch(3C)\f1 .\" index@node from a binary search tree, delete a@@@\f3tsearch(3C)\f1 .\" index@traverse a binary search tree@@@\f3tsearch(3C)\f1 .\" index@manage a binary search tree@@@\f3tsearch(3C)\f1 .\" index@binary search tree, manage a@@@\f3tsearch(3C)\f1 .\" index@search tree, manage a binary@@@\f3tsearch(3C)\f1 .\" index@tree, manage a binary search@@@\f3tsearch(3C)\f1 .\" .\" toc@\f3tsearch(3C)\f1:\0\0\f4tsearch()\fP, \f4tfind()\fP, \f4tdelete()\fP, \f4twalk()\fP@@@manage binary search trees .\" toc@\f4tfind()\fP:\0\0manage binary search trees@@@see \f3tsearch(3C)\f1 .\" toc@\f4tdelete()\fP:\0\0manage binary search trees@@@see \f3tsearch(3C)\f1 .\" toc@\f4twalk()\fP:\0\0manage binary search trees@@@see \f3tsearch(3C)\f1 .\" .\" links@tsearch.3c tfind.3c .\" links@tsearch.3c tdelete.3c .\" links@tsearch.3c twalk.3c .\" .\" fileset_database@tsearch.3c PROGRAMING-MAN .\" $Header: directory.3c,v 76.1 95/07/05 17:28:05 ssa Exp $ .TA d .TH directory 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME opendir(\|), readdir(\|), readdir_r(\|), telldir(\|), seekdir(\|), rewinddir(\|), closedir(\|) \- directory operations .SH SYNOPSIS .C "#include " .PP .C "DIR *opendir(const char *dirname);" .PP .C "struct dirent *readdir(DIR *dirp);" .PP .C "int readdir_r(DIR *dirp, struct dirent *result);" .PP .C "long int telldir(DIR *dirp);" .PP .C "void seekdir(DIR *dirp, long int loc);" .PP .C "void rewinddir(DIR *dirp);" .PP .C "int closedir(DIR *dirp);" .SH DESCRIPTION This library package provides functions that allow programs to read directory entries without having to know the actual directory format associated with the file system. Because these functions allow programs to be used portably on file systems with different directory formats, this is the recommended way to read directory entries. .TP 15 .CR opendir() opens the directory .I dirname and associates a directory stream with it. .CR opendir() returns a pointer used to identify the directory stream in subsequent operations. .CR opendir() uses .IR malloc (3C) to allocate memory. .TP .CR readdir() returns a pointer to the next directory entry. It returns a .SM NULL pointer upon reaching the end of the directory or detecting an invalid .CR seekdir() operation. See .IR dirent (5) for a description of the fields available in a directory entry. .TP .CR readdir_r() expects to be passed the address of a .CR "struct dirent" and will store the result at the supplied location. .TP .CR telldir() returns the current location (encoded) associated with the directory stream to which .IR dirp refers. .TP .CR seekdir() sets the position of the next .CR readdir() operation on the directory stream to which .IR dirp refers. The .IR loc argument is a location within the directory stream obtained from .CR telldir() . The position of the directory stream is restored to where it was when .CR telldir() returned that .I loc value. Values returned by .CR telldir() are valid only while the .CR DIR pointer from which they are derived remains open. If the directory stream is closed and then reopened, the .CR telldir() value might be invalid. .TP .CR rewinddir() resets the position of the directory stream to which .IR dirp refers to the beginning of the directory. It also causes the directory stream to refer to the current state of the corresponding directory, as a call to .CR opendir() would have done. .TP .CR closedir() closes the named directory stream, then frees the structure associated with the .CR DIR pointer. .SH RETURN VALUE .TP 15 .CR opendir() , upon successful completion, returns a pointer to an object of type .CR DIR referring to an open directory stream. Otherwise, it returns a .SM NULL pointer and sets the global variable .CR errno to indicate the error. .TP .CR readdir() , upon successful completion, returns a pointer to an object of type .CR struct dirent describing a directory entry. Upon reaching the end of the directory, .CR readdir() returns a .SM NULL pointer and does not change the value of .CR errno . Otherwise, it returns a .SM NULL pointer and sets .CR errno to indicate the error. .TP .CR readdir_r() , upon successful completion, returns a 0. Upon reaching the end of directory or encountering an error, it returns a -1 and sets .CR errno to indicate the error. .TP .CR telldir() , upon successful completion, returns a long value indicating the current position in the directory. Otherwise it returns .CR \-1 and sets .CR errno to indicate the error. .TP .CR seekdir() does not return any value, but if an error is encountered, .CR errno is set to indicate the error. .TP .CR closedir() , upon successful completion, returns a value of .CR 0 . Otherwise, it returns a value of .CR \-1 and sets .CR errno to indicate the error. .SH ERRORS .CR opendir() fails if any of the following conditions are encountered: .RS .TP 20 .SM [EACCES] Search permission is denied for a component of .IR dirname , or read permission is denied for .IR dirname . .TP .SM [EFAULT] .I dirname points outside the allocated address space of the process. The reliable detection of this error is implementation dependent. .TP .SM [ELOOP] Too many symbolic links were encountered in translating the path name. .TP .SM [EMFILE] Too many open file descriptors are currently open for the calling process. .TP .SM [ENAMETOOLONG] A component of .IR dirname exceeds .CR PATH_MAX bytes, or the entire length of .IR dirname exceeds .CR PATH_MAX \(mi 1 bytes while .CR _POSIX_NO_TRUNC is in effect. .TP .SM [ENFILE] Too many open file descriptors are currently open on the system. .TP .SM [ENOENT] A component of .I dirname does not exist. .TP .SM [ENOMEM] .CR malloc() failed to provide sufficient memory to process the directory. .TP .SM [ENOTDIR] A component of .I dirname is not a directory. .TP .SM [ENOENT] The .IR dirname argument points to an empty string. .RE .PP .CR readdir() " or " readdir_r() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] The directory stream to which .IR dirp refers is not located at a valid directory entry. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR telldir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR seekdir() might fail if the following condition is encountered: .RS .TP 20 .SM [ENOENT] .I dirp specifies an improper file system block size. .RE .PP .CR closedir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP 20 .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .PP .CR rewinddir() might fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] .IR dirp does not refer to an open directory stream. .TP .SM [EFAULT] .IR dirp points outside the allocated address space of the process. .RE .SH EXAMPLES The following code searches the current directory for an entry .IR name : .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 DIR *dirp; struct dirent *dp; dirp = opendir("."); while ((dp = readdir(dirp)) != NULL) { if (strcmp(dp->d_name, name) == 0) { (void) closedir(dirp); return FOUND; } } (void) closedir(dirp); return NOT_FOUND; .ft .ps .fi .RE .SH WARNINGS .CR readdir() and .CR getdirentries() (see .IR getdirentries (2) are the only ways to access remote .SM NFS directories. Attempting to read a remote directory via .SM NFS by using .CR read() returns .CR \-1 and sets .CR errno to .SM EISDIR (see .IR read (2)). .PP .CR readdir() is unsafe in multi-thread applications. .CR readdir_r() is MT-Safe and should be used instead. Users of .CR readdir_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH APPLICATION USAGE The header file required for these functions and the type of the return value from .CR readdir() has been changed for compatibility with System V Release 3 and the .IR "X/Open Portability Guide" . See .IR ndir (5) for a description of the header file .RC < ndir.h >, which is provided to allow existing .SM HP-UX applications to compile unmodified. .PP New applications should use the .RC < dirent.h > header file for portability to System V and X/Open systems. .SH AUTHOR .CR directory was developed by AT&T, HP, and the University of California, Berkeley. .SH SEE ALSO close(2), getdirentries(2), lseek(2), open(2), read(2), dir(4), dirent(5), ndir(5). .SH STANDARDS CONFORMANCE .CR closedir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR opendir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR readdir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR rewinddir() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR seekdir() ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR telldir() ": AES, XPG2, XPG3, XPG4" .\" .\" index@\f4opendir()\f1 \- open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f4readdir()\f1 \- get pointer to current entry in open directory@@@\f3directory(3C)\f1 .\" index@\f4telldir()\f1 \- get current location of named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4seekdir()\f1 \- set position of next \f4readdir()\f1 operation on named \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@\f4rewinddir()\f1 \- reset position of named \f2directory stream\f1 to beginning of directory@@@\f3directory(3C)\f1 .\" index@\f4closedir()\f1 \- close a currently open directory@@@\f3directory(3C)\f1 .\" index@open a directory and associated \f2directory stream\f1 for access@@@\f3directory(3C)\f1 .\" index@\f2directory stream\f1, directory and associated, open for access@@@\f3directory(3C)\f1 .\" index@open, access, or close a directory@@@\f3directory(3C)\f1 .\" index@close, access, or open a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" index@directory: access, open, or close a directory and associated \f2directory stream\f1@@@\f3directory(3C)\f1 .\" .\" toc@\f3directory(3C)\f1:\0\0\f4directory()\f1, \f4opendir()\f1, \f4readdir()\f1, \f4telldir()\f1, \f4seekdir()\f1, \f4rewinddir()\f1,\n\f4closedir()\f1@@@directory operations .\" toc@\f4opendir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4readdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4telldir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4seekdir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4rewinddir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" toc@\f4closedir()\f1:\0\0directory operations@@@see \f3directory(3C)\f1 .\" .\" links@directory.3c opendir.3c .\" links@directory.3c readdir.3c .\" links@directory.3c readdir_r.3c .\" links@directory.3c telldir.3c .\" links@directory.3c seekdir.3c .\" links@directory.3c rewinddir.3c .\" links@directory.3c closedir.3c .\" $Header: tmpnam.3s,v 78.1 96/01/22 22:28:32 ssa Exp $ .TA t .TH tmpnam 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tmpnam(\|), tempnam(\|) \- create a name for a temporary file .SH SYNOPSIS .C "#include " .PP .C "char *tmpnam(char *s);" .PP .C "char *tempnam(const char *dir, const char *pfx);" .SH DESCRIPTION .CR tmpnam() and .CR tempnam() generate file names that can safely be used for a temporary file. .RS .TP 15 .CR tmpnam() Always generates a file name using the path-prefix defined as .CR P_tmpdir in the .RC < stdio.h > header file. If .I s is .SM NULL, .CR tmpnam() leaves its result in an internal static area and returns a pointer to that area. The next call to .CR tmpnam() destroys the contents of the area. If .I s is not .SM NULL, it is assumed to be the address of an array of at least .CR L_tmpnam bytes, where .CR L_tmpnam is a constant defined in .RC < stdio.h >; .CR tmpnam() places its result in that array and returns .IR s . For multi-thread applications, if .I s is a .SM NULL pointer, the operation is not performed and a .SM NULL pointer is returned. .TP .CR tempnam() allows the user to control the choice of a directory. The argument .I dir points to the name of the directory in which the file is to be created. If .I dir is .SM NULL or points to a string that is not an appropriate directory name, the path-prefix defined as .CR P_tmpdir in the .RC < stdio.h > header file is used. If that directory is not accessible, .CR /tmp is used as a last resort. This entire sequence can be eliminated by providing an environment variable .CR TMPDIR in the user's environment, whose value is the name of the desired temporary-file directory. .RE .PP In order to request the default behavior for either .CR tempnam() or .CR tmpnam() , a NULL value must be passed in .IR dir and .IR pfx for .CR tempnam() , or in .IR s for .CR tmpnam() . If valid parameters are not passed in, behavior is undefined. .RE .PP Many applications are written such that temporary files have certain initial character sequences in their names. Use the .I pfx argument to define a given prefix. The argument can be .SM NULL or point to a string of up to five characters to be used as the first characters in the temporary-file name. .PP .CR tempnam() uses .CR malloc() (see .IR malloc (3C)) to get space for the constructed file name, and returns a pointer to this area. Thus, any pointer value returned from .CR tempnam() can serve as an argument to .CR free() (see .IR malloc (3C)). If .CR tempnam() cannot return the expected result for any reason; i.e., .CR malloc() failed, or none of the above mentioned attempts to find an appropriate directory was successful, a .SM NULL pointer is returned. .SH NOTES .CR tmpnam() and .CR tempnam() generate a different file name each time they are called, but start recycling previously used names if called more than .CR TMP_MAX times in a single process. .PP Files created using these functions and either .CR fopen() or .CR creat() (see .IR fopen (3S) and .IR creat (2)) are temporary only in the sense that they reside in a directory intended for temporary use, and their names are unique. It is the user's responsibility to use .IR unlink (2) to remove the file when it is no longer needed. .SH WARNINGS Between the time a file name is created and the file is opened, it is possible for some other process to create a file with the same name. This can never happen if that other process is using these functions or .CR mktemp , and the file names are chosen such that duplication by other means is unlikely. .SH SEE ALSO creat(2), unlink(2), malloc(3C), mktemp(3C), fopen(3S), tmpfile(3S). .SH STANDARDS CONFORMANCE .CR tmpnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR tempnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4tmpnam()\fP \- create a name for a temporary file@@@\f3tmpnam(3S)\f1 .\" index@\f4tempnam()\fP \- create a name for a temporary file@@@\f3tmpnam(3S)\f1 .\" index@create a name for a temporary file@@@\f3tmpnam(3S)\f1 .\" index@name: create a name for a temporary file@@@\f3tmpnam(3S)\f1 .\" index@temporary file, create a name for@@@\f3tmpnam(3S)\f1 .\" index@file: create a name for a temporary file@@@\f3tmpnam(3S)\f1 .\" .\" toc@\f3tmpnam(3S)\f1:\0\0\f4tmpnam()\fP, \f4tempnam()\fP@@@create a name for a temporary file .\" toc@\f4tempnam()\fP:\0\0create a name for a temporary file@@@see \f3tmpnam(3S)\f1 .\" .\" links@tmpnam.3s tempnam.3s .\" $Header: termattrs.3x,v 76.2 95/08/01 14:52:10 ssa Exp $ .TA t .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH termattrs 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME termattrs, term_attrs \(em get supported terminal video attributes .SH SYNOPSIS .C "#include " .P .C "chtype termattrs(void);" .P .C "attr_t term_attrs(void);" .SH DESCRIPTION The .Fn termattrs function extracts the video attributes of the current terminal. That are supported by the .B chtype data type. .P The .Fn term_attrs function extracts the video attributes of the current terminal. That are supported for a .B cchar_t data type. .SH "RETURN VALUE" The .Fn termattrs function returns a logical OR of A_ values of all video attributes supported by the terminal. .P The .Fn term_attrs function returns a logical OR of WA_ values of all video attributes supported by the terminal. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Attributes\f1 in curses_intro, attroff(), attr_get(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3termattrs(3X)\f1:\0\0\f4termattrs()\f1, \f4term_attrs()\f1@@@get supported terminal video attributes .\" toc@\f4term_attrs()\f1: get supported terminal video attributes@@@see \f3termattrs(3X)\f1 .\" .\" index@\f4termattrs()\f1 \- get supported terminal video attributes@@@\f3termattrs(3X)\f1 .\" index@\f4term_attrs()\f1 \- get supported terminal video attributes@@@\f3termattrs(3X)\f1 .\" index@\f1get supported terminal video attributes@@@\f3termattrs(3X)\f1 .\" index@\f1supported terminal video attributes, get@@@\f3termattrs(3X)\f1 .\" index@\f1terminal video attributes, get supported ones@@@\f3termattrs(3X)\f1 .\" index@\f1video attributes, terminal, get supported@@@\f3termattrs(3X)\f1 .\" .\" links@termattrs.3x term_attrs.3x .\" .\" fileset_database@termattrs.3x CURS-ENG-A-MAN .\" $Header: termattrs.3x,v 76.2 95/08/01 14:52:10 ssa Exp $ .TA t .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH termattrs 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME termattrs, term_attrs \(em get supported terminal video attributes .SH SYNOPSIS .C "#include " .P .C "chtype termattrs(void);" .P .C "attr_t term_attrs(void);" .SH DESCRIPTION The .Fn termattrs function extracts the video attributes of the current terminal. That are supported by the .B chtype data type. .P The .Fn term_attrs function extracts the video attributes of the current terminal. That are supported for a .B cchar_t data type. .SH "RETURN VALUE" The .Fn termattrs function returns a logical OR of A_ values of all video attributes supported by the terminal. .P The .Fn term_attrs function returns a logical OR of WA_ values of all video attributes supported by the terminal. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Attributes\f1 in curses_intro, attroff(), attr_get(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3termattrs(3X)\f1:\0\0\f4termattrs()\f1, \f4term_attrs()\f1@@@get supported terminal video attributes .\" toc@\f4term_attrs()\f1: get supported terminal video attributes@@@see \f3termattrs(3X)\f1 .\" .\" index@\f4termattrs()\f1 \- get supported terminal video attributes@@@\f3termattrs(3X)\f1 .\" index@\f4term_attrs()\f1 \- get supported terminal video attributes@@@\f3termattrs(3X)\f1 .\" index@\f1get supported terminal video attributes@@@\f3termattrs(3X)\f1 .\" index@\f1supported terminal video attributes, get@@@\f3termattrs(3X)\f1 .\" index@\f1terminal video attributes, get supported ones@@@\f3termattrs(3X)\f1 .\" index@\f1video attributes, terminal, get supported@@@\f3termattrs(3X)\f1 .\" .\" links@termattrs.3x term_attrs.3x .\" .\" fileset_database@termattrs.3x CURS-ENG-A-MAN .\" $Header: termcap.3x,v 76.1 95/08/23 17:41:19 ssa Exp $ .TA t .TH termcap 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tgetent(\|), tgetnum(\|), tgetflag(\|), tgetstr(\|), tgoto(\|), .ifn .br .ifn \0\0\0\0 tputs(\|) \- emulate /usr/share/lib/termcap access routines .SH SYNOPSIS .C "#include " .P .C "int tgetent(char *bp, const char *name);" .P .C "int tgetnum(const char *id);" .P .C "int tgetflag(const char *id);" .P .C "char *tgetstr(const char *id, char **area);" .P .C "char *tgoto(char *cm, int destcol, int destline);" .P .C "int tputs(char *cp, int affcnt, int (*outc)(int));" .SH DESCRIPTION These functions extract and use capabilities from the compiled terminal capability data bases (see .IR terminfo (4)). They are emulation routines that are provided as a part of the .IR curses (3X) library. .RS .TP 15 .CR tgetent() Extracts the compiled entry for terminal .I name into buffers accessible by the programmer. Unlike previous termcap routines, all capability strings (except cursor addressing and padding information) are already compiled and stored internally upon return from .CR tgetent() . The buffer pointer .I bp is redundant in the emulation, and is ignored. It should not be relied upon to point to meaningful information. .CR tgetent() returns \-1 if it cannot access the .I terminfo directory, 0 if there is no capability file for .I name, and 1 if all goes well. If a .CR TERMINFO environment variable is set, .CR tgetent() first looks for .CI TERMINFO/?/ name (where .CR ? is the first character of .IR name ), and if that file is not accessible, it looks for .CI /usr/share/lib/terminfo/?/ name\f1. .TP .CR tgetnum() Gets the numeric value of capability .I id, returning \-1 if it is not given for the terminal. .CR tgetnum() is useful only with capabilities having numeric values. .TP .CR tgetflag() Returns 1 if the specified capability is present in the terminal's entry, and 0 if it is not. .CR tgetflag() is useful only with capabilities that are boolean in nature (i.e. either present or missing in .IR terminfo (4)). .TP .CR tgetstr() Returns a pointer to the string value of capability .IR id . In addition, if .I area is not a NULL pointer, .CR tgetstr() places the capability in the buffer at .I area and advances the area pointer. The returned string capability is compiled except for cursor addressing and padding information. .CR tgetstr() is useful only with capabilities having string values. .TP .CR tgoto() Returns a cursor addressing string decoded from .I cm to go to column .I destcol in line .IR destline . (Programs that call .CR tgoto() should be sure to turn off the TAB3 bit or bits, since .CR tgoto() can now output a tab. See .IR termio (7)). Note that programs using .CR termcap should in general turn off TAB3 anyway since some terminals use Ctrl-I for other functions, such as nondestructive space.) If a .CR % sequence is given that is not understood, .CR tgoto() returns [OOPS]. .TP .CR tputs() Decodes the padding information of the string .IR cp . .I affcnt gives the number of lines affected by the operation, or 1 if this is not applicable. .I outc is a routine that is called with each character in turn. The .CR terminfo variable .I pad_char should contain a pad character to be used (from the .I pc capability) if a null .ifn (\f3^@\fP) .ift (\f4^@\fP) is inappropriate. .RE .SH WARNINGS These routines are not meant to be used by programs running in the background. .SH FILES .TP 42 .C "/usr/lib/libcurses.a -lcurses" library .TP .C /usr/share/lib/terminfo/?/* data bases .SH SEE ALSO ex(1), terminfo(4), termio(7). .\" index@\f4tgetent()\fP \- get compiled terminfo data base entry into buffer@@@\f3termcap(3X)\f1 .\" index@\f4tgetnum()\fP \- get numeric value of compiled terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgetflag()\fP \- get availability of compiled boolean terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgetstr()\fP \- get string value of compiled terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgoto()\fP \- get compiled terminal cursor addressing string@@@\f3termcap(3X)\f1 .\" index@\f4tputs()\fP \- decode terminal string padding information@@@\f3termcap(3X)\f1 .\" index@emulate \f2/etc/termcap\f1 access routines@@@\f3termcap(3X)\f1 .\" index@\f2/etc/termcap\f1 access routines, emulate@@@\f3termcap(3X)\f1 .\" index@\f4termcap()\fP access routines, emulate \f2/etc/\f1@@@\f3termcap(3X)\f1 .\" index@routines, emulate \f2/etc/termcap\f1 access@@@\f3termcap(3X)\f1 .\" .\" toc@\f3termcap(3X)\f1:\0\0\f4tgetent()\fP, \f4tgetnum()\fP, \f4tgetflag()\fP, \f4tgetstr()\fP, \f4tgoto()\fP, \f4tputs()\fP@@@emulate \f2/etc/termcap\f1 access routines .\" toc@\f4tgetent()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetnum()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetflag()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetstr()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgoto()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tputs()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" .\" links@termcap.3x tgetnum.3x .\" links@termcap.3x tgetflag.3x .\" links@termcap.3x tgetstr.3x .\" links@termcap.3x tgoto.3x .\" .\" fileset_database@termcap.3x PROGRAMING-MAN .\" $Header: termname.3x,v 76.2 95/08/01 14:53:25 ssa Exp $ .TA t .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH termname 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME termname \(em get terminal name .SH SYNOPSIS .C "#include " .P .C "char *termname(void);" .SH DESCRIPTION The .Fn termname function obtains the terminal name as recorded by .CR setupterm() . .SH "RETURN VALUE" The .Fn termname function returns a pointer to the terminal name. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Minimum Guaranteed Limits\f1 in terminfo(4), del_curterm(), getenv() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), initscr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4termname()\f1 \- get terminal name@@@\f3termname(3X)\f1 .\" index@\f1get terminal name@@@\f3termname(3X)\f1 .\" index@\f1terminal name, get@@@\f3termname(3X)\f1 .\" index@\f1terminal, get name@@@\f3termname(3X)\f1 .\" .\" toc@\f3termname(3X)\f1:\0\0\f4termname()\f1@@@get terminal name .\" .\" fileset_database@termname.3x CURS-ENG-A-MAN .\" $Header: tsearch.3c,v 72.5 94/11/15 09:56:53 ssa Exp $ .TA t .TH tsearch 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tsearch(\|), tfind(\|), tdelete(\|), twalk(\|) \- manage binary search trees .SH SYNOPSIS .C "#include " .PP .C "void *tsearch(" .nf .PD 0 .IP .C "const void *key," .C "void **rootp," .C "int (*compar)(const void *, const void *)" .P .C ");" .PD .PP .C "void *tfind(" .PD 0 .IP .C "const void *key," .C "void * const *rootp," .C "int (*compar)(const void *, const void *)" .P .C ");" .PD .PP .C "void *tdelete(" .PD 0 .IP .C "const void *key," .C "void **rootp," .C "int (*compar)(const void *, const void *)" .PP .C ");" .PD .PP .C "void twalk(" .PD 0 .IP .C "const void *root," .C "void (*action)(const void *, VISIT, int)" .PP .C ");" .PD .fi .SH DESCRIPTION .CR tsearch() , .CR tfind() , .CR tdelete() , and .C twalk() are routines for manipulating binary search trees. They are generalized from Knuth (6.2.2) Algorithms T and D. All comparisons are done with a user-supplied routine, .IR compar . This routine is called with two arguments, the pointers to the elements being compared. It returns an integer less than, equal to, or greater than 0, according to whether the first argument is to be considered less than, equal to or greater than the second argument. The comparison function need not compare every byte, so arbitrary data may be contained in the elements in addition to the values being compared. .PP .C tsearch() is used to build and access the tree. .I key is a pointer to an entry to be accessed or stored. If there is an entry in the tree equal to the value pointed to by .IR key , a pointer to the previous key associated with this found entry is returned. Otherwise, .I key is inserted, and a pointer to it returned. Note that since the value returned is a pointer to .I key and .I key itself is a pointer, the value returned is a pointer to a pointer. Only pointers are copied, so the calling routine must store the data. .I rootp points to a variable that points to the root of the tree. A .SM NULL value for the variable pointed to by .I rootp denotes an empty tree; in this case, the variable is set to point to the entry which will be at the root of the new tree. .PP Like .CR tsearch() , .C tfind() searches for an entry in the tree, returning a pointer to it if found. However, if it is not found, .C tfind() returns a .SM NULL pointer. The arguments for .C tfind() are the same as for .CR tsearch() . .PP .C tdelete() deletes a node from a binary search tree. Arguments are the same as for .CR tsearch() . The variable pointed to by .I rootp is changed if the deleted node was the root of the tree. .C tdelete() returns a pointer to the parent of the deleted node, or a .SM NULL pointer if the node is not found. .PP .C twalk() traverses a binary search tree. .I root is the root of the tree to be traversed. (Any node in a tree may be used as the root for a walk below that node.) .I action is the name of a routine to be invoked at each node. This routine is, in turn, called with three arguments: .RS .TP 3 \(bu First argument is the address of the node being visited. .TP \(bu Second argument is a value from an enumeration data type .C "typedef enum { preorder, postorder, endorder, leaf }" .C VISIT; (defined in the .RC < search.h > header file), depending on whether this is the first, second or third time that the node has been visited (during a depth-first, left-to-right traversal of the tree), or whether the node is a leaf. .TP \(bu Third argument is the level of the node in the tree, with the root being level zero. .RE .SH EXAMPLE The following code reads strings, and stores structures containing a pointer to each string and a count of its length. It then walks the tree, printing out the stored strings and their lengths in alphabetical order. .nf .IP .C "#include " .C "#include " .C "#include " .C "#include " .IP .C "struct element /* pointers to these are stored in the tree */" .C { .C " char *string;" .C " int length;" .C " };" .C "char string_space[10000]; /* space to store strings */" .C "struct element elements[500]; /* elements to store */" .C "struct element *root = NULL; /* this points to the root */" .C " .C "void print_node(void *, VISIT, int);" .C "int element_compare(const void *, const void *);" .IP .C "main( )" .C { .C " char *strptr = string_space;" .C " struct element *element_ptr = elements;" .C " struct element **ts_retval;" .IP .C " int i = 0;" .IP .C " while (gets(strptr) != NULL && i++ < 500)" .C " {" .IP .C " /* set element */" .C " element_ptr->string = strptr;" .C " element_ptr->length = strlen(strptr);" .IP .C " /* put element into the tree */" .C " ts_retval = (struct element **) tsearch((void *) element_ptr," .C " (void **) &root, element_compare);" .IP .C " if (*ts_retval == element_ptr)" .C " { .ift .ft 4 .ps +1 .ifn .ft 3 (void) printf("The element \e"%s\e" ", (*ts_retval)->string); (void) printf("has now been inserted into the tree\en"); .ps .ft .C " }" .C " else" .C " {" .ift .ft 4 .ps +1 .ifn .ft 3 (void) printf("The element \e"%s\e" ", (*ts_retval)->string); (void) printf("already existed in the tree\en"); .ps .ft .C " }" .IP .C " /* adjust pointers, so we don't overwrite tree */" .C " strptr += element_ptr->length + 1;" .C " element_ptr++;" .C " }" .C " twalk((void *) root, print_node);" .C } .C "/* This routine compares two elements, based on an" .C " alphabetical ordering of the string field. */" .C int .C "element_compare(elem1, elem2)" .C "void *elem1, *elem2;" .C { .C " return strcmp(((struct element *) elem1)->string," .C " ((struct element *) elem2)->string);" .C } .C "/* This routine prints out a node, the first time" .C " twalk encounters it. */" .C void .C "print_node(element, order, level)" .C "void *element;" .C "VISIT order;" .C "int level;" .C { .C " if (order == preorder || order == leaf)" .C " {" .ift .ft 4 .ps +1 .ifn .ft 3 (void) printf("string = %20s, length = %d\en", .ps .ft .C " (*(struct element **) element)->string," .C " (*(struct element **) element)->length);" .C " }" .C } .fi .RE .SH SEE ALSO bsearch(3C), hsearch(3C), lsearch(3C). .SH RETURN VALUE A .SM NULL pointer is returned by .C tsearch() if there is not enough space available to create a new node. .PP A .SM NULL pointer is returned by .CR tsearch() , .CR tfind() , and .C tdelete() if .I rootp is .SM NULL on entry. .PP If the datum is found, both .C tsearch() and .C tfind() return a pointer to it. If not, .C tfind() returns .SM NULL, and .C tsearch() returns a pointer to the inserted item. .SH WARNINGS The .I root argument to .C twalk() is one level of indirection less than the .I rootp arguments to .C tsearch() and .CR tdelete() . .PP Two nomenclatures are used to refer to the order in which tree nodes are visited. .C tsearch() uses preorder, postorder and endorder to respectively refer to visiting a node before any of its children, after its left child and before its right and after both its children. The alternate nomenclature uses preorder, inorder, and postorder to refer to the same visits, which could result in some confusion over the meaning of postorder. If the calling function alters the pointer to the root, results are unpredictable. .SH STANDARDS CONFORMANCE .CR tsearch() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR tdelete() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR tfind() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR twalk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4tsearch()\fP \- build and access a binary search tree@@@\f3tsearch(3C)\f1 .\" index@\f4tfind()\fP \- get data pointer for binary search tree@@@\f3tsearch(3C)\f1 .\" index@\f4tdelete()\fP \- delete a node from a binary search tree@@@\f3tsearch(3C)\f1 .\" index@\f4twalk()\fP \- traverse a binary search tree@@@\f3tsearch(3C)\f1 .\" index@build or access a binary search tree@@@\f3tsearch(3C)\f1 .\" index@access or build a binary search tree@@@\f3tsearch(3C)\f1 .\" index@get: data pointer for binary search tree@@@\f3tsearch(3C)\f1 .\" index@data pointer for binary search tree, get@@@\f3tsearch(3C)\f1 .\" index@pointer for binary search tree, get data@@@\f3tsearch(3C)\f1 .\" index@delete a node from a binary search tree@@@\f3tsearch(3C)\f1 .\" index@node from a binary search tree, delete a@@@\f3tsearch(3C)\f1 .\" index@traverse a binary search tree@@@\f3tsearch(3C)\f1 .\" index@manage a binary search tree@@@\f3tsearch(3C)\f1 .\" index@binary search tree, manage a@@@\f3tsearch(3C)\f1 .\" index@search tree, manage a binary@@@\f3tsearch(3C)\f1 .\" index@tree, manage a binary search@@@\f3tsearch(3C)\f1 .\" .\" toc@\f3tsearch(3C)\f1:\0\0\f4tsearch()\fP, \f4tfind()\fP, \f4tdelete()\fP, \f4twalk()\fP@@@manage binary search trees .\" toc@\f4tfind()\fP:\0\0manage binary search trees@@@see \f3tsearch(3C)\f1 .\" toc@\f4tdelete()\fP:\0\0manage binary search trees@@@see \f3tsearch(3C)\f1 .\" toc@\f4twalk()\fP:\0\0manage binary search trees@@@see \f3tsearch(3C)\f1 .\" .\" links@tsearch.3c tfind.3c .\" links@tsearch.3c tdelete.3c .\" links@tsearch.3c twalk.3c .\" .\" fileset_database@tsearch.3c PROGRAMING-MAN .\" $Header: tgetent.3x,v 76.3 95/08/23 17:45:17 ssa Exp $ .TA t .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH tgetent 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 tgetent .SH NAME tgetent, tgetflag, tgetnum, tgetstr, tgoto \(em \f3termcap\f1 database emulation (\f3TO BE WITHDRAWN\fP) .SH SYNOPSIS .C "#include " .P .C "int tgetent(char *\f2bp\fP, char *const \f2name\fP);" .P .C "int tgetflag(char \f2id\fP[2]);" .P .C "int tgetnum(char \f2id\fP[2]);" .P .C "char *tgetstr(char \f2id\fP[2], char **\f2area\fP);" .P .C "char *tgoto(char *const \f2cap\fP, int \f2col\fP, int \f2row\fP);" .SH DESCRIPTION The .Fn tgetent function looks up the \f3termcap\f1 entry for \f2name\f1. The emulation ignores the buffer pointer \f2bp\f1. .P The .Fn tgetflag function gets the boolean entry for \f2id\f1. .P The .Fn tgetnum function gets the numeric entry for \f2id\f1. .P The .Fn tgetstr function gets the string entry for \f2id\f1. If .I area is not a null pointer and does not point to a null pointer, .Fn tgetstr copies the string entry into the buffer pointed to by .I *area and advances the variable pointed to by .I area to the first byte after the copy of the string entry. .P The .Fn tgoto function instantiates .I col and .I row into .I cap and returns a pointer to the resulting string. .P All of the information available in the \f3terminfo\f1 database need not be available through these functions. .SH "RETURN VALUE" Upon successful completion, functions that return an integer return OK. Otherwise, they return ERR. .P Functions that return pointers return a null pointer on error. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are included as a conversion aid for programs that use the \f3termcap\f1 library. Their arguments are the same and the functions are emulated using the \f3terminfo\f1 database. .P These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .P Any terminal capabilities from the \f3terminfo\f1 database that cannot be retrieved using these interfaces can be retrieved using the interfaces described on the .Fn tigetflg page. .P Portable applications must use .Fn tputs to output the strings returned by .Fn tgetstr and .CR tgoto() . .SH "SEE ALSO" putc(), setupterm(), tigetflg(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3tgetent(3X)\f1:\0\0\f4tgetent()\f1, \f4tgetflag()\f1, \f4tgetnum()\f1, \f4tgetstr()\f1, \f4tgoto\f1@@@\f4termcap\f1 database emulation .\" toc@\f4tgetflag()\f1: \f4termcap\f1 database emulation@@@see \f3tgetent(3X)\f1 .\" toc@\f4tgetnum()\f1: \f4termcap\f1 database emulation@@@see \f3tgetent(3X)\f1 .\" toc@\f4tgetstr()\f1: \f4termcap\f1 database emulation@@@see \f3tgetent(3X)\f1 .\" toc@\f4tgoto()\f1: \f4termcap\f1 database emulation@@@see \f3tgetent(3X)\f1 .\" .\" index@\f4tgetent()\f1 \- \f4temcap\f1 database emulation@@@\f3tgetent(3X)\f1 .\" index@\f4tgetflag()\f1 \- \f4temcap\f1 database emulation@@@\f3tgetent(3X)\f1 .\" index@\f4tgetnum()\f1 \- \f4temcap\f1 database emulation@@@\f3tgetent(3X)\f1 .\" index@\f4tgetstr()\f1 \- \f4temcap\f1 database emulation@@@\f3tgetent(3X)\f1 .\" index@\f4tgoto()\f1 \- \f4temcap\f1 database emulation@@@\f3tgetent(3X)\f1 .\" index@\f4temcap\f1 database emulation@@@\f3tgetent(3X)\f1 .\" index@\f1database, \f4termcap\f1, emulation@@@\f3tgetent(3X)\f1 .\" index@\f1emulation of \f4termcap\f1 database@@@\f3tgetent(3X)\f1 .\" .\" fileset_database@tgetent.3x CURS-ENG-A-MAN .\" $Header: termcap.3x,v 76.1 95/08/23 17:41:19 ssa Exp $ .TA t .TH termcap 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tgetent(\|), tgetnum(\|), tgetflag(\|), tgetstr(\|), tgoto(\|), .ifn .br .ifn \0\0\0\0 tputs(\|) \- emulate /usr/share/lib/termcap access routines .SH SYNOPSIS .C "#include " .P .C "int tgetent(char *bp, const char *name);" .P .C "int tgetnum(const char *id);" .P .C "int tgetflag(const char *id);" .P .C "char *tgetstr(const char *id, char **area);" .P .C "char *tgoto(char *cm, int destcol, int destline);" .P .C "int tputs(char *cp, int affcnt, int (*outc)(int));" .SH DESCRIPTION These functions extract and use capabilities from the compiled terminal capability data bases (see .IR terminfo (4)). They are emulation routines that are provided as a part of the .IR curses (3X) library. .RS .TP 15 .CR tgetent() Extracts the compiled entry for terminal .I name into buffers accessible by the programmer. Unlike previous termcap routines, all capability strings (except cursor addressing and padding information) are already compiled and stored internally upon return from .CR tgetent() . The buffer pointer .I bp is redundant in the emulation, and is ignored. It should not be relied upon to point to meaningful information. .CR tgetent() returns \-1 if it cannot access the .I terminfo directory, 0 if there is no capability file for .I name, and 1 if all goes well. If a .CR TERMINFO environment variable is set, .CR tgetent() first looks for .CI TERMINFO/?/ name (where .CR ? is the first character of .IR name ), and if that file is not accessible, it looks for .CI /usr/share/lib/terminfo/?/ name\f1. .TP .CR tgetnum() Gets the numeric value of capability .I id, returning \-1 if it is not given for the terminal. .CR tgetnum() is useful only with capabilities having numeric values. .TP .CR tgetflag() Returns 1 if the specified capability is present in the terminal's entry, and 0 if it is not. .CR tgetflag() is useful only with capabilities that are boolean in nature (i.e. either present or missing in .IR terminfo (4)). .TP .CR tgetstr() Returns a pointer to the string value of capability .IR id . In addition, if .I area is not a NULL pointer, .CR tgetstr() places the capability in the buffer at .I area and advances the area pointer. The returned string capability is compiled except for cursor addressing and padding information. .CR tgetstr() is useful only with capabilities having string values. .TP .CR tgoto() Returns a cursor addressing string decoded from .I cm to go to column .I destcol in line .IR destline . (Programs that call .CR tgoto() should be sure to turn off the TAB3 bit or bits, since .CR tgoto() can now output a tab. See .IR termio (7)). Note that programs using .CR termcap should in general turn off TAB3 anyway since some terminals use Ctrl-I for other functions, such as nondestructive space.) If a .CR % sequence is given that is not understood, .CR tgoto() returns [OOPS]. .TP .CR tputs() Decodes the padding information of the string .IR cp . .I affcnt gives the number of lines affected by the operation, or 1 if this is not applicable. .I outc is a routine that is called with each character in turn. The .CR terminfo variable .I pad_char should contain a pad character to be used (from the .I pc capability) if a null .ifn (\f3^@\fP) .ift (\f4^@\fP) is inappropriate. .RE .SH WARNINGS These routines are not meant to be used by programs running in the background. .SH FILES .TP 42 .C "/usr/lib/libcurses.a -lcurses" library .TP .C /usr/share/lib/terminfo/?/* data bases .SH SEE ALSO ex(1), terminfo(4), termio(7). .\" index@\f4tgetent()\fP \- get compiled terminfo data base entry into buffer@@@\f3termcap(3X)\f1 .\" index@\f4tgetnum()\fP \- get numeric value of compiled terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgetflag()\fP \- get availability of compiled boolean terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgetstr()\fP \- get string value of compiled terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgoto()\fP \- get compiled terminal cursor addressing string@@@\f3termcap(3X)\f1 .\" index@\f4tputs()\fP \- decode terminal string padding information@@@\f3termcap(3X)\f1 .\" index@emulate \f2/etc/termcap\f1 access routines@@@\f3termcap(3X)\f1 .\" index@\f2/etc/termcap\f1 access routines, emulate@@@\f3termcap(3X)\f1 .\" index@\f4termcap()\fP access routines, emulate \f2/etc/\f1@@@\f3termcap(3X)\f1 .\" index@routines, emulate \f2/etc/termcap\f1 access@@@\f3termcap(3X)\f1 .\" .\" toc@\f3termcap(3X)\f1:\0\0\f4tgetent()\fP, \f4tgetnum()\fP, \f4tgetflag()\fP, \f4tgetstr()\fP, \f4tgoto()\fP, \f4tputs()\fP@@@emulate \f2/etc/termcap\f1 access routines .\" toc@\f4tgetent()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetnum()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetflag()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetstr()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgoto()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tputs()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" .\" links@termcap.3x tgetnum.3x .\" links@termcap.3x tgetflag.3x .\" links@termcap.3x tgetstr.3x .\" links@termcap.3x tgoto.3x .\" .\" fileset_database@termcap.3x PROGRAMING-MAN .\" $Header: termcap.3x,v 76.1 95/08/23 17:41:19 ssa Exp $ .TA t .TH termcap 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tgetent(\|), tgetnum(\|), tgetflag(\|), tgetstr(\|), tgoto(\|), .ifn .br .ifn \0\0\0\0 tputs(\|) \- emulate /usr/share/lib/termcap access routines .SH SYNOPSIS .C "#include " .P .C "int tgetent(char *bp, const char *name);" .P .C "int tgetnum(const char *id);" .P .C "int tgetflag(const char *id);" .P .C "char *tgetstr(const char *id, char **area);" .P .C "char *tgoto(char *cm, int destcol, int destline);" .P .C "int tputs(char *cp, int affcnt, int (*outc)(int));" .SH DESCRIPTION These functions extract and use capabilities from the compiled terminal capability data bases (see .IR terminfo (4)). They are emulation routines that are provided as a part of the .IR curses (3X) library. .RS .TP 15 .CR tgetent() Extracts the compiled entry for terminal .I name into buffers accessible by the programmer. Unlike previous termcap routines, all capability strings (except cursor addressing and padding information) are already compiled and stored internally upon return from .CR tgetent() . The buffer pointer .I bp is redundant in the emulation, and is ignored. It should not be relied upon to point to meaningful information. .CR tgetent() returns \-1 if it cannot access the .I terminfo directory, 0 if there is no capability file for .I name, and 1 if all goes well. If a .CR TERMINFO environment variable is set, .CR tgetent() first looks for .CI TERMINFO/?/ name (where .CR ? is the first character of .IR name ), and if that file is not accessible, it looks for .CI /usr/share/lib/terminfo/?/ name\f1. .TP .CR tgetnum() Gets the numeric value of capability .I id, returning \-1 if it is not given for the terminal. .CR tgetnum() is useful only with capabilities having numeric values. .TP .CR tgetflag() Returns 1 if the specified capability is present in the terminal's entry, and 0 if it is not. .CR tgetflag() is useful only with capabilities that are boolean in nature (i.e. either present or missing in .IR terminfo (4)). .TP .CR tgetstr() Returns a pointer to the string value of capability .IR id . In addition, if .I area is not a NULL pointer, .CR tgetstr() places the capability in the buffer at .I area and advances the area pointer. The returned string capability is compiled except for cursor addressing and padding information. .CR tgetstr() is useful only with capabilities having string values. .TP .CR tgoto() Returns a cursor addressing string decoded from .I cm to go to column .I destcol in line .IR destline . (Programs that call .CR tgoto() should be sure to turn off the TAB3 bit or bits, since .CR tgoto() can now output a tab. See .IR termio (7)). Note that programs using .CR termcap should in general turn off TAB3 anyway since some terminals use Ctrl-I for other functions, such as nondestructive space.) If a .CR % sequence is given that is not understood, .CR tgoto() returns [OOPS]. .TP .CR tputs() Decodes the padding information of the string .IR cp . .I affcnt gives the number of lines affected by the operation, or 1 if this is not applicable. .I outc is a routine that is called with each character in turn. The .CR terminfo variable .I pad_char should contain a pad character to be used (from the .I pc capability) if a null .ifn (\f3^@\fP) .ift (\f4^@\fP) is inappropriate. .RE .SH WARNINGS These routines are not meant to be used by programs running in the background. .SH FILES .TP 42 .C "/usr/lib/libcurses.a -lcurses" library .TP .C /usr/share/lib/terminfo/?/* data bases .SH SEE ALSO ex(1), terminfo(4), termio(7). .\" index@\f4tgetent()\fP \- get compiled terminfo data base entry into buffer@@@\f3termcap(3X)\f1 .\" index@\f4tgetnum()\fP \- get numeric value of compiled terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgetflag()\fP \- get availability of compiled boolean terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgetstr()\fP \- get string value of compiled terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgoto()\fP \- get compiled terminal cursor addressing string@@@\f3termcap(3X)\f1 .\" index@\f4tputs()\fP \- decode terminal string padding information@@@\f3termcap(3X)\f1 .\" index@emulate \f2/etc/termcap\f1 access routines@@@\f3termcap(3X)\f1 .\" index@\f2/etc/termcap\f1 access routines, emulate@@@\f3termcap(3X)\f1 .\" index@\f4termcap()\fP access routines, emulate \f2/etc/\f1@@@\f3termcap(3X)\f1 .\" index@routines, emulate \f2/etc/termcap\f1 access@@@\f3termcap(3X)\f1 .\" .\" toc@\f3termcap(3X)\f1:\0\0\f4tgetent()\fP, \f4tgetnum()\fP, \f4tgetflag()\fP, \f4tgetstr()\fP, \f4tgoto()\fP, \f4tputs()\fP@@@emulate \f2/etc/termcap\f1 access routines .\" toc@\f4tgetent()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetnum()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetflag()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetstr()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgoto()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tputs()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" .\" links@termcap.3x tgetnum.3x .\" links@termcap.3x tgetflag.3x .\" links@termcap.3x tgetstr.3x .\" links@termcap.3x tgoto.3x .\" .\" fileset_database@termcap.3x PROGRAMING-MAN .\" $Header: termcap.3x,v 76.1 95/08/23 17:41:19 ssa Exp $ .TA t .TH termcap 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tgetent(\|), tgetnum(\|), tgetflag(\|), tgetstr(\|), tgoto(\|), .ifn .br .ifn \0\0\0\0 tputs(\|) \- emulate /usr/share/lib/termcap access routines .SH SYNOPSIS .C "#include " .P .C "int tgetent(char *bp, const char *name);" .P .C "int tgetnum(const char *id);" .P .C "int tgetflag(const char *id);" .P .C "char *tgetstr(const char *id, char **area);" .P .C "char *tgoto(char *cm, int destcol, int destline);" .P .C "int tputs(char *cp, int affcnt, int (*outc)(int));" .SH DESCRIPTION These functions extract and use capabilities from the compiled terminal capability data bases (see .IR terminfo (4)). They are emulation routines that are provided as a part of the .IR curses (3X) library. .RS .TP 15 .CR tgetent() Extracts the compiled entry for terminal .I name into buffers accessible by the programmer. Unlike previous termcap routines, all capability strings (except cursor addressing and padding information) are already compiled and stored internally upon return from .CR tgetent() . The buffer pointer .I bp is redundant in the emulation, and is ignored. It should not be relied upon to point to meaningful information. .CR tgetent() returns \-1 if it cannot access the .I terminfo directory, 0 if there is no capability file for .I name, and 1 if all goes well. If a .CR TERMINFO environment variable is set, .CR tgetent() first looks for .CI TERMINFO/?/ name (where .CR ? is the first character of .IR name ), and if that file is not accessible, it looks for .CI /usr/share/lib/terminfo/?/ name\f1. .TP .CR tgetnum() Gets the numeric value of capability .I id, returning \-1 if it is not given for the terminal. .CR tgetnum() is useful only with capabilities having numeric values. .TP .CR tgetflag() Returns 1 if the specified capability is present in the terminal's entry, and 0 if it is not. .CR tgetflag() is useful only with capabilities that are boolean in nature (i.e. either present or missing in .IR terminfo (4)). .TP .CR tgetstr() Returns a pointer to the string value of capability .IR id . In addition, if .I area is not a NULL pointer, .CR tgetstr() places the capability in the buffer at .I area and advances the area pointer. The returned string capability is compiled except for cursor addressing and padding information. .CR tgetstr() is useful only with capabilities having string values. .TP .CR tgoto() Returns a cursor addressing string decoded from .I cm to go to column .I destcol in line .IR destline . (Programs that call .CR tgoto() should be sure to turn off the TAB3 bit or bits, since .CR tgoto() can now output a tab. See .IR termio (7)). Note that programs using .CR termcap should in general turn off TAB3 anyway since some terminals use Ctrl-I for other functions, such as nondestructive space.) If a .CR % sequence is given that is not understood, .CR tgoto() returns [OOPS]. .TP .CR tputs() Decodes the padding information of the string .IR cp . .I affcnt gives the number of lines affected by the operation, or 1 if this is not applicable. .I outc is a routine that is called with each character in turn. The .CR terminfo variable .I pad_char should contain a pad character to be used (from the .I pc capability) if a null .ifn (\f3^@\fP) .ift (\f4^@\fP) is inappropriate. .RE .SH WARNINGS These routines are not meant to be used by programs running in the background. .SH FILES .TP 42 .C "/usr/lib/libcurses.a -lcurses" library .TP .C /usr/share/lib/terminfo/?/* data bases .SH SEE ALSO ex(1), terminfo(4), termio(7). .\" index@\f4tgetent()\fP \- get compiled terminfo data base entry into buffer@@@\f3termcap(3X)\f1 .\" index@\f4tgetnum()\fP \- get numeric value of compiled terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgetflag()\fP \- get availability of compiled boolean terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgetstr()\fP \- get string value of compiled terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgoto()\fP \- get compiled terminal cursor addressing string@@@\f3termcap(3X)\f1 .\" index@\f4tputs()\fP \- decode terminal string padding information@@@\f3termcap(3X)\f1 .\" index@emulate \f2/etc/termcap\f1 access routines@@@\f3termcap(3X)\f1 .\" index@\f2/etc/termcap\f1 access routines, emulate@@@\f3termcap(3X)\f1 .\" index@\f4termcap()\fP access routines, emulate \f2/etc/\f1@@@\f3termcap(3X)\f1 .\" index@routines, emulate \f2/etc/termcap\f1 access@@@\f3termcap(3X)\f1 .\" .\" toc@\f3termcap(3X)\f1:\0\0\f4tgetent()\fP, \f4tgetnum()\fP, \f4tgetflag()\fP, \f4tgetstr()\fP, \f4tgoto()\fP, \f4tputs()\fP@@@emulate \f2/etc/termcap\f1 access routines .\" toc@\f4tgetent()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetnum()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetflag()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetstr()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgoto()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tputs()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" .\" links@termcap.3x tgetnum.3x .\" links@termcap.3x tgetflag.3x .\" links@termcap.3x tgetstr.3x .\" links@termcap.3x tgoto.3x .\" .\" fileset_database@termcap.3x PROGRAMING-MAN .\" $Header: termcap.3x,v 76.1 95/08/23 17:41:19 ssa Exp $ .TA t .TH termcap 3X .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tgetent(\|), tgetnum(\|), tgetflag(\|), tgetstr(\|), tgoto(\|), .ifn .br .ifn \0\0\0\0 tputs(\|) \- emulate /usr/share/lib/termcap access routines .SH SYNOPSIS .C "#include " .P .C "int tgetent(char *bp, const char *name);" .P .C "int tgetnum(const char *id);" .P .C "int tgetflag(const char *id);" .P .C "char *tgetstr(const char *id, char **area);" .P .C "char *tgoto(char *cm, int destcol, int destline);" .P .C "int tputs(char *cp, int affcnt, int (*outc)(int));" .SH DESCRIPTION These functions extract and use capabilities from the compiled terminal capability data bases (see .IR terminfo (4)). They are emulation routines that are provided as a part of the .IR curses (3X) library. .RS .TP 15 .CR tgetent() Extracts the compiled entry for terminal .I name into buffers accessible by the programmer. Unlike previous termcap routines, all capability strings (except cursor addressing and padding information) are already compiled and stored internally upon return from .CR tgetent() . The buffer pointer .I bp is redundant in the emulation, and is ignored. It should not be relied upon to point to meaningful information. .CR tgetent() returns \-1 if it cannot access the .I terminfo directory, 0 if there is no capability file for .I name, and 1 if all goes well. If a .CR TERMINFO environment variable is set, .CR tgetent() first looks for .CI TERMINFO/?/ name (where .CR ? is the first character of .IR name ), and if that file is not accessible, it looks for .CI /usr/share/lib/terminfo/?/ name\f1. .TP .CR tgetnum() Gets the numeric value of capability .I id, returning \-1 if it is not given for the terminal. .CR tgetnum() is useful only with capabilities having numeric values. .TP .CR tgetflag() Returns 1 if the specified capability is present in the terminal's entry, and 0 if it is not. .CR tgetflag() is useful only with capabilities that are boolean in nature (i.e. either present or missing in .IR terminfo (4)). .TP .CR tgetstr() Returns a pointer to the string value of capability .IR id . In addition, if .I area is not a NULL pointer, .CR tgetstr() places the capability in the buffer at .I area and advances the area pointer. The returned string capability is compiled except for cursor addressing and padding information. .CR tgetstr() is useful only with capabilities having string values. .TP .CR tgoto() Returns a cursor addressing string decoded from .I cm to go to column .I destcol in line .IR destline . (Programs that call .CR tgoto() should be sure to turn off the TAB3 bit or bits, since .CR tgoto() can now output a tab. See .IR termio (7)). Note that programs using .CR termcap should in general turn off TAB3 anyway since some terminals use Ctrl-I for other functions, such as nondestructive space.) If a .CR % sequence is given that is not understood, .CR tgoto() returns [OOPS]. .TP .CR tputs() Decodes the padding information of the string .IR cp . .I affcnt gives the number of lines affected by the operation, or 1 if this is not applicable. .I outc is a routine that is called with each character in turn. The .CR terminfo variable .I pad_char should contain a pad character to be used (from the .I pc capability) if a null .ifn (\f3^@\fP) .ift (\f4^@\fP) is inappropriate. .RE .SH WARNINGS These routines are not meant to be used by programs running in the background. .SH FILES .TP 42 .C "/usr/lib/libcurses.a -lcurses" library .TP .C /usr/share/lib/terminfo/?/* data bases .SH SEE ALSO ex(1), terminfo(4), termio(7). .\" index@\f4tgetent()\fP \- get compiled terminfo data base entry into buffer@@@\f3termcap(3X)\f1 .\" index@\f4tgetnum()\fP \- get numeric value of compiled terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgetflag()\fP \- get availability of compiled boolean terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgetstr()\fP \- get string value of compiled terminal capability@@@\f3termcap(3X)\f1 .\" index@\f4tgoto()\fP \- get compiled terminal cursor addressing string@@@\f3termcap(3X)\f1 .\" index@\f4tputs()\fP \- decode terminal string padding information@@@\f3termcap(3X)\f1 .\" index@emulate \f2/etc/termcap\f1 access routines@@@\f3termcap(3X)\f1 .\" index@\f2/etc/termcap\f1 access routines, emulate@@@\f3termcap(3X)\f1 .\" index@\f4termcap()\fP access routines, emulate \f2/etc/\f1@@@\f3termcap(3X)\f1 .\" index@routines, emulate \f2/etc/termcap\f1 access@@@\f3termcap(3X)\f1 .\" .\" toc@\f3termcap(3X)\f1:\0\0\f4tgetent()\fP, \f4tgetnum()\fP, \f4tgetflag()\fP, \f4tgetstr()\fP, \f4tgoto()\fP, \f4tputs()\fP@@@emulate \f2/etc/termcap\f1 access routines .\" toc@\f4tgetent()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetnum()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetflag()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgetstr()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tgoto()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" toc@\f4tputs()\fP:\0\0emulate \f2/etc/termcap\f1 access routines@@@see \f3termcap(3X)\f1 .\" .\" links@termcap.3x tgetnum.3x .\" links@termcap.3x tgetflag.3x .\" links@termcap.3x tgetstr.3x .\" links@termcap.3x tgoto.3x .\" .\" fileset_database@termcap.3x PROGRAMING-MAN ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED. ...\" ******************************************************************** ...\" * ...\" COPYRIGHT (c) 1991 BY DIGITAL EQUIPMENT CORPORATION, * ...\" Maynard, Massachusetts * ...\" All Rights Reserved. * ...\" * ...\" This document is furnished under a license and may be used and * ...\" copied only in accordance with the terms of such license and with * ...\" the inclusion of the above copyright notice. No title to or * ...\" ownership of the document is hereby transferred. * ...\" * ...\" The information in this document is subject to change without * ...\" notice and should not be construed as a commitment by Digital * ...\" Equipment Corporation. * ...\" * ...\" ******************************************************************** ...\".nr H1 1 ...\" .rm zA .rm zZ .TH thr_intro 3 .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .SH NAME .PP \*Lthr_intro\*O - Introduction to DCE Threads .wH "" .SH "DESCRIPTION" .PP DCE Threads is a set of routines that you can call to create a multithreaded program. Multithreading is used to improve the performance of a program. Routines implemented by DCE Threads that are not specified by Draft 4 of the POSIX 1003.4a standard are indicated by an \*L_np\*O suffix on the name. These routines are new primitives. .iX "new primitive routines" .iX "non-portable routines" .iX "np suffix" .iX "suffix" "np" .PP The Threads routines sort alphabetically in the reference pages; however, the tables in this introduction list the routines in the following functional groups: .ad l .ML .LI Threads Routines ...\" .zA "defect,7104,R1.0.2,Threads Initializing Routines" .LI Routines that Implicitly Initialize Threads Package .zZ "defect,7104,R1.0.2,Threads Initializing Routines" ...\" .LI Attributes Object Routines .LI Mutex Routines .LI Condition Variable Routines .LI Thread-Specific Data Routines .LI Threads Cancellation Routines .LI Threads Priority and Scheduling Routines .LI Cleanup Routines .LI The \*Latfork(\|)\*O Routine ...\" .LI ...\" The \*Lexceptions(\|)\*O Routine .LI Signal Handling Routines ...\" ...\" .LI ...\" Data Types ...\" .LE .ad n .sp .4i ...\" .TB "Threads Routines" .ad l .ne 4.0i .TS center tab (@) box; cB s lB | lB lB | l. Threads Routines _ Routine@Description _ pthread_create(\|)@T{ Creates a thread T} pthread_delay_np(\|)\ @T{ Causes a thread to wait for a period of time T} pthread_detach(\|)\ @T{ Marks a thread for deletion T} .zA"defect,5118,R1.0.2, routine in code missing from docs" pthread_equal(\|)\ @T{ Compares one thread identifier to another thread identifier T} .zZ"defect,5118,R1.0.2, routine in code missing from docs" pthread_exit(\|)\ @T{ Terminates the calling thread T} pthread_join(\|)\ @T{ Causes the calling thread to wait for the termination of a specified thread T} pthread_once(\|)\ @T{ Calls an initialization routine to be executed only once T} pthread_self(\|)\ @T{ Obtains the identifier of the current thread T} pthread_yield(\|)\ @T{ Notifies the scheduler that the current thread will release its processor to other threads of the same or higher priority T} .TE .ad b ...\" ...\" ...\" ...\" defect,7104,R1.0.2,Initializing Routines ...\" .sp .4i ...\" The following DCE Threads routines will, when called, implicitly perform any necessary initialization of the Threads package. Thus any application using DCE Threads should call one of the following routines before calling any other Threads routines, in order to ensure that the package is properly initialized. .PP ...\" ...\" ...\" .TB "Routines that Cause Initialization" .zA "defect,7104,R1.0.2,Threads Initializing Routines" .ad l .ne 6.0i .TS center tab (@) box; cB s lB | lB lB | l. Routines that Implicitly Perform Threads Initialization _ Routine@Description _ pthread_attr_create(\|)\ @T{ Creates a thread attributes object T} pthread_create(\|)\ @T{ Creates a thread T} pthread_self(\|)\ @T{ Obtains the identifier of the current thread T} pthread_setprio(\|)\ @T{ Changes the scheduling priority attribute T} pthread_getprio(\|)\ @T{ Obtains the scheduling priority attribute T} pthread_setscheduler(\|)\ @T{ Changes the scheduling policy attribute T} pthread_getscheduler(\|)\ @T{ Obtains the scheduling policy attribute T} pthread_once(\|)\ @T{ Calls an initialization routine to be executed only once T} pthread_keycreate(\|)\ @T{ Generates a unique thread-specific data key value T} pthread_mutexattr_create(\|)\ @T{ Creates a mutex attributes object T} pthread_mutex_init(\|)\ @T{ Creates a mutex T} pthread_condattr_create(\|)\ @T{ Creates a condition variable attributes object T} pthread_cond_init(\|)\ @T{ Creates a condition variable T} pthread_testcancel(\|)\ @T{ Requests delivery of a pending cancel T} pthread_setcancel(\|)\ @T{ Enables or disables the current thread's general cancelability T} pthread_setasynccancel(\|)\ @T{ Enables or disables the current thread's asynchronous cancelability T} pthread_delay_np(\|)\ @T{ Causes a thread to wait for a period of time T} .TE .ad b ...\" .zZ "defect,7104,R1.0.2,Threads Initializing Routines" ...\" ...\" defect,7104,R1.0.2,Initializing Routines ...\" ...\" ...\" .sp .4i .ne 1.5i ...\" .TB "Attributes Object Routines" .ad l .TS center tab (@) box; cB s lB | lB lB | l. Attributes Object Routines _ Routine@Description _ pthread_attr_create(\|)\ @T{ Creates a thread attributes object T} pthread_attr_delete(\|)\ @T{ Deletes a thread attributes object T} pthread_attr_getinheritsched(\|)\ @T{ Obtains the inherit scheduling attribute T} pthread_attr_getprio(\|)\ @T{ Obtains the scheduling priority attribute T} pthread_attr_getsched(\|)\ @T{ Obtains the scheduling policy attribute T} pthread_attr_getstacksize(\|)\ @T{ Obtains the stacksize attribute T} pthread_attr_setinheritsched(\|)\ @T{ Changes the inherit scheduling attribute T} pthread_attr_setprio(\|)\ @T{ Changes the scheduling priority attribute T} pthread_attr_setsched(\|)\ @T{ Changes the scheduling policy attribute T} pthread_attr_setstacksize(\|)\ @T{ Changes the stacksize attribute T} pthread_condattr_create(\|)\ @Creates a condition variable attributes object pthread_condattr_delete(\|)\ @T{ Deletes a condition variable attributes object T} pthread_mutexattr_create(\|)\ @T{ Creates a mutex attributes object T} pthread_mutexattr_delete(\|)\@T{ Deletes a mutex attributes object T} pthread_mutexattr_getkind_np(\|)\ @T{ Obtains the mutex type attribute T} pthread_mutexattr_setkind_np(\|)\ @T{ Changes the mutex type attribute T} .TE .ad b .sp .4i .ne 2.5i ...\" .TB "Mutex Routines" .ad l .TS center tab (@) box; cB s lB | lB lB | l. Mutex Routines _ Routine@Description _ pthread_lock_global_np(\|)\ @Locks a global mutex pthread_mutex_destroy(\|)\ @Deletes a mutex pthread_mutex_init(\|)\ @Creates a mutex pthread_mutex_lock(\|)\ @T{ Locks a mutex and waits if the mutex is already locked T} pthread_mutex_trylock(\|)\ @T{ Locks a mutex and returns if the mutex is already locked T} pthread_mutex_unlock(\|)\ @Unlocks a mutex pthread_unlock_global_np(\|)\ @Unlocks a global mutex .TE .ad b .PP .sp .4i .ne 2i ...\" .TB "Condition Variable Routines" .ad l .TS expand tab (@) box; cB s lB | lB lB | l. Condition Variable Routines _ Routine@Description _ pthread_cond_broadcast(\|)\ @Wakes all threads waiting on a condition variable pthread_cond_destroy(\|)\ @Deletes a condition variable pthread_cond_init(\|)\ @Creates a condition variable pthread_cond_signal(\|)\ @Wakes one thread waiting on a condition variable pthread_cond_timedwait(\|)\ @Causes a thread to wait for a specified period of time for a @condition variable to be signaled or broadcast pthread_cond_wait(\|)\ @T{ Causes a thread to wait for a condition variable to be signaled or broadcast T} pthread_get_expiration_np(\|)\ @Obtains a value representing a desired expiration time .TE .ad b .sp .4i .ne 2i ...\" .TB "Thread-Specific Data" .ad l .TS center tab (@) box; cB s lB | lB lB | l. Thread-Specific Data _ Routine@Description _ pthread_getspecific(\|)\ @Obtains the thread-specific data associated with the specified key pthread_keycreate(\|)\ @Generates a unique thread-specific data key value pthread_setspecific(\|)\ @T{ Sets the thread-specific data associated with the specified key T} .TE .ad b .sp .4i .ne 3.0i ...\" .TB "Threads Cancellation Routines" .ad l .TS expand tab (@) box; cB s lB | lB lB | l. Threads Cancellation Routines _ Routine@Description _ pthread_cancel(\|)\ @Allows a thread to request termination pthread_setasynccancel(\|)\ @T{ Enables or disables the current thread's asynchronous cancelability T} pthread_setcancel(\|)\ @Enables or disables the current thread's general cancelability pthread_signal_to_cancel_np(\|) @Cancels a thread if a signal is received by the process pthread_testcancel(\|)\ @Requests delivery of a pending cancel .TE .ad b .sp .4i .ne 1.5i ...\" .TB "Threads Priority and Scheduling Routines" .ad l .TS center tab (@) box; cB s lB | lB lB | l. Threads Priority and Scheduling Routines _ Routine@Description _ pthread_getprio(\|)\ @Obtains the current priority of a thread pthread_getscheduler(\|)\ @Obtains the current scheduling policy of a thread pthread_setprio(\|)\ @Changes the current priority of a thread pthread_setscheduler(\|)\ @Changes the current scheduling policy and priority of a thread .TE .ad b .sp .4i .ne 1.5i ...\" .TB "Cleanup Routines" .ad l .TS center tab (@) box; cB s lB | lB lB | l. Cleanup Routines _ Routine@Description _ pthread_cleanup_pop(\|)\ @Removes a cleanup handler from the stack pthread_cleanup_push(\|)\ @Establishes a cleanup handler .TE .ad b .sp .4i .ne 1.5i ...\" .TB "The atfork(\|) Routine" .TS center tab (@) box; cB s lB | lB. The atfork(\|) Routine _ Routine@Description _ .T& lB | l. atfork(\|)\ @Arranges for fork cleanup handling .TE .sp .4i .ne 1.5i ...\" .TB "Exceptions in DCE Threads" ...\" .TS ...\" center tab (@) box; ...\" cB s ...\" lB | lB. ...\" Exceptions in DCE Threads ...\" _ ...\" Routine@Description ...\" _ ...\" .T& ...\" lB | l. ...\" exceptions(\|)\ @Describes exception handling in DCE Threads ...\" .TE ...\" ...\" .zA "defect,7282,R1.0.2, Added new routine (was in code but not in doc)" .sp .4i .ne 1.5i ...\" .TS center tab (@) box; cB s lB | lB lB | l. Signal Handling Routines _ Routine@Description _ sigaction(\|)\ @Specifies action to take on receipt of signal sigpending(\|)\ @Examines pending signals sigprocmask(\|)\ @Sets the current signal mask sigwait(\|)\ @Causes thread to wait for asynchronous signal .TE ...\" ...\" .zZ "defect,7282,R1.0.2, Added new routine (was in code but not in doc)" .\" $Header: tigetflag.3x,v 76.2 95/08/01 14:55:09 ssa Exp $ .TA t .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH tigetflag 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 tigetflag .SH NAME tigetflag, tigetnum, tigetstr, tparm \(em retrieve capabilities from the \f3terminfo\f1 database .SH SYNOPSIS .C "#include " .P .C "int tigetflag(char *\f2capname\fP);" .P .C "int tigetnum(char *\f2capname\fP);" .P .C "char *tigetstr(char *\f2capname\fP);" .P .C "char *tparm(char *\f2cap\fP, long \f2p1\fP, long \f2p2\fP, long \f2p3\fP, long \f2p4\fP," .br .C " long \f2p5\fP, long \f2p6\fP, long \f2p7\fP, long \f2p8\fP, long \f2p9\fP);" .SH DESCRIPTION The .CR tigetflag() , .CR tigetnum() , and .Fn tigetstr functions obtain boolean, numeric and string capabilities, respectively, from the selected record of the \f3terminfo\f1 database. For each capability, the value to use as \f2capname\f1 appears in the .B Capname column in the table in \f3Defined Capabilities\f1 in terminfo(4). .P The .Fn tparm function takes as .I cap a string capability. If .I cap is parameterised (as described in \f3Parameterised Strings\f1 in terminfo(4)), .Fn tparm resolves the parameterisation. If the parameterised string refers to parameters \f4%p1\f1 through \f4%p9\f1, then .Fn tparm substitutes the values of \f2p1\f1 through \f2p9\fP, respectively. .SH "RETURN VALUE" Upon successful completion, .CR tigetflg() , .Fn tigetnum and .Fn tigetstr return the specified capability. The .Fn tigetflag function returns \(mi1 if \f2capname\f1 is not a boolean capability. The .Fn tigetnum function returns \(mi2 if \f2capname\f1 is not a numeric capability. The .Fn tigetstr function returns (\f3char *\f1)\(mi1 if \f2capname\f1 is not a string capability. .P Upon successful completion, .Fn tparm returns \f2str\f1 with parameterisation resolved. Otherwise, it returns a null pointer. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" For parameterised string capabilities, the application should pass the return value from .Fn tigetstr to .CR tparm() , as described above. .P Applications intending to send terminal capabilities directly to the terminal (which should only be done using .Fn tputs or .CR putp() ) instead of using Curses, normally should obey the following rules: .RS .TP 3 .C \(bu Call .Fn reset_shell_mode to restore the display modes before exiting. .TP .C \(bu If using cursor addressing, output \f3enter_ca_mode\f1 upon startup and output \f3exit_ca_mode\f1 before exiting. .TP .C \(bu If using shell escapes, output .B exit_ca_mode and call .Fn reset_shell_mode before calling the shell; call .Fn reset_prog_mode and output .I enter_ca_mode after returning from the shell. .RE .P All parameterised terminal capabilities defined in this document can be passed to .CR tparm() . Some implementations create their own capabilities, create capabilities for non-terminal devices, and redefine the capabilities in this document. These practices are non-conforming because it may be that .Fn tparm cannot parse these user-defined strings. .SH "SEE ALSO" def_prog_mode(), tgetent(), putp(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3tigetflag(3X)\f1:\0\0\f4tigetflag()\f1, \f4tigetnum()\f1, \f4tigetstr()\f1, \f4tparm()\f1\n@@@retrieve capabilities from the \f4terminfo\f1 database .\" toc@\f4tigetnum()\f1: retrieve capabilities from the \f4terminfo\f1 database@@@see \f3tigetflag(3X)\f1 .\" toc@\f4tigetstr()\f1: retrieve capabilities from the \f4terminfo\f1 database@@@see \f3tigetflag(3X)\f1 .\" toc@\f4tparm()\f1: retrieve capabilities from the \f4terminfo\f1 database@@@see \f3tigetflag(3X)\f1 .\" .\" index@\f4tigetflag()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f4tigetnum()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f4tigetstr()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f4tparm()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f1retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f1retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f1\f4terminfo\f1 database, retrieve capabilities from@@@\f3tigetflag(3X)\f1 .\" index@\f1capabilities, retrieve from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" .\" links@tigetflag.3x tigetnum.3x .\" links@tigetflag.3x tigetstr.3x .\" links@tigetflag.3x tparm.3x .\" .\" fileset_database@tigetflag.3x CURS-ENG-A-MAN .\" $Header: tigetflag.3x,v 76.2 95/08/01 14:55:09 ssa Exp $ .TA t .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH tigetflag 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 tigetflag .SH NAME tigetflag, tigetnum, tigetstr, tparm \(em retrieve capabilities from the \f3terminfo\f1 database .SH SYNOPSIS .C "#include " .P .C "int tigetflag(char *\f2capname\fP);" .P .C "int tigetnum(char *\f2capname\fP);" .P .C "char *tigetstr(char *\f2capname\fP);" .P .C "char *tparm(char *\f2cap\fP, long \f2p1\fP, long \f2p2\fP, long \f2p3\fP, long \f2p4\fP," .br .C " long \f2p5\fP, long \f2p6\fP, long \f2p7\fP, long \f2p8\fP, long \f2p9\fP);" .SH DESCRIPTION The .CR tigetflag() , .CR tigetnum() , and .Fn tigetstr functions obtain boolean, numeric and string capabilities, respectively, from the selected record of the \f3terminfo\f1 database. For each capability, the value to use as \f2capname\f1 appears in the .B Capname column in the table in \f3Defined Capabilities\f1 in terminfo(4). .P The .Fn tparm function takes as .I cap a string capability. If .I cap is parameterised (as described in \f3Parameterised Strings\f1 in terminfo(4)), .Fn tparm resolves the parameterisation. If the parameterised string refers to parameters \f4%p1\f1 through \f4%p9\f1, then .Fn tparm substitutes the values of \f2p1\f1 through \f2p9\fP, respectively. .SH "RETURN VALUE" Upon successful completion, .CR tigetflg() , .Fn tigetnum and .Fn tigetstr return the specified capability. The .Fn tigetflag function returns \(mi1 if \f2capname\f1 is not a boolean capability. The .Fn tigetnum function returns \(mi2 if \f2capname\f1 is not a numeric capability. The .Fn tigetstr function returns (\f3char *\f1)\(mi1 if \f2capname\f1 is not a string capability. .P Upon successful completion, .Fn tparm returns \f2str\f1 with parameterisation resolved. Otherwise, it returns a null pointer. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" For parameterised string capabilities, the application should pass the return value from .Fn tigetstr to .CR tparm() , as described above. .P Applications intending to send terminal capabilities directly to the terminal (which should only be done using .Fn tputs or .CR putp() ) instead of using Curses, normally should obey the following rules: .RS .TP 3 .C \(bu Call .Fn reset_shell_mode to restore the display modes before exiting. .TP .C \(bu If using cursor addressing, output \f3enter_ca_mode\f1 upon startup and output \f3exit_ca_mode\f1 before exiting. .TP .C \(bu If using shell escapes, output .B exit_ca_mode and call .Fn reset_shell_mode before calling the shell; call .Fn reset_prog_mode and output .I enter_ca_mode after returning from the shell. .RE .P All parameterised terminal capabilities defined in this document can be passed to .CR tparm() . Some implementations create their own capabilities, create capabilities for non-terminal devices, and redefine the capabilities in this document. These practices are non-conforming because it may be that .Fn tparm cannot parse these user-defined strings. .SH "SEE ALSO" def_prog_mode(), tgetent(), putp(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3tigetflag(3X)\f1:\0\0\f4tigetflag()\f1, \f4tigetnum()\f1, \f4tigetstr()\f1, \f4tparm()\f1\n@@@retrieve capabilities from the \f4terminfo\f1 database .\" toc@\f4tigetnum()\f1: retrieve capabilities from the \f4terminfo\f1 database@@@see \f3tigetflag(3X)\f1 .\" toc@\f4tigetstr()\f1: retrieve capabilities from the \f4terminfo\f1 database@@@see \f3tigetflag(3X)\f1 .\" toc@\f4tparm()\f1: retrieve capabilities from the \f4terminfo\f1 database@@@see \f3tigetflag(3X)\f1 .\" .\" index@\f4tigetflag()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f4tigetnum()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f4tigetstr()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f4tparm()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f1retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f1retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f1\f4terminfo\f1 database, retrieve capabilities from@@@\f3tigetflag(3X)\f1 .\" index@\f1capabilities, retrieve from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" .\" links@tigetflag.3x tigetnum.3x .\" links@tigetflag.3x tigetstr.3x .\" links@tigetflag.3x tparm.3x .\" .\" fileset_database@tigetflag.3x CURS-ENG-A-MAN .\" $Header: tigetflag.3x,v 76.2 95/08/01 14:55:09 ssa Exp $ .TA t .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH tigetflag 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 tigetflag .SH NAME tigetflag, tigetnum, tigetstr, tparm \(em retrieve capabilities from the \f3terminfo\f1 database .SH SYNOPSIS .C "#include " .P .C "int tigetflag(char *\f2capname\fP);" .P .C "int tigetnum(char *\f2capname\fP);" .P .C "char *tigetstr(char *\f2capname\fP);" .P .C "char *tparm(char *\f2cap\fP, long \f2p1\fP, long \f2p2\fP, long \f2p3\fP, long \f2p4\fP," .br .C " long \f2p5\fP, long \f2p6\fP, long \f2p7\fP, long \f2p8\fP, long \f2p9\fP);" .SH DESCRIPTION The .CR tigetflag() , .CR tigetnum() , and .Fn tigetstr functions obtain boolean, numeric and string capabilities, respectively, from the selected record of the \f3terminfo\f1 database. For each capability, the value to use as \f2capname\f1 appears in the .B Capname column in the table in \f3Defined Capabilities\f1 in terminfo(4). .P The .Fn tparm function takes as .I cap a string capability. If .I cap is parameterised (as described in \f3Parameterised Strings\f1 in terminfo(4)), .Fn tparm resolves the parameterisation. If the parameterised string refers to parameters \f4%p1\f1 through \f4%p9\f1, then .Fn tparm substitutes the values of \f2p1\f1 through \f2p9\fP, respectively. .SH "RETURN VALUE" Upon successful completion, .CR tigetflg() , .Fn tigetnum and .Fn tigetstr return the specified capability. The .Fn tigetflag function returns \(mi1 if \f2capname\f1 is not a boolean capability. The .Fn tigetnum function returns \(mi2 if \f2capname\f1 is not a numeric capability. The .Fn tigetstr function returns (\f3char *\f1)\(mi1 if \f2capname\f1 is not a string capability. .P Upon successful completion, .Fn tparm returns \f2str\f1 with parameterisation resolved. Otherwise, it returns a null pointer. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" For parameterised string capabilities, the application should pass the return value from .Fn tigetstr to .CR tparm() , as described above. .P Applications intending to send terminal capabilities directly to the terminal (which should only be done using .Fn tputs or .CR putp() ) instead of using Curses, normally should obey the following rules: .RS .TP 3 .C \(bu Call .Fn reset_shell_mode to restore the display modes before exiting. .TP .C \(bu If using cursor addressing, output \f3enter_ca_mode\f1 upon startup and output \f3exit_ca_mode\f1 before exiting. .TP .C \(bu If using shell escapes, output .B exit_ca_mode and call .Fn reset_shell_mode before calling the shell; call .Fn reset_prog_mode and output .I enter_ca_mode after returning from the shell. .RE .P All parameterised terminal capabilities defined in this document can be passed to .CR tparm() . Some implementations create their own capabilities, create capabilities for non-terminal devices, and redefine the capabilities in this document. These practices are non-conforming because it may be that .Fn tparm cannot parse these user-defined strings. .SH "SEE ALSO" def_prog_mode(), tgetent(), putp(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3tigetflag(3X)\f1:\0\0\f4tigetflag()\f1, \f4tigetnum()\f1, \f4tigetstr()\f1, \f4tparm()\f1\n@@@retrieve capabilities from the \f4terminfo\f1 database .\" toc@\f4tigetnum()\f1: retrieve capabilities from the \f4terminfo\f1 database@@@see \f3tigetflag(3X)\f1 .\" toc@\f4tigetstr()\f1: retrieve capabilities from the \f4terminfo\f1 database@@@see \f3tigetflag(3X)\f1 .\" toc@\f4tparm()\f1: retrieve capabilities from the \f4terminfo\f1 database@@@see \f3tigetflag(3X)\f1 .\" .\" index@\f4tigetflag()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f4tigetnum()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f4tigetstr()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f4tparm()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f1retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f1retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f1\f4terminfo\f1 database, retrieve capabilities from@@@\f3tigetflag(3X)\f1 .\" index@\f1capabilities, retrieve from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" .\" links@tigetflag.3x tigetnum.3x .\" links@tigetflag.3x tigetstr.3x .\" links@tigetflag.3x tparm.3x .\" .\" fileset_database@tigetflag.3x CURS-ENG-A-MAN .\" $Header: notimeout.3x,v 76.2 95/08/01 14:32:46 ssa Exp $ .TA n .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH notimeout 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME notimeout, timeout, wtimeout \(em control blocking on input .SH SYNOPSIS .C "#include " .P .C "int notimeout(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "void timeout(int \f2delay\fP);" .P .C "void wtimeout(WINDOW *\f2win\fP, int \f2delay\fP);" .SH DESCRIPTION The .Fn notimeout function specifies whether Timeout Mode or No Timeout Mode is in effect for the screen associated with the specified window. If \f2bf\f1 is TRUE, this screen is set to No Timeout Mode. If \f2bf\f1 is FALSE, this screen is set to Timeout Mode. The initial state is FALSE. .P The .Fn timeout and .Fn wtimeout functions set blocking or non-blocking read for the current or specified window based on the value of \f2delay\fP: .RS .TP 15 .C "\f2delay\fP\0<\00" One or more blocking reads (indefinite waits for input) are used. .TP .C "\f2delay\fP\0=\00" One or more non-blocking reads are used. Any Curses input function will fail if every character of the requested string is not immediately available. .TP .C "\f2delay\fP\0>\00" Any Curses input function blocks for \f2delay\f1 milliseconds and fails if there is still no input. .RE .SH "RETURN VALUE" Upon successful completion, the .Fn notimeout function returns OK. Otherwise, it returns ERR. .P The .Fn timeout and .Fn wtimeout functions do not return a value. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, getch(), halfdelay(), nodelay(), , \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Section 9.2, \f3Parameters That Can Be Set\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3notimeout(3X)\f1:\0\0\f4notimeout()\f1, \f4timeout()\f1, \f4wtimeout()\f1@@@control blocking on input .\" toc@\f4timeout()\f1: control blocking on input@@@see \f3notimeout(3X)\f1 .\" toc@\f4wtimeout()\f1: control blocking on input@@@see \f3notimeout(3X)\f1 .\" .\" index@\f4notimeout()\f1 \- control blocking on input@@@\f3notimeout(3X)\f1 .\" index@\f4timeout()\f1 \- control blocking on input@@@\f3notimeout(3X)\f1 .\" index@\f4wtimeout()\f1 \- control blocking on input@@@\f3notimeout(3X)\f1 .\" index@\f1control blocking on input@@@\f3notimeout(3X)\f1 .\" index@\f1blocking on input, control@@@\f3notimeout(3X)\f1 .\" index@\f1input, control blocking on@@@\f3notimeout(3X)\f1 .\" .\" links@notimeout.3x timeout.3x .\" links@notimeout.3x wtimeout.3x .\" .\" fileset_database@notimeout.3x CURS-ENG-A-MAN .\" $Header: ctime.3c,v 76.1 95/07/05 17:27:14 ssa Exp $ .TA c .TH ctime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctime(\|), ctime_r(\|), localtime(\|), localtime_r(\|), gmtime(\|), gmtime_r(\|), mktime(\|), difftime(\|), asctime(\|), asctime_r(\|), timezone(\|), daylight(\|), tzname(\|), tzset(\|) \- convert date and time to string .SH SYNOPSIS .nf .C "#include " .PP .C "char *asctime(const struct tm *timeptr);" .PP .C "int asctime_r(const struct tm *timeptr, char *buffer, int buflen);" .PP .C "char *ctime(const time_t *timer);" .PP .C "int ctime_r(const time_t *timer, char *buffer, int buflen);" .PP .C "double difftime(time_t time1, time_t time0);" .PP .C "struct tm *gmtime(const time_t *timer);" .PP .C "int gmtime_r(const time_t *timer, struct tm *result);" .PP .C "struct tm *localtime(const time_t *timer);" .PP .C "int localtime_r(const time_t *timer, struct tm *result);" .PP .C "time_t mktime(struct tm *timeptr);" .PP .C "extern long timezone;" .PP .C "extern int daylight;" .PP .C "extern char *tzname[2];" .PP .C "void tzset(void);" .fi .SH DESCRIPTION .TP 18 .C asctime() Convert the broken-down time contained in the structure pointed to by .I timeptr and return a pointer to a 26-character string in the form: .RS .IP .C "Sun Sep 16 01:03:52 1973\en\e0" .RE .IP All the fields have constant width. .TP .C asctime_r() is identical to .CR asctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C ctime() Convert the calendar time pointed to by .IR timer , representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: .RS .IP .C asctime(localtime(timer)) .RE .TP .C ctime_r() is identical to .CR ctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C gmtime() Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. .C gmtime() returns a pointer to the .C tm structure described below. .TP .C gmtime_r() is identical to .CR gmtime() , except that .C gmtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C localtime() Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA\c), according to the contents of the TZ environment variable (see Environment Variables below). .C localtime() returns a pointer to the .C tm structure described below. .TP .C localtime_r() is identical to .CR localtime() , except that .C localtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C difftime() Return the difference in seconds between two calendar times: .IR "time1 \(mi time0" . .TP .C mktime() Convert the broken-down time (expressed as local time) in the structure pointed to by .I timeptr into a calendar time value with the same encoding as that of the values returned by .IR time (2). The original values of the .C tm_wday and .C tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below. .IP A positive or zero value for .C tm_isdst causes .C mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for .C tm_isdst causes .C mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time. .IP Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of .C tm_mday is not set until .C tm_mon and .C tm_year are determined. .C mktime() returns the specified calendar time encoded as a value of type .CR time_t . .IP If the calendar time cannot be represented, the function returns the value .RC ( time_t )\|\(em\|1 and sets .C errno to .CR ERANGE . Note the value .RC ( time_t )\|\(em\|1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and .C errno to reliably detect an error condition. .TP .C tzset() Sets the values of the external variables .IR timezone , .IR daylight , and .I tzname according to the contents of the .C TZ environment variable (independent of any time value). The functions .CR localtime() , .CR mktime() , .CR ctime() , .CR asctime() , and .C strftime() (see .IR strftime (3C)) call .C tzset() and use the values returned in the external variables described below for their operations. .C tzset() can also be called directly by the user. .PP The .RC < time.h > header file contains declarations of all relevant functions and externals. It also contains the .C tm structure, which includes the following members: .RS .PP .nf .ift .ft 4 .ps +1 int tm_sec; /* seconds after the minute - [0,61] */ int tm_min; /* minutes after the hour - [0,59] */ int tm_hour; /* hours - [0,23] */ int tm_mday; /* day of month - [1,31] */ int tm_mon; /* month of year - [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday - [0,6] */ int tm_yday; /* days since January 1 - [0,365] */ int tm_isdst; /* daylight savings time flag */ .ift .ft .ps .fi .PP The value of .C tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available. .RE .PP The external variable .C timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), .C timezone is 5\(**60\(**60). The external variable .C daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable .C tzname[2] contains the local standard and local summer time zone abbreviations as specified by the .C TZ environment variable. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .SS Environment Variables The .C tzset() function uses the contents of .C TZ to set the values of the external variables .CR timezone , .C daylight , and .CR tzname . .C TZ also determines the time zone name substituted for the .C %Z and .C %z directives and the time zone adjustments performed by .CR localtime() , .CR mktime() , and .CR ctime() . Two methods for specifying a time zone within .C TZ are described in .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH "RETURN VALUE" .PP For .C asctime_r() and .C ctime_r(), if the buffer is of insufficient length, -1 is returned. For .C asctime_r(), ctime_r(), gmtime_r(), and .C localtime_r(), if the operation is successful, 0 is returned. .SH WARNINGS The return values for .CR asctime() , .CR ctime() , .CR gmtime() , and .CR localtime() point to static data whose contents is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() are MT-Safe and should be used instead. .PP Users of .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .PP The range of .C tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by .IR time (2) and passed as the .I timer argument does not include accumulated leap seconds. The .C tm structure generated by .C localtime() and .C gmtime() will never reflect any leap seconds. Upon successful completion, .C mktime() forces the value of the .C tm_sec component to the range [0,59]. .PP .CR ctime() , .CR ctime_r() , .CR asctime() , and .CR asctime_r() are considered obsolescent and may be removed in a future release. Use of .IR strftime (3C) is recommended instead. .SH AUTHOR .C ctime() was developed by AT&T and HP. .SH SEE ALSO time(2), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR ctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR asctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR daylight ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR difftime() ": AES, SVID3, XPG4, ANSI C" .PP .CR gmtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR localtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mktime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR timezone ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR tzname ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tzset() ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4asctime()\fP, \f4asctime_r()\f1 \- convert \f3tm\f1 structure date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4ctime()\fP, \f4ctime_r()\f1 \- convert \f4clock()\fP date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4daylight()\fP \- Daylight Savings Time flag@@@\f3ctime(3C)\f1 .\" index@\f4gmtime()\fP, \f4gmtime_r()\fP \- convert date and time to Greenwich Mean Time@@@\f3ctime(3C)\f1 .\" index@\f4localtime()\fP, \f4localtime_r()\fP \- convert date and time to local timezone@@@\f3ctime(3C)\f1 .\" index@\f4timezone()\fP \- difference between \s-1UCT\s+1 and local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzname()\fP \- name of local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzset()\fP \- initialize \f4timezone()\fP, \f4daylight()\fP, and \f4tzname()\fP using \s-1TZ\s+1 variable@@@\f3ctime(3C)\f1 .\" index@\f4mktime()\fP \- convert time into calendar time value@@@\f3ctime(3C)\f1 .\" index@\f4difftime()\fP \- difference between two calendar time values@@@\f3ctime(3C)\f1 .\" index@convert date and time to string@@@\f3ctime(3C)\f1 .\" index@string, convert date and time to@@@\f3ctime(3C)\f1 .\" index@date and time, convert to string@@@\f3ctime(3C)\f1 .\" index@time and date, convert to string@@@\f3ctime(3C)\f1 .\" .\" toc@\f3ctime(3C)\f1:\0\0\f4ctime()\fP, \f4ctime_r()\fP, \f4localtime()\fP, \f4localtime_r()\fP, \f4difftime()\f1, \f4 mktime()\f1, \n\f4gmtime()\fP, \f4gmtime_r()\fP,\f4asctime()\fP, \f4asctime_r()\fP, \f4timezone()\fP, \f4daylight()\fP, \f4tzname()\fP,\n\f4tzset()\f1@@@convert date and time to string .\" toc@\f4ctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4ctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4timezone()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4daylight()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzname()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzset()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4difftime()\fP:\0\0difference between calendar times@@@see \f3ctime(3C)\f1 .\" toc@\f4mktime()\fP:\0\0create calendar time value@@@see \f3ctime(3C)\f1 .\" .\" links@ctime.3c ctime_r.3c .\" links@ctime.3c localtime.3c .\" links@ctime.3c localtime_r.3c .\" links@ctime.3c gmtime.3c .\" links@ctime.3c gmtime_r.3c .\" links@ctime.3c asctime.3c .\" links@ctime.3c asctime_r.3c .\" links@ctime.3c timezone.3c .\" links@ctime.3c daylight.3c .\" links@ctime.3c tzname.3c .\" links@ctime.3c tzset.3c .\" links@ctime.3c difftime.3c .\" links@ctime.3c mktime.3c .\" .\" fileset_database@ctime.3c PROGRAMING-MAN .\" $Header: tmpfile.3s,v 78.1 96/02/12 14:20:30 ssa Exp $ .TA t .TH tmpfile 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tmpfile(\|) \- create a temporary file .SH SYNOPSIS .C "#include " .P .C "FILE *tmpfile(void);" .SH DESCRIPTION .C tmpfile() creates a temporary file by generating a name through .CR tmpnam() (see .IR tmpnam (3S)), and returns a corresponding .C FILE pointer. If the file cannot be opened a .SM NULL pointer is returned. The file is automatically deleted when the process using it terminates. The file is opened for update .RC ( wb+ ). .SH ERRORS The .CR tmpfile() function will fail if: .RS .TP 25 [EOVERFLOW] The named file is a regular file and the size of the file cannot be represented correctly in an object of size .CR off_t in this environment. .PP Additional .CR errno values may be set by the underlying .CR fopen() function (see .IR fopen (3S)). .SH NOTES On .SM HP-UX systems, the .C wb+ mode is equivalent to the .C w+ mode. .SH SEE ALSO creat(2), unlink(2), mktemp(3C), fopen(3S), tmpfile64(3S), tmpnam(3S). .SH STANDARDS CONFORMANCE .CR tmpfile() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4tmpfile()\fP \- create a temporary file@@@\f3tmpfile(3S)\f1 .\" index@\f1create a temporary file@@@\f3tmpfile(3S)\f1 .\" index@\f1temporary file, create a@@@\f3tmpfile(3S)\f1 .\" index@\f1file: create a temporary file@@@\f3tmpfile(3S)\f1 .\" .\" toc@\f3tmpfile(3S)\f1:\0\0\f4tmpfile()\fP@@@create a temporary file .\" .\" $Header: fgetpos64.3s,v 78.3 96/02/12 17:04:12 ssa Exp $ .TA f .TH fgetpos64 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fgetpos64(\|), fopen64(\|), freopen64(\|), fseeko64(\|), fsetpos64(\|), fstatvfsdev64(\|), ftello64(\|), ftw64(\|), nftw64(\|), statvfsdev64(\|), tmpfile64(\|) \- non-POSIX standard API interfaces to support large files. .SH SYNOPSIS .C "#include " .PP .C "int\0fgetpos64(FILE\0*stream,\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "FILE\0*fopen64(const\0char\0*pathname,\0const\0char\0*type);" .PP .C "#include " .PP .C "FILE\0*freopen64(const\0char\0*pathname,\0const\0char\0*type,\0FILE\0*stream);" .PP .C "#include " .PP .C "int\0fseeko64(FILE\0*stream,\0off64_t\0*offset,\0int\0whence);" .PP .C "#include " .PP .C "int\0fsetpos64(FILE\0*stream,\0const\0fpos64_t\0*pos);" .PP .C "#include " .PP .C "int\0fstatvfsdev64(int\0filedes,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "off64_t\0ftello64(FILE\0*stream);" .PP .nf .C "#include " .PP .C "int ftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags)," .C " int depth);" .PP .C "#include " .PP .C "int nftw64(const char *path," .C " int (*fn)(const char *obj_path," .C " const struct stat64 *obj_stat," .C " int obj_flags," .C " struct FTW obj_FTW)," .C " int depth," .C " int flags);" .fi .PP .C "#include " .PP .C "int\0statvfsdev64(const\0char\0*path,\0struct\0statvfs64\0*buf);" .PP .C "#include " .PP .C "FILE\0*tmpfile64(void);" .SH DESCRIPTION New API's to support large files. These API interfaces are not a part of the POSIX standard and may be removed in the future. .TP 22 .C fgetpos64() The .C fgetpos64() function is identical to .C fgetpos() except that .C fgetpos64() returns the position in a .C fpos64_t instead of a .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fopen64() The .C fopen64() function is identical to .C fopen() in 64-bit compile environment. The .C fopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR fopen() . .TP .C freopen64() The .C freopen64() function is identical to .C freopen() in 64-bit compile environment. The .C freopen64() function returns a pointer to a FILE which can be used to grow the file past 2 GB if desired. All other functional behaviors, returns, and errors are identical to .CR freopen() . .TP .C fseeko64() The .C fseeko64() function is identical to .C fseeko() except that .C fseeko64() accepts an .CR off64_t for the size parameter instead of .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C fsetpos64() The .C fsetpos64() function is identical to .C fsetpos() except that .C fsetpos64() accepts an .CR fpos64_t for the pos parameter instead of .CR fpos_t . All other functional behaviors, returns, and errors are identical. .TP .C fstatvfsdev64() The .C fstatvfsdev64() function is identical to .C fstatvfsdev() except that .C fstatvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C ftello64() The .C ftello64() function is identical to .C ftello() except that .C ftello64() returns the file position in an .C off64_t instead of an .CR off_t . All other functional behaviors, returns, and errors are identical. .TP .C ftw64() The .C ftw64() function is identical to .C ftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR ftw64() . All other functional behaviors, returns, and errors are identical. .TP .C nftw64() The .C nftw64() function is identical to .C nftw() except that it that it utilizes a .CR "struct stat64" as the second parameter to the function whose pointer is passed to .CR nftw64() . All other functional behaviors, returns, and errors are identical. .TP .C statvfsdev64() The .C statvfsdev64() function is identical to .C statvfsdev() except that .C statvfsdev64() accepts a .CR "struct statvfs64" for the second parameter instead of .CR "struct statvfs" . All other functional behaviors, returns, and errors are identical. .TP .C tmpfile64() The .C tmpfile64() function is identical to .C tmpfile() in the 64-bit compile environment. Both interfaces create a temporary file that is capable of growing beyond 2GB's if desired. All other functional behaviors, returns, and errors are identical. .\" .\" toc@\f4fgetpos64(2)\f1:\0\0\f4fopen64\f1, \f4freopen64\f1, \f4fseeko64\f1, \f4fsetpos64\f1, \f4fstatvfsdev64\f1, \f4ftello64\f1, \f4ftw64\f1, \n\f4nftw64\f1, \f4statvfsdev64\f1, \f4tmpfile64\f1@@@file system APIs to support large files .\" .\" .\" index@\f4fgetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4freopen64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fseeko64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fsetpos64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4fstatvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftello64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4ftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4nftw64()\f1 \- file sysmmaptem API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4statvfsdev64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f4tmpfile64()\f1 \- file system API to support large files@@@\f3fgetpos64(2)\f1 .\" index@\f1file system APIs to support large files@@@\f3fgetpos64(2)\f1 .\" .\" links@fgetpos64.3s fopen64.3s .\" links@fgetpos64.3s freopen64.3s .\" links@fgetpos64.3s fseek64.3s .\" links@fgetpos64.3s fsetpos64.3s .\" links@fgetpos64.3s fstatvfs64.3s .\" links@fgetpos64.3s ftello64.3s .\" links@fgetpos64.3s ftw64.3s .\" links@fgetpos64.3s nftw64.3s .\" links@fgetpos64.3s statvfsdev64.3s .\" links@fgetpos64.3s tmpfile64.3s .\" .\" $Header: tmpnam.3s,v 78.1 96/01/22 22:28:32 ssa Exp $ .TA t .TH tmpnam 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tmpnam(\|), tempnam(\|) \- create a name for a temporary file .SH SYNOPSIS .C "#include " .PP .C "char *tmpnam(char *s);" .PP .C "char *tempnam(const char *dir, const char *pfx);" .SH DESCRIPTION .CR tmpnam() and .CR tempnam() generate file names that can safely be used for a temporary file. .RS .TP 15 .CR tmpnam() Always generates a file name using the path-prefix defined as .CR P_tmpdir in the .RC < stdio.h > header file. If .I s is .SM NULL, .CR tmpnam() leaves its result in an internal static area and returns a pointer to that area. The next call to .CR tmpnam() destroys the contents of the area. If .I s is not .SM NULL, it is assumed to be the address of an array of at least .CR L_tmpnam bytes, where .CR L_tmpnam is a constant defined in .RC < stdio.h >; .CR tmpnam() places its result in that array and returns .IR s . For multi-thread applications, if .I s is a .SM NULL pointer, the operation is not performed and a .SM NULL pointer is returned. .TP .CR tempnam() allows the user to control the choice of a directory. The argument .I dir points to the name of the directory in which the file is to be created. If .I dir is .SM NULL or points to a string that is not an appropriate directory name, the path-prefix defined as .CR P_tmpdir in the .RC < stdio.h > header file is used. If that directory is not accessible, .CR /tmp is used as a last resort. This entire sequence can be eliminated by providing an environment variable .CR TMPDIR in the user's environment, whose value is the name of the desired temporary-file directory. .RE .PP In order to request the default behavior for either .CR tempnam() or .CR tmpnam() , a NULL value must be passed in .IR dir and .IR pfx for .CR tempnam() , or in .IR s for .CR tmpnam() . If valid parameters are not passed in, behavior is undefined. .RE .PP Many applications are written such that temporary files have certain initial character sequences in their names. Use the .I pfx argument to define a given prefix. The argument can be .SM NULL or point to a string of up to five characters to be used as the first characters in the temporary-file name. .PP .CR tempnam() uses .CR malloc() (see .IR malloc (3C)) to get space for the constructed file name, and returns a pointer to this area. Thus, any pointer value returned from .CR tempnam() can serve as an argument to .CR free() (see .IR malloc (3C)). If .CR tempnam() cannot return the expected result for any reason; i.e., .CR malloc() failed, or none of the above mentioned attempts to find an appropriate directory was successful, a .SM NULL pointer is returned. .SH NOTES .CR tmpnam() and .CR tempnam() generate a different file name each time they are called, but start recycling previously used names if called more than .CR TMP_MAX times in a single process. .PP Files created using these functions and either .CR fopen() or .CR creat() (see .IR fopen (3S) and .IR creat (2)) are temporary only in the sense that they reside in a directory intended for temporary use, and their names are unique. It is the user's responsibility to use .IR unlink (2) to remove the file when it is no longer needed. .SH WARNINGS Between the time a file name is created and the file is opened, it is possible for some other process to create a file with the same name. This can never happen if that other process is using these functions or .CR mktemp , and the file names are chosen such that duplication by other means is unlikely. .SH SEE ALSO creat(2), unlink(2), malloc(3C), mktemp(3C), fopen(3S), tmpfile(3S). .SH STANDARDS CONFORMANCE .CR tmpnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR tempnam() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4tmpnam()\fP \- create a name for a temporary file@@@\f3tmpnam(3S)\f1 .\" index@\f4tempnam()\fP \- create a name for a temporary file@@@\f3tmpnam(3S)\f1 .\" index@create a name for a temporary file@@@\f3tmpnam(3S)\f1 .\" index@name: create a name for a temporary file@@@\f3tmpnam(3S)\f1 .\" index@temporary file, create a name for@@@\f3tmpnam(3S)\f1 .\" index@file: create a name for a temporary file@@@\f3tmpnam(3S)\f1 .\" .\" toc@\f3tmpnam(3S)\f1:\0\0\f4tmpnam()\fP, \f4tempnam()\fP@@@create a name for a temporary file .\" toc@\f4tempnam()\fP:\0\0create a name for a temporary file@@@see \f3tmpnam(3S)\f1 .\" .\" links@tmpnam.3s tempnam.3s .\" $Header: conv.3c,v 72.7 94/11/28 08:25:12 ssa Exp $ .TA c .TH conv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME toupper(\|), tolower(\|), _toupper(\|), _tolower(\|), toascii(\|) \- translate characters .SH SYNOPSIS .C "#include " .PP .C "int toupper(int c);" .PP .C "int tolower(int c);" .PP .C "int _toupper(int c);" .PP .C "int _tolower(int c);" .PP .C "int toascii(int c);" .SH DESCRIPTION .C toupper() and .C tolower() have as domain the range of .IR getc (3S): the integers from \(mi1 through 255. If the argument of .C toupper() represents a lower-case letter, the result is the corresponding upper-case letter. If the argument of .C tolower() represents an upper-case letter, the result is the corresponding lower-case letter. All other arguments in the domain are returned unchanged. Arguments outside the domain cause undefined results. .PP The macros .C _toupper() and .C _tolower() are identical to .C toupper() and .CR tolower() , respectively. .PP .C toascii() yields its argument with all bits that are not part of a standard 7-bit .SM ASCII character cleared; it is intended for compatibility with other systems. .SH WARNING .C toascii() is supplied both as a library function and as a macro defined in the .RC < ctype.h > header. Normally, the macro version is used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI C mode, enclose the function name in parenthesis or take its address. The following examples use the library function for .CR toascii() : .nf .IP .C #include .C #undef toascii \h'.4i'... .C main() .C { \h'.5i'... .C " c1 = toascii(c);" \h'.5i'... .C } .PP or .IP .C #include \h'.4i'... .C main() .C { .C " int (*conv_func)();" \h'.5i'... .C " c1 = (toascii)(c);" \h'.5i'... .C " conv_func = toascii;" \h'.5i'... .C } .fi .PP The following example use the library function for .CR toupper() : .nf .IP .C #include .C #undef toupper \h'.4i'... .C main() .C { \h'.5i'... char *c; *c=toupper ((unsigned char*) c); \h'.5i'... .C } .PP .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the translations to be done. .SS International Code Set Support Single-byte character code sets are supported. .SH AUTHOR .CR conv() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), getc(3S), setlocale(3C), lang(5). .SH STANDARDS CONFORMANCE .CR _tolower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR _toupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR toascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR tolower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR toupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4conv()\f1, \- translate characters@@@\f3conv(3C)\f1 .\" index@\f4toupper()\fP, \f2_toupper\f1, \- translate characters to upper-case@@@\f3conv(3C)\f1 .\" index@\f4tolower()\fP, \f2_tolower\f1 \- translate characters to lower-case@@@\f3conv(3C)\f1 .\" index@\f4toascii()\fP \- translate characters to 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1translate characters to upper-case, lower-case, or 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1characters, translate to upper-case, lower-case, or 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1upper-case, translate characters to@@@\f3conv(3C)\f1 .\" index@\f1lower-case, translate characters to@@@\f3conv(3C)\f1 .\" index@\s-1ASCII\s+1, 7-bit, translate characters to@@@\f3conv(3C)\f1 .\" .\" toc@\f3conv(3C)\f1:\0\0\f4toupper()\fP, \f4tolower()\fP, \f2_toupper\f1, \f2_tolower\f1, \f4toascii()\fP@@@translate characters .\" .\" toc@\f4toupper()\fP, \f2_toupper\f1:\0\0translate characters@@@see \f3conv(3C)\f1 .\" toc@\f4tolower()\fP, \f2_tolower\f1:\0\0translate characters@@@see \f3conv(3C)\f1 .\" toc@\f4toascii()\fP:\0\0translate characters@@@see \f3conv(3C)\f1 .\" .\" links@conv.3c toupper.3c .\" links@conv.3c tolower.3c .\" links@conv.3c _toupper.3c .\" links@conv.3c _tolower.3c .\" links@conv.3c toascii.3c .\" .\" fileset_database@conv.3c PROGRAMING-MAN .\" $Header: conv.3c,v 72.7 94/11/28 08:25:12 ssa Exp $ .TA c .TH conv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME toupper(\|), tolower(\|), _toupper(\|), _tolower(\|), toascii(\|) \- translate characters .SH SYNOPSIS .C "#include " .PP .C "int toupper(int c);" .PP .C "int tolower(int c);" .PP .C "int _toupper(int c);" .PP .C "int _tolower(int c);" .PP .C "int toascii(int c);" .SH DESCRIPTION .C toupper() and .C tolower() have as domain the range of .IR getc (3S): the integers from \(mi1 through 255. If the argument of .C toupper() represents a lower-case letter, the result is the corresponding upper-case letter. If the argument of .C tolower() represents an upper-case letter, the result is the corresponding lower-case letter. All other arguments in the domain are returned unchanged. Arguments outside the domain cause undefined results. .PP The macros .C _toupper() and .C _tolower() are identical to .C toupper() and .CR tolower() , respectively. .PP .C toascii() yields its argument with all bits that are not part of a standard 7-bit .SM ASCII character cleared; it is intended for compatibility with other systems. .SH WARNING .C toascii() is supplied both as a library function and as a macro defined in the .RC < ctype.h > header. Normally, the macro version is used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI C mode, enclose the function name in parenthesis or take its address. The following examples use the library function for .CR toascii() : .nf .IP .C #include .C #undef toascii \h'.4i'... .C main() .C { \h'.5i'... .C " c1 = toascii(c);" \h'.5i'... .C } .PP or .IP .C #include \h'.4i'... .C main() .C { .C " int (*conv_func)();" \h'.5i'... .C " c1 = (toascii)(c);" \h'.5i'... .C " conv_func = toascii;" \h'.5i'... .C } .fi .PP The following example use the library function for .CR toupper() : .nf .IP .C #include .C #undef toupper \h'.4i'... .C main() .C { \h'.5i'... char *c; *c=toupper ((unsigned char*) c); \h'.5i'... .C } .PP .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the translations to be done. .SS International Code Set Support Single-byte character code sets are supported. .SH AUTHOR .CR conv() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), getc(3S), setlocale(3C), lang(5). .SH STANDARDS CONFORMANCE .CR _tolower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR _toupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR toascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR tolower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR toupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4conv()\f1, \- translate characters@@@\f3conv(3C)\f1 .\" index@\f4toupper()\fP, \f2_toupper\f1, \- translate characters to upper-case@@@\f3conv(3C)\f1 .\" index@\f4tolower()\fP, \f2_tolower\f1 \- translate characters to lower-case@@@\f3conv(3C)\f1 .\" index@\f4toascii()\fP \- translate characters to 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1translate characters to upper-case, lower-case, or 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1characters, translate to upper-case, lower-case, or 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1upper-case, translate characters to@@@\f3conv(3C)\f1 .\" index@\f1lower-case, translate characters to@@@\f3conv(3C)\f1 .\" index@\s-1ASCII\s+1, 7-bit, translate characters to@@@\f3conv(3C)\f1 .\" .\" toc@\f3conv(3C)\f1:\0\0\f4toupper()\fP, \f4tolower()\fP, \f2_toupper\f1, \f2_tolower\f1, \f4toascii()\fP@@@translate characters .\" .\" toc@\f4toupper()\fP, \f2_toupper\f1:\0\0translate characters@@@see \f3conv(3C)\f1 .\" toc@\f4tolower()\fP, \f2_tolower\f1:\0\0translate characters@@@see \f3conv(3C)\f1 .\" toc@\f4toascii()\fP:\0\0translate characters@@@see \f3conv(3C)\f1 .\" .\" links@conv.3c toupper.3c .\" links@conv.3c tolower.3c .\" links@conv.3c _toupper.3c .\" links@conv.3c _tolower.3c .\" links@conv.3c toascii.3c .\" .\" fileset_database@conv.3c PROGRAMING-MAN .\" $Header: is_linetouched.3x,v 76.2 95/08/01 11:31:01 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH is_linetouched 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 manpage_touch .SH NAME is_linetouched, is_wintouched, touchline, untouchwin, wtouchln \(em window refresh control functions .SH SYNOPSIS .C "#include " .P .C "bool is_linetouched(WINDOW *\f2win\fP, int \f2line\fP);" .P .C "bool is_wintouched(WINDOW *\f2win\fP);" .P .C "int touchline(WINDOW *\f2win\fP, int \f2start\fP, int \f2count\fP);" .P .C "int untouchwin(WINDOW *\f2win\fP);" .P .C "int wtouchln(WINDOW *\f2win\fP, int \f2y\fP, int \f2n\fP, int \f2changed\fP);" .SH DESCRIPTION The .Fn touchline function only touches \f2count\f1 lines, beginning with line \f2start\f1. .P The .Fn untouchwin function marks all lines in the window as unchanged since the last refresh operation. .P Calling .Fn wtouchln , if \f2changed\f1 is 1, touches \f2n\f1 lines in the specified window, starting at line \f2y\f1. If \f2changed\f1 is 0, .Fn wtouchln marks such lines as unchanged since the last refresh operation. .P The .Fn is_wintouched function determines whether the specified window is touched. The .Fn is_linetouched function determines whether line .I line of the specified window is touched. .SH "RETURN VALUE" The .Fn is_linetouched and .Fn is_wintouched functions return TRUE if any of the specified lines, or the specified window, respectively, has been touched since the last refresh operation. Otherwise, they return FALSE. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. Exceptions to this are noted in the preceding function descriptions. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Calling .Fn touchwin or .Fn touchline is sometimes necessary when using overlapping windows, since a change to one window affects the other window, but the records of which lines have been changed in the other window do not reflect the change. .SH "SEE ALSO" \f3Screens, Windows and Terminals\f1 in curs_intro, doupdate(), touchwin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3is_linetouched(3X)\f1:\0\0\f4is_linetouched()\f1, \f4is_wintouched()\f1, \f4touchline()\f1, \f4untouchwin()\f1, \n\f4wtouchln()\f1@@@window refresh control functions .\" toc@\f4is_wintouched()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4touchline()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4untouchwin()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4wtouchln()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" .\" index@\f4is_linetouched()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4is_wintouched()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4touchline()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4untouchwin()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4wtouchln()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f1window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f1refresh control functions for window@@@\f3is_linetouched(3X)\f1 .\" index@\f1control functions, window refresh@@@\f3is_linetouched(3X)\f1 .\" index@\f1functions, window refresh control@@@\f3is_linetouched(3X)\f1 .\" .\" links@is_linetouched.3x is_wintouched.3x .\" links@is_linetouched.3x touchline.3x .\" links@is_linetouched.3x untouchwin.3x .\" links@is_linetouched.3x wtouchln.3x .\" .\" fileset_database@is_linetouched.3x CURS-ENG-A-MAN .\" $Header: touchwin.3x,v 76.2 95/08/01 14:55:59 ssa Exp $ .TA t .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH touchwin 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 manpage_touch .SH NAME touchwin \(em window refresh control function .SH SYNOPSIS .C "#include " .P .C "int touchwin(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn touchwin function touches the specified window (that is, marks it as having changed more recently than the last refresh operation). .SH "RETURN VALUE" .P Upon successful completion, the this function return OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Calling .Fn touchwin or .Fn touchline is sometimes necessary when using overlapping windows, since a change to one window affects the other window, but the records of which lines have been changed in the other window do not reflect the change. .SH "SEE ALSO" \f3Screens, Windows and Terminals\f1 in curs_intro, doupdate(), is_linetouched(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .\" .\" index@\f4touchwin()\f1 \- window refresh control function@@@\f3touchwin(3X)\f1 .\" index@\f1window refresh control function@@@\f3touchwin(3X)\f1 .\" index@\f1refresh control function, for window@@@\f3touchwin(3X)\f1 .\" index@\f1control function, for window refresh@@@\f3touchwin(3X)\f1 .\" index@\f1function, window refresh control@@@\f3touchwin(3X)\f1 .\" .\" toc@\f3touchwin(3X)\f1:\0\0\f4touchwin()\f1@@@window refresh control function .\" .\" fileset_database@touchwin.3x CURS-ENG-A-MAN .\" $Header: conv.3c,v 72.7 94/11/28 08:25:12 ssa Exp $ .TA c .TH conv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME toupper(\|), tolower(\|), _toupper(\|), _tolower(\|), toascii(\|) \- translate characters .SH SYNOPSIS .C "#include " .PP .C "int toupper(int c);" .PP .C "int tolower(int c);" .PP .C "int _toupper(int c);" .PP .C "int _tolower(int c);" .PP .C "int toascii(int c);" .SH DESCRIPTION .C toupper() and .C tolower() have as domain the range of .IR getc (3S): the integers from \(mi1 through 255. If the argument of .C toupper() represents a lower-case letter, the result is the corresponding upper-case letter. If the argument of .C tolower() represents an upper-case letter, the result is the corresponding lower-case letter. All other arguments in the domain are returned unchanged. Arguments outside the domain cause undefined results. .PP The macros .C _toupper() and .C _tolower() are identical to .C toupper() and .CR tolower() , respectively. .PP .C toascii() yields its argument with all bits that are not part of a standard 7-bit .SM ASCII character cleared; it is intended for compatibility with other systems. .SH WARNING .C toascii() is supplied both as a library function and as a macro defined in the .RC < ctype.h > header. Normally, the macro version is used. To obtain the library function, either use a .C #undef to remove the macro definition or, if compiling in .SM ANSI C mode, enclose the function name in parenthesis or take its address. The following examples use the library function for .CR toascii() : .nf .IP .C #include .C #undef toascii \h'.4i'... .C main() .C { \h'.5i'... .C " c1 = toascii(c);" \h'.5i'... .C } .PP or .IP .C #include \h'.4i'... .C main() .C { .C " int (*conv_func)();" \h'.5i'... .C " c1 = (toascii)(c);" \h'.5i'... .C " conv_func = toascii;" \h'.5i'... .C } .fi .PP The following example use the library function for .CR toupper() : .nf .IP .C #include .C #undef toupper \h'.4i'... .C main() .C { \h'.5i'... char *c; *c=toupper ((unsigned char*) c); \h'.5i'... .C } .PP .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the translations to be done. .SS International Code Set Support Single-byte character code sets are supported. .SH AUTHOR .CR conv() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), getc(3S), setlocale(3C), lang(5). .SH STANDARDS CONFORMANCE .CR _tolower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR _toupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR toascii() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR tolower() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR toupper() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4conv()\f1, \- translate characters@@@\f3conv(3C)\f1 .\" index@\f4toupper()\fP, \f2_toupper\f1, \- translate characters to upper-case@@@\f3conv(3C)\f1 .\" index@\f4tolower()\fP, \f2_tolower\f1 \- translate characters to lower-case@@@\f3conv(3C)\f1 .\" index@\f4toascii()\fP \- translate characters to 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1translate characters to upper-case, lower-case, or 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1characters, translate to upper-case, lower-case, or 7-bit \s-1ASCII\s+1@@@\f3conv(3C)\f1 .\" index@\f1upper-case, translate characters to@@@\f3conv(3C)\f1 .\" index@\f1lower-case, translate characters to@@@\f3conv(3C)\f1 .\" index@\s-1ASCII\s+1, 7-bit, translate characters to@@@\f3conv(3C)\f1 .\" .\" toc@\f3conv(3C)\f1:\0\0\f4toupper()\fP, \f4tolower()\fP, \f2_toupper\f1, \f2_tolower\f1, \f4toascii()\fP@@@translate characters .\" .\" toc@\f4toupper()\fP, \f2_toupper\f1:\0\0translate characters@@@see \f3conv(3C)\f1 .\" toc@\f4tolower()\fP, \f2_tolower\f1:\0\0translate characters@@@see \f3conv(3C)\f1 .\" toc@\f4toascii()\fP:\0\0translate characters@@@see \f3conv(3C)\f1 .\" .\" links@conv.3c toupper.3c .\" links@conv.3c tolower.3c .\" links@conv.3c _toupper.3c .\" links@conv.3c _tolower.3c .\" links@conv.3c toascii.3c .\" .\" fileset_database@conv.3c PROGRAMING-MAN .\" $Header: wconv.3c,v 72.7 94/11/28 08:37:51 ssa Exp $ .TA w .TH wconv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME towupper(\|), towlower(\|) \- translate wide characters .SH SYNOPSIS .C "#include " .PP .C "wint_t towupper(wint_t wc);" .PP .C "wint_t towlower(wint_t wc);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character conversion functions. They parallel the 8-bit character conversion functions defined in .IR conv(3C) . .SH DESCRIPTION .C towupper() and .C towlower() have as domain a .CR wint_t , the value of which is representable as a .C wchar_t or the value .CR WEOF . If the argument has any other value, the behavior is undefined. If the argument of .C towupper() represents a lowercase letter, the result is the corresponding uppercase letter. If the argument of .C towlower() represents an uppercase letter, the result is the corresponding lowercase letter. All other arguments are returned unchanged. .PP Definitions for these functions, the types .CR wint_t , .CR wchar_t , and the value .C WEOF are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the translations to be done. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wconv() was developed by IBM, OSF, and HP. .SH SEE ALSO conv(3C), multibyte(3C), wctype(3C), setlocale(3C), lang(5). .SH STANDARDS CONFORMANCE .CR towlower() ": XPG4" .PP .CR towupper() ": XPG4" .\" .\" index@\f4wconv()\f1 \- translate wide characters@@@\f3wconv(3C)\f1 .\" index@\f4towupper()\f1 \- translate wide characters to uppercase@@@\f3wconv(3C)\f1 .\" index@\f4towlower()\f1 \- translate wide characters to lowercase@@@\f3wconv(3C)\f1 .\" index@\f1translate wide characters to uppercase or lowercase@@@\f3wconv(3C)\f1 .\" index@\f1wide characters, translate to uppercase or lowercase@@@\f3wconv(3C)\f1 .\" index@\f1uppercase, translate wide characters to@@@\f3wconv(3C)\f1 .\" index@\f1lowercase, translate wide characters to@@@\f3wconv(3C)\f1 .\" .\" toc@\f3wconv(3C)\f1:\0\0\f4towupper()\f1, \f4towlower()\f1@@@translate wide characters .\" toc@\f4towupper()\f1:\0\0translate wide characters@@@\f1see \f3wconv(3C)\f1 .\" toc@\f4towlower()\f1:\0\0translate wide characters@@@\f1see \f3wconv(3C)\f1 .\" .\" links@wconv.3c towupper.3c .\" links@wconv.3c towlower.3c .\" .\" fileset_database@wconv.3c PROGRAMING-MAN .\" $Header: wconv.3c,v 72.7 94/11/28 08:37:51 ssa Exp $ .TA w .TH wconv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME towupper(\|), towlower(\|) \- translate wide characters .SH SYNOPSIS .C "#include " .PP .C "wint_t towupper(wint_t wc);" .PP .C "wint_t towlower(wint_t wc);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character conversion functions. They parallel the 8-bit character conversion functions defined in .IR conv(3C) . .SH DESCRIPTION .C towupper() and .C towlower() have as domain a .CR wint_t , the value of which is representable as a .C wchar_t or the value .CR WEOF . If the argument has any other value, the behavior is undefined. If the argument of .C towupper() represents a lowercase letter, the result is the corresponding uppercase letter. If the argument of .C towlower() represents an uppercase letter, the result is the corresponding lowercase letter. All other arguments are returned unchanged. .PP Definitions for these functions, the types .CR wint_t , .CR wchar_t , and the value .C WEOF are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the translations to be done. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wconv() was developed by IBM, OSF, and HP. .SH SEE ALSO conv(3C), multibyte(3C), wctype(3C), setlocale(3C), lang(5). .SH STANDARDS CONFORMANCE .CR towlower() ": XPG4" .PP .CR towupper() ": XPG4" .\" .\" index@\f4wconv()\f1 \- translate wide characters@@@\f3wconv(3C)\f1 .\" index@\f4towupper()\f1 \- translate wide characters to uppercase@@@\f3wconv(3C)\f1 .\" index@\f4towlower()\f1 \- translate wide characters to lowercase@@@\f3wconv(3C)\f1 .\" index@\f1translate wide characters to uppercase or lowercase@@@\f3wconv(3C)\f1 .\" index@\f1wide characters, translate to uppercase or lowercase@@@\f3wconv(3C)\f1 .\" index@\f1uppercase, translate wide characters to@@@\f3wconv(3C)\f1 .\" index@\f1lowercase, translate wide characters to@@@\f3wconv(3C)\f1 .\" .\" toc@\f3wconv(3C)\f1:\0\0\f4towupper()\f1, \f4towlower()\f1@@@translate wide characters .\" toc@\f4towupper()\f1:\0\0translate wide characters@@@\f1see \f3wconv(3C)\f1 .\" toc@\f4towlower()\f1:\0\0translate wide characters@@@\f1see \f3wconv(3C)\f1 .\" .\" links@wconv.3c towupper.3c .\" links@wconv.3c towlower.3c .\" .\" fileset_database@wconv.3c PROGRAMING-MAN .\" $Header: tigetflag.3x,v 76.2 95/08/01 14:55:09 ssa Exp $ .TA t .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH tigetflag 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 tigetflag .SH NAME tigetflag, tigetnum, tigetstr, tparm \(em retrieve capabilities from the \f3terminfo\f1 database .SH SYNOPSIS .C "#include " .P .C "int tigetflag(char *\f2capname\fP);" .P .C "int tigetnum(char *\f2capname\fP);" .P .C "char *tigetstr(char *\f2capname\fP);" .P .C "char *tparm(char *\f2cap\fP, long \f2p1\fP, long \f2p2\fP, long \f2p3\fP, long \f2p4\fP," .br .C " long \f2p5\fP, long \f2p6\fP, long \f2p7\fP, long \f2p8\fP, long \f2p9\fP);" .SH DESCRIPTION The .CR tigetflag() , .CR tigetnum() , and .Fn tigetstr functions obtain boolean, numeric and string capabilities, respectively, from the selected record of the \f3terminfo\f1 database. For each capability, the value to use as \f2capname\f1 appears in the .B Capname column in the table in \f3Defined Capabilities\f1 in terminfo(4). .P The .Fn tparm function takes as .I cap a string capability. If .I cap is parameterised (as described in \f3Parameterised Strings\f1 in terminfo(4)), .Fn tparm resolves the parameterisation. If the parameterised string refers to parameters \f4%p1\f1 through \f4%p9\f1, then .Fn tparm substitutes the values of \f2p1\f1 through \f2p9\fP, respectively. .SH "RETURN VALUE" Upon successful completion, .CR tigetflg() , .Fn tigetnum and .Fn tigetstr return the specified capability. The .Fn tigetflag function returns \(mi1 if \f2capname\f1 is not a boolean capability. The .Fn tigetnum function returns \(mi2 if \f2capname\f1 is not a numeric capability. The .Fn tigetstr function returns (\f3char *\f1)\(mi1 if \f2capname\f1 is not a string capability. .P Upon successful completion, .Fn tparm returns \f2str\f1 with parameterisation resolved. Otherwise, it returns a null pointer. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" For parameterised string capabilities, the application should pass the return value from .Fn tigetstr to .CR tparm() , as described above. .P Applications intending to send terminal capabilities directly to the terminal (which should only be done using .Fn tputs or .CR putp() ) instead of using Curses, normally should obey the following rules: .RS .TP 3 .C \(bu Call .Fn reset_shell_mode to restore the display modes before exiting. .TP .C \(bu If using cursor addressing, output \f3enter_ca_mode\f1 upon startup and output \f3exit_ca_mode\f1 before exiting. .TP .C \(bu If using shell escapes, output .B exit_ca_mode and call .Fn reset_shell_mode before calling the shell; call .Fn reset_prog_mode and output .I enter_ca_mode after returning from the shell. .RE .P All parameterised terminal capabilities defined in this document can be passed to .CR tparm() . Some implementations create their own capabilities, create capabilities for non-terminal devices, and redefine the capabilities in this document. These practices are non-conforming because it may be that .Fn tparm cannot parse these user-defined strings. .SH "SEE ALSO" def_prog_mode(), tgetent(), putp(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3tigetflag(3X)\f1:\0\0\f4tigetflag()\f1, \f4tigetnum()\f1, \f4tigetstr()\f1, \f4tparm()\f1\n@@@retrieve capabilities from the \f4terminfo\f1 database .\" toc@\f4tigetnum()\f1: retrieve capabilities from the \f4terminfo\f1 database@@@see \f3tigetflag(3X)\f1 .\" toc@\f4tigetstr()\f1: retrieve capabilities from the \f4terminfo\f1 database@@@see \f3tigetflag(3X)\f1 .\" toc@\f4tparm()\f1: retrieve capabilities from the \f4terminfo\f1 database@@@see \f3tigetflag(3X)\f1 .\" .\" index@\f4tigetflag()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f4tigetnum()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f4tigetstr()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f4tparm()\f1 \- retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f1retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f1retrieve capabilities from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" index@\f1\f4terminfo\f1 database, retrieve capabilities from@@@\f3tigetflag(3X)\f1 .\" index@\f1capabilities, retrieve from the \f4terminfo\f1 database@@@\f3tigetflag(3X)\f1 .\" .\" links@tigetflag.3x tigetnum.3x .\" links@tigetflag.3x tigetstr.3x .\" links@tigetflag.3x tparm.3x .\" .\" fileset_database@tigetflag.3x CURS-ENG-A-MAN .\" $Header: putp.3x,v 76.2 95/08/01 14:36:10 ssa Exp $ .TA p .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH putp 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME putp, tputs \(em output commands to the terminal .SH SYNOPSIS .C "#include " .P .C "int putp(char *const \f2str\fP);" .P .C "int tputs(char *const \f2str\fP, int \f2affcnt\fP, int (*\f2putfunc\fP)(int));" .SH DESCRIPTION These functions output commands contained in the \f3terminfo\f1 database to the terminal. .P The .Fn putp function is equivalent to \f2tputs\f1(\f2str\fP, 1, \f2putchar\f1). The output of .Fn putp always goes to \f3stdout\fP, not to the \f2fildes\f1 specified in .CR setupterm() . .P The .Fn tputs function outputs \f2str\f1 to the terminal. The \f2str\f1 argument must be a \f3terminfo\f1 string variable or the return value from .CR tgetstr() , .CR tgoto() , .Fn tigetstr or .CR tparm() . The \f2affcnt\f1 argument is the number of lines affected, or 1 if not applicable. If the \f3terminfo\f1 database indicates that the terminal in use requires padding after any command in the generated string, .Fn tputs inserts pad characters into the string that is sent to the terminal, at positions indicated by the \f3terminfo\f1 database. The .Fn tputs function outputs each character of the generated string by calling the user-supplied function .I putfunc (see below). .P The user-supplied function .I putfunc (specified as an argument to .CR tputs ) is either .Fn putchar or some other function with the same prototype. The .Fn tputs function ignores the return value of .I putfunc . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" After use of any of these functions, the model Curses maintains of the state of the terminal might not match the actual state of the terminal. The application should touch and refresh the window before resuming conventional use of Curses. .P Use of these functions requires that the application contain so much information about a particular class of terminal that it defeats the purpose of using Curses. .P On some terminals, a command to change rendition conceptually occupies space in the screen buffer (with or without width). Thus, a command to set the terminal to a new rendition would change the rendition of some characters already displayed. .SH "SEE ALSO" doupdate(), is_linetouched(), putchar() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), tgetent(), tigetflag(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3putp(3X)\f1:\0\0\f4putp()\f1, \f4tputs()\f1@@@output commands to the terminal .\" toc@\f4tputs()\f1: output commands to the terminal@@@see \f3putp(3X)\f1 .\" .\" index@\f4putp()\f1 \- output commands to the terminal@@@\f3putp(3X)\f1 .\" index@\f4tputs()\f1 \- output commands to the terminal@@@\f3putp(3X)\f1 .\" index@\f1output commands to the terminal@@@\f3putp(3X)\f1 .\" index@\f1commands, output to the terminal@@@\f3putp(3X)\f1 .\" index@\f1terminal, output commands to@@@\f3putp(3X)\f1 .\" .\" links@putp.3x tputs.3x .\" .\" fileset_database@putp.3x CURS-ENG-A-MAN .\" $Header: tsearch.3c,v 72.5 94/11/15 09:56:53 ssa Exp $ .TA t .TH tsearch 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tsearch(\|), tfind(\|), tdelete(\|), twalk(\|) \- manage binary search trees .SH SYNOPSIS .C "#include " .PP .C "void *tsearch(" .nf .PD 0 .IP .C "const void *key," .C "void **rootp," .C "int (*compar)(const void *, const void *)" .P .C ");" .PD .PP .C "void *tfind(" .PD 0 .IP .C "const void *key," .C "void * const *rootp," .C "int (*compar)(const void *, const void *)" .P .C ");" .PD .PP .C "void *tdelete(" .PD 0 .IP .C "const void *key," .C "void **rootp," .C "int (*compar)(const void *, const void *)" .PP .C ");" .PD .PP .C "void twalk(" .PD 0 .IP .C "const void *root," .C "void (*action)(const void *, VISIT, int)" .PP .C ");" .PD .fi .SH DESCRIPTION .CR tsearch() , .CR tfind() , .CR tdelete() , and .C twalk() are routines for manipulating binary search trees. They are generalized from Knuth (6.2.2) Algorithms T and D. All comparisons are done with a user-supplied routine, .IR compar . This routine is called with two arguments, the pointers to the elements being compared. It returns an integer less than, equal to, or greater than 0, according to whether the first argument is to be considered less than, equal to or greater than the second argument. The comparison function need not compare every byte, so arbitrary data may be contained in the elements in addition to the values being compared. .PP .C tsearch() is used to build and access the tree. .I key is a pointer to an entry to be accessed or stored. If there is an entry in the tree equal to the value pointed to by .IR key , a pointer to the previous key associated with this found entry is returned. Otherwise, .I key is inserted, and a pointer to it returned. Note that since the value returned is a pointer to .I key and .I key itself is a pointer, the value returned is a pointer to a pointer. Only pointers are copied, so the calling routine must store the data. .I rootp points to a variable that points to the root of the tree. A .SM NULL value for the variable pointed to by .I rootp denotes an empty tree; in this case, the variable is set to point to the entry which will be at the root of the new tree. .PP Like .CR tsearch() , .C tfind() searches for an entry in the tree, returning a pointer to it if found. However, if it is not found, .C tfind() returns a .SM NULL pointer. The arguments for .C tfind() are the same as for .CR tsearch() . .PP .C tdelete() deletes a node from a binary search tree. Arguments are the same as for .CR tsearch() . The variable pointed to by .I rootp is changed if the deleted node was the root of the tree. .C tdelete() returns a pointer to the parent of the deleted node, or a .SM NULL pointer if the node is not found. .PP .C twalk() traverses a binary search tree. .I root is the root of the tree to be traversed. (Any node in a tree may be used as the root for a walk below that node.) .I action is the name of a routine to be invoked at each node. This routine is, in turn, called with three arguments: .RS .TP 3 \(bu First argument is the address of the node being visited. .TP \(bu Second argument is a value from an enumeration data type .C "typedef enum { preorder, postorder, endorder, leaf }" .C VISIT; (defined in the .RC < search.h > header file), depending on whether this is the first, second or third time that the node has been visited (during a depth-first, left-to-right traversal of the tree), or whether the node is a leaf. .TP \(bu Third argument is the level of the node in the tree, with the root being level zero. .RE .SH EXAMPLE The following code reads strings, and stores structures containing a pointer to each string and a count of its length. It then walks the tree, printing out the stored strings and their lengths in alphabetical order. .nf .IP .C "#include " .C "#include " .C "#include " .C "#include " .IP .C "struct element /* pointers to these are stored in the tree */" .C { .C " char *string;" .C " int length;" .C " };" .C "char string_space[10000]; /* space to store strings */" .C "struct element elements[500]; /* elements to store */" .C "struct element *root = NULL; /* this points to the root */" .C " .C "void print_node(void *, VISIT, int);" .C "int element_compare(const void *, const void *);" .IP .C "main( )" .C { .C " char *strptr = string_space;" .C " struct element *element_ptr = elements;" .C " struct element **ts_retval;" .IP .C " int i = 0;" .IP .C " while (gets(strptr) != NULL && i++ < 500)" .C " {" .IP .C " /* set element */" .C " element_ptr->string = strptr;" .C " element_ptr->length = strlen(strptr);" .IP .C " /* put element into the tree */" .C " ts_retval = (struct element **) tsearch((void *) element_ptr," .C " (void **) &root, element_compare);" .IP .C " if (*ts_retval == element_ptr)" .C " { .ift .ft 4 .ps +1 .ifn .ft 3 (void) printf("The element \e"%s\e" ", (*ts_retval)->string); (void) printf("has now been inserted into the tree\en"); .ps .ft .C " }" .C " else" .C " {" .ift .ft 4 .ps +1 .ifn .ft 3 (void) printf("The element \e"%s\e" ", (*ts_retval)->string); (void) printf("already existed in the tree\en"); .ps .ft .C " }" .IP .C " /* adjust pointers, so we don't overwrite tree */" .C " strptr += element_ptr->length + 1;" .C " element_ptr++;" .C " }" .C " twalk((void *) root, print_node);" .C } .C "/* This routine compares two elements, based on an" .C " alphabetical ordering of the string field. */" .C int .C "element_compare(elem1, elem2)" .C "void *elem1, *elem2;" .C { .C " return strcmp(((struct element *) elem1)->string," .C " ((struct element *) elem2)->string);" .C } .C "/* This routine prints out a node, the first time" .C " twalk encounters it. */" .C void .C "print_node(element, order, level)" .C "void *element;" .C "VISIT order;" .C "int level;" .C { .C " if (order == preorder || order == leaf)" .C " {" .ift .ft 4 .ps +1 .ifn .ft 3 (void) printf("string = %20s, length = %d\en", .ps .ft .C " (*(struct element **) element)->string," .C " (*(struct element **) element)->length);" .C " }" .C } .fi .RE .SH SEE ALSO bsearch(3C), hsearch(3C), lsearch(3C). .SH RETURN VALUE A .SM NULL pointer is returned by .C tsearch() if there is not enough space available to create a new node. .PP A .SM NULL pointer is returned by .CR tsearch() , .CR tfind() , and .C tdelete() if .I rootp is .SM NULL on entry. .PP If the datum is found, both .C tsearch() and .C tfind() return a pointer to it. If not, .C tfind() returns .SM NULL, and .C tsearch() returns a pointer to the inserted item. .SH WARNINGS The .I root argument to .C twalk() is one level of indirection less than the .I rootp arguments to .C tsearch() and .CR tdelete() . .PP Two nomenclatures are used to refer to the order in which tree nodes are visited. .C tsearch() uses preorder, postorder and endorder to respectively refer to visiting a node before any of its children, after its left child and before its right and after both its children. The alternate nomenclature uses preorder, inorder, and postorder to refer to the same visits, which could result in some confusion over the meaning of postorder. If the calling function alters the pointer to the root, results are unpredictable. .SH STANDARDS CONFORMANCE .CR tsearch() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR tdelete() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR tfind() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR twalk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4tsearch()\fP \- build and access a binary search tree@@@\f3tsearch(3C)\f1 .\" index@\f4tfind()\fP \- get data pointer for binary search tree@@@\f3tsearch(3C)\f1 .\" index@\f4tdelete()\fP \- delete a node from a binary search tree@@@\f3tsearch(3C)\f1 .\" index@\f4twalk()\fP \- traverse a binary search tree@@@\f3tsearch(3C)\f1 .\" index@build or access a binary search tree@@@\f3tsearch(3C)\f1 .\" index@access or build a binary search tree@@@\f3tsearch(3C)\f1 .\" index@get: data pointer for binary search tree@@@\f3tsearch(3C)\f1 .\" index@data pointer for binary search tree, get@@@\f3tsearch(3C)\f1 .\" index@pointer for binary search tree, get data@@@\f3tsearch(3C)\f1 .\" index@delete a node from a binary search tree@@@\f3tsearch(3C)\f1 .\" index@node from a binary search tree, delete a@@@\f3tsearch(3C)\f1 .\" index@traverse a binary search tree@@@\f3tsearch(3C)\f1 .\" index@manage a binary search tree@@@\f3tsearch(3C)\f1 .\" index@binary search tree, manage a@@@\f3tsearch(3C)\f1 .\" index@search tree, manage a binary@@@\f3tsearch(3C)\f1 .\" index@tree, manage a binary search@@@\f3tsearch(3C)\f1 .\" .\" toc@\f3tsearch(3C)\f1:\0\0\f4tsearch()\fP, \f4tfind()\fP, \f4tdelete()\fP, \f4twalk()\fP@@@manage binary search trees .\" toc@\f4tfind()\fP:\0\0manage binary search trees@@@see \f3tsearch(3C)\f1 .\" toc@\f4tdelete()\fP:\0\0manage binary search trees@@@see \f3tsearch(3C)\f1 .\" toc@\f4twalk()\fP:\0\0manage binary search trees@@@see \f3tsearch(3C)\f1 .\" .\" links@tsearch.3c tfind.3c .\" links@tsearch.3c tdelete.3c .\" links@tsearch.3c twalk.3c .\" .\" fileset_database@tsearch.3c PROGRAMING-MAN .\" $Header: ttyname.3c,v 76.1 95/07/05 17:53:09 ssa Exp $ .TA t .TH ttyname 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ttyname(\|), ttyname_r(\|), isatty(\|) \- find name of a terminal .SH SYNOPSIS .C "#include " .P .C "char *ttyname(int fildes);" .PP .C "int ttyname_r(int fildes, char *buffer, int buflen);" .P .C "int isatty(int fildes);" .SH DESCRIPTION .CR ttyname() returns a pointer to a string containing the null-terminated path name of the terminal device associated with file descriptor .IR fildes . .PP .CR isatty() returns 1 if .I fildes is associated with a terminal device, 0 otherwise. .SS Reentrant Interfaces .CR ttyname_r() returns the result string in the supplied buffer. A buffer length of 64 is recommended. If an error is detected or the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .SH RETURN VALUE .CR ttyname() returns a .SM NULL pointer if .I fildes does not describe a terminal device in directory .CR /dev . .SH ERRORS .CR isatty() and .CR ttyname() fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] The .IR fildes argument is invalid. .TP .SM [ENOTTY] An inappropriate .SM I/O control operation has been attempted. .SH WARNINGS The return value for .CR ttyname() points to static data whose content is overwritten by each call. For streams ptys, .CR ttyname() and .CR isatty() do not consider master ptys to be tty devices. It should also be noted that .CR ttyname() returns a pointer to the master pty name for all master pty devices. This is a result of device files being linked together. .PP .CR ttyname() is unsafe for multi-thread applications. .CR ttyname_r() is MT-Safe and should be used instead. .PP Users of .CR ttyname_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH FILES .CR /dev/* .br .CR /dev/pty/* .SH STANDARDS CONFORMANCE .CR ttyname() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR isatty() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4ttyname()\fP, \f4isatty()\fP \- find name of a terminal@@@\f3ttyname(3C)\f1 .\" index@\f4isatty()\fP \- find name of a terminal@@@\f3ttyname(3C)\f1 .\" index@find name of a terminal@@@\f3ttyname(3C)\f1 .\" index@name: find name of a terminal@@@\f3ttyname(3C)\f1 .\" index@terminal, find name of@@@\f3ttyname(3C)\f1 .\" .\" toc@\f3ttyname(3C)\f1:\0\0\f4ttyname()\fP, \f4isatty()\fP@@@find name of a terminal .\" toc@\f4isatty()\fP:\0\0find name of a terminal@@@see \f3ttyname(3C)\f1 .\" .\" links@ttyname.3c isatty.3c .\" links@ttyname.3c ttyname_r.3c .\" $Header: ttyname.3c,v 76.1 95/07/05 17:53:09 ssa Exp $ .TA t .TH ttyname 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ttyname(\|), ttyname_r(\|), isatty(\|) \- find name of a terminal .SH SYNOPSIS .C "#include " .P .C "char *ttyname(int fildes);" .PP .C "int ttyname_r(int fildes, char *buffer, int buflen);" .P .C "int isatty(int fildes);" .SH DESCRIPTION .CR ttyname() returns a pointer to a string containing the null-terminated path name of the terminal device associated with file descriptor .IR fildes . .PP .CR isatty() returns 1 if .I fildes is associated with a terminal device, 0 otherwise. .SS Reentrant Interfaces .CR ttyname_r() returns the result string in the supplied buffer. A buffer length of 64 is recommended. If an error is detected or the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. .SH RETURN VALUE .CR ttyname() returns a .SM NULL pointer if .I fildes does not describe a terminal device in directory .CR /dev . .SH ERRORS .CR isatty() and .CR ttyname() fail if any of the following conditions are encountered: .RS .TP 20 .SM [EBADF] The .IR fildes argument is invalid. .TP .SM [ENOTTY] An inappropriate .SM I/O control operation has been attempted. .SH WARNINGS The return value for .CR ttyname() points to static data whose content is overwritten by each call. For streams ptys, .CR ttyname() and .CR isatty() do not consider master ptys to be tty devices. It should also be noted that .CR ttyname() returns a pointer to the master pty name for all master pty devices. This is a result of device files being linked together. .PP .CR ttyname() is unsafe for multi-thread applications. .CR ttyname_r() is MT-Safe and should be used instead. .PP Users of .CR ttyname_r() should also note that the prototype of this function will change in the next release for conformance with the new POSIX Threads standard. .SH FILES .CR /dev/* .br .CR /dev/pty/* .SH STANDARDS CONFORMANCE .CR ttyname() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR isatty() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4ttyname()\fP, \f4isatty()\fP \- find name of a terminal@@@\f3ttyname(3C)\f1 .\" index@\f4isatty()\fP \- find name of a terminal@@@\f3ttyname(3C)\f1 .\" index@find name of a terminal@@@\f3ttyname(3C)\f1 .\" index@name: find name of a terminal@@@\f3ttyname(3C)\f1 .\" index@terminal, find name of@@@\f3ttyname(3C)\f1 .\" .\" toc@\f3ttyname(3C)\f1:\0\0\f4ttyname()\fP, \f4isatty()\fP@@@find name of a terminal .\" toc@\f4isatty()\fP:\0\0find name of a terminal@@@see \f3ttyname(3C)\f1 .\" .\" links@ttyname.3c isatty.3c .\" links@ttyname.3c ttyname_r.3c .\" $Header: ttyslot.3c,v 72.5 94/11/15 09:56:56 ssa Exp $ .TA t .TH ttyslot 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ttyslot(\|) \- find the slot in the utmp file of the current user .SH SYNOPSIS .C "#include " .PP .C "int ttyslot(void);" .SH DESCRIPTION .C ttyslot() returns the index of the current user's entry in the .C /etc/utmp file. This is accomplished by scanning .C /etc/utmp for the name of the terminal associated with the standard input, standard output, or standard error (file descriptor 0, 1 or 2). .SH RETURN VALUE .C ttyslot() returns \-1 if an error was encountered while searching for the terminal name or if none of file descriptors 0, 1, or 2 is associated with a terminal device. .SH FILES /etc/utmp .SH SEE ALSO getut(3C), ttyname(3C). .SH STANDARDS CONFORMANCE .CR ttyslot() ": XPG2" .\" .\" index@\f4ttyslot()\fP \- find the slot in the \f4utmp()\fP file of the current user@@@\f3ttyslot(3C)\f1 .\" index@find the slot in the \f4utmp()\fP file of the current user@@@\f3ttyslot(3C)\f1 .\" index@slot in the \f4utmp()\fP file of the current user, find@@@\f3ttyslot(3C)\f1 .\" index@\f4utmp()\fP file of the current user, find the slot in the@@@\f3ttyslot(3C)\f1 .\" index@file, \f4utmp()\fP, of the current user, find the slot in the@@@\f3ttyslot(3C)\f1 .\" index@current user, find the slot in the \f4utmp()\fP file of the@@@\f3ttyslot(3C)\f1 .\" index@user, current, find the slot in the \f4utmp()\fP file of the@@@\f3ttyslot(3C)\f1 .\" .\" toc@\f3ttyslot(3C)\f1:\0\0\f4ttyslot()\fP@@@find the slot in the utmp file of the current user .\" .\" fileset_database@ttyslot.3c PROGRAMING-MAN .\" $Header: tsearch.3c,v 72.5 94/11/15 09:56:53 ssa Exp $ .TA t .TH tsearch 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME tsearch(\|), tfind(\|), tdelete(\|), twalk(\|) \- manage binary search trees .SH SYNOPSIS .C "#include " .PP .C "void *tsearch(" .nf .PD 0 .IP .C "const void *key," .C "void **rootp," .C "int (*compar)(const void *, const void *)" .P .C ");" .PD .PP .C "void *tfind(" .PD 0 .IP .C "const void *key," .C "void * const *rootp," .C "int (*compar)(const void *, const void *)" .P .C ");" .PD .PP .C "void *tdelete(" .PD 0 .IP .C "const void *key," .C "void **rootp," .C "int (*compar)(const void *, const void *)" .PP .C ");" .PD .PP .C "void twalk(" .PD 0 .IP .C "const void *root," .C "void (*action)(const void *, VISIT, int)" .PP .C ");" .PD .fi .SH DESCRIPTION .CR tsearch() , .CR tfind() , .CR tdelete() , and .C twalk() are routines for manipulating binary search trees. They are generalized from Knuth (6.2.2) Algorithms T and D. All comparisons are done with a user-supplied routine, .IR compar . This routine is called with two arguments, the pointers to the elements being compared. It returns an integer less than, equal to, or greater than 0, according to whether the first argument is to be considered less than, equal to or greater than the second argument. The comparison function need not compare every byte, so arbitrary data may be contained in the elements in addition to the values being compared. .PP .C tsearch() is used to build and access the tree. .I key is a pointer to an entry to be accessed or stored. If there is an entry in the tree equal to the value pointed to by .IR key , a pointer to the previous key associated with this found entry is returned. Otherwise, .I key is inserted, and a pointer to it returned. Note that since the value returned is a pointer to .I key and .I key itself is a pointer, the value returned is a pointer to a pointer. Only pointers are copied, so the calling routine must store the data. .I rootp points to a variable that points to the root of the tree. A .SM NULL value for the variable pointed to by .I rootp denotes an empty tree; in this case, the variable is set to point to the entry which will be at the root of the new tree. .PP Like .CR tsearch() , .C tfind() searches for an entry in the tree, returning a pointer to it if found. However, if it is not found, .C tfind() returns a .SM NULL pointer. The arguments for .C tfind() are the same as for .CR tsearch() . .PP .C tdelete() deletes a node from a binary search tree. Arguments are the same as for .CR tsearch() . The variable pointed to by .I rootp is changed if the deleted node was the root of the tree. .C tdelete() returns a pointer to the parent of the deleted node, or a .SM NULL pointer if the node is not found. .PP .C twalk() traverses a binary search tree. .I root is the root of the tree to be traversed. (Any node in a tree may be used as the root for a walk below that node.) .I action is the name of a routine to be invoked at each node. This routine is, in turn, called with three arguments: .RS .TP 3 \(bu First argument is the address of the node being visited. .TP \(bu Second argument is a value from an enumeration data type .C "typedef enum { preorder, postorder, endorder, leaf }" .C VISIT; (defined in the .RC < search.h > header file), depending on whether this is the first, second or third time that the node has been visited (during a depth-first, left-to-right traversal of the tree), or whether the node is a leaf. .TP \(bu Third argument is the level of the node in the tree, with the root being level zero. .RE .SH EXAMPLE The following code reads strings, and stores structures containing a pointer to each string and a count of its length. It then walks the tree, printing out the stored strings and their lengths in alphabetical order. .nf .IP .C "#include " .C "#include " .C "#include " .C "#include " .IP .C "struct element /* pointers to these are stored in the tree */" .C { .C " char *string;" .C " int length;" .C " };" .C "char string_space[10000]; /* space to store strings */" .C "struct element elements[500]; /* elements to store */" .C "struct element *root = NULL; /* this points to the root */" .C " .C "void print_node(void *, VISIT, int);" .C "int element_compare(const void *, const void *);" .IP .C "main( )" .C { .C " char *strptr = string_space;" .C " struct element *element_ptr = elements;" .C " struct element **ts_retval;" .IP .C " int i = 0;" .IP .C " while (gets(strptr) != NULL && i++ < 500)" .C " {" .IP .C " /* set element */" .C " element_ptr->string = strptr;" .C " element_ptr->length = strlen(strptr);" .IP .C " /* put element into the tree */" .C " ts_retval = (struct element **) tsearch((void *) element_ptr," .C " (void **) &root, element_compare);" .IP .C " if (*ts_retval == element_ptr)" .C " { .ift .ft 4 .ps +1 .ifn .ft 3 (void) printf("The element \e"%s\e" ", (*ts_retval)->string); (void) printf("has now been inserted into the tree\en"); .ps .ft .C " }" .C " else" .C " {" .ift .ft 4 .ps +1 .ifn .ft 3 (void) printf("The element \e"%s\e" ", (*ts_retval)->string); (void) printf("already existed in the tree\en"); .ps .ft .C " }" .IP .C " /* adjust pointers, so we don't overwrite tree */" .C " strptr += element_ptr->length + 1;" .C " element_ptr++;" .C " }" .C " twalk((void *) root, print_node);" .C } .C "/* This routine compares two elements, based on an" .C " alphabetical ordering of the string field. */" .C int .C "element_compare(elem1, elem2)" .C "void *elem1, *elem2;" .C { .C " return strcmp(((struct element *) elem1)->string," .C " ((struct element *) elem2)->string);" .C } .C "/* This routine prints out a node, the first time" .C " twalk encounters it. */" .C void .C "print_node(element, order, level)" .C "void *element;" .C "VISIT order;" .C "int level;" .C { .C " if (order == preorder || order == leaf)" .C " {" .ift .ft 4 .ps +1 .ifn .ft 3 (void) printf("string = %20s, length = %d\en", .ps .ft .C " (*(struct element **) element)->string," .C " (*(struct element **) element)->length);" .C " }" .C } .fi .RE .SH SEE ALSO bsearch(3C), hsearch(3C), lsearch(3C). .SH RETURN VALUE A .SM NULL pointer is returned by .C tsearch() if there is not enough space available to create a new node. .PP A .SM NULL pointer is returned by .CR tsearch() , .CR tfind() , and .C tdelete() if .I rootp is .SM NULL on entry. .PP If the datum is found, both .C tsearch() and .C tfind() return a pointer to it. If not, .C tfind() returns .SM NULL, and .C tsearch() returns a pointer to the inserted item. .SH WARNINGS The .I root argument to .C twalk() is one level of indirection less than the .I rootp arguments to .C tsearch() and .CR tdelete() . .PP Two nomenclatures are used to refer to the order in which tree nodes are visited. .C tsearch() uses preorder, postorder and endorder to respectively refer to visiting a node before any of its children, after its left child and before its right and after both its children. The alternate nomenclature uses preorder, inorder, and postorder to refer to the same visits, which could result in some confusion over the meaning of postorder. If the calling function alters the pointer to the root, results are unpredictable. .SH STANDARDS CONFORMANCE .CR tsearch() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR tdelete() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR tfind() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR twalk() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .\" .\" index@\f4tsearch()\fP \- build and access a binary search tree@@@\f3tsearch(3C)\f1 .\" index@\f4tfind()\fP \- get data pointer for binary search tree@@@\f3tsearch(3C)\f1 .\" index@\f4tdelete()\fP \- delete a node from a binary search tree@@@\f3tsearch(3C)\f1 .\" index@\f4twalk()\fP \- traverse a binary search tree@@@\f3tsearch(3C)\f1 .\" index@build or access a binary search tree@@@\f3tsearch(3C)\f1 .\" index@access or build a binary search tree@@@\f3tsearch(3C)\f1 .\" index@get: data pointer for binary search tree@@@\f3tsearch(3C)\f1 .\" index@data pointer for binary search tree, get@@@\f3tsearch(3C)\f1 .\" index@pointer for binary search tree, get data@@@\f3tsearch(3C)\f1 .\" index@delete a node from a binary search tree@@@\f3tsearch(3C)\f1 .\" index@node from a binary search tree, delete a@@@\f3tsearch(3C)\f1 .\" index@traverse a binary search tree@@@\f3tsearch(3C)\f1 .\" index@manage a binary search tree@@@\f3tsearch(3C)\f1 .\" index@binary search tree, manage a@@@\f3tsearch(3C)\f1 .\" index@search tree, manage a binary@@@\f3tsearch(3C)\f1 .\" index@tree, manage a binary search@@@\f3tsearch(3C)\f1 .\" .\" toc@\f3tsearch(3C)\f1:\0\0\f4tsearch()\fP, \f4tfind()\fP, \f4tdelete()\fP, \f4twalk()\fP@@@manage binary search trees .\" toc@\f4tfind()\fP:\0\0manage binary search trees@@@see \f3tsearch(3C)\f1 .\" toc@\f4tdelete()\fP:\0\0manage binary search trees@@@see \f3tsearch(3C)\f1 .\" toc@\f4twalk()\fP:\0\0manage binary search trees@@@see \f3tsearch(3C)\f1 .\" .\" links@tsearch.3c tfind.3c .\" links@tsearch.3c tdelete.3c .\" links@tsearch.3c twalk.3c .\" .\" fileset_database@tsearch.3c PROGRAMING-MAN .\" $Header: typeahead.3x,v 76.2 95/08/01 14:56:45 ssa Exp $ .TA t .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH typeahead 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME typeahead \(em control checking for typeahead .SH SYNOPSIS .C "#include " .P .C "int typeahead(int \f2fildes\fP);" .SH DESCRIPTION The .Fn typeahead function controls the detection of typeahead during a refresh, based on the value of \f2fildes\fP: .RS .TP 3 .C \(bu If \f2fildes\f1 is a valid file descriptor, typeahead is enabled during refresh; Curses periodically checks \f2fildes\f1 for input and aborts the refresh if any character is available. (This is the initial setting, and the typeahead file descriptor corresponds to the input file associated with the screen created by .Fn initscr or .CR newterm() .) The value of \f2fildes\f1 need not be the file descriptor on which the refresh is occurring. .TP .C \(bu If \f2fildes\f1 is \(mi1, Curses does not check for typeahead during refresh. .RE .SH "RETURN VALUE" Upon successful completion, .Fn typeahead returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, doupdate(), getch(), initscr(), , \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Section 9.2, \f3Parameters That Can Be Set\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The .B "RETURN VALUE" section now states that the function returns OK on success and ERR on failure. No return values were defined in previous issues. .\" .\" index@\f4typeahead()\f1 \- control checking for typeahead@@@\f3typeahead(3X)\f1 .\" index@\f1control checking for typeahead@@@\f3typeahead(3X)\f1 .\" index@\f1typeahead, control checking for@@@\f3typeahead(3X)\f1 .\" .\" toc@\f3typeahead(3X)\f1:\0\0\f4typeahead()\f1@@@control checking for typeahead .\" .\" fileset_database@typeahead.3x CURS-ENG-A-MAN .\" $Header: ctime.3c,v 76.1 95/07/05 17:27:14 ssa Exp $ .TA c .TH ctime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctime(\|), ctime_r(\|), localtime(\|), localtime_r(\|), gmtime(\|), gmtime_r(\|), mktime(\|), difftime(\|), asctime(\|), asctime_r(\|), timezone(\|), daylight(\|), tzname(\|), tzset(\|) \- convert date and time to string .SH SYNOPSIS .nf .C "#include " .PP .C "char *asctime(const struct tm *timeptr);" .PP .C "int asctime_r(const struct tm *timeptr, char *buffer, int buflen);" .PP .C "char *ctime(const time_t *timer);" .PP .C "int ctime_r(const time_t *timer, char *buffer, int buflen);" .PP .C "double difftime(time_t time1, time_t time0);" .PP .C "struct tm *gmtime(const time_t *timer);" .PP .C "int gmtime_r(const time_t *timer, struct tm *result);" .PP .C "struct tm *localtime(const time_t *timer);" .PP .C "int localtime_r(const time_t *timer, struct tm *result);" .PP .C "time_t mktime(struct tm *timeptr);" .PP .C "extern long timezone;" .PP .C "extern int daylight;" .PP .C "extern char *tzname[2];" .PP .C "void tzset(void);" .fi .SH DESCRIPTION .TP 18 .C asctime() Convert the broken-down time contained in the structure pointed to by .I timeptr and return a pointer to a 26-character string in the form: .RS .IP .C "Sun Sep 16 01:03:52 1973\en\e0" .RE .IP All the fields have constant width. .TP .C asctime_r() is identical to .CR asctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C ctime() Convert the calendar time pointed to by .IR timer , representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: .RS .IP .C asctime(localtime(timer)) .RE .TP .C ctime_r() is identical to .CR ctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C gmtime() Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. .C gmtime() returns a pointer to the .C tm structure described below. .TP .C gmtime_r() is identical to .CR gmtime() , except that .C gmtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C localtime() Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA\c), according to the contents of the TZ environment variable (see Environment Variables below). .C localtime() returns a pointer to the .C tm structure described below. .TP .C localtime_r() is identical to .CR localtime() , except that .C localtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C difftime() Return the difference in seconds between two calendar times: .IR "time1 \(mi time0" . .TP .C mktime() Convert the broken-down time (expressed as local time) in the structure pointed to by .I timeptr into a calendar time value with the same encoding as that of the values returned by .IR time (2). The original values of the .C tm_wday and .C tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below. .IP A positive or zero value for .C tm_isdst causes .C mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for .C tm_isdst causes .C mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time. .IP Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of .C tm_mday is not set until .C tm_mon and .C tm_year are determined. .C mktime() returns the specified calendar time encoded as a value of type .CR time_t . .IP If the calendar time cannot be represented, the function returns the value .RC ( time_t )\|\(em\|1 and sets .C errno to .CR ERANGE . Note the value .RC ( time_t )\|\(em\|1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and .C errno to reliably detect an error condition. .TP .C tzset() Sets the values of the external variables .IR timezone , .IR daylight , and .I tzname according to the contents of the .C TZ environment variable (independent of any time value). The functions .CR localtime() , .CR mktime() , .CR ctime() , .CR asctime() , and .C strftime() (see .IR strftime (3C)) call .C tzset() and use the values returned in the external variables described below for their operations. .C tzset() can also be called directly by the user. .PP The .RC < time.h > header file contains declarations of all relevant functions and externals. It also contains the .C tm structure, which includes the following members: .RS .PP .nf .ift .ft 4 .ps +1 int tm_sec; /* seconds after the minute - [0,61] */ int tm_min; /* minutes after the hour - [0,59] */ int tm_hour; /* hours - [0,23] */ int tm_mday; /* day of month - [1,31] */ int tm_mon; /* month of year - [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday - [0,6] */ int tm_yday; /* days since January 1 - [0,365] */ int tm_isdst; /* daylight savings time flag */ .ift .ft .ps .fi .PP The value of .C tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available. .RE .PP The external variable .C timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), .C timezone is 5\(**60\(**60). The external variable .C daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable .C tzname[2] contains the local standard and local summer time zone abbreviations as specified by the .C TZ environment variable. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .SS Environment Variables The .C tzset() function uses the contents of .C TZ to set the values of the external variables .CR timezone , .C daylight , and .CR tzname . .C TZ also determines the time zone name substituted for the .C %Z and .C %z directives and the time zone adjustments performed by .CR localtime() , .CR mktime() , and .CR ctime() . Two methods for specifying a time zone within .C TZ are described in .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH "RETURN VALUE" .PP For .C asctime_r() and .C ctime_r(), if the buffer is of insufficient length, -1 is returned. For .C asctime_r(), ctime_r(), gmtime_r(), and .C localtime_r(), if the operation is successful, 0 is returned. .SH WARNINGS The return values for .CR asctime() , .CR ctime() , .CR gmtime() , and .CR localtime() point to static data whose contents is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() are MT-Safe and should be used instead. .PP Users of .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .PP The range of .C tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by .IR time (2) and passed as the .I timer argument does not include accumulated leap seconds. The .C tm structure generated by .C localtime() and .C gmtime() will never reflect any leap seconds. Upon successful completion, .C mktime() forces the value of the .C tm_sec component to the range [0,59]. .PP .CR ctime() , .CR ctime_r() , .CR asctime() , and .CR asctime_r() are considered obsolescent and may be removed in a future release. Use of .IR strftime (3C) is recommended instead. .SH AUTHOR .C ctime() was developed by AT&T and HP. .SH SEE ALSO time(2), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR ctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR asctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR daylight ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR difftime() ": AES, SVID3, XPG4, ANSI C" .PP .CR gmtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR localtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mktime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR timezone ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR tzname ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tzset() ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4asctime()\fP, \f4asctime_r()\f1 \- convert \f3tm\f1 structure date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4ctime()\fP, \f4ctime_r()\f1 \- convert \f4clock()\fP date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4daylight()\fP \- Daylight Savings Time flag@@@\f3ctime(3C)\f1 .\" index@\f4gmtime()\fP, \f4gmtime_r()\fP \- convert date and time to Greenwich Mean Time@@@\f3ctime(3C)\f1 .\" index@\f4localtime()\fP, \f4localtime_r()\fP \- convert date and time to local timezone@@@\f3ctime(3C)\f1 .\" index@\f4timezone()\fP \- difference between \s-1UCT\s+1 and local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzname()\fP \- name of local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzset()\fP \- initialize \f4timezone()\fP, \f4daylight()\fP, and \f4tzname()\fP using \s-1TZ\s+1 variable@@@\f3ctime(3C)\f1 .\" index@\f4mktime()\fP \- convert time into calendar time value@@@\f3ctime(3C)\f1 .\" index@\f4difftime()\fP \- difference between two calendar time values@@@\f3ctime(3C)\f1 .\" index@convert date and time to string@@@\f3ctime(3C)\f1 .\" index@string, convert date and time to@@@\f3ctime(3C)\f1 .\" index@date and time, convert to string@@@\f3ctime(3C)\f1 .\" index@time and date, convert to string@@@\f3ctime(3C)\f1 .\" .\" toc@\f3ctime(3C)\f1:\0\0\f4ctime()\fP, \f4ctime_r()\fP, \f4localtime()\fP, \f4localtime_r()\fP, \f4difftime()\f1, \f4 mktime()\f1, \n\f4gmtime()\fP, \f4gmtime_r()\fP,\f4asctime()\fP, \f4asctime_r()\fP, \f4timezone()\fP, \f4daylight()\fP, \f4tzname()\fP,\n\f4tzset()\f1@@@convert date and time to string .\" toc@\f4ctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4ctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4timezone()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4daylight()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzname()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzset()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4difftime()\fP:\0\0difference between calendar times@@@see \f3ctime(3C)\f1 .\" toc@\f4mktime()\fP:\0\0create calendar time value@@@see \f3ctime(3C)\f1 .\" .\" links@ctime.3c ctime_r.3c .\" links@ctime.3c localtime.3c .\" links@ctime.3c localtime_r.3c .\" links@ctime.3c gmtime.3c .\" links@ctime.3c gmtime_r.3c .\" links@ctime.3c asctime.3c .\" links@ctime.3c asctime_r.3c .\" links@ctime.3c timezone.3c .\" links@ctime.3c daylight.3c .\" links@ctime.3c tzname.3c .\" links@ctime.3c tzset.3c .\" links@ctime.3c difftime.3c .\" links@ctime.3c mktime.3c .\" .\" fileset_database@ctime.3c PROGRAMING-MAN .\" $Header: ctime.3c,v 76.1 95/07/05 17:27:14 ssa Exp $ .TA c .TH ctime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ctime(\|), ctime_r(\|), localtime(\|), localtime_r(\|), gmtime(\|), gmtime_r(\|), mktime(\|), difftime(\|), asctime(\|), asctime_r(\|), timezone(\|), daylight(\|), tzname(\|), tzset(\|) \- convert date and time to string .SH SYNOPSIS .nf .C "#include " .PP .C "char *asctime(const struct tm *timeptr);" .PP .C "int asctime_r(const struct tm *timeptr, char *buffer, int buflen);" .PP .C "char *ctime(const time_t *timer);" .PP .C "int ctime_r(const time_t *timer, char *buffer, int buflen);" .PP .C "double difftime(time_t time1, time_t time0);" .PP .C "struct tm *gmtime(const time_t *timer);" .PP .C "int gmtime_r(const time_t *timer, struct tm *result);" .PP .C "struct tm *localtime(const time_t *timer);" .PP .C "int localtime_r(const time_t *timer, struct tm *result);" .PP .C "time_t mktime(struct tm *timeptr);" .PP .C "extern long timezone;" .PP .C "extern int daylight;" .PP .C "extern char *tzname[2];" .PP .C "void tzset(void);" .fi .SH DESCRIPTION .TP 18 .C asctime() Convert the broken-down time contained in the structure pointed to by .I timeptr and return a pointer to a 26-character string in the form: .RS .IP .C "Sun Sep 16 01:03:52 1973\en\e0" .RE .IP All the fields have constant width. .TP .C asctime_r() is identical to .CR asctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C ctime() Convert the calendar time pointed to by .IR timer , representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to: .RS .IP .C asctime(localtime(timer)) .RE .TP .C ctime_r() is identical to .CR ctime() , except that the result is returned in the supplied buffer. A buffer length of 26 is recommended. .TP .C gmtime() Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. .C gmtime() returns a pointer to the .C tm structure described below. .TP .C gmtime_r() is identical to .CR gmtime() , except that .C gmtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C localtime() Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA\c), according to the contents of the TZ environment variable (see Environment Variables below). .C localtime() returns a pointer to the .C tm structure described below. .TP .C localtime_r() is identical to .CR localtime() , except that .C localtime_r() expects to be passed the address of a .C "tm struct" and will store the result at the supplied address. .TP .C difftime() Return the difference in seconds between two calendar times: .IR "time1 \(mi time0" . .TP .C mktime() Convert the broken-down time (expressed as local time) in the structure pointed to by .I timeptr into a calendar time value with the same encoding as that of the values returned by .IR time (2). The original values of the .C tm_wday and .C tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below. .IP A positive or zero value for .C tm_isdst causes .C mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for .C tm_isdst causes .C mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time. .IP Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of .C tm_mday is not set until .C tm_mon and .C tm_year are determined. .C mktime() returns the specified calendar time encoded as a value of type .CR time_t . .IP If the calendar time cannot be represented, the function returns the value .RC ( time_t )\|\(em\|1 and sets .C errno to .CR ERANGE . Note the value .RC ( time_t )\|\(em\|1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and .C errno to reliably detect an error condition. .TP .C tzset() Sets the values of the external variables .IR timezone , .IR daylight , and .I tzname according to the contents of the .C TZ environment variable (independent of any time value). The functions .CR localtime() , .CR mktime() , .CR ctime() , .CR asctime() , and .C strftime() (see .IR strftime (3C)) call .C tzset() and use the values returned in the external variables described below for their operations. .C tzset() can also be called directly by the user. .PP The .RC < time.h > header file contains declarations of all relevant functions and externals. It also contains the .C tm structure, which includes the following members: .RS .PP .nf .ift .ft 4 .ps +1 int tm_sec; /* seconds after the minute - [0,61] */ int tm_min; /* minutes after the hour - [0,59] */ int tm_hour; /* hours - [0,23] */ int tm_mday; /* day of month - [1,31] */ int tm_mon; /* month of year - [0,11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday - [0,6] */ int tm_yday; /* days since January 1 - [0,365] */ int tm_isdst; /* daylight savings time flag */ .ift .ft .ps .fi .PP The value of .C tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available. .RE .PP The external variable .C timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), .C timezone is 5\(**60\(**60). The external variable .C daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable .C tzname[2] contains the local standard and local summer time zone abbreviations as specified by the .C TZ environment variable. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters. .SS Environment Variables The .C tzset() function uses the contents of .C TZ to set the values of the external variables .CR timezone , .C daylight , and .CR tzname . .C TZ also determines the time zone name substituted for the .C %Z and .C %z directives and the time zone adjustments performed by .CR localtime() , .CR mktime() , and .CR ctime() . Two methods for specifying a time zone within .C TZ are described in .IR environ (5). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH "RETURN VALUE" .PP For .C asctime_r() and .C ctime_r(), if the buffer is of insufficient length, -1 is returned. For .C asctime_r(), ctime_r(), gmtime_r(), and .C localtime_r(), if the operation is successful, 0 is returned. .SH WARNINGS The return values for .CR asctime() , .CR ctime() , .CR gmtime() , and .CR localtime() point to static data whose contents is overwritten by each call. Thus, these routines are unsafe in multi-thread applications. .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() are MT-Safe and should be used instead. .PP Users of .CR asctime_r() , .CR ctime_r() , .CR gmtime_r() , and .C localtime_r() should also note that the prototypes of these functions will change in the next release for conformance with the new POSIX Threads standard. .PP The range of .C tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by .IR time (2) and passed as the .I timer argument does not include accumulated leap seconds. The .C tm structure generated by .C localtime() and .C gmtime() will never reflect any leap seconds. Upon successful completion, .C mktime() forces the value of the .C tm_sec component to the range [0,59]. .PP .CR ctime() , .CR ctime_r() , .CR asctime() , and .CR asctime_r() are considered obsolescent and may be removed in a future release. Use of .IR strftime (3C) is recommended instead. .SH AUTHOR .C ctime() was developed by AT&T and HP. .SH SEE ALSO time(2), getdate(3C), setlocale(3C), strftime(3C), tztab(4), environ(5), hpnls(5), lang(5), langinfo(5). .SH STANDARDS CONFORMANCE .CR ctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR asctime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR daylight ": AES, SVID2, SVID3, XPG2, XPG3, XPG4" .PP .CR difftime() ": AES, SVID3, XPG4, ANSI C" .PP .CR gmtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR localtime() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mktime() ": AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR timezone ": AES, SVID3, XPG2, XPG3, XPG4" .PP .CR tzname ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .PP .CR tzset() ": AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4asctime()\fP, \f4asctime_r()\f1 \- convert \f3tm\f1 structure date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4ctime()\fP, \f4ctime_r()\f1 \- convert \f4clock()\fP date and time to string@@@\f3ctime(3C)\f1 .\" index@\f4daylight()\fP \- Daylight Savings Time flag@@@\f3ctime(3C)\f1 .\" index@\f4gmtime()\fP, \f4gmtime_r()\fP \- convert date and time to Greenwich Mean Time@@@\f3ctime(3C)\f1 .\" index@\f4localtime()\fP, \f4localtime_r()\fP \- convert date and time to local timezone@@@\f3ctime(3C)\f1 .\" index@\f4timezone()\fP \- difference between \s-1UCT\s+1 and local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzname()\fP \- name of local timezone@@@\f3ctime(3C)\f1 .\" index@\f4tzset()\fP \- initialize \f4timezone()\fP, \f4daylight()\fP, and \f4tzname()\fP using \s-1TZ\s+1 variable@@@\f3ctime(3C)\f1 .\" index@\f4mktime()\fP \- convert time into calendar time value@@@\f3ctime(3C)\f1 .\" index@\f4difftime()\fP \- difference between two calendar time values@@@\f3ctime(3C)\f1 .\" index@convert date and time to string@@@\f3ctime(3C)\f1 .\" index@string, convert date and time to@@@\f3ctime(3C)\f1 .\" index@date and time, convert to string@@@\f3ctime(3C)\f1 .\" index@time and date, convert to string@@@\f3ctime(3C)\f1 .\" .\" toc@\f3ctime(3C)\f1:\0\0\f4ctime()\fP, \f4ctime_r()\fP, \f4localtime()\fP, \f4localtime_r()\fP, \f4difftime()\f1, \f4 mktime()\f1, \n\f4gmtime()\fP, \f4gmtime_r()\fP,\f4asctime()\fP, \f4asctime_r()\fP, \f4timezone()\fP, \f4daylight()\fP, \f4tzname()\fP,\n\f4tzset()\f1@@@convert date and time to string .\" toc@\f4ctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4ctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4localtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4gmtime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4asctime_r()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4timezone()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4daylight()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzname()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4tzset()\fP:\0\0convert date and time to string@@@see \f3ctime(3C)\f1 .\" toc@\f4difftime()\fP:\0\0difference between calendar times@@@see \f3ctime(3C)\f1 .\" toc@\f4mktime()\fP:\0\0create calendar time value@@@see \f3ctime(3C)\f1 .\" .\" links@ctime.3c ctime_r.3c .\" links@ctime.3c localtime.3c .\" links@ctime.3c localtime_r.3c .\" links@ctime.3c gmtime.3c .\" links@ctime.3c gmtime_r.3c .\" links@ctime.3c asctime.3c .\" links@ctime.3c asctime_r.3c .\" links@ctime.3c timezone.3c .\" links@ctime.3c daylight.3c .\" links@ctime.3c tzname.3c .\" links@ctime.3c tzset.3c .\" links@ctime.3c difftime.3c .\" links@ctime.3c mktime.3c .\" .\" fileset_database@ctime.3c PROGRAMING-MAN .\" $Header: lckpwdf.3c,v 72.2 94/07/03 11:05:08 ssa Exp $ .TA l .TH lckpwdf 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME lckpwdf(), ulckpwdf() \- control access to /etc/passwd file .SH SYNOPSIS .C #include .br .C int lckpwdf (void) .br .C int ulckpwdf (void) .SH DESCRIPTION The .CR lckpwdf() and .CR ulckpwdf() routines are used to coordinate modification access to the password file .CR /etc/passwd and to the secure password entries. The lock file used by these two routines is .CR /etc/.pwd.lock . A process first calls .CR lckpwdf() to gain exclusive access rights for password modification. When modifications are complete, .CR ulckpwdf() is called to release the lock on .CR /etc/.pwd.lock . This mechanism prevents simultaneous modification of password files or entries. .SH RETURN VALUE The .CR lckpwdf() routine returns zero upon successful completion. If the lock could not be obtained, it returns \(mi1 and sets .CR errno to indicate the error. .PP The .CR ulckpwdf() routine returns zero upon successful completion. If the lock has already been released, .CR ulckpwdf() returns \(mi1 and sets .CR errno to indicate the error. .SH FILES .C /etc/passwd .br .C /etc/.pwd.lock .SH SEE ALSO getpwent(3C), passwd(4). .\" toc@\f3lckpwdf(3C)\f1:\0\0f4lckpwdf()\f1, \f4ulckpwdf()\f1@@@control access to /etc/passwd file\f1 .\" toc@\f3ulckpwdf()\f1:\0\0unlock access to /etc/passwd file@@@\f1see \f3lckpwd(3C)\f1 .\" .\" index@\f4lckpwdf()\f1 \- control access to /etc/passwd file@@@\f3lckpwdf(3C)\f1 .\" index@\f4ulckpwdf()\f1 \- control access to /etc/passwd file@@@\f3lckpwdf(3C)\f1 .\" index@\f1access to /etc/passwd file, control@@@\f3lckpwdf(3C)\f1 .\" index@\f1lock access to /etc/passwd file@@@\f3lckpwdf(3C)\f1 .\" index@\f1unlock access to /etc/passwd file@@@\f3lckpwdf(3C)\f1 .\" .\" links@lckpwdf.3c ulckpwdf.3c .\" $Header: ltostr.3c,v 74.1 95/05/10 21:07:18 ssa Exp $ .TA l .TH ltostr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ltostr(), ltostr_r(), ultostr(), ultostr_r(), ltoa(), ltoa_r(), ultoa(), ultoa_r() \- convert long integers to strings .SH SYNOPSIS .C "#include " .PP .C "char *ltostr(long n, int base);" .PP .C "int ltostr_r(long n, int base, char *buffer, int buflen);" .PP .C "char *ultostr(unsigned long n, int base);" .PP .C "int ultostr_r(unsigned long n, int base, char *buffer, int buflen);" .PP .C "char *ltoa(long n);" .PP .C "int ltoa_r(long n, char *buffer, int buflen);" .PP .C "char *ultoa(unsigned long n);" .PP .C "int ultoa_r(unsigned long n, char *buffer, int buflen);" .SH DESCRIPTION .RS .TP 15 .CR ltostr() Convert a signed long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ultostr() Convert an unsigned long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ltoa() Convert a signed long integer to the corresponding base 10 string representation, returning a pointer to the result. .TP .CR ultoa() Convert an unsigned long integer to the corresponding base 10 string representation, returning a pointer to the result. .RE .PP These functions are smaller and faster than using .CR sprintf() for simple conversions (see .IR printf (3S)). .SS Reentrant Interfaces For the reentrant .CR "(_r)" interfaces, the result string is passed back in the supplied buffer. If the buffer is of insufficient length, .CR \(mi1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .SH ERRORS If the value of .I base is not between 2 and 36, .CR ltostr() and .CR ultostr() return NULL and set the external variable .CR errno to ERANGE. The reentrant versions .RC ( ltostr_r() " and " ultostr_r() ) return .CR \(mi1 and set the external variable .CR errno to ERANGE. .SH WARNINGS The return values for .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() point to static data whose content is overwritten by each call. .PP .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() are unsafe in multi-thread applications. .CR ltostr_r() , .CR ultostr_r() , .CR ltoa_r() , and .CR ultoa_r() are MT-Safe and should be used instead. .SH AUTHOR .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() were developed by HP. .SH SEE ALSO printf(3C), strtol(3C), printf(3S). .\" .\" index@\f4ltostr()\f1 \- convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ltostr_r()\f1 \- convert long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa()\f1 \- convert long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa_r()\f1 \- convert long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr()\f1 \- convert unsigned long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr_r()\f1 \- convert unsigned long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa()\f1 \- convert unsigned long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa_r()\f1 \- convert unsigned long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f1convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f1long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1unsigned long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1integer, long, convert to string,@@@\f3ltostr(3C)\f1 .\" index@\f1string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1decimal ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" .\" toc@\f3ltostr(3C)\f1:\0\0\f4ltostr()\f1, \f4ltostr_r()\f1, \f4ultostr()\f1, \f4ultostr_r()\f1, \f4ltoa()\f1, \n\f4ltoa_r()\f1, \f4ultoa()\f1, \f4ultoa_r()\f1@@@convert long integers to strings .\" toc@\f4ltostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr()\f1:\0\0unsigned long to ASCII@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa()\f1:\0\0long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa_r()\f1:\0\0long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa()\f1:\0\0unsigned long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa_r()\f1:\0\0unsigned long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" links@ltostr.3c ltostr_r.3c .\" links@ltostr.3c ultostr.3c .\" links@ltostr.3c ultostr_r.3c .\" links@ltostr.3c ultoa.3c .\" links@ltostr.3c ultoa_r.3c .\" links@ltostr.3c ltoa.3c .\" links@ltostr.3c ltoa_r.3c .\" $Header: ltostr.3c,v 74.1 95/05/10 21:07:18 ssa Exp $ .TA l .TH ltostr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ltostr(), ltostr_r(), ultostr(), ultostr_r(), ltoa(), ltoa_r(), ultoa(), ultoa_r() \- convert long integers to strings .SH SYNOPSIS .C "#include " .PP .C "char *ltostr(long n, int base);" .PP .C "int ltostr_r(long n, int base, char *buffer, int buflen);" .PP .C "char *ultostr(unsigned long n, int base);" .PP .C "int ultostr_r(unsigned long n, int base, char *buffer, int buflen);" .PP .C "char *ltoa(long n);" .PP .C "int ltoa_r(long n, char *buffer, int buflen);" .PP .C "char *ultoa(unsigned long n);" .PP .C "int ultoa_r(unsigned long n, char *buffer, int buflen);" .SH DESCRIPTION .RS .TP 15 .CR ltostr() Convert a signed long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ultostr() Convert an unsigned long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ltoa() Convert a signed long integer to the corresponding base 10 string representation, returning a pointer to the result. .TP .CR ultoa() Convert an unsigned long integer to the corresponding base 10 string representation, returning a pointer to the result. .RE .PP These functions are smaller and faster than using .CR sprintf() for simple conversions (see .IR printf (3S)). .SS Reentrant Interfaces For the reentrant .CR "(_r)" interfaces, the result string is passed back in the supplied buffer. If the buffer is of insufficient length, .CR \(mi1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .SH ERRORS If the value of .I base is not between 2 and 36, .CR ltostr() and .CR ultostr() return NULL and set the external variable .CR errno to ERANGE. The reentrant versions .RC ( ltostr_r() " and " ultostr_r() ) return .CR \(mi1 and set the external variable .CR errno to ERANGE. .SH WARNINGS The return values for .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() point to static data whose content is overwritten by each call. .PP .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() are unsafe in multi-thread applications. .CR ltostr_r() , .CR ultostr_r() , .CR ltoa_r() , and .CR ultoa_r() are MT-Safe and should be used instead. .SH AUTHOR .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() were developed by HP. .SH SEE ALSO printf(3C), strtol(3C), printf(3S). .\" .\" index@\f4ltostr()\f1 \- convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ltostr_r()\f1 \- convert long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa()\f1 \- convert long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa_r()\f1 \- convert long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr()\f1 \- convert unsigned long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr_r()\f1 \- convert unsigned long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa()\f1 \- convert unsigned long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa_r()\f1 \- convert unsigned long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f1convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f1long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1unsigned long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1integer, long, convert to string,@@@\f3ltostr(3C)\f1 .\" index@\f1string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1decimal ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" .\" toc@\f3ltostr(3C)\f1:\0\0\f4ltostr()\f1, \f4ltostr_r()\f1, \f4ultostr()\f1, \f4ultostr_r()\f1, \f4ltoa()\f1, \n\f4ltoa_r()\f1, \f4ultoa()\f1, \f4ultoa_r()\f1@@@convert long integers to strings .\" toc@\f4ltostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr()\f1:\0\0unsigned long to ASCII@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa()\f1:\0\0long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa_r()\f1:\0\0long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa()\f1:\0\0unsigned long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa_r()\f1:\0\0unsigned long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" links@ltostr.3c ltostr_r.3c .\" links@ltostr.3c ultostr.3c .\" links@ltostr.3c ultostr_r.3c .\" links@ltostr.3c ultoa.3c .\" links@ltostr.3c ultoa_r.3c .\" links@ltostr.3c ltoa.3c .\" links@ltostr.3c ltoa_r.3c .\" $Header: ltostr.3c,v 74.1 95/05/10 21:07:18 ssa Exp $ .TA l .TH ltostr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ltostr(), ltostr_r(), ultostr(), ultostr_r(), ltoa(), ltoa_r(), ultoa(), ultoa_r() \- convert long integers to strings .SH SYNOPSIS .C "#include " .PP .C "char *ltostr(long n, int base);" .PP .C "int ltostr_r(long n, int base, char *buffer, int buflen);" .PP .C "char *ultostr(unsigned long n, int base);" .PP .C "int ultostr_r(unsigned long n, int base, char *buffer, int buflen);" .PP .C "char *ltoa(long n);" .PP .C "int ltoa_r(long n, char *buffer, int buflen);" .PP .C "char *ultoa(unsigned long n);" .PP .C "int ultoa_r(unsigned long n, char *buffer, int buflen);" .SH DESCRIPTION .RS .TP 15 .CR ltostr() Convert a signed long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ultostr() Convert an unsigned long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ltoa() Convert a signed long integer to the corresponding base 10 string representation, returning a pointer to the result. .TP .CR ultoa() Convert an unsigned long integer to the corresponding base 10 string representation, returning a pointer to the result. .RE .PP These functions are smaller and faster than using .CR sprintf() for simple conversions (see .IR printf (3S)). .SS Reentrant Interfaces For the reentrant .CR "(_r)" interfaces, the result string is passed back in the supplied buffer. If the buffer is of insufficient length, .CR \(mi1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .SH ERRORS If the value of .I base is not between 2 and 36, .CR ltostr() and .CR ultostr() return NULL and set the external variable .CR errno to ERANGE. The reentrant versions .RC ( ltostr_r() " and " ultostr_r() ) return .CR \(mi1 and set the external variable .CR errno to ERANGE. .SH WARNINGS The return values for .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() point to static data whose content is overwritten by each call. .PP .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() are unsafe in multi-thread applications. .CR ltostr_r() , .CR ultostr_r() , .CR ltoa_r() , and .CR ultoa_r() are MT-Safe and should be used instead. .SH AUTHOR .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() were developed by HP. .SH SEE ALSO printf(3C), strtol(3C), printf(3S). .\" .\" index@\f4ltostr()\f1 \- convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ltostr_r()\f1 \- convert long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa()\f1 \- convert long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa_r()\f1 \- convert long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr()\f1 \- convert unsigned long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr_r()\f1 \- convert unsigned long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa()\f1 \- convert unsigned long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa_r()\f1 \- convert unsigned long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f1convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f1long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1unsigned long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1integer, long, convert to string,@@@\f3ltostr(3C)\f1 .\" index@\f1string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1decimal ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" .\" toc@\f3ltostr(3C)\f1:\0\0\f4ltostr()\f1, \f4ltostr_r()\f1, \f4ultostr()\f1, \f4ultostr_r()\f1, \f4ltoa()\f1, \n\f4ltoa_r()\f1, \f4ultoa()\f1, \f4ultoa_r()\f1@@@convert long integers to strings .\" toc@\f4ltostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr()\f1:\0\0unsigned long to ASCII@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa()\f1:\0\0long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa_r()\f1:\0\0long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa()\f1:\0\0unsigned long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa_r()\f1:\0\0unsigned long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" links@ltostr.3c ltostr_r.3c .\" links@ltostr.3c ultostr.3c .\" links@ltostr.3c ultostr_r.3c .\" links@ltostr.3c ultoa.3c .\" links@ltostr.3c ultoa_r.3c .\" links@ltostr.3c ltoa.3c .\" links@ltostr.3c ltoa_r.3c .\" $Header: ltostr.3c,v 74.1 95/05/10 21:07:18 ssa Exp $ .TA l .TH ltostr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ltostr(), ltostr_r(), ultostr(), ultostr_r(), ltoa(), ltoa_r(), ultoa(), ultoa_r() \- convert long integers to strings .SH SYNOPSIS .C "#include " .PP .C "char *ltostr(long n, int base);" .PP .C "int ltostr_r(long n, int base, char *buffer, int buflen);" .PP .C "char *ultostr(unsigned long n, int base);" .PP .C "int ultostr_r(unsigned long n, int base, char *buffer, int buflen);" .PP .C "char *ltoa(long n);" .PP .C "int ltoa_r(long n, char *buffer, int buflen);" .PP .C "char *ultoa(unsigned long n);" .PP .C "int ultoa_r(unsigned long n, char *buffer, int buflen);" .SH DESCRIPTION .RS .TP 15 .CR ltostr() Convert a signed long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ultostr() Convert an unsigned long integer to the corresponding string representation in the specified base. The argument .I base must be between 2 and 36, inclusive. .TP .CR ltoa() Convert a signed long integer to the corresponding base 10 string representation, returning a pointer to the result. .TP .CR ultoa() Convert an unsigned long integer to the corresponding base 10 string representation, returning a pointer to the result. .RE .PP These functions are smaller and faster than using .CR sprintf() for simple conversions (see .IR printf (3S)). .SS Reentrant Interfaces For the reentrant .CR "(_r)" interfaces, the result string is passed back in the supplied buffer. If the buffer is of insufficient length, .CR \(mi1 is returned. If the operation is successful, the length of the result string (not including the terminating null character) is returned. .SH ERRORS If the value of .I base is not between 2 and 36, .CR ltostr() and .CR ultostr() return NULL and set the external variable .CR errno to ERANGE. The reentrant versions .RC ( ltostr_r() " and " ultostr_r() ) return .CR \(mi1 and set the external variable .CR errno to ERANGE. .SH WARNINGS The return values for .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() point to static data whose content is overwritten by each call. .PP .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() are unsafe in multi-thread applications. .CR ltostr_r() , .CR ultostr_r() , .CR ltoa_r() , and .CR ultoa_r() are MT-Safe and should be used instead. .SH AUTHOR .CR ltostr() , .CR ultostr() , .CR ltoa() , and .CR ultoa() were developed by HP. .SH SEE ALSO printf(3C), strtol(3C), printf(3S). .\" .\" index@\f4ltostr()\f1 \- convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ltostr_r()\f1 \- convert long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa()\f1 \- convert long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ltoa_r()\f1 \- convert long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr()\f1 \- convert unsigned long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f4ultostr_r()\f1 \- convert unsigned long integer to string (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa()\f1 \- convert unsigned long integer to ASCII decimal@@@\f3ltostr(3C)\f1 .\" index@\f4ultoa_r()\f1 \- convert unsigned long integer to ASCII decimal (MT-Safe)@@@\f3ltostr(3C)\f1 .\" index@\f1convert long integer to string@@@\f3ltostr(3C)\f1 .\" index@\f1long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1unsigned long integer to string, convert@@@\f3ltostr(3C)\f1 .\" index@\f1integer, long, convert to string,@@@\f3ltostr(3C)\f1 .\" index@\f1string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" index@\f1decimal ASCII string, convert long integer to@@@\f3ltostr(3C)\f1 .\" .\" toc@\f3ltostr(3C)\f1:\0\0\f4ltostr()\f1, \f4ltostr_r()\f1, \f4ultostr()\f1, \f4ultostr_r()\f1, \f4ltoa()\f1, \n\f4ltoa_r()\f1, \f4ultoa()\f1, \f4ultoa_r()\f1@@@convert long integers to strings .\" toc@\f4ltostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr()\f1:\0\0unsigned long to ASCII@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultostr_r()\f1:\0\0unsigned long to ASCII (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa()\f1:\0\0long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ltoa_r()\f1:\0\0long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa()\f1:\0\0unsigned long to ASCII decimal@@@\f1see \f3ltostr(3C)\f1 .\" toc@\f4ultoa_r()\f1:\0\0unsigned long to ASCII decimal (MT-Safe)@@@\f1see \f3ltostr(3C)\f1 .\" links@ltostr.3c ltostr_r.3c .\" links@ltostr.3c ultostr.3c .\" links@ltostr.3c ultostr_r.3c .\" links@ltostr.3c ultoa.3c .\" links@ltostr.3c ultoa_r.3c .\" links@ltostr.3c ltoa.3c .\" links@ltostr.3c ltoa_r.3c .\" $Header: unctrl.3x,v 76.2 95/08/01 14:57:45 ssa Exp $ .TA u .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH unctrl 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME unctrl \(em generate printable representation of a character .SH SYNOPSIS .C "#include " .P .C "char *unctrl(chtype \f2c\fP);" .SH DESCRIPTION The .Fn unctrl function generates a character string that is a printable representation of \f2c\f1. If \f2c\f1 is a control character, it is converted to the \f4^\f2X\f1 notation. If \f2c\f1 contains rendition information, the effect is undefined. .SH "RETURN VALUE" Upon successful completion, .Fn unctrl returns the generated string. Otherwise, it returns a null pointer. .SH ERRORS No errors are defined. .SH "SEE ALSO" keyname(), wunctrl(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The .B "RETURN VALUE" section now states that the function may return a null pointer. This condition was not specified in previous issues. .\" .\" index@\f4unctrl()\f1 \- generate printable representation of a character@@@\f3unctrl(3X)\f1 .\" index@\f1generate printable representation of a character@@@\f3unctrl(3X)\f1 .\" index@\f1printable representation of a character, generate@@@\f3unctrl(3X)\f1 .\" index@\f1character, generate printable representation of@@@\f3unctrl(3X)\f1 .\" .\" toc@\f3unctrl(3X)\f1:\0\0\f4unctrl()\f1@@@generate printable representation of a character .\" .\" fileset_database@unctrl.3x CURS-ENG-A-MAN .\" $Header: dial.3c,v 72.5 94/11/02 11:55:44 ssa Exp $ .TA d .TH dial 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dial(), undial() \- establish an outgoing terminal line connection .SH SYNOPSIS .C "#include " .PP .C "int dial(CALL call);" .PP .C "void undial(int fd);" .SH DESCRIPTION The .CR dial() function returns a file descriptor for a terminal line open for read/write. The argument to .CR dial() is a .CR CALL structure (defined in the .RC < dial.h > header file). .PP When finished with the terminal line, the calling program must invoke .CR undial() to release the semaphore that has been set during the allocation of the terminal device. .PP The definition of .CR CALL in the .RC < dial.h > header file is: .PP .RS .nf .C "typedef struct {" .RS .C "struct termio *attr; /* pointer to termio attribute struct */" .C "int baud; /* transmission data rate */" .C "int speed; /* 212A modem: low=300, high=1200 */" .C "char *line; /* device name for out-going line */" .C "char *telno; /* pointer to tel-no digits string */ .C "int modem; /* specify modem control for direct lines */" .C "char *device; /* Will hold the name of the device used" .C " to make a connection */" .C "int dev_len; /* The length of the device used to" .C " make connection */" .RE .C "} CALL;" .fi .RE .PP .CR CALL elements are as follows: .RS .TP 12 .I speed Intended only for use with an outgoing dialed call, in which case its value should be either 300 or 1200 to identify the 113A modem, or the high- or low-speed setting on the 212A modem. Note that the 113A modem or the low-speed setting of the 212A modem transmits at any rate between 0 and 300 bits per second. However, the high-speed setting of the 212A modem transmits and receives at 1200 bits per second only. .TP .I baud Desired transmission baud rate. For example, one might set .I baud to 110 and .I speed to 300 (or 1200). However, if .I speed is set to 1200, .I baud must be set to high (1200). .TP .I line If the desired terminal line is a direct line, a string pointer to its device name should be placed in the .I line element in the .CR CALL structure. Legal values for such terminal device names are kept in the .CR Devices file. In this case, the value of the .I baud element need not be specified as it will be determined from the .CR Devices file. .TP .I telno A pointer to a character string representing the telephone number to be dialed. Such numbers can consist only of symbols described below. The termination symbol is supplied by the .CR dial() function, and should not be included in the .I telno string passed to .CR dial() in the .CR CALL structure. .IP .RS .RS .TS box; lB s lw l. .vs +1p Permissible Codes _ 0-9 dial 0-9 _ * or : dial * _ # or ; dial # _ - 4-second delay for second dial tone _ e or < end-of-number _ w or = wait for secondary dial tone _ f flash off hook for 1 second .TE .sp .5 .RE .RE .TP 12 .I modem Specifies modem control for direct lines. Set to non-zero if modem control is required. .TP .I attr Pointer to a .CR termio structure, as defined in the .RC < termio.h > header file. A NULL value for this pointer element can be passed to the .CR dial() function, but if such a structure is included, the elements specified in it are set for the outgoing terminal line before the connection is established. This is often important for certain attributes such as parity and baud rate. .TP .I device Holds the device name that establishes the connection. .TP .I dev_len Length of the device name that is copied into the array device. .SH RETURN VALUE On failure, a negative value indicating the reason for the failure is returned. Mnemonics for these negative indices as listed here are defined in the .RC < dial.h > header file. .PP .RS .nf .C "INTRPT -1 /* interrupt occurred */" .C "D_HUNG -2 /* dialer hung (no return from write) */" .C "NO_ANS -3 /* no answer within 10 seconds */" .C "ILL_BD -4 /* illegal baud-rate */" .C "A_PROB -5 /* automatic call unit (acu) problem (open() failure) */" .C "L_PROB -6 /* line problem (open() failure) */" .C "NO_Ldv -7 /* can't open LDEVS file */" .C "DV_NT_A -8 /* requested device not available */" .C "DV_NT_K -9 /* requested device not known */" .C "NO_BD_A -10 /* no device available at requested baud */" .C "NO_BD_K -11 /* no device known at requested baud */" .fi .RE .SH WARNINGS Including the .RC < dial.h > header file automatically includes the .RC < termio.h > header file. .PP The above routine uses .RC < stdio.h >, which causes unexpected increases in the size of programs that otherwise do not use standard I/O. .PP The .CR dial() function will modify the values of some of the fields of the the .CR CALL structure so if .CR dial() , is reinvoked, reinitialize the values of the .CR CALL structure. .SH FILES .C /etc/uucp/Devices .SH SEE ALSO uucp(1), alarm(2), read(2), write(2), termio(7). .PP .IR UUCP tutorial in .IR "Remote Access User's Guide" . .\" .\" index@\f4dial()\f1 \- establish an out-bound terminal line connection@@@\f3dial(3C)\f1 .\" index@\f4undial()\f1\- establish an out-bound terminal line connection@@@\f3dial(3C)\f1 .\" index@\f1establish an out-bound terminal line connection@@@\f3dial(3C)\f1 .\" index@\f1out-bound terminal line connection, establish an@@@\f3dial(3C)\f1 .\" index@\f1terminal line connection, establish an out-bound@@@\f3dial(3C)\f1 .\" index@\f1line connection, establish an out-bound terminal@@@\f3dial(3C)\f1 .\" index@\f1connection, establish an out-bound terminal line@@@\f3dial(3C)\f1 .\" .\" toc@\f3dial(3C)\f1:\0\0\f4dial()\fP, \f4undial()\f1@@@establish an outgoing terminal line connection\f1 .\" toc@\f4undial()\f1:\0\0establish an outgoing terminal line connection@@@\f1`see \f3dial(3C)\f1 .\" .\" links@dial.3c undial.3c .\" $Header: ungetch.3x,v 76.2 95/08/01 14:59:47 ssa Exp $ .TA u .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ungetch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ungetch, unget_wch \(em push a character onto the input queue .SH SYNOPSIS .C "#include " .P .C "int ungetch(int \f2ch\fP);" .P .C "int unget_wch(const wchar_t \f2wch\fP);" .SH DESCRIPTION The .Fn ungetch function pushes the single-byte character \f2ch\f1 onto the head of the input queue. .P The .Fn unget_wch function pushes the wide character \f2wch\f1 onto the head of the input queue. .P One character of push-back is guaranteed. If these functions are called too many times without an intervening call to .Fn getch or .CR get_wch() , the operation may fail. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, getch(), get_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3ungetch(3X)\f1:\0\0\f4ungetch()\f1, \f4unget_wch()\f1@@@push a character onto the input queue .\" toc@\f4unget_wch()\f1: push a character onto the input queue@@@see \f3ungetch(3X)\f1 .\" .\" index@\f4ungetch()\f1 \- push a character onto the input queue@@@\f3ungetch(3X)\f1 .\" index@\f4unget_wch()\f1 \- push a character onto the input queue@@@\f3ungetch(3X)\f1 .\" index@\f1push a character onto the input queue@@@\f3ungetch(3X)\f1 .\" index@\f1character, push onto the input queue@@@\f3ungetch(3X)\f1 .\" index@\f1input queue, push a character onto@@@\f3ungetch(3X)\f1 .\" index@\f1queue, input, push a character onto@@@\f3ungetch(3X)\f1 .\" .\" links@ungetch.3x unget_wch.3x .\" .\" fileset_database@ungetch.3x CURS-ENG-A-MAN .\" $Header: ungetc.3s,v 72.5 94/11/15 09:56:57 ssa Exp $ .TA u .TH ungetc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ungetc(\|), ungetc_unlocked(\|) \- push character back into input stream .SH SYNOPSIS .C "#include " .PP .C "int ungetc(int c, FILE *stream);" .PP .C "int ungetc_unlocked(int c, FILE *stream);" .SH DESCRIPTION .CR ungetc() inserts the character .I c (converted to an unsigned char) into the buffer associated with an input .IR stream . That character, .IR c , is returned by the next call to .CR getc() (see .IR getc (3S)) on that .IR stream . A successful intervening call to a file positioning function with .I stream .RC ( fseek() , .CR fsetpos() , or .CR rewind() ) erases all memory of the inserted characters. .PP .CR ungetc() affects only the buffer associated with the input .IR stream . It does not affect the contents of the file corresponding to .IR stream . .PP One character of pushback is guaranteed. .PP If .I c equals .SM EOF, .CR ungetc() does nothing to the buffer and returns .SM EOF. .PP .CR ungetc_unlocked() is identical to .CR ungetc() except it does not perform any internal locking of the .I stream for multi-thread applications. .CR ungetc_unlocked() can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE If successful, .CR ungetc() " and " ungetc_unlocked() return .I c and clear the end-of-file indicator for the stream. .CR ungetc() " and " ungetc_unlocked() return .SM EOF if they cannot insert the character. .SH SEE ALSO flockfile(3S), fseek(3S), fsetpos(3S), getc(3S), setbuf(3S). .SH STANDARDS CONFORMANCE .CR ungetc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4ungetc()\fP \- push character back into input stream@@@\f3ungetc(3S)\f1 .\" index@push character back into input stream@@@\f3ungetc(3S)\f1 .\" index@return character back into input stream@@@\f3ungetc(3S)\f1 .\" index@character back into input stream, push@@@\f3ungetc(3S)\f1 .\" index@back into input stream, push character@@@\f3ungetc(3S)\f1 .\" index@input stream, push character back into@@@\f3ungetc(3S)\f1 .\" index@stream, push character back into input@@@\f3ungetc(3S)\f1 .\" .\" toc@\f3ungetc(3S)\f1:\0\0\f4ungetc()\fP@@@push character back into input stream .\" .\" links@ungetc.3s ungetc_unlo.3s .\" $Header: ungetc.3s,v 72.5 94/11/15 09:56:57 ssa Exp $ .TA u .TH ungetc 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ungetc(\|), ungetc_unlocked(\|) \- push character back into input stream .SH SYNOPSIS .C "#include " .PP .C "int ungetc(int c, FILE *stream);" .PP .C "int ungetc_unlocked(int c, FILE *stream);" .SH DESCRIPTION .CR ungetc() inserts the character .I c (converted to an unsigned char) into the buffer associated with an input .IR stream . That character, .IR c , is returned by the next call to .CR getc() (see .IR getc (3S)) on that .IR stream . A successful intervening call to a file positioning function with .I stream .RC ( fseek() , .CR fsetpos() , or .CR rewind() ) erases all memory of the inserted characters. .PP .CR ungetc() affects only the buffer associated with the input .IR stream . It does not affect the contents of the file corresponding to .IR stream . .PP One character of pushback is guaranteed. .PP If .I c equals .SM EOF, .CR ungetc() does nothing to the buffer and returns .SM EOF. .PP .CR ungetc_unlocked() is identical to .CR ungetc() except it does not perform any internal locking of the .I stream for multi-thread applications. .CR ungetc_unlocked() can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH RETURN VALUE If successful, .CR ungetc() " and " ungetc_unlocked() return .I c and clear the end-of-file indicator for the stream. .CR ungetc() " and " ungetc_unlocked() return .SM EOF if they cannot insert the character. .SH SEE ALSO flockfile(3S), fseek(3S), fsetpos(3S), getc(3S), setbuf(3S). .SH STANDARDS CONFORMANCE .CR ungetc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4ungetc()\fP \- push character back into input stream@@@\f3ungetc(3S)\f1 .\" index@push character back into input stream@@@\f3ungetc(3S)\f1 .\" index@return character back into input stream@@@\f3ungetc(3S)\f1 .\" index@character back into input stream, push@@@\f3ungetc(3S)\f1 .\" index@back into input stream, push character@@@\f3ungetc(3S)\f1 .\" index@input stream, push character back into@@@\f3ungetc(3S)\f1 .\" index@stream, push character back into input@@@\f3ungetc(3S)\f1 .\" .\" toc@\f3ungetc(3S)\f1:\0\0\f4ungetc()\fP@@@push character back into input stream .\" .\" links@ungetc.3s ungetc_unlo.3s .\" $Header: ungetch.3x,v 76.2 95/08/01 14:59:47 ssa Exp $ .TA u .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ungetch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ungetch, unget_wch \(em push a character onto the input queue .SH SYNOPSIS .C "#include " .P .C "int ungetch(int \f2ch\fP);" .P .C "int unget_wch(const wchar_t \f2wch\fP);" .SH DESCRIPTION The .Fn ungetch function pushes the single-byte character \f2ch\f1 onto the head of the input queue. .P The .Fn unget_wch function pushes the wide character \f2wch\f1 onto the head of the input queue. .P One character of push-back is guaranteed. If these functions are called too many times without an intervening call to .Fn getch or .CR get_wch() , the operation may fail. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, getch(), get_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3ungetch(3X)\f1:\0\0\f4ungetch()\f1, \f4unget_wch()\f1@@@push a character onto the input queue .\" toc@\f4unget_wch()\f1: push a character onto the input queue@@@see \f3ungetch(3X)\f1 .\" .\" index@\f4ungetch()\f1 \- push a character onto the input queue@@@\f3ungetch(3X)\f1 .\" index@\f4unget_wch()\f1 \- push a character onto the input queue@@@\f3ungetch(3X)\f1 .\" index@\f1push a character onto the input queue@@@\f3ungetch(3X)\f1 .\" index@\f1character, push onto the input queue@@@\f3ungetch(3X)\f1 .\" index@\f1input queue, push a character onto@@@\f3ungetch(3X)\f1 .\" index@\f1queue, input, push a character onto@@@\f3ungetch(3X)\f1 .\" .\" links@ungetch.3x unget_wch.3x .\" .\" fileset_database@ungetch.3x CURS-ENG-A-MAN .\" $Header: ungetwc.3c,v 72.6 94/11/15 09:56:58 ssa Exp $ .TA u .TH ungetwc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ungetwc(\|), ungetwc_unlocked(\|) \- push a wide character back into an input stream .SH SYNOPSIS .C "#include " .PP .C "wint_t ungetwc(wint_t wc, FILE *stream);" .PP .C "wint_t ungetwc_unlocked(wint_t wc, FILE *stream);" .SS Remarks: This function is compliant with the .SM XPG4 Worldwide Portability Interface wide-character .SM I/O functions. It parallels the 8-bit character .SM I/O function defined in .IR ungetc(3S) . .SH DESCRIPTION .CR ungetwc() pushes the character corresponding to the wide-character code .I wc into the buffer associated with an input .IR stream . That wide-character code, .IR wc , is returned by the next call to .CR getwc() (see .IR getwc (3C)) on that .IR stream . A successful intervening call to a file positioning function with .I stream .RC ( fseek() , .CR fsetpos() , or .CR rewind() ) erases all memory of the pushed-back characters. .PP .CR ungetwc() affects only the buffer associated with the input .IR stream . It does not affect the contents of the file corresponding to .IR stream . .PP One character of pushback is guaranteed. .PP If .I wc equals .CR WEOF , .CR ungetwc() does nothing to the buffer and returns .CR WEOF . .PP The definition for this function, the type .CR wint_t and the value .CR WEOF are provided in the .RC < wchar.h > header. .PP .CR ungetwc_unlocked() is identical to .CR ungetwc() except it does not perform any internal locking of the .I stream for multi-threaded applications. .CR ungetwc_unlocked() can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE If successful, .CR ungetwc() " and " ungetwc_unlocked() return .I wc and clear the end-of-file indicator for the stream. .CR ungetwc() " and " ungetwc_unlocked() return .CR WEOF if they cannot insert the wide character. .SH AUTHOR .CR ungetwc() and .CR ungetwc_unlocked() were developed by OSF and HP. .SH SEE ALSO flockfile(3S), fseek(3S), fsetpos(3S), getwc(3C), setbuf(3S). .SH STANDARDS CONFORMANCE .CR ungetwc() ": XPG4" .\" .\" index@\f4ungetwc()\f1 \- push wide character back into input stream@@@\f3ungetwc(3C)\f1 .\" index@\f4ungetwc_unlocked()\f1 \- unlocked version of ungetwc()@@@\f3ungetwc(3C)\f1 .\" index@\f1push wide character back into input stream@@@\f3ungetwc(3C)\f1 .\" index@\f1return wide character back into input stream@@@\f3ungetwc(3C)\f1 .\" index@\f1wide character back into input stream, push@@@\f3ungetwc(3C)\f1 .\" index@\f1back into input stream, push wide character@@@\f3ungetwc(3C)\f1 .\" index@\f1input stream, push wide character back into@@@\f3ungetwc(3C)\f1 .\" index@\f1stream, push wide character back into input@@@\f3ungetwc(3C)\f1 .\" .\" toc@\f3ungetwc(3C)\f1:\0\0\f4ungetwc()\f1, \f4ungetwc_unlocked()\f1@@@push wide character back into input stream .\" toc@\f3ungetwc_unlocked()\f1:\0\0push wide character back into input stream,do not lock stream\f1see \f3ungetwc(3C)\f1 .\" .\" links@ungetwc.3c ungetwc_unl.3c .\" $Header: ungetwc.3c,v 72.6 94/11/15 09:56:58 ssa Exp $ .TA u .TH ungetwc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ungetwc(\|), ungetwc_unlocked(\|) \- push a wide character back into an input stream .SH SYNOPSIS .C "#include " .PP .C "wint_t ungetwc(wint_t wc, FILE *stream);" .PP .C "wint_t ungetwc_unlocked(wint_t wc, FILE *stream);" .SS Remarks: This function is compliant with the .SM XPG4 Worldwide Portability Interface wide-character .SM I/O functions. It parallels the 8-bit character .SM I/O function defined in .IR ungetc(3S) . .SH DESCRIPTION .CR ungetwc() pushes the character corresponding to the wide-character code .I wc into the buffer associated with an input .IR stream . That wide-character code, .IR wc , is returned by the next call to .CR getwc() (see .IR getwc (3C)) on that .IR stream . A successful intervening call to a file positioning function with .I stream .RC ( fseek() , .CR fsetpos() , or .CR rewind() ) erases all memory of the pushed-back characters. .PP .CR ungetwc() affects only the buffer associated with the input .IR stream . It does not affect the contents of the file corresponding to .IR stream . .PP One character of pushback is guaranteed. .PP If .I wc equals .CR WEOF , .CR ungetwc() does nothing to the buffer and returns .CR WEOF . .PP The definition for this function, the type .CR wint_t and the value .CR WEOF are provided in the .RC < wchar.h > header. .PP .CR ungetwc_unlocked() is identical to .CR ungetwc() except it does not perform any internal locking of the .I stream for multi-threaded applications. .CR ungetwc_unlocked() can be used by multi-thread applications which have already used .CR flockfile() to acquire a mutual exclusion lock for the .IR stream " (see " flockfile (3S)). .SH EXTERNAL INFLUENCES .SS Locale The .CR LC_CTYPE category determines how wide character conversions are done. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE If successful, .CR ungetwc() " and " ungetwc_unlocked() return .I wc and clear the end-of-file indicator for the stream. .CR ungetwc() " and " ungetwc_unlocked() return .CR WEOF if they cannot insert the wide character. .SH AUTHOR .CR ungetwc() and .CR ungetwc_unlocked() were developed by OSF and HP. .SH SEE ALSO flockfile(3S), fseek(3S), fsetpos(3S), getwc(3C), setbuf(3S). .SH STANDARDS CONFORMANCE .CR ungetwc() ": XPG4" .\" .\" index@\f4ungetwc()\f1 \- push wide character back into input stream@@@\f3ungetwc(3C)\f1 .\" index@\f4ungetwc_unlocked()\f1 \- unlocked version of ungetwc()@@@\f3ungetwc(3C)\f1 .\" index@\f1push wide character back into input stream@@@\f3ungetwc(3C)\f1 .\" index@\f1return wide character back into input stream@@@\f3ungetwc(3C)\f1 .\" index@\f1wide character back into input stream, push@@@\f3ungetwc(3C)\f1 .\" index@\f1back into input stream, push wide character@@@\f3ungetwc(3C)\f1 .\" index@\f1input stream, push wide character back into@@@\f3ungetwc(3C)\f1 .\" index@\f1stream, push wide character back into input@@@\f3ungetwc(3C)\f1 .\" .\" toc@\f3ungetwc(3C)\f1:\0\0\f4ungetwc()\f1, \f4ungetwc_unlocked()\f1@@@push wide character back into input stream .\" toc@\f3ungetwc_unlocked()\f1:\0\0push wide character back into input stream,do not lock stream\f1see \f3ungetwc(3C)\f1 .\" .\" links@ungetwc.3c ungetwc_unl.3c .\" $Header: unlockpt.3c,v 72.2 94/09/22 10:14:54 ssa Exp $ .TA u .TH unlockpt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME unlockpt \- unlock a STREAMS pty master and slave pair .SH SYNOPSIS .C int unlockpt (int fildes); .SH DESCRIPTION The passed parameter, .IR fildes , is a file descriptor that is returned from a successful open of a master pty (pseudo-terminal) device. The .C unlockpt() function unlocks a slave pty from its associated master counterpart. It does this by clearing a lock flag so that the slave pty can be opened. For security reason, .IR grantpt (3C) must be executed before .IR unlockpt (3C). .SH RETURN VALUE Upon successful completion, the .C unlockpt() function returns a value of 0 (zero). Otherwise, it returns a value of -1. .PP Failure may result under the following conditions: .RS .TP 3 \(bu The file descriptor specified by the .IR fildes parameter is not an open file descriptor. .TP \(bu The file descriptor specified by the .IR fildes parameter is not associated with a STREAMS pty master device. .RE .SH EXAMPLES The following example shows how .C unlockpt is typically used. .nf .IP .C int fd_master, fd_slave; .C char *slave; \h'.3i'.\|.\|. .IP " " 10 .C "fd_master = open(""/dev/ptmx"", O_RDWR);" .C "grantpt(fd_master);" .C "unlockpt(fd_master);" .C "slave = ptsname(fd_master);" .C "fd_slave = open(slave, O_RDWR);" .C "ioctl(fd_slave, I_PUSH, ""ptem"");" .C "ioctl(fd_slave, I_PUSH, ""ldterm"");" .fi .SH AUTHOR .C unlockpt() was developed by HP and OSF. .SH SEE ALSO open(2), grantpt(3C), ptsname(3C), ptm(7), pts(7), ptem(7). .\" .\" index@\f4unlockpt()\f1 \- unlock a STREAMS pty master and slave pair@@@\f3unlockpt(3C)\f1 .\" index@\f1unlock a STREAMS pty master/slave pair@@@\f3unlockpt(3C)\f1 .\" index@\f1STREAMS pty master/slave pair, unlocking@@@\f3unlockpt(3C)\f1 .\" index@\f1master and slave pty, STREAMS, unlocking@@@\f3unlockpt(3C)\f1 .\" index@\f1slave and master pty, STREAMS, unlocking@@@\f3unlockpt(3C)\f1 .\" .\" toc@\f3unlockpt(3C)\f1:\0\0\f4unlockpt\f1@@@unlock a STREAMS pty master and slave pair .\" .\" fileset_database@unlockpt.3c STRTIO-MAN .\" $Header: is_linetouched.3x,v 76.2 95/08/01 11:31:01 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH is_linetouched 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 manpage_touch .SH NAME is_linetouched, is_wintouched, touchline, untouchwin, wtouchln \(em window refresh control functions .SH SYNOPSIS .C "#include " .P .C "bool is_linetouched(WINDOW *\f2win\fP, int \f2line\fP);" .P .C "bool is_wintouched(WINDOW *\f2win\fP);" .P .C "int touchline(WINDOW *\f2win\fP, int \f2start\fP, int \f2count\fP);" .P .C "int untouchwin(WINDOW *\f2win\fP);" .P .C "int wtouchln(WINDOW *\f2win\fP, int \f2y\fP, int \f2n\fP, int \f2changed\fP);" .SH DESCRIPTION The .Fn touchline function only touches \f2count\f1 lines, beginning with line \f2start\f1. .P The .Fn untouchwin function marks all lines in the window as unchanged since the last refresh operation. .P Calling .Fn wtouchln , if \f2changed\f1 is 1, touches \f2n\f1 lines in the specified window, starting at line \f2y\f1. If \f2changed\f1 is 0, .Fn wtouchln marks such lines as unchanged since the last refresh operation. .P The .Fn is_wintouched function determines whether the specified window is touched. The .Fn is_linetouched function determines whether line .I line of the specified window is touched. .SH "RETURN VALUE" The .Fn is_linetouched and .Fn is_wintouched functions return TRUE if any of the specified lines, or the specified window, respectively, has been touched since the last refresh operation. Otherwise, they return FALSE. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. Exceptions to this are noted in the preceding function descriptions. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Calling .Fn touchwin or .Fn touchline is sometimes necessary when using overlapping windows, since a change to one window affects the other window, but the records of which lines have been changed in the other window do not reflect the change. .SH "SEE ALSO" \f3Screens, Windows and Terminals\f1 in curs_intro, doupdate(), touchwin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3is_linetouched(3X)\f1:\0\0\f4is_linetouched()\f1, \f4is_wintouched()\f1, \f4touchline()\f1, \f4untouchwin()\f1, \n\f4wtouchln()\f1@@@window refresh control functions .\" toc@\f4is_wintouched()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4touchline()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4untouchwin()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4wtouchln()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" .\" index@\f4is_linetouched()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4is_wintouched()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4touchline()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4untouchwin()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4wtouchln()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f1window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f1refresh control functions for window@@@\f3is_linetouched(3X)\f1 .\" index@\f1control functions, window refresh@@@\f3is_linetouched(3X)\f1 .\" index@\f1functions, window refresh control@@@\f3is_linetouched(3X)\f1 .\" .\" links@is_linetouched.3x is_wintouched.3x .\" links@is_linetouched.3x touchline.3x .\" links@is_linetouched.3x untouchwin.3x .\" links@is_linetouched.3x wtouchln.3x .\" .\" fileset_database@is_linetouched.3x CURS-ENG-A-MAN .\" $Header: use_env.3x,v 76.2 95/08/01 15:00:50 ssa Exp $ .TA u .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH use_env 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME use_env \(em specify source of screen size information .SH SYNOPSIS .C "#include " .P .C "void use_env(char \f2boolvalue\fP);" .SH DESCRIPTION The .Fn use_env function specifies the technique by which the implementation determines the size of the screen. If \f2boolvalue\f1 is FALSE, the implementation uses the values of \f2lines\f1 and \f2columns\f1 specified in the \f3terminfo\f1 database. If \f2boolvalue\f1 is TRUE, the implementation uses the .Ev LINES and .Ev COLUMNS environment variables. The initial value is TRUE. .P Any call to .Fn use_env must precede calls to .CR initscr() , .Fn newterm or .CR setupterm() . .SH "RETURN VALUE" The function does not return a value. .SH ERRORS No errors are defined. .SH "SEE ALSO" del_curterm(), initscr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4use_env()\f1 \- specify source of screen size information@@@\f3use_env(3X)\f1 .\" index@\f1specify source of screen size information@@@\f3use_env(3X)\f1 .\" index@\f1source of screen size information, specify@@@\f3use_env(3X)\f1 .\" index@\f1screen size information, specify source@@@\f3use_env(3X)\f1 .\" index@\f1size information of screen, specify source@@@\f3use_env(3X)\f1 .\" .\" toc@\f3use_env(3X)\f1:\0\0\f4use_env()\f1@@@specify source of screen size information .\" .\" fileset_database@use_env.3x CURS-ENG-A-MAN .\" $Header: secure_rpc.3c,v 74.1 95/05/10 21:12:12 ssa Exp $ .TA s .TH secure_rpc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME secure_rpc(), authdes_create(), authdes_getucred(), get_myaddress(), getnetname(), host2netname(), key_decryptsession(), key_encryptsession(), key_gendes(), key_setsecret(), netname2host(), netname2user(), user2netname() \- library routines for secure remote procedure calls .SH DESCRIPTION .LP .C RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, the server calls a dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call returns to the client. .LP .C RPC allows various authentication flavors. The .B authdes_getucred() and .B authdes_create() routines implement the .B DES authentication flavor. See .BR rpc_clnt_auth (3C) for routines relating to the .B AUTH_NONE and .B AUTH_UNIX authentication types. .IP Note: Both the client and server should have their keys in the .BR publickey (5) database. Also, the keyserver daemon .BR keyserv (1M) must be running on both the client and server hosts for the .B DES authentication system to work. .SS Routines .LP The following routines require that the header .BR be included. .PP The .B AUTH data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "AUTH *" .C "authdes_create(netname, window, syncaddr, deskeyp)" .C "char *netname;" .C "unsigned window;" .C "struct sockaddr_in *syncaddr;" .C "des_block *deskeyp;" .fi .IP .B authdes_create() is an interface to the .B RPC secure authentication system, known as .B DES authentication. .IP Used on the client side, .B authdes_create() returns an authentication handle that enables the use of the secure authentication system. The first parameter .I netname is the network name of the owner of the server process. This field usually represents a .I host derived from the utility routine .BR host2netname() , but could also represent a user name using .BR user2netname() . The second field is window on the validity of the client credential, given in seconds. A small window is more secure than a large one, but choosing too small of a window will increase the frequency of resynchronizations because of clock drift. The third parameter .I syncaddr is optional. If it is .B NULL, then the authentication system will assume that the local clock is always in sync with the server's clock, and will not attempt to synchronize with the server. If an address is supplied then the system will use it for consulting the remote time service whenever resynchronization is required. This parameter is usually the address of the .B RPC server itself. The final parameter .I deskeyp is also optional. If it is .B NULL, then the authentication system will generate a random .B DES key to be used for the encryption of credentials. If .I deskeyp is supplied then it is used instead. .PP .nf .C "int" .C "authdes_getucred(adc, uidp, gidp, gidlenp, gidlistp)" .C "struct authdes_cred *adc;" .C "short *uidp, *gidp, *gidlenp;" .C "int *gidlistp;" .fi .IP .BR authdes_getucred() , is a .B DES authentication routine used by the server for converting a .B DES credential, which is operating system independent, into a .B UNIX credential. .I uidp points to the user .B ID of the user associated with .IR adc ; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. .br .ne 5 .IP This routine differs from the utility routine .B netname2user() in that .B authdes_getucred() pulls its information from a cache, and does not have to do a .B NIS name service lookup every time it is called to get its information. Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "void" .C "get_myaddress(addr)" .C "struct sockaddr_in *addr;" .fi .IP Return the machine's .B IP address in .IR addr. The port number is always set to .BR htons(PMAPPORT) . .PP .nf .C "int" .C "getnetname(netname)" .C "char netname[MAXNETNAMELEN];" .fi .IP Return the unique, operating-system independent netname of the caller in the fixed-length array .IR netname . Returns 1 if it succeeds and 0 if it fails. .PP .nf .C "int" .C "host2netname(netname, host, domain)" .C "char netname[MAXNETNAMELEN];" .C "char *host;" .C "char *domain;" .fi .IP Convert from a domain-specific hostname to an operating-system independent netname. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . This routine should be used if the owner of the server process is the machine that is, the user with effective user .B ID zero. Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2host() . .PP .nf .C "int" .C "key_decryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP An interface routine to the keyserver daemon, which is associated with .B RPC's secure authentication system ( .B DES authentication). User programs rarely need to call it, or its associated routines .BR key_encryptsession() , .B key_gendes() and .BR key_setsecret() . System commands such as .B login and the .B RPC library are the main clients of these four routines. .IP .B key_decryptsession() takes the netname of a server and a .B DES key, and decrypts the key by using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_encryptsession() . .PP .nf .C "int" .C "key_encryptsession(netname, deskeyp)" .C "char *netname;" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It takes the netname of the server and a .B DES key, and encrypts it using the public key of the server and the secret key associated with the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. This routine is the inverse of .BR key_decryptsession() . .PP .nf .C "int" .C "key_gendes(deskeyp)" .C "des_block *deskeyp;" .fi .IP A keyserver interface routine. It is used to ask the keyserver for a secure conversation key. Choosing one at random is usually not good enough, because the common ways of choosing random numbers, such as using the current time, are very easy to guess. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "key_setsecret(keyp)" .C "char *keyp;" .fi .IP A keyserver interface routine. It is used to set the secret key for the effective user .B ID of the calling process. Returns 0 if it succeeds and -1 if it fails. .PP .nf .C "int" .C "netname2host(netname, host, hostlen)" .C "char *netname;" .C "char *host;" .C "int hostlen;" .fi .IP Convert an operating-system independent netname to a domain-specific hostname. .I hostlen specifies the size of the array pointed to by .I host. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR host2netname() . .PP .nf .C "int" .C "netname2user(netname, uidp, gidp, gidlenp, gidlistp)" .C "char *netname;" .C "int *uidp, *gidp, *gidlenp, *gidlistp;" .fi .IP Convert an operating-system independent netname to a domain-specific user .B ID. .I uidp points to the user .B ID of the user; .I gidp refers to the user's current group .B ID; .I gidlistp refers to an array of groups to which the user belongs and .I gidlenp has the count of the entries in this array. It returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR user2netname() . .PP .nf .C "int" .C "user2netname(netname, uid, domain)" .C "char netname[MAXNETNAMELEN];" .C "int uid;" .C "char *domain;" .fi .IP Convert a domain-specific username to an operating-system independent netname. .I uid is the user .B ID of the owner of the server process. This routine is normally used to get the netname of the server, which is then used to get an authentication handle by calling .BR authdes_create() . Returns 1 if it succeeds and 0 if it fails. This routine is the inverse of .BR netname2user() . .SH AUTHOR .B rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR login (1), .BR chkey (1), .BR rpc (3C), .BR rpc_clnt_auth (3C), .BR publickey (4), .BR keyserv (1M), .BR newkey (1M) .\" toc@\f3secure_rpc(3C)\f1:\0\0\f4authdes_create()\fP, \f4authdes_getucred()\fP, \f4get_myaddress()\fP, \n\f4getnetaddress()\fP, \f4getnetname()\fP, \f4host2netname()\fP, \n\f4key_decryptsession()\fP, \f4key_encryptsession()\fP, \f4key_gendes()\fP, \n\f4key_setsecret()\fP, \f4netname2host()\fP, \f4netname2user()\fP, \n\f4user2netname()\fP@@@library routines for secure remote procedure calls .\" toc@\f4secure_rpc()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_create()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4authdes_getucred()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4get_myaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetaddress()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4getnetname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4host2netname()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_decryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_encryptsession()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_gendes()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4key_setsecret()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2host()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" toc@\f4netname2user()\fP: library routines for secure remote procedure calls@@@see \f3secure_rpc(3C)\f1 .\" toc@\f4user2netname()\fP: library routines for secure remote procedure calls@@@ see \f3secure_rpc(3C)\f1 .\" index@library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4secure_rpc()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_create()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4authdes_getucred()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4get_myaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetaddress()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4getnetname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4host2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_decryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_encryptsession()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_gendes()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4key_setsecret()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2host()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4netname2user()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" index@\f4user2netname()\fP \- library routines for secure remote procedure calls@@@\f3secure_rpc(3C)\f1 .\" links@secure_rpc.3c authdes_create.3c .\" links@secure_rpc.3c authdes_getucred.3c .\" links@secure_rpc.3c get_myaddress.3c .\" links@secure_rpc.3c getnetaddress.3c .\" links@secure_rpc.3c getnetname.3c .\" links@secure_rpc.3c host2netname.3c .\" links@secure_rpc.3c key_decryptsession.3c .\" links@secure_rpc.3c key_encryptsession.3c .\" links@secure_rpc.3c key_gendes.3c .\" links@secure_rpc.3c key_setsecret.3c .\" links@secure_rpc.3c netname2host.3c .\" links@secure_rpc.3c netname2user.3c .\" links@secure_rpc.3c user2netname.3c .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: getut.3c,v 76.1 95/07/05 17:30:22 ssa Exp $ .TA g .TH getut 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getutent(\|), getutent_r(\|), getutid(\|), getutid_r(\|), getutline(\|), getutline_r(\|), pututline(\|), pututline_r(\|), _pututline(\|), setutent(\|), setutent_r(\|), endutent(\|), endutent_r(\|), utmpname(\|), utmpname_r(\|) \- access utmp file entry .SH SYNOPSIS .C "#include " .PP .C "struct utmp *getutent(void);" .PP .C "int getutent_r(struct utmp **utmp, struct utmp_data *ud);" .PP .C "struct utmp *getutid(const struct utmp *id);" .nf .PD 0 .PP .C "int getutid_r(" .nf .PD 0 .IP .C "struct utmp *id," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *getutline(const struct utmp *line);" .PP .C "int getutline_r(" .PD 0 .IP .C "struct utmp *line," .C "struct utmp **utmp," .C "struct utmp_data *ud);" .PD .PP .C "struct utmp *_pututline(const struct utmp *utmp);" .PP .C "void pututline(const struct utmp *utmp);" .PP .C "int pututline_r(const struct utmp *utmp, struct utmp_data *ud);" .PP .C "void setutent(void);" .PP .C "void setutent_r(struct utmp_data *ud);" .PP .C "void endutent(void);" .PP .C "void endutent_r(struct utmp_data *ud);" .PP .C "void utmpname(const char *file);" .PP .C "void utmpname_r(const char *file);" .fi .SH DESCRIPTION .CR getutent() , .CR getutid() , and .C getutline() each return a pointer to a structure of the following type: .RS .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id (usually line #) */ char ut_line[12]; /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status { short e_termination; /* Process termination status */ short e_exit; /* Process exit status */ } ut_exit; /* The exit status of a process */ /* marked as DEAD_PROCESS. */ unsigned short ut_reserved1; /* Reserved for future use */ time_t ut_time; /* time entry was made */ char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/ unsigned long ut_addr; /* Internet addr of host, if remote */ }; .ps .ft .fi .RE .TP 20 .C getutent() Reads in the next entry from a .CR utmp -like file. If the file is not already open, .C getutent() opens it. If it reaches the end of the file, .C getutent() fails. .TP .C getutid() Searches forward from the current point in the .I utmp file until it finds an entry with a .C ut_type matching .IR id \(mi> ut_type if the type specified is .CR RUN_LVL , .CR BOOT_TIME , .CR OLD_TIME , or .CR NEW_TIME . If the type specified in .I id is .RC INIT_PROCESS , .RC LOGIN_PROCESS , .RC USER_PROCESS , or .RC DEAD_PROCESS , .C getutid() returns a pointer to the first entry whose type is one of these four, and whose .C ut_id field matches .IR id \(mi> ut_id . If end-of-file is reached without a match, .C getutid() fails. .TP .C getutline() Searches forward from the current point in the .I utmp file until it finds an entry of type .C LOGIN_PROCESS or .C USER_PROCESS that also has a .C ut_line string matching the .IR line \(mi> ut_line string. If end-of-file is reached without a match, .C getutline() fails. .TP .C pututline() Writes out the supplied .C utmp structure into the .I utmp file, translates the supplied .I utmp structure int a .I utmpx structure and writes it to a .I utmpx file. .C pututline() uses .C getutid() to search forward for the proper location if it is not already there. It is normally expected that the application program has already searched for the proper entry by using one of the .C getut() routines before calling .CR pututline() . If the search as already been made, .C pututline() does not repeat it. If .C pututline() does not find a matching slot for the new entry, it adds a new entry to the end of the file. .TP .C _pututline() Performs the same actions as .CR pututline() , except that it returns a value useful for error checking. .TP .C setutent() Resets the input stream to the beginning of the file. This should be done before each search for a new entry if it is desired that the entire file be examined. .TP .C endutent() Closes the currently open file. .TP .C utmpname() Allows the user to change the name of the file being examined from .C /etc/utmp and .C /etc/utmpx to any other file(s). In this case, the name provided to .C utmpname will be used for the .I utmp functions. An "x" will be appended to this name, and will be used by the .I getutx functions. The one exception to this are the .I putut(x) functions as they access both files in an attempt to keep the .I utmp and .I utmpx files in sync. The other file(s) are usually .CR /var/adm/wtmp and .CR /var/adm/wtmpx . If the file(s) do not exist, its absence is not discovered until the first subsequent attempt to reference the file. .C utmpname() does not open the file \(em it merely closes the old file if it is currently open, and saves the new file name. .PP The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are made. During each call to either .C getutid() or .CR getutline() , the static structure is examined before performing more .SM I/O. If the contents of the static structure match what the routine is searching for, no additional searching is done. Therefore, if using .C getutline() to search for multiple occurrences, it is necessary to zero out the static structure after each success; otherwise .C getutline() simply returns the same pointer over and over again. There is one exception to the rule about removing the structure before a new read: The implicit read done by .C pututline() (if it finds that it is not already at the correct place in the file) does not alter the contents of the static structure returned by .CR getutent() , .CR getutid() , or .C getutline() if the user has just modified those contents and passed the pointer back to .CR pututline() . .SS Reentrant Interfaces .PP All the reentrant .C "(_r)" routines, except .CR utmpname_r() , expect a parameter, .IR ud , which is a pointer to a .C "struct utmp_data" structure, defined in .CR as: .nf .IP .C "struct utmp_data {" .C "int fd; /* file descriptor for utmp file */" .C "int fd_flags; /* the flags bits used to open the utmp file */" .C "long loc_utmp; /* current position in the utmp file */" .C "struct utmp ubuf /* copy of last entry read in */" .C "} ;" .fi .RE .PP When a program first calls one of these routines, it must initialize the structure member, .IR fd , to a negative integer, (e.g -1). After such call, it shall not change the members in any way. .PP Additionally, .C getutent_r() and .C getutid_r() require a .CI "struct utmp " **utmp parameter to store and return a pointer to the corresponding .I utmp entry. .PP .C utmpname_r() does not close the current .CR utmp file. It is the caller responsibility to ensure this file is closed by calling .C endutent_r(). .SH RETURN VALUE These functions return a .SM NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to write. They also return a .SM NULL pointer if the size of the file is not an integral multiple of .CR "sizeof(struct utmp)" . .PP .C _pututline() behaves the same as .CR pututline() , except that it returns a pointer to a static location containing the most current utmp entry if the .C _pututline() call succeeds. The contents of this structure is identical to the contents of the supplied .C utmp structure if successful. If .C _pututline() fails upon writing to .C utmp , it returns a .SM NULL pointer. If .C _putuline() is successful in writing to the .C utmp file and fails in writing to the .C utmpx file, then _pututline will behave as if it succeeded. .SM Please Note that the .C utmp file and the .C utmpx file may not be in sync due to the above behavior. .C pututline() and .C _pututline() are only guaranteed to have written to the .C utmp file upon successful completion. .SS Reentrant Interfaces .PP Upon successful completion, .CR getutent_r() , .CR getutid_r() , .CR getutline_r() and .CR pututline_r() return 0. Otherwise, they all return -1 and set .CR errno . .SH ERRORS .SS Reentrant Interfaces .RS .TP 12 .SM [EINVAL] .IR utmp or .IR ud parameter is equal to .SM NULL . .RE .SH WARNINGS .CR getutent() , .CR getutid() , .CR getutline() , .CR pututline() , .CR setutent() , .CR endutent() , and .C utmpname() are unsafe in multi-thread applications. .CR getutent_r() , .CR getutid_r() , .CR getutline_r() , .CR pututline_r() , .CR setutent_r() , .CR endutent_r() , and .C utmpname_r() are MT-Safe and should be used instead. .PP Some vendors' versions of .C getutent() erase the .I utmp file if the file exists but is not an integral multiple of .CR "sizeof(struct utmp)" . Given the possiblity of user error in providing a name to .I utmpname (such as giving improper arguments to .IR who (1)), .SM HP-UX does not do this, but instead returns an error indication. .PP For portability, .C getutx functions are preferred over these functions. .SH FILES .C /etc/utmp .br .C /etc/utmpx .br .C /var/adm/wtmp .SH SEE ALSO ttyslot(3C), utmp(4), pututxline(3). .SH STANDARDS CONFORMANCE .CR endutent() ": SVID2, SVID3, XPG2" .PP .CR getutent() ": SVID2, SVID3, XPG2" .PP .CR getutid() ": SVID2, SVID3, XPG2" .PP .CR getutline() ": SVID2, SVID3, XPG2" .PP .CR pututline() ": SVID2, SVID3, XPG2" .PP .CR setutent() ": SVID2, SVID3, XPG2" .PP .CR utmpname() ": SVID2, SVID3, XPG2" .\" .\" index@\f4getutent()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutent_r()\f1 \- get pointer to next entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutid_r()\f1 \- get pointer to entry matching \f4id()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4getutline_r()\f1 \- get pointer to entry matching \f4line()\f1 in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4pututline_r()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4_pututline()\f1 \- update or create entry in a \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4setutent_r()\f1 \- reset input stream to beginning of \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4endutent_r()\f1 \- close currently open \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmpname()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f4utmpname_r()\f1 \- change name of \f4utmp()\f1 file being examined@@@\f3getut(3C)\f1 .\" index@\f1access \f4utmp()\f1 or \f4wtmp()\f1 file@@@\f3getut(3C)\f1 .\" index@\f4utmp()\f1 or \f4wtmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f4wtmp()\f1 or \f4utmp()\f1 file, access@@@\f3getut(3C)\f1 .\" index@\f1file: access \f4wtmp()\f1 or \f4utmp()\f1 file@@@\f3getut(3C)\f1 .\" .\" toc@\f3getut(3C)\f1:\0\0\f4getutent()\f1, \f4getutent_r()\f1, \f4getutid()\f1, \f4getutid_r()\f1, \f4getutline()\f1, \f4getutline_r()\f1, \n\f4pututline()\f1, \f4pututline_r()\f1, \f4_pututline()\f1, \f4setutent()\f1, \f4setutent_r()\f1, \f4endutent()\f1, \n\f4endutent_r()\f1, \f4utmpname()\f1, \f4utmpname_r()\f1@@@access utmp file entry .\" toc@\f4getutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutid()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4getutline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4_pututline()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4setutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4endutent()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" toc@\f4utmpname()\f1:\0\0access utmp file entry@@@see \f3getut(3C)\f1 .\" .\" links@getut.3c getutent.3c .\" links@getut.3c getutent_r.3c .\" links@getut.3c getutid.3c .\" links@getut.3c getutid_r.3c .\" links@getut.3c getutline.3c .\" links@getut.3c getutline_r.3c .\" links@getut.3c pututline.3c .\" links@getut.3c _pututline.3c .\" links@getut.3c pututline_r.3c .\" links@getut.3c setutent.3c .\" links@getut.3c setutent_r.3c .\" links@getut.3c endutent.3c .\" links@getut.3c endutent_r.3c .\" links@getut.3c utmpname.3c .\" links@getut.3c utmpname_r.3c .\" .\" fileset_database@getut.3c PROGRAMING-MAN .\" $Header: malloc.3c,v 72.6 94/11/15 09:55:17 ssa Exp $ .TA m .TH malloc 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME malloc(), free(), realloc(), calloc(), valloc(), mallopt(), mallinfo(), memorymap(), alloca() \- main memory allocator .SH SYNOPSIS .C "#include " .PP .C "void *malloc(size_t size);" .PP .C "void *calloc(size_t nelem, size_t elsize);" .PP .C "void *realloc(void *ptr, size_t size);" .PP .C "void *valloc(size_t size);" .PP .C "void free(void *ptr);" .PP .C "void memorymap(int show_stats);" .PP .C " " .PP .C "#include " .PP .C "void *alloca(size_t size);" .SH SYSTEM V SYNOPSIS .C "#include " .PP .C "char *malloc(unsigned size);" .PP .C "void free(char *ptr);" .PP .C "char *realloc(char *ptr, unsigned size);" .PP .C "char *calloc(unsigned nelem, unsigned elsize);" .PP .C "int mallopt(int cmd, int value);" .PP .C "struct mallinfo mallinfo(void);" .SS Remarks The functionality in the old .IR malloc (3X) package has been incorporated into .IR malloc (3C). The library .RC ( /usr/lib/libmalloc.a ) corresponding to the .CR -lmalloc linker option is now an empty library. Makefiles that reference this library will continue to work. Applications that used the .IR malloc (3X) package should still work properly with the new .IR malloc (3C) package. If the old versions must be used, they are provided in files .CR /usr/old/libmalloc3x.a and .CR /usr/old/libmalloc3c.o for Release 8.07 only. .SH DESCRIPTION The functions described in this manual entry provide a simple, general purpose memory allocation package: .RS .TP 17 .C malloc() Allocates space for a block of at least .I size bytes, but does not initialize the space. .TP .C calloc() Allocates space for an array of .I nelem elements, each of size .I elsize bytes, and initializes the space to zeros. Actual amount of space allocated will be at least .I nelem * elsize bytes. .TP .C realloc() Changes the size of the block pointed to by .I ptr to .I size bytes and returns a pointer to the (possibly moved) block. Existing contents are unchanged up to the lesser of the new and old sizes. If .I ptr is a NULL pointer, .CR realloc() behaves like .CR malloc() for the specified size. If .I size is zero and .I ptr is not a NULL pointer, the object it points to is freed and NULL is returned. .TP .C valloc() Allocates space for a block of at least .I size bytes starting on a boundary aligned to a multiple of the value returned by .IR sysconf(__SC_PAGESIZE) . This space is uninitialized. .TP .C free() Deallocates the space pointed to by .I ptr (a pointer to a block previously allocated by .CR malloc() , .CR realloc() , or .CR calloc() ) and makes the space available for further allocation. If .I ptr is a NULL pointer, no action occurs. .TP .C mallopt() Provides for control over the allocation algorithm and other options in the .IR malloc (3C) package. The available values for .I cmd are: .RS .RS .TP 15 .C M_MXFAST Set .IR maxfast to .IR value . The algorithm allocates all blocks below the size of .IR maxfast in large groups, then doles them out very quickly. The default value for .IR maxfast is zero. .TP .C M_NLBLKS Set .IR numlblks to .IR value . The above mentioned ``large groups'' each contain .I numlblks blocks. .I numlblks must be greater than 1. The default value for .I numlblks is .CR 100 . .TP .C M_GRAIN Set .I grain to .IR value . The sizes of all blocks smaller than .I maxfast are considered to be rounded up to the nearest multiple of .IR grain . .I grain must be greater than zero. The default value of .I grain is the smallest number of bytes that can accommodate alignment of any data type. .I value is rounded up to a multiple of the default when .I grain is set. .TP .C M_KEEP Preserve data in a freed block until the next .CR malloc() , .CR realloc() , or .CR calloc() . This option is provided only for compatibility with the old version of .CR malloc() and is not recommended. .TP .C M_BLOCK Block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option is provided for those who need to write signal handlers that allocate memory. When set, the .IR malloc (3C) routines can be called from within signal handlers (they become re-entrant). Default action is .I not to block all blockable signals. .TP .C M_UBLOCK Do not block all blockable signals in .CR malloc() , .CR realloc() , .CR calloc() , and .CR free() . This option cancels signal blocking initiated by the .CR M_BLOCK option. .RE .RE .IP These values are defined in the .CR header file. .IP .CR mallopt() can be called repeatedly, but must not be called after the first small block is allocated (unless .I cmd is set to .CR M_BLOCK or .CR M_UBLOCK ). .TP .C mallinfo() Provides instrumentation describing space usage, but cannot be called until the first small block is allocated. It returns the structure: .nf .IP .C "struct mallinfo {" .C " int arena; /* total space in arena */" .C " int ordblks; /* number of ordinary blocks */" .C " int smblks; /* number of small blocks */" .C " int hblkhd; /* space in holding block headers */" .C " int hblks; /* number of holding blocks */" .C " int usmblks /* space in small blocks in use */" .C " int fsmblks /* space in free small blocks */" .C " int uordblks; /* space in ordinary blocks in use */" .C " int fordblks; /* space in free ordinary blocks */" .C " int keepcost; /* space penalty if keep option is used */" .C } .fi .IP This structure is defined in the .CR header file. .RE .PP Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. .RS .TP 17 .C memorymap() Can be used to display the contents of the memory allocator. A list of addresses and block descriptions is written (using .CR printf() ) to standard output. If the value of the .I show_stats parameter is 1, statistics concerning number of blocks and sizes used will also be written. If the value is zero, only the memory map will be written. .IP The addresses and sizes displayed by .CR memorymap() may not correspond to those requested by an application. The size of a block (as viewed by the allocator) includes header information and padding to properly align the block. The address is also offset by a certain amount to accommodate the header information. .TP .C alloca() Allocates space from the stack of the caller for a block of at least .I size bytes, but does not initialize the space. The space is automatically freed when the calling routine exits. .IP Memory returned by .CR alloca() is not related to memory allocated by other memory allocation functions. Behavior of addresses returned by .CR alloca() as parameters to other memory functions is undefined. .IP The implementation of this routine is system dependent and its use is discouraged. .RE .SH RETURN VALUE Upon successful completion, .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. Otherwise, they return a NULL pointer. If .CR realloc() returns a NULL pointer, the memory pointed to by the original pointer is left intact. .PP .CR mallopt() returns zero for success and nonzero for failure. .SH DIAGNOSTICS .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() return a NULL pointer if there is no available memory, or if the memory managed by .CR malloc() has been detectably corrupted. This memory may become corrupted if data is stored outside the bounds of a block, or if an invalid pointer (a pointer not generated by .CR malloc() , .CR realloc() , or .CR calloc() ) is passed as an argument to .CR free() or .CR realloc() . .PP If .CR mallopt() is called after any allocation of a small block and .I cmd is not set to .CR M_BLOCK or .CR M_UBLOCK , or if .I cmd or .I value is invalid, nonzero is returned. Otherwise, it returns zero. .SH ERRORS .RS .TP 17 [ENOMEM] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to ENOMEM and return a NULL pointer when an out-of-memory condition arises. .TP [EINVAL] .CR malloc() , .CR realloc() , .CR calloc() , and .CR valloc() set .CR errno to EINVAL and return a NULL pointer when the memory being managed by .CR malloc() has been detectably corrupted. .SH WARNINGS .CR malloc() functions use .CR brk() and .CR sbrk() (see .IR brk (2)) to increase the address space of a process. Therefore, an application program that uses .CR brk() or .CR sbrk() must not use them to decrease the address space, because this confuses the .CR malloc() functions. .PP .CR free() and .CR realloc() do not check their pointer argument for validity. .PP If .CR free() or .CR realloc() is passed a pointer that was not the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() , or if space assigned by an allocation function is overrun, loss of data, a memory fault, bus error, or an infinite loop may occur at that time or during any subsequent call to .CR malloc() , .CR realloc() , .CR calloc() , .CR valloc() , or .CR free() . .PP The following actions are not supported and cause undesirable effects: .RS .TP 3 \(bu Attempting to .CR free() or .CR realloc() a pointer not generated as the result of a call to .CR malloc() , .CR realloc() , .CR calloc() , or .CR valloc() . .RE .PP The following actions are strongly discouraged and may be unsupported in a future implementation of .CR malloc() : .RS .TP 3 \(bu attempting to .CR free() the same block twice, .TP \(bu depending on unmodified contents of a block after it has been freed. .RE .PP Undocumented features of earlier memory allocators have not been duplicated. .SH COMPATIBILITY The only external difference between the old .IR malloc (3X) allocator and the .IR malloc (3C) allocator is that the old allocator would return a NULL pointer for a request of zero bytes. The .IR malloc (3C) allocator returns a valid memory address. This is not a concern for most applications. .ift .br .ift .ne 4 .PP Although the current implementation of .IR malloc (3C) allows for freeing a block twice and does not corrupt the contents of a block after it is freed (until the next call to .CR realloc() , .CR calloc() , .CR malloc() , or .CR valloc() ), support for these features may be discontinued in a future implementation of .IR malloc (3C) and should not be used. .SH SEE ALSO brk(2), errno(2). .SH STANDARDS CONFORMANCE .CR malloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR calloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR free() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR mallinfo() ": SVID2, XPG2" .PP .CR mallopt() ": SVID2, SVID3, XPG2" .PP .CR realloc() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4malloc()\f1 \- allocate block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4free()\f1 \- release allocated block of main memory@@@\f3malloc(3C)\f1 .\" index@\f4realloc()\f1 \- change size of allocated memory block@@@\f3malloc(3C)\f1 .\" index@\f4calloc()\f1 \- allocate memory for array@@@\f3malloc(3C)\f1 .\" index@\f4mallopt()\f1 \- control memory space allocation@@@\f3malloc(3C)\f1 .\" index@\f4mallinfo()\f1 \- display memory space usage@@@\f3malloc(3C)\f1 .\" index@\f4memorymap()\f1 \- display contents of memory allocator@@@\f3malloc(3C)\f1 .\" index@\f4alloca()\f1 \- allocate space from the stack@@@\f3malloc(3C)\f1 .\" index@\f4valloc()\f1 \- allocate space on boundary aligned to sysconf value@@@\f3malloc(3C)\f1 .\" index@\f1main memory allocator@@@\f3malloc(3C)\f1 .\" index@\f1memory allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1allocator for main memory@@@\f3malloc(3C)\f1 .\" index@\f1main memory space usage, display@@@\f3malloc(3C)\f1 .\" index@\f1main memory space allocation, control@@@\f3malloc(3C)\f1 .\" .\" toc@\f3malloc(3C)\f1:\0\0\f4alloca()\f1, \f4calloc()\f1, \f4free()\f1, \f4mallinfo()\f1,\n\f4malloc()\f1, \f4mallopt()\f1, \f4memorymap()\f1, \f4realloc()\f1, \f4valloc()\f1@@@main memory allocator\f1 .\" .\" toc@\f4free()\f1:\0\0release allocated block of main memory@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4realloc()\f1:\0\0change size of allocated memory block@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4calloc()\f1:\0\0allocate memory for array@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4valloc()\f1:\0\0allocate space on boundary aligned to sysconf value@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallopt()\f1:\0\0control memory space allocation@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4mallinfo()\f1:\0\0display memory space usage@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4memorymap()\f1:\0\0display contents of memory allocator@@@\f1see \f3malloc(3C)\f1 .\" toc@\f4alloca()\f1:\0\0allocate space from the stack@@@\f1see \f3malloc(3C)\f1 .\" .\" links@malloc.3c free.3c .\" links@malloc.3c realloc.3c .\" links@malloc.3c calloc.3c .\" links@malloc.3c valloc.3c .\" links@malloc.3c mallopt.3c .\" links@malloc.3c mallinfo.3c .\" links@malloc.3c memorymap.3c .\" links@malloc.3c alloca.3c .\" $Header: vprintf.3s,v 78.1 96/03/15 16:47:24 ssa Exp $ .TA v .TH vprintf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vprintf(), vfprintf(), vsprintf() \- print formatted output of a varargs argument list .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "int vprintf(const char *format, va_list ap);" .PP .C "int vfprintf(FILE *stream, const char *format, va_list ap);" .PP .C "int vsprintf(char *s, const char *format, va_list ap);" .SH DESCRIPTION .CR vprintf() , .CR vfprintf() , and .C vsprintf() are the same as .CR printf() , .CR fprintf() , and .C sprintf() respectively, except that instead of being called with a variable number of arguments, they are called with an argument list as defined by .CR . .SH EXAMPLE The following demonstrates how .CR vfprintf() could be used to write an error routine: .nf .IP .ift .ft 4 .ps +1 #include #include . . . /* * error should be called using the form: * error(function_name, format, arg1, arg2...); */ /*VARARGS0*/ void error(va_alist) va_dcl { va_list args; char *fmt; va_start(args); /* print out name of function causing error */ (void)fprintf(stderr, "ERROR in %s: ", va_arg(args, char *)); fmt = va_arg(args, char *); /* print out remainder of message */ (void)vfprintf(stderr, fmt, args); va_end(args); (void)abort( ); } .ift .ft 1 .ps .fi .SH SEE ALSO printf(3S), setlocale(3C), varargs(5). .SH STANDARDS CONFORMANCE .CR vprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR vfprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR vsprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4vprintf()\f1 \- print formatted output of a varargs argument list@@@\f3vprintf(3S)\f1 .\" index@\f4vfprintf()\f1 \- print formatted output of a varargs argument list@@@\f3vprintf(3S)\f1 .\" index@\f4vsprintf()\f1 \- print formatted output of a varargs argument list@@@\f3vprintf(3S)\f1 .\" index@print formatted output of a varargs argument list@@@\f3vprintf(3S)\f1 .\" index@formatted output of a varargs argument list, print@@@\f3vprintf(3S)\f1 .\" index@output of a varargs argument list, print formatted@@@\f3vprintf(3S)\f1 .\" index@varargs argument list, print formatted output of a@@@\f3vprintf(3S)\f1 .\" index@argument list, print formatted output of a varargs@@@\f3vprintf(3S)\f1 .\" index@list, print formatted output of a varargs argument@@@\f3vprintf(3S)\f1 .\" .\" toc@\f3vprintf(3S)\f1:\0\0\f4vprintf()\f1, \f4vfprintf()\f1, \f4vsprintf()\f1@@@print formatted output of a varargs argument list .\" toc@\f4vfprintf()\f1:\0\0print formatted output of a varargs argument list@@@see \f3vprintf(3S)\f1 .\" toc@\f4vsprintf()\f1:\0\0print formatted output of a varargs argument list@@@see \f3vprintf(3S)\f1 .\" .\" links@vprintf.3s vfprintf.3s .\" links@vprintf.3s vsprintf.3s .\" $Header: vscanf.3s,v 72.3 93/01/14 14:39:08 ssa Exp $ .TA v .TH vscanf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vscanf(\|), vfscanf(\|), vsscanf(\|) \- formatted input conversion to a varargs argument list, read from stream file .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "int vscanf(const char *format, va_list ap);" .PP .C "int vfscanf(FILE *stream, const char *format, va_list ap);" .PP .C "int vsscanf(char *s, const char *format, va_list ap);" .SH DESCRIPTION .CR vscanf() , .CR vfscanf() , and .C vsscanf() are the same as .CR scanf() , .CR fscanf() , and .C sscanf() respectively, except that instead of being called with a variable number of arguments, they are called with an argument list as defined by .IR varargs (5). .SH SEE ALSO scanf(3S), setlocale(3C), varargs(5). .\" .\" index@\f4vscanf()\fP \- formatted input conversion to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@\f4vfscanf()\fP \- formatted input conversion to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@\f4vsscanf()\fP \- formatted input conversion to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@formatted input conversion to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@input conversion, formatted, to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@conversion, formatted input, to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@varargs argument, formatted input conversion to a@@@\f3vscanf(3S)\f1 .\" index@argument, varargs, formatted input conversion to a@@@\f3vscanf(3S)\f1 .\" .\" toc@\f3vscanf(3S)\f1:\0\0\f4vscanf()\fP, \f4vfscanf()\fP, \f4vsscanf()\fP@@@formatted input conversion to a varargs argument .\" toc@\f4vfscanf()\fP: formatted input conversion to a varargs argument@@@see \f3vscanf(3S)\f1 .\" toc@\f4vsscanf()\fP: formatted input conversion to a varargs argument@@@see \f3vscanf(3S)\f1 .\" links@vscanf.3s vfscanf.3s .\" links@vscanf.3s vsscanf.3s .\" .\" fileset_database@vscanf.3s PROGRAMING-MAN .\" $Header: vidattr.3x,v 76.2 95/08/01 15:21:23 ssa Exp $ .TA v .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH vidattr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vidattr, vid_attr, vidputs, vid_puts \(em output attributes to the terminal .SH SYNOPSIS .C "#include " .P .C "int vidattr(chtype \f2attr\f4);" .P .C "int vid_attr(attr_t \f2attr\f4, short \f2color_pair_number\f1, void *\f2opt\f1);" .P .C "int vidputs(chtype \f2attr\f4, int (*\f2putfunc\f4)(int));" .P .C "int vid_puts(attr_t \f2attr\f4, short \f2color_pair_number\f1, void *\f2opt\f1, wint_t (*\f2putwfunc\f4)(wint_t));" .SH DESCRIPTION These functions output commands to the terminal that change the terminal's attributes. .P If the \f3terminfo\f1 database indicates that the terminal in use can display characters in the rendition specified by \f2attr\f1, then .Fn vidattr outputs one or more commands to request that the terminal display subsequent characters in that rendition. The function outputs by calling .Fn putchar . The .Fn vidattr function neither relies on nor updates the model Curses maintains of the prior rendition mode. .P The .Fn vidputs function computes the same terminal output string that .Fn vidattr does, based on \f2attr\f1, but .Fn vidputs outputs by calling the user-supplied function .I putfunc . .P The user-supplied function .I putfunc (specified as an argument to .Fn vidputs ) is either .Fn putchar or some other function with the same prototype. The .Fn vidputs function ignores the return value of .I putfunc . .P The .Fn vid_attr and .Fn vid_puts functions correspond to .Fn vidattr and .Fn vidputs , respectively, but take a set of arguments, one of type .B attr_t for the attributes .B short for the color pair number and .B "void *" and thus support the attribute constants with the WA_ prefix. .P The \f2opts\f1 argument is reserved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .P The user-supplied function .I putwfunc (specified as an argument to .Fn vid_puts ) is either .Fn putwchar or some other function with the same prototype. The .Fn vid_puts function ignores the return value of .I putwfunc . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" After use of any of these functions, the model Curses maintains of the state of the terminal might not match the actual state of the terminal. The application should touch and refresh the window before resuming conventional use of Curses. .P Use of these functions requires that the application contain so much information about a particular class of terminal that it defeats the purpose of using Curses. .P On some terminals, a command to change rendition conceptually occupies space in the screen buffer (with or without width). Thus, a command to set the terminal to a new rendition would change the rendition of some characters already displayed. .SH "SEE ALSO" doupdate(), is_linetouched(), putchar() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), putwchar() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), tigetflag(), . .br .ne 4 .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3vidattr(3x)\f1:\0\0\f4vidattr()\f1@@@output attributes to the terminal .\" toc@\f3vid_attr()\f1:\0\0output attributes to the terminal@@@\f1see \f3vidattr(3x)\f1 .\" toc@\f3vidputs()\f1:\0\0output attributes to the terminal@@@\f1see \f3vidattr(3x)\f1 .\" toc@\f3vid_puts()\f1:\0\0output attributes to the terminal@@@\f1see \f3vidattr(3x)\f1 .\" .\" index@\f4vidattr()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f4vid_attr()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f4vidputs()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f4vid_puts()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f1output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f1terminal, output attributes@@@\f3vidattr(3x)\f1 .\" .\" links@vidattr.3x vid_attr.3x .\" links@vidattr.3x vidputs.3x .\" links@vidattr.3x vid_puts.3x .\" .\" fileset_database@vidattr.3x CURS-ENG-A-MAN .\" .\" $Header: vidattr.3x,v 76.2 95/08/01 15:21:23 ssa Exp $ .TA v .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH vidattr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vidattr, vid_attr, vidputs, vid_puts \(em output attributes to the terminal .SH SYNOPSIS .C "#include " .P .C "int vidattr(chtype \f2attr\f4);" .P .C "int vid_attr(attr_t \f2attr\f4, short \f2color_pair_number\f1, void *\f2opt\f1);" .P .C "int vidputs(chtype \f2attr\f4, int (*\f2putfunc\f4)(int));" .P .C "int vid_puts(attr_t \f2attr\f4, short \f2color_pair_number\f1, void *\f2opt\f1, wint_t (*\f2putwfunc\f4)(wint_t));" .SH DESCRIPTION These functions output commands to the terminal that change the terminal's attributes. .P If the \f3terminfo\f1 database indicates that the terminal in use can display characters in the rendition specified by \f2attr\f1, then .Fn vidattr outputs one or more commands to request that the terminal display subsequent characters in that rendition. The function outputs by calling .Fn putchar . The .Fn vidattr function neither relies on nor updates the model Curses maintains of the prior rendition mode. .P The .Fn vidputs function computes the same terminal output string that .Fn vidattr does, based on \f2attr\f1, but .Fn vidputs outputs by calling the user-supplied function .I putfunc . .P The user-supplied function .I putfunc (specified as an argument to .Fn vidputs ) is either .Fn putchar or some other function with the same prototype. The .Fn vidputs function ignores the return value of .I putfunc . .P The .Fn vid_attr and .Fn vid_puts functions correspond to .Fn vidattr and .Fn vidputs , respectively, but take a set of arguments, one of type .B attr_t for the attributes .B short for the color pair number and .B "void *" and thus support the attribute constants with the WA_ prefix. .P The \f2opts\f1 argument is reserved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .P The user-supplied function .I putwfunc (specified as an argument to .Fn vid_puts ) is either .Fn putwchar or some other function with the same prototype. The .Fn vid_puts function ignores the return value of .I putwfunc . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" After use of any of these functions, the model Curses maintains of the state of the terminal might not match the actual state of the terminal. The application should touch and refresh the window before resuming conventional use of Curses. .P Use of these functions requires that the application contain so much information about a particular class of terminal that it defeats the purpose of using Curses. .P On some terminals, a command to change rendition conceptually occupies space in the screen buffer (with or without width). Thus, a command to set the terminal to a new rendition would change the rendition of some characters already displayed. .SH "SEE ALSO" doupdate(), is_linetouched(), putchar() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), putwchar() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), tigetflag(), . .br .ne 4 .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3vidattr(3x)\f1:\0\0\f4vidattr()\f1@@@output attributes to the terminal .\" toc@\f3vid_attr()\f1:\0\0output attributes to the terminal@@@\f1see \f3vidattr(3x)\f1 .\" toc@\f3vidputs()\f1:\0\0output attributes to the terminal@@@\f1see \f3vidattr(3x)\f1 .\" toc@\f3vid_puts()\f1:\0\0output attributes to the terminal@@@\f1see \f3vidattr(3x)\f1 .\" .\" index@\f4vidattr()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f4vid_attr()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f4vidputs()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f4vid_puts()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f1output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f1terminal, output attributes@@@\f3vidattr(3x)\f1 .\" .\" links@vidattr.3x vid_attr.3x .\" links@vidattr.3x vidputs.3x .\" links@vidattr.3x vid_puts.3x .\" .\" fileset_database@vidattr.3x CURS-ENG-A-MAN .\" .\" $Header: vidattr.3x,v 76.2 95/08/01 15:21:23 ssa Exp $ .TA v .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH vidattr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vidattr, vid_attr, vidputs, vid_puts \(em output attributes to the terminal .SH SYNOPSIS .C "#include " .P .C "int vidattr(chtype \f2attr\f4);" .P .C "int vid_attr(attr_t \f2attr\f4, short \f2color_pair_number\f1, void *\f2opt\f1);" .P .C "int vidputs(chtype \f2attr\f4, int (*\f2putfunc\f4)(int));" .P .C "int vid_puts(attr_t \f2attr\f4, short \f2color_pair_number\f1, void *\f2opt\f1, wint_t (*\f2putwfunc\f4)(wint_t));" .SH DESCRIPTION These functions output commands to the terminal that change the terminal's attributes. .P If the \f3terminfo\f1 database indicates that the terminal in use can display characters in the rendition specified by \f2attr\f1, then .Fn vidattr outputs one or more commands to request that the terminal display subsequent characters in that rendition. The function outputs by calling .Fn putchar . The .Fn vidattr function neither relies on nor updates the model Curses maintains of the prior rendition mode. .P The .Fn vidputs function computes the same terminal output string that .Fn vidattr does, based on \f2attr\f1, but .Fn vidputs outputs by calling the user-supplied function .I putfunc . .P The user-supplied function .I putfunc (specified as an argument to .Fn vidputs ) is either .Fn putchar or some other function with the same prototype. The .Fn vidputs function ignores the return value of .I putfunc . .P The .Fn vid_attr and .Fn vid_puts functions correspond to .Fn vidattr and .Fn vidputs , respectively, but take a set of arguments, one of type .B attr_t for the attributes .B short for the color pair number and .B "void *" and thus support the attribute constants with the WA_ prefix. .P The \f2opts\f1 argument is reserved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .P The user-supplied function .I putwfunc (specified as an argument to .Fn vid_puts ) is either .Fn putwchar or some other function with the same prototype. The .Fn vid_puts function ignores the return value of .I putwfunc . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" After use of any of these functions, the model Curses maintains of the state of the terminal might not match the actual state of the terminal. The application should touch and refresh the window before resuming conventional use of Curses. .P Use of these functions requires that the application contain so much information about a particular class of terminal that it defeats the purpose of using Curses. .P On some terminals, a command to change rendition conceptually occupies space in the screen buffer (with or without width). Thus, a command to set the terminal to a new rendition would change the rendition of some characters already displayed. .SH "SEE ALSO" doupdate(), is_linetouched(), putchar() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), putwchar() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), tigetflag(), . .br .ne 4 .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3vidattr(3x)\f1:\0\0\f4vidattr()\f1@@@output attributes to the terminal .\" toc@\f3vid_attr()\f1:\0\0output attributes to the terminal@@@\f1see \f3vidattr(3x)\f1 .\" toc@\f3vidputs()\f1:\0\0output attributes to the terminal@@@\f1see \f3vidattr(3x)\f1 .\" toc@\f3vid_puts()\f1:\0\0output attributes to the terminal@@@\f1see \f3vidattr(3x)\f1 .\" .\" index@\f4vidattr()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f4vid_attr()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f4vidputs()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f4vid_puts()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f1output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f1terminal, output attributes@@@\f3vidattr(3x)\f1 .\" .\" links@vidattr.3x vid_attr.3x .\" links@vidattr.3x vidputs.3x .\" links@vidattr.3x vid_puts.3x .\" .\" fileset_database@vidattr.3x CURS-ENG-A-MAN .\" .\" $Header: vidattr.3x,v 76.2 95/08/01 15:21:23 ssa Exp $ .TA v .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH vidattr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vidattr, vid_attr, vidputs, vid_puts \(em output attributes to the terminal .SH SYNOPSIS .C "#include " .P .C "int vidattr(chtype \f2attr\f4);" .P .C "int vid_attr(attr_t \f2attr\f4, short \f2color_pair_number\f1, void *\f2opt\f1);" .P .C "int vidputs(chtype \f2attr\f4, int (*\f2putfunc\f4)(int));" .P .C "int vid_puts(attr_t \f2attr\f4, short \f2color_pair_number\f1, void *\f2opt\f1, wint_t (*\f2putwfunc\f4)(wint_t));" .SH DESCRIPTION These functions output commands to the terminal that change the terminal's attributes. .P If the \f3terminfo\f1 database indicates that the terminal in use can display characters in the rendition specified by \f2attr\f1, then .Fn vidattr outputs one or more commands to request that the terminal display subsequent characters in that rendition. The function outputs by calling .Fn putchar . The .Fn vidattr function neither relies on nor updates the model Curses maintains of the prior rendition mode. .P The .Fn vidputs function computes the same terminal output string that .Fn vidattr does, based on \f2attr\f1, but .Fn vidputs outputs by calling the user-supplied function .I putfunc . .P The user-supplied function .I putfunc (specified as an argument to .Fn vidputs ) is either .Fn putchar or some other function with the same prototype. The .Fn vidputs function ignores the return value of .I putfunc . .P The .Fn vid_attr and .Fn vid_puts functions correspond to .Fn vidattr and .Fn vidputs , respectively, but take a set of arguments, one of type .B attr_t for the attributes .B short for the color pair number and .B "void *" and thus support the attribute constants with the WA_ prefix. .P The \f2opts\f1 argument is reserved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .P The user-supplied function .I putwfunc (specified as an argument to .Fn vid_puts ) is either .Fn putwchar or some other function with the same prototype. The .Fn vid_puts function ignores the return value of .I putwfunc . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" After use of any of these functions, the model Curses maintains of the state of the terminal might not match the actual state of the terminal. The application should touch and refresh the window before resuming conventional use of Curses. .P Use of these functions requires that the application contain so much information about a particular class of terminal that it defeats the purpose of using Curses. .P On some terminals, a command to change rendition conceptually occupies space in the screen buffer (with or without width). Thus, a command to set the terminal to a new rendition would change the rendition of some characters already displayed. .SH "SEE ALSO" doupdate(), is_linetouched(), putchar() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), putwchar() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), tigetflag(), . .br .ne 4 .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3vidattr(3x)\f1:\0\0\f4vidattr()\f1@@@output attributes to the terminal .\" toc@\f3vid_attr()\f1:\0\0output attributes to the terminal@@@\f1see \f3vidattr(3x)\f1 .\" toc@\f3vidputs()\f1:\0\0output attributes to the terminal@@@\f1see \f3vidattr(3x)\f1 .\" toc@\f3vid_puts()\f1:\0\0output attributes to the terminal@@@\f1see \f3vidattr(3x)\f1 .\" .\" index@\f4vidattr()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f4vid_attr()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f4vidputs()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f4vid_puts()\f1 \- output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f1output attributes to terminal@@@\f3vidattr(3x)\f1 .\" index@\f1terminal, output attributes@@@\f3vidattr(3x)\f1 .\" .\" links@vidattr.3x vid_attr.3x .\" links@vidattr.3x vidputs.3x .\" links@vidattr.3x vid_puts.3x .\" .\" fileset_database@vidattr.3x CURS-ENG-A-MAN .\" .\" $Header: hline.3x,v 76.2 95/08/01 11:07:23 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline, mvhline, mvvline, mvwhline, mvwvline, vline, whline, wvline \(em draw lines from single-byte characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvhline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvvline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwhline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwvline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int vline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int whline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int wvline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline() , .CR mvhline() , .Fn mvwhline and .Fn whline functions draw a line proceeding toward the last column of the same line. .P The .CR vline() , .CR mvvline() , .Fn mvwvline and .Fn wvline functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" border(), box(), hline_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline(3X)\f1:\0\0\f4hline()\f1, \f4mvhline()\f1, \f4mvvline()\f1, \f4mvwhline()\f1, \f4mvwvline()\f1, \f4vline()\f1, \f4whline()\f1, \f4wvline()\f1\n@@@draw lines from single-byte characters and renditions .\" toc@\f4mvhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4vline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4whline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4wvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" .\" index@\f4hline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4vline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4whline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4wvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1lines, draw from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1single-byte characters and renditions, draw lines from@@@\f3hline(3X)\f1 .\" index@\f1characters and renditions, draw lines from single-byte@@@\f3hline(3X)\f1 .\" index@\f1renditions and characters, draw lines from single-byte@@@\f3hline(3X)\f1 .\" .\" links@hline.3x mvhline.3x .\" links@hline.3x mvvline.3x .\" links@hline.3x mvwhline.3x .\" links@hline.3x mvwvline.3x .\" links@hline.3x vline.3x .\" links@hline.3x whline.3x .\" links@hline.3x wvline.3x .\" .\" fileset_database@hline.3x CURS-ENG-A-MAN .\" $Header: hline_set.3x,v 76.2 95/08/01 11:08:14 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline_set 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline_set, mvhline_set, mvvline_set, mvwhline_set, mvwvline_set, vline_set, whline_set, wvline_set \(em draw lines from complex characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvhline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvvline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwhline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwvline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int vline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int whline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int wvline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline_set() , .CR mvhline_set() , .Fn mvwhline_set and .Fn whline_set functions draw a line proceeding toward the last column of the same line. .P The .CR vline_set() , .CR mvvline_set() , .Fn mvwvline_set and .Fn wvline_set functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" border_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline_set(3X)\f1:\0\0\f4hline_set()\f1, \f4mvhline_set()\f1, \f4mvvline_set()\f1, \f4mvwhline_set()\f1, \f4mvwvline_set()\f1, \n\f4vline_set()\f1, \f4whline_set()\f1, \f4wvline_set()\f1@@@draw lines from complex characters and renditions .\" toc@\f4mvhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4vline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4whline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4wvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" .\" index@\f4hline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4vline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4whline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4wvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1lines, draw from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1complex characters and renditions, draw lines from@@@\f3hline_set(3X)\f1 .\" index@\f1characters and renditions, complex, draw lines from@@@\f3hline_set(3X)\f1 .\" .\" links@hline_set.3x mvhline_set.3x .\" links@hline_set.3x mvvline_set.3x .\" links@hline_set.3x mvwhline_set.3x .\" links@hline_set.3x mvwvline_set.3x .\" links@hline_set.3x vline_set.3x .\" links@hline_set.3x whline_set.3x .\" links@hline_set.3x wvline_set.3x .\" .\" fileset_database@hline_set.3x CURS-ENG-A-MAN .\" $Header: pfmt.3c,v 72.3 94/07/22 11:26:34 ssa Exp $ .TA p .TH pfmt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME pfmt(), vpfmt() \- display message in standard format .SH SYNOPSIS .nf .C "#include " .C "int pfmt(FILE *stream, long flags, char *fmt, /* [arg, ] */ ...);" .PP .C "#include " .C "#include " .C "int vpfmt(FILE *stream, long flags, char *fmt, va_list ap);" .fi .SH DESCRIPTION The .CR pfmt() system call can be used to write a message in standard format to .IR stream . It can also be used to write a localized string to .IR stream . The arguments to .CR pfmt() are formatted using .CR printf() style formatting. .CR vpfmt() is similar to .CR pfmt() except that the arguments are passed in an argument list (see .IR stdarg (5)). .PP The standard format displayed to .I stream has the following fields: .IP .IC label : severity : text .PP The .I label string is defined through .IR setlabel (3C). If no label is defined, this field is not used. The .I severity string is controlled by the .I severity group of .IR flags . The .I text string is the formatted user string. .PP The .I flags control how formatting is done. The control information is separated into several different groups. Only one flag from each group should be set. .RS .TP .B "Output Format" .RS .TP 20 .C MM_NOSTD Do not use the standard format. Treat .I fmt as a .CR printf() format string. In this mode, only flags related to catalog access can be set. .TP .C MM_STD Format using the standard format .RC ( MM_STD is the default). .RE .TP .B "Catalog Access" .RS .TP 20 .C MM_NOGET Do not access the localized message catalog. Use the .I def_str (a field in .I fmt ) as the format string. .TP .C MM_GET Access the localized message catalog .RC ( MM_GET is the default). .RE .TP .B "Severity" .RS .TP 20 .C MM_HALT Display a localized .CR HALT string. .TP .C MM_ERROR Display a localized .CR ERROR string .RC ( MM_ERROR is the default). .TP .C MM_WARNING Display a localized .CR WARNING string. .TP .C MM_INFO Display a localized .CR INFO string. .RE .IP Besides these reserved severities, additional severity strings may be defined by the user (see .IR addsev (3C)). To specify a user defined severity, .IR flags should be a logical-or of the numeric value of the user defined severity and flags from other control groups. .TP .B "Action" .RS .TP 20 .C MM_ACTION This flag generates the localized string of .CR "TO FIX:" in the .I severity field of the standard format message. If this flag and flags from the severity control group are set, this flag has precedence and the .CR "TO FIX:" string will be displayed. .RE .RE .PP The .I fmt string has the following fields: .IP .IC catalog : msg_number : def_str .PP The .I catalog is the message catalog created by .IR mkmsgs (1) where the localized message is to be retrieved. The .I msg_number is a positive index number identifying the string to be retrieved from the message catalog (begins at 1). The .I def_str is the default string to use if .CR pfmt() fails to retrieve the message from .I catalog from either the current locale or the default locale. The failure may occur if the message catalog does not exist or if the .I msg_number is out of bound. .PP If .I catalog is not specified, .CR pfmt() uses the message catalog defined by .IR setcat (3C). If .CR MM_NOGET is set in .IR flags , only .I def_str must be specified. .PP The .CR pfmt() system call displays .CR "Message not found!!" under the following conditions: .RS .TP 3 \(bu No message catalog is specified in .I fmt and no catalog is defined via .IR setcat (3C). .TP \(bu .I msg_number is not positive. .TP \(bu No message could be retrieved and .I def_str is not specified. .RE .SH RETURN VALUE If successful, .CR pfmt() and .CR vpfmt() return the number of bytes written. Otherwise they return a negative value. .SH EXAMPLES Example 1 .nf .IP .C setlabel("UX:my_appl"); .C pfmt(stderr, MM_INFO,"MY_cat:1:file is writable"); .fi .PP generates the message: .IP .C UX:my_appl: INFO: file is writable .PP Example 2 .nf .IP .C setlabel(""); .C setcat("MY_cat"); .C "pfmt(stderr, MM_ERROR,"":1:%s is writable"", ""my_file"");" .fi .PP generates the message: .IP .C ERROR: my_file is writable .RE .PP Example 3 .nf .IP .C setlabel(""); .C setcat("MY_cat"); .C "pfmt(stderr, MM_NOSTD,"":1:%s is writable"", ""my_file"");" .fi .PP generates the message: .IP .C my_file is writable .RE .PP Example 4 .nf .IP .C #define MM_USER 10 .C setlabel(""); .C "addsev(MM_USER, ""MY_NOTE"");" .C "pfmt(stderr, MM_USER|MM_GET,""MY_cat:1:%s is writable"", ""my_file"");" .fi .PP generates the message: .IP .C MY_NOTE: my_file is writable .RE .SH SEE ALSO mkmsgs(1), addsev(3C), gettxt(3C), setcat(3C), setlabel(3C), setlocale(3C), printf(3S), stdarg(5). .SH STANDARDS COMPLIANCE .CR pfmt() ": SVID3" .PP .CR vpfmt() ": SVID3" .\" .\" toc@\f3pfmt(3C)\f1:\0\0\f4pfmt()\f1, \f4vpfmt()\f1@@@display message in standard format\f1 .\" toc@\f3vpfmt()\f1:\0\0\f1@@@display message in standard format, using argument list\f1@@@\f1see \f3pfmt(3C)\f1 .\" .\" index@\f4pfmt()\f1 \- display message in standard format@@@\f3pfmt(3C)\f1 .\" index@\f4vpfmt()\f1 \- display message in standard format@@@\f3pfmt(3C)\f1 .\" index@\f4pfmt()\f1 \- message, display in standard format@@@\f3pfmt(3C)\f1 .\" index@\f4pfmt()\f1 \- standard format, display message in@@@\f3pfmt(3C)\f1 .\" .\" links@pfmt.3c vpfmt.3c .\" $Header: vprintf.3s,v 78.1 96/03/15 16:47:24 ssa Exp $ .TA v .TH vprintf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vprintf(), vfprintf(), vsprintf() \- print formatted output of a varargs argument list .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "int vprintf(const char *format, va_list ap);" .PP .C "int vfprintf(FILE *stream, const char *format, va_list ap);" .PP .C "int vsprintf(char *s, const char *format, va_list ap);" .SH DESCRIPTION .CR vprintf() , .CR vfprintf() , and .C vsprintf() are the same as .CR printf() , .CR fprintf() , and .C sprintf() respectively, except that instead of being called with a variable number of arguments, they are called with an argument list as defined by .CR . .SH EXAMPLE The following demonstrates how .CR vfprintf() could be used to write an error routine: .nf .IP .ift .ft 4 .ps +1 #include #include . . . /* * error should be called using the form: * error(function_name, format, arg1, arg2...); */ /*VARARGS0*/ void error(va_alist) va_dcl { va_list args; char *fmt; va_start(args); /* print out name of function causing error */ (void)fprintf(stderr, "ERROR in %s: ", va_arg(args, char *)); fmt = va_arg(args, char *); /* print out remainder of message */ (void)vfprintf(stderr, fmt, args); va_end(args); (void)abort( ); } .ift .ft 1 .ps .fi .SH SEE ALSO printf(3S), setlocale(3C), varargs(5). .SH STANDARDS CONFORMANCE .CR vprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR vfprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR vsprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4vprintf()\f1 \- print formatted output of a varargs argument list@@@\f3vprintf(3S)\f1 .\" index@\f4vfprintf()\f1 \- print formatted output of a varargs argument list@@@\f3vprintf(3S)\f1 .\" index@\f4vsprintf()\f1 \- print formatted output of a varargs argument list@@@\f3vprintf(3S)\f1 .\" index@print formatted output of a varargs argument list@@@\f3vprintf(3S)\f1 .\" index@formatted output of a varargs argument list, print@@@\f3vprintf(3S)\f1 .\" index@output of a varargs argument list, print formatted@@@\f3vprintf(3S)\f1 .\" index@varargs argument list, print formatted output of a@@@\f3vprintf(3S)\f1 .\" index@argument list, print formatted output of a varargs@@@\f3vprintf(3S)\f1 .\" index@list, print formatted output of a varargs argument@@@\f3vprintf(3S)\f1 .\" .\" toc@\f3vprintf(3S)\f1:\0\0\f4vprintf()\f1, \f4vfprintf()\f1, \f4vsprintf()\f1@@@print formatted output of a varargs argument list .\" toc@\f4vfprintf()\f1:\0\0print formatted output of a varargs argument list@@@see \f3vprintf(3S)\f1 .\" toc@\f4vsprintf()\f1:\0\0print formatted output of a varargs argument list@@@see \f3vprintf(3S)\f1 .\" .\" links@vprintf.3s vfprintf.3s .\" links@vprintf.3s vsprintf.3s .\" $Header: vscanf.3s,v 72.3 93/01/14 14:39:08 ssa Exp $ .TA v .TH vscanf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vscanf(\|), vfscanf(\|), vsscanf(\|) \- formatted input conversion to a varargs argument list, read from stream file .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "int vscanf(const char *format, va_list ap);" .PP .C "int vfscanf(FILE *stream, const char *format, va_list ap);" .PP .C "int vsscanf(char *s, const char *format, va_list ap);" .SH DESCRIPTION .CR vscanf() , .CR vfscanf() , and .C vsscanf() are the same as .CR scanf() , .CR fscanf() , and .C sscanf() respectively, except that instead of being called with a variable number of arguments, they are called with an argument list as defined by .IR varargs (5). .SH SEE ALSO scanf(3S), setlocale(3C), varargs(5). .\" .\" index@\f4vscanf()\fP \- formatted input conversion to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@\f4vfscanf()\fP \- formatted input conversion to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@\f4vsscanf()\fP \- formatted input conversion to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@formatted input conversion to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@input conversion, formatted, to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@conversion, formatted input, to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@varargs argument, formatted input conversion to a@@@\f3vscanf(3S)\f1 .\" index@argument, varargs, formatted input conversion to a@@@\f3vscanf(3S)\f1 .\" .\" toc@\f3vscanf(3S)\f1:\0\0\f4vscanf()\fP, \f4vfscanf()\fP, \f4vsscanf()\fP@@@formatted input conversion to a varargs argument .\" toc@\f4vfscanf()\fP: formatted input conversion to a varargs argument@@@see \f3vscanf(3S)\f1 .\" toc@\f4vsscanf()\fP: formatted input conversion to a varargs argument@@@see \f3vscanf(3S)\f1 .\" links@vscanf.3s vfscanf.3s .\" links@vscanf.3s vsscanf.3s .\" .\" fileset_database@vscanf.3s PROGRAMING-MAN .\" $Header: vprintf.3s,v 78.1 96/03/15 16:47:24 ssa Exp $ .TA v .TH vprintf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vprintf(), vfprintf(), vsprintf() \- print formatted output of a varargs argument list .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "int vprintf(const char *format, va_list ap);" .PP .C "int vfprintf(FILE *stream, const char *format, va_list ap);" .PP .C "int vsprintf(char *s, const char *format, va_list ap);" .SH DESCRIPTION .CR vprintf() , .CR vfprintf() , and .C vsprintf() are the same as .CR printf() , .CR fprintf() , and .C sprintf() respectively, except that instead of being called with a variable number of arguments, they are called with an argument list as defined by .CR . .SH EXAMPLE The following demonstrates how .CR vfprintf() could be used to write an error routine: .nf .IP .ift .ft 4 .ps +1 #include #include . . . /* * error should be called using the form: * error(function_name, format, arg1, arg2...); */ /*VARARGS0*/ void error(va_alist) va_dcl { va_list args; char *fmt; va_start(args); /* print out name of function causing error */ (void)fprintf(stderr, "ERROR in %s: ", va_arg(args, char *)); fmt = va_arg(args, char *); /* print out remainder of message */ (void)vfprintf(stderr, fmt, args); va_end(args); (void)abort( ); } .ift .ft 1 .ps .fi .SH SEE ALSO printf(3S), setlocale(3C), varargs(5). .SH STANDARDS CONFORMANCE .CR vprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR vfprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .PP .CR vsprintf() ": AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C" .\" .\" index@\f4vprintf()\f1 \- print formatted output of a varargs argument list@@@\f3vprintf(3S)\f1 .\" index@\f4vfprintf()\f1 \- print formatted output of a varargs argument list@@@\f3vprintf(3S)\f1 .\" index@\f4vsprintf()\f1 \- print formatted output of a varargs argument list@@@\f3vprintf(3S)\f1 .\" index@print formatted output of a varargs argument list@@@\f3vprintf(3S)\f1 .\" index@formatted output of a varargs argument list, print@@@\f3vprintf(3S)\f1 .\" index@output of a varargs argument list, print formatted@@@\f3vprintf(3S)\f1 .\" index@varargs argument list, print formatted output of a@@@\f3vprintf(3S)\f1 .\" index@argument list, print formatted output of a varargs@@@\f3vprintf(3S)\f1 .\" index@list, print formatted output of a varargs argument@@@\f3vprintf(3S)\f1 .\" .\" toc@\f3vprintf(3S)\f1:\0\0\f4vprintf()\f1, \f4vfprintf()\f1, \f4vsprintf()\f1@@@print formatted output of a varargs argument list .\" toc@\f4vfprintf()\f1:\0\0print formatted output of a varargs argument list@@@see \f3vprintf(3S)\f1 .\" toc@\f4vsprintf()\f1:\0\0print formatted output of a varargs argument list@@@see \f3vprintf(3S)\f1 .\" .\" links@vprintf.3s vfprintf.3s .\" links@vprintf.3s vsprintf.3s .\" $Header: vscanf.3s,v 72.3 93/01/14 14:39:08 ssa Exp $ .TA v .TH vscanf 3S .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vscanf(\|), vfscanf(\|), vsscanf(\|) \- formatted input conversion to a varargs argument list, read from stream file .SH SYNOPSIS .C "#include " .br .C "#include " .PP .C "int vscanf(const char *format, va_list ap);" .PP .C "int vfscanf(FILE *stream, const char *format, va_list ap);" .PP .C "int vsscanf(char *s, const char *format, va_list ap);" .SH DESCRIPTION .CR vscanf() , .CR vfscanf() , and .C vsscanf() are the same as .CR scanf() , .CR fscanf() , and .C sscanf() respectively, except that instead of being called with a variable number of arguments, they are called with an argument list as defined by .IR varargs (5). .SH SEE ALSO scanf(3S), setlocale(3C), varargs(5). .\" .\" index@\f4vscanf()\fP \- formatted input conversion to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@\f4vfscanf()\fP \- formatted input conversion to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@\f4vsscanf()\fP \- formatted input conversion to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@formatted input conversion to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@input conversion, formatted, to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@conversion, formatted input, to a varargs argument@@@\f3vscanf(3S)\f1 .\" index@varargs argument, formatted input conversion to a@@@\f3vscanf(3S)\f1 .\" index@argument, varargs, formatted input conversion to a@@@\f3vscanf(3S)\f1 .\" .\" toc@\f3vscanf(3S)\f1:\0\0\f4vscanf()\fP, \f4vfscanf()\fP, \f4vsscanf()\fP@@@formatted input conversion to a varargs argument .\" toc@\f4vfscanf()\fP: formatted input conversion to a varargs argument@@@see \f3vscanf(3S)\f1 .\" toc@\f4vsscanf()\fP: formatted input conversion to a varargs argument@@@see \f3vscanf(3S)\f1 .\" links@vscanf.3s vfscanf.3s .\" links@vscanf.3s vsscanf.3s .\" .\" fileset_database@vscanf.3s PROGRAMING-MAN .\" $Header: vw_printw.3x,v 76.2 95/08/01 15:22:21 ssa Exp $ .TA v .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH vw_printw 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vw_printw \(em print formatted output in window (\f3TO BE WITHDRAWN\f1) .SH SYNOPSIS .C "#include " .C "#include " .P .C "int vw_printw(WINDOW *\f2win\f4, char *\f2fmt\f4, va_list \f2varglist\f4);" .SH DESCRIPTION The .Fn vw_printw function achieves the same effect as .Fn wprintw using a variable argument list. The third argument is a \f3va_list\f1, as defined in .Hd stdarg.h . .SH "RETURN VALUE" Upon successful completion, .Fn vw_printw returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" mvprintw(), fprintf() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" .\" toc@\f3vw_printw(3x)\f1:\0\0\f4vw_printw()\f1@@@print formatted output in a window (\f3TO BE WITHDRAWN\f1) .\" .\" index@\f4vw_printw()\f1 \- print formatted output in a window@@@\f3vw_printw(3x)\f1 .\" index@\f1print formatted output in a window@@@\f3vw_printw(3x)\f1 .\" index@\f1window, print formatted output@@@\f3vw_printw(3x)\f1 .\" index@\f1formatted output, print in a window@@@\f3vw_printw(3x)\f1 .\" .\" fileset_database@vw_printw.3x CURS-ENG-A-MAN .\" .\" $Header: vw_scanw.3x,v 76.2 95/08/01 15:23:03 ssa Exp $ .TA v .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH vw_scanw 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vw_scanw \(em convert formatted input from a window (\f3TO BE WITHDRAWN\f1) .SH SYNOPSIS .C "#include " .C "#include " .P .C "int vw_scanw(WINDOW *\f2win\f4, char *\f2fmt\f4, va_list \f2varglist\f4);" .SH DESCRIPTION The .Fn vw_scanw function achieves the same effect as .Fn wscanw using a variable argument list. The third argument is a \f3va_list\f1, as defined in .Hd stdarg.h . .SH "RETURN VALUE" Upon successful completion, .Fn vw_scanw returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" fscanf() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), mvscanw(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3vw_scanw(3x)\f1:\0\0\f4vw_scanw()\f1@@@convert formatted input from a window (\f3TO BE WITHDRAWN\f1) .\" .\" index@\f4vw_scanw()\f1 \- convert formatted input from a window@@@\f3vwprintw(3x)\f1 .\" index@\f1convert formatted input from a window@@@\f3vw_scanw(3x)\f1 .\" index@\f1window, convert formatted input@@@\f3vw_scanw(3x)\f1 .\" index@\f1formatted input, convert from a window@@@\f3vw_scanw(3x)\f1 .\" .\" fileset_database@vw_scanw.3x CURS-ENG-A-MAN .\" .\" $Header: vwprintw.3x,v 76.2 95/08/01 15:23:57 ssa Exp $ .TA v .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH vwprintw 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vwprintw \(em print formatted output in window .SH SYNOPSIS .C "#include " .C "#include " .P .C "int vwprintw(WINDOW *\f2win\f4, char *\f2fmt\f4, va_list \f2varglist\f4);" .SH DESCRIPTION The .Fn vwprintw function achieves the same effect as .Fn wprintw using a variable argument list. The third argument is a \f3va_list\f1, as defined in .Hd stdarg.h . .SH "RETURN VALUE" Upon successful completion, .Fn vwprintw returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn vwprintw function is deprecated because it relies on deprecated functions in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification . The .Fn vw_printw function is preferred. .SH "SEE ALSO" mvprintw(), fprintf() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), vw_printw(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3vwprintw(3x)\f1:\0\0\f4vwprintw()\f1@@@print formatted output in a window .\" .\" index@\f4vwprintw()\f1 \- print formatted output in a window@@@\f3vwprintw(3x)\f1 .\" index@\f1print formatted output in a window@@@\f3vwprintw(3x)\f1 .\" index@\f1window, print formatted output@@@\f3vwprintw(3x)\f1 .\" index@\f1formatted output, print in a window@@@\f3vwprintw(3x)\f1 .\" .\" fileset_database@vwprintw.3x CURS-ENG-A-MAN .\" .\" $Header: vwscanw.3x,v 76.2 95/08/01 15:24:47 ssa Exp $ .TA v .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH vwscanw 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME vwscanw \(em convert formatted input from a window .SH SYNOPSIS .C "#include " .C "#include " .P .C "int vwscanw(WINDOW *\f2win\f4, char *\f2fmt\f4, va_list \f2varglist\f4);" .SH DESCRIPTION The .Fn vwscanw function achieves the same effect as .Fn wscanw using a variable argument list. The third argument is a \f3va_list\f1, as defined in .Hd stdarg.h . .SH "RETURN VALUE" Upon successful completion, .Fn vwscanw returns OK. Otherwise, it returns ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn vwscanw function is deprecated because it relies on deprecated functions in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification . The .Fn vw_scanw function is preferred. .SH "SEE ALSO" fscanf() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), mvscanw(), vw_scanw(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3vwscanw(3x)\f1:\0\0\f4vwscanw()\f1@@@convert formatted input from a window .\" .\" index@\f4vwscanw()\f1 \- convert formatted input from a window@@@\f3vwprintw(3x)\f1 .\" index@\f1convert formatted input from a window@@@\f3vwscanw(3x)\f1 .\" index@\f1window, convert formatted input@@@\f3vwscanw(3x)\f1 .\" index@\f1formatted input, convert from a window@@@\f3vwscanw(3x)\f1 .\" .\" fileset_database@vwscanw.3x CURS-ENG-A-MAN .\" .\" $Header: add_wch.3x,v 76.2 95/07/31 11:12:51 ssa Exp $ .TA a .TH add_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME add_wch, mvadd_wch, mvwadd_wch, wadd_wch \(em add a complex character and rendition to a window .SH SYNOPSIS .C "#include " .P .C "int add_wch(cchar_t *const \f2wch\fP);" .P .C "int wadd_wch(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "int mvadd_wch(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .P .C "int mvwadd_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .SH DESCRIPTION These functions add information to the current or specified window at the current or specified position, and then advance the cursor. These functions perform wrapping. These functions perform special-character processing. .RS .TP 3 .C \(bu If \f2wch\f1 refers to a spacing character, then any previous character at that location is removed, a new character specified by \f2wch\f1 is placed at that location with rendition specified by \f2wch\fP; then the cursor advances to the next spacing character on the screen. .TP .C \(bu If \f2wch\f1 refers to a non-spacing character, all previous characters at that location are preserved, the non-spacing characters of \f2wch\f1 are added to the spacing complex character, and the rendition specified by \f2wch\f1 is ignored. .RE .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Rendition of Characters Placed into a Window\f1 in curses_intro, addch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4add_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f4mvadd_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f4mvwadd_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f4wadd_wch\f1 \- add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f1add a complex character and rendition to a window@@@\f3add_wch(3X)\f1 .\" index@\f1character and rendition to a window, add a complex@@@\f3add_wch(3X)\f1 .\" index@\f1complex character and rendition, add to a window@@@\f3add_wch(3X)\f1 .\" .\" toc@\f3add_wch(3X)\f1:\0\0\f4add_wch()\f1, \f4mvadd_wch()\f1, \f4mvwadd_wch()\f1, \n\f4wadd_ch()\f1@@@add a complex character and rendition to a window .\" toc@\f4mvadd_wch()\f1: add a complex character and rendition to a window@@@see \f3add_wch(3X)\f1 .\" toc@\f4mvwadd_wch()\f1: add a complex character and rendition to a window@@@see \f3add_wch(3X)\f1 .\" toc@\f4wadd_wch()\f1: add a complex character and rendition to a window@@@see \f3add_wch(3X)\f1 .\" .\" links@add_wch.3x mvadd_wch.3x .\" links@add_wch.3x mvwadd_wch.3x .\" links@add_wch.3x wadd_wch.3x .\" .\" fileset_database@add_wch.3x CURS-ENG-A-MAN .\" $Header: add_wchnstr.3x,v 76.2 95/07/31 11:15:08 ssa Exp $ .TA a .TH add_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME add_wchnstr, add_wchstr, mvadd_wchnstr, mvadd_wchstr, mvwadd_wchnstr, mvwadd_wchstr, wadd_wchnstr, wadd_wchstr \(em add an array of complex characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int add_wchnstr(cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int add_wchstr(cchar_t *const \f2wchstr\fP);" .P .C "int wadd_wchnstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int wadd_wchstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvadd_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int mvadd_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvwadd_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP," .br .C " int \f2n\fP);" .P .C "int mvwadd_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .SH DESCRIPTION These functions write the array of \f3cchar_t\f1 specified by \f2wchstr\f1 into the current or specified window starting at the current or specified cursor position. .P These functions do not advance the cursor. The results are unspecified if \f2wchstr\f1 contains any special characters. .P The functions end successfully on encountering a null \f3cchar_t\f1. The functions also end successfully when they fill the current line. If a character cannot completely fit at the end of the current line, those columns are filled with the background character and rendition. .P The .CR add_wchnstr() , .CR mvadd_wchnstr() , .CR mvwadd_wchnstr() and .CR wadd_wchnstr() functions end successfully after writing \f2n\f1 \f3cchar_t\fPs (or the entire array of \f3cchar_t\fPs, if \f2n\f1 is \(mi1). .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3add_wchnstr(3X)\f1:\0\0\f4add_wchstr()\f1, \f4mvadd_wchnstr()\f1, \f4mvadd_wchstr()\f1, \f4mvwadd_wchnstr()\f1,\n\f4mvwadd_wchstr\f1, \f4wadd_wchnstr\f1, \n\f4wadd_wchstr\f1@@@add an array of complex characters and renditions to a window .\" toc@\f4add_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" .\" index@\f4add_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4add_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1an array of complex characters and renditions to a window, add@@@\f3add_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, add an array of, to a window@@@\f3add_wchnstr(3X)\f1 .\" .\" links@add_wchnstr.3x add_wchstr.3x .\" links@add_wchnstr.3x mvadd_wchnstr.3x .\" links@add_wchnstr.3x mvadd_wchstr.3x .\" links@add_wchnstr.3x mvwadd_wchnstr.3x .\" links@add_wchnstr.3x mvwadd_wchstr.3x .\" links@add_wchnstr.3x wadd_wchnstr.3x .\" links@add_wchnstr.3x wadd_wchstr.3x .\" .\" fileset_database@add_wchnstr.3x CURS-ENG-A-MAN .\" $Header: add_wchnstr.3x,v 76.2 95/07/31 11:15:08 ssa Exp $ .TA a .TH add_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME add_wchnstr, add_wchstr, mvadd_wchnstr, mvadd_wchstr, mvwadd_wchnstr, mvwadd_wchstr, wadd_wchnstr, wadd_wchstr \(em add an array of complex characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int add_wchnstr(cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int add_wchstr(cchar_t *const \f2wchstr\fP);" .P .C "int wadd_wchnstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int wadd_wchstr(WINDOW *\f2win\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvadd_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP, int \f2n\fP);" .P .C "int mvadd_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .P .C "int mvwadd_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP," .br .C " int \f2n\fP);" .P .C "int mvwadd_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wchstr\fP);" .SH DESCRIPTION These functions write the array of \f3cchar_t\f1 specified by \f2wchstr\f1 into the current or specified window starting at the current or specified cursor position. .P These functions do not advance the cursor. The results are unspecified if \f2wchstr\f1 contains any special characters. .P The functions end successfully on encountering a null \f3cchar_t\f1. The functions also end successfully when they fill the current line. If a character cannot completely fit at the end of the current line, those columns are filled with the background character and rendition. .P The .CR add_wchnstr() , .CR mvadd_wchnstr() , .CR mvwadd_wchnstr() and .CR wadd_wchnstr() functions end successfully after writing \f2n\f1 \f3cchar_t\fPs (or the entire array of \f3cchar_t\fPs, if \f2n\f1 is \(mi1). .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3add_wchnstr(3X)\f1:\0\0\f4add_wchstr()\f1, \f4mvadd_wchnstr()\f1, \f4mvadd_wchstr()\f1, \f4mvwadd_wchnstr()\f1,\n\f4mvwadd_wchstr\f1, \f4wadd_wchnstr\f1, \n\f4wadd_wchstr\f1@@@add an array of complex characters and renditions to a window .\" toc@\f4add_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4mvwadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchnstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" toc@\f4wadd_wchstr()\f1: add an array of complex characters and renditions to a window@@@see \f3add_wchnstr(3X)\f1 .\" .\" index@\f4add_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4add_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4mvwadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchnstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f4wadd_wchstr()\f1 \- add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1add an array of complex characters and renditions to a window@@@\f3add_wchnstr(3X)\f1 .\" index@\f1an array of complex characters and renditions to a window, add@@@\f3add_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, add an array of, to a window@@@\f3add_wchnstr(3X)\f1 .\" .\" links@add_wchnstr.3x add_wchstr.3x .\" links@add_wchnstr.3x mvadd_wchnstr.3x .\" links@add_wchnstr.3x mvadd_wchstr.3x .\" links@add_wchnstr.3x mvwadd_wchnstr.3x .\" links@add_wchnstr.3x mvwadd_wchstr.3x .\" links@add_wchnstr.3x wadd_wchnstr.3x .\" links@add_wchnstr.3x wadd_wchstr.3x .\" .\" fileset_database@add_wchnstr.3x CURS-ENG-A-MAN .\" $Header: addch.3x,v 76.2 95/07/28 16:16:36 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addch, mvaddch, mvwaddch, waddch \(em add a single-byte character and rendition to a window and advance the cursor .SH SYNOPSIS .C "#include " .P .C "int addch(const chtype \f2ch\fP);" .P .C "int mvaddch(int \f2y\fP, int \f2x\fP, const chtype \f2ch\fP);" .P .C "int mvwaddch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, const chtype \f2ch\fP);" .P .C "int waddch(WINDOW *\f2win\fP, const chtype \f2ch\fP);" .SH DESCRIPTION The .CR addch() , .CR mvaddch() , .CR mvwaddch() and .CR waddch() functions place \f2ch\f1 into the current or specified window at the current or specified position, and then advance the window's cursor position. These functions perform wrapping. These functions perform special-character processing. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" \f3Rendition of Characters Placed into a Window\f1 in curses_intro, add_wch(), attroff(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The entry is rewritten for clarity. Also the type of argument \f2ch\f1 is changed from \f3chtype\f1 to \f3const chtype\f1. .\" .\" toc@\f3addch(3X)\f1:\0\0\f4addch()\f1, \f4mvaddch()\f1, \f4mvwaddch()\f1, \f4waddch\f1\n@@@add a single-byte character and rendition to a window and advance the cursor .\" toc@\f4mvaddch()\f1: add a single-byte character and rendition to a window and advance the cursor@@@see \f3addch(3X)\f1 .\" toc@\f4mvwaddch()\f1: add a single-byte character and rendition to a window and advance the cursor@@@see \f3addch(3X)\f1 .\" toc@\f4waddch()\f1: add a single-byte character and rendition to a window and advance the cursor@@@see \f3addch(3X)\f1 .\" .\" index@\f4addch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f4mvaddch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f4mvwaddch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f4waddch()\f1 \- add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f1add a single-byte character and rendition to a window and advance the cursor@@@\f3addch(3X)\f1 .\" index@\f1single-byte character and rendition, add, to a window and advance the cursor@@@\f3addch(3X)\f1 .\" .\" links@addch.3x mvaddch.3x .\" links@addch.3x mvwaddch.3x .\" links@addch.3x waddch.3x .\" .\" fileset_database@addch.3x CURS-ENG-A-MAN .\" $Header: addchnstr.3x,v 76.2 95/07/31 11:17:15 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addchnstr, mvaddchnstr, mvwaddchnstr, waddchnstr \(em add length limited string of single-byte characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int addchnstr(chtype *const \f2chstr\fP, int \f2n\fP);" .P .C "int mvaddchnstr(int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP, int \f2n\fP);" .P .C "int mvwaddchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP," .br .C " int \f2n\fP);" .P .C "int waddchnstr(WINDOW *\f2win\fP, chtype *const \f2chstr\fP, int \f2n\fP);" .SH DESCRIPTION These functions overlay the contents of the current or specified window, starting at the current or specified position, with the contents of the array pointed to by .I chstr until a null .B chtype is encountered in the array pointed to by .I chstr . .P These functions do not change the cursor position. These functions do not perform special-character processing. These functions do not perform wrapping. .P These functions copy at most \f2n\f1 items, but no more than will fit on the line. If \f2n\f1\ is \(mi1 then the whole string is copied, to the maximum number that fit on the line. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" addch(), add_wch(), add_wchstr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addchnstr(3X)\f1:\0\0\f4mvaddchnstr()\f1, \f4mvwaddchnstr()\f1, \f4waddchnstr()\f1\n@@@add length limited string of single-byte characters and renditions to a window .\" toc@\f4mvaddchnstr()\f1: add length limited string of single-byte characters and renditions to a window\n@@@see \f3addchnstr(3X)\f1 .\" toc@\f4mvwaddchnstr()\f1: add length limited string of single-byte characters and renditions to a window\n@@@see \f3addchnstr(3X)\f1 .\" toc@\f4waddchnstr()\f1: add length limited string of single-byte characters and renditions to a window\n@@@see \f3addchnstr(3X)\f1 .\" .\" index@\f4addchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window@@@\f3addchnstr(3X)\f1 .\" index@\f4mvaddchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window\n@@@\f3addchnstr(3X)\f1 .\" index@\f4mvwaddchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window\n@@@\f3addchnstr(3X)\f1 .\" index@\f4waddchnstr()\f1 \- add length limited string of single-byte characters and renditions to a window@@@\f3addchnstr(3X)\f1 .\" index@\f1add length limited string of single-byte characters and renditions to a window@@@\f3addchnstr(3X)\f1 .\" index@\f1length limited string of single-byte characters and renditions to a window, add@@@\f3addchnstr(3X)\f1 .\" index@\f1single-byte characters and renditions to a window, add length limited string of@@@\f3addchnstr(3X)\f1 .\" .\" links@addchnstr.3x mvaddchnstr.3x .\" links@addchnstr.3x mvwaddchnstr.3x .\" links@addchnstr.3x waddchnstr.3x .\" .\" fileset_database@addchnstr.3x CURS-ENG-A-MAN .\" $Header: addchstr.3x,v 76.2 95/07/31 11:19:11 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addchstr 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addchstr, mvaddchstr, mvwaddchstr, waddchstr \(em add string of single-byte characters and renditions to a window .SH SYNOPSIS .C "#include " .P .C "int addchstr(chtype *const \f2chstr\fP);" .P .C "int mvaddchstr(int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP);" .P .C "int mvwaddchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *const \f2chstr\fP);" .P .C "int waddchstr(WINDOW *\f2win\fP, chtype *const \f2chstr\fP);" .SH DESCRIPTION These functions overlay the contents of the current or specified window, starting at the current or specified position, with the contents of the array pointed to by .I chstr until a null .CR chtype is encountered in the array pointed to by .IR chstr . .P These functions do not change the cursor position. These functions do not perform special-character processing. These functions do not perform wrapping. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" addch(), addchnstr(), add_wch(), add_wchstr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addchstr(3X)\f1:\0\0\f4mvaddchstr()\f1, \f4mvwaddchstr()\f1, \f4waddchstr()\f1\n@@@add string of single-byte characters and renditions to a window .\" toc@\f4mvaddchstr()\f1: add string of single-byte characters and renditions to a window@@@see \f3addchstr(3X)\f1 .\" toc@\f4mvwaddchstr()\f1: add string of single-byte characters and renditions to a window@@@see \f3addchstr(3X)\f1 .\" toc@\f4waddchstr()\f1: add string of single-byte characters and renditions to a window@@@see \f3addchstr(3X)\f1 .\" .\" index@\f4addchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f4mvaddchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f4mvwaddchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f4waddchstr()\f1 \- add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f1add string of single-byte characters and renditions to a window@@@\f3addchstr(3X)\f1 .\" index@\f1string of single-byte characters and renditions to a window, add@@@\f3addchstr(3X)\f1 .\" index@\f1single-byte characters and renditions to a window, add string of@@@\f3addchstr(3X)\f1 .\" .\" links@addchstr.3x mvaddchstr.3x .\" links@addchstr.3x mvwaddchstr.3x .\" links@addchstr.3x waddchstr.3x .\" .\" fileset_database@addchstr.3x CURS-ENG-A-MAN .\" $Header: addnstr.3x,v 76.2 95/07/31 11:20:19 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnstr, addstr, mvaddnstr, mvaddstr, mvwaddnstr, mvwaddstr waddnstr, waddstr \(em add a string of multi-byte characters without rendition to a window and advance cursor .SH SYNOPSIS .C "#include " .P .C "int addnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int addstr(char *const \f2str\fP);" .P .C "int mvaddnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvaddstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwaddnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwaddstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int waddnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int waddstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions write the characters of the string \f2str\f1 on the current or specified window starting at the current or specified position using the background rendition. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions are similar to calling .CR mbstowcs() on \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .P The .CR addnstr() , .CR mvaddnstr() , .CR mvwaddnstr() and .CR waddnstr() functions use at most \f2n\f1 bytes from \f2str\f1. These functions add the entire string when \f2n\f1 is \(mi1. These functions are similar to calling .CR mbstowcs() on the first \f2n\f1 bytes of \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" addnwstr(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .P In X/Open Curses, Issue 3, the .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions were described in the .CR addstr() entry. In X/Open Curses, Issue 4, the type of the \f2str\f1 argument defined for these functions is changed from \f3char\ *\f1 to \f3char\ *const\fP, and the .BR DESCRIPTION is changed to indicate that the functions will handle multi-byte sequences correctly. .\" toc@\f3addnstr(3X)\f1:\0\0\f4addstr()\f1, \f4mvaddnstr()\f1, \f4mvaddstr()\f1, \f4mvwaddnstr()\f1, \f4mvwaddstr()\f1, \f4waddnstr()\f1, \n\f4waddstr()\f1@@@add a string of multi-byte characters without rendition to a window and advance cursor .\" toc@\f4addstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" .\" index@\f4addnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4addstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1add a string of multi-byte characters without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1multi-byte characters, add a string of, without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" .\" links@addnstr.3x addstr.3x .\" links@addnstr.3x mvaddnstr.3x .\" links@addnstr.3x mvaddstr.3x .\" links@addnstr.3x mvwaddstr.3x .\" links@addnstr.3x mvwaddnstr.3x .\" links@addnstr.3x waddstr.3x .\" links@addnstr.3x waddnstr.3x .\" .\" fileset_database@addnstr.3x CURS-ENG-A-MAN .\" $Header: addnwstr.3x,v 76.2 95/07/28 16:19:15 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnwstr, addwstr, mvaddnwstr, mvaddwstr, mvwaddnwstr, mvwaddwstr, waddnwstr, waddwstr \(em add a wide-character string to a window and advance the cursor .SH SYNOPSIS .C "#include " .P .C "int addnwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int addwstr(wchar_t *const \f2wstr\fP);" .P .C "int mvaddnwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvaddwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwaddnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwaddwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int waddnwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int waddwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions write the characters of the wide character string \f2wstr\f1 on the current or specified window at that window's current or specified cursor position. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The effect is similar to building a \f3cchar_t\f1 from the \f3wchar_t\f1 and the background rendition and calling .CR wadd_wch() once for each \f3wchar_t\f1 character in the string. The cursor movement specified by the .I mv functions occurs only once at the start of the operation. .P The .CR addnwstr() , .CR mvaddnwstr() , .CR mvwaddnwstr() and .CR waddnwstr() functions write at most \f2n\f1 wide characters. If \f2n\f1 is \(mi1, then the entire string will be added. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" add_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addnwstr(3X)\f1:\0\0\f4addnwstr()\f1, \f4addwstr()\f1, \f4mvaddnwstr()\f1, \f4mvaddwstr()\f1, \f4mvwaddnwstr()\f1, \f4mvwaddwstr()\f1, \n\f4waddnwstr()\f1, \f4waddwstr()\f1@@@add a wide-character string to a window and advance the cursor .\" toc@\f4addwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" .\" index@\f4addnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4addwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f1add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" .\" links@addnwstr.3x addwstr.3x .\" links@addnwstr.3x mvaddnwstr.3x .\" links@addnwstr.3x mvaddwstr.3x .\" links@addnwstr.3x mvwaddnwstr.3x .\" links@addnwstr.3x mvwaddwstr.3x .\" links@addnwstr.3x waddnwstr.3x .\" links@addnwstr.3x waddwstr.3x .\" .\" fileset_database@addnwstr.3x CURS-ENG-A-MAN .\" $Header: addnstr.3x,v 76.2 95/07/31 11:20:19 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnstr, addstr, mvaddnstr, mvaddstr, mvwaddnstr, mvwaddstr waddnstr, waddstr \(em add a string of multi-byte characters without rendition to a window and advance cursor .SH SYNOPSIS .C "#include " .P .C "int addnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int addstr(char *const \f2str\fP);" .P .C "int mvaddnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvaddstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwaddnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwaddstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int waddnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int waddstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions write the characters of the string \f2str\f1 on the current or specified window starting at the current or specified position using the background rendition. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions are similar to calling .CR mbstowcs() on \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .P The .CR addnstr() , .CR mvaddnstr() , .CR mvwaddnstr() and .CR waddnstr() functions use at most \f2n\f1 bytes from \f2str\f1. These functions add the entire string when \f2n\f1 is \(mi1. These functions are similar to calling .CR mbstowcs() on the first \f2n\f1 bytes of \f2str\fP, and then calling .CR addwstr() , .CR mvaddwstr() , .CR mvwaddwstr() and .CR waddwstr() , respectively. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" addnwstr(), mbstowcs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .P In X/Open Curses, Issue 3, the .CR addstr() , .CR mvaddstr() , .CR mvwaddstr() and .CR waddstr() functions were described in the .CR addstr() entry. In X/Open Curses, Issue 4, the type of the \f2str\f1 argument defined for these functions is changed from \f3char\ *\f1 to \f3char\ *const\fP, and the .BR DESCRIPTION is changed to indicate that the functions will handle multi-byte sequences correctly. .\" toc@\f3addnstr(3X)\f1:\0\0\f4addstr()\f1, \f4mvaddnstr()\f1, \f4mvaddstr()\f1, \f4mvwaddnstr()\f1, \f4mvwaddstr()\f1, \f4waddnstr()\f1, \n\f4waddstr()\f1@@@add a string of multi-byte characters without rendition to a window and advance cursor .\" toc@\f4addstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4mvwaddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddnstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" toc@\f4waddstr()\f1: add a string of multi-byte characters without rendition to a window and advance \ncursor@@@see \f3addnstr(3X)\f1 .\" .\" index@\f4addnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4addstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4mvwaddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddnstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f4waddstr()\f1 \- add a string of multi-byte characters without rendition to a window and \nadvance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1add a string of multi-byte characters without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" index@\f1multi-byte characters, add a string of, without rendition to a window and advance cursor@@@\f3addnstr(3X)\f1 .\" .\" links@addnstr.3x addstr.3x .\" links@addnstr.3x mvaddnstr.3x .\" links@addnstr.3x mvaddstr.3x .\" links@addnstr.3x mvwaddstr.3x .\" links@addnstr.3x mvwaddnstr.3x .\" links@addnstr.3x waddstr.3x .\" links@addnstr.3x waddnstr.3x .\" .\" fileset_database@addnstr.3x CURS-ENG-A-MAN .\" $Header: addnwstr.3x,v 76.2 95/07/28 16:19:15 ssa Exp $ .TA a .de Fn .IR \\$1 () .. .de Hd .BR <\\$1> .. .TH addnwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME addnwstr, addwstr, mvaddnwstr, mvaddwstr, mvwaddnwstr, mvwaddwstr, waddnwstr, waddwstr \(em add a wide-character string to a window and advance the cursor .SH SYNOPSIS .C "#include " .P .C "int addnwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int addwstr(wchar_t *const \f2wstr\fP);" .P .C "int mvaddnwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvaddwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwaddnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwaddwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int waddnwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int waddwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions write the characters of the wide character string \f2wstr\f1 on the current or specified window at that window's current or specified cursor position. .P These functions advance the cursor position. These functions perform special character processing. These functions perform wrapping. .P The effect is similar to building a \f3cchar_t\f1 from the \f3wchar_t\f1 and the background rendition and calling .CR wadd_wch() once for each \f3wchar_t\f1 character in the string. The cursor movement specified by the .I mv functions occurs only once at the start of the operation. .P The .CR addnwstr() , .CR mvaddnwstr() , .CR mvwaddnwstr() and .CR waddnwstr() functions write at most \f2n\f1 wide characters. If \f2n\f1 is \(mi1, then the entire string will be added. .SH "RETURN VALUE" Upon successful completion, these functions return .CR OK . Otherwise, they return .CR ERR . .SH ERRORS No errors are defined. .SH "SEE ALSO" add_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3addnwstr(3X)\f1:\0\0\f4addnwstr()\f1, \f4addwstr()\f1, \f4mvaddnwstr()\f1, \f4mvaddwstr()\f1, \f4mvwaddnwstr()\f1, \f4mvwaddwstr()\f1, \n\f4waddnwstr()\f1, \f4waddwstr()\f1@@@add a wide-character string to a window and advance the cursor .\" toc@\f4addwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4mvwaddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddnwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" toc@\f4waddwstr()\f1: add a wide-character string to a window and advance the cursor@@@see \f3addnwstr(3X)\f1 .\" .\" index@\f4addnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4addwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4mvwaddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddnwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f4waddwstr()\f1 \- add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" index@\f1add a wide-character string to a window and advance the cursor@@@\f3addnwstr(3X)\f1 .\" .\" links@addnwstr.3x addwstr.3x .\" links@addnwstr.3x mvaddnwstr.3x .\" links@addnwstr.3x mvaddwstr.3x .\" links@addnwstr.3x mvwaddnwstr.3x .\" links@addnwstr.3x mvwaddwstr.3x .\" links@addnwstr.3x waddnwstr.3x .\" links@addnwstr.3x waddwstr.3x .\" .\" fileset_database@addnwstr.3x CURS-ENG-A-MAN .\" $Header: attr_get.3x,v 76.2 95/07/31 11:21:27 ssa Exp $ .TA a .de Fn .C \\$1() .. .de Hd .BR <\\$1> .. .TH attr_get 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attr_get, attr_off, attr_on, attr_set, color_set, wattr_get, wattr_off, wattr_on, wattr_set, wcolor_set \(em window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attr_get(attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int attr_off(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_on(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_set(attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int color_set(short \f2color\fP);" .P .C "int wattr_get(WINDOW *\f2win\fP, attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wattr_off(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_on(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_set(WINDOW *\f2win\fP, attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wcolor_set(WINDOW *\f2win\fP, short \f2color\fP);" .SH DESCRIPTION These functions manipulate the attributes and color of the window rendition of the current or specified window. .P The .Fn attr_get and .Fn wattr_get functions obtain the current rendition of a window. .P The .Fn attr_off and .Fn wattr_off functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_on and .Fn wattr_on functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_set and .Fn wattr_set functions set the window rendition of the current or specified window to \f2attrs\f1 and \f2color\f1. .P The .Fn color_set and .Fn wcolor_set functions set the window color of the current or specified window to color. .P The \f2opts\f1 argument is reswerved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" These functions always return OK. .SH ERRORS No errors are defined. .SH "SEE ALSO" attroff(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3attr_get(3X)\f1:\0\0\f4attr_off()\f1, \f4attr_on()\f1, \f4attr_set()\f1, \f4color_set()\f1, \f4wattr_get()\f1, \f4wattr_off()\f1, \n\f4wattr_on()\f1, \f4wattr_set()\f1, \f4wcolor_set()\f1@@@window attribute control functions .\" toc@\f4attr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_get()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4color_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wcolor_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" .\" index@\f4attr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4color_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wcolor_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1attribute, for window, control functions@@@\f3attr_get(3X)\f1 .\" index@\f1control functions for window attribute@@@\f3attr_get(3X)\f1 .\" .\" links@attr_get.3x attr_set.3x .\" links@attr_get.3x attr_off.3x .\" links@attr_get.3x attr_on.3x .\" links@attr_get.3x wattr_set.3x .\" links@attr_get.3x wattr_get.3x .\" links@attr_get.3x wattr_off.3x .\" links@attr_get.3x wattr_on.3x .\" links@attr_get.3x color_set.3x .\" links@attr_get.3x wcolor_set.3x .\" .\" fileset_database@attr_get.3x CURS-ENG-A-MAN .\" $Header: attr_get.3x,v 76.2 95/07/31 11:21:27 ssa Exp $ .TA a .de Fn .C \\$1() .. .de Hd .BR <\\$1> .. .TH attr_get 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attr_get, attr_off, attr_on, attr_set, color_set, wattr_get, wattr_off, wattr_on, wattr_set, wcolor_set \(em window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attr_get(attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int attr_off(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_on(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_set(attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int color_set(short \f2color\fP);" .P .C "int wattr_get(WINDOW *\f2win\fP, attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wattr_off(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_on(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_set(WINDOW *\f2win\fP, attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wcolor_set(WINDOW *\f2win\fP, short \f2color\fP);" .SH DESCRIPTION These functions manipulate the attributes and color of the window rendition of the current or specified window. .P The .Fn attr_get and .Fn wattr_get functions obtain the current rendition of a window. .P The .Fn attr_off and .Fn wattr_off functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_on and .Fn wattr_on functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_set and .Fn wattr_set functions set the window rendition of the current or specified window to \f2attrs\f1 and \f2color\f1. .P The .Fn color_set and .Fn wcolor_set functions set the window color of the current or specified window to color. .P The \f2opts\f1 argument is reswerved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" These functions always return OK. .SH ERRORS No errors are defined. .SH "SEE ALSO" attroff(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3attr_get(3X)\f1:\0\0\f4attr_off()\f1, \f4attr_on()\f1, \f4attr_set()\f1, \f4color_set()\f1, \f4wattr_get()\f1, \f4wattr_off()\f1, \n\f4wattr_on()\f1, \f4wattr_set()\f1, \f4wcolor_set()\f1@@@window attribute control functions .\" toc@\f4attr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_get()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4color_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wcolor_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" .\" index@\f4attr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4color_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wcolor_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1attribute, for window, control functions@@@\f3attr_get(3X)\f1 .\" index@\f1control functions for window attribute@@@\f3attr_get(3X)\f1 .\" .\" links@attr_get.3x attr_set.3x .\" links@attr_get.3x attr_off.3x .\" links@attr_get.3x attr_on.3x .\" links@attr_get.3x wattr_set.3x .\" links@attr_get.3x wattr_get.3x .\" links@attr_get.3x wattr_off.3x .\" links@attr_get.3x wattr_on.3x .\" links@attr_get.3x color_set.3x .\" links@attr_get.3x wcolor_set.3x .\" .\" fileset_database@attr_get.3x CURS-ENG-A-MAN .\" $Header: attr_get.3x,v 76.2 95/07/31 11:21:27 ssa Exp $ .TA a .de Fn .C \\$1() .. .de Hd .BR <\\$1> .. .TH attr_get 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attr_get, attr_off, attr_on, attr_set, color_set, wattr_get, wattr_off, wattr_on, wattr_set, wcolor_set \(em window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attr_get(attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int attr_off(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_on(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_set(attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int color_set(short \f2color\fP);" .P .C "int wattr_get(WINDOW *\f2win\fP, attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wattr_off(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_on(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_set(WINDOW *\f2win\fP, attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wcolor_set(WINDOW *\f2win\fP, short \f2color\fP);" .SH DESCRIPTION These functions manipulate the attributes and color of the window rendition of the current or specified window. .P The .Fn attr_get and .Fn wattr_get functions obtain the current rendition of a window. .P The .Fn attr_off and .Fn wattr_off functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_on and .Fn wattr_on functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_set and .Fn wattr_set functions set the window rendition of the current or specified window to \f2attrs\f1 and \f2color\f1. .P The .Fn color_set and .Fn wcolor_set functions set the window color of the current or specified window to color. .P The \f2opts\f1 argument is reswerved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" These functions always return OK. .SH ERRORS No errors are defined. .SH "SEE ALSO" attroff(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3attr_get(3X)\f1:\0\0\f4attr_off()\f1, \f4attr_on()\f1, \f4attr_set()\f1, \f4color_set()\f1, \f4wattr_get()\f1, \f4wattr_off()\f1, \n\f4wattr_on()\f1, \f4wattr_set()\f1, \f4wcolor_set()\f1@@@window attribute control functions .\" toc@\f4attr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_get()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4color_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wcolor_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" .\" index@\f4attr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4color_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wcolor_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1attribute, for window, control functions@@@\f3attr_get(3X)\f1 .\" index@\f1control functions for window attribute@@@\f3attr_get(3X)\f1 .\" .\" links@attr_get.3x attr_set.3x .\" links@attr_get.3x attr_off.3x .\" links@attr_get.3x attr_on.3x .\" links@attr_get.3x wattr_set.3x .\" links@attr_get.3x wattr_get.3x .\" links@attr_get.3x wattr_off.3x .\" links@attr_get.3x wattr_on.3x .\" links@attr_get.3x color_set.3x .\" links@attr_get.3x wcolor_set.3x .\" .\" fileset_database@attr_get.3x CURS-ENG-A-MAN .\" $Header: attr_get.3x,v 76.2 95/07/31 11:21:27 ssa Exp $ .TA a .de Fn .C \\$1() .. .de Hd .BR <\\$1> .. .TH attr_get 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attr_get, attr_off, attr_on, attr_set, color_set, wattr_get, wattr_off, wattr_on, wattr_set, wcolor_set \(em window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attr_get(attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int attr_off(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_on(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_set(attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int color_set(short \f2color\fP);" .P .C "int wattr_get(WINDOW *\f2win\fP, attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wattr_off(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_on(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_set(WINDOW *\f2win\fP, attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wcolor_set(WINDOW *\f2win\fP, short \f2color\fP);" .SH DESCRIPTION These functions manipulate the attributes and color of the window rendition of the current or specified window. .P The .Fn attr_get and .Fn wattr_get functions obtain the current rendition of a window. .P The .Fn attr_off and .Fn wattr_off functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_on and .Fn wattr_on functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_set and .Fn wattr_set functions set the window rendition of the current or specified window to \f2attrs\f1 and \f2color\f1. .P The .Fn color_set and .Fn wcolor_set functions set the window color of the current or specified window to color. .P The \f2opts\f1 argument is reswerved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" These functions always return OK. .SH ERRORS No errors are defined. .SH "SEE ALSO" attroff(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3attr_get(3X)\f1:\0\0\f4attr_off()\f1, \f4attr_on()\f1, \f4attr_set()\f1, \f4color_set()\f1, \f4wattr_get()\f1, \f4wattr_off()\f1, \n\f4wattr_on()\f1, \f4wattr_set()\f1, \f4wcolor_set()\f1@@@window attribute control functions .\" toc@\f4attr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_get()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4color_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wcolor_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" .\" index@\f4attr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4color_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wcolor_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1attribute, for window, control functions@@@\f3attr_get(3X)\f1 .\" index@\f1control functions for window attribute@@@\f3attr_get(3X)\f1 .\" .\" links@attr_get.3x attr_set.3x .\" links@attr_get.3x attr_off.3x .\" links@attr_get.3x attr_on.3x .\" links@attr_get.3x wattr_set.3x .\" links@attr_get.3x wattr_get.3x .\" links@attr_get.3x wattr_off.3x .\" links@attr_get.3x wattr_on.3x .\" links@attr_get.3x color_set.3x .\" links@attr_get.3x wcolor_set.3x .\" .\" fileset_database@attr_get.3x CURS-ENG-A-MAN .\" $Header: attroff.3x,v 76.2 95/07/31 11:26:00 ssa Exp $ .TA a .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH attroff 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attroff, attron, attrset, wattroff, wattron, wattrset \(em restricted window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attroff(int \f2attrs\fP);" .P .C "int attron(int \f2attrs\fP);" .P .C "int attrset(int \f2attrs\fP);" .P .C "int wattroff(WINDOW *\f2win\fP, int \f2attrs\fP);" .P .C "int wattron(WINDOW *\f2win\fP, int \f2attrs\fP);" .P .C "int wattrset(WINDOW *\f2win\fP, int \f2attrs\fP);" .SH DESCRIPTION These functions manipulate the window attributes of the current or specified window. .P The .Fn attroff and .Fn wattroff functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attron and .Fn wattron functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attrset and .Fn wattrset functions set the background attributes of the current or specified window to \f2attrs\f1. .P It is unspecified whether these functions can be used to manipulate attributes other than .CR A_BLINK , .CR A_BOLD , .CR A_DIM , .CR A_REVERSE , .CR A_STANDOUT and .CR A_UNDERLINE . .SH "RETURN VALUE" These functions always return either .CR OK or .CR 1 . .SH ERRORS No errors are defined. .SH "SEE ALSO" attr_get(), standend(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" This entry is rewritten for clarity. The .BR DESCRIPTION is updated to specify that it is undefined whether these functions can be used to manipulate attributes beyond those defined in X/Open Curses, Issue 3. The .CR standend() , .CR standout() , .Fn wstandend and .Fn wstandout functions are moved to the .Fn standend entry. .\" toc@\f3attroff(3X)\f1:\0\0\f4attron()\f1, \f4attrset()\f1, \f4wattroff()\f1, \f4wattron()\f1, \f4wattrset()\f1\n@@@restricted window attribute control functions .\" toc@\f4attron()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4attrset()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattroff()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattron()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattrset()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" .\" index@\f4attroff()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4attron()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4attrset()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattroff()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattron()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattrset()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f1restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f1window attribute control functions, restricted@@@\f3attroff(3X)\f1 .\" index@\f1control functions, restricted window attribute@@@\f3attroff(3X)\f1 .\" .\" links@attroff.3x attron.3x .\" links@attroff.3x attrset.3x .\" links@attroff.3x wattron.3x .\" links@attroff.3x wattroff.3x .\" links@attroff.3x wattrset.3x .\" .\" fileset_database@attroff.3x CURS-ENG-A-MAN .\" $Header: attroff.3x,v 76.2 95/07/31 11:26:00 ssa Exp $ .TA a .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH attroff 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attroff, attron, attrset, wattroff, wattron, wattrset \(em restricted window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attroff(int \f2attrs\fP);" .P .C "int attron(int \f2attrs\fP);" .P .C "int attrset(int \f2attrs\fP);" .P .C "int wattroff(WINDOW *\f2win\fP, int \f2attrs\fP);" .P .C "int wattron(WINDOW *\f2win\fP, int \f2attrs\fP);" .P .C "int wattrset(WINDOW *\f2win\fP, int \f2attrs\fP);" .SH DESCRIPTION These functions manipulate the window attributes of the current or specified window. .P The .Fn attroff and .Fn wattroff functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attron and .Fn wattron functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attrset and .Fn wattrset functions set the background attributes of the current or specified window to \f2attrs\f1. .P It is unspecified whether these functions can be used to manipulate attributes other than .CR A_BLINK , .CR A_BOLD , .CR A_DIM , .CR A_REVERSE , .CR A_STANDOUT and .CR A_UNDERLINE . .SH "RETURN VALUE" These functions always return either .CR OK or .CR 1 . .SH ERRORS No errors are defined. .SH "SEE ALSO" attr_get(), standend(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" This entry is rewritten for clarity. The .BR DESCRIPTION is updated to specify that it is undefined whether these functions can be used to manipulate attributes beyond those defined in X/Open Curses, Issue 3. The .CR standend() , .CR standout() , .Fn wstandend and .Fn wstandout functions are moved to the .Fn standend entry. .\" toc@\f3attroff(3X)\f1:\0\0\f4attron()\f1, \f4attrset()\f1, \f4wattroff()\f1, \f4wattron()\f1, \f4wattrset()\f1\n@@@restricted window attribute control functions .\" toc@\f4attron()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4attrset()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattroff()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattron()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattrset()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" .\" index@\f4attroff()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4attron()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4attrset()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattroff()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattron()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattrset()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f1restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f1window attribute control functions, restricted@@@\f3attroff(3X)\f1 .\" index@\f1control functions, restricted window attribute@@@\f3attroff(3X)\f1 .\" .\" links@attroff.3x attron.3x .\" links@attroff.3x attrset.3x .\" links@attroff.3x wattron.3x .\" links@attroff.3x wattroff.3x .\" links@attroff.3x wattrset.3x .\" .\" fileset_database@attroff.3x CURS-ENG-A-MAN .\" $Header: attroff.3x,v 76.2 95/07/31 11:26:00 ssa Exp $ .TA a .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH attroff 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attroff, attron, attrset, wattroff, wattron, wattrset \(em restricted window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attroff(int \f2attrs\fP);" .P .C "int attron(int \f2attrs\fP);" .P .C "int attrset(int \f2attrs\fP);" .P .C "int wattroff(WINDOW *\f2win\fP, int \f2attrs\fP);" .P .C "int wattron(WINDOW *\f2win\fP, int \f2attrs\fP);" .P .C "int wattrset(WINDOW *\f2win\fP, int \f2attrs\fP);" .SH DESCRIPTION These functions manipulate the window attributes of the current or specified window. .P The .Fn attroff and .Fn wattroff functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attron and .Fn wattron functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attrset and .Fn wattrset functions set the background attributes of the current or specified window to \f2attrs\f1. .P It is unspecified whether these functions can be used to manipulate attributes other than .CR A_BLINK , .CR A_BOLD , .CR A_DIM , .CR A_REVERSE , .CR A_STANDOUT and .CR A_UNDERLINE . .SH "RETURN VALUE" These functions always return either .CR OK or .CR 1 . .SH ERRORS No errors are defined. .SH "SEE ALSO" attr_get(), standend(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" This entry is rewritten for clarity. The .BR DESCRIPTION is updated to specify that it is undefined whether these functions can be used to manipulate attributes beyond those defined in X/Open Curses, Issue 3. The .CR standend() , .CR standout() , .Fn wstandend and .Fn wstandout functions are moved to the .Fn standend entry. .\" toc@\f3attroff(3X)\f1:\0\0\f4attron()\f1, \f4attrset()\f1, \f4wattroff()\f1, \f4wattron()\f1, \f4wattrset()\f1\n@@@restricted window attribute control functions .\" toc@\f4attron()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4attrset()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattroff()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattron()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" toc@\f4wattrset()\f1: restricted window attribute control functions@@@see \f3attroff(3X)\f1 .\" .\" index@\f4attroff()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4attron()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4attrset()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattroff()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattron()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f4wattrset()\f1 \- restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f1restricted window attribute control functions@@@\f3attroff(3X)\f1 .\" index@\f1window attribute control functions, restricted@@@\f3attroff(3X)\f1 .\" index@\f1control functions, restricted window attribute@@@\f3attroff(3X)\f1 .\" .\" links@attroff.3x attron.3x .\" links@attroff.3x attrset.3x .\" links@attroff.3x wattron.3x .\" links@attroff.3x wattroff.3x .\" links@attroff.3x wattrset.3x .\" .\" fileset_database@attroff.3x CURS-ENG-A-MAN .\" $Header: bkgd.3x,v 76.2 95/07/31 17:03:01 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH bkgd 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bkgd, bkgdset, getbkgd, wbkgd, wbkgdset \(em set or get background character and rendition using a single-byte character .SH SYNOPSIS .C "#include " .P .C "int bkgd(chtype \f2ch\fP);" .P .C "void bkgdset(chtype \f2ch\fP);" .P .C "chtype getbkgd(WINDOW *\f2win\fP);" .P .C "int wbkgd(WINDOW *\f2win\fP, chtype \f2ch\fP);" .P .C "void wbkgdset(WINDOW *\f2win\fP, chtype \f2ch\fP);" .SH DESCRIPTION The .Fn bkgdset and .Fn wbkgdset functions set the background property of the current or specified window based on the information in \f2ch\f1. If \f2ch\f1 refers to a multi-column character, the results are undefined. .P The .Fn bkgd and .Fn wbkgd functions set the background property of the current or specified window and then apply this setting to every character position in that window: .RS .TP 3 .C \(bu The rendition of every character on the screen is changed to the new background rendition. .TP .C \(bu Wherever the former background character appears, it is changed to the new background character. .RE .P The .Fn getbkgd function extracts the specified window's background character and rendition. .SH "RETURN VALUE" Upon successful completion, .Fn bkgd and .Fn wbkgd return OK. Otherwise, they return ERR. .P The .Fn bkgdset and .Fn wbkgdset functions do not return a value. .P Upon successful completion, .Fn getbkgd returns the specified window's background character and rendition. Otherwise, it returns (\f3chtype\fP)ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" \f3Rendition\f1 in curses_intro, . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3bkgd(3X)\f1:\0\0\f4bkgd()\f1, \f4bkgdset()\f1, \f4getbkgd()\f1, \f4wbkgd()\f1, \f4wbkgdset()\f1\n@@@set or get background character and rendition using a single-byte character .\" toc@\f4bkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4bkgdset()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4getbkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4wbkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4wbkgdset()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" .\" index@\f4bkgd()\f1 \- set or get background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1set or get background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1get or set background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1single-byte character, set or get background character or rendition, using@@@\f3bkgd(3X)\f1 .\" .\" links@bkgd.3x bkgdset.3x .\" links@bkgd.3x getbkgd.3x .\" links@bkgd.3x wbkgd.3x .\" links@bkgd.3x wbkgdset.3x .\" .\" fileset_database@bkgd.3x CURS-ENG-A-MAN .\" $Header: bkgd.3x,v 76.2 95/07/31 17:03:01 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH bkgd 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bkgd, bkgdset, getbkgd, wbkgd, wbkgdset \(em set or get background character and rendition using a single-byte character .SH SYNOPSIS .C "#include " .P .C "int bkgd(chtype \f2ch\fP);" .P .C "void bkgdset(chtype \f2ch\fP);" .P .C "chtype getbkgd(WINDOW *\f2win\fP);" .P .C "int wbkgd(WINDOW *\f2win\fP, chtype \f2ch\fP);" .P .C "void wbkgdset(WINDOW *\f2win\fP, chtype \f2ch\fP);" .SH DESCRIPTION The .Fn bkgdset and .Fn wbkgdset functions set the background property of the current or specified window based on the information in \f2ch\f1. If \f2ch\f1 refers to a multi-column character, the results are undefined. .P The .Fn bkgd and .Fn wbkgd functions set the background property of the current or specified window and then apply this setting to every character position in that window: .RS .TP 3 .C \(bu The rendition of every character on the screen is changed to the new background rendition. .TP .C \(bu Wherever the former background character appears, it is changed to the new background character. .RE .P The .Fn getbkgd function extracts the specified window's background character and rendition. .SH "RETURN VALUE" Upon successful completion, .Fn bkgd and .Fn wbkgd return OK. Otherwise, they return ERR. .P The .Fn bkgdset and .Fn wbkgdset functions do not return a value. .P Upon successful completion, .Fn getbkgd returns the specified window's background character and rendition. Otherwise, it returns (\f3chtype\fP)ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" \f3Rendition\f1 in curses_intro, . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3bkgd(3X)\f1:\0\0\f4bkgd()\f1, \f4bkgdset()\f1, \f4getbkgd()\f1, \f4wbkgd()\f1, \f4wbkgdset()\f1\n@@@set or get background character and rendition using a single-byte character .\" toc@\f4bkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4bkgdset()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4getbkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4wbkgd()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" toc@\f4wbkgdset()\f1: set or get background character and rendition using a single-byte character@@@see \f3bkgd(3X)\f1 .\" .\" index@\f4bkgd()\f1 \- set or get background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1set or get background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1get or set background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1background character and rendition using a single-byte character@@@\f3bkgd(3X)\f1 .\" index@\f1single-byte character, set or get background character or rendition, using@@@\f3bkgd(3X)\f1 .\" .\" links@bkgd.3x bkgdset.3x .\" links@bkgd.3x getbkgd.3x .\" links@bkgd.3x wbkgd.3x .\" links@bkgd.3x wbkgdset.3x .\" .\" fileset_database@bkgd.3x CURS-ENG-A-MAN .\" $Header: bkgrnd.3x,v 76.2 95/07/31 17:05:26 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH bkgrnd 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bkgrnd, bkgrndset, getbkgrnd, wbkgrnd, wbkgrndset, wgetbkgrnd \(em set or get background character and rendition using a complex character .SH SYNOPSIS .C "#include " .P .C "int bkgrnd(cchar_t *const \f2wch\fP);" .P .C "void bkgrndset(cchar_t *const \f2wch\fP);" .P .C "int getbkgrnd(cchar_t *\f2wch\fP);" .P .C "int wbkgrnd(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "void wbkgrndset(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "int wgetbkgrnd(WINDOW *\f2win\fP, cchar_t *\f2wch\fP);" .SH DESCRIPTION The .Fn bkgrndset and .Fn wbkgrndset functions set the background property of the current or specified window based on the information in \f2wch\f1. .P The .Fn bkgrnd and .Fn wbkgrnd functions set the background property of the current or specified window and then apply this setting to every character position in that window: .RS .TP 3 .C \(bu The rendition of every character on the screen is changed to the new background rendition. .TP .C \(bu Wherever the former background character appears, it is changed to the new background character. .RE .P If \f2wch\f1 refers to a non-spacing complex character for .CR bkgrnd() , .CR bkgrndset() , .Fn wbkgrnd and .CR wbkgrndset() , then \f2wch\f1 is added to the existing spacing complex character that is the background character. If \f2wch\f1 refers to a multi-column character, the results are unspecified. .P The .Fn getbkgrnd and .Fn wgetbkgrnd functions store, into the area pointed to by \f2wch\fP, the value of the window's background character and rendition. .SH "RETURN VALUE" The .Fn bkgrndset and .Fn wbkgrndset functions do not return a value. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Rendition\f1 in curses_intro, .Hd curses.h .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3bkgrnd(3X)\f1:\0\0\f4bkgrnd()\f1, \f4bkgrndset()\f1, \f4getbkgrnd()\f1, \f4wbkgrnd()\f1, \f4wbkgrndset()\f1, \f4wgetbkgrnd()\f1\n@@@set or get background character and rendition using a complex character .\" toc@\f4bkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4bkgrndset()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4getbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wbkgrndset()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wgetbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" index@\f1set or get background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1get or set background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1complex character, set or get background character and rendition using@@@\f3bkgrnd(3X)\f1 .\" index@\f4bkgrnd()\f1 \- set or get background character and rendition using omplex character@@@\f3bkgrnd(3X)\f1 .\" .\" links@bkgrnd.3x bkgrndset.3x .\" links@bkgrnd.3x getbkgrnd.3x .\" links@bkgrnd.3x wbkgrnd.3x .\" links@bkgrnd.3x wbkgrndset.3x .\" links@bkgrnd.3x wgetbkgrnd.3x .\" .\" fileset_database@bkgrnd.3x CURS-ENG-A-MAN .\" $Header: bkgrnd.3x,v 76.2 95/07/31 17:05:26 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH bkgrnd 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bkgrnd, bkgrndset, getbkgrnd, wbkgrnd, wbkgrndset, wgetbkgrnd \(em set or get background character and rendition using a complex character .SH SYNOPSIS .C "#include " .P .C "int bkgrnd(cchar_t *const \f2wch\fP);" .P .C "void bkgrndset(cchar_t *const \f2wch\fP);" .P .C "int getbkgrnd(cchar_t *\f2wch\fP);" .P .C "int wbkgrnd(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "void wbkgrndset(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "int wgetbkgrnd(WINDOW *\f2win\fP, cchar_t *\f2wch\fP);" .SH DESCRIPTION The .Fn bkgrndset and .Fn wbkgrndset functions set the background property of the current or specified window based on the information in \f2wch\f1. .P The .Fn bkgrnd and .Fn wbkgrnd functions set the background property of the current or specified window and then apply this setting to every character position in that window: .RS .TP 3 .C \(bu The rendition of every character on the screen is changed to the new background rendition. .TP .C \(bu Wherever the former background character appears, it is changed to the new background character. .RE .P If \f2wch\f1 refers to a non-spacing complex character for .CR bkgrnd() , .CR bkgrndset() , .Fn wbkgrnd and .CR wbkgrndset() , then \f2wch\f1 is added to the existing spacing complex character that is the background character. If \f2wch\f1 refers to a multi-column character, the results are unspecified. .P The .Fn getbkgrnd and .Fn wgetbkgrnd functions store, into the area pointed to by \f2wch\fP, the value of the window's background character and rendition. .SH "RETURN VALUE" The .Fn bkgrndset and .Fn wbkgrndset functions do not return a value. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Rendition\f1 in curses_intro, .Hd curses.h .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3bkgrnd(3X)\f1:\0\0\f4bkgrnd()\f1, \f4bkgrndset()\f1, \f4getbkgrnd()\f1, \f4wbkgrnd()\f1, \f4wbkgrndset()\f1, \f4wgetbkgrnd()\f1\n@@@set or get background character and rendition using a complex character .\" toc@\f4bkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4bkgrndset()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4getbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wbkgrndset()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wgetbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" index@\f1set or get background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1get or set background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1complex character, set or get background character and rendition using@@@\f3bkgrnd(3X)\f1 .\" index@\f4bkgrnd()\f1 \- set or get background character and rendition using omplex character@@@\f3bkgrnd(3X)\f1 .\" .\" links@bkgrnd.3x bkgrndset.3x .\" links@bkgrnd.3x getbkgrnd.3x .\" links@bkgrnd.3x wbkgrnd.3x .\" links@bkgrnd.3x wbkgrndset.3x .\" links@bkgrnd.3x wgetbkgrnd.3x .\" .\" fileset_database@bkgrnd.3x CURS-ENG-A-MAN .\" $Header: border.3x,v 76.2 95/07/31 17:06:39 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH border 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME border, wborder \(em draw borders from single-byte characters and renditions .SH SYNOPSIS .C "#include " .P .C "int border(chtype \f2ls\fP, chtype \f2rs\fP, chtype \f2ts\fP, chtype \f2bs\fP, chtype \f2tl\fP," .br .C " chtype \f2tr\fP, chtype \f2bl\fP, chtype \f2br\fP);" .P .C "int wborder(WINDOW *\f2win\fP, chtype \f2ls\fP, chtype \f2rs\fP, chtype \f2ts\fP, chtype \f2bs\fP," .br .C " chtype \f2tl\fP, chtype \f2tr\fP, chtype \f2bl\fP, chtype \f2br\fP);" .SH DESCRIPTION The .Fn border and .Fn wborder functions draw a border around the edges of the current or specified window. These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The arguments in the left-hand column of the following table contain single-byte characters with renditions, which have the following uses in drawing the border: .PP .TS box center tab(@); cb cb cb cb cb cb li l l. Argument@@Default Name@Usage@Value _ ls@Starting-column side@ACS_VLINE rs@Ending-column side@ACS_VLINE ts@First-line side@ACS_HLINE bs@Last-line side@ACS_HLINE tl@Corner of the first line and the starting column@ACS_ULCORNER tr@Corner of the first line and the ending column@ACS_URCORNER bl@Corner of the last line and the starting column@ACS_BLCORNER br@Corner of the last line and the ending column@ACS_BRCORNER .TE .PP If the value of any argument in the left-hand column is 0, then the default value in the right-hand column is used. If the value of any argument in the left-hand column is a multi-column character, the results are undefined. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" border_set(), box (), hline(), .Hd curses.h .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3border(3X)\f1:\0\0\f4wborder()\f1@@@draw borders from single-byte characters and renditions .\" toc@\f4wborder()\f1: draw borders from single-byte characters and renditions@@@see \f3border(3X)\f1 .\" index@\f1draw borders from single-byte characters and renditions@@@\f3border(3X)\f1 .\" index@\f4border()\f1 \- draw borders from single-byte characters and renditions@@@\f3border(3X)\f1 .\" index@\f1borders, draw from single-byte characters and renditions@@@\f3border(3X)\f1 .\" index@\f1single-byte characters and renditions, draw borders@@@\f3border(3X)\f1 .\" .\" links@border.3x wborder.3x .\" .\" fileset_database@border.3x CURS-ENG-A-MAN .\" $Header: border_set.3x,v 76.2 95/07/31 17:08:12 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH border_set 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME border_set, wborder_set \(em draw borders from complex characters and renditions .SH SYNOPSIS .C "#include " .P .C "int border_set(cchar_t *const \f2ls\fP, cchar_t *const \f2rs\fP, cchar_t *const \f2ts\fP," .br .C " cchar_t *const \f2bs\fP, cchar_t *const \f2tl\fP, cchar_t *const \f2tr\fP," .br .C " cchar_t *const \f2bl\fP, cchar_t *const \f2br\fP);" .PP .C "int wborder_set(WINDOW *\f2win\fP, cchar_t *const \f2ls\fP, cchar_t *const \f2rs\fP," .br .C " cchar_t *const \f2ts\fP, cchar_t *const \f2bs\fP, " .br .C " cchar_t *const \f2tl\fP, cchar_t *const \f2tr\fP, " .br .C " cchar_t *const \f2bl\fP, cchar_t *const \f2br\fP);" .SH DESCRIPTION The .Fn border_set and .Fn wborder_set functions draw a border around the edges of the current or specified window. These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The arguments in the left-hand column of the following table contain spacing complex characters with renditions, which have the following uses in drawing the border: .PP .TS box center tab(@); cb cb cb cb cb cb li l l. Argument@@Default Name@Usage@Value _ ls@Starting-column side@WACS_VLINE rs@Ending-column side@WACS_VLINE ts@First-line side@WACS_HLINE bs@Last-line side@WACS_HLINE tl@Corner of the first line and the starting column@WACS_ULCORNER tr@Corner of the first line and the ending column@WACS_URCORNER bl@Corner of the last line and the starting column@WACS_BLCORNER br@Corner of the last line and the ending column@WACS_BRCORNER .TE .PP If the value of any argument in the left-hand column is a null pointer, then the default value in the right-hand column is used. If the value of any argument in the left-hand column is a multi-column character, the results are undefined. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" box_set(), hline_set(), .Hd curses.h .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3border_set(3X)\f1:\0\0\f4wborder_set()\f1@@@draw borders from complex characters and renditions .\" toc@\f4wborder_set()\f1: draw borders from complex characters and renditions@@@see \f3border_set(3X)\f1 .\" .\" index@\f4border_set()\f1 \- draw borders from complex characters and renditions@@@\f3border_set(3X)\f1 .\" index@\f1draw borders from complex characters and renditions@@@\f3border_set(3X)\f1 .\" index@\f1borders, draw from complex characters and renditions@@@\f3border_set(3X)\f1 .\" index@\f1complex characters and renditions, draw borders@@@\f3border_set(3X)\f1 .\" .\" links@border_set.3x wborder_set.3x .\" .\" fileset_database@border_set.3x CURS-ENG-A-MAN .\" $Header: chgat.3x,v 76.2 95/07/31 17:23:18 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH chgat 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME chgat, mvchgat, mvwchgat, wchgat \(em change renditions of characters in a window .SH SYNOPSIS .C "#include " .P .C "int chgat(int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP, void *const \f2opts\fP);" .P .C "int mvchgat(int \f2y\fP, int \f2x\fP, int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP," .br .C " void *const \f2opts\fP);" .P .C "int mvwchgat(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, int \f2n\fP, attr_t \f2attr\fP," .br .C " short \f2color\fP, void *const \f2opts\fP);" .P .C "int wchgat(WINDOW *\f2win\fP, int \f2n\fP, attr_t \f2attr\fP, short \f2color\fP," .br .C " void *const \f2opts\fP);" .SH DESCRIPTION These functions change the renditions of the next \f2n\f1 characters in the current or specified window (or of the remaining characters on the line, if \f2n\f1 is \(mi1), starting at the current or specified cursor position. The attributes and colors are specified by \f2attr\f1 and \f2color\f1 as for .CR setcchar() . .P These functions do not update the cursor. These functions do not perform wrapping. .P A value of \f2n\f1 that is greater than the remaining characters on a line is not an error. .P The \f2opts\f1 argument is reserved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" setcchar(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3chgat(3X)\f1:\0\0\f4chgat()\f1, \f4mvchgat()\f1, \f4mvwchgat()\f1, \f4wchgat()\f1@@@change renditions of characters in a window .\" toc@\f4mvchgat()\f1: change renditions of characters in a window@@@see \f3chgat(3X)\f1 .\" toc@\f4mvwchgat()\f1: change renditions of characters in a window@@@see \f3chgat(3X)\f1 .\" toc@\f4wchgat()\f1: change renditions of characters in a window@@@see \f3chgat(3X)\f1 .\" .\" index@\f4chgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f4mvchgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f4mvwchgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f4wchgat()\f1 \- change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f1change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f1renditions of characters in a window, change@@@\f3chgat(3X)\f1 .\" index@\f1window, change renditions of characters in a window@@@\f3chgat(3X)\f1 .\" index@\f1characters, renditions of, change in a window@@@\f3chgat(3X)\f1 .\" .\" links@chgat.3x mvchgat.3x .\" links@chgat.3x mvwchgat.3x .\" links@chgat.3x wchgat.3x .\" .\" fileset_database@chgat.3x CURS-ENG-A-MAN .\" $Header: clear.3x,v 76.2 95/07/31 17:24:33 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH clear 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clear, erase, wclear, werase \(em clear a window .SH SYNOPSIS .C "#include " .P .C "int clear(void);" .P .C "int erase(void);" .P .C "int wclear(WINDOW *\f2win\fP);" .P .C "int werase(WINDOW *\f2win\fP);" .SH DESCRIPTION The .CR clear() , .CR erase() , .Fn wclear and .Fn werase functions clear every position in the current or specified window. .P The .Fn clear and .Fn wclear functions also achieve the same effect as calling .Fn clearok , so that the window is cleared completely on the next call to .Fn wrefresh for the window and is redrawn in its entirety. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" clearok(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn erase and .Fn werase functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The argument list for the .Fn clear and .Fn erase functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3clear(3X)\f1:\0\0\f4clear()\f1, \f4erase()\f1, \f4wclear()\f1, \f4werase()\f1@@@clear a window .\" toc@\f4erase()\f1: clear a window@@@see \f3clear(3X)\f1 .\" toc@\f4werase()\f1: clear a window@@@see \f3clear(3X)\f1 .\" toc@\f4wclear()\f1: clear a window@@@see \f3clear(3X)\f1 .\" .\" index@\f4clear()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f4wclear()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f4erase()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f4werase()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f1clear a window@@@\f3clear(3X)\f1 .\" index@\f1window, clear@@@\f3clear(3X)\f1 .\" .\" links@clear.3x wclear.3x .\" links@clear.3x erase.3x .\" links@clear.3x werase.3x .\" .\" fileset_database@clear.3x CURS-ENG-A-MAN .\" $Header: clrtobot.3x,v 76.2 95/07/31 17:27:49 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH clrtobot 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clrtobot, wclrtobot \(em clear from cursor to end of window .SH SYNOPSIS .C "#include " .P .C "int clrtobot(void);" .P .C "int wclrtobot(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn clrtobot and .Fn wclrtobot functions erase all lines following the cursor in the current or specified window, and erase the current line from the cursor to the end of the line, inclusive. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn clrtobot function is explicitly declared as \f3void\f1. .\" .\" toc@\f3clrtobot(3X)\f1:\0\0\f4clrtobot()\f1, \f4wclrtobot()\f1@@@clear from cursor to end of window .\" toc@\f4wclrtobot()\f1: clear from cursor to end of window@@@see \f3clrtobot(3X)\f1 .\" .\" index@\f4clrtobot()\f1 \- clear from cursor to end of window@@@\f3clrtobot(3X)\f1 .\" index@\f4wclrtobot()\f1 \- clear from cursor to end of window@@@\f3clrtobot(3X)\f1 .\" index@\f1clear from cursor to end of window@@@\f3clrtobot(3X)\f1 .\" index@\f1cursor to end of window, clear@@@\f3clrtobot(3X)\f1 .\" index@\f1window, clear from cursor to end of window@@@\f3clrtobot(3X)\f1 .\" .\" links@clrtobot.3x wclrtobot.3x .\" .\" fileset_database@clrtobot.3x CURS-ENG-A-MAN .\" $Header: clrtoeol.3x,v 76.2 95/07/31 17:29:24 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH clrtoeol 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clrtoeol, wclrtoeol \(em clear from cursor to end of line .SH SYNOPSIS .C "#include " .P .C "int clrtoeol(void);" .P .C "int wclrtoeol(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn clrtoeol and .Fn wclrtoeol functions erase the current line from the cursor to the end of the line, inclusive, in the current or specified window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn clrtoeol function is explicitly declared as \f3void\f1. .\" .\" toc@\f3clrtoeol(3X)\f1:\0\0\f4clrtoeol()\f1, \f4wclrtoeol()\f1@@@clear from cursor to end of line .\" toc@\f4wclrtoeol()\f1: clear from cursor to end of line@@@see \f3clrtoeol(3X)\f1 .\" .\" index@\f4clrtoeol()\f1 \- clear from cursor to end of line@@@\f3clrtoeol(3X)\f1 .\" index@\f4wclrtoeol()\f1 \- clear from cursor to end of line@@@\f3clrtoeol(3X)\f1 .\" index@\f1clear from cursor to end of line@@@\f3clrtoeol(3X)\f1 .\" index@\f1cursor, clear from it to end of line@@@\f3clrtoeol(3X)\f1 .\" index@\f1end of line, clear from cursor to end of line@@@\f3clrtoeol(3X)\f1 .\" .\" links@clrtoeol.3x wclrtoeol.3x .\" .\" fileset_database@clrtoeol.3x CURS-ENG-A-MAN .\" $Header: attr_get.3x,v 76.2 95/07/31 11:21:27 ssa Exp $ .TA a .de Fn .C \\$1() .. .de Hd .BR <\\$1> .. .TH attr_get 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME attr_get, attr_off, attr_on, attr_set, color_set, wattr_get, wattr_off, wattr_on, wattr_set, wcolor_set \(em window attribute control functions .SH SYNOPSIS .C "#include " .P .C "int attr_get(attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int attr_off(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_on(attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int attr_set(attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int color_set(short \f2color\fP);" .P .C "int wattr_get(WINDOW *\f2win\fP, attr_t *\f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wattr_off(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_on(WINDOW *\f2win\fP, attr_t \f2attrs\fP, void *\f2opts\fP);" .P .C "int wattr_set(WINDOW *\f2win\fP, attr_t \f2attrs\fP, short *\f2color\fP, void *\f2opts\fP);" .P .C "int wcolor_set(WINDOW *\f2win\fP, short \f2color\fP);" .SH DESCRIPTION These functions manipulate the attributes and color of the window rendition of the current or specified window. .P The .Fn attr_get and .Fn wattr_get functions obtain the current rendition of a window. .P The .Fn attr_off and .Fn wattr_off functions turn off \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_on and .Fn wattr_on functions turn on \f2attrs\f1 in the current or specified window without affecting any others. .P The .Fn attr_set and .Fn wattr_set functions set the window rendition of the current or specified window to \f2attrs\f1 and \f2color\f1. .P The .Fn color_set and .Fn wcolor_set functions set the window color of the current or specified window to color. .P The \f2opts\f1 argument is reswerved for definition in a future edition of this document. Currently, the application must provide a null pointer as \f2opts\f1. .SH "RETURN VALUE" These functions always return OK. .SH ERRORS No errors are defined. .SH "SEE ALSO" attroff(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3attr_get(3X)\f1:\0\0\f4attr_off()\f1, \f4attr_on()\f1, \f4attr_set()\f1, \f4color_set()\f1, \f4wattr_get()\f1, \f4wattr_off()\f1, \n\f4wattr_on()\f1, \f4wattr_set()\f1, \f4wcolor_set()\f1@@@window attribute control functions .\" toc@\f4attr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4attr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_get()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_off()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wattr_on()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4color_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" toc@\f4wcolor_set()\f1: window attribute control functions@@@see \f3attr_get(3X)\f1 .\" .\" index@\f4attr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4attr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4color_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_get()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_off()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_on()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wattr_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f4wcolor_set()\f1 \- window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1window attribute control functions@@@\f3attr_get(3X)\f1 .\" index@\f1attribute, for window, control functions@@@\f3attr_get(3X)\f1 .\" index@\f1control functions for window attribute@@@\f3attr_get(3X)\f1 .\" .\" links@attr_get.3x attr_set.3x .\" links@attr_get.3x attr_off.3x .\" links@attr_get.3x attr_on.3x .\" links@attr_get.3x wattr_set.3x .\" links@attr_get.3x wattr_get.3x .\" links@attr_get.3x wattr_off.3x .\" links@attr_get.3x wattr_on.3x .\" links@attr_get.3x color_set.3x .\" links@attr_get.3x wcolor_set.3x .\" .\" fileset_database@attr_get.3x CURS-ENG-A-MAN .\" $Header: wconv.3c,v 72.7 94/11/28 08:37:51 ssa Exp $ .TA w .TH wconv 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME towupper(\|), towlower(\|) \- translate wide characters .SH SYNOPSIS .C "#include " .PP .C "wint_t towupper(wint_t wc);" .PP .C "wint_t towlower(wint_t wc);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character conversion functions. They parallel the 8-bit character conversion functions defined in .IR conv(3C) . .SH DESCRIPTION .C towupper() and .C towlower() have as domain a .CR wint_t , the value of which is representable as a .C wchar_t or the value .CR WEOF . If the argument has any other value, the behavior is undefined. If the argument of .C towupper() represents a lowercase letter, the result is the corresponding uppercase letter. If the argument of .C towlower() represents an uppercase letter, the result is the corresponding lowercase letter. All other arguments are returned unchanged. .PP Definitions for these functions, the types .CR wint_t , .CR wchar_t , and the value .C WEOF are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the translations to be done. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wconv() was developed by IBM, OSF, and HP. .SH SEE ALSO conv(3C), multibyte(3C), wctype(3C), setlocale(3C), lang(5). .SH STANDARDS CONFORMANCE .CR towlower() ": XPG4" .PP .CR towupper() ": XPG4" .\" .\" index@\f4wconv()\f1 \- translate wide characters@@@\f3wconv(3C)\f1 .\" index@\f4towupper()\f1 \- translate wide characters to uppercase@@@\f3wconv(3C)\f1 .\" index@\f4towlower()\f1 \- translate wide characters to lowercase@@@\f3wconv(3C)\f1 .\" index@\f1translate wide characters to uppercase or lowercase@@@\f3wconv(3C)\f1 .\" index@\f1wide characters, translate to uppercase or lowercase@@@\f3wconv(3C)\f1 .\" index@\f1uppercase, translate wide characters to@@@\f3wconv(3C)\f1 .\" index@\f1lowercase, translate wide characters to@@@\f3wconv(3C)\f1 .\" .\" toc@\f3wconv(3C)\f1:\0\0\f4towupper()\f1, \f4towlower()\f1@@@translate wide characters .\" toc@\f4towupper()\f1:\0\0translate wide characters@@@\f1see \f3wconv(3C)\f1 .\" toc@\f4towlower()\f1:\0\0translate wide characters@@@\f1see \f3wconv(3C)\f1 .\" .\" links@wconv.3c towupper.3c .\" links@wconv.3c towlower.3c .\" .\" fileset_database@wconv.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcsftime.3c,v 72.6 94/11/29 10:02:04 ssa Exp $ .TA w .TH wcsftime 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcsftime(\|) \- convert date and time to wide-character string .SH SYNOPSIS .nf .C "#include " .PP .C "size_t wcsftime(" .PD 0 .IP .C "wchar_t *ws," .C "size_t maxsize," .C "const char *format," .C "const struct tm *timeptr" .PP .C ");" .PD .fi .SS Remarks: This function is compliant with the .SM XPG4 Worldwide Portability Interface wide-character formatting functions. It parallels the 8-bit character formatting function defined in .IR strftime (3C). .SH DESCRIPTION .C wcsftime() converts the contents of a .C tm structure (see .IR ctime (3C)) to a formatted date and time wide-character string. .PP .C wcsftime() places wide characters into the array pointed to by .I ws as controlled by the string pointed to by .IR format . The .I format string consists of zero or more directives and ordinary characters. A directive consists of a .C % character, an optional field width and precision specification, and a terminating character that determines the directive's behavior. All ordinary characters (including the terminating null character) are converted into corresponding wide characters and are copied into the array. No more than .I maxsize wide characters are placed into the array. Each directive is replaced by the appropriate wide characters as described in the following list. The appropriate wide characters are determined by the program's locale, by the values contained in the structure pointed to by .IR timeptr , and by the .C TZ environment variable (see External Influences below). .PP The definition for this function and the type .C wchar_t are provided in the .RC < wchar.h > header. .SS Directives The following directives, shown without the optional field width and precision specification, are replaced by the corresponding wide characters as indicated: .RS .TP 10 .CR %a Locale's abbreviated weekday name. .PD 0 .TP .CR %A Locale's full weekday name. .TP .CR %b Locale's abbreviated month name. .TP .CR %B Locale's full month name. .TP .CR %c Locale's appropriate date and time representation. .TP .CR %C The century number (the year divided by 100 and truncated to an integer) as a decimal number [00-99]. .TP .CR %d Day of the month as a decimal number [01,31]. .TP .CR %D Equivalent to the directive string .I %m/%d/%y. .TP .CR %e Day of the month as a decimal number [1,31]; a single digit is preceded by a space. .TP .CR %h Equivalent to %b. .TP .CR %H Hour (24-hour clock) as a decimal number [00,23]. .TP .CR %I Hour (12-hour clock) as a decimal number [01,12]. .TP .CR %j Day of the year as a decimal number [001,366]. .TP .CR %m Month as a decimal number [01,12]. .TP .CR %M Minute as a decimal number [00,59]. .TP .CR %n The New-line character. .TP .CR %p Locale's equivalent of either .SM AM or .SM PM. .TP .CR %r The time in AM and PM notation; in the POSIX locale this is equivalent to .I %I:%M:%S %p. .TP .CR %R The time in 24 hour notation (%H:%M). .TP .CR %S Second as a decimal number [00,61]. .TP .CR %t The Tab character. .TP .CR %T The time in hours, minutes, and seconds (%H:%M:%S). .TP .CR %u The weekday as a decimal number [1(Monday),7]. .TP .CR %U Week number of the year (Sunday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Sunday are considered to be in week 0. .TP .CR %V The week number of the year (Monday as the first day of the week) as a decimal number [01,53]. If the week containing January 1st has four or more days in the new year, then it is considered week 1; otherwise, it is week 53 of the previous year, and the next week is week 1. .TP .CR %w Weekday as a decimal number [0(Sunday),6]. .TP .CR %W Week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0. .TP .CR %x Locale's appropriate date representation. .TP .CR %X Locale's appropriate time representation. .TP .CR %y Year without century as a decimal number [00,99]. .TP .CR %Y Year with century as a decimal number. .TP .CR %Z Time zone name (or by no characters if no time zone exists). .TP .CR %% The percent (%) character. .RE .PD .PP The following directives are provided for backward compatibility with the directives supported by .IR date (1) and the .IR ctime (3C) functions. These directives may be removed in a future release. It is recommended that the directives above be used in preference to those below. .RS .TP 10 .CR %E Locale's combined Emperor/Era name and year (use .CR %EC%Ey instead). .TP .CR %F Locale's full month name (use .CR %B instead). .TP .CR %N Locale's Emperor/Era name (use .CR %EC instead). .TP .CR %o Locale's Emperor/Era year (use .CR %Ey instead). .TP .CR %z Time zone name (or by no characters if no time zone exists) (use .CR %Z instead). .RE .PD .PP If a directive is not one of the above, the behavior is undefined. .SS Modified Conversion Specifiers Some conversion specifiers can be modified by the E or O modifer characters to indicate that an alternative format or specification should be used rather than the one normally used by the unmodified conversion specifier. If the alternative format or specification does not exist for the current locale, the behavior will be as if the unmodified conversion specification were used. Alternative numeric symbols refers to those symbols defined by the .CR ALT_DIGIT .IR (see langinfo(5)) in the locale. .RS .TP 10 .CR %Ec The locales alternative appropriate date and time representation. .TP .CR %EC The name of the base year (period/Emperor/Era) in the locale's alternative representation. .TP .CR %Ex The locale's alternative date representation .TP .CR %EX The locale's alternative time representation. .TP .CR %Ey The offset from %EC (year only) in the locale's alternative representation. .TP .CR %EY The full alternative year representation. .TP .CR %Od The day of the month, using the locale's alternative numeric symbols, filled as needed with leading zeros if there is any alternative symbol for zero, otherwise with leading spaces. .TP .CR %Oe the day of the month, using the locale's alternative numeric symbols, filled as needed with leading spaces. .TP .CR %OH The hour (24-hour clock) using the locale's alternative numeric symbols. .TP .CR %OI The hour (12-hour clock) using the locale's alternative numeric symbols. .TP .CR %Om The month using the locale's alternative numeric symbols. .TP .CR %OM The minutes using the locale's alternative numeric symbols. .TP .CR %OS The seconds using the locale's alternative numeric symbols. .TP .CR %Ou The weekday as a number in the locale's alternative representation (Monday=1). .TP .CR %OU The week number of the year (Sunday as the first day of the week, rules corresponding to %U) using the locale's alternative numeric symbols. .TP .CR %OV The week number of the year (Monday as the first day of the week, rules corresponding to %V) using tht locale's alternative numeric symbols. .TP .CR %Ow The number of the weekday (Sunday=0) using the locale's alternative numeric symbols. .TP .CR %OW The week number of the year (Monday as the first day of the week) using the locale's alternative numeric symbols. .TP .CR %Oy The year (offset from %C) in the locale's alternative representation and using the locale's alternative symbols. .RE .TP .SS Field Width and Precision An optional field width and precision specification can immediately follow the initial .C % of a directive in the following order: .RS .TP 15 .RC [ - \(or 0 ]\f2w\fP the decimal digit string .I w specifies a minimum field width in which the result of the conversion is right- or left-justified. It is right-justified (with space padding) by default. If the optional .C - character is specified, it is left-justified with space padding on the right. If the optional .C 0 character is specified, it is right-justified and padded with zeros on the left. .TP .CI . p the decimal digit string .I p specifies the minimum number of digits to appear for the .CR d , .CR H , .CR I , .CR j , .CR m , .CR M , .CR o , .CR S , .CR U , .CR w , .CR W , .CR y and .C Y directives, and the maximum number of corresponding wide characters to be used from the .CR a , .CR A , .CR b , .CR B , .CR c , .CR D , .CR E , .CR F , .CR h , .CR n , .CR N , .CR p , .CR r , .CR t , .CR T , .CR x , .CR X , .CR z , .CR Z , and .C % directives. In the first case, if a directive supplies fewer digits than specified by the precision, it is expanded with leading zeros. In the second case, if a directive supplies more characters than specified by the precision, excess characters are truncated on the right. .PP If no field width or precision is specified for a .CR d , .CR H , .CR I , .CR m , .CR M , .CR S , .CR U , .CR W , .CR y , or .C j directive, a default of .C .2 is used for all but .C j for which .C .3 is used. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_TIME category determines the characters to be substituted for those directives described above as being from the locale. .PP The .C LC_CTYPE category determines the interpretation of the bytes within .I format as single and/or multi-byte characters as well as how wide-character conversions are done. .PP The .CR LC_NUMERIC category determines the characters used to form numbers for those directives that produce numbers in the output. If .CR ALT_DIGITS (see .IR langinfo (5)) is defined for the locale, the characters so specified are used in place of the default .SM ASCII characters. If both .CR ALT_DIGITS and .CR ALT_DIGIT is defined for the locale, .CR ALT_DIGITS will take precedence over .CR ALT_DIGIT. .SS Environment Variables .C TZ determines the time zone name substituted for the .C %Z and .C %z directives. The time zone name is determined by calling the function .C tzset() which sets the external variable .C tzname (see .IR ctime (3C)). .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE If the total number of resulting wide characters including the terminating null wide character is not more than .CR maxsize , .C wcsftime() returns the number of wide characters placed into the array pointed to by .IR ws , not including the terminating null wide character. Otherwise, zero is returned and the contents of the array are indeterminate. .SH EXAMPLES If the .I timeptr argument contains the following values: .nf .IP .C "timeptr->tm_sec = 4;" .C "timeptr->tm_min = 9;" .C "timeptr->tm_hour = 15;" .C "timeptr->tm_mday = 4;" .C "timeptr->tm_mon = 6;" .C "timeptr->tm_year = 88;" .C "timeptr->tm_wday = 1;" .C "timeptr->tm_yday = 185;" .C "timeptr->tm_isdst = 1;" .fi .PP the following combinations of the .C LC_TIME category and format strings produce the indicated output: .PP .TS center tab(;); lf4 | lB | lB lf4 | lf4 | lf4 . LC_TIME;Format String;Output _ en_US.roman8;%x;Mon, Jul 4, 1988 de_De.roman8;%x;Mo., 4. Juli 1988 en_US.roman8;%X;03:09:04 PM fr_FR.roman8;%X;15h09 04 \f2any\f1\(dg;%H:%M:%S;15:09:04 \f2any\f1\(dg;%.1H:%.1M:%.1S;15:9:4 \f2any\f1\(dg;%2.1H:%-3M:%03.1S;15:9 :004 .TE .IP \(dg The directives used in these examples are not affected by the .C LC_TIME category of the locale. .SH WARNINGS The function .C tzset() is called upon every invocation of .C wcsftime() (whether or not the time zone name is copied to the output array). .PP The range of values for .C %S ([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the system does not accumulate leap seconds and the .C tm structure generated by the functions .C localtime() and .C gmtime() (see .IR ctime (3C)) never reflects any leap seconds. .PP Results are undefined if values contained in the structure pointed to by .I timeptr exceed the ranges defined for the .C tm structure (see .IR ctime (3C)) or are not consistent (such as if the .C tm_yday element is set to 0, indicating the first day of January, while the .C tm_mon element is set to 11, indicating a day in December). .SH AUTHOR .C wcsftime() was developed by OSF and HP. .SH SEE ALSO date(1), ctime(3C), setlocale(3C), environ(5), langinfo(5), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcsftime() ": XPG4" .\" .\" index@\f4wcsftime()\fP \- convert date and time to wide-character string@@@\f3wcsftime(3C)\f1 .\" index@convert date and time to wide-character string@@@\f3wcsftime(3C)\f1 .\" index@date and time, convert to wide-character string@@@\f3wcsftime(3C)\f1 .\" index@time and date, convert to wide-character string@@@\f3wcsftime(3C)\f1 .\" index@wide-character string, convert date and time to@@@\f3wcsftime(3C)\f1 .\" index@string, convert date and time to wide-character@@@\f3wcsftime(3C)\f1 .\" .\" toc@\f3wcsftime(3C)\f1:\0\0\f4wcsftime()\fP@@@convert date and time to wide-character string .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstod.3c,v 72.4 94/11/15 09:57:12 ssa Exp $ .TA w .TH wcstod 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcstod(\|) \- convert wide character string to double-precision number .SH SYNOPSIS .C "#include " .PP .C "double wcstod(const wchar_t *nptr, wchar_t **endptr);" .SS Remarks: This function is compliant with the .SM XPG4 Worldwide Portability Interface wide-character formatting functions. It parallels the 8-bit character formatting function defined in .IR strtod (3C). .SH DESCRIPTION .C wcstod() returns, as a double-precision floating-point number, the value represented by the wide character string pointed to by .IR nptr . The wide character string is scanned (leading white-space characters as defined by .C iswspace() in .IR wctype (3C) are ignored) up to the first unrecognized character. If no conversion can take place, zero is returned. .PP .C wcstod() recognizes wide characters in the following sequence: .RS .TP 5 1. An optional string of ``white-space'' wide characters which are ignored, .PD 0 .TP 2. An optional sign, .TP 3. A string of digits optionally containing a radix character, .TP 4. An optional .C e or .C E followed by an optional sign or space, followed by an integer. .PD .RE .PP The radix character is determined by the current .SM NLS environment (see .IR setlocale (3C)). If .C setlocale() has not been called successfully, the default .SM NLS environment, "C", is used (see .IR lang (5)). The default environment specifies a period (.) as the radix character. .PP If the value of .I endptr is not .CR "(wchar_t **)NULL" , the variable to which it points is set to point at the wide character after the last number, if any, that was recognized. If no number can be formed, .CI * endptr is set to .IR nptr , and zero is returned. .PP The definition for this function and the type .C wchar_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_NUMERIC category determines the value of the radix character within the currently loaded .SM NLS environment. .PP The .C LC_CTYPE category determines how wide character codes are interpreted. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE If the correct value would cause overflow, .C +HUGE_VAL or .C -HUGE_VAL is returned (according to the sign of the value), and .C errno is set to .SM ERANGE. .PP If the correct value would cause underflow, zero is returned and .C errno is set to .SM ERANGE. .SH AUTHOR .C wcstod() was developed by AT&T and HP. .SH SEE ALSO wctype(3C), setlocale(3C), scanf(3S), wcstol(3C), hpnls(5), lang(5). .SH STANDARDS CONFORMANCE .CR wcstod() ": XPG4" .\" .\" index@\f4wcstod()\fP \- convert wide character string to double-precision number@@@\f3wcstod(3C)\f1 .\" index@convert wide character string to double-precision number@@@\f3wcstod(3C)\f1 .\" index@wide character string to double-precision number, convert@@@\f3wcstod(3C)\f1 .\" index@double-precision number, convert wide character string to@@@\f3wcstod(3C)\f1 .\" index@number, convert wide character string to double-precision@@@\f3wcstod(3C)\f1 .\" .\" toc@\f3wcstod(3C)\f1:\0\0\f4wcstod()\fP@@@convert wide character string to double-precision number .\" .\" .\" fileset_database@wcstod.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstol.3c,v 72.5 94/11/15 09:57:13 ssa Exp $ .TA w .TH wcstol 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcstol(\|), wcstoul(\|) \- convert wide character string to long integer .SH SYNOPSIS .C "#include " .PP .C "long int wcstol(const wchar_t *nptr, wchar_t **endptr, int base);" .PP .C "unsigned long int wcstoul(const wchar_t *nptr, wchar_t **endptr, int base);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character formatting functions. They parallel the 8-bit character formatting functions defined in .IR strtol (3C). .SH DESCRIPTION .C wcstol() .RC ( wcstoul() ) converts the wide character string pointed to by .I nptr to .C long int .RC ( "unsigned long int" ) representation. The wide character string is scanned up to the first wide character inconsistent with the base. Leading ``white-space'' wide characters (as defined by .C iswspace() in .IR wctype (3C)) are ignored. If no conversion can take place, zero is returned. .PP If .I base is greater than or equal to 2 and less than or equal to 36, it is used as the base for conversion. After an optional leading sign, leading zeros are ignored, and .C 0x or .C 0X is ignored if .I base is 16. .PP If .I base is zero, the wide character string itself determines the base as follows: After an optional leading sign, a leading zero indicates octal conversion; a leading .C 0x or .C 0X hexadecimal conversion. Otherwise, decimal conversion is used. .PP If the value of .I endptr is not .CR "(wchar_t **)NULL" , a pointer to the wide character terminating the scan is returned in the location pointed to by .IR endptr . If no integer can be formed, the location pointed to by .I endptr is set to .IR nptr , and zero is returned. .PP Definitions for these functions and the type .C wchar_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines how wide character codes are interpreted. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE Upon successful completion, both functions return the converted value, if any. If the correct value would cause overflow, .C wcstol() returns .C LONG_MAX or .C LONG_MIN (according to the sign of the value), and sets .C errno to .SM ERANGE; .C wcstoul() returns .C ULONG_MAX and sets .C errno to .SM ERANGE. .PP For all other errors, zero is returned and .C errno is set to indicate the error. .SH ERRORS .C wcstol() and .C wcstoul() fail and .C errno is set if any of the following conditions are encountered: .RS .TP 15 .SM [EINVAL] The value of .I base is not supported. .TP .SM [ERANGE] The value to be returned would have caused overflow. .RE .SH AUTHOR .CR wcstol() and .CR wcstoul() were developed by OSF and HP. .SH SEE ALSO wctype(3C), wcstod(3C), scanf(3S). .SH STANDARDS CONFORMANCE .CR wcstol() ": XPG4" .PP .CR wcstoul() ": XPG4" .\" .\" index@\f4wcstol()\f1 \- convert wide character string to long integer@@@\f3wcstol(3C)\f1 .\" index@\f4wcstoul()\f1 \- convert wide character string to long integer@@@\f3wcstol(3C)\f1 .\" index@\f1convert wide character string to long integer@@@\f3wcstol(3C)\f1 .\" index@\f1wide character string to long integer, convert@@@\f3wcstol(3C)\f1 .\" index@\f1integer, convert wide character string to long@@@\f3wcstol(3C)\f1 .\" .\" toc@\f3wcstol(3C)\f1:\0\0\f4wcstol()\f1, \f4wcstoul()\f1@@@convert wide character string to integer .\" toc@\f3wcstoul()\f1:\0\0convert wide character string to integer@@@\f1see \f3wcstol(3C)\f1 .\" .\" links@wcstol.3c wcstoul.3c .\" .\" fileset_database@wcstol.3c PROGRAMING-MAN .\" $Header: multibyte.3c,v 72.6 94/11/15 09:55:30 ssa Exp $ .TA m .TH multibyte 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mblen(\|), mbtowc(\|), mbstowcs(\|), wctomb(\|), wcstombs(\|) \- multibyte characters and strings conversions .SH SYNOPSIS .C "#include " .PP .C "int mblen(const char *s, size_t n);" .PP .C "int mbtowc(wchar_t *pwc, const char *s, size_t n);" .PP .C "int wctomb(char *s, wchar_t wchar);" .PP .C "size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);" .PP .C "size_t wcstombs(char *s, const wchar_t *pwcs, size_t n);" .SH DESCRIPTION A multibyte character is composed of one or more bytes that represent a "whole" character in a character encoding. A wide character (type of .CR wchar_t ) is composed of a fixed number of bytes whose code value can represent any character in a character encoding. .TP 12 .C mblen() Determine the number of bytes in the multibyte character pointed to by .IR s . Equivalent to: .IP .C "mbtowc((wchar_t *)0, s, n);" .IP If .I s is a null pointer, .I mblen returns a nonzero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .I mblen returns the number of bytes in the multibyte character if the next .I n or fewer bytes form a valid multibyte character, or return \-1 if they do not form a valid multibyte character. If .I s points to the null character, .I mblen returns 0. .TP .C mbtowc() Determine the number of bytes in the multibyte character pointed to by .IR s , determine the code for the value of type .C wchar_t corresponding to that multibyte character, then store the code in the object pointed to by .IR pwc . The value of the code corresponding to the null character is zero. At most .I n characters are examined, starting at the character pointed to by .IR s . .IP If .I s is a null pointer, .C mbtowc() returns a non-zero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .C mbtowc() returns the number of bytes in the converted multibyte character if the next .I n or fewer bytes form a valid multibyte character, or \-1 if they do not form a valid multibyte character. If .I s points to the null character, .C mbtowc() returns 0. The value returned is never greater than .I n or the value of the .C MB_CUR_MAX macro. .TP .C wctomb() Determine the number of bytes needed to represent the multibyte character corresponding to the code whose value is .I wchar and store the multibyte character representation in the array object pointed to by .IR s . At most .C MB_CUR_MAX characters are stored. .IP If .I s is a null pointer, .C wctomb() returns a nonzero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .C wctomb() returns the number of bytes in the multibyte character corresponding to the value of .IR wchar , or \-1 if the value of .I wchar does not correspond to a valid multibyte character. The value returned is never greater than the value of the .C MB_CUR_MAX macro. .TP .C mbstowcs() Convert a sequence of multibyte characters from the array pointed to by .I s into a sequence of corresponding codes and store these codes into the array pointed to by .IR pwcs , stopping after either .I n codes or a code with value zero (a converted null character) is stored. Each multibyte character is converted as if by a call to .CR mbtowc() . No more than .I n elements are modified in the array pointed to by .IR pwcs . .IP If an invalid multibyte character is encountered, .C mbstowcs() returns (size_t)\|\(mi\|1. Otherwise, .C mbstowcs() returns the number of array elements modified, not including a terminating zero code, if any. The array is not null- or zero-terminated if the value returned is .IR n . If .I pwcs is a null pointer, .C mbstowcs() returns the number of elements required for the wide-character-code array. .TP .C wcstombs() Convert a sequence of codes corresponding to multibyte characters from the array pointed to by .I pwcs into a sequence of multibyte characters and store them into the array pointed to by .IR s , stopping if a multibyte character exceeds the limit of .I n total bytes or if a null character is stored. Each code is converted as if by a call to .CR wctomb() . No more than .I n bytes are modified in the array pointed to by .IR s . .IP If a code is encountered that does not correspond to a valid multibyte character, .C wcstombs() returns (size_t)\|\(mi\|1. Otherwise, .C wcstombs() returns the number of bytes modified, not including a terminating null character, if any. The array is not null- or zero-terminated if the value returned is .IR n . If .I s is a null pointer, .C wcstombs() returns the number of bytes required for the character array. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the behavior of the multibyte character and string functions. .SH ERRORS .CR mblen() , .CR mbstowcs() , .CR mbtowc() , .C wcstombs() and .C wctomb() may fail and .C errno is set if the following condition is encountered: .RS .TP 15 .SM [EILSEQ] An invalid multibyte sequence or wide character code was found. .RE .SH WARNINGS With the exception of .SM ASCII characters, the code values of wide characters (type of .CR wchar_t ) are specific to the effective locale specified by the .C LC_CTYPE environment variable. These values may not be compatible with values obtained by specifying other locales that are supported now, or which may be supported in the future. It is recommended that wide character constants and wide string literals (see the .IR "C Reference Manual" ) not be used, and that wide character code values not be stored in files or devices because future standards may dictate changes in the code value assignments of the wide characters. However, wide character constants and wide string literals corresponding to the characters of the .SM ASCII code set can be safely used since their values are guaranteed to be the same as their .SM ASCII code set values. .SH AUTHOR The multibyte functions in this entry were developed by OSF and HP. .SH SEE ALSO setlocale(3C), wctype(3X). .SH STANDARDS CONFORMANCE .CR mblen() ": AES, SVID3, XPG4, ANSI C" .PP .CR mbstowcs() ": AES, SVID3, XPG4, ANSI C" .PP .CR mbtowc() ": AES, SVID3, XPG4, ANSI C" .PP .CR wcstombs() ": AES, SVID3, XPG4, ANSI C" .PP .CR wctomb() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4multibyte()\f1 \- multibyte characters and strings conversions@@@\f3multibyte(3C)\f1 .\" .\" index@\f4mblen()\f1 \- number of bytes in the multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4mbtowc()\f1 \- number of bytes in the multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4wctomb()\f1 \- number of bytes needed to represent multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4mbstowcs()\f1 \- convert sequence of multibyte characters@@@\f3multibyte(3C)\f1 .\" index@\f4wcstombs()\f1 \- convert sequence of codes corresponding to multibyte characters@@@\f3multibyte(3C)\f1 .\" .\" .\" index@\f1multibyte characters and strings conversions@@@\f3multibyte(3C)\f1 .\" index@\f1characters and strings conversions, multibyte@@@\f3multibyte(3C)\f1 .\" index@\f1strings and characters conversions, multibyte@@@\f3multibyte(3C)\f1 .\" index@\f1conversions, multibyte characters and strings@@@\f3multibyte(3C)\f1 .\" .\" toc@\f3multibyte(3C)\f1:\0\0\f4mblen()\f1, \f4mbtowc()\f1, \f4mbstowcs()\f1, \f4wctomb()\f1,\n \f4wcstombs()\f1@@@multibyte characters and strings conversions .\" toc@\f4mblen()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4mbstowcs()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4mbtowc()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4wctomb()\f1: multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4wctombs()\f1: multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" .\" links@multibyte.3c mblen.3c .\" links@multibyte.3c mbtowc.3c .\" links@multibyte.3c mbstowcs.3c .\" links@multibyte.3c wctomb.3c .\" links@multibyte.3c wcstombs.3c .\" $Header: wcstol.3c,v 72.5 94/11/15 09:57:13 ssa Exp $ .TA w .TH wcstol 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcstol(\|), wcstoul(\|) \- convert wide character string to long integer .SH SYNOPSIS .C "#include " .PP .C "long int wcstol(const wchar_t *nptr, wchar_t **endptr, int base);" .PP .C "unsigned long int wcstoul(const wchar_t *nptr, wchar_t **endptr, int base);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character formatting functions. They parallel the 8-bit character formatting functions defined in .IR strtol (3C). .SH DESCRIPTION .C wcstol() .RC ( wcstoul() ) converts the wide character string pointed to by .I nptr to .C long int .RC ( "unsigned long int" ) representation. The wide character string is scanned up to the first wide character inconsistent with the base. Leading ``white-space'' wide characters (as defined by .C iswspace() in .IR wctype (3C)) are ignored. If no conversion can take place, zero is returned. .PP If .I base is greater than or equal to 2 and less than or equal to 36, it is used as the base for conversion. After an optional leading sign, leading zeros are ignored, and .C 0x or .C 0X is ignored if .I base is 16. .PP If .I base is zero, the wide character string itself determines the base as follows: After an optional leading sign, a leading zero indicates octal conversion; a leading .C 0x or .C 0X hexadecimal conversion. Otherwise, decimal conversion is used. .PP If the value of .I endptr is not .CR "(wchar_t **)NULL" , a pointer to the wide character terminating the scan is returned in the location pointed to by .IR endptr . If no integer can be formed, the location pointed to by .I endptr is set to .IR nptr , and zero is returned. .PP Definitions for these functions and the type .C wchar_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines how wide character codes are interpreted. .SS International Code Set Support Single- and multi-byte character code sets are supported. .SH RETURN VALUE Upon successful completion, both functions return the converted value, if any. If the correct value would cause overflow, .C wcstol() returns .C LONG_MAX or .C LONG_MIN (according to the sign of the value), and sets .C errno to .SM ERANGE; .C wcstoul() returns .C ULONG_MAX and sets .C errno to .SM ERANGE. .PP For all other errors, zero is returned and .C errno is set to indicate the error. .SH ERRORS .C wcstol() and .C wcstoul() fail and .C errno is set if any of the following conditions are encountered: .RS .TP 15 .SM [EINVAL] The value of .I base is not supported. .TP .SM [ERANGE] The value to be returned would have caused overflow. .RE .SH AUTHOR .CR wcstol() and .CR wcstoul() were developed by OSF and HP. .SH SEE ALSO wctype(3C), wcstod(3C), scanf(3S). .SH STANDARDS CONFORMANCE .CR wcstol() ": XPG4" .PP .CR wcstoul() ": XPG4" .\" .\" index@\f4wcstol()\f1 \- convert wide character string to long integer@@@\f3wcstol(3C)\f1 .\" index@\f4wcstoul()\f1 \- convert wide character string to long integer@@@\f3wcstol(3C)\f1 .\" index@\f1convert wide character string to long integer@@@\f3wcstol(3C)\f1 .\" index@\f1wide character string to long integer, convert@@@\f3wcstol(3C)\f1 .\" index@\f1integer, convert wide character string to long@@@\f3wcstol(3C)\f1 .\" .\" toc@\f3wcstol(3C)\f1:\0\0\f4wcstol()\f1, \f4wcstoul()\f1@@@convert wide character string to integer .\" toc@\f3wcstoul()\f1:\0\0convert wide character string to integer@@@\f1see \f3wcstol(3C)\f1 .\" .\" links@wcstol.3c wcstoul.3c .\" .\" fileset_database@wcstol.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: multibyte.3c,v 72.6 94/11/15 09:55:30 ssa Exp $ .TA m .TH multibyte 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mblen(\|), mbtowc(\|), mbstowcs(\|), wctomb(\|), wcstombs(\|) \- multibyte characters and strings conversions .SH SYNOPSIS .C "#include " .PP .C "int mblen(const char *s, size_t n);" .PP .C "int mbtowc(wchar_t *pwc, const char *s, size_t n);" .PP .C "int wctomb(char *s, wchar_t wchar);" .PP .C "size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);" .PP .C "size_t wcstombs(char *s, const wchar_t *pwcs, size_t n);" .SH DESCRIPTION A multibyte character is composed of one or more bytes that represent a "whole" character in a character encoding. A wide character (type of .CR wchar_t ) is composed of a fixed number of bytes whose code value can represent any character in a character encoding. .TP 12 .C mblen() Determine the number of bytes in the multibyte character pointed to by .IR s . Equivalent to: .IP .C "mbtowc((wchar_t *)0, s, n);" .IP If .I s is a null pointer, .I mblen returns a nonzero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .I mblen returns the number of bytes in the multibyte character if the next .I n or fewer bytes form a valid multibyte character, or return \-1 if they do not form a valid multibyte character. If .I s points to the null character, .I mblen returns 0. .TP .C mbtowc() Determine the number of bytes in the multibyte character pointed to by .IR s , determine the code for the value of type .C wchar_t corresponding to that multibyte character, then store the code in the object pointed to by .IR pwc . The value of the code corresponding to the null character is zero. At most .I n characters are examined, starting at the character pointed to by .IR s . .IP If .I s is a null pointer, .C mbtowc() returns a non-zero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .C mbtowc() returns the number of bytes in the converted multibyte character if the next .I n or fewer bytes form a valid multibyte character, or \-1 if they do not form a valid multibyte character. If .I s points to the null character, .C mbtowc() returns 0. The value returned is never greater than .I n or the value of the .C MB_CUR_MAX macro. .TP .C wctomb() Determine the number of bytes needed to represent the multibyte character corresponding to the code whose value is .I wchar and store the multibyte character representation in the array object pointed to by .IR s . At most .C MB_CUR_MAX characters are stored. .IP If .I s is a null pointer, .C wctomb() returns a nonzero or zero value, depending on whether the multibyte character encodings do or do not have state-dependent encodings, respectively. Since no character encodings currently supported by .SM HP-UX are state-dependent, zero is always returned in this case. However, for maximum portability to other systems, application programs should not depend on this. .IP If .I s is not a null pointer, .C wctomb() returns the number of bytes in the multibyte character corresponding to the value of .IR wchar , or \-1 if the value of .I wchar does not correspond to a valid multibyte character. The value returned is never greater than the value of the .C MB_CUR_MAX macro. .TP .C mbstowcs() Convert a sequence of multibyte characters from the array pointed to by .I s into a sequence of corresponding codes and store these codes into the array pointed to by .IR pwcs , stopping after either .I n codes or a code with value zero (a converted null character) is stored. Each multibyte character is converted as if by a call to .CR mbtowc() . No more than .I n elements are modified in the array pointed to by .IR pwcs . .IP If an invalid multibyte character is encountered, .C mbstowcs() returns (size_t)\|\(mi\|1. Otherwise, .C mbstowcs() returns the number of array elements modified, not including a terminating zero code, if any. The array is not null- or zero-terminated if the value returned is .IR n . If .I pwcs is a null pointer, .C mbstowcs() returns the number of elements required for the wide-character-code array. .TP .C wcstombs() Convert a sequence of codes corresponding to multibyte characters from the array pointed to by .I pwcs into a sequence of multibyte characters and store them into the array pointed to by .IR s , stopping if a multibyte character exceeds the limit of .I n total bytes or if a null character is stored. Each code is converted as if by a call to .CR wctomb() . No more than .I n bytes are modified in the array pointed to by .IR s . .IP If a code is encountered that does not correspond to a valid multibyte character, .C wcstombs() returns (size_t)\|\(mi\|1. Otherwise, .C wcstombs() returns the number of bytes modified, not including a terminating null character, if any. The array is not null- or zero-terminated if the value returned is .IR n . If .I s is a null pointer, .C wcstombs() returns the number of bytes required for the character array. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the behavior of the multibyte character and string functions. .SH ERRORS .CR mblen() , .CR mbstowcs() , .CR mbtowc() , .C wcstombs() and .C wctomb() may fail and .C errno is set if the following condition is encountered: .RS .TP 15 .SM [EILSEQ] An invalid multibyte sequence or wide character code was found. .RE .SH WARNINGS With the exception of .SM ASCII characters, the code values of wide characters (type of .CR wchar_t ) are specific to the effective locale specified by the .C LC_CTYPE environment variable. These values may not be compatible with values obtained by specifying other locales that are supported now, or which may be supported in the future. It is recommended that wide character constants and wide string literals (see the .IR "C Reference Manual" ) not be used, and that wide character code values not be stored in files or devices because future standards may dictate changes in the code value assignments of the wide characters. However, wide character constants and wide string literals corresponding to the characters of the .SM ASCII code set can be safely used since their values are guaranteed to be the same as their .SM ASCII code set values. .SH AUTHOR The multibyte functions in this entry were developed by OSF and HP. .SH SEE ALSO setlocale(3C), wctype(3X). .SH STANDARDS CONFORMANCE .CR mblen() ": AES, SVID3, XPG4, ANSI C" .PP .CR mbstowcs() ": AES, SVID3, XPG4, ANSI C" .PP .CR mbtowc() ": AES, SVID3, XPG4, ANSI C" .PP .CR wcstombs() ": AES, SVID3, XPG4, ANSI C" .PP .CR wctomb() ": AES, SVID3, XPG4, ANSI C" .\" .\" index@\f4multibyte()\f1 \- multibyte characters and strings conversions@@@\f3multibyte(3C)\f1 .\" .\" index@\f4mblen()\f1 \- number of bytes in the multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4mbtowc()\f1 \- number of bytes in the multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4wctomb()\f1 \- number of bytes needed to represent multibyte character@@@\f3multibyte(3C)\f1 .\" index@\f4mbstowcs()\f1 \- convert sequence of multibyte characters@@@\f3multibyte(3C)\f1 .\" index@\f4wcstombs()\f1 \- convert sequence of codes corresponding to multibyte characters@@@\f3multibyte(3C)\f1 .\" .\" .\" index@\f1multibyte characters and strings conversions@@@\f3multibyte(3C)\f1 .\" index@\f1characters and strings conversions, multibyte@@@\f3multibyte(3C)\f1 .\" index@\f1strings and characters conversions, multibyte@@@\f3multibyte(3C)\f1 .\" index@\f1conversions, multibyte characters and strings@@@\f3multibyte(3C)\f1 .\" .\" toc@\f3multibyte(3C)\f1:\0\0\f4mblen()\f1, \f4mbtowc()\f1, \f4mbstowcs()\f1, \f4wctomb()\f1,\n \f4wcstombs()\f1@@@multibyte characters and strings conversions .\" toc@\f4mblen()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4mbstowcs()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4mbtowc()\f1:\0\0multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4wctomb()\f1: multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" toc@\f4wctombs()\f1: multibyte characters and strings conversions@@@\f1see \f3multibyte(3C)\f1 .\" .\" links@multibyte.3c mblen.3c .\" links@multibyte.3c mbtowc.3c .\" links@multibyte.3c mbstowcs.3c .\" links@multibyte.3c wctomb.3c .\" links@multibyte.3c wcstombs.3c .\" $Header: wctype.3c,v 72.7 94/11/28 08:38:08 ssa Exp $ .TA w .TH wctype 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME iswalpha(\|), iswupper(\|), iswlower(\|), iswdigit(\|), iswxdigit(\|), iswalnum(\|), iswspace(\|), iswpunct(\|), iswprint(\|), iswgraph(\|), iswcntrl(\|), wctype(\|), iswctype(\|) \- classify wide characters .SH SYNOPSIS .nf .C "#include " .PP .C "wctype_t wctype(const char *charclass);" .C "int iswctype(wint_t wc, wctype_t prop);" .C "int iswalnum(wint_t wc);" .C "int iswalpha(wint_t wc);" .C "int iswcntrl(wint_t wc);" .C "int iswdigit(wint_t wc);" .C "int iswgraph(wint_t wc);" .C "int iswlower(wint_t wc);" .C "int iswprint(wint_t wc);" .C "int iswpunct(wint_t wc);" .C "int iswspace(wint_t wc);" .C "int iswupper(wint_t wc);" .C "int iswxdigit(wint_t wc);" .fi .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character classification functions. They parallel the 8-bit character classification functions defined in .IR ctype(3C) . .SH DESCRIPTION These functions classify wide character values according to the rules of the coded character set identified by the last successful call to .C setlocale() (see .IR setlocale (3C)). .PP If .C setlocale() has not been called successfully, characters are classified according to the rules of the default .SM ASCII 7-bit coded character set (see .IR setlocale (3C)). .PP Each of the classification functions is a predicate that returns non-zero for true, zero for false. .PP .C wctype() is defined for valid character class names as defined in the current locale. .I charclass is a string identifying a generic character class for which codeset-specific type information is required. The following class names are defined in all locales: .CR alnum , .CR alpha , .CR blank , .CR cntrl , .CR digit , .CR graph , .CR lower , .CR print , .CR punct , .CR space , .CR upper , and .CR xdigit . User-defined class names may be specified if supported by the current locale as defined by .C setlocale() (see .IR setlocale (3C)). .C wctype() returns a value of type .C wctype_t that can be used in a subsequent call to .CR iswctype() , or .C (wctype_t)-1 if .I charclass is not valid in the current locale. .PP The classification functions return non-zero under the following circumstances, and zero otherwise: .RS .TP 20 .CI iswctype( wc , prop ) .I wc has the property defined by .IR prop . .TP .CI iswalpha( wc ) .I wc is a letter. .TP .CI iswupper( wc ) .I wc is an uppercase letter. .TP .CI iswlower( wc ) .I wc is a lowercase letter. .TP .CI iswdigit( wc ) .I wc is a decimal digit (in .SM ASCII\s0: characters [0-9]). .TP .CI iswxdigit( wc ) .I wc is a hexadecimal digit (in .SM ASCII\s0: characters [0-9], [A-F] or [a-f]). .TP .CI iswalnum( wc ) .I wc is an alphanumeric (letters or digits). .TP .CI iswspace( wc ) .I wc is a character that creates "white space" in displayed text (in .SM ASCII\s0: space, tab, carriage return, new-line, vertical tab, and form-feed). .TP .CI iswpunct( wc ) .I wc is a punctuation character (in .SM ASCII\s0: any printing character except the space character (040), digits, letters). .TP .CI iswprint( wc ) .I wc is a printing character. .TP .CI iswgraph( wc ) .I wc is a visible character (in .SM ASCII\s0: printing characters, excluding the space character (040)). .TP .CI iswcntrl( wc ) .I wc is a control character (in .SM ASCII\s0: character codes less than 040 and the delete character (0177)). .RE .PP If the argument to any of these functions is outside the domain of the function, the result is 0 (false). .PP Definitions for these functions and the types .CR wint_t , .CR wchar_t , and .C wctype_t are provided in the .RC < wchar.h > header. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_CTYPE category determines the classification of character type. .SS International Code Set Support Single-byte and multi-byte character code sets are supported. .SH AUTHOR .C wctype() was developed by IBM, OSF, and HP. .SH SEE ALSO ctype(3C), multibyte(3C), setlocale(3C), ascii(5). .SH STANDARDS CONFORMANCE .CR wctype() ": XPG4" .PP .CR iswalnum() ": XPG4" .PP .CR iswalpha() ": XPG4" .PP .CR iswcntrl() ": XPG4" .PP .CR iswctype() ": XPG4" .PP .CR iswdigit() ": XPG4" .PP .CR iswgraph() ": XPG4" .PP .CR iswlower() ": XPG4" .PP .CR iswprint() ": XPG4" .PP .CR iswpunct() ": XPG4" .PP .CR iswspace() ": XPG4" .PP .CR iswupper() ": XPG4" .PP .CR iswxdigit() ": XPG4" .\" .\" index@\f4wctype()\f1 \- classify characters according to type@@@\f3wctype(3C)\f1 .\" .\" index@\f4iswalpha\f1 \- character is alpha@@@\f3wctype(3C)\f1 .\" index@\f4iswupper\f1 \- character is uppercase@@@\f3wctype(3C)\f1 .\" index@\f4iswlower\f1 \- character is lowercase@@@\f3wctype(3C)\f1 .\" index@\f4iswdigit\f1 \- character is a digit@@@\f3wctype(3C)\f1 .\" index@\f4iswxdigit\f1 \- character is a hexadecimal digit@@@\f3wctype(3C)\f1 .\" index@\f4iswalnum\f1 \- character is alphanumeric@@@\f3wctype(3C)\f1 .\" index@\f4iswspace\f1 \- character is whitespace@@@\f3wctype(3C)\f1 .\" index@\f4iswpunct\f1 \- character is punctuation@@@\f3wctype(3C)\f1 .\" index@\f4iswprint\f1 \- character is a printing character@@@\f3wctype(3C)\f1 .\" index@\f4iswgraph\f1 \- character is a visible character@@@\f3wctype(3C)\f1 .\" index@\f4iswcntrl\f1 \- character is a control character@@@\f3wctype(3C)\f1 .\" index@\f4ISASCII\f1 \- character is 7-bit \s-1ASCII\s+1 code@@@\f3wctype(3C)\f1 .\" index@\f1classify characters according to type@@@\f3wctype(3C)\f1 .\" index@\f1characters, classify according to type@@@\f3wctype(3C)\f1 .\" index@\f1type, classify characters according to@@@\f3wctype(3C)\f1 .\" .\" toc@\f3wctype(3C)\f1:\0\0\f4iswalpha\f1, \f4iswupper\f1, \f4iswlower\f1, \f4iswdigit\f1, \f4iswxdigit\f1, \f4iswalnum\f1, \f4iswspace\f1,\n\f4iswpunct\f1, \f4iswprint\f1, \f4iswgraph\f1, \f4iswcntrl\f1@@@classify wide characters .\" toc@\f4iswalpha\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswupper\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswlower\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswxdigit\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswalnum\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswspace\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswpunct\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswprint\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswgraph\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" toc@\f4iswcntrl\f1:\0\0classify wide characters@@@see \f3wctype(3C)\f1 .\" .\" links@wctype.3c iswctype.3c .\" links@wctype.3c iswalpha.3c .\" links@wctype.3c iswupper.3c .\" links@wctype.3c iswlower.3c .\" links@wctype.3c iswdigit.3c .\" links@wctype.3c iswxdigit.3c .\" links@wctype.3c iswalnum.3c .\" links@wctype.3c iswspace.3c .\" links@wctype.3c iswpunct.3c .\" links@wctype.3c iswprint.3c .\" links@wctype.3c iswgraph.3c .\" links@wctype.3c iswcntrl.3c .\" .\" fileset_database@wctype.3c PROGRAMING-MAN .\" $Header: syncok.3x,v 76.2 95/08/01 14:50:38 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH syncok 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME syncok, wcursyncup, wsyncdown, wsyncup \(em synchronise a window with its parents or children .SH SYNOPSIS .C "#include " .P .C "int syncok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "void wcursyncup(WINDOW *\f2win\fP);" .P .C "void wsyncdown(WINDOW *\f2win\fP);" .P .C "void wsyncup(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn syncok function determines whether all ancestors of the specified window are implicitly touched whenever there is a change in the window. If \f2bf\f1 is TRUE, such implicit touching occurs. If \f2bf\f1 is FALSE, such implicit touching does not occur. The initial state is FALSE. .P The .Fn wcursyncup function updates the current cursor position of the ancestors of \f2win\f1 to reflect the current cursor position of \f2win\f1. .P The .Fn wsyncdown function touches \f2win\f1 if any ancestor window has been touched. .P The .Fn wsyncup function unconditionally touches all ancestors of \f2win\f1. .SH "RETURN VALUE" Upon successful completion, .Fn syncok returns OK. Otherwise, it returns ERR. .P The other functions do not return a value. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Applications seldom call .Fn wsyncdown because it is called by all refresh operations. .SH "SEE ALSO" doupdate(), is_linetouched(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3syncok(3X)\f1:\0\0\f4syncok()\f1, \f4wcursyncup()\f1, \f4wsyncdown()\f1, \f4wsyncup()\f1\n@@@synchronise a window with its parents or children .\" toc@\f4wcursyncup()\f1: synchronise a window with its parents or children@@@see \f3syncok(3X)\f1 .\" toc@\f4wsyncdown()\f1: synchronise a window with its parents or children@@@see \f3syncok(3X)\f1 .\" toc@\f4wsyncup()\f1: synchronise a window with its parents or children@@@see \f3syncok(3X)\f1 .\" .\" index@\f4syncok()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f4wcursyncup()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f4wsyncup()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f4wsyncdown()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f1synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f1window, synchronise with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f1parents, synchronise a window with@@@\f3syncok(3X)\f1 .\" index@\f1children, synchronise a window with@@@\f3syncok(3X)\f1 .\" .\" links@syncok.3x wcursyncup.3x .\" links@syncok.3x wsyncup.3x .\" links@syncok.3x wsyncdown.3x .\" .\" fileset_database@syncok.3x CURS-ENG-A-MAN .\" $Header: wcstring.3c,v 72.7 94/11/21 08:33:18 ssa Exp $ .TA w .TH wcstring 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wcscat(\|), wcsncat(\|), wcscmp(\|), wcsncmp(\|), wcscpy(\|), wcsncpy(\|), wcslen(\|), wcschr(\|), wcsrchr(\|), wcspbrk(\|), wcsspn(\|), wcscspn(\|), wcswcs(\|), wcstok(\|), wcstok_r(\), wcscoll(\|), wcwidth(\|), wcswidth(\|) \- wide character string operations .SH SYNOPSIS .C "#include " .PP .C "wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "int wcscmp(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);" .PP .C "size_t wcslen(const wchar_t *ws);" .PP .C "wchar_t *wcschr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcsrchr(const wchar_t *ws, wint_t wc);" .PP .C "wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2);" .PP .C "wchar_t *wcstok_r(wchar_t *ws1, const wchar_t *ws2, wchar_t **wlast);" .PP .C "int wcscoll(const wchar_t *ws1, const wchar_t *ws2);" .PP .C "int wcwidth(wint_t wc);" .PP .C "int wcswidth(const wchar_t *ws, size_t n);" .SS Remarks: These functions are compliant with the .SM XPG4 Worldwide Portability Interface wide-character string handling functions. They parallel the 8 bit string functions defined in .IR string(3C) . .SH DESCRIPTION The arguments .IR ws1 , .IR ws2 , and .I ws point to wide character strings (arrays of type .C wchar_t terminated by a null value). .PP .C wcscat() appends a copy of wide string .I ws2 to the end of wide string .IR ws1 . .C wcsncat() appends a maximum of .I n characters; fewer if .I ws2 is shorter than .I n characters. Each returns a pointer to the null-terminated result (the value of .IR ws1 ). .PP .C wcscmp() compares its arguments and returns an integer less than, equal to, or greater than zero, depending on whether .I ws1 is lexicographically less than, equal to, or greater than .IR ws2 . The comparison of corresponding wide characters is done by comparing numeric values of the wide character codes. Null pointer values for .I ws1 and .I ws2 are treated the same as pointers to empty wide strings. .C wcsncmp() makes the same comparison but examines a maximum of .I n characters .RI ( n less than or equal to zero yields equality). .PP .C wcscpy() copies wide string .I ws2 to .IR ws1 , stopping after the null value has been copied. .C wcsncpy() copies up to .I n characters from .IR ws2 , adding null values to .I ws1 if necessary, until a total of .I n have been copied. The result is not null-terminated if the length of .I ws2 is .I n or more. Each function returns .IR ws1 . Note that .C wcsncpy() should not be used to copy an arbitrary structure. If that structure contains sizeof(wchar_t) consecutive null bytes, .C wcsncpy() may not copy the entire structure. Use the .C memcpy() function (see .IR memory (3C)) to copy arbitrary binary data. .PP .C wcslen() returns the number of wide characters in .IR ws , not including the terminating null wide character. .PP .C wcschr() .RC ( wcsrchr() ) returns a pointer to the first (last) occurrence of wide character .I wc in wide string .IR ws , or a null pointer if .I wc does not occur in the wide string. The null wide character terminating a wide string is considered to be part of the wide string. .PP .C wcspbrk() returns a pointer to the first occurrence in wide string .I ws1 of any wide character from wide string .IR ws2 , or a null pointer if no wide character from .I ws2 exists in .IR ws1 . .PP .C wcsspn() .RC ( wcscspn() ) returns the length of the maximum initial segment of wide string .IR ws1 , which consists entirely of wide characters from (not from) wide string .IR ws2 . .PP .C wcswcs() returns a pointer to the first occurrence of wide string .I ws2 in wide string .IR ws1 , or a null pointer if .I ws2 does not occur in the wide string. If .I ws2 points to a wide string of zero length, .C wcswcs() returns .IR ws1 . .PP .C wcstok() considers the wide string .I ws1 to consist of a sequence of zero or more text tokens separated by spans of one or more wide characters from the separator wide string .IR ws2 . The first call (with a non-null pointer .I ws1 specified) returns a pointer to the first wide character of the first token, and writes a null wide character into .I ws1 immediately following the returned token. The function keeps track of its position in the wide string .I ws1 between separate calls, so that subsequent calls made with the first argument a null pointer work through the wide string immediately following that token. In this way subsequent calls work through the wide string .I ws1 until no tokens remain. The separator wide string .I ws2 can be different from call to call. When no token remains in .IR ws1 , a null pointer is returned. .PP .C wcstok_r() is identical to .CR wcstok() , except that it expects to be passed the address of a wide-character string pointer as the third argument. It will use this argument to keep track of the current position in the string being searched. It returns a pointer to the current token in the string or a .C NULL value if there are no more tokens. .PP .C wcscoll() returns an integer greater than, equal to, or less than zero, according to whether the wide string pointed to by .I ws1 is greater than, equal to, or less than the wide string pointed to by .IR ws2 . The comparison is based on wide strings interpreted as appropriate to the program's locale (see Locale below). In the ``C'' locale .C wcscoll() works like .CR wcscmp() . .PP .C wcwidth() returns the number of column positions required for the wide character .IR wc , or 0 if .I wc is a null wide character, or -1 if .I wc is an unprintable wide character. .PP .C wcswidth() returns the number of column positions required for .I n wide characters (or fewer than .I n wide characters if a null wide character is encountered before .I n wide characters are exhausted) in the wide string pointed to by .IR ws . .C wcswidth() returns 0 if .I ws points to a null wide character, or -1 if .I ws contains an unprintable wide character. .PP Definitions for these functions and the type .C wchar_t are provided in header file .RC < wchar.h >. .SH EXTERNAL INFLUENCES .SS Locale The .C LC_COLLATE category determines the collation ordering used by the .C wcscoll() function. See .IR nlsinfo (1) to determine the collation used for a particular locale. .PP The .C LC_CTYPE category determines how widths are calculated by the .C wcwidth() and .C wcswidth() functions. .SH EXAMPLE The following sample piece of code finds the tokens, separated by blanks, that are in the string .I s (assuming that there are at most .B MAXTOK tokens): .PP .RS .nf .ift .ft 4 .ifn .ft 3 .ps +1 int i = 0; wchar_t *ws, *wlast, *wtok[MAXTOK]; wtok[0] = wcstok_r(ws, L" ", &wlast); while (wtok[++i] = wcstok_r(NULL, L" ", &wlast)); .ft .ps .fi .RE .SH WARNINGS The functions .CR wcscat() , .CR wcsncat() , .CR wcscpy() , .CR wcsncpy() , .CR wcstok() , and .C wcstok_r() alter the contents of the array to which .I ws1 points. They do not check for overflow of the array. .PP Null pointers for destination wide strings cause undefined behavior. .PP Wide character movement is performed differently in different implementations, so copying that involves overlapping source and destination wide strings may yield unexpected results. .PP For the .C wcscoll() function, the results are undefined if the languages specified by the .C LC_COLLATE and .C LC_CTYPE categories use different code sets. .PP .C wcstok() is unsafe in multi-thread applications. .C wcstok_r() is safe for multi-thread applications and should be used instead. .SH AUTHOR .C wcstring functions were developed by OSF and HP. .SH SEE ALSO nlsinfo(1), wconv(3C), memory(3C), multibyte(3C), setlocale(3C), string(3C), hpnls(5). .SH STANDARDS CONFORMANCE .CR wcscat() ": XPG4" .PP .CR wcschr() ": XPG4" .PP .CR wcscmp() ": XPG4" .PP .CR wcscoll() ": XPG4" .PP .CR wcscpy() ": XPG4" .PP .CR wcscspn() ": XPG4" .PP .CR wcslen() ": XPG4" .PP .CR wcsncat() ": XPG4" .PP .CR wcsncmp() ": XPG4" .PP .CR wcsncpy() ": XPG4" .PP .CR wcspbrk() ": XPG4" .PP .CR wcsrchr() ": XPG4" .PP .CR wcsspn() ": XPG4" .PP .CR wcstok() ": XPG4" .PP .CR wcswcs() ": XPG4" .PP .CR wcswidth() ": XPG4" .PP .CR wcwidth() ": XPG4" .\" .\" index@\f4wcscat\f1, \f4wcsncat\f1 \- append wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscmp\f1, \f4wcsncmp\f1 \- compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@\f4wcscpy\f1, \f4wcsncpy\f1 \- copy wide string 2 to wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcslen\f1 \- determine length of a wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcschr\f1, \f4wcsrchr\f1 \- get pointer to wide character in wide string@@@\f3wcstring(3C)\f1 .\" index@\f4wcspbrk\f1 \- find occurrence of wide character from wide string 2 in wide string 1@@@\f3wcstring(3C)\f1 .\" index@\f4wcscspn\f1, \f4wcsspn\f1 \- find length of matching wide substrings@@@\f3wcstring(3C)\f1 .\" index@\f4wcswcs\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcstok_r\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@\f4wcscoll\f1 \- process wide string of text tokens@@@\f3wcstring(3C)\f1 .\" index@wide character string operations@@@\f3wcstring(3C)\f1 .\" index@string operations, wide character@@@\f3wcstring(3C)\f1 .\" index@wide strings, concatenate two@@@\f3wcstring(3C)\f1 .\" index@length of wide string, find@@@\f3wcstring(3C)\f1 .\" index@compare two wide strings@@@\f3wcstring(3C)\f1 .\" index@concatenate two wide strings@@@\f3wcstring(3C)\f1 .\" .\" toc@\f3wcstring(3C)\f1:\0\0\f4wcscat\f1, \f4wcsncat\f1, \f4wcscmp\f1, \f4wcsncmp\f1, \f4wcscpy\f1, \f4wcsncpy\f1, \f4wcslen\f1, \f4wcschr\f1,\n\f4wcsrchr\f1, \f4wcspbrk\f1, \f4wcsspn\f1, \f4wcscspn\f1, \f4wcstok\f1, \f4wcstok_r\f1,\n\f4nl_wcscmp\f1, \f4nl_wcsncmp\f1@@@wide character string operations .\" toc@\f4wcscat\f1, \f4wcsncat\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscmp\f1, \f4wcsncmp\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscpy\f1, \f4wcsncpy\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcslen\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcschr\f1, \f4wcsrchr\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcspbrk\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcsspn\f1, \f4wcscspn\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswcs\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcstok_r\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcscoll\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcwidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" toc@\f4wcswidth\f1:\0\0wide character string operations@@@see \f3wcstring(3C)\f1 .\" .\" links@wcstring.3c wcscat.3c .\" links@wcstring.3c wcsncat.3c .\" links@wcstring.3c wcscmp.3c .\" links@wcstring.3c wcsncmp.3c .\" links@wcstring.3c wcscpy.3c .\" links@wcstring.3c wcsncpy.3c .\" links@wcstring.3c wcslen.3c .\" links@wcstring.3c wcschr.3c .\" links@wcstring.3c wcsrchr.3c .\" links@wcstring.3c wcspbrk.3c .\" links@wcstring.3c wcsspn.3c .\" links@wcstring.3c wcscspn.3c .\" links@wcstring.3c wcswcs.3c .\" links@wcstring.3c wcstok.3c .\" links@wcstring.3c wcstok_r.3c .\" links@wcstring.3c wcscoll.3c .\" links@wcstring.3c wcwidth.3c .\" links@wcstring.3c wcswidth.3c .\" .\" fileset_database@wcstring.3c PROGRAMING-MAN .\" $Header: delch.3x,v 76.2 95/08/01 15:04:04 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH delch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME delch, mvdelch, mvwdelch, wdelch \(em delete a character from a window. .SH SYNOPSIS .C "#include " .P .C "int delch(void);" .P .C "int mvdelch(int \f2y\fP, int \f2x\fP);" .P .C "int mvwdelch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "int wdelch(WINDOW *\f2win\fP);" .SH DESCRIPTION These functions delete the character at the current or specified position in the current or specified window. This function does not change the cursor position. .SS "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SS ERRORS No errors are defined. .SS "SEE ALSO" . .SS "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn delch function is explicitly declared as \f3void\f1. .\" .\" toc@\f3delch(3x)\f1:\0\0\f4delch()\f1, \f4mvdelch()\f1, \f4mvwdelch()\f1, \f4wdelch()\f1@@@delete character from a window .\" .\" toc@\f3mvdelch()\f1:\0\0delete character from a window@@@\f1see\f3delch(3x)\f1 .\" toc@\f3mvwdelch()\f1:\0\0delete character from a window@@@\f1see\f3delch(3x)\f1 .\" toc@\f3wdelch()\f1:\0\0delete character from a window@@@\f1see\f3delch(3x)\f1 .\" .\" index@\f4delch()\f1, \f4mvdelch()\f1, \f4mvwdelch()\f1, \f4wdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" index@\f4mvdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" index@\f4mvwdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" index@\f4wdelch()\f1 \- delete character from a window@@@\f3delch(3x)\f1 .\" .\" links@delch.3x mvdelch.3x .\" links@delch.3x mvwdelch.3x .\" links@delch.3x wdelch.3x .\" .\" fileset_database@delch.3x CURS-ENG-A-MAN .\" .\" $Header: deleteln.3x,v 76.2 95/08/01 15:07:08 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH deleteln 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME deleteln, wdeleteln \(em delete lines in a window .SH SYNOPSIS .C "#include " .P .C "int deleteln(void);" .P .C "int wdeleteln(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn deleteln and .Fn wdeleteln functions delete the line containing the cursor in the current or specified window and move all lines following the current line one line toward the cursor. The last line of the window is cleared. The cursor position does not change. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" insdelln(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SS "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn deleteln function is explicitly declared as \f3void\f1. .\" .\" toc@\f3deleteln(3x)\f1:\0\0\f4deleteln()\f1, \f4wdeleteln()\f1@@@delete lines in window .\" .\" toc@\f3deleteln()\f1:\0\0delete lines in window@@@\f1see \f3deleteln(3x)\f1 .\" toc@\f3wdeleteln()\f1:\0\0delete lines in window@@@\f1see \f3deleteln(3x)\f1 .\" .\" index@\f4deleteln()\f1, \f4wdeleteln()\f1 \- delete lines in window@@@\f3deleteln(3x)\f1 .\" index@\f4wdeleteln()\f1, \f4deleteln()\f1 \- delete lines in window@@@\f3deleteln(3x)\f1 .\" .\" links@deleteln.3x wdeleteln.3x .\" .\" fileset_database@deleteln.3x CURS-ENG-A-MAN .\" .\" $Header: echo_wchar.3x,v 76.2 95/07/31 17:43:21 ssa Exp $ .TA e .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH echo_wchar 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME echo_wchar, wecho_wchar \(em write a complex character and immediately refresh the window .SH SYNOPSIS .C "#include " .P .C "int echo_wchar(cchar_t *const \f2wch\fP);" .P .C "int wecho_wchar(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .SH DESCRIPTION .P The .Fn echo_wchar function is equivalent to calling .Fn add_wch and then calling .CR refresh() . .P The .Fn wecho_wchar function is equivalent to calling .Fn wadd_wch and then calling .CR wrefresh() . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" addch(), add_wch(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3echo_wchar(3X)\f1:\0\0\f4echo_wchar()\f1, \f4wecho_wchar()\f1\n@@@write a complex character and immediately refresh the window .\" toc@\f4wecho_wchar()\f1: write a complex character and immediately refresh the window@@@see \f3echo_wchar(3X)\f1 .\" .\" index@\f4echo_wchar()\f1 \- write a complex character and immediately refresh the window@@@\f3echo_wchar(3X)\f1 .\" index@\f4wecho_wchar()\f1 \- write a complex character and immediately refresh the window@@@\f3echo_wchar(3X)\f1 .\" index@\f1write a complex character and immediately refresh the window@@@\f3echo_wchar(3X)\f1 .\" index@\f1window, refresh immediately after writing a complex character@@@\f3echo_wchar(3X)\f1 .\" index@\f1complex character, write and immediately refresh the window@@@\f3echo_wchar(3X)\f1 .\" index@\f1refresh the window immediately after writing a complex character@@@\f3echo_wchar(3X)\f1 .\" .\" links@echo_wchar.3x wecho_wchar.3x .\" .\" fileset_database@echo_wchar.3x CURS-ENG-A-MAN .\" $Header: echochar.3x,v 76.2 95/07/31 17:44:25 ssa Exp $ .TA e .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH echochar 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME echochar, wechochar \(em echo single-byte character and rendition to a window and refresh .SH SYNOPSIS .C "#include " .P .C "int echochar(const chtype \f2ch\fP);" .P .C "int wechochar(WINDOW *\f2win\fP, const chtype \f2ch\fP);" .SH DESCRIPTION The .Fn echochar function is equivalent to a call to .Fn addch followed by a call to .CR refresh() . .P The .Fn wechochar function is equivalent to a call to .Fn waddch followed by a call to .CR wrefresh() . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" addch(), doupdate(), echo_wchar(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3echochar(3X)\f1:\0\0\f4echochar()\f1, \f4wechochar()\f1@@@echo single-byte character and rendition to a window and refresh .\" toc@\f4wechochar()\f1: echo single-byte character and rendition to a window and refresh@@@see \f3echochar(3X)\f1 .\" .\" index@\f4echochar()\f1 \- echo single-byte character and rendition to a window and refresh@@@\f3echochar(3X)\f1 .\" index@\f4wechochar()\f1 \- echo single-byte character and rendition to a window and refresh@@@\f3echochar(3X)\f1 .\" index@\f1echo single-byte character and rendition to a window and refresh@@@\f3echochar(3X)\f1 .\" index@\f1single-byte character and rendition, echo to a window and refresh@@@\f3echochar(3X)\f1 .\" index@\f1window refreshed after echo single-byte character and rendition@@@\f3echochar(3X)\f1 .\" .\" links@echochar.3x wechochar.3x .\" .\" fileset_database@echochar.3x CURS-ENG-A-MAN .\" $Header: clear.3x,v 76.2 95/07/31 17:24:33 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH clear 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clear, erase, wclear, werase \(em clear a window .SH SYNOPSIS .C "#include " .P .C "int clear(void);" .P .C "int erase(void);" .P .C "int wclear(WINDOW *\f2win\fP);" .P .C "int werase(WINDOW *\f2win\fP);" .SH DESCRIPTION The .CR clear() , .CR erase() , .Fn wclear and .Fn werase functions clear every position in the current or specified window. .P The .Fn clear and .Fn wclear functions also achieve the same effect as calling .Fn clearok , so that the window is cleared completely on the next call to .Fn wrefresh for the window and is redrawn in its entirety. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" clearok(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .Fn erase and .Fn werase functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The argument list for the .Fn clear and .Fn erase functions is explicitly declared as \f3void\f1. .\" .\" toc@\f3clear(3X)\f1:\0\0\f4clear()\f1, \f4erase()\f1, \f4wclear()\f1, \f4werase()\f1@@@clear a window .\" toc@\f4erase()\f1: clear a window@@@see \f3clear(3X)\f1 .\" toc@\f4werase()\f1: clear a window@@@see \f3clear(3X)\f1 .\" toc@\f4wclear()\f1: clear a window@@@see \f3clear(3X)\f1 .\" .\" index@\f4clear()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f4wclear()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f4erase()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f4werase()\f1 \- clear a window@@@\f3clear(3X)\f1 .\" index@\f1clear a window@@@\f3clear(3X)\f1 .\" index@\f1window, clear@@@\f3clear(3X)\f1 .\" .\" links@clear.3x wclear.3x .\" links@clear.3x erase.3x .\" links@clear.3x werase.3x .\" .\" fileset_database@clear.3x CURS-ENG-A-MAN .\" $Header: get_wch.3x,v 76.2 95/08/01 10:38:24 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH get_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME get_wch, mvget_wch, mvwget_wch, wget_wch \(em get a wide character from a terminal .SH SYNOPSIS .C "#include " .P .C "int get_wch(wint_t *\f2ch\fP);" .P .C "int mvget_wch(int \f2y\fP, int \f2x\fP, wint_t *\f2ch\fP);" .P .C "int mvwget_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2ch\fP);" .P .C "int wget_wch(WINDOW *\f2win\fP, wint_t *\f2ch\fP);" .SH DESCRIPTION These functions read a character from the terminal associated with the current or specified window. If .Fn keypad is enabled, these functions respond to the pressing of a function key by setting the object pointed to by .I ch to the corresponding KEY_ value defined in .Hd curses.h and returning KEY_CODE_YES. .P Processing of terminal input is subject to the general rules described in \f3Input Processing\f1 in curses_intro. .P If echoing is enabled, then the character is echoed as though it were provided as an input argument to .CR ins_wch() , except for the following characters: .PP .TS tab(@); lw(2.00i)@lw(3i). T{ , and the current erase character: T}@T{ The input is interpreted as specified in .CR specialchars and then the character at the resulting cursor position is deleted as though .Fn delch were called, except that if the cursor was originally in the first column of the line, then the user is alerted as though .Fn beep were called. T} .P Function keys@T{ The user is alerted as though .Fn beep were called. Information concerning the function keys is not returned to the caller. T} .TE .P If the current or specified window is not a pad, and it has been moved or modified since the last refresh operation, then it will be refreshed before another character is read. .SH "RETURN VALUE" When these functions successfully report the pressing of a function key, they return KEY_CODE_YES. When they successfully report a wide character, they return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Applications should not define the escape key by itself as a single-character function. .P When using these functions, .Fn nocbreak mode and .Fn echo mode should not be used at the same time. Depending on the state of the terminal when each character is typed, the application may produce undesirable results. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, beep(), cbreak(), ins_wch(), keypad(), move(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ). .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3get_wch(3X)\f1:\0\0\f4get_wch()\f1, \f4mvget_wch()\f1, \f4mvwget_wch()\f1, \f4wget_wch\f1()\f1@@@get a wide character from a terminal .\" toc@\f4mvget_wch()\f1: get a wide character from a terminal@@@see \f3get_wch(3X)\f1 .\" toc@\f4mvwget_wch()\f1: get a wide character from a terminal@@@see \f3get_wch(3X)\f1 .\" toc@\f4wget_wch()\f1: get a wide character from a terminal@@@see \f3get_wch(3X)\f1 .\" .\" index@\f4get_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f4mvget_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f4mvwget_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f4wget_wch()\f1 \- get a wide character from a terminal @@@\f3get_wch(3X)\f1 .\" index@\f1get a wide character from a terminal@@@\f3get_wch(3X)\f1 .\" index@\f1wide character, get from a terminal@@@\f3get_wch(3X)\f1 .\" index@\f1terminal, get a wide character from@@@\f3get_wch(3X)\f1 .\" index@\f1character, get a wide character from a terminal@@@\f3get_wch(3X)\f1 .\" .\" links@get_wch.3x mvget_wch.3x .\" links@get_wch.3x mvwget_wch.3x .\" links@get_wch.3x wget_wch.3x .\" .\" fileset_database@get_wch.3x CURS-ENG-A-MAN .\" $Header: getn_wstr.3x,v 76.2 95/08/01 10:52:41 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getn_wstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getn_wstr, get_wstr, mvgetn_wstr, mvget_wstr, mvwgetn_wstr, mvwget_wstr, wgetn_wstr, wget_wstr \(em get an array of wide characters and function key codes from a terminal .SH SYNOPSIS .C "#include " .P .C "int getn_wstr(wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int get_wstr(wint_t *\f2wstr\fP);" .P .C "int mvgetn_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvget_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int mvwgetn_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwget_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int wgetn_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int wget_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP);" .SH DESCRIPTION The effect of .Fn get_wstr is as though a series of calls to .Fn get_wch were made, until a newline character, end-of-line character, or end-of-file character is processed. An end-of-file character is represented by WEOF, as defined in .CR . A newline or end-of-line is represented as its .CR wchar_t value. In all instances, the end of the string is terminated by a null .CR wchar_t . The resulting values are placed in the area pointed to by \f2wstr\f1. .P The user's erase and kill characters are interpreted and affect the sequence of characters returned. .P The effect of .Fn wget_wstr is as though a series of calls to .Fn wget_wch were made. .P The effect of .Fn mvget_wstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_wstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. The effect of .Fn mvget_nwstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_nwstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. .P The .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr and .Fn wgetn_wstr functions read at most \f2n\f1 characters, letting the application prevent overflow of the input buffer. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR get_wstr() , .CR mvget_wstr() , .Fn mvwget_wstr or .Fn wget_wstr causes undefined results. The use of .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr or .Fn wgetn_wstr , respectively, is recommended. .P These functions cannot return KEY_ values as there is no way to distinguish a KEY_ value from a valid .B wchar_t value. .SH "SEE ALSO" get_wch(), getstr(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Chapter 9,\f3General Terminal Interface\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getn_wstr(3X)\f1:\0\0\f4getn_wstr()\f1, \f4get_wstr()\f1, \f4mvgetn_wstr()\f1, \f4mvget_wstr()\f1, \f4mvwgetn_wstr()\f1, \n\f4mvwget_wstr()\f1, \f4wgetn_wstr()\f1, \f4wget_wstr()\f1\n@@@get an array of wide characters and function key codes from a terminal .\" toc@\f4get_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" .\" index@\f4getn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4get_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1array of wide characters and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1wide characters, an array of, and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1terminal, get an array of wide characters and function key codes@@@\f3getn_wstr(3X)\f1 .\" .\" links@getn_wstr.3x get_wstr.3x .\" links@getn_wstr.3x mvgetn_wstr.3x .\" links@getn_wstr.3x mvget_wstr.3x .\" links@getn_wstr.3x mvwgetn_wstr.3x .\" links@getn_wstr.3x mvwget_wstr.3x .\" links@getn_wstr.3x wgetn_wstr.3x .\" links@getn_wstr.3x wget_wstr.3x .\" .\" fileset_database@getn_wstr.3x CURS-ENG-A-MAN .\" $Header: bkgrnd.3x,v 76.2 95/07/31 17:05:26 ssa Exp $ .TA b .de Fn .CR \\$1() .. .de Hd .RC <\\$1>. .. .TH bkgrnd 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME bkgrnd, bkgrndset, getbkgrnd, wbkgrnd, wbkgrndset, wgetbkgrnd \(em set or get background character and rendition using a complex character .SH SYNOPSIS .C "#include " .P .C "int bkgrnd(cchar_t *const \f2wch\fP);" .P .C "void bkgrndset(cchar_t *const \f2wch\fP);" .P .C "int getbkgrnd(cchar_t *\f2wch\fP);" .P .C "int wbkgrnd(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "void wbkgrndset(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "int wgetbkgrnd(WINDOW *\f2win\fP, cchar_t *\f2wch\fP);" .SH DESCRIPTION The .Fn bkgrndset and .Fn wbkgrndset functions set the background property of the current or specified window based on the information in \f2wch\f1. .P The .Fn bkgrnd and .Fn wbkgrnd functions set the background property of the current or specified window and then apply this setting to every character position in that window: .RS .TP 3 .C \(bu The rendition of every character on the screen is changed to the new background rendition. .TP .C \(bu Wherever the former background character appears, it is changed to the new background character. .RE .P If \f2wch\f1 refers to a non-spacing complex character for .CR bkgrnd() , .CR bkgrndset() , .Fn wbkgrnd and .CR wbkgrndset() , then \f2wch\f1 is added to the existing spacing complex character that is the background character. If \f2wch\f1 refers to a multi-column character, the results are unspecified. .P The .Fn getbkgrnd and .Fn wgetbkgrnd functions store, into the area pointed to by \f2wch\fP, the value of the window's background character and rendition. .SH "RETURN VALUE" The .Fn bkgrndset and .Fn wbkgrndset functions do not return a value. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Rendition\f1 in curses_intro, .Hd curses.h .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" toc@\f3bkgrnd(3X)\f1:\0\0\f4bkgrnd()\f1, \f4bkgrndset()\f1, \f4getbkgrnd()\f1, \f4wbkgrnd()\f1, \f4wbkgrndset()\f1, \f4wgetbkgrnd()\f1\n@@@set or get background character and rendition using a complex character .\" toc@\f4bkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4bkgrndset()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4getbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wbkgrndset()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" toc@\f4wgetbkgrnd()\f1: set or get background character and rendition using a complex character@@@see \f3bkgrnd(3X)\f1 .\" index@\f1set or get background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1get or set background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1background character and rendition using a complex character@@@\f3bkgrnd(3X)\f1 .\" index@\f1complex character, set or get background character and rendition using@@@\f3bkgrnd(3X)\f1 .\" index@\f4bkgrnd()\f1 \- set or get background character and rendition using omplex character@@@\f3bkgrnd(3X)\f1 .\" .\" links@bkgrnd.3x bkgrndset.3x .\" links@bkgrnd.3x getbkgrnd.3x .\" links@bkgrnd.3x wbkgrnd.3x .\" links@bkgrnd.3x wbkgrndset.3x .\" links@bkgrnd.3x wgetbkgrnd.3x .\" .\" fileset_database@bkgrnd.3x CURS-ENG-A-MAN .\" $Header: getch.3x,v 76.2 95/08/01 10:51:16 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getch, wgetch, mvgetch, mvwgetch \(em get a single-byte character from the terminal .SH SYNOPSIS .C "#include " .P .C "int getch(void);" .P .C "int mvgetch(int \f2y\fP, int \f2x\fP);" .P .C "int mvwgetch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "int wgetch(WINDOW *\f2win\fP);" .SH DESCRIPTION These functions read a single-byte character from the terminal associated with the current or specified window. The results are unspecified if the input is not a single-byte character. If .Fn keypad is enabled, these functions respond to the pressing of a function key by returning the corresponding KEY_ value defined in .CR . .P Processing of terminal input is subject to the general rules described in \f3Input Processing\f1 in curses_intro. .P If echoing is enabled, then the character is echoed as though it were provided as an input argument to .CR insch() , except for the following characters: .PP .TS tab(`); lw(2.00i) lw(3i). T{ , and the current erase character: T}`T{ The input is interpreted as specified in .CR specialchars and then the character at the resulting cursor position is deleted as though .Fn delch were called, except that if the cursor was originally in the first column of the line, then the user is alerted as though .Fn beep were called. T} .P Function keys`T{ The user is alerted as though .Fn beep were called. Information concerning the function keys is not returned to the caller. T} .TE .P If the current or specified window is not a pad, and it has been moved or modified since the last refresh operation, then it will be refreshed before another character is read. .SH "RETURN VALUE" Upon successful completion, these functions return the single-byte character, KEY_ value, or ERR. .P If in nodelay mode and no data is available, ERR is returned. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Applications should not define the escape key by itself as a single-character function. .P When using these functions, nocbreak mode (\c .CR nocbreak() ) and echo mode (\c .CR echo() ) should not be used at the same time. Depending on the state of the terminal when each character is typed, the program may produce undesirable results. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, cbreak(), doupdate(), insch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn getch function is explicitly declared as \f3void\f1. .\" .\" toc@\f3getch(3X)\f1:\0\0\f4getch()\f1, \f4wgetch()\f1, \f4mvgetch()\f1, \f4mvwgetch()\f1@@@get a single-byte character from the terminal .\" toc@\f4wgetch()\f1: get a single-byte character from the terminal@@@see \f3getch(3X)\f1 .\" toc@\f4mvwgetch()\f1: get a single-byte character from the terminal@@@see \f3getch(3X)\f1 .\" toc@\f4mvgetch()\f1: get a single-byte character from the terminal@@@see \f3getch(3X)\f1 .\" .\" index@\f4getch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f4wgetch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f4mvgetch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f4mvwgetch()\f1 \- get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f1get a single-byte character from the terminal@@@\f3getch(3X)\f1 .\" index@\f1single-byte character, get from the terminal@@@\f3getch(3X)\f1 .\" index@\f1terminal, get a single-byte character@@@\f3getch(3X)\f1 .\" index@\f1character, single-byte, get from the terminal@@@\f3getch(3X)\f1 .\" .\" links@getch.3x wgetch.3x .\" links@getch.3x mvwgetch.3x .\" links@getch.3x mvgetch.3x .\" .\" fileset_database@getch.3x CURS-ENG-A-MAN .\" $Header: getn_wstr.3x,v 76.2 95/08/01 10:52:41 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getn_wstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getn_wstr, get_wstr, mvgetn_wstr, mvget_wstr, mvwgetn_wstr, mvwget_wstr, wgetn_wstr, wget_wstr \(em get an array of wide characters and function key codes from a terminal .SH SYNOPSIS .C "#include " .P .C "int getn_wstr(wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int get_wstr(wint_t *\f2wstr\fP);" .P .C "int mvgetn_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvget_wstr(int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int mvwgetn_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwget_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wint_t *\f2wstr\fP);" .P .C "int wgetn_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP, int \f2n\fP);" .P .C "int wget_wstr(WINDOW *\f2win\fP, wint_t *\f2wstr\fP);" .SH DESCRIPTION The effect of .Fn get_wstr is as though a series of calls to .Fn get_wch were made, until a newline character, end-of-line character, or end-of-file character is processed. An end-of-file character is represented by WEOF, as defined in .CR . A newline or end-of-line is represented as its .CR wchar_t value. In all instances, the end of the string is terminated by a null .CR wchar_t . The resulting values are placed in the area pointed to by \f2wstr\f1. .P The user's erase and kill characters are interpreted and affect the sequence of characters returned. .P The effect of .Fn wget_wstr is as though a series of calls to .Fn wget_wch were made. .P The effect of .Fn mvget_wstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_wstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. The effect of .Fn mvget_nwstr is as though a call to .Fn move and then a series of calls to .Fn get_wch were made. The effect of .Fn mvwget_nwstr is as though a call to .Fn wmove and then a series of calls to .Fn wget_wch were made. .P The .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr and .Fn wgetn_wstr functions read at most \f2n\f1 characters, letting the application prevent overflow of the input buffer. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR get_wstr() , .CR mvget_wstr() , .Fn mvwget_wstr or .Fn wget_wstr causes undefined results. The use of .CR getn_wstr() , .CR mvgetn_wstr() , .Fn mvwgetn_wstr or .Fn wgetn_wstr , respectively, is recommended. .P These functions cannot return KEY_ values as there is no way to distinguish a KEY_ value from a valid .B wchar_t value. .SH "SEE ALSO" get_wch(), getstr(), , (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Chapter 9,\f3General Terminal Interface\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getn_wstr(3X)\f1:\0\0\f4getn_wstr()\f1, \f4get_wstr()\f1, \f4mvgetn_wstr()\f1, \f4mvget_wstr()\f1, \f4mvwgetn_wstr()\f1, \n\f4mvwget_wstr()\f1, \f4wgetn_wstr()\f1, \f4wget_wstr()\f1\n@@@get an array of wide characters and function key codes from a terminal .\" toc@\f4get_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4mvwget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wgetn_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" toc@\f4wget_wstr()\f1: get an array of wide characters and function key codes from a terminal@@@see \f3getn_wstr(3X)\f1 .\" .\" index@\f4getn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4get_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4mvwget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wgetn_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f4wget_wstr()\f1 \- get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1get an array of wide characters and function key codes from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1array of wide characters and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1wide characters, an array of, and function key codes, get from a terminal@@@\f3getn_wstr(3X)\f1 .\" index@\f1terminal, get an array of wide characters and function key codes@@@\f3getn_wstr(3X)\f1 .\" .\" links@getn_wstr.3x get_wstr.3x .\" links@getn_wstr.3x mvgetn_wstr.3x .\" links@getn_wstr.3x mvget_wstr.3x .\" links@getn_wstr.3x mvwgetn_wstr.3x .\" links@getn_wstr.3x mvwget_wstr.3x .\" links@getn_wstr.3x wgetn_wstr.3x .\" links@getn_wstr.3x wget_wstr.3x .\" .\" fileset_database@getn_wstr.3x CURS-ENG-A-MAN .\" $Header: getnstr.3x,v 76.2 95/08/01 10:57:27 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getnstr, mvgetnstr, mvwgetnstr, wgetnstr, \(em get a multi-byte character length limited string from the terminal .SH SYNOPSIS .C "#include " .P .C "int getnstr(char *\f2str\fP, int \f2n\fP);" .P .C "int mvgetnstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvwgetnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int wgetnstr(WINDOW *\f2win\fP, char *\f2str\fP, int \f2n\fP);" .SH DESCRIPTION The effect of .Fn getnstr and .Fn wgetnstr is as though a series of calls to .Fn getch were made, until a newline or carriage return is received. The resulting value is placed in the area pointed to by \f2str\f1. The .Fn getnstr and .Fn wgetnstr functions read at most \f2n\f1 bytes, thus preventing a possible overflow of the input buffer. The user's erase and kill characters are interpreted, as well as any special keys (such as function keys, home key, clear key, and so on). .P The .Fn mvgetnstr function is identical to .Fn getnstr except that it is as though it is a call to .Fn move and then a series of calls to .CR getch() . The .Fn mvwgetnstr function is identical to .Fn getnstr except it is as though a call to .Fn wmove is made and then a series of calls to .CR wgetch() . .P The .CR getnstr() , .CR wgetnstr() , .Fn mvgetnstr and .Fn mvwgetnstr functions will only return the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character, the functions fill the array with complete characters. If the array is not large enough to contain any complete characters, the function fails. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" .P Traditional implementations often limited the number of bytes returned to 256. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, beep(), getch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3getnstr(3X)\f1:\0\0\f4getnstr()\f1, \f4mvgetnstr()\f1, \f4mvwgetnstr()\f1, \f4wgetnstr()\f1\n@@@get a multi-byte character length limited string from the terminal .\" toc@\f4mvgetnstr()\f1: get a multi-byte character length limited string from the terminal@@@see \f3getnstr(3X)\f1 .\" toc@\f4mvwgetnstr()\f1: get a multi-byte character length limited string from the terminal@@@see \f3getnstr(3X)\f1 .\" toc@\f4wgetnstr()\f1: get a multi-byte character length limited string from the terminal@@@see \f3getnstr(3X)\f1 .\" .\" index@\f4getnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f4mvgetnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f4mvwgetnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f4wgetnstr()\f1 \- get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1multi-byte character length limited string, get from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1terminal, get a multi-byte character length limited string from@@@\f3getnstr(3X)\f1 .\" index@\f1character, get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" index@\f1string, get a multi-byte character length limited string from the terminal@@@\f3getnstr(3X)\f1 .\" .\" links@getnstr.3x mvgetnstr.3x .\" links@getnstr.3x mvwgetnstr.3x .\" links@getnstr.3x wgetnstr.3x .\" .\" fileset_database@getnstr.3x CURS-ENG-A-MAN .\" $Header: getstr.3x,v 76.2 95/08/01 10:58:50 ssa Exp $ .TA g .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH getstr 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME getstr, mvgetstr, mvwgetstr, wgetstr \(em get a multi-byte character string from the terminal .SH SYNOPSIS .C "#include " .P .C "int getstr(char *\f2str\fP);" .P .C "int mvgetstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int mvwgetstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int wgetstr(WINDOW *\f2win\fP, char *\f2str\fP);" .SH DESCRIPTION The effect of .Fn getstr is as though a series of calls to .Fn getch were made, until a newline or carriage return is received. The resulting value is placed in the area pointed to by \f2str\f1. The user's erase and kill characters are interpreted, as well as any special keys (such as function keys, home key, clear key, and so on). .P The .Fn mvgetstr function is identical to .Fn getstr except that it is as though it is a call to .Fn move and then a series of calls to .CR getch() . The .Fn mvwgetstr function is identical to .Fn getstr except it is as though a call to .Fn wmove is made and then a series of calls to .CR wgetch() . .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2str\f1 with .CR getstr() , .CR mvgetstr() , .Fn mvwgetstr or .Fn wgetstr causes undefined results. .P Traditional implementations often limited the number of bytes returned to 256. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, beep(), getch(), getnstr(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .br .ne 5 .SH Issue 3 .P In X/Open Curses, Issue 3, the .CR getstr() , .CR mvgetstr() , .Fn mvwgetstr and .Fn wgetstr functions were described in the .Fn addstr entry. In X/Open Curses, Issue 4, the .B DESCRIPTION of these functions is rewritten for clarity and is updated to indicate that they will handle multi-byte sequences correctly. .\" .\" toc@\f3getstr(3X)\f1:\0\0\f4getstr()\f1, \f4mvgetstr()\f1, \f4mvwgetstr()\f1, \f4wgetstr()\f1\n@@@get a multi-byte character string from the terminal .\" toc@\f4mvgetstr()\f1: get a multi-byte character string from the terminal@@@see \f3getstr(3X)\f1 .\" toc@\f4mvwgetstr()\f1: get a multi-byte character string from the terminal@@@see \f3getstr(3X)\f1 .\" toc@\f4wgetstr()\f1: get a multi-byte character string from the terminal@@@see \f3getstr(3X)\f1 .\" .\" index@\f4getstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f4mvgetstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f4mvwgetstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f4wgetstr()\f1 \- get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1multi-byte character string, get from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1terminal, get a multi-byte character string@@@\f3getstr(3X)\f1 .\" index@\f1character, get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" index@\f1string, get a multi-byte character string from the terminal@@@\f3getstr(3X)\f1 .\" .\" links@getstr.3x mvgetstr.3x .\" links@getstr.3x mvwgetstr.3x .\" links@getstr.3x wgetstr.3x .\" .\" fileset_database@getstr.3x CURS-ENG-A-MAN .\" $Header: hline.3x,v 76.2 95/08/01 11:07:23 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline, mvhline, mvvline, mvwhline, mvwvline, vline, whline, wvline \(em draw lines from single-byte characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvhline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvvline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwhline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwvline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int vline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int whline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int wvline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline() , .CR mvhline() , .Fn mvwhline and .Fn whline functions draw a line proceeding toward the last column of the same line. .P The .CR vline() , .CR mvvline() , .Fn mvwvline and .Fn wvline functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" border(), box(), hline_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline(3X)\f1:\0\0\f4hline()\f1, \f4mvhline()\f1, \f4mvvline()\f1, \f4mvwhline()\f1, \f4mvwvline()\f1, \f4vline()\f1, \f4whline()\f1, \f4wvline()\f1\n@@@draw lines from single-byte characters and renditions .\" toc@\f4mvhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4vline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4whline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4wvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" .\" index@\f4hline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4vline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4whline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4wvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1lines, draw from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1single-byte characters and renditions, draw lines from@@@\f3hline(3X)\f1 .\" index@\f1characters and renditions, draw lines from single-byte@@@\f3hline(3X)\f1 .\" index@\f1renditions and characters, draw lines from single-byte@@@\f3hline(3X)\f1 .\" .\" links@hline.3x mvhline.3x .\" links@hline.3x mvvline.3x .\" links@hline.3x mvwhline.3x .\" links@hline.3x mvwvline.3x .\" links@hline.3x vline.3x .\" links@hline.3x whline.3x .\" links@hline.3x wvline.3x .\" .\" fileset_database@hline.3x CURS-ENG-A-MAN .\" $Header: hline_set.3x,v 76.2 95/08/01 11:08:14 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline_set 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline_set, mvhline_set, mvvline_set, mvwhline_set, mvwvline_set, vline_set, whline_set, wvline_set \(em draw lines from complex characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvhline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvvline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwhline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwvline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int vline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int whline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int wvline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline_set() , .CR mvhline_set() , .Fn mvwhline_set and .Fn whline_set functions draw a line proceeding toward the last column of the same line. .P The .CR vline_set() , .CR mvvline_set() , .Fn mvwvline_set and .Fn wvline_set functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" border_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline_set(3X)\f1:\0\0\f4hline_set()\f1, \f4mvhline_set()\f1, \f4mvvline_set()\f1, \f4mvwhline_set()\f1, \f4mvwvline_set()\f1, \n\f4vline_set()\f1, \f4whline_set()\f1, \f4wvline_set()\f1@@@draw lines from complex characters and renditions .\" toc@\f4mvhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4vline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4whline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4wvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" .\" index@\f4hline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4vline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4whline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4wvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1lines, draw from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1complex characters and renditions, draw lines from@@@\f3hline_set(3X)\f1 .\" index@\f1characters and renditions, complex, draw lines from@@@\f3hline_set(3X)\f1 .\" .\" links@hline_set.3x mvhline_set.3x .\" links@hline_set.3x mvvline_set.3x .\" links@hline_set.3x mvwhline_set.3x .\" links@hline_set.3x mvwvline_set.3x .\" links@hline_set.3x vline_set.3x .\" links@hline_set.3x whline_set.3x .\" links@hline_set.3x wvline_set.3x .\" .\" fileset_database@hline_set.3x CURS-ENG-A-MAN .\" $Header: in_wch.3x,v 76.2 95/08/01 11:13:14 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH in_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME in_wch, mvin_wch, mvwin_wch, win_wch \(em input a complex character and rendition from a window .SH SYNOPSIS .C "#include " .P .C "int in_wch(cchar_t *\f2wcval\fP);" .P .C "int mvin_wch(int \f2y\fP, int \f2x\fP, cchar_t *\f2wcval\fP);" .P .C "int mvwin_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wcval\fP);" .P .C "int win_wch(WINDOW *\f2win\fP, cchar_t *\f2wcval\fP);" .SH DESCRIPTION These functions extract the complex character and rendition from the current or specified position in the current or specified window into the object pointed to by \f2wcval\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3in_wch(3X)\f1:\0\0\f4in_wch()\f1, \f4mvin_wch()\f1, \f4mvwin_wch()\f1, \f4win_wch()\f1\n@@@input a complex character and rendition from a window .\" toc@\f4mvin_wch()\f1: input a complex character and rendition from a window@@@see \f3in_wch(3X)\f1 .\" toc@\f4mvwin_wch()\f1: input a complex character and rendition from a window@@@see \f3in_wch(3X)\f1 .\" toc@\f4win_wch()\f1: input a complex character and rendition from a window@@@see \f3in_wch(3X)\f1 .\" .\" index@\f4in_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f4mvin_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f4mvwin_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f4win_wch()\f1 \- input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f1input a complex character and rendition from a window@@@\f3in_wch(3X)\f1 .\" index@\f1complex character and rendition, input from a window@@@\f3in_wch(3X)\f1 .\" index@\f1character and rendition, complex, input from a window@@@\f3in_wch(3X)\f1 .\" index@\f1window, input a complex character and rendition from@@@\f3in_wch(3X)\f1 .\" .\" links@in_wch.3x mvin_wch.3x .\" links@in_wch.3x mvwin_wch.3x .\" links@in_wch.3x win_wch.3x .\" .\" fileset_database@in_wch.3x CURS-ENG-A-MAN .\" $Header: in_wchnstr.3x,v 76.2 95/08/01 11:14:16 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH in_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME in_wchnstr, in_wchstr, mvin_wchnstr, mvin_wchstr, mvwin_wchnstr, mvwin_wchstr, win_wchnstr, win_wchstr \(em input an array of complex characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int in_wchnstr(cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int in_wchstr(cchar_t *\f2wchstr\fP);" .P .C "int mvin_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvin_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int mvwin_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvwin_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int win_wchnstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int win_wchstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP);" .SH DESCRIPTION These functions extract characters from the current or specified window, starting at the current or specified position and ending at the end of the line, and place them in the array pointed to by .I wchstr . .P The .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr and .Fn win_wchnstr fill the array with at most \f2n\f1 \f3cchar_t\f1 elements. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wchstr\f1 with .CR in_wchstr() , .CR mvin_wchstr() , .Fn mvwin_wchstr or .Fn win_wchstr causes undefined results. The use of .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr or .Fn win_wchnstr , respectively, is recommended. .SH "SEE ALSO" in_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3in_wchnstr(3X)\f1:\0\0\f4in_wchnstr()\f1, \f4in_wchstr()\f1, \f4mvin_wchnstr()\f1, \f4mvin_wchstr()\f1, \f4mvwin_wchnstr()\f1, \n\f4mvwin_wchstr()\f1, \f4win_wchnstr()\f1, \f4win_wchstr()\f1\n@@@input an array of complex characters and renditions from a window .\" toc@\f4in_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" .\" index@\f4in_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4in_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1array of complex characters and renditions, input from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1window, input an array of complex characters and renditions from@@@\f3in_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, input an array of, from a window@@@\f3in_wchnstr(3X)\f1 .\" .\" links@in_wchnstr.3x in_wchstr.3x .\" links@in_wchnstr.3x mvin_wchstr.3x .\" links@in_wchnstr.3x mvin_wchnstr.3x .\" links@in_wchnstr.3x mvwin_wchstr.3x .\" links@in_wchnstr.3x mvwin_wchnstr.3x .\" links@in_wchnstr.3x win_wchstr.3x .\" links@in_wchnstr.3x win_wchnstr.3x .\" .\" fileset_database@in_wchnstr.3x CURS-ENG-A-MAN .\" $Header: in_wchnstr.3x,v 76.2 95/08/01 11:14:16 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH in_wchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME in_wchnstr, in_wchstr, mvin_wchnstr, mvin_wchstr, mvwin_wchnstr, mvwin_wchstr, win_wchnstr, win_wchstr \(em input an array of complex characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int in_wchnstr(cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int in_wchstr(cchar_t *\f2wchstr\fP);" .P .C "int mvin_wchnstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvin_wchstr(int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int mvwin_wchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int mvwin_wchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *\f2wchstr\fP);" .P .C "int win_wchnstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP, int \f2n\fP);" .P .C "int win_wchstr(WINDOW *\f2win\fP, cchar_t *\f2wchstr\fP);" .SH DESCRIPTION These functions extract characters from the current or specified window, starting at the current or specified position and ending at the end of the line, and place them in the array pointed to by .I wchstr . .P The .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr and .Fn win_wchnstr fill the array with at most \f2n\f1 \f3cchar_t\f1 elements. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wchstr\f1 with .CR in_wchstr() , .CR mvin_wchstr() , .Fn mvwin_wchstr or .Fn win_wchstr causes undefined results. The use of .CR in_wchnstr() , .CR mvin_wchnstr() , .Fn mvwin_wchnstr or .Fn win_wchnstr , respectively, is recommended. .SH "SEE ALSO" in_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3in_wchnstr(3X)\f1:\0\0\f4in_wchnstr()\f1, \f4in_wchstr()\f1, \f4mvin_wchnstr()\f1, \f4mvin_wchstr()\f1, \f4mvwin_wchnstr()\f1, \n\f4mvwin_wchstr()\f1, \f4win_wchnstr()\f1, \f4win_wchstr()\f1\n@@@input an array of complex characters and renditions from a window .\" toc@\f4in_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4mvwin_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" toc@\f4win_wchnstr()\f1: input an array of complex characters and renditions from a window@@@see \f3in_wchnstr(3X)\f1 .\" .\" index@\f4in_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4in_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4mvwin_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchnstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f4win_wchstr()\f1 \- input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1input an array of complex characters and renditions from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1array of complex characters and renditions, input from a window@@@\f3in_wchnstr(3X)\f1 .\" index@\f1window, input an array of complex characters and renditions from@@@\f3in_wchnstr(3X)\f1 .\" index@\f1complex characters and renditions, input an array of, from a window@@@\f3in_wchnstr(3X)\f1 .\" .\" links@in_wchnstr.3x in_wchstr.3x .\" links@in_wchnstr.3x mvin_wchstr.3x .\" links@in_wchnstr.3x mvin_wchnstr.3x .\" links@in_wchnstr.3x mvwin_wchstr.3x .\" links@in_wchnstr.3x mvwin_wchnstr.3x .\" links@in_wchnstr.3x win_wchstr.3x .\" links@in_wchnstr.3x win_wchnstr.3x .\" .\" fileset_database@in_wchnstr.3x CURS-ENG-A-MAN .\" $Header: inch.3x,v 76.2 95/08/01 11:18:42 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH inch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inch, mvinch, mvwinch, winch \(em input a single-byte character and rendition from a window .SH SYNOPSIS .C "#include " .P .C "chtype inch(void);" .P .C "chtype mvinch(int \f2y\fP, int \f2x\fP);" .P .C "chtype mvwinch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .P .C "chtype winch(WINDOW *\f2win\fP);" .SH DESCRIPTION These functions return the character and rendition, of type \f2chtype\f1, at the current or specified position in the current or specified window. .SH "RETURN VALUE" Upon successful completion, the functions return the specified character and rendition. Otherwise, they return (\f3chtype\fP)ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn inch function is explicitly declared as \f3void\f1. .\" .\" toc@\f3inch(3X)\f1:\0\0\f4inch()\f1, \f4mvinch()\f1, \f4mvwinch()\f1, \f4winch\f1@@@input a single-byte character and rendition from a window .\" toc@\f4mvinch()\f1: input a single-byte character and rendition from a window@@@see \f3inch(3X)\f1 .\" toc@\f4mvwinch()\f1: input a single-byte character and rendition from a window@@@see \f3inch(3X)\f1 .\" toc@\f4winch()\f1: input a single-byte character and rendition from a window@@@see \f3inch(3X)\f1 .\" .\" index@\f4inch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f4mvinch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f4mvwinch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f4winch()\f1 \- input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f1input a single-byte character and rendition from a window@@@\f3inch(3X)\f1 .\" index@\f1single-byte character and rendition, input from a window@@@\f3inch(3X)\f1 .\" index@\f1window, input a single-byte character and rendition from@@@\f3inch(3X)\f1 .\" index@\f1character and rendition, input a single-byte from a window@@@\f3inch(3X)\f1 .\" .\" links@inch.3x mvinch.3x .\" links@inch.3x mvwinch.3x .\" links@inch.3x winch.3x .\" .\" fileset_database@inch.3x CURS-ENG-A-MAN .\" $Header: inchnstr.3x,v 76.2 95/08/01 11:20:07 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH inchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inchnstr, inchstr, mvinchnstr, mvinchstr, mvwinchnstr, mvwinchstr, winchnstr, winchstr \(em input an array of single-byte characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int inchnstr(chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int inchstr(chtype *\f2chstr\fP);" .P .C "int mvinchnstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvinchstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int mvwinchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvwinchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int winchnstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int winchstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP);" .SH DESCRIPTION These functions place characters and renditions from the current or specified window into the array pointed to by \f2chstr\f1, starting at the current or specified position and ending at the end of the line. .P The .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr and .Fn winchnstr functions store at most \f2n\f1 elements from the current or specified window into the array pointed to by \f2chstr\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2chstr\f1 with .CR inchstr() , .CR mvinchstr() , .Fn mvwinchstr or .Fn winchstr causes undefined results. The use of .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr or .CR winchnstr() , respectively, is recommended. .SH "SEE ALSO" inch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3inchnstr(3X)\f1:\0\0\f4inchnstr()\f1, \f4inchstr()\f1, \f4mvinchnstr()\f1, \f4mvinchstr()\f1, \f4mvwinchnstr()\f1, \f4mvwinchstr()\f1, \n\f4winchnstr()\f1, \f4winchstr()\f1@@@input an array of single-byte characters and renditions from a window .\" toc@\f4inchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" .\" index@\f4inchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4inchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1array of single-byte characters and renditions, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1single-byte characters and renditions, array of, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1characters and renditions, an array of single-byte, input from a window@@@\f3inchnstr(3X)\f1 .\" .\" links@inchnstr.3x inchstr.3x .\" links@inchnstr.3x mvinchstr.3x .\" links@inchnstr.3x mvinchnstr.3x .\" links@inchnstr.3x mvwinchstr.3x .\" links@inchnstr.3x mvwinchnstr.3x .\" links@inchnstr.3x winchstr.3x .\" links@inchnstr.3x winchnstr.3x .\" .\" fileset_database@inchnstr.3x CURS-ENG-A-MAN .\" $Header: inchnstr.3x,v 76.2 95/08/01 11:20:07 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH inchnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME inchnstr, inchstr, mvinchnstr, mvinchstr, mvwinchnstr, mvwinchstr, winchnstr, winchstr \(em input an array of single-byte characters and renditions from a window .SH SYNOPSIS .C "#include " .P .C "int inchnstr(chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int inchstr(chtype *\f2chstr\fP);" .P .C "int mvinchnstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvinchstr(int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int mvwinchnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int mvwinchstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype *\f2chstr\fP);" .P .C "int winchnstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP, int \f2n\fP);" .P .C "int winchstr(WINDOW *\f2win\fP, chtype *\f2chstr\fP);" .SH DESCRIPTION These functions place characters and renditions from the current or specified window into the array pointed to by \f2chstr\f1, starting at the current or specified position and ending at the end of the line. .P The .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr and .Fn winchnstr functions store at most \f2n\f1 elements from the current or specified window into the array pointed to by \f2chstr\f1. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2chstr\f1 with .CR inchstr() , .CR mvinchstr() , .Fn mvwinchstr or .Fn winchstr causes undefined results. The use of .CR inchnstr() , .CR mvinchnstr() , .Fn mvwinchnstr or .CR winchnstr() , respectively, is recommended. .SH "SEE ALSO" inch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3inchnstr(3X)\f1:\0\0\f4inchnstr()\f1, \f4inchstr()\f1, \f4mvinchnstr()\f1, \f4mvinchstr()\f1, \f4mvwinchnstr()\f1, \f4mvwinchstr()\f1, \n\f4winchnstr()\f1, \f4winchstr()\f1@@@input an array of single-byte characters and renditions from a window .\" toc@\f4inchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4mvwinchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" toc@\f4winchnstr()\f1: input an array of single-byte characters and renditions from a window@@@see \f3inchnstr(3X)\f1 .\" .\" index@\f4inchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4inchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4mvwinchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchnstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f4winchstr()\f1 \- input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1input an array of single-byte characters and renditions from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1array of single-byte characters and renditions, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1single-byte characters and renditions, array of, input from a window@@@\f3inchnstr(3X)\f1 .\" index@\f1characters and renditions, an array of single-byte, input from a window@@@\f3inchnstr(3X)\f1 .\" .\" links@inchnstr.3x inchstr.3x .\" links@inchnstr.3x mvinchstr.3x .\" links@inchnstr.3x mvinchnstr.3x .\" links@inchnstr.3x mvwinchstr.3x .\" links@inchnstr.3x mvwinchnstr.3x .\" links@inchnstr.3x winchstr.3x .\" links@inchnstr.3x winchnstr.3x .\" .\" fileset_database@inchnstr.3x CURS-ENG-A-MAN .\" $Header: innstr.3x,v 76.2 95/08/01 11:22:05 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innstr, instr, mvinnstr, mvinstr, mvwinnstr, mvwinstr, winnstr, winstr \(em input a multi-byte character string from a window .SH SYNOPSIS .C "#include " .P .C "int innstr(char *\f2str\fP, int \f2n\fP);" .P .C "int instr(char *\f2str\fP);" .P .C "int mvinnstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvinstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int mvwinnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvwinstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int winnstr(WINDOW *\f2win\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int winstr(WINDOW *\f2win\fP, char *\f2str\fP);" .SH DESCRIPTION These functions place a string of characters from the current or specified window into the array pointed to by \f2str\fP, starting at the current or specified position and ending at the end of the line. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions store at most \f2n\f1 bytes in the string pointed to by \f2str\f1. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions will only store the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character the array is filled with complete characters. If the array is not large enough to contain any complete characters, the function fails. .SH "RETURN VALUE" Upon successful completion, .CR instr() , .CR mvinstr() , .Fn mvwinstr and .Fn winstr return OK. .P Upon successful completion, .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since multi-byte characters may be processed, there might not be a one-to-one correspondence between the number of column positions on the screen and the number of bytes returned. .P These functions do not return rendition information. .P Reading a line that overflows the array pointed to by \f2str\f1 with .CR instr() , .CR mvinstr() , .Fn mvwinstr or .Fn winstr causes undefined results. The use of .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr or .CR winnstr() , respectively, is recommended. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innstr(3X)\f1:\0\0\f4innstr()\f1, \f4instr()\f1, \f4mvinnstr()\f1, \f4mvinstr()\f1, \f4mvwinnstr()\f1, \f4mvwinstr()\f1, \f4winnstr()\f1, \n\f4winstr()\f1@@@input a multi-byte character string from a window .\" toc@\f4instr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" .\" index@\f4innstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4instr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1multi-byte character string, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1character string, multi-byte, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1window, input a multi-byte character string from@@@\f3innstr(3X)\f1 .\" .\" links@innstr.3x instr.3x .\" links@innstr.3x mvinstr.3x .\" links@innstr.3x mvinnstr.3x .\" links@innstr.3x mvwinstr.3x .\" links@innstr.3x mvwinnstr.3x .\" links@innstr.3x winstr.3x .\" links@innstr.3x winnstr.3x .\" .\" fileset_database@innstr.3x CURS-ENG-A-MAN .\" $Header: innwstr.3x,v 76.2 95/08/01 11:22:59 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innwstr, inwstr, mvinnwstr, mvinwstr, mvwinnwstr, mvwinwstr, winnwstr, winwstr \(em input a string of wide characters from a window .SH SYNOPSIS .C "#include " .P .C "int innwstr(wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int inwstr(wchar_t *\f2wstr\fP);" .P .C "int mvinnwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvinwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int mvwinnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwinwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int winnwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int winwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP);" .SH DESCRIPTION These functions place a string of \f3wchar_t\f1 characters from the current or specified window into the array pointed to by \f2wstr\f1 starting at the current or specified cursor position and ending at the end of the line. .P These functions will only store the entire wide character sequence associated with a spacing complex character. If the array is large enough to contain at least one complete spacing complex character, the array is filled with complete characters. If the array is not large enough to contain any complete characters this is an error. .P The .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr functions store at most \f2n\f1 characters in the array pointed to by \f2wstr\f1. .SH "RETURN VALUE" Upon successful completion, .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr and .Fn winwstr return OK. .P Upon successful completion, .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr or .Fn winwstr causes undefined results. The use of .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr or .CR winnwstr() , respectively, is recommended. .P These functions do not return rendition information. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innwstr(3X)\f1:\0\0\f4innwstr()\f1, \f4inwstr()\f1, \f4mvinnwstr()\f1, \f4mvinwstr()\f1, \f4mvwinnwstr()\f1, \f4mvwinwstr()\f1, \n\f4winnwstr()\f1, \f4winwstr()\f1@@@input a string of wide characters from a window .\" toc@\f4innwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4inwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" .\" index@\f4innwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4inwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1string of wide characters, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1wide characters, string of, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1window, input a string of wide characters from@@@\f3innwstr(3X)\f1 .\" index@\f1characters, wide, input a string of, from a window@@@\f3innwstr(3X)\f1 .\" .\" links@innwstr.3x inwstr.3x .\" links@innwstr.3x mvinnwstr.3x .\" links@innwstr.3x mvinwstr.3x .\" links@innwstr.3x mvwinnwstr.3x .\" links@innwstr.3x mvwinwstr.3x .\" links@innwstr.3x winnwstr.3x .\" links@innwstr.3x winwstr.3x .\" .\" fileset_database@innwstr.3x CURS-ENG-A-MAN .\" $Header: ins_nwstr.3x,v 76.2 95/08/01 11:23:53 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ins_nwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ins_nwstr, ins_wstr, mvins_nwstr, mvins_wstr, mvwins_nwstr, mvwins_wstr, wins_nwstr, wins_wstr \(em insert a wide-character string into a window .SH SYNOPSIS .C "#include " .P .C "int ins_nwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int ins_wstr(wchar_t *const \f2wstr\fP);" .P .C "int mvins_nwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvins_wstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwins_nwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwins_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int wins_nwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int wins_wstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions insert a .B wchar_t character string (as many .B wchar_t characters as will fit on the line) in the current or specified window immediately before the current or specified position. .P Any non-spacing characters in the string are associated with the first spacing character in the string that precedes the non-spacing characters. If the first character in the string is a non-spacing character, these functions will fail. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing. .P The .CR ins_nwstr() , .CR mvins_nwstr() , .Fn mvwins_nwstr and .Fn wins_nwstr functions insert at most \f2n\f1 \f3wchar_t\f1 characters. If \f2n\f1 is less than 1, then the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3ins_nwstr(3X)\f1:\0\0\f4ins_nwstr()\f1, \f4ins_wstr()\f1, \f4mvins_nwstr()\f1, \f4mvins_wstr()\f1, \f4mvwins_nwstr()\f1, \n\f4mvwins_wstr()\f1, \f4wins_nwstr()\f1, \f4wins_wstr()\f1@@@insert a wide-character string into a window .\" toc@\f4ins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" .\" index@\f4ins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4ins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1wide-character string, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1string of wide-character, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1window, insert a wide-character string into@@@\f3ins_nwstr(3X)\f1 .\" index@\f1character, insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" .\" links@ins_nwstr.3x ins_wstr.3x .\" links@ins_nwstr.3x mvins_nwstr.3x .\" links@ins_nwstr.3x mvins_wstr.3x .\" links@ins_nwstr.3x mvwins_nwstr.3x .\" links@ins_nwstr.3x mvwins_wstr.3x .\" links@ins_nwstr.3x wins_nwstr.3x .\" links@ins_nwstr.3x wins_wstr.3x .\" .\" fileset_database@ins_nwstr.3x CURS-ENG-A-MAN .\" $Header: ins_wch.3x,v 76.2 95/08/01 11:24:46 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ins_wch 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ins_wch, mvins_wch, mvwins_wch, wins_wch \(em insert a complex character and rendition into a window .SH SYNOPSIS .C "#include " .P .C "int ins_wch(cchar_t *const \f2wch\fP);" .P .C "int wins_wch(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP);" .P .C "int mvins_wch(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .P .C "int mvwins_wch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP);" .SH DESCRIPTION These functions insert the complex character \f2wch\f1 with its rendition in the current or specified window at the current or specified cursor position. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing, with the exception that if a newline is inserted into the last line of a window and scrolling is not enabled, the behaviour is unspecified. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" For non-spacing characters, .Fn add_wch can be used to add the non-spacing characters to a spacing complex character already in the window. .SH "SEE ALSO" add_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3ins_wch(3X)\f1:\0\0\f4ins_wch()\f1, \f4mvins_wch()\f1, \f4mvwins_wch()\f1, \f4wins_wch()\f1\n@@@insert a complex character and rendition into a window .\" toc@\f4mvins_wch()\f1: insert a complex character and rendition into a window@@@see \f3ins_wch(3X)\f1 .\" toc@\f4mvwins_wch()\f1: insert a complex character and rendition into a window@@@see \f3ins_wch(3X)\f1 .\" toc@\f4wins_wch()\f1: insert a complex character and rendition into a window@@@see \f3ins_wch(3X)\f1 .\" .\" index@\f4ins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f4mvins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f4mvwins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f4wins_wch()\f1 \- insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1insert a complex character and rendition into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1complex character and rendition, insert into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1character and rendition, complex, insert into a window@@@\f3ins_wch(3X)\f1 .\" index@\f1window, insert a complex character and rendition into@@@\f3ins_wch(3X)\f1 .\" .\" links@ins_wch.3x mvins_wch.3x .\" links@ins_wch.3x mvwins_wch.3x .\" links@ins_wch.3x wins_wch.3x .\" .\" fileset_database@ins_wch.3x CURS-ENG-A-MAN .\" $Header: ins_nwstr.3x,v 76.2 95/08/01 11:23:53 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH ins_nwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ins_nwstr, ins_wstr, mvins_nwstr, mvins_wstr, mvwins_nwstr, mvwins_wstr, wins_nwstr, wins_wstr \(em insert a wide-character string into a window .SH SYNOPSIS .C "#include " .P .C "int ins_nwstr(wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int ins_wstr(wchar_t *const \f2wstr\fP);" .P .C "int mvins_nwstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvins_wstr(int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int mvwins_nwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int mvwins_wstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *const \f2wstr\fP);" .P .C "int wins_nwstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP, int \f2n\fP);" .P .C "int wins_wstr(WINDOW *\f2win\fP, wchar_t *const \f2wstr\fP);" .SH DESCRIPTION These functions insert a .B wchar_t character string (as many .B wchar_t characters as will fit on the line) in the current or specified window immediately before the current or specified position. .P Any non-spacing characters in the string are associated with the first spacing character in the string that precedes the non-spacing characters. If the first character in the string is a non-spacing character, these functions will fail. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing. .P The .CR ins_nwstr() , .CR mvins_nwstr() , .Fn mvwins_nwstr and .Fn wins_nwstr functions insert at most \f2n\f1 \f3wchar_t\f1 characters. If \f2n\f1 is less than 1, then the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3ins_nwstr(3X)\f1:\0\0\f4ins_nwstr()\f1, \f4ins_wstr()\f1, \f4mvins_nwstr()\f1, \f4mvins_wstr()\f1, \f4mvwins_nwstr()\f1, \n\f4mvwins_wstr()\f1, \f4wins_nwstr()\f1, \f4wins_wstr()\f1@@@insert a wide-character string into a window .\" toc@\f4ins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4mvwins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_wstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" toc@\f4wins_nwstr()\f1: insert a wide-character string into a window@@@see \f3ins_nwstr(3X)\f1 .\" .\" index@\f4ins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4ins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4mvwins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_nwstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f4wins_wstr()\f1 \- insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1wide-character string, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1string of wide-character, insert into a window@@@\f3ins_nwstr(3X)\f1 .\" index@\f1window, insert a wide-character string into@@@\f3ins_nwstr(3X)\f1 .\" index@\f1character, insert a wide-character string into a window@@@\f3ins_nwstr(3X)\f1 .\" .\" links@ins_nwstr.3x ins_wstr.3x .\" links@ins_nwstr.3x mvins_nwstr.3x .\" links@ins_nwstr.3x mvins_wstr.3x .\" links@ins_nwstr.3x mvwins_nwstr.3x .\" links@ins_nwstr.3x mvwins_wstr.3x .\" links@ins_nwstr.3x wins_nwstr.3x .\" links@ins_nwstr.3x wins_wstr.3x .\" .\" fileset_database@ins_nwstr.3x CURS-ENG-A-MAN .\" $Header: insch.3x,v 76.2 95/08/01 11:25:41 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insch 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insch, mvinsch, mvwinsch, winsch \(em insert a single-byte character and rendition into a window .SH SYNOPSIS .C "#include " .P .C "int insch(chtype \f2ch\fP);" .P .C "int mvinsch(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP);" .P .C "int mvwinsch(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP);" .P .C "int winsch(WINDOW *\f2win\fP, chtype \f2ch\fP);" .SH DESCRIPTION These functions insert the character and rendition from \f2ch\f1 into the current or specified window at the current or specified position. .P These functions do not perform wrapping. These functions do not advance the cursor position. These functions perform special-character processing, with the exception that if a newline is inserted into the last line of a window and scrolling is not enabled, the behaviour is unspecified. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" ins_wch(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" toc@\f3insch(3X)\f1:\0\0\f4insch()\f1, \f4mvinsch()\f1, \f4mvwinsch()\f1, \f4winsch()\f1\n@@@insert a single-byte character and rendition into a window .\" toc@\f4mvinsch()\f1: insert a single-byte character and rendition into a window@@@see \f3insch(3X)\f1 .\" toc@\f4mvwinsch()\f1: insert a single-byte character and rendition into a window@@@see \f3insch(3X)\f1 .\" toc@\f4winsch()\f1: insert a single-byte character and rendition into a window@@@see \f3insch(3X)\f1 .\" .\" index@\f4insch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f4mvinsch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f4mvwinsch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f4winsch()\f1 \- insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f1insert a single-byte character and rendition into a window@@@\f3insch(3X)\f1 .\" index@\f1single-byte character and rendition, insert into a window@@@\f3insch(3X)\f1 .\" index@\f1character and rendition, single-byte, insert into a window@@@\f3insch(3X)\f1 .\" index@\f1window, insert a single-byte character and rendition into@@@\f3insch(3X)\f1 .\" .\" links@insch.3x mvinsch.3x .\" links@insch.3x mvwinsch.3x .\" links@insch.3x winsch.3x .\" .\" fileset_database@insch.3x CURS-ENG-A-MAN .\" $Header: insdelln.3x,v 76.2 95/08/01 11:26:22 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insdelln 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insdelln, winsdelln \(em delete or insert lines into a window .SH SYNOPSIS .C "#include " .P .C "int insdelln(int \f2n\fP);" .P .C "int winsdelln(WINDOW *\f2win\fP, int \f2n\fP);" .SH DESCRIPTION The .Fn insdelln and .Fn winsdelln functions perform the following actions: .RS .TP 3 .C \(bu If \f2n\f1 is positive, these functions insert \f2n\f1 lines into the current or specified window before the current line. The \f2n\f1 last lines are no longer displayed. .TP .C \(bu If \f2n\f1 is negative, these functions delete \f2n\f1 lines from the current or specified window starting with the current line, and move the remaining lines toward the cursor. The last \f2n\f1 lines are cleared. .RE .P The current cursor position remains the same. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" deleteln(), insertln(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3insdelln(3X)\f1:\0\0\f4insdelln()\f1, \f4winsdelln()\f1@@@delete or insert lines into a window .\" toc@\f4winsdelln()\f1: delete or insert lines into a window@@@see \f3insdelln(3X)\f1 .\" .\" index@\f4insdelln()\f1 \- delete or insert lines into a window@@@\f3insdelln(3X)\f1 .\" index@\f4winsdelln()\f1 \- delete or insert lines into a window@@@\f3insdelln(3X)\f1 .\" index@\f1delete or insert lines into a window@@@\f3insdelln(3X)\f1 .\" index@\f1insert or delete lines into a window@@@\f3insdelln(3X)\f1 .\" index@\f1lines, delete or insert into a window@@@\f3insdelln(3X)\f1 .\" index@\f1window, delete or insert lines into@@@\f3insdelln(3X)\f1 .\" .\" links@insdelln.3x winsdelln.3x .\" .\" fileset_database@insdelln.3x CURS-ENG-A-MAN .\" $Header: insertln.3x,v 76.2 95/08/01 11:27:16 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insertln 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insertln, winsertln \(em insert lines into a window .SH SYNOPSIS .C "#include " .P .C "int insertln(void);" .P .C "int winsertln(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn insertln and .Fn winsertln functions insert a blank line before the current line in the current or specified window. The bottom line is no longer displayed. The cursor position does not change. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" insdelln(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. The argument list for the .Fn insertln function is explicitly declared as \f3void\f1. .\" .\" toc@\f3insertln(3X)\f1:\0\0\f4insertln()\f1, \f4winsertln()\f1@@@insert lines into a window .\" toc@\f4winsertln()\f1: insert lines into a window@@@see \f3insertln(3X)\f1 .\" .\" index@\f4insertln()\f1 \- insert lines into a window@@@\f3insertln(3X)\f1 .\" index@\f4winsertln()\f1 \- insert lines into a window@@@\f3insertln(3X)\f1 .\" index@\f1insert lines into a window@@@\f3insertln(3X)\f1 .\" index@\f1lines, insert into a window@@@\f3insertln(3X)\f1 .\" index@\f1window, insert lines into@@@\f3insertln(3X)\f1 .\" .\" links@insertln.3x winsertln.3x .\" .\" fileset_database@insertln.3x CURS-ENG-A-MAN .\" $Header: insnstr.3x,v 76.3 95/10/05 14:42:06 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insnstr, insstr, mvinsnstr, mvinsstr, mvwinsnstr, mvwinsstr, winsnstr, winsstr \(em insert a multi-byte character string into a window .SH SYNOPSIS .C "#include " .P .C "int insnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int insstr(char *const \f2str\fP);" .P .C "int mvinsnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvinsstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwinsnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwinsstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int winsnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int winsstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions insert a character string (as many characters as will fit on the line) before the current or specified position in the current or specified window. .P These functions do not advance the cursor position. These functions perform special-character processing. The .Fn innstr and .Fn innwstr functions perform wrapping. The .Fn instr and .Fn inswstr functions do not perform wrapping. .P The .CR insnstr() , .CR mvinsnstr() , .Fn mvwinsnstr and .Fn winsnstr functions insert .\" entire multi-byte characters contained in the first at most \f2n\f1 bytes. If \f2n\f1 is less than 1, the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since the string may contain multi-byte characters, there might not be a one-to-one correspondence between the number of column positions occupied by the characters and the number of bytes in the string. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3insnstr(3X)\f1:\0\0\f4insnstr()\f1, \f4insstr()\f1, \f4mvinsnstr()\f1, \f4mvinsstr()\f1, \f4mvwinsnstr()\f1, \f4mvwinsstr()\f1, \n\f4winsnstr()\f1, \f4winsstr()\f1@@@insert a multi-byte character into a window .\" toc@\f4insstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" .\" index@\f4insnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4insstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1multi-byte character, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1character, multi-byte, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1window, insert a multi-byte character into@@@\f3insnstr(3X)\f1 .\" .\" links@insnstr.3x insstr.3x .\" links@insnstr.3x mvinsnstr.3x .\" links@insnstr.3x mvinsstr.3x .\" links@insnstr.3x mvwinsnstr.3x .\" links@insnstr.3x mvwinsstr.3x .\" links@insnstr.3x winsnstr.3x .\" links@insnstr.3x winsstr.3x .\" .\" fileset_database@insnstr.3x CURS-ENG-A-MAN .\" $Header: insnstr.3x,v 76.3 95/10/05 14:42:06 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH insnstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME insnstr, insstr, mvinsnstr, mvinsstr, mvwinsnstr, mvwinsstr, winsnstr, winsstr \(em insert a multi-byte character string into a window .SH SYNOPSIS .C "#include " .P .C "int insnstr(char *const \f2str\fP, int \f2n\fP);" .P .C "int insstr(char *const \f2str\fP);" .P .C "int mvinsnstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvinsstr(int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int mvwinsnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int mvwinsstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *const \f2str\fP);" .P .C "int winsnstr(WINDOW *\f2win\fP, char *const \f2str\fP, int \f2n\fP);" .P .C "int winsstr(WINDOW *\f2win\fP, char *const \f2str\fP);" .SH DESCRIPTION These functions insert a character string (as many characters as will fit on the line) before the current or specified position in the current or specified window. .P These functions do not advance the cursor position. These functions perform special-character processing. The .Fn innstr and .Fn innwstr functions perform wrapping. The .Fn instr and .Fn inswstr functions do not perform wrapping. .P The .CR insnstr() , .CR mvinsnstr() , .Fn mvwinsnstr and .Fn winsnstr functions insert .\" entire multi-byte characters contained in the first at most \f2n\f1 bytes. If \f2n\f1 is less than 1, the entire string is inserted. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since the string may contain multi-byte characters, there might not be a one-to-one correspondence between the number of column positions occupied by the characters and the number of bytes in the string. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3insnstr(3X)\f1:\0\0\f4insnstr()\f1, \f4insstr()\f1, \f4mvinsnstr()\f1, \f4mvinsstr()\f1, \f4mvwinsnstr()\f1, \f4mvwinsstr()\f1, \n\f4winsnstr()\f1, \f4winsstr()\f1@@@insert a multi-byte character into a window .\" toc@\f4insstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4mvwinsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsnstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" toc@\f4winsstr()\f1: insert a multi-byte character into a window@@@see \f3insnstr(3X)\f1 .\" .\" index@\f4insnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4insstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4mvwinsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsnstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f4winsstr()\f1 \- insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1insert a multi-byte character into a window@@@\f3insnstr(3X)\f1 .\" index@\f1multi-byte character, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1character, multi-byte, insert into a window@@@\f3insnstr(3X)\f1 .\" index@\f1window, insert a multi-byte character into@@@\f3insnstr(3X)\f1 .\" .\" links@insnstr.3x insstr.3x .\" links@insnstr.3x mvinsnstr.3x .\" links@insnstr.3x mvinsstr.3x .\" links@insnstr.3x mvwinsnstr.3x .\" links@insnstr.3x mvwinsstr.3x .\" links@insnstr.3x winsnstr.3x .\" links@insnstr.3x winsstr.3x .\" .\" fileset_database@insnstr.3x CURS-ENG-A-MAN .\" $Header: innstr.3x,v 76.2 95/08/01 11:22:05 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innstr, instr, mvinnstr, mvinstr, mvwinnstr, mvwinstr, winnstr, winstr \(em input a multi-byte character string from a window .SH SYNOPSIS .C "#include " .P .C "int innstr(char *\f2str\fP, int \f2n\fP);" .P .C "int instr(char *\f2str\fP);" .P .C "int mvinnstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvinstr(int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int mvwinnstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int mvwinstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2str\fP);" .P .C "int winnstr(WINDOW *\f2win\fP, char *\f2str\fP, int \f2n\fP);" .P .C "int winstr(WINDOW *\f2win\fP, char *\f2str\fP);" .SH DESCRIPTION These functions place a string of characters from the current or specified window into the array pointed to by \f2str\fP, starting at the current or specified position and ending at the end of the line. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions store at most \f2n\f1 bytes in the string pointed to by \f2str\f1. .P The .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr functions will only store the entire multi-byte sequence associated with a character. If the array is large enough to contain at least one character the array is filled with complete characters. If the array is not large enough to contain any complete characters, the function fails. .SH "RETURN VALUE" Upon successful completion, .CR instr() , .CR mvinstr() , .Fn mvwinstr and .Fn winstr return OK. .P Upon successful completion, .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr and .Fn winnstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Since multi-byte characters may be processed, there might not be a one-to-one correspondence between the number of column positions on the screen and the number of bytes returned. .P These functions do not return rendition information. .P Reading a line that overflows the array pointed to by \f2str\f1 with .CR instr() , .CR mvinstr() , .Fn mvwinstr or .Fn winstr causes undefined results. The use of .CR innstr() , .CR mvinnstr() , .Fn mvwinnstr or .CR winnstr() , respectively, is recommended. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innstr(3X)\f1:\0\0\f4innstr()\f1, \f4instr()\f1, \f4mvinnstr()\f1, \f4mvinstr()\f1, \f4mvwinnstr()\f1, \f4mvwinstr()\f1, \f4winnstr()\f1, \n\f4winstr()\f1@@@input a multi-byte character string from a window .\" toc@\f4instr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4mvwinnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" toc@\f4winnstr()\f1: input a multi-byte character string from a window@@@see \f3innstr(3X)\f1 .\" .\" index@\f4innstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4instr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4mvwinstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winnstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f4winstr()\f1 \- input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1input a multi-byte character string from a window@@@\f3innstr(3X)\f1 .\" index@\f1multi-byte character string, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1character string, multi-byte, input from a window@@@\f3innstr(3X)\f1 .\" index@\f1window, input a multi-byte character string from@@@\f3innstr(3X)\f1 .\" .\" links@innstr.3x instr.3x .\" links@innstr.3x mvinstr.3x .\" links@innstr.3x mvinnstr.3x .\" links@innstr.3x mvwinstr.3x .\" links@innstr.3x mvwinnstr.3x .\" links@innstr.3x winstr.3x .\" links@innstr.3x winnstr.3x .\" .\" fileset_database@innstr.3x CURS-ENG-A-MAN .\" $Header: innwstr.3x,v 76.2 95/08/01 11:22:59 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH innwstr 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME innwstr, inwstr, mvinnwstr, mvinwstr, mvwinnwstr, mvwinwstr, winnwstr, winwstr \(em input a string of wide characters from a window .SH SYNOPSIS .C "#include " .P .C "int innwstr(wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int inwstr(wchar_t *\f2wstr\fP);" .P .C "int mvinnwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvinwstr(int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int mvwinnwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int mvwinwstr(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, wchar_t *\f2wstr\fP);" .P .C "int winnwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP, int \f2n\fP);" .P .C "int winwstr(WINDOW *\f2win\fP, wchar_t *\f2wstr\fP);" .SH DESCRIPTION These functions place a string of \f3wchar_t\f1 characters from the current or specified window into the array pointed to by \f2wstr\f1 starting at the current or specified cursor position and ending at the end of the line. .P These functions will only store the entire wide character sequence associated with a spacing complex character. If the array is large enough to contain at least one complete spacing complex character, the array is filled with complete characters. If the array is not large enough to contain any complete characters this is an error. .P The .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr functions store at most \f2n\f1 characters in the array pointed to by \f2wstr\f1. .SH "RETURN VALUE" Upon successful completion, .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr and .Fn winwstr return OK. .P Upon successful completion, .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr and .Fn winnwstr return the number of characters actually read into the string. .P Otherwise, all these functions return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Reading a line that overflows the array pointed to by \f2wstr\f1 with .CR inwstr() , .CR mvinwstr() , .Fn mvwinwstr or .Fn winwstr causes undefined results. The use of .CR innwstr() , .CR mvinnwstr() , .Fn mvwinnwstr or .CR winnwstr() , respectively, is recommended. .P These functions do not return rendition information. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3innwstr(3X)\f1:\0\0\f4innwstr()\f1, \f4inwstr()\f1, \f4mvinnwstr()\f1, \f4mvinwstr()\f1, \f4mvwinnwstr()\f1, \f4mvwinwstr()\f1, \n\f4winnwstr()\f1, \f4winwstr()\f1@@@input a string of wide characters from a window .\" toc@\f4innwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4inwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4mvwinwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winnwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" toc@\f4winwstr()\f1: input a string of wide characters from a window@@@see \f3innwstr(3X)\f1 .\" .\" index@\f4innwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4inwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4mvwinwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winnwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f4winwstr()\f1 \- input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1input a string of wide characters from a window@@@\f3innwstr(3X)\f1 .\" index@\f1string of wide characters, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1wide characters, string of, input from a window@@@\f3innwstr(3X)\f1 .\" index@\f1window, input a string of wide characters from@@@\f3innwstr(3X)\f1 .\" index@\f1characters, wide, input a string of, from a window@@@\f3innwstr(3X)\f1 .\" .\" links@innwstr.3x inwstr.3x .\" links@innwstr.3x mvinnwstr.3x .\" links@innwstr.3x mvinwstr.3x .\" links@innwstr.3x mvwinnwstr.3x .\" links@innwstr.3x mvwinwstr.3x .\" links@innwstr.3x winnwstr.3x .\" links@innwstr.3x winwstr.3x .\" .\" fileset_database@innwstr.3x CURS-ENG-A-MAN .\" $Header: move.3x,v 76.2 95/08/01 11:46:48 ssa Exp $ .TA m .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH move 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME move, wmove \(em window cursor location functions .SH SYNOPSIS .C "#include " .P .C "int move(int \f2y\fP, int \f2x\fP);" .P .C "int wmove(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP);" .SH DESCRIPTION The .Fn move and .Fn wmove functions move the cursor associated with the current or specified window to (\f2y\f1, \f2x\f1) relative to the window's origin. This function does not move the terminal's cursor until the next refresh operation. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity. .\" .\" toc@\f3move(3X)\f1:\0\0\f4move()\f1, \f4wmove()\f1@@@window cursor location functions .\" toc@\f4wmove()\f1: window cursor location functions@@@see \f3move(3X)\f1 .\" .\" index@\f4move()\f1 \- window cursor location functions@@@\f3move(3X)\f1 .\" index@\f4wmove()\f1 \- window cursor location functions@@@\f3move(3X)\f1 .\" index@\f1window cursor location functions@@@\f3move(3X)\f1 .\" index@\f1cursor, window location functions@@@\f3move(3X)\f1 .\" index@\f1location functions, window cursor@@@\f3move(3X)\f1 .\" index@\f1functions, window cursor location@@@\f3move(3X)\f1 .\" .\" links@move.3x wmove.3x .\" .\" fileset_database@move.3x CURS-ENG-A-MAN .\" $Header: doupdate.3x,v 76.2 95/08/01 15:14:36 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH doupdate 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME doupdate, refresh, wnoutrefresh, wrefresh \(em refresh windows and lines .SH SYNOPSIS .C "#include " .P .C "int doupdate(void);" .P .C "int refresh(void);" .P .C "int wnoutrefresh(WINDOW *\f2win\fP);" .P .C "int wrefresh(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn refresh and .Fn wrefresh functions refresh the current or specified window. The functions position the terminal's cursor at the cursor position of the window, except that if the .Fn leaveok mode has been enabled, they may leave the cursor at an arbitrary position. .P The .Fn wnoutrefresh function determines which parts of the terminal may need updating. The .Fn doupdate function sends to the terminal the commands to perform any required changes. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Refreshing an entire window is typically more efficient than refreshing several subwindows separately. An efficient sequence is to call .Fn wnoutrefresh on each subwindow that has changed, followed by a call to .Fn doupdate , which updates the terminal. .P The .Fn refresh or .Fn wrefresh function (or .Fn wnoutrefresh followed by .Fn doupdate ) must be called to send output to the terminal, as other Curses functions merely manipulate data structures. .SH "SEE ALSO" clearok(), redrawwin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .P This entry is a merger of the X/Open Curses, Issue 3 entries .Fn refresh and .Fn wnoutrefresh . The .B DESCRIPTION is rewritten for clarity and the argument list for the .Fn doupdate and .Fn refresh functions is explicitly declared as \f3void\f1. Otherwise the functionality is identical to that defined in X/Open Curses, Issue 3. .\" .\" toc@\f3doupdate(3x)\f1:\0\0\f4doupdate()\f1, \f4refresh()\f1, \f4wnoutrefresh()\f1, \f4wrefresh()\f1@@@refresh windows and lines .\" .\" toc@\f3refresh()\f1:\0\0refresh windows and lines@@@\f1see \f3doupdate(3x)\f1 .\" toc@\f3wnoutrefresh()\f1:\0\0refresh windows and lines@@@\f1see \f3doupdate(3x)\f1 .\" toc@\f3wrefresh()\f1:\0\0refresh windows and lines@@@\f1see \f3doupdate(3x)\f1 .\" .\" index@\f4doupdate()\f1, \f4refresh()\f1, \f4wnoutrefresh()\f1, \n\f4wrefresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" index@\f4refresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" index@\f4wnoutrefresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" index@\f4wrefresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" .\" links@doupdate.3x refresh.3x .\" links@doupdate.3x wnoutrefresh.3x .\" links@doupdate.3x wrefresh.3x .\" .\" fileset_database@doupdate.3x CURS-ENG-A-MAN .\" $Header: wordexp.3c,v 72.5 94/11/15 09:57:17 ssa Exp $ .TA w .TH wordexp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wordexp(), wordfree() \- perform word expansions .SH SYNOPSIS .C "#include " .PP .C "int wordexp(const char *words, wordexp_t *pwordexp, int flags);" .PP .C "void wordfree(wordexp_t *pwordexp);" .SH DESCRIPTION .CR wordexp() performs word expansions and places the list of expanded words into the structure pointed to by .IR pwordexp . .PP The .IR words argument is a pointer to a string containing one or more words to be expanded. The expansions are the same as would be performed by the shell (see .IR sh-posix (1)), if words were the part of a command line representing the arguments to a utility. Therefore, .I words must not contain an unquoted newline character or any of the unquoted shell special characters .CR | , .CR & , .CR ; , .CR < or .CR > , except in the context of shell command substitution. If .IR words contains an unquoted comment character, .CR # , it is treated as the beginning of a token that .CR wordexp() interprets as a comment indicator, causing the remainder of .I words to be ignored. .PP The structure type .CR wordexp_t is defined in the header .CR , and includes the following members: .RS .TP 20 .C we_wordc A .CR size_t used to keep count of words matched by .IR words . .TP .C we_wordv A .CR char** used as a pointer to a list of expanded words. .TP .C we_offs Also a .CR size_t used to indicate the number of slots to reserve at the beginning of .CR pwordexp\->we_wordv . .RE .PP .CR wordexp() stores the number of generated words into .CR pwordexp\->we_wordc . Each individual field created during field splitting or path name expansion is a separated word in the .CR pwordexp\->we_wordv list. The words are in order as described in shell word expansions. The first pointer after the last word pointer is a null pointer. .PP It is the caller's responsibility to allocate the storage pointed to by .IR pwordexp . .CR wordexp() allocates other space as needed, including memory pointed to by .CR pwordexp\->we_wordv . .PP .CR wordfree() frees any memory associated with .I pwordexp from a previous call to .CR wordexp() . .PP The .IR flags argument is used to control the behavior of .CR wordexp() . The value of flags is the bitwise inclusive OR of zero or more of the following constants, which are defined in .CR : .RS .TP 20 .C WRDE_APPEND Append words generated to the ones from a previous call to .CR wordexp() . .TP .C WRDE_DOOFFS Make use of .CR pwordexp\->we_offs . If this flag is set, .CR pwordexp\->we_offs is used to specify how many null pointers to add to the beginning of .CR pwordexp\->we_wordv . In other words, .CR pwordexp\->we_wordv points to .CR pwordexp\->we_offs null pointers, followed by .CR pwordexp\->we_wordc word pointers, followed by a null pointer. .TP .C WRDE_NOCMD Fail if command substitution is requested. .TP .C WRDE_REUSE The .I pwordexp argument was passed to a previous successful call to .CR wordexp() , and has not been passed to .CR wordfree() . The result is the same as if the application had called .CR wordfree() and then called .CR wordexp() without .CR WRDE_REUSE . .TP .C WRDE_SHOWERR Do not redirect .IR stderr to .CR /dev/null . .TP .C WRDE_UNDEF Report error on an attempt to expand an undefined shell variable. .RE .PP The .CR WRDE_APPEND flag can be used to append a new set of words to those generated by a previous call to .CR wordexp() . The following rules apply when two or more calls to .CR wordexp() are made with the same value of .I pwordexp and without intervening calls to .CR wordfree() : .RS .TP 3 \(bu The first call must not set .CR WRDE_APPEND . All subsequent calls must set it. .TP \(bu All of the calls must set .CR WRDE_DOOFFS , or all must not set it. .TP \(bu After the second and each subsequent call, .CR pwordexp\->we_wordv points to a list containing the following: .RS .RS .TP 3 \(bu Zero or more null pointers, as specified by .CR WRED_DOOFFS and .CR pwordexp\->we_offs . .TP \(bu Pointers to the words that were in the .CR pwordexp\->we_wordv list before the call, in the same order as before. .TP \(bu Pointers to the new words generated by the latest call, in the specified order. .RE .RE .TP 3 \(bu The count returned in .CR pwordexp\->we_wordc is the total number of words from all of the calls. .TP \(bu The application can change any of the fields after a call to .CR wordexp() , but if it does, it must reset them to the original value before a subsequent call, using the same .IR pwordexp value, to .CR wordfree() or .CR wordexp() with the .CR WRDE_APPEND or .CR WRDE_REUSE flag. .RE .PP If .IR words contains an unquoted newline, .CR | , .CR & , .CR ; , .CR < , .CR > , parentheses, or curly brackets in an inappropriate context, .CR wordexp() fails, and the number of expanded words is zero. .PP Unless .CR WRDE_SHOWERR is set in .IR flags , .CR wordexp() redirects .IR stderr to .CR /dev/null for any utilities executed as a result of command substitution while expanding .IR words . If .CR WRDE_SHOWERR is set, .CR wordexp() writes messages to .IR stderr if syntax errors are detected while expanding .IR words . .PP If .CR WRDE_DOOFFS is set, .CR pwordexp\->we_offs has the same value for each .CR wordexp() call and the .CR wordfree() call using a given .CR wordexp() . .SH RETURN VALUE Upon successful completion, .CR wordexp() returns zero; otherwise, it returns a nonzero value defined in .CR to indicate the error: .RS .TP 20 .C WRDE_BADCHAR One of the unquoted characters .CR | , .CR & , .CR ; , .CR < , .CR > , parentheses, or braces appears in .IR words in an inappropriate context. .TP .C WRDE_BADVAL Reference to undefined shell variable when .CR WRDE_UNDEF is set in .IR flags . .TP .C WRDE_CMDSUB Command substitution requested when .CR WRDE_NOCMD was set in .IR flags . .TP .CR WRDE_NOSPACE Attempt to allocate memory failed. .TP .C WRDE_SYNTAX Shell syntax error such as unbalanced parentheses or unterminated string. .TP .C WRDE_INTERNAL Internal error. .RE .PP If .CR wordexp() returns the error value .CR WRDE_NOSPACE , .CR pwordexp\->we_wordc and .CR pwordexp\->we_wordv are updated to reflect any words that were successfully expanded. In other cases, they are not modified. .SH AUTHOR .CR wordexp() and .CR wordfree() were developed by OSF and HP. .SH SEE ALSO sh-posix(1), fnmatch(3C), glob(3C), regexp(5). .SH STANDARDS CONFORMANCE .CR wordexp() ": XPG4, POSIX.2" .PP .CR wordfree() ": XPG4, POSIX.2" .\" .\" toc@\f3wordexp(3C)\f1:\0\0\f4wordexp()\f1, \f4wordfree()\f1@@@perform word expansions\f1 .\" toc@\f4wordfree()\f1:\0\0free memory associated with word expansions@@@\f1see \f3wordexp(3C)\f1 .\" .\" index@\f4wordexp()\f1 \- perform word expansions@@@\f3wordexp(3C)\f1 .\" index@\f4wordfree()\f1 \- free memory associated with word expansions@@@\f3wordexp(3C)\f1 .\" index@\f1perform word expansions@@@\f3wordexp(3C)\f1 .\" index@\f1word expansions, perform@@@\f3wordexp(3C)\f1 .\" index@\f1expansions, perform word@@@\f3wordexp(3C)\f1 .\" index@\f1free memory associated with word expansions@@@\f3wordexp(3C)\f1 .\" .\" links@wordexp.3c wordfree.3c .\" $Header: wordexp.3c,v 72.5 94/11/15 09:57:17 ssa Exp $ .TA w .TH wordexp 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wordexp(), wordfree() \- perform word expansions .SH SYNOPSIS .C "#include " .PP .C "int wordexp(const char *words, wordexp_t *pwordexp, int flags);" .PP .C "void wordfree(wordexp_t *pwordexp);" .SH DESCRIPTION .CR wordexp() performs word expansions and places the list of expanded words into the structure pointed to by .IR pwordexp . .PP The .IR words argument is a pointer to a string containing one or more words to be expanded. The expansions are the same as would be performed by the shell (see .IR sh-posix (1)), if words were the part of a command line representing the arguments to a utility. Therefore, .I words must not contain an unquoted newline character or any of the unquoted shell special characters .CR | , .CR & , .CR ; , .CR < or .CR > , except in the context of shell command substitution. If .IR words contains an unquoted comment character, .CR # , it is treated as the beginning of a token that .CR wordexp() interprets as a comment indicator, causing the remainder of .I words to be ignored. .PP The structure type .CR wordexp_t is defined in the header .CR , and includes the following members: .RS .TP 20 .C we_wordc A .CR size_t used to keep count of words matched by .IR words . .TP .C we_wordv A .CR char** used as a pointer to a list of expanded words. .TP .C we_offs Also a .CR size_t used to indicate the number of slots to reserve at the beginning of .CR pwordexp\->we_wordv . .RE .PP .CR wordexp() stores the number of generated words into .CR pwordexp\->we_wordc . Each individual field created during field splitting or path name expansion is a separated word in the .CR pwordexp\->we_wordv list. The words are in order as described in shell word expansions. The first pointer after the last word pointer is a null pointer. .PP It is the caller's responsibility to allocate the storage pointed to by .IR pwordexp . .CR wordexp() allocates other space as needed, including memory pointed to by .CR pwordexp\->we_wordv . .PP .CR wordfree() frees any memory associated with .I pwordexp from a previous call to .CR wordexp() . .PP The .IR flags argument is used to control the behavior of .CR wordexp() . The value of flags is the bitwise inclusive OR of zero or more of the following constants, which are defined in .CR : .RS .TP 20 .C WRDE_APPEND Append words generated to the ones from a previous call to .CR wordexp() . .TP .C WRDE_DOOFFS Make use of .CR pwordexp\->we_offs . If this flag is set, .CR pwordexp\->we_offs is used to specify how many null pointers to add to the beginning of .CR pwordexp\->we_wordv . In other words, .CR pwordexp\->we_wordv points to .CR pwordexp\->we_offs null pointers, followed by .CR pwordexp\->we_wordc word pointers, followed by a null pointer. .TP .C WRDE_NOCMD Fail if command substitution is requested. .TP .C WRDE_REUSE The .I pwordexp argument was passed to a previous successful call to .CR wordexp() , and has not been passed to .CR wordfree() . The result is the same as if the application had called .CR wordfree() and then called .CR wordexp() without .CR WRDE_REUSE . .TP .C WRDE_SHOWERR Do not redirect .IR stderr to .CR /dev/null . .TP .C WRDE_UNDEF Report error on an attempt to expand an undefined shell variable. .RE .PP The .CR WRDE_APPEND flag can be used to append a new set of words to those generated by a previous call to .CR wordexp() . The following rules apply when two or more calls to .CR wordexp() are made with the same value of .I pwordexp and without intervening calls to .CR wordfree() : .RS .TP 3 \(bu The first call must not set .CR WRDE_APPEND . All subsequent calls must set it. .TP \(bu All of the calls must set .CR WRDE_DOOFFS , or all must not set it. .TP \(bu After the second and each subsequent call, .CR pwordexp\->we_wordv points to a list containing the following: .RS .RS .TP 3 \(bu Zero or more null pointers, as specified by .CR WRED_DOOFFS and .CR pwordexp\->we_offs . .TP \(bu Pointers to the words that were in the .CR pwordexp\->we_wordv list before the call, in the same order as before. .TP \(bu Pointers to the new words generated by the latest call, in the specified order. .RE .RE .TP 3 \(bu The count returned in .CR pwordexp\->we_wordc is the total number of words from all of the calls. .TP \(bu The application can change any of the fields after a call to .CR wordexp() , but if it does, it must reset them to the original value before a subsequent call, using the same .IR pwordexp value, to .CR wordfree() or .CR wordexp() with the .CR WRDE_APPEND or .CR WRDE_REUSE flag. .RE .PP If .IR words contains an unquoted newline, .CR | , .CR & , .CR ; , .CR < , .CR > , parentheses, or curly brackets in an inappropriate context, .CR wordexp() fails, and the number of expanded words is zero. .PP Unless .CR WRDE_SHOWERR is set in .IR flags , .CR wordexp() redirects .IR stderr to .CR /dev/null for any utilities executed as a result of command substitution while expanding .IR words . If .CR WRDE_SHOWERR is set, .CR wordexp() writes messages to .IR stderr if syntax errors are detected while expanding .IR words . .PP If .CR WRDE_DOOFFS is set, .CR pwordexp\->we_offs has the same value for each .CR wordexp() call and the .CR wordfree() call using a given .CR wordexp() . .SH RETURN VALUE Upon successful completion, .CR wordexp() returns zero; otherwise, it returns a nonzero value defined in .CR to indicate the error: .RS .TP 20 .C WRDE_BADCHAR One of the unquoted characters .CR | , .CR & , .CR ; , .CR < , .CR > , parentheses, or braces appears in .IR words in an inappropriate context. .TP .C WRDE_BADVAL Reference to undefined shell variable when .CR WRDE_UNDEF is set in .IR flags . .TP .C WRDE_CMDSUB Command substitution requested when .CR WRDE_NOCMD was set in .IR flags . .TP .CR WRDE_NOSPACE Attempt to allocate memory failed. .TP .C WRDE_SYNTAX Shell syntax error such as unbalanced parentheses or unterminated string. .TP .C WRDE_INTERNAL Internal error. .RE .PP If .CR wordexp() returns the error value .CR WRDE_NOSPACE , .CR pwordexp\->we_wordc and .CR pwordexp\->we_wordv are updated to reflect any words that were successfully expanded. In other cases, they are not modified. .SH AUTHOR .CR wordexp() and .CR wordfree() were developed by OSF and HP. .SH SEE ALSO sh-posix(1), fnmatch(3C), glob(3C), regexp(5). .SH STANDARDS CONFORMANCE .CR wordexp() ": XPG4, POSIX.2" .PP .CR wordfree() ": XPG4, POSIX.2" .\" .\" toc@\f3wordexp(3C)\f1:\0\0\f4wordexp()\f1, \f4wordfree()\f1@@@perform word expansions\f1 .\" toc@\f4wordfree()\f1:\0\0free memory associated with word expansions@@@\f1see \f3wordexp(3C)\f1 .\" .\" index@\f4wordexp()\f1 \- perform word expansions@@@\f3wordexp(3C)\f1 .\" index@\f4wordfree()\f1 \- free memory associated with word expansions@@@\f3wordexp(3C)\f1 .\" index@\f1perform word expansions@@@\f3wordexp(3C)\f1 .\" index@\f1word expansions, perform@@@\f3wordexp(3C)\f1 .\" index@\f1expansions, perform word@@@\f3wordexp(3C)\f1 .\" index@\f1free memory associated with word expansions@@@\f3wordexp(3C)\f1 .\" .\" links@wordexp.3c wordfree.3c .\" $Header: mvprintw.3x,v 76.2 95/08/01 11:56:52 ssa Exp $ .TA m .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH mvprintw 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mvprintw, mvwprintw, printw, wprintw \(em print formatted output in window .SH SYNOPSIS .C "#include " .P .C "int mvprintw(int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int mvwprintw(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int printw(char *\f2fmt\fP, ...);" .P .C "int wprintw(WINDOW *\f2win\fP, char *\f2fmt\fP, ...);" .SH DESCRIPTION The .CR mvprintw() , .CR mvwprintw() , .Fn printw and .Fn wprintw functions are analogous to .CR printf() . The effect of these functions is as though .Fn sprintf were used to format the string, and then .Fn waddstr were used to add that multi-byte string to the current or specified window at the current or specified cursor position. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" addnstr(), fprintf() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity and its name is changed from .Fn printw to .CR mvprintw() . .\" .\" toc@\f3mvprintw(3X)\f1:\0\0\f4mvprintw()\f1, \f4mvwprintw()\f1, \f4printw()\f1, \f4wprintw\f1@@@print formatted output in window .\" toc@\f4mvwprintw()\f1: print formatted output in window@@@see \f3mvprintw(3X)\f1 .\" toc@\f4printw()\f1: print formatted output in window@@@see \f3mvprintw(3X)\f1 .\" toc@\f4wprintw()\f1: print formatted output in window@@@see \f3mvprintw(3X)\f1 .\" .\" index@\f4mvprintw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f4mvwprintw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f4printw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f4wprintw()\f1 \- print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f1print formatted output in window@@@\f3mvprintw(3X)\f1 .\" index@\f1formatted output, print in window@@@\f3mvprintw(3X)\f1 .\" index@\f1output, formatted, print in window@@@\f3mvprintw(3X)\f1 .\" index@\f1window, print formatted output in@@@\f3mvprintw(3X)\f1 .\" .\" links@mvprintw.3x mvwprintw.3x .\" links@mvprintw.3x printw.3x .\" links@mvprintw.3x wprintw.3x .\" .\" fileset_database@mvprintw.3x CURS-ENG-A-MAN .\" $Header: redrawwin.3x,v 76.2 95/08/01 14:37:40 ssa Exp $ .TA r .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH redrawwin 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME redrawwin, wredrawln \(em line update status functions .SH SYNOPSIS .C "#include " .P .C "int redrawwin(WINDOW *\f2win\fP);" .P .C "int wredrawln(WINDOW *\f2win\fP, int \f2beg_line\fP, int \f2num_lines\fP);" .SH DESCRIPTION The .Fn redrawwin and .Fn wredrawln functions inform the implementation that some or all of the information physically displayed for the specified window may have been corrupted. The .Fn redrawwin function marks the entire window; .Fn wredrawln marks only \f2num_lines\f1 lines starting at line number \f2beg_line\f1. The functions prevent the next refresh operation on that window from performing any optimisation based on assumptions about what is physically displayed there. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The .Fn redrawwin and .Fn wredrawln functions could be used in a text editor to implement a command that redraws some or all of the screen. .SH "SEE ALSO" clearok(), doupdate(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3redrawwin(3X)\f1:\0\0\f4redrawwin()\f1, \f4wredrawln()\f1@@@line update status functions .\" toc@\f4wredrawln()\f1: line update status functions@@@see \f3redrawwin(3X)\f1 .\" .\" index@\f4redrawwin()\f1 \- line update status functions@@@\f3redrawwin(3X)\f1 .\" index@\f4wredrawln()\f1 \- line update status functions@@@\f3redrawwin(3X)\f1 .\" index@\f1line update status functions@@@\f3redrawwin(3X)\f1 .\" index@\f1functions, for line update status@@@\f3redrawwin(3X)\f1 .\" index@\f1update status, line, functions@@@\f3redrawwin(3X)\f1 .\" index@\f1status, line update status functions@@@\f3redrawwin(3X)\f1 .\" .\" links@redrawwin.3x wredrawln.3x .\" .\" fileset_database@redrawwin.3x CURS-ENG-A-MAN .\" $Header: doupdate.3x,v 76.2 95/08/01 15:14:36 ssa Exp $ .TA d .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH doupdate 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME doupdate, refresh, wnoutrefresh, wrefresh \(em refresh windows and lines .SH SYNOPSIS .C "#include " .P .C "int doupdate(void);" .P .C "int refresh(void);" .P .C "int wnoutrefresh(WINDOW *\f2win\fP);" .P .C "int wrefresh(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn refresh and .Fn wrefresh functions refresh the current or specified window. The functions position the terminal's cursor at the cursor position of the window, except that if the .Fn leaveok mode has been enabled, they may leave the cursor at an arbitrary position. .P The .Fn wnoutrefresh function determines which parts of the terminal may need updating. The .Fn doupdate function sends to the terminal the commands to perform any required changes. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Refreshing an entire window is typically more efficient than refreshing several subwindows separately. An efficient sequence is to call .Fn wnoutrefresh on each subwindow that has changed, followed by a call to .Fn doupdate , which updates the terminal. .P The .Fn refresh or .Fn wrefresh function (or .Fn wnoutrefresh followed by .Fn doupdate ) must be called to send output to the terminal, as other Curses functions merely manipulate data structures. .SH "SEE ALSO" clearok(), redrawwin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .P This entry is a merger of the X/Open Curses, Issue 3 entries .Fn refresh and .Fn wnoutrefresh . The .B DESCRIPTION is rewritten for clarity and the argument list for the .Fn doupdate and .Fn refresh functions is explicitly declared as \f3void\f1. Otherwise the functionality is identical to that defined in X/Open Curses, Issue 3. .\" .\" toc@\f3doupdate(3x)\f1:\0\0\f4doupdate()\f1, \f4refresh()\f1, \f4wnoutrefresh()\f1, \f4wrefresh()\f1@@@refresh windows and lines .\" .\" toc@\f3refresh()\f1:\0\0refresh windows and lines@@@\f1see \f3doupdate(3x)\f1 .\" toc@\f3wnoutrefresh()\f1:\0\0refresh windows and lines@@@\f1see \f3doupdate(3x)\f1 .\" toc@\f3wrefresh()\f1:\0\0refresh windows and lines@@@\f1see \f3doupdate(3x)\f1 .\" .\" index@\f4doupdate()\f1, \f4refresh()\f1, \f4wnoutrefresh()\f1, \n\f4wrefresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" index@\f4refresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" index@\f4wnoutrefresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" index@\f4wrefresh()\f1 \- refresh windows and lines@@@\f3doupdate(3x)\f1 .\" .\" links@doupdate.3x refresh.3x .\" links@doupdate.3x wnoutrefresh.3x .\" links@doupdate.3x wrefresh.3x .\" .\" fileset_database@doupdate.3x CURS-ENG-A-MAN .\" $Header: mvscanw.3x,v 76.2 95/08/01 11:58:38 ssa Exp $ .TA m .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH mvscanw 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME mvscanw, mvwscanw, scanw, wscanw \(em convert formatted input from a window .SH SYNOPSIS .C "#include " .P .C "int mvscanw(int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int mvwscanw(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, char *\f2fmt\fP, ...);" .P .C "int scanw(char *\f2fmt\fP, ...);" .P .C "int wscanw(WINDOW *\f2win\fP, char *\f2fmt\fP, ...);" .SH DESCRIPTION These functions are similar to .CR scanf() . Their effect is as though .Fn mvwgetstr were called to get a multi-byte character string from the current or specified window at the current or specified cursor position, and then .Fn sscanf were used to interpret and convert that string. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" getnstr(), printw(), fscanf() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), wcstombs() (in the \f3X/Open System Interfaces and Headers, Issue 4, Version 2\f1 specification ), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The entry is rewritten for clarity and its name is changed from .Fn scanw to .CR mvscanw() . .\" .\" toc@\f3mvscanw(3X)\f1:\0\0\f4mvscanw()\f1, \f4mvwscanw()\f1, \f4scanw()\f1, \f4wscanw()\f1@@@convert formatted input from a window .\" toc@\f4mvwscanw()\f1: convert formatted input from a window@@@see \f3mvscanw(3X)\f1 .\" toc@\f4scanw()\f1: convert formatted input from a window@@@see \f3mvscanw(3X)\f1 .\" toc@\f4wscanw()\f1: convert formatted input from a window@@@see \f3mvscanw(3X)\f1 .\" .\" index@\f4mvscanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f4mvwscanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f4scanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f4wscanw()\f1 \- convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1convert formatted input from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1formatted input, convert, from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1input, convert formatted, from a window@@@\f3mvscanw(3X)\f1 .\" index@\f1window, convert formatted input from@@@\f3mvscanw(3X)\f1 .\" .\" links@mvscanw.3x mvwscanw.3x .\" links@mvscanw.3x scanw.3x .\" links@mvscanw.3x wscanw.3x .\" .\" fileset_database@mvscanw.3x CURS-ENG-A-MAN .\" $Header: scrl.3x,v 76.2 95/08/01 14:41:42 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH scrl 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME scrl, wscrl \(em enhanced scroll a Curses window functions .SH SYNOPSIS .C "#include " .P .C "int scrl(int \f2n\fP);" .P .C "int wscrl(WINDOW *\f2win\fP, int \f2n\fP);" .SH DESCRIPTION .P The .Fn scrl and .Fn wscrl functions scroll the current or specified window. If \f2n\f1 is positive, the window scrolls \f2n\f1 lines toward the first line. Otherwise, the window scrolls \(mi\f2n\f1 lines toward the last line. .P These functions do not change the cursor position. If scrolling is disabled for the current or specified window, these functions have no effect. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3scrl(3X)\f1:\0\0\f4scrl()\f1, \f4wscrl()\f1@@@enhanced scroll a curses window functions .\" toc@\f4wscrl()\f1: scroll the window, enhanced curses@@@see \f3scrl(3X)\f1 .\" .\" index@\f4scrl()\f1 \- scroll the window, enhanced curses@@@\f3scrl(3X)\f1 .\" index@\f4wscrl()\f1 \- scroll the window, enhanced curses@@@\f3scrl(3X)\f1 .\" index@\f1scroll the window, enhanced curses@@@\f3scrl(3X)\f1 .\" index@\f1window, scroll, enhanced curses@@@\f3scrl(3X)\f1 .\" .\" links@scrl.3x wscrl.3x .\" .\" fileset_database@scrl.3x CURS-ENG-A-MAN .\" $Header: clearok.3x,v 76.2 95/07/31 17:25:47 ssa Exp $ .TA c .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH clearok 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME clearok, idlok, leaveok, scrollok, setscrreg, wsetscrreg \(em terminal output control functions .SH SYNOPSIS .C "#include " .P .C "int clearok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int idlok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int leaveok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int scrollok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "int setscrreg(int \f2top\fP, int \f2bot\fP);" .P .C "int wsetscrreg(WINDOW *\f2win\fP, int \f2top\fP, int \f2bot\fP);" .SH DESCRIPTION These functions set options that deal with output within Curses. .P The .Fn clearok function assigns the value of .I bf to an internal flag in the specified window that governs clearing of the screen during a refresh. If, during a refresh operation on the specified window, the flag in .I curscr is TRUE or the flag in the specified window is TRUE, then the implementation clears the screen, redraws it in its entirety, and sets the flag to FALSE in .I curscr and in the specified window. The initial state is unspecified. .P The .Fn idlok function specifies whether the implementation may use the hardware insert-line, delete-line, and scroll features of terminals so equipped. If \f2bf\f1 is TRUE, use of these features is enabled. If \f2bf\f1 is FALSE, use of these features is disabled and lines are instead redrawn as required. The initial state is FALSE. .P The .Fn leaveok function controls the cursor position after a refresh operation. If \f2bf\f1 is TRUE, refresh operations on the specified window may leave the terminal's cursor at an arbitrary position. If \f2bf\f1 is FALSE, then at the end of any refresh operation, the terminal's cursor is positioned at the cursor position contained in the specified window. The initial state is FALSE. .P The .Fn scrollok function controls the use of scrolling. If \f2bf\f1 is TRUE, then scrolling is enabled for the specified window, with the consequences discussed in \f3Truncation, Wrapping and Scrolling\f1 in curses_intro. If \f2bf\f1 is FALSE, scrolling is disabled for the specified window. The initial state is FALSE. .P The .Fn setscrreg and .Fn wsetscrreg functions define a software scrolling region in the current or specified window. The \f2top\f1 and \f2bot\f1 arguments are the line numbers of the first and last line defining the scrolling region. (Line 0 is the top line of the window.) If this option and .Fn scrollok are enabled, an attempt to move off the last line of the margin causes all lines in the scrolling region to scroll one line in the direction of the first line. Only characters in the window are scrolled. If a software scrolling region is set and .Fn scrollok is not enabled, an attempt to move off the last line of the margin does not reposition any lines in the scrolling region. .SH "RETURN VALUE" Upon successful completion, .Fn setscrreg and .Fn wsetscrreg return OK. Otherwise, they return ERR. .P The other functions always return OK. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" The only reason to enable the .Fn idlok feature is to use scrolling to achieve the visual effect of motion of a partial window, such as for a screen editor. In other cases, the feature can be visually annoying. .P The .Fn leaveok option provides greater efficiency for applications that do not use the cursor. .SH "SEE ALSO" clear(), delscreen(), doupdate(), scrl(), . .SS "CHANGE HISTORY" First released in X/Open Curses, Issue 2. .SH "X/Open Curses, Issue 4" The .CR idlok() , .CR leaveok() , .CR scrollok() , .Fn setscrreq and .Fn wsetscrreq functions are merged with this entry. In previous issues, they appeared in entries of their own. .P The entry is rewritten for clarity. The .B DESCRIPTION of .Fn clearok is updated to indicate that clearing of a screen applies if the flag is TRUE in either \f2curscr\f1 or the specified window. .P The .B "RETURN VALUE" is changed to indicate that the .CR clearok() , .Fn leaveok and .Fn scrollok functions always return OK. .\" .\" toc@\f3clearok(3X)\f1:\0\0\f4clearok()\f1, \f4idleok()\f1, \f4leaveok()\f1, \f4scrollok()\f1, \f4setscrreg()\f1, \f4wsetscrreg()\f1\n@@@terminal output control functions .\" toc@\f4idleok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4leaveok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4scrollok()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4setscrreg()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" toc@\f4wsetscrreg()\f1: terminal output control functions@@@see \f3clearok(3X)\f1 .\" index@\f4clearok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4idleok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4leaveok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4scrollok()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4setscrreg()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f4wsetscrreg()\f1 \- terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f1terminal output control functions@@@\f3clearok(3X)\f1 .\" index@\f1output, terminal, control functions@@@\f3clearok(3X)\f1 .\" index@\f1control functions, terminal output@@@\f3clearok(3X)\f1 .\" .\" links@clearok.3x idleok.3x .\" links@clearok.3x leaveok.3x .\" links@clearok.3x scrollok.3x .\" links@clearok.3x setscrreg.3x .\" links@clearok.3x wsetscrreg.3x .\" .\" fileset_database@clearok.3x CURS-ENG-A-MAN .\" $Header: standend.3x,v 76.2 95/08/01 14:48:02 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH standend 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME standend, standout, wstandend, wstandout \(em set and clear window attributes .SH SYNOPSIS .C "#include " .P .C "int standend(void);" .P .C "int standout(void);" .P .C "int wstandend(WINDOW *\f2win\fP);" .P .C "int wstandout(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn standend and .Fn wstandend functions turn off all attributes of the current or specified window. .P The .Fn standout and .Fn wstandout functions turn on the standout attribute of the current or specified window. .SH "RETURN VALUE" These functions always return 1. .SH ERRORS No errors are defined. .SH "SEE ALSO" attroff(), attr_get(), . .SH "CHANGE HISTORY" Derived from the .Fn attroff entry in X/Open Curses, Issue 3. The entry is reworded for clarity, but otherwise the functionality is identical to previous issues. .\" .\" toc@\f3standend(3X)\f1:\0\0\f4standend()\f1, \f4standout()\f1, \f4wstandend()\f1, \f4wstandout()\f1@@@set and clear window attributes .\" toc@\f4standout()\f1: set and clear window attributes@@@see \f3standend(3X)\f1 .\" toc@\f4wstandend()\f1: set and clear window attributes@@@see \f3standend(3X)\f1 .\" toc@\f4wstandout()\f1: set and clear window attributes@@@see \f3standend(3X)\f1 .\" .\" index@\f4standend()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f4standout()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f4wstandend()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f4wstandout()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f1set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f1clear window attributes@@@\f3standend(3X)\f1 .\" index@\f1window attributes, set and clear@@@\f3standend(3X)\f1 .\" index@\f1attributes, window, set and clear@@@\f3standend(3X)\f1 .\" .\" links@standend.3x standout.3x .\" links@standend.3x wstandend.3x .\" links@standend.3x wstandout.3x .\" .\" fileset_database@standend.3x CURS-ENG-A-MAN .\" $Header: standend.3x,v 76.2 95/08/01 14:48:02 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH standend 3X "CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME standend, standout, wstandend, wstandout \(em set and clear window attributes .SH SYNOPSIS .C "#include " .P .C "int standend(void);" .P .C "int standout(void);" .P .C "int wstandend(WINDOW *\f2win\fP);" .P .C "int wstandout(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn standend and .Fn wstandend functions turn off all attributes of the current or specified window. .P The .Fn standout and .Fn wstandout functions turn on the standout attribute of the current or specified window. .SH "RETURN VALUE" These functions always return 1. .SH ERRORS No errors are defined. .SH "SEE ALSO" attroff(), attr_get(), . .SH "CHANGE HISTORY" Derived from the .Fn attroff entry in X/Open Curses, Issue 3. The entry is reworded for clarity, but otherwise the functionality is identical to previous issues. .\" .\" toc@\f3standend(3X)\f1:\0\0\f4standend()\f1, \f4standout()\f1, \f4wstandend()\f1, \f4wstandout()\f1@@@set and clear window attributes .\" toc@\f4standout()\f1: set and clear window attributes@@@see \f3standend(3X)\f1 .\" toc@\f4wstandend()\f1: set and clear window attributes@@@see \f3standend(3X)\f1 .\" toc@\f4wstandout()\f1: set and clear window attributes@@@see \f3standend(3X)\f1 .\" .\" index@\f4standend()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f4standout()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f4wstandend()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f4wstandout()\f1 \- set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f1set and clear window attributes@@@\f3standend(3X)\f1 .\" index@\f1clear window attributes@@@\f3standend(3X)\f1 .\" index@\f1window attributes, set and clear@@@\f3standend(3X)\f1 .\" index@\f1attributes, window, set and clear@@@\f3standend(3X)\f1 .\" .\" links@standend.3x standout.3x .\" links@standend.3x wstandend.3x .\" links@standend.3x wstandout.3x .\" .\" fileset_database@standend.3x CURS-ENG-A-MAN .\" $Header: syncok.3x,v 76.2 95/08/01 14:50:38 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH syncok 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME syncok, wcursyncup, wsyncdown, wsyncup \(em synchronise a window with its parents or children .SH SYNOPSIS .C "#include " .P .C "int syncok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "void wcursyncup(WINDOW *\f2win\fP);" .P .C "void wsyncdown(WINDOW *\f2win\fP);" .P .C "void wsyncup(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn syncok function determines whether all ancestors of the specified window are implicitly touched whenever there is a change in the window. If \f2bf\f1 is TRUE, such implicit touching occurs. If \f2bf\f1 is FALSE, such implicit touching does not occur. The initial state is FALSE. .P The .Fn wcursyncup function updates the current cursor position of the ancestors of \f2win\f1 to reflect the current cursor position of \f2win\f1. .P The .Fn wsyncdown function touches \f2win\f1 if any ancestor window has been touched. .P The .Fn wsyncup function unconditionally touches all ancestors of \f2win\f1. .SH "RETURN VALUE" Upon successful completion, .Fn syncok returns OK. Otherwise, it returns ERR. .P The other functions do not return a value. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Applications seldom call .Fn wsyncdown because it is called by all refresh operations. .SH "SEE ALSO" doupdate(), is_linetouched(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3syncok(3X)\f1:\0\0\f4syncok()\f1, \f4wcursyncup()\f1, \f4wsyncdown()\f1, \f4wsyncup()\f1\n@@@synchronise a window with its parents or children .\" toc@\f4wcursyncup()\f1: synchronise a window with its parents or children@@@see \f3syncok(3X)\f1 .\" toc@\f4wsyncdown()\f1: synchronise a window with its parents or children@@@see \f3syncok(3X)\f1 .\" toc@\f4wsyncup()\f1: synchronise a window with its parents or children@@@see \f3syncok(3X)\f1 .\" .\" index@\f4syncok()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f4wcursyncup()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f4wsyncup()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f4wsyncdown()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f1synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f1window, synchronise with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f1parents, synchronise a window with@@@\f3syncok(3X)\f1 .\" index@\f1children, synchronise a window with@@@\f3syncok(3X)\f1 .\" .\" links@syncok.3x wcursyncup.3x .\" links@syncok.3x wsyncup.3x .\" links@syncok.3x wsyncdown.3x .\" .\" fileset_database@syncok.3x CURS-ENG-A-MAN .\" $Header: syncok.3x,v 76.2 95/08/01 14:50:38 ssa Exp $ .TA s .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH syncok 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME syncok, wcursyncup, wsyncdown, wsyncup \(em synchronise a window with its parents or children .SH SYNOPSIS .C "#include " .P .C "int syncok(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "void wcursyncup(WINDOW *\f2win\fP);" .P .C "void wsyncdown(WINDOW *\f2win\fP);" .P .C "void wsyncup(WINDOW *\f2win\fP);" .SH DESCRIPTION The .Fn syncok function determines whether all ancestors of the specified window are implicitly touched whenever there is a change in the window. If \f2bf\f1 is TRUE, such implicit touching occurs. If \f2bf\f1 is FALSE, such implicit touching does not occur. The initial state is FALSE. .P The .Fn wcursyncup function updates the current cursor position of the ancestors of \f2win\f1 to reflect the current cursor position of \f2win\f1. .P The .Fn wsyncdown function touches \f2win\f1 if any ancestor window has been touched. .P The .Fn wsyncup function unconditionally touches all ancestors of \f2win\f1. .SH "RETURN VALUE" Upon successful completion, .Fn syncok returns OK. Otherwise, it returns ERR. .P The other functions do not return a value. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Applications seldom call .Fn wsyncdown because it is called by all refresh operations. .SH "SEE ALSO" doupdate(), is_linetouched(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3syncok(3X)\f1:\0\0\f4syncok()\f1, \f4wcursyncup()\f1, \f4wsyncdown()\f1, \f4wsyncup()\f1\n@@@synchronise a window with its parents or children .\" toc@\f4wcursyncup()\f1: synchronise a window with its parents or children@@@see \f3syncok(3X)\f1 .\" toc@\f4wsyncdown()\f1: synchronise a window with its parents or children@@@see \f3syncok(3X)\f1 .\" toc@\f4wsyncup()\f1: synchronise a window with its parents or children@@@see \f3syncok(3X)\f1 .\" .\" index@\f4syncok()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f4wcursyncup()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f4wsyncup()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f4wsyncdown()\f1 \- synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f1synchronise a window with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f1window, synchronise with its parents or children@@@\f3syncok(3X)\f1 .\" index@\f1parents, synchronise a window with@@@\f3syncok(3X)\f1 .\" index@\f1children, synchronise a window with@@@\f3syncok(3X)\f1 .\" .\" links@syncok.3x wcursyncup.3x .\" links@syncok.3x wsyncup.3x .\" links@syncok.3x wsyncdown.3x .\" .\" fileset_database@syncok.3x CURS-ENG-A-MAN .\" $Header: notimeout.3x,v 76.2 95/08/01 14:32:46 ssa Exp $ .TA n .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH notimeout 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME notimeout, timeout, wtimeout \(em control blocking on input .SH SYNOPSIS .C "#include " .P .C "int notimeout(WINDOW *\f2win\fP, bool \f2bf\fP);" .P .C "void timeout(int \f2delay\fP);" .P .C "void wtimeout(WINDOW *\f2win\fP, int \f2delay\fP);" .SH DESCRIPTION The .Fn notimeout function specifies whether Timeout Mode or No Timeout Mode is in effect for the screen associated with the specified window. If \f2bf\f1 is TRUE, this screen is set to No Timeout Mode. If \f2bf\f1 is FALSE, this screen is set to Timeout Mode. The initial state is FALSE. .P The .Fn timeout and .Fn wtimeout functions set blocking or non-blocking read for the current or specified window based on the value of \f2delay\fP: .RS .TP 15 .C "\f2delay\fP\0<\00" One or more blocking reads (indefinite waits for input) are used. .TP .C "\f2delay\fP\0=\00" One or more non-blocking reads are used. Any Curses input function will fail if every character of the requested string is not immediately available. .TP .C "\f2delay\fP\0>\00" Any Curses input function blocks for \f2delay\f1 milliseconds and fails if there is still no input. .RE .SH "RETURN VALUE" Upon successful completion, the .Fn notimeout function returns OK. Otherwise, it returns ERR. .P The .Fn timeout and .Fn wtimeout functions do not return a value. .SH ERRORS No errors are defined. .SH "SEE ALSO" \f3Input Processing\f1 in curses_intro, getch(), halfdelay(), nodelay(), , \f3X/Open System Interface Definitions, Issue 4, Version 2\f1 specification, Section 9.2, \f3Parameters That Can Be Set\f1. .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3notimeout(3X)\f1:\0\0\f4notimeout()\f1, \f4timeout()\f1, \f4wtimeout()\f1@@@control blocking on input .\" toc@\f4timeout()\f1: control blocking on input@@@see \f3notimeout(3X)\f1 .\" toc@\f4wtimeout()\f1: control blocking on input@@@see \f3notimeout(3X)\f1 .\" .\" index@\f4notimeout()\f1 \- control blocking on input@@@\f3notimeout(3X)\f1 .\" index@\f4timeout()\f1 \- control blocking on input@@@\f3notimeout(3X)\f1 .\" index@\f4wtimeout()\f1 \- control blocking on input@@@\f3notimeout(3X)\f1 .\" index@\f1control blocking on input@@@\f3notimeout(3X)\f1 .\" index@\f1blocking on input, control@@@\f3notimeout(3X)\f1 .\" index@\f1input, control blocking on@@@\f3notimeout(3X)\f1 .\" .\" links@notimeout.3x timeout.3x .\" links@notimeout.3x wtimeout.3x .\" .\" fileset_database@notimeout.3x CURS-ENG-A-MAN .\" $Header: is_linetouched.3x,v 76.2 95/08/01 11:31:01 ssa Exp $ .TA i .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH is_linetouched 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .xR 10 manpage_touch .SH NAME is_linetouched, is_wintouched, touchline, untouchwin, wtouchln \(em window refresh control functions .SH SYNOPSIS .C "#include " .P .C "bool is_linetouched(WINDOW *\f2win\fP, int \f2line\fP);" .P .C "bool is_wintouched(WINDOW *\f2win\fP);" .P .C "int touchline(WINDOW *\f2win\fP, int \f2start\fP, int \f2count\fP);" .P .C "int untouchwin(WINDOW *\f2win\fP);" .P .C "int wtouchln(WINDOW *\f2win\fP, int \f2y\fP, int \f2n\fP, int \f2changed\fP);" .SH DESCRIPTION The .Fn touchline function only touches \f2count\f1 lines, beginning with line \f2start\f1. .P The .Fn untouchwin function marks all lines in the window as unchanged since the last refresh operation. .P Calling .Fn wtouchln , if \f2changed\f1 is 1, touches \f2n\f1 lines in the specified window, starting at line \f2y\f1. If \f2changed\f1 is 0, .Fn wtouchln marks such lines as unchanged since the last refresh operation. .P The .Fn is_wintouched function determines whether the specified window is touched. The .Fn is_linetouched function determines whether line .I line of the specified window is touched. .SH "RETURN VALUE" The .Fn is_linetouched and .Fn is_wintouched functions return TRUE if any of the specified lines, or the specified window, respectively, has been touched since the last refresh operation. Otherwise, they return FALSE. .P Upon successful completion, the other functions return OK. Otherwise, they return ERR. Exceptions to this are noted in the preceding function descriptions. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" Calling .Fn touchwin or .Fn touchline is sometimes necessary when using overlapping windows, since a change to one window affects the other window, but the records of which lines have been changed in the other window do not reflect the change. .SH "SEE ALSO" \f3Screens, Windows and Terminals\f1 in curs_intro, doupdate(), touchwin(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3is_linetouched(3X)\f1:\0\0\f4is_linetouched()\f1, \f4is_wintouched()\f1, \f4touchline()\f1, \f4untouchwin()\f1, \n\f4wtouchln()\f1@@@window refresh control functions .\" toc@\f4is_wintouched()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4touchline()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4untouchwin()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" toc@\f4wtouchln()\f1: window refresh control functions@@@see \f3is_linetouched(3X)\f1 .\" .\" index@\f4is_linetouched()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4is_wintouched()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4touchline()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4untouchwin()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f4wtouchln()\f1 \- window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f1window refresh control functions@@@\f3is_linetouched(3X)\f1 .\" index@\f1refresh control functions for window@@@\f3is_linetouched(3X)\f1 .\" index@\f1control functions, window refresh@@@\f3is_linetouched(3X)\f1 .\" index@\f1functions, window refresh control@@@\f3is_linetouched(3X)\f1 .\" .\" links@is_linetouched.3x is_wintouched.3x .\" links@is_linetouched.3x touchline.3x .\" links@is_linetouched.3x untouchwin.3x .\" links@is_linetouched.3x wtouchln.3x .\" .\" fileset_database@is_linetouched.3x CURS-ENG-A-MAN .\" $Header: wunctrl.3x,v 76.2 95/08/01 15:01:32 ssa Exp $ .TA w .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH wunctrl 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME wunctrl \(em generate printable representation of a wide character .SH SYNOPSIS .C "#include " .P .C "wchar_t *wunctrl(cchar_t *\f2wc\fP);" .SH DESCRIPTION The .Fn wunctrl function generates a wide character string that is a printable representation of the wide character \f2wc\f1. .P This function also performs the following processing on the input argument: .RS .TP 3 .C \(bu Control characters are converted to the \f4^\f2X\f1 notation. .TP .C \(bu Any rendition information is removed. .RE .SH "RETURN VALUE" Upon successful completion, .Fn wunctrl returns the generated string. Otherwise, it returns a null pointer. .SH ERRORS No errors are defined. .SH "SEE ALSO" keyname(), unctrl(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" index@\f4wunctrl()\f1 \- generate printable representation of a wide character@@@\f3wunctrl(3X)\f1 .\" index@\f1generate printable representation of a wide character@@@\f3wunctrl(3X)\f1 .\" index@\f1printable representation of a wide character, generate@@@\f3wunctrl(3X)\f1 .\" index@\f1wide character, generate printable representation of@@@\f3wunctrl(3X)\f1 .\" .\" toc@\f3wunctrl(3X)\f1:\0\0\f4wunctrl()\f1@@@generate printable representation of a wide character .\" .\" fileset_database@wunctrl.3x CURS-ENG-A-MAN .\" $Header: hline.3x,v 76.2 95/08/01 11:07:23 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline, mvhline, mvvline, mvwhline, mvwvline, vline, whline, wvline \(em draw lines from single-byte characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvhline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvvline(int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwhline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int mvwvline(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int vline(chtype \f2ch\fP, int \f2n\fP);" .P .C "int whline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .P .C "int wvline(WINDOW *\f2win\fP, chtype \f2ch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline() , .CR mvhline() , .Fn mvwhline and .Fn whline functions draw a line proceeding toward the last column of the same line. .P The .CR vline() , .CR mvvline() , .Fn mvwvline and .Fn wvline functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "APPLICATION USAGE" These functions are only guaranteed to operate reliably on character sets in which each character fits into a single byte, whose attributes can be expressed using only constants with the A_ prefix. .SH "SEE ALSO" border(), box(), hline_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline(3X)\f1:\0\0\f4hline()\f1, \f4mvhline()\f1, \f4mvvline()\f1, \f4mvwhline()\f1, \f4mvwvline()\f1, \f4vline()\f1, \f4whline()\f1, \f4wvline()\f1\n@@@draw lines from single-byte characters and renditions .\" toc@\f4mvhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwhline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4mvwvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4vline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4whline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" toc@\f4wvline()\f1: draw lines from single-byte characters and renditions@@@see \f3hline(3X)\f1 .\" .\" index@\f4hline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwhline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4mvwvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4vline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4whline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f4wvline()\f1 \- draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1draw lines from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1lines, draw from single-byte characters and renditions@@@\f3hline(3X)\f1 .\" index@\f1single-byte characters and renditions, draw lines from@@@\f3hline(3X)\f1 .\" index@\f1characters and renditions, draw lines from single-byte@@@\f3hline(3X)\f1 .\" index@\f1renditions and characters, draw lines from single-byte@@@\f3hline(3X)\f1 .\" .\" links@hline.3x mvhline.3x .\" links@hline.3x mvvline.3x .\" links@hline.3x mvwhline.3x .\" links@hline.3x mvwvline.3x .\" links@hline.3x vline.3x .\" links@hline.3x whline.3x .\" links@hline.3x wvline.3x .\" .\" fileset_database@hline.3x CURS-ENG-A-MAN .\" $Header: hline_set.3x,v 76.2 95/08/01 11:08:14 ssa Exp $ .TA h .de Fn .CR \\$1() .. .de Hd .BR <\\$1> .. .TH hline_set 3X "ENHANCED CURSES" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME hline_set, mvhline_set, mvvline_set, mvwhline_set, mvwvline_set, vline_set, whline_set, wvline_set \(em draw lines from complex characters and renditions .SH SYNOPSIS .C "#include " .P .C "int hline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvhline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvvline_set(int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwhline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int mvwvline_set(WINDOW *\f2win\fP, int \f2y\fP, int \f2x\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int vline_set(cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int whline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .P .C "int wvline_set(WINDOW *\f2win\fP, cchar_t *const \f2wch\fP, int \f2n\fP);" .SH DESCRIPTION These functions draw a line in the current or specified window starting at the current or specified position, using \f2ch\f1. The line is at most \f2n\f1 positions long, or as many as fit into the window. .P These functions do not advance the cursor position. These functions do not perform special character processing. These functions do not perform wrapping. .P The .CR hline_set() , .CR mvhline_set() , .Fn mvwhline_set and .Fn whline_set functions draw a line proceeding toward the last column of the same line. .P The .CR vline_set() , .CR mvvline_set() , .Fn mvwvline_set and .Fn wvline_set functions draw a line proceeding toward the last line of the window. .SH "RETURN VALUE" Upon successful completion, these functions return OK. Otherwise, they return ERR. .SH ERRORS No errors are defined. .SH "SEE ALSO" border_set(), . .SH "CHANGE HISTORY" First released in X/Open Curses, Issue 4. .\" .\" toc@\f3hline_set(3X)\f1:\0\0\f4hline_set()\f1, \f4mvhline_set()\f1, \f4mvvline_set()\f1, \f4mvwhline_set()\f1, \f4mvwvline_set()\f1, \n\f4vline_set()\f1, \f4whline_set()\f1, \f4wvline_set()\f1@@@draw lines from complex characters and renditions .\" toc@\f4mvhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwhline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4mvwvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4vline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4whline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" toc@\f4wvline_set()\f1: draw lines from complex characters and renditions@@@see \f3hline_set(3X)\f1 .\" .\" index@\f4hline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwhline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4mvwvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4vline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4whline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f4wvline_set()\f1 \- draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1draw lines from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1lines, draw from complex characters and renditions@@@\f3hline_set(3X)\f1 .\" index@\f1complex characters and renditions, draw lines from@@@\f3hline_set(3X)\f1 .\" index@\f1characters and renditions, complex, draw lines from@@@\f3hline_set(3X)\f1 .\" .\" links@hline_set.3x mvhline_set.3x .\" links@hline_set.3x mvvline_set.3x .\" links@hline_set.3x mvwhline_set.3x .\" links@hline_set.3x mvwvline_set.3x .\" links@hline_set.3x vline_set.3x .\" links@hline_set.3x whline_set.3x .\" links@hline_set.3x wvline_set.3x .\" .\" fileset_database@hline_set.3x CURS-ENG-A-MAN .\" $Header: xdr.3c,v 74.2 95/05/10 22:07:00 ssa Exp $ .TA x .TH xdr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr \- library routines for external data representation .SH SYNOPSIS .nf .C "#include " .fi .SH DESCRIPTION .B XDR routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Data for remote procedure calls (\s-1RPC\s0) are encoded and decoded using these routines. See .BR rpc (3C). .PP The .B XDR routines have been grouped by usage on the following manpages. .TP 20 .BR xdr_admin (3C) Library routines for managing the .B XDR stream. The routines documented on this page include: .RS 25 .nf .ft B xdr_getpos() xdr_inline() xdrrec_endofrecord() xdrrec_eof() xdrrec_readbytes() xdrrec_skiprecord() xdr_setpos() .ft R .fi .RE .TP .BR xdr_complex (3C) Library routines for translating complex data types into their external data representation. The routines documented on this page include: .RS 25 .nf .ft B xdr_array() xdr_bytes() xdr_opaque() xdr_pointer() xdr_reference() xdr_string() xdr_union() xdr_vector() xdr_wrapstring() .ft R .fi .RE .TP .BR xdr_create (3C) Library routines for creating .B XDR streams. The routines documented on this page include: .RS 25 .nf .ft B xdr_destroy() xdrmem_create() xdrrec_create() xdrstdio_create() .ft R .fi .RE .TP .BR xdr_simple (3C) Library routines for translating simple data types into their external data representation. The routines documented on this page include: .RS 25 .nf .ft B xdr_bool() xdr_char() xdr_double() xdr_enum() xdr_float() xdr_free() xdr_int() xdr_long() xdr_short() xdr_u_char() xdr_u_int() xdr_u_long() xdr_u_short() xdr_void() .ft R .fi .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .ift .bp .SH SEE ALSO rpc (3C), xdr_admin (3C), xdr_complex (3C), xdr_create (3C), and xdr_simple (3C). .PP .IR "Power Programming with RPC". .\" index@\f4xdr()\fP: library routines for external data representation@@@\f3xdr(3C)\f1 .\" index@library routines for external data representation@@@\f3xdr(3C)\f1 .\" index@routines for external data representation, library@@@\f3xdr(3C)\f1 .\" index@external data representation, library routines for@@@\f3xdr(3C)\f1 .\" index@data representation, library routines for external@@@\f3xdr(3C)\f1 .\" index@representation, library routines for external data@@@\f3xdr(3C)\f1 .\" index@\f4xdr_admin()\fP \- routines for managing the XDR stream@@@\f3xdr(3C)\f1 .\" index@\f4xdr_complex()\fP \- routines for translating complex data types into external representation@@@\f3xdr(3C)\f1 .\" index@\f4xdr_create()\fP \- routines for creating XDR streams@@@\f3xdr(3C)\f1 .\" index@\f4xdr_simple()\fP \- routines for simple data types into external representation@@@\f3xdr(3C)\f1 .\" toc@\f3xdr(3C)\f1: \f4xdr()\fP@@@library routines for external data representation .\" fileset_database@xdr.3c PROGRAMING-MAN .\" $Header: rpc_xdr.3c,v 74.1 95/05/10 21:57:15 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_xdr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_accepted_reply, xdr_authunix_parms, xdr_callhdr, xdr_callmsg, xdr_opaque_auth, xdr_rejected_reply, xdr_replymsg \- XDR library routines for remote procedure calls .SH DESCRIPTION These routines are used for describing the .B RPC messages in .B XDR language. They should normally be used by those who do not want to use the .B RPC package. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_accepted_reply(xdrs, arp)" .C "XDR *xdrs;" .C "struct accepted_reply *arp;" .fi .IP Used for encoding .B RPC reply messages. It encodes the status of the .B RPC call in the .B XDR language format and in the case of success, it encodes the call results as well. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_authunix_parms(xdrs, aup)" .C "XDR *xdrs;" .C "struct authunix_parms *aup;" .fi .IP Used for describing .B UNIX credentials. It includes machine name, user .B ID, group .B ID list, etc. This routine is useful for users who wish to generate these credentials without using the .B RPC authentication package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_callhdr(xdrs, chdrp)" .C "XDR *xdrs;" .C "struct rpc_msg *chdrp;" .fi .IP Used for describing .B RPC call header messages. It encodes the static part of the call message header in the .B XDR language format. It includes information such as transaction .B ID, .B RPC version number, program number, and version number. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. .PP .nf .C "bool_t" .C "xdr_callmsg(xdrs, cmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *cmsgp;" .fi .IP Used for describing .B RPC call messages. It includes all the .B RPC call information such as transaction .B ID, .B RPC version number, program number, version number, authentication information, etc. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque_auth(xdrs, ap)" .C "XDR *xdrs;" .C "struct opaque_auth *ap;" .fi .IP Used for describing .B RPC authentication information messages. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_rejected_reply(xdrs, rrp)" .C "XDR *xdrs;" .C "struct rejected_reply *rrp;" .fi .IP Used for describing .B RPC reply messages. It encodes the rejected .B RPC message in the .B XDR language format. The message is rejected either because of version number mismatch or because of authentication errors. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_replymsg(xdrs, rmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *rmsgp;" .fi .IP Used for describing .B RPC reply messages. It encodes the .B RPC reply message in the .B XDR language format. This reply could be an acceptance, rejection, or .B NULL. This routine is useful for users who wish to generate .B RPC style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR rpc (3C) .\" toc@\f3rpc_xdr(3C)\f1:\0\0\f4xdr_accepted_reply()\f1, \f4xdr_authunix_parms()\f1, \f4xdr_callhdr()\f1, \n\f4xdr_callmsg()\f1, \f4xdr_opaque_auth()\f1, \f4xdr_rejected_reply()\f1, \n\f4xdr_replymsg()\f1@@@XDR library routines for remote procedure calls .\" toc@\f4rpc_xdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_accepted_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_authunix_parms()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callhdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callmsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_opaque_auth()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_rejected_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_replymsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" index@XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4rpc_accepted_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_authunix_parms()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_callhdr()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr3C)\f1 .\" index@\f4xdr_callmsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_opaque_auth()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_rejected_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_replymsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" links@rpc_xdr.3c xdr_accepted_reply.3c .\" links@rpc_xdr.3c xdr_authunix_parms.3c .\" links@rpc_xdr.3c xdr_callhdr.3c .\" links@rpc_xdr.3c xdr_callmsg.3c .\" links@rpc_xdr.3c xdr_opaque_auth.3c .\" links@rpc_xdr.3c xdr_rejected_reply.3c .\" links@rpc_xdr.3c xdr_replymsg.3c .\" $Header: xdr_admin.3c,v 74.1 95/05/10 22:07:16 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA x .TH xdr_admin 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_admin(), xdr_getpos(), xdr_inline(), xdrrec_endofrecord(), xdrrec_eof(), xdrrec_readbytes(), xdrrec_skiprecord(), xdr_setpos() \- library routines for management of the XDR stream .SH DESCRIPTION .B XDR library routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines deal specifically with the management of the .B XDR stream. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "u_int" .C "xdr_getpos(xdrs)" .C "XDR *xdrs;" .fi .IP Invoke the get-position routine associated with the .B XDR stream, .IR xdrs . The routine returns an unsigned integer, which indicates the position of the .B XDR byte stream. A desirable feature of .B XDR streams is that simple arithmetic works with this number, although the .B XDR stream instances need not guarantee this. .PP .nf .C "long *" .C "xdr_inline(xdrs, len)" .C "XDR *xdrs;" .C "int len;" .fi .IP Invoke the in-line routine associated with the .B XDR stream, .IR xdrs . The routine returns a pointer to a contiguous piece of the stream's buffer; .I len is the byte length of the desired buffer. Note: A pointer is cast to .BR "long *" . .IP Warning: .B xdr_inline() may return .B NULL if it cannot allocate a contiguous piece of a buffer. Therefore the behavior may vary among stream instances; it exists for the sake of efficiency. .PP .nf .C "bool_t" .C "xdrrec_endofrecord(xdrs, sendnow)" .C "XDR *xdrs;" .C "int sendnow;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). The data in the output buffer is marked as a completed record, and the output buffer is optionally written out if .I sendnow is non-zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdrrec_eof(xdrs, empty)" .C "XDR *xdrs;" .C "int empty;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). After consuming the rest of the current record in the stream, this routine returns .B TRUE if the stream has no more input, .B FALSE otherwise. .PP .nf .C "int" .C "xdrrec_readbytes(xdrs, addr, nbytes)" .C "XDR *xdrs;" .C "caddr_t addr;" .C "u_int nbytes;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It attempts to read .I nbytes bytes from the .B XDR stream into the buffer pointed to by .I addr. On success it returns the number of bytes read. Returns \-1 on failure. A return value of 0 indicates an end of record. .PP .nf .C "bool_t" .C "xdrrec_skiprecord(xdrs)" .C "XDR *xdrs;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It tells the .B XDR implementation that the rest of the current record in the stream's input buffer should be discarded. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_setpos(xdrs, pos)" .C "XDR *xdrs;" .C "u_int pos;" .fi .IP Invoke the set position routine associated with the .B XDR stream .IR xdrs . The parameter .I pos is a position value obtained from .BR xdr_getpos() . This routine returns 1 if the .B XDR stream could be repositioned, and 0 otherwise. .IP Warning: It is difficult to reposition some types of .B XDR streams, so this routine may fail with one type of stream and succeed with another. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_complex (3C), .BR xdr_create (3C), .BR xdr_simple (3C) .\" toc@\f3xdr_admin(3C)\f1:\0\0\f4xdr_admin()\fP, \f4xdr_getpos()\fP, \f4xdr_inline()\fP, \n\f4xdrrec_endofrecord()\fP, \f4xdrrec_eof()\fP, \f4xdrrec_readbytes()\fP, \n\f4xdrrec_skiprecord()\fP, \f4xdr_setpos()\fP@@@library routines for managing XDR streams .\" toc@\f4xdr_admin()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_getpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_inline()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_endofrecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_eof()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_readbytes()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_skiprecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_setpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" index@library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_admin()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_getpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_inline()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_endofrecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_eof()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_readbytes()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_skiprecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_setpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" links@xdr_admin.3c xdr_getpos.3c .\" links@xdr_admin.3c xdr_inline.3c .\" links@xdr_admin.3c xdrrec_endofrecord.3c .\" links@xdr_admin.3c xdrrec_eof.3c .\" links@xdr_admin.3c xdrrec_readbytes.3c .\" links@xdr_admin.3c xdrrec_skiprecord.3c .\" links@xdr_admin.3c xdr_setpos.3c .\" $Header: xdr_complex.3c,v 74.1 95/05/10 22:07:29 ssa Exp $ .TA x .TH xdr_complex 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_complex(), xdr_array(), xdr_bytes(), xdr_opaque(), xdr_pointer(), xdr_reference(), xdr_string(), xdr_union(), xdr_vector(), xdr_wrapstring() \- library routines for translating complex data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe complex data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between a variable-length array and its corresponding external representations. The parameter .I arrp is the address of the pointer to the array, while .I sizep is the address of the element count of the array. This value is used by the filter while encoding and is set by it while decoding; the routine fails if the element count exceeds .IR maxsize . The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_bytes(xdrs, arrp, sizep, maxsize)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize;" .fi .IP A filter primitive that translates between an array of bytes and its external representation. It treats the array of bytes as opaque data. The parameter .I arrp is the address of the array of bytes. While decoding if .I *arrp is .B NULL\s0, then the necessary storage is allocated to hold the array. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). .I sizep is the pointer to the actual length specifier for the array. This value is used by the filter while encoding and is set by it when decoding. .I maxsize is the maximum length of the array. The routine fails if the actual length of the array is greater than .I maxsize This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque(xdrs, cp, cnt)" .C "XDR *xdrs;" .C "char *cp;" .C "u_int cnt;" .fi .IP A filter primitive that translates between fixed size opaque data and its external representation. The parameter .I cp is the address of the opaque object, and .I cnt is its size in bytes. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_pointer(xdrs, objpp, objsize, objproc)" .C "XDR *xdrs;" .C "char **objpp;" .C "u_int objsize;" .C "xdrproc_t objproc;" .fi .IP Like .B xdr_reference() except that it serializes .B NULL pointers, whereas .B xdr_reference() does not. Thus, .B xdr_pointer() can represent recursive data structures, such as binary trees or linked lists. The parameter .I objpp is the address of the pointer; .I objsize is the .I sizeof the structure that .I *objpp points to; and .I objproc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_reference(xdrs, pp, size, proc)" .C "XDR *xdrs;" .C "char **pp;" .C "u_int size;" .C "xdrproc_t proc;" .fi .IP A primitive that provides pointer chasing within structures. The parameter .I pp is the address of the pointer; .I size is the .I sizeof the structure that .I *pp points to; and .I proc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Warning: This routine does not understand .B NULL pointers. Use .B xdr_pointer() instead. .PP .nf .C "bool_t" .C "xdr_string(xdrs, strp, maxsize)" .C "XDR *xdrs;" .C "char **strp;" .C "u_int maxsize;" .fi .IP A filter primitive that translates between C strings and their corresponding external representations. The routine fails if the string being translated is longer than .IR maxsize . .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold this null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_union(xdrs, dscmp, unp, choices, defaultarm)" .C "XDR *xdrs;" .C "int *dscmp;" .C "char *unp;" .C "struct xdr_discrim *choices;" .C "bool_t (*defaultarm) ();" /* may be NULL */ .fi .IP A filter primitive that translates between a discriminated C .B union and its corresponding external representation. It first translates the discriminant of the union located at .IR dscmp . This discriminant is always an .BR enum_t . Next the union located at .I unp is translated. The parameter .I choices is a pointer to an array of .B xdr_discrim structures. Each structure contains an ordered pair of .RI [ value , proc ]. If the union's discriminant is equal to any of the .IR value s, then the associated .I proc is called to translate the union. The end of the .B xdr_discrim structure array is denoted by a .B NULL pointer. If the discriminant is not found in the .I choices array, then the .I defaultarm procedure is called (if it is not .B NULL\s0). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_vector(xdrs, arrp, size, elsize, elproc)" .C "XDR *xdrs;" .C "char *arrp;" .C "u_int size, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between fixed-length arrays and their corresponding external representations. The parameter .I arrp is the address of the array, while .I size is the element count of the array. The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_wrapstring(xdrs, strp)" .C "XDR *xdrs;" .C "char **strp;" .fi .IP A primitive that calls .B "xdr_string("xdrs, strp, "\s-1MAXUNSIGNED\s0 );" where .B MAXUNSIGNED is the maximum value of an unsigned integer. .B xdr_wrapstring() is handy because the .B RPC package passes a maximum of two .B XDR routines as parameters, and .BR xdr_string() , one of the most frequently used primitives, requires three. .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold the null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3N), .BR xdr_admin (3N), .BR xdr_create (3N), .BR xdr_simple (3N) .\" toc@\f3xdr_complex(3C)\f1:\0\0\f4xdr_complex()\f1, \f4xdr_array()\f1, \f4xdr_bytes()\f1, \f4xdr_opaque()\f1, \f4xdr_pointer()\f1, \n\f4xdr_reference()\f1, \f4xdr_string()\f1, \f4xdr_union()\f1, \f4xdr_vector()\f1, \n\f4xdr_wrapstring()\f1@@@library routines for translating complex data types .\" toc@\f4xdr_complex()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_array()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_bytes()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_opaque()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_pointer()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_reference()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_string()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_union()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_vector()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_wrapstring()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" index@library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_complex()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_array()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_bytes()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_opaque()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_pointer()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_reference()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_string()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_union()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_vector()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_wrapstring()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" links@xdr_complex.3c xdr_array.3c .\" links@xdr_complex.3c xdr_bytes.3c .\" links@xdr_complex.3c xdr_opaque.3c .\" links@xdr_complex.3c xdr_pointer.3c .\" links@xdr_complex.3c xdr_reference.3c .\" links@xdr_complex.3c xdr_string.3c .\" links@xdr_complex.3c xdr_union.3c .\" links@xdr_complex.3c xdr_vector.3c .\" links@xdr_complex.3c xdr_wrapstring.3c .\" $Header: rpc_xdr.3c,v 74.1 95/05/10 21:57:15 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_xdr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_accepted_reply, xdr_authunix_parms, xdr_callhdr, xdr_callmsg, xdr_opaque_auth, xdr_rejected_reply, xdr_replymsg \- XDR library routines for remote procedure calls .SH DESCRIPTION These routines are used for describing the .B RPC messages in .B XDR language. They should normally be used by those who do not want to use the .B RPC package. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_accepted_reply(xdrs, arp)" .C "XDR *xdrs;" .C "struct accepted_reply *arp;" .fi .IP Used for encoding .B RPC reply messages. It encodes the status of the .B RPC call in the .B XDR language format and in the case of success, it encodes the call results as well. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_authunix_parms(xdrs, aup)" .C "XDR *xdrs;" .C "struct authunix_parms *aup;" .fi .IP Used for describing .B UNIX credentials. It includes machine name, user .B ID, group .B ID list, etc. This routine is useful for users who wish to generate these credentials without using the .B RPC authentication package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_callhdr(xdrs, chdrp)" .C "XDR *xdrs;" .C "struct rpc_msg *chdrp;" .fi .IP Used for describing .B RPC call header messages. It encodes the static part of the call message header in the .B XDR language format. It includes information such as transaction .B ID, .B RPC version number, program number, and version number. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. .PP .nf .C "bool_t" .C "xdr_callmsg(xdrs, cmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *cmsgp;" .fi .IP Used for describing .B RPC call messages. It includes all the .B RPC call information such as transaction .B ID, .B RPC version number, program number, version number, authentication information, etc. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque_auth(xdrs, ap)" .C "XDR *xdrs;" .C "struct opaque_auth *ap;" .fi .IP Used for describing .B RPC authentication information messages. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_rejected_reply(xdrs, rrp)" .C "XDR *xdrs;" .C "struct rejected_reply *rrp;" .fi .IP Used for describing .B RPC reply messages. It encodes the rejected .B RPC message in the .B XDR language format. The message is rejected either because of version number mismatch or because of authentication errors. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_replymsg(xdrs, rmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *rmsgp;" .fi .IP Used for describing .B RPC reply messages. It encodes the .B RPC reply message in the .B XDR language format. This reply could be an acceptance, rejection, or .B NULL. This routine is useful for users who wish to generate .B RPC style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR rpc (3C) .\" toc@\f3rpc_xdr(3C)\f1:\0\0\f4xdr_accepted_reply()\f1, \f4xdr_authunix_parms()\f1, \f4xdr_callhdr()\f1, \n\f4xdr_callmsg()\f1, \f4xdr_opaque_auth()\f1, \f4xdr_rejected_reply()\f1, \n\f4xdr_replymsg()\f1@@@XDR library routines for remote procedure calls .\" toc@\f4rpc_xdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_accepted_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_authunix_parms()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callhdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callmsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_opaque_auth()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_rejected_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_replymsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" index@XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4rpc_accepted_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_authunix_parms()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_callhdr()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr3C)\f1 .\" index@\f4xdr_callmsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_opaque_auth()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_rejected_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_replymsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" links@rpc_xdr.3c xdr_accepted_reply.3c .\" links@rpc_xdr.3c xdr_authunix_parms.3c .\" links@rpc_xdr.3c xdr_callhdr.3c .\" links@rpc_xdr.3c xdr_callmsg.3c .\" links@rpc_xdr.3c xdr_opaque_auth.3c .\" links@rpc_xdr.3c xdr_rejected_reply.3c .\" links@rpc_xdr.3c xdr_replymsg.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_complex.3c,v 74.1 95/05/10 22:07:29 ssa Exp $ .TA x .TH xdr_complex 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_complex(), xdr_array(), xdr_bytes(), xdr_opaque(), xdr_pointer(), xdr_reference(), xdr_string(), xdr_union(), xdr_vector(), xdr_wrapstring() \- library routines for translating complex data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe complex data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between a variable-length array and its corresponding external representations. The parameter .I arrp is the address of the pointer to the array, while .I sizep is the address of the element count of the array. This value is used by the filter while encoding and is set by it while decoding; the routine fails if the element count exceeds .IR maxsize . The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_bytes(xdrs, arrp, sizep, maxsize)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize;" .fi .IP A filter primitive that translates between an array of bytes and its external representation. It treats the array of bytes as opaque data. The parameter .I arrp is the address of the array of bytes. While decoding if .I *arrp is .B NULL\s0, then the necessary storage is allocated to hold the array. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). .I sizep is the pointer to the actual length specifier for the array. This value is used by the filter while encoding and is set by it when decoding. .I maxsize is the maximum length of the array. The routine fails if the actual length of the array is greater than .I maxsize This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque(xdrs, cp, cnt)" .C "XDR *xdrs;" .C "char *cp;" .C "u_int cnt;" .fi .IP A filter primitive that translates between fixed size opaque data and its external representation. The parameter .I cp is the address of the opaque object, and .I cnt is its size in bytes. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_pointer(xdrs, objpp, objsize, objproc)" .C "XDR *xdrs;" .C "char **objpp;" .C "u_int objsize;" .C "xdrproc_t objproc;" .fi .IP Like .B xdr_reference() except that it serializes .B NULL pointers, whereas .B xdr_reference() does not. Thus, .B xdr_pointer() can represent recursive data structures, such as binary trees or linked lists. The parameter .I objpp is the address of the pointer; .I objsize is the .I sizeof the structure that .I *objpp points to; and .I objproc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_reference(xdrs, pp, size, proc)" .C "XDR *xdrs;" .C "char **pp;" .C "u_int size;" .C "xdrproc_t proc;" .fi .IP A primitive that provides pointer chasing within structures. The parameter .I pp is the address of the pointer; .I size is the .I sizeof the structure that .I *pp points to; and .I proc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Warning: This routine does not understand .B NULL pointers. Use .B xdr_pointer() instead. .PP .nf .C "bool_t" .C "xdr_string(xdrs, strp, maxsize)" .C "XDR *xdrs;" .C "char **strp;" .C "u_int maxsize;" .fi .IP A filter primitive that translates between C strings and their corresponding external representations. The routine fails if the string being translated is longer than .IR maxsize . .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold this null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_union(xdrs, dscmp, unp, choices, defaultarm)" .C "XDR *xdrs;" .C "int *dscmp;" .C "char *unp;" .C "struct xdr_discrim *choices;" .C "bool_t (*defaultarm) ();" /* may be NULL */ .fi .IP A filter primitive that translates between a discriminated C .B union and its corresponding external representation. It first translates the discriminant of the union located at .IR dscmp . This discriminant is always an .BR enum_t . Next the union located at .I unp is translated. The parameter .I choices is a pointer to an array of .B xdr_discrim structures. Each structure contains an ordered pair of .RI [ value , proc ]. If the union's discriminant is equal to any of the .IR value s, then the associated .I proc is called to translate the union. The end of the .B xdr_discrim structure array is denoted by a .B NULL pointer. If the discriminant is not found in the .I choices array, then the .I defaultarm procedure is called (if it is not .B NULL\s0). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_vector(xdrs, arrp, size, elsize, elproc)" .C "XDR *xdrs;" .C "char *arrp;" .C "u_int size, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between fixed-length arrays and their corresponding external representations. The parameter .I arrp is the address of the array, while .I size is the element count of the array. The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_wrapstring(xdrs, strp)" .C "XDR *xdrs;" .C "char **strp;" .fi .IP A primitive that calls .B "xdr_string("xdrs, strp, "\s-1MAXUNSIGNED\s0 );" where .B MAXUNSIGNED is the maximum value of an unsigned integer. .B xdr_wrapstring() is handy because the .B RPC package passes a maximum of two .B XDR routines as parameters, and .BR xdr_string() , one of the most frequently used primitives, requires three. .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold the null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3N), .BR xdr_admin (3N), .BR xdr_create (3N), .BR xdr_simple (3N) .\" toc@\f3xdr_complex(3C)\f1:\0\0\f4xdr_complex()\f1, \f4xdr_array()\f1, \f4xdr_bytes()\f1, \f4xdr_opaque()\f1, \f4xdr_pointer()\f1, \n\f4xdr_reference()\f1, \f4xdr_string()\f1, \f4xdr_union()\f1, \f4xdr_vector()\f1, \n\f4xdr_wrapstring()\f1@@@library routines for translating complex data types .\" toc@\f4xdr_complex()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_array()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_bytes()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_opaque()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_pointer()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_reference()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_string()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_union()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_vector()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_wrapstring()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" index@library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_complex()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_array()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_bytes()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_opaque()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_pointer()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_reference()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_string()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_union()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_vector()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_wrapstring()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" links@xdr_complex.3c xdr_array.3c .\" links@xdr_complex.3c xdr_bytes.3c .\" links@xdr_complex.3c xdr_opaque.3c .\" links@xdr_complex.3c xdr_pointer.3c .\" links@xdr_complex.3c xdr_reference.3c .\" links@xdr_complex.3c xdr_string.3c .\" links@xdr_complex.3c xdr_union.3c .\" links@xdr_complex.3c xdr_vector.3c .\" links@xdr_complex.3c xdr_wrapstring.3c .\" $Header: rpc_xdr.3c,v 74.1 95/05/10 21:57:15 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_xdr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_accepted_reply, xdr_authunix_parms, xdr_callhdr, xdr_callmsg, xdr_opaque_auth, xdr_rejected_reply, xdr_replymsg \- XDR library routines for remote procedure calls .SH DESCRIPTION These routines are used for describing the .B RPC messages in .B XDR language. They should normally be used by those who do not want to use the .B RPC package. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_accepted_reply(xdrs, arp)" .C "XDR *xdrs;" .C "struct accepted_reply *arp;" .fi .IP Used for encoding .B RPC reply messages. It encodes the status of the .B RPC call in the .B XDR language format and in the case of success, it encodes the call results as well. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_authunix_parms(xdrs, aup)" .C "XDR *xdrs;" .C "struct authunix_parms *aup;" .fi .IP Used for describing .B UNIX credentials. It includes machine name, user .B ID, group .B ID list, etc. This routine is useful for users who wish to generate these credentials without using the .B RPC authentication package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_callhdr(xdrs, chdrp)" .C "XDR *xdrs;" .C "struct rpc_msg *chdrp;" .fi .IP Used for describing .B RPC call header messages. It encodes the static part of the call message header in the .B XDR language format. It includes information such as transaction .B ID, .B RPC version number, program number, and version number. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. .PP .nf .C "bool_t" .C "xdr_callmsg(xdrs, cmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *cmsgp;" .fi .IP Used for describing .B RPC call messages. It includes all the .B RPC call information such as transaction .B ID, .B RPC version number, program number, version number, authentication information, etc. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque_auth(xdrs, ap)" .C "XDR *xdrs;" .C "struct opaque_auth *ap;" .fi .IP Used for describing .B RPC authentication information messages. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_rejected_reply(xdrs, rrp)" .C "XDR *xdrs;" .C "struct rejected_reply *rrp;" .fi .IP Used for describing .B RPC reply messages. It encodes the rejected .B RPC message in the .B XDR language format. The message is rejected either because of version number mismatch or because of authentication errors. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_replymsg(xdrs, rmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *rmsgp;" .fi .IP Used for describing .B RPC reply messages. It encodes the .B RPC reply message in the .B XDR language format. This reply could be an acceptance, rejection, or .B NULL. This routine is useful for users who wish to generate .B RPC style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR rpc (3C) .\" toc@\f3rpc_xdr(3C)\f1:\0\0\f4xdr_accepted_reply()\f1, \f4xdr_authunix_parms()\f1, \f4xdr_callhdr()\f1, \n\f4xdr_callmsg()\f1, \f4xdr_opaque_auth()\f1, \f4xdr_rejected_reply()\f1, \n\f4xdr_replymsg()\f1@@@XDR library routines for remote procedure calls .\" toc@\f4rpc_xdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_accepted_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_authunix_parms()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callhdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callmsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_opaque_auth()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_rejected_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_replymsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" index@XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4rpc_accepted_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_authunix_parms()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_callhdr()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr3C)\f1 .\" index@\f4xdr_callmsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_opaque_auth()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_rejected_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_replymsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" links@rpc_xdr.3c xdr_accepted_reply.3c .\" links@rpc_xdr.3c xdr_authunix_parms.3c .\" links@rpc_xdr.3c xdr_callhdr.3c .\" links@rpc_xdr.3c xdr_callmsg.3c .\" links@rpc_xdr.3c xdr_opaque_auth.3c .\" links@rpc_xdr.3c xdr_rejected_reply.3c .\" links@rpc_xdr.3c xdr_replymsg.3c .\" $Header: rpc_xdr.3c,v 74.1 95/05/10 21:57:15 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_xdr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_accepted_reply, xdr_authunix_parms, xdr_callhdr, xdr_callmsg, xdr_opaque_auth, xdr_rejected_reply, xdr_replymsg \- XDR library routines for remote procedure calls .SH DESCRIPTION These routines are used for describing the .B RPC messages in .B XDR language. They should normally be used by those who do not want to use the .B RPC package. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_accepted_reply(xdrs, arp)" .C "XDR *xdrs;" .C "struct accepted_reply *arp;" .fi .IP Used for encoding .B RPC reply messages. It encodes the status of the .B RPC call in the .B XDR language format and in the case of success, it encodes the call results as well. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_authunix_parms(xdrs, aup)" .C "XDR *xdrs;" .C "struct authunix_parms *aup;" .fi .IP Used for describing .B UNIX credentials. It includes machine name, user .B ID, group .B ID list, etc. This routine is useful for users who wish to generate these credentials without using the .B RPC authentication package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_callhdr(xdrs, chdrp)" .C "XDR *xdrs;" .C "struct rpc_msg *chdrp;" .fi .IP Used for describing .B RPC call header messages. It encodes the static part of the call message header in the .B XDR language format. It includes information such as transaction .B ID, .B RPC version number, program number, and version number. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. .PP .nf .C "bool_t" .C "xdr_callmsg(xdrs, cmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *cmsgp;" .fi .IP Used for describing .B RPC call messages. It includes all the .B RPC call information such as transaction .B ID, .B RPC version number, program number, version number, authentication information, etc. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque_auth(xdrs, ap)" .C "XDR *xdrs;" .C "struct opaque_auth *ap;" .fi .IP Used for describing .B RPC authentication information messages. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_rejected_reply(xdrs, rrp)" .C "XDR *xdrs;" .C "struct rejected_reply *rrp;" .fi .IP Used for describing .B RPC reply messages. It encodes the rejected .B RPC message in the .B XDR language format. The message is rejected either because of version number mismatch or because of authentication errors. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_replymsg(xdrs, rmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *rmsgp;" .fi .IP Used for describing .B RPC reply messages. It encodes the .B RPC reply message in the .B XDR language format. This reply could be an acceptance, rejection, or .B NULL. This routine is useful for users who wish to generate .B RPC style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR rpc (3C) .\" toc@\f3rpc_xdr(3C)\f1:\0\0\f4xdr_accepted_reply()\f1, \f4xdr_authunix_parms()\f1, \f4xdr_callhdr()\f1, \n\f4xdr_callmsg()\f1, \f4xdr_opaque_auth()\f1, \f4xdr_rejected_reply()\f1, \n\f4xdr_replymsg()\f1@@@XDR library routines for remote procedure calls .\" toc@\f4rpc_xdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_accepted_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_authunix_parms()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callhdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callmsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_opaque_auth()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_rejected_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_replymsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" index@XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4rpc_accepted_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_authunix_parms()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_callhdr()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr3C)\f1 .\" index@\f4xdr_callmsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_opaque_auth()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_rejected_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_replymsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" links@rpc_xdr.3c xdr_accepted_reply.3c .\" links@rpc_xdr.3c xdr_authunix_parms.3c .\" links@rpc_xdr.3c xdr_callhdr.3c .\" links@rpc_xdr.3c xdr_callmsg.3c .\" links@rpc_xdr.3c xdr_opaque_auth.3c .\" links@rpc_xdr.3c xdr_rejected_reply.3c .\" links@rpc_xdr.3c xdr_replymsg.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_complex.3c,v 74.1 95/05/10 22:07:29 ssa Exp $ .TA x .TH xdr_complex 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_complex(), xdr_array(), xdr_bytes(), xdr_opaque(), xdr_pointer(), xdr_reference(), xdr_string(), xdr_union(), xdr_vector(), xdr_wrapstring() \- library routines for translating complex data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe complex data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between a variable-length array and its corresponding external representations. The parameter .I arrp is the address of the pointer to the array, while .I sizep is the address of the element count of the array. This value is used by the filter while encoding and is set by it while decoding; the routine fails if the element count exceeds .IR maxsize . The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_bytes(xdrs, arrp, sizep, maxsize)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize;" .fi .IP A filter primitive that translates between an array of bytes and its external representation. It treats the array of bytes as opaque data. The parameter .I arrp is the address of the array of bytes. While decoding if .I *arrp is .B NULL\s0, then the necessary storage is allocated to hold the array. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). .I sizep is the pointer to the actual length specifier for the array. This value is used by the filter while encoding and is set by it when decoding. .I maxsize is the maximum length of the array. The routine fails if the actual length of the array is greater than .I maxsize This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque(xdrs, cp, cnt)" .C "XDR *xdrs;" .C "char *cp;" .C "u_int cnt;" .fi .IP A filter primitive that translates between fixed size opaque data and its external representation. The parameter .I cp is the address of the opaque object, and .I cnt is its size in bytes. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_pointer(xdrs, objpp, objsize, objproc)" .C "XDR *xdrs;" .C "char **objpp;" .C "u_int objsize;" .C "xdrproc_t objproc;" .fi .IP Like .B xdr_reference() except that it serializes .B NULL pointers, whereas .B xdr_reference() does not. Thus, .B xdr_pointer() can represent recursive data structures, such as binary trees or linked lists. The parameter .I objpp is the address of the pointer; .I objsize is the .I sizeof the structure that .I *objpp points to; and .I objproc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_reference(xdrs, pp, size, proc)" .C "XDR *xdrs;" .C "char **pp;" .C "u_int size;" .C "xdrproc_t proc;" .fi .IP A primitive that provides pointer chasing within structures. The parameter .I pp is the address of the pointer; .I size is the .I sizeof the structure that .I *pp points to; and .I proc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Warning: This routine does not understand .B NULL pointers. Use .B xdr_pointer() instead. .PP .nf .C "bool_t" .C "xdr_string(xdrs, strp, maxsize)" .C "XDR *xdrs;" .C "char **strp;" .C "u_int maxsize;" .fi .IP A filter primitive that translates between C strings and their corresponding external representations. The routine fails if the string being translated is longer than .IR maxsize . .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold this null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_union(xdrs, dscmp, unp, choices, defaultarm)" .C "XDR *xdrs;" .C "int *dscmp;" .C "char *unp;" .C "struct xdr_discrim *choices;" .C "bool_t (*defaultarm) ();" /* may be NULL */ .fi .IP A filter primitive that translates between a discriminated C .B union and its corresponding external representation. It first translates the discriminant of the union located at .IR dscmp . This discriminant is always an .BR enum_t . Next the union located at .I unp is translated. The parameter .I choices is a pointer to an array of .B xdr_discrim structures. Each structure contains an ordered pair of .RI [ value , proc ]. If the union's discriminant is equal to any of the .IR value s, then the associated .I proc is called to translate the union. The end of the .B xdr_discrim structure array is denoted by a .B NULL pointer. If the discriminant is not found in the .I choices array, then the .I defaultarm procedure is called (if it is not .B NULL\s0). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_vector(xdrs, arrp, size, elsize, elproc)" .C "XDR *xdrs;" .C "char *arrp;" .C "u_int size, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between fixed-length arrays and their corresponding external representations. The parameter .I arrp is the address of the array, while .I size is the element count of the array. The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_wrapstring(xdrs, strp)" .C "XDR *xdrs;" .C "char **strp;" .fi .IP A primitive that calls .B "xdr_string("xdrs, strp, "\s-1MAXUNSIGNED\s0 );" where .B MAXUNSIGNED is the maximum value of an unsigned integer. .B xdr_wrapstring() is handy because the .B RPC package passes a maximum of two .B XDR routines as parameters, and .BR xdr_string() , one of the most frequently used primitives, requires three. .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold the null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3N), .BR xdr_admin (3N), .BR xdr_create (3N), .BR xdr_simple (3N) .\" toc@\f3xdr_complex(3C)\f1:\0\0\f4xdr_complex()\f1, \f4xdr_array()\f1, \f4xdr_bytes()\f1, \f4xdr_opaque()\f1, \f4xdr_pointer()\f1, \n\f4xdr_reference()\f1, \f4xdr_string()\f1, \f4xdr_union()\f1, \f4xdr_vector()\f1, \n\f4xdr_wrapstring()\f1@@@library routines for translating complex data types .\" toc@\f4xdr_complex()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_array()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_bytes()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_opaque()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_pointer()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_reference()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_string()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_union()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_vector()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_wrapstring()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" index@library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_complex()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_array()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_bytes()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_opaque()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_pointer()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_reference()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_string()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_union()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_vector()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_wrapstring()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" links@xdr_complex.3c xdr_array.3c .\" links@xdr_complex.3c xdr_bytes.3c .\" links@xdr_complex.3c xdr_opaque.3c .\" links@xdr_complex.3c xdr_pointer.3c .\" links@xdr_complex.3c xdr_reference.3c .\" links@xdr_complex.3c xdr_string.3c .\" links@xdr_complex.3c xdr_union.3c .\" links@xdr_complex.3c xdr_vector.3c .\" links@xdr_complex.3c xdr_wrapstring.3c .\" $Header: xdr_create.3c,v 74.1 95/05/10 22:07:43 ssa Exp $ .TA x .TH xdr_create 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_create(), xdr_destroy(), xdrmem_create(), xdrrec_create(), xdrstdio_create() \- library routines for external data representation stream creation .SH DESCRIPTION .B XDR library routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines deal with the creation of .B XDR streams. .B XDR streams have to be created before any data can be translated into .B XDR format. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "void" .C "xdr_destroy(xdrs)" .C "XDR *xdrs;" .fi .IP Invoke the destroy routine associated with the .B XDR stream, .IR xdrs . Destruction usually involves freeing private data structures associated with the stream. Using .I xdrs after invoking .B xdr_destroy() is undefined. .PP .nf .C "void" .C "xdrmem_create(xdrs, addr, size, op)" .C "XDR *xdrs;" .C "char *addr;" .C "u_int size;" .C "enum xdr_op op;" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The stream's data is written to, or read from, a chunk of memory at location .I addr whose length is no more than .I size bytes long. .I size should be a multiple of 4. The .I op determines the direction of the .B XDR stream (either .BR \s-1XDR_ENCODE\s0 , .BR \s-1XDR_DECODE\s0 , or .BR \s-1XDR_FREE\s0 ). .PP .nf .C "void" .C "xdrrec_create(xdrs, sendsz, recvsz, handle, readit, writeit)" .C "XDR *xdrs;" .C "u_int sendsz, recvsz;" .C "char *handle;" .C "int (*readit) (), (*writeit) ();" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The stream's data is written to a buffer of size .IR sendsz ; a value of zero indicates the system should use a suitable default. The stream's data is read from a buffer of size .IR recvsz ; it too can be set to a suitable default by passing a zero value. When a stream's output buffer is full, .I writeit is called. Similarly, when a stream's input buffer is empty, .I readit is called. The behavior of these two routines is similar to .BR read (2) and .BR write (2), except that .I handle is passed to the former routines as the first parameter. Note: The .B XDR stream's .I op field must be set by the caller. .I sendsz and .I recvsz should be multiples of 4. .IP Warning: This .B XDR stream implements an intermediate record stream. Therefore there are additional bytes in the stream to provide record boundary information. .PP .nf .C "void" .C "xdrstdio_create(xdrs, filep, op)" .C "XDR *xdrs;" .C "FILE *filep;" .C "enum xdr_op op;" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The .B XDR stream data is written to, or read from, the Standard .B I/O stream .IR filep . The parameter .I op determines the direction of the .B XDR stream (either .BR \s-1XDR_ENCODE\s0 , .BR \s-1XDR_DECODE\s0 , or .BR \s-1XDR_FREE\s0 ). .IP Warning: The destroy routine associated with such .B XDR streams calls .B fflush() on the .I file stream, but never .BR fclose (3S). .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR read (2), .BR write (2), .BR fclose (3S), .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_simple (3C) .\" toc@\f3xdr_create(3C)\f1:\0\0\f4xdr_create()\fP, \f4xdr_destroy()\fP, \f4xdrmem_create()\fP, \n\f4xdrrec_create()\fP, \f4xdrstdio_create()\fP@@@library routines for external data stream creation .\" toc@\f4xdr_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdr_destroy()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrmem_create()\fP: library routines for extrnal data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrrec_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrstdio_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" index@library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdr_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdr_destroy()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrmem_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrrec_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrstdio_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" links@xdr_create.3c xdr_destroy.3c .\" links@xdr_create.3c xdrmem_create.3c .\" links@xdr_create.3c xdrrec_create.3c .\" links@xdr_create.3c xdrstdio_create.3c .\" $Header: xdr_create.3c,v 74.1 95/05/10 22:07:43 ssa Exp $ .TA x .TH xdr_create 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_create(), xdr_destroy(), xdrmem_create(), xdrrec_create(), xdrstdio_create() \- library routines for external data representation stream creation .SH DESCRIPTION .B XDR library routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines deal with the creation of .B XDR streams. .B XDR streams have to be created before any data can be translated into .B XDR format. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "void" .C "xdr_destroy(xdrs)" .C "XDR *xdrs;" .fi .IP Invoke the destroy routine associated with the .B XDR stream, .IR xdrs . Destruction usually involves freeing private data structures associated with the stream. Using .I xdrs after invoking .B xdr_destroy() is undefined. .PP .nf .C "void" .C "xdrmem_create(xdrs, addr, size, op)" .C "XDR *xdrs;" .C "char *addr;" .C "u_int size;" .C "enum xdr_op op;" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The stream's data is written to, or read from, a chunk of memory at location .I addr whose length is no more than .I size bytes long. .I size should be a multiple of 4. The .I op determines the direction of the .B XDR stream (either .BR \s-1XDR_ENCODE\s0 , .BR \s-1XDR_DECODE\s0 , or .BR \s-1XDR_FREE\s0 ). .PP .nf .C "void" .C "xdrrec_create(xdrs, sendsz, recvsz, handle, readit, writeit)" .C "XDR *xdrs;" .C "u_int sendsz, recvsz;" .C "char *handle;" .C "int (*readit) (), (*writeit) ();" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The stream's data is written to a buffer of size .IR sendsz ; a value of zero indicates the system should use a suitable default. The stream's data is read from a buffer of size .IR recvsz ; it too can be set to a suitable default by passing a zero value. When a stream's output buffer is full, .I writeit is called. Similarly, when a stream's input buffer is empty, .I readit is called. The behavior of these two routines is similar to .BR read (2) and .BR write (2), except that .I handle is passed to the former routines as the first parameter. Note: The .B XDR stream's .I op field must be set by the caller. .I sendsz and .I recvsz should be multiples of 4. .IP Warning: This .B XDR stream implements an intermediate record stream. Therefore there are additional bytes in the stream to provide record boundary information. .PP .nf .C "void" .C "xdrstdio_create(xdrs, filep, op)" .C "XDR *xdrs;" .C "FILE *filep;" .C "enum xdr_op op;" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The .B XDR stream data is written to, or read from, the Standard .B I/O stream .IR filep . The parameter .I op determines the direction of the .B XDR stream (either .BR \s-1XDR_ENCODE\s0 , .BR \s-1XDR_DECODE\s0 , or .BR \s-1XDR_FREE\s0 ). .IP Warning: The destroy routine associated with such .B XDR streams calls .B fflush() on the .I file stream, but never .BR fclose (3S). .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR read (2), .BR write (2), .BR fclose (3S), .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_simple (3C) .\" toc@\f3xdr_create(3C)\f1:\0\0\f4xdr_create()\fP, \f4xdr_destroy()\fP, \f4xdrmem_create()\fP, \n\f4xdrrec_create()\fP, \f4xdrstdio_create()\fP@@@library routines for external data stream creation .\" toc@\f4xdr_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdr_destroy()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrmem_create()\fP: library routines for extrnal data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrrec_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrstdio_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" index@library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdr_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdr_destroy()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrmem_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrrec_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrstdio_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" links@xdr_create.3c xdr_destroy.3c .\" links@xdr_create.3c xdrmem_create.3c .\" links@xdr_create.3c xdrrec_create.3c .\" links@xdr_create.3c xdrstdio_create.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_admin.3c,v 74.1 95/05/10 22:07:16 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA x .TH xdr_admin 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_admin(), xdr_getpos(), xdr_inline(), xdrrec_endofrecord(), xdrrec_eof(), xdrrec_readbytes(), xdrrec_skiprecord(), xdr_setpos() \- library routines for management of the XDR stream .SH DESCRIPTION .B XDR library routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines deal specifically with the management of the .B XDR stream. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "u_int" .C "xdr_getpos(xdrs)" .C "XDR *xdrs;" .fi .IP Invoke the get-position routine associated with the .B XDR stream, .IR xdrs . The routine returns an unsigned integer, which indicates the position of the .B XDR byte stream. A desirable feature of .B XDR streams is that simple arithmetic works with this number, although the .B XDR stream instances need not guarantee this. .PP .nf .C "long *" .C "xdr_inline(xdrs, len)" .C "XDR *xdrs;" .C "int len;" .fi .IP Invoke the in-line routine associated with the .B XDR stream, .IR xdrs . The routine returns a pointer to a contiguous piece of the stream's buffer; .I len is the byte length of the desired buffer. Note: A pointer is cast to .BR "long *" . .IP Warning: .B xdr_inline() may return .B NULL if it cannot allocate a contiguous piece of a buffer. Therefore the behavior may vary among stream instances; it exists for the sake of efficiency. .PP .nf .C "bool_t" .C "xdrrec_endofrecord(xdrs, sendnow)" .C "XDR *xdrs;" .C "int sendnow;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). The data in the output buffer is marked as a completed record, and the output buffer is optionally written out if .I sendnow is non-zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdrrec_eof(xdrs, empty)" .C "XDR *xdrs;" .C "int empty;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). After consuming the rest of the current record in the stream, this routine returns .B TRUE if the stream has no more input, .B FALSE otherwise. .PP .nf .C "int" .C "xdrrec_readbytes(xdrs, addr, nbytes)" .C "XDR *xdrs;" .C "caddr_t addr;" .C "u_int nbytes;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It attempts to read .I nbytes bytes from the .B XDR stream into the buffer pointed to by .I addr. On success it returns the number of bytes read. Returns \-1 on failure. A return value of 0 indicates an end of record. .PP .nf .C "bool_t" .C "xdrrec_skiprecord(xdrs)" .C "XDR *xdrs;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It tells the .B XDR implementation that the rest of the current record in the stream's input buffer should be discarded. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_setpos(xdrs, pos)" .C "XDR *xdrs;" .C "u_int pos;" .fi .IP Invoke the set position routine associated with the .B XDR stream .IR xdrs . The parameter .I pos is a position value obtained from .BR xdr_getpos() . This routine returns 1 if the .B XDR stream could be repositioned, and 0 otherwise. .IP Warning: It is difficult to reposition some types of .B XDR streams, so this routine may fail with one type of stream and succeed with another. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_complex (3C), .BR xdr_create (3C), .BR xdr_simple (3C) .\" toc@\f3xdr_admin(3C)\f1:\0\0\f4xdr_admin()\fP, \f4xdr_getpos()\fP, \f4xdr_inline()\fP, \n\f4xdrrec_endofrecord()\fP, \f4xdrrec_eof()\fP, \f4xdrrec_readbytes()\fP, \n\f4xdrrec_skiprecord()\fP, \f4xdr_setpos()\fP@@@library routines for managing XDR streams .\" toc@\f4xdr_admin()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_getpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_inline()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_endofrecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_eof()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_readbytes()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_skiprecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_setpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" index@library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_admin()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_getpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_inline()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_endofrecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_eof()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_readbytes()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_skiprecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_setpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" links@xdr_admin.3c xdr_getpos.3c .\" links@xdr_admin.3c xdr_inline.3c .\" links@xdr_admin.3c xdrrec_endofrecord.3c .\" links@xdr_admin.3c xdrrec_eof.3c .\" links@xdr_admin.3c xdrrec_readbytes.3c .\" links@xdr_admin.3c xdrrec_skiprecord.3c .\" links@xdr_admin.3c xdr_setpos.3c .\" $Header: xdr_admin.3c,v 74.1 95/05/10 22:07:16 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA x .TH xdr_admin 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_admin(), xdr_getpos(), xdr_inline(), xdrrec_endofrecord(), xdrrec_eof(), xdrrec_readbytes(), xdrrec_skiprecord(), xdr_setpos() \- library routines for management of the XDR stream .SH DESCRIPTION .B XDR library routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines deal specifically with the management of the .B XDR stream. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "u_int" .C "xdr_getpos(xdrs)" .C "XDR *xdrs;" .fi .IP Invoke the get-position routine associated with the .B XDR stream, .IR xdrs . The routine returns an unsigned integer, which indicates the position of the .B XDR byte stream. A desirable feature of .B XDR streams is that simple arithmetic works with this number, although the .B XDR stream instances need not guarantee this. .PP .nf .C "long *" .C "xdr_inline(xdrs, len)" .C "XDR *xdrs;" .C "int len;" .fi .IP Invoke the in-line routine associated with the .B XDR stream, .IR xdrs . The routine returns a pointer to a contiguous piece of the stream's buffer; .I len is the byte length of the desired buffer. Note: A pointer is cast to .BR "long *" . .IP Warning: .B xdr_inline() may return .B NULL if it cannot allocate a contiguous piece of a buffer. Therefore the behavior may vary among stream instances; it exists for the sake of efficiency. .PP .nf .C "bool_t" .C "xdrrec_endofrecord(xdrs, sendnow)" .C "XDR *xdrs;" .C "int sendnow;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). The data in the output buffer is marked as a completed record, and the output buffer is optionally written out if .I sendnow is non-zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdrrec_eof(xdrs, empty)" .C "XDR *xdrs;" .C "int empty;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). After consuming the rest of the current record in the stream, this routine returns .B TRUE if the stream has no more input, .B FALSE otherwise. .PP .nf .C "int" .C "xdrrec_readbytes(xdrs, addr, nbytes)" .C "XDR *xdrs;" .C "caddr_t addr;" .C "u_int nbytes;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It attempts to read .I nbytes bytes from the .B XDR stream into the buffer pointed to by .I addr. On success it returns the number of bytes read. Returns \-1 on failure. A return value of 0 indicates an end of record. .PP .nf .C "bool_t" .C "xdrrec_skiprecord(xdrs)" .C "XDR *xdrs;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It tells the .B XDR implementation that the rest of the current record in the stream's input buffer should be discarded. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_setpos(xdrs, pos)" .C "XDR *xdrs;" .C "u_int pos;" .fi .IP Invoke the set position routine associated with the .B XDR stream .IR xdrs . The parameter .I pos is a position value obtained from .BR xdr_getpos() . This routine returns 1 if the .B XDR stream could be repositioned, and 0 otherwise. .IP Warning: It is difficult to reposition some types of .B XDR streams, so this routine may fail with one type of stream and succeed with another. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_complex (3C), .BR xdr_create (3C), .BR xdr_simple (3C) .\" toc@\f3xdr_admin(3C)\f1:\0\0\f4xdr_admin()\fP, \f4xdr_getpos()\fP, \f4xdr_inline()\fP, \n\f4xdrrec_endofrecord()\fP, \f4xdrrec_eof()\fP, \f4xdrrec_readbytes()\fP, \n\f4xdrrec_skiprecord()\fP, \f4xdr_setpos()\fP@@@library routines for managing XDR streams .\" toc@\f4xdr_admin()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_getpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_inline()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_endofrecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_eof()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_readbytes()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_skiprecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_setpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" index@library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_admin()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_getpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_inline()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_endofrecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_eof()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_readbytes()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_skiprecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_setpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" links@xdr_admin.3c xdr_getpos.3c .\" links@xdr_admin.3c xdr_inline.3c .\" links@xdr_admin.3c xdrrec_endofrecord.3c .\" links@xdr_admin.3c xdrrec_eof.3c .\" links@xdr_admin.3c xdrrec_readbytes.3c .\" links@xdr_admin.3c xdrrec_skiprecord.3c .\" links@xdr_admin.3c xdr_setpos.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_complex.3c,v 74.1 95/05/10 22:07:29 ssa Exp $ .TA x .TH xdr_complex 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_complex(), xdr_array(), xdr_bytes(), xdr_opaque(), xdr_pointer(), xdr_reference(), xdr_string(), xdr_union(), xdr_vector(), xdr_wrapstring() \- library routines for translating complex data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe complex data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between a variable-length array and its corresponding external representations. The parameter .I arrp is the address of the pointer to the array, while .I sizep is the address of the element count of the array. This value is used by the filter while encoding and is set by it while decoding; the routine fails if the element count exceeds .IR maxsize . The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_bytes(xdrs, arrp, sizep, maxsize)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize;" .fi .IP A filter primitive that translates between an array of bytes and its external representation. It treats the array of bytes as opaque data. The parameter .I arrp is the address of the array of bytes. While decoding if .I *arrp is .B NULL\s0, then the necessary storage is allocated to hold the array. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). .I sizep is the pointer to the actual length specifier for the array. This value is used by the filter while encoding and is set by it when decoding. .I maxsize is the maximum length of the array. The routine fails if the actual length of the array is greater than .I maxsize This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque(xdrs, cp, cnt)" .C "XDR *xdrs;" .C "char *cp;" .C "u_int cnt;" .fi .IP A filter primitive that translates between fixed size opaque data and its external representation. The parameter .I cp is the address of the opaque object, and .I cnt is its size in bytes. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_pointer(xdrs, objpp, objsize, objproc)" .C "XDR *xdrs;" .C "char **objpp;" .C "u_int objsize;" .C "xdrproc_t objproc;" .fi .IP Like .B xdr_reference() except that it serializes .B NULL pointers, whereas .B xdr_reference() does not. Thus, .B xdr_pointer() can represent recursive data structures, such as binary trees or linked lists. The parameter .I objpp is the address of the pointer; .I objsize is the .I sizeof the structure that .I *objpp points to; and .I objproc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_reference(xdrs, pp, size, proc)" .C "XDR *xdrs;" .C "char **pp;" .C "u_int size;" .C "xdrproc_t proc;" .fi .IP A primitive that provides pointer chasing within structures. The parameter .I pp is the address of the pointer; .I size is the .I sizeof the structure that .I *pp points to; and .I proc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Warning: This routine does not understand .B NULL pointers. Use .B xdr_pointer() instead. .PP .nf .C "bool_t" .C "xdr_string(xdrs, strp, maxsize)" .C "XDR *xdrs;" .C "char **strp;" .C "u_int maxsize;" .fi .IP A filter primitive that translates between C strings and their corresponding external representations. The routine fails if the string being translated is longer than .IR maxsize . .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold this null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_union(xdrs, dscmp, unp, choices, defaultarm)" .C "XDR *xdrs;" .C "int *dscmp;" .C "char *unp;" .C "struct xdr_discrim *choices;" .C "bool_t (*defaultarm) ();" /* may be NULL */ .fi .IP A filter primitive that translates between a discriminated C .B union and its corresponding external representation. It first translates the discriminant of the union located at .IR dscmp . This discriminant is always an .BR enum_t . Next the union located at .I unp is translated. The parameter .I choices is a pointer to an array of .B xdr_discrim structures. Each structure contains an ordered pair of .RI [ value , proc ]. If the union's discriminant is equal to any of the .IR value s, then the associated .I proc is called to translate the union. The end of the .B xdr_discrim structure array is denoted by a .B NULL pointer. If the discriminant is not found in the .I choices array, then the .I defaultarm procedure is called (if it is not .B NULL\s0). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_vector(xdrs, arrp, size, elsize, elproc)" .C "XDR *xdrs;" .C "char *arrp;" .C "u_int size, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between fixed-length arrays and their corresponding external representations. The parameter .I arrp is the address of the array, while .I size is the element count of the array. The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_wrapstring(xdrs, strp)" .C "XDR *xdrs;" .C "char **strp;" .fi .IP A primitive that calls .B "xdr_string("xdrs, strp, "\s-1MAXUNSIGNED\s0 );" where .B MAXUNSIGNED is the maximum value of an unsigned integer. .B xdr_wrapstring() is handy because the .B RPC package passes a maximum of two .B XDR routines as parameters, and .BR xdr_string() , one of the most frequently used primitives, requires three. .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold the null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3N), .BR xdr_admin (3N), .BR xdr_create (3N), .BR xdr_simple (3N) .\" toc@\f3xdr_complex(3C)\f1:\0\0\f4xdr_complex()\f1, \f4xdr_array()\f1, \f4xdr_bytes()\f1, \f4xdr_opaque()\f1, \f4xdr_pointer()\f1, \n\f4xdr_reference()\f1, \f4xdr_string()\f1, \f4xdr_union()\f1, \f4xdr_vector()\f1, \n\f4xdr_wrapstring()\f1@@@library routines for translating complex data types .\" toc@\f4xdr_complex()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_array()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_bytes()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_opaque()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_pointer()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_reference()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_string()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_union()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_vector()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_wrapstring()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" index@library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_complex()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_array()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_bytes()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_opaque()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_pointer()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_reference()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_string()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_union()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_vector()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_wrapstring()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" links@xdr_complex.3c xdr_array.3c .\" links@xdr_complex.3c xdr_bytes.3c .\" links@xdr_complex.3c xdr_opaque.3c .\" links@xdr_complex.3c xdr_pointer.3c .\" links@xdr_complex.3c xdr_reference.3c .\" links@xdr_complex.3c xdr_string.3c .\" links@xdr_complex.3c xdr_union.3c .\" links@xdr_complex.3c xdr_vector.3c .\" links@xdr_complex.3c xdr_wrapstring.3c .\" $Header: rpc_xdr.3c,v 74.1 95/05/10 21:57:15 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_xdr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_accepted_reply, xdr_authunix_parms, xdr_callhdr, xdr_callmsg, xdr_opaque_auth, xdr_rejected_reply, xdr_replymsg \- XDR library routines for remote procedure calls .SH DESCRIPTION These routines are used for describing the .B RPC messages in .B XDR language. They should normally be used by those who do not want to use the .B RPC package. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_accepted_reply(xdrs, arp)" .C "XDR *xdrs;" .C "struct accepted_reply *arp;" .fi .IP Used for encoding .B RPC reply messages. It encodes the status of the .B RPC call in the .B XDR language format and in the case of success, it encodes the call results as well. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_authunix_parms(xdrs, aup)" .C "XDR *xdrs;" .C "struct authunix_parms *aup;" .fi .IP Used for describing .B UNIX credentials. It includes machine name, user .B ID, group .B ID list, etc. This routine is useful for users who wish to generate these credentials without using the .B RPC authentication package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_callhdr(xdrs, chdrp)" .C "XDR *xdrs;" .C "struct rpc_msg *chdrp;" .fi .IP Used for describing .B RPC call header messages. It encodes the static part of the call message header in the .B XDR language format. It includes information such as transaction .B ID, .B RPC version number, program number, and version number. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. .PP .nf .C "bool_t" .C "xdr_callmsg(xdrs, cmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *cmsgp;" .fi .IP Used for describing .B RPC call messages. It includes all the .B RPC call information such as transaction .B ID, .B RPC version number, program number, version number, authentication information, etc. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque_auth(xdrs, ap)" .C "XDR *xdrs;" .C "struct opaque_auth *ap;" .fi .IP Used for describing .B RPC authentication information messages. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_rejected_reply(xdrs, rrp)" .C "XDR *xdrs;" .C "struct rejected_reply *rrp;" .fi .IP Used for describing .B RPC reply messages. It encodes the rejected .B RPC message in the .B XDR language format. The message is rejected either because of version number mismatch or because of authentication errors. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_replymsg(xdrs, rmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *rmsgp;" .fi .IP Used for describing .B RPC reply messages. It encodes the .B RPC reply message in the .B XDR language format. This reply could be an acceptance, rejection, or .B NULL. This routine is useful for users who wish to generate .B RPC style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR rpc (3C) .\" toc@\f3rpc_xdr(3C)\f1:\0\0\f4xdr_accepted_reply()\f1, \f4xdr_authunix_parms()\f1, \f4xdr_callhdr()\f1, \n\f4xdr_callmsg()\f1, \f4xdr_opaque_auth()\f1, \f4xdr_rejected_reply()\f1, \n\f4xdr_replymsg()\f1@@@XDR library routines for remote procedure calls .\" toc@\f4rpc_xdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_accepted_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_authunix_parms()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callhdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callmsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_opaque_auth()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_rejected_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_replymsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" index@XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4rpc_accepted_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_authunix_parms()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_callhdr()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr3C)\f1 .\" index@\f4xdr_callmsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_opaque_auth()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_rejected_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_replymsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" links@rpc_xdr.3c xdr_accepted_reply.3c .\" links@rpc_xdr.3c xdr_authunix_parms.3c .\" links@rpc_xdr.3c xdr_callhdr.3c .\" links@rpc_xdr.3c xdr_callmsg.3c .\" links@rpc_xdr.3c xdr_opaque_auth.3c .\" links@rpc_xdr.3c xdr_rejected_reply.3c .\" links@rpc_xdr.3c xdr_replymsg.3c .\" $Header: xdr_complex.3c,v 74.1 95/05/10 22:07:29 ssa Exp $ .TA x .TH xdr_complex 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_complex(), xdr_array(), xdr_bytes(), xdr_opaque(), xdr_pointer(), xdr_reference(), xdr_string(), xdr_union(), xdr_vector(), xdr_wrapstring() \- library routines for translating complex data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe complex data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between a variable-length array and its corresponding external representations. The parameter .I arrp is the address of the pointer to the array, while .I sizep is the address of the element count of the array. This value is used by the filter while encoding and is set by it while decoding; the routine fails if the element count exceeds .IR maxsize . The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_bytes(xdrs, arrp, sizep, maxsize)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize;" .fi .IP A filter primitive that translates between an array of bytes and its external representation. It treats the array of bytes as opaque data. The parameter .I arrp is the address of the array of bytes. While decoding if .I *arrp is .B NULL\s0, then the necessary storage is allocated to hold the array. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). .I sizep is the pointer to the actual length specifier for the array. This value is used by the filter while encoding and is set by it when decoding. .I maxsize is the maximum length of the array. The routine fails if the actual length of the array is greater than .I maxsize This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque(xdrs, cp, cnt)" .C "XDR *xdrs;" .C "char *cp;" .C "u_int cnt;" .fi .IP A filter primitive that translates between fixed size opaque data and its external representation. The parameter .I cp is the address of the opaque object, and .I cnt is its size in bytes. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_pointer(xdrs, objpp, objsize, objproc)" .C "XDR *xdrs;" .C "char **objpp;" .C "u_int objsize;" .C "xdrproc_t objproc;" .fi .IP Like .B xdr_reference() except that it serializes .B NULL pointers, whereas .B xdr_reference() does not. Thus, .B xdr_pointer() can represent recursive data structures, such as binary trees or linked lists. The parameter .I objpp is the address of the pointer; .I objsize is the .I sizeof the structure that .I *objpp points to; and .I objproc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_reference(xdrs, pp, size, proc)" .C "XDR *xdrs;" .C "char **pp;" .C "u_int size;" .C "xdrproc_t proc;" .fi .IP A primitive that provides pointer chasing within structures. The parameter .I pp is the address of the pointer; .I size is the .I sizeof the structure that .I *pp points to; and .I proc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Warning: This routine does not understand .B NULL pointers. Use .B xdr_pointer() instead. .PP .nf .C "bool_t" .C "xdr_string(xdrs, strp, maxsize)" .C "XDR *xdrs;" .C "char **strp;" .C "u_int maxsize;" .fi .IP A filter primitive that translates between C strings and their corresponding external representations. The routine fails if the string being translated is longer than .IR maxsize . .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold this null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_union(xdrs, dscmp, unp, choices, defaultarm)" .C "XDR *xdrs;" .C "int *dscmp;" .C "char *unp;" .C "struct xdr_discrim *choices;" .C "bool_t (*defaultarm) ();" /* may be NULL */ .fi .IP A filter primitive that translates between a discriminated C .B union and its corresponding external representation. It first translates the discriminant of the union located at .IR dscmp . This discriminant is always an .BR enum_t . Next the union located at .I unp is translated. The parameter .I choices is a pointer to an array of .B xdr_discrim structures. Each structure contains an ordered pair of .RI [ value , proc ]. If the union's discriminant is equal to any of the .IR value s, then the associated .I proc is called to translate the union. The end of the .B xdr_discrim structure array is denoted by a .B NULL pointer. If the discriminant is not found in the .I choices array, then the .I defaultarm procedure is called (if it is not .B NULL\s0). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_vector(xdrs, arrp, size, elsize, elproc)" .C "XDR *xdrs;" .C "char *arrp;" .C "u_int size, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between fixed-length arrays and their corresponding external representations. The parameter .I arrp is the address of the array, while .I size is the element count of the array. The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_wrapstring(xdrs, strp)" .C "XDR *xdrs;" .C "char **strp;" .fi .IP A primitive that calls .B "xdr_string("xdrs, strp, "\s-1MAXUNSIGNED\s0 );" where .B MAXUNSIGNED is the maximum value of an unsigned integer. .B xdr_wrapstring() is handy because the .B RPC package passes a maximum of two .B XDR routines as parameters, and .BR xdr_string() , one of the most frequently used primitives, requires three. .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold the null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3N), .BR xdr_admin (3N), .BR xdr_create (3N), .BR xdr_simple (3N) .\" toc@\f3xdr_complex(3C)\f1:\0\0\f4xdr_complex()\f1, \f4xdr_array()\f1, \f4xdr_bytes()\f1, \f4xdr_opaque()\f1, \f4xdr_pointer()\f1, \n\f4xdr_reference()\f1, \f4xdr_string()\f1, \f4xdr_union()\f1, \f4xdr_vector()\f1, \n\f4xdr_wrapstring()\f1@@@library routines for translating complex data types .\" toc@\f4xdr_complex()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_array()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_bytes()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_opaque()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_pointer()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_reference()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_string()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_union()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_vector()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_wrapstring()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" index@library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_complex()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_array()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_bytes()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_opaque()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_pointer()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_reference()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_string()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_union()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_vector()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_wrapstring()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" links@xdr_complex.3c xdr_array.3c .\" links@xdr_complex.3c xdr_bytes.3c .\" links@xdr_complex.3c xdr_opaque.3c .\" links@xdr_complex.3c xdr_pointer.3c .\" links@xdr_complex.3c xdr_reference.3c .\" links@xdr_complex.3c xdr_string.3c .\" links@xdr_complex.3c xdr_union.3c .\" links@xdr_complex.3c xdr_vector.3c .\" links@xdr_complex.3c xdr_wrapstring.3c .\" $Header: xdr_complex.3c,v 74.1 95/05/10 22:07:29 ssa Exp $ .TA x .TH xdr_complex 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_complex(), xdr_array(), xdr_bytes(), xdr_opaque(), xdr_pointer(), xdr_reference(), xdr_string(), xdr_union(), xdr_vector(), xdr_wrapstring() \- library routines for translating complex data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe complex data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between a variable-length array and its corresponding external representations. The parameter .I arrp is the address of the pointer to the array, while .I sizep is the address of the element count of the array. This value is used by the filter while encoding and is set by it while decoding; the routine fails if the element count exceeds .IR maxsize . The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_bytes(xdrs, arrp, sizep, maxsize)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize;" .fi .IP A filter primitive that translates between an array of bytes and its external representation. It treats the array of bytes as opaque data. The parameter .I arrp is the address of the array of bytes. While decoding if .I *arrp is .B NULL\s0, then the necessary storage is allocated to hold the array. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). .I sizep is the pointer to the actual length specifier for the array. This value is used by the filter while encoding and is set by it when decoding. .I maxsize is the maximum length of the array. The routine fails if the actual length of the array is greater than .I maxsize This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque(xdrs, cp, cnt)" .C "XDR *xdrs;" .C "char *cp;" .C "u_int cnt;" .fi .IP A filter primitive that translates between fixed size opaque data and its external representation. The parameter .I cp is the address of the opaque object, and .I cnt is its size in bytes. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_pointer(xdrs, objpp, objsize, objproc)" .C "XDR *xdrs;" .C "char **objpp;" .C "u_int objsize;" .C "xdrproc_t objproc;" .fi .IP Like .B xdr_reference() except that it serializes .B NULL pointers, whereas .B xdr_reference() does not. Thus, .B xdr_pointer() can represent recursive data structures, such as binary trees or linked lists. The parameter .I objpp is the address of the pointer; .I objsize is the .I sizeof the structure that .I *objpp points to; and .I objproc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_reference(xdrs, pp, size, proc)" .C "XDR *xdrs;" .C "char **pp;" .C "u_int size;" .C "xdrproc_t proc;" .fi .IP A primitive that provides pointer chasing within structures. The parameter .I pp is the address of the pointer; .I size is the .I sizeof the structure that .I *pp points to; and .I proc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Warning: This routine does not understand .B NULL pointers. Use .B xdr_pointer() instead. .PP .nf .C "bool_t" .C "xdr_string(xdrs, strp, maxsize)" .C "XDR *xdrs;" .C "char **strp;" .C "u_int maxsize;" .fi .IP A filter primitive that translates between C strings and their corresponding external representations. The routine fails if the string being translated is longer than .IR maxsize . .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold this null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_union(xdrs, dscmp, unp, choices, defaultarm)" .C "XDR *xdrs;" .C "int *dscmp;" .C "char *unp;" .C "struct xdr_discrim *choices;" .C "bool_t (*defaultarm) ();" /* may be NULL */ .fi .IP A filter primitive that translates between a discriminated C .B union and its corresponding external representation. It first translates the discriminant of the union located at .IR dscmp . This discriminant is always an .BR enum_t . Next the union located at .I unp is translated. The parameter .I choices is a pointer to an array of .B xdr_discrim structures. Each structure contains an ordered pair of .RI [ value , proc ]. If the union's discriminant is equal to any of the .IR value s, then the associated .I proc is called to translate the union. The end of the .B xdr_discrim structure array is denoted by a .B NULL pointer. If the discriminant is not found in the .I choices array, then the .I defaultarm procedure is called (if it is not .B NULL\s0). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_vector(xdrs, arrp, size, elsize, elproc)" .C "XDR *xdrs;" .C "char *arrp;" .C "u_int size, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between fixed-length arrays and their corresponding external representations. The parameter .I arrp is the address of the array, while .I size is the element count of the array. The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_wrapstring(xdrs, strp)" .C "XDR *xdrs;" .C "char **strp;" .fi .IP A primitive that calls .B "xdr_string("xdrs, strp, "\s-1MAXUNSIGNED\s0 );" where .B MAXUNSIGNED is the maximum value of an unsigned integer. .B xdr_wrapstring() is handy because the .B RPC package passes a maximum of two .B XDR routines as parameters, and .BR xdr_string() , one of the most frequently used primitives, requires three. .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold the null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3N), .BR xdr_admin (3N), .BR xdr_create (3N), .BR xdr_simple (3N) .\" toc@\f3xdr_complex(3C)\f1:\0\0\f4xdr_complex()\f1, \f4xdr_array()\f1, \f4xdr_bytes()\f1, \f4xdr_opaque()\f1, \f4xdr_pointer()\f1, \n\f4xdr_reference()\f1, \f4xdr_string()\f1, \f4xdr_union()\f1, \f4xdr_vector()\f1, \n\f4xdr_wrapstring()\f1@@@library routines for translating complex data types .\" toc@\f4xdr_complex()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_array()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_bytes()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_opaque()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_pointer()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_reference()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_string()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_union()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_vector()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_wrapstring()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" index@library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_complex()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_array()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_bytes()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_opaque()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_pointer()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_reference()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_string()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_union()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_vector()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_wrapstring()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" links@xdr_complex.3c xdr_array.3c .\" links@xdr_complex.3c xdr_bytes.3c .\" links@xdr_complex.3c xdr_opaque.3c .\" links@xdr_complex.3c xdr_pointer.3c .\" links@xdr_complex.3c xdr_reference.3c .\" links@xdr_complex.3c xdr_string.3c .\" links@xdr_complex.3c xdr_union.3c .\" links@xdr_complex.3c xdr_vector.3c .\" links@xdr_complex.3c xdr_wrapstring.3c .\" $Header: rpc_xdr.3c,v 74.1 95/05/10 21:57:15 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_xdr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_accepted_reply, xdr_authunix_parms, xdr_callhdr, xdr_callmsg, xdr_opaque_auth, xdr_rejected_reply, xdr_replymsg \- XDR library routines for remote procedure calls .SH DESCRIPTION These routines are used for describing the .B RPC messages in .B XDR language. They should normally be used by those who do not want to use the .B RPC package. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_accepted_reply(xdrs, arp)" .C "XDR *xdrs;" .C "struct accepted_reply *arp;" .fi .IP Used for encoding .B RPC reply messages. It encodes the status of the .B RPC call in the .B XDR language format and in the case of success, it encodes the call results as well. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_authunix_parms(xdrs, aup)" .C "XDR *xdrs;" .C "struct authunix_parms *aup;" .fi .IP Used for describing .B UNIX credentials. It includes machine name, user .B ID, group .B ID list, etc. This routine is useful for users who wish to generate these credentials without using the .B RPC authentication package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_callhdr(xdrs, chdrp)" .C "XDR *xdrs;" .C "struct rpc_msg *chdrp;" .fi .IP Used for describing .B RPC call header messages. It encodes the static part of the call message header in the .B XDR language format. It includes information such as transaction .B ID, .B RPC version number, program number, and version number. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. .PP .nf .C "bool_t" .C "xdr_callmsg(xdrs, cmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *cmsgp;" .fi .IP Used for describing .B RPC call messages. It includes all the .B RPC call information such as transaction .B ID, .B RPC version number, program number, version number, authentication information, etc. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque_auth(xdrs, ap)" .C "XDR *xdrs;" .C "struct opaque_auth *ap;" .fi .IP Used for describing .B RPC authentication information messages. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_rejected_reply(xdrs, rrp)" .C "XDR *xdrs;" .C "struct rejected_reply *rrp;" .fi .IP Used for describing .B RPC reply messages. It encodes the rejected .B RPC message in the .B XDR language format. The message is rejected either because of version number mismatch or because of authentication errors. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_replymsg(xdrs, rmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *rmsgp;" .fi .IP Used for describing .B RPC reply messages. It encodes the .B RPC reply message in the .B XDR language format. This reply could be an acceptance, rejection, or .B NULL. This routine is useful for users who wish to generate .B RPC style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR rpc (3C) .\" toc@\f3rpc_xdr(3C)\f1:\0\0\f4xdr_accepted_reply()\f1, \f4xdr_authunix_parms()\f1, \f4xdr_callhdr()\f1, \n\f4xdr_callmsg()\f1, \f4xdr_opaque_auth()\f1, \f4xdr_rejected_reply()\f1, \n\f4xdr_replymsg()\f1@@@XDR library routines for remote procedure calls .\" toc@\f4rpc_xdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_accepted_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_authunix_parms()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callhdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callmsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_opaque_auth()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_rejected_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_replymsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" index@XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4rpc_accepted_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_authunix_parms()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_callhdr()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr3C)\f1 .\" index@\f4xdr_callmsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_opaque_auth()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_rejected_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_replymsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" links@rpc_xdr.3c xdr_accepted_reply.3c .\" links@rpc_xdr.3c xdr_authunix_parms.3c .\" links@rpc_xdr.3c xdr_callhdr.3c .\" links@rpc_xdr.3c xdr_callmsg.3c .\" links@rpc_xdr.3c xdr_opaque_auth.3c .\" links@rpc_xdr.3c xdr_rejected_reply.3c .\" links@rpc_xdr.3c xdr_replymsg.3c .\" $Header: rpc_xdr.3c,v 74.1 95/05/10 21:57:15 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA r .TH rpc_xdr 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_accepted_reply, xdr_authunix_parms, xdr_callhdr, xdr_callmsg, xdr_opaque_auth, xdr_rejected_reply, xdr_replymsg \- XDR library routines for remote procedure calls .SH DESCRIPTION These routines are used for describing the .B RPC messages in .B XDR language. They should normally be used by those who do not want to use the .B RPC package. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_accepted_reply(xdrs, arp)" .C "XDR *xdrs;" .C "struct accepted_reply *arp;" .fi .IP Used for encoding .B RPC reply messages. It encodes the status of the .B RPC call in the .B XDR language format and in the case of success, it encodes the call results as well. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_authunix_parms(xdrs, aup)" .C "XDR *xdrs;" .C "struct authunix_parms *aup;" .fi .IP Used for describing .B UNIX credentials. It includes machine name, user .B ID, group .B ID list, etc. This routine is useful for users who wish to generate these credentials without using the .B RPC authentication package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_callhdr(xdrs, chdrp)" .C "XDR *xdrs;" .C "struct rpc_msg *chdrp;" .fi .IP Used for describing .B RPC call header messages. It encodes the static part of the call message header in the .B XDR language format. It includes information such as transaction .B ID, .B RPC version number, program number, and version number. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. .PP .nf .C "bool_t" .C "xdr_callmsg(xdrs, cmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *cmsgp;" .fi .IP Used for describing .B RPC call messages. It includes all the .B RPC call information such as transaction .B ID, .B RPC version number, program number, version number, authentication information, etc. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque_auth(xdrs, ap)" .C "XDR *xdrs;" .C "struct opaque_auth *ap;" .fi .IP Used for describing .B RPC authentication information messages. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_rejected_reply(xdrs, rrp)" .C "XDR *xdrs;" .C "struct rejected_reply *rrp;" .fi .IP Used for describing .B RPC reply messages. It encodes the rejected .B RPC message in the .B XDR language format. The message is rejected either because of version number mismatch or because of authentication errors. This routine is useful for users who wish to generate .B RPC-style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_replymsg(xdrs, rmsgp)" .C "XDR *xdrs;" .C "struct rpc_msg *rmsgp;" .fi .IP Used for describing .B RPC reply messages. It encodes the .B RPC reply message in the .B XDR language format. This reply could be an acceptance, rejection, or .B NULL. This routine is useful for users who wish to generate .B RPC style messages without using the .B RPC package. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B rpc_xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR rpc (3C) .\" toc@\f3rpc_xdr(3C)\f1:\0\0\f4xdr_accepted_reply()\f1, \f4xdr_authunix_parms()\f1, \f4xdr_callhdr()\f1, \n\f4xdr_callmsg()\f1, \f4xdr_opaque_auth()\f1, \f4xdr_rejected_reply()\f1, \n\f4xdr_replymsg()\f1@@@XDR library routines for remote procedure calls .\" toc@\f4rpc_xdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_accepted_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_authunix_parms()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callhdr()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_callmsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_opaque_auth()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_rejected_reply()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" toc@\f4xdr_replymsg()\f1: XDR library routines for remote procedure calls@@@see \f3rpc_xdr(3C)\f1 .\" index@XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4rpc_accepted_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_authunix_parms()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_callhdr()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr3C)\f1 .\" index@\f4xdr_callmsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_opaque_auth()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_rejected_reply()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" index@\f4xdr_replymsg()\f1 \- XDR library routines for remote procedure calls@@@\f3rpc_xdr(3C)\f1 .\" links@rpc_xdr.3c xdr_accepted_reply.3c .\" links@rpc_xdr.3c xdr_authunix_parms.3c .\" links@rpc_xdr.3c xdr_callhdr.3c .\" links@rpc_xdr.3c xdr_callmsg.3c .\" links@rpc_xdr.3c xdr_opaque_auth.3c .\" links@rpc_xdr.3c xdr_rejected_reply.3c .\" links@rpc_xdr.3c xdr_replymsg.3c .\" $Header: xdr_admin.3c,v 74.1 95/05/10 22:07:16 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA x .TH xdr_admin 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_admin(), xdr_getpos(), xdr_inline(), xdrrec_endofrecord(), xdrrec_eof(), xdrrec_readbytes(), xdrrec_skiprecord(), xdr_setpos() \- library routines for management of the XDR stream .SH DESCRIPTION .B XDR library routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines deal specifically with the management of the .B XDR stream. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "u_int" .C "xdr_getpos(xdrs)" .C "XDR *xdrs;" .fi .IP Invoke the get-position routine associated with the .B XDR stream, .IR xdrs . The routine returns an unsigned integer, which indicates the position of the .B XDR byte stream. A desirable feature of .B XDR streams is that simple arithmetic works with this number, although the .B XDR stream instances need not guarantee this. .PP .nf .C "long *" .C "xdr_inline(xdrs, len)" .C "XDR *xdrs;" .C "int len;" .fi .IP Invoke the in-line routine associated with the .B XDR stream, .IR xdrs . The routine returns a pointer to a contiguous piece of the stream's buffer; .I len is the byte length of the desired buffer. Note: A pointer is cast to .BR "long *" . .IP Warning: .B xdr_inline() may return .B NULL if it cannot allocate a contiguous piece of a buffer. Therefore the behavior may vary among stream instances; it exists for the sake of efficiency. .PP .nf .C "bool_t" .C "xdrrec_endofrecord(xdrs, sendnow)" .C "XDR *xdrs;" .C "int sendnow;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). The data in the output buffer is marked as a completed record, and the output buffer is optionally written out if .I sendnow is non-zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdrrec_eof(xdrs, empty)" .C "XDR *xdrs;" .C "int empty;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). After consuming the rest of the current record in the stream, this routine returns .B TRUE if the stream has no more input, .B FALSE otherwise. .PP .nf .C "int" .C "xdrrec_readbytes(xdrs, addr, nbytes)" .C "XDR *xdrs;" .C "caddr_t addr;" .C "u_int nbytes;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It attempts to read .I nbytes bytes from the .B XDR stream into the buffer pointed to by .I addr. On success it returns the number of bytes read. Returns \-1 on failure. A return value of 0 indicates an end of record. .PP .nf .C "bool_t" .C "xdrrec_skiprecord(xdrs)" .C "XDR *xdrs;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It tells the .B XDR implementation that the rest of the current record in the stream's input buffer should be discarded. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_setpos(xdrs, pos)" .C "XDR *xdrs;" .C "u_int pos;" .fi .IP Invoke the set position routine associated with the .B XDR stream .IR xdrs . The parameter .I pos is a position value obtained from .BR xdr_getpos() . This routine returns 1 if the .B XDR stream could be repositioned, and 0 otherwise. .IP Warning: It is difficult to reposition some types of .B XDR streams, so this routine may fail with one type of stream and succeed with another. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_complex (3C), .BR xdr_create (3C), .BR xdr_simple (3C) .\" toc@\f3xdr_admin(3C)\f1:\0\0\f4xdr_admin()\fP, \f4xdr_getpos()\fP, \f4xdr_inline()\fP, \n\f4xdrrec_endofrecord()\fP, \f4xdrrec_eof()\fP, \f4xdrrec_readbytes()\fP, \n\f4xdrrec_skiprecord()\fP, \f4xdr_setpos()\fP@@@library routines for managing XDR streams .\" toc@\f4xdr_admin()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_getpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_inline()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_endofrecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_eof()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_readbytes()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_skiprecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_setpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" index@library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_admin()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_getpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_inline()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_endofrecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_eof()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_readbytes()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_skiprecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_setpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" links@xdr_admin.3c xdr_getpos.3c .\" links@xdr_admin.3c xdr_inline.3c .\" links@xdr_admin.3c xdrrec_endofrecord.3c .\" links@xdr_admin.3c xdrrec_eof.3c .\" links@xdr_admin.3c xdrrec_readbytes.3c .\" links@xdr_admin.3c xdrrec_skiprecord.3c .\" links@xdr_admin.3c xdr_setpos.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_complex.3c,v 74.1 95/05/10 22:07:29 ssa Exp $ .TA x .TH xdr_complex 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_complex(), xdr_array(), xdr_bytes(), xdr_opaque(), xdr_pointer(), xdr_reference(), xdr_string(), xdr_union(), xdr_vector(), xdr_wrapstring() \- library routines for translating complex data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe complex data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between a variable-length array and its corresponding external representations. The parameter .I arrp is the address of the pointer to the array, while .I sizep is the address of the element count of the array. This value is used by the filter while encoding and is set by it while decoding; the routine fails if the element count exceeds .IR maxsize . The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_bytes(xdrs, arrp, sizep, maxsize)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize;" .fi .IP A filter primitive that translates between an array of bytes and its external representation. It treats the array of bytes as opaque data. The parameter .I arrp is the address of the array of bytes. While decoding if .I *arrp is .B NULL\s0, then the necessary storage is allocated to hold the array. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). .I sizep is the pointer to the actual length specifier for the array. This value is used by the filter while encoding and is set by it when decoding. .I maxsize is the maximum length of the array. The routine fails if the actual length of the array is greater than .I maxsize This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque(xdrs, cp, cnt)" .C "XDR *xdrs;" .C "char *cp;" .C "u_int cnt;" .fi .IP A filter primitive that translates between fixed size opaque data and its external representation. The parameter .I cp is the address of the opaque object, and .I cnt is its size in bytes. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_pointer(xdrs, objpp, objsize, objproc)" .C "XDR *xdrs;" .C "char **objpp;" .C "u_int objsize;" .C "xdrproc_t objproc;" .fi .IP Like .B xdr_reference() except that it serializes .B NULL pointers, whereas .B xdr_reference() does not. Thus, .B xdr_pointer() can represent recursive data structures, such as binary trees or linked lists. The parameter .I objpp is the address of the pointer; .I objsize is the .I sizeof the structure that .I *objpp points to; and .I objproc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_reference(xdrs, pp, size, proc)" .C "XDR *xdrs;" .C "char **pp;" .C "u_int size;" .C "xdrproc_t proc;" .fi .IP A primitive that provides pointer chasing within structures. The parameter .I pp is the address of the pointer; .I size is the .I sizeof the structure that .I *pp points to; and .I proc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Warning: This routine does not understand .B NULL pointers. Use .B xdr_pointer() instead. .PP .nf .C "bool_t" .C "xdr_string(xdrs, strp, maxsize)" .C "XDR *xdrs;" .C "char **strp;" .C "u_int maxsize;" .fi .IP A filter primitive that translates between C strings and their corresponding external representations. The routine fails if the string being translated is longer than .IR maxsize . .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold this null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_union(xdrs, dscmp, unp, choices, defaultarm)" .C "XDR *xdrs;" .C "int *dscmp;" .C "char *unp;" .C "struct xdr_discrim *choices;" .C "bool_t (*defaultarm) ();" /* may be NULL */ .fi .IP A filter primitive that translates between a discriminated C .B union and its corresponding external representation. It first translates the discriminant of the union located at .IR dscmp . This discriminant is always an .BR enum_t . Next the union located at .I unp is translated. The parameter .I choices is a pointer to an array of .B xdr_discrim structures. Each structure contains an ordered pair of .RI [ value , proc ]. If the union's discriminant is equal to any of the .IR value s, then the associated .I proc is called to translate the union. The end of the .B xdr_discrim structure array is denoted by a .B NULL pointer. If the discriminant is not found in the .I choices array, then the .I defaultarm procedure is called (if it is not .B NULL\s0). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_vector(xdrs, arrp, size, elsize, elproc)" .C "XDR *xdrs;" .C "char *arrp;" .C "u_int size, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between fixed-length arrays and their corresponding external representations. The parameter .I arrp is the address of the array, while .I size is the element count of the array. The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_wrapstring(xdrs, strp)" .C "XDR *xdrs;" .C "char **strp;" .fi .IP A primitive that calls .B "xdr_string("xdrs, strp, "\s-1MAXUNSIGNED\s0 );" where .B MAXUNSIGNED is the maximum value of an unsigned integer. .B xdr_wrapstring() is handy because the .B RPC package passes a maximum of two .B XDR routines as parameters, and .BR xdr_string() , one of the most frequently used primitives, requires three. .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold the null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3N), .BR xdr_admin (3N), .BR xdr_create (3N), .BR xdr_simple (3N) .\" toc@\f3xdr_complex(3C)\f1:\0\0\f4xdr_complex()\f1, \f4xdr_array()\f1, \f4xdr_bytes()\f1, \f4xdr_opaque()\f1, \f4xdr_pointer()\f1, \n\f4xdr_reference()\f1, \f4xdr_string()\f1, \f4xdr_union()\f1, \f4xdr_vector()\f1, \n\f4xdr_wrapstring()\f1@@@library routines for translating complex data types .\" toc@\f4xdr_complex()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_array()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_bytes()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_opaque()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_pointer()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_reference()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_string()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_union()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_vector()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_wrapstring()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" index@library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_complex()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_array()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_bytes()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_opaque()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_pointer()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_reference()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_string()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_union()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_vector()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_wrapstring()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" links@xdr_complex.3c xdr_array.3c .\" links@xdr_complex.3c xdr_bytes.3c .\" links@xdr_complex.3c xdr_opaque.3c .\" links@xdr_complex.3c xdr_pointer.3c .\" links@xdr_complex.3c xdr_reference.3c .\" links@xdr_complex.3c xdr_string.3c .\" links@xdr_complex.3c xdr_union.3c .\" links@xdr_complex.3c xdr_vector.3c .\" links@xdr_complex.3c xdr_wrapstring.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_simple.3c,v 74.1 95/05/10 22:08:02 ssa Exp $ .TA x .TH xdr_simple 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_simple(), xdr_bool(), xdr_char(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_int(), xdr_long(), xdr_short(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_void() \- library routines for translating simple data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe simple data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines require the creation of .B XDR streams (see .BR xdr_create (3N)). .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_bool(xdrs, bp)" .C "XDR *xdrs;" .C "bool_t *bp;" .fi .IP A filter primitive that translates between a boolean (C integer) and its external representation. When encoding data, this filter produces values of either one or zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_char(xdrs, cp)" .C "XDR *xdrs;" .C "char *cp;" .fi .IP A filter primitive that translates between a C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Note: Encoded characters are not packed, and occupy 4 bytes each. For arrays of characters, it is worthwhile to consider .BR xdr_bytes() , .B xdr_opaque() or .B xdr_string() , see .BR xdr_complex (3N). .PP .nf .C "bool_t" .C "xdr_double(xdrs, dp)" .C "XDR *xdrs;" .C "double *dp;" .fi .IP A filter primitive that translates between a C .B double precision number and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_enum(xdrs, ep)" .C "XDR *xdrs;" .C "enum_t *ep;" .fi .IP A filter primitive that translates between a C .BR enum (actually integer) and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_float(xdrs, fp)" .C "XDR *xdrs;" .C "float *fp;" .fi .IP A filter primitive that translates between a C .BR float and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "void" .C "xdr_free(proc, objp)" .C "xdrproc_t proc;" .C "char *objp;" .fi .IP Generic freeing routine. The first argument is the .B XDR routine for the object being freed. The second argument is a pointer to the object itself. Note: The pointer passed to this routine is .I not freed, but what it points to .I is freed, recursively such that objects pointed to are also freed for example, linked lists. .PP .nf .C "bool_t" .C "xdr_int(xdrs, ip)" .C "XDR *xdrs;" .C "int *ip;" .fi .IP A filter primitive that translates between a C .B integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_long(xdrs, lp)" .C "XDR *xdrs;" .C "long *lp;" .fi .IP A filter primitive that translates between a C .B long integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_short(xdrs, sp)" .C "XDR *xdrs;" .C "short *sp;" .fi .IP A filter primitive that translates between a C .B short integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_char(xdrs, ucp)" .C "XDR *xdrs;" .C "unsigned char *ucp;" .fi .IP A filter primitive that translates between an .B unsigned C character and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_int(xdrs, up)" .C "XDR *xdrs;" .C "unsigned *up;" .fi .IP A filter primitive that translates between a C .B unsigned integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_long(xdrs, ulp)" .C "XDR *xdrs;" .C "unsigned long *ulp;" .fi .IP A filter primitive that translates between a C .B "unsigned long" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_u_short(xdrs, usp)" .C "XDR *xdrs;" .C "unsigned short *usp;" .fi .IP A filter primitive that translates between a C .B "unsigned short" integer and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_void()" .fi .IP This routine always returns .B TRUE\s0. It may be passed to .B RPC routines that require a function parameter, where nothing is to be done. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_create (3C) .\" toc@\f3xdr_simple(3C)\f1:\0\0\f4xdr_simple()\f1, \f4xdr_bool()\f1, \f4xdr_char()\f1, \f4xdr_double()\f1, \f4xdr_enum()\f1, \f4xdr_float()\f1, \n\f4xdr_free()\f1, \f4xdr_int()\f1, \f4xdr_long()\f1, \f4xdr_short()\f1, \f4xdr_u-char()\f1, \f4xdr_u_int()\f1, \n\f4xdr_u_long()\f1, \f4xdr_u_short()\f1, \f4xdr_u_void\f1@@@library routines for translating simple data types .\" toc@\f4xdr_simple()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_bool()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_double()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_enum()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_float()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_free()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_char()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_int()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_long()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_short()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" toc@\f4xdr_u_void()\f1: library routines for translating simple data types@@@see \f3xdr_simple(3C)\f1 .\" index@library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_simple()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_bool()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_double()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_enum()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_float()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_free()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_char()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_int()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_long()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_short()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" index@\f4xdr_u_void()\f1 \- library routines for translating simple data types@@@\f3xdr_simple(3C)\f1 .\" links@xdr_simple.3c xdr_bool.3c .\" links@xdr_simple.3c xdr_char.3c .\" links@xdr_simple.3c xdr_double.3c .\" links@xdr_simple.3c xdr_enum.3c .\" links@xdr_simple.3c xdr_float.3c .\" links@xdr_simple.3c xdr_free.3c .\" links@xdr_simple.3c xdr_int.3c .\" links@xdr_simple.3c xdr_long.3c .\" links@xdr_simple.3c xdr_short.3c .\" links@xdr_simple.3c xdr_u_char.3c .\" links@xdr_simple.3c xdr_u_int.3c .\" links@xdr_simple.3c xdr_u_long.3c .\" links@xdr_simple.3c xdr_u_short.3c .\" links@xdr_simple.3c xdr_u_void.3c .\" $Header: xdr_complex.3c,v 74.1 95/05/10 22:07:29 ssa Exp $ .TA x .TH xdr_complex 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_complex(), xdr_array(), xdr_bytes(), xdr_opaque(), xdr_pointer(), xdr_reference(), xdr_string(), xdr_union(), xdr_vector(), xdr_wrapstring() \- library routines for translating complex data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe complex data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between a variable-length array and its corresponding external representations. The parameter .I arrp is the address of the pointer to the array, while .I sizep is the address of the element count of the array. This value is used by the filter while encoding and is set by it while decoding; the routine fails if the element count exceeds .IR maxsize . The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_bytes(xdrs, arrp, sizep, maxsize)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize;" .fi .IP A filter primitive that translates between an array of bytes and its external representation. It treats the array of bytes as opaque data. The parameter .I arrp is the address of the array of bytes. While decoding if .I *arrp is .B NULL\s0, then the necessary storage is allocated to hold the array. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). .I sizep is the pointer to the actual length specifier for the array. This value is used by the filter while encoding and is set by it when decoding. .I maxsize is the maximum length of the array. The routine fails if the actual length of the array is greater than .I maxsize This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque(xdrs, cp, cnt)" .C "XDR *xdrs;" .C "char *cp;" .C "u_int cnt;" .fi .IP A filter primitive that translates between fixed size opaque data and its external representation. The parameter .I cp is the address of the opaque object, and .I cnt is its size in bytes. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_pointer(xdrs, objpp, objsize, objproc)" .C "XDR *xdrs;" .C "char **objpp;" .C "u_int objsize;" .C "xdrproc_t objproc;" .fi .IP Like .B xdr_reference() except that it serializes .B NULL pointers, whereas .B xdr_reference() does not. Thus, .B xdr_pointer() can represent recursive data structures, such as binary trees or linked lists. The parameter .I objpp is the address of the pointer; .I objsize is the .I sizeof the structure that .I *objpp points to; and .I objproc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_reference(xdrs, pp, size, proc)" .C "XDR *xdrs;" .C "char **pp;" .C "u_int size;" .C "xdrproc_t proc;" .fi .IP A primitive that provides pointer chasing within structures. The parameter .I pp is the address of the pointer; .I size is the .I sizeof the structure that .I *pp points to; and .I proc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Warning: This routine does not understand .B NULL pointers. Use .B xdr_pointer() instead. .PP .nf .C "bool_t" .C "xdr_string(xdrs, strp, maxsize)" .C "XDR *xdrs;" .C "char **strp;" .C "u_int maxsize;" .fi .IP A filter primitive that translates between C strings and their corresponding external representations. The routine fails if the string being translated is longer than .IR maxsize . .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold this null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_union(xdrs, dscmp, unp, choices, defaultarm)" .C "XDR *xdrs;" .C "int *dscmp;" .C "char *unp;" .C "struct xdr_discrim *choices;" .C "bool_t (*defaultarm) ();" /* may be NULL */ .fi .IP A filter primitive that translates between a discriminated C .B union and its corresponding external representation. It first translates the discriminant of the union located at .IR dscmp . This discriminant is always an .BR enum_t . Next the union located at .I unp is translated. The parameter .I choices is a pointer to an array of .B xdr_discrim structures. Each structure contains an ordered pair of .RI [ value , proc ]. If the union's discriminant is equal to any of the .IR value s, then the associated .I proc is called to translate the union. The end of the .B xdr_discrim structure array is denoted by a .B NULL pointer. If the discriminant is not found in the .I choices array, then the .I defaultarm procedure is called (if it is not .B NULL\s0). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_vector(xdrs, arrp, size, elsize, elproc)" .C "XDR *xdrs;" .C "char *arrp;" .C "u_int size, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between fixed-length arrays and their corresponding external representations. The parameter .I arrp is the address of the array, while .I size is the element count of the array. The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_wrapstring(xdrs, strp)" .C "XDR *xdrs;" .C "char **strp;" .fi .IP A primitive that calls .B "xdr_string("xdrs, strp, "\s-1MAXUNSIGNED\s0 );" where .B MAXUNSIGNED is the maximum value of an unsigned integer. .B xdr_wrapstring() is handy because the .B RPC package passes a maximum of two .B XDR routines as parameters, and .BR xdr_string() , one of the most frequently used primitives, requires three. .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold the null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3N), .BR xdr_admin (3N), .BR xdr_create (3N), .BR xdr_simple (3N) .\" toc@\f3xdr_complex(3C)\f1:\0\0\f4xdr_complex()\f1, \f4xdr_array()\f1, \f4xdr_bytes()\f1, \f4xdr_opaque()\f1, \f4xdr_pointer()\f1, \n\f4xdr_reference()\f1, \f4xdr_string()\f1, \f4xdr_union()\f1, \f4xdr_vector()\f1, \n\f4xdr_wrapstring()\f1@@@library routines for translating complex data types .\" toc@\f4xdr_complex()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_array()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_bytes()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_opaque()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_pointer()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_reference()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_string()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_union()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_vector()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_wrapstring()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" index@library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_complex()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_array()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_bytes()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_opaque()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_pointer()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_reference()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_string()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_union()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_vector()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_wrapstring()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" links@xdr_complex.3c xdr_array.3c .\" links@xdr_complex.3c xdr_bytes.3c .\" links@xdr_complex.3c xdr_opaque.3c .\" links@xdr_complex.3c xdr_pointer.3c .\" links@xdr_complex.3c xdr_reference.3c .\" links@xdr_complex.3c xdr_string.3c .\" links@xdr_complex.3c xdr_union.3c .\" links@xdr_complex.3c xdr_vector.3c .\" links@xdr_complex.3c xdr_wrapstring.3c .\" $Header: xdr_complex.3c,v 74.1 95/05/10 22:07:29 ssa Exp $ .TA x .TH xdr_complex 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_complex(), xdr_array(), xdr_bytes(), xdr_opaque(), xdr_pointer(), xdr_reference(), xdr_string(), xdr_union(), xdr_vector(), xdr_wrapstring() \- library routines for translating complex data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe complex data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between a variable-length array and its corresponding external representations. The parameter .I arrp is the address of the pointer to the array, while .I sizep is the address of the element count of the array. This value is used by the filter while encoding and is set by it while decoding; the routine fails if the element count exceeds .IR maxsize . The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_bytes(xdrs, arrp, sizep, maxsize)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize;" .fi .IP A filter primitive that translates between an array of bytes and its external representation. It treats the array of bytes as opaque data. The parameter .I arrp is the address of the array of bytes. While decoding if .I *arrp is .B NULL\s0, then the necessary storage is allocated to hold the array. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). .I sizep is the pointer to the actual length specifier for the array. This value is used by the filter while encoding and is set by it when decoding. .I maxsize is the maximum length of the array. The routine fails if the actual length of the array is greater than .I maxsize This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque(xdrs, cp, cnt)" .C "XDR *xdrs;" .C "char *cp;" .C "u_int cnt;" .fi .IP A filter primitive that translates between fixed size opaque data and its external representation. The parameter .I cp is the address of the opaque object, and .I cnt is its size in bytes. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_pointer(xdrs, objpp, objsize, objproc)" .C "XDR *xdrs;" .C "char **objpp;" .C "u_int objsize;" .C "xdrproc_t objproc;" .fi .IP Like .B xdr_reference() except that it serializes .B NULL pointers, whereas .B xdr_reference() does not. Thus, .B xdr_pointer() can represent recursive data structures, such as binary trees or linked lists. The parameter .I objpp is the address of the pointer; .I objsize is the .I sizeof the structure that .I *objpp points to; and .I objproc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_reference(xdrs, pp, size, proc)" .C "XDR *xdrs;" .C "char **pp;" .C "u_int size;" .C "xdrproc_t proc;" .fi .IP A primitive that provides pointer chasing within structures. The parameter .I pp is the address of the pointer; .I size is the .I sizeof the structure that .I *pp points to; and .I proc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Warning: This routine does not understand .B NULL pointers. Use .B xdr_pointer() instead. .PP .nf .C "bool_t" .C "xdr_string(xdrs, strp, maxsize)" .C "XDR *xdrs;" .C "char **strp;" .C "u_int maxsize;" .fi .IP A filter primitive that translates between C strings and their corresponding external representations. The routine fails if the string being translated is longer than .IR maxsize . .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold this null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_union(xdrs, dscmp, unp, choices, defaultarm)" .C "XDR *xdrs;" .C "int *dscmp;" .C "char *unp;" .C "struct xdr_discrim *choices;" .C "bool_t (*defaultarm) ();" /* may be NULL */ .fi .IP A filter primitive that translates between a discriminated C .B union and its corresponding external representation. It first translates the discriminant of the union located at .IR dscmp . This discriminant is always an .BR enum_t . Next the union located at .I unp is translated. The parameter .I choices is a pointer to an array of .B xdr_discrim structures. Each structure contains an ordered pair of .RI [ value , proc ]. If the union's discriminant is equal to any of the .IR value s, then the associated .I proc is called to translate the union. The end of the .B xdr_discrim structure array is denoted by a .B NULL pointer. If the discriminant is not found in the .I choices array, then the .I defaultarm procedure is called (if it is not .B NULL\s0). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_vector(xdrs, arrp, size, elsize, elproc)" .C "XDR *xdrs;" .C "char *arrp;" .C "u_int size, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between fixed-length arrays and their corresponding external representations. The parameter .I arrp is the address of the array, while .I size is the element count of the array. The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_wrapstring(xdrs, strp)" .C "XDR *xdrs;" .C "char **strp;" .fi .IP A primitive that calls .B "xdr_string("xdrs, strp, "\s-1MAXUNSIGNED\s0 );" where .B MAXUNSIGNED is the maximum value of an unsigned integer. .B xdr_wrapstring() is handy because the .B RPC package passes a maximum of two .B XDR routines as parameters, and .BR xdr_string() , one of the most frequently used primitives, requires three. .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold the null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3N), .BR xdr_admin (3N), .BR xdr_create (3N), .BR xdr_simple (3N) .\" toc@\f3xdr_complex(3C)\f1:\0\0\f4xdr_complex()\f1, \f4xdr_array()\f1, \f4xdr_bytes()\f1, \f4xdr_opaque()\f1, \f4xdr_pointer()\f1, \n\f4xdr_reference()\f1, \f4xdr_string()\f1, \f4xdr_union()\f1, \f4xdr_vector()\f1, \n\f4xdr_wrapstring()\f1@@@library routines for translating complex data types .\" toc@\f4xdr_complex()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_array()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_bytes()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_opaque()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_pointer()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_reference()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_string()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_union()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_vector()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_wrapstring()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" index@library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_complex()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_array()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_bytes()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_opaque()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_pointer()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_reference()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_string()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_union()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_vector()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_wrapstring()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" links@xdr_complex.3c xdr_array.3c .\" links@xdr_complex.3c xdr_bytes.3c .\" links@xdr_complex.3c xdr_opaque.3c .\" links@xdr_complex.3c xdr_pointer.3c .\" links@xdr_complex.3c xdr_reference.3c .\" links@xdr_complex.3c xdr_string.3c .\" links@xdr_complex.3c xdr_union.3c .\" links@xdr_complex.3c xdr_vector.3c .\" links@xdr_complex.3c xdr_wrapstring.3c .\" $Header: xdr_complex.3c,v 74.1 95/05/10 22:07:29 ssa Exp $ .TA x .TH xdr_complex 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_complex(), xdr_array(), xdr_bytes(), xdr_opaque(), xdr_pointer(), xdr_reference(), xdr_string(), xdr_union(), xdr_vector(), xdr_wrapstring() \- library routines for translating complex data types .SH DESCRIPTION .B XDR library routines allow C programmers to describe complex data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "bool_t" .C "xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between a variable-length array and its corresponding external representations. The parameter .I arrp is the address of the pointer to the array, while .I sizep is the address of the element count of the array. This value is used by the filter while encoding and is set by it while decoding; the routine fails if the element count exceeds .IR maxsize . The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_bytes(xdrs, arrp, sizep, maxsize)" .C "XDR *xdrs;" .C "char **arrp;" .C "u_int *sizep, maxsize;" .fi .IP A filter primitive that translates between an array of bytes and its external representation. It treats the array of bytes as opaque data. The parameter .I arrp is the address of the array of bytes. While decoding if .I *arrp is .B NULL\s0, then the necessary storage is allocated to hold the array. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). .I sizep is the pointer to the actual length specifier for the array. This value is used by the filter while encoding and is set by it when decoding. .I maxsize is the maximum length of the array. The routine fails if the actual length of the array is greater than .I maxsize This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_opaque(xdrs, cp, cnt)" .C "XDR *xdrs;" .C "char *cp;" .C "u_int cnt;" .fi .IP A filter primitive that translates between fixed size opaque data and its external representation. The parameter .I cp is the address of the opaque object, and .I cnt is its size in bytes. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_pointer(xdrs, objpp, objsize, objproc)" .C "XDR *xdrs;" .C "char **objpp;" .C "u_int objsize;" .C "xdrproc_t objproc;" .fi .IP Like .B xdr_reference() except that it serializes .B NULL pointers, whereas .B xdr_reference() does not. Thus, .B xdr_pointer() can represent recursive data structures, such as binary trees or linked lists. The parameter .I objpp is the address of the pointer; .I objsize is the .I sizeof the structure that .I *objpp points to; and .I objproc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_reference(xdrs, pp, size, proc)" .C "XDR *xdrs;" .C "char **pp;" .C "u_int size;" .C "xdrproc_t proc;" .fi .IP A primitive that provides pointer chasing within structures. The parameter .I pp is the address of the pointer; .I size is the .I sizeof the structure that .I *pp points to; and .I proc is an .B XDR procedure that filters the structure between its C form and its external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .IP Warning: This routine does not understand .B NULL pointers. Use .B xdr_pointer() instead. .PP .nf .C "bool_t" .C "xdr_string(xdrs, strp, maxsize)" .C "XDR *xdrs;" .C "char **strp;" .C "u_int maxsize;" .fi .IP A filter primitive that translates between C strings and their corresponding external representations. The routine fails if the string being translated is longer than .IR maxsize . .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold this null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_union(xdrs, dscmp, unp, choices, defaultarm)" .C "XDR *xdrs;" .C "int *dscmp;" .C "char *unp;" .C "struct xdr_discrim *choices;" .C "bool_t (*defaultarm) ();" /* may be NULL */ .fi .IP A filter primitive that translates between a discriminated C .B union and its corresponding external representation. It first translates the discriminant of the union located at .IR dscmp . This discriminant is always an .BR enum_t . Next the union located at .I unp is translated. The parameter .I choices is a pointer to an array of .B xdr_discrim structures. Each structure contains an ordered pair of .RI [ value , proc ]. If the union's discriminant is equal to any of the .IR value s, then the associated .I proc is called to translate the union. The end of the .B xdr_discrim structure array is denoted by a .B NULL pointer. If the discriminant is not found in the .I choices array, then the .I defaultarm procedure is called (if it is not .B NULL\s0). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_vector(xdrs, arrp, size, elsize, elproc)" .C "XDR *xdrs;" .C "char *arrp;" .C "u_int size, elsize;" .C "xdrproc_t elproc;" .fi .IP A filter primitive that translates between fixed-length arrays and their corresponding external representations. The parameter .I arrp is the address of the array, while .I size is the element count of the array. The parameter .I elsize is the .I sizeof each of the array's elements, and .I elproc is an .B XDR filter that translates between the array elements' C form, and their external representation. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_wrapstring(xdrs, strp)" .C "XDR *xdrs;" .C "char **strp;" .fi .IP A primitive that calls .B "xdr_string("xdrs, strp, "\s-1MAXUNSIGNED\s0 );" where .B MAXUNSIGNED is the maximum value of an unsigned integer. .B xdr_wrapstring() is handy because the .B RPC package passes a maximum of two .B XDR routines as parameters, and .BR xdr_string() , one of the most frequently used primitives, requires three. .I strp is the address of the pointer to the string. While decoding if .I *strp is .B NULL\s0, then the necessary storage is allocated to hold the null-terminated string and .I *strp is set to point to this. This storage can be freed by using .B xdr_free() (see .BR xdr_simple (3N)). This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3N), .BR xdr_admin (3N), .BR xdr_create (3N), .BR xdr_simple (3N) .\" toc@\f3xdr_complex(3C)\f1:\0\0\f4xdr_complex()\f1, \f4xdr_array()\f1, \f4xdr_bytes()\f1, \f4xdr_opaque()\f1, \f4xdr_pointer()\f1, \n\f4xdr_reference()\f1, \f4xdr_string()\f1, \f4xdr_union()\f1, \f4xdr_vector()\f1, \n\f4xdr_wrapstring()\f1@@@library routines for translating complex data types .\" toc@\f4xdr_complex()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_array()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_bytes()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_opaque()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_pointer()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_reference()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_string()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_union()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_vector()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" toc@\f4xdr_wrapstring()\f1: library routines for translating complex data types@@@see \f3xdr_complex(3C)\f1 .\" index@library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_complex()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_array()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_bytes()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_opaque()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_pointer()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_reference()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_string()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_union()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_vector()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" index@\f4xdr_wrapstring()\f1 \- library routines for translating complex data types@@@\f3xdr_complex(3C)\f1 .\" links@xdr_complex.3c xdr_array.3c .\" links@xdr_complex.3c xdr_bytes.3c .\" links@xdr_complex.3c xdr_opaque.3c .\" links@xdr_complex.3c xdr_pointer.3c .\" links@xdr_complex.3c xdr_reference.3c .\" links@xdr_complex.3c xdr_string.3c .\" links@xdr_complex.3c xdr_union.3c .\" links@xdr_complex.3c xdr_vector.3c .\" links@xdr_complex.3c xdr_wrapstring.3c .\" $Header: xdr_create.3c,v 74.1 95/05/10 22:07:43 ssa Exp $ .TA x .TH xdr_create 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_create(), xdr_destroy(), xdrmem_create(), xdrrec_create(), xdrstdio_create() \- library routines for external data representation stream creation .SH DESCRIPTION .B XDR library routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines deal with the creation of .B XDR streams. .B XDR streams have to be created before any data can be translated into .B XDR format. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "void" .C "xdr_destroy(xdrs)" .C "XDR *xdrs;" .fi .IP Invoke the destroy routine associated with the .B XDR stream, .IR xdrs . Destruction usually involves freeing private data structures associated with the stream. Using .I xdrs after invoking .B xdr_destroy() is undefined. .PP .nf .C "void" .C "xdrmem_create(xdrs, addr, size, op)" .C "XDR *xdrs;" .C "char *addr;" .C "u_int size;" .C "enum xdr_op op;" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The stream's data is written to, or read from, a chunk of memory at location .I addr whose length is no more than .I size bytes long. .I size should be a multiple of 4. The .I op determines the direction of the .B XDR stream (either .BR \s-1XDR_ENCODE\s0 , .BR \s-1XDR_DECODE\s0 , or .BR \s-1XDR_FREE\s0 ). .PP .nf .C "void" .C "xdrrec_create(xdrs, sendsz, recvsz, handle, readit, writeit)" .C "XDR *xdrs;" .C "u_int sendsz, recvsz;" .C "char *handle;" .C "int (*readit) (), (*writeit) ();" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The stream's data is written to a buffer of size .IR sendsz ; a value of zero indicates the system should use a suitable default. The stream's data is read from a buffer of size .IR recvsz ; it too can be set to a suitable default by passing a zero value. When a stream's output buffer is full, .I writeit is called. Similarly, when a stream's input buffer is empty, .I readit is called. The behavior of these two routines is similar to .BR read (2) and .BR write (2), except that .I handle is passed to the former routines as the first parameter. Note: The .B XDR stream's .I op field must be set by the caller. .I sendsz and .I recvsz should be multiples of 4. .IP Warning: This .B XDR stream implements an intermediate record stream. Therefore there are additional bytes in the stream to provide record boundary information. .PP .nf .C "void" .C "xdrstdio_create(xdrs, filep, op)" .C "XDR *xdrs;" .C "FILE *filep;" .C "enum xdr_op op;" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The .B XDR stream data is written to, or read from, the Standard .B I/O stream .IR filep . The parameter .I op determines the direction of the .B XDR stream (either .BR \s-1XDR_ENCODE\s0 , .BR \s-1XDR_DECODE\s0 , or .BR \s-1XDR_FREE\s0 ). .IP Warning: The destroy routine associated with such .B XDR streams calls .B fflush() on the .I file stream, but never .BR fclose (3S). .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR read (2), .BR write (2), .BR fclose (3S), .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_simple (3C) .\" toc@\f3xdr_create(3C)\f1:\0\0\f4xdr_create()\fP, \f4xdr_destroy()\fP, \f4xdrmem_create()\fP, \n\f4xdrrec_create()\fP, \f4xdrstdio_create()\fP@@@library routines for external data stream creation .\" toc@\f4xdr_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdr_destroy()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrmem_create()\fP: library routines for extrnal data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrrec_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrstdio_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" index@library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdr_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdr_destroy()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrmem_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrrec_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrstdio_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" links@xdr_create.3c xdr_destroy.3c .\" links@xdr_create.3c xdrmem_create.3c .\" links@xdr_create.3c xdrrec_create.3c .\" links@xdr_create.3c xdrstdio_create.3c .\" $Header: xdr_create.3c,v 74.1 95/05/10 22:07:43 ssa Exp $ .TA x .TH xdr_create 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_create(), xdr_destroy(), xdrmem_create(), xdrrec_create(), xdrstdio_create() \- library routines for external data representation stream creation .SH DESCRIPTION .B XDR library routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines deal with the creation of .B XDR streams. .B XDR streams have to be created before any data can be translated into .B XDR format. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "void" .C "xdr_destroy(xdrs)" .C "XDR *xdrs;" .fi .IP Invoke the destroy routine associated with the .B XDR stream, .IR xdrs . Destruction usually involves freeing private data structures associated with the stream. Using .I xdrs after invoking .B xdr_destroy() is undefined. .PP .nf .C "void" .C "xdrmem_create(xdrs, addr, size, op)" .C "XDR *xdrs;" .C "char *addr;" .C "u_int size;" .C "enum xdr_op op;" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The stream's data is written to, or read from, a chunk of memory at location .I addr whose length is no more than .I size bytes long. .I size should be a multiple of 4. The .I op determines the direction of the .B XDR stream (either .BR \s-1XDR_ENCODE\s0 , .BR \s-1XDR_DECODE\s0 , or .BR \s-1XDR_FREE\s0 ). .PP .nf .C "void" .C "xdrrec_create(xdrs, sendsz, recvsz, handle, readit, writeit)" .C "XDR *xdrs;" .C "u_int sendsz, recvsz;" .C "char *handle;" .C "int (*readit) (), (*writeit) ();" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The stream's data is written to a buffer of size .IR sendsz ; a value of zero indicates the system should use a suitable default. The stream's data is read from a buffer of size .IR recvsz ; it too can be set to a suitable default by passing a zero value. When a stream's output buffer is full, .I writeit is called. Similarly, when a stream's input buffer is empty, .I readit is called. The behavior of these two routines is similar to .BR read (2) and .BR write (2), except that .I handle is passed to the former routines as the first parameter. Note: The .B XDR stream's .I op field must be set by the caller. .I sendsz and .I recvsz should be multiples of 4. .IP Warning: This .B XDR stream implements an intermediate record stream. Therefore there are additional bytes in the stream to provide record boundary information. .PP .nf .C "void" .C "xdrstdio_create(xdrs, filep, op)" .C "XDR *xdrs;" .C "FILE *filep;" .C "enum xdr_op op;" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The .B XDR stream data is written to, or read from, the Standard .B I/O stream .IR filep . The parameter .I op determines the direction of the .B XDR stream (either .BR \s-1XDR_ENCODE\s0 , .BR \s-1XDR_DECODE\s0 , or .BR \s-1XDR_FREE\s0 ). .IP Warning: The destroy routine associated with such .B XDR streams calls .B fflush() on the .I file stream, but never .BR fclose (3S). .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR read (2), .BR write (2), .BR fclose (3S), .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_simple (3C) .\" toc@\f3xdr_create(3C)\f1:\0\0\f4xdr_create()\fP, \f4xdr_destroy()\fP, \f4xdrmem_create()\fP, \n\f4xdrrec_create()\fP, \f4xdrstdio_create()\fP@@@library routines for external data stream creation .\" toc@\f4xdr_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdr_destroy()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrmem_create()\fP: library routines for extrnal data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrrec_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrstdio_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" index@library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdr_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdr_destroy()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrmem_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrrec_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrstdio_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" links@xdr_create.3c xdr_destroy.3c .\" links@xdr_create.3c xdrmem_create.3c .\" links@xdr_create.3c xdrrec_create.3c .\" links@xdr_create.3c xdrstdio_create.3c .\" $Header: xdr_admin.3c,v 74.1 95/05/10 22:07:16 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA x .TH xdr_admin 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_admin(), xdr_getpos(), xdr_inline(), xdrrec_endofrecord(), xdrrec_eof(), xdrrec_readbytes(), xdrrec_skiprecord(), xdr_setpos() \- library routines for management of the XDR stream .SH DESCRIPTION .B XDR library routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines deal specifically with the management of the .B XDR stream. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "u_int" .C "xdr_getpos(xdrs)" .C "XDR *xdrs;" .fi .IP Invoke the get-position routine associated with the .B XDR stream, .IR xdrs . The routine returns an unsigned integer, which indicates the position of the .B XDR byte stream. A desirable feature of .B XDR streams is that simple arithmetic works with this number, although the .B XDR stream instances need not guarantee this. .PP .nf .C "long *" .C "xdr_inline(xdrs, len)" .C "XDR *xdrs;" .C "int len;" .fi .IP Invoke the in-line routine associated with the .B XDR stream, .IR xdrs . The routine returns a pointer to a contiguous piece of the stream's buffer; .I len is the byte length of the desired buffer. Note: A pointer is cast to .BR "long *" . .IP Warning: .B xdr_inline() may return .B NULL if it cannot allocate a contiguous piece of a buffer. Therefore the behavior may vary among stream instances; it exists for the sake of efficiency. .PP .nf .C "bool_t" .C "xdrrec_endofrecord(xdrs, sendnow)" .C "XDR *xdrs;" .C "int sendnow;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). The data in the output buffer is marked as a completed record, and the output buffer is optionally written out if .I sendnow is non-zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdrrec_eof(xdrs, empty)" .C "XDR *xdrs;" .C "int empty;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). After consuming the rest of the current record in the stream, this routine returns .B TRUE if the stream has no more input, .B FALSE otherwise. .PP .nf .C "int" .C "xdrrec_readbytes(xdrs, addr, nbytes)" .C "XDR *xdrs;" .C "caddr_t addr;" .C "u_int nbytes;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It attempts to read .I nbytes bytes from the .B XDR stream into the buffer pointed to by .I addr. On success it returns the number of bytes read. Returns \-1 on failure. A return value of 0 indicates an end of record. .PP .nf .C "bool_t" .C "xdrrec_skiprecord(xdrs)" .C "XDR *xdrs;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It tells the .B XDR implementation that the rest of the current record in the stream's input buffer should be discarded. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_setpos(xdrs, pos)" .C "XDR *xdrs;" .C "u_int pos;" .fi .IP Invoke the set position routine associated with the .B XDR stream .IR xdrs . The parameter .I pos is a position value obtained from .BR xdr_getpos() . This routine returns 1 if the .B XDR stream could be repositioned, and 0 otherwise. .IP Warning: It is difficult to reposition some types of .B XDR streams, so this routine may fail with one type of stream and succeed with another. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_complex (3C), .BR xdr_create (3C), .BR xdr_simple (3C) .\" toc@\f3xdr_admin(3C)\f1:\0\0\f4xdr_admin()\fP, \f4xdr_getpos()\fP, \f4xdr_inline()\fP, \n\f4xdrrec_endofrecord()\fP, \f4xdrrec_eof()\fP, \f4xdrrec_readbytes()\fP, \n\f4xdrrec_skiprecord()\fP, \f4xdr_setpos()\fP@@@library routines for managing XDR streams .\" toc@\f4xdr_admin()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_getpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_inline()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_endofrecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_eof()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_readbytes()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_skiprecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_setpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" index@library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_admin()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_getpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_inline()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_endofrecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_eof()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_readbytes()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_skiprecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_setpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" links@xdr_admin.3c xdr_getpos.3c .\" links@xdr_admin.3c xdr_inline.3c .\" links@xdr_admin.3c xdrrec_endofrecord.3c .\" links@xdr_admin.3c xdrrec_eof.3c .\" links@xdr_admin.3c xdrrec_readbytes.3c .\" links@xdr_admin.3c xdrrec_skiprecord.3c .\" links@xdr_admin.3c xdr_setpos.3c .\" $Header: xdr_admin.3c,v 74.1 95/05/10 22:07:16 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA x .TH xdr_admin 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_admin(), xdr_getpos(), xdr_inline(), xdrrec_endofrecord(), xdrrec_eof(), xdrrec_readbytes(), xdrrec_skiprecord(), xdr_setpos() \- library routines for management of the XDR stream .SH DESCRIPTION .B XDR library routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines deal specifically with the management of the .B XDR stream. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "u_int" .C "xdr_getpos(xdrs)" .C "XDR *xdrs;" .fi .IP Invoke the get-position routine associated with the .B XDR stream, .IR xdrs . The routine returns an unsigned integer, which indicates the position of the .B XDR byte stream. A desirable feature of .B XDR streams is that simple arithmetic works with this number, although the .B XDR stream instances need not guarantee this. .PP .nf .C "long *" .C "xdr_inline(xdrs, len)" .C "XDR *xdrs;" .C "int len;" .fi .IP Invoke the in-line routine associated with the .B XDR stream, .IR xdrs . The routine returns a pointer to a contiguous piece of the stream's buffer; .I len is the byte length of the desired buffer. Note: A pointer is cast to .BR "long *" . .IP Warning: .B xdr_inline() may return .B NULL if it cannot allocate a contiguous piece of a buffer. Therefore the behavior may vary among stream instances; it exists for the sake of efficiency. .PP .nf .C "bool_t" .C "xdrrec_endofrecord(xdrs, sendnow)" .C "XDR *xdrs;" .C "int sendnow;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). The data in the output buffer is marked as a completed record, and the output buffer is optionally written out if .I sendnow is non-zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdrrec_eof(xdrs, empty)" .C "XDR *xdrs;" .C "int empty;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). After consuming the rest of the current record in the stream, this routine returns .B TRUE if the stream has no more input, .B FALSE otherwise. .PP .nf .C "int" .C "xdrrec_readbytes(xdrs, addr, nbytes)" .C "XDR *xdrs;" .C "caddr_t addr;" .C "u_int nbytes;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It attempts to read .I nbytes bytes from the .B XDR stream into the buffer pointed to by .I addr. On success it returns the number of bytes read. Returns \-1 on failure. A return value of 0 indicates an end of record. .PP .nf .C "bool_t" .C "xdrrec_skiprecord(xdrs)" .C "XDR *xdrs;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It tells the .B XDR implementation that the rest of the current record in the stream's input buffer should be discarded. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_setpos(xdrs, pos)" .C "XDR *xdrs;" .C "u_int pos;" .fi .IP Invoke the set position routine associated with the .B XDR stream .IR xdrs . The parameter .I pos is a position value obtained from .BR xdr_getpos() . This routine returns 1 if the .B XDR stream could be repositioned, and 0 otherwise. .IP Warning: It is difficult to reposition some types of .B XDR streams, so this routine may fail with one type of stream and succeed with another. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_complex (3C), .BR xdr_create (3C), .BR xdr_simple (3C) .\" toc@\f3xdr_admin(3C)\f1:\0\0\f4xdr_admin()\fP, \f4xdr_getpos()\fP, \f4xdr_inline()\fP, \n\f4xdrrec_endofrecord()\fP, \f4xdrrec_eof()\fP, \f4xdrrec_readbytes()\fP, \n\f4xdrrec_skiprecord()\fP, \f4xdr_setpos()\fP@@@library routines for managing XDR streams .\" toc@\f4xdr_admin()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_getpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_inline()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_endofrecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_eof()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_readbytes()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_skiprecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_setpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" index@library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_admin()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_getpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_inline()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_endofrecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_eof()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_readbytes()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_skiprecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_setpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" links@xdr_admin.3c xdr_getpos.3c .\" links@xdr_admin.3c xdr_inline.3c .\" links@xdr_admin.3c xdrrec_endofrecord.3c .\" links@xdr_admin.3c xdrrec_eof.3c .\" links@xdr_admin.3c xdrrec_readbytes.3c .\" links@xdr_admin.3c xdrrec_skiprecord.3c .\" links@xdr_admin.3c xdr_setpos.3c .\" $Header: xdr_admin.3c,v 74.1 95/05/10 22:07:16 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA x .TH xdr_admin 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_admin(), xdr_getpos(), xdr_inline(), xdrrec_endofrecord(), xdrrec_eof(), xdrrec_readbytes(), xdrrec_skiprecord(), xdr_setpos() \- library routines for management of the XDR stream .SH DESCRIPTION .B XDR library routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines deal specifically with the management of the .B XDR stream. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "u_int" .C "xdr_getpos(xdrs)" .C "XDR *xdrs;" .fi .IP Invoke the get-position routine associated with the .B XDR stream, .IR xdrs . The routine returns an unsigned integer, which indicates the position of the .B XDR byte stream. A desirable feature of .B XDR streams is that simple arithmetic works with this number, although the .B XDR stream instances need not guarantee this. .PP .nf .C "long *" .C "xdr_inline(xdrs, len)" .C "XDR *xdrs;" .C "int len;" .fi .IP Invoke the in-line routine associated with the .B XDR stream, .IR xdrs . The routine returns a pointer to a contiguous piece of the stream's buffer; .I len is the byte length of the desired buffer. Note: A pointer is cast to .BR "long *" . .IP Warning: .B xdr_inline() may return .B NULL if it cannot allocate a contiguous piece of a buffer. Therefore the behavior may vary among stream instances; it exists for the sake of efficiency. .PP .nf .C "bool_t" .C "xdrrec_endofrecord(xdrs, sendnow)" .C "XDR *xdrs;" .C "int sendnow;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). The data in the output buffer is marked as a completed record, and the output buffer is optionally written out if .I sendnow is non-zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdrrec_eof(xdrs, empty)" .C "XDR *xdrs;" .C "int empty;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). After consuming the rest of the current record in the stream, this routine returns .B TRUE if the stream has no more input, .B FALSE otherwise. .PP .nf .C "int" .C "xdrrec_readbytes(xdrs, addr, nbytes)" .C "XDR *xdrs;" .C "caddr_t addr;" .C "u_int nbytes;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It attempts to read .I nbytes bytes from the .B XDR stream into the buffer pointed to by .I addr. On success it returns the number of bytes read. Returns \-1 on failure. A return value of 0 indicates an end of record. .PP .nf .C "bool_t" .C "xdrrec_skiprecord(xdrs)" .C "XDR *xdrs;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It tells the .B XDR implementation that the rest of the current record in the stream's input buffer should be discarded. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_setpos(xdrs, pos)" .C "XDR *xdrs;" .C "u_int pos;" .fi .IP Invoke the set position routine associated with the .B XDR stream .IR xdrs . The parameter .I pos is a position value obtained from .BR xdr_getpos() . This routine returns 1 if the .B XDR stream could be repositioned, and 0 otherwise. .IP Warning: It is difficult to reposition some types of .B XDR streams, so this routine may fail with one type of stream and succeed with another. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_complex (3C), .BR xdr_create (3C), .BR xdr_simple (3C) .\" toc@\f3xdr_admin(3C)\f1:\0\0\f4xdr_admin()\fP, \f4xdr_getpos()\fP, \f4xdr_inline()\fP, \n\f4xdrrec_endofrecord()\fP, \f4xdrrec_eof()\fP, \f4xdrrec_readbytes()\fP, \n\f4xdrrec_skiprecord()\fP, \f4xdr_setpos()\fP@@@library routines for managing XDR streams .\" toc@\f4xdr_admin()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_getpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_inline()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_endofrecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_eof()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_readbytes()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_skiprecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_setpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" index@library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_admin()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_getpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_inline()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_endofrecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_eof()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_readbytes()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_skiprecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_setpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" links@xdr_admin.3c xdr_getpos.3c .\" links@xdr_admin.3c xdr_inline.3c .\" links@xdr_admin.3c xdrrec_endofrecord.3c .\" links@xdr_admin.3c xdrrec_eof.3c .\" links@xdr_admin.3c xdrrec_readbytes.3c .\" links@xdr_admin.3c xdrrec_skiprecord.3c .\" links@xdr_admin.3c xdr_setpos.3c .\" $Header: xdr_admin.3c,v 74.1 95/05/10 22:07:16 ssa Exp $ .ds RZ \&For HP Internal Use Only .ds RL Release 10.0 .TA x .TH xdr_admin 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_admin(), xdr_getpos(), xdr_inline(), xdrrec_endofrecord(), xdrrec_eof(), xdrrec_readbytes(), xdrrec_skiprecord(), xdr_setpos() \- library routines for management of the XDR stream .SH DESCRIPTION .B XDR library routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines deal specifically with the management of the .B XDR stream. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR data structure is defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "u_int" .C "xdr_getpos(xdrs)" .C "XDR *xdrs;" .fi .IP Invoke the get-position routine associated with the .B XDR stream, .IR xdrs . The routine returns an unsigned integer, which indicates the position of the .B XDR byte stream. A desirable feature of .B XDR streams is that simple arithmetic works with this number, although the .B XDR stream instances need not guarantee this. .PP .nf .C "long *" .C "xdr_inline(xdrs, len)" .C "XDR *xdrs;" .C "int len;" .fi .IP Invoke the in-line routine associated with the .B XDR stream, .IR xdrs . The routine returns a pointer to a contiguous piece of the stream's buffer; .I len is the byte length of the desired buffer. Note: A pointer is cast to .BR "long *" . .IP Warning: .B xdr_inline() may return .B NULL if it cannot allocate a contiguous piece of a buffer. Therefore the behavior may vary among stream instances; it exists for the sake of efficiency. .PP .nf .C "bool_t" .C "xdrrec_endofrecord(xdrs, sendnow)" .C "XDR *xdrs;" .C "int sendnow;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). The data in the output buffer is marked as a completed record, and the output buffer is optionally written out if .I sendnow is non-zero. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdrrec_eof(xdrs, empty)" .C "XDR *xdrs;" .C "int empty;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). After consuming the rest of the current record in the stream, this routine returns .B TRUE if the stream has no more input, .B FALSE otherwise. .PP .nf .C "int" .C "xdrrec_readbytes(xdrs, addr, nbytes)" .C "XDR *xdrs;" .C "caddr_t addr;" .C "u_int nbytes;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It attempts to read .I nbytes bytes from the .B XDR stream into the buffer pointed to by .I addr. On success it returns the number of bytes read. Returns \-1 on failure. A return value of 0 indicates an end of record. .PP .nf .C "bool_t" .C "xdrrec_skiprecord(xdrs)" .C "XDR *xdrs;" .fi .IP This routine can be invoked only on streams created by .B xdrrec_create() (see .BR xdr_create (3C)). It tells the .B XDR implementation that the rest of the current record in the stream's input buffer should be discarded. This routine returns .B TRUE if it succeeds, .B FALSE otherwise. .PP .nf .C "bool_t" .C "xdr_setpos(xdrs, pos)" .C "XDR *xdrs;" .C "u_int pos;" .fi .IP Invoke the set position routine associated with the .B XDR stream .IR xdrs . The parameter .I pos is a position value obtained from .BR xdr_getpos() . This routine returns 1 if the .B XDR stream could be repositioned, and 0 otherwise. .IP Warning: It is difficult to reposition some types of .B XDR streams, so this routine may fail with one type of stream and succeed with another. .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR xdr (3C), .BR xdr_complex (3C), .BR xdr_create (3C), .BR xdr_simple (3C) .\" toc@\f3xdr_admin(3C)\f1:\0\0\f4xdr_admin()\fP, \f4xdr_getpos()\fP, \f4xdr_inline()\fP, \n\f4xdrrec_endofrecord()\fP, \f4xdrrec_eof()\fP, \f4xdrrec_readbytes()\fP, \n\f4xdrrec_skiprecord()\fP, \f4xdr_setpos()\fP@@@library routines for managing XDR streams .\" toc@\f4xdr_admin()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_getpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_inline()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_endofrecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_eof()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_readbytes()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdrrec_skiprecord()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" toc@\f4xdr_setpos()\fP: library routines for managing XDR streams@@@see \f3xdr_admin(3C)\f1 .\" index@library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_admin()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_getpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_inline()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_endofrecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_eof()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_readbytes()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdrrec_skiprecord()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" index@\f4xdr_setpos()\fP \- library routines for managing XDR streams@@@\f3xdr_admin(3C)\f1 .\" links@xdr_admin.3c xdr_getpos.3c .\" links@xdr_admin.3c xdr_inline.3c .\" links@xdr_admin.3c xdrrec_endofrecord.3c .\" links@xdr_admin.3c xdrrec_eof.3c .\" links@xdr_admin.3c xdrrec_readbytes.3c .\" links@xdr_admin.3c xdrrec_skiprecord.3c .\" links@xdr_admin.3c xdr_setpos.3c .\" $Header: xdr_create.3c,v 74.1 95/05/10 22:07:43 ssa Exp $ .TA x .TH xdr_create 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME xdr_create(), xdr_destroy(), xdrmem_create(), xdrrec_create(), xdrstdio_create() \- library routines for external data representation stream creation .SH DESCRIPTION .B XDR library routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Protocols such as remote procedure calls (\s-1RPC\s0) use these routines to describe the format of the data. .PP These routines deal with the creation of .B XDR streams. .B XDR streams have to be created before any data can be translated into .B XDR format. .SS Routines The following routines require that the header .BR be included. .PP The .B XDR, CLIENT, and .B SVCXPRT data structures are defined in .IR "Power Programming with RPC". .TP .C "#include " .PP .nf .C "void" .C "xdr_destroy(xdrs)" .C "XDR *xdrs;" .fi .IP Invoke the destroy routine associated with the .B XDR stream, .IR xdrs . Destruction usually involves freeing private data structures associated with the stream. Using .I xdrs after invoking .B xdr_destroy() is undefined. .PP .nf .C "void" .C "xdrmem_create(xdrs, addr, size, op)" .C "XDR *xdrs;" .C "char *addr;" .C "u_int size;" .C "enum xdr_op op;" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The stream's data is written to, or read from, a chunk of memory at location .I addr whose length is no more than .I size bytes long. .I size should be a multiple of 4. The .I op determines the direction of the .B XDR stream (either .BR \s-1XDR_ENCODE\s0 , .BR \s-1XDR_DECODE\s0 , or .BR \s-1XDR_FREE\s0 ). .PP .nf .C "void" .C "xdrrec_create(xdrs, sendsz, recvsz, handle, readit, writeit)" .C "XDR *xdrs;" .C "u_int sendsz, recvsz;" .C "char *handle;" .C "int (*readit) (), (*writeit) ();" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The stream's data is written to a buffer of size .IR sendsz ; a value of zero indicates the system should use a suitable default. The stream's data is read from a buffer of size .IR recvsz ; it too can be set to a suitable default by passing a zero value. When a stream's output buffer is full, .I writeit is called. Similarly, when a stream's input buffer is empty, .I readit is called. The behavior of these two routines is similar to .BR read (2) and .BR write (2), except that .I handle is passed to the former routines as the first parameter. Note: The .B XDR stream's .I op field must be set by the caller. .I sendsz and .I recvsz should be multiples of 4. .IP Warning: This .B XDR stream implements an intermediate record stream. Therefore there are additional bytes in the stream to provide record boundary information. .PP .nf .C "void" .C "xdrstdio_create(xdrs, filep, op)" .C "XDR *xdrs;" .C "FILE *filep;" .C "enum xdr_op op;" .fi .IP This routine initializes the .B XDR stream object pointed to by .IR xdrs . The .B XDR stream data is written to, or read from, the Standard .B I/O stream .IR filep . The parameter .I op determines the direction of the .B XDR stream (either .BR \s-1XDR_ENCODE\s0 , .BR \s-1XDR_DECODE\s0 , or .BR \s-1XDR_FREE\s0 ). .IP Warning: The destroy routine associated with such .B XDR streams calls .B fflush() on the .I file stream, but never .BR fclose (3S). .SH AUTHOR .B xdr was developed by Sun Microsystems, Inc. .SH SEE ALSO .BR read (2), .BR write (2), .BR fclose (3S), .BR xdr (3C), .BR xdr_admin (3C), .BR xdr_complex (3C), .BR xdr_simple (3C) .\" toc@\f3xdr_create(3C)\f1:\0\0\f4xdr_create()\fP, \f4xdr_destroy()\fP, \f4xdrmem_create()\fP, \n\f4xdrrec_create()\fP, \f4xdrstdio_create()\fP@@@library routines for external data stream creation .\" toc@\f4xdr_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdr_destroy()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrmem_create()\fP: library routines for extrnal data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrrec_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" toc@\f4xdrstdio_create()\fP: library routines for external data stream creation@@@see \f3xdr_create(3C)\f1 .\" index@library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdr_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdr_destroy()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrmem_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrrec_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" index@\f4xdrstdio_create()\fP \- library routines for external data stream creation@@@\f3xdr_create(3C)\f1 .\" links@xdr_create.3c xdr_destroy.3c .\" links@xdr_create.3c xdrmem_create.3c .\" links@xdr_create.3c xdrrec_create.3c .\" links@xdr_create.3c xdrstdio_create.3c .\" $Header: rpc_svc_calls.3c,v 74.1 95/05/10 21:56:31 ssa Exp $ .TA r .TH rpc_svc_calls 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME registerrpc, svc_register, svc_unregister, xprt_register, xprt_unregister \- library routines for registering servers .SH SYNOPSIS .C "#include " .PP .nf .C /* registerrpc */ .C "int" .C "registerrpc(prognum, versnum, procnum, procname, inproc, outproc)" .C "u_long prognum, versnum, procnum;" .C "char *(*procname) ();" .C "xdrproc_t inproc, outproc;" .fi .PP .nf .C "/* svc_register */" .C "bool_t" .C "svc_register(xprt, prognum, versnum, dispatch, protocol)" .C "SVCXPRT *xprt;" .C "u_long prognum, versnum;" .C "void (*dispatch) ();" .C "u_long protocol;" .fi .PP .nf .C "/* svc_unregister */ .C "void" .C "svc_unregister(prognum, versnum)" .C "u_long prognum, versnum;" .fi .PP .nf .C /* xprt_register */ .C "void" .C "xprt_register(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* xprt_unregister */" .C "void" .C "xprt_unregister(xprt)" .C "SVCXPRT *xprt;" .fi .SH DESCRIPTION These routines are a part of the RPC library, which allows the RPC servers to register themselves with .IR portmap (1M), and it associates the given program and version number with the dispatch function. .SS Routines .PP To use these routines, the C programs must include the header file .CR . .PP The .C SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP 20 .C registerrpc Register procedure .I procname with the RPC service package. If a request arrives for program .IR prognum , version .IR versnum , and procedure .IR procnum , .I procname is called with a pointer to its parameter; .I progname must be a procedure that returns a pointer to its static result; .I inproc is used to decode the parameters while .I outproc is used to encode the results. This routine returns 0 if the registration succeeded, \-1 otherwise. .IP .BR Warning : Remote procedures registered in this form are accessed using the UDP/IP transport; see .C svcudp_create() on .IR rpc_svc_create (3C) for restrictions. This routine should not be used more than once for the same program and version number. .TP .C svc_register Associates .I prognum and .I versnum with the service dispatch procedure, .IR dispatch . If .I protocol is zero, the service is not registered with the .C portmap service. If .I protocol is non-zero, a mapping of the triple .RI [ "prognum, versnum, protocol"\f1] to .C xprt->xp_port is established with the local .C portmap service (generally .I protocol is zero, .C IPPROTO_UDP or .CR IPPROTO_TCP ). The procedure .I dispatch has the following form: .RS 2i .PP .nf .C "dispatch(request, xprt)" .C "struct svc_req *request;" .C "SVCXPRT *xprt;" .ft R .fi .RE .IP The .B svc_register() routine returns .C TRUE if it succeeds, and .C FALSE otherwise. .TP .C svc_unregister Remove all mapping of the pair .RI [ prognum , versnum ] to dispatch routines, and of the triple .RI [ prognum , versnum , *\f1] to port number. .TP .C xprt_register After RPC service transport handles are created, they should register themselves with the RPC service package. This routine modifies the global variable .IR svc_fds . Service implementors usually do not need this routine. .TP .C xprt_unregister Before an RPC service transport handle is destroyed, it should unregister itself with the RPC service package. This routine modifies the global variable .IR svc_fds . Service implementors usually do not need this routine directly. .SH AUTHOR .C rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M), portmap(3C), rpc(3C), rpc_svc_err(3C), rpc_svc_create(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3rpc_svc_calls(3C)\f1:\0\0\f4registerrpc()\f1,\f4svc_register()\f1, \f4svc_unregister()\f1, \f4xprt_register()\f1,\n \f4xprt_unregister()\f1@@@library routines for registering servers .\" toc@\f4registerrpc()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4svc_register()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4svc_unregister()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4xprt_register()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4xprt_unregister()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" index@\f4rpc_svc_calls(3C)\f1library routines for registering servers@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4registerrpc()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4svc_register()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4svc_unregister()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4xprt_register()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4xprt_unregister()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" links@rpc_svc_calls.3c registerrpc.3c .\" links@rpc_svc_calls.3c svc_register.3c .\" links@rpc_svc_calls.3c svc_unregister.3c .\" links@rpc_svc_calls.3c xprt_register.3c .\" links@rpc_svc_calls.3c xprt_unregister.3c .\" $Header: rpc_svc_calls.3c,v 74.1 95/05/10 21:56:31 ssa Exp $ .TA r .TH rpc_svc_calls 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME registerrpc, svc_register, svc_unregister, xprt_register, xprt_unregister \- library routines for registering servers .SH SYNOPSIS .C "#include " .PP .nf .C /* registerrpc */ .C "int" .C "registerrpc(prognum, versnum, procnum, procname, inproc, outproc)" .C "u_long prognum, versnum, procnum;" .C "char *(*procname) ();" .C "xdrproc_t inproc, outproc;" .fi .PP .nf .C "/* svc_register */" .C "bool_t" .C "svc_register(xprt, prognum, versnum, dispatch, protocol)" .C "SVCXPRT *xprt;" .C "u_long prognum, versnum;" .C "void (*dispatch) ();" .C "u_long protocol;" .fi .PP .nf .C "/* svc_unregister */ .C "void" .C "svc_unregister(prognum, versnum)" .C "u_long prognum, versnum;" .fi .PP .nf .C /* xprt_register */ .C "void" .C "xprt_register(xprt)" .C "SVCXPRT *xprt;" .fi .PP .nf .C "/* xprt_unregister */" .C "void" .C "xprt_unregister(xprt)" .C "SVCXPRT *xprt;" .fi .SH DESCRIPTION These routines are a part of the RPC library, which allows the RPC servers to register themselves with .IR portmap (1M), and it associates the given program and version number with the dispatch function. .SS Routines .PP To use these routines, the C programs must include the header file .CR . .PP The .C SVCXPRT data structure is defined in .IR "Power Programming with RPC". .TP 20 .C registerrpc Register procedure .I procname with the RPC service package. If a request arrives for program .IR prognum , version .IR versnum , and procedure .IR procnum , .I procname is called with a pointer to its parameter; .I progname must be a procedure that returns a pointer to its static result; .I inproc is used to decode the parameters while .I outproc is used to encode the results. This routine returns 0 if the registration succeeded, \-1 otherwise. .IP .BR Warning : Remote procedures registered in this form are accessed using the UDP/IP transport; see .C svcudp_create() on .IR rpc_svc_create (3C) for restrictions. This routine should not be used more than once for the same program and version number. .TP .C svc_register Associates .I prognum and .I versnum with the service dispatch procedure, .IR dispatch . If .I protocol is zero, the service is not registered with the .C portmap service. If .I protocol is non-zero, a mapping of the triple .RI [ "prognum, versnum, protocol"\f1] to .C xprt->xp_port is established with the local .C portmap service (generally .I protocol is zero, .C IPPROTO_UDP or .CR IPPROTO_TCP ). The procedure .I dispatch has the following form: .RS 2i .PP .nf .C "dispatch(request, xprt)" .C "struct svc_req *request;" .C "SVCXPRT *xprt;" .ft R .fi .RE .IP The .B svc_register() routine returns .C TRUE if it succeeds, and .C FALSE otherwise. .TP .C svc_unregister Remove all mapping of the pair .RI [ prognum , versnum ] to dispatch routines, and of the triple .RI [ prognum , versnum , *\f1] to port number. .TP .C xprt_register After RPC service transport handles are created, they should register themselves with the RPC service package. This routine modifies the global variable .IR svc_fds . Service implementors usually do not need this routine. .TP .C xprt_unregister Before an RPC service transport handle is destroyed, it should unregister itself with the RPC service package. This routine modifies the global variable .IR svc_fds . Service implementors usually do not need this routine directly. .SH AUTHOR .C rpc was developed by Sun Microsystems, Inc. .SH SEE ALSO portmap(1M), portmap(3C), rpc(3C), rpc_svc_err(3C), rpc_svc_create(3C), rpc_svc_reg(3C). .br .I "Power Programming with RPC" .\" .\" toc@\f3rpc_svc_calls(3C)\f1:\0\0\f4registerrpc()\f1,\f4svc_register()\f1, \f4svc_unregister()\f1, \f4xprt_register()\f1,\n \f4xprt_unregister()\f1@@@library routines for registering servers .\" toc@\f4registerrpc()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4svc_register()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4svc_unregister()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4xprt_register()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" toc@\f4xprt_unregister()\f1:\0\0@@@see \f3rpc_svc_calls(3C)\f1 .\" index@\f4rpc_svc_calls(3C)\f1library routines for registering servers@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4registerrpc()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4svc_register()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4svc_unregister()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4xprt_register()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" index@\f4xprt_unregister()\f1@@@\f3rpc_svc_calls(3C)\f1 .\" links@rpc_svc_calls.3c registerrpc.3c .\" links@rpc_svc_calls.3c svc_register.3c .\" links@rpc_svc_calls.3c svc_unregister.3c .\" links@rpc_svc_calls.3c xprt_register.3c .\" links@rpc_svc_calls.3c xprt_unregister.3c .\" $Header: y0.3m,v 78.1 96/02/13 14:16:13 ssa Exp $ .TA y .TH y0 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME y0(\|), y1(\|), yn(\|) \- Bessel functions of the second kind .SH SYNOPSIS .C "#include " .PP .C "double y0(double x);" .PP .C "double y1(double x);" .PP .C "double yn(int n, double x);" .SH DESCRIPTION .CR y0() and .CR y1() return the Bessel functions of .I x of the second kind of orders 0 and 1 respectively. .CR yn() returns the Bessel function of .I x of the second kind of order .IR n . The value of .I x must be positive. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE .PP If .I x is negative or zero, .CR y0() , .CR y1() , and .CR yn() return .CR \(miHUGE_VAL . .PP If .I x is NaN, .CR y0() , .CR y1() , and .CR yn() return NaN. .PP If the correct result after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR y0() , .CR y1() , and .CR yn() return zero. .PP If the correct result would overflow, .CR y0() , .CR y1() , and .CR yn() return .CR \(miHUGE_VAL . .SH ERRORS No errors are defined. .SH SEE ALSO j0(3M), isnan(3M), values(5). .PP M. Abramowitz and I. Stegun, .I "Handbook of Mathematical Functions" (New York: Dover Publications, 1972). .SH STANDARDS CONFORMANCE .CR y0() ": SVID3, XPG4.2" .PP .CR y1() ": SVID3, XPG4.2" .PP .CR yn() ": SVID3, XPG4.2" .\" .\" index@\f4y0()\f1, \f4y1()\f1, \f4yn()\fP \- Bessel functions of the second kind@@@\f3y0(3M)\f1 .\" index@\f1math: Bessel functions of the second kind@@@\f3y0(3M)\f1 .\" index@\f1Bessel functions of the second kind@@@\f3y0(3M)\f1 .\" index@\f4y1()\f1 \- Bessel function@@@\f3y0(3M)\f1 .\" index@\f4yn()\f1 \- Bessel function@@@\f3y0(3M)\f1 .\" .\" toc@\f3y0(3M)\f1:\0\0\f4y0()\f1, \f4y1()\f1, \f4yn()\f1@@@Bessel functions of the second kind .\" toc@\f4y1()\f1:\0\0Bessel function@@@see \f3y0(3M)\f1 .\" toc@\f4yn()\f1:\0\0Bessel function@@@see \f3y0(3M)\f1 .\" .\" links@y0.3m y1.3m .\" links@y0.3m yn.3m .\" .\" fileset_database@y0.3m PROGRAMING-MAN .\" $Header: y0.3m,v 78.1 96/02/13 14:16:13 ssa Exp $ .TA y .TH y0 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME y0(\|), y1(\|), yn(\|) \- Bessel functions of the second kind .SH SYNOPSIS .C "#include " .PP .C "double y0(double x);" .PP .C "double y1(double x);" .PP .C "double yn(int n, double x);" .SH DESCRIPTION .CR y0() and .CR y1() return the Bessel functions of .I x of the second kind of orders 0 and 1 respectively. .CR yn() returns the Bessel function of .I x of the second kind of order .IR n . The value of .I x must be positive. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE .PP If .I x is negative or zero, .CR y0() , .CR y1() , and .CR yn() return .CR \(miHUGE_VAL . .PP If .I x is NaN, .CR y0() , .CR y1() , and .CR yn() return NaN. .PP If the correct result after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR y0() , .CR y1() , and .CR yn() return zero. .PP If the correct result would overflow, .CR y0() , .CR y1() , and .CR yn() return .CR \(miHUGE_VAL . .SH ERRORS No errors are defined. .SH SEE ALSO j0(3M), isnan(3M), values(5). .PP M. Abramowitz and I. Stegun, .I "Handbook of Mathematical Functions" (New York: Dover Publications, 1972). .SH STANDARDS CONFORMANCE .CR y0() ": SVID3, XPG4.2" .PP .CR y1() ": SVID3, XPG4.2" .PP .CR yn() ": SVID3, XPG4.2" .\" .\" index@\f4y0()\f1, \f4y1()\f1, \f4yn()\fP \- Bessel functions of the second kind@@@\f3y0(3M)\f1 .\" index@\f1math: Bessel functions of the second kind@@@\f3y0(3M)\f1 .\" index@\f1Bessel functions of the second kind@@@\f3y0(3M)\f1 .\" index@\f4y1()\f1 \- Bessel function@@@\f3y0(3M)\f1 .\" index@\f4yn()\f1 \- Bessel function@@@\f3y0(3M)\f1 .\" .\" toc@\f3y0(3M)\f1:\0\0\f4y0()\f1, \f4y1()\f1, \f4yn()\f1@@@Bessel functions of the second kind .\" toc@\f4y1()\f1:\0\0Bessel function@@@see \f3y0(3M)\f1 .\" toc@\f4yn()\f1:\0\0Bessel function@@@see \f3y0(3M)\f1 .\" .\" links@y0.3m y1.3m .\" links@y0.3m yn.3m .\" .\" fileset_database@y0.3m PROGRAMING-MAN .\" $Header: y0.3m,v 78.1 96/02/13 14:16:13 ssa Exp $ .TA y .TH y0 3M .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME y0(\|), y1(\|), yn(\|) \- Bessel functions of the second kind .SH SYNOPSIS .C "#include " .PP .C "double y0(double x);" .PP .C "double y1(double x);" .PP .C "double yn(int n, double x);" .SH DESCRIPTION .CR y0() and .CR y1() return the Bessel functions of .I x of the second kind of orders 0 and 1 respectively. .CR yn() returns the Bessel function of .I x of the second kind of order .IR n . The value of .I x must be positive. .PP To use these functions, link in the math library by specifying .CR \-lm on the compiler or linker command line. .SH RETURN VALUE .PP If .I x is negative or zero, .CR y0() , .CR y1() , and .CR yn() return .CR \(miHUGE_VAL . .PP If .I x is NaN, .CR y0() , .CR y1() , and .CR yn() return NaN. .PP If the correct result after rounding would be smaller in magnitude than .CR MINDOUBLE , .CR y0() , .CR y1() , and .CR yn() return zero. .PP If the correct result would overflow, .CR y0() , .CR y1() , and .CR yn() return .CR \(miHUGE_VAL . .SH ERRORS No errors are defined. .SH SEE ALSO j0(3M), isnan(3M), values(5). .PP M. Abramowitz and I. Stegun, .I "Handbook of Mathematical Functions" (New York: Dover Publications, 1972). .SH STANDARDS CONFORMANCE .CR y0() ": SVID3, XPG4.2" .PP .CR y1() ": SVID3, XPG4.2" .PP .CR yn() ": SVID3, XPG4.2" .\" .\" index@\f4y0()\f1, \f4y1()\f1, \f4yn()\fP \- Bessel functions of the second kind@@@\f3y0(3M)\f1 .\" index@\f1math: Bessel functions of the second kind@@@\f3y0(3M)\f1 .\" index@\f1Bessel functions of the second kind@@@\f3y0(3M)\f1 .\" index@\f4y1()\f1 \- Bessel function@@@\f3y0(3M)\f1 .\" index@\f4yn()\f1 \- Bessel function@@@\f3y0(3M)\f1 .\" .\" toc@\f3y0(3M)\f1:\0\0\f4y0()\f1, \f4y1()\f1, \f4yn()\f1@@@Bessel functions of the second kind .\" toc@\f4y1()\f1:\0\0Bessel function@@@see \f3y0(3M)\f1 .\" toc@\f4yn()\f1:\0\0Bessel function@@@see \f3y0(3M)\f1 .\" .\" links@y0.3m y1.3m .\" links@y0.3m yn.3m .\" .\" fileset_database@y0.3m PROGRAMING-MAN .\" $Header: ypclnt.3c,v 72.6 94/10/31 13:44:14 ssa Exp $ .TA y .TH ypclnt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypclnt(\|), yp_all(\|), yp_bind(\|), yp_first(\|), yp_get_default_domain(\|), yp_master(\|), yp_match(\|), yp_next(\|), yp_order(\|), yp_unbind(\|), yperr_string(\|), ypprot_err(\|) \- Network Information Service client interface .SH SYNOPSIS .nf .C #include .PP .C #include .C #include .C #include .PP .C int yp_all( .C " char *indomain," .C " char *inmap," .C " struct ypall_callback incallback" .C ); .PP .C int yp_bind(char *indomain); .PP .C int yp_first( .C " char *indomain," .C " char *inmap," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C "int yp_get_default_domain(char **outdomain);" .PP .C int yp_master( .C " char *indomain," .C " char *inmap," .C " char **outmaster" .C ); .PP .C int yp_match( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_next( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_order( .C " char *indomain," .C " char *inmap," .C " unsigned long *outorder" .C ); .PP .C "void yp_unbind(char *indomain);" .PP .C "char *yperr_string(int incode);" .PP .C "int ypprot_err(unsigned int incode);" .fi .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These functions provide an interface to the Network Information Service (NIS) network-lookup service. Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of the NIS, including the definitions of .I map and NIS .IR domain , and a description of the various servers, databases, and commands comprising the NIS. .PP Input parameter names begin with .CR in ; output parameter names begin with .CR out . Output parameters of type .CR char ** should be the addresses of uninitialized character pointers. Memory is allocated by the NIS client package using .CR malloc() and can be freed if the user code has no continuing need for it (see .IR malloc (3C)). For each .I outkey and .IR outval , two extra bytes of memory are allocated at the end that contain new-line and null (in that order), but these two bytes are not reflected in .I outkeylen and .IR outvallen . The .I indomain and .I inmap strings must be non-null and null-terminated. String parameters that are accompanied by a length parameter cannot be null, but can point to null strings with a length parameter of zero. Counted strings need not be null-terminated. .PP The NIS lookup calls require a map (database) name and a NIS domain name. The client process should know the name of the map of interest. Client processes should obtain the host's NIS domain by calling .CR yp_get_default_domain() and use the returned .I outdomain as the .I indomain parameter to subsequent NIS calls. .PP To use the NIS services, the client process must be ``bound'' to an NIS server that serves the appropriate NIS domain using .CR yp_bind() . Binding does not have to occur explicitly by user code. Rather, it occurs automatically whenever a NIS lookup function is called. .CR yp_bind() can be called directly for processes that use a backup strategy (such as a local file) when NIS services are not available. .PP Each binding allocates (uses up) one client process socket descriptor. Each bound NIS domain costs one socket descriptor. However, multiple requests to the same NIS domain use that same descriptor. .CR yp_unbind() is available at the client interface for processes that explicitly manage their socket descriptors while accessing multiple NIS domains. The call to .CR yp_unbind makes the NIS domain .B unbound and frees all per-process and per-node resources used to bind it. .PP If an RPC failure results when using a binding, that NIS domain is unbound automatically. The ypclnt layer then continues retrying until the operation succeeds, provided .CR ypbind is running (see .IR ypbind (1M)) and either: .RS .TP 3 a. the client process cannot bind a server for the proper NIS domain, or .TP b. RPC requests to the server fail. .RE .PP If an error is not RPC-related, if .CR ypbind is not running, or if a bound .CR ypserv process returns any answer (success or failure), the ypclnt layer returns control to the user code with either an error code or with a success code and any results (see .IR ypbind (1M) and .IR ypserv (1M)). .SS Operational Behavior .TP 20 .CR yp_match() Returns the value associated with a passed key. This key must be exact; no pattern matching is available. .TP .CR yp_first() Returns the first key-value pair from the named map in the named NIS domain. .TP .CR yp_next() Returns the next key-value pair in a named map. To obtain the second key-value pair, the .I inkey parameter should be the .I outkey returned from an initial call to .CR yp_first() . To obtain the .RI ( "n + 1" )th key-value pair, the .I inkey value should be the .I outkey value from the .IR n th call to .CR yp_next() . .IP The concepts of first and next are particular to the structure of the NIS map being processed. No relation in retrieval order exists to either the lexical order within any original ASCII file or to any obvious numerical sorting order on the keys, values, or key-value pairs. The only ordering guarantee is that if the .CR yp_first() function is called on a particular map and the .CR yp_next() function is called repeatedly on the same map at the same server until the call fails with an error of YPERR_NOMORE, every entry in the database is retrieved exactly once. If the same sequence of operations is performed on the same map at the same server, the entries are retrieved in the same order. .IP Under conditions of heavy server load or server failure, the NIS domain may become unbound and bind again (perhaps to a different server) while a client is running. This process can cause a break in one of the enumeration (retrieval) rules: specific entries may be seen twice by the client or not at all. This approach protects the client from error messages that would otherwise be returned in the midst of the enumeration. .IP .CR yp_all() describes a better solution to enumerating all entries in a map. .TP .CR yp_all() Provides a way to transfer an entire map from server to client in a single request using TCP (rather than UDP as with other functions in this package). The entire transaction occurs as a single RPC request and response. You can use .CR yp_all() like any other NIS procedure by identifying the map in the normal manner and supplying the name of a function called to process each key-value pair within the map. A return from the call to .CR yp_all() occurs only when the transaction is completed (either successfully or unsuccessfully) or the .I foreach function decides it does not want any more key-value pairs. .IP The third parameter to .CR yp_all() is: .RS .nf .IP .CR "struct ypall_callback *incallback {" .CR " int (*foreach)();" .CR " char *data;" .CR }; .fi .RE .IP The function .CR foreach() is called as follows: .RS .nf .IP .CR foreach( .CR " int instatus;" .CR " char *inkey;" .CR " int inkeylen;" .CR " char *inval;" .CR " int invallen;" .CR " char *indata;" .CR ); .fi .RE .IP Where: .RS .TP 15 .I instatus Holds one of the return status values defined in .RC < rpcsvc/yp_prot.h >: either .CR YP_TRUE or an error code (see .CR ypprot_err() below, for a function that converts a NIS protocol error code to a ypclnt layer error code, as defined in .RC < rpcsvc/ypclnt.h >). .TP .I inkey .PD 0 .TP .I inval .sp -2v The key and value parameters are somewhat different than defined in the SYNOPSIS section above. First, the memory pointed to by .I inkey and .I inval is private to .CR yp_all() , and is overwritten with the arrival of each new key-value pair. Therefore, .CR foreach() should do something useful with the contents of that memory, but it does not own the memory. Key and value objects presented to the .CR foreach() look exactly as they do in the server's map. Therefore, if they were not newline-terminated or null-terminated in the map, they will not be terminated with newline or null characters here, either. .PD .TP .I indata Is the contents of the .I incallback\|\(mi>\|data element passed to .CR yp_all() The .I data element of the callback structure can share state information between .CR foreach() and the mainline code. Its use is optional, and no part of the NIS client package inspects its contents. Cast it to something useful or ignore it as appropriate. .RE .IP The .CR foreach() function is Boolean. It should return zero to indicate it needs to be called again for further received key-value pairs, or non-zero to stop the flow of key-value pairs. If .CR foreach() returns a non-zero value, it is not called again and the functional value of .CR yp_all() is then 0. .TP .CR yp_order() Returns the order number for a map. .TP .CR yp_master() Returns the host name of the master NIS server for a map. .TP .CR yperr_string() Returns a pointer to an error message string that is null-terminated, but contains no period or newline. .TP .CR ypprot_err() Takes an NIS protocol error code as input and returns a ypclnt layer error code that can be used as input to .CR yperr_string() .SH RETURN VALUE All functions in this package of type .CR int return 0 if the requested operation is successful or one of the following errors if the operation fails. .RS .TP 22 [YPERR_ACCESS] database access violation .TP [YPERR_BADARGS] args to function are bad .TP [YPERR_BADDB] NIS map is defective .TP [YPERR_BUSY] database busy .TP [YPERR_DOMAIN] cannot bind to server on this NIS domain .TP [YPERR_KEY] no such key in map .TP [YPERR_MAP] no such map in server's NIS domain .TP [YPERR_NODOM] local NIS domain name not set .TP [YPERR_NOMORE] no more records in map .TP [YPERR_PMAP] cannot communicate with portmap .TP [YPERR_RESRC] resource allocation failure .TP [YPERR_RPC] RPC failure \(mi NIS domain has been unbound .TP [YPERR_VERS] NIS client/server version mismatch: the NIS server bound to uses Version 1 protocol, so it does not provide .CR yp_all() functionality .TP [YPERR_YPBIND] cannot communicate with ypbind .TP [YPERR_YPERR] internal NIS server or client error .TP [YPERR_YPSERV] cannot communicate with ypserv .SH AUTHOR .CR ypclnt() was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4). .\" index@Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@client interface, Network Information Service@@@\f3ypclnt(3C)\f1 .\" index@interface, Network Information Service client@@@\f3ypclnt(3C)\f1 .\" index@\f4ypclnt()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_all()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_bind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_first()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_master()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_match()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_next()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_order()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_unbind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yperr_string()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4ypprot_err()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" toc@\f3ypclnt(3C)\f1:\0\0\f4ypclnt()\f1, \f4yp_all()\f1, \f4yp_bind()\f1, \f4yp_first()\f1, \f4yp_get_default_domain()\f1,\n\f4yp_master()\f1, \f4yp_match()\f1, \f4yp_next()\f1, \f4yp_order()\f1, \f4yp_unbind()\f1,\n\f4yperr_string()\f1, \f4ypprot_err()\f1@@@Network Information Service client interface .\" toc@\f4yp_all()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_bind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_first()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_master()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_match()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_next()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_order()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_unbind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yperr_string()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4ypprot_err()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" .\" links@ypclnt.3c yp_all.3c .\" links@ypclnt.3c yp_bind.3c .\" links@ypclnt.3c yp_first.3c .\" links@ypclnt.3c yp_get_defa.3c .\" links@ypclnt.3c yp_master.3c .\" links@ypclnt.3c yp_match.3c .\" links@ypclnt.3c yp_next.3c .\" links@ypclnt.3c yp_order.3c .\" links@ypclnt.3c yp_unbind.3c .\" links@ypclnt.3c yperr_strin.3c .\" links@ypclnt.3c ypprot_err.3c .\" $Header: ypclnt.3c,v 72.6 94/10/31 13:44:14 ssa Exp $ .TA y .TH ypclnt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypclnt(\|), yp_all(\|), yp_bind(\|), yp_first(\|), yp_get_default_domain(\|), yp_master(\|), yp_match(\|), yp_next(\|), yp_order(\|), yp_unbind(\|), yperr_string(\|), ypprot_err(\|) \- Network Information Service client interface .SH SYNOPSIS .nf .C #include .PP .C #include .C #include .C #include .PP .C int yp_all( .C " char *indomain," .C " char *inmap," .C " struct ypall_callback incallback" .C ); .PP .C int yp_bind(char *indomain); .PP .C int yp_first( .C " char *indomain," .C " char *inmap," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C "int yp_get_default_domain(char **outdomain);" .PP .C int yp_master( .C " char *indomain," .C " char *inmap," .C " char **outmaster" .C ); .PP .C int yp_match( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_next( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_order( .C " char *indomain," .C " char *inmap," .C " unsigned long *outorder" .C ); .PP .C "void yp_unbind(char *indomain);" .PP .C "char *yperr_string(int incode);" .PP .C "int ypprot_err(unsigned int incode);" .fi .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These functions provide an interface to the Network Information Service (NIS) network-lookup service. Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of the NIS, including the definitions of .I map and NIS .IR domain , and a description of the various servers, databases, and commands comprising the NIS. .PP Input parameter names begin with .CR in ; output parameter names begin with .CR out . Output parameters of type .CR char ** should be the addresses of uninitialized character pointers. Memory is allocated by the NIS client package using .CR malloc() and can be freed if the user code has no continuing need for it (see .IR malloc (3C)). For each .I outkey and .IR outval , two extra bytes of memory are allocated at the end that contain new-line and null (in that order), but these two bytes are not reflected in .I outkeylen and .IR outvallen . The .I indomain and .I inmap strings must be non-null and null-terminated. String parameters that are accompanied by a length parameter cannot be null, but can point to null strings with a length parameter of zero. Counted strings need not be null-terminated. .PP The NIS lookup calls require a map (database) name and a NIS domain name. The client process should know the name of the map of interest. Client processes should obtain the host's NIS domain by calling .CR yp_get_default_domain() and use the returned .I outdomain as the .I indomain parameter to subsequent NIS calls. .PP To use the NIS services, the client process must be ``bound'' to an NIS server that serves the appropriate NIS domain using .CR yp_bind() . Binding does not have to occur explicitly by user code. Rather, it occurs automatically whenever a NIS lookup function is called. .CR yp_bind() can be called directly for processes that use a backup strategy (such as a local file) when NIS services are not available. .PP Each binding allocates (uses up) one client process socket descriptor. Each bound NIS domain costs one socket descriptor. However, multiple requests to the same NIS domain use that same descriptor. .CR yp_unbind() is available at the client interface for processes that explicitly manage their socket descriptors while accessing multiple NIS domains. The call to .CR yp_unbind makes the NIS domain .B unbound and frees all per-process and per-node resources used to bind it. .PP If an RPC failure results when using a binding, that NIS domain is unbound automatically. The ypclnt layer then continues retrying until the operation succeeds, provided .CR ypbind is running (see .IR ypbind (1M)) and either: .RS .TP 3 a. the client process cannot bind a server for the proper NIS domain, or .TP b. RPC requests to the server fail. .RE .PP If an error is not RPC-related, if .CR ypbind is not running, or if a bound .CR ypserv process returns any answer (success or failure), the ypclnt layer returns control to the user code with either an error code or with a success code and any results (see .IR ypbind (1M) and .IR ypserv (1M)). .SS Operational Behavior .TP 20 .CR yp_match() Returns the value associated with a passed key. This key must be exact; no pattern matching is available. .TP .CR yp_first() Returns the first key-value pair from the named map in the named NIS domain. .TP .CR yp_next() Returns the next key-value pair in a named map. To obtain the second key-value pair, the .I inkey parameter should be the .I outkey returned from an initial call to .CR yp_first() . To obtain the .RI ( "n + 1" )th key-value pair, the .I inkey value should be the .I outkey value from the .IR n th call to .CR yp_next() . .IP The concepts of first and next are particular to the structure of the NIS map being processed. No relation in retrieval order exists to either the lexical order within any original ASCII file or to any obvious numerical sorting order on the keys, values, or key-value pairs. The only ordering guarantee is that if the .CR yp_first() function is called on a particular map and the .CR yp_next() function is called repeatedly on the same map at the same server until the call fails with an error of YPERR_NOMORE, every entry in the database is retrieved exactly once. If the same sequence of operations is performed on the same map at the same server, the entries are retrieved in the same order. .IP Under conditions of heavy server load or server failure, the NIS domain may become unbound and bind again (perhaps to a different server) while a client is running. This process can cause a break in one of the enumeration (retrieval) rules: specific entries may be seen twice by the client or not at all. This approach protects the client from error messages that would otherwise be returned in the midst of the enumeration. .IP .CR yp_all() describes a better solution to enumerating all entries in a map. .TP .CR yp_all() Provides a way to transfer an entire map from server to client in a single request using TCP (rather than UDP as with other functions in this package). The entire transaction occurs as a single RPC request and response. You can use .CR yp_all() like any other NIS procedure by identifying the map in the normal manner and supplying the name of a function called to process each key-value pair within the map. A return from the call to .CR yp_all() occurs only when the transaction is completed (either successfully or unsuccessfully) or the .I foreach function decides it does not want any more key-value pairs. .IP The third parameter to .CR yp_all() is: .RS .nf .IP .CR "struct ypall_callback *incallback {" .CR " int (*foreach)();" .CR " char *data;" .CR }; .fi .RE .IP The function .CR foreach() is called as follows: .RS .nf .IP .CR foreach( .CR " int instatus;" .CR " char *inkey;" .CR " int inkeylen;" .CR " char *inval;" .CR " int invallen;" .CR " char *indata;" .CR ); .fi .RE .IP Where: .RS .TP 15 .I instatus Holds one of the return status values defined in .RC < rpcsvc/yp_prot.h >: either .CR YP_TRUE or an error code (see .CR ypprot_err() below, for a function that converts a NIS protocol error code to a ypclnt layer error code, as defined in .RC < rpcsvc/ypclnt.h >). .TP .I inkey .PD 0 .TP .I inval .sp -2v The key and value parameters are somewhat different than defined in the SYNOPSIS section above. First, the memory pointed to by .I inkey and .I inval is private to .CR yp_all() , and is overwritten with the arrival of each new key-value pair. Therefore, .CR foreach() should do something useful with the contents of that memory, but it does not own the memory. Key and value objects presented to the .CR foreach() look exactly as they do in the server's map. Therefore, if they were not newline-terminated or null-terminated in the map, they will not be terminated with newline or null characters here, either. .PD .TP .I indata Is the contents of the .I incallback\|\(mi>\|data element passed to .CR yp_all() The .I data element of the callback structure can share state information between .CR foreach() and the mainline code. Its use is optional, and no part of the NIS client package inspects its contents. Cast it to something useful or ignore it as appropriate. .RE .IP The .CR foreach() function is Boolean. It should return zero to indicate it needs to be called again for further received key-value pairs, or non-zero to stop the flow of key-value pairs. If .CR foreach() returns a non-zero value, it is not called again and the functional value of .CR yp_all() is then 0. .TP .CR yp_order() Returns the order number for a map. .TP .CR yp_master() Returns the host name of the master NIS server for a map. .TP .CR yperr_string() Returns a pointer to an error message string that is null-terminated, but contains no period or newline. .TP .CR ypprot_err() Takes an NIS protocol error code as input and returns a ypclnt layer error code that can be used as input to .CR yperr_string() .SH RETURN VALUE All functions in this package of type .CR int return 0 if the requested operation is successful or one of the following errors if the operation fails. .RS .TP 22 [YPERR_ACCESS] database access violation .TP [YPERR_BADARGS] args to function are bad .TP [YPERR_BADDB] NIS map is defective .TP [YPERR_BUSY] database busy .TP [YPERR_DOMAIN] cannot bind to server on this NIS domain .TP [YPERR_KEY] no such key in map .TP [YPERR_MAP] no such map in server's NIS domain .TP [YPERR_NODOM] local NIS domain name not set .TP [YPERR_NOMORE] no more records in map .TP [YPERR_PMAP] cannot communicate with portmap .TP [YPERR_RESRC] resource allocation failure .TP [YPERR_RPC] RPC failure \(mi NIS domain has been unbound .TP [YPERR_VERS] NIS client/server version mismatch: the NIS server bound to uses Version 1 protocol, so it does not provide .CR yp_all() functionality .TP [YPERR_YPBIND] cannot communicate with ypbind .TP [YPERR_YPERR] internal NIS server or client error .TP [YPERR_YPSERV] cannot communicate with ypserv .SH AUTHOR .CR ypclnt() was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4). .\" index@Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@client interface, Network Information Service@@@\f3ypclnt(3C)\f1 .\" index@interface, Network Information Service client@@@\f3ypclnt(3C)\f1 .\" index@\f4ypclnt()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_all()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_bind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_first()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_master()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_match()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_next()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_order()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_unbind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yperr_string()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4ypprot_err()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" toc@\f3ypclnt(3C)\f1:\0\0\f4ypclnt()\f1, \f4yp_all()\f1, \f4yp_bind()\f1, \f4yp_first()\f1, \f4yp_get_default_domain()\f1,\n\f4yp_master()\f1, \f4yp_match()\f1, \f4yp_next()\f1, \f4yp_order()\f1, \f4yp_unbind()\f1,\n\f4yperr_string()\f1, \f4ypprot_err()\f1@@@Network Information Service client interface .\" toc@\f4yp_all()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_bind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_first()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_master()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_match()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_next()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_order()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_unbind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yperr_string()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4ypprot_err()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" .\" links@ypclnt.3c yp_all.3c .\" links@ypclnt.3c yp_bind.3c .\" links@ypclnt.3c yp_first.3c .\" links@ypclnt.3c yp_get_defa.3c .\" links@ypclnt.3c yp_master.3c .\" links@ypclnt.3c yp_match.3c .\" links@ypclnt.3c yp_next.3c .\" links@ypclnt.3c yp_order.3c .\" links@ypclnt.3c yp_unbind.3c .\" links@ypclnt.3c yperr_strin.3c .\" links@ypclnt.3c ypprot_err.3c .\" $Header: ypclnt.3c,v 72.6 94/10/31 13:44:14 ssa Exp $ .TA y .TH ypclnt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypclnt(\|), yp_all(\|), yp_bind(\|), yp_first(\|), yp_get_default_domain(\|), yp_master(\|), yp_match(\|), yp_next(\|), yp_order(\|), yp_unbind(\|), yperr_string(\|), ypprot_err(\|) \- Network Information Service client interface .SH SYNOPSIS .nf .C #include .PP .C #include .C #include .C #include .PP .C int yp_all( .C " char *indomain," .C " char *inmap," .C " struct ypall_callback incallback" .C ); .PP .C int yp_bind(char *indomain); .PP .C int yp_first( .C " char *indomain," .C " char *inmap," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C "int yp_get_default_domain(char **outdomain);" .PP .C int yp_master( .C " char *indomain," .C " char *inmap," .C " char **outmaster" .C ); .PP .C int yp_match( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_next( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_order( .C " char *indomain," .C " char *inmap," .C " unsigned long *outorder" .C ); .PP .C "void yp_unbind(char *indomain);" .PP .C "char *yperr_string(int incode);" .PP .C "int ypprot_err(unsigned int incode);" .fi .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These functions provide an interface to the Network Information Service (NIS) network-lookup service. Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of the NIS, including the definitions of .I map and NIS .IR domain , and a description of the various servers, databases, and commands comprising the NIS. .PP Input parameter names begin with .CR in ; output parameter names begin with .CR out . Output parameters of type .CR char ** should be the addresses of uninitialized character pointers. Memory is allocated by the NIS client package using .CR malloc() and can be freed if the user code has no continuing need for it (see .IR malloc (3C)). For each .I outkey and .IR outval , two extra bytes of memory are allocated at the end that contain new-line and null (in that order), but these two bytes are not reflected in .I outkeylen and .IR outvallen . The .I indomain and .I inmap strings must be non-null and null-terminated. String parameters that are accompanied by a length parameter cannot be null, but can point to null strings with a length parameter of zero. Counted strings need not be null-terminated. .PP The NIS lookup calls require a map (database) name and a NIS domain name. The client process should know the name of the map of interest. Client processes should obtain the host's NIS domain by calling .CR yp_get_default_domain() and use the returned .I outdomain as the .I indomain parameter to subsequent NIS calls. .PP To use the NIS services, the client process must be ``bound'' to an NIS server that serves the appropriate NIS domain using .CR yp_bind() . Binding does not have to occur explicitly by user code. Rather, it occurs automatically whenever a NIS lookup function is called. .CR yp_bind() can be called directly for processes that use a backup strategy (such as a local file) when NIS services are not available. .PP Each binding allocates (uses up) one client process socket descriptor. Each bound NIS domain costs one socket descriptor. However, multiple requests to the same NIS domain use that same descriptor. .CR yp_unbind() is available at the client interface for processes that explicitly manage their socket descriptors while accessing multiple NIS domains. The call to .CR yp_unbind makes the NIS domain .B unbound and frees all per-process and per-node resources used to bind it. .PP If an RPC failure results when using a binding, that NIS domain is unbound automatically. The ypclnt layer then continues retrying until the operation succeeds, provided .CR ypbind is running (see .IR ypbind (1M)) and either: .RS .TP 3 a. the client process cannot bind a server for the proper NIS domain, or .TP b. RPC requests to the server fail. .RE .PP If an error is not RPC-related, if .CR ypbind is not running, or if a bound .CR ypserv process returns any answer (success or failure), the ypclnt layer returns control to the user code with either an error code or with a success code and any results (see .IR ypbind (1M) and .IR ypserv (1M)). .SS Operational Behavior .TP 20 .CR yp_match() Returns the value associated with a passed key. This key must be exact; no pattern matching is available. .TP .CR yp_first() Returns the first key-value pair from the named map in the named NIS domain. .TP .CR yp_next() Returns the next key-value pair in a named map. To obtain the second key-value pair, the .I inkey parameter should be the .I outkey returned from an initial call to .CR yp_first() . To obtain the .RI ( "n + 1" )th key-value pair, the .I inkey value should be the .I outkey value from the .IR n th call to .CR yp_next() . .IP The concepts of first and next are particular to the structure of the NIS map being processed. No relation in retrieval order exists to either the lexical order within any original ASCII file or to any obvious numerical sorting order on the keys, values, or key-value pairs. The only ordering guarantee is that if the .CR yp_first() function is called on a particular map and the .CR yp_next() function is called repeatedly on the same map at the same server until the call fails with an error of YPERR_NOMORE, every entry in the database is retrieved exactly once. If the same sequence of operations is performed on the same map at the same server, the entries are retrieved in the same order. .IP Under conditions of heavy server load or server failure, the NIS domain may become unbound and bind again (perhaps to a different server) while a client is running. This process can cause a break in one of the enumeration (retrieval) rules: specific entries may be seen twice by the client or not at all. This approach protects the client from error messages that would otherwise be returned in the midst of the enumeration. .IP .CR yp_all() describes a better solution to enumerating all entries in a map. .TP .CR yp_all() Provides a way to transfer an entire map from server to client in a single request using TCP (rather than UDP as with other functions in this package). The entire transaction occurs as a single RPC request and response. You can use .CR yp_all() like any other NIS procedure by identifying the map in the normal manner and supplying the name of a function called to process each key-value pair within the map. A return from the call to .CR yp_all() occurs only when the transaction is completed (either successfully or unsuccessfully) or the .I foreach function decides it does not want any more key-value pairs. .IP The third parameter to .CR yp_all() is: .RS .nf .IP .CR "struct ypall_callback *incallback {" .CR " int (*foreach)();" .CR " char *data;" .CR }; .fi .RE .IP The function .CR foreach() is called as follows: .RS .nf .IP .CR foreach( .CR " int instatus;" .CR " char *inkey;" .CR " int inkeylen;" .CR " char *inval;" .CR " int invallen;" .CR " char *indata;" .CR ); .fi .RE .IP Where: .RS .TP 15 .I instatus Holds one of the return status values defined in .RC < rpcsvc/yp_prot.h >: either .CR YP_TRUE or an error code (see .CR ypprot_err() below, for a function that converts a NIS protocol error code to a ypclnt layer error code, as defined in .RC < rpcsvc/ypclnt.h >). .TP .I inkey .PD 0 .TP .I inval .sp -2v The key and value parameters are somewhat different than defined in the SYNOPSIS section above. First, the memory pointed to by .I inkey and .I inval is private to .CR yp_all() , and is overwritten with the arrival of each new key-value pair. Therefore, .CR foreach() should do something useful with the contents of that memory, but it does not own the memory. Key and value objects presented to the .CR foreach() look exactly as they do in the server's map. Therefore, if they were not newline-terminated or null-terminated in the map, they will not be terminated with newline or null characters here, either. .PD .TP .I indata Is the contents of the .I incallback\|\(mi>\|data element passed to .CR yp_all() The .I data element of the callback structure can share state information between .CR foreach() and the mainline code. Its use is optional, and no part of the NIS client package inspects its contents. Cast it to something useful or ignore it as appropriate. .RE .IP The .CR foreach() function is Boolean. It should return zero to indicate it needs to be called again for further received key-value pairs, or non-zero to stop the flow of key-value pairs. If .CR foreach() returns a non-zero value, it is not called again and the functional value of .CR yp_all() is then 0. .TP .CR yp_order() Returns the order number for a map. .TP .CR yp_master() Returns the host name of the master NIS server for a map. .TP .CR yperr_string() Returns a pointer to an error message string that is null-terminated, but contains no period or newline. .TP .CR ypprot_err() Takes an NIS protocol error code as input and returns a ypclnt layer error code that can be used as input to .CR yperr_string() .SH RETURN VALUE All functions in this package of type .CR int return 0 if the requested operation is successful or one of the following errors if the operation fails. .RS .TP 22 [YPERR_ACCESS] database access violation .TP [YPERR_BADARGS] args to function are bad .TP [YPERR_BADDB] NIS map is defective .TP [YPERR_BUSY] database busy .TP [YPERR_DOMAIN] cannot bind to server on this NIS domain .TP [YPERR_KEY] no such key in map .TP [YPERR_MAP] no such map in server's NIS domain .TP [YPERR_NODOM] local NIS domain name not set .TP [YPERR_NOMORE] no more records in map .TP [YPERR_PMAP] cannot communicate with portmap .TP [YPERR_RESRC] resource allocation failure .TP [YPERR_RPC] RPC failure \(mi NIS domain has been unbound .TP [YPERR_VERS] NIS client/server version mismatch: the NIS server bound to uses Version 1 protocol, so it does not provide .CR yp_all() functionality .TP [YPERR_YPBIND] cannot communicate with ypbind .TP [YPERR_YPERR] internal NIS server or client error .TP [YPERR_YPSERV] cannot communicate with ypserv .SH AUTHOR .CR ypclnt() was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4). .\" index@Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@client interface, Network Information Service@@@\f3ypclnt(3C)\f1 .\" index@interface, Network Information Service client@@@\f3ypclnt(3C)\f1 .\" index@\f4ypclnt()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_all()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_bind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_first()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_master()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_match()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_next()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_order()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_unbind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yperr_string()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4ypprot_err()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" toc@\f3ypclnt(3C)\f1:\0\0\f4ypclnt()\f1, \f4yp_all()\f1, \f4yp_bind()\f1, \f4yp_first()\f1, \f4yp_get_default_domain()\f1,\n\f4yp_master()\f1, \f4yp_match()\f1, \f4yp_next()\f1, \f4yp_order()\f1, \f4yp_unbind()\f1,\n\f4yperr_string()\f1, \f4ypprot_err()\f1@@@Network Information Service client interface .\" toc@\f4yp_all()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_bind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_first()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_master()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_match()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_next()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_order()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_unbind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yperr_string()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4ypprot_err()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" .\" links@ypclnt.3c yp_all.3c .\" links@ypclnt.3c yp_bind.3c .\" links@ypclnt.3c yp_first.3c .\" links@ypclnt.3c yp_get_defa.3c .\" links@ypclnt.3c yp_master.3c .\" links@ypclnt.3c yp_match.3c .\" links@ypclnt.3c yp_next.3c .\" links@ypclnt.3c yp_order.3c .\" links@ypclnt.3c yp_unbind.3c .\" links@ypclnt.3c yperr_strin.3c .\" links@ypclnt.3c ypprot_err.3c .\" $Header: ypclnt.3c,v 72.6 94/10/31 13:44:14 ssa Exp $ .TA y .TH ypclnt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypclnt(\|), yp_all(\|), yp_bind(\|), yp_first(\|), yp_get_default_domain(\|), yp_master(\|), yp_match(\|), yp_next(\|), yp_order(\|), yp_unbind(\|), yperr_string(\|), ypprot_err(\|) \- Network Information Service client interface .SH SYNOPSIS .nf .C #include .PP .C #include .C #include .C #include .PP .C int yp_all( .C " char *indomain," .C " char *inmap," .C " struct ypall_callback incallback" .C ); .PP .C int yp_bind(char *indomain); .PP .C int yp_first( .C " char *indomain," .C " char *inmap," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C "int yp_get_default_domain(char **outdomain);" .PP .C int yp_master( .C " char *indomain," .C " char *inmap," .C " char **outmaster" .C ); .PP .C int yp_match( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_next( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_order( .C " char *indomain," .C " char *inmap," .C " unsigned long *outorder" .C ); .PP .C "void yp_unbind(char *indomain);" .PP .C "char *yperr_string(int incode);" .PP .C "int ypprot_err(unsigned int incode);" .fi .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These functions provide an interface to the Network Information Service (NIS) network-lookup service. Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of the NIS, including the definitions of .I map and NIS .IR domain , and a description of the various servers, databases, and commands comprising the NIS. .PP Input parameter names begin with .CR in ; output parameter names begin with .CR out . Output parameters of type .CR char ** should be the addresses of uninitialized character pointers. Memory is allocated by the NIS client package using .CR malloc() and can be freed if the user code has no continuing need for it (see .IR malloc (3C)). For each .I outkey and .IR outval , two extra bytes of memory are allocated at the end that contain new-line and null (in that order), but these two bytes are not reflected in .I outkeylen and .IR outvallen . The .I indomain and .I inmap strings must be non-null and null-terminated. String parameters that are accompanied by a length parameter cannot be null, but can point to null strings with a length parameter of zero. Counted strings need not be null-terminated. .PP The NIS lookup calls require a map (database) name and a NIS domain name. The client process should know the name of the map of interest. Client processes should obtain the host's NIS domain by calling .CR yp_get_default_domain() and use the returned .I outdomain as the .I indomain parameter to subsequent NIS calls. .PP To use the NIS services, the client process must be ``bound'' to an NIS server that serves the appropriate NIS domain using .CR yp_bind() . Binding does not have to occur explicitly by user code. Rather, it occurs automatically whenever a NIS lookup function is called. .CR yp_bind() can be called directly for processes that use a backup strategy (such as a local file) when NIS services are not available. .PP Each binding allocates (uses up) one client process socket descriptor. Each bound NIS domain costs one socket descriptor. However, multiple requests to the same NIS domain use that same descriptor. .CR yp_unbind() is available at the client interface for processes that explicitly manage their socket descriptors while accessing multiple NIS domains. The call to .CR yp_unbind makes the NIS domain .B unbound and frees all per-process and per-node resources used to bind it. .PP If an RPC failure results when using a binding, that NIS domain is unbound automatically. The ypclnt layer then continues retrying until the operation succeeds, provided .CR ypbind is running (see .IR ypbind (1M)) and either: .RS .TP 3 a. the client process cannot bind a server for the proper NIS domain, or .TP b. RPC requests to the server fail. .RE .PP If an error is not RPC-related, if .CR ypbind is not running, or if a bound .CR ypserv process returns any answer (success or failure), the ypclnt layer returns control to the user code with either an error code or with a success code and any results (see .IR ypbind (1M) and .IR ypserv (1M)). .SS Operational Behavior .TP 20 .CR yp_match() Returns the value associated with a passed key. This key must be exact; no pattern matching is available. .TP .CR yp_first() Returns the first key-value pair from the named map in the named NIS domain. .TP .CR yp_next() Returns the next key-value pair in a named map. To obtain the second key-value pair, the .I inkey parameter should be the .I outkey returned from an initial call to .CR yp_first() . To obtain the .RI ( "n + 1" )th key-value pair, the .I inkey value should be the .I outkey value from the .IR n th call to .CR yp_next() . .IP The concepts of first and next are particular to the structure of the NIS map being processed. No relation in retrieval order exists to either the lexical order within any original ASCII file or to any obvious numerical sorting order on the keys, values, or key-value pairs. The only ordering guarantee is that if the .CR yp_first() function is called on a particular map and the .CR yp_next() function is called repeatedly on the same map at the same server until the call fails with an error of YPERR_NOMORE, every entry in the database is retrieved exactly once. If the same sequence of operations is performed on the same map at the same server, the entries are retrieved in the same order. .IP Under conditions of heavy server load or server failure, the NIS domain may become unbound and bind again (perhaps to a different server) while a client is running. This process can cause a break in one of the enumeration (retrieval) rules: specific entries may be seen twice by the client or not at all. This approach protects the client from error messages that would otherwise be returned in the midst of the enumeration. .IP .CR yp_all() describes a better solution to enumerating all entries in a map. .TP .CR yp_all() Provides a way to transfer an entire map from server to client in a single request using TCP (rather than UDP as with other functions in this package). The entire transaction occurs as a single RPC request and response. You can use .CR yp_all() like any other NIS procedure by identifying the map in the normal manner and supplying the name of a function called to process each key-value pair within the map. A return from the call to .CR yp_all() occurs only when the transaction is completed (either successfully or unsuccessfully) or the .I foreach function decides it does not want any more key-value pairs. .IP The third parameter to .CR yp_all() is: .RS .nf .IP .CR "struct ypall_callback *incallback {" .CR " int (*foreach)();" .CR " char *data;" .CR }; .fi .RE .IP The function .CR foreach() is called as follows: .RS .nf .IP .CR foreach( .CR " int instatus;" .CR " char *inkey;" .CR " int inkeylen;" .CR " char *inval;" .CR " int invallen;" .CR " char *indata;" .CR ); .fi .RE .IP Where: .RS .TP 15 .I instatus Holds one of the return status values defined in .RC < rpcsvc/yp_prot.h >: either .CR YP_TRUE or an error code (see .CR ypprot_err() below, for a function that converts a NIS protocol error code to a ypclnt layer error code, as defined in .RC < rpcsvc/ypclnt.h >). .TP .I inkey .PD 0 .TP .I inval .sp -2v The key and value parameters are somewhat different than defined in the SYNOPSIS section above. First, the memory pointed to by .I inkey and .I inval is private to .CR yp_all() , and is overwritten with the arrival of each new key-value pair. Therefore, .CR foreach() should do something useful with the contents of that memory, but it does not own the memory. Key and value objects presented to the .CR foreach() look exactly as they do in the server's map. Therefore, if they were not newline-terminated or null-terminated in the map, they will not be terminated with newline or null characters here, either. .PD .TP .I indata Is the contents of the .I incallback\|\(mi>\|data element passed to .CR yp_all() The .I data element of the callback structure can share state information between .CR foreach() and the mainline code. Its use is optional, and no part of the NIS client package inspects its contents. Cast it to something useful or ignore it as appropriate. .RE .IP The .CR foreach() function is Boolean. It should return zero to indicate it needs to be called again for further received key-value pairs, or non-zero to stop the flow of key-value pairs. If .CR foreach() returns a non-zero value, it is not called again and the functional value of .CR yp_all() is then 0. .TP .CR yp_order() Returns the order number for a map. .TP .CR yp_master() Returns the host name of the master NIS server for a map. .TP .CR yperr_string() Returns a pointer to an error message string that is null-terminated, but contains no period or newline. .TP .CR ypprot_err() Takes an NIS protocol error code as input and returns a ypclnt layer error code that can be used as input to .CR yperr_string() .SH RETURN VALUE All functions in this package of type .CR int return 0 if the requested operation is successful or one of the following errors if the operation fails. .RS .TP 22 [YPERR_ACCESS] database access violation .TP [YPERR_BADARGS] args to function are bad .TP [YPERR_BADDB] NIS map is defective .TP [YPERR_BUSY] database busy .TP [YPERR_DOMAIN] cannot bind to server on this NIS domain .TP [YPERR_KEY] no such key in map .TP [YPERR_MAP] no such map in server's NIS domain .TP [YPERR_NODOM] local NIS domain name not set .TP [YPERR_NOMORE] no more records in map .TP [YPERR_PMAP] cannot communicate with portmap .TP [YPERR_RESRC] resource allocation failure .TP [YPERR_RPC] RPC failure \(mi NIS domain has been unbound .TP [YPERR_VERS] NIS client/server version mismatch: the NIS server bound to uses Version 1 protocol, so it does not provide .CR yp_all() functionality .TP [YPERR_YPBIND] cannot communicate with ypbind .TP [YPERR_YPERR] internal NIS server or client error .TP [YPERR_YPSERV] cannot communicate with ypserv .SH AUTHOR .CR ypclnt() was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4). .\" index@Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@client interface, Network Information Service@@@\f3ypclnt(3C)\f1 .\" index@interface, Network Information Service client@@@\f3ypclnt(3C)\f1 .\" index@\f4ypclnt()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_all()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_bind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_first()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_master()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_match()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_next()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_order()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_unbind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yperr_string()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4ypprot_err()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" toc@\f3ypclnt(3C)\f1:\0\0\f4ypclnt()\f1, \f4yp_all()\f1, \f4yp_bind()\f1, \f4yp_first()\f1, \f4yp_get_default_domain()\f1,\n\f4yp_master()\f1, \f4yp_match()\f1, \f4yp_next()\f1, \f4yp_order()\f1, \f4yp_unbind()\f1,\n\f4yperr_string()\f1, \f4ypprot_err()\f1@@@Network Information Service client interface .\" toc@\f4yp_all()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_bind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_first()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_master()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_match()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_next()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_order()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_unbind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yperr_string()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4ypprot_err()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" .\" links@ypclnt.3c yp_all.3c .\" links@ypclnt.3c yp_bind.3c .\" links@ypclnt.3c yp_first.3c .\" links@ypclnt.3c yp_get_defa.3c .\" links@ypclnt.3c yp_master.3c .\" links@ypclnt.3c yp_match.3c .\" links@ypclnt.3c yp_next.3c .\" links@ypclnt.3c yp_order.3c .\" links@ypclnt.3c yp_unbind.3c .\" links@ypclnt.3c yperr_strin.3c .\" links@ypclnt.3c ypprot_err.3c .\" $Header: ypclnt.3c,v 72.6 94/10/31 13:44:14 ssa Exp $ .TA y .TH ypclnt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypclnt(\|), yp_all(\|), yp_bind(\|), yp_first(\|), yp_get_default_domain(\|), yp_master(\|), yp_match(\|), yp_next(\|), yp_order(\|), yp_unbind(\|), yperr_string(\|), ypprot_err(\|) \- Network Information Service client interface .SH SYNOPSIS .nf .C #include .PP .C #include .C #include .C #include .PP .C int yp_all( .C " char *indomain," .C " char *inmap," .C " struct ypall_callback incallback" .C ); .PP .C int yp_bind(char *indomain); .PP .C int yp_first( .C " char *indomain," .C " char *inmap," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C "int yp_get_default_domain(char **outdomain);" .PP .C int yp_master( .C " char *indomain," .C " char *inmap," .C " char **outmaster" .C ); .PP .C int yp_match( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_next( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_order( .C " char *indomain," .C " char *inmap," .C " unsigned long *outorder" .C ); .PP .C "void yp_unbind(char *indomain);" .PP .C "char *yperr_string(int incode);" .PP .C "int ypprot_err(unsigned int incode);" .fi .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These functions provide an interface to the Network Information Service (NIS) network-lookup service. Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of the NIS, including the definitions of .I map and NIS .IR domain , and a description of the various servers, databases, and commands comprising the NIS. .PP Input parameter names begin with .CR in ; output parameter names begin with .CR out . Output parameters of type .CR char ** should be the addresses of uninitialized character pointers. Memory is allocated by the NIS client package using .CR malloc() and can be freed if the user code has no continuing need for it (see .IR malloc (3C)). For each .I outkey and .IR outval , two extra bytes of memory are allocated at the end that contain new-line and null (in that order), but these two bytes are not reflected in .I outkeylen and .IR outvallen . The .I indomain and .I inmap strings must be non-null and null-terminated. String parameters that are accompanied by a length parameter cannot be null, but can point to null strings with a length parameter of zero. Counted strings need not be null-terminated. .PP The NIS lookup calls require a map (database) name and a NIS domain name. The client process should know the name of the map of interest. Client processes should obtain the host's NIS domain by calling .CR yp_get_default_domain() and use the returned .I outdomain as the .I indomain parameter to subsequent NIS calls. .PP To use the NIS services, the client process must be ``bound'' to an NIS server that serves the appropriate NIS domain using .CR yp_bind() . Binding does not have to occur explicitly by user code. Rather, it occurs automatically whenever a NIS lookup function is called. .CR yp_bind() can be called directly for processes that use a backup strategy (such as a local file) when NIS services are not available. .PP Each binding allocates (uses up) one client process socket descriptor. Each bound NIS domain costs one socket descriptor. However, multiple requests to the same NIS domain use that same descriptor. .CR yp_unbind() is available at the client interface for processes that explicitly manage their socket descriptors while accessing multiple NIS domains. The call to .CR yp_unbind makes the NIS domain .B unbound and frees all per-process and per-node resources used to bind it. .PP If an RPC failure results when using a binding, that NIS domain is unbound automatically. The ypclnt layer then continues retrying until the operation succeeds, provided .CR ypbind is running (see .IR ypbind (1M)) and either: .RS .TP 3 a. the client process cannot bind a server for the proper NIS domain, or .TP b. RPC requests to the server fail. .RE .PP If an error is not RPC-related, if .CR ypbind is not running, or if a bound .CR ypserv process returns any answer (success or failure), the ypclnt layer returns control to the user code with either an error code or with a success code and any results (see .IR ypbind (1M) and .IR ypserv (1M)). .SS Operational Behavior .TP 20 .CR yp_match() Returns the value associated with a passed key. This key must be exact; no pattern matching is available. .TP .CR yp_first() Returns the first key-value pair from the named map in the named NIS domain. .TP .CR yp_next() Returns the next key-value pair in a named map. To obtain the second key-value pair, the .I inkey parameter should be the .I outkey returned from an initial call to .CR yp_first() . To obtain the .RI ( "n + 1" )th key-value pair, the .I inkey value should be the .I outkey value from the .IR n th call to .CR yp_next() . .IP The concepts of first and next are particular to the structure of the NIS map being processed. No relation in retrieval order exists to either the lexical order within any original ASCII file or to any obvious numerical sorting order on the keys, values, or key-value pairs. The only ordering guarantee is that if the .CR yp_first() function is called on a particular map and the .CR yp_next() function is called repeatedly on the same map at the same server until the call fails with an error of YPERR_NOMORE, every entry in the database is retrieved exactly once. If the same sequence of operations is performed on the same map at the same server, the entries are retrieved in the same order. .IP Under conditions of heavy server load or server failure, the NIS domain may become unbound and bind again (perhaps to a different server) while a client is running. This process can cause a break in one of the enumeration (retrieval) rules: specific entries may be seen twice by the client or not at all. This approach protects the client from error messages that would otherwise be returned in the midst of the enumeration. .IP .CR yp_all() describes a better solution to enumerating all entries in a map. .TP .CR yp_all() Provides a way to transfer an entire map from server to client in a single request using TCP (rather than UDP as with other functions in this package). The entire transaction occurs as a single RPC request and response. You can use .CR yp_all() like any other NIS procedure by identifying the map in the normal manner and supplying the name of a function called to process each key-value pair within the map. A return from the call to .CR yp_all() occurs only when the transaction is completed (either successfully or unsuccessfully) or the .I foreach function decides it does not want any more key-value pairs. .IP The third parameter to .CR yp_all() is: .RS .nf .IP .CR "struct ypall_callback *incallback {" .CR " int (*foreach)();" .CR " char *data;" .CR }; .fi .RE .IP The function .CR foreach() is called as follows: .RS .nf .IP .CR foreach( .CR " int instatus;" .CR " char *inkey;" .CR " int inkeylen;" .CR " char *inval;" .CR " int invallen;" .CR " char *indata;" .CR ); .fi .RE .IP Where: .RS .TP 15 .I instatus Holds one of the return status values defined in .RC < rpcsvc/yp_prot.h >: either .CR YP_TRUE or an error code (see .CR ypprot_err() below, for a function that converts a NIS protocol error code to a ypclnt layer error code, as defined in .RC < rpcsvc/ypclnt.h >). .TP .I inkey .PD 0 .TP .I inval .sp -2v The key and value parameters are somewhat different than defined in the SYNOPSIS section above. First, the memory pointed to by .I inkey and .I inval is private to .CR yp_all() , and is overwritten with the arrival of each new key-value pair. Therefore, .CR foreach() should do something useful with the contents of that memory, but it does not own the memory. Key and value objects presented to the .CR foreach() look exactly as they do in the server's map. Therefore, if they were not newline-terminated or null-terminated in the map, they will not be terminated with newline or null characters here, either. .PD .TP .I indata Is the contents of the .I incallback\|\(mi>\|data element passed to .CR yp_all() The .I data element of the callback structure can share state information between .CR foreach() and the mainline code. Its use is optional, and no part of the NIS client package inspects its contents. Cast it to something useful or ignore it as appropriate. .RE .IP The .CR foreach() function is Boolean. It should return zero to indicate it needs to be called again for further received key-value pairs, or non-zero to stop the flow of key-value pairs. If .CR foreach() returns a non-zero value, it is not called again and the functional value of .CR yp_all() is then 0. .TP .CR yp_order() Returns the order number for a map. .TP .CR yp_master() Returns the host name of the master NIS server for a map. .TP .CR yperr_string() Returns a pointer to an error message string that is null-terminated, but contains no period or newline. .TP .CR ypprot_err() Takes an NIS protocol error code as input and returns a ypclnt layer error code that can be used as input to .CR yperr_string() .SH RETURN VALUE All functions in this package of type .CR int return 0 if the requested operation is successful or one of the following errors if the operation fails. .RS .TP 22 [YPERR_ACCESS] database access violation .TP [YPERR_BADARGS] args to function are bad .TP [YPERR_BADDB] NIS map is defective .TP [YPERR_BUSY] database busy .TP [YPERR_DOMAIN] cannot bind to server on this NIS domain .TP [YPERR_KEY] no such key in map .TP [YPERR_MAP] no such map in server's NIS domain .TP [YPERR_NODOM] local NIS domain name not set .TP [YPERR_NOMORE] no more records in map .TP [YPERR_PMAP] cannot communicate with portmap .TP [YPERR_RESRC] resource allocation failure .TP [YPERR_RPC] RPC failure \(mi NIS domain has been unbound .TP [YPERR_VERS] NIS client/server version mismatch: the NIS server bound to uses Version 1 protocol, so it does not provide .CR yp_all() functionality .TP [YPERR_YPBIND] cannot communicate with ypbind .TP [YPERR_YPERR] internal NIS server or client error .TP [YPERR_YPSERV] cannot communicate with ypserv .SH AUTHOR .CR ypclnt() was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4). .\" index@Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@client interface, Network Information Service@@@\f3ypclnt(3C)\f1 .\" index@interface, Network Information Service client@@@\f3ypclnt(3C)\f1 .\" index@\f4ypclnt()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_all()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_bind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_first()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_master()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_match()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_next()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_order()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_unbind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yperr_string()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4ypprot_err()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" toc@\f3ypclnt(3C)\f1:\0\0\f4ypclnt()\f1, \f4yp_all()\f1, \f4yp_bind()\f1, \f4yp_first()\f1, \f4yp_get_default_domain()\f1,\n\f4yp_master()\f1, \f4yp_match()\f1, \f4yp_next()\f1, \f4yp_order()\f1, \f4yp_unbind()\f1,\n\f4yperr_string()\f1, \f4ypprot_err()\f1@@@Network Information Service client interface .\" toc@\f4yp_all()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_bind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_first()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_master()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_match()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_next()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_order()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_unbind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yperr_string()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4ypprot_err()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" .\" links@ypclnt.3c yp_all.3c .\" links@ypclnt.3c yp_bind.3c .\" links@ypclnt.3c yp_first.3c .\" links@ypclnt.3c yp_get_defa.3c .\" links@ypclnt.3c yp_master.3c .\" links@ypclnt.3c yp_match.3c .\" links@ypclnt.3c yp_next.3c .\" links@ypclnt.3c yp_order.3c .\" links@ypclnt.3c yp_unbind.3c .\" links@ypclnt.3c yperr_strin.3c .\" links@ypclnt.3c ypprot_err.3c .\" $Header: ypclnt.3c,v 72.6 94/10/31 13:44:14 ssa Exp $ .TA y .TH ypclnt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypclnt(\|), yp_all(\|), yp_bind(\|), yp_first(\|), yp_get_default_domain(\|), yp_master(\|), yp_match(\|), yp_next(\|), yp_order(\|), yp_unbind(\|), yperr_string(\|), ypprot_err(\|) \- Network Information Service client interface .SH SYNOPSIS .nf .C #include .PP .C #include .C #include .C #include .PP .C int yp_all( .C " char *indomain," .C " char *inmap," .C " struct ypall_callback incallback" .C ); .PP .C int yp_bind(char *indomain); .PP .C int yp_first( .C " char *indomain," .C " char *inmap," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C "int yp_get_default_domain(char **outdomain);" .PP .C int yp_master( .C " char *indomain," .C " char *inmap," .C " char **outmaster" .C ); .PP .C int yp_match( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_next( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_order( .C " char *indomain," .C " char *inmap," .C " unsigned long *outorder" .C ); .PP .C "void yp_unbind(char *indomain);" .PP .C "char *yperr_string(int incode);" .PP .C "int ypprot_err(unsigned int incode);" .fi .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These functions provide an interface to the Network Information Service (NIS) network-lookup service. Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of the NIS, including the definitions of .I map and NIS .IR domain , and a description of the various servers, databases, and commands comprising the NIS. .PP Input parameter names begin with .CR in ; output parameter names begin with .CR out . Output parameters of type .CR char ** should be the addresses of uninitialized character pointers. Memory is allocated by the NIS client package using .CR malloc() and can be freed if the user code has no continuing need for it (see .IR malloc (3C)). For each .I outkey and .IR outval , two extra bytes of memory are allocated at the end that contain new-line and null (in that order), but these two bytes are not reflected in .I outkeylen and .IR outvallen . The .I indomain and .I inmap strings must be non-null and null-terminated. String parameters that are accompanied by a length parameter cannot be null, but can point to null strings with a length parameter of zero. Counted strings need not be null-terminated. .PP The NIS lookup calls require a map (database) name and a NIS domain name. The client process should know the name of the map of interest. Client processes should obtain the host's NIS domain by calling .CR yp_get_default_domain() and use the returned .I outdomain as the .I indomain parameter to subsequent NIS calls. .PP To use the NIS services, the client process must be ``bound'' to an NIS server that serves the appropriate NIS domain using .CR yp_bind() . Binding does not have to occur explicitly by user code. Rather, it occurs automatically whenever a NIS lookup function is called. .CR yp_bind() can be called directly for processes that use a backup strategy (such as a local file) when NIS services are not available. .PP Each binding allocates (uses up) one client process socket descriptor. Each bound NIS domain costs one socket descriptor. However, multiple requests to the same NIS domain use that same descriptor. .CR yp_unbind() is available at the client interface for processes that explicitly manage their socket descriptors while accessing multiple NIS domains. The call to .CR yp_unbind makes the NIS domain .B unbound and frees all per-process and per-node resources used to bind it. .PP If an RPC failure results when using a binding, that NIS domain is unbound automatically. The ypclnt layer then continues retrying until the operation succeeds, provided .CR ypbind is running (see .IR ypbind (1M)) and either: .RS .TP 3 a. the client process cannot bind a server for the proper NIS domain, or .TP b. RPC requests to the server fail. .RE .PP If an error is not RPC-related, if .CR ypbind is not running, or if a bound .CR ypserv process returns any answer (success or failure), the ypclnt layer returns control to the user code with either an error code or with a success code and any results (see .IR ypbind (1M) and .IR ypserv (1M)). .SS Operational Behavior .TP 20 .CR yp_match() Returns the value associated with a passed key. This key must be exact; no pattern matching is available. .TP .CR yp_first() Returns the first key-value pair from the named map in the named NIS domain. .TP .CR yp_next() Returns the next key-value pair in a named map. To obtain the second key-value pair, the .I inkey parameter should be the .I outkey returned from an initial call to .CR yp_first() . To obtain the .RI ( "n + 1" )th key-value pair, the .I inkey value should be the .I outkey value from the .IR n th call to .CR yp_next() . .IP The concepts of first and next are particular to the structure of the NIS map being processed. No relation in retrieval order exists to either the lexical order within any original ASCII file or to any obvious numerical sorting order on the keys, values, or key-value pairs. The only ordering guarantee is that if the .CR yp_first() function is called on a particular map and the .CR yp_next() function is called repeatedly on the same map at the same server until the call fails with an error of YPERR_NOMORE, every entry in the database is retrieved exactly once. If the same sequence of operations is performed on the same map at the same server, the entries are retrieved in the same order. .IP Under conditions of heavy server load or server failure, the NIS domain may become unbound and bind again (perhaps to a different server) while a client is running. This process can cause a break in one of the enumeration (retrieval) rules: specific entries may be seen twice by the client or not at all. This approach protects the client from error messages that would otherwise be returned in the midst of the enumeration. .IP .CR yp_all() describes a better solution to enumerating all entries in a map. .TP .CR yp_all() Provides a way to transfer an entire map from server to client in a single request using TCP (rather than UDP as with other functions in this package). The entire transaction occurs as a single RPC request and response. You can use .CR yp_all() like any other NIS procedure by identifying the map in the normal manner and supplying the name of a function called to process each key-value pair within the map. A return from the call to .CR yp_all() occurs only when the transaction is completed (either successfully or unsuccessfully) or the .I foreach function decides it does not want any more key-value pairs. .IP The third parameter to .CR yp_all() is: .RS .nf .IP .CR "struct ypall_callback *incallback {" .CR " int (*foreach)();" .CR " char *data;" .CR }; .fi .RE .IP The function .CR foreach() is called as follows: .RS .nf .IP .CR foreach( .CR " int instatus;" .CR " char *inkey;" .CR " int inkeylen;" .CR " char *inval;" .CR " int invallen;" .CR " char *indata;" .CR ); .fi .RE .IP Where: .RS .TP 15 .I instatus Holds one of the return status values defined in .RC < rpcsvc/yp_prot.h >: either .CR YP_TRUE or an error code (see .CR ypprot_err() below, for a function that converts a NIS protocol error code to a ypclnt layer error code, as defined in .RC < rpcsvc/ypclnt.h >). .TP .I inkey .PD 0 .TP .I inval .sp -2v The key and value parameters are somewhat different than defined in the SYNOPSIS section above. First, the memory pointed to by .I inkey and .I inval is private to .CR yp_all() , and is overwritten with the arrival of each new key-value pair. Therefore, .CR foreach() should do something useful with the contents of that memory, but it does not own the memory. Key and value objects presented to the .CR foreach() look exactly as they do in the server's map. Therefore, if they were not newline-terminated or null-terminated in the map, they will not be terminated with newline or null characters here, either. .PD .TP .I indata Is the contents of the .I incallback\|\(mi>\|data element passed to .CR yp_all() The .I data element of the callback structure can share state information between .CR foreach() and the mainline code. Its use is optional, and no part of the NIS client package inspects its contents. Cast it to something useful or ignore it as appropriate. .RE .IP The .CR foreach() function is Boolean. It should return zero to indicate it needs to be called again for further received key-value pairs, or non-zero to stop the flow of key-value pairs. If .CR foreach() returns a non-zero value, it is not called again and the functional value of .CR yp_all() is then 0. .TP .CR yp_order() Returns the order number for a map. .TP .CR yp_master() Returns the host name of the master NIS server for a map. .TP .CR yperr_string() Returns a pointer to an error message string that is null-terminated, but contains no period or newline. .TP .CR ypprot_err() Takes an NIS protocol error code as input and returns a ypclnt layer error code that can be used as input to .CR yperr_string() .SH RETURN VALUE All functions in this package of type .CR int return 0 if the requested operation is successful or one of the following errors if the operation fails. .RS .TP 22 [YPERR_ACCESS] database access violation .TP [YPERR_BADARGS] args to function are bad .TP [YPERR_BADDB] NIS map is defective .TP [YPERR_BUSY] database busy .TP [YPERR_DOMAIN] cannot bind to server on this NIS domain .TP [YPERR_KEY] no such key in map .TP [YPERR_MAP] no such map in server's NIS domain .TP [YPERR_NODOM] local NIS domain name not set .TP [YPERR_NOMORE] no more records in map .TP [YPERR_PMAP] cannot communicate with portmap .TP [YPERR_RESRC] resource allocation failure .TP [YPERR_RPC] RPC failure \(mi NIS domain has been unbound .TP [YPERR_VERS] NIS client/server version mismatch: the NIS server bound to uses Version 1 protocol, so it does not provide .CR yp_all() functionality .TP [YPERR_YPBIND] cannot communicate with ypbind .TP [YPERR_YPERR] internal NIS server or client error .TP [YPERR_YPSERV] cannot communicate with ypserv .SH AUTHOR .CR ypclnt() was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4). .\" index@Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@client interface, Network Information Service@@@\f3ypclnt(3C)\f1 .\" index@interface, Network Information Service client@@@\f3ypclnt(3C)\f1 .\" index@\f4ypclnt()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_all()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_bind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_first()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_master()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_match()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_next()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_order()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_unbind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yperr_string()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4ypprot_err()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" toc@\f3ypclnt(3C)\f1:\0\0\f4ypclnt()\f1, \f4yp_all()\f1, \f4yp_bind()\f1, \f4yp_first()\f1, \f4yp_get_default_domain()\f1,\n\f4yp_master()\f1, \f4yp_match()\f1, \f4yp_next()\f1, \f4yp_order()\f1, \f4yp_unbind()\f1,\n\f4yperr_string()\f1, \f4ypprot_err()\f1@@@Network Information Service client interface .\" toc@\f4yp_all()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_bind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_first()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_master()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_match()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_next()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_order()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_unbind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yperr_string()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4ypprot_err()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" .\" links@ypclnt.3c yp_all.3c .\" links@ypclnt.3c yp_bind.3c .\" links@ypclnt.3c yp_first.3c .\" links@ypclnt.3c yp_get_defa.3c .\" links@ypclnt.3c yp_master.3c .\" links@ypclnt.3c yp_match.3c .\" links@ypclnt.3c yp_next.3c .\" links@ypclnt.3c yp_order.3c .\" links@ypclnt.3c yp_unbind.3c .\" links@ypclnt.3c yperr_strin.3c .\" links@ypclnt.3c ypprot_err.3c .\" $Header: ypclnt.3c,v 72.6 94/10/31 13:44:14 ssa Exp $ .TA y .TH ypclnt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypclnt(\|), yp_all(\|), yp_bind(\|), yp_first(\|), yp_get_default_domain(\|), yp_master(\|), yp_match(\|), yp_next(\|), yp_order(\|), yp_unbind(\|), yperr_string(\|), ypprot_err(\|) \- Network Information Service client interface .SH SYNOPSIS .nf .C #include .PP .C #include .C #include .C #include .PP .C int yp_all( .C " char *indomain," .C " char *inmap," .C " struct ypall_callback incallback" .C ); .PP .C int yp_bind(char *indomain); .PP .C int yp_first( .C " char *indomain," .C " char *inmap," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C "int yp_get_default_domain(char **outdomain);" .PP .C int yp_master( .C " char *indomain," .C " char *inmap," .C " char **outmaster" .C ); .PP .C int yp_match( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_next( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_order( .C " char *indomain," .C " char *inmap," .C " unsigned long *outorder" .C ); .PP .C "void yp_unbind(char *indomain);" .PP .C "char *yperr_string(int incode);" .PP .C "int ypprot_err(unsigned int incode);" .fi .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These functions provide an interface to the Network Information Service (NIS) network-lookup service. Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of the NIS, including the definitions of .I map and NIS .IR domain , and a description of the various servers, databases, and commands comprising the NIS. .PP Input parameter names begin with .CR in ; output parameter names begin with .CR out . Output parameters of type .CR char ** should be the addresses of uninitialized character pointers. Memory is allocated by the NIS client package using .CR malloc() and can be freed if the user code has no continuing need for it (see .IR malloc (3C)). For each .I outkey and .IR outval , two extra bytes of memory are allocated at the end that contain new-line and null (in that order), but these two bytes are not reflected in .I outkeylen and .IR outvallen . The .I indomain and .I inmap strings must be non-null and null-terminated. String parameters that are accompanied by a length parameter cannot be null, but can point to null strings with a length parameter of zero. Counted strings need not be null-terminated. .PP The NIS lookup calls require a map (database) name and a NIS domain name. The client process should know the name of the map of interest. Client processes should obtain the host's NIS domain by calling .CR yp_get_default_domain() and use the returned .I outdomain as the .I indomain parameter to subsequent NIS calls. .PP To use the NIS services, the client process must be ``bound'' to an NIS server that serves the appropriate NIS domain using .CR yp_bind() . Binding does not have to occur explicitly by user code. Rather, it occurs automatically whenever a NIS lookup function is called. .CR yp_bind() can be called directly for processes that use a backup strategy (such as a local file) when NIS services are not available. .PP Each binding allocates (uses up) one client process socket descriptor. Each bound NIS domain costs one socket descriptor. However, multiple requests to the same NIS domain use that same descriptor. .CR yp_unbind() is available at the client interface for processes that explicitly manage their socket descriptors while accessing multiple NIS domains. The call to .CR yp_unbind makes the NIS domain .B unbound and frees all per-process and per-node resources used to bind it. .PP If an RPC failure results when using a binding, that NIS domain is unbound automatically. The ypclnt layer then continues retrying until the operation succeeds, provided .CR ypbind is running (see .IR ypbind (1M)) and either: .RS .TP 3 a. the client process cannot bind a server for the proper NIS domain, or .TP b. RPC requests to the server fail. .RE .PP If an error is not RPC-related, if .CR ypbind is not running, or if a bound .CR ypserv process returns any answer (success or failure), the ypclnt layer returns control to the user code with either an error code or with a success code and any results (see .IR ypbind (1M) and .IR ypserv (1M)). .SS Operational Behavior .TP 20 .CR yp_match() Returns the value associated with a passed key. This key must be exact; no pattern matching is available. .TP .CR yp_first() Returns the first key-value pair from the named map in the named NIS domain. .TP .CR yp_next() Returns the next key-value pair in a named map. To obtain the second key-value pair, the .I inkey parameter should be the .I outkey returned from an initial call to .CR yp_first() . To obtain the .RI ( "n + 1" )th key-value pair, the .I inkey value should be the .I outkey value from the .IR n th call to .CR yp_next() . .IP The concepts of first and next are particular to the structure of the NIS map being processed. No relation in retrieval order exists to either the lexical order within any original ASCII file or to any obvious numerical sorting order on the keys, values, or key-value pairs. The only ordering guarantee is that if the .CR yp_first() function is called on a particular map and the .CR yp_next() function is called repeatedly on the same map at the same server until the call fails with an error of YPERR_NOMORE, every entry in the database is retrieved exactly once. If the same sequence of operations is performed on the same map at the same server, the entries are retrieved in the same order. .IP Under conditions of heavy server load or server failure, the NIS domain may become unbound and bind again (perhaps to a different server) while a client is running. This process can cause a break in one of the enumeration (retrieval) rules: specific entries may be seen twice by the client or not at all. This approach protects the client from error messages that would otherwise be returned in the midst of the enumeration. .IP .CR yp_all() describes a better solution to enumerating all entries in a map. .TP .CR yp_all() Provides a way to transfer an entire map from server to client in a single request using TCP (rather than UDP as with other functions in this package). The entire transaction occurs as a single RPC request and response. You can use .CR yp_all() like any other NIS procedure by identifying the map in the normal manner and supplying the name of a function called to process each key-value pair within the map. A return from the call to .CR yp_all() occurs only when the transaction is completed (either successfully or unsuccessfully) or the .I foreach function decides it does not want any more key-value pairs. .IP The third parameter to .CR yp_all() is: .RS .nf .IP .CR "struct ypall_callback *incallback {" .CR " int (*foreach)();" .CR " char *data;" .CR }; .fi .RE .IP The function .CR foreach() is called as follows: .RS .nf .IP .CR foreach( .CR " int instatus;" .CR " char *inkey;" .CR " int inkeylen;" .CR " char *inval;" .CR " int invallen;" .CR " char *indata;" .CR ); .fi .RE .IP Where: .RS .TP 15 .I instatus Holds one of the return status values defined in .RC < rpcsvc/yp_prot.h >: either .CR YP_TRUE or an error code (see .CR ypprot_err() below, for a function that converts a NIS protocol error code to a ypclnt layer error code, as defined in .RC < rpcsvc/ypclnt.h >). .TP .I inkey .PD 0 .TP .I inval .sp -2v The key and value parameters are somewhat different than defined in the SYNOPSIS section above. First, the memory pointed to by .I inkey and .I inval is private to .CR yp_all() , and is overwritten with the arrival of each new key-value pair. Therefore, .CR foreach() should do something useful with the contents of that memory, but it does not own the memory. Key and value objects presented to the .CR foreach() look exactly as they do in the server's map. Therefore, if they were not newline-terminated or null-terminated in the map, they will not be terminated with newline or null characters here, either. .PD .TP .I indata Is the contents of the .I incallback\|\(mi>\|data element passed to .CR yp_all() The .I data element of the callback structure can share state information between .CR foreach() and the mainline code. Its use is optional, and no part of the NIS client package inspects its contents. Cast it to something useful or ignore it as appropriate. .RE .IP The .CR foreach() function is Boolean. It should return zero to indicate it needs to be called again for further received key-value pairs, or non-zero to stop the flow of key-value pairs. If .CR foreach() returns a non-zero value, it is not called again and the functional value of .CR yp_all() is then 0. .TP .CR yp_order() Returns the order number for a map. .TP .CR yp_master() Returns the host name of the master NIS server for a map. .TP .CR yperr_string() Returns a pointer to an error message string that is null-terminated, but contains no period or newline. .TP .CR ypprot_err() Takes an NIS protocol error code as input and returns a ypclnt layer error code that can be used as input to .CR yperr_string() .SH RETURN VALUE All functions in this package of type .CR int return 0 if the requested operation is successful or one of the following errors if the operation fails. .RS .TP 22 [YPERR_ACCESS] database access violation .TP [YPERR_BADARGS] args to function are bad .TP [YPERR_BADDB] NIS map is defective .TP [YPERR_BUSY] database busy .TP [YPERR_DOMAIN] cannot bind to server on this NIS domain .TP [YPERR_KEY] no such key in map .TP [YPERR_MAP] no such map in server's NIS domain .TP [YPERR_NODOM] local NIS domain name not set .TP [YPERR_NOMORE] no more records in map .TP [YPERR_PMAP] cannot communicate with portmap .TP [YPERR_RESRC] resource allocation failure .TP [YPERR_RPC] RPC failure \(mi NIS domain has been unbound .TP [YPERR_VERS] NIS client/server version mismatch: the NIS server bound to uses Version 1 protocol, so it does not provide .CR yp_all() functionality .TP [YPERR_YPBIND] cannot communicate with ypbind .TP [YPERR_YPERR] internal NIS server or client error .TP [YPERR_YPSERV] cannot communicate with ypserv .SH AUTHOR .CR ypclnt() was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4). .\" index@Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@client interface, Network Information Service@@@\f3ypclnt(3C)\f1 .\" index@interface, Network Information Service client@@@\f3ypclnt(3C)\f1 .\" index@\f4ypclnt()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_all()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_bind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_first()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_master()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_match()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_next()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_order()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_unbind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yperr_string()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4ypprot_err()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" toc@\f3ypclnt(3C)\f1:\0\0\f4ypclnt()\f1, \f4yp_all()\f1, \f4yp_bind()\f1, \f4yp_first()\f1, \f4yp_get_default_domain()\f1,\n\f4yp_master()\f1, \f4yp_match()\f1, \f4yp_next()\f1, \f4yp_order()\f1, \f4yp_unbind()\f1,\n\f4yperr_string()\f1, \f4ypprot_err()\f1@@@Network Information Service client interface .\" toc@\f4yp_all()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_bind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_first()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_master()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_match()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_next()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_order()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_unbind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yperr_string()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4ypprot_err()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" .\" links@ypclnt.3c yp_all.3c .\" links@ypclnt.3c yp_bind.3c .\" links@ypclnt.3c yp_first.3c .\" links@ypclnt.3c yp_get_defa.3c .\" links@ypclnt.3c yp_master.3c .\" links@ypclnt.3c yp_match.3c .\" links@ypclnt.3c yp_next.3c .\" links@ypclnt.3c yp_order.3c .\" links@ypclnt.3c yp_unbind.3c .\" links@ypclnt.3c yperr_strin.3c .\" links@ypclnt.3c ypprot_err.3c .\" $Header: ypclnt.3c,v 72.6 94/10/31 13:44:14 ssa Exp $ .TA y .TH ypclnt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypclnt(\|), yp_all(\|), yp_bind(\|), yp_first(\|), yp_get_default_domain(\|), yp_master(\|), yp_match(\|), yp_next(\|), yp_order(\|), yp_unbind(\|), yperr_string(\|), ypprot_err(\|) \- Network Information Service client interface .SH SYNOPSIS .nf .C #include .PP .C #include .C #include .C #include .PP .C int yp_all( .C " char *indomain," .C " char *inmap," .C " struct ypall_callback incallback" .C ); .PP .C int yp_bind(char *indomain); .PP .C int yp_first( .C " char *indomain," .C " char *inmap," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C "int yp_get_default_domain(char **outdomain);" .PP .C int yp_master( .C " char *indomain," .C " char *inmap," .C " char **outmaster" .C ); .PP .C int yp_match( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_next( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_order( .C " char *indomain," .C " char *inmap," .C " unsigned long *outorder" .C ); .PP .C "void yp_unbind(char *indomain);" .PP .C "char *yperr_string(int incode);" .PP .C "int ypprot_err(unsigned int incode);" .fi .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These functions provide an interface to the Network Information Service (NIS) network-lookup service. Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of the NIS, including the definitions of .I map and NIS .IR domain , and a description of the various servers, databases, and commands comprising the NIS. .PP Input parameter names begin with .CR in ; output parameter names begin with .CR out . Output parameters of type .CR char ** should be the addresses of uninitialized character pointers. Memory is allocated by the NIS client package using .CR malloc() and can be freed if the user code has no continuing need for it (see .IR malloc (3C)). For each .I outkey and .IR outval , two extra bytes of memory are allocated at the end that contain new-line and null (in that order), but these two bytes are not reflected in .I outkeylen and .IR outvallen . The .I indomain and .I inmap strings must be non-null and null-terminated. String parameters that are accompanied by a length parameter cannot be null, but can point to null strings with a length parameter of zero. Counted strings need not be null-terminated. .PP The NIS lookup calls require a map (database) name and a NIS domain name. The client process should know the name of the map of interest. Client processes should obtain the host's NIS domain by calling .CR yp_get_default_domain() and use the returned .I outdomain as the .I indomain parameter to subsequent NIS calls. .PP To use the NIS services, the client process must be ``bound'' to an NIS server that serves the appropriate NIS domain using .CR yp_bind() . Binding does not have to occur explicitly by user code. Rather, it occurs automatically whenever a NIS lookup function is called. .CR yp_bind() can be called directly for processes that use a backup strategy (such as a local file) when NIS services are not available. .PP Each binding allocates (uses up) one client process socket descriptor. Each bound NIS domain costs one socket descriptor. However, multiple requests to the same NIS domain use that same descriptor. .CR yp_unbind() is available at the client interface for processes that explicitly manage their socket descriptors while accessing multiple NIS domains. The call to .CR yp_unbind makes the NIS domain .B unbound and frees all per-process and per-node resources used to bind it. .PP If an RPC failure results when using a binding, that NIS domain is unbound automatically. The ypclnt layer then continues retrying until the operation succeeds, provided .CR ypbind is running (see .IR ypbind (1M)) and either: .RS .TP 3 a. the client process cannot bind a server for the proper NIS domain, or .TP b. RPC requests to the server fail. .RE .PP If an error is not RPC-related, if .CR ypbind is not running, or if a bound .CR ypserv process returns any answer (success or failure), the ypclnt layer returns control to the user code with either an error code or with a success code and any results (see .IR ypbind (1M) and .IR ypserv (1M)). .SS Operational Behavior .TP 20 .CR yp_match() Returns the value associated with a passed key. This key must be exact; no pattern matching is available. .TP .CR yp_first() Returns the first key-value pair from the named map in the named NIS domain. .TP .CR yp_next() Returns the next key-value pair in a named map. To obtain the second key-value pair, the .I inkey parameter should be the .I outkey returned from an initial call to .CR yp_first() . To obtain the .RI ( "n + 1" )th key-value pair, the .I inkey value should be the .I outkey value from the .IR n th call to .CR yp_next() . .IP The concepts of first and next are particular to the structure of the NIS map being processed. No relation in retrieval order exists to either the lexical order within any original ASCII file or to any obvious numerical sorting order on the keys, values, or key-value pairs. The only ordering guarantee is that if the .CR yp_first() function is called on a particular map and the .CR yp_next() function is called repeatedly on the same map at the same server until the call fails with an error of YPERR_NOMORE, every entry in the database is retrieved exactly once. If the same sequence of operations is performed on the same map at the same server, the entries are retrieved in the same order. .IP Under conditions of heavy server load or server failure, the NIS domain may become unbound and bind again (perhaps to a different server) while a client is running. This process can cause a break in one of the enumeration (retrieval) rules: specific entries may be seen twice by the client or not at all. This approach protects the client from error messages that would otherwise be returned in the midst of the enumeration. .IP .CR yp_all() describes a better solution to enumerating all entries in a map. .TP .CR yp_all() Provides a way to transfer an entire map from server to client in a single request using TCP (rather than UDP as with other functions in this package). The entire transaction occurs as a single RPC request and response. You can use .CR yp_all() like any other NIS procedure by identifying the map in the normal manner and supplying the name of a function called to process each key-value pair within the map. A return from the call to .CR yp_all() occurs only when the transaction is completed (either successfully or unsuccessfully) or the .I foreach function decides it does not want any more key-value pairs. .IP The third parameter to .CR yp_all() is: .RS .nf .IP .CR "struct ypall_callback *incallback {" .CR " int (*foreach)();" .CR " char *data;" .CR }; .fi .RE .IP The function .CR foreach() is called as follows: .RS .nf .IP .CR foreach( .CR " int instatus;" .CR " char *inkey;" .CR " int inkeylen;" .CR " char *inval;" .CR " int invallen;" .CR " char *indata;" .CR ); .fi .RE .IP Where: .RS .TP 15 .I instatus Holds one of the return status values defined in .RC < rpcsvc/yp_prot.h >: either .CR YP_TRUE or an error code (see .CR ypprot_err() below, for a function that converts a NIS protocol error code to a ypclnt layer error code, as defined in .RC < rpcsvc/ypclnt.h >). .TP .I inkey .PD 0 .TP .I inval .sp -2v The key and value parameters are somewhat different than defined in the SYNOPSIS section above. First, the memory pointed to by .I inkey and .I inval is private to .CR yp_all() , and is overwritten with the arrival of each new key-value pair. Therefore, .CR foreach() should do something useful with the contents of that memory, but it does not own the memory. Key and value objects presented to the .CR foreach() look exactly as they do in the server's map. Therefore, if they were not newline-terminated or null-terminated in the map, they will not be terminated with newline or null characters here, either. .PD .TP .I indata Is the contents of the .I incallback\|\(mi>\|data element passed to .CR yp_all() The .I data element of the callback structure can share state information between .CR foreach() and the mainline code. Its use is optional, and no part of the NIS client package inspects its contents. Cast it to something useful or ignore it as appropriate. .RE .IP The .CR foreach() function is Boolean. It should return zero to indicate it needs to be called again for further received key-value pairs, or non-zero to stop the flow of key-value pairs. If .CR foreach() returns a non-zero value, it is not called again and the functional value of .CR yp_all() is then 0. .TP .CR yp_order() Returns the order number for a map. .TP .CR yp_master() Returns the host name of the master NIS server for a map. .TP .CR yperr_string() Returns a pointer to an error message string that is null-terminated, but contains no period or newline. .TP .CR ypprot_err() Takes an NIS protocol error code as input and returns a ypclnt layer error code that can be used as input to .CR yperr_string() .SH RETURN VALUE All functions in this package of type .CR int return 0 if the requested operation is successful or one of the following errors if the operation fails. .RS .TP 22 [YPERR_ACCESS] database access violation .TP [YPERR_BADARGS] args to function are bad .TP [YPERR_BADDB] NIS map is defective .TP [YPERR_BUSY] database busy .TP [YPERR_DOMAIN] cannot bind to server on this NIS domain .TP [YPERR_KEY] no such key in map .TP [YPERR_MAP] no such map in server's NIS domain .TP [YPERR_NODOM] local NIS domain name not set .TP [YPERR_NOMORE] no more records in map .TP [YPERR_PMAP] cannot communicate with portmap .TP [YPERR_RESRC] resource allocation failure .TP [YPERR_RPC] RPC failure \(mi NIS domain has been unbound .TP [YPERR_VERS] NIS client/server version mismatch: the NIS server bound to uses Version 1 protocol, so it does not provide .CR yp_all() functionality .TP [YPERR_YPBIND] cannot communicate with ypbind .TP [YPERR_YPERR] internal NIS server or client error .TP [YPERR_YPSERV] cannot communicate with ypserv .SH AUTHOR .CR ypclnt() was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4). .\" index@Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@client interface, Network Information Service@@@\f3ypclnt(3C)\f1 .\" index@interface, Network Information Service client@@@\f3ypclnt(3C)\f1 .\" index@\f4ypclnt()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_all()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_bind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_first()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_master()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_match()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_next()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_order()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_unbind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yperr_string()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4ypprot_err()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" toc@\f3ypclnt(3C)\f1:\0\0\f4ypclnt()\f1, \f4yp_all()\f1, \f4yp_bind()\f1, \f4yp_first()\f1, \f4yp_get_default_domain()\f1,\n\f4yp_master()\f1, \f4yp_match()\f1, \f4yp_next()\f1, \f4yp_order()\f1, \f4yp_unbind()\f1,\n\f4yperr_string()\f1, \f4ypprot_err()\f1@@@Network Information Service client interface .\" toc@\f4yp_all()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_bind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_first()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_master()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_match()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_next()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_order()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_unbind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yperr_string()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4ypprot_err()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" .\" links@ypclnt.3c yp_all.3c .\" links@ypclnt.3c yp_bind.3c .\" links@ypclnt.3c yp_first.3c .\" links@ypclnt.3c yp_get_defa.3c .\" links@ypclnt.3c yp_master.3c .\" links@ypclnt.3c yp_match.3c .\" links@ypclnt.3c yp_next.3c .\" links@ypclnt.3c yp_order.3c .\" links@ypclnt.3c yp_unbind.3c .\" links@ypclnt.3c yperr_strin.3c .\" links@ypclnt.3c ypprot_err.3c .\" $Header: ypclnt.3c,v 72.6 94/10/31 13:44:14 ssa Exp $ .TA y .TH ypclnt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypclnt(\|), yp_all(\|), yp_bind(\|), yp_first(\|), yp_get_default_domain(\|), yp_master(\|), yp_match(\|), yp_next(\|), yp_order(\|), yp_unbind(\|), yperr_string(\|), ypprot_err(\|) \- Network Information Service client interface .SH SYNOPSIS .nf .C #include .PP .C #include .C #include .C #include .PP .C int yp_all( .C " char *indomain," .C " char *inmap," .C " struct ypall_callback incallback" .C ); .PP .C int yp_bind(char *indomain); .PP .C int yp_first( .C " char *indomain," .C " char *inmap," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C "int yp_get_default_domain(char **outdomain);" .PP .C int yp_master( .C " char *indomain," .C " char *inmap," .C " char **outmaster" .C ); .PP .C int yp_match( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_next( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_order( .C " char *indomain," .C " char *inmap," .C " unsigned long *outorder" .C ); .PP .C "void yp_unbind(char *indomain);" .PP .C "char *yperr_string(int incode);" .PP .C "int ypprot_err(unsigned int incode);" .fi .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These functions provide an interface to the Network Information Service (NIS) network-lookup service. Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of the NIS, including the definitions of .I map and NIS .IR domain , and a description of the various servers, databases, and commands comprising the NIS. .PP Input parameter names begin with .CR in ; output parameter names begin with .CR out . Output parameters of type .CR char ** should be the addresses of uninitialized character pointers. Memory is allocated by the NIS client package using .CR malloc() and can be freed if the user code has no continuing need for it (see .IR malloc (3C)). For each .I outkey and .IR outval , two extra bytes of memory are allocated at the end that contain new-line and null (in that order), but these two bytes are not reflected in .I outkeylen and .IR outvallen . The .I indomain and .I inmap strings must be non-null and null-terminated. String parameters that are accompanied by a length parameter cannot be null, but can point to null strings with a length parameter of zero. Counted strings need not be null-terminated. .PP The NIS lookup calls require a map (database) name and a NIS domain name. The client process should know the name of the map of interest. Client processes should obtain the host's NIS domain by calling .CR yp_get_default_domain() and use the returned .I outdomain as the .I indomain parameter to subsequent NIS calls. .PP To use the NIS services, the client process must be ``bound'' to an NIS server that serves the appropriate NIS domain using .CR yp_bind() . Binding does not have to occur explicitly by user code. Rather, it occurs automatically whenever a NIS lookup function is called. .CR yp_bind() can be called directly for processes that use a backup strategy (such as a local file) when NIS services are not available. .PP Each binding allocates (uses up) one client process socket descriptor. Each bound NIS domain costs one socket descriptor. However, multiple requests to the same NIS domain use that same descriptor. .CR yp_unbind() is available at the client interface for processes that explicitly manage their socket descriptors while accessing multiple NIS domains. The call to .CR yp_unbind makes the NIS domain .B unbound and frees all per-process and per-node resources used to bind it. .PP If an RPC failure results when using a binding, that NIS domain is unbound automatically. The ypclnt layer then continues retrying until the operation succeeds, provided .CR ypbind is running (see .IR ypbind (1M)) and either: .RS .TP 3 a. the client process cannot bind a server for the proper NIS domain, or .TP b. RPC requests to the server fail. .RE .PP If an error is not RPC-related, if .CR ypbind is not running, or if a bound .CR ypserv process returns any answer (success or failure), the ypclnt layer returns control to the user code with either an error code or with a success code and any results (see .IR ypbind (1M) and .IR ypserv (1M)). .SS Operational Behavior .TP 20 .CR yp_match() Returns the value associated with a passed key. This key must be exact; no pattern matching is available. .TP .CR yp_first() Returns the first key-value pair from the named map in the named NIS domain. .TP .CR yp_next() Returns the next key-value pair in a named map. To obtain the second key-value pair, the .I inkey parameter should be the .I outkey returned from an initial call to .CR yp_first() . To obtain the .RI ( "n + 1" )th key-value pair, the .I inkey value should be the .I outkey value from the .IR n th call to .CR yp_next() . .IP The concepts of first and next are particular to the structure of the NIS map being processed. No relation in retrieval order exists to either the lexical order within any original ASCII file or to any obvious numerical sorting order on the keys, values, or key-value pairs. The only ordering guarantee is that if the .CR yp_first() function is called on a particular map and the .CR yp_next() function is called repeatedly on the same map at the same server until the call fails with an error of YPERR_NOMORE, every entry in the database is retrieved exactly once. If the same sequence of operations is performed on the same map at the same server, the entries are retrieved in the same order. .IP Under conditions of heavy server load or server failure, the NIS domain may become unbound and bind again (perhaps to a different server) while a client is running. This process can cause a break in one of the enumeration (retrieval) rules: specific entries may be seen twice by the client or not at all. This approach protects the client from error messages that would otherwise be returned in the midst of the enumeration. .IP .CR yp_all() describes a better solution to enumerating all entries in a map. .TP .CR yp_all() Provides a way to transfer an entire map from server to client in a single request using TCP (rather than UDP as with other functions in this package). The entire transaction occurs as a single RPC request and response. You can use .CR yp_all() like any other NIS procedure by identifying the map in the normal manner and supplying the name of a function called to process each key-value pair within the map. A return from the call to .CR yp_all() occurs only when the transaction is completed (either successfully or unsuccessfully) or the .I foreach function decides it does not want any more key-value pairs. .IP The third parameter to .CR yp_all() is: .RS .nf .IP .CR "struct ypall_callback *incallback {" .CR " int (*foreach)();" .CR " char *data;" .CR }; .fi .RE .IP The function .CR foreach() is called as follows: .RS .nf .IP .CR foreach( .CR " int instatus;" .CR " char *inkey;" .CR " int inkeylen;" .CR " char *inval;" .CR " int invallen;" .CR " char *indata;" .CR ); .fi .RE .IP Where: .RS .TP 15 .I instatus Holds one of the return status values defined in .RC < rpcsvc/yp_prot.h >: either .CR YP_TRUE or an error code (see .CR ypprot_err() below, for a function that converts a NIS protocol error code to a ypclnt layer error code, as defined in .RC < rpcsvc/ypclnt.h >). .TP .I inkey .PD 0 .TP .I inval .sp -2v The key and value parameters are somewhat different than defined in the SYNOPSIS section above. First, the memory pointed to by .I inkey and .I inval is private to .CR yp_all() , and is overwritten with the arrival of each new key-value pair. Therefore, .CR foreach() should do something useful with the contents of that memory, but it does not own the memory. Key and value objects presented to the .CR foreach() look exactly as they do in the server's map. Therefore, if they were not newline-terminated or null-terminated in the map, they will not be terminated with newline or null characters here, either. .PD .TP .I indata Is the contents of the .I incallback\|\(mi>\|data element passed to .CR yp_all() The .I data element of the callback structure can share state information between .CR foreach() and the mainline code. Its use is optional, and no part of the NIS client package inspects its contents. Cast it to something useful or ignore it as appropriate. .RE .IP The .CR foreach() function is Boolean. It should return zero to indicate it needs to be called again for further received key-value pairs, or non-zero to stop the flow of key-value pairs. If .CR foreach() returns a non-zero value, it is not called again and the functional value of .CR yp_all() is then 0. .TP .CR yp_order() Returns the order number for a map. .TP .CR yp_master() Returns the host name of the master NIS server for a map. .TP .CR yperr_string() Returns a pointer to an error message string that is null-terminated, but contains no period or newline. .TP .CR ypprot_err() Takes an NIS protocol error code as input and returns a ypclnt layer error code that can be used as input to .CR yperr_string() .SH RETURN VALUE All functions in this package of type .CR int return 0 if the requested operation is successful or one of the following errors if the operation fails. .RS .TP 22 [YPERR_ACCESS] database access violation .TP [YPERR_BADARGS] args to function are bad .TP [YPERR_BADDB] NIS map is defective .TP [YPERR_BUSY] database busy .TP [YPERR_DOMAIN] cannot bind to server on this NIS domain .TP [YPERR_KEY] no such key in map .TP [YPERR_MAP] no such map in server's NIS domain .TP [YPERR_NODOM] local NIS domain name not set .TP [YPERR_NOMORE] no more records in map .TP [YPERR_PMAP] cannot communicate with portmap .TP [YPERR_RESRC] resource allocation failure .TP [YPERR_RPC] RPC failure \(mi NIS domain has been unbound .TP [YPERR_VERS] NIS client/server version mismatch: the NIS server bound to uses Version 1 protocol, so it does not provide .CR yp_all() functionality .TP [YPERR_YPBIND] cannot communicate with ypbind .TP [YPERR_YPERR] internal NIS server or client error .TP [YPERR_YPSERV] cannot communicate with ypserv .SH AUTHOR .CR ypclnt() was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4). .\" index@Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@client interface, Network Information Service@@@\f3ypclnt(3C)\f1 .\" index@interface, Network Information Service client@@@\f3ypclnt(3C)\f1 .\" index@\f4ypclnt()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_all()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_bind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_first()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_master()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_match()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_next()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_order()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_unbind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yperr_string()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4ypprot_err()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" toc@\f3ypclnt(3C)\f1:\0\0\f4ypclnt()\f1, \f4yp_all()\f1, \f4yp_bind()\f1, \f4yp_first()\f1, \f4yp_get_default_domain()\f1,\n\f4yp_master()\f1, \f4yp_match()\f1, \f4yp_next()\f1, \f4yp_order()\f1, \f4yp_unbind()\f1,\n\f4yperr_string()\f1, \f4ypprot_err()\f1@@@Network Information Service client interface .\" toc@\f4yp_all()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_bind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_first()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_master()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_match()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_next()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_order()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_unbind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yperr_string()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4ypprot_err()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" .\" links@ypclnt.3c yp_all.3c .\" links@ypclnt.3c yp_bind.3c .\" links@ypclnt.3c yp_first.3c .\" links@ypclnt.3c yp_get_defa.3c .\" links@ypclnt.3c yp_master.3c .\" links@ypclnt.3c yp_match.3c .\" links@ypclnt.3c yp_next.3c .\" links@ypclnt.3c yp_order.3c .\" links@ypclnt.3c yp_unbind.3c .\" links@ypclnt.3c yperr_strin.3c .\" links@ypclnt.3c ypprot_err.3c .\" $Header: ypclnt.3c,v 72.6 94/10/31 13:44:14 ssa Exp $ .TA y .TH ypclnt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypclnt(\|), yp_all(\|), yp_bind(\|), yp_first(\|), yp_get_default_domain(\|), yp_master(\|), yp_match(\|), yp_next(\|), yp_order(\|), yp_unbind(\|), yperr_string(\|), ypprot_err(\|) \- Network Information Service client interface .SH SYNOPSIS .nf .C #include .PP .C #include .C #include .C #include .PP .C int yp_all( .C " char *indomain," .C " char *inmap," .C " struct ypall_callback incallback" .C ); .PP .C int yp_bind(char *indomain); .PP .C int yp_first( .C " char *indomain," .C " char *inmap," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C "int yp_get_default_domain(char **outdomain);" .PP .C int yp_master( .C " char *indomain," .C " char *inmap," .C " char **outmaster" .C ); .PP .C int yp_match( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_next( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_order( .C " char *indomain," .C " char *inmap," .C " unsigned long *outorder" .C ); .PP .C "void yp_unbind(char *indomain);" .PP .C "char *yperr_string(int incode);" .PP .C "int ypprot_err(unsigned int incode);" .fi .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These functions provide an interface to the Network Information Service (NIS) network-lookup service. Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of the NIS, including the definitions of .I map and NIS .IR domain , and a description of the various servers, databases, and commands comprising the NIS. .PP Input parameter names begin with .CR in ; output parameter names begin with .CR out . Output parameters of type .CR char ** should be the addresses of uninitialized character pointers. Memory is allocated by the NIS client package using .CR malloc() and can be freed after the last time the application accesses the information returned (see .IR malloc (3C)). For each .I outkey and .IR outval , two extra bytes of memory are allocated at the end that contain new-line and null (in that order), but these two bytes are not reflected in .I outkeylen and .IR outvallen . The .I indomain and .I inmap strings must be non-null and null-terminated. String parameters that are accompanied by a length parameter cannot be null, but can point to null strings with a length parameter of zero. Counted strings need not be null-terminated. .PP The NIS lookup calls require a map (database) name and a NIS domain name. The client process should know the name of the map of interest. Client processes should obtain the host's NIS domain by calling .CR yp_get_default_domain() and use the returned .I outdomain as the .I indomain parameter to subsequent NIS calls. .PP To use the NIS services, the client process must be ``bound'' to an NIS server that serves the appropriate NIS domain using .CR yp_bind() . Binding does not have to occur explicitly by user code. Rather, it occurs automatically whenever a NIS lookup function is called. .CR yp_bind() can be called directly for processes that use a backup strategy (such as a local file) when NIS services are not available. .PP Each binding allocates (uses up) one client process socket descriptor. Each bound NIS domain costs one socket descriptor. However, multiple requests to the same NIS domain use that same descriptor. .CR yp_unbind() is available at the client interface for processes that explicitly manage their socket descriptors while accessing multiple NIS domains. The call to .CR yp_unbind makes the NIS domain .B unbound and frees all per-process and per-node resources used to bind it. .PP If an RPC failure results when using a binding, that NIS domain is unbound automatically. The ypclnt layer then continues retrying until the operation succeeds, provided .CR ypbind is running (see .IR ypbind (1M)) and either: .RS .TP 3 a. the client process cannot bind a server for the proper NIS domain, or .TP b. RPC requests to the server fail. .RE .PP If an error is not RPC-related, if .CR ypbind is not running, or if a bound .CR ypserv process returns any answer (success or failure), the ypclnt layer returns control to the user code with either an error code or with a success code and any results (see .IR ypbind (1M) and .IR ypserv (1M)). .SS Operational Behavior .TP 20 .CR yp_match() Returns the value associated with a passed key. This key must be exact; no pattern matching is available. .TP .CR yp_first() Returns the first key-value pair from the named map in the named NIS domain. .TP .CR yp_next() Returns the next key-value pair in a named map. To obtain the second key-value pair, the .I inkey parameter should be the .I outkey returned from an initial call to .CR yp_first() . To obtain the .RI ( "n + 1" )th key-value pair, the .I inkey value should be the .I outkey value from the .IR n th call to .CR yp_next() . .IP The concepts of first and next are particular to the structure of the NIS map being processed. No relation in retrieval order exists to either the lexical order within any original ASCII file or to any obvious numerical sorting order on the keys, values, or key-value pairs. The only ordering guarantee is that if the .CR yp_first() function is called on a particular map and the .CR yp_next() function is called repeatedly on the same map at the same server until the call fails with an error of YPERR_NOMORE, every entry in the database is retrieved exactly once. If the same sequence of operations is performed on the same map at the same server, the entries are retrieved in the same order. .IP Under conditions of heavy server load or server failure, the NIS domain may become unbound and bind again (perhaps to a different server) while a client is running. This process can cause a break in one of the enumeration (retrieval) rules: specific entries may be seen twice by the client or not at all. This approach protects the client from error messages that would otherwise be returned in the midst of the enumeration. .IP .CR yp_all() describes a better solution to enumerating all entries in a map. .TP .CR yp_all() Provides a way to transfer an entire map from server to client in a single request using TCP (rather than UDP as with other functions in this package). The entire transaction occurs as a single RPC request and response. You can use .CR yp_all() like any other NIS procedure by identifying the map in the normal manner and supplying the name of a function called to process each key-value pair within the map. A return from the call to .CR yp_all() occurs only when the transaction is completed (either successfully or unsuccessfully) or the .I foreach function decides it does not want any more key-value pairs. .IP The third parameter to .CR yp_all() is: .RS .nf .IP .CR "struct ypall_callback *incallback {" .CR " int (*foreach)();" .CR " char *data;" .CR }; .fi .RE .IP The function .CR foreach() is called as follows: .RS .nf .IP .CR foreach( .CR " int instatus;" .CR " char *inkey;" .CR " int inkeylen;" .CR " char *inval;" .CR " int invallen;" .CR " char *indata;" .CR ); .fi .RE .IP Where: .RS .TP 15 .I instatus Holds one of the return status values defined in .RC < rpcsvc/yp_prot.h >: either .CR YP_TRUE or an error code (see .CR ypprot_err() below, for a function that converts a NIS protocol error code to a ypclnt layer error code, as defined in .RC < rpcsvc/ypclnt.h >). .TP .I inkey .PD 0 .TP .I inval .sp -2v The key and value parameters are somewhat different than defined in the SYNOPSIS section above. First, the memory pointed to by .I inkey and .I inval is private to .CR yp_all() , and is overwritten with the arrival of each new key-value pair. Therefore, .CR foreach() should do something useful with the contents of that memory, but it does not own the memory. Key and value objects presented to the .CR foreach() look exactly as they do in the server's map. Therefore, if they were not newline-terminated or null-terminated in the map, they will not be terminated with newline or null characters here, either. .PD .TP .I indata Is the contents of the .I incallback\|\(mi>\|data element passed to .CR yp_all() The .I data element of the callback structure can share state information between .CR foreach() and the mainline code. Its use is optional, and no part of the NIS client package inspects its contents. Cast it to something useful or ignore it as appropriate. .RE .IP The .CR foreach() function is Boolean. It should return zero to indicate it needs to be called again for further received key-value pairs, or non-zero to stop the flow of key-value pairs. If .CR foreach() returns a non-zero value, it is not called again and the functional value of .CR yp_all() is then 0. .TP .CR yp_order() Returns the order number for a map. .TP .CR yp_master() Returns the host name of the master NIS server for a map. .TP .CR yperr_string() Returns a pointer to an error message string that is null-terminated, but contains no period or newline. .TP .CR ypprot_err() Takes an NIS protocol error code as input and returns a ypclnt layer error code that can be used as input to .CR yperr_string() .SH RETURN VALUE All functions in this package of type .CR int return 0 if the requested operation is successful or one of the following errors if the operation fails. .RS .TP 22 [YPERR_ACCESS] database access violation .TP [YPERR_BADARGS] args to function are bad .TP [YPERR_BADDB] NIS map is defective .TP [YPERR_BUSY] database busy .TP [YPERR_DOMAIN] cannot bind to server on this NIS domain .TP [YPERR_KEY] no such key in map .TP [YPERR_MAP] no such map in server's NIS domain .TP [YPERR_NODOM] local NIS domain name not set .TP [YPERR_NOMORE] no more records in map .TP [YPERR_PMAP] cannot communicate with portmap .TP [YPERR_RESRC] resource allocation failure .TP [YPERR_RPC] RPC failure \(mi NIS domain has been unbound .TP [YPERR_VERS] NIS client/server version mismatch: the NIS server bound to uses Version 1 protocol, so it does not provide .CR yp_all() functionality .TP [YPERR_YPBIND] cannot communicate with ypbind .TP [YPERR_YPERR] internal NIS server or client error .TP [YPERR_YPSERV] cannot communicate with ypserv .SH AUTHOR .CR ypclnt() was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4). .\" index@Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@client interface, Network Information Service@@@\f3ypclnt(3C)\f1 .\" index@interface, Network Information Service client@@@\f3ypclnt(3C)\f1 .\" index@\f4ypclnt()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_all()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_bind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_first()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_master()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_match()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_next()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_order()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_unbind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yperr_string()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4ypprot_err()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" toc@\f3ypclnt(3C)\f1:\0\0\f4ypclnt()\f1, \f4yp_all()\f1, \f4yp_bind()\f1, \f4yp_first()\f1, \f4yp_get_default_domain()\f1,\n\f4yp_master()\f1, \f4yp_match()\f1, \f4yp_next()\f1, \f4yp_order()\f1, \f4yp_unbind()\f1,\n\f4yperr_string()\f1, \f4ypprot_err()\f1@@@Network Information Service client interface .\" toc@\f4yp_all()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_bind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_first()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_master()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_match()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_next()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_order()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_unbind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yperr_string()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4ypprot_err()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" .\" links@ypclnt.3c yp_all.3c .\" links@ypclnt.3c yp_bind.3c .\" links@ypclnt.3c yp_first.3c .\" links@ypclnt.3c yp_get_defa.3c .\" links@ypclnt.3c yp_master.3c .\" links@ypclnt.3c yp_match.3c .\" links@ypclnt.3c yp_next.3c .\" links@ypclnt.3c yp_order.3c .\" links@ypclnt.3c yp_unbind.3c .\" links@ypclnt.3c yperr_strin.3c .\" links@ypclnt.3c ypprot_err.3c .\" $Header: ypclnt.3c,v 72.6 94/10/31 13:44:14 ssa Exp $ .TA y .TH ypclnt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypclnt(\|), yp_all(\|), yp_bind(\|), yp_first(\|), yp_get_default_domain(\|), yp_master(\|), yp_match(\|), yp_next(\|), yp_order(\|), yp_unbind(\|), yperr_string(\|), ypprot_err(\|) \- Network Information Service client interface .SH SYNOPSIS .nf .C #include .PP .C #include .C #include .C #include .PP .C int yp_all( .C " char *indomain," .C " char *inmap," .C " struct ypall_callback incallback" .C ); .PP .C int yp_bind(char *indomain); .PP .C int yp_first( .C " char *indomain," .C " char *inmap," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C "int yp_get_default_domain(char **outdomain);" .PP .C int yp_master( .C " char *indomain," .C " char *inmap," .C " char **outmaster" .C ); .PP .C int yp_match( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_next( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_order( .C " char *indomain," .C " char *inmap," .C " unsigned long *outorder" .C ); .PP .C "void yp_unbind(char *indomain);" .PP .C "char *yperr_string(int incode);" .PP .C "int ypprot_err(unsigned int incode);" .fi .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These functions provide an interface to the Network Information Service (NIS) network-lookup service. Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of the NIS, including the definitions of .I map and NIS .IR domain , and a description of the various servers, databases, and commands comprising the NIS. .PP Input parameter names begin with .CR in ; output parameter names begin with .CR out . Output parameters of type .CR char ** should be the addresses of uninitialized character pointers. Memory is allocated by the NIS client package using .CR malloc() and can be freed if the user code has no continuing need for it (see .IR malloc (3C)). For each .I outkey and .IR outval , two extra bytes of memory are allocated at the end that contain new-line and null (in that order), but these two bytes are not reflected in .I outkeylen and .IR outvallen . The .I indomain and .I inmap strings must be non-null and null-terminated. String parameters that are accompanied by a length parameter cannot be null, but can point to null strings with a length parameter of zero. Counted strings need not be null-terminated. .PP The NIS lookup calls require a map (database) name and a NIS domain name. The client process should know the name of the map of interest. Client processes should obtain the host's NIS domain by calling .CR yp_get_default_domain() and use the returned .I outdomain as the .I indomain parameter to subsequent NIS calls. .PP To use the NIS services, the client process must be ``bound'' to an NIS server that serves the appropriate NIS domain using .CR yp_bind() . Binding does not have to occur explicitly by user code. Rather, it occurs automatically whenever a NIS lookup function is called. .CR yp_bind() can be called directly for processes that use a backup strategy (such as a local file) when NIS services are not available. .PP Each binding allocates (uses up) one client process socket descriptor. Each bound NIS domain costs one socket descriptor. However, multiple requests to the same NIS domain use that same descriptor. .CR yp_unbind() is available at the client interface for processes that explicitly manage their socket descriptors while accessing multiple NIS domains. The call to .CR yp_unbind makes the NIS domain .B unbound and frees all per-process and per-node resources used to bind it. .PP If an RPC failure results when using a binding, that NIS domain is unbound automatically. The ypclnt layer then continues retrying until the operation succeeds, provided .CR ypbind is running (see .IR ypbind (1M)) and either: .RS .TP 3 a. the client process cannot bind a server for the proper NIS domain, or .TP b. RPC requests to the server fail. .RE .PP If an error is not RPC-related, if .CR ypbind is not running, or if a bound .CR ypserv process returns any answer (success or failure), the ypclnt layer returns control to the user code with either an error code or with a success code and any results (see .IR ypbind (1M) and .IR ypserv (1M)). .SS Operational Behavior .TP 20 .CR yp_match() Returns the value associated with a passed key. This key must be exact; no pattern matching is available. .TP .CR yp_first() Returns the first key-value pair from the named map in the named NIS domain. .TP .CR yp_next() Returns the next key-value pair in a named map. To obtain the second key-value pair, the .I inkey parameter should be the .I outkey returned from an initial call to .CR yp_first() . To obtain the .RI ( "n + 1" )th key-value pair, the .I inkey value should be the .I outkey value from the .IR n th call to .CR yp_next() . .IP The concepts of first and next are particular to the structure of the NIS map being processed. No relation in retrieval order exists to either the lexical order within any original ASCII file or to any obvious numerical sorting order on the keys, values, or key-value pairs. The only ordering guarantee is that if the .CR yp_first() function is called on a particular map and the .CR yp_next() function is called repeatedly on the same map at the same server until the call fails with an error of YPERR_NOMORE, every entry in the database is retrieved exactly once. If the same sequence of operations is performed on the same map at the same server, the entries are retrieved in the same order. .IP Under conditions of heavy server load or server failure, the NIS domain may become unbound and bind again (perhaps to a different server) while a client is running. This process can cause a break in one of the enumeration (retrieval) rules: specific entries may be seen twice by the client or not at all. This approach protects the client from error messages that would otherwise be returned in the midst of the enumeration. .IP .CR yp_all() describes a better solution to enumerating all entries in a map. .TP .CR yp_all() Provides a way to transfer an entire map from server to client in a single request using TCP (rather than UDP as with other functions in this package). The entire transaction occurs as a single RPC request and response. You can use .CR yp_all() like any other NIS procedure by identifying the map in the normal manner and supplying the name of a function called to process each key-value pair within the map. A return from the call to .CR yp_all() occurs only when the transaction is completed (either successfully or unsuccessfully) or the .I foreach function decides it does not want any more key-value pairs. .IP The third parameter to .CR yp_all() is: .RS .nf .IP .CR "struct ypall_callback *incallback {" .CR " int (*foreach)();" .CR " char *data;" .CR }; .fi .RE .IP The function .CR foreach() is called as follows: .RS .nf .IP .CR foreach( .CR " int instatus;" .CR " char *inkey;" .CR " int inkeylen;" .CR " char *inval;" .CR " int invallen;" .CR " char *indata;" .CR ); .fi .RE .IP Where: .RS .TP 15 .I instatus Holds one of the return status values defined in .RC < rpcsvc/yp_prot.h >: either .CR YP_TRUE or an error code (see .CR ypprot_err() below, for a function that converts a NIS protocol error code to a ypclnt layer error code, as defined in .RC < rpcsvc/ypclnt.h >). .TP .I inkey .PD 0 .TP .I inval .sp -2v The key and value parameters are somewhat different than defined in the SYNOPSIS section above. First, the memory pointed to by .I inkey and .I inval is private to .CR yp_all() , and is overwritten with the arrival of each new key-value pair. Therefore, .CR foreach() should do something useful with the contents of that memory, but it does not own the memory. Key and value objects presented to the .CR foreach() look exactly as they do in the server's map. Therefore, if they were not newline-terminated or null-terminated in the map, they will not be terminated with newline or null characters here, either. .PD .TP .I indata Is the contents of the .I incallback\|\(mi>\|data element passed to .CR yp_all() The .I data element of the callback structure can share state information between .CR foreach() and the mainline code. Its use is optional, and no part of the NIS client package inspects its contents. Cast it to something useful or ignore it as appropriate. .RE .IP The .CR foreach() function is Boolean. It should return zero to indicate it needs to be called again for further received key-value pairs, or non-zero to stop the flow of key-value pairs. If .CR foreach() returns a non-zero value, it is not called again and the functional value of .CR yp_all() is then 0. .TP .CR yp_order() Returns the order number for a map. .TP .CR yp_master() Returns the host name of the master NIS server for a map. .TP .CR yperr_string() Returns a pointer to an error message string that is null-terminated, but contains no period or newline. .TP .CR ypprot_err() Takes an NIS protocol error code as input and returns a ypclnt layer error code that can be used as input to .CR yperr_string() .SH RETURN VALUE All functions in this package of type .CR int return 0 if the requested operation is successful or one of the following errors if the operation fails. .RS .TP 22 [YPERR_ACCESS] database access violation .TP [YPERR_BADARGS] args to function are bad .TP [YPERR_BADDB] NIS map is defective .TP [YPERR_BUSY] database busy .TP [YPERR_DOMAIN] cannot bind to server on this NIS domain .TP [YPERR_KEY] no such key in map .TP [YPERR_MAP] no such map in server's NIS domain .TP [YPERR_NODOM] local NIS domain name not set .TP [YPERR_NOMORE] no more records in map .TP [YPERR_PMAP] cannot communicate with portmap .TP [YPERR_RESRC] resource allocation failure .TP [YPERR_RPC] RPC failure \(mi NIS domain has been unbound .TP [YPERR_VERS] NIS client/server version mismatch: the NIS server bound to uses Version 1 protocol, so it does not provide .CR yp_all() functionality .TP [YPERR_YPBIND] cannot communicate with ypbind .TP [YPERR_YPERR] internal NIS server or client error .TP [YPERR_YPSERV] cannot communicate with ypserv .SH AUTHOR .CR ypclnt() was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4). .\" index@Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@client interface, Network Information Service@@@\f3ypclnt(3C)\f1 .\" index@interface, Network Information Service client@@@\f3ypclnt(3C)\f1 .\" index@\f4ypclnt()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_all()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_bind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_first()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_master()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_match()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_next()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_order()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_unbind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yperr_string()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4ypprot_err()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" toc@\f3ypclnt(3C)\f1:\0\0\f4ypclnt()\f1, \f4yp_all()\f1, \f4yp_bind()\f1, \f4yp_first()\f1, \f4yp_get_default_domain()\f1,\n\f4yp_master()\f1, \f4yp_match()\f1, \f4yp_next()\f1, \f4yp_order()\f1, \f4yp_unbind()\f1,\n\f4yperr_string()\f1, \f4ypprot_err()\f1@@@Network Information Service client interface .\" toc@\f4yp_all()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_bind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_first()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_master()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_match()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_next()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_order()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_unbind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yperr_string()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4ypprot_err()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" .\" links@ypclnt.3c yp_all.3c .\" links@ypclnt.3c yp_bind.3c .\" links@ypclnt.3c yp_first.3c .\" links@ypclnt.3c yp_get_defa.3c .\" links@ypclnt.3c yp_master.3c .\" links@ypclnt.3c yp_match.3c .\" links@ypclnt.3c yp_next.3c .\" links@ypclnt.3c yp_order.3c .\" links@ypclnt.3c yp_unbind.3c .\" links@ypclnt.3c yperr_strin.3c .\" links@ypclnt.3c ypprot_err.3c .\" $Header: yppasswd.3n,v 72.3 93/01/14 14:58:28 ssa Exp $ .TA y .TH yppasswd 3N .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME yppasswd(\|) \- update user password in Network Information Service .SH SYNOPSIS .C #include .br .C #include .PP .C "int yppasswd(char *oldpass, struct passwd *newpw);" .SH DESCRIPTION If .I oldpass is the old, unencrypted user password, this routine replaces the password entry with the encrypted .IR newpw . .SS \s-1RPC\s0 Info .nf program number: \s-1YPPASSWDPROG\s+1 .PP xdr routines: xdr_yppasswd(xdrs, yp) \s-1XDR\s+1 *xdrs; struct yppasswd *yp; xdr_passwd(xdrs, pw) \s-1XDR\s+1 *xdrs; struct passwd *pw; procs: \s-1YPPASSWDPROC_UPDATE\s+1 Takes \f2struct yppasswd\fP as an argument; returns an integer. Behaves the same as the \f2yppasswd\|(\|)\fP function. Uses \s-1UNIX\s+1 authentication. versions: \s-1YPPASSWDVERS\s+1 .PP structures: struct yppasswd { char *oldpass; /* old (unencrypted) password */ struct passwd newpw; /* new pw structure */ }; .fi .SH RETURN VALUE .IR yppasswd () returns 0 if successful and \(mi1 if an error occurs. .SH AUTHOR .C yppasswd() was developed by Sun Microsystems, Inc. .SH SEE ALSO yppasswd(1), yppasswdd(1M). .\" .\" index@\f4yppasswd()\fP: update user password in Network Information Service@@@\f3yppasswd(3N)\f1 .\" index@update user password in Network Information Service@@@\f3yppasswd(3N)\f1 .\" index@user password in Network Information Service, update@@@\f3yppasswd(3N)\f1 .\" index@password in Network Information Service, update user@@@\f3yppasswd(3N)\f1 .\" index@Network Information Service, update user password in@@@\f3yppasswd(3N)\f1 .\" .\" toc@\f3yppasswd(3N)\f1: \f4yppasswd()\fP@@@update user password in Network Information Service .\" .\" fileset_database@yppasswd.3n PROGRAMING-MAN .\" $Header: ypclnt.3c,v 72.6 94/10/31 13:44:14 ssa Exp $ .TA y .TH ypclnt 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypclnt(\|), yp_all(\|), yp_bind(\|), yp_first(\|), yp_get_default_domain(\|), yp_master(\|), yp_match(\|), yp_next(\|), yp_order(\|), yp_unbind(\|), yperr_string(\|), ypprot_err(\|) \- Network Information Service client interface .SH SYNOPSIS .nf .C #include .PP .C #include .C #include .C #include .PP .C int yp_all( .C " char *indomain," .C " char *inmap," .C " struct ypall_callback incallback" .C ); .PP .C int yp_bind(char *indomain); .PP .C int yp_first( .C " char *indomain," .C " char *inmap," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C "int yp_get_default_domain(char **outdomain);" .PP .C int yp_master( .C " char *indomain," .C " char *inmap," .C " char **outmaster" .C ); .PP .C int yp_match( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_next( .C " char *indomain," .C " char *inmap," .C " char *inkey," .C " int inkeylen," .C " char **outkey," .C " int *outkeylen," .C " char **outval," .C " int *outvallen" .C ); .PP .C int yp_order( .C " char *indomain," .C " char *inmap," .C " unsigned long *outorder" .C ); .PP .C "void yp_unbind(char *indomain);" .PP .C "char *yperr_string(int incode);" .PP .C "int ypprot_err(unsigned int incode);" .fi .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION These functions provide an interface to the Network Information Service (NIS) network-lookup service. Refer to .IR ypfiles (4) and .IR ypserv (1M) for an overview of the NIS, including the definitions of .I map and NIS .IR domain , and a description of the various servers, databases, and commands comprising the NIS. .PP Input parameter names begin with .CR in ; output parameter names begin with .CR out . Output parameters of type .CR char ** should be the addresses of uninitialized character pointers. Memory is allocated by the NIS client package using .CR malloc() and can be freed if the user code has no continuing need for it (see .IR malloc (3C)). For each .I outkey and .IR outval , two extra bytes of memory are allocated at the end that contain new-line and null (in that order), but these two bytes are not reflected in .I outkeylen and .IR outvallen . The .I indomain and .I inmap strings must be non-null and null-terminated. String parameters that are accompanied by a length parameter cannot be null, but can point to null strings with a length parameter of zero. Counted strings need not be null-terminated. .PP The NIS lookup calls require a map (database) name and a NIS domain name. The client process should know the name of the map of interest. Client processes should obtain the host's NIS domain by calling .CR yp_get_default_domain() and use the returned .I outdomain as the .I indomain parameter to subsequent NIS calls. .PP To use the NIS services, the client process must be ``bound'' to an NIS server that serves the appropriate NIS domain using .CR yp_bind() . Binding does not have to occur explicitly by user code. Rather, it occurs automatically whenever a NIS lookup function is called. .CR yp_bind() can be called directly for processes that use a backup strategy (such as a local file) when NIS services are not available. .PP Each binding allocates (uses up) one client process socket descriptor. Each bound NIS domain costs one socket descriptor. However, multiple requests to the same NIS domain use that same descriptor. .CR yp_unbind() is available at the client interface for processes that explicitly manage their socket descriptors while accessing multiple NIS domains. The call to .CR yp_unbind makes the NIS domain .B unbound and frees all per-process and per-node resources used to bind it. .PP If an RPC failure results when using a binding, that NIS domain is unbound automatically. The ypclnt layer then continues retrying until the operation succeeds, provided .CR ypbind is running (see .IR ypbind (1M)) and either: .RS .TP 3 a. the client process cannot bind a server for the proper NIS domain, or .TP b. RPC requests to the server fail. .RE .PP If an error is not RPC-related, if .CR ypbind is not running, or if a bound .CR ypserv process returns any answer (success or failure), the ypclnt layer returns control to the user code with either an error code or with a success code and any results (see .IR ypbind (1M) and .IR ypserv (1M)). .SS Operational Behavior .TP 20 .CR yp_match() Returns the value associated with a passed key. This key must be exact; no pattern matching is available. .TP .CR yp_first() Returns the first key-value pair from the named map in the named NIS domain. .TP .CR yp_next() Returns the next key-value pair in a named map. To obtain the second key-value pair, the .I inkey parameter should be the .I outkey returned from an initial call to .CR yp_first() . To obtain the .RI ( "n + 1" )th key-value pair, the .I inkey value should be the .I outkey value from the .IR n th call to .CR yp_next() . .IP The concepts of first and next are particular to the structure of the NIS map being processed. No relation in retrieval order exists to either the lexical order within any original ASCII file or to any obvious numerical sorting order on the keys, values, or key-value pairs. The only ordering guarantee is that if the .CR yp_first() function is called on a particular map and the .CR yp_next() function is called repeatedly on the same map at the same server until the call fails with an error of YPERR_NOMORE, every entry in the database is retrieved exactly once. If the same sequence of operations is performed on the same map at the same server, the entries are retrieved in the same order. .IP Under conditions of heavy server load or server failure, the NIS domain may become unbound and bind again (perhaps to a different server) while a client is running. This process can cause a break in one of the enumeration (retrieval) rules: specific entries may be seen twice by the client or not at all. This approach protects the client from error messages that would otherwise be returned in the midst of the enumeration. .IP .CR yp_all() describes a better solution to enumerating all entries in a map. .TP .CR yp_all() Provides a way to transfer an entire map from server to client in a single request using TCP (rather than UDP as with other functions in this package). The entire transaction occurs as a single RPC request and response. You can use .CR yp_all() like any other NIS procedure by identifying the map in the normal manner and supplying the name of a function called to process each key-value pair within the map. A return from the call to .CR yp_all() occurs only when the transaction is completed (either successfully or unsuccessfully) or the .I foreach function decides it does not want any more key-value pairs. .IP The third parameter to .CR yp_all() is: .RS .nf .IP .CR "struct ypall_callback *incallback {" .CR " int (*foreach)();" .CR " char *data;" .CR }; .fi .RE .IP The function .CR foreach() is called as follows: .RS .nf .IP .CR foreach( .CR " int instatus;" .CR " char *inkey;" .CR " int inkeylen;" .CR " char *inval;" .CR " int invallen;" .CR " char *indata;" .CR ); .fi .RE .IP Where: .RS .TP 15 .I instatus Holds one of the return status values defined in .RC < rpcsvc/yp_prot.h >: either .CR YP_TRUE or an error code (see .CR ypprot_err() below, for a function that converts a NIS protocol error code to a ypclnt layer error code, as defined in .RC < rpcsvc/ypclnt.h >). .TP .I inkey .PD 0 .TP .I inval .sp -2v The key and value parameters are somewhat different than defined in the SYNOPSIS section above. First, the memory pointed to by .I inkey and .I inval is private to .CR yp_all() , and is overwritten with the arrival of each new key-value pair. Therefore, .CR foreach() should do something useful with the contents of that memory, but it does not own the memory. Key and value objects presented to the .CR foreach() look exactly as they do in the server's map. Therefore, if they were not newline-terminated or null-terminated in the map, they will not be terminated with newline or null characters here, either. .PD .TP .I indata Is the contents of the .I incallback\|\(mi>\|data element passed to .CR yp_all() The .I data element of the callback structure can share state information between .CR foreach() and the mainline code. Its use is optional, and no part of the NIS client package inspects its contents. Cast it to something useful or ignore it as appropriate. .RE .IP The .CR foreach() function is Boolean. It should return zero to indicate it needs to be called again for further received key-value pairs, or non-zero to stop the flow of key-value pairs. If .CR foreach() returns a non-zero value, it is not called again and the functional value of .CR yp_all() is then 0. .TP .CR yp_order() Returns the order number for a map. .TP .CR yp_master() Returns the host name of the master NIS server for a map. .TP .CR yperr_string() Returns a pointer to an error message string that is null-terminated, but contains no period or newline. .TP .CR ypprot_err() Takes an NIS protocol error code as input and returns a ypclnt layer error code that can be used as input to .CR yperr_string() .SH RETURN VALUE All functions in this package of type .CR int return 0 if the requested operation is successful or one of the following errors if the operation fails. .RS .TP 22 [YPERR_ACCESS] database access violation .TP [YPERR_BADARGS] args to function are bad .TP [YPERR_BADDB] NIS map is defective .TP [YPERR_BUSY] database busy .TP [YPERR_DOMAIN] cannot bind to server on this NIS domain .TP [YPERR_KEY] no such key in map .TP [YPERR_MAP] no such map in server's NIS domain .TP [YPERR_NODOM] local NIS domain name not set .TP [YPERR_NOMORE] no more records in map .TP [YPERR_PMAP] cannot communicate with portmap .TP [YPERR_RESRC] resource allocation failure .TP [YPERR_RPC] RPC failure \(mi NIS domain has been unbound .TP [YPERR_VERS] NIS client/server version mismatch: the NIS server bound to uses Version 1 protocol, so it does not provide .CR yp_all() functionality .TP [YPERR_YPBIND] cannot communicate with ypbind .TP [YPERR_YPERR] internal NIS server or client error .TP [YPERR_YPSERV] cannot communicate with ypserv .SH AUTHOR .CR ypclnt() was developed by Sun Microsystems, Inc. .SH SEE ALSO domainname(1), rpcinfo(1M), ypserv(1M), ypfiles(4). .\" index@Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@client interface, Network Information Service@@@\f3ypclnt(3C)\f1 .\" index@interface, Network Information Service client@@@\f3ypclnt(3C)\f1 .\" index@\f4ypclnt()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_all()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_bind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_first()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_master()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_match()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_next()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_order()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yp_unbind()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4yperr_string()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" index@\f4ypprot_err()\f1 \- Network Information Service client interface@@@\f3ypclnt(3C)\f1 .\" toc@\f3ypclnt(3C)\f1:\0\0\f4ypclnt()\f1, \f4yp_all()\f1, \f4yp_bind()\f1, \f4yp_first()\f1, \f4yp_get_default_domain()\f1,\n\f4yp_master()\f1, \f4yp_match()\f1, \f4yp_next()\f1, \f4yp_order()\f1, \f4yp_unbind()\f1,\n\f4yperr_string()\f1, \f4ypprot_err()\f1@@@Network Information Service client interface .\" toc@\f4yp_all()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_bind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_first()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_get_default_domain()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_master()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_match()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_next()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_order()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yp_unbind()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4yperr_string()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" toc@\f4ypprot_err()\f1 \- Network Information Service client interface@@@see \f3ypclnt(3C)\f1 .\" .\" links@ypclnt.3c yp_all.3c .\" links@ypclnt.3c yp_bind.3c .\" links@ypclnt.3c yp_first.3c .\" links@ypclnt.3c yp_get_defa.3c .\" links@ypclnt.3c yp_master.3c .\" links@ypclnt.3c yp_match.3c .\" links@ypclnt.3c yp_next.3c .\" links@ypclnt.3c yp_order.3c .\" links@ypclnt.3c yp_unbind.3c .\" links@ypclnt.3c yperr_strin.3c .\" links@ypclnt.3c ypprot_err.3c .\" $Header: ypupdate.3c,v 72.2 94/08/25 17:01:27 ssa Exp $ .TA y .TH ypupdate 3C .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ypupdate \- changes NIS information .SH SYNOPSIS .C #include .C yp_update (domain, map, ypop, key, keylen, data, datalen) .C char *domain; .C char *map; .C unsigned ypop; .C char *key; .C int keylen; .C char *data; .C int datalen; .SS Remarks The Network Information Service (NIS) was formerly known as Yellow Pages (yp). Although the name has changed, the functionality of the service remains the same. .SH DESCRIPTION The routine .C yp_update() is used to make changes to the Network Information Service (NIS) database. The syntax is the same as that of .C yp_match() (see ypclnt(3C)) except for the extra parameter ypop which may take on one of four values. .PP .RS .TP 20 .C YPOP_CHANGE The data associated with the key will be changed to the new value. If the key is not found in the database, then .C yp_update() returns .C YPERR_KEY. .TP .C YPOP_INSERT The key-value pair will be inserted into the database. The error .C YPERR_KEY is returned if the key already exists in the database. .TP .C YPOP_STORE The key-value pair will be stored into the database without concern for whether it already exists or not. .TP .C YPOP_DELETE The key-value pair will be deleted from the database. .RE .PP This routine depends upon secure RPC and will not work unless the network is running secure RPC. .SH AUTHOR The .C yp_update routine was developed by Sun Microsystems, Inc. .SH SEE ALSO ypclnt(3C). .\" .\" toc@\f3ypupdate(3C)\f1:\0\0\f4ypupdate\f1@@@changes NIS information .\" .\" index@\f4ypupdate\f1 \- changes NIS information@@@\f3ypupdate(3C)\f1 .\" .\" index@NIS information, changes@@@\f3ypupdate(3C)\f1 .\" index@information, changes NIS@@@\f3ypupdate(3C)\f1 .\" index@changes NIS information@@@\f3ypupdate(3C)\f1 ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "BosConfig" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*LBosConfig\*O file" "about" .iX "-[" "BOS Server" "about" .SH NAME .PP \*LBosConfig\*O \- Defines server processes to be monitored by the Basic OverSeer (BOS) Server .SH "DESCRIPTION" .PP The \*LBosConfig\*O file defines the server processes to be monitored by the BOS Server (\*Lbosserver\*O process) on a server machine. It contains a process entry for each process to be monitored by the BOS Server; each entry defines how its process is to run. The \*LBosConfig\*O file also maintains both the weekly and daily restart times for the BOS Server and processes that have entries in the file. .PP The BOS Server runs on each server machine, continually monitoring and, if necessary, restarting the other server processes on the machine. The BOS Server checks the \*LBosConfig\*O file whenever it starts or restarts; the information is then transferred into memory and the file is not read again until the BOS Server restarts. Thus, server processes can be started or stopped, independently of their process entries, based on their status in the BOS Server's memory. The order in which process entries appear in the \*LBosConfig\*O file is irrelevant. .PP The \*LBosConfig\*O file must reside in the directory named \*Vdcelocal\*L/var/dfs\*O on the local disk of a server machine running the BOS Server. The BOS Server creates a \*LBosConfig\*O file with only default restart times and no process entries if the file does not exist when the BOS Server starts. Because it is a local file, the information it contains can be different for different machines. .PP Each process entry in a \*LBosConfig\*O file includes the following information about the process: .VL .LI "Name" This is the name used by the BOS Server to refer to the process. Although any name can be chosen, the following names are recommended for consistency: .VL .LI "\*Lftserver\*O" For the Fileset Server process .LI "\*Lflserver\*O" For the Fileset Location Server process .LI "\*Lupclient\*O" For the client portion of the Update Server .LI "\*Lupserver\*O" For the server portion of the Update Server .LI "\*Lrepserver\*O" For the Replication Server process .LI "\*Lbakserver\*O" For the Backup Server process .LE .LI "Type" A process can be one of two types: .VL .LI "\*Lsimple\*O" A continuous process that runs independently of any other processes on a server machine. All standard DFS processes are \*Lsimple\*O processes. .LI "\*Lcron\*O" A process that runs independently of any other processes; however, unlike a \*Lsimple\*O process, a \*Lcron\*O process runs periodically, not continuously. .LE .LI "Status flag" Status flags are for internal use only; they do not appear in any output. A process can have one of two status flags: .VL .LI "\*LRun\*O" Means the process is to run whenever possible; the BOS Server starts it automatically at reboot and restarts it automatically if it fails. (The \*LRun\*O status flag appears in the file as a \*L1\*O.) .LI "\*LNotRun\*O" Means the BOS Server does not start or restart the process. (The \*LNotRun\*O status flag appears in the file as a \*L0\*O.) .LE .LI "Command parameters" .zA "defect,7219,R1.0.2,Review comments" The BOS Server uses these parameters to run the process. For a \*Lsimple\*O process, a single command parameter specifying the complete pathname of the binary file for a DFS command or any other command to be executed is used. For a \*Lcron\*O process, two command parameters are used: the complete pathname of the binary file for a DFS command or any other command to be executed, and the time the BOS Server is to execute the command. .zZ "defect,7219,R1.0.2,Review comments" .LE .PP .zA "defect,7219,R1.0.2,Review comments" Although it is an ASCII file, do not edit the \*LBosConfig\*O file directly; always use the appropriate \*Lbos\*O commands. Editing the file directly can introduce changes the BOS Server does not recognize until it is restarted and again reads the file. .zZ "defect,7219,R1.0.2,Review comments" .PP The following \*Lbos\*O commands modify process entries or restart times in the \*LBosConfig\*O file: .VL .LI "\*Lbos create\*O" Adds a process entry to the file, setting the process' status to \*LRun\*O in both the file and memory, and starts the process .LI "\*Lbos delete\*O" Removes a process entry for a stopped process from the file .LI "\*Lbos stop\*O" Stops a running process by changing its status to \*LNotRun\*O in both the file and memory .LI "\*Lbos start\*O" Starts a stopped process by changing its status to \*LRun\*O in both the file and memory .LI "\*Lbos setrestart\*O" Sets the weekly and daily restart times included in the file .LE .PP The following \*Lbos\*O commands access process entries in the \*LBosConfig\*O file: .VL .LI "\*Lbos status\*O" Lists the statuses of server processes on a machine, from which you can determine information about their process entries .LI "\*Lbos restart\*O" Stops and immediately restarts processes that have process entries in the file .LI "\*Lbos getrestart\*O" Displays both the weekly and daily restart times from the file .LE .PP Additional \*Lbos\*O commands can be used to start or stop a process by changing its status in the BOS Server's memory without affecting its process entry in the \*LBosConfig\*O file. .SH "CAUTIONS" .PP .zA "defect,7219,R1.0.2,Review comments" Do not edit the \*LBosConfig\*O file directly. Always use the appropriate \*Lbos\*O commands to manipulate process entries in the \*LBosConfig\*O file. Editing the file directly can introduce changes that the BOS Server is not aware of until it is restarted and again reads the file. .zZ "defect,7219,R1.0.2,Review comments" .SH "EXAMPLES" .PP The following \*Lbos create\*O command creates a process entry in the \*LBosConfig\*O file and starts the process. The command adds the process entry to the \*LBosConfig\*O file on the server machine named \*Lfs1.abc.com\*O. It specifies that a \*Lcron\*O process identified by \*Lbackup\*O is to use the \*Lfts clonesys\*O command daily at 5:30 a.m. to create backup versions of all read-write filesets on \*Lfs1.abc.com\*O. The \*L\-localauth\*O option is used with the \*Lfts clonesys\*O command to use the identity of the local machine as the identity of the issuer of the command. .zA "defect,7219,R1.0.2,Review comments" .iS \*C$\*O \*Lbos create /.../abc.com/hosts/fs1 backup cron "\*Vdcelocal\*L/bin/fts clonesys \\ -server /.../abc.com/hosts/fs1 -localauth" 5:30\*O .iE .zZ "defect,7219,R1.0.2,Review comments" .PP The following \*Lbos setrestart\*O command sets the general restart time when the BOS Server restarts itself and all of the processes with entries in the \*LBosConfig\*O file. It specifies that all processes, including the \*Lbosserver\*O process, on \*Lfs1.abc.com\*O are to be restarted every Sunday morning at 4:00 a.m. .zA "defect,7219,R1.0.2,Review comments" .iS \*C$\*O \*Lbos setrestart /.../abc.com/hosts/fs1 -general "sun 4:00"\*O .iE .zZ "defect,7219,R1.0.2,Review comments" .SH "RELATED INFORMATION" .PP Commands: \*Lbos create(1m)\*O, \*Lbos delete(1m)\*O, \*Lbos setrestart(1m)\*O, \*Lbos start(1m)\*O, \*Lbos stop(1m)\*O, \*Lbosserver(1m)\*O .iX "-]" "\*LBosConfig\*O file" "about" .iX "-]" "BOS Server" "about" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "BosLog" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "\*LBosLog\*O file" .iX "BOS Server" "log files" .SH NAME .PP \*LBosLog\*O \- Contains messages generated by the Basic OverSeer (BOS) Server .SH "DESCRIPTION" .PP The \*LBosLog\*O file contains execution and error messages generated by the Basic OverSeer (BOS) Server (\*Lbosserver\*O process). The BOS Server runs on every server machine in a cell, monitoring the other server processes on the machine and restarting them as necessary. .PP If the \*LBosLog\*O file does not already exist when the BOS Server starts, the server process creates the file in the directory named \*Edcelocal\*L/var/dfs/adm\*O. The process then appends any subsequent messages to the file once it exists. If the file exists when the BOS Server starts, the process moves the current version of the file to the \*LBosLog.old\*O file in the same directory (overwriting the current \*LBosLog.old\*O file if it exists) before creating a new version to which to append messages. .PP The process can write different types of output to the file, depending on the actions it performs and any problems it encounters. The file can be viewed with the \*Lbos getlog\*O command. Because it is an ASCII file, it can also be viewed with the \*Lmore\*O command (or a similar command appropriate to the local operating system), which requires \*Lread\*O permission on the file. .PP Events are recorded in the log file only at their completion, so the process does not use the file to reconstruct failed operations. However, the contents of the log file can help you evaluate server process failures and other problems. .SH "RELATED INFORMATION" .PP Commands: \*Lbos getlog(1m)\*O, \*Lbosserver(1m)\*O ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "CacheInfo" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*LCacheInfo\*O file" .iX "-[" "Cache Manager" "configuring" .SH NAME .PP \*LCacheInfo\*O \- Defines the initial configuration of the Cache Manager .SH "DESCRIPTION" .PP .zA "misc,R1.0.2,Correct bad tech. mistake from PH work" The \*LCacheInfo\*O file specifies the initial configuration of the Cache Manager on a client machine. The Cache Manager checks the file at initialization to determine certain cache configuration information. It uses the file regardless of the type of caching, disk or memory, in use on the machine. .zZ "misc,R1.0.2,Correct bad tech. mistake from PH work" .PP .zA "defect,10439,R1.1,Fix cross-references for DFS reorganization" .zA "enh,R1.0.2,Clarify small details" The \*LCacheInfo\*O file is manually created during DFS client installation. (See Part 1 of the \*(Ad for details on creating the file.) It must reside in the directory named \*Edcelocal\*L/etc\*O. .zZ "enh,R1.0.2,Clarify small details" .zZ "defect,10439,R1.1,Fix cross-references for DFS reorganization" .PP The file is a one-line ASCII file consisting of the following three fields separated by colons: .ML .LI The first field names a directory on the local disk where the Cache Manager mounts the DCE global namespace. The default entry is the global namespace designation (\*L/...\*O). If \*L/...\*O is not specified, symbolic links to the global namespace fail. .PP The value of this field can be overridden with the \*Ldfsd\*O command and the \*L-mountdir\*O option. .LI .zA "defect,5125,R1.0.2,Clarify cache dir and memory cache" .zA "defect,6062,R1.0.2,Remove cm debug command" The second field names a directory on the local disk to serve as the cache directory for a disk cache. This is the directory in which the Cache Manager stores the \*LV\*En\*O, \*LCacheItems\*O, and \*LFilesetItems\*O files that it creates. The default entry is \*Edcelocal\*L/var/adm/dfs/cache\*O. You can change this to a directory on another partition if more space is available elsewhere. Although the indicated directory is not used with a memory cache, an entry must appear in this field even if memory caching is employed on the machine. .zZ "defect,6062,R1.0.2,Remove cm debug command" .zZ "defect,5125,R1.0.2,Clarify cache dir and memory cache" .PP The value of this field can be overridden with the \*Ldfsd\*O command and the \*L-cachedir\*O option. .LI The third field specifies the cache size in 1024-byte (1-kilobyte) blocks. The amount of disk space or machine memory used for caching depends on several factors. The size of the partition housing the cache directory or the amount of memory available on the machine places an absolute limit on the cache size. However, do not use more than 90% of the cache directory's partition for a disk cache, and do not use more than 20 to 25% of available memory for a memory cache. .PP The value of this field can be overridden with the \*Ldfsd\*O command and the \*L-blocks\*O option. It can also be overridden with the \*Lcm setcachesize\*O command. The \*Lcm getcachesize\*O command can be used to view the current size of the cache and the amount in use. .LE .PP Because it is an ASCII file, the \*LCacheInfo\*O file can be directly modified with a text editor. To modify the file, log in as \*Lroot\*O on the machine. .SH "CAUTIONS" .PP The size of the partition housing the cache directory or the amount of memory available on the machine places an absolute limit on the cache size. However, do not use more than 90% of the cache directory's partition for a disk cache, and do not use more than 20 to 25% of available memory for a memory cache. .PP Be precise when editing the \*LCacheInfo\*O file; use colons to separate the fields in the file, and do not include any spaces in the file. Improper formatting of this file can cause the kernel to panic. .SH "EXAMPLES" .PP An example of a typical \*LCacheInfo\*O file follows. It lists the DCE global namespace mounted at the global namespace designation (\*L/...\*O), \*Edcelocal\*L/var/adm/dfs/cache\*O used for the cache directory, and a defined cache size of 50,000 1-kilobyte blocks. .oS \*C/...:\*Edcelocal\*C/var/adm/dfs/cache:50000\*O .oE .SH "RELATED INFORMATION" .PP .zA "defect,6062,R1.0.2,Remove cm debug command" Commands: \*Lcm getcachesize(1m)\*O, \*Lcm setcachesize(1m)\*O, \*Ldfsd(1m)\*O .PP Files: \*LCacheItems(4)\*O, \*LFilesetItems(4)\*O, \*LVn(4)\*O .zZ "defect,6062,R1.0.2,Remove cm debug command" .iX "-]" "\*LCacheInfo\*O file" .iX "-]" "Cache Manager" "configuring" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "CacheItems" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "Cache Manager" "monitoring V files" .iX "\*LCacheItems\*O file" .iX "V files" "about" .iX "cache" "disk" .iX "disk cache" "about" .SH NAME .PP \*LCacheItems\*O \- Records information about each V file in a disk cache .SH "DESCRIPTION" .PP The \*LCacheItems\*O file is a binary file created and maintained by the Cache Manager for its own use and for use by developers for debugging. It records information about each V file on a client machine using a disk cache. The information includes the file ID number and data version number of each V file. .PP The \*LCacheItems\*O file always resides in the cache directory with the cache's V files. The default directory for the files is \*Edcelocal\*L/var/adm/dfs/cache\*O. This directory is specified in the second field of the \*LCacheInfo\*O file; it can be overridden to name a different directory. .SH "CAUTIONS" .PP Never directly modify or delete the \*LCacheItems\*O file; this can cause the kernel to panic. Always use the commands provided with DFS to alter the cache. If the file is accidentally modified or deleted, rebooting the machine should restore normal performance. .SH "RELATED INFORMATION" .PP Files: \*LCacheInfo(4)\*O, \*LVn(4)\*O ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" Copyright (c) 1994 Hewlett-Packard Company ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" .rm zA .rm zZ .TH "DfsgwLog" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 .zA "defect,11180,R1.1,Incorporate DFS/NFS gateway doc" .iX "\*LDfsgwLog\*O file" .iX "DFS/NFS Gateway" "\*LDfsgwLog\*O file" .SH NAME .PP \*LDfsgwLog\*O \- Contains messages generated by the Gateway Server process of the DFS/NFS Secure Gateway .SH "DESCRIPTION" .PP The \*LDfsgwLog\*O file contains messages generated by the Gateway Server (\*Ldfsgwd\*O) process. The Gateway Server process runs on machines configured as DFS clients to allow users to authenticate to DCE from NFS clients. .PP If the \*LDfsgwLog\*O file does not already exist when the Gateway Server process starts, the process creates the file in the directory named \*Edcelocal\*L/var/dfs/adm\*O. Once the file exists, the process appends messages to it. If the file exists when the Gateway Server process starts, the process moves the current version of the file to the \*LDfsgwLog.old\*O file in the same directory (overwriting the current \*LDfsgwLog.old\*O file if it exists) before creating a new version to which to append messages. .PP The process can write different types of output to the file, depending on the actions it performs and any problems it encounters. The file can be viewed with the \*Lbos getlog\*O command. Because it is an ASCII file, it can also be viewed with the \*Lmore\*O command (or a similar command appropriate to the local operating system), which requires \*Lread\*O permission on the file. .PP Events are recorded in the log file only at their completion, so the process does not use the file to reconstruct failed operations. However, the contents of the log file can help in evaluating server process failures and other problems. .SH "RELATED INFORMATION" .PP Commands: \*Lbos getlog(1m)\*O, \*Ldfsgwd(1m)\*O .zZ "defect,11180,R1.1,Incorporate DFS/NFS gateway doc" ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "FilesetItems" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "\*LFilesetItems\*O file" .iX "Cache Manager" "mount points mapping file" .iX "mount points" "fileset mapping file" .SH NAME .PP .zA "enf,R1.0.2,Add details" \*LFilesetItems\*O \- Records location mappings for filesets accessed by a Cache Manager using a disk cache .zZ "enf,R1.0.2,Add details" .SH "DESCRIPTION" .PP .zA "enf,R1.0.2,Add details" .zA "enh,R1.0.2,Small enhancement" The \*LFilesetItems\*O file is a binary file created and maintained by the Cache Manager for its own use and for use by developers for debugging. It stores the fileset-to-mount point mapping for each fileset accessed by a Cache Manager using a disk cache. The mappings enable the Cache Manager to respond correctly to operating system and related commands such as \*Lpwd\*O. .zZ "enh,R1.0.2,Small enhancement" .zZ "enf,R1.0.2,Add details" .PP The \*LFilesetItems\*O file always resides in the cache directory. The default directory is \*Edcelocal\*L/var/adm/dfs/cache\*O. This directory is specified in the second field of the \*LCacheInfo\*O file; it can be overridden to name a different directory. .SH "CAUTIONS" .PP Never directly modify or delete the \*LFilesetItems\*O file; this can cause the kernel to panic. Always use the commands provided with DFS to alter the cache. If the file is accidentally modified or deleted, rebooting the machine should restore normal performance. .SH "RELATED INFORMATION" .PP Files: \*LCacheInfo(4)\*O ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "FlLog" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "\*LFlLog\*O file" .iX "Fileset Location Server" "log file" .SH NAME .PP \*LFlLog\*O \- Contains messages generated by the Fileset Location Server .SH "DESCRIPTION" .PP The \*LFlLog\*O file contains execution messages and error messages generated by the Fileset Location Server (\*Lflserver\*O process). The Fileset Location Server runs on every Fileset Database machine in a cell, providing the interface by which authorized users can modify the Fileset Location Database (FLDB). .PP If the \*LFlLog\*O file does not already exist when the Fileset Location Server starts, the server process creates the file in the directory named \*Edcelocal\*L/var/dfs/adm\*O. The process then appends any subsequent messages to the file once it exists. If the file exists when the Fileset Location Server starts, the process moves the current version of the file to the \*LFlLog.old\*O file in the same directory (overwriting the current \*LFlLog.old\*O file if it exists) before creating a new version to which to append messages. .PP The process can write different types of output to the file, depending on the actions it performs and any problems it encounters. The file can be viewed with the \*Lbos getlog\*O command. Because it is an ASCII file, it can also be viewed with the \*Lmore\*O command (or a similar command appropriate to the local operating system), which requires \*Lread\*O permission on the file. .PP Events are recorded in the log file only at their completion, so the process does not use the file to reconstruct failed operations. However, the contents of the log file can help in evaluating server process failures and other problems. .SH "RELATED INFORMATION" .PP Commands: \*Lbos getlog(1m)\*O, \*Lflserver(1m)\*O ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "FtLog" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "\*LFtLog\*O file" .iX "Fileset Server" "log file" .SH NAME .PP \*LFtLog\*O \- Contains messages generated by the Fileset Server .SH "DESCRIPTION" .PP The \*LFtLog\*O file contains execution messages and error messages generated by the Fileset Server (\*Lftserver\*O process). The Fileset Server runs on every File Server machine in a cell. It provides the interface for any commands that affect filesets on a File Server machine. .PP If the \*LFtLog\*O file does not already exist when the Fileset Server starts, the server process creates the file in the directory named \*Edcelocal\*L/var/dfs/adm\*O. The process then appends any subsequent messages to the file once it exists. If the file exists when the Fileset Server starts, the process moves the current version of the file to the \*LFtLog.old\*O file in the same directory (overwriting the current \*LFtLog.old\*O file if it exists) before creating a new version to which to append messages. .PP The process can write different types of output to the file, depending on the actions it performs and any problems it encounters. The file can be viewed with the \*Lbos getlog\*O command. Because it is an ASCII file, it can also be viewed with the \*Lmore\*O command (or a similar command appropriate to the local operating system), which requires \*Lread\*O permission on the file. .PP Events are recorded in the log file only at their completion, so the process does not use the file to reconstruct failed operations. However, the contents of the log file can help in evaluating server process failures and other problems. .SH "RELATED INFORMATION" .PP Commands: \*Lbos getlog(1m)\*O, \*Lftserver(1m)\*O ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "NoAuth" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "\*LNoAuth\*O file" .iX "authorization checking" "disabling" .SH NAME .PP \*LNoAuth\*O \- Indicates that DFS authorization checking is disabled .SH "DESCRIPTION" .PP .zA "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" The \*LNoAuth\*O file is a zero-length file that dictates whether DFS authorization checking is enabled or disabled on a server machine. The presence of the \*LNoAuth\*O file in the \*Edcelocal\*L/var/dfs\*O directory on a local disk indicates to all DFS server processes on that machine that DFS authorization checking is disabled. All DFS server processes, including the BOS Server, check for the presence of the file when they are requested to perform an operation; they do not check for the necessary administrative privilege for a requested operation when the file is present. .PP .zA "defect,8634,R1.0.3,Change anonymous to nobody" When the \*LNoAuth\*O file is present in \*Edcelocal\*L/var/dfs\*O on a server machine, DFS authorization checking is disabled on that machine. The server processes on the machine perform any action for any user who requests it, including the unprivileged identity \*Lnobody\*O. This is a serious security risk and should be used only in the following situations: .zZ "defect,8634,R1.0.3,Change anonymous to nobody" .ML .LI During initial DFS installation .LI If the Security Service is unavailable .LI During server encryption key emergencies .LI To view the actual keys stored in a keytab file .LE .PP When the \*LNoAuth\*O file is \*Enot\*O present in \*Edcelocal\*L/var/dfs\*O on a server machine, DFS authorization checking is enabled on that machine. All DFS server processes on the machine check that the issuer of a command has the proper authorization (is included in the necessary administrative lists) before they perform the requested operation. By default, DFS authorization checking is always enabled on every server machine. .PP .zA "defect,5791,R1.0.2,Bos status displays NoAuth message" The \*Lbos status\*O command can be used to determine whether DFS authorization checking is enabled or disabled on a server machine. The command displays the following message if DFS authorization checking is disabled on a machine (it does not display the message if DFS authorization checking is enabled): .PP \*CBosserver reports machine is not checking authorization.\*O .zZ "defect,5791,R1.0.2,Bos status displays NoAuth message" .PP The BOS Server on a server machine creates the \*LNoAuth\*O file when an authorized user (one listed in the \*Ladmin.bos\*O file on the machine) executes the \*Lbos setauth\*O command with the \*L\-authchecking\*O option set to \*Loff\*O (the file can also be created with the \*L\-noauth\*O option of the \*Lbosserver\*O command used to start the BOS Server). The BOS Server removes the file when a user executes the \*Lbos setauth\*O command with the \*L\-authchecking\*O option set to \*Lon\*O. Whenever the \*Lbos setauth\*O command is used to change the state of DFS authorization checking, all server processes immediately recognize the changed state and respond accordingly to any subsequent commands. .zZ "defect,6019,R1.0.2,Clarify -noauth option with bos and fts" .SH "CAUTIONS" .PP Always use the \*Lbos setauth\*O command to create the \*Edcelocal\*L/var/dfs/NoAuth\*O file. Do not create the file directly except when explicitly told to do so by instructions for dealing with emergencies (such as server encryption key emergencies). Creating the file directly requires logging into the local operating system of a machine as \*Lroot\*O and using the \*Ltouch\*O command (or its equivalent). .SH "RELATED INFORMATION" .PP .zA "defect,5791,R1.0.2,Bos status displays NoAuth message" Commands: \*Lbos setauth(1m)\*O, \*Lbos status(1m)\*O, \*Lbosserver(1m)\*O .zZ "defect,5791,R1.0.2,Bos status displays NoAuth message" .\" $Header: term_c.4,v 78.1 95/12/20 11:19:19 ssa Exp $ .TA t .\"#ident "@(#)unified:headers/term 1.4" .TH term_c 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME term.h \- terminal capabilities .SH DESCRIPTION The header <\f3term.h\f1> contains definitions for each of the following symbolic constants and capability names in the following tables. .PP In the following table, a \f3Variable\f1 is the name by which a \f3C\f1 programmer accesses a capability (at the \f4terminfo\f1 level). A \f3Capname\f1 is the short name for a capability specified in the \f4terminfo\f1 source file. It is used by a person updating the source file and by the \f4tput\f1 command. .SS Booleans .ift \{ .TS lfHB lfHB lfHB lfHB lfHB lfHB lfHB lfHB lw(1.15i)p7fCW lp7fCW lp7fCW lw(2i)p7. \s-2Cap-\s0 \s-2Termcap\s0 \s-2Variable\s0 \s-2name\s0 \s-2Code\s0 \s-2Description\s0 .sp0.5 .ft1 auto_left_margin bw bw \f4cub1\f1 wraps from column 0 to last column auto_right_margin am am Terminal has automatic margins back_color_erase bce ut Screen erased with background color buttons btns BT Number of buttons on the mouse can_change ccc cc Terminal can re-define existing color ceol_standout_glitch xhp xs Standout not erased by overwriting (hp) col_addr_glitch xhpa YA Only positive motion for \f4hpa\f1/\f4mhpa\f1 caps cpi_changes_res cpix YF Changing character pitch changes resolution create_window cwin CW Define win #1 to go from #2,#3 to #4,#5 cr_cancels_micro_mode crxm YB Using \f4cr\f1 turns off micro mode dest_tabs_magic_smso xt xt Destructive tabs, magic \f4smso\f1 char (t1061) dial_phone dial DI Dial phone number #1 display_clock dclk DK Display time-of-day clock eat_newline_glitch xenl xn Newline ignored after 80 columns (Concept) erase_overstrike eo eo Can erase overstrikes with a blank fixed_pause pause PA Pause for 2-3 seconds flash_hook hook fh Flash the switch hook generic_type gn gn Generic line type (\f2e.g.\f1, dialup, switch) get_mouse getm Gm Curses should get button events goto_window wingo WG Got to window #1 hangup hup HU Hang-up phone hard_copy hc hc Hardcopy terminal hard_cursor chts HC Cursor is hard to see has_meta_key km km Has a meta key (shift, sets parity bit) has_print_wheel daisy YC Printer needs operator to change character set has_status_line hs hs Has extra "status line" hue_lightness_saturation hls hl Terminal uses only HLS color notation (Tektronix) insert_null_glitch in in Insert mode distinguishes nulls lpi_changes_res lpix YG Changing line pitch changes resolution memory_above da da Display may be retained above the screen memory_below db db Display may be retained below the screen move_insert_mode mir mi Safe to move while in insert mode move_standout_mode msgr ms Safe to move in standout modes needs_xon_xoff nxon nx Padding won't work, xon/xoff required no_esc_ctlc xsb xb Beehive (f1=escape, f2=ctrl C) no_pad_char npc NP Pad character doesn't exist non_dest_scroll_region ndscr ND Scrolling region is nondestructive non_rev_rmcup nrrmc NR \f4smcup\f1 does not reverse \f4rmcup\f1 over_strike os os Terminal overstrikes on hard-copy terminal print_rate cps Ym Print rate in characters per second prtr_silent mc5i 5i Printer won't echo on screen row_addr_glitch xvpa YD Only positive motion for \f4vpa\f1/\f4mvpa\f1 caps semi_auto_right_margin sam YE Printing in last column causes \f4cr\f1 set_pglen_inch slength YI Set page length to #1 hundredth of an inch (use tparm) status_line_esc_ok eslok es Escape can be used on the status line tilde_glitch hz hz Hazeltine; can't print tilde (~) transparent_underline ul ul Underline character overstrikes xon_xoff xon xo Terminal uses xon/xoff handshaking .ft1 .TE \} .ifn \{ .PP .nf Cap- Termcap Variable name Code Description .sp0.5 .ft1 auto_left_margin bw bw cub1 wraps from col 0 to last column auto_right_margin am am Terminal has automatic margins back_color_erase bce ut Screen erased with background color buttons btns BT Number of buttons on the mouse can_change ccc cc Terminal can re-define existing color ceol_standout_ xhp xs Standout not erased by overwriting (hp) glitch col_addr_glitch xhpa YA Only positive motion for hpa/mhpa caps cpi_changes_res cpix YF Changing char pitch changes resolution create_window cwin CW Define win #1 to go from #2,#3 to #4,#5 cr_cancels_micro_ crxm YB Using \f4cr\f1 turns off micro mode mode dest_tabs_magic_smso xt xt Destructive tabs, magic \f4smso\f1 char (t1061) dial_phone dial DI Dial phone number #1 display_clock dclk DK Display time-of-day clock eat_newline_glitch xenl xn Newline ignored after 80 columns erase_overstrike eo eo Can erase overstrikes with a blank fixed_pause pause PA Pause for 2-3 seconds flash_hook hook fh Flash the switch hook generic_type gn gn Generic line type (eg, dialup, switch) get_mouse getm Gm Curses should get button events goto_window wingo WG Got to window #1 hangup hup HU Hang-up phone hard_copy hc hc Hardcopy terminal hard_cursor chts HC Cursor is hard to see has_meta_key km km Has a meta key (shift, sets parity bit) has_print_wheel daisy YC Printer needs to change char set has_status_line hs hs Has extra "status line" hue_lightness_ hls hl Terminal uses only HLS color notation saturation (Tektronix) insert_null_glitch in in Insert mode distinguishes nulls lpi_changes_res lpix YG Changing line pitch changes resolution memory_above da da Display may be retained above screen memory_below db db Display may be retained below screen move_insert_mode mir mi Safe to move while in insert mode move_standout_mode msgr ms Safe to move in standout modes needs_xon_xoff nxon nx Padding won't work, xon/xoff required no_esc_ctlc xsb xb Beehive (f1=escape, f2=ctrl C) no_pad_char npc NP Pad character doesn't exist non_dest_scroll_ ndscr ND Scrolling region is nondestructive region non_rev_rmcup nrrmc NR \f4smcup\f1 does not reverse \f4rmcup\f1 over_strike os os Terminal overstrikes on hard-copy terminal print_rate cps Ym Print rate in characters per second prtr_silent mc5i 5i Printer won't echo on screen row_addr_glitch xvpa YD Only positive motion for vpa/mvpa caps semi_auto_right_ sam YE Printing in last column causes \f4cr\f1 margin set_pglen_inch slength YI Set page length to #1 hundredth of an inch (use tparm) status_line_esc_ok eslok es Escape can be used on the status line tilde_glitch hz hz Hazeltine; can't print tilde (~) transparent_ ul ul Underline character overstrikes underline xon_xoff xon xo Terminal uses xon/xoff handshaking .fi .PP \} .SS Numbers .ift \{ .TS lfHB lfHB lfHB lfHB lfHB lfHB lfHB lfHB lw(1.15i)p7fCW lp7fCW lp7fCW lw(2i)p7. \s-2Cap-\s0 \s-2Termcap\s0 \s-2Variable\s0 \s-2name\s0 \s-2Code\s0 \s-2Description\s0 .sp0.5 .ft1 bit_image_entwining bitwin Yo Number of passes for each bit-map row bit_image_type bitype Yp Type of bit image device buffer_capacity bufsz Ya Number of bytes buffered before printing columns cols co Number of columns in a line dot_horz_spacing spinh Yc Spacing of dots horizontally in dots per inch dot_vert_spacing spinv Yb Spacing of pins vertically in pins per inch init_tabs it it Tabs initially every # spaces label_height lh lh Number of rows in each label label_width lw lw Number of columns in each label lines lines li Number of lines on a screen or a page lines_of_memory lm lm Lines of memory if > \f4lines\f1; \f40\f1 means varies max_attributes ma ma Maximum combined video attributes terminal can display magic_cookie_glitch xmc sg Number of blank chars left by \f4smso\f1 or \f4rmso\f1 max_colors colors Co Maximum number of colors on the screen max_micro_address maddr Yd Maximum value in \f4micro_..._address\f1 max_micro_jump mjump Ye Maximum value in \f4parm_..._micro\f1 max_pairs pairs pa Maximum number of color-pairs on the screen maximum_windows Wnum MW Maximum number of definable windows micro_char_size mcs Yg Character step size when in micro mode micro_line_size mls Yf Line step size when in micro mode no_color_video ncv NC Video attributes that can't be used with colors num_labels nlab Nl Number of labels on screen (start at 1) number_of_pins npins Yh Number of pins in print-head output_res_char orc Yi Horizontal resolution in units per character output_res_line orl Yj Vertical resolution in units per line output_res_horz_inch orhi Yk Horizontal resolution in units per inch output_res_vert_inch orvi Yl Vertical resolution in units per inch padding_baud_rate pb pb Lowest baud rate where padding needed virtual_terminal vt vt Virtual terminal number wide_char_size widcs Yn Character step size when in double wide mode width_status_line wsl ws Number of columns in status line .ft1 .TE \} .ifn \{ .PP .nf Cap- Termcap Variable name Code Description .sp0.5 .ft1 bit_image_entwining bitwin Yo Number of passes for each bit-map row bit_image_type bitype Yp Type of bit image device buffer_capacity bufsz Ya Number of bytes buffered before printing columns cols co Number of columns in a line dot_horz_spacing spinh Yc Spacing of dots horizontally in dots per inch dot_vert_spacing spinv Yb Spacing of pins vertically in pins/inch init_tabs it it Tabs initially every # spaces label_height lh lh Number of rows in each label label_width lw lw Number of columns in each label lines lines li Number of lines on a screen or a page lines_of_memory lm lm Lines of memory if > \f4lines\f1; \f40\f1 means varies max_attributes ma ma Maximum combined video attributes terminal can display magic_cookie_glitch xmc sg Number of blanks left by \f4smso\f1 or \f4rmso\f1 max_colors colors Co Max number of colors on the screen max_micro_address maddr Yd Max value in \f4micro_..._address\f1 max_micro_jump mjump Ye Max value in \f4parm_..._micro\f1 max_pairs pairs pa Max number of color-pairs on screen maximum_windows Wnum MW Max number of definable windows micro_char_size mcs Yg Character step size when in micro mode micro_line_size mls Yf Line step size when in micro mode no_color_video ncv NC Video attributes that can't be used with colors num_labels nlab Nl Number of labels on screen (start at 1) number_of_pins npins Yh Number of pins in print-head output_res_char orc Yi Horizontal resolution in units per char output_res_line orl Yj Vertical resolution in units per line output_res_horz_inch orhi Yk Horizontal resolution in units per inch output_res_vert_inch orvi Yl Vertical resolution in units per inch padding_baud_rate pb pb Lowest baud rate where padding needed virtual_terminal vt vt Virtual terminal number wide_char_size widcs Yn Char step size when in double wide mode width_status_line wsl ws Number of columns in status line .ft1 .TE .fi .PP \} .SS Strings .ift \{ .TS lfHB lfHB lfHB lfHB lfHB lfHB lfHB lfHB lw(1.15i)p7fCW lp7fCW lp7fCW lw(2i)p7. \s-2Cap-\s0 \s-2Termcap\s0 \s-2Variable\s0 \s-2name\s0 \s-2Code\s0 \s-2Description\s0 .sp0.5 .ft1 acs_chars acsc ac Graphic charset pairs aAbBcC alt_scancode_esc scesa S8 Alternate escape for scancode emulation (default is for vt100) back_tab cbt bt Back tab bell bel bl Audible signal (bell) bit_image_carriage_return bicr Yv Move to beginning of same row (use tparm) bit_image_newline binel Zz Move to next row of the bit image (use tparm) bit_image_repeat birep Xy Repeat bit-image cell #1 #2 times (use tparm) carriage_return cr cr Carriage return change_char_pitch cpi ZA Change number of characters per inch change_line_pitch lpi ZB Change number of lines per inch change_res_horz chr ZC Change horizontal resolution change_res_vert cvr ZD Change vertical resolution change_scroll_region csr cs Change to lines #1 through #2 (vt100) char_padding rmp rP Like \f4ip\f1 but when in replace mode char_set_names csnm Zy List of character set names clear_all_tabs tbc ct Clear all tab stops clear_margins mgc MC Clear all margins (top, bottom, and sides) clear_screen clear cl Clear screen and home cursor clr_bol el1 cb Clear to beginning of line, inclusive clr_eol el ce Clear to end of line clr_eos ed cd Clear to end of display code_set_init csin ci Init sequence for multiple codesets color_names colornm Yw Give name for color #1 column_address hpa ch Horizontal position absolute command_character cmdch CC Terminal settable cmd character in prototype cursor_address cup cm Move to row #1 col #2 cursor_down cud1 do Down one line cursor_home home ho Home cursor (if no \f4cup\f1) cursor_invisible civis vi Make cursor invisible cursor_left cub1 le Move left one space. cursor_mem_address mrcup CM Memory relative cursor addressing cursor_normal cnorm ve Make cursor appear normal (undo \f4vs/vi\f1) cursor_right cuf1 nd Non-destructive space (cursor or carriage right) cursor_to_ll ll ll Last line, first column (if no \f4cup\f1) cursor_up cuu1 up Upline (cursor up) cursor_visible cvvis vs Make cursor very visible define_bit_image_region defbi Yx Define rectangular bit-image region (use tparm) define_char defc ZE Define a character in a character set\|\(dg delete_character dch1 dc Delete character delete_line dl1 dl Delete line device_type devt dv Indicate language/codeset support dis_status_line dsl ds Disable status line display_pc_char dispc S1 Display PC character down_half_line hd hd Half-line down (forward 1/2 linefeed) ena_acs enacs eA Enable alternate character set end_bit_image_region endbi Yy End a bit-image region (use tparm) enter_alt_charset_mode smacs as Start alternate character set enter_am_mode smam SA Turn on automatic margins enter_blink_mode blink mb Turn on blinking enter_bold_mode bold md Turn on bold (extra bright) mode enter_ca_mode smcup ti String to begin programs that use \f4cup\f1 enter_delete_mode smdc dm Delete mode (enter) enter_dim_mode dim mh Turn on half-bright mode enter_doublewide_mode swidm ZF Enable double wide printing enter_draft_quality sdrfq ZG Set draft quality print enter_horizontal_hl_mode ehhlm \f2n/a\f1 turn on horizontal highlight mode enter_insert_mode smir im Insert mode (enter) enter_italics_mode sitm ZH Enable italics enter_left_hl_mode elhlm \f2n/a\f1 Turn on left highlight mode enter_leftward_mode slm ZI Enable leftward carriage motion enter_low_hl_mode elohlm \f2n/a\f1 turn on low highlight mode enter_micro_mode smicm ZJ Enable micro motion capabilities enter_near_letter_quality snlq ZK Set near-letter quality print enter_normal_quality snrmq ZL Set normal quality print enter_pc_charset_mode smpch S2 Enter PC character display mode enter_protected_mode prot mp Turn on protected mode enter_reverse_mode rev mr Turn on reverse video mode enter_right_hl_mode erhlm \f2n/a\f1 turn on right highlight mode enter_scancode_mode smsc S4 Enter PC scancode mode enter_secure_mode invis mk Turn on blank mode (characters invisible) enter_shadow_mode sshm ZM Enable shadow printing enter_standout_mode smso so Begin standout mode enter_subscript_mode ssubm ZN Enable subscript printing enter_superscript_mode ssupm ZO Enable superscript printing enter_top_hl_mode ethlm \f2n/a\f1 Turn on top highlight mode enter_underline_mode smul us Start underscore mode enter_upward_mode sum ZP Enable upward carriage motion enter_vertical_hl_mode evhlm \f2n/a\f1 turn on vertical highlight mode enter_xon_mode smxon SX Turn on xon/xoff handshaking erase_chars ech ec Erase #1 characters exit_alt_charset_mode rmacs ae End alternate character set exit_am_mode rmam RA Turn off automatic margins exit_attribute_mode sgr0 me Turn off all attributes exit_ca_mode rmcup te String to end programs that use \f4cup\f1 exit_delete_mode rmdc ed End delete mode exit_doublewide_mode rwidm ZQ Disable double wide printing exit_insert_mode rmir ei End insert mode exit_italics_mode ritm ZR Disable italics exit_leftward_mode rlm ZS Enable rightward (normal) carriage motion exit_micro_mode rmicm ZT Disable micro motion capabilities exit_pc_charset_mode rmpch S3 Disable PC character display mode exit_scancode_mode rmsc S5 Disable PC scancode mode exit_shadow_mode rshm ZU Disable shadow printing exit_standout_mode rmso se End standout mode exit_subscript_mode rsubm ZV Disable subscript printing exit_superscript_mode rsupm ZW Disable superscript printing exit_underline_mode rmul ue End underscore mode exit_upward_mode rum ZX Enable downward (normal) carriage motion exit_xon_mode rmxon RX Turn off xon/xoff handshaking flash_screen flash vb Visible bell (may not move cursor) form_feed ff ff Hardcopy terminal page eject from_status_line fsl fs Return from status line init_1string is1 i1 Terminal or printer initialization string init_2string is2 is Terminal or printer initialization string init_3string is3 i3 Terminal or printer initialization string init_file if if Name of initialization file init_prog iprog iP Path name of program for initialization initialize_color initc IC Initialize the definition of color initialize_pair initp Ip Initialize color-pair insert_character ich1 ic Insert character insert_line il1 al Add new blank line insert_padding ip ip Insert pad after character inserted .TE \} .ifn \{ .PP .nf Cap- Termcap Variable name Code Description .sp0.5 .ft1 acs_chars acsc ac Graphic charset pairs aAbBcC alt_scancode_esc scesa S8 Alternate escape for scancode emulation (default is for vt100) back_tab cbt bt Back tab bell bel bl Audible signal (bell) bit_image_ bicr Yv Move to beginning of same row carriage_return (use tparm) bit_image_newline binel Zz Move to next row of bit image (use tparm) bit_image_repeat birep Xy Repeat bit-image cell #1 #2 times (use tparm) carriage_return cr cr Carriage return change_char_pitch cpi ZA Change number of characters per inch change_line_pitch lpi ZB Change number of lines per inch change_res_horz chr ZC Change horizontal resolution change_res_vert cvr ZD Change vertical resolution change_scroll_ csr cs Change to lines #1 through #2 (vt100) region char_padding rmp rP Like \f4ip\f1 but when in replace mode char_set_names csnm Zy List of character set names clear_all_tabs tbc ct Clear all tab stops clear_margins mgc MC Clear all margins (top, bottom, and sides) clear_screen clear cl Clear screen and home cursor clr_bol el1 cb Clear to beginning of line, inclusive clr_eol el ce Clear to end of line clr_eos ed cd Clear to end of display code_set_init csin ci Init sequence for multiple codesets color_names colornm Yw Give name for color #1 column_address hpa ch Horizontal position absolute command_character cmdch CC Terminal settable cmd char in prototype cursor_address cup cm Move to row #1 col #2 cursor_down cud1 do Down one line cursor_home home ho Home cursor (if no \f4cup\f1) cursor_invisible civis vi Make cursor invisible cursor_left cub1 le Move left one space. cursor_mem_address mrcup CM Memory relative cursor addressing cursor_normal cnorm ve Make cursor appear normal (undo \f4vs/vi\f1) cursor_right cuf1 nd Non-destructive space (cursor or carriage right) cursor_to_ll ll ll Last line, first column (if no \f4cup\f1) cursor_up cuu1 up Upline (cursor up) cursor_visible cvvis vs Make cursor very visible define_bit_ defbi Yx Define rectangular bit-image region image_region (use tparm) define_char defc ZE Define a character in a character set\|\(dg delete_character dch1 dc Delete character delete_line dl1 dl Delete line device_type devt dv Indicate language/codeset support dis_status_line dsl ds Disable status line display_pc_char dispc S1 Display PC character down_half_line hd hd Half-line down (forward 1/2 linefeed) ena_acs enacs eA Enable alternate character set end_bit_image_ endbi Yy End a bit-image region (use tparm) region enter_alt_ smacs as Start alternate character set charset_mode enter_am_mode smam SA Turn on automatic margins enter_blink_mode blink mb Turn on blinking enter_bold_mode bold md Turn on bold (extra bright) mode enter_ca_mode smcup ti String to begin programs that use \f4cup\f1 enter_delete_mode smdc dm Delete mode (enter) enter_dim_mode dim mh Turn on half-bright mode enter_doublewide_ swidm ZF Enable double wide printing mode enter_draft_quality sdrfq ZG Set draft quality print enter_horizontal_ ehhlm n/a turn on horizontal highlight mode hl_mode enter_insert_mode smir im Insert mode (enter) enter_italics_mode sitm ZH Enable italics enter_left_hl_mode elhlm n/a turn on left highlight mode enter_leftward_mode slm ZI Enable leftward carriage motion enter_low_hl_mode elohlm n/a Turn on low highlight mode enter_micro_mode smicm ZJ Enable micro motion capabilities enter_near_letter_ snlq ZK Set near-letter quality print quality enter_normal_ snrmq ZL Set normal quality print quality enter_pc_charset_ smpch S2 Enter PC character display mode mode enter_protected_mode prot mp Turn on protected mode enter_reverse_mode rev mr Turn on reverse video mode enter_right_hl_mode erhlm n/a turn on right highlight mode enter_scancode_mode smsc S4 Enter PC scancode mode enter_secure_mode invis mk Turn on blank mode (characters invisible) enter_shadow_mode sshm ZM Enable shadow printing enter_standout_mode smso so Begin standout mode enter_subscript_mode ssubm ZN Enable subscript printing enter_superscript_ ssupm ZO Enable superscript printing mode enter_top_hl_mode ethlm n/a Turn on top highlight mode enter_underline_ smul us Start underscore mode mode enter_upward_mode sum ZP Enable upward carriage motion enter_vertical_hl_ evhlm n/a Turn on vertical highlight mode mode enter_xon_mode smxon SX Turn on xon/xoff handshaking erase_chars ech ec Erase #1 characters exit_alt_charset_ rmacs ae End alternate character set mode exit_am_mode rmam RA Turn off automatic margins exit_attribute_mode sgr0 me Turn off all attributes exit_ca_mode rmcup te String to end programs that use \f4cup\f1 exit_delete_mode rmdc ed End delete mode exit_doublewide_ rwidm ZQ Disable double wide printing mode exit_insert_mode rmir ei End insert mode exit_italics_mode ritm ZR Disable italics exit_leftward_mode rlm ZS Enable rightward (normal) carriage motion exit_micro_mode rmicm ZT Disable micro motion capabilities exit_pc_charset_ rmpch S3 Disable PC character display mode mode exit_scancode_mode rmsc S5 Disable PC scancode mode exit_shadow_mode rshm ZU Disable shadow printing exit_standout_mode rmso se End standout mode exit_subscript_mode rsubm ZV Disable subscript printing exit_superscript_ rsupm ZW Disable superscript printing mode exit_underline_mode rmul ue End underscore mode exit_upward_mode rum ZX Enable downward (normal) carriage motion exit_xon_mode rmxon RX Turn off xon/xoff handshaking flash_screen flash vb Visible bell (may not move cursor) form_feed ff ff Hardcopy terminal page eject from_status_line fsl fs Return from status line init_1string is1 i1 Terminal or printer initialization string init_2string is2 is Terminal or printer initialization string init_3string is3 i3 Terminal or printer initialization string init_file if if Name of initialization file init_prog iprog iP Path name of program for initialization initialize_color initc IC Initialize the definition of color initialize_pair initp Ip Initialize color-pair insert_character ich1 ic Insert character insert_line il1 al Add new blank line insert_padding ip ip Insert pad after character inserted .fi \} .P The ``\f4key_\fP'' strings are sent by specific keys. The ``\f4key_\fP'' descriptions include the macro, defined in \f4\f1, for the code returned by the CURSES function \f4getch()\f1 when the key is pressed [see \f2curs_getch\f1(3X)]. .ift \{ .TS lfHB lfHB lfHB lfHB lfHB lfHB lfHB lfHB lw(1.15i)p7fCW lp7fCW lp7fCW lw(2i)p7. \s-2Cap-\s0 \s-2Termcap\s0 \s-2Variable\s0 \s-2name\s0 \s-2Code\s0 \s-2Description\s0 .sp0.5 .ft1 key_a1 ka1 K1 upper left of keypad key_a3 ka3 K3 upper right of keypad key_b2 kb2 K2 center of keypad key_backspace kbs kb sent by backspace key key_beg kbeg @1 sent by beg(inning) key key_btab kcbt kB sent by back-tab key key_c1 kc1 K4 lower left of keypad key_c3 kc3 K5 lower right of keypad key_cancel kcan @2 sent by cancel key key_catab ktbc ka sent by clear-all-tabs key key_clear kclr kC sent by clear-screen or erase key key_close kclo @3 sent by close key key_command kcmd @4 sent by cmd (command) key key_copy kcpy @5 sent by copy key key_create kcrt @6 sent by create key key_ctab kctab kt sent by clear-tab key key_dc kdch1 kD sent by delete-character key key_dl kdl1 kL sent by delete-line key key_down kcud1 kd sent by terminal down-arrow key key_eic krmir kM sent by \f4rmir\f1 or \f4smir\f1 in insert mode key_end kend @7 sent by end key key_enter kent @8 sent by enter/send key key_eol kel kE sent by clear-to-end-of-line key key_eos ked kS sent by clear-to-end-of-screen key key_exit kext @9 sent by exit key key_f0 kf0 k0 sent by function key f0 key_f1 kf1 k1 sent by function key f1 key_f2 kf2 k2 sent by function key f2 key_f3 kf3 k3 sent by function key f3 key_f4 kf4 k4 sent by function key f4 key_f5 kf5 k5 sent by function key f5 key_f6 kf6 k6 sent by function key f6 key_f7 kf7 k7 sent by function key f7 key_f8 kf8 k8 sent by function key f8 key_f9 kf9 k9 sent by function key f9 key_f10 kf10 k; sent by function key f10 key_f11 kf11 F1 sent by function key f11 key_f12 kf12 F2 sent by function key f12 key_f13 kf13 F3 sent by function key f13 key_f14 kf14 F4 sent by function key f14 key_f15 kf15 F5 sent by function key f15 key_f16 kf16 F6 sent by function key f16 key_f17 kf17 F7 sent by function key f17 key_f18 kf18 F8 sent by function key f18 key_f19 kf19 F9 sent by function key f19 key_f20 kf20 FA sent by function key f20 key_f21 kf21 FB sent by function key f21 key_f22 kf22 FC sent by function key f22 key_f23 kf23 FD sent by function key f23 key_f24 kf24 FE sent by function key f24 key_f25 kf25 FF sent by function key f25 key_f26 kf26 FG sent by function key f26 key_f27 kf27 FH sent by function key f27 key_f28 kf28 FI sent by function key f28 key_f29 kf29 FJ sent by function key f29 key_f30 kf30 FK sent by function key f30 key_f31 kf31 FL sent by function key f31 key_f32 kf32 FM sent by function key f32 key_f33 kf33 FN sent by function key f33 key_f34 kf34 FO sent by function key f34 key_f35 kf35 FP sent by function key f35 key_f36 kf36 FQ sent by function key f36 key_f37 kf37 FR sent by function key f37 key_f38 kf38 FS sent by function key f38 key_f39 kf39 FT sent by function key f39 key_f40 kf40 FU sent by function key f40 key_f41 kf41 FV sent by function key f41 key_f42 kf42 FW sent by function key f42 key_f43 kf43 FX sent by function key f43 key_f44 kf44 FY sent by function key f44 key_f45 kf45 FZ sent by function key f45 key_f46 kf46 Fa sent by function key f46 key_f47 kf47 Fb sent by function key f47 key_f48 kf48 Fc sent by function key f48 key_f49 kf49 Fd sent by function key f49 key_f50 kf50 Fe sent by function key f50 key_f51 kf51 Ff sent by function key f51 key_f52 kf52 Fg sent by function key f52 key_f53 kf53 Fh sent by function key f53 key_f54 kf54 Fi sent by function key f54 key_f55 kf55 Fj sent by function key f55 key_f56 kf56 Fk sent by function key f56 key_f57 kf57 Fl sent by function key f57 key_f58 kf58 Fm sent by function key f58 key_f59 kf59 Fn sent by function key f59 key_f60 kf60 Fo sent by function key f60 key_f61 kf61 Fp sent by function key f61 key_f62 kf62 Fq sent by function key f62 key_f63 kf63 Fr sent by function key f63 key_find kfnd @0 sent by find key key_help khlp %1 sent by help key key_home khome kh sent by home key key_ic kich1 kI sent by ins-char/enter ins-mode key key_il kil1 kA sent by insert-line key key_left kcub1 kl sent by terminal left-arrow key key_ll kll kH sent by home-down key key_mark kmrk %2 sent by mark key key_message kmsg %3 sent by message key key_mouse kmous Km 0631, Mouse event has occurred key_move kmov %4 sent by move key key_next knxt %5 sent by next-object key key_npage knp kN sent by next-page key key_open kopn %6 sent by open key key_options kopt %7 sent by options key key_ppage kpp kP sent by previous-page key key_previous kprv %8 sent by previous-object key key_print kprt %9 sent by print or copy key key_redo krdo %0 sent by redo key key_reference kref &1 sent by ref(erence) key key_refresh krfr &2 sent by refresh key key_replace krpl &3 sent by replace key key_restart krst &4 sent by restart key key_resume kres &5 sent by resume key key_right kcuf1 kr sent by terminal right-arrow key key_save ksav &6 sent by save key key_sbeg kBEG &9 sent by shifted beginning key key_scancel kCAN &0 sent by shifted cancel key key_scommand kCMD \(**1 sent by shifted command key key_scopy kCPY \(**2 sent by shifted copy key key_screate kCRT \(**3 sent by shifted create key key_sdc kDC \(**4 sent by shifted delete-char key key_sdl kDL \(**5 sent by shifted delete-line key key_select kslt \(**6 sent by select key key_send kEND \(**7 sent by shifted end key key_seol kEOL \(**8 sent by shifted clear-line key key_sexit kEXT \(**9 sent by shifted exit key key_sf kind kF sent by scroll-forward/down key key_sfind kFND \(**0 sent by shifted find key key_shelp kHLP #1 sent by shifted help key key_shome kHOM #2 sent by shifted home key key_sic kIC #3 sent by shifted input key key_sleft kLFT #4 sent by shifted left-arrow key key_smessage kMSG %a sent by shifted message key key_smove kMOV %b sent by shifted move key key_snext kNXT %c sent by shifted next key key_soptions kOPT %d sent by shifted options key key_sprevious kPRV %e sent by shifted prev key key_sprint kPRT %f sent by shifted print key key_sr kri kR sent by scroll-backward/up key key_sredo kRDO %g sent by shifted redo key key_sreplace kRPL %h sent by shifted replace key key_sright kRIT %i sent by shifted right-arrow key key_srsume kRES %j sent by shifted resume key key_ssave kSAV !1 sent by shifted save key key_ssuspend kSPD !2 sent by shifted suspend key key_stab khts kT sent by set-tab key key_sundo kUND !3 sent by shifted undo key key_suspend kspd &7 sent by suspend key key_undo kund &8 sent by undo key key_up kcuu1 ku sent by terminal up-arrow key keypad_local rmkx ke Out of ``keypad-transmit'' mode keypad_xmit smkx ks Put terminal in ``keypad-transmit'' mode lab_f0 lf0 l0 Labels on function key f0 if not f0 lab_f1 lf1 l1 Labels on function key f1 if not f1 lab_f2 lf2 l2 Labels on function key f2 if not f2 lab_f3 lf3 l3 Labels on function key f3 if not f3 lab_f4 lf4 l4 Labels on function key f4 if not f4 lab_f5 lf5 l5 Labels on function key f5 if not f5 lab_f6 lf6 l6 Labels on function key f6 if not f6 lab_f7 lf7 l7 Labels on function key f7 if not f7 lab_f8 lf8 l8 Labels on function key f8 if not f8 lab_f9 lf9 l9 Labels on function key f9 if not f9 lab_f10 lf10 la Labels on function key f10 if not f10 label_format fln Lf Label format label_off rmln LF Turn off soft labels label_on smln LO Turn on soft labels meta_off rmm mo Turn off "meta mode" meta_on smm mm Turn on "meta mode" (8th bit) micro_column_address mhpa ZY Like \f4column_address\f1 for micro adjustment micro_down mcud1 ZZ Like \f4cursor_down\f1 for micro adjustment micro_left mcub1 Za Like \f4cursor_left\f1 for micro adjustment micro_right mcuf1 Zb Like \f4cursor_right\f1 for micro adjustment micro_row_address mvpa Zc Like \f4row_address\f1 for micro adjustment micro_up mcuu1 Zd Like \f4cursor_up\f1 for micro adjustment mouse_info minfo Mi Mouse status information newline nel nw Newline (behaves like \f4cr\f1 followed by \f4lf\f1) order_of_pins porder Ze Matches software bits to print-head pins orig_colors oc oc Set all color(-pair)s to the original ones orig_pair op op Set default color-pair to the original one pad_char pad pc Pad character (rather than null) parm_dch dch DC Delete #1 chars parm_delete_line dl DL Delete #1 lines parm_down_cursor cud DO Move down #1 lines. parm_down_micro mcud Zf Like \f4parm_down_cursor\f1 for micro adjust. parm_ich ich IC Insert #1 blank chars parm_index indn SF Scroll forward #1 lines. parm_insert_line il AL Add #1 new blank lines parm_left_cursor cub LE Move cursor left #1 spaces parm_left_micro mcub Zg Like \f4parm_left_cursor\f1 for micro adjust. parm_right_cursor cuf RI Move right #1 spaces. parm_right_micro mcuf Zh Like \f4parm_right_cursor\f1 for micro adjust. parm_rindex rin SR Scroll backward #1 lines. parm_up_cursor cuu UP Move cursor up #1 lines. parm_up_micro mcuu Zi Like \f4parm_up_cursor\f1 for micro adjust. pc_term_options pctrm S6 PC terminal options pkey_key pfkey pk Prog funct key #1 to type string #2 pkey_local pfloc pl Prog funct key #1 to execute string #2 pkey_plab pfxl xl Prog key #1 to xmit string #2 and show string #3 pkey_xmit pfx px Prog funct key #1 to xmit string #2 plab_norm pln pn Prog label #1 to show string #2 print_screen mc0 ps Print contents of the screen prtr_non mc5p pO Turn on the printer for #1 bytes prtr_off mc4 pf Turn off the printer prtr_on mc5 po Turn on the printer pulse pulse PU Select pulse dialing quick_dial qdial QD Dial phone number #1, without progress detection remove_clock rmclk RC Remove time-of-day clock repeat_char rep rp Repeat char #1 #2 times req_for_input rfi RF Send next input char (for ptys) req_mouse_pos reqmp RQ Request mouse position report reset_1string rs1 r1 Reset terminal completely to sane modes reset_2string rs2 r2 Reset terminal completely to sane modes reset_3string rs3 r3 Reset terminal completely to sane modes reset_file rf rf Name of file containing reset string restore_cursor rc rc Restore cursor to position of last sc row_address vpa cv Vertical position absolute save_cursor sc sc Save cursor position scancode_escape scesc S7 Escape for scancode emulation scroll_forward ind sf Scroll text up scroll_reverse ri sr Scroll text down select_char_set scs Zj Select character set set0_des_seq s0ds s0 Shift into codeset 0 (EUC set 0, ASCII) set1_des_seq s1ds s1 Shift into codeset 1 set2_des_seq s2ds s2 Shift into codeset 2 set3_des_seq s3ds s3 Shift into codeset 3 set_a_background setab AB Set background color using ANSI escape set_a_foreground setaf AF Set foreground color using ANSI escape set_attributes sgr sa Define the video attributes #1-#9 set_background setb Sb Set current background color set_bottom_margin smgb Zk Set bottom margin at current line set_bottom_margin_parm smgbp Zl Set bottom margin at #1 or #2 lines from bottom set_clock sclk SC Set time-of-day clock set_color_band setcolor Yz Change to ribbon color #1 set_color_pair scp sp Set current color-pair set_foreground setf Sf Set current foreground color1 set_left_margin smgl ML Set left margin at current line set_left_margin_parm smglp Zm Set left (right) margin at column #1 (#2) set_lr_margin smglr ML Sets both left and right margins set_page_length slines YZ Set page length to #1 lines (use tparm) set_right_margin smgr MR Set right margin at current column set_right_margin_parm smgrp Zn Set right margin at column #1 set_tab hts st Set a tab in all rows, current column set_tb_margin smgtb MT Sets both top and bottom margins set_top_margin smgt Zo Set top margin at current line set_top_margin_parm smgtp Zp Set top (bottom) margin at line #1 (#2) set_window wind wi Current window is lines #1-#2 cols #3-#4 start_bit_image sbim Zq Start printing bit image graphics start_char_set_def scsd Zr Start definition of a character set stop_bit_image rbim Zs End printing bit image graphics stop_char_set_def rcsd Zt End definition of a character set subscript_characters subcs Zu List of ``subscript-able'' characters superscript_characters supcs Zv List of ``superscript-able'' characters tab ht ta Tab to next 8-space hardware tab stop these_cause_cr docr Zw Printing any of these chars causes \f4cr\f1 to_status_line tsl ts Go to status line, col #1 tone tone TO Select touch tone dialing user0 u0 U0 User string 0 user1 u1 U1 User string 1 user2 u2 U2 User string 2 user3 U3 u3 User string 3 user4 u4 u4 User string 4 user5 u5 u5 User string 5 user6 u6 u6 User string 6 user7 u7 u7 User string 7 user8 u8 u8 User string 8 user9 u9 u9 User string 9 underline_char uc uc Underscore one char and move past it up_half_line hu hu Half-line up (reverse 1/2 linefeed) wait_tone wait WA Wait for dial tone xoff_character xoffc XF X-off character xon_character xonc XN X-on character zero_motion zerom Zx No motion for the subsequent character .ft1 .TE \} .ifn \{ .nf .PP Cap- Termcap Variable name Code Description\s0 .sp0.5 .ft1 key_a1 ka1 K1 upper left of keypad key_a3 ka3 K3 upper right of keypad key_b2 kb2 K2 center of keypad key_backspace kbs kb sent by backspace key key_beg kbeg @1 sent by beg(inning) key key_btab kcbt kB sent by back-tab key key_c1 kc1 K4 lower left of keypad key_c3 kc3 K5 lower right of keypad key_cancel kcan @2 sent by cancel key key_catab ktbc ka sent by clear-all-tabs key key_clear kclr kC sent by clear-screen or erase key key_close kclo @3 sent by close key key_command kcmd @4 sent by cmd (command) key key_copy kcp @5 sent by copy key key_create kcrt @6 sent by create key key_ctab kctab kt sent by clear-tab key key_dc kdch1 kD sent by delete-character key key_dl kdl1 kL sent by delete-line key key_down kcud1 kd sent by terminal down-arrow key key_eic krmir kM sent by \f4rmir\f1 or \f4smir\f1 in insert mode key_end kend @7 sent by end key key_enter kent @8 sent by enter/send key key_eol kel kE sent by clear-to-end-of-line key key_eos ked kS sent by clear-to-end-of-screen key key_exit kext @9 sent by exit key key_f0 kf0 k0 sent by function key f0 key_f1 kf1 k1 sent by function key f1 key_f2 kf2 k2 sent by function key f2 key_f3 kf3 k3 sent by function key f3 key_f4 kf4 k4 sent by function key f4 key_f5 kf5 k5 sent by function key f5 key_f6 kf6 k6 sent by function key f6 key_f7 kf7 k7 sent by function key f7 key_f8 kf8 k8 sent by function key f8 key_f9 kf9 k9 sent by function key f9 key_f10 kf10 k; sent by function key f10 key_f11 kf11 F1 sent by function key f11 key_f12 kf12 F2 sent by function key f12 key_f13 kf13 F3 sent by function key f13 key_f14 kf14 F4 sent by function key f14 key_f15 kf15 F5 sent by function key f15 key_f16 kf16 F6 sent by function key f16 key_f17 kf17 F7 sent by function key f17 key_f18 kf18 F8 sent by function key f18 key_f19 kf19 F9 sent by function key f19 key_f20 kf20 FA sent by function key f20 key_f21 kf21 FB sent by function key f21 key_f22 kf22 FC sent by function key f22 key_f23 kf23 FD sent by function key f23 key_f24 kf24 FE sent by function key f24 key_f25 kf25 FF sent by function key f25 key_f26 kf26 FG sent by function key f26 key_f27 kf27 FH sent by function key f27 key_f28 kf28 FI sent by function key f28 key_f29 kf29 FJ sent by function key f29 key_f30 kf30 FK sent by function key f30 key_f31 kf31 FL sent by function key f31 key_f32 kf32 FM sent by function key f32 key_f33 kf33 FN sent by function key f33 key_f34 kf34 FO sent by function key f34 key_f35 kf35 FP sent by function key f35 key_f36 kf36 FQ sent by function key f36 key_f37 kf37 FR sent by function key f37 key_f38 kf38 FS sent by function key f38 key_f39 kf39 FT sent by function key f39 key_f40 kf40 FU sent by function key f40 key_f41 kf41 FV sent by function key f41 key_f42 kf42 FW sent by function key f42 key_f43 kf43 FX sent by function key f43 key_f44 kf44 FY sent by function key f44 key_f45 kf45 FZ sent by function key f45 key_f46 kf46 Fa sent by function key f46 key_f47 kf47 Fb sent by function key f47 key_f48 kf48 Fc sent by function key f48 key_f49 kf49 Fd sent by function key f49 key_f50 kf50 Fe sent by function key f50 key_f51 kf51 Ff sent by function key f51 key_f52 kf52 Fg sent by function key f52 key_f53 kf53 Fh sent by function key f53 key_f54 kf54 Fi sent by function key f54 key_f55 kf55 Fj sent by function key f55 key_f56 kf56 Fk sent by function key f56 key_f57 kf57 Fl sent by function key f57 key_f58 kf58 Fm sent by function key f58 key_f59 kf59 Fn sent by function key f59 key_f60 kf60 Fo sent by function key f60 key_f61 kf61 Fp sent by function key f61 key_f62 kf62 Fq sent by function key f62 key_f63 kf63 Fr sent by function key f63 key_find kfnd @0 sent by find key key_helpi khlp %1 sent by help key key_homei khome kh sent by home key key_ic kich1 kI sent by ins-char/enter ins-mode key key_il kil1 kA sent by insert-line key key_left kcub1 kl sent by terminal left-arrow key key_ll kll kH sent by home-down key key_mark kmrk %2 sent by mark key key_message kmsg %3 sent by message key key_mouse kmous Km 0631, Mouse event has occurred key_movei kmov %4 sent by move key key_next knxt %5 sent by next-object key key_npage knp kN sent by next-page key key_open kopn %6 sent by open key key_options kopt %7 sent by options key key_ppagei kpp kP sent by previous-page key key_previous kprv %8 sent by previous-object key key_print kprt %9 sent by print or copy key key_redo krdo %0 sent by redo key key_reference kref &1 sent by ref(erence) key key_refresh krfr &2 sent by refresh key key_replace krpl &3 sent by replace key key_restart krst &4 sent by restart key key_resume kres &5 sent by resume key key_right kcuf1 kr sent by terminal right-arrow key key_save ksav &6 sent by save key key_sbeg kBEG &9 sent by shifted beginning key key_scancel kCAN &0 sent by shifted cancel key key_scommand kCMD \(**1 sent by shifted command key key_scopy kCPY \(**2 sent by shifted copy key key_screate kCRT \(**3 sent by shifted create key key_sdc kDCi \(**4 sent by shifted delete-char key key_sdl kDL \(**5 sent by shifted delete-line key key_select kslt \(**6 sent by select key key_send kEND \(**7 sent by shifted end key key_seol kEOL \(**8 sent by shifted clear-line key key_sexit kEXT \(**9 sent by shifted exit key key_sf kind kF sent by scroll-forward/down key key_sfind kFNDi \(**0 sent by shifted find key key_shelp kHLP #1 sent by shifted help key key_shome kHOM #2 sent by shifted home key key_sic kIC #3 sent by shifted input key key_sleft kLFT #4 sent by shifted left-arrow key key_smessage kMSG %a sent by shifted message key key_smove kMOV %b sent by shifted move key key_snext kNXT %c sent by shifted next key key_soptions kOPT %d sent by shifted options key key_sprevious kPRV %e sent by shifted prev key key_sprint kPRT %f sent by shifted print key key_sr kri kR sent by scroll-backward/up key key_sredo kRDO %g sent by shifted redo key key_sreplace kRPL %h sent by shifted replace key key_sright kRIT %i sent by shifted right-arrow key key_srsume kRES %j sent by shifted resume key key_ssave kSAV !1 sent by shifted save key key_ssuspend kSPD !2 sent by shifted suspend key key_stab khts kT sent by set-tab key key_sundo kUND !3 sent by shifted undo key key_suspend kspd &7 sent by suspend key key_undo kund &8 sent by undo key key_up kcuu1 ku sent by terminal up-arrow key keypad_local rmkx ke Out of ``keypad-transmit'' mode keypad_xmit smkx ks Put terminal in ``keypad-transmit'' mode lab_f0 lf0 l0 Labels on function key f0 if not f0 lab_f1 lf1 l1 Labels on function key f1 if not f1 lab_f2 lf2 l2 Labels on function key f2 if not f2 lab_f3 lf3 l3 Labels on function key f3 if not f3 lab_f4 lf4 l4 Labels on function key f4 if not f4 lab_f5 lf5 l5 Labels on function key f5 if not f5 lab_f6 lf6 l6 Labels on function key f6 if not f6 lab_f7 lf7 l7 Labels on function key f7 if not f7 lab_f8 lf8 l8 Labels on function key f8 if not f8 lab_f9 lf9 l9 Labels on function key f9 if not f9 lab_f10 lf10 la Labels on function key f10 if not f10 label_forma fln Lf Label format label_off rmln LF Turn off soft labels label_on smln LO Turn on soft labels meta_off rmm mo Turn off "meta mode" meta_on smm mm Turn on "meta mode" (8th bit) micro_column_ mhpa ZY Like \f4column_address\f1 for micro adjustment address micro_down mcud1 ZZ Like \f4cursor_down\f1 for micro adjustment micro_left mcub1 Za Like \f4cursor_left\f1 for micro adjustment micro_right mcuf1 Zb Like \f4cursor_right\f1 for micro adjustment micro_row_address mvpa Zc Like \f4row_address\f1 for micro adjustment micro_up mcuu1 Zd Like \f4cursor_up\f1 for micro adjustment mouse_info minfo Mi Mouse status information newline nel nw Newline (behaves like \f4cr\f1 followed by \f4lf\f1) order_of_pins porder Ze Matches software bits to print-head pins orig_colors oc oc Set all color(-pair)s to the original ones orig_pair op op Set default color-pair to the original one pad_char pad pc Pad character (rather than null) parm_dch dch DC Delete #1 chars parm_delete_line dl DL Delete #1 lines parm_down_cursor cud DO Move down #1 lines. parm_down_micro mcud Zf Like \f4parm_down_cursor\f1 for micro adjust. parm_ich ich IC Insert #1 blank chars parm_index indn SF Scroll forward #1 lines. parm_insert_line il AL Add #1 new blank lines parm_left_cursor cub LE Move cursor left #1 spaces parm_left_micro mcub Zg Like \f4parm_left_cursor\f1 for micro adjust. parm_right_cursor cuf RI Move right #1 spaces. parm_right_micro mcuf Zh Like \f4parm_right_cursor\f1 for micro adjust. parm_rindex rin SR Scroll backward #1 lines. parm_up_cursor cuu UP Move cursor up #1 lines. parm_up_micro mcuu Zi Like \f4parm_up_cursor\f1 for micro adjust. pc_term_options pctrm S6 PC terminal options pkey_key pfkey pk Prog funct key #1 to type string #2 pkey_local pfloc pl Prog funct key #1 to execute string #2 pkey_plab pfxl xl Prog key #1 to xmit string #2 and show string #3 pkey_xmit pfx px Prog funct key #1 to xmit string #2 plab_norm pln pn Prog label #1 to show string #2 print_screen mc0 ps Print contents of the screen prtr_non mc5p pO Turn on the printer for #1 bytes prtr_off mc4 pf Turn off the printer prtr_on mc5 po Turn on the printer pulse pulse PU Select pulse dialing quick_dial qdial QD Dial phonenumber #1, w/out progress detection remove_clock rmclk RC Remove time-of-day clock repeat_char rep rp Repeat char #1 #2 times req_for_input rfi RF Send next input char (for ptys) req_mouse_pos reqmp RQ Request mouse position report reset_1string rs1 r1 Reset terminal completely to sane modes reset_2string rs2 r2 Reset terminal completely to sane modes reset_3string rs3 r3 Reset terminal completely to sane modes reset_file rf rf Name of file containing reset string restore_cursor rc rc Restore cursor to position of last sc row_address vpa cv Vertical position absolute save_cursor sc sc Save cursor position scancode_escape scesc S7 Escape for scancode emulation scroll_forward ind sf Scroll text up scroll_reverse ri sr Scroll text down select_char_set scs Zj Select character set set0_des_seq s0ds s0 Shift into codeset 0 (EUC set 0, ASCII) set1_des_seq s1ds s1 Shift into codeset 1 set2_des_seq s2ds s2 Shift into codeset 2 set3_des_seq s3ds s3 Shift into codeset 3 set_a_background setab AB Set background color using ANSI escape set_a_foreground setaf AF Set foreground color using ANSI escape set_attributes sgr sa Define the video attributes #1-#9 set_background setb Sb Set current background color set_bottom_margin smgb Zk Set bottom margin at current line set_bottom_ smgbp Zl Set bottom margin at #1 or #2 lines from margin_parm bottom set_clocki sclk SC Set time-of-day clock set_color_bandi setcolor Yz Change to ribbon color #1 set_color_pair scp sp Set current color-pair set_foreground setf Sf Set current foreground color1 set_left_margin smgl ML Set left margin at current line set_left_margin_ smglp Zm Set left (right) margin at column #1 (#2) parm set_lr_margin smglr ML Sets both left and right margins set_page_length slines YZ Set page length to #1 lines (use tparm) set_right_margin smgr MR Set right margin at current column set_right_ smgrp Zn Set right margin at column #1 margin_parm set_tab hts st Set a tab in all rows, current column set_tb_margin smgtb MT Sets both top and bottom margins set_top_margin smgt Zo Set top margin at current line set_top_margin_ smgtp Zp Set top (bottom) margin at line #1 (#2) parm set_window wind wi Current window is lines #1-#2 cols #3-#4 start_bit_image sbim Zq Start printing bit image graphics start_char_set_ scsd Zr Start definition of a character set def stop_bit_image rbim Zs End printing bit image graphics stop_char_set_def rcsd Zt End definition of a character set subscript_ subcs Zu List of ``subscript-able'' characters characters superscript_ supcs Zv List of ``superscript-able'' characters characters tab ht ta Tab to next 8-space hardware tab stop these_cause_cr docr Zw Printing any of these chars causes \f4cr\f1 to_status_line tsl ts Go to status line, col #1 tone tone TO Select touch tone dialing user0 u0 U0 User string 0 user1 u1 U1 User string 1 user2 u2 U2 User string 2 user3 U3 u3 User string 3 user4 u4 u4 User string 4 user5 u5 u5 User string 5 user6 u6 u6 User string 6 user7 u7 u7 User string 7 user8 u8 u8 User string 8 user9 u9 u9 User string 9 underline_char uc uc Underscore one char and move past it up_half_line hu hu Half-line up (reverse 1/2 linefeed) wait_tone wait WA Wait for dial tone xoff_character xoffc XF X-off character xon_character xonc XN X-on character zero_motion zerom Zx No motion for the subsequent character \} .PP The following are declared as functions and may be defined as macros: .in +3 .ft 4 .TS l l. int tgetent(char *\f2bp\fP, char *\f2name\fP); int tgetflag(char \f2id\fP[2]); int tgetnum(char \f2id\fP[2]); char *tgetstr(char \f2id\fP[2], char **\f2area\fP); char *tgoto(char *\f2cap\fP, int \f2col\fP, int \f2row\fP); int tputs(char *\f2str\fP, int \f2affcnt\fP, int (*\f2putc\fP)(void)); .TE .ft 1 .in -3 .SH SEE ALSO .br curs_termcap(3X), curs_termin(3X), printf(1). .\" .\" .\"toc@\f3term_c(4)\f1:\0\0\f4term()\fP, \f4term.h()\f1@@@terminal capabilities .\"toc@\f4term()\f1: terminal capabilities@@@see \f3term_c(4)\f1 .\"toc@\f4term.h()\f1: terminal capabilities@@@see \f3term_c(4)\f1 .\"index@\f4term()\fP \- terminal capabilities@@@\f3term_c(4)\f1 .\"index@\f4term.h()\fP \- terminal capabilities@@@\f3term_c(4)\f1 .\"index@terminal capabilities@@@\f3term_c(4)\f1 .\"links@term_c.4 TERM.4 .\"links@term_c.4 term.h.4 ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "UpLog" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "\*LUpLog\*O file" .iX "Update Server" "log file" .SH NAME .PP \*LUpLog\*O \- Contains messages generated by the server portion of the Update Server .SH "DESCRIPTION" .PP The \*LUpLog\*O file contains execution and error messages generated by the server portion (\*Lupserver\*O process) of the Update Server. The \*Lupserver\*O process distributes files from the local disk of a machine in response to requests from the client portion (\*Lupclient\*O process) of the Update Server running on other machines. The \*Lupserver\*O process should run on the cell's System Control machine and on the Binary Distribution machine for each CPU/operating system type. .PP If the \*LUpLog\*O file does not already exist when the \*Lupserver\*O process starts, the server process creates the file in the directory named \*Edcelocal\*L/var/dfs/adm\*O. The process then appends any subsequent messages to the file once it exists. If the file exists when the \*Lupserver\*O process starts, the process moves the current version of the file to the \*LUpLog.old\*O file in the same directory (overwriting the current \*LUpLog.old\*O file if it exists) before creating a new version to which to append messages. .PP The process can write different types of output to the file, depending on the actions it performs and any problems it encounters. The file can be viewed with the \*Lbos getlog\*O command. Because it is an ASCII file, it can also be viewed with the \*Lmore\*O command (or a similar command appropriate to the local operating system), which requires \*Lread\*O permission on the file. .PP Events are recorded in the log file only at their completion, so the process does not use the file to reconstruct failed operations. However, the contents of the log file can help you evaluate server process failures and other problems. .PP Note that the \*LUpLog\*O file contains execution and error messages for the \*Lupserver\*O process only; it does not log messages for the \*Lupclient\*O process. A log file can be specified for use with the \*Lupclient\*O process when that process is started on a client machine. .SH "RELATED INFORMATION" .PP Commands: \*Lbos getlog(1m)\*O, \*Lupclient(1m)\*O, \*Lupserver(1m)\*O ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "Vn" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .SH NAME .iX "-[" "V files" "about" .iX "-[" "disk cache" "V files" .iX "-[" "cache" "V files" .iX "-[" "chunks" "V files" .PP \*LV\*En\*O \- Contains a chunk of data cached in a disk cache .SH "DESCRIPTION" .PP .zA "enh,R1.0.2,Small clarification" A \*LV\*En\*O file, or V file, holds a chunk of cached data on a client machine that is using a disk cache. In the name of an actual V file, \*En\*O is an integer; the name of each V file has a unique integer different from other V files on the machine (for example, \*LV1\*O, \*LV2\*O, and so on). The format of a V file depends on the format of the data it is caching: a V file containing a cached binary file has a binary format; a V file storing a cached ASCII file has an ASCII format. .zZ "enh,R1.0.2,Small clarification" .PP Each V file always resides in the cache directory, which by default is \*Edcelocal\*L/var/adm/dfs/cache\*O. This directory is specified in the second field of the \*LCacheInfo\*O file; it can be overridden to name a different directory. The \*LCacheItems\*O file in the cache directory records information about each V file, such as its file ID and data version numbers. .PP .zA "defect,7219,R1.0.2,Review comments" The number of V files, or cache chunks, depends on the size of the disk cache (specified in the third field of the \*LCacheInfo\*O file, defined with the \*Ldfsd\*O command's \*L-blocks\*O option, or set with the \*Lcm setcachesize\*O command). For a disk cache, the number of chunks is heuristically computed as the number of cache blocks divided by 8. You can override the default number of chunks with the \*Ldfsd\*O command using the \*L-files\*O option. Specify a positive integer not greater than 32,000. .zZ "defect,7219,R1.0.2,Review comments" .PP To use a cache most effectively, issue the \*Ldu\*O command on the cache directory to determine the number of cache blocks used; compare this number to the number of blocks allocated to the cache. If you are not using 90 percent of the cache, increase the number of V files (chunks). .PP By default, each V file holds up to 65,536 bytes (64 kilobytes) of a cached file; files larger than 65,536 bytes are divided among multiple V files. A V file can hold only one cached element; if a cached element is smaller than the size of a V file (the chunk size), the remaining space in the V file remains unused. .PP You can override the default chunk size with the \*Ldfsd\*O command using the \*L-chunksize\*O option. Specify an integer between 13 and 18 to be used as an exponent of 2; the unit of measure is bytes. For example, a value of 16 equals the default chunk size (2\u\s-4\&16\s0\d equals 65,536). A value less than 13 or greater than 18 sets the chunk size to the default, as does a value of 16. .SH "CAUTIONS" .PP Never directly modify or delete a V file; this can cause the kernel to panic. Always use the commands provided with DFS to alter the cache. If a V file is accidentally modified or deleted, rebooting the machine should restore normal performance. .SH "RELATED INFORMATION" .PP Commands: \*Lcm setcachesize(1m)\*O, \*Ldfsd(1m)\*O .PP Files: \*LCacheInfo(4)\*O, \*LCacheItems(4)\*O .iX "-]" "V files" "about" .iX "-]" "disk cache" "V files" .iX "-]" "cache" "V files" .iX "-]" "chunks" "V files" .\" $Header: a.out.4,v 78.1 96/02/12 13:27:30 ssa Exp $ .TA a .TH a.out 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME a.out \- assembler and link editor output .SH SYNOPSIS .C #include .SH DESCRIPTION The file name .CR a.out is the default file name for the output file from the assembler (see .IR as (1)), compilers, and the linker (see .IR ld (1)). The assembler and compilers create relocatable object files, ready for input to the linker. The linker creates executable object files and shared library files. .PP An object file consists of a file header, auxiliary headers, space dictionary, subspace dictionary, symbol table, relocation information, compiler records, space string table, symbol string table, and the data for initialized code and data. Not all of these sections are required for all object files. The file must begin with the file header, but the remaining sections do not have to be in any particular order; the file header contains pointers to each of the other sections of the file. .PP A relocatable object file, created by the assembler or compiler, must contain at least the following sections: file header, space dictionary, subspace dictionary, symbol table, relocation information, space string table, symbol string table, and code and data. It may also contain auxiliary headers and compiler records. Relocatable files generally contain unresolved symbols. The linker combines relocatable files and searches libraries to produce an executable file. The linker can also be used to combine relocatable files and produce a new relocatable file as output, suitable for input to a subsequent linker run. .PP An executable file, created by the linker, typically contains the following sections: file header, an HP-UX auxiliary header, space dictionary, subspace dictionary, symbol table, space string table, symbol string table, and code and data. The linker also copies any auxiliary headers and compiler records from the input files to the output file. If the file has been stripped (see .IR strip (1)), it will not contain a symbol table, symbol string table, or compiler records. An executable file must not contain any unresolved symbols. .PP A shared library file, created by the linker, contains the same sections found in an executable file, with additional information added to the code section of the file. This additional information contains a header, export table, import table, and dynamic relocation records to be used by the dynamic loader. .PP Programs consist of two loadable spaces: a shared, non-writable, code space named .CR $TEXT$ ; and a private, writable, data space named .CR $PRIVATE$ . A program may contain other unloadable spaces that contain data needed by development tools. For example, symbolic debugging information is contained in a space named .CR $DEBUG$ or .CR $PINFO$ . The linker treats loadable and unloadable spaces exactly the same, so the full generality of symbol resolution and relocation is available for the symbolic debugging information. .PP Spaces have an addressing range of 4,294,967,296 (2^32) bytes. Each loadable space is divided into four 1,073,741,824 (2^30) byte quadrants. The HP-UX operating system places all code in the first quadrant of the .CR $TEXT$ space, all data in the second quadrant of the .CR $PRIVATE$ space, and all shared library code in the third quadrant of shared memory space. .PP Each space is also divided into logical units called subspaces. When the linker combines relocatable object files, it groups all subspaces from the input files by name, then arranges the groups within the space by a sort key associated with each subspace. Subspaces are not architecturally significant; they merely provide a mechanism for combining individual parts of spaces independently from many input files. Some typical subspaces in a program are shown in the following table: .ne 10 .PP .TS center tab(:); lf4p+1 l. $SHLIB_INFO$:Information needed for dynamic loading $MILLICODE$:Code for millicode routines $LIT$:Sharable literals $CODE$:Code $UNWIND$:Stack unwind information $GLOBAL$:Outer block declarations for Pascal $DATA$:Static initialized data $COMMON$:FORTRAN common $BSS$:Uninitialized data .TE .PP Subspaces can be initialized or uninitialized (although typically, only .CR $BSS$ is uninitialized). The subspace dictionary entry for an initialized subspace contains a file pointer to the initialization data, while the entry for an uninitialized subspace contains only a 32-bit pattern used to initialize the entire area at load time. .PP In a relocatable file, initialized code and data often contain references to locations elsewhere in the file, and to unresolved symbols defined in other files. These references are patched at link time using the relocation information. Each entry in the relocation information (a "fixup") specifies a location within the initialized data for a subspace, and an expression that defines the actual value that should be placed at that location, relative to one or two symbols. .PP The linker summarizes the subspace dictionary in the HP-UX auxiliary header when creating an executable file. HP-UX programs contain only three separate sections: one for the code, one for initialized data, and one for uninitialized data. By convention, this auxiliary header is placed immediately following the file header. .PP When an .CR a.out file is loaded into memory for execution, three areas of memory are set up: the .CR a.out code is loaded into the first quadrant of a new, sharable space; the data (initialized followed by uninitialized) is loaded into the second quadrant of a new, private space; and a stack is created beginning at a fixed address near the middle of the second quadrant of the data space. .PP If the .CR a.out file uses shared libraries, then the dynamic loader .CR /usr/lib/dld.sl is loaded into memory and called to map into memory all shared libraries requested by the program. The shared library text is loaded into the third quadrant of the shared memory space, and the shared library data is allocated in the second quadrant of the data space. .PP The file format described here is a common format for all operating systems designed for HP's Precision Architecture. Therefore, there are some fields and structures that are not used on HP-UX or have been reserved for future use. .SS File Header The format of the file header is described by the following structure declaration from .CR . .nf .\" NOTE: lines below can be max 78 chars (. to ") to print properly in nroff .PP .C "struct header {" .C " short int system_id; /* system id */" .C " short int a_magic; /* magic number */ .C " unsigned int version_id; /* a.out format version */" .C " struct sys_clock file_time; /* timestamp */" .C " unsigned int entry_space; /* index of space containing entry point */" .C " unsigned int entry_subspace; /* subspace index of entry */" .C " unsigned int entry_offset; /* offset of entry point */" .C " unsigned int aux_header_location; /* file ptr to aux hdrs */" .C " unsigned int aux_header_size; /* sizeof aux hdrs */" .C " unsigned int som_length; /* length of object module */" .C " unsigned int presumed_dp; /* DP value assumed during compilation */" .C " unsigned int space_location; /* file ptr to space dict */" .C " unsigned int space_total; /* # of spaces */" .C " unsigned int subspace_location; /* file ptr to subsp dict */" .C " unsigned int subspace_total; /* # of subspaces */" .C " unsigned int loader_fixup_location; /* space reference array */" .C " unsigned int loader_fixup_total; /* # of space reference recs */" .C " unsigned int space_strings_location; /* file ptr to sp. strings */" .C " unsigned int space_strings_size; /* sizeof sp. strings */" .C " unsigned int init_array_location; /* location of init pointers */" .C " unsigned int init_array_total; /* # of init pointers */" .C " unsigned int compiler_location; /* file ptr to comp recs */" .C " unsigned int compiler_total; /* # of compiler recs */" .C " unsigned int symbol_location; /* file ptr to sym table */" .C " unsigned int symbol_total; /* # of symbols */" .C " unsigned int fixup_request_location; /* file ptr to fixups */" .C " unsigned int fixup_request_total; /* # of fixups */" .C " unsigned int symbol_strings_location; /* file ptr to sym strings */" .C " unsigned int symbol_strings_size; /* sizeof sym strings */" .C " unsigned int unloadable_sp_location; /* file ptr to debug info */" .C " unsigned int unloadable_sp_size; /* size of debug info */" .C " unsigned int checksum; /* header checksum */" .C "};" .fi .PP The timestamp is a two-word structure as shown below. If unused, both fields are zero. .nf .PP .C "struct sys_clock {" .C " unsigned int secs;" .C " unsigned int nanosecs;" .C "};" .fi .SS Auxiliary Headers The auxiliary headers are contained in a single contiguous area in the file, and are located by a pointer in the file header. Auxiliary headers are used for two purposes: to attach users' version and copyright strings to an object file, and to contain the information needed to load an executable program. In an executable program, the HP-UX auxiliary header must precede all other auxiliary headers. The following declarations are found in .CR . .nf .\" NOTE: lines below can be max 78 chars (. to ") to print properly in nroff .PP .C "struct aux_id {" .C " unsigned int mandatory : 1; /* linker must understand aux hdr info */" .C " unsigned int copy : 1; /* copy aux hdr without modification */" .C " unsigned int append : 1; /* merge multiple entries of same type */" .C " unsigned int ignore : 1; /* ignore aux hdr if type unknown */" .C " unsigned int reserved : 12; /* reserved */" .C " unsigned int type : 16; /* aux hdr type */" .C " unsigned int length; /* sizeof rest of aux hdr */" .C "};" .PP .C "/* Values for the aux_id.type field */" .C "#define HPUX_AUX_ID 4" .C "#define VERSION_AUX_ID 6" .C "#define COPYRIGHT_AUX_ID 9" .C "#define SHLIB_VERSION_AUX_ID 10" .PP .C "struct som_exec_auxhdr { /* HP-UX auxiliary header */" .C " struct aux_id som_auxhdr; /* aux header id */" .C " long exec_tsize; /* text size */" .C " long exec_tmem; /* start address of text */" .C " long exec_tfile; /* file ptr to text */" .C " long exec_dsize; /* data size */" .C " long exec_dmem; /* start address of data */" .C " long exec_dfile; /* file ptr to data */" .C " long exec_bsize; /* bss size */" .C " long exec_entry; /* address of entry point */" .C " long exec_flags; /* loader flags */" .C " long exec_bfill; /* bss initialization value */" .C "};" .PP .C "/* Values for exec_flags */" .C "#define TRAP_NIL_PTRS 01" .PP .C "struct user_string_aux_hdr { /* Version string auxiliary header */" .C " struct aux_id header_id; /* aux header id */" .C " unsigned int string_length; /* strlen(user_string) */" .C " char user_string[1]; /* user-defined string */" .C "};" .PP .C "struct copyright_aux_hdr { /* Copyright string auxiliary header */" .C " struct aux_id header_id; /* aux header id */" .C " unsigned int string_length; /* strlen(user_string) */" .C " char copyright[1]; /* user-defined string */" .C }; .PP .C "struct shlib_version_aux_hdr {" .C " struct aux_id header_id; /* aux header id */" .C " short version; /* version number */" .C }; .fi .SS Space Dictionary The space dictionary consists of a sequence of space records, as defined in .CR . .nf .\" NOTE: lines below can be max 78 chars (. to ") to print properly in nroff .PP .C "struct space_dictionary_record {" .C " union name_pt name; /* index to space name */" .C " unsigned int is_loadable: 1; /* space is loadable */" .C " unsigned int is_defined: 1; /* space is defined within file */" .C " unsigned int is_private: 1; /* space is not sharable */" .C " unsigned int has_intermediate_code: 1; /* contains intermediate" .C " code */" .C " unsigned int reserved: 12; /* reserved */" .C " unsigned int sort_key: 8; /* sort key for space */" .C " unsigned int reserved2: 8; /* reserved */" .C " int space_number; /* space index */" .C " int subspace_index; /* index to first subspace */" .C " unsigned int subspace_quantity; /* # of subspaces in space */" .C " int loader_fix_index; /* index into loader fixup array */" .C " unsigned int loader_fix_quantity; /* # of loader fixups in space */" .C " int init_pointer_index; /* index into init pointer array */" .C " unsigned int init_pointer_quantity; /* # of init ptrs */" .C "};" .fi .PP The strings for the space names are contained in the space strings table, which is located by a pointer in the file header. Each entry in the space strings table is preceded by a 4-byte integer that defines the length of the string, and is terminated by one to five null characters to pad the string out to a word boundary. Indices to this table are relative to the start of the table, and point to the first byte of the string (not the preceding length word). The union defined below is used for all such string pointers; the character pointer is defined for programs that read the string table into memory and wish to relocate in-memory copies of space records. .nf .PP .C "union name_pt {" .C " char *n_name;" .C " unsigned int n_strx;" .C "};" .fi .SS Subspace Dictionary The subspace dictionary consists of a sequence of subspace records, as defined in .CR . Strings for subspace names are contained in the space strings table. .nf .\" NOTE: lines below can be max 78 chars (. to ") to print properly in nroff .PP .C "struct subspace_dictionary_record {" .C " int space_index; /* index into space dictionary */" .C " unsigned int access_control_bits: 7; /* access and priv levels" .C " of subsp */" .C " unsigned int memory_resident: 1; /* lock in memory during exec */" .C " unsigned int dup_common: 1; /* duplicate data symbols allowed */" .C " unsigned int is_common: 1; /* initialized common block */" .C " unsigned int is_loadable: 1; /* subspace is loadable */" .C " unsigned int quadrant: 2; /* quadrant in space subsp" .C " should reside in */" .C " unsigned int initially_frozen: 1; /* lock in memory" .C " when OS booted */" .C " unsigned int is_first: 1; /* must be first subspace */" .C " unsigned int code_only: 1; /* subspace contains only code */" .C " unsigned int sort_key: 8; /* subspace sort key */" .C " unsigned int replicate_init: 1; /* init values to be replicated" .C " to fill subsp len */" .C " unsigned int continuation: 1; /* subspace is a continuation */" .C " unsigned int reserved: 6; /* reserved */" .C " int file_loc_init_value; /* file location or init value */" .C " unsigned int initialization_length; /* length of initialization */" .C " unsigned int subspace_start; /* starting offset */" .C " unsigned int subspace_length; /* total subspace length */" .C " unsigned int reserved2: 16; /* reserved */" .C " unsigned int alignment: 16; /* alignment required */" .C " union name_pt name; /* index of subspace name */" .C " int fixup_request_index; /* index to first fixup */" .C " unsigned int fixup_request_quantity; /* # of fixup requests */" .C "};" .fi .SS Symbol Table The symbol table consists of a sequence of entries described by the structure shown below, from .CR . Strings for symbol and qualifier names are contained in the symbol strings table, whose structure is identical with the space strings table. .nf .\" NOTE: lines below can be max 78 chars (. to ") to print properly in nroff .PP .C "struct symbol_dictionary_record {" .C " unsigned int hidden: 1; /* symbol not visible to loader */" .C " unsigned int secondary_def: 1; /* secondary def symbol */" .C " unsigned int symbol_type: 6; /* symbol type */" .C " unsigned int symbol_scope: 4; /* symbol value */" .C " unsigned int check_level: 3; /* type checking level */" .C " unsigned int must_qualify: 1; /* qualifier required */" .C " unsigned int initially_frozen: 1; /* lock in memory" .C " when OS booted */" .C " unsigned int memory_resident: 1; /* lock in memory during exec */" .C " unsigned int is_common: 1; /* common block */" .C " unsigned int dup_common: 1; /* duplicate data symbols allowed */" .C " unsigned int xleast: 2; /* MPE-only */ " .C " unsigned int arg_reloc: 10; /* parameter relocation bits */" .C " union name_pt name; /* index to symbol name */" .C " union name_pt qualifier_name; /* index to qual name */" .C " unsigned int symbol_info; /* subspace index */" .C " unsigned int symbol_value; /* symbol value */" .C "};" .PP .C /* Values for symbol_type */ .C "#define ST_NULL 0 /* unused symbol entry */" .C "#define ST_ABSOLUTE 1 /* non-relocatable symbol */" .C "#define ST_DATA 2 /* initialized data symbol */" .C "#define ST_CODE 3 /* generic code symbol */" .C "#define ST_PRI_PROG 4 /* program entry point */" .C "#define ST_SEC_PROG 5 /* secondary prog entry point*/" .C "#define ST_ENTRY 6 /* procedure entry point */" .C "#define ST_STORAGE 7 /* storage request */" .C "#define ST_STUB 8 /* MPE-only */" .C "#define ST_MODULE 9 /* Pascal module name */" .C "#define ST_SYM_EXT 10 /* symbol extension record */" .C "#define ST_ARG_EXT 11 /* argument extension record */" .C "#define ST_MILLICODE 12 /* millicode entry point */" .C "#define ST_PLABEL 13 /* MPE-only */" .C "#define ST_OCT_DIS 14 /* Used by OCT only--ptr to translated code */" .C "#define ST_MILLI_EXT 15 /* address of external millicode */" .PP .C "/* Values for symbol_scope */" .C "#define SS_UNSAT 0 /* unsatisfied reference */" .C "#define SS_EXTERNAL 1 /* import request to external symbol */" .C "#define SS_LOCAL 2 /* local symbol */" .C "#define SS_UNIVERSAL 3 /* global symbol */" .fi .PP The meaning of the symbol value depends on the symbol type. For the code symbols (generic code, program entry points, procedure and millicode entry points), the low-order two bits of the symbol value encode the execution privilege level, which is not used on HP-UX, but is generally set to 3. The symbol value with those bits masked out is the address of the symbol (which is always a multiple of 4). For data symbols, the symbol value is simply the address of the symbol. For storage requests, the symbol value is the number of bytes requested; the linker allocates space for the largest request for each symbol in the .CR $BSS$ subspaces, unless a local or universal symbol is found for that symbol (in which case the storage request is treated like an unsatisfied reference). .PP If a relocatable file is compiled with parameter type checking, extension records follow symbols that define and reference procedure entry points and global variables. The first extension record, the .IR "symbol extension record" , defines the type of the return value or global variable, and (if a procedure or function) the number of parameters and the types of the first three parameters. If more parameter type descriptors are needed, one or more .I argument extension records follow, each containing four more descriptors. A check level of 0 specifies no type checking; no extension records follow. A check level of 1 or more specifies checking of the return value or global variable type. A check level of 2 or more specifies checking of the number of parameters, and a check level of 3 specifies checking the types of each individual parameter. The linker performs the requested level of type checking between unsatisfied symbols and local or universal symbols as it resolves symbol references. .nf .\" NOTE: lines below can be max 78 chars (. to ") to print properly in nroff .PP .C "union arg_descriptor {" .C " struct { .C " unsigned int reserved: 3; /* reserved */" .C " unsigned int packing: 1; /* packing algorithm used */" .C " unsigned int alignment: 4; /* byte alignment */" .C " unsigned int mode: 4; /* type of descriptor and its use */" .C " unsigned int structure: 4; /* structure of symbol */" .C " unsigned int hash: 1; /* set if arg_type is hashed */" .C " int arg_type: 15; /* data type */" .C " } arg_desc;" .C " unsigned int word;" .C "};" .PP .C "struct symbol_extension_record {" .C " unsigned int type: 8; /* always ST_SYM_EXT */" .C " unsigned int max_num_args: 8; /* max # of parameters */" .C " unsigned int min_num_args: 8; /* min # of parameters */" .C " unsigned int num_args: 8; /* actual # of parameters */" .C " union arg_descriptor symbol_desc; /* symbol type desc. */" .C " union arg_descriptor argument_desc[3]; /* first 3 parameters */" .C "};" .PP .C "struct argument_desc_array {" .C " unsigned int type: 8; /* always ST_ARG_EXT */" .C " unsigned int reserved: 24; /* reserved */" .C " union arg_descriptor argument_desc[4]; /* next 4 parameters */" .C "};" .fi .PP The .CR alignment field in .CR arg_descriptor indicates the minimum alignment of the data, where a value of .CR n represents .RC 2^ n byte alignment. The values for the .CR mode , .CR structure , and .CR arg_type (when the data type is not hashed) fields in .CR arg_descriptor are given in the following table. .PP .ne 18 .TS center tab(:) ; cB lf4p+1 lf4p+1 lf4p+1 nf4p+1 l l l . Value:mode:structure:arg_type _ 0:any:any:any 1:value parm:scalar:void 2:reference parm:array:signed byte 3:value-result:struct:unsigned byte 4:name:pointer:signed short 5:variable:long ptr:unsigned short 6:function return:C string:signed long 7:procedure:Pascal string:unsigned long 8:long ref parm:procedure:signed dbl word 9::function:unsigned dbl word 10::label:short real 11:::real 12:::long real 13:::short complex 14:::complex 15:::long complex 16:::packed decimal 17:::struct/array .TE .PP For procedure entry points, the parameter relocation bits define the locations of the formal parameters and the return value. Normally, the first four words of the parameter list are passed in general registers .RC ( r26-r23 ) instead of on the stack, and the return value is returned in .CR r29 . Floating-point parameters in this range are passed instead in floating-point registers .RC ( fr4-fr7 ) and a floating-point value is returned in .CR fr4 . The parameter relocation bits consist of five pairs of bits that describe the first four words of the parameter list and the return value. The leftmost pair of bits describes the first parameter word, and the rightmost pair of bits describes the return value. The meanings of these bits are shown in the following table. .PP .ne 5 .TS center tab(:); cB | lB nf4p+1 | l. Bits:Meaning _ 00:No parameter or return value 01:Parameter or return value in general register 10:Parameter or return value in floating-point register 11:Double-precision floating-point value .TE .PP For double-precision floating-point parameters, the odd-numbered parameter word should be marked .CR 11 and the even-numbered parameter word should be marked .CR 10 . Double-precision return values are simply marked .CR 11 . .PP Every procedure call is tagged with a similar set of bits (see "Relocation Information" below), so that the linker can match each call with the expectations of the procedure entry point. If the call and entry point mismatch, the linker creates a stub that relocates the parameters and return value as appropriate. .SS Relocation Information Each initialized subspace defines a range of fixups that apply to the data in that subspace. A fixup request is associated with every word that requires relocation or that contains a reference to an unsatisfied symbol. In relocatable object files created prior to HP-UX Release 3.0 on Series 800 systems, each fixup request is a five-word structure describing a code or data word to be patched at link time. Object files created on Release 3.0 or later contain variable-length fixup requests that describe every byte of the subspace. The .I version_id field in the file header distinguishes these two formats; the constant .CR VERSION_ID is found in older object files, and the constant .CR NEW_VERSION_ID is found in newer ones. .PP In older object files, fixups can compute an expression involving zero, one, or two symbols and a constant, then extract a field of bits from that result and deposit those bits in any of several different formats (corresponding to the Precision Architecture instruction set). The .I fixup_request_index field in the subspace dictionary entry indexes into the fixup request area defined by the file header and the .I fixup_request_quantity field refers to the number of fixup requests used for that subspace. The structure of a fixup request is contained in .CR . .nf .\" NOTE: lines below can be max 78 chars (. to ") to print properly in nroff .PP .C "struct fixup_request_record {" .C " unsigned int need_data_ref: 1; /* reserved */" .C " unsigned int arg_reloc: 10; /* parameter relocation bits */" .C " unsigned int expression_type: 5; /* how to compute value */" .C " unsigned int exec_level: 2; /* reserved */" .C " unsigned int fixup_format: 6; /* how to deposit bits */" .C " unsigned int fixup_field: 8; /* field to extract */" .C " unsigned int subspace_offset; /* subspace offset of word */" .C " unsigned int symbol_index_one; /* index of first symbol */" .C " unsigned int symbol_index_two; /* index of second symbol */" .C " int fixup_constant; /* constant */" .C "};" .PP .C "/* Values for expression_type */" .C "#define e_one 0 /* symbol1 + constant */" .C "#define e_two 1 /* symbol1 - symbol2 + constant */" .C "#define e_pcrel 2 /* symbol1 - pc + constant */" .C "#define e_con 3 /* constant */" .C "#define e_plabel 7 /* symbol1 + constant */" .C "#define e_abs 18 /* absolute, 1st sym index is address */" .PP .C "/* Values for fixup_field (assembler mnemonics shown) */" .C "#define e_fsel 0 /* F': no change */" .C "#define e_lssel 1 /* LS': inverse of RS' */" .C "#define e_rssel 2 /* RS': rightmost 11 bits, signed */" .C "#define e_lsel 3 /* L': leftmost 21 bits */" .C "#define e_rsel 4 /* R': rightmost 11 bits */" .C "#define e_ldsel 5 /* LD': inverse of RD' */" .C "#define e_rdsel 6 /* RD': rightmost 11 bits, filled left with ones */" .C "#define e_lrsel 7 /* LR': L' with ""rounded"" constant */" .C "#define e_rrsel 8 /* RR': R' with ""rounded"" constant */" .C "#define e_nsel 9 /* N1': set all bits to zero: for id of 3-inst" .C " code gen sequence */" .\".IP .PP .C "/* Values for fixup_format (typical instructions shown) */" .C "#define i_exp14 0 /* 14-bit immediate (LDW, STW) */" .C "#define i_exp21 1 /* 21-bit immediate (LDIL, ADDIL) */" .C "#define i_exp11 2 /* 11-bit immediate (ADDI, SUBI) */" .C "#define i_rel17 3 /* 17-bit pc-relative (BL) */" .C "#define i_rel12 4 /* 12 bit pc-relative (COMBT, COMBF, etc.) */" .C "#define i_data 5 /* whole word */" .C "#define i_none 6" .C "#define i_abs17 7 /* 17-bit absolute (BE, BLE) */" .C "#define i_milli 8 /* 17-bit millicode call (BLE) */" .C "#define i_break 9 /* reserved (no effect on HP-UX) */" .fi .PP In newer object files, relocation entries consist of a stream of bytes. The .I fixup_request_index field in the subspace dictionary entry is a byte offset into the fixup dictionary defined by the file header, and the .I fixup_request_quantity field defines the length of the fixup request stream, in bytes, for that subspace. The first byte of each fixup request (the opcode) identifies the request and determines the length of the request. .PP In general, the fixup stream is a series of linker instructions that governs how the linker places data in the .CR a.out file. Certain fixup requests cause the linker to copy one or more bytes from the input subspace to the output subspace without change, while others direct the linker to relocate words or resolve external references. Still others direct the linker to insert zeroes in the output subspace or to leave areas uninitialized without copying any data from the input subspace, and others describe points in the code without contributing any new data to the output file. .PP The include file .CR defines constants for each major opcode. Many fixup requests use a range of opcodes; only a constant for the beginning of the range is defined. The meaning of each fixup request is described below. The opcode ranges and parameters for each fixup are described in the table further below. .ift .TP 25 .ifn .TP 19 .CR R_NO_RELOCATION Copy L bytes with no relocation. .TP .CR R_ZEROES Insert L zero bytes into the output subspace. .TP .CR R_UNINIT Skip L bytes in the output subspace. .TP .CR R_RELOCATION Copy one data word with relocation. The word is assumed to contain a 32-bit pointer relative to its own subspace. .TP .CR R_DATA_ONE_SYMBOL Copy one data word with relocation relative to an external symbol whose symbol index is S. .TP .CR R_DATA_PLABEL Copy one data word as a 32-bit procedure label, referring to the symbol S. The original contents of the word should be 0 (no static link) or 2 (static link required). .TP .CR R_SPACE_REF Copy one data word as a space reference. This fixup request is not currently supported. .TP .CR R_REPEATED_INIT Copy L bytes from the input subspace, replicating the data to fill M bytes in the output subspace. .TP .CR R_PCREL_CALL Copy one instruction word with relocation. The word is assumed to be a pc-relative procedure call instruction (for example, .CR BL ). The target procedure is identified by symbol S, and the parameter relocation bits are R. .TP .CR R_ABS_CALL Copy one instruction word with relocation. The word is assumed to be an absolute procedure call instruction (for example, .CR BLE ). The target procedure is identified by symbol S, and the parameter relocation bits are R. .TP .CR R_DP_RELATIVE Copy one instruction word with relocation. The word is assumed to be a dp-relative load or store instruction (for example, .CR ADDIL , .CR LDW , .CR STW ). The target symbol is identified by symbol S. The linker forms the difference between the value of the symbol S and the value of the symbol .CR $global$ . By convention, the value of .CR $global$ is always contained in register 27. Instructions may have a small constant in the displacement field of the instruction. .TP .CR R_DLT_REL Copy one instruction word with relocation. The word is assumed to be a register-18-relative load or store instruction (for example, .CR LDW , .CR LDO , .CR STW ). The target symbol is identified by symbol S. The linker computes a linkage table offset relative to register 18 (reserved for a linkage table pointer in position-independent code) for the symbol S. .TP .CR R_CODE_ONE_SYMBOL Copy one instruction word with relocation. The word is assumed to be an instruction referring to symbol S (for example, .CR LDIL , .CR LDW , .CR BE ). Instructions may have a small constant in the displacement field of the instruction. .TP .CR R_MILLI_REL Copy one instruction word with relocation. The word is assumed to be a short millicode call instruction (for example, .CR BLE ). The linker forms the difference between the value of the target symbol S and the value of symbol 1 in the module's symbol table. By convention, the value of symbol 1 should have been previously loaded into the base register used in the BLE instruction. The instruction may have a small constant in the displacement field of the instruction. .TP .CR R_CODE_PLABEL Copy one instruction word with relocation. The word is assumed to be part of a code sequence forming a procedure label (for example, .CR LDIL , .CR LDO ), referring to symbol S. The .CR LDO instruction should contain the value 0 (no static link) or 2 (static link required) in its displacement field. .TP .CR R_BREAKPOINT Copy one instruction word conditionally. On HP-UX, the linker always replaces the word with a .CR NOP instruction. .TP .CR R_ENTRY Define a procedure entry point. The stack unwind bits, U, and the frame size, F, are recorded in a stack unwind descriptor. .TP .CR R_ALT_ENTRY Define an alternate procedure entry point. .TP .CR R_EXIT Define a procedure exit point. .TP .CR R_BEGIN_TRY Define the beginning of a try/recover region. .TP .CR R_END_TRY Define the end of a try/recover region. The offset R defines the distance in bytes from the end of the region to the beginning of the recover block. .TP .CR R_BEGIN_BRTAB Define the beginning of a branch table. .TP .CR R_END_BRTAB Define the end of a branch table. .TP .CR R_AUX_UNWIND Define an auxiliary unwind table. .CR CN is a symbol index of the symbol that labels the beginning of the compilation unit string table. .CR SN is the offset, relative to the .CR CN symbol, of the scope name string. .CR SK is an integer specifying the scope kind. .TP .CR R_STATEMENT Define the beginning of statement number N. .TP .CR R_SEC_STATEMENT Define the beginning of a secondary statement number N. .TP .CR R_DATA_EXPR Pop one word from the expression stack and copy one data word from the input subspace to the output subspace, adding the popped value to it. .TP .CR R_CODE_EXPR Pop one word from the expression stack, and copy one instruction word from the input subspace to the output subspace, adding the popped value to the displacement field of the instruction. .TP .CR R_FSEL Use an F\(fm field selector for the next fixup request instead of the default appropriate for the instruction. .TP .CR R_LSEL Use an L-class field selector for the next fixup request instead of the default appropriate for the instruction. Depending on the current rounding mode, L\(fm, LS\(fm, LD\(fm, or LR\(fm may be used. .TP .CR R_RSEL Use an R-class field selector for the next fixup request instead of the default appropriate for the instruction. Depending on the current rounding mode, R\(fm, RS\(fm, RD\(fm, or RR\(fm may be used. .TP .CR R_N_MODE Select round-down mode (L\(fm/R\(fm). This is the default mode at the beginning of each subspace. This setting remains in effect until explicitly changed or until the end of the subspace. .TP .CR R_S_MODE Select round-to-nearest-page mode (LS\(fm/RS\(fm). This setting remains in effect until explicitly changed or until the end of the subspace. .TP .CR R_D_MODE Select round-up mode (LD\(fm/RD\(fm). This setting remains in effect until explicitly changed or until the end of the subspace. .TP .CR R_R_MODE Select round-down-with-adjusted-constant mode (LR\(fm/RR\(fm). This setting remains in effect until explicitly changed or until the end of the subspace. .TP .CR R_DATA_OVERRIDE Use the constant V for the next fixup request in place of the constant from the data word or instruction in the input subspace. .TP .CR R_TRANSLATED Toggle "translated" mode. This fixup request is generated only by the linker during a relocatable link to indicate a subspace that was originally read from an old-format relocatable object file. .TP .CR R_COMP1 Stack operations. The second byte of this fixup request contains a secondary opcode. In the descriptions below, A refers to the top of the stack and B refers to the next item on the stack. All items on the stack are considered signed 32-bit integers. .RS .ifn .TP 16 .ift .TP 25 .PD 0 .CR R_PUSH_PCON1 Push the (positive) constant V. .TP .CR R_PUSH_DOT Push the current virtual address. .TP .CR R_MAX Pop A and B, then push max(A, B). .TP .CR R_MIN Pop A and B, then push min(A, B). .TP .CR R_ADD Pop A and B, then push A + B. .TP .CR R_SUB Pop A and B, then push B \(mi A. .TP .CR R_MULT Pop A and B, then push A * B. .TP .CR R_DIV Pop A and B, then push B / A. .TP .CR R_MOD Pop A and B, then push B % A. .TP .CR R_AND Pop A and B, then push A & B. .TP .CR R_OR Pop A and B, then push A | B. .TP .CR R_XOR Pop A and B, then push A XOR B. .TP .CR R_NOT Replace A with its complement. .TP .CR R_LSHIFT If C = 0, pop A and B, then push B << A. Otherwise, replace A with A << C. .TP .CR R_ARITH_RSHIFT If C = 0, pop A and B, then push B >> A. Otherwise, replace A with A >> C. The shifting is done with sign extension. .TP .CR R_LOGIC_RSHIFT If C = 0, pop A and B, then push B >> A. Otherwise, replace A with A >> C. The shifting is done with zero fill. .TP .CR R_PUSH_NCON1 Push the (negative) constant V. .PD .RE .TP .CR R_COMP2 More stack operations. .RS .ifn .TP 16 .ift .TP 25 .PD 0 .CR R_PUSH_PCON2 Push the (positive) constant V. .TP .CR R_PUSH_SYM Push the value of the symbol S. .TP .CR R_PUSH_PLABEL Push the value of a procedure label for symbol S. The static link bit is L. .TP .CR R_PUSH_NCON2 Push the (negative) constant V. .PD .RE .TP .CR R_COMP3 More stack operations. .RS .ifn .TP 16 .ift .TP 25 .PD 0 .CR R_PUSH_PROC Push the value of the procedure entry point S. The parameter relocation bits are R. .TP .CR R_PUSH_CONST Push the constant V. .PD .RE .TP .CR R_PREV_FIXUP The linker keeps a queue of the last four unique multi-byte fixup requests. This is an abbreviation for a fixup request identical to one on the queue. The queue index X references one of the four; X = 0 refers to the most recent. As a side effect of this fixup request, the referenced fixup is moved to the front of the queue. .TP .CR R_N0SEL Indicates that the following fixup is applied to the first of a three-instruction sequence to access data, generated by the compilers to enable the importing of shared library data. .TP .CR R_N1SEL Uses a (N\(fm) field selector for the next fixup request. This indicates that zero bits are to be used for the displacement on the instruction. This fixup is used to identify three-instruction sequences to access data (for importing shared library data). .TP .CR R_LINETAB Defines the beginning of a line table. CU is a symbol index of the symbol that labels the beginning of the line table. SM is the offset relative to the CU symbol. ES designates the version information for the current line table. .TP .CR R_LINETAB_ESC Defines an escape entry to be entered into the line table. ES designates the escape entry entered in the table. M designates the number of R_STATEMENT fixups to be interpreted as raw 8-bit table data. .TP .CR R_LTP_OVERRIDE Override the following fixup, which is expected to be a R_DATA_ONE_SYMBOL fixup to copy one data word without relocation when building a shared library. The absolute byte offset of the symbol relative to the linkage table pointer is copied. If the linker is building a complete executable, the absolute virtual address is copied. .TP .CR R_COMMENT Fixup used to pass comment information from the compiler to the linker. This fixup has a 5 byte argument that can be skipped and ignored by applications. .TP .CR R_RESERVED Fixups in this range are reserved for internal use by the compilers and linker. .PP The following table shows the mnemonic fixup request type and length and parameter information for each range of opcodes. In the parameters column, the symbol D refers to the difference between the opcode and the beginning of the range described by that table entry; the symbols B1, B2, B3, and B4 refer to the value of the next one, two, three, or four bytes of the fixup request, respectively. .PP .ne 15 .TS center tab(:); lB cB cB lB lf4p+1 c n lf4p+1. Mnemonic:Opcodes:Length:Parameters _ R_NO_RELOCATION:\00-23:1:L = (D+1) * 4 :24-27:2:L = (D<<8 + B1 + 1) * 4 :28-30:3:L = (D<<16 + B2 + 1) * 4 :31:4:L = B3 + 1 R_ZEROES:32:2:L = (B1 + 1) * 4 :33:4:L = B3 + 1 R_UNINIT:34:2:L = (B1 + 1) * 4 :35:4:L = B3 + 1 R_RELOCATION:36:1:\f1\s-1none\s0 R_DATA_ONE_SYMBOL:37:2:S = B1 :38:4:S = B3 R_DATA_PLABEL:39:2:S = B1 :40:4:S = B3 R_SPACE_REF:41:1:\f1\s-1none\s0 R_REPEATED_INIT:42:2:L = 4; M = (B1 + 1) * 4 :43:3:L = (B1 + 1) * 4; M = (B1 + 1) * L :44:5:L = (B1 + 1) * 4; M = (B3 + 1) * 4 :45:8:L = B3 + 1; M = B4 + 1 R_PCREL_CALL:48\-57:2:R = rbits1(D); S = B1 :58\-59:3:R = rbits2(D<<8 + B1); S = B1 :60\-61:5:R = rbits2(D<<8 + B1); S = B3 R_ABS_CALL:64\-73:2:R = rbits1(D); S = B1 :74\-75:3:R = rbits2(D<<8 + B1); S = B1 :76\-77:5:R = rbits2(D<<8 + B1); S = B3 R_DP_RELATIVE:\080\-111:1:S = D :112:2:S = B1 :113:4:S = B3 R_DLT_REL:120:2:S = B1 :121:4:S = B3 R_CODE_ONE_SYMBOL:128\-159:1:S = D :160:2:S = B1 :161:4:S = B3 R_MILLI_REL:174:2:S = B1 :175:4:S = B3 R_CODE_PLABEL:176:2:S = B1 :177:4:S = B3 R_BREAKPOINT:178:1:\f1\s-1none\s0 R_ENTRY:179:9:U,F = B8 \f1\s-1(U is 37 bits; F is 27 bits)\s0 :180:6:U = B5 >> 3; F = pop A R_ALT_ENTRY:181:1:\f1\s-1none\s0 R_EXIT:182:1:\f1\s-1none\s0 R_BEGIN_TRY:183:1:\f1\s-1none\s0 R_END_TRY:184:1:R = 0 :185:2:R = sign_extend(B1) * 4 :186:4:R = sign_extend(B3) * 4 R_BEGIN_BRTAB:187:1:\f1\s-1none\s0 R_END_BRTAB:188:1:\f1\s-1none\s0 R_STATEMENT:189:2:N = B1 :190:3:N = B2 :191:4:N = B3 R_DATA_EXPR:192:1:\f1\s-1none\s0 R_CODE_EXPR:193:1:\f1\s-1none\s0 R_FSEL:194:1:\f1\s-1none\s0 R_LSEL:195:1:\f1\s-1none\s0 R_RSEL:196:1:\f1\s-1none\s0 R_N_MODE:197:1:\f1\s-1none\s0 R_S_MODE:198:1:\f1\s-1none\s0 R_D_MODE:199:1:\f1\s-1none\s0 R_R_MODE:200:1:\f1\s-1none\s0 R_DATA_OVERRIDE:201:1:V = 0 :202:2:V = sign_extend(B1) :203:3:V = sign_extend(B2) :204:4:V = sign_extend(B3) :205:5:V = B4 R_TRANSLATED:206:1:\f1\s-1none\s0 R_AUX_UNWIND:207:12:CU,SN,SK = B11 \f1\s-1(CU is 24 bits;\s0 :::\f1\s-1SN is 32 bits; SK is 32 bits)\s0 R_COMP1:208:2:OP = B1; V = OP & 0x3f; C = OP & 0x1f R_COMP2:209:5:OP = B1; S = B3; L = OP & 1; :::V = ((OP & 0x7f) << 24) | S R_COMP3:210:6:OP = B1; V = B4; :::R = ((OP & 1) << 8) | (V >> 16); :::S = V & 0xffffff R_PREV_FIXUP:211\-214:1:X = D R_N0SEL:216:1:\f1\s-1none\s0 R_N1SEL:217:1:\f1\s-1none\s0 R_SEC_STMT:215:1:\f1\s-1none\s0 R_LINETAB:218:9:ES = B1; CU = B3; SM = B4 R_LINETAB_ESC:219:3:ES = B1; M = B1 R_LTP_OVERRIDE:220:1:\f1\s-1none\s0 R_COMMENT:221:6:OP = B1; V = B2 to B6 R_RESERVED:224\-255::\f1\s-1reserved\s0 .TE .PP Parameter relocation bits are encoded in the fixup requests in two ways, noted as .I rbits1 and .I rbits2 in the above table. .PP The first encoding recognizes that the most common procedure calls have only general register arguments with no holes in the parameter list. The encoding for such calls is simply the number of parameters in general registers (0 to 4), plus 5 if there is a return value in a general register. .PP The second encoding is more complex. The 10 argument relocation bits are compressed into 9 bits by eliminating some impossible combinations. The encoding is the combination of three contributions. The first contribution is the pair of bits for the return value, which are not modified. The second contribution is 9 if the first two parameter words together form a double-precision parameter; otherwise, it is 3 times the pair of bits for the first word plus the pair of bits for the second word. Similarly, the third contribution is formed based on the third and fourth parameter words. The second contribution is multiplied by 40, the third is multiplied by 4, then the three are added together. .SS Compiler Records Compiler records are placed in relocatable files by each compiler or assembler to identify the version of the compiler that was used to produce the file. These records are copied into the executable file by the linker, but are strippable. The structure of a compiler record is shown below. All strings are contained in the symbol string table. .PP The format of the compilation record is described by the following structure declaration from .CR . .nf .\" NOTE: lines below can be max 78 chars (. to ") to print properly in nroff .PP .C struct compilation_unit { .C " union name_pt name; /* entry name */" .C " union name_pt language_name; /* language used */" .C " union name_pt product_id; /* compiler ID */" .C " union name_pt version_id; /* compiler version */" .C " unsigned int reserved: 31; /* reserved */" .C " unsigned int chunk_flag: 1; /* MPE-only */" .C " struct sys_clock compile_time; /* time file was compiled */" .C " struct sys_clock source_time; /* time file was last modified */" .C }; .fi .SH FILES .nf .CR .CR .CR .CR .CR .CR .CR .CR .fi .SH SEE ALSO .SS System Tools .TP 10 .PD 0 as(1) Translate assembly code to machine code .TP cc(1) Invoke the HP-UX C compiler .TP ld(1) Invoke the link editor .PD .SS Miscellaneous .TP 10 .PD 0 crt0(3) Execution startup routine .TP end(3C) Symbol of the last locations in program .TP magic(4) Magic number for HP-UX implementations .TP nm(1) Print name list of object file .TP strip(1) Strip symbol and line number information from an object file .PD .\" .\" index@\f4a.out\f1 \- assembler and link editor output format@@@\f3a.out(4)\f1 .\" index@assembler and link editor output format@@@\f3a.out(4)\f1 .\" index@link editor and assembler output format@@@\f3a.out(4)\f1 .\" index@output format, link editor and assembler@@@\f3a.out(4)\f1 .\" index@object file, link editor and assembler@@@\f3a.out(4)\f1 .\" index@library file, link editor and assembler@@@\f3a.out(4)\f1 .\" .\" toc@\f3a.out(4)\f1:\0\0\f4a.out\f1@@@assembler and link editor output .\" $Header: acct.4,v 78.2 96/01/23 11:15:41 ssa Exp $ .TA a .TH acct 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME acct \- per-process accounting file format .SH SYNOPSIS .C #include .SH DESCRIPTION Files produced as a result of calling .C acct() (see .IR acct (2)) have records in the form defined by .CR , whose contents are: .PP .nf .ift .ft 4 .ifn .ft 3 .ps +1 typedef ushort comp_t; /* "floating point": 13-bit fraction, 3-bit exponent */ struct acct { char ac_flag; /* Accounting flag */ char ac_stat; /* Exit status */ uid_t ac_uid; /* Accounting user ID */ gid_t ac_gid; /* Accounting group ID */ dev_t ac_tty; /* control typewriter */ time_t ac_btime; /* Beginning time */ comp_t ac_utime; /* acctng user time in clock ticks */ comp_t ac_stime; /* acctng system time in clock ticks */ comp_t ac_etime; /* acctng elapsed time in clock ticks */ comp_t ac_mem; /* memory usage in clicks */ comp_t ac_io; /* chars trnsfrd by read/write */ comp_t ac_rw; /* number of block reads/writes */ char ac_comm[8]; /* command name */ }; #define AFORK 01 /* has executed fork, but no exec */ #define ASU 02 /* used super-user privileges */ #define ACCTF 0300 /* record type: 00 = acct */ .ft .ps .fi .PP In .CR ac_flag , the .C AFORK flag is turned on by each .C fork() and turned off by an .C exec() (see .IR fork (2) and .IR exec (2)). The .C ac_comm field is inherited from the parent process and is reset by any .CR exec() . Each time the system charges the process with a clock tick, it also adds to .C ac_mem the current process size, computed as follows: .IP (data size) + (text size) + (number of in-core processes sharing text) + .br sum of ((shared memory segment size) / (number of in-core processes attached to segment)) .RE .PP For systems with virtual memory, the text, data, and shared memory sizes refer to the resident portion of the memory segments. The value of .CR ac_mem \|/\|( ac_stime + ac_utime ) can be viewed as an approximation to the mean process size, as modified by text-sharing. .PP The .C tacct structure, which resides with the source files of the accounting commands, represents the total accounting format used by the various accounting commands: .nf .IP .C /* .C "* total accounting (for acct period), also for day" .C */ .C struct tacct { .C " uid_t ta_uid; /* userid */ .C " char ta_name[8]; /* login name */ .C " float ta_cpu[2]; /* cum. cpu time, p/np (mins) */ .C " float ta_kcore[2]; /* cum kcore-minutes, p/np */ .C " float ta_con[2]; /* cum. connect time, p/np, mins */ .C " float ta_du; /* cum. disk usage */ .C " long ta_pc; /* count of processes */ .C " unsigned short ta_sc; /* count of login sessions */ .C " unsigned short ta_dc; /* count of disk samples */ .C " short ta_fee; /* fee for special services */ .C }; .fi .SH SEE ALSO acct(2), acct(1M), acctcom(1M), exec(2), fork(2). .SH WARNINGS The .C ac_mem value for a short-lived command gives little information about the actual size of the command because .C ac_mem can be incremented while a different command (such as the shell) is being executed by the process. .PP Kernel internal structures may change from release to release without warning. Applications directly relying on these structures are not supported. .SH STANDARDS CONFORMANCE .CR acct ": SVID2, SVID3, XPG2" .\" .\" index@\f4acct\fP \- per-process accounting file format@@@\f3acct(4)\f1 .\" index@accounting: per-process accounting file format@@@\f3acct(4)\f1 .\" index@per-process accounting file format@@@\f3acct(4)\f1 .\" index@file format: per-process accounting files@@@\f3acct(4)\f1 .\" index@format: per-process accounting files@@@\f3acct(4)\f1 .\" .\" toc@\f3acct(4)\f1:\0\0\f4acct\fP@@@per-process accounting file format .\" .\" fileset_database@acct.4 SYS-ADMIN-MAN .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the .\" src directory for the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "admin.bos" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Ladmin.bos\*O file" .iX "-[" "BOS Server" "administrative list" .SH NAME .PP \*Ladmin.bos\*O \- Contains the administrative list for the Basic OverSeer (BOS) Server .SH "DESCRIPTION" .PP The \*Ladmin.bos\*O file is an administrative list of all users and groups that can use the Basic OverSeer Server (BOS Server) to manage server processes on a server machine. The \*Ladmin.bos\*O file usually includes the UUIDs of users and groups only; it is not necessary to add a server machine to the \*Ladmin.bos\*O file. .PP The BOS server, or \*Lbosserver\*O process, runs on every DFS server machine in a domain. An \*Ladmin.bos\*O file must reside on each machine running the \*Lbosserver\*O process. .PP A user must be represented in the \*Ladmin.bos\*O file on a machine (either directly or indirectly, through a group) to issue commands that affect the server processes on that machine (for example, to create, start, or stop processes). Because system administrators listed in the \*Ladmin.bos\*O file can issue \*Lbos\*O commands, they can cause DFS server processes to run with DFS authorization checking disabled. Because inclusion in the \*Ladmin.bos\*O file gives an administrator such additional privileges, the administrators listed in the \*Ladmin.bos\*O file are usually a subset of the users in the administrative lists for a server machine or domain. .PP Each time the BOS Server is started on any machine, it automatically creates the \*Edcelocal\*L/var/dfs/admin.bos\*O file if the file does not already exist. Once the file exists, principals and groups can be added to it with the \*Lbos addadmin\*O command, and they can be removed from it with the \*Lbos rmadmin\*O command. The \*Lbos lsadmin\*O command can be used to list the principals and groups currently in the file. Because administrative lists are stored as binary files, you must use these commands to modify them; you cannot edit them directly. .PP The \*Ladmin.bos\*O file should be stored in the directory named \*Edcelocal\*L/var/dfs\*O on each server machine. If it is stored in a different directory, the full pathname of the file must be specified when the BOS Server is started. Do not create multiple copies of the \*Ladmin.bos\*O file and store them in different directories on the same machine; unauthorized users may be able to use the extraneous copies to access the BOS Server. .PP It is recommended that a single version of the \*Ladmin.bos\*O file be created and maintained on a domain System Control machine. The \*Lupclient\*O processes running on the domain's server machines can then reference the file via the \*Lupserver\*O process running on the System Control machine. .PP Independent versions of the \*Ladmin.bos\*O file should not be maintained on each server machine in a domain. Doing so may result in a system administrator being permitted to manage processes on one machine but not on another. .PP .zA "defect,7219,R1.0.2,Review comments" (Note that a Private File Server machine might have a separate \*Ladmin.bos\*O file. The administrative users included in such a file would represent a superset of the administrative users listed in the domain's \*Ladmin.bos\*O file, the additional members being the users who are to administer the Private File Server machine.) .zZ "defect,7219,R1.0.2,Review comments" .SH "RELATED INFORMATION" .PP Commands: \*Lbos addadmin(1m)\*O, \*Lbos lsadmin(1m)\*O, \*Lbos rmadmin(1m)\*O, \*Lbosserver(1m)\*O .iX "-]" "\*Ladmin.bos\*O file" .iX "-]" "BOS Server" "administrative list" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the .\" src directory for the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "admin.fl" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Ladmin.fl\*O file" .iX "-[" "Fileset Location Server" "administrative list" .SH NAME .PP \*Ladmin.fl\*O \- Contains the administrative list for the Fileset Location (FL) Server .SH "DESCRIPTION" .PP .zA "defect,9472,R1.1,Add admin list requirement to Ubik" The \*Ladmin.fl\*O file is an administrative list of all users and groups that can use the Fileset Location (FL) Server to modify the Fileset Location Database (FLDB). A master copy of the FLDB resides on one server machine; other server machines (usually two) house replicated copies of the database. Any machine that houses a copy of the FLDB is referred to as a Fileset Database machine. The FL Server, or \*Lflserver\*O process, must run on all Fileset Database machines. .PP An \*Ladmin.fl\*O file must reside on each Fileset Database machine. For the most part, the \*Ladmin.fl\*O file contains the UUIDs of users and groups. However, it must also contain the abbreviated DFS server principals of all Fileset Database machines in the local cell to allow the synchronization site for the FLDB to distribute changes to the secondary sites. The server principals can be present as members of a group included in the list. .zZ "defect,9472,R1.1,Add admin list requirement to Ubik" .PP Each time the Fileset Location Server is started on any machine, it automatically creates the \*Vdcelocal\*L/var/dfs/admin.fl\*O file if the file does not already exist. You can also create the file by including the \*L-createlist\*O option with the \*Lbos addadmin\*O command. Once the \*Ladmin.fl\*O file exists, principals and groups can be added to it with the \*Lbos addadmin\*O command, and they can be removed from it with the \*Lbos rmadmin\*O command. The \*Lbos lsadmin\*O command can be used to list the principals and groups currently in the file. Because administrative lists are stored as binary files, you must use these commands to modify them; you cannot edit them directly. .PP The \*Ladmin.fl\*O file should be stored in the directory named \*Vdcelocal\*L/var/dfs\*O on each Fileset Database machine. If it is stored in a different directory, the full pathname of the file must be specified when the FL Server is started. Do not create multiple copies of the \*Ladmin.fl\*O file and store them in different directories on the same machine; unauthorized users may be able to use the extraneous copies to access the FLDB. .PP A single version of the \*Ladmin.fl\*O file should be created and maintained on a System Control machine. The \*Lupclient\*O processes running on the cell's Fileset Database machines can then update their local copies of the file via the \*Lupserver\*O process running on the System Control machine. .PP Independent versions of the \*Ladmin.fl\*O file should not be maintained on each Fileset Database machine in a cell. Because the FLDB is a Ubik database, any of the secondary sites may be obliged to assume the role of synchronization site for the FLDB at any time. A system administrator listed in the \*Ladmin.fl\*O file on the machine housing the former synchronization site may not be listed in the \*Ladmin.fl\*O file on the machine housing the new synchronization site. The administrator, who could issue commands that affect the FLDB on the former machine, may not be able to issue commands that affect the database on the new machine, or vice versa. .SH "RELATED INFORMATION" .PP Commands: \*Lbos addadmin(1m)\*O, \*Lbos lsadmin(1m)\*O, \*Lbos rmadmin(1m)\*O, \*Lflserver(1m)\*O .iX "-]" "\*Ladmin.fl\*O file" .iX "-]" "Fileset Location Server" "administrative list" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the .\" src directory for the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "admin.ft" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Ladmin.ft\*O file" .iX "-[" "Fileset Server" "administrative list" .SH NAME .PP \*Ladmin.ft\*O \- Contains the administrative list for the Fileset Server .SH "DESCRIPTION" .PP The \*Ladmin.ft\*O file is an administrative list of all principals and groups that can use the Fileset Server to manipulate filesets on a File Server machine. The \*Ladmin.ft\*O file includes the UUIDs of users and groups who can issue commands that affect a machine's filesets; it includes the UUIDs of servers the machine can accept filesets from. .PP A File Server machine is defined as any machine that exports data for use in the global namespace. The Fileset Server, or \*Lftserver\*O process, runs on every File Server machine in a domain. The \*Lftserver\*O process provides the interface for any commands that affect filesets on a File Server machine. An \*Ladmin.ft\*O file must reside on each machine running the \*Lftserver\*O process. .PP A user must be represented in the \*Ladmin.ft\*O file on a machine (either directly or indirectly, through a group) to issue commands that affect the filesets on a machine (for example, to create, move, delete, back up, or restore a fileset). The user must also be listed in the file to move filesets onto the machine from a different machine. In addition, the principal name for a server machine must be included in the \*Ladmin.ft\*O file on another machine if filesets are to be moved from it to the other machine. .PP Each time the Fileset Server is started on any machine, it automatically creates the \*Edcelocal\*L/var/dfs/admin.ft\*O file if the file does not already exist. You can also create the file by including the \*L-createlist\*O option with the \*Lbos addadmin\*O command. .PP Once the \*Ladmin.ft\*O file exists, principals and groups can be added to it with the \*Lbos addadmin\*O command, and they can be removed from it with the \*Lbos rmadmin\*O command. The \*Lbos lsadmin\*O command can be used to list the principals and groups currently in the file. Because administrative lists are stored as binary files, you must use these commands to modify them; you cannot edit them directly. .PP The \*Ladmin.ft\*O file should be stored in the directory named \*Edcelocal\*L/var/dfs\*O on each File Server machine. If it is stored in a different directory, the full pathname of the file must be specified when the Fileset Server is started. Do not create multiple copies of the \*Ladmin.ft\*O file and store them in different directories on the same machine; unauthorized users may be able to use the extraneous copies to access the Fileset Server or to allow the File Server machine to accept filesets from unprivileged machines. .PP It is recommended that a single version of the \*Ladmin.ft\*O file be created and maintained on a domain's System Control machine. The \*Lupclient\*O processes running on the domain's File Server machines can then reference the file via the \*Lupserver\*O process running on the System Control machine. .PP Independent versions of the \*Ladmin.ft\*O file should not be maintained on each File Server machine in a domain. Doing so may result in a system administrator being permitted to manipulate filesets on one machine but not on another, or it may result in the administrator being able to move filesets among only some of the machines in the domain. .PP .zA "defect,7219,R1.0.2,Review comments" (Note that a Private File Server machine might have a separate \*Ladmin.ft\*O file. The administrative users included in such a file would represent a superset of the administrative users listed in the domain's \*Ladmin.ft\*O file, the additional members being the users who are to administer the Private File Server machine.) .zZ "defect,7219,R1.0.2,Review comments" .SH "RELATED INFORMATION" .PP Commands: \*Lbos addadmin(1m)\*O, \*Lbos lsadmin(1m)\*O, \*Lbos rmadmin(1m)\*O, \*Lftserver(1m)\*O .iX "-]" "\*Ladmin.ft\*O file" .iX "-]" "Fileset Server" "administrative list" .\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" .\" COPYRIGHT NOTICE .\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation .\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the .\" src directory for the full copyright text. .\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "admin.up" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "\*Ladmin.up\*O file" .iX "-[" "Update Server" "administrative list" .SH NAME .PP \*Ladmin.up\*O \- Contains the administrative list for the Update Server .SH "DESCRIPTION" .PP The \*Ladmin.up\*O file is an administrative list of all server principals that can receive copies of files using the Update Server. The \*Ladmin.up\*O file usually contains the UUIDs of server machines only; it is not necessary to add users or groups to the \*Ladmin.up\*O file. .PP The Update Server distributes files such as common configuration files, binary files, and administrative lists from System Control and Binary Distribution machines to the other server machines in a domain. Server machines that rely on System Control and Binary Distribution machines for these kinds of files run the \*Lupclient\*O process, the client portion of the Update Server. System Control and Binary Distribution machines run the \*Lupserver\*O process, the server portion of the Update Server. .PP Each instance of the \*Lupclient\*O process frequently checks with the \*Lupserver\*O process on the System Control and Binary Distribution machines to ensure that its local copies of the proper files are current. If newer versions of the files exist, the \*Lupclient\*O process retrieves them from the \*Lupserver\*O process and installs them in place of the outdated versions of the files. The \*Ladmin.up\*O file resides on machines running the \*Lupserver\*O process; it specifies the machines whose \*Lupclient\*O processes are permitted to obtain copies of files from the \*Lupserver\*O process. .PP Each time the \*Lupserver\*O process is started on any machine, it automatically creates the \*Edcelocal\*L/var/dfs/admin.up\*O file if the file does not already exist. You can also create the file by including the \*L-createlist\*O option with the \*Lbos addadmin\*O command. .PP Once the \*Ladmin.up\*O file exists, principals can be added to it with the \*Lbos addadmin\*O command, and they can be removed from it with the \*Lbos rmadmin\*O command. The \*Lbos lsadmin\*O command can be used to list the principals currently in the file. Because administrative lists are stored as binary files, you must use these commands to modify them; you cannot edit them directly. .PP The \*Ladmin.up\*O file should be stored in the directory named \*Edcelocal\*L/var/dfs\*O on each machine running the \*Lupserver\*O portion of the Update Server. If it is stored in a different directory, the full pathname of the file must be specified when the \*Lupserver\*O process is started. Do not create multiple copies of the \*Ladmin.up\*O file and store them in different directories; unauthorized users may be able to use the extraneous copies to have the \*Lupserver\*O process allow unprivileged machines to obtain copies of files. .SH "RELATED INFORMATION" .PP Commands: \*Lbos addadmin(1m)\*O, \*Lbos lsadmin(1m)\*O, \*Lbos rmadmin(1m)\*O, \*Lupclient(1m)\*O, \*Lupserver(1m)\*O .iX "-]" "\*Ladmin.up\*O file" .iX "-]" "administrative lists" "DFS servers" .iX "-]" "Update Server" "administrative list" .\" $Header: ar.4,v 74.1 95/03/23 17:44:19 ssa Exp $ .TA a .TH ar 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ar \- common archive file format .SH SYNOPSIS .B #include .SH DESCRIPTION The .C ar command is used to concatenate several files into an archive file (see .IR ar (1)). Archives are used mainly as libraries to be searched by the link editor (see .IR ld (1)). .PP Each archive begins with the archive magic string. .PP .ift .ft 4 .ifn .ft 3 .ps +1 .nf #define ARMAG "!\en" /* magic string */ #define SARMAG 8 /* length of magic string */ .ft .ps .fi .PP Following the archive magic string are the archive file members. Each file member is preceded by a file member header which is of the following format: .PP .ift .ft 4 .ifn .ft 3 .nf #define ARFMAG "\`\en" /* header trailer string */ #define AR_NAME_LEN 16 /* ar_name size, includes `/' */ struct ar_hdr /* archive file member header - printable ascii */ { char ar_name[16]; /* file member name - `/' terminated */ char ar_date[12]; /* file member date - decimal */ char ar_uid[6]; /* file member user id - decimal */ char ar_gid[6]; /* file member group id - decimal */ char ar_mode[8]; /* file member mode - octal */ char ar_size[10]; /* file member size - decimal */ char ar_fmag[2]; /* ARFMAG - string to end header */ }; .ft .fi .PP All information in the file member headers is in printable .SM ASCII. The numeric information contained in the headers is stored as decimal numbers (except for .C ar_mode which is in octal). Thus, if the archive contains printable files, the archive itself is printable. .PP The contents of the .C ar_name field are slash .RC ( / ) terminated and blank-padded. The .C ar_date field is the modification date of the file at the time of its insertion into the archive. Common format archives can be moved from system to system as long as the portable archive command .C ar is used. Note that older versions of .C ar did not use the common archive format, and those archives cannot be read or written by the common archiver. .PP Each archive file member begins on an even byte boundary; a new-line character is inserted between files if necessary. Nevertheless, the size given reflects the actual size of the file exclusive of padding. .PP Notice there is no provision for empty areas in an archive file. If the archive symbol table exists, the first file in the archive has a zero-length name (i.e., .CR "ar_name[0] == '/'" and .CR "ar_name[1] == '\ '"). The contents of this archive member are machine-dependent. Refer to the appropriate .IR a.out (4) manual entry for more information. .PP Each archive which contains object files (see .IR a.out (4)) may include an archive symbol table. This symbol table is used by the link editor (see .IR ld (1)) to determine which archive members must be loaded during the link edit process. The archive symbol table (if it exists) is always the first member in the archive (but is never listed) and is automatically created and/or updated by .CR ar . .PP If a member with a file name greater than 15 bytes exists within the archive, then the archive will also contain an additional special member to store the long file name string table. The special string table member has a zero length name where .CR "ar_name[0] == '/'" and .CR "ar_name[1] == '/'" . .PP If a special string table exists, it will precede all non-special archive members. If both a symbol table member and a string table member exist then the symbol table member will always precede the string table member. .PP Each entry in the string table is followed by a slash and a new-line character. The offset of the table begins at zero. If an archive member name exceeds 15 bytes, then the .C ar_name entry in the member's header does not contain a name, instead it contains the offset into the string table preceded by a slash. .PP For example, the member name .C thisverylongfilename.o contains .C "/0" in the .C ar_name field. This value represents the offset into the string table. The member name .C yetanotherlongfilename.o contains .C "/27" in the .C ar_name field. The long name string table would have the following format: .sp 2 .TS center,tab(@); r c c c c c c c c c c r c c c c c c c c c c r|c|c|c|c|c|c|c|c|c|c| r|c|c|c|c|c|c|c|c|c|c| r|c|c|c|c|c|c|c|c|c|c| r|c|c|c|c|c|c|c|c|c|c| r|c|c|c|c|c|c|c|c|c|c| r|c|c|c|c|c|c|c|c|c|c| r|c|c|c|c|c|c|c|c|c|c| r|c|c|c|c|c|c|c|c|c|c| r|c|c|c|c|c|c|c|c|c|c| r|c|c|c|c|c|c|c|c|c|c| r|c|c|c| r|c|c|c|. @+0@+1@+2@+3@+4@+5@+6@+7@+8@+9 @_@_@_@_@_@_@_@_@_@_ 0@t@h@i@s@i@s@a@v@e@r @_@_@_@_@_@_@_@_@_@_ 10@y@l@o@n@g@f@i@l@e@n @_@_@_@_@_@_@_@_@_@_ 20@a@m@e@.@o@/@\en@y@e@t @_@_@_@_@_@_@_@_@_@_ 30@a@n@o@t@h@e@r@l@o@n @_@_@_@_@_@_@_@_@_@_ 40@g@f@i@l@e@n@a@m@e@. @_@_@_@_@_@_@_@_@_@_ 50@o@/@\en @_@_@_ .TE .SH SEE ALSO .PD .SS System Tools: .TP 18 .IR ar(1) create archived libraries .PD 0 .TP .IR ld(1) invoke the link editor .PD .SS Miscellaneous: .TP 18 .IR a.out(4) assembler, compiler, and linker output .PD 0 .TP .IR magic(4) magic number for HP-UX implementations .TP .IR ranlib(1) regenerate an archive symbol table .TP .IR strip(1) strip symbol and line number information from an object file .PD .SH CAVEATS .C strip removes the archive symbol table member from the archive (see .IR strip (1)). The archive symbol table must be restored by using the .C -ts option of the .C ar command or the .IR ranlib (1) command before the archive can be used with the .C ld link editor. .\" index@\f4ar\f1 \- common archive file format@@@\f3ar(4)\f1 .\" index@common archive file format@@@\f3ar(4)\f1 .\" index@archive file format, common@@@\f3ar(4)\f1 .\" index@file format: common archive files@@@\f3ar(4)\f1 .\" index@format: common archive file@@@\f3ar(4)\f1 .\" .\" toc@\f3ar(4)\f1:\0\0\f4ar\f1@@@common archive file format .\" .\" fileset_database@ar.4 SYS-ADMIN-MAN .\" @(#) $Header: arraytab.4,v 1.3 96/03/06 13:53:08 hmgr Exp $ .TA a .TH arraytab 4 .SH NAME arraytab \- disk array configuration table .SH DESCRIPTION Arraytab is a table of supported configurations for .SM HP SCSI disk array products. Each table entry includes a set of parameter values that specify an array configuration. The array configuration table is located in .C /etc/hpC2400/arraytab. .PP .SM HP SCSI disk array devices are highly configurable. The physical disk mechanisms in an array can be grouped in special ways to provide various levels of data redundancy, and data read/write performance. These levels are known as .B RAID (for .B R\c edundant .B A\c rray of .B I\c nexpensive .B D\c isks) levels. .PP Using a process called .BR striping , data from each read or write operation can be distributed across multiple physical disk mechanisms to provide load balancing and/or to add data redundancy for protection against the failure of physical disk mechanisms. Striping is done in increments of the physical disk block size for all .SM RAID levels except .SM RAID\c _3 (which uses byte striping). The stripe size, also known as .BR "segment size" , establishes the degree of data spread across the set of disk mechanisms. .PP Logical disks are created by defining address regions that include all or part of the address space of a disk group. Each logical disk are separately addressable. .PP For example: .PP .PD 0 .B " Physical Phys Drive " .PP .B " Block 1 2 3 " .PP .B " Address " .PP .B " " .PP .B " 0 X X X | " .PP .B " : X X X | Logical Drive 0 " .PP .B " X X X | " .PP .B " " .PP .B " Y Y Y | " .PP .B " Y Y Y | Logical Drive 1 " .PP .B " Y Y Y | " .PP .B " " .PP .B " Z Z Z | " .PP .B " Z Z Z | Logical Drive 2 " .PP .B " N Z Z Z | " .PD .PP In this example, 3 physical drives have been grouped into a single .SM RAID group (1 vertical partition). Three logical disks have then been formed by partitioning the composite logical address space (in blocks) into 3 logical regions. .PP A logical configuration which has more than one logical partition per physical disk group is called a "sub-\c .SM LUN". If the logical partition includes the entire address space of the disk group, the logical partition is called a "regular .SM LUN". .PP Each array configuration requires two types of specifications \(em physical specifications, and logical specifications. A physical specification determines which disk mechanisms form the groups. A logical configuration specifies the type and location of each physical disk mechanism (in the array) that is to be used within the logical partition. The logical configuration also specifies the size and characteristics of the logical partition. .PP .SS Raid Levels .PP The disk array can be configured using one of the following .SM RAID levels, depending on the I/O requirements of the system, and the degree of data availablity required. Data availability (redundancy) is achieved at the expense of storage capacity, and possibly performance. .PP .TP 9 .B "RAID_0:" This level provides no data redundancy, however disks may be grouped in a set, and data striped across the disk set to provide load balancing. .PP .RS 9 A special case exists when a drive group of size 1 is defined (independent mode). In this case the physical disk mechanisms appear to the system as they would if there were no array controller. The array controller is transparent, providing only address selection among the disks connected to it. When configured in this manner the disks operate independently for every I/O request. .RE .TP 9 .B "RAID_1:" This level provides disk mirroring. Two sets of disks maintain identical copies of the data. By choosing the number of disks in each set larger than one, data can be striped across the disks in each set (\c RAID\c _0) to provide better load balancing; the redundant disk sets provide availability. .TP .B "RAID_3:" This level uses byte striping across a set of .I n drives, with an additional drive maintaining an .SM XOR parity check byte for each byte of data. The resulting logical disk sector size is .I n times the sector size of one disk. Data can be recovered, if a drive fails, by using the redundancy of the parity drive while operating in a "degraded" mode. Since reads and writes to the individual mechanisms are accomplished in parallel, long I/O requests to the array complete in 1/\c .IR n th the time, exclusive of the access time, allowing higher bandwidth I/O rates. Because the mechanisms operate in concert during the input/output operation, only one I/O may process at a time. Disks configured in .SM RAID\c _3 have access time characteristics of a single disk, but are capable of transferring data at higher rates. This mode is most useful with long I/O requests. .TP .B "RAID_5:" This level uses block striping across a set of .I n drives. .SM XOR parity information is maintained across the set of the drives on a block basis, such that the failure of any one drive allows continued operation in a "degraded" mode. While degraded, data from the failed drive is reconstructed from the parity information, and the data on the remaining disks. Unlike .SM RAID\ _3, block sizes can be the same as for a single disk; however, write performance suffers when write requests are less than .I n blocks, because read-modify-write operations must be done on the data drive, and the parity drive. Because the XOR parity data is maintained on a block basis, drive mechanisms can operate independently, allowing multiple I/O requests to process concurrently on the set of disks. This mode is most useful for short I/O requests. This mode allows parallel processing of I/Os requests across the set of disks, however data transfer rates are equivalent to those of a single disk. .PP .SH CONFIGURATION TABLE .PP Entries in the configuration table are formed from a number of fields, each terminated by a ':' character. The fields are organized as shown below: .PP .RS 2 Drive Group Name (Physical Configuration Name) .RS 2 Drive List .PP : .PP Drive List .PP .RE Logical Configuration Name .RS 2 Logical partition configuration .PP Logical partition configuration .PP : .PP Logical partition configuration .RE 0 .PP Each part of the specification is terminated by a 'New Line' character. The fields are generally composed of an identifier token, followed by parameter value or values, separated by '#'. Comments may also be placed within the file by leading the field with '#'. All following characters up to 'New Line' will be ignored. A character may be escaped by immediately preceding it with '\\'. Logical configurations and physical configurations may appear in any order, provided the syntax requirements are met. Physical disk configuration labels must be unique within the table. Logical configuration labels need not be unique. However, configurations with non-unique labels should have different parameter values for the array controller type field, or specify a different disk group. Logical disk configurations are searched sequentially-- the first labeled specification which matches will be used. .PP .RE The following list describes the arraytable parameters and their use. .PP .BI "Name" " Type" " Description" .TP 12 .BI " ct " " str" Array Controller Type. This parameter must be specified in at least one logical partition of a logical configuration. The field consists of the concatenated vendor ID and product ID strings which are returned by the SCSI Inquiry message to the array controller, with "_" separating these two strings. This field defines array product for which this configuration may be used. For example, "HP_C2425D" or "HP_C2430D". .BI " dl " " num" Physical Drive list. Each drive group consists of 1 or more lists of disk mechanisms, each specified by the array channel number, the channel ID of the disk mechanism on the channel, and a disk identifier label, respectively. A drive list may have up to 5 drives listed. The order of the drives in the list determines the order in which data is placed on the drives. This order is defined by the drive sequence label "d", where N is a number from 0 to 4. Subsequent lists may be used to create drive groups larger than 5 disks. The disk identifier label is a string formed from the vendor ID and product ID strings returned from a SCSI Inquiry message, separated by "_". Certain constraints are made for the drive groups and drive lists, depending upon the number of drives and the RAID level chosen. See restrictions below. .TP .BI " lp " " num" Logical partition within the logical configuration. A logical configuration will have one or more logical partitions, with each logical partition consisting of a portion or the whole of a drive group (See LUN type). Address space is allocated to each logical partition in the order in which it is found in the table, and begin start from the beginning block of the disk group. A logical partition number corresponds with the SCSI logical unit (LUN) number. .TP .BI " lt " " str" Logical partition or LUN type. A logical partition may be either "regular LUN" (reg) or "sub-LUN" (sub). A sub-LUN allows configuring multiple logical disks for a group of disks, each to an arbitrary capacity. A regular LUN allows a logical disk capacity of the composite disk capacity of a group of drives, or 2 GByte, whichever is smaller. When the regular LUN option is used, the capacity parameter is ignored by the array controller. Additional logical drives may be configured to use the remaining capacity beyond 2 GByte if the regular LUN mode is chosen. .TP .BI " bs " " num" Block size of the logical partition or LUN in bytes. This value must be specified in increments of the native disk mechanism sector size. Currently supported values are 512, 1024, 2048, 4096 bytes. .TP .BI " cv " " num" Capacity of the logical partition or LUN in blocks. If this value is set to 0, the array will configure as many blocks as are available (not previously configured in another LUN). .TP .BI " ss " " num" Segment size. The size in bytes of a contiguous segment of the logical address space which will reside on a single physical disk. This allows controlling how many disks are involved with a single I/O request. If I/O requests are mostly random, single block requests, this value should be set to the block size. If the I/O requests are typically more than a single sequential block, then this value should be set to the number of bytes which minimizes the number of disks necessary to service most I/Os. The value must be an integral number of the block size. .TP .BI " is " " num" The size in bytes of the first segment of the LUN. This allows this area to be set to a size different than the remainder of the disk, an area typically used as the boot block for some systems. This must be an integral number of the block size. If there are no special requirements, this parameter should be set to 0. .TP .BI " rl " " str" RAID level. Acceptable strings are { RAID_0, RAID_1, RAID_3, RAID_5 }. The RAID modes are described above. .TP .BI " gn " " str" Group name. This is the label used to identify the physical drive group or configuration to be used with the logical configuration. .TP .BI " gs " " num" Number of physical drives in the drive group. .TP .BI " rs " " num" Reconstruction size. This is the number of logical disk blocks which will be reconstructed in one operation when a drive data set is being repaired. A larger value will cause the reconstruction to complete more quickly (and efficiently), but will cause longer delays in processing other I/O requests. .TP .BI " rf " " num" Reconstruction frequency. This is the period of time between reconstruction operations, specified in 0.1 Sec. (see Reconstruction Size). This parameter is useful in systems which do not do I/O request queuing to allow I/Os to process smoothly while reconstructing the data set. .TP .BI " lf " " num" LUN configuration flags. There are 16 possible LUN configuration flags. Currently only 6 of these flags are defined. It is not recommended that these fields be altered. The flags are used to enable certain features of the array controller for the specified LUN. The flags may be set by specifying the hexadecimal value for all the flags. The flags are defined as follows: .PP .RS 13 .TP 15 .BI "Bit 0 " " off" Not used. .TP .BI "Bit 1 " " on" Automatic reconstruction disable. Enabled allows the array controller to automatically begin data restruction when the replacement of a failed disk is detected. .TP .BI "Bit 2 " " off" Not used. .TP .BI "Bit 3 " " off" Not used. .TP .BI "Bit 4 " " on" Asynchronous Event Notification polling enable. .TP .BI "Bit 5 " " on" Parity verification enable. .TP .BI "Bit 6 " " on" Write with parity verification enable. .TP .BI "Bit 7 " " off" Not used. .TP .BI "Bit 8 " " off" Mode Sense: Current. Current values are accessed during mode sense. This bit should not be set concurrently with Bit 9. .TP .BI "Bit 9 " " off" Mode Sense: Saved. Saved values are accessed during mode sense. This bit should not be set concurrently with Bit 10. .TP .BI "Bit 10-15" " off" Not used. .PP .RE .RS .PP .SH RAID LEVEL RESTRICTIONS: .RS 2 The following restrictions apply to RAID configurations for the array: .TP 9 .B "RAID_0:" .PP .RS 2 .PD 0 .IP "- " 2 No disk list may contain more than 1 disk per channel .PP .IP "- " 2 For groups larger than 5 disks, additional lists are defined and data is accessed in the order of definition. .PD .RE .PP .TP 9 .B "RAID_1:" .RS 2 .PP In this mode the lists define the set of disks for data, and the set of disks which form the mirrored pair. .PP .PD 0 .IP "- " 2 Two lists must be specified. .PP .IP "- " 2 The two lists must be of equal length. .PP .IP "- " 2 No list may contain more than 1 disk per channel .PP .IP "- " 2 Corresponding entries in the two lists (these form a mirrored disk pair) cannot be on the same channel. .PD .RE .PP .TP 9 .B "RAID_3:" .RS 2 .PP .PD 0 .IP "- " 2 There must be an odd number of disks in the disk list. .PP .IP "- " 2 Disks in the disk list must be on separate channels. .PP .IP "- " 2 The first disk of the set must be on channel 1, followed in order by the other channels. Thus a 3 disk set will use channels 1 through 3. .PP .IP "- " 2 The disk on the last channel is the parity disk. (Channel 3 for 3 disk configuration, channel 5 for 5 disk configuration.) .PP .IP "- " 2 Maximum configuration is 1 list of 5 disks. .RE .PD .PP .TP 9 .B "RAID_5:" .PP .RS 2 .PD 0 .IP "- " 2 The disk list cannot contain more than 1 disk per channel. .PP .IP "- " 2 Maximum configuration is 1 list of 5 disks. .RE .PD .PP .SH EXAMPLE: .PP .RS 2 .PP 0 .B "PGroup1: dl#0: d0#1#0#HP_02425: d1#2#0#HP_02425: d2#3#0#HP_02425:" .PP .B "LConfig: lp#0: gs#3: gn#PGroup1: r#RAID_3: is#0: ss#8192:\\\\" .PP .B " cv#204994: ct#HP_C2425D" .PP .B " lp#1: gs#3: gn#PGroup1: r#RAID_3: is#0: ss#8192:\\\\" .PP .B " cv#8192: ct:#HP_C2425D" .RE 0 .PP .SH FILE SYSTEM CONSIDERATIONS: The performance of the disk array will depend heavily upon the RAID level used, and the application. In addition, the disk array configuration parameters should be chosen with consideration of the parameters used for the file system in use on the array. .PP .SH WARNING: .PP The configurations found in .I /etc/hpC2400/arraytab have been chosen and certified by HP for proper operation on HP systems. Use of configurations other than these have NOT been certified for proper operation, and cannot be warranted. .PP For configurations using logical partitions exceeding 2 GB it is necessary that the 2 GB governor flag be turned off in the array controller. See .B see(1m). .SH DEPENDENCIES: .B Series 700: .RS 2 .PP LUN address 6 and 7 are reserved for use with array management utilities, and should not be configured. .RE .PP .B Series 800: .RS 2 .PP LUN address 6 and 7 are reserved for use with array management utilities, and should not be configured. .PP Only RAID levels 0 (Independent), 3, and 5 are supported. .PP RAID 0 configurations must span only a single disk (Independent mode) and result in separate addressable logical partitions, one for each physical disk. .PP RAID 3 and RAID 5 configurations must result in a single logical partition, which span all disks on the array. .RE 0 .SH AUTHOR: .I Arraytab was developed by HP. .SH FILES /etc/hpC2400/arraytab .SH SEE ALSO newarray(1m), mkfs(1m), buildfs(1m), cfl(1m), fs(4), see(1m) .\" .\" index@\f4arraytab\f1 \- disk array configuration table@@@\f3arraytab(4)\f1 .\" index@disk array, configuration table@@@\f3arraytab(4)\f1 .\" index@configuration table for disk arrays@@@\f3arraytab(4)\f1 .\" .\" toc@\f3arraytab(4)\f1:\0\0\f4arraytab\f1@@@disk array configuration table .\" .\" fileset_database@arraytab.4 SYS-ADMIN-MAN .\" $Header: audeventsta.4,v 72.4 94/11/02 17:42:59 ssa Exp $ .TA a .TH audeventstab 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME audeventstab \- define and describe audit system events .SH DESCRIPTION The .C /usr/audit/audeventstab file lists audit event numbers, corresponding mnemonic names, and brief explanations of each event. Blank lines and comments (beginning with a .C # character) are allowed. Each non-comment, non-blank line in this file contains three parts: .RS .TP 15 .I event Audit event number in decimal: a single field separated by whitespace. .TP .I name Corresponding mnemonic name: a single field separated by whitespace. .TP .I explanation Remainder of the line, following a .C # character. .RE .PP For kernel-generated audit events, event numbers match kernel-internal system call numbers, and event names are system call names. For events from self-auditing programs, names are macros defined in .RC < sys/audit.h >. .SH EXAMPLES To extract a list of event numbers and names from the file by stripping comments and ignoring blank lines: .RS .PP .nf .ifn .ft 3 .ift .ft 4 .ps +1 tab=' ' sed < /usr/audit/audeventstab -e 's/#.\(**//' -e "/^[\0$tab]\(**$/d" .ft .ps .fi .RE .SH AUTHOR .C audeventstab was developed by .SM HP. .SH FILES .C /usr/audit/audeventstab .SH SEE ALSO audisp(1M), audevent(1M). .\" .\" index@\f4audeventstab\fP \- define and describe audit system events@@@\f3audeventstab(4)\f1 .\" index@define and describe audit system events@@@\f3audeventstab(4)\f1 .\" index@describe audit system events, define and@@@\f3audeventstab(4)\f1 .\" index@audit system events, define and describe@@@\f3audeventstab(4)\f1 .\" index@events, audit system, define and describe@@@\f3audeventstab(4)\f1 .\" toc@\f3audeventstab(4)\f1:\0\0\f4audeventstab\fP@@@define and describe audit system events .\" .\" fileset_database@audeventsta.4 SYS-ADMIN-MAN .\" $Header: audit.4,v 78.1 96/01/09 13:47:16 ssa Exp $ .TA a .TH audit 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME audit \- file format and other information for auditing .SH SYNOPSIS .C #include .SH DESCRIPTION Audit records are generated when users make security-relevant system calls, as well as by self-auditing processes that call .C audwrite() (see .IR audwrite (2)). Access to the auditing system is restricted to super-user. .PP Each audit record consists of an audit record header and a record body. The record header is comprised of time, process .SM ID, error, event type, and record body length. The time refers to the time the audited event completes in either success or failure; the process .SM ID belongs to the process being audited; the event type is a field identifying the type of audited activity; the length is the record body length expressed in bytes. The exact format of the header is defined in .RC < sys/audit.h > as follows: .nf .IP .C struct audit_hdr { .C " u_long ah_time; /* date/time (tv_sec of timeeval) */" .C " u_short ah_pid; /* process ID */" .C " u_short ah_error; /* success/failure */" .C " u_short ah_event; /* event being audited */" .C " u_short ah_len; /* length of variant part */" .C }; .fi .PP The record body is the variable-length component of an audit record containing more information about the audited activity. For records generated by system calls, the body contains the parameters of the system calls; for records generated by self-auditing processes, the body consists of a high-level description of the event (see .IR audwrite (2)). .PP The records in the audit file are compressed to save file space. When a process is audited the first time, a .I pid identification record .SM (PIR) is written into the audit file containing information that remains constant throughout the lifetime of the process. This includes the parent's process .SM ID, audit .SM ID, real user .SM ID, real group .SM ID, effective user .SM ID, effective group .SM ID, and the terminal .SM ID (tty). The .SM PIR is entered only once per process per audit file, and is also defined in .RC < sys/audit.h > as follows: .nf .IP .C "struct pir_body { /* pir-related info */" .C " short ppid; /* parent process ID */ .C " int32_t aid; /* audit ID */ .C " uid_t ruid; /* user_ID */ .C " gid_t rgid; /* group ID */ .C " uid_t euid; /* effective user_ID */ .C " gid_t egid; /* effective group_ID */ .C " dev_t tty; /* tty number */ .C }; .fi .PP Information accumulated in an audit file is analyzed and displayed by .C audisp (see .IR audisp (1M)). .PP Whenever auditing is turned on, a ``current'' audit file is required and a ``next'' audit file (for backup) is recommended (see .IR audsys (1M) and .IR audomon (1M)). When the ``current'' audit file is full and the ``next'' audit file is available, the auditing system switches files automatically. .SH AUTHOR .C audit was developed by HP. .SH SEE ALSO audsys(1M), audevent(1M), audisp(1M), audomon(1M), audwrite(2), getevent(2), setevent(2). .\" .\" index@audit: file format and other information for auditing@@@\f3audit(4)\f1 .\" index@file format and other information for auditing@@@\f3audit(4)\f1 .\" toc@\f3audit(4)\f1:\0\0\f4audit\fP@@@file format and other information for auditing .\" .\" $Header: authcap.4,v 74.1 95/05/10 21:27:01 ssa Exp $ .TA a .TH authcap 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME authcap \- security databases for trusted systems .SH SYNOPSIS .B "/tcb/files/auth/*" .br .B "/tcb/files/auth/system/*" .SH DESCRIPTION All security-relevant databases are stored in an .SM ASCII format in the file system. This format is converted to binary structures by support routines described in Section 3 manual entries. This manual entry describes the format of these databases, and describes the philosophy of conversion into data structures. .SS "Hierarchy Structure" The complete database resides in two hierarchies: .B "/tcb/files/auth/*" and .BR /tcb/files . The first hierarchy contains the Protected Password database, and has subdirectories with single letter names, each of which is a starting letter for user names. Within each of these directories are regular files, each containing an .IR authcap (4) format file containing the Protected Password entry for a particular user. Thus, all user names beginning with .B x have their respective authentication and identity information in a file in directory .BR /tcb/files/auth/x . .PP Directories within .B /tcb/files/auth/system and .BR /tcb/files contain system-wide information. Global system settings reside in directory .BR /tcb/files/auth/system . Terminal and device assignment files are located in directory .BR /tcb/files . .PP The following database files reside in directory .BR system : .IP .TS tab(;); lB l. default;Default Control .TE .PP The following database files reside in directory .BR /tcb/files : .IP .TS tab(;); lB l. ttys;Terminal Control devassign;Device Assignment .TE .PP .SS File Format Each data file \c .RB ( /tcb/files/auth/system and .BR /tcb/files ) \c has the same format. Each file consists of one virtual line, optionally split into multiple physical lines with the \e character present at the end of all lines except the last. For example, the line .IP .B smk:u_name=smk:u_id#16:u_pwd=a78/a1.eitfn6:chkent: .PP can be split into: \c .IP .B smk:u_name=smk:u_id#16:\e .br .B \h'.5i':u_pwd=a78/a1.eitfn6:\e .br .B \h'.5i':chkent: .PP Note that all capabilities must be immediately preceded and followed with the .B : separator. Multiple line entries require .B : at the end of each line and at the beginning of each continuation line in the entry. Continuation lines are indented by a tab character. Multiple entries are separated by a new-line character that is not preceded by a continuation character: .IP .B daa:u_name=daa:u_id#75:u_maxtries#9:chkent: .br .B smk:u_name=smk:u_id#76:u_maxtries#5:chkent: .PP .SS Line Format The format of a line \c is briefly as follows: .IP .B name:cap1:cap2:cap3:...:capn:chkent: .PP The entry is referenced by the name. The end of the name part of the entry is terminated by the .B : character. .PP At the end of each entry is the .I chkent field. This is used as an integrity check on each entry. The .IR authcap (3) routines reject all entries that do not contain the .I chkent terminator. .PP Each entry has 0 or more capabilities, each terminated with the .B : character. Each capability has a unique name. Numeric capabilities have the format: .IP .IB id # num .PP where .I num is a decimal or (0-preceded) octal number. Boolean capabilities have the format: .IP .I id .PP or .IP \f2id\f3@\f1 .PP where the first form signals the presence of the capability and the second form signals the absence of the capability. String capabilities have the format: .IP .B id=string .PP where string is 0 or more characters. The .B \e and .B : characters are escaped as .B \e\|\e and .B \e: respectively. .SS File Locking All databases use a lock file, the existence of which means that the file is currently being rewritten. Occasionally, the lock files remain after a system crash and must be removed manually. The lock file is formed by appending .B \-t to the database file name. .SS Fields/Flags All databases are converted into structures by programs. The data structures consist of two substructures, each of which has one member for each field in the database entry. The .I field structure contains a field value (for example, a number, a boolean flag, a directory string, or a mask), while the flag value (one bit) indicates the presence or absence of the field in that entry. .SH AUTHOR SecureWare Inc. .SH SEE ALSO default(4), devassign(4), getdvagent(3), getprdfent (3), getprpwent(3), getprtcent(3), prpwd(4), ttys(4). .\" .\" index@\f4authcap\f1 \- security databases@@@\f3authcap(4)\f1 .\" index@\f1security databases@@@\f3authcap(4)\f1 .\" index@\f1databases, security@@@\f3authcap(4)\f1 .\" .\" toc@\f3authcap(4)\f1:\0\0\f4authcap\f1@@@security databases .\" .\" fileset_database@authcap.4 UX-CORE-MAN .\" $Header: bootconf.4,v 76.1 95/07/05 17:26:13 ssa Exp $ .TA b .TH bootconf 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME /stand/bootconf - boot device configuration table .SH DESCRIPTION .PP This file contains the address and disk layout type of the system's boot devices or .I lif volumes. It is used by the .C Software Distributor and HP-UX kernel control scripts (fileset .CR "OS-Core.KERN-RUN" ) to determine how and where to update the initial boot loader. Normally the kernel's .CR checkinstall script queries the system's hardware and creates the file. In rare cases when either the system configuration cannot be automatically determined or additional and/or alternate boot devices should be automatically updated, the administrator must to edit the .CR /stand/bootconf file manually. .PP There is one line in the file for each boot device. Each line contains the following blank-separated fields in the order shown: .RS .TP 15 .I disk type A flag indicating how the file system(s) on the disk are laid out. The flag must be one of the following: .RS .RS .TP 3 .C l Indicates that the root disk is in LVM format. If LVM mirrors are used, then each of the "mirrors" must have its own line. .TP .C p Indicates that the root disk has Series 800-style hard partitions and that the boot volume is is section 6. .TP .C w Indicates that the root disk is in the Release 9.X Series 700-style "whole disk" format with no partitions, but boot and swap space are reserved outside the file system. .RE .RE .TP .I device file The absolute path of the device special file that accesses the physical device where the boot area is located. For LVM root disks, the device special file is the physical volume(s) returned by the .C vgdisplay -v command. For Series 800 hard partitions, this is the device special file that points to section six of the disk. For Series 700-style "whole disks" this is the device file that references the entire disk. .RE .PP Blank lines are permitted. Any line beginning with a .CR # is considered to be a comment. .SH DIAGNOSTICS The Software Distributor log file .C /var/adm/sw/swagent.log contains diagnostic messages under the .CR OS-Core.KERN-RUN fileset if the .C bootconf file is incorrect. Most of the messages are self-explanatory; a few warrant additional explanation: .TP .C "... is either empty or improperly formatted..." If there are no other messages about .C bootconf, the file is probably empty. Otherwise, the file is not in the proper format, and the other messages will explain what the problem is. .TP .IC "device file" "... does not contain a valid boot LIF ..." The specified device file does not point to a disk where there is a .I lif which contains the file .C HPUX. .TP .C "... has an invalid character in the flag field..." Some character other than .CR # , .CR l , .CR p , or .CR w is in the first field of a line. .TP .C ... contains contradictory boot LIF types..." As of release 10.0, the boot areas in .CR /stand/bootconf must all be on the same type of disk layout. .TP .C "... has unrecognized extra characters..." There are characters after the .I device file specification. .SH EXAMPLES .PP The boot area is on an LVM root disk: .PP .RS # Boot Device configuration file .br # This file contains information regarding the location .br # of the boot LIF. It is used by the KERN-RUN fileset to .br # update the boot kernel. .br l /dev/dsk/c2t7d0 .RE .PP The system has LVM mirroring on root (the device files indicate that the system is running on a 9.0 release being prepared for updating to 10.0): .PP .RS #Boot Device configuration file .br # This file contains information regarding the location .br # of the boot LIF. It is used by the KERN-RUN fileset to .br # update the boot kernel. .br l /dev/dsk/c1d0s2 .br l /dev/dsk/c4d0s2 .br l /dev/dsk/c5d0s2 .RE .PP The boot area is on a hard partitioned disk: .PP .RS # Boot Device configuration file .br # This File contains information regarding the location .br # of the boot LIF. It is used by the KERN-RUN fileset to .br # update the boot kernel. .br p /dev/dsk/0s0 .RE .PP The boot area is on a whole disk layout: .PP .RS # Boot Device configuration file .br # This File contains information regarding the location .br # of the boot LIF. It is used by the KERN-RUN fileset to .br # update the boot kernel. .br w /dev/dsk/6s0 .RE .PP .SH WARNINGS All of the boot devices in the file must have the same disk layout. .SH AUTHOR .PP .C bootconf was developed by the Hewlett-Packard Company. .SH FILES .CR /stand/bootconf .SH SEE ALSO mediainit(1), hpux(1M), mkboot(1M), vgdisplay(1M), lif(4), .br .CR "Software Distributor" documentation. .\" toc@\f3bootconf(4)\f1:\0\0\f4bootconf\f1@@@ boot device configuration table .\" index@\f4bootconf\f1 \- boot device configuration table@@@\f3bootconf(4)\f1 .\" index@\f1boot device configuration table@@@\f3bootconf(4)\f1 .\" index@\f1configuration table, boot device@@@\f3bootconf(4)\f1 .\" $Header: utmp.4,v 72.7 94/11/15 09:57:28 ssa Exp $ .TA u .TH utmp 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME utmp, wtmp, btmp \- utmp, wtmp, btmp entry format .SH SYNOPSIS .C #include .br .C #include .SH DESCRIPTION These files, which hold user and accounting information for such commands as .CR last , .CR who , .CR write , and .C login (see .IR last (1), .IR who (1), .IR write (1), and .IR login (1)), have the following structure as defined by .RC < utmp.h >: .RS 3 .IP .nf .ift .ft 4 .ifn .ft 3 .ps +1 #define UTMP_FILE "/etc/utmp" #define WTMP_FILE "/var/adm/wtmp" #define BTMP_FILE "/var/adm/btmp" #define ut_name ut_user .sp struct utmp { char ut_user[8]; /* User login name */ char ut_id[4]; /* /etc/inittab id(usually line#)*/ char ut_line[12] /* device name (console, lnxx) */ pid_t ut_pid; /* process id */ short ut_type; /* type of entry */ struct exit_status short e_termination; /* Process termination status*/ short e_exit; /* Process exit status*/ } ut_exit; /* The exit status of a process*/ /* marked as DEAD_PROCESS.*/ unsigned short ut_reserved1; /* Reserved for future use*/ time_t ut_time; /* time entry was made*/ char ut_host[16]; /* host name,if remote*/ unsigned long ut_addr; /* host Internet addr, if remote*/ }; .sp 1v /* Definitions for ut_type */ #define EMPTY 0 #define RUN_LVL 1 #define BOOT_TIME 2 #define OLD_TIME 3 #define NEW_TIME 4 #define INIT_PROCESS 5 /* Process spawned by "init" */ #define LOGIN_PROCESS 6 /* getty process awaiting login */ #define USER_PROCESS 7 /* A user process */ #define DEAD_PROCESS 8 #define ACCOUNTING 9 #define UTMAXTYPE ACCOUNTING /* Max. legal value of ut_type */ .sp 1v /* Special strings or formats used in the "ut_line" field */ /* when accounting for something other than a process */ /* No string for the ut_line field can be more than */ /* 11 chars + a \s-1NULL\s+1 in length */ #define RUNLVL_MSG "run\-level %c" #define BOOT_MSG "system boot" #define OTIME_MSG "old time" #define NTIME_MSG "new time" .fi .RE .PP File .C utmp contains a record of all users logged onto the system. File .C btmp contains bad login entries for each invalid logon attempt. File .C wtmp contains a record of all logins and logouts. .PP Note that .C wtmp and .C btmp tend to grow without bound, and should be checked regularly. Information that is no longer useful should be removed periodically to prevent it from becoming too large. Also note that .C wtmp and .C btmp are not created by the programs that maintain them. Thus, if these files are removed, record-keeping is turned off. .SH FILES .C /etc/utmp .br .C /var/adm/wtmp .br .C /var/adm/btmp .SH AUTHOR .CR utmp , .CR wtmp , and .C btmp were developed by HP and the University of California, Berkeley. .SH SEE ALSO last(1), login(1), who(1), write(1), acctcon(1M), fwtmp(1M), getut(3C). .SH STANDARDS CONFORMANCE .RC < utmp.h ">: XPG2" .\" .\" index@\f4utmp()\fP, \f4wtmp()\fP, \f4btmp()\fP \- utmp, wtmp, btmp user accounting file entry format@@@\f3utmp(4)\f1 .\" index@\f4wtmp()\fP, \f4utmp()\fP, \f4btmp()\fP \- utmp, wtmp, btmp user accounting file entry format@@@\f3utmp(4)\f1 .\" index@\f4btmp()\fP, \f4utmp()\fP, \f4wtmp()\fP \- utmp, wtmp, btmp user accounting file entry format@@@\f3utmp(4)\f1 .\" index@user accounting file entry format for \f4btmp()\fP, \f4utmp()\fP, and \f4wtmp()\fP@@@\f3utmp(4)\f1 .\" index@accounting: user accounting file entry format@@@\f3utmp(4)\f1 .\" index@file format: user accounting file entry@@@\f3utmp(4)\f1 .\" index@entry format, user accounting files \f4btmp()\fP, \f4utmp()\fP, and \f4wtmp()\fP@@@\f3utmp(4)\f1 .\" index@format: user accounting files \f4btmp()\fP, \f4utmp()\fP, and \f4wtmp()\fP@@@\f3utmp(4)\f1 .\" .\" toc@\f3utmp(4)\f1:\0\0\f4utmp()\fP, \f4wtmp()\fP, \f4btmp()\fP@@@utmp, wtmp, btmp entry format .\" toc@\f4wtmp()\fP:\0\0wtmp entry format@@@see \f3utmp(4)\f1 .\" toc@\f4btmp()\fP:\0\0btmp entry format@@@see \f3utmp(4)\f1 .\" .\" links@utmp.4 wtmp.4 .\" links@utmp.4 btmp.4 .\" $Header: cdnode.4,v 72.3 93/01/14 16:02:20 ssa Exp $ .TA c .TH cdnode 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cdnode \- format of a \s-1CDFS\s+1 cdnode .SH SYNOPSIS .ft 3 #include .br #include .ft 1 .SH DESCRIPTION This entry describes the cdnode structure and related concepts for the .SM CDFS file system. Refer to other .IR inode (4) manual pages for information regarding the inode structure for other file systems. .PP The .SM CDFS file system does not have the concept of a separate entity called an inode. The information normally found in an .SM HFS inode is kept in a .B cdnode data structure. However, the cdnode data structure does not reside on the physical media, but instead is kept in kernel memory space only. The cdnode information is used to uniquely identify a file. .PP The information kept in the cdnode structure is obtained from two other data structures in the .SM CDFS file system: .RS .TP 5 1. Directory record for the file or directory, and .TP 2. Extended attribute record .SM (XAR) for the file or directory, if one exists. .RE .PP Because few files usually have .SM XAR\c s associated with them, the cdnode information most often consists only of attributes given by the directory record for the file. .PP Since cdnodes are kept in kernel memory, they cannot be directly accessed by the user. The .C stat() system call attempts to map whatever information is included in the cdnode for a given file into the standard stat structure (see .IR stat (2)). However, since a cdnode includes information that does not have corresponding fields in the stat structure, that information cannot be mapped and therefore cannot be accessed. No method is provided to access an entire cdnode structure. .SH FILES .C /usr/include/sys/cdnode.h .br .C /usr/include/sys/cdfsdir.h .SH SEE ALSO stat(2), cdrom(4), cdfsdir(4). .\" .\" index@\f4cdnode\fP \- format of a \s-1CDFS\s+1 cdnode@@@\f3cdnode(4)\f1 .\" index@\s-1CD-ROM\s+1: format of a \s-1CDFS\s+1 cdnode@@@\f3cdnode(4)\f1 .\" index@format of a \s-1CDFS\s+1 cdnode@@@\f3cdnode(4)\f1 .\" index@\s-1CDFS\s+1 cdnode, format of a@@@\f3cdnode(4)\f1 .\" .\" toc@\f3cdnode(4)\f1:\0\0\f4cdnode\fP@@@format of a \s-1CDFS\s+1 cdnode .\" .\" fileset_database@cdnode.4 SYS-ADMIN-MAN .\" $Header: cdrom.4,v 78.1 95/12/20 10:40:05 ssa Exp $ .TA c .TH cdrom 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cdrom \- CD-ROM background information .SH DESCRIPTION This manual entry provides general information on existing CD-ROM standards, terminology, data layout, and levels of support. More detailed information is available in the standard documents listed in SEE ALSO. .PP Not all topics discussed here are supported in the current HP-UX release. Refer to the DEPENDENCIES section for details about the contents of the current release. .SS Standard Formats Currently, two standard formats are defined for CD-ROM. .PP The High Sierra Group (HSG) standard was produced by the CD-ROM Ad Hoc Advisory Committee, and is documented in a publication entitled .I "The Working Paper for Information Processing \(mi" .I "Volume and File Structure of Compact Read Only" .IR "Optical Discs for Information Interchange" . This document is available from the National Information Standards Organization (NISO). .PP The second standard, which evolved from the HSG standard, was produced by the International Organization for Standardization (ISO). This standard is documented in a publication entitled .I "Information Processing \(mi Volume and File Structure of" .I CD-ROM .IR "for Information Interchange" , reference number ISO 9660: 1988 (E). .SS Data Layout The data layout on a CD-ROM can be represented as follows: .PP .TS center, doublebox; C. .sp .2v System Area - 32 kilobytes .sp .2v = .sp .3v Volume Descriptor .sp .2v _ \f3.\f1 \f3.\f1 \f3.\f1 .sp .2v _ .sp .2v Volume Descriptor Terminator .sp .2v _ \f3.\f1 \f3.\f1 \f3.\f1 .sp .2v = .sp .3v Path Table .sp .2v _ .sp .2v Path Table .sp .2v _ \f3.\f1 \f3.\f1 \f3.\f1 .sp .2v = .sp .3v Directory and File Data .sp .2v \f3.\f1 \f3.\f1 \f3.\f1 .sp .2v = .TE .PP There are typically four sections in the CD-ROM data (indicated by double horizontal lines in the table above): Only the first two sections must occur in the order shown above. .PP The .B System Area consists of the first sixteen 2048-byte blocks on the media. The contents of this section are not specified by either standard; here, the creator of the CD-ROM can put data that is relevant to the system for which the CD-ROM is intended. .PP The .B Volume Descriptor typically contains one primary volume descriptor and zero or more supplementary volume descriptors. Each volume descriptor is 2048 bytes in length, and describes the attributes and structure of a directory hierarchy on the CD-ROM. The list of volume descriptors is terminated by one or more .BR "volume descriptor terminators" . A volume descriptor terminator is also 2048 bytes in length, and simply signals the end of the volume descriptor section. .PP The .B Path Table contains all the path tables for all directory hierarchies on the CD-ROM. Path tables do not have to be constrained to this section of the CD-ROM data, but can be interspersed with .B Directory and File Data (described below) to minimize seek times. .PP The .B Directory and File Data contains data for all directory hierarchies on the CD-ROM and, as described above, can be made noncontiguous by the occasional inclusion of a path table. .SS Volumes and Directory Hierarchies A .B volume is a single physical CD-ROM. A .B directory hierarchy is a hierarchical file system written on a volume. Multiple directory hierarchies can be placed on a single volume, or a single directory hierarchy can span multiple volumes. Each directory hierarchy on a volume is described by a .BR "volume descriptor" . .PP Directory hierarchies on the same volume can be totally independent of each other with each one defining a totally unique and unrelated file system. They can also be related to each other through the sharing of data between them. .PP A .B volume set is a set of one or more volumes that are to be treated as a unit. Each successive volume in the volume set updates or augments the data on the volumes preceding it. Thus, the last volume in a volume set is always the volume which describes the most up-to-date directory hierarchy for the volume set. A unique and ascending value called the .BR "volume sequence number" , is assigned to each volume in a volume set. Volume sets are useful for updating large multivolume databases without having to rework the entire set. .SS Volume Descriptors Each directory hierarchy on a volume is described by a .BR "volume descriptor" . There are several types of volume descriptors, but the two of most interest are the .B primary volume descriptor and the .BR "supplementary volume descriptor" . Their content is almost identical, but they have different intended uses. .PP The primary volume descriptor describes the primary directory hierarchy on a volume. If there are additional directory hierarchies on the volume, or different ways to view the same directory hierarchy, these are described by supplementary volume descriptors. In the case of a volume set, the primary volume descriptor on each volume describes the primary directory hierarchy for that volume and all preceding volumes in the set thus far. .PP Volume descriptors contain the following information: .nf .IP standard ID (identifies the format of the volume); system ID; volume ID; size of the volume; volume set size; volume sequence number; logical block size; path table size; pointers to the path tables; directory record for the root directory; volume set ID; publisher ID; data preparer ID; application ID; copyright file name; abstract file name; bibliographic file name (ISO only); volume creation date and time; volume modification date and time; volume expiration date and time; volume effective date and time; application use area. .fi .SS Path Tables A .B path table defines a directory hierarchy structure within a volume. Each path table contains a record for each directory in the hierarchy. In each record are kept the directory's name, the length of any extended attribute record associated with the directory, the logical block number of the block in which the directory begins, and the number of the parent directory for that directory. (All directories in a path table are numbered according to the order in which they appear in the path table.) .PP There are two types of path tables. One is a .B type-L path table in which all numerical values in each path table record are recorded least-significant-byte-first. The other type, .BR type-M , is a path table in which all numerical values are recorded most-significant-byte-first. One of each type of path table is required by both standards. The ISO standard allows for one additional optional copy of each type of path table, while the HSG standard allows for up to three additional optional copies of each type. Additional copies of path tables are useful for redundancy or seek time minimization. .SS Extended Attribute Records An .B extended attribute record (abbreviated .B XAR ) is a data structure specifying additional information about the file or directory with which the XAR is associated. An XAR contains the following information: .nf .IP owner id; group id; permissions; creation date and time; modification date and time; expiration date and time; effective date and time; record information; application use area. .fi .PP If an XAR is recorded, the XAR is written beginning at the first block of the file or directory. The actual data for the file or directory is written beginning at the next block after the block in which the XAR ends. .PP Where possible, XAR information is mapped into the stat structure by the .C stat() system call (see .IR stat (2)). However, many items do not map very well due to lack of appropriate fields in the stat structure for information provided by the XAR. To preserve backward compatibility of the stat structure, such information is discarded by .CR stat() . The .C fsctl() system call can be used to obtain the XAR for a particular file or directory (see .IR fsctl (2)). .SS Interleaving For performance reasons, data in a file can be interleaved when recorded on the volume. This is accomplished by dividing the file into pieces called .BR "file units" . The size of each file unit (in logical blocks) is called the .BR "file unit size" . The interleaved file is then recorded onto the volume by writing a file unit, skipping one or more blocks, writing another file unit, skipping more blocks, and so on until the entire file is recorded. The number of blocks to skip between file units is called the .BR "interleave gap size" . Blocks making up the interleave gap are available for assignment to other files. .PP File unit and interleave gap sizes are kept in the directory record for each file. Thus, the file unit and interleave gap sizes may change from file to file, but cannot change within the same file (unless the file is written in .B sections \(mi see below). .PP Directories cannot be interleaved. .SS File Sections In order to be able to share data between files, a file can be broken up into .BR "file sections" . File sections for a particular file are not necessarily all the same size. .PP Each file section is treated like a separate file in that each section gets its own directory record. This implies that each file section has its own size, its own XAR, and its own unique file unit and interleave gap sizes. However, all file sections for the same file must all share the same file name. The order of the file sections in the file is determined by the order of the directory records for each section. A bit in each directory record determines whether or not that record is the last record for the file. .PP A file section can appear more than once in a single file, or appear many times in many different files. A file section in one volume can also be claimed by a file in a subsequent volume in a volume set (this is how updates are accomplished). .PP Each file section can have its own XAR. However, if the final file section of a file has no associated XAR, the entire file is treated as if it has no XAR. This is done to make updates work sensibly. .PP Directories must always consist of a single section. .SS Implementation and Interchange Levels CD-ROM standards define two levels of implementation and three levels of interchange. .B implementation levels provide a way for receiving systems that support CD-ROM to specify their level of support. The implementation levels are: .RS .TP 12 Level 1 The system is permitted to ignore supplementary volume descriptors, their associated path tables, and all directory and file data associated with them. .TP Level 2 No restrictions apply. .RE .PP In all cases, receiving systems must fulfill the receiving system requirements specified in section 10 of the ISO standard (no equivalent section exists for HSG). .PP .B Interchange levels provide a way to specify the data structure and complexity that exists on a CD-ROM. The levels are: .RS .TP 12 Level 1 Each file consists of a single file section. File names contain no more than eight characters, and file name extensions contain no more than three. Directory names contain no more than eight characters. .TP Level 2 Each file consists of a single file section. .TP Level 3 No restrictions apply. .RE .SH DEPENDENCIES HP-UX supports only the primary volume descriptor. When a volume is mounted, HP-UX mounts the directory hierarchy described by the first primary volume descriptor it finds. Supplementary volume descriptors are recognized and ignored, as are their associated directory hierarchies. .PP Directory hierarchies spanning multiple volumes are not supported. .PP Volume sets consisting of more than one volume are not supported. .PP Path tables are ignored in HP-UX. The normal path name lookup scheme used in HFS file systems is used instead. This is done to allow other mountable file systems to be mounted on top of a mounted CDFS file system. Also, since HP-UX maintains a cache of cdnodes for CDFS files (see .IR cdnode (4)), the additional performance gains provided by path tables are minimal. .PP HP-UX does not support multiple file sections. Each file must be recorded in a single file section. .PP HP-UX supports level 1 implementation and level 2 interchange. .SH SEE ALSO fsctl(2), stat(2), cdnode(4). .PP .I "Information Processing \- Volume and File Structure of CD-ROM for" .IR "Information Interchange" , Ref. No. ISO 9660: 1988 (E). .PP .I "The Working Paper for Information Processing \(mi" .I "Volume and File Structure of Compact Read Only Optical Discs" .IR" for Information Interchange" , National Information Standards Organization [Z39]. .\" .\" index@\f4cdrom\f1 \- CD-ROM background information@@@\f3cdrom(4)\f1 .\" index@\f1CD-ROM: background information@@@\f3cdrom(4)\f1 .\" .\" toc@\f3cdrom(4)\f1:\0\0\f4cdrom\f1@@@CD-ROM background information .\" $Header: charmap.4,v 76.1 95/07/10 16:58:07 ssa Exp $ .TA c .TH charmap 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME charmap \- symbolic translation file for localedef scripts .SH SYNOPSIS .C localedef -f .I charmap .C locale_name .SH DESCRIPTION Invoking the .C localedef command with the .C -f option causes symbolic names in the .B locale description file to be translated into the encodings given in the .I charmap file (see .IR localedef (1M)). As a recommendation, a locale description file should be written completely with symbolic names. .PP The .I charmap file has two sections: a declarations section and a character definition section. .SS Declarations Section Declarations can precede the character definitions. .PP Each consists of the symbol (including the surrounding angle brackets), followed by one or more blanks (or tabs or space characters), followed by the value of the symbol. .PP Certain declarations are required for multibyte character codesets. For single-byte codesets, all are optional. .PP Following is a list of possible declarations: .PP .C .I value .IP Used to declare the name of the coded character set for which the charmap file is defined. This keyword is required for multibyte character codesets. For HP15 encoding scheme, .C HP15 needs to be part of the name. For EUC encoding scheme, .C EUC needs to be part of the name. .PP .C .I value .IP Used to declare the cswidth parameter of the coded character set for which the charmap file is defined (see .IR euset (1)). .PP .C .I value .IP Used to declare the maximum number of bytes in a multibyte character. Defaults to 1 if not given. For multibyte character codesets, this keyword must be specified. .PP .C .I value .IP Used to declare the minimum number of bytes in a character for the encoded character set. The value must be less than or equal to .CR . If not given, the default is equal to .CR . .PP .C .I value .IP Used to declare the escape character, which is used to escape characters that otherwise would have special meaning. If not given, the default is backslash .RC ( \e ). .PP .C .I value .IP Used to declare the comment character, which is used to begin comments and should be placed in column one of the .I charmap file. If not given, the default is the .C # character. .SS Character Definition Section The character-set mapping definitions immediately follow an identifier line containing the string .C CHARMAP and precede a trailer line consisting of the string .CR "END CHARMAP" . (Empty lines and lines beginning with the comment character are ignored.) .PP The character definitions are of two forms. .PP The first form defines a single character and its encoding: .IP .CI < symbolic_name > .I encoding .PP A .IR symbolic_name is one or more visible characters from the portable character set as specified by XPG, enclosed in angle brackets. Metacharacters such as angle brackets, escape characters, or comment characters must be escaped if they are used in the name. Two or more symbolic names can be given for the same encoding. .PP The .IR encoding is a character constant in one of three forms: .RS .TP 15 decimal An escape character followed by the letter .CR d , followed by one to three decimal digits. .TP octal An escape character followed by one to three octal digits. .TP hexadecimal An escape character followed by an .CR x , followed by two hexadecimal digits. .RE .PP Multibyte characters are represented by the concatenation of character constants. All constants used in the encoding of a multibyte character must be of the same form. .PP The second form defines a range of characters consisting of all characters from the first symbolic name to the second, inclusive: .IP .CI < symbolic_name >\c \&... .CI < symbolic_name > .I encoding .PP The symbolic name must consist of one or more nonnumeric characters followed by an integer formed of one or more decimal digits. The integer part of the second symbolic name must be larger than that of the first. The range is then interpreted as a list of symbolic names consisting of the same character portion and successive integer values from the first through the last. These names are assigned successive encodings starting with the one given. .PP For example, the character definition line .IP .C "... \ed129" .PP is equivalent to: .nf .IP .C " \ed129" .C " \ed130" .C " \ed131" .fi .SH EXAMPLES For examples, see any of the files under .CR /usr/lib/nls/loc/charmaps directory. .SH SEE ALSO localedef(1M), localedef(4). .SH STANDARDS COMPLIANCE .CR localedef " POSIX.2, XPG4." .\" .\" index@\f4charmap\f1 \- symbolic translation file for localedef scripts@@@\f3charmap(4)\f1 .\" index@\f1symbolic translation file for localedef scripts@@@\f3charmap(4)\f1 .\" index@\f1translation file for localedef scripts, symbolic@@@\f3charmap(4)\f1 .\" index@\f1file for localedef scripts, symbolic translation@@@\f3charmap(4)\f1 .\" index@\f1localedef scripts, symbolic translation file for@@@\f3charmap(4)\f1 .\" index@\f1scripts, symbolic translation file for localedef@@@\f3charmap(4)\f1 .\" .\" toc@\f3charmap(4)\f1:\0\0\f4charmap\f1@@@symbolic translation file for localedef scripts .\" $Header: core.4,v 78.1 96/05/24 06:46:08 ssa Exp $ .TA c .TH core 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME core \- format of core image file .SH DESCRIPTION The .SM HP-UX system writes out a file containing a core image of a terminated process when certain signals are received (see .IR signal (5) for the list of reasons). The most common causes are memory violations, illegal instructions, floating point exceptions, bus errors, and user-generated quit signals. The core image file is called .C core and is written in the process's working directory (provided it is allowed by normal access controls). A process with an effective user .SM ID different from its real user .SM ID does not produce a core image. .PP The file contains sufficient information to determine what the process was doing at the time of its termination. Core file contents consist of objects that represent different segments of a process. Each object is preceded by a .C corehead data structure, and each .C corehead data structure describes the corresponding object following it. The structure is defined in .RC < sys/core.h >, and includes the following members: .nf .IP .C "int type;" .C "space_t space;" .C "caddr_t addr;" .C "size_t len;" .fi .PP The .I space and .I addr members specify the virtual memory address in the process where the described object began. The .IR len member is the length of the object in bytes. .PP The following possible values for .IR type are defined in .RC < sys/core.h >: .RS .TP 18 .C CORE_DATA Process data as it existed at the time the core image was created. This includes initialized data, uninitalized data, and the heap at the time the core image is generated. .TP .C CORE_EXEC A compiler-dependent data structure containing the exec data structure, the magic number of the executable file, and the command (see the declaration of the .C proc_exec structure in .RC < sys/core.h >). .TP .C CORE_FORMAT The version number of the core format produced. This number changes with each .SM HP-UX release where the core format itself has changed. However, it does not necessarily change with every .SM HP-UX release. .C CORE_FORMAT can thus be easily used by core-reading tools to determine whether they are compatible with a given core image. This type is expressed by a four-byte binary integer. .TP .C CORE_KERNEL The null-terminated version string associated with the kernel at the time the core image was generated. .TP .C CORE_PROC An architecture-dependent data structure containing per-process information such as hardware register contents. See the declaration of the .CR proc_info structure in .RC < sys/core.h >. In Release 10.20, the field user_tid is not supported. .TP .C CORE_STACK Process stack contents at the time the core image was created. .RE .PP Objects dumped in a .C core image file are not arranged in any particular order. Use .C corehead information to determine the type of the object that immediately follows it. .SH SEE ALSO adb(1), cdb(1), xdb(1), setuid(2), crt0(3), end(3C), signal(5). .\" .\" index@\f4core\fP \- core image file format@@@\f3core(4)\f1 .\" index@format: core image file@@@\f3core(4)\f1 .\" index@core image file format@@@\f3core(4)\f1 .\" index@file format: core image files@@@\f3core(4)\f1 .\" .\" toc@\f3core(4)\f1:\0\0\f4core\fP@@@format of core image file .\" .\" fileset_database@core.4 SYS-ADMIN-MAN .\" $Header: cpio.4,v 74.1 95/03/23 17:45:28 ssa Exp $ .TA c .TH cpio 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME cpio \- format of cpio archive .SH DESCRIPTION .PP The .I header structure, when the .C -c option of .C cpio is not used (see .IR cpio (1)), is: .nf .IP .C struct { .C " short c_magic," .C " c_dev;" .C " ushort c_ino," .C " c_mode," .C " c_uid," .C " c_gid;" .C " short c_nlink," .C " c_rdev," .C " c_mtime[2]," .C " c_namesize," .C " c_filesize[2];" .C " char c_name[c_namesize rounded to word];" .C } Hdr; .fi .PP When the .C cpio -c option is used, the .I header information is described by: .nf .IP .C sscanf(Chdr,"%6ho%6ho%6ho%6ho%6ho%6ho%6ho%6ho%11lo%6ho%11lo", .C " &Hdr.c_magic,&Hdr.c_dev,&Hdr.c_ino,&Hdr.c_mode," .C " &Hdr.c_uid,&Hdr.c_gid,&Hdr.c_nlink,&Hdr.c_rdev," .C " &Longtime,&Hdr.c_namesize,&Longfile);" .fi .PP .I Longtime and .I Longfile are equivalent to .C Hdr.c_mtime and .CR Hdr.c_filesize , respectively. The contents of each file are recorded together with other items describing the file. Every instance of .C c_magic contains the constant 070707 (octal). The items .C c_dev through .C c_mtime have meanings explained in .IR stat (2). The length of the null-terminated path name .CR c_name , including the null byte, is given by .CR c_namesize . .PP The last record of the .I archive always contains the name .CR TRAILER!!! . Directories and the trailer are recorded with .C c_filesize equal to zero. .PP It will not always be the case that .C c_dev and .C c_ino correspond to the results of .CR stat() , but the values are always sufficient to tell whether two files in the archive are linked to each other. .PP When a device special file is archived by .SM HP-UX .C cpio (using the .C -x option), .C c_rdev contains a magic constant which is dependent upon the implementation doing the writing. .C H_rdev flags the device file as an .SM HP-UX 32-bit device specifier, and .C c_filesize contains the 32-bit device specifier (see .IR stat (2)). If the .C -x option is not present, special files are not archived or restored. Non-HPUX device special files are never restored. .SH SEE ALSO cpio(1), find(1), stat(2). .SH STANDARDS CONFORMANCE .CR cpio ": XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1" .\" .\" index@\f4cpio\fP \- format of cpio archive@@@\f3cpio(4)\f1 .\" index@format: cpio archive@@@\f3cpio(4)\f1 .\" index@cpio archive format@@@\f3cpio(4)\f1 .\" index@archive format, cpio@@@\f3cpio(4)\f1 .\" .\" toc@\f3cpio(4)\f1:\0\0\f4cpio\fP@@@format of cpio archive .\" .\" fileset_database@cpio.4 SYS-ADMIN-MAN .\" $Header: dialups.4,v 72.4 94/05/18 17:17:50 ssa Exp $ .TA d .TH dialups 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dialups, d_passwd \- dialup security control .SH DESCRIPTION .C dialups and .C d_passwd are used to control the dialup security feature of .C login (see .IR login (1)). If .C /etc/dialups is present, the first word on each line is compared with the name of the line upon which the login is being performed (including the .CR /dev/ , as returned by .C ttyname() (see .IR ttyname (3C)). If the login is occurring on a line found in .CR dialups , dialup security is invoked. Anything after a space or tab is ignored. .PP When dialup security is invoked, .C login requests an additional password, and checks it against that found in .CR /etc/d_passwd . The command name found in the ``program to use as shell'' field of .C /etc/passwd is used to select the password to be used. Each entry in .C d_passwd consists of three fields, separated by colons. The first is the command name, matching an entry in .CR passwd . The second is the encrypted password to be used for dialup security for those users logging in to use that program. The third is commentary, but the second colon is required to delimit the end of the password. A null password is designated with two adjacent colons. The entry for .C /usr/bin/sh is used if no other entry matches the command name taken from .CR passwd . .SH FILES .TP 25 .C /etc/dialups dial-in tty lines .PD 0 .TP .C /etc/d_passwd passwords .SH SEE ALSO login(1), passwd(4). .\" .\" index@\f4dialups\fP, \f2d_passwd\f1 \- dialup security control@@@\f3dialups(4)\f1 .\" index@\f2d_passwd\f1 \- dialup security control@@@\f3dialups(4)\f1 .\" .\" toc@\f3dialups(4)\f1:\0\0\f4dialups\fP, \f2d_passwd\f1@@@dialup security control .\" toc@\f2d_passwd\f1:\0\0dialup security control@@@see \f3dialups(4)\f1 .\" .\" links@dialups.4 d_passwd.4 .\" .\" fileset_database@dialups.4 SYS-ADMIN-MAN .\" -*-Text-*- .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .\" (c) Copyright 1987 - 1992, Hewlett-Packard Company, all rights reserved. .\";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .TH DATEBOOK 4 "" "" .ad b .SH NAME datebook \- event file format .SH DESCRIPTION The \fIdatebook\fP program uses an ascii file format to describe events. .SS File Format The general format of an event file looks like: .nf [==\fIdefaultclass\fP] \fImessage\fP [=\fIclass\fP] \fIdatespec\fP [\fItime\fP] . . . .fi .SS Grammar Description The following is a YACC-style specification for the \fIdatebook\fP event file grammar. Keywords are shown in \fBBold\fP and are defined below. .nf .TS ; li cb li. event : \fBMessage\fP \fBClass\fP datespec | \fBMessage\fP \fBClass\fP datespec timerange datespec : daterange | relativedate | periodic | datespec \fBExcept\fP datespec | datespec \fBLogical_And\fP datespec | datespec \fBOr\fP datespec | datespec \fBAnd\fP datespec | \fBNot\fP datespec .T& l s s. NOTE: All words in \fIdatespec\fP are case insensitive. The \fBAnd\fP operator behaves like "or" as in English usage. .T& li cb li. daterange : date \fBThru\fP date | \fBMonth\fP ',' \fBYear\fP | \fBMonth\fP \fBYear\fP | \fBMonth\fP | \fBInteger\fP '/' \fBYear\fP | \fBYear\fP relativedate : date | datespec duringrange | \fBNth\fP \fBDay\fP | \fBNth\fP \fBDay\fP duringrange | \fBNth\fP \fBDay\fP \fBBefore_Or_After\fP date | \fBInteger\fP \fBintervals\fP \fBBefore_Or_After\fP date | relativedate \fBBefore_Or_After\fP date duringrange : \fBBetween\fP date \fBAnd\fP date | \fBIn\fP daterange periodic : relativeday | \fBEvery\fP relativeday | \fBDay\fP \fBThru\fP \fBDay\fP | \fBEvery\fP \fBNth\fP \fBDay\fP \fBBefore_Or_After\fP date | \fBEvery\fP \fBInteger\fP \fBintervals\fP \fBBefore_Or_After\fP date .T& l s s. NOTE: \fBDay\fP can not be "Weekday" .T& li cb li. relativeday : \fBDay\fP | \fBDay\fP \fBBefore_Or_After\fP date date : \fBMonth\fP \fBInteger\fP ',' \fBYear\fB | \fBInteger\fP \fBMonth\fP ',' \fBYear\fP | \fBMonth\fP \fBInteger\fP \fBYear\fP | \fBInteger\fP \fBMonth\fP \fBYear\fP | \fBInteger\fP '/' \fBInteger\fP '/' \fBYear\fP | \fBInteger\fP '/' \fBInteger\fP | \fBMonth\fP \fBInteger\fP | \fBInteger\fP \fBMonth\fP | \fBToday\fP timerange : time | time \fBThru\fP time | \fBAt\fP time | \fBAt\fP time \fBThru\fP time time : \fBInteger\fP ':' \fBInteger\fP | \fBInteger\fP ':' \fBInteger\fP \fBAm_Or_PM\fP | \fBInteger\fP \fBAm_Or_Pm\fP .TE .fi .SS Keywords All of the following are case insensitive. .TP 12 \fBAm_Or_Pm\fP am, a.m., pm, p.m. .TP 12 \fBAnd\fP and .TP 12 \fBAt\fP at .TP 12 \fBBefore_Or_After\fP after, >, starting, >=, onorafter, before, <, until, ending, <=, onorbefore. .TP 12 \fBBetween\fP between .TP 12 \fBClass\fP = .TP 12 \fBDay\fP Weekday, Everyday, name of a day (e.g. \fIFriday\fP), or the first three letters of the name of a day (e.g. \fIFri\fP). .TP 12 \fBEvery\fP every. .TP 12 \fBExcept\fP except. .TP 12 \fBIn\fP during, in, from, of. .TP 12 \fBInteger\fP Represents a day of the month (\fI1-31\fP), a month of the year (\fI1-12\fP), a count of intervals (\fI1-59\fP), an hour (\fI0-24\fP), or a minute (\fI0-59\fP). .TP 12 \fBIntervals\fP day, days, week, weeks, month, months, year, years. .TP 12 \fBLogical_And\fP &&. .TP 12 .B Message Any string or characters enclosed in matching characters from the set: '' "" () {} [] .TP 12 \fBMonth\fP Can be "Everymonth", the entire name of a month (e.g. \fIJanuary\fP), or the first three letters of the name of a month (e.g. \fIJan\fP). .TP 12 \fBNot\fP not. .TP 12 \fBNth\fP From the sequence \fI1st\fP, \fI2nd\fP, \fI3rd\fP, \fI4th\fP, \fI5th\fP, ..., \fI59th\fP. The words \fIfirst\fP, \fIsecond\fP, ... \fItwentieth\fP are also allowed. The keyword \fIlast\fP can also be used to specify a date prior to another date. .TP 12 \fBOr\fP or. .TP 12 \fBStarting\fP starting. .TP 12 \fBThru\fP through, thru, to, or "-". .TP 12 \fBToday\fP today, tomorrow, or yesterday. .TP 12 \fBYear\fP Of the form \fI1989\fP or \fI89\fP. .SS Combination Precedence .nf There are several ways to combine datespecs: datespec IN daterange (or BETWEEN date AND date) datespec EXCEPT datespec datespec OR datespec datespec LOGICAL_AND datespec NOT datespec The associativity and precedence when combining more than one datespec is: NOT left associative highest precedence LOGICAL_AND left associative OR AND left associative EXCEPT right associative BETWEEN IN non associative lowest precedence .fi .SH EXAMPLE DATE FILE A sample event file might look like this: .nf ==meeting "Joan's Birthday" =birthday October 10 "Project Meeting in the Sea Breeze room" Monday 2:00 PM "monthly report due" 1st weekday "Doctor's appointment" =doctor 2nd Tuesday at 3:30 PM "staff meeting" Tuesday except April 25 at 1:00 PM "Section meeting 10-11 in the Auditorium" March 18,1993 at 10 am "Leave Early" Today "Pay Day" Last weekday onorbefore 15 Everymonth [SEPC]=offsite Aug 1 - Aug 5 at 8:30 "mail tax return"=nag 1 week before 15 April "Memorial Day" =holiday last Monday in May "Memorial Day" =holiday 1st Monday before 31 May .fi The line \fB==meeting\fP specifies that the default class for all events in this file is \fBmeeting\fP. All but six of the events will use the default class. The first event will have the class \fBbirthday\fP. The fourth event will have the class \fBdoctor\fP. The last four events use the classes \fBoffsite\fP, \fBnag\fP, and \fBholiday\fP (twice). The last two events show two alternative ways to specify the same date. Note that \fBdatebook\fP may interpret and rewrite date specifications with different syntax, but equivalent semantics. For example, datebook would read the date specification for the "Pay Day" event and rewrite it as "last weekday ending Everymonth 15." Datebook also would translate the "Leave Early" date specification "Today" into today's date. .SH SEE ALSO datebook(1) .\" $Header: default.4,v 72.2 94/08/30 14:09:05 ssa Exp $ .TA d .TH default 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME default \- system default database file for a trusted system .SH SYNOPSIS .nf .CR "/tcb/files/auth/system/default" .fi .SH DESCRIPTION The system default database is unique in that it defines system-wide global parameters for a trusted system. It is designed to provide values for users and devices on a global scale rather than requiring an administrator to replicate values in user or device databases when they are all the same. In addition to being easier to specify global values, it is also much easier to make a global system change if necessary. .PP The system default database is made up of four types of values: .TP 30 system-wide parameters These are parameters that do not have corresponding specifications in any other trusted system database. If a system-wide parameter is not specified in the default database, then it is undefined. .TP 30 user parameters These parameters are typically specified in a protected password database file. .TP 30 terminal control parameters These parameters are typically specified in the terminal control database file. .TP 30 device assignment parameters These parameters are typically specified in the device assignment database file. .PP System default parameters may be specified for fields found in the protected password, terminal control, and device assignment databases. When a specific entry is retrieved from one of these databases, a structure called, .IR ufld that contains all of the explicitly specified values, is provided to the caller. A second structure, called .IR sfld , is also provided which defines those values supplied from the system default database. Each of these structures has a corresponding flag structure called .IR uflg and .IR sflg , respectively, that indicates which fields in each structure have been specified and are valid for use. Programs honor the user or device specific value first if one is provided. Otherwise, the program may choose to use the system default value if one has been specified. If neither value is specified, the program may supply a reasonable default value or abort. .PP For descriptions of the specific fields provided by the protected password, terminal control, and device assignment databases, see the corresponding manual pages listed in the SEE ALSO section for those databases. The following fields are unique to the system default database and can not be specified in any of the other system databases. .TP 25 .C d_name This name is set to the string "default". .TP 25 .C d_boot_authenticate This flag field indicates whether or not boot authentication is required to boot the machine. If authentication is required, it is performed by the system .IR init(1M) program prior to completing system boot. .SH "EXAMPLES" The following is an example of a typical system default database. Refer to .IR authcap(4) for descriptions of the file and line formats. .PP .IP .nf .ift .sp -1v default:\\ :d_name=default:\\ :d_boot_authenticate@:\\ :u_pwd=*:\\ :u_minchg#0:u_maxlen#10:u_exp#15724800:u_life#31449600:\\ :u_pickpw@:u_genpwd@:u_restrict@:u_nullpw@:\\ :u_genchars@:u_genletters@:\\ :u_maxtries#5:u_lock:\\ :t_logdelay#2:t_maxtries#10:\\ :chkent: .fi .PP This system default database defines the four different types of values which are supported. First, values that can be assigned on a system-wide only basis are defined. Boot authentication at system startup is not enabled. Login programs will provide password expiration warnings if the password expires in less than 604800 seconds from the current system time (this translates into 60*60*24*7 or 7 days). .PP The system default database also defines numerous protected password database default values. Fields that begin with .C u_ correspond to protected password fields. Similarly, fields starting with the .C t_ prefix are terminal control database fields. These field types are used to supply system-wide default values if a user or device specific value is not supplied by the corresponding database. See the appropriate manual pages listed in the SEE ALSO section for these databases for a complete description of the applicable fields. .SH FILES .TP 50 .CR /tcb/files/auth/system/default system default database file for a trusted system; see .IR authcap(4) .TP 50 .CR /tcb/files/auth/*/* protected password database files; see .IR prpwd(4) .TP 50 .CR /tcb/files/ttys terminal control database file; see .IR ttys(4) .TP 50 .CR /tcb/files/devassign device assignment database file; see .IR devassign(4) .SH AUTHOR SecureWare Inc. .SH "SEE ALSO" getprdfent(3), authcap(4), devassign(4), prpwd(4), ttys(4). .PD 0 .\" .\" index@\f4default\f1 \- system default database file for a trusted system@@@\f3default(4)\f1 .\" index@\f1default database file, trusted system@@@\f3default(4)\f1 .\" index@\f1system default database file, trusted system@@@\f3default(4)\f1 .\" index@\f1trusted system, system default database file@@@\f3default(4)\f1 .\" .\" toc@\f3default(4)\f1@@@system default database file for a trusted system .\" .\" fileset_database@default.4 .\" $Header: devassign.4,v 78.1 96/02/12 13:38:11 ssa Exp $ .TA d .TH devassign 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME devassign \- device assignment database file for a trusted system .SH SYNOPSIS .nf .CR "/tcb/files/devassign" .fi .SH DESCRIPTION The system supports a single device assignment database that contains entries for local and remote login terminals. .PP The format of the terminal control database file is identical to other trusted system authentication database files. For more information on the file format, see .IR authcap(4) . The file consists of keyword field identifiers and values for those fields. The keyword identifiers supported and their use include: .TP 15 .C v_devs This field specifies a comma separated list of aliases that refer to the same device defined by the entry. Use of this field avoids the need to replicate device assignment database entries for all device aliases. .TP 15 .C v_type This field specifies the device that is described by the entry. Device types supported include: .RS 20 .TP 15 .C terminal The device is assigned as a local or remote login terminal device. .RE .TP 15 .C v_users This field, if specified, contains a comma separated list of user names that are permitted to use the device for login or the import\^/\^export of data. If the list is not present, all users are permitted to use the device. If the list is present, it is searched for a match by the .IR login program to determine if the user is permitted to use the device. .PP .SH "EXAMPLES" The following is an example of a device assignment database entry for a terminal device assigned as a login device: .PP .IP .nf .ift .sp -1v tty0:v_devs=/dev/tty0:\\ :v_type=terminal:\\ :chkent: .fi .SH AUTHOR SecureWare Inc. .SH "SEE ALSO" cpio(1), login(1), tar(1), getdvagent(3), authcap(4), default(4). .PD 0 .\" .\" index@\f4devassign\f1 \- trusted system device assignment database file@@@\f3devassign(4)\f1 .\" index@\f1trusted system device assignment database file@@@\f3devassign(4)\f1 .\" index@\f1database file, trusted system device assignment@@@\f3devassign(4)\f1 .\" index@\f1system, trusted system device assignment database file@@@\f3devassign(4)\f1 .\" index@\f1trusted system, system device assignment database file@@@\f3devassign(4)\f1 .\" .\" toc@\f3devassign(4)\f1@@@device assignment database file for a trusted system .\" .\" $Header: devices.4,v 72.3 93/01/14 16:00:31 ssa Exp $ .TA d .TH devices 4 "" "Series 800 Only" .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .\" does not apply to Series 700 .SH NAME devices \- file of driver information for insf, mksf, lssf .SH DESCRIPTION The .C devices file contains a description of .SM I/O drivers, pseudo-drivers, hardware addresses and block/character major numbers. It is created by .C uxgen (see .IR uxgen (1M)). This file normally resides in the directory .CR /etc . .PP This is an .SM ASCII file consisting of zero or more lines where each line is terminated by a new-line character. Each line begins with a name which normally represents an .SM I/O driver or pseudo-driver. Tokens are separated by white space. .PP Each parameter in the line is preceded by a keyword. All parameters are optional. The keywords are: .CR lu , .CR address , .CR b_major , and .CR c_major . representing logical unit number, hardware address, block major number, character major number, respectively. Parameters can appear in any order after the name; however, they must be directly preceded by their keyword. .PP The following lines represent typical entries in a .C devices file: .nf .IP .C "cn c_major 0" .C "disc0 lu 0 address 28.0.0 b_major 0 c_major 4" .C "disc0 lu 1 address 28.0.2 b_major 0 c_major 4" .fi .SH AUTHOR .C devices was developed by HP. .SH SEE ALSO insf(1M), mksf(1M), lssf(1M), uxgen(1M). .\" .\" index@\f4devices\fP \- file of driver information for \f4insf\fP, \f4mksf\fP, \f4lssf\fP@@@\f3devices(4)\f1 .\" index@file, driver: driver information for \f4insf\fP, \f4mksf\fP, \f4lssf\fP@@@\f3devices(4)\f1 .\" index@driver information file for \f4insf\fP, \f4mksf\fP, \f4lssf\fP@@@\f3devices(4)\f1 .\" index@information file, driver, for \f4insf\fP, \f4mksf\fP, \f4lssf\fP@@@\f3devices(4)\f1 .\" .\" toc@\f3devices(4)\f1:\0\0\f4devices\fP@@@file of driver information for \f4insf\fP, \f4mksf\fP, \f4lssf\fP .\" .\" fileset_database@devices.4 SYS-ADMIN-MAN ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993, 1994 Open Software Foundation, Inc. ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE for ...\" the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "dfs_intro" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .iX "-[" "Distributed File Service (DFS)" "system files" .SH NAME .PP \*Ldfs_intro\*O \- Introduction to \*LDFS\*O files .SH "DESCRIPTION" .PP DFS includes a number of system-specific files. These files can be grouped into the following general categories: .VL .LI "\*LConfiguration files\*O" Define configuration parameters for specific server and kernel processes such as a Tape Coordinator or Cache Manager. .LI "\*LAdministrative lists\*O" List the principals (users, groups, and servers) allowed to access specific server processes, including the Backup Server, the Basic OverSeer Server, the Fileset Server, the Fileset Location Server, and the Update Server. .LI "\*LCache-related files\*O" Contain cached data or information about cached data. .LI "\*LLog files\*O" Contain output from specific processes or commands. .LE .PP .zA "defect,10439,R1.1,Fix cross-references for DFS reorganization" Specific information about the files, such as pathnames and format, is included with the reference pages that describe them. Most of the files are referred to in Part 1 of the \*(Ad. Refer to Part 1 of that document for more information about these files and the DFS components and commands with which they are associated. .zZ "defect,10439,R1.1,Fix cross-references for DFS reorganization" .SH "RELATED INFORMATION" .PP .zA "enh,5923,R1.1,remove cross-refs to User Guide and Ref" Following is a list of all relevant DFS files for which reference pages are included. See the DCE DFS portion of this reference for information about any of the commands referenced in these pages. .zZ "enh,5923,R1.1,remove cross-refs to User Guide and Ref" .ML .LI Configuration files: .VL .LI "\*LBosConfig(4)\*O" .LI "\*LCacheInfo(4)\*O" .zA "defect,10418,R1.1,Remove lingering refs to dfsatab file" .zZ "defect,10418,R1.1,Remove lingering refs to dfsatab file" .LI "\*Ldfstab(4)\*O" .LI "\*LNoAuth(4)\*O" .LI "\*LTapeConfig(4)\*O" .LE .LI Administrative files: .VL .LI "\*Ladmin.bak(4)\*O" .LI "\*Ladmin.bos(4)\*O" .LI "\*Ladmin.fl(4)\*O" .LI "\*Ladmin.ft(4)\*O" .LI "\*Ladmin.up(4)\*O" .LE .LI Cache-related files: .VL .LI "\*LCacheItems(4)\*O" .LI "\*LFilesetItems(4)\*O" .LI "\*LVn(4)\*O" .LE .LI Log files: .VL .LI "\*LBakLog(4)\*O" .LI "\*LBosLog(4)\*O" .zA "defect,6062,R1.0.2,Remove cm debug command" .zZ "defect,6062,R1.0.2,Remove cm debug command" .zA "defect,1069,R1.0.2,Remove FileLog file" .zZ "defect,1069,R1.0.2,Remove FileLog file" .zA "defect,11180,R1.1,Incorporate DFS/NFS gateway doc" .LI "\*LDfsgwLog(4)\*O" .zZ "defect,11180,R1.1,Incorporate DFS/NFS gateway doc" .LI "\*LFlLog(4)\*O" .LI "\*LFMSLog(4)\*O" .LI "\*LFtLog(4)\*O" .LI "\*LRepLog(4)\*O" .zA "defect,6960,R1.0.2,Remove SalvageLog file" .zZ "defect,6960,R1.0.2,Remove SalvageLog file" .LI "\*LTE(4)\*O" .LI "\*LTL(4)\*O" .LI "\*LUpLog(4)\*O" .LE .LE ...\" ...\" ...\" ...\" (c) Copyright 1990, 1991, 1992, 1993, 1994 OPEN SOFTWARE FOUNDATION, INC. ...\" ALL RIGHTS RESERVED ...\" ...\" OSF DCE Version 1.1 ...\" .so /usr/share/lib/macros/osfhead.rsml .so /usr/share/lib/macros/sml .so /usr/share/lib/macros/rsml ...\" ...\" COPYRIGHT NOTICE ...\" Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc. ...\" Copyright (C) 1989, 1991, 1992, 1993 Transarc Corporation ...\" ALL RIGHTS RESERVED (DCE). See the file named COPYRIGHT.DCE in the ...\" src directory for the full copyright text. ...\" ...\" ...\" ...\" (c) Copyright 1991, Open Software Foundation, Inc. ALL RIGHTS RESERVED ...\" .rm zA .rm zZ .TH "dfstab" "4" "" "" "" .ds )H Hewlett-Packard Company .ds ]W OSF DCE 1.1/HP DCE 1.5 ...\"DOCUMENTSTYLE [12pt]{book} .SH NAME .iX "-[" "\*Ldfstab\*O file" .iX "-[" "aggregates" "specifying for export" .PP \*Ldfstab\*O \- Specifies DCE LFS aggregates and non-LFS partitions that can be exported .SH "DESCRIPTION" .PP The \*Ldfstab\*O file includes information about each DCE LFS aggregate and each non-LFS partition that can be exported from the local disk to the DCE namespace. The file is read by the \*Ldfsexport\*O command, which exports specified aggregates and partitions to the DCE namespace. (It is also read by the \*Lnewaggr\*O command, which initializes DCE LFS aggregates.) The \*Ldfstab\*O file must reside in the directory named \*Edcelocal\*L/var/dfs\*O. The \*Ldfsexport\*O command looks in that directory for the file; if the file is not there, no aggregates or partitions can be exported. .PP The \*Ldfstab\*O file is an ASCII file that can be created and edited with a text editor. You must have write and execute permissions on the \*Edcelocal\*L/var/dfs\*O directory to create the file. You must have write permission on the file to edit it. .PP The file contains a one-line entry for each aggregate or partition available for exporting. Each entry in the file must appear on its own line. The fields in the following list must appear for each entry; they must appear in the order listed, and each field must be separated by at least one space or tab. Because DCE LFS aggregates contain an arbitrary number of filesets, \*Edo not include a fileset ID number when creating an entry for a DCE LFS aggregate\*O. .VL 15 .LI "\*LDevice name\*O" The block device name of the aggregate or partition to be exported; for example, \*L/dev/lv02\*O. .LI "\*LAggregate name\*O" The name to be associated with the aggregate or partition to be exported. An aggregate name can contain any characters, but it cannot be longer than 31 characters. It must be different from any other aggregate name in the \*Ldfstab\*O file. Aggregate names cannot be abbreviated, so you should choose a short, descriptive name; for example, \*Llfs1\*O. The aggregate name of a non-LFS partition must match the name of the partition's local mount point (for example, \*L/usr\*O). .LI "\*LFile system type\*O" The identifier for the type of file system housing the aggregate or partition. For DCE LFS aggregates, this must be \*Llfs\*O; for non-LFS partitions, it must be \*Lufs\*O. Enter the identifier in all lowercase letters. .LI "\*LAggregate ID\*O" A positive integer different from any other aggregate ID in the \*Ldfstab\*O file. In the entry for a non-LFS partition, this field must contain the aggregate ID number specified with the \*L-aggrid\*O option of the \*Lfts crfldbentry\*O command. .LI "\*LFileset ID\*O" The unique fileset ID number to be associated with the fileset on a non-LFS partition; for example, \*L0,,18756\*O. In the entry for a non-LFS partition, this field must contain the fileset ID number generated with the \*Lfts crfldbentry\*O command. \*EDo not include a fileset ID number with an entry for a DCE LFS aggregate.\*O .LE .PP .zA "defect,10418,R1.1,Remove lingering refs to dfsatab file" When the \*Ldfsexport\*O command is executed, it reads the \*Ldfstab\*O file to verify that each aggregate or partition to be exported is listed in the file. An aggregate or partition must have an entry in the \*Ldfstab\*O file if it is to be exported. To ensure that it does not export an aggregate or partition that is currently exported, the \*Ldfsexport\*O command refers to a list of all currently exported aggregates and partitions that exists in the kernel of the local machine. .zZ "defect,10418,R1.1,Remove lingering refs to dfsatab file" .SH "CAUTIONS" .PP .iX "aggregates" "changing ID numbers" Do not change the aggregate ID number assigned to an aggregate or partition in this file once Fileset Location Database (FLDB) entries have been created for filesets on the aggregate or partition. Changing the aggregate ID number used for an aggregate or partition in this file invalidates existing FLDB entries for filesets on the aggregate or partition. .SH "EXAMPLES" .PP The following \*Ldfstab\*O file specifies that one non-LFS partition (\*L/dev/lv02\*O) and two DCE LFS aggregates (\*L/dev/lv03\*O and \*L/dev/lv04\*O) can be exported: .oS \*C/dev/lv02\ \ \ \ \ \ /usr\ \ ufs\ \ \ 1\ \ 0,,18756 /dev/lv03\ \ \ \ \ \ lfs1\ \ lfs\ \ \ 3 /dev/lv04\ \ \ \ \ \ lfs2\ \ lfs\ \ 11\*O .oE .SH "RELATED INFORMATION" .PP Commands: \*Ldfsexport(1m)\*O, \*Lfts crfldbentry(1m)\*O .zA "defect,10418,R1.1,Remove lingering refs to dfsatab file" .zZ "defect,10418,R1.1,Remove lingering refs to dfsatab file" .iX "-]" "\*Ldfstab\*O file" .iX "-]" "aggregates" "specifying for export" .iX "-]" "Distributed File Service (DFS)" "system files" .\" $Header: dialups.4,v 72.4 94/05/18 17:17:50 ssa Exp $ .TA d .TH dialups 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dialups, d_passwd \- dialup security control .SH DESCRIPTION .C dialups and .C d_passwd are used to control the dialup security feature of .C login (see .IR login (1)). If .C /etc/dialups is present, the first word on each line is compared with the name of the line upon which the login is being performed (including the .CR /dev/ , as returned by .C ttyname() (see .IR ttyname (3C)). If the login is occurring on a line found in .CR dialups , dialup security is invoked. Anything after a space or tab is ignored. .PP When dialup security is invoked, .C login requests an additional password, and checks it against that found in .CR /etc/d_passwd . The command name found in the ``program to use as shell'' field of .C /etc/passwd is used to select the password to be used. Each entry in .C d_passwd consists of three fields, separated by colons. The first is the command name, matching an entry in .CR passwd . The second is the encrypted password to be used for dialup security for those users logging in to use that program. The third is commentary, but the second colon is required to delimit the end of the password. A null password is designated with two adjacent colons. The entry for .C /usr/bin/sh is used if no other entry matches the command name taken from .CR passwd . .SH FILES .TP 25 .C /etc/dialups dial-in tty lines .PD 0 .TP .C /etc/d_passwd passwords .SH SEE ALSO login(1), passwd(4). .\" .\" index@\f4dialups\fP, \f2d_passwd\f1 \- dialup security control@@@\f3dialups(4)\f1 .\" index@\f2d_passwd\f1 \- dialup security control@@@\f3dialups(4)\f1 .\" .\" toc@\f3dialups(4)\f1:\0\0\f4dialups\fP, \f2d_passwd\f1@@@dialup security control .\" toc@\f2d_passwd\f1:\0\0dialup security control@@@see \f3dialups(4)\f1 .\" .\" links@dialups.4 d_passwd.4 .\" .\" fileset_database@dialups.4 SYS-ADMIN-MAN .\" $Header: dir.4,v 72.3 93/01/14 16:02:14 ssa Exp $ .TA d .TH dir 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dir \- format of directories on short-name HFS file systems .SH SYNOPSIS .C #include .br .C #include .SH REMARKS This entry describes the System V-compatible directory format for the .SM HFS file system. It is provided strictly for backward compatibility and compatibility with applications expecting a System V file system environment. It is not compatible with the similar but more general .SM HFS directory format in .RC < dirent.h >, which describes a format identical to that used in an .SM HFS file system supporting long file names up to 255 bytes in length. .PP The .C dirent structure defined in .RC < dirent.h > should be used in conjunction with the .IR directory (3C) routines for portability to other industry .SM UNIX implementations. .SH DESCRIPTION A directory behaves exactly like an ordinary file, except that no user can write into a directory. The fact that a file is a directory is indicated by a bit in the flag word of its i-node entry (see .IR fs (4)). The structure of a directory entry as given in the .RC < sys/dir.h > header file is: .nf .IP .C "#define DIRSIZ 14" .C "#define DIRSIZ_CONSTANT 14" .C "#define DIR_PADSIZE 10" .C "#define MAXNAMLEN 255" .C "struct direct {" .C " u_long d_ino; /* inode number of entry */" .C " u_short d_reclen; /* length of this record */" .C " u_short d_namlen; /* length of string in d_name */" .C " char d_name[DIRSIZ_CONSTANT];" .C " char d_pad[DIR_PADSIZE];" .C }; .sp .C /* .C " * DIRSTRCTSIZ is the number of bytes in the structure" .C " * representing a System V-compatible (14-character" .C " * maximum file name length) HFS directory entry." .C " */" .sp .C "#define DIRSTRCTSIZ 32 /* sizeof(struct direct) */ .fi .PP By convention, the first two entries in each directory are for .C . and .C .. (``dot'' and ``dot dot''). The first is an entry for the directory itself. The second is for the parent directory. The meaning of .C .. is modified for the root directory of the master file system; there is no parent, so .C .\|. and .C . have the same meaning. .SH AUTHOR .C dir was developed by AT&T and HP. .SH SEE ALSO fs(4), directory(3C). .\" .\" index@\f4dir\fP \- format of directories@@@\f3dir(4)\f1 .\" index@format: directories@@@\f3dir(4)\f1 .\" index@directory format@@@\f3dir(4)\f1 .\" index@disk directory format@@@\f3dir(4)\f1 .\" .\" toc@\f3dir(4)\f1:\0\0\f4dir\fP@@@format of directories on short-name \s-1HFS\s+1 file systems .\" .\" fileset_database@dir.4 SYS-ADMIN-MAN .\" $Header: disktab.4,v 72.4 94/07/05 16:23:56 ssa Exp $ .TA d .TH disktab 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME disktab \- disk description file .SH SYNOPSIS .CR #include .SH DESCRIPTION .CR disktab is a simple database that describes disk geometries. Entries in .CR disktab consist of a number of colon-separated fields. The first entry for each disk gives the names by which the disk is known, separated by vertical bar .RC ( | ) characters. .PP This file is provided for backward compatibility with previous HP-UX releases only. Its use is discouraged. .PP The following list indicates the normal values stored for each disk entry. Sectors are of size .CR DEV_BSIZE , defined in .RC < sys/param.h >. .RS .PP .TS cB cB lB cf4p+1 cf4p+1 l. Name Type Description _ ns num Number of sectors per track nt num Number of tracks per cylinder nc num Total number of cylinders on the disk b0 num Block size (bytes) f0 num Fragment size (bytes) s0 num Size of disk in sectors rm num Revolution per minute .TE .PP Example: .IP .nf .CR HP_7914: .CR " :132.1 MB:ns#16:nt#7:nc#1152:\" .CR " :s0#129024:b0#8192:f0#1024:\" .CR " :se#256:rm#3600:" .fi .SH AUTHOR .CR disktab was developed by HP and the University of California, Berkeley. .SH FILES .CR /etc/disktab .SH SEE ALSO newfs(1M), getdiskbyname(3C). .\" .\" index@\f4disktab\f1 \- disk description file@@@\f3disktab(4)\f1 .\" index@\f1disk description file@@@\f3disktab(4)\f1 .\" index@\f1file format: disk description file format@@@\f3disktab(4)\f1 .\" .\" toc@\f3disktab(4)\f1:\0\0\f4disktab\f1@@@disk description file .\" $Header: dosif.4,v 72.5 94/09/20 15:49:54 ssa Exp $ .TA d .TH dosif 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME \s-1DOSIF\s+1 \- \s-1DOS\s+1 Interchange Format description .SH DESCRIPTION .SM DOSIF (\c .SM DOS Interchange Format) is the name given to the media format used by the .SM DOS operating system. This format is based upon that used in .SM IBM PC and .SM PC AT and .SM HP Vectra systems. .PP The .SM DOS utilities described in Section 1 (referred to hereafter as .IR dos \(**(1)) are provided for reading data from and writing data to .SM DOSIF volumes. Use these utilities to retrieve information from a .SM DOSIF volume. .PP The .IR dos \(**(1) utilities are the only .SM HP-UX commands that can interact directly with the contents of a .SM DOSIF volume. The only other way to interact with the contents of a .SM DOSIF volume is to use an .SM HP-UX DOS emulation or coprocessor facility such as Soft\c .SM PC or the .SM DOS Coprocessor. .C mount cannot be used on a .SM DOSIF volume because the operating system does not recognize it (see .IR mount (1)). .PP When constructing file names for .IR dos \(**(1) commands, start with the .SM HP-UX path name of the .SM DOSIF volume, then add a colon .RC ( : ) followed by the file name: .IP .IC device_file \|:\| file .PP or .IP .IC path_name \|:\| file .PP .C Note: This file naming convention is suitable for use only in arguments to the .IR dos \(**(1) utilities. It does not constitute a legal path name for any other use in .SM HP-UX applications. .PP Metacharacters .CR * , .CR ? , and .CR [ \0...\0 ] can be used when specifying both .SM HP-UX and .SM DOS file names. These must be quoted when specifying a .SM DOS file name, because file name expansion must be performed by the .SM DOS utilities, not by the shell. The .IR dos \(**(1) utilities expand file names as described in .IR regexp (5) under .I PATTERN MATCHING .IR NOTATION . .PP By convention, if the .SM HP-UX device name and a trailing colon are specified, but no file or directory name is provided (for example, .CR /dev/rdsk/c1t1d0: ), the root .RC ( / ) of the .SM DOS file system is assumed. .SH EXAMPLES Specify .SM DOSIF file .C /dos/ivy accessed through .SM HP-UX special file .CR /dev/rdsk/c1t1d0 : .IP .C /dev/rdsk/c1t1d0:/dos/ivy .PP Specify .SM DOSIF file .C /math accessed through the .SM DOS volume stored as .SM HP-UX file .CR /home/mydir/driveC : .IP .C /home/mydir/driveC:/math .PP .SH SEE ALSO dos2ux(1), doschmod(1), doscp(1), dosdf(1), dosls(1), dosmkdir(1), dosrm(1). .\" .\" index@\s-1DOSIF\s+1 \- \s-1DOS\s+1 Interchange Format description@@@\f3dosif(4)\f1 .\" index@description, \s-1DOS\s+1 Interchange Format@@@\f3dosif(4)\f1 .\" .\" toc@\f3dosif(4)\f1:\0\0\f4dosif\f1@@@\s-1DOS\s+1 Interchange Format description\f1 .\"$Header: dp.4,v 74.1 95/05/10 21:30:13 ssa Exp $ .TA d .TH dp 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME dp \- dedicated ports file used by \s-1DDFA\s0 software and Telnet port identification feature .SH DESCRIPTION The .C dp file has two uses: .RS .TP .B "Datacommunications and Terminal Controller Device File Access" The .C dp file is used by the Datacommunications and Terminal Controller Device File Access .SM (DDFA) software to allow terminal server ports to be programmatically accessed from .SM HP-UX applications in the same way as devices connected directly to the .SM HP-UX system. It contains a one-line entry for each configured terminal server port. .IP The .C dp file contains the information the .SM DDFA software needs to set up and manage an outbound connection to a specified terminal server port. The file is parsed by the Dedicated Port Parser .RC ( dpp ) which spawns an Outbound Connection Daemon .RC ( ocd ) for each outbound connection specified in the file. .TP .B Telnet Port Identification The .C dp file is used by the .SM HP-UX telnet daemon .RC ( telnetd ) to identify the calling port and board of a telnet connection from an .SM HP Datacommunications and Terminal Controller .SM (DTC). .IP At connection time, the host negotiates the telnet environment option and the .SM DTC replies with the port and board number of the connecting device. .C Telnetd maps the port and board numbers to the well-known name for the device, which has previously been configured in the .C dp file. .SS "Datacommunications and Terminal Controller Device File Access" For outbound connections, an entry should have the following format: .IP .IC "dtc_name board" / "port pseudonym config_file log_level" .PP The exact details of each field are given below. .SS Telnet Port Identification To configure the .C dp file for using the Telnet port identification feature, the default file .C /usr/examples/ddfa/dp should be copied to a new file and the copy configured with the appropriate values for the incoming connections. The recommended procedure is to create a directory to hold the .C dp file and the modified port configuration files. .PP An entry for this purpose should have the following format: .IP .IC "dtc_name board" / "port pseudonym" .PP The exact details of each field are given below. .SS Configuration Information There are three ways to specify a terminal server port: .RS .TP 3 \(bu Explicitly specify its .SM IP address. .TP \(bu Specify the node name or the .SM IP address of the .SM DTC then specify the board and port. .TP \(bu Specify the node name or the .SM IP address of the terminal server and the .SM TCP port service address of the port. .RE .PP Comments in the .C dp file can be appended by starting them with a .C # character. Everything after the .C # is ignored by the parser. Fields in the .C dp file are separated by space characters. .PP See .IR ddfa (7) for more information on how to configure the .SM DDFA software. .PP The fields of an entry of the .C dp file are as follows: .TP 18 .I dtc_name This field is the node name or the .SM IP address of the terminal server being accessed or the .SM IP address of the port on the terminal server. A node name must be defined in a name database. .TP 18 .IC board / port This field contains the terminal server port address with the parts separated by the .C / character. It is not necessary to pad the values with leading zeros. The port address is not checked by .CR dpp , but is checked by .CR ocd . Valid values are 0 through 7 for .IR board , and 0 through 31 for .I port (these restrictions do not apply if the .SM TCP port service address is specified instead). .IP If the .I dtc_name field explicitly defines the node name or the IP address of the terminal server port, the value in the .IC board / port field must be .C xx/xx (use .C X or .CR x ). .IP If the field is of the form .CI xx/ n where .I n is a decimal number, .I n is assumed to be the .SM TCP port service address and it is used when the connection is established. .TP .I pseudonym This field is the absolute path of the device file known to the system and the end-user application. The device file name portion of the path name is limited to 14 characters. .TP .I pc_file_path This field is the path to a port configuration file which contains the configuration information for the terminal server port. This field is mandatory for outbound connections as .C dpp uses the presence of this field as its flag to spawn a daemon for the entry. .TP .I log_level This field is the logging level for the particular .C ocd and it determines the severity of messages sent to .CR /var/adm/syslog . The logging levels (and how they relate to system logging levels) are as follows: .RS .TP .C 0 Log only LOG_CRIT messages. .PD 0 .TP .C 1 Log only LOG_CRIT and LOG_ERR messages. .TP .C 2 Log only LOG_CRIT, LOG_ERR, and LOG_WARNING messages. .TP .C 3 Log all messages. .PD .PP It is optional and may only be specified for outbound connections. If it is omitted, the logging level is set to 1. .RE .SH EXAMPLES The following examples illustrate file entry syntax. .PP A printer is connected to port 1 of board 3 of a .SM DTC with the .SM IP address 11.234.87.123. The device attached to the port can be accessed with the .SM HP-UX spooler by using the device file .CR /dev/telnet/ocd_lp1 . .IP .C "11.234.87.123 03/01 /dev/telnet/ocd_lp1 /usr/examples/ddfa/pcf" .PP A printer is connected to a terminal server port with .SM IP address 11.234.87.124. The .IC board / port field contains .CR xx/xx . The device attached to the port can be accessed with the .SM HP-UX spooler by using the device file .CR /dev/telnet/ocd_lp2 . .IP .C "11.234.87.124 xx/xx /dev/telnet/ocd_lp2 /usr/examples/ddfa/pcf" .PP A printer is connected to a port accessed with .SM TCP port service address 5001 of a terminal server with the .SM IP address 11.234.87.215. The device attached to the port can be accessed with the .SM HP-UX spooler by using the device file .CR /dev/telnet/ocd_lp3 . .IP .C "11.234.87.215 xx/5001 /dev/telnet/ocd_lp3 /usr/examples/ddfa/pcf" .PP A terminal is connected to port 1 of board 2 of a DTC with the .SM IP address 11.234.87.215 and wishes to use Telnet port identification. .IP .C "11.234.87.215 02/01 /dev/telnet/terminal02" .SH WARNINGS In order to ensure that commands (such as .IR ps ) display the correct device file name (that is, the .IR pseudonym ), all pseudonyms should be placed into the directory .CR /dev/telnet . If pseudonyms are not specified for placement in this directory, the correct display of device file names with many commands is not guaranteed. .SH FILES .nf .C /usr/sbin/dpp .C /usr/sbin/ocd .C /usr/sbin/ocdebug .C /var/adm/dpp_login.bin .C /var/adm/utmp.dfa .C /usr/examples/ddfa/dp .C /usr/examples/ddfa/pcf .fi .SH SEE ALSO dpp(1M), ocd(1M), ocdebug(1M), syslog(3C), pcf(4), ddfa(7). .\" .\" toc \f3dp(4)\f1:\0\0\f4dp\f1@@@dedicated ports file used by \s-1DDFA\s0 software and Telnet port identification feature .\" .\" index@\f4dp\f1 \- dedicated ports file used by \s-1DDFA\s0 software and Telnet port identification feature@@@\f3dp(4)\f1 .\" index@dedicated ports file used by \s-1DDFA\s0 software and Telnet port identification feature@@@\f3dp(4)\f1 .\" index@ports file used by \s-1DDFA\s0 software and Telnet port identification feature, dedicated@@@\f3dp(4)\f1 .\" index@file used by \s-1DDFA\s0 software and Telnet port identification feature, dedicated ports@@@\f3dp(4)\f1 .\" index@\s-1DDFA\s0 software and Telnet port identification feature, dedicated ports file used by@@@\f3dp(4)\f1 .\" index@Telnet port identification feature, dedicated ports file used by \s-1DDFA\s0 software and@@@\f3dp(4)\f1 .\" .\" fileset_database dp.4 INETSVCS-MAN .\" $Header: exports.4,v 1.1.111.1 95/01/17 18:13:12 kcs Exp $ .TA e .TH exports 4 .SH NAME exports, xtab \- directories to export to NFS clients .SH SYNOPSIS .C /etc/exports .PP .C /etc/xtab .SH DESCRIPTION File .CR /etc/exports describes the directories that can be exported to NFS clients. The system administrator creates it using a text editor. .CR mountd processes it each time a mount request is received (see .IR mountd (1M)). .PP .CR /etc/exports is read automatically by the .CR exportfs command (see .IR exportfs (1M)). If this file is changed, .CR exportfs must be run .RC ( "exportfs -a" ) before the changes can affect the daemon's operation. .PP If this file is present at boot time the .CR /sbin/init.d/nfs.server script will execute an .CR exportfs command and export the file systems listed in the file. .PP .CR /etc/xtab contains entries for directories that are currently exported. This file should only be accessed by programs using .CR getexportent (see .IR exportent (3)). (Use .CR "exportfs -u" to remove entries from this file). .PP An entry for a directory consists of a line of the following form: .IP .I directory .CI - option\c .RC [ ,\c .IR option\| ]\|... .PP where .I directory is the path name of a directory (or file). .PP .I options can have any of the following values and forms: .RS .TP 10 .C ro Export the directory read-only. If not specified, the directory is exported read-write. The .CR ro and .CR rw options are mutually exclusive. .TP .CI rw= hostname\f1[\fP : hostname\|\f1]\|...\fP Export the directory read-mostly. Read-mostly means read-only to most machines, but read-write to those specified. If neither .CR ro nor .CR rw is specified, the directory is exported read-write to all. The .CR ro and .CR rw options are mutually exclusive. .TP .CI anon= uid If a request comes from an unknown user, use .I uid as the effective user ID. .BR Note: Root users (uid 0) are always considered ``unknown'' by the NFS server unless they are included in the .CR root option below. .IP The default value for this option is -2. Setting .CR anon to -1 disables anonymous access. .TP .CI root= hostname\f1[\fP : hostname\|\f1]\|...\fP Give root access only to the root users from a specified .IR hostname . The default is for no hosts to be granted root access. For this option .CR hostname cannot be a netgroup name. .TP .CI access= client\f1[\fP : client\|\f1]\|...\fP Give mount access to each client listed. A client can either be a hostname or a netgroup (see .IR netgroup (4)). Each client in the list is first checked in the .CR netgroup database, then in the .CR hosts database. A directory name with no accompanying name list allows any machine to mount the given directory. .TP .C async Specifying .CR async increases write performance on the NFS server by causing asynchronous writes on the NFS server. The .CR async option can be specified anywhere on the command line after the file system name. Before using this option, refer to WARNINGS below. .TP .CI Comments are no longer allowed in the exports file as they can be parsed by exportfs as illegal access hostnames. .PP .CR /etc/exports contains a list of file systems and the .CR netgroup or machine names allowed to remotely mount each file system (see .IR netgroup (4)). The file system names are left-justified and followed by a list of names separated by white space. The names are searched for in .CR /etc/netgroup then in .CR /etc/hosts . A file system name with no accompanying name list means the file system is available to everyone. .PP A .CR # Comment in these examples are included for illustration only and are not to be included in the exports file. Comments are no longer permitted in the exports file as they can generally end up as being parsed as illegal access hostnames by exportfs. .SH EXAMPLES .nf .IP .C "/usr/games cocoa fudge # export to only these machines" .C "/usr -access=clients # export to my clients" .C "/usr/local # export to the world" .C "/usr2 -access=bison:deer:pup # export to only these machines" .C "/var/adm -root=bison:deer # give root access only to these" .C "/usr/new -anon=0 # give all machines root access" .C "/usr/temp -rw=ram:alligator # export read-write only to these" .C "/usr/bin -ro # export read-only to everyone" .C "/usr/stuff -access=bear,anon=-1,ro .C " # several options on one line" .fi .SH WARNINGS If the .CR async option is used, an unreported data loss may occur .CR "ONLY" on a write and .CR "ONLY" if the NFS server experiences a failure after the write reply has been sent to the client. Specifically, blocks which have been queued for the server's disk, but have not yet been written to the disk .I may be lost. .PP If comments are included in the exports file they can cause problems with the proper parsing of the access hostnames by exportfs. For this reason, comments are no longer allowed in the exports file. .PP You cannot export either a parent directory or a subdirectory of an exported directory that resides .IR "within the same file system" . It is not allowed, for instance, to export both .CR /usr and .CR /usr/local if both directories reside on the same disk partition. .SH AUTHOR .CR exports was developed by Sun Microsystems, Inc. .SH FILES .nf .C /etc/exports .C /etc/xtab .C /etc/hosts .C /etc/netgroup .C /sbin/init.d/nfs.server .fi .SH SEE ALSO exportfs(1M), mountd(1M), nfsd(1M), exportent(3), hosts(4), netgroup(4). .\" .\" index@\f4exports\f1 \- directories to export to NFS clients@@@\f3exports(4)\f1 .\" index@\f4xtab\f1 \- directories to export to NFS clients@@@\f3exports(4)\f1 .\" index@\f1directories to export to NFS clients@@@\f3exports(4)\f1 .\" index@\f1export to NFS clients, directories to@@@\f3exports(4)\f1 .\" index@\f1NFS clients, directories to export to@@@\f3exports(4)\f1 .\" index@\f1clients, directories to export to NFS@@@\f3exports(4)\f1 .\" .\" toc@\f3exports(4)\f1@@@directories to export to NFS clients\f1 .\" toc@\f4xtab\f1:\0\0directories to export to NFS clients@@@\f1see \f3exports(4)\f1 .\" links@exports.4 xtab.4 .\" $Header: fs.4,v 76.1 95/07/10 17:14:54 ssa Exp $ .TA f .TH fs 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fs \- format of file system volume .SH SYNOPSIS .nf .C #include .C #include .C #include .C #include .C #include .C #include .fi .SH DESCRIPTION Every file system storage volume has a common format for certain vital information. The first 8 kbytes on a volume contain a volume header which identifies that volume as a Logical Interchange Format .SM (LIF) volume. Such volume may be divided into a number of sections. .PP Each section can contain a file system. The first 8 kbytes in each section is ignored, except where it coincides with the volume header discussed above. The actual file system begins next with the "super block." The layout of the super block as defined by the include file .RC < sys/fs.h > is: .PP .nf .C "#define FS_MAGIC 0x011954 .C "#define FS_MAGIC_LFN 0x095014 .C "#define FS_CLEAN 0x17 .C "#define FS_OK 0x53 .C "#define FS_NOTOK 0x31 .C struct fs { .C " struct fs *fs_link; /* linked list of file systems */ .C " struct fs *fs_rlink; /* used for incore super blocks */ .C " daddr_t fs_sblkno; /* addr of super-block in filesys */ .C " daddr_t fs_cblkno; /* offset of cyl-block in filesys */ .C " daddr_t fs_iblkno; /* offset of inode-blocks in filesys*/ .C " daddr_t fs_dblkno; /* offset of first data after cg */ .C " long fs_cgoffset; /* cylinder group offset in cylinder*/ .C " long fs_cgmask; /* used to calc mod fs_ntrak */ .C " time_t fs_time; /* last time written */ .C " long fs_size; /* number of blocks in fs */ .C " long fs_dsize; /* number of data blocks in fs */ .C " long fs_ncg; /* number of cylinder groups */ .C " long fs_bsize; /* size of basic blocks in fs */ .C " long fs_fsize; /* size of frag blocks in fs */ .C " long fs_frag; /* number of frags in a block in fs*/ .C "/* these are configuration parameters */ .C " long fs_minfree; /* minimum percentage of free blocks*/ .C " long fs_rotdelay; /* num of ms for optimal next block */ .C " long fs_rps; /* disk revolutions per second */ .C "/* these fields can be computed from the others */ .C " long fs_bmask; /* ``blkoff'' calc of blk offsets */ .C " long fs_fmask; /* ``fragoff'' calc of frag offsets */ .C " long fs_bshift; /* ``lblkno'' calc of logical blkno */ .C " long fs_fshift; /* ``numfrags'' calc number of frags*/ .C "/* these are configuration parameters */ .C " long fs_maxcontig; /* max number of contiguous blks */ .C " long fs_maxbpg; /* max number of blks per cyl group */ .C "/* these fields can be computed from the others */ .C " long fs_fragshift; /* block to frag shift */ .C " long fs_fsbtodb; /* fsbtodb and dbtofsb shift constant*/ .C " long fs_sbsize; /* actual size of super block */ .C " long fs_csmask; /* csum block offset */ .C " long fs_csshift; /* csum block number */ .C " long fs_nindir; /* value of NINDIR */ .C " long fs_inopb; /* value of INOPB */ .C " long fs_nspf; /* value of NSPF */ .C " long fs_sparecon[6]; /* reserved for future constants */ .C "/* sizes determined by number of cylinder groups and their sizes */ .C " daddr_t fs_csaddr; /* blk addr of cyl grp summary area */ .C " long fs_cssize; /* size of cyl grp summary area */ .C " long fs_cgsize; /* cylinder group size */ .C "/* these fields should be derived from the hardware */ .C " long fs_ntrak; /* tracks per cylinder */ .C " long fs_nsect; /* sectors per track */ .C " long fs_spc; /* sectors per cylinder */ .C "/* this comes from the disk driver partitioning */ .C " long fs_ncyl; /* cylinders in file system */ .C "/* these fields can be computed from the others */ .C " long fs_cpg; /* cylinders per group */ .C " long fs_ipg; /* inodes per group */ .C " long fs_fpg; /* blocks per group * fs_frag */ .C "/* this data must be re-computed after crashes */ .C " struct csum fs_cstotal; /* cylinder summary information */ .C "/* these fields are cleared at mount time */ .C " char fs_fmod; /* super block modified flag */ .C " char fs_clean; /* file system is clean flag */ .C " char fs_ronly; /* mounted read-only flag */ .C " char fs_flags; /* currently unused flag */ .C " char fs_fsmnt[MAXMNTLEN];/* name mounted on */ .C "/* these fields retain the current block allocation info */ .C " long fs_cgrotor; /* last cg searched */ .C " struct csum *fs_csp[MAXCSBUFS]; /* list of fs_cs info buffers */ .C " long fs_cpc; /* cyl per cycle in postbl */ .C " short fs_postbl[MAXCPG][NRPOS];/*head of blocks per rotation */ .C " long fs_magic; /* magic number */ .C " char fs_fname[6]; /* name of file system */ .C " char fs_fpack[6]; /* pack name of file system */ .C " u_char fs_rotbl[1]; /* list of blocks for each rotation */ .C "/* actually longer */ .C }; .fi .PP A file system consists of a number of cylinder groups. Each cylinder group has inodes and data. .PP A file system is described by its super-block, which in turn describes the cylinder groups. The super-block is critical data and is replicated in each cylinder group to protect against catastrophic loss. This is done at file system creation time and the critical super-block data does not change, so the copies need not be referenced further unless disaster strikes. .PP Addresses stored in inodes are capable of addressing fragments of `blocks'. File system blocks of at most size .C MAXBSIZE can be optionally broken into smaller pieces, each of which is addressable; these pieces may be .CR DEV_BSIZE , or some multiple of a .C DEV_BSIZE unit .RC ( DEV_BSIZE is defined in .RC < sys/param.h >). .PP Large files consist of exclusively large data blocks. To avoid undue wasted disk space, the last data block of a file is allocated only as many fragments of a large block as are necessary, if that file is small enough to not require indirect data blocks. The file system format retains only a single pointer to such a fragment, which is a piece of a single large block that has been divided. The size of such a fragment is determinable from information in the inode, using the .C blksize(fs, ip, lbn) macro. .PP The file system records space availability at the fragment level; to determine block availability, aligned fragments are examined. .PP I-numbers begin at 0. Inodes 0 and 1 are reserved. Inode 2 is used for the root directory of the file system. The .C lost+found directory is given the next available inode when it is initially created by .CR mkfs . .PP .C fs_minfree gives the minimum acceptable percentage of file system blocks that can be free. If the freelist drops below this level, only the super-user may continue to allocate blocks. This can be set to 0 if no reserve of free blocks is deemed necessary. However, severe performance degradations result if the file system is run at greater than 90% full; thus the default value of .C fs_minfree is 10%. .PP The best trade-off between block fragmentation and overall disk utilization and performance varies for each intended use of the file system. Suggested values can be found in the system administrator's manual for each implementation. .SS Cylinder-Group-Related Limits Each cylinder keeps track of the availability of blocks at different rotational positions, so that sequential blocks can be laid out with minimum rotational latency. NRPOS is the number of rotational positions which are distinguished. For example, with NRPOS 8 the resolution of the summary information is 2ms for a typical 3600 rpm drive. .PP .C fs_rotdelay gives the minimum number of milliseconds to initiate another disk transfer on the same cylinder. It is used in determining the rotationally optimal layout for disk blocks within a file; the default value for .C fs_rotdelay is 2ms. Suggested values of .C fs_rotdelay for different disks can be found in the system administrator's manual. .PP Each file system has a statically allocated number of inodes. An inode is allocated for each .C NBPI bytes of disk space. The inode allocation strategy is extremely conservative. .PP .C MAXIPG bounds the number of inodes per cylinder group, and is needed only to keep the structure simpler by having only a single variable size element (the free bit map). .PP .B Important Note: .C MAXIPG must be a multiple of .CR INOPB(fs) . .PP .C MINBSIZE is the smallest allowable block size. With a .C MINBSIZE of 4096, it is possible to create files of size .ifn 2^32 .ift 2\u\s-232\s0\d with only two levels of indirection. .C MINBSIZE must be big enough to hold a cylinder group block, thus .C MINBSIZE must always be greater than .CR "sizeof(struct cg)" . Note that super blocks are never more than size .CR SBSIZE . .PP The path name on which the file system is mounted is maintained in .CR fs_fsmnt . .C MAXMNTLEN defines the amount of space allocated in the super block for this name. The limit on the amount of summary information per file system is defined by .CR MAXCSBUFS . It is currently parameterized for a maximum of two million cylinders. .PP Per cylinder group information is summarized in blocks allocated from the first cylinder group's data blocks. These blocks are read in from .C fs_csaddr (size .CR fs_cssize ) in addition to the super block. .PP .B Important Note: .C sizeof (struct csum) must be a power of two in order for the .C fs_cs macro to work. .PP The two possible values for .C fs_magic are .CR FS_MAGIC , the default magic number for an .SM HFS file system with a fixed-size directory format that limits file name length to .C DIRSIZ (14), and .CR FS_MAGIC_LFN , the magic number of a file system using a variable-size directory format that supports file names of up to .C MAXNAMLEN (255) characters in length. .SS Super Block for a File System: .C MAXBPC bounds the size of the rotational layout tables and is limited by the fact that the super block is of size .CR SBSIZE . The size of these tables is inversely proportional to the block size of the file system. The size of the tables is increased when sector sizes are not powers of two, as this increases the number of cylinders included before the rotational pattern repeats .RC ( fs_cpc ). The size of the rotational layout tables is derived from the number of bytes remaining in .CR "(struct fs)" . .PP .C MAXBPG bounds the number of blocks of data per cylinder group, and is limited by the fact that cylinder groups are, at most, one block. The size of the free block table is derived from the size of blocks and the number of remaining bytes in the cylinder group structure .CR "(struct cg)" . .SS inode: The inode is the focus of all file activity in the .SM HP-UX file system. There is a unique inode allocated for each active file, each continuation inode, each current directory, each mounted-on file, text file, and the root. An inode is ``named'' by its device-and-i-number pair. For the format of an inode and its flags, see .IR inode (4). .SH DEPENDENCIES .SS Series 700 Series 700 systems support only one section per volume. Thus, there can only be one file system on each volume and the first 8 Kbytes of a file system is the boot area. This area contains the .SM LIF volume header, the directory that defines the contents of the volume, and the bootstrapping program. .SH AUTHOR .CR fs was developed by HP and the University of California, Berkeley. .SH SEE ALSO inode(4), lif(4). .\" .\" index@\f4fs\fP \- format of file system volume@@@\f3fs(4)\f1 .\" index@format: file system volume@@@\f3fs(4)\f1 .\" index@file system: file system volume format@@@\f3fs(4)\f1 .\" index@volume format, file system@@@\f3fs(4)\f1 .\" .\" toc@\f3fs(4)\f1:\0\0\f4fs\fP@@@format of file system volume .\" .\" fileset_database@fs.4 SYS-ADMIN-MAN .\" $Header: fs_vxfs.4,v 78.1 96/02/13 11:21:46 ssa Exp $ .\" .\" DO NOT REMOVE THIS COPYRIGHT STATEMENT UNLESS YOU CHECK .\" WITH HP LEGAL FIRST .\" Copyright 1993-1996 Veritas Software Corporation. All .\" rights reserved. .\" .\" *** COMPANY CONFIDENTIAL *** .\" .\" This media contains information which is proprietary .\" and confidential to Veritas Software Corporation. It .\" is not to be disclosed to anyone outside this organization. .\" .\" *** NOTE *** .\" .\" If you are NOT an employee or contractor of Hewlett-Packard .\" Company or HP's subsidiaries, the standard HP-UX source code .\" license does NOT grant you a license to modify this software. .\" If you want to modify this software, please contact HP for .\" further details about a separate, royalty-bearing license. .\" .so /usr/share/lib/macros/vxfs.an .TA f .TH fs_vxfs 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fs (vxfs) \- format of \s-1VxFS\s0 file system volume .SH SYNOPSIS .nf .C "#include " .C "#include " .C "#include " .C "#include " .C "#include " .C "#include " .fi .SH DESCRIPTION The .B vxfs super-block always begins at byte offset 8192 from the start of the file system. The super-block location is fixed so utilities know where to look for it. .PP The super-block contains the following fundamental sizes and offsets: .RS .TP .B fs_magic The magic number for the file system .RB ( VX_MAGIC ). This number identifies the file system as being a .B vxfs FSType. .TP .B fs_version The version number of the file system layout .RB ( VX_VERSION ). This is currently 2 for the .B vxfs Version 2 disk layout and 3 for the Version 3 layout. .TP .B fs_ctime The creation date of the file system. The .IR time (2) system call supplies the time. .TP .B fs_ectime This field is a placeholder in instances when the creation date for a file system is expanded for more precision. It currently is zero. .TP .B fs_logstart The block address of the first Log Area block. It currently is two. .TP .B fs_logend The block address of the last Log Area block. The Log Area size in blocks may be specified as part of .IR mkfs (1M). If not specified, a default of 512 blocks is used. A minimum size of 32 blocks is enforced. For smaller file systems, the default is reduced to avoid wasting space. .TP .B fs_bsize The block size of the file system. The current choices are 1024, 2048, 4096, and 8192 bytes. .TP .B fs_size The number of blocks in the file system, expressed as the number of blocks of size .IR fs_bsize . The .B fs_size field is a signed 32 bit number. The maximum number of blocks in a .B vxfs file system is limited to 31 bits. .TP .B fs_dsize The number of data blocks in the file system. A data block is a block which may be allocated to a file in the file system. .TP .B fs_ninode The number of inodes in the file system allocation units. For Version 2 or Version 3 layout file systems, this field is 0. .TP .B fs_nau The number of allocation units in the file system. The number of allocation units may be specified as part of .IR mkfs (1M). .TP .B fs_defiextsize The default size for indirect data extents, expressed in blocks. This field is currently set to 64 by default. .TP .B fs_oilbsize The size of an old inode list block, expressed in bytes. For Version 2 and 3 layouts, this is initialized to 0 and not used. .TP .B fs_immedlen The size, in bytes, of the immediate data area in each inode. This value is 96 for the .B vxfs file system. .TP .B fs_ndaddr The number of direct extents supported by the .B VX_EXT4 mapping type (see the section describing inode list). This value is 10 for the .B vxfs file system. .RE .PP The preceding fields define the size and makeup of the file system. To reduce the calculations required in utilities, a number of values are derived from the fundamental values and placed in the super-block. .PP The super-block contains the following derived offsets: .RS .TP .B fs_aufirst The address, in blocks, of the first allocation unit. There can be a gap between the end of the intent log and the first allocation unit. This gap could be used to align the first allocation unit on a desired boundary. .TP .B fs_emap The offset in blocks of the free extent map .RB ( emap ) from the start of an allocation unit. .TP .B fs_imap The offset in blocks of the free inode map .RB ( imap ) from the start of an allocation unit. .TP .B fs_iextop The offset in blocks of the extended inode operation map from the start of an allocation unit. For Version 2 and 3 layouts, this is initialized to 0 and not used. .TP .B fs_istart The offset in blocks of the inode list .RB ( ilist ) from the start of an allocation unit. For Version 2 and 3 layouts, this is initialized to 0 and not used. .TP .B fs_bstart The offset in blocks of the first data block from the start of an allocation unit. An allocation unit header may contain padding to align the first data block. .TP .B fs_femap The offset in blocks of the first free extent map .RB ( emap ) from the start of the file system. .TP .B fs_fimap The offset in blocks of the first free inode map .RB ( imap ) from the start of the file system. .TP .B fs_fiextop The offset in blocks of the first extended inode operation map from the start of the file system. For Version 2 and 3 layouts, this is initialized to 0 and not used. .TP .B fs_fistart The offset in blocks of the first ilist from the start of the file system. For Version 2 and 3 layouts, this is initialized to 0 and not used. .TP .B fs_fbstart The offset in blocks of the first data block from the start of the file system. .TP .B fs_nindir The number of entries in an indirect address extent. An indirect address extent is currently 8192 bytes in length, making the current value for .B fs_nindir 2048. .TP .B fs_aulen The length of an allocation unit in blocks. .TP .B fs_auimlen The length of a free inode map in blocks. For Version 2 and 3 layouts, this is initialized to 0 and not used. .TP .B fs_auemlen The length of a free extent map in blocks. .TP .B fs_auilen The length, in blocks, of the inode list for this allocation unit. For Version 2 and 3 layouts, this is initialized to 0 and not used. .TP .B fs_aupad The length, in blocks, of the allocation unit alignment padding. .TP .B fs_aublocks The number of data blocks in an allocation unit. .TP .B fs_maxtier The log base 2 of .IR fs_aublocks . .TP .B fs_inopb The number of inode entries per .I fs_bsize block in the inode list. The .B vxfs inode is currently 256 bytes long. .TP .B fs_inopau The number of inodes in an allocation unit. .TP .B fs_inopilb The number of inode entries per .I fs_oilbsize block in the inode list. For Version 2 and 3 layouts, this field is obsolete. .TP .B fs_ndiripau Expected number of directory inodes per allocation unit. For Version 2 and 3 layouts, this is initialized to 0 and not used. .TP .B fs_iaddrlen The size, in blocks, of an indirect address block. An indirect address block is 8K bytes. This field will be set to (8K / .IR fs_bsize ). .TP .B fs_bshift The log base 2 of .IR fs_bsize . Used to convert a byte offset into a block offset. .TP .B fs_inoshift The log base 2 of .IR fs_inopb . Used to convert an inode number into a block offset in the inode list. .TP .B fs_bmask A mask value such that .RI ( byte_offset & .IR fs_bmask ) rounds the offset to the nearest smaller block boundary. .TP .B fs_boffmask A mask value such that .RI ( byte_offset & .IR fs_boffmask ) yields the offset from the start of the nearest smaller block boundary. .TP .B fs_inomask A mask value such that .RI ( inode_number & .IR fs_inomask ) yields the offset from the start of the containing inode list block of the corresponding inode list entry. For Version 2 and 3 layouts, this field is obsolete. .TP .B fs_checksum A simple checksum of the above fields. A macro, .B VX_FSCHECKSUM is provided to verify or calculate the checksum. .RE .PP The above fields are initialized when the file system is created and do not change unless the file system is resized. These fields are replicated in each allocation unit header. .PP There are additional fields which are considered to be dynamic: .RS .TP .B fs_free The current number of free data blocks. .TP .B fs_ifree The current number of free inodes. For Version 2 and 3 layouts, a separate free inode count is kept for each fileset; this is initialized to 0 and is not used. .TP .B fs_efree An array of the current number of free extents of each extent size in the file system. .TP .B fs_flags The following flags are recognized: .RS .TP .B VX_FULLFSCK Set when a file system requires a full structural check to recover from an error. If this flag is set, a full check will be performed after the replay recovery is finished. .TP .B VX_NOLOG Set when the file system was mounted with the .B VX_MS_NOLOG option. If this flag is set, then no log replay recovery will be performed. .TP .B VX_LOGBAD Set when an I/O error has invalidated the log. If this flag is set, then no log replay recovery will be performed. .TP .B VX_LOGRESET Set when the log ID runs over .B VX_MAXLOGID (2^30). The log ID will be reset at the next appropriate opportunity (such as a mount or 60-second sync). .TP .B VX_RESIZE Set when a file system resizing is in progress. If an .IR fsck (1M) sees this flag, it will have to perform resize recovery. Refer to .IR fsadm (1M) for a description of file system expansion. .TP .B VX_UPGRADING Set when a file system upgrade is in progress. If an .IR fsck (1M) sees this flag, it will have to perform upgrade recovery. .RE .TP .B fs_mod Set whenever a mounted file system is modified. It is used to indicate if the super-block needs to be written when a .B sync operation is performed. .TP .B fs_clean Set to .B VX_DIRTY when a file system is mounted for read/write access. Set to .B VX_CLEAN upon .B umount or successful .IR fsck (1M). The file system cannot be mounted for read/write access unless the .B fs_clean field is .BR VX_CLEAN . .TP .B fs_reserved Reserved for future use. .TP .B fs_firstlogid Initial log ID to use when the file system is mounted. .TP .B fs_time Last time the super-block was written to disk, indicated as the number of seconds that have elapsed since 00:00 January 1, 1970. .TP .B fs_fname File system name (6 characters). .TP .B fs_fpack File system pack label (6 characters). .TP .B fs_logversion The version number of the log format. This field is set by the kernel on each mount to ensure that an .IR fsck (1M) running log replay understands the log format written by the kernel. .PP The log format may change with each release, so all file systems should be clean before upgrading to a new release. .RE .PP The read-only area that supports the .B vxfs Version 2 layout has the following fields: .RS .TP .B fs_oltext This is an array of two extent addresses. These extent addresses point to the two replicated copies of the first object location table extent. .TP .B fs_oltsize This is the size, in blocks, of the object location table extents pointed to by .BR fs_oltext . .TP .B fs_iauimlen The length, in blocks, of a free inode map in an inode allocation unit. .TP .B fs_iausize The size, in blocks, of an inode allocation unit. .TP .B fs_dinosize The size, in bytes, of a disk inode. This is currently 256 bytes. .TP .B fs_checksum2 This is a checksum of the fields specific to the Version 2 layout. .RE .SH SEE ALSO .BR fsck (1M), .BR fsdb (1M), .BR vxfs -specific .BR inode (4), .BR mkfs (1M), .BR mount (2) .\" .\" toc@\f3fs_vxfs(4)\f1@@@format of VxFS file system volume .\" .\" index@\f4fs_vxfs\f1 \- format of VxFS file system volume@@@\f3fs_vxfs(4)\f1 .\" index@\f1format of VxFS file system volume@@@\f3fs_vxfs(4)\f1 .\" index@\f1VxFS file system volume, format@@@\f3fs_vxfs(4)\f1 .\" .\" $Header: fspec.4,v 72.3 93/01/14 16:00:34 ssa Exp $ .TA f .TH fspec 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fspec \- format specification in text files .SH DESCRIPTION It is sometimes convenient to maintain text files on the .SM HP-UX system with non-standard tabs, (meaning tabs that are not set at every eighth column). Generally, such files must be converted to a standard format \(mi frequently by replacing all tabs with the appropriate number of spaces \(mi before they can be processed by .SM HP-UX system commands. A format specification occurring in the first line of a text file specifies how tabs are to be expanded in the remainder of the file. .PP A format specification consists of a sequence of parameters separated by blanks and surrounded by the brackets .C <: and .CR :> . Each parameter consists of a keyletter, possibly followed immediately by a value. The following parameters are recognized: .RS .TP 15 .CI t tabs The .C t parameter specifies tab settings for the file. The value of .I tabs must be one of the following: .RS .RS .TP 4 1. A list of column numbers separated by commas, indicating tabs set at the specified columns; .TP 2. A .C - followed immediately by an integer .IR n , indicating tabs at intervals of .I n columns; .TP 3. A .C - followed by the name of a ``canned'' tab specification. .RE .RE .IP Standard tabs are specified by .CR t-8 , or equivalently, .C t1,9,17,25, etc. Recognized canned tabs are defined by the .C tabs command (see .IR tabs (1)). .TP .CI s size The .C s parameter specifies a maximum line size. The value of .I size must be an integer. Size checking is performed after tabs have been expanded, but before the margin is inserted at the beginning of the line. .TP .CI m margin The .C m parameter specifies a number of spaces to be inserted at the beginning of each line. The value of .I margin must be an integer. .TP .C d The .C d parameter takes no value. Its presence indicates that the line containing the format specification is to be deleted from the converted file. .TP .C e The .C e parameter takes no value. Its presence indicates that the current format is to prevail only until another format specification is encountered in the file. .RE .PP Default values (assumed for parameters not supplied) are .C t-8 and .CR m0 . If the .C s parameter is not specified, no size checking is performed. If the first line of a file does not contain a format specification, the above defaults are assumed for the entire file. The following is an example of a line containing a format specification: .IP .C * <:t5,10,15 s72:> * .PP If a format specification can be disguised as a comment, it is not necessary to code the .C d parameter. .PP Several .SM HP-UX system commands correctly interpret the format specification for a file. Among them is .CR ed , which can be used to convert files to a standard format acceptable to other .SM HP-UX system commands. .SH SEE ALSO ed(1), newform(1), tabs(1). .\" .\" index@\f4fspec\fP \- format specification in text files@@@\f3fspec(4)\f1 .\" index@format specification in text files@@@\f3fspec(4)\f1 .\" index@specification, format, in text files@@@\f3fspec(4)\f1 .\" index@text file format specification@@@\f3fspec(4)\f1 .\" index@file format: text file format specification@@@\f3fspec(4)\f1 .\" .\" toc@\f3fspec(4)\f1:\0\0\f4fspec\fP@@@format specification in text files .\" .\" fileset_database@fspec.4 SYS-ADMIN-MAN .\" $Header: fstab.4,v 72.4 94/09/08 13:46:07 ssa Exp $ .TA f .TH fstab 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME fstab \- static information about the file systems .SH SYNOPSIS .C #include .SH DESCRIPTION .C fstab is an .SM ASCII file that resides in directory .CR /etc . Programs read it, but do not write to or from it. System administrators are responsible for creating and maintaining this file properly. .PP .C /etc/fstab contains a list of mountable file-system entries. Each file-system entry appears on a separate line, and consists of fields separated by one or more blanks or tabs. .PP The order of entries in .C /etc/fstab is important only for entries without a .I pass number field. Entries without a .I pass number are sequentially checked by .C fsck (see .IR fsck (1M)) after the entries with a .I pass number have been checked. .PP Each file-system entry must contain a .I device special file and may additionally contain all of the following fields, in the following order: .RS 5 .I directory .br .I type .br .I options .br .I "backup frequency" .br .I "pass number " (on parallel .CR fsck ) .br .I comment .RE .PP If any field after the name of the device special file is present, all fields must be present in the order indicated, to ensure correct place-holding. .PP Entries from this file are accessed using .C getmntent() (see .IR getmntent (3X)). .PP The fields are separated by white space, and a .C # as the first non-whitespace character in an entry or field indicates a comment. .TP 20 .I device special file A block device special file name. This field is used by .CR fsck , .CR mount , .CR swapon , and other commands to identify the location of the storage device on which the file system resides. .TP .I directory Name of the root of the mounted file system that corresponds to the .IR "device special file" . If .I type is .CR swapfs , .I directory can be the name of any directory within a file system. Only one directory should be specified per file system. .I directory must already exist and must be given as an absolute path name. .TP .I type Can be .CR swap , .CR swapfs , .CR ignore , or a file system type (for example, .CR hfs , .CR vxfs , .CR cdfs , .CR nfs , or .CR lofs ). .IP If .I type is .CR swap , the .I device special file is made available as an area of swap space by the .C swapon command (see .IR swapon (1M)). The .I options field is valid. The fields .IR "directory" , .IR "pass number" , and .I "backup frequency" are ignored for .C swap entries. .IP If .I type is .CR swapfs , the file system in which .I directory resides is made available as swap space by .CR swapon . The .I options field is valid. The fields .IR "device special file" , .IR "pass number" , and .I "backup frequency" are ignored for .C swapfs entries. .IP Entries marked by the .I type .C ignore are ignored by all commands and can be used to mark unused sections. If .I type is specified as either .CR ignore , .CR swap , or .CR swapfs , the entry is ignored by the .C mount and .C fsck commands (see .IR mount (1M) and .IR fsck (1M)). .I fsck also ignores entries with .I type specified as .CR cdfs , .CR nfs , or .CR lofs . .TP .I options A comma-separated list of option keywords, as found in .IR mount (1M) or .IR swapon (1M). The keywords used depend on the parameter specified in .IR type . .TP .I backup frequency Reserved for possible use by future backup utilities. .TP .I pass number Used by the .C fsck command to determine the order in which file system checks are done. The root file system should be specified with a .I pass number of 1, to be checked first, and other file systems should have larger numbers. (A file system with a .I pass number of zero is ignored by the .C fsck command.) .IP File systems within a drive should be assigned different pass numbers, but file systems on different drives can be checked on the same pass, to utilize possible parallelism available in the hardware. If .I pass number is not present, .C fsck checks each such file system sequentially after all eligible file systems with pass numbers have been checked. .TP .I comment An optional field that begins with a .C # character and ends with a new-line character. Space from the .I pass number to the .I comment field (if present) or to the new-line is reserved for future use. .PP There is no limit to the number of .I "device special file" fields in .CR /etc/fstab . .SH NETWORKING FEATURES .SS \s-1NFS\s0 If the field .I type is .CR nfs , a remote .SM NFS file system is implied. For .SM NFS file systems, the .I device special file should be the serving machine name followed by ":" followed by the path on the serving machine of the directory being served. The .IR "pass number" , and .I backup frequency fields are ignored for .SM NFS entries. .SH EXAMPLES Examples of typical .C /etc/fstab entries: .RS .PP Add an .SM HFS file system at .C /home using default mount options; (backup frequency 0) fsck pass 2: .IP .C "/dev/dsk/c0t6d0 /home hfs defaults 0 2 # /home disk" .PP Add a .C swap device to a system managed using LVM, with default options (Note, the .I directory field .RC ( / ) cannot be empty, even though it is ignored): .IP .C "/dev/vg01/lv10 / swap defaults 0 0 # swap device" .PP Add a swap device on a system implementing whole-disk layout to use the space after the end of the file system (\c .I options\c .RC = end ): .IP .C "/dev/dsk/c0t5d0 / swap end 0 0 # swap at end of device" .PP Add file system swap space on the file system containing directory .CR /swap . .I type is .CR swapfs ; set .I options to .CR min=10 , .CR lim=4500 , .CR res=100 , and .C pri=0 (see .IR swapon (1M)) for explanation of .IR options ). .I device field is ignored but must not be empty: .IP .C "default /swap swapfs min=10,lim=4500,res=100,pri=0 0 0" .PP (Note that both a file system entry and a swap entry are required for devices providing both services.) .SH DEPENDENCIES .SS \s-1NFS\s0 Here is an example for mounting an .SM NFS file system for systems that support .SM NFS file systems: .IP .C "server:/mnt /mnt nfs rw,hard 0 0 \&#mount from server." .SH AUTHOR .I fstab was developed by HP, AT&T, Sun Microsystems, Inc., and the University of California, Berkeley. .SH FILES .C /etc/fstab .br .C /usr/include/fstab.h .SH SEE ALSO fsck(1M), mount(1M), swapon(1M), getfsent(3X), getmntent(3X), mnttab(4). .\" toc@\f3fstab(4)\f1@@@static information about the file systems .\" index@\f2fstab\f1 \- static information about the file systems@@@\f3fstab(4)\f1 .\" index@static information about the file systems@@@\f3fstab(4)\f1 .\" index@file system: static information about file systems@@@\f3fstab(4)\f1 .\" $Header: ftpusers.4,v 72.4 94/07/03 17:01:45 ssa Exp $ .TA f .TH ftpusers 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Release 10.20: July 1996 .SH NAME ftpusers \- security file for \f2ftpd\fP(1M) .SH DESCRIPTION .CR ftpd rejects remote logins to local user accounts that are named in .CR /etc/ftpusers . Each restricted account name must appear alone on a line in the file. The line cannot contain any white space. User accounts that specify a restricted login shell in .C /etc/passwd should be listed in .C /etc/ftpusers because .C ftpd accesses local accounts without using their login shells. .SM UUCP accounts should be listed in .CR /etc/ftpusers . If .C /etc/ftpusers does not exist, .C ftpd skips the security check. .SH EXAMPLES Given an .C /etc/ftpusers file containing the following: .IP .nf .ft CW Only lines that exactly match user account names are significant. Blank lines are harmless because they do not match any account names. However you must be careful. .IP .ft CW uucp guest .ft R .fi .PP .C ftpd would reject login attempts using the local accounts .CR careful. , .CR uucp , or .CR guest . .SH AUTHOR .C ftpusers was developed by the University of California, Berkeley. .SH SEE ALSO ftp(1), ftpd(1M). .\" .\" index@\f4ftpusers\f1 \- security file for \f2ftpd\fP(1M)@@@\f3ftpusers(4)\fP .\" index@\f1security file for \f2ftpd\fP(1M)@@@\f3ftpusers(4)\fP .\" index@\f4ftpd\fP, security file for@@@\f3ftpusers(4)\fP .\" index@\f1file, security for \f2ftpd\fP(1M)@@@\f3ftpusers(4)\fP .\" .\" toc@\f3ftpusers(4)\fP:\0\0\f4ftpusers\fP@@@security file for \f2ftpd\fP(1M) .\" .\" fileset_database@ftpusers.4 INETSVCS-MAN .\" $Header: gated.conf.4,v 80.5 97/02/19 22:28:01 ssa Exp $ .\" ######################################################### .\" ## ## .\" ## This document converted from HTML by 'ht2man' ## .\" ## ## .\" ## ht2man - HTML to Nroff/Troff converter ## .\" ## Developed by ## .\" ## ## .\" ## Tom Drake of UX /etc... ## .\" ## Email: rtd@pobox.com ## .\" ## Phone: 408/847-7150 ## .\" ## ## .\" ######################################################### .\"------------------------------------------------------------------------ .\" .\" gated, release 3.5 .\" .\" copyright (c) 1990,1991,1992,1993,1994,1995 by Cornell university. .\" all rights reserved. .\" .\" this software is provided "as is" and without any .\" express or implied warranties, including, without .\" limitation, the implied warranties of merchantability .\" and fitness for a particular purpose. .\" .\" royalty-free licenses to redistribute gated release .\" 3 in whole or in part may be obtained by writing to: .\" .\" gatedaemon project .\" information technologies/network resources .\" 200 ccc .\" Cornell university .\" ithaca, ny 14853-2601 usa .\" .\" gated is based on kirton's egp, uc Berkeley's routing .\" daemon (routed), and dcn's hello routing protocol. .\" development of gated has been supported in part by the .\" national science foundation. .\" .\" please forward bug fixes, enhancements and questions to the .\" gated mailing list: gated-people@gated.cornell.edu. .\" .\"------------------------------------------------------------------------ .\" .\" portions of this software may fall under the following .\" copyrights: .\" .\" copyright (c) 1988 regents of the university of California. .\" all rights reserved. .\" .\" redistribution and use in source and binary forms are .\" permitted provided that the above copyright notice and .\" this paragraph are duplicated in all such forms and that .\" any documentation, advertising materials, and other .\" materials related to such distribution and use .\" acknowledge that the software was developed by the .\" university of California, Berkeley. the name of the .\" university may not be used to endorse or promote .\" products derived from this software without specific .\" prior written permission. this software is provided .\" ``as is'' and without any express or implied warranties, .\" including, without limitation, the implied warranties of .\" merchantability and fitness for a particular purpose. .\"> .\"/vol/src/devel/gated/master/gated/doc/config_guide/config.html,v 1.2.2.2 1995/04/19 18:42:10 jch exp .TA g .TH gated.conf 4 .ds )H Hewlett-Packard Company .ds ]W HP-UX Formatted: March 1998 .SH NAME gated.config \- GateDaemon Configuration Guide .SH SYNOPSIS .C /etc/gated.conf .SH DESCRIPTION .SS Configuration Overview .RS .TP 3 \(bu Introduction .TP 3 \(bu Statement Summary .TP 3 \(bu Preferences and Route Selection .TP 3 \(bu Trace Statements and Global Options .TP 3 \(bu Directive Statements .TP 3 \(bu Options Statements .TP 3 \(bu Interface Statements and Configuration .TP 3 \(bu Definition Statements .RE .SS Protocol Statements .RS .TP 3 \(bu Protocol Overview .TP 3 \(bu Interior gateway protocols (igps) .RS .TP 3 \(bu RIP, HELLO, OSPF .RE .TP 3 \(bu Exterior gateway protocols (egps) .RS .TP 3 \(bu EGP, BGP .RE .TP 3 \(bu ICMP Statement .TP 3 \(bu Redirect Statement .TP 3 \(bu Router Discovery Statement .TP 3 \(bu Kernel Interface .TP 3 \(bu Static Routes .RE .SS Control Statements .RS .TP 3 \(bu Route filtering .TP 3 \(bu Matching AS paths .TP 3 \(bu Route Importation .TP 3 \(bu Route Exportation .TP 3 \(bu Route Aggregation .RE .SS Appendices .RS .TP 3 \(bu Glossary of Terms .TP 3 \(bu References .RE .\"/vol/src/devel/gated/master/gated/doc/config_guide/intro.html,v 1.2 1994/03/16 21:38:27 jch exp .SH Introduction to Configuring GateD .SS Syntax The gated configuration file consists of a sequence of statements terminated by a semi-colon (`\f4;\f1'). Statements are composed of tokens separated by white space, which can be any combination of blanks, tabs and newlines. This structure simplifies identification of the parts of the configuration associated with each other and with specific protocols. Comments may be specified in either of two forms. One form begins with a pound sign (`\f4#\f1') and runs to the end of the line. The other form, \f2C\f1 style, starts with a `\f4/*\f1' and continues until it reaches `\f4*/\f1'. .SS Syntax description conventions Keywords and special characters that the parser expects exactly are displayed using \f3bold\f1 type. Parameters are displayed in italic \f2variable definition\f1 style. Parameters shown in square brackets (`\f4[\f1' and `\f4]\f1') are used to show optional keywords and parameters. The vertical bar (`\f4|\f1') is used to indicate between a choice of optional parameters. Parentheses (`\f4(\f1' and `\f4)\f1') are used to group keywords and parameters when necessary. .PP For example, in the syntax description: .RS .nf .P [ \f3backbone\f1 | ( \f3area\f1 \f2area\f1 ) ] .fi .RE .P The square brackets say that either parameter is optional. The keywords are \f3backbone\f1 and \f3area\f1. The vertical bar indicates that either ``\f3backbone\f1'' or ``\f3area\f1 \f2area\f1'' may be specified. Since \f2area\f1 is in the \f2variable definition\f1 style, it is a parameter that needs to be provided. .SS Statement Grouping The configuration statements and the order in which these statements appear divide .CR gated.conf into options statements, interface statements, definition statements, protocol statements, static statements, control statements, and aggregate statements. Entering a statement out of order causes an error when parsing the configuration file. .PP Two other types of statements do not fit in these categories: %directive statements and %trace statements. These statements provide instructions to the parser and control tracing from the configuration file. They do not relate to the configuration of any protocol and may occur anywhere in the gated.conf file. .SS Statement Summary A summary table of the configuration statements (in the configuration statement summary) lists each GateD configuration statement by name, identifies the statement type, and provides a short synopsis of the command function. More detailed definitions and descriptions of each of the eight classes of GateD statements follow in separate sections. .\"/vol/src/devel/gated/master/gated/doc/config_guide/statements.html,v 1.2 1994/03/16 21:38:45 jch exp .SH GateD Configuration Statement Summary The GateD configuration commands are summarized below. The table lists each command by name, identifies the statement type, and gives a synopsis of the statement function: .SS Summary of GateD Configuration Statements .RS .TP 30 %directory (directive) sets the directory for include files. .TP %include (directive) includes a file into gated.conf. .TP traceoptions (trace) specifies which events are traced. .TP options (definition) defines GateD options. .TP interfaces (definition) defines GateD interfaces. .TP autonomoussystem (definition) defines the AS number. .TP routerid (definition) defines the originating router (BGP, OSPF). .TP martians (definition) defines invalid destination addresses. .TP rip (protocol) enables RIP protocol. .TP hello (protocol) enables HELLO protocol. .TP isis (protocol) enables ISIS protocol. .TP kernel (protocol) configures kernel interface options. .TP ospf (protocol) enables OSPF protocol. .TP egp (protocol) enables EGP protocol. .TP bgp (protocol) enables BGP protocol. .TP redirect (protocol) configures the processing of ICMP redirects. .TP icmp (protocol) configures the processing of general ICMP packets. .TP static (static) defines static routes. .TP import (control) defines which routes to import. .TP export (control) defines which routes to export. .TP aggregate (control) defines which routes to aggregate. .TP generate (control) defines which routes to generate. .RE .\"/vol/src/devel/gated/master/gated/doc/config_guide/pref.html,v 1.2 1994/03/16 21:38:35 jch exp .SH Preference Preference is the value GateD uses to order preference of routes from one protocol or peer over another. Preference can be set in the GateD configuration files in several different configuration statements. Preference can be set based on network interface over another, from one protocol over another, or from one remote gateway over another. Preference may not be used to control the selection of routes within an \f3igp\f1, this is accomplished automatically by the protocol based on metric. Preference may be used to select routes from the same \f3egp\f1 learned from different peers or autonomous systems. Each route has only one preference value associated with it, even though preference can be set at many places in the configuration file. Simply, the last or most specific preference value set for a route is the value used. (See .BR "Glossary of Terms: Preference" .) The preference value is an arbitrarily assigned value used to determine the order of routes to the same destination in a single routing database. The active route is chosen by the lowest preference value. Some protocols implement a second preference (preference2), sometimes referred to as a tie-breaker. .SS Selecting a route .RS .TP 3 \(bu The route with the best (numerically smallest) preference is preferred. .TP 3 \(bu If the two routes have the same preference, the route with the best (numerically smallest) preference2 (also known as a tie-breaker) is preferred. .TP 3 \(bu A route learned from a \f3igp\f1 is preferred to a route learned from an \f3egp\f1. Least preferred is a route learned indirectly by an \f3igp\f1 from an \f3egp\f1. .TP 3 \(bu If AS path information is available, it is used to help determine the most preferred route. .RS .TP 3 \(bu A route with an AS path is preferred over one without an AS path. .TP 3 \(bu If the AS paths and origins are identical, the route with the lower metric is preferred. .TP 3 \(bu A route with an AS path origin of \f3igp\f1 is preferred over a route with an AS path origin of \f3egp\f1. Least preferred is an AS path with an \f3unknown\f1 origin. .TP 3 \(bu A route with a shorter AS path is preferred. .RE .TP 3 \(bu If both routes are from the same protocol and AS, the one with the lowest metric is preferred. .TP 3 \(bu The route with the lowest numeric next-hop address is used. .RE .SS Assigning preferences A default preference is assigned to each source from which GateD receives routes. Preference values range from 0 to 255 with the lowest number indicating the most preferred route. .PP The following table summarizes the default preference values for routes learned in various ways. The table lists the statements (some of these are clauses within statements) that set preference, and shows the types of routes to which each statement applies. The default preference for each type of route is listed, and the table notes preference precedence between protocols. The narrower the scope of the statement, the higher precedence its preference value is given, but the smaller the set of routes it affects. .P .TS lf3 cf3 cf3 l l n . Preference Of Defined by Statement Default _ direct connected networks interface 0 OSPF routes ospf 10 IS-IS level 1 routes isis level 1 15 IS-IS level 2 routes isis level 2 18 internally generated default gendefault 20 redirects redirect 30 routes learned via route socket kernel 40 static routes from config static 60 ANS SPF (SLSP) routes slsp 70 HELLO routes hello 90 RIP routes rip 100 point-to-point interface 110 routes to interfaces that are down interfaces 120 aggregate/generate routes aggregate/generate 130 OSPF AS external routes ospf 150 BGP routes bgp 170 EGP egp 200 .TE .SS Sample Preference Specifications .RS 0 .nf .P .ft 4 interfaces { interface 138.66.12.2 preference 10 ; } ; rip yes { preference 90 ; } ; import proto rip gateway 138.66.12.1 preference 75 ; .ft 1 .fi .RE .PP In these statements the preference applicable to routes learned via RIP from gateway 138.66.12.1 is 75. The last preference applicable to routes learned via RIP from gateway 128.66.12.1 is defined in the accept statement. The preference applicable to other RIP routes is found in the .BR rip statement. The preference set on the interface statement applies only to the route to that interface. .\"/vol/src/devel/gated/master/gated/doc/config_guide/trace.html,v 1.2 1994/03/16 21:38:49 jch exp .SH Trace Statements Trace statements control tracing options. The GateD tracing options may be configured at many levels. Tracing options include the file specifications, control options, and global and protocol specific tracing options. Unless overridden, tracing options from the next higher level are inherited by lower levels. For example, BGP peer tracing options are inherited from BGP group tracing options, which are inherited from global BGP tracing options, which are inherited from global GateD tracing options. At each level tracing specifications override the inherited options. .SS Global tracing options There are two types of global options, those which only affect global operations and those which have potential significance to protocols. .SS Global significance only The trace flags that only have global significance are: .RS .TP 10 \f3parse\f1 Trace the lexical analyzer and parser. Mostly used by GateD developers for debugging. .TP \f3adv\f1 Trace the allocation of and freeing of policy blocks. Mostly used by the GateD developers for debugging. .TP \f3symbols\f1 Used to trace symbols read from the kernel at startup. The only useful way to specify this level of tracing is via the \f4-t\f1 option on the command line since the symbols are read from the kernel before parsing the configuration file. .TP \f3iflist\f1 Used to trace the reading of the kernel interface list. It is useful to specify this with the \f4-t\f1 option on the command line since the first interface scan is done before reading the configuration file. .RE .SS Protocol significance The options flags that have potential significance to protocols are: .RS .TP 10 \f3all\f1 Turn on all of the following. .TP \f3general\f1 A shorthand notation for specifying both \f4normal\f1 and \f4route\f1. .TP \f3state\f1 Trace state machine transitions in the protocols. .TP \f3normal\f1 Trace normal protocols occurrences. Abnormal protocol occurrences are always traced. .TP \f3policy\f1 Trace application of protocol and user-specified policy to routes being imported and exported. .TP \f3task\f1 Trace system interface and processing associated with this protocol or peer. .TP \f3timer\f1 Trace timer usage by this protocol or peer. .TP \f3route\f1 Trace routing table changes for routes installed by this protocol or peer. .RE .P Not all of the above options apply to all of the protocols. In some cases their use does not make sense (for instance, RIP does not have a state machine) and in some instances the requested tracing has not been implemented (such as RIP support of the \f4policy\f1 option). .PP It is not currently possible to specify packet tracing from the command line. This is because a global option for packet tracing would potentially create too much output. .PP When protocols inherit their tracing options from the global tracing options, tracing levels that do not make sense (such as \f4parse\f1, \f4adv\f1 and packet tracing options) are masked out. .PP Global tracing statements have an immediate effect, especially parsing options that effect the parsing of the configuration file. Tracing values inherited by protocols specified in the configuration file are initially inherited from the global options in effect as they are parsed, unless they are overridden by more specific options. After the configuration file is read, tracing options that were not explicitly specified are inherited from the global options in effect at the end of the configuration file. .SS Packet tracing Tracing of packets is very flexible. For any given protocol there are one or more options for tracing packets. all protocols allow use of the \f3packets\f1 keyword allows for tracing \f2all\f1 packets sent and received by the protocol. most protocols have other options for limiting tracing to a useful subset of packet types. These tracing options can be further controlled with the following modifiers: .RS .TP 10 \f3detail\f1 \f4detail\f1 must be specified before \f4send\f1 or \f4recv\f1. Normally packets are traced in a terse form of one or two lines. When \f4detail\f1 is specified, a more verbose format is used to provide further detail on the contents of the packet. .TP \f3send\f1 .PD 0 .TP .PD \f3recv\f1 These options limit the tracing to packets sent or received. Without these options both sent and received packets will be traced. .RE .PP \f4Detail\f1, if specified, must be before \f4send\f1 or \f4recv\f1. If a protocol allows for several different types of packet tracing, modifiers may be applied to each individual type. But be aware that within one tracing specification the trace flags are summed up, so specifying \f4detail packets\f1 will turn on full tracing for all packets. .SS Traceoptions syntax .RS 0 .nf .P \f3traceoptions\f1 ["\f2trace_file\f1" [\f3replace\f1] [\f3size\f1 \f2size\f1[\f3k\f1|\f3m\f1] \f3files\f1 \f2files\f1]] [\f2control_options\f1] \f2trace_options\f1 [\f3except\f1 \f2trace_options\f1] ; \f3traceoptions\f1 \f3none\f1 ; .fi .RE .P .RS .TP 10 \f2trace_file\f1 Specifies the file to receive tracing information. If this file name does not begin with a slash \f3(/)\f1, the directory where gated was started in prepended to the name. .TP \f3replace\f1 Tracing should start by replacing an existing file. The default is to append to an existing file. .TP \f3size\f1 \f2size\f1[\f3k\f1|\f3m\f1] \f3files\f1 \f2files\f1 Limit the maximum size of the trace file to the specified size (minimum 10k). When the trace file reaches the specified size, it is renamed to \f4file.0\f1, then \f4file.1\f1, \f4file.2\f1 up to the maximum number of files (minimum specification is 2). .TP \f2control_options\f1 Specifies options that control the appearance of tracing. Valid values are: .RS .TP \f3nostamp\f1 Specifies that a timestamp should not be prepended to all trace lines. .RE .TP \f3except\f1 \f2trace_options\f1 Used to enable a broad class of tracing and then disable more specific options. .TP \f3none\f1 Specifies that all tracing should be turned off for this protocol or peer. .RE .\"/vol/src/devel/gated/master/gated/doc/config_guide/direct.html,v 1.2 1994/03/16 21:38:14 jch exp .SH Directive Statements Directive statements provide direction to the GateD configuration language parser about included files and the directories in which these files reside. Directive statements are immediately acted upon by the parser. Other statements terminate with a semi-colon (;), but directive statements terminate with a newline. The two directive statements are: .RS .TP \f3%directory\f1 "\f2directory\f1" Defines the directory where the include files are stored. When it is used, GateD looks in the directory identified by pathname for any included files that do not have a fully qualified filename, such as files that do not begin with "/". This statement does not actually change the current the directory, it just specifies the prefix applied to included file names. .TP \f3%include\f1 "\f2filename\f1" Identifies an include file. The contents of the file is \f2included\f1 in the gated.conf file at the point in the gated.conf file where the \f4%include\f1 directive is encountered. If the filename is not fully qualified (does not begin with "/"), it is considered to be relative to the directory defined in the \f4%directory\f1 directive. The \f4%include\f1 directive statement causes the specified file to be parsed completely before resuming with this file. Nesting up to ten levels is supported. The maximum nesting level may be increased by changing the definition of \f3FI_MAX\f1 in \f4parse.h\f1. .RE In a complex environment, segmenting a large configuration into smaller more easily understood segments might be helpful, but one of the great advantages of GateD is that it combines the configuration of several different routing protocols into a single file. Segmenting a small file unnecessarily complicates routing configurations. .\"/vol/src/devel/gated/master/gated/doc/config_guide/options.html,v 1.2 1994/03/16 21:38:32 jch exp .SH Options Statements Options statements allow specification of some global options. If used, \f4options\f1 must appear before any other type of configuration statement in the gated.conf file. .PP The options statement syntax is: .RS .nf .PP \f3options\f1 [ \f3nosend\f1 ] [ \f3noresolv\f1 ] [ \f3gendefault\f1 [ \f3preference\f1 \f2preference\f1 ] [ \f3gateway\f1 \f2gateway\f1] ] [ \f3syslog\f1 [ \f3upto\f1 ] \f2log_level\f1 ] [ \f3mark\f1 \f2time\f1 ] \f3;\f1 .fi .RE .P The options list can contain one or more of the following options: .RS .TP \f3gendefault\f1 [ \f3preference\f1 \f2preference\f1 ] [ \f3gateway\f1 \f2gateway\f1] When \f4gendefault\f1 is enabled, when a BGP or EGP neighbor is up it causes the creation of a default route with the special protocol \f4default\f1. This can be disabled per BGP/EGP group with the \f4nogendefault\f1 option. By default, this route has a preference of 20. This route is normally not installed in the kernel forwarding table, it is only present so it can be announced to other protocols. If a gateway is specified, the default route will be installed in the kernel forwarding table with a next hop of the listed gateway. .IP Note that the use of the more general option is preferred to the use of this \f4gendefault\f1 option. The \f4gendefault\f1 option may go away in future releases. The the section on Route Aggregation for more information on the \f4generate\f1 statement. .TP \f3nosend\f1 Do not send any packets. This option makes it possible to run GateD on a live network to test protocol interactions without actually participating in the routing protocols. The packet traces in the GateD log can be examined to verify that GateD is functioning properly. This is most useful for RIP and HELLO and possibly the SMUX SNMP interface. This option does not yet apply to BGP and is less than useful with EGP and OSPF. .TP \f3noresolv\f1 By default GateD will try to resolve symbolic names into IP addresses by using the gethostbyname() and getnetbyname() library calls. These calls usually use the Domain Name System (DNS) instead of the hosts local host and network tables. If there is insufficient routing information to send DNS queries, GateD will deadlock during startup. This option can be used to prevent these calls, symbolic names will result in configuration file errors. .TP \f3syslog\f1 [ \f3upto\f1 ] \f2log_level\f1 Controls the amount of data GateD logs via syslog on systems where setlogmask() is supported. The available logging levels and other terminology are as defined in the \f4setlogmask(3)\f1 man page. The default is equivalent to \f4syslog upto info\f1. .TP \f3mark\f1 \f2time\f1 Specifying this option causes gated to output a message to the trace log at the specified interval. This can be used as one method of determining if gated is still running. .RE .\"/vol/src/devel/gated/master/gated/doc/config_guide/intfcs.html,v 1.2.2.3 1994/11/15 21:09:52 jch exp .SH Interfaces Statement .SS Interface Syntax .RS 0 .nf \f3interfaces\f1 \f3{\f1 \f3options\f1 [ \f3strictinterfaces\f1 ] [ \f3scaninterval\f1 \f2time\f1 ] \f3;\f1 \f3interface\f1 \f2interface_list\f1 [ \f3preference\f1 \f2preference\f1 ] [ \f3down\f1 \f3preference\f1 \f2preference\f1 ] [ \f3passive\f1 ] [ \f3simplex\f1 ] [ \f3reject\f1 ] [ \f3blackhole\f1 ] \f3;\f1 \f3define\f1 \f2address\f1 [ \f3broadcast\f1 \f2address\f1 ] | [ \f3pointtopoint\f1 \f2address\f1 ] [ \f3netmask\f1 \f2mask\f1 ] [ \f3multicast\f1 ] \f3;\f1 \f3}\f1 \f3;\f1 .fi .RE .P An interface is the connection between a router and one of its attached networks. A physical interface may be specified by interface name, by IP address, or by domain name, (unless the network is an unnumbered point-to-point network.) Multiple levels of reference in the configuration language allow identification of interfaces using wildcard, interface type name, or delete word address. Be careful with the use of interface names as future Unix operating systems may allow more than one address per interface. The interface_list is a list of one or more interface names including wildcard names (names without a number) and names which may specify more than one interface or address, or the token \f4all\f1 for all interfaces. .RS .TP \f3options\f1 Allows configuration of some global options related to interfaces. These are: .RS .TP \f3strictinterfaces\f1 Indicates that it is a fatal error to reference an interface in the configuration file that is not present when GateD is started and not listed in a \f4define\f1 statement. Without this option a warning message will be issued but GateD will continue. .TP \f3scaninterval\f1 \f2time\f1 Specifies how often GateD scans the kernel interface list for changes. The default is every 15 seconds on most systems, and 60 seconds on systems that pass interface status changes through the routing socket (BSD 4.4). Note that GateD will also scan the interface list on receipt of a \f4SIGUSR2\f1. .RE .TP \f3interface\f1 \f2interface_list\f1 Sets interface options on the specified interfaces. An interface list is \f4all\f1 or a list of interface names (see warning about interface names), domain names, or numeric addresses. Options available on this statement are: .RS .TP \f3preference\f1 \f2preference\f1 Sets the preference for routes to this interface when it is up and appears to be functioning properly. The default preference is \f40\f1. .TP \f3down preference\f1 \f2preference\f1 Sets the preference for routes to this interface when GateD does not believe it to be functioning properly, but the kernel does not indicate it is down. The default value is \f4120\f1. .TP \f3passive\f1 Prevents GateD from changing the preference of the route to this interface if it is not believed to be functioning properly due to lack of received routing information. GateD will only perform this check if the interface is actively participating in a routing protocol. .TP \f3simplex\f1 Defines an interface as unable to hear its own broadcast packets. Some systems define an interface as simplex with the IFF_SIMPLEX flag, on others it needs to be specified in the configuration file. On simplex interfaces, packets from myself are assumed to have been looped back in software and are not used as an indication that the interface is functioning properly. .TP \f3reject\f1 Specifies that the address of the interface which matches these criteria will be used as the local address when installing \f2reject\f1 routes in the kernel. Should only be used with systems based on BSD 4.3 Tahoe or earlier which have installed a reject/blackhole pseudo interface. .TP \f3blackhole\f1 Specifies that the address of the interface which matches these criteria will be used as the local address when installing \f2reject\f1 routes in the kernel. Should only be used with systems based on BSD 4.3 Tahoe or earlier which have installed a reject/blackhole pseudo interface. .RE .TP \f3define\f1 \f2address\f1 Defines interfaces that might not be present when GateD is started so they may be referenced in the configuration file when \f4strictinterfaces\f1 is defined. Possible \f4define\f1 keywords are: .RS .TP \f3broadcast\f1 \f2address\f1 Defines the interface as broadcast capable (Ethernet or Token Ring) and specifies the broadcast address. .TP \f3pointopoint\f1 \f2address\f1 Defines the interface as a point-to-point interface (SLIP or PPP) and specifies the address on the local side. The first \f2address\f1 on the \f4define\f1 statement references the address of the host on the \f3remote\f1 end of the interface, the \f2address\f1 specified after this \f4pointopoint\f1 keyword defines the address on the \f3local\f1 side of the interface. .RE .IP An interface not defined as broadcast or point-to-point is assumed to be non-broadcast multiaccess (NBMA), such as an X.25 network. .RS .TP \f3netmask\f1 \f2mask\f1 Specifies the subnetmask to be used on this interface. This is ignored on pointtopoint interfaces. .TP \f3multicast\f1 Specifies that the interface is multicast capable. .RE .RE .SS Interface lists An interface list is a list of references to interfaces or groups of interfaces. There are four methods available for referring to interfaces. They are listed here from most general to most specific. .RS .TP \f3all\f1 This refers to all available interfaces. .TP Interface name wildcard This refers to all the interfaces of the same type. Unix interfaces consist of the name of the device driver, like \f4ie\f1, and a unit number, like \f40\f1, \f45\f1 or \f422\f1. Reference to the name contain only alphabetic characters and match any interfaces that have the same alphabetic part. .IP For example, \f4ie\f1 on a Sun would refer to all Interlan Ethernet interfaces, \f4le\f1 would refer to all Lance Ethernet interfaces. But \f4ie\f1 would not match \f4iel0\f1. .TP Interface name This refers to a specific interface, usually one physical interface. These are specified as an alphabetic part followed by a numeric part. This will match one specific interface. But be aware that on many systems, there can be more than one protocol (\f2IP\f1) address on a given physical interface. For example, \f4ef1\f1 will match an interface named \f4ef1\f1, but not an interface named \f4ef10\f1. .TP Interface address This matches one specific interface. The reference can be by protocol address (\f210.0.0.51\f1), or by symbolic hostname (\f2nic.ddn.mil\f1). Note that a symbolic hostname reference is only valid when it resolves to only one address. Use of symbolic hostnames is not recommended. .RE .P If many interface lists are present in the configuration file with more than one parameter, these parameters are collected at run-time to create the specific parameter list for a given interface. If the same parameter is specified on more than one list, the parameters with the most specific interface is used. .PP For example, consider a system with three interfaces, \f4le0\f1, \f4le1\f1 and \f4du0\f1. .RS .nf .P .ft 4 rip yes { interface all noripin noripout ; interface le ripin ; interface le1 ripout ; } ; .ft 1 .fi .RE RIP packets would only be accepted from interfaces \f4le0\f1 and \f4le1\f1, but not from \f4du0\f1. RIP packets would only be sent on interface \f4le1\f1. .SS IP Interface addresses and routes The \f2BSD 4.3\f1 and later networking implementations allow four types of interfaces. Some implementations allow multiple protocol addresses per physical interface, these are mostly based on \f2BSD 4.3 Reno\f1 or later. .RS .TP \f3loopback\f1 This interface must have the address of \f3127.0.0.1\f1. Packets sent to this interface are sent back to the originator. This interface is also used as a catch all interface for implementing other features, such as \f2reject\f1 and \f2blackhole\f1 routes. Although a netmask is reported on this interface, it is ignored. It is useful to assign an additional address to this interface that is the same as the OSPF or BGP \f2router id\f1; this allows routing to a system based on the \f2router id\f1 which will work if some interfaces are down. .TP \f3broadcast\f1 This is a multi-access interface capable of a physical level broadcast, such as \f2Ethernet\f1, \f2Token Ring\f1 and \f2FDDI\f1. This interface has an associated subnet mask and broadcast address. The interface route to an \f2broadcast\f1 network will be a route to the complete subnet. .TP \f3point-to-point\f1 This is a \f2tunnel\f1 to another host, usually on some sort of \f2serial\f1 link. This interface has a \f2local\f1 address, and a \f2remote\f1 address. Although it may be possible to specify multiple addresses for a \f2point-to-point\f1 interface, there does not seem to be a useful reason for doing so. .IP The \f2remote\f1 address must be unique among all the interface addresses on a given router. The \f2local\f1 address may be shared among many \f2point-to-point\f1 and up to one non-\f2point-to-point\f1 interface. This is technically a form of the \f2router id\f1 method for addressless links. This technique conserves subnets as none are required when using this technique. .IP If a subnet mask is specified on a \f2point-to-point\f1 interface, it is only used by RIP version 1 and HELLO to determine which subnets may be propagated to the router on the other side of this interface. .TP \f3non-broadcast multi-access\f1 or \f3nbma\f1 This type of interface is multi-access, but not capable of broadcast. And example would be \f2frame relay\f1 and \f2X.25\f1. This type of interface has a local address and a subnet mask. .RE .PP GateD insures that there is a route available to each IP interface that is configured and up. Normally this this done by the \f2ifconfig\f1 command that configures the interface; GateD does it to insure consistency. .PP For \f2point-to-point\f1 interfaces, gated installs some special routes. If the \f2local\f1 address on one or more \f2point-to-point\f1 interfaces is not shared with a non-\f2point-to-point\f1 interface, gated installs a route to the \f2local\f1 address pointing at the \f2loopback\f1 interface with a preference of 110. This insures that packets originating on this host destined for this \f2local\f1 address are handled locally. OSPF prefers to route packets for the \f2local\f1 interface across the \f2point-to-point\f1 link where they will be returned by the router on the remote end. This is used to verify operation of the link. Since OSPF installs routes with a preference of 10, these routes will override the route installed with a preference of 110. .PP If the \f2local\f1 address of one or more \f2point-to-point\f1 interfaces is shared with a non-\f2point-to-point\f1 interface, gated installs a route to the \f2local\f1 with a preference of 0 that will not be installed in the forwarding table. This is to prevent protocols like OSPF from routing packets to this address across a serial interface when this system could be functioning as a \f2host\f1. .PP When the status of an interface changes, GateD notifies all the protocols, which take the appropriate action. GateD assumes that interfaces which are not marked \f2UP\f1 do not exist. While this might not be the most correct action, it is the way things currently work. .PP GateD ignores any interfaces that have invalid data for the \f2local\f1, \f2remote\f1 or \f2broadcast\f1 addresses or the \f2subnet mask\f1. Invalid data includes zeros in any field. GateD will also ignore any \f2point-to-point\f1 interface that has the same local and remote addresses, it assumes it is in some sort of \f2loopback test\f1 mode. .\"/vol/src/devel/gated/master/gated/doc/config_guide/defines.html,v 1.2 1994/03/16 21:38:12 jch exp .SH Definition Statements Definition statements are general configuration statements that relate to all of GateD or at least to more than one protocol. The three definition statements are \f4autonomoussystem\f1, \f4routerid\f1 and \f4martians\f1. if used, \f4autonomoussystem\f1, \f4routerid\f1 and \f4martians\f1 must appear before any other type of configuration statement in gated.conf file. .SS Autonomous System configuration .RS 0 .nf .P \f3autonomoussystem\f1 \f2autonomous_system\f1 [ \f3loops\f1 \f2number\f1 ] \f3;\f1 .fi .RE .P Sets the autonomous system number of this router to be \f4autonomous system\f1. This option is required if BGP or EGP are in use. The AS number is assigned by the Network Information Center (NIC). .PP \f4Loops\f1 is only for protocols supporting AS paths, such as BGP. It controls the number of times this autonomous system may appear in an AS path and defaults to 1 (one). .SS Router ID configuration .RS 0 .nf .P \f3routerid\f1 \f2host\f1 \f3;\f1 .fi .RE .P Sets the router identifier for use by the BGP and OSPF protocols. The default is the address of the first interface encountered by GateD. The address of a non-point-to-point interface is preferred over the local address of a point-to-point interface and an address on a loopback interface that is not the loopback address (127.0.0.1) is most preferred. .SS Martian configuration .RS 0 .nf .P \f3martians\f1 \f3{\f1 \f3host\f1 \f2host\f1 [ \f3allow\f1 ] \f3;\f1 \f2network\f1 [ \f3allow\f1 ] \f3;\f1 \f2network\f1 \f3mask\f1 \f2mask\f1 [ \f3allow\f1 ] \f3;\f1 \f2network\f1 \f3masklen\f1 \f2number\f1 [ \f3allow\f1 ] \f3;\f1 \f3default\f1 [ \f3allow\f1 ] \f3;\f1 \f3}\f1 \f3;\f1 .ft 1 .fi .RE .P Defines a list of \f2martian\f1 addresses about which all routing information is ignored. Sometimes a misconfigured system sends out obviously invalid destination addresses. These invalid addresses, called martians, are rejected by the routing software. This command allows additions to the list of martian addresses. See the section on Route Filtering for more information on specifying ranges. Also, the \f4allow\f1 parameter may be specified to explicitly allow a subset of a range that was disallowed. .SS Sample Definition Statements .RS 0 .nf .P .ft 4 options gendefault ; autonomoussystem 249 ; interface 128.66.12.2 passive ; martians { 0.0.0.26 }; .ft 1 .fi .RE .PP The statements in the sample perform the following functions: .PP .RS .TP 3 \(bu The options statement tells the system to generate a default route when it peers with an EGP or BGP neighbor. .TP 3 \(bu The autonomoussystem statement tells GateD to use AS number 249 for in EGP and BGP. .TP 3 \(bu The interface statement tells GateD not to mark interface 128.66.12.2 as down even if it sees no traffic. .TP 3 \(bu The martians statement prevents routes to 0.0.0.26 from ever being accepted. .RE .SH Protocol Overview Routing protocols determine the "best" route to each destination and distribute routing information among the systems on a network. Routing protocols are divided into two general groups: interior and exterior protocols. GateD software combines management of the interior and exterior routing protocols in one software daemon. .SS Interior Routing Protocols Interior protocols are used to exchange reachability information within an autonomous system (AS). They are referred to as a class by the acronym \f3igp\f1. There are several interior protocols: .RS 0 .TP 5 \f3RIP\f1 The Routing Information Protocol, Version 1 and Version 2, is the most commonly used interior protocol. RIP selects the route with the lowest metric as the best route. The metric is a hop count representing the number of gateways through which data must pass to reach its destination. The longest path that RIP accepts is 15 hops. If the metric is greater than 15, a destination is considered unreachable and GateD discards the route. RIP assumes the best route is the one that uses the fewest gateways which is the shortest path, not taking into account congestion or delay on route. .IP The RIP version 1 protocol is described in RFC 1058 and the RIP version 2 protocol is described in RFC 1388. .TP \f3HELLO\f1 HELLO , another interior protocol, uses delay as the deciding factor in choosing the best route. Round-trip time is the length of time it takes a datagram to travel from the source and destination. HELLO is historically significant for the Internet as it was the protocol used among the original prototype NSFNET backbone \f2fuzzball\f1 gateways. Today, like fuzzballs, HELLO is a little-used protocol. .IP An earlier version of the HELLO protocol is described in RFC 891. .TP \f3OSPF\f1 Open Shortest Path First is a link-state protocol. OSPF is better suited than RIP for complex networks with many routers. OSPF provides equal cost multipath routing. .IP OSPF is described in RFC 1583, the MIB is defined in RFC 1253. Other related documents are RFC 1245, RFC 1246 and RFC 1370. .\"